keymaster

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Finding } from '../types'
5import { findSecrets, glob, redactDeep, riskyCommand, tag } from './scan'
6
7const findings = atom({ plugin: 'keymaster', key: 'findings' } as const, [])
8
9const STORE_ALLOW = 'keymaster.allow'
10let skip: string[] = []
11let warnCommands = true
12let allowed = new Set<string>()
13
14async function record($: EngineInterface, tool: string, hits: { kind: string; where: string; value: string; tag: string }[]): Promise<number> {
15  const at = await $.clock.now()
16  const list = await update($, findings, l => [...l, ...hits.map(h => ({ kind: h.kind, tool, where: h.where, length: h.value.length, tag: h.tag, at }))].slice(-200))
17  $.ui.status(`🔒 ${list.length} masked`)
18  const kinds = [...new Set(hits.map(h => h.kind))].join(', ')
19  $.ui.toast(`🔒 Keymaster masked ${hits.length} secret${hits.length === 1 ? '' : 's'} (${kinds}) from ${tool.replace(/^mcp__([^_]+(?:_[^_]+)*)__/, '$1 ')} output`)
20  return list.length
21}
22
23async function loadAllowed($: EngineInterface): Promise<void> {
24  const v = (await $.store.get(STORE_ALLOW)) as string[] | undefined
25  allowed = new Set(Array.isArray(v) ? v : [])
26}
27
28export const register: Register = (on, options) => {
29  skip = ((options.skipTools as readonly string[] | undefined) ?? []).map(String)
30  warnCommands = options.warnCommands !== false
31
32  on('session.start', async ($, e, next) => {
33    const started = await next(e)
34    await loadAllowed($)
35    await $.command.register({ name: 'keymaster', description: 'What Keymaster masked this session (kind and place, never the value); allow a false positive by its tag', argumentHint: '[allow <tag> | disallow <tag>]' })
36    return started
37  })
38
39  on('tool.call', async ($, e, next) => {
40    const tool = String(e.tool)
41    if (skip.some(p => glob(p, tool))) return next(e)
42    const r = await next(e)
43    if (r.deny !== undefined) return r
44    const notes: string[] = []
45    if (warnCommands && tool === 'Bash') {
46      const note = riskyCommand(String((e as { command?: unknown }).command ?? ''))
47      if (note) notes.push(`keymaster: ${note}`)
48    }
49    const { value: result, hits } = redactDeep(r.result, tag, allowed)
50    if (!hits.length) {
51      // The text core made from the result should match it; if it alone holds a secret, withhold rather than pass it on.
52      if (typeof r.text === 'string' && findSecrets(r.text).some(h => !allowed.has(tag(h.value))))
53        return { deny: 'Keymaster withheld this output: it holds a key-like value it could not mask in place. Re-run the command so it prints only the fields you need.' }
54      return notes.length ? { ...r, context: [...(r.context ?? []), ...notes] } : r
55    }
56    await record($, tool, hits)
57    const kinds = [...new Set(hits.map(h => h.kind))].join(', ')
58    notes.push(
59      `keymaster: ${hits.length} value${hits.length === 1 ? '' : 's'} (${kinds}) in this output ${hits.length === 1 ? 'is' : 'are'} masked as ‹masked kind tag›. ` +
60        `They are hidden on purpose: don't print them another way (no cat, grep, base64 or env tricks). If one is clearly not a secret, ask David to run /keymaster allow <tag>.`,
61    )
62    return { result: result as typeof r.result, ...(r.isError ? { isError: true as const } : {}), context: [...(r.context ?? []), ...notes] }
63  }).catch(($, e, next) => (next.called ? { deny: 'Keymaster could not scan this output, so it withheld it.' } : next(e)))
64
65  on('command.run', { command: 'keymaster' }, async ($, e) => {
66    const [verb = '', arg = ''] = e.args.trim().split(/\s+/)
67    if (verb === 'allow' || verb === 'disallow') {
68      if (!/^[0-9a-f]{8}$/.test(arg)) return { text: 'Usage: /keymaster allow <tag> (the 8 hex digits in ‹masked kind tag›).' }
69      await loadAllowed($)
70      if (verb === 'allow') allowed.add(arg)
71      else allowed.delete(arg)
72      await $.store.set(STORE_ALLOW, [...allowed])
73      return { text: verb === 'allow' ? `Values tagged ${arg} pass through from now on.` : `Values tagged ${arg} are masked again.` }
74    }
75    const list: Finding[] = await read($, findings)
76    if (!list.length) return { text: `Nothing masked this session.${allowed.size ? ` Allowed tags: ${[...allowed].join(', ')}.` : ''}` }
77    const lines = list.slice(-30).map(f => `${f.tag}  ${f.kind.padEnd(16)} ${String(f.length).padStart(4)} chars  ${f.tool} → ${f.where}`)
78    return { text: [`Masked this session (${list.length}; the newest 30, values never kept):`, ...lines, allowed.size ? `Allowed tags: ${[...allowed].join(', ')}` : ''].filter(Boolean).join('\n') }
79  })
80}
81
82

1// Pure detection for keymaster. Each detector names the part of a match that
2// is the secret (group `secret`), so the words around it survive.
3
4export type Hit = { kind: string; start: number; end: number; value: string }
5
6type Detector = { kind: string; re: RegExp }
7
8const ASSIGN_KEYS = [
9  'api[_-]?key', 'apikey', 'api[_-]?token', 'access[_-]?token', 'refresh[_-]?token', 'auth[_-]?token', 'token', 'secret', 'client[_-]?secret',
10  'password', 'passwd', 'pwd', 'passphrase', 'x-plex-token', 'x-api-key', 'access[_-]?key', 'secret[_-]?key', 'private[_-]?key',
11  'encryption[_-]?key', 'webhook[_-]?id', 'bearer', 'mqtt[_-]?pass(?:word)?', 'ha[_-]?token', 'license[_-]?key',
12].join('|')
13
14export const DETECTORS: Detector[] = [
15  { kind: 'private-key', re: /-----BEGIN (?:[A-Z]+ )?PRIVATE KEY-----(?<secret>[\s\S]+?)-----END (?:[A-Z]+ )?PRIVATE KEY-----/g },
16  { kind: 'jwt', re: /(?<secret>eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,})/g },
17  { kind: 'github-token', re: /(?<secret>(?:gh[pousr]_[A-Za-z0-9]{30,}|github_pat_[A-Za-z0-9_]{40,}))/g },
18  { kind: 'anthropic-key', re: /(?<secret>sk-ant-[A-Za-z0-9_-]{20,})/g },
19  { kind: 'openai-key', re: /(?<![A-Za-z0-9])(?<secret>sk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{20,})/g },
20  { kind: 'aws-key', re: /(?<secret>(?:AKIA|ASIA)[0-9A-Z]{16})/g },
21  { kind: 'slack-token', re: /(?<secret>xox[abprs]-[A-Za-z0-9-]{10,})/g },
22  { kind: 'google-key', re: /(?<secret>AIza[0-9A-Za-z_-]{35})/g },
23  { kind: 'arr-api-key', re: /<ApiKey>(?<secret>[^<\s]{16,})<\/ApiKey>/g },
24  { kind: 'esphome-key', re: /\bkey:\s*["']?(?<secret>[A-Za-z0-9+/]{40,}={0,2})["']?/g },
25  { kind: 'bearer', re: /\b(?:Bearer|Token)\s+(?<secret>[A-Za-z0-9._~+/=-]{16,})/g },
26  { kind: 'url-password', re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:(?<secret>[^\s@/]{3,})@/gi },
27  {
28    kind: 'assigned-secret',
29    // name = value, name: value, "name": "value", name=value in a query string; the value is the secret.
30    re: new RegExp(`(?<![A-Za-z0-9])["']?(?:${ASSIGN_KEYS})["']?\\s*[:=]\\s*["']?(?<secret>[^\\s"',;&<>{}()\\[\\]]{8,})`, 'gi'),
31  },
32]
33
34const PLACEHOLDER = /^(?:\$\{?[A-Z_][A-Z0-9_]*\}?|<[^>]*>|\*+|x{3,}|•+|‹masked[^›]*›|redacted|\[redacted\]|null|none|true|false|undefined|changeme|example|your[_-].*|\{\{.*\}\})$/i
35
36/** Whether a candidate value is a real-looking secret rather than a placeholder, path, number or masked text. */
37export function isSecretLike(kind: string, v: string): boolean {
38  if (PLACEHOLDER.test(v)) return false
39  if (v.includes('‹masked')) return false
40  if (kind === 'assigned-secret' || kind === 'bearer') {
41    if (/^[./~]/.test(v) || /^[a-z]+:\/\//i.test(v)) return false // a path or URL
42    if (/^\d+$/.test(v)) return false // a count or port
43    if (/^[a-z]+([_-][a-z]+)*$/.test(v) && v.length < 20) return false // a word like `required`, `file_path`
44    if (/^!secret\b/.test(v)) return false
45  }
46  return true
47}
48
49export function findSecrets(text: string): Hit[] {
50  const hits: Hit[] = []
51  for (const d of DETECTORS) {
52    d.re.lastIndex = 0
53    for (const m of text.matchAll(d.re)) {
54      const value = m.groups?.secret
55      if (!value || m.index === undefined) continue
56      const start = m.index + m[0].indexOf(value)
57      if (!isSecretLike(d.kind, value)) continue
58      hits.push({ kind: d.kind, start, end: start + value.length, value })
59    }
60  }
61  // Earlier and longer first; drop hits inside one already kept.
62  hits.sort((a, b) => a.start - b.start || b.end - a.end)
63  const kept: Hit[] = []
64  for (const h of hits) if (!kept.some(k => h.start < k.end && h.end > k.start)) kept.push(h)
65  return kept
66}
67
68export const mask = (kind: string, tag: string): string => `‹masked ${kind} ${tag}›`
69
70/** Masks every hit not allowed; `tagOf` names each value (a hash prefix). */
71export function redact(text: string, tagOf: (v: string) => string, allowed: ReadonlySet<string>): { text: string; hits: (Hit & { tag: string })[] } {
72  const hits = findSecrets(text)
73    .map(h => ({ ...h, tag: tagOf(h.value) }))
74    .filter(h => !allowed.has(h.tag))
75  if (!hits.length) return { text, hits }
76  let out = ''
77  let at = 0
78  for (const h of hits) {
79    out += text.slice(at, h.start) + mask(h.kind, h.tag)
80    at = h.end
81  }
82  return { text: out + text.slice(at), hits }
83}
84
85/** Walks a value, redacting every string; returns the new value and what it found, with where. */
86export function redactDeep(value: unknown, tagOf: (v: string) => string, allowed: ReadonlySet<string>, path = ''): { value: unknown; hits: (Hit & { tag: string; where: string })[] } {
87  if (typeof value === 'string') {
88    const r = redact(value, tagOf, allowed)
89    return { value: r.text, hits: r.hits.map(h => ({ ...h, where: path || 'output' })) }
90  }
91  if (Array.isArray(value)) {
92    const hits: (Hit & { tag: string; where: string })[] = []
93    const out = value.map((v, i) => {
94      const r = redactDeep(v, tagOf, allowed, path ? `${path}.${i}` : String(i))
95      hits.push(...r.hits)
96      return r.value
97    })
98    return { value: hits.length ? out : value, hits }
99  }
100  if (value && typeof value === 'object') {
101    const hits: (Hit & { tag: string; where: string })[] = []
102    const out: Record<string, unknown> = {}
103    for (const [k, v] of Object.entries(value)) {
104      const r = redactDeep(v, tagOf, allowed, path ? `${path}.${k}` : k)
105      hits.push(...r.hits)
106      out[k] = r.value
107    }
108    return { value: hits.length ? out : value, hits }
109  }
110  return { value, hits: [] }
111}
112
113/** Every string in a value, joined: what gets scanned and hashed. */
114export function strings(value: unknown, out: string[] = []): string[] {
115  if (typeof value === 'string') out.push(value)
116  else if (Array.isArray(value)) value.forEach(v => strings(v, out))
117  else if (value && typeof value === 'object') Object.values(value).forEach(v => strings(v, out))
118  return out
119}
120
121/** A note for commands that tend to print secrets, or null. */
122export function riskyCommand(command: string): string | null {
123  if (/\bdocker\s+(container\s+)?inspect\b/.test(command) && !/--format|-f\s/.test(command)) return 'docker inspect prints every environment variable, keys included; use --format with only the fields you need.'
124  if (/(^|[\s;&|])(printenv|env)(\s*($|[|;&]))/.test(command)) return 'printenv/env prints every variable, tokens included; print only the variable names (env | cut -d= -f1) or test the one you need.'
125  if (/\b(cat|less|head|tail|bat|grep)\b[^|;&]*\.env(\.[a-z]+)?\b/.test(command)) return '.env files hold secrets; read only the names (cut -d= -f1) unless a value is truly needed.'
126  if (/config\.xml\b/.test(command) && /(radarr|sonarr|prowlarr|lidarr|readarr|bazarr)/i.test(command)) return "An Arr config.xml holds the instance's ApiKey; grep for the fields you need with the key left out."
127  return null
128}
129
130export const glob = (pattern: string, s: string): boolean =>
131  new RegExp('^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$').test(s)
132
133/** FNV-1a as 8 hex digits: a stable tag for a value, never the value. */
134export function tag(value: string): string {
135  let h = 2166136261
136  for (let i = 0; i < value.length; i++) h = Math.imul(h ^ value.charCodeAt(i), 16777619) >>> 0
137  return h.toString(16).padStart(8, '0')
138}
139

1export type Finding = {
2  kind: string
3  tool: string
4  /** Where in the output: the field path (stdout, content.0.text). */
5  where: string
6  length: number
7  /** An 8-hex-digit FNV-1a tag of the value (never the value): what /keymaster allow takes. */
8  tag: string
9  at: number
10}
11
12declare module 'claude-code' {
13  interface PluginState {
14    keymaster: {
15      findings: Finding[]
16    }
17  }
18}
19