@ultimat3/auth 1.2.0 → 2.0.0

package/src/oauth-login.ts

@@ -3,14 +3,18 @@
 // matter which door the user came through. `completeOAuthLogin` is the blessed entry point;
 // the three steps under it are exported because a custom flow needs the seams, not a second path.
 
-import { ConfigInvalidError, uuid } from '@ultimat3/core';
+import { ConfigInvalidError, logger, uuid } from '@ultimat3/core';
 import type { AuthAccount, AuthUser } from './adapter';
 import type { Auth, LoginResult } from './auth';
+import { normaliseEmail } from './email';
 import {
+  authWriteFailed,
   emailVerifiedNotStored,
   mfaRequired,
   oauthAccountNotLinked,
   oauthExchangeFailed,
+  oauthLinkingDisabled,
+  restartAt,
 } from './errors';
 import type { OAuthCallback, OAuthHandshake } from './oauth';
 import {
@@ -25,14 +29,43 @@ import { resolveActor } from './policy-bridge';
 import { loginFailed } from './rate-limit';
 import { createSession, sessionCookie } from './session';
 
+/**
+ * What the IdP's answer entitles this identity to, in the app's own vocabulary. Which group maps
+ * to which role is business convention and never ships (axiom 8) — this is the seam it arrives
+ * through, and every field is independently optional so a seam that only knows the org says only
+ * that.
+ */
+export interface OAuthGrants {
+  readonly orgId?: string | null | undefined;
+  readonly roles?: readonly string[] | undefined;
+  readonly scopes?: readonly string[] | undefined;
+  /**
+   * The IdP's own stable id for this person, if the app has one. Deliberately NOT derived from
+   * `profile.providerAccountId`: `x_users.external_id` is unique across the table, and two
+   * different OPs are free to issue the same `sub`, so auto-filling it would make one tenant's
+   * google login collide with another's okta login. The app knows which id its provisioning
+   * system uses; the framework does not.
+   */
+  readonly externalId?: string | null | undefined;
+}
+
+/** Called once per callback, after the profile is proven and before the session is minted. */
+export type ResolveOAuthGrants = (profile: OAuthProfile) => Promise<OAuthGrants> | OAuthGrants;
+
 export interface OAuthSignInInput {
   readonly profile: OAuthProfile;
   readonly tokens: OAuthTokens;
   readonly ip?: string | null | undefined;
   readonly userAgent?: string | null | undefined;
-  /** Granted to a user this flow creates. An existing user's roles are never rewritten here. */
-  readonly roles?: readonly string[] | undefined;
-  readonly orgId?: string | null | undefined;
+  /**
+   * Authoritative on EVERY login, not only the first. The IdP is the source of truth for who is
+   * in which group, so a member removed from a group there has to lose the role here on their
+   * next sign-in — an apply-once-at-creation rule made "revoke in the IdP" a no-op, and left the
+   * first-time user with `roles: []`, `orgId: null` and an actor every `can()` denies.
+   *
+   * Absent means "the app has no opinion": the stored row is left exactly as it is.
+   */
+  readonly grants?: OAuthGrants | undefined;
 }
 
 async function userForAccount(auth: Auth, account: AuthAccount): Promise<AuthUser> {
@@ -41,8 +74,48 @@ async function userForAccount(auth: Auth, account: AuthAccount): Promise<AuthUse
   return user;
 }
 
+/**
+ * The grant seam applied to a row that already exists. Only the fields the seam actually returned
+ * are written, and only when they differ — an unconditional `updateUser` would make every SSO
+ * login a write, which is the same mistake `verifySession` used to make on every request.
+ */
+async function applyGrants(auth: Auth, user: AuthUser, grants: OAuthGrants): Promise<AuthUser> {
+  const same = (a: readonly string[] | undefined, b: readonly string[]): boolean =>
+    a === undefined || (a.length === b.length && a.every((one, index) => one === b[index]));
+  const unchanged = (declared: string | null | undefined, stored: string | null): boolean =>
+    declared === undefined || (declared ?? null) === stored;
+  if (
+    unchanged(grants.orgId, user.orgId) &&
+    unchanged(grants.externalId, user.externalId) &&
+    same(grants.roles, user.roles) &&
+    same(grants.scopes, user.scopes)
+  ) {
+    return user;
+  }
+  const patched = await auth.adapter.updateUser(user.id, {
+    ...(grants.orgId === undefined ? {} : { orgId: grants.orgId ?? null }),
+    ...(grants.roles === undefined ? {} : { roles: grants.roles }),
+    ...(grants.scopes === undefined ? {} : { scopes: grants.scopes }),
+    ...(grants.externalId === undefined ? {} : { externalId: grants.externalId ?? null }),
+  });
+  // Failing closed rather than signing in with the stale row: the whole point of the seam is that
+  // the session about to be minted carries what the IdP says today.
+  if (patched === null) throw authWriteFailed('updateUser', 'x_users');
+  return patched;
+}
+
+/**
+ * The provider's address, put through the one normalisation every other door uses. Providers send
+ * display casing (`Ada@Example.com`) and change it between logins, and `x_users.email` is a plain
+ * case-sensitive `unique` column — so unnormalised, the lookup below missed the account the user
+ * registered and `createUserFor` minted a second one at the same address, which `login()` could
+ * then never reach. `MemoryAdapter` used to fold case itself, which is why no test saw it.
+ */
+const profileEmail = (profile: OAuthProfile): string | null =>
+  profile.email === null ? null : normaliseEmail(profile.email);
+
 async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthUser> {
-  const email = input.profile.email;
+  const email = profileEmail(input.profile);
   // The provider authenticated somebody and told us no address. There is nothing to create an
   // account from, and saying "wrong password" here would send the developer hunting the wrong bug.
   if (email === null) {
@@ -50,7 +123,17 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
       provider: input.profile.provider,
       stage: 'userinfo',
       detail: 'the provider returned an identity with no email address',
-      fix: `request the email scope for ${input.profile.provider} in beginOAuth(), then restart the flow`,
+      fix: `request the email scope for ${input.profile.provider} in beginOAuth(), then ${restartAt(input.profile.provider)}`,
+    });
+  }
+  const grants = input.grants ?? {};
+  if ((grants.roles ?? []).length === 0 && (grants.orgId ?? null) === null) {
+    // Not an error — an app may genuinely want a roleless account until somebody approves it —
+    // but silent is how "SSO works and the user can do nothing" survives to production. Every
+    // `can()` denies a roleless actor, and a tenant-scoped read throws before the query is built.
+    logger.warn('auth.oauth.user_created_without_grants', {
+      provider: input.profile.provider,
+      seam: 'oauthLogin(auth, { resolveGrants })',
     });
   }
   const created = await auth.adapter.createUser({
@@ -59,8 +142,10 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
     // An OAuth-only account has no password to store, and must never be given a random one:
     // a hash nobody knows the input to is still a credential a reset flow could hand over.
     passwordHash: null,
-    orgId: input.orgId ?? null,
-    roles: input.roles ?? [],
+    orgId: grants.orgId ?? null,
+    roles: grants.roles ?? [],
+    scopes: grants.scopes ?? [],
+    externalId: grants.externalId ?? null,
     createdAt: auth.clock.now(),
   });
   if (!input.profile.emailVerified) return created;
@@ -79,13 +164,17 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
  * An address alone is not proof of ownership on either side. Attaching a provider identity to a
  * local account that never verified its own email hands the login to whoever registered that
  * address first, so both halves must have proven it before they are treated as one person.
+ *
+ * `auth.link` is the app's one say in that. `'never'` skips the address step entirely and refuses
+ * a collision; `'verified-email'` — the default — is the both-halves-proven rule below.
  */
 async function resolveUser(
   auth: Auth,
   input: OAuthSignInInput,
   linked: AuthAccount | null,
 ): Promise<AuthUser> {
-  const { provider, email, emailVerified } = input.profile;
+  const { provider, emailVerified } = input.profile;
+  const email = profileEmail(input.profile);
   if (linked !== null) return await userForAccount(auth, linked);
 
   if (email === null) return await createUserFor(auth, input);
@@ -94,6 +183,12 @@ async function resolveUser(
   if (existing.disabledAt !== null) throw loginFailed();
   // The provider did not vouch for the address, so nothing here proves the two are one person.
   if (!emailVerified) throw loginFailed();
+  // Only past that line is the caller known to own the address, which is what makes naming the
+  // collision safe. Refusing `'never'` any earlier answered an UNVERIFIED provider address with a
+  // distinct code and a `meta.email` where `'verified-email'` answers `loginFailed()` — so the
+  // strict policy confirmed an account exists at an address its caller never proved. `disabledAt`
+  // above is generic and reveals nothing, which is why it can be asked first.
+  if (auth.link === 'never') throw oauthLinkingDisabled(provider, email);
   // It did vouch, and the local account never did: say so, because this caller owns the address.
   if (existing.emailVerifiedAt === null) throw oauthAccountNotLinked(provider, email);
   return existing;
@@ -127,7 +222,9 @@ export async function signInWithOAuth(auth: Auth, input: OAuthSignInInput): Prom
   }
 
   const linked = await auth.adapter.findAccount(provider, input.profile.providerAccountId);
-  const user = await resolveUser(auth, input, linked);
+  const resolved = await resolveUser(auth, input, linked);
+  const user =
+    input.grants === undefined ? resolved : await applyGrants(auth, resolved, input.grants);
   // Linked before the MFA gate on purpose: the second factor is finished on another request,
   // and that request must find the identity already attached. A re-link refreshes the tokens
   // and keeps the row's own identity — the provider account never changes hands.
@@ -162,8 +259,8 @@ export interface CompleteOAuthLoginInput {
   readonly timeoutMs?: number | undefined;
   readonly ip?: string | null | undefined;
   readonly userAgent?: string | null | undefined;
-  readonly roles?: readonly string[] | undefined;
-  readonly orgId?: string | null | undefined;
+  /** The app's grant seam. Called once, after the profile is proven. */
+  readonly resolveGrants?: ResolveOAuthGrants | undefined;
 }
 
 /** Callback → session, in one call: exchange, identify, sign in. */
@@ -182,12 +279,12 @@ export async function completeOAuthLogin(
     fetch: input.fetch,
     timeoutMs: input.timeoutMs,
   });
+  const grants = input.resolveGrants === undefined ? undefined : await input.resolveGrants(profile);
   return await signInWithOAuth(auth, {
     profile,
     tokens,
     ip: input.ip,
     userAgent: input.userAgent,
-    roles: input.roles,
-    orgId: input.orgId,
+    ...(grants === undefined ? {} : { grants }),
   });
 }

package/src/oauth-paths.ts

@@ -0,0 +1,20 @@
+// Single responsibility: the one declaration of where the OAuth login routes live. It imports
+// nothing so that `errors.ts` and `oauth-route.ts` can both read it without a cycle — which is
+// the point: three shipped `fix:` lines told the caller to restart at `GET /auth/oauth/<provider>`
+// while no route was mounted anywhere. Deriving both the mount and the fix from here makes a fix
+// line that names a route nothing serves impossible rather than merely discouraged.
+
+/** Not configurable, on purpose: a movable base path is a `fix:` line that can go stale again. */
+export const OAUTH_BASE_PATH = '/auth/oauth';
+
+/** The pattern a router mounts. `:provider` is the segment `oauthStartPath` fills in. */
+export const OAUTH_START_ROUTE_PATH = `${OAUTH_BASE_PATH}/:provider` as const;
+
+export const OAUTH_CALLBACK_ROUTE_PATH = `${OAUTH_BASE_PATH}/:provider/callback` as const;
+
+/** Where a browser starts a login. This exact string is what the `fix:` lines quote. */
+export const oauthStartPath = (provider: string): string => `${OAUTH_BASE_PATH}/${provider}`;
+
+/** Where the provider sends it back. Registered with the provider as the `redirect_uri`. */
+export const oauthCallbackPath = (provider: string): string =>
+  `${OAUTH_BASE_PATH}/${provider}/callback`;

package/src/oauth-profile.ts

@@ -4,15 +4,17 @@
 // decides whether this login may attach itself to an existing account by address.
 
 import { logger } from '@ultimat3/core';
-import { oauthExchangeFailed } from './errors';
+import { oauthExchangeFailed, restartAt } from './errors';
 import { idTokenEmailVerified, isVerifiedFlag } from './id-token';
-import { OAUTH_PROVIDERS, type OAuthProviderId } from './oauth';
+import { isRecord } from './json';
+import type { OAuthProviderId } from './oauth';
 import {
   OAUTH_USER_AGENT,
   type OAuthFetch,
   type OAuthTokens,
   providerDetail,
 } from './oauth-exchange';
+import { providerFor } from './oauth-registry';
 
 const DEFAULT_TIMEOUT_MS = 10_000;
 
@@ -37,9 +39,6 @@ interface GithubEmail {
   readonly verified: boolean;
 }
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value);
-
 const stringOrNull = (value: unknown): string | null =>
   typeof value === 'string' && value !== '' ? value : null;
 
@@ -108,14 +107,14 @@ async function fromUserInfo(
   tokens: OAuthTokens,
   options: OAuthProfileOptions,
 ): Promise<OAuthProfile> {
-  const config = OAUTH_PROVIDERS[provider];
+  const config = providerFor(provider);
   const url = config.userInfoUrl;
   if (url === null) {
     throw oauthExchangeFailed({
       provider,
       stage: 'userinfo',
       detail: `${provider} publishes no userinfo endpoint and its id token carried no identity`,
-      fix: `request the "email" scope for ${provider} in beginOAuth(), then restart the flow`,
+      fix: `request the "email" scope for ${provider} in beginOAuth(), then ${restartAt(provider)}`,
     });
   }
 
@@ -126,7 +125,7 @@ async function fromUserInfo(
       stage: 'userinfo',
       detail: result.detail,
       status: result.status,
-      fix: `confirm the ${provider} app still grants ${config.scopes.join(' ')}, then restart the flow`,
+      fix: `confirm the ${provider} app still grants ${config.scopes.join(' ')}, then ${restartAt(provider)}`,
     });
   }
   if (!isRecord(result.body)) {
@@ -148,7 +147,7 @@ async function fromUserInfo(
       provider,
       stage: 'userinfo',
       detail: 'the profile carried no stable account id',
-      fix: `confirm the ${provider} app requests ${config.scopes.join(' ')} and restart the flow`,
+      fix: `confirm the ${provider} app requests ${config.scopes.join(' ')}, then ${restartAt(provider)}`,
     });
   }
 
@@ -186,7 +185,7 @@ export async function oauthProfile(
   if (claims === null) return await fromUserInfo(provider, tokens, options);
 
   const email = stringOrNull(claims.email);
-  const userInfoUrl = OAUTH_PROVIDERS[provider].userInfoUrl;
+  const userInfoUrl = providerFor(provider).userInfoUrl;
   if (email === null && userInfoUrl !== null) {
     const profile = await fromUserInfo(provider, tokens, options);
     // Two surfaces, one identity — or this is not that identity. Overwriting the subject and

package/src/oauth-registry.ts

@@ -0,0 +1,65 @@
+// Single responsibility: which OAuth providers this process knows about. A closed union of three
+// consumer IdPs made an enterprise OP — Okta, Entra, Ping, an in-house OP — *unrepresentable*: the
+// constraint was a type, so there was no runtime escape and the only ways out were forking the
+// package or bypassing the whole subsystem, losing PKCE, the sealed handshake, issuer pinning and
+// account linking with it. The three built-ins register through the same call an app uses, so the
+// opening does not create a second path.
+
+import { oauthProviderDuplicate, oauthProviderUnknown } from './errors';
+import type { OAuthProvider } from './oauth';
+import { BUILTIN_OAUTH_PROVIDERS } from './oauth-builtins';
+
+const registry = new Map<string, OAuthProvider>();
+
+/**
+ * Frozen on the way in, arrays included: a registered provider is read on every login of its
+ * kind, and a caller that kept a reference to the object it passed could otherwise repoint
+ * `tokenUrl` or widen `issuers` after boot.
+ */
+const seal = (provider: OAuthProvider): OAuthProvider =>
+  Object.freeze({
+    ...provider,
+    issuers: Object.freeze([...provider.issuers]),
+    scopes: Object.freeze([...provider.scopes]),
+  });
+
+/**
+ * Add an IdP. The one extension point, and the same one `oauth-builtins.ts` goes through.
+ *
+ * `usesPkce` stays the literal `true` on `OAuthProvider`, so this opening cannot be used to
+ * register a PKCE-less provider: the mechanism the package exists to own survives the widening.
+ *
+ * A duplicate id is `X_OAUTH_PROVIDER_DUPLICATE` rather than a silent replacement — two modules
+ * each registering `'okta'` is one of them quietly deciding where every okta login goes.
+ */
+export function registerOAuthProvider(provider: OAuthProvider): OAuthProvider {
+  if (registry.has(provider.id)) throw oauthProviderDuplicate(provider.id);
+  const sealed = seal(provider);
+  registry.set(sealed.id, sealed);
+  return sealed;
+}
+
+for (const provider of BUILTIN_OAUTH_PROVIDERS) registerOAuthProvider(provider);
+
+export function hasOAuthProvider(id: string): boolean {
+  return registry.has(id);
+}
+
+/**
+ * The one lookup. Throws rather than answering `undefined`, because every caller in this package
+ * would otherwise have to decide what an unknown provider means — and one of them would decide
+ * wrong. `X_OAUTH_PROVIDER_UNKNOWN` already existed for exactly this.
+ */
+export function providerFor(id: string): OAuthProvider {
+  const provider = registry.get(id);
+  if (provider === undefined) throw oauthProviderUnknown(id, oauthProviderIds());
+  return provider;
+}
+
+/**
+ * Live, never a snapshot taken at import: `defineAuth({ providers })` defaults to this, and a
+ * frozen copy would leave an IdP registered after this module loaded enabled nowhere.
+ */
+export function oauthProviderIds(): readonly string[] {
+  return [...registry.keys()];
+}

package/src/oauth-route.ts

@@ -0,0 +1,293 @@
+// Single responsibility: the two HTTP routes the OAuth library functions have always been
+// missing — the redirect out and the callback back — mounted at one fixed pair of paths so the
+// `fix:` lines that name them cannot go stale. Everything below composes `beginOAuth`,
+// `handshakeCookie` and `completeOAuthLogin`; no new protocol lives here.
+//
+// A route DESCRIPTOR, never a mounted handler, for the reason `mcpHttpRoute()` is one:
+// `@ultimat3/http` is tier 2 like this package, so auth may not import it — and `defineRoute`
+// is tier 4 and describes a rendered page. A bare `Request` in, a `Response` out, drivable from
+// a test and mountable by any router that can match a `:param`.
+
+import { type Clock, isUltimateError, renderThrowable, type UltimateError } from '@ultimat3/core';
+import type { Auth, LoginResult } from './auth';
+import { oauthDenied, oauthExchangeFailed, oauthProviderUnknown } from './errors';
+import { beginOAuth, type OAuthProviderId } from './oauth';
+import { BUILTIN_OAUTH_PROVIDER_IDS } from './oauth-builtins';
+import { clearHandshakeCookie, handshakeCookie, readHandshakeCookie } from './oauth-cookie';
+import type { OAuthClientCredentials, OAuthFetch } from './oauth-exchange';
+import { oauthCredentials } from './oauth-exchange';
+import { completeOAuthLogin, type ResolveOAuthGrants } from './oauth-login';
+import {
+  OAUTH_CALLBACK_ROUTE_PATH,
+  OAUTH_START_ROUTE_PATH,
+  oauthCallbackPath,
+} from './oauth-paths';
+import { hasOAuthProvider } from './oauth-registry';
+
+/**
+ * What a router needs to mount one of these. Structural, like `RequestLike` in `session.ts`:
+ * `@ultimat3/http` binds to this shape, this package never binds to `@ultimat3/http`.
+ */
+export interface AuthRouteDescriptor {
+  readonly method: 'GET';
+  /** The mount pattern, `:provider` included. The handler re-reads it off the request itself. */
+  readonly path: string;
+  /** Stable id for a route table, a trace and the manifest. */
+  readonly name: string;
+  /** Both legs are public by definition — they are how an anonymous visitor stops being one. */
+  readonly auth: 'public';
+  handle(request: Request): Promise<Response>;
+}
+
+export interface OAuthLoginRoutes {
+  readonly start: AuthRouteDescriptor;
+  readonly callback: AuthRouteDescriptor;
+}
+
+export interface OAuthLoginOptions {
+  /**
+   * The origin the provider redirects back to. Defaults to `APP_URL`, then to the request's own
+   * origin — which is the `Host` header, so it is preferred last: a forged one only ever produces
+   * a `redirect_uri` the provider refuses, but naming the canonical origin costs nothing.
+   */
+  readonly baseUrl?: string | undefined;
+  /** Defaults to the two env vars in the provider table, read per request, never at import. */
+  readonly credentials?: OAuthClientCredentials | undefined;
+  /** Defaults to `SESSION_SECRET`. Seals the handshake across the two requests. */
+  readonly secret?: string | undefined;
+  /** Injected in tests; production uses the global. */
+  readonly fetch?: OAuthFetch | undefined;
+  readonly timeoutMs?: number | undefined;
+  /** Where a signed-in browser lands. A fixed path — never read from the request. See below. */
+  readonly successPath?: string | undefined;
+  /** Narrower scopes than the provider's defaults, when the app wants less. */
+  readonly scopes?: readonly string[] | undefined;
+  /**
+   * The client address recorded on the session. Defaults to none: the only honest source is a
+   * trusted-proxy chain, and this package cannot see one. `@ultimat3/http` can, and passes it.
+   */
+  readonly clientIp?: ((request: Request) => string | null | undefined) | undefined;
+  /**
+   * What the IdP's answer entitles this identity to. **Omit it and a first-time SSO user is
+   * created with `roles: []` and `orgId: null`** — an actor every `can()` denies, and a
+   * tenant-scoped read that throws `X_TENANCY_ACTOR_ORG_REQUIRED` before the query is built. SSO
+   * "works" and the person can do nothing until somebody runs SQL.
+   *
+   * A seam and not a group-to-role table, because which IdP group means which role is business
+   * convention and business convention never ships (axiom 8). The framework's part is calling it
+   * on every login, so removing somebody from a group in the IdP takes effect at their next
+   * sign-in rather than never.
+   */
+  readonly resolveGrants?: ResolveOAuthGrants | undefined;
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+}
+
+/**
+ * HTTP status per code, for a descriptor driven OUTSIDE a pipeline — a bare `Request` in, a
+ * `Response` out, which is the whole point of a descriptor. `@ultimat3/http`'s `error-map.ts` OWNS
+ * these numbers and is where a new one is declared; this package is the same tier and can never
+ * import it, so the table is a copy the pin `scripts/oauth-route-status.test.ts` holds identical to
+ * `statusFor()`. Everything absent is the provider's fault until proven otherwise: 502.
+ */
+export const OAUTH_ROUTE_STATUS: Readonly<Record<string, number>> = {
+  X_OAUTH_PROVIDER_UNKNOWN: 404,
+  X_OAUTH_DENIED: 403,
+  X_OAUTH_STATE_INVALID: 400,
+  X_OAUTH_TOKEN_INVALID: 400,
+  X_UNAUTHENTICATED: 401,
+  X_MFA_REQUIRED: 401,
+  X_ACCOUNT_LOCKED: 429,
+  X_ENV_MISSING: 500,
+  X_CONFIG_INVALID: 500,
+};
+
+/**
+ * What an anonymous caller is allowed to read. `UltimateError.toJSON()` carries `meta` and `stack`
+ * — a developer's fields — and BOTH legs of this flow are public by definition, so serialising it
+ * whole published a stack trace and whatever a factory put in `meta` to whoever typed the URL. Four
+ * fields, the same four on every code: no per-code judgement about which `meta` key is safe today.
+ */
+const publicBody = (coded: UltimateError): Record<string, string> => ({
+  code: coded.code,
+  title: coded.title,
+  cause: coded.cause,
+  fix: coded.fix,
+  docs: coded.docs,
+});
+
+/**
+ * Failure is JSON, never a redirect to a login page carrying `?error=`. A callback is the one
+ * request in the flow whose failure the developer has to read, and a redirect that drops the code
+ * and the fix line is exactly how three dead `fix:` strings survived a whole release. An app that
+ * wants a rendered page wraps these two descriptors; the framework ships the debuggable answer.
+ */
+function problem(error: unknown, extraCookies: readonly string[]): Response {
+  const coded = isUltimateError(error)
+    ? error
+    : oauthExchangeFailed({
+        provider: 'oauth',
+        stage: 'token',
+        // `renderThrowable`, never `error.message`: the throw came from an adapter or a `fetch`
+        // this package does not own, and a getter on `message` — or a `Proxy` trapping
+        // `getPrototypeOf` — would make the callback's last answer throw instead of send.
+        detail: renderThrowable(error),
+        fix: 'throw an UltimateError from the AuthAdapter or OAuthFetch that failed — the factories are in packages/auth/src/errors.ts',
+      });
+  const headers = new Headers({ 'content-type': 'application/json; charset=utf-8' });
+  for (const cookie of extraCookies) headers.append('set-cookie', cookie);
+  return new Response(JSON.stringify(publicBody(coded)), {
+    // 502 is the default: an uncoded throw on this path came out of the provider conversation.
+    status: OAUTH_ROUTE_STATUS[coded.code] ?? 502,
+    headers,
+  });
+}
+
+/** `/auth/oauth/github` → `github`; `/auth/oauth/github/callback` → `github`. */
+function providerSegment(request: Request, leg: 'start' | 'callback'): string {
+  const segments = new URL(request.url).pathname.split('/').filter((s) => s.length > 0);
+  const index = leg === 'start' ? segments.length - 1 : segments.length - 2;
+  return segments[index] ?? '';
+}
+
+/**
+ * Both halves of "is this a provider", in one refusal. An unknown segment and a known provider
+ * the app left out of `defineAuth({ providers })` are the same 404 on purpose — telling an
+ * anonymous caller which of the two it hit describes the app's configuration for free.
+ *
+ * The list in the refusal is the THREE BUILT-INS, never the live registry and never
+ * `defineAuth({ providers })`. Both of the latter are this deployment's own configuration, and
+ * this caller is an anonymous stranger who typed a URL: an app that registered an internal OP has
+ * put its own vocabulary into the registry, and echoing it back names a system the stranger had no
+ * way to know exists. The built-in list is a framework constant already in the public docs, so it
+ * discloses nothing while still making the fix executable — and `registerOAuthProvider` in the
+ * same sentence covers the other branch without enumerating anything.
+ *
+ * `providerFor()` keeps the full registered list for the same reason in reverse: its reader is a
+ * developer holding a stack trace, and there the list is exactly what makes the fix runnable.
+ */
+function assertEnabled(auth: Auth, segment: string): OAuthProviderId {
+  const supported = BUILTIN_OAUTH_PROVIDER_IDS;
+  if (!hasOAuthProvider(segment)) throw oauthProviderUnknown(segment, supported);
+  const provider: OAuthProviderId = segment;
+  if (!auth.providers.includes(provider)) throw oauthProviderUnknown(segment, supported);
+  return provider;
+}
+
+function originFor(request: Request, options: OAuthLoginOptions): string {
+  const env = options.env ?? Bun.env;
+  const declared = options.baseUrl ?? env['APP_URL']?.trim() ?? '';
+  return declared === '' ? new URL(request.url).origin : declared.replace(/\/+$/, '');
+}
+
+/** The handshake's own options, assembled once so both legs seal and open it identically. */
+const sealOptions = (
+  clock: Clock,
+  options: OAuthLoginOptions,
+): { clock: Clock; secret?: string | undefined } => ({
+  clock,
+  ...(options.secret === undefined ? {} : { secret: options.secret }),
+});
+
+async function startHandler(
+  auth: Auth,
+  options: OAuthLoginOptions,
+  request: Request,
+): Promise<Response> {
+  try {
+    const provider = assertEnabled(auth, providerSegment(request, 'start'));
+    const credentials = options.credentials ?? oauthCredentials(provider, options.env ?? Bun.env);
+    const handshake = beginOAuth({
+      provider,
+      clientId: credentials.clientId,
+      redirectUri: `${originFor(request, options)}${oauthCallbackPath(provider)}`,
+      scopes: options.scopes,
+    });
+    return new Response(null, {
+      // 302, the status every OAuth client already expects on this hop.
+      status: 302,
+      headers: {
+        location: handshake.authorizeUrl,
+        'set-cookie': handshakeCookie(handshake, sealOptions(auth.clock, options)),
+      },
+    });
+  } catch (error) {
+    return problem(error, []);
+  }
+}
+
+/** The provider declining is `error=` on the redirect, and there is no code to exchange. */
+function assertNoProviderError(url: URL, provider: string): void {
+  const declined = url.searchParams.get('error');
+  if (declined === null || declined === '') return;
+  throw oauthDenied(provider, declined, url.searchParams.get('error_description'));
+}
+
+async function callbackHandler(
+  auth: Auth,
+  options: OAuthLoginOptions,
+  request: Request,
+): Promise<Response> {
+  const segment = providerSegment(request, 'callback');
+  // Cleared on every outcome, success and failure alike: the code it authorised is spent either
+  // way, so a handshake that outlives its own callback is a replay window and nothing else.
+  const clear = hasOAuthProvider(segment) ? [clearHandshakeCookie(segment)] : [];
+  try {
+    const provider = assertEnabled(auth, segment);
+    const url = new URL(request.url);
+    assertNoProviderError(url, provider);
+    const result: LoginResult = await completeOAuthLogin(auth, {
+      handshake: readHandshakeCookie(request, provider, sealOptions(auth.clock, options)),
+      callback: {
+        state: url.searchParams.get('state') ?? '',
+        code: url.searchParams.get('code') ?? '',
+      },
+      ...(options.credentials === undefined ? {} : { credentials: options.credentials }),
+      ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+      ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+      ...(options.resolveGrants === undefined ? {} : { resolveGrants: options.resolveGrants }),
+      ip: options.clientIp?.(request) ?? null,
+      userAgent: request.headers.get('user-agent'),
+    });
+    const headers = new Headers({
+      // A fixed path, never `?next=`: an attacker-supplied return target on the one endpoint whose
+      // job is to hand out a session is the classic open redirect, and `@ultimat3/http`'s
+      // `nextAfterSignIn` is the one implementation of that check. Two copies is one that drifts.
+      location: options.successPath ?? '/',
+    });
+    // 303: the callback may arrive as a `form_post`, and the destination is a GET either way.
+    headers.append('set-cookie', result.cookie);
+    for (const cookie of clear) headers.append('set-cookie', cookie);
+    return new Response(null, { status: 303, headers });
+  } catch (error) {
+    return problem(error, clear);
+  }
+}
+
+/**
+ * The two routes. Mount them and "log in with GitHub" is a button pointing at
+ * `/auth/oauth/github` — no handshake store, no PKCE bookkeeping, no state check to forget.
+ *
+ * ```ts
+ * const { start, callback } = oauthLogin(auth);
+ * // start.path    → '/auth/oauth/:provider'
+ * // callback.path → '/auth/oauth/:provider/callback'
+ * ```
+ */
+export function oauthLogin(auth: Auth, options: OAuthLoginOptions = {}): OAuthLoginRoutes {
+  return Object.freeze({
+    start: Object.freeze({
+      method: 'GET',
+      path: OAUTH_START_ROUTE_PATH,
+      name: 'auth.oauth.start',
+      auth: 'public',
+      handle: (request: Request) => startHandler(auth, options, request),
+    } as const),
+    callback: Object.freeze({
+      method: 'GET',
+      path: OAUTH_CALLBACK_ROUTE_PATH,
+      name: 'auth.oauth.callback',
+      auth: 'public',
+      handle: (request: Request) => callbackHandler(auth, options, request),
+    } as const),
+  });
+}