@ory/argus 0.14.0 → 1.0.1

package/dist/local/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEV_JAEGER_IMAGE = exports.DEV_JAEGER_CONTAINER = exports.stopDevJaeger = exports.ensureDevJaeger = exports.JAEGER_OTLP_HTTP_URL = exports.JAEGER_UI_URL = exports.JAEGER_OTLP_HTTP_PORT = exports.JAEGER_UI_PORT = exports.HYDRA_ADMIN_PORT = exports.HYDRA_PUBLIC_PORT = exports.KETO_WRITE_PORT = exports.KETO_READ_PORT = exports.KRATOS_ADMIN_PORT = exports.KRATOS_PUBLIC_PORT = exports.GATEWAY_PORT = exports.GATEWAY_URL = exports.USER_SUBJECT_NAMESPACE = exports.USER_CLIENT_ID = exports.seedLocalEnvironment = exports.waitForGateway = exports.checkAllServices = exports.ensureLocalOryStack = exports.localConfigure = exports.localEnv = exports.localReset = exports.localLogs = exports.localSeed = exports.localStatus = exports.localDown = exports.localUp = exports.runLocalCommand = void 0;
+exports.hostUrl = exports.describePortConflicts = exports.findPortConflicts = exports.isPortAvailable = exports.isLocalDockerDaemon = exports.hostFromDockerHost = exports.resolveLocalHost = exports.resolveLocalPorts = exports.DEFAULT_LOCAL_HOST = exports.PORT_OFFSET_ENV_VAR = exports.LOCAL_HOST_ENV_VAR = exports.LOCAL_PORT_SPECS = exports.LOCAL_PORT_NAMES = exports.getLocalPorts = exports.LOCAL_PORT_WARNINGS = exports.LOCAL_STACK_HOST_SOURCE = exports.LOCAL_STACK_HOST = exports.LOGIN_UI_URL = exports.LOGIN_UI_PORT = exports.CONSOLE_URL = exports.CONSOLE_PORT = exports.HYDRA_TOKEN_USER_PORT = exports.HYDRA_ADMIN_PORT = exports.HYDRA_PUBLIC_PORT = exports.KETO_WRITE_PORT = exports.KETO_READ_PORT = exports.KRATOS_ADMIN_PORT = exports.KRATOS_PUBLIC_PORT = exports.GATEWAY_PORT = exports.GATEWAY_URL = exports.USER_SUBJECT_NAMESPACE = exports.USER_CLIENT_ID = exports.seedLocalEnvironment = exports.waitForGateway = exports.checkAllServices = exports.ensureLocalOryStack = exports.localConfigure = exports.localEnv = exports.localReset = exports.localLogs = exports.localSeed = exports.localStatus = exports.localDown = exports.localUp = exports.runLocalCommand = void 0;
 var cli_js_1 = require("./cli.js");
 Object.defineProperty(exports, "runLocalCommand", { enumerable: true, get: function () { return cli_js_1.runLocalCommand; } });
 var manager_js_1 = require("./manager.js");
@@ -29,12 +29,26 @@ Object.defineProperty(exports, "KETO_READ_PORT", { enumerable: true, get: functi
 Object.defineProperty(exports, "KETO_WRITE_PORT", { enumerable: true, get: function () { return configs_js_1.KETO_WRITE_PORT; } });
 Object.defineProperty(exports, "HYDRA_PUBLIC_PORT", { enumerable: true, get: function () { return configs_js_1.HYDRA_PUBLIC_PORT; } });
 Object.defineProperty(exports, "HYDRA_ADMIN_PORT", { enumerable: true, get: function () { return configs_js_1.HYDRA_ADMIN_PORT; } });
-Object.defineProperty(exports, "JAEGER_UI_PORT", { enumerable: true, get: function () { return configs_js_1.JAEGER_UI_PORT; } });
-Object.defineProperty(exports, "JAEGER_OTLP_HTTP_PORT", { enumerable: true, get: function () { return configs_js_1.JAEGER_OTLP_HTTP_PORT; } });
-Object.defineProperty(exports, "JAEGER_UI_URL", { enumerable: true, get: function () { return configs_js_1.JAEGER_UI_URL; } });
-Object.defineProperty(exports, "JAEGER_OTLP_HTTP_URL", { enumerable: true, get: function () { return configs_js_1.JAEGER_OTLP_HTTP_URL; } });
-var jaeger_js_1 = require("./jaeger.js");
-Object.defineProperty(exports, "ensureDevJaeger", { enumerable: true, get: function () { return jaeger_js_1.ensureDevJaeger; } });
-Object.defineProperty(exports, "stopDevJaeger", { enumerable: true, get: function () { return jaeger_js_1.stopDevJaeger; } });
-Object.defineProperty(exports, "DEV_JAEGER_CONTAINER", { enumerable: true, get: function () { return jaeger_js_1.DEV_JAEGER_CONTAINER; } });
-Object.defineProperty(exports, "DEV_JAEGER_IMAGE", { enumerable: true, get: function () { return jaeger_js_1.DEV_JAEGER_IMAGE; } });
+Object.defineProperty(exports, "HYDRA_TOKEN_USER_PORT", { enumerable: true, get: function () { return configs_js_1.HYDRA_TOKEN_USER_PORT; } });
+Object.defineProperty(exports, "CONSOLE_PORT", { enumerable: true, get: function () { return configs_js_1.CONSOLE_PORT; } });
+Object.defineProperty(exports, "CONSOLE_URL", { enumerable: true, get: function () { return configs_js_1.CONSOLE_URL; } });
+Object.defineProperty(exports, "LOGIN_UI_PORT", { enumerable: true, get: function () { return configs_js_1.LOGIN_UI_PORT; } });
+Object.defineProperty(exports, "LOGIN_UI_URL", { enumerable: true, get: function () { return configs_js_1.LOGIN_UI_URL; } });
+Object.defineProperty(exports, "LOCAL_STACK_HOST", { enumerable: true, get: function () { return configs_js_1.LOCAL_STACK_HOST; } });
+Object.defineProperty(exports, "LOCAL_STACK_HOST_SOURCE", { enumerable: true, get: function () { return configs_js_1.LOCAL_STACK_HOST_SOURCE; } });
+Object.defineProperty(exports, "LOCAL_PORT_WARNINGS", { enumerable: true, get: function () { return configs_js_1.LOCAL_PORT_WARNINGS; } });
+Object.defineProperty(exports, "getLocalPorts", { enumerable: true, get: function () { return configs_js_1.getLocalPorts; } });
+var ports_js_1 = require("./ports.js");
+Object.defineProperty(exports, "LOCAL_PORT_NAMES", { enumerable: true, get: function () { return ports_js_1.LOCAL_PORT_NAMES; } });
+Object.defineProperty(exports, "LOCAL_PORT_SPECS", { enumerable: true, get: function () { return ports_js_1.LOCAL_PORT_SPECS; } });
+Object.defineProperty(exports, "LOCAL_HOST_ENV_VAR", { enumerable: true, get: function () { return ports_js_1.LOCAL_HOST_ENV_VAR; } });
+Object.defineProperty(exports, "PORT_OFFSET_ENV_VAR", { enumerable: true, get: function () { return ports_js_1.PORT_OFFSET_ENV_VAR; } });
+Object.defineProperty(exports, "DEFAULT_LOCAL_HOST", { enumerable: true, get: function () { return ports_js_1.DEFAULT_LOCAL_HOST; } });
+Object.defineProperty(exports, "resolveLocalPorts", { enumerable: true, get: function () { return ports_js_1.resolveLocalPorts; } });
+Object.defineProperty(exports, "resolveLocalHost", { enumerable: true, get: function () { return ports_js_1.resolveLocalHost; } });
+Object.defineProperty(exports, "hostFromDockerHost", { enumerable: true, get: function () { return ports_js_1.hostFromDockerHost; } });
+Object.defineProperty(exports, "isLocalDockerDaemon", { enumerable: true, get: function () { return ports_js_1.isLocalDockerDaemon; } });
+Object.defineProperty(exports, "isPortAvailable", { enumerable: true, get: function () { return ports_js_1.isPortAvailable; } });
+Object.defineProperty(exports, "findPortConflicts", { enumerable: true, get: function () { return ports_js_1.findPortConflicts; } });
+Object.defineProperty(exports, "describePortConflicts", { enumerable: true, get: function () { return ports_js_1.describePortConflicts; } });
+Object.defineProperty(exports, "hostUrl", { enumerable: true, get: function () { return ports_js_1.hostUrl; } });

package/dist/local/manager.d.ts

@@ -12,7 +12,7 @@
  * .ory-dev/registry/ owned by the local npm registry manager.
  */
 export interface EnsureLocalOryStackResult {
-    status: "already-running" | "started" | "skipped:no-docker" | "compose-failed" | "gateway-unhealthy" | "console-misconfigured";
+    status: "already-running" | "started" | "skipped:no-docker" | "port-conflict" | "compose-failed" | "gateway-unhealthy" | "console-misconfigured";
     /** Local Ory gateway URL. Set when status is `already-running` or `started`. */
     gatewayUrl?: string;
     /** Filesystem path to the compose project (for log hints). */
@@ -44,4 +44,23 @@ export declare function localSeed(): Promise<void>;
 export declare function localLogs(args: string[]): void;
 export declare function localReset(): Promise<void>;
 export declare function localEnv(): void;
+/**
+ * Point the shared config at the local Ory stack.
+ *
+ * The local stack is part of the plugin's developer-experience surface and
+ * runs perfectly well without this: `local up` starts Kratos, Hydra, Keto,
+ * and the Console regardless of what any plugin is connected to, and
+ * connecting a plugin to a hosted Ory project takes none of that away.
+ *
+ * This command is the *opt-in* extra step of also pointing the security half
+ * at the local stack, so sign-in runs against local Kratos/Hydra and permission
+ * checks use the canonical local Agent Security origin. Because that writes the
+ * connection values into the config every installed plugin shares, an existing
+ * connection is reported before it is replaced — silently repointing someone's
+ * hosted project at localhost is the kind of surprise this warns about.
+ *
+ * The Agent Security service is provided separately at
+ * ``https://agents.console.ory:8080``; when it is not running, checks and
+ * delegation recording retain their normal classified fail-open behavior.
+ */
 export declare function localConfigure(): void;

package/dist/local/manager.js

@@ -60,9 +60,11 @@ const path = __importStar(require("node:path"));
 const crypto = __importStar(require("node:crypto"));
 const node_child_process_1 = require("node:child_process");
 const configs_js_1 = require("./configs.js");
+const ports_js_1 = require("./ports.js");
 const health_js_1 = require("./health.js");
 const seed_js_1 = require("./seed.js");
 const config_js_1 = require("../config.js");
+const opl_js_1 = require("../opl.js");
 const LOCAL_DIR_NAME = ".ory-dev/ory";
 async function isGatewayHealthy(timeoutMs, url) {
     try {
@@ -179,6 +181,51 @@ function runCompose(composeArgs, localDir, opts) {
         stderr: result.stderr?.toString(),
     };
 }
+/**
+ * Does this compose project have containers (running or stopped)? Used to
+ * decide whether a port probe means anything — our own containers hold the
+ * stack's ports legitimately, so probing with them present reports the stack
+ * as conflicting with itself.
+ *
+ * Note the compose project name is fixed (`ory-local`), so this also answers
+ * "yes" for a stack brought up from a *different* directory. That is the right
+ * answer for the preflight anyway — that stack is this stack, and `up` will
+ * reconcile it onto the current ports rather than collide with it.
+ *
+ * Treated as "yes, containers exist" on any failure: skipping the preflight is
+ * the safe direction, since the failure path still diagnoses a real conflict
+ * after `docker compose up` reports one.
+ */
+function composeProjectHasContainers(localDir) {
+    if (!fs.existsSync(path.join(localDir, "docker-compose.yml")))
+        return false;
+    try {
+        const result = runCompose(["ps", "-aq"], localDir, { stdio: "pipe" });
+        if (result.status !== 0)
+            return true;
+        return (result.stdout ?? "").trim().length > 0;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Render the port-conflict report, or `undefined` when there is nothing to
+ * report.
+ *
+ * Returns nothing for a remote Docker daemon (the stack's ports are published
+ * on *that* host, so probing this machine's sockets would answer a question
+ * nobody asked) or when probing is switched off entirely — see
+ * `ORY_LOCAL_SKIP_PORT_CHECK`.
+ */
+async function describeStartupPortConflicts() {
+    if ((0, ports_js_1.portCheckDisabled)() || !(0, ports_js_1.isLocalDockerDaemon)())
+        return undefined;
+    const conflicts = await (0, ports_js_1.findPortConflicts)((0, configs_js_1.getLocalPorts)());
+    if (conflicts.length === 0)
+        return undefined;
+    return (0, ports_js_1.describePortConflicts)(conflicts);
+}
 /**
  * Dump captured output from a failing piped command to stderr so the user
  * can see the underlying error. In non-piped mode, the output already
@@ -203,11 +250,11 @@ function dumpCapturedOutput(label, result) {
  * `writeConfigs` writes these and `configFingerprint` hashes them, so the
  * on-disk stack and its change-detection signal never drift.
  */
-function renderConfigs(projectRoot, consoleCfg) {
-    return [
+function renderConfigs(projectRoot, consoleCfg, oathkeeperCfg) {
+    const configs = [
         {
             relPath: "docker-compose.yml",
-            content: (0, configs_js_1.dockerComposeYaml)(projectRoot, consoleCfg),
+            content: (0, configs_js_1.dockerComposeYaml)(projectRoot, consoleCfg, oathkeeperCfg),
         },
         { relPath: "kratos/kratos.yml", content: (0, configs_js_1.kratosConfigYaml)() },
         {
@@ -215,10 +262,20 @@ function renderConfigs(projectRoot, consoleCfg) {
             content: (0, configs_js_1.kratosIdentitySchema)(),
         },
         { relPath: "keto/keto.yml", content: (0, configs_js_1.ketoConfigYaml)() },
+        // OPL namespace definitions referenced by keto.yml's `namespaces.location`.
+        // Defines the block-aware `access` permit on both the AgentTool and
+        // ShellTool namespaces (buildAgentSecurityOpl emits both).
+        { relPath: "keto/namespaces.keto.ts", content: (0, opl_js_1.buildAgentSecurityOpl)() },
         { relPath: "hydra/hydra.yml", content: (0, configs_js_1.hydraConfigYaml)() },
-        // nginx config is always emitted — the gateway is no longer optional.
-        { relPath: "nginx/nginx.conf", content: (0, configs_js_1.nginxConf)() },
+        // nginx config is always emitted — the gateway is no longer optional. Its
+        // /user/* routing depends on whether Oathkeeper fronts that path.
+        { relPath: "nginx/nginx.conf", content: (0, configs_js_1.nginxConf)(oathkeeperCfg.enabled) },
     ];
+    // Oathkeeper config is only materialized when the /user override is enabled.
+    if (oathkeeperCfg.enabled) {
+        configs.push({ relPath: "oathkeeper/oathkeeper.yml", content: (0, configs_js_1.oathkeeperConfigYaml)() }, { relPath: "oathkeeper/access-rules.yml", content: (0, configs_js_1.oathkeeperAccessRulesYaml)() });
+    }
+    return configs;
 }
 /**
  * Stable content hash of the rendered config set. Used to decide whether an
@@ -226,9 +283,9 @@ function renderConfigs(projectRoot, consoleCfg) {
  * generate; a change (e.g. the login-UI port, a service env var) invalidates
  * the fast-path short-circuit so the stack is reconciled instead of reused.
  */
-function configFingerprint(projectRoot, consoleCfg) {
+function configFingerprint(projectRoot, consoleCfg, oathkeeperCfg) {
     const hash = crypto.createHash("sha256");
-    for (const { relPath, content } of renderConfigs(projectRoot, consoleCfg)) {
+    for (const { relPath, content } of renderConfigs(projectRoot, consoleCfg, oathkeeperCfg)) {
         hash.update(relPath);
         hash.update("\0");
         hash.update(content);
@@ -257,13 +314,16 @@ function writeConfigFingerprint(localDir, fingerprint) {
         // Best-effort: a missing fingerprint only costs a reconcile next launch.
     }
 }
-function writeConfigs(localDir, projectRoot, consoleCfg) {
+function writeConfigs(localDir, projectRoot, consoleCfg, oathkeeperCfg) {
     ensureDir(localDir);
     ensureDir(path.join(localDir, "kratos"));
     ensureDir(path.join(localDir, "keto"));
     ensureDir(path.join(localDir, "hydra"));
     ensureDir(path.join(localDir, "nginx"));
-    for (const { relPath, content } of renderConfigs(projectRoot, consoleCfg)) {
+    if (oathkeeperCfg.enabled) {
+        ensureDir(path.join(localDir, "oathkeeper"));
+    }
+    for (const { relPath, content } of renderConfigs(projectRoot, consoleCfg, oathkeeperCfg)) {
         fs.writeFileSync(path.join(localDir, relPath), content);
     }
 }
@@ -289,6 +349,7 @@ async function ensureLocalOryStack(opts = {}) {
     if (cfgError) {
         return { status: "console-misconfigured", localDir, detail: cfgError };
     }
+    const oathkeeperCfg = (0, configs_js_1.getOathkeeperConfig)();
     const gatewayCfg = (0, configs_js_1.getGatewayConfig)();
     const healthUrl = `${configs_js_1.GATEWAY_URL}${gatewayCfg.healthPath}`;
     // Short-circuit if the gateway is already serving AND the running stack was
@@ -306,7 +367,7 @@ async function ensureLocalOryStack(opts = {}) {
     // source tree behind the path may have changed, which the fingerprint of the
     // generated config can't see).
     const explicitConsoleLiteOverride = (process.env.ORY_CONSOLE_LITE_PATH ?? "").trim() !== "";
-    const fingerprint = configFingerprint(projectRoot, consoleCfg);
+    const fingerprint = configFingerprint(projectRoot, consoleCfg, oathkeeperCfg);
     const configUnchanged = readConfigFingerprint(localDir) === fingerprint;
     if (!explicitConsoleLiteOverride &&
         configUnchanged &&
@@ -323,10 +384,32 @@ async function ensureLocalOryStack(opts = {}) {
             detail: "Docker is not running. Start Docker Desktop and try again.",
         };
     }
-    writeConfigs(localDir, projectRoot, consoleCfg);
+    // A typo'd port override would otherwise fall back to a default the user
+    // thinks they changed, and only show up as a collision much later.
+    for (const warning of configs_js_1.LOCAL_PORT_WARNINGS)
+        log(`  Warning: ${warning}`);
+    // Preflight, but only when the answer is trustworthy: with no containers in
+    // this compose project, every host port we want is either free or held by
+    // something that isn't us. Once containers exist they legitimately hold
+    // those ports and a probe would report the stack as conflicting with itself.
+    if (!composeProjectHasContainers(localDir)) {
+        const conflictReport = await describeStartupPortConflicts();
+        if (conflictReport) {
+            return { status: "port-conflict", localDir, detail: conflictReport };
+        }
+    }
+    writeConfigs(localDir, projectRoot, consoleCfg, oathkeeperCfg);
     log("  Config files written.");
     log("  Gateway: bundled nginx API passthrough.");
     log("  Login UI: oryd/kratos-selfservice-ui-node.");
+    if (oathkeeperCfg.enabled) {
+        log("  Oathkeeper: /user Keto read path fronted with OAuth2 token " +
+            "introspection (default; set ORY_LOCAL_OATHKEEPER=0 to disable).");
+    }
+    else {
+        log("  Oathkeeper: disabled (ORY_LOCAL_OATHKEEPER=0) — /user path is a " +
+            "transparent passthrough with no auth.");
+    }
     if (consoleCfg.enabled) {
         const sourceLabel = consoleCfg.source === "default"
             ? "default sibling checkout"
@@ -351,21 +434,20 @@ async function ensureLocalOryStack(opts = {}) {
             stdio: opts.quiet ? "pipe" : "inherit",
         });
         if (buildResult.status !== 0) {
-            // Surface the actual build error first — in dev launcher (quiet)
-            // mode the build runs piped, so without dumping the captured
-            // output the user only sees "exit N" with no clue why.
+            // Surface the actual build error first. In quiet mode the build runs
+            // piped, so otherwise the user only sees "exit N" with no clue why.
             dumpCapturedOutput("docker compose build console", buildResult);
             // Graceful fallback: a Console Lite source-tree build failure
             // shouldn't block the rest of the local stack from coming up.
             // Disable Console for this run, regenerate the compose YAML
             // without it, and continue. The rest of the stack (API gateway,
-            // login UI, Kratos/Hydra/Keto, Jaeger) is unaffected. The user
+            // login UI and Kratos/Hydra/Keto) is unaffected. The user
             // can fix the cloud repo and rerun to bring Console back.
             log(`  Warning: Ory Console Lite build failed (exit ${buildResult.status}). ` +
                 `Continuing without Console — the rest of the stack will come up. ` +
                 `Re-run the build directly to iterate: cd ${localDir} && docker compose build console`);
             consoleCfg = { enabled: false };
-            writeConfigs(localDir, projectRoot, consoleCfg);
+            writeConfigs(localDir, projectRoot, consoleCfg, oathkeeperCfg);
         }
     }
     log("  Starting services...");
@@ -374,6 +456,13 @@ async function ensureLocalOryStack(opts = {}) {
     });
     if (upResult.status !== 0) {
         dumpCapturedOutput("docker compose up", upResult);
+        // Docker's own message names a port but not the service that wanted it,
+        // and says nothing about how to move it. Probe now that we know the start
+        // failed: at this point a held port is unambiguously someone else's.
+        const conflictReport = await describeStartupPortConflicts();
+        if (conflictReport) {
+            return { status: "port-conflict", localDir, detail: conflictReport };
+        }
         return {
             status: "compose-failed",
             localDir,
@@ -394,7 +483,7 @@ async function ensureLocalOryStack(opts = {}) {
     // Record the fingerprint of the config the stack was actually brought up
     // with (consoleCfg may have fallen back to disabled above), so the next
     // launch can short-circuit only while the config is unchanged.
-    writeConfigFingerprint(localDir, configFingerprint(projectRoot, consoleCfg));
+    writeConfigFingerprint(localDir, configFingerprint(projectRoot, consoleCfg, oathkeeperCfg));
     return { status: "started", gatewayUrl: configs_js_1.GATEWAY_URL, localDir };
 }
 async function localUp(opts = {}) {
@@ -407,6 +496,12 @@ async function localUp(opts = {}) {
         case "console-misconfigured":
             console.error(`Error: ${result.detail}`);
             process.exit(1);
+        case "port-conflict":
+            // The report is already a complete, actionable message; a log hint would
+            // point at containers that were never created.
+            console.error("");
+            console.error(result.detail);
+            process.exit(1);
         case "compose-failed":
         case "gateway-unhealthy":
             console.error(`Error: ${result.detail}`);
@@ -542,7 +637,7 @@ async function localStatus() {
     }
 }
 async function localSeed() {
-    const namespace = process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTools";
+    const namespace = process.env.ORY_PERMISSION_NAMESPACE ?? "AgentTool";
     try {
         const result = await (0, seed_js_1.seedLocalEnvironment)(namespace);
         printSeedResult(result);
@@ -687,31 +782,60 @@ async function localReset() {
 function localEnv() {
     console.log("# Add these to your shell profile or .env file:");
     console.log(`export ORY_PROJECT_URL=${configs_js_1.GATEWAY_URL}`);
+    console.log(`export ORY_AGENT_SECURITY_URL=${config_js_1.LOCAL_AGENT_SECURITY_URL}`);
     console.log("export ORY_AGENT_DEBUG=true");
     console.log("");
-    console.log("# If you ran 'local seed', also set the session token:");
-    console.log("# export ORY_SESSION_TOKEN=<token from seed output>");
-    console.log("");
-    console.log("# Ship traces to the bundled Jaeger (UI: http://localhost:16686):");
-    console.log(`export OTEL_EXPORTER_OTLP_ENDPOINT=${configs_js_1.JAEGER_OTLP_HTTP_URL}`);
+    console.log("# 'local seed' registers the PKCE login client it prints:");
+    console.log("# export ORY_OAUTH2_CLIENT_ID=<client id from seed output>");
+    console.log("# (sign in with the seeded email + password when the browser opens;");
+    console.log("#  or set ORY_USER_OAUTH2_TOKEN=<access token> to skip the flow)");
 }
+/**
+ * Point the shared config at the local Ory stack.
+ *
+ * The local stack is part of the plugin's developer-experience surface and
+ * runs perfectly well without this: `local up` starts Kratos, Hydra, Keto,
+ * and the Console regardless of what any plugin is connected to, and
+ * connecting a plugin to a hosted Ory project takes none of that away.
+ *
+ * This command is the *opt-in* extra step of also pointing the security half
+ * at the local stack, so sign-in runs against local Kratos/Hydra and permission
+ * checks use the canonical local Agent Security origin. Because that writes the
+ * connection values into the config every installed plugin shares, an existing
+ * connection is reported before it is replaced — silently repointing someone's
+ * hosted project at localhost is the kind of surprise this warns about.
+ *
+ * The Agent Security service is provided separately at
+ * ``https://agents.console.ory:8080``; when it is not running, checks and
+ * delegation recording retain their normal classified fail-open behavior.
+ */
 function localConfigure() {
+    const previous = (0, config_js_1.loadConfig)();
+    const replacing = previous.projectUrl && previous.projectUrl !== configs_js_1.GATEWAY_URL ? previous.projectUrl : undefined;
+    if (replacing) {
+        console.log(`Note: this replaces the currently configured project URL (${replacing}).`);
+        console.log("      That connection is shared by every installed Ory agent plugin.");
+        console.log("");
+    }
     console.log(`Saving local Ory gateway URL to shared config...`);
-    // 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.
+    // Persist the canonical local broker origin instead of falling back to the
+    // project gateway, which does not implement Agent Security broker routes.
     (0, config_js_1.saveConfig)({
         projectUrl: configs_js_1.GATEWAY_URL,
+        agentSecurityUrl: config_js_1.LOCAL_AGENT_SECURITY_URL,
         oauth2ClientId: seed_js_1.USER_CLIENT_ID,
-        auditOnly: false,
     });
     console.log(`  Project URL:      ${configs_js_1.GATEWAY_URL}`);
+    console.log(`  Agent Security:   ${config_js_1.LOCAL_AGENT_SECURITY_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>'");
-    console.log("to switch back to a remote Ory project.");
+    console.log("Sign-in and permission checks now target the local environment.");
+    console.log(`Start local Agent Security at ${config_js_1.LOCAL_AGENT_SECURITY_URL} for broker calls.`);
+    console.log("");
+    console.log("This persists across sessions. Point at a hosted project with");
+    console.log("'configure --project-url <URL> --agent-security-url <URL>',");
+    console.log("or turn checks off");
+    console.log("with 'configure --disconnect' — the local stack keeps running either way.");
 }
 // ─── Helpers ───────────────────────────────────────────────────────
 function printSeedResult(result) {
@@ -730,6 +854,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_AGENT_SECURITY_URL=${config_js_1.LOCAL_AGENT_SECURITY_URL}`);
     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}`);
@@ -748,11 +873,9 @@ function printConnectionInfo() {
     console.log("===============");
     console.log("");
     console.log(`  Gateway URL: ${configs_js_1.GATEWAY_URL}`);
-    console.log(`  Kratos:      http://localhost:4433 (public) / http://localhost:4434 (admin)`);
-    console.log(`  Keto:        http://localhost:4466 (read) / http://localhost:4467 (write)`);
-    console.log(`  Hydra:       http://localhost:4444 (public) / http://localhost:4445 (admin)`);
-    console.log(`  Jaeger UI:   ${configs_js_1.JAEGER_UI_URL}`);
-    console.log(`  OTLP HTTP:   ${configs_js_1.JAEGER_OTLP_HTTP_URL} (set OTEL_EXPORTER_OTLP_ENDPOINT to ship traces)`);
+    console.log(`  Kratos:      ${(0, ports_js_1.hostUrl)(configs_js_1.LOCAL_STACK_HOST, configs_js_1.KRATOS_PUBLIC_PORT)} (public) / ${(0, ports_js_1.hostUrl)(configs_js_1.LOCAL_STACK_HOST, configs_js_1.KRATOS_ADMIN_PORT)} (admin)`);
+    console.log(`  Keto:        ${(0, ports_js_1.hostUrl)(configs_js_1.LOCAL_STACK_HOST, configs_js_1.KETO_READ_PORT)} (read) / ${(0, ports_js_1.hostUrl)(configs_js_1.LOCAL_STACK_HOST, configs_js_1.KETO_WRITE_PORT)} (write)`);
+    console.log(`  Hydra:       ${(0, ports_js_1.hostUrl)(configs_js_1.LOCAL_STACK_HOST, configs_js_1.HYDRA_PUBLIC_PORT)} (public) / ${(0, ports_js_1.hostUrl)(configs_js_1.LOCAL_STACK_HOST, configs_js_1.HYDRA_ADMIN_PORT)} (admin)`);
     console.log("");
     console.log("Run 'local seed' to create test data, or 'local env' to print env vars.");
 }

package/dist/local/ports.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Host-facing addressing for the local Ory stack — which ports it publishes on
+ * the host, and which host name everything else should use to reach it.
+ *
+ * Two kinds of port live in this stack, and conflating them is the bug this
+ * module exists to prevent:
+ *
+ * - **Container-internal ports** are what each service listens on *inside* the
+ *   compose network, and what one service uses to address another
+ *   (`http://kratos:4433`). They live on a private bridge network, so they can
+ *   never collide with anything on the host and there is no reason to make them
+ *   configurable. They are fixed constants below.
+ * - **Host ports** are the left-hand side of a compose `ports:` mapping — the
+ *   only ports that are actually claimed on the developer's machine, and so the
+ *   only ones that can collide. Every one of them is overridable.
+ *
+ * The defaults are the stock upstream Ory ports (4433/4434, 4444/4445,
+ * 4466/4467, …), which is deliberate — they are the ports every Ory doc and
+ * tutorial uses. It also means a developer who already runs Ory locally, which
+ * is precisely this stack's audience, collides on first run. Before #63 there
+ * was no override and no diagnosis: `docker compose up` failed with Docker's
+ * raw "port is already allocated" and the only apparent fix was to hand-edit
+ * the generated compose file, which the next `local up` regenerates away.
+ *
+ * Three levels of control, cheapest first:
+ *
+ * 1. `ORY_LOCAL_PORT_OFFSET=100` shifts *every* default by a constant, which is
+ *    the common case ("something else owns the Ory ports, move the whole
+ *    stack"). Relative spacing is preserved, so the set stays collision-free
+ *    with itself.
+ * 2. `ORY_LOCAL_<SERVICE>_PORT` pins one service exactly, and wins over the
+ *    offset.
+ * 3. `ORY_LOCAL_HOST` changes the host every generated URL advertises, for a
+ *    remote Docker daemon or an agent running inside a container. It defaults
+ *    to the host parsed out of `DOCKER_HOST` when that points somewhere other
+ *    than this machine, so the remote-daemon case usually needs no flag at all.
+ */
+export declare const KRATOS_PUBLIC_CONTAINER_PORT = 4433;
+export declare const KRATOS_ADMIN_CONTAINER_PORT = 4434;
+export declare const KETO_READ_CONTAINER_PORT = 4466;
+export declare const KETO_WRITE_CONTAINER_PORT = 4467;
+export declare const HYDRA_PUBLIC_CONTAINER_PORT = 4444;
+export declare const HYDRA_ADMIN_CONTAINER_PORT = 4445;
+export declare const HYDRA_TOKEN_USER_CONTAINER_PORT = 5555;
+export declare const GATEWAY_CONTAINER_PORT = 4000;
+export declare const LOGIN_UI_CONTAINER_PORT = 4455;
+export declare const OATHKEEPER_PROXY_CONTAINER_PORT = 4456;
+export declare const OATHKEEPER_API_CONTAINER_PORT = 4457;
+/** Console Lite's Dockerfile sets `ENV PORT=3000`. */
+export declare const CONSOLE_CONTAINER_PORT = 3000;
+/** Every host port the stack publishes, in the order `local status` lists them. */
+export declare const LOCAL_PORT_NAMES: readonly ["gateway", "console", "loginUi", "kratosPublic", "kratosAdmin", "ketoRead", "ketoWrite", "hydraPublic", "hydraAdmin", "hydraTokenUser", "oathkeeperProxy", "oathkeeperApi"];
+export type LocalPortName = (typeof LOCAL_PORT_NAMES)[number];
+export type ResolvedLocalPorts = Record<LocalPortName, number>;
+interface PortSpec {
+    /** Default host port — the stock Ory port, and the container port it maps to. */
+    default: number;
+    /** Env var that pins this port exactly. */
+    envVar: string;
+    /** Human label used in conflict messages and banners. */
+    label: string;
+}
+/**
+ * The port table. `default` doubles as the container-internal port for every
+ * service, which is what keeps the generated mapping readable
+ * (`"4433:4433"` by default, `"5433:4433"` once overridden).
+ */
+export declare const LOCAL_PORT_SPECS: Record<LocalPortName, PortSpec>;
+/** Shifts every default port by a constant. Overridden per-port by the specific var. */
+export declare const PORT_OFFSET_ENV_VAR = "ORY_LOCAL_PORT_OFFSET";
+/** Overrides the host name every generated URL advertises. */
+export declare const LOCAL_HOST_ENV_VAR = "ORY_LOCAL_HOST";
+/**
+ * Skips every port probe — the pre-start preflight *and* the post-failure
+ * diagnosis.
+ *
+ * Both open real sockets, which is the right thing before starting containers
+ * and the wrong thing in a unit test (the core suite sets this so no test
+ * depends on which ports happen to be free on the machine running it) or in a
+ * sandbox that forbids listening. The sandbox case is why this covers the
+ * diagnosis too: where binding is denied, `isPortAvailable` answers "taken" for
+ * every port, so an unrelated startup failure would otherwise be reported as a
+ * confident and completely wrong "every port is in use".
+ */
+export declare const SKIP_PORT_CHECK_ENV_VAR = "ORY_LOCAL_SKIP_PORT_CHECK";
+export declare function portCheckDisabled(env?: Env): boolean;
+type Env = Record<string, string | undefined>;
+/**
+ * Resolve every host port from the environment.
+ *
+ * Invalid values are **ignored with a warning** rather than throwing: this runs
+ * on the way into `local up`, and refusing to start because one env var has a
+ * typo would be a worse outcome than starting on the documented default and
+ * saying so. Warnings are returned rather than printed so the caller controls
+ * the output stream.
+ */
+export declare function resolveLocalPorts(env?: Env): {
+    ports: ResolvedLocalPorts;
+    warnings: string[];
+};
+export type LocalHostSource = "env" | "docker-host" | "default";
+export declare const DEFAULT_LOCAL_HOST = "localhost";
+/**
+ * Pull the host out of a `DOCKER_HOST` value.
+ *
+ * `unix://` and `npipe://` sockets are this machine, so they yield nothing and
+ * the default stands. A `tcp://` or `ssh://` daemon publishes the stack's ports
+ * on *its* host, not ours, so that host is what generated URLs have to
+ * advertise — otherwise every URL we print and persist points at a machine that
+ * isn't running the stack.
+ */
+export declare function hostFromDockerHost(dockerHost: string | undefined): string | undefined;
+export declare function isLoopbackHost(host: string): boolean;
+/**
+ * The host name every generated URL should advertise: config files, banners,
+ * the health probe, and the `projectUrl` that `local configure` persists.
+ */
+export declare function resolveLocalHost(env?: Env): {
+    host: string;
+    source: LocalHostSource;
+};
+/**
+ * True when the Docker daemon publishes ports on *this* machine, which is the
+ * only case where probing a local socket says anything about whether the stack
+ * will be able to bind. With a remote daemon the probe would test the wrong
+ * host, so callers skip the preflight entirely rather than report a conflict
+ * that isn't there (or miss one that is).
+ */
+export declare function isLocalDockerDaemon(env?: Env): boolean;
+/** Build an `http://host:port` origin, bracketing bare IPv6 literals. */
+export declare function hostUrl(host: string, port: number): string;
+export interface PortConflict {
+    name: LocalPortName;
+    port: number;
+    label: string;
+    envVar: string;
+}
+/**
+ * Can we bind this port? Docker publishes on all interfaces, so we test the
+ * same thing it will do. A port held on loopback alone still fails a
+ * wildcard bind, so this catches both.
+ *
+ * Anything other than a clean listen counts as unavailable: `EADDRINUSE` is the
+ * case we are looking for, and `EACCES` (a privileged port without rights)
+ * would fail the container just the same.
+ */
+export declare function isPortAvailable(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * Which of the stack's host ports are already taken. Probed concurrently —
+ * twelve sequential binds would add noticeable latency to every `local up`.
+ */
+export declare function findPortConflicts(ports: ResolvedLocalPorts): Promise<PortConflict[]>;
+/**
+ * The message a user gets instead of Docker's "port is already allocated":
+ * which service wanted which port, and the two ways to move it.
+ */
+export declare function describePortConflicts(conflicts: PortConflict[]): string;
+export {};