@fatelabs/pi-estelle 0.0.0-stage → 0.0.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/LICENSE +201 -0
  2. package/NOTICE +6 -0
  3. package/README.md +44 -2
  4. package/adapters/claude.mjs +17 -0
  5. package/adapters/codex.mjs +85 -0
  6. package/adapters/cursor.mjs +66 -0
  7. package/adapters/dsh-host.mjs +181 -0
  8. package/adapters/dsh-plugin.mjs +11 -0
  9. package/adapters/dsh.mjs +54 -0
  10. package/adapters/grok.mjs +63 -0
  11. package/adapters/host-bridge.mjs +85 -0
  12. package/adapters/kimi.mjs +135 -0
  13. package/adapters/opencode-mirror.mjs +103 -0
  14. package/adapters/opencode-plugin.mjs +143 -0
  15. package/adapters/opencode.mjs +15 -0
  16. package/adapters/pi-extension.mjs +107 -0
  17. package/adapters/pi.mjs +13 -0
  18. package/adapters/plugin-envelope.mjs +56 -0
  19. package/commands/cloud.md +28 -0
  20. package/commands/code.md +6 -0
  21. package/commands/handoff.md +25 -0
  22. package/commands/monitor.md +6 -0
  23. package/commands/resume.md +6 -0
  24. package/commands/review.md +6 -0
  25. package/commands/rooms.md +7 -0
  26. package/instructions.md +19 -0
  27. package/package.json +38 -4
  28. package/runtime/auth.mjs +27 -0
  29. package/runtime/checkpoint.mjs +208 -0
  30. package/runtime/claude-setup.mjs +130 -0
  31. package/runtime/cli.mjs +112 -0
  32. package/runtime/codex-trust.mjs +68 -0
  33. package/runtime/credential.mjs +341 -0
  34. package/runtime/dsh-session.mjs +91 -0
  35. package/runtime/dsh-telemetry.mjs +31 -0
  36. package/runtime/hooks.mjs +234 -0
  37. package/runtime/identity.mjs +20 -0
  38. package/runtime/io.mjs +155 -0
  39. package/runtime/key-check.mjs +51 -0
  40. package/runtime/kimi-history.mjs +163 -0
  41. package/runtime/mailbox.mjs +46 -0
  42. package/runtime/migration.mjs +118 -0
  43. package/runtime/move.mjs +443 -0
  44. package/runtime/native-export.mjs +204 -0
  45. package/runtime/native-index.mjs +77 -0
  46. package/runtime/native-tree.mjs +117 -0
  47. package/runtime/queued-context.mjs +152 -0
  48. package/runtime/redact.mjs +74 -0
  49. package/runtime/reindex.mjs +259 -0
  50. package/runtime/setup.mjs +174 -0
  51. package/runtime/stream.mjs +755 -0
  52. package/runtime/version.mjs +2 -0
  53. package/runtime/write-warning.mjs +67 -0
  54. package/skills/abstain-right/SKILL.md +19 -0
  55. package/skills/api-call-ground/SKILL.md +19 -0
  56. package/skills/bug-hunt/SKILL.md +20 -0
  57. package/skills/chain-of-verification/SKILL.md +19 -0
  58. package/skills/change-impact/SKILL.md +19 -0
  59. package/skills/coding-workflow/SKILL.md +20 -0
  60. package/skills/commit-guard/SKILL.md +20 -0
  61. package/skills/context-checkpoint/SKILL.md +19 -0
  62. package/skills/continuity-brief/SKILL.md +19 -0
  63. package/skills/dead-code-sweep/SKILL.md +19 -0
  64. package/skills/deep-search/SKILL.md +19 -0
  65. package/skills/diff-review/SKILL.md +19 -0
  66. package/skills/estelle/SKILL.md +119 -0
  67. package/skills/estelle-loop/SKILL.md +19 -0
  68. package/skills/estelle-monitor-install/SKILL.md +20 -0
  69. package/skills/evidence-traceability-audit/SKILL.md +19 -0
  70. package/skills/grounded-generate/SKILL.md +19 -0
  71. package/skills/incident-rca/SKILL.md +20 -0
  72. package/skills/mutation-test/SKILL.md +19 -0
  73. package/skills/program-repair/SKILL.md +20 -0
  74. package/skills/prompt-injection-defense/SKILL.md +19 -0
  75. package/skills/property-based-test/SKILL.md +19 -0
  76. package/skills/refactor-rfc/SKILL.md +19 -0
  77. package/skills/root-cause-loop/SKILL.md +19 -0
  78. package/skills/test-first/SKILL.md +19 -0
  79. package/skills/threat-model-stride/SKILL.md +19 -0
@@ -0,0 +1,130 @@
1
+ /** Claude Code setup has one path: an old install migrates, and no old install is a fresh one. */
2
+ import { execFile } from 'node:child_process';
3
+ import { createHash } from 'node:crypto';
4
+ import { open } from 'node:fs/promises';
5
+ import { homedir } from 'node:os';
6
+ import { join, resolve } from 'node:path';
7
+ import { checkKey, KEY_MESSAGES } from './key-check.mjs';
8
+ import { commitHooks, inspectHooks, planHooks } from './migration.mjs';
9
+ import { VERSION } from './version.mjs';
10
+
11
+ export const OLD_PLUGIN = 'estelle@fatelabs', NEW_PLUGIN = 'estelle@estelle-plugins';
12
+ const LIST_BYTES = 262144, CALL_MS = 15000, RC_BYTES = 262144, MAX_LISTED_PLUGINS = 1024;
13
+ const COMMANDS = Object.freeze({ list: ['plugin', 'list', '--json'],
14
+ // --keep-data: the old plugin's saved data stays on disk, and `user` is the only scope setup may change.
15
+ uninstall: ['plugin', 'uninstall', OLD_PLUGIN, '--keep-data', '--json', '--scope', 'user'] });
16
+ const RC_FILES = Object.freeze(['.zshenv', '.zprofile', '.zshrc', '.zlogin', '.bash_profile', '.bashrc', '.profile']);
17
+ const EXPORT_LINE = /^[ \t]*(?:export[ \t]+)?ESTELLE_API_KEY=/gm;
18
+
19
+ function nativeClaude(operation) {
20
+ return new Promise(done => {
21
+ execFile('claude', COMMANDS[operation], { timeout: CALL_MS, maxBuffer: LIST_BYTES, windowsHide: true },
22
+ (error, stdout) => done(error ? { ok: false, text: stdout || '' } : { ok: true, text: stdout }));
23
+ });
24
+ }
25
+
26
+ /** The plugins Claude Code reports. Throws on any row without an id: non-empty is not correctly parsed. */
27
+ function parseList(text) {
28
+ const items = JSON.parse(text);
29
+ if (!Array.isArray(items) || items.length > MAX_LISTED_PLUGINS) throw new Error('plugin_list_shape');
30
+ if (!items.every(item => typeof item?.id === 'string' && typeof item?.scope === 'string')) throw new Error('plugin_list_shape');
31
+ return items;
32
+ }
33
+
34
+ const scopesOf = (items, id) => items.filter(item => item.id === id).map(item => item.scope);
35
+
36
+ /** How many times shell startup files set the key. A count and file names only; the contents never leave this function.
37
+ * A warning, not a proof: a file past RC_BYTES is read in part, so null means none were found, not that none exist. */
38
+ export async function duplicateKeyExports(home) {
39
+ const found = [];
40
+ let count = 0;
41
+ for (const name of RC_FILES) {
42
+ const file = await open(join(home, name), 'r').catch(() => null);
43
+ if (!file) continue;
44
+ try {
45
+ const bytes = Buffer.alloc(RC_BYTES), { bytesRead } = await file.read(bytes, 0, RC_BYTES, 0);
46
+ const hits = (bytes.subarray(0, bytesRead).toString('utf8').match(EXPORT_LINE) || []).length;
47
+ if (hits) { count += hits; found.push(name); }
48
+ } catch { /* an unreadable file is not a duplicate */ } finally { await file.close(); }
49
+ }
50
+ if (count < 2) return null;
51
+ return { exports: count, files: found,
52
+ message: `ESTELLE_API_KEY is set ${count} times in ${found.join(', ')}. Your shell keeps the last one it reads, so hooks may use a different key or account than you expect. Keep one.` };
53
+ }
54
+
55
+ async function accountFields(env, home, check) {
56
+ const duplicate = await duplicateKeyExports(home);
57
+ const key = env.ESTELLE_API_KEY;
58
+ const keyCheck = key ? await check(key) : null;
59
+ return { capture_auth: key ? 'environment_key' : 'off_no_key',
60
+ ...(keyCheck ? { key_check: keyCheck, key_message: KEY_MESSAGES[keyCheck] } : {}),
61
+ ...(duplicate ? { duplicate_key: duplicate } : {}) };
62
+ }
63
+
64
+ const report = (status, fields = {}) => ({ status, host: 'claude', version: VERSION, ...fields,
65
+ mcp_auth: 'oauth_in_claude_not_probed', accounts_match: 'not_proved', hook_execution: 'not_observed',
66
+ trust: 'not_changed_not_measured', reload: 'fresh_session_required' });
67
+
68
+ const next = capture => ['Restart Claude Code. In a session, run /mcp, choose Estelle, and sign in with your browser.',
69
+ ...(capture === 'off_no_key' ? ['MCP works without a key. Session capture stays off until ESTELLE_API_KEY is set to a key from the same Estelle account.'] : [])];
70
+
71
+ async function uninstallOld(native) {
72
+ const removed = await native('uninstall');
73
+ let outcome = null;
74
+ try { outcome = JSON.parse(removed.text).outcome; } catch { /* unparsed is not removed; the read-back decides */ }
75
+ const after = await native('list');
76
+ if (after.ok !== true) return 'unknown';
77
+ const gone = !scopesOf(parseList(after.text), OLD_PLUGIN).includes('user');
78
+ return gone && outcome === 'ok' ? 'removed' : gone ? 'unknown' : 'not_removed';
79
+ }
80
+
81
+ async function applyMigration(file, snapshot, oldScopes, native, fields) {
82
+ let hooks = { status: 'unchanged', removed: 0 };
83
+ try {
84
+ if (snapshot) hooks = await commitHooks(file, snapshot);
85
+ } catch {
86
+ return report('pending_conflict', { ...fields, path: 'migrate', hooks: 'not_applied', old_plugin: 'not_removed' });
87
+ }
88
+ if (hooks.status === 'unknown') return report('unknown', { ...fields, path: 'migrate', hooks: 'unknown', old_plugin: 'not_removed' });
89
+ const plugin = oldScopes.includes('user') ? await uninstallOld(native) : 'absent';
90
+ const left = oldScopes.filter(scope => scope !== 'user');
91
+ const complete = plugin !== 'not_removed' && plugin !== 'unknown' && left.length === 0;
92
+ return report(complete ? 'applied' : plugin === 'unknown' ? 'unknown' : 'partial', { ...fields, path: 'migrate', hooks: hooks.status,
93
+ hook_removals: hooks.removed, old_plugin: plugin, old_plugin_left_in_scopes: left,
94
+ next: complete ? next(fields.capture_auth) : [`Run /plugin in Claude Code and remove ${OLD_PLUGIN} from the listed scope. Nothing else was changed.`] });
95
+ }
96
+
97
+ export async function runClaudeSetup({ apply = false, expect, env = process.env, home = homedir(), base } = {}, ports = {}) {
98
+ if (apply && (ports.platform || process.platform) === 'win32') return report('pending_unsupported_platform');
99
+ const native = ports.native || nativeClaude;
100
+ const check = ports.checkKey || (key => checkKey(key, { base, version: VERSION }));
101
+ const listing = await native('list');
102
+ let items;
103
+ try {
104
+ if (listing.ok !== true) throw new Error('plugin_list');
105
+ items = parseList(listing.text);
106
+ } catch { return report('pending_host_cli', { message: 'The claude command could not list plugins, so nothing was changed.' }); }
107
+ if (!scopesOf(items, NEW_PLUGIN).length) {
108
+ return report('pending_package', { message: `Install ${NEW_PLUGIN} first. Nothing was changed, so any old install keeps working.` });
109
+ }
110
+ const file = join(env.CLAUDE_CONFIG_DIR ? resolve(env.CLAUDE_CONFIG_DIR) : join(home, '.claude'), 'settings.json');
111
+ let snapshot, removals;
112
+ try {
113
+ snapshot = await inspectHooks(file);
114
+ removals = snapshot ? planHooks(snapshot.bytes).removed : 0;
115
+ } catch { return report('pending_configuration', { message: 'settings.json could not be read safely, so nothing was changed.' }); }
116
+ const oldScopes = scopesOf(items, OLD_PLUGIN);
117
+ const path = oldScopes.length || removals ? 'migrate' : 'fresh';
118
+ const fields = await accountFields(env, home, check);
119
+ const planHash = createHash('sha256').update(JSON.stringify({ before: snapshot?.hash || null, removals, oldScopes, version: VERSION })).digest('hex');
120
+ if (expect !== undefined && expect !== planHash) return report('pending_conflict', { ...fields, path });
121
+ if (path === 'fresh') {
122
+ return report(apply ? 'unchanged' : 'planned', { ...fields, path, next: next(fields.capture_auth),
123
+ message: 'No old Estelle install was found, so there is nothing to migrate.' });
124
+ }
125
+ if (!apply) {
126
+ return report('planned', { ...fields, path, old_plugin_scopes: oldScopes, hook_removals: removals, plan_sha256: planHash,
127
+ message: `Found an old Estelle install: ${[oldScopes.length ? OLD_PLUGIN : '', removals ? `${removals} old hook command(s)` : ''].filter(Boolean).join(' and ')}. Run setup claude --apply to remove it. Sessions, saved memory and every other setting stay.` });
128
+ }
129
+ return applyMigration(file, snapshot, oldScopes, native, fields);
130
+ }
@@ -0,0 +1,112 @@
1
+ #!/usr/bin/env node
2
+ import { existsSync } from 'node:fs';
3
+ import { opendir } from 'node:fs/promises';
4
+ import { join } from 'node:path';
5
+ import { apiBase, apiClient, errorCode, MAX_JSON_BYTES, readJson, recordStatus, stateDirectory } from './io.mjs';
6
+ import { checkKey, KEY_MESSAGES } from './key-check.mjs';
7
+ import { VERSION } from './version.mjs';
8
+
9
+ async function readInput() {
10
+ const chunks = [];
11
+ let bytes = 0;
12
+ for await (const chunk of process.stdin) {
13
+ bytes += chunk.length;
14
+ if (bytes > MAX_JSON_BYTES) throw new Error('input_size');
15
+ chunks.push(chunk);
16
+ }
17
+ try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
18
+ catch { throw new Error('input_json'); }
19
+ }
20
+
21
+ async function status(stateDir) {
22
+ let directory;
23
+ try { directory = await opendir(join(stateDir, 'status')); }
24
+ catch (error) { if (error.code === 'ENOENT') return []; throw error; }
25
+ const rows = [];
26
+ const MAX_STATUS_ROWS = 64;
27
+ for await (const entry of directory) {
28
+ if (rows.length >= MAX_STATUS_ROWS) break;
29
+ if (!entry.isFile() || !/^[a-z-]+\.json$/.test(entry.name)) continue;
30
+ rows.push(await readJson(join(stateDir, 'status', entry.name), 16_000));
31
+ }
32
+ return rows;
33
+ }
34
+
35
+ async function doctor() {
36
+ const api = apiBase();
37
+ const keyPresent = Boolean(process.env.ESTELLE_API_KEY);
38
+ // Presence is not validity: a revoked key is present. Anything but `accepted` is not a pass.
39
+ const keyCheck = keyPresent ? await checkKey(process.env.ESTELLE_API_KEY, { base: api, version: VERSION }) : 'not_checked_no_key';
40
+ // Only the Codex package asks Codex: nothing else should start an app-server on this machine.
41
+ const codexHooks = existsSync(new URL('../.codex-plugin/plugin.json', import.meta.url))
42
+ ? await (await import('./codex-trust.mjs')).codexHookTrust() : undefined;
43
+ console.log(JSON.stringify({ version: VERSION, node: process.version, api,
44
+ credential: keyPresent ? 'environment' : 'missing', key_check: keyCheck,
45
+ ...(KEY_MESSAGES[keyCheck] ? { key_message: KEY_MESSAGES[keyCheck] } : {}),
46
+ ...(codexHooks ? { codex_hooks: codexHooks } : {}),
47
+ status: await status(stateDirectory()) }, null, 2));
48
+ // As with the key: not being able to tell that hooks will run is not a pass.
49
+ if (keyCheck !== 'accepted' || (codexHooks && codexHooks.status !== 'trusted')) process.exitCode = 1;
50
+ }
51
+
52
+ const [command, host] = process.argv.slice(2);
53
+ if (command === 'doctor') {
54
+ doctor().catch(error => { console.error(errorCode(error)); process.exitCode = 1; });
55
+ } else if (command === 'hook') {
56
+ let payload;
57
+ // Optional integration failures must not abort a user's turn. They remain visible in doctor.
58
+ try {
59
+ payload = await readInput();
60
+ const { handleHook } = await import('./hooks.mjs');
61
+ const output = await handleHook({ host, payload, stateDir: stateDirectory(), request: apiClient() });
62
+ if (output) console.log(JSON.stringify(output));
63
+ } catch (error) {
64
+ if (host === 'cursor') {
65
+ const { defaultOutput } = await import('../adapters/cursor.mjs');
66
+ const output = defaultOutput(payload?.hook_event_name);
67
+ if (output) console.log(JSON.stringify(output));
68
+ }
69
+ try {
70
+ const directory = stateDirectory({ ...process.env, ESTELLE_PLUGIN_DATA: undefined });
71
+ await recordStatus(directory, { host: /^[a-z-]+$/.test(host || '') ? host : 'unknown',
72
+ event: 'unknown', mode: 'runner', status: 'failed', code: errorCode(error) });
73
+ } catch {
74
+ console.error('Estelle could not save hook diagnostics. Check the plugin data directory permissions.');
75
+ }
76
+ }
77
+ } else if (command === 'move') {
78
+ const chunks = [];
79
+ for await (const chunk of process.stdin) chunks.push(chunk);
80
+ const { moveCommand } = await import('./move.mjs');
81
+ await moveCommand(host, Buffer.concat(chunks).toString('utf8'));
82
+ } else if (command === 'continue-cloud') {
83
+ try {
84
+ const { runNativeContinue } = await import('./native-export.mjs');
85
+ console.log(JSON.stringify(await runNativeContinue(process.argv.slice(3))));
86
+ } catch (error) {
87
+ const { nativeErrorCode } = await import('./native-export.mjs');
88
+ console.error(`Native continuation could not be completed (${nativeErrorCode(error)}). No safe-to-close acknowledgment was issued.`);
89
+ process.exitCode = 1;
90
+ }
91
+ } else if (command === 'dsh-telemetry') {
92
+ // `dsh --profile <name> --dump-config | node runtime/cli.mjs dsh-telemetry`: the Silo's check on what dsh will mount.
93
+ const chunks = [];
94
+ for await (const chunk of process.stdin) chunks.push(chunk);
95
+ const { telemetryCheck, TELEMETRY_OFF } = await import('./dsh-telemetry.mjs');
96
+ const verdict = telemetryCheck(Buffer.concat(chunks).toString('utf8'));
97
+ console.log(verdict);
98
+ if (verdict !== TELEMETRY_OFF) process.exitCode = 1;
99
+ } else if (command === 'setup') {
100
+ try {
101
+ const { runSetupArgs } = await import('./setup.mjs');
102
+ const result = await runSetupArgs(process.argv.slice(3));
103
+ console.log(JSON.stringify(result));
104
+ if (!['planned', 'applied', 'unchanged'].includes(result.status)) process.exitCode = 1;
105
+ } catch {
106
+ console.log(JSON.stringify({ status: 'pending_setup_unavailable' }));
107
+ process.exitCode = 1;
108
+ }
109
+ } else {
110
+ console.error('Usage: node runtime/cli.mjs hook <claude-code|codex|kimi|grok|cursor|dsh|opencode|pi> | doctor | setup <host> [--apply] [--expect SHA256]');
111
+ process.exitCode = 1;
112
+ }
@@ -0,0 +1,68 @@
1
+ /** Read whether Codex will run Estelle's hooks. Read-only: hook approval belongs to the person, in Codex. */
2
+ import { spawn } from 'node:child_process';
3
+
4
+ const PLUGIN_ID = 'estelle@estelle-plugins';
5
+ const DEADLINE_MS = 8_000;
6
+ const MAX_OUTPUT_BYTES = 1_000_000;
7
+ const MAX_HOOK_ROWS = 64;
8
+
9
+ export const REVIEW_STEP = 'Codex turned off Estelle\'s hooks because the plugin changed. Run /hooks in Codex and press t, '
10
+ + 'or choose "Trust all and continue" the next time Codex starts. Until then Estelle captures nothing from this '
11
+ + 'machine and does not check file writes for credentials.';
12
+ // Right after an update is when this read is most likely to fail, so a failed read still says what to do.
13
+ export const UNREADABLE = Object.freeze({ status: 'unavailable',
14
+ next_step: 'Estelle could not ask Codex whether its hooks will run. Run /hooks in Codex, and if an Estelle hook needs review, press t.' });
15
+
16
+ /** Counts by Codex's own trust status. A hook that is not trusted does not run. */
17
+ export function summarizeHooks(rows) {
18
+ if (!Array.isArray(rows) || rows.length > MAX_HOOK_ROWS) return UNREADABLE;
19
+ const ours = rows.filter(row => row?.pluginId === PLUGIN_ID);
20
+ if (!ours.length) return { status: 'not_installed' };
21
+ const needs = ours.filter(row => row.enabled !== false && !['trusted', 'managed'].includes(row.trustStatus)).length;
22
+ const result = { status: needs ? 'review_required' : 'trusted', hooks: ours.length, needs_review: needs };
23
+ return needs ? { ...result, next_step: REVIEW_STEP } : result;
24
+ }
25
+
26
+ /** Codex's documented hooks/list over a private app-server, closed before returning. Never approves. */
27
+ export function codexHookTrust(cwd = process.cwd(), { spawnImpl = spawn, deadlineMs = DEADLINE_MS, env = process.env } = {}) {
28
+ return new Promise(resolve => {
29
+ let child;
30
+ let bytes = 0;
31
+ let buffer = '';
32
+ let settled = false;
33
+ let timer;
34
+ const finish = value => {
35
+ if (settled) return;
36
+ settled = true;
37
+ clearTimeout(timer);
38
+ try { child?.kill(); } catch { /* already gone */ }
39
+ resolve(value);
40
+ };
41
+ const send = message => child.stdin.write(`${JSON.stringify(message)}\n`);
42
+ const receive = chunk => {
43
+ bytes += chunk.length;
44
+ if (bytes > MAX_OUTPUT_BYTES) return finish(UNREADABLE);
45
+ buffer += chunk.toString('utf8');
46
+ for (let at = buffer.indexOf('\n'); at >= 0; at = buffer.indexOf('\n')) {
47
+ const line = buffer.slice(0, at);
48
+ buffer = buffer.slice(at + 1);
49
+ let row;
50
+ try { row = JSON.parse(line); } catch { return finish(UNREADABLE); }
51
+ if (row.id === 1) {
52
+ send({ method: 'initialized', params: {} });
53
+ send({ id: 2, method: 'hooks/list', params: { cwds: [cwd] } });
54
+ } else if (row.id === 2) finish(summarizeHooks(row.result?.data?.[0]?.hooks));
55
+ }
56
+ return undefined;
57
+ };
58
+ timer = setTimeout(() => finish(UNREADABLE), deadlineMs);
59
+ try {
60
+ child = spawnImpl('codex', ['app-server', '--stdio'], { cwd, env, stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });
61
+ child.on('error', () => finish(UNREADABLE));
62
+ child.on('exit', () => finish(UNREADABLE));
63
+ child.stdin.on('error', () => finish(UNREADABLE));
64
+ child.stdout.on('data', receive);
65
+ send({ id: 1, method: 'initialize', params: { clientInfo: { name: 'estelle-plugin-doctor', version: '1' } } });
66
+ } catch { finish(UNREADABLE); }
67
+ });
68
+ }
@@ -0,0 +1,341 @@
1
+ // What counts as a credential in text. One owner, separate from privacy redaction on purpose.
2
+ //
3
+ // redact.mjs hides too much by design: over-hiding a log line costs nothing. What reads this acts on someone's
4
+ // work, so it needs evidence of a VALUE. A NAME that merely sounds secret is not evidence, and ML code is full of them.
5
+ // Two readers, of different strength: `textHasCredential` decides what a handoff leaves behind instead of pushing
6
+ // (move.mjs), and `vendorKindIn` is all the write hook looks at, because it only warns (write-warning.mjs).
7
+ import { VENDOR_PATTERNS } from './redact.mjs';
8
+
9
+ const MIN_LITERAL = 8;
10
+ const MIN_OPAQUE = 20;
11
+ const MIN_HEX = 32;
12
+ const MIN_OPAQUE_SEGMENT = 16;
13
+ const MIN_OPAQUE_DIGITS = 2;
14
+ const MIN_ENTROPY_LENGTH = 24;
15
+ const MIN_ENTROPY_BITS = 4.2;
16
+ const MAX_ENTROPY_SEPARATORS = 2;
17
+ const MAX_VALUE_SCAN = 4096;
18
+ const MAX_EXPRESSION_SCAN = 512;
19
+ const MAX_LINE_LOOKBACK = 64;
20
+ const MAX_LABEL_PART = 128;
21
+ const MAX_TEMPLATE_REMAINDER = 3;
22
+
23
+ // A label is found by its credential word; the words around it decide how much evidence it needs.
24
+ const LABEL = new RegExp(String.raw`(?<![\w$-])[\w$-]{0,${MAX_LABEL_PART}}`
25
+ + String.raw`(?:secret|token|passw(?:or)?d|passphrase|api[_-]?key|private[_-]?key)[\w$-]{0,${MAX_LABEL_PART}}`, 'gi');
26
+ const CREDENTIAL_WORD = /(?:secrets?|tokens?|passw(?:or)?d|passphrase|apikey|privatekey)$/;
27
+ const COUNT_LIKE_NEIGHBOURS = new Set(['max', 'min', 'num', 'n', 'total', 'input', 'output', 'prompt', 'completion',
28
+ 'cached', 'cache', 'reasoning', 'bos', 'eos', 'pad', 'unk', 'sep', 'cls', 'mask', 'start', 'end', 'stop', 'special',
29
+ 'next', 'prev', 'previous', 'last', 'first', 'current', 'page', 'continuation', 'lexer', 'parser', 'word', 'char']);
30
+ const DESCRIPTOR_ENDINGS = new Set(['env', 'envvar', 'var', 'variable', 'name', 'names', 'url', 'uri', 'endpoint', 'path',
31
+ 'file', 'header', 'field', 'param', 'parameter', 'prefix', 'suffix', 'pattern', 'regex', 'type', 'kind', 'count',
32
+ 'counts', 'id', 'ids', 'len', 'length', 'limit', 'budget', 'usage', 'size', 'index', 'idx', 'ttl', 'expiry', 'expires',
33
+ 'expiration', 'lifetime', 'timeout', 'scope', 'scopes', 'audience', 'issuer', 'provider', 'manager', 'store', 'policy',
34
+ 'label', 'description', 'desc', 'help', 'hint', 'placeholder', 'format', 'digest', 'hash', 'hashed', 'version',
35
+ 'revision', 'rev', 'schema', 'class']);
36
+ const CREDENTIAL_PLURAL_PREFIXES = /^(?:auth|access|refresh|bearer|session|api|id|oauth|csrf|jwt)/;
37
+
38
+ const PLACEHOLDER_MARKERS = new Set(['test', 'testing', 'tests', 'example', 'examples', 'sample', 'dummy', 'fake', 'mock',
39
+ 'placeholder', 'changeme', 'your', 'foo', 'bar', 'baz', 'qux', 'redacted', 'todo', 'fixture', 'stub', 'invalid',
40
+ 'notreal', 'nonexistent']);
41
+ const PLACEHOLDER_WORDS = new Set([...PLACEHOLDER_MARKERS, 'change', 'me', 'my', 'here', 'insert', 'replace', 'put', 'enter',
42
+ 'not', 'a', 'an', 'real', 'secret', 'token', 'key', 'api', 'apikey', 'password', 'pass', 'value', 'string', 'client', 'user',
43
+ 'auth', 'access', 'the', 'for', 'only', 'local', 'dev', 'unit', 'wrong', 'bad', 'good', 'correct', 'valid', 'expired',
44
+ 'revoked', 'none', 'null']);
45
+ const KEYWORD_VALUES = new Set(['required', 'optional', 'redacted', 'disabled', 'enabled', 'hidden', 'masked', 'unknown',
46
+ 'provided', 'undefined', 'password', 'username']);
47
+ const PROSE_WORDS = new Set(['the', 'a', 'an', 'is', 'are', 'of', 'for', 'to', 'your', 'not', 'missing', 'invalid', 'enter',
48
+ 'please', 'must', 'be', 'required', 'provide', 'set', 'no', 'with', 'and', 'or', 'in', 'this', 'that', 'can', 'cannot',
49
+ 'failed', 'expired', 'use', 'using', 'used']);
50
+ // The two example keys AWS prints in its own documentation; nothing else with this shape is waived.
51
+ const EXACT_VENDOR_EXAMPLES = new Set(['AKIA', 'ASIA'].map(prefix => `${prefix}IOSFODNN7EXAMPLE`));
52
+ const STORE_REFERENCE = /^(?:process\.env|import\.meta\.env|os\.environ|os\.getenv|getenv\b|System\.getenv|ENV\[|env\[|Deno\.env|std::env|env::var|secrets\.|vault\.)/;
53
+ const TEMPLATES = /\$\{\{[^}]*\}\}|\$\{[^}]*\}|\$\([^)]*\)|\{\{[^}]*\}\}|\$[A-Za-z_]\w*|%\([^)]*\)[sd]|%[A-Za-z_]\w*%|%[sd]|\{[A-Za-z_][\w.]*\}|<[^<>\n]*>|\[[A-Za-z_][\w -]*\]/g;
54
+ const STORE_LOCATOR = /^(?:op|vault|ssm|secretsmanager|gcp-secret|azure-keyvault|ref\+[a-z]+):|^arn:aws:(?:secretsmanager|ssm):|^ENC\[/;
55
+ const ENV_NAME = /^[A-Z][A-Z0-9_]*_?(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PASSPHRASE)$/;
56
+ const EMPTY_PEM = /-----BEGIN ([A-Z ]*PRIVATE KEY)-----((?:\s|\\+[rn])*)(?:-----END \1-----)?/g;
57
+ const SOURCE_END = /^(?:\\*["'`]|\/[gimsuy]*)(?:\s|\\+[rn])*(?:[,;)}\]]|$)/;
58
+ const BEARER = /\bBearer\s+([A-Za-z0-9._~+/-]{8,}=*)/gi;
59
+ const NAMED_HEX = /\bsession[_-]token\s+is\s+["'`]?[a-f0-9]{32,128}/i;
60
+ // Any scheme with a userinfo password. The vendor list only knows one database scheme.
61
+ const URL_USERINFO = /\b[a-z][a-z0-9+.-]{1,20}:\/\/[^\s:@/'"`]{0,128}:([^\s@/'"`]{3,256})@/gi;
62
+ const PORT_ONLY = /^\d{1,5}$/;
63
+ const COMMON_URL_WORDS = /^(?:password|pass|postgres|secret)$/i;
64
+ const YAML_LINE_START = /^[+\- \t]*$/;
65
+ const YAML_LINE_END = /[ \t]*(?:#[^\n]*)?(?:\r?\n|$)/y;
66
+ const CLOSES_OBJECT = /\s*[}\])]/y;
67
+ const CONTAINS_CREDENTIAL_WORD = /secret|token|passw|passphrase|key/;
68
+ const QUOTED_VALUE_ON_NEXT_LINE = /\s*/y;
69
+ const SAME_LINE_GAP = /[ \t]*/y;
70
+ const OPERATOR = /\\*["'`]?\s*(:=|=>|=(?![=~])|:(?!:))/y;
71
+ const QUOTE_OPEN = /([frbuFRBU]{0,2})(\\*)(["'`])/y;
72
+ const BARE_VALUE = /[^\s,;)}\]"'`]{1,512}/y;
73
+ // A type hint can sit between the name and the value, in Python and TypeScript annotations alike.
74
+ const TYPE_THEN_ASSIGN = /[A-Za-z_][\w.]*(?:\[[^\]\n]{0,128}\])?(?:\s*\|\s*[A-Za-z_][\w.]*(?:\[[^\]\n]{0,64}\])?){0,4}\??\s*=(?![=~>])[ \t]*/y;
75
+ const TYPE_NAME = /^[A-Z][\w.]*(?:\[.*)?$|^(?:str|string|bytes|int|bool|number|any|object|None|null|undefined)(?:\[.*)?\??$/;
76
+ const REGEX_LITERAL = /^\/(?=[^/]*[|^$*+?\\])[^/\n]+\/[dgimsuvy]*$/;
77
+
78
+ const matchAt = (pattern, text, index) => { pattern.lastIndex = index; return pattern.exec(text); };
79
+ const wordsOf = label => label.replace(/([a-z0-9])([A-Z])/g, '$1_$2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
80
+ .toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
81
+
82
+ function joinTwoPartNames(words) {
83
+ const joined = [];
84
+ for (let i = 0; i < words.length; i++) {
85
+ const pair = `${words[i]}${words[i + 1] ?? ''}`;
86
+ if (pair === 'apikey' || pair === 'privatekey') { joined.push(pair); i++; } else joined.push(words[i]);
87
+ }
88
+ return joined;
89
+ }
90
+
91
+ /** 'none' never refuses on its own; 'weak' needs an opaque value; 'strong' refuses any real-looking literal. */
92
+ export function labelStrength(label) {
93
+ const words = joinTwoPartNames(wordsOf(label));
94
+ const at = words.findIndex(word => CREDENTIAL_WORD.test(word));
95
+ if (at < 0) return 'none';
96
+ const word = words[at];
97
+ if (DESCRIPTOR_ENDINGS.has(words.at(-1)) && words.length > 1) return 'weak';
98
+ if (!word.endsWith('tokens') && !/token$/.test(word)) return 'strong';
99
+ const before = words[at - 1];
100
+ if (word.endsWith('tokens')) {
101
+ const authPrefix = CREDENTIAL_PLURAL_PREFIXES.test(before ?? '') || CREDENTIAL_PLURAL_PREFIXES.test(word.replace(/tokens$/, ''));
102
+ return authPrefix ? 'strong' : 'weak';
103
+ }
104
+ return COUNT_LIKE_NEIGHBOURS.has(before) ? 'weak' : 'strong';
105
+ }
106
+
107
+ function shannonBits(text) {
108
+ const counts = new Map();
109
+ for (const char of text) counts.set(char, (counts.get(char) ?? 0) + 1);
110
+ let bits = 0;
111
+ for (const count of counts.values()) { const p = count / text.length; bits -= p * Math.log2(p); }
112
+ return bits;
113
+ }
114
+
115
+ /** Random-looking: the shape of a generated value rather than of a name, path, URL or sentence. */
116
+ export function isOpaque(value) {
117
+ if (value.length < MIN_OPAQUE || /:\/\//.test(value) || !/^[\w\-./:=+~]+$/.test(value)) return false;
118
+ const hex = new RegExp(`^[a-fA-F0-9]{${MIN_HEX},}$`);
119
+ if (hex.test(value)) return true;
120
+ const segments = value.split(/[-_./:=+]/);
121
+ for (const segment of segments) {
122
+ if (hex.test(segment)) return true;
123
+ const digits = segment.replace(/\D/g, '').length;
124
+ if (segment.length >= MIN_OPAQUE_SEGMENT && digits >= MIN_OPAQUE_DIGITS && digits < segment.length) return true;
125
+ }
126
+ return value.length >= MIN_ENTROPY_LENGTH && segments.length - 1 <= MAX_ENTROPY_SEPARATORS
127
+ && shannonBits(value) >= MIN_ENTROPY_BITS;
128
+ }
129
+
130
+ const isTemplate = body => STORE_LOCATOR.test(body) || body.replace(TEMPLATES, '').trim().length <= MAX_TEMPLATE_REMAINDER;
131
+ const isRepeatedMask = body => /^(.)\1*$/.test(body) && /^[xX*.\-#•]/.test(body);
132
+
133
+ function isPlaceholder(body) {
134
+ if (isRepeatedMask(body)) return true;
135
+ const words = body.toLowerCase().split(/[^a-z0-9]+/).flatMap(word => word.split(/(?<=[a-z])(?=\d)|(?<=\d)(?=[a-z])/)).filter(Boolean);
136
+ if (!words.length) return false;
137
+ let marked = false;
138
+ for (const word of words) {
139
+ if (/^\d{1,4}$/.test(word) || /^x{3,}$/.test(word)) continue;
140
+ const glued = [...PLACEHOLDER_MARKERS].find(marker => word.startsWith(marker) && PLACEHOLDER_WORDS.has(word.slice(marker.length)));
141
+ if (PLACEHOLDER_MARKERS.has(word) || glued) { marked = true; continue; }
142
+ if (!PLACEHOLDER_WORDS.has(word)) return false;
143
+ }
144
+ return marked;
145
+ }
146
+
147
+ function isProse(body) {
148
+ const words = body.trim().split(/\s+/);
149
+ if (words.length < 2 || !words.every(word => /^[A-Za-z][A-Za-z'-]*[.,:;!?)]?$/.test(word))) return false;
150
+ return words.some(word => PROSE_WORDS.has(word.toLowerCase().replace(/[.,:;!?)]$/, '')));
151
+ }
152
+
153
+ /** Does this literal, assigned to a label of this strength, hold a credential? */
154
+ function literalIsCredential(body, strength) {
155
+ if (strength === 'none' || isTemplate(body) || isPlaceholder(body)) return false;
156
+ if (strength === 'weak') return isOpaque(body);
157
+ if (body.length < MIN_LITERAL || KEYWORD_VALUES.has(body.toLowerCase())) return false;
158
+ return !isProse(body) && !ENV_NAME.test(body);
159
+ }
160
+
161
+ function closingQuote(text, from, quote, escapes) {
162
+ const end = Math.min(text.length, from + MAX_VALUE_SCAN);
163
+ for (let i = from; i < end; i++) {
164
+ const char = text[i];
165
+ if (char === '\n' && quote !== '`') return i;
166
+ if (char === '\\' && escapes === 0) { i++; continue; }
167
+ if (char !== quote) continue;
168
+ if (escapes === 0) return i;
169
+ let run = 0;
170
+ while (run <= escapes && text[i - run - 1] === '\\') run++;
171
+ if (run >= escapes) return i - escapes;
172
+ }
173
+ return end;
174
+ }
175
+
176
+ function readValue(text, start) {
177
+ const open = matchAt(QUOTE_OPEN, text, start);
178
+ if (open) {
179
+ const from = start + open[0].length;
180
+ const close = closingQuote(text, from, open[3], open[2].length);
181
+ return { quoted: true, body: text.slice(from, close), after: close + open[2].length + 1 };
182
+ }
183
+ const bare = matchAt(BARE_VALUE, text, start);
184
+ return { quoted: false, body: bare ? bare[0] : '', after: start + (bare ? bare[0].length : 0) };
185
+ }
186
+
187
+ /** Walk the rest of one expression: a reference followed by an opaque literal is still a literal. */
188
+ function expressionHoldsOpaqueLiteral(text, from) {
189
+ let depth = 0;
190
+ const end = Math.min(text.length, from + MAX_EXPRESSION_SCAN);
191
+ for (let i = from; i < end; i++) {
192
+ const char = text[i];
193
+ if (char === '\n' || (depth === 0 && (char === ',' || char === ';'))) return false;
194
+ if ('([{'.includes(char)) depth++;
195
+ if (')]}'.includes(char) && --depth < 0) return false;
196
+ if (!'"\'`'.includes(char)) continue;
197
+ const close = closingQuote(text, i + 1, char, 0);
198
+ const body = text.slice(i + 1, close);
199
+ if (isOpaque(body) && !isTemplate(body) && !isPlaceholder(body) && !ENV_NAME.test(body)) return true;
200
+ i = close;
201
+ }
202
+ return false;
203
+ }
204
+
205
+ /** An all-caps name assigned with no spaces at the start of a line, or a long command-line flag:
206
+ * an env file or shell line, where a bare value cannot be a variable. */
207
+ function isDeclarationForm(text, label, labelStart, operatorText) {
208
+ if (operatorText !== '=') return false;
209
+ if (label.startsWith('--')) return true;
210
+ if (label !== label.toUpperCase() || !/[A-Z]/.test(label)) return false;
211
+ const prefix = lineBefore(text, labelStart);
212
+ return prefix !== null && /^[+\- \t]*(?:export[ \t]+|set[ \t]+)?$/.test(prefix);
213
+ }
214
+
215
+ /** What precedes a position on its line, or null when that line is longer than the lookback. */
216
+ function lineBefore(text, position) {
217
+ const before = text.slice(Math.max(0, position - MAX_LINE_LOOKBACK), position);
218
+ const newline = before.lastIndexOf('\n');
219
+ if (newline < 0 && position > before.length) return null;
220
+ return before.slice(newline + 1);
221
+ }
222
+
223
+ /** A key and one lowercase word alone on a line: YAML's unquoted string. Anything that could be a
224
+ * variable (punctuation, a trailing comma, the last property of an object) stays a reference. */
225
+ function isLoneYamlWord(text, labelStart, value) {
226
+ const { body } = value;
227
+ if (!/^[a-z]+$/.test(body) || body.length < MIN_LITERAL) return false;
228
+ if (KEYWORD_VALUES.has(body) || CONTAINS_CREDENTIAL_WORD.test(body) || isPlaceholder(body)) return false;
229
+ const prefix = lineBefore(text, labelStart);
230
+ if (prefix === null || !YAML_LINE_START.test(prefix)) return false;
231
+ const end = matchAt(YAML_LINE_END, text, value.after);
232
+ if (!end) return false;
233
+ if (matchAt(CLOSES_OBJECT, text, end.index + end[0].length)) return false;
234
+ return true;
235
+ }
236
+
237
+ /** Source, not a value: at least two lowercase words joined by `_`, one of them all letters, none with more than two digits.
238
+ * This stops catching a human password written bare in that shape, such as `hunter2_summer`. Quoted, or on an env-file line, it is still refused. */
239
+ function isSnakeIdentifier(body) {
240
+ if (!/^[a-z_$][a-z0-9_$]*$/.test(body)) return false;
241
+ const segments = body.split('_').filter(Boolean);
242
+ if (segments.length < 2 || !segments.some(segment => /^[a-z]{3,}$/.test(segment))) return false;
243
+ return segments.every(segment => segment.replace(/\D/g, '').length <= MIN_OPAQUE_DIGITS);
244
+ }
245
+
246
+ function bareLiteralIsCredential(body, strength) {
247
+ if (/^\d+$/.test(body)) return strength === 'strong' && body.length >= MIN_LITERAL;
248
+ if (isOpaque(body)) return !isTemplate(body) && !isPlaceholder(body) && !ENV_NAME.test(body);
249
+ if (strength !== 'strong' || body.length < MIN_LITERAL || /[()[\]{}."'`]/.test(body)) return false;
250
+ // A regex with an operator in it describes values. An opaque one between slashes was already refused above.
251
+ if (REGEX_LITERAL.test(body) || isSnakeIdentifier(body)) return false;
252
+ return /\d/.test(body) && /[A-Za-z]/.test(body) && !isPlaceholder(body);
253
+ }
254
+
255
+ function assignmentIsCredential(text, label, labelStart, labelEnd) {
256
+ const strength = labelStrength(label);
257
+ if (strength === 'none') return false;
258
+ const operator = matchAt(OPERATOR, text, labelEnd);
259
+ if (!operator) return false;
260
+ // A segment of a colon-separated path, as in a cloud resource name, is not a name being assigned.
261
+ if (operator[1] === ':' && text[labelStart - 1] === ':') return false;
262
+ const labelQuoted = /["'`]/.test(operator[0]);
263
+ const start = operator.index + operator[0].length;
264
+ const gap = matchAt(labelQuoted ? QUOTED_VALUE_ON_NEXT_LINE : SAME_LINE_GAP, text, start);
265
+ const valueStart = start + gap[0].length;
266
+ const value = readValue(text, valueStart);
267
+ if (value.quoted) return literalIsCredential(value.body, strength) || expressionHoldsOpaqueLiteral(text, value.after);
268
+ if (!value.body) return false;
269
+ if (operator[1] === ':' && TYPE_NAME.test(value.body) && !isOpaque(value.body) && !/(?:\D*\d){3}/.test(value.body)) {
270
+ const typed = matchAt(TYPE_THEN_ASSIGN, text, valueStart);
271
+ if (!typed) return false;
272
+ const assignedStart = valueStart + typed[0].length;
273
+ const assigned = readValue(text, assignedStart);
274
+ const direct = assigned.quoted ? literalIsCredential(assigned.body, strength) : bareLiteralIsCredential(assigned.body, strength);
275
+ return direct || expressionHoldsOpaqueLiteral(text, assignedStart);
276
+ }
277
+ if (operator[1] === ':' && strength === 'strong' && !labelQuoted && isLoneYamlWord(text, labelStart, value)) return true;
278
+ const reference = STORE_REFERENCE.test(value.body) || /^[$%]/.test(value.body);
279
+ if (!reference && strength === 'strong' && gap[0] === '' && isDeclarationForm(text, label, labelStart, operator[0])) {
280
+ return value.body.length >= MIN_LITERAL && !isTemplate(value.body) && !isPlaceholder(value.body);
281
+ }
282
+ if (!reference && bareLiteralIsCredential(value.body, strength)) return true;
283
+ return expressionHoldsOpaqueLiteral(text, valueStart);
284
+ }
285
+
286
+ function urlPasswordIsReal(value) {
287
+ return !(isTemplate(value) || isPlaceholder(value) || COMMON_URL_WORDS.test(value) || PORT_ONLY.test(value));
288
+ }
289
+
290
+ function urlCredential(text) {
291
+ for (const match of text.matchAll(URL_USERINFO)) if (urlPasswordIsReal(match[1])) return true;
292
+ return false;
293
+ }
294
+
295
+ function vendorMatchIsReal(match) {
296
+ const whole = match[0];
297
+ if (EXACT_VENDOR_EXAMPLES.has(whole)) return false;
298
+ if (/^postgres/.test(whole)) return urlPasswordIsReal(whole.slice(whole.lastIndexOf(':') + 1, -1));
299
+ if (whole.startsWith('-----BEGIN')) return true;
300
+ return !/^x{6,}$/i.test(whole.slice(Math.max(whole.lastIndexOf('_'), whole.lastIndexOf('-')) + 1));
301
+ }
302
+
303
+ /** The kind of the first real vendor shape in this text, or ''. */
304
+ function vendorKind(text) {
305
+ for (const [pattern, label] of VENDOR_PATTERNS) {
306
+ for (const match of text.matchAll(pattern)) {
307
+ if (vendorMatchIsReal(match)) return /\[redacted ([^\]]+)\]/.exec(label)?.[1] ?? 'database password';
308
+ }
309
+ }
310
+ return '';
311
+ }
312
+
313
+ function bearerCredential(text) {
314
+ for (const match of text.matchAll(BEARER)) {
315
+ const value = match[1];
316
+ if (STORE_REFERENCE.test(value)) continue;
317
+ if (/\d/.test(value) || isOpaque(value) || (/[a-z]/.test(value) && /[A-Z]/.test(value) && value.length >= MIN_OPAQUE)) return true;
318
+ }
319
+ return false;
320
+ }
321
+
322
+ /** A bare PEM marker is public syntax used by every scanner; a marker with a body is a key. */
323
+ function withoutEmptyPem(text) {
324
+ return text.replace(EMPTY_PEM, (whole, _kind, _space, offset) => {
325
+ const rest = text.slice(offset + whole.length);
326
+ return !rest || SOURCE_END.test(rest) ? '' : whole;
327
+ });
328
+ }
329
+
330
+ /** The kind of the first exact vendor key shape in this text, or ''. A name, a URL password or a bearer value is not one. */
331
+ export const vendorKindIn = source => vendorKind(withoutEmptyPem(source.replaceAll('\0', '')));
332
+
333
+ /** Input size is capped at MAX_JSON_BYTES by the hook runner, so each scan below is bounded by it. */
334
+ export function textHasCredential(source) {
335
+ const text = withoutEmptyPem(source.replaceAll('\0', ''));
336
+ if (vendorKind(text) || urlCredential(text) || bearerCredential(text) || NAMED_HEX.test(text)) return true;
337
+ for (const match of text.matchAll(LABEL)) {
338
+ if (assignmentIsCredential(text, match[0], match.index, match.index + match[0].length)) return true;
339
+ }
340
+ return false;
341
+ }