@_mustachio/openauth 0.9.2 → 0.11.0

package/src/domain/dpop.ts

@@ -0,0 +1,293 @@
+/**
+ * DPoP — Demonstration of Proof-of-Possession (RFC 9449).
+ *
+ * The RP/client generates an asymmetric key pair, sends a fresh proof
+ * JWT with each authenticated request, and the IdP binds the issued
+ * access token to the public key's SHA-256 thumbprint (`cnf.jkt`).
+ *
+ * This module parses + verifies DPoP proof JWTs. Replay protection is
+ * delegated to `TokenStore.recordDpopJti`; adapters without that method
+ * cannot satisfy DPoP and the verifier returns `invalid_dpop_proof`.
+ *
+ * Per RFC 9449 §4.2/§4.3, the proof JWT carries:
+ *   - header: `typ: "dpop+jwt"`, `alg: <asymmetric>`, `jwk: <pub-JWK>`
+ *   - payload: `htu`, `htm`, `iat`, `jti`, optional `ath`, optional `nonce`
+ *
+ * Verification chain (§4.3):
+ *   1. Header `typ` is exactly `"dpop+jwt"`.
+ *   2. `alg` is in the asymmetric allow-list (`ES256`, `EdDSA`).
+ *   3. `jwk` is a public key in JWK form; signature verifies under it.
+ *   4. `htm` equals the request method (case-sensitive).
+ *   5. `htu` equals the request URI (scheme + host + path; query / frag stripped).
+ *   6. `iat` is within ±`iatToleranceSec` of `now`.
+ *   7. `jti` has not been seen within the replay window (TokenStore-tracked).
+ *   8. If `expectedAth` supplied (resource-server check), `ath` matches.
+ *
+ * The thumbprint (`jkt`) is computed via RFC 7638 over the public JWK.
+ */
+import type { JWK, KeyLike } from "jose"
+import {
+  calculateJwkThumbprint,
+  decodeProtectedHeader,
+  importJWK,
+  jwtVerify,
+} from "jose"
+
+import type { TokenStore } from "../ports/token-store"
+import { authError, type AuthError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+
+import { base64url, sha256, utf8 } from "./crypto"
+
+/** Allow-list of `alg` values accepted in DPoP proofs. Asymmetric only. */
+const DPOP_ASYMMETRIC_ALGS: ReadonlySet<string> = new Set(["ES256", "EdDSA"])
+
+/** RFC 9449 §4.2 — fixed 60-second tolerance is the conventional default. */
+export const DEFAULT_DPOP_IAT_TOLERANCE_SEC = 60
+
+/** Replay-window TTL for `jti` tracking. Matches `iat` tolerance × 2. */
+export const DEFAULT_DPOP_JTI_TTL_MS = 2 * DEFAULT_DPOP_IAT_TOLERANCE_SEC * 1000
+
+export type DpopProofPayload = {
+  htu: string
+  htm: string
+  iat: number
+  jti: string
+  ath?: string
+  nonce?: string
+}
+
+export type VerifiedDpopProof = {
+  /** RFC 7638 JWK thumbprint of the proof's public key. */
+  jkt: string
+  /** The decoded + signature-verified proof payload. */
+  payload: DpopProofPayload
+}
+
+export type VerifyDpopProofInput = {
+  proofJwt: string
+  /** Actual request URI (scheme + host + port + path; query/frag stripped). */
+  htu: string
+  /** Actual HTTP method, uppercase. */
+  htm: string
+  /** Wall clock seconds. */
+  nowSec: number
+  /** Optional skew allowance. */
+  iatToleranceSec?: number
+  /**
+   * Required at resource servers when the proof must bind to a presented
+   * access token. The verifier checks the proof's `ath` equals
+   * base64url(SHA-256(access_token ASCII)). Omit at the AS `/token`
+   * endpoint — no access token exists yet there.
+   */
+  expectedAth?: string
+}
+
+export type VerifyDpopProofDeps = {
+  tokenStore: TokenStore
+  jtiTtlMs?: number
+}
+
+/**
+ * Verify a DPoP proof JWT and return its `jkt` + payload. Side-effect:
+ * records the `jti` in `TokenStore` so a replay within the TTL window
+ * is rejected.
+ */
+export async function verifyDpopProof(
+  input: VerifyDpopProofInput,
+  deps: VerifyDpopProofDeps,
+): Promise<Result<VerifiedDpopProof, AuthError>> {
+  if (!deps.tokenStore.recordDpopJti) {
+    return err(
+      authError.invalidDpopProof(
+        "token-store adapter does not support DPoP replay protection",
+      ),
+    )
+  }
+  // 1. Decode the header to recover the embedded JWK + check `typ`/`alg`
+  //    before the signature verification call so we can return precise
+  //    errors instead of a generic jose failure.
+  let header: ReturnType<typeof decodeProtectedHeader>
+  try {
+    header = decodeProtectedHeader(input.proofJwt)
+  } catch (e) {
+    return err(
+      authError.invalidDpopProof(
+        `dpop proof header is not a valid compact JWS: ${stringifyError(e)}`,
+      ),
+    )
+  }
+  if (header.typ !== "dpop+jwt") {
+    return err(
+      authError.invalidDpopProof(
+        `dpop proof header.typ must be "dpop+jwt", got "${String(header.typ)}"`,
+      ),
+    )
+  }
+  if (!header.alg || !DPOP_ASYMMETRIC_ALGS.has(header.alg)) {
+    return err(
+      authError.invalidDpopProof(
+        `dpop proof alg "${String(header.alg)}" not in {ES256, EdDSA}`,
+      ),
+    )
+  }
+  const jwk = header.jwk as JWK | undefined
+  if (!jwk || typeof jwk !== "object") {
+    return err(
+      authError.invalidDpopProof(
+        "dpop proof header.jwk missing or not an object",
+      ),
+    )
+  }
+  // §4.2: the embedded JWK MUST be a public key. Reject anything that
+  // looks like a private key (`d` for EC / OKP, `d`+`p`+`q` for RSA).
+  if ("d" in jwk) {
+    return err(
+      authError.invalidDpopProof(
+        "dpop proof header.jwk must be a public key (private material present)",
+      ),
+    )
+  }
+
+  // 2. Verify the signature with the embedded JWK.
+  let key: KeyLike
+  try {
+    key = (await importJWK(jwk, header.alg)) as KeyLike
+  } catch (e) {
+    return err(
+      authError.invalidDpopProof(
+        `dpop proof JWK import failed: ${stringifyError(e)}`,
+      ),
+    )
+  }
+  let verified
+  try {
+    verified = await jwtVerify(input.proofJwt, key, {
+      algorithms: [header.alg],
+    })
+  } catch (e) {
+    return err(
+      authError.invalidDpopProof(
+        `dpop proof signature verification failed: ${stringifyError(e)}`,
+      ),
+    )
+  }
+  const payload = verified.payload as Partial<DpopProofPayload>
+
+  // 3. Payload-shape checks. The compact set: htu, htm, iat, jti.
+  if (typeof payload.htm !== "string") {
+    return err(authError.invalidDpopProof("dpop proof missing string htm"))
+  }
+  if (typeof payload.htu !== "string") {
+    return err(authError.invalidDpopProof("dpop proof missing string htu"))
+  }
+  if (typeof payload.iat !== "number") {
+    return err(authError.invalidDpopProof("dpop proof missing numeric iat"))
+  }
+  if (typeof payload.jti !== "string" || payload.jti.length === 0) {
+    return err(
+      authError.invalidDpopProof("dpop proof missing non-empty string jti"),
+    )
+  }
+
+  // 4. htm / htu equality.
+  if (payload.htm !== input.htm) {
+    return err(
+      authError.invalidDpopProof(
+        `dpop htm "${payload.htm}" does not match request method "${input.htm}"`,
+      ),
+    )
+  }
+  if (payload.htu !== input.htu) {
+    return err(
+      authError.invalidDpopProof(
+        `dpop htu "${payload.htu}" does not match request uri "${input.htu}"`,
+      ),
+    )
+  }
+
+  // 5. iat freshness.
+  const tolerance = input.iatToleranceSec ?? DEFAULT_DPOP_IAT_TOLERANCE_SEC
+  const skew = Math.abs(input.nowSec - payload.iat)
+  if (skew > tolerance) {
+    return err(
+      authError.invalidDpopProof(
+        `dpop iat skew ${skew}s exceeds tolerance ${tolerance}s`,
+      ),
+    )
+  }
+
+  // 6. ath check (RS use only).
+  if (input.expectedAth !== undefined) {
+    if (typeof payload.ath !== "string" || payload.ath !== input.expectedAth) {
+      return err(
+        authError.invalidDpopProof(
+          "dpop ath does not match SHA-256 of the access token",
+        ),
+      )
+    }
+  }
+
+  // 7. jti replay protection — atomic record-or-fail in the token store.
+  const recorded = await deps.tokenStore.recordDpopJti(
+    payload.jti,
+    deps.jtiTtlMs ?? DEFAULT_DPOP_JTI_TTL_MS,
+  )
+  if (isErr(recorded)) {
+    return err(
+      authError.invalidDpopProof(`dpop jti "${payload.jti}" replayed`, {
+        jti: payload.jti,
+      }),
+    )
+  }
+
+  // 8. Compute jkt thumbprint (RFC 7638) — bound onto the issued token.
+  let jkt: string
+  try {
+    jkt = await calculateJwkThumbprint(jwk, "sha256")
+  } catch (e) {
+    return err(
+      authError.invalidDpopProof(
+        `dpop jkt thumbprint computation failed: ${stringifyError(e)}`,
+      ),
+    )
+  }
+
+  return ok({
+    jkt,
+    payload: {
+      htm: payload.htm,
+      htu: payload.htu,
+      iat: payload.iat,
+      jti: payload.jti,
+      ...(payload.ath !== undefined ? { ath: payload.ath } : {}),
+      ...(payload.nonce !== undefined ? { nonce: payload.nonce } : {}),
+    },
+  })
+}
+
+/**
+ * Canonicalize a request URL for `htu` comparison (RFC 9449 §4.3).
+ * Strips query string and fragment; preserves scheme, host, port, path.
+ * Default port for the scheme is removed.
+ */
+export function canonicalHtu(rawUrl: string): string {
+  const u = new URL(rawUrl)
+  u.search = ""
+  u.hash = ""
+  // Normalize default ports per the URL spec — `new URL("https://x:443").port` is "".
+  return u.toString()
+}
+
+/**
+ * Compute the `ath` value (RFC 9449 §4.2): base64url(SHA-256(access_token ASCII)).
+ * Resource servers compare the presented DPoP proof's `ath` to this.
+ */
+export async function computeAth(accessToken: string): Promise<string> {
+  return base64url.encode(await sha256(utf8.encode(accessToken)))
+}
+
+function stringifyError(e: unknown): string {
+  return e instanceof Error ? e.message : String(e)
+}

package/src/domain/id-token.ts

@@ -0,0 +1,213 @@
+/**
+ * `id_token` assembly — claim selection, scope gating, `at_hash`, `amr`
+ * derivation.
+ *
+ * OIDC Core §2 mandates `iss`, `sub`, `aud`, `exp`, `iat`. `auth_time` is
+ * required when `max_age` was requested or `auth_time` is essential; we
+ * always include it because we always know it (stamped at `success`).
+ * `nonce` is required to echo the RP's `/authorize` value when present.
+ *
+ * Scope→claim mapping follows OIDC Core §5.4 exactly. Properties are
+ * sourced from `SubjectClaim.properties` — hosts populate that record in
+ * their `IdPOptions.success` callback. We only emit a profile claim
+ * when (a) the corresponding scope was granted and (b) the value is a
+ * recognized JSON-serializable type. Unknown values are silently
+ * dropped (forward compat with subject schemas the host adds later).
+ *
+ * `at_hash` is computed per §3.1.3.6: left-half SHA-256 of the access
+ * token's ASCII octets, base64url-encoded with no padding.
+ *
+ * `amr` (RFC 8176) is derived from `methodKind` via a small fixed table.
+ * Methods that aren't in the table simply omit the claim — `amr` is
+ * optional. Hosts that want richer amr semantics should add the claim
+ * via the host claim hook (Phase E).
+ */
+import { base64url, sha256, utf8 } from "./crypto"
+import type { ClaimsRequest } from "../types/authorization"
+import type { IdTokenClaims, ScopedProfileClaims } from "../types/token"
+import type { SubjectClaim } from "../types/subject"
+
+/**
+ * Map of OIDC scope name → list of profile claim names that scope grants
+ * (OIDC Core §5.4). `openid` itself is the discriminator that an id_token
+ * should be issued at all — it grants no profile claims.
+ */
+const SCOPE_TO_CLAIMS: Record<string, ReadonlyArray<string>> = {
+  profile: [
+    "name",
+    "given_name",
+    "family_name",
+    "middle_name",
+    "nickname",
+    "preferred_username",
+    "profile",
+    "picture",
+    "website",
+    "gender",
+    "birthdate",
+    "zoneinfo",
+    "locale",
+    "updated_at",
+  ],
+  email: ["email", "email_verified"],
+  phone: ["phone_number", "phone_number_verified"],
+  address: ["address"],
+}
+
+/**
+ * Derive `amr` from the originating `methodKind`. Values are RFC 8176
+ * registered AMR codes. Returns `undefined` when no clean mapping exists
+ * — `amr` is an OPTIONAL id_token claim, so omission is spec-compliant.
+ */
+export function deriveAmr(methodKind: string): string[] | undefined {
+  switch (methodKind) {
+    case "password":
+      return ["pwd"]
+    case "code":
+      return ["otp"]
+    case "passkey":
+      // Resident credentials backed by a platform authenticator. Best
+      // approximated by `hwk` (hardware key) per RFC 8176; platform
+      // authenticators are usually hardware-backed (Secure Enclave,
+      // TPM, etc.) even when the key is software-resident on disk.
+      return ["hwk"]
+    default:
+      // External federated providers (google, github, oidc-generic, …)
+      // — no standardized AMR for "logged in elsewhere", so omit.
+      return undefined
+  }
+}
+
+/**
+ * `at_hash` per OIDC Core §3.1.3.6: left-half of SHA-256(access_token
+ * ASCII), base64url. Always 16 bytes → 22 base64url characters for
+ * SHA-256 (256-bit → 128-bit half → 16 bytes → 22 chars).
+ */
+export async function computeAtHash(accessToken: string): Promise<string> {
+  const digest = await sha256(utf8.encode(accessToken))
+  const half = digest.slice(0, digest.byteLength / 2)
+  return base64url.encode(half)
+}
+
+/**
+ * Filter a `SubjectClaim.properties` record down to claims granted by the
+ * requested OIDC scopes, then optionally augment with claim names the RP
+ * specifically requested via the OIDC Core §5.5 `claims` parameter.
+ * Returns a typed `ScopedProfileClaims` ready to spread into the id_token
+ * or `/userinfo` response. Properties not named by any granted scope or
+ * explicit claim request are dropped.
+ *
+ * `extra` is the set of claim names the RP requested via `claims`
+ * parameter for THIS surface (id_token vs userinfo). Listing a name in
+ * `extra` bypasses scope gating per §5.5 ("works without the requestor
+ * having to include the scope value").
+ *
+ * `customMappings` is a host-supplied scope → claim-names map merged on
+ * top of the OIDC Core §5.4 table. Lets the host expose vendor-specific
+ * identity fields (e.g. `tenant_id`, `org_role`) via a custom scope
+ * (`scope=foo` granting `[tenant_id, …]`). Reserved §5.4 names cannot be
+ * shadowed — the standard mapping always wins on collision so an
+ * `email` scope can't accidentally start meaning something else.
+ *
+ * Host-supplied values are trusted to match their declared OIDC types
+ * — schemas live on `IdPOptions.subjects`, not here. The narrowing cast
+ * is the boundary between "host's responsibility" and "framework's
+ * responsibility."
+ */
+export function pickScopedClaims(
+  claim: SubjectClaim,
+  scopes: ReadonlyArray<string>,
+  extra: ReadonlyArray<string> = [],
+  customMappings: Record<string, ReadonlyArray<string>> = {},
+): ScopedProfileClaims {
+  const props = (claim as { properties: Record<string, unknown> }).properties
+  if (!props || typeof props !== "object") return {}
+  // Standard §5.4 names take precedence: spread custom first, then
+  // SCOPE_TO_CLAIMS, so a host can't override `email → [email, ...]`.
+  const mappings: Record<string, ReadonlyArray<string>> = {
+    ...customMappings,
+    ...SCOPE_TO_CLAIMS,
+  }
+  const granted = new Set<string>()
+  for (const scope of scopes) {
+    const list = mappings[scope]
+    if (!list) continue
+    for (const c of list) granted.add(c)
+  }
+  for (const name of extra) granted.add(name)
+  const out: Record<string, unknown> = {}
+  for (const key of granted) {
+    if (key in props && props[key] !== undefined) out[key] = props[key]
+  }
+  return out as ScopedProfileClaims
+}
+
+export type BuildIdTokenInput = {
+  issuerUrl: string
+  /** RP `client_id` — the id_token's `aud`. */
+  audience: string
+  /** Stable subject identifier (same value as the access token's `sub`). */
+  subjectId: string
+  claim: SubjectClaim
+  scopes: ReadonlyArray<string>
+  /** Seconds-since-epoch the user authenticated. */
+  authTime: number
+  /** RP-supplied OIDC nonce, when present. */
+  appNonce?: string
+  /** Wall clock (ms). */
+  now: number
+  /** id_token TTL (ms). Default 5 minutes. */
+  ttlMs?: number
+  /** Method kind for `amr` derivation. */
+  methodKind: string
+  /** Pre-signed access token whose `at_hash` is bound into the id_token. */
+  accessToken: string
+  /** OIDC Core §5.5 — RP-requested claims (this drives only id_token here). */
+  claimsRequest?: ClaimsRequest
+  /**
+   * Host-supplied vendor scope → claim-names map. Merged on top of OIDC
+   * Core §5.4 at scope-gating time. See `pickScopedClaims`.
+   */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
+}
+
+export const DEFAULT_ID_TOKEN_TTL_MS = 5 * 60 * 1000
+
+/**
+ * Assemble an `IdTokenClaims` object. Pure — no crypto except `at_hash`.
+ * Caller signs the result via `signIdToken`.
+ *
+ * Composition is via spread so the type stays narrow: the base claim set
+ * (REQUIRED OIDC §2 + auth_time + at_hash + optional nonce/amr) is built
+ * first; the scope-gated §5.1 profile claims merge over the top via
+ * `...pickScopedClaims(...)`. No dynamic index assignment, no cast.
+ */
+export async function buildIdTokenClaims(
+  input: BuildIdTokenInput,
+): Promise<IdTokenClaims> {
+  const ttl = input.ttlMs ?? DEFAULT_ID_TOKEN_TTL_MS
+  const amr = deriveAmr(input.methodKind)
+  const extraClaims = Object.keys(input.claimsRequest?.id_token ?? {})
+  return {
+    iss: input.issuerUrl,
+    sub: input.subjectId,
+    aud: input.audience,
+    exp: Math.floor((input.now + ttl) / 1000),
+    iat: Math.floor(input.now / 1000),
+    auth_time: input.authTime,
+    at_hash: await computeAtHash(input.accessToken),
+    ...(input.appNonce !== undefined ? { nonce: input.appNonce } : {}),
+    ...(amr ? { amr } : {}),
+    ...pickScopedClaims(
+      input.claim,
+      input.scopes,
+      extraClaims,
+      input.customScopeClaims ?? {},
+    ),
+  }
+}
+
+/** Predicate: does this token request warrant an `id_token` being issued? */
+export function shouldIssueIdToken(scopes: ReadonlyArray<string>): boolean {
+  return scopes.includes("openid")
+}

package/src/domain/introspect.ts

@@ -0,0 +1,155 @@
+/**
+ * `/introspect` endpoint logic (RFC 7662).
+ *
+ * RFC 7662 §2.1 REQUIRES authentication: "To prevent token scanning
+ * attacks, the endpoint MUST also require some form of authorization to
+ * access this endpoint." Confidential-client credentials are validated
+ * against the **presenter's** tenant — resolved by the HTTP layer from
+ * the request, exactly the same way `/token client_credentials` resolves
+ * tenant. Authenticating before touching the token's `tid` means:
+ *
+ *   - Unknown presenting client OR wrong secret → `invalid_client`
+ *     (uniform — the response says nothing about the token).
+ *   - Token belongs to a different tenant than the presenter, or names a
+ *     different client as audience, or fails verification → `{active: false}`.
+ *
+ * Pre-fix the order was "verify token → load token's tenant → look up
+ * presenter in *that* tenant", which let a client authenticated in
+ * tenant X probe whether its `client_id` existed in tenant Y by
+ * watching for `invalid_client` versus `{active: false}` responses.
+ *
+ * Audience check (RFC 7662 §2.2): an authenticated client may only
+ * inspect tokens that name it as the audience. Tokens belonging to a
+ * different client return `{ active: false }` — never a structured
+ * error — to avoid leaking which tokens exist.
+ *
+ * Refresh tokens are not introspectable here; RFC 7662 §2.1 only
+ * requires access-token introspection, and our refresh tokens are
+ * opaque and don't carry the standard introspection metadata.
+ */
+import type { ConfigStore } from "../ports/config-store"
+import type { KeyStore } from "../ports/key-store"
+import type { AuthError } from "../types/error"
+import { authError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { AccessTokenClaims } from "../types/token"
+import type { TenantId } from "../types/tenant"
+
+import { verifyClientCredentials } from "./client-auth"
+import { verifyAccessToken } from "./jwt"
+
+export type IntrospectResponse =
+  | { active: false }
+  | {
+      active: true
+      sub: string
+      aud: string
+      iss: string
+      exp: number
+      iat: number
+      scope?: string
+      client_id?: string
+      /** RFC 7662 §2.2 — the token's type indicator. */
+      token_type: "Bearer" | "DPoP"
+      tid: string
+      mid?: string
+      mkind?: string
+      /** Library-specific — subject schema discriminator (e.g. "user", "admin"). */
+      subject_type?: string
+      /** RFC 9449 §6 — present when the access token is DPoP-bound. */
+      cnf?: { jkt: string }
+    }
+
+export type IntrospectRequest = {
+  token: string
+  tokenTypeHint?: "access_token" | "refresh_token"
+  /** REQUIRED — RFC 7662 §2.1. */
+  clientId: string
+  clientSecret?: string
+  /**
+   * The tenant the presenting client belongs to. Resolved by the HTTP
+   * layer via `IdPOptions.resolveTenant`, just like for the m2m grant.
+   * Cross-tenant introspection collapses to `{active: false}` regardless
+   * of whether the presenter's client exists in the token's tenant.
+   */
+  presenterTenantId: TenantId
+}
+
+export type IntrospectDeps = {
+  keyStore: KeyStore
+  configStore: ConfigStore
+  /** Expected issuer for additional validation. */
+  issuerUrl?: string
+}
+
+export async function introspect(
+  req: IntrospectRequest,
+  deps: IntrospectDeps,
+): Promise<Result<IntrospectResponse, AuthError>> {
+  // 1. Authenticate the presenting client against its OWN tenant before
+  //    looking at the token. Failure here = `invalid_client` (RFC 7662
+  //    §2.1). The presenter's tenant is the only signal we trust until
+  //    auth succeeds.
+  const presenterTenantCfg = await deps.configStore.getTenantConfig(
+    req.presenterTenantId,
+  )
+  if (isErr(presenterTenantCfg)) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`))
+  }
+  const presenter = presenterTenantCfg.value.clients.find(
+    (c) => c.id === req.clientId,
+  )
+  if (!presenter) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`))
+  }
+  const authErr = await verifyClientCredentials(presenter, req.clientSecret)
+  if (authErr) return err(authErr)
+
+  // 2. Try to verify the token. Unverifiable / wrong issuer / expired →
+  //    `{active: false}` so a presenter cannot tell the difference
+  //    between a forged token and a valid one belonging to another
+  //    tenant or client.
+  const keysRes = await deps.keyStore.signingKeys()
+  if (isErr(keysRes)) return err(keysRes.error)
+  let claims: AccessTokenClaims | null
+  try {
+    claims = await verifyAccessToken(req.token, keysRes.value, {
+      ...(deps.issuerUrl ? { issuer: deps.issuerUrl } : {}),
+    })
+  } catch {
+    return ok({ active: false })
+  }
+
+  // 3. Token's tenant must match the presenter's tenant. RFC 7662 lets
+  //    us return `{active: false}` here — never a structured error —
+  //    so a presenter can't probe across tenants. (H6 of the
+  //    post-rebuild review.)
+  if ((claims.tid as TenantId) !== req.presenterTenantId) {
+    return ok({ active: false })
+  }
+
+  // 4. Audience check (RFC 7662 §2.2): only the client the token names
+  //    as audience may see its claims.
+  if (claims.aud !== req.clientId) {
+    return ok({ active: false })
+  }
+
+  const subjectType = (claims.claim as { type?: string } | undefined)?.type
+  return ok({
+    active: true,
+    sub: claims.sub,
+    aud: claims.aud,
+    iss: claims.iss,
+    exp: claims.exp,
+    iat: claims.iat,
+    scope: claims.scope,
+    client_id: claims.aud,
+    token_type: claims.cnf?.jkt !== undefined ? "DPoP" : "Bearer",
+    tid: claims.tid,
+    mid: claims.mid,
+    mkind: claims.mkind,
+    ...(subjectType !== undefined ? { subject_type: subjectType } : {}),
+    ...(claims.cnf !== undefined ? { cnf: claims.cnf } : {}),
+  })
+}