@vola-trebla/croak 0.1.0 → 0.1.3

package/dist/signals/hidden.js

@@ -1,25 +1,8 @@
-/**
- * Facts about code placed where a human reading the file will not see it:
- *
- * - offscreen — after a long run of spaces or tabs on the same line, far past
- *   the right edge of the editor (e.g. a payload after `module.exports = {};`)
- * - vertical  — after hundreds of blank lines, far below the visible code
- * - bidi      — Unicode bidirectional controls that make the displayed text
- *   differ from what runs (Trojan Source, CVE-2021-42574)
- *
- * No verdicts here; detectors weigh these facts with code signals. Character
- * scanning only, no backtracking regexes.
- */
-/** Whitespace run, in characters, that pushes code offscreen. */
 export const MIN_GAP = 100;
-/** Consecutive blank lines that push code below the fold. */
 export const MIN_BLANK_LINES = 150;
-// Any Unicode whitespace hides code, not only spaces and tabs (NBSP, U+3000, …).
 const isSpace = (ch) => /\s/.test(ch);
 const BLANK = /^\s*$/;
-/** JS and editors break lines at \r\n, \n, a lone \r, U+2028, and U+2029. */
 const LINE_BREAK = /\r\n|[\n\r\u2028\u2029]/;
-/** U+202A–U+202E (embeddings/overrides) and U+2066–U+2069 (isolates). */
 function isBidiControl(code) {
     return ((code >= 0x202a && code <= 0x202e) || (code >= 0x2066 && code <= 0x2069));
 }

package/dist/signals/jsonc.js

@@ -1,9 +1,3 @@
-/**
- * JSON with comments and trailing commas, as VS Code reads `.vscode/*.json`.
- * One linear pass turns JSONC into plain JSON (comments become spaces,
- * trailing commas are dropped), then JSON.parse does the rest. Nesting depth
- * is checked during the pass so hostile input cannot recurse deeply.
- */
 export const MAX_JSONC_DEPTH = 64;
 export class JsoncError extends Error {
     constructor(message) {
@@ -11,7 +5,6 @@ export class JsoncError extends Error {
         this.name = "JsoncError";
     }
 }
-/** Index of the next character that is not whitespace, or text.length. */
 function nextSignificant(text, from) {
     let i = from;
     while (i < text.length && /\s/.test(text[i] ?? ""))
@@ -56,8 +49,6 @@ function toJson(text) {
             out += ch;
         }
         else if (ch === ",") {
-            // Drop a comma whose next significant token (comments already being
-            // skipped) closes the container.
             out += ",";
             const rest = toJsonPeek(text, i + 1);
             if (rest === "}" || rest === "]")
@@ -69,7 +60,6 @@ function toJson(text) {
     }
     return out;
 }
-/** The next significant character after `from`, skipping whitespace and comments. */
 function toJsonPeek(text, from) {
     let i = nextSignificant(text, from);
     while (i < text.length &&

package/dist/signals/obfuscation.js

@@ -1,10 +1,3 @@
-/**
- * Facts that code was deliberately made unreadable — not merely minified.
- * Minifiers shorten names and drop whitespace but keep strings and property
- * names readable; obfuscators encode strings, rename to `_0x…`, rotate string
- * arrays, and reach `eval` through computed names. No verdicts here.
- * Patterns are linear (checked by `pnpm redos`).
- */
 export const OBFUSCATION_PATTERNS = [
     {
         kind: "escapes",
@@ -30,9 +23,6 @@ export const OBFUSCATION_PATTERNS = [
     {
         kind: "dynamic-call",
         label: "computed global call",
-        // globalThis[expr](…) with a non-literal key (one level of nested [] allowed),
-        // but not a well-known symbol: self[Symbol.asyncIterator]() is how
-        // iterators are called (the Anthropic SDK's streaming code)…
         pattern: /\b(?:globalThis|window|global|self)\s*\[\s*(?!Symbol\s*\.)[^\]"'`\s][^\]]{0,100}\]{1,2}\s*\(/,
         threshold: 1,
         scope: "line",
@@ -40,7 +30,6 @@ export const OBFUSCATION_PATTERNS = [
     {
         kind: "dynamic-call",
         label: "string-keyed eval",
-        // …or a literal key that names eval or Function.
         pattern: /\b(?:globalThis|window|global|self)\s*\[\s*["'`](?:eval|Function)["'`]\s*\]/,
         threshold: 1,
         scope: "line",

package/dist/signals/shell.js

@@ -1,12 +1,3 @@
-/**
- * A small, defensive shell parser for package.json scripts. It understands
- * quoting, pipes, command lists, `$(...)`, backticks, `<(...)`, subshells,
- * redirects, and `sh -c '...'` — enough to see what a script really runs,
- * without one fragile regex. It never executes anything.
- *
- * Linear scanning only; input length and nesting depth are capped so hostile
- * scripts cannot make it hang.
- */
 export const MAX_SCRIPT_LENGTH = 10_000;
 const MAX_DEPTH = 8;
 const DOWNLOADERS = new Set([
@@ -24,7 +15,6 @@ const DOWNLOADERS = new Set([
     "certutil",
     "bitsadmin",
 ]);
-/** Commands that execute code they are given via stdin, arguments, or files. */
 const INTERPRETERS = new Set([
     "sh",
     "bash",
@@ -75,7 +65,6 @@ const WRAPPERS = new Set([
     "setsid",
     "ionice",
 ]);
-/** Shell keywords that start or end a compound command, not a command name. */
 const RESERVED = new Set([
     "{",
     "}",
@@ -96,7 +85,6 @@ const RESERVED = new Set([
 ]);
 const PACKAGE_RUNNERS = new Set(["npm", "pnpm", "yarn"]);
 const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
-/** Package-manager subcommands that are not package.json script names. */
 const PM_BUILTINS = new Set([
     "install",
     "i",
@@ -129,9 +117,7 @@ const PM_BUILTINS = new Set([
     "set",
     "help",
 ]);
-/** npm runs these scripts without `run`. */
 const NPM_SCRIPT_ALIASES = new Set(["test", "start", "stop", "restart"]);
-/** The package.json script a package-manager command runs, if any. */
 function scriptName(name, args) {
     if (!PACKAGE_RUNNERS.has(name) && name !== "bun")
         return undefined;
@@ -147,7 +133,6 @@ function scriptName(name, args) {
 }
 class ParseError extends Error {
 }
-/** Index just past the `close` that balances the opener before `start`. */
 function findClose(input, start, open, close) {
     let depth = 1;
     for (let i = start; i < input.length; i++) {
@@ -260,7 +245,6 @@ function parse(input, depth) {
         }
         else if (ch === '"') {
             const end = findDoubleQuoteEnd(input, i + 1);
-            // Inside double quotes, $(...) and backticks still run.
             const body = input.slice(i + 1, end);
             for (let j = 0; j < body.length; j++) {
                 if (body[j] === "\\") {
@@ -300,7 +284,6 @@ function parse(input, depth) {
             i = close;
         }
         else if (ch === "#" && !inWord) {
-            // A comment runs to the end of the line, quotes and all.
             const newline = input.indexOf("\n", i);
             i = (newline === -1 ? input.length : newline) - 1;
         }
@@ -308,7 +291,6 @@ function parse(input, depth) {
             !inWord &&
             words.length === 0 &&
             (next === " " || next === "\t" || next === "\n")) {
-            // { …; } groups commands like a subshell does.
             const close = findClose(input, i + 1, "{", "}");
             subshell = parse(input.slice(i + 1, close - 1), depth + 1);
             i = close - 1;
@@ -335,7 +317,6 @@ function parse(input, depth) {
             endPipeline();
         }
         else if (ch === ">" || ch === "<") {
-            // A leading fd number (2>) belongs to the redirect, not to a word.
             if (inWord && /^\d+$/.test(text) && subs.length === 0) {
                 text = "";
                 inWord = false;
@@ -359,14 +340,12 @@ function parse(input, depth) {
     endPipeline();
     return script;
 }
-// ---------------------------------------------------------------- analysis
 const basename = (path) => path.slice(path.lastIndexOf("/") + 1);
 const normalizeName = (word) => basename(word)
     .toLowerCase()
     .replace(/\.exe$/, "");
 const stripDot = (path) => path.startsWith("./") ? path.slice(2) : path;
 const urlFileName = (url) => basename(url.split(/[?#]/)[0] ?? "");
-/** The real command after env assignments and wrappers, with its arguments. */
 const NPX_LIKE = new Set(["npx", "pnpx", "bunx"]);
 const WORKSPACE_FLAGS = new Set([
     "-r",
@@ -379,7 +358,6 @@ const WORKSPACE_FLAGS = new Set([
     "-ws",
     "--if-present",
 ]);
-/** The real command after env assignments and wrappers, with its arguments. */
 function resolveCommand(command) {
     const words = [...command.words];
     const modifiers = [];
@@ -400,7 +378,6 @@ function resolveCommand(command) {
         if (WRAPPERS.has(name)) {
             words.shift();
             const flags = [];
-            // Skip wrapper flags (sudo -u user, nice -n 5, npx --yes).
             while (words[0]?.text.startsWith("-")) {
                 const flag = words.shift()?.text ?? "";
                 flags.push(flag);
@@ -409,10 +386,8 @@ function resolveCommand(command) {
                     words.shift();
                 }
             }
-            // timeout's first operand is the duration, not the command.
             if (name === "timeout" && /^\d/.test(words[0]?.text ?? ""))
                 words.shift();
-            // A bare npx runs a local bin; npx with flags or any other wrapper changes what runs.
             if (!NPX_LIKE.has(name) || flags.length > 0)
                 modifiers.push(`runs through ${name}${flags.length > 0 ? ` ${flags.join(" ")}` : ""}`);
             continue;
@@ -459,7 +434,6 @@ function addLocal(acc, path) {
     if (!acc.localFiles.includes(clean))
         acc.localFiles.push(clean);
 }
-/** Files a downloader writes, so a later command that runs them is caught. */
 function downloadTargets(name, args, redirects) {
     const targets = [];
     const url = args.find((a) => /^[a-z]+:\/\//i.test(a.text))?.text ?? "";
@@ -468,7 +442,6 @@ function downloadTargets(name, args, redirects) {
         const flag = args[i]?.text ?? "";
         const value = args[i + 1]?.text;
         if (name === "curl") {
-            // -o FILE, also inside a cluster such as -sSLo FILE
             if ((flag === "--output" || /^-[a-zA-Z]*o$/.test(flag)) &&
                 value !== undefined)
                 targets.push(value);
@@ -476,7 +449,6 @@ function downloadTargets(name, args, redirects) {
                 targets.push(urlFileName(url));
         }
         if (name === "wget") {
-            // -O FILE, -qO FILE, -qO- (stdout), --output-document=FILE
             const cluster = /^-[a-zA-Z]*O(.*)$/.exec(flag);
             const long = flag.startsWith("--output-document")
                 ? (flag.split("=")[1] ?? value)
@@ -522,7 +494,6 @@ function walkCommand(command, acc, depth) {
     const script = scriptName(name, args);
     if (script !== undefined)
         acc.runScripts.push(script);
-    // Running a file the script downloaded earlier.
     if (acc.downloaded.has(stripDot(raw)) ||
         args.some((a) => INTERPRETERS.has(name) && acc.downloaded.has(stripDot(a.text)))) {
         acc.downloadExecute = true;
@@ -535,7 +506,6 @@ function walkCommand(command, acc, depth) {
     }
     const interpreter = INTERPRETERS.has(name);
     if (interpreter) {
-        // bash <(curl …), sh -c "$(curl …)", eval "$(curl …)"
         const fed = [...args, ...command.redirects.map((r) => r.target)].some((w) => w.subs.some(hasNetwork));
         if (fed)
             acc.downloadExecute = true;
@@ -543,7 +513,6 @@ function walkCommand(command, acc, depth) {
     if (raw.includes("/") && !interpreter && !downloader)
         addLocal(acc, raw);
     if (SHELLS.has(name)) {
-        // -c, also inside a cluster such as -ec or -xc
         const c = args.findIndex((a) => /^-[a-zA-Z]*c[a-zA-Z]*$/.test(a.text));
         const body = c === -1 ? undefined : args[c + 1];
         if (body !== undefined) {
@@ -595,7 +564,6 @@ function walkCommand(command, acc, depth) {
     }
     return { downloader, interpreter };
 }
-/** A command with a process substitution whose first command is an interpreter, as in `tee >(sh)`. */
 function feedsInterpreter(command) {
     return command.words.some((word) => word.subs.some((sub) => {
         const first = sub[0]?.[0];
@@ -608,7 +576,6 @@ function walkScript(script, acc, depth) {
         let downloaded = false;
         for (const command of pipeline) {
             const { downloader, interpreter } = walkCommand(command, acc, depth);
-            // curl … | sh, curl … | tee f | sh, curl … | tee >(sh)
             if ((interpreter || feedsInterpreter(command)) && downloaded)
                 acc.downloadExecute = true;
             if (downloader)
@@ -678,11 +645,6 @@ export function analyzeShell(command) {
         unparsable: false,
     };
 }
-/**
- * Commands in the order the shell would run them (pipelines and lists
- * flattened), for callers that need argument-level detail, such as the agent
- * hook. Undefined when the text cannot be parsed or is longer than maxLength.
- */
 export function shellCommands(input, maxLength = MAX_SCRIPT_LENGTH) {
     if (input.length > maxLength)
         return undefined;
@@ -695,8 +657,6 @@ export function shellCommands(input, maxLength = MAX_SCRIPT_LENGTH) {
             return undefined;
         throw error;
     }
-    // $(…) and backticks run before their command, in a subshell: each comes
-    // first as a group of its own, so an install inside one is seen.
     const flatten = (s) => s.flatMap((pipeline) => pipeline.flatMap((command) => {
         const subs = [
             ...command.words.flatMap((w) => w.subs),

package/dist/signals/text.js

@@ -1,2 +1 @@
-/** npm, VS Code, and most JSON readers ignore a leading UTF-8 byte-order mark. */
 export const stripBom = (text) => text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;

package/dist/ui.js

@@ -1,4 +1,3 @@
-// Every icon is a single wide (2-column) emoji, so text after it stays aligned.
 export const VERDICT_ICON = {
     allow: "🟢",
     warn: "🟡",

package/dist/verdict.js

@@ -11,7 +11,6 @@ const SEVERITY_VERDICT = {
     warn: "warn",
     block: "block",
 };
-/** The verdict is the most severe finding; info findings and no findings mean allow. */
 export function aggregate(findings) {
     return findings.reduce((worst, finding) => {
         const verdict = SEVERITY_VERDICT[finding.severity];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vola-trebla/croak",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Croak before you install: a pre-execution gate for package installs, built for AI agents",
   "keywords": [
     "security",

package/scripts/croak-hook.sh

@@ -15,8 +15,10 @@ here=$(dirname "$self")
 cli="$here/../dist/cli.js"
 install="$here/croak-install.sh"
 [ -f "$cli" ] || deny "$cli not found (run pnpm build in the croak repo)"
-# Below Node 24.2 the CLI's entry point does not run and exits 0 with no
-# output: every step would "succeed" silently, and every install would pass.
+# croak needs Node 24.2 or later (package.json engines). On a Node whose
+# entry point check does not run, the CLI exits 0 with no output, and every
+# step would "succeed" silently; on others, behaviour croak was never tested
+# with would decide. Either way: deny instead.
 node -e 'const [a, b] = process.versions.node.split(".").map(Number); process.exit(a > 24 || (a === 24 && b >= 2) ? 0 : 1)' ||
   deny "croak needs Node 24.2 or later (found $(node --version 2>/dev/null || echo none))"
 

package/scripts/croak-install.sh

@@ -229,12 +229,20 @@ if ! isolated "$@" >"$work/plan.log" 2>&1; then
   tail -n 15 "$work/plan.log" >&2
   exit 3
 fi
-if [ ! -f "$work/plan/$lockname" ] && [ -n "$member" ] && [ -f "$work/plan/$member/$lockname" ]; then
-  # The package manager planned the folder as its own project: the workspace
-  # does not list it, and the real install runs there too. That plan lacked
-  # the folder's own lockfile and sanitized manifest, so plan the folder again
-  # as a project of its own, exactly as outside any workspace (D48). croak
-  # plan still refuses a --member the lockfile does not list (M6 review).
+# The copy holds package.json files only, so a lockfile in the member's folder
+# means the package manager planned that folder apart from the workspace, as
+# the real install will. Decide by that, never by the root lockfile, which the
+# package manager then left as it was and the repository may have forged (D52).
+if [ -n "$member" ] && [ -f "$work/plan/$member/$lockname" ]; then
+  if [ "$manager" != npm ]; then
+    # pnpm writes one for a real member too (sharedWorkspaceLockfile: false);
+    # planning it alone would leave the rest of the workspace out.
+    echo "croak-install: $manager planned $member apart from its workspace, so this install was not checked" >&2
+    exit 3
+  fi
+  # npm installs a folder the workspace does not list as a project of its own.
+  # That plan lacked the folder's own lockfile and sanitized manifest, so plan
+  # the folder again, exactly as outside any workspace (D48).
   cd "$start"
   if [ "$manager" = npm ] && [ -f npm-shrinkwrap.json ]; then
     echo "croak-install: npm-shrinkwrap.json is not supported yet, so this install was not checked" >&2