@ory/codex 0.1.2 → 0.2.0

package/README.md

@@ -2,9 +2,18 @@
 
 [Ory](https://ory.com) bundled into [Codex](https://github.com/openai/codex): skills that scaffold Ory authentication into your codebase, a local Ory stack you can spin up in one command, and (when pointed at an Ory project) authentication, authorization, and audit for every tool Codex runs.
 
+You don't need an Ory account or any prior Ory experience to start.
+
+## Prerequisites
+
+- [Codex](https://github.com/openai/codex) installed and signed in
+- Node.js **≥ 24**
+- [Docker](https://docs.docker.com/get-docker/) (only needed for the local Ory stack)
+- macOS or Linux. Windows works via WSL2.
+
 ## Install
 
-Codex loads hooks from its config. Install and register in one step, with no prior `npm install` required:
+No prior `npm install` required:
 
 ```bash
 npx @ory/codex install            # current project
@@ -12,30 +21,53 @@ npx @ory/codex install --global   # all Codex projects
 npx @ory/codex uninstall
 ```
 
-`install` wires the Ory hooks into your Codex config non-destructively (existing hooks are preserved), registers the Ory MCP server, and drops the Ory skill catalog into `.codex/skills/`. If the installer can't locate your Codex config, `npx -y -p @ory/codex ory-codex-setup` writes it directly.
+That's it — skills, hooks, and the Ory MCP server are now registered. Existing entries in your Codex config are preserved.
 
-## Developer experience
+<details>
+<summary>Alternative install</summary>
 
-This plugin is a productivity layer for Ory itself. You don't need a real Ory project, an account, or any prior Ory experience to start using it.
+If the installer can't locate your Codex config, this writes it directly:
 
-### Skills for scaffolding Ory into your application
+```bash
+npx -y -p @ory/codex ory-codex-setup
+```
+
+</details>
+
+## Quickstart (≈ 3 minutes)
+
+From any project where you'd like Ory authentication, inside Codex:
 
-Codex surfaces the skill catalog in `/skills` and auto-invokes by description. Ask Codex to add Ory auth to your codebase, or invoke a skill directly:
+1. **Start a local Ory instance.** Ask Codex *"start the local Ory stack"* or pick `ory-local-up` from the `/skills` menu.
 
-- **`ory-auth-setup`**: full project setup. Install the Ory CLI, create an Ory Network project, add Ory Elements, configure the SDK, build the auth pages, wire session middleware.
-- **`ory-login-flow`**: login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
-- **`ory-social-login`**: Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
-- **`ory-local-dev`**: drive the local Ory stack (below) from within Codex to prototype and test against without a remote project.
+   A banner prints the seeded test user's email and password. Note them — you'll log in with them in step 3.
 
-Skills are versioned with the plugin so guidance stays in sync as Ory APIs evolve.
+2. **Scaffold Ory into your project.** Ask Codex *"add Ory auth to this app"* or pick `ory-auth-setup` from `/skills`.
+
+   Codex installs Ory Elements, wires the SDK, generates the login / registration / recovery / verification / settings pages, and sets up session middleware. It targets the local stack from step 1, so no signup or API key is needed.
+
+3. **Sign in.** Start your app, visit the login page Codex added, and sign in with the seeded credentials. You now have a real Ory session backed by a real Ory stack — locally, offline, with zero configuration.
+
+That's the full Ory DX path. Stop here if you're just evaluating the plugin. Continue to [Agent security](#agent-security) when you're ready to enforce.
+
+## What's included
+
+### Skills for scaffolding Ory into your application
+
+Codex surfaces the skill catalog in `/skills` and auto-invokes by description. Ask Codex in natural language or invoke a skill directly:
+
+- **`ory-auth-setup`** — full project setup. Install the Ory CLI, create an Ory Network project (or use the local one), add Ory Elements, configure the SDK, build the auth pages, wire session middleware.
+- **`ory-login-flow`** — login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
+- **`ory-social-login`** — Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
+- **`ory-local-dev`** — drive the local Ory stack from within Codex to prototype and test without a remote project.
 
 ### Ory MCP server
 
-Bundled and registered automatically. It exposes the Ory CLI and the Ory Network REST API as MCP tools so Codex can manage identities, OAuth2 clients, projects, permission tuples, and configuration without ever leaving the chat. Useful for seeding test data, verifying a scaffolded integration, or running one-off admin tasks.
+Bundled and registered automatically. Exposes the Ory CLI and the Ory Network REST API as MCP tools so Codex can manage identities, OAuth2 clients, projects, permission tuples, and configuration without ever leaving the chat. Useful for seeding test data, verifying a scaffolded integration, or running one-off admin tasks.
 
-### Local Ory stack in one command
+### Local Ory stack
 
-From Codex's `/skills` picker:
+From Codex's `/skills` menu:
 
 ```
 ory-local-up      # start a local Ory instance in Docker
@@ -44,46 +76,104 @@ ory-local-down    # tear it all down
 
 Or via the CLI: `npx -y -p @ory/codex ory-codex local up | down`.
 
-`local up` runs a local Ory instance in Docker, covering everything the plugin and your scaffolded application need. It also brings up a login UI on `:3000` and Jaeger on `:16686`, all reachable through `http://localhost:4000`. A test user identity is seeded and the credentials are printed for you. Use it to:
+`ory-local-up` brings up Ory Identities, OAuth2, and Permissions, plus a login UI on `:3000` and Jaeger on `:16686`, all reachable through `http://localhost:4000`. A test user identity is seeded and the credentials are printed for you. Use it to:
 
 - **Learn Ory hands-on** without signing up for a hosted project.
-- **Prototype** flows (login, social, MFA, recovery, permission tuples) against a real Ory backend in your local dev loop.
+- **Prototype** flows (login, social, MFA, recovery, permission tuples) against a real Ory backend.
 - **Test** an auth integration end-to-end before pushing anything to a real environment.
 - **Develop** your application against the same identity, OAuth2, and permission surfaces you'll ship with.
 
-Point `ORY_PROJECT_URL` at `http://localhost:4000` (or run `npx -y -p @ory/codex ory-codex configure`) and the security features below run against the local stack.
+## Pointing at a real Ory project
 
-## Configure
+The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project, point the plugin at it:
 
 ```bash
-npx -y -p @ory/codex ory-codex configure --project-url https://<id>.projects.oryapis.com --api-key ory_pat_...
+npx -y -p @ory/codex ory-codex configure \
+  --project-url https://<id>.projects.oryapis.com \
+  --api-key ory_pat_...
 ```
 
-Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine. Without it the plugin still loads cleanly and runs in **pass-through mode**: skills work, but nothing is blocked.
+Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine.
+
+Without configuration the plugin still loads cleanly and runs in **pass-through mode**: skills work, but nothing is blocked. You can stay in pass-through mode indefinitely if you only want the DX features.
 
-## Agent security (Argus)
+## Agent security
 
-Once the plugin is pointed at an Ory project (local or hosted), Codex's session and every tool call are governed by Ory.
+Once the plugin is pointed at an Ory project (local or hosted), Codex's session and every tool call can be governed by Ory.
 
-- **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when `ORY_AUTH_GATE=1`. The Codex process (the **agent**) gets its own OAuth2 identity, self-registered via Dynamic Client Registration on first run.
-- **Authorization.** Before any tool runs, the plugin checks Ory Permissions against the user's subject and blocks the call on `deny`. MCP tool calls additionally get a server-level check.
-- **Audit.** Every decision (allow, deny, fallback) is recorded as a structured trace span: NDJSON file output and/or OTLP/HTTP export to Jaeger, Honeycomb, Grafana, and similar collectors. The user-to-agent delegation is written to Ory as a Zanzibar tuple so "agent X acting on behalf of user Y" stays queryable after tokens expire.
+- **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when `ORY_AUTH_GATE=1` is set. The Codex process (the **agent**) gets its own OAuth2 identity, self-registered via [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) on first run.
+- **Authorization.** Before any tool runs, the plugin checks [Ory Permissions](https://www.ory.com/docs/keto) (Zanzibar-style relation tuples) against the user's subject and blocks the call on `deny`. MCP tool calls additionally get a server-level check.
+- **Audit.** Every decision (allow, deny, fallback) is recorded as a structured trace span: NDJSON file output and/or OTLP/HTTP export to Jaeger, Honeycomb, Grafana, and similar collectors. The user → agent delegation is written to Ory as a relation tuple so *"agent X acting on behalf of user Y"* stays queryable after tokens expire.
 
-The plugin is **fail-open** on its own infrastructure failures (network errors, rate limits, missing config), so enforcement is only as strong as your tuples; grant explicit `invoke` relations for the tools each user should be able to run.
+The plugin is **fail-open** on its own infrastructure failures (network errors, rate limits, missing config), so enforcement is only as strong as your tuples — grant explicit `invoke` relations for the tools each user should be able to run.
 
-## CLI
+### 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
+   export ORY_AUTH_GATE=1
+   ```
+
+   The next Codex session opens a browser for PKCE login. Subsequent sessions reuse the persisted token until it expires.
+
+2. **Bootstrap tuples for the built-in tools.** One idempotent command grants the current user `use` on every tool Codex ships with (shell, apply_patch, …):
+
+   ```bash
+   npx -y -p @ory/codex ory-codex 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
+   npx -y -p @ory/codex ory-codex permissions status
+   ```
+
+   Add tuples for any MCP server tools or custom commands by hand, or via the Ory MCP server from inside Codex (*"grant me use on the shell tool"*).
+
+4. **Promote to enforce.** Once the observe-mode logs look right, switch over:
+
+   ```bash
+   npx -y -p @ory/codex ory-codex permissions enforce
+   ```
+
+   Denies now block the tool call; Codex shows the denial reason and the decision is recorded as a `tool.block` trace span with `blocked: true`. Switch back any time with `permissions observe`.
+
+## CLI reference
 
 ```
 npx -y -p @ory/codex ory-codex install | uninstall                 [--global]
 npx -y -p @ory/codex ory-codex configure                            [--project-url <url>] [--api-key <key>] [--audit-only]
 npx -y -p @ory/codex ory-codex agent <status|unregister>            Manage the agent's OAuth2 identity
+npx -y -p @ory/codex ory-codex permissions <status|bootstrap|observe|enforce>
 npx -y -p @ory/codex ory-codex local <up|down|status|seed|logs|env|configure|reset>
 npx -y -p @ory/codex ory-codex status
 ```
 
+Highlights:
+
+- `agent status` — show the current persisted DCR identity for the agent.
+- `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
+
+- **`ory-local-up` fails.** Make sure Docker is running and ports `3000`, `4000`, `4100`, and `16686` are free.
+- **PKCE login loops.** Clear persisted state with `npx -y -p @ory/codex ory-codex agent unregister` and retry.
+- **`npx` fetches an old version.** Force a fresh fetch: `npx -y -p @ory/codex@latest ory-codex …`.
+- **Need more signal.** Set `ORY_AGENT_DEBUG=true` and `ORY_AGENT_LOG_FILE=/tmp/ory.log` to capture structured logs.
+
 ## Links
 
-- [ory.com](https://ory.com)
+- [Ory documentation](https://www.ory.com/docs/)
+- [Ory Network console](https://console.ory.sh)
+- [Ory Elements](https://github.com/ory/elements)
+- [Codex documentation](https://github.com/openai/codex)
 
 ## License
 

package/dist/cli/main.js

@@ -53,6 +53,10 @@ function main() {
     switch (command) {
         case "install":
             install(args);
+            postInstallPermissions("ory-codex", "codex").then(() => process.exit(0), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
             break;
         case "uninstall":
             uninstall(args);
@@ -66,6 +70,12 @@ function main() {
                 process.exit(1);
             });
             break;
+        case "permissions":
+            (0, argus_1.runPermissionsCommand)("ory-codex", "codex", args).then((code) => process.exit(code), (err) => {
+                console.error(err.message ?? err);
+                process.exit(1);
+            });
+            break;
         case "setup":
             require("./setup.js");
             break;
@@ -105,6 +115,12 @@ function manualSetup(isGlobal) {
     process.argv = ["node", "setup.js", ...setupArgs];
     require("./setup.js");
 }
+async function postInstallPermissions(binName, harness) {
+    const bootstrapped = await (0, argus_1.maybeAutoBootstrap)(binName, harness);
+    (0, argus_1.printPermissionsOnboardingHelp)(binName, harness, {
+        bootstrappedAutomatically: bootstrapped,
+    });
+}
 function status() {
     console.log("Ory Agent Plugin Status (Codex)");
     console.log("================================");
@@ -129,6 +145,7 @@ Commands:
   install [--global]   Install the Ory hooks into Codex configuration
   uninstall            Remove the Ory hooks from Codex configuration
   configure            Set or view Ory project URL and API key
+  permissions <cmd>    Manage permission mode and tool tuples (status, bootstrap, observe, enforce)
   setup [--global]     Write hooks directly to config (fallback)
   status               Show plugin status and configuration
   local <cmd>          Manage local Ory dev environment (up, down, status, seed, ...)

package/dist/handlers.js

@@ -180,40 +180,65 @@ async function handlePreToolUse(input, client) {
                 subject,
                 spanAttributes: { toolName },
             });
-            if (!mcpResult.allowed) {
+            const mcpAttrs = {
+                toolName,
+                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, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary, ...(0, argus_1.alertAttributes)(true) },
+                    attributes: { ...mcpAttrs, allowed: false, ...(0, argus_1.alertAttributes)(false) },
                 });
-                return {
-                    decision: "block",
-                    reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }),
-                };
+                client.tracer.record("tool.invoke", "ok", {
+                    attributes: { ...mcpAttrs, allowed: false, observed: true },
+                });
+                return {};
             }
-            client.tracer.record("tool.invoke", "ok", {
-                attributes: { toolName, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName, ...inputSummary },
-            });
-            return {};
-        }
-        const namespace = resolveNamespace();
-        const result = await client.checkPermission({
-            namespace,
-            object: toolName,
-            relation: "use",
-            ...subject,
-        }, { spanAttributes: { toolName } });
-        if (!result.allowed) {
             client.tracer.record("tool.block", "denied", {
-                attributes: { toolName, ...inputSummary, allowed: result.allowed, ...(0, argus_1.alertAttributes)(true) },
+                attributes: { ...mcpAttrs, allowed: false, ...(0, argus_1.alertAttributes)(true) },
             });
             return {
                 decision: "block",
-                reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }),
+                reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }),
             };
         }
-        client.tracer.record("tool.invoke", "ok", {
-            attributes: { toolName, ...inputSummary, allowed: result.allowed },
+        const namespace = resolveNamespace();
+        const decision = await (0, argus_1.checkAndDecide)(client, { namespace, object: toolName, relation: "use", ...subject }, { spanAttributes: { toolName } });
+        if (decision.kind === "fail_open") {
+            return handlePermissionError(decision.error, toolName, client);
+        }
+        const attrs = { toolName, ...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)(true) },
         });
-        return {};
+        return {
+            decision: "block",
+            reason: (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }),
+        };
     }
     catch (err) {
         return handlePermissionError(err, toolName, client);
@@ -271,20 +296,34 @@ async function handlePermissionRequest(input, client) {
                 subject,
                 spanAttributes: { toolName },
             });
-            return permissionRequestDecision(mcpResult.allowed ? "allow" : "deny", mcpResult.allowed
-                ? "Ory MCP server permission granted"
-                : (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }));
+            const decision = (0, argus_1.applyPermissionMode)(client, mcpResult.allowed, {
+                object: mcpTool.serverName,
+                relation: "use",
+                subjectId,
+                spanAttributes: { toolName, mcpServer: mcpTool.serverName, mcpTool: mcpTool.toolName },
+            });
+            if (decision.kind === "deny") {
+                return permissionRequestDecision("deny", (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, mcp: mcpTool }));
+            }
+            return permissionRequestDecision("allow", decision.kind === "observe"
+                ? "Ory observe mode — denied by policy but allowed through"
+                : "Ory MCP server permission granted");
         }
         const namespace = resolveNamespace();
-        const result = await client.checkPermission({
-            namespace,
-            object: toolName,
-            relation: "use",
-            ...subject,
-        }, { spanAttributes: { toolName } });
-        return permissionRequestDecision(result.allowed ? "allow" : "deny", result.allowed
-            ? "Ory permission granted"
-            : (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }));
+        const decision = await (0, argus_1.checkAndDecide)(client, { namespace, object: toolName, relation: "use", ...subject }, { spanAttributes: { toolName } });
+        if (decision.kind === "fail_open") {
+            const code = decision.error.code;
+            const reason = code === "network_error" || code === "rate_limited"
+                ? `Ory unavailable (${code}), falling back to user prompt`
+                : `Ory permission check failed: ${decision.error.message}`;
+            return permissionRequestFallback(reason);
+        }
+        if (decision.kind === "deny") {
+            return permissionRequestDecision("deny", (0, argus_1.formatDenialMessage)({ tool: toolName, subjectId, namespace }));
+        }
+        return permissionRequestDecision("allow", decision.kind === "observe"
+            ? "Ory observe mode — denied by policy but allowed through"
+            : "Ory permission granted");
     }
     catch (err) {
         const oryErr = err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/codex",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Ory plugin for Codex: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",
@@ -67,7 +67,7 @@
     ".codex-plugin"
   ],
   "dependencies": {
-    "@ory/argus": "0.1.2"
+    "@ory/argus": "0.2.0"
   },
   "engines": {
     "node": ">=24"