supply-chain-guard 6.5.1 → 6.5.2

package/README.md

@@ -30,7 +30,7 @@ Gate every pull request:
 
 ```yaml
 - uses: actions/checkout@v4
-- uses: homeofe/supply-chain-guard@v6.5.1
+- uses: homeofe/supply-chain-guard@v6.5.2
 ```
 
 Let your AI coding agent check a package before it installs it (MCP):
@@ -204,7 +204,7 @@ Run the scanner as a [pre-commit](https://pre-commit.com) hook (Python-ecosystem
 ```yaml
 repos:
   - repo: https://github.com/homeofe/supply-chain-guard
-    rev: v6.5.1
+    rev: v6.5.2
     hooks:
       - id: supply-chain-guard
 ```
@@ -236,7 +236,7 @@ The hook scans the repository root on every commit and fails on high or critical
 Run the scanner without a Node toolchain via the official multi-arch image (linux/amd64, linux/arm64), published to GHCR on every release tag:
 
 ```bash
-docker run --rm -v ${PWD}:/scan ghcr.io/homeofe/supply-chain-guard:6.5.1 scan /scan
+docker run --rm -v ${PWD}:/scan ghcr.io/homeofe/supply-chain-guard:6.5.2 scan /scan
 ```
 
 `${PWD}` works in bash, zsh, and PowerShell; in cmd.exe use `%cd%` instead.
@@ -245,8 +245,8 @@ The image keeps the catalog cache in `/cache` (`SCG_CACHE_DIR`), so it is gone
 after `--rm`. To keep it across runs, mount a named volume there:
 
 ```bash
-docker run --rm -v scg-cache:/cache ghcr.io/homeofe/supply-chain-guard:6.5.1 feed refresh
-docker run --rm -v scg-cache:/cache -v ${PWD}:/scan ghcr.io/homeofe/supply-chain-guard:6.5.1 scan /scan
+docker run --rm -v scg-cache:/cache ghcr.io/homeofe/supply-chain-guard:6.5.2 feed refresh
+docker run --rm -v scg-cache:/cache -v ${PWD}:/scan ghcr.io/homeofe/supply-chain-guard:6.5.2 scan /scan
 ```
 
 ## Quickstart
@@ -532,7 +532,7 @@ The external file is one entry per line, `#` for comments, `sha256:<digest>` for
 **The two sources are not equally trusted, and the difference is deliberate.** `SCG_INTERNAL_DISCLOSURE_FILE` is set by whoever runs the scan, so it may name any path on the machine and carry any pattern. `internalDisclosure.externalFile` and `internalDisclosure.patterns` live in the committed policy file, which travels inside the repository being scanned, and scanning a repository you do not own is the ordinary case for this tool. Entries from there are therefore bounded:
 
 - `externalFile` must stay inside the scanned directory. An absolute path is refused, a relative path that climbs out with `..` is refused, and so is one that leaves through a symbolic link. The file is not opened, so nothing about a path outside the tree reaches the report. The bound is the scanned directory and nothing narrower: a path that stays inside it is still read, `.git/config` included, so a committed `externalFile` can still point at whatever your runner wrote into the workspace. Matches from it stay redacted.
-- A regular expression from `patterns`, **or from an `externalFile` that is inside the tree**, is capped at 200 characters and refused when it quantifies a group that already contains a variable quantifier (`(a+)+`, `(a?)*`, and the like). That shape can take exponential time to report no match, so one committed line would otherwise occupy a runner until the workflow times out.
+- A regular expression from `patterns`, **or from an `externalFile` that is inside the tree**, is capped at 200 characters and limited to a safe subset: no quantified group at all (`(a+)+`, `(a|a)+`, `(a|ab)*`, `(a+){2,30}`), no backreference and no lookaround. Literals, unquantified groups and quantified single characters or classes (`[a-z0-9.-]+`, `ab[0-9]{3}`) are accepted. A quantified group can take exponential time to report no match, so one committed line would otherwise occupy a runner until the workflow times out. A pattern from the operator's own file or environment variable is not restricted.
 - Whatever survives those checks runs under a wall-clock budget for the whole scan. On overrun the file reports `INTERNAL_DISCLOSURE_TRUNCATED` rather than running on.
 
 A refusal is an `INTERNAL_DENYLIST_REFUSED` finding at `medium` severity, and like every other coverage finding it marks the scan partial rather than passing quietly. In the published Action a partial scan exits 1 on its own, independently of `fail-on`. None of this applies to the environment-variable source.
@@ -612,13 +612,21 @@ baseline:
 
 Findings can also be suppressed inline with a comment on the line directly
 above them: `// scg-ignore-next-line RULE reason` (JS/TS) or
-`# scg-ignore-next-line RULE` (Python/YAML/shell).
+`# scg-ignore-next-line RULE` (Python/YAML/shell). Inline comments apply to
+local directory scans only, and never hide a `high` or `critical` finding in a
+cloned GitHub repository, an MCP `scan_directory` call, or an npm, PyPI or
+VS Code package scan.
 
 ### Where the policy is read from, and what that means on a pull request
 
-The policy file is read **from the directory being scanned**, and from nowhere
-else. There is no flag, environment variable or Action input that points the
-scanner at a policy outside the scan target.
+For a local directory scan the policy file is read **from the directory being
+scanned**, and from nowhere else. There is no flag, environment variable or
+Action input that points the scanner at a policy outside the scan target.
+
+A scan whose target is a cloned GitHub repository URL, and the MCP
+`scan_directory` tool, **never load a policy file from the scanned tree**
+(library callers can set `trustTargetPolicy: false` to get the same). The tree
+there belongs to someone else.
 
 On a `pull_request` event the checkout materialises the **head of the proposing
 branch**, so the policy that governs the scan is the one on the branch under
@@ -639,6 +647,13 @@ than left to be discovered. What it is **not** is silent:
   (`POLICY_DISABLE_NO_REASON`, `POLICY_IGNORE_NO_REASON`,
   `POLICY_SUPPRESSION_NO_REASON`), so an undocumented exclusion costs a line in
   the report rather than nothing.
+- When the policy, or an inline `scg-ignore-next-line` comment, removes,
+  ignores or downgrades a `high` or `critical` finding, the scan runs a second
+  pass without them and the report gains a medium `POLICY_SUPPRESSED_SEVERE`
+  finding that lists the rule ids and counts, plus `riskLevelBeforePolicy` and
+  `maxSeverityBeforePolicy` (JSON and the "RISK BEFORE POLICY" text line). The
+  exit code is not changed by default, because suppressing a false positive is
+  the intended use of the mechanism. A scan with neither stays single-pass.
 
 If your threat model includes an untrusted proposer, the controls that actually
 hold are outside this tool: require review on `.supply-chain-guard.yml` through
@@ -1001,7 +1016,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: homeofe/supply-chain-guard@v6.5.1
+      - uses: homeofe/supply-chain-guard@v6.5.2
         with:
           fail-on: critical
           comment-on-pr: true
@@ -1089,7 +1104,7 @@ two are never confused. If a deliberately frozen rule set is the intent, exclude
 the rule by name:
 
 ```yaml
-- uses: homeofe/supply-chain-guard@v6.5.1
+- uses: homeofe/supply-chain-guard@v6.5.2
   with:
     exclude-rules: THREAT_FEED_STALE
 ```
@@ -1112,6 +1127,20 @@ scans, in the per-user cache directory unless `--cache-dir` or `SCG_CACHE_DIR`
 names another (see [Catalog cache](#catalog-cache)). The cache belongs to one
 release, so an upgrade needs a new refresh.
 
+A catalog that was never downloaded is the ordinary state of a fresh install, so
+it stays an informational note and does not mark the scan partial. A catalog
+that IS on disk but cannot be used (unreadable or truncated, or not matching
+the digest this release pins) is reported as
+`THREAT_FEED_CATALOG_UNAVAILABLE` instead: the scan is marked partial and exits
+non-zero, because the historical indicators were silently not consulted. Run
+`supply-chain-guard feed refresh` to replace it. A catalog that `feed refresh`
+installed for this release and that has since been deleted counts the same way:
+the refresh leaves a small `catalog-installed.json` marker beside it, and a
+missing catalog with that marker present is `THREAT_FEED_CATALOG_UNAVAILABLE`
+(high, partial), not a fresh install. The marker only ever raises the finding; a
+missing, malformed or older-release marker reads as never installed.
+`catalog: required` raises both rules to critical.
+
 #### Catalog cache
 
 `feed refresh` and every scan resolve the same directory, in this order:
@@ -1192,7 +1221,7 @@ preceding `feed refresh` in the workflow does not count. `catalog: required`
 on the Action therefore needs:
 
 ```yaml
-- uses: homeofe/supply-chain-guard@v6.5.1
+- uses: homeofe/supply-chain-guard@v6.5.2
   with:
     refresh-catalog: true
 ```
@@ -1203,7 +1232,7 @@ setting rather than firing on every scan. If scanning against the bundled set
 alone is the intent, exclude the rule by name:
 
 ```yaml
-- uses: homeofe/supply-chain-guard@v6.5.1
+- uses: homeofe/supply-chain-guard@v6.5.2
   with:
     exclude-rules: THREAT_FEED_CATALOG_MISSING
 ```
@@ -1327,6 +1356,24 @@ supply-chain-guard feed osv       # export malicious-package IOCs as OSV records
 
 A refreshed feed is merged into every scan for the next 24 hours automatically.
 
+**Feed integrity:** the default source is the `feed.json` attached to the latest
+GitHub Release, with `feed.json.sig` beside it, an Ed25519 signature over the
+exact bytes of the feed that the release job makes. `feed refresh` verifies it
+against the public key compiled into the installed package (fingerprint in
+[SECURITY.md](SECURITY.md#feed-integrity)) before parsing anything, and refuses
+a missing, malformed or wrong signature with a non-zero exit, leaving the
+previous cache in place. The signed bytes and signature are kept beside the
+cache and checked again on every scan, so a cache edited or planted afterwards
+is reported as `THREAT_FEED_CACHE_UNREADABLE` and the scan is partial.
+
+A self-hosted mirror passed with `--url` must serve `feed.json.sig` next to the
+feed, signed by the same key. A mirror that cannot be signed can be accepted
+explicitly with `feed refresh --url <url> --allow-unsigned-feed`; that prints a
+warning, records in the cache that the feed was not verified, and trusts the
+feed as downloaded. There is no environment variable for it. The feed is
+published with each release, so a refresh picks up the indicators of the latest
+release rather than of the latest commit.
+
 **Rule-set age:** `feed stats` reports two ages, the one bundled with the
 installed version and the effective one at scan time, and marks either `[STALE]`
 past 30 days. `--format json` returns the same values as `bundledFreshness` and

package/action.yml

@@ -18,8 +18,14 @@ branding:
 # suppressed by the loaded config is named in the scan report in every output
 # format, including the markdown body of the pull request comment this Action
 # posts by default, and a narrowing with no written reason is reported as a
-# finding. See the "Where the policy is read from" section of the README for
-# the controls that apply when the proposer is untrusted.
+# finding. When the config (or an inline scg-ignore-next-line comment) hides a
+# high or critical finding, the report adds POLICY_SUPPRESSED_SEVERE and
+# riskLevelBeforePolicy, the risk level the scan would have had without it.
+# A policy file and inline suppression comments are NOT honoured for a
+# high or critical finding when the scan target is a cloned GitHub repository
+# URL or an MCP scan_directory call. See the "Where the policy is read from"
+# section of the README for the controls that apply when the proposer is
+# untrusted.
 inputs:
   path:
     description: "Path to scan (defaults to repository root)"
@@ -99,7 +105,7 @@ runs:
     - name: Install supply-chain-guard
       shell: bash
       env:
-        SCG_VERSION: "6.5.1"
+        SCG_VERSION: "6.5.2"
         SCG_EXPECTED_REPOSITORY: "homeofe/supply-chain-guard"
         SCG_EXPECTED_REPOSITORY_ID: "1185867580"
         SCG_EXPECTED_WORKFLOW: ".github/workflows/ci.yml"
@@ -253,6 +259,7 @@ runs:
             or . == "INTERNAL_DENYLIST_REFUSED"
             or . == "POLICY_INVALID_INTERNAL_TERM"
             or . == "THREAT_FEED_CACHE_UNREADABLE"
+            or . == "THREAT_FEED_CATALOG_UNAVAILABLE"
             or . == "DIFF_BASE_UNAVAILABLE"
             or . == "RISK_HISTORY_UNREADABLE"
             or . == "TRIAGE_STORE_UNREADABLE"

package/dist/archive-extractor.d.ts

@@ -1,6 +1,7 @@
 /**
- * Archive extraction helpers. Every member is validated before an argv-array
- * extractor invocation so an archive cannot write outside the extraction root.
+ * Archive extraction helpers. Every member is validated and then written by
+ * this module itself (no extractor process), so an archive cannot write outside
+ * the extraction root and the validated path is the written path.
  */
 export declare const ARCHIVE_MAX_ENTRIES = 100000;
 export declare const ARCHIVE_MAX_INPUT_BYTES: number;
@@ -11,7 +12,29 @@ export declare class ArchiveSecurityError extends Error {
 }
 export declare function preflightZipArchive(archivePath: string): void;
 export declare function preflightTarArchive(archivePath: string): void;
-export declare function extractZip(archivePath: string, extractDir: string, overwrite?: boolean): void;
-export declare function extractTar(archivePath: string, extractDir: string): void;
-export declare function extractTarGz(archivePath: string, extractDir: string): void;
+export interface TarExtractionResult {
+    /**
+     * Symlink and hardlink members whose content was NOT written. A link that
+     * resolves to a regular file in the archive is written as a copy of that file
+     * instead; only links to directories (or whose path a directory already
+     * occupies) land here. No link is ever created on disk. Callers report each
+     * as an incomplete path so the result is partial, not silently clean.
+     */
+    skippedLinks: string[];
+}
+/**
+ * Extract a ZIP by writing the members the parser validated, never by spawning
+ * `unzip` or bsdtar: a tool may read names, extra fields or entry types
+ * differently from what was validated. Default keeps files that already exist;
+ * `overwrite` replaces an existing regular file (never a link or directory).
+ */
+export declare function extractZip(archivePath: string, extractDir: string, overwrite?: boolean): TarExtractionResult;
+/**
+ * Extract a tar (gzip, bzip2 and xz are autodetected) by writing the members
+ * the parser validated, never by spawning the PATH `tar`. This keeps the
+ * validated path identical to the written path and works the same on every
+ * host, including Windows machines whose PATH puts GNU tar before System32.
+ */
+export declare function extractTar(archivePath: string, extractDir: string): TarExtractionResult;
+export declare function extractTarGz(archivePath: string, extractDir: string): TarExtractionResult;
 //# sourceMappingURL=archive-extractor.d.ts.map

package/dist/archive-extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-extractor.d.ts","sourceRoot":"","sources":["../src/archive-extractor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,eAAO,MAAM,mBAAmB,SAAU,CAAC;AAC3C,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AACzD,eAAO,MAAM,0BAA0B,QAAoB,CAAC;AAC5D,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAgC9C,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAmZD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CA8E7D;AA6FD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAyG7D;AAED,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,IAAI,CA2B3F;AAED,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAKxE;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAK1E"}
+{"version":3,"file":"archive-extractor.d.ts","sourceRoot":"","sources":["../src/archive-extractor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,eAAO,MAAM,mBAAmB,SAAU,CAAC;AAC3C,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AACzD,eAAO,MAAM,0BAA0B,QAAoB,CAAC;AAC5D,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAkC9C,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AA4fD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAE7D;AAsOD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AA2GD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,mBAAmB,CAM1G;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAEvF;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAEzF"}

package/dist/archive-extractor.js

@@ -1,7 +1,8 @@
 "use strict";
 /**
- * Archive extraction helpers. Every member is validated before an argv-array
- * extractor invocation so an archive cannot write outside the extraction root.
+ * Archive extraction helpers. Every member is validated and then written by
+ * this module itself (no extractor process), so an archive cannot write outside
+ * the extraction root and the validated path is the written path.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -43,9 +44,10 @@ exports.preflightTarArchive = preflightTarArchive;
 exports.extractZip = extractZip;
 exports.extractTar = extractTar;
 exports.extractTarGz = extractTarGz;
-const node_child_process_1 = require("node:child_process");
+const safe_exec_js_1 = require("./safe-exec.js");
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const zlib = __importStar(require("node:zlib"));
 const node_zlib_1 = require("node:zlib");
 exports.ARCHIVE_MAX_ENTRIES = 100_000;
 exports.ARCHIVE_MAX_INPUT_BYTES = 128 * 1024 * 1024;
@@ -492,7 +494,28 @@ function decodeZipPayload(entry, compressed) {
         unsafe(`member "${entry.path || "."}" payload cannot be decompressed safely`);
     }
 }
-function preflightZipArchive(archivePath) {
+/** CRC-32 (IEEE 802.3), as ZIP stores it. `zlib.crc32` exists from Node 22.2; engines allows 22.0. */
+let crcTable;
+function crc32Of(data) {
+    const native = zlib.crc32;
+    if (typeof native === "function")
+        return native(data) >>> 0;
+    if (crcTable === undefined) {
+        crcTable = new Uint32Array(256);
+        for (let n = 0; n < 256; n++) {
+            let c = n;
+            for (let k = 0; k < 8; k++)
+                c = (c & 1) !== 0 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+            crcTable[n] = c >>> 0;
+        }
+    }
+    let crc = 0xffffffff;
+    for (let index = 0; index < data.length; index++)
+        crc = crcTable[(crc ^ data[index]) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** Validate a ZIP and return its members with the payloads that were validated. */
+function parseZipArchive(archivePath) {
     const content = readBoundedArchive(path.resolve(archivePath));
     const eocdOffset = findZipEndOfCentralDirectory(content);
     const location = parseZipDirectoryLocation(content, eocdOffset);
@@ -568,6 +591,10 @@ function preflightZipArchive(archivePath) {
     for (const entry of entries) {
         const local = zipLocalPayload(content, entry, location.centralOffset);
         const expanded = decodeZipPayload(entry, local.compressed);
+        // The central directory's CRC is what every other reader trusts; a payload
+        // that disagrees was altered or corrupted after it was described.
+        if (crc32Of(expanded) !== entry.crc32)
+            unsafe(`member "${entry.path || "."}" fails its CRC-32 check`);
         if (entry.kind === "directory" && expanded.length !== 0)
             unsafe(`directory "${entry.path || "."}" has a payload`);
         if (entry.kind === "symlink") {
@@ -575,6 +602,8 @@ function preflightZipArchive(archivePath) {
                 unsafe(`link "${entry.path}" target is too large`);
             entry.target = resolveRelativeTarget(entry.path, decodeZipPortableString(expanded, entry.flags, `ZIP link "${entry.path}" target`));
         }
+        else if (entry.kind === "file")
+            entry.data = expanded;
         localRegions.push({ start: local.start, end: local.end, path: entry.path || "." });
     }
     localRegions.sort((left, right) => left.start - right.start || left.end - right.end);
@@ -583,7 +612,12 @@ function preflightZipArchive(archivePath) {
             unsafe(`local ZIP regions for "${localRegions[index - 1].path}" and "${localRegions[index].path}" overlap`);
         }
     }
-    validateArchiveGraph(entries.filter((entry) => entry.path.length > 0));
+    const members = entries.filter((entry) => entry.path.length > 0);
+    validateArchiveGraph(members);
+    return members;
+}
+function preflightZipArchive(archivePath) {
+    parseZipArchive(archivePath);
 }
 function parseTarNumber(field, label) {
     if (field.length === 0)
@@ -683,7 +717,7 @@ function decompressTarArchive(archivePath, content) {
     const isXz = content.length >= 6 && content.subarray(0, 6).equals(Buffer.from([0xfd, 0x37, 0x7a, 0x58, 0x5a, 0x00]));
     if (isBzip2 || isXz) {
         try {
-            return (0, node_child_process_1.execFileSync)(isBzip2 ? "bzip2" : "xz", ["-dc", archivePath], {
+            return (0, safe_exec_js_1.execToolSync)(isBzip2 ? "bzip2" : "xz", ["-dc", archivePath], {
                 encoding: "buffer", maxBuffer: exports.ARCHIVE_MAX_EXPANDED_BYTES + 1, stdio: ["ignore", "pipe", "pipe"],
             });
         }
@@ -693,7 +727,20 @@ function decompressTarArchive(archivePath, content) {
     }
     return content;
 }
-function preflightTarArchive(archivePath) {
+/** A validated tar member; `data` is set for regular files only. */
+/**
+ * Parse and validate every tar header, returning the members exactly as the
+ * extractor will write them. Metadata precedence (one rule, documented here
+ * because GNU tar and bsdtar disagree on several corners):
+ *   - a PAX `x` record applies to the next member and wins over GNU `L`/`K`
+ *     long-name records, whatever order they appear in;
+ *   - a GNU `L`/`K` record wins over the header fields;
+ *   - a PAX `g` record may carry neither `path` nor `linkpath` (the two
+ *     extractors disagree on it, so the archive is refused).
+ * Nothing here is delegated to a system `tar`, so no dialect can resolve a
+ * member to a different path than the one validated.
+ */
+function parseTarArchive(archivePath) {
     const resolvedArchivePath = path.resolve(archivePath);
     const compressed = readBoundedArchive(resolvedArchivePath);
     const content = decompressTarArchive(resolvedArchivePath, compressed);
@@ -706,8 +753,10 @@ function preflightTarArchive(archivePath) {
     let headerCount = 0;
     let cursor = 0;
     let sawEndMarker = false;
-    let nextOverrides = {};
+    let paxOverrides = {};
+    let gnuOverrides = {};
     let globalOverrides = {};
+    const pendingMetadata = () => Object.keys(paxOverrides).length > 0 || Object.keys(gnuOverrides).length > 0;
     while (cursor + TAR_BLOCK_SIZE <= content.length) {
         const header = content.subarray(cursor, cursor + TAR_BLOCK_SIZE);
         if (header.every((byte) => byte === 0)) {
@@ -722,20 +771,20 @@ function preflightTarArchive(archivePath) {
             unsafe(`entry count exceeds ${exports.ARCHIVE_MAX_ENTRIES}`);
         verifyTarChecksum(header);
         const headerNameBytes = tarFieldBytes(header, 0, 100);
-        const posixUstar = header.subarray(257, 263).equals(Buffer.from([0x75, 0x73, 0x74, 0x61, 0x72, 0x00])) &&
-            header[263] === 0x30 &&
-            header[264] === 0x30;
+        // Any `ustar\0` magic is POSIX ustar whatever the two version bytes say:
+        // GNU tar and bsdtar both honour the prefix field then.
+        const posixUstar = header.subarray(257, 263).equals(Buffer.from([0x75, 0x73, 0x74, 0x61, 0x72, 0x00]));
         // Bytes 345..499 are a pathname prefix only in POSIX ustar/PAX. Old-GNU
-        // uses the same region for timestamps and sparse metadata; V7 leaves it
-        // outside the header. Treating either as a prefix validates a path that the
-        // extractor never writes.
+        // (`ustar  `) uses the same region for timestamps and sparse metadata; V7
+        // leaves it outside the header. Treating either as a prefix would validate
+        // a path the extractor never writes.
         const prefixBytes = posixUstar
             ? tarFieldBytes(header, 345, 155)
             : Buffer.alloc(0);
         const rawHeaderLinkBytes = tarFieldBytes(header, 157, 100);
         const typeFlag = header[156] === 0 ? "0" : String.fromCharCode(header[156]);
         const headerSize = parseTarNumber(header.subarray(124, 136), "tar entry size");
-        const overrides = { ...globalOverrides, ...nextOverrides };
+        const overrides = { ...globalOverrides, ...gnuOverrides, ...paxOverrides };
         const metadataRecord = typeFlag === "x" || typeFlag === "g" ||
             typeFlag === "L" || typeFlag === "K";
         const size = metadataRecord ? headerSize : (overrides.size ?? headerSize);
@@ -750,10 +799,14 @@ function preflightTarArchive(archivePath) {
             unsafe("tar entry padding is truncated");
         if (typeFlag === "x" || typeFlag === "g") {
             const parsed = parsePax(payload);
-            if (typeFlag === "g")
+            if (typeFlag === "g") {
+                if (parsed.path !== undefined || parsed.linkpath !== undefined) {
+                    unsafe("a PAX global record carries path or linkpath, which extractors apply inconsistently");
+                }
                 globalOverrides = { ...globalOverrides, ...parsed };
+            }
             else
-                nextOverrides = { ...nextOverrides, ...parsed };
+                paxOverrides = { ...paxOverrides, ...parsed };
             cursor = nextCursor;
             continue;
         }
@@ -762,13 +815,14 @@ function preflightTarArchive(archivePath) {
                 unsafe("GNU tar long-name record is too large");
             const nul = payload.indexOf(0);
             const value = decodeLegacyTarString(nul === -1 ? payload : payload.subarray(0, nul), "GNU tar long-name record");
-            nextOverrides = typeFlag === "L"
-                ? { ...nextOverrides, path: value }
-                : { ...nextOverrides, linkpath: value };
+            gnuOverrides = typeFlag === "L"
+                ? { ...gnuOverrides, path: value }
+                : { ...gnuOverrides, linkpath: value };
             cursor = nextCursor;
             continue;
         }
-        const selectedOverrides = { ...globalOverrides, ...nextOverrides };
+        // PAX `x` over GNU `L`/`K`, independent of record order (see above).
+        const selectedOverrides = { ...gnuOverrides, ...paxOverrides };
         let rawPath = selectedOverrides.path;
         if (rawPath === undefined) {
             const headerName = decodeLegacyTarString(headerNameBytes, "tar header name");
@@ -779,12 +833,20 @@ function preflightTarArchive(archivePath) {
         if (rawLink === undefined && (typeFlag === "1" || typeFlag === "2")) {
             rawLink = decodeLegacyTarString(rawHeaderLinkBytes, "tar header link target");
         }
+        const carriesLinkpath = rawLink !== undefined;
         rawLink ??= "";
-        nextOverrides = {};
+        paxOverrides = {};
+        gnuOverrides = {};
         const normalizedPath = normalizeMemberPath(rawPath, "entry path", typeFlag === "5");
+        // bsdtar turns a regular file that carries a linkpath into a hardlink while
+        // GNU tar writes a regular file, so the member type would depend on the
+        // extractor. Refuse it.
+        if (carriesLinkpath && (typeFlag === "0" || typeFlag === "7" || typeFlag === "5")) {
+            unsafe(`member "${normalizedPath}" is not a link but carries a linkpath`);
+        }
         let entry;
         if (typeFlag === "0" || typeFlag === "7")
-            entry = { path: normalizedPath, kind: "file" };
+            entry = { path: normalizedPath, kind: "file", data: payload };
         else if (typeFlag === "5") {
             if (size !== 0)
                 unsafe(`directory "${normalizedPath}" has a data payload`);
@@ -811,46 +873,158 @@ function preflightTarArchive(archivePath) {
         unsafe("tar end marker is missing");
     if (!content.subarray(cursor).every((byte) => byte === 0))
         unsafe("tar contains non-zero data after its end marker");
-    if (Object.keys(nextOverrides).length > 0)
+    if (pendingMetadata())
         unsafe("tar ends with metadata that does not describe a member");
     validateArchiveGraph(entries.filter((entry) => entry.path.length > 0));
+    return entries;
+}
+function preflightTarArchive(archivePath) {
+    parseTarArchive(archivePath);
+}
+/** Create `rel` below `root` one component at a time, refusing anything that is not a plain directory. */
+function ensureContainedDirectory(root, rootReal, rel, verified) {
+    let current = root;
+    let built = "";
+    for (const component of rel === "" ? [] : rel.split("/")) {
+        built = built === "" ? component : `${built}/${component}`;
+        current = path.join(current, component);
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch {
+            stat = undefined;
+        }
+        if (stat === undefined)
+            fs.mkdirSync(current);
+        else if (!stat.isDirectory())
+            unsafe(`"${built}" already exists and is not a directory`);
+    }
+    if (!verified.has(rel)) {
+        const real = fs.realpathSync(current);
+        if (real !== rootReal && !real.startsWith(rootReal + path.sep)) {
+            unsafe(`"${rel || "."}" resolves outside the extraction root`);
+        }
+        verified.add(rel);
+    }
+    return current;
+}
+/**
+ * Write the validated members ourselves: regular files and directories only,
+ * every file created with `wx` so nothing existing is followed or replaced.
+ */
+function writeArchiveMembers(members, extractDir, existing = "refuse") {
+    fs.mkdirSync(extractDir, { recursive: true });
+    const rootReal = fs.realpathSync(extractDir);
+    const verified = new Set();
+    const skippedLinks = [];
+    const writeFile = (memberPath, data) => {
+        const slash = memberPath.lastIndexOf("/");
+        const parentRel = slash === -1 ? "" : memberPath.slice(0, slash);
+        const parent = ensureContainedDirectory(extractDir, rootReal, parentRel, verified);
+        const target = path.join(parent, memberPath.slice(slash + 1));
+        let fd;
+        try {
+            fd = fs.openSync(target, "wx", 0o644);
+        }
+        catch { /* handled below */ }
+        if (fd === undefined) {
+            let stat;
+            try {
+                stat = fs.lstatSync(target);
+            }
+            catch {
+                stat = undefined;
+            }
+            if (stat === undefined || existing === "refuse")
+                unsafe(`"${memberPath}" cannot be created exclusively`);
+            // Keep: an existing entry of any kind stays as it is. Replace: only a
+            // plain regular file is replaced, never a link or directory.
+            if (existing === "keep")
+                return;
+            if (!stat.isFile())
+                unsafe(`"${memberPath}" already exists and is not a regular file`);
+            try {
+                fs.unlinkSync(target);
+                fd = fs.openSync(target, "wx", 0o644);
+            }
+            catch {
+                unsafe(`"${memberPath}" cannot be replaced`);
+            }
+        }
+        try {
+            let written = 0;
+            while (written < data.length)
+                written += fs.writeSync(fd, data, written, data.length - written);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    };
+    const links = [];
+    for (const member of members) {
+        if (member.path.length === 0)
+            continue;
+        if (member.kind === "symlink" || member.kind === "hardlink") {
+            links.push(member);
+            continue;
+        }
+        if (member.kind === "directory") {
+            ensureContainedDirectory(extractDir, rootReal, member.path, verified);
+            continue;
+        }
+        writeFile(member.path, member.data ?? Buffer.alloc(0));
+    }
+    // Links are never created on disk. A link the preflight resolved to a
+    // regular FILE inside the archive is written as a copy of that file's bytes,
+    // so the scan reads exactly what the link would show without a path anything
+    // could follow out of the root; a symlinked LICENSE or README in an sdist must
+    // not make the whole scan partial. A link to a directory, or one whose path is
+    // already taken by a directory, is reported to the caller as skipped.
+    const byPath = new Map();
+    for (const member of members) {
+        if (member.path.length > 0)
+            byPath.set(portableMemberPathKey(member.path), member);
+    }
+    const context = { resolvedPaths: new Map(), work: 0 };
+    for (const link of links) {
+        const resolved = link.kind === "hardlink"
+            ? resolveVirtualPath(link.target ?? "", byPath, true, context)
+            : resolveVirtualPath(link.path, byPath, true, context);
+        const target = byPath.get(portableMemberPathKey(resolved));
+        let taken = false;
+        try {
+            fs.lstatSync(path.join(extractDir, link.path));
+            taken = true;
+        }
+        catch { /* free */ }
+        if (target?.kind !== "file" || (taken && existing === "refuse")) {
+            skippedLinks.push(link.path);
+            continue;
+        }
+        writeFile(link.path, target.data ?? Buffer.alloc(0));
+    }
+    return { skippedLinks };
 }
+/**
+ * Extract a ZIP by writing the members the parser validated, never by spawning
+ * `unzip` or bsdtar: a tool may read names, extra fields or entry types
+ * differently from what was validated. Default keeps files that already exist;
+ * `overwrite` replaces an existing regular file (never a link or directory).
+ */
 function extractZip(archivePath, extractDir, overwrite = false) {
-    const resolvedArchivePath = path.resolve(archivePath);
-    const resolvedExtractDir = path.resolve(extractDir);
-    preflightZipArchive(resolvedArchivePath);
-    fs.mkdirSync(resolvedExtractDir, { recursive: true });
-    if (process.platform === "win32") {
-        // Modern Windows ships bsdtar in System32. It auto-detects ZIP and avoids
-        // making runtime extraction depend on a separately installed Info-ZIP.
-        const windowsRoot = process.env.SystemRoot || "C:\\Windows";
-        const tarPath = path.win32.join(windowsRoot, "System32", "tar.exe");
-        if (!fs.existsSync(tarPath)) {
-            throw new Error(`ZIP extraction backend is unavailable: expected Windows bsdtar at ${tarPath}`);
-        }
-        const args = ["-x"];
-        if (!overwrite)
-            args.push("-k");
-        args.push("-f", resolvedArchivePath, "-C", resolvedExtractDir);
-        (0, node_child_process_1.execFileSync)(tarPath, args, { stdio: "pipe" });
-        return;
-    }
-    const args = ["-q"];
-    if (overwrite)
-        args.push("-o");
-    args.push(resolvedArchivePath, "-d", resolvedExtractDir);
-    (0, node_child_process_1.execFileSync)("unzip", args, { stdio: "pipe" });
+    return writeArchiveMembers(parseZipArchive(archivePath), path.resolve(extractDir), overwrite ? "replace" : "keep");
 }
+/**
+ * Extract a tar (gzip, bzip2 and xz are autodetected) by writing the members
+ * the parser validated, never by spawning the PATH `tar`. This keeps the
+ * validated path identical to the written path and works the same on every
+ * host, including Windows machines whose PATH puts GNU tar before System32.
+ */
 function extractTar(archivePath, extractDir) {
-    const resolvedArchivePath = path.resolve(archivePath);
-    const resolvedExtractDir = path.resolve(extractDir);
-    preflightTarArchive(resolvedArchivePath);
-    (0, node_child_process_1.execFileSync)("tar", ["xf", resolvedArchivePath, "-C", resolvedExtractDir], { stdio: "pipe" });
+    return writeArchiveMembers(parseTarArchive(archivePath), path.resolve(extractDir));
 }
 function extractTarGz(archivePath, extractDir) {
-    const resolvedArchivePath = path.resolve(archivePath);
-    const resolvedExtractDir = path.resolve(extractDir);
-    preflightTarArchive(resolvedArchivePath);
-    (0, node_child_process_1.execFileSync)("tar", ["xzf", resolvedArchivePath, "-C", resolvedExtractDir], { stdio: "pipe" });
+    return extractTar(archivePath, extractDir);
 }
 //# sourceMappingURL=archive-extractor.js.map