npm - @blamejs/core - Versions diffs - 0.7.18 → 0.7.19 - Mend

@blamejs/core 0.7.18 → 0.7.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (167) hide show

package/CHANGELOG.md +425 -423
package/README.md +150 -150
package/bin/blamejs.js +0 -0
package/index.js +310 -308
package/lib/api-key.js +660 -660
package/lib/api-snapshot.js +338 -338
package/lib/app-shutdown.js +385 -385
package/lib/app.js +365 -365
package/lib/archive.js +250 -250
package/lib/atomic-file.js +544 -544
package/lib/audit-chain.js +177 -177
package/lib/audit-sign.js +344 -344
package/lib/audit-tools.js +677 -677
package/lib/audit.js +766 -766
package/lib/auth/jwt-external.js +365 -0
package/lib/auth/jwt.js +337 -311
package/lib/auth/lockout.js +436 -436
package/lib/auth/oauth.js +721 -721
package/lib/auth/passkey.js +181 -181
package/lib/auth/password.js +628 -594
package/lib/backup/bundle.js +217 -217
package/lib/backup/crypto.js +176 -176
package/lib/backup/index.js +515 -515
package/lib/backup/manifest.js +282 -282
package/lib/break-glass.js +1338 -1338
package/lib/bundler.js +441 -441
package/lib/cache-redis.js +256 -256
package/lib/cache.js +1206 -1206
package/lib/canonical-json.js +115 -115
package/lib/chain-writer.js +234 -234
package/lib/cli-helpers.js +206 -206
package/lib/cli.js +2334 -2334
package/lib/cluster-provider-db.js +317 -317
package/lib/cluster-storage.js +226 -226
package/lib/cluster.js +703 -703
package/lib/config-drift.js +301 -301
package/lib/consent.js +222 -222
package/lib/constants.js +191 -191
package/lib/cookies.js +315 -315
package/lib/credential-hash.js +322 -322
package/lib/crypto.js +266 -266
package/lib/csv.js +275 -275
package/lib/db-declare-row-policy.js +267 -267
package/lib/db-declare-view.js +420 -420
package/lib/db-query.js +406 -406
package/lib/db-schema.js +319 -319
package/lib/db.js +1288 -1288
package/lib/deprecate.js +222 -222
package/lib/dev.js +335 -335
package/lib/dual-control.js +473 -473
package/lib/error-page.js +420 -420
package/lib/external-db-migrate.js +441 -441
package/lib/external-db.js +1061 -1061
package/lib/file-type.js +273 -273
package/lib/forms.js +422 -422
package/lib/framework-error.js +293 -293
package/lib/framework-schema.js +717 -717
package/lib/handlers.js +350 -350
package/lib/http-client-cookie-jar.js +508 -508
package/lib/http-client.js +1195 -1195
package/lib/i18n.js +878 -878
package/lib/jobs.js +185 -185
package/lib/log-stream-cloudwatch.js +369 -369
package/lib/log-stream-local.js +146 -146
package/lib/log-stream-otlp-grpc.js +410 -410
package/lib/log-stream-otlp.js +286 -286
package/lib/log-stream-syslog.js +302 -302
package/lib/log-stream-webhook.js +199 -199
package/lib/log-stream.js +330 -330
package/lib/log.js +500 -500
package/lib/mail-bounce.js +528 -528
package/lib/mail-dkim.js +369 -369
package/lib/mail.js +981 -981
package/lib/metrics.js +683 -683
package/lib/middleware/api-encrypt.js +936 -936
package/lib/middleware/attach-user.js +157 -157
package/lib/middleware/bearer-auth.js +152 -0
package/lib/middleware/body-parser.js +1170 -1170
package/lib/middleware/bot-guard.js +178 -178
package/lib/middleware/compression.js +452 -452
package/lib/middleware/cors.js +314 -314
package/lib/middleware/csp-nonce.js +348 -348
package/lib/middleware/csrf-protect.js +316 -316
package/lib/middleware/db-role-for.js +264 -264
package/lib/middleware/health.js +392 -392
package/lib/middleware/index.js +82 -79
package/lib/middleware/rate-limit.js +358 -358
package/lib/middleware/request-id.js +61 -61
package/lib/middleware/request-log.js +168 -168
package/lib/middleware/require-auth.js +104 -104
package/lib/middleware/security-headers.js +116 -116
package/lib/middleware/sse.js +166 -166
package/lib/migrations.js +383 -383
package/lib/mtls-ca.js +518 -518
package/lib/mtls-engine-default.js +481 -481
package/lib/network-dns.js +632 -632
package/lib/network-heartbeat.js +290 -290
package/lib/network-nts.js +574 -574
package/lib/network-proxy.js +265 -265
package/lib/network-tls.js +328 -328
package/lib/network.js +233 -233
package/lib/notify.js +612 -612
package/lib/ntp-check.js +229 -229
package/lib/numeric-bounds.js +111 -111
package/lib/object-store/azure-blob-bucket-ops.js +349 -349
package/lib/object-store/azure-blob.js +488 -488
package/lib/object-store/gcs-bucket-ops.js +351 -351
package/lib/object-store/gcs.js +519 -519
package/lib/object-store/http-put.js +153 -153
package/lib/object-store/index.js +197 -197
package/lib/object-store/sigv4-bucket-ops.js +1092 -1092
package/lib/object-store/sigv4.js +903 -903
package/lib/observability.js +151 -151
package/lib/otel-export.js +269 -269
package/lib/pagination.js +464 -464
package/lib/parsers/index.js +80 -80
package/lib/parsers/safe-env.js +642 -642
package/lib/parsers/safe-ini.js +292 -292
package/lib/parsers/safe-toml.js +784 -784
package/lib/parsers/safe-xml.js +390 -390
package/lib/parsers/safe-yaml.js +1015 -1015
package/lib/permissions.js +708 -708
package/lib/pqc-agent.js +87 -87
package/lib/pqc-gate.js +279 -279
package/lib/protobuf-encoder.js +190 -190
package/lib/protocol-dispatcher.js +161 -161
package/lib/pubsub-redis.js +167 -167
package/lib/pubsub.js +429 -429
package/lib/queue-local.js +476 -476
package/lib/queue-redis.js +745 -745
package/lib/queue-sqs.js +319 -319
package/lib/queue.js +695 -695
package/lib/redis-client.js +519 -519
package/lib/request-helpers.js +340 -340
package/lib/restore-bundle.js +237 -237
package/lib/restore-rollback.js +259 -259
package/lib/restore.js +409 -409
package/lib/retry.js +376 -376
package/lib/router.js +748 -748
package/lib/safe-async.js +735 -735
package/lib/safe-buffer.js +237 -237
package/lib/safe-json.js +541 -541
package/lib/safe-schema.js +1266 -1266
package/lib/safe-url.js +159 -159
package/lib/scheduler.js +706 -706
package/lib/security-assert.js +373 -373
package/lib/seeders.js +618 -618
package/lib/session.js +535 -478
package/lib/slug.js +269 -269
package/lib/ssrf-guard.js +401 -401
package/lib/storage.js +471 -471
package/lib/subject.js +281 -281
package/lib/template.js +791 -791
package/lib/testing.js +798 -798
package/lib/time.js +310 -310
package/lib/totp.js +302 -302
package/lib/tracing.js +494 -494
package/lib/uuid.js +132 -132
package/lib/validate-opts.js +340 -340
package/lib/vault/index.js +308 -308
package/lib/vault/rotate.js +784 -784
package/lib/vault/wrap.js +296 -296
package/lib/vendor/noble-ciphers.cjs +9 -9
package/lib/webhook.js +595 -595
package/lib/websocket.js +1048 -1048
package/package.json +77 -77
package/sbom.cyclonedx.json +7 -7

package/lib/webhook.js CHANGED Viewed

@@ -1,595 +1,595 @@
-"use strict";
-/**
- * b.webhook — outbound webhook signing + inbound verification.
- *
- *   var signer = b.webhook.signer({
- *     algo:       "hmac-sha3-512",
- *     keys:       { v1: secretBytes },
- *     defaultKid: "v1",
- *   });
- *
- *   await signer.send({ url: "https://example.com/hook", body: jsonString });
- *   // POSTs with:
- *   //   Webhook-Signature: t=<unix-seconds>,id=<uuid>,v1=<sig-hex>
- *
- *   var verifier = b.webhook.verifier({
- *     algo:        "hmac-sha3-512",
- *     keys:        { v1: secret, v0: oldSecret },     // multi-key for rotation
- *     toleranceMs: b.constants.TIME.minutes(5),
- *     nonceStore:  b.nonceStore.create({ ... }),      // optional replay defense
- *   });
- *
- *   router.use(b.middleware.bodyParser({ keepRawBody: true }));   // REQUIRED
- *   router.post("/inbound-webhook", verifier.middleware(), function (req, res) {
- *     // req.webhook = { algo, kid, timestamp, id }
- *   });
- *
- * Algorithms:
- *   "hmac-sha3-512" — symmetric. keys: { kid → Buffer/string secret }
- *   "pqc-pem"       — asymmetric. keys map for signer:
- *                       { kid → { privateKey, publicKey } }   (PEM)
- *                     keys map for verifier:
- *                       { kid → publicKey }                   (PEM)
- *                     Algorithm (SLH-DSA-SHAKE-256f / ML-DSA-87) is
- *                     auto-detected by Node from the PEM. No classical
- *                     (Ed25519, RSA, ECDSA) signature scheme is exposed.
- *
- * Signed string (deterministic, prefix-bound to defend against algorithm-
- * substitution and key-substitution attacks):
- *
- *     <algo>.<kid>.<timestamp>.<id>.<body>
- *
- * Header format (single combined header, Stripe-shape):
- *
- *     Webhook-Signature: t=<unix-seconds>,id=<uuid>,<kid>=<sig-hex>
- *
- * `t` and `id` are reserved segment names; every other `<name>=<value>`
- * pair is treated as a kid → signature mapping. Multiple kid pairs are
- * accepted on the verifier side; the signer emits exactly one. Operators
- * rotating keys point the verifier at both old + new keys and migrate
- * signers progressively.
- *
- * Replay defense:
- *   - `id` is included in the signed string, so a captured signature
- *     cannot be reused with a fresh id.
- *   - Optional `nonceStore` records seen ids; second delivery with the
- *     same id rejects with REPLAY. The framework's b.nonceStore is the
- *     reference impl; operators plug in Redis/SQL by passing any object
- *     with `checkAndInsert(nonce, expireAt) → bool/Promise<bool>`.
- *
- * Validation policy:
- *
- *   - signer/verifier creation opts → throw at config time
- *   - signer.sign body type         → throw at call site
- *   - signer.send url shape         → throw at call site (via safeUrl)
- *   - verifier.verify input shape   → throw WebhookError at call site
- *   - nonceStore.checkAndInsert err → propagates (fail-closed)
- */
-var crypto = require("./crypto");
-var httpClient = require("./http-client");
-var safeBuffer = require("./safe-buffer");
-var safeUrl = require("./safe-url");
-var retry = require("./retry");
-var C = require("./constants");
-var lazyRequire = require("./lazy-require");
-var numericChecks = require("./numeric-checks");
-var requestHelpers = require("./request-helpers");
-var validateOpts = require("./validate-opts");
-var { WebhookError } = require("./framework-error");
-var observability = lazyRequire(function () { return require("./observability"); });
-function _emitEvent(n, v, l) { observability().safeEvent(n, v, l || {}); }
-var _err = WebhookError.factory;
-// ---- Constants ----
-var ALGOS = Object.freeze({
-  HMAC_SHA3_512: "hmac-sha3-512",
-  PQC_PEM:       "pqc-pem",
-});
-var HEADER = Object.freeze({
-  SIGNATURE: "Webhook-Signature",
-});
-var DEFAULTS = Object.freeze({
-  toleranceMs:     C.TIME.minutes(5),
-  clockSkewMs:     C.TIME.minutes(1),
-  signatureHeader: HEADER.SIGNATURE,
-  // Audit defaults: BOTH success and failure default ON. The webhook
-  // verify is the framework boundary where an inbound message gets
-  // accepted — that acceptance IS the audit-worthy event, not a
-  // precursor to one. "Inbound webhook id <X> verified from kid <Y>
-  // at time T" is the compliance trail. The send side mirrors:
-  // outbound delivery success/failure to a partner is also a
-  // standalone audit event. Operators with extreme volume opt out
-  // via auditSuccess: false; failures remain on regardless.
-  auditFailures:   true,
-  auditSuccess:    true,
-});
-// ---- Call-site validation helpers (throw on bad input) ----
-var _isPositiveInt  = numericChecks.isPositiveInt;
-var _isNonNegFinite = numericChecks.isFiniteNonNegative;
-function _hasOwn(obj, k) { return Object.prototype.hasOwnProperty.call(obj, k); }
-function _objectKeys(obj) { return Object.keys(obj); }
-function _validateAlgo(algo) {
-  if (algo !== ALGOS.HMAC_SHA3_512 && algo !== ALGOS.PQC_PEM) {
-    throw _err("BAD_OPT", "webhook: algo must be one of " +
-      JSON.stringify([ALGOS.HMAC_SHA3_512, ALGOS.PQC_PEM]) + ", got " + JSON.stringify(algo));
-  }
-}
-function _validateKeysShape(name, algo, keys, side) {
-  if (!keys || typeof keys !== "object" || Array.isArray(keys)) {
-    throw _err("BAD_OPT", name + ": keys must be a non-empty object map of kid → key, got " +
-      typeof keys);
-  }
-  var kids = _objectKeys(keys);
-  if (kids.length === 0) {
-    throw _err("BAD_OPT", name + ": keys must have at least one kid entry");
-  }
-  for (var i = 0; i < kids.length; i++) {
-    var kid = kids[i];
-    if (kid.length === 0 || /[,=\s]/.test(kid)) {
-      throw _err("BAD_OPT", name + ": kid must be non-empty and contain no comma/equals/whitespace, got " +
-        JSON.stringify(kid));
-    }
-    if (kid === "t" || kid === "id") {
-      throw _err("BAD_OPT", name + ": kid '" + kid + "' is reserved (collides with header field)");
-    }
-    var k = keys[kid];
-    if (algo === ALGOS.HMAC_SHA3_512) {
-      if (!Buffer.isBuffer(k) && typeof k !== "string") {
-        throw _err("BAD_OPT", name + ": HMAC key for kid '" + kid +
-          "' must be a Buffer or string, got " + typeof k);
-      }
-      if (k.length === 0) {
-        throw _err("BAD_OPT", name + ": HMAC key for kid '" + kid + "' must be non-empty");
-      }
-    } else if (algo === ALGOS.PQC_PEM) {
-      if (side === "signer") {
-        if (!k || typeof k !== "object" || Array.isArray(k) ||
-            (typeof k.privateKey !== "string" && !Buffer.isBuffer(k.privateKey)) ||
-            (typeof k.publicKey  !== "string" && !Buffer.isBuffer(k.publicKey))) {
-          throw _err("BAD_OPT", name + ": PQC signer key for kid '" + kid +
-            "' must be { privateKey, publicKey } as PEM strings/Buffers");
-        }
-      } else {
-        if (typeof k !== "string" && !Buffer.isBuffer(k)) {
-          throw _err("BAD_OPT", name + ": PQC verifier key for kid '" + kid +
-            "' must be a PEM string/Buffer (public key)");
-        }
-      }
-    }
-  }
-}
-function _validateBody(body) {
-  if (typeof body !== "string" && !Buffer.isBuffer(body)) {
-    throw _err("BAD_BODY", "webhook: body must be a string or Buffer, got " + typeof body);
-  }
-}
-// ---- Signed-string composition ----
-function _composeSignedString(algo, kid, timestamp, id, body) {
-  var prefix = algo + "." + kid + "." + timestamp + "." + id + ".";
-  if (Buffer.isBuffer(body)) {
-    return Buffer.concat([Buffer.from(prefix, "utf8"), body]);
-  }
-  return Buffer.from(prefix + body, "utf8");
-}
-// ---- Sign / verify primitives ----
-function _hmacSign(key, data) {
-  return crypto.hmacSha3(key, data);    // hex string
-}
-function _hmacVerify(key, data, expectedHex) {
-  if (!safeBuffer.isHex(expectedHex)) return false;
-  var actualHex = crypto.hmacSha3(key, data);
-  return crypto.timingSafeEqual(actualHex, expectedHex);
-}
-function _pqcSign(privateKeyPem, data) {
-  return crypto.sign(data, privateKeyPem).toString("hex");
-}
-function _pqcVerify(publicKeyPem, data, expectedHex) {
-  if (!safeBuffer.isHex(expectedHex) || (expectedHex.length % 2) !== 0) {
-    return false;
-  }
-  var sigBuf;
-  try { sigBuf = Buffer.from(expectedHex, "hex"); }
-  catch (_e) { return false; }
-  try { return crypto.verify(data, sigBuf, publicKeyPem); }
-  catch (_e) { return false; }
-}
-// ---- Header parsing ----
-//
-// Format:  t=<seconds>,id=<uuid>,<kid>=<hex>[,<kid>=<hex>]*
-// `t` and `id` are reserved segment names; everything else is treated as
-// a kid → signature pair. Whitespace tolerated around commas.
-function _parseSignatureHeader(headerValue) {
-  var segs = requestHelpers.parseListHeader(headerValue);
-  var t = null, id = null, sigs = {};
-  for (var i = 0; i < segs.length; i++) {
-    var seg = segs[i];
-    var eq = seg.indexOf("=");
-    if (eq <= 0) continue;            // skip malformed segments rather than failing whole header
-    var name = seg.slice(0, eq);
-    var value = seg.slice(eq + 1);
-    if (name === "t") t = value;
-    else if (name === "id") id = value;
-    else if (name.length > 0) sigs[name] = value;   // kid → sig hex
-  }
-  return { t: t, id: id, sigs: sigs };
-}
-// ---- Signer ----
-function _validateSignerOpts(opts) {
-  validateOpts.requireObject(opts, "webhook.signer", WebhookError);
-  _validateAlgo(opts.algo);
-  _validateKeysShape("webhook.signer", opts.algo, opts.keys, "signer");
-  var kids = _objectKeys(opts.keys);
-  if (opts.defaultKid !== undefined) {
-    if (!_hasOwn(opts.keys, opts.defaultKid)) {
-      throw _err("BAD_OPT", "webhook.signer: defaultKid '" + opts.defaultKid +
-        "' not present in keys (have: " + JSON.stringify(kids) + ")");
-    }
-  } else if (kids.length > 1) {
-    throw _err("BAD_OPT", "webhook.signer: defaultKid required when keys has " +
-      kids.length + " entries");
-  }
-  validateOpts.optionalNonEmptyString(opts.signatureHeader, "webhook.signer: signatureHeader", WebhookError);
-  validateOpts.optionalFunction(opts.idGenerator, "webhook.signer: idGenerator", WebhookError);
-  validateOpts.optionalFunction(opts.now, "webhook.signer: now", WebhookError);
-  validateOpts.auditShape(opts.audit, "webhook.signer", WebhookError);
-}
-function signer(opts) {
-  _validateSignerOpts(opts);
-  var algo = opts.algo;
-  var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
-  var keys = opts.keys;
-  var kids = _objectKeys(keys);
-  var defaultKid = opts.defaultKid || kids[0];
-  var sigHeader = cfg.signatureHeader;
-  var idGen = opts.idGenerator || function () { return crypto.generateToken(C.BYTES.bytes(16)); };
-  var nowFn = opts.now || function () { return Date.now(); };
-  var retryOpts = opts.retry || retry.DEFAULT_RETRY;
-  var httpOpts = opts.http || {};
-  var audit = opts.audit || null;
-  var auditFailures = cfg.auditFailures;
-  var auditSuccess  = cfg.auditSuccess;
-  var _auditEmit = validateOpts.makeAuditEmitter(audit);
-  function _signOne(body, kid) {
-    _validateBody(body);
-    var keyForKid = kids.indexOf(kid) === -1 ? null : keys[kid];
-    if (keyForKid == null) {
-      throw _err("BAD_OPT", "webhook.signer: unknown kid '" + kid + "'");
-    }
-    var timestamp = Math.floor(nowFn() / C.TIME.seconds(1));
-    var id = idGen();
-    if (typeof id !== "string" || id.length === 0 || /[,=\s]/.test(id)) {
-      throw _err("BAD_OPT", "webhook.signer: idGenerator must return a non-empty string with no comma/equals/whitespace, got " + JSON.stringify(id));
-    }
-    var signed = _composeSignedString(algo, kid, timestamp, id, body);
-    var sigHex;
-    if (algo === ALGOS.HMAC_SHA3_512) {
-      sigHex = _hmacSign(keyForKid, signed);
-    } else {
-      sigHex = _pqcSign(keyForKid.privateKey, signed);
-    }
-    return { kid: kid, timestamp: timestamp, id: id, signature: sigHex };
-  }
-  function sign(body, callOpts) {
-    var kid = (callOpts && callOpts.kid) || defaultKid;
-    var s = _signOne(body, kid);
-    var headerValue = "t=" + s.timestamp + ",id=" + s.id + "," + s.kid + "=" + s.signature;
-    var headers = {};
-    headers[sigHeader] = headerValue;
-    return {
-      headers:   headers,
-      timestamp: s.timestamp,
-      id:        s.id,
-      kid:       s.kid,
-      signature: s.signature,
-    };
-  }
-  function headers(body, callOpts) {
-    return sign(body, callOpts).headers;
-  }
-  async function send(input) {
-    if (!input || typeof input !== "object") {
-      throw _err("BAD_OPT", "webhook.signer.send: input must be { url, body, headers? }");
-    }
-    var url = input.url;
-    var body = input.body;
-    safeUrl.parse(url, {
-      allowedProtocols: httpOpts.allowedProtocols || safeUrl.ALLOW_HTTP_TLS,
-      errorClass:       WebhookError,
-    });
-    _validateBody(body);
-    var signed = sign(body, { kid: input.kid });
-    var mergedHeaders = Object.assign({}, input.headers || {}, signed.headers);
-    if (!mergedHeaders["Content-Type"] && !mergedHeaders["content-type"]) {
-      mergedHeaders["Content-Type"] = Buffer.isBuffer(body)
-        ? "application/octet-stream"
-        : "application/json";
-    }
-    var requestOpts = Object.assign({
-      method:           "POST",
-      url:              url,
-      headers:          mergedHeaders,
-      body:             body,
-      allowedProtocols: safeUrl.ALLOW_HTTP_TLS,
-      errorClass:       WebhookError,
-    }, httpOpts);
-    requestOpts.headers = mergedHeaders;
-    requestOpts.url = url;
-    requestOpts.body = body;
-    requestOpts.method = "POST";
-    var hostLabel = "";
-    try {
-      hostLabel = safeUrl.parse(url, {
-        allowedProtocols: httpOpts.allowedProtocols || safeUrl.ALLOW_HTTP_TLS,
-        errorClass:       WebhookError,
-      }).host;
-    } catch (_e) { hostLabel = ""; }
-    try {
-      var res = await retry.withRetry(function () {
-        return httpClient.request(requestOpts);
-      }, retryOpts);
-      var statusCode = (res && (res.statusCode || res.status)) || 0;
-      _emitEvent("webhook.send", 1, {
-        outcome: statusCode >= 200 && statusCode < 300 ? "success" : "failure",
-        status: statusCode,
-        host: hostLabel,
-      });
-      if (auditSuccess && statusCode >= 200 && statusCode < 300) {
-        _auditEmit("webhook.send", {
-          resource: { kind: "webhook", id: hostLabel },
-          outcome:  "success",
-          metadata: { status: statusCode },
-        });
-      }
-      if (auditFailures && (statusCode < 200 || statusCode >= 300)) {
-        _auditEmit("webhook.send", {
-          resource: { kind: "webhook", id: hostLabel },
-          outcome:  "failure",
-          reason:   "http-" + statusCode,
-        });
-      }
-      return res;
-    } catch (err) {
-      _emitEvent("webhook.send", 1, {
-        outcome: "failure", reason: "transport-error", host: hostLabel,
-      });
-      if (auditFailures) {
-        _auditEmit("webhook.send", {
-          resource: { kind: "webhook", id: hostLabel },
-          outcome:  "failure",
-          reason:   (err && err.code) || "transport-error",
-        });
-      }
-      throw err;
-    }
-  }
-  return {
-    sign:    sign,
-    headers: headers,
-    send:    send,
-  };
-}
-// ---- Verifier ----
-function _validateVerifierOpts(opts) {
-  validateOpts.requireObject(opts, "webhook.verifier", WebhookError);
-  _validateAlgo(opts.algo);
-  _validateKeysShape("webhook.verifier", opts.algo, opts.keys, "verifier");
-  validateOpts.optionalFiniteNonNegative(opts.toleranceMs, "webhook.verifier: toleranceMs", WebhookError);
-  validateOpts.optionalFiniteNonNegative(opts.clockSkewMs, "webhook.verifier: clockSkewMs", WebhookError);
-  validateOpts.optionalNonEmptyString(opts.signatureHeader, "webhook.verifier: signatureHeader", WebhookError);
-  validateOpts.optionalObjectWithMethod(opts.nonceStore, "checkAndInsert",
-    "webhook.verifier: nonceStore", WebhookError, "BAD_OPT",
-    "must implement checkAndInsert(nonce, expireAt)");
-  validateOpts.optionalFunction(opts.now, "webhook.verifier: now", WebhookError);
-  validateOpts.auditShape(opts.audit, "webhook.verifier", WebhookError);
-  validateOpts.optionalBoolean(opts.auditFailures, "webhook.verifier: auditFailures", WebhookError);
-  validateOpts.optionalBoolean(opts.auditSuccess, "webhook.verifier: auditSuccess", WebhookError);
-}
-function verifier(opts) {
-  _validateVerifierOpts(opts);
-  var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
-  var algo = opts.algo;
-  var keys = opts.keys;
-  var toleranceMs = cfg.toleranceMs;
-  var clockSkewMs = cfg.clockSkewMs;
-  var sigHeader = cfg.signatureHeader.toLowerCase();
-  var nonceStore = opts.nonceStore || null;
-  var nowFn = opts.now || function () { return Date.now(); };
-  var audit = opts.audit || null;
-  var auditFailures = cfg.auditFailures;
-  var auditSuccess  = cfg.auditSuccess;
-  function _auditEmit(outcome, reason, info, req) {
-    if (!audit) return;
-    if (outcome === "success" && !auditSuccess) return;
-    if (outcome === "failure" && !auditFailures) return;
-    try {
-      audit.safeEmit({
-        action:   "webhook.verify",
-        actor:    requestHelpers.extractActorContext(req),
-        resource: { kind: "webhook" },
-        outcome:  outcome,
-        reason:   reason || null,
-        metadata: info || null,
-      });
-    } catch (_e) { /* audit best-effort */ }
-  }
-  function _failure(code, message, reason, req) {
-    _emitEvent("webhook.verify", 1, { outcome: "failure", reason: reason || code });
-    _auditEmit("failure", reason || code, null, req);
-    return _err(code, message);
-  }
-  async function verify(input) {
-    if (!input || typeof input !== "object") {
-      throw _err("BAD_OPT", "webhook.verifier.verify: input must be { body, headers }");
-    }
-    var headers = input.headers;
-    if (!headers || typeof headers !== "object") {
-      throw _err("BAD_OPT", "webhook.verifier.verify: headers must be an object");
-    }
-    var body = input.body;
-    _validateBody(body);
-    var ctxReq = input.req || null;
-    // Headers may be node-style (lowercased keys) or operator-supplied
-    // (mixed case). Resolve case-insensitively.
-    var headerValue = null;
-    var headerKeys = Object.keys(headers);
-    for (var i = 0; i < headerKeys.length; i++) {
-      if (headerKeys[i].toLowerCase() === sigHeader) {
-        headerValue = headers[headerKeys[i]];
-        break;
-      }
-    }
-    if (typeof headerValue !== "string" || headerValue.length === 0) {
-      throw _failure("MISSING_HEADER",
-        "webhook: " + (opts.signatureHeader || HEADER.SIGNATURE) + " header missing",
-        "missing-header", ctxReq);
-    }
-    var parsed = _parseSignatureHeader(headerValue);
-    if (parsed.t === null && parsed.id === null && Object.keys(parsed.sigs).length === 0) {
-      throw _failure("BAD_HEADER_FORMAT", "webhook: signature header could not be parsed", "bad-header-format", ctxReq);
-    }
-    if (parsed.t === null) {
-      throw _failure("MISSING_TIMESTAMP", "webhook: t= field missing from signature header", "missing-timestamp", ctxReq);
-    }
-    var ts = Number(parsed.t);
-    if (!isFinite(ts) || ts < 0 || Math.floor(ts) !== ts) {
-      throw _failure("BAD_TIMESTAMP", "webhook: t= field is not a non-negative integer, got " + JSON.stringify(parsed.t), "bad-timestamp", ctxReq);
-    }
-    if (parsed.id === null || parsed.id.length === 0) {
-      throw _failure("MISSING_ID", "webhook: id= field missing from signature header", "missing-id", ctxReq);
-    }
-    var sigKids = Object.keys(parsed.sigs);
-    if (sigKids.length === 0) {
-      throw _failure("MISSING_SIGNATURE", "webhook: no v<kid>= segment found in signature header", "missing-signature", ctxReq);
-    }
-    // Timestamp window: signed in seconds, compare to ms clock.
-    var nowMs = nowFn();
-    var ageMs = nowMs - C.TIME.seconds(ts);
-    if (ageMs > toleranceMs) {
-      throw _failure("EXPIRED", "webhook: timestamp older than toleranceMs (age=" + ageMs + "ms)", "expired", ctxReq);
-    }
-    if (-ageMs > clockSkewMs) {
-      throw _failure("FUTURE", "webhook: timestamp in the future beyond clockSkewMs (skew=" + (-ageMs) + "ms)", "future", ctxReq);
-    }
-    // Find the first kid the verifier holds a key for.
-    var matchedKid = null;
-    for (var j = 0; j < sigKids.length; j++) {
-      if (_hasOwn(keys, sigKids[j])) { matchedKid = sigKids[j]; break; }
-    }
-    if (matchedKid === null) {
-      throw _failure("UNKNOWN_KID",
-        "webhook: no registered key matches signed kids " + JSON.stringify(sigKids),
-        "unknown-kid", ctxReq);
-    }
-    var signed = _composeSignedString(algo, matchedKid, ts, parsed.id, body);
-    var ok;
-    if (algo === ALGOS.HMAC_SHA3_512) {
-      ok = _hmacVerify(keys[matchedKid], signed, parsed.sigs[matchedKid]);
-    } else {
-      ok = _pqcVerify(keys[matchedKid], signed, parsed.sigs[matchedKid]);
-    }
-    if (!ok) {
-      throw _failure("BAD_SIGNATURE", "webhook: cryptographic verification failed", "bad-signature", ctxReq);
-    }
-    if (nonceStore) {
-      var expireAt = C.TIME.seconds(ts) + toleranceMs;
-      var fresh = await nonceStore.checkAndInsert(parsed.id, expireAt);
-      if (!fresh) {
-        throw _failure("REPLAY", "webhook: id '" + parsed.id + "' has been seen before", "replay", ctxReq);
-      }
-    }
-    _emitEvent("webhook.verify", 1, { outcome: "success", kid: matchedKid });
-    _auditEmit("success", null, { kid: matchedKid }, ctxReq);
-    return { algo: algo, kid: matchedKid, timestamp: ts, id: parsed.id };
-  }
-  function middleware() {
-    return function (req, res, next) {
-      var raw = req.bodyRaw;
-      if (raw === undefined) {
-        if (Buffer.isBuffer(req.body)) raw = req.body;
-        else if (typeof req.body === "string") raw = req.body;
-      }
-      if (raw === undefined) {
-        return _writeError(res, 401, "MISSING_RAW_BODY",
-          "webhook verifier middleware requires bodyParser({ keepRawBody: true })");
-      }
-      verify({ body: raw, headers: req.headers, req: req }).then(
-        function (info) {
-          req.webhook = info;
-          next();
-        },
-        function (err) {
-          if (err && err.isWebhookError) {
-            _writeError(res, 401, err.code, err.message);
-          } else {
-            _writeError(res, 500, "VERIFY_ERROR", "webhook verification error");
-          }
-        }
-      );
-    };
-  }
-  return {
-    verify:     verify,
-    middleware: middleware,
-  };
-}
-function _writeError(res, status, code, message) {
-  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
-  res.end(JSON.stringify({ error: code, message: message }));
-}
-// ---- Public surface ----
-module.exports = {
-  signer:       signer,
-  verifier:     verifier,
-  ALGOS:        ALGOS,
-  HEADER:       HEADER,
-  DEFAULTS:     DEFAULTS,
-  WebhookError: WebhookError,
-};
+"use strict";
+/**
+ * b.webhook — outbound webhook signing + inbound verification.
+ *
+ *   var signer = b.webhook.signer({
+ *     algo:       "hmac-sha3-512",
+ *     keys:       { v1: secretBytes },
+ *     defaultKid: "v1",
+ *   });
+ *
+ *   await signer.send({ url: "https://example.com/hook", body: jsonString });
+ *   // POSTs with:
+ *   //   Webhook-Signature: t=<unix-seconds>,id=<uuid>,v1=<sig-hex>
+ *
+ *   var verifier = b.webhook.verifier({
+ *     algo:        "hmac-sha3-512",
+ *     keys:        { v1: secret, v0: oldSecret },     // multi-key for rotation
+ *     toleranceMs: b.constants.TIME.minutes(5),
+ *     nonceStore:  b.nonceStore.create({ ... }),      // optional replay defense
+ *   });
+ *
+ *   router.use(b.middleware.bodyParser({ keepRawBody: true }));   // REQUIRED
+ *   router.post("/inbound-webhook", verifier.middleware(), function (req, res) {
+ *     // req.webhook = { algo, kid, timestamp, id }
+ *   });
+ *
+ * Algorithms:
+ *   "hmac-sha3-512" — symmetric. keys: { kid → Buffer/string secret }
+ *   "pqc-pem"       — asymmetric. keys map for signer:
+ *                       { kid → { privateKey, publicKey } }   (PEM)
+ *                     keys map for verifier:
+ *                       { kid → publicKey }                   (PEM)
+ *                     Algorithm (SLH-DSA-SHAKE-256f / ML-DSA-87) is
+ *                     auto-detected by Node from the PEM. No classical
+ *                     (Ed25519, RSA, ECDSA) signature scheme is exposed.
+ *
+ * Signed string (deterministic, prefix-bound to defend against algorithm-
+ * substitution and key-substitution attacks):
+ *
+ *     <algo>.<kid>.<timestamp>.<id>.<body>
+ *
+ * Header format (single combined header, Stripe-shape):
+ *
+ *     Webhook-Signature: t=<unix-seconds>,id=<uuid>,<kid>=<sig-hex>
+ *
+ * `t` and `id` are reserved segment names; every other `<name>=<value>`
+ * pair is treated as a kid → signature mapping. Multiple kid pairs are
+ * accepted on the verifier side; the signer emits exactly one. Operators
+ * rotating keys point the verifier at both old + new keys and migrate
+ * signers progressively.
+ *
+ * Replay defense:
+ *   - `id` is included in the signed string, so a captured signature
+ *     cannot be reused with a fresh id.
+ *   - Optional `nonceStore` records seen ids; second delivery with the
+ *     same id rejects with REPLAY. The framework's b.nonceStore is the
+ *     reference impl; operators plug in Redis/SQL by passing any object
+ *     with `checkAndInsert(nonce, expireAt) → bool/Promise<bool>`.
+ *
+ * Validation policy:
+ *
+ *   - signer/verifier creation opts → throw at config time
+ *   - signer.sign body type         → throw at call site
+ *   - signer.send url shape         → throw at call site (via safeUrl)
+ *   - verifier.verify input shape   → throw WebhookError at call site
+ *   - nonceStore.checkAndInsert err → propagates (fail-closed)
+ */
+var crypto = require("./crypto");
+var httpClient = require("./http-client");
+var safeBuffer = require("./safe-buffer");
+var safeUrl = require("./safe-url");
+var retry = require("./retry");
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var numericChecks = require("./numeric-checks");
+var requestHelpers = require("./request-helpers");
+var validateOpts = require("./validate-opts");
+var { WebhookError } = require("./framework-error");
+var observability = lazyRequire(function () { return require("./observability"); });
+function _emitEvent(n, v, l) { observability().safeEvent(n, v, l || {}); }
+var _err = WebhookError.factory;
+// ---- Constants ----
+var ALGOS = Object.freeze({
+  HMAC_SHA3_512: "hmac-sha3-512",
+  PQC_PEM:       "pqc-pem",
+});
+var HEADER = Object.freeze({
+  SIGNATURE: "Webhook-Signature",
+});
+var DEFAULTS = Object.freeze({
+  toleranceMs:     C.TIME.minutes(5),
+  clockSkewMs:     C.TIME.minutes(1),
+  signatureHeader: HEADER.SIGNATURE,
+  // Audit defaults: BOTH success and failure default ON. The webhook
+  // verify is the framework boundary where an inbound message gets
+  // accepted — that acceptance IS the audit-worthy event, not a
+  // precursor to one. "Inbound webhook id <X> verified from kid <Y>
+  // at time T" is the compliance trail. The send side mirrors:
+  // outbound delivery success/failure to a partner is also a
+  // standalone audit event. Operators with extreme volume opt out
+  // via auditSuccess: false; failures remain on regardless.
+  auditFailures:   true,
+  auditSuccess:    true,
+});
+// ---- Call-site validation helpers (throw on bad input) ----
+var _isPositiveInt  = numericChecks.isPositiveInt;
+var _isNonNegFinite = numericChecks.isFiniteNonNegative;
+function _hasOwn(obj, k) { return Object.prototype.hasOwnProperty.call(obj, k); }
+function _objectKeys(obj) { return Object.keys(obj); }
+function _validateAlgo(algo) {
+  if (algo !== ALGOS.HMAC_SHA3_512 && algo !== ALGOS.PQC_PEM) {
+    throw _err("BAD_OPT", "webhook: algo must be one of " +
+      JSON.stringify([ALGOS.HMAC_SHA3_512, ALGOS.PQC_PEM]) + ", got " + JSON.stringify(algo));
+  }
+}
+function _validateKeysShape(name, algo, keys, side) {
+  if (!keys || typeof keys !== "object" || Array.isArray(keys)) {
+    throw _err("BAD_OPT", name + ": keys must be a non-empty object map of kid → key, got " +
+      typeof keys);
+  }
+  var kids = _objectKeys(keys);
+  if (kids.length === 0) {
+    throw _err("BAD_OPT", name + ": keys must have at least one kid entry");
+  }
+  for (var i = 0; i < kids.length; i++) {
+    var kid = kids[i];
+    if (kid.length === 0 || /[,=\s]/.test(kid)) {
+      throw _err("BAD_OPT", name + ": kid must be non-empty and contain no comma/equals/whitespace, got " +
+        JSON.stringify(kid));
+    }
+    if (kid === "t" || kid === "id") {
+      throw _err("BAD_OPT", name + ": kid '" + kid + "' is reserved (collides with header field)");
+    }
+    var k = keys[kid];
+    if (algo === ALGOS.HMAC_SHA3_512) {
+      if (!Buffer.isBuffer(k) && typeof k !== "string") {
+        throw _err("BAD_OPT", name + ": HMAC key for kid '" + kid +
+          "' must be a Buffer or string, got " + typeof k);
+      }
+      if (k.length === 0) {
+        throw _err("BAD_OPT", name + ": HMAC key for kid '" + kid + "' must be non-empty");
+      }
+    } else if (algo === ALGOS.PQC_PEM) {
+      if (side === "signer") {
+        if (!k || typeof k !== "object" || Array.isArray(k) ||
+            (typeof k.privateKey !== "string" && !Buffer.isBuffer(k.privateKey)) ||
+            (typeof k.publicKey  !== "string" && !Buffer.isBuffer(k.publicKey))) {
+          throw _err("BAD_OPT", name + ": PQC signer key for kid '" + kid +
+            "' must be { privateKey, publicKey } as PEM strings/Buffers");
+        }
+      } else {
+        if (typeof k !== "string" && !Buffer.isBuffer(k)) {
+          throw _err("BAD_OPT", name + ": PQC verifier key for kid '" + kid +
+            "' must be a PEM string/Buffer (public key)");
+        }
+      }
+    }
+  }
+}
+function _validateBody(body) {
+  if (typeof body !== "string" && !Buffer.isBuffer(body)) {
+    throw _err("BAD_BODY", "webhook: body must be a string or Buffer, got " + typeof body);
+  }
+}
+// ---- Signed-string composition ----
+function _composeSignedString(algo, kid, timestamp, id, body) {
+  var prefix = algo + "." + kid + "." + timestamp + "." + id + ".";
+  if (Buffer.isBuffer(body)) {
+    return Buffer.concat([Buffer.from(prefix, "utf8"), body]);
+  }
+  return Buffer.from(prefix + body, "utf8");
+}
+// ---- Sign / verify primitives ----
+function _hmacSign(key, data) {
+  return crypto.hmacSha3(key, data);    // hex string
+}
+function _hmacVerify(key, data, expectedHex) {
+  if (!safeBuffer.isHex(expectedHex)) return false;
+  var actualHex = crypto.hmacSha3(key, data);
+  return crypto.timingSafeEqual(actualHex, expectedHex);
+}
+function _pqcSign(privateKeyPem, data) {
+  return crypto.sign(data, privateKeyPem).toString("hex");
+}
+function _pqcVerify(publicKeyPem, data, expectedHex) {
+  if (!safeBuffer.isHex(expectedHex) || (expectedHex.length % 2) !== 0) {
+    return false;
+  }
+  var sigBuf;
+  try { sigBuf = Buffer.from(expectedHex, "hex"); }
+  catch (_e) { return false; }
+  try { return crypto.verify(data, sigBuf, publicKeyPem); }
+  catch (_e) { return false; }
+}
+// ---- Header parsing ----
+//
+// Format:  t=<seconds>,id=<uuid>,<kid>=<hex>[,<kid>=<hex>]*
+// `t` and `id` are reserved segment names; everything else is treated as
+// a kid → signature pair. Whitespace tolerated around commas.
+function _parseSignatureHeader(headerValue) {
+  var segs = requestHelpers.parseListHeader(headerValue);
+  var t = null, id = null, sigs = {};
+  for (var i = 0; i < segs.length; i++) {
+    var seg = segs[i];
+    var eq = seg.indexOf("=");
+    if (eq <= 0) continue;            // skip malformed segments rather than failing whole header
+    var name = seg.slice(0, eq);
+    var value = seg.slice(eq + 1);
+    if (name === "t") t = value;
+    else if (name === "id") id = value;
+    else if (name.length > 0) sigs[name] = value;   // kid → sig hex
+  }
+  return { t: t, id: id, sigs: sigs };
+}
+// ---- Signer ----
+function _validateSignerOpts(opts) {
+  validateOpts.requireObject(opts, "webhook.signer", WebhookError);
+  _validateAlgo(opts.algo);
+  _validateKeysShape("webhook.signer", opts.algo, opts.keys, "signer");
+  var kids = _objectKeys(opts.keys);
+  if (opts.defaultKid !== undefined) {
+    if (!_hasOwn(opts.keys, opts.defaultKid)) {
+      throw _err("BAD_OPT", "webhook.signer: defaultKid '" + opts.defaultKid +
+        "' not present in keys (have: " + JSON.stringify(kids) + ")");
+    }
+  } else if (kids.length > 1) {
+    throw _err("BAD_OPT", "webhook.signer: defaultKid required when keys has " +
+      kids.length + " entries");
+  }
+  validateOpts.optionalNonEmptyString(opts.signatureHeader, "webhook.signer: signatureHeader", WebhookError);
+  validateOpts.optionalFunction(opts.idGenerator, "webhook.signer: idGenerator", WebhookError);
+  validateOpts.optionalFunction(opts.now, "webhook.signer: now", WebhookError);
+  validateOpts.auditShape(opts.audit, "webhook.signer", WebhookError);
+}
+function signer(opts) {
+  _validateSignerOpts(opts);
+  var algo = opts.algo;
+  var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
+  var keys = opts.keys;
+  var kids = _objectKeys(keys);
+  var defaultKid = opts.defaultKid || kids[0];
+  var sigHeader = cfg.signatureHeader;
+  var idGen = opts.idGenerator || function () { return crypto.generateToken(C.BYTES.bytes(16)); };
+  var nowFn = opts.now || function () { return Date.now(); };
+  var retryOpts = opts.retry || retry.DEFAULT_RETRY;
+  var httpOpts = opts.http || {};
+  var audit = opts.audit || null;
+  var auditFailures = cfg.auditFailures;
+  var auditSuccess  = cfg.auditSuccess;
+  var _auditEmit = validateOpts.makeAuditEmitter(audit);
+  function _signOne(body, kid) {
+    _validateBody(body);
+    var keyForKid = kids.indexOf(kid) === -1 ? null : keys[kid];
+    if (keyForKid == null) {
+      throw _err("BAD_OPT", "webhook.signer: unknown kid '" + kid + "'");
+    }
+    var timestamp = Math.floor(nowFn() / C.TIME.seconds(1));
+    var id = idGen();
+    if (typeof id !== "string" || id.length === 0 || /[,=\s]/.test(id)) {
+      throw _err("BAD_OPT", "webhook.signer: idGenerator must return a non-empty string with no comma/equals/whitespace, got " + JSON.stringify(id));
+    }
+    var signed = _composeSignedString(algo, kid, timestamp, id, body);
+    var sigHex;
+    if (algo === ALGOS.HMAC_SHA3_512) {
+      sigHex = _hmacSign(keyForKid, signed);
+    } else {
+      sigHex = _pqcSign(keyForKid.privateKey, signed);
+    }
+    return { kid: kid, timestamp: timestamp, id: id, signature: sigHex };
+  }
+  function sign(body, callOpts) {
+    var kid = (callOpts && callOpts.kid) || defaultKid;
+    var s = _signOne(body, kid);
+    var headerValue = "t=" + s.timestamp + ",id=" + s.id + "," + s.kid + "=" + s.signature;
+    var headers = {};
+    headers[sigHeader] = headerValue;
+    return {
+      headers:   headers,
+      timestamp: s.timestamp,
+      id:        s.id,
+      kid:       s.kid,
+      signature: s.signature,
+    };
+  }
+  function headers(body, callOpts) {
+    return sign(body, callOpts).headers;
+  }
+  async function send(input) {
+    if (!input || typeof input !== "object") {
+      throw _err("BAD_OPT", "webhook.signer.send: input must be { url, body, headers? }");
+    }
+    var url = input.url;
+    var body = input.body;
+    safeUrl.parse(url, {
+      allowedProtocols: httpOpts.allowedProtocols || safeUrl.ALLOW_HTTP_TLS,
+      errorClass:       WebhookError,
+    });
+    _validateBody(body);
+    var signed = sign(body, { kid: input.kid });
+    var mergedHeaders = Object.assign({}, input.headers || {}, signed.headers);
+    if (!mergedHeaders["Content-Type"] && !mergedHeaders["content-type"]) {
+      mergedHeaders["Content-Type"] = Buffer.isBuffer(body)
+        ? "application/octet-stream"
+        : "application/json";
+    }
+    var requestOpts = Object.assign({
+      method:           "POST",
+      url:              url,
+      headers:          mergedHeaders,
+      body:             body,
+      allowedProtocols: safeUrl.ALLOW_HTTP_TLS,
+      errorClass:       WebhookError,
+    }, httpOpts);
+    requestOpts.headers = mergedHeaders;
+    requestOpts.url = url;
+    requestOpts.body = body;
+    requestOpts.method = "POST";
+    var hostLabel = "";
+    try {
+      hostLabel = safeUrl.parse(url, {
+        allowedProtocols: httpOpts.allowedProtocols || safeUrl.ALLOW_HTTP_TLS,
+        errorClass:       WebhookError,
+      }).host;
+    } catch (_e) { hostLabel = ""; }
+    try {
+      var res = await retry.withRetry(function () {
+        return httpClient.request(requestOpts);
+      }, retryOpts);
+      var statusCode = (res && (res.statusCode || res.status)) || 0;
+      _emitEvent("webhook.send", 1, {
+        outcome: statusCode >= 200 && statusCode < 300 ? "success" : "failure",
+        status: statusCode,
+        host: hostLabel,
+      });
+      if (auditSuccess && statusCode >= 200 && statusCode < 300) {
+        _auditEmit("webhook.send", {
+          resource: { kind: "webhook", id: hostLabel },
+          outcome:  "success",
+          metadata: { status: statusCode },
+        });
+      }
+      if (auditFailures && (statusCode < 200 || statusCode >= 300)) {
+        _auditEmit("webhook.send", {
+          resource: { kind: "webhook", id: hostLabel },
+          outcome:  "failure",
+          reason:   "http-" + statusCode,
+        });
+      }
+      return res;
+    } catch (err) {
+      _emitEvent("webhook.send", 1, {
+        outcome: "failure", reason: "transport-error", host: hostLabel,
+      });
+      if (auditFailures) {
+        _auditEmit("webhook.send", {
+          resource: { kind: "webhook", id: hostLabel },
+          outcome:  "failure",
+          reason:   (err && err.code) || "transport-error",
+        });
+      }
+      throw err;
+    }
+  }
+  return {
+    sign:    sign,
+    headers: headers,
+    send:    send,
+  };
+}
+// ---- Verifier ----
+function _validateVerifierOpts(opts) {
+  validateOpts.requireObject(opts, "webhook.verifier", WebhookError);
+  _validateAlgo(opts.algo);
+  _validateKeysShape("webhook.verifier", opts.algo, opts.keys, "verifier");
+  validateOpts.optionalFiniteNonNegative(opts.toleranceMs, "webhook.verifier: toleranceMs", WebhookError);
+  validateOpts.optionalFiniteNonNegative(opts.clockSkewMs, "webhook.verifier: clockSkewMs", WebhookError);
+  validateOpts.optionalNonEmptyString(opts.signatureHeader, "webhook.verifier: signatureHeader", WebhookError);
+  validateOpts.optionalObjectWithMethod(opts.nonceStore, "checkAndInsert",
+    "webhook.verifier: nonceStore", WebhookError, "BAD_OPT",
+    "must implement checkAndInsert(nonce, expireAt)");
+  validateOpts.optionalFunction(opts.now, "webhook.verifier: now", WebhookError);
+  validateOpts.auditShape(opts.audit, "webhook.verifier", WebhookError);
+  validateOpts.optionalBoolean(opts.auditFailures, "webhook.verifier: auditFailures", WebhookError);
+  validateOpts.optionalBoolean(opts.auditSuccess, "webhook.verifier: auditSuccess", WebhookError);
+}
+function verifier(opts) {
+  _validateVerifierOpts(opts);
+  var cfg = validateOpts.applyDefaults(opts, DEFAULTS);
+  var algo = opts.algo;
+  var keys = opts.keys;
+  var toleranceMs = cfg.toleranceMs;
+  var clockSkewMs = cfg.clockSkewMs;
+  var sigHeader = cfg.signatureHeader.toLowerCase();
+  var nonceStore = opts.nonceStore || null;
+  var nowFn = opts.now || function () { return Date.now(); };
+  var audit = opts.audit || null;
+  var auditFailures = cfg.auditFailures;
+  var auditSuccess  = cfg.auditSuccess;
+  function _auditEmit(outcome, reason, info, req) {
+    if (!audit) return;
+    if (outcome === "success" && !auditSuccess) return;
+    if (outcome === "failure" && !auditFailures) return;
+    try {
+      audit.safeEmit({
+        action:   "webhook.verify",
+        actor:    requestHelpers.extractActorContext(req),
+        resource: { kind: "webhook" },
+        outcome:  outcome,
+        reason:   reason || null,
+        metadata: info || null,
+      });
+    } catch (_e) { /* audit best-effort */ }
+  }
+  function _failure(code, message, reason, req) {
+    _emitEvent("webhook.verify", 1, { outcome: "failure", reason: reason || code });
+    _auditEmit("failure", reason || code, null, req);
+    return _err(code, message);
+  }
+  async function verify(input) {
+    if (!input || typeof input !== "object") {
+      throw _err("BAD_OPT", "webhook.verifier.verify: input must be { body, headers }");
+    }
+    var headers = input.headers;
+    if (!headers || typeof headers !== "object") {
+      throw _err("BAD_OPT", "webhook.verifier.verify: headers must be an object");
+    }
+    var body = input.body;
+    _validateBody(body);
+    var ctxReq = input.req || null;
+    // Headers may be node-style (lowercased keys) or operator-supplied
+    // (mixed case). Resolve case-insensitively.
+    var headerValue = null;
+    var headerKeys = Object.keys(headers);
+    for (var i = 0; i < headerKeys.length; i++) {
+      if (headerKeys[i].toLowerCase() === sigHeader) {
+        headerValue = headers[headerKeys[i]];
+        break;
+      }
+    }
+    if (typeof headerValue !== "string" || headerValue.length === 0) {
+      throw _failure("MISSING_HEADER",
+        "webhook: " + (opts.signatureHeader || HEADER.SIGNATURE) + " header missing",
+        "missing-header", ctxReq);
+    }
+    var parsed = _parseSignatureHeader(headerValue);
+    if (parsed.t === null && parsed.id === null && Object.keys(parsed.sigs).length === 0) {
+      throw _failure("BAD_HEADER_FORMAT", "webhook: signature header could not be parsed", "bad-header-format", ctxReq);
+    }
+    if (parsed.t === null) {
+      throw _failure("MISSING_TIMESTAMP", "webhook: t= field missing from signature header", "missing-timestamp", ctxReq);
+    }
+    var ts = Number(parsed.t);
+    if (!isFinite(ts) || ts < 0 || Math.floor(ts) !== ts) {
+      throw _failure("BAD_TIMESTAMP", "webhook: t= field is not a non-negative integer, got " + JSON.stringify(parsed.t), "bad-timestamp", ctxReq);
+    }
+    if (parsed.id === null || parsed.id.length === 0) {
+      throw _failure("MISSING_ID", "webhook: id= field missing from signature header", "missing-id", ctxReq);
+    }
+    var sigKids = Object.keys(parsed.sigs);
+    if (sigKids.length === 0) {
+      throw _failure("MISSING_SIGNATURE", "webhook: no v<kid>= segment found in signature header", "missing-signature", ctxReq);
+    }
+    // Timestamp window: signed in seconds, compare to ms clock.
+    var nowMs = nowFn();
+    var ageMs = nowMs - C.TIME.seconds(ts);
+    if (ageMs > toleranceMs) {
+      throw _failure("EXPIRED", "webhook: timestamp older than toleranceMs (age=" + ageMs + "ms)", "expired", ctxReq);
+    }
+    if (-ageMs > clockSkewMs) {
+      throw _failure("FUTURE", "webhook: timestamp in the future beyond clockSkewMs (skew=" + (-ageMs) + "ms)", "future", ctxReq);
+    }
+    // Find the first kid the verifier holds a key for.
+    var matchedKid = null;
+    for (var j = 0; j < sigKids.length; j++) {
+      if (_hasOwn(keys, sigKids[j])) { matchedKid = sigKids[j]; break; }
+    }
+    if (matchedKid === null) {
+      throw _failure("UNKNOWN_KID",
+        "webhook: no registered key matches signed kids " + JSON.stringify(sigKids),
+        "unknown-kid", ctxReq);
+    }
+    var signed = _composeSignedString(algo, matchedKid, ts, parsed.id, body);
+    var ok;
+    if (algo === ALGOS.HMAC_SHA3_512) {
+      ok = _hmacVerify(keys[matchedKid], signed, parsed.sigs[matchedKid]);
+    } else {
+      ok = _pqcVerify(keys[matchedKid], signed, parsed.sigs[matchedKid]);
+    }
+    if (!ok) {
+      throw _failure("BAD_SIGNATURE", "webhook: cryptographic verification failed", "bad-signature", ctxReq);
+    }
+    if (nonceStore) {
+      var expireAt = C.TIME.seconds(ts) + toleranceMs;
+      var fresh = await nonceStore.checkAndInsert(parsed.id, expireAt);
+      if (!fresh) {
+        throw _failure("REPLAY", "webhook: id '" + parsed.id + "' has been seen before", "replay", ctxReq);
+      }
+    }
+    _emitEvent("webhook.verify", 1, { outcome: "success", kid: matchedKid });
+    _auditEmit("success", null, { kid: matchedKid }, ctxReq);
+    return { algo: algo, kid: matchedKid, timestamp: ts, id: parsed.id };
+  }
+  function middleware() {
+    return function (req, res, next) {
+      var raw = req.bodyRaw;
+      if (raw === undefined) {
+        if (Buffer.isBuffer(req.body)) raw = req.body;
+        else if (typeof req.body === "string") raw = req.body;
+      }
+      if (raw === undefined) {
+        return _writeError(res, 401, "MISSING_RAW_BODY",
+          "webhook verifier middleware requires bodyParser({ keepRawBody: true })");
+      }
+      verify({ body: raw, headers: req.headers, req: req }).then(
+        function (info) {
+          req.webhook = info;
+          next();
+        },
+        function (err) {
+          if (err && err.isWebhookError) {
+            _writeError(res, 401, err.code, err.message);
+          } else {
+            _writeError(res, 500, "VERIFY_ERROR", "webhook verification error");
+          }
+        }
+      );
+    };
+  }
+  return {
+    verify:     verify,
+    middleware: middleware,
+  };
+}
+function _writeError(res, status, code, message) {
+  res.writeHead(status, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify({ error: code, message: message }));
+}
+// ---- Public surface ----
+module.exports = {
+  signer:       signer,
+  verifier:     verifier,
+  ALGOS:        ALGOS,
+  HEADER:       HEADER,
+  DEFAULTS:     DEFAULTS,
+  WebhookError: WebhookError,
+};