@_mustachio/openauth 0.9.2 → 0.10.0

package/src/domain/refresh.ts

@@ -0,0 +1,169 @@
+/**
+ * `/token` endpoint logic for `grant_type=refresh_token`.
+ *
+ * Rotation semantics (plan §"Cross-cutting Decisions" + §"Port consistency
+ * contracts"):
+ *
+ *  - Refresh tokens rotate on every use. The presented token is consumed
+ *    (CAS); a fresh refresh token is issued, keyed by the same `family`.
+ *  - If the same token is presented a second time within the reuse window
+ *    (default 60 s), the family is revoked and the request is rejected
+ *    with `invalid_grant`. Audit: `refresh_reuse_detected`.
+ *  - Outside the reuse window the row should be GC'd; presentation
+ *    returns `invalid_grant` ("unknown token").
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { ConfigStore } from "../ports/config-store"
+import type { KeyStore } from "../ports/key-store"
+import type { TokenStore } from "../ports/token-store"
+import { authError, type AuthError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr } from "../types/result"
+import type { TenantContext } from "../types/tenant"
+import type { TokenResponse } from "../types/token"
+
+import { safeAudit } from "./audit"
+import { verifyClientCredentials } from "./client-auth"
+import { mintTokens } from "./token"
+
+export type RefreshGrantRequest = {
+  grantType: "refresh_token"
+  refreshToken: string
+  /** Optional per RFC 6749 — narrow scope. If absent, original scopes are reused. */
+  scope?: string
+  /** Confidential clients authenticate at /token. */
+  clientId?: string
+  clientSecret?: string
+}
+
+export type RefreshTokensDeps = {
+  configStore: ConfigStore
+  tokenStore: TokenStore
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  issuerUrl: string
+  clock: () => number
+  /** Reuse-detection window (ms). Default 60 s. */
+  reuseWindowMs?: number
+  newRefreshToken?: () => string
+}
+
+export async function refreshTokens(
+  req: RefreshGrantRequest,
+  deps: RefreshTokensDeps,
+): Promise<Result<TokenResponse, AuthError>> {
+  // Peek before consuming so we can authenticate the client without
+  // burning the token on auth failures (RFC 6749 §6).
+  const peek = await deps.tokenStore.peekRefresh(req.refreshToken)
+  if (isErr(peek)) return err(peek.error)
+  const peekedPayload = peek.value
+
+  const tenantCfg = await deps.configStore.getTenantConfig(
+    peekedPayload.tenantId,
+  )
+  if (isErr(tenantCfg)) return err(tenantCfg.error)
+
+  // Authenticate the *presenting* client first, then check ownership.
+  // Wrong-secret, wrong-client, and unknown-presenting-client all collapse
+  // to the same `invalid_grant` response so an attacker holding a stolen
+  // refresh token cannot probe candidate `client_id` values: every
+  // misroute looks identical on the wire (RFC 6749 §5.2; H4 of the
+  // post-rebuild review).
+  const INVALID_REFRESH_DESC = "refresh token is invalid"
+  const client = tenantCfg.value.clients.find(
+    (c) => c.id === peekedPayload.clientId,
+  )
+  if (!client) {
+    return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+  }
+
+  if (req.clientId !== undefined) {
+    const presenting = tenantCfg.value.clients.find(
+      (c) => c.id === req.clientId,
+    )
+    if (!presenting) {
+      return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+    }
+    const authErr = await verifyClientCredentials(presenting, req.clientSecret)
+    if (authErr) return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+    if (req.clientId !== peekedPayload.clientId) {
+      return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+    }
+  } else if (client.type === "confidential") {
+    return err(authError.invalidGrant(INVALID_REFRESH_DESC))
+  }
+
+  const consumed = await deps.tokenStore.consumeRefresh(req.refreshToken, {
+    reuseWindowMs: deps.reuseWindowMs,
+  })
+  if (isErr(consumed)) {
+    if (consumed.error.code === "invalid_grant" && consumed.error.reuseSignal) {
+      // Reuse-detection signal arrives typed on the AuthError. tenantId /
+      // subjectId come from the signal when the adapter emits it; we fall
+      // back to the peeked payload's fields for adapters that don't
+      // (older 4th-party adapters that satisfy the port without the
+      // structured carrier). `family` always prefers the signal — it's
+      // the discriminating identifier the adapter knows.
+      const signal = consumed.error.reuseSignal
+      await safeAudit(deps, {
+        kind: "refresh_reuse_detected",
+        tenantId: peekedPayload.tenantId,
+        clientId: peekedPayload.clientId,
+        family: signal.family,
+        timestamp: deps.clock(),
+      })
+    }
+    return err(consumed.error)
+  }
+  const payload = consumed.value
+
+  // Narrow scope if requested (must be subset of original).
+  const requestedScopes = req.scope
+    ? req.scope.split(" ").filter(Boolean)
+    : payload.scopes
+  for (const s of requestedScopes) {
+    if (!payload.scopes.includes(s)) {
+      return err(
+        authError.invalidScope(
+          `requested scope "${s}" not granted by original refresh token`,
+        ),
+      )
+    }
+  }
+
+  const tenant: TenantContext = {
+    id: payload.tenantId,
+    config: tenantCfg.value,
+    request: { raw: new Request("about:blank"), custom: {} },
+  }
+
+  return mintTokens({
+    tenant,
+    claim: payload.claim,
+    payload: {
+      tenantId: payload.tenantId,
+      clientId: payload.clientId,
+      // Carry original method provenance forward — descendant tokens
+      // surface the method that started the chain via `mid` / `mkind`,
+      // not the grant-type literal "refresh".
+      methodId: payload.methodId,
+      methodKind: payload.methodKind,
+      scopes: requestedScopes,
+      audience: payload.audience,
+    },
+    family: payload.family,
+    deps,
+  }).then(async (result) => {
+    if (result.ok) {
+      await safeAudit(deps, {
+        kind: "token_refreshed",
+        tenantId: payload.tenantId,
+        clientId: payload.clientId,
+        subjectId: payload.subjectId,
+        family: payload.family,
+        timestamp: deps.clock(),
+      })
+    }
+    return result
+  })
+}

package/src/domain/revoke.ts

@@ -0,0 +1,161 @@
+/**
+ * `/revoke` endpoint logic (RFC 7009).
+ *
+ * Access tokens are stateless JWTs in this IdP; revocation has to wait
+ * for natural expiry. `tokenTypeHint: "access_token"` resolves to a
+ * no-op per RFC 7009 §2.2 (invalid hint is ignored).
+ *
+ * Refresh tokens are server-side state. RFC 7009 §2.2 requires the
+ * authorization server to verify that the presented token was issued to
+ * the authenticated client and refuse otherwise. We implement this via
+ * `peekRefresh` (non-destructive) → ownership check → `consumeRefresh`
+ * (destructive). The peek/consume race is benign: if a concurrent caller
+ * consumes the token in between, our consume returns `invalid_grant`,
+ * which RFC 7009 §2.2 says we treat as a successful no-op.
+ *
+ * Anonymous revoke (no `client_id`) is permitted only for tokens issued
+ * to public clients. Confidential-client tokens MUST authenticate per
+ * RFC 7009 §2.1.
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { ConfigStore } from "../ports/config-store"
+import type { TokenStore } from "../ports/token-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 { TenantId } from "../types/tenant"
+
+import { safeAudit } from "./audit"
+import { verifyClientCredentials } from "./client-auth"
+
+export type RevokeRequest = {
+  token: string
+  /** RFC 7009 hint: `"access_token"` or `"refresh_token"`. */
+  tokenTypeHint?: "access_token" | "refresh_token"
+  /** Optional — required when revoking a confidential client's token. */
+  clientId?: string
+  clientSecret?: string
+}
+
+export type RevokeDeps = {
+  tokenStore: TokenStore
+  configStore: ConfigStore
+  auditLog?: AuditLog
+  clock: () => number
+}
+
+/**
+ * Revoke a single refresh token. Anonymous revokes are accepted for
+ * public-client tokens; confidential-client tokens require valid
+ * credentials.
+ */
+export async function revokeToken(
+  req: RevokeRequest,
+  deps: RevokeDeps,
+): Promise<Result<void, AuthError>> {
+  if (req.tokenTypeHint === "access_token") {
+    return ok(undefined)
+  }
+
+  // RFC 7009 §2.2: unknown tokens are successful no-ops. Peek tells us
+  // the token's owner without consuming so we can authenticate first.
+  const peek = await deps.tokenStore.peekRefresh(req.token)
+  if (isErr(peek)) {
+    return ok(undefined)
+  }
+  const payload = peek.value
+
+  // Load the issuing client so we can decide whether auth is required.
+  const tenantCfg = await deps.configStore.getTenantConfig(payload.tenantId)
+  if (isErr(tenantCfg)) {
+    // Tenant evaporated. Treat as no-op — caller can't usefully retry.
+    return ok(undefined)
+  }
+  const client = tenantCfg.value.clients.find((c) => c.id === payload.clientId)
+  if (!client) {
+    return ok(undefined)
+  }
+
+  // Confidential clients MUST authenticate per RFC 7009 §2.1.
+  if (client.type === "confidential") {
+    if (!req.clientId || !req.clientSecret) {
+      return err(
+        authError.invalidClient(
+          "confidential client must authenticate to revoke its tokens",
+        ),
+      )
+    }
+  }
+
+  // If a client_id was presented but it doesn't own the token, RFC 7009
+  // §2.2 still wants a successful no-op response — surfacing
+  // `invalid_grant` here would let a different client probe for token
+  // existence. Audit the attempt so operators can spot abuse.
+  if (req.clientId !== undefined && req.clientId !== payload.clientId) {
+    await safeAudit(deps, {
+      kind: "custom",
+      type: "revoke_wrong_client_attempt",
+      tenantId: payload.tenantId,
+      data: {
+        presentedClientId: req.clientId,
+        tokenClientId: payload.clientId,
+        subjectId: payload.subjectId,
+      },
+      timestamp: deps.clock(),
+    })
+    return ok(undefined)
+  }
+
+  // Credentials presented by the owning client must validate. Anonymous
+  // revoke of a public-client token is permitted.
+  if (req.clientId !== undefined) {
+    const authErr = await verifyClientCredentials(client, req.clientSecret)
+    if (authErr) return err(authErr)
+  }
+
+  const consumed = await deps.tokenStore.consumeRefresh(req.token, {
+    reuseWindowMs: 0,
+  })
+  if (isErr(consumed)) {
+    return ok(undefined)
+  }
+  await safeAudit(deps, {
+    kind: "token_revoked",
+    tenantId: payload.tenantId,
+    clientId: payload.clientId,
+    subjectId: payload.subjectId,
+    family: payload.family,
+    reason: "client_revoke",
+    timestamp: deps.clock(),
+  })
+  return ok(undefined)
+}
+
+/**
+ * Revoke every refresh token for a `(tenantId, subjectId)` pair and emit
+ * a `token_revoked` audit event with `reason: "subject_revoke"`.
+ *
+ * Public primitive exposed for host-driven "log me out of all devices"
+ * flows. Not called from the reuse-detection path — that stays at
+ * family-scope per OAuth 2.0 Security BCP §4.13.2 (revoking sibling
+ * families would punish legitimate other-device sessions sharing the
+ * same subject). See ARCHITECTURE.md §"Reuse detection scope".
+ */
+export async function revokeAllForSubject(
+  tenantId: TenantId,
+  subjectId: string,
+  deps: { tokenStore: TokenStore; auditLog?: AuditLog; clock: () => number },
+): Promise<Result<void, AuthError>> {
+  const res = await deps.tokenStore.revokeBySubject(tenantId, subjectId)
+  if (isErr(res)) return err(res.error)
+  await safeAudit(deps, {
+    kind: "token_revoked",
+    tenantId,
+    clientId: null,
+    subjectId,
+    reason: "subject_revoke",
+    timestamp: deps.clock(),
+  })
+  return ok(undefined)
+}

package/src/domain/state-envelope.ts

@@ -0,0 +1,142 @@
+/**
+ * MAC-signed `state` envelope used by the tenant-recovery chain.
+ *
+ * Format (intentionally compact, well under 256 base64url bytes):
+ *
+ *   `<b64u(payloadJson)>.<b64u(hmacSha256(payloadJson, key[kid]))>`
+ *
+ * where `payloadJson` is canonical JSON over `{tenantId, flowId, nonce, kid}`.
+ *
+ * **Nothing sensitive is in the envelope** — only the minimal recovery
+ * tuple. Sensitive data (`clientPkce`, `appRedirectUri`, scopes, etc.)
+ * lives in the server-side `FlowRecord`, identified by `flowId`.
+ *
+ * See `ARCHITECTURE.md` §"Tenant recovery across redirects" and plan
+ * §"Crypto — HMAC-SHA-256".
+ */
+import { authError, type AuthError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, ok } from "../types/result"
+import type {
+  StateEnvelope,
+  StateKey,
+  StateKeyRing,
+  TenantId,
+} from "../types/tenant"
+import { asTenantId } from "../types/tenant"
+
+import { base64url, hmacSign, hmacVerify, importHmacKey, utf8 } from "./crypto"
+
+/**
+ * Serialize envelope fields in a fixed order so the MAC input is
+ * deterministic regardless of object-key insertion order.
+ */
+function canonicalize(env: StateEnvelope): string {
+  return JSON.stringify({
+    tenantId: env.tenantId,
+    flowId: env.flowId,
+    nonce: env.nonce,
+    kid: env.kid,
+  })
+}
+
+/** Mint a signed state string for the given envelope under the active key. */
+export async function mintStateEnvelope(
+  envelope: Omit<StateEnvelope, "kid">,
+  keyRing: StateKeyRing,
+): Promise<string> {
+  const active = keyRing.active
+  const stamped: StateEnvelope = { ...envelope, kid: active.kid }
+  const payloadBytes = utf8.encode(canonicalize(stamped))
+  const key = await importHmacKey(active.key, ["sign"])
+  const sig = await hmacSign(key, payloadBytes)
+  return `${base64url.encode(payloadBytes)}.${base64url.encode(sig)}`
+}
+
+/**
+ * Verify and parse a state string. Returns `unknown_state` on malformed
+ * input, unknown `kid`, or signature mismatch.
+ *
+ * The MAC verification step uses `crypto.subtle.verify`, which is
+ * timing-safe by spec.
+ */
+export async function verifyStateEnvelope(
+  state: string,
+  keyRing: StateKeyRing,
+): Promise<Result<StateEnvelope, AuthError>> {
+  if (typeof state !== "string" || !state.includes(".")) {
+    return err(authError.unknownState("malformed state"))
+  }
+  const dotIdx = state.indexOf(".")
+  const headerB64u = state.slice(0, dotIdx)
+  const sigB64u = state.slice(dotIdx + 1)
+  if (!headerB64u || !sigB64u || sigB64u.includes(".")) {
+    return err(authError.unknownState("malformed state"))
+  }
+
+  let payloadBytes: Uint8Array
+  let sigBytes: Uint8Array
+  try {
+    payloadBytes = base64url.decode(headerB64u)
+    sigBytes = base64url.decode(sigB64u)
+  } catch {
+    return err(authError.unknownState("malformed state encoding"))
+  }
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(utf8.decode(payloadBytes))
+  } catch {
+    return err(authError.unknownState("malformed state payload"))
+  }
+  if (!isEnvelopeShape(parsed)) {
+    return err(authError.unknownState("state payload missing fields"))
+  }
+
+  const candidate = findKey(keyRing, parsed.kid)
+  if (!candidate) {
+    return err(authError.unknownState(`unknown state kid "${parsed.kid}"`))
+  }
+
+  const key = await importHmacKey(candidate.key, ["verify"])
+  const okSig = await hmacVerify(key, sigBytes, payloadBytes)
+  if (!okSig) {
+    return err(authError.unknownState("state signature mismatch"))
+  }
+
+  // Cross-check that the payload's `kid` matches the verifying key — guards
+  // against a malicious sender re-encoding the header to claim a different
+  // key was used while the MAC was actually computed under another.
+  if (parsed.kid !== candidate.kid) {
+    return err(authError.unknownState("state kid drift"))
+  }
+
+  return ok({
+    tenantId: asTenantId(parsed.tenantId),
+    flowId: parsed.flowId,
+    nonce: parsed.nonce,
+    kid: parsed.kid,
+  })
+}
+
+function findKey(ring: StateKeyRing, kid: string): StateKey | undefined {
+  return ring.verify.find((k) => k.kid === kid)
+}
+
+type EnvelopeShape = {
+  tenantId: TenantId & string
+  flowId: string
+  nonce: string
+  kid: string
+}
+
+function isEnvelopeShape(value: unknown): value is EnvelopeShape {
+  if (!value || typeof value !== "object") return false
+  const v = value as Record<string, unknown>
+  return (
+    typeof v.tenantId === "string" &&
+    typeof v.flowId === "string" &&
+    typeof v.nonce === "string" &&
+    typeof v.kid === "string"
+  )
+}

package/src/domain/token-exchange.ts

@@ -0,0 +1,232 @@
+/**
+ * `/token` logic for `grant_type=urn:ietf:params:oauth:grant-type:token-exchange`
+ * (RFC 8693).
+ *
+ * Scope: **audience-switch / impersonation only.** A subject who holds an
+ * access token for tenant A can present it here to receive a fresh
+ * access + refresh pair scoped to tenant B (the `audience` parameter).
+ * Delegation (`actor_token`) is rejected at the HTTP layer.
+ *
+ * Flow:
+ *   1. Verify the `subject_token` JWT against the IdP's own signing keys.
+ *      Expired / wrong-issuer / bad-sig tokens fail with `invalid_grant`
+ *      (per RFC 8693 §2.4).
+ *   2. Refuse if the host hasn't configured `exchangeAudience` — return
+ *      `unsupported_grant_type` for graceful degradation.
+ *   3. Narrow scope if the caller requested a subset.
+ *   4. Call `exchangeAudience(currentClaim, request)`. The host returns
+ *      either the SubjectClaim that should anchor the new tokens at the
+ *      target tenant, or an `AuthError` (typically `invalid_target`).
+ *   5. Load the target tenant config via `ConfigStore.getTenantConfig`.
+ *      This validates that the audience is a real partition.
+ *   6. Mint a fresh access + refresh pair with `tid = audience` and a
+ *      brand-new refresh family. The previous family lives untouched.
+ *   7. Audit `token_exchanged`.
+ *
+ * Notes:
+ *   - The new tokens' `clientId` is the **authenticated** client (the
+ *     one doing the exchange), not the original audience of the
+ *     subject_token. Hosts that need a different client must register
+ *     one in the target tenant.
+ *   - `methodId` / `methodKind` are preserved from the subject_token so
+ *     the audit trail still names the original authentication method.
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { ConfigStore } from "../ports/config-store"
+import type { KeyStore } from "../ports/key-store"
+import type { TokenStore } from "../ports/token-store"
+import { authError, type AuthError } from "../types/error"
+import type { ExchangeAudience } from "../types/idp"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { SubjectClaim } from "../types/subject"
+import type { ClientConfig, TenantContext, TenantId } from "../types/tenant"
+import type { AccessTokenClaims, TokenResponse } from "../types/token"
+
+import { safeAudit } from "./audit"
+import { verifyClientCredentials } from "./client-auth"
+import { randomId } from "./crypto"
+import { verifyAccessToken } from "./jwt"
+import { mintTokens } from "./token"
+
+export type TokenExchangeRequest = {
+  grantType: "urn:ietf:params:oauth:grant-type:token-exchange"
+  subjectToken: string
+  audience: string
+  /** Confidential clients authenticate. Public clients use the subject_token alone. */
+  clientId?: string
+  clientSecret?: string
+  /** Optional subset of subject_token scopes. */
+  scope?: string
+}
+
+export type TokenExchangeResponse = TokenResponse & {
+  /** RFC 8693 §2.2.1. Always `access_token` for this grant. */
+  issued_token_type: "urn:ietf:params:oauth:token-type:access_token"
+}
+
+export type ExchangeTokenDeps = {
+  configStore: ConfigStore
+  tokenStore: TokenStore
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  exchangeAudience?: ExchangeAudience
+  issuerUrl: string
+  clock: () => number
+  newRefreshFamily?: () => string
+}
+
+export async function exchangeToken(
+  req: TokenExchangeRequest,
+  deps: ExchangeTokenDeps,
+): Promise<Result<TokenExchangeResponse, AuthError>> {
+  // 1. Graceful degradation: refuse cleanly if not configured.
+  if (!deps.exchangeAudience) {
+    return err(
+      authError.unsupportedGrantType(
+        "token-exchange is not configured on this IdP",
+      ),
+    )
+  }
+
+  // 2. Verify the subject_token.
+  const keysRes = await deps.keyStore.signingKeys()
+  if (isErr(keysRes)) return err(keysRes.error)
+  let subjectClaims: AccessTokenClaims
+  try {
+    subjectClaims = await verifyAccessToken(req.subjectToken, keysRes.value, {
+      issuer: deps.issuerUrl,
+    })
+  } catch (e) {
+    return err(
+      authError.invalidGrant(
+        `subject_token verification failed: ${
+          e instanceof Error ? e.message : "unknown"
+        }`,
+      ),
+    )
+  }
+  if (!subjectClaims.claim) {
+    return err(
+      authError.invalidGrant(
+        "subject_token does not carry a SubjectClaim — was it issued by this IdP?",
+      ),
+    )
+  }
+
+  // 3. Load the issuing tenant + client so we can authenticate the caller.
+  const fromTenantId = subjectClaims.tid
+  const fromTenantCfg = await deps.configStore.getTenantConfig(fromTenantId)
+  if (isErr(fromTenantCfg)) return err(fromTenantCfg.error)
+  // The client doing the exchange — defaults to the subject_token's `aud`
+  // when not presented (public-client case).
+  const callerClientId = req.clientId ?? subjectClaims.aud
+  const callerClient = fromTenantCfg.value.clients.find(
+    (c: ClientConfig) => c.id === callerClientId,
+  )
+  if (!callerClient) {
+    return err(authError.invalidClient(`unknown client "${callerClientId}"`))
+  }
+  // Same client-auth rules as auth_code / refresh: confidential clients
+  // MUST authenticate; public clients MUST NOT present a secret.
+  const authErr = await verifyClientCredentials(callerClient, req.clientSecret)
+  if (authErr) return err(authErr)
+
+  // 4. Scope subset check (RFC 8693 §2.1 — `scope` MAY be requested).
+  const subjectScopes = (subjectClaims.scope ?? "")
+    .split(" ")
+    .filter((s) => s.length > 0)
+  const requestedScopes = req.scope
+    ? req.scope.split(" ").filter((s) => s.length > 0)
+    : subjectScopes
+  for (const s of requestedScopes) {
+    if (!subjectScopes.includes(s)) {
+      return err(
+        authError.invalidScope(
+          `requested scope "${s}" not granted by subject_token`,
+        ),
+      )
+    }
+  }
+
+  // 5. Host decision — does the subject get to access `audience`?
+  const audienceClaim = await deps.exchangeAudience(subjectClaims.claim, {
+    audience: req.audience,
+    ...(req.scope !== undefined ? { requestedScopes } : {}),
+    clientId: callerClient.id,
+    fromTenantId,
+  })
+  // The hook may return either a SubjectClaim (success) or an
+  // AuthError (rejection). Distinguish by checking for the `code`
+  // discriminator — AuthError is a closed taxonomy, all variants have
+  // `code: string`.
+  if (
+    typeof (audienceClaim as { code?: unknown }).code === "string" &&
+    typeof (audienceClaim as { description?: unknown }).description === "string"
+  ) {
+    return err(audienceClaim as AuthError)
+  }
+  const newClaim = audienceClaim as SubjectClaim
+
+  // 6. Load the target tenant config so mintTokens has a TenantContext.
+  const targetTenantId = req.audience as TenantId
+  const targetTenantCfg = await deps.configStore.getTenantConfig(targetTenantId)
+  if (isErr(targetTenantCfg)) return err(targetTenantCfg.error)
+  // Verify the calling client exists at the target tenant — otherwise
+  // the issued token's `aud` would name a client the target tenant
+  // doesn't know about.
+  const targetClient = targetTenantCfg.value.clients.find(
+    (c: ClientConfig) => c.id === callerClient.id,
+  )
+  if (!targetClient) {
+    return err(
+      authError.invalidTarget(
+        `client "${callerClient.id}" is not registered in target tenant "${targetTenantId}"`,
+      ),
+    )
+  }
+
+  // 7. Mint. Fresh family — previous family is untouched.
+  const targetTenant: TenantContext = {
+    id: targetTenantId,
+    config: targetTenantCfg.value,
+    request: { raw: new Request("about:blank"), custom: {} },
+  }
+  const minted = await mintTokens({
+    tenant: targetTenant,
+    claim: newClaim,
+    payload: {
+      tenantId: targetTenantId,
+      clientId: callerClient.id,
+      // Preserve provenance — operators can trace exchanged tokens back
+      // to the originating method through the audit chain.
+      methodId: subjectClaims.mid ?? "token_exchange",
+      methodKind: subjectClaims.mkind ?? "token_exchange",
+      scopes: requestedScopes,
+      ...(subjectClaims.aud !== undefined &&
+      subjectClaims.aud !== callerClient.id
+        ? { audience: subjectClaims.aud }
+        : {}),
+    },
+    family: (deps.newRefreshFamily ?? randomId)(),
+    deps,
+  })
+  if (isErr(minted)) return err(minted.error)
+
+  // 8. Audit. mintTokens already emits `token_issued`; the additional
+  // `token_exchanged` event records the cross-tenant context.
+  await safeAudit(deps, {
+    kind: "token_exchanged",
+    tenantId: targetTenantId,
+    fromTenantId,
+    clientId: callerClient.id,
+    subjectId: subjectClaims.sub,
+    family: "exchanged",
+    timestamp: deps.clock(),
+  })
+
+  return ok({
+    ...minted.value,
+    issued_token_type: "urn:ietf:params:oauth:token-type:access_token",
+  })
+}