@ory/claude-code 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +46 -46
- package/dist/cli/main.js +22 -21
- package/package.json +7 -4
package/README.md
CHANGED
|
@@ -16,52 +16,49 @@ You don't need an Ory account or any prior Ory experience to start.
|
|
|
16
16
|
Inside Claude Code:
|
|
17
17
|
|
|
18
18
|
```
|
|
19
|
-
/plugin
|
|
19
|
+
/plugin marketplace add ory/claude-plugins
|
|
20
|
+
/plugin install ory-agent-plugin@ory
|
|
20
21
|
```
|
|
21
22
|
|
|
22
|
-
|
|
23
|
+
Skills, slash commands, hooks, and the Ory MCP server are now registered. Verify with `/plugin list`.
|
|
23
24
|
|
|
24
25
|
<details>
|
|
25
|
-
<summary>Alternative install
|
|
26
|
-
|
|
27
|
-
If the public marketplace install above isn't available, either of these registers the same plugin:
|
|
28
|
-
|
|
29
|
-
```
|
|
30
|
-
# Ory-hosted marketplace
|
|
31
|
-
/plugin marketplace add ory/claude-plugins
|
|
32
|
-
/plugin install ory-agent-plugin@ory-plugins
|
|
33
|
-
```
|
|
26
|
+
<summary>Alternative install path (no Claude Code session required)</summary>
|
|
34
27
|
|
|
35
28
|
```bash
|
|
36
|
-
# Direct installer
|
|
37
|
-
npx @ory/claude-code install # current project
|
|
38
|
-
npx @ory/claude-code install --global # all projects (user scope)
|
|
39
|
-
npx @ory/claude-code uninstall
|
|
29
|
+
# Direct installer — registers the marketplace and installs the plugin via the claude CLI.
|
|
30
|
+
npx -y -p @ory/claude-code ory-claude install # current project
|
|
31
|
+
npx -y -p @ory/claude-code ory-claude install --global # all projects (user scope)
|
|
32
|
+
npx -y -p @ory/claude-code ory-claude uninstall
|
|
40
33
|
```
|
|
41
34
|
|
|
35
|
+
The installer requires the `claude` CLI on `PATH`. After it finishes, run `ory-claude status` to confirm the plugin is registered.
|
|
36
|
+
|
|
42
37
|
</details>
|
|
43
38
|
|
|
44
|
-
## Quickstart
|
|
39
|
+
## Quickstart
|
|
45
40
|
|
|
46
41
|
From any project where you'd like Ory authentication, inside Claude Code:
|
|
47
42
|
|
|
48
|
-
1. **Start a local Ory instance.** Ask Claude *"start the local Ory stack"* or run:
|
|
43
|
+
1. **Start a local Ory instance.** *(~1 min. Requires Docker running.)* Ask Claude *"start the local Ory stack"* or run the slash command:
|
|
49
44
|
|
|
50
45
|
```
|
|
51
|
-
/ory:local-up
|
|
46
|
+
/ory-agent-plugin:local-up
|
|
52
47
|
```
|
|
53
48
|
|
|
54
49
|
A banner prints the seeded test user's email and password. Note them — you'll log in with them in step 3.
|
|
55
50
|
|
|
56
|
-
2. **Scaffold Ory into your project.** Ask Claude *"add Ory auth to this app"
|
|
51
|
+
2. **Scaffold Ory into your project.** *(~5–10 min, depending on your project.)* Ask Claude *"add Ory auth to this app"*. The `ory-auth-setup` skill takes over: it 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.
|
|
57
52
|
|
|
58
|
-
|
|
59
|
-
/ory:auth-setup
|
|
60
|
-
```
|
|
53
|
+
3. **Sign in.** Start your app, visit the login page Claude 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.
|
|
61
54
|
|
|
62
|
-
|
|
55
|
+
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 — set:
|
|
63
56
|
|
|
64
|
-
|
|
57
|
+
```bash
|
|
58
|
+
export ORY_AUTH_GATE=1
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Then restart Claude. On next session start, Claude opens an Ory login in your browser; sign in with the same seeded credentials from step 1. This is what makes `permissions enforce` (see [Agent security](#agent-security)) deny on the right identity later.
|
|
65
62
|
|
|
66
63
|
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.
|
|
67
64
|
|
|
@@ -69,58 +66,60 @@ That's the full Ory DX path. Stop here if you're just evaluating the plugin. Con
|
|
|
69
66
|
|
|
70
67
|
### Skills for scaffolding Ory into your application
|
|
71
68
|
|
|
72
|
-
Each skill is a vetted, end-to-end playbook.
|
|
69
|
+
Each skill is a vetted, end-to-end playbook. Skills are model-invoked — ask Claude in natural language and the matching skill takes over.
|
|
73
70
|
|
|
74
|
-
-
|
|
75
|
-
-
|
|
76
|
-
-
|
|
77
|
-
-
|
|
71
|
+
- **`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.
|
|
72
|
+
- **`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.
|
|
73
|
+
- **`ory-social-login`** *(e.g. "add Google sign-in via Ory")* — Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
|
|
74
|
+
- **`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.
|
|
75
|
+
- **`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.
|
|
78
76
|
|
|
79
77
|
### Ory MCP server
|
|
80
78
|
|
|
81
|
-
Bundled and registered automatically. Exposes the Ory CLI and the Ory Network REST API as MCP tools so Claude can manage identities, OAuth2 clients, projects,
|
|
79
|
+
Bundled and registered automatically. Exposes the Ory CLI and the Ory Network REST API as MCP tools so Claude 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.
|
|
82
80
|
|
|
83
81
|
### Local Ory stack
|
|
84
82
|
|
|
85
83
|
```
|
|
86
|
-
/ory:local-up # start a local Ory instance in Docker
|
|
87
|
-
/ory:local-down # tear it all down
|
|
84
|
+
/ory-agent-plugin:local-up # start a local Ory instance in Docker
|
|
85
|
+
/ory-agent-plugin:local-down # tear it all down
|
|
88
86
|
```
|
|
89
87
|
|
|
90
88
|
`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:
|
|
91
89
|
|
|
92
90
|
- **Learn Ory hands-on** without signing up for a hosted project.
|
|
93
|
-
- **Prototype** flows (login, social, MFA, recovery,
|
|
91
|
+
- **Prototype** flows (login, social, MFA, recovery, permissions) against a real Ory backend.
|
|
94
92
|
- **Test** an auth integration end-to-end before pushing anything to a real environment.
|
|
95
93
|
- **Develop** your application against the same identity, OAuth2, and permission surfaces you'll ship with.
|
|
96
94
|
|
|
97
95
|
## Pointing at a real Ory project
|
|
98
96
|
|
|
99
|
-
The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project, point the plugin at it:
|
|
97
|
+
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:
|
|
100
98
|
|
|
101
99
|
```bash
|
|
102
100
|
npx -y -p @ory/claude-code ory-claude configure \
|
|
103
|
-
--project-url https://<id>.projects.oryapis.com
|
|
104
|
-
--api-key ory_pat_...
|
|
101
|
+
--project-url https://<id>.projects.oryapis.com
|
|
105
102
|
```
|
|
106
103
|
|
|
107
|
-
|
|
104
|
+
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).
|
|
105
|
+
|
|
106
|
+
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.
|
|
108
107
|
|
|
109
|
-
Without configuration the plugin still loads cleanly and runs in **pass-through mode**: skills
|
|
108
|
+
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.
|
|
110
109
|
|
|
111
110
|
## Agent security
|
|
112
111
|
|
|
113
112
|
Once the plugin is pointed at an Ory project (local or hosted), Claude's session and every tool call can be governed by Ory.
|
|
114
113
|
|
|
115
114
|
- **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when `ORY_AUTH_GATE=1` is set. 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.
|
|
116
|
-
- **Authorization.** Before any tool runs, the plugin checks [Ory Permissions](https://www.ory.sh/docs/keto) (Zanzibar-style
|
|
117
|
-
- **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
|
|
115
|
+
- **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.
|
|
116
|
+
- **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.
|
|
118
117
|
|
|
119
|
-
The plugin is **fail-open** on its own infrastructure failures (network errors, rate limits, missing config), so enforcement is only as strong as your
|
|
118
|
+
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.
|
|
120
119
|
|
|
121
120
|
### Enable enforcement
|
|
122
121
|
|
|
123
|
-
|
|
122
|
+
With an Ory project configured, the plugin runs in **observe mode** by default: every tool call is checked against Ory Permissions, 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. (Without a project configured, the plugin is in pass-through mode — no checks run at all.)
|
|
124
123
|
|
|
125
124
|
1. **Turn on the user gate.** In your shell:
|
|
126
125
|
|
|
@@ -130,7 +129,7 @@ After install the plugin runs in **observe mode**: every tool call is checked ag
|
|
|
130
129
|
|
|
131
130
|
The next Claude session opens a browser for PKCE login. Subsequent sessions reuse the persisted token until it expires.
|
|
132
131
|
|
|
133
|
-
2. **Bootstrap
|
|
132
|
+
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, …):
|
|
134
133
|
|
|
135
134
|
```bash
|
|
136
135
|
npx -y -p @ory/claude-code ory-claude permissions bootstrap
|
|
@@ -144,7 +143,7 @@ After install the plugin runs in **observe mode**: every tool call is checked ag
|
|
|
144
143
|
npx -y -p @ory/claude-code ory-claude permissions status
|
|
145
144
|
```
|
|
146
145
|
|
|
147
|
-
Add
|
|
146
|
+
Add permissions for any MCP server tools or custom commands by hand, or via the Ory MCP server from inside Claude (*"grant me use on the Bash tool"*).
|
|
148
147
|
|
|
149
148
|
4. **Promote to enforce.** Once the observe-mode logs look right, switch over:
|
|
150
149
|
|
|
@@ -168,15 +167,16 @@ npx -y -p @ory/claude-code ory-claude status
|
|
|
168
167
|
Highlights:
|
|
169
168
|
|
|
170
169
|
- `agent status` — show the current persisted DCR identity for the agent.
|
|
171
|
-
- `permissions observe` / `permissions enforce` — switch between "log denies, allow through" (the install default) and "block denies." `permissions bootstrap` writes `use`
|
|
170
|
+
- `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.
|
|
172
171
|
- `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`.
|
|
173
172
|
- `local seed` / `local env` — reseed the test user, or print env vars for pointing other tools at the local stack.
|
|
174
173
|
|
|
175
174
|
## Troubleshooting
|
|
176
175
|
|
|
177
|
-
- **`/ory:local-up` fails.** Make sure Docker is running and ports `3000`, `4000`, `4100`, and `16686` are free.
|
|
176
|
+
- **`/ory-agent-plugin:local-up` fails.** Make sure Docker is running and ports `3000`, `4000`, `4100`, and `16686` are free.
|
|
178
177
|
- **PKCE login loops.** Clear persisted state with `npx -y -p @ory/claude-code ory-claude agent unregister` and retry.
|
|
179
178
|
- **`npx` fetches an old version.** Force a fresh fetch: `npx -y -p @ory/claude-code@latest ory-claude …`.
|
|
179
|
+
- **Hooks pinned to an old plugin version.** After a plugin upgrade, run `/plugin marketplace update ory` inside Claude Code (or re-run the npx installer) so the hook commands and MCP server pick up the new release.
|
|
180
180
|
- **Need more signal.** Set `ORY_AGENT_DEBUG=true` and `ORY_AGENT_LOG_FILE=/tmp/ory.log` to capture structured logs.
|
|
181
181
|
|
|
182
182
|
## Links
|
package/dist/cli/main.js
CHANGED
|
@@ -79,7 +79,10 @@ function main() {
|
|
|
79
79
|
});
|
|
80
80
|
break;
|
|
81
81
|
case "status":
|
|
82
|
-
status()
|
|
82
|
+
status().then(() => process.exit(0), (err) => {
|
|
83
|
+
console.error(err.message ?? err);
|
|
84
|
+
process.exit(1);
|
|
85
|
+
});
|
|
83
86
|
break;
|
|
84
87
|
case "local":
|
|
85
88
|
(0, argus_1.runLocalCommand)("ory-claude", args).catch((err) => {
|
|
@@ -105,26 +108,24 @@ async function postInstallPermissions(binName, harness) {
|
|
|
105
108
|
bootstrappedAutomatically: bootstrapped,
|
|
106
109
|
});
|
|
107
110
|
}
|
|
108
|
-
function status() {
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
}
|
|
126
|
-
console.log(` Hook script: ${fs.existsSync(path.join(PACKAGE_ROOT, "dist", "hook.js")) ? "built" : "NOT BUILT (run pnpm build)"}`);
|
|
127
|
-
(0, argus_1.printLogTail)();
|
|
111
|
+
async function status() {
|
|
112
|
+
await (0, argus_1.runStatusCommand)("ory-claude", "claude-code", {
|
|
113
|
+
title: "Claude Code",
|
|
114
|
+
printPluginSection: () => {
|
|
115
|
+
// The default install path delegates plugin assembly to the public
|
|
116
|
+
// `ory/claude-plugins` marketplace, so the persistent dir below is
|
|
117
|
+
// only populated for `--from-source` installs (the dev launcher and
|
|
118
|
+
// local iteration). Run `claude plugin list` for an authoritative
|
|
119
|
+
// view of what the `claude` CLI has registered.
|
|
120
|
+
console.log("Hooks & plugin:");
|
|
121
|
+
const assembled = fs.existsSync(PERSISTENT_DIR);
|
|
122
|
+
console.log(` Local --from-source dir: ${assembled ? PERSISTENT_DIR : "(none — production installs use the ory/claude-plugins marketplace; run 'claude plugin list' to see registered plugins)"}`);
|
|
123
|
+
if (assembled) {
|
|
124
|
+
console.log(` Skills: ${fs.existsSync(path.join(PERSISTENT_DIR, "skills")) ? "installed" : "not installed"}`);
|
|
125
|
+
}
|
|
126
|
+
console.log(` Hook script: ${fs.existsSync(path.join(PACKAGE_ROOT, "dist", "hook.js")) ? "built" : "NOT BUILT (run pnpm build)"}`);
|
|
127
|
+
},
|
|
128
|
+
});
|
|
128
129
|
}
|
|
129
130
|
function help() {
|
|
130
131
|
console.log(`
|
package/package.json
CHANGED
|
@@ -1,9 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ory/claude-code",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Ory plugin for Claude Code: scaffolding skills, a local Ory instance, and authentication, authorization, and audit for every tool call",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
|
-
"homepage": "https://
|
|
6
|
+
"homepage": "https://github.com/ory/claude-plugins/tree/master/plugins/ory-agent-plugin",
|
|
7
|
+
"bugs": {
|
|
8
|
+
"url": "https://github.com/ory/claude-plugins/issues"
|
|
9
|
+
},
|
|
7
10
|
"keywords": [
|
|
8
11
|
"ory",
|
|
9
12
|
"claude",
|
|
@@ -72,10 +75,10 @@
|
|
|
72
75
|
"!dist/**/*.tsbuildinfo"
|
|
73
76
|
],
|
|
74
77
|
"dependencies": {
|
|
75
|
-
"@ory/argus": "0.
|
|
78
|
+
"@ory/argus": "0.4.0"
|
|
76
79
|
},
|
|
77
80
|
"engines": {
|
|
78
|
-
"node": ">=
|
|
81
|
+
"node": ">=22"
|
|
79
82
|
},
|
|
80
83
|
"scripts": {
|
|
81
84
|
"build": "tsc",
|