@blamejs/core 0.8.18 → 0.8.25

package/index.js

@@ -100,6 +100,8 @@ var graphqlFederation = require("./lib/graphql-federation");
 var aiInput = require("./lib/ai-input");
 var a2a = require("./lib/a2a");
 var darkPatterns = require("./lib/dark-patterns");
+var budr = require("./lib/budr");
+var secCyber = require("./lib/sec-cyber");
 var safeUrl = require("./lib/safe-url");
 var safeRedirect = require("./lib/safe-redirect");
 var pick = require("./lib/pick");
@@ -287,6 +289,8 @@ module.exports = {
   graphqlFederation: graphqlFederation,
   a2a:              a2a,
   darkPatterns:     darkPatterns,
+  budr:             budr,
+  secCyber:         secCyber,
   safeUrl:          safeUrl,
   safeRedirect:     safeRedirect,
   pick:             pick,

package/lib/audit.js

@@ -238,6 +238,8 @@ var FRAMEWORK_NAMESPACES = [
   "aiinput",    // b.ai.input.classify (aiInput.classify)
   "a2a",        // b.a2a (a2a.card_signed / verified / rejected)
   "darkpatterns", // b.darkPatterns (darkPatterns.attest / cancel-blocked)
+  "budr",       // b.budr (budr.declared)
+  "seccyber",   // b.secCyber (seccyber.eight_k_artifact)
 ];
 var registeredNamespaces = new Set(FRAMEWORK_NAMESPACES);
 

package/lib/budr.js

@@ -0,0 +1,132 @@
+"use strict";
+/**
+ * b.budr — backup, disaster-recovery, RTO/RPO declaration primitive.
+ *
+ * Operators in regulated environments (HIPAA / DORA / ISO 22301:2019 /
+ * NIST SP 800-34) must declare their Recovery Time Objective (RTO,
+ * how long systems can be down before unacceptable impact) and
+ * Recovery Point Objective (RPO, max acceptable data loss). The
+ * declaration is auditor-facing — regulators want it on file as part
+ * of business-continuity / disaster-recovery documentation.
+ *
+ * The framework can't enforce RTO/RPO end-to-end (those depend on
+ * downstream backup cadence, replication topology, restore testing).
+ * What it can do: capture the operator's declared targets in a
+ * tamper-evident audit row + expose them to dashboards.
+ *
+ * Public API:
+ *
+ *   b.budr.declare(opts) -> declaration
+ *     opts:
+ *       service:        operator-named service identifier (string).
+ *       rtoMs:          Recovery Time Objective in milliseconds.
+ *       rpoMs:          Recovery Point Objective in milliseconds.
+ *       tier:           "platinum" / "gold" / "silver" / "bronze"
+ *                       (BCDR criticality classification — platinum
+ *                       most-critical).
+ *       criticality:    "critical" / "high" / "medium" / "low".
+ *       owner:          operator-named accountable owner (team / role).
+ *       reviewedAt:     timestamp of the most recent operator review.
+ *       citations:      array of regulatory citations (e.g. ["dora-art-11", "iso-22301:2019"]).
+ *       audit:          bool, default true.
+ *
+ *   b.budr.list() -> Array<declaration>
+ *
+ *   b.budr.get(service) -> declaration | null
+ */
+
+var nb = require("./numeric-bounds");
+var validateOpts = require("./validate-opts");
+var audit = require("./audit");
+var { defineClass } = require("./framework-error");
+var BudrError = defineClass("BudrError", { alwaysPermanent: true });
+
+var SERVICE_MAX = 128;                                                                        // allow:raw-byte-literal — string-length cap, not bytes
+var SERVICE_RE = /^[a-zA-Z0-9._:/-]{1,128}$/;                                                 // allow:raw-byte-literal — string-length cap; not bytes
+var TIERS = ["platinum", "gold", "silver", "bronze"];
+var CRITICALITIES = ["critical", "high", "medium", "low"];
+
+var declarations = new Map();
+
+function declare(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw BudrError.factory("BAD_OPTS", "budr.declare: opts required");
+  }
+  if (typeof opts.service !== "string" || opts.service.length === 0 ||
+      opts.service.length > SERVICE_MAX || !SERVICE_RE.test(opts.service)) {
+    throw BudrError.factory("BAD_SERVICE",
+      "budr.declare: service must match " + SERVICE_RE);
+  }
+  nb.requirePositiveFiniteIntIfPresent(opts.rtoMs, "budr.declare: rtoMs", BudrError, "BAD_RTO");
+  nb.requirePositiveFiniteIntIfPresent(opts.rpoMs, "budr.declare: rpoMs", BudrError, "BAD_RPO");
+  if (typeof opts.rtoMs !== "number" || typeof opts.rpoMs !== "number") {
+    throw BudrError.factory("BAD_TARGETS",
+      "budr.declare: rtoMs and rpoMs are required positive integer milliseconds");
+  }
+  if (opts.tier !== undefined && TIERS.indexOf(opts.tier) === -1) {
+    throw BudrError.factory("BAD_TIER",
+      "budr.declare: tier must be one of " + TIERS.join(", "));
+  }
+  if (opts.criticality !== undefined && CRITICALITIES.indexOf(opts.criticality) === -1) {
+    throw BudrError.factory("BAD_CRITICALITY",
+      "budr.declare: criticality must be one of " + CRITICALITIES.join(", "));
+  }
+  validateOpts.optionalNonEmptyString(opts.owner,
+    "budr.declare: owner", BudrError, "BAD_OWNER");
+  if (opts.citations !== undefined && !Array.isArray(opts.citations)) {
+    throw BudrError.factory("BAD_CITATIONS",
+      "budr.declare: citations must be an array of strings");
+  }
+
+  var declaration = Object.freeze({
+    service:     opts.service,
+    rtoMs:       opts.rtoMs,
+    rpoMs:       opts.rpoMs,
+    tier:        opts.tier         || null,
+    criticality: opts.criticality  || null,
+    owner:       opts.owner        || null,
+    citations:   Array.isArray(opts.citations) ? opts.citations.slice() : [],
+    declaredAt:  Date.now(),
+    reviewedAt:  typeof opts.reviewedAt === "number" ? opts.reviewedAt : Date.now(),
+  });
+  declarations.set(opts.service, declaration);
+
+  if (opts.audit !== false) {
+    audit.safeEmit({
+      action:   "budr.declared",
+      outcome:  "success",
+      metadata: {
+        service:     declaration.service,
+        rtoMs:       declaration.rtoMs,
+        rpoMs:       declaration.rpoMs,
+        tier:        declaration.tier,
+        criticality: declaration.criticality,
+        owner:       declaration.owner,
+        citations:   declaration.citations,
+      },
+    });
+  }
+  return declaration;
+}
+
+function get(service) {
+  if (typeof service !== "string") return null;
+  var rec = declarations.get(service);
+  return rec === undefined ? null : rec;
+}
+
+function list() {
+  return Array.from(declarations.values());
+}
+
+function _resetForTest() { declarations.clear(); }
+
+module.exports = {
+  declare:        declare,
+  get:            get,
+  list:           list,
+  TIERS:          TIERS.slice(),
+  CRITICALITIES:  CRITICALITIES.slice(),
+  BudrError:      BudrError,
+  _resetForTest:  _resetForTest,
+};

package/lib/compliance.js

@@ -63,6 +63,28 @@ var KNOWN_POSTURES = Object.freeze([
   // ---- Canada / UK ----
   "pipeda-ca",   // Canada Personal Information Protection and Electronic Documents Act (added 2026)
   "uk-gdpr",     // UK General Data Protection Regulation (added 2026)
+  // ---- Sectoral expansions (added 2026 — v0.8.24) ----
+  "fapi-2.0",        // Financial-grade API 2.0 Final (composes PAR + DPoP + OAuth 2.1 + mTLS)
+  "cfpb-1033",       // CFPB §1033 / FDX consumer-financial-data sharing (deadline past for $250B+ banks 2026-04-01)
+  "iab-tcf-v2.3",    // IAB Transparency & Consent Framework v2.3 with disclosedVendors (deadline past 2026-02-28)
+  "iab-mspa",        // IAB Multi-State Privacy Agreement / Global Privacy Platform universal opt-out
+  "tcpa-10dlc",      // TCPA 10DLC carrier-shaped consent + FCC 1:1 disclosure
+  "fda-21cfr11",     // FDA 21 CFR Part 11 — audit-trail + electronic signatures (general-purpose subset)
+  "fda-annex-11",    // EU GMP Annex 11 — computerized systems (Part-11 equivalent)
+  "sec-1.05",        // SEC Cybersecurity Disclosure Item 1.05 — material-incident 8-K filing                                  // allow:raw-byte-literal — regulatory identifier, not bytes
+  // ---- US state student-data privacy (F5.1 posture group) ----
+  "ny-2-d",          // NY Education Law §2-d
+  "il-soppa",        // Illinois Student Online Personal Protection Act
+  "ca-sopipa",       // California Student Online Personal Information Protection Act
+  "ct-pa-5-2",       // Connecticut Public Act 5-2
+  "tx-hb-4504",      // Texas HB 4504                                                                                            // allow:raw-byte-literal — statute identifier, not bytes
+  "va-sb-1376",      // Virginia SB 1376                                                                                         // allow:raw-byte-literal — statute identifier, not bytes
+  // ---- EU government / cloud-region ----
+  "staterramp",      // StateRAMP / TX-RAMP / AZ-RAMP / GovRAMP family (FedRAMP-Moderate cross-walks)
+  "irap",            // Australia IRAP / Essential Eight / ISM
+  "bsi-c5",          // Germany BSI C5
+  "ens-es",          // Spain Esquema Nacional de Seguridad
+  "uk-g-cloud",      // UK G-Cloud
 ]);
 
 var STATE = { posture: null, setAt: null };
@@ -106,6 +128,22 @@ function set(posture) {
   STATE.posture = posture;
   STATE.setAt   = Date.now();
   _emitAudit("compliance.posture.set", { posture: posture });
+  // F-AUD-5 — TZ awareness. Auditors expect timestamps in UTC.
+  // process.env.TZ controls Node's local-time conversion for any
+  // operator code that uses non-UTC formatters; under regulated
+  // postures (hipaa / pci-dss / sox / gdpr / soc2) emit a boot
+  // warning if it's set to a non-UTC value or unset (which means
+  // host-default which on most cloud images IS UTC but isn't
+  // guaranteed). Pure signal — no behavior change.
+  var REGULATED = ["hipaa", "pci-dss", "sox", "gdpr", "soc2", "fda-21cfr11"];
+  if (REGULATED.indexOf(posture) !== -1) {
+    var tz = process.env.TZ;                                                                  // allow:raw-process-env — bootstrap signal, no operator-supplied default needed
+    if (typeof tz === "string" && tz !== "UTC" && tz !== "Etc/UTC") {
+      _emitAudit("compliance.posture.tz_warning",
+        { posture: posture, tz: tz, recommendation: "Set TZ=UTC under regulated postures so audit timestamps align with regulator expectations." },
+        "warning");
+    }
+  }
 }
 
 function current() {

package/lib/crypto.js

@@ -160,6 +160,13 @@ function verify(data, signature, publicKeyPem) {
   return nodeCrypto.verify(null, Buffer.from(data), publicKeyPem, signature);
 }
 
+// Track whether the hybrid-disabled audit has been emitted at least
+// once per process, so a high-volume KEM-only deployment doesn't peg
+// the audit bus with one event per encrypt() call. Operators who want
+// the per-call signal can call encryptMlkemOnly directly (which never
+// emits) or read the metric at b.metrics — the count is preserved.
+var _hybridDisabledAuditEmitted = false;
+
 // ---- Envelope encrypt (ML-KEM-1024 + P-384 ECDH hybrid + SHAKE256 + XChaCha20) ----
 function encrypt(plaintext, publicKeys) {
   var mlkemPubPem = typeof publicKeys === "string" ? publicKeys : publicKeys.publicKey;
@@ -168,20 +175,23 @@ function encrypt(plaintext, publicKeys) {
     // Operator passed only an ML-KEM public key — silently dropping
     // the P-384 hybrid leg means the operator's defense-in-depth
     // posture (classical ECDH backstop on top of PQC KEM) is gone
-    // without any signal. Emit on next tick (crypto must not import
-    // audit synchronously — audit imports crypto for chain hashing).
-    // Operators who genuinely want KEM-only should call
+    // without any signal. Audit ONCE per process (M2 audit-dedup —
+    // pre-v0.8.22 every plain-KEM call emitted, pegging the audit
+    // bus). Operators who genuinely want KEM-only should call
     // encryptMlkemOnly explicitly so this audit doesn't fire.
-    setImmediate(function () {
-      try {
-        var auditMod = require("./audit");                                          // allow:inline-require — circular-load defense (audit imports crypto)
-        auditMod.safeEmit({
-          action:   "system.crypto.hybrid_disabled",
-          outcome:  "success",
-          metadata: { reason: "no-ec-public-key", note: "encrypt() received only mlkem; ecPublicKey absent — call encryptMlkemOnly explicitly to silence" },
-        });
-      } catch (_e) { /* drop-silent — best-effort */ }
-    });
+    if (!_hybridDisabledAuditEmitted) {
+      _hybridDisabledAuditEmitted = true;
+      setImmediate(function () {
+        try {
+          var auditMod = require("./audit");                                        // allow:inline-require — circular-load defense (audit imports crypto)
+          auditMod.safeEmit({
+            action:   "system.crypto.hybrid_disabled",
+            outcome:  "success",
+            metadata: { reason: "no-ec-public-key", note: "encrypt() received only mlkem; ecPublicKey absent — call encryptMlkemOnly explicitly to silence (audited once per process)" },
+          });
+        } catch (_e) { /* drop-silent — best-effort */ }
+      });
+    }
     return encryptMlkemOnly(plaintext, mlkemPubPem);
   }
 

package/lib/db.js

@@ -704,6 +704,20 @@ async function init(opts) {
   // delete, which the framework's audit-and-DSR-erase path already
   // dominates with audit-chain emissions and cascade fan-out.
   runSql(database, "PRAGMA secure_delete=ON");
+  // PRAGMA trusted_schema=OFF — refuses to call functions / virtual-
+  // table modules referenced from a malicious shadow schema. Defends
+  // the CVE-2018-8740 family where an attacker who can write to the
+  // database file (backups, logs, restore-from-untrusted) plants
+  // schema entries that fire on next access.
+  try { runSql(database, "PRAGMA trusted_schema=OFF"); } catch (_e) { /* sqlite < 3.31 */ }
+  // PRAGMA cell_size_check=ON — refuses pages with corrupted cell
+  // sizes at parse time rather than crashing later. Cheap defense
+  // against malformed-page attacks.
+  try { runSql(database, "PRAGMA cell_size_check=ON"); } catch (_e) { /* sqlite < 3.26 */ }
+  // node:sqlite does not expose loadExtension at all — extensions must
+  // be statically linked into the runtime. The framework's surface is
+  // therefore implicitly extension-free; no runtime defense is needed
+  // beyond the trusted_schema + cell_size_check PRAGMAs above.
 
   // Boot-time integrity check — refuse to boot on B-tree corruption.
   // SQLite normally surfaces corruption only when a query stumbles on
@@ -1002,9 +1016,52 @@ function stream(sql) {
   });
 }
 
+// DDL_RE — case-insensitive prefix match for the eight statement
+// shapes that MUTATE schema. Audited individually so a forensic
+// review can reconstruct schema evolution from the chain alone (D-M1).
+var DDL_RE = /^\s*(CREATE|DROP|ALTER|TRUNCATE|RENAME|ATTACH|DETACH|REINDEX)\b/i;
+
 function execRaw(sql) {
   _requireInit();
-  return runSql(database, sql);
+  var startedAt = Date.now();
+  var auditMod = (function () { try { return require("./audit"); } catch (_e) { return null; } })(); // allow:inline-require — circular-load defense (audit imports db)
+  // DDL_RE only matches the leading keyword — bounded by `/\s*(KEYWORD)\b/`
+  // so the test is constant-time regardless of the rest of the query.
+  var isDdl = typeof sql === "string" && DDL_RE.test(sql);                                    // allow:regex-no-length-cap — leading-keyword anchor; constant-time test
+  try {
+    var result = runSql(database, sql);
+    if (isDdl && auditMod) {
+      auditMod.safeEmit({
+        action:   "db.ddl.executed",
+        outcome:  "success",
+        metadata: {
+          // OTel db.* semconv (F-RFC-4) — emit framework-conventional
+          // attributes alongside the audit row so dashboards built on
+          // OTel can correlate without an adapter.
+          "db.system":     "sqlite",
+          "db.operation":  String(sql).match(DDL_RE)[1].toUpperCase(),
+          "db.statement":  String(sql).slice(0, 256),                                          // allow:raw-byte-literal — log-truncation length, not bytes
+          durationMs:      Date.now() - startedAt,
+        },
+      });
+    }
+    return result;
+  } catch (e) {
+    if (isDdl && auditMod) {
+      auditMod.safeEmit({
+        action:   "db.ddl.executed",
+        outcome:  "failure",
+        reason:   (e && e.message) || String(e),
+        metadata: {
+          "db.system":     "sqlite",
+          "db.operation":  String(sql).match(DDL_RE)[1].toUpperCase(),
+          "db.statement":  String(sql).slice(0, 256),                                          // allow:raw-byte-literal — log-truncation length, not bytes
+          durationMs:      Date.now() - startedAt,
+        },
+      });
+    }
+    throw e;
+  }
 }
 
 function transaction(fn) {

package/lib/external-db-migrate.js

@@ -146,7 +146,7 @@ async function _acquireLock(xdb, opts) {
       "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
       [nowMs, holder]
     );
-    return holder;
+    return { holder: holder, takeoverFrom: null, takeoverAgeMs: 0 };
   } catch (_e) {
     // PRIMARY KEY conflict → existing lock. Inspect it.
     var existingRes = await xdb.query(
@@ -160,7 +160,7 @@ async function _acquireLock(xdb, opts) {
           "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
           [nowMs, holder]
         );
-        return holder;
+        return { holder: holder, takeoverFrom: null, takeoverAgeMs: 0 };
       } catch (e2) {
         throw _err("externaldb-migrate/lock-busy",
           "could not acquire migration lock: " + ((e2 && e2.message) || String(e2)));
@@ -168,7 +168,9 @@ async function _acquireLock(xdb, opts) {
     }
     var ageMs = nowMs - Number(existing.lockedat || existing.lockedAt);
     if (staleAfterMs > 0 && ageMs > staleAfterMs) {
-      // Force-replace the stale lock atomically.
+      // Force-replace the stale lock atomically. Stale-takeover is a
+      // SOC2 evidence event — caller emits an audit row.
+      var prevHolder = existing.lockedby || existing.lockedBy;
       await xdb.query(
         "DELETE FROM " + Q_LOCK + " WHERE scope = 'lock' AND lockedAt = $1",
         [Number(existing.lockedat || existing.lockedAt)]
@@ -177,7 +179,7 @@ async function _acquireLock(xdb, opts) {
         "INSERT INTO " + Q_LOCK + " (scope, lockedAt, lockedBy) VALUES ('lock', $1, $2)",
         [nowMs, holder]
       );
-      return holder;
+      return { holder: holder, takeoverFrom: prevHolder, takeoverAgeMs: ageMs };
     }
     throw _err("externaldb-migrate/lock-held",
       "migration lock is held by " + (existing.lockedby || existing.lockedBy) +
@@ -310,12 +312,21 @@ function create(opts) {
       // pool acquisition for the lock connection — the migrate runner
       // serializes apply order, so this single-connection lock is
       // sufficient.
-      var lockHolder = await externalDbModule().transaction(async function (xdb) {
+      var lockResult = await externalDbModule().transaction(async function (xdb) {
         return await _acquireLock(xdb, opts);
       }, { backend: backendName });
+      var lockHolder = lockResult.holder;
 
       _emit(audit, "externaldb.migrate.lock.acquired", "success",
             { holder: lockHolder, backend: backendName }, null);
+      // SOC2 evidence — record the stale-takeover separately so a
+      // forensic review can reconstruct WHICH process orphaned the
+      // lock and WHEN. Pre-v0.8.19 the takeover happened silently.
+      if (lockResult.takeoverFrom) {
+        _emit(audit, "externaldb.migrate.lock.takeover", "success",
+              { holder: lockHolder, takeoverFrom: lockResult.takeoverFrom,
+                takeoverAgeMs: lockResult.takeoverAgeMs, backend: backendName }, null);
+      }
 
       try {
         var appliedRes = await externalDbModule().query(
@@ -379,12 +390,18 @@ function create(opts) {
       await _ensureLockTable(xdb);
     }, { backend: backendName });
 
-    var lockHolder = await externalDbModule().transaction(async function (xdb) {
+    var lockResultDown = await externalDbModule().transaction(async function (xdb) {
       return await _acquireLock(xdb, opts);
     }, { backend: backendName });
+    var lockHolder = lockResultDown.holder;
 
     _emit(audit, "externaldb.migrate.lock.acquired", "success",
           { holder: lockHolder, backend: backendName }, null);
+    if (lockResultDown.takeoverFrom) {
+      _emit(audit, "externaldb.migrate.lock.takeover", "success",
+            { holder: lockHolder, takeoverFrom: lockResultDown.takeoverFrom,
+              takeoverAgeMs: lockResultDown.takeoverAgeMs, backend: backendName }, null);
+    }
 
     try {
       var appliedRes = await externalDbModule().query(

package/lib/external-db.js

@@ -946,9 +946,27 @@ function _connectAs(rawConnect, query, opts) {
     for (var gn in opts.gucs) {
       var gv = opts.gucs[gn];
       if (typeof gv === "number") {
+        // Numeric GUCs must be finite — Infinity / NaN serialize as
+        // tokens that Postgres would reject at parse time, but only
+        // AFTER the connection started using a half-set state. Refuse
+        // at config-time instead.
+        if (!isFinite(gv)) {
+          throw _err("INVALID_CONFIG",
+            "connectAs: gucs[" + gn + "] number must be finite (got " + gv + ")",
+            true);
+        }
         stmts.push('SET "' + gn + '" TO ' + gv);
       } else {
         var gvs = String(gv).replace(/'/g, "''");
+        // Refuse embedded NUL / line breaks in GUC string values —
+        // they have no legitimate use and would terminate the SET
+        // statement early in some drivers.
+        // eslint-disable-next-line no-control-regex
+        if (/[\r\n\u0000]/.test(gvs)) {
+          throw _err("INVALID_CONFIG",
+            "connectAs: gucs[" + gn + "] string value must not contain NUL or newline characters",
+            true);
+        }
         stmts.push('SET "' + gn + '" TO \'' + gvs + "'");
       }
     }

package/lib/guard-archive.js

@@ -332,7 +332,7 @@ function checkExtractionPath(entryName, extractionRoot) {
     return { ok: false, reason: "entry name is an absolute path" };
   }
   // Reject entries containing null bytes regardless of extraction root.
-  if (entryName.indexOf("") !== -1) {
+  if (entryName.indexOf("\u0000") !== -1) {
     return { ok: false, reason: "entry name contains null byte" };
   }
   void extractionRoot;

package/lib/sec-cyber.js

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * b.secCyber — SEC Cybersecurity Disclosure Item 1.05 (Form 8-K)
+ * artifact generator.
+ *
+ * Required by 17 CFR §229.106 / Form 8-K Item 1.05 (final rule
+ * effective 2023-12-18). When a registrant determines that a
+ * cybersecurity incident is material, it MUST file a Form 8-K within
+ * 4 business days of the materiality determination, describing:
+ *
+ *   - The material aspects of the nature, scope, and timing
+ *   - The material impact or reasonably likely material impact on
+ *     the registrant (financial condition + results of operations)
+ *
+ * Materiality determination MUST be made "without unreasonable
+ * delay." The Attorney General can authorize a delay (when public
+ * disclosure would pose substantial risk to national security or
+ * public safety) — registrant requests the delay before the 4-day
+ * window elapses.
+ *
+ * The framework can't decide materiality (that's a fact-and-circum-
+ * stances judgment). What it CAN do:
+ *
+ *   - Structure the operator's materiality finding into a
+ *     tamper-evident audit-chain row (the regulator-facing record).
+ *   - Generate the 8-K Item 1.05 narrative skeleton with the
+ *     operator's content slotted in.
+ *   - Compute the 4-business-day deadline so the operator's
+ *     filing-system gate refuses to slip past it.
+ *   - Emit an AG-delay-request artifact when the operator asserts
+ *     national-security / public-safety risk.
+ *
+ * Public API:
+ *
+ *   b.secCyber.eightKArtifact(opts) -> { artifact, deadline, audit }
+ *     opts:
+ *       incidentId:        operator-supplied incident reference (string).
+ *       registrant:        { name, cik, filer }
+ *       detectedAt:        Unix-ms when the incident was detected.
+ *       materialityDeterminedAt: Unix-ms when materiality was determined.
+ *       materialityFinding:      "material" | "not-material" | "pending".
+ *       materialityReasoning:    operator-provided narrative
+ *                                explaining the materiality call.
+ *       nature:            string describing the incident's nature.
+ *       scope:             string describing the scope.
+ *       timing:            string describing the timing.
+ *       impact:            string describing material/likely-material
+ *                          impact on financial condition + operations.
+ *       agDelayRequested:  bool. When true, the artifact includes the
+ *                          AG-delay-request template and the 4-day
+ *                          deadline is suspended pending DOJ response.
+ *       agDelayJustification: string explaining the national-security
+ *                          / public-safety risk that justifies delay
+ *                          (REQUIRED when agDelayRequested = true).
+ *       audit:             bool, default true.
+ *
+ *   Returns:
+ *       artifact:          structured 8-K Item 1.05 content (markdown
+ *                          + JSON for downstream EDGAR filing).
+ *       deadline:          Unix-ms 4-business-day deadline (null when
+ *                          AG-delay-requested).
+ *       deadlineBusinessDays: business-day count (4 by default; spec
+ *                          gives no exception).
+ *
+ * The framework does NOT submit to EDGAR — operators wire the
+ * artifact into their existing filer-attorney workflow.
+ */
+
+var audit = require("./audit");
+var C = require("./constants");
+var validateOpts = require("./validate-opts");
+var nb = require("./numeric-bounds");
+var { defineClass } = require("./framework-error");
+var SecCyberError = defineClass("SecCyberError", { alwaysPermanent: true });
+
+var FINDINGS = ["material", "not-material", "pending"];
+
+function _addBusinessDays(startMs, days) {
+  // Walk forward N business days (Mon-Fri). Doesn't honor US federal
+  // holidays — operators with a calendar-aware filing system override
+  // by reading deadlineBusinessDays and computing themselves.
+  var t = new Date(startMs);
+  var added = 0;
+  while (added < days) {
+    t = new Date(t.getTime() + C.TIME.days(1));
+    var dow = t.getUTCDay();
+    if (dow !== 0 && dow !== 6) added += 1;
+  }
+  return t.getTime();
+}
+
+function eightKArtifact(opts) {
+  if (!opts || typeof opts !== "object") {
+    throw SecCyberError.factory("BAD_OPTS",
+      "secCyber.eightKArtifact: opts required");
+  }
+  validateOpts.requireNonEmptyString(opts.incidentId,
+    "secCyber.eightKArtifact: incidentId", SecCyberError, "BAD_INCIDENT_ID");
+  if (!opts.registrant || typeof opts.registrant !== "object") {
+    throw SecCyberError.factory("BAD_REGISTRANT",
+      "secCyber.eightKArtifact: registrant object required");
+  }
+  validateOpts.requireNonEmptyString(opts.registrant.name,
+    "secCyber.eightKArtifact: registrant.name", SecCyberError, "BAD_REGISTRANT_NAME");
+  validateOpts.requireNonEmptyString(opts.registrant.cik,
+    "secCyber.eightKArtifact: registrant.cik", SecCyberError, "BAD_CIK");
+  nb.requirePositiveFiniteIntIfPresent(opts.detectedAt,
+    "secCyber.eightKArtifact: detectedAt", SecCyberError, "BAD_DETECTED_AT");
+  nb.requirePositiveFiniteIntIfPresent(opts.materialityDeterminedAt,
+    "secCyber.eightKArtifact: materialityDeterminedAt", SecCyberError, "BAD_MAT_AT");
+
+  if (FINDINGS.indexOf(opts.materialityFinding) === -1) {
+    throw SecCyberError.factory("BAD_FINDING",
+      "secCyber.eightKArtifact: materialityFinding must be one of " + FINDINGS.join(", "));
+  }
+  validateOpts.requireNonEmptyString(opts.materialityReasoning,
+    "secCyber.eightKArtifact: materialityReasoning", SecCyberError, "BAD_REASONING");
+
+  if (opts.materialityFinding === "material") {
+    validateOpts.requireNonEmptyString(opts.nature,
+      "secCyber.eightKArtifact: nature", SecCyberError, "BAD_NATURE");
+    validateOpts.requireNonEmptyString(opts.scope,
+      "secCyber.eightKArtifact: scope", SecCyberError, "BAD_SCOPE");
+    validateOpts.requireNonEmptyString(opts.timing,
+      "secCyber.eightKArtifact: timing", SecCyberError, "BAD_TIMING");
+    validateOpts.requireNonEmptyString(opts.impact,
+      "secCyber.eightKArtifact: impact", SecCyberError, "BAD_IMPACT");
+  }
+
+  var agDelayRequested = opts.agDelayRequested === true;
+  if (agDelayRequested) {
+    validateOpts.requireNonEmptyString(opts.agDelayJustification,
+      "secCyber.eightKArtifact: agDelayJustification (required when agDelayRequested=true)",
+      SecCyberError, "BAD_AG_JUSTIFICATION");
+  }
+
+  var matAt = opts.materialityDeterminedAt || Date.now();
+  var deadline = agDelayRequested ? null : _addBusinessDays(matAt, 4);
+
+  var markdown = "# Form 8-K — Item 1.05 Material Cybersecurity Incident\n\n" +
+    "**Registrant:** " + opts.registrant.name + " (CIK: " + opts.registrant.cik + ")\n\n" +
+    "**Incident ID:** " + opts.incidentId + "\n\n" +
+    "**Materiality determination date:** " + new Date(matAt).toISOString() + "\n\n" +
+    "**Materiality finding:** " + opts.materialityFinding + "\n\n" +
+    "**Reasoning:**\n\n" + opts.materialityReasoning + "\n\n";
+
+  if (opts.materialityFinding === "material") {
+    markdown +=
+      "## Item 1.05(a) — Material aspects\n\n" +
+      "**Nature.** " + opts.nature + "\n\n" +
+      "**Scope.** " + opts.scope + "\n\n" +
+      "**Timing.** " + opts.timing + "\n\n" +
+      "## Item 1.05(b) — Material impact\n\n" + opts.impact + "\n\n";
+  }
+
+  if (agDelayRequested) {
+    markdown += "## AG-delay request (17 CFR §229.106(c)(1)(ii))\n\n" +
+      "Registrant asserts that disclosure of this incident would pose a substantial " +
+      "risk to national security or public safety. Pursuant to the rule, registrant " +
+      "requests that the Attorney General authorize a delay of disclosure.\n\n" +
+      "**Justification:** " + opts.agDelayJustification + "\n\n";
+  }
+
+  markdown += "**Filing deadline:** " +
+    (deadline ? new Date(deadline).toISOString() + " (4 business days from materiality determination)" :
+                "suspended pending DOJ response to AG-delay request") + "\n";
+
+  var artifactJson = {
+    form:         "8-K",
+    item:         "1.05",
+    incidentId:   opts.incidentId,
+    registrant:   { name: opts.registrant.name, cik: opts.registrant.cik },
+    detectedAt:   opts.detectedAt || null,
+    materialityDeterminedAt: matAt,
+    materialityFinding: opts.materialityFinding,
+    materialityReasoning: opts.materialityReasoning,
+    items: opts.materialityFinding === "material" ? {
+      "1.05(a)": {
+        nature: opts.nature, scope: opts.scope, timing: opts.timing,
+      },
+      "1.05(b)": { impact: opts.impact },
+    } : null,
+    agDelayRequested:     agDelayRequested,
+    agDelayJustification: agDelayRequested ? opts.agDelayJustification : null,
+    deadlineMs:           deadline,
+  };
+
+  if (opts.audit !== false) {
+    audit.safeEmit({
+      action:   "seccyber.eight_k_artifact",
+      outcome:  "success",
+      metadata: {
+        incidentId:           opts.incidentId,
+        registrant:           opts.registrant.name,
+        cik:                  opts.registrant.cik,
+        materialityFinding:   opts.materialityFinding,
+        deadlineMs:           deadline,
+        agDelayRequested:     agDelayRequested,
+      },
+    });
+  }
+
+  return {
+    artifact: { markdown: markdown, json: artifactJson },
+    deadline: deadline,
+    deadlineBusinessDays: agDelayRequested ? null : 4,                                       // allow:raw-byte-literal — SEC Item 1.05 4-business-day deadline (17 CFR §229.106(c)(1))
+  };
+}
+
+module.exports = {
+  eightKArtifact: eightKArtifact,
+  FINDINGS:       FINDINGS.slice(),
+  SecCyberError:  SecCyberError,
+};

package/lib/vault/seal-pem-file.js

@@ -59,6 +59,7 @@ var path = require("path");
 var atomicFile = require("../atomic-file");
 var C = require("../constants");
 var lazyRequire = require("../lazy-require");
+var safeBuffer = require("../safe-buffer");
 var validateOpts = require("../validate-opts");
 var { defineClass } = require("../framework-error");
 var { boot } = require("../log");
@@ -77,11 +78,18 @@ var SealPemFileError = defineClass("SealPemFileError", { alwaysPermanent: true }
 // override via opts.pollInterval.
 var DEFAULT_POLL_MS = C.TIME.seconds(2);
 
+// PEM files are tiny — 4 KiB for an ECDSA key, ~8 KiB for a 4096-bit
+// RSA key, ~64 KiB for a long cert chain. Cap at 1 MiB so an operator
+// with write access to source can't present a 10 GiB file and OOM the
+// host. Operators with genuinely larger inputs override via
+// opts.maxSourceBytes.
+var DEFAULT_MAX_SOURCE_BYTES = C.BYTES.mib(1);
+
 function sealPemFile(opts) {
   opts = opts || {};
   validateOpts(opts, [
     "source", "destination", "audit", "pollInterval",
-    "onResealed", "onError",
+    "onResealed", "onError", "maxSourceBytes",
   ], "vault.sealPemFile");
 
   validateOpts.requireNonEmptyString(opts.source,
@@ -109,6 +117,9 @@ function sealPemFile(opts) {
   var auditOn       = opts.audit !== false;
   var onResealed    = typeof opts.onResealed === "function" ? opts.onResealed : null;
   var onError       = typeof opts.onError === "function" ? opts.onError : null;
+  validateOpts.optionalPositiveFinite(opts.maxSourceBytes,
+    "vault.sealPemFile: maxSourceBytes", SealPemFileError, "seal-pem-file/bad-max-source-bytes");
+  var maxSourceBytes = opts.maxSourceBytes || DEFAULT_MAX_SOURCE_BYTES;
 
   var generation       = 0;
   var lastResealedAt   = null;
@@ -149,18 +160,64 @@ function sealPemFile(opts) {
     try { fs.unlinkSync(markerPath); } catch (_e) { /* marker cleanup best-effort */ }
   }
 
-  function _resealNow() {
+  function _resealNow(actor) {
     if (resealing) return;
     resealing = true;
+    var plaintext = null;
     try {
-      var plaintext;
-      try { plaintext = fs.readFileSync(source); }
+      // H6 #1 — bounded read. fs.readFileSync without a size cap on a
+      // file the operator's renewal process writes is an OOM vector.
+      // H6 #3 — symlink TOCTOU defense. Open the file via fs.openSync
+      // with O_NOFOLLOW where possible; lstat first to verify the
+      // source isn't a symlink we don't expect, then read via fd so
+      // a swap-after-stat doesn't change which bytes we read.
+      try {
+        var lstat = fs.lstatSync(source);
+        if (lstat.isSymbolicLink()) {
+          throw new SealPemFileError("seal-pem-file/symlink-refused",
+            "source is a symlink (refused; follow + re-stat opens TOCTOU)");
+        }
+        if (lstat.size > maxSourceBytes) {
+          throw new SealPemFileError("seal-pem-file/source-too-large",
+            "source size " + lstat.size + " exceeds maxSourceBytes " + maxSourceBytes);
+        }
+        var fd = fs.openSync(source, "r");
+        try {
+          var fstat = fs.fstatSync(fd);
+          // H6 #3 — confirm the fd points at the same inode lstat saw.
+          if (fstat.ino !== lstat.ino || fstat.size > maxSourceBytes) {
+            throw new SealPemFileError("seal-pem-file/toctou-detected",
+              "source mutated between lstat and open (TOCTOU defense)");
+          }
+          plaintext = Buffer.alloc(fstat.size);
+          var read = 0;
+          while (read < fstat.size) {
+            var n = fs.readSync(fd, plaintext, read, fstat.size - read, null);
+            if (n === 0) break;
+            read += n;
+          }
+          if (read !== fstat.size) {
+            throw new SealPemFileError("seal-pem-file/short-read",
+              "short read: " + read + " of " + fstat.size + " bytes");
+          }
+        } finally {
+          try { fs.closeSync(fd); } catch (_e) { /* close best-effort */ }
+        }
+      }
       catch (e) {
         var err = new SealPemFileError("seal-pem-file/source-read-failed",
           "vault.sealPemFile: failed to read source '" + source + "': " + e.message);
         lastError = err;
         _emitAudit("read_failed", "failure", { source: source, error: e.message });
-        if (onError) { try { onError(err); } catch (_e) { /* drop-silent */ } }
+        if (onError) {
+          try { onError(err); }
+          catch (cbErr) {
+            // H6 #7 — operator callback throw is captured in audit
+            // rather than dropped silently.
+            _emitAudit("on_error_callback_failed", "failure",
+              { error: cbErr && cbErr.message });
+          }
+        }
         return;
       }
       try {
@@ -172,7 +229,13 @@ function sealPemFile(opts) {
         _emitAudit("seal_failed", "failure", {
           source: source, destination: destination, error: e2.message,
         });
-        if (onError) { try { onError(err2); } catch (_e) { /* drop-silent */ } }
+        if (onError) {
+          try { onError(err2); }
+          catch (cbErr) {
+            _emitAudit("on_error_callback_failed", "failure",
+              { error: cbErr && cbErr.message });
+          }
+        }
         return;
       }
       generation += 1;
@@ -183,6 +246,11 @@ function sealPemFile(opts) {
         destination: destination,
         bytes:      plaintext.length,
         generation: generation,
+        // H6 #8 — actor is captured when forceReseal({ actor }) is
+        // called explicitly. Watcher-driven resealings record actor=null
+        // (the kernel's mtime-change notification has no operator).
+        actor:      (actor && actor.actorId) || null,
+        actorReason: (actor && actor.reason) || null,
       });
       if (onResealed) {
         try {
@@ -193,9 +261,18 @@ function sealPemFile(opts) {
             resealedAt: lastResealedAt,
             generation: generation,
           });
-        } catch (_e) { /* drop-silent */ }
+        } catch (cbErr) {
+          // H6 #7 — operator callback throw lands in audit.
+          _emitAudit("on_resealed_callback_failed", "failure",
+            { error: cbErr && cbErr.message });
+        }
       }
     } finally {
+      // H6 #2 — zero plaintext PEM bytes from the heap. V8 may have
+      // copied the buffer internally (string interning, GC compaction)
+      // but the explicit zero ensures the operator-visible buffer no
+      // longer holds the secret.
+      if (plaintext) { try { safeBuffer.secureZero(plaintext); } catch (_e) { /* best-effort */ } }
       resealing = false;
       if (pendingMtime) {
         // A change event arrived while we were resealing — reseal again
@@ -271,8 +348,11 @@ function sealPemFile(opts) {
     get watching()         { return watching; },
     // Force a reseal — useful for tests and operator-triggered rotations
     // (e.g. after a manual ACME renewal). Idempotent: produces an
-    // updated destination from the current source bytes.
-    forceReseal:           _resealNow,
+    // updated destination from the current source bytes. Accepts
+    // { actorId, reason } for forensic audit-trail capture (H6 #8).
+    forceReseal:           function (actorOpts) {
+      _resealNow(actorOpts && typeof actorOpts === "object" ? actorOpts : null);
+    },
   };
 }
 

package/package.json

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

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:1751cf74-fcc9-495e-a159-bac5eb2565b3",
+  "serialNumber": "urn:uuid:a6056d34-71d3-41f1-a99f-80454c5b2780",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-07T07:40:58.458Z",
+    "timestamp": "2026-05-07T13:31:44.359Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.8.18",
+      "bom-ref": "@blamejs/core@0.8.25",
       "type": "library",
       "name": "blamejs",
-      "version": "0.8.18",
+      "version": "0.8.25",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.8.18",
+      "purl": "pkg:npm/%40blamejs/core@0.8.25",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.8.18",
+      "ref": "@blamejs/core@0.8.25",
       "dependsOn": []
     }
   ]