@blamejs/core 0.10.15 → 0.11.1

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/ssrf-guard.js

@@ -717,15 +717,76 @@ function isCloudMetadata(ip) { return classify(ip) === "cloud-metadata"; }
  */
 function isReserved(ip)      { return classify(ip) === "reserved"; }
 
+/**
+ * @primitive b.ssrfGuard.checkUrlTextual
+ * @signature b.ssrfGuard.checkUrlTextual(url, opts?)
+ * @since     0.11.1
+ * @status    stable
+ * @related   b.ssrfGuard.checkUrl
+ *
+ * Text-only SSRF check for paths where the DNS lookup is
+ * intentionally deferred to a downstream resolver (e.g. an outbound
+ * HTTP proxy resolving hostnames in its own network context, or a
+ * pinned-IP transport that already knows the destination address).
+ * The hostname is checked verbatim against the cloud-metadata IP list
+ * — those addresses (`169.254.169.254`, `169.254.170.2`,
+ * `fd00:ec2::254`) are NEVER overridable, even when
+ * `allowInternal: true` and a proxy is configured. Operators short-
+ * circuiting the DNS-resolution portion of `checkUrl` MUST still call
+ * this primitive so the unconditional metadata-IP block applies at
+ * the textual layer.
+ *
+ * Returns `{ ips: null, host }` on accept. Throws `SsrfError` with
+ * `code: "ssrf-guard/blocked-cloud-metadata"` when the hostname is
+ * an IP literal matching a known cloud-metadata IP.
+ *
+ * @opts
+ *   errorClass?: typeof FrameworkError,    // operator-supplied error class for typed refusal
+ *
+ * @example
+ *   b.ssrfGuard.checkUrlTextual("http://intranet-app/api");
+ *   // → { ips: null, host: "intranet-app" }
+ *
+ *   try { b.ssrfGuard.checkUrlTextual("http://169.254.169.254/x"); }
+ *   catch (e) { e.code; }
+ *   // → "ssrf-guard/blocked-cloud-metadata"
+ */
+function checkUrlTextual(url, opts) {
+  opts = opts || {};
+  var ErrorClass = opts.errorClass || SsrfError;
+  var parsed = url instanceof URL ? url : safeUrl.parse(String(url), {
+    allowedProtocols: safeUrl.ALLOW_HTTP_ALL,
+    errorClass: ErrorClass,
+  });
+  if (!parsed.hostname) {
+    throw new ErrorClass("URL '" + parsed.toString() + "' has no hostname",
+      "ssrf-guard/no-hostname", { url: parsed.toString() });
+  }
+  var host = parsed.hostname.replace(/^\[|\]$/g, "");
+  // If the textual hostname IS an IP literal AND matches a cloud-
+  // metadata IP, refuse — even with `allowInternal: true` and a proxy.
+  // Metadata IPs leak instance credentials (AWS IMDS, GCP, Azure) and
+  // are not a configuration knob.
+  if (net.isIP(host) && CLOUD_METADATA_IPS.indexOf(host) !== -1) {
+    throw new ErrorClass(
+      "URL '" + parsed.toString() + "' resolves to cloud-metadata IP " + host +
+      " — refused unconditionally (not overridable via allowInternal + proxy)",
+      "ssrf-guard/blocked-cloud-metadata",
+      { url: parsed.toString(), ip: host, category: "cloud-metadata" });
+  }
+  return { ips: null, host: host };
+}
+
 module.exports = {
-  classify:        classify,
-  cidrContains:    cidrContains,
-  checkUrl:        checkUrl,
-  createAllowlist: createAllowlist,
-  isPrivate:       isPrivate,
-  isLoopback:      isLoopback,
-  isLinkLocal:     isLinkLocal,
-  isCloudMetadata: isCloudMetadata,
-  isReserved:      isReserved,
-  SsrfError:       SsrfError,
+  classify:         classify,
+  cidrContains:     cidrContains,
+  checkUrl:         checkUrl,
+  checkUrlTextual:  checkUrlTextual,
+  createAllowlist:  createAllowlist,
+  isPrivate:        isPrivate,
+  isLoopback:       isLoopback,
+  isLinkLocal:      isLinkLocal,
+  isCloudMetadata:  isCloudMetadata,
+  isReserved:       isReserved,
+  SsrfError:        SsrfError,
 };

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,
+};