@blamejs/core 0.12.7 → 0.12.9

package/lib/backup/index.js

@@ -65,6 +65,8 @@ var compliance = lazyRequire(function () { return require("../compliance"); });
 // module graph (CLI tools, stand-alone backup runners). The db()
 // callable resolves on first access.
 var dbModuleLazy = lazyRequire(function () { return require("../db"); });
+var archiveLazy = lazyRequire(function () { return require("../archive"); });
+var archiveAdaptersLazy = lazyRequire(function () { return require("../archive-adapters"); });
 var { defineClass } = require("../framework-error");
 
 var BackupError = defineClass("BackupError");
@@ -993,6 +995,7 @@ module.exports = {
   create:                    create,
   diskStorage:               diskStorage,
   bundleAdapterStorage:      bundleAdapterStorage,
+  migrate:                   migrate,
   recommendedFiles:          recommendedFiles,
   runInWorker:               runInWorker,
   verifyManifestSignature:   verifyManifestSignature,
@@ -1055,6 +1058,35 @@ function bundleAdapterStorage(opts) {
         "bundleAdapterStorage: adapter missing method '" + required[i] + "'");
     }
   }
+  // v0.12.8 — `format: "tar"` becomes the default for new bundles.
+  // `format: "directory"` opts back into the v0.12.7 file-by-file
+  // layout for operators with existing bundles. The format is
+  // operator-supplied so a single backup engine can transition over
+  // time + b.backup.migrate() handles the directory → tar conversion.
+  var format = opts.format || "tar";
+  if (format !== "tar" && format !== "tar.gz" && format !== "directory") {
+    throw new BackupError("backup/bad-format",
+      "bundleAdapterStorage: format must be \"tar\" (default) | \"tar.gz\" (v0.12.9 compressed) | \"directory\" (legacy v0.12.7)");
+  }
+  // Codex P2 on v0.12.8 PR #159 — tar mode builds the whole archive
+  // in memory before adapter.writeFile because the v0.12.8 adapter
+  // contract is bytes-in (no writeStream method). The OOM-prevention
+  // gate is maxBundleBytes: writeBundle pre-walks the source tree,
+  // sums file sizes, and refuses upfront if the projected uncompressed
+  // tar would exceed the cap. Default 8 GiB — accommodates typical
+  // db + mail-spool + log bundles while refusing pathological inputs.
+  // Defer-with-condition for true streaming: when the adapter
+  // contract gains writeStream(key) (slated for v0.13+ alongside
+  // multipart S3 upload primitives), this path switches to
+  // tarBuilder.toStream() and writes chunks as they're produced.
+  var maxBundleBytes = opts.maxBundleBytes !== undefined
+    ? opts.maxBundleBytes
+    : 8 * 1024 * 1024 * 1024;                                                       // allow:raw-byte-literal — 8 GiB default cap; uses C.BYTES.bytes covers numeric-literal rule
+  if (!numericBounds.isPositiveFiniteInt(maxBundleBytes)) {                         // allow:inline-numeric-bounds-cascade — required-with-default opt
+    throw new BackupError("backup/bad-arg",
+      "bundleAdapterStorage: maxBundleBytes must be a positive finite integer; got " +
+      numericBounds.shape(opts.maxBundleBytes));
+  }
 
   function _ensureBundleId(bundleId) {
     if (!_isValidBundleId(bundleId)) {
@@ -1078,6 +1110,20 @@ function bundleAdapterStorage(opts) {
     return out;
   }
 
+  // Tar-format bundle storage stores the whole bundle as a single
+  // key under `<bundleId>/bundle.tar` (or `<bundleId>/bundle.tar.gz`
+  // for the v0.12.9 compressed variant). The marker is named that
+  // way so listBundles + hasBundle can locate either format by key
+  // prefix walk.
+  var TAR_KEY_SUFFIX = "/bundle.tar";
+  var TAR_GZ_KEY_SUFFIX = "/bundle.tar.gz";
+
+  function _hasBundleKey(bundleId, format) {
+    if (format === "tar") return adapter.hasKey(bundleId + TAR_KEY_SUFFIX);
+    if (format === "tar.gz") return adapter.hasKey(bundleId + TAR_GZ_KEY_SUFFIX);
+    return adapter.hasKey(bundleId + "/manifest.json");
+  }
+
   return {
     name: "adapter",
     async writeBundle(bundleId, sourceDir) {
@@ -1086,16 +1132,58 @@ function bundleAdapterStorage(opts) {
         throw new BackupError("backup/no-source",
           "writeBundle: sourceDir does not exist: " + sourceDir);
       }
-      var alreadyHas = await adapter.hasKey(bundleId + "/manifest.json");
+      var alreadyHas = await _hasBundleKey(bundleId, format);
       if (alreadyHas) {
         throw new BackupError("backup/bundle-exists",
           "writeBundle: bundle '" + bundleId + "' already exists in storage");
       }
-      var relPaths = _walkDirSync(sourceDir, []);
-      for (var i = 0; i < relPaths.length; i += 1) {
-        var rel = relPaths[i];
-        var bytes = nodeFs.readFileSync(nodePath.join(sourceDir, rel));
-        await adapter.writeFile(bundleId + "/" + rel, bytes);
+      if (format === "tar" || format === "tar.gz") {
+        // Pack the source-directory tree into a single tar archive +
+        // store under one key. Composes b.archive.tar (+ b.archive.gz
+        // for the tar.gz variant which adds gzip compression on the
+        // wire). Bundle sizes drop ~3-5× on text-heavy backups
+        // (databases, JSON exports, mail spools) under tar.gz.
+        //
+        // Codex P2 on v0.12.8 PR #159 — tar bytes are materialized in
+        // memory because the v0.12.8 adapter contract is bytes-in
+        // (writeFile takes a Buffer, no writeStream method). The
+        // maxBundleBytes pre-walk computes the uncompressed payload
+        // size (file bytes only — tar header overhead is bounded at
+        // ~512 B per entry + 1024 B trailer) and refuses upfront so
+        // pathological inputs throw `backup/bundle-too-large` instead
+        // of OOM. The defer-with-condition for true streaming is
+        // gated on the adapter contract gaining writeStream(key).
+        var relPaths = _walkDirSync(sourceDir, []);
+        var projectedBytes = 0;
+        for (var pi = 0; pi < relPaths.length; pi += 1) {
+          var stat = nodeFs.statSync(nodePath.join(sourceDir, relPaths[pi]));
+          projectedBytes += stat.size;
+        }
+        if (projectedBytes > maxBundleBytes) {
+          throw new BackupError("backup/bundle-too-large",
+            "writeBundle: projected uncompressed bundle " + projectedBytes +
+            " bytes exceeds maxBundleBytes=" + maxBundleBytes +
+            " — split the source tree across multiple bundles or raise the cap");
+        }
+        var t = archiveLazy().tar();
+        for (var i = 0; i < relPaths.length; i += 1) {
+          var rel = relPaths[i];
+          var bytes = nodeFs.readFileSync(nodePath.join(sourceDir, rel));
+          t.addFile(rel, bytes);
+        }
+        var keySuffix = format === "tar.gz" ? TAR_GZ_KEY_SUFFIX : TAR_KEY_SUFFIX;
+        var payloadBytes = format === "tar.gz"
+          ? archiveLazy().gz(t.toBuffer()).toBuffer()
+          : t.toBuffer();
+        await adapter.writeFile(bundleId + keySuffix, payloadBytes);
+        return;
+      }
+      // Directory format (v0.12.7 layout).
+      var dirRelPaths = _walkDirSync(sourceDir, []);
+      for (var j = 0; j < dirRelPaths.length; j += 1) {
+        var dirRel = dirRelPaths[j];
+        var dirBytes = nodeFs.readFileSync(nodePath.join(sourceDir, dirRel));
+        await adapter.writeFile(bundleId + "/" + dirRel, dirBytes);
       }
     },
     async readBundle(bundleId, destDir) {
@@ -1104,20 +1192,51 @@ function bundleAdapterStorage(opts) {
         throw new BackupError("backup/dest-exists",
           "readBundle: destDir already exists: " + destDir);
       }
-      var keys = await adapter.listKeys(bundleId + "/");
-      if (keys.length === 0) {
+      // Detect which format this bundle is in — operators with mixed
+      // pre-v0.12.8 + post-v0.12.8 (+ v0.12.9 tar.gz) bundles can read
+      // every flavor back.
+      var hasTar = await adapter.hasKey(bundleId + TAR_KEY_SUFFIX);
+      var hasTarGz = await adapter.hasKey(bundleId + TAR_GZ_KEY_SUFFIX);
+      var hasManifest = await adapter.hasKey(bundleId + "/manifest.json");
+      if (!hasTar && !hasTarGz && !hasManifest) {
         throw new BackupError("backup/bundle-not-found",
           "readBundle: '" + bundleId + "' not in storage");
       }
       atomicFile.ensureDir(destDir);
+      if (hasTarGz) {
+        // Codex P1/P2 on v0.12.9 PR #160 — propagate maxBundleBytes
+        // to the gz restore path + disable the expansion-ratio cap.
+        // archive.read.gz defaults (1 GiB output / 100× ratio) are
+        // bomb-defense settings appropriate for adversarial input;
+        // this is a SELF-AUTHORED bundle the writeBundle path
+        // produced under maxBundleBytes — the restore contract is
+        // "decompress to at most what was permitted on write." A
+        // zero-filled DB file can easily hit >100× compression
+        // ratio; without these opts the same primitive writes
+        // bundles it can't read back.
+        var gzBytes = await adapter.readFile(bundleId + TAR_GZ_KEY_SUFFIX);
+        var gzReader = archiveLazy().read.gz(archiveAdaptersLazy().buffer(gzBytes), {
+          maxDecompressedBytes: maxBundleBytes,
+          maxExpansionRatio:    0,
+        });
+        var tarReader = gzReader.asTar();
+        await tarReader.extract({ destination: destDir });
+        return;
+      }
+      if (hasTar) {
+        var tarBytes = await adapter.readFile(bundleId + TAR_KEY_SUFFIX);
+        var reader = archiveLazy().read.tar(archiveAdaptersLazy().buffer(tarBytes));
+        await reader.extract({ destination: destDir });
+        return;
+      }
+      // Directory format readback (v0.12.7 layout).
+      var keys = await adapter.listKeys(bundleId + "/");
       for (var i = 0; i < keys.length; i += 1) {
         var key = keys[i];
         var prefix = bundleId + "/";
         if (key.indexOf(prefix) !== 0) continue;
         var rel = key.slice(prefix.length);
-        // Path-safety: rel must not escape destDir. Reuse the
-        // verifyExtractionPath dual-check primitive when the dest
-        // already exists (writeable directory just created).
+        // Path-safety: rel must not escape destDir.
         var destPath = nodePath.join(destDir, rel);
         var resolvedDest = nodePath.resolve(destPath);
         var resolvedRoot = nodePath.resolve(destDir);
@@ -1129,7 +1248,13 @@ function bundleAdapterStorage(opts) {
         }
         atomicFile.ensureDir(nodePath.dirname(destPath));
         var bytes = await adapter.readFile(key);
-        nodeFs.writeFileSync(destPath, bytes);
+        // Exclusive-create (wx) carries the v0.12.7 atomic-rollback
+        // contract: readBundle refuses to overwrite pre-existing
+        // files at destPath. Combined with the upfront destDir check
+        // above (refuses if destDir already exists), the only way
+        // wx fires here is a symlink swap between ensureDir and write
+        // — which the framework refuses rather than following.
+        nodeFs.writeFileSync(destPath, bytes, { flag: "wx", mode: 0o600 });
       }
     },
     async listBundles() {
@@ -1175,7 +1300,18 @@ function bundleAdapterStorage(opts) {
     },
     async hasBundle(bundleId) {
       _ensureBundleId(bundleId);
-      return adapter.hasKey(bundleId + "/manifest.json");
+      // Format-aware: check the storage layout's marker key. Tar
+      // bundles store under <bid>/bundle.tar; tar.gz bundles store
+      // under <bid>/bundle.tar.gz; directory bundles store under
+      // <bid>/manifest.json. Operators with a mixed bundle set
+      // (some tar, some tar.gz, some directory) get true for any.
+      var tarKey = bundleId + TAR_KEY_SUFFIX;
+      var tarGzKey = bundleId + TAR_GZ_KEY_SUFFIX;
+      var dirKey = bundleId + "/manifest.json";
+      if (await adapter.hasKey(tarKey)) return true;
+      if (await adapter.hasKey(tarGzKey)) return true;
+      if (await adapter.hasKey(dirKey)) return true;
+      return false;
     },
   };
 }
@@ -1244,3 +1380,91 @@ bundleAdapterStorage.fsAdapter = function (fsOpts) {
     },
   };
 };
+
+// ---- v0.12.8: migrate ----------------------------------------------------
+
+/**
+ * @primitive b.backup.migrate
+ * @signature b.backup.migrate(opts)
+ * @since     0.12.8
+ * @status    stable
+ * @related   b.backup.bundleAdapterStorage
+ *
+ * One-shot helper that walks an operator's directory-tree-format
+ * bundle (v0.12.7 layout) and writes the same content as a tar-format
+ * bundle via the v0.12.8 `bundleAdapterStorage`. Idempotent: re-
+ * running on an already-migrated bundle is a no-op. Source stays in
+ * place by default; operators with explicit transition windows opt
+ * into the inline replace via `deleteSourceOnSuccess: true`.
+ *
+ * @opts
+ *   from:                    bundleAdapterStorage with format: "directory",
+ *   to:                      bundleAdapterStorage with format: "tar",
+ *   bundleId:                string  (single-bundle migrate; omit to migrate all),
+ *   deleteSourceOnSuccess:   boolean (default false; explicit opt-in),
+ *
+ * @example
+ *   var from = b.backup.bundleAdapterStorage({
+ *     adapter: b.backup.bundleAdapterStorage.fsAdapter({ root: "/var/backups-v7" }),
+ *     format:  "directory",
+ *   });
+ *   var to = b.backup.bundleAdapterStorage({
+ *     adapter: b.backup.bundleAdapterStorage.fsAdapter({ root: "/var/backups-v8" }),
+ *     format:  "tar",
+ *   });
+ *   await b.backup.migrate({ from: from, to: to });
+ */
+async function migrate(opts) {
+  opts = opts || {};
+  if (!opts.from || typeof opts.from.readBundle !== "function" ||
+      typeof opts.from.listBundles !== "function") {
+    throw new BackupError("backup/bad-from",
+      "migrate: opts.from must be a storage backend (got " + typeof opts.from + ")");
+  }
+  if (!opts.to || typeof opts.to.writeBundle !== "function" ||
+      typeof opts.to.hasBundle !== "function") {
+    throw new BackupError("backup/bad-to",
+      "migrate: opts.to must be a storage backend (got " + typeof opts.to + ")");
+  }
+  var ids;
+  if (opts.bundleId) {
+    if (!_isValidBundleId(opts.bundleId)) {
+      throw new BackupError("backup/bad-bundle-id",
+        "migrate: bundleId must match the framework's timestamp+suffix format");
+    }
+    ids = [opts.bundleId];
+  } else {
+    var list = await opts.from.listBundles();
+    ids = list.map(function (b) { return b.bundleId; });
+  }
+  var migrated = 0;
+  var skipped = 0;
+  for (var i = 0; i < ids.length; i += 1) {
+    var bid = ids[i];
+    // Idempotency: skip if destination already has the bundle.
+    if (await opts.to.hasBundle(bid)) {
+      skipped += 1;
+      continue;
+    }
+    // Stage source-bundle into a tmp dir, then write via destination.
+    var tmpDir = nodeFs.mkdtempSync(nodePath.join(os.tmpdir(),
+      "blamejs-backup-migrate-" + bid + "-"));
+    var stageDir = nodePath.join(tmpDir, "bundle");
+    try {
+      await opts.from.readBundle(bid, stageDir);
+      await opts.to.writeBundle(bid, stageDir);
+      migrated += 1;
+      if (opts.deleteSourceOnSuccess === true) {
+        if (typeof opts.from.deleteBundle === "function") {
+          await opts.from.deleteBundle(bid);
+        }
+      }
+    } finally {
+      try { nodeFs.rmSync(tmpDir, { recursive: true, force: true }); }
+      catch (_e) { /* drop-silent */ }
+    }
+  }
+  return { migrated: migrated, skipped: skipped, total: ids.length };
+}
+
+

package/lib/guard-archive.js

@@ -902,6 +902,7 @@ module.exports = {
   inspect:             inspect,
   zipBombPolicy:       zipBombPolicy,
   entryTypePolicy:     entryTypePolicy,
+  tarEntryPolicy:      tarEntryPolicy,
 };
 
 // ---- v0.12.7 extensions ---------------------------------------------------
@@ -1039,3 +1040,42 @@ function entryTypePolicy(opts) {
     sockets:   opts.sockets   === true,
   });
 }
+
+/**
+ * @primitive b.guardArchive.tarEntryPolicy
+ * @signature b.guardArchive.tarEntryPolicy(opts)
+ * @since     0.12.8
+ * @status    stable
+ * @related   b.guardArchive.entryTypePolicy, b.archive.read.tar
+ *
+ * Tar-specific entry-type policy. Same shape as `entryTypePolicy`
+ * but explicitly named for tar's typeflag vocabulary (1=hardlink,
+ * 2=symlink, 3=char-device, 4=block-device, 6=FIFO, 7=contiguous-
+ * file) so call sites read clearly when the operator's intent is
+ * tar-specific. Defaults refuse every dangerous typeflag. Operators
+ * opting symlinks / hardlinks in get the link target routed through
+ * `b.guardFilename.verifyExtractionPath`'s realpath-on-target check
+ * (defends CVE-2026-23745 / 24842 node-tar path-resolution divergence
+ * class).
+ *
+ * @opts
+ *   symlinks:   false,
+ *   hardlinks:  false,
+ *   devices:    false,
+ *   fifos:      false,
+ *   sockets:    false,
+ *
+ * @example
+ *   var policy = b.guardArchive.tarEntryPolicy({ symlinks: true });
+ *   await b.safeArchive.extract({
+ *     source, destination, entryTypePolicy: policy,
+ *     allowDangerous: { symlinks: true },
+ *   });
+ */
+function tarEntryPolicy(opts) {
+  // Same shape as entryTypePolicy; aliased for tar-specific call-site
+  // readability. The implementation is intentionally identical — the
+  // policy-object shape is format-neutral, only the typeflag mapping
+  // in the reader differs.
+  return entryTypePolicy(opts);
+}

package/lib/safe-archive.js

@@ -45,6 +45,8 @@ var SafeArchiveError = defineClass("SafeArchiveError", { alwaysPermanent: true }
 
 var archiveRead = lazyRequire(function () { return require("./archive-read"); });
 var archiveAdapters = lazyRequire(function () { return require("./archive-adapters"); });
+var archiveTarRead = lazyRequire(function () { return require("./archive-tar-read"); });
+var archiveGz = lazyRequire(function () { return require("./archive-gz"); });
 
 // ---- Format sniffing ----------------------------------------------------
 
@@ -178,18 +180,43 @@ async function extract(opts) {
       var sniff = await _sniffMagic(source);
       format = sniff.format;
     }
-    if (format !== "zip") {
+    var reader;
+    if (format === "zip") {
+      reader = archiveRead().zip(source, {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+    } else if (format === "tar") {
+      reader = archiveTarRead().tar(source, {
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+    } else if (format === "tar.gz") {
+      // gzip envelope around tar — safeDecompress caps run on the gz
+      // layer before the tar walker ever sees a decompressed byte.
+      reader = archiveGz().read.gz(source, {
+        maxDecompressedBytes: opts.maxDecompressedBytes,
+        maxExpansionRatio:    opts.maxExpansionRatio,
+        audit:                opts.audit,
+      }).asTar({
+        bombPolicy:      opts.bombPolicy,
+        entryTypePolicy: opts.entryTypePolicy,
+        guardProfile:    opts.guardProfile,
+        audit:           opts.audit,
+      });
+    } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
-        "extract: format=" + JSON.stringify(format) + " — v0.12.7 ships ZIP only " +
-        "(tar lands v0.12.8, gz lands v0.12.9, encryptPacked-wrap lands v0.12.10)");
+        "extract: format=" + JSON.stringify(format) + " — v0.12.9 ships ZIP + tar + tar.gz " +
+        "(encryptPacked-wrap lands v0.12.10)");
     }
-    var reader = archiveRead().zip(source, {
-      bombPolicy:      opts.bombPolicy,
-      entryTypePolicy: opts.entryTypePolicy,
-      guardProfile:    opts.guardProfile,
-      audit:           opts.audit,
+    var result = await reader.extract({
+      destination:    opts.destination,
+      allowDangerous: opts.allowDangerous,
     });
-    var result = await reader.extract({ destination: opts.destination });
     return Object.assign({ format: format }, result);
   } finally {
     if (typeof source.close === "function" && typeof opts.source === "string") {
@@ -238,14 +265,21 @@ async function inspect(opts) {
       var sniff = await _sniffMagic(source);
       format = sniff.format;
     }
-    if (format !== "zip") {
+    var reader;
+    if (format === "zip") {
+      reader = archiveRead().zip(source, {
+        bombPolicy: opts.bombPolicy,
+        audit:      opts.audit,
+      });
+    } else if (format === "tar") {
+      reader = archiveTarRead().tar(source, {
+        bombPolicy: opts.bombPolicy,
+        audit:      opts.audit,
+      });
+    } else {
       throw new SafeArchiveError("safe-archive/format-unsupported",
-        "inspect: format=" + JSON.stringify(format) + " — v0.12.7 ships ZIP only");
+        "inspect: format=" + JSON.stringify(format) + " — v0.12.8 ships ZIP + tar");
     }
-    var reader = archiveRead().zip(source, {
-      bombPolicy: opts.bombPolicy,
-      audit:      opts.audit,
-    });
     var entries = await reader.inspect();
     var totalCompressed = 0;
     var totalUncompressed = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.7",
+  "version": "0.12.9",
   "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:6ee9d122-fc29-4cdb-a4fb-bd4afab5f35d",
+  "serialNumber": "urn:uuid:f5a3cd7a-802d-4f55-ba59-958f474f38a0",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-23T15:14:39.191Z",
+    "timestamp": "2026-05-23T17:58:07.192Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.7",
+      "bom-ref": "@blamejs/core@0.12.9",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.7",
+      "version": "0.12.9",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.7",
+      "purl": "pkg:npm/%40blamejs/core@0.12.9",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.7",
+      "ref": "@blamejs/core@0.12.9",
       "dependsOn": []
     }
   ]