redact-secrets

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, RenderChildren } from 'claude-code'
3
4// National ID numbers, switched on per country by the `countries` option.
5export const NATIONAL_IDS: Record<string, RegExp> = {
6  IT: /\b[A-Z]{6}\d{2}[A-EHLMPR-T]\d{2}[A-Z]\d{3}[A-Z]\b/gi, // codice fiscale
7  US: /\b\d{3}-\d{2}-\d{4}\b/g, // SSN
8  GB: /\b[A-CEGHJ-PR-TW-Z]{2} ?\d{2} ?\d{2} ?\d{2} ?[A-D]\b/g, // National Insurance number
9  ES: /\b(?:\d{8}|[XYZ]\d{7})[A-Z]\b/g, // DNI / NIE
10  FR: /\b[12] ?\d{2} ?\d{2} ?(?:\d{2}|2[AB]) ?\d{3} ?\d{3} ?\d{2}\b/g, // NIR (sécurité sociale)
11  BR: /\b\d{3}\.\d{3}\.\d{3}-\d{2}\b/g, // CPF
12  IN: /\b[A-Z]{5}\d{4}[A-Z]\b/g, // PAN (Aadhaar's 12 digits are caught as a number)
13  MX: /\b[A-Z]{4}\d{6}[HM][A-Z]{5}[A-Z0-9]\d\b/g, // CURP
14  CN: /\b\d{17}[\dX]\b/g, // resident identity card
15}
16
17// Run before national IDs, so no ID pattern takes a piece of a key.
18const SECRETS: [string, RegExp][] = [
19  ['key', /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g],
20  ['key', /(?<=\bBearer\s+)[A-Za-z0-9._~+\/-]{16,}=*/g],
21  // A digit, +, / or = sets base64 credentials apart from prose like "Basic Authentication".
22  ['key', /(?<=\bBasic\s+)(?=[A-Za-z0-9+\/]*[\d+\/=])[A-Za-z0-9+\/]{8,}=*/g],
23  ['key', /\b(?:sk-[A-Za-z0-9_-]{16,}|sk-ant-[A-Za-z0-9_-]{16,}|[rs]k_(?:live|test)_[A-Za-z0-9]{10,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|glpat-[A-Za-z0-9_-]{20,}|SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}|(?:AKIA|ASIA)[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{35}|xox[abposre]-[A-Za-z0-9-]{10,}|eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}|[A-Za-z0-9_-]*(?=[A-Za-z0-9_-]*\d)(?=[A-Za-z0-9_-]*[A-Za-z])[A-Za-z0-9_-]{32,})\b/g],
24  // The password in scheme://user:password@host.
25  ['secret', /(?<=:\/\/[^\s:@\/]*:)[^\s@\/]+(?=@)/g],
26  // The value of PASSWORD=…, "api_key": "…", client_secret: …; not env lookups like process.env.X or ${X}.
27  // (?<!⟦): the `secret:` label of a placeholder is not an assignment.
28  // (?<![a-z])pass: DB_PASS, not bypass or compass.
29  ['secret', /(?<=(?<!⟦)(?:passw(?:or)?d|(?<![a-z])pass\b|pwd|secret(?:[_-]?key)?|token|api[_-]?key|access[_-]?key|private[_-]?key)["']?\s*[:=]\s*["']?)(?![$%{(<⟦]|[A-Za-z_]\w*[.([])[^\s"'`,;]{4,}/gi],
30]
31
32// Dates, times, IPv4 addresses and build numbers look like phone numbers but are not secret.
33// A build has a one-digit group inside (130.0.6723.91); dotted phones do not (06.12.34.56.78, 1.800.555.1234).
34const NOT_A_PHONE = /^(?:\d{4}([./-])\d{2}\1\d{2}|\d{1,2}([./-])\d{1,2}\2\d{4})(?: \d{1,2})?$|^\d{1,3}(?:\.\d{1,3}){3}$|^\d+(?:\.\d+)*\.\d(?:\.\d+)+$/
35
36// Git commit hashes, SHA-256 digests and UUIDs fill tool output and are not secret.
37const NOT_A_KEY = /^(?:[\da-f]{40}|[\da-f]{64}|[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12})$/i
38
39// Order matters: IBANs before phones, so their digits are not taken as a number.
40const PATTERNS: [string, RegExp][] = [
41  // \p{L}/\p{Nd}: international addresses (josé@müller.de) and non-Latin digits (Arabic, Persian, Devanagari).
42  ['email', /[\p{L}\p{N}._%+-]+@[\p{L}\p{N}.-]+\.\p{L}{2,}/gu],
43  ['bank_account', /\b[A-Z]{2}\d{2}(?: ?[A-Z0-9]{4}){3,7}(?: ?[A-Z0-9]{1,3})?\b/g],
44  ['card', /(?<!\p{Nd})(?:\p{Nd}[ -]?){13,19}(?!\p{Nd})/gu],
45  ['phone', /(?:\+|(?<!\p{Nd})00)?\(?\p{Nd}[\p{Nd} ().\/-]{6,}\p{Nd}(?!\p{Nd})/gu],
46]
47
48// Every card number passes the Luhn check; most timestamps and order numbers do not.
49const luhn = (digits: number[]) =>
50  digits.reverse().reduce((sum, d, i) => sum + (i % 2 ? (d * 2 > 9 ? d * 2 - 9 : d * 2) : d), 0) % 10 === 0
51
52// What the model and the transcript see in place of a secret: its first 3 characters.
53const MASK = /⟦(\w+):([^⟧]*)•••⟧/g
54
55// "all", or a list like "IT, us,GB": the countries whose national IDs are masked.
56export const countryIds = (countries: string) =>
57  countries.trim().toLowerCase() === 'all'
58    ? Object.values(NATIONAL_IDS)
59    : countries.toUpperCase().split(/[\s,;]+/).flatMap(c => NATIONAL_IDS[c] ?? [])
60
61export const redact = (text: string, ids: RegExp[] = Object.values(NATIONAL_IDS)) =>
62  [...SECRETS, ...ids.map(re => ['id', re] as [string, RegExp]), ...PATTERNS].reduce(
63    (t, [kind, re]) =>
64      t.replace(re, m =>
65        // Fewer than 8 digits is a year, a price, a count: left alone.
66        ((kind === 'card' || kind === 'phone' || kind === 'bank_account') && (m.match(/\p{Nd}/gu) ?? []).length < 8) ||
67        // A long number that fails Luhn is left for the phone pattern, which still masks it.
68        (kind === 'card' && !luhn((m.match(/\p{Nd}/gu) ?? []).map(d => +d))) ||
69        (kind === 'phone' && NOT_A_PHONE.test(m)) ||
70        (kind === 'key' && NOT_A_KEY.test(m))
71          ? m
72          : `⟦${kind}:${m.slice(0, 3)}•••⟧`,
73      ),
74    text,
75  )
76
77// Every string in a tool's result, but encoded images and PDFs (`base64`, MCP's `data`).
78export const redactDeep = (value: unknown, ids?: RegExp[]): unknown =>
79  typeof value === 'string'
80    ? redact(value, ids)
81    : Array.isArray(value)
82      ? value.map(v => redactDeep(v, ids))
83      : value && typeof value === 'object'
84        ? Object.fromEntries(
85            Object.entries(value).map(([k, v]) => [k, k === 'base64' || k === 'data' ? v : redactDeep(v, ids)]),
86          )
87        : value
88
89const placeholders = (text: string) => (text.match(MASK) ?? []).length
90
91// The placeholders `after` holds beyond those already in `before`, by kind, in order of appearance.
92export const maskedKinds = (before: string, after: string) => {
93  const counts: Record<string, number> = {}
94  for (const [, kind = ''] of after.matchAll(MASK)) counts[kind] = (counts[kind] ?? 0) + 1
95  for (const [, kind = ''] of before.matchAll(MASK)) counts[kind] = (counts[kind] ?? 0) - 1
96  return Object.fromEntries(Object.entries(counts).filter(([, n]) => n > 0))
97}
98
99// Tokyo Night palette; the `color` option picks one.
100export const COLORS: Record<string, string> = {
101  purple: '#bb9af7',
102  blue: '#7aa2f7',
103  cyan: '#7dcfff',
104  green: '#9ece6a',
105  yellow: '#e0af68',
106  orange: '#ff9e64',
107  red: '#f7768e',
108  pink: '#ff79c6',
109}
110
111// One neutral "label: n" form per language, so no plural rules are needed.
112const LABELS: Record<string, string> = {
113  en: 'Sensitive data masked before sending',
114  it: 'Dati sensibili oscurati prima dell\'invio',
115  es: 'Datos sensibles ocultados antes de enviar',
116  pt: 'Dados sensíveis ocultados antes do envio',
117  fr: 'Données sensibles masquées avant l\'envoi',
118  de: 'Sensible Daten vor dem Senden maskiert',
119  nl: 'Gevoelige gegevens gemaskeerd vóór verzending',
120  sv: 'Känsliga uppgifter maskerade före sändning',
121  da: 'Følsomme data maskeret før afsendelse',
122  no: 'Sensitive data maskert før sending',
123  nb: 'Sensitive data maskert før sending',
124  fi: 'Arkaluonteiset tiedot peitetty ennen lähetystä',
125  pl: 'Dane wrażliwe ukryte przed wysłaniem',
126  cs: 'Citlivé údaje skryty před odesláním',
127  ro: 'Date sensibile mascate înainte de trimitere',
128  hu: 'Érzékeny adatok elrejtve küldés előtt',
129  el: 'Ευαίσθητα δεδομένα αποκρύφθηκαν πριν την αποστολή',
130  ru: 'Конфиденциальные данные скрыты перед отправкой',
131  uk: 'Конфіденційні дані приховано перед надсиланням',
132  tr: 'Hassas veriler gönderilmeden önce gizlendi',
133  ar: 'تم إخفاء البيانات الحساسة قبل الإرسال',
134  he: 'מידע רגיש הוסתר לפני השליחה',
135  fa: 'داده‌های حساس پیش از ارسال پنهان شدند',
136  hi: 'भेजने से पहले संवेदनशील डेटा छिपाया गया',
137  bn: 'পাঠানোর আগে সংবেদনশীল তথ্য লুকানো হয়েছে',
138  ur: 'بھیجنے سے پہلے حساس ڈیٹا چھپا دیا گیا',
139  zh: '发送前已隐藏敏感数据',
140  ja: '送信前に機密データをマスクしました',
141  ko: '전송 전에 민감한 데이터를 가렸습니다',
142  id: 'Data sensitif disamarkan sebelum dikirim',
143  ms: 'Data sensitif disembunyikan sebelum dihantar',
144  vi: 'Đã ẩn dữ liệu nhạy cảm trước khi gửi',
145  th: 'ซ่อนข้อมูลที่ละเอียดอ่อนก่อนส่งแล้ว',
146  tl: 'Itinago ang sensitibong data bago ipadala',
147  sw: 'Data nyeti imefichwa kabla ya kutuma',
148}
149
150// One icon per kind, so the breakdown needs no translation.
151const ICONS: Record<string, string> = {
152  email: '📧',
153  phone: '📞',
154  key: '🔑',
155  secret: '🔐',
156  card: '💳',
157  bank_account: '🏦',
158  id: '🪪',
159}
160
161// "it_IT.UTF-8" / "pt-BR" -> "it" / "pt"; English when unknown.
162export const toastText = (locale: string | undefined, kinds: Record<string, number>) =>
163  `🔒 ${LABELS[(locale ?? '').toLowerCase().split(/[_.@-]/)[0] ?? ''] ?? LABELS.en}: ${Object.entries(kinds)
164    .map(([kind, n]) => `${ICONS[kind] ?? kind} ${n}`)
165    .join(' · ')}`
166
167// A toast naming what `after` masked beyond `before`; none when nothing was.
168const toast = async ($: EngineInterface, before: string, after: string) => {
169  const kinds = maskedKinds(before, after)
170  if (Object.keys(kinds).length === 0) return
171  const locale = (await $.env.get('LC_ALL')) || (await $.env.get('LC_MESSAGES')) || (await $.env.get('LANG'))
172  $.ui.toast(toastText(locale, kinds))
173}
174
175const isBannerShown = atom({ plugin: 'redact-secrets', key: 'isBannerShown' } as const, false)
176
177export const register: Register = (on, options) => {
178  const countries = String(options.countries ?? 'all')
179  const color = String(options.color ?? 'purple')
180  const ids = countryIds(countries)
181  const background = COLORS[color] ?? COLORS.purple
182
183  on('session.start', async ($, e, next) => {
184    await $.command.register({ name: 'redact-secrets', description: 'Show the redact-secrets banner and its settings' })
185    // The banner greets once, on the first session after install.
186    if (!(await $.store.get('welcomed'))) await update($, isBannerShown, () => true)
187    return next(e)
188  })
189
190  on('command.run', { command: 'redact-secrets' }, async $ => {
191    await update($, isBannerShown, () => true)
192    return { text: `redact-secrets: countries ${countries}, color ${color}` }
193  })
194
195  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
196    if (e.props.hasSurvey || !(await read($, isBannerShown))) return next(e)
197
198    const { Box, Button, Text } = $.ui.resolve(e)
199    return (
200      <Box flexDirection="row" gap={1}>
201        <Text color="#1a1b26" backgroundColor={background} bold>
202          {' ⟦•••⟧ '}
203        </Text>
204        <Box flexDirection="column">
205          <Text>
206            <Text bold>redact-secrets</Text>
207            <Text dimColor> · countries: {countries} · color: {color}</Text>
208          </Text>
209          <Text dimColor>Emails, phones, API keys, passwords, cards, IBANs and national IDs are masked before they are sent.</Text>
210        </Box>
211        <Button
212          key="dismiss"
213          label="Got it"
214          onPress={async () => {
215            await $.store.set('welcomed', true)
216            await update($, isBannerShown, () => false)
217          }}
218        />
219      </Box>
220    )
221  })
222
223  on('prompt.submit', async ($, e, next) => {
224    if (e.command) return next(e)
225    const text = redact(e.text, ids)
226    await toast($, e.text, text)
227    return next({ ...e, text })
228  }).catch(($, e, next) =>
229    // Fail closed: a prompt that could not be checked is not sent unmasked.
230    next.called ? next(e) : { drop: 'redact-secrets could not check this prompt, so it was not sent' },
231  )
232
233  // What a tool read or printed (a file, a command's output, a web page) reaches the model masked too.
234  on('tool.call', async ($, e, next) => {
235    const ran = await next(e)
236    if (ran.deny !== undefined || ran.isError) return ran
237    const before = JSON.stringify(ran.result) ?? ''
238    const result = redactDeep(ran.result, ids)
239    const after = JSON.stringify(result) ?? ''
240    if (after === before) return ran
241    await toast($, before, after)
242    return { result, context: ran.context }
243  }).catch(() =>
244    // Fail closed: the tool has run, but output that could not be checked is withheld.
245    ({ deny: 'redact-secrets could not check this output, so it was withheld' }),
246  )
247
248  // A placeholder is not the value it hides: writing one into a file would replace a real secret.
249  const guard = (path: string, before: string, after: string) =>
250    placeholders(after) > placeholders(before)
251      ? {
252          deny:
253            `redact-secrets: this would write a masked placeholder (⟦…•••⟧) into ${path}, ` +
254            'destroying the real value it stands for. Leave those lines untouched, or ask the user to edit them.',
255        }
256      : undefined
257
258  on('tool.call', { tool: 'Edit' }, ($, e, next) => guard(e.file_path, e.old_string, e.new_string) ?? next(e)).catch(
259    ($, e, next) => (next.called ? next(e) : { deny: 'redact-secrets could not check this edit' }),
260  )
261
262  on('tool.call', { tool: 'Write' }, async ($, e, next) => {
263    // A file that exists but cannot be read (permissions, over 4 MiB) cannot be checked: refused.
264    const current = (await $.fs.exists(e.file_path)) ? await $.fs.read(e.file_path).catch(() => undefined) : ''
265    if (current === undefined) return { deny: 'redact-secrets could not check this write' }
266    return guard(e.file_path, current, e.content) ?? next(e)
267  }).catch(($, e, next) => (next.called ? next(e) : { deny: 'redact-secrets could not check this write' }))
268
269  // A shell command can write too (sed -i, echo > .env), and what it touches cannot be known: any placeholder is refused.
270  on('tool.call', { tool: 'Bash' }, ($, e, next) =>
271    placeholders(e.command) > 0
272      ? {
273          deny:
274            'redact-secrets: this command carries a masked placeholder (⟦…•••⟧), which could be written over the real value it ' +
275            'stands for. Refer to the value through its file or an environment variable, or ask the user to run the command.',
276        }
277      : next(e),
278  ).catch(($, e, next) => (next.called ? next(e) : { deny: 'redact-secrets could not check this command' }))
279
280  on('ui.render', { component: 'UserMessage' }, ($, e, next) => {
281    const text = e.props.text
282    if (!text.includes('⟦')) return next(e)
283
284    const { Box, Text } = $.ui.resolve(e)
285    const parts: RenderChildren[] = []
286    let last = 0
287    for (const m of text.matchAll(MASK)) {
288      parts.push(text.slice(last, m.index))
289      parts.push(
290        <Text color="#1a1b26" backgroundColor={background} bold>
291          {` 🔒 ${m[2]}••• `}
292        </Text>,
293      )
294      last = m.index! + m[0].length
295    }
296    parts.push(text.slice(last))
297
298    return (
299      <Box>
300        <Text>
301          <Text dimColor>{'> '}</Text>
302          {parts}
303        </Text>
304      </Box>
305    )
306  })
307}
308

1declare module 'claude-code' {
2  interface PluginState {
3    'redact-secrets': { isBannerShown: boolean }
4  }
5}
6