border-customs 0.3.0 → 0.3.2

package/README.md

@@ -313,6 +313,7 @@ border <command> [options]
 | `status` | newest gate records per target |
 | `llm-request` | emit the masked review bundle for LLM-authored commits |
 | `llm-ingest <findings.json>` | validate agent findings and record the combined verdict |
+| `scan <[ecosystem:]name@version>` | inspect a third-party published artifact for residue before installing it |
 
 Every subcommand accepts the same global flags (verified against `border <cmd> --help`):
 
@@ -324,7 +325,7 @@ Every subcommand accepts the same global flags (verified against `border <cmd> -
 | `--yes` | execute mutations (push only); without it a push is always DRY-RUN |
 | `--require-engine <list>` | replaces the required-engine set from config; unknown or unprobeable names degrade the run (exit 2) |
 | `--llm` | opt this check into the LLM review layer (a plain check can never satisfy an llm-recorded skip) |
-| `--json` | machine-readable report on stdout (check) |
+| `--json` | machine-readable report on stdout (check, scan) |
 | `--help, -h` | usage table |
 
 ### Exit codes (the contract)
@@ -340,6 +341,73 @@ rests on a leg that silently skipped. Engine exit codes are translated against a
 matrix (`gitleaks` 0/1, `trufflehog` 0/183, `secretlint` 0/1); *anything* else, including a
 126 from gitleaks, is exit 2, never "clean".
 
+### `border scan` — inspect a third-party package before installing it
+
+```bash
+border scan puppeteer@23.11.1   # npm is the default ecosystem
+border scan pypi:requests@2.32.3
+border scan crates:serde@1.0.219
+border scan rubygems:rails@7.1.1
+```
+
+`border scan <[ecosystem:]name@version>` fetches that exact published artifact from its
+registry, materializes it in a throwaway temp directory, and runs the same engine stack
+`check` runs — secrets plus the T0–T4 residue classifiers — over the bytes you are about
+to install. `--json` emits the standard machine-readable report.
+
+**Capability, not fact.** A scan verdict proves what the package *can* do — persist past
+uninstall, write outside the install tree, run hooks on every consumer install — because
+those shapes are readable in the published bytes. Proof that a package *did* persist is
+the uninstall-roundtrip valve, and it ships in 0.4.0; until then treat a scan as pre-install
+risk triage, never as post-mortem evidence.
+
+Scan touches neither side of your work: it reads no ledger and writes no skip records (every
+scan is a full scan), and it creates no `.border/` in your repo — the fetched artifact and
+its temp git tree live in the sandbox and are destroyed when the run ends. Exit codes follow
+the same contract: `0` clean, `1` blocking (HIGH/CRITICAL) findings, `2` the scan could not
+genuinely run — unreachable registry, malformed spec, a tree shape the engines cannot
+consume. A scan that could not run never prints a clean verdict.
+
+crates artifacts get one **envelope normalization** before staging: a registry `.crate`
+ships three files — `Cargo.toml.orig`, `.cargo-ok`, `.cargo_vcs_info.json` — that
+`cargo package` rejects as reserved, so scan drops them before the rebuild and logs each
+dropped file to stderr with the sha256 of its original bytes
+(`border scan: crates envelope normalized: <file> sha256=<hex>`); the rebuild regenerates
+them from the normalized manifest, so no scanned byte is silently lost.
+
+### Engines in consumer installs
+
+`dist/index.js` is one self-contained esbuild bundle and every runtime asset (vendored
+gitleaks rules, prompt template, the secretlint fingerprint snapshot) ships inside `dist/`,
+so after `npm i -D border-customs` (or `-g`) the engine surface is:
+
+- **publint** — installed automatically: it is an exact-pinned runtime dependency of the
+  package, invoked via bin resolution (package-local `node_modules/.bin`, the hoisted
+  project-level `node_modules/.bin`, then `PATH`, then `~/.local/bin`). The
+  `publint-fail` leg of the npm artifact stage works out of the box in a consumer install.
+- **secretlint** — no consumer action, ever: the default lint runs **in-process** with the
+  `@secretlint/*` rule modules already declared as border's own runtime dependencies
+  (`src/engines/secretlint.ts` header). The `mode: "cli"` fallback that spawns a
+  `secretlint` binary is border-internal (test transport); it is not reachable from
+  `border.yaml` or any flag, so installing `secretlint` into your project changes nothing
+  for border. If the engine probe cannot read the bundled lock snapshot
+  (`dist/assets/package-lock.json`), the run fails closed as `DEGRADED-ENGINE` exit 2 —
+  never a silent pass.
+- **gitleaks** — stays external, same posture as `git`: border vendors the 8.30.1 rule
+  config but the binary is yours (on `PATH` or `~/.local/bin/gitleaks`; see the
+  requirements paragraph at the top and `src/engines/ADAPTER-CONTRACT.md`). Missing
+  gitleaks means `border check` records a CRITICAL `DEGRADED-ENGINE` finding and exits 2,
+  and `border scan` exits 2 with `engine binary 'gitleaks' not found; border fails
+  closed`. Neither command degrades to a skip.
+- **trufflehog** — optional third engine, external binary, same posture as gitleaks once
+  enabled: `engines.trufflehog: true` puts it in the required set, and an absent binary
+  degrades the run to exit 2 exactly like a missing gitleaks.
+
+There is no "engine absent ⇒ leg silently skipped" state anywhere: missing required
+engines are exit 2 (`2` = the gate could not answer, see
+[Exit codes](#exit-codes-the-contract)), and the ledger refuses to write a PASS for a
+degraded run.
+
 ## Configuration
 
 Everything border can be told lives in `border.yaml` at the repo root. Unknown keys are
@@ -506,6 +574,19 @@ same one that wrote the commit) how to run the five subcommands, how to produce
 
 ## Changelog
 
+### 0.3.2 (2026-09-10)
+- Fix: CLI invoked through the npm `.bin` shim silently exited 0 without running
+  (entrypoint detection now realpath-canonicalizes both sides). Regression-locked by a
+  pack -> install -> shim-invocation test (`BORDER_PACK_TEST=1`, wired into CI).
+- Fix: `publint` is an exact-pinned runtime dependency, so `border scan`/npm checks work
+  out of the box in consumer installs; README documents the engine posture truthfully.
+- Add: release-coherence seed test pinning the scan User-Agent version to package.json.
+
+### 0.3.1 (2026-09-10)
+- Add: `border scan [ecosystem:]name@version` — static residue inspection of third-party
+  registry packages (npm/PyPI/crates.io/RubyGems), ledger-free by design.
+- Docs: README scan section; crates envelope normalization now logs scrubbed-file hashes.
+
 ### 0.3.0 (2026-09-09)
 
 - **Residue gate (artifact stage).** The blanket install-hook CRITICAL becomes a classified

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "border-customs",
-  "version": "0.1.0",
+  "version": "0.3.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "border",
-      "version": "0.1.0",
+      "name": "border-customs",
+      "version": "0.3.1",
       "license": "MIT",
       "dependencies": {
         "@secretlint/core": "13.0.5",
@@ -14,6 +14,7 @@
         "@secretlint/secretlint-rule-no-homedir": "13.0.5",
         "@secretlint/secretlint-rule-pattern": "13.0.5",
         "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
+        "publint": "0.3.24",
         "yaml": "2.9.0",
         "zod": "4.5.4"
       },
@@ -23,7 +24,6 @@
       "devDependencies": {
         "@types/node": "22.19.0",
         "esbuild": "0.25.12",
-        "publint": "0.3.24",
         "secretlint": "13.0.5",
         "typescript": "5.9.3",
         "verdaccio": "6.10.2"
@@ -601,7 +601,6 @@
       "version": "0.1.7",
       "resolved": "https://registry.npmjs.org/@publint/pack/-/pack-0.1.7.tgz",
       "integrity": "sha512-4EDEmvxWtgsCnnVeBvtFIFZtUhPPt1+bA9JrSwU4Sa//6oKtzCSlGGXYJr44OD9aGISymbieJ4mCKHUygUDU+g==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "tinyexec": "^1.3.0"
@@ -3821,7 +3820,6 @@
       "version": "1.2.0",
       "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz",
       "integrity": "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=4"
@@ -3982,7 +3980,6 @@
       "version": "1.8.0",
       "resolved": "https://registry.npmjs.org/package-manager-detector/-/package-manager-detector-1.8.0.tgz",
       "integrity": "sha512-yQA4H19AmPEoMUeavPMDIe1higySl/gH/yaQrkT/s07Qp+7pp2hYz30N3z2l5BkjVkF9Ow6o0wjJamm2y7Sn0A==",
-      "dev": true,
       "license": "MIT"
     },
     "node_modules/pako": {
@@ -4073,7 +4070,6 @@
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
       "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
-      "dev": true,
       "license": "ISC"
     },
     "node_modules/picomatch": {
@@ -4255,7 +4251,6 @@
       "version": "0.3.24",
       "resolved": "https://registry.npmjs.org/publint/-/publint-0.3.24.tgz",
       "integrity": "sha512-9zS56KrKBoqi5Qt8h92uMP8TTM9AYZSgnmCo4u2priMqkOZvQnTsziZ2p5LJ2ywbYkAjoCDp2jda9u4cgFefIw==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "@publint/pack": "^0.1.7",
@@ -4551,7 +4546,6 @@
       "version": "1.8.1",
       "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz",
       "integrity": "sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==",
-      "dev": true,
       "license": "MIT",
       "dependencies": {
         "mri": "^1.1.0"
@@ -5231,7 +5225,6 @@
       "version": "1.3.1",
       "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.1.tgz",
       "integrity": "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA==",
-      "dev": true,
       "license": "MIT",
       "engines": {
         "node": ">=18"

package/dist/index.js

@@ -13028,7 +13028,8 @@ var require_micromatch = __commonJS({
 });
 
 // src/index.ts
-import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { fileURLToPath as fileURLToPath5, pathToFileURL } from "node:url";
 
 // src/cli.ts
 import { parseArgs } from "node:util";
@@ -37896,10 +37897,14 @@ var NPM_TARGET_LABEL = "artifact";
 var DEFAULT_TOOL_TIMEOUT_MS = 12e4;
 var MESSAGE_TAIL_CHARS = 600;
 var HERE = dirname3(fileURLToPath3(import.meta.url));
-var PUBLINT_LOCAL_BINS = [
-  join6(HERE, "..", "node_modules", ".bin", "publint"),
-  join6(HERE, "..", "..", "node_modules", ".bin", "publint")
-];
+function publintLocalBins(here) {
+  return [
+    join6(here, "..", "node_modules", ".bin", "publint"),
+    join6(here, "..", "..", "node_modules", ".bin", "publint"),
+    join6(here, "..", "..", ".bin", "publint")
+  ];
+}
+var PUBLINT_LOCAL_BINS = publintLocalBins(HERE);
 function tail(text) {
   const trimmed = text.trim();
   return trimmed.length > MESSAGE_TAIL_CHARS ? `${trimmed.slice(-MESSAGE_TAIL_CHARS)}\u2026` : trimmed;
@@ -40394,8 +40399,8 @@ function exitCodeFromVerdict(verdict) {
 var MESSAGE_CAP = 512;
 var URL_IN_TEXT_RE = /(?:\w+:\/\/\S+|[A-Za-z0-9_.+-]+@[A-Za-z0-9_.+-]+:\S+)/g;
 function sanitizeMessage(message) {
-  const oneLine = message.replace(/\s+/g, " ").trim();
-  const scrubbed = oneLine.replace(URL_IN_TEXT_RE, (candidate) => sanitizeUrl(candidate));
+  const oneLine2 = message.replace(/\s+/g, " ").trim();
+  const scrubbed = oneLine2.replace(URL_IN_TEXT_RE, (candidate) => sanitizeUrl(candidate));
   return scrubbed.length > MESSAGE_CAP ? `${scrubbed.slice(0, MESSAGE_CAP - 3)}...` : scrubbed;
 }
 function labelFor(err) {
@@ -40442,17 +40447,17 @@ function requirePassedRecord(kind, i) {
 function rehashRecordedArtifacts(kind, extensions, record2, repoDir) {
   const conventions = extensions;
   const entries = (record2.artifacts ?? []).filter((a) => conventions.some((ext) => a.file.endsWith(ext)));
-  const fail = (detail) => ({ ok: false, message: `artifact changed since check \u2014 ${detail}` });
+  const fail3 = (detail) => ({ ok: false, message: `artifact changed since check \u2014 ${detail}` });
   if (entries.length === 0) {
-    return fail(`the PASSED check recorded no ${kind} artifacts (${conventions.join("/")}) to re-verify`);
+    return fail3(`the PASSED check recorded no ${kind} artifacts (${conventions.join("/")}) to re-verify`);
   }
   const files = [];
   for (const a of entries) {
     const rel = join16(DIST_DIR, basename3(a.file));
     const abs = join16(repoDir, rel);
-    if (!existsSync11(abs)) return fail(`${rel} is missing from the working tree`);
+    if (!existsSync11(abs)) return fail3(`${rel} is missing from the working tree`);
     const digest2 = createHash10("sha256").update(readFileSync10(abs)).digest("hex");
-    if (digest2 !== a.sha256) return fail(`${rel} no longer hashes to the digest recorded by the check`);
+    if (digest2 !== a.sha256) return fail3(`${rel} no longer hashes to the digest recorded by the check`);
     files.push(rel);
   }
   return { ok: true, files: files.sort() };
@@ -40911,7 +40916,7 @@ function npmExposureCoords(cfg, read) {
   return { name, version: version2 };
 }
 function classifyNpmVersionView(o) {
-  const fail = (why) => {
+  const fail3 = (why) => {
     throw new EngineRunError(
       `npm registry probe inconclusive (${why}); refusing to assume the version is absent \u2014 registry unreachable or returned unexpected output, push blocked until the probe succeeds`,
       o.status
@@ -40919,19 +40924,19 @@ function classifyNpmVersionView(o) {
   };
   if (o.status === 0) {
     const text = o.stdout.trim();
-    if (text.length === 0) return fail("exit 0 with empty stdout");
+    if (text.length === 0) return fail3("exit 0 with empty stdout");
     let body;
     try {
       body = JSON.parse(text);
     } catch {
-      return fail("exit 0 with malformed JSON body");
+      return fail3("exit 0 with malformed JSON body");
     }
-    if (typeof body !== "object" || body === null) return fail("exit 0 with non-object JSON body");
+    if (typeof body !== "object" || body === null) return fail3("exit 0 with non-object JSON body");
     return "present";
   }
   if (/code E404\b/.test(o.stderr) || /\b404 Not Found\b/.test(o.stderr)) return "absent";
   const m = /code (E[A-Z0-9_]+|ERR_[A-Z0-9_]+)/.exec(o.stderr);
-  return fail(m === null ? `exit ${String(o.status)} without a 404 marker` : `npm error ${m[1]}`);
+  return fail3(m === null ? `exit ${String(o.status)} without a 404 marker` : `npm error ${m[1]}`);
 }
 function npmNameClaimed(o) {
   if (o.status === 0) return true;
@@ -42024,6 +42029,10 @@ function expandInConfig(cfg, env2) {
   }
   return { ...cfg, targets };
 }
+function parseConfig(text, source = "<inline>", options = {}) {
+  const doc = yamlToJson(text, source);
+  return expandInConfig(validateDoc(doc, source), options.env ?? process.env);
+}
 function deepMergeRaw(base, overlay) {
   if (isRecord(base) && isRecord(overlay)) {
     const out = { ...base };
@@ -43427,6 +43436,336 @@ async function executeYesPush(ctx, loaded) {
   return EXIT_PASS;
 }
 
+// src/scan/scan.ts
+import { mkdtempSync as mkdtempSync5 } from "node:fs";
+import { tmpdir as tmpdir3 } from "node:os";
+import { join as join26 } from "node:path";
+
+// src/scan/config.ts
+function buildScanConfigYaml(eco) {
+  return [
+    "version: 1",
+    "targets:",
+    "  git:",
+    "    remotes: []",
+    `  ${eco}: {}`,
+    "rules:",
+    "  authors:",
+    "    emails: []",
+    "    names: []",
+    "  hosts: []",
+    "  ips: []",
+    "  pathPatterns: []",
+    "residue:",
+    "  enabled: true",
+    ""
+  ].join("\n");
+}
+function synthesizeScanConfig(eco) {
+  return parseConfig(buildScanConfigYaml(eco), "<border scan>");
+}
+
+// src/scan/fetch.ts
+import { createHash as createHash15 } from "node:crypto";
+import { basename as basename4 } from "node:path";
+var SCAN_MAX_ARTIFACT_BYTES = 200 * 1024 * 1024;
+var SCAN_REQUEST_TIMEOUT_MS = 6e4;
+var SCAN_USER_AGENT = "border-customs/0.3.2 (+https://github.com/sumteclab/border; border scan)";
+var CRATES_DOWNLOAD_HOST = "https://static.crates.io";
+var defaultScanFetcher = async (url2, init) => {
+  if (!/^https?:\/\//.test(url2)) throw new EngineRunError(`border scan refuses non-http(s) URL: ${url2}`, null);
+  const res = await fetch(url2, {
+    redirect: "follow",
+    signal: init.signal,
+    headers: { "user-agent": SCAN_USER_AGENT, ...init.headers ?? {} }
+  });
+  const raw = res.headers.get("content-length");
+  const parsed = raw === null ? Number.NaN : Number(raw);
+  return {
+    status: res.status,
+    contentLength: Number.isFinite(parsed) && parsed >= 0 ? parsed : null,
+    chunks: () => {
+      if (res.body === null) {
+        return {
+          async *[Symbol.asyncIterator]() {
+          }
+        };
+      }
+      return res.body;
+    }
+  };
+};
+var fail = (why) => {
+  throw new EngineRunError(`border scan could not fetch the artifact (${why}) \u2014 refusing to scan a partial or absent download (fail-closed)`, null);
+};
+async function readCapped(res, url2, cap = SCAN_MAX_ARTIFACT_BYTES) {
+  if (res.status !== 200) fail(`HTTP ${String(res.status)} for ${url2}`);
+  if (res.contentLength !== null && res.contentLength > cap) {
+    fail(`${url2} announces ${String(res.contentLength)} bytes, over the 200 MiB scan size cap`);
+  }
+  const parts = [];
+  let total = 0;
+  for await (const chunk of res.chunks()) {
+    total += chunk.byteLength;
+    if (total > cap) fail(`${url2} streams past the 200 MiB scan size cap after ${String(total)} bytes`);
+    parts.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(parts);
+}
+async function fetchBytes(fetcher, url2, timeoutMs, headers) {
+  const res = await fetcher(url2, { signal: AbortSignal.timeout(timeoutMs), ...headers !== void 0 ? { headers } : {} });
+  return readCapped(res, url2);
+}
+async function fetchJson(fetcher, url2, timeoutMs) {
+  const body = await fetchBytes(fetcher, url2, timeoutMs);
+  try {
+    return JSON.parse(body.toString("utf8"));
+  } catch {
+    fail(`metadata response from ${url2} is not valid JSON`);
+  }
+}
+var isRecord2 = (v) => typeof v === "object" && v !== null;
+function channelBaseUrl(eco) {
+  const ch = publishChannels().find((c) => c.id === eco);
+  if (ch === void 0 || ch.defaultUrl.length === 0) {
+    throw new EngineRunError(`border scan: channel '${eco}' exposes no defaultUrl`, null);
+  }
+  return ch.defaultUrl;
+}
+function npmMetadataUrl(name, version2, base = channelBaseUrl("npm")) {
+  const enc = name.startsWith("@") ? name.replace("/", "%2F") : name;
+  return `${base}/${enc}/${version2}`;
+}
+function pypiMetadataUrl(name, version2, base = channelBaseUrl("pypi")) {
+  return `${base}/pypi/${encodeURIComponent(name)}/${version2}/json`;
+}
+function cratesDownloadUrl(name, version2) {
+  return `${CRATES_DOWNLOAD_HOST}/crates/${name}/${name}-${version2}.crate`;
+}
+function rubygemsDownloadUrl(name, version2, base = channelBaseUrl("rubygems")) {
+  return `${base}/downloads/${name}-${version2}.gem`;
+}
+function safeArtifactName(raw, fallback) {
+  const base = basename4(raw.split("?")[0] ?? "").replace(/[^A-Za-z0-9._+-]/g, "_");
+  return base.length > 0 && base !== "." && base !== ".." ? base : fallback;
+}
+async function fetchArtifact(spec, o) {
+  const timeoutMs = o.timeoutMs ?? SCAN_REQUEST_TIMEOUT_MS;
+  const label = `${spec.ecosystem}:${spec.name}@${spec.version}`;
+  switch (spec.ecosystem) {
+    case "npm": {
+      const meta3 = await fetchJson(o.fetcher, npmMetadataUrl(spec.name, spec.version), timeoutMs);
+      const dist = isRecord2(meta3) && isRecord2(meta3["dist"]) ? meta3["dist"] : {};
+      const tarball = dist["tarball"];
+      if (typeof tarball !== "string" || tarball.length === 0) fail(`npm metadata for ${label} has no dist.tarball`);
+      if (!/^https?:\/\//.test(tarball)) fail(`npm dist.tarball for ${label} is not an http(s) URL`);
+      const bytes = await fetchBytes(o.fetcher, tarball, timeoutMs);
+      const filename = safeArtifactName(tarball, `${spec.name.replace("@", "").replace("/", "-")}-${spec.version}.tgz`);
+      if (!filename.endsWith(".tgz") && !filename.endsWith(".tar.gz")) fail(`npm tarball ${filename} is not a .tgz/.tar.gz`);
+      return { bytes, filename };
+    }
+    case "pypi": {
+      const meta3 = await fetchJson(o.fetcher, pypiMetadataUrl(spec.name, spec.version), timeoutMs);
+      const urls = isRecord2(meta3) && Array.isArray(meta3["urls"]) ? meta3["urls"] : [];
+      const files = urls.filter(isRecord2);
+      const sdists = files.filter((f) => f["packagetype"] === "sdist");
+      const sdist = sdists.find((f) => typeof f["filename"] === "string" && f["filename"].endsWith(".tar.gz"));
+      if (sdist === void 0) {
+        fail(`no .tar.gz sdist published for ${label} \u2014 wheels are pre-built artifacts and out of scan scope (setup code lives in the sdist)`);
+      }
+      const url2 = sdist["url"];
+      const name = sdist["filename"];
+      if (typeof url2 !== "string" || typeof name !== "string") fail(`PyPI sdist entry for ${label} is malformed`);
+      const bytes = await fetchBytes(o.fetcher, url2, timeoutMs);
+      return { bytes, filename: safeArtifactName(url2, name) };
+    }
+    case "crates": {
+      const url2 = cratesDownloadUrl(spec.name, spec.version);
+      const bytes = await fetchBytes(o.fetcher, url2, timeoutMs, { "user-agent": SCAN_USER_AGENT });
+      return { bytes, filename: `${spec.name}-${spec.version}.crate` };
+    }
+    case "rubygems": {
+      const url2 = rubygemsDownloadUrl(spec.name, spec.version);
+      const bytes = await fetchBytes(o.fetcher, url2, timeoutMs, { "user-agent": SCAN_USER_AGENT });
+      return { bytes, filename: `${spec.name}-${spec.version}.gem` };
+    }
+    default: {
+      const eco = spec.ecosystem;
+      throw new UnknownArgError(`unknown ecosystem '${String(eco)}' \u2014 border scan cannot fetch it`);
+    }
+  }
+}
+function sha256Hex(data) {
+  return createHash15("sha256").update(data).digest("hex");
+}
+
+// src/scan/materialize.ts
+import { existsSync as existsSync17, mkdirSync as mkdirSync11, readdirSync as readdirSync10, readFileSync as readFileSync16, rmSync as rmSync12, writeFileSync as writeFileSync7 } from "node:fs";
+import { join as join25 } from "node:path";
+var CRATES_ENVELOPE_FILES = ["Cargo.toml.orig", ".cargo-ok", ".cargo_vcs_info.json"];
+var fail2 = (why) => {
+  throw new Error(`border scan cannot materialize the artifact (${why}) \u2014 refusing to stage an unusable tree (fail-closed)`);
+};
+var oneLine = (err) => (err instanceof Error ? err.message : String(err)).replace(/\s+/g, " ").trim();
+function extractFlat(archive, destDir) {
+  try {
+    extractArchive(archive, destDir);
+  } catch (err) {
+    fail2(`extraction of ${archive} failed: ${oneLine(err)}`);
+  }
+}
+function unwrapSingleDir(dir) {
+  const entries = readdirSync10(dir, { withFileTypes: true });
+  const dirs = entries.filter((e) => e.isDirectory());
+  if (entries.length === 1 && dirs.length === 1 && dirs[0] !== void 0) {
+    return join25(dir, dirs[0].name);
+  }
+  return dir;
+}
+function requireManifest(repoDir, ecosystem, candidates) {
+  if (!candidates.some((rel) => existsSync17(join25(repoDir, rel)))) {
+    fail2(`${ecosystem} package tree has none of [${candidates.join(", ")}] at its root`);
+  }
+}
+function materializePackage(o) {
+  const note = o.note ?? ((line) => {
+    process.stderr.write(`${line}
+`);
+  });
+  const safe = safeArtifactName(o.filename, `${o.ecosystem}-artifact`);
+  const archive = join25(o.baseDir, safe);
+  writeFileSync7(archive, o.bytes);
+  const extractDir = join25(o.baseDir, "extract");
+  mkdirSync11(extractDir, { recursive: true });
+  extractFlat(archive, extractDir);
+  let repoDir = unwrapSingleDir(extractDir);
+  if (o.ecosystem === "rubygems") {
+    const outer = repoDir;
+    const dataCandidates = findNativeMissArchives(outer).filter((f) => f.endsWith("data.tar.gz"));
+    const inner = dataCandidates[0] ?? join25(outer, "data.tar.gz");
+    if (!existsSync17(inner)) fail2(".gem archive contains no data.tar.gz");
+    const gemTree = join25(o.baseDir, "gem-tree");
+    mkdirSync11(gemTree, { recursive: true });
+    extractFlat(inner, gemTree);
+    repoDir = unwrapSingleDir(gemTree);
+  } else if (o.ecosystem === "npm") {
+    requireManifest(repoDir, o.ecosystem, ["package.json"]);
+  } else if (o.ecosystem === "pypi") {
+    requireManifest(repoDir, o.ecosystem, ["pyproject.toml", "setup.py"]);
+  } else {
+    requireManifest(repoDir, o.ecosystem, ["Cargo.toml"]);
+    for (const file2 of CRATES_ENVELOPE_FILES) {
+      const path4 = join25(repoDir, file2);
+      if (!existsSync17(path4)) continue;
+      const original = readFileSync16(path4);
+      rmSync12(path4, { force: true });
+      note(`border scan: crates envelope normalized: ${file2} sha256=${sha256Hex(original)}`);
+    }
+  }
+  const env2 = o.env;
+  const git = (args) => runGitChecked(repoDir, args, ...env2 !== void 0 ? [{ env: env2 }] : [{}]);
+  git(["init", "-q"]);
+  git(["add", "-A"]);
+  git(["-c", "user.email=border@local", "-c", "user.name=border", "commit", "-qm", "border scan"]);
+  return repoDir;
+}
+
+// src/scan/spec.ts
+var ECOSYSTEMS = ["npm", "pypi", "crates", "rubygems"];
+var SCAN_SPEC_USAGE = "usage: border scan <[ecosystem:]name@version> \u2014 e.g. border scan puppeteer@23.11.1 | pypi:requests@2.32.3 | crates:serde@1.0.219 | rubygems:rails@7.1.1";
+var PLAIN_NAME = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+var SCOPED_NAME = /^@[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+var VERSION = /^[A-Za-z0-9][A-Za-z0-9._+-]*$/;
+var bad2 = (why) => {
+  throw new UnknownArgError(`${why}; ${SCAN_SPEC_USAGE}`);
+};
+function parseScanSpec(raw) {
+  const text = raw.trim();
+  if (text.length === 0) return bad2("empty spec");
+  let ecosystem = "npm";
+  let rest = text;
+  const colon = text.indexOf(":");
+  if (colon >= 0) {
+    const prefix = text.slice(0, colon);
+    const found = ECOSYSTEMS.find((e) => e === prefix);
+    if (found === void 0) {
+      return bad2(`unknown ecosystem '${prefix}' \u2014 expected one of: ${ECOSYSTEMS.join(", ")}`);
+    }
+    ecosystem = found;
+    rest = text.slice(colon + 1);
+    if (rest.length === 0) return bad2("missing package name after the ecosystem prefix");
+  }
+  const scoped = rest.startsWith("@");
+  const at = rest.lastIndexOf("@");
+  if (at <= 0) return bad2(`spec '${raw}' is missing '@version'`);
+  const name = rest.slice(0, at);
+  const version2 = rest.slice(at + 1);
+  if (!(scoped ? SCOPED_NAME : PLAIN_NAME).test(name)) {
+    return bad2(`invalid package name '${name}'`);
+  }
+  if (!VERSION.test(version2)) {
+    return bad2(`invalid version '${version2}' in spec '${raw}'`);
+  }
+  return { ecosystem, name, version: version2 };
+}
+
+// src/scan/scan.ts
+async function runScanCore(ctx, deps = {}) {
+  const raw = ctx.positionals[0];
+  if (ctx.positionals.length !== 1 || raw === void 0) {
+    throw new UnknownArgError(
+      `border scan expects exactly one <spec> argument (got ${String(ctx.positionals.length)}); ${SCAN_SPEC_USAGE}`
+    );
+  }
+  const spec = parseScanSpec(raw);
+  const channel = publishChannels().find((c) => c.id === spec.ecosystem);
+  if (channel === void 0) {
+    throw new EngineRunError(`border scan: no channel registered for ecosystem '${spec.ecosystem}'`, null);
+  }
+  const cfg = synthesizeScanConfig(spec.ecosystem);
+  const fetcher = deps.fetcher ?? defaultScanFetcher;
+  const baseDir = mkdtempSync5(join26(tmpdir3(), "border-scan-"));
+  try {
+    const { bytes, filename } = await fetchArtifact(spec, { fetcher });
+    const env2 = { ...ctx.env };
+    const repoDir = materializePackage({ ecosystem: spec.ecosystem, bytes, filename, baseDir, env: env2 });
+    const stage = await channel.stage({ repoDir, cfg, env: env2, sanitizer: new TextSanitizer() });
+    const head = runGitChecked(repoDir, ["rev-parse", "HEAD"], { env: env2 }).trim();
+    const findings = stage.findings;
+    const verdict = computeVerdict(findings);
+    const report = {
+      schemaVersion: 1,
+      key: sha256Hex(`scan:${spec.ecosystem}:${spec.name}@${spec.version}:${head}`),
+      head,
+      dirty: false,
+      exposureSet: [`${spec.ecosystem}:${spec.name}@${spec.version}`],
+      refSet: [],
+      rulesHash: sha256Hex(buildScanConfigYaml(spec.ecosystem)),
+      verdict,
+      counts: countFindings(findings),
+      findings,
+      ts: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    const label = `${spec.ecosystem}:${spec.name}@${spec.version}`;
+    const sanitizer = new TextSanitizer();
+    const line = (text) => sanitizer.sanitize(text).replace(/\s+/g, " ").trim();
+    if (ctx.flags.json) {
+      ctx.stdout(renderReportJson(report));
+    } else {
+      ctx.stdout(line(`border scan ${label} ${report.verdict}: ${String(report.counts.total)} finding(s), ${String(report.counts.blocking)} blocking`));
+      for (const f of report.findings) {
+        ctx.stdout(line(`  ${f.severity} ${f.rule} [${f.engine}] ${f.path ?? f.commit ?? f.target} ${f.message}`));
+      }
+    }
+    return exitCodeFromVerdict(verdict);
+  } finally {
+    removeSandbox(baseDir);
+  }
+}
+
+// src/commands/scan.ts
+var runScan2 = (ctx) => runScanCore(ctx);
+
 // src/commands/status.ts
 function oneInertLine(value) {
   return value.replace(/[\x00-\x1f\x7f]+/g, " ").trim();
@@ -43508,11 +43847,12 @@ var handlers = {
   push: runPush,
   status: runStatus,
   "llm-request": runLlmRequest,
-  "llm-ingest": runLlmIngest
+  "llm-ingest": runLlmIngest,
+  scan: runScan2
 };
 
 // src/cli/types.ts
-var SUBCOMMANDS = ["check", "push", "status", "llm-request", "llm-ingest"];
+var SUBCOMMANDS = ["check", "push", "status", "llm-request", "llm-ingest", "scan"];
 
 // src/cli.ts
 var VALID_TARGETS = targetIds();
@@ -43528,6 +43868,7 @@ function usage() {
     "  status         show gate state, config, and engine versions",
     "  llm-request    emit the provenance request for LLM-authored commits",
     "  llm-ingest     record provenance captured by the harness",
+    "  scan           inspect a third-party package ([ecosystem:]name@version) for residue",
     "",
     "flags:",
     "  --config <path>             config file (default: ./border.yaml, then git-remote fallback)",
@@ -43541,7 +43882,7 @@ function usage() {
     "",
     "exit codes: 0 pass (MEDIUM/INFO/LOW allowed) | 1 gate-blocked (CRITICAL/HIGH) or partial push | 2 config/tool error",
     "",
-    "subcommands: check, push, status, llm-request, llm-ingest"
+    "subcommands: check, push, status, llm-request, llm-ingest, scan"
   ].join("\n");
 }
 function isSubcommand(value) {
@@ -43650,11 +43991,18 @@ function run(argv, stdout = (line) => {
 }
 
 // src/index.ts
-function isMainModule() {
-  const entry = process.argv[1];
-  return entry !== void 0 && import.meta.url === pathToFileURL(entry).href;
+function isMainModule({ argv1, moduleUrl, realpath }) {
+  if (argv1 === void 0) return false;
+  const canonical = (p) => {
+    try {
+      return realpath(p);
+    } catch {
+      return p;
+    }
+  };
+  return pathToFileURL(canonical(argv1)).href === pathToFileURL(canonical(fileURLToPath5(moduleUrl))).href;
 }
-if (isMainModule()) {
+if (isMainModule({ argv1: process.argv[1], moduleUrl: import.meta.url, realpath: realpathSync.native })) {
   const outcome = run(process.argv.slice(2));
   process.exitCode = outcome instanceof Promise ? await outcome : outcome;
 }
@@ -43663,6 +44011,7 @@ export {
   EXIT_ERROR,
   EXIT_PASS,
   SUBCOMMANDS,
+  isMainModule,
   run,
   translateError,
   usage

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "border-customs",
-  "version": "0.3.0",
+  "version": "0.3.2",
+  "//": "publint is a runtime dep (exact pin): the npm-stage engine is invoked via bin resolution against the installed layout, so consumers get the publint-fail leg out of the box; the dev suite resolves the same node_modules/.bin/publint — no devDependencies entry is needed for it to stay green.",
   "description": "Fail-closed git push gate: secret scanning + supply-chain checks before any remote leaves the machine",
   "type": "module",
   "bin": {
@@ -30,13 +31,13 @@
     "@secretlint/secretlint-rule-no-homedir": "13.0.5",
     "@secretlint/secretlint-rule-pattern": "13.0.5",
     "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
+    "publint": "0.3.24",
     "yaml": "2.9.0",
     "zod": "4.5.4"
   },
   "devDependencies": {
     "@types/node": "22.19.0",
     "esbuild": "0.25.12",
-    "publint": "0.3.24",
     "secretlint": "13.0.5",
     "typescript": "5.9.3",
     "verdaccio": "6.10.2"