secret-guard

1import type { Register } from 'claude-code'
2
3import { blockedReason, isEnvFile, mask } from './secrets'
4
5const WITHHELD = 'secret-guard: masking failed, so the output was withheld.'
6
7export const register: Register = on => {
8  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
9    const why = blockedReason(e.command)
10    if (why !== undefined) {
11      return { deny: `secret-guard: blocked because ${why}. Refer to variables by name, or ask the user to check the value.` }
12    }
13
14    const ran = await next(e)
15    if (ran.deny !== undefined) return ran
16    if (ran.isError === true) {
17      const masked = mask(ran.text ?? '')
18      return masked.count === 0 ? ran : { deny: `the command failed; output with ${masked.count} secret(s) masked:\n${masked.text}` }
19    }
20
21    const out = mask(ran.result.stdout)
22    const err = mask(ran.result.stderr)
23    if (out.count + err.count === 0) return ran
24    $.ui.toast(`secret-guard: masked ${out.count + err.count} secret(s) in Bash output`)
25    return { result: { ...ran.result, stdout: out.text, stderr: err.text }, context: ran.context }
26  }).catch(($, e, next) => (next.called ? { deny: WITHHELD } : { deny: 'secret-guard: the guard failed; the command did not run.' }))
27
28  on('tool.call', { tool: 'Read' }, async ($, e, next) => {
29    if (isEnvFile(e.file_path)) {
30      return { deny: 'secret-guard: reading .env files is blocked. Refer to variables by name, or ask the user to check the value.' }
31    }
32    const ran = await next(e)
33    if (ran.deny !== undefined || ran.isError === true || ran.result.type !== 'text') return ran
34    const masked = mask(ran.result.file.content)
35    if (masked.count === 0) return ran
36    $.ui.toast(`secret-guard: masked ${masked.count} secret(s) in ${ran.result.file.filePath}`)
37    return { result: { ...ran.result, file: { ...ran.result.file, content: masked.text } }, context: ran.context }
38  }).catch(($, e, next) => (next.called ? { deny: WITHHELD } : { deny: 'secret-guard: the guard failed; the file was not read.' }))
39}
40

1// Token shapes worth masking: each has a fixed prefix or structure, so dev
2// placeholders such as DEV_ADMIN_PASSWORD=changeme are left alone.
3const PATTERNS: readonly [string, RegExp][] = [
4  ['private-key', /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g],
5  ['jwt', /\beyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g],
6  ['aws-access-key', /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g],
7  ['aws-secret', /(aws_secret_access_key\s*[=:]\s*["']?)[A-Za-z0-9/+=]{40}/gi],
8  ['github-token', /\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{60,})\b/g],
9  ['slack-token', /\bxox[abprs]-[A-Za-z0-9-]{10,}/g],
10  ['anthropic-key', /\bsk-ant-[A-Za-z0-9_-]{20,}/g],
11  ['openai-key', /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}/g],
12  ['google-api-key', /\bAIza[0-9A-Za-z_-]{35}\b/g],
13]
14
15/** Masks known token shapes; returns the text and how many were masked. */
16export function mask(text: string): { text: string; count: number } {
17  let count = 0
18  let out = text
19  for (const [name, re] of PATTERNS) {
20    out = out.replace(re, (match: string, prefix?: unknown) => {
21      count++
22      return `${typeof prefix === 'string' ? prefix : ''}[REDACTED:${name}]`
23    })
24  }
25  return { text: out, count }
26}
27
28// `.env`, `.env.local`, `.env.prod`, but not `.env.example` / `.sample` /
29// `.template` / `.dist`, as a word or path component.
30const ENV_FILE = /(?:^|[\s'"=<>:/(])\.env(?:\.(?!example\b|sample\b|template\b|dist\b)[\w-]+)?(?=$|[\s'";|&)<>])/
31const CLAUDE_CONFIG = /(?:~|\$HOME|\/home\/[^/\s]+)\/\.claude(?:\.json|\/config\.json)\b/
32
33// A heredoc with a quoted delimiter (<<'EOF') is literal text, not commands;
34// an unquoted one still expands $(...), so its body stays in the check.
35const LITERAL_HEREDOC = /<<-?\s*(['"])(\w+)\1[^\n]*\n[\s\S]*?\n\s*\2[ \t]*(?=\n|$)/g
36
37/** Whether a file path names a .env file (not an example/template). */
38export function isEnvFile(path: string): boolean {
39  return ENV_FILE.test(path)
40}
41
42/** Why a Bash command must not run, or undefined when it may. */
43export function blockedReason(command: string): string | undefined {
44  const code = command.replace(LITERAL_HEREDOC, '')
45  if (ENV_FILE.test(code)) return 'it touches a .env file'
46  if (CLAUDE_CONFIG.test(code)) return 'it touches ~/.claude.json or ~/.claude/config.json'
47  return undefined
48}
49