@seanmozeik/tripwire 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@seanmozeik/tripwire",
+  "version": "0.1.0",
+  "description": "Opinionated hooks dispatcher for AI coding agents with configurable safety rules",
+  "license": "MIT",
+  "bin": {
+    "tripwire": "./dist/tripwire-cli.js",
+    "tripwire-hook": "./dist/tripwire.js"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "prepublishOnly": "bun run build",
+    "check": "bun run format && bun run lint:fix && bun run typecheck",
+    "format": "oxfmt --write .",
+    "lint": "oxlint --tsconfig tsconfig.oxlint.json .",
+    "lint:fix": "oxlint --format agent --tsconfig tsconfig.oxlint.json --fix .",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@effect/platform-bun": "^4.0.0-beta.65",
+    "effect": "^4.0.0-beta.65",
+    "shell-quote": "^1.8.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.13",
+    "@types/shell-quote": "^1.7.5",
+    "oxfmt": "^0.48.0",
+    "oxlint": "^1.61.0",
+    "oxlint-tsgolint": "^0.22.1",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "bun": ">=1.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+// `tripwire test '<command>'` — pipe a synthetic event through the
+// Dispatcher and pretty-print the decision. Indispensable for tuning
+// Rules without going through Claude Code.
+//
+// Usage:
+//   Bun src/cli.ts test 'rm -rf /etc'
+//   Bun src/cli.ts test --tool=Read --path=.env
+//   Bun src/cli.ts test --post --tool=Bash --stdout='ghp_<token>'
+
+import { spawnSync } from 'node:child_process';
+
+const DISPATCH_BIN = `${import.meta.dir}/../dist/tripwire.js`;
+
+interface CliArgs {
+  readonly tool: string;
+  readonly post: boolean;
+  readonly path: string | undefined;
+  readonly command: string | undefined;
+  readonly stdout: string | undefined;
+  readonly stderr: string | undefined;
+  readonly content: string | undefined;
+}
+
+const parseArgs = (argv: readonly string[]): CliArgs => {
+  let tool = 'Bash';
+  let post = false;
+  let path: string | undefined;
+  let command: string | undefined;
+  let stdout: string | undefined;
+  let stderr: string | undefined;
+  let content: string | undefined;
+  for (const a of argv) {
+    if (a === '--post') {
+      post = true;
+      continue;
+    }
+    if (a.startsWith('--tool=')) {
+      tool = a.slice('--tool='.length);
+      continue;
+    }
+    if (a.startsWith('--path=')) {
+      path = a.slice('--path='.length);
+      continue;
+    }
+    if (a.startsWith('--stdout=')) {
+      stdout = a.slice('--stdout='.length);
+      continue;
+    }
+    if (a.startsWith('--stderr=')) {
+      stderr = a.slice('--stderr='.length);
+      continue;
+    }
+    if (a.startsWith('--content=')) {
+      content = a.slice('--content='.length);
+      continue;
+    }
+    command ??= a;
+  }
+  return { tool, post, path, command, stdout, stderr, content };
+};
+
+interface BuiltEvent {
+  hook_event_name: string;
+  tool_name: string;
+  cwd: string;
+  session_id: string;
+  tool_input?: unknown;
+  tool_response?: unknown;
+}
+
+const buildToolInput = (tool: string, args: CliArgs): unknown => {
+  if (tool === 'Bash') {
+    return { command: args.command ?? '' };
+  }
+  if (tool === 'Read') {
+    return { file_path: args.path ?? '' };
+  }
+  if (tool === 'Write') {
+    return { file_path: args.path ?? '', content: args.content ?? '' };
+  }
+  if (tool === 'Edit' || tool === 'MultiEdit') {
+    return { file_path: args.path ?? '', old_string: '', new_string: args.content ?? '' };
+  }
+  return undefined;
+};
+
+const buildEvent = (args: CliArgs): BuiltEvent => {
+  const eventName = args.post ? 'PostToolUse' : 'PreToolUse';
+  const tool = args.tool;
+  const event: BuiltEvent = {
+    hook_event_name: eventName,
+    tool_name: tool,
+    cwd: process.cwd(),
+    session_id: 'tripwire-cli-test',
+    tool_input: buildToolInput(tool, args),
+  };
+  if (args.post) {
+    event.tool_response =
+      tool === 'Bash'
+        ? { stdout: args.stdout ?? '', stderr: args.stderr ?? '' }
+        : { content: args.content ?? '' };
+  }
+  return event;
+};
+
+const printUsage = (): void => {
+  process.stdout.write(
+    [
+      'tripwire CLI — synthetic-event tester',
+      '',
+      'Usage:',
+      "  tripwire test '<command>'                 # PreToolUse Bash",
+      '  tripwire test --tool=Read --path=.env     # PreToolUse Read',
+      "  tripwire test --tool=Write --path=foo.ts --content='TODO finish'",
+      "  tripwire test --post --tool=Bash --stdout='ghp_REAL_TOKEN'  # PostToolUse",
+      '',
+    ].join('\n'),
+  );
+};
+
+const main = (): void => {
+  const argv = process.argv.slice(2);
+  if (argv.length === 0 || argv[0] !== 'test') {
+    printUsage();
+    process.exit(0);
+  }
+  const args = parseArgs(argv.slice(1));
+  const event = buildEvent(args);
+  const result = spawnSync(DISPATCH_BIN, [], {
+    input: JSON.stringify(event),
+    encoding: 'utf8',
+    timeout: 10_000,
+  });
+  if (result.error !== undefined) {
+    process.stderr.write(`error: ${String(result.error)}\n`);
+    process.exit(1);
+  }
+  const stdout: string = result.stdout;
+  try {
+    const parsed = JSON.parse(stdout) as unknown;
+    process.stdout.write(`${JSON.stringify(parsed, null, 2)}\n`);
+  } catch {
+    process.stdout.write(stdout);
+  }
+};
+
+main();

package/src/dispatch.ts

@@ -0,0 +1,340 @@
+#!/usr/bin/env bun
+// Tripwire — Claude Code hooks dispatcher.
+//
+// Reads a hook event JSON payload on stdin, routes by hook_event_name +
+// Tool_name, runs rules with per-rule timeouts, merges decisions
+// (most-restrictive wins), wraps allowed Bash commands through rtk for
+// Token-saver rewriting, scans PostToolUse output for secrets via
+// Betterleaks, and writes Claude Code's expected JSON response on stdout.
+//
+// Design rules:
+//   - A buggy or slow rule must never block the agent. Every rule runs
+//     Under a timeout; any defect or timeout collapses to `allow`, logged.
+//   - Block messages address the agent in second person and name the
+//     Concrete alternative tool / approach. No vague "denied for safety".
+//   - One bypass token: `tripwire-allow` (any comment syntax) on a code
+//     Line, or `# tripwire-allow` in a bash command.
+
+import { BunRuntime } from '@effect/platform-bun';
+import { Cause, Effect, Exit, Schema } from 'effect';
+
+import { parseCommand } from './lib/bash';
+import { loadConfig, type Config } from './lib/config';
+import { type Decision, allow, merge } from './lib/decision';
+import {
+  type BashInput,
+  type EditInput,
+  type HookEvent,
+  HookEventSchema,
+  type ReadInput,
+  type WriteInput,
+  isBashInput,
+  isEditInput,
+  isReadInput,
+  isWriteInput,
+} from './lib/event.ts';
+import { logError } from './lib/log';
+import { runRtkRewrite } from './lib/rtk';
+import { bashDeny } from './rules/bash-deny';
+import { bashGit } from './rules/bash-git';
+import { bashNetworkInstall } from './rules/bash-network-install';
+import { bashRedirect } from './rules/bash-redirect';
+import { bashScopedRm } from './rules/bash-scoped-rm';
+import { bashTarExplosion } from './rules/bash-tar-explosion';
+import { bashToolPolicy } from './rules/bash-tool-policy';
+import { configCustom } from './rules/config-custom';
+import { lazyCode } from './rules/lazy-code';
+import { pathProtect } from './rules/path-protect';
+import { postSecretScrub } from './rules/post-secret-scrub';
+import { readProtect } from './rules/read-protect';
+
+const RULE_TIMEOUT_MS = 250;
+const POST_RULE_TIMEOUT_MS = 5000; // Betterleaks subprocess can take longer
+
+const readStdin = async (): Promise<string> => {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+};
+
+const writeAllow = (): void => {
+  process.stdout.write('{"continue": true}\n');
+};
+
+// Codex's PreToolUse hook rejects `hookSpecificOutput.additionalContext`
+// (openai/codex issue #19385) and `updatedInput` (#18491). Detect Codex
+// Via its `turn_id` extension and downgrade output accordingly. Claude
+// Code accepts both, so we only narrow when we can confirm we're on Codex.
+const isCodex = (event: HookEvent): boolean => event.turn_id !== undefined;
+
+const writeRewriteAllow = (event: HookEvent, command: string, _reason?: string): void => {
+  // Codex's PreToolUse parser strict-rejects `updatedInput` (openai/codex
+  // #18491 — parsed but unimplemented as of codex-cli 0.12x). On Codex we
+  // Can't transparently rewrite, so pass the original command through
+  // Silently. Until #18491 lands, RTK savings are Claude-only.
+  if (isCodex(event)) {
+    writeAllow();
+    return;
+  }
+  // Claude Code: rewrite silently. We deliberately omit
+  // `permissionDecisionReason` so the model's context isn't polluted with
+  // "rtk rewrote your command" chatter every Bash call.
+  const out = {
+    continue: true,
+    hookSpecificOutput: { hookEventName: event.hook_event_name, updatedInput: { command } },
+  };
+  process.stdout.write(`${JSON.stringify(out)}\n`);
+};
+
+interface WarnOutput {
+  hookEventName: string;
+  additionalContext?: string;
+  updatedInput?: { command: string };
+}
+
+const writeWarn = (event: HookEvent, decision: Decision): void => {
+  const eventName = event.hook_event_name;
+  const reason = `[tripwire:${decision.rule}] ${decision.message}`;
+  if (isCodex(event)) {
+    // Codex rejects both `additionalContext` and `updatedInput` on
+    // PreToolUse. Send only `systemMessage`; the rewrite (if any) is
+    // Dropped and the original command runs.
+    process.stdout.write(`${JSON.stringify({ continue: true, systemMessage: reason })}\n`);
+    return;
+  }
+  const hookSpecificOutput: WarnOutput = { hookEventName: eventName, additionalContext: reason };
+  if (decision.rewriteCommand !== undefined) {
+    hookSpecificOutput.updatedInput = { command: decision.rewriteCommand };
+  }
+  process.stdout.write(`${JSON.stringify({ continue: true, hookSpecificOutput })}\n`);
+};
+
+const writePreToolGate = (eventName: string, decision: Decision): void => {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: eventName,
+      permissionDecision: decision.kind === 'deny' ? 'deny' : 'ask',
+      permissionDecisionReason: `[tripwire:${decision.rule}] ${decision.message}`,
+    },
+  };
+  process.stdout.write(`${JSON.stringify(out)}\n`);
+};
+
+const writePostToolBlock = (decision: Decision): void => {
+  const out = {
+    continue: true,
+    decision: 'block',
+    reason: `[tripwire:${decision.rule}] ${decision.message}`,
+  };
+  process.stdout.write(`${JSON.stringify(out)}\n`);
+};
+
+// Tool names vary across hosts. Claude Code uses `Bash`/`Read`/`Write`/
+// `Edit`/`MultiEdit`. Codex sends `apply_patch` for file edits. Devin sends
+// `exec` for shell. Pi (via pi-hooks) sends lowercase `bash`/`read`/`write`/
+// `edit`. Normalize everything to the Claude vocabulary so the rest of the
+// Dispatcher only deals with one set of names.
+const normalizeToolName = (name: string): string => {
+  const n = name.toLowerCase();
+  if (n === 'bash' || n === 'exec' || n === 'shell' || n === 'run_command') {
+    return 'Bash';
+  }
+  if (n === 'read' || n === 'read_file') {
+    return 'Read';
+  }
+  if (n === 'write' || n === 'write_file') {
+    return 'Write';
+  }
+  if (n === 'edit' || n === 'edit_file' || n === 'multiedit' || n === 'apply_patch') {
+    return 'Edit';
+  }
+  if (n === 'webfetch' || n === 'web_fetch' || n === 'fetch') {
+    return 'WebFetch';
+  }
+  return name;
+};
+
+type RuleFn = () => Decision;
+
+const runRule = (name: string, fn: RuleFn, timeoutMs: number): Effect.Effect<Decision> =>
+  Effect.gen(function* () {
+    const exit = yield* Effect.exit(
+      Effect.try({ try: fn, catch: (e) => e }).pipe(Effect.timeout(timeoutMs)),
+    );
+    if (Exit.isSuccess(exit)) {
+      return exit.value;
+    }
+    logError(name, Cause.pretty(exit.cause));
+    return allow(name);
+  });
+
+interface Rule {
+  readonly name: string;
+  readonly fn: RuleFn;
+}
+
+const collectPreToolUseRules = (tool: string, input: unknown, config: Config): Rule[] => {
+  const rules: Rule[] = [];
+  if (tool === 'Bash' && isBashInput(input)) {
+    const i: BashInput = input;
+    const segments = parseCommand(i.command);
+    rules.push({ name: 'bash-deny', fn: () => bashDeny(segments, i.command) });
+    rules.push({
+      name: 'bash-git',
+      fn: () => bashGit(segments, i.command, config.git ?? { enforceConventionalCommits: true }),
+    });
+    rules.push({
+      name: 'bash-scoped-rm',
+      fn: () => bashScopedRm(segments, i.command, config.safePaths ?? {}),
+    });
+    rules.push({ name: 'bash-redirect', fn: () => bashRedirect(segments, i.command) });
+    rules.push({ name: 'bash-network-install', fn: () => bashNetworkInstall(segments, i.command) });
+    rules.push({ name: 'bash-tar-explosion', fn: () => bashTarExplosion(segments, i.command) });
+    rules.push({ name: 'bash-tool-policy', fn: () => bashToolPolicy(segments, i.command) });
+    rules.push({
+      name: 'config-custom',
+      fn: () =>
+        configCustom(
+          segments,
+          i.command,
+          config.blockedCommands ?? [],
+          config.allowedCommands ?? [],
+        ),
+    });
+    return rules;
+  }
+  if (tool === 'Read' && isReadInput(input)) {
+    const i: ReadInput = input;
+    rules.push({ name: 'read-protect', fn: () => readProtect(i) });
+    return rules;
+  }
+  const isEdit = (tool === 'Edit' || tool === 'MultiEdit') && isEditInput(input);
+  const isWrite = tool === 'Write' && isWriteInput(input);
+  if (isEdit) {
+    const i: EditInput = input;
+    rules.push({ name: 'path-protect', fn: () => pathProtect(i) });
+    rules.push({ name: 'lazy-code', fn: () => lazyCode(i) });
+  } else if (isWrite) {
+    const i: WriteInput = input;
+    rules.push({ name: 'path-protect', fn: () => pathProtect(i) });
+    rules.push({ name: 'lazy-code', fn: () => lazyCode(i) });
+  }
+  return rules;
+};
+
+const collectPostToolUseRules = (tool: string, response: unknown): Rule[] => {
+  if (tool === 'Bash' || tool === 'Read' || tool === 'WebFetch') {
+    return [{ name: 'post-secret-scrub', fn: () => postSecretScrub({ toolName: tool, response }) }];
+  }
+  return [];
+};
+
+const runRules = (rules: readonly Rule[], timeoutMs: number): Effect.Effect<Decision> =>
+  Effect.gen(function* () {
+    if (rules.length === 0) {
+      return allow('no-rules');
+    }
+    const decisions: Decision[] = [];
+    for (const r of rules) {
+      decisions.push(yield* runRule(r.name, r.fn, timeoutMs));
+    }
+    return merge(decisions);
+  });
+
+const handleBashAllow = (event: HookEvent, decision: Decision, config: Config): void => {
+  // After the gate passes (allow or warn), apply rtk command-rewrite. If
+  // Rtk doesn't change the command, fall through to normal allow / warn.
+  const rtk = runRtkRewrite(event, config.rtk ?? { enabled: false });
+  const original = (event.tool_input as { command?: string } | undefined)?.command ?? '';
+  const rewritten =
+    rtk.updatedCommand !== undefined && rtk.updatedCommand !== original ? rtk.updatedCommand : null;
+
+  if (decision.kind === 'warn') {
+    if (rewritten !== null) {
+      writeWarn(event, { ...decision, rewriteCommand: rewritten });
+      return;
+    }
+    writeWarn(event, decision);
+    return;
+  }
+  if (rewritten !== null) {
+    writeRewriteAllow(event, rewritten, rtk.reason);
+    return;
+  }
+  writeAllow();
+};
+
+const handleAllow = (event: HookEvent, decision: Decision, config: Config): void => {
+  const eventName = event.hook_event_name;
+  const tool = normalizeToolName(event.tool_name ?? '');
+  if (eventName === 'PreToolUse' && tool === 'Bash') {
+    handleBashAllow(event, decision, config);
+    return;
+  }
+  if (decision.kind === 'warn') {
+    writeWarn(event, decision);
+    return;
+  }
+  writeAllow();
+};
+
+const program = Effect.gen(function* () {
+  const config = yield* loadConfig();
+  const raw = yield* Effect.promise(readStdin);
+
+  const parseExit = yield* Effect.exit(
+    Effect.try({ try: () => JSON.parse(raw) as unknown, catch: (e) => e }),
+  );
+  if (Exit.isFailure(parseExit)) {
+    logError('parse', Cause.pretty(parseExit.cause));
+    writeAllow();
+    return;
+  }
+
+  const decodeExit = yield* Effect.exit(
+    Schema.decodeUnknownEffect(HookEventSchema)(parseExit.value),
+  );
+  if (Exit.isFailure(decodeExit)) {
+    logError('decode', Cause.pretty(decodeExit.cause));
+    writeAllow();
+    return;
+  }
+  const event = decodeExit.value;
+  const tool = normalizeToolName(event.tool_name ?? '');
+
+  if (event.hook_event_name === 'PreToolUse') {
+    const rules = collectPreToolUseRules(tool, event.tool_input, config);
+    const decision = yield* runRules(rules, RULE_TIMEOUT_MS);
+    if (decision.kind === 'deny' || decision.kind === 'ask') {
+      writePreToolGate(event.hook_event_name, decision);
+      return;
+    }
+    handleAllow(event, decision, config);
+    return;
+  }
+
+  if (event.hook_event_name === 'PostToolUse') {
+    const rules = collectPostToolUseRules(tool, event.tool_response);
+    const decision = yield* runRules(rules, POST_RULE_TIMEOUT_MS);
+    if (decision.kind === 'deny') {
+      writePostToolBlock(decision);
+      return;
+    }
+    writeAllow();
+    return;
+  }
+
+  writeAllow();
+});
+
+const handled = program.pipe(
+  Effect.catchCause((cause) => {
+    logError('dispatch-fatal', Cause.pretty(cause));
+    writeAllow();
+    return Effect.void;
+  }),
+);
+
+BunRuntime.runMain(handled);

package/src/index.ts

@@ -0,0 +1,4 @@
+export type { Decision } from './lib/decision.ts';
+export type { HookEvent } from './lib/event.ts';
+export type { Config } from './lib/config.ts';
+export { allow, deny, ask, warn } from './lib/decision.ts';