@fungi.computer/veil 0.2.1 → 0.4.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/connections/contract.d.ts

@@ -0,0 +1,141 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import type { PublicEgressPolicy } from "../public-egress-policy.js";
+export type ConnectionsRefusal = "invalid_input" | "denied" | "revoked" | "conflict" | "unsupported" | "too_large" | "reconnect_required" | "invalid_response" | "unavailable";
+/** Fixed codes only: upstream bodies, URLs and credential bytes never enter errors. */
+export declare class ConnectionsError extends Error {
+    readonly code: ConnectionsRefusal;
+    readonly name = "ConnectionsError";
+    constructor(code: ConnectionsRefusal, options?: ErrorOptions);
+}
+export declare const identifier: Schema.String;
+declare const placementSchema: Schema.Union<readonly [Schema.Literal<"bearer">, Schema.Struct<{
+    readonly header: Schema.String;
+}>, Schema.Struct<{
+    readonly query: Schema.String;
+}>]>;
+export type Placement = typeof placementSchema.Type;
+/** How the final request is authorized. OAuth joins this union in slice 3. */
+export declare const credentialSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly kind: Schema.Literal<"none">;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"static">;
+    readonly placement: Schema.Union<readonly [Schema.Literal<"bearer">, Schema.Struct<{
+        readonly header: Schema.String;
+    }>, Schema.Struct<{
+        readonly query: Schema.String;
+    }>]>;
+}>]>;
+export type Credential = typeof credentialSchema.Type;
+export type SurfaceView = Readonly<{
+    kind: "mcp";
+    url: string;
+}> | Readonly<{
+    kind: "openapi";
+    baseUrl: string;
+    table: unknown;
+}>;
+export declare const toolsSchema: Schema.Union<readonly [Schema.Literal<"all">, Schema.$Array<Schema.String>]>;
+export type Tools = typeof toolsSchema.Type;
+export declare const draftSchema: Schema.Struct<{
+    /** Idempotency key: a replay with the same request returns the same connection. */
+    readonly requestId: Schema.String;
+    readonly name: Schema.String;
+    readonly surface: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"mcp">;
+        readonly url: Schema.String;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"openapi">;
+        readonly baseUrl: Schema.String;
+        readonly table: Schema.Unknown;
+    }>]>;
+    readonly credential: Schema.Union<readonly [Schema.Struct<{
+        readonly kind: Schema.Literal<"none">;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"static">;
+        readonly placement: Schema.Union<readonly [Schema.Literal<"bearer">, Schema.Struct<{
+            readonly header: Schema.String;
+        }>, Schema.Struct<{
+            readonly query: Schema.String;
+        }>]>;
+    }>]>;
+    readonly secret: Schema.optional<Schema.String>;
+}>;
+export type ConnectionDraft = typeof draftSchema.Type;
+export declare const grantInputSchema: Schema.Struct<{
+    readonly connectionId: Schema.String;
+    readonly agentId: Schema.String;
+    readonly tools: Schema.Union<readonly [Schema.Literal<"all">, Schema.$Array<Schema.String>]>;
+}>;
+export type GrantInput = typeof grantInputSchema.Type;
+export declare const egressRefSchema: Schema.Struct<{
+    readonly connectionId: Schema.String;
+    readonly grantVersion: Schema.Number;
+}>;
+export type EgressRef = typeof egressRefSchema.Type;
+/** Where custody finds one connection; carries no secret. */
+export type CustodyAddress = Readonly<{
+    ownerId: string;
+    connectionId: string;
+    credential: Credential;
+}>;
+/**
+ * Owner-side credential custody. `sealed` stores ciphertext, `nango` a locator.
+ * Only `inject` ever opens a credential, and it sends the request itself.
+ */
+export type CustodyAdapter = Readonly<{
+    put: (address: CustodyAddress, secret: string) => Effect.Effect<string, ConnectionsError>;
+    inject: (address: CustodyAddress, locator: string, request: Request) => Effect.Effect<Response, ConnectionsError>;
+    remove: (address: CustodyAddress, locator: string) => Effect.Effect<"deleted" | "absent", ConnectionsError>;
+}>;
+export type SqlValue = string | number | null;
+/** The owner's SQLite in Cloudflare `ctx.storage` shape. */
+export type SqlStore = Readonly<{
+    sql: Readonly<{
+        exec: (statement: string, ...bindings: SqlValue[]) => Readonly<{
+            toArray: () => readonly unknown[];
+        }>;
+    }>;
+    transactionSync: <A>(operation: () => A) => A;
+}>;
+export type ConnectionsOptions = Readonly<{
+    ownerId: string;
+    store: SqlStore;
+    custody: CustodyAdapter;
+    /** Host authority read: may this actor manage connections, or still stand as a grantor? */
+    authorize: (actorId: string, purpose: "manage" | "grantor") => boolean;
+    egressPolicy?: PublicEgressPolicy;
+    clock: () => number;
+    ids: () => string;
+}>;
+/** Secret-free, versioned, and safe to hand to an Agent. */
+export type ConnectionProjection = Readonly<{
+    revision: number;
+    connections: readonly Readonly<{
+        connectionId: string;
+        name: string;
+        surface: SurfaceView;
+        tools: Tools;
+        authorityVersion: number;
+        grantVersion: number;
+    }>[];
+}>;
+export type ConnectionView = Readonly<{
+    connectionId: string;
+    name: string;
+    surface: Readonly<{
+        kind: "mcp" | "openapi";
+        origin: string;
+    }>;
+    credentialKind: Credential["kind"];
+    state: "active" | "reconnect_required" | "revoked";
+    authorityVersion: number;
+    grants: readonly Readonly<{
+        agentId: string;
+        tools: Tools;
+        version: number;
+    }>[];
+}>;
+/** The Agent's narrowed capability: only the owner opens the credential. */
+export type NarrowFetch = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+export {};

package/dist/connections/contract.js

@@ -0,0 +1,55 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/** Fixed codes only: upstream bodies, URLs and credential bytes never enter errors. */
+export class ConnectionsError extends Error {
+    code;
+    name = "ConnectionsError";
+    constructor(code, options) {
+        super(code, options);
+        this.code = code;
+    }
+}
+export const identifier = Schema.String.pipe(Schema.check(Schema.isPattern(/^[A-Za-z0-9_.:-]{1,128}$/u)));
+const headerName = Schema.String.pipe(Schema.check(Schema.isPattern(/^[A-Za-z0-9-]{1,64}$/u)));
+const queryName = Schema.String.pipe(Schema.check(Schema.isPattern(/^[A-Za-z0-9_.-]{1,64}$/u)));
+const version = Schema.Number.pipe(Schema.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(1)));
+const placementSchema = Schema.Union([
+    Schema.Literal("bearer"),
+    Schema.Struct({ header: headerName }),
+    Schema.Struct({ query: queryName }),
+]);
+/** How the final request is authorized. OAuth joins this union in slice 3. */
+export const credentialSchema = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("none") }),
+    Schema.Struct({ kind: Schema.Literal("static"), placement: placementSchema }),
+]);
+/** What the Agent can call. The OpenAPI table is decoded by Forage before it is stored. */
+const surfaceDraftSchema = Schema.Union([
+    Schema.Struct({ kind: Schema.Literal("mcp"), url: Schema.String }),
+    Schema.Struct({
+        kind: Schema.Literal("openapi"),
+        baseUrl: Schema.String,
+        table: Schema.Unknown,
+    }),
+]);
+export const toolsSchema = Schema.Union([
+    Schema.Literal("all"),
+    Schema.Array(Schema.String.pipe(Schema.check(Schema.isMinLength(1), Schema.isMaxLength(256)))).pipe(Schema.check(Schema.isMaxLength(256))),
+]);
+export const draftSchema = Schema.Struct({
+    /** Idempotency key: a replay with the same request returns the same connection. */
+    requestId: identifier,
+    name: Schema.String.pipe(Schema.check(Schema.isMinLength(1), Schema.isMaxLength(128))),
+    surface: surfaceDraftSchema,
+    credential: credentialSchema,
+    secret: Schema.optional(Schema.String.pipe(Schema.check(Schema.isPattern(/^[\x21-\x7e]{1,16384}$/u)))),
+});
+export const grantInputSchema = Schema.Struct({
+    connectionId: identifier,
+    agentId: identifier,
+    tools: toolsSchema,
+});
+export const egressRefSchema = Schema.Struct({
+    connectionId: identifier,
+    grantVersion: version,
+});

package/dist/connections/core.d.ts

@@ -0,0 +1,48 @@
+import * as Effect from "effect/Effect";
+import { ConnectionsError, type ConnectionDraft, type GrantInput, type ConnectionsOptions, type EgressRef, type NarrowFetch, type SurfaceView } from "./contract.js";
+/** One owner's connections: attempts, connections, grants, receipts and cleanup in its SQLite. */
+export declare function createConnections(options: ConnectionsOptions): {
+    begin: (actor: string, input: ConnectionDraft) => Effect.Effect<{
+        connectionId: string;
+        authorizeUrl: null;
+    }, ConnectionsError, never>;
+    grant: (actor: string, input: GrantInput) => Effect.Effect<{
+        grantVersion: number;
+    }, ConnectionsError, never>;
+    ungrant: (actor: string, input: {
+        connectionId: string;
+        agentId: string;
+    }) => Effect.Effect<void, ConnectionsError, never>;
+    revoke: (actor: string, input: {
+        connectionId: string;
+    }) => Effect.Effect<void, ConnectionsError, never>;
+    projection: (agentId: string) => Effect.Effect<{
+        revision: number;
+        connections: {
+            connectionId: string;
+            name: string;
+            surface: SurfaceView;
+            tools: readonly string[] | "all";
+            authorityVersion: number;
+            grantVersion: number;
+        }[];
+    }, ConnectionsError, never>;
+    list: (actor: string) => Effect.Effect<Readonly<{
+        connectionId: string;
+        name: string;
+        surface: Readonly<{
+            kind: "mcp" | "openapi";
+            origin: string;
+        }>;
+        credentialKind: import("./contract.js").Credential["kind"];
+        state: "active" | "reconnect_required" | "revoked";
+        authorityVersion: number;
+        grants: readonly Readonly<{
+            agentId: string;
+            tools: import("./contract.js").Tools;
+            version: number;
+        }>[];
+    }>[], ConnectionsError, never>;
+    egress: (agentId: string, input: EgressRef) => NarrowFetch;
+    sweep: () => Effect.Effect<void, ConnectionsError, never>;
+};