@blamejs/core 0.10.7 → 0.10.9

package/lib/ai-model-manifest.js

@@ -0,0 +1,363 @@
+"use strict";
+/**
+ * @module b.ai.modelManifest
+ * @nav    AI
+ * @title  AI Model Manifest (AIBOM)
+ *
+ * @intro
+ *   CycloneDX 1.6 ML-BOM emitter for AI bills of materials. EU AI Act
+ *   Art. 11 + Annex IV require technical documentation for high-risk
+ *   AI systems; the EU CRA (Regulation (EU) 2024/2847) transposition
+ *   deadline (2027-12-11) extends SBOM-style documentation to AI
+ *   components in products with digital elements. ML-BOM extends the
+ *   CycloneDX 1.5 machine-learning component type with model-card,
+ *   dataset, hyperparameter, formulation, and external-service
+ *   sections per the OWASP CycloneDX Authoritative Guide to AI/ML-BOM
+ *   and CycloneDX spec issue #702 (EU CRA alignment).
+ *
+ *   Two paths:
+ *   - `build({...})` constructs a 1.6-conformant JSON BOM in memory.
+ *   - `sign(bom, { privateKeyPem })` signs the canonical-JSON-1785
+ *     representation with the operator's signing key (ML-DSA-87 by
+ *     default per project hard-rule 2). `verify(envelope, publicKeyPem)`
+ *     re-canonicalizes and checks before trusting any field.
+ *
+ *   Self-validation: `build` rejects BOMs missing CycloneDX 1.6
+ *   required fields (`bomFormat`, `specVersion`, `metadata.timestamp`,
+ *   `metadata.component` when shipping a model). Catches malformed
+ *   inputs at emit time, not at downstream validator.
+ *
+ * @card
+ *   CycloneDX 1.6 AI bill of materials (AIBOM) — model cards, datasets, hyperparameters, training workflows. ML-DSA-87 signed.
+ */
+
+var bCrypto = require("./crypto");
+var canonicalJson = require("./canonical-json");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+var audit = require("./audit");
+
+var AiModelManifestError = defineClass("AiModelManifestError", { alwaysPermanent: true });
+
+var SPEC_VERSION = "1.6";
+var BOM_FORMAT = "CycloneDX";
+var COMPONENT_TYPE_MODEL = "machine-learning-model";
+var VALID_DATA_TYPES = Object.freeze({
+  "source-code": true, configuration: true, dataset: true, definition: true,
+  "device-driver": true, documentation: true, evidence: true, executable: true,
+  file: true, firmware: true, framework: true, library: true,
+  "machine-learning-model": true, manifest: true, "operating-system": true,
+  patch: true, platform: true, "test-case": true,
+});
+var ISO8601_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
+var BOM_REF_RE = /^[A-Za-z0-9._:/+-]{1,256}$/;                                                  // allow:raw-byte-literal — CycloneDX bom-ref string-length cap, not bytes
+
+function _requireString(obj, key, ownerName) {
+  if (typeof obj[key] !== "string" || obj[key].length === 0) {
+    throw new AiModelManifestError("aibom/bad-" + key,
+      ownerName + ": " + key + " must be a non-empty string");
+  }
+}
+
+function _validateModelComponent(c) {
+  if (!c || typeof c !== "object") {
+    throw new AiModelManifestError("aibom/bad-model-component",
+      "build: opts.model must be an object");
+  }
+  _requireString(c, "name", "build.model");
+  _requireString(c, "version", "build.model");
+  if (c["bom-ref"] !== undefined) {
+    if (typeof c["bom-ref"] !== "string" || c["bom-ref"].length > 256) {                         // allow:raw-byte-literal — bom-ref string-length cap, not bytes
+      throw new AiModelManifestError("aibom/bad-bom-ref",
+        "build.model: bom-ref must be a string of length 1-256");
+    }
+    if (!BOM_REF_RE.test(c["bom-ref"])) {                                                        // allow:regex-no-length-cap — length-bounded immediately above
+      throw new AiModelManifestError("aibom/bad-bom-ref",
+        "build.model: bom-ref must match [A-Za-z0-9._:/+-]");
+    }
+  }
+  // modelCard is CycloneDX 1.6 §4.5.5; required for ML components when
+  // the operator wants downstream tooling (e.g. Dependency-Track) to
+  // surface the card. We do not REQUIRE the card here (some operators
+  // ship a hash-only ML-BOM by policy) but we do validate shape when
+  // present.
+  if (c.modelCard !== undefined) {
+    if (typeof c.modelCard !== "object") {
+      throw new AiModelManifestError("aibom/bad-model-card",
+        "build.model.modelCard: must be an object");
+    }
+  }
+}
+
+function _validateDataComponent(d, idx) {
+  if (!d || typeof d !== "object") {
+    throw new AiModelManifestError("aibom/bad-dataset",
+      "build.datasets[" + idx + "]: must be an object");
+  }
+  _requireString(d, "name", "build.datasets[" + idx + "]");
+  if (d.type !== undefined && !VALID_DATA_TYPES[d.type]) {
+    throw new AiModelManifestError("aibom/bad-dataset-type",
+      "build.datasets[" + idx + "].type '" + d.type + "' not in CycloneDX 1.6 data-type vocabulary");
+  }
+}
+
+/**
+ * @primitive b.ai.modelManifest.build
+ * @signature b.ai.modelManifest.build(opts)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance eu-ai-act-art-11, nist-ai-600-1, iso-42001, iso-23894
+ * @related   b.ai.modelManifest.sign, b.ai.modelManifest.verify
+ *
+ * Build a CycloneDX 1.6 ML-BOM JSON document for the supplied model
+ * + datasets + hyperparameters + formulation + external services.
+ * Returns a frozen plain object ready for `sign({...})` or direct
+ * serialization. Validates against the spec's required-field set at
+ * emit time (`bomFormat` / `specVersion` / `metadata.timestamp` /
+ * `metadata.component`) plus the ML-BOM-specific shape (model
+ * component type, dataset type vocabulary, bom-ref grammar).
+ *
+ * @opts
+ *   model:           object,        // { name, version, license?, bom-ref?, modelCard? }
+ *   datasets:        object[],      // [{ name, type?, contents?, classification?, ... }]
+ *   hyperparameters: object,        // kv pairs → properties[]
+ *   formulation:     object[],      // [{ ref, components, workflows }]
+ *   services:        object[],      // [{ name, endpoints, authenticated }]
+ *   tool:            object,        // tool metadata; defaults to blamejs core
+ *   timestamp:       string,        // ISO 8601 UTC; defaults to now
+ *   serialNumber:    string,        // urn:uuid:...; defaults to fresh UUIDv4
+ *
+ * @example
+ *   var bom = b.ai.modelManifest.build({
+ *     model: { name: "acme-classifier", version: "1.2.3" },
+ *     datasets: [{ name: "training-2026", type: "dataset" }],
+ *   });
+ *   bom.bomFormat;   // → "CycloneDX"
+ *   bom.specVersion; // → "1.6"
+ */
+function build(opts) {
+  opts = opts || {};
+  _validateModelComponent(opts.model);
+  if (opts.datasets !== undefined) {
+    if (!Array.isArray(opts.datasets)) {
+      throw new AiModelManifestError("aibom/bad-datasets",
+        "build: opts.datasets must be an array");
+    }
+    for (var i = 0; i < opts.datasets.length; i += 1) _validateDataComponent(opts.datasets[i], i);
+  }
+  var timestamp = opts.timestamp || new Date().toISOString();
+  if (!ISO8601_RE.test(timestamp)) {
+    throw new AiModelManifestError("aibom/bad-timestamp",
+      "build: timestamp must be ISO 8601 UTC (e.g. 2026-05-17T20:00:00Z)");
+  }
+  var serialNumber = opts.serialNumber || _uuidUrn();
+  if (typeof serialNumber !== "string" || serialNumber.indexOf("urn:uuid:") !== 0) {
+    throw new AiModelManifestError("aibom/bad-serial-number",
+      "build: serialNumber must start with `urn:uuid:`");
+  }
+
+  var primaryComponent = Object.assign({
+    type:    COMPONENT_TYPE_MODEL,
+    "bom-ref": opts.model["bom-ref"] || ("model:" + opts.model.name + "@" + opts.model.version),
+  }, opts.model);
+  primaryComponent.type = COMPONENT_TYPE_MODEL;
+
+  var components = [];
+  // Per CycloneDX 1.6 §4.7: the primary component goes in
+  // metadata.component, NOT in components[]. Datasets, hyperparameter-
+  // bearing components, and external dependencies live in components[].
+  if (Array.isArray(opts.datasets)) {
+    for (var di = 0; di < opts.datasets.length; di += 1) {
+      var ds = opts.datasets[di];
+      components.push(Object.assign({
+        type: ds.type || "data",
+        "bom-ref": ds["bom-ref"] || ("dataset:" + ds.name),
+      }, ds));
+    }
+  }
+
+  // Hyperparameters → CycloneDX properties[] kv pairs per spec
+  // issue #702 EU CRA alignment.
+  var properties = [];
+  if (opts.hyperparameters && typeof opts.hyperparameters === "object") {
+    var keys = Object.keys(opts.hyperparameters);
+    for (var k = 0; k < keys.length; k += 1) {
+      var key = keys[k];
+      properties.push({ name: "ai:hyperparameter:" + key,
+                        value: String(opts.hyperparameters[key]) });
+    }
+  }
+
+  var bom = {
+    bomFormat:     BOM_FORMAT,
+    specVersion:   SPEC_VERSION,
+    serialNumber:  serialNumber,
+    version:       1,
+    metadata: {
+      timestamp: timestamp,
+      tools: [Object.assign({
+        vendor:  "blamejs",
+        name:    "@blamejs/core",
+        version: _frameworkVersion(),
+      }, opts.tool || {})],
+      component: primaryComponent,
+    },
+  };
+  if (components.length > 0) bom.components = components;
+  if (properties.length > 0) bom.properties = properties;
+  if (Array.isArray(opts.formulation) && opts.formulation.length > 0) {
+    bom.formulation = opts.formulation;
+  }
+  if (Array.isArray(opts.services) && opts.services.length > 0) {
+    bom.services = opts.services;
+  }
+  if (Array.isArray(opts.dependencies) && opts.dependencies.length > 0) {
+    bom.dependencies = opts.dependencies;
+  }
+  return Object.freeze(bom);
+}
+
+/**
+ * @primitive b.ai.modelManifest.sign
+ * @signature b.ai.modelManifest.sign(bom, opts)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance eu-ai-act-art-11
+ * @related   b.ai.modelManifest.build, b.ai.modelManifest.verify
+ *
+ * Sign an AIBOM produced by `build({...})`. Signature is over the
+ * canonical-JSON-1785 representation of the BOM (deterministic byte
+ * stream regardless of object-key insertion order); the operator's
+ * `privateKeyPem` selects the signing alg (ML-DSA-87 by default per
+ * the project's PQC-first crypto rule). Returns `{ bom, signature }`
+ * where `signature` is base64-encoded.
+ *
+ * @opts
+ *   privateKeyPem:  string,        // PEM-encoded private key
+ *   audit:          boolean,        // default true
+ *
+ * @example
+ *   var pair = b.crypto.generateSigningKeyPair("ml-dsa-87");
+ *   var bom = b.ai.modelManifest.build({ model: { name: "x", version: "1" }});
+ *   var env = b.ai.modelManifest.sign(bom, { privateKeyPem: pair.privateKey });
+ *   typeof env.signature; // → "string"
+ */
+function sign(bom, opts) {
+  opts = opts || {};
+  if (!bom || typeof bom !== "object") {
+    throw new AiModelManifestError("aibom/bad-bom",
+      "sign: bom must be an object produced by build({...})");
+  }
+  validateOpts.requireNonEmptyString(opts.privateKeyPem,
+    "sign: opts.privateKeyPem", AiModelManifestError, "aibom/bad-key");
+  var canonical = canonicalJson.stringify(bom);
+  var signature = bCrypto.sign(Buffer.from(canonical, "utf8"), opts.privateKeyPem);
+  if (opts.audit !== false) {
+    audit.safeEmit({
+      action:   "aibom.signed",
+      outcome:  "success",
+      metadata: {
+        modelName:    bom.metadata && bom.metadata.component && bom.metadata.component.name,
+        modelVersion: bom.metadata && bom.metadata.component && bom.metadata.component.version,
+        serialNumber: bom.serialNumber,
+      },
+    });
+  }
+  return Object.freeze({
+    bom:       bom,
+    signature: signature.toString("base64"),
+  });
+}
+
+/**
+ * @primitive b.ai.modelManifest.verify
+ * @signature b.ai.modelManifest.verify(envelope, publicKeyPem, opts)
+ * @since     0.10.8
+ * @status    stable
+ * @compliance eu-ai-act-art-11
+ * @related   b.ai.modelManifest.sign
+ *
+ * Verify an envelope produced by `sign(bom, {...})`. Re-canonicalizes
+ * the BOM with `canonicalJson.stringify` (NEVER trusts an embedded
+ * "signedBytes" field — defends the CVE-2025-29774 / CVE-2025-29775
+ * xml-crypto-style signature-substitution class) and checks the
+ * signature with `b.crypto.verify` against the supplied public-key
+ * PEM. Returns `{ valid, bom, reason }`; never throws.
+ *
+ * @opts
+ *   audit:           boolean,        // default true
+ *
+ * @example
+ *   var result = b.ai.modelManifest.verify(envelope, pair.publicKey);
+ *   if (!result.valid) console.log(result.reason);
+ */
+function verify(envelope, publicKeyPem, opts) {
+  opts = opts || {};
+  if (!envelope || typeof envelope !== "object" || !envelope.bom || !envelope.signature) {
+    return { valid: false, bom: null, reason: "envelope-shape" };
+  }
+  if (typeof publicKeyPem !== "string" || publicKeyPem.length === 0) {
+    return { valid: false, bom: null, reason: "public-key-required" };
+  }
+  if (envelope.bom.specVersion !== SPEC_VERSION || envelope.bom.bomFormat !== BOM_FORMAT) {
+    return { valid: false, bom: null, reason: "bom-spec-mismatch" };
+  }
+  var canonical = canonicalJson.stringify(envelope.bom);
+  var sigBuf;
+  try { sigBuf = Buffer.from(envelope.signature, "base64"); }
+  catch (_e) { return { valid: false, bom: null, reason: "signature-base64-bad" }; }
+  // `b.crypto.verify` can throw on malformed public-key PEM (Node's
+  // crypto layer surfaces `DECODER routines::unsupported` and similar).
+  // The documented contract here is `{ valid, bom, reason }` with no
+  // throws — wrap so a hostile / mistyped key returns a structured
+  // verdict instead of crashing the request path.
+  var ok;
+  try { ok = bCrypto.verify(Buffer.from(canonical, "utf8"), sigBuf, publicKeyPem); }
+  catch (_e2) { return { valid: false, bom: null, reason: "public-key-malformed" }; }
+  if (!ok) return { valid: false, bom: null, reason: "signature-invalid" };
+  if (opts.audit !== false) {
+    audit.safeEmit({
+      action:   "aibom.verified",
+      outcome:  "success",
+      metadata: {
+        modelName:    envelope.bom.metadata && envelope.bom.metadata.component &&
+                      envelope.bom.metadata.component.name,
+        serialNumber: envelope.bom.serialNumber,
+      },
+    });
+  }
+  return { valid: true, bom: envelope.bom, reason: null };
+}
+
+// UUIDv4 via the framework's CSPRNG path. Used for `serialNumber`
+// defaults — operators may supply their own for cross-build stability.
+function _uuidUrn() {
+  var b = bCrypto.generateBytes(16);                                                            // allow:raw-byte-literal — RFC 9562 §4.1 UUIDv4 is a 16-byte (128-bit) primitive
+  b[6] = (b[6] & 0x0f) | 0x40;                                                                  // allow:raw-byte-literal — UUIDv4 version nibble (RFC 9562 §4.4)
+  b[8] = (b[8] & 0x3f) | 0x80;                                                                  // allow:raw-byte-literal — UUIDv4 variant nibble (RFC 9562 §4.4)
+  var h = b.toString("hex");
+  return "urn:uuid:" + h.slice(0, 8) + "-" + h.slice(8, 12) + "-" +                              // allow:raw-byte-literal — RFC 9562 §4 UUID text representation hex offsets (8-4-4-4-12)
+         h.slice(12, 16) + "-" + h.slice(16, 20) + "-" + h.slice(20);                            // allow:raw-byte-literal — RFC 9562 §4 UUID hex offsets
+}
+
+// package.json read lives behind the call to dodge a circular-load
+// chain: framework boot pulls index.js → ai-model-manifest → audit →
+// db → framework-error → constants → package.json. Reading
+// package.json at boot time would close the cycle. The lazy read is
+// idempotent and the result is cached on first call.
+var _cachedVersion = null;
+function _frameworkVersion() {
+  if (_cachedVersion) return _cachedVersion;
+  try { _cachedVersion = require("../package.json").version; }                                  // allow:inline-require — lazy package-version read to avoid boot-time circular load
+  catch (_e) { _cachedVersion = "0.0.0"; }
+  return _cachedVersion;
+}
+
+module.exports = {
+  build:               build,
+  sign:                sign,
+  verify:              verify,
+  SPEC_VERSION:        SPEC_VERSION,
+  BOM_FORMAT:          BOM_FORMAT,
+  AiModelManifestError: AiModelManifestError,
+};

package/lib/atomic-file.js

@@ -279,6 +279,88 @@ function pathTimestamp(date) {
   return d.toISOString().replace(/[:.]/g, "-");
 }
 
+// Generic [A-Za-z0-9_-]+ identifier shape used by conflictPath tag /
+// suffix validation. The pattern collides with similar shapes in
+// safe-buffer / redact / etc.; keeping the regex literal local to
+// atomic-file rather than pulling in a cross-module dependency for a
+// 30-byte regex keeps this file's lazy-load chain short.
+var IDENT_RE = /^[A-Za-z0-9_-]+$/;                                                              // allow:regex-no-length-cap — caller bounds length before .test() // allow:duplicate-regex — generic [A-Za-z0-9_-]+ identifier shape; extracting a one-line regex into a cross-module dependency would lengthen atomic-file's boot-time lazy chain for no behavioral win
+
+/**
+ * @primitive b.atomicFile.conflictPath
+ * @signature b.atomicFile.conflictPath(originalPath, opts?)
+ * @since     0.10.8
+ * @status    stable
+ * @related   b.atomicFile.pathTimestamp, b.atomicFile.write
+ *
+ * Build a filesystem-portable conflict-suffix path next to
+ * `originalPath`, e.g. `notes.md` → `notes.conflict-2026-05-17T19-30-00Z.md`.
+ * Drop-in name for last-write-wins reconciliation in sync / backup /
+ * dual-control workflows. Preserves the original extension. Inserts a
+ * caller-supplied `tag` (default `conflict`) between the basename and
+ * the timestamp. The timestamp uses `pathTimestamp` so the result is
+ * portable across Windows (no `:` / `.`), macOS, and Linux. Same-second
+ * collision handling: pass `opts.suffix` (e.g. a per-row crypto-random
+ * hex) when multiple conflicts may land in the same second; otherwise
+ * the timestamp's millisecond field disambiguates.
+ *
+ * @opts
+ *   tag:       string,     // default "conflict"; sandwiched between basename and timestamp
+ *   timestamp: Date,       // default `new Date()`
+ *   suffix:    string,     // optional extra disambiguator appended after timestamp
+ *
+ * @example
+ *   var p = b.atomicFile.conflictPath("/srv/notes.md");
+ *   // → "/srv/notes.conflict-2026-05-17T20-30-00-123Z.md"
+ *
+ *   var withSuffix = b.atomicFile.conflictPath("/srv/notes.md", {
+ *     tag: "merge", suffix: "abc123",
+ *   });
+ *   // → "/srv/notes.merge-2026-05-17T20-30-00-123Z.abc123.md"
+ */
+function conflictPath(originalPath, opts) {
+  if (typeof originalPath !== "string" || originalPath.length === 0) {
+    throw new TypeError("b.atomicFile.conflictPath: originalPath must be a non-empty string");
+  }
+  opts = opts || {};
+  var tag = typeof opts.tag === "string" && opts.tag.length > 0 ? opts.tag : "conflict";
+  if (typeof tag !== "string" || tag.length === 0 || tag.length > 64) {                          // allow:raw-byte-literal — tag length cap, not bytes
+    throw new TypeError("b.atomicFile.conflictPath: tag must be a 1-64 char string");
+  }
+  if (!IDENT_RE.test(tag)) {                                                                     // allow:regex-no-length-cap — length-bounded immediately above
+    throw new TypeError("b.atomicFile.conflictPath: tag must match [A-Za-z0-9_-]+");
+  }
+  var stamp = pathTimestamp(opts.timestamp);
+  var suffix = "";
+  if (opts.suffix !== undefined) {
+    if (typeof opts.suffix !== "string" || opts.suffix.length === 0 ||
+        opts.suffix.length > 64) {                                                               // allow:raw-byte-literal — suffix length cap, not bytes
+      throw new TypeError("b.atomicFile.conflictPath: suffix must be a 1-64 char string");
+    }
+    if (!IDENT_RE.test(opts.suffix)) {                                                           // allow:regex-no-length-cap — length-bounded immediately above
+      throw new TypeError("b.atomicFile.conflictPath: suffix must match [A-Za-z0-9_-]+");
+    }
+    suffix = "." + opts.suffix;
+  }
+  // Walk from the rightmost `.` to split base + ext. POSIX `path` module
+  // does it portably; using string ops here keeps the helper free of
+  // additional require()s in the hot atomic-file file (which is loaded
+  // before most of the framework's lazy chain). Extension preservation
+  // walks ONLY the basename — a directory containing a `.` doesn't
+  // confuse the suffix.
+  var sep = originalPath.lastIndexOf("/");
+  var bsep = originalPath.lastIndexOf("\\");
+  var lastSep = sep > bsep ? sep : bsep;
+  var dir = lastSep >= 0 ? originalPath.slice(0, lastSep + 1) : "";
+  var name = lastSep >= 0 ? originalPath.slice(lastSep + 1) : originalPath;
+  var dotIdx = name.lastIndexOf(".");
+  // Treat a leading dot (dotfile, e.g. `.env`) as part of the base, not
+  // as an extension separator. `dotIdx === 0` → no extension.
+  var base = dotIdx > 0 ? name.slice(0, dotIdx) : name;
+  var ext  = dotIdx > 0 ? name.slice(dotIdx) : "";
+  return dir + base + "." + tag + "-" + stamp + suffix + ext;
+}
+
 /**
  * @primitive b.atomicFile.writeSync
  * @signature b.atomicFile.writeSync(filepath, data, opts)
@@ -935,6 +1017,7 @@ module.exports = {
   ensureDir:         ensureDir,
   copyDirRecursive:  copyDirRecursive,
   pathTimestamp:     pathTimestamp,
+  conflictPath:      conflictPath,
   AtomicFileError:   AtomicFileError,
   DEFAULTS:          DEFAULTS,
 };

package/lib/audit.js

@@ -296,6 +296,11 @@ var FRAMEWORK_NAMESPACES = [
   "localdb",    // b.localDb.thin (localdb.thin.opened / recovered / closed — desktop-daemon SQLite wrapper)
   "dataact",    // b.dataAct (EU Data Act 2023/2854 — product_declared / user_access / share_with_third_party / share_refused / switch_request)
   "idempotency", // b.middleware.idempotencyKey (idempotency.missing_key / bad_key / replay / key_reuse_mismatch / cache_store / store_read_failed / store_write_failed / skip_5xx / body_too_large — draft-ietf-httpapi-idempotency-key)
+  "aibom",            // b.ai.modelManifest (aibom.signed / aibom.verified — CycloneDX 1.6 ML-BOM)
+  "aicontentdetect",  // b.ai.aiContentDetect (aicontentdetect.report — AB-853 / EU AI Act Art. 50 inbound provenance)
+  "sdnotify",         // b.sdNotify (sdnotify.send / sdnotify.send.skipped — systemd Type=notify)
+  "bootgates",        // b.bootGates (bootgates.passed / bootgates.failed / bootgates.onfail_threw — boot-invariant runner)
+  "metrics",          // b.metrics.snapshot.shadowRegistry (metrics.shadow.cardinality_dropped — namespaced metrics export)
 ];
 var registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
 

package/lib/boot-gates.js

@@ -0,0 +1,174 @@
+"use strict";
+/**
+ * @module b.bootGates
+ * @nav    Process
+ * @title  Boot Gates
+ *
+ * @intro
+ *   Sequential gate runner for boot-time invariants — vault unseal,
+ *   KEM key load, TLS material presence, DB schema migration, etc.
+ *   Each gate is `{ name, fn, timeoutMs?, exitCode?, onFail? }`; the
+ *   runner walks them in order and on FIRST failure:
+ *
+ *     1. emits `bootgates.failed { name, error, durationMs }` audit,
+ *     2. runs `onFail(err)` if provided (await async; swallows
+ *        throws + emits a separate `bootgates.onfail_threw` audit),
+ *     3. writes a single-line failure summary to stderr,
+ *     4. calls `process.exit(gate.exitCode || 1)`.
+ *
+ *   On success: emits `bootgates.passed { name, durationMs }` and
+ *   proceeds. Returns `{ passed, totalMs }` when EVERY gate passes.
+ *
+ *   Replaces the open-coded boot sequence operators write per-process
+ *   (try / log / process.exit) with one greppable primitive that
+ *   composes audit observability and gate-specific timeouts.
+ *
+ * @card
+ *   Sequential boot-invariant runner — gate, audit, exit with the right exit code. The thing every daemon main() reaches for.
+ */
+
+var C = require("./constants");
+var audit = require("./audit");
+var safeAsync = require("./safe-async");
+var { defineClass } = require("./framework-error");
+
+var BootGatesError = defineClass("BootGatesError", { alwaysPermanent: true });
+
+var DEFAULT_GATE_TIMEOUT_MS = C.TIME.seconds(60);
+var DEFAULT_EXIT_CODE = 1;
+
+/**
+ * @primitive b.bootGates.run
+ * @signature b.bootGates.run(gates, opts?)
+ * @since     0.10.9
+ * @status    stable
+ * @related   b.appShutdown.create, b.audit.safeEmit
+ *
+ * Walk `gates` in order, awaiting each `fn`. First failure stops the
+ * sequence and (after `onFail` + audit + stderr) calls
+ * `process.exit(gate.exitCode || opts.exitCode || 1)`. Returns
+ * `{ passed: string[], totalMs: number }` on full success.
+ *
+ * @opts
+ *   exitCode:        number,           // default 1 — overall fall-through
+ *   log:             function,         // default console.error.bind(console)
+ *   exit:            function,         // test seam; default process.exit
+ *   overallTimeoutMs: number,          // cap across the full sequence
+ *
+ * @example
+ *   await b.bootGates.run([
+ *     { name: "vault.unseal",       fn: async function () { await b.vault.unseal(); } },
+ *     { name: "tls.material",       fn: async function () { await loadTls(); } },
+ *     { name: "db.schemaMigration", fn: async function () { await migrate(); },
+ *       onFail: async function () { await db.close(); } },
+ *   ]);
+ */
+async function run(gates, opts) {
+  opts = opts || {};
+  if (!Array.isArray(gates) || gates.length === 0) {
+    throw new BootGatesError("bootgates/bad-input",
+      "b.bootGates.run: gates must be a non-empty array");
+  }
+  var log = typeof opts.log === "function" ? opts.log : function (msg) {
+    process.stderr.write(msg + "\n");
+  };
+  // Default exit handler invokes process.exit on the platform — guarded
+  // behind the opt because lib/ code is forbidden from calling
+  // process.exit directly (codebase-patterns rule "no process.exit() in
+  // lib/ (CLI surface only)"); the indirection routes through an opts-
+  // supplied function so test code substitutes a capture, and the CLI
+  // (bin/blamejs.js) is the one that wires the real exit call. When
+  // opts.exit isn't supplied, the boot-gate failure path bubbles a
+  // throw rather than terminating the process — operators that wire
+  // bootGates from their daemon main() pass `exit: process.exit.bind(process)`.
+  var exit = typeof opts.exit === "function" ? opts.exit : function (code) {
+    var e = new BootGatesError("bootgates/no-exit-wired",
+      "b.bootGates.run: gate failed (exitCode=" + code + ") but no opts.exit handler was supplied; " +
+      "operators wire opts.exit to process.exit.bind(process) in their daemon main()");
+    e.exitCode = code;
+    throw e;
+  };
+  var overallTimeoutMs = opts.overallTimeoutMs;
+  var t0 = Date.now();
+  var passed = [];
+
+  for (var i = 0; i < gates.length; i += 1) {
+    var gate = gates[i];
+    if (!gate || typeof gate.name !== "string" || gate.name.length === 0 ||
+        typeof gate.fn !== "function") {
+      throw new BootGatesError("bootgates/bad-gate",
+        "b.bootGates.run: gates[" + i + "] must be { name: string, fn: function }");
+    }
+    var timeoutMs = gate.timeoutMs || DEFAULT_GATE_TIMEOUT_MS;
+    if (typeof timeoutMs !== "number" || !isFinite(timeoutMs) || timeoutMs < 1) {
+      throw new BootGatesError("bootgates/bad-timeout",
+        "b.bootGates.run: gates[" + i + "].timeoutMs must be a positive finite number");
+    }
+    var gateT0 = Date.now();
+    var failure = null;
+    try {
+      await safeAsync.withTimeout(Promise.resolve().then(gate.fn), timeoutMs,
+        new BootGatesError("bootgates/timeout",
+          "b.bootGates.run: gate '" + gate.name + "' exceeded " + timeoutMs + "ms"));
+    } catch (err) {
+      failure = err;
+    }
+    if (overallTimeoutMs !== undefined &&
+        Date.now() - t0 > overallTimeoutMs && failure === null) {
+      failure = new BootGatesError("bootgates/overall-timeout",
+        "b.bootGates.run: overall budget " + overallTimeoutMs + "ms exceeded after gate '" +
+        gate.name + "'");
+    }
+    var durationMs = Date.now() - gateT0;
+    if (failure !== null) {
+      try {
+        audit.safeEmit({
+          action:   "bootgates.failed",
+          outcome:  "failure",
+          metadata: { name: gate.name, error: (failure && failure.message) || String(failure),
+                      durationMs: durationMs },
+        });
+      } catch (_e) { /* drop-silent */ }
+      if (typeof gate.onFail === "function") {
+        try {
+          await Promise.resolve().then(function () { return gate.onFail(failure); });
+        } catch (oe) {
+          try {
+            audit.safeEmit({
+              action:   "bootgates.onfail_threw",
+              outcome:  "failure",
+              metadata: { name: gate.name, error: (oe && oe.message) || String(oe) },
+            });
+          } catch (_e2) { /* drop-silent */ }
+        }
+      }
+      log("[bootgates] FAILED gate=" + gate.name + " durationMs=" + durationMs +
+          " error=" + ((failure && failure.message) || String(failure)));
+      if (failure && failure.stack) log(failure.stack);
+      var code = gate.exitCode || opts.exitCode || DEFAULT_EXIT_CODE;
+      exit(code);
+      // The test seam swaps `exit` out; in that case we still surface
+      // a synthetic return value so the caller's promise resolves.
+      return { passed: passed, failed: gate.name, exitCode: code, totalMs: Date.now() - t0 };
+    }
+    try {
+      audit.safeEmit({
+        action:   "bootgates.passed",
+        outcome:  "success",
+        metadata: { name: gate.name, durationMs: durationMs },
+      });
+    } catch (_e3) { /* drop-silent */ }
+    if (typeof opts.onPassed === "function") {
+      try { opts.onPassed({ name: gate.name, durationMs: durationMs }); }
+      catch (_e4) { /* drop-silent */ }
+    }
+    passed.push(gate.name);
+  }
+
+  return { passed: passed, totalMs: Date.now() - t0 };
+}
+
+module.exports = {
+  run:            run,
+  BootGatesError: BootGatesError,
+};