@ory/argus 0.14.0 → 1.0.0

package/dist/permission-mode.js

@@ -0,0 +1,307 @@
+"use strict";
+/**
+ * Server-read permission mode.
+ *
+ * `observe` vs `enforce` is no longer a local, per-machine setting — it is a
+ * **permission the plugin reads from Keto** before gating a tool call, so an
+ * admin controls the deny posture centrally from the Ory project (Ory Console /
+ * Agent Security), and every session inherits it. There is no local override
+ * and no `ORY_PERMISSION_MODE` env var.
+ *
+ * The mode lives in its own `PermissionMode` namespace — it is not a tool, so it
+ * is not a tool object (see the naming-conventions note in `opl.ts`). It is
+ * resolved by `checkPermission` against the `mode` anchor, at two scopes:
+ *
+ *     project:       PermissionMode:mode#enforcedSubjects@(PermissionMode:project#enforcedSubjects)
+ *     applicable:    PermissionMode:mode#enforcedSubjects@<identity|agent|subagent>
+ *       allowed ⇒ enforce      denied ⇒ observe
+ *
+ * The **project** grant is checked first and is the posture an admin normally
+ * sets: one tuple governs every principal, including ones that do not exist
+ * yet. That matters because a per-principal grant cannot cover a future
+ * principal — before the project scope existed, an agent connecting after an
+ * admin turned on enforce resolved `observe` and silently escaped enforcement
+ * until someone re-applied the grant for it. A **per-principal** grant remains
+ * meaningful as an exception: enforce one identity, agent harness, or sub-agent
+ * type while the project still observes. Type grants are inherited through the
+ * server-managed AgentType/SubAgentType membership relations.
+ * Neither scope can be set by the runtime — the plugin only ever reads, riding
+ * its own OAuth2 access token like every other Keto read.
+ *
+ * Resolution precedence, applied by {@link resolvePermissionMode}:
+ *
+ *   1. **In-memory TTL cache** (per scope) — avoids a Keto round-trip on
+ *      literally every tool call while still re-reading the server every `ttlMs()`.
+ *      The project scope caches under one key shared by every subject, so the
+ *      common "whole project enforced" case costs a single read per TTL window.
+ *   2. **Server check** — project scope, then identity and acting machine scopes
+ *      only if the project is not enforcing. On a clean result, refresh the in-memory cache
+ *      and return it (`source: "server"`).
+ *   3. **Persistent cache** — when the server is unreachable, fall back to the
+ *      last value read from the server, persisted in `config.json`
+ *      (`source: "cache"`).
+ *   4. **`observe`** — nothing was ever cached (`source: "default"`).
+ *
+ * The persistent cache is written by {@link warmPermissionModeCache} at session
+ * start and when a gate first discovers a new acting-machine scope. It only
+ * writes when a cached mode changes, so normal per-tool checks do not churn the
+ * shared config while child-only posture still survives subprocess boundaries.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resetPermissionModeCache = resetPermissionModeCache;
+exports.resolvePermissionMode = resolvePermissionMode;
+exports.warmPermissionModeCache = warmPermissionModeCache;
+const config_js_1 = require("./config.js");
+const read_credential_js_1 = require("./read-credential.js");
+const opl_js_1 = require("./opl.js");
+/**
+ * Default in-memory cache TTL (ms). Small enough that an admin's mode change is
+ * picked up within a session without a restart, large enough that a burst of
+ * tool calls doesn't issue a Keto read each. Override with
+ * `ORY_PERMISSION_MODE_TTL_MS`.
+ */
+const DEFAULT_TTL_MS = 30_000;
+function ttlMs() {
+    const raw = process.env.ORY_PERMISSION_MODE_TTL_MS;
+    if (!raw)
+        return DEFAULT_TTL_MS;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_TTL_MS;
+    return n;
+}
+/**
+ * The posture is read from the fixed `PermissionMode` namespace, **not** the tool
+ * namespace: `ORY_PERMISSION_NAMESPACE` names where an operator's *tool* objects
+ * live, and the deny posture is a property of the project rather than of any one
+ * tool namespace. Keeping it fixed also means the two tool namespaces
+ * (`AgentTool`, `ShellTool`) can never disagree about the posture.
+ */
+function resolveNamespace() {
+    return opl_js_1.PERMISSION_MODE_NAMESPACE;
+}
+/**
+ * In-memory cache, keyed **by client** (so it is scoped to one session's
+ * lifecycle) and then by subject. A `WeakMap` means a discarded client's cache
+ * is collected with it — and, crucially, that each test's fresh client starts
+ * with an empty cache, so no stale mode bleeds across tests.
+ */
+let clientMemo = new WeakMap();
+function memoFor(client) {
+    let m = clientMemo.get(client);
+    if (!m) {
+        m = new Map();
+        clientMemo.set(client, m);
+    }
+    return m;
+}
+function subjectKey(subject) {
+    if (subject.subjectId)
+        return `id:${subject.subjectId}`;
+    const s = subject.subjectSet;
+    if (s)
+        return `set:${s.namespace}:${s.object}#${s.relation}`;
+    return "anon";
+}
+/**
+ * Cache key for the project-scope read. Distinct from every {@link subjectKey}
+ * (which is always `id:`/`set:`/`anon`-prefixed) and shared by all subjects, so
+ * one read per TTL window covers the whole session.
+ */
+const PROJECT_SCOPE_KEY = "project";
+/** The sentinel subject a project-wide posture grant is written to. */
+function projectPostureSubject(namespace) {
+    return {
+        subjectSet: {
+            namespace,
+            object: opl_js_1.PROJECT_POSTURE_OBJECT,
+            relation: opl_js_1.RELATION_ENFORCED_SUBJECTS,
+        },
+    };
+}
+/** Drop all in-memory caches. Test-only (reassigns the WeakMap). */
+function resetPermissionModeCache() {
+    clientMemo = new WeakMap();
+}
+/**
+ * Resolve the current permission mode for `subject`. Never throws — a Keto
+ * error falls back to the persistent cache, then `observe`. See the module
+ * doc for the precedence. Does **not** persist (that is
+ * {@link warmPermissionModeCache}'s job); `opts.now` is injectable for tests.
+ */
+async function resolvePermissionMode(client, subject, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const projectUrl = (0, config_js_1.resolveConfig)().projectUrl;
+    const namespace = resolveNamespace();
+    const key = subjectKey(subject);
+    const subjects = [
+        { subject, scope: "principal", key },
+        ...(opts.additionalSubjects ?? []).map((item) => ({
+            ...item,
+            key: subjectKey(item.subject),
+        })),
+    ].filter((item, index, all) => all.findIndex((candidate) => candidate.key === item.key) === index);
+    const memo = memoFor(client);
+    const fresh = (cacheKey) => {
+        const entry = memo.get(cacheKey);
+        if (entry && now - entry.fetchedAt < ttlMs())
+            return entry;
+        memo.delete(cacheKey);
+        return undefined;
+    };
+    // An enforcing project settles the mode for every subject, so a fresh project
+    // hit short-circuits before the subject is even considered.
+    const cachedProject = fresh(PROJECT_SCOPE_KEY);
+    if (cachedProject?.mode === "enforce") {
+        return { mode: "enforce", source: cachedProject.source };
+    }
+    const cachedSubjects = subjects.map((item) => fresh(item.key));
+    if (cachedProject && cachedSubjects.every(Boolean)) {
+        const enforcing = cachedSubjects.find((entry) => entry?.mode === "enforce");
+        return { mode: enforcing?.mode ?? "observe", source: enforcing?.source ?? cachedProject.source };
+    }
+    // The mode is read from the project, so it needs the same authenticated Keto
+    // read a tool check does. Without this a subprocess event past the user
+    // token's hour read nothing and fell back to the `observe` default — silently
+    // un-enforcing an `enforce` project (#242). After the short-circuits above, so
+    // a cache hit costs nothing.
+    await (0, read_credential_js_1.ensureReadCredential)(client);
+    const check = async (scope, modeSubject, cacheKey) => {
+        const result = await client.checkPermission({
+            namespace,
+            object: opl_js_1.PERMISSION_MODE_OBJECT,
+            relation: opl_js_1.RELATION_ENFORCED_SUBJECTS,
+            ...modeSubject,
+        }, {
+            // This is a mode *read*, not a gate: a `false` result selects `observe`,
+            // it is not a tool denial. Mark it informational so the event ends `ok`
+            // and carry a note explaining the boolean, so live debug output is
+            // self-explanatory rather than looking like a blocked tool.
+            informational: true,
+            activityAttributes: {
+                source: "permission_mode",
+                scope,
+                note: "mode read — allowed=true ⇒ enforce, allowed=false ⇒ observe",
+            },
+        });
+        const mode = result.allowed ? "enforce" : "observe";
+        memo.set(cacheKey, { mode, source: "server", fetchedAt: now });
+        return mode;
+    };
+    try {
+        const projectMode = cachedProject?.mode
+            ?? (await check("project", projectPostureSubject(namespace), PROJECT_SCOPE_KEY));
+        let scope = "project";
+        let mode = projectMode;
+        if (projectMode !== "enforce") {
+            mode = "observe";
+            for (const [index, item] of subjects.entries()) {
+                const subjectMode = cachedSubjects[index]?.mode ?? (await check(item.scope, item.subject, item.key));
+                if (subjectMode === "enforce") {
+                    mode = subjectMode;
+                    scope = item.scope;
+                    break;
+                }
+            }
+            if (mode === "observe")
+                scope = "principal";
+        }
+        client.logger.activity("permission.mode_resolve", "ok", {
+            attributes: {
+                permissionMode: mode,
+                enforceGranted: mode === "enforce",
+                scope,
+                source: "server",
+            },
+        });
+        return { mode, source: "server" };
+    }
+    catch (err) {
+        const oryErr = err;
+        const cache = (0, config_js_1.resolveConfig)().permissionModeCache;
+        const scoped = cache && cache.projectUrl === projectUrl ? cache.scopes : undefined;
+        const project = scoped?.[PROJECT_SCOPE_KEY];
+        const subjectEntries = subjects.map((item) => scoped?.[item.key]);
+        const scopedMode = project?.mode === "enforce" || subjectEntries.some((entry) => entry?.mode === "enforce")
+            ? "enforce"
+            : project && subjectEntries.every(Boolean)
+                ? "observe"
+                : undefined;
+        // A legacy scalar enforce value is a conservative fallback for every scope.
+        // A scalar observe value is not: it may have been written for a different
+        // identity or harness and must not silently relax that scope.
+        const legacyMode = cache && !cache.scopes && (!cache.projectUrl || cache.projectUrl === projectUrl)
+            ? cache.mode
+            : undefined;
+        const cachedMode = scopedMode ?? (legacyMode === "enforce" ? "enforce" : undefined);
+        if (cachedMode) {
+            client.logger.debug("permission.mode_cache", {
+                code: oryErr?.code,
+                note: "mode check failed; using last cached server value",
+                mode: cachedMode,
+            });
+            return { mode: cachedMode, source: "cache" };
+        }
+        client.logger.debug("permission.mode_default", {
+            code: oryErr?.code,
+            note: "mode check failed and no cached value; defaulting to observe",
+        });
+        return { mode: "observe", source: "default" };
+    }
+}
+/**
+ * Resolve the mode and, when it came from a live server read, persist it to
+ * `config.json` so a subprocess harness's later hook processes (and the
+ * synchronous MCP `applyPermissionMode` path) see the current posture, and so a
+ * subsequent offline session has a cached value to fall back to. Called once at
+ * session start. Best-effort; never throws. Only writes when the value changed,
+ * so it doesn't churn the config lockfile.
+ */
+async function warmPermissionModeCache(client, subject, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const projectUrl = (0, config_js_1.resolveConfig)().projectUrl;
+    const resolved = await resolvePermissionMode(client, subject, {
+        now,
+        additionalSubjects: opts.additionalSubjects,
+    });
+    if (resolved.source === "server") {
+        const requestedKeys = [PROJECT_SCOPE_KEY, subjectKey(subject), ...(opts.additionalSubjects ?? []).map((item) => subjectKey(item.subject))];
+        const updates = {};
+        for (const key of new Set(requestedKeys)) {
+            const entry = memoFor(client).get(key);
+            if (entry?.source === "server")
+                updates[key] = { mode: entry.mode, fetchedAt: entry.fetchedAt };
+        }
+        try {
+            (0, config_js_1.mutateConfig)((config) => {
+                const current = config.permissionModeCache;
+                const scopes = { ...(current && current.projectUrl === projectUrl ? current.scopes ?? {} : {}) };
+                const projectMode = updates[PROJECT_SCOPE_KEY]?.mode
+                    ?? scopes[PROJECT_SCOPE_KEY]?.mode
+                    ?? "observe";
+                let changed = current?.mode !== projectMode || current?.projectUrl !== projectUrl;
+                for (const [key, entry] of Object.entries(updates)) {
+                    const refreshed = { mode: entry.mode, fetchedAt: now };
+                    if (scopes[key]?.mode === refreshed.mode && scopes[key]?.fetchedAt === refreshed.fetchedAt)
+                        continue;
+                    scopes[key] = refreshed;
+                    changed = true;
+                }
+                if (!changed)
+                    return undefined;
+                const boundedScopes = Object.fromEntries(Object.entries(scopes)
+                    .sort(([, left], [, right]) => right.fetchedAt - left.fetchedAt)
+                    .slice(0, 256));
+                return {
+                    ...config,
+                    permissionModeCache: { mode: projectMode, fetchedAt: now, projectUrl, scopes: boundedScopes },
+                };
+            });
+        }
+        catch {
+            // Best-effort — a write failure just means the next process re-reads
+            // from the server (or starts at observe until it can).
+        }
+    }
+    return resolved;
+}

package/dist/permissions-cli.d.ts

@@ -1,24 +1,20 @@
 /**
  * Shared `permissions` CLI implementation. Each harness's `cli/main.ts`
- * delegates to {@link runPermissionsCommand}, passing the harness's name
- * so subcommands can scope to that harness's tool catalog.
+ * delegates to {@link runPermissionsCommand}, passing the harness's name so the
+ * report can scope to that harness's tool catalog.
  *
- * Subcommands:
+ * `permissions` takes **no subcommand** — it is a single read-only report: the
+ * live permission mode (read from the Ory project), the subject being checked,
+ * and the allow / deny / blocked breakdown across the harness's known tool
+ * catalog. (`permissions status` is still accepted; it was the name through
+ * v0.14, and the report is the same.)
  *
- *   - `status`   — Print the configured {@link PermissionMode} and, when
- *                  the client can reach Ory, the allow/deny breakdown
- *                  across the harness's known tool catalog.
- *   - `bootstrap` — Idempotently write `<namespace>:<tool>#use@<userSubject>`
- *                  tuples for every tool in the harness's catalog. Run
- *                  automatically by `install` when a user identity is
- *                  cached; can be re-run by hand any time.
- *   - `observe`  — Persist `permissionMode = "observe"` in the shared
- *                  config (denies log but don't block).
- *   - `enforce`  — Persist `permissionMode = "enforce"` in the shared
- *                  config (denies block — the production posture).
- *
- * All four are non-destructive on existing config and idempotent on
- * Keto: re-running them is always safe.
+ * Everything that *writes* to the project is provisioned in the **Ory Console**
+ * (Agent Security), not from the plugin: the permission model, the per-tool
+ * grants, explicit blocks, and the observe/enforce posture. That is what lets a
+ * plugin be installed with nothing but a project URL — the public OAuth2 client
+ * id has a reserved default, with no workspace privilege, project API key, or admin write path. The
+ * plugin is a read-only client of the project's permission state.
  */
 /**
  * Entry point invoked by each harness CLI's `permissions` case.
@@ -28,35 +24,3 @@
  * exit so the parent CLI doesn't need a try/catch.
  */
 export declare function runPermissionsCommand(binName: string, harness: string, args: string[]): Promise<number>;
-/**
- * Whether a user identity is cached locally — used by `install` to
- * decide whether to opportunistically bootstrap tuples without
- * prompting. Returns true when persisted tokens exist and are not
- * expired, or when ORY_USER_SUBJECT_ID is set explicitly.
- */
-export declare function isUserIdentityCached(): boolean;
-/**
- * Print the "permission mode" section of the install banner.
- *
- * Tells the user what observe vs enforce mean, and prints the two
- * follow-up commands they'll typically reach for next:
- *
- *   - `<bin> permissions bootstrap` to seed tuples for the harness's
- *     built-in tools (the line is shown whether or not we just ran it
- *     ourselves, so the user can re-run after editing the catalog).
- *   - `<bin> permissions enforce` once they're satisfied with the
- *     observe-mode trace output and want denies to actually block.
- */
-export declare function printPermissionsOnboardingHelp(binName: string, harness: string, opts?: {
-    bootstrappedAutomatically?: boolean;
-}): void;
-/**
- * If a user identity is already cached and the plugin is configured,
- * opportunistically run `permissions bootstrap` so the user lands in a
- * "tools work out of the box" state. Otherwise a no-op (the install
- * banner still prints the manual command).
- *
- * Always best-effort: any failure is logged and swallowed so install
- * never aborts because of a permissions write problem.
- */
-export declare function maybeAutoBootstrap(binName: string, harness: string): Promise<boolean>;