@ory/codex 0.8.2 → 0.9.1

package/README.md

@@ -4,6 +4,20 @@
 
 You don't need an Ory account or any prior Ory experience to start.
 
+## New to Ory?
+
+[Ory](https://www.ory.com/docs/) is an open-source identity and access platform — it provides login, registration, sessions, social sign-in, multi-factor auth, and fine-grained permissions, so you don't have to build any of that yourself. Two things make it easy to try with no prior experience:
+
+- **Ory Elements** are prebuilt, themeable UI components for the auth pages (login, registration, recovery, settings). The scaffolding skills wire them into your app for you.
+- **The local Ory stack** is a complete Ory running on your laptop in Docker — no account, no signup, no API key. Everything in the Quickstart below works against it, fully offline.
+
+This plugin does two independent things, and you can use either on its own:
+
+1. **Build auth into your app.** Have Codex scaffold Ory login, registration, social sign-in, and permissions into the project you're working on, backed by the local stack. This is the Quickstart below — it needs nothing but Docker.
+2. **Govern the agent itself.** Authenticate Codex's own session and authorize every tool it runs against Ory Permissions, with a full audit trail. See [Agent security](#agent-security).
+
+If you're just exploring, do the Quickstart first.
+
 ## Prerequisites
 
 - [Codex](https://github.com/openai/codex) installed and signed in
@@ -45,10 +59,11 @@ From any project where you'd like Ory authentication, inside Codex:
 4. **Turn on Ory login for the Codex session itself.** *(Optional but recommended.)* Out of the box the plugin only governs your *app*. To also attach an Ory identity to *Codex's* session — so every tool call is attributed to you, not a fallback `session:<id>` subject — opt in to the user-login flow:
 
    ```bash
-   export ORY_USER_LOGIN=1
+   export ORY_USER_LOGIN=true
+   export ORY_OAUTH2_CLIENT_ID=<value printed by `local up`>
    ```
 
-   User login is off by default. With it on, the next Codex session opens an Ory login in your browser; sign in with the same seeded credentials from step 1, and the token is reused on subsequent sessions until it expires. This is what makes `permissions enforce` (see [Agent security](#agent-security)) deny on the right identity later.
+   User login is off by default. Both exports above are printed in the `local up` banner — copy them straight from there. `ORY_OAUTH2_CLIENT_ID` is required whenever `ORY_USER_LOGIN` is on: it identifies the public OAuth2 client the PKCE browser flow exchanges for a token. With both set, the next Codex session opens an Ory login in your browser; sign in with the same seeded credentials from step 1, and the token is reused on subsequent sessions until it expires. This is what makes `permissions enforce` (see [Agent security](#agent-security)) deny on the right identity later.
 
 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.
 
@@ -58,11 +73,16 @@ That's the full Ory DX path. Stop here if you're just evaluating the plugin. Con
 
 Codex surfaces the skill catalog in `/skills` and auto-invokes by description. Ask Codex in natural language or invoke a skill directly:
 
+**Start here — add Ory auth to your app:**
+
 - **`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-permissions-onboarding`** — bootstrap permission tuples for built-in tools, switch between observe and enforce mode, troubleshoot denials.
+
+**Going further:**
+
+- **`ory-permissions-onboarding`** — bootstrap permissions for built-in tools, switch between observe and enforce mode, troubleshoot denials.
 - **`ory-build-integration`** — pull the runnable subset of an `ory/integrates` template (webhook / config / http-event) into your own app and wire it to your Ory project — no contribution/registry concerns.
 - **`ory-contribute-integration`** — author a brand-new integration as a contribution to `ory/integrates`, including `registry.entry.yaml`, the `Maintained by:` footer, DCO sign-off, and registry regeneration.
 - **`ory-e2b-sandbox`** — scaffold an [E2B](https://e2b.dev) sandbox template that boots with this plugin preinstalled and registered, so every sandbox session is gated by Ory auth, permissions, and tracing without any per-sandbox setup.
@@ -71,7 +91,7 @@ Codex surfaces the skill catalog in `/skills` and auto-invokes by description. A
 
 ### Ory MCP server
 
-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.
+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, permissions, 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
 
@@ -85,36 +105,93 @@ ory-temporal-up   # start a local Temporal dev server (for ory-temporal-worker)
 
 Or via the CLI: `npx -y -p @ory/codex ory-codex local up | down`.
 
-`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:
+`ory-local-up` runs a complete Ory on your laptop: the Ory APIs (Identities, OAuth2, Permissions) at `http://localhost:4000`, a login UI on `:3000`, and Jaeger (the trace viewer) on `:16686`. A test user identity is seeded and its 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.
+- **Prototype** flows (login, social, MFA, recovery, permissions) 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.
 
 ## Pointing at a real Ory project
 
-The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project, point the plugin at it:
+The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project (Ory's managed cloud), point the plugin at it with a single configure command. **The plugin requires `--oauth2-client-id` whenever `--project-url` is provided** — register the client first (see [Register the user OAuth2 client](#register-the-user-oauth2-client) below), then run:
 
 ```bash
 npx -y -p @ory/codex ory-codex configure \
   --project-url https://<id>.projects.oryapis.com \
-  --api-key ory_pat_...
+  --oauth2-client-id <public OAuth2 client id>
 ```
 
+- **`--project-url`** points the plugin at your project. The **agent identity** (machine credentials for Codex's outgoing Ory API calls) is created automatically on first run via OAuth2 Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) against the project's `/oauth2/register` endpoint — no manual step required for that one.
+- **`--oauth2-client-id`** is required because the **user** PKCE browser flow (triggered by `ORY_USER_LOGIN=true`) cannot self-register — you must register a public OAuth2 client ahead of time and supply its id here. The configure command refuses to save a project URL without it, so you don't end up with a silently-broken setup later. See [Register the user OAuth2 client](#register-the-user-oauth2-client) below for the exact CLI / Console steps.
+- **`--api-key ory_pat_...`** is optional — pass it only if you want to override the auto-registered agent identity with a static personal access token (operator override; rarely needed).
+
+If you only want audit logging (no auth or permission checks), substitute `--audit-only` — the OAuth2 client id is not required in that mode:
+
+```bash
+npx -y -p @ory/codex ory-codex configure --audit-only
+```
+
+The same settings can be supplied via environment variables (`ORY_PROJECT_URL`, `ORY_OAUTH2_CLIENT_ID`, `ORY_AGENT_API_KEY`) — env vars take precedence over the config file when both are set, which is what most CI / scripted setups want.
+
 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.
 
+### Register the user OAuth2 client
+
+If you plan to turn on `ORY_USER_LOGIN=true` (recommended — it's what attributes every tool call to *you* rather than a fallback `session:<id>` subject), your hosted Ory project needs a **public** OAuth2 client (no client secret) registered ahead of time. The local stack provisions this for you automatically; against a hosted project you have to register it once yourself.
+
+The client must list **all four** loopback ports as redirect URIs:
+
+- `http://127.0.0.1:47823/callback`
+- `http://127.0.0.1:47824/callback`
+- `http://127.0.0.1:47825/callback`
+- `http://127.0.0.1:47826/callback`
+
+The plugin walks the four ports at runtime so the login can survive any one of them being occupied — Ory rejects the callback if the port it lands on isn't on the registered list, so register all four.
+
+Create the client with the [Ory CLI](https://www.ory.com/docs/guides/cli/installation):
+
+```bash
+ory create oauth2-client --project <project-id> \
+  --name "ory-agent-plugin" \
+  --grant-type authorization_code,refresh_token \
+  --response-type code \
+  --scope openid,offline_access \
+  --token-endpoint-auth-method none \
+  --redirect-uri http://127.0.0.1:47823/callback \
+  --redirect-uri http://127.0.0.1:47824/callback \
+  --redirect-uri http://127.0.0.1:47825/callback \
+  --redirect-uri http://127.0.0.1:47826/callback
+```
+
+…or in the [Ory Console](https://console.ory.sh) under *OAuth2* → *Clients* → *Create client* (pick "Public client", set "Authorization Code" + "Refresh Token" grants, scopes `openid offline_access`, paste the four redirect URIs above). Then persist the issued id with the configure command (preferred — survives across sessions):
+
+```bash
+npx -y -p @ory/codex ory-codex configure \
+  --project-url https://<id>.projects.oryapis.com \
+  --oauth2-client-id <client-id from the step above>
+```
+
+…or set it in the environment alongside `ORY_USER_LOGIN`:
+
+```bash
+export ORY_USER_LOGIN=true
+export ORY_OAUTH2_CLIENT_ID=<client-id from the step above>
+```
+
+Headless / CI runs that already hold a session token can skip this entirely by setting `ORY_USER_SESSION_TOKEN` instead — no browser flow runs, so no OAuth2 client is needed.
+
 ## Agent security
 
 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 user login is enabled (`ORY_USER_LOGIN=1`, off by default — browser PKCE flow on first session, persisted token thereafter). 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.
+- **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when user login is enabled (`ORY_USER_LOGIN=true`, off by default — browser PKCE flow on first session, persisted token thereafter). 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 relations) 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 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 permission grants — grant explicit `use` on the tools each user should be able to run.
 
 ### Enable enforcement
 
@@ -123,12 +200,15 @@ After install the plugin runs in **observe mode**: every tool call is checked ag
 1. **Turn on user login.** It's off by default. In your shell:
 
    ```bash
-   export ORY_USER_LOGIN=1
+   export ORY_USER_LOGIN=true
+   export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>
    ```
 
    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, …):
+   `ORY_OAUTH2_CLIENT_ID` is required when `ORY_USER_LOGIN` is on: PKCE needs a public OAuth2 client registered with the four loopback redirect URIs (`http://127.0.0.1:47823..47826/callback`) to exchange the authorization code for a token. The local stack provisions one and prints the export in its `local up` banner; for a hosted Ory project see [Register the user OAuth2 client](#register-the-user-oauth2-client) for the exact CLI / Console steps. Headless / CI runs can skip the browser flow entirely by pre-supplying `ORY_USER_SESSION_TOKEN` instead.
+
+2. **Bootstrap permissions 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
@@ -142,7 +222,7 @@ After install the plugin runs in **observe mode**: every tool call is checked ag
    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"*).
+   Add permissions 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:
 
@@ -156,7 +236,7 @@ After install the plugin runs in **observe mode**: every tool call is checked ag
 
 ```
 npx -y -p @ory/codex ory-codex install | uninstall
-npx -y -p @ory/codex ory-codex configure                            [--project-url <url>] [--api-key <key>] [--audit-only]
+npx -y -p @ory/codex ory-codex configure                            [--project-url <url> --oauth2-client-id <id>] [--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>
@@ -166,7 +246,7 @@ 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.
+- `permissions observe` / `permissions enforce` — switch between "log denies, allow through" (the install default) and "block denies." `permissions bootstrap` writes `use` permissions for the harness's built-in tools so the promotion path doesn't require hand-writing relations.
 - `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.
 

package/dist/cli/setup.js

@@ -260,12 +260,15 @@ function printNextSteps() {
     console.log("  1. (Optional) Point at an Ory project — without this, the plugin");
     console.log("     runs in pass-through mode (skills work, nothing is blocked):");
     console.log("       npx ory-codex configure --project-url https://<id>.projects.oryapis.com \\");
-    console.log("                              --api-key ory_pat_...");
+    console.log("                              --oauth2-client-id <public OAuth2 client id>");
+    console.log("     (`--oauth2-client-id` is required when --project-url is set, because the");
+    console.log("     user PKCE browser flow needs a pre-registered public client. Add");
+    console.log("     `--api-key ory_pat_...` only to override the agent's auto-registered identity.)");
     console.log("");
     console.log("  2. Or spin up the local Ory stack from inside Codex (`/skills` -> `ory-local-up`).");
     console.log("");
     console.log("  3. Turn on the interactive user login (opt-in):");
-    console.log("       export ORY_USER_LOGIN=1");
+    console.log("       export ORY_USER_LOGIN=true");
     console.log("     Without this, Codex runs without a human Ory identity attached to the");
     console.log("     session and permission checks fall back to a session:<id> subject.");
     console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/codex",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "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",
@@ -66,7 +66,7 @@
     "marketplace"
   ],
   "dependencies": {
-    "@ory/argus": "0.8.2"
+    "@ory/argus": "0.9.1"
   },
   "engines": {
     "node": ">=22"