@ory/argus 0.13.9 → 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

@@ -1,18 +1,16 @@
 /**
  * Seed the local Ory environment with test data for development.
  *
- * Creates two principals:
+ * Creates the **User** (`user@ory-local.dev`) — a human identity with a
+ * known password (printed by the launcher) and an OAuth2
+ * `authorization_code` + PKCE client registered against the loopback
+ * redirect URIs. The launcher always runs the real PKCE browser flow; the
+ * user types these credentials into the login UI to complete the flow.
  *
- *   1. **Agent** (`agent@ory-local.dev`) — a Kratos identity that the
- *      harness will register a DCR OAuth2 client *for* on first session
- *      start. No OAuth2 client is pre-registered here.
- *
- *   2. **User** (`user@ory-local.dev`) — a human identity with a known
- *      password (printed by the launcher) and an OAuth2
- *      `authorization_code` + PKCE client registered against the
- *      loopback redirect URIs. The launcher always runs the real PKCE
- *      browser flow; the user types these credentials into the login
- *      UI to complete the flow.
+ * No agent principal is seeded: the harness self-registers a DCR OAuth2
+ * client for the agent on first session start (using the user's bearer as
+ * the initial access token), and permission checks are made against the
+ * user subject — so a pre-seeded agent Kratos identity would be unused.
  *
  * Permission tuples are written as SubjectSet `User:<identity.id>` so
  * the Console's *Add relationship* dialog (which always emits SubjectSet
@@ -24,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;
@@ -39,15 +41,6 @@ export interface SeededOAuth2Client {
     clientSecret?: string;
 }
 export interface SeedResult {
-    /**
-     * Agent (machine) identity — Kratos identity only. The agent's OAuth2
-     * client is *not* pre-registered: the harness self-registers via DCR
-     * (RFC 7591) on first session start using the user's bearer as the
-     * initial access token.
-     */
-    agent: {
-        identity: SeededIdentity;
-    };
     /** User (human) identity — subject of permission checks. */
     user: {
         identity: SeededIdentity;
@@ -67,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.