@ultimat3/auth 23.0.0 → 25.0.0

package/src/builtin-adapter.ts

@@ -3,6 +3,7 @@
 // drive it without a database. Rows arrive as `unknown` and are read through the small typed
 // readers below — no `any`, and a column rename fails loudly instead of producing `undefined`.
 
+import { type Clock, systemClock } from '@ultimat3/core';
 import { type DbClient, db, sql } from '@ultimat3/db';
 import type {
   AuthAccount,
@@ -13,9 +14,11 @@ import type {
   AuthVerification,
   CreateUserInput,
   SessionPatch,
+  StoredMfaSecret,
   UserPatch,
   UserQuery,
 } from './adapter';
+import { usersUniqueViolation } from './builtin-adapter-violation';
 import { authWriteFailed } from './errors';
 
 type Row = Readonly<Record<string, unknown>>;
@@ -114,12 +117,27 @@ 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;
 
-  constructor(client: DbClient = db()) {
+  /**
+   * `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) {
     this.#db = client;
+    this.#clock = clock;
+  }
+
+  /** A write to `x_users`, with the table's own unique violations answered as this package's. */
+  async #writeUser(operation: string, statement: Parameters<DbClient['one']>[0]) {
+    try {
+      return await this.#db.one<Row>(statement);
+    } catch (error) {
+      throw usersUniqueViolation(operation, error) ?? error;
+    }
   }
 
   async findUserByEmail(email: string): Promise<AuthUser | null> {
@@ -133,13 +151,16 @@ export class BuiltinAdapter implements AuthAdapter {
   }
 
   async createUser(input: CreateUserInput): Promise<AuthUser> {
-    const row = await this.#db.one<Row>(sql`
+    const row = await this.#writeUser(
+      'createUser',
+      sql`
       insert into x_users (id, email, password_hash, org_id, roles, scopes, external_id,
                            created_at)
       values (${input.id}, ${input.email}, ${input.passwordHash}, ${input.orgId},
               ${[...input.roles]}, ${[...(input.scopes ?? [])]}, ${input.externalId ?? null},
               ${input.createdAt})
-      returning *`);
+      returning *`,
+    );
     // An empty `returning` means no row landed. A user fabricated from `{}` would travel back
     // out of `register()` as a successful registration with no identity in it.
     if (row === null) throw authWriteFailed('createUser', 'x_users');
@@ -147,7 +168,9 @@ export class BuiltinAdapter implements AuthAdapter {
   }
 
   async updateUser(id: string, patch: UserPatch): Promise<AuthUser | null> {
-    const row = await this.#db.one<Row>(sql`
+    const row = await this.#writeUser(
+      'updateUser',
+      sql`
       update x_users set
         password_hash = case when ${patch.passwordHash !== undefined}
           then ${patch.passwordHash ?? null} else password_hash end,
@@ -170,10 +193,39 @@ export class BuiltinAdapter implements AuthAdapter {
         external_id = case when ${patch.externalId !== undefined}
           then ${patch.externalId ?? null} else external_id end
       where id = ${id}
-      returning *`);
+      returning *`,
+    );
     return row === null ? null : toUser(row);
   }
 
+  async listUsersWithMfaSecret(): Promise<readonly StoredMfaSecret[]> {
+    const rows = await this.#db.query<Row>(
+      sql`select id, mfa_secret from x_users where mfa_secret is not null order by id`,
+    );
+    return rows.map((row) => ({ userId: text(row, 'id'), mfaSecret: text(row, 'mfa_secret') }));
+  }
+
+  async replaceMfaSecret(userId: string, expected: string, next: string): Promise<boolean> {
+    const row = await this.#db.one<Row>(sql`
+      update x_users set mfa_secret = ${next}
+       where id = ${userId} and mfa_secret = ${expected}
+      returning id`);
+    return row !== null;
+  }
+
+  /**
+   * One conditional UPDATE: the row is locked, and the `where` is re-checked against the version
+   * a concurrent redemption just committed, so the second of two finds the hash already gone.
+   */
+  async consumeRecoveryCode(userId: string, codeHash: string): Promise<boolean> {
+    const row = await this.#db.one<Row>(sql`
+      update x_users
+         set recovery_code_hashes = array_remove(recovery_code_hashes, ${codeHash})
+       where id = ${userId} and ${codeHash} = any(recovery_code_hashes)
+      returning id`);
+    return row !== null;
+  }
+
   async findUserByExternalId(externalId: string): Promise<AuthUser | null> {
     const row = await this.#db.one<Row>(
       sql`select * from x_users where external_id = ${externalId}`,
@@ -185,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;
@@ -194,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);
   }
 
@@ -308,6 +362,9 @@ export class BuiltinAdapter implements AuthAdapter {
   }
 
   /**
+   * `consumed_at` is the injected clock's instant, bound — never the server's `now()`, which made
+   * the stamp the one instant in this package no test could move and no `Clock` agreed with.
+   *
    * One conditional UPDATE, and every part of the predicate is load-bearing. `consumed_at is null`
    * on the UPDATE itself is what makes redemption single-use under concurrency — inside the
    * subselect alone, two racing redemptions both pick the row and both consume it. `token_hash`
@@ -324,7 +381,7 @@ export class BuiltinAdapter implements AuthAdapter {
     tokenHash: string,
   ): Promise<AuthVerification | null> {
     const row = await this.#db.one<Row>(sql`
-      update x_verifications set consumed_at = now()
+      update x_verifications set consumed_at = ${this.#clock.now()}
       where consumed_at is null and id = (
         select id from x_verifications
         where purpose = ${purpose} and identifier = ${identifier}
@@ -367,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/client-scope.ts

@@ -5,7 +5,7 @@
 
 import type { Actor } from '@ultimat3/core';
 import { logger } from '@ultimat3/core';
-import { clientScopeSecretShort } from './errors';
+import { AuthError } from './errors';
 
 /** 128 bits: a scope only has to differ between principals, never to authenticate anyone. */
 const SCOPE_HEX_CHARS = 32;
@@ -46,7 +46,13 @@ function scopeKey(options: ClientScopeOptions): string {
     // The same floor as the env path below: an explicit key is a caller's value, so a short one is
     // refused rather than silently swapped for the process key.
     if (options.secret.length < MIN_SECRET_LENGTH) {
-      throw clientScopeSecretShort(options.secret.length, MIN_SECRET_LENGTH);
+      // Never its length: how long the key handed over is narrows a guess at it.
+      throw new AuthError({
+        code: 'X_CONFIG_INVALID',
+        cause: `clientScopeOf({ secret }) was passed a key shorter than the ${String(MIN_SECRET_LENGTH)} characters required, so the scope id would be keyed by a guessable secret`,
+        fix: 'omit secret so clientScopeOf reads SESSION_SECRET, or pass one generated with: openssl rand -hex 32',
+        meta: { option: 'secret', minLength: MIN_SECRET_LENGTH },
+      });
     }
     return options.secret;
   }

package/src/directory.ts

@@ -6,7 +6,6 @@
 
 import type { AuthUser, UserQuery } from './adapter';
 import type { Auth } from './auth';
-import { authNotImplemented } from './errors';
 
 /** Safe to render in an admin page, return from an MCP tool, or paste into a review ticket. */
 export interface AuthUserSummary {
@@ -45,21 +44,13 @@ export function describeUser(user: AuthUser): AuthUserSummary {
   };
 }
 
-const unsupported = (method: string, adapterName: string) =>
-  authNotImplemented(
-    `${adapterName}.${method}()`,
-    `implement ${method}() on your AuthAdapter — BuiltinAdapter (Postgres) and MemoryAdapter are the two reference implementations, in packages/auth/src`,
-  );
-
 /** Every member of one org, as summaries. `query.role` narrows it to one role's holders. */
 export async function listOrgUsers(
   auth: Auth,
   orgId: string,
   query?: UserQuery,
 ): Promise<readonly AuthUserSummary[]> {
-  const list = auth.adapter.listUsersByOrg?.bind(auth.adapter);
-  if (list === undefined) throw unsupported('listUsersByOrg', auth.adapter.name);
-  return (await list(orgId, query)).map(describeUser);
+  return (await auth.adapter.listUsersByOrg(orgId, query)).map(describeUser);
 }
 
 /**
@@ -71,7 +62,5 @@ export async function findUserByExternalId(
   auth: Auth,
   externalId: string,
 ): Promise<AuthUser | null> {
-  const find = auth.adapter.findUserByExternalId?.bind(auth.adapter);
-  if (find === undefined) throw unsupported('findUserByExternalId', auth.adapter.name);
-  return await find(externalId);
+  return await auth.adapter.findUserByExternalId(externalId);
 }

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

@@ -29,6 +29,7 @@ export const AUTH_OWNED_ERROR_CODES = [
   'X_AUTH_WRITE_FAILED',
   'X_AUTH_LIMITER_NOT_SHARED',
   'X_AUTH_LIMITER_POLICY_MISMATCH',
+  'X_MFA_SECRET_UNSEALED',
 ] as const;
 
 /**
@@ -74,6 +75,7 @@ export const AUTH_ERROR_TITLES: Readonly<Record<AuthOwnedErrorCode, string>> = {
   X_AUTH_WRITE_FAILED: 'an adapter write returned no row, so it cannot be confirmed',
   X_AUTH_LIMITER_NOT_SHARED: 'the lockout is declared fleet-wide and the limiter is per-process',
   X_AUTH_LIMITER_POLICY_MISMATCH: 'the limiter in use enforces other numbers than the app declared',
+  X_MFA_SECRET_UNSEALED: 'a stored totp secret is not sealed, so it is never read as one',
 };
 
 // Registered unconditionally, in one call: a second package claiming a code auth owns has to fail
@@ -115,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}`,
@@ -162,23 +164,41 @@ export const kdfOverloaded = (active: number, queued: number): AuthError =>
   });
 
 /**
- * The second leg is the APP's, and this line says so — it named `POST /auth/mfa/verify` for a
- * release while no such route, no `completeMfa()` and no pending-MFA credential existed anywhere,
- * the same dead-`fix:` defect `oauth-paths.ts` exists to stop. Shipping that route from here would
- * be worse than saying nothing: the only correlation value this error carries is a user id, so the
- * route would be unauthenticated by construction and MFA would become the ONLY factor. The design
- * constraint for the real second leg is in `packages/auth/CLAUDE.md`.
+ * The second leg is `completeMfa(auth, challenge, code)` (`mfa-challenge.ts`), and the only thing
+ * that correlates it with a passed first leg is `meta.challenge`: a sealed, short-lived value the
+ * sign-in handler carries to the caller and back. It replaces a bare user id, which made any
+ * second leg built on it unauthenticated by construction.
  *
- * `userId` is `meta`, never `cause`: both surfaces that render this code to an anonymous caller
- * (`oauth-route.ts`'s `publicBody`, `@ultimat3/http`'s problem document) publish `cause` and drop
- * `meta`, and a user id handed to whoever typed the URL is what feeds the attack above.
+ * The challenge is `meta`, never `cause`: both surfaces that render this code to an anonymous
+ * caller (`oauth-route.ts`'s `publicBody`, `@ultimat3/http`'s problem document) publish `cause`
+ * and drop `meta`, so the handler decides where it travels — a cookie or its own response body.
  */
-export const mfaRequired = (userId: string): AuthError =>
+export const mfaRequired = (challenge: string): AuthError =>
   new AuthError({
     code: 'X_MFA_REQUIRED',
     cause: 'this account has TOTP enrolled and the second factor has not been satisfied',
-    fix: 'no second-factor route ships yet — catch X_MFA_REQUIRED in your sign-in handler, check the code with verifyTotp({ secret: user.mfaSecret, code, at }), then mint the session with createSession(auth.sessions, { userId, mfaSatisfied: true })',
-    meta: { userId },
+    fix: 'catch X_MFA_REQUIRED in your sign-in handler, hand error.meta.challenge to the caller, and finish with: await completeMfa(auth, challenge, code)',
+    meta: { challenge },
+  });
+
+/**
+ * A challenge `completeMfa` will not act on: not one this app sealed, past its expiry, or naming
+ * an account that can no longer finish (deleted, disabled, or no longer enrolled). One refusal
+ * for all of them — which it was is not the caller's to learn.
+ */
+export const mfaChallengeInvalid = (): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: 'the second-factor challenge is not one this app issued, or it is no longer usable',
+    fix: 'sign in again for a fresh challenge: await login(auth, { email, password })',
+  });
+
+/** A wrong or already-spent code. The attempt it cost stays counted against the account. */
+export const mfaCodeRejected = (): AuthError =>
+  new AuthError({
+    code: 'X_UNAUTHENTICATED',
+    cause: 'the second-factor code did not match, or it was already used',
+    fix: 'read the current code from the authenticator app and retry: await completeMfa(auth, challenge, code)',
   });
 
 /**
@@ -201,6 +221,19 @@ export const mfaSecretInvalid = (surface: string): AuthError =>
     fix: 'issue a fresh one and store it: const { secret } = enrolTotp(auth, { account: user.email }) — an imported secret must be base32 (A-Z and 2-7, padding, spaces and dashes ignored) and decode to at least one byte',
   });
 
+/**
+ * A stored secret that is not sealed. It is refused rather than read: the plaintext path is the
+ * thing sealing removes, and a reader that fell back to it would keep it alive for good. The fix
+ * is the one-shot that seals every such row; `x doctor` reports the count before a user does.
+ */
+export const mfaSecretUnsealed = (): AuthError =>
+  new AuthError({
+    code: 'X_MFA_SECRET_UNSEALED',
+    cause:
+      'x_users.mfa_secret holds a value that is not sealed — written before second-factor secrets were sealed at rest, or written past saveTotpSecret — and a plaintext secret is never read as one',
+    fix: 'x auth seal-mfa --json',
+  });
+
 /**
  * `defineAuth({ mfa: { required: true } })`, refused where it is declared. The option read as a
  * security guarantee — "this deployment requires a second factor" — and nothing in this package
@@ -246,23 +279,10 @@ export const authPolicyNumberInvalid = (
     meta: { option: key, value: String(value) },
   });
 
-/**
- * An explicit key for `clientScopeOf` under the floor `SESSION_SECRET` is held to. The env path
- * already refused a short secret; the option skipped the screen, so `{ secret: 'x' }` keyed every
- * page's scope id with one character. `X_CONFIG_INVALID`, borrowed like the two above.
- */
-export const clientScopeSecretShort = (length: number, minLength: number): AuthError =>
-  new AuthError({
-    code: 'X_CONFIG_INVALID',
-    cause: `clientScopeOf({ secret }) was passed a key of ${String(length)} characters and at least ${String(minLength)} are required, so the scope id would be keyed by a guessable secret`,
-    fix: 'omit secret so clientScopeOf reads SESSION_SECRET, or pass one generated with: openssl rand -hex 32',
-    meta: { option: 'secret', minLength },
-  });
-
 /**
  * An api key `env` the parser cannot read back. `parseApiKey` splits `ult_<env>_<id>_<secret>` on
  * `_`, so `issueApiKey({ env: 'live_eu' })` minted a key its own verifier refused. Refused at
- * issue — `X_CONFIG_INVALID`, borrowed like the three above — never at first use.
+ * issue — `X_CONFIG_INVALID`, borrowed like the two above — never at first use.
  */
 export const apiKeyEnvInvalid = (env: string): AuthError =>
   new AuthError({
@@ -274,6 +294,19 @@ export const apiKeyEnvInvalid = (env: string): AuthError =>
     meta: { option: 'env' },
   });
 
+/**
+ * A wildcard scope on an api key. `*` and `<resource>:*` are how a ROLE is granted everything; on
+ * a key they are a credential that silently grows with every permission the app adds later.
+ * Refused at issue — `X_CONFIG_INVALID`, borrowed like the ones above.
+ */
+export const apiKeyScopeWildcard = (scope: string): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause: `api key scope ${renderCauseValue(scope)} is a wildcard, and a key carries exactly the permissions it names`,
+    fix: "pass each permission by name to issueApiKey({ scopes }) — e.g. scopes: ['post:read', 'post:publish']",
+    meta: { option: 'scopes' },
+  });
+
 export const passwordWeak = (reasons: readonly string[]): AuthError =>
   new AuthError({
     code: 'X_PASSWORD_WEAK',
@@ -281,28 +314,35 @@ export const passwordWeak = (reasons: readonly string[]): AuthError =>
     fix: 'choose a longer, uncommon password — or relax defineAuth({ password: { minLength } })',
   });
 
+/** The tenant bucket's key prefix. Declared here because the refusal below must recognise it. */
+export const ORG_KEY_PREFIX = 'org:';
+
 /**
  * The escape is `recordSuccess(key)`, which is what a successful login already calls: it deletes
  * the bucket, so it clears exactly this one key and nothing else. `reset()` exists too and is the
  * wrong reach — it drops every bucket in the table, including the spray this lockout is holding.
  *
- * `key` carries an address or an email the caller chose, so it goes through `renderFixLiteral`:
- * a fix line has to still parse after a hostile value lands in it.
+ * An `ip:` or `account:` key is the caller's own input, so it is echoed (escaped). A tenant key is
+ * NOT: the org id was looked up from the address the caller typed, and naming it — or even saying
+ * "an organisation" — confirms to an anonymous caller that the address belongs to a member.
  */
-export const accountLocked = (key: string, retryAfterSeconds: number): AuthError =>
-  new AuthError({
+export const accountLocked = (key: string, retryAfterSeconds: number): AuthError => {
+  const tenant = key.startsWith(ORG_KEY_PREFIX);
+  return new AuthError({
     code: 'X_ACCOUNT_LOCKED',
-    // `renderCauseValue`, matching `oauthDenied`: `ipKey(ip)` builds this key from whatever address
-    // string its caller passed, so a newline in it writes a second log line an operator reads as
-    // genuine. The value is `string` by type — the static scan only sees `unknown`/`any`, so this
-    // one was never going to be caught for us — and rendering it as a JSON string literal is
-    // escaping, not throw-safety.
-    cause: `${renderCauseValue(key)} is locked out for another ${retryAfterSeconds}s after repeated failures`,
-    fix: `wait ${retryAfterSeconds}s — or clear this one bucket: auth.limiter.recordSuccess(${renderFixLiteral(key, '<key>')}), auth.orgLimiter for an org: key — or raise defineAuth({ rateLimit })`,
+    // `renderCauseValue`: `ipKey(ip)` builds the key from whatever address string its caller
+    // passed, so a newline in it would write a second log line an operator reads as genuine.
+    cause: tenant
+      ? `sign-in is locked out for another ${retryAfterSeconds}s after repeated failures`
+      : `${renderCauseValue(key)} is locked out for another ${retryAfterSeconds}s after repeated failures`,
+    fix: tenant
+      ? `wait ${retryAfterSeconds}s — or clear the one bucket that is holding: await auth.orgLimiter.recordSuccess(orgKey(user.orgId)) — or raise defineAuth({ rateLimit })`
+      : `wait ${retryAfterSeconds}s — or clear this one bucket: await auth.limiter.recordSuccess(${renderFixLiteral(key, '<key>')}) — or raise defineAuth({ rateLimit })`,
     // `kdfOverloaded`'s shape: `@ultimat3/http`'s `retryAfterOf` reads exactly this field. `key`
     // stays out — `cause`/`fix` escape it on purpose and `meta` is read by surfaces that do not.
     meta: { retryAfterSeconds },
   });
+};
 
 /** One shape for every api-key rejection: unknown, revoked, expired and wrong all look alike. */
 export const apiKeyInvalid = (): AuthError =>
@@ -332,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
@@ -376,11 +416,3 @@ export const authLimiterPolicyMismatch = (
     fix: `construct the limiter with ${field}: ${declared} — defineAuth({ rateLimit, limiter }) compares the two, and the declaration is what Auth.rateLimit reports`,
     meta: { field, declared, enforced },
   });
-
-/** For a custom `AuthAdapter` that implements part of the seam. Nothing shipped throws it. */
-export const authNotImplemented = (feature: string, fix: string): AuthError =>
-  new AuthError({
-    code: 'X_NOT_IMPLEMENTED',
-    cause: `${feature} is not implemented by the built-in driver`,
-    fix,
-  });

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;
 }