@blamejs/core 0.10.14 → 0.11.0

package/lib/metrics.js

@@ -376,6 +376,7 @@ function create(opts) {
       type:       "counter",
       name:       fullName,
       help:       help,
+      unit:       copts.unit || null,
       labelNames: labelNames,
       values:     values,
       inc: function (callLabels, n) {
@@ -445,6 +446,7 @@ function create(opts) {
       type:       "gauge",
       name:       fullName,
       help:       help,
+      unit:       copts.unit || null,
       labelNames: labelNames,
       values:     values,
       set: function (callLabels, v) {
@@ -509,10 +511,11 @@ function create(opts) {
       type:       "histogram",
       name:       fullName,
       help:       help,
+      unit:       copts.unit || null,
       labelNames: labelNames,
       buckets:    buckets,
       values:     values,
-      observe: function (callLabels, v) {
+      observe: function (callLabels, v, exemplar) {
         var arg = _normalizeLabelArg(callLabels, v, NaN);
         if (typeof arg.value !== "number" || isNaN(arg.value)) {
           throw new MetricsError("metrics/histogram-bad-value",
@@ -531,15 +534,28 @@ function create(opts) {
           }
           // counts[i] is the count for the [<=buckets[i]] bucket; counts[buckets.length] is +Inf.
           entry = {
-            labels: resolved,
-            counts: new Array(buckets.length + 1).fill(0),
-            sum:    0,
-            count:  0,
+            labels:    resolved,
+            counts:    new Array(buckets.length + 1).fill(0),
+            sum:       0,
+            count:     0,
+            exemplars: new Array(buckets.length + 1).fill(null),
           };
           values.set(key, entry);
         }
         for (var i = 0; i < buckets.length; i++) {
-          if (arg.value <= buckets[i]) entry.counts[i]++;
+          if (arg.value <= buckets[i]) {
+            entry.counts[i]++;
+            // OpenMetrics §6.2 — store the most-recent exemplar per
+            // bucket. Operators wire trace_id / span_id via `exemplar`
+            // arg; the registry only records what's passed in.
+            if (exemplar && typeof exemplar === "object") {
+              entry.exemplars[i] = {
+                labels:    exemplar.labels    || {},
+                value:     exemplar.value !== undefined ? exemplar.value : arg.value,
+                timestamp: exemplar.timestamp || null,
+              };
+            }
+          }
         }
         entry.counts[buckets.length]++;   // +Inf bucket is everything
         entry.sum   += arg.value;
@@ -552,34 +568,68 @@ function create(opts) {
 
   // ---- exposition ----
 
-  function exposition() {
+  function exposition(opts) {
+    opts = opts || {};
+    // v0.10.16 — `format: "openmetrics"` emits OpenMetrics 1.0 wire
+    // format (RFC TBD; project at https://openmetrics.io). Differences
+    // from Prometheus 0.0.4: `# UNIT <metric> <unit>` lines, `_total`
+    // suffix MUST on counters, `# EOF` terminator. v0.10.16 ships
+    // the EOF terminator + UNIT lines when opts.format === "openmetrics".
+    var openMetrics = opts.format === "openmetrics";
     var lines = [];
     var sortedNames = Array.from(metrics.keys()).sort();
     for (var i = 0; i < sortedNames.length; i++) {
       var m = metrics.get(sortedNames[i]);
-      if (m.help) lines.push("# HELP " + m.name + " " + m.help);
-      lines.push("# TYPE " + m.name + " " + m.type);
+      // OpenMetrics §5.1.2 — counter sample lines MUST suffix with
+      // `_total`. The metadata `# HELP / # TYPE / # UNIT` lines MUST
+      // name the SAME family identifier the samples use, otherwise
+      // strict OpenMetrics parsers reject the family. Derive the
+      // exposition name once at the top of the loop so both the
+      // metadata lines and the sample lines agree.
+      var exposedName = m.name;
+      if (openMetrics && m.type === "counter" && !/_total$/.test(m.name)) {
+        exposedName = m.name + "_total";
+      }
+      if (m.help) lines.push("# HELP " + exposedName + " " + m.help);
+      lines.push("# TYPE " + exposedName + " " + m.type);
+      if (openMetrics && m.unit) lines.push("# UNIT " + exposedName + " " + m.unit);
       var keys = Array.from(m.values.keys()).sort();
       if (m.type === "histogram") {
         for (var k = 0; k < keys.length; k++) {
           var entry = m.values.get(keys[k]);
           for (var bi = 0; bi < m.buckets.length; bi++) {
             var bLabels = Object.assign({}, entry.labels, { le: String(m.buckets[bi]) });
-            lines.push(m.name + "_bucket" + _renderLabels(bLabels) + " " + entry.counts[bi]);
+            var bucketLine = m.name + "_bucket" + _renderLabels(bLabels) + " " + entry.counts[bi];
+            // OpenMetrics 1.0 §6.2 — exemplar trace + span IDs appended
+            // as `# {trace_id="...",span_id="..."} <value> <timestamp>`.
+            if (openMetrics && entry.exemplars && entry.exemplars[bi]) {
+              var ex = entry.exemplars[bi];
+              bucketLine += " # " + _renderLabels(ex.labels || {}) + " " + ex.value;
+              if (ex.timestamp) bucketLine += " " + ex.timestamp;
+            }
+            lines.push(bucketLine);
           }
           var infLabels = Object.assign({}, entry.labels, { le: "+Inf" });
           lines.push(m.name + "_bucket" + _renderLabels(infLabels) + " " + entry.counts[m.buckets.length]);
           lines.push(m.name + "_sum"   + _renderLabels(entry.labels) + " " + entry.sum);
           lines.push(m.name + "_count" + _renderLabels(entry.labels) + " " + entry.count);
         }
-      } else {
+      } else if (m.type === "counter" && openMetrics) {
+        // exposedName already carries the `_total` suffix when needed
+        // (derived at the top of the loop so metadata + samples agree).
         for (var v = 0; v < keys.length; v++) {
           var ent = m.values.get(keys[v]);
-          lines.push(m.name + _renderLabels(ent.labels) + " " + ent.value);
+          lines.push(exposedName + _renderLabels(ent.labels) + " " + ent.value);
+        }
+      } else {
+        for (var v2 = 0; v2 < keys.length; v2++) {
+          var ent2 = m.values.get(keys[v2]);
+          lines.push(m.name + _renderLabels(ent2.labels) + " " + ent2.value);
         }
       }
       lines.push("");
     }
+    if (openMetrics) lines.push("# EOF");
     return lines.join("\n") + (lines.length ? "" : "\n");
   }
 

package/lib/middleware/security-headers.js

@@ -10,7 +10,8 @@
  *   Referrer-Policy: no-referrer     — don't leak full URL to outbound links
  *   Permissions-Policy               — disable common-attack APIs (camera, geolocation, payment, etc.)
  *   Cross-Origin-Opener-Policy: same-origin
- *   Cross-Origin-Embedder-Policy: require-corp   (off by default — breaks images from CDNs)
+ *   Cross-Origin-Embedder-Policy: require-corp / credentialless   (off by default — breaks images from CDNs; credentialless is the
+ *   CR 2024-12 relaxed mode that lets cross-origin no-cors requests load without CORP markers as long as they don't carry credentials)
  *   Cross-Origin-Resource-Policy: same-origin
  *   Origin-Agent-Cluster: ?1        — origin-keyed agent cluster; extra process isolation
  *   X-DNS-Prefetch-Control: off     — don't pre-resolve DNS for off-page links

package/lib/standard-webhooks.js

@@ -0,0 +1,183 @@
+"use strict";
+/**
+ * @module b.standardWebhooks
+ * @nav    HTTP
+ * @title  Standard Webhooks
+ * @order  235
+ *
+ * @intro
+ *   StandardWebhooks (standardwebhooks.com) signing + verification —
+ *   the consortium spec (Stripe / Svix / Okta / etc.) for inbound
+ *   webhook authentication. Three headers:
+ *
+ *     webhook-id        ULID-ish unique identifier
+ *     webhook-timestamp Unix seconds at send time
+ *     webhook-signature `v1,<base64-of-HMAC-SHA256-result>` (multi-version)
+ *
+ *   The signature payload is `<id>.<timestamp>.<body>`, signed with the
+ *   shared secret. Verification reproduces the signature and uses
+ *   `b.crypto.timingSafeEqual` to compare. Skew tolerated within
+ *   `tolerance` seconds (default 5 minutes).
+ *
+ * @card
+ *   StandardWebhooks (standardwebhooks.com) HMAC-SHA256 sign + verify for inbound + outbound webhook delivery. 5-minute skew tolerance + version-prefix header.
+ */
+
+var nodeCrypto = require("node:crypto");
+var validateOpts = require("./validate-opts");
+var numericBounds = require("./numeric-bounds");
+var bCrypto    = require("./crypto");
+var C          = require("./constants");
+var { defineClass } = require("./framework-error");
+
+var StandardWebhooksError = defineClass("StandardWebhooksError", { alwaysPermanent: true });
+
+var DEFAULT_TOLERANCE_SEC = 300;                                                                      // allow:raw-time-literal allow:raw-byte-literal — 5min default per StandardWebhooks §3.2
+
+/**
+ * @primitive b.standardWebhooks.sign
+ * @signature b.standardWebhooks.sign(opts)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Build the three StandardWebhooks headers for an outbound delivery.
+ * Returns `{ headers, body }` where `body` is the raw request body
+ * (operators write that to the wire; the headers go on the request).
+ *
+ * @opts
+ *   id:        string,         // auto-minted if omitted (32-byte random)
+ *   timestamp: number,         // Unix seconds; defaults to now
+ *   body:      Buffer|string,  // request body bytes
+ *   secret:    Buffer,         // shared secret (>= 32 bytes)
+ *
+ * @example
+ *   var s = b.standardWebhooks.sign({ body: bodyBuf, secret: secret });
+ *   for (var k in s.headers) req.setHeader(k, s.headers[k]);
+ */
+function sign(opts) {
+  opts = validateOpts.requireObject(opts, "standardWebhooks.sign",
+    StandardWebhooksError, "standard-webhooks/bad-opts");
+  validateOpts(opts, ["id", "timestamp", "body", "secret"], "standardWebhooks.sign");
+  if (!Buffer.isBuffer(opts.secret) || opts.secret.length < 32) {                                     // allow:raw-byte-literal — 32-byte HMAC secret floor
+    throw new StandardWebhooksError("standard-webhooks/bad-secret",
+      "sign: opts.secret must be a Buffer (>= 32 bytes)");
+  }
+  if (!opts.body || (!Buffer.isBuffer(opts.body) && typeof opts.body !== "string")) {
+    throw new StandardWebhooksError("standard-webhooks/bad-body",
+      "sign: opts.body must be a non-empty Buffer or string");
+  }
+  var bodyBuf = Buffer.isBuffer(opts.body) ? opts.body : Buffer.from(opts.body, "utf8");
+  var id = opts.id || ("msg_" + bCrypto.generateToken(32));                                           // allow:raw-byte-literal — 32-char id token
+  var timestamp = typeof opts.timestamp === "number"
+    ? opts.timestamp
+    : Math.floor(Date.now() / 1000);                                                                  // allow:raw-time-literal — wall-clock seconds
+  if (timestamp <= 0 || !isFinite(timestamp)) {
+    throw new StandardWebhooksError("standard-webhooks/bad-timestamp",
+      "sign: timestamp must be a positive finite integer");
+  }
+  var toSign = id + "." + timestamp + "." + bodyBuf.toString("utf8");
+  var sigB64 = nodeCrypto.createHmac("sha256", opts.secret).update(toSign).digest("base64");
+  return {
+    headers: {
+      "webhook-id":        id,
+      "webhook-timestamp": String(timestamp),
+      "webhook-signature": "v1," + sigB64,
+    },
+    body: bodyBuf,
+  };
+}
+
+/**
+ * @primitive b.standardWebhooks.verify
+ * @signature b.standardWebhooks.verify(opts)
+ * @since     0.10.16
+ * @status    stable
+ *
+ * Verify an inbound webhook against the StandardWebhooks spec.
+ * Refuses on missing headers, timestamp skew > tolerance, or
+ * HMAC mismatch. Returns `{ valid, id, timestamp }`.
+ *
+ * @opts
+ *   headers:    object,           // request headers
+ *   body:       Buffer|string,    // raw request body
+ *   secret:     Buffer,           // shared secret
+ *   toleranceSec: number,         // default 300s (5 minutes)
+ *
+ * @example
+ *   var v = b.standardWebhooks.verify({
+ *     headers: req.headers, body: rawBody, secret: secret,
+ *   });
+ *   if (!v.valid) throw 401;
+ */
+function verify(opts) {
+  opts = validateOpts.requireObject(opts, "standardWebhooks.verify",
+    StandardWebhooksError, "standard-webhooks/bad-opts");
+  validateOpts(opts, ["headers", "body", "secret", "toleranceSec"],
+    "standardWebhooks.verify");
+  if (!opts.headers || typeof opts.headers !== "object") {
+    throw new StandardWebhooksError("standard-webhooks/bad-headers",
+      "verify: opts.headers required");
+  }
+  if (!Buffer.isBuffer(opts.secret) || opts.secret.length < 32) {                                     // allow:raw-byte-literal — 32-byte HMAC secret floor
+    throw new StandardWebhooksError("standard-webhooks/bad-secret",
+      "verify: opts.secret must be a Buffer (>= 32 bytes)");
+  }
+  var bodyBuf = Buffer.isBuffer(opts.body) ? opts.body
+              : typeof opts.body === "string" ? Buffer.from(opts.body, "utf8")
+              : null;
+  if (!bodyBuf) {
+    throw new StandardWebhooksError("standard-webhooks/bad-body",
+      "verify: opts.body must be a Buffer or string");
+  }
+  // Normalise header names — case-insensitive.
+  var lower = {};
+  var keys = Object.keys(opts.headers);
+  for (var i = 0; i < keys.length; i += 1) lower[keys[i].toLowerCase()] = opts.headers[keys[i]];
+  var id = lower["webhook-id"];
+  var tsStr = lower["webhook-timestamp"];
+  var sigHeader = lower["webhook-signature"];
+  if (!id || !tsStr || !sigHeader) {
+    throw new StandardWebhooksError("standard-webhooks/missing-headers",
+      "verify: webhook-id / webhook-timestamp / webhook-signature required");
+  }
+  var ts = parseInt(tsStr, 10);
+  if (!isFinite(ts) || ts <= 0) {
+    throw new StandardWebhooksError("standard-webhooks/bad-timestamp",
+      "verify: webhook-timestamp is not a positive integer");
+  }
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.toleranceSec, "toleranceSec",
+    StandardWebhooksError, "standard-webhooks/bad-tolerance");
+  var tolerance = typeof opts.toleranceSec === "number" ? opts.toleranceSec : DEFAULT_TOLERANCE_SEC;
+  var nowSec = Math.floor(Date.now() / 1000);                                                         // allow:raw-time-literal — wall-clock seconds
+  if (Math.abs(nowSec - ts) > tolerance) {
+    throw new StandardWebhooksError("standard-webhooks/timestamp-skew",
+      "verify: timestamp skew " + Math.abs(nowSec - ts) + "s exceeds tolerance " + tolerance + "s");
+  }
+  var toSign = id + "." + ts + "." + bodyBuf.toString("utf8");
+  var expected = nodeCrypto.createHmac("sha256", opts.secret).update(toSign).digest("base64");
+  // Multi-version: signature header is `v1,<sig> v2,<sig>` etc.
+  var parts = sigHeader.split(" ");
+  var any = false;
+  for (var p = 0; p < parts.length; p += 1) {
+    var pair = parts[p].split(",");
+    if (pair.length !== 2) continue;
+    if (pair[0] !== "v1") continue;
+    if (bCrypto.timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(pair[1], "utf8"))) {
+      any = true;
+      break;
+    }
+  }
+  if (!any) {
+    throw new StandardWebhooksError("standard-webhooks/bad-signature",
+      "verify: no v1 signature matched");
+  }
+  void C;   // module loaded for future tolerance defaulting; not used directly today
+  return { valid: true, id: id, timestamp: ts };
+}
+
+module.exports = {
+  sign:                       sign,
+  verify:                     verify,
+  DEFAULT_TOLERANCE_SEC:      DEFAULT_TOLERANCE_SEC,
+  StandardWebhooksError:      StandardWebhooksError,
+};

package/lib/web-push-vapid.js

@@ -0,0 +1,322 @@
+"use strict";
+/**
+ * @module b.webPush
+ * @nav    Networking
+ * @title  Web Push (VAPID)
+ * @order  240
+ *
+ * @intro
+ *   RFC 8292 Voluntary Application Server Identification (VAPID) for
+ *   Web Push (RFC 8030). Operators sign JWTs with an ECDSA-P256 key
+ *   to identify themselves to the push service; the browser-side
+ *   subscription includes the operator's VAPID public key in
+ *   `applicationServerKey`. RFC 8292 §3 mandates ES256; the framework
+ *   uses node:crypto for ECDSA because the protocol is not PQC-yet
+ *   (browser push services don't accept ML-DSA today; track
+ *   draft-ietf-webpush-vapid-pqc for the migration).
+ *
+ *   `b.webPush.buildVapidAuthHeader({ subscription, contact,
+ *   privateKeyPem, publicKeyPem })` returns the `Authorization:
+ *   vapid t=<jwt>, k=<base64url-pubkey>` header value the operator
+ *   sets on the push-request POST to the push-service endpoint.
+ *
+ *   `b.webPush.generateVapidKeypair()` returns `{ publicKeyPem,
+ *   privateKeyPem, publicKeyB64Url }` — the b64url-encoded public
+ *   key is what the browser code passes as `applicationServerKey`.
+ *
+ * @card
+ *   RFC 8292 VAPID JWT signer + RFC 8030 push request shape (ECDSA-P256). Operators sign once per subscription endpoint; browsers identify the push origin via the operator's public key.
+ */
+
+var nodeCrypto    = require("node:crypto");
+var C             = require("./constants");
+var validateOpts  = require("./validate-opts");
+var safeUrl       = require("./safe-url");
+var bCrypto       = require("./crypto");
+var { defineClass } = require("./framework-error");
+
+var WebPushError = defineClass("WebPushError", { alwaysPermanent: true });
+
+/**
+ * @primitive b.webPush.generateVapidKeypair
+ * @signature b.webPush.generateVapidKeypair()
+ * @since     0.10.16
+ * @status    stable
+ * @related   b.webPush.buildVapidAuthHeader
+ *
+ * Generate a fresh ECDSA-P256 keypair suitable for VAPID. Returns
+ * `{ publicKeyPem, privateKeyPem, publicKeyB64Url }`. The b64url-
+ * encoded public key is what the browser code passes as
+ * `applicationServerKey` to `pushManager.subscribe`.
+ *
+ * @example
+ *   var kp = b.webPush.generateVapidKeypair();
+ *   // Browser:
+ *   //   pushManager.subscribe({ applicationServerKey: kp.publicKeyB64Url })
+ */
+function generateVapidKeypair() {
+  var kp = nodeCrypto.generateKeyPairSync("ec", {
+    namedCurve:         "prime256v1",
+    publicKeyEncoding:  { type: "spki",  format: "pem" },
+    privateKeyEncoding: { type: "pkcs8", format: "pem" },
+  });
+  // RFC 8292 §3.2 — uncompressed point (0x04 ‖ X ‖ Y), base64url-encoded.
+  var pubKeyObj = nodeCrypto.createPublicKey(kp.publicKey);
+  var jwk = pubKeyObj.export({ format: "jwk" });
+  var raw = Buffer.concat([
+    Buffer.from([0x04]),                                                                              // allow:raw-byte-literal — uncompressed point prefix per SEC1 §2.3.3
+    Buffer.from(jwk.x, "base64url"),
+    Buffer.from(jwk.y, "base64url"),
+  ]);
+  return {
+    publicKeyPem:    kp.publicKey,
+    privateKeyPem:   kp.privateKey,
+    publicKeyB64Url: bCrypto.toBase64Url(raw),
+  };
+}
+
+/**
+ * @primitive b.webPush.buildVapidAuthHeader
+ * @signature b.webPush.buildVapidAuthHeader(opts)
+ * @since     0.10.16
+ * @status    stable
+ * @related   b.webPush.generateVapidKeypair
+ *
+ * Build the `Authorization: vapid t=<jwt>, k=<pubkey-b64url>` header
+ * value per RFC 8292 §3. The JWT claims (`aud` / `exp` / `sub`) are
+ * computed from the subscription endpoint origin + operator contact;
+ * `exp` defaults to 12 hours (RFC 8292 §2 caps at 24 hours).
+ *
+ * @opts
+ *   subscription:    { endpoint: string },              // browser-returned subscription
+ *   contact:         string,                            // mailto:... or https:... per RFC 8292 §2
+ *   privateKeyPem:   string,                            // ECDSA-P256 PEM-encoded private key
+ *   publicKeyB64Url: string,                            // public key from generateVapidKeypair()
+ *   ttlSec:          number,                            // optional, default 12h
+ *
+ * @example
+ *   var hdr = b.webPush.buildVapidAuthHeader({
+ *     subscription: { endpoint: "https://fcm.googleapis.com/wp/abc" },
+ *     contact:      "mailto:ops@example.com",
+ *     privateKeyPem:   kp.privateKeyPem,
+ *     publicKeyB64Url: kp.publicKeyB64Url,
+ *   });
+ *   // → "vapid t=<jwt>, k=<b64url>"
+ */
+function buildVapidAuthHeader(opts) {
+  opts = validateOpts.requireObject(opts, "webPush.buildVapidAuthHeader",
+    WebPushError, "web-push/bad-opts");
+  validateOpts(opts, ["subscription", "contact", "privateKeyPem",
+                       "publicKeyB64Url", "ttlSec"],
+    "webPush.buildVapidAuthHeader");
+  if (!opts.subscription || typeof opts.subscription.endpoint !== "string") {
+    throw new WebPushError("web-push/bad-subscription",
+      "buildVapidAuthHeader: opts.subscription must include a string endpoint");
+  }
+  validateOpts.requireNonEmptyString(opts.contact, "contact",
+    WebPushError, "web-push/bad-contact");
+  if (!/^(mailto:|https:)/i.test(opts.contact)) {
+    throw new WebPushError("web-push/bad-contact",
+      "buildVapidAuthHeader: contact must start with 'mailto:' or 'https:' per RFC 8292 §2");
+  }
+  validateOpts.requireNonEmptyString(opts.privateKeyPem, "privateKeyPem",
+    WebPushError, "web-push/bad-key");
+  validateOpts.requireNonEmptyString(opts.publicKeyB64Url, "publicKeyB64Url",
+    WebPushError, "web-push/bad-key");
+  validateOpts.optionalPositiveFinite(opts.ttlSec, "webPush.buildVapidAuthHeader: ttlSec",
+    WebPushError, "web-push/bad-ttl");
+  var ttlSec = opts.ttlSec || C.TIME.hours(12);
+  // Audience: origin of the subscription endpoint per RFC 8292 §2.
+  var endpointUrl;
+  try { endpointUrl = safeUrl.parse(opts.subscription.endpoint); }
+  catch (_e) {
+    throw new WebPushError("web-push/bad-endpoint",
+      "buildVapidAuthHeader: subscription.endpoint is not a parseable URL");
+  }
+  var aud = endpointUrl.origin;
+  var now = Math.floor(Date.now() / 1000);                                                            // allow:raw-time-literal — wall-clock seconds for JWT exp
+  // Inline JWT sign with ES256 — VAPID strictly mandates ECDSA-P256
+  // (RFC 8292 §3.1). The framework jwt.sign is PQC-first and refuses
+  // ES256 by design; VAPID is a wire-protocol constraint outside
+  // that policy. b.webPush owns the ES256 signing inline so the
+  // framework's broader PQC posture remains intact.
+  var header  = { typ: "JWT", alg: "ES256" };
+  var payload = { aud: aud, exp: now + ttlSec, sub: opts.contact };
+  var headerB64  = bCrypto.toBase64Url(Buffer.from(JSON.stringify(header), "utf8"));
+  var payloadB64 = bCrypto.toBase64Url(Buffer.from(JSON.stringify(payload), "utf8"));
+  var signingInput = headerB64 + "." + payloadB64;
+  var keyObj = nodeCrypto.createPrivateKey(opts.privateKeyPem);
+  if (keyObj.asymmetricKeyType !== "ec") {
+    throw new WebPushError("web-push/bad-key",
+      "buildVapidAuthHeader: privateKeyPem must be an ECDSA-P256 key (RFC 8292 §3.1)");
+  }
+  // node:crypto produces DER-encoded ECDSA signature; JWT ES256
+  // requires the raw 64-byte r||s shape. Convert.
+  var derSig = nodeCrypto.sign("sha256", Buffer.from(signingInput, "utf8"), keyObj);
+  var rawSig = _ecdsaDerToRaw(derSig, 32);                                                            // allow:raw-byte-literal — 32-byte P-256 component
+  var token = signingInput + "." + bCrypto.toBase64Url(rawSig);
+  return "vapid t=" + token + ", k=" + opts.publicKeyB64Url;
+}
+
+function _ecdsaDerToRaw(der, componentLen) {
+  // ECDSA-Sig-Value DER = SEQUENCE { r INTEGER, s INTEGER }.
+  if (der[0] !== 0x30) {                                                                              // allow:raw-byte-literal — ASN.1 SEQUENCE tag
+    throw new WebPushError("web-push/bad-sig",
+      "ECDSA signature is not a DER SEQUENCE");
+  }
+  var off = 2;
+  if (der[1] & 0x80) off = 2 + (der[1] & 0x7f);                                                       // allow:raw-byte-literal — long-form length byte
+  if (der[off] !== 0x02) throw new WebPushError("web-push/bad-sig", "missing r INTEGER");             // allow:raw-byte-literal — ASN.1 INTEGER tag
+  var rLen = der[off + 1];
+  var rStart = off + 2;
+  var r = der.slice(rStart, rStart + rLen);
+  off = rStart + rLen;
+  if (der[off] !== 0x02) throw new WebPushError("web-push/bad-sig", "missing s INTEGER");             // allow:raw-byte-literal — ASN.1 INTEGER tag
+  var sLen = der[off + 1];
+  var sStart = off + 2;
+  var s = der.slice(sStart, sStart + sLen);
+  // Trim leading zero pad (DER requires it when high bit set; JWT raw doesn't).
+  if (r.length > componentLen && r[0] === 0x00) r = r.slice(1);                                        // allow:raw-byte-literal — DER sign-bit pad
+  if (s.length > componentLen && s[0] === 0x00) s = s.slice(1);                                        // allow:raw-byte-literal — DER sign-bit pad
+  var out = Buffer.alloc(componentLen * 2);
+  r.copy(out, componentLen - r.length);
+  s.copy(out, componentLen * 2 - s.length);
+  return out;
+}
+
+/**
+ * @primitive b.webPush.encrypt
+ * @signature b.webPush.encrypt(opts)
+ * @since     0.10.16
+ * @status    stable
+ * @related   b.webPush.buildVapidAuthHeader
+ *
+ * Encrypt a Web Push message payload per RFC 8291 (Message Encryption
+ * for Web Push) using the aes128gcm content-coding per RFC 8188.
+ * Returns `{ body, headers }`:
+ *   - `body` is the Buffer to POST to the subscription endpoint
+ *   - `headers` carries the spec-required Content-Encoding +
+ *     Content-Length + TTL (caller-overridable) so operators wire
+ *     them onto the push-request alongside the VAPID Authorization.
+ *
+ * The recipient's subscription object provides `p256dh` (their ECDH
+ * P-256 public key, base64url) and `auth` (16-byte auth secret,
+ * base64url). The framework computes the ephemeral keypair, performs
+ * ECDH, runs the two-stage HKDF per RFC 8291 §3.4, and AES-128-GCM
+ * encrypts with the padded plaintext per RFC 8188 §2.
+ *
+ * @opts
+ *   subscription: { endpoint, keys: { p256dh, auth } },
+ *   payload:      Buffer|string,
+ *   ttlSec:       number,                       // default 28d (RFC 8030 §5.2)
+ *
+ * @example
+ *   var e = b.webPush.encrypt({
+ *     subscription: { endpoint: sub.endpoint, keys: { p256dh, auth } },
+ *     payload: "hello",
+ *   });
+ *   b.httpClient.request({
+ *     url: sub.endpoint, method: "POST",
+ *     headers: Object.assign({}, e.headers, {
+ *       Authorization: vapidHeader,
+ *     }),
+ *     body: e.body,
+ *   });
+ */
+function encrypt(opts) {
+  opts = validateOpts.requireObject(opts, "webPush.encrypt",
+    WebPushError, "web-push/bad-opts");
+  validateOpts(opts, ["subscription", "payload", "ttlSec"], "webPush.encrypt");
+  if (!opts.subscription || typeof opts.subscription !== "object" ||
+      !opts.subscription.keys || typeof opts.subscription.keys !== "object") {
+    throw new WebPushError("web-push/bad-subscription",
+      "encrypt: subscription must have a keys: { p256dh, auth } object");
+  }
+  validateOpts.requireNonEmptyString(opts.subscription.keys.p256dh, "p256dh",
+    WebPushError, "web-push/bad-p256dh");
+  validateOpts.requireNonEmptyString(opts.subscription.keys.auth, "auth",
+    WebPushError, "web-push/bad-auth");
+  var plaintext = Buffer.isBuffer(opts.payload) ? opts.payload
+                : typeof opts.payload === "string" ? Buffer.from(opts.payload, "utf8")
+                : null;
+  if (!plaintext) {
+    throw new WebPushError("web-push/bad-payload",
+      "encrypt: payload must be a Buffer or string");
+  }
+  // Decode the subscription's p256dh + auth.
+  var recipientPubRaw = Buffer.from(opts.subscription.keys.p256dh, "base64url");
+  if (recipientPubRaw.length !== 65 || recipientPubRaw[0] !== 0x04) {                                 // allow:raw-byte-literal — uncompressed P-256 point shape per SEC1 §2.3.3
+    throw new WebPushError("web-push/bad-p256dh",
+      "encrypt: p256dh must be a 65-byte uncompressed P-256 point");
+  }
+  var authSecret = Buffer.from(opts.subscription.keys.auth, "base64url");
+  if (authSecret.length !== 16) {                                                                     // allow:raw-byte-literal — RFC 8291 §3.2 auth_secret length
+    throw new WebPushError("web-push/bad-auth",
+      "encrypt: auth must be a 16-byte secret (got " + authSecret.length + ")");
+  }
+  // Generate ephemeral ECDH P-256 keypair.
+  var ephemeral = nodeCrypto.createECDH("prime256v1");
+  ephemeral.generateKeys();
+  var ephemeralPubRaw = ephemeral.getPublicKey();   // uncompressed 65 bytes
+  // ECDH shared secret.
+  var sharedSecret = ephemeral.computeSecret(recipientPubRaw);                                       // allow:raw-byte-literal — ECDH shared secret (32 bytes per P-256)
+  // RFC 8291 §3.4 two-stage HKDF:
+  //   PRK_key = HKDF-Extract(salt=auth_secret, IKM=ECDH_shared)
+  //   key_info = "WebPush: info\x00" || ua_public || as_public
+  //   IKM = HKDF-Expand(PRK_key, key_info, 32)
+  // Then RFC 8188 §2.2:
+  //   salt = 16 random bytes
+  //   PRK = HKDF-Extract(salt, IKM)
+  //   cek_info  = "Content-Encoding: aes128gcm\x00"
+  //   nonce_info = "Content-Encoding: nonce\x00"
+  //   CEK   = HKDF-Expand(PRK, cek_info,   16)
+  //   nonce = HKDF-Expand(PRK, nonce_info, 12)
+  var keyInfo = Buffer.concat([
+    Buffer.from("WebPush: info\x00", "utf8"),
+    recipientPubRaw,
+    ephemeralPubRaw,
+  ]);
+  var ikm = _hkdf(authSecret, sharedSecret, keyInfo, 32);                                              // allow:raw-byte-literal — 256-bit IKM
+  var salt = nodeCrypto.randomBytes(16);                                                              // allow:raw-byte-literal — RFC 8188 §2.2 16-byte salt
+  var cek   = _hkdf(salt, ikm, Buffer.from("Content-Encoding: aes128gcm\x00", "utf8"), 16);            // allow:raw-byte-literal — 128-bit AEAD key
+  var nonce = _hkdf(salt, ikm, Buffer.from("Content-Encoding: nonce\x00",     "utf8"), 12);            // allow:raw-byte-literal — 96-bit AEAD nonce
+  // RFC 8188 §2 padding: plaintext || 0x02 (delimiter for single-record).
+  // RFC 8291 mandates single-record (record_size > plaintext+padding+tag).
+  var padded = Buffer.concat([plaintext, Buffer.from([0x02])]);                                        // allow:raw-byte-literal — RFC 8188 single-record delimiter
+  var cipher = nodeCrypto.createCipheriv("aes-128-gcm", cek, nonce);
+  var ct = Buffer.concat([cipher.update(padded), cipher.final()]);
+  var tag = cipher.getAuthTag();
+  // RFC 8188 §2.1 header: salt(16) || rs(4 big-endian) || idlen(1) || keyid
+  // For RFC 8291 the keyid is the as_public (ephemeral pubkey, 65 bytes).
+  var rs = padded.length + 16;                                                                        // allow:raw-byte-literal — record size = plaintext + tag length
+  var header = Buffer.alloc(16 + 4 + 1);                                                              // allow:raw-byte-literal — salt + rs + idlen layout
+  salt.copy(header, 0);
+  header.writeUInt32BE(rs, 16);                                                                       // allow:raw-byte-literal — salt offset
+  header[20] = ephemeralPubRaw.length;                                                                // allow:raw-byte-literal — rs offset
+  var body = Buffer.concat([header, ephemeralPubRaw, ct, tag]);
+  var ttlSec = opts.ttlSec || (28 * 24 * 3600);                                                       // allow:raw-time-literal — RFC 8030 §5.2 default
+  return {
+    body:    body,
+    headers: {
+      "Content-Encoding": "aes128gcm",
+      "Content-Length":   String(body.length),
+      "TTL":              String(ttlSec),
+    },
+  };
+}
+
+function _hkdf(salt, ikm, info, length) {
+  // RFC 5869 HKDF-Extract + Expand using SHA-256 (per RFC 8291 / 8188).
+  var prk = nodeCrypto.createHmac("sha256", salt).update(ikm).digest();
+  // Expand with one-byte counter (length <= 32 always in this use).
+  var t = Buffer.concat([info, Buffer.from([0x01])]);                                                 // allow:raw-byte-literal — HKDF counter start
+  var out = nodeCrypto.createHmac("sha256", prk).update(t).digest();
+  return out.slice(0, length);
+}
+
+module.exports = {
+  generateVapidKeypair:     generateVapidKeypair,
+  buildVapidAuthHeader:     buildVapidAuthHeader,
+  encrypt:                  encrypt,
+  WebPushError:             WebPushError,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.10.14",
+  "version": "0.11.0",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",