open-multi-agent-kit 0.80.7 → 0.80.8

package/dist/core/command-safety-parser.d.ts

@@ -0,0 +1,77 @@
+export interface ShellSegment {
+    /** Raw top-level command text (split on `;`, `&&`, `||`, `&`, newline). */
+    readonly text: string;
+    /** Coarse quote-aware tokens for this segment. */
+    readonly tokens: readonly string[];
+}
+export interface SubcommandNode {
+    readonly kind: "dollar_paren" | "backtick";
+    readonly inner: string;
+    readonly depth: number;
+}
+export interface SubshellNode {
+    readonly inner: string;
+    readonly depth: number;
+}
+export interface ProcessSubNode {
+    readonly direction: "in" | "out";
+    readonly inner: string;
+    readonly depth: number;
+}
+export interface EnvAssignment {
+    readonly name: string;
+    /** Raw value text exactly as written (may itself contain expansions). */
+    readonly value: string;
+    readonly position: "prefix" | "export" | "env" | "inline";
+    readonly loaderInjection: boolean;
+    readonly sensitiveName: boolean;
+}
+export interface ExpansionNode {
+    readonly kind: "var" | "brace";
+    readonly name: string;
+    readonly depth: number;
+}
+export interface DecoderPipeline {
+    readonly stages: readonly string[];
+    readonly decoderIndex: number;
+    readonly executorIndex: number;
+    readonly executor: string;
+}
+export interface ParseDiagnostic {
+    readonly code: string;
+    readonly message: string;
+    readonly fatal: boolean;
+}
+export interface ShellAnalysis {
+    readonly raw: string;
+    readonly segments: readonly ShellSegment[];
+    readonly subcommands: readonly SubcommandNode[];
+    readonly subshells: readonly SubshellNode[];
+    readonly processSubstitutions: readonly ProcessSubNode[];
+    readonly assignments: readonly EnvAssignment[];
+    readonly dynamicExpansions: readonly ExpansionNode[];
+    readonly decoderPipelines: readonly DecoderPipeline[];
+    readonly wrapperDepth: number;
+    readonly diagnostics: readonly ParseDiagnostic[];
+}
+export type CommandAction = "allow" | "confirm" | "block" | "escalate";
+export interface RiskReason {
+    readonly code: string;
+    readonly message: string;
+}
+export interface CommandRiskV2Verdict {
+    readonly action: CommandAction;
+    readonly reasons: readonly RiskReason[];
+    /** Effective command strings after unwrapping dynamic structures. */
+    readonly normalizedCommands: readonly string[];
+    readonly analysis: ShellAnalysis;
+}
+/** Public: analyze a shell command into structural metadata. */
+export declare function analyzeShellCommandV2(command: string): ShellAnalysis;
+/**
+ * Public: classify a shell command into allow / confirm / block / escalate,
+ * composing the existing `classifyShellCommand` verdict with V2 structural
+ * detections. The result never lowers the existing risk tier.
+ */
+export declare function classifyCommandRiskV2(command: string): CommandRiskV2Verdict;
+//# sourceMappingURL=command-safety-parser.d.ts.map

package/dist/core/command-safety-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-safety-parser.d.ts","sourceRoot":"","sources":["../../src/core/command-safety-parser.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Lane SA3 - Command Safety Parser V2.\n *\n * Pure, side-effect-free shell command analysis layered on top of the existing\n * `classifyShellCommand` engine. It adds quoting-aware detection of:\n *   - command substitution: `$(...)` and backticks\n *   - subshell grouping: `(...)`\n *   - process substitution: `<(...)` and `>(...)`\n *   - environment assignment injection: `VAR=... cmd`, `export VAR=...`, `env VAR=...`\n *   - dynamic expansions: `$VAR`, `${VAR}`\n *   - decoder pipelines: `base64 -d` / `xxd -r` / `openssl enc -d` feeding a shell\n *   - wrapper nesting depth and parser diagnostics (fail-closed)\n *\n * It does NOT execute, decode, or normalize away the original command. The\n * classifier composes the existing verdict with V2 detections and never lowers\n * the existing risk tier.\n */\nimport { classifyShellCommand } from \"./command-safety.ts\";\n\n/** Maximum structural recursion depth ($() inside $(...) inside ...). */\nconst MAX_SCAN_DEPTH = 6;\n\n/** Executables that decode and/or execute an encoded payload. */\nconst DECODER_EXECUTABLES = new Set<string>([\n\t\"sh\",\n\t\"bash\",\n\t\"zsh\",\n\t\"dash\",\n\t\"ksh\",\n\t\"ash\",\n\t\"eval\",\n\t\"source\",\n\t\".\",\n\t\"python\",\n\t\"python2\",\n\t\"python3\",\n\t\"node\",\n\t\"perl\",\n\t\"ruby\",\n\t\"php\",\n\t\"lua\",\n\t\"expect\",\n\t\"env\",\n\t\"xargs\",\n]);\n\n/**\n * Environment variable names that inject code or redirect runtime loader\n * behavior. Assigning any of these on a command line is treated as a loader /\n * runtime injection attempt.\n */\nconst LOADER_INJECTION_ENV = new Set<string>([\n\t\"LD_PRELOAD\",\n\t\"LD_LIBRARY_PATH\",\n\t\"LD_AUDIT\",\n\t\"LD_BIND_NOW\",\n\t\"LD_PROFILE\",\n\t\"DYLD_INSERT_LIBRARIES\",\n\t\"DYLD_LIBRARY_PATH\",\n\t\"DYLD_FALLBACK_LIBRARY_PATH\",\n\t\"NODE_OPTIONS\",\n\t\"NODE_PATH\",\n\t\"NODE_REPL_EXTERNAL_MODULE\",\n\t\"NODE_EXTRA_CA_CERTS\",\n\t\"NODE_TLS_REJECT_UNAUTHORIZED\",\n\t\"PYTHONPATH\",\n\t\"PYTHONHOME\",\n\t\"PYTHONSTARTUP\",\n\t\"PYTHONINSPECT\",\n\t\"PERL5LIB\",\n\t\"PERLLIB\",\n\t\"PERL5OPT\",\n\t\"RUBYLIB\",\n\t\"RUBYOPT\",\n\t\"RUBYPATH\",\n\t\"JAVA_TOOL_OPTIONS\",\n\t\"_JAVA_OPTIONS\",\n\t\"JDK_JAVA_OPTIONS\",\n\t\"MAVEN_OPTS\",\n]);\n\n/** Exact sensitive variable names (do not end in a standard suffix). */\nconst SENSITIVE_NAME_EXACT = new Set<string>([\n\t\"AWS_ACCESS_KEY_ID\",\n\t\"AWS_SECRET_ACCESS_KEY\",\n\t\"AWS_SESSION_TOKEN\",\n\t\"GITHUB_TOKEN\",\n\t\"GH_TOKEN\",\n\t\"GITLAB_TOKEN\",\n\t\"NPM_TOKEN\",\n\t\"NODE_AUTH_TOKEN\",\n]);\n\n/** Sensitive variable name suffixes. */\nconst SENSITIVE_NAME_REGEX =\n\t/(^|_)(API_KEY|API_TOKEN|ACCESS_TOKEN|SECRET|SECRET_KEY|PRIVATE_KEY|PASSWORD|PASSWD|TOKEN)$/i;\n\n/**\n * Commands whose arguments become filesystem or history targets. An\n * unresolved `$VAR` expansion in their argument position is treated as a\n * dynamic target (could expand to /, ~, or a sensitive path).\n */\nconst RISKY_EXPANSION_EXEC = new Set<string>([\n\t\"rm\",\n\t\"dd\",\n\t\"mkfs\",\n\t\"find\",\n\t\"git\",\n\t\"chmod\",\n\t\"chown\",\n\t\"cp\",\n\t\"mv\",\n\t\"install\",\n\t\"rsync\",\n\t\"scp\",\n]);\n\nexport interface ShellSegment {\n\t/** Raw top-level command text (split on `;`, `&&`, `||`, `&`, newline). */\n\treadonly text: string;\n\t/** Coarse quote-aware tokens for this segment. */\n\treadonly tokens: readonly string[];\n}\n\nexport interface SubcommandNode {\n\treadonly kind: \"dollar_paren\" | \"backtick\";\n\treadonly inner: string;\n\treadonly depth: number;\n}\n\nexport interface SubshellNode {\n\treadonly inner: string;\n\treadonly depth: number;\n}\n\nexport interface ProcessSubNode {\n\treadonly direction: \"in\" | \"out\";\n\treadonly inner: string;\n\treadonly depth: number;\n}\n\nexport interface EnvAssignment {\n\treadonly name: string;\n\t/** Raw value text exactly as written (may itself contain expansions). */\n\treadonly value: string;\n\treadonly position: \"prefix\" | \"export\" | \"env\" | \"inline\";\n\treadonly loaderInjection: boolean;\n\treadonly sensitiveName: boolean;\n}\n\nexport interface ExpansionNode {\n\treadonly kind: \"var\" | \"brace\";\n\treadonly name: string;\n\treadonly depth: number;\n}\n\nexport interface DecoderPipeline {\n\treadonly stages: readonly string[];\n\treadonly decoderIndex: number;\n\treadonly executorIndex: number;\n\treadonly executor: string;\n}\n\nexport interface ParseDiagnostic {\n\treadonly code: string;\n\treadonly message: string;\n\treadonly fatal: boolean;\n}\n\nexport interface ShellAnalysis {\n\treadonly raw: string;\n\treadonly segments: readonly ShellSegment[];\n\treadonly subcommands: readonly SubcommandNode[];\n\treadonly subshells: readonly SubshellNode[];\n\treadonly processSubstitutions: readonly ProcessSubNode[];\n\treadonly assignments: readonly EnvAssignment[];\n\treadonly dynamicExpansions: readonly ExpansionNode[];\n\treadonly decoderPipelines: readonly DecoderPipeline[];\n\treadonly wrapperDepth: number;\n\treadonly diagnostics: readonly ParseDiagnostic[];\n}\n\nexport type CommandAction = \"allow\" | \"confirm\" | \"block\" | \"escalate\";\n\nexport interface RiskReason {\n\treadonly code: string;\n\treadonly message: string;\n}\n\nexport interface CommandRiskV2Verdict {\n\treadonly action: CommandAction;\n\treadonly reasons: readonly RiskReason[];\n\t/** Effective command strings after unwrapping dynamic structures. */\n\treadonly normalizedCommands: readonly string[];\n\treadonly analysis: ShellAnalysis;\n}\n\nconst ACTION_RANK: Readonly<Record<CommandAction, number>> = {\n\tallow: 0,\n\tconfirm: 1,\n\tescalate: 2,\n\tblock: 3,\n};\n\nfunction isWhitespace(ch: string): boolean {\n\treturn ch === \" \" || ch === \"\\t\" || ch === \"\\n\" || ch === \"\\r\" || ch === \"\\f\" || ch === \"\\v\";\n}\n\nfunction isSensitiveEnvName(name: string): boolean {\n\tif (SENSITIVE_NAME_EXACT.has(name)) return true;\n\treturn SENSITIVE_NAME_REGEX.test(name);\n}\n\n/** Split a command into top-level command segments on `;`, `&&`, `||`, `&`, newline. */\nfunction splitTopLevelCommands(command: string): string[] {\n\tconst segments: string[] = [];\n\tlet buf = \"\";\n\tlet quote: string | undefined;\n\tlet escaped = false;\n\tconst flush = (): void => {\n\t\tconst trimmed = buf.trim();\n\t\tif (trimmed) segments.push(trimmed);\n\t\tbuf = \"\";\n\t};\n\tfor (let i = 0; i < command.length; i += 1) {\n\t\tconst ch = command[i];\n\t\tconst next = command[i + 1];\n\t\tif (escaped) {\n\t\t\tbuf += ch;\n\t\t\tescaped = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"\\\\\" && quote !== \"'\") {\n\t\t\tescaped = true;\n\t\t\tbuf += ch;\n\t\t\tcontinue;\n\t\t}\n\t\tif (quote) {\n\t\t\tbuf += ch;\n\t\t\tif (ch === quote) quote = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"'\" || ch === '\"') {\n\t\t\tquote = ch;\n\t\t\tbuf += ch;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \";\") {\n\t\t\tflush();\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"&\") {\n\t\t\tflush();\n\t\t\tif (next === \"&\") i += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"|\") {\n\t\t\tif (next === \"|\") {\n\t\t\t\tflush();\n\t\t\t\ti += 1;\n\t\t\t} else {\n\t\t\t\t// single pipe stays within the segment (decoder pipeline detection)\n\t\t\t\tbuf += ch;\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"\\n\" || ch === \"\\r\") {\n\t\t\tflush();\n\t\t\tcontinue;\n\t\t}\n\t\tbuf += ch;\n\t}\n\tflush();\n\treturn segments;\n}\n\n/** Coarse quote-aware tokenizer for one segment. */\nfunction tokenize(segment: string): string[] {\n\tconst tokens: string[] = [];\n\tlet cur = \"\";\n\tlet quote: string | undefined;\n\tlet escaped = false;\n\tfor (const ch of segment) {\n\t\tif (escaped) {\n\t\t\tcur += ch;\n\t\t\tescaped = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"\\\\\" && quote !== \"'\") {\n\t\t\tescaped = true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (quote) {\n\t\t\tif (ch === quote) {\n\t\t\t\tquote = undefined;\n\t\t\t} else {\n\t\t\t\tcur += ch;\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"'\" || ch === '\"') {\n\t\t\tquote = ch;\n\t\t\tcontinue;\n\t\t}\n\t\tif (isWhitespace(ch)) {\n\t\t\tif (cur) {\n\t\t\t\ttokens.push(cur);\n\t\t\t\tcur = \"\";\n\t\t\t}\n\t\t\tcontinue;\n\t\t}\n\t\tcur += ch;\n\t}\n\tif (cur) tokens.push(cur);\n\treturn tokens;\n}\n\n/** Split a segment on single `|` (pipe stages), quote-aware. `||` is gone already. */\nfunction splitPipeStages(segment: string): string[] {\n\tconst stages: string[] = [];\n\tlet buf = \"\";\n\tlet quote: string | undefined;\n\tlet escaped = false;\n\tconst flush = (): void => {\n\t\tconst trimmed = buf.trim();\n\t\tif (trimmed) stages.push(trimmed);\n\t\tbuf = \"\";\n\t};\n\tfor (let i = 0; i < segment.length; i += 1) {\n\t\tconst ch = segment[i];\n\t\tif (escaped) {\n\t\t\tbuf += ch;\n\t\t\tescaped = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"\\\\\" && quote !== \"'\") {\n\t\t\tescaped = true;\n\t\t\tbuf += ch;\n\t\t\tcontinue;\n\t\t}\n\t\tif (quote) {\n\t\t\tbuf += ch;\n\t\t\tif (ch === quote) quote = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"'\" || ch === '\"') {\n\t\t\tquote = ch;\n\t\t\tbuf += ch;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"|\") {\n\t\t\tflush();\n\t\t\tcontinue;\n\t\t}\n\t\tbuf += ch;\n\t}\n\tflush();\n\treturn stages;\n}\n\n/** Return the index of the `)` matching the `(` at `openIndex`, or -1. */\nfunction findMatchingParen(text: string, openIndex: number): number {\n\tif (text[openIndex] !== \"(\") return -1;\n\tlet depth = 0;\n\tlet quote: string | undefined;\n\tlet escaped = false;\n\tfor (let i = openIndex; i < text.length; i += 1) {\n\t\tconst ch = text[i];\n\t\tif (escaped) {\n\t\t\tescaped = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"\\\\\" && quote !== \"'\") {\n\t\t\tescaped = true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (quote) {\n\t\t\tif (ch === quote) quote = undefined;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"'\" || ch === '\"') {\n\t\t\tquote = ch;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"(\") depth += 1;\n\t\telse if (ch === \")\") {\n\t\t\tdepth -= 1;\n\t\t\tif (depth === 0) return i;\n\t\t}\n\t}\n\treturn -1;\n}\n\ninterface RawExpansion {\n\treadonly kind: \"var\" | \"brace\";\n\treadonly name: string;\n\treadonly end: number;\n}\n\n/** Read a `$VAR` or `${VAR}` expansion starting at `dollarIndex`. Returns null for `${...}` ops we do not model. */\nfunction readExpansion(text: string, dollarIndex: number): RawExpansion | null {\n\tconst next = text[dollarIndex + 1];\n\tif (next === \"{\") {\n\t\tconst close = text.indexOf(\"}\", dollarIndex + 2);\n\t\tif (close === -1) return null;\n\t\tconst name = text.slice(dollarIndex + 2, close);\n\t\tif (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) return null;\n\t\treturn { kind: \"brace\", name, end: close + 1 };\n\t}\n\tif (next && /[A-Za-z_]/.test(next)) {\n\t\tconst match = /^[A-Za-z_][A-Za-z0-9_]*/.exec(text.slice(dollarIndex + 1));\n\t\tif (match) return { kind: \"var\", name: match[0], end: dollarIndex + 1 + match[0].length };\n\t}\n\treturn null;\n}\n\ninterface ScanState {\n\treadonly subcommands: SubcommandNode[];\n\treadonly subshells: SubshellNode[];\n\treadonly processSubs: ProcessSubNode[];\n\treadonly expansions: ExpansionNode[];\n\treadonly diagnostics: ParseDiagnostic[];\n\tmaxDepth: number;\n}\n\n/** Recursively scan `text` for structural shell nodes, quote-aware. */\nfunction scanStructural(text: string, state: ScanState, depth: number): void {\n\tif (depth > MAX_SCAN_DEPTH) {\n\t\tstate.diagnostics.push({\n\t\t\tcode: \"parser.depth_exceeded\",\n\t\t\tmessage: `Wrapper nesting exceeded depth ${MAX_SCAN_DEPTH}.`,\n\t\t\tfatal: false,\n\t\t});\n\t\treturn;\n\t}\n\tlet i = 0;\n\tlet quote: string | undefined;\n\tlet escaped = false;\n\tconst n = text.length;\n\twhile (i < n) {\n\t\tconst ch = text[i];\n\t\tconst next = text[i + 1];\n\t\tif (escaped) {\n\t\t\tescaped = false;\n\t\t\ti += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"\\\\\" && quote !== \"'\") {\n\t\t\tescaped = true;\n\t\t\ti += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (quote) {\n\t\t\t// Inside double quotes, $() and backticks still expand; `(` alone is literal.\n\t\t\tif (quote === '\"' && ch === \"$\" && next === \"(\") {\n\t\t\t\tconst end = findMatchingParen(text, i + 1);\n\t\t\t\tif (end === -1) {\n\t\t\t\t\tstate.diagnostics.push({\n\t\t\t\t\t\tcode: \"parser.unterminated_dollar_paren\",\n\t\t\t\t\t\tmessage: \"Unterminated $( ... ).\",\n\t\t\t\t\t\tfatal: true,\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tconst inner = text.slice(i + 2, end);\n\t\t\t\tstate.subcommands.push({ kind: \"dollar_paren\", inner, depth });\n\t\t\t\tstate.maxDepth = Math.max(state.maxDepth, depth);\n\t\t\t\tscanStructural(inner, state, depth + 1);\n\t\t\t\ti = end + 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (quote === '\"' && ch === \"`\") {\n\t\t\t\tconst end = text.indexOf(\"`\", i + 1);\n\t\t\t\tif (end === -1) {\n\t\t\t\t\tstate.diagnostics.push({\n\t\t\t\t\t\tcode: \"parser.unterminated_backtick\",\n\t\t\t\t\t\tmessage: \"Unterminated backtick.\",\n\t\t\t\t\t\tfatal: true,\n\t\t\t\t\t});\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tconst inner = text.slice(i + 1, end);\n\t\t\t\tstate.subcommands.push({ kind: \"backtick\", inner, depth });\n\t\t\t\tstate.maxDepth = Math.max(state.maxDepth, depth);\n\t\t\t\tscanStructural(inner, state, depth + 1);\n\t\t\t\ti = end + 1;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (quote === '\"' && ch === \"$\") {\n\t\t\t\tconst exp = readExpansion(text, i);\n\t\t\t\tif (exp) {\n\t\t\t\t\tstate.expansions.push({ kind: exp.kind, name: exp.name, depth });\n\t\t\t\t\ti = exp.end;\n\t\t\t\t\tcontinue;\n\t\t\t\t}\n\t\t\t}\n\t\t\tif (ch === quote) quote = undefined;\n\t\t\ti += 1;\n\t\t\tcontinue;\n\t\t}\n\t\t// unquoted\n\t\tif (ch === \"'\" || ch === '\"') {\n\t\t\tquote = ch;\n\t\t\ti += 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"$\" && next === \"(\") {\n\t\t\tconst end = findMatchingParen(text, i + 1);\n\t\t\tif (end === -1) {\n\t\t\t\tstate.diagnostics.push({\n\t\t\t\t\tcode: \"parser.unterminated_dollar_paren\",\n\t\t\t\t\tmessage: \"Unterminated $( ... ).\",\n\t\t\t\t\tfatal: true,\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst inner = text.slice(i + 2, end);\n\t\t\tstate.subcommands.push({ kind: \"dollar_paren\", inner, depth });\n\t\t\tstate.maxDepth = Math.max(state.maxDepth, depth);\n\t\t\tscanStructural(inner, state, depth + 1);\n\t\t\ti = end + 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"`\") {\n\t\t\tconst end = text.indexOf(\"`\", i + 1);\n\t\t\tif (end === -1) {\n\t\t\t\tstate.diagnostics.push({\n\t\t\t\t\tcode: \"parser.unterminated_backtick\",\n\t\t\t\t\tmessage: \"Unterminated backtick.\",\n\t\t\t\t\tfatal: true,\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst inner = text.slice(i + 1, end);\n\t\t\tstate.subcommands.push({ kind: \"backtick\", inner, depth });\n\t\t\tstate.maxDepth = Math.max(state.maxDepth, depth);\n\t\t\tscanStructural(inner, state, depth + 1);\n\t\t\ti = end + 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif ((ch === \"<\" || ch === \">\") && next === \"(\") {\n\t\t\tconst end = findMatchingParen(text, i + 1);\n\t\t\tif (end === -1) {\n\t\t\t\tstate.diagnostics.push({\n\t\t\t\t\tcode: \"parser.unterminated_process_sub\",\n\t\t\t\t\tmessage: \"Unterminated process substitution.\",\n\t\t\t\t\tfatal: true,\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst inner = text.slice(i + 2, end);\n\t\t\tstate.processSubs.push({ direction: ch === \"<\" ? \"in\" : \"out\", inner, depth });\n\t\t\tstate.maxDepth = Math.max(state.maxDepth, depth);\n\t\t\tscanStructural(inner, state, depth + 1);\n\t\t\ti = end + 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"(\") {\n\t\t\tconst end = findMatchingParen(text, i);\n\t\t\tif (end === -1) {\n\t\t\t\tstate.diagnostics.push({\n\t\t\t\t\tcode: \"parser.unterminated_subshell\",\n\t\t\t\t\tmessage: \"Unterminated subshell.\",\n\t\t\t\t\tfatal: true,\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst inner = text.slice(i + 1, end);\n\t\t\tstate.subshells.push({ inner, depth });\n\t\t\tstate.maxDepth = Math.max(state.maxDepth, depth);\n\t\t\tscanStructural(inner, state, depth + 1);\n\t\t\ti = end + 1;\n\t\t\tcontinue;\n\t\t}\n\t\tif (ch === \"$\") {\n\t\t\tconst exp = readExpansion(text, i);\n\t\t\tif (exp) {\n\t\t\t\tstate.expansions.push({ kind: exp.kind, name: exp.name, depth });\n\t\t\t\ti = exp.end;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\t\ti += 1;\n\t}\n\tif (quote !== undefined) {\n\t\tstate.diagnostics.push({\n\t\t\tcode: \"parser.unterminated_quote\",\n\t\t\tmessage: `Unterminated ${quote} quote.`,\n\t\t\tfatal: true,\n\t\t});\n\t}\n}\n\n/** Detect leading `VAR=value` assignments, including `export` / `env` prefixes. */\nfunction detectAssignments(segment: string): EnvAssignment[] {\n\tconst tokens = tokenize(segment);\n\tif (tokens.length === 0) return [];\n\tconst assignments: EnvAssignment[] = [];\n\tlet idx = 0;\n\tlet position: EnvAssignment[\"position\"] = \"prefix\";\n\tconst head = tokens[0]?.toLowerCase();\n\tif (head === \"export\" || head === \"set\") {\n\t\tposition = \"export\";\n\t\tidx = 1;\n\t} else if (head === \"env\") {\n\t\tposition = \"env\";\n\t\tidx = 1;\n\t\t// skip leading env options (-i, -u NAME, -C, ...). -u / --unset consume a name token.\n\t\twhile (idx < tokens.length) {\n\t\t\tconst tok = tokens[idx];\n\t\t\tif (!tok || !tok.startsWith(\"-\") || tok === \"--\") {\n\t\t\t\tif (tok === \"--\") idx += 1;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t\tidx += 1;\n\t\t\tconst lower = tok.toLowerCase();\n\t\t\tif (lower === \"-u\" || lower === \"--unset\" || lower === \"-s\" || lower === \"--ignore-environment\") {\n\t\t\t\tif (idx < tokens.length && !tokens[idx].includes(\"=\")) idx += 1;\n\t\t\t}\n\t\t}\n\t}\n\tconst assignRegex = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/;\n\twhile (idx < tokens.length) {\n\t\tconst tok = tokens[idx];\n\t\tconst match = assignRegex.exec(tok);\n\t\tif (!match) break;\n\t\tconst name = match[1];\n\t\tassignments.push({\n\t\t\tname,\n\t\t\tvalue: match[2],\n\t\t\tposition,\n\t\t\tloaderInjection: LOADER_INJECTION_ENV.has(name),\n\t\t\tsensitiveName: isSensitiveEnvName(name),\n\t\t});\n\t\tidx += 1;\n\t}\n\treturn assignments;\n}\n\nfunction isDecoderStage(exec: string, tokens: readonly string[]): boolean {\n\tif (exec === \"base64\") {\n\t\treturn tokens.slice(1).some((t) => t === \"-d\" || t === \"--decode\" || t === \"-D\");\n\t}\n\tif (exec === \"xxd\") {\n\t\treturn tokens.slice(1).some((t) => t === \"-r\" || t === \"-rp\" || t === \"-r -p\");\n\t}\n\tif (exec === \"openssl\") {\n\t\tconst lower = tokens.map((t) => t.toLowerCase());\n\t\treturn lower.includes(\"enc\") && lower.some((t) => t === \"-d\" || t === \"-decrypt\" || t === \"-aes-256-cbc\");\n\t}\n\treturn exec === \"printf\" || exec === \"uudecode\" || exec === \"mmencode\" || exec === \"recode\";\n}\n\nfunction detectDecoderPipeline(segment: string): DecoderPipeline | null {\n\tconst stages = splitPipeStages(segment);\n\tif (stages.length < 2) return null;\n\tlet decoderIndex = -1;\n\tlet executorIndex = -1;\n\tlet executor = \"\";\n\tfor (let i = 0; i < stages.length; i += 1) {\n\t\tconst toks = tokenize(stages[i]);\n\t\tconst exec = toks[0]?.toLowerCase();\n\t\tif (!exec) continue;\n\t\tif (decoderIndex === -1 && isDecoderStage(exec, toks)) decoderIndex = i;\n\t\tif (executorIndex === -1 && DECODER_EXECUTABLES.has(exec)) {\n\t\t\texecutorIndex = i;\n\t\t\texecutor = exec;\n\t\t}\n\t}\n\tif (decoderIndex !== -1 && executorIndex !== -1 && executorIndex >= decoderIndex) {\n\t\treturn { stages, decoderIndex, executorIndex, executor };\n\t}\n\treturn null;\n}\n\n/** Public: analyze a shell command into structural metadata. */\nexport function analyzeShellCommandV2(command: string): ShellAnalysis {\n\tconst raw = command;\n\tconst topSegments = splitTopLevelCommands(command);\n\tconst segments: ShellSegment[] = topSegments.map((text) => ({ text, tokens: tokenize(text) }));\n\n\tconst state: ScanState = {\n\t\tsubcommands: [],\n\t\tsubshells: [],\n\t\tprocessSubs: [],\n\t\texpansions: [],\n\t\tdiagnostics: [],\n\t\tmaxDepth: 0,\n\t};\n\tscanStructural(command, state, 0);\n\n\tconst assignments: EnvAssignment[] = [];\n\tfor (const seg of topSegments) assignments.push(...detectAssignments(seg));\n\n\tconst decoderPipelines: DecoderPipeline[] = [];\n\tfor (const seg of topSegments) {\n\t\tconst dp = detectDecoderPipeline(seg);\n\t\tif (dp) decoderPipelines.push(dp);\n\t}\n\n\treturn {\n\t\traw,\n\t\tsegments,\n\t\tsubcommands: state.subcommands,\n\t\tsubshells: state.subshells,\n\t\tprocessSubstitutions: state.processSubs,\n\t\tassignments,\n\t\tdynamicExpansions: state.expansions,\n\t\tdecoderPipelines,\n\t\twrapperDepth: state.maxDepth,\n\t\tdiagnostics: state.diagnostics,\n\t};\n}\n\nfunction bump(current: CommandAction, candidate: CommandAction): CommandAction {\n\treturn ACTION_RANK[candidate] > ACTION_RANK[current] ? candidate : current;\n}\n\n/**\n * Public: classify a shell command into allow / confirm / block / escalate,\n * composing the existing `classifyShellCommand` verdict with V2 structural\n * detections. The result never lowers the existing risk tier.\n */\nexport function classifyCommandRiskV2(command: string): CommandRiskV2Verdict {\n\tconst analysis = analyzeShellCommandV2(command);\n\tconst base = classifyShellCommand(command);\n\tlet action: CommandAction = base.risk === \"block\" ? \"block\" : base.risk === \"confirm\" ? \"confirm\" : \"allow\";\n\tconst reasons: RiskReason[] = [{ code: base.rule, message: base.reason }];\n\tconst normalizedCommands: string[] = [command];\n\tfor (const node of analysis.subcommands) normalizedCommands.push(node.inner);\n\tfor (const node of analysis.subshells) normalizedCommands.push(node.inner);\n\tfor (const node of analysis.processSubstitutions) normalizedCommands.push(node.inner);\n\n\t// Privilege commands escalate (sudo / su / doas / pkexec). Never auto-allowed headlessly.\n\tif (base.rule.startsWith(\"priv.\")) {\n\t\treasons.push({ code: \"priv.escalate\", message: \"Privilege escalation requires explicit human approval.\" });\n\t\taction = bump(action, \"escalate\");\n\t}\n\n\t// Inspect dynamic-structure inner content for hidden destructive commands.\n\tfor (const node of analysis.subcommands) {\n\t\tconst innerVerdict = classifyShellCommand(node.inner);\n\t\tif (innerVerdict.risk === \"block\") {\n\t\t\treasons.push({\n\t\t\t\tcode: `exec.inner_block:${innerVerdict.rule}`,\n\t\t\t\tmessage: `Command substitution hides a destructive command: ${innerVerdict.reason}`,\n\t\t\t});\n\t\t\taction = bump(action, \"block\");\n\t\t} else if (innerVerdict.risk === \"confirm\") {\n\t\t\treasons.push({\n\t\t\t\tcode: `exec.inner_confirm:${innerVerdict.rule}`,\n\t\t\t\tmessage: `Command substitution hides a risky command: ${innerVerdict.reason}`,\n\t\t\t});\n\t\t}\n\t}\n\tfor (const node of analysis.subshells) {\n\t\tconst innerVerdict = classifyShellCommand(node.inner);\n\t\tif (innerVerdict.risk === \"block\") {\n\t\t\treasons.push({\n\t\t\t\tcode: `exec.inner_block:${innerVerdict.rule}`,\n\t\t\t\tmessage: `Subshell hides a destructive command: ${innerVerdict.reason}`,\n\t\t\t});\n\t\t\taction = bump(action, \"block\");\n\t\t} else if (innerVerdict.risk === \"confirm\") {\n\t\t\treasons.push({\n\t\t\t\tcode: `exec.inner_confirm:${innerVerdict.rule}`,\n\t\t\t\tmessage: `Subshell hides a risky command: ${innerVerdict.reason}`,\n\t\t\t});\n\t\t}\n\t}\n\tfor (const node of analysis.processSubstitutions) {\n\t\tconst innerVerdict = classifyShellCommand(node.inner);\n\t\tif (innerVerdict.risk === \"block\") {\n\t\t\treasons.push({\n\t\t\t\tcode: `exec.inner_block:${innerVerdict.rule}`,\n\t\t\t\tmessage: `Process substitution hides a destructive command: ${innerVerdict.reason}`,\n\t\t\t});\n\t\t\taction = bump(action, \"block\");\n\t\t}\n\t}\n\n\tconst hasDynamic =\n\t\tanalysis.subcommands.length > 0 || analysis.subshells.length > 0 || analysis.processSubstitutions.length > 0;\n\n\t// Dynamic plus already-risky base -> escalate (the dynamic part can hide a worse payload).\n\tif (hasDynamic && base.risk !== \"allow\") {\n\t\treasons.push({\n\t\t\tcode: \"exec.dynamic_elevated\",\n\t\t\tmessage: \"Dynamic shell structure combined with a risky base command.\",\n\t\t});\n\t\taction = bump(action, \"escalate\");\n\t}\n\n\tif (analysis.subcommands.length > 0) {\n\t\treasons.push({\n\t\t\tcode: \"exec.command_substitution\",\n\t\t\tmessage: \"Command substitution $(...) or backticks can execute arbitrary commands.\",\n\t\t});\n\t\taction = bump(action, \"confirm\");\n\t}\n\tif (analysis.subshells.length > 0) {\n\t\treasons.push({ code: \"exec.subshell\", message: \"Subshell grouping (...) can execute arbitrary commands.\" });\n\t\taction = bump(action, \"confirm\");\n\t}\n\tif (analysis.processSubstitutions.length > 0) {\n\t\treasons.push({\n\t\t\tcode: \"exec.process_substitution\",\n\t\t\tmessage: \"Process substitution <(...) or >(...) spawns a process.\",\n\t\t});\n\t\taction = bump(action, \"confirm\");\n\t}\n\n\tfor (const dp of analysis.decoderPipelines) {\n\t\treasons.push({\n\t\t\tcode: \"exec.decoder_pipeline\",\n\t\t\tmessage: `Decoder pipeline (${dp.stages[dp.decoderIndex]} -> ${dp.executor}) can execute a decoded payload.`,\n\t\t});\n\t\taction = bump(action, \"confirm\");\n\t}\n\n\tfor (const assignment of analysis.assignments) {\n\t\tif (assignment.loaderInjection) {\n\t\t\treasons.push({\n\t\t\t\tcode: \"env.loader_injection\",\n\t\t\t\tmessage: `Assignment sets loader/runtime injection variable ${assignment.name}.`,\n\t\t\t});\n\t\t\taction = bump(action, \"confirm\");\n\t\t} else if (assignment.sensitiveName) {\n\t\t\treasons.push({\n\t\t\t\tcode: \"env.sensitive_assignment\",\n\t\t\t\tmessage: `Assignment exposes a sensitive variable ${assignment.name} on the command line.`,\n\t\t\t});\n\t\t\taction = bump(action, \"confirm\");\n\t\t}\n\t}\n\n\t// Unresolved expansion inside a risky command's argument list (could expand to /, ~, or a sensitive path).\n\tfor (const seg of analysis.segments) {\n\t\tconst exec = seg.tokens[0]?.toLowerCase();\n\t\tif (!exec || !RISKY_EXPANSION_EXEC.has(exec)) continue;\n\t\tconst hasExpansion = seg.tokens.slice(1).some((tok) => tok.includes(\"$\"));\n\t\tif (hasExpansion) {\n\t\t\treasons.push({\n\t\t\t\tcode: \"exec.dynamic_target\",\n\t\t\t\tmessage: `Unresolved expansion in arguments of risky command '${exec}'.`,\n\t\t\t});\n\t\t\taction = bump(action, \"confirm\");\n\t\t}\n\t}\n\n\tfor (const diag of analysis.diagnostics) {\n\t\tif (diag.fatal) {\n\t\t\treasons.push({ code: diag.code, message: diag.message });\n\t\t\t// Parser fatal -> fail-closed to at least confirm (block stays block).\n\t\t\taction = bump(action, \"confirm\");\n\t\t}\n\t}\n\n\treturn { action, reasons, normalizedCommands, analysis };\n}\n"]}