border-customs 0.8.1 → 0.8.3

package/README.md

@@ -10,7 +10,7 @@ cd /path/to/your/repo
 border check
 ```
 
-Requires Node >= 22 and the `gitleaks` binary on `PATH` (border vendors the rule config for
+Requires Node >= 22.22.2 (the transitive `ini@7` dependency sets that floor) and the `gitleaks` binary on `PATH` (border vendors the rule config for
 gitleaks 8.30.1; the binary itself is yours to install, same as `git`). secretlint runs
 in-process as a bundled dependency. Each registry leg additionally shells out to its platform's
 own publisher, which must be on `PATH` whenever that target is configured; a missing publisher
@@ -18,14 +18,29 @@ binary is exit 2, never a skipped leg:
 
 | Registry target | Publisher border runs | Version the same-bytes proofs were measured on |
 | --- | --- | --- |
-| `npm` | `npm` | (unchanged since 0.1.0) |
+| `npm` | `npm` | npm >= 11 for packages with pack-phase hooks (see below) |
 | `pypi` | `python3 -m build` / `python3 -m twine` | (unchanged since 0.1.0) |
 | `crates` | `cargo` | cargo 1.93.1 (rustup) |
 | `rubygems` | `gem` | RubyGems 3.6.7 on ruby 3.3.8 |
 
+**npm pack safety probe.** `npm pack --ignore-scripts` is not trustworthy on npm 10: measured
+on npm 10.9.7, the target package's `prepare` script still executes (npm 11.19.1 is clean).
+Before packing, border runs `npm --version`. On npm < 11 it refuses, with a named exit 2, any
+package that declares a `prepack`, `prepare`, or `postpack` script — border never executes the
+code it audits. A package with none of those hooks has nothing for npm to run and stays
+scannable on npm 10. Installing npm >= 11 removes the refusal.
+
 Other toolchain versions of `cargo` and `gem` are untested by those byte-determinism proofs.
 Optional engines are listed in [Configuration](#configuration).
 
+**Pinned consumption.** Install an exact version (`npm install -g border-customs@<version>`;
+`npx border-customs@<version> check` for a one-off) instead of running gate code out of a
+source checkout. Every check and push record carries `engineBuild` — the identity
+(`<version>+<commit>[.dirty]`) of the border build that produced the verdict, the same string
+`border --version` prints. A `.dirty` suffix means the verdict came from uncommitted code, and
+records from one repo carrying different `engineBuild` values mean the audit trail is mixed:
+both are findings an auditor should chase, which is exactly why the identity is on the record face.
+
 ## The problem it solves
 
 The usual secret workflow is leak-then-repent: `git push`, notice the AWS key in the diff
@@ -207,7 +222,7 @@ an installer *does*, per tier — the split behind opencode-ai's in-tree `postin
 The pairing classes behind these rows (multi-channel PASS **C5** subset/ordering discipline;
 **C9** interpolated-and-indirected root spellings; **C10** comment/quote-boundary shapes that
 once silent-passed) are frozen with their evidence in
-[src/artifacts/RESIDUE-CONTRACT.md](src/artifacts/RESIDUE-CONTRACT.md).
+[src/artifacts/RESIDUE-CONTRACT.md](https://github.com/TachikomaGundam/Border-Customs/blob/main/src/artifacts/RESIDUE-CONTRACT.md).
 
 **Fail-closed:** a residue scan whose rule table or classifier sources cannot be read is exit 2,
 never a silent pass — and the classifier source bytes are part of the ledger `rulesHash`, so
@@ -222,10 +237,30 @@ clean residue scan is an absence of matched signatures, never a certificate of b
 The signature table is deliberately closed, and the list of shapes it **cannot see** —
 content-writes, handle-variants, dead spellings, interpolation-then-slash, span-quirk
 over-blocks, IO-instance writers, user-shadowed bare verbs — lives in
-[RESIDUE-CONTRACT.md §8](src/artifacts/RESIDUE-CONTRACT.md); this README points, it does not
+[RESIDUE-CONTRACT.md §8](https://github.com/TachikomaGundam/Border-Customs/blob/main/src/artifacts/RESIDUE-CONTRACT.md); this README points, it does not
 restate. The empirical roundtrip (install → snapshot → uninstall → rc-delta-zero) is the 0.4.0
-valve. **border is NOT a malware sandbox**: it never executes, intercepts, or sandboxes the
-code it reads; it matches text and blocks the push.
+valve. **border does not execute the code it audits.** Every scan leg (gitleaks, secretlint,
+the native rules, the exfil lens) is pure byte inspection; the cross-channel marker fixture
+(`test/build.execMarkers.test.ts`) pins that a consentless `border check` spawns ZERO build
+toolchains. Registry artifact builds (npm pack, `python -m build`, `gem build`, `cargo
+ package`) DO execute repo-supplied build code, so they run only on operator consent:
+`--allow-builds`, or `allowBuilds: true` in the machine store / an explicit `--config` file
+outside the repo (the environment is deliberately NOT a consent source — a hostile `.envrc`
+owns it). Both sources live OUTSIDE the audited tree, and a repo's own border.yaml can declare
+targets but can never enable building them. Without
+consent the run is scan-only: no artifact digests are recorded (visible as MEDIUM
+`build-stage-withheld` findings), and a scan-only PASS can never back a registry publish.
+Consented builds can additionally run inside a **pinned container** (`targets.<ch>.sandboxImage`,
+see Configuration): the container is launched with the network disabled — the `--network none`
+argv the daemon applies is the enforcement anchor, and an in-container probe re-checks DNS and
+TCP from inside as a tripwire — the repo mounted read-only and built from a tmpfs copy, host
+credentials never entering the container, and every ledger record bound to the exact image
+digest that certified its bytes. `sandboxImage` itself is a security-tier key: honored only
+from the machine store or a `--config` file outside the repo whose ownership and modes pass
+the fd-chain qualification, and any competing declaration (repo config, lax-mode file, hijacked
+`XDG_CONFIG_HOME`) is a hard refusal, never a silent fallback. Border is
+containment-by-consent plus optional container containment — it is not a malware sandbox and
+not a VM: a kernel-level escape from the container remains in the threat model.
 
 #### Proof valve: `residue.requireProof` (0.4.0)
 
@@ -267,7 +302,7 @@ lives inside. The exfil lens adds five rules over the surfaces about to become p
 | `exfil-machine-binding` | vendor inference-model ids pinned on portable surfaces next to model/default/provider context (L-MACHINE-LOCAL; born 2026-10-02) |
 
 The severity a reader **observes** is the (rule × facet × channel) matrix, and its single
-home is [src/exfil/severity.ts](src/exfil/severity.ts) — the check pipeline, the
+home is [src/exfil/severity.ts](https://github.com/TachikomaGundam/Border-Customs/blob/main/src/exfil/severity.ts) — the check pipeline, the
 `border exfil` CLI and this table all render that table, never re-decide it; the
 `EXFIL-DOC` guard test fails the build if a cell is restated wrong:
 
@@ -608,11 +643,60 @@ degraded run.
 
 ## Configuration
 
-Everything border can be told lives in `border.yaml` at the repo root. Unknown keys are
+Border is a property of the **checking machine**, not of the checked repo. Config resolves
+in this order, and the machine-side rungs exist so gate config (including waivers) never has
+to be committed into a product repo:
+
+1. `--config <path>` (explicit);
+2. `$BORDER_CONFIG` — fail-closed: set-but-empty or unreadable is exit 2, never a fall-through;
+3. the **machine store**: `$BORDER_CONFIG_DIR` (else `$XDG_CONFIG_HOME/border/machines`, else
+   `~/.config/border/machines`) holding `<sha256-16>.yaml` files keyed by the repo's canonical
+   remote URL (`host/path`, credentials/`.git`/scp-vs-https spellings collapsed);
+4. `./border.yaml` (cwd, then git toplevel) — kept for repos that *choose* to carry their config;
+5. git-remote inference (targets only, no waivers) when nothing above exists.
+
+Unknown keys are
 rejected at load (a typo in a gate config is a gate you did not ask for). `${VAR}`
 expansion applies only to remote URLs and registry/repository/host values, and an unset variable
 is a hard error, never an empty string.
 
+#### Sandboxed builds (`targets.<ch>.sandboxImage`)
+
+Configure pins with the helper instead of hand-editing the machine store:
+`border sandbox init --lane npm --image node@sha256:<64hex>` (writes only the
+0600 machine-store file under the §3-qualified root, refuses tmp/unowned dirs and
+tag refs); `border sandbox status` shows what the loader will actually honor;
+`unpin` removes keys. The helper never writes into the audited repo.
+
+When a lane declares `sandboxImage`, that lane's consented build runs inside `docker run`
+instead of on the host: `--network none` (the daemon-applied argv is the enforcement anchor;
+a DNS+TCP probe re-checks from *inside* as a tripwire that fails the build closed), read-only repo mount, build on a tmpfs snapshot, `--cap-drop ALL`,
+`no-new-privileges`, and a scrubbed env (image defaults + `HOME=/tmp` only). The image MUST be
+digest-pinned:
+
+```yaml
+targets:
+  npm:
+    sandboxImage: node@sha256:<64 hex>   # tags are rejected at load — a mutable tag
+                                          # would let check and push certify different bytes
+```
+
+`sandboxImage` is a **security-tier key**: it is honored only from the machine store or an
+explicit `--config` file outside the repo, and only after fd-chain qualification (every path
+component verified by open file descriptor: root-owned or euid-owned above your trust anchor,
+euid-owned `0700`-below files `0600` below it — symlink or mode violations fail closed).
+Any other declaration of the same key — the repo's own border.yaml, a lax-mode (group/world
+readable or writable) store file, an `XDG_CONFIG_HOME` override pointing somewhere
+unqualifiable — is a named hard refusal (`sandbox-config-shadowed` /
+`sandbox-config-unqualified`), never a silent ignore and never a host fallback.
+
+Freshness and push carry the same binding: a PASS certified inside image X is re-proved only
+inside X (config drift forces a full re-check), and docker being *absent* while an image is
+configured is exit 2 with the remedy named — never a silent host fallback. No `sandboxImage`
+means today's host build, unchanged. The crates lane keeps its registry cache in
+`.border/cache/` (the one writable bind); the pypi image must ship the build backend's
+dependencies (there is no network inside).
+
 Minimal, a git-only repo:
 
 ```yaml
@@ -663,8 +747,15 @@ rules:
   ips: ["192.0.2.1"]
   pathPatterns: ["/Users/*", "*.pfx"]
   maxFileKB: 500                            # oversized-file threshold (default)
+  aliases:                                  # optional: rule-rename migration for allow pins
+    old-rule-name: current-rule-name        #   {renamed-from: current} — waivers survive renames
 allow:                                      # enumerated suppressions, never blanket
   - { rule: "junk-artifact", match: "*", file: "test/fixtures/**" }
+  - rule: "gitleaks:*"                      # fixture-set waiver: values pins the exact
+    file: "tests/fixtures/**"               #   value digests; ANY value outside stays red
+    values: ["<64hex>", "<64hex>"]
+    until: "2027-01-01"                     # optional UTC sunset; after it the entry is
+                                            #   inert and echoed as allow-entry-expired
 engines:
   require: [gitleaks, secretlint]           # trufflehog: true adds the third-party engine
 residue:
@@ -675,6 +766,15 @@ release:
 
 Notes that change behavior:
 
+- **Archive member addressing in `allow.file`:** findings inside archives are attributed
+  `archive!<inner>`. A plain `file` glob matches only the truncated OUTER path (`archive`),
+  so member-level pins need the escape form `archive\\!inner` (the `\!` switches the entry to
+  full-attribution matching). Members are addressable; forgetting the escape silently matches
+  the whole archive instead.
+- **Waiver floors:** a `values` entry suppresses only the listed value digests — a new value
+  under the same path/rule stays red; an `until` entry is inert after its UTC date and is
+  echoed as an INFO `allow-entry-expired` finding instead of quietly keeping work.
+
 - `targets.git.remotes: []` (explicit, empty) is a *deliberate* repo-local scope: all
   history/tree/identity/artifact legs still run, only the exposure set is empty. A
   completely missing config with real remotes falls back to config-from-`git remote` with
@@ -719,7 +819,10 @@ the hook must first pass. Drop `--force` to get sub-second skip-ledger replay in
 re-scan on every `git push`.
 
 **CI.** `border check --json` emits the stable report object; gate on the exit code, parse
-`verdict`/`counts` for dashboards. In CI you typically want `--force` on a cache-less
+`verdict`/`counts` for dashboards. Each finding is
+`{ rule, severity, target, path?, line?, commit?, engine, message, valueDigest, snippet }` —
+the file location is **`path`** (absent when the finding is commit-only, e.g. an identity
+finding); there is no `file` field. In CI you typically want `--force` on a cache-less
 runner, plus your `gitleaks` binary provisioned in the image (a degraded run exits 2, which
 most CI maps to red; that is the point).
 
@@ -736,7 +839,7 @@ plugin entry ships as `exports["./server"]`):
 ```jsonc
 {
   // pin the exact version — an @latest channel hits the registry on every cold start
-  "plugin": ["border-customs@0.8.1"]
+  "plugin": ["border-customs@0.8.3"]
 }
 ```
 
@@ -832,6 +935,10 @@ which is now a thin consumer of `inspect --json` with the rc contract unchanged
 - **Fail-closed doctrine.** "Silence never means absent" is applied mechanically: empty
   registry stdout, unparsed versions, non-translatable exit codes, unresolvable ownership,
   corrupt-but-present rules inputs, all become exit 2 or a CRITICAL, never a pass.
+- **Platform behaviour is probed, not assumed.** The npm stage reads `npm --version` before
+  packing. On npm < 11 a declared pack-phase hook is a named exit 2, because that npm line
+  executes `prepare` despite `--ignore-scripts` (reproduced on npm 10.9.7, 2026-10-19); a
+  missing or unparseable version is also exit 2.
 - **No telemetry, no callbacks.** `border check` touches the network only for the
   registry pre-flight, against the URLs the channels define: `registry.npmjs.org`,
   `pypi.org`, and `rubygems.org` are overridable (private indexes; `targets.rubygems.host`),
@@ -843,9 +950,91 @@ which is now a thin consumer of `inspect --json` with the rc contract unchanged
   it, and which every scan leg refuses to treat as a finding source or an allow-list
   target. A repo that *tracks* `.border/**` is itself a CRITICAL finding. A single-writer
   lock makes concurrent runs exit 2 instead of racing.
+- **Reports go through a private channel.** See [SECURITY.md](SECURITY.md) for the
+  reporting route and scope. Do not put exploit details or live secrets in a public issue.
+
+## Development
+
+Contributor setup, the exact external-engine list, subset test commands, and the version
+rotation procedure live in [CONTRIBUTING.md](CONTRIBUTING.md). In short:
+
+```bash
+npm ci
+npm run typecheck
+npm test
+```
+
+CI runs the full suite on Node 22 (npm 10) and Node 24 (npm 11) for every push to `main`
+and every pull request, plus version single-source, typecheck, build, and audit gates.
 
 ## Changelog
 
+### 0.8.3 (2026-11-02)
+- Fix: `exfil-cred-location` is now syntax-aware in JS/TS sources (handoff b61b42a) —
+  `.env` tokens count only inside string-literal spans (TypeScript compiler API, shipped
+  as a runtime dependency, bundle stays external-pinned); member accesses (`opts.env`),
+  short receivers and comment text are no longer reported. Markdown/text keep the
+  bare-mention behavior; every other rule is untouched. All tree faces (check, history,
+  tip lens) share the guard; parse failure ⇒ old behavior + one stderr note, exit codes
+  unchanged. Rules fingerprint rotated (cached PASSes re-verify once).
+
+### 0.8.2 (2026-11-01)
+- Production dependency graph now measures ZERO advisories (`npm audit --omit=dev`): the
+  pattern rule is vendored (`src/engines/borderPatternRule.ts`, MIT attribution; drops the
+  unpatchable braces/micromatch + fast-uri chain) and `tool` — an identity function — is
+  vendored in `plugin/border.ts`, moving `@opencode-ai/plugin` (and its effect-beta → toml
+  chain) to devDependencies; live-host probe tests keep the activation proof. The CI audit
+  gate tightens from critical to HIGH so this cannot rot.
+- `border sandbox init|pin|status|unpin` — the opt-in pin helper from the Q1 ruling
+  (machine store only, 0600 atomic writes, §3 self-verification with rollback of its own
+  writes; deliberately absent from the plugin's agent-reachable command set).
+- Security tier for execution-deciding keys (`src/tier.ts`, sibyl §3⁗/§3⁖/§3‡):
+  `sandboxImage`/`allowBuilds` honor only from fd-chain-qualified machine-store or out-of-repo
+  `--config` sources; repo declarations, lax-mode files, and hijacked `XDG_CONFIG_HOME` are
+  named refusals (`sandbox-config-shadowed`/`sandbox-config-unqualified`); the
+  `BORDER_ALLOW_BUILDS` environment channel is REMOVED (never released, so no migration);
+  passwd-derived canonical store root — `$HOME` spoofing cannot move it.
+- Sandboxed artifact builds: optional `targets.<ch>.sandboxImage` (digest-pinned, tags fail
+  closed at load) runs consented npm/pypi/crates/rubygems builds — and freshness re-packs —
+  inside `docker run` with `--network none` proved by an in-container DNS+TCP probe, a
+  read-only repo mount, tmpfs build, `--cap-drop ALL`, scrubbed env, and the ledger record
+  bound to the exact image digest (a rotated image invalidates cached PASS). Missing docker
+  with an image configured is a named exit 2, never a host fallback. New `test/sandbox.test.ts`
+  pins the docker argv contract token by token.
+- Hardened the npm pack-phase guard (sibyl must_fix): ALL package.json manifests in the tree
+  are scanned, not just the root (a workspaces child's `prepare` is now refused on npm < 11),
+  and unreadable manifests or a walk-cap hit count as a hook — unknown is never assumed safe.
+- Machine-side config (HR decoupling handoff 2026-10-23): resolution chain is now
+  `--config > $BORDER_CONFIG (fail-closed) > machine store (XDG/border/machines, keyed by
+  canonical remote URL) > ./border.yaml > git-remote inference`, so gate config and waiver
+  lists live on the checking machine and never need to be committed into a product repo.
+  Allow entries gained `values` (fixture-set waivers that never cover a new value), `until`
+  (UTC sunset, expired entries echoed never silently honored), `\!` archive-member escaping,
+  and `rules.aliases` (rule renames no longer strand waivers). Border state was already
+  porcelain-invisible (`.border/.gitignore` self-ignore; verified 2026-10-23).
+- Provenance: every check and push record carries `engineBuild`
+  (`<version>+<commit>[.dirty]`, the string `border --version` prints), so a verdict names
+  the exact border build that produced it. Motivated by a machine where every gate ran off
+  an unpinned worktree bundle and no record said so; worktree use is now visible on the
+  record face (see "Pinned consumption"). Bundles are stamped by `tools/build.mjs`.
+- Security (breaking): artifact build stages now require operator consent. A hostile clone can
+  ship its own border.yaml declaring pypi/rubygems targets, and `border check` built them —
+  PEP 517 backends and gemspecs ARE code (`python3 -m build --no-isolation` and `gem build`
+  markers reproduced 2026-10-23). Default runs are now scan-only (zero build spawns, pinned by
+  `test/build.execMarkers.test.ts`); consent comes only from outside the audited tree:
+  `--allow-builds` or `BORDER_ALLOW_BUILDS=1`. A scan-only PASS records no artifact digests and
+  therefore can never back a registry publish; `border scan` of third-party artifacts requires
+  the same consent (named exit 2 without it).
+- Security: refuse npm < 11 packages that declare `prepack`/`prepare`/`postpack` before
+  spawning `npm pack`. npm 10 executes `prepare` even with `--ignore-scripts` (reproduced on
+  10.9.7; npm 11.19.1 is clean), so the old defense could execute code from the audited repo.
+  The probe also runs before freshness re-packs. New regression tests pin the refusal and the
+  never-fires hook marker.
+- Fix: the Windows drive-letter path pattern no longer fires on JS escapes in prose
+  (`raw-repoPath:\n`); the UNC pattern no longer spans newlines.
+- Docs: the `--json` findings schema is stated explicitly (`path`, no `file` alias);
+  npm-target prerequisites now name the npm 11 boundary.
+
 ### 0.8.1 (2026-10-06)
 - Maintenance release: certificate-chain rebuild off the scrubbed lineage (INCIDENT-20261006
   identity-exposure cleanup). No functional change vs 0.8.0; 0.8.0's tarball is byte-intact but

package/dist/assets/exfil-src/rules.ts

@@ -31,6 +31,11 @@ export type RuleOptions = {
   readonly hosts?: readonly string[];
   /** exemption-band override (production default DEFAULT_EXEMPT_BANDS; [] forces in-range arms red in unit tests). */
   readonly exemptBands?: readonly string[];
+  /** source path (tree facet only) — drives the syntax-aware credential-location
+   *  guard (handoff b61b42a): JS/TS sources classify .env tokens by literal spans. */
+  readonly filePath?: string;
+  /** one-shot diagnostic sink (parse-failure notes; wired to stderr by the tree leg). */
+  readonly onNote?: (line: string) => void;
 };
 
 // ---------------------------------------------------------------- IPv4 machinery

package/dist/assets/exfil-src/rulesPath.ts

@@ -4,6 +4,7 @@
 // Self-stealth: no absolute workspace paths and no dotted quads in this file
 // (see rules.ts header for the 0.5.1 dogfood lesson this obeys).
 import type { RuleHit, RuleOptions } from "./rules.ts";
+import { inSpan, isJsTsPath, literalSpans, type LiteralSpan } from "./tsSpans.ts";
 
 // ---------------------------------------------------------------- exfil-home-path
 
@@ -52,20 +53,48 @@ function envTokenIsLocation(tok: string): boolean {
  * prefix, or has a real file-stem receiver (≥3 chars, never the process/os
  * API names); the JS optional-chain read `x?.env` never counts.
  */
-export function matchCredLocation(text: string, _o: RuleOptions): RuleHit[] {
+export function matchCredLocation(text: string, o: RuleOptions): RuleHit[] {
   const hits: RuleHit[] = [];
   const push = (matched: string, line: number): void => {
     hits.push({ rule: "exfil-cred-location", matched, line, message: "Reference to a credential-bearing location (env file / pypirc / SSHPASS); the location itself, value not required to fire." });
   };
-  text.split("\n").forEach((body, idx) => {
-    for (const m of body.matchAll(PYPIRC_RE)) push(m[0] ?? "", idx + 1);
-    for (const m of body.matchAll(SSHPASS_RE)) push(m[0] ?? "", idx + 1);
+  // Syntax-aware guard (handoff b61b42a §3): in JS/TS sources a .env token is a
+  // path candidate ONLY inside a string-like literal span. Property accesses
+  // (opts.env), short receivers and comment text are syntactically not paths —
+  // no lexical rule over receiver names can tell them apart (read-aloud proof
+  // in the handoff). Parse failure ⇒ old behavior + one stderr note, exit code
+  // untouched. pypirc/SSHPASS tokens are untouched by the guard, in any file.
+  const filePath = o.filePath ?? "";
+  let spans: LiteralSpan[] | null | undefined;
+  const spansFor = (): LiteralSpan[] | null => {
+    if (spans === undefined) {
+      spans = literalSpans(filePath, text);
+      if (spans === null) o.onNote?.(`${filePath}: JS/TS parse unavailable — credential-location matches reported by the pre-0.8.3 text rule for this file`);
+    }
+    return spans;
+  };
+  const guarded = isJsTsPath(filePath);
+  let lineOffset = 0;
+  for (const [idx, body] of text.split("\n").entries()) {
+    const line = idx + 1;
+    for (const m of body.matchAll(PYPIRC_RE)) push(m[0] ?? "", line);
+    for (const m of body.matchAll(SSHPASS_RE)) push(m[0] ?? "", line);
     for (const m of body.matchAll(ENVFILE_RE)) {
       const tok = m[0] ?? "";
       if ((body[(m.index ?? 0) - 1] ?? "") === "?") continue;
-      if (envTokenIsLocation(tok)) push(tok, idx + 1);
+      if (!envTokenIsLocation(tok)) continue;
+      if (guarded) {
+        const sp = spansFor();
+        // token starts one char past the match (leading '.'); comment and
+        // identifier positions sit outside every literal span.
+        const offset = lineOffset + (m.index ?? 0) + 1;
+        if (sp === null) { /* parse-failure fallback: report (old behavior) */ }
+        else if (!inSpan(sp, offset)) continue;
+      }
+      push(tok, line);
     }
-  });
+    lineOffset += body.length + 1;
+  }
   return hits;
 }
 

package/dist/assets/exfil-src/scan.ts

@@ -69,6 +69,12 @@ export type ExfilScanInput = {
   readonly source: string;
   /** operator's rules.hosts (config.ts:102) for the ssh-target predicate. */
   readonly hosts?: readonly string[];
+  /** source file path (tree facet) — threaded to predicates for the syntax-aware
+   *  credential-location guard; message facets keep it undefined (a commit message
+   *  is not JS source). */
+  readonly filePath?: string;
+  /** parse-failure diagnostic sink for the tree leg. */
+  readonly onNote?: (line: string) => void;
   /**
    * Ingest hook mirroring the redact.ts adapter contract ("every adapter
    * registers every value it ingests"): the check pipeline passes
@@ -111,7 +117,12 @@ const PREDICATES: Readonly<Record<ExfilRuleId, (text: string, o: RuleOptions) =>
  */
 function scanFacet(input: ExfilScanInput, facet: Extract<ExfilFacet, "tree" | "message">): ExfilFinding[] {
   const channel: ExfilChannel = "native";
-  const options: RuleOptions = { facet, ...(input.hosts !== undefined ? { hosts: input.hosts } : {}) };
+  const options: RuleOptions = {
+    facet,
+    ...(input.hosts !== undefined ? { hosts: input.hosts } : {}),
+    ...(input.filePath !== undefined ? { filePath: input.filePath } : {}),
+    ...(input.onNote !== undefined ? { onNote: input.onNote } : {}),
+  };
   const findings: ExfilFinding[] = [];
   for (const rule of emitRulesFor(facet, channel)) {
     const severity = observedSeverity(rule, facet, channel);

package/dist/assets/exfil-src/tsSpans.ts

@@ -0,0 +1,88 @@
+// provenance: Abathur handoff 2026-11-01 (rule-class-3 false positives, commit b61b42a).
+//
+// `.env` is a disk location inside a string literal and a property access inside
+// code — the same characters, a SYNTACTIC distinction no receiver-shaped regex can
+// draw (opts vs secrets are both plain identifiers; proven by the handoff's
+// read-aloud round). This module answers one question for JS/TS sources: at which
+// byte spans does the file contain string-like literal text?
+//
+// Contract (handoff §3, decided there):
+//   * string literals, no-substitution template literals, and template fragments
+//     (head/middle/tail) are literal spans — the ${...} regions are INCLUDED,
+//     deliberately conservative: a location inside an interpolation is still the
+//     author writing a location into source text;
+//   * comments are NOT literal spans (the AST visitor never yields them);
+//   * parse diagnostics ⇒ null ⇒ the CALLER keeps the old behavior and emits the
+//     required stderr diagnostic. This module stays silent and side-effect free.
+// typescript is a real dependency resolved at runtime (esbuild keeps it external;
+// the createRequire banner in the bundle resolves it from the installed package).
+import { createRequire } from "node:module";
+
+const JS_TS_KINDS: Readonly<Record<string, string>> = {
+  ".js": "JS", ".jsx": "JSX", ".mjs": "JS", ".cjs": "JS",
+  ".ts": "TS", ".tsx": "TSX", ".mts": "TS", ".cts": "TS",
+};
+
+export type LiteralSpan = { readonly start: number; readonly end: number };
+
+export function isJsTsPath(filePath: string): boolean {
+  const dot = filePath.lastIndexOf(".");
+  return dot >= 0 && JS_TS_KINDS[filePath.slice(dot).toLowerCase()] !== undefined;
+}
+
+let tsApi: any; // eslint-disable-line @typescript-eslint/no-explicit-any -- compiler API is structural here
+function loadTs(): any {
+  if (tsApi === undefined) {
+    try {
+      tsApi = createRequire(import.meta.url)("typescript");
+    } catch {
+      tsApi = null; // resolution failure behaves like a parse failure: caller keeps old behavior + diagnostic
+    }
+  }
+  return tsApi;
+}
+
+/** Literal spans for a JS/TS source; null when no tree can be trusted. */
+export function literalSpans(filePath: string, text: string): LiteralSpan[] | null {
+  const ts = loadTs();
+  if (ts === null) return null;
+  const dot = filePath.lastIndexOf(".");
+  const kind = JS_TS_KINDS[filePath.slice(dot).toLowerCase()] ?? "TS";
+  const scriptKind = ts.ScriptKind[kind as keyof typeof ts.ScriptKind];
+  let sf: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  try {
+    sf = ts.createSourceFile(filePath, text, scriptKind, /* setParentNodes */ true);
+  } catch {
+    return null;
+  }
+  const parseDiagnostics: unknown[] = sf.parseDiagnostics ?? [];
+  if (parseDiagnostics.length > 0) return null;
+  const spans: LiteralSpan[] = [];
+  const visit = (node: any): void => { // eslint-disable-line @typescript-eslint/no-explicit-any
+    const k = node.kind as number;
+    if (
+      k === ts.SyntaxKind.StringLiteral
+      || k === ts.SyntaxKind.NoSubstitutionTemplateLiteral
+      || k === ts.SyntaxKind.TemplateHead
+      || k === ts.SyntaxKind.TemplateMiddle
+      || k === ts.SyntaxKind.TemplateTail
+    ) {
+      spans.push({ start: node.getStart(sf), end: node.getEnd() });
+    }
+    node.forEachChild(visit);
+  };
+  visit(sf);
+  spans.sort((a: LiteralSpan, b: LiteralSpan) => a.start - b.start);
+  return spans;
+}
+
+/** Membership: is offset inside any span? Linear with early exit — literal
+ *  spans nest (template head inside full template), and nested intervals
+ *  defeat a plain binary walk (a right sibling can shadow its left ancestor). */
+export function inSpan(spans: readonly LiteralSpan[], offset: number): boolean {
+  for (const s of spans) {
+    if (s.start > offset) break;
+    if (offset < s.end) return true;
+  }
+  return false;
+}

package/dist/assets/gitleaks-defaults-v8.30.1.toml

@@ -1,3 +1,27 @@
+# Vendored from gitleaks v8.30.1 (assets/default_config.toml), MIT License.
+#
+# MIT License
+#
+# Copyright (c) 2019 Zachary Rice
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
 # This file has been auto-generated. Do not edit manually.
 # If you would like to contribute new rules, please use
 # cmd/generate/config/main.go and follow the contributing guidelines