border-customs 0.8.2 → 0.8.4

package/README.md

@@ -608,38 +608,10 @@ 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.
+## Engines
+
+Engine posture per scanner — vendored vs external, version matrices,
+consumer-install behavior: [docs/engines.md](docs/engines.md).
 
 ## Configuration
 
@@ -839,7 +811,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.2"]
+  "plugin": ["border-customs@0.8.4"]
 }
 ```
 
@@ -969,262 +941,9 @@ and every pull request, plus version single-source, typecheck, build, and audit
 
 ## Changelog
 
-### 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
-  its OIDC provenance pin moved with the history rewrite, so a fresh tag + publish restores a
-  verifiable chain. Rotation: package.json + lock roots + plugin marker + scan UA + README pins +
-  this entry.
-
-### 0.8.0 (2026-09-30)
-- Add: **`border opencode inspect [--json]`** — the load-surface self-audit becomes a gate-owned
-  surface: six read-only aspects (cache self-consistency, spec freshness vs pin/registry, identity
-  handshake replay, Route A byte parity, Route A∧B dual-route collision, scope declaration),
-  fail-closed aggregation FAIL 1 > CANNOT 2 > PASS 0. `--json` pins `scope:"v1"` — V2 load surfaces
-  are a declared blind spot, not silently covered. Zero writes; `--purge` stays in the cron shell.
-- Change: **`exfil` joins the plugin's closed command list** (owner ruling R1 under the four-question
-  eligibility gate — no mutation, no credentials, no foreign-byte execution, no local egress;
-  packet: `.omo/evidence/F-EXFIL-ALLOWLIST-RULING-2026-09-30.md`). `border opencode …` verbs stay
-  terminal-only: they mutate `$XDG_CONFIG_HOME` and fail the gate's first question.
-- Change: `tools/plugin-drift-watch.mjs` retires to a thin shell over `border opencode inspect --json`
-  (single source of verdicts); the cron rc contract is byte-stable — FRESH 0, DRIFT 1, NOT-CACHED 0
-  (special-cased per ruling B2), CANNOT 2 — and the crontab line is unchanged.
-
-### 0.7.1 (2026-09-30)
-- Fix: **release-gate test ruler race** (`test/push.integration.test.ts` I4) — the
-  "dry-run made ZERO verdaccio requests" invariant counted lines in verdaccio's stdout
-  log, an eventually-consistent view: on a saturated CI runner the gate-leg probe lines
-  of an earlier phase land after the snapshot, inflating the dry-run delta (v0.7.0 CI
-  run 36671401844 failed `6 !== 2` while the identical bytes pass locally). The suite
-  now takes every snapshot through a FIFO drain barrier (sentinel request whose log line
-  must be visible before counting; sentinel traffic is excluded from the count). The
-  zero-network dry-run contract itself is unchanged — verified request-free on both sides
-  of the barrier; only the measuring instrument was repaired.
-
-### 0.7.0 (2026-09-28)
-- Add: **OpenCode 2 (beta) plugin compatibility** — the plugin module is dual-shaped
-  (`{id, setup}` for V2 hosts, frozen V1 `server()`), sharing the pre-spawn
-  allowlist/`--yes` gates and the 0.5.1 identity handshake across both shapes;
-  refusal/handshake/rendering byte-parity between edges is pinned by
-  `test/opencode.v2shape.test.ts` while the V1 path stays 16/16 on unmodified
-  tests. Root `index.ts` re-export shipped for V2 directory discovery (which
-  bypasses the exports map; live-proven on `@opencode-ai/cli` beta-19271).
-- Fix: the live V1 probe is anti-vacuous — opting in (`BORDER_OPENCODE_PROBE=1`)
-  without a resolvable binary or built dist now FAILS naming the remedy instead
-  of skipping green-adjacent (`BORDER_OPENCODE_BIN` override added).
-- Docs: support matrix (V1 object entry ≥ 1.18.29; V2 project-local verified;
-  `/border` command V1-only pending the V2 delivery API).
-
-### 0.6.0 (2026-09-25)
-- Add: **the exfil lens** — five rules (`exfil-rfc1918`, `exfil-ssh-target`,
-  `exfil-home-path`, `exfil-cred-location`, `exfil-host-profile`, `exfil-machine-binding`) that flag
-  exfil-shaped literals on about-to-be-public surfaces, the gap classic secret
-  scanners leave open because an internal IP is not a credential. The observed
-  severity of every (rule × facet × channel) cell lives in one machine-readable
-  home, `src/exfil/severity.ts`, rendered — never re-decided — by the check
-  pipeline, the new read-only `border exfil <rev|url>` CLI (tip tree by default,
-  `--deep` history, URL modes into a destroyed temp clone) and the README table,
-  each cell pinned by a docs guard. The tree HIGH family ships as vendored
-  twins (gitleaks TOML + secretlint patterns, ids byte-equal, verdict parity
-  tested); the commit-message facet is native-exclusive with a `:message` id
-  family so allow-list waivers can never cross facets; tag notes stay with the
-  pre-existing `tag-message-secret` engine leg. All exfil sources are
-  fingerprinted into `rulesHash`.
-- Add: **post-push landing verification** — after git legs move, the remote tip
-  is re-observed and scanned with the same machinery; clean appends an
-  append-only `t:"landing"` record and preserves the exit, a blocking hit exits
-  1 ("ALREADY PUBLIC; border detects, never erases"), an unobservable tip exits
-  2 with no record minted. Executed-push rows are never mutated; DRY-RUN lands
-  nothing.
-- Add: **fixture band + assembly doctrine** — 10.200.0.0/16 is reserved as the
-  always-exempt-on-tree test range (exemption mirrored natively in both twins,
-  message facet deliberately not exempt), and the test corpus assembles every
-  other leak shape at runtime (`assembleOctet`/`assembleHost`) so checked-out
-  bytes carry no complete leak tokens: border's own lens is green against
-  border's own corpus. Golden-suite coverage includes an opt-in truth lane
-  (`BORDER_EXFIL_TRUTH=1`) with a documented red-anchor lifetime clause.
-- Note: this release line traces to the 0.5.1 impersonation-wave audit; that
-  wave's H-3 follow-up — scrubbing this repo's own historical tip surfaces —
-  landed here as byte edits with the extracted values withheld from public
-  records by design (see the sanitized `.omo/evidence/` trail, not this log).
-
-### 0.5.1 (2026-09-24)
-- Fix: **plugin impersonation — the `border` tool could spawn the host binary instead of the
-  gate.** On Route B the 0.5.0 adapter resolved its packaged CLI as `process.execPath +
-  dist/index.js`, but inside the opencode plugin host `process.execPath` is the opencode
-  (bun-compiled) binary — sessions saw opencode's banner for `--help` and opencode usage
-  errors for every other command, while the tool's schema still promised border's
-  fail-closed contract. The resolution order is now: `BORDER_BIN` (wins alone; a broken
-  override never silently falls back) → packaged `dist/index.js` exec'd directly via its
-  shebang, else under `PATH` `node` → `border` on `PATH`. `process.execPath` is removed from
-  the adapter, pinned by a source-level regression test, and **every candidate must pass an
-  identity handshake** (`--help` answering with border's banner + `usage: border`, exit 0,
-  20 s cap) before any user argv is spawned — failure reports `cannot-answer` at exit 2 and
-  runs nothing else (spawn failures now map to 2, not 127, aligning the tool with the CLI's
-  exit-code contract). Regression tests cover the unspawnable-override and the
-  opencode-style-impostor fixtures; the impostor logs prove user argv never reaches it.
-  Honest boundary: the handshake catches mistaken identity (host binaries, PATH accidents),
-  not a deliberately forged banner.
-
-### 0.5.0 (2026-09-12)
-- Add: OpenCode plugin adapter (`exports["./server"]` + `/border` + `border` tool) loadable
-  two ways with zero manual install — config-declared `"plugin": ["border-customs@0.5.0"]`
-  (opencode downloads the package; the plugin spawns its own packaged CLI via a
-  package-relative `dist/index.js` resolution, `BORDER_BIN` override, PATH fallback) or
-  `border opencode install` (marker-identified idempotent file drop, foreign files refused,
-  never overwritten). Trigger: an agent session drives the gate without a shell-out or an
-  install ritual; `push --yes` stays terminal-only by design — the tool refuses it.
-
-### 0.4.2 (2026-09-12)
-- Fix: `npm publish` no longer prints the misleading "bin[border] script name
-  dist/index.js was invalid and removed" warning — package.json now carries the
-  canonical bare-relative bin form npm normalizes to anyway (mechanism traced to
-  @npmcli/package-json publish-side; artifacts were never broken; an always-on
-  test locks the form).
-- Change: RubyGems freshness (skip-ledger) parity compares a normalized CONTENT
-  digest instead of raw file bytes — `gem build` stamps the building toolchain
-  (RubyGems <3.6 embeds the build second in gzip headers), so raw-sha repack
-  parity could never be honored on those machines. The ledger digest and the
-  publish-time same-bytes re-hash stay RAW: what gets uploaded is still exactly
-  the certified bytes, and any unparseable artifact fails closed to a full
-  re-check.
-
-### 0.4.1 (2026-09-11)
-- Add: release-coherence rule family — every version source inside a published artifact
-  must agree (pyproject vs MODULE vs filename, gemspec vs gem metadata, Cargo.toml vs
-  crate filename, package.json self-consistency; the git-tag half is a publish-workflow
-  hard gate). Trigger: the aihr incident where a wheel labeled 0.2.2 shipped modules
-  self-reporting 0.2.1 — every pinned consumer silently got old behavior.
-- Add: `border roundtrip` local-artifact input — an argument resolving to an existing
-  file (.whl/.tgz/.crate/.gem, closed table) proves unpublished bytes end-to-end; the
-  streaming sha256 of those exact bytes is the ledger identity and the report carries
-  `source:local:<abs>` provenance. Honest boundary documented: the local PyPI-wheel lane
-  is residue-INERT by construction (pip fully tracks and prunes; verified live on pip
-  24.0 AND 25.0.1) — planted-detection demos belong to the hook-executing lanes
-  (npm postinstall, gem extconf, crates build.rs).
-- Change: pypi roundtrip lane dep-closure calibration — pip's resolver report demotes
-  dependency-storm files to LOW `dep-owned` rows, so genuine orphans stand alone; the
-  demotion requires a legitimate claimant dist-info (pin Name+Version match, canonical
-  dirname, unique, own site-packages root, not the target) after an independent verifier
-  proved a shadow `*-9.9.9.dist-info` could otherwise launder hostile writes.
-
-### 0.4.0 (2026-09-10)
-- Add: `border roundtrip <[ecosystem:]name@version>` — fact-proof valve. Installs the
-  package inside a throwaway Docker container, content-hashes the whole filesystem before
-  and after uninstall, and reports exactly what the uninstaller left behind. Persistence
-  surfaces (rc/profile mutations) => CRITICAL; orphan files => HIGH. Verdicts record to
-  the ledger by default (`--no-record` opts out); Docker absent => fail-closed, never clean.
-- Add: `residue.requireProof` — when on, a residue-capable artifact only passes `border
-  check` with a fresh recorded roundtrip proof (bound to rulesHash; flipping the config
-  invalidates cached verdicts). Missing proof => CRITICAL `roundtrip-proof-missing`.
-- Opt-in test legs: BORDER_ROUNDTRIP_DOCKER=1 (8 real container legs, 4 ecosystems).
-
-### 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
-  family of seven closed `residue-*` rules across tiers T1–T4 plus cross-manager, pairing,
-  and gem-unmatched lanes (see "The residue scan"): a hook matching the closed T1 safe-shape
-  signature drops to MEDIUM; every unknown shape keeps the original CRITICAL row verbatim.
-  Pairing (`# BEGIN <id>` marker blocks) is **detected only** — `residue-pairing-missing`
-  fires on the orphaned WRITE, a verified pair still pays its T3 HIGH; the waiver downgrade
-  path is the 0.4.0 roundtrip valve. Detection classes: C5 pairing discipline, C9 indirection
-  spellings, C10 comment/quote boundaries — evidence frozen in `src/artifacts/RESIDUE-CONTRACT.md`.
-- New `residue: { enabled }` config key (default on; strict; the ONLY skip path for the family,
-  and flipping it invalidates cached PASS rows because the toggle rides the fingerprint). The
-  residue rule table and classifier sources are now part of the ledger `rulesHash`: editing a
-  signature forces a re-check even at an unchanged commit and tree.
-- Boundary stated plainly: static analysis proves *capability*, not *fact*; border is not a
-  malware sandbox and never executes what it reads.
-
-### 0.2.0 (2026-09-05)
-
-- Two new push channels, same doctrine end to end: **crates** (public crates.io only;
-  literal `Cargo.toml` coordinates; pre-publish repackage digest-assert) and **rubygems**
-  (rubygems.org or any `targets.rubygems.host` gemcutter-compatible host; literal-only
-  gemspecs; `s.date` rejection).
-- Platforms are now descriptors in a channel registry: each channel owns its config schema,
-  env expansion, coordinate reading, probe, artifact stage, publish argv, and ledger fields
-  in one file. The git/npm/pypi legs share the same publish core they already used; their
-  behavior is unchanged.
-- Ledger `confirmedVia` gained `crates-json` and `rubygems-json`; 0.1.x ledgers parse
-  unchanged.
-- New prerequisites when those targets are configured: `cargo` on `PATH` (measured against
-  1.93.1 via rustup) and `gem` (measured against RubyGems 3.6.7 on ruby 3.3.8); other
-  versions are untested by the gate's same-bytes proofs.
-
-### 0.1.0
-
-- Initial release: git, npm, and PyPI push channels behind the fingerprint PASS gate.
+Full per-version history with the motivating incident for each release:
+[CHANGELOG.md](CHANGELOG.md). Release receipts (build provenance, gate transcripts):
+[docs/release/](docs/release/).
 
 ## License
 

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/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "border-customs",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "border-customs",
-      "version": "0.8.2",
+      "version": "0.8.4",
       "license": "MIT",
       "dependencies": {
         "@secretlint/core": "13.0.5",
@@ -15,8 +15,9 @@
         "@secretlint/secretlint-rule-preset-recommend": "13.0.5",
         "@textlint/regexp-string-matcher": "2.0.2",
         "publint": "0.3.24",
+        "typescript": "5.9.3",
         "yaml": "2.9.0",
-        "zod": "4.5.4"
+        "zod": "4.6.7"
       },
       "bin": {
         "border": "dist/index.js"
@@ -27,7 +28,6 @@
         "@types/node": "22.19.0",
         "esbuild": "0.25.12",
         "secretlint": "13.0.5",
-        "typescript": "5.9.3",
         "verdaccio": "6.10.2"
       },
       "engines": {
@@ -5760,7 +5760,6 @@
       "version": "5.9.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
-      "dev": true,
       "license": "Apache-2.0",
       "bin": {
         "tsc": "bin/tsc",
@@ -6105,9 +6104,9 @@
       }
     },
     "node_modules/zod": {
-      "version": "4.5.4",
-      "resolved": "https://registry.npmjs.org/zod/-/zod-4.5.4.tgz",
-      "integrity": "sha512-sC95tT5iHHH9gtpj6A81kh+NEaRAUFN+qlUPDUbRfOMvNf5QCBqsb3WgvnpVtK5Y+4UfA6KqufotuTvMGiTlsA==",
+      "version": "4.6.7",
+      "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz",
+      "integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==",
       "license": "MIT",
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"