@blamejs/core 0.8.43 → 0.8.49

package/lib/guard-archive.js

@@ -1,124 +1,69 @@
 "use strict";
 /**
- * guard-archive — archive content-safety primitive (b.guardArchive).
- *
- * Threat catalog grounded in current research (multiple 2025-2026 CVEs):
- *   - CVE-2025-3445 mholt/archiver Zip Slip
- *   - CVE-2025-32779 EDDI Zip Slip
- *   - CVE-2025-62156 Argo Workflows Zip Slip
- *   - CVE-2025-66945 Zdir Pro Path Traversal
- *   - CVE-2025-45582 GNU Tar Path Traversal (two-step symlink bypass)
- *   - CVE-2025-11001 / 11002 7-Zip symlink + directory traversal RCE
- *   - CVE-2025-4138 Python tarfile extraction-filter symlink bypass
- *   - CVE-2025-4517 Python tarfile path traversal
- *   - CVE-2025-10854 txtai Framework path traversal
- *   - CVE-2025-12060 Keras path traversal
- *   - CVE-2026-26960 node-tar hardlink-via-symlink-chain escape
- *
- *   var rv = b.guardArchive.validateEntries(entries, { profile: "strict" });
- *   var fmt = b.guardArchive.inspectMagic(buffer);
- *   var g = b.guardArchive.gate({ profile: "strict" });
- *
- * **Scope.** This primitive validates archive METADATA (entry list +
- * sizes + flags + types) before extraction. It does NOT include a
- * pure-JS unzip / untar implementation — the framework's no-deps rule
- * argues against shipping a parser for every archive format. Operators
- * use their archive library (built-in zlib for gzip/deflate, OS tar /
- * unzip CLI, or vendored libraries) to enumerate entries, then validate
- * the list before extracting. The gate's job is to refuse hostile
- * metadata BEFORE files touch the filesystem.
- *
- *   var entries = parseZipCentralDirectory(uploadedBuffer);
- *   var rv = b.guardArchive.validateEntries(entries, { profile: "strict" });
- *   if (!rv.ok) throw new Error("hostile archive: " + rv.issues[0].snippet);
- *   await extractEachEntry(entries, extractionRoot);
- *
- * Entry shape (operator passes one of these per archive entry):
- *
- *   {
- *     name:           string,    // entry filename / path WITHIN archive
- *     size:           number,    // uncompressed size in bytes
- *     compressedSize: number,    // compressed size (optional; enables ratio check)
- *     isSymlink:      boolean,   // true if entry creates a symbolic link
- *     isHardlink:     boolean,   // true if entry creates a hardlink
- *     linkTarget:     string,    // when isSymlink/isHardlink: where it points
- *     isDirectory:    boolean,   // directory entry (no extraction needed)
- *     isEncrypted:    boolean,   // entry is encrypted
- *     attrs:          object,    // optional: extra format-specific metadata
- *   }
- *
- * Threat catalog covered:
- *
- *   1. Zip slip / path traversal — entry name with `../`, `..\\`, or
- *      absolute path (leading `/` or `\\` or drive letter). Composes
- *      `b.guardFilename` for per-entry-name validation; archive-level
- *      adds the absolute-path check that filename-leaf doesn't.
- *
- *   2. Symlink escape — entry creates a symbolic link whose `linkTarget`
- *      contains `..` or absolute path that resolves outside the
- *      extraction root. Refused or audited per profile.
- *
- *   3. Hardlink escape — same as symlink but via the hardlink mechanism
- *      (CVE-2026-26960 node-tar class). The extraction step typically
- *      resolves hardlink targets relative to extraction root; entries
- *      with `..` in linkTarget escape.
- *
- *   4. Symlink-chained traversal — operator pre-extracts a symlink, then
- *      a later entry writes through the symlink's target. We refuse any
- *      entry whose extraction path passes THROUGH a symlink already in
- *      the entry list (when the operator passes pre-sorted entries).
- *
- *   5. Decompression-ratio bombs — per-entry compressedSize/size ratio
- *      cap (default: 100:1 strict, 1000:1 permissive). Aggregate ratio
- *      across all entries also capped.
- *
- *   6. Total-size cap — sum of uncompressed sizes (anti-DoS).
- *
- *   7. File-count cap — number of entries.
- *
- *   8. Nested-archive depth — refuses entries that are themselves
- *      archives unless `maxNestedDepth > 0`. Entry name suffixes are
- *      checked against an archive-extension catalog (.zip / .tar /
- *      .tar.gz / .tgz / .gz / .bz2 / .xz / .7z / .rar / .ar / .cpio /
- *      .lzma / .zst).
- *
- *   9. Per-entry-name validation via b.guardFilename — applies the full
- *      filename-safety catalog (path traversal / null-byte / Windows
- *      reserved names / NTFS ADS / RTLO bidi / overlong UTF-8 / shell-
- *      exec extensions / double-extension) to every entry's name.
- *
- *  10. Duplicate entry names — second entry with the same name silently
- *      overwrites the first on extraction. Refused.
- *
- *  11. Mixed-case duplicate names — case-insensitive collision on Windows
- *      / macOS HFS+ / APFS-non-case-sensitive volumes. Audited.
- *
- *  12. Encryption-claim mismatch — operator opts in to either "all
- *      entries encrypted" or "no entries encrypted"; mixing flagged.
- *
- *  13. Format-claim mismatch — `inspectMagic(buffer)` reads the first
- *      bytes and returns the detected format. Operator can compare
- *      against the declared content-type / extension; mismatch flagged.
- *
- *  14. Sparse archive (tar) — sparse entries can claim large
- *      uncompressed size with zero data; refused unless explicitly
- *      allowed.
- *
- *  15. Anti-DoS caps — total entry count, per-entry size, total size,
- *      compression ratio, recursion depth.
- *
- * Profiles:
- *   strict     — every threat refused; no symlinks; no hardlinks;
- *                no nested archives; 100 entry max; 100 MiB total;
- *                100:1 ratio cap; case-insensitive collision refused.
- *   balanced   — symlinks within extraction-root allowed; no hardlinks;
- *                nested-depth 2; 10000 entries; 1 GiB total; 100:1
- *                per-entry / 1000:1 aggregate; case-collision audited.
- *   permissive — symlinks + hardlinks within root allowed; nested-depth
- *                4; 100000 entries; 10 GiB total; 1000:1 ratio.
- *
- * Compliance postures: hipaa / pci-dss / gdpr / soc2 — strict
- * overlay + forensic snapshots.
+ * @module b.guardArchive
+ * @nav    Guards
+ * @title  Guard Archive
+ *
+ * @intro
+ *   Archive content-safety guard — refuses hostile archive metadata
+ *   BEFORE files touch the filesystem. Validates an operator-supplied
+ *   entry list (the framework ships no pure-JS unzip / untar parser per
+ *   the no-deps rule) plus an optional magic-byte inspection on raw
+ *   bytes. Operators enumerate entries via their archive library
+ *   (built-in zlib, OS tar / unzip CLI, vendored mupdf-of-archives) and
+ *   pass `[{ name, size, compressedSize, isSymlink, isHardlink,
+ *   linkTarget, isDirectory, isEncrypted, attrs }, ...]` to
+ *   `validateEntries`.
+ *
+ *   Zip-slip / path-traversal: entry names containing `..` segments,
+ *   leading `/` or `\\`, or Windows drive-letter prefixes (`C:\\`) are
+ *   refused under every profile. Composes `b.guardFilename` for the
+ *   full leaf-safety catalog (null-byte, Windows reserved names, NTFS
+ *   ADS, RTLO bidi, overlong UTF-8, shell-exec extensions, double-
+ *   extension). Tracks the 2025-2026 CVE class: CVE-2025-3445
+ *   (mholt/archiver), CVE-2025-32779 (EDDI), CVE-2025-62156 (Argo
+ *   Workflows), CVE-2025-66945 (Zdir Pro), CVE-2025-45582 (GNU Tar
+ *   two-step symlink bypass), CVE-2025-11001 / 11002 (7-Zip RCE),
+ *   CVE-2025-4138 / 4517 (Python tarfile), CVE-2025-10854 (txtai),
+ *   CVE-2025-12060 (Keras), CVE-2026-26960 (node-tar hardlink-via-
+ *   symlink chain).
+ *
+ *   Symlink / hardlink escape: entries whose `linkTarget` contains `..`
+ *   or is absolute are refused. `strict` rejects symlinks AND hardlinks
+ *   outright; `balanced` permits in-root symlinks and rejects hardlinks
+ *   (CVE-2026-26960 class); `permissive` audits both.
+ *
+ *   Decompression amplification: per-entry `compressedSize`/`size` ratio
+ *   cap defaults 100:1 (strict) / 100:1 (balanced) / 1000:1 (permissive).
+ *   Aggregate ratio across all entries also capped (`maxAggregateRatio`).
+ *   Entry-count cap (`maxEntries`), per-entry size cap (`maxEntryBytes`),
+ *   total uncompressed cap (`maxTotalBytes`).
+ *
+ *   NTFS ADS, overlong UTF-8, leaf-bidi: routed through `b.guardFilename`
+ *   on every entry name with `pathSeparatorsPolicy: "allow"` (archive
+ *   entries legitimately use `/` as separator).
+ *
+ *   Nested archives: entries with archive extensions (`.zip`, `.tar.gz`,
+ *   `.7z`, `.rar`, `.zst`, ...) refused under `strict` (`maxNestedDepth:
+ *   0`); audited under `balanced` (depth 2) / `permissive` (depth 4) so
+ *   the operator can recurse.
+ *
+ *   Duplicate-name + case-insensitive collision detection — the second
+ *   entry with the same name silently overwrites on extraction (refused);
+ *   case-insensitive collisions on Windows / HFS+ / APFS-non-case-
+ *   sensitive volumes (audited / refused per profile).
+ *
+ *   `inspectMagic(buffer)` returns `{ format, magic }` for ZIP / GZIP /
+ *   BZIP2 / XZ / 7Z / RAR4 / RAR5 / LZMA / ZSTD / TAR (the latter via
+ *   the "ustar" magic at offset 257). `checkExtractionPath(name, root)`
+ *   provides a single-entry boolean for callers that already enumerate.
+ *
+ *   Profiles `strict` / `balanced` / `permissive` and compliance
+ *   postures `hipaa` / `pci-dss` / `gdpr` / `soc2` overlay on the
+ *   profile baseline.
+ *
+ * @card
+ *   Archive content-safety guard — refuses hostile archive metadata BEFORE files touch the filesystem.
  */
 
 var lazyRequire = require("./lazy-require");
@@ -296,8 +241,33 @@ function _bufferStartsWith(buf, sig) {
   return true;
 }
 
-// inspectMagic — reads the first bytes of a buffer and returns the
-// detected archive format, or null if not recognized.
+/**
+ * @primitive b.guardArchive.inspectMagic
+ * @signature b.guardArchive.inspectMagic(buffer)
+ * @since     0.7.8
+ * @status    stable
+ * @related   b.guardArchive.validateEntries, b.guardArchive.gate
+ *
+ * Read the first bytes of `buffer` and return
+ * `{ format, magic }` when the buffer matches a known archive-format
+ * signature (`zip` / `gzip` / `bzip2` / `xz` / `7z` / `rar4` / `rar5` /
+ * `lzma` / `zstd` / `tar`). TAR is detected via the `"ustar"` magic
+ * at offset 257 within the first 512-byte header block. Returns
+ * `null` on unrecognized input or non-Buffer / empty input. Pure
+ * inspection — never mutates the buffer or throws.
+ *
+ * Operators compare the detected format against the declared
+ * Content-Type / extension to surface format-claim mismatches before
+ * routing the bytes to a parser.
+ *
+ * @example
+ *   var zipBytes = Buffer.from([0x50, 0x4B, 0x03, 0x04, 0x14, 0x00]);
+ *   var hit = b.guardArchive.inspectMagic(zipBytes);
+ *   hit.format;                                         // → "zip"
+ *
+ *   var noise = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+ *   b.guardArchive.inspectMagic(noise);                 // → null
+ */
 function inspectMagic(buffer) {
   if (!Buffer.isBuffer(buffer) || buffer.length === 0) return null;
   for (var i = 0; i < MAGIC_SIGNATURES.length; i += 1) {
@@ -318,9 +288,35 @@ function inspectMagic(buffer) {
   return null;
 }
 
-// checkExtractionPath — single-entry helper. Returns { ok, reason } for
-// a candidate (entryName, extractionRoot) pair. Anchored, for callers
-// that already enumerate entries and want a per-call boolean.
+/**
+ * @primitive b.guardArchive.checkExtractionPath
+ * @signature b.guardArchive.checkExtractionPath(entryName, extractionRoot)
+ * @since     0.7.8
+ * @status    stable
+ * @related   b.guardArchive.validateEntries, b.guardArchive.gate
+ *
+ * Single-entry boolean check: returns `{ ok, reason }` for a candidate
+ * `(entryName, extractionRoot)` pair. Refuses entries whose name
+ * contains a `..` component (zip slip — CVE-2025-3445 class), is an
+ * absolute path (leading `/`, `\\`, or `C:\\` drive-letter prefix),
+ * carries a null byte, or is empty. The framework cannot resolve
+ * `path.resolve(extractionRoot, entryName)` without a `node:path`
+ * coupling that the gate keeps portable; the operator's extraction
+ * code is expected to additionally call `path.resolve` and confirm
+ * the result starts with `path.resolve(extractionRoot)`.
+ *
+ * Use when the operator already enumerates archive entries and wants
+ * a per-call boolean rather than running the full
+ * `validateEntries` issue list.
+ *
+ * @example
+ *   b.guardArchive.checkExtractionPath("docs/readme.txt", "/var/extract").ok;
+ *   //                                                   → true
+ *
+ *   var bad = b.guardArchive.checkExtractionPath("../etc/passwd", "/var/extract");
+ *   bad.ok;                                              // → false
+ *   bad.reason;                                          // → "entry name contains .. component (zip slip)"
+ */
 function checkExtractionPath(entryName, extractionRoot) {
   if (typeof entryName !== "string" || entryName.length === 0) {
     return { ok: false, reason: "empty entry name" };
@@ -630,6 +626,64 @@ function _detectIssues(entries, opts) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive  b.guardArchive.validateEntries
+ * @signature  b.guardArchive.validateEntries(entries, opts)
+ * @since      0.7.8
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardArchive.gate, b.guardArchive.inspectMagic, b.guardFilename.validate
+ *
+ * Inspect an operator-supplied `entries` array (one entry per archive
+ * member: `{ name, size, compressedSize, isSymlink, isHardlink,
+ * linkTarget, isDirectory, isEncrypted, attrs }`) and return
+ * `{ ok, issues }`. Issues carry `{ kind, severity, ruleId, location,
+ * snippet }` with severity `"warn"` / `"high"` / `"critical"`.
+ * Detected: zip-slip, absolute path, symlink / hardlink escape,
+ * compression-ratio bombs (per-entry + aggregate), per-entry size
+ * cap, total-size cap, entry-count cap, nested-archive entries,
+ * duplicate names, case-insensitive collisions, encryption-claim
+ * mismatch, sparse-tar entries, plus the full `b.guardFilename`
+ * leaf-safety catalog re-attached with archive-context locations.
+ * Pure inspection — never mutates input or throws on hostile entries.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   traversalPolicy:                "reject"|"audit"|"allow",
+ *   absolutePathPolicy:             "reject"|"audit"|"allow",
+ *   symlinkPolicy:                  "reject"|"audit"|"allow",
+ *   hardlinkPolicy:                 "reject"|"audit"|"allow",
+ *   nestedArchivePolicy:            "reject"|"audit"|"allow",
+ *   duplicateNamePolicy:            "reject"|"audit"|"allow",
+ *   caseInsensitiveCollisionPolicy: "reject"|"audit"|"allow",
+ *   encryptionPolicy:               "reject"|"audit"|"allow",
+ *   sparseEntryPolicy:              "reject"|"audit"|"allow",
+ *   filenameProfile:                "balanced"|"strict"|"permissive",
+ *   maxEntries:           number,   // strict 100, balanced 10000, permissive 100000
+ *   maxTotalBytes:        number,   // strict 100 MiB, balanced 1 GiB, permissive 10 GiB
+ *   maxEntryBytes:        number,   // strict 50 MiB, balanced 500 MiB, permissive 2 GiB
+ *   maxCompressionRatio:  number,   // strict / balanced 100, permissive 1000
+ *   maxAggregateRatio:    number,   // strict 200, balanced 1000, permissive 10000
+ *   maxNestedDepth:       number,   // strict 0, balanced 2, permissive 4
+ *
+ * @example
+ *   var rv = b.guardArchive.validateEntries([
+ *     { name: "docs/readme.txt", size: 1000, compressedSize: 500 },
+ *     { name: "../etc/passwd",   size: 100,  compressedSize: 50 },
+ *   ], { profile: "strict" });
+ *   rv.ok;                                               // → false
+ *   rv.issues[0].kind;                                   // → "zip-slip"
+ *   rv.issues[0].severity;                               // → "critical"
+ *
+ *   // Compression-ratio bomb — 50 MiB uncompressed from 50 KiB compressed
+ *   // is 1000:1, far above the 100:1 strict cap.
+ *   var bomb = b.guardArchive.validateEntries([
+ *     { name: "bomb.bin", size: 52428800, compressedSize: 51200 },
+ *   ], { profile: "strict" });
+ *   bomb.issues.some(function (i) { return i.kind === "compression-ratio-bomb"; });
+ *   //                                                   → true
+ */
 function validateEntries(entries, opts) {
   opts = _resolveOpts(opts);
   numericBounds.requireAllPositiveFiniteIntIfPresent(opts,
@@ -646,6 +700,49 @@ function validateEntries(entries, opts) {
   return gateContract.aggregateIssues(_detectIssues(entries, opts));
 }
 
+/**
+ * @primitive  b.guardArchive.gate
+ * @signature  b.guardArchive.gate(opts)
+ * @since      0.7.8
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardArchive.validateEntries, b.guardArchive.inspectMagic, b.fileUpload, b.staticServe
+ *
+ * Build a `b.gateContract` gate suitable for `b.fileUpload({ contentSafety:
+ * { "application/zip": gate } })` or `b.staticServe`. Operators pass
+ * `ctx.entries` (the enumerated entry list from their archive library)
+ * — when only `ctx.bytes` is supplied, the gate runs `inspectMagic` to
+ * confirm the format and refuses with a `"no-entry-list"` issue
+ * directing the operator to enumerate entries explicitly (the
+ * framework ships no parser for any archive format).
+ *
+ * Action chain: `serve` (no issues) → `audit-only` (warn-only) →
+ * `refuse` (any critical/high). Archive content has no safe
+ * sanitization — there is no `sanitize` action in the chain.
+ *
+ * @opts
+ *   profile:    "strict"|"balanced"|"permissive",
+ *   compliance: "hipaa"|"pci-dss"|"gdpr"|"soc2",
+ *   name:       string,
+ *   ...:        any validateEntries opt
+ *
+ * @example
+ *   var archiveGate = b.guardArchive.gate({ profile: "strict" });
+ *
+ *   var verdict = await archiveGate.check({
+ *     entries: [
+ *       { name: "docs/readme.txt", size: 1000, compressedSize: 500 },
+ *       { name: "../etc/passwd",   size: 100,  compressedSize: 50 },
+ *     ],
+ *   });
+ *   verdict.action;                                      // → "refuse"
+ *
+ *   // Bytes-only call without an entry list — operator must enumerate.
+ *   var zipBytes = Buffer.from([0x50, 0x4B, 0x03, 0x04, 0x14, 0x00]);
+ *   var v2 = await archiveGate.check({ bytes: zipBytes });
+ *   v2.action;                                           // → "refuse"
+ *   v2.issues[0].kind;                                   // → "no-entry-list"
+ */
 function gate(opts) {
   opts = _resolveOpts(opts);
   return gateContract.buildGuardGate(
@@ -689,13 +786,78 @@ function gate(opts) {
     });
 }
 
+/**
+ * @primitive b.guardArchive.buildProfile
+ * @signature b.guardArchive.buildProfile(opts)
+ * @since     0.7.8
+ * @status    stable
+ * @related   b.guardArchive.compliancePosture, b.guardArchive.gate
+ *
+ * Resolve a named profile against the guard's PROFILES catalog and
+ * return the merged options bag. Operators introspecting the active
+ * caps (without calling `validateEntries` / `gate`) use this. Throws
+ * `GuardArchiveError("archive.bad-profile")` on unknown name.
+ *
+ * @opts
+ *   profile: "strict"|"balanced"|"permissive",
+ *
+ * @example
+ *   var resolved = b.guardArchive.buildProfile({ profile: "strict" });
+ *   resolved.maxEntries;                                 // → 100
+ *   resolved.symlinkPolicy;                              // → "reject"
+ *   resolved.maxCompressionRatio;                        // → 100
+ */
 var buildProfile = gateContract.makeProfileBuilder(PROFILES);
 
+/**
+ * @primitive  b.guardArchive.compliancePosture
+ * @signature  b.guardArchive.compliancePosture(name)
+ * @since      0.7.8
+ * @status     stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related    b.guardArchive.gate, b.guardArchive.buildProfile
+ *
+ * Return the option overlay for a named compliance posture
+ * (`"hipaa"` / `"pci-dss"` / `"gdpr"` / `"soc2"`). Composes over a
+ * base profile to harden defaults per regulatory regime. Throws
+ * `GuardArchiveError("archive.bad-posture")` on unknown name.
+ *
+ * @example
+ *   var posture = b.guardArchive.compliancePosture("hipaa");
+ *   posture.symlinkPolicy;                               // → "reject"
+ *   posture.hardlinkPolicy;                              // → "reject"
+ *   posture.forensicSnippetBytes;                        // → 256
+ */
 function compliancePosture(name) {
   return gateContract.lookupCompliancePosture(name, COMPLIANCE_POSTURES, _err, "archive");
 }
 
 var _archiveRulePacks = gateContract.makeRulePackLoader(GuardArchiveError, "archive");
+/**
+ * @primitive b.guardArchive.loadRulePack
+ * @signature b.guardArchive.loadRulePack(pack)
+ * @since     0.7.8
+ * @status    stable
+ * @related   b.guardArchive.gate
+ *
+ * Register an operator-supplied rule pack with the guard-archive
+ * registry. The pack is identified by `pack.id` (non-empty string)
+ * and stored for later inspection / dispatch by gates that opt in
+ * via `opts.rulePackId`. Returns the pack object unchanged on
+ * success; throws `GuardArchiveError("archive.bad-opt")` when
+ * `pack` is missing or `pack.id` is not a non-empty string.
+ *
+ * @example
+ *   var pack = b.guardArchive.loadRulePack({
+ *     id: "kb-2026-archive",
+ *     extraReservedNames: ["system32"],
+ *     rules: [
+ *       { id: "no-windows-system", severity: "critical",
+ *         reason: "entry name targets Windows system directory" },
+ *     ],
+ *   });
+ *   pack.id;                                             // → "kb-2026-archive"
+ */
 var loadRulePack = _archiveRulePacks.load;
 
 module.exports = {