@hasna/hooks 0.10.3 → 0.10.5

package/dist/native-safety.js

@@ -0,0 +1,401 @@
+// @bun
+// src/native-safety.ts
+import { execFile } from "child_process";
+import { createHash as createHash2, randomUUID } from "crypto";
+import { closeSync as closeSync2, constants as constants2, existsSync as existsSync2, fstatSync as fstatSync2, fsyncSync, linkSync, lstatSync as lstatSync2, mkdirSync, openSync as openSync2, readFileSync as readFileSync2, realpathSync as realpathSync2, renameSync, unlinkSync, writeFileSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, isAbsolute as isAbsolute2, join as join2, resolve } from "path";
+
+// src/lib/native-safety.ts
+import { createHash } from "crypto";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, realpathSync } from "fs";
+import { dirname, isAbsolute, join } from "path";
+import { homedir } from "os";
+function isNativeSafetyName(name) {
+  return name === "trash-guard" || name === "workspace-repos-guard";
+}
+var supervisorSource = String.raw`async function supervise(encoded) {
+  const fs = require("node:fs");
+  const path = require("node:path");
+  const crypto = require("node:crypto");
+  const cp = require("node:child_process");
+  const fail = () => { process.stderr.write("Native safety guard refused: verification or execution failed.\n"); process.exit(2); };
+  try {
+    const b = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    const check = (file, hash, maximum) => {
+      if (!path.isAbsolute(file) || fs.realpathSync(file) !== file) throw Error();
+      for (let parent = path.dirname(file);;) {
+        const s = fs.lstatSync(parent);
+        if (!s.isDirectory() || ![0, process.getuid()].includes(s.uid) || (s.mode & 0o022)) throw Error();
+        if (parent === path.dirname(parent)) break;
+        parent = path.dirname(parent);
+      }
+      const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+      try {
+        const s = fs.fstatSync(fd);
+        if (!s.isFile() || ![0, process.getuid()].includes(s.uid) || (s.mode & 0o022) || s.size > maximum) throw Error();
+        const bytes = fs.readFileSync(fd);
+        if (crypto.createHash("sha256").update(bytes).digest("hex") !== hash) throw Error();
+        return bytes;
+      } finally { fs.closeSync(fd); }
+    };
+    check(b.runtime, b.runtimeSHA256, 200_000_000);
+    const bytes = check(b.worker, b.workerSHA256, 256_000);
+    const deadline = setTimeout(fail, 1500);
+    const chunks = []; let size = 0;
+    for await (const chunk of process.stdin) {
+      size += chunk.length;
+      if (size > 1_048_576) throw Error();
+      chunks.push(chunk);
+    }
+    clearTimeout(deadline);
+    const input = Buffer.concat(chunks);
+    const child = cp.spawnSync(b.runtime, ["--config=/dev/null", "--no-env-file", "--no-macros", "--no-install", "--eval", bytes.toString("utf8"), b.name], {
+      input, env: { HOME: b.home, PATH: b.path }, cwd: "/", timeout: 2500, killSignal: "SIGKILL", maxBuffer: 1_048_576,
+    });
+    if (child.error || child.status !== 0 || child.signal || child.stderr.length) throw Error();
+    const result = JSON.parse(child.stdout.toString("utf8"));
+    if (!result || Array.isArray(result) || Object.keys(result).length !== 1) throw Error();
+    if (result.verdict === null) return;
+    const output = result.verdict?.hookSpecificOutput;
+    if (!output || Object.keys(result.verdict).length !== 1 || output.hookEventName !== "PreToolUse") throw Error();
+    if (output.permissionDecision === "deny") {
+      if (Object.keys(output).sort().join() !== "hookEventName,permissionDecision,permissionDecisionReason" || typeof output.permissionDecisionReason !== "string" || !output.permissionDecisionReason.trim()) throw Error();
+    } else if (output.permissionDecision === "allow") {
+      if (b.name !== "trash-guard" || Object.keys(output).sort().join() !== "hookEventName,permissionDecision,updatedInput" || !output.updatedInput || typeof output.updatedInput.command !== "string" || !output.updatedInput.command.trim()) throw Error();
+    } else throw Error();
+    process.stdout.write(JSON.stringify(result.verdict));
+  } catch { fail(); }
+}`;
+var quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+var program = `(${supervisorSource})(process.argv[1]);`;
+var shell = `cd / || exit 2
+exec 3<&0 || exit 2
+/usr/bin/env -i HOME="$3" PATH="$4" "$2" --config=/dev/null --no-env-file --no-macros --no-install --eval ${quote(program)} "$1" <&3 3<&- 2>/dev/null &
+runner=$!
+exec 3<&-
+(trap 'kill "$sleeper" 2>/dev/null; exit 0' TERM; /bin/sleep 6 & sleeper=$!; wait "$sleeper"; kill -KILL "$runner" 2>/dev/null) &
+watchdog=$!
+wait "$runner"; result=$?
+kill "$watchdog" 2>/dev/null; wait "$watchdog" 2>/dev/null
+if [ "$result" -ne 0 ]; then printf '%s\\n' 'Native safety guard refused: verification or execution failed.' >&2; exit 2; fi`;
+var prefix = `/usr/bin/env -i /bin/sh -c ${quote(shell)} hasna-native-safety-v1 `;
+function validateBinding(b) {
+  if (!b || !isNativeSafetyName(b.name) || ![b.runtime, b.worker, b.home].every((p) => typeof p === "string" && isAbsolute(p) && !/[\0\r\n]/.test(p)) || ![b.runtimeSHA256, b.workerSHA256].every((h) => /^[0-9a-f]{64}$/.test(h)) || typeof b.path !== "string" || b.path.split(":").some((p) => !isAbsolute(p) || /[\0\r\n]/.test(p)))
+    throw new Error("Invalid native safety binding");
+}
+function buildNativeSafetyCommand(binding) {
+  validateBinding(binding);
+  const encoded = Buffer.from(JSON.stringify(binding)).toString("base64url");
+  return prefix + [encoded, binding.runtime, binding.home, binding.path].map(quote).join(" ");
+}
+function nativeSafetyCommandBinding(command) {
+  if (!command.startsWith(prefix))
+    return;
+  const encoded = command.slice(prefix.length).match(/^'([A-Za-z0-9_-]+)' /)?.[1];
+  if (!encoded || encoded.length > 16384)
+    return;
+  try {
+    const binding = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    return buildNativeSafetyCommand(binding) === command ? binding : undefined;
+  } catch {
+    return;
+  }
+}
+function pinEligibleFile(file, maximum, executable = false) {
+  if (!isAbsolute(file) || realpathSync(file) !== file)
+    throw new Error("Native safety requires canonical files");
+  for (let parent = dirname(file);; ) {
+    const s = lstatSync(parent);
+    if (!s.isDirectory() || ![0, process.getuid()].includes(s.uid) || s.mode & 18)
+      throw new Error("Native safety requires trusted, non-writable file ancestry");
+    if (parent === dirname(parent))
+      break;
+    parent = dirname(parent);
+  }
+  const fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const s = fstatSync(fd);
+    if (!s.isFile() || ![0, process.getuid()].includes(s.uid) || s.mode & 18 || s.size > maximum || executable && !(s.mode & 64))
+      throw new Error("Native safety requires an eligible installed file");
+    const bytes = readFileSync(fd);
+    if (bytes.length > maximum)
+      throw new Error("Native safety file exceeds its bound");
+    return createHash("sha256").update(bytes).digest("hex");
+  } finally {
+    closeSync(fd);
+  }
+}
+function installedNativeSafetyCommand(name) {
+  const home = realpathSync(homedir());
+  const runtime = realpathSync(process.execPath);
+  const candidates = [join(import.meta.dir, "../../bin/native-safety-entry.js"), join(import.meta.dir, "../bin/native-safety-entry.js"), join(import.meta.dir, "native-safety-entry.js")];
+  const worker = candidates.find(existsSync);
+  if (!worker)
+    throw new Error("Bundled native safety runner is missing; build or reinstall @hasna/hooks before installing its guards.");
+  const canonicalWorker = realpathSync(worker);
+  return buildNativeSafetyCommand({ name, runtime, runtimeSHA256: pinEligibleFile(runtime, 200000000, true), worker: canonicalWorker, workerSHA256: pinEligibleFile(canonicalWorker, 256000), home, path: `${dirname(runtime)}:${join(home, ".bun/bin")}:/usr/local/bin:/usr/bin:/bin` });
+}
+
+// src/native-safety.ts
+class NativeSafetyError extends Error {
+  code;
+  reason;
+  constructor(code, reason) {
+    super(`Native deletion safety refused (${code}). Run the reviewed Hooks safety setup before using shell or patch tools.`);
+    this.code = code;
+    this.reason = reason;
+    this.name = "NativeSafetyError";
+  }
+}
+var executionSchema = "hasna.hooks.execution.v1";
+var hash = (value) => createHash2("sha256").update(value).digest("hex");
+var filename = "sumi-trash-guard.json";
+var owner = (uid) => uid === 0 || uid === process.getuid?.();
+function safeDirectory(path) {
+  for (let cursor = path;; cursor = dirname2(cursor)) {
+    const stat = lstatSync2(cursor);
+    if (!stat.isDirectory() || !owner(stat.uid) || stat.mode & 18)
+      throw new NativeSafetyError("binding_invalid");
+    if (dirname2(cursor) === cursor)
+      return;
+  }
+}
+function canonicalHome(home) {
+  if (!isAbsolute2(home) || home.includes("\x00") || realpathSync2(home) !== resolve(home))
+    throw new NativeSafetyError("binding_invalid");
+  safeDirectory(home);
+  return resolve(home);
+}
+function readOwned(path) {
+  safeDirectory(dirname2(path));
+  const fd = openSync2(path, constants2.O_RDONLY | constants2.O_NOFOLLOW | constants2.O_NONBLOCK);
+  try {
+    const stat = fstatSync2(fd);
+    if (!stat.isFile() || !owner(stat.uid) || stat.mode & 63 || stat.size > 32768)
+      throw new NativeSafetyError("binding_invalid");
+    const value = readFileSync2(fd, "utf8");
+    if (Buffer.byteLength(value) > 32768)
+      throw new NativeSafetyError("binding_invalid");
+    return value;
+  } finally {
+    closeSync2(fd);
+  }
+}
+function parseRecord(text, home) {
+  const record = JSON.parse(text);
+  if (!record || Array.isArray(record) || Object.keys(record).sort().join() !== "command,harness,schema" || record.schema !== "hasna.hooks.native-safety.v1" || record.harness !== "sumi" || typeof record.command !== "string")
+    throw new NativeSafetyError("binding_invalid");
+  const binding = nativeSafetyCommandBinding(record.command);
+  if (binding?.name !== "trash-guard" || binding.home !== home)
+    throw new NativeSafetyError("binding_invalid");
+  return record;
+}
+function syncDirectory(path) {
+  const fd = openSync2(path, constants2.O_RDONLY | constants2.O_DIRECTORY | constants2.O_NOFOLLOW);
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync2(fd);
+  }
+}
+function readNativeSafetyRegistration(home = homedir2()) {
+  try {
+    home = canonicalHome(home);
+    const path = join2(home, ".hasna/hooks/native", filename), text = readOwned(path);
+    return { record: parseRecord(text, home), sha256: hash(text), path };
+  } catch (error) {
+    if (error instanceof NativeSafetyError)
+      throw error;
+    throw new NativeSafetyError(error?.code === "ENOENT" ? "binding_missing" : "binding_invalid");
+  }
+}
+function registerNativeSafety(options = {}) {
+  const home = canonicalHome(options.home ?? homedir2());
+  const record = { schema: "hasna.hooks.native-safety.v1", harness: "sumi", command: options.command ?? installedNativeSafetyCommand("trash-guard") };
+  const text = JSON.stringify(record) + `
+`;
+  parseRecord(text, home);
+  for (const dir of [join2(home, ".hasna"), join2(home, ".hasna/hooks"), join2(home, ".hasna/hooks/native")]) {
+    try {
+      mkdirSync(dir, { mode: 448 });
+      syncDirectory(dirname2(dir));
+    } catch (error) {
+      if (error.code !== "EEXIST")
+        throw error;
+    }
+    safeDirectory(dir);
+  }
+  const directory = join2(home, ".hasna/hooks/native"), path = join2(directory, filename), lock = path + ".lock";
+  let lockFD;
+  try {
+    lockFD = openSync2(lock, constants2.O_CREAT | constants2.O_EXCL | constants2.O_WRONLY, 384);
+  } catch {
+    throw new NativeSafetyError("binding_busy");
+  }
+  const lockIdentity = fstatSync2(lockFD);
+  let temporaryIdentity;
+  const temporary = join2(directory, `.${filename}.${randomUUID()}`);
+  try {
+    writeFileSync(lockFD, JSON.stringify({ pid: process.pid, expectedSHA256: options.expectedSHA256 ?? "absent" }));
+    fsyncSync(lockFD);
+    syncDirectory(directory);
+    let before;
+    try {
+      before = readNativeSafetyRegistration(home);
+    } catch (error) {
+      if (!(error instanceof NativeSafetyError) || error.code !== "binding_missing")
+        throw error;
+    }
+    if (before?.sha256 === hash(text))
+      return { ok: true, changed: false, path, sha256: before.sha256 };
+    if (before ? options.expectedSHA256 !== before.sha256 : options.expectedSHA256 !== undefined && options.expectedSHA256 !== "absent")
+      throw new NativeSafetyError("binding_changed");
+    if (before) {
+      const backup = path + ".before-" + before.sha256;
+      if (existsSync2(backup)) {
+        if (hash(readOwned(backup)) !== before.sha256)
+          throw new NativeSafetyError("binding_changed");
+      } else {
+        const original = readOwned(path);
+        if (hash(original) !== before.sha256)
+          throw new NativeSafetyError("binding_changed");
+        const fd2 = openSync2(backup, constants2.O_CREAT | constants2.O_EXCL | constants2.O_WRONLY, 384);
+        try {
+          writeFileSync(fd2, original);
+          fsyncSync(fd2);
+        } finally {
+          closeSync2(fd2);
+        }
+        syncDirectory(directory);
+      }
+    }
+    const fd = openSync2(temporary, constants2.O_CREAT | constants2.O_EXCL | constants2.O_WRONLY, 384);
+    try {
+      temporaryIdentity = fstatSync2(fd);
+      writeFileSync(fd, text);
+      fsyncSync(fd);
+    } finally {
+      closeSync2(fd);
+    }
+    if (before) {
+      if (hash(readOwned(path)) !== before.sha256)
+        throw new NativeSafetyError("binding_changed");
+      renameSync(temporary, path);
+    } else {
+      linkSync(temporary, path);
+      unlinkSync(temporary);
+    }
+    syncDirectory(directory);
+    const after = readNativeSafetyRegistration(home);
+    if (after.sha256 !== hash(text))
+      throw new NativeSafetyError("binding_changed");
+    return { ok: true, changed: true, path, sha256: after.sha256 };
+  } finally {
+    closeSync2(lockFD);
+    const currentTemporary = lstatSync2(temporary, { throwIfNoEntry: false });
+    if (temporaryIdentity && currentTemporary?.dev === temporaryIdentity.dev && currentTemporary.ino === temporaryIdentity.ino)
+      unlinkSync(temporary);
+    const currentLock = lstatSync2(lock, { throwIfNoEntry: false });
+    if (currentLock?.dev !== lockIdentity.dev || currentLock.ino !== lockIdentity.ino)
+      throw new NativeSafetyError("binding_changed");
+    unlinkSync(lock);
+    syncDirectory(directory);
+  }
+}
+async function evaluateNativeSafety(event, options = {}) {
+  return evaluateRecord(event, readNativeSafetyRegistration(options.home).record, options.signal);
+}
+async function evaluateNativeSafetyForExecution(event, options) {
+  if (!options || typeof options.agent !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/.test(options.agent))
+    throw new NativeSafetyError("input_invalid");
+  let snapshot;
+  try {
+    snapshot = JSON.parse(JSON.stringify(event));
+  } catch {
+    throw new NativeSafetyError("input_invalid");
+  }
+  if (snapshot?.tool_input && Object.hasOwn(snapshot.tool_input, "hasna_execution"))
+    throw new NativeSafetyError("input_invalid");
+  const before = readNativeSafetyRegistration(options.home);
+  const binding = nativeSafetyCommandBinding(before.record.command);
+  const decision = await evaluateRecord(snapshot, before.record, options.signal, options.agent);
+  if (readNativeSafetyRegistration(options.home).sha256 !== before.sha256)
+    throw new NativeSafetyError("binding_changed");
+  return decision.decision === "rewrite" ? {
+    decision: "rewrite",
+    execution: { command: decision.command, shell: "/bin/sh", cwd: snapshot.cwd, env: { HOME: binding.home, PATH: binding.path } }
+  } : decision;
+}
+async function evaluateRecord(event, record, signal, executionAgent) {
+  if (!event || event.hook_event_name !== "PreToolUse" || !["Bash", "apply_patch"].includes(event.tool_name) || typeof event.cwd !== "string" || !isAbsolute2(event.cwd) || !event.tool_input || typeof event.tool_input !== "object" || Array.isArray(event.tool_input))
+    throw new NativeSafetyError("input_invalid");
+  const input = JSON.stringify(executionAgent === undefined ? event : { ...event, hasna_execution: { schema: executionSchema, agent: executionAgent } });
+  if (Buffer.byteLength(input) > 1048576)
+    throw new NativeSafetyError("input_invalid");
+  const output = await new Promise((accept, reject) => {
+    const child = execFile("/bin/sh", ["-c", record.command], { cwd: "/", env: {}, encoding: "utf8", timeout: 8000, maxBuffer: 1048576, signal }, (error, stdout, stderr) => {
+      if (error || stderr) {
+        reject(new NativeSafetyError("guard_failed"));
+        return;
+      }
+      accept(stdout);
+    });
+    child.stdin?.on("error", () => {});
+    child.stdin?.end(input);
+  });
+  if (!output)
+    return { decision: "continue" };
+  try {
+    const value = JSON.parse(output);
+    if (Object.keys(value).join() !== "hookSpecificOutput")
+      throw new Error;
+    const verdict = value.hookSpecificOutput;
+    if (verdict.hookEventName !== "PreToolUse")
+      throw new Error;
+    if (verdict.permissionDecision === "deny" && Object.keys(verdict).sort().join() === "hookEventName,permissionDecision,permissionDecisionReason" && typeof verdict.permissionDecisionReason === "string" && verdict.permissionDecisionReason.trim())
+      return { decision: "deny", reason: verdict.permissionDecisionReason };
+    if (event.tool_name === "Bash" && verdict.permissionDecision === "allow" && Object.keys(verdict).sort().join() === "hookEventName,permissionDecision,updatedInput" && typeof verdict.updatedInput?.command === "string" && verdict.updatedInput.command.trim() && (executionAgent === undefined || verdict.updatedInput.hasna_execution === executionSchema))
+      return { decision: "rewrite", command: verdict.updatedInput.command };
+  } catch {}
+  throw new NativeSafetyError("guard_failed");
+}
+async function verifyNativeSafetyCommand(command, home = homedir2()) {
+  home = canonicalHome(home);
+  const record = parseRecord(JSON.stringify({ schema: "hasna.hooks.native-safety.v1", harness: "sumi", command }), home);
+  const verdict = await evaluateRecord({ hook_event_name: "PreToolUse", tool_name: "Bash", cwd: home, tool_input: { command: "rm -- .hasna-trash-verification-only" } }, record);
+  if (verdict.decision !== "rewrite")
+    throw new NativeSafetyError("guard_failed", verdict.decision === "deny" ? verdict.reason.slice(0, 512) : undefined);
+}
+async function verifyNativeSafetyRegistration(home = homedir2()) {
+  const before = readNativeSafetyRegistration(home);
+  await verifyNativeSafetyCommand(before.record.command, home);
+  const after = readNativeSafetyRegistration(home);
+  if (after.sha256 !== before.sha256)
+    throw new NativeSafetyError("binding_changed");
+  return { path: before.path, sha256: before.sha256 };
+}
+async function verifyNativeSafetyExecutionRegistration(home = homedir2()) {
+  const before = readNativeSafetyRegistration(home);
+  const verdict = await evaluateNativeSafetyForExecution({
+    hook_event_name: "PreToolUse",
+    tool_name: "Bash",
+    cwd: home,
+    tool_input: { command: "rm -- .hasna-trash-verification-only" }
+  }, { home, agent: "native-safety-verification" });
+  if (verdict.decision !== "rewrite")
+    throw new NativeSafetyError("guard_failed", verdict.decision === "deny" ? verdict.reason.slice(0, 512) : undefined);
+  if (readNativeSafetyRegistration(home).sha256 !== before.sha256)
+    throw new NativeSafetyError("binding_changed");
+  return { path: before.path, sha256: before.sha256 };
+}
+export {
+  verifyNativeSafetyRegistration,
+  verifyNativeSafetyExecutionRegistration,
+  verifyNativeSafetyCommand,
+  registerNativeSafety,
+  readNativeSafetyRegistration,
+  evaluateNativeSafetyForExecution,
+  evaluateNativeSafety,
+  NativeSafetyError
+};

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

@@ -0,0 +1,158 @@
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { accessSync, closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, readlinkSync, readSync, realpathSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+/**
+ * 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 type TrashBinaryFailure = "missing" | "unsafe_executable" | "unsafe_manifest" | "unsafe_directory" | "unsafe_interpreter" | "unrecognized_package" | "identity_failed" | "unsupported_protocol";
+export type TrashBinaryInspection = { ok: true; path: string; version: string } | { ok: false; code: TrashBinaryFailure };
+
+export const BINARY_FAILURES: Record<TrashBinaryFailure, string> = {
+  missing: "No verified @hasna/trash guard was found on PATH.",
+  unsafe_executable: "The Trash candidate is not an owned executable file or is writable by group or others.",
+  unsafe_manifest: "The Trash package manifest is not a safe owned regular file.",
+  unsafe_directory: "A Trash PATH or package directory is not owned safely or is writable by group or others.",
+  unsafe_interpreter: "The Trash interpreter is missing, unsupported, or not a safe owned executable on its actual PATH.",
+  unrecognized_package: "The candidate is not the registered @hasna/trash executable.",
+  identity_failed: "The installed Trash identity probe failed or exceeded its deadline.",
+  unsupported_protocol: "The installed Trash version does not expose the required guard protocol.",
+};
+
+function trustedOwner(uid: number): boolean {
+  return uid === 0 || uid === process.getuid?.();
+}
+
+function safeExecutableFile(path: string, systemBinAlias = false): boolean {
+  let current = path;
+  for (let hop = 0; hop < 32; hop++) {
+    if (!isAbsolute(current) || current.length > 4096 || !safeBinaryDirectory("/")) return false;
+    const parts = current.split("/"), name = parts.pop();
+    if (!name || name === "." || name === "..") return false;
+    let parent = "/";
+    // Validate literal components before consuming ..; realpath alone hides
+    // intermediate writable symlink parents, even when its final target is safe.
+    for (const part of parts) {
+      if (!part || part === ".") continue;
+      if (part === "..") { parent = dirname(parent); continue; }
+      const next = join(parent, part), info = lstatSync(next);
+      if (systemBinAlias && next === "/bin" && info.isSymbolicLink() && info.uid === 0) {
+        const target = realpathSync(next);
+        if (!safeBinaryDirectory(target)) return false;
+        parent = target; continue;
+      }
+      if (!info.isDirectory() || !trustedOwner(info.uid) || (info.mode & 0o022)) return false;
+      parent = next;
+    }
+    const candidate = join(parent, name), info = lstatSync(candidate);
+    if (!trustedOwner(info.uid)) return false;
+    if (info.isSymbolicLink()) {
+      const target = readlinkSync(candidate);
+      current = isAbsolute(target) ? target : parent + "/" + target;
+      continue;
+    }
+    return info.isFile() && Boolean(info.mode & 0o111) && !(info.mode & 0o022);
+  }
+  return false;
+}
+
+function safeInterpreterSearchDirectory(path: string): boolean {
+  if (!isAbsolute(path) || resolve(path) !== (path.replace(/\/+$/, "") || "/")) return false;
+  // Even an earlier empty PATH directory could acquire a shadow interpreter.
+  // Missing directories are safe only beneath verified non-writable ancestry.
+  for (let cursor = resolve(path);; cursor = dirname(cursor)) {
+    try { lstatSync(cursor); return safeBinaryDirectory(cursor); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") return false; }
+    if (dirname(cursor) === cursor) return false;
+  }
+}
+
+function safeScriptInterpreter(executable: string, pathValue: string): boolean {
+  const fd = openSync(executable, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+  let header: string;
+  try {
+    if (!fstatSync(fd).isFile()) return false;
+    const bytes = Buffer.alloc(256), length = readSync(fd, bytes, 0, bytes.length, 0);
+    header = bytes.subarray(0, length).toString("utf8").split("\n")[0]!;
+  } finally { closeSync(fd); }
+  const direct = /^#!(\/[A-Za-z0-9_./-]+)$/.exec(header);
+  if (direct && direct[1] !== "/usr/bin/env") return safeExecutableFile(direct[1]!, true);
+  // The published Trash entrypoint uses this exact shebang. Do not execute an
+  // env program until the first executable it will actually select is safe.
+  // Extra env options/arguments and unresolved interpreters fail closed.
+  if (header !== "#!/usr/bin/env bun" || !safeExecutableFile("/usr/bin/env", true)) return false;
+  for (const dir of pathValue.split(":").slice(0, 64)) {
+    if (!safeInterpreterSearchDirectory(dir)) return false;
+    const interpreter = resolve(dir, "bun");
+    try {
+      if (!statSync(interpreter).isFile()) continue;
+      accessSync(interpreter, constants.X_OK);
+    } catch { continue; }
+    return safeExecutableFile(interpreter, true);
+  }
+  return false;
+}
+
+function safeBinaryDirectory(path: string): boolean {
+  let current = path;
+  for (;;) {
+    const info = lstatSync(current);
+    if (!info.isDirectory() || !trustedOwner(info.uid) || (info.mode & 0o022) !== 0) return false;
+    const parent = dirname(current);
+    if (parent === current) return true;
+    current = parent;
+  }
+}
+
+/** Bounded, credential-free diagnostic shared by pre-action guards and setup checks. */
+export function inspectTrashBinary(env: NodeJS.ProcessEnv = process.env): TrashBinaryInspection {
+  const pathValue = env.PATH ?? "";
+  const deadline = Date.now() + 2_000;
+  let failure: TrashBinaryFailure = "missing";
+  const reject = (code: TrashBinaryFailure) => {
+    // An unrelated system trash utility must not hide a later permission defect.
+    if (failure === "missing" || failure === "unrecognized_package" || code.startsWith("unsafe_")) failure = code;
+  };
+  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() || !trustedOwner(stat.uid) || (stat.mode & 0o111) === 0 || (stat.mode & 0o022) !== 0) { reject("unsafe_executable"); continue; }
+      const executable = realpathSync(candidate);
+      // Bin files may be package-manager symlinks. PATH directory ancestry must
+      // remain literal and safe: resolving it first would hide writable parents
+      // of a directory alias while probe/rewrite still used the original path.
+      if (!safeBinaryDirectory(resolve(dir)) || !safeBinaryDirectory(dirname(executable))) { reject("unsafe_directory"); continue; }
+      if (!safeExecutableFile(candidate)) { reject("unsafe_directory"); continue; }
+      const packageRoot = resolve(dirname(executable), "../..");
+      const manifestPath = join(packageRoot, "package.json");
+      const manifestStat = statSync(manifestPath);
+      if (!manifestStat.isFile() || !trustedOwner(manifestStat.uid) || manifestStat.size > 16_384 || (manifestStat.mode & 0o022) !== 0 || lstatSync(manifestPath).isSymbolicLink()) { reject("unsafe_manifest"); 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) { reject("unrecognized_package"); continue; }
+      try { if (!safeScriptInterpreter(executable, pathValue)) { reject("unsafe_interpreter"); continue; } }
+      catch { reject("unsafe_interpreter"); 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) { reject("identity_failed"); continue; }
+      const identity = JSON.parse(probe.stdout);
+      if (identity.name === "@hasna/trash" && identity.version === manifest.version &&
+          identity.guardProtocol === "hasna.trash.guard.v1") return { ok: true, path: candidate, version: manifest.version };
+      reject("unsupported_protocol");
+    } catch {
+      // Missing, unrelated, malformed or unresponsive packages are not targets.
+    }
+  }
+  return { ok: false, code: failure };
+}
+
+export function findTrashBinary(env: NodeJS.ProcessEnv = process.env): string | null {
+  const result = inspectTrashBinary(env);
+  return result.ok ? result.path : null;
+}