@ultimat3/auth 24.0.0 → 25.1.0

package/src/builtin-adapter.ts

@@ -117,13 +117,13 @@ const toApiKey = (row: Row): AuthApiKeyRecord => ({
  * assembled into dynamic SQL: `null` stays a meaningful value ("clear this field") and the
  * statement text remains constant, so the query plan is cached and nothing is interpolated.
  */
-export class BuiltinAdapter implements AuthAdapter {
+export class PostgresAuthAdapter implements AuthAdapter {
   readonly name = 'builtin-postgres';
   readonly #db: DbClient;
   readonly #clock: Clock;
 
   /**
-   * `clock` is the one `MemoryAdapter` takes, for the same stamp: hand over the clock
+   * `clock` is the one `MemoryAuthAdapter` takes, for the same stamp: hand over the clock
    * `defineAuth` was given, so a redemption is dated by the clock that judged its expiry.
    */
   constructor(client: DbClient = db(), clock: Clock = systemClock) {
@@ -237,7 +237,9 @@ export class BuiltinAdapter implements AuthAdapter {
    * One statement, and the two filters are conditional predicates rather than assembled SQL, for
    * the reason `updateUser`'s columns are: the statement text stays constant and nothing is
    * interpolated. Disabled members are excluded by default — an access review reads who can sign
-   * in today — and `includeDisabled` is what an offboarding audit passes.
+   * in today — and `includeDisabled` is what an offboarding audit passes. Ordered `collate "C"`
+   * (byte order, which `MemoryAuthAdapter` restates): the database default collation is the
+   * cluster's locale, so the order changed with the deployment and disagreed with memory's.
    */
   async listUsersByOrg(orgId: string, query?: UserQuery): Promise<readonly AuthUser[]> {
     const role = query?.role ?? null;
@@ -246,7 +248,7 @@ export class BuiltinAdapter implements AuthAdapter {
       where org_id = ${orgId}
         and (${query?.includeDisabled === true} or disabled_at is null)
         and (${role === null} or ${role} = any (roles))
-      order by email asc`);
+      order by email collate "C" asc`);
     return rows.map(toUser);
   }
 
@@ -422,3 +424,14 @@ export class BuiltinAdapter implements AuthAdapter {
     return changed > 0;
   }
 }
+
+/**
+ * The one way to build the Postgres adapter — the twin of `memoryAuthAdapter()`. The class is a
+ * type in the barrel only (`X_FACTORY_NAME_SPELLING`), so `new` is never a second spelling.
+ */
+export function postgresAuthAdapter(
+  client: DbClient = db(),
+  clock: Clock = systemClock,
+): PostgresAuthAdapter {
+  return new PostgresAuthAdapter(client, clock);
+}

package/src/email.ts

@@ -1,7 +1,7 @@
 // Single responsibility: the ONE normalisation an email address gets before anything uses it as an
 // identity key — a user lookup, a user insert, or the lockout bucket that has to key the same way
 // those two do. It lives above the `AuthAdapter` seam because an adapter that normalises hides a
-// caller that forgot to: `MemoryAdapter` did and `BuiltinAdapter` did not, so "does this account
+// caller that forgot to: `MemoryAuthAdapter` did and `PostgresAuthAdapter` did not, so "does this account
 // exist" had two answers, one under `x dev` and another in production.
 
 /**

package/src/errors.ts

@@ -117,14 +117,14 @@ export class AuthError extends UltimateError {
  * `authenticate()` returns the anonymous actor for a missing cookie rather than throwing, which
  * is correct — and is exactly why the failure surfaces here, one layer later, instead of there.
  */
-export const unauthenticated = (surface: string): AuthError =>
+export const authUnauthenticated = (surface: string): AuthError =>
   new AuthError({
     code: 'X_UNAUTHENTICATED',
     cause: `${surface} needs an actor but ctx.actor is anonymous`,
     fix: 'send the __Host-x_session cookie with this request, and resolve it once at the boundary: authenticate(auth, readSessionCookie(request, auth.sessions.policy))',
   });
 
-export const forbidden = (surface: string, reason: string): AuthError =>
+export const authForbidden = (surface: string, reason: string): AuthError =>
   new AuthError({
     code: 'X_FORBIDDEN',
     cause: `${surface} denied: ${reason}`,
@@ -372,7 +372,7 @@ export const authWriteFailed = (operation: string, table: string): AuthError =>
  * the same failure to an operator — the row is not there and the caller must not assume it is —
  * and the cause says which of the two happened.
  *
- * `MemoryAdapter` enforced neither `x_users.email` nor `x_users.external_id`, while `BuiltinAdapter`
+ * `MemoryAuthAdapter` enforced neither `x_users.email` nor `x_users.external_id`, while `PostgresAuthAdapter`
  * leans on both: two `register()` calls at one address made TWO rows in memory, and the second was
  * unreachable forever because `findUserByEmail` returns the first. That adapter is what `x new`
  * scaffolds and what every test runs against, so the duplicate path was only exercised against the

package/src/guards.ts

@@ -5,14 +5,14 @@
 
 import type { Actor } from '@ultimat3/core';
 import { isAnonymous, useContext } from '@ultimat3/core';
-import { unauthenticated } from './errors';
+import { authUnauthenticated } from './errors';
 
 const DEFAULT_SURFACE = 'this request';
 
 /** Throws `X_UNAUTHENTICATED` when the ambient actor is anonymous. */
 export function requireActor(surface: string = DEFAULT_SURFACE): Actor {
   const { actor } = useContext();
-  if (isAnonymous(actor)) throw unauthenticated(surface);
+  if (isAnonymous(actor)) throw authUnauthenticated(surface);
   return actor;
 }
 

package/src/id-token.ts

@@ -6,13 +6,12 @@
 // default is what silently makes the second door as trusting as the first.
 
 import type { Clock } from '@ultimat3/core';
-import { renderCauseValue } from '@ultimat3/core';
+import { renderCauseValue, timingSafeEqual } from '@ultimat3/core';
 import { decodeJwtSegment } from './json';
 import { type IdTokenKeys, verifyJwtSignature } from './jwks';
 import type { OAuthProvider, OAuthProviderId } from './oauth';
 import { oauthStateInvalid, oauthTokenInvalid, restartAt } from './oauth-errors';
 import { providerFor } from './oauth-registry';
-import { timingSafeEqual } from './tokens';
 
 /** The subset of OIDC claims this package acts on. Provider-specific extras are ignored. */
 export interface IdTokenClaims {
@@ -128,7 +127,7 @@ export interface VerifyIdTokenInput {
    * Required, and there is deliberately no default. `'token-endpoint-tls'` asserts this token was
    * read off a TLS response from the provider's own token endpoint — the OIDC Core 3.1.3.7 case,
    * and the only one where an unverified JWT is safe. Every other channel passes a key source:
-   * `providerJwks(providerFor(id))`, or a `createJwksClient({ jwksUri })` of its own.
+   * `providerJwks(providerFor(id))`, or a `jwksClient({ jwksUri })` of its own.
    */
   readonly keys: IdTokenKeys;
 }

package/src/index.ts

@@ -61,7 +61,7 @@ export {
   UserSchema,
   VerificationSchema,
 } from './auth';
-export { BuiltinAdapter } from './builtin-adapter';
+export { type PostgresAuthAdapter, postgresAuthAdapter } from './builtin-adapter';
 /** The opaque per-principal id a per-request document hands the page's client store. */
 export type { ClientScopeOptions } from './client-scope';
 export { clientScopeOf } from './client-scope';
@@ -78,11 +78,12 @@ export {
   AuthError,
   accountLocked,
   apiKeyInvalid,
+  authForbidden,
   authLimiterNotShared,
   authLimiterPolicyMismatch,
+  authUnauthenticated,
   authUniqueViolation,
   authWriteFailed,
-  forbidden,
   kdfOverloaded,
   mfaRequiredUnenforceable,
   mfaSecretInvalid,
@@ -90,7 +91,6 @@ export {
   passwordWeak,
   sessionExpired,
   sessionUnknown,
-  unauthenticated,
 } from './errors';
 export { currentActor, requireActor } from './guards';
 export type { IdTokenClaims, VerifyIdTokenInput } from './id-token';
@@ -108,22 +108,22 @@ export type {
   JwtHeader,
 } from './jwks';
 export {
-  createJwksClient,
   decodeJwtHeader,
+  jwksClient,
   providerJwks,
   verifyJwtSignature,
 } from './jwks';
 export type { KdfGate, KdfLimits } from './kdf-gate';
 export {
+  boundedKdfGate,
   configureKdfGate,
-  createKdfGate,
   kdfGate,
 } from './kdf-gate';
 export type { AuthLimiterFactory } from './limiter-install';
 // `installedAuthLimiter` is deliberately absent: `defineAuth` is the one reader, and a second
 // caller building limiters out of band would be a second answer to where failures are counted.
 export { configureAuthLimiters, purgeAuthLimits, resetAuthLimiters } from './limiter-install';
-export { MemoryAdapter } from './memory-adapter';
+export { type MemoryAuthAdapter, memoryAuthAdapter } from './memory-adapter';
 export type {
   EnrolTotpInput,
   MemoryTotpReplayGuard,
@@ -136,11 +136,11 @@ export type {
 export {
   base32Decode,
   base32Encode,
-  createTotpReplayGuard,
   DEFAULT_MAX_TOTP_SUBJECTS,
   enrolTotp,
   generateRecoveryCodes,
   generateTotpSecret,
+  memoryTotpReplayGuard,
   recoveryCodeHash,
   TOTP_DIGITS,
   TOTP_DRIFT_STEPS,
@@ -174,7 +174,7 @@ export type {
   OAuthProviderId,
   PkcePair,
 } from './oauth';
-export { assertOAuthCallback, beginOAuth, createPkce } from './oauth';
+export { assertOAuthCallback, beginOAuth, pkcePair } from './oauth';
 export {
   APPLE_PROVIDER,
   BUILTIN_OAUTH_PROVIDER_IDS,
@@ -212,6 +212,7 @@ export type {
   OAuthTokens,
 } from './oauth-exchange';
 export { exchangeOAuthCode, oauthCredentials } from './oauth-exchange';
+export type { OAuthGrantContext } from './oauth-grant-context';
 export type {
   CompleteOAuthLoginInput,
   OAuthGrants,
@@ -284,11 +285,11 @@ export type {
 export {
   accountKey,
   assertAuthLimiterPolicy,
-  createAuthLimiter,
   DEFAULT_AUTH_RATE_LIMIT,
   DEFAULT_MAX_AUTH_LIMIT_KEYS,
   ipKey,
   loginFailed,
+  memoryAuthLimiter,
   orgKey,
   orgRateLimit,
 } from './rate-limit';
@@ -323,6 +324,7 @@ export {
   idleSlideMs,
   listDevices,
   readSessionCookie,
+  remainingMaxAgeSeconds,
   revokeOtherSessions,
   revokeSession,
   rotateSession,
@@ -341,7 +343,6 @@ export {
 export {
   randomToken,
   sha256Hex,
-  timingSafeEqual,
 } from './tokens';
 export type {
   ConsumeVerificationInput,

package/src/jwks.ts

@@ -8,11 +8,11 @@
 
 import type { Clock, Scheduler } from '@ultimat3/core';
 import {
-  createFence,
-  createSingleFlight,
+  generationFence,
   isFixShellSafe,
   renderFixShellArg,
   renderThrowable,
+  singleFlight,
   systemClock,
 } from '@ultimat3/core';
 import { decodeJwtSegment, isRecord } from './json';
@@ -117,7 +117,7 @@ const algorithmOf = (jwk: Record<string, unknown>): JwtAlgorithm | null => {
  * become an unbounded outbound request per attempt, so the refresh is rate-limited by the same
  * TTL as the ordinary one.
  */
-export function createJwksClient(options: JwksClientOptions): JwksKeySource {
+export function jwksClient(options: JwksClientOptions): JwksKeySource {
   const clock = options.clock ?? systemClock;
   const ttlMs = options.ttlMs ?? DEFAULT_JWKS_TTL_MS;
   assertFiniteAuthCount(
@@ -144,7 +144,7 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
   // already gave up on could drop a pre-rotation key set on top of the live one, and every login
   // against the new `kid` would start missing again. Read, never `guard`: a superseded refresh is
   // still the honest answer for the callers holding it, and only the shared cache is fenced.
-  const fence = createFence('the published jwks key set');
+  const fence = generationFence('the published jwks key set');
   // All three refusals below put this URI in a COMMAND position, and it came out of the ISSUER's
   // own discovery document — `jwks_uri` is remote text, and `new URL()` keeps `$`, `(`, `)` and a
   // backtick in a path. `renderFixLiteral` is the wrong tool here, because its double quotes leave
@@ -235,7 +235,7 @@ export function createJwksClient(options: JwksClientOptions): JwksKeySource {
   // running, its own callers keep their promise, and the fence above stops its late answer from
   // landing in the cache. So the worst case is one duplicate JWKS fetch, never a failed
   // verification — which is what makes a deadline here a fix rather than a risk.
-  const flight = createSingleFlight({
+  const flight = singleFlight({
     deadlineMs: timeoutMs * JWKS_DEADLINE_FACTOR,
     schedule: options.schedule,
   });
@@ -295,7 +295,7 @@ const clients = new Map<string, JwksKeySource>();
  *
  * Not cached by option identity, deliberately: `fetch` and `clock` are functions and objects, so
  * any canonical key over them either collides (two different proxies, one entry) or never hits.
- * A bespoke client is a bespoke client; `createJwksClient` is what it is, and its own cache still
+ * A bespoke client is a bespoke client; `jwksClient` is what it is, and its own cache still
  * works for as long as the caller holds it.
  */
 export function providerJwks(
@@ -312,7 +312,7 @@ export function providerJwks(
   const bespoke = options !== undefined && Object.keys(options).length > 0;
   const existing = bespoke ? undefined : clients.get(provider.id);
   if (existing !== undefined) return existing;
-  const client = createJwksClient({ ...options, provider: provider.id, jwksUri: provider.jwksUri });
+  const client = jwksClient({ ...options, provider: provider.id, jwksUri: provider.jwksUri });
   if (!bespoke) clients.set(provider.id, client);
   return client;
 }

package/src/kdf-gate.ts

@@ -6,7 +6,7 @@
 // what argon2id costs is MEMORY — 19 MiB per hash at the OWASP floor. The only remaining backstop
 // was `http.maxInflight` (1000), i.e. roughly 19 GB of arenas queued on one box.
 
-import { createFlightGate } from '@ultimat3/core';
+import { flightGate } from '@ultimat3/core';
 import { kdfOverloaded } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
 
@@ -43,7 +43,7 @@ export interface KdfGate {
  * The declared return type stays `KdfGate` rather than core's `FlightGate`: `active` and `queued`
  * are observations no caller here has ever had, and widening a public signature is not a refactor.
  */
-export function createKdfGate(limits: KdfLimits = DEFAULT_KDF_LIMITS): KdfGate {
+export function boundedKdfGate(limits: KdfLimits = DEFAULT_KDF_LIMITS): KdfGate {
   // Screened at the CONSTRUCTOR, because this pair WEDGES rather than fails: core asks
   // `active < maxConcurrent` and then `waiters.length >= maxQueued`, and both are false for `NaN`,
   // so every hash on the box parks in a queue with no bound and nothing to release it — login
@@ -66,12 +66,12 @@ export function createKdfGate(limits: KdfLimits = DEFAULT_KDF_LIMITS): KdfGate {
     '`waiters.length >= NaN` is false, so the queue this gate exists to bound has no bound at all',
     0,
   );
-  return createFlightGate(limits, {
+  return flightGate(limits, {
     overflow: (state) => kdfOverloaded(state.active, state.queued),
   });
 }
 
-let gate = createKdfGate();
+let gate = boundedKdfGate();
 
 /** The process-wide gate every `hashPassword`/`verifyPassword` passes through. */
 export const kdfGate = (): KdfGate => gate;
@@ -83,10 +83,10 @@ export const kdfGate = (): KdfGate => gate;
  * runs on a 512 MiB PaaS dyno and a 64 GiB node.
  */
 export function configureKdfGate(limits: KdfLimits): void {
-  gate = createKdfGate(limits);
+  gate = boundedKdfGate(limits);
 }
 
 /** Back to the shipped defaults. Tests that call `configureKdfGate` must call this in cleanup. */
 export function resetKdfGate(): void {
-  gate = createKdfGate();
+  gate = boundedKdfGate();
 }

package/src/limiter-install.ts

@@ -52,7 +52,7 @@ export function configureAuthLimiters(next: AuthLimiterFactory): void {
   built = new Map();
 }
 
-/** Back to `createAuthLimiter`, the per-process default. A host that installs one calls this on stop. */
+/** Back to `memoryAuthLimiter`, the per-process default. A host that installs one calls this on stop. */
 export function resetAuthLimiters(): void {
   factory = undefined;
   built = new Map();

package/src/memory-adapter.ts

@@ -2,7 +2,7 @@
 // database exists and the one every test in this package runs against — the same interface
 // Postgres and Better Auth implement, so a flow that works here works there or the seam is wrong.
 
-import { type Clock, systemClock } from '@ultimat3/core';
+import { type Clock, systemClock, timingSafeEqual } from '@ultimat3/core';
 import type {
   AuthAccount,
   AuthAdapter,
@@ -17,11 +17,28 @@ import type {
   UserQuery,
 } from './adapter';
 import { authUniqueViolation } from './errors';
-import { timingSafeEqual } from './tokens';
 
 const verificationKey = (purpose: string, identifier: string): string => `${purpose}:${identifier}`;
 
-export class MemoryAdapter implements AuthAdapter {
+/**
+ * `PostgresAuthAdapter`'s `order by email collate "C"`: byte order over UTF-8, which is CODE-POINT order
+ * — never `localeCompare` (the machine's locale) and never `<` on strings, whose UTF-16 code units
+ * put an astral character (a lead surrogate, 0xD8xx) ahead of U+E000–U+FFFF.
+ */
+const byCodePoint = (a: string, b: string): number => {
+  const left = a[Symbol.iterator]();
+  const right = b[Symbol.iterator]();
+  for (;;) {
+    const x = left.next();
+    const y = right.next();
+    if (x.done === true || y.done === true)
+      return (x.done === true ? 0 : 1) - (y.done === true ? 0 : 1);
+    const delta = (x.value.codePointAt(0) ?? 0) - (y.value.codePointAt(0) ?? 0);
+    if (delta !== 0) return delta;
+  }
+};
+
+export class MemoryAuthAdapter implements AuthAdapter {
   readonly name = 'memory';
   readonly #clock: Clock;
   readonly #users = new Map<string, AuthUser>();
@@ -33,14 +50,14 @@ export class MemoryAdapter implements AuthAdapter {
   /**
    * The clock every instant this adapter stamps comes from — one argument, because a stamp is a
    * fact about WHEN a call happened and a test that cannot move it can only assert a range.
-   * Defaults to `systemClock`, so `new MemoryAdapter()` is what it always was.
+   * Defaults to `systemClock`, so `memoryAuthAdapter()` is what it always was.
    */
   constructor(clock: Clock = systemClock) {
     this.#clock = clock;
   }
 
   /**
-   * Exact match, because `BuiltinAdapter` issues `where email = $1` against a plain `text ...
+   * Exact match, because `PostgresAuthAdapter` issues `where email = $1` against a plain `text ...
    * unique` column and nothing folds case there. Normalising here instead made this the ONE
    * adapter that found an account Postgres would not, which is a linked account under `x dev` and
    * a duplicate one in production. `normaliseEmail` is the caller's, above the seam.
@@ -57,7 +74,7 @@ export class MemoryAdapter implements AuthAdapter {
   }
 
   /**
-   * The two UNIQUE constraints `x_users` declares, enforced here because `BuiltinAdapter` LEANS on
+   * The two UNIQUE constraints `x_users` declares, enforced here because `PostgresAuthAdapter` LEANS on
    * them: `email text not null unique` and `external_id text unique` (`tables.ts`). Without them
    * this adapter — the one `x new` scaffolds and every test runs against — accepted two rows at one
    * address, and the second was unreachable forever, since `findUserByEmail` returns the first.
@@ -178,7 +195,7 @@ export class MemoryAdapter implements AuthAdapter {
       .filter((user) => user.orgId === orgId)
       .filter((user) => query?.includeDisabled === true || user.disabledAt === null)
       .filter((user) => query?.role === undefined || user.roles.includes(query.role))
-      .sort((a, b) => a.email.localeCompare(b.email));
+      .sort((a, b) => byCodePoint(a.email, b.email));
   }
 
   async getSession(id: string): Promise<AuthSession | null> {
@@ -330,3 +347,11 @@ export class MemoryAdapter implements AuthAdapter {
     return true;
   }
 }
+
+/**
+ * The one way to build the in-memory adapter — the twin of `postgresAuthAdapter()`. The class is a
+ * type in the barrel only (`X_FACTORY_NAME_SPELLING`), so `new` is never a second spelling.
+ */
+export function memoryAuthAdapter(clock: Clock = systemClock): MemoryAuthAdapter {
+  return new MemoryAuthAdapter(clock);
+}

package/src/mfa.ts

@@ -4,11 +4,11 @@
 // and single-use, so a database dump is not a permanent MFA bypass; consuming one is the
 // adapter's (`consumeRecoveryCode`), because single-use has to be one atomic step.
 
-import { finiteCount } from '@ultimat3/core';
+import { finiteCount, timingSafeEqual } from '@ultimat3/core';
 import type { Auth } from './auth';
 import { mfaSecretInvalid } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
-import { randomBytes, sha256Hex, timingSafeEqual } from './tokens';
+import { randomBytes, sha256Hex } from './tokens';
 
 const BASE32_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
 
@@ -196,7 +196,7 @@ export interface TotpReplayGuard {
   remember(subject: string, step: number, at: Date): void;
 }
 
-/** What `createTotpReplayGuard` returns: the interface, plus the bound it keeps, observable. */
+/** What `memoryTotpReplayGuard` returns: the interface, plus the bound it keeps, observable. */
 export interface MemoryTotpReplayGuard extends TotpReplayGuard {
   readonly size: number;
 }
@@ -245,9 +245,9 @@ const newestStep = (steps: ReadonlySet<number>): number => {
  * is *forgotten*, not evicted: `verifyTotp` only ever offers a step within ±drift of now, so that
  * entry answers exactly as a missing one and dropping it changes no decision. Only if forgetting
  * is not enough does the cap evict live state, furthest from the live window first — the shape
- * `createAuthLimiter` evicts by, where a live lockout is the last bucket to go.
+ * `memoryAuthLimiter` evicts by, where a live lockout is the last bucket to go.
  */
-export function createTotpReplayGuard(
+export function memoryTotpReplayGuard(
   drift: number = TOTP_DRIFT_STEPS,
   maxSubjects: number = DEFAULT_MAX_TOTP_SUBJECTS,
 ): MemoryTotpReplayGuard {

package/src/oauth-cookie.ts

@@ -6,13 +6,19 @@
 // format at one trust level.
 
 import type { Clock } from '@ultimat3/core';
-import { EnvMissingError, readCookie, systemClock } from '@ultimat3/core';
+import {
+  EnvMissingError,
+  readCookie,
+  serializeSetCookie,
+  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, timingSafeEqual } from './tokens';
+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';
@@ -189,7 +195,7 @@ export function handshakeCookie(
   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 `${name}=${sealHandshake(handshake, options)}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
+  return serializeSetCookie(name, sealHandshake(handshake, options), { maxAge });
 }
 
 /**
@@ -200,7 +206,7 @@ export function handshakeCookie(
  * clear nothing, and clearing every provider's would cancel a login running in another tab.
  */
 export function clearHandshakeCookie(provider: OAuthProviderId, name?: string): string {
-  return `${name ?? handshakeCookieName(provider)}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+  return serializeSetCookie(name ?? handshakeCookieName(provider), '', { maxAge: 0 });
 }
 
 /** Reads the cookie set on the redirect and returns the handshake `completeOAuthLogin` takes. */

package/src/oauth-grant-context.ts

@@ -0,0 +1,106 @@
+// Single responsibility: what `resolveGrants` may read besides the profile (#670). An IdP is free
+// to put authorization facts — groups, entitlements, `allowed_oauth_apps` — on `/userinfo` only,
+// or in an id-token claim `OAuthProfile` does not name; a seam that sees the profile alone refuses
+// a correctly granted user. The token set, the whole verified payload, and a lazy userinfo read.
+
+import { renderFixLiteral } from '@ultimat3/core';
+import { decodeJwtSegment } from './json';
+import type { OAuthProviderId } from './oauth';
+import { oauthExchangeFailed } from './oauth-errors';
+import type { OAuthTokens } from './oauth-exchange';
+import { oauthStartPath } from './oauth-paths';
+import {
+  type OAuthProfile,
+  type OAuthProfileOptions,
+  userinfoAccountId,
+  userinfoBody,
+} from './oauth-profile';
+import { providerFor } from './oauth-registry';
+
+/** The second argument of `resolveGrants`. Read-only, and alive for one callback only. */
+export interface OAuthGrantContext {
+  readonly provider: OAuthProviderId;
+  /**
+   * The exchange's token set, in flight. The framework persists none of it (`accountFor` writes
+   * `null`), so an app that keeps a token past this call has chosen to store a credential.
+   */
+  readonly tokens: OAuthTokens;
+  /**
+   * Every claim of the id token the exchange VERIFIED — custom ones (`hd`, `groups`) included,
+   * which `tokens.claims` drops. `null` when the provider issued no id token.
+   */
+  readonly idTokenClaims: Readonly<Record<string, unknown>> | null;
+  /**
+   * The provider's userinfo answer, every claim, read with the access token. At most one request
+   * per login, however often it is asked: none at all when the profile was already read off
+   * userinfo (GitHub), whose body is handed back; a failed read is not remembered.
+   * A body naming another subject is `X_OAUTH_EXCHANGE_FAILED` — the same rule `oauthProfile`
+   * applies, so a grant can never be read off somebody else's identity.
+   */
+  userinfo(): Promise<Readonly<Record<string, unknown>>>;
+}
+
+/** The verified token's payload, whole. Its signature, `iss`, `aud` and `exp` were checked already. */
+function fullPayload(tokens: OAuthTokens): Readonly<Record<string, unknown>> | null {
+  if (tokens.claims === null || tokens.idToken === null) return null;
+  const payload = decodeJwtSegment(tokens.idToken.split('.')[1] ?? '');
+  return payload === null ? null : Object.freeze(payload);
+}
+
+async function readUserinfo(
+  profile: OAuthProfile,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions,
+): Promise<Readonly<Record<string, unknown>>> {
+  const { provider } = profile;
+  // Asked before `userinfoBody`, whose own refusal for this case speaks of a missing identity:
+  // here the identity is proven, and what is missing is the endpoint the app's rule reads.
+  if (providerFor(provider).userInfoUrl === null) {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'userinfo',
+      detail: `${provider} publishes no userinfo endpoint, so resolveGrants cannot read one`,
+      fix: `resolveGrants: (profile, { idTokenClaims }) => grantsFrom(idTokenClaims)   # ${provider} puts its claims in the id token, never behind context.userinfo()`,
+    });
+  }
+  const body = await userinfoBody(provider, tokens, options);
+  if (userinfoAccountId(body) !== profile.providerAccountId) {
+    throw oauthExchangeFailed({
+      provider,
+      stage: 'userinfo',
+      detail: 'the userinfo subject is not the subject of the identity being signed in',
+      fix: `registerOAuthProvider({ id: ${renderFixLiteral(provider, '<id>')}, userInfoUrl: '<the provider's own userinfo endpoint>', … })   # a proxy that rewrites sub is refused; then restart at ${oauthStartPath(provider)}`,
+    });
+  }
+  return Object.freeze(body);
+}
+
+/**
+ * Built once per callback, after the profile is proven and before `resolveGrants` runs. `fetched`
+ * is the userinfo body the profile read already made, if it made one — its subject IS the profile's.
+ */
+export function oauthGrantContext(
+  profile: OAuthProfile,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions,
+  fetched: Record<string, unknown> | null = null,
+): OAuthGrantContext {
+  let pending: Promise<Readonly<Record<string, unknown>>> | undefined =
+    fetched === null ? undefined : Promise.resolve(Object.freeze(fetched));
+  return Object.freeze({
+    provider: profile.provider,
+    tokens,
+    idTokenClaims: fullPayload(tokens),
+    userinfo() {
+      if (pending === undefined) {
+        const read = readUserinfo(profile, tokens, options);
+        pending = read;
+        // Forget a failure, so a seam that retries asks the provider again rather than the cache.
+        read.catch(() => {
+          if (pending === read) pending = undefined;
+        });
+      }
+      return pending;
+    },
+  });
+}