pyric-admin 0.1.0-alpha.32 → 0.1.0-alpha.34

package/src/auth/index.ts

@@ -5,9 +5,10 @@
  * `app` argument is the branded handle from `pyric-admin/app`
  * ({@link PyricAdminApp}); only sandbox-branded apps enter this package.
  * The local sandbox path uses an in-memory store keyed off `app.sandbox`
- * and implements the core user-management subset below. Tokens are NOT
- * real JWTs — they are deterministic strings parsed by the same sandbox
- * backend. This is enough to exercise agent code paths that use
+ * and implements the core user-management subset below. Custom tokens are
+ * NOT real JWTs — they are deterministic strings. `verifyIdToken` checks the
+ * ID token JWTs pyric's Auth mints, as firebase-admin checks an ID token.
+ * This is enough to exercise agent code paths that use
  * `createUser` / `getUser` / `setCustomUserClaims` /
  * `createCustomToken` / `verifyIdToken`, not enough to model a real
  * identity platform.
@@ -24,11 +25,20 @@
  * Surface scope on the sandbox backend (what works):
  *
  *   - {@link getAuth}
- *   - `Auth.createCustomToken(uid, claims?)` — returns a deterministic
- *     `pyric-sandbox-custom:${uid}:${json}` string; no signing.
- *   - `Auth.verifyIdToken(token)` — parses tokens minted by
- *     `createCustomToken`; returns a {@link DecodedIdToken}-shaped
- *     object.
+ *   - `Auth.createCustomToken(uid, claims?)` — returns a custom token in
+ *     firebase-admin's JWT shape for the app's project, signed by the
+ *     sandbox, which pyric's `signInWithCustomToken` exchanges (#1952).
+ *   - `Auth.verifyIdToken(token, checkRevoked?)` — verifies an ID token
+ *     pyric's Auth minted for the app's project (the app's project ID, or
+ *     `pyric-sandbox` when it names none), with production's error codes;
+ *     returns a {@link DecodedIdToken}. A custom token is refused with
+ *     `auth/argument-error`, as in production (#1949). With
+ *     `checkRevoked`, the client account behind the token must exist
+ *     (`auth/user-not-found`), be enabled (`auth/user-disabled`), and have
+ *     no revocation after the token's `auth_time` (`auth/id-token-revoked`).
+ *   - `Auth.revokeRefreshTokens(uid)` — revokes the client account's
+ *     refresh tokens: its held sessions fail their next refresh, and
+ *     `verifyIdToken(token, true)` refuses tokens authenticated before it.
  *   - `Auth.createUser(properties)` — stores a {@link UserRecord}
  *     in an in-memory `Map<uid, UserRecord>`. Auto-generates a `uid`
  *     when one is not supplied.
@@ -54,7 +64,6 @@
  *     `generateSignInWithEmailLink`, `generateVerifyAndChangeEmailLink`.
  *   - Bulk operations: `listUsers`, `getUsers`, `deleteUsers`,
  *     `importUsers`.
- *   - Revocation: `revokeRefreshTokens`.
  *   - `getUserByPhoneNumber`, `getUserByProviderUid`.
  *   - `updateUser` — not required by the brief.
  *
@@ -67,7 +76,14 @@ import {
   type Sandbox,
   type SandboxEvent,
 } from 'pyric/sandbox';
-import { assertNoReservedCustomClaims } from 'pyric/sandbox/internal';
+import {
+  assertNoReservedCustomClaims,
+  authAccountsFor,
+  getClock,
+  mintCustomToken,
+  SANDBOX_PROJECT_ID,
+  type AuthAccountStanding,
+} from 'pyric/sandbox/internal';
 import type {
   AuthUserRecord,
   CreateUserRequest as SandboxCreateUserRequest,
@@ -79,6 +95,7 @@ import {
   type PyricAdminApp,
 } from '../app/index.js';
 import { assertAdminAppActive } from '../app/lifecycle.js';
+import { explicitProjectId } from '../app/project-id.js';
 import type {
   Auth,
   CreateRequest,
@@ -87,19 +104,17 @@ import type {
   UpdateRequest,
   UserRecord,
 } from './types.js';
-import { SANDBOX_TOKEN_PREFIX } from './token-decoders.js';
-import { verifySandboxIdToken } from './verify-token.js';
+import { assertIdTokenArgument, assertNotRevokedOrDisabled, invalidUid, userNotFound, verifySandboxIdToken } from './verify-token.js';
 
 export * from './types.js';
-export { SANDBOX_TOKEN_PREFIX } from './token-decoders.js';
 
 // ─── Sandbox backend ────────────────────────────────────────────────────
 
 /**
  * Per-sandbox in-memory store. One instance per `Sandbox` (tracked in
  * the {@link sandboxStores} WeakMap below). Holds the user table; the
- * token format is stateless (`createCustomToken` mints, `verifyIdToken`
- * parses) so it doesn't need to live here.
+ * tokens are stateless (`createCustomToken` mints, `verifyIdToken`
+ * checks) so they don't need to live here.
  *
  * `usersByUid` is the canonical index. `getUserByEmail` does a linear
  * scan over its values — the sandbox is for development and agent test
@@ -174,15 +189,14 @@ function storeFor(sandbox: Sandbox): AuthStore {
 }
 
 /**
- * Mint a deterministic sandbox token (the {@link SANDBOX_TOKEN_PREFIX}
- * format). Stateless — shared verbatim by the local and remote sandbox
- * arms, so a token minted against either round-trips through
- * verifySandboxIdToken on the other.
+ * Mint a sandbox custom token for the app's project at `nowMs`, in
+ * firebase-admin's shape (`pyric/sandbox/internal` `mintCustomToken`).
+ * Stateless, shared by the local and remote sandbox arms. Like production's
+ * custom token, it is not an ID token, and `verifyIdToken` refuses it.
  */
-function mintSandboxCustomToken(uid: string, developerClaims?: object): Promise<string> {
-  const claims = developerClaims ?? {};
-  const token = `${SANDBOX_TOKEN_PREFIX}:${uid}:${JSON.stringify(claims)}`;
-  return Promise.resolve(token);
+function mintSandboxCustomToken(app: PyricAdminApp, nowMs: number, uid: string, developerClaims?: object): Promise<string> {
+  const claims = developerClaims as Record<string, unknown> | undefined;
+  return Promise.resolve(mintCustomToken({ uid, claims, projectId: idTokenProjectId(app), nowMs }));
 }
 
 /**
@@ -199,7 +213,26 @@ function mintSandboxCustomToken(uid: string, developerClaims?: object): Promise<
  * cast acknowledges the divergence in one place and lets the rest of
  * the file focus on the methods that actually work.
  */
-function makeSandboxAuth(sandbox: Sandbox): Auth {
+/**
+ * The project an ID token must name for `app`: firebase-admin's explicit
+ * project ID, or `pyric-sandbox`, which pyric's Auth mints for when it knows
+ * no project. Production throws `auth/invalid-credential` with no project;
+ * the sandbox checks against `pyric-sandbox` instead, by design.
+ */
+function idTokenProjectId(app: PyricAdminApp): string {
+  return explicitProjectId(app) ?? SANDBOX_PROJECT_ID;
+}
+
+/**
+ * Where the client account with `uid` stands, from the account table the
+ * sandbox's client sign-ins write to. A sandbox no client Auth has touched
+ * has no accounts.
+ */
+function clientAccountStanding(sandbox: Sandbox, uid: string): AuthAccountStanding {
+  return authAccountsFor(sandbox)?.standing(uid) ?? { kind: 'unrecorded' };
+}
+
+function makeSandboxAuth(app: PyricAdminApp, sandbox: Sandbox): Auth {
   const store = storeFor(sandbox);
 
   /** Canonical "not implemented" error for surface that the sandbox
@@ -259,22 +292,22 @@ function makeSandboxAuth(sandbox: Sandbox): Auth {
     },
 
     /**
-     * Mint a deterministic sandbox token. Format is fixed at
-     * `${SANDBOX_TOKEN_PREFIX}:${uid}:${JSON.stringify(claims ?? {})}`.
-     * Round-trips through {@link verifyIdToken} on the same sandbox
-     * backend; rejected by every other token verifier. Shared
-     * implementation: {@link mintSandboxCustomToken}.
+     * Mint a custom token for the app's project on the sandbox clock. Not
+     * an ID token: {@link verifyIdToken} refuses it, as production does.
+     * Shared implementation: {@link mintSandboxCustomToken}.
      */
     createCustomToken(uid: string, developerClaims?: object): Promise<string> {
-      return mintSandboxCustomToken(uid, developerClaims);
+      return mintSandboxCustomToken(app, getClock(sandbox).now(), uid, developerClaims);
     },
 
     /**
-     * Parse a token minted by {@link createCustomToken}. Shared
-     * implementation: {@link verifySandboxIdToken}.
+     * Verify an ID token for the app's project, reading `exp` and `nbf` on
+     * the sandbox clock. Shared implementation: {@link verifySandboxIdToken}.
      */
-    verifyIdToken(idToken: string, _checkRevoked?: boolean): Promise<DecodedIdToken> {
-      return verifySandboxIdToken(idToken);
+    verifyIdToken(idToken: string, checkRevoked = false): Promise<DecodedIdToken> {
+      const verified = verifySandboxIdToken(idToken, { projectId: idTokenProjectId(app), nowMs: getClock(sandbox).now() });
+      if (!checkRevoked) return verified;
+      return verified.then((decoded) => assertNotRevokedOrDisabled(decoded, clientAccountStanding(sandbox, decoded.sub)));
     },
 
     /**
@@ -402,8 +435,20 @@ function makeSandboxAuth(sandbox: Sandbox): Auth {
     importUsers(): Promise<unknown> {
       return Promise.reject(notImplemented('importUsers'));
     },
-    revokeRefreshTokens(): Promise<void> {
-      return Promise.reject(notImplemented('revokeRefreshTokens'));
+    /**
+     * Revoke the client account's refresh tokens at the sandbox clock's now,
+     * through the shared foundation's account table. A uid that is not a
+     * non-empty string of at most 128 characters rejects `auth/invalid-uid`,
+     * and a uid with no client record `auth/user-not-found`, as production's do.
+     */
+    revokeRefreshTokens(uid: string): Promise<void> {
+      const uidError = invalidUid(uid);
+      if (uidError !== null) return Promise.reject(uidError);
+      const standing = clientAccountStanding(sandbox, uid);
+      const hasRecord = standing.kind === 'active' || standing.kind === 'disabled';
+      if (!hasRecord) return Promise.reject(userNotFound());
+      authAccountsFor(sandbox)?.revokeRefreshTokens(uid);
+      return Promise.resolve();
     },
     createSessionCookie(): Promise<string> {
       return Promise.reject(notImplemented('createSessionCookie'));
@@ -465,10 +510,14 @@ function makeSandboxAuth(sandbox: Sandbox): Auth {
 // dedicated single-lookup op, and O(n) over the wire is fine at sandbox
 // scale (per the design spike — add an op if it ever matters).
 //
-// Tokens stay stateless and local: `createCustomToken` / `verifyIdToken`
-// are the same string transforms as the local arm
-// ({@link mintSandboxCustomToken} / {@link verifySandboxIdToken}), so a
-// token minted server-side verifies against any pyric-admin backend.
+// Tokens are minted and checked in this process with the local arm's
+// transforms ({@link mintSandboxCustomToken} / {@link verifySandboxIdToken}),
+// at the instant the worker's sandbox clock reads (`sandbox.clock`), so after
+// `advanceClock` both arms agree on `iat`, `exp` and expiry (#2010). The
+// clock is read on every call rather than cached: Studio, the CLI, an agent
+// or the page can move it at any moment, and the bridge relays no clock
+// updates to this process, so a cached offset would go stale at exactly the
+// advance a test makes.
 
 /** Map a firebase-admin `CreateRequest` onto the worker's sandbox
  *  create-user request. `null`s (upstream "clear") become "unset" — a
@@ -535,7 +584,7 @@ function fromAuthUserRecord(r: AuthUserRecord): UserRecord {
  *   - User mutations emit auth `SandboxEvent`s in the worker (visible to
  *     Studio/agents) and are visible to the browser app immediately.
  */
-function makeRemoteAuth(sandbox: RemoteSandbox): Auth {
+function makeRemoteAuth(app: PyricAdminApp, sandbox: RemoteSandbox): Auth {
   const channel = sandbox.channel;
 
   const notImplemented = (method: string): Error =>
@@ -546,20 +595,46 @@ function makeRemoteAuth(sandbox: RemoteSandbox): Auth {
   const listRecords = async (): Promise<AuthUserRecord[]> =>
     (await channel.op({ method: 'auth.listUsers' })) as AuthUserRecord[];
 
+  /** The worker's sandbox clock now, in epoch milliseconds. */
+  const sandboxNow = async (): Promise<number> =>
+    ((await channel.op({ method: 'sandbox.clock' })) as { now: number }).now;
+
+  /**
+   * Where the account stands, from the worker's user pool. The worker relays
+   * no revocation time (this arm has no `revokeRefreshTokens`), so a token is
+   * refused here only for a missing or disabled account.
+   */
+  const relayedStanding = async (uid: string): Promise<AuthAccountStanding> => {
+    const record = (await listRecords()).find((u) => u.uid === uid);
+    if (record === undefined) return { kind: 'unrecorded' };
+    if (record.disabled) return { kind: 'disabled' };
+    return { kind: 'active', tokensValidAfterMs: null };
+  };
+
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const handle: any = {
     get app() {
       throw notImplemented('auth.app');
     },
 
-    /** Stateless mint — identical to the local arm; needs no relay. */
-    createCustomToken(uid: string, developerClaims?: object): Promise<string> {
-      return mintSandboxCustomToken(uid, developerClaims);
+    /** The local arm's mint for the app's project, at the worker's sandbox clock. */
+    async createCustomToken(uid: string, developerClaims?: object): Promise<string> {
+      return mintSandboxCustomToken(app, await sandboxNow(), uid, developerClaims);
     },
 
-    /** Stateless parse — identical to the local arm; needs no relay. */
-    verifyIdToken(idToken: string, _checkRevoked?: boolean): Promise<DecodedIdToken> {
-      return verifySandboxIdToken(idToken);
+    /**
+     * The local arm's token check, for the app's project, with expiry read on
+     * the worker's sandbox clock. A token that is not a string throws before
+     * the clock is read, as the local arm throws. With `checkRevoked`, the
+     * account's standing is relayed from the worker's user pool
+     * ({@link relayedStanding}).
+     */
+    verifyIdToken(idToken: string, checkRevoked = false): Promise<DecodedIdToken> {
+      assertIdTokenArgument(idToken);
+      const projectId = idTokenProjectId(app);
+      const verified = sandboxNow().then((nowMs) => verifySandboxIdToken(idToken, { projectId, nowMs }));
+      if (!checkRevoked) return verified;
+      return verified.then(async (decoded) => assertNotRevokedOrDisabled(decoded, await relayedStanding(decoded.sub)));
     },
 
     /** Relays `auth.adminCreateUser`. Uid conflicts / invalid emails /
@@ -666,7 +741,9 @@ function makeRemoteAuth(sandbox: RemoteSandbox): Auth {
     importUsers(): Promise<unknown> {
       return Promise.reject(notImplemented('importUsers'));
     },
-    revokeRefreshTokens(): Promise<void> {
+    revokeRefreshTokens(uid: string): Promise<void> {
+      const uidError = invalidUid(uid);
+      if (uidError !== null) return Promise.reject(uidError);
       return Promise.reject(notImplemented('revokeRefreshTokens'));
     },
     createSessionCookie(): Promise<string> {
@@ -732,9 +809,11 @@ function makeRemoteAuth(sandbox: RemoteSandbox): Auth {
  * const auth = getAuth(app);
  *
  * const user = await auth.createUser({ uid: 'alice', email: 'a@e.com' });
- * const token = await auth.createCustomToken(user.uid, { role: 'admin' });
- * const decoded = await auth.verifyIdToken(token);
- * console.log(decoded.uid, decoded.role); // 'alice' 'admin'
+ * await auth.setCustomUserClaims(user.uid, { role: 'admin' });
+ *
+ * // An ID token from a client signed in on the same sandbox.
+ * const decoded = await auth.verifyIdToken(idTokenFromTheClient);
+ * console.log(decoded.uid);
  * ```
  */
 export function getAuth(app?: PyricAdminApp): Auth {
@@ -755,6 +834,6 @@ export function getAuth(app?: PyricAdminApp): Auth {
     throw new TypeError('pyric-admin/auth: getAuth expected a sandbox admin app.');
   }
   return isRemoteSandbox(app.sandbox)
-    ? makeRemoteAuth(app.sandbox)
-    : makeSandboxAuth(app.sandbox);
+    ? makeRemoteAuth(app, app.sandbox)
+    : makeSandboxAuth(app, app.sandbox);
 }

package/src/auth/oracle-admin-answers.test.ts

@@ -11,7 +11,8 @@
 import { afterEach, describe, expect, it } from 'bun:test';
 import { readFileSync } from 'node:fs';
 import { initializeSandbox } from 'pyric/sandbox';
-import { createUserWithEmailAndPassword, getAuth as getClientAuth, sandbox as clientSandbox } from 'pyric/auth';
+import { getClock } from 'pyric/sandbox/internal';
+import { createUserWithEmailAndPassword, getAuth as getClientAuth, sandbox as clientSandbox, signInWithEmailAndPassword } from 'pyric/auth';
 import { deleteApp, getApps, initializeApp } from '../app/index.js';
 import { getAuth } from './index.js';
 
@@ -59,9 +60,6 @@ const PINS: Record<string, { pyric: string; production: string; finding: string
   createCustomToken129Uid: { pyric: 'resolved', production: 'throws auth/argument-error', finding: 'auth-claims AU-4' },
   createCustomTokenReservedAud: { pyric: 'resolved', production: 'throws auth/argument-error', finding: 'auth-claims AU-4' },
   createCustomTokenNullClaims: { pyric: 'resolved', production: 'throws auth/argument-error', finding: 'auth-claims AU-4' },
-  verifyIdTokenOfCustomToken: { pyric: 'resolved', production: 'rejects auth/argument-error', finding: 'auth-claims AU-9: verifyIdToken accepts a custom token' },
-  verifyIdTokenCheckRevokedDisabled: { pyric: 'resolved', production: 'rejects auth/user-disabled', finding: 'auth-claims AU-10: checkRevoked ignores disabled and deleted users' },
-  verifyIdTokenCheckRevokedDeleted: { pyric: 'resolved', production: 'rejects auth/user-not-found', finding: 'auth-claims AU-10' },
 };
 
 describe('pyric-admin auth answers as the production Admin SDK does', () => {
@@ -111,4 +109,42 @@ describe('pyric-admin auth answers as the production Admin SDK does', () => {
     const pinned = Object.fromEntries(Object.entries(PINS).map(([call, pin]) => [call, { pyric: pin.pyric, production: pin.production }]));
     expect(found).toEqual(pinned);
   });
+
+  it('verifyIdToken with checkRevoked refuses a token issued before revokeRefreshTokens', async () => {
+    const sandbox = initializeSandbox();
+    const admin = getAuth(initializeApp({ sandbox }, 'oracle-admin-revoked'));
+    const client = getClientAuth(sandbox);
+    const { user } = await createUserWithEmailAndPassword(client, 'revoked@example.com', 'secret-pw');
+    const idToken = await user.getIdToken();
+    // firebase-admin compares whole seconds: a token authenticated in the
+    // revocation's second is still valid.
+    getClock(sandbox).advance(2000);
+    await admin.revokeRefreshTokens(user.uid);
+
+    expect(await outcome(() => admin.verifyIdToken(idToken))).toBe('resolved');
+    expect(await outcome(() => admin.verifyIdToken(idToken, true))).toBe('rejects auth/id-token-revoked');
+    // The held client session's next refresh is refused, and it signs out.
+    expect(await outcome(() => user.getIdToken(true))).toBe('rejects auth/user-token-expired');
+    expect(client.currentUser).toBeNull();
+    // A new sign-in authenticates after the revocation, so its token is valid.
+    const { user: again } = await signInWithEmailAndPassword(client, 'revoked@example.com', 'secret-pw');
+    expect(await outcome(async () => admin.verifyIdToken(await again.getIdToken(), true))).toBe('resolved');
+  });
+
+  it('revokeRefreshTokens rejects auth/user-not-found for a uid with no account', async () => {
+    const sandbox = initializeSandbox();
+    const admin = getAuth(initializeApp({ sandbox }, 'oracle-admin-revoke-missing'));
+    getClientAuth(sandbox);
+    expect(await outcome(() => admin.revokeRefreshTokens('oracle-missing'))).toBe('rejects auth/user-not-found');
+  });
+
+  it('revokeRefreshTokens rejects auth/invalid-uid for an empty or overlong uid before looking it up', async () => {
+    const sandbox = initializeSandbox();
+    const admin = getAuth(initializeApp({ sandbox }, 'oracle-admin-revoke-invalid-uid'));
+    getClientAuth(sandbox);
+    expect(await outcome(() => admin.revokeRefreshTokens(''))).toBe('rejects auth/invalid-uid');
+    expect(await outcome(() => admin.revokeRefreshTokens('u'.repeat(129)))).toBe('rejects auth/invalid-uid');
+    const message = await admin.revokeRefreshTokens('').catch((e: Error) => e.message);
+    expect(message).toBe('The uid must be a non-empty string with at most 128 characters.');
+  });
 });

package/src/auth/token-decoders.ts

@@ -1,158 +1,115 @@
 /**
- * Modular token decoders for `pyric-admin/auth` verification.
- * Each decoder strategy isolates prefix detection and claim decoding
- * for one recognized token format.
+ * The ID token check behind `pyric-admin/auth` `verifyIdToken`.
+ *
+ * The only token that verifies is the JWT pyric's Auth mints
+ * (`pyric/sandbox/internal` `mintIdToken`), checked by the shared
+ * {@link checkIdToken} and then by firebase-admin 13.10.0's rules, in its
+ * order (lib/auth/token-verifier.js `verifyContent` and `verifySignature`,
+ * lib/utils/jwt.js, and jsonwebtoken's `nbf` and `exp`). A plain string, or
+ * the client token shape from before #1836, fails to decode, and a custom
+ * token is refused as one, as in production (#1949, #1952).
  */
+import { checkIdToken, CUSTOM_TOKEN_AUDIENCE } from 'pyric/sandbox/internal';
 import type { DecodedIdToken } from './types.js';
 
-/**
- * Token format minted by `createCustomToken` and parsed by
- * `verifyIdToken`. Exported as a constant so tests can lock the shape.
- *
- * Layout: `pyric-sandbox-custom:${uid}:${jsonClaims}`
- *
- * - The prefix lets `verifyIdToken` reject foreign tokens with a clear
- *   "not a sandbox token" error rather than NaN'ing out.
- * - `uid` is colon-free per the auto-uid format above.
- * - `jsonClaims` is the JSON-stringified developer claims (or `{}` when
- *   none were provided). Round-trips losslessly through `JSON.parse`.
- *
- * NOT a JWT. NOT signed. Do not use this token format to talk to any
- * real Firebase service — it only round-trips through this same
- * sandbox backend.
- */
-export const SANDBOX_TOKEN_PREFIX = 'pyric-sandbox-custom';
+const ID_TOKEN_ISSUER = 'https://securetoken.google.com/';
+const MAX_SUBJECT_LENGTH = 128;
 
-export interface TokenDecoder {
-  readonly name: string;
-  readonly prefix: string;
-  decode(token: string, nowSec: number): DecodedIdToken;
-}
+const DOCS = ' See https://firebase.google.com/docs/auth/admin/verify-id-tokens for details on how to retrieve an ID token.';
+const PROJECT_MATCH = ' Make sure the ID token comes from the same Firebase project as the service account used to authenticate this SDK.';
+
+const MESSAGES = {
+  decode: `Decoding Firebase ID token failed. Make sure you passed the entire string JWT which represents an ID token.${DOCS}`,
+  customToken: `verifyIdToken() expects an ID token, but was given a custom token.${DOCS}`,
+  legacyCustomToken: `verifyIdToken() expects an ID token, but was given a legacy custom token.${DOCS}`,
+  noKid: `Firebase ID token has no "kid" claim.${DOCS}`,
+  algorithm: (alg: unknown) => `Firebase ID token has incorrect algorithm. Expected "RS256" but got "${String(alg)}".${DOCS}`,
+  audience: (projectId: string, aud: unknown) =>
+    `Firebase ID token has incorrect "aud" (audience) claim. Expected "${projectId}" but got "${String(aud)}".${PROJECT_MATCH}${DOCS}`,
+  issuer: (projectId: string, iss: unknown) =>
+    `Firebase ID token has incorrect "iss" (issuer) claim. Expected "${ID_TOKEN_ISSUER}${projectId}" but got "${String(iss)}".${PROJECT_MATCH}${DOCS}`,
+  noSub: `Firebase ID token has no "sub" (subject) claim.${DOCS}`,
+  emptySub: `Firebase ID token has an empty "sub" (subject) claim.${DOCS}`,
+  longSub: `Firebase ID token has a "sub" (subject) claim longer than 128 characters.${DOCS}`,
+  unknownKid:
+    'Firebase ID token has "kid" claim which does not correspond to a known public key. Most likely the ID token is expired, so get a fresh token from your client app and try again.',
+  signature: `Firebase ID token has invalid signature.${DOCS}`,
+  expired: `Firebase ID token has expired. Get a fresh ID token from your client app and try again (auth/id-token-expired).${DOCS}`,
+};
+
+/** The two codes an ID token check fails with. */
+export type IdTokenFailureCode = 'argument-error' | 'id-token-expired';
 
-function resolveStringClaim(claims: Record<string, unknown>, key: string, fallback: string): string {
-  const val = claims[key];
-  const hasStringValue = typeof val === 'string';
-  return hasStringValue ? val : fallback;
+export type IdTokenVerdict =
+  | { ok: true; token: DecodedIdToken }
+  | { ok: false; code: IdTokenFailureCode; message: string };
+
+type Claims = Readonly<Record<string, unknown>>;
+
+function refused(message: string): IdTokenVerdict {
+  return { ok: false, code: 'argument-error', message };
 }
 
-function resolveNumberClaim(claims: Record<string, unknown>, key: string, fallback: number): number {
-  const val = claims[key];
-  const hasNumberValue = typeof val === 'number';
-  return hasNumberValue ? val : fallback;
+/** token-verifier.js: a missing `kid` names a custom token, a legacy custom token, or neither. */
+function missingKidMessage(header: Claims, claims: Claims): string {
+  if (claims.aud === CUSTOM_TOKEN_AUDIENCE) return MESSAGES.customToken;
+  const legacyData = claims.d;
+  const isLegacyCustomToken =
+    header.alg === 'HS256' && claims.v === 0 && typeof legacyData === 'object' && legacyData !== null && 'uid' in legacyData;
+  if (isLegacyCustomToken) return MESSAGES.legacyCustomToken;
+  return MESSAGES.noKid;
 }
 
-function resolveUid(idToken: string, firstColon: number, claims: Record<string, unknown>): string {
-  const rawSub = claims['sub'];
-  const hasExplicitSubjectClaim = typeof rawSub === 'string';
-  if (hasExplicitSubjectClaim) {
-    return rawSub;
-  }
-  const prefixSegment = idToken.slice('sandbox-id-token-'.length, firstColon);
-  const lastHyphen = prefixSegment.lastIndexOf('-');
-  const hasHyphenatedSerialSuffix = lastHyphen > 0;
-  if (hasHyphenatedSerialSuffix) {
-    return prefixSegment.slice(0, lastHyphen);
-  }
-  return prefixSegment;
+/** Auth blocking events with no user record, whose `sub` firebase-admin leaves unchecked. */
+function skipsSubjectCheck(claims: Claims): boolean {
+  return claims.event_type === 'beforeSendSms' || claims.event_type === 'beforeSendEmail';
 }
 
-function resolveFirebaseClaim(
-  claims: Record<string, unknown>,
-): { identities: Record<string, unknown>; sign_in_provider: string } {
-  const rawFirebase = claims['firebase'];
-  const isMissingFirebaseClaim = !rawFirebase || typeof rawFirebase !== 'object';
-  if (isMissingFirebaseClaim) {
-    return { identities: {}, sign_in_provider: 'custom' };
-  }
-  const fb = rawFirebase as Record<string, unknown>;
-  const signInProvider = resolveStringClaim(fb, 'sign_in_provider', 'custom');
-  const rawIdentities = fb['identities'];
-  const isMissingIdentitiesMap = !rawIdentities || typeof rawIdentities !== 'object';
-  if (isMissingIdentitiesMap) {
-    return { identities: {}, sign_in_provider: signInProvider };
-  }
-  return { identities: rawIdentities as Record<string, unknown>, sign_in_provider: signInProvider };
+function subjectMessage(sub: unknown): string | undefined {
+  if (typeof sub !== 'string') return MESSAGES.noSub;
+  if (sub === '') return MESSAGES.emptySub;
+  if (sub.length > MAX_SUBJECT_LENGTH) return MESSAGES.longSub;
+  return undefined;
 }
 
-const customTokenDecoder: TokenDecoder = {
-  name: 'custom-token',
-  prefix: `${SANDBOX_TOKEN_PREFIX}:`,
-  decode(idToken: string, nowSec: number): DecodedIdToken {
-    const firstColon = idToken.indexOf(':');
-    const secondColon = idToken.indexOf(':', firstColon + 1);
-    const isMissingClaimsSegment = secondColon < 0;
-    if (isMissingClaimsSegment) {
-      throw new Error(
-        `pyric-admin/auth: verifyIdToken received a malformed sandbox token (missing claims segment): ${idToken}`,
-      );
-    }
-    const uid = idToken.slice(firstColon + 1, secondColon);
-    const jsonClaims = idToken.slice(secondColon + 1);
-    let claims: Record<string, unknown>;
-    try {
-      claims = JSON.parse(jsonClaims) as Record<string, unknown>;
-    } catch (e) {
-      throw new Error(
-        `pyric-admin/auth: verifyIdToken failed to parse sandbox token claims as JSON: ${(e as Error).message}`,
-      );
-    }
-    return {
-      aud: 'pyric-sandbox',
-      auth_time: nowSec,
-      exp: nowSec + 3600,
-      firebase: {
-        identities: {},
-        sign_in_provider: 'custom',
-      },
-      iat: nowSec,
-      iss: 'pyric-sandbox',
-      sub: uid,
-      uid,
-      ...claims,
-    };
-  },
-};
+/** token-verifier.js `verifyContent`: `kid`, `alg`, `aud`, `iss`, then `sub`; the first failure wins. */
+function contentMessage(header: Claims, claims: Claims, projectId: string): string | undefined {
+  if (header.kid === undefined) return missingKidMessage(header, claims);
+  if (header.alg !== 'RS256') return MESSAGES.algorithm(header.alg);
+  if (claims.aud !== projectId) return MESSAGES.audience(projectId, claims.aud);
+  if (claims.iss !== `${ID_TOKEN_ISSUER}${projectId}`) return MESSAGES.issuer(projectId, claims.iss);
+  if (skipsSubjectCheck(claims)) return undefined;
+  return subjectMessage(claims.sub);
+}
 
-const clientIdTokenDecoder: TokenDecoder = {
-  name: 'client-id-token',
-  prefix: 'sandbox-id-token-',
-  decode(idToken: string, nowSec: number): DecodedIdToken {
-    const firstColon = idToken.indexOf(':');
-    const isMissingClaimsSegment = firstColon < 0;
-    if (isMissingClaimsSegment) {
-      throw new Error(
-        `pyric-admin/auth: verifyIdToken received a malformed client ID token (missing claims segment after colon): ${idToken}`,
-      );
-    }
-    const jsonClaims = idToken.slice(firstColon + 1);
-    let claims: Record<string, unknown>;
-    try {
-      claims = JSON.parse(jsonClaims) as Record<string, unknown>;
-    } catch (e) {
-      throw new Error(
-        `pyric-admin/auth: verifyIdToken failed to parse client ID token claims as JSON: ${(e as Error).message}`,
-      );
-    }
-    const uid = resolveUid(idToken, firstColon, claims);
-    const aud = resolveStringClaim(claims, 'aud', 'pyric-sandbox');
-    const iss = resolveStringClaim(claims, 'iss', 'https://sandbox.pyric.dev');
-    const exp = resolveNumberClaim(claims, 'exp', nowSec + 3600);
-    const iat = resolveNumberClaim(claims, 'iat', nowSec);
-    const authTime = resolveNumberClaim(claims, 'auth_time', nowSec);
-    const firebase = resolveFirebaseClaim(claims);
+/** jsonwebtoken's `nbf` rule, which runs before `exp`; firebase-admin reports a failure as an invalid signature. */
+function isNotYetValid(nbf: unknown, nowSec: number): boolean {
+  if (nbf === undefined) return false;
+  return typeof nbf !== 'number' || nbf > nowSec;
+}
 
-    return {
-      ...claims,
-      aud,
-      auth_time: authTime,
-      exp,
-      firebase,
-      iat,
-      iss,
-      sub: uid,
-      uid,
-    };
-  },
-};
+/** jsonwebtoken's `exp` rule: an absent `exp` never expires, and a non-number is an invalid signature. */
+function expiryVerdict(exp: unknown, nowSec: number): IdTokenVerdict | undefined {
+  if (exp === undefined) return undefined;
+  if (typeof exp !== 'number') return refused(MESSAGES.signature);
+  const hasExpired = nowSec >= exp;
+  if (hasExpired) return { ok: false, code: 'id-token-expired', message: MESSAGES.expired };
+  return undefined;
+}
 
-export const TOKEN_DECODERS: TokenDecoder[] = [customTokenDecoder, clientIdTokenDecoder];
+/**
+ * Checks an ID token for `projectId` at `nowSec`, in firebase-admin's order:
+ * decoding, the content rules, the key and signature, then `nbf` and `exp`.
+ */
+export async function checkClientIdToken(idToken: string, projectId: string, nowSec: number): Promise<IdTokenVerdict> {
+  const check = await checkIdToken(idToken);
+  if (!check.ok && check.reason === 'malformed') return refused(MESSAGES.decode);
+  const contentFailure = contentMessage(check.header, check.claims, projectId);
+  if (contentFailure !== undefined) return refused(contentFailure);
+  if (!check.ok) return refused(check.reason === 'kid' ? MESSAGES.unknownKid : MESSAGES.signature);
+  if (isNotYetValid(check.claims.nbf, nowSec)) return refused(MESSAGES.signature);
+  const expired = expiryVerdict(check.claims.exp, nowSec);
+  if (expired !== undefined) return expired;
+  const token = { ...check.claims, uid: check.claims.sub } as DecodedIdToken;
+  return { ok: true, token };
+}