melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/tools/oauthTools.d.ts

@@ -0,0 +1,242 @@
+/**
+ * lib/tools/oauthTools.ts — `auth: { oauth2 }` from a syndicate YAML: an
+ * OpenAPI entry or an MCP server whose calls carry an OAuth access token
+ * (WS6-3c, ADR 0112).
+ *
+ * WHY this file exists:
+ *   The credential store (ADR 0072) holds each user's tokens and the consent
+ *   step (ADR 0085) puts them there, but nothing said which tools send which
+ *   provider's token. The YAML says it, next to the tool it protects:
+ *
+ *     openapi:
+ *       - spec: specs/tracker.yaml
+ *         auth:
+ *           oauth2:
+ *             provider: tracker
+ *             grant: authorization_code
+ *             authorization_url: https://tracker.example.com/oauth/authorize
+ *             token_url: https://tracker.example.com/oauth/token
+ *             client_id_env: TRACKER_CLIENT_ID
+ *             client_secret_env: TRACKER_CLIENT_SECRET
+ *             scopes: [issues:read]
+ *
+ *   and `mcp_auth: { oauth2: { ... } }` beside an agent's `mcp_server_url`.
+ *
+ * THE TWO GRANTS:
+ *   - authorization_code: the token is the run's own user's, read through
+ *     `ctx.accessToken(provider)` at each call. A user who has not granted it
+ *     is asked (the consent pause, when the run has a consent step whose
+ *     clients include the provider: `oauthClientsFor` builds them from the
+ *     same YAML, and `oauthRefreshProviders` the store's refresh hooks).
+ *     The tool never chooses whose token.
+ *   - client_credentials: the server's own token for the provider, from its
+ *     token endpoint with the client id and secret, held in this process's
+ *     memory until shortly before it expires, never in the credential store
+ *     (no user owns it).
+ *
+ * SECRETS: the YAML names environment variables, never values; the variable
+ *   names pass credentialEnvProblem (lib/tools/credentialEnv.ts), so a YAML
+ *   cannot send a framework secret to a token endpoint. No token, client
+ *   secret or provider error text reaches a result, an error, a log line or
+ *   a span: a failure is reported by kind (ToolCredentialError).
+ *
+ * WHERE A TOKEN MAY GO: a token is sent only over https, or http to a
+ *   loopback host (local development), to the server the YAML names, and
+ *   only to a host the operator's allowlist binds to the provider
+ *   (lib/tools/oauthHosts.ts, ADR 0114): with none configured, an
+ *   authorization_code grant is refused. The allowlist is checked when a
+ *   served syndicate loads (`syndicateOAuthHostProblems`), when the tools
+ *   compile (the server, the token endpoint and the authorization
+ *   endpoint), and again before each call sends a token
+ *   (`oauthCallProblem`). The client-credentials token endpoint passes the
+ *   same SSRF guard as the server it serves (ALLOW_PRIVATE_OPENAPI or
+ *   ALLOW_PRIVATE_MCP), and no redirect from it is followed.
+ *
+ * WHERE A CLIENT SECRET MAY GO: to the token endpoint, and, when the
+ *   operator configures a credential host allowlist
+ *   (lib/tools/credentialHosts.ts, ADR 0122), only to a host it binds the
+ *   `client_secret_env` variable to: checked at compile, when the consent
+ *   clients are built, and before each client-credentials token request,
+ *   code exchange (lib/tools/oauthConsent.ts) and refresh.
+ */
+import type { OAuthProvider } from './auth.ts';
+import type { OAuthHostAllowlist } from './oauthHosts.ts';
+import type { OAuthClientConfig } from './oauthConsent.ts';
+import type { ToolContext } from './tool.ts';
+/** The `oauth2` block of an `auth` (OpenAPI) or an `mcp_auth` (MCP). */
+export interface OAuth2AuthConfig {
+    /** The credential store's name for the provider (lowercase). */
+    provider: string;
+    grant: 'authorization_code' | 'client_credentials';
+    /** The provider's authorization endpoint (authorization_code only). */
+    authorization_url?: string;
+    /** The provider's token endpoint. */
+    token_url: string;
+    /** The client id, written out (it is not a secret) … */
+    client_id?: string;
+    /** … or the environment variable holding it. */
+    client_id_env?: string;
+    /** The environment variable holding the client secret. Required for client_credentials. */
+    client_secret_env?: string;
+    scopes?: string[];
+    /** Extra authorization parameters (authorization_code only), e.g. `access_type: offline`. */
+    authorization_params?: Record<string, string>;
+}
+/** An agent's `mcp_auth:` beside its `mcp_server_url`. */
+export interface McpAuthConfig {
+    oauth2: OAuth2AuthConfig;
+}
+/** Where a declared grant sits: for the doctor, and for the error messages. */
+export interface OAuthGrantUse {
+    /** The agent that holds the tools. */
+    agent: string;
+    /** `openapi <spec>` or `mcp <url>`. */
+    tools: string;
+    oauth2: OAuth2AuthConfig;
+}
+/** An agent's declared OAuth grants, OpenAPI entries first, then its MCP server. */
+export declare function agentOAuthGrants(agent: {
+    name?: string;
+    openapi?: Array<{
+        spec?: string;
+        auth?: {
+            oauth2?: OAuth2AuthConfig;
+        };
+    }>;
+    mcp_server_url?: string;
+    mcp_auth?: {
+        oauth2?: OAuth2AuthConfig;
+    };
+}, prefix?: string): OAuthGrantUse[];
+/** The environment variables a grant reads, by role. */
+export declare function oauthEnvNames(oauth2: OAuth2AuthConfig): string[];
+/** Why a token may not be sent to `raw`, or null: https, or http to a loopback host. */
+export declare function tokenTransportProblem(raw: string): string | null;
+/**
+ * Why this grant may not be declared for these servers, one line per
+ * refusal: each server the tools call, the token endpoint and the
+ * authorization endpoint must be hosts the operator's allowlist binds to the
+ * provider (lib/tools/oauthHosts.ts). With no allowlist, an
+ * authorization_code grant is refused and a client_credentials one allowed.
+ * `allowlist` defaults to the one in force; `null` means none is configured.
+ */
+export declare function oauthGrantHostProblems(oauth2: OAuth2AuthConfig, servers: readonly string[], allowlist?: OAuthHostAllowlist | null): string[];
+/**
+ * Why a call may not send this grant's token (or secret) to `destination`
+ * now, or null: the transport rule and the allowlist in force, checked again
+ * at each call. The compile checked the same; this holds if a request is
+ * aimed elsewhere, or the allowlist changed. A malformed allowlist refuses.
+ */
+export declare function oauthCallProblem(oauth2: Pick<OAuth2AuthConfig, 'provider' | 'grant'>, destination: string): string | null;
+export interface ClientCredentialsOptions {
+    provider: string;
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scopes?: string[];
+    /** Private and loopback token endpoints are allowed (ALLOW_PRIVATE_OPENAPI / ALLOW_PRIVATE_MCP). */
+    allowPrivate?: boolean;
+    /** A token this close to its expiry is fetched again. Default 60 s. */
+    refreshSkewMs?: number;
+    /** The token request's time limit, ms. Default 10 s. */
+    timeoutMs?: number;
+    /** For tests. */
+    fetch?: typeof fetch;
+    now?: () => number;
+}
+/**
+ * The server's own token for a provider (RFC 6749 4.4), fetched when first
+ * needed and again shortly before it expires, one request at a time. A
+ * failure throws ToolCredentialError('grant_failed'), never the provider's
+ * text, which may echo what it refused.
+ */
+export declare function clientCredentialsGrant(options: ClientCredentialsOptions): {
+    token(signal?: AbortSignal): Promise<string>;
+};
+/**
+ * What a tool calls for the token of one call, naming where that call goes.
+ * Throws ToolCredentialError, whose message names no value: `host_refused`
+ * when the destination is not one of the provider's hosts (`allowlist`
+ * `'oauth'`), or when a client secret's token endpoint is not bound to its
+ * variable (`allowlist` `'credential'`).
+ */
+export type OAuthTokenSource = (ctx: ToolContext | undefined, destination: string) => Promise<string>;
+/**
+ * The token source a declared `oauth2` block gives its tools. Reads the
+ * client-credentials variables now, so a variable that is not set (or that
+ * the allowlist refuses) fails the compile, naming the variable only, and
+ * so does a host the operator's OAuth host allowlist does not bind to the
+ * provider (ADR 0114). `where` prefixes those messages; `server` is the URL
+ * (or URLs) the token is sent to.
+ */
+export declare function oauthTokenSource(oauth2: OAuth2AuthConfig, where: string, server: string | readonly string[], options?: {
+    allowPrivate?: boolean;
+    env?: NodeJS.ProcessEnv;
+    fetch?: typeof fetch;
+}): OAuthTokenSource;
+/** The parts of a syndicate config `oauthClientsFor` reads. */
+interface AgentLike {
+    name?: string;
+    openapi?: Array<{
+        spec?: string;
+        auth?: {
+            oauth2?: OAuth2AuthConfig;
+        };
+    }>;
+    mcp_server_url?: string;
+    mcp_auth?: {
+        oauth2?: OAuth2AuthConfig;
+    };
+    yaml_reference?: string;
+}
+interface SyndicateLike {
+    orchestrator?: AgentLike;
+    subagents?: AgentLike[];
+}
+/**
+ * The OAuth clients the consent step needs for these syndicates' declared
+ * authorization-code grants, by provider: pass them as
+ * `oauthConsent({ providers })` (lib/tools/oauthConsent.ts). Client ids and
+ * secrets are read from the variables the YAML names. Two declarations of
+ * one provider must agree on its endpoints, client and scopes, or this
+ * throws: a provider's grant is one grant, whichever tool asks for it.
+ * `load` reads a nested `yaml_reference:` file, when given.
+ */
+export declare function oauthClientsFor(configs: readonly SyndicateLike[], options?: {
+    env?: NodeJS.ProcessEnv;
+    load?: (ref: string) => SyndicateLike;
+    allowlist?: OAuthHostAllowlist | null;
+}): Record<string, OAuthClientConfig>;
+/**
+ * Every OAuth grant these syndicates declare, orchestrators and subagents,
+ * following a nested `yaml_reference:` through `load` when given (once per
+ * file; agent names then read "Parent › Child").
+ */
+export declare function syndicateOAuthGrants(configs: readonly SyndicateLike[], load?: (ref: string) => SyndicateLike): OAuthGrantUse[];
+/**
+ * Why these syndicates may not be served here, one line per refusal
+ * (ADR 0114): each declared grant's MCP server, token endpoint and
+ * authorization endpoint against the operator's OAuth host allowlist (an
+ * OpenAPI entry's servers are in its spec, so its compile checks those).
+ * The A2A server checks every syndicate it loads to serve; the compile
+ * checks again, and each call once more.
+ */
+export declare function syndicateOAuthHostProblems(configs: readonly SyndicateLike[], options?: {
+    load?: (ref: string) => SyndicateLike;
+    allowlist?: OAuthHostAllowlist | null;
+}): string[];
+/**
+ * The credential store's refresh hooks for the same providers
+ * (`credentialStore({ providers })`, lib/tools/credentialStore.ts): an
+ * expired user token is renewed at the provider's token endpoint with its
+ * refresh token (RFC 6749 6) instead of asking the person again. Built from
+ * `oauthClientsFor`'s clients; `allowPrivate` lets a private or loopback
+ * token endpoint through the guard (development).
+ */
+export declare function oauthRefreshProviders(clients: Record<string, OAuthClientConfig>, options?: {
+    allowPrivate?: boolean;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    now?: () => number;
+}): Record<string, OAuthProvider>;
+export {};