melchizedek-agents 1.0.2 → 1.1.0

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

@@ -0,0 +1,233 @@
+/**
+ * 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.
+ */
+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.
+ */
+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 {};

package/dist/lib/tools/oauthTools.js

@@ -0,0 +1,421 @@
+/**
+ * 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.
+ */
+import { blockedHostReason, checkHost } from '../net/addressGuard.js';
+import { PROVIDER_NAME, ToolCredentialError } from './auth.js';
+import { readCredentialEnv } from './credentialEnv.js';
+import { oauthHostProblem, oauthHosts } from './oauthHosts.js';
+/** An agent's declared OAuth grants, OpenAPI entries first, then its MCP server. */
+export function agentOAuthGrants(agent, prefix = '') {
+    const name = `${prefix}${agent.name ?? ''}`;
+    const out = [];
+    for (const entry of agent.openapi ?? []) {
+        if (entry?.auth?.oauth2)
+            out.push({ agent: name, tools: `openapi ${entry.spec ?? ''}`, oauth2: entry.auth.oauth2 });
+    }
+    if (agent.mcp_auth?.oauth2)
+        out.push({ agent: name, tools: `mcp ${agent.mcp_server_url ?? ''}`, oauth2: agent.mcp_auth.oauth2 });
+    return out;
+}
+/** The environment variables a grant reads, by role. */
+export function oauthEnvNames(oauth2) {
+    return [oauth2.client_id_env, oauth2.client_secret_env].filter((e) => typeof e === 'string' && e !== '');
+}
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+/** Why a token may not be sent to `raw`, or null: https, or http to a loopback host. */
+export function tokenTransportProblem(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return `'${raw.slice(0, 200)}' is not a URL`;
+    }
+    if (url.username || url.password)
+        return `${url.hostname} must not carry credentials in its URL`;
+    if (url.protocol === 'https:')
+        return null;
+    if (url.protocol === 'http:' && LOOPBACK.has(url.hostname))
+        return null;
+    return `an OAuth token is sent only over https (http only to a loopback host), not to ${url.protocol}//${url.hostname}`;
+}
+// ── The operator's host allowlist (ADR 0114) ─────────────────────────────────
+/**
+ * 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 function oauthGrantHostProblems(oauth2, servers, allowlist) {
+    const list = allowlist === undefined ? oauthHosts() ?? null : allowlist;
+    const urls = servers.map((s) => ['server', s]);
+    urls.push(['token_url', oauth2.token_url]);
+    if (oauth2.authorization_url)
+        urls.push(['authorization_url', oauth2.authorization_url]);
+    const out = new Set();
+    for (const [role, url] of urls) {
+        const problem = oauthHostProblem(oauth2, url, role, list);
+        if (problem)
+            out.add(problem);
+    }
+    return [...out];
+}
+/**
+ * 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 function oauthCallProblem(oauth2, destination) {
+    const transport = tokenTransportProblem(destination);
+    if (transport)
+        return transport;
+    try {
+        return oauthHostProblem(oauth2, destination, 'server', oauthHosts() ?? null);
+    }
+    catch {
+        return 'the OAuth host allowlist is malformed';
+    }
+}
+const MAX_TOKEN_RESPONSE_BYTES = 64 * 1024;
+/** A token response, read whole up to a bound, as a JSON object; undefined otherwise. */
+async function readTokenJson(res) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        return undefined;
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > MAX_TOKEN_RESPONSE_BYTES) {
+            await reader.cancel().catch(() => { });
+            return undefined;
+        }
+        chunks.push(value);
+    }
+    try {
+        const parsed = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Why the server may not call this token endpoint, or null (the full guard, with DNS). */
+async function tokenEndpointProblem(raw, allowPrivate) {
+    const transport = tokenTransportProblem(raw);
+    if (transport)
+        return transport;
+    if (allowPrivate)
+        return null;
+    const reason = await checkHost(new URL(raw).hostname);
+    return reason ? `refusing token endpoint ${new URL(raw).hostname}: ${reason}` : null;
+}
+/**
+ * One token-endpoint request (RFC 6749 4.4, 6): the endpoint checked by the
+ * guard first, no redirect followed, a time limit, a bounded response. Any
+ * failure is ToolCredentialError('grant_failed'), never the provider's text,
+ * which may echo what it refused.
+ */
+async function tokenRequest(tokenUrl, body, provider, options) {
+    if (await tokenEndpointProblem(tokenUrl, options.allowPrivate))
+        throw new ToolCredentialError('grant_failed', provider);
+    let json;
+    try {
+        const res = await options.doFetch(tokenUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body,
+            // A redirect would carry the client secret (or the refresh token) to wherever it points.
+            redirect: 'error',
+            signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(options.timeoutMs)]) : AbortSignal.timeout(options.timeoutMs),
+        });
+        json = await readTokenJson(res);
+        if (!res.ok)
+            json = undefined;
+    }
+    catch {
+        json = undefined;
+    }
+    const accessToken = json?.access_token;
+    const tokenType = json?.token_type;
+    if (typeof accessToken !== 'string' || !accessToken)
+        throw new ToolCredentialError('grant_failed', provider);
+    if (tokenType !== undefined && (typeof tokenType !== 'string' || tokenType.toLowerCase() !== 'bearer'))
+        throw new ToolCredentialError('grant_failed', provider);
+    const refreshToken = typeof json?.refresh_token === 'string' && json.refresh_token ? json.refresh_token : undefined;
+    const expiresIn = typeof json?.expires_in === 'number' ? json.expires_in : typeof json?.expires_in === 'string' ? Number(json.expires_in) : undefined;
+    const scopes = typeof json?.scope === 'string' ? json.scope.split(' ').filter((x) => x !== '') : undefined;
+    return {
+        accessToken,
+        ...(refreshToken ? { refreshToken } : {}),
+        ...(expiresIn !== undefined && Number.isFinite(expiresIn) && expiresIn > 0 ? { expiresAt: new Date(options.now() + expiresIn * 1000) } : {}),
+        ...(scopes ? { scopes } : {}),
+    };
+}
+/**
+ * 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 function clientCredentialsGrant(options) {
+    const now = options.now ?? Date.now;
+    const skew = options.refreshSkewMs ?? 60_000;
+    const doFetch = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    let held;
+    let pending;
+    const request = async (signal) => {
+        const body = new URLSearchParams({ grant_type: 'client_credentials', client_id: options.clientId, client_secret: options.clientSecret });
+        if (options.scopes?.length)
+            body.set('scope', options.scopes.join(' '));
+        const issued = await tokenRequest(options.tokenUrl, body, options.provider, { allowPrivate: options.allowPrivate === true, doFetch, timeoutMs, now, ...(signal ? { signal } : {}) });
+        held = { accessToken: issued.accessToken, ...(issued.expiresAt ? { expiresAt: issued.expiresAt.getTime() } : {}) };
+        return issued.accessToken;
+    };
+    return {
+        async token(signal) {
+            if (held && (held.expiresAt === undefined || held.expiresAt - skew > now()))
+                return held.accessToken;
+            if (!pending)
+                pending = request(signal).finally(() => (pending = undefined));
+            return pending;
+        },
+    };
+}
+/**
+ * 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 function oauthTokenSource(oauth2, where, server, options = {}) {
+    const servers = typeof server === 'string' ? [server] : [...server];
+    for (const s of servers) {
+        const problem = tokenTransportProblem(s);
+        if (problem)
+            throw new Error(`${where}: ${problem}`);
+    }
+    if (!PROVIDER_NAME.test(oauth2.provider))
+        throw new Error(`${where}: provider must match ${PROVIDER_NAME}`);
+    const hostProblems = oauthGrantHostProblems(oauth2, servers);
+    if (hostProblems.length)
+        throw new Error(`${where}: ${hostProblems.join('; ')}`);
+    const provider = oauth2.provider;
+    /** The call-time check (ADR 0114): before any token is read or fetched. */
+    const refuse = (destination) => {
+        if (oauthCallProblem(oauth2, destination))
+            throw new ToolCredentialError('host_refused', provider);
+    };
+    if (oauth2.grant === 'authorization_code') {
+        return async (ctx, destination) => {
+            refuse(destination);
+            if (!ctx?.accessToken)
+                throw new ToolCredentialError('unavailable', provider);
+            return ctx.accessToken(provider);
+        };
+    }
+    const env = options.env ?? process.env;
+    if (!oauth2.client_secret_env)
+        throw new Error(`${where}: a client_credentials grant needs client_secret_env`);
+    const transport = tokenTransportProblem(oauth2.token_url);
+    if (transport)
+        throw new Error(`${where}: token_url: ${transport}`);
+    if (options.allowPrivate !== true) {
+        const blocked = blockedHostReason(new URL(oauth2.token_url).hostname);
+        if (blocked)
+            throw new Error(`${where}: refusing token endpoint ${new URL(oauth2.token_url).hostname}: ${blocked}`);
+    }
+    const grant = clientCredentialsGrant({
+        provider,
+        tokenUrl: oauth2.token_url,
+        clientId: oauth2.client_id ?? readCredentialEnv(oauth2.client_id_env ?? '', where, env),
+        clientSecret: readCredentialEnv(oauth2.client_secret_env, where, env),
+        ...(oauth2.scopes?.length ? { scopes: [...oauth2.scopes] } : {}),
+        ...(options.allowPrivate ? { allowPrivate: true } : {}),
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+    return async (ctx, destination) => {
+        refuse(destination);
+        // The client secret goes to the token endpoint: held to the same rule.
+        refuse(oauth2.token_url);
+        return grant.token(ctx?.signal);
+    };
+}
+/**
+ * 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 function oauthClientsFor(configs, options = {}) {
+    const env = options.env ?? process.env;
+    const allowlist = options.allowlist === undefined ? oauthHosts(env) ?? null : options.allowlist;
+    const clients = {};
+    const signature = new Map();
+    for (const use of syndicateOAuthGrants(configs, options.load)) {
+        const o = use.oauth2;
+        if (o.grant !== 'authorization_code')
+            continue;
+        const where = `${use.agent} · ${use.tools} · oauth2`;
+        if (!o.authorization_url)
+            throw new Error(`${where}: an authorization_code grant needs authorization_url`);
+        // The consent step sends the client secret, the code and later the refresh token to these endpoints (ADR 0114).
+        const hostProblems = oauthGrantHostProblems(o, [], allowlist);
+        if (hostProblems.length)
+            throw new Error(`${where}: ${hostProblems.join('; ')}`);
+        const sig = JSON.stringify([o.authorization_url, o.token_url, o.client_id ?? null, o.client_id_env ?? null, o.client_secret_env ?? null, [...(o.scopes ?? [])].sort(), o.authorization_params ?? {}]);
+        const before = signature.get(o.provider);
+        if (before !== undefined) {
+            if (before !== sig)
+                throw new Error(`${where}: provider "${o.provider}" is declared twice with different endpoints, client or scopes`);
+            continue;
+        }
+        signature.set(o.provider, sig);
+        clients[o.provider] = {
+            authorizationUrl: o.authorization_url,
+            tokenUrl: o.token_url,
+            clientId: o.client_id ?? readCredentialEnv(o.client_id_env ?? '', where, env),
+            ...(o.client_secret_env ? { clientSecret: readCredentialEnv(o.client_secret_env, where, env) } : {}),
+            scopes: [...(o.scopes ?? [])],
+            ...(o.authorization_params ? { authorizationParams: { ...o.authorization_params } } : {}),
+        };
+    }
+    return clients;
+}
+/**
+ * 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 function syndicateOAuthGrants(configs, load) {
+    const out = [];
+    const seen = new Set();
+    const visit = (config, prefix) => {
+        const agents = [config.orchestrator, ...(config.subagents ?? [])].filter((a) => !!a);
+        for (const agent of agents) {
+            if (agent.yaml_reference) {
+                if (!load || seen.has(agent.yaml_reference))
+                    continue;
+                seen.add(agent.yaml_reference);
+                visit(load(agent.yaml_reference), `${prefix}${agent.name ?? agent.yaml_reference} › `);
+                continue;
+            }
+            out.push(...agentOAuthGrants(agent, prefix));
+        }
+    };
+    for (const config of configs)
+        visit(config, '');
+    return out;
+}
+/**
+ * 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 function syndicateOAuthHostProblems(configs, options = {}) {
+    const allowlist = options.allowlist === undefined ? oauthHosts() ?? null : options.allowlist;
+    const out = [];
+    for (const use of syndicateOAuthGrants(configs, options.load)) {
+        const servers = use.tools.startsWith('mcp ') && use.tools.length > 4 ? [use.tools.slice(4)] : [];
+        for (const problem of oauthGrantHostProblems(use.oauth2, servers, allowlist))
+            out.push(`${use.agent} · ${use.tools} · oauth2: ${problem}`);
+    }
+    return out;
+}
+/**
+ * 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 function oauthRefreshProviders(clients, options = {}) {
+    const providers = {};
+    for (const [name, client] of Object.entries(clients)) {
+        providers[name] = {
+            refresh: async (refreshToken, context) => {
+                // A refresh token goes only to a token endpoint the allowlist binds to its provider (ADR 0114).
+                if (oauthCallProblem({ provider: name, grant: 'authorization_code' }, client.tokenUrl))
+                    throw new ToolCredentialError('host_refused', name);
+                const body = new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken, client_id: client.clientId });
+                if (client.clientSecret)
+                    body.set('client_secret', client.clientSecret);
+                return tokenRequest(client.tokenUrl, body, name, {
+                    allowPrivate: options.allowPrivate === true,
+                    doFetch: options.fetch ?? fetch,
+                    timeoutMs: options.timeoutMs ?? 10_000,
+                    now: options.now ?? Date.now,
+                    ...(context.signal ? { signal: context.signal } : {}),
+                });
+            },
+        };
+    }
+    return providers;
+}

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

@@ -1,4 +1,6 @@
 import type { Tool } from './tool.ts';
+import type { OAuth2AuthConfig } from './oauthTools.ts';
+export { credentialEnvProblem } from './credentialEnv.ts';
 export { namesTool, toSnake } from './openapi/parse.ts';
 export interface OpenApiAuthConfig {
     /** Environment variable holding a bearer token (`Authorization: Bearer …`). */
@@ -9,6 +11,8 @@ export interface OpenApiAuthConfig {
         in: 'header' | 'query';
         name: string;
     };
+    /** An OAuth access token per call: the run's user's (authorization_code) or the server's (client_credentials). ADR 0112. */
+    oauth2?: OAuth2AuthConfig;
 }
 /** One entry of an agent's `openapi:` list. */
 export interface OpenApiConfig {
@@ -29,12 +33,6 @@ export declare const MAX_RESULT_CHARS = 20000;
  * operationId (lib/compile.ts). Its value is the operationId.
  */
 export declare const OPENAPI_TOOL: unique symbol;
-/**
- * Why an `auth` may not read this variable, or null. With
- * OPENAPI_CREDENTIAL_ENVS set, only the names it lists are allowed; without
- * it, anything but the framework's own variables is.
- */
-export declare function credentialEnvProblem(name: string, env?: NodeJS.ProcessEnv): string | null;
 /**
  * Cut an API result to MAX_RESULT_CHARS, saying so. Kept for consumers of
  * this module; the tools cut with capResult (lib/tools/tool.ts).