@fastagent-sh/fastagent 0.28.0 → 0.30.0

package/dist/mcp/config.js

@@ -0,0 +1,225 @@
+/**
+ * The MCP servers an instance opens (agent-artifact.md §3.3, §4.2): the program's, the `mcpServers` map of its
+ * `context.json`, and what the instance adds, the `mcpServers` map of its `fastagent.json`. One list, read once, that
+ * every reader (the open, `inspectMcp`, sign-in, the secrets list, the build's warning) is given.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import * as Schema from "effect/Schema";
+import * as SchemaIssue from "effect/SchemaIssue";
+import { readProgramMcpServers } from "../content/file.js";
+import { isEnvName } from "../declared-secrets.js";
+import { McpError } from "../mcp-api.js";
+import { CONTEXT_FILE } from "../paths.js";
+const Strings = Schema.Record(Schema.String, Schema.String);
+const Stdio = Schema.Struct({
+    type: Schema.optional(Schema.Literal("stdio")),
+    command: Schema.NonEmptyString,
+    args: Schema.optional(Schema.Array(Schema.String)),
+    env: Schema.optional(Strings),
+});
+const Http = Schema.Struct({
+    type: Schema.Literal("http"),
+    url: Schema.String,
+    headers: Schema.optional(Strings),
+});
+const Declaration = Schema.Union([Stdio, Http]);
+const Servers = Schema.Record(Schema.String, Declaration);
+/** The `mcpServers` map `raw` holds (undefined is none), checked; every refusal names `file` and, where it can, the server. */
+function declareServers(raw, file) {
+    if (raw === undefined)
+        return {};
+    let servers;
+    try {
+        servers = Schema.decodeUnknownSync(Servers)(raw, { onExcessProperty: "error" });
+    }
+    catch (error) {
+        const paths = error instanceof Error && SchemaIssue.isIssue(error.cause)
+            ? SchemaIssue.makeFormatterStandardSchemaV1()(error.cause).issues.map((issue) => issue.path)
+            : [];
+        throw new McpError("configuration", `${file}: invalid MCP configuration at ${JSON.stringify(paths)}; expected stdio command/args/env or http url/headers; unknown fields are refused`);
+    }
+    for (const [name, server] of Object.entries(servers)) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(name) || name.includes("__") || name.length > 40) {
+            throw new McpError("configuration", `${file}: server names must be 1–40 letters, digits, hyphens or underscores, without __`);
+        }
+        if (server.type === "http")
+            checkMcpUrl(server.url, name, file);
+        else
+            for (const key of Object.keys(server.env ?? {})) {
+                if (!isEnvName(key))
+                    throw new McpError("configuration", `${file}: invalid environment variable name for ${name}`, name);
+            }
+        for (const value of configStrings(server))
+            variables(value, name, file);
+    }
+    return servers;
+}
+/** An instance's servers, checked: what `resolveConfig` asks of a configuration, so its refusal is the file's. */
+export function checkInstanceServers(instance) {
+    declareServers(mapOf(instance.values), instance.label);
+}
+const mapOf = (values) => typeof values === "object" && values !== null ? values.mcpServers : undefined;
+/**
+ * The servers of the program in `dir` and of `instance`. An instance only adds: a name both declare is refused, naming
+ * both, so nothing is shadowed.
+ */
+export function declareMcp(dir, instance) {
+    const own = readProgramMcpServers(dir);
+    const program = Object.entries(declareServers(own.values, own.path)).map(([name, server]) => ({ name, server, file: CONTEXT_FILE, base: resolve(dir), origin: "program" }));
+    if (instance === undefined)
+        return program;
+    const added = Object.entries(declareServers(mapOf(instance.values), instance.label)).map(([name, server]) => ({
+        name,
+        server,
+        file: instance.label,
+        ...(instance.directory === undefined ? {} : { base: instance.directory }),
+        origin: "instance",
+    }));
+    for (const { name } of added) {
+        if (program.some((declared) => declared.name === name)) {
+            throw new McpError("configuration", `MCP server "${name}" is declared by the program (${CONTEXT_FILE}) and by the instance (${instance.label}): an ` +
+                `instance adds to the program's servers and does not replace them — name it otherwise`);
+        }
+    }
+    return [...program, ...added];
+}
+/** An instance configuration given to `inspectMcp` or `signInMcp`: an object, or the absolute path of a `fastagent.json`. */
+export function mcpInstance(config) {
+    if (config === undefined)
+        return undefined;
+    if (typeof config !== "string")
+        return { values: config, label: "the config object" };
+    if (!isAbsolute(config))
+        throw new McpError("configuration", `config must be an absolute path, and is ${JSON.stringify(config)}`);
+    let text;
+    try {
+        text = readFileSync(config, "utf8");
+    }
+    catch (error) {
+        throw new McpError("configuration", `cannot read the instance configuration ${config}: ${error.message}`);
+    }
+    try {
+        return { values: JSON.parse(text), label: config, directory: dirname(config) };
+    }
+    catch (error) {
+        throw new McpError("configuration", `${config} is not JSON: ${error.message}`);
+    }
+}
+function configStrings(server) {
+    return server.type === "http"
+        ? Object.values(server.headers ?? {})
+        : [server.command, ...(server.args ?? []), ...Object.values(server.env ?? {})];
+}
+function variables(value, server, file) {
+    const names = [];
+    const rest = value.replace(/\$\{([^}]*)\}/g, (_match, name) => {
+        if (!isEnvName(name))
+            throw new McpError("configuration", `${file}: ${server} supports only \${NAME} substitutions`, server);
+        names.push(name);
+        return "";
+    });
+    if (rest.includes("${") || rest.includes("$("))
+        throw new McpError("configuration", `${file}: unsupported substitution in ${server}`, server);
+    return names;
+}
+/** The secrets the servers' `${NAME}` references need: each required, declared where the server is. */
+export function mcpSecrets(declarations) {
+    return declarations.flatMap(({ name, server, file }) => configStrings(server).flatMap((value) => variables(value, name, file).map((secret) => ({
+        name: secret,
+        declaredIn: `${file} mcpServers.${name}`,
+        optional: false,
+    }))));
+}
+/**
+ * The header and environment values with no `${VAR}` in them: the format allows a literal credential, and where the
+ * file travels (a build publishes it, a deploy bakes or delivers it) each is said. FastAgent cannot tell a secret from a
+ * setting, so a caller warns and never refuses.
+ */
+export function literalCredentials(declarations) {
+    return declarations.flatMap(({ name, server, file }) => {
+        const [field, entries] = server.type === "http" ? ["headers", server.headers ?? {}] : ["env", server.env ?? {}];
+        return Object.entries(entries)
+            .filter(([, value]) => value !== "" && !value.includes("${"))
+            .map(([key]) => ({ file, server: name, field, key }));
+    });
+}
+/**
+ * The stdio servers whose command is a path relative to the file that declares it, as it is written: what a build or a
+ * deploy has to be able to deliver, since a script is not found on a `PATH`. A command that starts with a `${VAR}` is
+ * left to the variable, and `args` are never read as paths, since FastAgent cannot know which strings are.
+ */
+export function relativeCommands(declarations) {
+    return declarations.flatMap((declaration) => {
+        const { server } = declaration;
+        const command = server.type === "http" ? undefined : server.command;
+        return command !== undefined && /[/\\]/.test(command) && !isAbsolute(command) && !command.startsWith("${")
+            ? [{ ...declaration, command }]
+            : [];
+    });
+}
+/** What to write instead of a literal credential, which a header's value usually carries a scheme in front of. */
+export function literalCredentialAdvice({ field, key }) {
+    const name = key.toUpperCase().replace(/[^A-Z0-9_]/g, "_");
+    return field === "headers"
+        ? `replace the secret in it with \${${name}} (a scheme stays: \`Bearer \${${name}}\`)`
+        : `write \${${name}}`;
+}
+export function checkMcpUrl(value, server, file = "mcpServers") {
+    const url = URL.parse(value);
+    if (!url ||
+        value.includes("${") ||
+        value.includes("$(") ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        (url.protocol !== "https:" &&
+            !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))) {
+        throw new McpError("configuration", `${file}: MCP endpoints require HTTPS (HTTP is allowed only on loopback), without userinfo or fragments`, server);
+    }
+    return url;
+}
+export function resolveMcpServers(declarations, env, only, 
+/** Where a stdio server runs: the instance's workspace, whoever declared it. */
+cwd, 
+/** What every process the instance starts gets (child-env.ts), under a stdio server's own `env`. */
+processEnv) {
+    return declarations
+        .filter(({ name }) => only === undefined || name === only)
+        .map(({ name, server, file, base }) => {
+        const expand = (value) => value.replace(/\$\{([^}]*)\}/g, (_match, key) => {
+            const result = env[key];
+            if (!result)
+                throw new McpError("configuration", `${file}: ${name} requires ${key}`, name);
+            return result;
+        });
+        if (server.type === "http") {
+            const headers = Object.fromEntries(Object.entries(server.headers ?? {}).map(([key, value]) => [key, expand(value)]));
+            try {
+                new Headers(headers);
+            }
+            catch {
+                throw new McpError("configuration", `${file}: invalid HTTP headers for ${name}`, name);
+            }
+            return { name, type: "http", url: checkMcpUrl(server.url, name, file).href, headers };
+        }
+        let command = expand(server.command);
+        if (!isAbsolute(command) && /[/\\]/.test(command)) {
+            if (base === undefined) {
+                throw new McpError("configuration", `${file}: the command "${command}" has a path and no file to be relative to: write an absolute path or a bare command`, name);
+            }
+            command = resolve(base, command);
+        }
+        return {
+            name,
+            type: "stdio",
+            command,
+            args: (server.args ?? []).map(expand),
+            cwd: resolve(cwd),
+            env: {
+                ...processEnv,
+                ...Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(value)])),
+            },
+        };
+    });
+}

package/dist/mcp/grants.d.ts

@@ -0,0 +1,4 @@
+import { type McpGrantRecord, type McpGrantStore, type McpGrantSummary } from "../mcp-api.ts";
+export declare function checkedGrant(value: unknown): McpGrantRecord;
+export declare function grantSummary(id: string, record: McpGrantRecord): McpGrantSummary;
+export declare function mcpGrantFile(path: string): McpGrantStore;

package/dist/mcp/grants.js

@@ -0,0 +1,132 @@
+/** Durable OAuth grants: explicit writes under the same lock that guards refresh and deletion. */
+import { lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import * as Schema from "effect/Schema";
+import { withLockedFile } from "../locked-file.js";
+import { McpError } from "../mcp-api.js";
+const RecordSchema = Schema.Struct({
+    version: Schema.Literal(1),
+    serverUrl: Schema.NonEmptyString,
+    resource: Schema.NonEmptyString,
+    issuer: Schema.NonEmptyString,
+    client: Schema.Struct({
+        id: Schema.NonEmptyString,
+        secret: Schema.optional(Schema.String),
+        tokenEndpointAuthMethod: Schema.Literals(["none", "client_secret_post", "client_secret_basic"]),
+    }),
+    scopes: Schema.Array(Schema.NonEmptyString),
+    status: Schema.Literals(["ready", "refreshing", "reauthorization_required"]),
+    generation: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+    accessToken: Schema.NonEmptyString,
+    refreshToken: Schema.optional(Schema.NonEmptyString),
+    expiresAt: Schema.optional(Schema.Number.check(Schema.isFinite())),
+});
+const FileSchema = Schema.Record(Schema.String, RecordSchema);
+export function checkedGrant(value) {
+    try {
+        return Schema.decodeUnknownSync(RecordSchema)(value, { onExcessProperty: "error" });
+    }
+    catch {
+        throw new McpError("storage", "Invalid MCP grant record; refusing to read or overwrite credentials");
+    }
+}
+export function grantSummary(id, record) {
+    return {
+        id,
+        serverUrl: record.serverUrl,
+        resource: record.resource,
+        issuer: record.issuer,
+        scopes: [...record.scopes],
+        status: record.status,
+        ...(record.expiresAt === undefined ? {} : { expiresAt: record.expiresAt }),
+    };
+}
+function decode(raw, path) {
+    if (raw === undefined)
+        return {};
+    try {
+        return Schema.decodeUnknownSync(Schema.fromJsonString(FileSchema))(raw, { onExcessProperty: "error" });
+    }
+    catch {
+        throw new McpError("storage", `Invalid MCP grant file ${path}; refusing to overwrite it`);
+    }
+}
+function idIsValid(id) {
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(id) || ["__proto__", "constructor", "prototype"].includes(id)) {
+        throw new McpError("storage", "Invalid MCP grant ID");
+    }
+}
+function grantFileTarget(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        const link = lstatSync(path, { throwIfNoEntry: false });
+        return link?.isSymbolicLink()
+            ? grantFileTarget(resolve(dirname(path), readlinkSync(path)))
+            : resolve(grantFileTarget(dirname(path)), basename(path));
+    }
+}
+export function mcpGrantFile(path) {
+    const file = resolve(path);
+    const read = () => {
+        try {
+            return decode(readFileSync(file, "utf8"), file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return {};
+            throw error;
+        }
+    };
+    return {
+        async read(id) {
+            idIsValid(id);
+            const records = read();
+            return Object.hasOwn(records, id) ? records[id] : undefined;
+        },
+        async list() {
+            return Object.entries(read()).map(([id, value]) => grantSummary(id, value));
+        },
+        withGrant(id, operation) {
+            idIsValid(id);
+            // The shared lock helper preserves pi credential path spellings; MCP locks the backing file itself.
+            return withLockedFile(grantFileTarget(file), async (raw, replace) => {
+                let records = decode(raw, file);
+                const save = (next) => {
+                    replace(`${JSON.stringify(next)}\n`);
+                    records = next;
+                };
+                let active = true;
+                const assertActive = () => {
+                    if (!active)
+                        throw new McpError("storage", "MCP grant access escaped its exclusive scope");
+                };
+                try {
+                    const result = await operation({
+                        read() {
+                            assertActive();
+                            return Object.hasOwn(records, id) ? checkedGrant(records[id]) : undefined;
+                        },
+                        async write(value) {
+                            assertActive();
+                            save({ ...records, [id]: checkedGrant(value) });
+                        },
+                        async remove() {
+                            assertActive();
+                            const next = { ...records };
+                            delete next[id];
+                            save(next);
+                        },
+                    });
+                    return { result };
+                }
+                finally {
+                    active = false;
+                }
+            }, { create: false });
+        },
+    };
+}

package/dist/mcp/host.d.ts

@@ -0,0 +1,19 @@
+import { type McpAuthorization, type McpInspectOptions, type McpOptions, type McpServerSummary } from "../mcp-api.ts";
+import { type McpServer } from "./config.ts";
+/** The project's `.secrets/`: where the CLI keeps them. A write first makes the directory ignored by git. */
+export declare function mcpAuthorization(dir: string, env: NodeJS.ProcessEnv, stateRoot: string, options?: McpOptions): McpAuthorization;
+/** The instance's state directory: where an app that is given no store keeps them, beside its other state. */
+export declare function mcpAuthorizationInState(stateRoot: string, options?: McpOptions): McpAuthorization;
+export declare function writeMcpBinding(stateRoot: string, server: string, id: string | undefined): Promise<void>;
+export declare function mcpContext(dir: string, options?: McpOptions): {
+    agentDir: string;
+    environment: {
+        [x: string]: string | undefined;
+    };
+    stateRoot: string;
+    auth: McpAuthorization;
+};
+export declare function httpServer(servers: readonly McpServer[], name: string): Extract<McpServer, {
+    type: "http";
+}>;
+export declare function inspectMcp(dir: string, options?: McpInspectOptions): Promise<McpServerSummary[]>;

package/dist/mcp/host.js

@@ -0,0 +1,128 @@
+/** MCP declarations and authorization bindings before an agent is opened. */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import * as Schema from "effect/Schema";
+import { McpError, } from "../mcp-api.js";
+import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
+import { agentValues, prepareSecretsDirectory, unprotectedSecretsNote } from "../value-file.js";
+import { log } from "../log.js";
+import { withLockedFile } from "../locked-file.js";
+import { checkedGrant, mcpGrantFile } from "./grants.js";
+import { checkMcpUrl, declareMcp, mcpInstance } from "./config.js";
+const Bindings = Schema.Record(Schema.String, Schema.String);
+function decodeBindings(raw) {
+    if (raw === undefined)
+        return {};
+    try {
+        return Schema.decodeUnknownSync(Schema.fromJsonString(Bindings))(raw);
+    }
+    catch {
+        throw new McpError("storage", "Invalid MCP bindings file; refusing to overwrite it");
+    }
+}
+/** The project's `.secrets/`: where the CLI keeps them. A write first makes the directory ignored by git. */
+export function mcpAuthorization(dir, env, stateRoot, options = {}) {
+    const secretsDir = resolveSecretsDir(dir, env);
+    return authorizationIn({ file: join(secretsDir, "mcp-auth.json"), prepare: () => prepareSecretsDirectory(dir, secretsDir) }, stateRoot, options);
+}
+/** The instance's state directory: where an app that is given no store keeps them, beside its other state. */
+export function mcpAuthorizationInState(stateRoot, options = {}) {
+    return authorizationIn({ file: join(stateRoot, "mcp-auth.json") }, stateRoot, options);
+}
+function authorizationIn(home, stateRoot, options) {
+    if ((options.store === undefined) !== (options.bindings === undefined))
+        throw new McpError("configuration", "MCP store and bindings must be supplied together");
+    if (options.store && options.bindings)
+        return { store: options.store, bindings: { ...options.bindings } };
+    const path = join(stateRoot, "mcp-bindings.json");
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const file = mcpGrantFile(home.file);
+    const protectedWrite = async (write) => {
+        const unprotected = await home.prepare?.();
+        await write();
+        if (unprotected !== undefined)
+            log.warn(`[fastagent] ${unprotectedSecretsNote(unprotected)}`);
+    };
+    return {
+        store: {
+            ...file,
+            withGrant: (id, operation) => file.withGrant(id, (access) => operation({
+                ...access,
+                write: (record) => protectedWrite(() => access.write(record)),
+                remove: () => protectedWrite(() => access.remove()),
+            })),
+        },
+        bindings: decodeBindings(raw),
+    };
+}
+export async function writeMcpBinding(stateRoot, server, id) {
+    await withLockedFile(join(stateRoot, "mcp-bindings.json"), async (raw) => {
+        const entries = decodeBindings(raw);
+        if (id === undefined)
+            delete entries[server];
+        else
+            entries[server] = id;
+        return { result: undefined, next: `${JSON.stringify(entries)}\n` };
+    }, { create: false });
+}
+export function mcpContext(dir, options = {}) {
+    const agentDir = resolve(dir);
+    const environment = { ...process.env, ...agentValues(agentDir) };
+    const stateRoot = resolveStateRoot(agentDir, environment);
+    return {
+        agentDir,
+        environment,
+        stateRoot,
+        auth: mcpAuthorization(agentDir, environment, stateRoot, options),
+    };
+}
+export function httpServer(servers, name) {
+    const server = servers.find((s) => s.name === name);
+    if (server?.type !== "http")
+        throw new McpError("configuration", "OAuth needs a declared HTTP MCP server", name);
+    if (new Headers(server.headers).has("authorization"))
+        throw new McpError("configuration", "An MCP server cannot use a static Authorization header and an OAuth binding together", name);
+    return server;
+}
+export async function inspectMcp(dir, options = {}) {
+    const { agentDir, auth } = mcpContext(dir, options);
+    return Promise.all(declareMcp(agentDir, mcpInstance(options.config)).map(async ({ name, server: declaration }) => {
+        const server = { ...declaration, name, type: declaration.type ?? "stdio" };
+        const id = Object.hasOwn(auth.bindings, server.name) ? auth.bindings[server.name] : undefined;
+        const raw = id === undefined ? undefined : await auth.store.read(id);
+        const grant = raw === undefined ? undefined : checkedGrant(raw);
+        let authorization = "not_bound";
+        if (declaration.type !== "http")
+            authorization = id === undefined ? "not_required" : "binding_mismatch";
+        else if (grant) {
+            authorization =
+                grant.serverUrl !== checkMcpUrl(declaration.url).href || new Headers(declaration.headers).has("authorization")
+                    ? "binding_mismatch"
+                    : grant.status !== "ready"
+                        ? "reauthorization_required"
+                        : grant.expiresAt !== undefined && grant.expiresAt <= Date.now() + 30_000
+                            ? grant.refreshToken
+                                ? "refresh_needed"
+                                : "reauthorization_required"
+                            : "ready";
+        }
+        else if (id !== undefined)
+            authorization = "reauthorization_required";
+        else if (declaration.type === "http" && new Headers(declaration.headers).has("authorization"))
+            authorization = "not_required";
+        return {
+            name: server.name,
+            transport: server.type,
+            ...(declaration.type === "http" ? { url: checkMcpUrl(declaration.url).href } : {}),
+            authorization,
+            ...(id === undefined ? {} : { grantId: id }),
+        };
+    }));
+}

package/dist/mcp/network.d.ts

@@ -0,0 +1,12 @@
+export declare function checkMcpTarget(serverUrl: string, value: string): URL;
+export declare function mcpFetch(serverUrl: string, fetchImpl: typeof globalThis.fetch, timeoutMs?: number): typeof globalThis.fetch;
+type Lookup = (host: string) => Promise<readonly {
+    address: string;
+    family: number;
+}[]>;
+export interface McpNetwork {
+    fetch: typeof globalThis.fetch;
+    close(): Promise<void>;
+}
+export declare function openMcpNetwork(serverUrl: string, customFetch?: typeof globalThis.fetch, resolve?: Lookup): Promise<McpNetwork>;
+export {};

package/dist/mcp/network.js

@@ -0,0 +1,150 @@
+/** MCP-derived URLs stay public unless they address the explicitly declared local endpoint. */
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import { port, portError } from "../effect-port.js";
+import { McpError } from "../mcp-api.js";
+import { checkMcpUrl } from "./config.js";
+const blocked = new BlockList();
+for (const [address, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.88.99.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+])
+    blocked.addSubnet(address, prefix, "ipv4");
+blocked.addAddress("168.63.129.16", "ipv4");
+for (const [address, prefix] of [
+    ["2001::", 23],
+    ["2001:db8::", 32],
+    ["2002::", 16],
+    ["3fff::", 20],
+])
+    blocked.addSubnet(address, prefix, "ipv6");
+const globalV6 = new BlockList();
+globalV6.addSubnet("2000::", 3, "ipv6");
+const mappedV4 = new BlockList();
+mappedV4.addSubnet("0.0.0.0", 0, "ipv4");
+const loopback = new BlockList();
+loopback.addSubnet("127.0.0.0", 8, "ipv4");
+loopback.addAddress("::1", "ipv6");
+const hostname = (url) => url.hostname.replace(/^\[|\]$/g, "");
+const localName = (name) => /(^|\.)localhost\.?$/i.test(name);
+function allowedAddress(declared, target, address) {
+    const version = isIP(address);
+    if (!version)
+        return false;
+    const family = version === 4 ? "ipv4" : "ipv6";
+    if (declared.origin === target.origin &&
+        (hostname(declared) === address || (localName(hostname(declared)) && loopback.check(address, family))))
+        return true;
+    return (!blocked.check(address, family) &&
+        (version === 4 || mappedV4.check(address, family) || globalV6.check(address, family)));
+}
+function denied() {
+    throw new McpError("authorization_mismatch", "MCP network policy refused an undeclared non-public destination");
+}
+export function checkMcpTarget(serverUrl, value) {
+    const declared = checkMcpUrl(serverUrl);
+    const target = checkMcpUrl(value);
+    const host = hostname(target);
+    if (isIP(host) ? !allowedAddress(declared, target, host) : localName(host) && target.origin !== declared.origin)
+        denied();
+    return target;
+}
+export function mcpFetch(serverUrl, fetchImpl, timeoutMs = 30_000) {
+    return (input, init) => {
+        checkMcpTarget(serverUrl, input instanceof Request ? input.url : String(input));
+        const signal = init?.signal ?? (input instanceof Request ? input.signal : undefined);
+        return fetchImpl(input, {
+            ...init,
+            redirect: "error",
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs),
+        });
+    };
+}
+export async function openMcpNetwork(serverUrl, customFetch, resolve = (host) => lookup(host, { all: true, order: "ipv4first" })) {
+    if (customFetch)
+        return { fetch: mcpFetch(serverUrl, customFetch, 60_000), close: async () => { } };
+    // Bun's bare undici shim ignores dispatcher factories; load the installed implementation on both runtimes.
+    const { EnvHttpProxyAgent, Pool, fetch } = await import("undici/index.js");
+    const { noProxyList } = await import("../proxy.js");
+    const declared = checkMcpUrl(serverUrl);
+    const pins = new Map();
+    let closed = false;
+    const dispatcher = new EnvHttpProxyAgent({
+        noProxy: noProxyList(),
+        proxyTunnel: true,
+        factory: (origin, options) => {
+            const authority = new URL(origin);
+            const target = pins.get(authority.origin);
+            if (!target)
+                return denied();
+            // fetch removes Host; restore the original authority only after it selects this pinned pool.
+            return new Pool(target, options).compose((dispatch) => (request, handler) => dispatch({
+                ...request,
+                headers: Array.isArray(request.headers)
+                    ? ["host", authority.host, ...request.headers]
+                    : { ...request.headers, host: authority.host },
+            }, handler));
+        },
+    });
+    const request = async (input, init) => {
+        if (closed)
+            throw new McpError("connection", "MCP network is closed");
+        const request = new Request(input, init);
+        const url = checkMcpTarget(serverUrl, request.url);
+        if (!pins.has(url.origin)) {
+            const resolved = await Effect.runPromiseExit(port(async () => {
+                const host = hostname(url);
+                const addresses = isIP(host) ? [{ address: host, family: isIP(host) }] : await resolve(host);
+                const first = addresses[0];
+                if (!first || addresses.some(({ address }) => !allowedAddress(declared, url, address)))
+                    return denied();
+                const pinned = new URL(url.origin);
+                const address = first.address;
+                pinned.hostname = isIP(address) === 6 ? `[${address}]` : address;
+                return pinned;
+            }), { signal: request.signal });
+            if (Exit.isFailure(resolved)) {
+                request.signal.throwIfAborted();
+                throw portError(resolved.cause);
+            }
+            pins.set(url.origin, resolved.value);
+        }
+        request.signal.throwIfAborted();
+        if (closed)
+            throw new McpError("connection", "MCP network is closed");
+        const headers = new Headers(request.headers);
+        if (headers.has("host") && headers.get("host") !== url.host)
+            throw new McpError("configuration", "MCP Host header must match the declared URL");
+        return (await fetch(request.url, {
+            dispatcher,
+            method: request.method,
+            headers: [...headers],
+            signal: request.signal,
+            body: request.body,
+            duplex: "half",
+            redirect: "error",
+        }));
+    };
+    return {
+        fetch: mcpFetch(serverUrl, request, 60_000),
+        close: async () => {
+            closed = true;
+            await dispatcher.destroy();
+        },
+    };
+}

package/dist/mcp/sign-in.d.ts

@@ -0,0 +1,2 @@
+import { type McpGrantSummary, type McpSignInRequest } from "../mcp-api.ts";
+export declare function signInMcp(request: McpSignInRequest): Promise<McpGrantSummary>;