@blamejs/core 0.14.19 → 0.14.20

package/lib/auth/oauth.js

@@ -115,6 +115,7 @@ var safeJson = require("../safe-json");
 var safeUrl = require("../safe-url");
 var { URL } = require("node:url");
 var { defineClass } = require("../framework-error");
+var validateOpts = require("../validate-opts");
 var lazyRequire = require("../lazy-require");
 // Shared JOSE defenses (CVE-2026-22817 alg/kty cross-check +
 // CVE-2026-23552 constant-time iss compare). Top-of-file per project
@@ -348,6 +349,644 @@ function _jwkToKey(jwk) {
   }
 }
 
+// ---- RFC 9396 Rich Authorization Requests (RAR) ----
+//
+// The client requests fine-grained, typed authorization via the
+// `authorization_details` parameter (a JSON array of objects each
+// carrying a required `type`). The authorization server returns the
+// GRANTED `authorization_details` in the token response (RFC 9396 §7);
+// the client cross-checks granted against requested so an AS (hostile
+// or buggy) cannot silently broaden the grant — a granted detail whose
+// `type` was never requested, or whose array-valued sub-fields
+// (`locations` / `actions` / `datatypes` / `privileges`) exceed the
+// requested set, is refused. This is the client-side mirror of the
+// AS-side subset rule (RFC 9396 §6.3) and defends against an upstream
+// privilege-escalation.
+
+// Sub-fields whose values are bounded arrays of strings; a granted
+// value here MUST be a subset of the requested value for the same type
+// (RFC 9396 §2.1 — locations / actions / datatypes / privileges are the
+// registered array-valued common data fields; `privileges` is the most
+// authority-bearing of them, so an unchecked over-grant here is the
+// sharpest escalation).
+var RAR_SUBSET_FIELDS = Object.freeze(["locations", "actions", "datatypes", "privileges"]);
+
+// Cap on a serialized authorization_details payload. RFC 9396 puts no
+// fixed limit; 64 KiB matches the step-up RAR parser and refuses a
+// pathological array without touching legitimate transaction payloads.
+var RAR_MAX_BYTES = C.BYTES.kib(64);
+
+// Validate the request-side authorization_details array. Config-time
+// entry-point → THROW on bad shape (operator typo at boot). Mirrors
+// step-up.parseAuthorizationDetails but operates on an already-parsed
+// array (the operator passes opts.authorizationDetails as JS objects).
+function _validateAuthorizationDetailsArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new OAuthError("auth-oauth/bad-authorization-details",
+      label + ": authorizationDetails must be an array of typed objects (RFC 9396 §2)");
+  }
+  for (var i = 0; i < value.length; i += 1) {
+    var entry = value[i];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      throw new OAuthError("auth-oauth/bad-authorization-details",
+        label + ": authorizationDetails[" + i + "] must be an object");
+    }
+    if (typeof entry.type !== "string" || entry.type.length === 0) {
+      throw new OAuthError("auth-oauth/bad-authorization-details",
+        label + ": authorizationDetails[" + i + "] missing required 'type' field (RFC 9396 §2)");
+    }
+  }
+  return value;
+}
+
+// True when `grantedVal` (an array of strings) contains an element not
+// present in `requestedVal`. Anything the AS grants outside the request
+// is an over-grant. A non-array granted value where the request was an
+// array, or a granted array where no request entry constrained it, is
+// also treated as exceeding.
+function _arraySubfieldExceeds(grantedVal, requestedVal) {
+  if (grantedVal === undefined) return false;          // not granted → can't exceed
+  if (!Array.isArray(grantedVal)) {
+    // AS returned a non-array where RAR defines an array field. If the
+    // request didn't carry this field at all, an unconstrained scalar
+    // is an over-grant; if it matches the requested scalar exactly it
+    // is fine (lenient toward non-conforming-but-equal AS output).
+    return !(requestedVal !== undefined &&
+             !Array.isArray(requestedVal) &&
+             grantedVal === requestedVal);
+  }
+  if (!Array.isArray(requestedVal)) return grantedVal.length > 0;
+  for (var i = 0; i < grantedVal.length; i += 1) {
+    if (requestedVal.indexOf(grantedVal[i]) === -1) return true;
+  }
+  return false;
+}
+
+// Decide whether a single granted authorization_detail exceeds what was
+// requested. `requestedForType` is the matching request entry (same
+// type) or null when the type was never requested.
+function _grantedDetailExceeds(granted, requestedForType) {
+  if (!requestedForType) return true;                  // type never requested
+  for (var i = 0; i < RAR_SUBSET_FIELDS.length; i += 1) {
+    var f = RAR_SUBSET_FIELDS[i];
+    if (_arraySubfieldExceeds(granted[f], requestedForType[f])) return true;
+  }
+  return false;
+}
+
+// Cross-check the granted authorization_details from a token response
+// against what the client requested. Returns the normalized granted
+// array (or null when the AS returned none). `requested` is the
+// validated request array (or null/undefined when RAR was not used).
+//
+// strict=true (default when requested details were sent): refuse on any
+// over-grant. strict=false: surface but don't throw (operator audits).
+function _crossCheckGrantedAuthorizationDetails(grantedRaw, requested, strict) {
+  if (grantedRaw === undefined || grantedRaw === null) return null;
+  if (!Array.isArray(grantedRaw)) {
+    throw new OAuthError("auth-oauth/bad-granted-authorization-details",
+      "token response authorization_details must be a JSON array (RFC 9396 §7)");
+  }
+  // Bound the parse cost of an attacker-influenced upstream payload.
+  if (Buffer.byteLength(JSON.stringify(grantedRaw), "utf8") > RAR_MAX_BYTES) {
+    throw new OAuthError("auth-oauth/granted-authorization-details-too-large",
+      "token response authorization_details exceeds " + RAR_MAX_BYTES + " bytes");
+  }
+  if (requested === undefined || requested === null) return grantedRaw;
+  for (var i = 0; i < grantedRaw.length; i += 1) {
+    var granted = grantedRaw[i];
+    if (!granted || typeof granted !== "object" || Array.isArray(granted) ||
+        typeof granted.type !== "string") {
+      throw new OAuthError("auth-oauth/bad-granted-authorization-details",
+        "token response authorization_details[" + i + "] is not a typed object (RFC 9396 §2)");
+    }
+    // Find a requested entry of the SAME type. Exact string equality on
+    // the type field — never a substring scan.
+    var match = null;
+    for (var j = 0; j < requested.length; j += 1) {
+      if (requested[j].type === granted.type) { match = requested[j]; break; }
+    }
+    if (_grantedDetailExceeds(granted, match)) {
+      if (strict) {
+        throw new OAuthError("auth-oauth/authorization-details-over-grant",
+          "token response granted an authorization_detail (type='" + granted.type +
+          "') that exceeds the request — refusing per RFC 9396 §7 (broadened grant). " +
+          "Operators that intentionally accept asymmetric grants pass " +
+          "verifyAuthorizationDetails: false.");
+      }
+    }
+  }
+  return grantedRaw;
+}
+
+// ---- OAuth 2.0 Attestation-Based Client Authentication ----
+// (draft-ietf-oauth-attestation-based-client-auth-08)
+//
+// A FAPI / wallet client authenticates with two HTTP headers instead of
+// a client_secret:
+//   OAuth-Client-Attestation       — a JWT signed by the client's
+//                                     BACKEND ("Attester"), binding the
+//                                     client_id to a per-instance public
+//                                     key via a `cnf` claim (§4).
+//   OAuth-Client-Attestation-PoP    — a JWT signed by the per-instance
+//                                     PRIVATE key (the one named in the
+//                                     attestation's `cnf`), proving the
+//                                     instance possesses that key (§5).
+//
+// The framework signs these with node:crypto directly — this is the
+// classical-JWS interop case (the Attester / instance keys are RS/PS/ES/
+// EdDSA), distinct from lib/auth/jwt.js which signs framework tokens
+// PQC-only. HMAC ("none" included) is refused on both JWTs.
+
+// Asymmetric JWS algorithms accepted for attestation + PoP. HMAC and
+// "none" are intentionally absent (draft §5.2 requires an asymmetric
+// signature for the PoP; we apply the same floor to the attestation).
+var ATTESTATION_ALGS = Object.freeze([
+  "RS256", "RS384", "RS512",
+  "PS256", "PS384", "PS512",
+  "ES256", "ES384", "ES512",
+  "EdDSA",
+]);
+
+// Cap on an attestation / PoP JWT. HTTP-header-borne JWTs are small;
+// 16 KiB refuses a pathological header without touching real tokens.
+var MAX_ATTESTATION_JWT_BYTES = C.BYTES.kib(16);
+
+// Default acceptable PoP age (draft §8 step "iat within an acceptable
+// time window"). Operator-tunable via opts.maxPopAgeSec.
+var DEFAULT_POP_MAX_AGE_SEC = C.TIME.minutes(5) / C.TIME.seconds(1);
+
+// Sign/verify params keyed by alg — superset of _verifyParamsForAlg that
+// also covers EdDSA (used only on the attestation path; the ID-token
+// verifier keeps its own narrower table untouched).
+function _attestationCryptoParams(alg) {
+  if (alg === "EdDSA") return { hash: null };
+  return _verifyParamsForAlg(alg);
+}
+
+function _toAttestationPrivateKey(value, label) {
+  if (!value) {
+    throw new OAuthError("auth-oauth/attestation-no-key", label + ": privateKey is required");
+  }
+  if (value instanceof nodeCrypto.KeyObject) return value;
+  try {
+    if (typeof value === "string" || Buffer.isBuffer(value)) {
+      return nodeCrypto.createPrivateKey({ key: value, format: "pem" });
+    }
+    if (typeof value === "object" && value.kty) {
+      return nodeCrypto.createPrivateKey({ key: value, format: "jwk" });
+    }
+  } catch (e) {
+    throw new OAuthError("auth-oauth/attestation-bad-key",
+      label + ": private key parse failed: " + ((e && e.message) || String(e)));
+  }
+  throw new OAuthError("auth-oauth/attestation-bad-key",
+    label + ": privateKey must be a PEM string/Buffer, JWK object, or KeyObject");
+}
+
+// EC curve → the one ES* alg whose hash matches it (RFC 7518 §3.4).
+var _EC_CURVE_ALG = { prime256v1: "ES256", secp384r1: "ES384", secp521r1: "ES512" };
+
+// Resolve the JWS alg for an attestation / PoP signature. When the caller
+// gives no `algorithm`, infer the default that matches the key type so a
+// non-EC attester key (RSA, Ed25519) yields a self-consistent JWS — header
+// alg ⇄ signature key — instead of a fixed `ES256` header signed with the
+// real key, which `verifyClientAttestation`'s alg/kty cross-check would
+// then reject. An explicit alg incompatible with the key is refused BEFORE
+// signing rather than producing a self-invalid attestation.
+function _resolveAttestationAlg(explicitAlg, privateKey, label) {
+  var kty = privateKey.asymmetricKeyType;
+  var defaultAlg, compatible;
+  if (kty === "ec") {
+    var curve = (privateKey.asymmetricKeyDetails && privateKey.asymmetricKeyDetails.namedCurve) || "";
+    defaultAlg = _EC_CURVE_ALG[curve];
+    if (!defaultAlg) {
+      throw new OAuthError("auth-oauth/attestation-key-unsupported",
+        label + ": EC curve '" + curve + "' has no attestation JWS alg (use P-256 / P-384 / P-521)");
+    }
+    compatible = [defaultAlg];                       // an EC curve pins exactly one ES alg
+  } else if (kty === "rsa") {
+    defaultAlg = "RS256";
+    compatible = ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512"];
+  } else if (kty === "rsa-pss") {
+    defaultAlg = "PS256";
+    compatible = ["PS256", "PS384", "PS512"];        // an RSA-PSS key cannot produce an RS* signature
+  } else if (kty === "ed25519" || kty === "ed448") {
+    defaultAlg = "EdDSA";
+    compatible = ["EdDSA"];
+  } else {
+    throw new OAuthError("auth-oauth/attestation-key-unsupported",
+      label + ": key type '" + String(kty) + "' is not a supported attestation key (EC / RSA / Ed25519 / Ed448)");
+  }
+  if (explicitAlg === undefined || explicitAlg === null) return defaultAlg;
+  if (ATTESTATION_ALGS.indexOf(explicitAlg) === -1) {
+    throw new OAuthError("auth-oauth/attestation-alg-not-accepted",
+      label + ": alg '" + explicitAlg + "' is not an accepted attestation algorithm");
+  }
+  if (compatible.indexOf(explicitAlg) === -1) {
+    throw new OAuthError("auth-oauth/attestation-alg-key-mismatch",
+      label + ": alg '" + explicitAlg + "' is incompatible with the " + kty +
+      " key (compatible: " + compatible.join(", ") + ")");
+  }
+  return explicitAlg;
+}
+
+function _signAttestationJws(header, payload, privateKey, alg) {
+  var params = _attestationCryptoParams(alg);
+  var headerB64  = _b64urlEncode(Buffer.from(JSON.stringify(header), "utf8"));
+  var payloadB64 = _b64urlEncode(Buffer.from(JSON.stringify(payload), "utf8"));
+  var signingInput = headerB64 + "." + payloadB64;
+  var sig;
+  var input = Buffer.from(signingInput, "ascii");
+  if (params.hash === null) {
+    sig = nodeCrypto.sign(null, input, privateKey);     // EdDSA — no prehash
+  } else {
+    var keyParam = { key: privateKey };
+    if (params.padding !== undefined)     keyParam.padding     = params.padding;
+    if (params.saltLength !== undefined)  keyParam.saltLength  = params.saltLength;
+    if (params.dsaEncoding !== undefined) keyParam.dsaEncoding = params.dsaEncoding;
+    sig = nodeCrypto.sign(params.hash, input, keyParam);
+  }
+  return signingInput + "." + _b64urlEncode(sig);
+}
+
+// Verify a compact JWS against an already-imported public KeyObject. The
+// alg is read from the header but MUST equal expectedAlg AND match the
+// key's kty (via the shared cross-check) — no alg-confusion window.
+function _verifyAttestationJws(jws, publicKeyJwk, label) {
+  if (typeof jws !== "string" || jws.length === 0) {
+    throw new OAuthError("auth-oauth/attestation-malformed", label + ": JWT must be a non-empty string");
+  }
+  if (jws.length > MAX_ATTESTATION_JWT_BYTES) {
+    throw new OAuthError("auth-oauth/attestation-too-large",
+      label + ": JWT exceeds " + MAX_ATTESTATION_JWT_BYTES + " bytes");
+  }
+  var parts = jws.split(".");
+  if (parts.length === 5) {
+    throw new OAuthError("auth-oauth/attestation-jwe-refused",
+      label + ": 5-segment JWE refused — attestation JWTs are JWS only");
+  }
+  if (parts.length !== 3) {
+    throw new OAuthError("auth-oauth/attestation-malformed", label + ": JWT is not 3 segments");
+  }
+  var header, payload;
+  try {
+    header  = safeJson.parse(_b64urlDecode(parts[0]).toString("utf8"), { maxBytes: MAX_ATTESTATION_JWT_BYTES });
+    payload = safeJson.parse(_b64urlDecode(parts[1]).toString("utf8"), { maxBytes: MAX_ATTESTATION_JWT_BYTES });
+  } catch (e) {
+    throw new OAuthError("auth-oauth/attestation-malformed",
+      label + ": header/payload decode failed: " + ((e && e.message) || String(e)));
+  }
+  if (!header || typeof header.alg !== "string") {
+    throw new OAuthError("auth-oauth/attestation-malformed", label + ": header missing 'alg'");
+  }
+  if (ATTESTATION_ALGS.indexOf(header.alg) === -1) {
+    throw new OAuthError("auth-oauth/attestation-alg-not-accepted",
+      label + ": alg '" + header.alg + "' is not an accepted attestation algorithm " +
+      "(HMAC / none refused — alg-allowlist gate)");
+  }
+  if (header.crit !== undefined && header.crit !== null) {
+    throw new OAuthError("auth-oauth/attestation-crit-not-supported",
+      label + ": JWS 'crit' header is not supported (RFC 7515 §4.1.11)");
+  }
+  // CVE-2026-22817 — cross-check alg against the key's kty before verify.
+  jwtExternal._assertAlgKtyMatch(header.alg, publicKeyJwk);
+  var keyObject = _jwkToKey(publicKeyJwk);
+  var params = _attestationCryptoParams(header.alg);
+  var signingInput = parts[0] + "." + parts[1];
+  var sig = _b64urlDecode(parts[2]);
+  var verifyOpts = { key: keyObject };
+  if (params.padding !== undefined)     verifyOpts.padding     = params.padding;
+  if (params.saltLength !== undefined)  verifyOpts.saltLength  = params.saltLength;
+  if (params.dsaEncoding !== undefined) verifyOpts.dsaEncoding = params.dsaEncoding;
+  var ok;
+  try {
+    ok = nodeCrypto.verify(params.hash, Buffer.from(signingInput, "ascii"), verifyOpts, sig);
+  } catch (verifyErr) {
+    throw new OAuthError("auth-oauth/attestation-bad-signature",
+      label + ": signature verification raised: " + ((verifyErr && verifyErr.message) || String(verifyErr)));
+  }
+  if (!ok) {
+    throw new OAuthError("auth-oauth/attestation-bad-signature", label + ": signature verification failed");
+  }
+  return { header: header, payload: payload };
+}
+
+// Strip a JWK down to its public components only — a private half MUST
+// never reach the attestation's cnf claim. Mirrors the dpop.buildProof
+// public-only embed.
+function _publicCnfJwk(jwk, label) {
+  if (!jwk || typeof jwk !== "object") {
+    throw new OAuthError("auth-oauth/attestation-bad-cnf",
+      label + ": instanceKeyJwk (public JWK for the cnf claim) is required");
+  }
+  if (jwk.kty === "EC")  return { kty: "EC",  crv: jwk.crv, x: jwk.x, y: jwk.y };
+  if (jwk.kty === "OKP") return { kty: "OKP", crv: jwk.crv, x: jwk.x };
+  if (jwk.kty === "RSA") return { kty: "RSA", e: jwk.e, n: jwk.n };
+  throw new OAuthError("auth-oauth/attestation-bad-cnf",
+    label + ": instanceKeyJwk.kty='" + jwk.kty + "' is not an asymmetric public JWK");
+}
+
+/**
+ * @primitive b.auth.oauth.buildClientAttestation
+ * @signature b.auth.oauth.buildClientAttestation(opts)
+ * @since     0.14.20
+ * @status    experimental
+ * @related   b.auth.oauth.buildClientAttestationPop, b.auth.oauth.verifyClientAttestation
+ *
+ * Builds the `OAuth-Client-Attestation` JWT defined by
+ * draft-ietf-oauth-attestation-based-client-auth-08 §4. The client's
+ * backend ("Attester") signs a JWT binding the `client_id` (in `sub`)
+ * to a per-instance public key carried in the RFC 7800 `cnf` claim.
+ * The companion PoP (`buildClientAttestationPop`) then proves the
+ * instance holds the matching private key — together they replace a
+ * shared `client_secret` for FAPI / wallet clients.
+ *
+ * The JWT is a classical JWS (RS/PS/ES/EdDSA) signed via `node:crypto`;
+ * HMAC and `none` are refused. This is the interop case distinct from
+ * `b.auth.jwt`, which signs framework tokens PQC-only.
+ *
+ * Opt-in / additive: a client that never calls this behaves as before.
+ *
+ * @opts
+ *   {
+ *     clientId:            string,         // → sub claim (required)
+ *     attesterPrivateKey:  KeyObject|PEM|JWK, // Attester signing key (required)
+ *     instanceKeyJwk:      object,         // instance PUBLIC JWK → cnf.jwk (required)
+ *     algorithm?:          string,         // JWS alg (default: inferred from the key type — ES256/384/512, RS256, or EdDSA)
+ *     expiresInSec?:       number,         // exp = iat + this (default: 300)
+ *     nbf?:                number,         // optional not-before (epoch seconds)
+ *     iat?:                number,         // override issued-at (epoch seconds)
+ *     extraClaims?:        object,         // merged without overriding spec fields
+ *   }
+ *
+ * @example
+ *   var att = b.auth.oauth.buildClientAttestation({
+ *     clientId:           "wallet-app",
+ *     attesterPrivateKey: attesterKey,
+ *     instanceKeyJwk:     instancePublicJwk,
+ *   });
+ *   // → "eyJ0eXAiOiJvYXV0aC1jbGllbnQtYXR0ZXN0YXRpb24rand0Ii..."
+ */
+function buildClientAttestation(aopts) {
+  aopts = aopts || {};
+  validateOpts(aopts, [
+    "clientId", "attesterPrivateKey", "instanceKeyJwk", "algorithm",
+    "expiresInSec", "nbf", "iat", "extraClaims",
+  ], "auth.oauth.buildClientAttestation");
+  validateOpts.requireNonEmptyString(aopts.clientId,
+    "buildClientAttestation: clientId", OAuthError, "auth-oauth/attestation-no-client-id");
+  validateOpts.optionalPositiveInt(aopts.expiresInSec,
+    "buildClientAttestation: expiresInSec", OAuthError, "auth-oauth/attestation-bad-expiry");
+  var key = _toAttestationPrivateKey(aopts.attesterPrivateKey, "buildClientAttestation");
+  var alg = _resolveAttestationAlg(aopts.algorithm, key, "buildClientAttestation");
+  var cnfJwk = _publicCnfJwk(aopts.instanceKeyJwk, "buildClientAttestation");
+  var iatSec = typeof aopts.iat === "number" ? aopts.iat : Math.floor(Date.now() / C.TIME.seconds(1));
+  var ttl = typeof aopts.expiresInSec === "number" ? aopts.expiresInSec : DEFAULT_POP_MAX_AGE_SEC;
+  var payload = {
+    sub: aopts.clientId,                 // draft §4.1 — sub = client_id
+    iat: iatSec,
+    exp: iatSec + ttl,
+    cnf: { jwk: cnfJwk },                // draft §4.1 — RFC 7800 cnf
+  };
+  if (typeof aopts.nbf === "number") payload.nbf = aopts.nbf;
+  // Operator extra claims merged WITHOUT overriding the spec-required
+  // fields (no prototype-pollution: only own enumerable keys, reserved
+  // names rejected).
+  if (aopts.extraClaims && typeof aopts.extraClaims === "object" && !Array.isArray(aopts.extraClaims)) {
+    var ck = Object.keys(aopts.extraClaims);
+    for (var i = 0; i < ck.length; i += 1) {
+      var k = ck[i];
+      if (k === "__proto__" || k === "constructor" || k === "prototype") continue;
+      if (Object.prototype.hasOwnProperty.call(payload, k)) continue;   // never override spec fields
+      payload[k] = aopts.extraClaims[k];
+    }
+  }
+  return _signAttestationJws(
+    { typ: "oauth-client-attestation+jwt", alg: alg }, payload, key, alg);
+}
+
+/**
+ * @primitive b.auth.oauth.buildClientAttestationPop
+ * @signature b.auth.oauth.buildClientAttestationPop(opts)
+ * @since     0.14.20
+ * @status    experimental
+ * @related   b.auth.oauth.buildClientAttestation, b.auth.oauth.verifyClientAttestation
+ *
+ * Builds the `OAuth-Client-Attestation-PoP` JWT defined by
+ * draft-ietf-oauth-attestation-based-client-auth-08 §5. Signed by the
+ * per-instance PRIVATE key whose public half lives in the attestation's
+ * `cnf` claim, it proves the instance possesses that key for this
+ * request. `aud` MUST be the authorization server's issuer; `jti` is a
+ * fresh per-request identifier the AS tracks for replay defense.
+ *
+ * Asymmetric JWS only (RS/PS/ES/EdDSA) — MAC / `none` are refused.
+ *
+ * Opt-in / additive.
+ *
+ * @opts
+ *   {
+ *     instancePrivateKey:  KeyObject|PEM|JWK, // matches cnf.jwk (required)
+ *     audience:            string,         // AS issuer URL → aud (required)
+ *     algorithm?:          string,         // JWS alg (default: inferred from the key type — ES256/384/512, RS256, or EdDSA)
+ *     challenge?:          string,         // server-issued nonce → challenge claim
+ *     jti?:                string,         // override jti (default: fresh CSPRNG)
+ *     iat?:                number,         // override issued-at (epoch seconds)
+ *     expiresInSec?:       number,         // optional exp = iat + this
+ *   }
+ *
+ * @example
+ *   var pop = b.auth.oauth.buildClientAttestationPop({
+ *     instancePrivateKey: instanceKey,
+ *     audience:           "https://as.example.com",
+ *   });
+ *   // send both headers on the token request:
+ *   //   OAuth-Client-Attestation: <att>
+ *   //   OAuth-Client-Attestation-PoP: <pop>
+ */
+function buildClientAttestationPop(popts) {
+  popts = popts || {};
+  validateOpts(popts, [
+    "instancePrivateKey", "audience", "algorithm", "challenge",
+    "jti", "iat", "expiresInSec",
+  ], "auth.oauth.buildClientAttestationPop");
+  validateOpts.requireNonEmptyString(popts.audience,
+    "buildClientAttestationPop: audience (AS issuer)", OAuthError, "auth-oauth/attestation-pop-no-aud");
+  validateOpts.optionalNonEmptyString(popts.challenge,
+    "buildClientAttestationPop: challenge", OAuthError, "auth-oauth/attestation-pop-bad-challenge");
+  validateOpts.optionalPositiveInt(popts.expiresInSec,
+    "buildClientAttestationPop: expiresInSec", OAuthError, "auth-oauth/attestation-pop-bad-expiry");
+  var key = _toAttestationPrivateKey(popts.instancePrivateKey, "buildClientAttestationPop");
+  var alg = _resolveAttestationAlg(popts.algorithm, key, "buildClientAttestationPop");
+  var iatSec = typeof popts.iat === "number" ? popts.iat : Math.floor(Date.now() / C.TIME.seconds(1));
+  var jti = typeof popts.jti === "string" && popts.jti.length > 0
+              ? popts.jti : _generateRandomToken(STATE_NONCE_BYTES);
+  var payload = {
+    aud: popts.audience,                 // draft §5.2 — AS issuer
+    jti: jti,                            // draft §5.2 — replay detection
+    iat: iatSec,                         // draft §5.2
+  };
+  if (typeof popts.expiresInSec === "number") payload.exp = iatSec + popts.expiresInSec;
+  if (typeof popts.challenge === "string" && popts.challenge.length > 0) {
+    payload.challenge = popts.challenge; // draft §5.2 — server nonce
+  }
+  return _signAttestationJws(
+    { typ: "oauth-client-attestation-pop+jwt", alg: alg }, payload, key, alg);
+}
+
+/**
+ * @primitive b.auth.oauth.verifyClientAttestation
+ * @signature b.auth.oauth.verifyClientAttestation(attestationJwt, popJwt, opts)
+ * @since     0.14.20
+ * @status    experimental
+ * @related   b.auth.oauth.buildClientAttestation, b.auth.oauth.buildClientAttestationPop
+ *
+ * Verifies a `OAuth-Client-Attestation` + `OAuth-Client-Attestation-PoP`
+ * header pair, performing the authorization-server checks of
+ * draft-ietf-oauth-attestation-based-client-auth-08 §8: the attestation
+ * signature against a TRUSTED Attester key; the PoP signature against
+ * the attestation's `cnf` key (never the Attester's); attestation `exp`
+ * freshness; PoP `aud` == this AS issuer (constant-time); PoP `iat`
+ * within `maxPopAgeSec`; optional server-challenge binding; and `jti`
+ * replay defense via an operator-supplied atomic check-and-insert.
+ *
+ * Async (returns a Promise) so the `jti` replay store can be an async
+ * Redis / DB check-and-insert. Resolves to `{ clientId, cnfJwk,
+ * attestation, pop }` on success; rejects with a typed `OAuthError` on
+ * any failure. Opt-in / additive — an AS that doesn't accept
+ * attestation-based auth never calls it.
+ *
+ * @opts
+ *   {
+ *     attesterJwk:        object,    // trusted Attester PUBLIC JWK (required)
+ *     expectedAudience:   string,    // this AS issuer URL (required)
+ *     expectedClientId?:  string,    // request client_id; must equal attestation sub
+ *     challenge?:         string,    // server-issued nonce the PoP must echo
+ *     maxPopAgeSec?:      number,    // PoP iat freshness window (default: 300)
+ *     clockSkewSec?:      number,    // allowed skew (default: 60)
+ *     seenJti?:           function,  // (jti, iat) → truthy when UNSEEN (atomic); may return a Promise (async store)
+ *   }
+ *
+ * @example
+ *   var v = await b.auth.oauth.verifyClientAttestation(
+ *     req.headers["oauth-client-attestation"],
+ *     req.headers["oauth-client-attestation-pop"],
+ *     { attesterJwk: trustedAttesterJwk, expectedAudience: "https://as.example.com",
+ *       seenJti: function (jti) { return jtiStore.checkAndInsert(jti); } });
+ *   // → { clientId: "wallet-app", cnfJwk: {...}, attestation: {...}, pop: {...} }
+ */
+async function verifyClientAttestation(attestationJwt, popJwt, vopts) {
+  vopts = vopts || {};
+  validateOpts(vopts, [
+    "attesterJwk", "expectedAudience", "expectedClientId", "challenge",
+    "maxPopAgeSec", "clockSkewSec", "seenJti",
+  ], "auth.oauth.verifyClientAttestation");
+  if (!vopts.attesterJwk || typeof vopts.attesterJwk !== "object") {
+    throw new OAuthError("auth-oauth/attestation-no-attester-jwk",
+      "verifyClientAttestation: opts.attesterJwk (trusted Attester public JWK) is required");
+  }
+  validateOpts.requireNonEmptyString(vopts.expectedAudience,
+    "verifyClientAttestation: expectedAudience (this AS issuer)", OAuthError,
+    "auth-oauth/attestation-no-expected-aud");
+
+  // 1. Attestation signature against the TRUSTED attester key.
+  var att = _verifyAttestationJws(attestationJwt, vopts.attesterJwk, "client-attestation");
+  var ap = att.payload || {};
+  if (typeof ap.sub !== "string" || ap.sub.length === 0) {
+    throw new OAuthError("auth-oauth/attestation-no-sub",
+      "client-attestation: missing 'sub' (client_id) claim");
+  }
+  if (!ap.cnf || typeof ap.cnf !== "object" || !ap.cnf.jwk || typeof ap.cnf.jwk !== "object") {
+    throw new OAuthError("auth-oauth/attestation-no-cnf",
+      "client-attestation: missing 'cnf.jwk' confirmation key (RFC 7800)");
+  }
+  var nowSec  = Math.floor(Date.now() / C.TIME.seconds(1));
+  var skewSec = typeof vopts.clockSkewSec === "number" ? vopts.clockSkewSec : (C.TIME.minutes(1) / C.TIME.seconds(1));
+  if (typeof ap.exp !== "number" || ap.exp + skewSec < nowSec) {
+    throw new OAuthError("auth-oauth/attestation-expired",
+      "client-attestation: expired (exp=" + ap.exp + ", now=" + nowSec + ")");
+  }
+  if (typeof ap.nbf === "number" && ap.nbf - skewSec > nowSec) {
+    throw new OAuthError("auth-oauth/attestation-not-yet-valid", "client-attestation: nbf in the future");
+  }
+  if (vopts.expectedClientId !== undefined && vopts.expectedClientId !== null) {
+    // Exact equality (constant-time) — defends against a client_id the
+    // request claims that the attestation never bound (draft §8 step 10).
+    if (!_constantTimeStrEq(String(vopts.expectedClientId), ap.sub)) {
+      throw new OAuthError("auth-oauth/attestation-client-id-mismatch",
+        "client-attestation: sub does not match the request's client_id");
+    }
+  }
+
+  // 2. PoP signature against the attestation's cnf key (NOT the attester).
+  var pop = _verifyAttestationJws(popJwt, ap.cnf.jwk, "client-attestation-pop");
+  var pp = pop.payload || {};
+  // aud MUST be THIS AS issuer (constant-time, exact). Attacker-replayed
+  // PoP minted for a different AS is refused (draft §8 step 7).
+  if (typeof pp.aud !== "string" || !_constantTimeStrEq(vopts.expectedAudience, pp.aud)) {
+    throw new OAuthError("auth-oauth/attestation-pop-aud-mismatch",
+      "client-attestation-pop: aud does not match this authorization server's issuer");
+  }
+  if (typeof pp.jti !== "string" || pp.jti.length === 0) {
+    throw new OAuthError("auth-oauth/attestation-pop-no-jti", "client-attestation-pop: missing 'jti'");
+  }
+  if (typeof pp.iat !== "number") {
+    throw new OAuthError("auth-oauth/attestation-pop-no-iat", "client-attestation-pop: missing 'iat'");
+  }
+  var maxAge = typeof vopts.maxPopAgeSec === "number" ? vopts.maxPopAgeSec : DEFAULT_POP_MAX_AGE_SEC;
+  if (pp.iat - skewSec > nowSec) {
+    throw new OAuthError("auth-oauth/attestation-pop-iat-future", "client-attestation-pop: iat in the future");
+  }
+  if (pp.iat + maxAge + skewSec < nowSec) {
+    throw new OAuthError("auth-oauth/attestation-pop-stale",
+      "client-attestation-pop: iat older than maxPopAgeSec (" + maxAge + "s)");
+  }
+  if (typeof pp.exp === "number" && pp.exp + skewSec < nowSec) {
+    throw new OAuthError("auth-oauth/attestation-pop-expired", "client-attestation-pop: expired");
+  }
+  // challenge binding when the AS issued one (draft §8 step 5/6).
+  if (vopts.challenge !== undefined && vopts.challenge !== null) {
+    if (typeof pp.challenge !== "string" || !_constantTimeStrEq(String(vopts.challenge), pp.challenge)) {
+      throw new OAuthError("auth-oauth/attestation-pop-challenge-mismatch",
+        "client-attestation-pop: challenge does not match the server-issued value");
+    }
+  }
+  // Replay defense (draft §12.1). Atomic check-and-insert contract:
+  // returns truthy when the jti was UNSEEN (first sighting). The result
+  // MAY be a Promise (Redis/DB store) — it is awaited so an async store's
+  // resolved `false` (a replayed jti) refuses, instead of comparing a
+  // never-`false` Promise object. Hot dep — a thrown / rejected callback
+  // is surfaced as a typed error, not swallowed.
+  if (typeof vopts.seenJti === "function") {
+    var unseen;
+    try {
+      unseen = vopts.seenJti(pp.jti, pp.iat);
+      if (unseen && typeof unseen.then === "function") unseen = await unseen;
+    } catch (e) {
+      throw new OAuthError("auth-oauth/attestation-pop-seen-callback-failed",
+        "client-attestation-pop: seenJti() callback threw: " + ((e && e.message) || String(e)));
+    }
+    if (unseen === false) {
+      throw new OAuthError("auth-oauth/attestation-pop-replay",
+        "client-attestation-pop: jti already seen (replay refused, draft §12.1)");
+    }
+  }
+  return {
+    clientId:    ap.sub,
+    cnfJwk:      ap.cnf.jwk,
+    attestation: ap,
+    pop:         pp,
+  };
+}
+
+// Constant-time string equality. b.crypto.timingSafeEqual accepts
+// strings, returns false (never throws) on length mismatch, and refuses
+// non-string/Buffer input — so it carries the timing + type discipline.
+function _constantTimeStrEq(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return false;
+  return cryptoTimingSafeEqual(a, b);
+}
+
 // ---- core ----
 
 function create(opts) {
@@ -609,6 +1248,17 @@ function create(opts) {
     if (uopts.prompt)  params.set("prompt", uopts.prompt);
     if (uopts.loginHint) params.set("login_hint", uopts.loginHint);
     if (uopts.maxAge != null) params.set("max_age", String(uopts.maxAge));
+    // RFC 9396 — fine-grained authorization request. Validated at this
+    // entry-point (THROW on bad shape) then serialized as the JSON-array
+    // `authorization_details` parameter. The validated array is returned
+    // so the caller can thread it into exchangeCode for the granted-vs-
+    // requested cross-check.
+    var requestedAuthzDetails = null;
+    if (uopts.authorizationDetails !== undefined) {
+      requestedAuthzDetails = _validateAuthorizationDetailsArray(
+        uopts.authorizationDetails, "authorizationUrl");
+      params.set("authorization_details", JSON.stringify(requestedAuthzDetails));
+    }
     // Operator-supplied additional params (audience, resource, etc.).
     if (uopts.extraParams && typeof uopts.extraParams === "object") {
       var ek = Object.keys(uopts.extraParams);
@@ -621,6 +1271,7 @@ function create(opts) {
       nonce:     nonce,
       verifier:  pkceVals ? pkceVals.verifier  : null,
       challenge: pkceVals ? pkceVals.challenge : null,
+      authorizationDetails: requestedAuthzDetails,
     };
   }
 
@@ -655,9 +1306,25 @@ function create(opts) {
     body.set("client_id",    clientId);
     if (clientSecret) body.set("client_secret", clientSecret);
     if (eopts.verifier) body.set("code_verifier", eopts.verifier);
+    // RFC 9396 — the operator threads the requested authorization_details
+    // (the validated array returned from authorizationUrl /
+    // pushAuthorizationRequest) so the granted set in the token response
+    // can be cross-checked. The array is also re-sent on the token
+    // request, which RFC 9396 §6.3 allows for narrowing the grant.
+    var requestedAuthzDetails = null;
+    if (eopts.authorizationDetails !== undefined && eopts.authorizationDetails !== null) {
+      requestedAuthzDetails = _validateAuthorizationDetailsArray(
+        eopts.authorizationDetails, "exchangeCode");
+      body.set("authorization_details", JSON.stringify(requestedAuthzDetails));
+    }
 
     var tokens = await _postForm(endpoint, body);
-    return await _normalizeTokens(tokens, { nonce: eopts.nonce, skipNonceCheck: eopts.skipNonceCheck });
+    return await _normalizeTokens(tokens, {
+      nonce:          eopts.nonce,
+      skipNonceCheck: eopts.skipNonceCheck,
+      requestedAuthorizationDetails: requestedAuthzDetails,
+      verifyAuthorizationDetails:    eopts.verifyAuthorizationDetails,
+    });
   }
 
   async function refreshAccessToken(refreshToken, ropts) {
@@ -1042,6 +1709,21 @@ function create(opts) {
         picture: v.claims.picture,
       };
     }
+    // RFC 9396 §7 — surface the GRANTED authorization_details and, when
+    // the operator threaded the requested array through, cross-check it.
+    // strict by default whenever a request was sent (refuse an over-
+    // grant); operators that intentionally accept asymmetric grants pass
+    // verifyAuthorizationDetails: false.
+    if (raw.authorization_details !== undefined) {
+      var strict = vopts.requestedAuthorizationDetails != null &&
+                   vopts.verifyAuthorizationDetails !== false;
+      tokens.authorizationDetails = _crossCheckGrantedAuthorizationDetails(
+        raw.authorization_details,
+        vopts.requestedAuthorizationDetails != null ? vopts.requestedAuthorizationDetails : null,
+        strict);
+    } else {
+      tokens.authorizationDetails = null;
+    }
     return tokens;
   }
 
@@ -1347,6 +2029,14 @@ function create(opts) {
     if (uopts.loginHint) body.set("login_hint", uopts.loginHint);
     if (uopts.maxAge != null) body.set("max_age", String(uopts.maxAge));
     if (clientSecret) body.set("client_secret", clientSecret);
+    // RFC 9396 — push the fine-grained authorization request through PAR
+    // identically to the redirect path (validated, then JSON-serialized).
+    var requestedAuthzDetails = null;
+    if (uopts.authorizationDetails !== undefined) {
+      requestedAuthzDetails = _validateAuthorizationDetailsArray(
+        uopts.authorizationDetails, "pushAuthorizationRequest");
+      body.set("authorization_details", JSON.stringify(requestedAuthzDetails));
+    }
     if (uopts.extraParams && typeof uopts.extraParams === "object") {
       var ek = Object.keys(uopts.extraParams);
       for (var i = 0; i < ek.length; i++) body.set(ek[i], String(uopts.extraParams[ek[i]]));
@@ -1371,6 +2061,7 @@ function create(opts) {
       challenge:   pkceVals.challenge,
       requestUri:  rv.request_uri,
       expiresIn:   typeof rv.expires_in === "number" ? rv.expires_in : null,
+      authorizationDetails: requestedAuthzDetails,
     };
   }
 
@@ -2151,6 +2842,42 @@ function create(opts) {
     });
   }
 
+  // draft-ietf-oauth-attestation-based-client-auth — convenience that
+  // builds BOTH headers for THIS client. clientId is taken from create();
+  // audience defaults to the configured issuer (the AS the client talks
+  // to). The instance attestation/PoP keys are passed per call.
+  function clientAttestationHeaders(copts) {
+    copts = copts || {};
+    var audience = copts.audience || issuer;
+    if (!audience) {
+      throw new OAuthError("auth-oauth/attestation-no-aud",
+        "clientAttestationHeaders: opts.audience (AS issuer) is required when the client " +
+        "was created without an issuer");
+    }
+    var attestation = buildClientAttestation({
+      clientId:           clientId,
+      attesterPrivateKey: copts.attesterPrivateKey,
+      instanceKeyJwk:     copts.instanceKeyJwk,
+      algorithm:          copts.algorithm,
+      expiresInSec:       copts.expiresInSec,
+    });
+    var pop = buildClientAttestationPop({
+      instancePrivateKey: copts.instancePrivateKey,
+      audience:           audience,
+      algorithm:          copts.popAlgorithm || copts.algorithm,
+      challenge:          copts.challenge,
+      expiresInSec:       copts.popExpiresInSec,
+    });
+    return {
+      attestation: attestation,
+      pop:         pop,
+      headers: {
+        "OAuth-Client-Attestation":     attestation,
+        "OAuth-Client-Attestation-PoP": pop,
+      },
+    };
+  }
+
   return {
     authorizationUrl:                authorizationUrl,
     exchangeCode:                    exchangeCode,
@@ -2175,6 +2902,7 @@ function create(opts) {
     pollDeviceCode:                  pollDeviceCode,
     exchangeToken:                   exchangeToken,
     nativeSsoExchange:               nativeSsoExchange,
+    clientAttestationHeaders:        clientAttestationHeaders,
     // Diagnostic / power-user surface
     issuer:              issuer,
     clientId:            clientId,
@@ -2189,10 +2917,17 @@ module.exports = {
   PRESETS:               PRESETS,
   OAuthError:            OAuthError,
   DEFAULT_ACCEPTED_ALGS: DEFAULT_ACCEPTED_ALGS,
+  ATTESTATION_ALGS:      ATTESTATION_ALGS,
+  // draft-ietf-oauth-attestation-based-client-auth — issuer-agnostic
+  // builders + validator (usable without a create()'d client).
+  buildClientAttestation:    buildClientAttestation,
+  buildClientAttestationPop: buildClientAttestationPop,
+  verifyClientAttestation:   verifyClientAttestation,
   // Internal helpers exposed for tests
   _generatePkce:         _generatePkce,
   _generateRandomToken:  _generateRandomToken,
   _b64urlEncode:         _b64urlEncode,
   _b64urlDecode:         _b64urlDecode,
   _verifyParamsForAlg:   _verifyParamsForAlg,
+  _crossCheckGrantedAuthorizationDetails: _crossCheckGrantedAuthorizationDetails,
 };