@ultimat3/auth 31.1.0 → 31.2.0

package/CLAUDE.md

@@ -67,8 +67,14 @@ A rule marked `†` has its full text in [`docs/history/auth-rules.md`](../../do
   `deleteSessionsForOrg` joins through `x_users`; `x_sessions` does **not** gain an `org_id`.
 - The code flow carries `nonce` inside the id token. `assertOAuthCallback` checks an echoed one when
   present and never requires it; `verifyIdToken` is the real gate.
-- `sealHandshake`/`openHandshake` (a hand-built flow's cookie, not `oauthLogin`'s): the provider is
-  an argument, expiry the server's clock, one cookie per provider (`handshakeCookieName`).
+- `sealHandshake`/`openHandshake` (a hand-built flow's server-side store): the provider is an
+  argument, expiry the server's clock. **The handshake COOKIE is `oauthLogin`'s own**:
+  `handshakeCookieName` IS `identityStateCookieName` (`__Host-x_sso_<p>`) and `handshakeCookie`
+  seals `encodeOidcState`, so a built-in leg and a hand-built one read each other
+  (`oauth-handshake-cookie.test.ts`). The read-only `__Host-x_oauth_<p>` fallback goes in 32.0.0.
+- **`oauthLogin({ callbackPath })` is the one movable path** (`sign-in-callback-path.ts`): mount,
+  `redirect_uri` and the checked URL from one pattern, refused if URL normalisation would rewrite
+  it; the start path never moves.
 - `takeVerification(purpose, identifier, tokenHash)` consumes **only on a hash match**, in one
   conditional statement (`consumed_at is null` on the UPDATE and its subselect,
   `order by created_at desc limit 1`); `consumeVerification` still compares in constant time.
@@ -84,7 +90,7 @@ A rule marked `†` has its full text in [`docs/history/auth-rules.md`](../../do
 - Link by address only when the provider **and** the local account both verified it
   (`link: 'verified-email'`, default; `'never'` is the only other value).
 - **One sign-in route implementation** (`identity-provider-route-core.ts`) at
-  `/auth/sso/:provider[/callback]`; failure is coded JSON, success a 303 to `successPath`. †
+  `/auth/sso/:provider[/callback]` (the callback movable only by `callbackPath`); failure is coded JSON, success a 303 to `successPath`. †
 - Refresh is **not implemented**, so the framework **stores no provider token**: `accountFor`
   (`oauth-login.ts`) writes `accessToken: null, refreshToken: null`. The columns and `AuthAccount`
   fields stay; an app that stores tokens implements `linkAccount` itself.
@@ -173,7 +179,9 @@ A rule marked `†` has its full text in [`docs/history/auth-rules.md`](../../do
 | `mfa-secret.ts` | the TOTP secret at rest: seal on write, open on read, the one-shot that seals older rows |
 | `directory.ts` | `describeUser` (allow-list projection), `listOrgUsers`, external-id lookup |
 | `privileges.ts` | `updatePrivileges` — the grant, the rotation it requires, and the sessions a changed password ends |
-| `oauth-cookie.ts` | the handshake's home between the two legs: seal, open, the cookie |
+| `oauth-cookie.ts` | the handshake's server-side codec: seal, open, secret, TTL |
+| `oauth-handshake-cookie.ts` | the handshake as a cookie — the sign-in routes' own name and seal, plus the one-release legacy read |
+| `sign-in-callback-path.ts` | the callback pattern: default or `callbackPath`, validated; mount, `redirect_uri`, provider segment |
 | `oauth-exchange.ts` | `oauthCredentials` + the one POST to the token endpoint |
 | `id-token.ts` | id token → claims this handshake may believe |
 | `*-fixture.ts` | test-only, off `index.ts`: `id-token-` (the string-input JWT builder), `auth-` (KDF params, password, `AuthError` catcher for `auth*.test.ts`), `oauth-login-` (adapter, clock, profile) |

package/README.md

@@ -866,11 +866,35 @@ router that can match a `:param` — and `runtime.routes` is the one an app has.
 framework's own routes and before the pages; every field it shares the file with is in
 [`wiki/Configuration.md`](../../wiki/Configuration.md#runtime-overrides--appsappruntimets).
 
-**The paths are not configurable.** `X_OAUTH_STATE_INVALID` quotes `oauthStartPath()`, the same
-declaration the mount reads. A movable base path is that sentence going stale again. Since 31.0.0
-the base is `/auth/sso`: `oauthLogin` is a front door over `identityProviderRoutes`' legs, so OAuth
-and SAML share the paths, the sealed state cookie and the refusal body (re-register the callback
-URL at each IdP — `wiki/Upgrading.md`).
+**The start path is fixed; the callback path is not.** `X_OAUTH_STATE_INVALID` quotes
+`oauthStartPath()`, the same declaration the start mount reads — a movable start path is that
+sentence going stale again. Since 31.0.0 the base is `/auth/sso`: `oauthLogin` is a front door over
+`identityProviderRoutes`' legs, so OAuth and SAML share the paths, the sealed state cookie and the
+refusal body. The callback defaults to `/auth/sso/<provider>/callback`, which each IdP must have
+registered (`wiki/Upgrading.md`) — or keep the URI it already has with
+[`oauthLogin({ callbackPath })`](#keeping-a-registered-callback-url).
+
+### Keeping a registered callback URL
+
+`oauthLogin(auth, { callbackPath })` moves the callback
+leg — its mount (`callback.path`), the `redirect_uri` every provider is sent, and the URL the
+callback checks it against — for an app whose IdP registration cannot change:
+
+```ts
+import { type Auth, oauthLogin } from '@ultimat3/auth';
+
+declare const auth: Auth; // your defineAuth(...)
+declare const router: { get(path: string, handle: (request: Request) => Promise<Response>): void };
+
+const { start, callback } = oauthLogin(auth, { callbackPath: '/auth/oauth/:provider/callback' });
+router.get(start.path, start.handle); // '/auth/sso/:provider' — the start leg never moves
+router.get(callback.path, callback.handle); // mount callback.path, never OAUTH_CALLBACK_ROUTE_PATH
+```
+
+One whole `:provider` segment, absolute, no query, fragment, wildcard or other parameter, no
+segment URL normalisation would rewrite (`.`, `..`, empty, `%`-encoded, `\`), and not the start
+path — anything else is `X_CONFIG_INVALID` at the call. The start leg stays
+`/auth/sso/:provider`: it is a link in your own page, and the `fix:` lines name it.
 
 `oauthLogin` needs an origin to build the provider's `redirect_uri` from: `baseUrl`, or `APP_URL`.
 With neither, the start leg refuses with `X_ENV_MISSING` rather than trust a request header.
@@ -907,11 +931,16 @@ SameSite=Lax` under a `__Host-` name, and expired against the server's clock rat
 client's copy of `Max-Age`. `sealHandshake` / `openHandshake` are the same codec without the
 cookie, for an app that would rather keep it server-side.
 
-`oauthLogin` itself no longer uses this cookie (31.0.0): its state rides the sign-in routes' own
-`__Host-x_sso_<provider>`, sealed the same way and claimed once in `auth.totpReplay`. The
-`handshakeCookie` family stays for a hand-built flow over `beginOAuth` / `completeOAuthLogin`.
+**One cookie, both doors.** `handshakeCookie` writes exactly what `oauthLogin`'s start leg writes —
+the name `__Host-x_sso_<provider>`, the seal, the encoding — so either leg can be the built-in one
+and the other hand-built: `oauthLogin().start` with a callback over `readHandshakeCookie` /
+`completeOAuthLogin`, or a `beginOAuth` + `handshakeCookie` start with `oauthLogin().callback`.
+31.1 and before wrote `__Host-x_oauth_<provider>` from this family, which the start leg never
+read and never wrote. `readHandshakeCookie` still opens that cookie, read-only, for one release —
+a handshake begun on an old pod mid-deploy finishes on a new one — and stops in 32.0.0.
+`clearHandshakeCookie` clears only the current name; a legacy one expires on its own `Max-Age`.
 
-**One cookie per provider:** `handshakeCookieName(provider)` → `__Host-x_oauth_github`. A browser
+**One cookie per provider:** `handshakeCookieName(provider)` → `__Host-x_sso_github`. A browser
 is one cookie jar and a user is allowed two tabs, so a single shared name means the `google`
 redirect overwrites a `github` handshake still in flight — and the github callback then opens
 google's and fails `X_OAUTH_STATE_INVALID` for a reason no restart clears. `handshakeCookie` takes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "31.1.0",
+  "version": "31.2.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "keywords": [
     "ultimate",
@@ -48,8 +48,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "31.1.0",
-    "@ultimat3/db": "31.1.0",
-    "@ultimat3/schema": "31.1.0"
+    "@ultimat3/core": "31.2.0",
+    "@ultimat3/db": "31.2.0",
+    "@ultimat3/schema": "31.2.0"
   }
 }

package/src/identity-provider-cookie.ts

@@ -7,8 +7,14 @@ import { type Clock, hmac, readCookie, serializeSetCookie, timingSafeEqual } fro
 import type { IdentityProvider } from './identity-provider';
 import { DEFAULT_HANDSHAKE_TTL_MS, handshakeSecret } from './oauth-cookie';
 import { oauthStateInvalid } from './oauth-errors';
+import { assertFiniteAuthCount } from './policy-numbers';
 import { base64Url, base64UrlBytes } from './tokens';
 
+/**
+ * The ONE name every sign-in state cookie is written and read under — the built-in legs and the
+ * exported `handshakeCookie` family alike (`handshakeCookieName` is this function). Two names
+ * once let a built-in start leg and a hand-built callback miss each other entirely.
+ */
 export const IDENTITY_STATE_COOKIE_PREFIX = '__Host-x_sso';
 
 export const identityStateCookieName = (provider: string): string =>
@@ -18,56 +24,41 @@ export interface IdentityStateOptions {
   readonly clock: Clock;
   /** Defaults to `SESSION_SECRET`. */
   readonly secret?: string | undefined;
+  /** Defaults to `DEFAULT_HANDSHAKE_TTL_MS`; the caller screens it. */
+  readonly ttlMs?: number | undefined;
 }
 
+type CallbackMethod = IdentityProvider['callbackMethod'];
+
 const sign = (body: string, secret: string): string => hmac('sha256', secret, body, 'hex');
 
-export function identityStateCookie(
-  provider: IdentityProvider,
+const sameSite = (method: CallbackMethod) => (method === 'POST' ? 'None' : 'Lax');
+
+/** `[id, state, issuedAt]`, signed: the value both cookie writers put under the one name. */
+export function sealIdentityState(
+  id: string,
   state: string,
   options: IdentityStateOptions,
 ): string {
   const body = base64Url(
-    new TextEncoder().encode(JSON.stringify([provider.id, state, options.clock.now().getTime()])),
+    new TextEncoder().encode(JSON.stringify([id, state, options.clock.now().getTime()])),
   );
-  const sealed = `${body}.${sign(body, options.secret ?? handshakeSecret())}`;
-  return serializeSetCookie(identityStateCookieName(provider.id), sealed, {
-    maxAge: Math.floor(DEFAULT_HANDSHAKE_TTL_MS / 1000),
-    sameSite: provider.callbackMethod === 'POST' ? 'None' : 'Lax',
-  });
+  return `${body}.${sign(body, options.secret ?? handshakeSecret())}`;
 }
 
-/**
- * Sent with every callback answer: the state it carried is spent whatever the outcome. Takes the id
- * and method rather than a provider, so a refusal before the provider resolved can still clear it.
- */
-export const clearIdentityStateCookie = (
+/** The state `sealIdentityState` sealed for `id`, or `X_OAUTH_STATE_INVALID` for every failure. */
+export function openIdentityState(
+  sealed: string,
   id: string,
-  callbackMethod: IdentityProvider['callbackMethod'],
-): string =>
-  serializeSetCookie(identityStateCookieName(id), '', {
-    maxAge: 0,
-    sameSite: callbackMethod === 'POST' ? 'None' : 'Lax',
-  });
-
-/** The state `begin` returned, or `X_OAUTH_STATE_INVALID` — one refusal for every way it fails. */
-export function readIdentityState(
-  request: Request,
-  provider: IdentityProvider,
   options: IdentityStateOptions,
 ): string {
-  const sealed = readCookie(request.headers.get('cookie'), identityStateCookieName(provider.id));
-  if (sealed === null) throw oauthStateInvalid(provider.id, 'no sign-in state cookie arrived');
   const dot = sealed.lastIndexOf('.');
   const body = sealed.slice(0, Math.max(dot, 0));
   if (
     dot <= 0 ||
     !timingSafeEqual(sign(body, options.secret ?? handshakeSecret()), sealed.slice(dot + 1))
   ) {
-    throw oauthStateInvalid(
-      provider.id,
-      'the sign-in state was tampered with, or the secret rotated',
-    );
+    throw oauthStateInvalid(id, 'the sign-in state was tampered with, or the secret rotated');
   }
   let parsed: unknown;
   try {
@@ -76,14 +67,63 @@ export function readIdentityState(
     parsed = null;
   }
   if (!Array.isArray(parsed) || parsed.length !== 3) {
-    throw oauthStateInvalid(provider.id, 'the sign-in state is not readable');
+    throw oauthStateInvalid(id, 'the sign-in state is not readable');
   }
-  const [id, state, issuedAt] = parsed as readonly unknown[];
-  if (id !== provider.id || typeof state !== 'string' || typeof issuedAt !== 'number') {
-    throw oauthStateInvalid(provider.id, 'the sign-in state belongs to another provider');
+  const [sealedId, state, issuedAt] = parsed as readonly unknown[];
+  if (sealedId !== id || typeof state !== 'string' || typeof issuedAt !== 'number') {
+    throw oauthStateInvalid(id, 'the sign-in state belongs to another provider');
   }
-  if (options.clock.now().getTime() - issuedAt > DEFAULT_HANDSHAKE_TTL_MS) {
-    throw oauthStateInvalid(provider.id, 'the sign-in state expired before the IdP answered');
+  // Screened at the reader: `now - issuedAt > NaN` is false forever, so a NaN deadline never expires.
+  const ttlMs = assertFiniteAuthCount(
+    'oauth.handshake.ttlMs',
+    options.ttlMs ?? DEFAULT_HANDSHAKE_TTL_MS,
+    'the server-side replay deadline is a comparison that is false for every sign-in state, so a lifted one stays redeemable',
+    1,
+  );
+  if (options.clock.now().getTime() - issuedAt > ttlMs) {
+    throw oauthStateInvalid(id, 'the sign-in state expired before the IdP answered');
   }
   return state;
 }
+
+/** A sealed value as a `Set-Cookie`; `name` defaults to the one name. */
+export const serializeIdentityState = (
+  id: string,
+  value: string,
+  callbackMethod: CallbackMethod,
+  maxAge: number,
+  name: string = identityStateCookieName(id),
+): string => serializeSetCookie(name, value, { maxAge, sameSite: sameSite(callbackMethod) });
+
+export const identityStateCookie = (
+  provider: IdentityProvider,
+  state: string,
+  options: IdentityStateOptions,
+): string =>
+  serializeIdentityState(
+    provider.id,
+    sealIdentityState(provider.id, state, options),
+    provider.callbackMethod,
+    Math.floor(DEFAULT_HANDSHAKE_TTL_MS / 1000),
+  );
+
+/**
+ * Sent with every callback answer: the state it carried is spent whatever the outcome. Takes the id
+ * and method rather than a provider, so a refusal before the provider resolved can still clear it.
+ */
+export const clearIdentityStateCookie = (
+  id: string,
+  callbackMethod: CallbackMethod,
+  name?: string,
+): string => serializeIdentityState(id, '', callbackMethod, 0, name);
+
+/** The state `begin` returned, or `X_OAUTH_STATE_INVALID` — one refusal for every way it fails. */
+export function readIdentityState(
+  request: Request,
+  provider: IdentityProvider,
+  options: IdentityStateOptions,
+): string {
+  const sealed = readCookie(request.headers.get('cookie'), identityStateCookieName(provider.id));
+  if (sealed === null) throw oauthStateInvalid(provider.id, 'no sign-in state cookie arrived');
+  return openIdentityState(sealed, provider.id, options);
+}

package/src/identity-provider-oidc.ts

@@ -43,12 +43,23 @@ export interface OidcIdentityProviderConfig {
 const FIELDS = ['state', 'nonce', 'verifier', 'redirectUri', 'authorizeUrl'] as const;
 
 /** The handshake, and when it was issued — the instant its single-use claim is keyed on. */
-interface StoredHandshake {
+export interface StoredHandshake {
   readonly handshake: OAuthHandshake;
   readonly issuedAt: number;
 }
 
-function readHandshake(provider: OAuthProviderId, state: string): StoredHandshake {
+/**
+ * The handshake as the sign-in state string. The ONE encoding: `begin` writes it, and so does
+ * `handshakeCookie`, so a hand-built leg and a built-in one read each other's cookie.
+ */
+export const encodeOidcState = (handshake: OAuthHandshake, issuedAt: number): string =>
+  JSON.stringify({
+    ...Object.fromEntries(FIELDS.map((field) => [field, handshake[field]])),
+    issuedAt,
+  });
+
+/** `encodeOidcState`'s inverse, bound to `provider`; `X_OAUTH_STATE_INVALID` for anything else. */
+export function decodeOidcState(provider: OAuthProviderId, state: string): StoredHandshake {
   let parsed: unknown;
   try {
     parsed = JSON.parse(state);
@@ -91,21 +102,18 @@ export function oidcIdentityProvider(config: OidcIdentityProviderConfig): Identi
         redirectUri: callbackUrl,
         scopes: config.scopes,
       });
-      const state = {
-        ...Object.fromEntries(FIELDS.map((field) => [field, handshake[field]])),
-        issuedAt: clock.now().getTime(),
-      };
-      return { location: handshake.authorizeUrl, state: JSON.stringify(state) };
+      const state = encodeOidcState(handshake, clock.now().getTime());
+      return { location: handshake.authorizeUrl, state };
     },
     answers(state, params) {
       try {
-        return timingSafeEqual(readHandshake(id, state).handshake.state, params['state'] ?? '');
+        return timingSafeEqual(decodeOidcState(id, state).handshake.state, params['state'] ?? '');
       } catch {
         return false;
       }
     },
     async complete({ state, params, callbackUrl, clock, replay }): Promise<VerifiedIdentity> {
-      const { handshake, issuedAt } = readHandshake(id, state);
+      const { handshake, issuedAt } = decodeOidcState(id, state);
       if (handshake.redirectUri !== callbackUrl) {
         throw oauthStateInvalid(id, 'the handshake was started for another callback URL');
       }

package/src/identity-provider-route-core.ts

@@ -24,12 +24,9 @@ import {
 import { oauthRouteStatus } from './identity-provider-status';
 import { oauthStateInvalid } from './oauth-errors';
 import type { OAuthGrants } from './oauth-login';
-import {
-  OAUTH_CALLBACK_ROUTE_PATH,
-  OAUTH_START_ROUTE_PATH,
-  oauthCallbackPath,
-} from './oauth-paths';
+import { OAUTH_START_ROUTE_PATH } from './oauth-paths';
 import { samlResponseInvalid } from './saml-errors';
+import { type CallbackPath, callbackPath } from './sign-in-callback-path';
 
 export interface SignInRouteDescriptor {
   readonly method: 'GET' | 'POST';
@@ -85,6 +82,8 @@ export interface SignInRoutePolicy {
   /** A throw with no code, logged and turned into the refusal served. Its text never is. */
   uncoded(error: unknown): UltimateError;
   grants(identity: VerifiedIdentity): Promise<OAuthGrants | undefined> | OAuthGrants | undefined;
+  /** The callback leg's pattern; `oauthLogin({ callbackPath })` only. Default: the framework's. */
+  readonly callbackPath?: CallbackPath | undefined;
 }
 
 export interface SignInRoutes {
@@ -120,9 +119,9 @@ function problem(policy: SignInRoutePolicy, error: unknown, cookies: readonly st
   return new Response(JSON.stringify(body), { status, headers });
 }
 
-function segmentOf(request: Request, leg: 'start' | 'callback'): string {
+function startSegment(request: Request): string {
   const parts = new URL(request.url).pathname.split('/').filter((part) => part !== '');
-  return parts[leg === 'start' ? parts.length - 1 : parts.length - 2] ?? '';
+  return parts[parts.length - 1] ?? '';
 }
 
 function origin(options: SignInRouteOptions): string {
@@ -169,6 +168,7 @@ export function signInRoutes(
   options: SignInRouteOptions,
   policy: SignInRoutePolicy,
 ): SignInRoutes {
+  const back = policy.callbackPath ?? callbackPath();
   const seal = {
     clock: auth.clock,
     ...(options.secret === undefined ? {} : { secret: options.secret }),
@@ -179,8 +179,8 @@ export function signInRoutes(
       // Before the provider: asked after, a missing origin answered 500 for an enabled provider
       // and 404 for one that is not — an oracle for the app's configuration.
       const base = origin(options);
-      const provider = policy.resolve(segmentOf(request, 'start'), 'start');
-      const callbackUrl = `${base}${oauthCallbackPath(provider.id)}`;
+      const provider = policy.resolve(startSegment(request), 'start');
+      const callbackUrl = `${base}${back.pathFor(provider.id)}`;
       const redirect = await provider.begin({ callbackUrl, clock: auth.clock });
       const headers = new Headers({ location: redirect.location });
       headers.append('set-cookie', identityStateCookie(provider, redirect.state, seal));
@@ -191,7 +191,7 @@ export function signInRoutes(
   };
 
   const callback = async (request: Request): Promise<Response> => {
-    const segment = segmentOf(request, 'callback');
+    const segment = back.providerOf(new URL(request.url).pathname);
     // Set only once the answer is bound to this browser's state; then cleared on every outcome,
     // since that answer is spent either way. An unbound answer — a junk cross-site POST riding the
     // SameSite=None cookie — clears nothing, so it cannot end a sign-in in flight.
@@ -213,7 +213,7 @@ export function signInRoutes(
       const identity = await provider.complete({
         state,
         params,
-        callbackUrl: `${base}${oauthCallbackPath(provider.id)}`,
+        callbackUrl: `${base}${back.pathFor(provider.id)}`,
         clock: auth.clock,
         replay: auth.totpReplay,
       });
@@ -247,7 +247,7 @@ export function signInRoutes(
   };
   return Object.freeze({
     start: route('GET', OAUTH_START_ROUTE_PATH, policy.names.start, start),
-    callback: route('GET', OAUTH_CALLBACK_ROUTE_PATH, policy.names.callback, callback),
-    acs: route('POST', OAUTH_CALLBACK_ROUTE_PATH, policy.names.acs, callback),
+    callback: route('GET', back.pattern, policy.names.callback, callback),
+    acs: route('POST', back.pattern, policy.names.acs, callback),
   });
 }

package/src/index.ts

@@ -243,15 +243,11 @@ export {
   GITHUB_PROVIDER,
   GOOGLE_PROVIDER,
 } from './oauth-builtins';
-export type { HandshakeCookieOptions, HandshakeSealOptions } from './oauth-cookie';
+export type { HandshakeSealOptions } from './oauth-cookie';
 export {
-  clearHandshakeCookie,
   DEFAULT_HANDSHAKE_TTL_MS,
-  handshakeCookie,
-  handshakeCookieName,
   handshakeSecret,
   openHandshake,
-  readHandshakeCookie,
   sealHandshake,
 } from './oauth-cookie';
 export type { DiscoverOAuthProviderInput } from './oauth-discovery';
@@ -273,6 +269,13 @@ export type {
 } from './oauth-exchange';
 export { exchangeOAuthCode, oauthCredentials } from './oauth-exchange';
 export type { OAuthGrantContext } from './oauth-grant-context';
+export type { HandshakeCookieOptions } from './oauth-handshake-cookie';
+export {
+  clearHandshakeCookie,
+  handshakeCookie,
+  handshakeCookieName,
+  readHandshakeCookie,
+} from './oauth-handshake-cookie';
 export type {
   CompleteOAuthLoginInput,
   OAuthGrants,

package/src/oauth-cookie.ts

@@ -1,40 +1,17 @@
-// Single responsibility: where the handshake lives between the redirect and the callback. The
-// two legs of an authorization-code login are separate HTTP requests, so `beginOAuth`'s state,
-// nonce and PKCE verifier have to survive the round trip — and a framework that leaves that to
-// the app gets one hand-rolled store per app, which is exactly where PKCE quietly stops proving
-// anything. Sealed here and opened here, so the cookie below and a server-side store share one
-// format at one trust level.
+// Single responsibility: the handshake's server-side codec (`sealHandshake` / `openHandshake`), its
+// secret and its deadline. The two legs of an authorization-code login are separate HTTP requests,
+// so `beginOAuth`'s state, nonce and PKCE verifier have to survive the round trip — and a framework
+// that leaves that to the app gets one hand-rolled store per app, which is exactly where PKCE
+// quietly stops proving anything. The cookie is `oauth-handshake-cookie.ts`.
 
 import type { Clock } from '@ultimat3/core';
-import {
-  EnvMissingError,
-  hmac,
-  readCookie,
-  serializeSetCookie,
-  systemClock,
-  timingSafeEqual,
-} from '@ultimat3/core';
+import { EnvMissingError, hmac, systemClock, timingSafeEqual } from '@ultimat3/core';
 import type { OAuthHandshake, OAuthProviderId } from './oauth';
 import { oauthStateInvalid } from './oauth-errors';
 import { hasOAuthProvider } from './oauth-registry';
 import { assertFiniteAuthCount } from './policy-numbers';
-import type { RequestLike } from './session';
 import { base64Url } from './tokens';
 
-/** `__Host-` for the same reason the session cookie carries it: no subdomain can plant one. */
-export const OAUTH_HANDSHAKE_COOKIE_PREFIX = '__Host-x_oauth';
-
-/**
- * One cookie per provider, because a browser is one cookie jar and a user is allowed two tabs.
- * Under a single shared name, starting a `google` login while a `github` one is mid-flight
- * overwrites the github handshake — and the github callback then opens google's, fails
- * `X_OAUTH_STATE_INVALID` and tells the user to restart the flow that just collided again.
- * Scoping the name makes the two handshakes independent instead of the last writer's.
- */
-export function handshakeCookieName(provider: OAuthProviderId): string {
-  return `${OAUTH_HANDSHAKE_COOKIE_PREFIX}_${provider}`;
-}
-
 /** Long enough to read a consent screen, short enough that a lifted cookie is already stale. */
 export const DEFAULT_HANDSHAKE_TTL_MS = 10 * 60 * 1000;
 
@@ -49,7 +26,7 @@ export const DEFAULT_HANDSHAKE_TTL_MS = 10 * 60 * 1000;
  * Screened at every reader rather than once at seal time: the two legs are two HTTP requests and
  * two calls, so a check on the way out is one the way back never runs.
  */
-function handshakeTtlMs(options: HandshakeSealOptions | undefined): number {
+export function handshakeTtlMs(options: HandshakeSealOptions | undefined): number {
   return assertFiniteAuthCount(
     'oauth.handshake.ttlMs',
     options?.ttlMs ?? DEFAULT_HANDSHAKE_TTL_MS,
@@ -91,15 +68,6 @@ export interface HandshakeSealOptions {
   readonly ttlMs?: number | undefined;
 }
 
-export interface HandshakeCookieOptions extends HandshakeSealOptions {
-  /**
-   * Defaults to `handshakeCookieName(provider)`. Overriding it opts out of the per-provider
-   * scoping, so both legs have to pass the same one — a name set on the redirect and defaulted on
-   * the callback reads a cookie that is not there.
-   */
-  readonly name?: string | undefined;
-}
-
 /**
  * Signed, not encrypted, for the reason the cursor codec is: every field here is already the
  * browser's own — `state` travelled in the URL it was just sent to, and the verifier and nonce
@@ -182,50 +150,6 @@ export function openHandshake(
   return { provider, state, nonce, verifier, redirectUri, authorizeUrl };
 }
 
-/**
- * Set on the redirect. `SameSite=Lax` is the one attribute that differs in reasoning from the
- * session cookie's: the callback is a top-level cross-site GET from the provider, which `Lax`
- * still attaches the cookie to and `Strict` would strip — leaving every login to fail its state
- * check. A provider answering with `response_mode=form_post` POSTs instead, and this cookie
- * would not reach it; neither built-in provider is configured that way.
- */
-export function handshakeCookie(
-  handshake: OAuthHandshake,
-  options?: HandshakeCookieOptions,
-): string {
-  const maxAge = Math.floor(handshakeTtlMs(options) / 1000);
-  // The handshake already names its provider, so the two legs cannot disagree about the name.
-  const name = options?.name ?? handshakeCookieName(handshake.provider);
-  return serializeSetCookie(name, sealHandshake(handshake, options), { maxAge });
-}
-
-/**
- * Send this with the callback's response, always — an authorization code is single-use, so the
- * handshake that authorised it must not outlive it. A mismatched attribute set leaves a live twin.
- *
- * `provider` is required for the reason `openHandshake`'s is: clearing the unscoped name would
- * clear nothing, and clearing every provider's would cancel a login running in another tab.
- */
-export function clearHandshakeCookie(provider: OAuthProviderId, name?: string): string {
-  return serializeSetCookie(name ?? handshakeCookieName(provider), '', { maxAge: 0 });
-}
-
-/** Reads the cookie set on the redirect and returns the handshake `completeOAuthLogin` takes. */
-export function readHandshakeCookie(
-  request: RequestLike,
-  provider: OAuthProviderId,
-  options?: HandshakeCookieOptions,
-): OAuthHandshake {
-  const sealed = readCookie(
-    request.headers.get('cookie'),
-    options?.name ?? handshakeCookieName(provider),
-  );
-  if (sealed === null) {
-    throw oauthStateInvalid(provider, 'no handshake cookie arrived with the callback');
-  }
-  return openHandshake(sealed, provider, options);
-}
-
 /** Keyed SHA-256. Untruncated, unlike a cursor's: a cookie has room and this authorises a login. */
 function sign(body: string, secret: string): string {
   return hmac('sha256', secret, body, 'hex');

package/src/oauth-handshake-cookie.ts

@@ -0,0 +1,107 @@
+// Single responsibility: the OAuth handshake as a cookie, for a hand-built leg over `beginOAuth` /
+// `completeOAuthLogin`. Same name, same seal, same encoding as `oauthLogin`'s own state cookie
+// (`identity-provider-cookie.ts`, `encodeOidcState`), so either leg can be the built-in one: a
+// second name once left a built-in start leg and a hand-built callback unable to find each other.
+
+import { readCookie, systemClock } from '@ultimat3/core';
+import {
+  clearIdentityStateCookie,
+  identityStateCookieName,
+  openIdentityState,
+  sealIdentityState,
+  serializeIdentityState,
+} from './identity-provider-cookie';
+import { decodeOidcState, encodeOidcState } from './identity-provider-oidc';
+import type { OAuthHandshake, OAuthProviderId } from './oauth';
+import { type HandshakeSealOptions, handshakeTtlMs, openHandshake } from './oauth-cookie';
+import { oauthStateInvalid } from './oauth-errors';
+import type { RequestLike } from './session';
+
+/**
+ * One cookie per provider, because a browser is one cookie jar and a user is allowed two tabs.
+ * Under a single shared name, starting a `google` login while a `github` one is mid-flight
+ * overwrites the github handshake — and the github callback then opens google's, fails
+ * `X_OAUTH_STATE_INVALID` and tells the user to restart the flow that just collided again.
+ * The name is the sign-in routes' own: `__Host-x_sso_<provider>`.
+ */
+export const handshakeCookieName = (provider: OAuthProviderId): string =>
+  identityStateCookieName(provider);
+
+/**
+ * The name, and the `sealHandshake` format, this family wrote up to 31.1. Read — never written —
+ * so a handshake begun on an old pod finishes on a new one during the deploy. Its life is the
+ * handshake TTL (10 min by default), so one release of reading it is the whole transition.
+ * Delete with the fallback below in 32.0.0.
+ */
+const LEGACY_HANDSHAKE_COOKIE_PREFIX = '__Host-x_oauth';
+
+export interface HandshakeCookieOptions extends HandshakeSealOptions {
+  /**
+   * Defaults to `handshakeCookieName(provider)`. Overriding it opts out of the per-provider
+   * scoping, so both legs have to pass the same one — a name set on the redirect and defaulted on
+   * the callback reads a cookie that is not there.
+   */
+  readonly name?: string | undefined;
+}
+
+/**
+ * Set on the redirect. `SameSite=Lax`: the callback is a top-level cross-site GET from the
+ * provider, which `Lax` still attaches the cookie to and `Strict` would strip. A provider answering
+ * with `response_mode=form_post` POSTs instead, and this cookie would not reach it.
+ */
+export function handshakeCookie(
+  handshake: OAuthHandshake,
+  options?: HandshakeCookieOptions,
+): string {
+  const maxAge = Math.floor(handshakeTtlMs(options) / 1000);
+  const clock = options?.clock ?? systemClock;
+  const state = encodeOidcState(handshake, clock.now().getTime());
+  const sealed = sealIdentityState(handshake.provider, state, { ...options, clock });
+  // The handshake already names its provider, so the two legs cannot disagree about the name.
+  return serializeIdentityState(handshake.provider, sealed, 'GET', maxAge, options?.name);
+}
+
+/**
+ * Send this with the callback's response, always — an authorization code is single-use, so the
+ * handshake that authorised it must not outlive it. A mismatched attribute set leaves a live twin.
+ *
+ * `provider` is required: clearing every provider's would cancel a login running in another tab.
+ * A legacy `__Host-x_oauth_<p>` cookie is not cleared — one `Set-Cookie` names one cookie; it
+ * expires on its own `Max-Age`, and the code it guarded is spent.
+ */
+export const clearHandshakeCookie = (provider: OAuthProviderId, name?: string): string =>
+  clearIdentityStateCookie(provider, 'GET', name);
+
+/** Opens the current format, else the legacy one; the first refusal is the one reported. */
+function open(sealed: string, provider: OAuthProviderId, options?: HandshakeSealOptions) {
+  const clock = options?.clock ?? systemClock;
+  try {
+    const ttlMs = handshakeTtlMs(options);
+    const state = openIdentityState(sealed, provider, { ...options, clock, ttlMs });
+    return decodeOidcState(provider, state).handshake;
+  } catch (refusal) {
+    try {
+      return openHandshake(sealed, provider, options);
+    } catch {
+      throw refusal;
+    }
+  }
+}
+
+/** Reads the cookie set on the redirect — by either leg — and returns the handshake. */
+export function readHandshakeCookie(
+  request: RequestLike,
+  provider: OAuthProviderId,
+  options?: HandshakeCookieOptions,
+): OAuthHandshake {
+  const header = request.headers.get('cookie');
+  const sealed =
+    readCookie(header, options?.name ?? handshakeCookieName(provider)) ??
+    (options?.name === undefined
+      ? readCookie(header, `${LEGACY_HANDSHAKE_COOKIE_PREFIX}_${provider}`)
+      : null);
+  if (sealed === null) {
+    throw oauthStateInvalid(provider, 'no handshake cookie arrived with the callback');
+  }
+  return open(sealed, provider, options);
+}

package/src/oauth-paths.ts

@@ -5,7 +5,9 @@
 // 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.
+ * The base and the start path are not configurable, on purpose: a movable start path is a `fix:`
+ * line that can go stale again. The callback pattern is the one exception — `oauthLogin({
+ * callbackPath })`, for a `redirect_uri` an IdP already has registered — and no `fix:` quotes it.
  * `/auth/sso` since 31.0.0: every `IdentityProvider` — OIDC and SAML — signs in through it.
  */
 export const OAUTH_BASE_PATH = '/auth/sso';

package/src/oauth-route.ts

@@ -30,6 +30,7 @@ import type { OAuthClientCredentials, OAuthFetch } from './oauth-exchange';
 import { oauthCredentials } from './oauth-exchange';
 import type { ResolveOAuthGrants } from './oauth-login';
 import { hasOAuthProvider } from './oauth-registry';
+import { callbackPath } from './sign-in-callback-path';
 
 /**
  * What a router needs to mount one of these. Structural, like `RequestLike` in `session.ts`:
@@ -97,6 +98,15 @@ export interface OAuthLoginOptions {
    * branch: `providerJwks(providerFor('github'))` throws, because GitHub publishes no `jwks_uri`.
    */
   readonly idTokenKeys?: ((provider: OAuthProviderId) => IdTokenKeys | undefined) | undefined;
+  /**
+   * The callback leg's mount pattern, one whole `:provider` segment — and so the `redirect_uri`
+   * every provider is sent and must have registered. Defaults to `OAUTH_CALLBACK_ROUTE_PATH`
+   * (`/auth/sso/:provider/callback`). Set it to keep a URI already registered at an IdP you cannot
+   * edit, e.g. 30.x's `'/auth/oauth/:provider/callback'`, and mount `callback.path`, never the
+   * constant. The start leg does not move: it is a link in your own page, and `fix:` lines name it.
+   * A pattern a router cannot mount is `X_CONFIG_INVALID` here, at the call.
+   */
+  readonly callbackPath?: string | undefined;
   readonly env?: Readonly<Record<string, string | undefined>> | undefined;
 }
 
@@ -171,6 +181,7 @@ const asGet = (descriptor: SignInRouteDescriptor): AuthRouteDescriptor =>
  */
 export function oauthLogin(auth: Auth, options: OAuthLoginOptions = {}): OAuthLoginRoutes {
   const routes = signInRoutes(auth, options, {
+    callbackPath: callbackPath(options.callbackPath),
     resolve(segment, leg) {
       if (!hasOAuthProvider(segment) || !auth.providers.includes(segment)) throw unknown(segment);
       // Asked on the callback only: the start leg verifies nothing.

package/src/sign-in-callback-path.ts

@@ -0,0 +1,61 @@
+// Single responsibility: the callback leg's path pattern — the default, or an app's own
+// (`oauthLogin({ callbackPath })`) — refused at construction when a router could not mount it or the
+// provider could not be read back out of it. One value yields the mount, the `redirect_uri` sent
+// to the IdP and the provider segment of an arriving request, so the three cannot disagree.
+
+import { ConfigInvalidError, renderCauseValue } from '@ultimat3/core';
+import { OAUTH_CALLBACK_ROUTE_PATH, OAUTH_START_ROUTE_PATH } from './oauth-paths';
+
+const PARAM = ':provider';
+
+export interface CallbackPath {
+  /** The mount pattern, `:provider` included. */
+  readonly pattern: string;
+  /** The concrete path for one provider: what `redirect_uri` carries. */
+  pathFor(provider: string): string;
+  /** The provider segment of a request this pattern matched, counted from the END of the path. */
+  providerOf(pathname: string): string;
+}
+
+const split = (path: string): string[] => path.split('/').filter((part) => part !== '');
+
+function refuse(pattern: string, why: string): ConfigInvalidError {
+  return new ConfigInvalidError({
+    cause: `oauthLogin({ callbackPath: ${renderCauseValue(pattern)} }) ${why}`,
+    fix: "oauthLogin(auth, { callbackPath: '/auth/oauth/:provider/callback' })  // absolute, one whole ':provider' segment, no other parameter, no ./../empty/encoded segment, not the start path",
+  });
+}
+
+/**
+ * Counted from the end so a router mounting the routes under a prefix still finds the segment —
+ * the default's `parts.length - 2` before this file existed.
+ */
+export function callbackPath(pattern: string = OAUTH_CALLBACK_ROUTE_PATH): CallbackPath {
+  if (!pattern.startsWith('/')) throw refuse(pattern, 'is not an absolute path');
+  if (/[?#*]/.test(pattern)) throw refuse(pattern, 'carries a query, fragment or wildcard');
+  if (pattern === OAUTH_START_ROUTE_PATH) throw refuse(pattern, 'is the start leg’s own path');
+  const parts = split(pattern);
+  const params = parts.filter((part) => part.includes(':'));
+  if (params.length !== 1 || params[0] !== PARAM) {
+    throw refuse(pattern, 'must carry exactly one parameter, the whole segment :provider');
+  }
+  // A browser and a router both see the NORMALISED path: `..`, `.`, `\` and `%2e` move segments,
+  // an empty one shifts the count, and `%2f` is a slash to some routers and not to others.
+  const sample = pattern.replace(PARAM, 'provider');
+  if (
+    pattern.includes('%') ||
+    pattern.slice(1).split('/').includes('') ||
+    new URL(sample, 'https://x.invalid').pathname !== sample
+  ) {
+    throw refuse(pattern, 'changes under URL normalisation, which would move or drop :provider');
+  }
+  const fromEnd = parts.length - 1 - parts.indexOf(PARAM);
+  return Object.freeze({
+    pattern,
+    pathFor: (provider: string) => pattern.replace(PARAM, provider),
+    providerOf(pathname: string) {
+      const segments = split(pathname);
+      return segments[segments.length - 1 - fromEnd] ?? '';
+    },
+  });
+}