@ory/claude-code 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 Claude 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 Claude'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
 
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and signed in
@@ -60,10 +74,11 @@ From any project where you'd like Ory authentication, inside Claude Code:
 4. **Turn on Ory login for the Claude session itself.** *(Optional but recommended.)* Out of the box the plugin only governs your *app*. To also attach an Ory identity to *Claude'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 Claude 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 Claude 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.
 
@@ -71,12 +86,17 @@ That's the full Ory DX path. Stop here if you're just evaluating the plugin. Con
 
 ### Skills for scaffolding Ory into your application
 
-Each skill is a vetted, end-to-end playbook. Skills are model-invoked — ask Claude in natural language and the matching skill takes over.
+Each skill is a vetted, end-to-end playbook. Skills are model-invoked — ask Claude in natural language and the matching skill takes over. New to Ory? Start with the first group.
+
+**Start here — add Ory auth to your app:**
 
 - **`ory-auth-setup`** *(e.g. "set up Ory auth in this project")* — 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`** *(e.g. "add login and registration pages with Ory Elements")* — login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
 - **`ory-social-login`** *(e.g. "add Google sign-in via Ory")* — Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
 - **`ory-local-dev`** *(e.g. "run the local Ory stack")* — drive the local Ory stack from within Claude to prototype and test without a remote project.
+
+**Going further:**
+
 - **`ory-permissions-onboarding`** *(e.g. "grant me use on the Bash tool")* — walk through writing the Ory Permissions that let the plugin enforce per-tool access.
 - **`ory-build-integration`** *(e.g. "wire an Ory webhook into my app")* — pull the runnable subset of an `ory/integrates` template (webhook / config / http-event) into the user's own app and wire it to their Ory project — no contribution/registry concerns.
 - **`ory-contribute-integration`** *(e.g. "contribute a new Ory 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.
@@ -96,7 +116,7 @@ Bundled and registered automatically. Exposes the Ory CLI and the Ory Network RE
 /ory-agent-plugin:temporal-up   # start a local Temporal dev server (for ory-temporal-worker)
 ```
 
-`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:
+`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, permissions) against a real Ory backend.
@@ -105,24 +125,80 @@ Bundled and registered automatically. Exposes the Ory CLI and the Ory Network RE
 
 ## 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. A project URL is enough — the agent identity is created automatically via OAuth2 Dynamic Client Registration on first run:
+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/claude-code ory-claude configure \
-  --project-url https://<id>.projects.oryapis.com
+  --project-url https://<id>.projects.oryapis.com \
+  --oauth2-client-id <public OAuth2 client id>
 ```
 
-Pass `--api-key ory_pat_...` only if you want to override the auto-registered agent identity with a static personal access token (operator override; rarely needed).
+- **`--project-url`** points the plugin at your project. The **agent identity** (machine credentials for Claude'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).
 
-Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine. The same settings can be supplied via environment variables (`ORY_PROJECT_URL`, `ORY_AGENT_API_KEY`) — env vars take precedence over the config file when both are set, which is what most CI / scripted setups want.
+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/claude-code ory-claude 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 any configuration the plugin still loads cleanly and runs in **pass-through mode**: skills, slash commands, and audit logging work, but no permission checks run, so nothing is ever 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/claude-code ory-claude 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), Claude'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 Claude 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. Sub-agents launched by the `Task` tool each receive their own typed identity.
+- **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 Claude 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. Sub-agents launched by the `Task` tool each receive their own typed identity.
 - **Authorization.** Before any tool runs, the plugin checks [Ory Permissions](https://www.ory.sh/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 (and agent → subagent) delegation chain is written to Ory as relations so *"agent X acting on behalf of user Y"* stays queryable after tokens expire.
 
@@ -135,11 +211,14 @@ With an Ory project configured, the plugin runs in **observe mode** by default:
 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 Claude session opens a browser for PKCE login. Subsequent sessions reuse the persisted token until it expires.
 
+   `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 Claude ships with (Read, Write, Bash, …):
 
    ```bash
@@ -168,7 +247,7 @@ With an Ory project configured, the plugin runs in **observe mode** by default:
 
 ```
 npx -y -p @ory/claude-code ory-claude install | uninstall              [--global]
-npx -y -p @ory/claude-code ory-claude configure                         [--project-url <url>] [--api-key <key>] [--audit-only]
+npx -y -p @ory/claude-code ory-claude configure                         [--project-url <url> --oauth2-client-id <id>] [--api-key <key>] [--audit-only]
 npx -y -p @ory/claude-code ory-claude agent <status|unregister>         Manage the agent's OAuth2 identity
 npx -y -p @ory/claude-code ory-claude permissions <status|bootstrap|observe|enforce>
 npx -y -p @ory/claude-code ory-claude local <up|down|status|seed|logs|env|configure|reset>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/claude-code",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Ory plugin for Claude Code: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
   "license": "Apache-2.0",
   "homepage": "https://github.com/ory/claude-plugins/tree/master/plugins/ory-agent-plugin",
@@ -75,7 +75,7 @@
     "!dist/**/*.tsbuildinfo"
   ],
   "dependencies": {
-    "@ory/argus": "0.8.2"
+    "@ory/argus": "0.9.1"
   },
   "engines": {
     "node": ">=22"