@blamejs/blamejs-shop 0.0.83 → 0.0.85

package/lib/vendor/blamejs/release-notes/v0.12.8.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "../scripts/release-notes-schema.json",
+  "version": "0.12.8",
+  "date": "2026-05-23",
+  "headline": "`b.archive.tar` + `b.archive.read.tar` — POSIX pax tar format end-to-end + `b.guardArchive.tarEntryPolicy` + `b.backup` tar bundle default",
+  "summary": "Tar lands as the second format in the archive family. `b.archive.tar()` builds POSIX pax archives (ustar magic + pax extended headers for >100-char names, >8 GiB sizes, nanosecond mtime); `b.archive.read.tar(adapter)` walks the 512-byte block sequence with the same bomb-cap + path-traversal + entry-type defenses that ZIP read shipped at v0.12.7. Tar's natively-streamable shape means `b.archive.adapters.trustedStream(readable)` is a first-class extract path here (no CD-walk required since tar has no central directory; sequential header-by-header is the canonical adversarial-safe path). `b.guardArchive.tarEntryPolicy` ships as the tar-specific entry-shape policy beyond `entryTypePolicy` — handles typeflag 0/5 (regular/directory) by default, refuses 1/2 (hardlink/symlink) unless `allowDangerous` is set with the realpath-on-link-target dual-check, and refuses 3/4/6/7 (char-device/block-device/FIFO/contiguous-file) unconditionally. `b.backup.bundleAdapterStorage({ format: \"tar\" })` becomes the default for new bundles — directory-tree format stays available via `format: \"directory\"` for back-compat with v0.12.7 bundles. `b.backup.migrate(from, to)` one-shot helper converts v0.12.7 directory bundles to v0.12.8 tar bundles transparently. `b.safeArchive.extract({ source, destination, format: \"auto\" })` now sniffs ustar magic at offset 257 inside the first 512-byte block and dispatches to the tar reader automatically. CVE coverage extends to the tar class: CVE-2026-23745 / 2026-24842 (node-tar symlink+hardlink path resolution), CVE-2025-4517 PATH_MAX TOCTOU (the v0.12.7 dual-check carries through), CVE-2025-11001/11002 (symlink TOCTOU on extract), CVE-2024-12905 / 2025-48387 (tar-fs traversal), CVE-2025-4138/4330 (Python tarfile data filter bypass).",
+  "sections": [
+    {
+      "heading": "Added",
+      "items": [
+        {
+          "title": "`b.archive.tar()` — POSIX pax write builder",
+          "body": "Mirrors `b.archive.zip()`'s contract: `addFile(name, content, opts?)` + `addDirectory(name, opts?)` + `toBuffer()` + `toStream(writable)` + `toAdapter(adapter)` + `digest()`. Emits ustar-magic 512-byte header blocks with the standard 11-field prefix (name / mode / uid / gid / size / mtime / chksum / typeflag / linkname / magic / version / uname / gname / devmajor / devminor / prefix). Names >100 chars + sizes >8 GiB + mtime with nanosecond precision get a pax extended header (typeflag=x) preceding the entry; the extended header records (per POSIX.1-2001 §4.18) carry the `path` / `size` / `mtime` / `atime` / `ctime` fields that overflow ustar's fixed widths. Determinism opts: `{ fixedMtime: 0, ignoreOrder: false }` for reproducible builds (matches the ZIP write side)."
+        },
+        {
+          "title": "`b.archive.read.tar(adapter, opts)` — sequential + random-access tar reader",
+          "body": "Walks 512-byte header blocks in order. `inspect()` enumerates entries without decompressing; `extract({ destination })` decompresses entry-by-entry with the same bomb-cap + path-traversal + entry-type defenses as ZIP read. Trusted-stream adapters are first-class here — tar has no central directory, so sequential header-by-header walk IS the canonical adversarial-safe path (`b.archive.adapters.trustedStream(readable)` and `b.archive.adapters.fs/buffer/objectStore/http` all flow through the same reader). Per-entry path safety routes through `b.guardFilename.verifyExtractionPath` (the v0.12.7 dual-check). Refuses to overwrite pre-existing destination files (carries the v0.12.7 atomic-rollback contract)."
+        },
+        {
+          "title": "`b.guardArchive.tarEntryPolicy(opts)` — tar-specific entry-type policy",
+          "body": "Defaults: typeflag 0 (regular file) + 5 (directory) extract; typeflag 1 (hardlink) + 2 (symlink) refused unless `allowDangerous: { symlinks: true, hardlinks: true }` is set; typeflag 3 (char-device) + 4 (block-device) + 6 (FIFO) + 7 (contiguous-file) refused unconditionally. When `allowDangerous` is set, link target is routed through `b.guardFilename.verifyExtractionPath` against the extraction root — the realpath-on-link-target check defends the CVE-2026-23745 / 24842 node-tar class where the safety check and creation logic diverged on path resolution. Pax extended-header (x) + global-header (g) entries consumed by the reader (merged into the following entry's metadata); operators never see them as standalone entries."
+        },
+        {
+          "title": "`b.backup.bundleAdapterStorage({ format: \"tar\" })` — tar bundle becomes default",
+          "body": "New bundles ship as a single tar archive instead of a directory tree. Restore via `b.archive.read.tar` (with the operator-supplied adapter routing the bytes). `format: \"directory\"` opts back into the v0.12.7 layout for operators with existing bundles. `format: \"tar\"` is the new default; `b.backup.diskStorage` stays back-compat at the legacy directory-tree format."
+        },
+        {
+          "title": "`b.backup.migrate(opts)` — directory → tar bundle migration",
+          "body": "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 bundle stays in place until the migrate succeeds; operators with explicit transition windows pass `{ deleteSourceOnSuccess: true }` to opt into the inline replace."
+        },
+        {
+          "title": "`b.safeArchive.extract({ format: \"auto\" })` recognizes tar",
+          "body": "Format auto-sniff now dispatches `ustar` magic at offset 257 inside the first 512-byte header block to the tar reader. ZIP magic + tar magic + GZIP magic (v0.12.9) live in the same sniff path; operators with mixed-format pipelines pass `format: \"auto\"` once + the orchestrator picks the right reader."
+        }
+      ]
+    },
+    {
+      "heading": "Security",
+      "items": [
+        {
+          "title": "Symlink + hardlink path resolution (CVE-2026-23745 / CVE-2026-24842 node-tar class)",
+          "body": "node-tar < 7.5.7 / ≤ 7.5.2 shipped a divergence between its hardlink safety check (which used one path resolution) and its hardlink creation logic (which used another). When `allowDangerous: { hardlinks: true }` is set, blamejs routes the link target through `b.guardFilename.verifyExtractionPath` — the SAME primitive that the eventual `link()` call resolves against — so check + create agree by construction. Symlink targets same shape."
+        },
+        {
+          "title": "Path traversal (CVE-2024-12905 / CVE-2025-48387 tar-fs + CVE-2025-4138 / 4330 Python tarfile data filter bypass)",
+          "body": "Every entry name passes through `b.guardFilename.verifyExtractionPath` — the v0.12.7 dual-check that refuses pre-resolve names > PATH_MAX (4096 bytes) AND verifies the string-normalize + `fs.realpath` resolutions agree on the same final path. Defends the CVE-2025-4517 / 4138 / 4330 class where the operator's path resolution and the kernel's diverge silently past PATH_MAX."
+        },
+        {
+          "title": "Symlink TOCTOU on extract (CVE-2025-11001 / CVE-2025-11002 7-Zip class)",
+          "body": "When `allowDangerous: { symlinks: true }` opts symlinks in, the reader resolves the link target via `verifyExtractionPath` against the extraction root BEFORE calling `fs.symlink` — so the resolved target is inside the trust boundary by construction. The v0.12.7 atomic-rollback contract carries through: any single entry failure aborts the whole extract + cleans up only newly-created files (pre-existing destination files refused at the pre-write check)."
+        }
+      ]
+    },
+    {
+      "heading": "Detectors",
+      "items": [
+        {
+          "title": "`tar-extract-allow-dangerous-without-link-target-check`",
+          "body": "Flags any `b.archive.read.tar(adapter).extract({ allowDangerous: ... })` call site in `lib/` that doesn't route the link target through `b.guardFilename.verifyExtractionPath` against the extraction root. Forces the dual-check discipline at every allow-dangerous opt-in — operators with hardlink / symlink extract needs see the realpath check at the call site."
+        },
+        {
+          "title": "`tar-entry-typeflag-without-policy`",
+          "body": "Flags `lib/archive-tar.js` extract code paths that switch on typeflag without composing `b.guardArchive.tarEntryPolicy` for the type-allowlist decision. Locks the shape: every typeflag dispatch goes through the policy, never inline."
+        },
+        {
+          "title": "`backup-migrate-without-source-preserve`",
+          "body": "Flags `b.backup.migrate(opts)` call sites that pass `deleteSourceOnSuccess: true` without an operator-stated justification comment. Default is preserve-source; deletes need an explicit reason."
+        }
+      ]
+    }
+  ],
+  "references": [
+    { "label": "POSIX.1-2001 pax extended format (IEEE 1003.1)",                "url": "https://pubs.opengroup.org/onlinepubs/9699919799/utilities/pax.html" },
+    { "label": "CVE-2026-23745 — node-tar symlink+hardlink path resolution",    "url": "https://www.sentinelone.com/vulnerability-database/cve-2026-23745/" },
+    { "label": "CVE-2026-24842 — node-tar hardlink path resolution",            "url": "https://github.com/advisories/GHSA-34x7-hfp2-rc4v" },
+    { "label": "CVE-2025-4517 — Python tarfile PATH_MAX bypass (CVSS 9.4)",     "url": "https://nvd.nist.gov/vuln/detail/CVE-2025-4517" },
+    { "label": "CVE-2025-4138 / CVE-2025-4330 — Python tarfile data filter",    "url": "https://github.com/0xDTC/CVE-2025-4138-4517-POC" },
+    { "label": "CVE-2025-11001 / CVE-2025-11002 — 7-Zip symlink TOCTOU on extract", "url": "https://www.sentinelone.com/vulnerability-database/cve-2025-11001/" },
+    { "label": "CVE-2024-12905 / CVE-2025-48387 — node-tar-fs path traversal",   "url": "https://vulert.com/vuln-db/debian-11-node-tar-fs-193050" }
+  ]
+}

package/lib/vendor/blamejs/test/layer-0-primitives/archive-read.test.js

@@ -0,0 +1,247 @@
+"use strict";
+/**
+ * Layer 0 — b.archive read substrate + safe-extract orchestrator +
+ * guard-archive policy builders + b.guardFilename.verifyExtractionPath
+ * + b.backup.bundleAdapterStorage.
+ *
+ * Round-trip coverage: write a ZIP via the existing write side, read
+ * it back via b.archive.read.zip (random-access buffer adapter), extract
+ * via b.safeArchive.extract into a quarantine directory, verify file
+ * contents. Refusal coverage: zip-slip entry name, oversize entries,
+ * NUL byte, PATH_MAX overflow.
+ */
+
+var helpers = require("../helpers");
+var check = helpers.check;
+var b = helpers.b;
+var os = require("node:os");
+var path = require("node:path");
+var fs = require("node:fs");
+
+async function testRoundTripExtract() {
+  var z = b.archive.zip();
+  z.addFile("readme.txt", "Hello, archive-read!\n");
+  z.addFile("data/numbers.csv", "n,sq\n1,1\n2,4\n3,9\n");
+  z.addFile("docs/nested/deep.txt", Buffer.from("payload\n"));
+  var bytes = z.toBuffer();
+
+  // Inspect via buffer adapter — verifies adapter contract + EOCD walk +
+  // CD-walk + LFH/CD skew check.
+  var reader = b.archive.read.zip(b.archive.adapters.buffer(bytes));
+  var entries = await reader.inspect();
+  check("archive.read.zip.inspect: 3 entries",         entries.length === 3);
+  check("archive.read.zip.inspect: name + size",        entries[0].name === "readme.txt" && entries[0].size === 21);
+  check("archive.read.zip.inspect: nested name",        entries[2].name === "docs/nested/deep.txt");
+
+  // Extract via safeArchive orchestrator.
+  var dest = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-archive-test-"));
+  try {
+    var result = await b.safeArchive.extract({
+      source:       bytes,
+      destination:  dest,
+      guardProfile: "balanced",
+    });
+    check("safeArchive.extract: 3 entries written",      result.entries.length === 3);
+    check("safeArchive.extract: format=zip",             result.format === "zip");
+    var readme = fs.readFileSync(path.join(dest, "readme.txt"), "utf8");
+    check("safeArchive.extract: readme contents match",  readme === "Hello, archive-read!\n");
+    var nested = fs.readFileSync(path.join(dest, "docs/nested/deep.txt"), "utf8");
+    check("safeArchive.extract: nested file restored",   nested === "payload\n");
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+}
+
+function testSafeArchiveErrorClass() {
+  // Sanity-check that the typed-error class is exported + an instance
+  // can be constructed with a code + message.
+  var err = new b.safeArchive.SafeArchiveError("safe-archive/test", "test instance");
+  check("SafeArchiveError: code carried",     err.code === "safe-archive/test");
+  check("SafeArchiveError: is Error subclass", err instanceof Error);
+}
+
+async function testSafeArchiveInspect() {
+  var z = b.archive.zip();
+  z.addFile("a.txt", "alpha");
+  z.addFile("b.txt", "beta");
+  var bytes = z.toBuffer();
+  var summary = await b.safeArchive.inspect({ source: bytes });
+  check("safeArchive.inspect: format=zip",                summary.format === "zip");
+  check("safeArchive.inspect: 2 entries",                 summary.entries.length === 2);
+  check("safeArchive.inspect: totalUncompressedBytes",    summary.totalUncompressedBytes === 9);
+}
+
+async function testZipBombPolicy() {
+  var policy = b.guardArchive.zipBombPolicy({
+    maxTotalDecompressedBytes: 8,
+    maxExpansionRatio:         100,
+  });
+  check("zipBombPolicy: maxTotalDecompressedBytes carries",  policy.maxTotalDecompressedBytes === 8);
+  check("zipBombPolicy: defaults applied",                   policy.maxEntries === 65535);
+  // 9-byte archive payload exceeds the 8-byte total cap.
+  var z = b.archive.zip();
+  z.addFile("big.txt", "123456789");
+  var bytes = z.toBuffer();
+  var refused = null;
+  try {
+    var reader = b.archive.read.zip(b.archive.adapters.buffer(bytes), {
+      bombPolicy: policy,
+    });
+    await reader.inspect();
+  } catch (e) { refused = e; }
+  check("bombPolicy: maxTotalDecompressedBytes trips",
+    refused && /total-too-large|entry-too-large/.test(refused.code || refused.message));
+}
+
+function testEntryTypePolicy() {
+  var p = b.guardArchive.entryTypePolicy({ symlinks: true });
+  check("entryTypePolicy: symlinks opted in",   p.symlinks === true);
+  check("entryTypePolicy: hardlinks default off", p.hardlinks === false);
+  check("entryTypePolicy: devices default off",   p.devices === false);
+}
+
+function testVerifyExtractionPathHappy() {
+  var dest = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-verifyx-"));
+  try {
+    var resolved = b.guardFilename.verifyExtractionPath("docs/readme.txt", dest);
+    check("verifyExtractionPath: ok resolved", resolved.indexOf(dest) === 0);
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+}
+
+function testVerifyExtractionPathRefusals() {
+  var refusals = 0;
+  function r(name, root) {
+    try { b.guardFilename.verifyExtractionPath(name, root); }
+    catch (_e) { refusals += 1; }
+  }
+  r("../etc/passwd", "/tmp");                       // zip slip
+  r("/etc/passwd", "/tmp");                         // absolute
+  r("docs/../../etc/passwd", "/tmp");               // mid-segment ..
+  // PATH_MAX overflow (4097 chars).
+  var oversize = new Array(4098).join("a");
+  r(oversize, "/tmp");
+  check("verifyExtractionPath: 4 refusals", refusals === 4);
+}
+
+async function testExtractRefusesOverwrite() {
+  // Codex P1 on v0.12.7 PR #158 — the catch-block cleanup deleted
+  // PRE-EXISTING destination files on abort because the rename-onto-
+  // canonical-path path overwrote them first, then `written[].path`
+  // got rm'd. Fix is to refuse overwrite up front; this regression
+  // test verifies the new refusal fires + that the pre-existing file
+  // is left untouched.
+  var z = b.archive.zip();
+  z.addFile("readme.txt", "from-archive\n");
+  var bytes = z.toBuffer();
+  var dest = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-overwrite-test-"));
+  try {
+    var collidePath = path.join(dest, "readme.txt");
+    fs.writeFileSync(collidePath, "operator's pre-existing file\n");
+    var refused = null;
+    try {
+      await b.safeArchive.extract({ source: bytes, destination: dest });
+    } catch (e) { refused = e; }
+    check("extract: refuses pre-existing destination file",
+      refused && /destination-exists/.test(refused.code || refused.message));
+    var stillThere = fs.readFileSync(collidePath, "utf8");
+    check("extract: pre-existing file untouched on refusal",
+      stillThere === "operator's pre-existing file\n");
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+}
+
+async function testSafeArchiveRefusesTrustedStreamSource() {
+  // Codex P2 on v0.12.7 PR #158 — safeArchive.extract accepted
+  // trusted-stream adapters via the input-shape validator but the
+  // implementation called the random-access reader, which threw the
+  // wrong-entry-point error. Fix is to refuse trusted-stream sources
+  // upfront with a typed safe-archive code.
+  var nodeStream = require("node:stream");
+  var fakeReadable = new nodeStream.Readable({ read: function () {} });
+  var adapter = b.archive.adapters.trustedStream(fakeReadable);
+  var dest = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-trusted-refusal-"));
+  try {
+    var refused = null;
+    try {
+      await b.safeArchive.extract({
+        source:      adapter,
+        destination: dest,
+      });
+    } catch (e) { refused = e; }
+    check("safeArchive.extract: trusted-stream upfront refused",
+      refused && /trusted-stream-unsupported/.test(refused.code || refused.message));
+  } finally {
+    fakeReadable.destroy();
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+}
+
+async function testGuardArchiveInspect() {
+  var z = b.archive.zip();
+  z.addFile("safe.txt", "safe");
+  var bytes = z.toBuffer();
+  var summary = await b.guardArchive.inspect(b.archive.adapters.buffer(bytes), {
+    profile: "balanced",
+  });
+  check("guardArchive.inspect: 1 entry",       summary.entries.length === 1);
+  check("guardArchive.inspect: issues array",   Array.isArray(summary.issues));
+}
+
+async function testBundleAdapterStorageRoundTrip() {
+  var rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-backup-adapter-root-"));
+  var srcDir = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-backup-adapter-src-"));
+  var destDir = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-backup-adapter-dest-"));
+  try {
+    // Populate a small bundle source.
+    fs.writeFileSync(path.join(srcDir, "manifest.json"), JSON.stringify({ v: 1 }));
+    fs.mkdirSync(path.join(srcDir, "files"));
+    fs.writeFileSync(path.join(srcDir, "files", "blob.bin"), Buffer.from([1, 2, 3]));
+
+    var storage = b.backup.bundleAdapterStorage({
+      adapter: b.backup.bundleAdapterStorage.fsAdapter({ root: rootDir }),
+    });
+    check("bundleAdapterStorage: name=adapter", storage.name === "adapter");
+
+    var bundleId = "2026-05-23T07-00-00-000Z-deadbeef";
+    await storage.writeBundle(bundleId, srcDir);
+    check("bundleAdapterStorage: hasBundle after write", await storage.hasBundle(bundleId));
+    fs.rmSync(destDir, { recursive: true });
+    await storage.readBundle(bundleId, destDir);
+    var restored = fs.readFileSync(path.join(destDir, "files", "blob.bin"));
+    check("bundleAdapterStorage: roundtrip bytes match", restored[0] === 1 && restored.length === 3);
+    var list = await storage.listBundles();
+    check("bundleAdapterStorage: listBundles returns the bundle", list.length === 1 && list[0].bundleId === bundleId);
+    await storage.deleteBundle(bundleId);
+    check("bundleAdapterStorage: hasBundle false after delete", !(await storage.hasBundle(bundleId)));
+  } finally {
+    try { fs.rmSync(rootDir, { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+    try { fs.rmSync(srcDir,  { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+    try { fs.rmSync(destDir, { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+  }
+}
+
+async function run() {
+  await testRoundTripExtract();
+  testSafeArchiveErrorClass();
+  await testSafeArchiveInspect();
+  await testZipBombPolicy();
+  testEntryTypePolicy();
+  testVerifyExtractionPathHappy();
+  testVerifyExtractionPathRefusals();
+  await testExtractRefusesOverwrite();
+  await testSafeArchiveRefusesTrustedStreamSource();
+  await testGuardArchiveInspect();
+  await testBundleAdapterStorageRoundTrip();
+}
+
+module.exports = { run: run };
+
+if (require.main === module) {
+  run().then(
+    function () { console.log("[archive-read] OK — " + helpers.getChecks() + " checks passed"); },
+    function (e) { console.error("FAIL:", e && e.stack || e); process.exit(1); }
+  );
+}

package/lib/vendor/blamejs/test/layer-0-primitives/archive-tar.test.js

@@ -0,0 +1,228 @@
+"use strict";
+/**
+ * Layer 0 — b.archive.tar write + b.archive.read.tar +
+ * b.guardArchive.tarEntryPolicy + b.backup.migrate.
+ *
+ * Round-trip coverage: write tar via b.archive.tar(), read back via
+ * b.archive.read.tar(buffer adapter), extract via b.safeArchive.extract
+ * (format auto-detect lands on tar). Refusal: oversize entry, dangerous
+ * typeflag refusal by default. Migration: write a directory bundle in
+ * one storage, migrate to tar bundle in another, verify content.
+ */
+
+var helpers = require("../helpers");
+var check = helpers.check;
+var b = helpers.b;
+var os = require("node:os");
+var path = require("node:path");
+var fs = require("node:fs");
+
+async function testTarRoundTrip() {
+  var t = b.archive.tar();
+  t.addFile("readme.txt", "Hello, tar!\n");
+  t.addFile("data/numbers.csv", "n,sq\n1,1\n2,4\n");
+  t.addDirectory("docs/");
+  t.addFile("docs/nested/deep.txt", "payload\n");
+  var bytes = t.toBuffer();
+
+  check("archive.tar: tar bytes round to 512", bytes.length % 512 === 0);
+  check("archive.tar: ustar magic at offset 257",
+    bytes.slice(257, 263).toString().indexOf("ustar") === 0);
+
+  var reader = b.archive.read.tar(b.archive.adapters.buffer(bytes));
+  var entries = await reader.inspect();
+  check("archive.read.tar.inspect: 4 entries",   entries.length === 4);
+  check("archive.read.tar.inspect: file type",   entries[0].entryType === "file");
+  check("archive.read.tar.inspect: directory type", entries[2].entryType === "directory");
+}
+
+async function testSafeArchiveTarExtract() {
+  var t = b.archive.tar();
+  t.addFile("a.txt", "alpha");
+  t.addFile("nested/b.txt", "beta");
+  var bytes = t.toBuffer();
+
+  var dest = fs.mkdtempSync(path.join(os.tmpdir(), "blamejs-tar-extract-"));
+  try {
+    var result = await b.safeArchive.extract({
+      source:       bytes,
+      destination:  dest,
+      guardProfile: "balanced",
+    });
+    check("safeArchive.extract: format=tar autodetected", result.format === "tar");
+    check("safeArchive.extract: 2 entries written",       result.entries.length === 2);
+    var a = fs.readFileSync(path.join(dest, "a.txt"), "utf8");
+    var bb = fs.readFileSync(path.join(dest, "nested", "b.txt"), "utf8");
+    check("safeArchive.extract: a.txt contents",          a === "alpha");
+    check("safeArchive.extract: nested b.txt contents",   bb === "beta");
+  } finally {
+    fs.rmSync(dest, { recursive: true, force: true });
+  }
+}
+
+function testTarEntryPolicy() {
+  var p = b.guardArchive.tarEntryPolicy({ symlinks: true });
+  check("tarEntryPolicy: symlinks opted in",      p.symlinks === true);
+  check("tarEntryPolicy: hardlinks default off",   p.hardlinks === false);
+  check("tarEntryPolicy: devices default off",     p.devices === false);
+  check("tarEntryPolicy: fifos default off",       p.fifos === false);
+  check("tarEntryPolicy: sockets default off",     p.sockets === false);
+}
+
+async function testTarChecksumDetection() {
+  // Build a valid tar, corrupt the chksum field, verify reader refuses.
+  var t = b.archive.tar();
+  t.addFile("payload.txt", "hello\n");
+  var bytes = t.toBuffer();
+  // Corrupt the checksum field of the first header (offset 148, 8 bytes).
+  bytes[148] = 0x39;   // change first chksum digit
+  var refused = null;
+  try {
+    var reader = b.archive.read.tar(b.archive.adapters.buffer(bytes));
+    await reader.inspect();
+  } catch (e) { refused = e; }
+  check("archive.read.tar: corrupted chksum refused",
+    refused && /chksum|bad-octal/.test(refused.code || refused.message));
+  check("archive.read.tar: chksum refusal is a b.archive.TarError",
+    refused instanceof b.archive.TarError);
+}
+
+async function testBackupMigrateDirectoryToTar() {
+  var fromRoot = fs.mkdtempSync(path.join(os.tmpdir(), "bjs-bk-from-"));
+  var toRoot = fs.mkdtempSync(path.join(os.tmpdir(), "bjs-bk-to-"));
+  var srcDir = fs.mkdtempSync(path.join(os.tmpdir(), "bjs-bk-src-"));
+  var verifyDir = fs.mkdtempSync(path.join(os.tmpdir(), "bjs-bk-verify-"));
+  fs.rmSync(verifyDir, { recursive: true });    // backend wants non-existent dest
+  try {
+    fs.writeFileSync(path.join(srcDir, "manifest.json"), JSON.stringify({ v: 1 }));
+    fs.mkdirSync(path.join(srcDir, "files"));
+    fs.writeFileSync(path.join(srcDir, "files", "blob.bin"), Buffer.from([1, 2, 3]));
+
+    var from = b.backup.bundleAdapterStorage({
+      adapter: b.backup.bundleAdapterStorage.fsAdapter({ root: fromRoot }),
+      format:  "directory",
+    });
+    var to = b.backup.bundleAdapterStorage({
+      adapter: b.backup.bundleAdapterStorage.fsAdapter({ root: toRoot }),
+      format:  "tar",
+    });
+
+    var bundleId = "2026-05-23T15-00-00-000Z-deadbeef";
+    await from.writeBundle(bundleId, srcDir);
+    check("migrate: source-bundle exists pre-migrate", await from.hasBundle(bundleId));
+    check("migrate: dest-bundle absent pre-migrate", !(await to.hasBundle(bundleId)));
+
+    var report = await b.backup.migrate({ from: from, to: to });
+    check("migrate: 1 migrated", report.migrated === 1 && report.skipped === 0);
+    check("migrate: dest-bundle present post-migrate", await to.hasBundle(bundleId));
+
+    // Idempotency: second run skips.
+    var second = await b.backup.migrate({ from: from, to: to });
+    check("migrate: idempotent (1 skipped)", second.migrated === 0 && second.skipped === 1);
+
+    // Read back from destination, verify file contents.
+    await to.readBundle(bundleId, verifyDir);
+    var manifest = JSON.parse(fs.readFileSync(path.join(verifyDir, "manifest.json"), "utf8"));
+    check("migrate: manifest round-tripped", manifest.v === 1);
+    var blob = fs.readFileSync(path.join(verifyDir, "files", "blob.bin"));
+    check("migrate: blob round-tripped",
+      blob.length === 3 && blob[0] === 1 && blob[2] === 3);
+  } finally {
+    try { fs.rmSync(fromRoot,   { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+    try { fs.rmSync(toRoot,     { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+    try { fs.rmSync(srcDir,     { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+    try { fs.rmSync(verifyDir,  { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+  }
+}
+
+async function testBackupTarFormatDefault() {
+  // Write a bundle via the v0.12.8-default format (tar) + verify the
+  // tar key landed on disk.
+  var root = fs.mkdtempSync(path.join(os.tmpdir(), "bjs-bk-tar-default-"));
+  var src = fs.mkdtempSync(path.join(os.tmpdir(), "bjs-bk-tar-src-"));
+  try {
+    fs.writeFileSync(path.join(src, "manifest.json"), JSON.stringify({ v: 1 }));
+    var storage = b.backup.bundleAdapterStorage({
+      adapter: b.backup.bundleAdapterStorage.fsAdapter({ root: root }),
+      // format defaults to "tar" in v0.12.8
+    });
+    var bid = "2026-05-23T15-30-00-000Z-cafebabe";
+    await storage.writeBundle(bid, src);
+    var tarKeyPresent = fs.existsSync(path.join(root, bid, "bundle.tar"));
+    check("bundleAdapterStorage default format: tar key on disk", tarKeyPresent);
+    check("bundleAdapterStorage default format: hasBundle true",
+      await storage.hasBundle(bid));
+  } finally {
+    try { fs.rmSync(root, { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+    try { fs.rmSync(src,  { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+  }
+}
+
+async function testTarTruncationRefused() {
+  // Codex P1 on v0.12.8 PR #159 — declare 11 bytes in the header
+  // but truncate the buffer to 8 payload bytes. The walker must
+  // refuse upfront rather than emitting a partial entry.
+  var t = b.archive.tar();
+  t.addFile("payload.txt", Buffer.from("hello world"));    // 11 bytes
+  var bytes = t.toBuffer();
+  // First header block is at offset 0-511; first data block at
+  // 512-1023 (padded to 512 bytes from the declared 11). Truncate to
+  // 768 bytes: header survives intact but the data block ends
+  // halfway — walker must refuse before slicing partial bytes as
+  // a "complete" file.
+  var truncated = bytes.slice(0, 768);
+  var refused = null;
+  try {
+    var reader = b.archive.read.tar(b.archive.adapters.buffer(truncated));
+    await reader.extract({
+      destination: fs.mkdtempSync(path.join(os.tmpdir(), "bjs-tar-trunc-")),
+    });
+  } catch (e) { refused = e; }
+  check("archive.read.tar: truncated entry refused with typed error",
+    refused && /truncated-entry/.test(refused.code || refused.message));
+}
+
+async function testBackupBundleTooLargeRefused() {
+  // Codex P2 on v0.12.8 PR #159 — bundleAdapterStorage with a
+  // tight maxBundleBytes cap must refuse oversized payloads upfront
+  // rather than OOM during in-memory tar materialization.
+  var srcDir = fs.mkdtempSync(path.join(os.tmpdir(), "bjs-bk-bulk-"));
+  var dest = fs.mkdtempSync(path.join(os.tmpdir(), "bjs-bk-bulk-dest-"));
+  try {
+    fs.writeFileSync(path.join(srcDir, "big.bin"), Buffer.alloc(64 * 1024));
+    var storage = b.backup.bundleAdapterStorage({
+      adapter:        b.backup.bundleAdapterStorage.fsAdapter({ root: dest }),
+      format:         "tar",
+      maxBundleBytes: 16 * 1024,
+    });
+    var refused = null;
+    try {
+      await storage.writeBundle("2026-05-23T00-00-00-000Z-abcdef12", srcDir);
+    } catch (e) { refused = e; }
+    check("backup: bundle exceeding maxBundleBytes refused upfront",
+      refused && /bundle-too-large/.test(refused.code || refused.message));
+  } finally {
+    try { fs.rmSync(srcDir, { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+    try { fs.rmSync(dest,   { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+  }
+}
+
+async function run() {
+  await testTarRoundTrip();
+  await testSafeArchiveTarExtract();
+  testTarEntryPolicy();
+  await testTarChecksumDetection();
+  await testTarTruncationRefused();
+  await testBackupMigrateDirectoryToTar();
+  await testBackupTarFormatDefault();
+  await testBackupBundleTooLargeRefused();
+}
+
+module.exports = { run: run };
+
+if (require.main === module) {
+  run().then(
+    function () { console.log("[archive-tar] OK — " + helpers.getChecks() + " checks passed"); },
+    function (e) { console.error("FAIL:", e && e.stack || e); process.exit(1); }
+  );
+}