rvlib-shipkit 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.37.0
+
+- **The leak guard grew an allowlist, because it had no way to be wrong.** Every keyword matched as a case-insensitive substring over the staged added lines, so a four letter row landed inside a real npm dependency name and inside a base64 integrity hash in `bun.lock`, and that lockfile became uncommittable forever with no per repo override of any kind. The only way past was `--no-verify`, which disarms every other gate too, so the guard was training people to switch it off. Two answers ship, in this order. A `w:<word>` keyword row now matches on word boundaries spelled in unicode rather than with `\b`, which is ascii only and would let an accented name match inside a longer accented word: that makes the PATTERN smarter rather than the guard looser, and it is opt in, so a keyword file that carries no `w:` row behaves exactly as before. Then `repo.config.ts hooks.leakAllow` (with the machine-global twin `~/.rv-private/leak-allow.json`) declares a known-good match: `paths` names the files, `patterns` names the keywords, and `inHashes` narrows to a match that falls inside a content hash, where the bytes are an address rather than prose. `paths` plus `patterns` is the shape to reach for, because it waives one keyword in named files while the same keyword still blocks everywhere else, and a single occurrence outside a hash refuses an `inHashes` entry outright.
+- **A waiver is never silent.** Each entry carries a required `reason`, every waiver that fires PRINTS with that reason and the entry that owns it (on the FAIL path too, so a partial waive is visible beside what still blocks), and `hooks list` counts the declared waivers. An entry with no reason, with neither `paths` nor `patterns`, or with an unknown key dies at config load through `defineRepo`, and an allowlist file that will not parse waives nothing and WARNs, so a broken waiver leaves the guard stricter rather than looser.
+- **A tracked allowlist never becomes a copy of the private keyword list.** An entry names a keyword by FINGERPRINT (`fp:` plus 12 hex of its sha256), printed beside every hit, which is how a waiver gets written without anyone typing the private word into git. `repo.config.ts` takes the fingerprint form alone and refuses a literal by name. The private machine-global file may use either. The honest limit is stated in the source: a fingerprint stops the list being read off a tracked file and is no defence against a targeted guess.
+- The staged diff is now parsed per FILE (`addedLinesByFile`), so a hit says which file it came from and a waiver can name one. Which file a line belongs to is decided by COUNTING each hunk body from the size its header declares, never by trusting a `+++ …` line wherever it appears: an added line whose own text starts with `++` reaches the parser looking exactly like a file header, and believing one inside a hunk would let ordinary looking text drop every added line after it (`++ /dev/null`) or file the rest under a name a waiver covers (`++ b/bun.lock`). Substring rows match through a case-insensitive regex instead of `indexOf` over a lowercased copy, because one unicode character lowercases into two and slides every offset after it, and those offsets are what decide whether a match sits inside a content hash. A content-hash span is consulted ONLY by an entry that asked for `inHashes`: an api token is also a long base64 run, so skipping those spans by default would silence the guard on the exact shape it exists to catch.
+
 ## 0.36.0
 
 - **`shipkit smoke` — verify the way the end user does, after a deploy.** A read only Playwright pass: it logs in through the app's OWN login page, visits every route `repo.config.ts smoke` declares, samples the body text until it stops growing (a `waitFor` selector first, because a spinner holds the length constant), counts the selector's matches, measures whether the PAGE scrolls sideways, screenshots each route under `tmp/smoke/`, and collects console errors, page errors, failed requests and 4xx/5xx responses. The exit code is the number of failed routes. The password is a secret NAME, read through the repo's new `credsReadCommand` template (the READ twin of `credsCommand`, `{name}` and `{field}` substituted, no shell), never argv, env or config, and `defineRepo` refuses a value typed where the name belongs and a login declared without the reader. Playwright is resolved from the CONSUMER repo at run time, never carried by this package: a repo without it gets one line naming `bun add -d playwright && npx playwright install chromium`. When the host sends `x-pockethost-ratelimit-ip-hourly-*` headers, the report prints the budget and labels a CORS-shaped failure as the backend refusing rather than the app failing, telling the hourly quota from the concurrent cap by the remaining count. Between routes it pauses `paceMs` (default 3000, measured against a 15-concurrent cap: 0 reported 8 of 12 routes, 3000 reports 12 of 12). A route with `open` (a link selector) follows the first match's href after it and judges the landed page as its own row, which is how a detail page with a real id gets visited without the config knowing one. The login form lives at `login.path`, default `/login`. A problem collected during the login is a failed row of its own, and the pause runs before the row label moves, so a previous page's late failure lands on the page that caused it. `emailSecret` is refused when the reader template carries no `{field}`: the account read would answer the value, and the run would type the password into the identity box, where a failed-login journal keeps it.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.36.0",
+    "version": "0.37.0",
     "funding": "https://github.com/sponsors/rvion",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",

package/src/hooks/leak-guard.ts

@@ -4,10 +4,23 @@
 //
 // the keyword file is deliberately untracked (a list of things to grep for
 // is itself private). absent file → loud skip, never a silent pass.
+//
+// a keyword matches as a SUBSTRING, which is what catches a private name
+// glued into a hostname or an identifier. The cost is a false positive a repo
+// cannot escape: a four letter row lands inside a dependency name or inside a
+// base64 integrity hash in a lockfile, and that lockfile is uncommittable
+// forever. A guard that cries wolf is a guard people answer with --no-verify,
+// which protects nothing. Two answers, in this order. `w:<word>` rows match on
+// word boundaries, which makes the PATTERN smarter rather than the guard
+// looser. An ALLOWLIST waives a known-good match in a named context, and every
+// waiver that fires is PRINTED with its reason, so a reader sees what was let
+// through and why.
+import { createHash } from 'crypto'
 import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
+import { basename, join } from 'path'
 
-export type LeakHit = { where: string; pattern: string }
+export type LeakHit = { where: string; pattern: string; file?: string }
+export type LeakWaiver = LeakHit & { reason: string; source: string }
 
 /** what a hit REPORTS. The matched string is private by construction, and a
  *  gate that prints it verbatim puts it in a terminal, a CI log and any paste
@@ -15,16 +28,66 @@ export type LeakHit = { where: string; pattern: string }
 export const maskPattern = (p: string): string =>
     p.startsWith('re:') || p.length <= 6 ? p : `${p.slice(0, 3)}…${p.slice(-2)} (${p.length} chars)`
 
+/** a stable name for a pattern that does not CARRY it, so a tracked allowlist
+ *  points at a private keyword without becoming a copy of the private keyword
+ *  list. Printed beside every hit, which is how a waiver gets written without
+ *  anyone typing the word.
+ *
+ *  Honest scope: this stops the list being READ off a tracked file. It is no
+ *  defence against a targeted guess, because a short keyword has a small
+ *  search space and whoever already suspects the word can confirm it. */
+export const patternFingerprint = (pattern: string): string =>
+    'fp:' + createHash('sha256').update(pattern.toLowerCase()).digest('hex').slice(0, 12)
+
+/** one known-good match a repo (or this machine) waives.
+ *
+ *  `paths` alone waives every pattern in those files. `patterns` alone waives
+ *  those patterns everywhere. The PAIR is the shape to reach for: this
+ *  pattern, in these files, while the same pattern still blocks anywhere else.
+ *  `inHashes` narrows further, to a match that lands inside a content hash. */
+export type LeakAllowEntry = {
+    /** why this match is known good. Printed every time the waiver fires, so
+     *  a reader months later can judge it. Required. */
+    reason: string
+    /** staged paths this entry covers: a repo-relative path, a bare basename
+     *  ('bun.lock'), or a 'dir/' prefix. Absent = every target, the commit
+     *  message included. */
+    paths?: string[]
+    /** the patterns this entry waives, named by FINGERPRINT (`fp:` + 12 hex,
+     *  printed beside every hit). Absent = every pattern, on `paths` alone.
+     *  A TRACKED source (repo.config.ts) takes the fingerprint form only: a
+     *  literal there puts the private keyword into git. */
+    patterns?: string[]
+    /** waive only a match that falls inside a content hash (an npm `sha512-…`
+     *  integrity field, a 40+ char base64 run). The bytes of a content address
+     *  are arithmetic, not prose, so a keyword inside one is noise. The same
+     *  keyword on a normal line of the same file still blocks. */
+    inHashes?: boolean
+}
+
 export type LeakGuardResult =
     | { status: 'skipped'; reason: string }
-    | { status: 'clean'; patterns: number }
-    | { status: 'hit'; hits: LeakHit[]; patterns: number }
+    | { status: 'clean'; patterns: number; waived: LeakWaiver[]; notes: string[] }
+    | { status: 'hit'; hits: LeakHit[]; patterns: number; waived: LeakWaiver[]; notes: string[] }
+
+export type ParsedPatterns = {
+    substrings: string[]
+    words: { word: string; re: RegExp }[]
+    regexes: { row: string; re: RegExp }[]
+}
+
+const escapeRegex = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
 
 /** Parse the keyword file: blank lines and `#` comments dropped, `re:<pattern>`
- *  rows become case-insensitive regexes, everything else a case-insensitive
- *  substring. */
-export function parsePatterns(text: string): { substrings: string[]; regexes: { row: string; re: RegExp }[] } {
+ *  rows become case-insensitive regexes, `w:<word>` rows match on word
+ *  boundaries, everything else a case-insensitive substring.
+ *
+ *  A `w:` row REPORTS as the bare word, so its mask and its fingerprint are
+ *  the same with or without the prefix: adding the prefix to a row never
+ *  invalidates a waiver already written against it. */
+export function parsePatterns(text: string): ParsedPatterns {
     const substrings: string[] = []
+    const words: { word: string; re: RegExp }[] = []
     const regexes: { row: string; re: RegExp }[] = []
     for (const raw of text.split('\n')) {
         const row = raw.trim()
@@ -32,24 +95,134 @@ export function parsePatterns(text: string): { substrings: string[]; regexes: {
         if (row.startsWith('re:')) {
             try { regexes.push({ row, re: new RegExp(row.slice(3), 'i') }) }
             catch { /* a malformed row must not disable the whole guard */ }
+        } else if (row.startsWith('w:')) {
+            const word = row.slice(2).trim().toLowerCase()
+            // \b is ascii-only in JS, which lets an accented name match inside
+            // a longer accented word: the boundary is spelled in unicode
+            if (word !== '') words.push({ word, re: new RegExp(`(?<![\\p{L}\\p{N}_])${escapeRegex(word)}(?![\\p{L}\\p{N}_])`, 'giu') })
         } else substrings.push(row.toLowerCase())
     }
-    return { substrings, regexes }
+    return { substrings, words, regexes }
 }
 
-function scan(haystack: string, where: string, p: ReturnType<typeof parsePatterns>, hits: LeakHit[]): void {
-    const lower = haystack.toLowerCase()
-    for (const s of p.substrings) if (lower.includes(s)) hits.push({ where, pattern: s })
-    for (const r of p.regexes) if (r.re.test(haystack)) hits.push({ where, pattern: r.row })
+type Span = [start: number, end: number]
+
+// a substring row is matched by a case-insensitive REGEX rather than by
+// indexOf over a lowercased copy: one unicode character (İ) lowercases into
+// two, which slides every offset after it, and the offsets are what decide
+// whether a match sits inside a content hash. Compiled once per keyword.
+const subRe = new Map<string, RegExp>()
+const substringRegex = (s: string): RegExp => {
+    const hit = subRe.get(s)
+    if (hit != null) return hit
+    const re = new RegExp(escapeRegex(s), 'gi')
+    subRe.set(s, re)
+    return re
 }
 
-export type LeakGuardOpts = {
-    /** path to the keyword file, relative to root (default '.rv-private/banned-keywords.txt') */
-    keywordFile?: string
-    /** extra text to scan (a commit message, a release note) */
-    text?: { label: string; content: string }[]
-    /** scan the staged diff + staged paths (default true) */
-    staged?: boolean
+/** every occurrence of every pattern, keyed by the id a hit reports. */
+function occurrences(haystack: string, p: ParsedPatterns): Map<string, Span[]> {
+    const found = new Map<string, Span[]>()
+    const push = (id: string, span: Span): void => {
+        const prev = found.get(id)
+        if (prev == null) found.set(id, [span])
+        else prev.push(span)
+    }
+    for (const s of p.substrings) for (const m of haystack.matchAll(substringRegex(s))) push(s, [m.index, m.index + m[0].length])
+    for (const w of p.words) for (const m of haystack.matchAll(w.re)) push(w.word, [m.index, m.index + m[0].length])
+    for (const r of p.regexes) {
+        const g = new RegExp(r.re.source, r.re.flags.includes('g') ? r.re.flags : r.re.flags + 'g')
+        for (const m of haystack.matchAll(g)) push(r.row, [m.index, m.index + m[0].length])
+    }
+    return found
+}
+
+// an npm/yarn integrity field, and any long base64 run. ONLY an entry that
+// asked for `inHashes` consults this: an api token is also a long base64 run,
+// so skipping these by default would be the guard going quiet on the exact
+// shape it exists to catch.
+const HASH_SPAN = /(?:sha\d{1,3}|md5)-[A-Za-z0-9+/=]{16,}|[A-Za-z0-9+/]{40,}={0,2}/gi
+
+const hashSpans = (text: string): Span[] => [...text.matchAll(HASH_SPAN)].map((m): Span => [m.index, m.index + m[0].length])
+
+const inside = (span: Span, spans: Span[]): boolean => spans.some(([a, b]) => span[0] >= a && span[1] <= b)
+
+/** a path selector: a repo-relative path, a bare basename, or a 'dir/' prefix. */
+function pathCovered(file: string | undefined, selectors: string[]): boolean {
+    if (file == null) return false
+    return selectors.some((s) => s === file || (s.endsWith('/') && file.startsWith(s)) || (!s.includes('/') && basename(file) === s))
+}
+
+export type LoadedAllow = LeakAllowEntry & { source: string }
+
+/** what the guard reads: one file's added lines, one staged path, or a text
+ *  the caller handed in (a commit message). */
+export type ScanTarget = { where: string; content: string; file?: string }
+
+/** the whole decision, with no git and no disk in it: which matches block,
+ *  which are waived, by whom, and why. */
+export function evaluateLeak(targets: ScanTarget[], p: ParsedPatterns, allow: LoadedAllow[]): { hits: LeakHit[]; waived: LeakWaiver[] } {
+    const hits: LeakHit[] = []
+    const waived: LeakWaiver[] = []
+    // one row per distinct (where, file, pattern): a keyword hit 40 times in
+    // one file is one finding
+    const seen = new Set<string>()
+    for (const t of targets) {
+        const found = occurrences(t.content, p)
+        if (found.size === 0) continue
+        let hashes: Span[] | null = null
+        for (const [id, spans] of found) {
+            const key = `${t.where} ${t.file ?? ''} ${id}`
+            if (seen.has(key)) continue
+            seen.add(key)
+            const fp = patternFingerprint(id)
+            const entry = allow.find((a) => {
+                if (a.paths != null && !pathCovered(t.file, a.paths)) return false
+                if (a.patterns != null && !a.patterns.some((x) => x === fp || x.toLowerCase() === id)) return false
+                if (a.inHashes === true) {
+                    hashes ??= hashSpans(t.content)
+                    if (!spans.every((s) => inside(s, hashes!))) return false
+                }
+                return true
+            })
+            if (entry == null) hits.push({ where: t.where, pattern: id, file: t.file })
+            else waived.push({ where: t.where, pattern: id, file: t.file, reason: entry.reason, source: entry.source })
+        }
+    }
+    return { hits, waived }
+}
+
+const ALLOW_KEYS = ['reason', 'paths', 'patterns', 'inHashes']
+const FINGERPRINT = /^fp:[0-9a-f]{12}$/
+
+/** why an entry cannot be used, or null. `tracked` = the source is committed
+ *  (repo.config.ts), where a literal pattern publishes the private word the
+ *  guard exists to keep out of git. */
+export function leakAllowProblem(entry: unknown, where: string, tracked: boolean): string | null {
+    if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) return `${where}: every entry is an object`
+    const e = entry as Record<string, unknown>
+    for (const k of Object.keys(e)) if (!ALLOW_KEYS.includes(k)) return `${where}: unknown key '${k}' (known: ${ALLOW_KEYS.join(', ')})`
+    if (typeof e['reason'] !== 'string' || e['reason'].trim() === '') return `${where}: needs a 'reason' — a waiver nobody can judge later is a hole`
+    if (e['paths'] == null && e['patterns'] == null)
+        return `${where}: needs 'paths' or 'patterns' — an entry with neither waives every pattern in every file, which is the guard switched off`
+    for (const k of ['paths', 'patterns'] as const) {
+        const v = e[k]
+        if (v == null) continue
+        if (!Array.isArray(v) || v.length === 0 || v.some((x) => typeof x !== 'string' || x.trim() === ''))
+            return `${where}: '${k}' is a non-empty array of non-empty strings`
+    }
+    if (e['inHashes'] != null && typeof e['inHashes'] !== 'boolean') return `${where}: 'inHashes' is a boolean`
+    if (tracked)
+        for (const x of (e['patterns'] as string[] | undefined) ?? [])
+            if (!FINGERPRINT.test(x))
+                return `${where}: '${x}' — a tracked allowlist names a pattern by FINGERPRINT (fp:…, printed beside every hit), never by value, or the private keyword lands in git`
+    return null
+}
+
+/** every problem in a declared allowlist. `defineRepo` throws on the first. */
+export function leakAllowProblems(entries: unknown, where: string, tracked: boolean): string[] {
+    if (!Array.isArray(entries)) return [`${where}: leakAllow is an array of entries`]
+    return entries.map((e, i) => leakAllowProblem(e, `${where}[${i}]`, tracked)).filter((x): x is string => x != null)
 }
 
 /** the machine-global list every repo's guard also reads: one private list
@@ -62,36 +235,138 @@ export function globalKeywordFile(): string | null {
     return existsSync(p) ? p : null
 }
 
+/** the machine-global allowlist, the twin of the keyword file. It is private,
+ *  so it may name a pattern by value as well as by fingerprint. */
+export function globalAllowFile(): string | null {
+    const home = process.env.HOME ?? ''
+    if (home === '') return null
+    const p = join(home, '.rv-private', 'leak-allow.json')
+    return existsSync(p) ? p : null
+}
+
+/** read an allowlist file (`LeakAllowEntry[]` as JSON). A file that will not
+ *  parse, or an entry that cannot be used, is a NOTE and never a failure: a
+ *  waiver that does not load leaves the guard stricter, never looser. */
+export function loadAllowFile(path: string, tracked: boolean): { entries: LoadedAllow[]; notes: string[] } {
+    let parsed: unknown
+    try { parsed = JSON.parse(readFileSync(path, 'utf8')) }
+    catch (e) { return { entries: [], notes: [`${path} is not readable JSON (${e instanceof Error ? e.message.split('\n')[0] : String(e)}) — its waivers are IGNORED`] } }
+    if (!Array.isArray(parsed)) return { entries: [], notes: [`${path} holds an array of allowlist entries — its waivers are IGNORED`] }
+    const entries: LoadedAllow[] = []
+    const notes: string[] = []
+    parsed.forEach((raw, i) => {
+        const problem = leakAllowProblem(raw, `${path}[${i}]`, tracked)
+        if (problem != null) notes.push(`${problem} — entry IGNORED`)
+        else entries.push({ ...(raw as LeakAllowEntry), source: `${basename(path)}[${i}]` })
+    })
+    return { entries, notes }
+}
+
+export type LeakGuardOpts = {
+    /** path to the keyword file, relative to root (default '.rv-private/banned-keywords.txt') */
+    keywordFile?: string
+    /** extra text to scan (a commit message, a release note) */
+    text?: { label: string; content: string }[]
+    /** scan the staged diff + staged paths (default true) */
+    staged?: boolean
+    /** the repo's declared waivers (repo.config.ts hooks.leakAllow). Tracked,
+     *  so fingerprints only. */
+    allow?: LeakAllowEntry[]
+    /** override the machine-global allowlist path; null reads none */
+    allowFile?: string | null
+}
+
+/** git c-quotes a path that carries a space or a non-ascii byte. */
+function unquotePath(p: string): string {
+    if (!p.startsWith('"')) return p
+    try { return JSON.parse(p) as string } catch { return p.slice(1, -1) }
+}
+
+/** `@@ -old,n +new,m @@`, the only line that says how long a hunk body is. */
+const HUNK_HEADER = /^@@ -\d+(?:,(\d+))? \+\d+(?:,(\d+))? @@/
+
+/** ADDED lines only, grouped by the file that receives them: what this commit
+ *  puts INTO the object store. Removed and context lines are already in
+ *  history, and a commit that DELETES private content must never be blocked by
+ *  that content. The grouping is what lets a waiver name a file.
+ *
+ *  A `+++ x` line is a file header only OUTSIDE a hunk body. Inside one it is
+ *  an added line whose own text starts with `++`, and reading it as a header
+ *  is a hole in both directions: `++ /dev/null` would drop every added line
+ *  after it in that file, and `++ b/bun.lock` would file them under a name a
+ *  waiver covers. So the hunk body is COUNTED, from the size its header
+ *  declares. A header this does not recognise (a combined `@@@` diff) opens an
+ *  unbounded body that only the next file closes, which is the safe direction:
+ *  content is still scanned, and no line inside it can name a file. */
+export function addedLinesByFile(diff: string): { file: string; content: string }[] {
+    const out: { file: string; content: string }[] = []
+    let current: { file: string; lines: string[] } | null = null
+    let oldLeft = 0
+    let newLeft = 0
+    const flush = (): void => {
+        if (current != null && current.lines.length > 0) out.push({ file: current.file, content: current.lines.join('\n') })
+        current = null
+    }
+    const add = (line: string): void => { if (current != null) current.lines.push(line.slice(1)) }
+    for (const line of diff.split('\n')) {
+        // a `diff --git ` at column 0 can never be diff CONTENT: a content line
+        // always carries its ' ', '+' or '-' prefix first
+        if (line.startsWith('diff --git ')) {
+            flush()
+            oldLeft = 0
+            newLeft = 0
+        } else if (oldLeft > 0 || newLeft > 0) {
+            if (line.startsWith('+')) { newLeft--; add(line) }
+            else if (line.startsWith('-')) oldLeft--
+            else if (!line.startsWith('\\')) { oldLeft--; newLeft-- } // '' counts for neither
+        } else if (line.startsWith('@@')) {
+            const h = HUNK_HEADER.exec(line)
+            oldLeft = h == null ? Infinity : h[1] == null ? 1 : Number(h[1])
+            newLeft = h == null ? Infinity : h[2] == null ? 1 : Number(h[2])
+        } else if (line.startsWith('+++ ')) {
+            flush()
+            const p = unquotePath(line.slice(4).trim())
+            current = p === '/dev/null' ? null : { file: p.startsWith('b/') ? p.slice(2) : p, lines: [] }
+        } else if (line.startsWith('+')) add(line) // a stray added line outside any hunk is still content
+    }
+    flush()
+    return out
+}
+
 export function runLeakGuard(root: string, o: LeakGuardOpts = {}): LeakGuardResult {
     const rel = o.keywordFile ?? '.rv-private/banned-keywords.txt'
     const file = join(root, rel)
     const sources = [existsSync(file) ? file : null, globalKeywordFile()].filter((f): f is string => f != null)
     if (sources.length === 0) return { status: 'skipped', reason: `${rel} not found and no ~/.rv-private/banned-keywords.txt — no keyword list, no leak guard` }
     const patterns = parsePatterns(sources.map((f) => readFileSync(f, 'utf8')).join('\n'))
-    const count = patterns.substrings.length + patterns.regexes.length
+    const count = patterns.substrings.length + patterns.words.length + patterns.regexes.length
     if (count === 0) return { status: 'skipped', reason: `keyword file(s) have no patterns (${sources.join(', ')})` }
 
-    const hits: LeakHit[] = []
+    const notes: string[] = []
+    const allow: LoadedAllow[] = []
+    ;(o.allow ?? []).forEach((e, i) => {
+        const problem = leakAllowProblem(e, `repo.config.ts hooks.leakAllow[${i}]`, true)
+        if (problem != null) notes.push(`${problem} — entry IGNORED`)
+        else allow.push({ ...e, source: `repo.config.ts hooks.leakAllow[${i}]` })
+    })
+    const globalAllow = o.allowFile === undefined ? globalAllowFile() : o.allowFile
+    if (globalAllow != null && existsSync(globalAllow)) {
+        const g = loadAllowFile(globalAllow, false)
+        allow.push(...g.entries)
+        notes.push(...g.notes)
+    }
+
+    const targets: ScanTarget[] = []
     if (o.staged !== false) {
-        // staged CONTENT (what lands in the object store) and staged PATHS
-        // (a filename can leak as loudly as a line of code)
         const diff = Bun.spawnSync(['git', 'diff', '--cached'], { cwd: root, maxBuffer: 256 * 1024 * 1024 })
-        if (diff.exitCode === 0) {
-            // ADDED lines only: what this commit puts INTO the object store.
-            // removed/context lines are already in history, and a commit that
-            // deletes private content must never be blocked by that content
-            const added = diff.stdout.toString().split('\n')
-                .filter((l) => l.startsWith('+') && !l.startsWith('+++'))
-                .join('\n')
-            scan(added, 'staged content', patterns, hits)
-        }
+        if (diff.exitCode === 0)
+            for (const f of addedLinesByFile(diff.stdout.toString())) targets.push({ where: 'staged content', file: f.file, content: f.content })
+        // a filename can leak as loudly as a line of code
         const names = Bun.spawnSync(['git', 'diff', '--cached', '--name-only'], { cwd: root })
-        if (names.exitCode === 0) scan(names.stdout.toString(), 'staged path', patterns, hits)
+        if (names.exitCode === 0) for (const n of names.stdout.toString().split('\n')) if (n.trim() !== '') targets.push({ where: 'staged path', file: n, content: n })
     }
-    for (const t of o.text ?? []) scan(t.content, t.label, patterns, hits)
+    for (const t of o.text ?? []) targets.push({ where: t.label, content: t.content })
 
-    // one row per distinct (where, pattern) — a keyword hit 40 times is one finding
-    const seen = new Set<string>()
-    const unique = hits.filter((h) => { const k = h.where + ' ' + h.pattern; if (seen.has(k)) return false; seen.add(k); return true })
-    return unique.length > 0 ? { status: 'hit', hits: unique, patterns: count } : { status: 'clean', patterns: count }
+    const { hits, waived } = evaluateLeak(targets, patterns, allow)
+    return hits.length > 0 ? { status: 'hit', hits, patterns: count, waived, notes } : { status: 'clean', patterns: count, waived, notes }
 }

package/src/hooks/run-hooks.ts

@@ -7,7 +7,7 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from
 import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { commitMessageOffenses } from './commit-message.ts'
-import { globalKeywordFile, maskPattern, runLeakGuard } from './leak-guard.ts'
+import { globalAllowFile, globalKeywordFile, maskPattern, patternFingerprint, runLeakGuard, type LeakAllowEntry, type LeakHit, type LeakWaiver } from './leak-guard.ts'
 import { runRootIdentity } from './root-identity.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { RepoConfig } from '../repo-config.ts'
@@ -21,6 +21,14 @@ export type HooksConfig = {
     commitMsg?: { id: string; cmd: string[] }[]
     /** keyword file for the leak guard (default '.rv-private/banned-keywords.txt') */
     keywordFile?: string
+    /** known-good leak-guard matches this repo waives: a lockfile whose
+     *  dependency names or integrity hashes collide with a keyword is the
+     *  motivating case. Each entry carries a reason, and a waiver that fires
+     *  PRINTS, so nothing passes silently. This file is tracked, so an entry
+     *  names a pattern by fingerprint (`fp:…`, printed beside every hit) and
+     *  never by value. The machine-global twin is ~/.rv-private/leak-allow.json.
+     *  hooks/leak-guard.ts */
+    leakAllow?: LeakAllowEntry[]
     /** staged-path prefixes that may never enter git (local state like
      *  '.comfy-ts/'). gitignore is advisory and editable; this gate is not. */
     blockedPaths?: string[]
@@ -148,6 +156,29 @@ function seedKeywordFile(root: string, keywordFile?: string): string | null {
 
 export type GateOutcome = { id: string; ok: boolean; lines: string[] }
 
+/** a hit line: the masked pattern plus its FINGERPRINT, which is the token a
+ *  waiver is written against, so nobody has to type the private word to
+ *  exempt it. The file rides along for a content hit; a staged-PATH hit adds
+ *  nothing, because there the path IS what matched. */
+const hitLine = (x: LeakHit): string =>
+    `      ${x.where}${x.where === 'staged content' && x.file != null ? ` ${x.file}` : ''}: ${maskPattern(x.pattern)} [${patternFingerprint(x.pattern)}]`
+
+/** what the allowlist let through, one line per waiver. An allowlist that
+ *  fires invisibly is a silent weakening, so a waived match is as loud as a
+ *  blocked one and carries the reason its author wrote. */
+function waivedLines(waived: LeakWaiver[]): string[] {
+    const rows = new Map<string, { pattern: string; reason: string; source: string; targets: Set<string> }>()
+    for (const w of waived) {
+        const key = `${w.pattern} ${w.source}`
+        const row = rows.get(key) ?? { pattern: w.pattern, reason: w.reason, source: w.source, targets: new Set<string>() }
+        row.targets.add(w.file ?? w.where)
+        rows.set(key, row)
+    }
+    return [...rows.values()].map(
+        (r) => `      waived ${maskPattern(r.pattern)} [${patternFingerprint(r.pattern)}] in ${r.targets.size} target(s) — ${r.reason} (${r.source})`,
+    )
+}
+
 /** the pre-commit gate: built-in leak guard, then the repo's own commands.
  *  A commit takes ~1s (build/shipkit.md): the gate times itself, and going
  *  over budget WARNs naming the fix, so drift back to slow commits is loud. */
@@ -156,16 +187,27 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
     const h = config.hooks ?? {}
     const out: GateOutcome[] = []
     if (!(h.disable ?? []).includes('leak-guard')) {
-        const r = runLeakGuard(root, { keywordFile: h.keywordFile })
+        const r = runLeakGuard(root, { keywordFile: h.keywordFile, allow: h.leakAllow })
         if (r.status === 'skipped') out.push({ id: 'leak-guard', ok: true, lines: [`skip: leak-guard (${r.reason})`] })
-        else if (r.status === 'clean') out.push({ id: 'leak-guard', ok: true, lines: [`ok: leak-guard clean (${r.patterns} pattern(s))`] })
+        else if (r.status === 'clean') out.push({
+            id: 'leak-guard',
+            ok: true,
+            lines: [
+                `ok: leak-guard clean (${r.patterns} pattern(s)${r.waived.length === 0 ? '' : `, ${r.waived.length} waived`})`,
+                ...waivedLines(r.waived),
+                ...r.notes.map((n) => `      WARN ${n}`),
+            ],
+        })
         else out.push({
             id: 'leak-guard',
             ok: false,
             lines: [
                 `FAIL: leak-guard matched ${r.hits.length} banned pattern(s) — this commit would leak private content`,
-                ...r.hits.map((x) => `      ${x.where}: ${maskPattern(x.pattern)}`),
+                ...r.hits.map(hitLine),
+                ...waivedLines(r.waived),
+                ...r.notes.map((n) => `      WARN ${n}`),
                 `      fix: remove the content, or edit the keyword file if the pattern is wrong`,
+                `      a known-good match: repo.config.ts hooks.leakAllow += { reason, paths, patterns: ['<the fp: above>'] }`,
             ],
         })
     }
@@ -242,9 +284,11 @@ export async function runCommitMsg(root: string, config: RepoConfig, messageFile
     // the leak guard also reads the MESSAGE, a private name pasted into a
     // commit body is as public as one pasted into a file
     if (!(h.disable ?? []).includes('leak-guard')) {
-        const r = runLeakGuard(root, { keywordFile: h.keywordFile, staged: false, text: [{ label: 'commit message', content: message }] })
+        const r = runLeakGuard(root, { keywordFile: h.keywordFile, staged: false, allow: h.leakAllow, text: [{ label: 'commit message', content: message }] })
         if (r.status === 'hit')
-            out.push({ id: 'leak-guard', ok: false, lines: [`FAIL: leak-guard matched in the commit message`, ...r.hits.map((x) => `      ${x.where}: ${maskPattern(x.pattern)}`)] })
+            out.push({ id: 'leak-guard', ok: false, lines: [`FAIL: leak-guard matched in the commit message`, ...r.hits.map(hitLine), ...waivedLines(r.waived)] })
+        else if (r.status === 'clean' && r.waived.length > 0)
+            out.push({ id: 'leak-guard', ok: true, lines: [`ok: leak-guard clean in the commit message (${r.waived.length} waived)`, ...waivedLines(r.waived)] })
     }
     for (const c of h.commitMsg ?? []) {
         const r = await spawnWithTimeout([...c.cmd, messageFile], { cwd: root, timeoutMs: 60_000 })
@@ -265,8 +309,12 @@ export function listGates(config: RepoConfig, root = process.cwd()): string[] {
     // a gate listed as active but unable to fire is worse than no listing:
     // this surface exists so nobody has to guess
     const leakState = off.has('leak-guard') ? ' (DISABLED by config)' : existsSync(join(root, kw)) || globalKeywordFile() != null ? '' : ` (INACTIVE, ${kw} absent and no ~/.rv-private list)`
+    // a waiver nobody can enumerate is a hole nobody can audit: the count of
+    // declared exemptions belongs on the same surface as the gate itself
+    const waivers = (h.leakAllow ?? []).length + (globalAllowFile() != null ? 1 : 0)
+    const leakAllowState = waivers === 0 ? '' : `, ${(h.leakAllow ?? []).length} repo waiver(s)${globalAllowFile() == null ? '' : ' + ~/.rv-private/leak-allow.json'}`
     return [
-        `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.rv-private/banned-keywords.txt`,
+        `pre-commit  leak-guard${leakState} — staged added lines + paths vs ${kw} + ~/.rv-private/banned-keywords.txt${leakAllowState}`,
         ...((h.blockedPaths ?? []).length > 0 ? [`pre-commit  blocked-paths — nothing under ${h.blockedPaths!.join(', ')} enters git`] : []),
         `pre-commit  root-identity${off.has('root-identity') ? ' (DISABLED by config)' : ''} — the repo's own name in package.json + repo.config.ts, and scratch files`,
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),

package/src/repo-config.ts

@@ -22,6 +22,7 @@ import { validateSmokeConfig, type SmokeConfig } from './smoke/run-smoke.ts'
 import { contractsFulfillness } from './rules/SK002-contracts-fulfillness.ts'
 import { BUILTIN_RULE_IDS, validateRules } from './rules/rule-registry.ts'
 import type { Rule } from './rules/rule.ts'
+import { leakAllowProblems } from './hooks/leak-guard.ts'
 import type { HooksConfig } from './hooks/run-hooks.ts'
 import type { ReleaseConfig } from './release/run-release.ts'
 import { UNIT_DECL_KEYS, type ReleaseUnitDecl } from './release/units.ts'
@@ -202,6 +203,12 @@ export function defineRepo(c: RepoConfig): RepoConfig {
     if (c.rules != null) validateRules(c.rules, { label: 'defineRepo: rules', taken: BUILTIN_RULE_IDS })
     // a smoke typo would land as a run that visits nothing and exits 0
     if (c.smoke != null) validateSmokeConfig(c.smoke)
+    // a leak-guard waiver is the one config row that can make a gate quieter,
+    // so a malformed one dies here rather than being dropped at commit time
+    if (c.hooks?.leakAllow != null) {
+        const problems = leakAllowProblems(c.hooks.leakAllow, 'defineRepo: hooks.leakAllow', true)
+        if (problems.length > 0) throw new Error(problems[0])
+    }
     if (c.credsReadCommand != null && !/\{name\}/.test(c.credsReadCommand))
         throw new Error(`defineRepo: credsReadCommand must carry {name} (and {field} for get | account), e.g. 'my-secrets {field} {name}'`)
     if (c.smoke?.login != null && (c.credsReadCommand ?? '') === '')