@fastagent-sh/fastagent 0.28.0 → 0.29.0

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>;

package/dist/mcp/sign-in.js

@@ -0,0 +1,204 @@
+/** Explicit browser OAuth for MCP; no auth URL, code or token passes through a model turn. */
+import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import { resolve } from "node:path";
+import { agentValues } from "../value-file.js";
+import { resolveMcpServers } from "./config.js";
+import { registerClient, startAuthorization, exchangeAuthorization, selectClientAuthMethod, validateAuthorizationResponseIssuer, } from "@modelcontextprotocol/client";
+import * as Effect from "effect/Effect";
+import * as Deferred from "effect/Deferred";
+import * as Exit from "effect/Exit";
+import { port, portJoin, portCleanup, portError } from "../effect-port.js";
+import { McpError } from "../mcp-api.js";
+import { sendPage, setupRequestUrl, statusCard } from "../setup-page.js";
+import { discoverMcp, mcpFailure } from "./auth.js";
+import { mcpFetch, openMcpNetwork } from "./network.js";
+import { httpServer } from "./host.js";
+import { grantSummary } from "./grants.js";
+export async function signInMcp(request) {
+    const timeout = request.timeoutSeconds ?? 900;
+    if (!Number.isInteger(timeout) ||
+        timeout <= 0 ||
+        (request.callbackPort !== undefined &&
+            (!Number.isInteger(request.callbackPort) || request.callbackPort < 0 || request.callbackPort > 65535))) {
+        throw new McpError("configuration", "Invalid MCP sign-in timeout or callback port", request.server);
+    }
+    const dir = resolve(request.agentDir);
+    const server = httpServer(resolveMcpServers(dir, { ...process.env, ...agentValues(dir), ...request.variables }, request.server), request.server);
+    let saved;
+    const work = Effect.gen(function* () {
+        const network = yield* Effect.acquireRelease(port(() => openMcpNetwork(server.url, request.fetch)), (value) => portCleanup("MCP network", () => value.close()));
+        const fetchImpl = mcpFetch(server.url, network.fetch);
+        const discovery = yield* port(() => discoverMcp(server.url, fetchImpl));
+        if (!discovery.metadata.code_challenge_methods_supported?.includes("S256")) {
+            return yield* Effect.fail(new McpError("protocol", "MCP authorization server does not advertise PKCE S256", server.name));
+        }
+        if (!request.clientId && !discovery.metadata.registration_endpoint)
+            return yield* Effect.fail(new McpError("configuration", "This MCP service requires a public clientId or client metadata URL; dynamic registration is unavailable", server.name));
+        const scopes = [...new Set(request.scopes ?? discovery.resourceMetadata.scopes_supported ?? [])];
+        if (scopes.some((scope) => !/^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)))
+            return yield* Effect.fail(new McpError("configuration", "Invalid OAuth scope", server.name));
+        const approved = yield* port(() => request.interaction.confirmAuthorization({
+            server: server.name,
+            resource: discovery.resource,
+            issuer: discovery.issuer,
+            scopes,
+        }));
+        if (!approved)
+            return yield* Effect.fail(new McpError("canceled", "MCP authorization canceled", server.name));
+        const callback = yield* Deferred.make();
+        const state = randomBytes(32).toString("base64url");
+        const path = request.clientId ? "/mcp/oauth/callback" : `/mcp/oauth/${randomBytes(24).toString("hex")}`;
+        let portNumber = 0;
+        let consumed = false;
+        const listener = createServer((incoming, response) => {
+            // This one-shot listener closes after sign-in; a later flow may bind the same callback port.
+            response.setHeader("connection", "close");
+            const url = setupRequestUrl(incoming, response);
+            if (!url)
+                return;
+            if (incoming.headers.host !== `127.0.0.1:${portNumber}` ||
+                incoming.method !== "GET" ||
+                url.pathname !== path ||
+                consumed) {
+                response.writeHead(404).end("not found\n");
+                return;
+            }
+            const received = url.searchParams.get("state") ?? "";
+            if (Buffer.byteLength(received) !== Buffer.byteLength(state) ||
+                !timingSafeEqual(Buffer.from(received), Buffer.from(state))) {
+                response.writeHead(400).end("invalid OAuth state\n");
+                return;
+            }
+            let problem;
+            try {
+                validateAuthorizationResponseIssuer({
+                    iss: url.searchParams.get("iss") ?? undefined,
+                    expectedIssuer: discovery.issuer,
+                    issParameterSupported: discovery.metadata.authorization_response_iss_parameter_supported === true,
+                });
+                if (url.searchParams.has("error"))
+                    problem = new McpError("canceled", "MCP authorization was not approved", server.name);
+                else if (!url.searchParams.get("code"))
+                    problem = new McpError("protocol", "MCP callback contained no authorization code", server.name);
+            }
+            catch {
+                problem = new McpError("authorization_mismatch", "MCP OAuth callback issuer mismatch", server.name);
+            }
+            consumed = true;
+            const completed = problem ? Deferred.fail(callback, problem) : Deferred.succeed(callback, url.searchParams);
+            // Closing the scope tears down the listener; first flush the page or observe the browser disconnect.
+            if (response.destroyed)
+                Effect.runSync(completed);
+            else
+                response.once("close", () => Effect.runSync(completed));
+            sendPage(response, problem ? 400 : 200, {
+                title: "MCP authorization — FastAgent",
+                card: statusCard({
+                    state: problem ? "failed" : "working",
+                    heading: problem ? "Authorization stopped" : "Authorization response received",
+                    lede: problem?.message ?? "FastAgent is verifying and saving the authorization.",
+                    next: "Return to your application or coding agent. Do not copy this address.",
+                }),
+            });
+        });
+        yield* Effect.acquireRelease(Effect.succeed(listener), (value) => portCleanup("MCP OAuth callback", () => new Promise((resolve, reject) => {
+            value.close((error) => (error ? reject(error) : resolve()));
+            value.closeAllConnections();
+        })));
+        yield* portJoin(() => new Promise((resolve, reject) => {
+            listener.once("error", reject);
+            listener.listen(request.callbackPort ?? 0, "127.0.0.1", () => {
+                listener.off("error", reject);
+                resolve();
+            });
+        }));
+        const address = listener.address();
+        if (!address || typeof address === "string")
+            return yield* Effect.fail(new McpError("connection", "MCP callback has no local port", server.name));
+        portNumber = address.port;
+        const redirectUrl = `http://127.0.0.1:${portNumber}${path}`;
+        const registration = request.clientId
+            ? { client_id: request.clientId }
+            : yield* portJoin(() => registerClient(discovery.issuer, {
+                metadata: discovery.metadata,
+                clientMetadata: {
+                    client_name: "FastAgent",
+                    redirect_uris: [redirectUrl],
+                    grant_types: ["authorization_code", "refresh_token"],
+                    response_types: ["code"],
+                    token_endpoint_auth_method: "none",
+                    application_type: "native",
+                    scope: scopes.join(" "),
+                },
+                scope: scopes.join(" "),
+                fetchFn: fetchImpl,
+            }));
+        const { authorizationUrl, codeVerifier } = yield* portJoin(() => startAuthorization(discovery.issuer, {
+            metadata: discovery.metadata,
+            clientInformation: registration,
+            state,
+            redirectUrl,
+            scope: scopes.join(" "),
+            resource: discovery.resource,
+        }));
+        request.interaction.notify({ type: "auth_url", url: authorizationUrl.href });
+        const params = yield* Deferred.await(callback);
+        // Redeeming a code can consume it. Finish the bounded exchange and durable save even if its waiter cancels.
+        return yield* Effect.uninterruptible(Effect.gen(function* () {
+            request.interaction.notify({ type: "progress", message: "Saving MCP authorization" });
+            const tokens = yield* portJoin(() => exchangeAuthorization(discovery.issuer, {
+                metadata: discovery.metadata,
+                clientInformation: registration,
+                authorizationCode: params.get("code"),
+                codeVerifier,
+                redirectUri: redirectUrl,
+                iss: params.get("iss") ?? undefined,
+                resource: discovery.resource,
+                fetchFn: fetchImpl,
+            }));
+            const granted = tokens.scope === undefined ? scopes : tokens.scope.split(/\s+/).filter(Boolean);
+            if (tokens.token_type.toLowerCase() !== "bearer" || granted.some((scope) => !scopes.includes(scope)))
+                return yield* Effect.fail(new McpError("insufficient_scope", "MCP authorization returned an unsupported token type or unapproved scopes", server.name));
+            const method = selectClientAuthMethod(registration, discovery.metadata.token_endpoint_auth_methods_supported ?? []);
+            if (method !== "none" && method !== "client_secret_post" && method !== "client_secret_basic")
+                return yield* Effect.fail(new McpError("protocol", "Unsupported MCP client authentication method", server.name));
+            const record = {
+                version: 1,
+                serverUrl: server.url,
+                resource: discovery.resource,
+                issuer: discovery.issuer,
+                client: {
+                    id: registration.client_id,
+                    tokenEndpointAuthMethod: method,
+                    ...("client_secret" in registration && registration.client_secret
+                        ? { secret: registration.client_secret }
+                        : {}),
+                },
+                scopes: granted,
+                status: "ready",
+                generation: 0,
+                accessToken: tokens.access_token,
+                ...(tokens.refresh_token ? { refreshToken: tokens.refresh_token } : {}),
+                ...(tokens.expires_in === undefined ? {} : { expiresAt: Date.now() + tokens.expires_in * 1000 }),
+            };
+            const id = randomUUID();
+            yield* portJoin(() => request.store.withGrant(id, async (access) => {
+                if (access.read())
+                    throw new McpError("storage", "MCP grant ID collision");
+                await access.write(record);
+            }));
+            saved = grantSummary(id, record);
+            return saved;
+        }));
+    }).pipe(Effect.timeout(timeout * 1000), Effect.scoped);
+    const result = await Effect.runPromiseExit(work, { signal: request.interaction.signal });
+    if (saved)
+        return saved;
+    if (Exit.isFailure(result)) {
+        if (Exit.hasInterrupts(result) || request.interaction.signal?.aborted)
+            throw new McpError("canceled", "MCP sign-in canceled", request.server);
+        throw mcpFailure(portError(result.cause), "MCP sign-in", request.server);
+    }
+    return result.value;
+}

package/dist/mcp-api.d.ts

@@ -0,0 +1,93 @@
+/** MCP authorization as an embedding host sees it. No SDK or harness types cross this boundary. */
+export type McpErrorCode = "configuration" | "authorization_required" | "authorization_mismatch" | "insufficient_scope" | "refresh_uncertain" | "canceled" | "connection" | "protocol" | "storage";
+export declare class McpError extends Error {
+    readonly code: McpErrorCode;
+    readonly server?: string;
+    constructor(code: McpErrorCode, message: string, server?: string);
+}
+export interface McpGrantRecord {
+    version: 1;
+    serverUrl: string;
+    resource: string;
+    issuer: string;
+    client: {
+        id: string;
+        secret?: string;
+        tokenEndpointAuthMethod: "none" | "client_secret_post" | "client_secret_basic";
+    };
+    scopes: readonly string[];
+    status: "ready" | "refreshing" | "reauthorization_required";
+    generation: number;
+    accessToken: string;
+    refreshToken?: string;
+    expiresAt?: number;
+}
+export interface McpGrantSummary {
+    id: string;
+    serverUrl: string;
+    resource: string;
+    issuer: string;
+    scopes: readonly string[];
+    status: McpGrantRecord["status"];
+    expiresAt?: number;
+}
+export interface McpGrantAccess {
+    read(): McpGrantRecord | undefined;
+    write(record: McpGrantRecord): Promise<void>;
+    remove(): Promise<void>;
+}
+export interface McpGrantStore {
+    read(grantId: string): Promise<McpGrantRecord | undefined>;
+    list(): Promise<readonly McpGrantSummary[]>;
+    /** Exclusive across all callers sharing storage. Each write is durable immediately, even if operation later throws. */
+    withGrant<T>(grantId: string, operation: (grant: McpGrantAccess) => Promise<T>): Promise<T>;
+}
+export interface McpAuthorization {
+    store: McpGrantStore;
+    bindings: Readonly<Record<string, string>>;
+}
+export interface McpOptions {
+    store?: McpGrantStore;
+    bindings?: Readonly<Record<string, string>>;
+    /** Per-instance interpolation values; never copied into process.env. */
+    variables?: Readonly<Record<string, string>>;
+    /** Trusted transport override: the host must enforce connection-level DNS/IP and redirect safety itself. */
+    fetch?: typeof globalThis.fetch;
+}
+export interface McpServerSummary {
+    name: string;
+    transport: "stdio" | "http";
+    url?: string;
+    authorization: "not_required" | "not_bound" | "ready" | "refresh_needed" | "reauthorization_required" | "binding_mismatch";
+    grantId?: string;
+}
+export interface McpSignInInteraction {
+    signal?: AbortSignal;
+    confirmAuthorization(request: {
+        server: string;
+        resource: string;
+        issuer: string;
+        scopes: readonly string[];
+    }): Promise<boolean>;
+    notify(event: {
+        type: "auth_url";
+        url: string;
+    } | {
+        type: "progress";
+        message: string;
+    }): void;
+}
+export interface McpSignInRequest {
+    agentDir: string;
+    server: string;
+    store: McpGrantStore;
+    interaction: McpSignInInteraction;
+    scopes?: readonly string[];
+    /** Non-secret registration choices for servers that require a pre-registered public client. */
+    clientId?: string;
+    /** With clientId, register http://127.0.0.1:<port>/mcp/oauth/callback. */
+    callbackPort?: number;
+    timeoutSeconds?: number;
+    variables?: Readonly<Record<string, string>>;
+    fetch?: McpOptions["fetch"];
+}

package/dist/mcp-api.js

@@ -0,0 +1,10 @@
+export class McpError extends Error {
+    code;
+    server;
+    constructor(code, message, server) {
+        super(server ? `${server}: ${message}` : message);
+        this.name = "McpError";
+        this.code = code;
+        this.server = server;
+    }
+}

package/dist/setup-page.d.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+export declare function setupRequestUrl(request: IncomingMessage, response: ServerResponse): URL | undefined;
+/** `1  Title`: the number and the title on one line, so the step's content below shares the card's one left edge. */
+export declare function step(number: number, title: string, content: string, options?: {
+    bare?: boolean;
+}): string;
+/** A sentence under a step's title. `html` is trusted markup: use `<b>` for a name the person must find on another site. */
+export declare const prose: (html: string) => string;
+/** A button that opens another site in a new tab (secondary: the step's real action is the primary button below). */
+export declare function openButton(label: string, href: string): string;
+/**
+ * A labelled input. `label` is the name the other site gives the value, so the person never has to map one to the other.
+ * A secret gets a Show/Hide toggle; nothing is ever put back in a secret field after a refusal.
+ */
+export declare function field(input: {
+    id: string;
+    label: string;
+    placeholder?: string;
+    secret?: boolean;
+    value?: string;
+    invalid?: boolean;
+    autofocus?: boolean;
+}): string;
+/**
+ * What was refused, in bold, and what to do about it. Sits above the field it is about. `why` is the other side's own
+ * words, for someone who has to look it up: small and set apart, so the sentence the person reads stays one they can act on.
+ */
+export declare function refusal(headline: string, detail?: string, why?: string): string;
+export declare const submit: (label: string) => string;
+/** The promise about where a pasted value goes. Said once, the same way, on every page that asks for one. */
+export declare const privacy: () => string;
+/** A page that asks for something: a heading, then the steps, in one form posting back to this address. */
+export declare function formCard(heading: string, steps: string): string;
+/** A page that says where things stand: working (it moves on by itself), done, or stopped. */
+export declare function statusCard(input: {
+    state: "working" | "done" | "failed";
+    heading: string;
+    lede?: string;
+    /** What the person does now, set apart under the status. */
+    next?: string;
+}): string;
+/**
+ * Send a page. The headers are those of a page that takes a secret: nothing cached, nothing framed, nothing loaded from
+ * elsewhere (a nonce admits only this page's own style and script). No `form-action`: browsers apply it to the redirects a
+ * submission is answered with, and Slack's page answers one by sending the browser on to Slack.
+ */
+export declare function sendPage(response: ServerResponse, status: number, page: {
+    title: string;
+    card: string;
+    head?: string;
+}): void;