@fungi.computer/veil 0.4.0 → 0.5.0

package/dist/connections/core.js

@@ -1,26 +1,16 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { parseOpenApiTable } from "@fungi.computer/forage/openapi";
 import { assertPublicHostName } from "../model-key-network.js";
 import { createPublicEgressPolicy } from "../public-egress-policy.js";
-import { ConnectionsError, credentialSchema, draftSchema, egressRefSchema, grantInputSchema, identifier, toolsSchema, } from "./contract.js";
+import { ConnectionsError, callInputSchema, completeInputSchema, draftSchema, egressRefSchema, grantInputSchema, identifier, toolsSchema, } from "./contract.js";
 import { admitRequest } from "./egress.js";
+import { admits, boundedText, decodeTable, operationOutput, operationRequest, } from "./openapi.js";
+import { createCleanup } from "./cleanup.js";
+import { attemptRow, connectionRow, count, decode, io, json, registryRow, sync, } from "./internal.js";
+import { createOAuthFlow } from "./oauth-flow.js";
+import { listMcpTools } from "./discover.js";
+import { createUpdate } from "./update.js";
 const attemptTtlMs = 10 * 60 * 1000;
-const cleanupLimit = 5;
-const json = (schema) => Schema.fromJsonString(schema);
-const connectionRow = Schema.Struct({
-    id: identifier,
-    name: Schema.String,
-    surface: json(Schema.Struct({
-        kind: Schema.Literals(["mcp", "openapi"]),
-        url: Schema.String,
-        table: Schema.NullOr(Schema.Unknown),
-    })),
-    credential: json(credentialSchema),
-    locator: Schema.NullOr(Schema.String),
-    state: Schema.Literals(["active", "reconnect_required", "revoked"]),
-    authorityVersion: Schema.Number,
-});
 const grantRow = Schema.Struct({
     connectionId: identifier,
     agentId: identifier,
@@ -31,40 +21,18 @@ const grantRow = Schema.Struct({
 });
 const receiptRow = Schema.Struct({
     fingerprint: Schema.String,
-    result: json(Schema.Struct({ connectionId: identifier })),
-});
-const cleanupRow = Schema.Struct({
-    id: Schema.Number,
-    connectionId: identifier,
-    locator: Schema.String,
-    credential: json(credentialSchema),
-    attempts: Schema.Number,
-});
-const count = Schema.Struct({ n: Schema.Number });
-function decode(schema, input) {
-    try {
-        return Schema.decodeUnknownSync(schema)(input);
-    }
-    catch {
-        throw new ConnectionsError("invalid_input");
-    }
-}
-const sync = (operation) => Effect.try({
-    try: operation,
-    catch: (cause) => cause instanceof ConnectionsError
-        ? cause
-        : new ConnectionsError("unavailable", { cause }),
-});
-const io = (operation) => Effect.tryPromise({
-    try: operation,
-    catch: (cause) => cause instanceof ConnectionsError
-        ? cause
-        : new ConnectionsError("unavailable", { cause }),
+    result: json(Schema.Struct({
+        connectionId: identifier,
+        authorizeUrl: Schema.optional(Schema.String),
+        version: Schema.optional(Schema.Number),
+    })),
 });
 /** One owner's connections: attempts, connections, grants, receipts and cleanup in its SQLite. */
 export function createConnections(options) {
     const ownerId = decode(identifier, options.ownerId);
-    const { sql, transactionSync } = options.store;
+    const { sql } = options.store;
+    // A Durable Object's storage must be called as a method, never detached.
+    const transactionSync = (body) => options.store.transactionSync(body);
     const policy = createPublicEgressPolicy(options.egressPolicy);
     sql.exec(`
     CREATE TABLE IF NOT EXISTS veil_connection_attempts (
@@ -73,7 +41,8 @@ export function createConnections(options) {
       pkceVerifierSealed TEXT, issuer TEXT) STRICT;
     CREATE TABLE IF NOT EXISTS veil_connections (
       id TEXT PRIMARY KEY, name TEXT NOT NULL, surface TEXT NOT NULL, credential TEXT NOT NULL,
-      locator TEXT, state TEXT NOT NULL, authorityVersion INTEGER NOT NULL) STRICT;
+      locator TEXT, state TEXT NOT NULL, authorityVersion INTEGER NOT NULL,
+      version INTEGER NOT NULL) STRICT;
     CREATE TABLE IF NOT EXISTS veil_connection_grants (
       connectionId TEXT NOT NULL, agentId TEXT NOT NULL, tools TEXT NOT NULL,
       grantor TEXT NOT NULL, version INTEGER NOT NULL, active INTEGER NOT NULL,
@@ -83,6 +52,8 @@ export function createConnections(options) {
     CREATE TABLE IF NOT EXISTS veil_connection_cleanup (
       id INTEGER PRIMARY KEY AUTOINCREMENT, connectionId TEXT NOT NULL, locator TEXT NOT NULL,
       credential TEXT NOT NULL, attempts INTEGER NOT NULL) STRICT;
+    CREATE TABLE IF NOT EXISTS veil_oauth_clients (
+      issuer TEXT PRIMARY KEY, locator TEXT NOT NULL) STRICT;
     CREATE TABLE IF NOT EXISTS veil_connection_epoch (id INTEGER PRIMARY KEY CHECK (id = 1), revision INTEGER NOT NULL) STRICT;
     INSERT OR IGNORE INTO veil_connection_epoch VALUES (1, 1);`);
     const rows = (schema, statement, ...bindings) => sql
@@ -101,6 +72,12 @@ export function createConnections(options) {
             throw new ConnectionsError("denied");
         return row;
     };
+    /** One live connection per binding name, so an Agent's module name is unambiguous. */
+    const assertNameFree = (name, exceptId) => {
+        const taken = rows(count, "SELECT COUNT(*) AS n FROM veil_connections WHERE name = ? AND state != 'revoked' AND id != ?", name, exceptId ?? "")[0];
+        if (taken === undefined || taken.n > 0)
+            throw new ConnectionsError("conflict");
+    };
     const grant = (id, agentId) => rows(grantRow, "SELECT * FROM veil_connection_grants WHERE connectionId = ? AND agentId = ?", id, agentId)[0];
     const address = (row) => ({
         ownerId,
@@ -127,30 +104,18 @@ export function createConnections(options) {
         }
         return url.href;
     };
-    const sweep = () => Effect.gen(function* () {
-        const due = yield* sync(() => rows(cleanupRow, "SELECT * FROM veil_connection_cleanup WHERE attempts < ?", cleanupLimit));
-        for (const job of due) {
-            const outcome = yield* options.custody
-                .remove({
-                ownerId,
-                connectionId: job.connectionId,
-                credential: job.credential,
-            }, job.locator)
-                .pipe(Effect.result);
-            yield* sync(() => {
-                if (outcome._tag === "Success")
-                    sql.exec("DELETE FROM veil_connection_cleanup WHERE id = ?", job.id);
-                else
-                    sql.exec("UPDATE veil_connection_cleanup SET attempts = attempts + 1 WHERE id = ?", job.id);
-            });
-        }
+    const { cleanupPending, sweep, enqueueLocator, enqueueCleanup, markReconnect, retireAttempt, } = createCleanup({
+        ownerId,
+        custody: options.custody,
+        clock: options.clock,
+        sql,
+        transactionSync,
+        rows,
+        bump,
     });
-    const enqueueCleanup = (row) => {
-        if (row.locator !== null)
-            sql.exec("INSERT INTO veil_connection_cleanup (connectionId, locator, credential, attempts) VALUES (?, ?, ?, 0)", row.id, row.locator, JSON.stringify(row.credential));
-    };
     const fingerprint = (draft) => JSON.stringify([
         draft.name,
+        draft.label ?? null,
         draft.surface.kind,
         "url" in draft.surface ? draft.surface.url : draft.surface.baseUrl,
         draft.credential,
@@ -160,9 +125,27 @@ export function createConnections(options) {
         const draft = yield* sync(() => {
             authorize(actor, "manage");
             const parsed = decode(draftSchema, input);
-            if (parsed.credential.kind === "static"
-                ? parsed.secret === undefined
-                : parsed.secret !== undefined)
+            const wantsSecret = parsed.credential.kind === "static"
+                ? "required"
+                : parsed.credential.kind === "oauth"
+                    ? "client"
+                    : "never";
+            if ((wantsSecret === "required" && parsed.secret === undefined) ||
+                (wantsSecret === "never" && parsed.secret !== undefined) ||
+                (parsed.credential.kind === "oauth" &&
+                    // An MCP server signs in at itself; a REST connection through a
+                    // provider the operator registered, with the operator's client; or
+                    // a custodian that runs the authorization (its integration id).
+                    (parsed.credential.provider === undefined
+                        ? parsed.surface.kind !== "mcp" ||
+                            (parsed.secret !== undefined &&
+                                parsed.credential.clientId === undefined)
+                        : parsed.secret !== undefined ||
+                            parsed.credential.clientId !== undefined ||
+                            (options.oauth?.providers?.[parsed.credential.provider] ===
+                                undefined
+                                ? options.custody.connect === undefined
+                                : parsed.surface.kind !== "openapi"))))
                 throw new ConnectionsError("invalid_input");
             return parsed;
         });
@@ -172,17 +155,33 @@ export function createConnections(options) {
                 return null;
             if (receipt.fingerprint !== fingerprint(draft))
                 throw new ConnectionsError("conflict");
-            return receipt.result.connectionId;
+            return receipt.result;
         });
         if (replay !== null)
-            return { connectionId: replay, authorizeUrl: null };
+            return {
+                connectionId: replay.connectionId,
+                authorizeUrl: replay.authorizeUrl ?? null,
+            };
+        yield* sync(() => {
+            assertNameFree(draft.name, null);
+        });
         const endpoint = yield* sync(() => publicUrl(draft.surface.kind === "mcp"
             ? draft.surface.url
             : draft.surface.baseUrl));
         const surface = draft.surface;
-        const table = surface.kind === "openapi"
-            ? (yield* io(() => parseOpenApiTable(surface.table))).operations
+        const decoded = surface.kind === "openapi"
+            ? yield* io(() => decodeTable(surface.table))
             : null;
+        if (draft.credential.kind === "oauth") {
+            const table = decoded === null
+                ? null
+                : { table: decoded.operations, digest: decoded.digest };
+            const viaCustodian = draft.credential.provider !== undefined &&
+                options.oauth?.providers?.[draft.credential.provider] === undefined;
+            return yield* viaCustodian
+                ? oauthFlow.beginCustody(actor, draft, draft.credential, endpoint, fingerprint(draft), table)
+                : oauthFlow.begin(actor, draft, draft.credential, endpoint, fingerprint(draft), table);
+        }
         const connectionId = options.ids();
         const state = options.ids();
         yield* sync(() => {
@@ -200,18 +199,22 @@ export function createConnections(options) {
             locator,
             state: "active",
             authorityVersion: 1,
+            version: 1,
             surface: {
                 kind: draft.surface.kind,
                 url: endpoint,
-                table,
+                table: decoded?.operations ?? null,
+                digest: decoded?.digest ?? null,
+                label: draft.label ?? draft.name,
             },
         };
         return yield* sync(() => transactionSync(() => {
             authorize(actor, "manage");
+            assertNameFree(stored.name, null);
             const attempt = rows(count, "SELECT COUNT(*) AS n FROM veil_connection_attempts WHERE state = ? AND status = 'pending' AND expiresAt > ?", state, options.clock())[0];
             if (attempt?.n !== 1)
                 throw new ConnectionsError("denied");
-            sql.exec("INSERT INTO veil_connections VALUES (?, ?, ?, ?, ?, 'active', 1)", stored.id, stored.name, JSON.stringify(stored.surface), JSON.stringify(stored.credential), stored.locator);
+            sql.exec("INSERT INTO veil_connections VALUES (?, ?, ?, ?, ?, 'active', 1, 1)", stored.id, stored.name, JSON.stringify(stored.surface), JSON.stringify(stored.credential), stored.locator);
             sql.exec("UPDATE veil_connection_attempts SET status = 'completed' WHERE state = ?", state);
             sql.exec("INSERT INTO veil_connection_receipts VALUES (?, ?, ?)", draft.requestId, fingerprint(draft), JSON.stringify({ connectionId }));
             bump();
@@ -220,15 +223,113 @@ export function createConnections(options) {
             enqueueCleanup(stored);
         })));
     });
+    const oauthStore = {
+        connection,
+        recordPending: (input) => {
+            transactionSync(() => {
+                authorize(input.actor, "manage");
+                const stored = input.connection;
+                assertNameFree(stored.name, null);
+                sql.exec("INSERT INTO veil_connections VALUES (?, ?, ?, ?, NULL, 'pending', 1, 1)", stored.id, stored.name, JSON.stringify(stored.surface), JSON.stringify(stored.credential));
+                sql.exec("INSERT INTO veil_connection_attempts VALUES (?, ?, ?, 'pending', ?, ?, ?)", input.state, stored.id, input.actor, options.clock() + attemptTtlMs, input.attemptLocator, input.issuer);
+                sql.exec("INSERT INTO veil_connection_receipts VALUES (?, ?, ?)", input.requestId, input.fingerprint, JSON.stringify({
+                    connectionId: stored.id,
+                    authorizeUrl: input.authorizeUrl,
+                }));
+                bump();
+            });
+        },
+        claimCustody: (state) => transactionSync(() => {
+            if (!state.startsWith(`${ownerId}.`))
+                throw new ConnectionsError("denied");
+            const attempt = rows(attemptRow, "SELECT * FROM veil_connection_attempts WHERE state = ?", state)[0];
+            // A browser attempt holds a sealed verifier; only a custodian's has none.
+            if (attempt?.status !== "pending" ||
+                attempt.pkceVerifierSealed !== null)
+                throw new ConnectionsError("denied");
+            if (attempt.expiresAt <= options.clock()) {
+                retireAttempt(attempt, "expired");
+                return { attempt, expired: true };
+            }
+            sql.exec("UPDATE veil_connection_attempts SET status = 'consumed' WHERE state = ?", state);
+            return { attempt, expired: false };
+        }),
+        claim: (actor, input) => transactionSync(() => {
+            authorize(actor, "manage");
+            const wanted = decode(completeInputSchema, input);
+            if (!wanted.state.startsWith(`${ownerId}.`))
+                throw new ConnectionsError("denied");
+            const attempt = rows(attemptRow, "SELECT * FROM veil_connection_attempts WHERE state = ?", wanted.state)[0];
+            if (attempt?.status !== "pending" ||
+                attempt.actor !== actor ||
+                attempt.pkceVerifierSealed === null)
+                throw new ConnectionsError("denied");
+            if (attempt.expiresAt <= options.clock()) {
+                retireAttempt(attempt, "expired");
+                return { attempt, wanted, expired: true };
+            }
+            sql.exec("UPDATE veil_connection_attempts SET status = 'consumed' WHERE state = ?", attempt.state);
+            return { attempt, wanted, expired: false };
+        }),
+        fail: (attempt) => {
+            transactionSync(() => {
+                retireAttempt(attempt, "failed");
+            });
+        },
+        activate: (row, attempt, locator) => transactionSync(() => {
+            const current = connection(row.id);
+            if (current.state !== "pending")
+                return false;
+            sql.exec("UPDATE veil_connections SET state = 'active', locator = ?, authorityVersion = authorityVersion + 1 WHERE id = ?", locator, row.id);
+            sql.exec("UPDATE veil_connection_attempts SET status = 'completed', pkceVerifierSealed = NULL WHERE state = ?", attempt.state);
+            if (attempt.pkceVerifierSealed !== null)
+                enqueueLocator(row.id, attempt.pkceVerifierSealed, row.credential);
+            bump();
+            return true;
+        }),
+        discard: (connectionId, locator, credential) => {
+            transactionSync(() => {
+                enqueueLocator(connectionId, locator, credential);
+            });
+        },
+        swap: (row, held, locator) => transactionSync(() => {
+            const current = connection(row.id);
+            if (current.state !== "active" || current.locator !== held)
+                return current.state;
+            sql.exec("UPDATE veil_connections SET locator = ? WHERE id = ?", locator, row.id);
+            enqueueLocator(row.id, held, row.credential);
+            return "applied";
+        }),
+        clientLocator: (issuer) => rows(registryRow, "SELECT locator FROM veil_oauth_clients WHERE issuer = ?", issuer)[0]?.locator,
+        saveClientLocator: (issuer, locator) => {
+            transactionSync(() => {
+                const old = rows(registryRow, "SELECT locator FROM veil_oauth_clients WHERE issuer = ?", issuer)[0];
+                sql.exec("INSERT OR REPLACE INTO veil_oauth_clients VALUES (?, ?)", issuer, locator);
+                if (old !== undefined)
+                    enqueueLocator("oauth-clients", old.locator, { kind: "oauth" });
+            });
+        },
+    };
+    const oauthFlow = createOAuthFlow({
+        ownerId,
+        custody: options.custody,
+        oauth: options.oauth,
+        clock: options.clock,
+        ids: options.ids,
+        policy,
+        store: oauthStore,
+        sweep,
+    });
     const grantTo = (actor, input) => sync(() => transactionSync(() => {
         authorize(actor, "manage");
         const wanted = decode(grantInputSchema, input);
         const row = connection(wanted.connectionId);
         if (row.state === "revoked")
             throw new ConnectionsError("revoked");
-        if (wanted.tools === "all"
-            ? false
-            : row.surface.kind !== "mcp" && wanted.tools.length === 0)
+        if (wanted.tools !== "all" &&
+            (Array.isArray(wanted.tools)
+                ? row.surface.kind !== "mcp" && wanted.tools.length === 0
+                : row.surface.kind !== "openapi"))
             throw new ConnectionsError("invalid_input");
         const tools = JSON.stringify(wanted.tools);
         const existing = grant(wanted.connectionId, wanted.agentId);
@@ -258,6 +359,8 @@ export function createConnections(options) {
                 const row = connection(decode(identifier, input.connectionId));
                 if (row.state === "revoked")
                     return;
+                for (const attempt of rows(attemptRow, "SELECT * FROM veil_connection_attempts WHERE connectionId = ? AND status IN ('pending', 'consumed')", row.id))
+                    retireAttempt(attempt, "revoked");
                 sql.exec("UPDATE veil_connections SET state = 'revoked', locator = NULL, authorityVersion = authorityVersion + 1 WHERE id = ?", row.id);
                 sql.exec("UPDATE veil_connection_grants SET active = 0, version = version + 1 WHERE connectionId = ? AND active = 1", row.id);
                 enqueueCleanup(row);
@@ -280,19 +383,22 @@ export function createConnections(options) {
         });
         const connections = [];
         for (const { g, row } of stored.granted) {
-            const surface = row.surface.kind === "mcp"
-                ? { kind: "mcp", url: row.surface.url }
-                : {
+            let surface = { kind: "mcp", url: row.surface.url };
+            if (row.surface.kind === "openapi") {
+                const decoded = yield* io(() => decodeTable(row.surface.table));
+                surface = {
                     kind: "openapi",
                     baseUrl: row.surface.url,
-                    table: (yield* io(() => parseOpenApiTable(row.surface.table)))
-                        .operations,
+                    table: decoded.operations,
+                    digest: decoded.digest,
                 };
+            }
             connections.push({
                 connectionId: row.id,
                 name: row.name,
                 surface,
                 tools: g.tools,
+                version: row.version,
                 authorityVersion: row.authorityVersion,
                 grantVersion: g.version,
             });
@@ -307,17 +413,23 @@ export function createConnections(options) {
         return rows(connectionRow, "SELECT * FROM veil_connections ORDER BY id").map((row) => ({
             connectionId: row.id,
             name: row.name,
+            label: row.surface.label ?? row.name,
             surface: {
                 kind: row.surface.kind,
                 origin: new URL(row.surface.url).origin,
+                url: row.surface.url,
+                digest: row.surface.digest ?? null,
             },
             credentialKind: row.credential.kind,
+            credential: row.credential,
             state: row.state,
+            version: row.version,
             authorityVersion: row.authorityVersion,
             grants: rows(grantRow, "SELECT * FROM veil_connection_grants WHERE connectionId = ? AND active = 1", row.id).map((g) => ({
                 agentId: g.agentId,
                 tools: g.tools,
                 version: g.version,
+                grantor: g.grantor,
             })),
         }));
     });
@@ -330,43 +442,190 @@ export function createConnections(options) {
             held?.active !== 1 ||
             held.version !== ref.grantVersion)
             throw new ConnectionsError("revoked");
+        if (row.state === "pending")
+            throw new ConnectionsError("pending");
         if (row.state === "reconnect_required")
             throw new ConnectionsError("reconnect_required");
         authorize(held.grantor, "grantor");
-        return { row, tools: held.tools };
+        return { row, tools: held.tools, grantor: held.grantor, agentId };
     };
+    /**
+     * One request through every gate: the grant, the host's last live check, the
+     * credential at the owner, and the grant again on the way back.
+     */
+    const deliver = (admit, prepare) => Effect.gen(function* () {
+        const { row, tools, grantor, agentId } = yield* sync(admit);
+        const { request, operation } = yield* prepare(row, tools);
+        const verdict = options.check;
+        if (verdict !== undefined &&
+            !(yield* io(() => verdict(grantor, { agentId, connectionId: row.id, tools }, operation))))
+            return yield* Effect.fail(new ConnectionsError("denied"));
+        yield* sync(admit);
+        if (row.locator === null && row.credential.kind === "static")
+            return yield* Effect.fail(new ConnectionsError("denied"));
+        const response = yield* // A custodian that runs the sign-in refreshes the token itself.
+         (row.credential.kind === "oauth" && options.custody.open !== undefined
+            ? oauthFlow.send(row, request)
+            : options.custody.inject(address(row), row.locator ?? "", request)).pipe(Effect.tapError((error) => error.code === "reconnect_required"
+            ? sync(() => {
+                markReconnect(row.id);
+            })
+            : Effect.void));
+        const stillCurrent = yield* sync(admit).pipe(Effect.result);
+        if (stillCurrent._tag === "Failure" ||
+            response.redirected ||
+            (response.status >= 300 && response.status < 400)) {
+            yield* io(() => response.body?.cancel() ?? Promise.resolve());
+            return yield* Effect.fail(stillCurrent._tag === "Failure"
+                ? stillCurrent.failure
+                : new ConnectionsError("invalid_response"));
+        }
+        return response;
+    });
+    const fetchThrough = (admit, target, init) => Effect.runPromise(deliver(admit, (row, tools) => row.surface.kind === "openapi" && tools !== "all"
+        ? // Effect and name grants are enforced per operation, by `call`.
+            Effect.fail(new ConnectionsError("denied"))
+        : io(() => admitRequest({ kind: row.surface.kind, url: row.surface.url }, tools, new Request(target, init), policy)).pipe(Effect.map((request) => ({ request, operation: null })))));
     const egress = (agentId, input) => {
         const ref = decode(egressRefSchema, input);
-        return (target, init) => Effect.runPromise(Effect.gen(function* () {
-            const { row, tools } = yield* sync(() => admitted(agentId, ref));
-            const request = yield* io(() => admitRequest({ kind: row.surface.kind, url: row.surface.url }, tools, new Request(target, init), policy));
-            if (row.locator === null && row.credential.kind === "static")
+        return (target, init) => fetchThrough(() => admitted(agentId, ref), target, init);
+    };
+    /** A typed OpenAPI operation: built from the stored table, checked against its stored schemas. */
+    const callThrough = (admit, raw) => Effect.gen(function* () {
+        const wanted = yield* sync(() => decode(callInputSchema, raw));
+        let chosen;
+        const response = yield* deliver(admit, (row, tools) => Effect.gen(function* () {
+            if (row.surface.kind !== "openapi")
+                return yield* Effect.fail(new ConnectionsError("unsupported"));
+            const table = yield* io(() => decodeTable(row.surface.table));
+            chosen = table.operations.find((candidate) => candidate.name === wanted.operation);
+            if (chosen === undefined || !admits(tools, chosen))
                 return yield* Effect.fail(new ConnectionsError("denied"));
-            const response = yield* options.custody
-                .inject(address(row), row.locator ?? "", request)
-                .pipe(Effect.tapError((error) => error.code === "reconnect_required"
-                ? sync(() => sql.exec("UPDATE veil_connections SET state = 'reconnect_required', authorityVersion = authorityVersion + 1 WHERE id = ? AND state = 'active'", row.id))
-                : Effect.void));
-            const stillCurrent = yield* sync(() => admitted(agentId, ref)).pipe(Effect.result);
-            if (stillCurrent._tag === "Failure" ||
-                response.redirected ||
-                (response.status >= 300 && response.status < 400)) {
-                yield* io(() => response.body?.cancel() ?? Promise.resolve());
-                return yield* Effect.fail(stillCurrent._tag === "Failure"
-                    ? stillCurrent.failure
-                    : new ConnectionsError("invalid_response"));
-            }
-            return response;
+            const picked = chosen;
+            const built = yield* io(() => operationRequest(row.surface.url, picked, wanted.input));
+            const request = yield* io(() => admitRequest({ kind: "openapi", url: row.surface.url }, "all", built, policy));
+            return {
+                request,
+                operation: { name: picked.name, effect: picked.effect },
+            };
         }));
+        const operation = chosen;
+        if (operation === undefined)
+            return yield* Effect.fail(new ConnectionsError("denied"));
+        const text = yield* io(() => boundedText(response));
+        // A grant ended while the body streamed: nothing read may be returned.
+        yield* sync(admit);
+        if (!response.ok)
+            return yield* Effect.fail(new ConnectionsError("invalid_response"));
+        return yield* io(() => operationOutput(operation, text));
+    });
+    const call = (agentId, input, raw) => {
+        const ref = decode(egressRefSchema, input);
+        return callThrough(() => admitted(agentId, ref), raw);
+    };
+    /** The owner as sender: no Agent grant, and a version they last saw, when they name one. */
+    const ownerAdmit = (actor, connectionId, expectedVersion) => {
+        authorize(actor, "manage");
+        const row = connection(connectionId);
+        if (row.state === "revoked")
+            throw new ConnectionsError("revoked");
+        if (expectedVersion !== null && row.version !== expectedVersion)
+            throw new ConnectionsError("conflict");
+        if (row.state !== "active")
+            throw new ConnectionsError("pending");
+        return {
+            row,
+            tools: "all",
+            grantor: actor,
+            agentId: `owner:${actor}`,
+        };
     };
+    const ownerCall = (actor, at, raw) => callThrough(() => ownerAdmit(actor, at.connectionId, at.expectedVersion), raw);
+    /** The owner's own raw fetch to one connection, through the same gates. */
+    const ownerFetch = (actor, connectionId) => (target, init) => fetchThrough(() => ownerAdmit(actor, connectionId, null), target, init);
+    /** The tools an MCP connection offers, listed by its owner. */
+    const tools = (actor, connectionId) => Effect.gen(function* () {
+        const row = yield* sync(() => {
+            authorize(actor, "manage");
+            return connection(connectionId);
+        });
+        if (row.surface.kind !== "mcp")
+            return yield* Effect.fail(new ConnectionsError("unsupported"));
+        return yield* io(() => listMcpTools(row.surface.url, ownerFetch(actor, connectionId)));
+    });
+    /** The decoded operations of one OpenAPI connection, for its owner. */
+    const operations = (actor, id) => Effect.gen(function* () {
+        const row = yield* sync(() => {
+            authorize(actor, "manage");
+            return connection(id);
+        });
+        if (row.surface.kind !== "openapi")
+            return yield* Effect.fail(new ConnectionsError("unsupported"));
+        return yield* io(() => decodeTable(row.surface.table));
+    });
+    const update = createUpdate({
+        ownerId,
+        custody: options.custody,
+        store: {
+            authorize: (actor) => {
+                authorize(actor, "manage");
+            },
+            connection,
+            receipt: (requestId) => {
+                const found = rows(receiptRow, "SELECT fingerprint, result FROM veil_connection_receipts WHERE requestId = ?", requestId)[0];
+                return found === undefined
+                    ? null
+                    : {
+                        stamp: found.fingerprint,
+                        connectionId: found.result.connectionId,
+                        version: found.result.version ?? 0,
+                    };
+            },
+            checkName: assertNameFree,
+            publicUrl,
+            commit: ({ actor, update: input, stamp, row, ...next }) => transactionSync(() => {
+                authorize(actor, "manage");
+                const current = connection(row.id);
+                if (current.version !== input.expectedVersion ||
+                    current.state !== row.state)
+                    throw new ConnectionsError("conflict");
+                if (input.name !== undefined)
+                    assertNameFree(input.name, row.id);
+                const version = current.version + 1;
+                sql.exec("UPDATE veil_connections SET name = ?, surface = ?, credential = ?, locator = ?, version = ?, authorityVersion = authorityVersion + 1 WHERE id = ?", input.name ?? current.name, JSON.stringify({
+                    ...current.surface,
+                    url: next.baseUrl,
+                    table: next.table,
+                    digest: next.digest,
+                    label: input.label ?? current.surface.label ?? current.name,
+                }), JSON.stringify(next.credential), next.locator, version, row.id);
+                if (input.secret !== undefined && row.locator !== null)
+                    enqueueLocator(row.id, row.locator, row.credential);
+                sql.exec("INSERT INTO veil_connection_receipts VALUES (?, ?, ?)", input.requestId, stamp, JSON.stringify({ connectionId: row.id, version }));
+                bump();
+                return { connectionId: row.id, version };
+            }),
+            discard: (connectionId, locator, credential) => {
+                enqueueLocator(connectionId, locator, credential);
+            },
+        },
+    });
     return {
         begin,
+        complete: oauthFlow.complete,
+        completeCustody: oauthFlow.completeCustody,
         grant: grantTo,
         ungrant,
         revoke,
         projection,
         list,
         egress,
+        call,
+        ownerCall,
+        tools,
+        operations,
+        update,
         sweep,
+        cleanupPending,
     };
 }

package/dist/connections/discover.d.ts

@@ -0,0 +1,3 @@
+import type { NarrowFetch } from "./contract.js";
+/** The tool names an MCP server offers, listed with the maintained SDK client. */
+export declare function listMcpTools(url: string, fetch: NarrowFetch): Promise<readonly string[]>;

package/dist/connections/discover.js

@@ -0,0 +1,23 @@
+const toolLimit = 1_024;
+/** The tool names an MCP server offers, listed with the maintained SDK client. */
+export async function listMcpTools(url, fetch) {
+    const sdk = await import("@modelcontextprotocol/client");
+    const client = new sdk.Client({ name: "fungi-connections", version: "1" });
+    await client.connect(new sdk.StreamableHTTPClientTransport(new URL(url), {
+        fetch,
+        requestInit: { redirect: "error" },
+    }));
+    try {
+        const names = [];
+        let cursor;
+        do {
+            const page = await client.listTools(cursor === undefined ? undefined : { cursor });
+            names.push(...page.tools.map((tool) => tool.name));
+            cursor = page.nextCursor;
+        } while (cursor !== undefined && names.length < toolLimit);
+        return names.slice(0, toolLimit);
+    }
+    finally {
+        await client.close();
+    }
+}