@ory/argus 0.13.9 → 1.0.0

package/dist/logger.js

@@ -33,15 +33,67 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DebugLogger = void 0;
+exports.DebugLogger = exports.ActiveActivity = void 0;
 exports.redactLogData = redactLogData;
+exports.activityValueHash = activityValueHash;
+exports.sanitizeActivityAttributes = sanitizeActivityAttributes;
+exports.formatLogEntryParts = formatLogEntryParts;
+exports.formatLogEntry = formatLogEntry;
 exports.withQuietStderr = withQuietStderr;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
-/**
- * Keys whose values are always redacted before being written to stderr or
- * to the log file. Match is case-insensitive on the final path segment.
- */
+const node_crypto_1 = require("node:crypto");
+const context_js_1 = require("./context.js");
+const MAX_BUFFERED_ACTIVITIES = 1_000;
+const ACTIVITY_HASH_LENGTH = 16;
+// These values are bounded vocabularies or names needed to interpret an event.
+// Every other string is summarized before it reaches the always-on activity sink.
+const SAFE_ACTIVITY_STRING_KEYS = new Set([
+    "alertKind",
+    "blockReason",
+    "blockedPrincipalLevel",
+    "checkRejected",
+    "composerMode",
+    "delegation",
+    "delegationKind",
+    "decision",
+    "event",
+    "failureType",
+    "harness",
+    "kind",
+    "mcpServer",
+    "mcpTool",
+    "mode",
+    "model",
+    "namespace",
+    "notificationType",
+    "object",
+    "permissionMode",
+    "postureSource",
+    "relation",
+    "reasonCode",
+    "revoke",
+    "scope",
+    "severity",
+    "source",
+    "stage",
+    "status",
+    "subAgentType",
+    "toolName",
+    "trigger",
+]);
+const SAFE_ACTIVITY_STRING_ARRAY_KEYS = new Set(["missing", "shellDeniedWords", "shellWords"]);
+const SAFE_ACTIVITY_ID_KEYS = new Set(["oryRequestId"]);
+const SAFE_ACTIVITY_ERROR_CODES = new Set([
+    "forbidden",
+    "network_error",
+    "not_found",
+    "rate_limited",
+    "session_aal2_required",
+    "session_inactive",
+    "tls_error",
+    "unknown",
+]);
 const REDACTED_KEYS = new Set([
     "accesstoken",
     "access_token",
@@ -51,50 +103,119 @@ const REDACTED_KEYS = new Set([
     "id_token",
     "sessiontoken",
     "session_token",
+    "token",
     "code_verifier",
     "codeverifier",
     "client_secret",
     "clientsecret",
     "authorization",
+    "cookie",
     "password",
     "apikey",
     "api_key",
 ]);
-/**
- * Recursively redact sensitive values from a structured log payload.
- * The original object is not modified.
- */
 function redactLogData(value) {
-    if (Array.isArray(value)) {
+    if (Array.isArray(value))
         return value.map(redactLogData);
-    }
     if (value && typeof value === "object") {
         const out = {};
-        for (const [k, v] of Object.entries(value)) {
-            if (REDACTED_KEYS.has(k.toLowerCase()) && v !== undefined && v !== null) {
-                out[k] = "[redacted]";
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = REDACTED_KEYS.has(key.toLowerCase()) && item !== undefined && item !== null
+                ? "[redacted]"
+                : redactLogData(item);
+        }
+        return out;
+    }
+    return value;
+}
+function activityValueHash(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value).digest("hex").slice(0, ACTIVITY_HASH_LENGTH);
+}
+/** Convert arbitrary strings to correlation-safe summaries for always-on activity. */
+function sanitizeActivityAttributes(attributes) {
+    const out = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (typeof value === "string") {
+            if (value === "[redacted]"
+                || SAFE_ACTIVITY_STRING_KEYS.has(key)
+                || SAFE_ACTIVITY_ID_KEYS.has(key)
+                || (key === "error" && SAFE_ACTIVITY_ERROR_CODES.has(value))
+                || (key.endsWith("Hash") && /^[a-f0-9]{16,64}$/i.test(value))) {
+                out[key] = value;
             }
             else {
-                out[k] = redactLogData(v);
+                out[`${key}Bytes`] = Buffer.byteLength(value, "utf8");
+                out[`${key}Hash`] = activityValueHash(value);
             }
+            continue;
         }
-        return out;
+        if (Array.isArray(value)) {
+            if (value.every((item) => typeof item === "string")) {
+                if (SAFE_ACTIVITY_STRING_ARRAY_KEYS.has(key)) {
+                    out[key] = value;
+                }
+                else {
+                    out[`${key}Count`] = value.length;
+                    out[`${key}Hashes`] = value.map(activityValueHash);
+                }
+                continue;
+            }
+            out[key] = value.map((item) => {
+                if (typeof item === "string")
+                    return activityValueHash(item);
+                if (item && typeof item === "object") {
+                    return sanitizeActivityAttributes(item);
+                }
+                return item;
+            });
+            continue;
+        }
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+            out[key] = sanitizeActivityAttributes(value);
+            continue;
+        }
+        out[key] = value;
+    }
+    return out;
+}
+class ActiveActivity {
+    logger;
+    event;
+    baseAttributes;
+    sessionId;
+    startedAt = performance.now();
+    timestamp = new Date().toISOString();
+    endedEntry;
+    constructor(logger, event, baseAttributes, sessionId) {
+        this.logger = logger;
+        this.event = event;
+        this.baseAttributes = baseAttributes;
+        this.sessionId = sessionId;
+    }
+    get ended() {
+        return this.endedEntry !== undefined;
+    }
+    end(status, attributes) {
+        if (this.endedEntry)
+            return this.endedEntry;
+        this.endedEntry = this.logger.activity(this.event, status, {
+            durationMs: Math.round(performance.now() - this.startedAt),
+            timestamp: this.timestamp,
+            sessionId: this.sessionId,
+            attributes: { ...this.baseAttributes, ...attributes },
+        });
+        return this.endedEntry;
     }
-    return value;
 }
+exports.ActiveActivity = ActiveActivity;
 class DebugLogger {
-    /**
-     * Process-global switch to suppress the stderr firehose while still writing
-     * to the log file. The interactive installer sets this so structured debug
-     * JSON (`[ory-agent] {...}`) doesn't interleave with the wizard's
-     * human-facing UI when a session runs with `ORY_AGENT_DEBUG=true` (the dev
-     * launcher, for one, always sets it). File logging — the real observability
-     * channel — is unaffected.
-     */
     static stderrSuppressed = false;
     enabled;
     harness;
     logFile;
+    activityEntries = [];
+    activityEnricher = null;
+    activitySink = null;
     constructor(harness, opts) {
         this.enabled = process.env.ORY_AGENT_DEBUG === "true";
         this.harness = harness;
@@ -109,12 +230,60 @@ class DebugLogger {
     disable() {
         this.enabled = false;
     }
+    setActivityEnricher(enricher) {
+        this.activityEnricher = enricher;
+    }
+    setActivitySink(sink) {
+        this.activitySink = sink;
+    }
+    activities() {
+        return this.activityEntries;
+    }
+    startActivity(event, attributes, sessionId) {
+        return new ActiveActivity(this, event, attributes, sessionId);
+    }
+    activity(event, status, options = {}) {
+        let enriched;
+        try {
+            enriched = this.activityEnricher?.();
+        }
+        catch {
+            enriched = undefined;
+        }
+        const merged = { ...enriched, ...options.attributes };
+        const safeAttributes = Object.keys(merged).length > 0
+            ? sanitizeActivityAttributes(redactLogData(merged))
+            : undefined;
+        const sessionId = options.sessionId ?? (0, context_js_1.currentSessionContext)().sessionId;
+        const entry = {
+            timestamp: options.timestamp ?? new Date().toISOString(),
+            level: "activity",
+            event,
+            harness: this.harness,
+            status,
+            durationMs: options.durationMs ?? 0,
+            ...(sessionId ? { sessionId } : {}),
+            ...(safeAttributes ? { attributes: safeAttributes } : {}),
+        };
+        this.activityEntries.push(entry);
+        if (this.activityEntries.length > MAX_BUFFERED_ACTIVITIES) {
+            this.activityEntries.splice(0, this.activityEntries.length - MAX_BUFFERED_ACTIVITIES);
+        }
+        if (this.enabled)
+            this.writeToStderr(entry);
+        this.writeToFile(entry);
+        try {
+            this.activitySink?.(entry);
+        }
+        catch {
+            // Remote reporting must never affect local activity or a hook decision.
+        }
+        return entry;
+    }
     log(level, event, data) {
         if (!this.enabled)
             return;
-        const safeData = data
-            ? redactLogData(data)
-            : undefined;
+        const safeData = data ? redactLogData(data) : undefined;
         const entry = {
             timestamp: new Date().toISOString(),
             level,
@@ -122,54 +291,151 @@ class DebugLogger {
             harness: this.harness,
             ...(safeData ? { data: safeData } : {}),
         };
-        const line = JSON.stringify(entry);
-        // Write to stderr (never stdout) so we don't interfere with hook stdout,
-        // unless the stderr firehose is globally suppressed (e.g. during the
-        // interactive installer, so it doesn't clutter the wizard UI). The log
-        // file below still captures everything.
-        if (!DebugLogger.stderrSuppressed) {
-            process.stderr.write(`[ory-agent] ${line}\n`);
+        this.writeToStderr(entry);
+        this.writeToFile(entry);
+    }
+    debug(event, data) { this.log("debug", event, data); }
+    info(event, data) { this.log("info", event, data); }
+    warn(event, data) { this.log("warn", event, data); }
+    error(event, data) { this.log("error", event, data); }
+    writeToStderr(entry) {
+        if (DebugLogger.stderrSuppressed)
+            return;
+        try {
+            process.stderr.write(`[ory-agent] ${JSON.stringify(entry)}\n`);
         }
-        if (this.logFile) {
-            const dir = path.dirname(this.logFile);
-            if (!fs.existsSync(dir)) {
-                fs.mkdirSync(dir, { recursive: true });
-            }
-            fs.appendFileSync(this.logFile, line + "\n");
+        catch {
+            // Logging must never affect a hook decision.
         }
     }
-    debug(event, data) {
-        this.log("debug", event, data);
+    writeToFile(entry) {
+        if (!this.logFile)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.logFile), { recursive: true });
+            fs.appendFileSync(this.logFile, JSON.stringify(entry) + "\n");
+        }
+        catch {
+            // Activity/audit persistence is best-effort and must never block a hook.
+        }
+    }
+}
+exports.DebugLogger = DebugLogger;
+const STATUS_MARKERS = {
+    ok: "+",
+    error: "!",
+    denied: "x",
+    skipped: "-",
+};
+function displayValue(value) {
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        const text = String(value).replace(/\s+/g, " ");
+        return text.length > 240 ? `${text.slice(0, 237)}...` : text;
     }
-    info(event, data) {
-        this.log("info", event, data);
+    if (Array.isArray(value) && value.every((item) => typeof item === "string" || typeof item === "number" || typeof item === "boolean")) {
+        return displayValue(value.join(","));
     }
-    warn(event, data) {
-        this.log("warn", event, data);
+    return undefined;
+}
+function decisionFor(entry, values) {
+    const explicit = displayValue(values.decision);
+    if (explicit)
+        return explicit;
+    if (values.observed === true && values.allowed === false)
+        return "observe";
+    if (values.allowed === true)
+        return "allow";
+    if (values.allowed === false)
+        return "deny";
+    if (values.securityConnected === false)
+        return "not_connected";
+    if (entry.level === "activity" && entry.status === "error")
+        return "error";
+    if (entry.event.includes("fail_open"))
+        return "fail_open";
+    if (entry.event.endsWith(".failed") || entry.event.endsWith(".failure"))
+        return "error";
+    return undefined;
+}
+function formatEntryDetails(entry) {
+    const values = entry.level === "activity" ? entry.attributes ?? {} : entry.data ?? {};
+    const details = [];
+    const decision = decisionFor(entry, values);
+    const tool = displayValue(values.toolName ?? values.tool);
+    const mode = displayValue(values.permissionMode ?? values.mode);
+    const error = displayValue(values.error ?? values.code);
+    const message = displayValue(values.message);
+    if (entry.level === "activity")
+        details.push(`status=${entry.status}`);
+    if (decision)
+        details.push(`decision=${decision}`);
+    if (tool)
+        details.push(`tool=${tool}`);
+    for (const key of [
+        "namespace",
+        "object",
+        "relation",
+        "blockReason",
+        "reasonCode",
+        "reason",
+        "stage",
+        "kind",
+        "trigger",
+    ]) {
+        const value = displayValue(values[key]);
+        if (value)
+            details.push(`${key}=${value}`);
     }
-    error(event, data) {
-        this.log("error", event, data);
+    if (mode)
+        details.push(`mode=${mode}`);
+    if (error)
+        details.push(`error=${error}`);
+    const status = entry.level !== "activity" ? displayValue(values.status) : undefined;
+    if (status)
+        details.push(`http=${status}`);
+    if (message)
+        details.push(`message=${message}`);
+    for (const key of ["count", "allowed", "denied", "tooComplex"]) {
+        if ((key === "allowed" || key === "denied") && typeof values[key] === "boolean")
+            continue;
+        const value = displayValue(values[key]);
+        if (value !== undefined)
+            details.push(`${key}=${value}`);
     }
+    const shellWords = displayValue(values.shellWords ?? values.words);
+    if (shellWords)
+        details.push(`commands=${shellWords}`);
+    const deniedWords = displayValue(values.shellDeniedWords);
+    if (deniedWords)
+        details.push(`deniedCommands=${deniedWords}`);
+    const command = displayValue(values.command);
+    if (command)
+        details.push(`command=${command}`);
+    if (entry.level === "activity" && entry.durationMs > 0)
+        details.push(`duration=${entry.durationMs}ms`);
+    if (entry.level === "activity" && entry.sessionId)
+        details.push(`session=${entry.sessionId}`);
+    return details;
+}
+function formatLogEntryParts(entry) {
+    return {
+        time: entry.timestamp.slice(11, 23),
+        event: entry.event,
+        marker: entry.level === "activity" ? STATUS_MARKERS[entry.status] : `[${entry.level}]`,
+        details: formatEntryDetails(entry),
+    };
+}
+function formatLogEntry(entry) {
+    const { time, event, marker, details } = formatLogEntryParts(entry);
+    return `${time} ${event.padEnd(28)} ${marker}${details.length ? ` ${details.join(" ")}` : ""}`;
 }
-exports.DebugLogger = DebugLogger;
-/**
- * Run `fn` with the structured stderr firehose suppressed, restoring the
- * previous state afterward (even on throw). File logging is unaffected.
- *
- * Human-facing CLI commands (the interactive installer, `status`,
- * `permissions status`/`bootstrap`) spin up a client and emit debug/info
- * events; when the process runs with `ORY_AGENT_DEBUG=true` (the dev launcher
- * always sets it) those `[ory-agent] {...}` lines would interleave with the
- * command's polished output. Wrapping the command body in this keeps the
- * terminal clean while the log file still captures everything.
- */
 async function withQuietStderr(fn) {
-    const prev = DebugLogger.stderrSuppressed;
+    const previous = DebugLogger.stderrSuppressed;
     DebugLogger.stderrSuppressed = true;
     try {
         return await fn();
     }
     finally {
-        DebugLogger.stderrSuppressed = prev;
+        DebugLogger.stderrSuppressed = previous;
     }
 }

package/dist/mcp.d.ts

@@ -30,10 +30,10 @@ export interface McpPermissionCheckOptions {
     checkToolLevel?: boolean;
     /**
      * Attributes merged into the permission.check / permission.batch_check
-     * trace spans. Use this to carry the harness-side tool name and any
+     * activity events. Use this to carry the harness-side tool name and any
      * other context the Zanzibar tuple shape doesn't capture.
      */
-    spanAttributes?: Record<string, unknown>;
+    activityAttributes?: Record<string, unknown>;
 }
 export interface McpPermissionResult {
     /** Whether the server-level check passed. */

package/dist/mcp.js

@@ -13,6 +13,7 @@ exports.parseClaudeCodeMcpTool = parseClaudeCodeMcpTool;
 exports.parseGeminiMcpTool = parseGeminiMcpTool;
 exports.parseMcpToolGeneric = parseMcpToolGeneric;
 exports.checkMcpPermission = checkMcpPermission;
+const read_credential_js_1 = require("./read-credential.js");
 // ─── Parsers ───────────────────────────────────────────────────────
 /**
  * Parse a Claude Code MCP tool name of the form `mcp__<server>__<tool>`.
@@ -80,20 +81,24 @@ async function checkMcpPermission(client, mcpTool, options) {
         (process.env.ORY_MCP_TOOL_NAMESPACE ?? "mcp_tools");
     const checkToolLevel = options.checkToolLevel ??
         process.env.ORY_MCP_TOOL_LEVEL_CHECKS === "true";
+    // MCP tool calls arrive on the same subprocess lifecycle events as any other
+    // tool, so this read needs a credential resolved for exactly the reasons
+    // `gateToolCall` does (#242).
+    await (0, read_credential_js_1.ensureReadCredential)(client);
     const serverCheck = {
         namespace: serverNamespace,
         object: mcpTool.serverName,
-        relation: "use",
+        relation: "users",
         ...options.subject,
     };
-    const spanAttributes = {
+    const activityAttributes = {
         mcpServer: mcpTool.serverName,
         ...(mcpTool.toolName ? { mcpTool: mcpTool.toolName } : {}),
-        ...options.spanAttributes,
+        ...options.activityAttributes,
     };
     if (!checkToolLevel || !mcpTool.toolName) {
         // Server-only check
-        const result = await client.checkPermission(serverCheck, { spanAttributes });
+        const result = await client.checkPermission(serverCheck, { activityAttributes });
         return {
             serverAllowed: result.allowed,
             toolAllowed: true,
@@ -109,7 +114,7 @@ async function checkMcpPermission(client, mcpTool, options) {
         relation: "invoke",
         ...options.subject,
     };
-    const batchResult = await client.batchCheckPermissions([serverCheck, toolCheck], { spanAttributes });
+    const batchResult = await client.batchCheckPermissions([serverCheck, toolCheck], { activityAttributes });
     const serverAllowed = batchResult.results[0]?.allowed ?? false;
     const toolAllowed = batchResult.results[1]?.allowed ?? false;
     return {

package/dist/mirror-bootstrap.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The bootstrap committed to the public install-surface mirrors.
+ *
+ * Three harnesses install from a git repo rather than from npm — Claude Code
+ * (plugin marketplace), Gemini CLI (`gemini extensions install <url>`) and
+ * Codex (`codex plugin marketplace add <url>`) — so those repos carry a
+ * checked-in `hooks.json` / manifest. A machine-specific shim path cannot go
+ * into a file a teammate will clone, and an `npx` command must not go back onto
+ * the tool-call path, so those surfaces instead reference a **bootstrap** that
+ * ships inside the plugin tree, addressed through the harness's own path
+ * variable (verified per harness — see `docs/distribution.md`).
+ *
+ * The bootstrap is deliberately **dependency-free**: the mirror repos have no
+ * `node_modules`, so it uses `node:` builtins only. It does three things:
+ *
+ *   1. Read the runtime manifest this machine's `install` wrote and `require`
+ *      the wired entry. That is the steady state, and it costs one file read.
+ *   2. On a **session-start** event with nothing wired, complete the install
+ *      once by shelling out to `npx <package> install`. This is what keeps
+ *      `claude plugin install …` a working one-liner: the marketplace install
+ *      is the install, and the runtime it needs is materialized on first use —
+ *      never per hook invocation.
+ *   3. Fail **open** in every other unresolved case: print what to run, emit
+ *      the harness's pass-through response, exit 0. A tool-call event never
+ *      triggers a materialize, because a `PreToolUse` hook has seconds to
+ *      answer and a harness that treats an unanswered gate as a block would
+ *      otherwise block the tool while npm ran.
+ */
+/** Which entry point the generated bootstrap loads. */
+export type MirrorBootstrapKind = "hook" | "mcp";
+export interface MirrorBootstrapOptions {
+    /** Harness slug, e.g. `claude-code` — the manifest key to look up. */
+    harness: string;
+    /** npm package the install command names, e.g. `@ory/claude-code`. */
+    packageName: string;
+    /** CLI bin the install command runs, e.g. `ory-claude`. */
+    binName: string;
+    /** Harness pass-through payload for the runtime-missing case. */
+    fallbackStdout?: string;
+    /**
+     * Event names (as they appear in the hook payload) that may trigger the
+     * one-time materialize. Defaults to the session-start spellings the
+     * harnesses use.
+     */
+    sessionStartEvents?: readonly string[];
+}
+/** Render the bootstrap script for one entry kind. */
+export declare function renderMirrorBootstrap(kind: MirrorBootstrapKind, opts: MirrorBootstrapOptions): string;