@ultimat3/auth 29.4.0 → 30.0.0

package/src/tables.ts

@@ -112,6 +112,46 @@ export const X_API_KEYS_TABLE = `create table if not exists x_api_keys (
   created_at            timestamptz not null default now()
 )`;
 
+// Passkeys (`passkey-*.ts`). Byte fields are base64url text; the challenge row holds the
+// challenge's sha256, never the challenge; evidence carries its own key so it verifies alone.
+export const X_PASSKEYS_TABLE = `create table if not exists x_passkeys (
+  id                    text primary key,
+  user_id               uuid not null references x_users (id) on delete cascade,
+  public_key            text not null,
+  algorithm             integer not null,
+  sign_count            bigint not null default 0,
+  transports            text[] not null default '{}',
+  created_at            timestamptz not null default now(),
+  last_used_at          timestamptz
+);
+create index if not exists x_passkeys_user_id_idx on x_passkeys (user_id)`;
+
+export const X_PASSKEY_CHALLENGES_TABLE = `create table if not exists x_passkey_challenges (
+  id                    text primary key,
+  ceremony              text not null,
+  user_id               uuid references x_users (id) on delete cascade,
+  digest                text,
+  nonce                 text,
+  expires_at            timestamptz not null,
+  created_at            timestamptz not null default now()
+);
+create index if not exists x_passkey_challenges_expires_at_idx on x_passkey_challenges (expires_at)`;
+
+export const X_PASSKEY_EVIDENCE_TABLE = `create table if not exists x_passkey_evidence (
+  id                    text primary key,
+  user_id               uuid not null references x_users (id) on delete cascade,
+  credential_id         text not null,
+  digest                text not null,
+  nonce                 text not null,
+  authenticator_data    text not null,
+  client_data_json      text not null,
+  signature             text not null,
+  public_key            text not null,
+  algorithm             integer not null,
+  created_at            timestamptz not null default now()
+);
+create index if not exists x_passkey_evidence_digest_idx on x_passkey_evidence (digest)`;
+
 /** Ordered by foreign-key dependency — run them top to bottom. */
 export const AUTH_TABLES: readonly string[] = Object.freeze([
   X_USERS_TABLE,
@@ -120,6 +160,9 @@ export const AUTH_TABLES: readonly string[] = Object.freeze([
   X_ACCOUNTS_TABLE,
   X_VERIFICATIONS_TABLE,
   X_API_KEYS_TABLE,
+  X_PASSKEYS_TABLE,
+  X_PASSKEY_CHALLENGES_TABLE,
+  X_PASSKEY_EVIDENCE_TABLE,
 ]);
 
 export const AUTH_TABLE_NAMES: readonly string[] = Object.freeze([
@@ -128,4 +171,7 @@ export const AUTH_TABLE_NAMES: readonly string[] = Object.freeze([
   'x_accounts',
   'x_verifications',
   'x_api_keys',
+  'x_passkeys',
+  'x_passkey_challenges',
+  'x_passkey_evidence',
 ]);

package/src/token-endpoints.ts

@@ -0,0 +1,61 @@
+// Single responsibility: RFC 7009 revocation and RFC 7662 introspection. Revocation answers 200
+// whatever the token was (§2.2: an unknown token is not an error, or the endpoint is an oracle)
+// and ends the whole grant at once. Introspection is a resource server's question, so it needs a
+// confidential client and answers `{ active: false }`, nothing else, for a token it does not own.
+
+import type { ResolvedAuthServerConfig } from './authorization-server-config';
+import { refused, resolveAccess, type TokenOutcome } from './authorization-server-tokens';
+import type { AuthServerClient } from './authorization-server-types';
+import { sha256Hex } from './tokens';
+
+const INACTIVE: TokenOutcome = { ok: true, body: { active: false } };
+
+export async function revokeToken(
+  config: ResolvedAuthServerConfig,
+  form: ReadonlyMap<string, string>,
+  client: AuthServerClient,
+): Promise<TokenOutcome> {
+  const token = form.get('token');
+  if (token === undefined) return refused('invalid_request', 'token is required');
+  const record = await config.store.getToken(sha256Hex(token));
+  const grant = record === null ? null : await config.store.getGrant(record.grantId);
+  // Only the client the token was issued to may revoke it (§2.1); anyone else learns nothing.
+  if (grant !== null && grant.clientId === client.clientId) {
+    await config.store.revokeGrant(grant.id, config.clock.now());
+    config.emit({ kind: 'revoked', clientId: client.clientId });
+  }
+  return { ok: true, body: {} };
+}
+
+export async function introspectToken(
+  config: ResolvedAuthServerConfig,
+  form: ReadonlyMap<string, string>,
+  client: AuthServerClient,
+): Promise<TokenOutcome> {
+  if (client.secretHash === null) {
+    return refused('invalid_client', 'introspection needs a confidential client', 401);
+  }
+  const token = form.get('token');
+  if (token === undefined) return refused('invalid_request', 'token is required');
+  const live = await resolveAccess(config, token);
+  if (live === null) return INACTIVE;
+  const { grant } = live;
+  const owned =
+    grant.clientId === client.clientId ||
+    (grant.resource !== null && client.resources.includes(grant.resource));
+  if (!owned) return INACTIVE;
+  return {
+    ok: true,
+    body: {
+      active: true,
+      scope: grant.scopes.join(' '),
+      client_id: grant.clientId,
+      sub: grant.subject,
+      token_type: 'Bearer',
+      iss: config.issuer,
+      iat: Math.floor(live.token.createdAt.getTime() / 1000),
+      exp: Math.floor(live.token.expiresAt.getTime() / 1000),
+      ...(grant.resource === null ? {} : { aud: grant.resource }),
+    },
+  };
+}

package/src/tokens.ts

@@ -5,9 +5,9 @@
 // same one — imported from core by every caller, never re-exported here (`X_HELPER_COPY`).
 
 import { finiteCount, timingSafeEqual } from '@ultimat3/core';
+import { base64Url } from './base64url';
 
-const BASE64URL_UNSAFE = /[+/=]/g;
-const BASE64URL_REPLACEMENTS: Readonly<Record<string, string>> = { '+': '-', '/': '_', '=': '' };
+export { base64Url, base64UrlBytes } from './base64url';
 
 export function randomBytes(length: number): Uint8Array {
   const bytes = new Uint8Array(length);
@@ -15,12 +15,6 @@ export function randomBytes(length: number): Uint8Array {
   return bytes;
 }
 
-export function base64Url(bytes: Uint8Array): string {
-  let binary = '';
-  for (const byte of bytes) binary += String.fromCharCode(byte);
-  return btoa(binary).replace(BASE64URL_UNSAFE, (char) => BASE64URL_REPLACEMENTS[char] ?? '');
-}
-
 /**
  * 32 bytes -> 43 base64url chars. Opaque by construction: it encodes nothing about the user.
  *
@@ -39,23 +33,6 @@ export function randomToken(byteLength = 32): string {
   return base64Url(randomBytes(finiteCount('randomToken', 'byteLength', byteLength, 1)));
 }
 
-/**
- * The inverse of `base64Url`, for the segments of a JWT. Answers `null` rather than throwing
- * because every caller is reading an attacker-supplied string — a `URIError` or an `InvalidCharacterError`
- * escaping from here would turn a coded refusal into a 500, the same reason `readCookie` never throws.
- */
-export function base64UrlBytes(segment: string): Uint8Array<ArrayBuffer> | null {
-  const padded = segment
-    .replaceAll('-', '+')
-    .replaceAll('_', '/')
-    .padEnd(Math.ceil(segment.length / 4) * 4, '=');
-  try {
-    return Uint8Array.from(atob(padded), (char) => char.charCodeAt(0));
-  } catch {
-    return null;
-  }
-}
-
 export function sha256Hex(value: string): string {
   return new Bun.CryptoHasher('sha256').update(value).digest('hex');
 }

package/src/verification-purposes.ts

@@ -0,0 +1,61 @@
+// Single responsibility: the one registry of verification purposes — a name, the mail template it
+// sends, how long its token lives and how its identifier is keyed. Open, not an enum: an invite or
+// an account deletion is the same single-use mailed credential as a reset, so it is declared here
+// once (`defineVerificationPurpose`, `verify.ts`) instead of hand-rolling hashing and compare again.
+
+import { renderCauseValue, renderFixLiteral } from '@ultimat3/core';
+import { AuthError } from './errors';
+
+export interface VerificationPurposeDef {
+  readonly name: string;
+  /** A catalog key, not copy: the body lives in the app's i18n catalog. */
+  readonly template: string;
+  readonly ttlMs: number;
+  /** How the identifier becomes the store key and the mail address. */
+  readonly identifier: (raw: string) => string;
+}
+
+// A Map, never a record keyed by an attacker-reachable string: `consumeVerification` looks a
+// purpose up by whatever name its caller passed, and `__proto__` on an object is not "undeclared".
+const purposes = new Map<string, VerificationPurposeDef>();
+
+const purposeInvalid = (cause: string, fix: string): AuthError =>
+  new AuthError({ code: 'X_VERIFICATION_PURPOSE_INVALID', cause, fix });
+
+/** At boot. A second declaration under one name is refused: two templates for one link. */
+export function registerVerificationPurpose(def: VerificationPurposeDef): void {
+  if (def.name.trim() === '' || def.name !== def.name.trim()) {
+    throw purposeInvalid(
+      `defineVerificationPurpose() was handed the name ${renderCauseValue(def.name)}, which is empty or padded`,
+      "defineVerificationPurpose({ name: 'member-invite', template, ttlMs })   # a non-empty, unpadded name",
+    );
+  }
+  if (def.template.trim() === '') {
+    throw purposeInvalid(
+      `defineVerificationPurpose({ name: '${def.name}' }) has no template, so its token could not be mailed`,
+      `defineVerificationPurpose({ name: '${def.name}', template: 'auth.${def.name}', ttlMs })   # and add the key to your i18n catalog`,
+    );
+  }
+  if (purposes.has(def.name)) {
+    throw purposeInvalid(
+      `the verification purpose '${def.name}' is declared twice, so which template and lifetime it has depends on import order`,
+      `defineVerificationPurpose({ name: '<another-name>', template, ttlMs })   # rename one of the two '${def.name}' declarations, or import the first`,
+    );
+  }
+  purposes.set(def.name, def);
+}
+
+/** The declared purpose, or the 400 an undeclared one is. Never a default. */
+export function verificationPurpose(name: string): VerificationPurposeDef {
+  const def = purposes.get(name);
+  if (def !== undefined) return def;
+  throw new AuthError({
+    code: 'X_VERIFICATION_PURPOSE_UNKNOWN',
+    // The name may be a request field: rendered as a literal, so it cannot forge a log line.
+    cause: `no verification purpose named ${renderCauseValue(name)} is declared`,
+    fix: `defineVerificationPurpose({ name: ${renderFixLiteral(name, "'<purpose>'")}, template: 'auth.<purpose>', ttlMs })   # once, at boot`,
+  });
+}
+
+/** Every declared name, for a test or `x doctor` to list. */
+export const verificationPurposeNames = (): readonly string[] => [...purposes.keys()];

package/src/verify.ts

@@ -1,6 +1,6 @@
-// Single responsibility: email verification and password reset — the two flows where a link in
-// an inbox is a credential. Tokens are single-use, expiring, stored hashed and compared in
-// constant time. Mail leaves through an injected structural `MailSender` port: `@ultimat3/mail` is
+// Single responsibility: every flow where a link in an inbox is a credential — email verification
+// and password reset built in, any other through `defineVerificationPurpose`, one code path.
+// Tokens are single-use, expiring, stored hashed and compared in constant time. Mail leaves through an injected structural `MailSender` port: `@ultimat3/mail` is
 // 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';
@@ -10,6 +10,7 @@ import { normaliseEmail } from './email';
 import { AuthError } from './errors';
 import { assertFiniteAuthCount } from './policy-numbers';
 import { randomToken, sha256Hex } from './tokens';
+import { registerVerificationPurpose, verificationPurpose } from './verification-purposes';
 
 /**
  * `locale` is required, not optional: an inferred locale is how a user gets a security email
@@ -24,18 +25,25 @@ export interface MailSender {
   ): Promise<void>;
 }
 
+/** The two purposes this package declares itself. Any other is `defineVerificationPurpose`'s. */
 export const VERIFICATION_PURPOSES = ['email-verify', 'password-reset'] as const;
 
-export type VerificationPurpose = (typeof VERIFICATION_PURPOSES)[number];
+/**
+ * Open since 30.0: any declared name. A `switch` over it needs a default arm. Undeclared at the
+ * call is `X_VERIFICATION_PURPOSE_UNKNOWN`, never a silent default template.
+ */
+export type VerificationPurpose = string;
+
+type BuiltinPurpose = (typeof VERIFICATION_PURPOSES)[number];
 
 /** Catalog keys, not copy. The template body lives in the app's i18n catalog. */
-export const VERIFICATION_TEMPLATES: Readonly<Record<VerificationPurpose, string>> = {
+export const VERIFICATION_TEMPLATES: Readonly<Record<BuiltinPurpose, string>> = {
   'email-verify': 'auth.email-verify',
   'password-reset': 'auth.password-reset',
 };
 
 /** Short by default: a reset link is a password, and a password that lives a day is a liability. */
-export const DEFAULT_VERIFICATION_TTL_MS: Readonly<Record<VerificationPurpose, number>> = {
+export const DEFAULT_VERIFICATION_TTL_MS: Readonly<Record<BuiltinPurpose, number>> = {
   'email-verify': 24 * 60 * 60 * 1000,
   'password-reset': 60 * 60 * 1000,
 };
@@ -67,6 +75,7 @@ export async function issueVerification(
   runtime: VerificationRuntime,
   input: IssueVerificationInput,
 ): Promise<IssuedVerification> {
+  const purpose = verificationPurpose(input.purpose);
   const now = runtime.clock.now();
   const token = randomToken(32);
   // Screened HERE, above the write, not beside the `Date` it feeds. Unscreened this threw a bare
@@ -77,7 +86,7 @@ export async function issueVerification(
   // had replaced whatever live token that address held on its way to failing.
   const ttl = assertFiniteAuthCount(
     'verification.ttlMs',
-    input.ttlMs ?? DEFAULT_VERIFICATION_TTL_MS[input.purpose],
+    input.ttlMs ?? purpose.ttlMs,
     'the stored expiry is an Invalid Date, `now >= NaN` is false, and the mailed link is a password that never expires',
     1,
   );
@@ -88,10 +97,10 @@ export async function issueVerification(
   // that was per SPELLING, so N live reset tokens for one address could be held at once by varying
   // the case, and each one of them is a password. It is also the address the mail is sent to, so
   // the link goes to the inbox the account is keyed by rather than to whatever a form posted.
-  const identifier = normaliseEmail(input.identifier);
+  const identifier = purpose.identifier(input.identifier);
   await runtime.store.putVerification({
     id: randomToken(12),
-    purpose: input.purpose,
+    purpose: purpose.name,
     identifier,
     tokenHash: sha256Hex(token),
     expiresAt,
@@ -99,7 +108,7 @@ export async function issueVerification(
     createdAt: now,
   });
   await runtime.mail.send(
-    VERIFICATION_TEMPLATES[input.purpose],
+    purpose.template,
     identifier,
     {
       ...(input.data ?? {}),
@@ -139,12 +148,13 @@ export async function consumeVerification(
   runtime: VerificationRuntime,
   input: ConsumeVerificationInput,
 ): Promise<AuthVerification> {
+  const purpose = verificationPurpose(input.purpose);
   const tokenHash = sha256Hex(input.token);
   // Normalised on the way OUT as well as in, or a link issued for `ada@x.test` is unredeemable by
   // a form that posted `Ada@X.test` — one door, one key.
   const record = await runtime.store.takeVerification(
-    input.purpose,
-    normaliseEmail(input.identifier),
+    purpose.name,
+    purpose.identifier(input.identifier),
     tokenHash,
   );
   if (record === null) throw verificationInvalid(input.purpose);
@@ -159,3 +169,67 @@ export async function consumeVerification(
   }
   return record;
 }
+
+export interface DefineVerificationPurposeInput {
+  /** The store key's first half and the name a consume must repeat. Unique, process-wide. */
+  readonly name: string;
+  /** The i18n catalog key of the mail: `'auth.member-invite'`. */
+  readonly template: string;
+  /** Required: how long a mailed credential lives is the app's call, stated once. */
+  readonly ttlMs: number;
+  /** The identifier's one normalisation. Defaults to `normaliseEmail`, the address door's. */
+  readonly identifier?: ((raw: string) => string) | undefined;
+}
+
+export interface VerificationPurposeHandle {
+  readonly name: string;
+  issue(
+    runtime: VerificationRuntime,
+    input: Omit<IssueVerificationInput, 'purpose'>,
+  ): Promise<IssuedVerification>;
+  consume(
+    runtime: VerificationRuntime,
+    input: Omit<ConsumeVerificationInput, 'purpose'>,
+  ): Promise<AuthVerification>;
+}
+
+/**
+ * A single-use mailed credential under its own name — an invite, an email change, an account
+ * deletion — on the one code path the two built-ins run: hashed at rest, consumed on a hash
+ * match in one atomic step, compared in constant time. Call it at module scope, once.
+ */
+export function defineVerificationPurpose(
+  input: DefineVerificationPurposeInput,
+): VerificationPurposeHandle {
+  const ttlMs = assertFiniteAuthCount(
+    `verification.${input.name}.ttlMs`,
+    input.ttlMs,
+    'the stored expiry is an Invalid Date and the mailed link is a credential that never expires',
+    1,
+  );
+  registerVerificationPurpose({
+    name: input.name,
+    template: input.template,
+    ttlMs,
+    identifier: input.identifier ?? normaliseEmail,
+  });
+  const name = input.name;
+  return {
+    name,
+    issue: (runtime, rest) => issueVerification(runtime, { ...rest, purpose: name }),
+    consume: (runtime, rest) => consumeVerification(runtime, { ...rest, purpose: name }),
+  };
+}
+
+/** The two built-ins, as instances: one code path for every purpose. */
+export const emailVerification = defineVerificationPurpose({
+  name: 'email-verify',
+  template: VERIFICATION_TEMPLATES['email-verify'],
+  ttlMs: DEFAULT_VERIFICATION_TTL_MS['email-verify'],
+});
+
+export const passwordReset = defineVerificationPurpose({
+  name: 'password-reset',
+  template: VERIFICATION_TEMPLATES['password-reset'],
+  ttlMs: DEFAULT_VERIFICATION_TTL_MS['password-reset'],
+});

package/src/webauthn-data.ts

@@ -0,0 +1,111 @@
+// Single responsibility: the two structures every WebAuthn ceremony signs over, read from the
+// bytes the browser forwarded — `authenticatorData` (W3C WebAuthn L3 §6.1) and `clientDataJSON`
+// (§5.8.1). Parsing only: what each field must equal is `passkey-verify.ts`'s to decide.
+
+import { canonicalBase64UrlBytes } from './base64url';
+import { type CborValue, decodeCborItem } from './cbor';
+import { isRecord } from './json';
+
+/** User Present, User Verified, Attested credential data, Extension data (§6.1 flags). */
+export const FLAG_UP = 0x01;
+export const FLAG_UV = 0x04;
+export const FLAG_AT = 0x40;
+export const FLAG_ED = 0x80;
+
+/** Longer than this is not a credential id an authenticator mints (§5.8.3, 1023 bytes). */
+const MAX_CREDENTIAL_ID_BYTES = 1023;
+
+export interface AttestedCredential {
+  readonly aaguid: Uint8Array;
+  readonly credentialId: Uint8Array;
+  /** The COSE_Key exactly as the authenticator encoded it — what is stored and re-imported. */
+  readonly publicKey: Uint8Array;
+}
+
+export interface AuthenticatorData {
+  readonly rpIdHash: Uint8Array;
+  readonly flags: number;
+  readonly signCount: number;
+  readonly attested: AttestedCredential | null;
+}
+
+/** `null` for a truncated buffer, trailing bytes, or an attested key that is not one CBOR item. */
+export function parseAuthenticatorData(bytes: Uint8Array): AuthenticatorData | null {
+  if (bytes.length < 37) return null;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const flags = bytes[32] ?? 0;
+  const signCount = view.getUint32(33);
+  let at = 37;
+  let attested: AttestedCredential | null = null;
+  if ((flags & FLAG_AT) !== 0) {
+    if (bytes.length < at + 18) return null;
+    const aaguid = bytes.slice(at, at + 16);
+    const idLength = view.getUint16(at + 16);
+    at += 18;
+    if (idLength === 0 || idLength > MAX_CREDENTIAL_ID_BYTES || at + idLength > bytes.length) {
+      return null;
+    }
+    const credentialId = bytes.slice(at, at + idLength);
+    at += idLength;
+    const key = decodeCborItem(bytes, at);
+    if (key === null || !(key.value instanceof Map)) return null;
+    attested = { aaguid, credentialId, publicKey: bytes.slice(at, key.end) };
+    at = key.end;
+  }
+  if ((flags & FLAG_ED) !== 0) {
+    const extensions = decodeCborItem(bytes, at);
+    if (extensions === null || !(extensions.value instanceof Map)) return null;
+    at = extensions.end;
+  }
+  if (at !== bytes.length) return null;
+  return { rpIdHash: bytes.slice(0, 32), flags, signCount, attested };
+}
+
+export interface ClientData {
+  readonly type: string;
+  /** The challenge as the browser echoed it: base64url TEXT, compared as text. */
+  readonly challenge: string;
+  readonly origin: string;
+  readonly crossOrigin: boolean;
+}
+
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+
+/** `null` unless the bytes are UTF-8 JSON carrying the four fields, each of its type. */
+export function parseClientData(bytes: Uint8Array): ClientData | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(utf8.decode(bytes));
+  } catch {
+    return null;
+  }
+  if (!isRecord(parsed)) return null;
+  const { type, challenge, origin, crossOrigin } = parsed;
+  if (typeof type !== 'string' || typeof origin !== 'string') return null;
+  if (canonicalBase64UrlBytes(challenge) === null || typeof challenge !== 'string') return null;
+  if (crossOrigin !== undefined && typeof crossOrigin !== 'boolean') return null;
+  return { type, challenge, origin, crossOrigin: crossOrigin === true };
+}
+
+export interface AttestationObject {
+  readonly fmt: string;
+  readonly authData: Uint8Array;
+}
+
+/**
+ * The attestation object's `fmt` and `authData`. `attStmt` is read for shape and NOT verified:
+ * registration asks for `attestation: 'none'`, so no statement is trusted for anything — the
+ * credential's key is bound by the signed challenge of every later assertion, not by its vendor.
+ */
+export function parseAttestationObject(bytes: Uint8Array): AttestationObject | null {
+  const decoded = decodeCborItem(bytes);
+  if (decoded === null || decoded.end !== bytes.length || !(decoded.value instanceof Map)) {
+    return null;
+  }
+  const map: ReadonlyMap<number | string, CborValue> = decoded.value;
+  const fmt = map.get('fmt');
+  const authData = map.get('authData');
+  if (typeof fmt !== 'string' || !(authData instanceof Uint8Array)) return null;
+  if (!(map.get('attStmt') instanceof Map)) return null;
+  return { fmt, authData };
+}

package/src/workload.ts

@@ -35,8 +35,28 @@ export interface WorkloadToken {
   readonly claims: WorkloadClaims;
   /** Feed this to `actorFromService()` — the same funnel every other credential goes through. */
   readonly identity: ServiceIdentity;
+  /**
+   * The whole decoded payload, read only after the signature, issuer, audience and time bounds
+   * held: an issuer's own claim (`tid`, `groups`, `azp`) is the app's to judge, and re-decoding the
+   * token to reach it is a second parser beside this one.
+   */
+  readonly raw: Readonly<Record<string, unknown>>;
 }
 
+/** Which check refused a token — a name for a log line, never a claim's value. */
+export type WorkloadCheck =
+  | 'signature'
+  | 'payload'
+  | 'subject'
+  | 'expiry'
+  | 'issuer'
+  | 'audience'
+  | 'not-before';
+
+export type WorkloadTokenCheck =
+  | { readonly ok: true; readonly token: WorkloadToken }
+  | { readonly ok: false; readonly check: WorkloadCheck; readonly reason: string };
+
 export interface VerifyWorkloadTokenInput {
   readonly token: string;
   /** Every issuer this caller may claim. A list, never a wildcard: an unpinned `iss` is no check. */
@@ -77,35 +97,63 @@ const readAudience = (value: unknown): readonly string[] => {
  * wrote it, and every check below would otherwise pass for a token the caller minted themselves.
  */
 export async function verifyWorkloadToken(input: VerifyWorkloadTokenInput): Promise<WorkloadToken> {
+  const checked = await checkWorkloadToken(input);
+  if (!checked.ok) throw refused(checked.reason);
+  return checked.token;
+}
+
+const checkRefusal = (check: WorkloadCheck, reason: string): WorkloadTokenCheck => ({
+  ok: false,
+  check,
+  reason,
+});
+
+/**
+ * `verifyWorkloadToken`'s checks as a verdict rather than a throw, naming the check that refused —
+ * what `jwtBearerResolver` logs. A key source that throws still throws: an unreadable key set is
+ * not a verdict on the token, and the caller decides what it is.
+ */
+export async function checkWorkloadToken(
+  input: VerifyWorkloadTokenInput,
+): Promise<WorkloadTokenCheck> {
   if (!(await verifyJwtSignature(input.token, input.keys))) {
-    throw refused('the signature does not verify against the published key set');
+    return checkRefusal('signature', 'the signature does not verify against the published key set');
   }
 
   const payloadSegment = input.token.split('.')[1];
   const parsed = payloadSegment === undefined ? null : decodeJwtSegment(payloadSegment);
   if (parsed === null) {
-    throw refused('the payload is not base64url-encoded JSON describing an object');
+    return checkRefusal(
+      'payload',
+      'the payload is not base64url-encoded JSON describing an object',
+    );
   }
 
   const iss = parsed['iss'];
   const sub = parsed['sub'];
   const exp = parsed['exp'];
   if (typeof iss !== 'string' || typeof sub !== 'string' || sub === '') {
-    throw refused('the payload carries no iss or sub');
+    return checkRefusal('subject', 'the payload carries no iss or sub');
+  }
+  if (typeof exp !== 'number') return checkRefusal('expiry', 'the payload carries no numeric exp');
+  if (!input.issuers.includes(iss)) {
+    return checkRefusal('issuer', 'the issuer is not one this service accepts');
   }
-  if (typeof exp !== 'number') throw refused('the payload carries no numeric exp');
-  if (!input.issuers.includes(iss)) throw refused('the issuer is not one this service accepts');
 
   const aud = readAudience(parsed['aud']);
-  if (!aud.includes(input.audience)) throw refused('the token is addressed to another audience');
+  if (!aud.includes(input.audience)) {
+    return checkRefusal('audience', 'the token is addressed to another audience');
+  }
 
   const nowMs = input.clock.now().getTime();
   // The same skew the id token path allows, from the same declaration: two servers rarely agree
   // on the second, and a second number here would drift from that one.
-  if (exp * 1000 + ID_TOKEN_CLOCK_SKEW_MS <= nowMs) throw refused('the token is already expired');
+  if (exp * 1000 + ID_TOKEN_CLOCK_SKEW_MS <= nowMs) {
+    return checkRefusal('expiry', 'the token is already expired');
+  }
   const nbf = parsed['nbf'];
   if (typeof nbf === 'number' && nbf * 1000 - ID_TOKEN_CLOCK_SKEW_MS > nowMs) {
-    throw refused('the token is not valid yet');
+    return checkRefusal('not-before', 'the token is not valid yet');
   }
   const iat = parsed['iat'];
 
@@ -119,13 +167,17 @@ export async function verifyWorkloadToken(input: VerifyWorkloadTokenInput): Prom
     ...(typeof iat === 'number' ? { iat } : {}),
   };
   return {
-    claims,
-    identity: {
-      // The SPIFFE ID, the service account's `system:serviceaccount:ns:name`, or the IMDS
-      // principal — whichever the issuer put there. Never rewritten, so a trace names the caller.
-      id: claims.sub,
-      scopes: claims.scopes,
-      ...(input.orgId === undefined ? {} : { orgId: input.orgId }),
+    ok: true,
+    token: {
+      claims,
+      identity: {
+        // The SPIFFE ID, the service account's `system:serviceaccount:ns:name`, or the IMDS
+        // principal — whichever the issuer put there. Never rewritten, so a trace names the caller.
+        id: claims.sub,
+        scopes: claims.scopes,
+        ...(input.orgId === undefined ? {} : { orgId: input.orgId }),
+      },
+      raw: parsed,
     },
   };
 }