@blamejs/core 0.13.7 → 0.13.8

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.13.x
 
+- v0.13.8 (2026-05-26) — **In-memory archive extraction for read-only / serverless filesystems.** Archive readers gain an in-memory extraction path so an uploaded archive can be opened and its contents read without writing anything to disk — the case a read-only or ephemeral serverless filesystem requires. b.archive.read.zip(...).extractEntries() and b.archive.read.tar(...).extractEntries() are async generators that yield each regular file entry as { name, bytes, size }, applying the same bomb-policy caps, b.guardArchive metadata cascade (which refuses a Zip-Slip / traversal archive wholesale), and entry-type-policy refusals as the disk extract() — only the disk realpath agreement check is omitted, since nothing is written and the caller owns where the returned bytes land. Directory and link entries carry no content and are not yielded. The guard cascade is factored into one shared path so disk and in-memory extraction refuse identically. Also a documentation fix: b.archive.gz no longer claims a b.archive.zip().toGzip() convenience exists — a ZIP is already DEFLATE-compressed per entry, so gzip-wrapping it gains nothing; gzip the uncompressed tar stream (the canonical .tar.gz) instead. **Added:** *`extractEntries()` — in-memory archive extraction (ZIP + tar)* — `b.archive.read.zip(source).extractEntries(opts?)` and `b.archive.read.tar(source).extractEntries(opts?)` are async generators yielding `{ name, bytes, size }` per regular file entry, never touching disk — for serverless / read-only filesystems where the disk `extract({ destination })` path cannot run. Same bomb-policy, guard-archive cascade, and entry-type-policy refusals as disk extraction; the bytes are byte-identical to what `extract()` writes. **Fixed:** *Removed the inaccurate `b.archive.zip().toGzip()` doc claim* — The `b.archive.gz` documentation described a `b.archive.zip().toGzip()` convenience method that does not (and should not) exist: a ZIP is already DEFLATE-compressed per entry, so gzip-wrapping it would compress already-compressed data for no benefit. `b.archive.tar().toGzip()` (the real `.tar.gz`) is unchanged.
+
 - v0.13.7 (2026-05-26) — **Documentation accuracy — several primitives described shipped features as deferred.** A documentation sweep corrected primitive descriptions that still called features deferred after they shipped, so the wiki and inline docs now match the code. b.mdoc documents that device authentication (the ISO 18013-5 §9.1.3 signature variant, verifyDeviceAuth) is verified, not deferred — only the COSE_Mac0 device-auth variant remains refused. b.network.dns.dnssec documents that the root-to-zone chain walk against the IANA trust anchors (verifyChain) and NSEC / NSEC3 denial of existence (verifyDenial / nsec3Hash) ship, where the card previously said they were deferred. b.cose lists COSE_Mac0 and COSE_Encrypt0 among what it ships. The JMAP server documents its push channel, blob upload/download, and EmailSubmission handlers as present, and the submission server documents CHUNKING / BDAT as supported. A new test detector keeps this class of drift from recurring: it fails the build when a comment promises a feature lands in a version that has already shipped. **Fixed:** *Corrected `deferred`/`does-not-ship` docs for features that have shipped* — `b.mdoc` (device authentication, §9.1.3), `b.network.dns.dnssec` (chain walk + NSEC/NSEC3), `b.cose` (COSE_Mac0 + COSE_Encrypt0), the JMAP server (push, blob, EmailSubmission), and the submission server (BDAT/CHUNKING) all carried `@card`/`@intro` text describing shipped capabilities as deferred or not-shipped. The descriptions now match the implemented surface; genuinely-deferred items (the mdoc MAC variant, DNSSEC in-RDATA name canonicalization, COSE multi-signer/multi-recipient) remain documented as such. **Detectors:** *Overdue-defer detector in the codebase-pattern gate* — A new check fails the build when a comment promises a feature "lands in" / is "deferred to" / is "not supported in" a version that the package has already reached — catching stale deferral notes (a feature that shipped but whose comment still says otherwise, or a missed deadline) before they reach a release. An allowlist records the deliberate defer-with-condition exceptions.
 
 - v0.13.6 (2026-05-26) — **`b.ai.frontierModelProtocol` — California SB 53 frontier-AI obligations.** b.ai.frontierModelProtocol assesses a developer's obligations under California's Transparency in Frontier Artificial Intelligence Act — SB 53, Cal. Bus. & Prof. Code §22757.10, effective 2026-01-01 — from a model's training compute and the developer's revenue. It reports whether the model crosses the frontier threshold (more than 10^26 training FLOPs), whether the developer is a large frontier developer (prior-year revenue, with affiliates, above $500M), and the resulting obligations: every frontier developer must report critical safety incidents and publish a transparency report, and a large frontier developer must additionally publish an annual safety framework and disclose its catastrophic-risk assessment. Passing a candidate safety framework reports which required elements (risk identification, mitigation, governance, cybersecurity, standards alignment) are missing. b.ai.frontierModelProtocol.incidentReport validates a critical-incident type against the Act's four categories and computes the notification deadline to the California Office of Emergency Services — 15 days from discovery, or 24 hours when there is an imminent risk of death or serious physical injury. The ca-tfaia compliance posture was already in the catalog. **Added:** *`b.ai.frontierModelProtocol` — SB 53 threshold classification, obligations, and incident reporting* — `b.ai.frontierModelProtocol({ trainingFlops, annualRevenueUsd, framework? })` returns `isFrontierModel`, `isLargeFrontierDeveloper`, the `obligations` list, and (when a framework is supplied) its `frameworkGaps`. `b.ai.frontierModelProtocol.incidentReport({ type, discoveredAt, imminentRiskToLife? })` builds a critical-safety-incident report with the California OES recipient and a `dueAt` / `deadlineHours` computed from the 15-day (or 24-hour imminent-risk) statutory window; `type` must be one of the four categories in `INCIDENT_TYPES`. Throws `FrontierProtocolError` on malformed input.

package/README.md

@@ -228,7 +228,7 @@ The framework bundles the surface a typical Node app reaches for. Every primitiv
 - **i18n** — CLDR plural rules, Accept-Language negotiation, Intl formatters, RTL (`b.i18n`)
 - **CSV** — RFC 4180 with Excel formula-injection prevention (`b.csv`)
 - **IDs + slugs** — RFC 9562 UUID v4 + v7 (`b.uuid`); URL-safe slugs (`b.slug`)
-- **Time + archive** — TZ-aware datetime (`b.time`); ZIP creation + adversarial-safe read with bomb caps + path-traversal + LFH/CD-skew defense (`b.archive` + `b.archive.read.zip`); one-liner quarantine extraction (`b.safeArchive.extract`); fs / objectStore / http / buffer / trusted-stream adapter contract (`b.archive.adapters`)
+- **Time + archive** — TZ-aware datetime (`b.time`); ZIP creation + adversarial-safe read with bomb caps + path-traversal + LFH/CD-skew defense (`b.archive` + `b.archive.read.zip`); one-liner quarantine extraction (`b.safeArchive.extract`); in-memory extraction with no disk write for read-only / serverless filesystems (`b.archive.read.zip(...).extractEntries()` / `.tar`); fs / objectStore / http / buffer / trusted-stream adapter contract (`b.archive.adapters`)
 - **Pagination + forms** — HMAC-signed cursor pagination (`b.pagination`); HTML form rendering + validation + CSRF (`b.forms`)
 
 ### Production

package/lib/archive-gz.js

@@ -47,9 +47,11 @@ function _isGzipMagic(buf) {
  * `toAdapter(adapter)` / `digest()` — so gzip slots into the same
  * downstream sinks (object-store + filesystem + http adapters).
  *
- * Composes `b.archive.tar().toGzip(adapter)` / `b.archive.zip().
- * toGzip(adapter)` indirectly: those convenience methods call this
- * primitive after materializing their archive bytes.
+ * `b.archive.tar().toGzip(adapter)` composes this primitive after
+ * materializing the tar bytes (the canonical `.tar.gz`). There is no
+ * `zip().toGzip()` — a ZIP is already DEFLATE-compressed per entry, so
+ * gzip-wrapping it would compress already-compressed data for no gain;
+ * gzip the uncompressed tar stream instead.
  *
  * @opts
  *   level:  number,    // 0-9, default 6 (zlib default).

package/lib/archive-read.js

@@ -546,21 +546,13 @@ function zip(adapter, opts) {
     }
   }
 
-  async function extract(extractOpts) {
-    extractOpts = extractOpts || {};
-    if (typeof extractOpts.destination !== "string" || extractOpts.destination.length === 0) {
-      throw new ArchiveReadError("archive-read/no-destination",
-        "extract: opts.destination must be a non-empty string (target directory)");
-    }
-    var destination = nodePath.resolve(extractOpts.destination);
-    if (!nodeFs.existsSync(destination)) {
-      nodeFs.mkdirSync(destination, { recursive: true });
-    }
-    var loaded = await _loadCD();
-    _enforceBombPolicy(loaded.entries, bombPolicy);
-    // Compose b.guardArchive on the metadata pass — operators with a
-    // posture set declared via opts.guardProfile get the cascade.
-    var guardEntries = loaded.entries.map(function (e) {
+  // Run the b.guardArchive metadata cascade and refuse the whole archive on
+  // any critical issue. Shared by disk `extract` and in-memory `extractEntries`
+  // so both apply the identical posture-aware refusal. `auditAction` names the
+  // audit row for the refusal path.
+  function _assertGuardMetadata(loadedEntries, auditAction) {
+    if (opts.guardProfile === false) return;
+    var guardEntries = loadedEntries.map(function (e) {
       return {
         name:           e.name,
         size:           e.uncompressedSize,
@@ -573,24 +565,80 @@ function zip(adapter, opts) {
         attrs:          { externalAttrs: e.externalAttrs },
       };
     });
-    if (opts.guardProfile !== false) {
-      var profile = opts.guardProfile || "balanced";
-      var guardResult = guardArchive().validateEntries(guardEntries, { profile: profile });
-      if (guardResult && Array.isArray(guardResult.issues) && guardResult.issues.length > 0) {
-        // Refuse the whole archive when any entry trips a critical
-        // guard issue; collect every issue for the audit trail.
-        var critical = guardResult.issues.filter(function (i) { return i.severity === "critical"; });
-        if (critical.length > 0) {
-          _emitAudit(opts, "archive.read.extract.refused", "refused", {
-            entries: loaded.entries.length,
-            issues:  critical.map(function (i) { return i.ruleId; }),
-          });
-          throw new ArchiveReadError("archive-read/guard-refused",
-            "extract refused — " + critical.length + " critical guard issue(s): " +
-            critical.map(function (i) { return i.ruleId + " (" + i.snippet + ")"; }).join("; "));
-        }
+    var profile = opts.guardProfile || "balanced";
+    var guardResult = guardArchive().validateEntries(guardEntries, { profile: profile });
+    if (!guardResult || !Array.isArray(guardResult.issues) || guardResult.issues.length === 0) return;
+    var critical = guardResult.issues.filter(function (i) { return i.severity === "critical"; });
+    if (critical.length === 0) return;
+    _emitAudit(opts, auditAction, "refused", {
+      entries: loadedEntries.length,
+      issues:  critical.map(function (i) { return i.ruleId; }),
+    });
+    throw new ArchiveReadError("archive-read/guard-refused",
+      "extract refused — " + critical.length + " critical guard issue(s): " +
+      critical.map(function (i) { return i.ruleId + " (" + i.snippet + ")"; }).join("; "));
+  }
+
+  // In-memory extraction: yields each file entry's decompressed bytes WITHOUT
+  // writing to disk — for read-only / serverless filesystems. Applies the same
+  // bomb-policy, guard cascade, entry-type policy, and per-entry filename
+  // safety as `extract`; directory entries are skipped (no bytes). The realpath
+  // agreement check is disk-specific and intentionally omitted (no extraction
+  // root); the caller owns where, if anywhere, the bytes land.
+  async function* extractEntries(extractOpts) {
+    extractOpts = extractOpts || {};
+    var loaded = await _loadCD();
+    _enforceBombPolicy(loaded.entries, bombPolicy);
+    _assertGuardMetadata(loaded.entries, "archive.read.extractEntries.refused");
+    var totalDecompressed = 0;
+    var yielded = 0;
+    for (var i = 0; i < loaded.entries.length; i += 1) {
+      var entry = loaded.entries[i];
+      if (entry.isEncrypted && !extractOpts.allowEncrypted) {
+        throw new ArchiveReadError("archive-read/encrypted-entry",
+          "entry " + JSON.stringify(entry.name) + " is encrypted — not decrypted on the in-memory path");
+      }
+      var typeRefusal = _enforceEntryTypePolicy(entry, entryTypePolicy);
+      if (typeRefusal) {
+        throw new ArchiveReadError("archive-read/entry-type-refused",
+          "entry " + JSON.stringify(entry.name) + " is a " + typeRefusal +
+          " — refused by entryTypePolicy");
+      }
+      if (_isDirectoryEntry(entry.name, entry.externalAttrs)) continue;
+      // Archive-level name threats (Zip-Slip traversal, etc.) are refused for
+      // the whole archive by the guardArchive cascade above. The caller owns
+      // final placement of the returned bytes; we deliberately do NOT apply the
+      // disk-write filename policy (shell-exec extensions / reserved names) here
+      // — nothing is written, and over-filtering would drop legitimate names.
+      var lfhResult = await _verifyLfhMatchesCd(adapter, entry);
+      var body = await _decompressEntry(adapter, entry, lfhResult.dataStart, bombPolicy);
+      totalDecompressed += body.length;
+      if (totalDecompressed > bombPolicy.maxTotalDecompressedBytes) {
+        throw new ArchiveReadError("archive-read/total-too-large",
+          "cumulative uncompressed=" + totalDecompressed +
+          " exceeds maxTotalDecompressedBytes during extractEntries");
       }
+      yielded += 1;
+      yield { name: entry.name, bytes: body, size: body.length };
+    }
+    _emitAudit(opts, "archive.read.extractEntries.completed", "success", { entries: yielded });
+  }
+
+  async function extract(extractOpts) {
+    extractOpts = extractOpts || {};
+    if (typeof extractOpts.destination !== "string" || extractOpts.destination.length === 0) {
+      throw new ArchiveReadError("archive-read/no-destination",
+        "extract: opts.destination must be a non-empty string (target directory)");
     }
+    var destination = nodePath.resolve(extractOpts.destination);
+    if (!nodeFs.existsSync(destination)) {
+      nodeFs.mkdirSync(destination, { recursive: true });
+    }
+    var loaded = await _loadCD();
+    _enforceBombPolicy(loaded.entries, bombPolicy);
+    // Compose b.guardArchive on the metadata pass — operators with a
+    // posture set declared via opts.guardProfile get the cascade.
+    _assertGuardMetadata(loaded.entries, "archive.read.extract.refused");
     var written = [];
     var bytesExtracted = 0;
     var totalDecompressed = 0;
@@ -693,10 +741,11 @@ function zip(adapter, opts) {
   }
 
   return {
-    kind:    "zip-random-access",
-    inspect: inspect,
-    entries: entries,
-    extract: extract,
+    kind:           "zip-random-access",
+    inspect:        inspect,
+    entries:        entries,
+    extract:        extract,
+    extractEntries: extractEntries,
   };
 }
 

package/lib/archive-tar-read.js

@@ -276,6 +276,87 @@ function tar(adapter, opts) {
     });
   }
 
+  // Shared b.guardArchive metadata cascade — disk `extract` + in-memory
+  // `extractEntries` refuse the whole archive identically on a critical issue.
+  function _assertGuardMetadata(entries, auditAction) {
+    if (opts.guardProfile === false) return;
+    var profile = opts.guardProfile || "balanced";
+    var guardEntries = entries.map(function (e) {
+      return {
+        name:           e.name,
+        size:           e.size,
+        compressedSize: e.size,
+        isSymlink:      e.typeflag === TF_SYMLINK,
+        isHardlink:     e.typeflag === TF_HARDLINK,
+        linkTarget:     e.linkname,
+        isDirectory:    e.typeflag === TF_DIRECTORY,
+        isEncrypted:    false,
+        attrs:          { mode: e.mode },
+      };
+    });
+    var guardResult = guardArchive().validateEntries(guardEntries, { profile: profile });
+    if (!guardResult || !Array.isArray(guardResult.issues)) return;
+    var critical = guardResult.issues.filter(function (i) { return i.severity === "critical"; });
+    if (critical.length === 0) return;
+    _emitAudit(opts, auditAction, "refused", {
+      entries: entries.length,
+      issues:  critical.map(function (i) { return i.ruleId; }),
+    });
+    throw new TarError("archive-tar/guard-refused",
+      "extract refused — " + critical.length + " critical guard issue(s)");
+  }
+
+  // In-memory extraction: yields each regular file entry's bytes without
+  // writing to disk (read-only / serverless filesystems). Same guard cascade,
+  // type-policy refusals, filename safety, and bomb cap as `extract`; directory
+  // and (validated) link entries carry no content and are not yielded.
+  async function* extractEntries(extractOpts) {
+    extractOpts = extractOpts || {};
+    var allowDangerous = extractOpts.allowDangerous || {};
+    var walked = await _walk();
+    var entries = walked.entries;
+    var bytes = walked.bytes;
+    _assertGuardMetadata(entries, "archive.read.tar.extractEntries.refused");
+    var totalDecompressed = 0;
+    var yielded = 0;
+    for (var i = 0; i < entries.length; i += 1) {
+      var entry = entries[i];
+      var type = _classifyTypeflag(entry.typeflag);
+      if (type === "device" || type === "fifo" || type === "socket") {
+        throw new TarError("archive-tar/entry-type-refused",
+          "entry " + JSON.stringify(entry.name) + " is a " + type + " — refused unconditionally");
+      }
+      if (type === "symlink" && !(allowDangerous.symlinks || entryTypePolicy.symlinks)) {
+        throw new TarError("archive-tar/entry-type-refused",
+          "entry " + JSON.stringify(entry.name) + " is a symlink — refused by entryTypePolicy");
+      }
+      if (type === "hardlink" && !(allowDangerous.hardlinks || entryTypePolicy.hardlinks)) {
+        throw new TarError("archive-tar/entry-type-refused",
+          "entry " + JSON.stringify(entry.name) + " is a hardlink — refused by entryTypePolicy");
+      }
+      // Directories + (now-permitted) links carry no content bytes.
+      if (type === "directory" || type === "symlink" || type === "hardlink") continue;
+      // Archive-level name threats are refused by the guardArchive cascade
+      // above; the caller owns placement of the returned bytes, so the
+      // disk-write filename policy is intentionally not applied here.
+      // COPY the slice — bytes.subarray/slice shares the full collected-archive
+      // backing store, so a caller retaining one entry would pin the whole
+      // archive in memory, defeating the serverless memory goal. Buffer.from
+      // gives the entry its own backing store (matching the ZIP path, whose
+      // _decompressEntry already returns a fresh buffer).
+      var body = Buffer.from(bytes.subarray(entry._bodyStart, entry._bodyStart + entry.size));
+      totalDecompressed += body.length;
+      if (totalDecompressed > bombPolicy.maxTotalDecompressedBytes) {
+        throw new TarError("archive-tar/total-too-large",
+          "cumulative uncompressed=" + totalDecompressed +
+          " exceeds maxTotalDecompressedBytes during extractEntries");
+      }
+      yielded += 1;
+      yield { name: entry.name, bytes: body, size: body.length };
+    }
+    _emitAudit(opts, "archive.read.tar.extractEntries.completed", "success", { entries: yielded });
+  }
+
   async function extract(extractOpts) {
     extractOpts = extractOpts || {};
     if (typeof extractOpts.destination !== "string" || extractOpts.destination.length === 0) {
@@ -290,34 +371,7 @@ function tar(adapter, opts) {
     var walked = await _walk();
     var entries = walked.entries;
     var bytes = walked.bytes;
-    if (opts.guardProfile !== false) {
-      var profile = opts.guardProfile || "balanced";
-      var guardEntries = entries.map(function (e) {
-        return {
-          name:           e.name,
-          size:           e.size,
-          compressedSize: e.size,
-          isSymlink:      e.typeflag === TF_SYMLINK,
-          isHardlink:     e.typeflag === TF_HARDLINK,
-          linkTarget:     e.linkname,
-          isDirectory:    e.typeflag === TF_DIRECTORY,
-          isEncrypted:    false,
-          attrs:          { mode: e.mode },
-        };
-      });
-      var guardResult = guardArchive().validateEntries(guardEntries, { profile: profile });
-      if (guardResult && Array.isArray(guardResult.issues)) {
-        var critical = guardResult.issues.filter(function (i) { return i.severity === "critical"; });
-        if (critical.length > 0) {
-          _emitAudit(opts, "archive.read.tar.extract.refused", "refused", {
-            entries: entries.length,
-            issues:  critical.map(function (i) { return i.ruleId; }),
-          });
-          throw new TarError("archive-tar/guard-refused",
-            "extract refused — " + critical.length + " critical guard issue(s)");
-        }
-      }
-    }
+    _assertGuardMetadata(entries, "archive.read.tar.extract.refused");
     var written = [];
     var bytesExtracted = 0;
     var totalDecompressed = 0;
@@ -405,9 +459,10 @@ function tar(adapter, opts) {
   }
 
   return {
-    kind:    "tar-reader",
-    inspect: inspect,
-    extract: extract,
+    kind:           "tar-reader",
+    inspect:        inspect,
+    extract:        extract,
+    extractEntries: extractEntries,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.13.7",
+  "version": "0.13.8",
   "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:22a52afe-2217-4e18-a7a1-15e6a137ec0c",
+  "serialNumber": "urn:uuid:fd9a8f72-de3b-4a8d-8059-9ff47ccebb1b",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-27T04:39:38.785Z",
+    "timestamp": "2026-05-27T05:52:19.814Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.13.7",
+      "bom-ref": "@blamejs/core@0.13.8",
       "type": "application",
       "name": "blamejs",
-      "version": "0.13.7",
+      "version": "0.13.8",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.13.7",
+      "purl": "pkg:npm/%40blamejs/core@0.13.8",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.13.7",
+      "ref": "@blamejs/core@0.13.8",
       "dependsOn": []
     }
   ]