@blamejs/core 0.13.18 → 0.13.19

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.19 (2026-05-27) — **`auditTools` export / archive / forensic-snapshot can return the bundle as bytes — no output directory for serverless / read-only filesystems.** b.auditTools.exportSlice, b.auditTools.archive, and b.auditTools.forensicSnapshot required an `out` directory to write the encrypted bundle (rows.enc + optional checkpoint.enc + manifest.json), which is unusable on a read-only or ephemeral serverless filesystem. Each now accepts `returnBytes: true` instead of `out` and returns the bundle as an in-memory `{ filename: Buffer }` map — ready to stream to object storage or over the wire with no filesystem access. `out` and `returnBytes` are mutually exclusive. The on-disk path is unchanged. The bundle's encryption (XChaCha20-Poly1305 + Argon2id), chain-proof material, and manifest checksums are identical to the written bundle, so an in-memory bundle written to disk verifies exactly as one produced by the `out` path. **Added:** *`returnBytes` on `auditTools.exportSlice` / `archive` / `forensicSnapshot` — in-memory bundles* — Pass `returnBytes: true` (and omit `out`) to get the encrypted audit bundle as an in-memory `{ filename: Buffer }` map instead of a directory write — the read-only / serverless path. `exportSlice` / `archive` return `{ manifest, files, rowCount, range }`; `forensicSnapshot` returns `{ ...manifest, files }` where `files` carries the slice's `rows.enc` + `manifest.json` plus the `forensic-snapshot.json` incident wrapper. The encryption, chain proof, and manifest checksums match the on-disk bundle byte-for-byte, so the bytes verify with `verifyBundle` once written out. `out` and `returnBytes` are mutually exclusive (passing both throws). **Fixed:** *`auditTools.forensicSnapshot` now honors the `since` window instead of capturing the entire audit history* — `forensicSnapshot` passed its `since` bound to the slice exporter under the wrong option name, so the time filter was silently dropped and the snapshot bundled every audit row regardless of `since`. The window is now applied — a snapshot scoped to an incident window contains only that window's rows. The snapshot manifest's `auditSliceFile` field, previously always undefined, now records the slice location.
+
 - v0.13.18 (2026-05-27) — **`bodyParser` multipart can buffer uploads in memory — no tmp directory for serverless / read-only filesystems.** The multipart/form-data sub-parser previously streamed every file part to a tmp directory on disk (os.tmpdir() by default), which fails on a read-only or ephemeral serverless filesystem. A new multipart.storage option selects where file parts land: "disk" (default, unchanged — req.files[].path points at a tmp file cleaned up on response end) or "memory" (req.files[].buffer holds the assembled bytes, with no filesystem access at all). Both modes enforce the same per-file (fileSize), per-field, and total-request (totalSize) caps, so memory mode adds no new memory-exhaustion surface. The file object shape is stable across both modes — disk sets path with buffer null, memory sets buffer with path null — so a handler branches on whichever is non-null. An invalid storage value is rejected when the middleware is constructed. **Added:** *`bodyParser` multipart `storage: "memory"` — buffer uploads in RAM instead of a tmp directory* — `b.middleware.bodyParser({ multipart: { storage: "memory" } })` buffers each uploaded file part in memory and exposes it as `req.files[].buffer` (a Buffer), with no `os.tmpdir()` write and no tmp-file cleanup — the read-only / serverless path. The default `storage: "disk"` is unchanged: file parts stream to a tmp file, `req.files[].path` points at it, and it is removed when the response finishes. Both modes apply the existing `fileSize` / per-field `maxBytes` / `totalSize` caps and SHA3-512 hash each part during streaming, so memory mode is bounded by the same limits and adds no new DoS surface. The `req.files[]` shape is stable across modes (disk: `path` set, `buffer` null; memory: `buffer` set, `path` null). A `storage` value other than `"disk"` or `"memory"` throws a `TypeError` at construction.
 
 - v0.13.17 (2026-05-27) — **Template engine can render from a string with no views directory — for serverless / read-only filesystems.** b.template.create previously required a viewsDir that exists on disk, and rendering always read the template (and its layout/partials) from that directory — unusable on a read-only or ephemeral serverless filesystem where the templates aren't on disk. The engine now accepts a source string directly: viewsDir is optional, and the returned engine exposes renderString(source, data?, opts?) and compileString(source, opts?) that compile and render from a string with no disk read. {% extends %} and {{> partial}} in a string source resolve through an operator-supplied opts.resolve(name) -> string callback (without it, an extends throws a clear error and a missing partial inlines empty, matching the file path). The same HTML-escaping, expression grammar, and extends/partial-depth caps apply. The file-backed render / compile / precompileAll still work exactly as before when a viewsDir is configured, and now refuse with a clear error when one isn't. **Added:** *`engine.renderString` / `engine.compileString` — render templates from a string, no viewsDir* — `b.template.create({})` (no `viewsDir`) returns a string-only engine; `renderString(source, data?, { resolve })` and `compileString(source, { resolve })` compile and render from a source string with zero filesystem access — the read-only / serverless path. `{% extends %}` and `{{> partial}}` resolve through `opts.resolve(name) -> string`. The HTML escaping, grammar, and depth caps are identical to the file path. When a `viewsDir` IS configured, `render`/`compile`/`precompileAll` behave exactly as before; without one they refuse with `viewsDir not configured`. `renderString(source, { resolve })` may omit the data argument — an opts object carrying a function `resolve` is recognized as opts, not data. **Security:** *Vendored `@simplewebauthn/server` refreshed 13.3.0 → 13.3.1* — The vendored WebAuthn server bundle (`b.auth.passkey`'s registration/authentication verification) is refreshed to the latest upstream patch, with the MANIFEST version, CPE, and SHA-256 integrity hashes updated and the bundle re-verified.

package/README.md

@@ -221,7 +221,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **PII redaction** — `b.redact`
 - **Decoy detection** — canary-credential / decoy-record framework auditing every positive lookup as `honeytoken.tripped` (`b.honeytoken`)
 - **Boot assertions** — operator-callable security policy assertions (`b.security.assertProduction`); tamper-evident config-baseline drift detection signed with audit-signing key + at-boot vendor-bundle SHA-256 integrity verification across `lib/vendor/*` (`b.configDrift`, `b.configDrift.verifyVendorIntegrity`)
-- **CSP reports + forensic export** — `b.middleware.cspReport`; post-incident audit-bundle composer (`b.auditTools.forensicSnapshot`)
+- **CSP reports + forensic export** — `b.middleware.cspReport`; post-incident audit-bundle composer (`b.auditTools.forensicSnapshot`); audit export / archive / forensic snapshot write to disk or return the encrypted bundle in memory (`returnBytes`) for read-only / serverless filesystems
 
 ### i18n + format helpers
 

package/lib/atomic-file.js

@@ -146,14 +146,18 @@ function fsync(fd) {
  *   b.atomicFile.fsyncDir("/var/lib/blamejs/data");
  */
 function fsyncDir(dirPath) {
-  // CodeQL js/insecure-temporary-file: dirPath is an operator-supplied
-  // framework data directory (e.g. /var/lib/blamejs/data) — never an
-  // os.tmpdir-reachable path. The fd is used solely for fsync and is
-  // closed immediately; no read or write occurs through it, so the
-  // tmp-file heuristic does not apply. Owner-only 0o700 dataDir
-  // perms are set by ensureDir.
+  // CodeQL js/insecure-temporary-file: this is a read-only open of an
+  // EXISTING directory to fsync its inode — no file is created, so the
+  // predictable-temp-name / symlink-race the query targets does not
+  // apply. The fd is opened "r", fsynced, and closed immediately; no
+  // write goes through it. The directory itself is created 0o700 by
+  // ensureDir. dirPath is normally an operator data dir (e.g.
+  // /var/lib/blamejs/data); when a caller fsyncs a dir under os.tmpdir
+  // (test fixtures via fs.mkdtempSync, or an audit bundle written to a
+  // tmp `out`), mkdtempSync already guarantees a unique 0o700 dir, so
+  // there is still no race surface.
   try {
-    var fd = nodeFs.openSync(dirPath, "r");
+    var fd = nodeFs.openSync(dirPath, "r"); // lgtm[js/insecure-temporary-file] — read-only fsync of an existing dir; no temp file created
     try { nodeFs.fsyncSync(fd); } catch (_e) { /* Windows rejects directory fsync */ }
     finally { nodeFs.closeSync(fd); }
   } catch (_e) { /* dir fsync is best-effort across filesystems */ }

package/lib/audit-tools.js

@@ -291,36 +291,43 @@ async function _defaultReadPredecessorRowHash(firstCounter) {
 
 // ---- Bundle writer ----
 
-async function _writeBundle(args) {
-  var outDir       = args.outDir;
+// Assemble the encrypted bundle entirely in memory: returns the
+// manifest plus an ordered { filename: Buffer } map. Pure — no
+// filesystem touch — so it backs both the on-disk writer and the
+// returnBytes / serverless path. The bundle is always the same 2-3
+// files (rows.enc, optional checkpoint.enc, manifest.json) whether it
+// lands on disk or ships as bytes.
+async function _buildBundle(args) {
   var kind         = args.kind;
   var rows         = args.rows;
   var checkpoint   = args.checkpoint || null;
   var passphrase   = args.passphrase;
   var predecessorRowHash = args.predecessorRowHash;
 
-  atomicFile.ensureDir(outDir);
-
   var firstRow = rows[0];
   var lastRow  = rows[rows.length - 1];
+  var files = {};
 
   // 1. Encrypt the rows JSONL
   var jsonl = rows.map(function (r) {
     return JSON.stringify(_rowToWireForm(r));
   }).join("\n") + "\n";
   var rowsEnc = await backupCrypto.encryptWithFreshSalt(jsonl, passphrase);
-  atomicFile.writeSync(nodePath.join(outDir, "rows.enc"), rowsEnc.encrypted, { fileMode: 0o600 });
+  files["rows.enc"] = rowsEnc.encrypted;
 
   // 2. (archive) Encrypt the checkpoint JSON
   var checkpointSalt = null;
+  var checkpointEncrypted = null;
   if (checkpoint) {
     var ckptJson = _canonicalize(_rowToWireForm(checkpoint));
     var ckptEnc = await backupCrypto.encryptWithFreshSalt(ckptJson, passphrase);
-    atomicFile.writeSync(nodePath.join(outDir, "checkpoint.enc"), ckptEnc.encrypted, { fileMode: 0o600 });
+    files["checkpoint.enc"] = ckptEnc.encrypted;
     checkpointSalt = ckptEnc.salt;
+    checkpointEncrypted = ckptEnc.encrypted;
   }
 
-  // 3. Build manifest
+  // 3. Build manifest — checksums computed from the in-memory buffers
+  // (no read-back of what we just wrote).
   var manifest = {
     format:         BUNDLE_FORMAT,
     kind:           kind,
@@ -342,8 +349,8 @@ async function _writeBundle(args) {
     },
     checksum: {
       rowsSha3_512:       backupCrypto.checksum(rowsEnc.encrypted),
-      checkpointSha3_512: checkpointSalt
-        ? backupCrypto.checksum(nodeFs.readFileSync(nodePath.join(outDir, "checkpoint.enc")))
+      checkpointSha3_512: checkpointEncrypted
+        ? backupCrypto.checksum(checkpointEncrypted)
         : null,
     },
   };
@@ -355,9 +362,22 @@ async function _writeBundle(args) {
       checkpointId:         String(checkpoint._id),
     };
   }
+  files["manifest.json"] = Buffer.from(_canonicalize(manifest), "utf8");
+  return { manifest: manifest, files: files };
+}
+
+async function _writeBundle(args) {
+  var outDir = args.outDir;
+  var built  = await _buildBundle(args);
+
+  atomicFile.ensureDir(outDir);
+  atomicFile.writeSync(nodePath.join(outDir, "rows.enc"), built.files["rows.enc"], { fileMode: 0o600 });
+  if (built.files["checkpoint.enc"]) {
+    atomicFile.writeSync(nodePath.join(outDir, "checkpoint.enc"), built.files["checkpoint.enc"], { fileMode: 0o600 });
+  }
   var manifestPath = nodePath.join(outDir, "manifest.json");
-  atomicFile.writeSync(manifestPath, _canonicalize(manifest), { fileMode: 0o600 });
-  return { manifest: manifest, manifestPath: manifestPath };
+  atomicFile.writeSync(manifestPath, built.files["manifest.json"], { fileMode: 0o600 });
+  return { manifest: built.manifest, manifestPath: manifestPath };
 }
 
 // ---- Bundle reader ----
@@ -437,8 +457,14 @@ async function _readBundle(inDir, passphrase) {
  * Refuses if `opts.out` exists, no rows match, or no signed
  * checkpoint covers the slice (run `b.audit.checkpoint()` first).
  *
+ * Pass `returnBytes: true` instead of `out` for the bundle as an
+ * in-memory `{ filename: Buffer }` map (`rows.enc` + `checkpoint.enc`
+ * + `manifest.json`) — the read-only / serverless path. `out` and
+ * `returnBytes` are mutually exclusive.
+ *
  * @opts
- *   out:        string,         // fresh directory path for the bundle
+ *   out:        string,         // fresh directory path (omit when returnBytes)
+ *   returnBytes:boolean,        // true → return { manifest, files } in memory, no disk
  *   before:     number|Date|string,  // archive rows recordedAt < this
  *   passphrase: Buffer|string,  // bundle-encryption passphrase
  *
@@ -455,7 +481,12 @@ async function _readBundle(inDir, passphrase) {
 async function archive(opts) {
   opts = opts || {};
   _requirePassphrase(opts.passphrase);
-  _requireOutDir(opts.out, "archive");
+  var returnBytes = opts.returnBytes === true;
+  if (returnBytes && opts.out !== undefined) {
+    throw new AuditToolsError("audit-tools/out-and-return-bytes",
+      "archive: specify either opts.out (write to disk) or opts.returnBytes (in-memory bytes), not both");
+  }
+  if (!returnBytes) _requireOutDir(opts.out, "archive");
   var beforeMs = _toMs(opts.before);
   if (beforeMs == null) {
     throw new AuditToolsError("audit-tools/no-before",
@@ -482,6 +513,22 @@ async function archive(opts) {
 
   var predecessorRowHash = await readPredecessorHash(firstCounter);
 
+  if (returnBytes) {
+    var built = await _buildBundle({
+      kind:       KIND_ARCHIVE,
+      rows:       rows,
+      checkpoint: checkpoint,
+      passphrase: opts.passphrase,
+      predecessorRowHash: predecessorRowHash,
+    });
+    return {
+      manifest: built.manifest,
+      files:    built.files,
+      rowCount: rows.length,
+      range:    built.manifest.range,
+    };
+  }
+
   var written = await _writeBundle({
     outDir:     opts.out,
     kind:       KIND_ARCHIVE,
@@ -517,8 +564,15 @@ async function archive(opts) {
  * action filter that drops intermediate counters is rejected with
  * `audit-tools/non-contiguous`.
  *
+ * Pass `returnBytes: true` instead of `out` to get the bundle as an
+ * in-memory `{ filename: Buffer }` map (`rows.enc` + `manifest.json`)
+ * with no filesystem touch — the read-only / serverless path; ship it
+ * to object storage or over the wire. `out` and `returnBytes` are
+ * mutually exclusive.
+ *
  * @opts
- *   out:        string,                // fresh directory path
+ *   out:        string,                // fresh directory path (omit when returnBytes)
+ *   returnBytes:boolean,               // true → return { manifest, files } in memory, no disk
  *   from:       number|Date|string,    // recordedAt >= this (inclusive)
  *   to:         number|Date|string,    // recordedAt <= this (inclusive)
  *   action:     string,                // exact action match (optional)
@@ -536,7 +590,12 @@ async function archive(opts) {
 async function exportSlice(opts) {
   opts = opts || {};
   _requirePassphrase(opts.passphrase);
-  _requireOutDir(opts.out, "export");
+  var returnBytes = opts.returnBytes === true;
+  if (returnBytes && opts.out !== undefined) {
+    throw new AuditToolsError("audit-tools/out-and-return-bytes",
+      "export: specify either opts.out (write to disk) or opts.returnBytes (in-memory bytes), not both");
+  }
+  if (!returnBytes) _requireOutDir(opts.out, "export");
   var fromMs = _toMs(opts.from);
   var toMs   = _toMs(opts.to);
   var readRows = opts.readRows || _defaultReadRows;
@@ -567,6 +626,22 @@ async function exportSlice(opts) {
   var firstCounter = Number(rows[0].monotonicCounter);
   var predecessorRowHash = await readPredecessorHash(firstCounter);
 
+  if (returnBytes) {
+    var built = await _buildBundle({
+      kind:       KIND_EXPORT,
+      rows:       rows,
+      checkpoint: null,
+      passphrase: opts.passphrase,
+      predecessorRowHash: predecessorRowHash,
+    });
+    return {
+      manifest: built.manifest,
+      files:    built.files,
+      rowCount: rows.length,
+      range:    built.manifest.range,
+    };
+  }
+
   var written = await _writeBundle({
     outDir:     opts.out,
     kind:       KIND_EXPORT,
@@ -852,9 +927,15 @@ async function _defaultApplyPurge(args) {
  * `audit.forensic_snapshot.composed` audit event so the act of
  * composing the snapshot is itself on-chain.
  *
+ * Pass `returnBytes: true` instead of `out` for the snapshot as an
+ * in-memory `{ filename: Buffer }` map (the slice's `rows.enc` +
+ * `manifest.json` plus `forensic-snapshot.json`) — the read-only /
+ * serverless path. `out` and `returnBytes` are mutually exclusive.
+ *
  * @opts
- *   out:        string,               // fresh directory path
- *   since:      number|Date|string,   // include rows recordedAt >= this
+ *   out:        string,               // fresh directory path (omit when returnBytes)
+ *   returnBytes:boolean,              // true → return { ...manifest, files } in memory, no disk
+ *   since:      number|Date|string,   // include rows recordedAt >= this (windowed since → now)
  *   passphrase: Buffer|string,        // bundle-encryption passphrase
  *   reason:     string,               // required incident-context reason
  *   incidentId: string,               // optional ticket / incident id
@@ -874,29 +955,39 @@ async function _defaultApplyPurge(args) {
 async function forensicSnapshot(opts) {
   opts = opts || {};
   _requirePassphrase(opts.passphrase);
-  _requireOutDir(opts.out, "forensicSnapshot");
+  var returnBytes = opts.returnBytes === true;
+  if (returnBytes && opts.out !== undefined) {
+    throw new AuditToolsError("audit-tools/out-and-return-bytes",
+      "forensicSnapshot: specify either opts.out (write to disk) or opts.returnBytes (in-memory bytes), not both");
+  }
+  if (!returnBytes) _requireOutDir(opts.out, "forensicSnapshot");
   var sinceMs = _toMs(opts.since);
   if (sinceMs == null) {
     throw new AuditToolsError("audit-tools/no-since",
       "forensicSnapshot: opts.since is required");
   }
   validateOpts.requireNonEmptyString(opts.reason, "reason", AuditToolsError, "audit-tools/no-reason");
+  // exportSlice windows by from/to — pass the requested `since` as `from`
+  // and now as `to` so the snapshot captures only the incident window
+  // rather than the entire audit history.
   var sliceResult = await exportSlice({
-    out:        opts.out,
-    since:      sinceMs,
-    until:      Date.now(),
-    passphrase: opts.passphrase,
-    readRows:   opts.readRows,
+    out:         returnBytes ? undefined : opts.out,
+    returnBytes: returnBytes,
+    from:        sinceMs,
+    to:          Date.now(),
+    passphrase:  opts.passphrase,
+    readRows:    opts.readRows,
     readCoveringCheckpoint: opts.readCoveringCheckpoint,
   });
-  // Compose snapshot manifest with operator-supplied IR context.
+  // Compose snapshot manifest with operator-supplied IR context. The
+  // audit slice lands as rows.enc inside the bundle either way.
   var manifest = {
     snapshotKind:      "forensic",
     incidentId:        opts.incidentId || null,
     reason:            opts.reason,
     actor:             opts.actor || null,
     composedAt:        new Date().toISOString(),
-    auditSliceFile:    sliceResult && sliceResult.path,
+    auditSliceFile:    returnBytes ? "rows.enc" : (sliceResult && sliceResult.manifestPath),
     auditSliceCount:   sliceResult && sliceResult.rowCount,
     runtime: {
       nodeVersion: process.version,
@@ -906,14 +997,18 @@ async function forensicSnapshot(opts) {
       uptimeSec:   Math.round(process.uptime()),
     },
   };
-  var manifestPath = require("node:path").join(opts.out, "forensic-snapshot.json");
-  require("node:fs").writeFileSync(manifestPath, _canonicalize(manifest), "utf8");
+  var manifestBytes = Buffer.from(_canonicalize(manifest), "utf8");
+  var manifestPath = null;
+  if (!returnBytes) {
+    manifestPath = nodePath.join(opts.out, "forensic-snapshot.json");
+    atomicFile.writeSync(manifestPath, manifestBytes, { fileMode: 0o600 });
+  }
   try {
     require("./audit").safeEmit({
       action:  "audit.forensic_snapshot.composed",
       outcome: "success",
       metadata: {
-        out:               opts.out,
+        out:               returnBytes ? null : opts.out,
         incidentId:        manifest.incidentId,
         reason:            opts.reason,
         actor:             opts.actor || null,
@@ -921,6 +1016,12 @@ async function forensicSnapshot(opts) {
       },
     });
   } catch (_e) { /* audit best-effort */ }
+  if (returnBytes) {
+    // Mirror the on-disk layout: the slice's files plus the IR wrapper.
+    var files = Object.assign({}, sliceResult.files);
+    files["forensic-snapshot.json"] = manifestBytes;
+    return Object.assign({}, manifest, { files: files });
+  }
   return Object.assign({}, manifest, { manifestPath: manifestPath });
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.18",
+  "version": "0.13.19",
   "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:85f02e1d-6e57-4585-9067-a882fb442bc0",
+  "serialNumber": "urn:uuid:bcf724d0-38ac-437e-86b3-47da5e8b72dc",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-27T19:52:58.359Z",
+    "timestamp": "2026-05-27T21:23:48.501Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.18",
+      "bom-ref": "@blamejs/core@0.13.19",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.18",
+      "version": "0.13.19",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.18",
+      "purl": "pkg:npm/%40blamejs/core@0.13.19",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.18",
+      "ref": "@blamejs/core@0.13.19",
       "dependsOn": []
     }
   ]