@ultimat3/auth 24.0.0 → 25.1.0

package/src/oauth-login.ts

@@ -3,7 +3,7 @@
 // matter which door the user came through. `completeOAuthLogin` is the blessed entry point;
 // the three steps under it are exported because a custom flow needs the seams, not a second path.
 
-import { ConfigInvalidError, logger, uuid } from '@ultimat3/core';
+import { ConfigInvalidError, logger, uuidV7 } from '@ultimat3/core';
 import type { AuthAccount, AuthUser } from './adapter';
 import type { Auth, LoginResult } from './auth';
 import { normaliseEmail } from './email';
@@ -18,7 +18,8 @@ import {
   type OAuthTokens,
   oauthCredentials,
 } from './oauth-exchange';
-import { type OAuthProfile, oauthProfile } from './oauth-profile';
+import { type OAuthGrantContext, oauthGrantContext } from './oauth-grant-context';
+import { type OAuthProfile, readOAuthProfile } from './oauth-profile';
 import { resolveActor } from './policy-bridge';
 import { loginFailed } from './rate-limit';
 import { createSession, sessionCookie } from './session';
@@ -65,7 +66,7 @@ export const emailVerifiedNotStored = (provider: string, userId: string): AuthEr
     // implements `updateUser` and lost a write it accepted.
     code: 'X_AUTH_WRITE_FAILED',
     cause: `the adapter returned no row for new user ${userId}, so the ${provider}-verified address was never stamped verified`,
-    fix: 'return the updated row from AuthAdapter.updateUser — MemoryAdapter.updateUser is the reference implementation',
+    fix: 'return the updated row from AuthAdapter.updateUser — MemoryAuthAdapter.updateUser is the reference implementation',
     meta: { provider, userId },
   });
 
@@ -89,8 +90,15 @@ export interface OAuthGrants {
   readonly externalId?: string | null | undefined;
 }
 
-/** Called once per callback, after the profile is proven and before the session is minted. */
-export type ResolveOAuthGrants = (profile: OAuthProfile) => Promise<OAuthGrants> | OAuthGrants;
+/**
+ * Called once per callback, after the profile is proven and before the session is minted. The
+ * `context` is what the IdP said beyond the profile — the token set, every id-token claim, and a
+ * lazy `userinfo()` — for an IdP that keeps its grants off the id token (#670).
+ */
+export type ResolveOAuthGrants = (
+  profile: OAuthProfile,
+  context: OAuthGrantContext,
+) => Promise<OAuthGrants> | OAuthGrants;
 
 export interface OAuthSignInInput {
   readonly profile: OAuthProfile;
@@ -149,7 +157,7 @@ async function applyGrants(auth: Auth, user: AuthUser, grants: OAuthGrants): Pro
  * display casing (`Ada@Example.com`) and change it between logins, and `x_users.email` is a plain
  * case-sensitive `unique` column — so unnormalised, the lookup below missed the account the user
  * registered and `createUserFor` minted a second one at the same address, which `login()` could
- * then never reach. `MemoryAdapter` used to fold case itself, which is why no test saw it.
+ * then never reach. `MemoryAuthAdapter` used to fold case itself, which is why no test saw it.
  */
 const profileEmail = (profile: OAuthProfile): string | null =>
   profile.email === null ? null : normaliseEmail(profile.email);
@@ -166,6 +174,12 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
       fix: `request the email scope for ${input.profile.provider} in beginOAuth(), then ${restartAt(input.profile.provider)}`,
     });
   }
+  // The provider did not vouch for the address, so this caller has proven nothing about owning
+  // it. Minting the account anyway is the pre-hijack: the real owner's `register()` then collides,
+  // their verified-provider login is refused as "never verified", and the attacker's identity stays
+  // linked to the row they later claim. Answered exactly as `resolveUser` answers the same
+  // unverified address when it IS taken, so the two branches are no oracle for "is it taken?".
+  if (!input.profile.emailVerified) throw loginFailed();
   const grants = input.grants ?? {};
   if ((grants.roles ?? []).length === 0 && (grants.orgId ?? null) === null) {
     // Not an error — an app may genuinely want a roleless account until somebody approves it —
@@ -177,7 +191,7 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
     });
   }
   const created = await auth.adapter.createUser({
-    id: uuid(auth.clock),
+    id: uuidV7(auth.clock),
     email,
     // An OAuth-only account has no password to store, and must never be given a random one:
     // a hash nobody knows the input to is still a credential a reset flow could hand over.
@@ -188,7 +202,6 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
     externalId: grants.externalId ?? null,
     createdAt: auth.clock.now(),
   });
-  if (!input.profile.emailVerified) return created;
   // `CreateUserInput` has no `emailVerifiedAt`, so the stamp is a required second write. Returning
   // `created` when it does not land would sign in a user whose row says unverified — and the next
   // login through this same provider would then refuse to link it at all.
@@ -199,7 +212,7 @@ async function createUserFor(auth: Auth, input: OAuthSignInInput): Promise<AuthU
 
 /**
  * Resolve the identity to a user: an already-linked account first, then an existing account
- * with the same address, then a fresh user.
+ * with the same address, then a fresh user — and a fresh user only for a provider-verified address.
  *
  * An address alone is not proof of ownership on either side. Attaching a provider identity to a
  * local account that never verified its own email hands the login to whoever registered that
@@ -236,7 +249,7 @@ async function resolveUser(
 
 function accountFor(auth: Auth, user: AuthUser, input: OAuthSignInInput): AuthAccount {
   return {
-    id: uuid(auth.clock),
+    id: uuidV7(auth.clock),
     userId: user.id,
     provider: input.profile.provider,
     providerAccountId: input.profile.providerAccountId,
@@ -327,11 +340,12 @@ export async function completeOAuthLogin(
     fetch: input.fetch,
     timeoutMs: input.timeoutMs,
   });
-  const profile = await oauthProfile(provider, tokens, {
-    fetch: input.fetch,
-    timeoutMs: input.timeoutMs,
-  });
-  const grants = input.resolveGrants === undefined ? undefined : await input.resolveGrants(profile);
+  const options = { fetch: input.fetch, timeoutMs: input.timeoutMs };
+  const { profile, userinfo } = await readOAuthProfile(provider, tokens, options);
+  const grants =
+    input.resolveGrants === undefined
+      ? undefined
+      : await input.resolveGrants(profile, oauthGrantContext(profile, tokens, options, userinfo));
   return await signInWithOAuth(auth, {
     profile,
     tokens,

package/src/oauth-profile.ts

@@ -133,11 +133,16 @@ async function githubPrimaryEmail(
   return verified.find((entry) => entry.primary) ?? verified[0] ?? null;
 }
 
-async function fromUserInfo(
+/**
+ * The provider's userinfo answer, whole: every claim, the ones `OAuthProfile` names and the ones it
+ * does not. Shared by the profile below and by `resolveGrants`' `userinfo()` (#670), so the two
+ * reads refuse the same three failures with the same codes — one endpoint, one reader.
+ */
+export async function userinfoBody(
   provider: OAuthProviderId,
   tokens: OAuthTokens,
   options: OAuthProfileOptions,
-): Promise<OAuthProfile> {
+): Promise<Record<string, unknown>> {
   const config = providerFor(provider);
   const url = config.userInfoUrl;
   if (url === null) {
@@ -167,12 +172,30 @@ async function fromUserInfo(
       fix: `confirm ${url} is the provider's real userinfo endpoint and not a proxy`,
     });
   }
+  return result.body;
+}
 
-  const body = result.body;
-  // GitHub's id is a number; OIDC's `sub` is a string. Both are stable, so both are accepted.
+/** GitHub's id is a number; OIDC's `sub` is a string. Both are stable, so both are accepted. */
+export function userinfoAccountId(body: Readonly<Record<string, unknown>>): string {
   const rawId = body['sub'] ?? body['id'];
-  const providerAccountId =
-    typeof rawId === 'number' ? String(rawId) : typeof rawId === 'string' ? rawId : '';
+  return typeof rawId === 'number' ? String(rawId) : typeof rawId === 'string' ? rawId : '';
+}
+
+/** A profile, and the userinfo body it was read from when it was read from one. */
+export interface OAuthProfileRead {
+  readonly profile: OAuthProfile;
+  /** `null` when the id token answered alone and no userinfo request was made. */
+  readonly userinfo: Record<string, unknown> | null;
+}
+
+async function fromUserInfo(
+  provider: OAuthProviderId,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions,
+): Promise<OAuthProfileRead> {
+  const config = providerFor(provider);
+  const body = await userinfoBody(provider, tokens, options);
+  const providerAccountId = userinfoAccountId(body);
   if (providerAccountId === '') {
     throw oauthExchangeFailed({
       provider,
@@ -193,13 +216,14 @@ async function fromUserInfo(
     }
   }
 
-  return {
+  const profile: OAuthProfile = {
     provider,
     providerAccountId,
     email,
     emailVerified,
     name: stringOrNull(body['name']) ?? stringOrNull(body['login']),
   };
+  return { profile, userinfo: body };
 }
 
 /**
@@ -212,17 +236,29 @@ export async function oauthProfile(
   tokens: OAuthTokens,
   options: OAuthProfileOptions = {},
 ): Promise<OAuthProfile> {
+  return (await readOAuthProfile(provider, tokens, options)).profile;
+}
+
+/**
+ * `oauthProfile`, keeping the userinfo body it fetched — so `resolveGrants`' `userinfo()` hands
+ * that body back instead of asking the provider a second time in the same login (#670).
+ */
+export async function readOAuthProfile(
+  provider: OAuthProviderId,
+  tokens: OAuthTokens,
+  options: OAuthProfileOptions = {},
+): Promise<OAuthProfileRead> {
   const claims = tokens.claims;
   if (claims === null) return await fromUserInfo(provider, tokens, options);
 
   const email = stringOrNull(claims.email);
   const userInfoUrl = providerFor(provider).userInfoUrl;
   if (email === null && userInfoUrl !== null) {
-    const profile = await fromUserInfo(provider, tokens, options);
+    const read = await fromUserInfo(provider, tokens, options);
     // Two surfaces, one identity — or this is not that identity. Overwriting the subject and
     // keeping the address would link the account on an address belonging to whoever the second
     // call described, so a disagreement ends the handshake instead of being reconciled.
-    if (profile.providerAccountId !== claims.sub) {
+    if (read.profile.providerAccountId !== claims.sub) {
       throw oauthExchangeFailed({
         provider,
         stage: 'userinfo',
@@ -230,14 +266,15 @@ export async function oauthProfile(
         fix: `confirm ${userInfoUrl} is ${provider}'s own userinfo endpoint and not a proxy that rewrites sub`,
       });
     }
-    return profile;
+    return read;
   }
 
-  return {
+  const profile: OAuthProfile = {
     provider,
     providerAccountId: claims.sub,
     email,
     emailVerified: email !== null && idTokenEmailVerified(claims),
     name: stringOrNull(claims.name),
   };
+  return { profile, userinfo: null };
 }

package/src/oauth.ts

@@ -4,9 +4,10 @@
 // configs are pure data and live in `oauth-registry.ts`: importing this file performs no network
 // I/O and reads no env.
 
+import { timingSafeEqual } from '@ultimat3/core';
 import { oauthStateInvalid } from './oauth-errors';
 import { providerFor } from './oauth-registry';
-import { base64Url, randomToken, sha256Bytes, timingSafeEqual } from './tokens';
+import { base64Url, randomToken, sha256Bytes } from './tokens';
 
 export interface OAuthProvider {
   readonly id: string;
@@ -63,7 +64,7 @@ export function pkceChallenge(verifier: string): string {
   return base64Url(sha256Bytes(verifier));
 }
 
-export function createPkce(): PkcePair {
+export function pkcePair(): PkcePair {
   // 32 random bytes -> 43 base64url chars, the RFC's minimum verifier length.
   const verifier = randomToken(32);
   return { verifier, challenge: pkceChallenge(verifier), method: 'S256' };
@@ -88,7 +89,7 @@ export interface BeginOAuthInput {
 
 export function beginOAuth(input: BeginOAuthInput): OAuthHandshake {
   const provider = providerFor(input.provider);
-  const pkce = createPkce();
+  const pkce = pkcePair();
   const state = randomToken(16);
   const nonce = randomToken(16);
   const url = new URL(provider.authorizeUrl);

package/src/policy-bridge.ts

@@ -5,7 +5,14 @@
 // import a same-tier package; policy binds to it by structure, in whichever order they land.
 
 import type { Actor } from '@ultimat3/core';
-import { agentActor, anonymousActor, assertNever, serviceActor, userActor } from '@ultimat3/core';
+import {
+  agentActor,
+  anonymousActor,
+  assertNever,
+  grantCovers,
+  serviceActor,
+  userActor,
+} from '@ultimat3/core';
 import type { AuthApiKeyRecord, AuthSession, AuthUser } from './adapter';
 
 /** Structural mirror of `@ultimat3/policy`'s `PolicyActorFields`. Kept in sync by hand. */
@@ -72,15 +79,6 @@ export function actorFromUser(user: AuthUser, session: AuthSession): PolicyActor
 /** `*` and `<resource>:*` — the two spellings a role uses to be granted everything. */
 export const isWildcardScope = (scope: string): boolean => scope === '*' || scope.endsWith(':*');
 
-// `@ultimat3/policy`'s own reading of a grant's resource, mirrored: same tier, so not imported.
-const resourceOf = (grant: string): string => grant.split(':')[0] ?? grant;
-
-/** Whether one of the owner's grants reaches a named permission. A grant MAY be a wildcard. */
-const covers = (grant: string, wanted: string): boolean =>
-  grant === '*' ||
-  grant === wanted ||
-  (grant.endsWith(':*') && resourceOf(grant) === resourceOf(wanted));
-
 /**
  * What a key may carry of what it names. Two cuts, and both only ever remove:
  *
@@ -99,7 +97,7 @@ export function apiKeyScopes(
   return scopes.filter(
     (scope) =>
       !isWildcardScope(scope) &&
-      (ownerGrants === null || ownerGrants.some((grant) => covers(grant, scope))),
+      (ownerGrants === null || ownerGrants.some((grant) => grantCovers(grant, scope))),
   );
 }
 

package/src/privileges.ts

@@ -5,7 +5,12 @@
 import type { AuthUser, UserPatch } from './adapter';
 import type { Auth } from './auth';
 import { authWriteFailed } from './errors';
-import { type IssuedSession, rotateSession, sessionCookie } from './session';
+import {
+  type IssuedSession,
+  remainingMaxAgeSeconds,
+  rotateSession,
+  sessionCookie,
+} from './session';
 
 /**
  * The fields whose change invalidates whatever the current cookie was issued under. `roles`,
@@ -63,17 +68,25 @@ export async function updatePrivileges(
   if (user === null) throw authWriteFailed('updateUser', 'x_users');
   if (changed.length === 0) return { user, changed, sessionsRevoked: 0 };
 
-  const issued =
-    own !== undefined && auth.sessions.policy.rotateOnPrivilegeChange
-      ? await rotateSession(auth.sessions, own)
-      : undefined;
+  // Every OTHER session ends BEFORE the rotation, keyed on the caller's current id (which the
+  // rotation deletes anyway). Rotation refuses a session that is already gone, and a password
+  // change must not leave the lifted cookies it was made to kill alive because of that refusal.
   let sessionsRevoked = 0;
   if (credentialChanged) {
-    const keep = issued?.session.id ?? own?.id;
     sessionsRevoked =
-      keep === undefined
+      own === undefined
         ? await auth.adapter.deleteSessionsForUser(userId)
-        : await auth.adapter.deleteOtherSessions(userId, keep);
+        : await auth.adapter.deleteOtherSessions(userId, own.id);
+  }
+  const issued =
+    own !== undefined && auth.sessions.policy.rotateOnPrivilegeChange
+      ? await rotateSession(auth.sessions, own)
+      : undefined;
+  // And once more AFTER it: a login that landed between the early sweep and the rotation was minted
+  // under the old password too. The early sweep stays — it is what still runs when rotation
+  // refuses a session that is already gone — and this one keeps only the replacement.
+  if (credentialChanged && own !== undefined) {
+    sessionsRevoked += await auth.adapter.deleteOtherSessions(userId, issued?.session.id ?? own.id);
   }
   if (issued === undefined) return { user, changed, sessionsRevoked };
   return {
@@ -81,6 +94,9 @@ export async function updatePrivileges(
     changed,
     sessionsRevoked,
     session: issued,
-    cookie: sessionCookie(issued.token, auth.sessions.policy),
+    // The rotated session keeps the old ceiling, so the cookie's `Max-Age` counts down to it too.
+    cookie: sessionCookie(issued.token, auth.sessions.policy, {
+      maxAgeSeconds: remainingMaxAgeSeconds(issued.session, auth.sessions.clock.now()),
+    }),
   };
 }

package/src/rate-limit.ts

@@ -109,14 +109,14 @@ export interface AuthLimiter {
   reset(): Promise<void>;
   /**
    * Drop every expired row this limiter is keeping, and answer how many went. Optional because a
-   * limiter that bounds itself has nothing to sweep — `createAuthLimiter` evicts on write, so it
+   * limiter that bounds itself has nothing to sweep — `memoryAuthLimiter` evicts on write, so it
    * omits this and `purgeAuthLimits()` skips it. A limiter backed by a table declares it, and
    * that is what makes the framework's purge job able to reach one without knowing it is Postgres.
    */
   purgeExpired?(): Promise<number>;
 }
 
-/** What `createAuthLimiter` returns: the interface, plus the bound it keeps, observable. */
+/** What `memoryAuthLimiter` returns: the interface, plus the bound it keeps, observable. */
 export interface MemoryAuthLimiter extends AuthLimiter {
   readonly size: number;
 }
@@ -174,7 +174,7 @@ const SWEEP_EVERY_MS = 60_000;
  * forgotten anyway go first: a locked account is the last key to go, so filling the table is not
  * a way to buy back attempts against one.
  */
-export function createAuthLimiter(
+export function memoryAuthLimiter(
   clock: Clock,
   policy: AuthRateLimitPolicy = DEFAULT_AUTH_RATE_LIMIT,
 ): MemoryAuthLimiter {

package/src/session.ts

@@ -5,11 +5,11 @@
 // to them without this package importing it (same-tier packages must not depend on each other).
 
 import type { Clock } from '@ultimat3/core';
-import { readCookie } from '@ultimat3/core';
+import { readCookie, serializeSetCookie, timingSafeEqual } from '@ultimat3/core';
 import type { AuthSession, SessionStore } from './adapter';
-import { sessionExpired, sessionUnknown } from './errors';
+import { AuthError, sessionExpired, sessionUnknown } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
-import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
+import { randomToken, sha256Hex } from './tokens';
 
 export interface SessionPolicy {
   /** Hard ceiling from creation. Never extended. */
@@ -92,8 +92,38 @@ export interface CreateSessionInput {
   readonly ip?: string | null | undefined;
   readonly userAgent?: string | null | undefined;
   readonly mfaSatisfied?: boolean | undefined;
+  /**
+   * The lifetime a rotation inherits. Absent means a new login: born now, ceiling one
+   * `absoluteTtlMs` away. Either way the ceiling is clamped to `createdAt + absoluteTtlMs` and
+   * `createdAt` to now, so an inherited value can only ever shorten a session — never buy it time.
+   */
+  readonly createdAt?: Date | undefined;
+  readonly absoluteExpiresAt?: Date | undefined;
 }
 
+/**
+ * An inherited instant that is not one. `X_CONFIG_INVALID`, core's code borrowed as
+ * `authPolicyNumberInvalid` borrows it: a caller handed this package a value it cannot honour. An
+ * Invalid Date ceiling is not a short session but one that never ends — `now >= NaN` is false.
+ */
+const inheritedInstantInvalid = (field: 'createdAt' | 'absoluteExpiresAt'): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause: `createSession({ ${field} }) is an Invalid Date, and stored as a ceiling it would never expire, because every comparison against NaN is false`,
+    fix: `createSession(runtime, { userId, createdAt: session.createdAt, absoluteExpiresAt: session.absoluteExpiresAt }) with the Dates read off a live session, or omit both for a new login`,
+    meta: { field },
+  });
+
+const inheritedMs = (
+  field: 'createdAt' | 'absoluteExpiresAt',
+  value: Date | undefined,
+): number | undefined => {
+  if (value === undefined) return undefined;
+  const ms = value.getTime();
+  if (!Number.isFinite(ms)) throw inheritedInstantInvalid(field);
+  return ms;
+};
+
 /** `<id>.<secret>`: the id is the row key, the secret is the half that is hashed. */
 export function parseSessionToken(token: string): { id: string; secret: string } | null {
   const dot = token.indexOf('.');
@@ -106,14 +136,20 @@ export async function createSession(
   input: CreateSessionInput,
 ): Promise<IssuedSession> {
   const now = runtime.clock.now();
+  // Screened ABOVE the write: `Math.min(NaN, …)` is NaN, so an Invalid Date stored a ceiling
+  // nothing ever reaches.
+  const inheritedBorn = inheritedMs('createdAt', input.createdAt);
+  const inheritedCeiling = inheritedMs('absoluteExpiresAt', input.absoluteExpiresAt);
   const id = randomToken(12);
   const secret = randomToken(32);
+  const born = Math.min(inheritedBorn ?? now.getTime(), now.getTime());
+  const ceiling = born + runtime.policy.absoluteTtlMs;
   const session = await runtime.store.createSession({
     id,
     userId: input.userId,
     tokenHash: sha256Hex(secret),
-    createdAt: now,
-    absoluteExpiresAt: new Date(now.getTime() + runtime.policy.absoluteTtlMs),
+    createdAt: new Date(born),
+    absoluteExpiresAt: new Date(Math.min(inheritedCeiling ?? ceiling, ceiling)),
     lastSeenAt: now,
     ip: input.ip ?? null,
     userAgent: input.userAgent ?? null,
@@ -184,21 +220,39 @@ export async function verifySession(
 /**
  * Privilege change (role grant, MFA satisfied, password change) must not reuse the old id:
  * whoever already holds the old cookie would inherit the new privileges.
+ *
+ * A new id, never a new lifetime: `createdAt` and the absolute ceiling carry over. Minting them
+ * fresh let a session rotated often enough (a weekly role toggle) live forever, and hid it from
+ * `revokeSessionsCreatedBefore` — the sweep run after a leak, keyed on exactly that column.
  */
 export async function rotateSession(
   runtime: SessionRuntime,
   session: AuthSession,
   patch?: { readonly mfaSatisfied?: boolean | undefined },
 ): Promise<IssuedSession> {
-  await runtime.store.deleteSession(session.id);
+  // The delete IS the claim, in one atomic step — the `consumeRecoveryCode` contract. Ignoring its
+  // answer resurrected a session revoked between verify and rotate, and let two concurrent
+  // rotations fork one session into two live ones. Only the caller whose delete landed mints S'.
+  if (!(await runtime.store.deleteSession(session.id))) throw sessionUnknown();
   return await createSession(runtime, {
     userId: session.userId,
     ip: session.ip,
     userAgent: session.userAgent,
     mfaSatisfied: patch?.mfaSatisfied ?? session.mfaSatisfied,
+    createdAt: session.createdAt,
+    absoluteExpiresAt: session.absoluteExpiresAt,
   });
 }
 
+/**
+ * `Max-Age` for a cookie carrying `session`: the seconds left until its absolute ceiling, never
+ * below zero. A rotated session's cookie needs this rather than the policy's full TTL, or the
+ * client keeps the cookie for weeks after the server stopped honouring it.
+ */
+export function remainingMaxAgeSeconds(session: AuthSession, now: Date): number {
+  return Math.max(0, Math.floor((session.absoluteExpiresAt.getTime() - now.getTime()) / 1000));
+}
+
 export async function revokeSession(runtime: SessionRuntime, sessionId: string): Promise<boolean> {
   return await runtime.store.deleteSession(sessionId);
 }
@@ -270,12 +324,16 @@ export function sessionCookie(
           'the cookie carries an attribute that is not delta-seconds, so the browser drops it and keeps the session cookie for the whole browsing session',
           0,
         );
-  return `${name}=${token}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`;
+  return serializeSetCookie(name, token, { maxAge });
 }
 
-/** Same attributes, empty value, `Max-Age=0` — a mismatched attribute set leaves a live twin. */
+/**
+ * Same attributes, empty value, `Max-Age=0` — a mismatched attribute set leaves a live twin. Both
+ * go through core's `serializeSetCookie`, whose defaults ARE `Path=/; HttpOnly; Secure;
+ * SameSite=Lax`, so the two lines cannot drift apart by one hand-edited attribute.
+ */
 export function clearSessionCookie(policy: SessionPolicy, name?: string): string {
-  return `${name ?? policy.cookieName}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+  return serializeSetCookie(name ?? policy.cookieName, '', { maxAge: 0 });
 }
 
 /**

package/src/tables.ts

@@ -1,4 +1,4 @@
-// Single responsibility: the DDL `BuiltinAdapter` expects, as `AUTH_TABLES` — applied at every boot
+// Single responsibility: the DDL `PostgresAuthAdapter` expects, as `AUTH_TABLES` — applied at every boot
 // by `@ultimat3/cli`'s `FRAMEWORK_SCHEMA`, upgrades of an older table included. Plain strings, so
 // what auth stores is verifiable by reading, never by trusting. There is nothing to paste into a
 // migration any more: the per-table exports and `X_USERS_MIGRATION_1_3` are gone (22.0.0).

package/src/tokens.ts

@@ -1,14 +1,11 @@
 // Single responsibility: the secret primitives every other file in this package shares —
 // CSPRNG tokens and SHA-256 hashing. Centralised so no call site can quietly reach for `===` on
 // a secret, which leaks the shared prefix length one request at a time. The constant-time
-// comparison itself lives in `@ultimat3/core` (`timingSafeEqual`) — `@ultimat3/storage` needs the
-// exact same one, and re-exporting it here keeps every existing `from '@ultimat3/auth'` import
-// working.
+// comparison itself is `@ultimat3/core`'s `timingSafeEqual` — `@ultimat3/storage` needs the exact
+// same one — imported from core by every caller, never re-exported here (`X_HELPER_COPY`).
 
 import { finiteCount, timingSafeEqual } from '@ultimat3/core';
 
-export { timingSafeEqual };
-
 const BASE64URL_UNSAFE = /[+/=]/g;
 const BASE64URL_REPLACEMENTS: Readonly<Record<string, string>> = { '+': '-', '/': '_', '=': '' };
 

package/src/verify.ts

@@ -4,11 +4,12 @@
 // tier 4 and auth is tier 2, so the app wires mail's `send` in and auth imports nothing upward.
 
 import type { Clock } from '@ultimat3/core';
+import { timingSafeEqual } from '@ultimat3/core';
 import type { AuthVerification, VerificationStore } from './adapter';
 import { normaliseEmail } from './email';
 import { AuthError } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
-import { randomToken, sha256Hex, timingSafeEqual } from './tokens';
+import { randomToken, sha256Hex } from './tokens';
 
 /**
  * `locale` is required, not optional: an inferred locale is how a user gets a security email