@hasna/hooks 0.9.0 → 0.9.1

package/dist/storage.js

@@ -458,6 +458,18 @@ function runRetention(db, days) {
 import { Database } from "bun:sqlite";
 import { existsSync as existsSync3, mkdirSync, cpSync } from "fs";
 import { join as join3 } from "path";
+function refuseLocalStore(message) {
+  localStoreRefusal = message;
+}
+function allowLocalStore() {
+  localStoreRefusal = null;
+}
+function isLocalStoreRefused() {
+  return localStoreRefusal !== null;
+}
+function localStoreRefusalMessage() {
+  return localStoreRefusal;
+}
 function resolveDataDir() {
   const effective = getEffectiveDataRoot();
   const oldDir = join3(getHomeDir(), ".hooks");
@@ -481,6 +493,8 @@ function ensureDir(dbPath) {
   }
 }
 function getDb() {
+  if (localStoreRefusal !== null)
+    throw new Error(localStoreRefusal);
   if (instance)
     return instance;
   const dbPath = getDbPath();
@@ -506,7 +520,7 @@ function getDb() {
   }
   return instance;
 }
-var instance = null;
+var instance = null, localStoreRefusal = null;
 var init_db = __esm(() => {
   init_app_home();
   init_migrations();

package/hooks/hook-trash-guard/README.md

@@ -94,8 +94,7 @@ advisory warning.
 The registration is written with `timeout: 5`. The harness's documented
 default is 600s, and a hook that times out **does not block** — only a verdict
 already on stdout does. Five seconds is several orders of magnitude above this
-hook's measured cost (a single-pass lexer, no process spawns, no I/O beyond
-one `statSync` per PATH entry).
+hook's measured cost (a bounded lexer and a 500 ms identity check against a verified package binary).
 
 ## Known limitations
 
@@ -111,8 +110,7 @@ The guard is a best-effort **text** classifier, not an execution sandbox.
   here.
 - **A hook only ever sees the agent's own tool calls.** It cannot stop a file
   being deleted by another process, by a build tool, by a script the agent
-  runs, or by `unlink(2)` called directly. Coverage is the Bash tool, wave 1,
-  nothing else — `Write`/`Edit` pre-image capture is wave 2.
+  runs, or by `unlink(2)` called directly. Bash `rm` is rewritten, and native `apply_patch` whole-file deletion is refused with an instruction to call Trash first. Ordinary `Write`/`Edit` pre-image capture is not implemented.
 - **Nested and generated commands escape it.** `bash -c`, `eval`, `make`,
   `npm run`, a `Dockerfile`, a heredoc-fed interpreter: the hook can only see
   that a shell string mentions a delete verb and refuse it, never redirect
@@ -128,5 +126,22 @@ The guard is a best-effort **text** classifier, not an execution sandbox.
 ## Configuration
 
 None. The home directory comes from `os.homedir()`; the trash binary is
-resolved by scanning `PATH` for an executable `trash` and rewriting to the
+resolved by scanning `PATH` for a verified `@hasna/trash` package and its `--identity` protocol and rewriting to the
 absolute path found, so the rewritten command does not depend on `PATH` again.
+
+## Native Codex and Claude
+
+The guard emits their documented `PreToolUse` decision contract, including a
+complete `updatedInput.command`. No-op hooks emit no output. Codex unified exec
+also matches `Bash`; a `Delete File` patch must use `trash put` first. Configure
+Codex in `~/.codex/hooks.json` with matcher
+`^(Bash|apply_patch|ApplyPatch|functions\\.apply_patch)$` and the command
+`hooks run trash-guard`, with hook timeout 5 seconds. Preserve other registrations
+and refuse a second overlapping input-rewriting hook. Claude registration uses
+`hooks install trash-guard --target claude`. The command rewrite defaults to
+600 seconds for upload and verification, preserving an explicitly supplied timeout.
+
+After installation, prove the native harness actually executes the rewritten
+command using a disposable file and a hosted entry/restore receipt; a hook JSON
+response alone does not prove interception. Other harnesses can use the Trash
+CLI/MCP directly; this hook does not claim their native interception.

package/hooks/hook-trash-guard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trash-guard",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Codewith-native Trash Guard hook for @hasna/hooks",
   "type": "module",
   "main": "./src/hook.ts",

package/hooks/hook-trash-guard/src/hook.ts

@@ -47,8 +47,9 @@
  */
 
 import { homedir } from "os";
-import { isAbsolute, join, normalize, resolve, sep } from "path";
-import { statSync } from "fs";
+import { dirname, isAbsolute, join, normalize, resolve, sep } from "path";
+import { readFileSync, realpathSync, statSync } from "fs";
+import { spawnSync } from "node:child_process";
 import {
   SYSTEM_PROTECTED_ROOTS,
   getCommand,
@@ -63,10 +64,10 @@ const RULE = "trash-guard";
 
 /**
  * Default Bash-tool timeout (ms) re-supplied on the rewrite. The rewritten
- * command is a same-device move, not a byte copy, so it is fast; an explicit
+ * command uploads and verifies the hosted capsule before source cleanup; an explicit
  * value keeps the rewritten tool_input complete.
  */
-const DEFAULT_TIMEOUT_MS = 120000;
+const DEFAULT_TIMEOUT_MS = 600000;
 
 /** Description supplied only when the model did not provide one. */
 const DEFAULT_DESCRIPTION = "Delete via trash guard (rm intercepted and made recoverable)";
@@ -864,22 +865,37 @@ function gitHasDryRun(segment: Segment, verbIndex: number): boolean {
 /* ------------------------------------------------------------------ */
 
 /**
- * Locate the `trash` executable on PATH and return its absolute path, or null
- * when there is nothing to redirect to. Presence only — the guard decision
- * never waits on the binary, its store, or a network.
+ * A command called trash may be Apple's unrelated system utility. Resolve
+ * package provenance before executing a bounded, credential-free identity
+ * probe. Never invoke an unknown executable merely to discover what it is.
  */
 export function findTrashBinary(env: NodeJS.ProcessEnv = process.env): string | null {
   const pathValue = env.PATH ?? "";
-  for (const dir of pathValue.split(":")) {
-    if (!dir) continue;
-    // resolve(): a relative PATH entry still yields the absolute path the
-    // rewrite must use, so the rewritten command never depends on PATH again.
+  const deadline = Date.now() + 2_000;
+  for (const dir of pathValue.split(":").slice(0, 64)) {
+    if (!isAbsolute(dir) || Date.now() >= deadline) continue;
     const candidate = resolve(dir, "trash");
     try {
       const stat = statSync(candidate);
-      if (stat.isFile() && (stat.mode & 0o111) !== 0) return candidate;
+      if (!stat.isFile() || (stat.mode & 0o111) === 0 || (stat.mode & 0o022) !== 0) continue;
+      const executable = realpathSync(candidate);
+      const packageRoot = resolve(dirname(executable), "../..");
+      const manifestPath = join(packageRoot, "package.json");
+      const manifestStat = statSync(manifestPath);
+      if (!manifestStat.isFile() || manifestStat.size > 16_384 || (manifestStat.mode & 0o022) !== 0) continue;
+      const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+      if (manifest.name !== "@hasna/trash" || typeof manifest.version !== "string" ||
+          typeof manifest.bin?.trash !== "string" || realpathSync(resolve(packageRoot, manifest.bin.trash)) !== executable) continue;
+      const probe = spawnSync(candidate, ["--identity"], {
+        encoding: "utf8", timeout: Math.max(1, Math.min(500, deadline - Date.now())), maxBuffer: 2_048,
+        env: { PATH: pathValue }, stdio: ["ignore", "pipe", "pipe"],
+      });
+      if (probe.error || probe.status !== 0) continue;
+      const identity = JSON.parse(probe.stdout);
+      if (identity.name === "@hasna/trash" && identity.version === manifest.version &&
+          identity.guardProtocol === "hasna.trash.guard.v1") return candidate;
     } catch {
-      // not there — keep looking
+      // Missing, unrelated, malformed or unresponsive packages are not targets.
     }
   }
   return null;
@@ -1004,10 +1020,18 @@ function resolveTrash(deps: GuardDependencies): { path: string | null; error: st
 }
 
 const ABSENT_REASON =
-  "[trash-guard] `trash` is not on PATH, so this `rm` cannot be redirected into a recoverable delete — and an unrecoverable delete is never allowed, so the command is refused rather than run. Install @hasna/trash (`npm install -g @hasna/trash`), which puts the binary on PATH, then re-run the same command: it is then rewritten to `trash guard` and the files land in trash instead of disappearing.";
+  "[trash-guard] No verified @hasna/trash guard was found on PATH. This deletion is refused. Install the current @hasna/trash package with Bun and run its setup; the operating-system trash utility is not a compatible guard.";
 
 export function evaluate(input: CodewithHookInput, deps: GuardDependencies): CodewithHookOutput {
   if (input.hook_event_name !== "PreToolUse") return { continue: true };
+  if (["apply_patch", "ApplyPatch", "functions.apply_patch"].includes(input.tool_name ?? "")) {
+    const patch = input.tool_input?.command;
+    if (typeof patch !== "string") return deny("[trash-guard] Unreadable patch input; deletion safety cannot be checked.");
+    if (/^\s*\*\*\* Delete File:/m.test(patch)) {
+      return deny("[trash-guard] Delete File would bypass recoverable deletion. First use `trash put -- <path>` or the trash_put MCP tool, then submit any remaining edits without the deletion block.");
+    }
+    return { continue: true };
+  }
   if (input.tool_name !== "Bash") return { continue: true };
 
   // A command we cannot READ is a payload we cannot verify, and the harness
@@ -1089,7 +1113,7 @@ export function evaluate(input: CodewithHookInput, deps: GuardDependencies): Cod
 
 /** Verdict used when the hook itself fails: refuse anything that could delete. */
 export function fallbackVerdict(command: string): CodewithHookOutput {
-  return mentionsDeleteVerb(command)
+  return mentionsDeleteVerb(command) || /^\s*\*\*\* Delete File:/m.test(command)
     ? deny(
         "[trash-guard] The hook failed while classifying this command, so it cannot be proven free of an unredirected delete. Re-run the delete as a plain `rm -- <path>` command.",
       )
@@ -1101,10 +1125,14 @@ export async function run(): Promise<void> {
   const command = getCommand(input);
   try {
     const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
-    respond(evaluate(input, { home: homedir(), cwd, findTrash: findTrashBinary }));
+    const verdict = evaluate(input, { home: homedir(), cwd, findTrash: findTrashBinary });
+    // Native Codex rejects `continue` in PreToolUse JSON. Silence is the
+    // documented no-op for both Codex and Claude; emit only actual decisions.
+    if (!("continue" in verdict && verdict.continue === true)) respond(verdict);
   } catch (error) {
     warn(`${RULE} failed: ${error instanceof Error ? error.message : String(error)}`);
-    respond(fallbackVerdict(command));
+    const verdict = fallbackVerdict(command);
+    if (!("continue" in verdict && verdict.continue === true)) respond(verdict);
   }
 }
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@hasna/hooks",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Open source hooks library for AI coding agents - Install safety, quality, and automation hooks with a single command",
   "type": "module",
   "bin": {
     "hooks": "bin/index.js",
+    "hooks-mcp": "bin/hooks-mcp.js",
     "hooks-serve": "bin/serve.js"
   },
   "exports": {
@@ -12,6 +13,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./sdk": {
+      "types": "./dist/sdk/index.d.ts",
+      "import": "./dist/sdk/index.js"
+    },
     "./storage": {
       "types": "./dist/storage.d.ts",
       "import": "./dist/storage.js"
@@ -20,7 +25,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:types",
+    "build": "rm -rf dist bin && bun build ./src/cli/index.tsx --outdir ./bin --target bun --external pg --external ink --external react --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/serve.ts --outdir ./bin --target bun --external pg && bun build ./src/mcp/hooks-mcp.ts --outdir ./bin --target bun --external pg --external chalk --external conf --external @modelcontextprotocol/sdk --external zod && bun build ./src/sdk/index.ts --outdir ./dist/sdk --target bun && bun build ./src/index.ts ./src/storage.ts --outdir ./dist --target bun --external pg && bun run build:types",
     "build:types": "tsc -p tsconfig.build.json",
     "dev": "bun run ./src/cli/index.tsx",
     "test": "bun test",

package/scripts/validate-package.ts

@@ -173,15 +173,27 @@ async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
     const dataDir = join(workspace, "data");
     const binIndex = join(packageDir, "bin", "index.js");
     const binServe = join(packageDir, "bin", "serve.js");
+    const binMcp = join(packageDir, "bin", "hooks-mcp.js");
+    const sdkBundle = join(packageDir, "dist", "sdk", "index.js");
     if (!existsSync(binIndex)) throw new Error(`packed tarball is missing bin/index.js (CLI bin)`);
     if (!existsSync(binServe)) throw new Error(`packed tarball is missing bin/serve.js (serve bin)`);
+    if (!existsSync(binMcp)) throw new Error(`packed tarball is missing bin/hooks-mcp.js (MCP bin)`);
+    if (!existsSync(sdkBundle)) throw new Error(`packed tarball is missing dist/sdk/index.js (./sdk export)`);
 
+    // Hermetic route: the smoke lanes below exercise the on-box store on
+    // purpose, so they opt in explicitly (hasna/apps#1720 — without the
+    // opt-in `hooks run` and `hooks-mcp` fail closed, which the fail-closed
+    // lane checks separately) and keep the station's Keychain out of it.
     const env = {
       ...process.env,
+      HASNA_STATION: "no-such-station",
+      HASNA_HOOKS_LOCAL: "1",
       HASNA_HOOKS_DATA_DIR: dataDir,
       HASNA_HOOKS_DB_PATH: join(dataDir, "hooks.db"),
       NO_COLOR: "1",
     };
+    const failClosedEnv = { ...env };
+    delete (failClosedEnv as Record<string, string | undefined>).HASNA_HOOKS_LOCAL;
 
     // 1. CLI help.
     const help = spawnSync("bun", ["run", binIndex, "--help"], { cwd: smokeDir, env, encoding: "utf8" });
@@ -210,8 +222,22 @@ async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
       await new Promise((r) => setTimeout(r, 100));
     }
 
-    // 3. MCP stdio startup: an initialize handshake must get a response.
-    const mcpProc = spawn("bun", ["run", binIndex, "mcp", "--stdio"], {
+    // 2b. Fail-closed lane (hasna/apps#1720): with nothing configured the
+    // packed CLI and the packed hooks-mcp bin exit non-zero, name the
+    // credential tiers + the opt-in on stderr, and create no local store.
+    const failClosedHome = join(workspace, "failclosed-home");
+    const fcEnv = { ...failClosedEnv, HOME: failClosedHome, HASNA_HOOKS_DATA_DIR: join(failClosedHome, "data"), HASNA_HOOKS_DB_PATH: join(failClosedHome, "data", "hooks.db") };
+    for (const [label, argv] of [["packed CLI `hooks categories`", [binIndex, "categories"]], ["packed hooks-mcp", [binMcp]]] as Array<[string, string[]]>) {
+      const fc = spawnSync("bun", ["run", ...argv], { cwd: smokeDir, env: fcEnv, encoding: "utf8", input: "", timeout: 20000 });
+      if (fc.status === 0) throw new Error(`${label} exited 0 with nothing configured (must fail closed)`);
+      if (!/HASNA_HOOKS_LOCAL=1/.test(fc.stderr) || !/hasna\.credentials\.hooks\.api-key/.test(fc.stderr)) {
+        throw new Error(`${label} refusal did not name the tiers + opt-in: ${fc.stderr.slice(0, 300)}`);
+      }
+      if (existsSync(join(failClosedHome, "data", "hooks.db"))) throw new Error(`${label} created hooks.db while failing closed`);
+    }
+
+    // 3. MCP stdio startup (explicit local opt-in): an initialize handshake must get a response.
+    const mcpProc = spawn("bun", ["run", binMcp], {
       cwd: smokeDir,
       env,
       stdio: ["pipe", "pipe", "pipe"],
@@ -252,11 +278,12 @@ async function validateExtractedSmoke(pkg: PackageJson): Promise<void> {
       // pg link is best-effort; the import below will fail loudly if needed.
     }
     const sdkSmoke = join(smokeDir, "sdk-smoke.ts");
-    await writeFile(sdkSmoke, `import { HOOKS, getStorageStatus } from "@hasna/hooks";\nimport { getStorageStatus as ss } from "@hasna/hooks/storage";\nconsole.log(JSON.stringify({ count: HOOKS.length, backend: getStorageStatus().backend, ss: ss().backend }));\n`);
+    await writeFile(sdkSmoke, `import { HOOKS, getStorageStatus } from "@hasna/hooks";\nimport { getStorageStatus as ss } from "@hasna/hooks/storage";\nimport { HooksClient, createHooksClient } from "@hasna/hooks/sdk";\nlet sdk = "threw";\ntry { createHooksClient({ env: { HASNA_STATION: "no-such-station" }, credentials: { keychain: { enabled: false } } }); sdk = "returned"; } catch (e) { sdk = /REMOTE_API_/.test(String(e)) ? "fail-closed" : "threw"; }\nconsole.log(JSON.stringify({ count: HOOKS.length, backend: getStorageStatus().backend, ss: ss().backend, sdk, hasClient: typeof HooksClient === "function" }));\n`);
     const sdk = spawnSync("bun", ["run", sdkSmoke], { cwd: smokeDir, env, encoding: "utf8", timeout: 20000 });
     if (sdk.status !== 0) throw new Error(`packed SDK import failed: ${sdk.stderr}`);
-    const sdkOut = JSON.parse(sdk.stdout.trim()) as { count: number; backend: string };
+    const sdkOut = JSON.parse(sdk.stdout.trim()) as { count: number; backend: string; sdk: string; hasClient: boolean };
     if (typeof sdkOut.count !== "number" || sdkOut.count <= 0) throw new Error(`packed SDK import returned count ${sdkOut.count}`);
+    if (sdkOut.sdk !== "fail-closed" || !sdkOut.hasClient) throw new Error(`packed ./sdk export did not fail closed with nothing configured: ${JSON.stringify(sdkOut)}`);
 
     // 5. One bundled-hook run from the packed artifact (isolated data dir;
     // first run self-trusts, then executes).