Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 7 additions & 3 deletions docs/security.md
Original file line number Diff line number Diff line change
Expand Up @@ -666,9 +666,13 @@ deliberately names no code that `secret:scan` cannot produce.
value, and fails closed: a scan that cannot complete exits non-zero rather than
looking clean — `2` when a tracked file could not be read, `1` when the scan
could not start. Only a complete, empty scan exits `0`. The inventory is
`docs/secrets.md`; the per-line whitelist for the three fake test fixtures is
`scripts/secret-scan-allowlist.json` (`test/crypto.test.ts:32`,
`test/transcript.test.ts:52` and `:66`). Never whitelist a directory.
`docs/secrets.md`; the per-line allowlist is `scripts/secret-scan-allowlist.json`
and carries exactly two entries, both in `test/transcript.test.ts`: `:52`, a
fixture user message that carries a token-shaped string, and `:66`, a redaction
test that needs one. `test/crypto.test.ts` needs no entry because its fixtures
are assembled from fragments, so the file holds no token-shaped literal. Never
allowlist a directory, and never let this sentence drift from the file it
describes — `test/secretsDoc.test.ts` fails when it does.

### OAuth

Expand Down
32 changes: 31 additions & 1 deletion test/secretsDoc.test.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import test from 'node:test'
import assert from 'node:assert/strict'
import { readFileSync } from 'node:fs'
import { existsSync, readFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'

// The inventory is only worth having if it is complete enough to rotate from and
Expand Down Expand Up @@ -97,3 +97,33 @@ test('.env.example keeps no GitHub token placeholder', () => {
test('the inventory is reachable from a command, not only from prose', () => {
assert.equal(packageJson.scripts?.['secret:scan'], 'node scripts/secret-scan.mjs')
})

// #59: the runbook told a reader that the allowlist covers "the three fake test
// fixtures" and named `test/crypto.test.ts:32`, which is a comment explaining
// why that file needs no entry at all. The scanner is the source of truth, so
// the sentence is pinned to the file it describes: an entry added, removed or
// renumbered without the prose following it fails here instead of sending the
// next rotation after a line that is not allowlisted.
test('the runbook names exactly the allowlist the scanner enforces', () => {
const security = readFileSync(`${root}docs/security.md`, 'utf8')
const allowlist = JSON.parse(readFileSync(`${root}scripts/secret-scan-allowlist.json`, 'utf8')) as Array<{
file: string
line: number
}>
assert.ok(allowlist.length > 0, 'the allowlist must not be empty')
const paragraph = security.split('\n\n').find((block) => block.includes('secret-scan-allowlist.json'))
assert.ok(paragraph !== undefined, 'docs/security.md must describe the allowlist the scanner reads')
// A bare `:66` belongs to the file named before it, which is how the runbook
// writes a second entry of the same file.
const named: string[] = []
let lastFile = ''
for (const token of paragraph.matchAll(/([A-Za-z0-9_./-]+\.test\.ts)|:(\d+)/g)) {
if (token[1] !== undefined) lastFile = token[1]
else if (lastFile !== '' && token[2] !== undefined) named.push(`${lastFile}:${token[2]}`)
}
const entries = allowlist.map((entry) => `${entry.file}:${entry.line}`)
assert.deepEqual(named.sort(), entries.sort(), 'docs/security.md must name exactly the entries scripts/secret-scan-allowlist.json carries')
for (const entry of allowlist) {
assert.ok(existsSync(`${root}${entry.file}`), `${entry.file} is allowlisted but does not exist`)
}
})
Loading