@ultimat3/auth 1.2.0 → 3.0.0

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),
+  });
+}

package/src/oauth.ts

@@ -1,9 +1,11 @@
 // Single responsibility: the OAuth2/OIDC handshake. PKCE is mandatory rather than
 // provider-dependent — an authorization code with no proof-of-possession is stealable from a
 // redirect, and "this provider does not need it" is how that becomes a real incident. Provider
-// configs are pure data: importing this file performs no network I/O and reads no env.
+// configs are pure data and live in `oauth-registry.ts`: importing this file performs no network
+// I/O and reads no env.
 
 import { oauthStateInvalid } from './errors';
+import { providerFor } from './oauth-registry';
 import { base64Url, randomToken, sha256Bytes, timingSafeEqual } from './tokens';
 
 export interface OAuthProvider {
@@ -18,67 +20,37 @@ export interface OAuthProvider {
    * token. A list rather than one string because Google has issued both forms for years.
    */
   readonly issuers: readonly string[];
+  /**
+   * Where this provider publishes the keys its id tokens are signed with. `null` for a provider
+   * that issues no id token (GitHub). A provider with a key set can have a token from it verified
+   * on a channel that is not the token endpoint — IdP-initiated login, `form_post`, back-channel
+   * logout — which is what `jwks.ts` and `verifyIdToken({ keys })` exist for.
+   */
+  readonly jwksUri: string | null;
   readonly scopes: readonly string[];
-  readonly usesPkce: boolean;
+  /**
+   * The literal `true`, not `boolean`. A provider config saying `usesPkce: false` was always
+   * invalid — an authorization code with no proof-of-possession is stealable from a redirect —
+   * and a comment saying so is not a build error. This is, and it deletes every downstream
+   * `if (provider.usesPkce)` branch along with the state it could ever have been false in.
+   *
+   * It stays the literal now that `registerOAuthProvider` is open to any app: the mechanism this
+   * package exists to own has to survive the opening, so an app cannot register a PKCE-less IdP.
+   */
+  readonly usesPkce: true;
   /** OIDC providers echo `nonce` in the id token; it binds the token to this browser. */
   readonly usesNonce: boolean;
   readonly clientIdEnv: string;
   readonly clientSecretEnv: string;
 }
 
-export const OAUTH_PROVIDERS = {
-  github: {
-    id: 'github',
-    authorizeUrl: 'https://github.com/login/oauth/authorize',
-    tokenUrl: 'https://github.com/login/oauth/access_token',
-    userInfoUrl: 'https://api.github.com/user',
-    // GitHub omits a private address from the profile; the identity is still incomplete
-    // without it, so the flow asks for the verified list rather than guessing.
-    userEmailsUrl: 'https://api.github.com/user/emails',
-    issuers: [],
-    scopes: ['read:user', 'user:email'],
-    usesPkce: true,
-    usesNonce: false,
-    clientIdEnv: 'GITHUB_CLIENT_ID',
-    clientSecretEnv: 'GITHUB_CLIENT_SECRET',
-  },
-  google: {
-    id: 'google',
-    authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
-    tokenUrl: 'https://oauth2.googleapis.com/token',
-    // Reached only when a narrowed `scopes` leaves the id token without an email claim.
-    userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
-    userEmailsUrl: null,
-    issuers: ['https://accounts.google.com', 'accounts.google.com'],
-    scopes: ['openid', 'email', 'profile'],
-    usesPkce: true,
-    usesNonce: true,
-    clientIdEnv: 'GOOGLE_CLIENT_ID',
-    clientSecretEnv: 'GOOGLE_CLIENT_SECRET',
-  },
-  apple: {
-    id: 'apple',
-    authorizeUrl: 'https://appleid.apple.com/auth/authorize',
-    tokenUrl: 'https://appleid.apple.com/auth/token',
-    // Apple returns claims in the id token only; there is no userinfo endpoint to call.
-    userInfoUrl: null,
-    userEmailsUrl: null,
-    issuers: ['https://appleid.apple.com'],
-    scopes: ['name', 'email'],
-    usesPkce: true,
-    usesNonce: true,
-    clientIdEnv: 'APPLE_CLIENT_ID',
-    // Apple alone does not accept a static secret: `APPLE_CLIENT_SECRET` must hold the ES256
-    // client-secret JWT signed with the .p8 key, which Apple expires every six months.
-    clientSecretEnv: 'APPLE_CLIENT_SECRET',
-  },
-} as const satisfies Readonly<Record<string, OAuthProvider>>;
-
-export type OAuthProviderId = keyof typeof OAUTH_PROVIDERS;
-
-export const OAUTH_PROVIDER_IDS: readonly OAuthProviderId[] = Object.freeze(
-  Object.keys(OAUTH_PROVIDERS) as OAuthProviderId[],
-);
+/**
+ * Any registered provider's id — `string`, not a closed union, since 1.3.0. The union of three
+ * consumer IdPs made an enterprise OP unrepresentable at the type level, which is a constraint no
+ * configuration can escape. `providerFor(id)` is the runtime check that replaces it, and it
+ * throws the same `X_OAUTH_PROVIDER_UNKNOWN` the route already answered with.
+ */
+export type OAuthProviderId = string;
 
 export interface PkcePair {
   readonly verifier: string;
@@ -115,7 +87,7 @@ export interface BeginOAuthInput {
 }
 
 export function beginOAuth(input: BeginOAuthInput): OAuthHandshake {
-  const provider = OAUTH_PROVIDERS[input.provider];
+  const provider = providerFor(input.provider);
   const pkce = createPkce();
   const state = randomToken(16);
   const nonce = randomToken(16);
@@ -155,11 +127,12 @@ export interface OAuthCallback {
  * tells an attacker which half to keep guessing at.
  */
 export function assertOAuthCallback(handshake: OAuthHandshake, callback: OAuthCallback): void {
-  const provider = OAUTH_PROVIDERS[handshake.provider];
+  const provider = providerFor(handshake.provider);
   if (!timingSafeEqual(handshake.state, callback.state)) {
     throw oauthStateInvalid(provider.id, 'state did not match the stored handshake');
   }
-  if (provider.usesPkce && handshake.verifier.length < 43) {
+  // Unconditional: `usesPkce` is the literal `true`, so there is no provider to exempt.
+  if (handshake.verifier.length < 43) {
     throw oauthStateInvalid(provider.id, 'no PKCE verifier was stored for this handshake');
   }
   if (callback.nonce !== undefined && !timingSafeEqual(handshake.nonce, callback.nonce)) {

package/src/password.ts

@@ -3,7 +3,8 @@
 // a migration. Verification always burns a full KDF even when the user does not exist —
 // otherwise response time answers "is this email registered?" for free.
 
-import { passwordWeak } from './errors';
+import { AuthError, passwordWeak } from './errors';
+import { kdfGate } from './kdf-gate';
 
 export interface PasswordParams {
   readonly algorithm: 'argon2id';
@@ -57,15 +58,24 @@ const COMMON_PASSWORDS: ReadonlySet<string> = new Set([
   'correcthorse',
 ]);
 
+/**
+ * Through `kdfGate()`, like every other KDF call here: 19 MiB of arena per hash and no per-source
+ * limiter that an IPv6 /64 cannot walk around means the ONLY thing bounding argon2 memory on this
+ * box is this gate. Past its queue it refuses with `X_OVERLOADED`, the same shed http's `admit`
+ * stage performs — a refusal that costs one comparison, not one arena.
+ */
 export async function hashPassword(
   password: string,
   params: PasswordParams = DEFAULT_PASSWORD_PARAMS,
 ): Promise<string> {
-  return await Bun.password.hash(password, {
-    algorithm: params.algorithm,
-    memoryCost: params.memoryCost,
-    timeCost: params.timeCost,
-  });
+  return await kdfGate().run(
+    async () =>
+      await Bun.password.hash(password, {
+        algorithm: params.algorithm,
+        memoryCost: params.memoryCost,
+        timeCost: params.timeCost,
+      }),
+  );
 }
 
 /** Reads the parameters back out of a PHC string. `null` means "not a hash we recognise". */
@@ -90,12 +100,51 @@ export function needsRehash(
 }
 
 export interface VerifyPasswordInput {
-  /** `null` when no user matched. The KDF still runs, on a throwaway hash. */
+  /**
+   * `null` when no user matched. The KDF still runs, on a throwaway hash — and a stored hash Bun
+   * cannot read takes that same branch, so neither is separable from a wrong password.
+   */
   readonly hash: string | null;
   readonly password: string;
   readonly params?: PasswordParams | undefined;
 }
 
+/** The KDF the happy path would have burnt, then the one failure shape. Never a cheap answer. */
+async function burnAndFail(
+  password: string,
+  params: PasswordParams,
+): Promise<PasswordVerification> {
+  await hashPassword(password, params);
+  return FAILED;
+}
+
+/**
+ * `false` is a wrong password, `null` is a stored hash Bun cannot read at all.
+ *
+ * `Bun.password.verify` THROWS rather than answering on a hash it cannot parse — measured, bun
+ * 1.3.14: a Django `pbkdf2_sha256$...` row is `UnsupportedAlgorithm`, a truncated bcrypt string is
+ * `InvalidEncoding`. Letting that escape was two faults. A bare `Error` reached `login()`, so the
+ * caller answered 500 instead of the one credential failure; and it landed on exactly the rows
+ * that have not migrated off the legacy scheme, which makes "has this account been migrated" —
+ * and therefore "does this account exist" — readable from the outside. That is the enumeration
+ * oracle the whole file is built to close, on the one table where a foreign hash is normal.
+ *
+ * Supported-but-old is a different thing and stays a verdict: bcrypt verifies natively here and
+ * `needsRehash` flags it, which is the lever a legacy migration rewrites rows with.
+ *
+ * Nothing is logged. The algorithm of an unreadable hash is the oracle again, one layer down.
+ */
+async function verifyAgainst(password: string, hash: string): Promise<boolean | null> {
+  try {
+    return await kdfGate().run(async () => await Bun.password.verify(password, hash));
+  } catch (error) {
+    // The gate shedding (`X_OVERLOADED`) is load, never a verdict on the credential: swallowing it
+    // would answer "wrong password" for a request this process refused to do the work for.
+    if (error instanceof AuthError) throw error;
+    return null;
+  }
+}
+
 /**
  * Never short-circuits on a missing user: the `hashPassword` call in the `null` branch costs
  * the same order of magnitude as the verify in the happy branch, so the two are not separable
@@ -103,13 +152,16 @@ export interface VerifyPasswordInput {
  */
 export async function verifyPassword(input: VerifyPasswordInput): Promise<PasswordVerification> {
   const params = input.params ?? DEFAULT_PASSWORD_PARAMS;
-  if (input.hash === null) {
-    await hashPassword(input.password, params);
-    return FAILED;
-  }
-  const ok = await Bun.password.verify(input.password, input.hash);
+  // Read into a local so the two branches below narrow it without a cast.
+  const hash = input.hash;
+  // `''` joins the no-user branch rather than reaching the KDF: an account with no password
+  // credential (oauth-only) answers `false` from Bun for free, and a failure that costs nothing
+  // is a stopwatch away from "this address exists but has never set a password".
+  if (hash === null || hash === '') return await burnAndFail(input.password, params);
+  const ok = await verifyAgainst(input.password, hash);
+  if (ok === null) return await burnAndFail(input.password, params);
   if (!ok) return FAILED;
-  return { ok: true, needsRehash: needsRehash(input.hash, params) };
+  return { ok: true, needsRehash: needsRehash(hash, params) };
 }
 
 export interface StrengthOptions {

package/src/policy-bridge.ts

@@ -38,12 +38,18 @@ const withPermissions = (actor: Actor, permissions: readonly string[]): PolicyAc
 });
 
 /**
- * A human. Roles come from the row and are expanded to permissions by policy; scopes stay
- * empty because a browser session is not scope-limited — the role set is the limit.
+ * A human. Roles come from the row and are expanded to permissions by policy; scopes come from
+ * the row too, and they are almost always empty.
+ *
+ * `scopes: []` used to be hardcoded here, which made a scope a thing no human could ever hold —
+ * so `hasScope(actor, 'tenancy:cross')`, whose own reasons name "an admin surface listing every
+ * org" and "support tooling", could only ever be satisfied by minting a `serviceActor` inside the
+ * handler. That discards the operator's identity and makes the sweep unattributable, which is the
+ * exact property the scope's required reason string exists to preserve.
  *
  * A session that has not satisfied an enrolled second factor resolves to an actor with no
- * roles and no permissions rather than an error, so a half-authenticated request can still
- * reach the "finish MFA" route and nothing else. Login throws `X_MFA_REQUIRED` separately.
+ * roles, no permissions and no scopes rather than an error, so a half-authenticated request can
+ * still reach the "finish MFA" route and nothing else. Login throws `X_MFA_REQUIRED` separately.
  */
 export function actorFromUser(user: AuthUser, session: AuthSession): PolicyActor {
   const mfaPending = user.mfaSecret !== null && !session.mfaSatisfied;
@@ -52,7 +58,7 @@ export function actorFromUser(user: AuthUser, session: AuthSession): PolicyActor
       id: user.id,
       orgId: user.orgId ?? undefined,
       roles: mfaPending ? [] : user.roles,
-      scopes: [],
+      scopes: mfaPending ? [] : user.scopes,
     }),
     mfaPending ? [] : user.permissions,
   );

package/src/privileges.ts

@@ -0,0 +1,74 @@
+// Single responsibility: changing what a user may do, and rotating the credential that was issued
+// under the old answer. `packages/auth/CLAUDE.md` has listed "rotate the session id on any
+// privilege change (`rotateSession`)" as a non-negotiable since 1.0, and
+// `SessionPolicy.rotateOnPrivilegeChange` has defaulted `true` — while `rotateSession` had no
+// caller anywhere outside its own test and the flag was read by nothing. Per axiom 3 the rule did
+// not exist. This is the caller that makes it exist.
+
+import type { AuthUser, UserPatch } from './adapter';
+import type { Auth } from './auth';
+import { authWriteFailed } from './errors';
+import { type IssuedSession, rotateSession, sessionCookie } from './session';
+
+/**
+ * The fields whose change invalidates whatever the current cookie was issued under. `roles`,
+ * `permissions` and `scopes` are what an actor is built from; `passwordHash` is the credential
+ * itself; `orgId` moves every tenant-scoped read the session can perform.
+ */
+const PRIVILEGE_FIELDS = ['roles', 'permissions', 'scopes', 'orgId', 'passwordHash'] as const;
+
+export interface UpdatePrivilegesResult {
+  readonly user: AuthUser;
+  /**
+   * The replacement session, present only when a current session was passed AND a privilege field
+   * actually changed. Set `cookie` on the response — the old id is already deleted, so a caller
+   * that drops this signs the user out rather than leaving a stale-privilege cookie live.
+   */
+  readonly session?: IssuedSession | undefined;
+  readonly cookie?: string | undefined;
+  /** Which of `PRIVILEGE_FIELDS` the patch actually named. Empty means nothing rotated. */
+  readonly changed: readonly string[];
+}
+
+const changedFields = (patch: UserPatch): readonly string[] =>
+  PRIVILEGE_FIELDS.filter((field) => patch[field] !== undefined);
+
+/**
+ * Apply the patch, then mint a new session id for the caller's own session when the patch touched
+ * privilege. Rotation is not about propagation — `authenticate` re-reads the user row on every
+ * request, so a revoked role takes effect on the very next one with no token-expiry lag, which is
+ * a better property than any claims-in-a-JWT design. It is about fixation: whoever planted or
+ * lifted the old cookie before the grant must not inherit the grant with it.
+ *
+ * `session` is optional because the common caller is an admin changing somebody ELSE's roles, and
+ * there is no cookie of theirs to rotate. That case wants `revokeUserSessions()` instead, and the
+ * two are deliberately separate calls — silently killing an operator's own session mid-request is
+ * not something a role edit should decide on its own.
+ */
+export async function updatePrivileges(
+  auth: Auth,
+  userId: string,
+  patch: UserPatch,
+  session?: IssuedSession['session'] | undefined,
+): Promise<UpdatePrivilegesResult> {
+  const user = await auth.adapter.updateUser(userId, patch);
+  if (user === null) throw authWriteFailed('updateUser', 'x_users');
+
+  const changed = changedFields(patch);
+  if (
+    changed.length === 0 ||
+    session === undefined ||
+    session.userId !== userId ||
+    !auth.sessions.policy.rotateOnPrivilegeChange
+  ) {
+    return { user, changed };
+  }
+
+  const issued = await rotateSession(auth.sessions, session);
+  return {
+    user,
+    changed,
+    session: issued,
+    cookie: sessionCookie(issued.token, auth.sessions.policy),
+  };
+}