@ory/argus 0.14.0 → 1.0.1

package/dist/bash-parser.js

@@ -0,0 +1,396 @@
+"use strict";
+/**
+ * Shell-command decomposition for fine-grained permission checks.
+ *
+ * The permission gate authorizes on *tool name* only, so a denied surface
+ * (`WebFetch`, `Read`, an MCP write) is trivially reached through
+ * `bash -c "curl …"`. This module parses a shell command with the
+ * `tree-sitter-bash` grammar (via `web-tree-sitter`) into a **structured
+ * command model** — the shared foundation for the permission work:
+ *
+ *   - #76 (this): check each command word as `ShellTool:<word>#use`.
+ *     Derived from `ParsedShell.commands.map(c => c.name)`.
+ *   - #77 (argument scoping): per-binary extractors read `ShellCommand.args`.
+ *   - #78 (combinatory dataflow): edges are built from `ShellCommand.pipeline`
+ *     grouping and `ShellCommand.redirects`.
+ *   - #79 (env escalation): `ShellCommand.assignments` and redirect targets.
+ *
+ * Building the model once (one parse, one AST walk) keeps every follow-on
+ * additive instead of re-walking the tree.
+ *
+ * **Why a grammar parser, not a regex/tokenizer.** A hand-rolled tokenizer is
+ * vulnerable to *parser-differential attacks* — where the checker reads a
+ * command differently than the shell that will run it. tree-sitter-bash gives
+ * us the shell's own view of the command.
+ *
+ * **Failure postures (two, deliberately opposite):**
+ *   - `tooComplex` — parsed but unresolvable (dynamic command name, parse
+ *     error, dynamic `sh -c` target). Security signal: enforce denies.
+ *   - `parserUnavailable` — the runtime/grammar could not load. Availability
+ *     signal: the gate falls open. A broken build must never block shell use.
+ *
+ * **Known static-analysis limits (checks for them are #77/#78/#79):** command
+ * names built at runtime, programs invoked as interpreter arguments
+ * (`python -c "…"`, `find -exec`), and dynamic dataflow. The backstop is that
+ * the decode/exec primitives themselves (`sh`, `bash`, `eval`, `base64`, …) are
+ * ordinary checked words.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractShellCommands = extractShellCommands;
+exports.extractBashCommandWords = extractBashCommandWords;
+/** Literal leaf node types whose `.text` is a real (non-expanded) string. */
+const LITERAL_LEAF_TYPES = new Set(["word", "string_content", "raw_string"]);
+/**
+ * Wrapper commands whose *argument* is another command to run. Each wrapper is
+ * itself a command; we additionally synthesize the command it wraps.
+ */
+const WRAPPERS = new Set([
+    "sudo", "doas", "env", "nohup", "setsid", "command", "exec", "nice",
+    "ionice", "chrt", "stdbuf", "time", "timeout", "xargs",
+]);
+/** Wrappers that take a numeric positional operand before the wrapped command. */
+const OPERAND_WRAPPERS = new Set(["timeout", "nice", "ionice", "chrt"]);
+/** A numeric operand (`5`, `5s`, `1.5`) consumed by an {@link OPERAND_WRAPPERS}. */
+const NUMERIC_OPERAND = /^\d+(\.\d+)?[smhdSMHD]?$/;
+/** Shells whose `-c "<script>"` argument is re-parsed as a nested command. */
+const SHELL_DASH_C = new Set(["sh", "bash", "dash", "zsh", "ksh", "ash"]);
+/** Cap re-parse recursion (`sh -c "sh -c …"`) so a pathological input can't loop. */
+const MAX_REPARSE_DEPTH = 6;
+/**
+ * Cap AST-walk recursion depth. A deeply nested command (`$( $( … ) )` thousands
+ * deep) would otherwise overflow the stack — and a thrown error would fail the
+ * gate OPEN. Past this depth we stop descending and mark the command
+ * `tooComplex` (fail-closed in enforce). Well above any real command; the
+ * grammar itself flags such inputs with ERROR nodes long before this.
+ */
+const MAX_WALK_DEPTH = 400;
+let parserPromise = null;
+/**
+ * Lazily initialize a singleton tree-sitter parser bound to the bash grammar.
+ * Returns `null` (never throws) if the WASM runtime or grammar cannot be loaded.
+ */
+async function getBashParser() {
+    if (!parserPromise) {
+        parserPromise = (async () => {
+            try {
+                const { Parser, Language } = await import("web-tree-sitter");
+                await Parser.init();
+                // GRAMMAR PARITY: this WASM bundles tree-sitter-bash 0.25.x. The Python
+                // core pins the same grammar minor (see ory-argus/pyproject.toml) so the
+                // two parse identically; the shared bash-parser-fixtures.json is the CI
+                // guard. Bump both sides together.
+                const wasmPath = require.resolve("@vscode/tree-sitter-wasm/wasm/tree-sitter-bash.wasm");
+                const bash = await Language.load(wasmPath);
+                const parser = new Parser();
+                parser.setLanguage(bash);
+                return parser;
+            }
+            catch {
+                return null;
+            }
+        })();
+    }
+    return parserPromise;
+}
+/** Strip a directory prefix: `/usr/bin/curl` → `curl`, `curl` → `curl`. */
+function basename(word) {
+    const slash = word.lastIndexOf("/");
+    return slash >= 0 ? word.slice(slash + 1) : word;
+}
+/** Strip a single matched pair of surrounding quotes, if present. */
+function stripQuotes(text) {
+    if (text.length >= 2) {
+        const first = text[0];
+        if ((first === '"' || first === "'") && text[text.length - 1] === first) {
+            return text.slice(1, -1);
+        }
+    }
+    return text;
+}
+/** The last named leaf under a node (deepest, right-most). */
+function lastLeaf(node) {
+    let cur = node;
+    while (cur.namedChildCount > 0) {
+        const next = cur.namedChild(cur.namedChildCount - 1);
+        if (!next)
+            break;
+        cur = next;
+    }
+    return cur;
+}
+/** Literal string value of a node, or `null` when any part is an expansion. */
+function literalText(node) {
+    switch (node.type) {
+        case "word":
+        case "number":
+            return node.text;
+        case "raw_string":
+            return stripQuotes(node.text);
+        case "string": {
+            let out = "";
+            for (let i = 0; i < node.namedChildCount; i++) {
+                const child = node.namedChild(i);
+                if (!child)
+                    continue;
+                if (child.type === "string_content")
+                    out += child.text;
+                else
+                    return null; // an expansion / command substitution inside
+            }
+            return out;
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Resolve a `command_name` node to a program word, or `null` when the name is
+ * dynamic (`$X`, `$(…)`, or a path whose final segment is an expansion).
+ */
+function resolveCommandName(nameNode) {
+    const child = nameNode.namedChild(0);
+    if (!child)
+        return basename(nameNode.text);
+    switch (child.type) {
+        case "word":
+            return basename(child.text);
+        case "raw_string":
+            return basename(stripQuotes(child.text));
+        case "simple_expansion":
+        case "expansion":
+        case "command_substitution":
+        case "process_substitution":
+            return null;
+        case "string":
+        case "concatenation": {
+            const leaf = lastLeaf(child);
+            if (LITERAL_LEAF_TYPES.has(leaf.type))
+                return basename(leaf.text);
+            return null;
+        }
+        default:
+            return basename(child.text);
+    }
+}
+function argNodes(cmd) {
+    return cmd.childrenForFieldName("argument").filter((n) => n !== null);
+}
+function collectAssignments(cmd) {
+    const out = [];
+    for (const child of cmd.namedChildren) {
+        if (child.type !== "variable_assignment")
+            continue;
+        const nameNode = child.childForFieldName("name");
+        const valueNode = child.childForFieldName("value");
+        if (!nameNode)
+            continue;
+        out.push({
+            name: nameNode.text,
+            value: valueNode ? literalText(valueNode) : "",
+        });
+    }
+    return out;
+}
+function collectRedirects(cmd) {
+    const parent = cmd.parent;
+    if (!parent || parent.type !== "redirected_statement")
+        return [];
+    const out = [];
+    for (const child of parent.namedChildren) {
+        if (child.type !== "file_redirect" && child.type !== "heredoc_redirect")
+            continue;
+        const dest = child.childForFieldName("destination");
+        // Operator token contains the redirect direction.
+        const opText = child.text;
+        const direction = opText.includes(">") ? "write" : "read";
+        const opChild = child.child(0);
+        out.push({
+            operator: opChild ? opChild.text : opText,
+            target: dest ? literalText(dest) ?? dest.text : null,
+            direction,
+        });
+    }
+    return out;
+}
+/**
+ * Descend a wrapper's argument list to the command it runs, synthesizing a
+ * {@link ShellCommand} for that command (and recursing through nested wrappers,
+ * e.g. `sudo env A=1 curl`).
+ */
+function descendWrapper(wrapper, args, pipeline, state) {
+    const skipsNumeric = OPERAND_WRAPPERS.has(wrapper);
+    for (let i = 0; i < args.length; i++) {
+        const txt = literalText(args[i]);
+        if (txt === null) {
+            state.tooComplex = true;
+            return;
+        }
+        if (txt.startsWith("-"))
+            continue;
+        if (/^[A-Za-z_]\w*=/.test(txt))
+            continue;
+        if (skipsNumeric && NUMERIC_OPERAND.test(txt))
+            continue;
+        const wrapped = basename(txt);
+        if (wrapped.length === 0)
+            return;
+        const rest = args.slice(i + 1);
+        state.commands.push({
+            name: wrapped,
+            args: rest.map((a) => a.text),
+            assignments: [],
+            redirects: [],
+            pipeline,
+        });
+        if (WRAPPERS.has(wrapped))
+            descendWrapper(wrapped, rest, pipeline, state);
+        return;
+    }
+}
+/** Recursively walk the tree, building the command model. */
+function walk(node, pipeline, parser, state, depth, treeDepth) {
+    // Bound recursion so a maliciously deep AST can't overflow the stack (which
+    // would throw and fail the gate open). Stop and fail closed instead.
+    if (treeDepth > MAX_WALK_DEPTH) {
+        state.tooComplex = true;
+        return;
+    }
+    if (node.type === "pipeline") {
+        const id = state.pipelineCounter++;
+        for (const child of node.children)
+            walk(child, id, parser, state, depth, treeDepth + 1);
+        return;
+    }
+    if (node.type === "command") {
+        const nameNode = node.childForFieldName("name");
+        if (!nameNode) {
+            // Assignment-only command (`FOO=bar`) — no program word. Left for #79.
+            for (const child of node.children)
+                walk(child, -1, parser, state, depth, treeDepth + 1);
+            return;
+        }
+        const pid = pipeline >= 0 ? pipeline : state.pipelineCounter++;
+        const name = resolveCommandName(nameNode);
+        if (name === null)
+            state.tooComplex = true;
+        const args = argNodes(node);
+        state.commands.push({
+            name,
+            args: args.map((a) => a.text),
+            assignments: collectAssignments(node),
+            redirects: collectRedirects(node),
+            pipeline: pid,
+        });
+        if (name && WRAPPERS.has(name))
+            descendWrapper(name, args, pid, state);
+        if (name && SHELL_DASH_C.has(name)) {
+            const flagIdx = args.findIndex((a) => {
+                const t = literalText(a);
+                return t !== null && t.startsWith("-") && t.includes("c");
+            });
+            if (flagIdx >= 0) {
+                const target = args[flagIdx + 1];
+                if (!target)
+                    state.tooComplex = true;
+                else {
+                    const script = literalText(target);
+                    if (script === null)
+                        state.tooComplex = true;
+                    else
+                        reparse(script, parser, state, depth + 1);
+                }
+            }
+        }
+        if (name === "eval") {
+            const parts = [];
+            let dynamic = false;
+            for (const a of args) {
+                const t = literalText(a);
+                if (t === null)
+                    dynamic = true;
+                else
+                    parts.push(t);
+            }
+            if (dynamic || parts.length === 0)
+                state.tooComplex = true;
+            else
+                reparse(parts.join(" "), parser, state, depth + 1);
+        }
+        // Descend into arguments for nested command substitutions ($(curl …)).
+        for (const child of node.children)
+            walk(child, -1, parser, state, depth, treeDepth + 1);
+        return;
+    }
+    for (const child of node.children) {
+        walk(child, pipeline >= 0 ? pipeline : -1, parser, state, depth, treeDepth + 1);
+    }
+}
+/** Parse a nested script string and fold its commands into `state`. */
+function reparse(script, parser, state, depth) {
+    if (depth > MAX_REPARSE_DEPTH || script.trim().length === 0)
+        return;
+    const tree = parser.parse(script);
+    if (!tree) {
+        state.tooComplex = true;
+        return;
+    }
+    if (tree.rootNode.hasError)
+        state.tooComplex = true;
+    walk(tree.rootNode, -1, parser, state, depth, 0);
+}
+/**
+ * Decompose a shell command into a {@link ParsedShell} model. Never throws.
+ * This is the shared foundation; see {@link extractBashCommandWords} for the
+ * flat word list the #76 gate uses.
+ */
+async function extractShellCommands(command) {
+    if (!command || command.trim().length === 0) {
+        return { commands: [], tooComplex: false };
+    }
+    const parser = await getBashParser();
+    if (!parser) {
+        return { commands: [], tooComplex: false, parserUnavailable: true };
+    }
+    let tree;
+    try {
+        tree = parser.parse(command);
+    }
+    catch {
+        return { commands: [], tooComplex: false, parserUnavailable: true };
+    }
+    if (!tree)
+        return { commands: [], tooComplex: true };
+    const state = { commands: [], tooComplex: false, pipelineCounter: 0 };
+    if (tree.rootNode.hasError)
+        state.tooComplex = true;
+    // The walk must never throw out of this function — an uncaught error would
+    // fail the gate OPEN. Any internal failure (e.g. an unexpected node shape or
+    // a stack limit) becomes a fail-CLOSED `tooComplex` result instead.
+    try {
+        walk(tree.rootNode, -1, parser, state, 0, 0);
+    }
+    catch {
+        return { commands: state.commands, tooComplex: true };
+    }
+    return { commands: state.commands, tooComplex: state.tooComplex };
+}
+/**
+ * Flat view of {@link extractShellCommands} for the #76 gate: the deduped set
+ * of command/builtin words the command will execute. Never throws. See
+ * {@link BashParseResult} for the two failure postures.
+ */
+async function extractBashCommandWords(command) {
+    const parsed = await extractShellCommands(command);
+    if (parsed.parserUnavailable) {
+        return { words: [], tooComplex: false, parserUnavailable: true };
+    }
+    const words = [];
+    const seen = new Set();
+    for (const cmd of parsed.commands) {
+        if (cmd.name === null || seen.has(cmd.name))
+            continue;
+        seen.add(cmd.name);
+        words.push(cmd.name);
+    }
+    return { words, tooComplex: parsed.tooComplex };
+}

package/dist/branding.d.ts

@@ -7,10 +7,13 @@
  * The policy has two tiers, because many users install these plugins against
  * the **same** Ory project:
  *
- *  - **Shared** resources (one per project, reused by every user/harness) get a
- *    **stable, identity-free** name so all installs find and reuse the one
- *    resource instead of duplicating it: {@link USER_LOGIN_CLIENT_NAME} and the
- *    permission namespace ({@link PERMISSION_NAMESPACE}).
+ *  - **Shared** resources (one per project, reused by every user/harness) are
+ *    addressed by a **stable, reserved identifier** so all installs find and
+ *    reuse the one resource instead of duplicating it: the login client's
+ *    {@link USER_LOGIN_CLIENT_ID} and the permission namespace
+ *    ({@link PERMISSION_NAMESPACE}). An identifier, not a display name — see
+ *    {@link USER_LOGIN_CLIENT_ID} for why the distinction is a security
+ *    property and not a preference.
  *  - **Per-installer** resources (many per project by design — confidential
  *    per-machine DCR credentials, write-once API keys) get an **attributable**
  *    name carrying *who* and *where*, so a shared project's resource list stays
@@ -22,36 +25,94 @@
 /** Human-readable umbrella name for everything this product creates. */
 export declare const PRODUCT_NAME = "Ory Agent Security";
 /**
- * The public PKCE client the human's browser sign-in uses. It is a *public*
- * client (no secret), so every user on a project shares the one client — the
- * installer dedupes by this exact name. Stable and identity-free on purpose.
+ * The **reserved client id** of the shared user-login OAuth2 client — the one
+ * thing that identifies it. Every provisioning path (Ory Console setup, the
+ * local-dev Hydra seed) creates the client *at this id*, and every lookup
+ * addresses it by this id, so all of them converge on one client.
+ *
+ * It is an id rather than a name for a security reason. A project set up for
+ * Agent Security has public dynamic client registration enabled, and Hydra's DCR
+ * endpoint places no restriction on `client_name` — so anyone can register a
+ * client carrying {@link USER_LOGIN_CLIENT_NAME} verbatim with their own
+ * `redirect_uris`, and a name-based lookup can resolve to it (Hydra lists
+ * clients ordered by id, so re-registering until the assigned UUID sorts first
+ * is roughly a coin flip). Whoever then installs a plugin would complete a PKCE
+ * login — `offline_access` included — against the attacker's client. A
+ * `client_id` is not forgeable the same way: Hydra assigns a fresh UUID to a
+ * dynamically registered client and refuses a caller-chosen one, so only a
+ * caller holding the project's admin credentials can claim this id.
+ *
+ * There is deliberately **no name-based fallback** anywhere: a fallback reopens
+ * exactly that hole.
+ */
+export declare const USER_LOGIN_CLIENT_ID = "ory-agent-security-login";
+/**
+ * The **display name** of the shared user-login client — a human-readable label
+ * for the Ory Console's client list, and nothing more. It is a *public* client
+ * (no secret) that every user on a project shares across every harness plugin,
+ * and the name says so plainly; no "PKCE" in it, since how it authenticates is
+ * an implementation detail, not what it is.
+ *
+ * Never resolve the client by this string. It is attacker-supplyable (see
+ * {@link USER_LOGIN_CLIENT_ID}); {@link USER_LOGIN_CLIENT_ID} is what dedupes
+ * installs onto one client, and {@link isUserLoginClient} is the only accepted
+ * test for "is this the login client".
  */
-export declare const USER_LOGIN_CLIENT_NAME = "Ory Agent Security \u00B7 user login (PKCE)";
+export declare const USER_LOGIN_CLIENT_NAME = "Ory Agent Security \u00B7 shared user login (all plugins)";
 /**
- * Names an older installer may have given the shared user-login client. The
- * reuse probe matches these too, so renaming the client never orphans one
- * created by a previous install (which would then mint a duplicate).
+ * Whether a client is *the* shared user-login client, decided **only** by its
+ * id. A client carrying {@link USER_LOGIN_CLIENT_NAME} under any other id is
+ * some other client — possibly one an attacker registered — and is rejected.
  */
-export declare const LEGACY_USER_LOGIN_CLIENT_NAMES: string[];
-/** All names the shared user-login client may carry, newest first. */
-export declare const USER_LOGIN_CLIENT_NAMES: string[];
+export declare function isUserLoginClient(client: {
+    clientId?: string;
+    clientName?: string;
+}): boolean;
+/**
+ * The single source of truth for the interactive user-login OAuth2 scopes.
+ * Every place that registers the client (`ory create/update oauth2-client`,
+ * the local-dev Hydra seed, the manual-setup help) and the PKCE flow that
+ * requests them must agree, or the flow fails with `invalid_scope` (or the
+ * requested scope is silently dropped). `openid`/`offline_access` are the
+ * baseline; `profile`/`email` populate the id_token's name claims so the
+ * signed-in user can be shown by name.
+ */
+export declare const USER_LOGIN_BASE_SCOPES: readonly ["openid", "offline_access"];
+export declare const USER_LOGIN_SCOPES: readonly string[];
+/** Space-delimited form for an OAuth2 `authorize` request / Hydra client `scope`. */
+export declare const USER_LOGIN_SCOPE_OAUTH: string;
+/** Comma-delimited form for the `ory … oauth2-client --scope` CLI flag. */
+export declare const USER_LOGIN_SCOPE_CLI: string;
 /** Default name for a project the installer creates. Harness-agnostic, since a
  *  team typically points several harnesses at one shared project. */
 export declare const DEFAULT_PROJECT_NAME = "Ory Agent Security";
 /** The shared permission-model namespace (an OPL class name, so it must stay a
  *  bare identifier — no spaces/branding — and stable across installs). */
-export declare const PERMISSION_NAMESPACE = "AgentTools";
+export declare const PERMISSION_NAMESPACE = "AgentTool";
 /**
  * The client_name for an agent's (or sub-agent's) OAuth2 identity registered
  * via DCR. These are confidential, per-machine credentials — many per shared
  * project by design — so the name is attributable: the harness it belongs to
- * and the host it was registered from (plus the sub-agent type, when it is one).
+ * and the host it was registered from, plus a short session label and the
+ * sub-agent type when applicable.
  */
 export declare function agentClientName(opts: {
     harness?: string;
     host: string;
     subAgentType?: string;
+    sessionId?: string;
 }): string;
+/**
+ * A short, stable label for a session id, for **display only** — `status`
+ * output and log lines. Ids are usually UUIDs; the leading characters separate
+ * them well enough for a human scanning a list, and the full id is always
+ * recoverable from the delegation record and activity events.
+ *
+ * Never use this to build a permission subject. A derived session subject must
+ * carry the full session id (`Agent:<clientId>|<session>`) so it matches what an
+ * admin writes in the Console after reading the same id off the delegation graph.
+ */
+export declare function shortSessionLabel(sessionId: string): string;
 /**
  * The name for a project API key minted for runtime permission checks. Ory only
  * returns a key's secret at creation, so a key can't be reused across machines