Auth

The output of authentication is an Actor. Nothing downstream authorizes on a session row, a user row or an api key: HTTP, actions, jobs and MCP all read ctx.actor and hand it to the one policy system (Policies and authz). Package @ultimat3/auth (tier 2) — the full reference is packages/auth/README.md; the walk-through is Tutorial 3.

import { defineAuth, login, oauthLogin, postgresAuthAdapter } from '@ultimat3/auth';

export const auth = defineAuth({
  adapter: postgresAuthAdapter(),            // or memoryAuthAdapter()
  session: { absoluteTtlMs: 30 * 864e5, idleTtlMs: 7 * 864e5 },
  password: { minLength: 12 },
  mfa: { issuer: 'Acme' },
  providers: ['github', 'google'],         // required to serve any OAuth route — the default is []
});

const { actor, token, cookie } = await login(auth, { email, password, ip });
const { start, callback } = oauthLogin(auth);   // /auth/sso/:provider and its callback

The tables (x_users, x_sessions, x_accounts, x_verifications, x_api_keys, and the passkeys' x_passkeys, x_passkey_challenges, x_passkey_evidence) are created by every boot; an app writes no migration for them.

Signing in by handle (As of 2026-10): an app whose users are @ada names the lookup once — defineAuth({ adapter, handles: async (handle) => (await db.users.where({ handle }).one())?.id ?? null }) — and calls login(auth, { handle, password }). The handle arrives trimmed and lowercased (normaliseHandle), its failures count against a bucket of its own, and an unknown handle is the same X_UNAUTHENTICATED after the same hash as a wrong password. The app's users row and the auth user share one id: register(auth, { id, email, password }) creates the auth user under it. A handle login on an app that declared no handles is X_CONFIG_INVALID. The deployed demo (dummy/social-media-clone/apps/web/app/auth/) signs in this way.

Sessions

Signing out is logout(auth, token) for the row plus signOutHeaders() on the response: it expires the session cookie and sends Clear-Site-Data: "cache", "storage" (SIGN_OUT_CLEAR_SITE_DATA), so the browser drops the previous principal's IndexedDB, storage, service worker and cached pages. Revocation at scale is revokeUserSessions, revokeOrgSessions, revokeSessionsCreatedBefore (after rotating a secret) and disableUser, which also revokes the user's live API keys. A passwordHash change through updatePrivileges ends every other session of that user — all of them when no session of theirs is passed, as in a reset.

A sign-in page is one command, As of 2026-11: x g sign-in --password (a native form over login(), its second leg over completeMfa()) or x g sign-in --oidc <provider> (an OpenID Connect issuer, discovered on the first sign-in). Both write the sign-in page, the destroySession action, auth.signInPath, and a boot guard: outside development and test a web or sync role with its sign-in keys unset refuses to start (X_AUTH_SIGN_IN_UNCONFIGURED). --password also writes createSession / confirmSession and the second-factor page; --oidc writes the start and callback routes and drops x new's development viewer while its files are still x new's own. What each writes: CLI reference.

OAuth

github and google ship; registerOAuthProvider adds one. PKCE is mandatory on every provider — usesPkce: false does not typecheck — and the handshake is a signed __Host- cookie bound to its provider. An id token is verified against the provider's JWKS. An identity links to an existing account only when both the provider and that account have verified the address (link: 'verified-email', the default); 'never' is the only alternative. Credentials are <PROVIDER>_CLIENT_ID / <PROVIDER>_CLIENT_SECRET.

SSO: OIDC and SAML behind one IdentityProvider port

Rule: every federated sign-in is an IdentityProvider (@ultimat3/auth), and signInWithIdentity(auth, identity) is the one path from it to a session — the same account-link, MFA and grant rules as OAuth. As of 2026-11-09.

identityProviderRoutes(auth, { providers }) mounts both kinds:

import type { Auth } from '@ultimat3/auth';
import {
  identityProviderRoutes,
  oidcIdentityProvider,
  parseSamlMetadata,
  samlIdentityProvider,
} from '@ultimat3/auth';

declare const auth: Auth;
declare const corpMetadataXml: string; // the IdP's metadata document, read at boot

export const sso = identityProviderRoutes(auth, {
  providers: [
    samlIdentityProvider({
      id: 'corp',
      idp: parseSamlMetadata(corpMetadataXml),
      spEntityId: 'https://app.example/saml/metadata',
      trustEmail: true,
      emailDomains: ['corp.example'], // the exact domains this IdP owns
    }),
    oidcIdentityProvider({ provider: 'github' }),
  ],
  successPath: '/app',
});

defineAuth({ providers }) lists both ids; an unknown or not-enabled id is X_IDENTITY_PROVIDER_UNKNOWN (404).

OIDC replay. oidcIdentityProvider claims the handshake's state once in the shared replay store before it spends the code, keyed on when the handshake was issued: a callback lifted from a browser is X_OAUTH_STATE_INVALID even inside the cookie's lifetime, and so is any answer more than 10 minutes after begin (DEFAULT_HANDSHAKE_TTL_MS).

Mount each leg with its meta verbatim — { method: leg.method, path: leg.path, handler: (request) => leg.handle(request.raw), meta: leg.meta }. The ACS (POST) declares csrf: 'cookieless' and authenticate: () => null: the IdP answers with an auto-submitted cross-site form, which the csrf stage refuses on any other route (403 X_CSRF_BLOCKED). CSRF is held there by the protocol instead — the answer must carry this browser's RelayState, checked against the HMAC-sealed state cookie, and its assertion must answer this request's ID.

SAML scope. SP-initiated only: an AuthnRequest over HTTP-Redirect with RelayState, the response over HTTP-POST. Signed assertions are required; encrypted assertions, SHA-1 and RSA under 2,048 bits are refused; trustEmail is required, because SAML has no email_verified, and trustEmail: true requires emailDomains — an IdP's admin can assert any address, so only an address in a listed domain (exact; list each subdomain) is verified, and one outside it can neither link to an existing account nor create one (trustEmail: true with no domains is a type error and X_CONFIG_INVALID at construction); clock skew is ±60 s (skewMs). parseSamlMetadata(xml) → { entityId, ssoUrl, certificates }, refused as X_SAML_METADATA_INVALID with no HTTP-Redirect SSO, no signing certificate, or an RSA key under 2,048 bits. Verification is in-package, no dependency (build vs wrap). Every refusal is X_SAML_RESPONSE_INVALID with meta.check:

Passkeys

WebAuthn, verified by hand on WebCrypto — no dependency (As of 2026-11). Two uses, one declaration: defineAuth({ passkeys: { rpId, origins } }). ES256 and RS256; CBOR, COSE and DER are parsed in this package, every malformed byte a refusal.

import { canonicalJson } from '@ultimat3/core';
import {
  defineAuth,
  memoryAuthAdapter,
  passkeyLogin,
  passkeyStepUp,
  sha256Hex,
  verifyPasskeyEvidence,
} from '@ultimat3/auth';

const auth = defineAuth({
  adapter: memoryAuthAdapter(),
  passkeys: { rpId: 'example.com', origins: ['https://example.com'] },
});

// Sign-in: register onto a signed-in account, then usernameless sign-in to the same session login() mints.
const { registerOptions, register, loginOptions, login } = passkeyLogin(auth);

// Step-up: the proof is bound to bytes the SERVER derives from the input, and stored as evidence.
const stepUp = passkeyStepUp<{ readonly to: string; readonly minor: number }>(auth, {
  ttlMs: 60_000,
  digest: ({ input }) => sha256Hex(canonicalJson(input)),
});

declare const userId: string;
declare const response: unknown;
const evidence = await stepUp.verify({ userId, input: { to: 'acct-7', minor: 12_500 }, response });
// Later, in another process, with the row alone:
const approved = await verifyPasskeyEvidence(evidence, { rpId: 'example.com', origins: ['https://example.com'] });

MFA, verification, API keys, workloads

Authorization server

As of 2026-11. authorizationServer({ issuer, store, consentPath, lifetimes, scopes, registration?, grants?, resources? }) is one OAuth 2.1 server for an app's MCP endpoint, public API, CLI and partners alike. It ships the RFC rules; the consent page, who may be a client and what a subject becomes are the app's.

import type { Actor, PgExecutor } from '@ultimat3/core';
import { authorizationServer, oauthBearerResolver, postgresAuthServerStore } from '@ultimat3/auth';

declare const executor: PgExecutor;
declare function actorFor(subject: string): Promise<Actor | null>;

export const oauth = authorizationServer({
  issuer: 'https://www.example.com',
  store: postgresAuthServerStore({ executor }),
  consentPath: '/oauth/consent',               // the app's page; the advertised authorization_endpoint
  lifetimes: { accessSeconds: 600, refreshIdleDays: 30, clientSeconds: 900 },
  scopes: ['cases:read', 'cases:write'],
  grants: ['authorization_code', 'refresh_token', 'client_credentials'],
});
export const runtime = { routes: [...oauth.routes] };           // apps/web/runtime.ts
const resolveToken = oauthBearerResolver(oauth, { actor: (grant) => actorFor(grant.subject) });

Bad configuration is X_AUTH_SERVER_INVALID naming the field; a grant not in grants answers unsupported_grant_type and is logged X_AUTH_GRANT_DISABLED. The five tables (x_oauth_*) are applied by the boot. For one MCP endpoint, mcpAuthorizationServer (MCP and AI).

Every auth code — X_UNAUTHENTICATED, X_SESSION_EXPIRED, X_MFA_REQUIRED, X_OAUTH_*, X_ACCOUNT_LOCKED, X_API_KEY_INVALID and the rest — is in Error codes.