@ory/argus 0.1.0

package/dist/agent-auth.js

@@ -0,0 +1,553 @@
+"use strict";
+/**
+ * Agent identity resolution.
+ *
+ * The "agent" is the AI process making calls on behalf of the human
+ * user. Unlike the user, the agent never authenticates interactively.
+ * The default path is **OAuth2 Dynamic Client Registration (RFC 7591)**:
+ * on first run the agent registers itself with the project's
+ * `/oauth2/register` endpoint, authenticated by the user's bearer token
+ * (or an out-of-band initial access token), and persists the issued
+ * credentials so subsequent runs reuse them.
+ *
+ * Resolution order:
+ *
+ *   1. ORY_AGENT_API_KEY                  — explicit static bearer
+ *   2. ORY_AGENT_CLIENT_ID +
+ *      ORY_AGENT_CLIENT_SECRET           — explicit static client_credentials
+ *   3. Persisted dynamic credentials      — reuse a prior DCR registration
+ *   4. Fresh dynamic registration         — POST /oauth2/register using the
+ *                                            user's bearer or
+ *                                            ORY_AGENT_REGISTRATION_TOKEN
+ *   5. ORY_API_KEY (deprecated)          — alias for ORY_AGENT_API_KEY
+ *   6. <none>                            — fail-open; plugin runs without
+ *                                            agent identity in audit logs
+ *
+ * Token-exchange (RFC 8693) — deriving an agent token whose `sub` is
+ * the user with an `act` claim showing the agent — is intentionally
+ * deferred.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = void 0;
+exports._resetAgentCredentialsCache = _resetAgentCredentialsCache;
+exports.loadSubAgentDynamicCredentials = loadSubAgentDynamicCredentials;
+exports.saveSubAgentDynamicCredentials = saveSubAgentDynamicCredentials;
+exports.clearSubAgentDynamicCredentials = clearSubAgentDynamicCredentials;
+exports.loadAgentDynamicCredentials = loadAgentDynamicCredentials;
+exports.saveAgentDynamicCredentials = saveAgentDynamicCredentials;
+exports.clearAgentDynamicCredentials = clearAgentDynamicCredentials;
+exports.registerAgentClient = registerAgentClient;
+exports.resolveAgentCredentials = resolveAgentCredentials;
+exports.fetchClientCredentialsToken = fetchClientCredentialsToken;
+exports.ensureAgentIdentity = ensureAgentIdentity;
+exports.ensureSubAgentIdentity = ensureSubAgentIdentity;
+const node_os_1 = require("node:os");
+const client_1 = require("@ory/client");
+const config_js_1 = require("./config.js");
+/**
+ * Skew window before nominal expiry at which a cached client_credentials
+ * token is considered stale. Matches the user-token skew in auth-store.
+ */
+exports.AGENT_TOKEN_EXPIRY_SKEW_SEC = 60;
+const ccCache = new Map();
+/** Drop all cached agent client_credentials tokens. Tests only. */
+function _resetAgentCredentialsCache() {
+    ccCache.clear();
+}
+// ─── Sub-agent persistence ───────────────────────────────────────────
+/** Load persisted sub-agent DCR credentials keyed by sub-agent type. */
+function loadSubAgentDynamicCredentials(subAgentType) {
+    return (0, config_js_1.loadConfig)().agent?.subAgents?.[subAgentType];
+}
+/** Persist sub-agent DCR credentials under the given type key. */
+function saveSubAgentDynamicCredentials(subAgentType, creds) {
+    (0, config_js_1.mutateConfig)((current) => {
+        const agent = { ...(current.agent ?? {}) };
+        const subAgents = { ...(agent.subAgents ?? {}) };
+        subAgents[subAgentType] = creds;
+        agent.subAgents = subAgents;
+        return { ...current, agent };
+    });
+}
+/** Remove persisted sub-agent DCR credentials for the given type. */
+function clearSubAgentDynamicCredentials(subAgentType) {
+    (0, config_js_1.mutateConfig)((current) => {
+        const next = { ...current };
+        if (!next.agent?.subAgents)
+            return next;
+        const agent = { ...next.agent };
+        const subAgents = { ...agent.subAgents };
+        delete subAgents[subAgentType];
+        if (Object.keys(subAgents).length === 0)
+            delete agent.subAgents;
+        else
+            agent.subAgents = subAgents;
+        if (!agent.dynamic && !agent.subAgents)
+            delete next.agent;
+        else
+            next.agent = agent;
+        return next;
+    });
+}
+// ─── Dynamic registration persistence ────────────────────────────────
+/** Load persisted DCR credentials from the shared config file. */
+function loadAgentDynamicCredentials() {
+    return (0, config_js_1.loadConfig)().agent?.dynamic;
+}
+/** Persist DCR credentials. Existing credentials are replaced atomically. */
+function saveAgentDynamicCredentials(creds) {
+    (0, config_js_1.mutateConfig)((current) => ({
+        ...current,
+        agent: { ...(current.agent ?? {}), dynamic: creds },
+    }));
+}
+/** Remove persisted DCR credentials (e.g. after revocation or unregister). */
+function clearAgentDynamicCredentials() {
+    (0, config_js_1.mutateConfig)((current) => {
+        const next = { ...current };
+        if (!next.agent)
+            return next;
+        const agent = { ...next.agent };
+        delete agent.dynamic;
+        if (Object.keys(agent).length === 0)
+            delete next.agent;
+        else
+            next.agent = agent;
+        return next;
+    });
+}
+/**
+ * Register a new OAuth2 client via RFC 7591. Authorization is carried
+ * either by the user's interactive token (the natural bootstrap) or by
+ * a pre-issued initial access token (`ORY_AGENT_REGISTRATION_TOKEN`).
+ * Throws on any non-2xx response so callers can decide whether to
+ * retry, fall back, or surface the error in the audit span. The
+ * `HTTP <status>` error message shape is preserved so callers and tests
+ * can pattern-match on it regardless of the underlying transport.
+ */
+async function registerAgentClient(args) {
+    const host = (args.hostnameFn ?? node_os_1.hostname)() || "unknown-host";
+    const clientName = args.harness
+        ? `ory-agent-${args.harness}@${host}`
+        : `ory-agent@${host}`;
+    const oidc = new client_1.OidcApi(new client_1.Configuration({
+        basePath: args.projectUrl,
+        accessToken: args.auth,
+    }));
+    let response;
+    try {
+        response = await oidc.createOidcDynamicClient({
+            oAuth2Client: {
+                client_name: clientName,
+                grant_types: ["client_credentials"],
+                response_types: ["token"],
+                scope: "openid offline_access",
+                token_endpoint_auth_method: "client_secret_post",
+            },
+        });
+    }
+    catch (err) {
+        const status = err?.response?.status;
+        if (typeof status === "number") {
+            throw new Error(`HTTP ${status}`);
+        }
+        throw err;
+    }
+    const client = response.data;
+    if (!client.client_id || client.client_id.length === 0) {
+        throw new Error("Registration response missing client_id");
+    }
+    return {
+        clientId: client.client_id,
+        clientSecret: client.client_secret,
+        registrationAccessToken: client.registration_access_token,
+        registrationClientUri: client.registration_client_uri,
+        registeredAt: Math.floor(Date.now() / 1000),
+        projectUrl: args.projectUrl,
+        harness: args.harness,
+    };
+}
+/**
+ * Resolve the agent's credentials from environment configuration and
+ * persisted state. Never throws — failures collapse to `kind: "none"`
+ * so the caller can fail open.
+ */
+async function resolveAgentCredentials(options = {}) {
+    const env = options.env ?? process.env;
+    const warnings = [];
+    const fetchCcFn = options.fetchClientCredentialsTokenFn ?? fetchClientCredentialsToken;
+    const registerFn = options.registerAgentClientFn ?? registerAgentClient;
+    const loadDynamicFn = options.loadDynamicFn ?? loadAgentDynamicCredentials;
+    const saveDynamicFn = options.saveDynamicFn ?? saveAgentDynamicCredentials;
+    const clearDynamicFn = options.clearDynamicFn ?? clearAgentDynamicCredentials;
+    const skipCache = options.skipCache ?? false;
+    // 1. Explicit static API key — operator override.
+    const apiKey = env.ORY_AGENT_API_KEY;
+    if (apiKey && apiKey.length > 0) {
+        return {
+            kind: "api_key",
+            token: apiKey,
+            subject: env.ORY_AGENT_SUBJECT_ID,
+            reason: "Resolved agent identity from ORY_AGENT_API_KEY",
+            warnings,
+        };
+    }
+    // 2. Explicit static client_credentials — operator override.
+    const clientId = env.ORY_AGENT_CLIENT_ID;
+    const clientSecret = env.ORY_AGENT_CLIENT_SECRET;
+    if (clientId && clientSecret) {
+        if (!options.projectUrl) {
+            return {
+                kind: "none",
+                reason: "ORY_AGENT_CLIENT_ID is set but ORY_PROJECT_URL is missing; cannot run client_credentials grant",
+                warnings,
+            };
+        }
+        return await resolveClientCredentials({
+            projectUrl: options.projectUrl,
+            clientId,
+            clientSecret,
+            audience: env.ORY_AGENT_AUDIENCE,
+            scope: env.ORY_AGENT_SCOPE,
+            subjectOverride: env.ORY_AGENT_SUBJECT_ID,
+            kind: "client_credentials",
+            fetchFn: fetchCcFn,
+            skipCache,
+            warnings,
+        });
+    }
+    // 3. Persisted dynamic registration — re-use a prior DCR run.
+    if (options.projectUrl) {
+        const persisted = loadDynamicFn();
+        if (persisted && persisted.projectUrl === options.projectUrl && persisted.clientSecret) {
+            const result = await resolveClientCredentials({
+                projectUrl: options.projectUrl,
+                clientId: persisted.clientId,
+                clientSecret: persisted.clientSecret,
+                audience: env.ORY_AGENT_AUDIENCE,
+                scope: env.ORY_AGENT_SCOPE,
+                subjectOverride: env.ORY_AGENT_SUBJECT_ID,
+                kind: "dynamic",
+                fetchFn: fetchCcFn,
+                skipCache,
+                warnings,
+            });
+            if (result.kind !== "none")
+                return result;
+            // Server rejected the persisted creds — clear and fall through to
+            // a fresh registration attempt.
+            warnings.push(`Persisted dynamic agent credentials rejected (${result.reason}); re-registering.`);
+            clearDynamicFn();
+        }
+    }
+    // 4. Fresh dynamic registration — bootstrap using the user's bearer
+    //    or an out-of-band initial access token.
+    const iat = options.userToken ?? env.ORY_AGENT_REGISTRATION_TOKEN;
+    if (options.projectUrl && iat) {
+        try {
+            const registered = await registerFn({
+                projectUrl: options.projectUrl,
+                auth: iat,
+                harness: options.harness,
+            });
+            if (!registered.clientSecret) {
+                warnings.push("Dynamic registration returned no client_secret; cannot run client_credentials grant.");
+            }
+            else {
+                saveDynamicFn(registered);
+                const result = await resolveClientCredentials({
+                    projectUrl: options.projectUrl,
+                    clientId: registered.clientId,
+                    clientSecret: registered.clientSecret,
+                    audience: env.ORY_AGENT_AUDIENCE,
+                    scope: env.ORY_AGENT_SCOPE,
+                    subjectOverride: env.ORY_AGENT_SUBJECT_ID,
+                    kind: "dynamic",
+                    fetchFn: fetchCcFn,
+                    skipCache: true, // freshly registered, no stale cache
+                    warnings,
+                });
+                if (result.kind !== "none")
+                    return result;
+                warnings.push(`Token grant failed immediately after registration (${result.reason}).`);
+            }
+        }
+        catch (err) {
+            warnings.push(`Dynamic client registration failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // 5. Deprecated ORY_API_KEY alias.
+    const legacyApiKey = env.ORY_API_KEY;
+    if (legacyApiKey && legacyApiKey.length > 0) {
+        warnings.push("ORY_API_KEY is deprecated for agent authentication — set ORY_AGENT_API_KEY instead");
+        return {
+            kind: "api_key",
+            token: legacyApiKey,
+            subject: env.ORY_AGENT_SUBJECT_ID,
+            reason: "Resolved agent identity from ORY_API_KEY (deprecated alias)",
+            warnings,
+        };
+    }
+    return {
+        kind: "none",
+        reason: "No agent credentials configured. Run with a user session (ORY_AUTH_GATE=1) or set ORY_AGENT_API_KEY / ORY_AGENT_CLIENT_ID + ORY_AGENT_CLIENT_SECRET / ORY_AGENT_REGISTRATION_TOKEN.",
+        warnings,
+    };
+}
+async function resolveClientCredentials(args) {
+    const cacheKey = `${args.kind}:${args.clientId}@${args.projectUrl}`;
+    const nowSec = Math.floor(Date.now() / 1000);
+    const reasonNoun = args.kind === "dynamic" ? "dynamic" : "static";
+    if (!args.skipCache) {
+        const cached = ccCache.get(cacheKey);
+        if (cached && cached.expiresAt - exports.AGENT_TOKEN_EXPIRY_SKEW_SEC > nowSec) {
+            return {
+                kind: args.kind,
+                token: cached.token,
+                subject: args.subjectOverride ?? cached.subject,
+                expiresAt: cached.expiresAt,
+                reason: `Re-using cached agent ${reasonNoun} token`,
+                warnings: args.warnings,
+            };
+        }
+    }
+    try {
+        const result = await args.fetchFn({
+            projectUrl: args.projectUrl,
+            clientId: args.clientId,
+            clientSecret: args.clientSecret,
+            audience: args.audience,
+            scope: args.scope,
+        });
+        ccCache.set(cacheKey, {
+            token: result.accessToken,
+            subject: args.subjectOverride ?? args.clientId,
+            expiresAt: result.expiresAt,
+        });
+        return {
+            kind: args.kind,
+            token: result.accessToken,
+            subject: args.subjectOverride ?? args.clientId,
+            expiresAt: result.expiresAt,
+            reason: `Fetched agent token via OAuth2 client_credentials grant (${reasonNoun})`,
+            warnings: args.warnings,
+        };
+    }
+    catch (err) {
+        return {
+            kind: "none",
+            reason: `${reasonNoun} client_credentials grant failed: ${err instanceof Error ? err.message : String(err)}`,
+            warnings: args.warnings,
+        };
+    }
+}
+// Kept as raw fetch (rather than @ory/client's OAuth2Api.oauth2TokenExchange)
+// because the SDK method's signature does not expose client_secret, audience,
+// or scope — all of which this grant needs. Ory's own SDK docstring on that
+// method says it should not be used via the SDK.
+/** POST /oauth2/token with grant_type=client_credentials. */
+async function fetchClientCredentialsToken(args) {
+    const body = new URLSearchParams({
+        grant_type: "client_credentials",
+        client_id: args.clientId,
+        client_secret: args.clientSecret,
+    });
+    if (args.scope)
+        body.set("scope", args.scope);
+    if (args.audience)
+        body.set("audience", args.audience);
+    const tokenUrl = new 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(`HTTP ${res.status}`);
+    }
+    const json = (await res.json());
+    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;
+    return {
+        accessToken,
+        expiresAt: Math.floor(Date.now() / 1000) + expiresIn,
+        scope: typeof json.scope === "string" ? json.scope : undefined,
+    };
+}
+/**
+ * Resolve the agent's credentials and attach them to the client.
+ *
+ * Always returns the resolved credentials; never throws and never blocks.
+ * Emits exactly one `agent.auth` span so the audit trail records whether
+ * the agent identity was available for the session.
+ */
+async function ensureAgentIdentity(client, options = {}) {
+    const resolveFn = options.resolveFn ?? resolveAgentCredentials;
+    let creds;
+    try {
+        creds = await resolveFn({
+            projectUrl: options.projectUrl,
+            env: options.env,
+            // The user gate populates userPrincipal.token on successful login;
+            // we hand it to the resolver so DCR can use it as the IAT.
+            userToken: client.userPrincipal.token,
+            harness: options.harness,
+        });
+    }
+    catch (err) {
+        creds = {
+            kind: "none",
+            reason: `Agent credential resolution threw: ${err instanceof Error ? err.message : String(err)}`,
+            warnings: [],
+        };
+    }
+    for (const warning of creds.warnings) {
+        client.logger.warn("agent.auth.warning", { message: warning });
+    }
+    if (creds.kind === "none") {
+        client.logger.warn("agent.auth.none", { reason: creds.reason });
+    }
+    if (creds.token) {
+        client.setAgentPrincipal({ token: creds.token, subject: creds.subject });
+    }
+    // When no credentials were resolved, leave the existing principal in
+    // place. The constructor may have seeded one from `config.apiKey` for
+    // backward compat, and "no resolver match" should not clear it.
+    client.tracer.record("agent.auth", creds.kind === "none" ? "skipped" : "ok", {
+        attributes: {
+            kind: creds.kind,
+            reason: creds.reason,
+            ...(creds.subject ? { subject: creds.subject } : {}),
+            ...(creds.expiresAt ? { expiresAt: creds.expiresAt } : {}),
+        },
+    });
+    return creds;
+}
+/**
+ * Resolve a sub-agent identity via OAuth2 Dynamic Client Registration.
+ *
+ * Reuses persisted credentials when the `(projectUrl, subAgentType)`
+ * pair matches; otherwise registers a fresh client with
+ * `client_name = ory-subagent-<type>@<host>` and persists the result.
+ * Never throws and never blocks — on any failure the identity collapses
+ * to `kind: "none"` and the plugin continues without it. Emits exactly
+ * one `agent.auth` span so the audit trail records each sub-agent
+ * resolution.
+ */
+async function ensureSubAgentIdentity(client, options) {
+    const env = options.env ?? process.env;
+    const registerFn = options.registerAgentClientFn ?? registerAgentClient;
+    const loadFn = options.loadFn ?? loadSubAgentDynamicCredentials;
+    const saveFn = options.saveFn ?? saveSubAgentDynamicCredentials;
+    const warnings = [];
+    let identity;
+    try {
+        identity = await resolveSubAgentIdentity({
+            subAgentType: options.subAgentType,
+            projectUrl: options.projectUrl,
+            harness: options.harness,
+            iat: options.iat
+                ?? client.agentPrincipal.token
+                ?? client.userPrincipal.token
+                ?? env.ORY_AGENT_REGISTRATION_TOKEN,
+            registerFn,
+            loadFn,
+            saveFn,
+            warnings,
+        });
+    }
+    catch (err) {
+        identity = {
+            kind: "none",
+            subAgentType: options.subAgentType,
+            reason: `Sub-agent identity resolution threw: ${err instanceof Error ? err.message : String(err)}`,
+            warnings,
+        };
+    }
+    for (const warning of identity.warnings) {
+        client.logger.warn("agent.auth.warning", {
+            message: warning,
+            subAgentType: options.subAgentType,
+        });
+    }
+    if (identity.kind === "none") {
+        client.logger.warn("agent.auth.none", {
+            reason: identity.reason,
+            subAgentType: options.subAgentType,
+        });
+    }
+    client.tracer.record("agent.auth", identity.kind === "none" ? "skipped" : "ok", {
+        attributes: {
+            kind: identity.kind === "dynamic" ? "subagent_dynamic" : "subagent_none",
+            subAgentType: identity.subAgentType,
+            reason: identity.reason,
+            ...(identity.subject ? { subject: identity.subject } : {}),
+        },
+    });
+    return identity;
+}
+async function resolveSubAgentIdentity(args) {
+    if (!args.projectUrl) {
+        return {
+            kind: "none",
+            subAgentType: args.subAgentType,
+            reason: "ORY_PROJECT_URL is missing; cannot register sub-agent identity",
+            warnings: args.warnings,
+        };
+    }
+    // 1. Re-use persisted credentials if they match the current project URL.
+    const persisted = args.loadFn(args.subAgentType);
+    if (persisted && persisted.projectUrl === args.projectUrl) {
+        return {
+            kind: "dynamic",
+            subAgentType: args.subAgentType,
+            subject: persisted.clientId,
+            credentials: persisted,
+            reason: `Re-using persisted sub-agent registration for ${args.subAgentType}`,
+            warnings: args.warnings,
+        };
+    }
+    // 2. Need an IAT to register. The parent agent's token is preferred;
+    //    the user's token is the fallback. Neither available ⇒ no identity.
+    if (!args.iat) {
+        return {
+            kind: "none",
+            subAgentType: args.subAgentType,
+            reason: "No initial access token available for sub-agent registration "
+                + "(neither agent nor user principal is populated, and "
+                + "ORY_AGENT_REGISTRATION_TOKEN is unset).",
+            warnings: args.warnings,
+        };
+    }
+    // 3. Fresh DCR. client_name is namespaced under sub-agent so audit logs
+    //    can distinguish it from the top-level agent registration.
+    const subHarness = args.harness
+        ? `${args.harness}-subagent-${args.subAgentType}`
+        : `subagent-${args.subAgentType}`;
+    try {
+        const registered = await args.registerFn({
+            projectUrl: args.projectUrl,
+            auth: args.iat,
+            harness: subHarness,
+        });
+        args.saveFn(args.subAgentType, registered);
+        return {
+            kind: "dynamic",
+            subAgentType: args.subAgentType,
+            subject: registered.clientId,
+            credentials: registered,
+            reason: `Registered sub-agent ${args.subAgentType} via DCR (RFC 7591)`,
+            warnings: args.warnings,
+        };
+    }
+    catch (err) {
+        return {
+            kind: "none",
+            subAgentType: args.subAgentType,
+            reason: `Sub-agent DCR failed: ${err instanceof Error ? err.message : String(err)}`,
+            warnings: args.warnings,
+        };
+    }
+}

package/dist/auth-gate.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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).
+ */
+import { OryAgentClient } from "./client.js";
+import { type OryOAuth2Tokens } from "./config.js";
+import { promptForProjectUrl } from "./cli.js";
+import { pkceLogin } from "./auth.js";
+export type AuthGateMode = "disabled" | "audit_only" | "env_token" | "ok" | "refreshed" | "skipped" | "declined" | "error";
+export interface AuthGateOptions {
+    /** Bin name used in user-facing prompts (e.g. "ory-claude"). */
+    binName: string;
+    /** Logical harness name (used by the tracer). */
+    harness: string;
+    /** Whether the caller can hard-block on auth failure. */
+    allowBlock: boolean;
+    /**
+     * Optional override of the PKCE login function — used by tests and by
+     * harnesses that want to plug in a different flow.
+     */
+    loginFn?: typeof pkceLogin;
+    /** Override TTY detection (for tests). */
+    isTtyAvailableFn?: () => boolean;
+    /** Override the prompt-for-URL step (for tests). */
+    promptForProjectUrlFn?: typeof promptForProjectUrl;
+}
+export interface AuthGateDecision {
+    /** Whether the caller should let the session proceed. */
+    proceed: boolean;
+    /** Stable mode identifier for telemetry and tests. */
+    mode: AuthGateMode;
+    /** Human-readable reason; safe to surface to the operator. */
+    reason: string;
+    /** Subject (sub claim) when authenticated. */
+    subject?: string;
+}
+/**
+ * The entry point that every plugin's session-start handler should call
+ * to authenticate the human user. Always returns a decision; never throws.
+ */
+export declare function ensureUserAuthenticated(client: OryAgentClient, options: AuthGateOptions): Promise<AuthGateDecision>;
+/** Re-export so callers don't need to import auth.ts directly. */
+export type { OryOAuth2Tokens };
+/**
+ * @deprecated Renamed to `ensureUserAuthenticated`. The old name will be
+ * removed in a future release. The behaviour is unchanged.
+ */
+export declare const ensureAuthenticated: typeof ensureUserAuthenticated;