@ory/argus 0.1.0

package/dist/auth-gate.js

@@ -0,0 +1,308 @@
+"use strict";
+/**
+ * User authentication gate. Orchestrates the "first interaction must
+ * authenticate the human user" requirement across all plugins:
+ *
+ *   1. Resolve config (env + ~/.config/ory-agent-plugins/config.json).
+ *   2. If no project URL, prompt for one when a TTY is available;
+ *      otherwise skip with an audit span.
+ *   3. If a session/oauth2 token is already in env, short-circuit ok.
+ *   4. If persisted tokens are valid, return ok.
+ *   5. If they are expired with a refresh_token, refresh.
+ *   6. Otherwise launch the PKCE browser login. The flow prints the
+ *      authorize URL to stderr and waits on a loopback callback, so a
+ *      missing TTY is fine — users without an interactive terminal can
+ *      paste the URL into any browser that can reach 127.0.0.1. Only
+ *      truly unattended (CI=true) environments short-circuit early.
+ *
+ * Every terminal path emits exactly one `user.auth` trace span so that
+ * the audit trail is complete regardless of outcome.
+ *
+ * The whole gate is a no-op (mode `disabled`) unless the
+ * `ORY_AUTH_GATE` env var is set to `1`/`true` — phased rollout.
+ *
+ * This gate authenticates the *user* (the human at the keyboard). The
+ * separate agent identity (the AI process making the calls) is resolved
+ * non-interactively via env-configured machine credentials and is not
+ * handled here — see `ensureAgentIdentity` (forthcoming).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureAuthenticated = void 0;
+exports.ensureUserAuthenticated = ensureUserAuthenticated;
+const config_js_1 = require("./config.js");
+const cli_js_1 = require("./cli.js");
+const auth_store_js_1 = require("./auth-store.js");
+const auth_js_1 = require("./auth.js");
+const ENABLED_VALUES = new Set(["1", "true", "yes", "on"]);
+function isGateEnabled() {
+    const v = process.env.ORY_AUTH_GATE?.toLowerCase();
+    return !!v && ENABLED_VALUES.has(v);
+}
+function clientId() {
+    return process.env.ORY_OAUTH2_CLIENT_ID;
+}
+function recordAuthSpan(client, decision) {
+    const status = decision.mode === "ok" || decision.mode === "refreshed" || decision.mode === "env_token"
+        ? "ok"
+        : decision.mode === "declined"
+            ? "denied"
+            : decision.mode === "error"
+                ? "error"
+                : "skipped";
+    client.tracer.record("user.auth", status, {
+        attributes: {
+            mode: decision.mode,
+            reason: decision.reason,
+            ...(decision.subject ? { subject: decision.subject } : {}),
+            proceed: decision.proceed,
+        },
+    });
+}
+/**
+ * The entry point that every plugin's session-start handler should call
+ * to authenticate the human user. Always returns a decision; never throws.
+ */
+async function ensureUserAuthenticated(client, options) {
+    if (!isGateEnabled()) {
+        const decision = {
+            proceed: true,
+            mode: "disabled",
+            reason: "ORY_AUTH_GATE is not enabled",
+        };
+        recordAuthSpan(client, decision);
+        return decision;
+    }
+    try {
+        const decision = await runGate(client, options);
+        attachUserPrincipal(client, decision);
+        recordAuthSpan(client, decision);
+        return decision;
+    }
+    catch (err) {
+        const decision = {
+            proceed: !options.allowBlock,
+            mode: "error",
+            reason: err instanceof Error ? err.message : String(err),
+        };
+        recordAuthSpan(client, decision);
+        return decision;
+    }
+}
+/**
+ * Attach the resolved user identity to the client so downstream
+ * permission checks and trace spans can reference it. Only fires for
+ * modes that actually authenticated a user — declined/skipped/error
+ * leave the principal alone.
+ */
+function attachUserPrincipal(client, decision) {
+    if (decision.mode === "ok" || decision.mode === "refreshed") {
+        // Tokens were just persisted (or are still valid); pull them so
+        // downstream code (e.g. the agent gate's DCR flow) can use the
+        // user's bearer as an initial access token.
+        const tokens = (0, auth_store_js_1.loadTokens)();
+        const subject = decision.subject ?? tokens?.subject;
+        const principal = {};
+        if (subject)
+            principal.subject = subject;
+        if (tokens?.accessToken)
+            principal.token = tokens.accessToken;
+        if (principal.subject || principal.token) {
+            client.setUserPrincipal(principal);
+        }
+        return;
+    }
+    if (decision.mode === "env_token") {
+        const subject = process.env.ORY_USER_SUBJECT_ID;
+        const token = process.env.ORY_USER_SESSION_TOKEN ??
+            process.env.ORY_USER_OAUTH2_TOKEN ??
+            process.env.ORY_SESSION_TOKEN ??
+            process.env.ORY_OAUTH2_TOKEN;
+        client.setUserPrincipal({
+            ...(subject ? { subject } : {}),
+            ...(token ? { token } : {}),
+        });
+    }
+}
+async function runGate(client, options) {
+    const ttyCheck = options.isTtyAvailableFn ?? cli_js_1.isTtyAvailable;
+    const tty = ttyCheck();
+    let resolved = (0, config_js_1.resolveConfig)();
+    if (resolved.auditOnly) {
+        return {
+            proceed: true,
+            mode: "audit_only",
+            reason: "Configured for audit-only mode; auth gate is a no-op",
+        };
+    }
+    // 1. Project URL.
+    if (!resolved.projectUrl) {
+        if (!tty) {
+            return {
+                proceed: !options.allowBlock,
+                mode: "skipped",
+                reason: "No ORY_PROJECT_URL configured and no TTY to prompt",
+            };
+        }
+        const promptFn = options.promptForProjectUrlFn ?? cli_js_1.promptForProjectUrl;
+        const url = await promptFn(options.binName);
+        if (!url) {
+            return {
+                proceed: !options.allowBlock,
+                mode: "declined",
+                reason: "User declined to enter an Ory project URL",
+            };
+        }
+        resolved = (0, config_js_1.resolveConfig)();
+        if (!resolved.projectUrl) {
+            return {
+                proceed: !options.allowBlock,
+                mode: "error",
+                reason: "Project URL was entered but config did not persist",
+            };
+        }
+    }
+    // 2. Pre-supplied env tokens short-circuit the browser flow (CI, scripted runs).
+    if (process.env.ORY_SESSION_TOKEN || process.env.ORY_OAUTH2_TOKEN) {
+        return {
+            proceed: true,
+            mode: "env_token",
+            reason: "Session/OAuth2 token supplied via environment",
+        };
+    }
+    // 3. Persisted tokens.
+    const existing = (0, auth_store_js_1.loadTokens)();
+    if (existing && !(0, auth_store_js_1.isExpired)(existing)) {
+        return {
+            proceed: true,
+            mode: "ok",
+            reason: "Re-using persisted access token",
+            subject: existing.subject,
+        };
+    }
+    if (existing && existing.refreshToken) {
+        const cid = clientId() ?? existing.clientId;
+        if (cid) {
+            try {
+                const refreshed = await (0, auth_store_js_1.refreshAndSave)({
+                    projectUrl: resolved.projectUrl,
+                    clientId: cid,
+                    current: existing,
+                });
+                return {
+                    proceed: true,
+                    mode: "refreshed",
+                    reason: "Refreshed access token via refresh_token",
+                    subject: refreshed.subject,
+                };
+            }
+            catch (err) {
+                // Fall through to browser login.
+                client.logger.warn("auth.refresh_failed", {
+                    message: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    // 4. Browser flow. Requires a registered OAuth2 client id.
+    const cid = clientId();
+    if (!cid) {
+        return {
+            proceed: !options.allowBlock,
+            mode: "skipped",
+            reason: "ORY_OAUTH2_CLIENT_ID is not set; cannot start browser login (run `npx " +
+                options.binName +
+                " configure` and register an OAuth2 client with the loopback redirect URIs)",
+        };
+    }
+    // No TTY check here on purpose: PKCE only needs a browser that can reach
+    // the loopback callback port, not stdin. `pkceLogin` prints the
+    // authorize URL to stderr so users in non-TTY environments (SSH without
+    // `-t`, `docker exec` without `-it`, IDE-integrated terminals) can still
+    // complete sign-in by pasting the URL into any browser that can reach
+    // 127.0.0.1. Truly unattended runs (CI=true) are short-circuited by
+    // `pkceLogin` itself via `detectHeadless`, and operators can bypass the
+    // gate entirely with `ORY_USER_SESSION_TOKEN` or `ORY_AUTH_GATE=0`.
+    // PKCE-flight lock so concurrent processes share a single browser flow.
+    const lock = (0, auth_store_js_1.tryAcquirePkceFlightLock)();
+    if (!lock) {
+        const peer = await (0, auth_store_js_1.waitForPeerTokens)({ timeoutMs: 90_000 });
+        if (peer) {
+            (0, auth_store_js_1.saveTokens)(peer); // refresh on-disk timestamps
+            return {
+                proceed: true,
+                mode: "ok",
+                reason: "Reused tokens from concurrent agent process",
+                subject: peer.subject,
+            };
+        }
+        return {
+            proceed: !options.allowBlock,
+            mode: "skipped",
+            reason: "Another agent process is mid-login; gave up waiting",
+        };
+    }
+    try {
+        const loginFn = options.loginFn ?? auth_js_1.pkceLogin;
+        const outcome = await loginFn({
+            projectUrl: resolved.projectUrl,
+            clientId: cid,
+        });
+        if (outcome.kind === "ok") {
+            (0, auth_store_js_1.saveTokens)(outcome.tokens);
+            return {
+                proceed: true,
+                mode: "ok",
+                reason: "Completed PKCE browser login",
+                subject: outcome.tokens.subject,
+            };
+        }
+        return {
+            proceed: !options.allowBlock,
+            mode: declineToMode(outcome.reason),
+            reason: declineMessage(outcome.reason),
+        };
+    }
+    finally {
+        lock.release();
+    }
+}
+function declineToMode(reason) {
+    switch (reason) {
+        case "user_denied":
+        case "timeout":
+        case "aborted":
+            return "declined";
+        case "headless":
+        case "no_port":
+        case "browser_launch_failed":
+            return "skipped";
+        case "state_mismatch":
+        case "token_exchange_failed":
+            return "error";
+    }
+}
+function declineMessage(reason) {
+    switch (reason) {
+        case "headless":
+            return "Browser login skipped: environment is headless (CI/SSH/no DISPLAY)";
+        case "timeout":
+            return "Browser login timed out before the user completed sign-in";
+        case "user_denied":
+            return "User declined the OAuth2 consent screen";
+        case "state_mismatch":
+            return "OAuth2 callback state did not match — possible CSRF; aborted";
+        case "no_port":
+            return "Could not bind any of the registered loopback redirect ports";
+        case "browser_launch_failed":
+            return "Failed to launch the system browser";
+        case "aborted":
+            return "Login was aborted by the caller";
+        case "token_exchange_failed":
+            return "Authorization code exchange failed at /oauth2/token";
+    }
+}
+/**
+ * @deprecated Renamed to `ensureUserAuthenticated`. The old name will be
+ * removed in a future release. The behaviour is unchanged.
+ */
+exports.ensureAuthenticated = ensureUserAuthenticated;

package/dist/auth-store.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Persistence layer for the human user's OAuth2 tokens obtained via PKCE
+ * login.
+ *
+ * Tokens live in the `user.oauth2` block of the shared config file at
+ * ~/.config/ory-agent-plugins/config.json. Reads use loadConfig(); writes
+ * go through mutateConfig() so the existing lockfile and atomic-rename
+ * machinery covers concurrent processes.
+ *
+ * In addition, this module provides a pkce-flight lock so that when two
+ * agent processes start simultaneously and neither has tokens yet, only
+ * one opens a browser and the others poll for the result.
+ */
+import { type OryOAuth2Tokens } from "./config.js";
+/** Load the user's OAuth2 tokens from the persisted config file, if any. */
+export declare function loadTokens(): OryOAuth2Tokens | undefined;
+/** Persist the user's OAuth2 tokens. Existing tokens are replaced atomically. */
+export declare function saveTokens(tokens: OryOAuth2Tokens): void;
+/** Remove the user's persisted OAuth2 tokens. */
+export declare function clearTokens(): void;
+/** Number of seconds before nominal expiry that we consider tokens stale. */
+export declare const TOKEN_EXPIRY_SKEW_SEC = 60;
+/** Returns true if the access token is missing or within the skew window of expiry. */
+export declare function isExpired(tokens: OryOAuth2Tokens, now?: number): boolean;
+/**
+ * Refresh the persisted tokens using their refresh_token. Saves the
+ * resulting tokens back to disk. Throws if no refresh token is available
+ * or if the refresh call fails.
+ */
+export declare function refreshAndSave(args: {
+    projectUrl: string;
+    clientId: string;
+    current: OryOAuth2Tokens;
+}): Promise<OryOAuth2Tokens>;
+export interface PkceFlightLock {
+    release: () => void;
+}
+/**
+ * Try to acquire the pkce-flight lock. Returns the lock handle if this
+ * caller is the leader (and should run the browser flow), or null if
+ * another process already holds the lock.
+ *
+ * The lock is a sibling file containing the holder's PID. A lock is
+ * considered stale (and reclaimed automatically) when either of these is
+ * true:
+ *
+ *   - the PID written in the file is no longer a live process, or
+ *   - the file is older than 5 minutes
+ *
+ * PID-liveness is the primary signal — it catches crashed / killed
+ * processes immediately so the next launch isn't stuck waiting. The age
+ * check is a fallback for the cross-host case (PID is meaningful only on
+ * the host that wrote it) and for PID reuse edge cases.
+ */
+export declare function tryAcquirePkceFlightLock(): PkceFlightLock | null;
+/**
+ * Unconditionally remove the pkce-flight lock, if any. Use this from
+ * single-owner contexts (e.g. the dev launcher at startup) where you
+ * know no peer is mid-flow. Returns true when a lock was removed.
+ */
+export declare function clearPkceFlightLock(): boolean;
+/**
+ * Block until another process completes the PKCE flow and writes tokens,
+ * or until the timeout elapses. Returns the tokens if they appeared in
+ * time, or null otherwise.
+ */
+export declare function waitForPeerTokens(opts?: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}): Promise<OryOAuth2Tokens | null>;
+/** Synchronous variant for callers that already block on the file system. */
+export declare function waitForPeerTokensSync(opts?: {
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}): OryOAuth2Tokens | null;

package/dist/auth-store.js

@@ -0,0 +1,261 @@
+"use strict";
+/**
+ * Persistence layer for the human user's OAuth2 tokens obtained via PKCE
+ * login.
+ *
+ * Tokens live in the `user.oauth2` block of the shared config file at
+ * ~/.config/ory-agent-plugins/config.json. Reads use loadConfig(); writes
+ * go through mutateConfig() so the existing lockfile and atomic-rename
+ * machinery covers concurrent processes.
+ *
+ * In addition, this module provides a pkce-flight lock so that when two
+ * agent processes start simultaneously and neither has tokens yet, only
+ * one opens a browser and the others poll for the result.
+ */
+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.TOKEN_EXPIRY_SKEW_SEC = void 0;
+exports.loadTokens = loadTokens;
+exports.saveTokens = saveTokens;
+exports.clearTokens = clearTokens;
+exports.isExpired = isExpired;
+exports.refreshAndSave = refreshAndSave;
+exports.tryAcquirePkceFlightLock = tryAcquirePkceFlightLock;
+exports.clearPkceFlightLock = clearPkceFlightLock;
+exports.waitForPeerTokens = waitForPeerTokens;
+exports.waitForPeerTokensSync = waitForPeerTokensSync;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const config_js_1 = require("./config.js");
+const auth_js_1 = require("./auth.js");
+const SLEEP_BUF = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms) {
+    Atomics.wait(SLEEP_BUF, 0, 0, ms);
+}
+function pkceLockPath() {
+    return (0, config_js_1.getConfigPath)() + ".pkce.lock";
+}
+/** Load the user's OAuth2 tokens from the persisted config file, if any. */
+function loadTokens() {
+    return (0, config_js_1.loadConfig)().user?.oauth2;
+}
+/** Persist the user's OAuth2 tokens. Existing tokens are replaced atomically. */
+function saveTokens(tokens) {
+    (0, config_js_1.mutateConfig)((current) => ({
+        ...current,
+        user: { ...(current.user ?? {}), oauth2: tokens },
+    }));
+}
+/** Remove the user's persisted OAuth2 tokens. */
+function clearTokens() {
+    (0, config_js_1.mutateConfig)((current) => {
+        const next = { ...current };
+        if (!next.user)
+            return next;
+        const user = { ...next.user };
+        delete user.oauth2;
+        if (Object.keys(user).length === 0)
+            delete next.user;
+        else
+            next.user = user;
+        return next;
+    });
+}
+/** Number of seconds before nominal expiry that we consider tokens stale. */
+exports.TOKEN_EXPIRY_SKEW_SEC = 60;
+/** Returns true if the access token is missing or within the skew window of expiry. */
+function isExpired(tokens, now = Date.now()) {
+    if (!tokens.accessToken)
+        return true;
+    const nowSec = Math.floor(now / 1000);
+    return tokens.expiresAt - exports.TOKEN_EXPIRY_SKEW_SEC <= nowSec;
+}
+/**
+ * Refresh the persisted tokens using their refresh_token. Saves the
+ * resulting tokens back to disk. Throws if no refresh token is available
+ * or if the refresh call fails.
+ */
+async function refreshAndSave(args) {
+    if (!args.current.refreshToken) {
+        throw new Error("No refresh_token available; a fresh login is required.");
+    }
+    const next = await (0, auth_js_1.refreshAccessToken)({
+        projectUrl: args.projectUrl,
+        clientId: args.clientId,
+        refreshToken: args.current.refreshToken,
+    });
+    saveTokens(next);
+    return next;
+}
+/**
+ * Try to acquire the pkce-flight lock. Returns the lock handle if this
+ * caller is the leader (and should run the browser flow), or null if
+ * another process already holds the lock.
+ *
+ * The lock is a sibling file containing the holder's PID. A lock is
+ * considered stale (and reclaimed automatically) when either of these is
+ * true:
+ *
+ *   - the PID written in the file is no longer a live process, or
+ *   - the file is older than 5 minutes
+ *
+ * PID-liveness is the primary signal — it catches crashed / killed
+ * processes immediately so the next launch isn't stuck waiting. The age
+ * check is a fallback for the cross-host case (PID is meaningful only on
+ * the host that wrote it) and for PID reuse edge cases.
+ */
+function tryAcquirePkceFlightLock() {
+    ensureDir(path.dirname((0, config_js_1.getConfigPath)()));
+    const file = pkceLockPath();
+    try {
+        const fd = fs.openSync(file, "wx", 0o600);
+        fs.writeSync(fd, String(process.pid));
+        fs.closeSync(fd);
+        return { release: () => releasePkceFlightLock() };
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    // Lock exists. Reclaim it if the holder is dead or the file is old.
+    if (isLockStale(file)) {
+        try {
+            fs.unlinkSync(file);
+        }
+        catch {
+            /* ignore — another process may have just cleaned it */
+        }
+        return tryAcquirePkceFlightLock();
+    }
+    return null;
+}
+function isLockStale(file) {
+    let stat;
+    try {
+        stat = fs.statSync(file);
+    }
+    catch {
+        // File vanished between EEXIST and stat — treat as stale so the
+        // caller retries cleanly.
+        return true;
+    }
+    // Age fallback: any lock older than 5 minutes is reclaimable.
+    if (Date.now() - stat.mtimeMs > 5 * 60_000)
+        return true;
+    // Primary check: is the PID still alive on this host?
+    let pid;
+    try {
+        pid = parseInt(fs.readFileSync(file, "utf8").trim(), 10);
+    }
+    catch {
+        return true;
+    }
+    if (!Number.isFinite(pid) || pid <= 0)
+        return true;
+    if (pid === process.pid)
+        return false; // we hold it ourselves
+    try {
+        // Signal 0 doesn't deliver a signal — it just checks whether the
+        // process exists and we have permission to signal it. ESRCH means
+        // no such process; EPERM means it exists but we can't signal it
+        // (still alive). Anything else: assume dead.
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "EPERM")
+            return false;
+        return true;
+    }
+}
+/**
+ * Unconditionally remove the pkce-flight lock, if any. Use this from
+ * single-owner contexts (e.g. the dev launcher at startup) where you
+ * know no peer is mid-flow. Returns true when a lock was removed.
+ */
+function clearPkceFlightLock() {
+    try {
+        fs.unlinkSync(pkceLockPath());
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return false;
+        return false;
+    }
+}
+function releasePkceFlightLock() {
+    try {
+        fs.unlinkSync(pkceLockPath());
+    }
+    catch {
+        /* ignore */
+    }
+}
+function ensureDir(dir) {
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+}
+/**
+ * Block until another process completes the PKCE flow and writes tokens,
+ * or until the timeout elapses. Returns the tokens if they appeared in
+ * time, or null otherwise.
+ */
+async function waitForPeerTokens(opts) {
+    const timeout = opts?.timeoutMs ?? 60_000;
+    const interval = opts?.pollIntervalMs ?? 250;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        const tokens = loadTokens();
+        if (tokens && !isExpired(tokens))
+            return tokens;
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+    return null;
+}
+/** Synchronous variant for callers that already block on the file system. */
+function waitForPeerTokensSync(opts) {
+    const timeout = opts?.timeoutMs ?? 60_000;
+    const interval = opts?.pollIntervalMs ?? 250;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+        const tokens = loadTokens();
+        if (tokens && !isExpired(tokens))
+            return tokens;
+        sleepSync(interval);
+    }
+    return null;
+}