@ory/argus 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Browser-based OAuth2 PKCE login for Ory agent plugins.
+ *
+ * Spins up a transient localhost callback server on a fixed-port range
+ * (option (a) — operators register the same loopback URIs once with the
+ * Ory OAuth2 client), generates a PKCE verifier/challenge, launches the
+ * user's browser at the project's authorize URL, and exchanges the
+ * resulting code for a token set via /oauth2/token.
+ *
+ * This module never writes to stdout. Browser launching uses the `open`
+ * package via dynamic import so the CJS-emitted core stays compatible
+ * with its ESM-only export shape.
+ */
+import { OryOAuth2Tokens } from "./config.js";
+/** Loopback ports tried in order. All must be registered as redirect URIs on the Ory OAuth2 client. */
+export declare const LOOPBACK_PORTS: readonly [47823, 47824, 47825, 47826];
+/** Hard timeout if the user never returns to the browser. */
+export declare const DEFAULT_LOGIN_TIMEOUT_MS = 120000;
+export interface PkceLoginOptions {
+    /** Ory project URL (e.g. https://your-project.projects.oryapis.com). */
+    projectUrl: string;
+    /** Public OAuth2 client id registered with the loopback redirect URIs. */
+    clientId: string;
+    /** Scopes to request. Defaults to `openid offline_access`. */
+    scope?: string;
+    /** Audience to request, if any. */
+    audience?: string;
+    /** Login timeout in ms. Defaults to {@link DEFAULT_LOGIN_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Override the loopback port list (mostly for testing). */
+    ports?: ReadonlyArray<number>;
+    /** Hook for opening the browser. Defaults to the `open` npm package. */
+    openBrowser?: (url: string) => Promise<void>;
+    /** Override headless detection (mostly for testing). */
+    isHeadless?: () => boolean;
+    /** Optional AbortSignal to cancel the login (e.g. on shutdown). */
+    signal?: AbortSignal;
+}
+export type PkceLoginOutcome = {
+    kind: "ok";
+    tokens: OryOAuth2Tokens;
+} | {
+    kind: "declined";
+    reason: PkceDeclineReason;
+};
+export type PkceDeclineReason = "headless" | "timeout" | "user_denied" | "state_mismatch" | "no_port" | "browser_launch_failed" | "aborted" | "token_exchange_failed";
+/**
+ * Default headless heuristic. Returns true only for unattended runs
+ * (CI=true / CI=1) so {@link pkceLogin} can short-circuit instead of
+ * waiting on a callback that will never arrive.
+ *
+ * Heuristics like `SSH_TTY` and "Linux without DISPLAY" used to live here
+ * but turned out to be wrong in practice: an SSH user can paste the
+ * printed authorize URL into their workstation browser, and a Linux box
+ * without a display still works as long as the operator can reach the
+ * loopback callback port (e.g. via `ssh -L`). The PKCE flow always
+ * prints the URL to stderr, so anything short of "no human at all" is
+ * recoverable.
+ */
+export declare function detectHeadless(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Run a PKCE login and return either a token set or the reason the flow
+ * could not complete. The function never throws on user-driven failures
+ * (timeout, decline, headless); it throws only on programmer error or
+ * unrecoverable I/O failures.
+ */
+export declare function pkceLogin(options: PkceLoginOptions): Promise<PkceLoginOutcome>;
+/** Generate a 64-byte (≈86-char base64url) code verifier per RFC 7636. */
+export declare function generateCodeVerifier(): string;
+/** SHA-256 + base64url, the only supported PKCE challenge method (`S256`). */
+export declare function sha256Base64Url(input: string): string;
+export declare function buildAuthorizeUrl(params: {
+    projectUrl: string;
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    codeChallenge: string;
+    scope: string;
+    audience?: string;
+}): string;
+/**
+ * Refresh an access token using a refresh token. Throws on any non-2xx
+ * response so callers can decide whether to fall back to a fresh login.
+ *
+ * Kept as raw fetch for parity with the other two /oauth2/token flows;
+ * see `exchangeCodeForTokens` and `fetchClientCredentialsToken` for why
+ * @ory/client's OAuth2Api.oauth2TokenExchange isn't used.
+ */
+export declare function refreshAccessToken(args: {
+    projectUrl: string;
+    clientId: string;
+    refreshToken: string;
+}): Promise<OryOAuth2Tokens>;

package/dist/auth.js

@@ -0,0 +1,323 @@
+"use strict";
+/**
+ * Browser-based OAuth2 PKCE login for Ory agent plugins.
+ *
+ * Spins up a transient localhost callback server on a fixed-port range
+ * (option (a) — operators register the same loopback URIs once with the
+ * Ory OAuth2 client), generates a PKCE verifier/challenge, launches the
+ * user's browser at the project's authorize URL, and exchanges the
+ * resulting code for a token set via /oauth2/token.
+ *
+ * This module never writes to stdout. Browser launching uses the `open`
+ * package via dynamic import so the CJS-emitted core stays compatible
+ * with its ESM-only export shape.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_LOGIN_TIMEOUT_MS = exports.LOOPBACK_PORTS = void 0;
+exports.detectHeadless = detectHeadless;
+exports.pkceLogin = pkceLogin;
+exports.generateCodeVerifier = generateCodeVerifier;
+exports.sha256Base64Url = sha256Base64Url;
+exports.buildAuthorizeUrl = buildAuthorizeUrl;
+exports.refreshAccessToken = refreshAccessToken;
+const node_crypto_1 = require("node:crypto");
+const node_http_1 = require("node:http");
+const node_url_1 = require("node:url");
+/** Loopback ports tried in order. All must be registered as redirect URIs on the Ory OAuth2 client. */
+exports.LOOPBACK_PORTS = [47823, 47824, 47825, 47826];
+/** Hard timeout if the user never returns to the browser. */
+exports.DEFAULT_LOGIN_TIMEOUT_MS = 120_000;
+/**
+ * Default headless heuristic. Returns true only for unattended runs
+ * (CI=true / CI=1) so {@link pkceLogin} can short-circuit instead of
+ * waiting on a callback that will never arrive.
+ *
+ * Heuristics like `SSH_TTY` and "Linux without DISPLAY" used to live here
+ * but turned out to be wrong in practice: an SSH user can paste the
+ * printed authorize URL into their workstation browser, and a Linux box
+ * without a display still works as long as the operator can reach the
+ * loopback callback port (e.g. via `ssh -L`). The PKCE flow always
+ * prints the URL to stderr, so anything short of "no human at all" is
+ * recoverable.
+ */
+function detectHeadless(env = process.env) {
+    return env.CI === "true" || env.CI === "1";
+}
+/**
+ * Run a PKCE login and return either a token set or the reason the flow
+ * could not complete. The function never throws on user-driven failures
+ * (timeout, decline, headless); it throws only on programmer error or
+ * unrecoverable I/O failures.
+ */
+async function pkceLogin(options) {
+    const isHeadless = options.isHeadless ?? detectHeadless;
+    const headless = isHeadless();
+    if (headless) {
+        // Unattended environment (CI). No human to follow the URL, so we
+        // skip the loopback listener entirely instead of timing out.
+        return { kind: "declined", reason: "headless" };
+    }
+    const { server, port } = await listenOnFirstAvailablePort(options.ports ?? exports.LOOPBACK_PORTS);
+    if (!server || port === null) {
+        return { kind: "declined", reason: "no_port" };
+    }
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = sha256Base64Url(codeVerifier);
+    const state = (0, node_crypto_1.randomBytes)(16).toString("base64url");
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const scope = options.scope ?? "openid offline_access";
+    const authorizeUrl = buildAuthorizeUrl({
+        projectUrl: options.projectUrl,
+        clientId: options.clientId,
+        redirectUri,
+        state,
+        codeChallenge,
+        scope,
+        audience: options.audience,
+    });
+    const timeoutMs = options.timeoutMs ?? exports.DEFAULT_LOGIN_TIMEOUT_MS;
+    // Print the URL to stderr *before* attempting to launch the browser.
+    // Users in non-TTY environments (SSH without `-t`, IDE terminals, etc.)
+    // can paste this into any browser that can reach 127.0.0.1 on the
+    // loopback port (locally on the same machine, or via `ssh -L
+    // <port>:localhost:<port>` from a remote box).
+    process.stderr.write(`\nOry sign-in required. Open this URL in a browser that can reach ${redirectUri}:\n\n  ${authorizeUrl}\n\n` +
+        `Waiting up to ${Math.round(timeoutMs / 1000)}s for the callback…\n\n`);
+    const callback = waitForCallback(server, {
+        expectedState: state,
+        timeoutMs,
+        signal: options.signal,
+    });
+    // Browser launch is best-effort. If `open` throws or the platform has
+    // no usable browser, we keep the callback server alive and rely on the
+    // user opening the printed URL themselves. Decline only on a real
+    // callback failure (timeout, state mismatch, user_denied).
+    try {
+        await launchBrowser(authorizeUrl, options.openBrowser);
+    }
+    catch (err) {
+        process.stderr.write(`Could not auto-launch a browser (${err instanceof Error ? err.message : String(err)}). ` +
+            `Open the URL above manually to continue.\n\n`);
+    }
+    const result = await callback;
+    server.close();
+    if (result.kind !== "ok")
+        return result;
+    try {
+        const tokens = await exchangeCodeForTokens({
+            projectUrl: options.projectUrl,
+            clientId: options.clientId,
+            redirectUri,
+            code: result.code,
+            codeVerifier,
+        });
+        return { kind: "ok", tokens };
+    }
+    catch {
+        return { kind: "declined", reason: "token_exchange_failed" };
+    }
+}
+// ─── PKCE primitives ──────────────────────────────────────────────────
+/** Generate a 64-byte (≈86-char base64url) code verifier per RFC 7636. */
+function generateCodeVerifier() {
+    return (0, node_crypto_1.randomBytes)(64).toString("base64url");
+}
+/** SHA-256 + base64url, the only supported PKCE challenge method (`S256`). */
+function sha256Base64Url(input) {
+    return (0, node_crypto_1.createHash)("sha256").update(input).digest("base64url");
+}
+function buildAuthorizeUrl(params) {
+    const url = new node_url_1.URL("/oauth2/auth", params.projectUrl);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("client_id", params.clientId);
+    url.searchParams.set("redirect_uri", params.redirectUri);
+    url.searchParams.set("state", params.state);
+    url.searchParams.set("scope", params.scope);
+    url.searchParams.set("code_challenge", params.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    if (params.audience)
+        url.searchParams.set("audience", params.audience);
+    return url.toString();
+}
+// ─── Callback server ──────────────────────────────────────────────────
+async function listenOnFirstAvailablePort(ports) {
+    for (const requested of ports) {
+        try {
+            const server = await new Promise((resolve, reject) => {
+                const s = (0, node_http_1.createServer)();
+                const onError = (err) => {
+                    s.removeListener("listening", onListening);
+                    reject(err);
+                };
+                const onListening = () => {
+                    s.removeListener("error", onError);
+                    resolve(s);
+                };
+                s.once("error", onError);
+                s.once("listening", onListening);
+                s.listen(requested, "127.0.0.1");
+            });
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : requested;
+            return { server, port };
+        }
+        catch (err) {
+            if (err.code === "EADDRINUSE")
+                continue;
+            throw err;
+        }
+    }
+    return { server: null, port: null };
+}
+function waitForCallback(server, opts) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (opts.signal)
+                opts.signal.removeEventListener("abort", onAbort);
+            server.removeListener("request", onRequest);
+            resolve(r);
+        };
+        const timer = setTimeout(() => settle({ kind: "declined", reason: "timeout" }), opts.timeoutMs);
+        const onAbort = () => settle({ kind: "declined", reason: "aborted" });
+        if (opts.signal) {
+            if (opts.signal.aborted) {
+                settle({ kind: "declined", reason: "aborted" });
+                return;
+            }
+            opts.signal.addEventListener("abort", onAbort);
+        }
+        const onRequest = (req, res) => {
+            if (!isLoopbackHost(req.headers.host)) {
+                respond(res, 400, "Bad Host");
+                return;
+            }
+            const url = new node_url_1.URL(req.url ?? "/", `http://127.0.0.1`);
+            if (url.pathname !== "/callback") {
+                respond(res, 404, "Not Found");
+                return;
+            }
+            const error = url.searchParams.get("error");
+            if (error) {
+                respond(res, 400, "Authentication declined. You may close this window.");
+                settle({ kind: "declined", reason: "user_denied" });
+                return;
+            }
+            const state = url.searchParams.get("state");
+            const code = url.searchParams.get("code");
+            if (!code || state !== opts.expectedState) {
+                respond(res, 400, "State mismatch.");
+                settle({ kind: "declined", reason: "state_mismatch" });
+                return;
+            }
+            respond(res, 200, "Sign-in complete. You may close this window and return to your terminal.");
+            settle({ kind: "ok", code });
+        };
+        server.on("request", onRequest);
+    });
+}
+function isLoopbackHost(host) {
+    if (!host)
+        return false;
+    const hostOnly = host.split(":")[0];
+    return hostOnly === "127.0.0.1" || hostOnly === "localhost" || hostOnly === "[::1]";
+}
+function respond(res, status, body) {
+    res.writeHead(status, { "content-type": "text/plain; charset=utf-8" });
+    res.end(body + "\n");
+}
+// ─── Browser launch ───────────────────────────────────────────────────
+async function launchBrowser(url, override) {
+    if (override) {
+        await override(url);
+        return;
+    }
+    // `open` is ESM-only; dynamic import works from CJS output.
+    const mod = (await import("open"));
+    await mod.default(url);
+}
+// Kept as raw fetch (rather than @ory/client's OAuth2Api.oauth2TokenExchange)
+// because the SDK method's signature does not expose code_verifier, which
+// PKCE requires. Ory's own SDK docstring on that method says it should not
+// be used via the SDK.
+async function exchangeCodeForTokens(args) {
+    const body = new URLSearchParams({
+        grant_type: "authorization_code",
+        client_id: args.clientId,
+        code: args.code,
+        redirect_uri: args.redirectUri,
+        code_verifier: args.codeVerifier,
+    });
+    const tokenUrl = new node_url_1.URL("/oauth2/token", args.projectUrl).toString();
+    const res = await fetch(tokenUrl, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`Token exchange failed: HTTP ${res.status}`);
+    }
+    const json = (await res.json());
+    return tokensFromTokenResponse(json, args.clientId);
+}
+/**
+ * Refresh an access token using a refresh token. Throws on any non-2xx
+ * response so callers can decide whether to fall back to a fresh login.
+ *
+ * Kept as raw fetch for parity with the other two /oauth2/token flows;
+ * see `exchangeCodeForTokens` and `fetchClientCredentialsToken` for why
+ * @ory/client's OAuth2Api.oauth2TokenExchange isn't used.
+ */
+async function refreshAccessToken(args) {
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: args.clientId,
+        refresh_token: args.refreshToken,
+    });
+    const tokenUrl = new node_url_1.URL("/oauth2/token", args.projectUrl).toString();
+    const res = await fetch(tokenUrl, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`Token refresh failed: HTTP ${res.status}`);
+    }
+    const json = (await res.json());
+    return tokensFromTokenResponse(json, args.clientId, args.refreshToken);
+}
+function tokensFromTokenResponse(json, clientId, fallbackRefreshToken) {
+    const accessToken = typeof json.access_token === "string" ? json.access_token : "";
+    if (!accessToken)
+        throw new Error("Token response missing access_token");
+    const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 3600;
+    const refreshToken = typeof json.refresh_token === "string" ? json.refresh_token : fallbackRefreshToken;
+    return {
+        accessToken,
+        refreshToken,
+        expiresAt: Math.floor(Date.now() / 1000) + expiresIn,
+        clientId,
+        idToken: typeof json.id_token === "string" ? json.id_token : undefined,
+        scope: typeof json.scope === "string" ? json.scope : undefined,
+        subject: subjectFromIdToken(typeof json.id_token === "string" ? json.id_token : undefined),
+    };
+}
+/** Best-effort sub-claim extraction from a JWT id_token. Returns undefined on any failure. */
+function subjectFromIdToken(idToken) {
+    if (!idToken)
+        return undefined;
+    const parts = idToken.split(".");
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+        return typeof payload.sub === "string" ? payload.sub : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared `configure` command implementation for all plugin CLIs.
+ *
+ * Parses --project-url and --api-key from args. If neither is provided,
+ * shows the current configuration. Otherwise saves the provided values.
+ */
+export declare function runConfigureCommand(binName: string, args: string[]): void;
+/**
+ * Print the "Configuration:" block showing Ory project URL and API key status.
+ */
+export declare function printOryConfig(): void;
+/**
+ * Print the "Environment:" block showing Ory-related environment variables.
+ */
+export declare function printEnvironment(): void;
+/**
+ * Print the last 5 debug log entries if ORY_AGENT_LOG_FILE is set and exists.
+ */
+export declare function printLogTail(): void;
+/**
+ * Print the "Configure your Ory credentials" help text.
+ */
+export declare function printEnvHelp(binName: string): void;
+/**
+ * Print the last 5 trace entries if ORY_AGENT_TRACE_FILE is set and exists.
+ */
+export declare function printTraceTail(): void;
+/**
+ * Run the live trace watcher. Tails the NDJSON trace file and prints
+ * formatted spans to stdout as they arrive. Blocks until interrupted.
+ */
+export declare function runWatchCommand(args: string[]): void;
+/**
+ * Returns true if `/dev/tty` can be opened for reading. Use this before
+ * attempting to prompt the user — the harness has already taken stdin so
+ * we cannot use `process.stdin`.
+ */
+export declare function isTtyAvailable(): boolean;
+/**
+ * Prompt the user to enter a value on /dev/tty. Returns the trimmed
+ * line, or null if no TTY is available. The prompt is written to stderr
+ * — never stdout.
+ */
+export declare function promptOnTty(prompt: string): Promise<string | null>;
+/**
+ * Inline prompt for the Ory project URL. Persists the entered URL to the
+ * shared config file and returns it. Returns null if the user cancels
+ * (empty input) or no TTY is available.
+ *
+ * This is the structured counterpart to {@link interactiveConfigPrompt},
+ * which only blocks until the user runs `configure` in another terminal.
+ */
+export declare function promptForProjectUrl(binName: string): Promise<string | null>;
+/**
+ * Display a friendly configuration prompt on stderr and block until the
+ * user presses Enter. After the user continues, re-checks config from
+ * disk and returns true if Ory is now configured.
+ *
+ * Falls back to non-interactive mode (returns false immediately) when
+ * no TTY is available (e.g. CI).
+ */
+export declare function interactiveConfigPrompt(binName: string): Promise<boolean>;
+/**
+ * Run the `agent <subcommand>` family of CLI commands. These manage the
+ * agent's dynamic OAuth2 client registration (RFC 7591). Subcommands:
+ *
+ *   - `status`     — print the persisted DCR identity, if any.
+ *   - `unregister` — best-effort RFC 7592 DELETE on the registered
+ *                    client, then clear the persisted block.
+ *
+ * Returns the process exit code (0 on success, non-zero on usage error).
+ */
+export declare function runAgentCommand(binName: string, args: string[]): Promise<number>;