melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/tools/mcpToolFactory.js

@@ -11,12 +11,20 @@
  * The server is an untrusted tool vendor (ADR 0041): its URL passes the
  * SSRF guard, a credential goes only to its exact host, and its
  * descriptions and results are cut to a bound.
+ *
+ * A server that takes an OAuth token declares it in YAML (`mcp_auth:
+ * { oauth2 }`, ADR 0112): the server's own token (client_credentials) on one
+ * shared connection, or each user's (authorization_code) on that user's own
+ * connection, read through `ctx.accessToken` so a user who has not granted
+ * it is asked (ADR 0085).
  */
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
 import { toContractJsonSchema } from '../models/schemaNormalize.js';
 import { checkHost } from '../net/addressGuard.js';
 import { fetchWithRedirectPolicy } from '../net/redirects.js';
+import { ToolCredentialError } from './auth.js';
+import { oauthCallProblem, oauthTokenSource } from './oauthTools.js';
 import { MAX_RESULT_CHARS } from './tool.js';
 import { toGeminiSchema } from './toolContract.js';
 // Security (SSRF): mcp_server_url can arrive from a registry-stored syndicate
@@ -117,6 +125,8 @@ const openTransports = new Set();
 export async function closeMcpConnections() {
     const all = [...openTransports];
     openTransports.clear();
+    for (const pool of userPools)
+        pool.clear();
     await Promise.all(all.map((t) => t.close().catch(() => { })));
 }
 /**
@@ -135,19 +145,74 @@ export function mcpToolParameters(inputSchema) {
     const required = Array.isArray(inputSchema?.required) ? inputSchema.required : [];
     return toContractJsonSchema(toGeminiSchema({ type: 'object', properties, required }));
 }
+/** What the server says about one tool, as the contract declares it (description bounded). */
+function declarationOf(tool) {
+    return {
+        name: tool.name,
+        description: bounded(tool.description || `MCP Tool: ${tool.name}`, MAX_MCP_DESCRIPTION_CHARS, 'description'),
+        parameters: mcpToolParameters(tool.inputSchema),
+    };
+}
+/** A callTool result's text parts, joined and bounded. */
+function resultText(result) {
+    // MCP callTool returns { content: [{ type: 'text', text: '...' }] }
+    const content = (result?.content ?? []);
+    const texts = content.filter((c) => c.type === 'text').map((c) => c.text ?? '');
+    return bounded(texts.join('\n'), MAX_MCP_RESULT_CHARS, 'result');
+}
+/** A message with every occurrence of `secret` cut out: an SDK error can quote a request. */
+const redact = (message, secret) => (secret ? message.split(secret).join('[redacted]') : message);
+/**
+ * The fetch an MCP transport uses when the server takes an OAuth token
+ * (ADR 0112): every request (the SSE stream and each POST) carries the
+ * token `token()` returns now, and every redirect hop is checked, a hop off
+ * the server's origin losing the header (MCP_REDIRECTS).
+ */
+function bearerFetch(oauth2, token) {
+    return async (input, init) => {
+        // Every request is checked where it actually goes (the stream, and the
+        // 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, 'oauth');
+        const headers = new Headers(init?.headers);
+        headers.set('Authorization', `Bearer ${await token(destination)}`);
+        return mcpFetch(input, { ...init, headers });
+    };
+}
+/** Per-user connections at most per authorization-code server; the least recently used is closed first. */
+export const MAX_MCP_USER_CONNECTIONS = 64;
+/** Every per-user pool, so closeMcpConnections can empty them. */
+const userPools = new Set();
 /**
  * The tools a remote MCP server offers, as own Tools, or none when the
  * server cannot be reached or refuses (logged, never thrown). The
  * connection stays open for the tools' calls; closeMcpConnections ends it.
+ *
+ * With `oauth2` (ADR 0112):
+ *   - client_credentials: one connection, every request carrying the
+ *     server's own token for the provider (lib/tools/oauthTools.ts).
+ *   - authorization_code: the token is each user's, so there is no
+ *     connection at compile time. Each name in `tools` becomes a Tool whose
+ *     call reads the run's user's token (`ctx.accessToken`, which asks for
+ *     consent when the user has not granted it) and runs on that user's own
+ *     connection. The parameters are the server's, learned from the first
+ *     listing any user's connection makes; until then a call connects and
+ *     asks the model to call again with them, rather than call blind.
+ * A missing variable or a refused URL fails the compile (thrown), naming
+ * the variable, never a value.
  */
-export async function loadMcpTools(mcpServerUrl) {
+export async function loadMcpTools(mcpServerUrl, options = {}) {
+    const oauth2 = options.oauth2;
+    if (oauth2?.grant === 'authorization_code')
+        return userGrantMcpTools(mcpServerUrl, oauth2, options.tools);
+    const tokenSource = oauth2 ? oauthTokenSource(oauth2, `mcp ${mcpServerUrl}`, mcpServerUrl, { allowPrivate: process.env.ALLOW_PRIVATE_MCP === 'true' }) : undefined;
     let transport;
     try {
         const url = await assertSafeMcpUrl(mcpServerUrl);
-        transport = new SSEClientTransport(url, {
-            requestInit: { headers: mcpAuthHeaders(url) },
-            fetch: mcpFetch,
-        });
+        transport = new SSEClientTransport(url, tokenSource
+            ? { fetch: bearerFetch(oauth2, (destination) => tokenSource(undefined, destination)) }
+            : { requestInit: { headers: mcpAuthHeaders(url) }, fetch: mcpFetch });
         const client = new Client({
             name: 'melchizedek-a2a-client',
             version: '1.0.0'
@@ -161,33 +226,24 @@ export async function loadMcpTools(mcpServerUrl) {
         return toolsResponse.tools.map((tool) => {
             // MCP servers describe tools in standard lowercase JSON Schema, which
             // is the contract's dialect; mcpToolParameters derives the parameters.
-            const declaration = {
-                name: tool.name,
-                description: bounded(tool.description || `MCP Tool: ${tool.name}`, MAX_MCP_DESCRIPTION_CHARS, 'description'),
-                parameters: mcpToolParameters(tool.inputSchema),
-            };
+            const declaration = declarationOf(tool);
             return {
                 name: tool.name,
                 declaration: () => declaration,
                 execute: async (input) => {
                     try {
-                        const result = await client.callTool({
-                            name: tool.name,
-                            arguments: input
-                        });
-                        const content = result.content;
-                        const texts = content.filter(c => c.type === 'text').map(c => c.text ?? '');
-                        return bounded(texts.join('\n'), MAX_MCP_RESULT_CHARS, 'result');
+                        return resultText(await client.callTool({ name: tool.name, arguments: input }));
                     }
                     catch (error) {
-                        return `[MCP ERROR] Tool ${tool.name} failed: ${error.message}`;
+                        return `[MCP ERROR] Tool ${tool.name} failed: ${error instanceof ToolCredentialError ? error.message : error?.message}`;
                     }
                 },
             };
         });
     }
     catch (error) {
-        console.warn(`[MCP] Failed to connect or load tools from ${mcpServerUrl}`, error);
+        // A token that cannot be had is reported by kind; the rest as before.
+        console.warn(`[MCP] Failed to connect or load tools from ${mcpServerUrl}`, error instanceof ToolCredentialError ? error.message : error);
         // A failed connect leaves the SSE stream's reconnect timer running; close
         // it, or every unreachable server keeps retrying for the process's life.
         if (transport)
@@ -196,7 +252,109 @@ export async function loadMcpTools(mcpServerUrl) {
         return [];
     }
 }
+/** The tools of a server whose calls carry each user's own OAuth token (authorization_code). */
+function userGrantMcpTools(mcpServerUrl, oauth2, names) {
+    const where = `mcp ${mcpServerUrl}`;
+    if (!names?.length)
+        throw new Error(`${where}: an authorization_code mcp_auth needs mcp_tools, the names this agent may use (no user's grant exists to list them at startup)`);
+    const source = oauthTokenSource(oauth2, where, mcpServerUrl);
+    const provider = oauth2.provider;
+    /** The server's declarations, from the first listing any user's connection made. */
+    const known = new Map();
+    let listed = false;
+    const pool = new Map();
+    userPools.add(pool);
+    const drop = (key, conn) => {
+        if (pool.get(key) === conn)
+            pool.delete(key);
+        if (!conn.transport)
+            return;
+        openTransports.delete(conn.transport);
+        void conn.transport.close().catch(() => { });
+    };
+    const connectionFor = (key, token) => {
+        const held = pool.get(key);
+        if (held) {
+            held.holder.token = token;
+            // Most recently used last.
+            pool.delete(key);
+            pool.set(key, held);
+            return held.ready;
+        }
+        const holder = { token };
+        const conn = {};
+        conn.holder = holder;
+        conn.ready = (async () => {
+            const url = await assertSafeMcpUrl(mcpServerUrl);
+            const transport = new SSEClientTransport(url, { fetch: bearerFetch(oauth2, async () => holder.token) });
+            conn.transport = transport;
+            const client = new Client({ name: 'melchizedek-a2a-client', version: '1.0.0' }, { capabilities: {} });
+            await client.connect(transport);
+            openTransports.add(transport);
+            if (!listed) {
+                const offered = await client.listTools();
+                for (const tool of offered.tools)
+                    if (names.includes(tool.name))
+                        known.set(tool.name, declarationOf(tool));
+                listed = true;
+            }
+            return client;
+        })();
+        conn.ready.catch(() => drop(key, conn));
+        pool.set(key, conn);
+        while (pool.size > MAX_MCP_USER_CONNECTIONS) {
+            const [oldestKey, oldest] = pool.entries().next().value;
+            drop(oldestKey, oldest);
+        }
+        return conn.ready;
+    };
+    return names.map((name) => {
+        const placeholder = {
+            name,
+            description: `${name}, a tool on the ${provider} MCP server. Its parameters are known once this person has connected ${provider}; until then, call it with no arguments to connect.`,
+            parameters: mcpToolParameters(undefined),
+        };
+        return {
+            name,
+            declaration: () => known.get(name) ?? placeholder,
+            execute: async (input, ctx) => {
+                let token;
+                try {
+                    token = await source(ctx, mcpServerUrl);
+                }
+                catch (error) {
+                    return `[MCP ERROR] Tool ${name}: ${error instanceof ToolCredentialError ? error.message : `the ${provider} authorization could not be read.`}`;
+                }
+                if (!ctx?.appName || !ctx?.userId)
+                    return `[MCP ERROR] Tool ${name}: ${new ToolCredentialError('no_user', provider).message}`;
+                const key = `${ctx.appName}\0${ctx.userId}`;
+                const blind = !known.has(name);
+                let client;
+                try {
+                    client = await connectionFor(key, token);
+                }
+                catch {
+                    return `[MCP ERROR] Tool ${name}: the ${provider} MCP server could not be reached with this person's authorization.`;
+                }
+                if (!known.has(name))
+                    return `[MCP ERROR] Tool ${name}: the ${provider} MCP server does not offer it.`;
+                if (blind)
+                    return `Connected to ${provider}. ${name}'s parameters are now known: call it again with them.`;
+                try {
+                    return resultText(await client.callTool({ name, arguments: input }));
+                }
+                catch (error) {
+                    // The connection may be dead (or its token refused): the next call opens a fresh one.
+                    const conn = pool.get(key);
+                    if (conn)
+                        drop(key, conn);
+                    return `[MCP ERROR] Tool ${name} failed: ${redact(String(error?.message ?? error), token)}`;
+                }
+            },
+        };
+    });
+}
 /** The server's tools, as the compiler lists them on an agent: loadMcpTools' own Tools. */
-export async function createMcpTools(mcpServerUrl) {
-    return loadMcpTools(mcpServerUrl);
+export async function createMcpTools(mcpServerUrl, options = {}) {
+    return loadMcpTools(mcpServerUrl, options);
 }

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

@@ -0,0 +1,73 @@
+/**
+ * lib/tools/oauthHosts.ts — the operator's OAuth host allowlist: which hosts
+ * each provider's tokens may be sent to (WS6-3d, ADR 0114).
+ *
+ * WHY this file exists:
+ *   A YAML declares an OAuth grant beside the tool it protects (ADR 0112) and
+ *   chooses the host that tool calls. The credential store keys a user's
+ *   grant by app (the memory namespace), user and provider, so two syndicates
+ *   in one namespace share their users' grants. Without a binding, a
+ *   registry-stored YAML could name a provider another syndicate's users
+ *   granted and point a tool at a host of its own, and receive their tokens.
+ *   The binding is the operator's, never the YAML's: an environment variable
+ *   or `createA2AApp({ oauthHosts })`.
+ *
+ * THE RULE (ADR 0114):
+ *   - With no allowlist configured, an authorization_code grant (a user's
+ *     token) is refused; a client_credentials grant (the server's own token,
+ *     from a secret the operator supplies) is allowed, as `bearer_env` is.
+ *   - With an allowlist configured, it is the whole list: every grant's
+ *     provider must be on it, and every host its tokens or its client secret
+ *     go to (the API or MCP server, the token endpoint, the authorization
+ *     endpoint) must be one of that provider's hosts.
+ *   - The check runs when a syndicate is loaded to be served, when its tools
+ *     are compiled, and again before each call sends a token.
+ *
+ * THE FORMAT: `MELCHIZEDEK_OAUTH_HOSTS="tracker=api.tracker.example.com,auth.tracker.example.com;github=api.github.com,github.com"`.
+ *   Entries are separated by `;` (or a newline), a provider from its hosts by
+ *   `=`, hosts by `,`. A host is a hostname, `*.example.com` (any subdomain,
+ *   not the apex), an IPv4 address, or a bracketed IPv6 address. Ports and
+ *   schemes are not part of a host: the transport rule (https, or http to a
+ *   loopback host) is checked separately (tokenTransportProblem).
+ *
+ * Nothing here reads or prints a secret: hosts and provider names only. No
+ * regular expression here can backtrack: labels are split, then each is
+ * matched by one bounded character class.
+ */
+/** The environment variable the allowlist is read from when no option sets it. */
+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.
+ */
+export declare function checkOAuthHosts(allowlist: Record<string, readonly string[]>, source?: string): Record<string, string[]>;
+/** The allowlist from its text form (MELCHIZEDEK_OAUTH_HOSTS). Throws on a malformed entry. */
+export declare function parseOAuthHosts(text: string): Record<string, string[]>;
+/**
+ * Sets this process's allowlist (createA2AApp's `oauthHosts` does), which
+ * wins over the environment variable. `undefined` returns to the variable.
+ */
+export declare function setOAuthHosts(allowlist: Record<string, readonly string[]> | undefined): void;
+/**
+ * The allowlist in force: the one set by `setOAuthHosts`, else the
+ * environment variable's, else undefined (not configured). A malformed
+ * variable throws, so the first check refuses rather than allowing.
+ */
+export declare function oauthHosts(env?: NodeJS.ProcessEnv): OAuthHostAllowlist | undefined;
+/** True when `hostname` (as URL.hostname gives it) matches one of `patterns`. */
+export declare function hostAllowed(patterns: readonly string[], hostname: string): boolean;
+/** The grant fields the rule reads. */
+export interface OAuthGrantRef {
+    provider: string;
+    grant: 'authorization_code' | 'client_credentials';
+}
+/**
+ * Why a token (or client secret) of this grant 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; pass `null` for "not configured".
+ */
+export declare function oauthHostProblem(grant: OAuthGrantRef, url: string, role?: string, allowlist?: OAuthHostAllowlist | null | undefined): string | null;

package/dist/lib/tools/oauthHosts.js

@@ -0,0 +1,154 @@
+/**
+ * lib/tools/oauthHosts.ts — the operator's OAuth host allowlist: which hosts
+ * each provider's tokens may be sent to (WS6-3d, ADR 0114).
+ *
+ * WHY this file exists:
+ *   A YAML declares an OAuth grant beside the tool it protects (ADR 0112) and
+ *   chooses the host that tool calls. The credential store keys a user's
+ *   grant by app (the memory namespace), user and provider, so two syndicates
+ *   in one namespace share their users' grants. Without a binding, a
+ *   registry-stored YAML could name a provider another syndicate's users
+ *   granted and point a tool at a host of its own, and receive their tokens.
+ *   The binding is the operator's, never the YAML's: an environment variable
+ *   or `createA2AApp({ oauthHosts })`.
+ *
+ * THE RULE (ADR 0114):
+ *   - With no allowlist configured, an authorization_code grant (a user's
+ *     token) is refused; a client_credentials grant (the server's own token,
+ *     from a secret the operator supplies) is allowed, as `bearer_env` is.
+ *   - With an allowlist configured, it is the whole list: every grant's
+ *     provider must be on it, and every host its tokens or its client secret
+ *     go to (the API or MCP server, the token endpoint, the authorization
+ *     endpoint) must be one of that provider's hosts.
+ *   - The check runs when a syndicate is loaded to be served, when its tools
+ *     are compiled, and again before each call sends a token.
+ *
+ * THE FORMAT: `MELCHIZEDEK_OAUTH_HOSTS="tracker=api.tracker.example.com,auth.tracker.example.com;github=api.github.com,github.com"`.
+ *   Entries are separated by `;` (or a newline), a provider from its hosts by
+ *   `=`, hosts by `,`. A host is a hostname, `*.example.com` (any subdomain,
+ *   not the apex), an IPv4 address, or a bracketed IPv6 address. Ports and
+ *   schemes are not part of a host: the transport rule (https, or http to a
+ *   loopback host) is checked separately (tokenTransportProblem).
+ *
+ * Nothing here reads or prints a secret: hosts and provider names only. No
+ * regular expression here can backtrack: labels are split, then each is
+ * matched by one bounded character class.
+ */
+import { PROVIDER_NAME } from './auth.js';
+/** The environment variable the allowlist is read from when no option sets it. */
+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 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))
+        return null;
+    const name = pattern.startsWith('*.') ? pattern.slice(2) : pattern;
+    const labels = name.split('.');
+    if (labels.length < 1 || labels.some((l) => !LABEL.test(l) || l.startsWith('-') || l.endsWith('-'))) {
+        return 'is not a hostname, *.domain, IPv4 or [IPv6] address (no scheme, port or path)';
+    }
+    if (pattern.startsWith('*.') && labels.length < 2)
+        return 'is a wildcard over a top-level domain';
+    return null;
+}
+/**
+ * The allowlist, checked and normalized (hosts lowercased, duplicates
+ * dropped). Throws, naming the provider and the host, on anything malformed.
+ */
+export function checkOAuthHosts(allowlist, source = 'oauthHosts') {
+    if (!allowlist || typeof allowlist !== 'object' || Array.isArray(allowlist))
+        throw new Error(`${source} must map each provider to its hosts.`);
+    const out = {};
+    for (const [provider, hosts] of Object.entries(allowlist)) {
+        if (!PROVIDER_NAME.test(provider))
+            throw new Error(`${source}: provider "${provider.slice(0, 64)}" must match ${PROVIDER_NAME}.`);
+        if (!Array.isArray(hosts) || hosts.length === 0)
+            throw new Error(`${source}: provider "${provider}" 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}: provider "${provider}": host "${String(raw).slice(0, 80)}" ${problem}.`);
+            seen.add(host);
+        }
+        out[provider] = [...seen];
+    }
+    return out;
+}
+/** The allowlist from its text form (MELCHIZEDEK_OAUTH_HOSTS). Throws on a malformed entry. */
+export function parseOAuthHosts(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(`${OAUTH_HOSTS_ENV}: each entry is provider=host,host (got "${trimmed.slice(0, 80)}").`);
+        const provider = trimmed.slice(0, eq).trim();
+        if (Object.hasOwn(parsed, provider))
+            throw new Error(`${OAUTH_HOSTS_ENV}: provider "${provider.slice(0, 64)}" is listed twice.`);
+        parsed[provider] = trimmed.slice(eq + 1).split(',').map((h) => h.trim()).filter((h) => h !== '');
+    }
+    return checkOAuthHosts(parsed, OAUTH_HOSTS_ENV);
+}
+let configured;
+let envCache;
+/**
+ * Sets this process's allowlist (createA2AApp's `oauthHosts` does), which
+ * wins over the environment variable. `undefined` returns to the variable.
+ */
+export function setOAuthHosts(allowlist) {
+    configured = allowlist === undefined ? undefined : checkOAuthHosts(allowlist);
+}
+/**
+ * The allowlist in force: the one set by `setOAuthHosts`, else the
+ * environment variable's, else undefined (not configured). A malformed
+ * variable throws, so the first check refuses rather than allowing.
+ */
+export function oauthHosts(env = process.env) {
+    if (configured)
+        return configured;
+    const raw = env[OAUTH_HOSTS_ENV];
+    if (raw === undefined || raw.trim() === '')
+        return undefined;
+    if (envCache?.raw !== raw)
+        envCache = { raw, value: parseOAuthHosts(raw) };
+    return envCache.value;
+}
+/** True when `hostname` (as URL.hostname gives it) matches one of `patterns`. */
+export function hostAllowed(patterns, hostname) {
+    const host = hostname.toLowerCase();
+    return patterns.some((p) => (p.startsWith('*.') ? host.length > p.length - 1 && host.endsWith(p.slice(1)) : host === p));
+}
+/**
+ * Why a token (or client secret) of this grant 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; pass `null` for "not configured".
+ */
+export function oauthHostProblem(grant, url, role = 'server', allowlist = oauthHosts()) {
+    const list = allowlist ?? undefined;
+    if (!list) {
+        if (grant.grant === 'client_credentials')
+            return null;
+        return `provider "${grant.provider}": an authorization_code grant sends each user's own token, so the operator binds the provider to its hosts first (${OAUTH_HOSTS_ENV}="${grant.provider}=api.example.com,…", or createA2AApp's oauthHosts)`;
+    }
+    if (!Object.hasOwn(list, grant.provider)) {
+        return `provider "${grant.provider}" is not on the operator's OAuth host allowlist (${OAUTH_HOSTS_ENV} or createA2AApp's oauthHosts)`;
+    }
+    let hostname;
+    try {
+        hostname = new URL(url).hostname;
+    }
+    catch {
+        return `${role} '${url.slice(0, 200)}' is not a URL`;
+    }
+    const hosts = list[grant.provider];
+    if (hostAllowed(hosts, hostname))
+        return null;
+    return `provider "${grant.provider}" may send its tokens only to ${hosts.join(', ')}; ${hostname} (${role}) is not one of them`;
+}