@_mustachio/openauth 0.10.0 → 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

@@ -50,9 +50,15 @@ export type IntrospectResponse =
       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 = {
@@ -129,6 +135,7 @@ export async function introspect(
     return ok({ active: false })
   }
 
+  const subjectType = (claims.claim as { type?: string } | undefined)?.type
   return ok({
     active: true,
     sub: claims.sub,
@@ -138,8 +145,11 @@ export async function introspect(
     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 } : {}),
   })
 }

package/src/domain/jwt.ts

@@ -9,7 +9,7 @@
 import type { JWK, KeyLike } from "jose"
 import { importJWK, jwtVerify, SignJWT } from "jose"
 
-import type { AccessTokenClaims } from "../types/token"
+import type { AccessTokenClaims, IdTokenClaims } from "../types/token"
 import type { SigningKey } from "../ports/key-store"
 
 /**
@@ -28,6 +28,85 @@ export async function signAccessToken(
     .sign(privateKey)
 }
 
+/**
+ * Sign an OIDC `id_token` claim set (OIDC Core §2). Header `typ` is
+ * `"JWT"` per common practice; OIDC Core does not mandate `"id_token"`.
+ * The claims object is verified by the caller to include `iss`, `sub`,
+ * `aud`, `exp`, `iat` (REQUIRED per §2).
+ */
+export async function signIdToken(
+  claims: IdTokenClaims,
+  privateKey: KeyLike,
+  alg: string,
+  kid: string,
+): Promise<string> {
+  return new SignJWT(claims as unknown as Record<string, unknown>)
+    .setProtectedHeader({ alg, typ: "JWT", kid })
+    .sign(privateKey)
+}
+
+/**
+ * Verify an OIDC `id_token` against the IdP's published signing keys.
+ * Used at `/end_session` to validate `id_token_hint` and by adjacent
+ * domain code that needs to introspect a previously-issued id_token.
+ *
+ * Same algorithm-confusion defenses as `verifyAccessToken`: only the
+ * asymmetric allow-list (`ES256`, `EdDSA`) accepted; `alg: "none"`
+ * rejected explicitly.
+ *
+ * `acceptExpired` relaxes the `exp` check — required at `/end_session`
+ * per OIDC RP-Initiated Logout 1.0 §2, where logout often follows token
+ * expiry and the spec permits accepting an expired hint. The signature
+ * + issuer + audience checks remain strict.
+ */
+export async function verifyIdToken(
+  token: string,
+  keys: ReadonlyArray<SigningKey>,
+  options: {
+    issuer?: string
+    audience?: string
+    acceptExpired?: boolean
+  } = {},
+): Promise<IdTokenClaims> {
+  const algorithms = Array.from(
+    new Set(keys.map((k) => k.alg).filter((a) => ASYMMETRIC_ALGS.has(a))),
+  )
+  const { payload } = await jwtVerify<IdTokenClaims>(
+    token,
+    async (header) => {
+      if (!header.alg || header.alg === "none") {
+        throw new Error(`verifyIdToken: refusing alg "${header.alg ?? ""}"`)
+      }
+      const match = keys.find((k) => k.kid === header.kid)
+      if (!match) {
+        throw new Error(`verifyIdToken: unknown kid "${header.kid}"`)
+      }
+      if (match.alg !== header.alg) {
+        throw new Error(
+          `verifyIdToken: header.alg "${header.alg}" does not match key alg "${match.alg}"`,
+        )
+      }
+      const imported = await importJWK(
+        match.publicJwk as unknown as JWK,
+        match.alg,
+      )
+      return imported as KeyLike
+    },
+    {
+      algorithms,
+      ...(options.issuer ? { issuer: options.issuer } : {}),
+      ...(options.audience ? { audience: options.audience } : {}),
+      // jose checks `exp` against `currentDate + clockTolerance`. A huge
+      // tolerance effectively disables the expiry check while preserving
+      // signature + issuer + audience validation.
+      ...(options.acceptExpired
+        ? { clockTolerance: Number.MAX_SAFE_INTEGER }
+        : {}),
+    },
+  )
+  return payload
+}
+
 /** Allow-list of asymmetric `alg` values the IdP issues + accepts. */
 const ASYMMETRIC_ALGS: ReadonlySet<string> = new Set(["ES256", "EdDSA"])