@advcomm/uids-io-auth

Production-ready authentication for Node.js backends: OAuth 2.0/OIDC, sessions, refresh tokens, SDK-registered device tracking, and an optional Express adapter.

The package is not Express-only — services (AuthService, TokenService, etc.) are framework-agnostic. Use createAuthRouter when you want a ready-made HTTP surface on Express.

Installation

npm install @advcomm/uids-io-auth pg express

Dependency	Role
pg	Required — PostgreSQL access
express	Optional peer — only needed for createAuthRouter / requireAuth

Subpath export (if you split Express-only imports):

import { createAuthRouter } from '@advcomm/uids-io-auth/express';

Environment variables

Use these in your auth server (see examples/express-auth-server/.env.example):

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
ISSUER	Yes	Public auth issuer URL (e.g. https://auth.example.com)
API_AUDIENCE	Yes	Resource server audience for access tokens
CSRF_SECRET	Yes (prod)	Secret for signing CSRF/session cookies — must be set explicitly in production (no fallback)
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	If using Google	OAuth client credentials
MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET	If using Microsoft	Entra app credentials
MICROSOFT_TENANT	No	Default common
LOG_LEVEL	No	Pino level: debug, info, warn, error (default: debug in dev, info in production)

Register OAuth clients for each portal with OAuthClientService.upsertPublicClient (see Portal OAuth clients). The example auth server uses a local seed helper, not a package export.

Database migrations

Migrations are not run automatically. Call explicitly on startup:

import { Pool } from 'pg';
import { runAuthMigrations } from '@advcomm/uids-io-auth';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
await runAuthMigrations(pool);

Auth server (auth.example.com)

import express from 'express';
import { Pool } from 'pg';
import {
  createAuthKit,
  createAuthRouter,
  OAuthClientService,
  runAuthMigrations,
} from '@advcomm/uids-io-auth';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
await runAuthMigrations(pool);

// Register one public OAuth client per portal (PKCE). Repeat per app.
const oauthClients = new OAuthClientService(pool);
await oauthClients.upsertPublicClient({
  id: 'merchant_portal_web',
  name: 'Merchant Portal Web',
  redirectUris: ['https://merchant.example.com/auth/callback'],
});

const authKit = await createAuthKit({
  issuer: process.env.ISSUER!,
  apiAudience: process.env.API_AUDIENCE!,
  pg: pool,
  cookie: {
    name: 'uids_auth_session',
    domain: '.example.com',
    secure: true,
    sameSite: 'lax',
  },
  csrf: { secret: process.env.CSRF_SECRET! },
  providers: {
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
      callbackUrl: `${process.env.ISSUER}/oauth/google/callback`,
    },
    microsoft: {
      clientId: process.env.MICROSOFT_CLIENT_ID!,
      clientSecret: process.env.MICROSOFT_CLIENT_SECRET!,
      tenant: process.env.MICROSOFT_TENANT ?? 'common',
      callbackUrl: `${process.env.ISSUER}/oauth/microsoft/callback`,
    },
  },
  email: {
    sendMagicLink: async (email, url) => {
      // integrate with your email provider
    },
  },
});

const app = express();
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use('/', createAuthRouter(authKit));
app.listen(3000);

createAuthRouter mounts:

• OIDC — /.well-known/openid-configuration, /.well-known/jwks.json, /login
• OAuth — /authorize, /token, provider callbacks, /logout
• Email — magic link and password login routes
• Sessions — session cookie introspection and revoke
• Devices — register, list, revoke (CSRF-protected where required)
• Middleware — CORS, CSRF on state-changing routes, Zod validation, centralized error handling

See examples/express-auth-server.

API docs (Bruno): Import OpenCollection bruno/uids-auth-api into your Bruno workspace alongside backend service collections — see bruno/README.md.

API server (api.example.com)

import express from 'express';
import { requireAuth } from '@advcomm/uids-io-auth';

const app = express();
app.use(express.json());

app.use(requireAuth({
  issuer: process.env.ISSUER!,
  audience: process.env.API_AUDIENCE!,
  jwksUrl: `${process.env.ISSUER}/.well-known/jwks.json`,
}));

app.get('/me', (req, res) => {
  res.json({ auth: req.auth });
});

Configure CORS on the API to allow your portal origins. This package does not set API CORS headers.

See examples/express-api-server.

Errors and logging

The Express adapter uses two response shapes so OAuth clients and REST portals both get usable errors.

Validation errors (Zod, HTTP 422)

Routes validated with the built-in middleware return all field issues:

{
  "success": false,
  "message": "Validation failed",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      { "field": "client_id", "message": "Required" },
      { "field": "platform", "message": "Invalid enum value..." }
    ]
  }
}

Use ValidationError, isValidationError, and ValidationDetail from the package if you handle errors in custom middleware.

OAuth / auth errors (HTTP 4xx)

Business and OAuth-style failures use the familiar shape:

{
  "error": "invalid_request",
  "error_description": "Invalid refresh token"
}

Other exported errors: UnauthorizedError, ForbiddenError, ConflictError, RateLimitError, InvalidRequestError, and base AuthError.

Server errors (HTTP 500)

Unexpected errors return a generic body (no stack or internal details). Full error context is logged server-side only.

Structured logs (Pino)

The router logs via Pino to stdout:

Situation	Level	What is logged
Request validation failed	warn	scope, field names, issue count (not request body values)
Expected auth errors	info	error code, status, method, path
Unexpected errors	error	error name/message, method, path

Set LOG_LEVEL=debug locally. In production, logs are JSON (no pretty-print).

Tracing: pass X-Request-Id from your gateway or API; it is included in log context when present.

Google Cloud OAuth setup

1. Create an OAuth 2.0 Client ID (Web application) in Google Cloud Console.
2. Authorized redirect URI: https://auth.example.com/oauth/google/callback
3. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET in your auth server environment.

Microsoft Entra setup

1. Register an application in Microsoft Entra ID.
2. Add redirect URI: https://auth.example.com/oauth/microsoft/callback
3. Create a client secret.
4. Set MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, and configure tenant (common, organizations, consumers, or a tenant ID).

Portal OAuth clients

Each portal is a public OAuth client (PKCE, no client secret in the browser):

import { OAuthClientService } from '@advcomm/uids-io-auth';

const oauthClients = new OAuthClientService(pool);
await oauthClients.upsertPublicClient({
  id: 'your_portal_web',
  name: 'Your Portal Web',
  redirectUris: ['https://your-portal.example.com/auth/callback'],
  // origins optional — derived from redirect URIs when omitted
});

For local dev with multiple UIDs portals, see examples/express-auth-server/seedPortalClients.ts (merchant_portal_web, agency_portal_web, etc.). That helper is not exported from the package.

Login flow (PKCE)

1. Portal generates PKCE verifier/challenge and optional SDK device_id.
2. Portal redirects user to GET /authorize?response_type=code&client_id=...&redirect_uri=...&scope=openid profile email&state=...&code_challenge=...&code_challenge_method=S256
3. User authenticates on auth domain (Google, Microsoft, or email).
4. Auth domain redirects to portal redirect_uri?code=...&state=...
5. Portal calls POST /token with grant_type=authorization_code, code, code_verifier, client_id, redirect_uri.
6. Portal receives access_token, refresh_token, and optional id_token.
7. Portal calls API with Authorization: Bearer {access_token}.

Device identity

Companion client SDKs (React, Flutter, native) generate a stable UUID device_id, register it via POST /devices/register, and send X-Uids-Device-Id on auth flows. The auth server binds devices to users and includes device_id in access token claims.

Supported platforms: web, ios, android, desktop, unknown (validated on register).

See docs/sdk-contract.md for the full client/server contract.

Recommended companion SDKs (future packages)

Platform	Package	Storage
React / Next.js	@uids-io/auth-react	localStorage / IndexedDB
Flutter web + mobile	@uids-io/auth-flutter	shared_preferences / Keychain
iOS / Android native	@uids-io/auth-native	Keychain / EncryptedSharedPreferences
Desktop	@uids-io/auth-react or native wrapper	OS keychain

Exports

Kit & HTTP

• createAuthKit, createAuthRouter, requireAuth
• runAuthMigrations
• verifyAccessToken, generatePkcePair, verifyCodeChallenge

Services (use directly without Express)

• AuthService, UserService, TokenService, SessionService, DeviceService, OAuthClientService

Errors

• AuthError, InvalidRequestError, ValidationError, UnauthorizedError, ForbiddenError, ConflictError, RateLimitError
• isAuthError, isValidationError, ValidationDetail

Types & helpers

• AuthUser, AuthContext, Device, DevicePlatform, TokenResponse, provider mappers, etc.

Testing

npm test              # all tests
npm run test:unit     # crypto, redirect_uri, provider mapping
npm run test:integration  # DB + Express flows (uses pg-mem by default)
npm run typecheck
npm run build

Integration tests use pg-mem by default (no Docker required). Optional backends:

• TEST_DATABASE_URL=postgres://... — run against an existing PostgreSQL instance
• USE_TESTCONTAINERS=1 — use Docker testcontainers when available

Releases

Releases on main use semantic-release — see RELEASING.md. Use Conventional Commits (feat:, fix:, etc.) so version bumps and npm publish happen automatically.

License

MIT