@ory/claude-code 0.1.2 → 0.1.3
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 +111 -35
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -2,99 +2,175 @@
|
|
|
2
2
|
|
|
3
3
|
[Ory](https://ory.com) bundled into [Claude Code](https://docs.anthropic.com/en/docs/claude-code): skills and slash commands 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 Claude runs.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
You don't need an Ory account or any prior Ory experience to start.
|
|
6
|
+
|
|
7
|
+
## Prerequisites
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and signed in
|
|
10
|
+
- Node.js **≥ 24**
|
|
11
|
+
- [Docker](https://docs.docker.com/get-docker/) (only needed for the local Ory stack)
|
|
12
|
+
- macOS or Linux. Windows works via WSL2.
|
|
13
|
+
|
|
14
|
+
## Install
|
|
8
15
|
|
|
9
|
-
|
|
16
|
+
Inside Claude Code:
|
|
10
17
|
|
|
11
18
|
```
|
|
12
19
|
/plugin install ory-agent-plugin
|
|
13
20
|
```
|
|
14
21
|
|
|
15
|
-
|
|
22
|
+
That's it — skills, slash commands, hooks, and the Ory MCP server are now registered.
|
|
23
|
+
|
|
24
|
+
<details>
|
|
25
|
+
<summary>Alternative install paths</summary>
|
|
26
|
+
|
|
27
|
+
If the public marketplace install above isn't available, either of these registers the same plugin:
|
|
16
28
|
|
|
17
29
|
```
|
|
30
|
+
# Ory-hosted marketplace
|
|
18
31
|
/plugin marketplace add ory/claude-plugins
|
|
19
32
|
/plugin install ory-agent-plugin@ory-plugins
|
|
20
33
|
```
|
|
21
34
|
|
|
22
|
-
**3. The Ory installer.** No prior `npm install` required:
|
|
23
|
-
|
|
24
35
|
```bash
|
|
36
|
+
# Direct installer, no prior npm install required
|
|
25
37
|
npx @ory/claude-code install # current project
|
|
26
38
|
npx @ory/claude-code install --global # all projects (user scope)
|
|
27
39
|
npx @ory/claude-code uninstall
|
|
28
40
|
```
|
|
29
41
|
|
|
30
|
-
|
|
42
|
+
</details>
|
|
31
43
|
|
|
32
|
-
##
|
|
44
|
+
## Quickstart (≈ 3 minutes)
|
|
33
45
|
|
|
34
|
-
|
|
46
|
+
From any project where you'd like Ory authentication, inside Claude Code:
|
|
35
47
|
|
|
36
|
-
|
|
48
|
+
1. **Start a local Ory instance.** Ask Claude *"start the local Ory stack"* or run:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
/ory:local-up
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
A banner prints the seeded test user's email and password. Note them — you'll log in with them in step 3.
|
|
55
|
+
|
|
56
|
+
2. **Scaffold Ory into your project.** Ask Claude *"add Ory auth to this app"* or run:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
/ory:auth-setup
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Claude 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.
|
|
63
|
+
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
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.
|
|
37
67
|
|
|
38
|
-
|
|
68
|
+
## What's included
|
|
39
69
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
- **`/ory:local-dev`**: drive the local Ory stack (below) from within Claude to prototype and test against without a remote project.
|
|
70
|
+
### Skills for scaffolding Ory into your application
|
|
71
|
+
|
|
72
|
+
Each skill is a vetted, end-to-end playbook. Ask Claude in natural language or invoke the slash command directly:
|
|
44
73
|
|
|
45
|
-
|
|
74
|
+
- **`/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.
|
|
75
|
+
- **`/ory:login-flow`** — login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
|
|
76
|
+
- **`/ory:social-login`** — Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
|
|
77
|
+
- **`/ory:local-dev`** — drive the local Ory stack from within Claude to prototype and test without a remote project.
|
|
46
78
|
|
|
47
79
|
### Ory MCP server
|
|
48
80
|
|
|
49
|
-
Bundled and registered automatically.
|
|
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, permission tuples, and configuration without ever leaving the chat. Useful for seeding test data, verifying a scaffolded integration, or running one-off admin tasks.
|
|
50
82
|
|
|
51
|
-
### Local Ory stack
|
|
83
|
+
### Local Ory stack
|
|
52
84
|
|
|
53
85
|
```
|
|
54
86
|
/ory:local-up # start a local Ory instance in Docker
|
|
55
87
|
/ory:local-down # tear it all down
|
|
56
88
|
```
|
|
57
89
|
|
|
58
|
-
`local
|
|
90
|
+
`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:
|
|
59
91
|
|
|
60
92
|
- **Learn Ory hands-on** without signing up for a hosted project.
|
|
61
|
-
- **Prototype** flows (login, social, MFA, recovery, permission tuples) against a real Ory backend
|
|
93
|
+
- **Prototype** flows (login, social, MFA, recovery, permission tuples) against a real Ory backend.
|
|
62
94
|
- **Test** an auth integration end-to-end before pushing anything to a real environment.
|
|
63
95
|
- **Develop** your application against the same identity, OAuth2, and permission surfaces you'll ship with.
|
|
64
96
|
|
|
65
|
-
|
|
97
|
+
## Pointing at a real Ory project
|
|
66
98
|
|
|
67
|
-
|
|
99
|
+
The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project, point the plugin at it:
|
|
68
100
|
|
|
69
101
|
```bash
|
|
70
|
-
npx -y -p @ory/claude-code ory-claude configure
|
|
102
|
+
npx -y -p @ory/claude-code ory-claude configure \
|
|
103
|
+
--project-url https://<id>.projects.oryapis.com \
|
|
104
|
+
--api-key ory_pat_...
|
|
71
105
|
```
|
|
72
106
|
|
|
73
|
-
Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine.
|
|
107
|
+
Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine.
|
|
108
|
+
|
|
109
|
+
Without configuration the plugin still loads cleanly and runs in **pass-through mode**: skills and commands work, but nothing is blocked. You can stay in pass-through mode indefinitely if you only want the DX features.
|
|
110
|
+
|
|
111
|
+
## Agent security
|
|
112
|
+
|
|
113
|
+
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
|
+
|
|
115
|
+
- **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 relation tuples) against the user's subject and blocks the call on `deny`. MCP tool calls additionally get a server-level check.
|
|
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 relation tuples so *"agent X acting on behalf of user Y"* stays queryable after tokens expire.
|
|
118
|
+
|
|
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 tuples — grant explicit `invoke` relations for the tools each user should be able to run.
|
|
120
|
+
|
|
121
|
+
### Enable enforcement
|
|
74
122
|
|
|
75
|
-
|
|
123
|
+
1. **Turn on the user gate.** In your shell:
|
|
76
124
|
|
|
77
|
-
|
|
125
|
+
```bash
|
|
126
|
+
export ORY_AUTH_GATE=1
|
|
127
|
+
```
|
|
78
128
|
|
|
79
|
-
|
|
80
|
-
- **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.
|
|
81
|
-
- **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 (and agent-to-subagent) delegation chain is written to Ory as Zanzibar tuples so "agent X acting on behalf of user Y" stays queryable after tokens expire.
|
|
129
|
+
The next Claude session opens a browser for PKCE login. Subsequent sessions reuse the persisted token until it expires.
|
|
82
130
|
|
|
83
|
-
|
|
131
|
+
2. **Grant yourself permission to use a tool.** Use the Ory MCP server from inside Claude (*"grant me invoke on the Bash tool"*) or the CLI directly:
|
|
84
132
|
|
|
85
|
-
|
|
133
|
+
```bash
|
|
134
|
+
ory create relationship \
|
|
135
|
+
--namespace AgentTools \
|
|
136
|
+
--object Bash \
|
|
137
|
+
--relation invoke \
|
|
138
|
+
--subject-id <your-user-subject-id>
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Your subject id is printed at the start of every Claude session when `ORY_AGENT_DEBUG=true`.
|
|
142
|
+
|
|
143
|
+
3. **See a denial.** Pick a tool you didn't grant (or remove the tuple) and ask Claude to use it. The hook blocks the call and Claude shows the denial reason. The decision is recorded as a `tool.block` trace span.
|
|
144
|
+
|
|
145
|
+
## CLI reference
|
|
86
146
|
|
|
87
147
|
```
|
|
88
|
-
npx -y -p @ory/claude-code ory-claude install | uninstall
|
|
89
|
-
npx -y -p @ory/claude-code ory-claude configure
|
|
90
|
-
npx -y -p @ory/claude-code ory-claude agent <status|unregister>
|
|
148
|
+
npx -y -p @ory/claude-code ory-claude install | uninstall [--global]
|
|
149
|
+
npx -y -p @ory/claude-code ory-claude configure [--project-url <url>] [--api-key <key>] [--audit-only]
|
|
150
|
+
npx -y -p @ory/claude-code ory-claude agent <status|unregister> Manage the agent's OAuth2 identity
|
|
91
151
|
npx -y -p @ory/claude-code ory-claude local <up|down|status|seed|logs|env|configure|reset>
|
|
92
152
|
npx -y -p @ory/claude-code ory-claude status
|
|
93
153
|
```
|
|
94
154
|
|
|
155
|
+
Highlights:
|
|
156
|
+
|
|
157
|
+
- `agent status` — show the current persisted DCR identity for the agent.
|
|
158
|
+
- `configure --audit-only` — record decisions without blocking; useful for a phased rollout.
|
|
159
|
+
- `local seed` / `local env` — reseed the test user, or print env vars for pointing other tools at the local stack.
|
|
160
|
+
|
|
161
|
+
## Troubleshooting
|
|
162
|
+
|
|
163
|
+
- **`/ory:local-up` fails.** Make sure Docker is running and ports `3000`, `4000`, `4100`, and `16686` are free.
|
|
164
|
+
- **PKCE login loops.** Clear persisted state with `npx -y -p @ory/claude-code ory-claude agent unregister` and retry.
|
|
165
|
+
- **`npx` fetches an old version.** Force a fresh fetch: `npx -y -p @ory/claude-code@latest ory-claude …`.
|
|
166
|
+
- **Need more signal.** Set `ORY_AGENT_DEBUG=true` and `ORY_AGENT_LOG_FILE=/tmp/ory.log` to capture structured logs.
|
|
167
|
+
|
|
95
168
|
## Links
|
|
96
169
|
|
|
97
|
-
- [
|
|
170
|
+
- [Ory documentation](https://www.ory.com/docs/)
|
|
171
|
+
- [Ory Network console](https://console.ory.sh)
|
|
172
|
+
- [Ory Elements](https://github.com/ory/elements)
|
|
173
|
+
- [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code)
|
|
98
174
|
|
|
99
175
|
## License
|
|
100
176
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ory/claude-code",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.3",
|
|
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
6
|
"homepage": "https://ory.com",
|
|
@@ -72,7 +72,7 @@
|
|
|
72
72
|
"!dist/**/*.tsbuildinfo"
|
|
73
73
|
],
|
|
74
74
|
"dependencies": {
|
|
75
|
-
"@ory/argus": "0.1.
|
|
75
|
+
"@ory/argus": "0.1.3"
|
|
76
76
|
},
|
|
77
77
|
"engines": {
|
|
78
78
|
"node": ">=24"
|