@fungi.computer/veil 0.0.0-stage → 0.1.0

package/dist/provider-egress.js

@@ -0,0 +1,155 @@
+import { VeilError } from "./index.js";
+const CAMEL_BASE = "https://stream.camelai.com/v1";
+const PARALLEL_BASE = "https://api.parallel.ai";
+const GATEWAY_ORIGIN = "https://gateway.ai.cloudflare.com";
+const CLOUDFLARE_API_ORIGIN = "https://api.cloudflare.com";
+const present = (value) => {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+};
+/** The one AI Gateway origin-and-path scope, or `undefined` when unnamed. */
+function gatewayScope(env) {
+    const account = present(env.AI_GATEWAY_ACCOUNT_ID);
+    const gateway = present(env.AI_GATEWAY_ID);
+    if (account === undefined || gateway === undefined)
+        return undefined;
+    return `${GATEWAY_ORIGIN}/v1/${encodeURIComponent(account)}/${encodeURIComponent(gateway)}`;
+}
+/** The destination and credential for a route; `undefined` if either is missing. */
+function target(env, route) {
+    switch (route) {
+        case "camel": {
+            const credential = present(env.CAMEL_API_KEY);
+            return credential === undefined
+                ? undefined
+                : { base: new URL(CAMEL_BASE), credential };
+        }
+        case "ai-gateway": {
+            const credential = present(env.AI_GATEWAY_AUTH_TOKEN);
+            const scope = gatewayScope(env);
+            return credential === undefined || scope === undefined
+                ? undefined
+                : { base: new URL(`${scope}/compat`), credential };
+        }
+        case "parallel": {
+            const credential = present(env.PARALLEL_API_KEY);
+            if (credential === undefined)
+                return undefined;
+            const scope = gatewayScope(env);
+            return {
+                base: new URL(scope === undefined ? PARALLEL_BASE : `${scope}/parallel`),
+                credential,
+            };
+        }
+        case "ai-gateway-logs": {
+            const credential = present(env.AI_GATEWAY_AUTH_TOKEN);
+            const account = present(env.AI_GATEWAY_ACCOUNT_ID);
+            const gateway = present(env.AI_GATEWAY_ID);
+            return credential === undefined ||
+                account === undefined ||
+                gateway === undefined
+                ? undefined
+                : {
+                    base: new URL(`${CLOUDFLARE_API_ORIGIN}/client/v4/accounts/${encodeURIComponent(account)}/ai-gateway/gateways/${encodeURIComponent(gateway)}/logs`),
+                    credential,
+                };
+        }
+    }
+}
+/** `url` is the base itself or lies beneath it, on the same https origin. */
+function within(url, base) {
+    if (url.protocol !== "https:" || url.origin !== base.origin)
+        return false;
+    if (url.username !== "" || url.password !== "")
+        return false;
+    const root = base.pathname.replace(/\/+$/u, "");
+    return url.pathname === root || url.pathname.startsWith(`${root}/`);
+}
+/** Replace whatever credential the caller sent with this route's own. */
+function authorize(route, headers, credential) {
+    for (const name of [
+        "authorization",
+        "x-api-key",
+        "cf-aig-authorization",
+        "proxy-authorization",
+    ])
+        headers.delete(name);
+    switch (route) {
+        case "camel":
+        case "ai-gateway-logs":
+            headers.set("authorization", `Bearer ${credential}`);
+            return;
+        case "ai-gateway":
+            headers.set("cf-aig-authorization", `Bearer ${credential}`);
+            return;
+        case "parallel":
+            headers.set("x-api-key", credential);
+            return;
+    }
+}
+/**
+ * The provider-key door. `fetch` is the transport the authorized request is
+ * finally sent on (a test double, or the Hub's telemetry-wrapped fetch).
+ */
+export function createProviderEgress(env, options = {}) {
+    const transport = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    return {
+        /** Whether this route's credential is configured; reveals no value. */
+        credentialed(route) {
+            switch (route) {
+                case "camel":
+                    return present(env.CAMEL_API_KEY) !== undefined;
+                case "parallel":
+                    return present(env.PARALLEL_API_KEY) !== undefined;
+                case "ai-gateway":
+                case "ai-gateway-logs":
+                    return present(env.AI_GATEWAY_AUTH_TOKEN) !== undefined;
+            }
+        },
+        /** The route's public base URL, or `null` while it is not configured. */
+        baseUrl(route) {
+            const resolved = target(env, route);
+            return resolved === undefined
+                ? null
+                : resolved.base.href.replace(/\/+$/u, "");
+        },
+        /**
+         * Send a credential-free request to a route. Refuses (`denied`) any
+         * destination outside the route and (`unavailable`) a route with no
+         * credential. Redirects are never followed, so a redirect cannot carry
+         * the key to another origin (workerd has no `error` mode; `manual` hands
+         * the 3xx back instead).
+         */
+        async fetch(route, input, init) {
+            const resolved = target(env, route);
+            if (resolved === undefined)
+                throw new VeilError("unavailable");
+            let request;
+            try {
+                request = new Request(input, init);
+            }
+            catch {
+                // Malformed, or a URL carrying userinfo: nothing Veil will send a key to.
+                throw new VeilError("denied");
+            }
+            if (!within(new URL(request.url), resolved.base))
+                throw new VeilError("denied");
+            const headers = new Headers(request.headers);
+            authorize(route, headers, resolved.credential);
+            try {
+                return await transport(new Request(request, { headers, redirect: "manual" }));
+            }
+            catch (error) {
+                // A cancelled call keeps its own reason; anything else is sanitized so
+                // a transport message can never carry request bytes back to the caller.
+                if (request.signal.aborted)
+                    throw error;
+                throw new VeilError("unavailable");
+            }
+        },
+    };
+}
+/** A `fetch` bound to one route, for consumers that take a plain fetch. */
+export function providerFetch(egress, route) {
+    return (input, init) => egress.fetch(route, input, init);
+}

package/dist/public-egress-policy.d.ts

@@ -0,0 +1,13 @@
+/** Host-owned policy, never populated from a Connector or OpenAPI document. */
+export type PublicEgressPolicy = Readonly<{
+    extraPorts?: readonly number[];
+    deniedHostSuffixes?: readonly string[];
+    deniedCidrs?: readonly string[];
+}>;
+/** Validate host-owned entries using the maintained IP parser and WHATWG URL grammar. */
+export declare function validatePublicEgressPolicyEntries(configuration: PublicEgressPolicy): boolean;
+/** The maintained IP parser owns CIDR matching, including mapped IPv4. */
+export declare function createPublicEgressPolicy(configuration?: PublicEgressPolicy): {
+    destination(url: URL): void;
+    addresses(values: readonly string[]): void;
+};

package/dist/public-egress-policy.js

@@ -0,0 +1,101 @@
+import ipaddr from "ipaddr.js";
+import { VeilError } from "./index.js";
+import { canonicalAddress } from "./model-key-network.js";
+/** Validate host-owned entries using the maintained IP parser and WHATWG URL grammar. */
+export function validatePublicEgressPolicyEntries(configuration) {
+    const cidrs = configuration.deniedCidrs ?? [];
+    const suffixes = configuration.deniedHostSuffixes ?? [];
+    if (new Set(cidrs).size !== cidrs.length ||
+        new Set(suffixes).size !== suffixes.length)
+        return false;
+    for (const cidr of cidrs) {
+        if (!ipaddr.isValidCIDR(cidr))
+            return false;
+        const [address, prefix] = ipaddr.parseCIDR(cidr);
+        if (address instanceof ipaddr.IPv4) {
+            if (prefix < 8 ||
+                cidr !==
+                    `${ipaddr.IPv4.networkAddressFromCIDR(cidr).toString()}/${String(prefix)}`)
+                return false;
+        }
+        else {
+            if (prefix < 16 ||
+                address.zoneId !== undefined ||
+                [
+                    "::ffff:0:0/96",
+                    "::ffff:0:0:0/96",
+                    "64:ff9b::/96",
+                    "64:ff9b:1::/48",
+                    "2002::/16",
+                    "2001::/32",
+                ].some((range) => {
+                    const [embedded, embeddedPrefix] = ipaddr.IPv6.parseCIDR(range);
+                    return address.match(embedded, Math.min(prefix, embeddedPrefix));
+                }) ||
+                cidr !==
+                    `${ipaddr.IPv6.networkAddressFromCIDR(cidr).toRFC5952String()}/${String(prefix)}`)
+                return false;
+        }
+    }
+    for (const suffix of suffixes) {
+        const input = `https://${suffix}`;
+        if (!URL.canParse(input))
+            return false;
+        const url = new URL(input);
+        const labels = suffix.split(".");
+        if (url.hostname !== suffix ||
+            url.username ||
+            url.password ||
+            url.port ||
+            url.pathname !== "/" ||
+            url.search ||
+            url.hash ||
+            ipaddr.isValid(suffix) ||
+            labels.length < 2 ||
+            suffix.length > 253 ||
+            !labels.every((label) => label.length <= 63 &&
+                /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u.test(label)))
+            return false;
+    }
+    return true;
+}
+/** The maintained IP parser owns CIDR matching, including mapped IPv4. */
+export function createPublicEgressPolicy(configuration = {}) {
+    if (!validatePublicEgressPolicyEntries(configuration))
+        throw new VeilError("invalid_input");
+    const ports = new Set([443, ...(configuration.extraPorts ?? [])]);
+    if ([...ports].some((port) => !Number.isInteger(port) || port < 1 || port > 65535))
+        throw new VeilError("invalid_input");
+    try {
+        const suffixes = configuration.deniedHostSuffixes ?? [];
+        const ranges = (configuration.deniedCidrs ?? []).map((cidr) => ipaddr.parseCIDR(cidr));
+        function address(value) {
+            const canonical = canonicalAddress(value);
+            if (canonical !== null &&
+                ipaddr.subnetMatch(ipaddr.process(canonical), { denied: ranges }, "allowed") === "denied")
+                throw new VeilError("denied");
+        }
+        return {
+            destination(url) {
+                const port = url.port === ""
+                    ? url.protocol === "https:"
+                        ? 443
+                        : 80
+                    : Number(url.port);
+                if (!ports.has(port))
+                    throw new VeilError("denied");
+                const hostname = url.hostname.toLowerCase().replace(/\.$/u, "");
+                if (suffixes.some((suffix) => hostname === suffix || hostname.endsWith(`.${suffix}`)))
+                    throw new VeilError("denied");
+                address(hostname);
+            },
+            addresses(values) {
+                for (const value of values)
+                    address(value);
+            },
+        };
+    }
+    catch {
+        throw new VeilError("invalid_input");
+    }
+}

package/dist/public-fetch.d.ts

@@ -0,0 +1,90 @@
+export { validatePublicEgressPolicyEntries } from "./public-egress-policy.js";
+import { type PublicEgressPolicy } from "./public-egress-policy.js";
+export { createPublicEgressPolicy, type PublicEgressPolicy, } from "./public-egress-policy.js";
+import { VeilError } from "./index.js";
+import { type HostResolver } from "./model-key-network.js";
+/**
+ * Veil's public-web door: an anonymous GET to a public URL, with no
+ * credential, from the one sanctioned egress. The name is resolved once,
+ * every answer must be public unicast (IPv4 and IPv6; loopback, private,
+ * link-local, metadata and address-embedding ranges are refused), and the
+ * connection is made to exactly one of those checked addresses. Host and TLS
+ * server name stay the URL's own, so certificates verify against the name the
+ * caller asked for while a second lookup can never move the connection (DNS
+ * rebinding). Each call is one hop: it never follows a redirect, so the
+ * caller's next hop resolves and is checked again.
+ */
+/** A connected socket, shaped like the Workers `cloudflare:sockets` Socket. */
+export type PublicSocket = Readonly<{
+    readable: ReadableStream<Uint8Array>;
+    writable: WritableStream<Uint8Array>;
+    opened: Promise<unknown>;
+    startTls: (options: Readonly<{
+        expectedServerHostname: string;
+    }>) => PublicSocket;
+    close: () => Promise<void>;
+}>;
+/**
+ * The host's socket primitive. Veil calls it only with an address it checked,
+ * never with a name, so no resolver sits between the check and the connection.
+ */
+export type PublicConnect = (address: Readonly<{
+    hostname: string;
+    port: number;
+}>, options: Readonly<{
+    secureTransport: "off" | "starttls";
+    allowHalfOpen: false;
+}>) => PublicSocket;
+/** One anonymous GET. Only these two request headers can ever be sent. */
+export type PublicGetRequest = Readonly<{
+    url: URL;
+    accept: string;
+    userAgent: string;
+    signal: AbortSignal;
+}>;
+export type PublicGet = (request: PublicGetRequest) => Promise<Response>;
+export type PublicFetchDoor = Readonly<{
+    get: PublicGet;
+}>;
+/** Where a refusal came from; the message never carries remote bytes. */
+export type PublicFetchStage = "address" | "dns" | "connect" | "response";
+export declare class PublicFetchError extends VeilError {
+    readonly stage: PublicFetchStage;
+    constructor(code: VeilError["code"], stage: PublicFetchStage);
+}
+/** Private HTTP adapter shared by anonymous GET and the OpenAPI policy door. */
+export type PublicHttpRequest = Readonly<{
+    url: URL;
+    method: string;
+    headers: Headers;
+    body: Uint8Array;
+    signal: AbortSignal;
+}>;
+/**
+ * The public-fetch door. `resolve` is the only name lookup and runs once per
+ * call; `connect` is handed only the addresses that lookup returned and
+ * Veil checked.
+ */
+export type PublicHttpDoor = Readonly<{
+    send: (request: PublicHttpRequest) => Promise<Response>;
+}>;
+export declare function createPublicHttp(options: Readonly<{
+    connect: PublicConnect;
+    resolve: HostResolver;
+    networkPolicy?: PublicEgressPolicy;
+}>): PublicHttpDoor;
+/** Anonymous GET keeps its existing two-header authority. */
+export declare function createPublicFetch(options: Readonly<{
+    connect: PublicConnect;
+    resolve: HostResolver;
+    networkPolicy?: PublicEgressPolicy;
+}>): PublicFetchDoor;
+/**
+ * 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 declare function configuredPublicFetch(options: Readonly<{
+    connect: PublicConnect;
+    fetch: typeof fetch;
+    networkPolicy?: PublicEgressPolicy;
+}>): PublicFetchDoor;