@ory/opencode 0.1.3 → 0.2.0

package/README.md

@@ -111,6 +111,8 @@ The plugin is **fail-open** on its own infrastructure failures (network errors,
 
 ### Enable enforcement
 
+After install the plugin runs in **observe mode**: every tool call is checked against Ory Permissions, but a deny is recorded as a `permission.observe_deny` audit span and the tool runs anyway. This lets you see what *would* be blocked before turning on hard blocking.
+
 1. **Turn on the user gate.** In your shell:
 
    ```bash
@@ -119,19 +121,29 @@ The plugin is **fail-open** on its own infrastructure failures (network errors,
 
    The next OpenCode session refreshes or prompts for PKCE login. Subsequent sessions reuse the persisted token until it expires.
 
-2. **Grant yourself permission to use a tool.** Use the Ory MCP server from inside OpenCode (*"grant me invoke on the Bash tool"*) or the CLI directly:
+2. **Bootstrap tuples for the built-in tools.** One idempotent command grants the current user `use` on every tool OpenCode ships with (read, write, edit, bash, …):
+
+   ```bash
+   npx -y -p @ory/opencode ory-opencode permissions bootstrap
+   ```
+
+   If a user identity is already cached at install time, the installer runs this for you automatically — re-run after adding tools, switching subjects, or changing the namespace.
+
+3. **Check coverage.** `permissions status` probes every tool in the harness's catalog and prints allowed / denied per tool:
 
    ```bash
-   ory create relationship \
-     --namespace AgentTools \
-     --object Bash \
-     --relation invoke \
-     --subject-id <your-user-subject-id>
+   npx -y -p @ory/opencode ory-opencode permissions status
    ```
 
-   Your subject id is printed at the start of every OpenCode session when `ORY_AGENT_DEBUG=true`.
+   Add tuples for any MCP server tools or custom commands by hand, or via the Ory MCP server from inside OpenCode (*"grant me use on the bash tool"*).
+
+4. **Promote to enforce.** Once the observe-mode logs look right, switch over:
+
+   ```bash
+   npx -y -p @ory/opencode ory-opencode permissions enforce
+   ```
 
-3. **See a denial.** Pick a tool you didn't grant (or remove the tuple) and ask OpenCode to use it. The hook blocks the call and OpenCode shows the denial reason. The decision is recorded as a `tool.block` trace span.
+   Denies now ask the harness to block via a thrown `OryDenialError`; OpenCode shows the denial reason and the decision is recorded as a `tool.block` trace span. Switch back any time with `permissions observe`.
 
 ## CLI reference
 
@@ -139,6 +151,7 @@ The plugin is **fail-open** on its own infrastructure failures (network errors,
 npx -y -p @ory/opencode ory-opencode install | uninstall              [--project-dir <path>]
 npx -y -p @ory/opencode ory-opencode configure                         [--project-url <url>] [--api-key <key>] [--audit-only]
 npx -y -p @ory/opencode ory-opencode agent <status|unregister>         Manage the agent's OAuth2 identity
+npx -y -p @ory/opencode ory-opencode permissions <status|bootstrap|observe|enforce>
 npx -y -p @ory/opencode ory-opencode local <up|down|status|seed|logs|env|configure|reset>
 npx -y -p @ory/opencode ory-opencode status                            [--project-dir <path>]
 ```
@@ -146,7 +159,8 @@ npx -y -p @ory/opencode ory-opencode status                            [--projec
 Highlights:
 
 - `agent status` — show the current persisted DCR identity for the agent.
-- `configure --audit-only` — record decisions without blocking; useful for a phased rollout.
+- `permissions observe` / `permissions enforce` — switch between "log denies, allow through" (the install default) and "block denies." `permissions bootstrap` writes `use` tuples for the harness's built-in tools so the promotion path doesn't require hand-writing relationships.
+- `configure --audit-only` — kill switch that disables Ory entirely (no auth, no permission checks; only audit logging of tool invocations). For phased rollouts, prefer `permissions observe` over `--audit-only`.
 - `local seed` / `local env` — reseed the test user, or print env vars for pointing other tools at the local stack.
 
 ## Troubleshooting

package/dist/cli/main.js

@@ -51,6 +51,10 @@ function main() {
     switch (command) {
         case "install":
             install(args);
+            postInstallPermissions("ory-opencode", "opencode").then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
             break;
         case "uninstall":
             uninstall(args);
@@ -64,6 +68,12 @@ function main() {
                 process.exit(1);
             });
             break;
+        case "permissions":
+            (0, argus_1.runPermissionsCommand)("ory-opencode", "opencode", args).then((code) => process.exit(code), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
         case "status":
             status(args);
             break;
@@ -85,6 +95,12 @@ function main() {
             process.exit(1);
     }
 }
+async function postInstallPermissions(binName, harness) {
+    const bootstrapped = await (0, argus_1.maybeAutoBootstrap)(binName, harness);
+    (0, argus_1.printPermissionsOnboardingHelp)(binName, harness, {
+        bootstrappedAutomatically: bootstrapped,
+    });
+}
 function parseProjectDir(args) {
     const idx = args.indexOf("--project-dir");
     if (idx !== -1 && args[idx + 1])
@@ -185,6 +201,7 @@ Commands:
   install [--project-dir <path>]   Register the Ory plugin in opencode.json
   uninstall [--project-dir <path>] Remove the Ory plugin from opencode.json
   configure                        Set or view Ory project URL and API key
+  permissions <cmd>                Manage permission mode and tool tuples (status, bootstrap, observe, enforce)
   status [--project-dir <path>]    Show plugin configuration and status
   local <cmd>                      Manage local Ory dev environment (up, down, status, seed, ...)
 

package/dist/plugin.js

@@ -201,16 +201,30 @@ function createPermissionHandler(client, _options) {
                     subject,
                     spanAttributes: { toolName: input.toolID },
                 });
-                output.status = mcpResult.allowed ? "allow" : "deny";
+                const decision = (0, argus_1.applyPermissionMode)(client, mcpResult.allowed, {
+                    object: mcpTool.serverName,
+                    relation: "use",
+                    subjectId: (0, argus_1.subjectLabel)(subject),
+                    spanAttributes: { toolName: input.toolID, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName },
+                });
+                output.status = decision.kind === "deny" ? "deny" : "allow";
+                return;
+            }
+            const decision = await (0, argus_1.checkAndDecide)(client, { namespace: resolveNamespace(), object: input.toolID, relation: "use", ...subject }, { spanAttributes: { toolName: input.toolID } });
+            if (decision.kind === "fail_open") {
+                const code = decision.error.code;
+                if (code === "network_error" || code === "rate_limited") {
+                    client.logger.warn("permission.fallback", {
+                        toolID: input.toolID,
+                        code,
+                    });
+                    // Leave output.status as "ask" (default)
+                    return;
+                }
+                output.status = "ask";
                 return;
             }
-            const result = await client.checkPermission({
-                namespace: resolveNamespace(),
-                object: input.toolID,
-                relation: "use",
-                ...subject,
-            }, { spanAttributes: { toolName: input.toolID } });
-            output.status = result.allowed ? "allow" : "deny";
+            output.status = decision.kind === "deny" ? "deny" : "allow";
         }
         catch (err) {
             if (isOryError(err) && (err.code === "network_error" || err.code === "rate_limited")) {
@@ -256,63 +270,90 @@ function createToolBeforeHandler(client) {
                     subject,
                     spanAttributes: { toolName: input.tool },
                 });
-                if (!mcpResult.allowed) {
+                const mcpAttrs = {
+                    toolName: input.tool,
+                    mcpServer: mcpTool.serverName,
+                    mcpTool: mcpTool.toolName,
+                    ...inputSummary,
+                };
+                const decision = (0, argus_1.applyPermissionMode)(client, mcpResult.allowed, {
+                    object: mcpTool.serverName,
+                    relation: "use",
+                    subjectId,
+                    spanAttributes: mcpAttrs,
+                });
+                if (decision.kind === "allow") {
+                    client.tracer.record("tool.invoke", "ok", { attributes: mcpAttrs });
+                    return;
+                }
+                if (decision.kind === "observe") {
                     client.tracer.record("tool.block", "denied", {
-                        attributes: { toolName: input.tool, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary, ...(0, argus_1.alertAttributes)(false) },
-                    });
-                    const message = (0, argus_1.formatDenialMessage)({
-                        tool: input.tool,
-                        subjectId,
-                        mcp: mcpTool,
+                        attributes: { ...mcpAttrs, allowed: false, ...(0, argus_1.alertAttributes)(false) },
                     });
-                    client.logger.warn("tool.denied", {
-                        tool: input.tool,
-                        subjectId,
-                        message,
-                    });
-                    // OpenCode has no native block signal in tool.execute.before;
-                    // throwing aborts execution (documented .env-protection pattern)
-                    // and surfaces error.message back to the agent.
-                    throw new argus_1.OryDenialError({
-                        tool: input.tool,
-                        subjectId,
-                        mcp: mcpTool,
+                    client.tracer.record("tool.invoke", "ok", {
+                        attributes: { ...mcpAttrs, allowed: false, observed: true },
                     });
+                    return;
                 }
-                client.tracer.record("tool.invoke", "ok", {
-                    attributes: { toolName: input.tool, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary },
-                });
-                return;
-            }
-            const namespace = resolveNamespace();
-            const result = await client.checkPermission({
-                namespace,
-                object: input.tool,
-                relation: "use",
-                ...subject,
-            }, { spanAttributes: { toolName: input.tool } });
-            if (!result.allowed) {
                 client.tracer.record("tool.block", "denied", {
-                    attributes: { toolName: input.tool, ...inputSummary, allowed: result.allowed, ...(0, argus_1.alertAttributes)(false) },
+                    attributes: { ...mcpAttrs, allowed: false, ...(0, argus_1.alertAttributes)(false) },
                 });
                 const message = (0, argus_1.formatDenialMessage)({
                     tool: input.tool,
                     subjectId,
-                    namespace,
+                    mcp: mcpTool,
                 });
                 client.logger.warn("tool.denied", {
                     tool: input.tool,
                     subjectId,
                     message,
                 });
+                // OpenCode has no native block signal in tool.execute.before;
+                // throwing aborts execution (documented .env-protection pattern)
+                // and surfaces error.message back to the agent.
                 throw new argus_1.OryDenialError({
                     tool: input.tool,
                     subjectId,
-                    namespace,
+                    mcp: mcpTool,
                 });
             }
-            client.tracer.record("tool.invoke", "ok", {
-                attributes: { toolName: input.tool, ...inputSummary, allowed: result.allowed },
+            const namespace = resolveNamespace();
+            const decision = await (0, argus_1.checkAndDecide)(client, { namespace, object: input.tool, relation: "use", ...subject }, { spanAttributes: { toolName: input.tool } });
+            if (decision.kind === "fail_open") {
+                handlePermissionError(decision.error, input.tool, client);
+                return;
+            }
+            const attrs = { toolName: input.tool, ...inputSummary };
+            if (decision.kind === "allow") {
+                client.tracer.record("tool.invoke", "ok", { attributes: { ...attrs, allowed: true } });
+                return;
+            }
+            if (decision.kind === "observe") {
+                client.tracer.record("tool.block", "denied", {
+                    attributes: { ...attrs, allowed: false, ...(0, argus_1.alertAttributes)(false) },
+                });
+                client.tracer.record("tool.invoke", "ok", {
+                    attributes: { ...attrs, allowed: false, observed: true },
+                });
+                return;
+            }
+            client.tracer.record("tool.block", "denied", {
+                attributes: { ...attrs, allowed: false, ...(0, argus_1.alertAttributes)(false) },
+            });
+            const message = (0, argus_1.formatDenialMessage)({
+                tool: input.tool,
+                subjectId,
+                namespace,
+            });
+            client.logger.warn("tool.denied", {
+                tool: input.tool,
+                subjectId,
+                message,
+            });
+            throw new argus_1.OryDenialError({
+                tool: input.tool,
+                subjectId,
+                namespace,
             });
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/opencode",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Ory plugin for OpenCode: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",
@@ -64,7 +64,7 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@ory/argus": "0.1.3"
+    "@ory/argus": "0.2.0"
   },
   "engines": {
     "node": ">=24"