@ory/argus 0.14.0 → 1.0.0

package/dist/local/ports.js

@@ -0,0 +1,443 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOCAL_HOST = exports.SKIP_PORT_CHECK_ENV_VAR = exports.LOCAL_HOST_ENV_VAR = exports.PORT_OFFSET_ENV_VAR = exports.LOCAL_PORT_SPECS = exports.LOCAL_PORT_NAMES = exports.CONSOLE_CONTAINER_PORT = exports.OATHKEEPER_API_CONTAINER_PORT = exports.OATHKEEPER_PROXY_CONTAINER_PORT = exports.LOGIN_UI_CONTAINER_PORT = exports.GATEWAY_CONTAINER_PORT = exports.HYDRA_TOKEN_USER_CONTAINER_PORT = exports.HYDRA_ADMIN_CONTAINER_PORT = exports.HYDRA_PUBLIC_CONTAINER_PORT = exports.KETO_WRITE_CONTAINER_PORT = exports.KETO_READ_CONTAINER_PORT = exports.KRATOS_ADMIN_CONTAINER_PORT = exports.KRATOS_PUBLIC_CONTAINER_PORT = void 0;
+exports.portCheckDisabled = portCheckDisabled;
+exports.resolveLocalPorts = resolveLocalPorts;
+exports.hostFromDockerHost = hostFromDockerHost;
+exports.isLoopbackHost = isLoopbackHost;
+exports.resolveLocalHost = resolveLocalHost;
+exports.isLocalDockerDaemon = isLocalDockerDaemon;
+exports.hostUrl = hostUrl;
+exports.isPortAvailable = isPortAvailable;
+exports.findPortConflicts = findPortConflicts;
+exports.describePortConflicts = describePortConflicts;
+const net = __importStar(require("node:net"));
+// ─── Container-internal ports (fixed) ──────────────────────────────
+//
+// Changing any of these would also mean rewriting the service's own listen
+// config and every cross-service URL on the compose network, for no benefit:
+// nothing outside the bridge network can see them.
+exports.KRATOS_PUBLIC_CONTAINER_PORT = 4433;
+exports.KRATOS_ADMIN_CONTAINER_PORT = 4434;
+exports.KETO_READ_CONTAINER_PORT = 4466;
+exports.KETO_WRITE_CONTAINER_PORT = 4467;
+exports.HYDRA_PUBLIC_CONTAINER_PORT = 4444;
+exports.HYDRA_ADMIN_CONTAINER_PORT = 4445;
+exports.HYDRA_TOKEN_USER_CONTAINER_PORT = 5555;
+exports.GATEWAY_CONTAINER_PORT = 4000;
+exports.LOGIN_UI_CONTAINER_PORT = 4455;
+exports.OATHKEEPER_PROXY_CONTAINER_PORT = 4456;
+exports.OATHKEEPER_API_CONTAINER_PORT = 4457;
+/** Console Lite's Dockerfile sets `ENV PORT=3000`. */
+exports.CONSOLE_CONTAINER_PORT = 3000;
+// ─── Host ports (overridable) ──────────────────────────────────────
+/** Every host port the stack publishes, in the order `local status` lists them. */
+exports.LOCAL_PORT_NAMES = [
+    "gateway",
+    "console",
+    "loginUi",
+    "kratosPublic",
+    "kratosAdmin",
+    "ketoRead",
+    "ketoWrite",
+    "hydraPublic",
+    "hydraAdmin",
+    "hydraTokenUser",
+    "oathkeeperProxy",
+    "oathkeeperApi",
+];
+/**
+ * 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).
+ */
+exports.LOCAL_PORT_SPECS = {
+    gateway: {
+        default: exports.GATEWAY_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_GATEWAY_PORT",
+        label: "API gateway",
+    },
+    console: {
+        default: 4100,
+        envVar: "ORY_LOCAL_CONSOLE_PORT",
+        label: "Ory Console",
+    },
+    loginUi: {
+        default: exports.LOGIN_UI_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_LOGIN_UI_PORT",
+        label: "Login UI",
+    },
+    kratosPublic: {
+        default: exports.KRATOS_PUBLIC_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_KRATOS_PUBLIC_PORT",
+        label: "Kratos (public)",
+    },
+    kratosAdmin: {
+        default: exports.KRATOS_ADMIN_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_KRATOS_ADMIN_PORT",
+        label: "Kratos (admin)",
+    },
+    ketoRead: {
+        default: exports.KETO_READ_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_KETO_READ_PORT",
+        label: "Keto (read)",
+    },
+    ketoWrite: {
+        default: exports.KETO_WRITE_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_KETO_WRITE_PORT",
+        label: "Keto (write)",
+    },
+    hydraPublic: {
+        default: exports.HYDRA_PUBLIC_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_HYDRA_PUBLIC_PORT",
+        label: "Hydra (public)",
+    },
+    hydraAdmin: {
+        default: exports.HYDRA_ADMIN_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_HYDRA_ADMIN_PORT",
+        label: "Hydra (admin)",
+    },
+    hydraTokenUser: {
+        default: exports.HYDRA_TOKEN_USER_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_HYDRA_TOKEN_USER_PORT",
+        label: "Hydra (token user)",
+    },
+    oathkeeperProxy: {
+        default: exports.OATHKEEPER_PROXY_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_OATHKEEPER_PROXY_PORT",
+        label: "Oathkeeper (proxy)",
+    },
+    oathkeeperApi: {
+        default: exports.OATHKEEPER_API_CONTAINER_PORT,
+        envVar: "ORY_LOCAL_OATHKEEPER_API_PORT",
+        label: "Oathkeeper (API)",
+    },
+};
+/** Shifts every default port by a constant. Overridden per-port by the specific var. */
+exports.PORT_OFFSET_ENV_VAR = "ORY_LOCAL_PORT_OFFSET";
+/** Overrides the host name every generated URL advertises. */
+exports.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".
+ */
+exports.SKIP_PORT_CHECK_ENV_VAR = "ORY_LOCAL_SKIP_PORT_CHECK";
+function portCheckDisabled(env = process.env) {
+    const raw = env[exports.SKIP_PORT_CHECK_ENV_VAR]?.trim().toLowerCase();
+    if (!raw)
+        return false;
+    return raw !== "0" && raw !== "false" && raw !== "no" && raw !== "off";
+}
+const MIN_PORT = 1;
+const MAX_PORT = 65535;
+function parsePort(raw) {
+    // Reject anything that isn't a bare integer — `"4000x"`, `"40.5"`, `" "`.
+    // parseInt would happily accept the first two and produce a port the user
+    // did not ask for, which is worse than ignoring the value.
+    if (!/^\d+$/.test(raw))
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < MIN_PORT || value > MAX_PORT) {
+        return undefined;
+    }
+    return value;
+}
+/**
+ * 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.
+ */
+function resolveLocalPorts(env = process.env) {
+    const warnings = [];
+    let offset = 0;
+    const rawOffset = env[exports.PORT_OFFSET_ENV_VAR]?.trim();
+    if (rawOffset) {
+        const parsed = /^-?\d+$/.test(rawOffset) ? Number(rawOffset) : undefined;
+        if (parsed === undefined) {
+            warnings.push(`${exports.PORT_OFFSET_ENV_VAR}="${rawOffset}" is not an integer — ignoring it and using the default ports.`);
+        }
+        else {
+            offset = parsed;
+        }
+    }
+    const ports = {};
+    for (const name of exports.LOCAL_PORT_NAMES) {
+        const spec = exports.LOCAL_PORT_SPECS[name];
+        const raw = env[spec.envVar]?.trim();
+        if (raw) {
+            const parsed = parsePort(raw);
+            if (parsed === undefined) {
+                warnings.push(`${spec.envVar}="${raw}" is not a port between ${MIN_PORT} and ${MAX_PORT} — using ${spec.default} for ${spec.label}.`);
+                ports[name] = spec.default;
+            }
+            else {
+                ports[name] = parsed;
+            }
+            continue;
+        }
+        if (offset !== 0) {
+            const shifted = spec.default + offset;
+            if (shifted < MIN_PORT || shifted > MAX_PORT) {
+                warnings.push(`${exports.PORT_OFFSET_ENV_VAR}=${offset} puts ${spec.label} at ${shifted}, outside ${MIN_PORT}-${MAX_PORT} — using ${spec.default}. Set ${spec.envVar} to place it explicitly.`);
+                ports[name] = spec.default;
+            }
+            else {
+                ports[name] = shifted;
+            }
+            continue;
+        }
+        ports[name] = spec.default;
+    }
+    warnings.push(...describeDuplicatePorts(ports));
+    return { ports, warnings };
+}
+/**
+ * Two services configured onto the same host port. Only reachable through
+ * explicit per-port overrides — the offset preserves the spacing of the
+ * defaults — and it would otherwise surface as a confusing Docker error about
+ * a port the user *did* mean to claim.
+ */
+function describeDuplicatePorts(ports) {
+    const byPort = new Map();
+    for (const name of exports.LOCAL_PORT_NAMES) {
+        const list = byPort.get(ports[name]) ?? [];
+        list.push(name);
+        byPort.set(ports[name], list);
+    }
+    const warnings = [];
+    for (const [port, names] of byPort) {
+        if (names.length < 2)
+            continue;
+        const labels = names.map((n) => exports.LOCAL_PORT_SPECS[n].label).join(" and ");
+        const vars = names.map((n) => exports.LOCAL_PORT_SPECS[n].envVar).join(" / ");
+        warnings.push(`${labels} are both configured on host port ${port} — the stack cannot start. Set ${vars} to different values.`);
+    }
+    return warnings;
+}
+exports.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.
+ */
+function hostFromDockerHost(dockerHost) {
+    const raw = dockerHost?.trim();
+    if (!raw)
+        return undefined;
+    if (raw.startsWith("unix://") || raw.startsWith("npipe://"))
+        return undefined;
+    let hostname;
+    try {
+        hostname = new URL(raw).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    if (!hostname)
+        return undefined;
+    // A tcp:// daemon on loopback is still this machine — `localhost` reads
+    // better in a banner than `127.0.0.1`, and keeps URLs stable for anyone who
+    // sets DOCKER_HOST explicitly at the default address.
+    if (isLoopbackHost(hostname))
+        return undefined;
+    return hostname;
+}
+function isLoopbackHost(host) {
+    const h = host.toLowerCase().replace(/^\[|\]$/g, "");
+    return h === "localhost" || h === "127.0.0.1" || h === "::1";
+}
+/**
+ * The host name every generated URL should advertise: config files, banners,
+ * the health probe, and the `projectUrl` that `local configure` persists.
+ */
+function resolveLocalHost(env = process.env) {
+    const explicit = env[exports.LOCAL_HOST_ENV_VAR]?.trim();
+    if (explicit)
+        return { host: explicit, source: "env" };
+    const fromDocker = hostFromDockerHost(env.DOCKER_HOST);
+    if (fromDocker)
+        return { host: fromDocker, source: "docker-host" };
+    return { host: exports.DEFAULT_LOCAL_HOST, source: "default" };
+}
+/**
+ * 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).
+ */
+function isLocalDockerDaemon(env = process.env) {
+    return hostFromDockerHost(env.DOCKER_HOST) === undefined;
+}
+/** Build an `http://host:port` origin, bracketing bare IPv6 literals. */
+function hostUrl(host, port) {
+    const needsBrackets = host.includes(":") && !host.startsWith("[");
+    return `http://${needsBrackets ? `[${host}]` : host}:${port}`;
+}
+/**
+ * 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.
+ */
+function isPortAvailable(port, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        let settled = false;
+        const finish = (available) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.removeAllListeners();
+            try {
+                server.close();
+            }
+            catch {
+                /* already closed */
+            }
+            resolve(available);
+        };
+        const timer = setTimeout(() => finish(true), timeoutMs);
+        timer.unref?.();
+        server.once("error", () => finish(false));
+        server.once("listening", () => finish(true));
+        try {
+            server.listen({ port, host: "0.0.0.0", exclusive: true });
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
+/**
+ * Which of the stack's host ports are already taken. Probed concurrently —
+ * twelve sequential binds would add noticeable latency to every `local up`.
+ */
+async function findPortConflicts(ports) {
+    const checks = exports.LOCAL_PORT_NAMES.map(async (name) => {
+        const available = await isPortAvailable(ports[name]);
+        return available
+            ? undefined
+            : {
+                name,
+                port: ports[name],
+                label: exports.LOCAL_PORT_SPECS[name].label,
+                envVar: exports.LOCAL_PORT_SPECS[name].envVar,
+            };
+    });
+    return (await Promise.all(checks)).filter((c) => c !== undefined);
+}
+/**
+ * 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.
+ */
+function describePortConflicts(conflicts) {
+    if (conflicts.length === 0)
+        return "";
+    const lines = [
+        conflicts.length === 1
+            ? "Port already in use — the local Ory stack cannot start:"
+            : `${conflicts.length} ports already in use — the local Ory stack cannot start:`,
+        "",
+        ...conflicts.map((c) => `  ${c.port}  ${c.label}  (override with ${c.envVar})`),
+        "",
+        "The defaults are the stock Ory ports, so another Ory instance is the usual cause.",
+        "Move the whole stack out of the way with a single offset:",
+        "",
+        `  ${exports.PORT_OFFSET_ENV_VAR}=100 <command>`,
+        "",
+        "or pin individual services with the variables listed above. Do not edit the",
+        "generated compose file — the next 'local up' regenerates it.",
+    ];
+    return lines.join("\n");
+}

package/dist/local/seed.d.ts

@@ -22,12 +22,16 @@
  * 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
+ * The client id Hydra issues to the seeded user PKCE client: the same
+ * **reserved** id Ory Network's Agent Security setup uses, so local dev and a
+ * hosted project name the shared login client identically and the id — never a
+ * `client_name` — is what resolves it in both.
+ *
+ * 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 declare const USER_CLIENT_ID = "ory-agent-security-login";
 export interface SeededIdentity {
     id: string;
     email: string;
@@ -56,7 +60,11 @@ export interface SeedResult {
         tuples: number;
     };
 }
-/** Subject namespace for user identities in seeded permission tuples. */
+/**
+ * Subject namespace for user identities in seeded permission tuples. Re-exported
+ * from the core default so the seed, the runtime resolver, and the persisted
+ * install config all address the user under the same namespace.
+ */
 export declare const USER_SUBJECT_NAMESPACE = "User";
 /**
  * Run the full seed process. Idempotent — safe to run multiple times.

package/dist/local/seed.js

@@ -26,26 +26,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.USER_SUBJECT_NAMESPACE = exports.USER_CLIENT_ID = void 0;
 exports.seedLocalEnvironment = seedLocalEnvironment;
 const auth_js_1 = require("../auth.js");
+const branding_js_1 = require("../branding.js");
 const tool_catalog_js_1 = require("../tool-catalog.js");
+const subject_js_1 = require("../subject.js");
+const opl_js_1 = require("../opl.js");
 const configs_js_1 = require("./configs.js");
+const ports_js_1 = require("./ports.js");
 const health_js_1 = require("./health.js");
-const KRATOS_ADMIN = `http://localhost:${configs_js_1.KRATOS_ADMIN_PORT}`;
-const KETO_WRITE = `http://localhost:${configs_js_1.KETO_WRITE_PORT}`;
-const HYDRA_ADMIN = `http://localhost:${configs_js_1.HYDRA_ADMIN_PORT}`;
+const KRATOS_ADMIN = (0, ports_js_1.hostUrl)(configs_js_1.LOCAL_STACK_HOST, configs_js_1.KRATOS_ADMIN_PORT);
+const KETO_WRITE = (0, ports_js_1.hostUrl)(configs_js_1.LOCAL_STACK_HOST, configs_js_1.KETO_WRITE_PORT);
+const HYDRA_ADMIN = (0, ports_js_1.hostUrl)(configs_js_1.LOCAL_STACK_HOST, configs_js_1.HYDRA_ADMIN_PORT);
 const USER_EMAIL = "user@ory-local.dev";
 const USER_PASSWORD = "ory-user-local-dev-password!";
-const USER_CLIENT_NAME = "ory-agent-plugins-local-user";
 /**
- * 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
+ * The client id Hydra issues to the seeded user PKCE client: the same
+ * **reserved** id Ory Network's Agent Security setup uses, so local dev and a
+ * hosted project name the shared login client identically and the id — never a
+ * `client_name` — is what resolves it in both.
+ *
+ * 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";
+exports.USER_CLIENT_ID = branding_js_1.USER_LOGIN_CLIENT_ID;
 /**
- * Tools the dev launcher seeds tuples for. Sourced from the shared
- * per-harness catalog so a single seed grants the local user identity
- * `use` on every harness's built-in tool set.
+ * Tools the explicit local-stack command seeds tuples for. Sourced from the
+ * shared catalog so one seed covers every harness's built-in tool set.
  */
 const COMMON_TOOLS = tool_catalog_js_1.ALL_TOOLS;
 async function jsonFetch(url, opts = {}) {
@@ -82,8 +88,12 @@ async function seedIdentity(email, password, name) {
     }));
     return { id: identity.id, email };
 }
-/** Subject namespace for user identities in seeded permission tuples. */
-exports.USER_SUBJECT_NAMESPACE = "User";
+/**
+ * Subject namespace for user identities in seeded permission tuples. Re-exported
+ * from the core default so the seed, the runtime resolver, and the persisted
+ * install config all address the user under the same namespace.
+ */
+exports.USER_SUBJECT_NAMESPACE = subject_js_1.DEFAULT_USER_SUBJECT_NAMESPACE;
 /**
  * Write permission tuples granting the user identity access to all
  * common tools. The subject is written as a SubjectSet
@@ -91,16 +101,16 @@ exports.USER_SUBJECT_NAMESPACE = "User";
  * dialog — which only emits SubjectSet subjects — can recreate the same
  * tuple by hand during the runbook walkthrough.
  */
-async function seedPermissions(userId, namespace) {
+async function seedPermissions(userId, namespace, objects = COMMON_TOOLS) {
     let created = 0;
-    for (const tool of COMMON_TOOLS) {
+    for (const object of objects) {
         try {
             await jsonFetch(`${KETO_WRITE}/admin/relation-tuples`, {
                 method: "PUT",
                 body: JSON.stringify({
                     namespace,
-                    object: tool,
-                    relation: "use",
+                    object,
+                    relation: opl_js_1.RELATION_USERS,
                     subject_set: {
                         namespace: exports.USER_SUBJECT_NAMESPACE,
                         object: userId,
@@ -113,7 +123,7 @@ async function seedPermissions(userId, namespace) {
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             if (!msg.includes("409")) {
-                process.stderr.write(`  Warning: failed to create permission for ${tool}: ${msg}\n`);
+                process.stderr.write(`  Warning: failed to create permission for ${object}: ${msg}\n`);
             }
             else {
                 created++;
@@ -123,25 +133,29 @@ async function seedPermissions(userId, namespace) {
     return created;
 }
 /**
- * Delete a Hydra OAuth2 client if it exists, then create it with a
- * known client_id/secret. We always recreate so the launcher knows the
- * exact credentials to inject into the harness env.
+ * Delete a Hydra OAuth2 client if it exists, then create it at a known
+ * client_id (with a known secret, for a confidential client). We always
+ * recreate so the launcher knows the exact credentials to inject into the
+ * harness env.
+ *
+ * The client is addressed **by id**, never by `client_name`. That mirrors how
+ * Ory Network resolves the shared login client — the name is a display label
+ * anyone can register a client under, so only the reserved id identifies it
+ * (see `USER_LOGIN_CLIENT_ID`) — so local dev cannot pass with a lookup shape
+ * that would be unsafe against a hosted project.
  */
 async function ensureOAuth2Client(spec) {
-    // Look up by client_name; delete if present so we can recreate with a
-    // deterministic secret.
-    const existing = (await jsonFetch(`${HYDRA_ADMIN}/admin/clients?client_name=${encodeURIComponent(spec.clientName)}`));
-    for (const c of existing) {
-        if (c.client_name !== spec.clientName)
-            continue;
-        try {
-            await jsonFetch(`${HYDRA_ADMIN}/admin/clients/${encodeURIComponent(c.client_id)}`, {
-                method: "DELETE",
-            });
-        }
-        catch {
-            // best-effort cleanup
-        }
+    // Delete the client at this id if one is already there, so the recreate
+    // below lands with the exact grants, scopes, and redirect URIs this seed
+    // declares. A 404 (nothing to delete) is the normal first-run case.
+    try {
+        await jsonFetch(`${HYDRA_ADMIN}/admin/clients/${encodeURIComponent(spec.clientId)}`, {
+            method: "DELETE",
+        });
+    }
+    catch {
+        // best-effort cleanup — absent, or Hydra refused; the create below reports
+        // the real problem if there is one.
     }
     const body = {
         client_id: spec.clientId,
@@ -174,7 +188,7 @@ function loopbackRedirectUris() {
  * Returns a `SeedResult` describing both identities, the user's
  * pre-minted session, and the OAuth2 clients registered for each.
  */
-async function seedLocalEnvironment(namespace = "AgentTools") {
+async function seedLocalEnvironment(namespace = "AgentTool") {
     process.stderr.write("Seeding local Ory environment...\n\n");
     // 0. Readiness barrier. The seed writes directly to Kratos (admin),
     //    Keto (write), and Hydra (admin). Neither the static nginx gateway
@@ -203,6 +217,14 @@ async function seedLocalEnvironment(namespace = "AgentTools") {
     process.stderr.write(`  Creating permissions for ${COMMON_TOOLS.length} tools...\n`);
     const tupleCount = await seedPermissions(userIdentity.id, namespace);
     process.stderr.write(`  Permissions: ${tupleCount} entries in '${namespace}' for ${subjectLabel}\n`);
+    // Shell-command sub-tools (issue #76): grant every catalog word in the
+    // ShellTool namespace so a launched harness can run `bash -c "curl …"`
+    // out of the box, and the enforce demo (revoke `ShellTool:curl#users`,
+    // watch it block) works without hand-writing tuples first.
+    const shellWords = (0, tool_catalog_js_1.getShellCommandCatalog)();
+    const shellNamespace = (0, tool_catalog_js_1.resolveShellCommandNamespace)();
+    const shellCount = await seedPermissions(userIdentity.id, shellNamespace, shellWords);
+    process.stderr.write(`  Shell commands: ${shellCount} entries in '${shellNamespace}' for ${subjectLabel}\n`);
     // 3. User OAuth2 client (PKCE) — pre-registered so the user gate's
     //    PKCE flow has somewhere to authenticate against. The agent's
     //    OAuth2 client is intentionally NOT pre-registered; the harness
@@ -211,13 +233,15 @@ async function seedLocalEnvironment(namespace = "AgentTools") {
     let userClient = { clientId: exports.USER_CLIENT_ID };
     try {
         userClient = await ensureOAuth2Client({
-            clientName: USER_CLIENT_NAME,
+            // Display label only, matching what a hosted project shows in the
+            // Console — the client is addressed by its id.
+            clientName: branding_js_1.USER_LOGIN_CLIENT_NAME,
             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"],
             responseTypes: ["code"],
-            scope: "openid offline_access",
+            scope: branding_js_1.USER_LOGIN_SCOPE_OAUTH,
             tokenEndpointAuthMethod: "none",
             redirectUris: loopbackRedirectUris(),
         });