border-customs 0.1.0 → 0.3.0

package/dist/assets/residue-src/npm.ts

@@ -0,0 +1,294 @@
+// provenance: original clean-room implementation per .omo/plans/border-push-gate.md todo 11
+//
+// npm pack-once artifact pipeline (plan G38/G39/G33/G23). ONE `npm pack` into
+// <repo>/.border/dist/ is the single source of bytes for the whole gate chain:
+// the recorded {file, sha256, bytes} is what todo 17 re-hashes before publish
+// and todo 14 pins in the ledger — nothing downstream rebuilds. The tarball is
+// extracted to a throwaway sandbox under .border/tmp/, content-scanned (gitleaks
+// dir + secretlint paths), manifest-diffed against the `files` whitelist, then
+// the sandbox is removed on success AND failure. publint runs against the
+// tarball itself, never the working tree.
+//
+// PATH CONTRACT (the false-green trap, round-3 M-A): packs live under
+// `.border/`, which filterBorderStateFindings hard-excludes at the user-repo
+// root — so EVERY finding path emitted here is scoped to the artifact root
+// (`package/<rel>`), never containing a `.border` segment. test/artifacts.npm.test.ts
+// pins this end-to-end with a secret planted inside a packed file.
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { join, relative } from "node:path";
+
+import type { BorderConfig } from "../config.ts";
+import type { Finding, Severity } from "../findings.ts";
+import { redact, type TextSanitizer } from "../redact.ts";
+import { BORDER_STATE_DIR, ensureStateDir } from "../check/lock.ts";
+import { extractArchive, removeSandbox } from "./extract.ts";
+import { scanTree } from "../engines/gitleaks.ts";
+import { scanPaths, type SecretlintMode } from "../engines/secretlint.ts";
+import { EngineRunError, type EngineOptions } from "../engines/support.ts";
+import { LIFECYCLE_SCRIPT_KEYS, parseNpmManifest, unexpectedEntries } from "./manifestDiff.ts";
+import { residueFindings, scanNpmLifecycleHook, sweepResidueNpmArtifact } from "./residue.ts";
+import { RESIDUE_T1_RULE } from "../rules/residueMatchers.ts";
+import {
+  NPM_LIFECYCLE_RULE,
+  NPM_PUBLINT_RULE,
+  NPM_PRIVATE_RULE,
+  NPM_TARGET_LABEL,
+  NPM_UNEXPECTED_RULE,
+  packOnce,
+  publintFinding,
+  sanitizeOut,
+  tail,
+} from "./npmPack.ts";
+
+export { NPM_LIFECYCLE_RULE, NPM_PUBLINT_RULE, NPM_PRIVATE_RULE, NPM_TARGET_LABEL, NPM_UNEXPECTED_RULE };
+
+export type NpmArtifactRecord = {
+  /** repo-relative path of the single packed tarball (`.border/dist/<file>`). */
+  readonly file: string;
+  readonly sha256: string;
+  readonly bytes: number;
+};
+
+export type NpmStageOptions = {
+  readonly repoDir: string;
+  readonly cfg: BorderConfig;
+  readonly env?: EngineOptions["env"];
+  readonly sanitizer?: TextSanitizer;
+  readonly skipGitleaks?: boolean;
+  readonly skipSecretlint?: boolean;
+  readonly secretlintMode?: SecretlintMode;
+  readonly npmBinPath?: string;
+  readonly publintBinPath?: string;
+  /** shared engine/extract timeout; npm/publint have their own knobs. */
+  readonly timeoutMs?: number;
+  readonly npmTimeoutMs?: number;
+  readonly publintTimeoutMs?: number;
+};
+
+export type NpmStageResult = {
+  readonly findings: readonly Finding[];
+  readonly artifact: NpmArtifactRecord | null;
+};
+
+function nativeFinding(
+  rule: string,
+  severity: Severity,
+  message: string,
+  path: string,
+  identity: string,
+  sanitizer: TextSanitizer | undefined,
+): Finding {
+  const digest = redact(identity);
+  return {
+    rule,
+    severity,
+    target: NPM_TARGET_LABEL,
+    path,
+    engine: "native",
+    message: sanitizeOut(sanitizer, message),
+    valueDigest: digest.valueDigest,
+    snippet: digest.snippet,
+  };
+}
+
+/**
+ * GAP B (todo 11 wired into `border check`): re-attribute stage findings from
+ * artifact-root-relative (`package/<rel>`, publint's `package.json`) to the
+ * exact packed bytes: `<tarball>!<rel>`. The tarball basename never contains a
+ * `!` and carries no `.border` segment, so it survives the repo-scoped filter.
+ */
+export function attributeToTarball(findings: readonly Finding[], artifact: NpmArtifactRecord | null): readonly Finding[] {
+  if (artifact === null) return findings;
+  const name = artifact.file.slice(artifact.file.lastIndexOf("/") + 1);
+  return findings.map((f) => {
+    const p = f.path ?? "";
+    const rel = p === "package.json" ? p : p.startsWith("package/") ? p.slice("package/".length) : null;
+    return rel === null || rel === "" ? f : { ...f, path: `${name}!${rel}` };
+  });
+}
+
+/** Re-scope engine findings (absolute / `<abs>!<inner>` shapes) to artifact-root-relative. */
+function scopeFindingPath(f: Finding, extractDir: string): Finding {
+  if (f.path === undefined) return f;
+  const bang = f.path.indexOf("!");
+  if (bang > 0) {
+    const rel = relative(extractDir, f.path.slice(0, bang));
+    if (!rel.startsWith("..")) return { ...f, path: rel === "" ? f.path.slice(bang + 1) : `${rel}${f.path.slice(bang)}` };
+  }
+  const rel = relative(extractDir, f.path);
+  return rel === "" || rel.startsWith("..") ? f : { ...f, path: rel };
+}
+
+function listFiles(dir: string): string[] {
+  const out: string[] = [];
+  const stack = [dir];
+  while (stack.length > 0) {
+    const cur = stack.pop() as string;
+    for (const ent of readdirSync(cur, { withFileTypes: true })) {
+      const p = join(cur, ent.name);
+      if (ent.isDirectory()) stack.push(p);
+      else if (ent.isFile()) out.push(p);
+    }
+  }
+  return out;
+}
+
+/**
+ * Run the npm artifact stage. Throws EngineMissingError/EngineRunError (exit 2
+ * via translateError) for anything that must NOT read as "clean": npm absent,
+ * pack failure, unparseable manifests, digest mismatch, unusable publint.
+ */
+export async function runNpmArtifactStage(o: NpmStageOptions): Promise<NpmStageResult> {
+  if (o.cfg.targets.npm === undefined) {
+    throw new EngineRunError("runNpmArtifactStage invoked without targets.npm configured — pipeline bug", null);
+  }
+  const { repoDir } = o;
+  const manifestPath = join(repoDir, "package.json");
+  if (!existsSync(manifestPath)) {
+    throw new EngineRunError("targets.npm is configured but the repo has no package.json to pack", null);
+  }
+  const manifest = parseNpmManifest(readFileSync(manifestPath, "utf8"));
+  const identity = `${manifest.name ?? "?"}@${manifest.version ?? "?"}`;
+
+  if (manifest.isPrivate) {
+    return {
+      findings: [nativeFinding(
+        NPM_PRIVATE_RULE,
+        "CRITICAL",
+        `package.json is private:true but border.yaml configures targets.npm — nothing can ever publish from this repo; drop the private flag or the npm target`,
+        "package.json",
+        `${identity}:private`,
+        o.sanitizer,
+      )],
+      artifact: null,
+    };
+  }
+
+  ensureStateDir(repoDir);
+  const stateDir = join(repoDir, BORDER_STATE_DIR);
+  const distDir = join(stateDir, "dist");
+  mkdirSync(distDir, { recursive: true });
+  const { filename, sha256, bytes, tarballAbs } = packOnce({
+    repoDir,
+    distDir,
+    ...(o.env !== undefined ? { env: o.env } : {}),
+    ...(o.npmBinPath !== undefined ? { npmBinPath: o.npmBinPath } : {}),
+    ...(o.npmTimeoutMs !== undefined ? { npmTimeoutMs: o.npmTimeoutMs } : {}),
+  });
+
+  const findings: Finding[] = [];
+  const extractDir = join(stateDir, "tmp", sha256.slice(0, 8));
+  rmSync(extractDir, { recursive: true, force: true }); // stale sandbox from an interrupted run
+  mkdirSync(extractDir, { recursive: true });
+  try {
+    extractArchive(tarballAbs, extractDir, {
+      ...(o.env !== undefined ? { env: o.env } : {}),
+      ...(o.timeoutMs !== undefined ? { timeoutMs: o.timeoutMs } : {}),
+    });
+    const relPaths = listFiles(extractDir).map((p) => relative(extractDir, p));
+    if (relPaths.length === 0) throw new EngineRunError("extracted artifact is empty — unusable npm pack output", null);
+    const root = relPaths[0]?.split("/")[0] ?? "package";
+    if (!relPaths.every((p) => p.startsWith(`${root}/`))) {
+      throw new EngineRunError("extracted artifact mixes multiple top-level roots — unexpected tar layout, failing closed", null);
+    }
+    const packedManifestRel = `${root}/package.json`;
+    if (!relPaths.includes(packedManifestRel)) throw new EngineRunError("extracted artifact has no package/package.json", null);
+    // lifecycle gate reads the PUBLISHED manifest (the bytes consumers install),
+    // not the working tree — npm may rewrite package.json inside the tarball.
+    const packedManifest = parseNpmManifest(readFileSync(join(extractDir, packedManifestRel), "utf8"));
+
+    // RESIDUE-CONTRACT §1.6/§3 (R2): a hook is downgraded to MEDIUM ONLY when the
+    // classifier matches closed signature #1 in full; every other outcome — unknown
+    // grammar, unreadable target, out-of-signature literal — keeps the 0.2.0
+    // lifecycle-script CRITICAL row byte-identically (gate-2 pins). Family rows
+    // (T2/T3/cross-manager) are emitted IN ADDITION; the gate only ever gets stricter.
+    const pkgDir = join(extractDir, root);
+    const residueCtx = { root, identity, ...(o.sanitizer !== undefined ? { sanitizer: o.sanitizer } : {}) };
+    for (const key of LIFECYCLE_SCRIPT_KEYS) {
+      const cmd = packedManifest.scripts[key];
+      if (cmd === undefined) continue;
+      const scan = scanNpmLifecycleHook({ pkgDir, hook: cmd });
+      if (scan.signatureId !== null) {
+        findings.push(nativeFinding(
+          RESIDUE_T1_RULE,
+          "MEDIUM",
+          `package.json script '${key}' matches closed safe signature '${scan.signatureId}' (T1: install-root writes only, frozen probe/fallback argv literals, zero network/out-of-tree/persistence/cross-manager hits) — allowed but audit-visible; any deviation keeps the blocking lifecycle-script CRITICAL`,
+          packedManifestRel,
+          `${identity}:residue:t1:${key}`,
+          o.sanitizer,
+        ));
+      } else {
+        findings.push(nativeFinding(
+          NPM_LIFECYCLE_RULE,
+          "CRITICAL",
+          `package.json script '${key}' is a lifecycle hook — npm executes it on every consumer install (G33): ${tail(sanitizeOut(o.sanitizer, cmd))}`,
+          packedManifestRel,
+          `${identity}:lifecycle:${key}`,
+          o.sanitizer,
+        ));
+      }
+      findings.push(...residueFindings(scan.hits, residueCtx));
+    }
+    const entries = relPaths.filter((p) => p !== packedManifestRel).map((p) => p.slice(root.length + 1));
+    for (const entry of unexpectedEntries(entries, manifest.files)) {
+      findings.push(nativeFinding(
+        NPM_UNEXPECTED_RULE,
+        "HIGH",
+        `packed entry '${entry}' matches no package.json files whitelist pattern and is not an always-packed name — force-packed via main/bin or default inclusion (G39); publish only intentional bytes`,
+        `${root}/${entry}`,
+        `${identity}:unexpected:${entry}`,
+        o.sanitizer,
+      ));
+    }
+
+    // T4 + B2 marker pair-detection are artifact-wide (contract §4/§5.3): a persistence string
+    // in ANY packed file blocks, even with no lifecycle hook present. NpmManifest does
+    // not parse `bin`, so the CLI-inverse surface is scanned over the packed bin/ tree.
+    const binRels = relPaths.filter((p) => p.startsWith(`${root}/bin/`));
+    findings.push(...residueFindings(sweepResidueNpmArtifact({ pkgDir, files: relPaths, binRels }), residueCtx));
+
+    if (o.skipGitleaks !== true) {
+      const tree = scanTree({
+        dir: extractDir,
+        stateDir,
+        target: NPM_TARGET_LABEL,
+        ...(o.env !== undefined ? { env: o.env } : {}),
+        ...(o.sanitizer !== undefined ? { sanitizer: o.sanitizer } : {}),
+        ...(o.timeoutMs !== undefined ? { timeoutMs: o.timeoutMs } : {}),
+      });
+      for (const f of tree) findings.push(scopeFindingPath(f, extractDir));
+    }
+    if (o.skipSecretlint !== true) {
+      const linted = await scanPaths({
+        dir: extractDir,
+        files: relPaths,
+        target: NPM_TARGET_LABEL,
+        rules: o.cfg.rules,
+        ...(o.secretlintMode !== undefined ? { mode: o.secretlintMode } : {}),
+        ...(o.env !== undefined ? { env: o.env } : {}),
+        ...(o.sanitizer !== undefined ? { sanitizer: o.sanitizer } : {}),
+        ...(o.timeoutMs !== undefined ? { timeoutMs: o.timeoutMs } : {}),
+      });
+      findings.push(...linted);
+    }
+  } finally {
+    removeSandbox(extractDir);
+  }
+
+  const publint = publintFinding(
+    {
+      ...(o.env !== undefined ? { env: o.env } : {}),
+      ...(o.publintBinPath !== undefined ? { publintBinPath: o.publintBinPath } : {}),
+      ...(o.publintTimeoutMs !== undefined ? { publintTimeoutMs: o.publintTimeoutMs } : {}),
+      ...(o.sanitizer !== undefined ? { sanitizer: o.sanitizer } : {}),
+    },
+    tarballAbs,
+    identity,
+  );
+  if (publint !== null) findings.push(publint);
+
+  return {
+    findings,
+    artifact: { file: `${BORDER_STATE_DIR}/dist/${filename}`, sha256, bytes },
+  };
+}

package/dist/assets/residue-src/pypi.ts

@@ -0,0 +1,333 @@
+// provenance: original clean-room implementation per .omo/plans/border-push-gate.md todo 12
+//
+// PyPI artifact pipeline: build-once (G38) → extract → scan → twine gate.
+//   build   = `python3 -m build --no-isolation --outdir <repo>/.border/dist/`.
+//     Prerequisites `python3 -m build --version` / `python3 -m twine --version`
+//     are probed FIRST; a missing one is PypiPrerequisiteError (border exit 2,
+//     naming the module) — never a silent skip. `--no-isolation` is deliberate:
+//     plan todo-12 Must-NOT forbids venv creation, and the image provisioned
+//     build 1.6.0/twine 7.0.0/setuptools for python3.14 (todo 1). The build
+//     backend comes from the target pyproject.toml itself — no poetry/flit
+//     special-casing. dist/ is wiped before every build, so leftovers from an
+//     earlier run (or an attacker's pre-seeded .tar.gz) are never scanned.
+//   extract = wheel via `python3 -m zipfile -e`, sdist via extractArchive
+//     (.tar.gz → `tar -xzf`), each into a mkdtemp sandbox under .border/tmp/,
+//     removed in a finally-block (round-2 m3).
+//   scan    = gitleaks scanTree + secretlint scanPaths per extracted tree, with
+//     finding paths RE-ANCHORED to artifact-inner relpaths (sdist wrapper
+//     stripped). This is load-bearing: filterBorderStateFindings(findings,
+//     repoDir) (src/check/exclusions.ts) silently drops any finding whose
+//     repo-relative path carries a `.border` segment — if we reported sandbox
+//     paths the whole artifact gate would false-green. Duplicate (rule, relpath,
+//     digest) triples across the sdist/wheel trees collapse to one finding.
+//   manifest = sdist entries vs `git ls-files`; entries explained by MANIFEST.in
+//     globs, pyproject readme/package-data/data-files strings, or build-
+//     generated metadata (PKG-INFO, setup.cfg stub, *.egg-info/*, ...) pass;
+//     anything else ⇒ HIGH `sdist-unexpected-file` — the G17/G18/G42 class:
+//     setuptools walks the WORKING TREE, so .gitignore never hides a planted
+//     file from the shipped artifact.
+//   twine   = `python3 -m twine check --strict` over every dist file; a FAILED
+//     artifact ⇒ HIGH `twine-check` finding (fail = verdict, not crash); an
+//     unparseable non-zero exit is a tool crash ⇒ EngineRunError (exit 2).
+// G23: every value flows through the engine adapters' redact() ingest; free
+// text we author (twine blocks) is sanitized. sha256 of each produced
+// .tar.gz/.whl is returned for the orchestrator's ctx.artifacts.pypi list
+// (todo 17 wires ctx; buildPypiArtifacts is exported so the gate builds once).
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmdirSync, rmSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+
+import { extractArchive, removeSandbox } from "./extract.ts";
+import { residueFindings } from "./residue.ts";
+import { residuePypiHits } from "./residuePy.ts";
+import type { Finding } from "../findings.ts";
+import { globToRegExp } from "../rules/artifactMatchers.ts";
+import { scanTree } from "../engines/gitleaks.ts";
+import { scanPaths, type SecretlintRulesInput } from "../engines/secretlint.ts";
+import {
+  binaryCandidates,
+  EngineMissingError,
+  EngineRunError,
+  spawnEngine,
+  type EngineOptions,
+} from "../engines/support.ts";
+import { redact, type TextSanitizer } from "../redact.ts";
+
+/** Prerequisite failure — the CLI maps it to border exit 2 (library never process.exits). */
+export class PypiPrerequisiteError extends Error {
+  override readonly name = "PypiPrerequisiteError";
+  readonly exitCode = 2 as const;
+}
+
+export type PypiArtifact = { readonly path: string; readonly kind: "sdist" | "wheel"; readonly sha256: string };
+export type PypiInput = EngineOptions & {
+  readonly repoDir: string;
+  readonly stateDir?: string;
+  readonly sanitizer?: TextSanitizer;
+  readonly rules?: SecretlintRulesInput;
+  readonly target?: string;
+  /** degraded-engine inheritance (todo 10 policy): the check pipeline skips the leg whose engine failed its probe. */
+  readonly skipGitleaks?: boolean;
+  readonly skipSecretlint?: boolean;
+};
+export type PypiScanResult = { readonly artifacts: readonly PypiArtifact[]; readonly findings: readonly Finding[] };
+
+const ANSI_RE = /\u001B\[[0-9;]*m/g;
+/** Names setuptools emits into the sdist that no source declaration lists (whitelisted metadata). */
+const GENERATED_NAMES = new Set(["PKG-INFO", "SOURCES.txt", "setup.py", "setup.cfg", "pyproject.toml", "MANIFEST.in",
+  "RECORD", "WHEEL", "METADATA", "top_level.txt", "dependency_links.txt", "requires.txt", "not-zip-safe"]);
+
+function tail(text: string, max = 300): string {
+  return text.replace(ANSI_RE, "").replace(/\s+/g, " ").trim().slice(-max);
+}
+
+function requireModule(o: EngineOptions, module: "build" | "twine"): void {
+  let out: ReturnType<typeof spawnEngine>;
+  try {
+    out = spawnEngine(binaryCandidates("python3", o), ["-m", module, "--version"], o);
+  } catch (err) {
+    if (err instanceof EngineMissingError) {
+      throw new PypiPrerequisiteError(
+        `\`python3 -m ${module}\` is unavailable: python3 was not found on PATH (border exit 2 — install python3 plus the '${module}' package)`,
+      );
+    }
+    throw err;
+  }
+  if (out.status !== 0) {
+    throw new PypiPrerequisiteError(
+      `\`python3 -m ${module} --version\` exited ${String(out.status)} — the '${module}' module is missing or broken (border exit 2). stderr: ${tail(out.stderr)}`,
+    );
+  }
+}
+
+/** build-once (G38): wipe stale dist, run `python3 -m build`, content-address every produced artifact. */
+export function buildPypiArtifacts(o: PypiInput): { readonly artifacts: readonly PypiArtifact[]; readonly distDir: string } {
+  requireModule(o, "build");
+  const repoDir = resolve(o.repoDir);
+  if (!existsSync(join(repoDir, "pyproject.toml"))) {
+    throw new PypiPrerequisiteError(`no pyproject.toml in the repo root — the PyPI pipeline builds from pyproject's own [build-system]`);
+  }
+  const distDir = join(resolve(o.stateDir ?? join(repoDir, ".border")), "dist");
+  mkdirSync(distDir, { recursive: true });
+  // Wipe ONLY the pypi kinds (.tar.gz/.whl): an earlier run's — or an
+  // attacker's pre-seeded — pypi artifact must never be scanned (build-once
+  // hygiene), but OTHER channels' staged artifacts (.tgz/.crate/.gem) must
+  // survive a multi-target check. Exposed by the C5 cross-channel matrix:
+  // a full rmSync made every git+npm+pypi repo's npm push leg fail at the
+  // re-hash gate ("artifact changed since check — .tgz is missing from the
+  // working tree"), because the npm stage packed first and this wipe deleted
+  // the recorded bytes before the record was written.
+  for (const name of readdirSync(distDir)) {
+    if (name.endsWith(".tar.gz") || name.endsWith(".whl")) rmSync(join(distDir, name), { force: true });
+  }
+  const out = spawnEngine(binaryCandidates("python3", o), ["-m", "build", "--no-isolation", "--outdir", distDir, repoDir], o);
+  if (out.status !== 0) {
+    throw new EngineRunError(`\`python3 -m build\` exited ${String(out.status)} — no artifacts to gate (border exit 2). stderr: ${tail(out.stderr)}`, out.status);
+  }
+  const names = readdirSync(distDir).filter((n) => n.endsWith(".tar.gz") || n.endsWith(".whl")).sort();
+  if (names.length === 0) {
+    throw new EngineRunError(`\`python3 -m build\` produced no .tar.gz/.whl in ${distDir} (border exit 2)`, null);
+  }
+  const artifacts = names.map((name): PypiArtifact => {
+    const path = join(distDir, name);
+    return { path, kind: name.endsWith(".whl") ? "wheel" : "sdist", sha256: createHash("sha256").update(readFileSync(path)).digest("hex") };
+  });
+  return { artifacts, distDir };
+}
+
+function walkFilesRel(root: string): string[] {
+  return readdirSync(root, { withFileTypes: true }).flatMap((e) =>
+    e.isDirectory() ? walkFilesRel(join(root, e.name)).map((r) => `${e.name}/${r}`) : e.isFile() ? [e.name] : []);
+}
+
+/** An sdist always wraps everything in `<name>-<version>/`; strip that ONE shared
+ *  top segment so wheel and sdist trees attribute the same inner relpath (and so
+ *  the wrapper's version string never pollutes finding paths). */
+function stripWrapper(entries: readonly string[]): { readonly root: string; readonly rest: readonly string[] } {
+  const tops = new Set(entries.map((e) => (e.includes("/") ? e.slice(0, e.indexOf("/")) : "\u0000")));
+  const only = tops.size === 1 ? [...tops][0] : undefined;
+  return only !== undefined && only !== "\u0000"
+    ? { root: only, rest: entries.map((e) => e.slice(only.length + 1)) }
+    : { root: "", rest: entries };
+}
+
+/** gitleaks dir-leg paths are absolute under the scan root; reattribute `<abs>` or
+ *  `<abs>!<inner>` (native-miss archive reattribution) to scan-root-relative. */
+function toInner(findingPath: string | undefined, scanRoot: string): string {
+  if (findingPath === undefined) return "";
+  const bang = findingPath.indexOf("!");
+  const head = bang === -1 ? findingPath : findingPath.slice(0, bang); const rest = bang === -1 ? "" : findingPath.slice(bang + 1);
+  const rel = relative(scanRoot, head);
+  const inner = rel !== "" && !rel.startsWith("..") ? rel : basename(head);
+  return rest === "" ? inner : `${inner}!${rest}`;
+}
+
+function gitTracked(o: EngineOptions, repoDir: string): Set<string> {
+  const out = spawnEngine(binaryCandidates("git", o), ["-C", repoDir, "ls-files"], {
+    ...o,
+    env: { ...(o.env ?? process.env), GIT_CEILING_DIRECTORIES: dirname(repoDir) },
+  });
+  if (out.status !== 0) throw new EngineRunError(`git ls-files in ${repoDir} exited ${String(out.status)} (border exit 2)`, out.status);
+  return new Set(out.stdout.split("\n").filter((l) => l !== ""));
+}
+
+/** MANIFEST.in + pyproject declarations → include/exclude glob matchers over
+ *  sdist-inner (project-relative) paths. distutils precedence: prune/exclude
+ *  remove whatever the includes pulled in, so exclusions are checked FIRST. */
+type Matchers = { readonly inc: readonly RegExp[]; readonly exc: readonly RegExp[] };
+
+function toRe(globs: readonly string[]): RegExp[] {
+  return globs.filter((g) => g !== "").map((g) => globToRegExp(g.includes("/") ? g : `**/${g}`));
+}
+
+function explainMatchers(repoDir: string): Matchers {
+  const inc: string[] = [];
+  const exc: string[] = [];
+  const manifest = join(repoDir, "MANIFEST.in");
+  if (existsSync(manifest)) {
+    for (const line of readFileSync(manifest, "utf8").split(/\r?\n/)) {
+      const t = line.split("#")[0]?.trim() ?? "";
+      if (t === "") continue;
+      const [cmd, ...args] = t.split(/\s+/);
+      const dir = args[0] ?? "";
+      if (cmd === "include") inc.push(...args);
+      else if (cmd === "recursive-include") for (const g of args.slice(1)) inc.push(`${dir}/**/${g}`, `${dir}/${g}`);
+      else if (cmd === "graft") inc.push(`${dir}/**`);
+      else if (cmd === "exclude") exc.push(...args);
+      else if (cmd === "global-exclude") for (const g of args) exc.push(`**/${g}`);
+      else if (cmd === "prune") exc.push(`${dir}/**`);
+      // ignore-* and unknown directives: distutils defaults; approximation documented here.
+    }
+  }
+  const pyproject = join(repoDir, "pyproject.toml");
+  if (existsSync(pyproject)) {
+    const text = readFileSync(pyproject, "utf8");
+    const readme = /^\s*readme\s*=\s*"([^"]+)"/m.exec(text);
+    if (readme?.[1] !== undefined) inc.push(readme[1]);
+    for (const block of text.matchAll(/readme\s*=\s*\{([^}]*)\}/g)) for (const f of block[1]?.matchAll(/"([^"]+)"/g) ?? []) inc.push(f[1] ?? "");
+    for (const block of text.matchAll(/\[tool\.setuptools\.(?:package-data|data-files)\]([\s\S]*?)(?=\n\[|$)/g))
+      for (const g of block[1]?.matchAll(/"([^"]+)"/g) ?? []) inc.push(g[1] ?? "");
+  }
+  return { inc: toRe(inc), exc: toRe(exc) };
+}
+
+function isGeneratedMetadata(inner: string): boolean {
+  const segs = inner.split("/");
+  return GENERATED_NAMES.has(segs[segs.length - 1] ?? "") || segs.some((s) => s.endsWith(".egg-info") || s.endsWith(".dist-info"));
+}
+
+function manifestFindings(o: PypiInput, sdistInner: readonly string[], target: string): Finding[] {
+  const tracked = gitTracked(o, resolve(o.repoDir));
+  const { inc, exc } = explainMatchers(resolve(o.repoDir));
+  const out: Finding[] = [];
+  for (const entry of sdistInner) {
+    const declared = inc.some((m) => m.test(entry)) && !exc.some((m) => m.test(entry));
+    if (tracked.has(entry) || isGeneratedMetadata(entry) || declared) continue;
+    const { valueDigest, snippet } = redact(entry);
+    out.push({
+      rule: "sdist-unexpected-file",
+      severity: "HIGH",
+      target,
+      path: entry,
+      engine: "pypi-manifest",
+      message: `sdist entry '${entry}' is not git-tracked and not explained by MANIFEST.in / pyproject declarations or build-generated metadata. setuptools builds sdist/wheels from the WORKING TREE (.gitignore-blind, G17/G18/G42): remove the file or commit/declare it intentionally.`,
+      valueDigest,
+      snippet,
+    });
+  }
+  return out;
+}
+
+function twineCheck(o: PypiInput, artifacts: readonly PypiArtifact[], target: string): Finding[] {
+  // COLUMNS/NO_COLOR: twine renders via rich, which hard-wraps long dist paths
+  // mid-token at terminal width — unwrapped single-line verdicts are what the
+  // PASSED/FAILED parser below consumes.
+  const out = spawnEngine(
+    binaryCandidates("python3", o),
+    ["-m", "twine", "check", "--strict", ...artifacts.map((a) => a.path)],
+    { ...o, env: { ...(o.env ?? process.env), COLUMNS: "100000", NO_COLOR: "1" } },
+  );
+  if (out.status === 0) return [];
+  const text = `${out.stdout}\n${out.stderr}`.replace(ANSI_RE, "");
+  const verdicts = [...text.matchAll(/Checking\s+(\S+):\s+(\w+)/g)];
+  const failed = verdicts.filter((m) => m[2] === "FAILED");
+  if (failed.length === 0) {
+    throw new EngineRunError(`\`python3 -m twine check\` exited ${String(out.status)} without a parseable PASSED/FAILED verdict (border exit 2): ${tail(text)}`, out.status);
+  }
+  return failed.map((m): Finding => {
+    const abs = m[1] ?? "";
+    const base = basename(abs);
+    const idx = text.indexOf(m[0]);
+    const next = text.indexOf("Checking ", idx + m[0].length);
+    const block = tail(text.slice(idx, next === -1 ? undefined : next), 400).replaceAll(abs, base);
+    const { valueDigest, snippet } = redact(`${base}\u0000FAILED`);
+    return {
+      rule: "twine-check",
+      severity: "HIGH",
+      target,
+      path: base,
+      engine: "twine",
+      message: o.sanitizer !== undefined ? o.sanitizer.sanitize(`twine check --strict rejected artifact '${base}': ${block}`) : `twine check --strict rejected artifact '${base}': ${block}`,
+      valueDigest,
+      snippet,
+    };
+  });
+}
+
+/** Full todo-12 pipeline: prereqs → build → extract-scan (both artifacts, deduped) → manifest-diff → twine. */
+export async function scanPyPiArtifacts(o: PypiInput): Promise<PypiScanResult> {
+  requireModule(o, "build");
+  requireModule(o, "twine");
+  const repoDir = resolve(o.repoDir);
+  const stateDir = resolve(o.stateDir ?? join(repoDir, ".border"));
+  const target = o.target ?? "artifact";
+  const { artifacts } = buildPypiArtifacts(o);
+  const tmpParent = join(stateDir, "tmp");
+  mkdirSync(tmpParent, { recursive: true });
+
+  const merged = new Map<string, Finding>();
+  const absorb = (f: Finding, path: string): void => {
+    const g: Finding = { ...f, ...(path !== "" ? { path } : {}) };
+    merged.set(`${g.rule}\u0000${g.path ?? ""}\u0000${g.valueDigest}`, g);
+  };
+  try {
+    for (const artifact of artifacts) {
+      const sandbox = mkdtempSync(join(tmpParent, "pypi-"));
+      try {
+        if (artifact.kind === "wheel") {
+          const z = spawnEngine(binaryCandidates("python3", o), ["-m", "zipfile", "-e", artifact.path, sandbox], o);
+          if (z.status !== 0) throw new EngineRunError(`\`python3 -m zipfile -e ${basename(artifact.path)}\` exited ${String(z.status)} (border exit 2): ${tail(z.stderr)}`, z.status);
+        } else {
+          extractArchive(artifact.path, sandbox, o);
+        }
+        const { root, rest } = artifact.kind === "sdist" ? stripWrapper(walkFilesRel(sandbox)) : { root: "", rest: walkFilesRel(sandbox) };
+        const scanRoot = join(sandbox, root);
+        const scanOpts = { ...o, target };
+        if (o.skipGitleaks !== true) {
+          for (const f of scanTree({ ...scanOpts, dir: scanRoot, stateDir })) absorb(f, toInner(f.path, scanRoot));
+        }
+        if (o.skipSecretlint !== true) {
+          for (const f of await scanPaths({ ...scanOpts, ...(o.sanitizer !== undefined ? { sanitizer: o.sanitizer } : {}), ...(o.rules !== undefined ? { rules: o.rules } : {}), dir: scanRoot, files: rest })) absorb(f, f.path ?? "");
+        }
+        // R3a residue leg (plan §57): build hooks + artifact-wide T4, attributed `<archive>!<inner>`.
+        for (const f of residueFindings(residuePypiHits(scanRoot, rest), {
+          root: basename(artifact.path),
+          sep: "!",
+          identity: basename(artifact.path),
+          ...(o.sanitizer !== undefined ? { sanitizer: o.sanitizer } : {}),
+        })) absorb(f, f.path ?? "");
+        if (artifact.kind === "sdist") for (const f of manifestFindings(o, rest, target)) absorb(f, f.path ?? "");
+      } finally {
+        removeSandbox(sandbox);
+      }
+    }
+    for (const f of twineCheck(o, artifacts, target)) absorb(f, f.path ?? "");
+  } finally {
+    try {
+      rmdirSync(tmpParent);
+    } catch {
+      // non-empty ⇒ a concurrent run owns sandboxes here; leave for the .border/tmp GC
+    }
+  }
+  return { artifacts, findings: [...merged.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([, f]) => f) };
+}