@fungi.computer/veil 0.2.0 → 0.3.0

package/README.md

@@ -84,6 +84,75 @@ Workerd's `startTls({ expectedServerHostname })` verifies the certificate
 against that name; it reports a verification failure on the first read, which
 the door types as `unavailable`.
 
+## Platform snapshot egress (private, not enabled by this change)
+
+`configuredProviderEgress(env)` (from `./gatekeeper`) also owns the platform
+snapshot routes below. Like the existing Hub search caller
+(`apps/hub/src/agent-web-search.ts`, `configuredWebSearch`), a caller obtains
+`baseUrl(route)` and passes credential-free requests through
+`providerFetch(egress, route)`. Veil alone reads the bindings, pins the
+destination and attaches the credential. The new holdings callers are composed
+later; these routes neither mount Hub endpoints nor schedule jobs.
+
+| Route                 | Destination / allowed calls                                                                      | Private bindings                                                                                                             |
+| --------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `solana-rpc`          | Helius mainnet, exactly `https://mainnet.helius-rpc.com/`, POST                                  | `SOLANA_RPC_URL` (that credential-free root), `SOLANA_RPC_API_KEY` (Worker secret)                                           |
+| `solana-rpc-fallback` | One configured QuickNode Solana mainnet endpoint, exactly its HTTPS root, POST                   | `SOLANA_RPC_FALLBACK_URL` (`https://<endpoint>.solana-mainnet.quiknode.pro/`), `SOLANA_RPC_FALLBACK_API_KEY` (Worker secret) |
+| `sanctions-screen`    | GET exactly `https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN.XML` | `SANCTIONS_SDN_URL` (that exact URL, opt-in)                                                                                 |
+
+The RPC routes accept only single JSON-RPC 2.0 calls to `getAccountInfo`,
+`getMultipleAccounts`, `getProgramAccounts`, `getTokenSupply` and `getSlot`:
+mint/program-owner boot checks, token and lock account reads, supply and
+finalized-slot reconciliation. Transactions, simulation, airdrops, arbitrary
+methods and batches are refused. The holdings owner still owns finality, params,
+maintained account decoders and reconciliation. QuickNode is the proposal's
+second-provider choice, not an automatic retry: its caller must apply the same
+snapshot checks on fallback.
+
+Helius receives `?api-key=<secret>`; QuickNode receives `/<secret>/`. Neither
+credential-bearing URL is returned from `baseUrl`. Caller headers, queries and
+alternate paths are not forwarded. Keep keys in the existing private
+Worker-secret custody, never Team storage, public config, telemetry or logs. The
+final transport sees the authorized URL and must not log it. Missing/invalid
+bindings refuse `unavailable` before fetch; other destinations or methods refuse
+`denied`. RPC redirects and non-2xx responses refuse `unavailable`; no upstream
+error body, headers or URL is returned. Successful bodies are bounded to 64 MiB
+and refused on a credential echo (raw, JSON-escaped or percent-encoded); RPC
+request bodies are bounded to 64 KiB. Transport failures, including aborts,
+expose only fixed `VeilError` codes. The existing streaming model/search routes
+and model-key rules are unchanged.
+
+The sanctions GET alone may manually follow **one HTTP 302** from the exact OFAC
+export to
+`https://wc2h-sls-prod-public-published.s3.us-gov-west-1.amazonaws.com`, with a
+path beginning `/Published/` and ending `/SDN.XML`. OFAC's signed query is
+retained; caller headers/credentials and upstream cookies are not forwarded. The
+Location string is capped at 8,192 code units, must have no userinfo or
+fragment, and cannot change HTTPS or port 443. Veil cancels the redirect body
+before the second GET, uses the original abort signal (including any caller
+deadline, never restarted) and keeps the same 64 MiB download bound. Another
+host/path, a missing/invalid Location, a second redirect or any other redirect
+status refuses `unavailable`. Direct entry at S3 and non-GET sanctions requests
+remain refused.
+
+**Sanctions choice:** use the official OFAC SDN XML list, not the Chainalysis
+free API. Read-only confirmation on 2026-10-31 found actual
+`Digital Currency Address - SOL` identifiers in the official export (including
+ID 194579), establishing Solana-address coverage without assuming a vendor's
+chain support. OFAC's public list requires **no credential**, so there is no
+`SANCTIONS_API_KEY` binding or invented anonymous-key fallback. F5 must parse
+the XML through a maintained decoder, match the SOL identifiers, and fail closed
+on an unavailable or unusable list; this door does not claim to screen persons,
+countries or unlisted addresses.
+
+Provider contract sources:
+[Helius RPC](https://www.helius.dev/docs/rpc/overview),
+[QuickNode endpoints](https://www.quicknode.com/docs/solana/endpoints),
+[OFAC data formats](https://ofac.treasury.gov/specially-designated-nationals-list-data-formats-data-schemas)
+and the exact official export above. Unit fixtures prove custody and route
+policy, not provisioned keys, paid-plan large-snapshot support, live RPC
+reconciliation or live screening; F4/F5 own those opt-in proofs.
+
 ## Model credentials and failure handling
 
 `src/model-credentials.ts` selects which key class may serve an inference

package/dist/model-credentials.d.ts

@@ -3,12 +3,11 @@
  * provider login policy: the local runtime, the TUI login registry and the Hub
  * read it; none of them decides visibility on its own.
  *
- * Stance: like Pi and OpenCode, offer a person's own subscription locally and
- * hosted, and turn a provider off through `subscriptionKillSwitch` if it
- * objects or blocks tokens. A subscription is always one person's: never
- * Team-scoped, shared or pooled. The new OpenAI ChatGPT plan flow is
- * local-only; hosted use awaits OpenAI approval. The retired Codex provider
- * is forbidden on both hosts.
+ * Offer a person's own Claude or ChatGPT subscription locally, never on
+ * hosted Fungi. A subscription is always one person's: never Team-scoped,
+ * shared or pooled. `subscriptionKillSwitch` can turn off a provider if it
+ * objects or blocks tokens. Hosted BYOK uses API keys. The retired Codex
+ * provider is forbidden on both hosts.
  * See wiki/3-resources/decisions/adr-byok-model-keys-v1.md.
  */
 /** The owner's own machine, or Fungi's servers acting for a Team. */
@@ -69,7 +68,9 @@ export declare const modelCredentialPolicy: Readonly<{
                 status: "allowed";
             }>;
             hosted: Readonly<{
-                status: "allowed";
+                status: "forbidden";
+                reason: string;
+                source: string;
             }>;
         };
     };

package/dist/model-credentials.js

@@ -3,17 +3,21 @@
  * provider login policy: the local runtime, the TUI login registry and the Hub
  * read it; none of them decides visibility on its own.
  *
- * Stance: like Pi and OpenCode, offer a person's own subscription locally and
- * hosted, and turn a provider off through `subscriptionKillSwitch` if it
- * objects or blocks tokens. A subscription is always one person's: never
- * Team-scoped, shared or pooled. The new OpenAI ChatGPT plan flow is
- * local-only; hosted use awaits OpenAI approval. The retired Codex provider
- * is forbidden on both hosts.
+ * Offer a person's own Claude or ChatGPT subscription locally, never on
+ * hosted Fungi. A subscription is always one person's: never Team-scoped,
+ * shared or pooled. `subscriptionKillSwitch` can turn off a provider if it
+ * objects or blocks tokens. Hosted BYOK uses API keys. The retired Codex
+ * provider is forbidden on both hosts.
  * See wiki/3-resources/decisions/adr-byok-model-keys-v1.md.
  */
 const allowed = { status: "allowed" };
 const unreviewed = { status: "unreviewed" };
 const notOffered = {
+    status: "forbidden",
+    reason: "Fungi does not offer this credential method on this host",
+    source: "wiki/3-resources/decisions/adr-byok-model-keys-v1.md",
+};
+const providerNotOffered = {
     status: "forbidden",
     reason: "The provider does not offer this credential method",
     source: "provider documentation",
@@ -25,7 +29,7 @@ const retiredCodex = {
 };
 const apiKeyOnly = {
     api_key: { local: allowed, hosted: allowed },
-    subscription: { local: notOffered, hosted: notOffered },
+    subscription: { local: providerNotOffered, hosted: providerNotOffered },
 };
 /**
  * Reviewed providers, keyed by Pi provider id. `openai-compatible` is a
@@ -38,9 +42,8 @@ export const modelCredentialPolicy = Object.freeze({
     },
     anthropic: {
         api_key: { local: allowed, hosted: allowed },
-        // Local: Pi's Claude Pro/Max OAuth, as Pi and OpenCode ship it. Hosted: the
-        // unmodified Claude Code binary on the owner's Computer, signed in by them.
-        subscription: { local: allowed, hosted: allowed },
+        // Local: Pi's Claude Pro/Max OAuth. Hosted: no Claude subscription login.
+        subscription: { local: allowed, hosted: notOffered },
     },
     "openai-codex": {
         api_key: { local: retiredCodex, hosted: retiredCodex },
@@ -52,8 +55,8 @@ export const modelCredentialPolicy = Object.freeze({
             local: allowed,
             hosted: {
                 status: "forbidden",
-                reason: "ChatGPT plan usage in a hosted app requires OpenAI approval",
-                source: "https://developers.openai.com/siwc/token-sharing-open-source",
+                reason: "Fungi does not offer ChatGPT subscription sign-in on hosted Fungi; approval alone would not enable it",
+                source: "wiki/3-resources/decisions/adr-byok-model-keys-v1.md",
             },
         },
     },

package/dist/provider-egress.d.ts

@@ -14,6 +14,9 @@
  *   `/parallel` route, with `x-api-key`.
  * - `ai-gateway-logs`: Cloudflare's API log read used for usage
  *   reconciliation, `Authorization: Bearer` with the gateway token.
+ * - `solana-rpc` / `solana-rpc-fallback`: finalized snapshot reads through
+ *   Helius / QuickNode, with private query / path credentials.
+ * - `sanctions-screen`: the official OFAC SDN XML export, without a key.
  */
 /** Private Worker bindings read only here; never Team storage or responses. */
 export type ProviderKeyBindings = Readonly<{
@@ -24,8 +27,16 @@ export type ProviderKeyBindings = Readonly<{
     /** Cloudflare account that owns the gateway; routes are scoped to it. */
     AI_GATEWAY_ACCOUNT_ID?: string;
     AI_GATEWAY_ID?: string;
+    /** Credential-free Helius mainnet root; the key is a separate Worker secret. */
+    SOLANA_RPC_URL?: string;
+    SOLANA_RPC_API_KEY?: string;
+    /** Credential-free QuickNode Solana mainnet root; token is a Worker secret. */
+    SOLANA_RPC_FALLBACK_URL?: string;
+    SOLANA_RPC_FALLBACK_API_KEY?: string;
+    /** Opt-in to the pinned public OFAC SDN XML export. No API key is needed. */
+    SANCTIONS_SDN_URL?: string;
 }>;
-export type ProviderRoute = "camel" | "ai-gateway" | "parallel" | "ai-gateway-logs";
+export type ProviderRoute = "camel" | "ai-gateway" | "parallel" | "ai-gateway-logs" | "solana-rpc" | "solana-rpc-fallback" | "sanctions-screen";
 /**
  * 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).
@@ -33,16 +44,16 @@ export type ProviderRoute = "camel" | "ai-gateway" | "parallel" | "ai-gateway-lo
 export declare function createProviderEgress(env: ProviderKeyBindings, options?: Readonly<{
     fetch?: typeof globalThis.fetch;
 }>): {
-    /** Whether this route's credential is configured; reveals no value. */
+    /** Whether required custody/configuration is present; reveals no value. */
     credentialed(route: ProviderRoute): boolean;
     /** The route's public base URL, or `null` while it is not configured. */
     baseUrl(route: ProviderRoute): string | null;
     /**
      * 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).
+     * credential. Credentialed routes never follow redirects (workerd has no
+     * `error` mode; `manual` hands the 3xx back instead). Only the anonymous
+     * sanctions GET may follow one pinned OFAC government-S3 302.
      */
     fetch(route: ProviderRoute, input: string | URL | Request, init?: RequestInit): Promise<Response>;
 };

package/dist/provider-egress.js

@@ -1,8 +1,33 @@
+import { z } from "zod";
 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 HELIUS_BASE = "https://mainnet.helius-rpc.com/";
+const OFAC_SDN = "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN.XML";
+const OFAC_DOWNLOAD_ORIGIN = "https://wc2h-sls-prod-public-published.s3.us-gov-west-1.amazonaws.com";
+// Single read-only JSON-RPC calls used by the finalized holdings/lock reader.
+// Zod owns JSON envelope decoding; the holdings owner owns params and results.
+const snapshotCall = z
+    .object({
+    jsonrpc: z.literal("2.0"),
+    id: z.union([z.string(), z.number()]),
+    method: z.enum([
+        "getAccountInfo",
+        "getMultipleAccounts",
+        "getProgramAccounts",
+        "getTokenSupply",
+        "getSlot",
+    ]),
+    params: z.array(z.unknown()).optional(),
+})
+    .strict();
+function snapshotRoute(route) {
+    return (route === "solana-rpc" ||
+        route === "solana-rpc-fallback" ||
+        route === "sanctions-screen");
+}
 const present = (value) => {
     const trimmed = value?.trim();
     return trimmed === undefined || trimmed === "" ? undefined : trimmed;
@@ -18,6 +43,34 @@ function gatewayScope(env) {
 /** The destination and credential for a route; `undefined` if either is missing. */
 function target(env, route) {
     switch (route) {
+        case "solana-rpc":
+        case "solana-rpc-fallback": {
+            const primary = route === "solana-rpc";
+            const raw = present(primary ? env.SOLANA_RPC_URL : env.SOLANA_RPC_FALLBACK_URL);
+            const credential = present(primary ? env.SOLANA_RPC_API_KEY : env.SOLANA_RPC_FALLBACK_API_KEY);
+            if (raw === undefined || credential === undefined)
+                return undefined;
+            if (!URL.canParse(raw))
+                return undefined;
+            const base = new URL(raw);
+            if (base.protocol !== "https:" ||
+                base.username ||
+                base.password ||
+                base.port ||
+                base.pathname !== "/" ||
+                base.search ||
+                base.hash)
+                return undefined;
+            if (primary
+                ? base.href !== HELIUS_BASE
+                : !/^[a-z0-9-]+\.solana-mainnet\.quiknode\.pro$/u.test(base.hostname))
+                return undefined;
+            return { base, credential };
+        }
+        case "sanctions-screen":
+            return present(env.SANCTIONS_SDN_URL) === OFAC_SDN
+                ? { base: new URL(OFAC_SDN) }
+                : undefined;
         case "camel": {
             const credential = present(env.CAMEL_API_KEY);
             return credential === undefined
@@ -67,6 +120,8 @@ function within(url, base) {
 }
 /** Replace whatever credential the caller sent with this route's own. */
 function authorize(route, headers, credential) {
+    if (credential === undefined)
+        throw new VeilError("unavailable");
     for (const name of [
         "authorization",
         "x-api-key",
@@ -75,6 +130,11 @@ function authorize(route, headers, credential) {
     ])
         headers.delete(name);
     switch (route) {
+        case "solana-rpc":
+        case "solana-rpc-fallback":
+        case "sanctions-screen":
+            // These doors construct their own headers and URL below.
+            return;
         case "camel":
         case "ai-gateway-logs":
             headers.set("authorization", `Bearer ${credential}`);
@@ -87,6 +147,130 @@ function authorize(route, headers, credential) {
             return;
     }
 }
+/** A bounded body, before JSON decoding or returning a provider response. */
+async function boundedText(message, limit) {
+    const reader = message.body?.getReader();
+    if (reader === undefined)
+        return "";
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            const chunk = part.value;
+            if (!(chunk instanceof Uint8Array))
+                throw new VeilError("unavailable");
+            size += chunk.byteLength;
+            if (size > limit)
+                throw new VeilError("unavailable");
+            chunks.push(chunk);
+        }
+        return await new Blob(chunks).text();
+    }
+    finally {
+        try {
+            await reader.cancel();
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}
+/** Fixed, non-streaming snapshot doors never return upstream headers or URLs. */
+async function fetchSnapshot(route, resolved, request, transport) {
+    try {
+        const url = new URL(request.url);
+        if (url.href !== resolved.base.href)
+            throw new VeilError("denied");
+        const screening = route === "sanctions-screen";
+        if (request.method !== (screening ? "GET" : "POST"))
+            throw new VeilError("denied");
+        let body;
+        if (!screening) {
+            body = await boundedText(request, 64 * 1024);
+            let envelope;
+            try {
+                envelope = JSON.parse(body);
+            }
+            catch {
+                throw new VeilError("denied");
+            }
+            if (!snapshotCall.safeParse(envelope).success)
+                throw new VeilError("denied");
+        }
+        const destination = new URL(resolved.base);
+        const key = resolved.credential;
+        if (!screening) {
+            if (key === undefined)
+                throw new VeilError("unavailable");
+            if (route === "solana-rpc")
+                destination.searchParams.set("api-key", key);
+            else
+                destination.pathname = `/${encodeURIComponent(key)}/`;
+        }
+        const init = {
+            method: request.method,
+            headers: screening
+                ? { accept: "application/xml" }
+                : {
+                    accept: "application/json",
+                    "content-type": "application/json",
+                },
+            signal: request.signal,
+            redirect: "manual",
+        };
+        if (body !== undefined)
+            init.body = body;
+        let response = await transport(new Request(destination, init));
+        // OFAC publishes a signed S3 download URL. Only this anonymous GET door
+        // may follow that one observed 302; the next response must succeed.
+        if (screening && response.status === 302) {
+            const location = response.headers.get("location");
+            await response.body?.cancel();
+            if (location === null ||
+                location.length > 8192 ||
+                !URL.canParse(location))
+                throw new VeilError("unavailable");
+            const download = new URL(location);
+            if (download.origin !== OFAC_DOWNLOAD_ORIGIN ||
+                download.username !== "" ||
+                download.password !== "" ||
+                !download.pathname.startsWith("/Published/") ||
+                !download.pathname.endsWith("/SDN.XML") ||
+                download.hash !== "")
+                throw new VeilError("unavailable");
+            request.signal.throwIfAborted();
+            response = await transport(new Request(download, {
+                method: "GET",
+                headers: { accept: "application/xml" },
+                signal: request.signal,
+                redirect: "manual",
+            }));
+        }
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new VeilError("unavailable");
+        }
+        const text = await boundedText(response, 64 * 1024 * 1024);
+        if (key !== undefined &&
+            [key, encodeURIComponent(key), JSON.stringify(key).slice(1, -1)].some((echo) => text.includes(echo)))
+            throw new VeilError("unavailable");
+        return new Response(text, {
+            status: response.status,
+            headers: {
+                "content-type": screening ? "application/xml" : "application/json",
+            },
+        });
+    }
+    catch (error) {
+        // Even aborted transports can include a credential-bearing URL in errors.
+        if (error instanceof VeilError)
+            throw error;
+        throw new VeilError("unavailable");
+    }
+}
 /**
  * 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).
@@ -94,9 +278,13 @@ function authorize(route, headers, credential) {
 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. */
+        /** Whether required custody/configuration is present; reveals no value. */
         credentialed(route) {
             switch (route) {
+                case "solana-rpc":
+                case "solana-rpc-fallback":
+                case "sanctions-screen":
+                    return target(env, route) !== undefined;
                 case "camel":
                     return present(env.CAMEL_API_KEY) !== undefined;
                 case "parallel":
@@ -116,9 +304,9 @@ export function createProviderEgress(env, options = {}) {
         /**
          * 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).
+         * credential. Credentialed routes never follow redirects (workerd has no
+         * `error` mode; `manual` hands the 3xx back instead). Only the anonymous
+         * sanctions GET may follow one pinned OFAC government-S3 302.
          */
         async fetch(route, input, init) {
             const resolved = target(env, route);
@@ -134,6 +322,8 @@ export function createProviderEgress(env, options = {}) {
             }
             if (!within(new URL(request.url), resolved.base))
                 throw new VeilError("denied");
+            if (snapshotRoute(route))
+                return fetchSnapshot(route, resolved, request, transport);
             const headers = new Headers(request.headers);
             authorize(route, headers, resolved.credential);
             try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fungi.computer/veil",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": "Levi <levi@technomancy.dev>",
   "description": "Team-authorized credential custody and provider access",
   "type": "module",