@_mustachio/openauth 0.10.0 → 0.12.0

package/src/domain/logout.ts

@@ -0,0 +1,180 @@
+/**
+ * `/end_session` endpoint logic — OIDC RP-Initiated Logout 1.0.
+ *
+ * The OP validates the optional `id_token_hint`, validates the optional
+ * `post_logout_redirect_uri` against the client's registered list,
+ * revokes the subject's refresh tokens (when a subject is identified),
+ * and either redirects the user-agent back to the RP with `state` echoed
+ * or returns a generic "logged out" acknowledgement.
+ *
+ * Per §2:
+ *  - `id_token_hint` (RECOMMENDED): a previously-issued id_token. The
+ *    OP MUST verify the signature; expiry MAY be tolerated because
+ *    logout commonly follows token expiry. We accept expired hints but
+ *    enforce signature + issuer.
+ *  - `client_id` (OPTIONAL): when both this and `id_token_hint` are
+ *    present, the OP MUST verify the client_id matches the hint's `aud`.
+ *  - `post_logout_redirect_uri` (OPTIONAL): MUST be exact-match against
+ *    the resolved client's `postLogoutRedirectUris`. If the URI is not
+ *    registered, the OP MUST NOT redirect — surface a non-redirecting
+ *    error instead, otherwise the endpoint becomes an open redirector.
+ *  - `state` (OPTIONAL): echoed back in the redirect.
+ *
+ * Front-channel / back-channel logout (RP notification of OP-initiated
+ * logout) is out of scope for this minimal endpoint. Hosts that need it
+ * can layer their own notification fan-out on top of `session_logout`
+ * audit events.
+ */
+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, ok } from "../types/result"
+import type { ClientConfig, TenantContext } from "../types/tenant"
+
+import { safeAudit } from "./audit"
+import { verifyIdToken } from "./jwt"
+import { revokeAllForSubject } from "./revoke"
+
+export type EndSessionRequest = {
+  idTokenHint?: string
+  clientId?: string
+  postLogoutRedirectUri?: string
+  state?: string
+}
+
+export type EndSessionDeps = {
+  configStore: ConfigStore
+  tokenStore: TokenStore
+  keyStore: KeyStore
+  auditLog?: AuditLog
+  issuerUrl: string
+  clock: () => number
+}
+
+export type EndSessionOutput =
+  /** Redirect the user-agent back to the RP. */
+  | { kind: "redirect"; url: string }
+  /**
+   * No `post_logout_redirect_uri` was supplied (or it wasn't registered).
+   * Caller should render a minimal "logged out" page or return 200.
+   */
+  | { kind: "ok"; subjectId?: string }
+
+/**
+ * Process an `/end_session` request and return an outcome the HTTP
+ * adapter can translate into a `Response`. Pure domain — no Hono types,
+ * no `Response` construction here.
+ */
+export async function endSession(
+  req: EndSessionRequest,
+  tenant: TenantContext,
+  deps: EndSessionDeps,
+): Promise<Result<EndSessionOutput, AuthError>> {
+  // 1. Verify the id_token_hint (if present). Tolerate expiry per §2.
+  let hintSubject: string | undefined
+  let hintAud: string | undefined
+  if (req.idTokenHint) {
+    const keysRes = await deps.keyStore.signingKeys()
+    if (isErr(keysRes)) return err(keysRes.error)
+    try {
+      const claims = await verifyIdToken(req.idTokenHint, keysRes.value, {
+        issuer: deps.issuerUrl,
+        acceptExpired: true,
+      })
+      hintSubject = claims.sub
+      hintAud = claims.aud
+    } catch (e) {
+      const reason = e instanceof Error ? e.message : String(e)
+      return err(
+        authError.invalidRequest(
+          `id_token_hint failed signature/issuer verification: ${reason}`,
+          "id_token_hint",
+        ),
+      )
+    }
+  }
+
+  // 2. If both client_id and id_token_hint are present, they MUST agree
+  //    (§2). Disagreement is `invalid_request` — never a redirect.
+  if (req.clientId && hintAud && req.clientId !== hintAud) {
+    return err(
+      authError.invalidRequest(
+        "client_id does not match id_token_hint.aud",
+        "client_id",
+      ),
+    )
+  }
+
+  // 3. Resolve the client for redirect-URI validation. Prefer explicit
+  //    client_id, fall back to the hint's aud.
+  const resolvedClientId = req.clientId ?? hintAud
+  let client: ClientConfig | undefined
+  if (resolvedClientId) {
+    client = tenant.config.clients.find((c) => c.id === resolvedClientId)
+    if (!client) {
+      return err(
+        authError.invalidRequest(
+          `unknown client "${resolvedClientId}"`,
+          "client_id",
+        ),
+      )
+    }
+  }
+
+  // 4. Validate post_logout_redirect_uri. MUST be exact-match against
+  //    the client's registered list (§2). No client → no validatable URI.
+  if (req.postLogoutRedirectUri) {
+    if (!client) {
+      return err(
+        authError.invalidRequest(
+          "post_logout_redirect_uri requires identifying the client via client_id or id_token_hint",
+          "post_logout_redirect_uri",
+        ),
+      )
+    }
+    const registered = client.postLogoutRedirectUris ?? []
+    if (!registered.includes(req.postLogoutRedirectUri)) {
+      return err(
+        authError.invalidRequest(
+          "post_logout_redirect_uri is not registered for this client",
+          "post_logout_redirect_uri",
+        ),
+      )
+    }
+  }
+
+  // 5. Revoke the subject's tokens. Only possible when an id_token_hint
+  //    identified a subject. Without a hint, /end_session is essentially
+  //    a session-cookie clear (which the framework doesn't yet own); we
+  //    still return a successful redirect/ok so RPs can complete UX.
+  if (hintSubject) {
+    const revoked = await revokeAllForSubject(tenant.id, hintSubject, {
+      tokenStore: deps.tokenStore,
+      ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+      clock: deps.clock,
+    })
+    if (isErr(revoked)) return err(revoked.error)
+  }
+
+  await safeAudit(deps, {
+    kind: "session_logout",
+    tenantId: tenant.id,
+    ...(resolvedClientId ? { clientId: resolvedClientId } : {}),
+    ...(hintSubject ? { subjectId: hintSubject } : {}),
+    timestamp: deps.clock(),
+  })
+
+  // 6. Build the redirect or signal "ok" for the caller to render.
+  if (req.postLogoutRedirectUri) {
+    const url = new URL(req.postLogoutRedirectUri)
+    if (req.state !== undefined) url.searchParams.set("state", req.state)
+    return ok({ kind: "redirect", url: url.toString() })
+  }
+  return ok({
+    kind: "ok",
+    ...(hintSubject ? { subjectId: hintSubject } : {}),
+  })
+}

package/src/domain/method-dispatch.ts

@@ -16,10 +16,11 @@ import type {
   MethodContext,
   MethodDispatchData,
   MethodResult,
+  MethodScratch,
 } from "../types/method"
 import type { Result } from "../types/result"
 import { err, isErr, ok } from "../types/result"
-import type { TenantContext } from "../types/tenant"
+import type { TenantContext, TenantId } from "../types/tenant"
 
 export type RouteKey = `${"GET" | "POST"} ${string}`
 
@@ -62,6 +63,11 @@ export async function dispatchMethod(
     methodState: input.flow?.methodState ?? null,
     cookies: input.cookies,
     dispatch: input.dispatch,
+    methodScratch: buildMethodScratch(
+      input.sessionStore,
+      input.tenant.id,
+      input.method.id,
+    ),
   }
 
   let result: MethodResult<unknown, unknown>
@@ -93,3 +99,49 @@ export async function dispatchMethod(
 
   return ok(result)
 }
+
+/**
+ * Construct the scoped `MethodScratch` handed to a method handler. Keys
+ * are namespaced `scratch:<tenantId>:<methodId>:<userKey>` so a method
+ * instance can never read or clobber another instance's data — even
+ * across tenants on a shared store.
+ *
+ * When the underlying `SessionStore` doesn't implement
+ * `saveScratch` / `readScratch` / `deleteScratch`, every operation
+ * returns `unsupportedAdapter` so methods can surface a clean error
+ * rather than silently no-op.
+ */
+function buildMethodScratch(
+  store: SessionStore,
+  tenantId: TenantId,
+  methodId: string,
+): MethodScratch {
+  const prefix = `scratch:${tenantId}:${methodId}:`
+  const scope = (key: string): string => `${prefix}${key}`
+  const unsupported = (op: string): AuthError =>
+    authError.internalError(
+      `SessionStore does not implement ${op}; methodScratch is unavailable on this adapter`,
+    )
+
+  return {
+    put: async (key, value, ttlMs) => {
+      if (!store.saveScratch) return err(unsupported("saveScratch"))
+      if (ttlMs <= 0) {
+        return err(
+          authError.internalError(
+            `methodScratch.put: ttlMs must be positive, got ${ttlMs}`,
+          ),
+        )
+      }
+      return store.saveScratch(scope(key), value, ttlMs)
+    },
+    get: async (key) => {
+      if (!store.readScratch) return err(unsupported("readScratch"))
+      return store.readScratch(scope(key))
+    },
+    delete: async (key) => {
+      if (!store.deleteScratch) return err(unsupported("deleteScratch"))
+      return store.deleteScratch(scope(key))
+    },
+  }
+}

package/src/domain/method-route.ts

@@ -32,7 +32,14 @@ import type { SessionStore } from "../ports/session-store"
 import type { TokenStore } from "../ports/token-store"
 import { authError, type AuthError } from "../types/error"
 import type { FlowRecord } from "../types/flow"
-import type { MethodResult, CachePolicy, SetCookie } from "../types/method"
+import type { LogoutEventInput, LogoutHookResult } from "../types/idp"
+import type {
+  AuthMethod,
+  CachePolicy,
+  MethodDispatchData,
+  MethodResult,
+  SetCookie,
+} from "../types/method"
 import type { Result } from "../types/result"
 import { err, isErr, ok } from "../types/result"
 import type { TenantContext } from "../types/tenant"
@@ -42,6 +49,7 @@ import { AUTH_CODE_TTL_MS } from "./authorize"
 import { randomToken } from "./crypto"
 import { MethodCache } from "./method-cache"
 import { dispatchMethod, type RouteKey } from "./method-dispatch"
+import { revokeAllForSubject } from "./revoke"
 import { saveEncryptedCode } from "./token"
 
 export type MethodRouteOutput =
@@ -166,6 +174,11 @@ async function translate(
           context: final.context ?? null,
           providerSubject: result.providerSubject,
           properties: result.properties,
+          ...(final.appNonce !== undefined ? { appNonce: final.appNonce } : {}),
+          ...(final.claimsRequest !== undefined
+            ? { claimsRequest: final.claimsRequest }
+            : {}),
+          authTime: Math.floor(now / 1000),
           expiresAt: now + AUTH_CODE_TTL_MS,
         },
         AUTH_CODE_TTL_MS,
@@ -206,3 +219,184 @@ async function translate(
       return err(result.error)
   }
 }
+
+/**
+ * Anonymous public method route — the fourth, deliberately narrow,
+ * pipeline. Used only for route keys a method explicitly lists in
+ * `AuthMethod.publicRoutes` (today: SAML SP `GET /metadata`). No flow
+ * cookie, no flow record, no `SessionStore` read: the handler is a pure
+ * function of `tenant` + `dispatch` + captured config.
+ *
+ * Security: this re-checks `publicRoutes` membership against the
+ * resolved method. The HTTP layer also checks before routing here, but
+ * a domain function guarding a no-auth path must not trust its caller —
+ * the gate is enforced here too, fail-closed.
+ *
+ * Only `challenge` (the metadata document) and `denied` are sensible
+ * outcomes; `success` from a flowless route is a programming error
+ * (there is no flow to consume into an auth code) and surfaces as an
+ * internal error rather than silently authenticating.
+ */
+export type HandlePublicMethodRouteInput = {
+  rawRequest: Request
+  tenant: TenantContext
+  /** Pre-resolved by the HTTP layer (it needed it to detect the public route). */
+  method: AuthMethod
+  route: RouteKey
+  subPath: string
+  /** Issuer/callback context so the handler can derive stable URLs. */
+  dispatch: MethodDispatchData
+}
+
+export type HandlePublicMethodRouteDeps = {
+  sessionStore: SessionStore
+  /**
+   * Required for the upstream-logout path: when a public route returns a
+   * `challenge` carrying `logout`, the framework runs
+   * `revokeAllForSubject` for the host-named subject. Anonymous read-only
+   * public routes (`/metadata`-style) never touch this.
+   */
+  tokenStore: TokenStore
+  clock: () => number
+  auditLog?: AuditLog
+  /**
+   * See `IdPOptions.onLogout`. Absent ⇒ the framework still verifies +
+   * acknowledges the logout and audits it, but revokes nothing (it
+   * cannot resolve the upstream id to a subject without the host).
+   */
+  onLogout?: (
+    input: LogoutEventInput,
+  ) => Promise<LogoutHookResult> | LogoutHookResult
+}
+
+export type PublicMethodRouteOutput =
+  | { kind: "challenge"; response: Response; cache?: CachePolicy }
+  | { kind: "denied"; reason: string }
+
+export async function handlePublicMethodRoute(
+  input: HandlePublicMethodRouteInput,
+  deps: HandlePublicMethodRouteDeps,
+): Promise<Result<PublicMethodRouteOutput, AuthError>> {
+  if (!input.method.publicRoutes?.includes(input.route)) {
+    return err(
+      authError.invalidRequest(
+        `route "${input.route}" is not public on method "${input.method.id}"`,
+        "path",
+      ),
+    )
+  }
+
+  const dispatched = await dispatchMethod({
+    method: input.method,
+    route: input.route,
+    tenant: input.tenant,
+    request: input.rawRequest,
+    subPath: input.subPath,
+    flow: null,
+    cookies: new Map(),
+    sessionStore: deps.sessionStore,
+    dispatch: input.dispatch,
+  })
+  if (isErr(dispatched)) return err(dispatched.error)
+
+  const r = dispatched.value
+  switch (r.kind) {
+    case "challenge": {
+      // A verified upstream logout (SAML front-channel SLS): the method
+      // proved authenticity and built the `LogoutResponse`; the
+      // privileged side effect (host teardown + token revocation) runs
+      // here, where the ports live. Fail closed — if the side effect
+      // errors we do NOT hand back a `LogoutResponse` that would tell
+      // the IdP the user is logged out when they may not be.
+      if (r.logout) {
+        const sideEffect = await runUpstreamLogout(input, deps, r.logout)
+        if (isErr(sideEffect)) return err(sideEffect.error)
+      }
+      return ok({
+        kind: "challenge",
+        response: r.response,
+        ...(r.cache !== undefined ? { cache: r.cache } : {}),
+      })
+    }
+    case "denied":
+      return ok({ kind: "denied", reason: r.reason })
+    case "success":
+      return err(
+        authError.internalError(
+          `public route "${input.route}" on method "${input.method.id}" ` +
+            `returned success — a flowless route cannot authenticate`,
+        ),
+      )
+    case "error":
+      return err(r.error)
+  }
+}
+
+/**
+ * Run the privileged side effect for a verified upstream logout: fire
+ * the host's `onLogout` hook, then — if the host named a subject —
+ * revoke that subject's library-issued tokens via the same
+ * `revokeAllForSubject` primitive `/end_session` uses. Always emits a
+ * `session_logout` audit event (`via: "upstream_slo"`).
+ *
+ * The library cannot map the upstream `nameId` to an OIDC subject
+ * itself (that mapping lives in the host's `success` callback), so
+ * revocation is host-directed by design. A throwing hook or a failed
+ * revoke fails closed (`internal_error`) — the caller then withholds
+ * the `LogoutResponse`.
+ */
+async function runUpstreamLogout(
+  input: HandlePublicMethodRouteInput,
+  deps: HandlePublicMethodRouteDeps,
+  logout: { nameId?: string; sessionIndex?: string },
+): Promise<Result<void, AuthError>> {
+  let hookResult: LogoutHookResult = undefined
+  if (deps.onLogout) {
+    const evt: LogoutEventInput = {
+      tenant: input.tenant,
+      methodId: input.method.id,
+      methodKind: input.method.kind,
+      reason: "upstream_slo",
+      ...(logout.nameId !== undefined ? { nameId: logout.nameId } : {}),
+      ...(logout.sessionIndex !== undefined
+        ? { sessionIndex: logout.sessionIndex }
+        : {}),
+    }
+    try {
+      hookResult = await deps.onLogout(evt)
+    } catch (e) {
+      return err(
+        authError.internalError(
+          `onLogout hook threw during upstream Single Logout for method ` +
+            `"${input.method.id}"`,
+          e,
+        ),
+      )
+    }
+  }
+
+  const revokeSubject =
+    hookResult && typeof hookResult === "object"
+      ? hookResult.revokeSubject
+      : undefined
+
+  if (revokeSubject) {
+    const revoked = await revokeAllForSubject(input.tenant.id, revokeSubject, {
+      tokenStore: deps.tokenStore,
+      ...(deps.auditLog ? { auditLog: deps.auditLog } : {}),
+      clock: deps.clock,
+    })
+    if (isErr(revoked)) return err(revoked.error)
+  }
+
+  await safeAudit(deps, {
+    kind: "session_logout",
+    tenantId: input.tenant.id,
+    via: "upstream_slo",
+    methodId: input.method.id,
+    methodKind: input.method.kind,
+    ...(revokeSubject ? { subjectId: revokeSubject } : {}),
+    timestamp: deps.clock(),
+  })
+  return ok(undefined)
+}

package/src/domain/par.ts

@@ -0,0 +1,141 @@
+/**
+ * Pushed Authorization Requests (RFC 9126).
+ *
+ * The RP submits the full `/authorize` parameter set to `POST /par` along
+ * with its client credentials. The OP authenticates the client, stores
+ * the payload under an opaque `request_uri`, and returns it with an
+ * `expires_in`. The RP then redirects the user-agent to
+ * `GET /authorize?client_id=...&request_uri=...` and the OP rehydrates
+ * the original parameter set.
+ *
+ * Per RFC 9126 §3:
+ *  - Response is HTTP 201 with `application/json` body
+ *    `{request_uri, expires_in}`.
+ *  - `request_uri` MUST be of the form
+ *    `urn:ietf:params:oauth:request_uri:<opaque>` (§2.2).
+ *  - Default TTL is 60 seconds — same as auth-code TTL.
+ *
+ * Per RFC 9126 §4:
+ *  - At `/authorize`, `request_uri` is one-shot — consumed and discarded
+ *    on first use.
+ *  - Parameters in the PAR record take precedence; additional `/authorize`
+ *    parameters MAY be merged but MUST NOT contradict (we strictly use
+ *    the PAR'd set and ignore any additional ones except `client_id`).
+ *
+ * Client authentication (§2):
+ *  - Public clients: `client_id` only.
+ *  - Confidential clients: `client_id` + `client_secret` (Basic or form).
+ */
+import type { AuditLog } from "../ports/audit-log"
+import type { ConfigStore } from "../ports/config-store"
+import type { SessionStore } from "../ports/session-store"
+import { authError, type AuthError } from "../types/error"
+import type { Result } from "../types/result"
+import { err, isErr, ok } from "../types/result"
+import type { TenantContext } from "../types/tenant"
+
+import { verifyClientCredentials } from "./client-auth"
+import { randomToken } from "./crypto"
+
+export const PAR_URI_PREFIX = "urn:ietf:params:oauth:request_uri:"
+export const DEFAULT_PAR_TTL_MS = 60 * 1000
+
+export type ParRequest = {
+  clientId: string
+  /** Confidential-client secret. */
+  clientSecret?: string
+  /** Raw `/authorize` parameter record, posted by the RP. */
+  params: Record<string, string>
+}
+
+export type ParResponse = {
+  request_uri: string
+  expires_in: number
+}
+
+export type ParDeps = {
+  configStore: ConfigStore
+  sessionStore: SessionStore
+  auditLog?: AuditLog
+  clock: () => number
+  /** Test override. */
+  newRequestUriSuffix?: () => string
+  ttlMs?: number
+}
+
+/**
+ * Process a `POST /par` request. Authenticates the client, validates the
+ * `client_id` consistency, and persists the parameter set.
+ */
+export async function pushAuthorizationRequest(
+  req: ParRequest,
+  tenant: TenantContext,
+  deps: ParDeps,
+): Promise<Result<ParResponse, AuthError>> {
+  if (!deps.sessionStore.savePar || !deps.sessionStore.consumePar) {
+    return err(
+      authError.invalidRequest(
+        "session adapter does not implement PAR storage",
+      ),
+    )
+  }
+
+  // 1. Client authentication. The `client_id` in the body must match the
+  //    authenticating client.
+  const client = tenant.config.clients.find((c) => c.id === req.clientId)
+  if (!client) {
+    return err(authError.invalidClient(`unknown client "${req.clientId}"`))
+  }
+  if (client.type === "confidential") {
+    const authErr = await verifyClientCredentials(client, req.clientSecret)
+    if (authErr) return err(authErr)
+  } else if (req.clientSecret !== undefined) {
+    return err(
+      authError.invalidClient("public client must not present client_secret"),
+    )
+  }
+
+  // 2. Sanity-check the body: client_id in body must match — the RFC
+  //    requires it (§2). RP shouldn't be authenticating one client and
+  //    pushing params for a different one.
+  if (req.params.client_id && req.params.client_id !== req.clientId) {
+    return err(
+      authError.invalidRequest(
+        "client_id in body conflicts with authenticated client",
+        "client_id",
+      ),
+    )
+  }
+  // RFC 9126 §2.1: `request_uri` MUST NOT appear in a PAR request body.
+  if ("request_uri" in req.params) {
+    return err(
+      authError.invalidRequest(
+        "request_uri MUST NOT be present in a PAR request",
+        "request_uri",
+      ),
+    )
+  }
+
+  // 3. Mint request_uri + persist.
+  const suffix = (deps.newRequestUriSuffix ?? randomToken)()
+  const requestUri = PAR_URI_PREFIX + suffix
+  const ttl = deps.ttlMs ?? DEFAULT_PAR_TTL_MS
+  const now = deps.clock()
+  const saved = await deps.sessionStore.savePar(
+    requestUri,
+    {
+      requestUri,
+      params: { ...req.params, client_id: req.clientId },
+      clientId: req.clientId,
+      issuedAt: now,
+      expiresAt: now + ttl,
+    },
+    ttl,
+  )
+  if (isErr(saved)) return err(saved.error)
+
+  return ok({
+    request_uri: requestUri,
+    expires_in: Math.floor(ttl / 1000),
+  })
+}

package/src/domain/refresh.ts

@@ -34,6 +34,13 @@ export type RefreshGrantRequest = {
   /** Confidential clients authenticate at /token. */
   clientId?: string
   clientSecret?: string
+  /**
+   * RFC 9449 §6 — JWK thumbprint of the DPoP proof presented on this
+   * refresh request. MUST match `RefreshTokenPayload.dpopJkt` when the
+   * original grant was DPoP-bound; presence is REQUIRED for bound
+   * tokens, OPTIONAL otherwise.
+   */
+  dpopJkt?: string
 }
 
 export type RefreshTokensDeps = {
@@ -46,6 +53,8 @@ export type RefreshTokensDeps = {
   /** Reuse-detection window (ms). Default 60 s. */
   reuseWindowMs?: number
   newRefreshToken?: () => string
+  /** See `IdPOptions.customScopeClaims`. Forwarded to `mintTokens`. */
+  customScopeClaims?: Record<string, ReadonlyArray<string>>
 }
 
 export async function refreshTokens(
@@ -93,6 +102,27 @@ export async function refreshTokens(
     return err(authError.invalidGrant(INVALID_REFRESH_DESC))
   }
 
+  // RFC 9449 §5 — when the refresh token is DPoP-bound, verify the
+  // presented DPoP thumbprint matches BEFORE consuming. Consuming first
+  // would burn the token on a wrong-key probe AND trip reuse-detection
+  // on a subsequent legitimate retry with the right key.
+  if (peekedPayload.dpopJkt !== undefined) {
+    if (req.dpopJkt === undefined) {
+      return err(
+        authError.invalidDpopProof(
+          "refresh token is DPoP-bound; request is missing a DPoP proof",
+        ),
+      )
+    }
+    if (req.dpopJkt !== peekedPayload.dpopJkt) {
+      return err(
+        authError.invalidDpopProof(
+          "refresh token DPoP jkt does not match the original binding",
+        ),
+      )
+    }
+  }
+
   const consumed = await deps.tokenStore.consumeRefresh(req.refreshToken, {
     reuseWindowMs: deps.reuseWindowMs,
   })
@@ -150,6 +180,17 @@ export async function refreshTokens(
       methodKind: payload.methodKind,
       scopes: requestedScopes,
       audience: payload.audience,
+      // `auth_time` is stable across refresh rotations per OIDC Core §12;
+      // refresh does not re-authenticate the user. `nonce` is deliberately
+      // NOT carried forward — the nonce was bound to the original
+      // `/authorize` request and should not reappear on rotated id_tokens.
+      authTime: payload.authTime,
+      // Preserve DPoP binding across refresh rotation (§6.1).
+      ...(payload.dpopJkt !== undefined ? { dpopJkt: payload.dpopJkt } : {}),
+      // Preserve OIDC §5.5 claims-parameter intent across refresh (§12).
+      ...(payload.claimsRequest !== undefined
+        ? { claimsRequest: payload.claimsRequest }
+        : {}),
     },
     family: payload.family,
     deps,