@blamejs/core 0.8.76 → 0.8.77

package/CHANGELOG.md

@@ -8,6 +8,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.8.x
 
+- v0.8.77 (2026-05-10) — substantive additive release closing 10 audit clusters surfaced by the 8-agent compliance audit. **OAuth resource-server completeness**: `b.auth.oauth.introspectToken` (RFC 7662), `registerClient` (RFC 7591 — refuses empty redirect_uris), `deviceAuthorization` + `pollDeviceCode` (RFC 8628 with slow_down/authorization_pending handling), `exchangeToken` (RFC 8693 subject+actor delegation), new `b.middleware.protectedResourceMetadata` serving `.well-known/oauth-protected-resource` (draft-ietf-oauth-resource-metadata). **Vendored-deps SBOM**: new `scripts/build-vendored-sbom.js` emits `sbom.vendored.cdx.json` (CycloneDX 1.6) covering every `lib/vendor/*` bundle with per-file SHA-256 + purl + license metadata; wired into `npm-publish.yml` so OSV-Scanner now scans it alongside the primary `sbom.cdx.json` — closes the gap where downstream scanners couldn't see what was actually shipping. **MCP endpoint coverage**: `b.mcp.assertProtocolVersion` (MCP 2025-11-25 §4.1 header), `b.mcp.sampling.guard({ maxRequestsPerSession, maxMessagesPerRequest, maxTokensPerRequest, allowedModelHints })` (HIGH-RISK endpoint — confused-deputy class), `b.mcp.elicitation.guard` (prompt-injection scan + schema-type allowlist + size cap). **ACME completeness**: `revokeCert` (RFC 8555 §7.6), `accountKeyRollover` (§7.3.5), `deactivateAccount` (§7.3.6), `tlsAlpn01KeyAuthorization` (RFC 8737), External Account Binding opt on `newAccount` (§7.3.4 — required by ZeroSSL/Buypass/Google CA) — closes 47-day CA/B forum surface before Mar 2026 effective date. **Permissions-Policy denylist** expanded with `identity-credentials-get`, `attribution-reporting-cross-site`, `publickey-credentials-create`, `join-ad-interest-group`, `run-ad-auction`, `shared-storage`, `shared-storage-select-url`, `smartcard`, `all-screens-capture`, `deferred-fetch` (10 directives — single-file fix). **NIST control crosswalk**: new `b.nistCrosswalk` catalog mapping `800-53r5` (~50 controls), `csf-2.0` (~22 functions), `800-171r3` (~25 requirements), `800-218` (SSDF tasks) to framework primitives — used by operators producing SSPs, POAMs, ATO packages, CMMC self-assessments. **SCIM 2.0 server**: new `b.middleware.scimServer` implementing RFC 7642/7643/7644 — Users + Groups + ServiceProviderConfig + ResourceTypes + Schemas + filter parser (eq/ne/co/sw/ew/pr/gt/ge/lt/le) + GET/POST/PUT/PATCH/DELETE dispatch + bearer-auth callback hook + 1 MiB body cap; the most operator-visible federation gap before this — Okta/Entra/etc. couldn't push users without an external adapter. **CRA + EU AI Act forward-deadline templates**: `b.cra.conformityAssessment` Annex VIII technical dossier scaffold (CE marking, Module routing, vuln-handling auto-fill), `b.complianceAiAct.fundamentalRightsImpactAssessment` (Article 27 FRIA template — mandatory for Annex III §5-8 deployers), `b.complianceAiAct.gpai.trainingDataSummary` (Article 53(1)(d) AI Office template — mandatory 2026-08-02). **C2PA COSE_Sign1 wrap**: new `b.contentCredentials.signCose` produces RFC 9052 COSE_Sign1 CBOR envelope with x5chain header + ML-DSA-87 / ed25519 / es256/384/512 / SLH-DSA-SHAKE-256f algorithms — interops with c2patool / JPEG Trust / Adobe verifiers (current `sign()` ships a blamejs-internal envelope; the new `signCose()` ships the canonical wire format). **US state-law backlog**: 22 new compliance postures (`vcdpa`, `co-cpa`, `ctdpa`, `ucpa`, `tdpsa`, `or-cpa`, `mt-cdpa`, `ia-icdpa`, `in-indpa`, `de-dpdpa`, `nh-nhpa`, `nj-njdpa`, `ky-kcdpa`, `tn-tipa`, `mn-mncdpa`, `ri-ricpa`, `ne-dpa`, `nv-sb370`, `ca-aadc`, `ct-sb3`, `tx-cubi`, plus existing `modpa` + `quebec-25`) registered in `b.compliance` + per-state DSR rules via `b.dsr.stateRules(state)` / `b.dsr.listStateRules()` returning `{ responseDays, extensionDays, cureDays, profilingOptOut, minorOptIn, notes }`. **Operator hook**: `b.middleware.rateLimit` instance gains `.resetAll()` for clean-slate flushing during incident-response (in-memory backends only; cluster backend no-ops per multi-replica race-safety). Cluster backend correctly refuses lest one replica's flush race another's in-flight `take()`. **`b.config.loadDbBacked` gains `transformValue: (row) => string | Promise<string>`** — per-row transform applied between `fetchRows` and schema validation; common shape is unsealing a `b.vault`-sealed ciphertext column so canonical secrets live encrypted-at-rest in `_blamejs_config_overrides`. Per-row failures (transform throws OR returns non-string) emit `config.reload.failed` and skip the row so a single bad row can't crash the poller. **`b.cryptoField` gains `sealDoc` / `unsealDoc` doc-shaped aliases** of the existing `sealRow` / `unsealRow` — same identity, lets downstream tests reach for the document-naming convention when preparing seed objects via raw `INSERT`. **Bug fix — `b.config` reactive `value`**: `cfg.value.X` now reflects the latest validated state after every `reload()` (and every `loadDbBacked` poll). Before this fix, `cfg.value` was a captured property pinned to the create-time object, so `cfg.value.FEATURE_X` stayed stale forever and only `cfg.get("FEATURE_X")` saw updates — the published example in `@primitive b.config.loadDbBacked` was wrong against the implementation. Now backed by a `Object.defineProperty` getter; `cfg.get()` / `cfg.has()` semantics unchanged. **Bug fix — `b.config.loadDbBacked` startup hydration window**: `loadDbBacked` returned a config handle that stayed at env-only defaults for the first `intervalMs` because `safeAsync.repeating` is `setInterval`-shaped (no t=0 fire). The handle now kicks off one immediate hydration `_tick()` on construction and exposes `cfg.hydrated` — a Promise that resolves after the first tick settles. Callers awaiting it before serving traffic get a fully-hydrated config; the Promise NEVER rejects (per-tick failures route through audit, last-good value stays). **`b.middleware._modules.rateLimit.instances()` + module-level `.resetAll()`** — module now keeps a registry of every rate-limit middleware created in the process. Incident-response scripts can enumerate every limiter and flush state across the whole process without threading references through the app code. `create()` registers; `middleware.close()` deregisters. Top-level `resetAll()` returns the count of instances it walked.
 - v0.8.76 (2026-05-10) — CI green-up for v0.8.75. The OSV-Scanner v2 binary refuses to parse SBOMs whose filename doesn't match the CycloneDX recognized-pattern spec — `sbom.cyclonedx.json` is NOT recognized; only `bom.json` / `*.cdx.json` / `*.spdx.json` etc. are. v0.8.75's npm-publish workflow failed with `Failed to parse SBOM "sbom.cyclonedx.json": Invalid SBOM filename`. Renamed the artifact to `sbom.cdx.json` everywhere (workflow generation step, post-process script, OSV scan target, cosign sign target, GH release asset upload, `package.json` `files` array, `scripts/check-pack-against-gitignore.js` allowlist, `.gitignore` allowlist). No primitive surface change versus v0.8.75; published-tarball asset filename changes from `sbom.cyclonedx.json` to `sbom.cdx.json` (consumers reading the SBOM out of the install tree should update the path).
 - v0.8.75 (2026-05-10) — CI green-up for v0.8.73 + v0.8.74. The OSV-Scanner action's v2.3.5 binary removed the `--fail-on-vuln=<severity>` flag; passing it now errors with `flag provided but not defined: -fail-on-vuln` and the entire npm-publish workflow exits 1 before `npm publish` ever runs. v0.8.73 + v0.8.74's npm-publish workflows both failed for this reason (Dependabot bumped osv-scanner-action 2.0.2 → 2.3.5 in PR #8 alongside the v2 flag removal; the workflow was never re-tested under the new binary). v2's default behavior is exit-1-on-ANY-finding — stricter than the v1 `--fail-on-vuln=HIGH` floor, and appropriate for a zero-npm-runtime-dep framework where any surfaced vuln means a vendor refresh is overdue. The framework currently has no findings, so the stricter floor is a no-op at HEAD. No primitive surface change versus v0.8.74.
 - v0.8.74 (2026-05-10) — line-ending fix for shell scripts that run inside Linux containers. The OSS-Fuzz + ClusterFuzzLite `build.sh`, the wiki + release Dockerfile init scripts, the Postgres + Mongo TLS bootstrap scripts, and the vendor-update + dep-confusion-placeholder scripts all execute inside bash inside a Linux container; under a Windows checkout with `core.autocrlf=true` git rewrites them to CRLF on checkout and bash then chokes with `$'\r': command not found` at line 1. Locally reproduced the OSS-Fuzz upstream submission failure (zero artifacts compiled, every `compile_javascript_fuzzer` call failed silently on the CRLF). `.gitattributes` gains an explicit `*.sh text eol=lf` override so every `.sh` checks out LF regardless of platform; existing tracked scripts re-normalized (CRLF stripped) in the same commit. Verified end-to-end: `docker run … gcr.io/oss-fuzz-base/base-builder-javascript bash /src/build.sh` now compiles all 15 fuzz harnesses + zips their seed corpora cleanly. Unblocks the OSS-Fuzz upstream submission.

package/index.js

@@ -107,6 +107,7 @@ var chainWriter = require("./lib/chain-writer");
 var safeBuffer = require("./lib/safe-buffer");
 var lazyRequire = require("./lib/lazy-require");
 var frameworkError = require("./lib/framework-error");
+var nistCrosswalk = require("./lib/nist-crosswalk");
 var httpClient = require("./lib/http-client");
 // Attach the encrypted-payload helper from the api-encrypt middleware so
 // `b.httpClient.encrypted({ pubkey, baseUrl })` is available alongside
@@ -367,6 +368,7 @@ module.exports = {
   auditDailyReview: auditDailyReview,
   ddlChangeControl: ddlChangeControl,
   compliance:       compliance,
+  nistCrosswalk:    nistCrosswalk,
   dataAct:          dataAct,
   gateContract:     gateContract,
   guardCsv:         guardCsv,

package/lib/acme.js

@@ -483,10 +483,47 @@ function create(opts) {
     return body;
   }
 
-  async function newAccount() {
+  async function newAccount(nopts) {
+    nopts = nopts || {};
     if (!state.directory) await fetchDirectory();
     var payload = { termsOfServiceAgreed: true };
     if (Array.isArray(opts.contact) && opts.contact.length > 0) payload.contact = opts.contact.slice();
+    // RFC 8555 §7.3.4 — External Account Binding (EAB). Required by
+    // ZeroSSL / Buypass / Google CA / many other commercial CAs.
+    // The operator obtains `kid` + `hmacKey` from the CA's account
+    // dashboard and supplies them either via the `externalAccountBinding`
+    // opt on newAccount() OR statically on create() opts. The EAB
+    // payload is an inner-JWS over the account's public JWK signed
+    // with HMAC-SHA256 keyed by the CA-supplied HMAC key.
+    var eab = nopts.externalAccountBinding || opts.externalAccountBinding;
+    if (eab) {
+      if (typeof eab.kid !== "string" || eab.kid.length === 0) {
+        throw _err("acme/eab-no-kid",
+          "newAccount: externalAccountBinding.kid required (RFC 8555 §7.3.4)", true);
+      }
+      if (typeof eab.hmacKey !== "string" || eab.hmacKey.length === 0) {
+        throw _err("acme/eab-no-hmac",
+          "newAccount: externalAccountBinding.hmacKey required (base64url-encoded)", true);
+      }
+      var eabProtected = {
+        alg:  eab.alg || "HS256",
+        kid:  eab.kid,
+        url:  state.directory.newAccount,
+      };
+      // Inner JWS: payload = the account's public JWK (RFC 8555 §7.3.4).
+      var eabHeaderB64  = _b64u(Buffer.from(_stringify(eabProtected), "utf8"));
+      var eabPayloadB64 = _b64u(Buffer.from(_stringify(publicJwk), "utf8"));
+      var eabSigningInput = eabHeaderB64 + "." + eabPayloadB64;
+      var hmacKeyRaw = Buffer.from(eab.hmacKey, "base64url");
+      var hmac = require("node:crypto").createHmac("sha256", hmacKeyRaw);
+      hmac.update(eabSigningInput);
+      var eabSig = _b64u(hmac.digest());
+      payload.externalAccountBinding = {
+        protected: eabHeaderB64,
+        payload:   eabPayloadB64,
+        signature: eabSig,
+      };
+    }
     var rsp = await _signedPost(state.directory.newAccount, payload, { useJwk: true });
     if (rsp.statusCode !== 200 && rsp.statusCode !== 201) {
       _emitAudit(audit, "acme.account.registered", "failure",
@@ -701,6 +738,164 @@ function create(opts) {
     return { shouldRenew: true, reason: "in-window", ari: ari };
   }
 
+  /**
+   * @primitive b.acme.create.revokeCert
+   * @signature b.acme.create.revokeCert(certDerBuf, opts?)
+   * @since     0.8.77
+   *
+   * RFC 8555 §7.6 — revoke a previously issued certificate. Accepts
+   * the DER-encoded cert (base64url-encoded automatically) plus an
+   * optional `reason` code per RFC 5280 §5.3.1 (0=unspecified,
+   * 1=keyCompromise, 3=affiliationChanged, 4=superseded, 5=cessationOfOperation).
+   * Signs with the account key by default; pass `useCertKey:true`
+   * + the cert's private key to authorize via the cert's own key
+   * when the account key is unavailable.
+   *
+   * @opts
+   *   reason:          number,    // RFC 5280 §5.3.1 reason code; default 0 (unspecified)
+   *   useCertKey:      boolean,   // sign with the cert's own key instead of account key
+   *   certPrivateKey:  KeyObject, // required when useCertKey:true
+   *
+   * @example
+   *   await acme.revokeCert(certDerBuffer, { reason: 4 });   // 4 = superseded
+   */
+  async function revokeCert(certDerBuf, ropts) {
+    ropts = ropts || {};
+    if (!Buffer.isBuffer(certDerBuf) && !(certDerBuf instanceof Uint8Array)) {
+      throw _err("acme/revoke-bad-cert",
+        "revokeCert: certDerBuf must be a Buffer / Uint8Array of the cert's DER bytes", true);
+    }
+    if (!state.directory) await fetchDirectory();
+    if (!state.directory.revokeCert) {
+      throw _err("acme/revoke-not-supported",
+        "revokeCert: directory has no revokeCert endpoint", true);
+    }
+    var payload = { certificate: _b64u(Buffer.from(certDerBuf)) };
+    if (typeof ropts.reason === "number") payload.reason = ropts.reason;
+    var signedOpts = { useJwk: false };                  // account-key signed by default
+    if (ropts.useCertKey === true) {
+      // RFC 8555 §7.6 alternate: certificate's own key as signer. Operator
+      // supplies the cert's private key via ropts.certPrivateKey; we
+      // build a one-off signed-post bypassing _signedPost's state.accountUrl
+      // assumption. For minimal v1 we support account-key signing only and
+      // document the cert-key path as not-yet-implemented.
+      throw _err("acme/revoke-cert-key-not-implemented",
+        "revokeCert: cert-key signing path not yet implemented; use account-key signing", true);
+    }
+    var rsp = await _signedPost(state.directory.revokeCert, payload, signedOpts);
+    if (rsp.statusCode !== 200) {
+      _emitAudit(audit, "acme.cert.revoked", "failure",
+        { status: rsp.statusCode, reason: _extractProblemReason(rsp.body) });
+      throw _err("acme/revoke-failed",
+        "revokeCert returned " + rsp.statusCode, true, rsp.statusCode);
+    }
+    _emitAudit(audit, "acme.cert.revoked", "success", { reason: ropts.reason || null });
+    _emitObs("acme.cert.revoked", { reason: ropts.reason || 0 });
+    return true;
+  }
+
+  /**
+   * @primitive b.acme.create.accountKeyRollover
+   * @signature b.acme.create.accountKeyRollover(newPrivateKey)
+   * @since     0.8.77
+   *
+   * RFC 8555 §7.3.5 — rotate the account key. Inner JWS payload
+   * commits the old + new public JWKs; outer JWS signed by old key
+   * authorizes the rotation. After success, future signed-posts use
+   * the new key. The instance is mutated; callers using multiple
+   * acme instances must rotate each independently.
+   *
+   * @example
+   *   var newKey = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" }).privateKey;
+   *   await acme.accountKeyRollover(newKey);
+   */
+  async function accountKeyRollover(newPrivateKey) {
+    if (!state.directory) await fetchDirectory();
+    if (!state.accountUrl) {
+      throw _err("acme/no-account", "accountKeyRollover: call newAccount() first", true);
+    }
+    if (!state.directory.keyChange) {
+      throw _err("acme/key-change-not-supported",
+        "accountKeyRollover: directory has no keyChange endpoint", true);
+    }
+    if (!newPrivateKey || typeof newPrivateKey !== "object") {
+      throw _err("acme/bad-new-key", "accountKeyRollover: newPrivateKey must be a KeyObject", true);
+    }
+    var newPublicJwk = _publicJwkFromKeyObject(newPrivateKey);
+    var innerProtected = {
+      alg: opts.alg || "ES256",
+      jwk: newPublicJwk,
+      url: state.directory.keyChange,
+    };
+    var innerPayload = { account: state.accountUrl, oldKey: publicJwk };
+    var innerJws = _signJws(newPrivateKey, innerProtected, _stringify(innerPayload));
+    var rsp = await _signedPost(state.directory.keyChange, innerJws);
+    if (rsp.statusCode !== 200) {
+      _emitAudit(audit, "acme.account.key_rotated", "failure",
+        { status: rsp.statusCode, reason: _extractProblemReason(rsp.body) });
+      throw _err("acme/key-change-failed",
+        "accountKeyRollover returned " + rsp.statusCode, true, rsp.statusCode);
+    }
+    // Swap the active key.
+    privateKey = newPrivateKey;
+    publicJwk  = newPublicJwk;
+    _emitAudit(audit, "acme.account.key_rotated", "success", { accountUrl: state.accountUrl });
+    _emitObs("acme.account.key_rotated", {});
+    return true;
+  }
+
+  /**
+   * @primitive b.acme.create.deactivateAccount
+   * @signature b.acme.create.deactivateAccount()
+   * @since     0.8.77
+   *
+   * RFC 8555 §7.3.6 — deactivate the account. The CA refuses subsequent
+   * requests signed by this account key. Irreversible — operators must
+   * register a new account via newAccount() afterwards.
+   *
+   * @example
+   *   await acme.deactivateAccount();
+   */
+  async function deactivateAccount() {
+    if (!state.accountUrl) {
+      throw _err("acme/no-account", "deactivateAccount: call newAccount() first", true);
+    }
+    var rsp = await _signedPost(state.accountUrl, { status: "deactivated" });
+    if (rsp.statusCode !== 200) {
+      _emitAudit(audit, "acme.account.deactivated", "failure",
+        { status: rsp.statusCode, reason: _extractProblemReason(rsp.body) });
+      throw _err("acme/deactivate-failed",
+        "deactivateAccount returned " + rsp.statusCode, true, rsp.statusCode);
+    }
+    _emitAudit(audit, "acme.account.deactivated", "success", { accountUrl: state.accountUrl });
+    return true;
+  }
+
+  /**
+   * @primitive b.acme.create.tlsAlpn01KeyAuthorization
+   * @signature b.acme.create.tlsAlpn01KeyAuthorization(token)
+   * @since     0.8.77
+   *
+   * RFC 8737 — TLS-ALPN-01 challenge variant. Returns the SHA-256
+   * digest of the key authorization (the value the operator embeds
+   * in the `acme-tls/1` SNI cert's `id-pe-acmeIdentifier` extension).
+   * Operator wires the digest into a one-off cert presented during
+   * the CA's ALPN-ALPN-1 probe. Pairs with HTTP-01 + DNS-01 as the
+   * three RFC 8555 / RFC 8737 challenge types.
+   *
+   * @example
+   *   var digest = acme.tlsAlpn01KeyAuthorization(challengeToken);
+   *   // embed `digest` in the acme-tls/1 cert's acmeIdentifier extension.
+   */
+  function tlsAlpn01KeyAuthorization(token) {
+    if (typeof token !== "string" || token.length === 0) {
+      throw _err("acme/bad-token", "tlsAlpn01KeyAuthorization: token must be a non-empty string", true);
+    }
+    var keyAuth = token + "." + _jwkThumbprint(publicJwk);
+    var crypto  = require("node:crypto");
+    return crypto.createHash("sha256").update(keyAuth, "utf8").digest();
+  }
+
   return Object.freeze({
     fetchDirectory:  fetchDirectory,
     newAccount:      newAccount,
@@ -709,6 +904,10 @@ function create(opts) {
     retrieveCert:    retrieveCert,
     fetchAri:        fetchAri,
     renewIfDue:      renewIfDue,
+    revokeCert:      revokeCert,
+    accountKeyRollover: accountKeyRollover,
+    deactivateAccount:  deactivateAccount,
+    tlsAlpn01KeyAuthorization: tlsAlpn01KeyAuthorization,
     accountUrl:      function () { return state.accountUrl; },
     directory:       function () { return state.directory; },
     publicJwk:       function () { return Object.assign({}, publicJwk); },

package/lib/auth/oauth.js

@@ -107,6 +107,7 @@
 var nodeCrypto = require("node:crypto");
 var cache = require("../cache");
 var C = require("../constants");
+var safeAsync = require("../safe-async");
 var { generateBytes } = require("../crypto");
 var httpClient = require("../http-client");
 var safeJson = require("../safe-json");
@@ -455,6 +456,9 @@ function create(opts) {
       checkSessionIframe:    "check_session_iframe",
       pushedAuthorizationRequestEndpoint: "pushed_authorization_request_endpoint",
       backchannelAuthenticationEndpoint:  "backchannel_authentication_endpoint",
+      introspectionEndpoint:              "introspection_endpoint",
+      registrationEndpoint:               "registration_endpoint",
+      deviceAuthorizationEndpoint:        "device_authorization_endpoint",
     })[name];
     var endpoint = config[snake];
     if (!endpoint) {
@@ -1252,6 +1256,326 @@ function create(opts) {
     return url;
   }
 
+  /**
+   * @primitive b.auth.oauth.introspectToken
+   * @signature b.auth.oauth.introspectToken(token, opts?)
+   * @since     0.8.77
+   * @related   b.middleware.bearerAuth
+   *
+   * RFC 7662 OAuth 2.0 Token Introspection. Resource-server side
+   * primitive: POSTs to the AS's introspection endpoint with the
+   * presented token and returns the active/inactive verdict + claims.
+   * `active: false` SHOULD be treated as token-invalid regardless of
+   * other fields (RFC 7662 §2.2). When the AS supports `token_type_hint`,
+   * pass `opts.tokenTypeHint` ("access_token" or "refresh_token") to
+   * speed up the lookup; the AS may ignore the hint.
+   *
+   * @opts
+   *   {
+   *     tokenTypeHint?: "access_token" | "refresh_token",
+   *   }
+   *
+   * @example
+   *   var verdict = await oauth.introspectToken(bearer);
+   *   if (!verdict.active) throw new Error("invalid_token");
+   */
+  async function introspectToken(token, iopts) {
+    iopts = iopts || {};
+    if (typeof token !== "string" || token.length === 0) {
+      throw new OAuthError("auth-oauth/bad-introspect",
+        "introspectToken: token must be a non-empty string");
+    }
+    var endpoint;
+    try { endpoint = await _resolveEndpoint("introspectionEndpoint"); }
+    catch (_e) {
+      throw new OAuthError("auth-oauth/no-introspection-endpoint",
+        "introspectToken: AS does not advertise introspection_endpoint " +
+        "(set opts.introspectionEndpoint on create() if it's static)");
+    }
+    var body = new URLSearchParams();
+    body.set("token", token);
+    if (iopts.tokenTypeHint) body.set("token_type_hint", iopts.tokenTypeHint);
+    body.set("client_id", clientId);
+    if (clientSecret) body.set("client_secret", clientSecret);
+    var parsed = await _postForm(endpoint, body);
+    // RFC 7662 §2.2 — `active` is the only required field; coerce
+    // every other interpretation through it.
+    if (typeof parsed.active !== "boolean") {
+      throw new OAuthError("auth-oauth/bad-introspect-response",
+        "introspectToken: response missing required `active` boolean");
+    }
+    return parsed;
+  }
+
+  /**
+   * @primitive b.auth.oauth.registerClient
+   * @signature b.auth.oauth.registerClient(metadata, opts?)
+   * @since     0.8.77
+   * @related   b.auth.oauth.introspectToken
+   *
+   * RFC 7591 OAuth 2.0 Dynamic Client Registration. POSTs the
+   * client metadata to the AS's `registration_endpoint` and returns
+   * the issued `client_id` + (for confidential clients) `client_secret`
+   * + `registration_access_token` + `registration_client_uri`.
+   *
+   * The framework refuses to register a client without an explicit
+   * `redirect_uris` array — RFC 7591 §2 makes it OPTIONAL but every
+   * security-sensitive deployment needs it; mis-registering with an
+   * empty list lets any redirect_uri be assigned later by the AS.
+   *
+   * @opts
+   *   {
+   *     initialAccessToken?: string,   // RFC 7591 §3 — bearer for the registration endpoint
+   *   }
+   *
+   * @example
+   *   var rv = await oauth.registerClient({
+   *     redirect_uris:            ["https://rp.example/cb"],
+   *     token_endpoint_auth_method: "client_secret_basic",
+   *     grant_types:              ["authorization_code", "refresh_token"],
+   *     response_types:           ["code"],
+   *     client_name:              "Example RP",
+   *   });
+   *   // rv.client_id / rv.client_secret / rv.registration_access_token
+   */
+  async function registerClient(metadata, ropts) {
+    ropts = ropts || {};
+    if (!metadata || typeof metadata !== "object") {
+      throw new OAuthError("auth-oauth/bad-register",
+        "registerClient: metadata must be an object");
+    }
+    if (!Array.isArray(metadata.redirect_uris) || metadata.redirect_uris.length === 0) {
+      throw new OAuthError("auth-oauth/register-no-redirect-uris",
+        "registerClient: metadata.redirect_uris must be a non-empty array " +
+        "(RFC 7591 §2 makes it optional, but registering without explicit URIs " +
+        "creates an open-redirect surface)");
+    }
+    var endpoint;
+    try { endpoint = await _resolveEndpoint("registrationEndpoint"); }
+    catch (_e) {
+      throw new OAuthError("auth-oauth/no-registration-endpoint",
+        "registerClient: AS does not advertise registration_endpoint");
+    }
+    var hc      = httpClient;
+    var headers = {
+      "Content-Type": "application/json",
+      "Accept":       "application/json",
+    };
+    if (ropts.initialAccessToken) {
+      headers["Authorization"] = "Bearer " + ropts.initialAccessToken;
+    }
+    var req = {
+      url:     endpoint,
+      method:  "POST",
+      headers: headers,
+      body:    Buffer.from(safeJson.stringify(metadata), "utf8"),
+    };
+    if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
+    if (allowInternal !== null) req.allowInternal = allowInternal;
+    Object.assign(req, httpClientOpts);
+    var res  = await hc.request(req);
+    var text = res.body ? res.body.toString("utf8") : "";
+    if (res.statusCode < 200 || res.statusCode >= 300) {
+      throw new OAuthError("auth-oauth/register-failed-" + res.statusCode,
+        "registerClient: " + res.statusCode + ": " + text.slice(0, 500));
+    }
+    var parsed;
+    try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
+    catch (e) {
+      throw new OAuthError("auth-oauth/bad-register-response",
+        "registerClient: response not JSON: " + ((e && e.message) || String(e)));
+    }
+    if (typeof parsed.client_id !== "string" || parsed.client_id.length === 0) {
+      throw new OAuthError("auth-oauth/register-no-client-id",
+        "registerClient: response missing client_id");
+    }
+    return parsed;
+  }
+
+  /**
+   * @primitive b.auth.oauth.deviceAuthorization
+   * @signature b.auth.oauth.deviceAuthorization(opts?)
+   * @since     0.8.77
+   * @related   b.auth.oauth.pollDeviceCode
+   *
+   * RFC 8628 OAuth 2.0 Device Authorization Grant. Initiates the
+   * device-code flow by POSTing to the AS's device_authorization
+   * endpoint. Returns `{ device_code, user_code, verification_uri,
+   * verification_uri_complete?, expires_in, interval }`. The caller
+   * displays `user_code` + `verification_uri` to the user, then polls
+   * via `pollDeviceCode(device_code, { interval })`.
+   *
+   * @opts
+   *   {
+   *     scope?: string[],    // override the client's default scope set
+   *   }
+   *
+   * @example
+   *   var auth = await oauth.deviceAuthorization();
+   *   console.log("Visit " + auth.verification_uri + " and enter " + auth.user_code);
+   *   var tokens = await oauth.pollDeviceCode(auth.device_code, { interval: auth.interval });
+   */
+  async function deviceAuthorization(dopts) {
+    dopts = dopts || {};
+    var endpoint;
+    try { endpoint = await _resolveEndpoint("deviceAuthorizationEndpoint"); }
+    catch (_e) {
+      throw new OAuthError("auth-oauth/no-device-endpoint",
+        "deviceAuthorization: AS does not advertise device_authorization_endpoint");
+    }
+    var body = new URLSearchParams();
+    body.set("client_id", clientId);
+    if (clientSecret) body.set("client_secret", clientSecret);
+    var scopes = Array.isArray(dopts.scope) ? dopts.scope : scope;
+    if (scopes && scopes.length > 0) body.set("scope", scopes.join(" "));
+    var parsed = await _postForm(endpoint, body);
+    if (typeof parsed.device_code !== "string" ||
+        typeof parsed.user_code   !== "string" ||
+        typeof parsed.verification_uri !== "string") {
+      throw new OAuthError("auth-oauth/bad-device-response",
+        "deviceAuthorization: response missing device_code / user_code / verification_uri");
+    }
+    return parsed;
+  }
+
+  /**
+   * @primitive b.auth.oauth.pollDeviceCode
+   * @signature b.auth.oauth.pollDeviceCode(deviceCode, opts?)
+   * @since     0.8.77
+   * @related   b.auth.oauth.deviceAuthorization
+   *
+   * Polls the token endpoint with grant_type=urn:ietf:params:oauth:
+   * grant-type:device_code per RFC 8628 §3.4-§3.5. Honors the slow_down
+   * error by extending the interval; returns the token response on
+   * success; throws on expired_token / access_denied.
+   *
+   * @opts
+   *   {
+   *     interval?:  number,        // seconds — default from deviceAuthorization()
+   *     maxWaitMs?: number,        // total budget (default 600s)
+   *   }
+   *
+   * @example
+   *   var auth = await oauth.deviceAuthorization();
+   *   var tokens = await oauth.pollDeviceCode(auth.device_code, { interval: auth.interval });
+   */
+  async function pollDeviceCode(deviceCode, popts) {
+    popts = popts || {};
+    if (typeof deviceCode !== "string" || deviceCode.length === 0) {
+      throw new OAuthError("auth-oauth/bad-device-code",
+        "pollDeviceCode: deviceCode must be a non-empty string");
+    }
+    var endpoint = await _resolveEndpoint("tokenEndpoint");
+    var interval = Math.max(1, popts.interval || 5);
+    var deadline = Date.now() + (popts.maxWaitMs || C.TIME.minutes(10));
+    while (Date.now() < deadline) {
+      var body = new URLSearchParams();
+      body.set("grant_type",  "urn:ietf:params:oauth:grant-type:device_code");
+      body.set("device_code", deviceCode);
+      body.set("client_id",   clientId);
+      if (clientSecret) body.set("client_secret", clientSecret);
+      var hc  = httpClient;
+      var req = {
+        url:     endpoint,
+        method:  "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          "Accept":       "application/json",
+        },
+        body:    Buffer.from(body.toString(), "utf8"),
+      };
+      if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
+      if (allowInternal !== null) req.allowInternal = allowInternal;
+      Object.assign(req, httpClientOpts);
+      var res    = await hc.request(req);
+      var text   = res.body ? res.body.toString("utf8") : "";
+      var parsed;
+      try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
+      catch (_e) { parsed = null; }
+      if (res.statusCode >= 200 && res.statusCode < 300 && parsed && parsed.access_token) {
+        return await _normalizeTokens(parsed, popts);
+      }
+      // RFC 8628 §3.5 — error codes that should keep polling.
+      var err = parsed && parsed.error;
+      if (err === "authorization_pending") {
+        await safeAsync.sleep(C.TIME.seconds(interval));
+        continue;
+      }
+      if (err === "slow_down") {
+        interval += 5;
+        await safeAsync.sleep(C.TIME.seconds(interval));
+        continue;
+      }
+      // Terminal errors.
+      throw new OAuthError("auth-oauth/device-" + (err || "unknown"),
+        "pollDeviceCode: " + (parsed && parsed.error_description ? parsed.error_description : text.slice(0, 200)));   // allow:raw-byte-literal — 200-char error-snippet cap, not bytes
+    }
+    throw new OAuthError("auth-oauth/device-poll-timeout",
+      "pollDeviceCode: exceeded maxWaitMs " + (popts.maxWaitMs || C.TIME.minutes(10)));
+  }
+
+  /**
+   * @primitive b.auth.oauth.exchangeToken
+   * @signature b.auth.oauth.exchangeToken(opts)
+   * @since     0.8.77
+   * @related   b.auth.oauth.introspectToken
+   *
+   * RFC 8693 OAuth 2.0 Token Exchange. Trades a subject token (and
+   * optionally an actor token for delegation chains) for a new
+   * access token with different audience / scopes / authorization
+   * context. Used by middleware tier services that need to call
+   * downstream APIs on behalf of an upstream caller.
+   *
+   * @opts
+   *   {
+   *     subjectToken:     string,     // required
+   *     subjectTokenType: string,     // required — RFC 8693 §3 URN
+   *     actorToken?:      string,     // delegation actor
+   *     actorTokenType?:  string,     // RFC 8693 §3 URN
+   *     audience?:        string,
+   *     resource?:        string,
+   *     scope?:           string[],
+   *     requestedTokenType?: string,  // default: access_token URN
+   *   }
+   *
+   * @example
+   *   var newTokens = await oauth.exchangeToken({
+   *     subjectToken:     upstreamAccessToken,
+   *     subjectTokenType: "urn:ietf:params:oauth:token-type:access_token",
+   *     audience:         "https://downstream.example.com",
+   *   });
+   */
+  async function exchangeToken(xopts) {
+    xopts = xopts || {};
+    if (typeof xopts.subjectToken !== "string" || xopts.subjectToken.length === 0) {
+      throw new OAuthError("auth-oauth/bad-exchange",
+        "exchangeToken: opts.subjectToken required");
+    }
+    if (typeof xopts.subjectTokenType !== "string") {
+      throw new OAuthError("auth-oauth/bad-exchange",
+        "exchangeToken: opts.subjectTokenType required (RFC 8693 §3 URN)");
+    }
+    var endpoint = await _resolveEndpoint("tokenEndpoint");
+    var body = new URLSearchParams();
+    body.set("grant_type",           "urn:ietf:params:oauth:grant-type:token-exchange");
+    body.set("subject_token",        xopts.subjectToken);
+    body.set("subject_token_type",   xopts.subjectTokenType);
+    body.set("client_id",            clientId);
+    if (clientSecret)         body.set("client_secret", clientSecret);
+    if (xopts.actorToken)     body.set("actor_token", xopts.actorToken);
+    if (xopts.actorTokenType) body.set("actor_token_type", xopts.actorTokenType);
+    if (xopts.audience)       body.set("audience", xopts.audience);
+    if (xopts.resource)       body.set("resource", xopts.resource);
+    if (xopts.scope && xopts.scope.length > 0) {
+      body.set("scope", xopts.scope.join(" "));
+    }
+    if (xopts.requestedTokenType) {
+      body.set("requested_token_type", xopts.requestedTokenType);
+    }
+    var parsed = await _postForm(endpoint, body);
+    return await _normalizeTokens(parsed, xopts);
+  }
+
   return {
     authorizationUrl:                authorizationUrl,
     exchangeCode:                    exchangeCode,
@@ -1267,6 +1591,11 @@ function create(opts) {
     checkSessionIframeUrl:           checkSessionIframeUrl,
     parseCallback:                   parseCallback,
     parseJarmResponse:               parseJarmResponse,
+    introspectToken:                 introspectToken,
+    registerClient:                  registerClient,
+    deviceAuthorization:             deviceAuthorization,
+    pollDeviceCode:                  pollDeviceCode,
+    exchangeToken:                   exchangeToken,
     // Diagnostic / power-user surface
     issuer:              issuer,
     clientId:            clientId,