@blamejs/core 0.8.52 → 0.8.57

package/lib/auth/passkey.js

@@ -121,20 +121,55 @@ async function verifyRegistration(opts) {
   _requireString(opts.expectedOrigin, "expectedOrigin");
   _requireString(opts.expectedRPID, "expectedRPID");
 
-  return await _vendor().verifyRegistrationResponse({
+  var rv = await _vendor().verifyRegistrationResponse({
     response:           opts.response,
     expectedChallenge:  opts.expectedChallenge,
     expectedOrigin:     opts.expectedOrigin,
     expectedRPID:       opts.expectedRPID,
     requireUserVerification: opts.requireUserVerification !== false,
   });
+  // WebAuthn L3 §6.1.3 — surface authenticator-data BE/BS flags as
+  // named fields. backupEligible (BE) signals the credential CAN be
+  // backed up to a cloud account; backupState (BS) signals it IS
+  // currently backed up. Operators key trust decisions on these
+  // (single-device passkey → require step-up; multi-device synced
+  // passkey → strong signal). The vendor parses authData and exposes
+  // credentialDeviceType ("singleDevice" | "multiDevice") and
+  // credentialBackedUp (boolean) on registrationInfo; we map them to
+  // the spec's flag names and add them to the top-level result so
+  // callers don't have to dig through registrationInfo.
+  if (rv && rv.registrationInfo) {
+    rv.backupEligible = rv.registrationInfo.credentialDeviceType === "multiDevice";
+    rv.backupState    = rv.registrationInfo.credentialBackedUp === true;
+  } else {
+    rv = rv || {};
+    rv.backupEligible = false;
+    rv.backupState    = false;
+  }
+  return rv;
 }
 
 // ---- Authentication ----
 
+// startAuthentication accepts an optional `mediation` token that the
+// caller passes through verbatim to the browser as
+// `navigator.credentials.get({ publicKey, mediation })`. The descriptor
+// itself doesn't carry mediation — it's a separate argument on the
+// page — but startAuthentication echoes it onto the returned options
+// so the operator's transport (typically a JSON GET) carries it to
+// the page without losing the value. Allowed tokens per the W3C
+// Credential Management spec: "silent" / "optional" / "required" /
+// "conditional". "conditional" enables passkey autofill on
+// <input autocomplete="webauthn">.
+var ALLOWED_MEDIATION = { silent: 1, optional: 1, required: 1, conditional: 1 };
+
 async function startAuthentication(opts) {
   if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
   _requireString(opts.rpId, "rpId");
+  if (opts.mediation !== undefined && !ALLOWED_MEDIATION[opts.mediation]) {
+    throw new AuthError("auth-passkey/bad-mediation",
+      "mediation must be one of silent/optional/required/conditional");
+  }
 
   var options = await _vendor().generateAuthenticationOptions({
     rpID:               opts.rpId,
@@ -148,9 +183,169 @@ async function startAuthentication(opts) {
   } else {
     options.hints = opts.hints;
   }
+  if (opts.mediation !== undefined) {
+    options.mediation = opts.mediation;
+  }
+  return options;
+}
+
+// conditionalAuthOptions — convenience wrapper for the passkey-autofill
+// flow (mediation: "conditional"). Browsers require an empty
+// allowCredentials list, presence-only userVerification (so the
+// autofill chip can surface without forcing biometric), and a present
+// challenge. Returns an object shaped for
+// `navigator.credentials.get({ publicKey: <opts>, mediation: "conditional" })`.
+async function conditionalAuthOptions(opts) {
+  if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
+  _requireString(opts.rpId, "rpId");
+
+  var options = await _vendor().generateAuthenticationOptions({
+    rpID:               opts.rpId,
+    // For conditional UI the spec mandates an empty allowCredentials
+    // list — discoverable credentials only. Supplying a list here
+    // suppresses the autofill chip in current browsers.
+    allowCredentials:   [],
+    userVerification:   opts.userVerification || "preferred",
+    timeout:            opts.timeout,
+    extensions:         opts.extensions,
+  });
+  options.mediation = "conditional";
+  if (!opts.hints) {
+    options.hints = ["client-device", "hybrid"];
+  } else {
+    options.hints = opts.hints;
+  }
   return options;
 }
 
+// ---- WebAuthn L3 extension helpers (PRF / largeBlob / credBlob) ----
+//
+// Pre-compute the spec-correct shape so callers don't have to remember
+// (a) what the field is called this year, (b) which inputs travel as
+// base64url vs Uint8Array, (c) which support the {support:"required"}
+// contract. Validation tier: throw at config-time. Misuse here is a
+// coding bug, not a request-shape thing.
+
+function _b64urlExtInput(value, name) {
+  // Accept a base64url string OR a Buffer / Uint8Array. Normalize the
+  // wire shape to base64url (the JSON descriptor ships base64url; the
+  // browser turns it into an ArrayBuffer before passing to the
+  // authenticator).
+  if (typeof value === "string") {
+    if (value.length === 0 || !safeBuffer.BASE64URL_RE.test(value)) {
+      throw new AuthError("auth-passkey/bad-extension-input",
+        name + " must be base64url (no padding) when string");
+    }
+    return value;
+  }
+  if (Buffer.isBuffer(value)) {
+    return value.toString("base64url");
+  }
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value).toString("base64url");
+  }
+  throw new AuthError("auth-passkey/bad-extension-input",
+    name + " must be base64url string, Buffer, or Uint8Array");
+}
+
+// PRF (Pseudo-Random Function) extension — WebAuthn L3 §10.1.2.
+// Authenticator-bound HKDF source. eval inputs are 32-byte salts; the
+// authenticator returns deterministic 32-byte outputs the operator
+// uses as a key-encryption key (vault unlock, file-encryption seed).
+// Shape: `{ prf: { eval: { first, second? } } }` per extension-id "prf".
+function _prfExt(args) {
+  if (!args || !args.eval) {
+    throw new AuthError("auth-passkey/missing-eval",
+      "extensions.prf({ eval: { first, second? } }) is required");
+  }
+  if (args.eval.first === undefined || args.eval.first === null) {
+    throw new AuthError("auth-passkey/missing-prf-first",
+      "extensions.prf eval.first is required");
+  }
+  var out = { prf: { eval: { first: _b64urlExtInput(args.eval.first, "eval.first") } } };
+  if (args.eval.second !== undefined && args.eval.second !== null) {
+    out.prf.eval.second = _b64urlExtInput(args.eval.second, "eval.second");
+  }
+  return out;
+}
+
+// largeBlob extension — WebAuthn L3 §10.3.
+// Per-credential opaque blob storage. At registration the operator
+// asks for support: "preferred" | "required". At auth time the
+// operator asks to read OR write, never both in the same assertion.
+function _largeBlobExt(args) {
+  if (!args) {
+    throw new AuthError("auth-passkey/missing-largeblob",
+      "extensions.largeBlob({ support? | read? | write? }) is required");
+  }
+  var out = { largeBlob: {} };
+  var SUPPORT = { preferred: 1, required: 1 };
+  var modes = 0;
+  if (args.support !== undefined) {
+    if (!SUPPORT[args.support]) {
+      throw new AuthError("auth-passkey/bad-largeblob-support",
+        "extensions.largeBlob support must be 'preferred' or 'required'");
+    }
+    out.largeBlob.support = args.support;
+    modes++;
+  }
+  if (args.read === true) {
+    out.largeBlob.read = true;
+    modes++;
+  } else if (args.read !== undefined && args.read !== false) {
+    throw new AuthError("auth-passkey/bad-largeblob-read",
+      "extensions.largeBlob read must be a boolean");
+  }
+  if (args.write !== undefined && args.write !== null) {
+    if (!Buffer.isBuffer(args.write) && !(args.write instanceof Uint8Array)) {
+      throw new AuthError("auth-passkey/bad-largeblob-write",
+        "extensions.largeBlob write must be a Uint8Array / Buffer");
+    }
+    out.largeBlob.write = Buffer.from(args.write).toString("base64url");
+    modes++;
+  }
+  if (modes === 0) {
+    throw new AuthError("auth-passkey/empty-largeblob",
+      "extensions.largeBlob({}) needs support, read, or write");
+  }
+  if (args.read === true && args.write !== undefined && args.write !== null) {
+    throw new AuthError("auth-passkey/conflicting-largeblob",
+      "extensions.largeBlob — read and write are mutually exclusive");
+  }
+  return out;
+}
+
+// credBlob extension — WebAuthn L3 §10.5.
+// Server-supplied opaque blob (≤32 bytes per CTAP2.1) bound to the
+// credential at registration. Returned in subsequent assertions.
+// Shape: `{ credBlob: <base64url> }`.
+function _credBlobExt(args) {
+  if (!args || args.blob === undefined || args.blob === null) {
+    throw new AuthError("auth-passkey/missing-credblob",
+      "extensions.credBlob({ blob }) is required");
+  }
+  var buf;
+  if (Buffer.isBuffer(args.blob)) {
+    buf = args.blob;
+  } else if (args.blob instanceof Uint8Array) {
+    buf = Buffer.from(args.blob);
+  } else {
+    throw new AuthError("auth-passkey/bad-credblob",
+      "extensions.credBlob blob must be a Uint8Array / Buffer");
+  }
+  if (buf.length === 0 || buf.length > 32) {                                       // allow:raw-byte-literal — CTAP2.1 §11.1 credBlob max
+    throw new AuthError("auth-passkey/credblob-bad-length",
+      "extensions.credBlob blob must be 1-32 bytes (CTAP2.1 §11.1)");
+  }
+  return { credBlob: buf.toString("base64url") };
+}
+
+var extensions = {
+  prf:       _prfExt,
+  largeBlob: _largeBlobExt,
+  credBlob:  _credBlobExt,
+};
+
 async function verifyAuthentication(opts) {
   if (!opts) throw new AuthError("auth-passkey/missing-opts", "opts is required");
   if (!opts.response) {
@@ -164,7 +359,7 @@ async function verifyAuthentication(opts) {
       "opts.credential { id, publicKey, counter? } is required");
   }
 
-  return await _vendor().verifyAuthenticationResponse({
+  var rv = await _vendor().verifyAuthenticationResponse({
     response:           opts.response,
     expectedChallenge:  opts.expectedChallenge,
     expectedOrigin:     opts.expectedOrigin,
@@ -177,6 +372,21 @@ async function verifyAuthentication(opts) {
     },
     requireUserVerification: opts.requireUserVerification !== false,
   });
+  // WebAuthn L3 §6.1.3 — same BE/BS surfacing as verifyRegistration.
+  // Authentication assertions also carry the BE/BS bits in authData; a
+  // credential that registered as single-device but later asserts as
+  // multi-device (or vice versa) is a backup-state-changed signal worth
+  // auditing at the operator level. We expose the current values so the
+  // caller can compare against what they persisted at registration.
+  if (rv && rv.authenticationInfo) {
+    rv.backupEligible = rv.authenticationInfo.credentialDeviceType === "multiDevice";
+    rv.backupState    = rv.authenticationInfo.credentialBackedUp === true;
+  } else {
+    rv = rv || {};
+    rv.backupEligible = false;
+    rv.backupState    = false;
+  }
+  return rv;
 }
 
 // ---- WebAuthn Signal API (W3C draft, 2024) ----
@@ -265,6 +475,8 @@ module.exports = {
   verifyRegistration:           verifyRegistration,
   startAuthentication:          startAuthentication,
   verifyAuthentication:         verifyAuthentication,
+  conditionalAuthOptions:       conditionalAuthOptions,
+  extensions:                   extensions,
   signalUnknownCredential:      signalUnknownCredential,
   signalAllAcceptedCredentials: signalAllAcceptedCredentials,
   signalCurrentUserDetails:     signalCurrentUserDetails,

package/lib/auth-bot-challenge.js

@@ -136,7 +136,7 @@ function _defaultKeyExtractor(req) {
  * @signature b.authBotChallenge.create(opts)
  * @since     0.8.48
  * @status    stable
- * @related   b.middleware.botGuard, b.auth.lockout, b.auth.atoKillSwitch
+ * @related   b.middleware.botGuard
  *
  * Build an adaptive bot-challenge gate. Returns
  * `{ middleware, recordFailure, recordSuccess, check, reset }`.

package/lib/credential-hash.js

@@ -173,7 +173,7 @@ function _decodeEnvelope(env) {
  * @since      0.2.28
  * @status     stable
  * @compliance pci-dss, soc2, hipaa
- * @related    b.credentialHash.verify, b.credentialHash.needsRehash, b.auth.password.hash
+ * @related    b.credentialHash.verify, b.credentialHash.needsRehash
  *
  * Hash a credential secret into a base64 envelope ready for storage in
  * a `credentialHash` column. Default algorithm is SHAKE256 with a
@@ -345,7 +345,7 @@ function inspect(envelope) {
  * @signature  b.credentialHash.needsRehash(envelope, opts?)
  * @since      0.2.28
  * @status     stable
- * @related    b.credentialHash.hash, b.credentialHash.verify, b.auth.password.needsRehash
+ * @related    b.credentialHash.hash, b.credentialHash.verify
  *
  * Returns `true` when the stored envelope was produced under an
  * algorithm or parameter set that no longer matches the framework

package/lib/framework-error.js

@@ -378,6 +378,19 @@ var SmtpPolicyError       = defineClass("SmtpPolicyError",       { alwaysPermane
 // record shape, fetch failures, missing keys, alignment issues.
 // Permanent — DNS-config / message-shape errors, not transient.
 var MailAuthError         = defineClass("MailAuthError",         { alwaysPermanent: true });
+// MailArfError covers RFC 5965 Abuse Reporting Format ingest failures:
+// missing required Feedback-Type / User-Agent fields, malformed
+// multipart/report, message/feedback-report MIME-type mismatch, parse
+// errors. Permanent — the report shape is operator-supplied input.
+var MailArfError          = defineClass("MailArfError",          { alwaysPermanent: true });
+// MailBimiError covers RFC 9091 BIMI VMC / CMC chain validation
+// + Tiny-PS SVG profile violations: VMC fetch failures, X.509 chain
+// validation failures, subjectAltName URI / BIMI domain mismatch,
+// missing BIMI policy OID (1.3.6.1.5.5.7.3.31 mark verification),
+// Tiny-PS SVG profile violations (root, version, baseProfile, scripts,
+// external refs, viewBox, byte cap). Permanent — every case is a
+// brand / certificate / asset shape error.
+var MailBimiError         = defineClass("MailBimiError",         { alwaysPermanent: true });
 // SseError covers Server-Sent Events stream-shape violations: newline
 // or CR or NUL injection in event:/id:/data: fields (CVE-2026-33128
 // h3, CVE-2026-29085 Hono, CVE-2026-44217 sse-channel — newline in
@@ -553,10 +566,47 @@ var DaemonError           = defineClass("DaemonError",           { alwaysPermane
 // framework refuses to coerce. Operators wrap the call in their own
 // retry policy when polling against a flaky CDN.
 var SelfUpdateError       = defineClass("SelfUpdateError",       { alwaysPermanent: true });
+// MailUnsubscribeError — b.mail.unsubscribe (lib/mail-unsubscribe.js).
+// RFC 8058 / RFC 2369 / RFC 2919 List-* header builder violations:
+// non-https URL in url/help/archive, non-mailto in mailto/owner,
+// invalid list-id shape per RFC 2919 §3, control bytes / over-length
+// header values. alwaysPermanent — every case is operator-misconfig
+// at config-time the framework refuses to coerce.
+var MailUnsubscribeError  = defineClass("MailUnsubscribeError",  { alwaysPermanent: true });
+// FidoMds3Error — b.auth.fidoMds3 (lib/auth/fido-mds3.js). FIDO MDS3
+// metadata BLOB verification + AAGUID lookup violations: BLOB fetch
+// failure (non-2xx, oversize, network), JWS shape mismatch, certificate
+// chain validation failure against the FIDO Alliance MDS3 root,
+// signature verification failure, payload schema violation
+// (missing entries / nextUpdate / no), nextUpdate parse failure,
+// AAGUID lookup against an authenticator carrying a REVOKED /
+// USER_KEY_PHYSICAL_COMPROMISE / USER_KEY_REMOTE_COMPROMISE status
+// report. alwaysPermanent — every case is configuration / network /
+// signing-shape errors that retry alone won't recover.
+var FidoMds3Error         = defineClass("FidoMds3Error",         { alwaysPermanent: true });
+// PublicSuffixError — b.publicSuffix (lib/public-suffix.js). Bad
+// domain input at lookup time (non-string, empty, overlong, control-
+// byte-bearing, IDN-normalization failure) and missing-vendored-data
+// at module-init are both alwaysPermanent — every case is operator-
+// shaped (caller passed garbage) or packaging-shaped (vendored .dat
+// missing). Codes: `public-suffix/invalid-domain`,
+// `public-suffix/not-loaded`.
+var PublicSuffixError     = defineClass("PublicSuffixError",     { alwaysPermanent: true });
+// MailMdnError — b.mailMdn (lib/mail-mdn.js). RFC 3798 / RFC 8098
+// Message Disposition Notification builder + parser violations: bad
+// opts at build/parse, malformed multipart/report shape, missing
+// required fields (Original-Recipient / Final-Recipient / Disposition),
+// disposition / action-mode / sending-mode token allowlist drift,
+// auto-generation refusal when the inbound message demanded user
+// confirmation (RFC 3798 §2.1) and the operator did not opt in.
+// alwaysPermanent — every case is operator-shape or message-shape
+// errors that retry will not recover.
+var MailMdnError          = defineClass("MailMdnError",          { alwaysPermanent: true });
 
 module.exports = {
   FrameworkError:         FrameworkError,
   defineClass:            defineClass,
+  MailUnsubscribeError:   MailUnsubscribeError,
   ObjectStoreError:       ObjectStoreError,
   LogStreamError:         LogStreamError,
   QueueError:             QueueError,
@@ -613,6 +663,8 @@ module.exports = {
   ComplianceError:        ComplianceError,
   SmtpPolicyError:        SmtpPolicyError,
   MailAuthError:          MailAuthError,
+  MailArfError:           MailArfError,
+  MailBimiError:          MailBimiError,
   SseError:               SseError,
   McpError:               McpError,
   AiInputError:           AiInputError,
@@ -641,4 +693,7 @@ module.exports = {
   ArgParserError:         ArgParserError,
   DaemonError:            DaemonError,
   SelfUpdateError:        SelfUpdateError,
+  FidoMds3Error:          FidoMds3Error,
+  PublicSuffixError:      PublicSuffixError,
+  MailMdnError:           MailMdnError,
 };

package/lib/guard-cidr.js

@@ -48,6 +48,7 @@ var lazyRequire = require("./lazy-require");
 var gateContract = require("./gate-contract");
 var C = require("./constants");
 var numericBounds = require("./numeric-bounds");
+var safeBuffer = require("./safe-buffer");
 var { GuardCidrError } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
@@ -202,7 +203,7 @@ function _parseIpv6(s) {
     var out = [];
     for (var i = 0; i < parts.length; i += 1) {
       var p = parts[i];
-      if (!/^[0-9a-fA-F]{1,4}$/.test(p)) return null;
+      if (!safeBuffer.IPV6_HEXTET_RE.test(p)) return null;
       out.push(p.toLowerCase());
     }
     return out;

package/lib/guard-jwt.js

@@ -437,7 +437,7 @@ function _detectIssues(input, opts) {
  * @since      0.7.49
  * @status     stable
  * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardJwt.sanitize, b.guardJwt.gate, b.auth.jwt.verifyExternal
+ * @related    b.guardJwt.sanitize, b.guardJwt.gate
  *
  * Apply the full guard-jwt threat catalog to a JWT compact-
  * serialization string. Returns `{ ok, issues, refusal? }` per
@@ -697,7 +697,7 @@ var loadRulePack = _jwtRulePacks.load;
  * @since      0.7.49
  * @status     stable
  * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardJwt.validate, b.auth.jwt.verifyExternal
+ * @related    b.guardJwt.validate
  *
  * Throw on any `kid` value that contains path-traversal indicators
  * (`..`, `/`, `\`, percent-encoded variants) or non-printable

package/lib/guard-oauth.js

@@ -349,7 +349,7 @@ function _detectIssues(flow, opts) {
  * @since      0.7.49
  * @status     stable
  * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardOauth.sanitize, b.guardOauth.gate, b.auth.oauth
+ * @related    b.guardOauth.sanitize, b.guardOauth.gate
  *
  * Apply the full guard-oauth threat catalog to a flow bundle.
  * Returns `{ ok, issues, refusal? }` per
@@ -461,7 +461,7 @@ function sanitize(input, opts) {
  * @since      0.7.49
  * @status     stable
  * @compliance hipaa, pci-dss, gdpr, soc2
- * @related    b.guardOauth.validate, b.guardOauth.sanitize, b.auth.oauth
+ * @related    b.guardOauth.validate, b.guardOauth.sanitize
  *
  * Build a `gateContract.buildGuardGate`-shaped gate that pulls
  * `ctx.oauthFlow` (or `ctx.flow`) and dispatches to `validate`.