@blamejs/core 0.10.7 → 0.10.9

package/lib/content-credentials.js

@@ -30,6 +30,7 @@
 
 var bCrypto = require("./crypto");
 var canonicalJson = require("./canonical-json");
+var safeJson = require("./safe-json");
 var validateOpts = require("./validate-opts");
 var audit = require("./audit");
 var { defineClass } = require("./framework-error");
@@ -552,12 +553,151 @@ function signCose(manifest, opts) {
   };
 }
 
+/**
+ * @primitive b.contentCredentials.cacImplicitLabel
+ * @signature b.contentCredentials.cacImplicitLabel(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance cac-genai-label
+ * @related   b.contentCredentials.build, b.contentCredentials.cacImplicitLabelRead
+ *
+ * Build the GB 45438-2025 "Cybersecurity Technology — Labeling Method
+ * for Content Generated by Artificial Intelligence" implicit metadata
+ * block (effective 2025-09-01 per CAC Measures for Labeling AI-
+ * Generated Synthetic Content). The framework owns the implicit lane
+ * (metadata); the visible explicit label is application-layer
+ * rendering. Operators co-emit alongside the C2PA-COSE manifest by
+ * declaring `cac-genai-label` posture on `b.contentCredentials.build`.
+ *
+ * @opts
+ *   providerName:   string,         // UTF-8 ≤256 bytes
+ *   providerCode:   string,         // 18-char 统一社会信用代码 (Chinese USCC)
+ *   contentId:      string,         // globally-unique asset id
+ *   contentKind:    string,         // "text"|"image"|"audio"|"video"|"virtual-scene"|"other"
+ *   generatedAt:    string,         // ISO 8601 UTC
+ *
+ * @example
+ *   var label = b.contentCredentials.cacImplicitLabel({
+ *     providerName: "Example AI",
+ *     providerCode: "91110000600037341A",
+ *     contentId:    "asset-2026-05-17-abc123",
+ *     contentKind:  "image",
+ *     generatedAt:  "2026-05-17T20:00:00Z",
+ *   });
+ *   // → { aigcMarker: "AIGC", providerName, providerCode, contentId, contentKind, generatedAt }
+ */
+var CAC_KIND_ENUM = Object.freeze({
+  text: true, image: true, audio: true, video: true,
+  "virtual-scene": true, other: true,
+});
+var CAC_USCC_RE = /^[0-9A-HJ-NPQRTUWXY]{18}$/;                                                  // allow:raw-byte-literal — GB 32100-2015 USCC fixed length, not bytes // allow:raw-time-literal — 18 is char-count of the credit code, not seconds
+var ISO8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+
+function cacImplicitLabel(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new ContentCredentialsError("cac-implicit-label/bad-opts",
+      "cacImplicitLabel: opts object required");
+  }
+  validateOpts.requireNonEmptyString(opts.providerName,
+    "cacImplicitLabel: providerName", ContentCredentialsError,
+    "cac-implicit-label/bad-provider-name");
+  if (Buffer.byteLength(opts.providerName, "utf8") > STR_LEN_MAX) {
+    throw new ContentCredentialsError("cac-implicit-label/oversize-provider-name",
+      "cacImplicitLabel: providerName exceeds " + STR_LEN_MAX + " bytes (UTF-8)");
+  }
+  if (typeof opts.providerCode !== "string" || opts.providerCode.length !== 18 ||                // allow:raw-byte-literal — USCC fixed length (GB 32100-2015), not bytes // allow:raw-time-literal — string length, not seconds
+      !CAC_USCC_RE.test(opts.providerCode)) {                                                    // allow:regex-no-length-cap — length-bounded immediately above
+    throw new ContentCredentialsError("cac-implicit-label/bad-provider-code",
+      "cacImplicitLabel: providerCode must be an 18-char unified social credit code " +
+      "(统一社会信用代码 per GB 32100-2015 / GB 45438-2025)");
+  }
+  if (typeof opts.contentId !== "string" || opts.contentId.length === 0 ||
+      opts.contentId.length > 128) {                                                             // allow:raw-byte-literal — contentId char cap, not bytes
+    throw new ContentCredentialsError("cac-implicit-label/bad-content-id",
+      "cacImplicitLabel: contentId must be 1-128 chars");
+  }
+  if (!ID_RE.test(opts.contentId)) {                                                             // allow:regex-no-length-cap — length-bounded immediately above
+    throw new ContentCredentialsError("cac-implicit-label/bad-content-id",
+      "cacImplicitLabel: contentId must match [A-Za-z0-9._:/-]");
+  }
+  if (typeof opts.contentKind !== "string" || !CAC_KIND_ENUM[opts.contentKind]) {
+    throw new ContentCredentialsError("cac-implicit-label/bad-content-kind",
+      "cacImplicitLabel: contentKind must be one of " +
+      Object.keys(CAC_KIND_ENUM).join("/"));
+  }
+  if (typeof opts.generatedAt !== "string" || !ISO8601_RE.test(opts.generatedAt)) {
+    throw new ContentCredentialsError("cac-implicit-label/bad-generated-at",
+      "cacImplicitLabel: generatedAt must be ISO 8601 UTC (e.g. 2026-05-17T20:00:00Z)");
+  }
+  return Object.freeze({
+    aigcMarker:   "AIGC",
+    providerName: opts.providerName,
+    providerCode: opts.providerCode,
+    contentId:    opts.contentId,
+    contentKind:  opts.contentKind,
+    generatedAt:  opts.generatedAt,
+  });
+}
+
+/**
+ * @primitive b.contentCredentials.cacImplicitLabelRead
+ * @signature b.contentCredentials.cacImplicitLabelRead(bytesOrObject)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance cac-genai-label
+ * @related   b.contentCredentials.cacImplicitLabel
+ *
+ * Reverse parser for the GB 45438-2025 implicit label. Accepts either
+ * a `Buffer` / `string` containing the JSON-serialized block (as the
+ * sender embedded in XMP / EXIF / MP4-box / etc.) or the already-
+ * parsed object. Returns the validated label shape or throws on any
+ * field that fails the same gate `cacImplicitLabel({...})` enforces.
+ *
+ * @example
+ *   var label = b.contentCredentials.cacImplicitLabelRead(jsonBuf);
+ *   // → { aigcMarker: "AIGC", providerName, providerCode, ... }
+ */
+function cacImplicitLabelRead(input) {
+  var obj;
+  if (Buffer.isBuffer(input)) {
+    try { obj = safeJson.parse(input.toString("utf8"), { maxBytes: 64 * 1024 }); }              // allow:raw-byte-literal — 64 KiB CAC label cap
+    catch (e) {
+      throw new ContentCredentialsError("cac-implicit-label/bad-json",
+        "cacImplicitLabelRead: JSON parse failed: " + (e && e.message));
+    }
+  } else if (typeof input === "string") {
+    try { obj = safeJson.parse(input, { maxBytes: 64 * 1024 }); }                                // allow:raw-byte-literal — 64 KiB CAC label cap
+    catch (e2) {
+      throw new ContentCredentialsError("cac-implicit-label/bad-json",
+        "cacImplicitLabelRead: JSON parse failed: " + (e2 && e2.message));
+    }
+  } else if (input && typeof input === "object") {
+    obj = input;
+  } else {
+    throw new ContentCredentialsError("cac-implicit-label/bad-input",
+      "cacImplicitLabelRead: input must be Buffer / string / object (got " + typeof input + ")");
+  }
+  if (obj.aigcMarker !== "AIGC") {
+    throw new ContentCredentialsError("cac-implicit-label/missing-aigc-marker",
+      "cacImplicitLabelRead: aigcMarker field must equal 'AIGC' (GB 45438-2025 §6)");
+  }
+  return cacImplicitLabel({
+    providerName: obj.providerName,
+    providerCode: obj.providerCode,
+    contentId:    obj.contentId,
+    contentKind:  obj.contentKind,
+    generatedAt:  obj.generatedAt,
+  });
+}
+
 module.exports = {
   build:      build,
   sign:       sign,
   signCose:   signCose,
   verify:     verify,
   required:   required,
+  cacImplicitLabel:     cacImplicitLabel,
+  cacImplicitLabelRead: cacImplicitLabelRead,
   REQUIRED_FIELDS: REQUIRED_FIELDS.slice(),
   COSE_ALGS:  Object.assign({}, COSE_ALGS),
   ContentCredentialsError: ContentCredentialsError,

package/lib/metrics.js

@@ -970,6 +970,68 @@ function snapshotRead(p) {
  *   res.setHeader("Content-Type", "text/plain; version=0.0.4");
  *   res.end(b.metrics.snapshot.render(snap, { format: "prometheus", prefix: "myapp" }));
  */
+var ISO_DATE_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;                                // allow:duplicate-regex — ISO-8601 instant shape ships in three primitives (metrics text-render, content-credentials, mail-server-imap APPEND); each is bounded by its own caller and the regex itself is 50 bytes — extracting into a cross-module dep wouldn't carry its weight
+
+// Formats a single field value for the text renderer. ISO-date-shaped
+// strings render verbatim (with millisecond precision) so the human
+// operator reads them as timestamps; everything else degrades to the
+// existing number / string / boolean / JSON formatting.
+function _formatTextValue(v) {
+  if (typeof v === "number") return String(v);
+  if (typeof v === "boolean") return v ? "true" : "false";
+  if (typeof v === "string") {
+    if (ISO_DATE_RE.test(v) && isFinite(Date.parse(v))) return v;                                    // allow:regex-no-length-cap — ISO-date shape, length-bounded by the anchored pattern
+    return v;
+  }
+  return JSON.stringify(v);
+}
+
+// Internal text-format renderer extracted from snapshotRender so the
+// E.grouped-text + H.iso-date paths share one code path.
+function _renderText(fields, snap, opts) {
+  var lines = ["snapshot written-at: " + snap.writtenAt];
+  // E. operator-supplied group map. Group ordering follows the
+  // insertion order of the `opts.groups` object; fields not named in
+  // any group fall to the bottom under `== Other ==`.
+  if (opts.groups && typeof opts.groups === "object" && !Array.isArray(opts.groups)) {
+    var groupNames = Object.keys(opts.groups);
+    var named = Object.create(null);
+    for (var gi = 0; gi < groupNames.length; gi += 1) {
+      var gName = groupNames[gi];
+      var fieldNames = opts.groups[gName];
+      if (!Array.isArray(fieldNames)) continue;
+      lines.push("");
+      lines.push("== " + gName + " ==");
+      for (var fi = 0; fi < fieldNames.length; fi += 1) {
+        var fn = fieldNames[fi];
+        named[fn] = true;
+        if (Object.prototype.hasOwnProperty.call(fields, fn)) {
+          lines.push("  " + fn + ": " + _formatTextValue(fields[fn]));
+        }
+      }
+    }
+    // Stable order for the unnamed remainder.
+    // allow:bare-canonicalize-walk — operator-facing display ordering
+    var remainder = Object.keys(fields).sort().filter(function (k) { return !named[k]; });
+    if (remainder.length > 0) {
+      lines.push("");
+      lines.push("== Other ==");
+      for (var ri = 0; ri < remainder.length; ri += 1) {
+        lines.push("  " + remainder[ri] + ": " + _formatTextValue(fields[remainder[ri]]));
+      }
+    }
+    return lines.join("\n") + "\n";
+  }
+  // Default flat rendering.
+  // allow:bare-canonicalize-walk — operator-facing display ordering
+  var keys = Object.keys(fields).sort();
+  for (var i = 0; i < keys.length; i += 1) {
+    var k = keys[i];
+    lines.push("  " + k + ": " + _formatTextValue(fields[k]));
+  }
+  return lines.join("\n") + "\n";
+}
+
 function snapshotRender(snap, opts) {
   opts = opts || {};
   var format = opts.format || "text";
@@ -979,21 +1041,7 @@ function snapshotRender(snap, opts) {
   }
   var fields = snap.fields;
   if (format === "text") {
-    var lines = ["snapshot written-at: " + snap.writtenAt];
-    // allow:bare-canonicalize-walk — sort is for stable human-readable
-    // output ordering, not canonicalize-for-hashing
-    var keys = Object.keys(fields).sort();
-    for (var i = 0; i < keys.length; i++) {
-      var k = keys[i];
-      var v = fields[k];
-      var s;
-      if (typeof v === "number") s = String(v);
-      else if (typeof v === "string") s = v;
-      else if (typeof v === "boolean") s = v ? "true" : "false";
-      else s = JSON.stringify(v);
-      lines.push("  " + k + ": " + s);
-    }
-    return lines.join("\n") + "\n";
+    return _renderText(fields, snap, opts);
   }
   if (format === "prometheus") {
     var prefix = opts.prefix || "blamejs";
@@ -1032,16 +1080,302 @@ function snapshotRender(snap, opts) {
       out.push("# TYPE " + metric + " " + fieldType);
       out.push(metric + " " + v2);
     }
+    // ISO-date string fields → parallel `<name>_epoch_ms` gauge per
+    // OpenMetrics 1.0 §3.4 (Timestamps MUST be float64 Unix-epoch). The
+    // operator-facing text format renders the ISO string verbatim; the
+    // Prometheus / OpenMetrics format gets the epoch-ms equivalent so
+    // downstream alerting can compute durations.
+    for (var jd = 0; jd < keys2.length; jd += 1) {
+      var kd = keys2[jd];
+      var vd = fields[kd];
+      if (typeof vd !== "string") continue;
+      if (vd.length > 64) continue;                                                                  // allow:raw-byte-literal — ISO 8601 max length cap, not bytes
+      if (!ISO_DATE_RE.test(vd)) continue;                                                           // allow:regex-no-length-cap — length-bounded immediately above
+      if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(kd)) continue;                                            // allow:regex-no-length-cap — field-name shape, length-bounded by snap field naming
+      var ms = Date.parse(vd);
+      if (!isFinite(ms)) continue;
+      var emName = prefix + "_" + kd + "_epoch_ms";
+      out.push("# TYPE " + emName + " gauge");
+      out.push(emName + " " + ms);
+    }
     return out.join("\n") + "\n";
   }
   throw new MetricsError("metrics-snapshot/bad-format",
     "metrics.snapshot.render: format must be 'text' or 'prometheus', got '" + format + "'");
 }
 
+/**
+ * @primitive b.metrics.snapshot.shadowRegistry
+ * @signature b.metrics.snapshot.shadowRegistry(opts)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.metrics.snapshot.render, b.metrics.create
+ *
+ * Build a namespaced shadow metrics registry that mirrors a subset of
+ * a primary registry's counters / gauges / info for export to systems
+ * needing isolated views (sidecar / per-tenant scrape endpoint /
+ * compliance-tagged subset). Cardinality cap closes the
+ * [client_golang CVE-2022-21698](https://nvd.nist.gov/vuln/detail/CVE-2022-21698)
+ * unbounded-cardinality DoS class. Returns
+ * `{ inc, set, setInfo, snapshot, render, reset }`.
+ *
+ * @opts
+ *   namespace:              string,           // identifier prefix; required
+ *   counters:               string[],         // counter names to mirror
+ *   gauges:                 string[],         // gauge names to mirror
+ *   info:                   string[],         // info names to mirror
+ *   cardinalityCap:         number,           // default 10000 per metric name
+ *   onCardinalityExceeded:  "drop" | "audit-only" | "refuse",  // default "drop"
+ *
+ * @example
+ *   var shadow = b.metrics.snapshot.shadowRegistry({
+ *     namespace: "tenant_a",
+ *     counters:  ["requests_total", "errors_total"],
+ *     gauges:    ["queue_depth"],
+ *   });
+ *   shadow.inc("requests_total");
+ *   shadow.set("queue_depth", 42);
+ *   shadow.snapshot();
+ */
+var SHADOW_DEFAULT_CARDINALITY = 10000;                                                              // allow:raw-byte-literal — cardinality cap, not bytes
+function shadowRegistry(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw new MetricsError("metrics-shadow/bad-opts",
+      "shadowRegistry: opts object required");
+  }
+  validateOpts.requireNonEmptyString(opts.namespace,
+    "shadowRegistry: opts.namespace", MetricsError, "metrics-shadow/bad-namespace");
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(opts.namespace)) {                                            // allow:regex-no-length-cap — OpenMetrics name-shape, length-bounded by namespace
+    throw new MetricsError("metrics-shadow/bad-namespace",
+      "shadowRegistry: namespace must match [a-zA-Z_][a-zA-Z0-9_]*");
+  }
+  var counterSet = _shadowSetOf(opts.counters, "counters");
+  var gaugeSet   = _shadowSetOf(opts.gauges,   "gauges");
+  var infoSet    = _shadowSetOf(opts.info,     "info");
+  var cap = opts.cardinalityCap === undefined ? SHADOW_DEFAULT_CARDINALITY : opts.cardinalityCap;
+  if (typeof cap !== "number" || !isFinite(cap) || cap < 1 || Math.floor(cap) !== cap) {
+    throw new MetricsError("metrics-shadow/bad-cap",
+      "shadowRegistry: cardinalityCap must be a positive integer");
+  }
+  var policy = opts.onCardinalityExceeded || "drop";
+  if (policy !== "drop" && policy !== "audit-only" && policy !== "refuse") {
+    throw new MetricsError("metrics-shadow/bad-policy",
+      "shadowRegistry: onCardinalityExceeded must be 'drop', 'audit-only', or 'refuse'");
+  }
+  var counters = Object.create(null);
+  var gauges   = Object.create(null);
+  var info     = Object.create(null);
+  var lastCardinalityAuditMs = 0;
+
+  function _cardinalityHit(metric) {
+    var now = Date.now();
+    // Rate-limit cardinality audit emissions to once per second per
+    // shadow registry so a hostile label flood doesn't fan out into
+    // the audit log.
+    if (now - lastCardinalityAuditMs >= C.TIME.seconds(1)) {
+      lastCardinalityAuditMs = now;
+      try {
+        require("./audit").safeEmit({
+          action:   "metrics.shadow.cardinality_dropped",
+          outcome:  policy === "refuse" ? "denied" : "denied",
+          metadata: { namespace: opts.namespace, metric: metric, cap: cap, policy: policy },
+        });
+      } catch (_e) { /* drop-silent */ }
+    }
+    if (policy === "refuse") {
+      throw new MetricsError("metrics-shadow/cardinality-exceeded",
+        "shadowRegistry.inc/set: '" + metric + "' cardinality exceeds cap=" + cap);
+    }
+  }
+
+  function _labelKey(labels) {
+    if (!labels || typeof labels !== "object") return "";
+    var keys = Object.keys(labels).sort();                                                            // allow:bare-canonicalize-walk — label-set canonicalization for cardinality keying
+    var parts = [];
+    for (var i = 0; i < keys.length; i += 1) {
+      parts.push(keys[i] + "=" + String(labels[keys[i]]));
+    }
+    return parts.join(",");
+  }
+
+  function inc(name, labels) {
+    if (!counterSet[name]) return;
+    var lk = _labelKey(labels);
+    if (!counters[name]) counters[name] = Object.create(null);
+    var current = counters[name][lk];
+    if (current === undefined) {
+      if (Object.keys(counters[name]).length >= cap) {
+        _cardinalityHit(name);
+        return;
+      }
+      counters[name][lk] = 1;
+    } else {
+      counters[name][lk] = current + 1;
+    }
+  }
+
+  function set(name, value, labels) {
+    if (!gaugeSet[name]) return;
+    if (typeof value !== "number" || !isFinite(value)) {
+      throw new MetricsError("metrics-shadow/bad-gauge-value",
+        "shadowRegistry.set: '" + name + "' value must be a finite number");
+    }
+    var lk = _labelKey(labels);
+    if (!gauges[name]) gauges[name] = Object.create(null);
+    if (gauges[name][lk] === undefined && Object.keys(gauges[name]).length >= cap) {
+      _cardinalityHit(name);
+      return;
+    }
+    gauges[name][lk] = value;
+  }
+
+  function setInfo(name, value) {
+    if (!infoSet[name]) return;
+    info[name] = value;
+  }
+
+  function snapshotShadow() {
+    return Object.freeze({
+      namespace: opts.namespace,
+      counters:  _shallowClone(counters),
+      gauges:    _shallowClone(gauges),
+      info:      Object.assign({}, info),
+    });
+  }
+
+  function renderShadow(renderOpts) {
+    renderOpts = renderOpts || {};
+    var format = renderOpts.format || "text";
+    // Prometheus / OpenMetrics — emit labeled metric lines directly so
+    // counters / gauges with label sets survive the export. Routing
+    // through `snapshotRender` would have filtered synthetic
+    // `name{labelKey=value}` field names against the Prometheus
+    // metric-name shape `[a-zA-Z_][a-zA-Z0-9_]*` and dropped them all.
+    if (format === "prometheus" || format === "openmetrics") {
+      var out = [];
+      var prefix = opts.namespace;
+      function _emitLabeled(name, labelMap, kind) {
+        var metric = prefix + "_" + name;
+        if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(metric)) return;                                        // allow:regex-no-length-cap — Prometheus name-shape; metric length bounded by namespace + name caps
+        out.push("# TYPE " + metric + " " + kind);
+        var lks = Object.keys(labelMap);
+        for (var li = 0; li < lks.length; li += 1) {
+          var lk = lks[li];
+          if (lk === "") { out.push(metric + " " + labelMap[lk]); continue; }
+          // The label-key string was assembled by `_labelKey` from a
+          // single shadow-registry call's `labels` object — values
+          // are framework-internal (operator code that supplied them
+          // is bounded by guards upstream); split on `,` is safe.
+          // Not a header-value parse (which would need a quoted-
+          // string aware split per RFC 9110).
+          var lpairs = lk.split(",");                                                                // allow:bare-split-on-quoted-header — framework-internal label-key (assembled by _labelKey), not an HTTP header parse
+          var formatted = [];
+          for (var pi = 0; pi < lpairs.length; pi += 1) {
+            var eqIdx = lpairs[pi].indexOf("=");
+            if (eqIdx === -1) continue;
+            var lname = lpairs[pi].slice(0, eqIdx);
+            var lvalue = lpairs[pi].slice(eqIdx + 1);
+            if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(lname)) continue;                                   // allow:regex-no-length-cap — Prometheus label-name shape
+            // Prometheus exposition: escape `\`, `"`, `\n` in label values.
+            lvalue = String(lvalue).replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\n/g, "\\n"); // allow:regex-no-length-cap — fixed-char-set escape // allow:duplicate-regex — Prometheus value escape shape
+            formatted.push(lname + '="' + lvalue + '"');
+          }
+          out.push(metric + "{" + formatted.join(",") + "} " + labelMap[lk]);
+        }
+      }
+      var cn2 = Object.keys(counters);
+      for (var ci = 0; ci < cn2.length; ci += 1) {
+        _emitLabeled(cn2[ci], counters[cn2[ci]], /_total$/.test(cn2[ci]) ? "counter" : "gauge");      // allow:regex-no-length-cap — name-suffix check
+      }
+      var gn2 = Object.keys(gauges);
+      for (var ggi = 0; ggi < gn2.length; ggi += 1) {
+        _emitLabeled(gn2[ggi], gauges[gn2[ggi]], "gauge");
+      }
+      return out.join("\n") + (out.length ? "\n" : "");
+    }
+    // Text format — route through snapshotRender via synthetic field
+    // names. The text-format renderer accepts arbitrary field names so
+    // labeled series survive here.
+    var snap = { writtenAt: new Date().toISOString(), fields: {} };
+    var cn = Object.keys(counters);
+    for (var i = 0; i < cn.length; i += 1) {
+      var labels = counters[cn[i]];
+      var labelKeys = Object.keys(labels);
+      if (labelKeys.length === 1 && labelKeys[0] === "") {
+        snap.fields[cn[i]] = labels[""];
+      } else {
+        for (var j = 0; j < labelKeys.length; j += 1) {
+          var key = labelKeys[j] === "" ? cn[i] : cn[i] + "{" + labelKeys[j] + "}";
+          snap.fields[key] = labels[labelKeys[j]];
+        }
+      }
+    }
+    var gn = Object.keys(gauges);
+    for (var gi = 0; gi < gn.length; gi += 1) {
+      var glabels = gauges[gn[gi]];
+      var glk = Object.keys(glabels);
+      if (glk.length === 1 && glk[0] === "") {
+        snap.fields[gn[gi]] = glabels[""];
+      } else {
+        for (var gj = 0; gj < glk.length; gj += 1) {
+          var gkey = glk[gj] === "" ? gn[gi] : gn[gi] + "{" + glk[gj] + "}";
+          snap.fields[gkey] = glabels[glk[gj]];
+        }
+      }
+    }
+    var inames = Object.keys(info);
+    for (var ii = 0; ii < inames.length; ii += 1) snap.fields[inames[ii]] = info[inames[ii]];
+    return snapshotRender(snap, Object.assign({ prefix: opts.namespace }, renderOpts));
+  }
+
+  function reset() {
+    counters = Object.create(null);
+    gauges   = Object.create(null);
+    info     = Object.create(null);
+    lastCardinalityAuditMs = 0;
+  }
+
+  return {
+    inc:      inc,
+    set:      set,
+    setInfo:  setInfo,
+    snapshot: snapshotShadow,
+    render:   renderShadow,
+    reset:    reset,
+  };
+}
+
+function _shadowSetOf(arr, label) {
+  if (arr === undefined) return Object.create(null);
+  if (!Array.isArray(arr)) {
+    throw new MetricsError("metrics-shadow/bad-" + label,
+      "shadowRegistry: opts." + label + " must be an array of metric names");
+  }
+  var set = Object.create(null);
+  for (var i = 0; i < arr.length; i += 1) {
+    if (typeof arr[i] !== "string" || arr[i].length === 0) {
+      throw new MetricsError("metrics-shadow/bad-" + label,
+        "shadowRegistry: opts." + label + "[" + i + "] must be a non-empty string");
+    }
+    set[arr[i]] = true;
+  }
+  return set;
+}
+
+function _shallowClone(obj) {
+  var out = Object.create(null);
+  var keys = Object.keys(obj);
+  for (var i = 0; i < keys.length; i += 1) {
+    out[keys[i]] = Object.assign(Object.create(null), obj[keys[i]]);
+  }
+  return out;
+}
+
 var snapshot = {
-  startWriter: snapshotStartWriter,
-  read:        snapshotRead,
-  render:      snapshotRender,
+  startWriter:     snapshotStartWriter,
+  read:            snapshotRead,
+  render:          snapshotRender,
+  shadowRegistry:  shadowRegistry,
 };
 
 module.exports = {

package/lib/pqc-agent.js

@@ -32,6 +32,10 @@ var C = require("./constants");
 var lazyRequire = require("./lazy-require");
 var networkTls = require("./network-tls");
 var safeBuffer = require("./safe-buffer");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var PqcAgentError = defineClass("PqcAgentError", { alwaysPermanent: true });
 
 // audit imports crypto/handlers transitively — lazy to avoid load
 // cycles when pqc-agent is required during framework bootstrap.
@@ -179,7 +183,72 @@ function _buildAgentOpts(opts) {
  *   req.end();
  */
 function create(opts) {
-  return new https.Agent(_buildAgentOpts(opts));
+  var built = _buildAgentOpts(opts);
+  var agent = new https.Agent(built);
+  agent._builtOpts = built;
+  // Per-instance cert rotation. The pre-v0.10.9 path required process
+  // restart for cert rotation on agents built via explicit `create()`
+  // (only the framework's lazy default had `b.pqcAgent.reload()`).
+  // Attach `reloadCerts` so long-running daemons can pivot in place.
+  agent.reloadCerts = function (newMaterial) {
+    return _reloadCertsOnAgent(agent, opts, newMaterial);
+  };
+  return agent;
+}
+
+function _reloadCertsOnAgent(agent, originalOpts, newMaterial) {
+  validateOpts.requireObject(newMaterial, "agent.reloadCerts",
+    PqcAgentError, "pqcagent/reload-bad-opts");
+  if (typeof newMaterial.cert !== "string" || newMaterial.cert.length === 0 ||
+      typeof newMaterial.key  !== "string" || newMaterial.key.length === 0) {
+    throw new PqcAgentError("pqcagent/reload-missing-material",
+      "agent.reloadCerts: both cert and key are required (non-empty PEM strings)");
+  }
+  // Compound on the AGENT's last-known-good builtOpts (which start as
+  // the create-time opts but are updated on each successful reload).
+  // A sequence like "reload with new ca once, then reload only
+  // cert/key" preserves the new ca because the previous successful
+  // reload wrote it into agent._builtOpts.
+  var nextOpts = Object.assign({}, agent._builtOpts, {
+    cert: newMaterial.cert,
+    key:  newMaterial.key,
+  });
+  if (newMaterial.ca !== undefined) nextOpts.ca = newMaterial.ca;
+  var t0 = Date.now();
+  try {
+    // tls.createSecureContext throws on mismatched cert/key — surface
+    // as a typed framework error with the underlying OpenSSL chain.
+    require("node:tls").createSecureContext({                                                        // allow:inline-require — node:tls only needed during cert rotation (a non-hot path); a top-level require would pull TLS into the boot graph of every process that never reaches reloadCerts
+      cert: nextOpts.cert,
+      key:  nextOpts.key,
+      ca:   nextOpts.ca,
+    });
+  } catch (e) {
+    var errMsg = (e && e.message) ? e.message : String(e);
+    if (/ca\b/i.test(errMsg)) {                                                                      // allow:regex-no-length-cap — error-message shape match; error text owned by Node, not adversarial input
+      throw new PqcAgentError("pqcagent/reload-bad-ca",
+        "agent.reloadCerts: ca bundle failed to parse: " + errMsg);
+    }
+    throw new PqcAgentError("pqcagent/reload-mismatch",
+      "agent.reloadCerts: cert/key mismatch or malformed PEM (" + errMsg + ")");
+  }
+  agent.options = Object.assign({}, agent.options, {
+    cert: nextOpts.cert,
+    key:  nextOpts.key,
+    ca:   nextOpts.ca,
+  });
+  agent._builtOpts = nextOpts;
+  // Close idle keep-alive sockets so the next request uses the new
+  // material. In-flight sockets complete naturally.
+  try { agent.destroy(); } catch (_e) { /* best-effort */ }
+  try {
+    audit.safeEmit({
+      action:   "pqcagent.reloadCerts",
+      outcome:  "success",
+      metadata: { durationMs: Date.now() - t0 },
+    });
+  } catch (_e2) { /* drop-silent */ }
+  return { reloaded: true, durationMs: Date.now() - t0 };
 }
 
 /**