@ory/argus 0.3.0 → 0.5.0

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

@@ -0,0 +1,108 @@
+---
+name: ory-build-integration
+description: Wire an Ory Network integration into your own application using the ory/integrates template patterns. Use when the user wants to add an Ory integration to their app — an Action webhook handler that fires during a flow, a Console/gateway config to validate Ory JWTs, or an Enterprise live-event-stream consumer — phrases like "wire up an Ory webhook", "add an Ory Action handler to my app", "react to Ory identity events", "validate Ory tokens at my gateway", "build an Ory integration in my project". For contributing an integration back to ory/integrates instead, use ory-contribute-integration.
+---
+
+# Build an Ory Integration Into Your App
+
+You are helping the user wire an Ory Network integration into **their own
+application**, reusing the proven patterns from the public `ory/integrates`
+repository. There is no contribution, registry, `Maintained by:`, or DCO concern
+here — you fetch the **runnable subset** of a template and adapt it in place.
+
+This skill carries the workflow. The template files live in
+`github.com/ory/integrates` (branch `main`); fetch the ones you need so they stay
+current.
+
+> **Precondition:** `ory/integrates` must be reachable (public repo). If a fetch
+> fails, tell the user and stop — do not fabricate handler code.
+
+## Step 1 — Determine the type and app context
+
+Pick the integration type from intent; ask directly if unclear.
+
+| Signal from the user | Type |
+|---|---|
+| Transform/enrich an identity at registration; gate or react to a flow **synchronously**; call a vendor API during an Ory flow | `webhook` |
+| Validate Ory JWTs at a gateway; **Console-only** config; no handler code | `config` |
+| React to events **asynchronously**; Ory **Enterprise** Live Event Stream consumer | `http-event` |
+
+Also establish: the app's framework/runtime, where the handler will live, and how
+it's deployed (these decide where you write files and how you mount the route).
+
+## Step 2 — Fetch the runnable subset
+
+Pull only the files the user needs from `_examples/_template-<type>/`. Prefer raw
+fetch so you don't clone the whole repo into the user's project.
+
+**Raw file fetch** (base URL
+`https://raw.githubusercontent.com/ory/integrates/main/_examples/_template-<type>/`):
+
+```bash
+BASE=https://raw.githubusercontent.com/ory/integrates/main/_examples/_template-webhook
+mkdir -p ory-integration/webhook ory-integration/jsonnet
+curl -fsSL "$BASE/ory-actions.yaml"          -o ory-integration/ory-actions.yaml
+curl -fsSL "$BASE/jsonnet/identity.jsonnet"  -o ory-integration/jsonnet/identity.jsonnet
+curl -fsSL "$BASE/webhook/server.ts"         -o ory-integration/webhook/server.ts
+curl -fsSL "$BASE/webhook/package.json"      -o ory-integration/webhook/package.json
+curl -fsSL "$BASE/webhook/tsconfig.json"     -o ory-integration/webhook/tsconfig.json
+curl -fsSL "$BASE/webhook/.env.example"      -o ory-integration/webhook/.env.example
+```
+
+**Sparse checkout** (if the user prefers a git copy to diff against):
+
+```bash
+git clone --depth 1 --filter=blob:none --sparse https://github.com/ory/integrates /tmp/ory-integrates
+git -C /tmp/ory-integrates sparse-checkout set _examples/_template-webhook
+# then copy the files you want out of /tmp/ory-integrates/_examples/_template-webhook
+```
+
+Runnable subset per type (skip `registry.entry.yaml.example`, the
+`Maintained by:` README, and lockfiles — `npm install` regenerates the lock):
+
+- **webhook** — `ory-actions.yaml`, `jsonnet/identity.jsonnet`,
+  `webhook/{server.ts, package.json, tsconfig.json, .env.example}`.
+- **config** — `ory-console-steps.md` (no code; it's a Console walkthrough).
+- **http-event** — `ory-event-stream.yaml`,
+  `webhook/{server.ts, idempotency.ts, package.json, tsconfig.json, .env.example}`.
+
+Adapt the fetched handler into the user's app: integrate the route into their
+existing server if they have one, or run the `webhook/` server standalone.
+
+## Step 3 — Wire it to the user's Ory project
+
+- **webhook** — deploy the handler, then create an Ory Action pointing at it using
+  `ory-actions.yaml` as the template (set `url` to the deployed handler, set the
+  `X-Webhook-Secret` value, and the matching `ORY_WEBHOOK_SECRET` in the
+  handler's `.env`). Adjust `jsonnet/identity.jsonnet` to the body shape the
+  handler expects. Apply via the Ory Console or the Ory CLI.
+- **config** — follow `ory-console-steps.md`: configure the vendor side, then the
+  Ory Console (gateway/JWT validation, provider config, etc.). No code to deploy.
+- **http-event** (Enterprise) — deploy the handler, then configure the
+  event-stream target from `ory-event-stream.yaml` (URL with embedded Basic Auth;
+  set `BASIC_AUTH_USER` / `BASIC_AUTH_PASSWORD` in `.env` to match) and the event
+  filter. Keep the `idempotency.ts` dedupe wired up — delivery is at-least-once.
+
+Always verify the signature/secret path: webhook uses the `X-Webhook-Secret`
+header; http-event uses HTTP Basic Auth embedded in the configured URL.
+
+## Step 4 — Test locally
+
+Stand up Ory and exercise the flow locally before pointing at production:
+
+- Use {{REF_LOCAL_DEV}} to run a local Ory stack (Kratos / Keto / Hydra +
+  gateway), then trigger the relevant flow and confirm the handler fires.
+- Use {{REF_AUTH_SETUP}} when the app also needs Ory project / SDK setup wired up.
+
+For a webhook, hit `GET /health` on the handler, then run the Ory flow and check
+the handler logs. For http-event, emit a test event and confirm both the dedupe
+and the downstream side effect.
+
+## What this skill does NOT do
+
+- It does not create a contribution to `ory/integrates` (no `registry.entry.yaml`,
+  `Maintained by:`, SPDX, or DCO) — use `ory-contribute-integration` for that.
+- It does not invent handler code — it fetches the real templates from
+  `ory/integrates`.
+- It does not deploy to the user's infrastructure or modify their Ory project
+  without confirmation.

package/assets/skills/ory-contribute-integration/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: ory-contribute-integration
+description: Author a new Ory Network integration as a contribution to the public ory/integrates repository. Use when the user wants to contribute an integration back to Ory, add an entry to the Ory integrations registry/catalog, open a PR against ory/integrates, or publish a reusable integration for others — phrases like "contribute an Ory integration", "add my integration to ory/integrates", "submit a webhook integration to Ory", "get my integration into the registry". For wiring an integration into your own app instead, use ory-build-integration.
+---
+
+# Contribute an Integration to ory/integrates
+
+You are helping the user author a new integration and contribute it back to the
+public `ory/integrates` repository ("Sample code and reference configuration for
+integrating Ory Network with third-party products"). The deliverable is a pull
+request against `github.com/ory/integrates`.
+
+This skill carries the workflow. The **template files** live in the repo itself —
+fetch them from `github.com/ory/integrates` (branch `main`) rather than
+reproducing them, so they never drift.
+
+> **Precondition:** `ory/integrates` must be reachable (it is a public repo). If
+> `gh repo view ory/integrates` or a fetch of a template file fails, tell the
+> user the repo is unreachable and stop — do not fabricate template contents.
+
+## Step 0 — Open the "New integration" issue first
+
+Ory asks contributors to open a **New integration** issue before the PR, so scope
+is confirmed and the work isn't already in flight. Remind the user to do this
+(GitHub → `ory/integrates` → Issues → "New integration" template) and capture the
+issue number for the PR.
+
+## Step 1 — Get a checkout and pick the category
+
+The contribution workflow happens inside a checkout of the repo:
+
+```bash
+gh repo clone ory/integrates
+cd integrates
+```
+
+(or a fork, if the user will PR from their own remote.) Then choose the
+**category folder** the integration belongs in — it must match an existing
+top-level directory (`crm/`, `api-gateways/`, `identity-verification/`, `mfa/`,
+`enterprise-sso/`, …). List them with `ls -d */ | grep -v _examples`.
+
+## Step 2 — Determine the integration type
+
+Every integration is one of three types. Infer from intent; if unclear, ask
+directly.
+
+| Signal from the user | Type | Template |
+|---|---|---|
+| Transform/enrich an identity at registration; gate or react to a self-service flow **synchronously**; call a vendor API during an Ory flow | `webhook` | `_examples/_template-webhook/` |
+| Validate Ory JWTs at a gateway; **Console-only** setup; no handler code | `config` | `_examples/_template-config/` |
+| React to events **asynchronously**; Ory Network **Enterprise** Live Event Stream consumer | `http-event` | `_examples/_template-http-event/` |
+
+## Step 3 — Copy the template into the category folder
+
+From the repo root, copy the whole template directory to
+`<category>/<integration-slug>` (slug is lowercase, hyphenated, matches the dir
+name):
+
+```bash
+cp -R _examples/_template-webhook crm/<integration-slug>      # webhook
+# or _examples/_template-config / _examples/_template-http-event
+```
+
+Each template ships these files (confirm with `ls -R <category>/<integration-slug>`):
+
+- **webhook** — `README.md`, `ory-actions.yaml`, `jsonnet/identity.jsonnet`,
+  `registry.entry.yaml.example`, and a runnable `webhook/` (`server.ts`,
+  `package.json`, `package-lock.json`, `tsconfig.json`, `.env.example`).
+- **config** — `README.md`, `ory-console-steps.md`,
+  `registry.entry.yaml.example`.
+- **http-event** — `README.md`, `ory-event-stream.yaml`,
+  `registry.entry.yaml.example`, and a runnable `webhook/` (`server.ts`,
+  `idempotency.ts`, `package.json`, `package-lock.json`, `tsconfig.json`,
+  `.env.example`).
+
+The copied files are the source of truth — read them and fill in every
+`<placeholder>` and `<!-- comment -->`.
+
+## Step 4 — Fill out the integration
+
+1. **README.md** — replace `<Integration Name>`, set the `Maintained by:` line
+   (`Ory Engineering`, `Community contributors`, or the user's `@handle`), and
+   complete: what it does, use case, prerequisites, deploy steps, **Ory Console
+   configuration**, troubleshooting. No vendor marketing — factual wiring only.
+2. **Code / config for the type** (see per-type notes below).
+3. **registry.entry.yaml** — rename `registry.entry.yaml.example` →
+   `registry.entry.yaml` and fill in every field (`name`, `displayName`,
+   `vendor`, `category`, `type`, `maintainedBy`, `description`, `useCase`,
+   `coreFunctionality`, `oryMechanism`, `protocol`, `status`; http-event also
+   needs `subscribedEvents`). The field comments in the file enumerate the
+   allowed enum values.
+4. **Apache-2.0 SPDX header** at the top of every source file you ship, e.g.
+   `// SPDX-License-Identifier: Apache-2.0`.
+
+### webhook specifics
+- `ory-actions.yaml` is the Ory Action hook config (a `web_hook` with an
+  `X-Webhook-Secret` `api_key` auth header). Point `url` at the deployed handler
+  and set the shared secret.
+- `jsonnet/identity.jsonnet` is the request-body template — adjust to the shape
+  your handler expects.
+- The `webhook/` server must run (`cd webhook && cp .env.example .env && npm
+  install && npm start`); it exposes `GET /health` and the `POST` target.
+  `ORY_WEBHOOK_SECRET` in `.env` must match the secret in `ory-actions.yaml`.
+
+### config specifics
+- No code. Write a real `ory-console-steps.md`: vendor-side setup, the exact Ory
+  Console navigation, the fields to configure, a test, and troubleshooting. A
+  README-only contribution with no real console steps will be rejected.
+
+### http-event specifics
+- `ory-event-stream.yaml` configures the Ory-side event target (URL with embedded
+  Basic Auth) and the event filter. List the consumed events under both the YAML
+  `events:` and the registry `subscribedEvents:`.
+- The `webhook/` handler authenticates with HTTP Basic Auth, dedupes by SHA-256
+  of the body (`idempotency.ts`) because delivery is at-least-once, and always
+  returns 200. Live event streams are an **Enterprise** feature — say so in the
+  README.
+
+## Step 5 — Regenerate the registry
+
+From the repo root:
+
+```bash
+cd scripts && npm install && cd ..
+node scripts/build-registry.js
+```
+
+This rewrites the top-level `registry.yaml` from every `registry.entry.yaml`.
+Commit the regenerated `registry.yaml` along with your integration.
+
+## Step 6 — Open the PR (DCO + checklist)
+
+Walk the CONTRIBUTING checklist before opening the PR:
+
+- [ ] Integration is in the correct category folder.
+- [ ] `README.md` covers what it does, prerequisites, deploy, Console config,
+      troubleshooting, and a `Maintained by:` line.
+- [ ] Type deliverables present: webhook → `ory-actions.yaml` + `jsonnet/` +
+      runnable `webhook/`; config → real `ory-console-steps.md`; http-event →
+      `ory-event-stream.yaml` + runnable `webhook/` + `subscribedEvents`.
+- [ ] `registry.entry.yaml` filled and `registry.yaml` regenerated.
+- [ ] Apache-2.0 SPDX header in each source file.
+- [ ] **DCO sign-off on every commit** — `git commit -s`.
+
+```bash
+git checkout -b add-<integration-slug>-integration
+git add <category>/<integration-slug> registry.yaml
+git commit -s -m "Add <Integration Name> integration"
+git push -u origin add-<integration-slug>-integration
+gh pr create --repo ory/integrates --title "Add <Integration Name> integration" \
+  --body "Closes #<issue-number>. <summary>"
+```
+
+Expect review questions about Ory Network compatibility, webhook security
+(signature verification, secret handling), and README clarity.
+
+## What this skill does NOT do
+
+- It does not wire an integration into the user's own application — use
+  `ory-build-integration` for that (no registry/DCO).
+- It does not run `build-registry.js` or open the PR without confirmation; it
+  guides, the user executes.
+- It does not invent template contents — it reads the real files from
+  `ory/integrates`.

package/dist/cli.js

@@ -93,7 +93,7 @@ function runConfigureCommand(binName, args) {
         console.log("");
         console.log("Or set environment variables:");
         console.log("  export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
-        console.log("  export ORY_API_KEY=ory_pat_...");
+        console.log("  export ORY_AGENT_API_KEY=ory_pat_...");
         return;
     }
     if (auditOnly) {
@@ -122,7 +122,7 @@ function runConfigureCommand(binName, args) {
         console.log(`  API Key: (set)`);
     console.log("");
     console.log("This configuration is shared across all Ory agent plugins.");
-    console.log("Environment variables (ORY_PROJECT_URL, ORY_API_KEY) take precedence when set.");
+    console.log("Environment variables (ORY_PROJECT_URL, ORY_AGENT_API_KEY) take precedence when set.");
 }
 /**
  * Print the "Configuration:" block showing Ory project URL and API key status.
@@ -130,11 +130,14 @@ function runConfigureCommand(binName, args) {
 function printOryConfig() {
     const resolved = (0, config_js_1.resolveConfig)();
     const configPath = (0, config_js_1.getConfigPath)();
+    const namespace = process.env.ORY_PERMISSION_NAMESPACE || "AgentTools";
     console.log("Configuration:");
-    console.log(`  Config file: ${configPath}`);
-    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(`  Config file:     ${configPath}`);
+    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(`  Permission mode: ${resolved.permissionMode} [source: ${resolved.permissionModeSource}]`);
+    console.log(`  Namespace:       ${namespace}`);
 }
 /**
  * Print the "Environment:" block showing Ory-related environment variables.
@@ -143,14 +146,37 @@ function printEnvironment() {
     console.log("");
     console.log("Environment:");
     const vars = [
-        ["ORY_SESSION_TOKEN", process.env.ORY_SESSION_TOKEN ? "(set)" : undefined, false],
+        ["ORY_AUTH_GATE", process.env.ORY_AUTH_GATE, false],
+        [
+            "ORY_AGENT_API_KEY",
+            process.env.ORY_AGENT_API_KEY ? "(set)" : undefined,
+            false,
+        ],
+        ["ORY_AGENT_CLIENT_ID", process.env.ORY_AGENT_CLIENT_ID, false],
+        [
+            "ORY_USER_SESSION_TOKEN",
+            process.env.ORY_USER_SESSION_TOKEN ? "(set)" : undefined,
+            false,
+        ],
+        ["ORY_USER_SUBJECT_ID", process.env.ORY_USER_SUBJECT_ID, false],
         ["ORY_AGENT_SUBJECT_ID", process.env.ORY_AGENT_SUBJECT_ID, false],
         ["ORY_AGENT_DEBUG", process.env.ORY_AGENT_DEBUG, false],
         ["ORY_AGENT_LOG_FILE", process.env.ORY_AGENT_LOG_FILE, false],
         ["ORY_AGENT_TRACE_FILE", process.env.ORY_AGENT_TRACE_FILE, false],
     ];
+    if (process.env.ORY_API_KEY && !process.env.ORY_AGENT_API_KEY) {
+        vars.splice(2, 0, [
+            "ORY_API_KEY",
+            "(set, DEPRECATED — use ORY_AGENT_API_KEY)",
+            false,
+        ]);
+    }
     for (const [name, value, required] of vars) {
-        const display = value ? `${value}` : required ? "NOT SET (required)" : "not set";
+        const display = value
+            ? value
+            : required
+                ? "NOT SET (required)"
+                : "not set";
         const icon = value ? "+" : required ? "!" : "-";
         console.log(`  [${icon}] ${name}: ${display}`);
     }
@@ -188,7 +214,7 @@ function printEnvHelp(binName) {
     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_API_KEY=ory_pat_...");
+    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.");
 }
@@ -355,7 +381,7 @@ async function interactiveConfigPrompt(binName) {
         "",
         "You can also set environment variables (requires session restart):",
         "  export ORY_PROJECT_URL=https://your-project.projects.oryapis.com",
-        "  export ORY_API_KEY=ory_pat_...",
+        "  export ORY_AGENT_API_KEY=ory_pat_...",
         "",
     ].join("\n");
     process.stderr.write(message + "\n");

package/dist/config.js

@@ -323,7 +323,10 @@ function writeConfigAtomic(config) {
 function resolveConfig() {
     const file = loadConfig();
     const envProjectUrl = process.env.ORY_PROJECT_URL;
-    const envApiKey = process.env.ORY_API_KEY;
+    // ORY_AGENT_API_KEY is the documented name; ORY_API_KEY is the deprecated
+    // 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 envMode = parsePermissionMode(process.env.ORY_PERMISSION_MODE);
     const permissionMode = envMode ?? file.permissionMode ?? "observe";
     const permissionModeSource = envMode

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export { resolveAgentCredentials, ensureAgentIdentity, ensureSubAgentIdentity, f
 export { type SessionInfo, type OAuth2TokenInfo, type PermissionCheck, type PermissionResult, type BatchPermissionResult, type OryError, type OryErrorCode, } from "./types.js";
 export { runConfigureCommand, runAgentCommand, printOryConfig, printEnvironment, printLogTail, printEnvHelp, printTraceTail, runWatchCommand, isTtyAvailable, promptOnTty, promptForProjectUrl, interactiveConfigPrompt, } from "./cli.js";
 export { runPermissionsCommand, isUserIdentityCached, maybeAutoBootstrap, printPermissionsOnboardingHelp, } from "./permissions-cli.js";
+export { runStatusCommand, printUserIdentitySection, printAgentIdentitySection, printPermissionsSection, type StatusCommandOptions, } from "./status-cli.js";
 export { parseSetupArgs, readJsonFile, writeJsonFile, isOryHookCommand, resolveHookCommand, matcherHookEntry, mergeMatcherHooks, removeMatcherHooks, flatHookEntry, mergeFlatHooks, removeFlatHooks, printSetupHelp, printNextSteps, resolveMcpServerCommand, mcpServerEntry, mergeMcpServer, removeMcpServer, registerPlugin, unregisterPlugin, type SetupArgs, type HookCommand, type MatcherEntry, } from "./setup.js";
 export { runDevLauncher, type DevLauncherConfig, type InstallContext, } from "./dev.js";
 export { renderOrySkills, renderOryCommands, commandToSkill, commandToToml, commandToFrontmatterMarkdown, commandToPlainMarkdown, toSkillMarkdown, writeSkillTree, removeSkillDirs, ORY_SKILL_NAMES, ORY_COMMAND_SKILL_NAMES, ORY_COMMAND_SLUGS, type RenderedSkill, type RenderedCommand, type RenderProfileOptions, } from "./skills.js";

package/dist/index.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.printOryConfig = exports.runAgentCommand = exports.runConfigureCommand = exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = exports.clearSubAgentDynamicCredentials = exports.saveSubAgentDynamicCredentials = exports.loadSubAgentDynamicCredentials = exports.clearAgentDynamicCredentials = exports.saveAgentDynamicCredentials = exports.loadAgentDynamicCredentials = exports.registerAgentClient = exports.fetchClientCredentialsToken = exports.ensureSubAgentIdentity = exports.ensureAgentIdentity = exports.resolveAgentCredentials = exports.ensureAuthenticated = exports.ensureUserAuthenticated = exports.TOKEN_EXPIRY_SKEW_SEC = exports.waitForPeerTokensSync = exports.waitForPeerTokens = exports.clearPkceFlightLock = exports.tryAcquirePkceFlightLock = exports.refreshAndSave = exports.isExpired = exports.clearTokens = exports.saveTokens = exports.loadTokens = exports.DEFAULT_LOGIN_TIMEOUT_MS = exports.LOOPBACK_PORTS = exports.buildAuthorizeUrl = exports.sha256Base64Url = exports.generateCodeVerifier = exports.detectHeadless = exports.refreshAccessToken = exports.pkceLogin = exports.getHarnessDataDir = exports.getDataDir = exports.getConfigPath = exports.mutateConfig = exports.resolveConfig = exports.saveConfig = exports.loadConfig = exports.watchTraceFile = exports.formatSpan = exports.deriveTraceId = exports.ActiveSpan = exports.Tracer = exports.redactLogData = exports.DebugLogger = exports.OryAgentClient = void 0;
-exports.runRegistryCommand = exports.DEV_JAEGER_CONTAINER = exports.stopDevJaeger = exports.ensureDevJaeger = exports.runLocalCommand = exports.ORY_COMMAND_SLUGS = exports.ORY_COMMAND_SKILL_NAMES = exports.ORY_SKILL_NAMES = exports.removeSkillDirs = exports.writeSkillTree = exports.toSkillMarkdown = exports.commandToPlainMarkdown = exports.commandToFrontmatterMarkdown = exports.commandToToml = exports.commandToSkill = exports.renderOryCommands = exports.renderOrySkills = exports.runDevLauncher = exports.unregisterPlugin = exports.registerPlugin = exports.removeMcpServer = exports.mergeMcpServer = exports.mcpServerEntry = exports.resolveMcpServerCommand = exports.printNextSteps = exports.printSetupHelp = exports.removeFlatHooks = exports.mergeFlatHooks = exports.flatHookEntry = exports.removeMatcherHooks = exports.mergeMatcherHooks = exports.matcherHookEntry = exports.resolveHookCommand = exports.isOryHookCommand = exports.writeJsonFile = exports.readJsonFile = exports.parseSetupArgs = exports.printPermissionsOnboardingHelp = exports.maybeAutoBootstrap = exports.isUserIdentityCached = exports.runPermissionsCommand = exports.interactiveConfigPrompt = exports.promptForProjectUrl = exports.promptOnTty = exports.isTtyAvailable = exports.runWatchCommand = exports.printTraceTail = exports.printEnvHelp = exports.printLogTail = exports.printEnvironment = void 0;
-exports.parseKeyValueList = exports.otlpExporterFromEnv = exports.OtlpHttpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.applyPermissionMode = exports.checkAndDecide = void 0;
+exports.runLocalCommand = exports.ORY_COMMAND_SLUGS = exports.ORY_COMMAND_SKILL_NAMES = exports.ORY_SKILL_NAMES = exports.removeSkillDirs = exports.writeSkillTree = exports.toSkillMarkdown = exports.commandToPlainMarkdown = exports.commandToFrontmatterMarkdown = exports.commandToToml = exports.commandToSkill = exports.renderOryCommands = exports.renderOrySkills = exports.runDevLauncher = exports.unregisterPlugin = exports.registerPlugin = exports.removeMcpServer = exports.mergeMcpServer = exports.mcpServerEntry = exports.resolveMcpServerCommand = exports.printNextSteps = exports.printSetupHelp = exports.removeFlatHooks = exports.mergeFlatHooks = exports.flatHookEntry = exports.removeMatcherHooks = exports.mergeMatcherHooks = exports.matcherHookEntry = exports.resolveHookCommand = exports.isOryHookCommand = exports.writeJsonFile = exports.readJsonFile = exports.parseSetupArgs = exports.printPermissionsSection = exports.printAgentIdentitySection = exports.printUserIdentitySection = exports.runStatusCommand = exports.printPermissionsOnboardingHelp = exports.maybeAutoBootstrap = exports.isUserIdentityCached = exports.runPermissionsCommand = exports.interactiveConfigPrompt = exports.promptForProjectUrl = exports.promptOnTty = exports.isTtyAvailable = exports.runWatchCommand = exports.printTraceTail = exports.printEnvHelp = exports.printLogTail = exports.printEnvironment = void 0;
+exports.parseKeyValueList = exports.otlpExporterFromEnv = exports.OtlpHttpExporter = exports.summarizeToolOutput = exports.summarizeToolInput = exports.OryDenialError = exports.alertAttributes = exports.formatAlertSummary = exports.formatAlertMessage = exports.formatDenialSummary = exports.formatDenialMessage = exports.subjectLabel = exports.resolveUserSubject = exports.checkMcpPermission = exports.parseMcpToolGeneric = exports.parseGeminiMcpTool = exports.parseClaudeCodeMcpTool = exports.getToolCatalog = exports.ALL_TOOLS = exports.KNOWN_HARNESSES = exports.HARNESS_TOOL_CATALOG = exports.applyPermissionMode = exports.checkAndDecide = exports.runRegistryCommand = exports.DEV_JAEGER_CONTAINER = exports.stopDevJaeger = exports.ensureDevJaeger = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "OryAgentClient", { enumerable: true, get: function () { return client_js_1.OryAgentClient; } });
 var logger_js_1 = require("./logger.js");
@@ -76,6 +76,11 @@ Object.defineProperty(exports, "runPermissionsCommand", { enumerable: true, get:
 Object.defineProperty(exports, "isUserIdentityCached", { enumerable: true, get: function () { return permissions_cli_js_1.isUserIdentityCached; } });
 Object.defineProperty(exports, "maybeAutoBootstrap", { enumerable: true, get: function () { return permissions_cli_js_1.maybeAutoBootstrap; } });
 Object.defineProperty(exports, "printPermissionsOnboardingHelp", { enumerable: true, get: function () { return permissions_cli_js_1.printPermissionsOnboardingHelp; } });
+var status_cli_js_1 = require("./status-cli.js");
+Object.defineProperty(exports, "runStatusCommand", { enumerable: true, get: function () { return status_cli_js_1.runStatusCommand; } });
+Object.defineProperty(exports, "printUserIdentitySection", { enumerable: true, get: function () { return status_cli_js_1.printUserIdentitySection; } });
+Object.defineProperty(exports, "printAgentIdentitySection", { enumerable: true, get: function () { return status_cli_js_1.printAgentIdentitySection; } });
+Object.defineProperty(exports, "printPermissionsSection", { enumerable: true, get: function () { return status_cli_js_1.printPermissionsSection; } });
 var setup_js_1 = require("./setup.js");
 Object.defineProperty(exports, "parseSetupArgs", { enumerable: true, get: function () { return setup_js_1.parseSetupArgs; } });
 Object.defineProperty(exports, "readJsonFile", { enumerable: true, get: function () { return setup_js_1.readJsonFile; } });

package/dist/setup.js

@@ -372,8 +372,10 @@ Options:
 
 Environment variables:
   ORY_PROJECT_URL       Your Ory project URL (required at runtime)
-  ORY_API_KEY           Ory API key (required at runtime)
-  ORY_SESSION_TOKEN     Session token for agent authentication
+  ORY_AGENT_API_KEY     Agent API key / OAuth2 bearer (preferred name;
+                        ORY_API_KEY is honored as a deprecated alias)
+  ORY_AUTH_GATE         Set to "1" to enable the interactive user login gate
+  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
   ORY_AGENT_SUBJECT_ID  Override the subject ID for permission checks
@@ -387,12 +389,17 @@ function printNextSteps(harnessName, uninstallCmd) {
     console.log("Next steps:");
     console.log("  1. Set required environment variables:");
     console.log("     export ORY_PROJECT_URL=https://your-project.projects.oryapis.com");
-    console.log("     export ORY_API_KEY=ory_pat_...");
+    console.log("     export ORY_AGENT_API_KEY=ory_pat_...");
     console.log("");
-    console.log("  2. Optionally enable debug logging:");
+    console.log("  2. Turn on the interactive user login gate (opt-in):");
+    console.log("     export ORY_AUTH_GATE=1");
+    console.log(`     Without this, ${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("");
+    console.log("  3. Optionally enable debug logging:");
     console.log("     export ORY_AGENT_DEBUG=true");
     console.log("");
-    console.log(`  3. Start ${harnessName} in your project directory.`);
+    console.log(`  4. Start ${harnessName} in your project directory.`);
     console.log("");
     console.log(`To uninstall: ${uninstallCmd}`);
 }

package/dist/skills.d.ts

@@ -1,7 +1,8 @@
 /**
  * Canonical Ory agent skills and commands.
  *
- * The skill playbooks (auth-setup, login-flow, social-login, local-dev) and the
+ * The skill playbooks (auth-setup, login-flow, social-login, local-dev,
+ * permissions-onboarding, contribute-integration, build-integration) and the
  * local-stack commands (local-up, local-down) live once, as token-bearing
  * templates under `packages/core/assets/`. Every harness plugin renders them
  * through {@link renderOrySkills} / {@link renderOryCommands}, substituting the
@@ -50,7 +51,7 @@ export interface RenderProfileOptions {
     packageName: string;
 }
 /**
- * Render the four guide skills for a harness as `SKILL.md` documents.
+ * Render the guide skills for a harness as `SKILL.md` documents.
  */
 export declare function renderOrySkills(harness: string, opts: RenderProfileOptions): RenderedSkill[];
 /**

package/dist/skills.js

@@ -2,7 +2,8 @@
 /**
  * Canonical Ory agent skills and commands.
  *
- * The skill playbooks (auth-setup, login-flow, social-login, local-dev) and the
+ * The skill playbooks (auth-setup, login-flow, social-login, local-dev,
+ * permissions-onboarding, contribute-integration, build-integration) and the
  * local-stack commands (local-up, local-down) live once, as token-bearing
  * templates under `packages/core/assets/`. Every harness plugin renders them
  * through {@link renderOrySkills} / {@link renderOryCommands}, substituting the
@@ -70,6 +71,16 @@ const SKILL_SOURCES = [
         name: "ory-permissions-onboarding",
         file: "skills/permissions-onboarding/SKILL.md",
     },
+    {
+        id: "contribute-integration",
+        name: "ory-contribute-integration",
+        file: "skills/ory-contribute-integration/SKILL.md",
+    },
+    {
+        id: "build-integration",
+        name: "ory-build-integration",
+        file: "skills/ory-build-integration/SKILL.md",
+    },
 ];
 const COMMAND_SOURCES = [
     {
@@ -177,7 +188,7 @@ function parseFrontmatter(markdown) {
 }
 // ─── Public render API ──────────────────────────────────────────────
 /**
- * Render the four guide skills for a harness as `SKILL.md` documents.
+ * Render the guide skills for a harness as `SKILL.md` documents.
  */
 function renderOrySkills(harness, opts) {
     const profile = buildProfile(harness, opts);

package/dist/status-cli.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Render the "User identity" block. Shows the `ORY_AUTH_GATE` state and,
+ * when a PKCE token is cached, the resolved subject and expiry.
+ */
+export declare function printUserIdentitySection(): void;
+/**
+ * Render the "Agent identity" block. Summarizes the resolved machine
+ * credential — static env override, persisted DCR, or unconfigured.
+ */
+export declare function printAgentIdentitySection(): void;
+/**
+ * Render the "Permissions" block. Always prints the configured mode and
+ * namespace; runs a network probe of the harness's built-in tool catalog
+ * only when a project URL is configured *and* a user identity is
+ * available (cached PKCE tokens or `ORY_USER_SUBJECT_ID`).
+ */
+export declare function printPermissionsSection(binName: string, harness: string): Promise<void>;
+export interface StatusCommandOptions {
+    /** Display title — typically the harness's human-friendly name, e.g. "Claude Code". */
+    title: string;
+    /**
+     * Optional renderer for the "Hooks & plugin" section. Each harness owns
+     * the layout for its plugin-specific registration data (extension dir,
+     * marketplace plugin ID, hook script path, etc.).
+     */
+    printPluginSection?: () => void;
+}
+/**
+ * Compose the unified `status` output for a plugin CLI. Sections render
+ * in this order: title → configuration → user identity → agent identity
+ * → permissions → hooks & plugin → environment → recent log tail.
+ *
+ * Each section degrades gracefully — missing project URL, audit-only
+ * mode, and empty token caches all surface as inline "n/a" lines rather
+ * than aborting the command.
+ */
+export declare function runStatusCommand(binName: string, harness: string, options: StatusCommandOptions): Promise<void>;

package/dist/status-cli.js

@@ -0,0 +1,285 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printUserIdentitySection = printUserIdentitySection;
+exports.printAgentIdentitySection = printAgentIdentitySection;
+exports.printPermissionsSection = printPermissionsSection;
+exports.runStatusCommand = runStatusCommand;
+/**
+ * Unified `status` CLI implementation. Each harness's `cli/main.ts` `status`
+ * subcommand delegates here so onboarding readers see configuration, user
+ * identity, agent identity, permissions, and the harness-specific plugin
+ * registration block in a single pass.
+ *
+ * The drill-down commands (`agent status`, `permissions status`) remain
+ * unchanged — this composes their inputs without altering their output.
+ */
+const config_js_1 = require("./config.js");
+const auth_store_js_1 = require("./auth-store.js");
+const agent_auth_js_1 = require("./agent-auth.js");
+const client_js_1 = require("./client.js");
+const agent_auth_js_2 = require("./agent-auth.js");
+const subject_js_1 = require("./subject.js");
+const tool_catalog_js_1 = require("./tool-catalog.js");
+const cli_js_1 = require("./cli.js");
+function resolveNamespace() {
+    return process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+}
+const AUTH_GATE_ENABLED = new Set(["1", "true", "yes", "on"]);
+function isAuthGateOn() {
+    const v = process.env.ORY_AUTH_GATE?.toLowerCase();
+    return !!v && AUTH_GATE_ENABLED.has(v);
+}
+/**
+ * Format a relative duration like "4h 32m" or "12s" for a future deadline.
+ * Returns "expired" when the deadline has already passed.
+ */
+function formatExpiresIn(expiresAtSec, nowMs = Date.now()) {
+    const remaining = expiresAtSec - Math.floor(nowMs / 1000);
+    if (remaining <= 0)
+        return "expired";
+    const days = Math.floor(remaining / 86400);
+    const hours = Math.floor((remaining % 86400) / 3600);
+    const minutes = Math.floor((remaining % 3600) / 60);
+    if (days > 0)
+        return `${days}d ${hours}h`;
+    if (hours > 0)
+        return `${hours}h ${minutes}m`;
+    if (minutes > 0)
+        return `${minutes}m`;
+    return `${remaining}s`;
+}
+/**
+ * Render the "User identity" block. Shows the `ORY_AUTH_GATE` state and,
+ * when a PKCE token is cached, the resolved subject and expiry.
+ */
+function printUserIdentitySection() {
+    const gateOn = isAuthGateOn();
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    console.log("");
+    console.log("User identity (interactive PKCE login):");
+    console.log(`  Gate:        ${gateOn ? "on (ORY_AUTH_GATE)" : "off (set ORY_AUTH_GATE=1 to enable)"}`);
+    if (!tokens) {
+        console.log("  Token cache: empty");
+        if (gateOn) {
+            console.log("  Subject:     (will resolve at next session start)");
+        }
+        else {
+            console.log("  Subject:     (gate disabled — no PKCE login will run)");
+        }
+        return;
+    }
+    const expired = (0, auth_store_js_1.isExpired)(tokens);
+    if (expired) {
+        console.log(`  Token cache: stale (${formatExpiresIn(tokens.expiresAt)}) — will refresh on next session start`);
+    }
+    else {
+        console.log(`  Token cache: present (expires in ${formatExpiresIn(tokens.expiresAt)})`);
+    }
+    const subject = tokens.subject ? `user:${tokens.subject}` : "(no subject claim on cached token)";
+    console.log(`  Subject:     ${subject}`);
+    if (tokens.clientId) {
+        console.log(`  Client ID:   ${tokens.clientId}`);
+    }
+}
+/**
+ * Render the "Agent identity" block. Summarizes the resolved machine
+ * credential — static env override, persisted DCR, or unconfigured.
+ */
+function printAgentIdentitySection() {
+    console.log("");
+    console.log("Agent identity (non-interactive):");
+    // Static overrides take precedence — surface them so the reader knows
+    // why DCR isn't running.
+    if (process.env.ORY_AGENT_API_KEY) {
+        console.log("  Source:      static API key (ORY_AGENT_API_KEY)");
+        if (process.env.ORY_AGENT_SUBJECT_ID) {
+            console.log(`  Subject:     ${process.env.ORY_AGENT_SUBJECT_ID}`);
+        }
+        return;
+    }
+    if (process.env.ORY_AGENT_CLIENT_ID && process.env.ORY_AGENT_CLIENT_SECRET) {
+        console.log("  Source:      static client_credentials (ORY_AGENT_CLIENT_ID/SECRET)");
+        console.log(`  Client ID:   ${process.env.ORY_AGENT_CLIENT_ID}`);
+        const subject = process.env.ORY_AGENT_SUBJECT_ID ?? process.env.ORY_AGENT_CLIENT_ID;
+        console.log(`  Subject:     ${subject}`);
+        return;
+    }
+    const persisted = (0, agent_auth_js_1.loadAgentDynamicCredentials)();
+    if (!persisted) {
+        console.log("  Source:      not registered yet");
+        console.log("  Status:      first session start will register an OAuth2 client (RFC 7591)");
+        return;
+    }
+    const resolved = (0, config_js_1.resolveConfig)();
+    const mismatched = resolved.projectUrl && persisted.projectUrl !== resolved.projectUrl;
+    console.log("  Source:      OAuth2 Dynamic Client Registration (RFC 7591)");
+    console.log(`  Status:      registered`);
+    console.log(`  Client ID:   ${persisted.clientId}`);
+    const subject = process.env.ORY_AGENT_SUBJECT_ID ?? persisted.clientId;
+    console.log(`  Subject:     ${subject}`);
+    console.log(`  Registered:  ${new Date(persisted.registeredAt * 1000).toISOString()}`);
+    if (mismatched) {
+        console.log(`  Warning:     registered against ${persisted.projectUrl}, but current project URL is ${resolved.projectUrl}`);
+        console.log("               run `agent unregister` to clear stale credentials");
+    }
+}
+async function probePermissionsCoverage(harness) {
+    const resolved = (0, config_js_1.resolveConfig)();
+    if (!resolved.projectUrl)
+        return undefined;
+    const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
+    if (catalog.length === 0)
+        return undefined;
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    const subjectOverride = process.env.ORY_USER_SUBJECT_ID;
+    if (!subjectOverride && (!tokens || (0, auth_store_js_1.isExpired)(tokens))) {
+        return undefined;
+    }
+    const client = client_js_1.OryAgentClient.fromEnv(harness);
+    if (tokens && !(0, auth_store_js_1.isExpired)(tokens)) {
+        client.setUserPrincipal({
+            subject: tokens.subject,
+            token: tokens.accessToken,
+        });
+    }
+    await (0, agent_auth_js_2.ensureAgentIdentity)(client, { projectUrl: resolved.projectUrl }).catch(() => {
+        /* best-effort; the probe still runs with whatever credentials we have */
+    });
+    const subject = (0, subject_js_1.resolveUserSubject)(client);
+    const subjectId = (0, subject_js_1.subjectLabel)(subject);
+    if (subjectId === "agent:unknown")
+        return undefined;
+    const namespace = resolveNamespace();
+    const result = {
+        total: catalog.length,
+        allowed: 0,
+        denied: 0,
+        errored: 0,
+    };
+    for (const tool of catalog) {
+        const check = {
+            namespace,
+            object: tool,
+            relation: "use",
+            ...subject,
+        };
+        try {
+            const probe = await client.checkPermission(check, {
+                spanAttributes: { toolName: tool, source: "status_coverage" },
+            });
+            if (probe.allowed)
+                result.allowed++;
+            else
+                result.denied++;
+        }
+        catch (err) {
+            const ory = err;
+            result.errored++;
+            result.errorCode = result.errorCode ?? ory.code ?? "unknown";
+        }
+    }
+    return result;
+}
+/**
+ * Render the "Permissions" block. Always prints the configured mode and
+ * namespace; runs a network probe of the harness's built-in tool catalog
+ * only when a project URL is configured *and* a user identity is
+ * available (cached PKCE tokens or `ORY_USER_SUBJECT_ID`).
+ */
+async function printPermissionsSection(binName, harness) {
+    const resolved = (0, config_js_1.resolveConfig)();
+    const namespace = resolveNamespace();
+    const catalog = (0, tool_catalog_js_1.getToolCatalog)(harness);
+    console.log("");
+    console.log("Permissions:");
+    console.log(`  Mode:        ${resolved.permissionMode}${formatModeSuffix(resolved.permissionModeSource)}`);
+    console.log(`  Namespace:   ${namespace}`);
+    if (resolved.auditOnly) {
+        console.log("  Coverage:    n/a (audit-only mode — Ory checks disabled)");
+        return;
+    }
+    if (!resolved.projectUrl) {
+        console.log("  Coverage:    n/a (no project URL configured)");
+        return;
+    }
+    if (catalog.length === 0) {
+        console.log(`  Coverage:    n/a (no built-in catalog for harness "${harness}")`);
+        console.log(`               known harnesses: ${tool_catalog_js_1.KNOWN_HARNESSES.join(", ")}`);
+        return;
+    }
+    const hasUser = !!process.env.ORY_USER_SUBJECT_ID || isUserTokenUsable();
+    if (!hasUser) {
+        console.log(`  Coverage:    n/a (no cached user identity — run with ORY_AUTH_GATE=1 once,`);
+        console.log(`               or set ORY_USER_SUBJECT_ID to probe a known subject)`);
+        return;
+    }
+    process.stdout.write("  Coverage:    checking…\r");
+    const probe = await probePermissionsCoverage(harness);
+    // Clear the "checking…" line by overwriting it.
+    process.stdout.write(" ".repeat(40) + "\r");
+    if (!probe) {
+        console.log("  Coverage:    unavailable (no user identity could be resolved)");
+        return;
+    }
+    const { total, allowed, denied, errored } = probe;
+    if (errored > 0 && allowed === 0 && denied === 0) {
+        console.log(`  Coverage:    probe failed (${probe.errorCode ?? "unknown"})`);
+        return;
+    }
+    const status = allowed === total
+        ? `bootstrapped (${allowed}/${total} built-in tools)`
+        : allowed === 0
+            ? `not bootstrapped (0/${total} built-in tools)`
+            : `partial (${allowed}/${total} built-in tools allowed)`;
+    console.log(`  Coverage:    ${status}`);
+    if (denied > 0) {
+        console.log(`               run "npx ${binName} permissions bootstrap" to grant the missing tools`);
+    }
+    else if (errored > 0) {
+        console.log(`               ${errored} probe error(s) — run "npx ${binName} permissions status" for details`);
+    }
+}
+function isUserTokenUsable() {
+    const tokens = (0, auth_store_js_1.loadTokens)();
+    return !!tokens && !(0, auth_store_js_1.isExpired)(tokens);
+}
+function formatModeSuffix(source) {
+    switch (source) {
+        case "env":
+            return "  (from ORY_PERMISSION_MODE env)";
+        case "config":
+            return "  (from config — change with `permissions observe|enforce`)";
+        case "default":
+            return "  (default)";
+    }
+}
+/**
+ * Compose the unified `status` output for a plugin CLI. Sections render
+ * in this order: title → configuration → user identity → agent identity
+ * → permissions → hooks & plugin → environment → recent log tail.
+ *
+ * Each section degrades gracefully — missing project URL, audit-only
+ * mode, and empty token caches all surface as inline "n/a" lines rather
+ * than aborting the command.
+ */
+async function runStatusCommand(binName, harness, options) {
+    const heading = `Ory Agent Plugin Status (${options.title})`;
+    console.log(heading);
+    console.log("=".repeat(heading.length));
+    console.log("");
+    (0, cli_js_1.printOryConfig)();
+    printUserIdentitySection();
+    printAgentIdentitySection();
+    await printPermissionsSection(binName, harness);
+    if (options.printPluginSection) {
+        console.log("");
+        options.printPluginSection();
+    }
+    (0, cli_js_1.printEnvironment)();
+    (0, cli_js_1.printLogTail)();
+    console.log("");
+    console.log(`Drill into any section with:`);
+    console.log(`  npx ${binName} agent status`);
+    console.log(`  npx ${binName} permissions status`);
+    console.log(`  npx ${binName} configure`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/argus",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "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",
@@ -69,7 +69,7 @@
     "open": "^11.0.0"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "scripts": {
     "build": "tsc",