@theokit/sdk-tools 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -269,17 +269,28 @@ declare function buildEnvContext(cwd: string): string;
 declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
 
 /**
- * Catastrophic-command guardrail for `shell_exec` (M3-2).
- *
- * `catastrophicShellReason` is a pure, segment-aware deny-list: it splits a
- * command on top-level connectors (`;`, `&&`, `||`, pipe), strips `sudo`/`env`
- * prefixes, and matches at COMMAND POSITION (the executable, not an arbitrary
- * substring) so a mention like `echo "rm -rf /"` is not over-blocked. It returns
- * a human reason for the first catastrophic segment, else `null`.
- *
- * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by obfuscation
- * (eval/base64) and is best-effort. POSIX `/bin/sh` only; Windows PowerShell is
- * out of scope. Design: blueprint m3-catastrophic-shell. Zero new deps.
+ * Catastrophic-command guardrail for `shell_exec` (M3-2; hardened V3-1).
+ *
+ * `catastrophicShellReason` is a pure, segment-aware deny-list ported from
+ * theocode's security-reviewed `shell-guard.ts` (the proven spec: 42-blocked +
+ * 24-allowed corpus, 0 misses / 0 false-positives). It splits a command on shell
+ * separators (`;`, `&&`, `||`, `|`, `&`, newline), inspects EVERY segment (so a
+ * chained `rm -rf <safe>; rm -rf /` cannot hide), and matches at COMMAND POSITION
+ * (the executable, not an arbitrary substring) so a mention like `echo "rm -rf /"`
+ * is not over-blocked. Returns a human reason for the first catastrophic segment,
+ * else `null`.
+ *
+ * Categories: recursive-force `rm` of an absolute/home/parent path; destructive git
+ * (force-push, `reset --hard`, `clean -fd`); remote-code-execution (curl/wget piped
+ * OR command-substitution `$( )` / `<( )` / eval / source); disk/raw-device wipe
+ * (mkfs, `dd of=/dev/`, `truncate /dev/`, `> /dev/<blockdev>`); recursive chmod/chown
+ * of a root path (SDK extra); fork bomb; `find -delete` / `-exec rm`; secret-file
+ * exfiltration over the network.
+ *
+ * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by deep obfuscation
+ * (base64/env-indirection) and is best-effort. POSIX `/bin/sh` only; Windows
+ * PowerShell is out of scope. True isolation needs a container.
+ * referencia: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
  */
 
 /** Thrown / reported when a command matches the catastrophic deny-list. */
@@ -288,10 +299,10 @@ declare class CatastrophicCommandError extends ConfigurationError {
     constructor(reason: string);
 }
 /**
- * Returns a human reason if `cmd` contains a catastrophic command (in any
- * segment, across chains/sudo/pipes), else `null`.
+ * Return a human-readable reason when `command` is catastrophic/irreversible, or `null`.
+ * The message is surfaced to the model so it self-corrects.
  */
-declare function catastrophicShellReason(cmd: string): string | null;
+declare function catastrophicShellReason(command: string): string | null;
 
 /**
  * ACI (Agent-Computer Interface) helpers for tools (M3-5).

package/dist/index.d.ts

@@ -269,17 +269,28 @@ declare function buildEnvContext(cwd: string): string;
 declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
 
 /**
- * Catastrophic-command guardrail for `shell_exec` (M3-2).
- *
- * `catastrophicShellReason` is a pure, segment-aware deny-list: it splits a
- * command on top-level connectors (`;`, `&&`, `||`, pipe), strips `sudo`/`env`
- * prefixes, and matches at COMMAND POSITION (the executable, not an arbitrary
- * substring) so a mention like `echo "rm -rf /"` is not over-blocked. It returns
- * a human reason for the first catastrophic segment, else `null`.
- *
- * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by obfuscation
- * (eval/base64) and is best-effort. POSIX `/bin/sh` only; Windows PowerShell is
- * out of scope. Design: blueprint m3-catastrophic-shell. Zero new deps.
+ * Catastrophic-command guardrail for `shell_exec` (M3-2; hardened V3-1).
+ *
+ * `catastrophicShellReason` is a pure, segment-aware deny-list ported from
+ * theocode's security-reviewed `shell-guard.ts` (the proven spec: 42-blocked +
+ * 24-allowed corpus, 0 misses / 0 false-positives). It splits a command on shell
+ * separators (`;`, `&&`, `||`, `|`, `&`, newline), inspects EVERY segment (so a
+ * chained `rm -rf <safe>; rm -rf /` cannot hide), and matches at COMMAND POSITION
+ * (the executable, not an arbitrary substring) so a mention like `echo "rm -rf /"`
+ * is not over-blocked. Returns a human reason for the first catastrophic segment,
+ * else `null`.
+ *
+ * Categories: recursive-force `rm` of an absolute/home/parent path; destructive git
+ * (force-push, `reset --hard`, `clean -fd`); remote-code-execution (curl/wget piped
+ * OR command-substitution `$( )` / `<( )` / eval / source); disk/raw-device wipe
+ * (mkfs, `dd of=/dev/`, `truncate /dev/`, `> /dev/<blockdev>`); recursive chmod/chown
+ * of a root path (SDK extra); fork bomb; `find -delete` / `-exec rm`; secret-file
+ * exfiltration over the network.
+ *
+ * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by deep obfuscation
+ * (base64/env-indirection) and is best-effort. POSIX `/bin/sh` only; Windows
+ * PowerShell is out of scope. True isolation needs a container.
+ * referencia: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
  */
 
 /** Thrown / reported when a command matches the catastrophic deny-list. */
@@ -288,10 +299,10 @@ declare class CatastrophicCommandError extends ConfigurationError {
     constructor(reason: string);
 }
 /**
- * Returns a human reason if `cmd` contains a catastrophic command (in any
- * segment, across chains/sudo/pipes), else `null`.
+ * Return a human-readable reason when `command` is catastrophic/irreversible, or `null`.
+ * The message is surfaced to the model so it self-corrects.
  */
-declare function catastrophicShellReason(cmd: string): string | null;
+declare function catastrophicShellReason(command: string): string | null;
 
 /**
  * ACI (Agent-Computer Interface) helpers for tools (M3-5).

package/dist/index.js

@@ -94,8 +94,8 @@ function isForbiddenPath(input) {
   if (first === ".git") return true;
   if (first === "node_modules") return true;
   if (first === ".theo") return true;
-  const basename2 = segments[segments.length - 1];
-  if (LOCK_FILES.has(basename2)) return true;
+  const basename = segments[segments.length - 1];
+  if (LOCK_FILES.has(basename)) return true;
   return false;
 }
 
@@ -599,128 +599,96 @@ var CatastrophicCommandError = class extends ConfigurationError {
     });
   }
 };
-var SHELL_NAMES = /* @__PURE__ */ new Set(["sh", "bash", "zsh", "dash", "ksh", "ash"]);
-var PREFIX_TOKENS = /* @__PURE__ */ new Set([
-  "sudo",
-  "doas",
-  "env",
-  "command",
-  "time",
-  "nice",
-  "nohup",
-  "exec",
-  "builtin"
-]);
-var FORK_BOMB = /:\s*\(\s*\)\s*\{[^}]*\|[^}]*&[^}]*\}/;
-var DEVICE_REDIRECT = /[>]\s*\/dev\/(?:sd|nvme|hd|vd|mmcblk|disk|loop|dm-)\w*/;
-var SYSTEM_DIR = /^\/(?:etc|usr|bin|sbin|lib|lib64|var|boot|home|root|opt|sys|proc|dev)(?:\/\*?)?$/;
-function basename(p) {
-  const i = p.lastIndexOf("/");
-  return i >= 0 ? p.slice(i + 1) : p;
-}
-function unquote(t) {
-  if (t.length >= 2) {
-    const a = t[0];
-    const b = t[t.length - 1];
-    if (a === '"' && b === '"' || a === "'" && b === "'") return t.slice(1, -1);
-  }
-  return t;
-}
-function tokenize(s) {
-  return s.trim().split(/\s+/).filter(Boolean);
-}
-function splitSegments(cmd) {
-  return cmd.split(/&&|\|\||;|\|/);
-}
-function stripPrefixTokens(tokens) {
-  let t = tokens;
-  let head = t[0];
-  while (head !== void 0 && PREFIX_TOKENS.has(basename(unquote(head)))) {
-    t = t.slice(1);
-    head = t[0];
-  }
-  return t;
-}
-function operandsOf(tokens) {
-  return tokens.slice(1).filter((t) => !t.startsWith("-")).map(unquote);
-}
-var HOME_VAR = /^\$\{?HOME\}?$/;
-function isRootishPath(op) {
-  if (op === "~" || op === "*" || op === "." || HOME_VAR.test(op)) return true;
-  let collapsed = op.replace(/\/+/g, "/");
-  if (collapsed.length > 1 && collapsed.endsWith("/")) collapsed = collapsed.slice(0, -1);
-  if (collapsed === "/" || collapsed === "/*" || collapsed === "/.") return true;
-  return SYSTEM_DIR.test(collapsed);
-}
-function hasRecursiveForce(tokens) {
-  const flags = tokens.slice(1).filter((t) => t.startsWith("-"));
-  const recursive = flags.some(
-    (f) => f === "--recursive" || !f.startsWith("--") && /[rR]/.test(f)
-  );
-  const force = flags.some((f) => f === "--force" || !f.startsWith("--") && f.includes("f"));
+function unquote(token) {
+  return token.replace(/^(['"])(.*)\1$/, "$2").replace(/^['"]|['"]$/g, "");
+}
+function commandSegments(command) {
+  return command.split(/&&|\|\||[;|&\n]/).map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function commandArgs(segment, name) {
+  const tokens = segment.split(/\s+/);
+  let i = 0;
+  if (tokens[i] === "sudo") i += 1;
+  if (tokens[i] !== name) return null;
+  return tokens.slice(i + 1);
+}
+function commandSegmentsNamed(command, name) {
+  return commandSegments(command).map((s) => commandArgs(s, name)).filter((args) => args !== null);
+}
+function isRecursiveForce(args) {
+  const flags = args.filter((t) => t.startsWith("-")).join(" ");
+  if (flags.length === 0) return false;
+  const recursive = /-[a-z]*r/i.test(flags) || /--recursive/.test(flags);
+  const force = /-[a-z]*f/i.test(flags) || /--force/.test(flags);
   return recursive && force;
 }
-function hasRecursiveFlag(tokens) {
-  return tokens.slice(1).some(
-    (t) => t === "--recursive" || t.startsWith("-") && !t.startsWith("--") && /[rR]/.test(t)
-  );
+function isRecursive(args) {
+  const flags = args.filter((t) => t.startsWith("-")).join(" ");
+  return /-[a-z]*r/i.test(flags) || /--recursive/.test(flags);
+}
+var SAFE_ABSOLUTE_TARGET = /^\/(tmp|var\/tmp)(\/|$)/;
+function targetsDangerousPath(args) {
+  const targets = args.filter((token) => token.length > 0 && !token.startsWith("-")).map(unquote);
+  return targets.some((raw) => {
+    const t = raw.replace(/\/+/g, "/");
+    if (t === "/dev/null" || SAFE_ABSOLUTE_TARGET.test(t)) return false;
+    return /^\/($|\*)/.test(t) || // "/" or "/*"
+    /^\/[^/]/.test(t) || // an absolute path like /etc, /usr/local, /home/user/x
+    t === "~" || t.startsWith("~/") || /\$\{?HOME\b\}?/.test(t) || // $HOME or ${HOME}
+    t === ".." || t.startsWith("../") || t.includes("/..") || t === "*";
+  });
 }
-function isCurlPipedToShell(cmd) {
-  const segs = cmd.replace(/\|\|/g, ";").split(/[;|]/).map((s) => s.trim()).filter(Boolean);
-  let fetcher = false;
-  let shell = false;
-  for (const s of segs) {
-    const tk = stripPrefixTokens(tokenize(s));
-    const head = tk[0];
-    if (head === void 0) continue;
-    const c = basename(unquote(head));
-    if (c === "curl" || c === "wget") fetcher = true;
-    if (SHELL_NAMES.has(c)) shell = true;
-  }
-  return fetcher && shell;
-}
-var rmCheck = (cmd0, tokens) => {
-  if (cmd0 !== "rm" || !hasRecursiveForce(tokens)) return null;
-  const ops = operandsOf(tokens);
-  return ops.length === 0 || ops.some(isRootishPath) ? "rm -rf of a root/home/glob path" : null;
-};
-var mkfsCheck = (cmd0) => cmd0.startsWith("mkfs") ? "mkfs on a device" : null;
-var ddCheck = (cmd0, tokens) => {
-  if (cmd0 !== "dd") return null;
-  return tokens.some((t) => unquote(t).startsWith("of=/dev/")) ? "dd writing to a device" : null;
-};
-var gitForceCheck = (cmd0, tokens) => {
-  if (cmd0 !== "git" || !tokens.includes("push") || tokens.includes("--force-with-lease")) {
-    return null;
+var DEVICE_WIPE = [
+  /\bmkfs(\.\w+)?\b/,
+  /\bdd\b[^\n]*\bof=\/dev\//,
+  /\btruncate\b[^\n]*\s\/dev\//,
+  />\s*\/dev\/(sd|nvme|hd|vd|mmcblk|disk|loop|dm-)/
+];
+var checkRemoteExec = (cmd) => /\b(curl|wget|fetch)\b[^\n]*\|\s*(sudo\s+)?(sh|bash|zsh|dash|python[0-9.]*|node|ruby|perl)\b/i.test(
+  cmd
+) || /(\$\(|<\()\s*(sudo\s+)?(curl|wget|fetch)\b/i.test(cmd) || /\b(eval|source)\b[^\n]*\b(curl|wget|fetch)\b/i.test(cmd) ? "executes a remote download (pipe / command-substitution / eval) \u2014 remote code execution" : null;
+var checkDeviceWipe = (cmd) => DEVICE_WIPE.some((re) => re.test(cmd)) ? "writes to a raw block device / formats a disk" : null;
+var checkForkBomb = (cmd) => /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(cmd) ? "fork bomb" : null;
+var checkDestructiveGit = (cmd) => {
+  if (/\bgit\b[^\n]*\bpush\b[^\n]*(--force(?!-with-lease)\b|\s-f\b|\s\+\S)/.test(cmd)) {
+    return "git force-push (overwrites remote history)";
+  }
+  if (/\bgit\b[^\n]*\breset\b[^\n]*--hard\b/.test(cmd)) {
+    return "git reset --hard (discards committed and working changes)";
+  }
+  if (/\bgit\b[^\n]*\bclean\b[^\n]*(-[a-z]*f[a-z]*d|-[a-z]*d[a-z]*f)/.test(cmd)) {
+    return "git clean -fd (permanently deletes untracked files)";
   }
-  const force = tokens.includes("--force") || tokens.some((t) => /^-[a-z]*f[a-z]*$/.test(t)) || operandsOf(tokens).some((op) => /^\+[^+]/.test(op));
-  return force ? "git push --force" : null;
+  return null;
 };
-var permCheck = (cmd0, tokens) => {
-  if (cmd0 !== "chmod" && cmd0 !== "chown" || !hasRecursiveFlag(tokens)) return null;
-  return operandsOf(tokens).some(isRootishPath) ? `${cmd0} -R on a root path` : null;
+var checkRm = (cmd) => commandSegmentsNamed(cmd, "rm").some((a) => isRecursiveForce(a) && targetsDangerousPath(a)) ? "recursive force-delete of an absolute, home, or parent path" : null;
+var checkPerm = (cmd) => ["chmod", "chown"].some(
+  (name) => commandSegmentsNamed(cmd, name).some((a) => isRecursive(a) && targetsDangerousPath(a))
+) ? "recursive permission change on an absolute, home, or parent path" : null;
+var checkFind = (cmd) => /\bfind\s+(\/\S*|~\S*|\$\{?HOME\}?\S*)\s[^\n]*(-delete\b|-exec\s+rm\b)/.test(cmd) ? "find -delete / -exec rm on an absolute or home path" : null;
+var checkExfiltration = (cmd) => {
+  const touchesSecret = /(^|[\s/'"])(\.env(\.\w+)?|id_rsa|id_ed25519|\.ssh(\/|\b)|credentials|\.aws(\/|\b)|\.npmrc)\b/.test(
+    cmd
+  );
+  const sendsNetwork = /\b(curl|wget|nc|netcat|scp|ftp|telnet)\b/.test(cmd) || /\bpython[0-9.]*\s+-m\s+http/.test(cmd);
+  return touchesSecret && sendsNetwork ? "sends a secret/credential file over the network (exfiltration)" : null;
 };
-var redirectCheck = (_cmd0, _tokens, seg) => DEVICE_REDIRECT.test(seg) ? "redirect to a device" : null;
-var SEGMENT_CHECKS = [
-  rmCheck,
-  mkfsCheck,
-  ddCheck,
-  gitForceCheck,
-  permCheck,
-  redirectCheck
+var CATEGORY_CHECKS = [
+  checkRemoteExec,
+  checkDeviceWipe,
+  checkForkBomb,
+  checkDestructiveGit,
+  checkRm,
+  checkPerm,
+  checkFind,
+  checkExfiltration
 ];
-function catastrophicShellReason(cmd) {
-  if (FORK_BOMB.test(cmd)) return "fork bomb";
-  if (isCurlPipedToShell(cmd)) return "curl/wget piped into a shell";
-  for (const seg of splitSegments(cmd)) {
-    const tokens = stripPrefixTokens(tokenize(seg));
-    const head = tokens[0];
-    if (head === void 0) continue;
-    const cmd0 = basename(unquote(head));
-    for (const check of SEGMENT_CHECKS) {
-      const reason = check(cmd0, tokens, seg);
-      if (reason) return reason;
-    }
+function catastrophicShellReason(command) {
+  const cmd = command.trim();
+  if (cmd.length === 0) return null;
+  for (const check of CATEGORY_CHECKS) {
+    const reason = check(cmd);
+    if (reason) return reason;
   }
   return null;
 }