@ory/argus 0.14.0 → 1.0.0

package/dist/opl.js

@@ -0,0 +1,446 @@
+"use strict";
+/**
+ * Ory Permission Language (OPL) schema for the Agent Security permission model.
+ *
+ * Argus relies on more than relation-tuple *existence*: a subject may be granted
+ * a tool and separately **blocked** from it, and the block must win. Keto
+ * permission is otherwise purely existence-based (no path ⇒ no access, any path
+ * ⇒ access), so the deny-override is modeled natively in OPL as a permit:
+ *
+ *     use = users.includes(subject) && !blockedSubjects.includes(subject)
+ *
+ * Keto evaluates the permit in a single check, so a `blockedSubjects` relation
+ * beats a `users` grant no matter how the grant was reached (direct subject or
+ * subject-set expansion). Argus always checks the **`use` permit** (see
+ * `resolveCheckRelation`), so this model must be applied to the project for
+ * checks to resolve; with nothing blocked, `use` resolves identically to a bare
+ * `users` existence check, so grants alone allow.
+ *
+ * ## Naming conventions
+ *
+ * Every name here follows Ory Permissions' documented conventions
+ * (https://www.ory.com/docs/keto/concepts/namespaces#naming-conventions):
+ *
+ * - **Namespaces** are TypeScript classes named after the **singular** form of
+ *   the type they describe, in UpperCamelCase — `AgentTool`, `ShellTool`,
+ *   `Delegation`, `PermissionMode`, `User`, `Agent`, `SubAgent`, `Session`.
+ * - **Relations** are **plural** nouns naming the set of subjects on the far end
+ *   of the edge, so each reads as an English sentence — `User:bob is in users of
+ *   AgentTool:Bash`, `Agent:abc is in credentials of Delegation:agent:<join>`.
+ * - **Permits** are verbs, like Keto's own `view` — hence `use` for "may this
+ *   subject use this tool", which is the question the gate actually asks.
+ * - A namespace holds a **homogeneous** type of object. That is why delegation
+ *   nodes and the posture sentinels are *not* tool objects: `AgentTool` holds
+ *   only tools, `Delegation` only delegation nodes, `PermissionMode` only the
+ *   posture anchors. A single namespace holding all three is the case the
+ *   convention doc calls out as incorrect, and it forced one class to carry a
+ *   grab bag of unrelated relations.
+ *
+ * A relation and a permit cannot share a name in OPL — which is exactly why the
+ * grant relation is the plural `users` and the permit the singular verb `use`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NODE_REFERENCE_NAMESPACES = exports.PRINCIPAL_NAMESPACES = exports.OPL_IMPORT_SYMBOLS = exports.OPL_IMPORT_MODULE = exports.PERMIT_USE = exports.PROJECT_POSTURE_OBJECT = exports.PERMISSION_MODE_OBJECT = exports.PERMISSION_MODE_NAMESPACE = exports.RELATION_OPTED_OUT_SUBJECTS = exports.AUTO_ENROLL_OBJECT = exports.ENROLLMENT_NAMESPACE = exports.RELATION_MEMBERS = exports.SUBAGENT_TYPE_NAMESPACE = exports.AGENT_TYPE_NAMESPACE = exports.AGENT_ROLE_NAMESPACE = exports.SUBAGENT_NODE_NAMESPACE = exports.AGENT_NODE_NAMESPACE = exports.DELEGATION_NAMESPACE = exports.DEFAULT_SHELL_NAMESPACE = exports.DEFAULT_NAMESPACE = exports.RELATION_ENFORCED_SUBJECTS = exports.RELATION_CREDENTIALS = exports.RELATION_BLOCKED_SUBJECTS = exports.RELATION_DELEGATES = exports.RELATION_USERS = void 0;
+exports.renderOplImport = renderOplImport;
+exports.renderPrincipalClass = renderPrincipalClass;
+exports.renderToolNamespaceClass = renderToolNamespaceClass;
+exports.renderDelegationNamespaceClass = renderDelegationNamespaceClass;
+exports.renderAgentRoleNamespaceClass = renderAgentRoleNamespaceClass;
+exports.renderAgentTypeNamespaceClass = renderAgentTypeNamespaceClass;
+exports.renderEnrollmentNamespaceClass = renderEnrollmentNamespaceClass;
+exports.renderPermissionModeNamespaceClass = renderPermissionModeNamespaceClass;
+exports.buildAgentSecurityOpl = buildAgentSecurityOpl;
+const subject_js_1 = require("./subject.js");
+/**
+ * The relation that grants a subject use of a tool object — the set of subjects
+ * that may use it. Written in the Ory Console (Agent Security); the plugin only
+ * ever reads it. Reads as `User:bob is in users of AgentTool:Bash`.
+ */
+exports.RELATION_USERS = "users";
+/**
+ * The relation that records a delegation edge on a {@link DELEGATION_NAMESPACE}
+ * node (`user→agent`, `agent→subagent`) — the set of subjects that delegated to
+ * it. Written by the agent-security broker, never by the runtime; declared here
+ * so the local Keto mount (which loads this OPL) accepts the tuples.
+ */
+exports.RELATION_DELEGATES = "delegates";
+/**
+ * The relation that explicitly blocks subjects from a tool object
+ * (deny-override). A participle has no natural plural, so the relation names the
+ * set it holds: `User:bob is in blockedSubjects of AgentTool:curl`.
+ */
+exports.RELATION_BLOCKED_SUBJECTS = "blockedSubjects";
+/**
+ * The relation recording which OAuth2 clients a delegation node ran as:
+ * `Delegation:agent:<join>#credentials@(Agent:<clientId>)`. Written by the
+ * broker, never by the runtime, and never checked — a delegation node is keyed
+ * on (identity, harness, host) so that it survives credential rotation, which
+ * means the node alone cannot say which credential acted and two clients for one
+ * triple collapse onto it. This edge carries that missing axis, for audit and so
+ * a reader can join a node to its client exactly rather than by inference.
+ */
+exports.RELATION_CREDENTIALS = "credentials";
+/**
+ * The relation holding the subjects that are in **enforce** mode. Read (never
+ * written by the runtime) via a `checkPermission` on the
+ * {@link PERMISSION_MODE_OBJECT} anchor: an admin grants
+ * `PermissionMode:mode#enforcedSubjects@<subject>` (directly, or to a
+ * subject-set / group for a project-wide flip) to promote that principal from
+ * the default `observe` posture to `enforce`. Absence ⇒ `observe`. Named for the
+ * set it holds, since `enforce` is a verb and has no plural noun form.
+ */
+exports.RELATION_ENFORCED_SUBJECTS = "enforcedSubjects";
+/**
+ * Default permission namespace / OPL class name for harness tool objects
+ * (`AgentTool:Bash`). Singular, because the namespace describes *one tool*, and
+ * an object in it is one. Mirrors `ORY_PERMISSION_NAMESPACE`.
+ */
+exports.DEFAULT_NAMESPACE = "AgentTool";
+/**
+ * Default Keto namespace for decomposed shell-command sub-tools (issue #76) —
+ * one object per program/builtin word (`ShellTool:curl`). Rendered with the same
+ * grant/block model as {@link DEFAULT_NAMESPACE}, so an explicit
+ * `ShellTool:curl#blockedSubjects` overrides a `users` grant. Mirrors
+ * `resolveShellCommandNamespace()` in tool-catalog.ts.
+ */
+exports.DEFAULT_SHELL_NAMESPACE = "ShellTool";
+/**
+ * Namespace for delegation nodes — the current-state graph of who delegated to
+ * whom (`Delegation:agent:<join>`, `Delegation:subagent:<join>|<type>`). Its own
+ * namespace because a delegation node is not a tool: mixing the two put
+ * heterogeneous objects in one namespace and made the tool class carry
+ * delegation relations that no tool object ever uses. The broker owns both the
+ * objects and the tuples; the plugin treats a node id as opaque.
+ */
+exports.DELEGATION_NAMESPACE = "Delegation";
+/**
+ * Namespaces for **references to** delegation nodes — the parent pointer on a
+ * delegation edge (issue #225).
+ *
+ * `Agent` and `SubAgent` name a *principal identity*: an OAuth2 client that
+ * authenticates, and the subject an admin grants or blocks. A delegation edge's
+ * `delegates` subject is a different kind of thing — a pointer at another node
+ * in the graph, keyed by `<identity>|<harness>|<host>|<session>`. Both were
+ * addressed under `Agent` / `SubAgent`, so one namespace carried two meanings:
+ *
+ *     Agent:<clientId>                              a principal identity
+ *     Agent:<identity>|<harness>|<host>|<session>   a graph-node reference
+ *
+ * Nothing written today is ambiguous, because a Hydra client id is a UUID and a
+ * join key always contains separators — but that disjointness is a property of
+ * the *data*, not of the model, and it is reachable-breakable through
+ * `ORY_AGENT_SUBJECT_ID` (guarded separately in #241). The costlier problem is
+ * silent: an admin, or a Console UI, that reads a node id off the delegation
+ * graph and writes it as a grant subject produces a tuple that is accepted,
+ * stored, and never matches any check — the same failure the SubjectSet-vs-
+ * SubjectID invariant exists to prevent, one level up. That surface is four
+ * relations wide (`users`, `blockedSubjects`, `members`, `enforcedSubjects`).
+ *
+ * Splitting the two meanings apart makes the wrong-form grant name a namespace
+ * that has no `users` relation at all, rather than looking plausible. It also
+ * lets the broker's downward walk use the right namespace per level instead of
+ * guessing `Agent` for every level — the latent inconsistency that would become
+ * a real bug the moment nested sub-agents ship.
+ */
+exports.AGENT_NODE_NAMESPACE = "AgentNode";
+/** Sub-agent counterpart of {@link AGENT_NODE_NAMESPACE}. */
+exports.SUBAGENT_NODE_NAMESPACE = "SubAgentNode";
+/**
+ * Namespace for the shared role a project grants tools to, rather than granting
+ * every identity directly (`AgentRole:agent-security-users#members@(User:<id>)`,
+ * with each tool granted to `(AgentRole:agent-security-users#members)`). Written
+ * by the Ory Console and the Agent Security broker's enrollment; the plugin only
+ * ever resolves it as part of the `use` permit.
+ *
+ * Its own namespace because a role is not a tool. That is also what makes **one**
+ * role tuple enough: while the role was a tool object, a membership had to be
+ * written once per tool namespace (Keto matches a subject-set exactly, and the
+ * role object's namespace had to be the same as the granting object's), so the
+ * same role existed twice and could drift.
+ */
+exports.AGENT_ROLE_NAMESPACE = "AgentRole";
+/** Group of registered agent credentials sharing a harness key. */
+exports.AGENT_TYPE_NAMESPACE = "AgentType";
+/** Group of registered sub-agent credentials sharing a type name. */
+exports.SUBAGENT_TYPE_NAMESPACE = "SubAgentType";
+/** The relation naming a role's members. Reads as `User:bob is in members of AgentRole:<role>`. */
+exports.RELATION_MEMBERS = "members";
+/**
+ * Namespace for Agent Security enrollment settings — currently whether a newly
+ * connected agent's identity is auto-enrolled into the shared role. Stored as an
+ * **opt-out** (`Enrollment:autoEnroll#optedOutSubjects@(Enrollment:project#optedOutSubjects)`)
+ * so absence means on, which is what a project provisioned before the setting
+ * existed reads as. Written and read by the Console and the broker.
+ */
+exports.ENROLLMENT_NAMESPACE = "Enrollment";
+/** The object the auto-enroll setting hangs off. */
+exports.AUTO_ENROLL_OBJECT = "autoEnroll";
+/** The relation holding the subjects that opted out of a setting. */
+exports.RELATION_OPTED_OUT_SUBJECTS = "optedOutSubjects";
+/**
+ * Namespace for the server-read deny posture. Its own namespace for the same
+ * reason as {@link DELEGATION_NAMESPACE}: the posture anchor is not a tool, and
+ * once it stops sharing a namespace with tool names it no longer needs a
+ * collision-proof sentinel spelling either — hence the plain
+ * {@link PERMISSION_MODE_OBJECT} / {@link PROJECT_POSTURE_OBJECT} object ids
+ * rather than the double-underscore guards an earlier release used.
+ */
+exports.PERMISSION_MODE_NAMESPACE = "PermissionMode";
+/**
+ * The object an enforce-mode grant hangs off. The permission mode is resolved as
+ * `checkPermission(PermissionMode:mode#enforcedSubjects@<subject>)`.
+ */
+exports.PERMISSION_MODE_OBJECT = "mode";
+/**
+ * Object standing in for **every principal on the project**, used as the subject
+ * of a project-wide posture grant:
+ *
+ *     PermissionMode:mode#enforcedSubjects@(PermissionMode:project#enforcedSubjects)
+ *
+ * Keto has no wildcard subject, and a per-principal grant cannot cover a
+ * principal that does not exist yet — so an agent connecting after an admin
+ * turned on enforce would resolve `observe` and silently escape enforcement
+ * until someone re-applied the grant for it. Checking this fixed sentinel first
+ * makes the posture a property of the project: one relation governs every
+ * principal, present and future. Per-principal grants remain meaningful as
+ * exceptions (enforce one user while the project is still observing).
+ */
+exports.PROJECT_POSTURE_OBJECT = "project";
+/**
+ * The permit Argus checks: `users && !blockedSubjects`, evaluated natively by
+ * Keto. A verb, as Keto's own `view` is — it names the question the gate asks.
+ */
+exports.PERMIT_USE = "use";
+/** Conventional user namespace used for SubjectSet-addressed users (`User:<id>`). */
+const USER_NAMESPACE = "User";
+/**
+ * The module OPL sources import their type symbols from. Keto's parser
+ * recognizes this name (and the equivalent `@ory/permission-namespace-types`)
+ * and strips the import — no npm dependency is pulled at runtime.
+ */
+exports.OPL_IMPORT_MODULE = "@ory/keto-namespace-types";
+/**
+ * Every type symbol the rendered OPL references, and therefore must import:
+ * `Namespace` (every class implements it), `SubjectSet` (the relation unions
+ * allow set expansion), and `Context` (the `use` permit is typed
+ * `(ctx: Context)`). This is the canonical set — any code that assembles or
+ * merges the OPL imports exactly these.
+ */
+exports.OPL_IMPORT_SYMBOLS = ["Namespace", "SubjectSet", "Context"];
+/**
+ * The principal namespaces every subject is addressed under (SubjectSets):
+ * `User`, `Agent`, `SubAgent`, and the `Session` fallback. The object
+ * namespaces' relations are typed by them, so they must be defined for checks to
+ * resolve rather than `NotFound`.
+ *
+ * These are **identities** — things that authenticate and that an admin can
+ * grant or block. Graph-node references are a separate kind and live in
+ * {@link NODE_REFERENCE_NAMESPACES}; keeping the two lists apart is what stops a
+ * node id from being written where an identity belongs (#225).
+ */
+exports.PRINCIPAL_NAMESPACES = [
+    USER_NAMESPACE,
+    subject_js_1.AGENT_NAMESPACE,
+    subject_js_1.SUBAGENT_NAMESPACE,
+    subject_js_1.SESSION_NAMESPACE,
+];
+/**
+ * Namespaces holding references to delegation-graph nodes. Declared so the
+ * `delegates` relation that is typed by them resolves, and deliberately *not*
+ * part of {@link PRINCIPAL_NAMESPACES}: a node reference is never a grant, block,
+ * role-membership, or posture subject.
+ */
+exports.NODE_REFERENCE_NAMESPACES = [
+    exports.AGENT_NODE_NAMESPACE,
+    exports.SUBAGENT_NODE_NAMESPACE,
+];
+/** Render the canonical import line for a from-scratch OPL file. */
+function renderOplImport() {
+    return `import { ${exports.OPL_IMPORT_SYMBOLS.join(", ")} } from "${exports.OPL_IMPORT_MODULE}"`;
+}
+/** Render a principal-namespace class (an empty `implements Namespace`). */
+function renderPrincipalClass(name) {
+    return `class ${name} implements Namespace {}`;
+}
+/**
+ * Render a tool-namespace class body: the `users` grant, the `blockedSubjects`
+ * deny-override, and the `use` permit (`users && !blockedSubjects`) Argus
+ * checks. The single definition of that class, used for both tool namespaces.
+ */
+function renderToolNamespaceClass(namespace = exports.DEFAULT_NAMESPACE) {
+    return `class ${namespace} implements Namespace {
+  related: {
+    // Machine principals are grantable in their own right: \`${subject_js_1.AGENT_NAMESPACE}:<clientId>\` is
+    // one session's registered agent credential and \`${subject_js_1.SUBAGENT_NAMESPACE}:<clientId>\` one
+    // typed sub-agent credential in that session. Their narrower session- and spawn-scoped forms
+    // (\`${subject_js_1.AGENT_NAMESPACE}:<clientId>|<session>\`, \`${subject_js_1.SUBAGENT_NAMESPACE}:<clientId>|<session>|<type>\`) are
+    // members of the same namespaces, which is what lets a block name one run.
+    // A grant may also name the shared role, so one membership covers every
+    // tool in every tool namespace: \`@(${exports.AGENT_ROLE_NAMESPACE}:<role>#${exports.RELATION_MEMBERS})\`.
+    ${exports.RELATION_USERS}: (${USER_NAMESPACE} | ${subject_js_1.SESSION_NAMESPACE} | ${subject_js_1.AGENT_NAMESPACE} | ${subject_js_1.SUBAGENT_NAMESPACE} | SubjectSet<${exports.AGENT_ROLE_NAMESPACE}, "${exports.RELATION_MEMBERS}"> | SubjectSet<${namespace}, "${exports.RELATION_USERS}">)[]
+    ${exports.RELATION_BLOCKED_SUBJECTS}: (${USER_NAMESPACE} | ${subject_js_1.SESSION_NAMESPACE} | ${subject_js_1.AGENT_NAMESPACE} | ${subject_js_1.SUBAGENT_NAMESPACE} | SubjectSet<${exports.AGENT_ROLE_NAMESPACE}, "${exports.RELATION_MEMBERS}"> | SubjectSet<${namespace}, "${exports.RELATION_BLOCKED_SUBJECTS}">)[]
+  }
+
+  permits = {
+    // Deny-override: any matching \`${exports.RELATION_BLOCKED_SUBJECTS}\` relation beats a
+    // \`${exports.RELATION_USERS}\` grant, regardless of how the grant was reached (direct or
+    // via a set).
+    ${exports.PERMIT_USE}: (ctx: Context): boolean =>
+      this.related.${exports.RELATION_USERS}.includes(ctx.subject) &&
+      !this.related.${exports.RELATION_BLOCKED_SUBJECTS}.includes(ctx.subject),
+  }
+}`;
+}
+/**
+ * Render the delegation-node class: who delegated to this node, and which OAuth2
+ * clients it ran as. Nothing is ever checked here — the graph is an audit trail —
+ * but the relations must be declared for the broker's writes to be accepted.
+ */
+function renderDelegationNamespaceClass(namespace = exports.DELEGATION_NAMESPACE) {
+    return `class ${namespace} implements Namespace {
+  related: {
+    // A delegation edge's subject is whoever delegated. For a user that is the
+    // identity itself (${USER_NAMESPACE}:<id>); for a machine it is a *reference to the
+    // delegating node* — \`${exports.AGENT_NODE_NAMESPACE}:<identity>|<harness>|<host>|<session>\`, not the
+    // OAuth2 client id. Those are different kinds of thing and no longer share a
+    // namespace with the grant/block identities (#225), so a node id that ends up
+    // written as a grant subject is visibly the wrong kind rather than being
+    // spelled exactly like a correct one. (Keto still stores such a tuple — it
+    // does not type-check subjects on write — it just never matches anything.)
+    ${exports.RELATION_DELEGATES}: (${USER_NAMESPACE} | ${exports.AGENT_NODE_NAMESPACE} | ${exports.SUBAGENT_NODE_NAMESPACE})[]
+    // Which OAuth2 clients this node ran as. Recorded for audit, never checked —
+    // the node key survives credential rotation, so this is the only place the
+    // credential that actually acted is written down.
+    ${exports.RELATION_CREDENTIALS}: (${subject_js_1.AGENT_NAMESPACE} | ${subject_js_1.SUBAGENT_NAMESPACE})[]
+  }
+}`;
+}
+/**
+ * Render the role class: the members of a shared role a project grants tools to.
+ * One class, one relation — a role is a group of subjects and nothing else.
+ */
+function renderAgentRoleNamespaceClass(namespace = exports.AGENT_ROLE_NAMESPACE) {
+    return `class ${namespace} implements Namespace {
+  related: {
+    // The subjects that belong to the role. A tool grant names
+    // \`(${namespace}:<role>#${exports.RELATION_MEMBERS})\` as its subject, so adding a member grants
+    // every tool the role holds, in either tool namespace, from one relation.
+    ${exports.RELATION_MEMBERS}: (${USER_NAMESPACE} | ${subject_js_1.AGENT_NAMESPACE} | ${subject_js_1.SUBAGENT_NAMESPACE} | SubjectSet<${namespace}, "${exports.RELATION_MEMBERS}">)[]
+  }
+}`;
+}
+/** Render a harness/sub-agent type group whose members inherit posture. */
+function renderAgentTypeNamespaceClass(namespace, memberNamespace) {
+    return `class ${namespace} implements Namespace {
+  related: {
+    ${exports.RELATION_MEMBERS}: (${memberNamespace} | SubjectSet<${namespace}, "${exports.RELATION_MEMBERS}">)[]
+  }
+}`;
+}
+/**
+ * Render the enrollment-settings class: which subjects opted out of a setting.
+ * An opt-out rather than an opt-in, so absence reads as "on".
+ */
+function renderEnrollmentNamespaceClass(namespace = exports.ENROLLMENT_NAMESPACE) {
+    return `class ${namespace} implements Namespace {
+  related: {
+    // Auto-enrollment of a newly connected agent's identity into the shared role
+    // is on unless opted out, so the setting is stored as an opt-out on the
+    // \`${exports.AUTO_ENROLL_OBJECT}\` object. Absence means on — which is also how a project
+    // provisioned before the setting existed reads.
+    ${exports.RELATION_OPTED_OUT_SUBJECTS}: (${USER_NAMESPACE} | SubjectSet<${namespace}, "${exports.RELATION_OPTED_OUT_SUBJECTS}">)[]
+  }
+}`;
+}
+/**
+ * Render the permission-mode class: the set of subjects an admin has promoted
+ * from `observe` to `enforce`. One relation, read by every gate.
+ */
+function renderPermissionModeNamespaceClass(namespace = exports.PERMISSION_MODE_NAMESPACE) {
+    return `class ${namespace} implements Namespace {
+  related: {
+    // An admin grants \`${exports.RELATION_ENFORCED_SUBJECTS}\` on the \`${exports.PERMISSION_MODE_OBJECT}\` object to
+    // promote a subject (or a whole group, via a SubjectSet) from the default
+    // \`observe\` posture to \`enforce\`. The \`${exports.PROJECT_POSTURE_OBJECT}\` sentinel subject-set is
+    // how a posture is set for the whole project, including principals that do
+    // not exist yet. Sub-agents are promotable in their own right.
+    ${exports.RELATION_ENFORCED_SUBJECTS}: (${USER_NAMESPACE} | ${subject_js_1.SESSION_NAMESPACE} | ${subject_js_1.AGENT_NAMESPACE} | ${subject_js_1.SUBAGENT_NAMESPACE} | SubjectSet<${exports.AGENT_TYPE_NAMESPACE}, "${exports.RELATION_MEMBERS}"> | SubjectSet<${exports.SUBAGENT_TYPE_NAMESPACE}, "${exports.RELATION_MEMBERS}"> | SubjectSet<${namespace}, "${exports.RELATION_ENFORCED_SUBJECTS}">)[]
+  }
+}`;
+}
+/**
+ * Render the complete OPL namespace-definition file for the Agent Security
+ * model.
+ *
+ * This is the model an Ory project must have for Agent Security checks to
+ * resolve. On a hosted project it is applied in the Ory Console (Agent
+ * Security) — the plugin never pushes it. This renderer exists so the **local
+ * dev stack** can mount the identical definition into its own Keto config,
+ * keeping local and hosted on one definition, and so the model can be printed
+ * for reference.
+ *
+ * `namespace` is the tool namespace (OPL class name); defaults to
+ * {@link DEFAULT_NAMESPACE}. Operators who override `ORY_PERMISSION_NAMESPACE`
+ * must provision the schema under the same name so the class the checks address
+ * exists. The `Delegation` and `PermissionMode` namespaces are not
+ * operator-configurable — they hold project-wide state, not per-deployment tool
+ * objects.
+ *
+ * The output is the TypeScript-flavored OPL source Keto parses (the import is
+ * recognized and stripped by Keto's parser — no npm dependency is pulled at
+ * runtime). It is written verbatim into the local stack's keto config mount.
+ */
+function buildAgentSecurityOpl(namespace = exports.DEFAULT_NAMESPACE, shellNamespace = exports.DEFAULT_SHELL_NAMESPACE) {
+    return [
+        renderOplImport(),
+        "",
+        "// Principal namespaces. Every principal — user, agent, sub-agent, and the",
+        `// \`${subject_js_1.SESSION_NAMESPACE}:<id>\` fallback subject — is addressed as a SubjectSet`,
+        `// (\`${USER_NAMESPACE}:<id>\`, \`${subject_js_1.AGENT_NAMESPACE}:<id>\`, …). They must exist so the object`,
+        "// namespaces' relations, which are typed by them, resolve.",
+        ...exports.PRINCIPAL_NAMESPACES.map(renderPrincipalClass),
+        "",
+        "// Delegation-graph node references. Distinct from the principal namespaces",
+        "// above because a node reference is not an identity: it is a pointer at a",
+        `// node keyed \`<identity>|<harness>|<host>|<session>\`, and it is only ever the`,
+        `// subject of \`${exports.RELATION_DELEGATES}\`. Keeping it out of \`${subject_js_1.AGENT_NAMESPACE}\` / \`${subject_js_1.SUBAGENT_NAMESPACE}\` means a`,
+        "// node id written as a grant, block, role, or posture subject names a class",
+        "// that has no such relation, rather than storing a tuple that never matches.",
+        ...exports.NODE_REFERENCE_NAMESPACES.map(renderPrincipalClass),
+        "",
+        `// Harness tool objects (\`${namespace}:Bash\`). \`${exports.RELATION_USERS}\` is the set of subjects`,
+        `// granted the tool; \`${exports.RELATION_BLOCKED_SUBJECTS}\` is an explicit deny-override. The`,
+        `// \`${exports.PERMIT_USE}\` permit is the effective decision Argus checks: granted AND not`,
+        "// blocked.",
+        renderToolNamespaceClass(namespace),
+        "",
+        "// Shell command sub-tools (issue #76): each program/builtin word a shell",
+        `// command runs is checked as \`${shellNamespace}:<word>#${exports.PERMIT_USE}\`, so a blocked`,
+        '// binary (e.g. curl) can\'t be reached through `bash -c "curl …"`. Same',
+        "// grant / block / use model as the tool namespace above.",
+        renderToolNamespaceClass(shellNamespace),
+        "",
+        "// The shared role a project grants tools to, so an admin adds a member",
+        "// instead of re-granting every tool per identity.",
+        renderAgentRoleNamespaceClass(),
+        "",
+        "// Delegation nodes: the current-state graph of who delegated to whom, written",
+        "// by the agent-security broker and read by the Console. Audit only — no",
+        "// permission check resolves against it.",
+        renderDelegationNamespaceClass(),
+        "",
+        "// Registered credential groups used to apply posture by harness or sub-agent type.",
+        renderAgentTypeNamespaceClass(exports.AGENT_TYPE_NAMESPACE, subject_js_1.AGENT_NAMESPACE),
+        "",
+        renderAgentTypeNamespaceClass(exports.SUBAGENT_TYPE_NAMESPACE, subject_js_1.SUBAGENT_NAMESPACE),
+        "",
+        "// Server-read deny posture: which subjects are in `enforce` rather than the",
+        "// default `observe`. Set in the Ory Console, read by every gate.",
+        renderPermissionModeNamespaceClass(),
+        "",
+        "// Agent Security enrollment settings, stored as opt-outs so absence reads as",
+        "// the default (on). Written and read by the Console and the broker.",
+        renderEnrollmentNamespaceClass(),
+        "",
+    ].join("\n");
+}

package/dist/permission-mode.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+import type { OryAgentClient } from "./client.js";
+import { type PermissionMode } from "./config.js";
+import type { PermissionCheck } from "./types.js";
+/** Where {@link resolvePermissionMode} sourced the value it returned. */
+export type PermissionModeSource = "server" | "cache" | "default";
+/** The subject a mode check is evaluated for — the same shape as a tool check. */
+export type ModeSubject = Pick<PermissionCheck, "subjectId" | "subjectSet">;
+export interface ResolvedPermissionMode {
+    mode: PermissionMode;
+    source: PermissionModeSource;
+}
+export interface AdditionalModeSubject {
+    subject: ModeSubject;
+    scope: "agent" | "subagent";
+}
+/** Drop all in-memory caches. Test-only (reassigns the WeakMap). */
+export declare function resetPermissionModeCache(): void;
+/**
+ * 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.
+ */
+export declare function resolvePermissionMode(client: OryAgentClient, subject: ModeSubject, opts?: {
+    now?: number;
+    additionalSubjects?: AdditionalModeSubject[];
+}): Promise<ResolvedPermissionMode>;
+/**
+ * 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.
+ */
+export declare function warmPermissionModeCache(client: OryAgentClient, subject: ModeSubject, opts?: {
+    now?: number;
+    additionalSubjects?: AdditionalModeSubject[];
+}): Promise<ResolvedPermissionMode>;