@ory/opencode 0.1.1 → 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.
Files changed (2) hide show
  1. package/README.md +100 -32
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -2,15 +2,29 @@
2
2
 
3
3
  [Ory](https://ory.com) bundled into [OpenCode](https://opencode.ai): skills and markdown 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 OpenCode runs.
4
4
 
5
+ You don't need an Ory account or any prior Ory experience to start.
6
+
7
+ ## Prerequisites
8
+
9
+ - [OpenCode](https://opencode.ai) installed
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
+
5
14
  ## Install
6
15
 
7
- OpenCode loads plugins listed in the `plugin` array of `opencode.json` and fetches them from npm on next launch:
16
+ Add the plugin to your `opencode.json`:
8
17
 
9
18
  ```json
10
19
  { "plugin": ["@ory/opencode"] }
11
20
  ```
12
21
 
13
- Or use the Ory installer to register the plugin **and** the Ory MCP server in one step, with no prior `npm install` required:
22
+ OpenCode fetches the plugin from npm on next launch.
23
+
24
+ <details>
25
+ <summary>Alternative install paths</summary>
26
+
27
+ The Ory installer registers the plugin **and** the Ory MCP server in one step, with no prior `npm install` required:
14
28
 
15
29
  ```bash
16
30
  npx @ory/opencode install # writes opencode.json + MCP config
@@ -20,68 +34,106 @@ npx @ory/opencode uninstall
20
34
 
21
35
  Either flow drops the Ory skill catalog into `.opencode/skills/` and the local-stack commands into `.opencode/commands/ory/`.
22
36
 
23
- ## Developer experience
37
+ </details>
24
38
 
25
- 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.
39
+ ## Quickstart (≈ 3 minutes)
26
40
 
27
- ### Skills for scaffolding Ory into your application
41
+ From any project where you'd like Ory authentication, inside OpenCode:
42
+
43
+ 1. **Start a local Ory instance.** Ask OpenCode *"start the local Ory stack"* or run:
44
+
45
+ ```
46
+ /ory:local-up
47
+ ```
48
+
49
+ A banner prints the seeded test user's email and password. Note them — you'll log in with them in step 3.
50
+
51
+ 2. **Scaffold Ory into your project.** Ask OpenCode *"add Ory auth to this app"* or invoke the `ory-auth-setup` skill.
52
+
53
+ OpenCode 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.
54
+
55
+ 3. **Sign in.** Start your app, visit the login page OpenCode 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.
56
+
57
+ 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.
28
58
 
29
- Ask OpenCode to add Ory auth to your codebase. Each skill is a vetted, end-to-end playbook:
59
+ ## What's included
30
60
 
31
- - **`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.
32
- - **`ory-login-flow`**: login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
33
- - **`ory-social-login`**: Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
34
- - **`ory-local-dev`**: drive the local Ory stack (below) from within OpenCode to prototype and test against without a remote project.
61
+ ### Skills for scaffolding Ory into your application
62
+
63
+ Each skill is a vetted, end-to-end playbook. Ask OpenCode in natural language or invoke a skill directly:
35
64
 
36
- Skills are versioned with the plugin so guidance stays in sync as Ory APIs evolve.
65
+ - **`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.
66
+ - **`ory-login-flow`** — login, registration, recovery, verification, and settings pages with Ory Elements. Next.js App Router and React SPA variants.
67
+ - **`ory-social-login`** — Google, GitHub, Apple, Microsoft, Discord, and other OIDC providers with Jsonnet data mappers.
68
+ - **`ory-local-dev`** — drive the local Ory stack from within OpenCode to prototype and test without a remote project.
37
69
 
38
70
  ### Ory MCP server
39
71
 
40
- Bundled and registered by the Ory installer. It exposes the Ory CLI and the Ory Network REST API as MCP tools so OpenCode 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.
72
+ Bundled and registered by the Ory installer. Exposes the Ory CLI and the Ory Network REST API as MCP tools so OpenCode 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.
41
73
 
42
- ### Local Ory stack in one command
74
+ ### Local Ory stack
43
75
 
44
76
  ```
45
77
  /ory:local-up # start a local Ory instance in Docker
46
78
  /ory:local-down # tear it all down
47
79
  ```
48
80
 
49
- `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:
81
+ `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:
50
82
 
51
83
  - **Learn Ory hands-on** without signing up for a hosted project.
52
- - **Prototype** flows (login, social, MFA, recovery, permission tuples) against a real Ory backend in your local dev loop.
84
+ - **Prototype** flows (login, social, MFA, recovery, permission tuples) against a real Ory backend.
53
85
  - **Test** an auth integration end-to-end before pushing anything to a real environment.
54
86
  - **Develop** your application against the same identity, OAuth2, and permission surfaces you'll ship with.
55
87
 
56
- Point `ORY_PROJECT_URL` at `http://localhost:4000` (or run `npx -y -p @ory/opencode ory-opencode configure`) and the security features below run against the local stack.
88
+ ## Pointing at a real Ory project
57
89
 
58
- ## Configure
90
+ The Quickstart uses the local stack. If you have a hosted [Ory Network](https://console.ory.sh) project, point the plugin at it:
59
91
 
60
92
  ```bash
61
- npx -y -p @ory/opencode ory-opencode configure --project-url https://<id>.projects.oryapis.com --api-key ory_pat_...
93
+ npx -y -p @ory/opencode ory-opencode configure \
94
+ --project-url https://<id>.projects.oryapis.com \
95
+ --api-key ory_pat_...
62
96
  ```
63
97
 
64
- 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 and commands work, but nothing is blocked.
98
+ Config is saved to `~/.config/ory-agent-plugins/config.json` and shared across every Ory agent plugin on the machine.
65
99
 
66
- ## Agent security (Argus)
100
+ 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.
67
101
 
68
- Once the plugin is pointed at an Ory project (local or hosted), OpenCode's session and every tool call are governed by Ory.
102
+ ## Agent security
69
103
 
70
- - **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when `ORY_AUTH_GATE=1`; tokens refresh and a `user.auth` audit span is emitted at every session start. The OpenCode process (the **agent**) gets its own OAuth2 identity, self-registered via Dynamic Client Registration on first run.
71
- - **Authorization.** When OpenCode prompts for permission to use a tool, the plugin checks Ory Permissions against the user's subject and returns `allow` / `deny`. A parallel pre-tool check is recorded as part of the audit trail. MCP tool calls additionally get a server-level check.
72
- - **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.
104
+ Once the plugin is pointed at an Ory project (local or hosted), OpenCode's session and every tool call can be governed by Ory.
73
105
 
74
- 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.
106
+ - **Authentication.** Two identities. The human at the keyboard (the **user**) authenticates interactively via Ory Identities when `ORY_AUTH_GATE=1` is set. The OpenCode 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.
107
+ - **Authorization.** When OpenCode prompts for permission to use a tool, the plugin checks [Ory Permissions](https://www.ory.com/docs/keto) (Zanzibar-style relation tuples) against the user's subject and returns `allow` / `deny`. A parallel pre-tool check is recorded as part of the audit trail. MCP tool calls additionally get a server-level check.
108
+ - **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.
75
109
 
76
- ## Programmatic usage
110
+ 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.
77
111
 
78
- ```typescript
79
- import { createOryPlugin } from "@ory/opencode";
112
+ ### Enable enforcement
80
113
 
81
- const plugin = createOryPlugin();
82
- ```
114
+ 1. **Turn on the user gate.** In your shell:
115
+
116
+ ```bash
117
+ export ORY_AUTH_GATE=1
118
+ ```
119
+
120
+ The next OpenCode session refreshes or prompts for PKCE login. Subsequent sessions reuse the persisted token until it expires.
121
+
122
+ 2. **Grant yourself permission to use a tool.** Use the Ory MCP server from inside OpenCode (*"grant me invoke on the Bash tool"*) or the CLI directly:
123
+
124
+ ```bash
125
+ ory create relationship \
126
+ --namespace AgentTools \
127
+ --object Bash \
128
+ --relation invoke \
129
+ --subject-id <your-user-subject-id>
130
+ ```
83
131
 
84
- ## CLI
132
+ Your subject id is printed at the start of every OpenCode session when `ORY_AGENT_DEBUG=true`.
133
+
134
+ 3. **See a denial.** Pick a tool you didn't grant (or remove the tuple) and ask OpenCode to use it. The hook blocks the call and OpenCode shows the denial reason. The decision is recorded as a `tool.block` trace span.
135
+
136
+ ## CLI reference
85
137
 
86
138
  ```
87
139
  npx -y -p @ory/opencode ory-opencode install | uninstall [--project-dir <path>]
@@ -91,9 +143,25 @@ npx -y -p @ory/opencode ory-opencode local <up|down|status|seed|logs|env|configu
91
143
  npx -y -p @ory/opencode ory-opencode status [--project-dir <path>]
92
144
  ```
93
145
 
146
+ Highlights:
147
+
148
+ - `agent status` — show the current persisted DCR identity for the agent.
149
+ - `configure --audit-only` — record decisions without blocking; useful for a phased rollout.
150
+ - `local seed` / `local env` — reseed the test user, or print env vars for pointing other tools at the local stack.
151
+
152
+ ## Troubleshooting
153
+
154
+ - **`/ory:local-up` fails.** Make sure Docker is running and ports `3000`, `4000`, `4100`, and `16686` are free.
155
+ - **PKCE login loops.** Clear persisted state with `npx -y -p @ory/opencode ory-opencode agent unregister` and retry.
156
+ - **`npx` fetches an old version.** Force a fresh fetch: `npx -y -p @ory/opencode@latest ory-opencode …`.
157
+ - **Need more signal.** Set `ORY_AGENT_DEBUG=true` and `ORY_AGENT_LOG_FILE=/tmp/ory.log` to capture structured logs.
158
+
94
159
  ## Links
95
160
 
96
- - [ory.com](https://ory.com)
161
+ - [Ory documentation](https://www.ory.com/docs/)
162
+ - [Ory Network console](https://console.ory.sh)
163
+ - [Ory Elements](https://github.com/ory/elements)
164
+ - [OpenCode documentation](https://opencode.ai)
97
165
 
98
166
  ## License
99
167
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ory/opencode",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "Ory plugin for OpenCode: 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",
@@ -64,7 +64,7 @@
64
64
  "!dist/**/*.tsbuildinfo"
65
65
  ],
66
66
  "dependencies": {
67
- "@ory/argus": "0.1.1"
67
+ "@ory/argus": "0.1.3"
68
68
  },
69
69
  "engines": {
70
70
  "node": ">=24"