cure-policy-guard

1import type { On } from 'claude-code'
2
3import { addedText, check, dependencyNames, parentDirs, targetPath, type Violation } from './rules'
4
5/**
6 * cure-policy-guard: refuses a file write that breaks a written Cure house
7 * rule, unless the person at the keyboard overrides it, and records every
8 * override.
9 *
10 * Scope: Claude's own Write / Edit / MultiEdit / NotebookEdit calls. A Bash
11 * command that writes a file (`cat > x`, `sed -i`) is not read here; the
12 * repos' CI and scanners remain the backstop for those.
13 *
14 * Fails closed on the question, open on the plumbing: if the person cannot be
15 * asked (headless, dismissed), the write is refused; if the repo or
16 * package.json cannot be read, the rules that need them see '' / [] and the
17 * path- and text-only rules still apply.
18 */
19
20const FILE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit'])
21const OVERRIDES_KEY = 'overrides'
22const MAX_OVERRIDES = 200
23
24type Override = { at: string; rule: string; path: string; repo: string }
25
26const REFUSE = 'Refuse the write'
27const ALLOW = 'Allow this once (logged)'
28
29export function register(on: On) {
30  on('session.start', async ($, e, next) => {
31    await $.command.register({
32      name: 'policy-guard',
33      description: 'Show the house rules the guard enforces and the recent overrides',
34    })
35    return next(e)
36  })
37
38  on('command.run', { command: 'policy-guard' }, async $ => {
39    const log = ((await $.store.get(OVERRIDES_KEY)) as Override[] | undefined) ?? []
40    const recent = log.slice(-10).reverse()
41    const lines = [
42      'cure-policy-guard rules: no-cron · level5-vertex-only · minors-new-ai-vendor · hardcoded-secret',
43      recent.length === 0
44        ? 'No overrides recorded.'
45        : 'Recent overrides:\n' +
46          recent.map(o => `  ${o.at}  ${o.rule}  ${o.repo}  ${o.path}`).join('\n'),
47    ]
48    return { text: lines.join('\n') }
49  })
50
51  on('tool.call', async ($, e, next) => {
52    if (!FILE_TOOLS.has(String(e.tool))) return next(e)
53    const path = targetPath(e)
54    const added = addedText(e)
55    if (!path || !added) return next(e)
56
57    const { repo, root } = await locateRepo($, path)
58    const deps = await nearestDependencies($, path, root)
59    const violations = check({ path, repo, added, deps })
60    if (violations.length === 0) return next(e)
61
62    const summary = violations.map(v => `[${v.rule}] ${v.reason}`).join('\n')
63    let answer: string
64    try {
65      answer = await $.ui.ask(
66        `cure-policy-guard: this ${String(e.tool)} to ${shortPath(path)} breaks a house rule:\n${summary}\nAllow it anyway?`,
67        { options: [REFUSE, ALLOW], header: 'House rule' },
68      )
69    } catch {
70      return { deny: denial(violations, 'nobody could be asked to override it') }
71    }
72    if (answer !== ALLOW) return { deny: denial(violations, 'the user refused it') }
73
74    await recordOverride($, violations, path, repo)
75    $.ui.log(`cure-policy-guard: override recorded for ${violations.map(v => v.rule).join(', ')} on ${shortPath(path)}`)
76    return next(e)
77  })
78}
79
80function denial(violations: Violation[], why: string): string {
81  return (
82    `Blocked by cure-policy-guard (${why}). ` +
83    violations.map(v => `${v.rule}: ${v.reason} Source: ${v.source}.`).join(' ') +
84    ' Do not retry the same write; change the approach or ask the user.'
85  )
86}
87
88export const shortPath = (p: string, maxLen = 38): string => {
89  const parts = p.split('/').filter(Boolean)
90  const tail = parts.slice(-3).join('/')
91  if (tail.length <= maxLen) return tail
92  const filename = parts[parts.length - 1] ?? ''
93  if (parts.length <= 2) return tail
94  const dir = parts[parts.length - 2] ?? ''
95  const mid = `.../${dir}/${filename}`
96  return mid.length <= maxLen ? mid : `.../${filename}`
97}
98
99/** The repository's name (main checkout's directory, also from a worktree) and root. */
100async function locateRepo($: any, path: string): Promise<{ repo: string; root: string }> {
101  try {
102    const dir = await firstExistingDir($, path)
103    if (!dir) return { repo: '', root: '' }
104    const common = await $.process.run(['git', '-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir'])
105    const top = await $.process.run(['git', '-C', dir, 'rev-parse', '--show-toplevel'])
106    if (common.exitCode !== 0 || top.exitCode !== 0) return { repo: '', root: '' }
107    const commonDir = common.stdout.trim().replace(/\/$/, '')
108    const repoDir = commonDir.endsWith('/.git') ? commonDir.slice(0, -5) : commonDir
109    return { repo: repoDir.split('/').pop() ?? '', root: top.stdout.trim() }
110  } catch {
111    return { repo: '', root: '' }
112  }
113}
114
115async function firstExistingDir($: any, path: string): Promise<string | undefined> {
116  for (const dir of parentDirs(path)) {
117    if (await $.fs.exists(dir)) return dir
118  }
119  return undefined
120}
121
122/** Dependencies of the nearest package.json between the file and the repo root. */
123async function nearestDependencies($: any, path: string, root: string): Promise<string[]> {
124  if (!root) return []
125  try {
126    for (const dir of parentDirs(path)) {
127      if (!dir.startsWith(root)) break
128      const pkg = `${dir}/package.json`
129      if (await $.fs.exists(pkg)) return dependencyNames(await $.fs.read(pkg))
130    }
131  } catch {
132    // unreadable: treat as no dependencies, which makes the vendor rule stricter
133  }
134  return []
135}
136
137async function recordOverride($: any, violations: Violation[], path: string, repo: string) {
138  const log = ((await $.store.get(OVERRIDES_KEY)) as Override[] | undefined) ?? []
139  const at = new Date(await $.clock.now()).toISOString()
140  for (const v of violations) log.push({ at, rule: v.rule, path, repo })
141  await $.store.set(OVERRIDES_KEY, log.slice(-MAX_OVERRIDES))
142}
143

1/**
2 * The house rules the guard enforces, as pure functions of one file write.
3 *
4 * Each rule comes from a decision already written down in a Cure repo; the
5 * `source` says where, so a refusal can be traced to the rule and argued with.
6 * Rules look only at text a write ADDS, so an edit that leaves an existing
7 * violation alone is not blocked here (the repo's own CI owns old debt).
8 */
9
10export type Write = {
11  /** Absolute path of the file being written. */
12  path: string
13  /** Basename of the git repository root holding the file, or '' outside one. */
14  repo: string
15  /** The text this write introduces (whole file for Write, new_string for Edit). */
16  added: string
17  /** Dependency names in the nearest package.json, if one was found. */
18  deps: readonly string[]
19}
20
21export type Violation = {
22  rule: string
23  reason: string
24  source: string
25}
26
27const isEnvFile = (path: string) => /(^|\/)\.env(\.[^/]*)?$/.test(path)
28
29/** Org policy since 2026-08-08: no `schedule:` trigger in any workflow. */
30export function noCron(w: Write): Violation | undefined {
31  if (!/(^|\/)\.github\/workflows\/[^/]+\.ya?ml$/.test(w.path)) return undefined
32  if (!/^\s*schedule\s*:/m.test(w.added)) return undefined
33  return {
34    rule: 'no-cron',
35    reason:
36      'adds a `schedule:` trigger to a workflow. Org policy since 2026-08-08 bans cron in GitHub Actions; use push, PR, dispatch or an age gate on a push trigger instead.',
37    source: 'DistrictZero/CLAUDE.md "No cron. Org policy since 2026-08-08"; github_policy scanner',
38  }
39}
40
41const CONSUMER_GEMINI = /@google\/generative-ai\b|generativelanguage\.googleapis\.com|\bGEMINI_API_KEY\b/
42
43/** Level5 handles PHI: Gemini only through Vertex AI under the GCP BAA. */
44export function level5VertexOnly(w: Write): Violation | undefined {
45  if (w.repo !== 'Level5') return undefined
46  const hit = CONSUMER_GEMINI.exec(w.added)
47  if (!hit) return undefined
48  return {
49    rule: 'level5-vertex-only',
50    reason: `introduces \`${hit[0]}\`, the consumer Gemini API path. Level5 processes PHI, and only Vertex AI is covered by the Google Cloud BAA.`,
51    source: 'Level5/docs/compliance/BAA_INVENTORY.md:33-34, :48',
52  }
53}
54
55/** Repos whose data is about minors or students (COPPA/FERPA-adjacent). */
56export const MINORS_REPOS: ReadonlySet<string> = new Set([
57  'initiated-recruiting',
58  'initiated-recruiting-nil',
59  'SPEDTECH',
60  'LearnLift',
61  'iep-and-thrive',
62])
63
64/** Model-vendor SDKs, as an import names them. */
65export const AI_VENDOR_PACKAGES: readonly string[] = [
66  'openai',
67  '@anthropic-ai/sdk',
68  '@google/genai',
69  '@google/generative-ai',
70  '@google-cloud/vertexai',
71  'cohere-ai',
72  '@mistralai/mistralai',
73  'groq-sdk',
74  'together-ai',
75  'replicate',
76  '@typesafe-ai/sdk',
77  'typesafe',
78]
79
80const importedPackages = (text: string): string[] => {
81  const found = new Set<string>()
82  const re = /(?:from\s+|require\(\s*|import\(\s*|import\s+)['"]([^'"]+)['"]/g
83  for (const m of text.matchAll(re)) {
84    const spec = m[1]
85    const name = spec.startsWith('@') ? spec.split('/').slice(0, 2).join('/') : spec.split('/')[0]
86    found.add(name)
87  }
88  return [...found]
89}
90
91/** A new AI vendor in a minors' repo needs a decision, not a default. */
92export function minorsNewAiVendor(w: Write): Violation | undefined {
93  if (!MINORS_REPOS.has(w.repo)) return undefined
94  const added = importedPackages(w.added).filter(
95    p => AI_VENDOR_PACKAGES.includes(p) && !w.deps.includes(p),
96  )
97  if (added.length === 0) return undefined
98  return {
99    rule: 'minors-new-ai-vendor',
100    reason: `imports ${added.map(p => `\`${p}\``).join(', ')}, an AI vendor this repo does not already depend on. ${w.repo} handles data about minors or students; a new processor needs a data-processing decision first (several vendors, TypeSafe among them, exclude under-18 data by policy).`,
101    source: 'Jev / AI-vendor review 2026-10-04; SPEDTECH privacy page "de-identified prompts only"',
102  }
103}
104
105const SECRET_PATTERNS: readonly [string, RegExp][] = [
106  ['Google API key', /AIza[0-9A-Za-z_-]{35}/],
107  ['Anthropic API key', /sk-ant-[0-9A-Za-z_-]{20,}/],
108  ['OpenAI API key', /\bsk-(?:proj-)?[0-9A-Za-z_-]{32,}/],
109  ['GitHub token', /\b(?:ghp|gho|ghs|ghu)_[0-9A-Za-z]{36}\b|\bgithub_pat_[0-9A-Za-z_]{40,}/],
110  ['Stripe secret key', /\b(?:sk|rk)_live_[0-9A-Za-z]{20,}/],
111  ['private key', /-----BEGIN (?:RSA |EC |OPENSSH |)PRIVATE KEY-----/],
112  ['service-account key', /"private_key"\s*:\s*"-----BEGIN/],
113]
114
115/** A credential literal in a tracked file. `.env*` files are where keys belong. */
116export function hardcodedSecret(w: Write): Violation | undefined {
117  if (isEnvFile(w.path)) return undefined
118  for (const [kind, re] of SECRET_PATTERNS) {
119    if (re.test(w.added)) {
120      return {
121        rule: 'hardcoded-secret',
122        reason: `writes what looks like a ${kind} into ${w.path.split('/').pop()}. Keep credentials in Secret Manager, a GitHub secret or a gitignored .env, and read them at run time.`,
123        source: 'TIR scripts/data-fixes/*.js shipped a hard-coded Gemini key (found 2026-10-04)',
124      }
125    }
126  }
127  return undefined
128}
129
130export const RULES = [noCron, level5VertexOnly, minorsNewAiVendor, hardcodedSecret] as const
131
132/** Every rule the write breaks, in RULES order. */
133export function check(w: Write): Violation[] {
134  return RULES.map(rule => rule(w)).filter((v): v is Violation => v !== undefined)
135}
136
137/** The text a built-in file tool call adds; '' for a call this guard does not read. */
138export function addedText(e: Record<string, unknown>): string {
139  const str = (v: unknown) => (typeof v === 'string' ? v : '')
140  switch (e.tool) {
141    case 'Write':
142      return str(e.content)
143    case 'Edit':
144      return str(e.new_string)
145    case 'MultiEdit':
146      return Array.isArray(e.edits)
147        ? e.edits.map(x => str((x as Record<string, unknown>)?.new_string)).join('\n')
148        : ''
149    case 'NotebookEdit':
150      return str(e.new_source)
151    default:
152      return ''
153  }
154}
155
156/** The path a built-in file tool call writes; '' when it names none. */
157export function targetPath(e: Record<string, unknown>): string {
158  const p = e.file_path ?? e.notebook_path
159  return typeof p === 'string' ? p : ''
160}
161
162/** Dependency names from a package.json's text; [] when it does not parse. */
163export function dependencyNames(packageJson: string | undefined): string[] {
164  if (!packageJson) return []
165  try {
166    const pkg = JSON.parse(packageJson) as Record<string, Record<string, string> | undefined>
167    return [
168      ...Object.keys(pkg.dependencies ?? {}),
169      ...Object.keys(pkg.devDependencies ?? {}),
170      ...Object.keys(pkg.optionalDependencies ?? {}),
171      ...Object.keys(pkg.peerDependencies ?? {}),
172    ]
173  } catch {
174    return []
175  }
176}
177
178/** The directories above a path, nearest first, ending at '/'. */
179export function parentDirs(path: string): string[] {
180  const out: string[] = []
181  let dir = path.replace(/\/+$/, '')
182  while (dir.includes('/')) {
183    dir = dir.slice(0, dir.lastIndexOf('/'))
184    out.push(dir === '' ? '/' : dir)
185    if (dir === '') break
186  }
187  return out
188}
189