@ory/argus 0.1.0

package/dist/agent-auth.d.ts

@@ -0,0 +1,204 @@
+/**
+ * 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.
+ */
+import { type OryAgentDynamicCredentials } from "./config.js";
+import { OryAgentClient } from "./client.js";
+export type AgentCredentialKind = "api_key" | "client_credentials" | "dynamic" | "none";
+export interface AgentCredentials {
+    kind: AgentCredentialKind;
+    /** Bearer token to attach to outgoing Ory API calls. */
+    token?: string;
+    /** Subject (sub) the token represents — usually the client_id. */
+    subject?: string;
+    /** Unix epoch seconds at which the token expires (client_credentials only). */
+    expiresAt?: number;
+    /**
+     * One-line reason for the resolved kind, suitable for telemetry.
+     * Distinguishes e.g. "no env credentials configured" vs "client_credentials
+     * grant failed: HTTP 401".
+     */
+    reason: string;
+    /**
+     * Diagnostic warnings raised during resolution (e.g. ORY_API_KEY used
+     * via deprecated alias). Never blocks resolution.
+     */
+    warnings: string[];
+}
+export interface ResolveAgentCredentialsOptions {
+    /** Ory project URL — required for client_credentials grant + DCR. */
+    projectUrl?: string;
+    /** Env override (defaults to process.env). */
+    env?: NodeJS.ProcessEnv;
+    /** User's bearer token; preferred IAT for dynamic registration. */
+    userToken?: string;
+    /** Harness identifier — baked into the registered client_name. */
+    harness?: string;
+    /** Inject the client_credentials token-grant function for tests. */
+    fetchClientCredentialsTokenFn?: typeof fetchClientCredentialsToken;
+    /** Inject the DCR registration call for tests. */
+    registerAgentClientFn?: typeof registerAgentClient;
+    /** Inject persisted-credential read/write/clear for tests. */
+    loadDynamicFn?: typeof loadAgentDynamicCredentials;
+    saveDynamicFn?: typeof saveAgentDynamicCredentials;
+    clearDynamicFn?: typeof clearAgentDynamicCredentials;
+    /** Bypass the in-memory cache (tests). */
+    skipCache?: boolean;
+}
+/**
+ * Skew window before nominal expiry at which a cached client_credentials
+ * token is considered stale. Matches the user-token skew in auth-store.
+ */
+export declare const AGENT_TOKEN_EXPIRY_SKEW_SEC = 60;
+/** Drop all cached agent client_credentials tokens. Tests only. */
+export declare function _resetAgentCredentialsCache(): void;
+/** Load persisted sub-agent DCR credentials keyed by sub-agent type. */
+export declare function loadSubAgentDynamicCredentials(subAgentType: string): OryAgentDynamicCredentials | undefined;
+/** Persist sub-agent DCR credentials under the given type key. */
+export declare function saveSubAgentDynamicCredentials(subAgentType: string, creds: OryAgentDynamicCredentials): void;
+/** Remove persisted sub-agent DCR credentials for the given type. */
+export declare function clearSubAgentDynamicCredentials(subAgentType: string): void;
+/** Load persisted DCR credentials from the shared config file. */
+export declare function loadAgentDynamicCredentials(): OryAgentDynamicCredentials | undefined;
+/** Persist DCR credentials. Existing credentials are replaced atomically. */
+export declare function saveAgentDynamicCredentials(creds: OryAgentDynamicCredentials): void;
+/** Remove persisted DCR credentials (e.g. after revocation or unregister). */
+export declare function clearAgentDynamicCredentials(): void;
+export interface RegisterAgentClientArgs {
+    projectUrl: string;
+    /** Bearer used as the initial access token (RFC 7591 §3). */
+    auth: string;
+    /** Harness identifier baked into the client_name for audit. */
+    harness?: string;
+    /** Override hostname for testing. */
+    hostnameFn?: () => string;
+}
+/**
+ * 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.
+ */
+export declare function registerAgentClient(args: RegisterAgentClientArgs): Promise<OryAgentDynamicCredentials>;
+/**
+ * Resolve the agent's credentials from environment configuration and
+ * persisted state. Never throws — failures collapse to `kind: "none"`
+ * so the caller can fail open.
+ */
+export declare function resolveAgentCredentials(options?: ResolveAgentCredentialsOptions): Promise<AgentCredentials>;
+interface ClientCredentialsTokenArgs {
+    projectUrl: string;
+    clientId: string;
+    clientSecret: string;
+    audience?: string;
+    scope?: string;
+}
+interface ClientCredentialsTokenResult {
+    accessToken: string;
+    expiresAt: number;
+    scope?: string;
+}
+/** POST /oauth2/token with grant_type=client_credentials. */
+export declare function fetchClientCredentialsToken(args: ClientCredentialsTokenArgs): Promise<ClientCredentialsTokenResult>;
+export interface EnsureAgentIdentityOptions {
+    /** Project URL for client_credentials grant + DCR. Defaults to resolveConfig(). */
+    projectUrl?: string;
+    /** Harness identifier baked into a fresh DCR client_name. */
+    harness?: string;
+    /** Env override (defaults to process.env). */
+    env?: NodeJS.ProcessEnv;
+    /** Inject resolver for tests. */
+    resolveFn?: typeof resolveAgentCredentials;
+}
+/**
+ * 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.
+ */
+export declare function ensureAgentIdentity(client: OryAgentClient, options?: EnsureAgentIdentityOptions): Promise<AgentCredentials>;
+/**
+ * Resolved identity for a sub-agent (a typed worker that the parent
+ * agent delegates to, e.g. Claude Code's `Task` tool launching an
+ * `Explore` sub-agent). The shape mirrors AgentCredentials but the
+ * caller does not attach the token to the client — sub-agent
+ * credentials are recorded for the audit trail; they aren't injected
+ * into the harness's child process.
+ */
+export interface SubAgentIdentity {
+    /** "dynamic" once registered/loaded, "none" on any failure. */
+    kind: "dynamic" | "none";
+    /** Sub-agent type as reported by the harness (e.g. "Explore"). */
+    subAgentType: string;
+    /** Issued client_id — also used as the audit subject for this sub-agent. */
+    subject?: string;
+    /** Persisted credentials returned by registration (or reloaded). */
+    credentials?: OryAgentDynamicCredentials;
+    /** One-line reason suitable for telemetry. */
+    reason: string;
+    /** Diagnostic warnings raised during resolution. */
+    warnings: string[];
+}
+export interface EnsureSubAgentIdentityOptions {
+    /** Sub-agent type identifier (e.g. "Explore", "general-purpose"). */
+    subAgentType: string;
+    /** Project URL for DCR. Defaults to resolveConfig(). */
+    projectUrl?: string;
+    /** Harness identifier baked into a fresh DCR client_name. */
+    harness?: string;
+    /**
+     * Bearer used as the IAT for the registration call. Defaults to the
+     * parent agent's token (when populated) so the audit trail shows the
+     * agent registering its sub-agent. Falls back to the user's token,
+     * then `ORY_AGENT_REGISTRATION_TOKEN`.
+     */
+    iat?: string;
+    /** Env override (defaults to process.env). */
+    env?: NodeJS.ProcessEnv;
+    /** Inject the DCR registration call for tests. */
+    registerAgentClientFn?: typeof registerAgentClient;
+    /** Inject persistence for tests. */
+    loadFn?: typeof loadSubAgentDynamicCredentials;
+    saveFn?: typeof saveSubAgentDynamicCredentials;
+}
+/**
+ * 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.
+ */
+export declare function ensureSubAgentIdentity(client: OryAgentClient, options: EnsureSubAgentIdentityOptions): Promise<SubAgentIdentity>;
+export {};