melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/tools/oauthTools.js

@@ -0,0 +1,447 @@
+/**
+ * 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 { blockedHostReason, checkHost } from '../net/addressGuard.js';
+import { PROVIDER_NAME, ToolCredentialError } from './auth.js';
+import { readCredentialEnv } from './credentialEnv.js';
+import { CLIENT_SECRET_ENV, clientSecretEnvOf, credentialCallProblem, credentialHostProblem } from './credentialHosts.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, 'oauth');
+    };
+    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}`);
+    }
+    // The client secret goes only to a host the operator binds its variable to (ADR 0122).
+    const secretEnv = oauth2.client_secret_env;
+    const unbound = credentialHostProblem(secretEnv, oauth2.token_url, 'token_url');
+    if (unbound)
+        throw new Error(`${where}: ${unbound}`);
+    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,
+        // and to the credential host allowlist (ADR 0122).
+        refuse(oauth2.token_url);
+        if (credentialCallProblem(secretEnv, oauth2.token_url))
+            throw new ToolCredentialError('host_refused', provider, 'credential');
+        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('; ')}`);
+        // The client secret goes to the token endpoint: a host the operator binds its variable to (ADR 0122).
+        const secretProblem = o.client_secret_env ? credentialHostProblem(o.client_secret_env, o.token_url, 'token_url') : null;
+        if (secretProblem)
+            throw new Error(`${where}: ${secretProblem}`);
+        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 } } : {}),
+            // The variable the secret came from, so the exchange and the refresh check its host at call time.
+            ...(o.client_secret_env ? { [CLIENT_SECRET_ENV]: o.client_secret_env } : {}),
+        };
+    }
+    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, 'oauth');
+                // The client secret too: only to a host the operator binds its variable to (ADR 0122).
+                const secretEnv = clientSecretEnvOf(client);
+                if (client.clientSecret && secretEnv && credentialCallProblem(secretEnv, client.tokenUrl))
+                    throw new ToolCredentialError('host_refused', name, 'credential');
+                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).
@@ -47,6 +45,13 @@ export declare function boundResult(result: unknown): unknown;
  * an operation the spec does not have, or a server the guard refuses.
  */
 export declare function buildOpenApiOwnTools(entry: OpenApiConfig, baseDir?: string): Promise<Tool[]>;
+/**
+ * The server URLs one `openapi:` entry calls: its `base_url`, else its
+ * spec's server. Reads and parses the spec (bounded); throws as the compile
+ * would on a spec that cannot be read. For the load-time credential host
+ * check (lib/tools/credentialUses.ts, ADR 0122).
+ */
+export declare function openApiServers(entry: OpenApiConfig, baseDir?: string): string[];
 /**
  * The tools one `openapi:` entry gives an agent: buildOpenApiOwnTools' own
  * Tools, each marked so require_approval can name it by its operationId.

package/dist/lib/tools/openapiTools.js

@@ -32,7 +32,16 @@
  *     OPENAPI_CREDENTIAL_ENVS, when the operator sets it, is the exact list
  *     of variables an `auth` may name. A credential is held by the tool,
  *     never written to session state, and its value never appears in an
- *     error the model reads.
+ *     error the model reads. An `auth: { oauth2 }` sends an OAuth token
+ *     instead, fetched per call: the run's user's own (authorization_code,
+ *     through `ctx.accessToken` and the consent pause) or the server's own
+ *     (client_credentials), lib/tools/oauthTools.ts, ADR 0112.
+ *   - STATIC CREDENTIALS ONLY TO THEIR HOSTS. When the operator configures a
+ *     credential host allowlist (MELCHIZEDEK_CREDENTIAL_HOSTS, or
+ *     createA2AApp's credentialHosts; lib/tools/credentialHosts.ts,
+ *     ADR 0122), a `bearer_env` or `api_key` variable is sent only to a host
+ *     it binds that variable to: checked at compile (every server), and
+ *     again before each call, which is refused with nothing sent.
  *   - THE SSRF GUARD. Every server URL the tools will call must be http(s)
  *     and pass lib/net/addressGuard.ts: its literal rules at compile time
  *     (offline), and the full check with DNS before each call (a name can
@@ -62,6 +71,11 @@ import { extname, resolve } from 'node:path';
 import { MAX_RESULT_CHARS as TOOL_RESULT_CHARS, capResult } from './tool.js';
 import { callOperation, hostProblem } from './openapi/call.js';
 import { MAX_SPEC_BYTES, operationNamed, parseOpenApiSpec } from './openapi/parse.js';
+import { ToolCredentialError } from './auth.js';
+import { readCredentialEnv } from './credentialEnv.js';
+import { credentialCallProblem, credentialHostProblem } from './credentialHosts.js';
+import { oauthTokenSource, tokenTransportProblem } from './oauthTools.js';
+export { credentialEnvProblem } from './credentialEnv.js';
 export { namesTool, toSnake } from './openapi/parse.js';
 /** Characters a single API result may carry into the conversation: every tool's shared limit (lib/tools/tool.ts). */
 export const MAX_RESULT_CHARS = TOOL_RESULT_CHARS;
@@ -70,51 +84,27 @@ export const MAX_RESULT_CHARS = TOOL_RESULT_CHARS;
  * operationId (lib/compile.ts). Its value is the operationId.
  */
 export const OPENAPI_TOOL = Symbol.for('melchizedek.openapiTool');
-/** Prefixes and names of variables the framework itself reads: never an API credential. */
-const FRAMEWORK_ENV_PREFIXES = [
-    'A2A_', 'SUPABASE_', 'DATABASE_', 'MCP_', 'MODEL_', 'MEMORY_', 'OTEL_', 'TELEMETRY_', 'MELCHIZEDEK_',
-    'GOOGLE_', 'GEMINI_', 'ANTHROPIC_', 'OPENAI_', 'AZURE_', 'AWS_', 'XAI_', 'MOONSHOT_', 'OLLAMA_', 'WIKI_',
-    'ALLOW_', 'OPENAPI_',
-];
-const FRAMEWORK_ENV_NAMES = new Set(['PUBLIC_URL', 'HOST', 'PORT', 'PATH', 'HOME', 'NODE_OPTIONS', 'WEB_EXTRACT_CHAR_LIMIT']);
-/**
- * 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 function credentialEnvProblem(name, env = process.env) {
-    const allow = env.OPENAPI_CREDENTIAL_ENVS?.split(',').map((s) => s.trim()).filter(Boolean);
-    if (allow?.length) {
-        return allow.includes(name) ? null : `${name} is not in OPENAPI_CREDENTIAL_ENVS (${allow.join(', ')})`;
-    }
-    if (FRAMEWORK_ENV_NAMES.has(name) || FRAMEWORK_ENV_PREFIXES.some((p) => name.startsWith(p))) {
-        return `${name} is one of the framework's own settings and may not be sent to an API; give the API its own variable (or list it in OPENAPI_CREDENTIAL_ENVS)`;
-    }
-    return null;
-}
 /**
  * The credential an `auth` names, read from the environment once, at
  * compile. Throws (failing the compile) on a variable the allowlist refuses
  * or one that is not set; the message names the variable, never its value.
+ * An `oauth2` block is not read here: its token is fetched per call
+ * (oauthTokenSource, lib/tools/oauthTools.ts).
  */
 function credentialFor(auth, spec) {
     if (!auth)
         return undefined;
-    const read = (env) => {
-        const refused = credentialEnvProblem(env);
-        if (refused)
-            throw new Error(`openapi ${spec}: ${refused}`);
-        const value = process.env[env]?.trim();
-        if (!value)
-            throw new Error(`openapi ${spec}: ${env} is not set (auth reads it from the environment)`);
-        return value;
-    };
+    const read = (env) => readCredentialEnv(env, `openapi ${spec}`);
     if (auth.bearer_env)
-        return { kind: 'bearer', token: read(auth.bearer_env) };
+        return { credential: { kind: 'bearer', token: read(auth.bearer_env) }, env: auth.bearer_env };
     if (auth.api_key)
-        return { kind: 'api_key', in: auth.api_key.in, name: auth.api_key.name, value: read(auth.api_key.env) };
+        return { credential: { kind: 'api_key', in: auth.api_key.in, name: auth.api_key.name, value: read(auth.api_key.env) }, env: auth.api_key.env };
     return undefined;
 }
+/** The variable a static `auth` sends (bearer_env or api_key.env), or undefined. */
+function staticCredentialEnv(auth) {
+    return auth?.bearer_env ?? auth?.api_key?.env;
+}
 /**
  * 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).
@@ -152,13 +142,42 @@ function readSpec(specPath, source) {
         closeSync(fd);
     }
 }
-/** An own Tool that calls one operation (lib/tools/openapi/call.ts), its result cut to MAX_RESULT_CHARS. */
-function operationTool(op, credential) {
+/**
+ * An own Tool that calls one operation (lib/tools/openapi/call.ts), its
+ * result cut to MAX_RESULT_CHARS. With `oauth`, each call fetches its token
+ * first; a token that cannot be had is answered as `{ error }` naming the
+ * provider and what to do, never a value (and, for a user who has not
+ * granted it, the run's consent step has already asked).
+ */
+function operationTool(op, held, oauth) {
+    const credential = held?.credential;
     const tool = {
         name: op.name,
         declaration: () => op.declaration,
         async execute(args, ctx) {
-            return capResult(await callOperation(op, args ?? {}, { credential, signal: ctx?.signal }));
+            // The operator's credential host allowlist, again at each call (ADR 0122): the
+            // compile checked it, and it can change. Refused, nothing is sent; the
+            // message names the host, never the value.
+            if (held && credentialCallProblem(held.env, op.baseUrl)) {
+                let host = op.baseUrl;
+                try {
+                    host = new URL(op.baseUrl).hostname;
+                }
+                catch {
+                    // A server that is not a URL is named as written.
+                }
+                return { error: `${op.name} was not called: the operator's credential host allowlist does not let this API's credential be sent to ${host}` };
+            }
+            let sent = credential;
+            if (oauth) {
+                try {
+                    sent = { kind: 'bearer', token: await oauth(ctx, op.baseUrl) };
+                }
+                catch (error) {
+                    return { error: error instanceof ToolCredentialError ? error.message : 'The authorization for this API could not be obtained.' };
+                }
+            }
+            return capResult(await callOperation(op, args ?? {}, { credential: sent, signal: ctx?.signal }));
         },
     };
     Object.defineProperty(tool, OPENAPI_TOOL, { value: op.operationId });
@@ -192,14 +211,45 @@ export async function buildOpenApiOwnTools(entry, baseDir = process.cwd()) {
         picked = all.filter((o) => o.method === 'get');
     }
     const chosen = entry.base_url ? picked.map((o) => ({ ...o, baseUrl: entry.base_url })) : picked;
+    const credentialEnv = staticCredentialEnv(entry.auth);
     for (const baseUrl of new Set(chosen.map((o) => o.baseUrl))) {
         if (!baseUrl)
             throw new Error(`openapi ${entry.spec}: the spec names no server; set base_url`);
         const problem = await hostProblem(baseUrl, false);
         if (problem)
             throw new Error(`openapi ${entry.spec}: ${problem}`);
+        // A static credential goes only to a host the operator binds its variable to (ADR 0122).
+        const bound = credentialEnv ? credentialHostProblem(credentialEnv, baseUrl) : null;
+        if (bound)
+            throw new Error(`openapi ${entry.spec}: ${bound}`);
     }
-    return chosen.map((o) => operationTool(o, credential));
+    let oauth;
+    if (entry.auth?.oauth2 && chosen.length) {
+        // Every server the token goes to takes it over https (or loopback http).
+        for (const server of new Set(chosen.map((o) => o.baseUrl))) {
+            const problem = tokenTransportProblem(server);
+            if (problem)
+                throw new Error(`openapi ${entry.spec}: ${problem}`);
+        }
+        oauth = oauthTokenSource(entry.auth.oauth2, `openapi ${entry.spec}`, [...new Set(chosen.map((o) => o.baseUrl))], { allowPrivate: process.env.ALLOW_PRIVATE_OPENAPI === 'true' });
+    }
+    return chosen.map((o) => operationTool(o, credential, oauth));
+}
+/**
+ * The server URLs one `openapi:` entry calls: its `base_url`, else its
+ * spec's server. Reads and parses the spec (bounded); throws as the compile
+ * would on a spec that cannot be read. For the load-time credential host
+ * check (lib/tools/credentialUses.ts, ADR 0122).
+ */
+export function openApiServers(entry, baseDir = process.cwd()) {
+    if (entry.base_url)
+        return [entry.base_url];
+    const specPath = resolve(baseDir, entry.spec);
+    const ext = extname(specPath).toLowerCase();
+    if (!['.yaml', '.yml', '.json'].includes(ext))
+        throw new Error(`openapi ${entry.spec}: a spec is .yaml, .yml or .json`);
+    const all = parseOpenApiSpec(readSpec(specPath, entry.spec), ext === '.json' ? 'json' : 'yaml', { source: entry.spec });
+    return [...new Set(all.map((o) => o.baseUrl).filter((u) => u !== ''))];
 }
 /**
  * The tools one `openapi:` entry gives an agent: buildOpenApiOwnTools' own