@blamejs/core 0.13.33 → 0.13.34

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.34 (2026-05-29) — **Corrupt TLS certs self-heal at boot, and graceful shutdown no longer loses the final DB flush.** Two failure-mode fixes in the same family as the encrypted-DB recovery in 0.13.33. The cert manager treated a corrupt sealed cert or key worse than a missing one: a missing file re-issues via ACME, but a corrupt one let a raw decrypt error escape out of start(), so the same bad file was read on every boot — an unrecoverable crash loop. A corrupt sealed cert/key is now treated like an absent one and re-issued, and a corrupt derived meta.json is re-derived rather than fatal; the ACME account key (which binds order history) instead fails with an actionable error rather than a raw throw. On the shutdown side, an encrypted database that failed its final re-encrypt used to delete its plaintext working copy anyway, discarding every write since the last periodic flush; it now keeps the working copy so the next boot recovers it. The shutdown orchestrator also gains a hard-deadline watchdog: when the operator delegates signal handling to it, a phase that never settles can no longer hold the process open until the supervisor SIGKILLs it (which would skip the final DB re-encrypt) — the watchdog forces a clean exit, so exit handlers still flush. The wiki production and base compose files set a stop_grace_period above that budget so a docker stop or rolling redeploy lets the re-encrypt finish. **Changed:** *Shutdown watchdog forces a clean, DB-flushing exit if a phase hangs* — The graceful-shutdown orchestrator uses soft per-phase timeouts — on expiry the underlying work keeps running — so a phase that never settles could hold the event loop open past the grace window, after which a container supervisor SIGKILLs the process and skips the final DB re-encrypt. When the operator opts into signal handling, a watchdog now forces `process.exit` `graceMs + forceExitMarginMs` after the signal; exit runs the registered handlers (the DB re-encrypt), so the last flush still happens. A new `forceExitMarginMs` option (default 5000) tunes the headroom; set the container stop grace above `graceMs + forceExitMarginMs`. · *Wiki compose sets stop_grace_period above the shutdown budget* — `examples/wiki/docker-compose.yml` and `docker-compose.prod.yml` now set `stop_grace_period: 40s`. Docker's 10s default would SIGKILL the container before the 30s shutdown budget reaches the DB re-encrypt phase, losing the final flush on a `docker stop` or rolling redeploy. The production note also reminds PaaS platforms that regenerate the compose (Coolify, Dokku, CapRover) to set the stop grace via the platform UI alongside the persistent-storage mount and `--shm-size`. **Fixed:** *A corrupt sealed TLS cert or key re-issues instead of crash-looping at boot* — `b.cert`'s start path read the sealed `cert.pem`/`key.pem` and let a raw unseal/decrypt error escape if the file was truncated or corrupt, so a managed restart read the same bad file on every boot — a crash loop, and worse handling than an absent file (which already re-issues). A corrupt sealed cert/key is now treated like a missing one: it is logged, an audit event is emitted, and the certificate is re-issued via ACME. A corrupt derived `meta.json` is likewise re-derived rather than throwing `cert/bad-meta`. · *Unreadable ACME account key fails with an actionable error, not a raw decrypt throw* — Unlike a re-issuable certificate, the ACME account key binds existing order and authorization history, so it is not silently regenerated on corruption. An unreadable `account/jwk.json.sealed` now raises `cert/account-key-unreadable` naming the file and the recovery (restore from backup, or delete to register a fresh account) instead of letting a raw decrypt/parse error escape out of start(). · *Encrypted DB keeps its working copy when the final shutdown re-encrypt fails* — `db.close()` re-encrypts the tmpfs working copy to `db.enc`, then deletes the working copy. If that final re-encrypt failed (a full `/dev/shm`, a full disk), the delete still ran, discarding every write since the last periodic flush and leaving only the older `db.enc`. The working copy is now kept whenever the re-encrypt fails, so the next boot's integrity-probed recovery picks up the latest writes (and still falls back to `db.enc` if the working copy is itself corrupt). `db.enc` is never modified by this path. **Detectors:** *Cross-artifact guard that stop_grace_period covers the shutdown budget* — A new codebase check fails if either wiki compose file omits `stop_grace_period` or sets it below the orchestrator's `graceMs` plus the watchdog margin read from `lib/app-shutdown.js`, so raising the shutdown budget without bumping the compose — or dropping the setting — cannot silently reopen the SIGKILL-before-re-encrypt data-loss window.
+
 - v0.13.33 (2026-05-28) — **Encrypted-mode DB recovers from a corrupt tmpfs working copy instead of crash-looping.** In encrypted-at-rest mode the live SQLite copy is decrypted into a tmpfs working file and re-encrypted to db.enc periodically. If that working copy was corrupted (an unclean shutdown, or a full tmpfs — Docker's /dev/shm defaults to 64 MiB), the boot path trusted it because its mtime was newer than db.enc, so db.init failed its integrity gate with "database disk image is malformed" identically on every boot — an unrecoverable crash loop. db now integrity-probes the newer working copy before trusting it: if it is unreadable, the working copy is discarded and db.enc (the last-good encrypted snapshot) is re-decrypted, so the next boot self-heals. db.enc is never modified by this path, and a genuinely-corrupt db.enc still fails loudly rather than wiping data. The boot error on an unreadable database is now actionable (it names the tmpfs-size cause and the recovery). The wiki production compose also gains the storage settings encrypted mode needs. **Fixed:** *Corrupt tmpfs working copy no longer causes a boot crash loop (encrypted-at-rest mode)* — `db.init`'s crash-recovery path preferred a newer tmpfs working copy over `db.enc` unconditionally. When that copy was corrupt (truncated by an unclean shutdown or a full `/dev/shm`), every boot trusted it and failed the integrity gate the same way — an unrecoverable loop. The newer working copy is now integrity-probed (`PRAGMA quick_check`); if it is unreadable it is discarded and `db.enc` — the last-good encrypted snapshot — is re-decrypted, so boot self-heals. `db.enc` is never modified, so this only ever rolls back to the persistent copy; if `db.enc` is also corrupt, boot still fails loudly (no silent data loss). A regression test pins the recovery. · *Actionable boot error when the database is unreadable* — When SQLite reports a database too corrupt to even run an integrity check, the boot error now names the likely cause and recovery instead of surfacing the raw "database disk image is malformed": in encrypted mode it points at the tmpfs working copy and the most common operational cause (Docker's 64 MiB `/dev/shm` default — raise it via `shm_size` / `--shm-size`), or restoring `db.enc` / the DB file from backup. · *Wiki production compose ships the storage encrypted mode needs* — `examples/wiki/docker-compose.prod.yml` now sets `shm_size: '512m'` (so the encrypted-mode tmpfs working copy has headroom above Docker's 64 MiB default) and mounts a persistent `wiki-data` volume at `/data` (so `db.enc` + sealed keys survive container recreate, host reboot, and image redeploys, and give a restore point). A note flags that PaaS platforms which regenerate the compose on deploy (Coolify, Dokku, CapRover, …) must set both via the platform UI — a persistent-storage mount for `/data` and a `--shm-size 512m` custom option.
 
 - v0.13.32 (2026-05-28) — **`b.auditDailyReview` enforces notify under the sox-404 posture; compliance doc corrections.** b.auditDailyReview documented `sox-404` (SOX §404 ICFR — the internal-controls regime this primitive serves) as one of the postures that make a `notify` callback mandatory at construction, but the enforcement set used only `sox`, so pinning `posture: "sox-404"` without a notify channel was silently accepted. `sox-404` is now in the mandatory-notify set, so the advertised guarantee holds (a regression test pins it). The rest are documentation corrections with no behavior change: b.compliance.posturesByDomain / posturesByJurisdiction examples showed small fixed arrays where the functions return every matching posture (the catalog has grown); b.dataAct's surface list named two methods that do not exist (the real surface is declareProduct / recordUserAccess / shareWithThirdParty / recordSwitchRequest, with gatekeeper refusal folded into shareWithThirdParty); b.secCyber.eightKArtifact's documented return key `audit` is actually `deadlineBusinessDays`; and b.compliance.aiAct.transparency's helper summary named `cspMetaTag` / a `watermark({ kind })` argument that are really `metaTags` / `watermark({ mediaKind })`. **Fixed:** *`b.auditDailyReview` requires a notify channel under the `sox-404` posture* — The docs listed `sox-404` among the postures that make a `notify` callback mandatory at create-time, but the enforcement set contained only `sox` — so `posture: "sox-404"` without `notify` was accepted instead of refused. `sox-404` (SOX §404 ICFR) is now in the mandatory-notify set, matching the documented guarantee; constructing without a notify channel under it throws `auditDailyReview/notify-required-under-posture`. · *`b.compliance` jurisdiction/domain lister examples no longer enumerate a stale fixed set* — `posturesByDomain` and `posturesByJurisdiction` return every posture matching the domain/jurisdiction, but their `@example`s showed small fixed arrays from before the posture catalog grew. The examples now show a representative prefix with `...` and note they return the full matching set. · *`b.dataAct` surface list matches the real methods* — The module surface listed `userAccessible(...)` and `refuseGatekeeper(...)`, neither of which exists. The real surface is `declareProduct` / `recordUserAccess` / `shareWithThirdParty` / `recordSwitchRequest`, and DMA-gatekeeper refusal (Art 32 §1) is enforced inside `shareWithThirdParty`. The doc now reflects that. · *`b.secCyber.eightKArtifact` documented return shape corrected* — The signature line showed `{ artifact, deadline, audit }`; the function returns `{ artifact, deadline, deadlineBusinessDays }` (there is no `audit` key). The doc now matches. · *`b.compliance.aiAct.transparency` helper names corrected* — The helper summary named a `cspMetaTag(...)` function and a `watermark({ kind })` argument; the real names are `metaTags(...)` and `watermark({ mediaKind })`. Calling the documented names threw. Also corrected: a `b.aiAdverseDecision` illustration showed an ECOA `statutoryDeadlines` shape that didn't match the regime's actual deadlines.

package/lib/app-shutdown.js

@@ -53,6 +53,10 @@ var AppShutdownError = defineClass("AppShutdownError", { alwaysPermanent: true }
 var log = boot("app-shutdown");
 
 var DEFAULT_GRACE_MS = C.TIME.seconds(30);
+// Headroom between the shutdown grace budget and the hard forced-exit
+// watchdog, so the watchdog fires before a container supervisor's own
+// stop-grace SIGKILL (set stop_grace_period > graceMs + this margin).
+var FORCE_EXIT_MARGIN_MS = C.TIME.seconds(5);
 
 /**
  * @primitive b.appShutdown.create
@@ -71,6 +75,7 @@ var DEFAULT_GRACE_MS = C.TIME.seconds(30);
  *
  * @opts
  *   graceMs:               number,    // total budget across all phases (default 30000)
+ *   forceExitMarginMs:     number,    // headroom after graceMs before the signal-handler watchdog forces exit (default 5000); set the container stop grace above graceMs + this
  *   phases:                array,     // [{ name, run: async fn, timeoutMs? }]
  *   installSignalHandlers: boolean,   // wire SIGTERM/SIGINT (default false)
  *   signals:               array,     // signal names (default ["SIGTERM","SIGINT"])
@@ -94,6 +99,9 @@ function create(opts) {
   numericBounds.requirePositiveFiniteIntIfPresent(opts.graceMs,
     "app-shutdown.create: opts.graceMs", AppShutdownError, "app-shutdown/bad-grace-ms");
   var graceMs = opts.graceMs !== undefined ? opts.graceMs : DEFAULT_GRACE_MS;
+  numericBounds.requirePositiveFiniteIntIfPresent(opts.forceExitMarginMs,
+    "app-shutdown.create: opts.forceExitMarginMs", AppShutdownError, "app-shutdown/bad-force-exit-margin-ms");
+  var forceExitMarginMs = opts.forceExitMarginMs !== undefined ? opts.forceExitMarginMs : FORCE_EXIT_MARGIN_MS;
   var phases = Array.isArray(opts.phases) ? opts.phases.slice() : [];
   var installSignalHandlers = !!opts.installSignalHandlers;
   for (var i = 0; i < phases.length; i++) {
@@ -224,6 +232,30 @@ function create(opts) {
   function _signalCallback(sig) {
     return function () {
       log("received " + sig + " — initiating graceful shutdown");
+      // Hard-deadline safety net. Per-phase budgets use a SOFT timeout
+      // (withTimeout lets the underlying work keep running on expiry), so
+      // shutdown() RESOLVING does not guarantee the process EXITS: a hung
+      // phase's leaked handle (a socket that won't close, a timer that keeps
+      // firing) can hold the event loop alive past the grace window, after
+      // which the supervisor SIGKILLs us and the final DB re-encrypt is lost.
+      // Arm an unref'd watchdog that forces a clean exit at the deadline.
+      // It is deliberately NOT cleared when shutdown() resolves — the whole
+      // point is to catch the case where the orchestration finished but the
+      // process won't die. unref() so it never itself keeps us alive: a clean
+      // shutdown with no leaked handles exits naturally well before it fires.
+      // process.exit() runs the registered exit handlers (db re-encrypts
+      // there), so the last flush still happens.
+      var watchdog = setTimeout(function () {
+        log.error("shutdown exceeded " + (graceMs + forceExitMarginMs) +
+          "ms without the process exiting — forcing exit (exit handlers run " +
+          "the final DB flush) before the supervisor SIGKILLs");
+        // Bounded forced exit after the grace deadline, armed ONLY inside the
+        // signal handler (operator opted into installSignalHandlers,
+        // delegating process lifecycle to the orchestrator).
+        // allow:process-exit — operator-delegated lifecycle, watchdog only
+        process.exit(process.exitCode || 1);
+      }, graceMs + forceExitMarginMs);
+      if (typeof watchdog.unref === "function") watchdog.unref();
       shutdown().then(function (result) {
         if (process.exitCode === undefined || process.exitCode === 0) {
           process.exitCode = result.ok ? 0 : 1;

package/lib/cert.js

@@ -54,6 +54,7 @@ var atomicFile    = require("./atomic-file");
 var safeJson      = require("./safe-json");
 var { defineClass } = require("./framework-error");
 var C             = require("./constants");
+var { boot }      = require("./log");
 
 var acme          = lazyRequire(function () { return require("./acme"); });
 var vault         = lazyRequire(function () { return require("./vault"); });
@@ -62,6 +63,7 @@ var networkTls    = lazyRequire(function () { return require("./network-tls"); }
 var bCrypto       = lazyRequire(function () { return require("./crypto"); });
 
 var CertError = defineClass("CertError");
+var log = boot("cert");
 
 var DEFAULT_RENEW_INTERVAL_MS    = C.TIME.hours(6);
 var DEFAULT_MIN_DAYS_BEFORE_EXPIRY = 14;
@@ -140,8 +142,13 @@ function _createSealedDiskStorage(opts) {
       if (!nodeFs.existsSync(p)) return null;
       try { return safeJson.parse(nodeFs.readFileSync(p, "utf8"), { maxBytes: C.BYTES.kib(16) }); }
       catch (e) {
-        throw new CertError("cert/bad-meta",
-          "cert: meta.json for '" + certName + "' is corrupt: " + e.message);
+        // meta.json is a derived index (expiry + fingerprint), not a
+        // source of truth — the sealed cert is. A corrupt meta must not
+        // block renewal: treat it as absent so _ensureCert re-derives it
+        // from a fresh issue rather than throwing out of start().
+        log.warn("cert: meta.json for '" + certName + "' unreadable (" +
+          e.message + ") — treating as absent, will re-derive");
+        return null;
       }
     },
 
@@ -413,8 +420,21 @@ function create(opts) {
       ? nodeFs.readFileSync(nodePath.join(storage.rootDir, "account/jwk.json.sealed"))
       : null;
     if (sealedBuf) {
-      var plain = (opts.storage.vault || vault().getDefaultStore()).unseal(sealedBuf);
-      var jwk = safeJson.parse(plain.toString("utf8"), { maxBytes: C.BYTES.kib(64) });
+      var jwk;
+      try {
+        var plain = (opts.storage.vault || vault().getDefaultStore()).unseal(sealedBuf);
+        jwk = safeJson.parse(plain.toString("utf8"), { maxBytes: C.BYTES.kib(64) });
+      } catch (e) {
+        // The ACME account key binds existing order + authorization
+        // history, so it is NOT auto-regenerated on corruption (unlike a
+        // re-issuable cert) — that would silently abandon the account.
+        // Fail with an actionable error naming the file + recovery instead
+        // of letting a raw decrypt/parse error escape out of start().
+        throw new CertError("cert/account-key-unreadable",
+          "cert: ACME account key 'account/jwk.json.sealed' is unreadable (" +
+          e.message + "). Restore it from backup, or delete it to register " +
+          "a fresh ACME account (this abandons prior order history).");
+      }
       return _accountKeyFromJwk(jwk);
     }
     var pair = nodeCrypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
@@ -555,10 +575,29 @@ function create(opts) {
   // for emergency reissue / key rollover when the existing cert is
   // structurally fine but operationally compromised (suspected key
   // disclosure, CA misissuance investigation, posture-driven rotation).
+  // A corrupt sealed cert/key is RECOVERABLE state — the CA re-issues on
+  // demand. Treat an unreadable sealed file like a missing one (log +
+  // re-issue) rather than letting a raw unseal/decrypt error escape out of
+  // start(): on a managed restart the same corrupt file is read on every
+  // boot, so throwing here is an unrecoverable crash loop, and a corrupt
+  // file must never be handled worse than an absent one (which already
+  // falls through to issue). The ACME account key is the one piece NOT
+  // auto-recovered this way — see _loadOrGenerateAccountKey.
+  async function _readSealedOrReissue(relPath, certName) {
+    try {
+      return await storage.readSealed(relPath);
+    } catch (e) {
+      log.warn("cert: sealed '" + relPath + "' unreadable (" + e.message +
+        ") — re-issuing as if absent");
+      _emitAudit("cert.sealed.corrupt", "recovered", { path: relPath, name: certName });
+      return null;
+    }
+  }
+
   async function _ensureCert(certManifest, forceIssue) {
     var meta = await storage.readMeta(certManifest.name);
-    var certBuf = await storage.readSealed(certManifest.name + "/cert.pem");
-    var keyBuf  = await storage.readSealed(certManifest.name + "/key.pem");
+    var certBuf = await _readSealedOrReissue(certManifest.name + "/cert.pem", certManifest.name);
+    var keyBuf  = await _readSealedOrReissue(certManifest.name + "/key.pem", certManifest.name);
     if (!forceIssue && meta && certBuf && keyBuf &&
         meta.expiresAt > Date.now() + minDaysBeforeExpiry * C.TIME.days(1)) {
       // Cached, not due for renewal yet.

package/lib/db.js

@@ -1997,11 +1997,19 @@ function close() {
   // Order: encrypt while the DB is still open (so the file is consistent),
   // then close the SQLite handle (releases the file lock on Windows),
   // THEN unlink the plaintext sidecar files.
-  try { encryptToDisk(); } catch (e) {
-    log.error("close: final encrypt failed: " + e.message);
+  var encryptOk = false;
+  try { encryptToDisk(); encryptOk = true; } catch (e) {
+    log.error("close: final encrypt failed: " + e.message +
+      " — keeping the plaintext working copy so the next boot can recover " +
+      "the latest writes (db.enc still holds the prior snapshot)");
   }
   try { database.close(); } catch (_e) { /* already closed */ }
-  if (atRest === "encrypted") removePlaintextFiles();
+  // Only discard the plaintext working copy once it has been safely
+  // re-encrypted. If the final encrypt failed (full /dev/shm, disk-full),
+  // the working copy is the ONLY carrier of writes since the last periodic
+  // flush — keep it so decryptToTmp's newer-mtime recovery picks it up next
+  // boot (integrity-probed, falling back to db.enc if it is itself corrupt).
+  if (atRest === "encrypted" && encryptOk) removePlaintextFiles();
   database = null;
   initialized = false;
 }

package/package.json

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

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:b63cfcae-7595-4c46-9fd5-8d4a36ad0b85",
+  "serialNumber": "urn:uuid:315508ca-8141-48dc-aa50-76d4a8892704",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-29T04:39:40.351Z",
+    "timestamp": "2026-05-29T12:27:08.508Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.33",
+      "bom-ref": "@blamejs/core@0.13.34",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.33",
+      "version": "0.13.34",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.33",
+      "purl": "pkg:npm/%40blamejs/core@0.13.34",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.33",
+      "ref": "@blamejs/core@0.13.34",
       "dependsOn": []
     }
   ]