@blamejs/blamejs-shop 0.0.83 → 0.0.98

package/lib/vendor/blamejs/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");
@@ -992,6 +994,8 @@ function runInWorker(opts) {
 module.exports = {
   create:                    create,
   diskStorage:               diskStorage,
+  bundleAdapterStorage:      bundleAdapterStorage,
+  migrate:                   migrate,
   recommendedFiles:          recommendedFiles,
   runInWorker:               runInWorker,
   verifyManifestSignature:   verifyManifestSignature,
@@ -999,3 +1003,468 @@ module.exports = {
   BackupError:               BackupError,
   BUNDLE_ID_RE:              BUNDLE_ID_RE,
 };
+
+// ---- v0.12.7: bundleAdapterStorage ---------------------------------------
+
+/**
+ * @primitive b.backup.bundleAdapterStorage
+ * @signature b.backup.bundleAdapterStorage(opts)
+ * @since     0.12.7
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.backup.diskStorage, b.backup.create
+ *
+ * Adapter-driven storage backend. Wraps the bundle directory's file
+ * tree into per-file key-value pairs routed through an operator-
+ * supplied byte-store adapter so backup bundles can land anywhere
+ * that exposes the contract (local fs is the v0.12.7 default; tar
+ * folding lands v0.12.8, tar.gz v0.12.9, S3/MinIO/Azure/GCS
+ * objectStore v0.12.11).
+ *
+ * The adapter contract (small surface; an `fs` implementation is the
+ * default + ships in `lib/backup/_adapter-fs.js`):
+ *
+ *   adapter.writeFile(key, bytes): Promise<void>
+ *   adapter.readFile(key): Promise<Buffer>
+ *   adapter.listKeys(prefix): Promise<string[]>
+ *   adapter.deleteKey(key): Promise<void>
+ *   adapter.hasKey(key): Promise<boolean>
+ *
+ * Keys are `<bundleId>/<relative/path/within/bundle>`. Operators
+ * pointing at an objectStore implementation pass an adapter that
+ * routes keys to S3 paths; pointing at an HTTP-backed store, ditto.
+ *
+ * @opts
+ *   adapter:   { writeFile, readFile, listKeys, deleteKey, hasKey },
+ *
+ * @example
+ *   var storage = b.backup.bundleAdapterStorage({
+ *     adapter: b.backup.bundleAdapterStorage.fsAdapter({ root: "/var/backups" }),
+ *   });
+ *   storage.name;       // → "adapter"
+ *   typeof storage.writeBundle;   // → "function"
+ */
+function bundleAdapterStorage(opts) {
+  opts = opts || {};
+  if (!opts.adapter || typeof opts.adapter !== "object") {
+    throw new BackupError("backup/bad-adapter",
+      "bundleAdapterStorage: opts.adapter is required (an object with writeFile/readFile/listKeys/deleteKey/hasKey)");
+  }
+  var adapter = opts.adapter;
+  var required = ["writeFile", "readFile", "listKeys", "deleteKey", "hasKey"];
+  for (var i = 0; i < required.length; i += 1) {
+    if (typeof adapter[required[i]] !== "function") {
+      throw new BackupError("backup/bad-adapter",
+        "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)) {
+      throw new BackupError("backup/bad-bundle-id",
+        "bundleId must match the framework's timestamp+suffix format");
+    }
+  }
+
+  function _walkDirSync(rootDir, out, rel) {
+    rel = rel || "";
+    var entries = nodeFs.readdirSync(nodePath.join(rootDir, rel), { withFileTypes: true });
+    for (var i = 0; i < entries.length; i += 1) {
+      var name = entries[i].name;
+      var relPath = rel ? (rel + "/" + name) : name;
+      if (entries[i].isDirectory()) {
+        _walkDirSync(rootDir, out, relPath);
+      } else if (entries[i].isFile()) {
+        out.push(relPath);
+      }
+    }
+    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) {
+      _ensureBundleId(bundleId);
+      if (!nodeFs.existsSync(sourceDir)) {
+        throw new BackupError("backup/no-source",
+          "writeBundle: sourceDir does not exist: " + sourceDir);
+      }
+      var alreadyHas = await _hasBundleKey(bundleId, format);
+      if (alreadyHas) {
+        throw new BackupError("backup/bundle-exists",
+          "writeBundle: bundle '" + bundleId + "' already exists in storage");
+      }
+      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) {
+      _ensureBundleId(bundleId);
+      if (nodeFs.existsSync(destDir)) {
+        throw new BackupError("backup/dest-exists",
+          "readBundle: destDir already exists: " + destDir);
+      }
+      // 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.
+        var destPath = nodePath.join(destDir, rel);
+        var resolvedDest = nodePath.resolve(destPath);
+        var resolvedRoot = nodePath.resolve(destDir);
+        if (resolvedDest !== resolvedRoot &&
+            resolvedDest.indexOf(resolvedRoot + nodePath.sep) !== 0) {
+          throw new BackupError("backup/bad-key",
+            "readBundle: storage key " + JSON.stringify(rel) +
+            " escapes destDir " + JSON.stringify(destDir));
+        }
+        atomicFile.ensureDir(nodePath.dirname(destPath));
+        var bytes = await adapter.readFile(key);
+        // 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() {
+      // Get every key, partition by bundleId prefix, return sorted.
+      var allKeys = await adapter.listKeys("");
+      var byBundle = new Map();
+      for (var i = 0; i < allKeys.length; i += 1) {
+        var key = allKeys[i];
+        var slash = key.indexOf("/");
+        if (slash <= 0) continue;
+        var bid = key.slice(0, slash);
+        if (!_isValidBundleId(bid)) continue;
+        var stats = byBundle.get(bid);
+        if (!stats) {
+          stats = { count: 0, size: 0 };
+          byBundle.set(bid, stats);
+        }
+        stats.count += 1;
+        // Note: size is approximate — we'd need a stat-per-key here,
+        // and many adapter implementations don't expose a fast stat
+        // primitive. listBundles is best-effort; operators wanting
+        // exact size do their own walk.
+      }
+      var out = [];
+      var entries = Array.from(byBundle.entries());
+      for (var j = 0; j < entries.length; j += 1) {
+        var bidJ = entries[j][0];
+        out.push({
+          bundleId:  bidJ,
+          createdAt: null,    // adapter may not expose mtime
+          size:      null,    // best-effort
+        });
+      }
+      out.sort(function (a, b) { return a.bundleId < b.bundleId ? 1 : -1; });
+      return out;
+    },
+    async deleteBundle(bundleId) {
+      _ensureBundleId(bundleId);
+      var keys = await adapter.listKeys(bundleId + "/");
+      for (var i = 0; i < keys.length; i += 1) {
+        await adapter.deleteKey(keys[i]);
+      }
+    },
+    async hasBundle(bundleId) {
+      _ensureBundleId(bundleId);
+      // 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;
+    },
+  };
+}
+
+// fsAdapter — default adapter for bundleAdapterStorage backed by the
+// local filesystem. Provides the same on-disk layout as diskStorage
+// (bundle directories under a root path) but via the adapter contract
+// so v0.12.8+ can swap the implementation transparently.
+bundleAdapterStorage.fsAdapter = function (fsOpts) {
+  fsOpts = fsOpts || {};
+  validateOpts.requireNonEmptyString(fsOpts.root,
+    "bundleAdapterStorage.fsAdapter: opts.root", BackupError, "backup/no-storage-root");
+  var root = fsOpts.root;
+  atomicFile.ensureDir(root);
+
+  function _keyPath(key) {
+    // Refuse keys with traversal segments — defense in depth even
+    // though the storage layer also checks.
+    if (key.indexOf("..") !== -1 || key.indexOf("\0") !== -1) {
+      throw new BackupError("backup/bad-key",
+        "fsAdapter: key contains invalid characters: " + JSON.stringify(key));
+    }
+    return nodePath.join(root, key);
+  }
+
+  return {
+    async writeFile(key, bytes) {
+      var path = _keyPath(key);
+      atomicFile.ensureDir(nodePath.dirname(path));
+      nodeFs.writeFileSync(path, bytes);
+    },
+    async readFile(key) {
+      var path = _keyPath(key);
+      if (!nodeFs.existsSync(path)) {
+        throw new BackupError("backup/no-key", "fsAdapter: key not found: " + JSON.stringify(key));
+      }
+      return nodeFs.readFileSync(path);
+    },
+    async listKeys(prefix) {
+      var out = [];
+      if (!nodeFs.existsSync(root)) return out;
+      function _walk(rel) {
+        var entries = nodeFs.readdirSync(nodePath.join(root, rel || "."), { withFileTypes: true });
+        for (var i = 0; i < entries.length; i += 1) {
+          var name = entries[i].name;
+          var nextRel = rel ? (rel + "/" + name) : name;
+          if (entries[i].isDirectory()) {
+            _walk(nextRel);
+          } else if (entries[i].isFile()) {
+            if (!prefix || nextRel.indexOf(prefix) === 0) {
+              out.push(nextRel);
+            }
+          }
+        }
+      }
+      _walk("");
+      return out;
+    },
+    async deleteKey(key) {
+      var path = _keyPath(key);
+      try { nodeFs.rmSync(path); } catch (_e) { /* drop-silent — key already gone */ }
+    },
+    async hasKey(key) {
+      try { return nodeFs.existsSync(_keyPath(key)); }
+      catch (_e) { return false; }
+    },
+  };
+};
+
+// ---- 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/vendor/blamejs/lib/guard-archive.js

@@ -71,6 +71,7 @@ var gateContract = require("./gate-contract");
 var C = require("./constants");
 var numericBounds = require("./numeric-bounds");
 var guardFilename = require("./guard-filename");
+var archiveRead = lazyRequire(function () { return require("./archive-read"); });
 var { GuardArchiveError } = require("./framework-error");
 
 var observability = lazyRequire(function () { return require("./observability"); });
@@ -898,4 +899,183 @@ module.exports = {
   ARCHIVE_EXTENSIONS:  ARCHIVE_EXTENSIONS,
   MAGIC_SIGNATURES:    MAGIC_SIGNATURES,
   GuardArchiveError:   GuardArchiveError,
+  inspect:             inspect,
+  zipBombPolicy:       zipBombPolicy,
+  entryTypePolicy:     entryTypePolicy,
+  tarEntryPolicy:      tarEntryPolicy,
 };
+
+// ---- v0.12.7 extensions ---------------------------------------------------
+
+/**
+ * @primitive b.guardArchive.inspect
+ * @signature b.guardArchive.inspect(adapter, opts?)
+ * @since     0.12.7
+ * @status    stable
+ * @related   b.archive.read.zip, b.guardArchive.validateEntries
+ *
+ * Bridge primitive: runs `b.archive.read.zip(adapter).inspect()` to
+ * enumerate the entry list (no decompression), then hands the list to
+ * `validateEntries` for the full posture-aware gate. Returns
+ * `{ entries, issues, decisions }` so the caller decides whether to
+ * proceed.
+ *
+ * Operators using the lower-level read primitive directly call this
+ * to combine the metadata pass with the guard pass; `b.safeArchive.
+ * extract` does the same composition inline under the hood.
+ *
+ * @opts
+ *   profile:        "strict" | "balanced" | "permissive" | "hipaa" | ...,
+ *   format:         "zip" (v0.12.7 — tar v0.12.8, gz v0.12.9),
+ *   audit:          b.audit,
+ *
+ * @example
+ *   var adapter = b.archive.adapters.fs("/var/uploads/payload.zip");
+ *   var summary = await b.guardArchive.inspect(adapter, { profile: "strict" });
+ *   if (summary.issues.length > 0) refuse(summary.issues);
+ */
+async function inspect(adapter, opts) {
+  opts = opts || {};
+  var format = opts.format || "zip";
+  if (format !== "zip") {
+    throw new GuardArchiveError("archive/format-unsupported",
+      "guardArchive.inspect: format=" + JSON.stringify(format) +
+      " — v0.12.7 ships ZIP only (tar v0.12.8, gz v0.12.9)");
+  }
+  var reader = archiveRead().zip(adapter, { audit: opts.audit });
+  var rawEntries = await reader.inspect();
+  // Project the read-primitive's entry shape into validateEntries'
+  // expected `{ name, size, compressedSize, isSymlink, ... }` shape.
+  var guardEntries = rawEntries.map(function (e) {
+    return {
+      name:           e.name,
+      size:           e.size,
+      compressedSize: e.compressedSize,
+      isSymlink:      e.entryType === "symlink",
+      isHardlink:     false,
+      linkTarget:     null,
+      isDirectory:    e.entryType === "directory",
+      isEncrypted:    e.isEncrypted,
+      attrs:          { externalAttrs: e.externalAttrs },
+    };
+  });
+  var profile = opts.profile || "balanced";
+  var result = validateEntries(guardEntries, { profile: profile });
+  return {
+    entries:   rawEntries,
+    issues:    (result && result.issues) || [],
+    decisions: (result && result.decisions) || {},
+  };
+}
+
+/**
+ * @primitive b.guardArchive.zipBombPolicy
+ * @signature b.guardArchive.zipBombPolicy(opts)
+ * @since     0.12.7
+ * @status    stable
+ * @related   b.archive.read.zip, b.safeArchive.extract
+ *
+ * Policy-object builder for decompression-bomb caps. Operators
+ * declare the cap set once + reuse it across `b.archive.read.zip` /
+ * `b.safeArchive.extract` call sites. Defaults match the cap shape
+ * in `lib/archive-read.js` `DEFAULT_BOMB_POLICY`.
+ *
+ * @opts
+ *   maxEntries:                65535,
+ *   maxEntryDecompressedBytes: 128 * MiB,
+ *   maxTotalDecompressedBytes: 4 * GiB,
+ *   maxExpansionRatio:         100,
+ *
+ * @example
+ *   var policy = b.guardArchive.zipBombPolicy({
+ *     maxTotalDecompressedBytes: 256 * 1024 * 1024,
+ *     maxExpansionRatio: 50,
+ *   });
+ *   await b.safeArchive.extract({ source, destination, bombPolicy: policy });
+ */
+function zipBombPolicy(opts) {
+  opts = opts || {};
+  return Object.freeze({
+    maxEntries:                opts.maxEntries                || 65535,
+    maxEntryDecompressedBytes: opts.maxEntryDecompressedBytes || C.BYTES.mib(128),
+    maxTotalDecompressedBytes: opts.maxTotalDecompressedBytes || C.BYTES.gib(4),
+    maxExpansionRatio:         opts.maxExpansionRatio         || 100,
+  });
+}
+
+/**
+ * @primitive b.guardArchive.entryTypePolicy
+ * @signature b.guardArchive.entryTypePolicy(opts)
+ * @since     0.12.7
+ * @status    stable
+ * @related   b.archive.read.zip, b.safeArchive.extract
+ *
+ * Policy-object builder for entry-type allowlist. Defaults refuse
+ * every "interesting" entry type (symlink / hardlink / device / fifo
+ * / socket); operators opt in per-type and route through the
+ * additional realpath-on-target check in `b.guardFilename.
+ * verifyExtractionPath`.
+ *
+ * Symlinks + hardlinks under default settings are refused
+ * unconditionally — CVE-2025-11001 / 11002 / 26960 class.
+ *
+ * @opts
+ *   symlinks:   false,
+ *   hardlinks:  false,
+ *   devices:    false,
+ *   fifos:      false,
+ *   sockets:    false,
+ *
+ * @example
+ *   var policy = b.guardArchive.entryTypePolicy({ symlinks: true });
+ *   await b.safeArchive.extract({ source, destination, entryTypePolicy: policy });
+ */
+function entryTypePolicy(opts) {
+  opts = opts || {};
+  return Object.freeze({
+    symlinks:  opts.symlinks  === true,
+    hardlinks: opts.hardlinks === true,
+    devices:   opts.devices   === true,
+    fifos:     opts.fifos     === true,
+    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);
+}