@ory/argus 0.14.0 → 1.0.0

package/dist/tool-catalog.js

@@ -1,22 +1,27 @@
 "use strict";
 /**
- * Canonical per-harness tool catalog used by `permissions bootstrap` to
- * seed Keto tuples granting the current user `use` on each tool.
+ * Canonical per-harness tool catalog: the objects an Ory project grants `use`
+ * on, and the set `permissions status` probes coverage across.
  *
  * These lists cover each harness's built-in tools — the names the harness
  * passes to the pre-tool-use hook. MCP server tools are intentionally
  * omitted because they're discovered dynamically per session and can't be
- * enumerated at bootstrap time.
+ * enumerated ahead of time.
  *
- * The lists are best-effort: harness vendors add and rename tools over
- * time. `bootstrap` is idempotent and additive, so re-running it after a
- * catalog update is safe.
+ * The lists are best-effort: harness vendors add and rename tools over time,
+ * so a project's grants may cover more or fewer names than the catalog knows.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INTERACTIVE_TOOL_CATALOG = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = void 0;
+exports.SHELL_COMMAND_CATALOG = exports.SHELL_TOOL_CATALOG = exports.INTERACTIVE_TOOL_CATALOG = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = void 0;
 exports.getToolCatalog = getToolCatalog;
 exports.getInteractiveToolCatalog = getInteractiveToolCatalog;
 exports.isInteractiveTool = isInteractiveTool;
+exports.getShellToolCatalog = getShellToolCatalog;
+exports.isShellTool = isShellTool;
+exports.getShellCommandCatalog = getShellCommandCatalog;
+exports.resolveShellCommandNamespace = resolveShellCommandNamespace;
+exports.extractShellCommand = extractShellCommand;
+const opl_js_1 = require("./opl.js");
 /**
  * Built-in tool names known to ship with each supported harness.
  */
@@ -43,7 +48,7 @@ exports.HARNESS_TOOL_CATALOG = {
     ],
     // The Claude Agent SDK exposes the same built-in tool surface as Claude
     // Code (it is the embeddable form of the same runtime), so the catalog
-    // mirrors claude-code's and `permissions bootstrap` can seed it.
+    // mirrors claude-code's.
     "claude-agent-sdk": [
         "Read",
         "Write",
@@ -135,20 +140,36 @@ exports.HARNESS_TOOL_CATALOG = {
         "search_web",
         "call_mcp_tool",
     ],
+    // Cursor's `preToolUse` hook serializes `tool_name` as a coarse tool
+    // category (Shell, Read, Write, Edit, Delete, List, Search, MCP, Task);
+    // fine-grained shell commands and MCP tools arrive on the dedicated
+    // `beforeShellExecution` / `beforeMCPExecution` hooks (logged, not gated,
+    // to avoid double-gating). Bootstrap seeds the categories the agent gate
+    // actually checks. Best-effort — verify against your Cursor version.
+    cursor: [
+        "Read",
+        "Write",
+        "Edit",
+        "Delete",
+        "Shell",
+        "List",
+        "Search",
+        "MCP",
+        "Task",
+    ],
 };
 exports.KNOWN_HARNESSES = Object.keys(exports.HARNESS_TOOL_CATALOG);
 /**
  * Tools for a specific harness. Returns the canonical list when known;
  * empty array for unknown harnesses (callers can fall back to {@link
- * ALL_TOOLS} or skip bootstrap with a warning).
+ * ALL_TOOLS} or skip the catalog-scoped step with a warning).
  */
 function getToolCatalog(harness) {
     return (exports.HARNESS_TOOL_CATALOG[harness] ?? []);
 }
 /**
- * Union of every known tool across all harnesses, deduplicated. Used by
- * the dev launcher's seed routine, which grants the local user identity
- * broad access so the same launcher can run every harness end-to-end.
+ * Union of every known tool across all harnesses, deduplicated. Used by local
+ * environment seeding to grant broad access across every built-in tool set.
  */
 exports.ALL_TOOLS = Array.from(new Set(Object.values(exports.HARNESS_TOOL_CATALOG).flat()));
 /**
@@ -161,7 +182,7 @@ exports.ALL_TOOLS = Array.from(new Set(Object.values(exports.HARNESS_TOOL_CATALO
  * the user is about to handle directly.
  *
  * Plugins consult this list in their pre-tool gate and short-circuit to
- * a single `user.interaction` audit span when a match is found. See
+ * a single `user.interaction` audit event when a match is found. See
  * `gateToolCall` in `permissions.ts`.
  *
  * The list is best-effort and additive: operators can extend it at
@@ -183,6 +204,7 @@ exports.INTERACTIVE_TOOL_CATALOG = {
     amp: [],
     pi: [],
     antigravity: [],
+    cursor: [],
 };
 function parseEnvInteractiveTools() {
     const raw = process.env.ORY_INTERACTIVE_TOOLS;
@@ -215,3 +237,132 @@ function getInteractiveToolCatalog(harness) {
 function isInteractiveTool(harness, toolName) {
     return getInteractiveToolCatalog(harness).includes(toolName);
 }
+// ─── Shell-command decomposition (issue #76) ───────────────────────
+/**
+ * Per-harness name(s) of the shell/exec tool whose input is decomposed into
+ * `ShellTool:<word>#use` sub-checks. Validated against each harness's
+ * types/handlers. Names vary (`Bash`, `shell`, `exec`, `run_command`, …) so a
+ * precise map is used rather than the {@link isBashLikeTool} heuristic.
+ */
+exports.SHELL_TOOL_CATALOG = {
+    "claude-code": ["Bash"],
+    "claude-agent-sdk": ["Bash"],
+    codex: ["Bash"],
+    // Gemini CLI's hook payload has been observed with both the short `shell`
+    // name and the fuller `run_shell_command` id across versions; accept both so
+    // decomposition fires regardless. `ORY_SHELL_TOOLS` remains the escape hatch.
+    "gemini-cli": ["shell", "run_shell_command"],
+    openclaw: ["exec"],
+    opencode: ["bash"],
+    continue: ["Bash"],
+    goose: ["shell"],
+    cline: ["execute_command"],
+    amp: ["Bash"],
+    pi: ["bash"],
+    antigravity: ["run_command"],
+};
+function parseEnvList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(",")
+        .map((v) => v.trim())
+        .filter((v) => v.length > 0);
+}
+/**
+ * Shell-tool names for a harness, merged with the operator env extension
+ * `ORY_SHELL_TOOLS` (same pattern as `ORY_INTERACTIVE_TOOLS`) so a vendor tool
+ * rename can be handled without a plugin release.
+ */
+function getShellToolCatalog(harness) {
+    const builtIn = exports.SHELL_TOOL_CATALOG[harness] ?? [];
+    const envExtra = parseEnvList(process.env.ORY_SHELL_TOOLS);
+    if (envExtra.length === 0)
+        return builtIn;
+    return Array.from(new Set([...builtIn, ...envExtra]));
+}
+/** Is the named tool, for this harness, the shell/exec tool to decompose? */
+function isShellTool(harness, toolName) {
+    return getShellToolCatalog(harness).includes(toolName);
+}
+/**
+ * Broad list of shell command *words* — common dev binaries, sensitive
+ * binaries, and builtins — that an Ory project is expected to grant `use` on
+ * so enforce mode is practical out of the box; revoke a specific word in the
+ * Ory Console to close it. Builtins are included because they are a real
+ * bypass surface (`echo "$SECRET" >/dev/tcp/…`, `read`, redirection tricks).
+ * `permissions status` reports coverage against this list.
+ */
+exports.SHELL_COMMAND_CATALOG = [
+    // network / transfer
+    "curl", "wget", "nc", "ncat", "socat", "ssh", "scp", "sftp", "rsync", "ftp",
+    "telnet",
+    // databases
+    "psql", "mysql", "mysqldump", "mongo", "mongosh", "redis-cli", "sqlite3",
+    // interpreters
+    "python", "python3", "node", "ruby", "perl", "php", "deno", "bun",
+    // shells / eval
+    "sh", "bash", "dash", "zsh", "ksh", "eval", "exec", "source",
+    // file read / transform
+    "cat", "less", "more", "head", "tail", "grep", "egrep", "fgrep", "sed", "awk",
+    "tee", "cut", "sort", "uniq", "tr", "xxd", "od", "strings", "dd", "base64",
+    // filesystem mutation
+    "rm", "mv", "cp", "ln", "chmod", "chown", "chgrp", "mkdir", "rmdir", "touch",
+    "truncate",
+    // discovery
+    "ls", "find", "which", "stat", "file", "du", "df",
+    // vcs / package / cloud / container
+    "git", "npm", "npx", "pnpm", "yarn", "pip", "pip3", "docker", "kubectl",
+    "helm", "aws", "gcloud", "az", "gh", "terraform",
+    // process / wrappers
+    "sudo", "env", "xargs", "kill", "pkill", "ps",
+    // builtins
+    "cd", "echo", "printf", "export", "pwd", "test", "read", "set", "unset",
+    "alias", "true", "false", ":",
+];
+/**
+ * The shell command word list, merged with the operator env extension
+ * `ORY_SHELL_COMMANDS`.
+ */
+function getShellCommandCatalog() {
+    const envExtra = parseEnvList(process.env.ORY_SHELL_COMMANDS);
+    if (envExtra.length === 0)
+        return exports.SHELL_COMMAND_CATALOG;
+    return Array.from(new Set([...exports.SHELL_COMMAND_CATALOG, ...envExtra]));
+}
+/**
+ * Keto namespace for shell-command sub-tools. Defaults to `ShellTool`,
+ * parallel to `mcp_servers` / `mcp_tools`. The object is the bare word (`curl`),
+ * relation `use`. Override with `ORY_SHELL_COMMAND_NAMESPACE`.
+ */
+function resolveShellCommandNamespace() {
+    return process.env.ORY_SHELL_COMMAND_NAMESPACE ?? opl_js_1.DEFAULT_SHELL_NAMESPACE;
+}
+/** Command-input field spellings across harnesses (claude/codex/…, antigravity). */
+const SHELL_COMMAND_FIELDS = [
+    "command",
+    "cmd",
+    "command_line",
+    "commandLine",
+    "CommandLine",
+];
+/**
+ * Extract the shell command string from a harness's tool-args object — the same
+ * object the handler already passes to `summarizeToolInput`. Returns `undefined`
+ * when the tool isn't a shell tool for this harness or no command field is
+ * present (the gate then skips decomposition and degrades to the top-level
+ * `Bash` check — it never breaks).
+ */
+function extractShellCommand(harness, toolName, args) {
+    if (!isShellTool(harness, toolName))
+        return undefined;
+    if (!args || typeof args !== "object")
+        return undefined;
+    const obj = args;
+    for (const field of SHELL_COMMAND_FIELDS) {
+        const value = obj[field];
+        if (typeof value === "string" && value.length > 0)
+            return value;
+    }
+    return undefined;
+}

package/dist/tool-metadata.d.ts

@@ -2,11 +2,11 @@
  * Privacy-preserving summarizers for tool input/output.
  *
  * Plugins must NEVER record raw tool content (commands, file bodies,
- * URLs with query strings, prompts) directly into trace attributes.
+ * URLs with query strings, prompts) directly into activity attributes.
  * These helpers emit only:
  *   - byte size (proxy for "how much data")
  *   - sha256-truncated content hash (for dedup / "we've seen this before")
- *   - a small set of safe per-tool fields (exit code, file path, URL host)
+ *   - a small set of safe per-tool fields (exit code and path/host hashes)
  *
  * Anything that could reflect content goes through here so the redaction
  * policy lives in one place.
@@ -17,10 +17,11 @@ export interface ToolInputSummary {
     /** Bash/shell — not the command itself. */
     bashCommandBytes?: number;
     bashCommandHash?: string;
-    /** File ops — path is metadata, file *contents* are not captured. */
-    filePath?: string;
-    /** Network ops — host only, never path or query string. */
-    urlHost?: string;
+    /** File ops — raw paths can contain user/workspace names. */
+    filePathBytes?: number;
+    filePathHash?: string;
+    /** Network ops — even hosts can identify private infrastructure. */
+    urlHostHash?: string;
 }
 export interface ToolOutputSummary {
     outputBytes?: number;

package/dist/tool-metadata.js

@@ -3,11 +3,11 @@
  * Privacy-preserving summarizers for tool input/output.
  *
  * Plugins must NEVER record raw tool content (commands, file bodies,
- * URLs with query strings, prompts) directly into trace attributes.
+ * URLs with query strings, prompts) directly into activity attributes.
  * These helpers emit only:
  *   - byte size (proxy for "how much data")
  *   - sha256-truncated content hash (for dedup / "we've seen this before")
- *   - a small set of safe per-tool fields (exit code, file path, URL host)
+ *   - a small set of safe per-tool fields (exit code and path/host hashes)
  *
  * Anything that could reflect content goes through here so the redaction
  * policy lives in one place.
@@ -38,18 +38,19 @@ function summarizeToolInput(toolName, input) {
             result.bashCommandBytes = Buffer.byteLength(command, "utf8");
             result.bashCommandHash = sha256Prefix(command);
         }
-        // File ops: path is metadata. We do NOT capture file content/body fields
+        // File ops: summarize paths because they can contain user/workspace names.
         // (e.g. `content`, `new_string`, `text`, `body`).
         const filePath = pickString(obj, ["file_path", "filePath", "path"]);
         if (filePath !== undefined) {
-            result.filePath = filePath;
+            result.filePathBytes = Buffer.byteLength(filePath, "utf8");
+            result.filePathHash = sha256Prefix(filePath);
         }
         // Network/fetch tools: extract host only, drop path + query string.
         const url = pickString(obj, ["url", "URL", "endpoint"]);
         if (url !== undefined) {
             const host = extractHost(url);
             if (host)
-                result.urlHost = host;
+                result.urlHostHash = sha256Prefix(host);
         }
     }
     return result;

package/dist/types.d.ts

@@ -46,7 +46,17 @@ export interface BatchPermissionResult {
     checks: PermissionCheck[];
     checkedAt: string;
 }
-export type OryErrorCode = "session_inactive" | "session_aal2_required" | "forbidden" | "rate_limited" | "not_found" | "network_error" | "unknown";
+export type OryErrorCode = "session_inactive" | "session_aal2_required" | "forbidden" | "rate_limited" | "not_found" | "network_error"
+/**
+ * TLS/certificate verification failed — an expired, self-signed, or otherwise
+ * untrusted certificate on the project host. Distinct from `network_error`
+ * because the posture differs: a socket-level blip is a transport failure and
+ * fails open, whereas a certificate failure means we cannot establish *who we
+ * are talking to*, so the check result cannot be trusted at all. It is also
+ * precisely the failure an active network attacker produces, so under
+ * `enforce` it denies rather than passing the tool through.
+ */
+ | "tls_error" | "unknown";
 export interface OryError {
     code: OryErrorCode;
     status?: number;

package/dist/uninstall.d.ts

@@ -1,39 +1,63 @@
 /**
  * Config teardown shared by every plugin's `uninstall` command.
  *
- * Uninstalling a plugin wipes the shared config file completely — every
- * value is removed, both *authentication* state (user tokens, agent DCR
- * credentials, static API key) and *configuration* (project URL, OAuth2
- * client id, audit mode, permission mode, user-login flag). The file is
- * left as an empty object, so a later re-install starts from a clean
- * slate rather than inheriting any stale state.
+ * `config.json` is a **single shared file** every installed harness plugin
+ * reads, so teardown is scoped: uninstalling one plugin must not knock the
+ * others back to an unconfigured state. Two scopes exist, and which one runs is
+ * decided from the install registry, not from a flag the caller guesses at:
  *
- * What is removed:
+ *   - **`harness` scope** — other plugins are still installed. Only the
+ *     departing harness's own identities go: the agent and sub-agent DCR
+ *     clients of **every session it retains** are revoked (RFC 7592), and its
+ *     entries are removed from `agent.dynamic` / `agent.subAgents`. Shared
+ *     state — `projectUrl`, `oauth2ClientId`, the user's tokens, the permission
+ *     mode — is left exactly as it was.
+ *   - **`all` scope** — the departing harness was the last one installed, or
+ *     the caller passed `purge: true`. Every harness's clients are revoked and
+ *     the config file is left as an empty object, so a re-install starts from a
+ *     clean slate rather than inheriting stale state.
+ *
+ * What an `all` teardown removes:
  *   - the user's persisted OAuth2 tokens (`user`)
- *   - the agent's dynamic-registration credentials and every sub-agent
- *     registration (`agent`)
- *   - the operator-supplied static agent API key (`apiKey`)
+ *   - every harness's agent and sub-agent registrations, across all sessions
+ *     (`agent`)
  *   - all configuration values (`projectUrl`, `projectId`, `projectName`,
- *     `workspaceName`, `oauth2ClientId`, `auditOnly`, `permissionMode`,
- *     `userLogin`, `userSubjectNamespace`)
+ *     `workspaceName`, `oauth2ClientId`, `permissionModeCache`,
+ *     `userSubjectNamespace`, `installedHarnesses`)
  *   - any dangling PKCE-flight lock
  *
- * Server-side teardown runs first, best-effort:
- *   - Each dynamically-registered OAuth2 client (the agent and every
- *     sub-agent) is revoked via RFC 7592, so the Ory project isn't left
- *     with orphaned clients accumulating across install/uninstall cycles.
- *   - The project API key the installer minted is deleted via the Ory
- *     Console API (addressed by the persisted token id).
+ * Server-side teardown runs first, best-effort, and covers exactly the
+ * resources the plugin itself created: each dynamically-registered OAuth2
+ * client in scope (the agent and every sub-agent, for every retained session)
+ * is revoked via RFC 7592, so the Ory project isn't left with orphaned clients
+ * accumulating across install/uninstall cycles.
  *
- * The one server-side resource deliberately **left behind** is the shared
- * user-login PKCE OAuth2 client (`oauth2ClientId`): it is a public,
- * identity-free client that every user and every harness install on the
- * project reuses, so deleting it would break other installations. It is
- * only forgotten locally (its id is wiped from the config file). Every
- * server-side step is best-effort: failures warn and local state is
- * cleared regardless.
+ * Nothing in the project's **permission** state is touched. Grants, blocks,
+ * delegation edges, and the permission model are provisioned in the Ory
+ * Console (Agent Security) and owned there — the plugin has no Keto write
+ * path to unwind them with, and deleting an admin's grants on uninstall was
+ * never its call to make. The shared user-login PKCE OAuth2 client
+ * (`oauth2ClientId`) is likewise left in place: it is a public, identity-free
+ * client that every user and every harness install on the project reuses, so
+ * deleting it would break other installations. Both are only forgotten
+ * locally. Every server-side step is best-effort: failures warn and local
+ * state is cleared regardless.
  */
+import { type OryPluginConfig } from "./config.js";
 export interface ClearCredentialsOptions {
+    /**
+     * The harness being uninstalled. When other harness plugins are still
+     * installed, teardown is scoped to this one and the shared config survives.
+     * Omitted ⇒ the caller can't say whose state this is, so the whole config is
+     * wiped (the pre-scoping behavior).
+     */
+    harness?: string;
+    /**
+     * Force a full wipe of the shared config and every harness's credentials,
+     * even when other plugins are still installed. Backs an explicit
+     * `uninstall --purge`. Default: `false`.
+     */
+    purge?: boolean;
     /**
      * Best-effort RFC 7592 `DELETE` of the agent + sub-agent dynamic clients
      * before clearing local state. Default: `true`. Set `false` to clear
@@ -46,20 +70,33 @@ export interface ClearCredentialsOptions {
 export interface ClearCredentialsResult {
     /** Whether any credential was present before clearing. */
     hadCredentials: boolean;
+    /**
+     * `harness` — only the departing harness's state was removed and the shared
+     * config survives; `all` — everything was wiped (last plugin, or `purge`).
+     */
+    scope: "harness" | "all";
+    /** Harness plugins still installed after this uninstall. */
+    remainingHarnesses: string[];
     /** Number of dynamic clients revoked server-side (includes already-gone). */
     revoked: number;
     /** Number of dynamic clients whose server-side revoke failed. */
     revokeFailures: number;
-    /**
-     * Whether the project API key was deleted server-side (includes an
-     * already-gone key). `false` when there was none to delete, its token id
-     * wasn't tracked, or the deletion failed/was skipped.
-     */
-    apiKeyDeleted: boolean;
 }
 /**
- * Wipe the shared config file completely — every value, both credentials
- * and configuration — revoking dynamically-registered clients server-side
- * first. The file is left as an empty object. Never throws.
+ * The harness plugins installed against the shared config, reconciled from
+ * every source that evidences one.
+ *
+ * The `installedHarnesses` registry is authoritative, but it only exists on
+ * configs written since it was introduced. Treating its absence as "nothing is
+ * installed" would make the first uninstall on an upgraded machine wipe the
+ * config every other plugin depends on — precisely the failure being fixed. So
+ * the runtime manifest (what each harness has wired) and the persisted
+ * credentials (which harnesses hold an identity) are folded in as evidence.
+ */
+export declare function resolveInstalledHarnesses(config?: OryPluginConfig): string[];
+/**
+ * Tear down the departing harness's state, wiping the whole shared config only
+ * when nothing else still depends on it. Dynamically-registered clients in
+ * scope are revoked server-side first. Never throws.
  */
 export declare function clearCredentialsForUninstall(options?: ClearCredentialsOptions): Promise<ClearCredentialsResult>;