melchizedek-agents 1.1.0 → 1.2.0

package/dist/lib/tools/credentialHosts.js

@@ -0,0 +1,165 @@
+/**
+ * lib/tools/credentialHosts.ts — the operator's credential host allowlist:
+ * which hosts the value of each static credential variable may be sent to
+ * (ADR 0122).
+ *
+ * WHY this file exists:
+ *   A syndicate YAML (possibly registry-stored) names a credential variable
+ *   and, beside it, the host its value goes to: an OpenAPI `auth` sends
+ *   `bearer_env` or `api_key.env` to the spec's server (or `base_url`), and
+ *   an `oauth2` block sends `client_secret_env` to its `token_url`.
+ *   credentialEnvProblem (lib/tools/credentialEnv.ts) keeps the framework's
+ *   own secrets out of reach, and the OAuth host allowlist (ADR 0114) binds
+ *   a provider's tokens, but nothing bound a static secret to its API: a
+ *   YAML that names TRACKER_TOKEN could aim it at a host of its own. The
+ *   binding is the operator's, never the YAML's: an environment variable or
+ *   `createA2AApp({ credentialHosts })`.
+ *
+ * THE RULE (ADR 0122):
+ *   - With no allowlist configured, nothing changes: a credential goes to
+ *     the host the YAML names, as before. The doctor and the server binary
+ *     name every credential variable a served YAML sends, as unbound.
+ *   - With an allowlist configured, it is the whole list: every credential
+ *     variable a YAML sends must be on it, and every host its value goes to
+ *     must be one of that variable's hosts.
+ *   - The check runs when a syndicate is loaded to be served, when its tools
+ *     are compiled, and again before each call sends the value.
+ *
+ * WHAT IT COVERS: `bearer_env`, `api_key.env` and `client_secret_env` (both
+ *   grants: the client-credentials token request, the consent step's code
+ *   exchange and its refresh). Not `client_id_env`: a client id is not a
+ *   secret. Not MCP_BEARER_TOKENS: it maps each token to its host already,
+ *   and the operator writes both.
+ *
+ * THE FORMAT: `MELCHIZEDEK_CREDENTIAL_HOSTS="TRACKER_TOKEN=api.tracker.example.com;WEATHER_KEY=api.weather.example.com,*.weather.example.com"`.
+ *   Entries are separated by `;` (or a newline), a variable from its hosts by
+ *   `=`, hosts by `,`. A host is what the OAuth host allowlist takes
+ *   (lib/tools/oauthHosts.ts): a hostname, `*.example.com`, IPv4 or
+ *   `[IPv6]`, with no scheme, port or path.
+ *
+ * Nothing here reads or prints a credential's value: variable names and
+ * hosts only. No regular expression here can backtrack: the separators are
+ * single characters, and a variable name is one bounded character class.
+ */
+import { hostAllowed, hostPatternProblem } from './oauthHosts.js';
+/** The environment variable the allowlist is read from when no option sets it. */
+export const CREDENTIAL_HOSTS_ENV = 'MELCHIZEDEK_CREDENTIAL_HOSTS';
+/** A credential variable's name, as a YAML may write it (lib/syndicateSchema.ts), bounded. */
+const ENV_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/;
+/**
+ * The allowlist, checked and normalized (hosts lowercased, duplicates
+ * dropped). Throws, naming the variable and the host, on anything malformed.
+ */
+export function checkCredentialHosts(allowlist, source = 'credentialHosts') {
+    if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist))
+        throw new Error(`${source} must map each credential variable to its hosts.`);
+    const out = {};
+    for (const [name, hosts] of Object.entries(allowlist)) {
+        if (!ENV_NAME.test(name))
+            throw new Error(`${source}: "${name.slice(0, 64)}" is not an environment variable name (A–Z, 0–9, _).`);
+        if (!Array.isArray(hosts) || hosts.length === 0)
+            throw new Error(`${source}: ${name} needs at least one host.`);
+        const seen = new Set();
+        for (const raw of hosts) {
+            const host = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+            const problem = host ? hostPatternProblem(host) : 'is empty';
+            if (problem)
+                throw new Error(`${source}: ${name}: host "${String(raw).slice(0, 80)}" ${problem}.`);
+            seen.add(host);
+        }
+        out[name] = [...seen];
+    }
+    return out;
+}
+/** The allowlist from its text form (MELCHIZEDEK_CREDENTIAL_HOSTS). Throws on a malformed entry. */
+export function parseCredentialHosts(text) {
+    const parsed = {};
+    for (const entry of text.split(/[;\n]/)) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq <= 0)
+            throw new Error(`${CREDENTIAL_HOSTS_ENV}: each entry is VARIABLE=host,host (got "${trimmed.slice(0, 80)}").`);
+        const name = trimmed.slice(0, eq).trim();
+        if (Object.hasOwn(parsed, name))
+            throw new Error(`${CREDENTIAL_HOSTS_ENV}: ${name.slice(0, 64)} is listed twice.`);
+        parsed[name] = trimmed.slice(eq + 1).split(',').map((h) => h.trim()).filter((h) => h !== '');
+    }
+    return checkCredentialHosts(parsed, CREDENTIAL_HOSTS_ENV);
+}
+let configured;
+let envCache;
+/**
+ * Sets this process's allowlist (createA2AApp's `credentialHosts` does),
+ * which wins over the environment variable. `undefined` returns to the
+ * variable.
+ */
+export function setCredentialHosts(allowlist) {
+    configured = allowlist === undefined ? undefined : checkCredentialHosts(allowlist);
+}
+/**
+ * The allowlist in force: the one set by `setCredentialHosts`, else the
+ * environment variable's, else undefined (not configured). A malformed
+ * variable throws, so the first check refuses rather than allowing.
+ */
+export function credentialHosts(env = process.env) {
+    if (configured)
+        return configured;
+    const raw = env[CREDENTIAL_HOSTS_ENV];
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    if (envCache?.raw !== raw)
+        envCache = { raw, value: parseCredentialHosts(raw) };
+    return envCache.value;
+}
+/**
+ * Why the value of credential variable `name` may not be sent to `url`, or
+ * null. `role` names the URL in the message (`server`, `token_url`).
+ * `allowlist` defaults to the one in force; `null` means none is
+ * configured, which allows (the behaviour before ADR 0122).
+ */
+export function credentialHostProblem(name, url, role = 'server', allowlist = credentialHosts()) {
+    const list = allowlist ?? undefined;
+    if (!list)
+        return null;
+    if (!Object.hasOwn(list, name)) {
+        return `${name} is not on the operator's credential host allowlist (${CREDENTIAL_HOSTS_ENV} or createA2AApp's credentialHosts), so it is sent nowhere`;
+    }
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return `${role} '${url.slice(0, 200)}' is not a URL`;
+    }
+    const hosts = list[name];
+    if (hostAllowed(hosts, hostname))
+        return null;
+    return `${name} may be sent only to ${hosts.join(', ')}; ${hostname} (${role}) is not one of them`;
+}
+/**
+ * The call-time check: why the value of `name` may not be sent to
+ * `destination` now, or null. A malformed allowlist refuses.
+ */
+export function credentialCallProblem(name, destination) {
+    try {
+        return credentialHostProblem(name, destination, 'server', credentialHosts() ?? null);
+    }
+    catch {
+        return `the credential host allowlist (${CREDENTIAL_HOSTS_ENV}) is malformed`;
+    }
+}
+/**
+ * Marks an OAuth client config (lib/tools/oauthConsent.ts) with the
+ * variable its client secret came from, so the consent step's code exchange
+ * and the refresh hook can check the token endpoint at call time. Set by
+ * oauthClientsFor (lib/tools/oauthTools.ts); a client built by hand carries
+ * none and is not checked.
+ */
+export const CLIENT_SECRET_ENV = Symbol.for('melchizedek.clientSecretEnv');
+/** The variable a client config's secret came from, when oauthClientsFor marked it. */
+export function clientSecretEnvOf(client) {
+    const name = client[CLIENT_SECRET_ENV];
+    return typeof name === 'string' ? name : undefined;
+}

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

@@ -0,0 +1,92 @@
+/**
+ * lib/tools/credentialUses.ts — every static credential variable a syndicate
+ * YAML sends somewhere, and where (ADR 0122).
+ *
+ * A YAML sends a static credential in three places: an OpenAPI entry's
+ * `auth.bearer_env` or `auth.api_key.env` (to the spec's server, or
+ * `base_url`), and an `oauth2` block's `client_secret_env` (to its
+ * `token_url`; the OpenAPI entry's or the MCP server's `mcp_auth`). The
+ * operator's credential host allowlist (lib/tools/credentialHosts.ts) is
+ * checked against them when a served syndicate loads
+ * (`syndicateCredentialHostProblems`), and the doctor and the server binary
+ * name each variable no allowlist binds (`unboundCredentialEnvs`).
+ *
+ * Names and hosts only: no value is read here.
+ */
+import type { CredentialHostAllowlist } from './credentialHosts.ts';
+/** One credential variable a YAML sends, and to what. */
+export interface CredentialUse {
+    /** The agent that holds the tools ("Parent › Child" inside a nested file). */
+    agent: string;
+    /** `openapi <spec>` or `mcp <url>`. */
+    tools: string;
+    /** The variable's name. */
+    env: string;
+    /** Where the YAML names it. */
+    role: 'bearer_env' | 'api_key' | 'client_secret_env';
+    /**
+     * The URLs its value goes to: the token endpoint for a client secret,
+     * `base_url` for an OpenAPI entry that sets one. Absent for an OpenAPI
+     * entry whose server is in its spec (read only when checked, by
+     * `syndicateCredentialHostProblems`).
+     */
+    destinations?: string[];
+    /** The OpenAPI entry, for its spec's servers. */
+    openapi?: OpenApiEntryLike;
+}
+/** The parts of an `oauth2` block read here. */
+interface OAuth2Like {
+    token_url: string;
+    client_secret_env?: string;
+}
+/** The parts of an `openapi:` entry read here. */
+interface OpenApiEntryLike {
+    spec?: string;
+    base_url?: string;
+    auth?: {
+        bearer_env?: string;
+        api_key?: {
+            env?: string;
+        };
+        oauth2?: OAuth2Like;
+    };
+}
+interface AgentLike {
+    name?: string;
+    openapi?: OpenApiEntryLike[];
+    mcp_server_url?: string;
+    mcp_auth?: {
+        oauth2?: OAuth2Like;
+    };
+    yaml_reference?: string;
+}
+/** The parts of a syndicate config read here. */
+export interface SyndicateLike {
+    orchestrator?: AgentLike;
+    subagents?: AgentLike[];
+}
+/** The credential variables one agent's tools send. */
+export declare function agentCredentialUses(agent: AgentLike, prefix?: string): CredentialUse[];
+/**
+ * Every credential variable these syndicates send, orchestrators and
+ * subagents, following a nested `yaml_reference:` through `load` when given
+ * (once per file; agent names then read "Parent › Child").
+ */
+export declare function syndicateCredentialUses(configs: readonly SyndicateLike[], load?: (ref: string) => SyndicateLike): CredentialUse[];
+/**
+ * Why these syndicates may not be served here, one line per refusal
+ * (ADR 0122): each credential variable they send, against the operator's
+ * credential host allowlist. With none configured, nothing is refused. The
+ * A2A server checks every syndicate it loads to serve; the compile checks
+ * again, and each call once more.
+ */
+export declare function syndicateCredentialHostProblems(configs: readonly SyndicateLike[], options?: {
+    load?: (ref: string) => SyndicateLike;
+    allowlist?: CredentialHostAllowlist | null;
+}): string[];
+/**
+ * The credential variables these uses send that no allowlist binds, sorted
+ * and once each: every one of them when none is configured. Names only.
+ */
+export declare function unboundCredentialEnvs(uses: readonly CredentialUse[], allowlist: CredentialHostAllowlist | null | undefined): string[];
+export {};

package/dist/lib/tools/credentialUses.js

@@ -0,0 +1,112 @@
+/**
+ * lib/tools/credentialUses.ts — every static credential variable a syndicate
+ * YAML sends somewhere, and where (ADR 0122).
+ *
+ * A YAML sends a static credential in three places: an OpenAPI entry's
+ * `auth.bearer_env` or `auth.api_key.env` (to the spec's server, or
+ * `base_url`), and an `oauth2` block's `client_secret_env` (to its
+ * `token_url`; the OpenAPI entry's or the MCP server's `mcp_auth`). The
+ * operator's credential host allowlist (lib/tools/credentialHosts.ts) is
+ * checked against them when a served syndicate loads
+ * (`syndicateCredentialHostProblems`), and the doctor and the server binary
+ * name each variable no allowlist binds (`unboundCredentialEnvs`).
+ *
+ * Names and hosts only: no value is read here.
+ */
+import { resolve } from 'node:path';
+import { credentialHostProblem, credentialHosts } from './credentialHosts.js';
+import { openApiServers } from './openapiTools.js';
+/** The credential variables one agent's tools send. */
+export function agentCredentialUses(agent, prefix = '') {
+    const name = `${prefix}${agent.name ?? ''}`;
+    const out = [];
+    for (const entry of agent.openapi ?? []) {
+        const tools = `openapi ${entry?.spec ?? ''}`;
+        const auth = entry?.auth;
+        if (!auth)
+            continue;
+        const servers = entry.base_url ? { destinations: [entry.base_url] } : {};
+        if (auth.bearer_env)
+            out.push({ agent: name, tools, env: auth.bearer_env, role: 'bearer_env', ...servers, openapi: entry });
+        if (auth.api_key?.env)
+            out.push({ agent: name, tools, env: auth.api_key.env, role: 'api_key', ...servers, openapi: entry });
+        if (auth.oauth2?.client_secret_env)
+            out.push({ agent: name, tools, env: auth.oauth2.client_secret_env, role: 'client_secret_env', destinations: [auth.oauth2.token_url] });
+    }
+    const mcp = agent.mcp_auth?.oauth2;
+    if (mcp?.client_secret_env)
+        out.push({ agent: name, tools: `mcp ${agent.mcp_server_url ?? ''}`, env: mcp.client_secret_env, role: 'client_secret_env', destinations: [mcp.token_url] });
+    return out;
+}
+/**
+ * Every credential variable these syndicates send, orchestrators and
+ * subagents, following a nested `yaml_reference:` through `load` when given
+ * (once per file; agent names then read "Parent › Child").
+ */
+export function syndicateCredentialUses(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(...agentCredentialUses(agent, prefix));
+        }
+    };
+    for (const config of configs)
+        visit(config, '');
+    return out;
+}
+/** The URLs a use's value goes to; an OpenAPI spec that cannot be read gives none (its compile fails on its own). */
+function destinationsOf(use) {
+    if (use.destinations)
+        return use.destinations;
+    if (!use.openapi?.spec)
+        return [];
+    try {
+        return openApiServers(use.openapi, resolve(process.cwd()));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Why these syndicates may not be served here, one line per refusal
+ * (ADR 0122): each credential variable they send, against the operator's
+ * credential host allowlist. With none configured, nothing is refused. The
+ * A2A server checks every syndicate it loads to serve; the compile checks
+ * again, and each call once more.
+ */
+export function syndicateCredentialHostProblems(configs, options = {}) {
+    const allowlist = options.allowlist === undefined ? credentialHosts() ?? null : options.allowlist;
+    if (!allowlist)
+        return [];
+    const out = new Set();
+    for (const use of syndicateCredentialUses(configs, options.load)) {
+        const role = use.role === 'client_secret_env' ? 'token_url' : 'server';
+        const where = `${use.agent} · ${use.tools} · ${use.role}`;
+        if (!Object.hasOwn(allowlist, use.env)) {
+            out.add(`${where}: ${credentialHostProblem(use.env, '', role, allowlist)}`);
+            continue;
+        }
+        for (const url of destinationsOf(use)) {
+            const problem = credentialHostProblem(use.env, url, role, allowlist);
+            if (problem)
+                out.add(`${where}: ${problem}`);
+        }
+    }
+    return [...out];
+}
+/**
+ * The credential variables these uses send that no allowlist binds, sorted
+ * and once each: every one of them when none is configured. Names only.
+ */
+export function unboundCredentialEnvs(uses, allowlist) {
+    return [...new Set(uses.map((u) => u.env))].filter((name) => !allowlist || !Object.hasOwn(allowlist, name)).sort();
+}

package/dist/lib/tools/mcpToolFactory.js

@@ -174,7 +174,7 @@ function bearerFetch(oauth2, token) {
         // message endpoint the server names), before a token is attached (ADR 0114).
         const destination = input instanceof Request ? input.url : String(input);
         if (oauthCallProblem(oauth2, destination))
-            throw new ToolCredentialError('host_refused', oauth2.provider);
+            throw new ToolCredentialError('host_refused', oauth2.provider, 'oauth');
         const headers = new Headers(init?.headers);
         headers.set('Authorization', `Bearer ${await token(destination)}`);
         return mcpFetch(input, { ...init, headers });

package/dist/lib/tools/oauthConsent.js

@@ -38,6 +38,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { scopeHashOf } from '../observability/audit.js';
 import { PROVIDER_NAME } from './auth.js';
+import { clientSecretEnvOf, credentialCallProblem } from './credentialHosts.js';
 /**
  * Flows in this process's memory, at most `max` of them: the oldest is
  * dropped first, and an expired one whenever another is put.
@@ -192,8 +193,14 @@ export function oauthConsent(options) {
             client_id: client.clientId,
             code_verifier: flow.codeVerifier,
         });
-        if (client.clientSecret)
+        if (client.clientSecret) {
+            // The secret goes only to a host the operator binds its variable to (ADR 0122), checked now:
+            // the allowlist can change after boot. Refused, nothing is sent.
+            const secretEnv = clientSecretEnvOf(client);
+            if (secretEnv && credentialCallProblem(secretEnv, client.tokenUrl))
+                throw new ConsentError('exchange_failed', flow.provider);
             body.set('client_secret', client.clientSecret);
+        }
         let json;
         try {
             const res = await doFetch(client.tokenUrl, {

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

@@ -38,6 +38,8 @@
 export declare const OAUTH_HOSTS_ENV = "MELCHIZEDEK_OAUTH_HOSTS";
 /** Provider name → the hosts its tokens may be sent to. */
 export type OAuthHostAllowlist = Readonly<Record<string, readonly string[]>>;
+/** Why `pattern` is not a host an allowlist can hold, or null (lowercased, trimmed). Also lib/tools/credentialHosts.ts. */
+export declare function hostPatternProblem(pattern: string): string | null;
 /**
  * The allowlist, checked and normalized (hosts lowercased, duplicates
  * dropped). Throws, naming the provider and the host, on anything malformed.

package/dist/lib/tools/oauthHosts.js

@@ -39,8 +39,8 @@ import { PROVIDER_NAME } from './auth.js';
 export const OAUTH_HOSTS_ENV = 'MELCHIZEDEK_OAUTH_HOSTS';
 const LABEL = /^[a-z0-9-]{1,63}$/;
 const IPV6 = /^\[[0-9a-f:.]{2,45}\]$/;
-/** Why `pattern` is not a host the allowlist can hold, or null. */
-function hostPatternProblem(pattern) {
+/** Why `pattern` is not a host an allowlist can hold, or null (lowercased, trimmed). Also lib/tools/credentialHosts.ts. */
+export function hostPatternProblem(pattern) {
     if (pattern.length > 253)
         return 'is longer than 253 characters';
     if (IPV6.test(pattern))

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

@@ -51,6 +51,13 @@
  *   (`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';
@@ -149,7 +156,9 @@ export declare function clientCredentialsGrant(options: ClientCredentialsOptions
 /**
  * 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.
+ * 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>;
 /**

package/dist/lib/tools/oauthTools.js

@@ -51,10 +51,18 @@
  *   (`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 = '') {
@@ -264,7 +272,7 @@ export function oauthTokenSource(oauth2, where, server, options = {}) {
     /** 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);
+            throw new ToolCredentialError('host_refused', provider, 'oauth');
     };
     if (oauth2.grant === 'authorization_code') {
         return async (ctx, destination) => {
@@ -285,6 +293,11 @@ export function oauthTokenSource(oauth2, where, server, options = {}) {
         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,
@@ -296,8 +309,11 @@ export function oauthTokenSource(oauth2, where, server, options = {}) {
     });
     return async (ctx, destination) => {
         refuse(destination);
-        // The client secret goes to the token endpoint: held to the same rule.
+        // 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);
     };
 }
@@ -326,6 +342,10 @@ export function oauthClientsFor(configs, options = {}) {
         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) {
@@ -341,6 +361,8 @@ export function oauthClientsFor(configs, options = {}) {
             ...(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;
@@ -403,7 +425,11 @@ export function oauthRefreshProviders(clients, options = {}) {
             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);
+                    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);

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

@@ -45,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

@@ -36,6 +36,12 @@
  *     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
@@ -67,6 +73,7 @@ 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';
@@ -89,11 +96,15 @@ function credentialFor(auth, spec) {
         return undefined;
     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).
@@ -138,11 +149,25 @@ function readSpec(specPath, source) {
  * 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, credential, oauth) {
+function operationTool(op, held, oauth) {
+    const credential = held?.credential;
     const tool = {
         name: op.name,
         declaration: () => op.declaration,
         async execute(args, ctx) {
+            // 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 {
@@ -186,12 +211,17 @@ 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}`);
     }
     let oauth;
     if (entry.auth?.oauth2 && chosen.length) {
@@ -205,6 +235,22 @@ export async function buildOpenApiOwnTools(entry, baseDir = process.cwd()) {
     }
     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
  * Tools, each marked so require_approval can name it by its operationId.