@blamejs/core 0.18.7 → 0.18.9

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.18.x
 
+- v0.18.9 (2026-08-02) — **Broader error- and edge-path test coverage for the CLI, mail, and HTTP-client primitives.** Error, edge, and fallback branches of b.cli, b.mail, and b.httpClient are now under explicit test. No behaviour changes: exercising every path confirmed each already behaves per its documented contract. One dead internal parameter on the HTTP-client cache path — never supplied by any caller — was removed. **Changed:** *Error- and edge-path tests for the CLI, mail, and HTTP-client primitives* — b.cli (the api-snapshot capture/compare load-error paths and the restore-apply round trip), b.mail (reverse-DNS forward-confirmation and failure fallbacks, SMTP UTF-8 and binary-MIME detection on edge inputs, AUTH LOGIN with an empty password, and audit-emit failures being swallowed without masking the delivery outcome), and b.httpClient (the HTTPS-connect failure classification and the HTTP/2 synchronous-request-throw path) now have explicit tests for their boundary branches. Behaviour is unchanged.
+
+- v0.18.8 (2026-08-02) — **SSRF-safe local-transport HTTP, timestamped-HMAC webhook verification, the OAuth client-credentials grant, trusted-proxy identity headers, and a public keyed-HMAC primitive; plus a fix for a filterless overflow update that could rewrite every row.** Five general-purpose primitives land: talking HTTP to a co-located daemon over a socket the SSRF gate cannot protect, verifying the single-header timestamped-HMAC webhook scheme, the machine-to-machine OAuth client_credentials grant with a cached auto-renewing token manager, and peer-gated trust of a reverse proxy's identity headers. b.crypto.hmac exposes the framework's keyed HMAC (SHA3-512 by default; weaker digests available explicitly for external-scheme interop) and replaces b.crypto.hmacSha3. Separately, an update() on a collection whose field lives in the overflow store, called with no filter, no longer slips past the unconditional-write guard and silently rewrites every row. **Added:** *b.localHttp — SSRF-safe HTTP over a local transport* — b.localHttp.create({ socketPath }) and b.localHttp.request() speak HTTP to a co-located daemon over a Unix domain socket, a Windows named pipe, or a loopback TCP peer with a bearer token — the transports an SSRF gate cannot protect, because there is no network host to steer. It deliberately does not route through b.httpClient (DNS + the SSRF gate): a socket-path request cannot be pointed at an arbitrary IP, so that surface is exactly what it exists to bypass safely. It refuses any non-loopback TCP host, never forwards Origin or Referer to the daemon, bounds the response body, and sets the caller's Host header verbatim. Use it for a local control-plane API — a sidecar's endpoint, a container-runtime socket, a metrics port. · *b.webhookHmac.verify — timestamped-HMAC webhook verification* — Verifies the single-header timestamped-HMAC webhook scheme — t=<unix-seconds>,v1=<hmac-hex> signed over <timestamp>.<raw-body> — used by Stripe, Tailscale, and others. It refuses a timestamp outside the tolerance window (replay defense), checks every v1 value so a rotated signing secret verifies with no downtime, compares in constant time, and ignores signature versions it does not recognize. Pass the exact bytes received, not a parsed-then-re-serialized JSON body, or the HMAC will not reproduce. This is distinct from b.standardWebhooks, which verifies the three-header StandardWebhooks scheme. · *b.auth.oauth.clientCredentials + clientCredentialsManager — the client_credentials grant* — The RFC 6749 §4.4 client_credentials grant for machine-to-machine authentication with no user present: clientCredentials() POSTs grant_type=client_credentials and returns the access token — never a refresh token, per the RFC. It authenticates with the client id/secret via client_secret_post (default) or client_secret_basic (tokenEndpointAuthMethod), sends no scope unless you supply one (the authorization-code scope default is not applied to a machine-to-machine request), and a client_credentials-only client needs no redirectUri at create. clientCredentialsManager() wraps it in an in-memory cache that fetches on first use, re-fetches a configurable window before expiry, collapses concurrent callers onto one in-flight request, and — throughout a 429 backoff window (honoring the server's Retry-After when present) — serves the still-valid cached token or fails fast without another network call, rather than hammering the authorization server. The client's tokenEndpointAuthMethod (client_secret_post / client_secret_basic) applies uniformly to every token-endpoint request, not just this grant. · *b.requestHelpers.trustedIdentityHeaders — peer-gated proxy identity headers* — Resolves an identity-injecting reverse proxy's header family — Cloudflare Access Cf-Access-*, oauth2-proxy X-Forwarded-User, Tailscale Serve Tailscale-User-*, or any custom mapping — under the same trusted-proxy peer-gate as b.requestHelpers.trustedClientIp. It is the identity-header mirror of the X-Forwarded-For discipline: the family is trusted only when the immediate socket peer is a configured trusted proxy; from any other peer the headers are stripped from req.headers so downstream code cannot read a forged identity. With no gate configured it fails closed and always strips. A naive trust of these headers is a full impersonation bypass; this closes it by construction rather than opening a second, looser trust path. · *b.crypto.hmac — a public keyed-HMAC primitive* — b.crypto.hmac(key, data, algorithm = "sha3-512") exposes the framework's keyed HMAC with a PQC-first SHA3-512 default. Weaker digests (sha256, sha384, sha512, sha3-256, sha3-384) are available by naming them explicitly, for interop with an external scheme that pins one — a provider's SHA-256 webhook signature, for example; SHA-1 and MD5 are refused. Key and data accept a Buffer or a string; the result is a lowercase hex digest. **Removed:** *b.crypto.hmacSha3 (folded into b.crypto.hmac)* — b.crypto.hmacSha3 is removed. b.crypto.hmac already defaults to SHA3-512, so replace b.crypto.hmacSha3(key, data) with b.crypto.hmac(key, data) — the same algorithm and the same output. **Fixed:** *A filterless update on an overflow-backed collection no longer rewrites every row* — An update() on a collection whose target field lives in the overflow (JSON) store, called with no filter conditions — an empty or absent query — slipped past the unconditional-write guard that protects real-column updates and silently rewrote every row: the internal per-row writes each carry a WHERE by row id, so the guard never saw a match-everything update. Such an update is now refused with the same "call where(...) first" error as a real-column update. Provide an explicit filter for the rows you intend to change. **Detectors:** *Overflow-store update re-asserts the unconditional-write refusal* — A source guard keeps the overflow-store update path re-checking, on its read query, that a filter is present — so a filterless overflow update cannot regress to silently rewriting every row.
+
 - v0.18.7 (2026-08-02) — **STARTTLS idle-timeout no longer injects plaintext into the encrypted channel; broader mail-server test coverage.** A STARTTLS upgrade on the POP3 / IMAP / ManageSieve / SMTP-submission / MX servers left the pre-upgrade plain-socket idle-timeout handler armed, so a post-handshake idle wrote a plaintext timeout reply into the now-encrypted stream (the peer saw a TLS decode error / reset). The shared socket-upgrade path now strips that handler so the idle timeout is delivered encrypted. Alongside the fix, error and edge branches of b.mail.server.pop3, b.mail.server.imap, and b.mail.auth are now under test. Except for the fix, behaviour is unchanged. **Changed:** *Error- and edge-path tests for the POP3, IMAP, and mail-authentication primitives* — b.mail.server.pop3 (the STLS upgrade and post-handshake idle timeout, pipelined-command draining, AUTH / APOP / USER-PASS branches, and store-fallback and tenant-refusal shapes), b.mail.server.imap (APPEND / CATENATE literal handling, command-dispatch and guard-error branches, and the LOGIN / NOTIFY paths), and b.mail.auth (SPF macro expansion and record parsing, iprev forward-confirm, and dual-CIDR a/mx parsing) now have explicit tests for their boundary paths. **Security:** *STARTTLS idle timeout is delivered over the encrypted channel, not injected as plaintext* — The POP3, IMAP, ManageSieve, SMTP-submission, and MX servers arm a plain-socket idle timer whose handler writes a plaintext idle-timeout reply and closes the connection. After a STARTTLS upgrade the shared socket-upgrade path stripped only the plain socket's data listeners, so that plaintext handler survived the wrap and, on a post-handshake idle, injected cleartext into the now-encrypted stream — the peer observed a TLS decode error or connection reset instead of a clean encrypted timeout reply. The upgrade path now strips the plain socket's timeout listeners and disarms its idle timer, so the upgraded TLS socket owns the idle timeout and replies over the encrypted channel. **Detectors:** *STARTTLS upgrade strips the plaintext idle-timeout handler* — A source guard keeps the shared socket-upgrade path stripping the plain socket's timeout listeners alongside its data listeners, so a plaintext idle-timeout reply cannot survive into the encrypted channel.
 
 - v0.18.6 (2026-08-01) — **Mail SMTPUTF8 + credential-validation fixes and a static-quota fail-open fix, with broad error- and edge-path test coverage.** b.mail no longer forces SMTPUTF8 on a long-but-pure-ASCII subject or address (so such a message delivers to a peer that does not advertise SMTPUTF8), and now rejects a non-string credential/identity option at config time instead of crashing mid-send. b.static enforces its per-actor concurrency and bandwidth quotas even when a proxy blanks the client IP, closing a fail-open. Alongside the fixes, error, edge, and adversarial branches of the blamejs CLI, b.mail, b.mail.bimi, and b.static are now under test. Except for the noted fixes, behaviour is unchanged. **Changed:** *restore rollback names the resolved target in its missing-path error* — b.restoreRollback.rollback's missing-target error now names the resolved rollback path, so an operator — and the CLI's relative `--rollback` resolution — can see exactly which path was checked and found missing. · *Error- and edge-path tests for the CLI, mail sender, BIMI verifier, and static-file server* — The blamejs CLI (migrate/seed runner coded-error paths, the dev runner's --watch / --ignore / --kill-signal handling and start-rejection exit, restore inspect/apply/rollback and list-rollbacks, backup inspect/verify, mtls show-cert / status, vault status, and config-drift inspect on a tampered sidecar), b.mail (SMTPUTF8 handling, reverse-DNS forward-confirm, address and EAI-domain validation edges, the outbound SMTP-smuggling refusal, DATA dot-stuffing transparency, the send-audit recipient counts, DKIM-sign and interpret error fallbacks, the console / http / resend transports and their option defaults, guardDomain profile defaults and cc/bcc validation, and the CAN-SPAM refusal audit), b.mail.bimi's verification branches (including the empty-canonical-domain SAN-authorization backstop), and b.static's request, path-resolution, and quota-enforcement branches (including concurrency-slot release on a mid-stream client abort) now have explicit tests for their boundary paths. **Fixed:** *A long pure-ASCII subject or address no longer forces SMTPUTF8* — b.mail treated any subject or address longer than 254 characters as non-ASCII content, so an otherwise-deliverable pure-ASCII message required SMTPUTF8 (RFC 6531) and was refused with `eai-required-not-supported` whenever the receiving server did not advertise SMTPUTF8. The requirement is now decided solely by whether a field carries a non-ASCII code point, independent of length: long ASCII subjects and addresses deliver to any peer, and genuinely non-ASCII content still opts into SMTPUTF8 where the peer advertises it. · *Non-string SMTP transport options are rejected at config time* — b.mail.transports.smtp accepted a present-but-non-string user, pass, host, servername, or ehloName at build, then failed later on the wire — a numeric user, for example, reached `Buffer.from` at AUTH and threw, failing the send instead of authenticating. Such a value is now rejected at config time with `mail/smtp-misconfigured`, so a misconfiguration fails fast at boot rather than at first send. **Security:** *A blank client IP no longer disables b.static per-actor quotas* — The shared request-context reader let an empty req.ip shadow the socket-address fallback, yielding a null actor key that silently skipped b.static's per-actor concurrency and bandwidth caps (fail-open) — for example behind a proxy that blanks req.ip when it can't resolve a forwarded address. A blank req.ip now falls through to the real peer address, so the quotas are enforced. **Detectors:** *SMTPUTF8 requirement stays content-based, not length-bounded* — A source guard keeps b.mail's SMTPUTF8 decision keyed on the presence of a non-ASCII code point rather than the length-bounded ASCII validity check, so the long-ASCII-subject deliverability regression cannot return. · *SMTP field validation fails closed on a non-string value* — A source guard keeps b.mail's SMTP identity/credential field check rejecting a present non-string value at config time rather than passing it through to crash on the wire. · *A blank req.ip must not shadow the socket-address fallback* — A source guard keeps the request-context reader falling through to the socket address on an empty req.ip, so per-actor quotas that key off the resolved IP cannot be silently disabled.

package/README.md

@@ -79,6 +79,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
   - OAuth 2.0 JARM signed-response decode (`parseJarmResponse`)
   - RFC 9101 JWT-Secured Authorization Request verification — server-side request-object parse with mandatory alg allowlist + iss/client_id/aud binding + anti-nesting (`b.auth.jar.parse`)
   - One-time-use refresh-token rotation with operator-supplied replay-defense callback (RFC 9700 §4.13 / OAuth 2.1 §6.1 — `refreshAccessToken({ seen })`)
+  - RFC 6749 §4.4 `client_credentials` grant for machine-to-machine auth, with a cached auto-renewing token manager — single-flight fetch, re-fetch before expiry, ride out a 429 on the cached token (`clientCredentials` / `clientCredentialsManager`)
 - **Federation / VC** — CIBA Core 1.0 (`b.auth.ciba`, poll/ping/push); OpenID Federation 1.0 trust chain + metadata_policy (`b.auth.openidFederation`); SAML 2.0 SP with XMLDSig signature-wrapping defense + RFC 9525 server-identity (`b.auth.saml`); OpenID4VCI 1.0 issuer (`b.auth.oid4vci`); OpenID4VP 1.0 verifier with DCQL (`b.auth.oid4vp`); SD-JWT VC with `key_attestation` extension (`b.auth.sdJwtVc`)
 - **Sessions** — `b.session`
   - PQC-sealed sid cookie (ML-KEM-1024 + P-384 hybrid + XChaCha20-Poly1305 wire envelope)
@@ -104,7 +105,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **Field-level + crypto-shred** — `b.cryptoField.eraseRow`; per-column and per-row data residency tagging enforced at the write boundary (cross-border DML refused under GDPR / UK-GDPR / DPDP / PIPL / LGPD / APPI / PDPA postures) — on the structured builder, on raw SQL writes (`b.db.runSql` / `b.db.prepare().run()`, parsed quote-aware and failing closed when unparseable), on read-replica fan-out (a regulated read with no row region identified is refused), and surfaced by `b.backup.create` for any per-row-residency table whose admitted regions differ from the backup destination — plus per-row keys (each row's key derives from a CSPRNG row-secret sealed under the vault root, never from an on-disk value) so destroying a row's wrapped secret leaves its WAL / replica / backup residual ciphertext undecryptable even with the vault root key (`b.cryptoField.declareColumnResidency`, `b.cryptoField.declarePerRowResidency`, `b.cryptoField.listPerRowResidency`, `b.cryptoField.declarePerRowKey`)
 - **AAD-bound sealed columns** — AEAD tag tied to `(table, rowId, column, schemaVersion)`; copy-paste between rows or schema-version replay surfaces as refused decrypt (`b.vault.aad`). The database encryption key is sealed the same way — bound to its purpose, data directory, and key path — so a relocated key file fails to unseal; an older unbound key upgrades itself on first load. A vault-key rotation re-seals every AAD-bound cell, the database key, and tenant archives under the new keypair and refuses rather than silently orphaning a store it cannot reach (`b.vaultRotate`, `b.vault.aad.resealRoot`, `b.archive.rewrapTenant`)
 - **Keyed lookup hashes** — sealed-column equality-lookup hashes default to salted SHA3-512 and can opt into a keyed `hmac-shake256` MAC off a per-deployment key (`cryptoField.registerTable({ derivedHashMode })`, `b.vault.getDerivedHashMacKey`), making the lookup hash unforgeable and un-correlatable across deployments
-- **Signed webhooks + API encryption** — SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in; ECIES API encryption (`b.webhook`, `b.crypto`)
+- **Signed webhooks + API encryption** — SLH-DSA-SHAKE-256f default; ML-DSA-65 opt-in; ECIES API encryption (`b.webhook`, `b.crypto`); inbound timestamped-HMAC (`t=,v1=`) webhook verification with a replay window, key-rotation multi-signature, and constant-time compare (`b.webhookHmac`); and a public keyed-HMAC primitive with a SHA3-512 default and explicit weaker digests for external-scheme interop (`b.crypto.hmac`)
 - **HPKE / HTTP signatures** — RFC 9180 HPKE with ML-KEM-1024 + HKDF-SHA3-512 + ChaCha20-Poly1305 (`b.crypto.hpke`); RFC 9421 HTTP Message Signatures with derived components and ed25519 / ML-DSA-65 (`b.crypto.httpSig`); RFC 9530 Content-Digest / Repr-Digest body-integrity fields (SHA-256 / SHA-512, legacy algorithms refused — `b.contentDigest`) to sign the digest rather than the whole body
 - **X-Wing hybrid KEM** — `b.crypto.xwing` (draft-connolly-cfrg-xwing-kem, experimental): ML-KEM-768 + X25519 bound by SHA3-256, secure if either component holds — the conservative key-encapsulation shape for migrating off classical ECDH. `keygen` / `encapsulate` / `decapsulate` with a 1216-byte public key, 1120-byte ciphertext, and 32-byte shared secret
 - **Link header** — RFC 8288 Web Linking codec (`b.linkHeader.parse` / `serialize`): parse and build `Link: <uri>; rel="next"` relations, the standard REST pagination mechanism; quote-aware (a comma inside a quoted parameter never splits the list)
@@ -137,6 +138,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
   - Every access-refusal layer takes a uniform `problemDetails: true` for an RFC 9457 `application/problem+json` body or `onDeny(req, res, info)` to render the refusal itself — so a service can standardize one error envelope across its API without working around hardcoded bodies (`b.problemDetails`)
 - **Additional middleware** to mount in your `routes` callback: compression, SSE, request logging, request-time DB role binding (`b.middleware.dbRoleFor`), in-process CIDR fence (`b.middleware.networkAllowlist`)
 - **Outbound HTTP client** — HTTP/1.1 + HTTP/2 with SSRF gate (cloud-metadata IPs hard-denied; private / loopback / link-local overridable per call); scheme + userinfo + per-host destination allowlist; redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`)
+- **Local-transport HTTP** — HTTP to a co-located daemon over a Unix domain socket, a Windows named pipe, or a loopback TCP peer with a bearer token — the transports the SSRF gate cannot protect, since there is no network host to steer; refuses any non-loopback host, never forwards Origin / Referer to the daemon, and bounds the response body (`b.localHttp`)
 - **Network configurability (`b.network`)** — env-driven NTP / NTS (RFC 8915), IPv4/IPv6 NTP, DNS with IPv6 / DoH / DoT (private-CA pinning) / cache / lookup timeout; local DNSSEC signature verification (RFC 4035 — `b.network.dns.dnssec.verifyRrset` over a canonicalised RRset against RSA / ECDSA P-256·P-384 / Ed25519 DNSKEYs, plus DS-digest + key-tag, plus `verifyDenial` for NSEC / NSEC3 (RFC 5155) NXDOMAIN / NODATA proofs with iteration caps + Opt-Out handling, plus `verifyChain` to validate a full root→TLD→zone delegation chain against the pinned IANA root anchors) so a resolver client can verify both positive and negative answers instead of trusting the upstream AD bit; DANE / TLSA certificate matching (RFC 6698/7671 — `b.network.dns.dane.matchCertificate`) to pin a service's key through DNSSEC instead of a public CA; TSIG transaction signatures (RFC 8945 — `b.network.dns.tsig.sign` / `verify`) for shared-key HMAC authentication of zone transfers, dynamic updates, and query/response pairs, with constant-time MAC compare + fudge-window check (verified against dnspython); outbound HTTP proxy (`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`); runtime DPI trust-store CA additions; application-level heartbeats; TCP socket defaults
 - **Error pages** — operator-rendered, no app-frame leakage (`b.errorPage`)
 ### Defensive parsers

package/index.js

@@ -135,6 +135,7 @@ var lazyRequire = require("./lib/lazy-require");
 var frameworkError = require("./lib/framework-error");
 var nistCrosswalk = require("./lib/nist-crosswalk");
 var httpClient = require("./lib/http-client");
+var localHttp = require("./lib/local-http");
 // Attach the encrypted-payload helper from the api-encrypt middleware so
 // `b.httpClient.encrypted({ pubkey, baseUrl })` is available alongside
 // the bare `b.httpClient.request(...)`. The api-encrypt module owns the
@@ -433,6 +434,7 @@ var base32 = require("./lib/base32");
 var uriTemplate = require("./lib/uri-template");
 var jwk = require("./lib/jwk");
 var standardWebhooks = require("./lib/standard-webhooks");
+var webhookHmac = require("./lib/webhook-hmac");
 var lro = require("./lib/lro");
 var jsonApi = require("./lib/jsonapi");
 var hal = require("./lib/hal");
@@ -461,6 +463,7 @@ module.exports = {
   uriTemplate:      uriTemplate,
   jwk:              jwk,
   standardWebhooks: standardWebhooks,
+  webhookHmac:      webhookHmac,
   lro:              lro,
   jsonApi:          jsonApi,
   hal:              hal,
@@ -546,6 +549,7 @@ module.exports = {
   lazyRequire:      lazyRequire,
   frameworkError:   frameworkError,
   httpClient:       httpClient,
+  localHttp:        localHttp,
   websocket:        websocket,
   sse:              sse,
   mcp:              mcp,

package/lib/auth/ciba.js

@@ -194,7 +194,10 @@ function create(opts) {
 
   function _basicAuthHeader() {
     if (clientAuth !== "secret") return null;
-    var pair = opts.clientId + ":" + opts.clientSecret;
+    // RFC 6749 §2.3.1: percent-encode the id + secret before the ':' join and
+    // base64, so a ':' / '+' / '%' / space / non-ASCII byte in the secret can't
+    // corrupt the username:password split.
+    var pair = encodeURIComponent(opts.clientId) + ":" + encodeURIComponent(opts.clientSecret);
     return "Basic " + Buffer.from(pair, "utf8").toString("base64");
   }
 

package/lib/auth/oauth.js

@@ -1129,10 +1129,11 @@ function create(opts) {
   if (!clientId) {
     throw new OAuthError("auth-oauth/no-client-id", "create: opts.clientId is required");
   }
-  if (!redirectUri) {
-    throw new OAuthError("auth-oauth/no-redirect-uri", "create: opts.redirectUri is required");
-  }
-  _validateUrl(redirectUri, allowHttp, "redirectUri");
+  // redirectUri is required only for the redirect-based authorization-code / OIDC
+  // flows; a machine-to-machine (client_credentials) client needs none. Validate
+  // it when present; authorizationUrl / exchangeCode enforce its presence at call
+  // time so a mis-configured redirect-flow client still fails loudly.
+  if (redirectUri) _validateUrl(redirectUri, allowHttp, "redirectUri");
 
   // Resolve preset → effective config.
   var preset = null;
@@ -1163,6 +1164,15 @@ function create(opts) {
                 : (preset && preset.defaultScope ? preset.defaultScope.slice() : ["openid"]);
   if (!responseMode && preset && preset.responseMode) responseMode = preset.responseMode;
 
+  // RFC 6749 §2.3.1 client authentication at the token endpoint. Default to
+  // client_secret_post (credentials in the request body); client_secret_basic
+  // (HTTP Basic Authorization header) is required by some authorization servers.
+  var tokenEndpointAuthMethod = opts.tokenEndpointAuthMethod || "client_secret_post";
+  if (tokenEndpointAuthMethod !== "client_secret_post" && tokenEndpointAuthMethod !== "client_secret_basic") {
+    throw new OAuthError("auth-oauth/bad-auth-method",
+      "create: tokenEndpointAuthMethod must be 'client_secret_post' or 'client_secret_basic'");
+  }
+
   // Endpoints — either from preset (explicit), discovery, or operator opts.
   var staticEndpoints = {
     authorizationEndpoint: opts.authorizationEndpoint || (preset && preset.authorizationEndpoint) || null,
@@ -1215,7 +1225,7 @@ function create(opts) {
     }, fetchOpts);
     if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
     if (allowInternal !== null) req.allowInternal = allowInternal;
-    Object.assign(req, httpClientOpts);
+    _mergeHttpClientOpts(req);
     var res = await hc.request(req);
     if (res.statusCode < 200 || res.statusCode >= 300) {
       /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
@@ -1332,6 +1342,10 @@ function create(opts) {
 
   async function authorizationUrl(uopts) {
     uopts = uopts || {};
+    if (!redirectUri) {
+      throw new OAuthError("auth-oauth/no-redirect-uri",
+        "authorizationUrl: a redirectUri must be configured at create() for the authorization-code flow");
+    }
     var endpoint = await _resolveEndpoint("authorizationEndpoint");
     // RFC 9700 §4.13 — refuse an OP whose discovery metadata advertises
     // code_challenge_methods_supported without S256 (PKCE downgrade /
@@ -1401,6 +1415,10 @@ function create(opts) {
 
   async function exchangeCode(eopts) {
     eopts = eopts || {};
+    if (!redirectUri) {
+      throw new OAuthError("auth-oauth/no-redirect-uri",
+        "exchangeCode: a redirectUri must be configured at create() for the authorization-code flow");
+    }
     if (!eopts.code) {
       throw new OAuthError("auth-oauth/no-code", "exchangeCode: opts.code is required");
     }
@@ -1768,6 +1786,9 @@ function create(opts) {
     if (ropts.type) body.set("token_type_hint", ropts.type);
     body.set("client_id", clientId);
     if (clientSecret) body.set("client_secret", clientSecret);
+    // Revocation endpoint (RFC 7009) — authenticate with client_secret_post (the
+    // credentials stay in the body, universally accepted). tokenEndpointAuthMethod
+    // is scoped to the token endpoint; this endpoint may advertise a different one.
     var hc = httpClient;
     var req = {
       url:     endpoint,
@@ -1777,7 +1798,7 @@ function create(opts) {
     };
     if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
     if (allowInternal !== null) req.allowInternal = allowInternal;
-    Object.assign(req, httpClientOpts);
+    _mergeHttpClientOpts(req);
     var res = await hc.request(req);
     // RFC 7009: 200 even if the token was already revoked / unknown.
     if (res.statusCode < 200 || res.statusCode >= 300) {
@@ -1786,26 +1807,82 @@ function create(opts) {
     }
   }
 
-  async function _postForm(endpoint, body) {
+  // Merge the operator's httpClient options into a request WITHOUT letting an
+  // httpClient.headers config clobber the request's own headers — Content-Type,
+  // Accept, the client Basic Authorization header, Content-Length. The request's
+  // headers win; the operator's are a base default. Applies to every token /
+  // revocation / introspection / registration POST this module builds.
+  function _mergeHttpClientOpts(req) {
+    var ownHeaders = req.headers || {};
+    Object.assign(req, httpClientOpts);   // may set req.headers from the operator config (always an object)
+    req.headers = Object.assign({}, req.headers, ownHeaders);
+  }
+
+  // RFC 7231 §7.1.3 Retry-After → milliseconds. Accepts delta-seconds or an
+  // HTTP-date; clamps to [0, 1h]; returns 0 for an unparseable / past value.
+  function _parseRetryAfterMs(ra) {
+    var s = String(ra).trim();
+    if (/^\d+$/.test(s)) return Math.min(parseInt(s, 10), 3600) * C.TIME.seconds(1);
+    var when = Date.parse(s);
+    if (!isNaN(when)) { var d = when - Date.now(); return d > 0 ? Math.min(d, C.TIME.hours(1)) : 0; }
+    return 0;
+  }
+
+  // RFC 6749 §2.3.1 client authentication, applied uniformly to EVERY token-
+  // endpoint POST (not one grant): callers set client_id + client_secret in the
+  // body (client_secret_post). When the client is configured for
+  // client_secret_basic, move the secret into an HTTP Basic Authorization header
+  // — id + secret each percent-encoded (encodeURIComponent) so a ':' / '+' / '%'
+  // / space / non-ASCII byte can't corrupt the username:password split — and out
+  // of the body; client_id stays in the body for authorization-server compat.
+  // Returns the extra header(s) to merge, or null. Mutates `body` (deletes the
+  // secret) only on the Basic path.
+  function _clientBasicAuthHeaders(body) {
+    if (clientSecret && tokenEndpointAuthMethod === "client_secret_basic") {
+      body.delete("client_secret");
+      return { Authorization: "Basic " + Buffer.from(
+        encodeURIComponent(clientId) + ":" + encodeURIComponent(clientSecret), "utf8").toString("base64") };
+    }
+    return null;
+  }
+
+  async function _postForm(endpoint, body, extraHeaders, applyTokenClientAuth) {
     var hc = httpClient;
+    // tokenEndpointAuthMethod (client_secret_basic) is the TOKEN endpoint's client
+    // authentication — apply it only to token-endpoint requests. Other endpoints
+    // (introspection / revocation / PAR / device-authorization) may advertise a
+    // different method, so they authenticate with client_secret_post (credentials
+    // in the body, universally accepted) unless the caller opts in.
+    var authHeaders = applyTokenClientAuth === false ? null : _clientBasicAuthHeaders(body);
     var req = {
       url:     endpoint,
       method:  "POST",
-      headers: {
+      headers: Object.assign({
         "Content-Type": "application/x-www-form-urlencoded",
         "Accept":       "application/json",
-      },
+      }, authHeaders || {}, extraHeaders || {}),
       body:    Buffer.from(body.toString(), "utf8"),
     };
     if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
     if (allowInternal !== null) req.allowInternal = allowInternal;
-    Object.assign(req, httpClientOpts);
+    _mergeHttpClientOpts(req);
+    // Force always-resolve so a non-2xx (e.g. a 429 rate-limit) is surfaced
+    // through this function's typed `auth-oauth/token-error-<status>` mapping
+    // below, NOT the httpClient's own rejection — which downstream callers (the
+    // clientCredentialsManager 429 backoff) cannot classify. This overrides any
+    // operator-supplied responseMode for token-endpoint POSTs.
+    req.responseMode = "always-resolve";
     var res = await hc.request(req);
     /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
     var text = res.body ? res.body.toString("utf8") : "";
     if (res.statusCode < 200 || res.statusCode >= 300) {
-      throw new OAuthError("auth-oauth/token-error-" + res.statusCode,
+      var tokenErr = new OAuthError("auth-oauth/token-error-" + res.statusCode,
         endpoint + " returned " + res.statusCode + ": " + text.slice(0, 500));
+      // Surface a 429 Retry-After (RFC 6585 §4) so the caller can honor the AS's
+      // stated wait instead of a fixed local backoff.
+      var ra = res.headers && (res.headers["retry-after"] !== undefined ? res.headers["retry-after"] : res.headers["Retry-After"]);
+      if (ra !== undefined && ra !== null) tokenErr.retryAfterMs = _parseRetryAfterMs(ra);
+      throw tokenErr;
     }
     var parsed;
     try { parsed = safeJson.parse(text, { maxBytes: OAUTH_MAX_RESPONSE_BYTES }); }
@@ -2210,6 +2287,10 @@ function create(opts) {
   // arrived exactly as the client signed them. Absent → plain-form PAR.
   async function pushAuthorizationRequest(uopts) {
     uopts = uopts || {};
+    if (!redirectUri) {
+      throw new OAuthError("auth-oauth/no-redirect-uri",
+        "pushAuthorizationRequest: a redirectUri must be configured at create() for the authorization-code flow");
+    }
     var endpoint;
     try { endpoint = await _resolveEndpoint("pushedAuthorizationRequestEndpoint"); }
     catch (_e) {
@@ -2307,7 +2388,7 @@ function create(opts) {
       for (var ap = 0; ap < ak.length; ap++) body.set(ak[ap], authzParams[ak[ap]]);
       if (clientSecret) body.set("client_secret", clientSecret);
     }
-    var rv = await _postForm(endpoint, body);
+    var rv = await _postForm(endpoint, body, null, false);   // PAR endpoint — client_secret_post
     if (!rv || typeof rv.request_uri !== "string" || rv.request_uri.length === 0) {
       throw new OAuthError("auth-oauth/par-bad-response",
         "pushAuthorizationRequest: IdP did not return a request_uri (got " +
@@ -2632,7 +2713,7 @@ function create(opts) {
     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);
+    var parsed = await _postForm(endpoint, body, null, false);   // introspection endpoint — client_secret_post
     // RFC 7662 §2.2 — `active` is the only required field; coerce
     // every other interpretation through it.
     if (typeof parsed.active !== "boolean") {
@@ -2718,7 +2799,7 @@ function create(opts) {
     };
     if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
     if (allowInternal !== null) req.allowInternal = allowInternal;
-    Object.assign(req, httpClientOpts);
+    _mergeHttpClientOpts(req);
     var res  = await hc.request(req);
     /* c8 ignore next -- httpClient always yields a Buffer body, so the empty-string arm is unreachable */
     var text = res.body ? res.body.toString("utf8") : "";
@@ -2841,7 +2922,7 @@ function create(opts) {
     }
     if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
     if (allowInternal !== null) req.allowInternal = allowInternal;
-    Object.assign(req, httpClientOpts);
+    _mergeHttpClientOpts(req);
     var res = await httpClient.request(req);
     if (method === "DELETE") {
       if (res.statusCode === 204 || res.statusCode === 200) return null;
@@ -2904,7 +2985,7 @@ function create(opts) {
     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);
+    var parsed = await _postForm(endpoint, body, null, false);   // device-authorization endpoint — client_secret_post
     if (typeof parsed.device_code !== "string" ||
         typeof parsed.user_code   !== "string" ||
         typeof parsed.verification_uri !== "string") {
@@ -2966,19 +3047,24 @@ function create(opts) {
       body.set("device_code", deviceCode);
       body.set("client_id",   clientId);
       if (clientSecret) body.set("client_secret", clientSecret);
+      // Same RFC 6749 §2.3.1 client authentication as every other token POST —
+      // client_secret_basic moves the secret to a Basic header (this loop builds
+      // its own request rather than routing through _postForm because it must
+      // read the pending/slow_down 400 bodies, so it composes the shared helper).
+      var authHeaders = _clientBasicAuthHeaders(body);
       var hc  = httpClient;
       var req = {
         url:     endpoint,
         method:  "POST",
-        headers: {
+        headers: Object.assign({
           "Content-Type": "application/x-www-form-urlencoded",
           "Accept":       "application/json",
-        },
+        }, authHeaders || {}),
         body:    Buffer.from(body.toString(), "utf8"),
       };
       if (allowHttp) req.allowedProtocols = safeUrl.ALLOW_HTTP_ALL;
       if (allowInternal !== null) req.allowInternal = allowInternal;
-      Object.assign(req, httpClientOpts);
+      _mergeHttpClientOpts(req);
       // RFC 8628 §3.5 / RFC 6749 §5.2 return the device-grant errors
       // (authorization_pending / slow_down and the terminal codes) as an
       // HTTP 400 whose body carries `error`. The loop below reads that body,
@@ -3190,9 +3276,217 @@ function create(opts) {
     };
   }
 
+  // Resolve the scope for a token request: an explicit override wins, else the
+  // client's configured scope; array or space-joined string → the wire string.
+  // Validate a caller-supplied scope opt is the documented string | string[]
+  // shape. A wrong type (e.g. 42 / {}) would otherwise silently omit scope and
+  // let the AS apply a possibly-broader default; a non-string array member would
+  // coerce through join(). Config-time throw.
+  function _validateScopeOpt(scopeOpt, label) {
+    if (scopeOpt === undefined || scopeOpt === null || typeof scopeOpt === "string") return;
+    if (Array.isArray(scopeOpt) && scopeOpt.every(function (x) { return typeof x === "string"; })) return;
+    throw new OAuthError("auth-oauth/bad-scope",
+      label + ": scope must be a string or an array of strings");
+  }
+
+  function _scopeParam(override) {
+    // Client-credentials only: the caller always supplies an explicit
+    // override (null when no scope), so there is deliberately no fallback to
+    // the create()-configured scope — M2M must not inherit the authorization
+    // -code default scope.
+    var s = override;
+    if (Array.isArray(s)) return s.length > 0 ? s.join(" ") : null;
+    if (typeof s === "string" && s.length > 0) return s;
+    return null;
+  }
+
+  /**
+   * @primitive b.auth.oauth.clientCredentials
+   * @signature b.auth.oauth.clientCredentials(opts?)
+   * @since     0.18.8
+   * @status    stable
+   * @related   b.auth.oauth.clientCredentialsManager
+   *
+   * RFC 6749 §4.4 <code>client_credentials</code> grant — machine-to-machine
+   * authentication with no user present. POSTs
+   * <code>grant_type=client_credentials</code> to the token endpoint,
+   * authenticating with the client id/secret via <code>client_secret_post</code>
+   * (default) or <code>client_secret_basic</code>, and returns the access token.
+   * A machine-to-machine request sends NO scope unless you supply one — the
+   * client's authorization-code scope default is not applied. Per the RFC a
+   * refresh_token is NEVER issued for this grant — present the credentials again
+   * to renew (see <code>clientCredentialsManager</code> for a cached,
+   * auto-renewing wrapper). A client_credentials-only client needs no
+   * <code>redirectUri</code> at <code>create</code>.
+   *
+   * Resolves <code>{ accessToken, tokenType, expiresIn, expiresAt, scope }</code>
+   * where <code>expiresAt</code> is an epoch-ms deadline (or null when the AS
+   * omits <code>expires_in</code>).
+   *
+   * @opts
+   *   scope: string[] | string,   // scope for this token (default: none — a machine-to-machine request sends no scope)
+   *
+   * @example
+   *   var t = await oauth.clientCredentials();
+   *   await fetch(api, { headers: { Authorization: "Bearer " + t.accessToken } });
+   */
+  async function clientCredentials(ccopts) {
+    ccopts = validateOpts.requireObject(ccopts === undefined ? {} : ccopts,
+      "clientCredentials", OAuthError, "auth-oauth/bad-opts");
+    validateOpts(ccopts, ["scope"], "clientCredentials");
+    _validateScopeOpt(ccopts.scope, "clientCredentials");
+    if (!clientSecret) {
+      throw new OAuthError("auth-oauth/no-client-secret",
+        "clientCredentials: a clientSecret is required for the client_credentials grant");
+    }
+    var endpoint = await _resolveEndpoint("tokenEndpoint");
+    var body = new URLSearchParams();
+    body.set("grant_type", "client_credentials");
+    body.set("client_id", clientId);
+    body.set("client_secret", clientSecret);
+    // Machine-to-machine requests carry NO scope by default — the client's
+    // configured (authorization-code / OIDC) scope like "openid" is meaningless
+    // for client_credentials, so only an explicitly-supplied scope is sent. Client
+    // authentication (client_secret_post vs _basic) is applied uniformly in
+    // _postForm from the client's configured tokenEndpointAuthMethod.
+    var reqScope = _scopeParam(ccopts.scope === undefined ? null : ccopts.scope);
+    if (reqScope) body.set("scope", reqScope);
+    var raw = await _postForm(endpoint, body);
+    if (!raw || typeof raw.access_token !== "string" || raw.access_token.length === 0) {
+      throw new OAuthError("auth-oauth/no-access-token",
+        "clientCredentials: token endpoint response has no access_token");
+    }
+    var expiresIn = (typeof raw.expires_in === "number" && isFinite(raw.expires_in) && raw.expires_in > 0)
+                      ? Math.floor(raw.expires_in) : null;
+    return {
+      accessToken: raw.access_token,
+      tokenType:   typeof raw.token_type === "string" ? raw.token_type : "Bearer",
+      expiresIn:   expiresIn,
+      expiresAt:   expiresIn !== null ? Date.now() + C.TIME.seconds(expiresIn) : null,
+      scope:       typeof raw.scope === "string" ? raw.scope : reqScope,
+    };
+  }
+
+  /**
+   * @primitive b.auth.oauth.clientCredentialsManager
+   * @signature b.auth.oauth.clientCredentialsManager(opts?)
+   * @since     0.18.8
+   * @status    stable
+   * @related   b.auth.oauth.clientCredentials
+   *
+   * A memory-cached <code>client_credentials</code> token manager.
+   * <code>getToken()</code> returns a valid bearer access token — fetching one
+   * on first use and re-fetching <code>refreshSkewSec</code> before expiry (60s
+   * by default). Concurrent <code>getToken()</code> calls during a fetch share
+   * ONE in-flight request (no thundering herd). A 429 from the token endpoint
+   * opens a short backoff window during which the still-cached token is served
+   * rather than hammering the AS. State is per-manager and in-memory only —
+   * seal the long-lived <code>clientSecret</code> at rest yourself.
+   *
+   * @opts
+   *   scope:          string[] | string,  // override the client's scope
+   *   refreshSkewSec: number,             // re-fetch this many seconds before expiry (default: 60)
+   *   backoffSec:     number,             // 429 backoff window (default: 30)
+   *
+   * @example
+   *   var mgr = oauth.clientCredentialsManager();
+   *   var token = await mgr.getToken();   // cached + auto-renewed
+   */
+  function clientCredentialsManager(mopts) {
+    mopts = validateOpts.requireObject(mopts === undefined ? {} : mopts,
+      "clientCredentialsManager", OAuthError, "auth-oauth/bad-opts");
+    validateOpts(mopts, ["scope", "refreshSkewSec", "backoffSec"], "clientCredentialsManager");
+    _validateScopeOpt(mopts.scope, "clientCredentialsManager");
+    numericBounds.requirePositiveFiniteIntIfPresent(mopts.refreshSkewSec, "refreshSkewSec",
+      OAuthError, "auth-oauth/bad-refresh-skew");
+    numericBounds.requirePositiveFiniteIntIfPresent(mopts.backoffSec, "backoffSec",
+      OAuthError, "auth-oauth/bad-backoff");
+    var skewMs    = typeof mopts.refreshSkewSec === "number" ? C.TIME.seconds(mopts.refreshSkewSec) : C.TIME.minutes(1);
+    var backoffMs = typeof mopts.backoffSec === "number" ? C.TIME.seconds(mopts.backoffSec) : C.TIME.seconds(30);
+    var cached = null;        // { accessToken, expiresAt, lifetimeMs }
+    var inflight = null;      // shared Promise while a fetch is running
+    var backoffUntil = 0;     // epoch-ms; a transient-failure backoff is active while now < this
+
+    function _isTransientRefreshError(e) {
+      // A refresh failure is TRANSIENT (safe to ride out on the still-valid cache)
+      // ONLY for a KNOWN transient error — a 429 or 5xx from the token endpoint,
+      // or a transport / network failure (b.httpClient marks those permanent:false).
+      // Everything else propagates: a 4xx (invalid_client / invalid_scope), a
+      // malformed response, or a permanent config error like no-endpoint (all
+      // OAuthError, permanent:true) — masking those would hide the actionable
+      // error and repeat it. Default-to-permanent, allowlist transient.
+      /* c8 ignore next -- e is always a coded error from the refresh; the null guard is defensive */
+      if (!e) return false;
+      // e.code is always a non-empty string here (every refresh error is a
+      // coded OAuthError / HttpClientError); exec coerces a missing code to the
+      // literal "undefined", which never matches, so no "|| ''" guard is needed.
+      var m = /^auth-oauth\/token-error-(\d+)$/.exec(e.code);
+      if (m) { var s = parseInt(m[1], 10); return s === 429 || s >= 500; }
+      return e.permanent === false;
+    }
+
+    function _usable(now) {
+      // A token whose expiry the AS did not state (no expires_in) is NOT cached
+      // — re-fetch each call rather than serve a token that may already be dead.
+      if (!cached || cached.expiresAt === null || cached.expiresAt <= now) return false;
+      // Normally refresh skewMs before expiry. A token whose whole lifetime is
+      // <= skewMs can never satisfy that (it is born inside the skew window), so
+      // it uses a PROPORTIONAL margin (half its lifetime) — cached + reused, but
+      // still refreshed before it dies rather than served to the last millisecond.
+      var effectiveSkew = (cached.lifetimeMs !== null && cached.lifetimeMs <= skewMs)
+        ? cached.lifetimeMs / 2
+        : skewMs;
+      return cached.expiresAt - now > effectiveSkew;
+    }
+    function _servableDuringBackoff(now) {
+      // During a 429 backoff we may ride out on the STILL-VALID cached token, but
+      // never an already-expired one — serving a dead token is worse than
+      // surfacing the rate-limit error and letting the caller retry.
+      return cached && cached.expiresAt !== null && cached.expiresAt > now;
+    }
+    async function getToken() {
+      var now = Date.now();
+      if (_usable(now)) return cached.accessToken;
+      // Inside a 429 backoff window: serve the still-valid cached token, else
+      // fail fast WITHOUT a network call. No token endpoint request is made for
+      // the whole backoff window — re-hammering it is exactly what the backoff
+      // exists to prevent.
+      if (now < backoffUntil) {
+        if (_servableDuringBackoff(now)) return cached.accessToken;
+        throw new OAuthError("auth-oauth/backoff-active",
+          "clientCredentialsManager: token endpoint is in 429 backoff and no still-valid cached token is available");
+      }
+      if (inflight) return inflight;
+      inflight = clientCredentials({ scope: mopts.scope }).then(function (t) {
+        cached = { accessToken: t.accessToken, expiresAt: t.expiresAt,
+          lifetimeMs: t.expiresIn !== null ? C.TIME.seconds(t.expiresIn) : null };
+        backoffUntil = 0;
+        inflight = null;
+        return t.accessToken;
+      }, function (e) {
+        inflight = null;
+        if (_isTransientRefreshError(e)) {
+          // Transient failure (429 / 5xx / transport): open a backoff so repeated
+          // failures don't hammer the endpoint — honor a 429 Retry-After (RFC 6585
+          // §4), else the fixed backoff — and ride out on the still-valid cached
+          // token. A PERMANENT error skips both and propagates so it is detected.
+          var waitMs = (e.code === "auth-oauth/token-error-429" && typeof e.retryAfterMs === "number" && e.retryAfterMs > 0)
+            ? e.retryAfterMs : backoffMs;
+          backoffUntil = Date.now() + waitMs;
+          if (_servableDuringBackoff(Date.now())) return cached.accessToken;
+        }
+        throw e;
+      });
+      return inflight;
+    }
+    return { getToken: getToken };
+  }
+
   return {
     authorizationUrl:                authorizationUrl,
     exchangeCode:                    exchangeCode,
+    clientCredentials:               clientCredentials,
+    clientCredentialsManager:        clientCredentialsManager,
     refreshAccessToken:              refreshAccessToken,
     fetchUserInfo:                   fetchUserInfo,
     revokeToken:                     revokeToken,

package/lib/crypto-field.js

@@ -487,7 +487,7 @@ var DERIVED_HASH_BYTES = 32;
 //     (64 hex). The key is a vault-derived secret, NOT a static salt, so an
 //     attacker who recovers the salt alone can't correlate two low-entropy
 //     plaintexts; the sponge has no length-extension weakness.
-//     (b.crypto.hmacSha3 (HMAC-SHA3-512) was considered; SHAKE256(key||msg)
+//     (b.crypto.hmac (HMAC-SHA3-512) was considered; SHAKE256(key||msg)
 //     is chosen for the fixed-width keyed digest with the same MAC-grade
 //     guarantee.) FIPS 202; NIST SP 800-185; GDPR Art. 4(5)
 //     pseudonymisation; HIPAA 45 CFR 164.514(b).