sql-guard

1import type { EngineInterface, Register, RenderInput } from 'claude-code';
2
3import { classify, envDatabaseHost, hostsIn, isLocalHost, maskSecrets, type Risk } from './rules';
4
5const PANE_ID = 'sql-guard';
6const POLL_MS = 250;
7const HOLD_LIMIT_MS = 10 * 60 * 1000;
8
9type Held = { risk: Risk; command: string; target: string; decision: 'proceed' | 'cancel' | null; where: 'pane' | 'band' };
10
11let held: Held | null = null;
12
13// The database a command reaches: hosts it names, else DATABASE_URL in the project's .env files.
14async function targetOf($: EngineInterface, command: string): Promise<string[]> {
15  const named = hostsIn(command);
16  if (named.length > 0) return named;
17  const cwd = await $.session.cwd();
18  for (const file of ['.env.local', '.env']) {
19    const text = await $.fs.read(`${cwd}/${file}`).catch(() => null);
20    const host = text === null ? undefined : envDatabaseHost(text);
21    if (host !== undefined) return [host];
22  }
23  return [];
24}
25
26export const register: Register = on => {
27  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
28    const risk = classify(e.command);
29    if (risk === null) return next(e);
30
31    const hosts = await targetOf($, e.command);
32    // Every host local: a development database, nothing to hold. No host found: assume it may be production.
33    if (hosts.length > 0 && hosts.every(isLocalHost)) return next(e);
34
35    while (held !== null) {
36      if (next.signal.aborted) return { deny: `${$.plugin.name}: the turn was interrupted while another database write waited. Nothing ran.` };
37      await $.clock.sleep(POLL_MS);
38    }
39    const mine: Held = {
40      risk,
41      command: maskSecrets(e.command).slice(0, 400),
42      target: hosts.length > 0 ? hosts.join(', ') : 'unknown (no host in the command or .env)',
43      decision: null,
44      where: 'pane',
45    };
46    held = mine;
47
48    let opened = { isPlaced: false };
49    let outcome: 'proceed' | 'cancel' | 'timeout' | 'interrupted' = 'timeout';
50    try {
51      opened = await $.ui.open({ id: PANE_ID, title: 'Database write', focus: true });
52      if (!opened.isPlaced) mine.where = 'band';
53      $.ui.invalidate('ui.render');
54      $.ui.toast(`${$.plugin.name}: ${risk.label} waits for your OK`);
55      const startedAt = await $.clock.now();
56      while (mine.decision === null && !next.signal.aborted && (await $.clock.now()) - startedAt <= HOLD_LIMIT_MS) {
57        await $.clock.sleep(POLL_MS);
58      }
59      outcome = mine.decision ?? (next.signal.aborted ? 'interrupted' : 'timeout');
60    } finally {
61      if (opened.isPlaced) await $.ui.close({ id: PANE_ID }).catch(() => undefined);
62      if (held === mine) held = null;
63      $.ui.invalidate('ui.render');
64    }
65
66    if (outcome === 'proceed') return next(e);
67    const why = { cancel: 'the user pressed Cancel', timeout: 'no answer within 10 minutes', interrupted: 'the turn was interrupted' }[outcome];
68    return { deny: `${$.plugin.name}: the ${risk.label} against ${mine.target} did not run: ${why}. Do not retry it unless the user asks.` };
69  }).catch(($, e, next) => (next.called ? next(e) : { deny: `${$.plugin.name}: the guard failed, so the database command did not run.` }));
70
71  on('ui.render', { component: 'Pane', requestId: PANE_ID }, ($, e, next) => (held === null ? next(e) : draw($, e, held)));
72  on('ui.render', { component: 'AbovePrompt' }, ($, e, next) => (held === null || held.where !== 'band' ? next(e) : draw($, e, held)));
73};
74
75function draw($: EngineInterface, e: RenderInput<'Pane' | 'AbovePrompt'>, call: Held) {
76  const { Box, Button, Text } = $.ui.resolve(e);
77  const decide = (decision: 'proceed' | 'cancel') => () => {
78    call.decision = decision;
79    $.ui.invalidate('ui.render');
80  };
81  return (
82    <Box flexDirection="column" borderStyle="round" borderColor="#ef4444" paddingX={1}>
83      <Text bold color="#ef4444">
84        Database write: {call.risk.label}
85      </Text>
86      <Text>Target: {call.target}</Text>
87      <Text dimColor wrap="wrap">
88        {call.command}
89      </Text>
90      <Box gap={1} marginTop={1}>
91        <Button key="proceed" label="Proceed" onPress={decide('proceed')} />
92        <Button key="cancel" label="Cancel" onPress={decide('cancel')} />
93      </Box>
94    </Box>
95  );
96}
97

1// Which shell commands write to a database, and whether that database is local. Pure, so the tests call it directly.
2
3export type Risk = { kind: 'sql-write' | 'sql-file' | 'migration'; label: string };
4
5const PSQL = /(^|[\s/;&|(])psql(\s|$)/;
6const WRITE_SQL =
7  /\b(insert\s+into|update\s+\w|delete\s+from|drop\s+(table|schema|database|index|view|column|type)|truncate\b|alter\s+(table|schema|database|type)|create\s+(table|schema|database|index|unique|type)|grant\b|revoke\b)/i;
8const SQL_FILE = /\s(-f|--file)(\s|=)|<\s*\S+\.sql\b|<<\s*['"]?\w+/;
9const MIGRATION = /\b(drizzle-kit\s+(push|migrate|drop)|bun\s+run\s+(db:)?(push|migrate)\b|bun\s+run\s+db:(reset|seed)\b)/;
10
11export function classify(command: string): Risk | null {
12  if (MIGRATION.test(command)) {
13    return { kind: 'migration', label: 'schema migration' };
14  }
15  if (!PSQL.test(command)) {
16    return null;
17  }
18  const write = WRITE_SQL.exec(command);
19  if (write !== null) {
20    return { kind: 'sql-write', label: write[0].replace(/\s+/g, ' ').toUpperCase() };
21  }
22  if (SQL_FILE.test(command)) {
23    return { kind: 'sql-file', label: 'SQL from a file or heredoc' };
24  }
25  return null;
26}
27
28// A host with no dot (`db`, `postgres`) is a Docker Compose service name: a managed database always has a domain.
29const LOCAL_HOST = /^(localhost|127\.\d+\.\d+\.\d+|\[?::1\]?|0\.0\.0\.0|host\.docker\.internal|[\w-]+\.localhost|[a-z][\w-]*)$/i;
30
31export const isLocalHost = (host: string): boolean => LOCAL_HOST.test(host);
32
33/** Database hosts named in a command: postgres URLs, psql -h/--host, PGHOST=. */
34export function hostsIn(command: string): string[] {
35  const hosts: string[] = [];
36  for (const match of command.matchAll(/postgres(?:ql)?:\/\/(?:[^@\s/'"]*@)?(\[[^\]]+\]|[^:/\s?'"]+)/g)) hosts.push(match[1] ?? '');
37  for (const match of command.matchAll(/(?:\s-h\s*|--host[=\s])['"]?([\w.:-]+)/g)) hosts.push(match[1] ?? '');
38  for (const match of command.matchAll(/\bPGHOST=['"]?([\w.:-]+)/g)) hosts.push(match[1] ?? '');
39  return hosts.filter(host => host !== '');
40}
41
42/** The host in a DATABASE_URL line of a .env file, if any. */
43export function envDatabaseHost(envFile: string): string | undefined {
44  const line = envFile.split('\n').find(row => /^\s*(export\s+)?DATABASE_URL\s*=/.test(row));
45  return line === undefined ? undefined : hostsIn(line)[0];
46}
47
48/** A command for display, with any URL password hidden. */
49export const maskSecrets = (command: string): string =>
50  command.replace(/(postgres(?:ql)?:\/\/[^:@\s/]+):[^@\s]+@/g, '$1:***@').replace(/\bPGPASSWORD=\S+/g, 'PGPASSWORD=***');
51