@fungi.computer/veil 0.0.0-stage → 0.0.1

package/dist/public-fetch.js

@@ -0,0 +1,347 @@
+export { validatePublicEgressPolicyEntries } from "./public-egress-policy.js";
+import { createPublicEgressPolicy, } from "./public-egress-policy.js";
+export { createPublicEgressPolicy, } from "./public-egress-policy.js";
+import { Buffer } from "node:buffer";
+import { HTTPParser } from "http-parser-js";
+import { VeilError } from "./index.js";
+import { bestEffortCleanup } from "./best-effort-cleanup.js";
+import { createDnsOverHttpsResolver, resolvePublicAddresses, } from "./model-key-network.js";
+export class PublicFetchError extends VeilError {
+    stage;
+    constructor(code, stage) {
+        super(code);
+        this.stage = stage;
+        this.name = "PublicFetchError";
+    }
+}
+/** Response status line and headers must fit here before the body starts. */
+const MAX_HEADER_BYTES = 64 * 1024;
+const HEADER_SLICE_BYTES = 4 * 1024;
+/** Checked addresses tried in order when a connection cannot be opened. */
+const MAX_ADDRESSES = 4;
+const encoder = new TextEncoder();
+function destination(url) {
+    if (url.protocol !== "https:" && url.protocol !== "http:")
+        throw new PublicFetchError("denied", "address");
+    if (url.username !== "" || url.password !== "")
+        throw new PublicFetchError("denied", "address");
+    const secure = url.protocol === "https:";
+    return {
+        secure,
+        hostname: url.hostname,
+        port: url.port === "" ? (secure ? 443 : 80) : Number(url.port),
+    };
+}
+function headerValue(value) {
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        if (code < 0x20 || code === 0x7f)
+            throw new PublicFetchError("invalid_input", "address");
+    }
+    return value;
+}
+function requestBytes(request) {
+    const { url } = request;
+    // The URL parser percent-encodes the path and query, so neither can carry a
+    // line break; `host` is the URL's own authority.
+    const head = encoder.encode([
+        `${request.method} ${url.pathname}${url.search} HTTP/1.1`,
+        `Host: ${url.host}`,
+        ...Array.from(request.headers, ([name, value]) => `${name}: ${headerValue(value)}`),
+        "Accept-Encoding: identity",
+        "Connection: close",
+        ...(request.body.byteLength > 0 ||
+            !["GET", "HEAD"].includes(request.method)
+            ? [`Content-Length: ${String(request.body.byteLength)}`]
+            : []),
+        "",
+        "",
+    ].join("\r\n"));
+    if (head.byteLength > MAX_HEADER_BYTES)
+        throw new PublicFetchError("invalid_input", "address");
+    const bytes = new Uint8Array(head.byteLength + request.body.byteLength);
+    bytes.set(head);
+    bytes.set(request.body, head.byteLength);
+    return bytes;
+}
+/** Wait for the socket to open, giving up when the call is cancelled. */
+async function opened(socket, signal) {
+    let onAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        onAbort = () => {
+            reject(new PublicFetchError("cancelled", "connect"));
+        };
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    });
+    try {
+        await Promise.race([socket.opened, aborted]);
+    }
+    finally {
+        if (onAbort !== undefined)
+            signal.removeEventListener("abort", onAbort);
+    }
+}
+/** Open a connection to the first checked address that accepts one. */
+async function connectChecked(connect, addresses, to, signal) {
+    for (const hostname of addresses.slice(0, MAX_ADDRESSES)) {
+        let socket;
+        try {
+            signal.throwIfAborted();
+            socket = connect({ hostname, port: to.port }, {
+                secureTransport: to.secure ? "starttls" : "off",
+                allowHalfOpen: false,
+            });
+            await opened(socket, signal);
+            return to.secure
+                ? socket.startTls({
+                    expectedServerHostname: to.hostname.replace(/^\[|\]$/gu, ""),
+                })
+                : socket;
+        }
+        catch {
+            await bestEffortCleanup("public-fetch-socket", () => socket?.close() ?? Promise.resolve());
+            if (signal.aborted)
+                throw new PublicFetchError("cancelled", "connect");
+        }
+    }
+    throw new PublicFetchError("unavailable", "connect");
+}
+const bodylessStatuses = new Set([204, 205, 304]);
+/** Headers describing wire framing, which the parsed Response no longer has. */
+const framingHeaders = new Set([
+    "transfer-encoding",
+    "connection",
+    "keep-alive",
+]);
+function refusedResponse() {
+    return new PublicFetchError("invalid_response", "response");
+}
+function decodeHead(info) {
+    if (info.upgrade || info.statusCode < 200)
+        throw refusedResponse();
+    const headers = new Headers();
+    let transferEncodings = 0;
+    for (let index = 0; index + 1 < info.headers.length; index += 2) {
+        const name = (info.headers[index] ?? "").toLowerCase();
+        const value = info.headers[index + 1] ?? "";
+        if (name === "transfer-encoding") {
+            // The parser frames only a bare `chunked`; anything layered is unreadable.
+            transferEncodings += 1;
+            if (transferEncodings > 1 || value.toLowerCase() !== "chunked")
+                throw refusedResponse();
+        }
+        if (name === "content-length" && !/^[0-9]{1,15}$/u.test(value))
+            throw refusedResponse();
+        // Compressed bodies are never requested; an unrequested one is not text.
+        if (name === "content-encoding" &&
+            value.trim() !== "" &&
+            value.trim().toLowerCase() !== "identity")
+            throw refusedResponse();
+        if (framingHeaders.has(name))
+            continue;
+        try {
+            headers.append(name, value);
+        }
+        catch {
+            throw refusedResponse();
+        }
+    }
+    return { status: info.statusCode, headers };
+}
+/**
+ * Write the request and read one HTTP/1.1 response from `socket`. The
+ * maintained parser frames it (status line, headers, content-length, chunked,
+ * read-to-close). The body stays a pull stream, so a reader that cancels
+ * closes the socket and cancelling `signal` closes it too.
+ */
+async function exchange(socket, request) {
+    const { signal } = request;
+    const reader = socket.readable.getReader();
+    const parser = new HTTPParser(HTTPParser.RESPONSE);
+    parser.maxHeaderSize = MAX_HEADER_BYTES;
+    const pending = [];
+    let head;
+    const state = { complete: false };
+    const finished = () => state.complete;
+    let disposed = false;
+    const dispose = async () => {
+        if (disposed)
+            return;
+        disposed = true;
+        signal.removeEventListener("abort", onAbort);
+        await Promise.allSettled([reader.cancel(), socket.close()]);
+    };
+    function onAbort() {
+        void dispose();
+    }
+    signal.addEventListener("abort", onAbort, { once: true });
+    // One request per connection: once the first response is complete, whatever
+    // else the peer sends is not part of it.
+    parser[HTTPParser.kOnHeadersComplete] = (info) => {
+        if (state.complete)
+            return 1;
+        head = decodeHead(info);
+        return bodylessStatuses.has(info.statusCode) || request.method === "HEAD"
+            ? 1
+            : undefined;
+    };
+    parser[HTTPParser.kOnBody] = (chunk, offset, length) => {
+        if (!state.complete && length > 0)
+            pending.push(Uint8Array.from(chunk.subarray(offset, offset + length)));
+    };
+    parser[HTTPParser.kOnMessageComplete] = () => {
+        state.complete = true;
+    };
+    /** Read one socket chunk into the parser; false once the peer has closed. */
+    const advance = async () => {
+        let next;
+        try {
+            next = await reader.read();
+        }
+        catch {
+            throw new PublicFetchError(signal.aborted ? "cancelled" : "unavailable", "response");
+        }
+        if (next.done) {
+            if (parser.finish() instanceof Error && !state.complete)
+                throw refusedResponse();
+            return false;
+        }
+        const { buffer, byteOffset, byteLength } = next.value;
+        // The parser measures its header cap after each call, so feed small slices
+        // until the head is read; a body may then arrive whole.
+        for (let start = 0; start < byteLength;) {
+            const end = head === undefined
+                ? Math.min(start + HEADER_SLICE_BYTES, byteLength)
+                : byteLength;
+            const parsed = parser.execute(Buffer.from(buffer, byteOffset + start, end - start));
+            if (parsed instanceof Error && !state.complete)
+                throw refusedResponse();
+            start = end;
+        }
+        return true;
+    };
+    try {
+        try {
+            const writer = socket.writable.getWriter();
+            await writer.write(requestBytes(request));
+            writer.releaseLock();
+        }
+        catch {
+            throw new PublicFetchError(signal.aborted ? "cancelled" : "unavailable", "connect");
+        }
+        while (head === undefined) {
+            if (!(await advance()))
+                throw refusedResponse();
+        }
+    }
+    catch (error) {
+        await dispose();
+        throw error;
+    }
+    const { status, headers } = head;
+    if (bodylessStatuses.has(status) || request.method === "HEAD") {
+        await dispose();
+        return new Response(null, { status, headers });
+    }
+    const body = new ReadableStream({
+        pull: async (controller) => {
+            try {
+                for (;;) {
+                    const chunk = pending.shift();
+                    if (chunk !== undefined) {
+                        controller.enqueue(chunk);
+                        return;
+                    }
+                    if (state.complete) {
+                        await dispose();
+                        controller.close();
+                        return;
+                    }
+                    const more = await advance();
+                    // `advance` may have completed the response, even at end of stream.
+                    if (!more && !finished())
+                        throw refusedResponse();
+                }
+            }
+            catch (error) {
+                await dispose();
+                throw error;
+            }
+        },
+        cancel: dispose,
+    });
+    try {
+        return new Response(body, { status, headers });
+    }
+    catch {
+        await dispose();
+        throw refusedResponse();
+    }
+}
+export function createPublicHttp(options) {
+    const policy = createPublicEgressPolicy(options.networkPolicy);
+    return {
+        send: async (request) => {
+            const to = destination(request.url);
+            let addresses;
+            try {
+                policy.destination(request.url);
+                addresses = await resolvePublicAddresses(to.hostname, options.resolve, request.signal);
+                policy.addresses(addresses);
+            }
+            catch (error) {
+                if (error instanceof VeilError && error.code === "denied")
+                    throw new PublicFetchError("denied", "address");
+                throw new PublicFetchError(request.signal.aborted ? "cancelled" : "unavailable", "dns");
+            }
+            const socket = await connectChecked(options.connect, addresses, to, request.signal);
+            return await exchange(socket, request);
+        },
+    };
+}
+/** Anonymous GET keeps its existing two-header authority. */
+export function createPublicFetch(options) {
+    const http = createPublicHttp({
+        ...options,
+        networkPolicy: {
+            ...options.networkPolicy,
+            // The anonymous public-web contract includes ordinary HTTP. Extra ports remain host-only.
+            extraPorts: [80, ...(options.networkPolicy?.extraPorts ?? [])],
+        },
+    });
+    return {
+        get: async (request) => {
+            let headers;
+            try {
+                headers = new Headers({
+                    Accept: request.accept,
+                    "User-Agent": request.userAgent,
+                });
+            }
+            catch {
+                throw new PublicFetchError("invalid_input", "address");
+            }
+            return http.send({
+                url: request.url,
+                method: "GET",
+                headers,
+                body: new Uint8Array(),
+                signal: request.signal,
+            });
+        },
+    };
+}
+/**
+ * The production door: the host's socket primitive plus its `fetch`, used only
+ * for the DNS-over-HTTPS lookup of the one resolution each call makes.
+ */
+export function configuredPublicFetch(options) {
+    return createPublicFetch({
+        connect: options.connect,
+        resolve: createDnsOverHttpsResolver(options.fetch),
+        networkPolicy: options.networkPolicy ?? {},
+    });
+}

package/dist/webhook-trigger-secrets.d.ts

@@ -0,0 +1,23 @@
+import { type EventRequest, type EventVerification, type EventVerifier } from "./event-verifiers.js";
+/**
+ * One event binding's secret. Rotating bumps `secretGeneration`, which derives
+ * a new, unrelated secret; the previous one stops verifying.
+ */
+export type EventBindingAddress = Readonly<{
+    teamId: string;
+    bindingId: string;
+    secretGeneration: number;
+}>;
+/** A Worker-secret-backed custodian. Per-binding bytes are derived on demand and never enter TeamDO. */
+export declare function createWebhookTriggerSecrets(masterSecret: string): {
+    /** Show this only on create or rotate. It is never part of a projection. */
+    reveal: (input: EventBindingAddress) => Promise<string>;
+    /**
+     * Verify one inbound request against the binding's current generation. A
+     * signature or token made under any earlier generation is `bad_signature`.
+     */
+    verify(input: EventRequest & Readonly<{
+        verifier: EventVerifier;
+        address: EventBindingAddress;
+    }>): Promise<EventVerification>;
+};

package/dist/webhook-trigger-secrets.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { verifyFungiV1, verifyGithub, verifySecretUrl, verifyStandardWebhooks, } from "./event-verifiers.js";
+const secretSchema = z.string().regex(/^[A-Za-z0-9_-]{43}$/u);
+const addressSchema = z.object({
+    teamId: z.string().min(1),
+    bindingId: z.string().min(1),
+    secretGeneration: z.number().int().nonnegative(),
+});
+/** A Worker-secret-backed custodian. Per-binding bytes are derived on demand and never enter TeamDO. */
+export function createWebhookTriggerSecrets(masterSecret) {
+    const decoded = secretSchema.safeParse(masterSecret);
+    // Never echo the master secret, even through a parse error.
+    if (!decoded.success)
+        throw new Error("Invalid webhook custody key");
+    const masterBytes = Uint8Array.from(Buffer.from(decoded.data, "base64url"));
+    if (masterBytes.length !== 32)
+        throw new Error("Invalid webhook custody key");
+    const master = crypto.subtle.importKey("raw", masterBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const reveal = async (input) => {
+        const address = addressSchema.safeParse(input);
+        if (!address.success)
+            throw new Error("Invalid event binding address");
+        const key = await master;
+        const bytes = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(JSON.stringify([
+            "fungi-event-binding-v1",
+            address.data.teamId,
+            address.data.bindingId,
+            address.data.secretGeneration,
+        ]))));
+        return Buffer.from(bytes).toString("base64url");
+    };
+    return {
+        /** Show this only on create or rotate. It is never part of a projection. */
+        reveal,
+        /**
+         * Verify one inbound request against the binding's current generation. A
+         * signature or token made under any earlier generation is `bad_signature`.
+         */
+        async verify(input) {
+            const current = await reveal(input.address);
+            switch (input.verifier) {
+                case "fungi-v1":
+                    return verifyFungiV1(current, input);
+                case "github":
+                    return verifyGithub(current, input);
+                case "secret-url":
+                    return verifySecretUrl(current, input);
+                case "standard-webhooks":
+                    return verifyStandardWebhooks(current, input);
+            }
+        },
+    };
+}

package/dist/world-seat.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Write-only custody for the credential a Team gives one Agent's Vishnu world
+ * seat. The token enters once through `seal`; nothing returns it. `send`
+ * attaches it at final egress, so the Team, the Agent and every projection
+ * hold only the private locator and the public endpoint.
+ */
+export type WorldSeatAccess = Readonly<{
+    /** Private custody id chosen by the Team owner; never a public field. */
+    locator: string;
+    /** The seat's MCP endpoint, already accepted by `worldSeatEndpoint`. */
+    endpoint: string;
+}>;
+export type WorldSeatCustodian = Readonly<{
+    seal: (input: Readonly<{
+        teamId: string;
+        locator: string;
+        endpoint: string;
+        token: string;
+    }>, signal: AbortSignal) => Promise<void>;
+    send: (access: WorldSeatAccess, request: Request) => Promise<Response>;
+    remove: (access: Pick<WorldSeatAccess, "locator">, signal: AbortSignal) => Promise<"deleted" | "absent">;
+}>;
+/** Longest token a seat may seal; the connection input schema bounds it too. */
+export declare const WORLD_SEAT_TOKEN_MAX = 512;
+/**
+ * The one MCP endpoint a seat may name: HTTPS on a public host, no
+ * credentials, query or fragment, path exactly `/mcp`. Custody fetches it from
+ * inside Fungi's own network, so a private name would be an SSRF reach.
+ *
+ * `allowLocalDev` is the host's explicit local/dev configuration, never
+ * inferred from the URL: it additionally admits plain HTTP (or HTTPS) to a
+ * loopback host so a developer's machine can serve the world.
+ */
+export declare function worldSeatEndpoint(text: string, options?: Readonly<{
+    allowLocalDev?: boolean;
+}>): string;
+/** The seat's endpoint and nothing else; the caller names no other target. */
+export declare function worldSeatTarget(access: WorldSeatAccess, request: Request): URL;
+/** Copy only MCP-meaningful headers; the caller's authorization is dropped. */
+export declare function worldSeatForwardedHeaders(request: Request): Headers;

package/dist/world-seat.js

@@ -0,0 +1,82 @@
+import { VeilError } from "./index.js";
+import { assertPublicHostName } from "./model-key-network.js";
+/** Longest token a seat may seal; the connection input schema bounds it too. */
+export const WORLD_SEAT_TOKEN_MAX = 512;
+/**
+ * The one MCP endpoint a seat may name: HTTPS on a public host, no
+ * credentials, query or fragment, path exactly `/mcp`. Custody fetches it from
+ * inside Fungi's own network, so a private name would be an SSRF reach.
+ *
+ * `allowLocalDev` is the host's explicit local/dev configuration, never
+ * inferred from the URL: it additionally admits plain HTTP (or HTTPS) to a
+ * loopback host so a developer's machine can serve the world.
+ */
+export function worldSeatEndpoint(text, options = {}) {
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw new VeilError("invalid_input");
+    }
+    if (url.username || url.password || url.search || url.hash)
+        throw new VeilError("invalid_input");
+    if (url.pathname !== "/mcp")
+        throw new VeilError("invalid_input");
+    if (options.allowLocalDev === true && isLoopbackHost(url.hostname)) {
+        if (url.protocol !== "http:" && url.protocol !== "https:")
+            throw new VeilError("invalid_input");
+        return url.href;
+    }
+    if (url.protocol !== "https:")
+        throw new VeilError("invalid_input");
+    try {
+        assertPublicHostName(url.hostname);
+    }
+    catch {
+        throw new VeilError("invalid_input");
+    }
+    return url.href;
+}
+function isLoopbackHost(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "[::1]" ||
+        /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/u.test(hostname));
+}
+const forwardedHeaders = [
+    "accept",
+    "content-type",
+    "mcp-protocol-version",
+    "mcp-session-id",
+    "last-event-id",
+];
+/** Streamable HTTP uses exactly these three verbs; any other is refused. */
+const worldSeatMethods = new Set([
+    "GET",
+    "POST",
+    "DELETE",
+]);
+/** The seat's endpoint and nothing else; the caller names no other target. */
+export function worldSeatTarget(access, request) {
+    let target;
+    try {
+        target = new URL(request.url);
+    }
+    catch {
+        throw new VeilError("denied");
+    }
+    if (target.href !== new URL(access.endpoint).href ||
+        !worldSeatMethods.has(request.method))
+        throw new VeilError("denied");
+    return target;
+}
+/** Copy only MCP-meaningful headers; the caller's authorization is dropped. */
+export function worldSeatForwardedHeaders(request) {
+    const headers = new Headers();
+    for (const name of forwardedHeaders) {
+        const value = request.headers.get(name);
+        if (value !== null)
+            headers.set(name, value);
+    }
+    return headers;
+}