@ory/argus 0.8.2 → 0.9.1

package/README.md

@@ -16,7 +16,7 @@ const session = await client.verifySession(sessionToken);
 const result = await client.checkPermission({
   namespace: "AgentTools",
   object: "Bash",
-  relation: "invoke",
+  relation: "use",
   subjectId: `session:${sessionId}`,
 });
 
@@ -57,7 +57,7 @@ async function onBeforeTool(toolName: string, sessionId: string) {
   const result = await client.checkPermission({
     namespace: "AgentTools",
     object: toolName,
-    relation: "invoke",
+    relation: "use",
     subjectId: `session:${sessionId}`,
   });
   if (result.allowed === false) {
@@ -84,7 +84,7 @@ The wrapped Ory client. One instance per harness session.
 | Sessions and tokens | `verifySession`, `introspectToken`, `classifyError` |
 | Permission checks | `checkPermission`, `batchCheckPermissions`, `checkMcpPermission` |
 | Principals (who is acting) | `setUserPrincipal`, `setAgentPrincipal` |
-| Delegation tuples | `createRelationship`, `deleteRelationship` |
+| Delegation relations | `createRelationship`, `deleteRelationship` |
 | Tracing | `tracer` (see Tracer below) |
 
 ### Identity gates

package/assets/skills/auth-setup/SKILL.md

@@ -32,6 +32,48 @@ If you find yourself writing `flow.ui.nodes.map(...)` to render auth UI,
 stop and switch to Ory Elements. Custom node rendering is a fallback,
 not a parallel option.
 
+## Correctness contract — satisfy these or the app will 404 / 500 / CSRF
+
+Almost every "Ory doesn't work" report comes from one of four wiring
+mistakes in the generated app — **not** from Ory itself and **not** from
+the agent plugin governing this session. Treat each as a hard requirement,
+and verify all four (Step 10) before telling the user the app is ready.
+
+1. **Ory must be first-party (same site as your app), or every flow fails
+   CSRF.** Ory's browser flows depend on a CSRF cookie. If the browser calls
+   Ory on a *different* site than your app, the browser drops that cookie and
+   you get `CSRF token mismatch`, 403s, or redirect loops. So the browser SDK
+   URL must be **your own origin** — never `https://<slug>.projects.oryapis.com`
+   directly:
+   - **Local dev against Ory Network** — run `ory tunnel` and point the SDK at
+     the tunnel (`http://localhost:4000`). See Step 9.
+   - **Local dev against the local stack** — the gateway is already on
+     `http://localhost:4000` (first-party to `localhost`). Use `http://localhost`,
+     not `127.0.0.1`.
+   - **Production** — serve Ory from your own domain via an Ory Network custom
+     domain (CNAME) or the `@ory/nextjs` proxy, and set the SDK URL to that.
+2. **The app's routes must match what Ory redirects to, or you get 404s.** Ory
+   redirects the browser to the self-service UI URLs configured on the project
+   (login, registration, recovery, verification, settings, **error**). If a page
+   lives at `/auth/login` but the project points at `/login`, the redirect 404s.
+   Pick one set of paths and make these four agree: the page files you create,
+   the `@ory/nextjs` UI-path config, the project's `selfservice.flows.*.ui_url`
+   (+ `error.ui_url`), and the middleware path lists. Always create an error
+   page — Ory redirects there on any flow error. See Step 8.
+3. **Server-side session/flow calls must forward the request cookies, or they
+   500/401.** A `FrontendApi` built with `credentials: "include"` only sends
+   cookies in the **browser**. In Next.js server components, route handlers, and
+   middleware you must forward the incoming request's cookies — the `@ory/nextjs`
+   server helpers do this for you. Reusing the browser client on the server is
+   the single most common 500. See Step 7.
+4. **The SDK URL env var must be set at runtime, or the SDK 500s on
+   construction.** Validate `NEXT_PUBLIC_ORY_SDK_URL` (browser) / `ORY_SDK_URL`
+   (server) at startup and fail with a clear message instead of constructing the
+   client with `undefined`. See Step 4.
+
+If a flow still fails after all four hold, isolate it with the **App bug vs.
+plugin bug** triage in Step 10 before assuming a bug in Ory or in the plugin.
+
 ## Step 1: Check prerequisites
 
 Before installing the Ory CLI, decide where the auth backend will run:
@@ -107,29 +149,54 @@ React island or a small client bundle so you still get the Elements UI
 on the auth routes. Rendering flow nodes directly on the server is the
 fallback of last resort.
 
+**Match the installed major versions.** `@ory/nextjs` and
+`@ory/elements-react` change import names and component props across major
+versions. After installing, run `npm ls @ory/nextjs @ory/elements-react`
+and follow the docs and TypeScript types for *that* major — do not assume
+symbol names from memory. A missing import or a prop type error at build
+time is a version mismatch in the generated app, not a plugin bug.
+
 ## Step 4: Configure the Ory SDK
 
-Create a shared Ory client configuration. The SDK URL should come
-from an environment variable:
+For **Next.js**, prefer wiring Ory through `@ory/nextjs` (its config proxies
+Ory under your own origin and supplies cookie-forwarding server helpers — this
+satisfies contract #1 and #3 for free). Build a hand-rolled `FrontendApi`
+client only for **browser** code in a React SPA, or for explicit client-side
+calls.
+
+When you do build a client, read the URL from an env var and **validate it** —
+constructing the SDK with an `undefined` `basePath` is a 500 waiting to happen
+(contract #4):
 
 ```typescript
 import { Configuration, FrontendApi } from "@ory/client-fetch";
 
+const sdkUrl = process.env.NEXT_PUBLIC_ORY_SDK_URL ?? process.env.ORY_SDK_URL;
+if (!sdkUrl) {
+  throw new Error(
+    "Ory SDK URL is not set. Set NEXT_PUBLIC_ORY_SDK_URL (browser) " +
+      "or ORY_SDK_URL (server) — see Step 4.",
+  );
+}
+
+// Browser-only: `credentials: "include"` sends cookies from browser code.
+// Do NOT reuse this client in server components / route handlers / middleware
+// (contract #3) — use the @ory/nextjs server helpers there.
 const ory = new FrontendApi(
-  new Configuration({
-    basePath: process.env.NEXT_PUBLIC_ORY_SDK_URL || process.env.ORY_SDK_URL,
-    credentials: "include",
-  })
+  new Configuration({ basePath: sdkUrl, credentials: "include" }),
 );
 
 export default ory;
 ```
 
-Add to the project's `.env` or `.env.local`:
+Add to the project's `.env` or `.env.local`. The **browser** value
+(`NEXT_PUBLIC_ORY_SDK_URL`) must be your own origin (contract #1), so in local
+development point it at the tunnel or the local gateway, not at `*.oryapis.com`:
 
 ```bash
-NEXT_PUBLIC_ORY_SDK_URL=https://<project-slug>.projects.oryapis.com
-# or
+# Local dev (Ory Tunnel for Network, or the local stack gateway):
+NEXT_PUBLIC_ORY_SDK_URL=http://localhost:4000
+# Server-side only (safe to be the direct project URL):
 ORY_SDK_URL=https://<project-slug>.projects.oryapis.com
 ```
 
@@ -191,17 +258,27 @@ with the user that an Ory Elements island is not viable.
 
 ## Step 7: Add session middleware
 
-Protect authenticated routes by checking the session:
+Protect authenticated routes by checking the session. **Where this code runs
+matters** (contract #3):
 
-```typescript
-const session = await ory.toSession();
-if (!session) {
-  // Redirect to login
-}
-```
+- **Browser code** can use the `credentials: "include"` client from Step 4
+  directly — the browser attaches the session cookie:
+
+  ```typescript
+  const session = await ory.toSession(); // browser only
+  if (!session) {
+    // Redirect to login
+  }
+  ```
+
+- **Server code** (server components, route handlers, middleware) must forward
+  the incoming request's cookies. Do **not** reuse the browser client — it has
+  no cookies on the server and will throw (→ 500) or always return 401. Use the
+  `@ory/nextjs` server helpers, which read and forward the request cookies for
+  you.
 
 For Next.js, prefer the official `@ory/nextjs` middleware helper since
-it pairs with the Elements pages:
+it pairs with the Elements pages and handles server-side cookie forwarding:
 
 ```typescript
 import { createOryMiddleware } from "@ory/nextjs/middleware";
@@ -216,37 +293,118 @@ export const config = {
 };
 ```
 
-## Step 8: Configure allowed redirect URLs
-
-Update the Ory project to allow redirects back to your app:
-
-```bash
-ory patch project <project-id> \
-  --replace '/services/identity/config/selfservice/allowed_return_urls=["http://localhost:3000", "https://your-domain.com"]'
-```
-
-## Step 9: Set up the Ory Tunnel for local development
-
-For local development, use the Ory tunnel to proxy requests and handle cookies:
-
-```bash
-ory tunnel http://localhost:3000 --project <project-slug>
-```
-
-This runs a proxy on `http://localhost:4000` that handles cookie domains
-correctly for local development. Update your SDK URL to point to the
-tunnel during development.
-
-## Step 10: Verify the setup
-
-1. Start the development server
-2. Navigate to the login page — confirm Ory Elements renders the form,
-   including any social login buttons configured on the project
-3. Create a test account via the registration page
-4. Verify login works
-5. Test account recovery flow
-6. Test the verification flow
-7. Check that protected routes redirect unauthenticated users
+## Step 8: Align the project's routes and return URLs with your app
+
+This step prevents the 404s in contract #2. Ory redirects the browser to the
+self-service UI URLs it has configured; those must point at pages your app
+actually serves.
+
+**Pick one route convention and use it everywhere.** This guide uses
+`/auth/login`, `/auth/registration`, `/auth/recovery`, `/auth/verification`,
+`/auth/settings`, and `/auth/error`. The page files, the middleware path lists,
+and the project config below must all use the same paths.
+
+1. **Create an error page.** Ory redirects to the error UI on *any* flow error;
+   if it doesn't exist you get a 404 (or a blank page) instead of a readable
+   message. Create `app/auth/error/page.tsx` rendering the Elements error
+   component (`<Error>` / the flow-error view for your installed version).
+
+2. **Tell Ory where the pages are.**
+   - **Next.js with `@ory/nextjs`:** declare the UI paths in its config (the
+     UI-path overrides in `ory.config.ts`) so its helpers, middleware, and proxy
+     route to your pages. The SDK serves the UI under your own origin, so you
+     usually do not also edit the project's `ui_url`s.
+   - **React SPA / no `@ory/nextjs` proxy:** set the project's self-service UI
+     URLs to your app's routes:
+
+     ```bash
+     ory patch project <project-id> \
+       --replace '/services/identity/config/selfservice/flows/login/ui_url="https://your-domain.com/auth/login"' \
+       --replace '/services/identity/config/selfservice/flows/registration/ui_url="https://your-domain.com/auth/registration"' \
+       --replace '/services/identity/config/selfservice/flows/recovery/ui_url="https://your-domain.com/auth/recovery"' \
+       --replace '/services/identity/config/selfservice/flows/verification/ui_url="https://your-domain.com/auth/verification"' \
+       --replace '/services/identity/config/selfservice/flows/settings/ui_url="https://your-domain.com/auth/settings"' \
+       --replace '/services/identity/config/selfservice/flows/error/ui_url="https://your-domain.com/auth/error"'
+     ```
+
+3. **Allow redirects back to your app** (every origin you run on — dev and prod):
+
+   ```bash
+   ory patch project <project-id> \
+     --replace '/services/identity/config/selfservice/allowed_return_urls=["http://localhost:3000", "https://your-domain.com"]'
+   ```
+
+## Step 9: Serve Ory first-party (required — contract #1)
+
+The browser must reach Ory on the same site as your app, or cookie-based flows
+fail CSRF. How you achieve that depends on the environment:
+
+- **Local dev against Ory Network — run the Ory Tunnel.** This is required, not
+  optional:
+
+  ```bash
+  ory tunnel http://localhost:3000 --project <project-slug>
+  ```
+
+  It runs a proxy on `http://localhost:4000` that serves Ory first-party to
+  `localhost`. Point `NEXT_PUBLIC_ORY_SDK_URL` at the tunnel
+  (`http://localhost:4000`) — **not** at `https://<slug>.projects.oryapis.com`.
+
+- **Local dev against the local stack** — the gateway is already first-party on
+  `http://localhost:4000`; no tunnel needed (switch to {{REF_LOCAL_DEV}}).
+
+- **Production** — serve Ory from your own domain via an Ory Network custom
+  domain (CNAME) or the `@ory/nextjs` proxy, and set the browser SDK URL to that
+  same-origin path.
+
+If you skip this step, login will appear to work but `whoami`/`toSession` will
+return 401 and form submits will fail with a CSRF error — the classic symptom of
+a cross-site SDK URL.
+
+## Step 10: Verify the setup — and confirm it's correct, not just present
+
+Do not declare success on "the pages render." Run these checks; each maps to a
+contract item so a failure points straight at the cause.
+
+1. **SDK URL is first-party (contract #1).** Confirm the browser SDK URL is your
+   own origin (the tunnel/gateway in dev), not `*.oryapis.com`. In the browser
+   devtools Network tab, the flow requests should go to your origin and the
+   response should `Set-Cookie` a CSRF cookie.
+2. **The flow API itself works (isolates Ory from your app).** Against the URL
+   the browser uses:
+
+   ```bash
+   curl -i "$NEXT_PUBLIC_ORY_SDK_URL/self-service/login/browser"
+   ```
+
+   Expect `200` with a `Set-Cookie: csrf_token...` header. If this fails, the
+   problem is Ory config / the tunnel — not your app code.
+3. **Every redirect target exists (contract #2).** Visit `/auth/login`,
+   `/auth/registration`, `/auth/recovery`, `/auth/verification`,
+   `/auth/settings`, and `/auth/error` directly. Each must return `200`, not
+   `404`. A 404 here means a route/`ui_url` mismatch (Step 8).
+4. **End-to-end:** register a test account, log in, confirm a protected route
+   loads while signed in and redirects to login when signed out, then test
+   recovery and verification.
+
+### App bug vs. plugin bug
+
+These are two different systems. Keep them straight so issues are filed in the
+right place:
+
+- **The generated app** (login pages, CSRF, sessions, the `/auth/*` routes) is
+  ordinary code running in the user's project. A `404`/`500`/CSRF on an `/auth/*`
+  route, or in the browser Network tab, is an **app/config** issue — work the
+  four contract items and the checks above.
+- **The agent plugin** governs *this coding session* — it authenticates the
+  agent, checks Ory Permissions before each tool call, and writes trace spans. It
+  never serves your app's HTTP routes. Diagnose it with
+  `{{NPX}} status` and the debug log (`ORY_AGENT_DEBUG=true`), **not** by looking
+  at your app's auth pages.
+
+Quick triage: if `curl` to the flow API (check 2) succeeds but the app page
+fails, it's the app. If `curl` fails, it's Ory/tunnel config. Neither is the
+plugin unless `{{NPX}} status` reports a problem.
 
 ## Customization
 

package/assets/skills/login-flow/SKILL.md

@@ -24,6 +24,27 @@ rendering belongs in the fallback section at the end of this skill.
   no per-app rewrite needed.
 - Works in Next.js (App Router and Pages Router) and any React SPA.
 
+## Avoid the 404 / 500 / CSRF traps
+
+These pages only work if the surrounding wiring is correct — most "the login
+page is broken" reports are wiring, not the pages or the plugin. If you have not
+run {{REF_AUTH_SETUP}}, do that first; it establishes the four invariants these
+pages depend on:
+
+- **First-party SDK URL** — the browser must reach Ory on your own origin (the
+  Ory Tunnel or local gateway, `http://localhost:4000` in dev), never
+  `https://<slug>.projects.oryapis.com` directly, or every form submit fails
+  with a CSRF error.
+- **Routes match the project config** — the `/auth/*` paths below must match the
+  project's self-service `ui_url`s and the middleware lists, and you must create
+  an `/auth/error` page, or Ory's redirects 404.
+- **Server calls forward cookies** — server-side session/flow reads must forward
+  the request cookies (the `@ory/nextjs` server helpers do this); reusing the
+  browser client on the server 500s.
+
+See the **Correctness contract** and the **App bug vs. plugin bug** triage in
+{{REF_AUTH_SETUP}} for the full detail.
+
 ## Before you start
 
 Check the project setup:
@@ -270,18 +291,39 @@ Initialize with `createBrowserSettingsFlow` and render
 component handles password changes, profile traits, MFA enrollment,
 and connected social providers.
 
+## Build the error page (do not skip — missing it causes 404s)
+
+Ory redirects the browser to the error UI on **any** flow error (expired flow,
+validation failure, misconfiguration). If that route doesn't exist the user
+hits a 404 or a blank page instead of a readable message, and the failure looks
+like a plugin bug when it's just a missing page.
+
+Create `app/auth/error/page.tsx` and render the Elements error view for your
+installed version (`getFlowError` from `@ory/nextjs/app` + the Elements error
+component). Make sure its path matches the project's `error.ui_url`
+(see {{REF_AUTH_SETUP}}, Step 8). For a React SPA, fetch the error with
+`getFlowError({ id })` from the `error` query param and display
+`error.error.message`.
+
 ## Add session management
 
-Create a utility to check the current session:
+Create a **browser** utility to check the current session. (For server
+components, route handlers, and middleware, use the `@ory/nextjs` server
+helpers instead — they forward the request cookies. Reusing this browser client
+on the server has no cookies and will 500/401.)
 
 ```typescript
 import { FrontendApi, Configuration, Session } from "@ory/client-fetch";
 
+const sdkUrl = process.env.NEXT_PUBLIC_ORY_SDK_URL;
+if (!sdkUrl) {
+  throw new Error("NEXT_PUBLIC_ORY_SDK_URL is not set — see ory-auth-setup Step 4.");
+}
+
+// Browser-only client. `credentials: "include"` only sends cookies in the browser,
+// and sdkUrl must be your own origin (the tunnel/gateway in dev), not *.oryapis.com.
 const ory = new FrontendApi(
-  new Configuration({
-    basePath: process.env.NEXT_PUBLIC_ORY_SDK_URL,
-    credentials: "include",
-  })
+  new Configuration({ basePath: sdkUrl, credentials: "include" }),
 );
 
 export async function getSession(): Promise<Session | null> {
@@ -345,14 +387,33 @@ falling back to custom node rendering.
 
 ## Test the flow
 
-1. Start the dev server and Ory tunnel (if developing locally)
-2. Visit `/auth/registration` to create an account — confirm Elements
-   renders all configured methods (password, social, passkey, etc.)
-3. Visit `/auth/login` to sign in
-4. Verify session is established (check protected routes)
-5. Test `/auth/recovery` with a registered email
-6. Test `/auth/settings` for profile changes
-7. Test logout
+Don't stop at "the page renders." Run these in order — each one isolates a
+different failure class:
+
+1. Start the dev server **and the Ory tunnel** (local dev against Network), or
+   the local stack. Confirm the browser SDK URL is your own origin, not
+   `*.oryapis.com`.
+2. **Flow API reachable (isolates Ory from your app):**
+
+   ```bash
+   curl -i "$NEXT_PUBLIC_ORY_SDK_URL/self-service/login/browser"
+   ```
+
+   Expect `200` and a `Set-Cookie: csrf_token...` header. If this fails it's the
+   tunnel / Ory config, not your pages.
+3. **No 404s:** visit `/auth/login`, `/auth/registration`, `/auth/recovery`,
+   `/auth/verification`, `/auth/settings`, and `/auth/error` — each returns
+   `200`. A 404 means a route/`ui_url` mismatch.
+4. Register at `/auth/registration` — confirm Elements renders all configured
+   methods (password, social, passkey, etc.).
+5. Sign in at `/auth/login`; confirm a protected route loads, and redirects to
+   login when signed out.
+6. Test `/auth/recovery` with a registered email, `/auth/settings` for profile
+   changes, and logout.
+
+If a submit fails with a CSRF error, the SDK URL is cross-site (trap #1). If a
+redirect 404s, a route doesn't match the project config (trap #2). Neither is a
+plugin bug — see the **App bug vs. plugin bug** triage in {{REF_AUTH_SETUP}}.
 
 ## Fallback: rendering UI nodes by hand
 

package/assets/skills/ory-build-agent/SKILL.md

@@ -86,7 +86,7 @@ import {
 const client = OryAgentClient.fromEnv("my-agent");
 const { projectUrl } = resolveConfig();
 
-// 1. User gate — interactive PKCE when ORY_USER_LOGIN=1, no-op otherwise.
+// 1. User gate — interactive PKCE when ORY_USER_LOGIN=true, no-op otherwise.
 const userDecision = await ensureUserAuthenticated(client, {
   binName: "my-agent",
   harness: "my-agent",
@@ -409,7 +409,7 @@ PKCE flow, permission tuples, and trace spans are all visible:
 1. {{REF_LOCAL_UP}} — brings up Kratos / Keto / Hydra on `localhost:4000`
    and seeds a demo user. The banner prints the email + password.
 2. Export the env vars the launcher writes (`ORY_PROJECT_URL`,
-   `ORY_USER_LOGIN=1`, `ORY_OAUTH2_CLIENT_ID`, optional
+   `ORY_USER_LOGIN=true`, `ORY_OAUTH2_CLIENT_ID`, optional
    `ORY_AGENT_TRACE_FILE` for an NDJSON span log).
 3. Start your agent. Confirm the browser opens for PKCE login.
 4. Invoke a gated tool and `tail -f $ORY_AGENT_TRACE_FILE | jq .` — you

package/assets/skills/ory-e2b-sandbox/SKILL.md

@@ -66,7 +66,7 @@ export const template = Template()
   // Sandbox runtime defaults. Per-tenant secrets (project URL, tokens, client
   // IDs) MUST be passed at Sandbox.create() time, never baked into the image.
   .setEnvs({
-    ORY_USER_LOGIN: "1",
+    ORY_USER_LOGIN: "true",
     ORY_PERMISSION_MODE: "observe",
     ORY_PERMISSION_NAMESPACE: "AgentTools",
     ORY_AGENT_DEBUG: "true",

package/assets/skills/permissions-onboarding/SKILL.md

@@ -41,9 +41,11 @@ What you want to see:
 If any of those are wrong, fix them before continuing:
 
 ```sh
-{{NPX}} configure --project-url <URL> --api-key <KEY>
+{{NPX}} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]
 ```
 
+`--oauth2-client-id` is the public OAuth2 client registered in your Ory project (required when `ORY_USER_LOGIN=true`; see the *Register the user OAuth2 client* section of the plugin README).
+
 ## Step 2: Look at the current permission posture
 
 ```sh
@@ -94,7 +96,7 @@ Two common failure modes:
 1. **No user identity cached.** Bootstrap needs to know which subject
    to grant tuples to. If user login has never run (no PKCE login,
    no `ORY_USER_SUBJECT_ID`), the command refuses. Run the harness once
-   with `ORY_USER_LOGIN=1` to cache a user token, or set
+   with `ORY_USER_LOGIN=true` to cache a user token, or set
    `ORY_USER_SUBJECT_ID=<id>` to target a known subject.
 2. **Credentials lack write scope on the permission namespace.** The
    command prints the full tuple list so you can apply them manually

package/assets/skills/social-login/SKILL.md

@@ -33,6 +33,15 @@ recommend switching to Ory Elements before adding more providers.
    recommend migrating to Ory Elements so social buttons render for
    free.
 
+**Social login depends on the same wiring as the rest of Ory.** Before
+debugging providers, confirm the base app is correct per the Correctness
+contract in {{REF_AUTH_SETUP}}: a first-party SDK URL (the tunnel or local
+gateway in dev, never `*.oryapis.com` in the browser), routes that match the
+project config, and your app origin listed in `allowed_return_urls`. The
+provider redirects the browser back *through Ory* to your app, so a missing
+return URL or a cross-site SDK URL produces a post-login error or 404 that looks
+like a provider bug but isn't.
+
 ## Step 1: Choose providers
 
 Ask the user which social login providers they want. Common options:

package/dist/agent-auth.js

@@ -290,7 +290,7 @@ async function resolveAgentCredentials(options = {}) {
     }
     return {
         kind: "none",
-        reason: "No agent credentials configured. Run with a user session (ORY_USER_LOGIN=1) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
+        reason: "No agent credentials configured. Run with a user session (ORY_USER_LOGIN=true) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
         warnings,
     };
 }

package/dist/cli.d.ts

@@ -1,8 +1,16 @@
 /**
  * Shared `configure` command implementation for all plugin CLIs.
  *
- * Parses --project-url and --api-key from args. If neither is provided,
- * shows the current configuration. Otherwise saves the provided values.
+ * Parses --project-url, --api-key, and --oauth2-client-id from args.
+ * If none is provided, shows the current configuration. Otherwise saves
+ * the provided values.
+ *
+ * When `--project-url` is provided, requires the OAuth2 client id to be
+ * resolvable from one of: the `--oauth2-client-id` flag, the
+ * `ORY_OAUTH2_CLIENT_ID` env var, or an already-persisted value in the
+ * shared config. The PKCE browser flow that runs when
+ * `ORY_USER_LOGIN=true` can't self-register that client — surfacing the
+ * requirement here keeps users from a silently-broken setup later.
  */
 export declare function runConfigureCommand(binName: string, args: string[]): void;
 /**

package/dist/cli.js

@@ -54,12 +54,21 @@ const tracer_js_1 = require("./tracer.js");
 /**
  * Shared `configure` command implementation for all plugin CLIs.
  *
- * Parses --project-url and --api-key from args. If neither is provided,
- * shows the current configuration. Otherwise saves the provided values.
+ * Parses --project-url, --api-key, and --oauth2-client-id from args.
+ * If none is provided, shows the current configuration. Otherwise saves
+ * the provided values.
+ *
+ * When `--project-url` is provided, requires the OAuth2 client id to be
+ * resolvable from one of: the `--oauth2-client-id` flag, the
+ * `ORY_OAUTH2_CLIENT_ID` env var, or an already-persisted value in the
+ * shared config. The PKCE browser flow that runs when
+ * `ORY_USER_LOGIN=true` can't self-register that client — surfacing the
+ * requirement here keeps users from a silently-broken setup later.
  */
 function runConfigureCommand(binName, args) {
     let projectUrl;
     let apiKey;
+    let oauth2ClientId;
     let auditOnly = false;
     for (let i = 0; i < args.length; i++) {
         switch (args[i]) {
@@ -69,30 +78,35 @@ function runConfigureCommand(binName, args) {
             case "--api-key":
                 apiKey = args[++i];
                 break;
+            case "--oauth2-client-id":
+                oauth2ClientId = args[++i];
+                break;
             case "--audit-only":
                 auditOnly = true;
                 break;
         }
     }
-    if (!projectUrl && !apiKey && !auditOnly) {
+    if (!projectUrl && !apiKey && !oauth2ClientId && !auditOnly) {
         const resolved = (0, config_js_1.resolveConfig)();
         const configPath = (0, config_js_1.getConfigPath)();
         console.log("Ory Plugin Configuration");
         console.log("========================");
         console.log("");
-        console.log(`Config file: ${configPath}`);
-        console.log(`Project URL: ${resolved.projectUrl ?? "(not set)"} [${resolved.projectUrlSource}]`);
-        console.log(`API Key:     ${resolved.apiKey ? "(set)" : "(not set)"} [${resolved.apiKeySource}]`);
-        console.log(`Audit Only:  ${resolved.auditOnly ? "yes" : "no"}`);
+        console.log(`Config file:      ${configPath}`);
+        console.log(`Project URL:      ${resolved.projectUrl ?? "(not set)"} [${resolved.projectUrlSource}]`);
+        console.log(`API Key:          ${resolved.apiKey ? "(set)" : "(not set)"} [${resolved.apiKeySource}]`);
+        console.log(`OAuth2 Client ID: ${resolved.oauth2ClientId ?? "(not set)"} [${resolved.oauth2ClientIdSource}]`);
+        console.log(`Audit Only:       ${resolved.auditOnly ? "yes" : "no"}`);
         console.log("");
         console.log("To configure:");
-        console.log(`  npx ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.log(`  npx ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         console.log("");
         console.log("To enable audit logging only (no auth or permission checks):");
         console.log(`  npx ${binName} configure --audit-only`);
         console.log("");
         console.log("Or set environment variables:");
         console.log("  export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
+        console.log("  export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>");
         console.log("  export ORY_AGENT_API_KEY=ory_pat_...");
         return;
     }
@@ -106,11 +120,49 @@ function runConfigureCommand(binName, args) {
         console.log("This configuration is shared across all Ory agent plugins.");
         return;
     }
+    // When --project-url is provided we need a usable OAuth2 client id for
+    // the user PKCE flow — block the configure with a clear error if none
+    // is reachable from the flag, env, or already-persisted config.
+    if (projectUrl) {
+        const persisted = (0, config_js_1.loadConfig)().oauth2ClientId;
+        const envClientId = process.env.ORY_OAUTH2_CLIENT_ID;
+        const resolved = oauth2ClientId ?? envClientId ?? persisted;
+        if (!resolved) {
+            console.error("Error: --project-url requires an OAuth2 client id for the user PKCE flow.\n" +
+                "\n" +
+                "Provide one with --oauth2-client-id <id>, or set ORY_OAUTH2_CLIENT_ID in your\n" +
+                "environment. The client must be a public OAuth2 client (no client secret,\n" +
+                "token_endpoint_auth_method=none) registered in your Ory project with all four\n" +
+                "loopback redirect URIs:\n" +
+                "  http://127.0.0.1:47823/callback\n" +
+                "  http://127.0.0.1:47824/callback\n" +
+                "  http://127.0.0.1:47825/callback\n" +
+                "  http://127.0.0.1:47826/callback\n" +
+                "\n" +
+                "Create it with:\n" +
+                "  ory create oauth2-client --project <project-id> \\\n" +
+                "    --name \"ory-agent-plugin\" \\\n" +
+                "    --grant-type authorization_code,refresh_token \\\n" +
+                "    --response-type code \\\n" +
+                "    --scope openid,offline_access \\\n" +
+                "    --token-endpoint-auth-method none \\\n" +
+                "    --redirect-uri http://127.0.0.1:47823/callback \\\n" +
+                "    --redirect-uri http://127.0.0.1:47824/callback \\\n" +
+                "    --redirect-uri http://127.0.0.1:47825/callback \\\n" +
+                "    --redirect-uri http://127.0.0.1:47826/callback\n" +
+                "\n" +
+                "If you only want audit logging (no auth or permission checks), use:\n" +
+                `  npx ${binName} configure --audit-only`);
+            process.exit(1);
+        }
+    }
     const update = {};
     if (projectUrl)
         update.projectUrl = projectUrl;
     if (apiKey)
         update.apiKey = apiKey;
+    if (oauth2ClientId)
+        update.oauth2ClientId = oauth2ClientId;
     // Clear auditOnly when configuring with a project URL
     update.auditOnly = false;
     (0, config_js_1.saveConfig)(update);
@@ -120,9 +172,11 @@ function runConfigureCommand(binName, args) {
         console.log(`  Project URL: ${projectUrl}`);
     if (apiKey)
         console.log(`  API Key: (set)`);
+    if (oauth2ClientId)
+        console.log(`  OAuth2 Client ID: ${oauth2ClientId}`);
     console.log("");
     console.log("This configuration is shared across all Ory agent plugins.");
-    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY) take precedence when set.");
+    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY, ORY_OAUTH2_CLIENT_ID) take precedence when set.");
 }
 /**
  * Print the "Configuration:" block showing Ory project URL and API key status.
@@ -136,6 +190,7 @@ function printOryConfig() {
     console.log(`  Mode:            ${resolved.auditOnly ? "audit-only" : "full"}`);
     console.log(`  Project URL:     ${resolved.projectUrl ?? "NOT SET"} [source: ${resolved.projectUrlSource}]`);
     console.log(`  API Key:         ${resolved.apiKey ? "(set)" : "NOT SET"} [source: ${resolved.apiKeySource}]`);
+    console.log(`  OAuth2 Client:   ${resolved.oauth2ClientId ?? "NOT SET"} [source: ${resolved.oauth2ClientIdSource}]`);
     console.log(`  Permission mode: ${resolved.permissionMode} [source: ${resolved.permissionModeSource}]`);
     console.log(`  Namespace:       ${namespace}`);
 }
@@ -153,6 +208,7 @@ function printEnvironment() {
             false,
         ],
         ["ORY_AGENT_CLIENT_ID", process.env.ORY_AGENT_CLIENT_ID, false],
+        ["ORY_OAUTH2_CLIENT_ID", process.env.ORY_OAUTH2_CLIENT_ID, false],
         [
             "ORY_USER_SESSION_TOKEN",
             process.env.ORY_USER_SESSION_TOKEN ? "(set)" : undefined,
@@ -210,10 +266,13 @@ function printEnvHelp(binName) {
     console.log("Configure your Ory credentials (one of these methods):");
     console.log("");
     console.log("  Option 1 — Save to config file (persists across sessions):");
-    console.log(`    npx ${binName} configure --project-url https://your-project.projects.oryapis.com --api-key ory_pat_...`);
+    console.log(`    npx ${binName} configure --project-url https://your-project.projects.oryapis.com \\`);
+    console.log("                              --oauth2-client-id <public OAuth2 client id> \\");
+    console.log("                              --api-key ory_pat_...");
     console.log("");
     console.log("  Option 2 — Set environment variables:");
     console.log("    export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
+    console.log("    export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>");
     console.log("    export ORY_AGENT_API_KEY=ory_pat_...");
     console.log("");
     console.log("If neither is set when a session starts, the agent will prompt for configuration.");
@@ -371,7 +430,7 @@ async function interactiveConfigPrompt(binName) {
         "Run one of the following commands in another terminal:",
         "",
         "  Connect to Ory (enables auth & permission checks):",
-        `    npx ${binName} configure --project-url <URL> --api-key <KEY>`,
+        `    npx ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`,
         "",
         "  Or, enable audit logging only (no auth or permission checks):",
         `    npx ${binName} configure --audit-only`,

package/dist/config.d.ts

@@ -75,6 +75,16 @@ export type PermissionMode = "observe" | "enforce";
 export interface OryPluginConfig {
     projectUrl?: string;
     apiKey?: string;
+    /**
+     * Public OAuth2 client id used by the user PKCE browser flow when
+     * `ORY_USER_LOGIN` is on. The client must be registered ahead of time
+     * in the Ory project with all four loopback redirect URIs
+     * (`http://127.0.0.1:47823..47826/callback`) and
+     * `token_endpoint_auth_method=none`. The local stack provisions one
+     * automatically; against a hosted project the operator registers it
+     * once and supplies the id here (or via `ORY_OAUTH2_CLIENT_ID`).
+     */
+    oauth2ClientId?: string;
     /** When true, only audit logging is enabled — no auth or permission checks. */
     auditOnly?: boolean;
     /**
@@ -144,11 +154,13 @@ export declare function mutateConfig(mutator: (current: OryPluginConfig) => OryP
 export declare function resolveConfig(): {
     projectUrl?: string;
     apiKey?: string;
+    oauth2ClientId?: string;
     auditOnly: boolean;
     permissionMode: PermissionMode;
     permissionModeSource: "env" | "config" | "default";
     projectUrlSource: "env" | "config" | "none";
     apiKeySource: "env" | "config" | "none";
+    oauth2ClientIdSource: "env" | "config" | "none";
 };
 /**
  * Build the "not configured" prompt message for a given harness CLI bin name.

package/dist/config.js

@@ -115,6 +115,7 @@ function loadConfig() {
         return {
             projectUrl: typeof parsed.projectUrl === "string" ? parsed.projectUrl : undefined,
             apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : undefined,
+            oauth2ClientId: typeof parsed.oauth2ClientId === "string" ? parsed.oauth2ClientId : undefined,
             auditOnly: parsed.auditOnly === true ? true : undefined,
             permissionMode: parsePermissionMode(parsed.permissionMode),
             user: parseUserCredentials(parsed),
@@ -328,6 +329,7 @@ function resolveConfig() {
     // alias kept for back-compat (agent-auth emits a warning when only the
     // legacy form is set).
     const envApiKey = process.env.ORY_AGENT_API_KEY ?? process.env.ORY_API_KEY;
+    const envClientId = process.env.ORY_OAUTH2_CLIENT_ID;
     const envMode = parsePermissionMode(process.env.ORY_PERMISSION_MODE);
     const permissionMode = envMode ?? file.permissionMode ?? "observe";
     const permissionModeSource = envMode
@@ -338,11 +340,13 @@ function resolveConfig() {
     return {
         projectUrl: envProjectUrl ?? file.projectUrl,
         apiKey: envApiKey ?? file.apiKey,
+        oauth2ClientId: envClientId ?? file.oauth2ClientId,
         auditOnly: file.auditOnly === true,
         permissionMode,
         permissionModeSource,
         projectUrlSource: envProjectUrl ? "env" : file.projectUrl ? "config" : "none",
         apiKeySource: envApiKey ? "env" : file.apiKey ? "config" : "none",
+        oauth2ClientIdSource: envClientId ? "env" : file.oauth2ClientId ? "config" : "none",
     };
 }
 /**
@@ -352,7 +356,7 @@ function configPromptMessage(binName) {
     return ("The Ory agent plugin is installed but not yet configured.\n" +
         "\n" +
         "  Option 1 — Connect to Ory (enables authentication and permission checks):\n" +
-        `    npx ${binName} configure --project-url <URL> --api-key <KEY>\n` +
+        `    npx ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]\n` +
         "\n" +
         "  Option 2 — Continue without authentication (audit logging only):\n" +
         `    npx ${binName} configure --audit-only\n` +

package/dist/dev.js

@@ -396,7 +396,7 @@ function buildLocalOryEnv(gatewayUrl, seed) {
         ORY_PERMISSION_NAMESPACE: seed.permissions.namespace,
         // User login — always on in local dev so the launcher demonstrates
         // the interactive PKCE login UX end-to-end every session.
-        ORY_USER_LOGIN: "1",
+        ORY_USER_LOGIN: "true",
         // Agent identity — the harness self-registers via DCR on first run
         // using the user's bearer as the initial access token. No static
         // client_credentials are seeded; explicitly clear them so a leaking

package/dist/local/manager.js

@@ -622,8 +622,17 @@ function localEnv() {
 }
 function localConfigure() {
     console.log(`Saving local Ory gateway URL to shared config...`);
-    (0, config_js_1.saveConfig)({ projectUrl: configs_js_1.GATEWAY_URL, auditOnly: false });
-    console.log(`  Project URL: ${configs_js_1.GATEWAY_URL}`);
+    // Persist the seeded user PKCE client id alongside the project URL so
+    // a subsequent `configure --project-url <hosted>` doesn't trip the
+    // require-OAuth2-client check, and the user gate resolves the right
+    // client out of the box.
+    (0, config_js_1.saveConfig)({
+        projectUrl: configs_js_1.GATEWAY_URL,
+        oauth2ClientId: seed_js_1.USER_CLIENT_ID,
+        auditOnly: false,
+    });
+    console.log(`  Project URL:      ${configs_js_1.GATEWAY_URL}`);
+    console.log(`  OAuth2 Client ID: ${seed_js_1.USER_CLIENT_ID}`);
     console.log("");
     console.log("All Ory agent plugins will now connect to the local environment.");
     console.log("This persists across sessions. Run 'configure --project-url <URL>'");
@@ -647,7 +656,7 @@ function printSeedResult(result) {
     console.log("To use with any Ory agent plugin, set these environment variables:");
     console.log("");
     console.log(`  export ORY_PROJECT_URL=${configs_js_1.GATEWAY_URL}`);
-    console.log(`  export ORY_USER_LOGIN=1`);
+    console.log(`  export ORY_USER_LOGIN=true`);
     console.log(`  export ORY_OAUTH2_CLIENT_ID=${result.user.client.clientId}`);
     console.log(`  export ORY_USER_SUBJECT_NAMESPACE=User`);
     console.log(`  export ORY_USER_SUBJECT_ID=${result.user.identity.id}`);

package/dist/local/seed.d.ts

@@ -23,6 +23,13 @@
  * Idempotent — re-running the seed reuses existing identities and
  * recreates OAuth2 clients (so the secret is always known).
  */
+/**
+ * Stable client id Hydra issues to the seeded user PKCE client. Stable
+ * so `local configure` can persist it to the shared config and downstream
+ * runs can rely on `ORY_OAUTH2_CLIENT_ID` resolution without first
+ * dragging the value out of the `local up` banner.
+ */
+export declare const USER_CLIENT_ID = "ory-user-local";
 export interface SeededIdentity {
     id: string;
     email: string;

package/dist/local/seed.js

@@ -25,7 +25,7 @@
  * recreates OAuth2 clients (so the secret is always known).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.USER_SUBJECT_NAMESPACE = void 0;
+exports.USER_SUBJECT_NAMESPACE = exports.USER_CLIENT_ID = void 0;
 exports.seedLocalEnvironment = seedLocalEnvironment;
 const auth_js_1 = require("../auth.js");
 const tool_catalog_js_1 = require("../tool-catalog.js");
@@ -38,7 +38,13 @@ const AGENT_PASSWORD = "ory-agent-local-dev-password!";
 const USER_EMAIL = "user@ory-local.dev";
 const USER_PASSWORD = "ory-user-local-dev-password!";
 const USER_CLIENT_NAME = "ory-agent-plugins-local-user";
-const USER_CLIENT_ID = "ory-user-local";
+/**
+ * Stable client id Hydra issues to the seeded user PKCE client. Stable
+ * so `local configure` can persist it to the shared config and downstream
+ * runs can rely on `ORY_OAUTH2_CLIENT_ID` resolution without first
+ * dragging the value out of the `local up` banner.
+ */
+exports.USER_CLIENT_ID = "ory-user-local";
 /**
  * Tools the dev launcher seeds tuples for. Sourced from the shared
  * per-harness catalog so a single seed grants the local user identity
@@ -193,11 +199,11 @@ async function seedLocalEnvironment(namespace = "AgentTools") {
     //    OAuth2 client is intentionally NOT pre-registered; the harness
     //    will self-register via DCR on first session start.
     process.stderr.write("  Registering user OAuth2 client (PKCE)...\n");
-    let userClient = { clientId: USER_CLIENT_ID };
+    let userClient = { clientId: exports.USER_CLIENT_ID };
     try {
         userClient = await ensureOAuth2Client({
             clientName: USER_CLIENT_NAME,
-            clientId: USER_CLIENT_ID,
+            clientId: exports.USER_CLIENT_ID,
             // Public PKCE client — no secret. Hydra accepts an empty string
             // for `token_endpoint_auth_method=none`.
             grantTypes: ["authorization_code", "refresh_token"],

package/dist/permissions-cli.js

@@ -129,12 +129,12 @@ async function runPermissionsStatus(binName, harness) {
     console.log("");
     if (resolved.auditOnly) {
         console.log("Ory is disabled (audit-only). No permission checks run.");
-        console.log(`Re-enable with: ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.log(`Re-enable with: ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         return 0;
     }
     if (!resolved.projectUrl) {
         console.log("No project URL configured — cannot probe permission coverage.");
-        console.log(`Configure first: ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.log(`Configure first: ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         return 0;
     }
     if (catalog.length === 0) {
@@ -211,12 +211,12 @@ async function runPermissionsBootstrap(binName, harness, args) {
     const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
     if (resolved.auditOnly) {
         console.error("Ory is in audit-only mode (kill-switch). Nothing to bootstrap.");
-        console.error(`Re-enable Ory: ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.error(`Re-enable Ory: ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         return 1;
     }
     if (!resolved.projectUrl) {
         console.error("No ORY_PROJECT_URL configured — cannot write permissions.");
-        console.error(`Configure first: ${binName} configure --project-url <URL> --api-key <KEY>`);
+        console.error(`Configure first: ${binName} configure --project-url <URL> --oauth2-client-id <CLIENT_ID> [--api-key <KEY>]`);
         return 1;
     }
     if (catalog.length === 0) {
@@ -235,7 +235,7 @@ async function runPermissionsBootstrap(binName, harness, args) {
         console.error("No user identity resolved — refusing to write permissions for an unknown subject.");
         console.error("");
         console.error("Either:");
-        console.error("  - run the harness once with ORY_USER_LOGIN=1 so a user token is cached, or");
+        console.error("  - run the harness once with ORY_USER_LOGIN=true so a user token is cached, or");
         console.error("  - set ORY_USER_SUBJECT_ID=<id> to target a known subject.");
         return 1;
     }

package/dist/setup.js

@@ -374,7 +374,9 @@ Environment variables:
   ORY_PROJECT_URL       Your Ory project URL (required at runtime)
   ORY_AGENT_API_KEY     Agent API key / OAuth2 bearer (preferred name;
                         ORY_API_KEY is honored as a deprecated alias)
-  ORY_USER_LOGIN        Set to "1" to enable the interactive user login
+  ORY_OAUTH2_CLIENT_ID  Public OAuth2 client id for the user PKCE flow
+                        (required when ORY_USER_LOGIN=true)
+  ORY_USER_LOGIN        Set to "true" to enable the interactive user login
   ORY_PERMISSION_MODE   "observe" (default) or "enforce" — what to do on deny
   ORY_AGENT_DEBUG       Set to "true" for debug logging
   ORY_AGENT_LOG_FILE    Path to write debug logs
@@ -392,9 +394,12 @@ function printNextSteps(harnessName, uninstallCmd) {
     console.log("     export ORY_AGENT_API_KEY=ory_pat_...");
     console.log("");
     console.log("  2. Turn on the interactive user login (opt-in):");
-    console.log("     export ORY_USER_LOGIN=1");
-    console.log(`     Without this, ${harnessName} runs without a human Ory identity attached`);
+    console.log("     export ORY_USER_LOGIN=true");
+    console.log("     export ORY_OAUTH2_CLIENT_ID=<public OAuth2 client id>");
+    console.log(`     Without these, ${harnessName} runs without a human Ory identity attached`);
     console.log("     to the session and permission checks fall back to a session:<id> subject.");
+    console.log("     The OAuth2 client id is the public client (no secret) you registered in");
+    console.log("     your Ory project with the four loopback redirect URIs.");
     console.log("");
     console.log("  3. Optionally enable debug logging:");
     console.log("     export ORY_AGENT_DEBUG=true");

package/dist/status-cli.js

@@ -57,7 +57,7 @@ function printUserIdentitySection() {
     const tokens = (0, auth_store_js_1.loadTokens)();
     console.log("");
     console.log("User identity (interactive PKCE login):");
-    console.log(`  Login:       ${loginOn ? "on (ORY_USER_LOGIN)" : "off (set ORY_USER_LOGIN=1 to enable)"}`);
+    console.log(`  Login:       ${loginOn ? "on (ORY_USER_LOGIN)" : "off (set ORY_USER_LOGIN=true to enable)"}`);
     if (!tokens) {
         console.log("  Token cache: empty");
         if (loginOn) {
@@ -209,7 +209,7 @@ async function printPermissionsSection(binName, harness) {
     }
     const hasUser = !!process.env.ORY_USER_SUBJECT_ID || isUserTokenUsable();
     if (!hasUser) {
-        console.log(`  Coverage:    n/a (no cached user identity — run with ORY_USER_LOGIN=1 once,`);
+        console.log(`  Coverage:    n/a (no cached user identity — run with ORY_USER_LOGIN=true once,`);
         console.log(`               or set ORY_USER_SUBJECT_ID to probe a known subject)`);
         return;
     }

package/dist/user-login.d.ts

@@ -18,7 +18,8 @@
  * the audit trail is complete regardless of outcome.
  *
  * The whole flow is a no-op (mode `disabled`) unless the
- * `ORY_USER_LOGIN` env var is set to `1`/`true`.
+ * `ORY_USER_LOGIN` env var is set to `true` (legacy values `1`, `yes`,
+ * `on` are still accepted for back-compat).
  *
  * This authenticates the *user* (the human at the keyboard). The
  * separate agent identity (the AI process making the calls) is resolved

package/dist/user-login.js

@@ -19,7 +19,8 @@
  * the audit trail is complete regardless of outcome.
  *
  * The whole flow is a no-op (mode `disabled`) unless the
- * `ORY_USER_LOGIN` env var is set to `1`/`true`.
+ * `ORY_USER_LOGIN` env var is set to `true` (legacy values `1`, `yes`,
+ * `on` are still accepted for back-compat).
  *
  * This authenticates the *user* (the human at the keyboard). The
  * separate agent identity (the AI process making the calls) is resolved
@@ -39,7 +40,10 @@ function isUserLoginEnabled() {
     return !!v && ENABLED_VALUES.has(v);
 }
 function clientId() {
-    return process.env.ORY_OAUTH2_CLIENT_ID;
+    // resolveConfig already merges env (ORY_OAUTH2_CLIENT_ID) with the
+    // persisted value, env winning. Centralizing here keeps the user gate,
+    // status CLI, and configure command in lockstep on resolution order.
+    return (0, config_js_1.resolveConfig)().oauth2ClientId;
 }
 function recordAuthSpan(client, decision) {
     const status = decision.mode === "ok" || decision.mode === "refreshed" || decision.mode === "env_token"
@@ -211,7 +215,9 @@ async function runUserLogin(client, options) {
             mode: "skipped",
             reason: "ORY_OAUTH2_CLIENT_ID is not set; cannot start browser login (run `npx " +
                 options.binName +
-                " configure` and register an OAuth2 client with the loopback redirect URIs)",
+                " configure --oauth2-client-id <id>` after registering a public OAuth2 client " +
+                "in your Ory project with all four loopback redirect URIs: " +
+                "http://127.0.0.1:47823..47826/callback)",
         };
     }
     // No TTY check here on purpose: PKCE only needs a browser that can reach
@@ -221,7 +227,7 @@ async function runUserLogin(client, options) {
     // complete sign-in by pasting the URL into any browser that can reach
     // 127.0.0.1. Truly unattended runs (CI=true) are short-circuited by
     // `pkceLogin` itself via `detectHeadless`, and operators can bypass
-    // login entirely with `ORY_USER_SESSION_TOKEN` or `ORY_USER_LOGIN=0`.
+    // login entirely with `ORY_USER_SESSION_TOKEN` or `ORY_USER_LOGIN=false`.
     // PKCE-flight lock so concurrent processes share a single browser flow.
     const lock = (0, auth_store_js_1.tryAcquirePkceFlightLock)();
     if (!lock) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Ory Argus: the core API for building authentication, authorization, and audit into AI agent harness plugins, extensions, and custom integrations",
   "license": "Apache-2.0",
   "homepage": "https://ory.com",