@fungi.computer/veil 0.4.0 → 0.6.0

package/README.md

@@ -1,69 +1,63 @@
 # Veil (`@fungi.computer/veil`)
 
-This package keeps provider credentials behind trusted Team doors. It owns
-GitHub Connection custody, model-key grants and the Agent's anonymous public-web
-fetch. A guest receives an authorized operation, not the provider token or its
-private locator.
+This package keeps provider credentials behind trusted owner doors. It owns the
+shared connections core (MCP, OpenAPI and a repository's git endpoint),
+model-key grants and the Agent's anonymous public-web fetch. A guest receives an
+authorized operation, not the provider token or its private locator.
 
 ## Set up and check
 
-The host supplies Team Connection authority and a `CredentialCustodian` to
-`createGitHubConnections`. Model input cannot select a repository or private
-locator. The `@fungi.computer/veil/nango` adapter needs a configured Nango
-origin, API key, webhook signing key, integration ID and public Connect URLs;
-these are host secrets or configuration, never browser or model input. Without
-custody configuration, report unavailable rather than manufacturing a
-connection.
+The host supplies the owner's SQLite, a `CustodyAdapter` and its live
+authorization to `createConnections` (`@fungi.computer/veil/connections`).
+Custody is `sealed` by default; Nango is the optional adapter
+(`@fungi.computer/veil/connections/nango`). Model input cannot choose a
+connection, repository or private locator. Without custody configuration, report
+unavailable rather than manufacturing a connection.
 
 Run `pnpm --filter @fungi.computer/veil test` for the package's synthetic
-custody, signed-webhook and public-fetch checks. For an exercised connection
-lifecycle, start with `test/nango-git.test.ts`; a unit test does not prove a
+custody, signed-webhook and public-fetch checks. A unit test does not prove a
 live Nango service or provider account.
 
-The root export in `src/index.ts` defines Team Connection receipts and
-`createGitHubConnections`. `package.json` lists the Nango, model-key and
-public-fetch subpaths used by trusted hosts; do not import private locators from
-these modules into guest code.
+GitHub REST is an ordinary `openapi` connection with an `oauth` credential:
+through an operator-registered provider on either custody adapter, or through a
+Nango integration. A custodian-run integration is pinned by the host
+(`configuredCustodyIntegrations`) to one surface kind and one origin, and the
+core refuses it at `begin` and again before every send, so the credential Nango
+holds never goes anywhere else. GitHub REST is pinned to `api.github.com`.
+
+A Computer's git is not a connection in this core.
+`@fungi.computer/veil/github-app` wraps Nango's `github-app` integration
+(`NANGO_GITHUB_APP_INTEGRATION_ID`, never the same as
+`NANGO_GITHUB_INTEGRATION_ID`): it opens the installation consent, verifies the
+signed completion, finds a lost one, deletes a connection and reads the current
+installation token. The Hub places that token on a request to `github.com` and
+nowhere else.
 
 ## Nango adapter
 
-`@fungi.computer/veil/nango` exports `createNangoCustodian`. The trusted host
-supplies a Nango server origin, API key, separate webhook signing key, one
-integration ID, and the public Connect UI base and public API URL. These are
-host configuration, never browser or model input. `openSession` returns the
-Connect document browsers open: Nango's issued link, confined to the configured
-Connect UI and pinned to the public API with `apiURL`. Unconfigured hosts must
-report unavailable instead of substituting fake custody.
-
-The adapter uses `@nangohq/node@0.71.6` to verify the raw callback body and
-ordinary `fetch` with each invocation's AbortSignal for REST operations. It does
-not call credential-returning connection inspection. Connect sessions carry
-Team-created attempt/principal/Team tags and restrict the integration. Signed
-webhooks are verified before decoding; the adapter handles only a successful
-`creation` and a failed `refresh` (reconnect evidence) and refuses every other
-operation as `unsupported`. It also checks end-user and organization
-correlation; Team owns final activation and replay decisions. A verified
-completion the Team refuses (late, unknown, superseded, or failing activation)
-is deleted from custody, and the settled deletion is recorded.
-
-Reconciliation queries `/connections` with exact integration, end-user,
-organization and attempt tags and a limit of two. The selected server filters
-before applying that limit: zero matches remain unresolved, multiple matches are
-ambiguous, and every returned row is checked again before a single completion is
-accepted. It never selects the first candidate from an arbitrary page.
-
-The pinned public deletion endpoint returns `200 {success:true}` after deletion
-and `400 {error:{code:"unknown_connection"}}` when the selected connection is
-absent. Other responses, including generic 404 and `success:false`, do not
-settle cleanup. This mapping is specific to the selected server implementation,
-not a generic Nango error policy. Provider/proxy failures stay unavailable,
-except a proxied provider `401` carrying GitHub's own error body, which marks
-the Connection reconnect-required; Nango's own `401` envelope stays unavailable.
-
-The one proxy operation is `GET /proxy/repos/{owner}/{name}` with private Nango
-connection/integration headers. Veil's existing caller decodes credential-free
-metadata and verifies the repository ID. Cancellation stops waiting through the
-maintained transport; it does not prove upstream work stopped or rolled back.
+`createNangoCustody` takes a Nango server origin, API key, a separate webhook
+signing key, one API-key integration for pasted credentials, and the public
+Connect UI base and public API URL. These are host configuration, never browser
+or model input. `connect` returns the Connect document browsers open: Nango's
+issued link, confined to the configured Connect UI and pinned to the public API
+with `apiURL`. `verifyCompletion` verifies the raw callback body with
+`@nangohq/node` before decoding it, and the core settles only an attempt the
+owner began. Unconfigured hosts must report unavailable instead of substituting
+fake custody.
+
+`inject` sends through Nango's proxy, which attaches and refreshes the
+credential; the pinned deletion endpoint returns `200 {success:true}` after
+deletion and `400 {error:{code:"unknown_connection"}}` when the connection is
+absent, and only those settle cleanup. A proxy `404` is the custodian no longer
+holding the connection and marks it reconnect-required. `find` asks Nango for
+the one connection that carries an attempt's state, actor and Team, so a sign-in
+whose signed completion was lost still settles. Cancellation stops the caller
+waiting; it does not prove upstream work stopped or rolled back.
+
+`configuredComputerGitIntegration(env)` names the integration through which a
+Computer's git signs in (`NANGO_GITHUB_APP_INTEGRATION_ID`);
+`NANGO_GITHUB_INTEGRATION_ID` joins the integrations an owner may sign in
+through for REST connections.
 
 ## Public-web door
 

package/dist/best-effort-cleanup.d.ts

@@ -1,2 +1,2 @@
 /** Report cleanup failures without exposing provider or transport details. */
-export declare function bestEffortCleanup(operation: "nango-git-response-body" | "public-fetch-socket", cleanup: () => Promise<void>): Promise<void>;
+export declare function bestEffortCleanup(operation: "public-fetch-socket", cleanup: () => Promise<void>): Promise<void>;

package/dist/connections/cleanup.d.ts

@@ -0,0 +1,21 @@
+import * as Effect from "effect/Effect";
+import type * as Schema from "effect/Schema";
+import type { ConnectionsOptions } from "./contract.js";
+import { type AttemptRow, type ConnectionRow } from "./internal.js";
+/** The cleanup outbox, attempt retirement and reconnect marking over the owner's SQLite. */
+export declare function createCleanup(deps: {
+    ownerId: string;
+    custody: ConnectionsOptions["custody"];
+    clock: () => number;
+    sql: ConnectionsOptions["store"]["sql"];
+    transactionSync: <A>(body: () => A) => A;
+    rows: <S extends Schema.Decoder<unknown>>(schema: S, statement: string, ...bindings: (string | number | null)[]) => S["Type"][];
+    bump: () => void;
+}): {
+    cleanupPending: () => number;
+    sweep: () => Effect.Effect<void, import("./contract.js").ConnectionsError, never>;
+    enqueueLocator: (connectionId: string, locator: string, credential: ConnectionRow["credential"]) => void;
+    enqueueCleanup: (row: ConnectionRow) => void;
+    markReconnect: (id: string) => void;
+    retireAttempt: (attempt: AttemptRow, status: string) => void;
+};

package/dist/connections/cleanup.js

@@ -0,0 +1,66 @@
+import * as Effect from "effect/Effect";
+import { attemptRow, cleanupRow, connectionRow, count, sync, } from "./internal.js";
+const cleanupLimit = 5;
+/** The cleanup outbox, attempt retirement and reconnect marking over the owner's SQLite. */
+export function createCleanup(deps) {
+    const { sql, rows, bump, transactionSync } = deps;
+    /** Sealed credentials still waiting to be deleted; hosts wake their alarm while this is positive. */
+    const cleanupPending = () => rows(count, "SELECT COUNT(*) AS n FROM veil_connection_cleanup WHERE attempts < ?", cleanupLimit)[0]?.n ?? 0;
+    const sweep = () => Effect.gen(function* () {
+        yield* sync(expireAttempts);
+        const due = yield* sync(() => rows(cleanupRow, "SELECT * FROM veil_connection_cleanup WHERE attempts < ?", cleanupLimit));
+        for (const job of due) {
+            const outcome = yield* deps.custody
+                .remove({
+                ownerId: deps.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 enqueueLocator = (connectionId, locator, credential) => {
+        sql.exec("INSERT INTO veil_connection_cleanup (connectionId, locator, credential, attempts) VALUES (?, ?, ?, 0)", connectionId, locator, JSON.stringify(credential));
+    };
+    const enqueueCleanup = (row) => {
+        if (row.locator !== null)
+            enqueueLocator(row.id, row.locator, row.credential);
+    };
+    const markReconnect = (id) => {
+        sql.exec("UPDATE veil_connections SET state = 'reconnect_required', authorityVersion = authorityVersion + 1 WHERE id = ? AND state = 'active'", id);
+        bump();
+    };
+    /** An attempt ends: its sealed verifier goes to cleanup and a still-pending connection is withdrawn. */
+    const retireAttempt = (attempt, status) => {
+        sql.exec("UPDATE veil_connection_attempts SET status = ?, pkceVerifierSealed = NULL WHERE state = ?", status, attempt.state);
+        const row = rows(connectionRow, "SELECT * FROM veil_connections WHERE id = ?", attempt.connectionId)[0];
+        if (row === undefined)
+            return;
+        if (attempt.pkceVerifierSealed !== null)
+            enqueueLocator(row.id, attempt.pkceVerifierSealed, row.credential);
+        if (row.state === "pending") {
+            sql.exec("UPDATE veil_connections SET state = 'revoked', authorityVersion = authorityVersion + 1 WHERE id = ?", row.id);
+            bump();
+        }
+    };
+    const expireAttempts = () => {
+        transactionSync(() => {
+            for (const attempt of rows(attemptRow, "SELECT * FROM veil_connection_attempts WHERE status IN ('pending', 'consumed') AND expiresAt <= ?", deps.clock()))
+                retireAttempt(attempt, "expired");
+        });
+    };
+    return {
+        cleanupPending,
+        sweep,
+        enqueueLocator,
+        enqueueCleanup,
+        markReconnect,
+        retireAttempt,
+    };
+}

package/dist/connections/contract.d.ts

@@ -1,13 +1,17 @@
 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";
+export type ConnectionsRefusal = "invalid_input" | "denied" | "revoked" | "conflict" | "unsupported" | "too_large" | "reconnect_required" | "pending" | "invalid_response"
+/** The provider's rate limit refused the request; retry later. */
+ | "rate_limited" | "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);
 }
+/** How long a sign-in attempt stays open before it expires. */
+export declare const attemptTtlMs: number;
 export declare const identifier: Schema.String;
 declare const placementSchema: Schema.Union<readonly [Schema.Literal<"bearer">, Schema.Struct<{
     readonly header: Schema.String;
@@ -15,7 +19,11 @@ declare const placementSchema: Schema.Union<readonly [Schema.Literal<"bearer">,
     readonly query: Schema.String;
 }>]>;
 export type Placement = typeof placementSchema.Type;
-/** How the final request is authorized. OAuth joins this union in slice 3. */
+/**
+ * How the final request is authorized. For `oauth` the owner may bring its own
+ * client (`clientId`, with the client secret as the draft's `secret`); without
+ * one the server's dynamic registration is used.
+ */
 export declare const credentialSchema: Schema.Union<readonly [Schema.Struct<{
     readonly kind: Schema.Literal<"none">;
 }>, Schema.Struct<{
@@ -25,6 +33,12 @@ export declare const credentialSchema: Schema.Union<readonly [Schema.Struct<{
     }>, Schema.Struct<{
         readonly query: Schema.String;
     }>]>;
+}>, Schema.Struct<{
+    readonly kind: Schema.Literal<"oauth">;
+    readonly scope: Schema.optional<Schema.String>;
+    readonly clientId: Schema.optional<Schema.String>;
+    /** An operator-registered REST provider; absent for an MCP server's own sign-in. */
+    readonly provider: Schema.optional<Schema.String>;
 }>]>;
 export type Credential = typeof credentialSchema.Type;
 export type SurfaceView = Readonly<{
@@ -33,21 +47,27 @@ export type SurfaceView = Readonly<{
 }> | Readonly<{
     kind: "openapi";
     baseUrl: string;
-    table: unknown;
+    table: readonly unknown[];
+    /** Digest of the decoded operation table. */
+    digest: string;
 }>;
-export declare const toolsSchema: Schema.Union<readonly [Schema.Literal<"all">, Schema.$Array<Schema.String>]>;
+export declare const toolsSchema: Schema.Union<readonly [Schema.Literal<"all">, Schema.Struct<{
+    readonly effect: Schema.Literal<"read">;
+}>, 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;
+    /** Display text for owners; defaults to the name. */
+    readonly label: Schema.optional<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 table: Schema.$Array<Schema.Unknown>;
     }>]>;
     readonly credential: Schema.Union<readonly [Schema.Struct<{
         readonly kind: Schema.Literal<"none">;
@@ -58,6 +78,12 @@ export declare const draftSchema: Schema.Struct<{
         }>, Schema.Struct<{
             readonly query: Schema.String;
         }>]>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"oauth">;
+        readonly scope: Schema.optional<Schema.String>;
+        readonly clientId: Schema.optional<Schema.String>;
+        /** An operator-registered REST provider; absent for an MCP server's own sign-in. */
+        readonly provider: Schema.optional<Schema.String>;
     }>]>;
     readonly secret: Schema.optional<Schema.String>;
 }>;
@@ -65,9 +91,54 @@ 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>]>;
+    readonly tools: Schema.Union<readonly [Schema.Literal<"all">, Schema.Struct<{
+        readonly effect: Schema.Literal<"read">;
+    }>, Schema.$Array<Schema.String>]>;
 }>;
 export type GrantInput = typeof grantInputSchema.Type;
+/** The authorization server's redirect back to the owner. */
+export declare const completeInputSchema: Schema.Struct<{
+    readonly state: Schema.String;
+    readonly code: Schema.String;
+    readonly iss: Schema.optional<Schema.String>;
+}>;
+export type CompleteInput = typeof completeInputSchema.Type;
+/** Owner edits to a live connection, guarded by the version the owner last saw. */
+export declare const updateInputSchema: Schema.Struct<{
+    readonly requestId: Schema.String;
+    readonly connectionId: Schema.String;
+    readonly expectedVersion: Schema.Number;
+    readonly label: Schema.optional<Schema.String>;
+    readonly name: Schema.optional<Schema.String>;
+    /** Replacement OpenAPI operation table, decoded by Forage. */
+    readonly table: Schema.optional<Schema.$Array<Schema.Unknown>>;
+    readonly baseUrl: Schema.optional<Schema.String>;
+    /** Credential swap; `none` and `static` only. */
+    readonly credential: Schema.optional<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;
+        }>]>;
+    }>, Schema.Struct<{
+        readonly kind: Schema.Literal<"oauth">;
+        readonly scope: Schema.optional<Schema.String>;
+        readonly clientId: Schema.optional<Schema.String>;
+        /** An operator-registered REST provider; absent for an MCP server's own sign-in. */
+        readonly provider: Schema.optional<Schema.String>;
+    }>]>>;
+    readonly secret: Schema.optional<Schema.String>;
+}>;
+export type UpdateInput = typeof updateInputSchema.Type;
+/** One typed OpenAPI operation call. */
+export declare const callInputSchema: Schema.Struct<{
+    readonly operation: Schema.String;
+    readonly input: Schema.Unknown;
+}>;
+export type CallInput = typeof callInputSchema.Type;
 export declare const egressRefSchema: Schema.Struct<{
     readonly connectionId: Schema.String;
     readonly grantVersion: Schema.Number;
@@ -87,6 +158,55 @@ 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>;
+    /**
+     * Release a sealed OAuth bundle to the owner's connections core, which runs
+     * the authorization flow and refreshes tokens. Never reaches an Agent.
+     */
+    open?: (address: CustodyAddress, locator: string) => Effect.Effect<string, ConnectionsError>;
+    /**
+     * A custodian that runs the authorization itself (Nango's Connect) returns
+     * the page to send the owner to; it settles through a signed completion
+     * (`complete`) carrying the `state` given here, not through our callback.
+     */
+    /**
+     * Ask a custodian that ran an authorization whether it finished, when its
+     * signed completion never arrived. Only an exact match of the attempt's
+     * state, actor and integration counts; two matches are ambiguous.
+     */
+    find?: (address: CustodyAddress, attempt: Readonly<{
+        state: string;
+        actor: string;
+        integrationId: string;
+    }>) => Effect.Effect<CustodyLookup, ConnectionsError>;
+    connect?: (address: CustodyAddress, attempt: Readonly<{
+        state: string;
+        actor: string;
+        integrationId: string;
+    }>) => Effect.Effect<Readonly<{
+        connectUrl: string;
+        expiresAt: number;
+    }>, ConnectionsError>;
+}>;
+export type CustodyLookup = Readonly<{
+    status: "unresolved";
+}> | Readonly<{
+    status: "ambiguous";
+}> | Readonly<{
+    status: "found";
+    locator: string;
+}>;
+/**
+ * What a custodian proves after it ran an authorization: the attempt's state
+ * and where it keeps the credential. The host verifies the custodian's
+ * signature before it builds one.
+ */
+export type CustodyCompletion = Readonly<{
+    state: string;
+    locator: string;
+    /** Who the custodian says signed in; it must be who began the attempt. */
+    principalId: string;
+    /** The integration the custodian ran it through; it must be the one the attempt began with. */
+    integrationId: string;
 }>;
 export type SqlValue = string | number | null;
 /** The owner's SQLite in Cloudflare `ctx.storage` shape. */
@@ -98,13 +218,69 @@ export type SqlStore = Readonly<{
     }>;
     transactionSync: <A>(operation: () => A) => A;
 }>;
+/**
+ * A REST provider the operator registered an app with. Such providers publish
+ * no metadata the SDK can discover, and many require a pre-registered client,
+ * so the host names the endpoints and holds the client. Only the operator's
+ * configuration reaches this type; neither an Agent nor an owner supplies one.
+ */
+export type StaticOAuthProvider = Readonly<{
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    /** Scopes requested when the owner names none. */
+    scope?: string;
+    client: {
+        client_id: string;
+        client_secret?: string | undefined;
+    };
+    /** The https origins this provider's API serves; its token goes nowhere else. */
+    apiOrigins: readonly string[];
+}>;
+/**
+ * An integration a custodian runs the sign-in for, as the operator declared
+ * it: the https origins its credential may reach. The custodian attaches the
+ * credential to whatever origin it is handed, so the core pins it here.
+ */
+export type CustodyProvider = Readonly<{
+    apiOrigins: readonly string[];
+}>;
 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;
+    /**
+     * Asked right before every send, with the grantor who stands behind the
+     * grant. The host keeps its own live recheck here (membership, write
+     * rights); the core never learns what the host's policy is.
+     */
+    check?: (grantor: string, grant: Readonly<{
+        agentId: string;
+        connectionId: string;
+        tools: Tools;
+    }>, operation: Readonly<{
+        name: string;
+        effect: "read" | "write" | null;
+    }> | null) => Promise<boolean>;
     egressPolicy?: PublicEgressPolicy;
+    /**
+     * Needed only for `oauth` connections: where the authorization server sends
+     * the owner back, and the checked public transport for discovery, token and
+     * refresh requests. Custody must also implement `open`.
+     */
+    oauth?: Readonly<{
+        callbackUrl: string;
+        fetch: (request: Request) => Promise<Response>;
+        /** REST providers the operator registered an app with, by id. */
+        providers?: Readonly<Record<string, StaticOAuthProvider>>;
+    }> | undefined;
+    /**
+     * Integrations the custodian signs in through, by id. An OAuth provider id
+     * that is neither here nor in `oauth.providers` is refused.
+     */
+    custodyProviders?: Readonly<Record<string, CustodyProvider>> | undefined;
     clock: () => number;
     ids: () => string;
 }>;
@@ -116,6 +292,8 @@ export type ConnectionProjection = Readonly<{
         name: string;
         surface: SurfaceView;
         tools: Tools;
+        /** Bumped by every `update`. */
+        version: number;
         authorityVersion: number;
         grantVersion: number;
     }>[];
@@ -123,17 +301,24 @@ export type ConnectionProjection = Readonly<{
 export type ConnectionView = Readonly<{
     connectionId: string;
     name: string;
+    label: string;
     surface: Readonly<{
         kind: "mcp" | "openapi";
         origin: string;
+        url: string;
+        digest: string | null;
     }>;
     credentialKind: Credential["kind"];
-    state: "active" | "reconnect_required" | "revoked";
+    /** How the secret is placed; the secret itself never appears. */
+    credential: Credential;
+    state: "pending" | "active" | "reconnect_required" | "revoked";
+    version: number;
     authorityVersion: number;
     grants: readonly Readonly<{
         agentId: string;
         tools: Tools;
         version: number;
+        grantor: string;
     }>[];
 }>;
 /** The Agent's narrowed capability: only the owner opens the credential. */

package/dist/connections/contract.js

@@ -9,6 +9,8 @@ export class ConnectionsError extends Error {
         this.code = code;
     }
 }
+/** How long a sign-in attempt stays open before it expires. */
+export const attemptTtlMs = 10 * 60 * 1000;
 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)));
@@ -18,10 +20,21 @@ const placementSchema = Schema.Union([
     Schema.Struct({ header: headerName }),
     Schema.Struct({ query: queryName }),
 ]);
-/** How the final request is authorized. OAuth joins this union in slice 3. */
+/**
+ * How the final request is authorized. For `oauth` the owner may bring its own
+ * client (`clientId`, with the client secret as the draft's `secret`); without
+ * one the server's dynamic registration is used.
+ */
 export const credentialSchema = Schema.Union([
     Schema.Struct({ kind: Schema.Literal("none") }),
     Schema.Struct({ kind: Schema.Literal("static"), placement: placementSchema }),
+    Schema.Struct({
+        kind: Schema.Literal("oauth"),
+        scope: Schema.optional(Schema.String),
+        clientId: Schema.optional(Schema.String),
+        /** An operator-registered REST provider; absent for an MCP server's own sign-in. */
+        provider: Schema.optional(Schema.String),
+    }),
 ]);
 /** What the Agent can call. The OpenAPI table is decoded by Forage before it is stored. */
 const surfaceDraftSchema = Schema.Union([
@@ -29,17 +42,21 @@ const surfaceDraftSchema = Schema.Union([
     Schema.Struct({
         kind: Schema.Literal("openapi"),
         baseUrl: Schema.String,
-        table: Schema.Unknown,
+        table: Schema.Array(Schema.Unknown),
     }),
 ]);
 export const toolsSchema = Schema.Union([
     Schema.Literal("all"),
+    /** OpenAPI only: every operation whose stored effect is `read`. */
+    Schema.Struct({ effect: Schema.Literal("read") }),
     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))),
+    /** Display text for owners; defaults to the name. */
+    label: Schema.optional(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)))),
@@ -49,6 +66,31 @@ export const grantInputSchema = Schema.Struct({
     agentId: identifier,
     tools: toolsSchema,
 });
+/** The authorization server's redirect back to the owner. */
+export const completeInputSchema = Schema.Struct({
+    state: Schema.String.pipe(Schema.check(Schema.isMaxLength(512))),
+    code: Schema.String.pipe(Schema.check(Schema.isMaxLength(4096))),
+    iss: Schema.optional(Schema.String.pipe(Schema.check(Schema.isMaxLength(2048)))),
+});
+/** Owner edits to a live connection, guarded by the version the owner last saw. */
+export const updateInputSchema = Schema.Struct({
+    requestId: identifier,
+    connectionId: identifier,
+    expectedVersion: version,
+    label: Schema.optional(Schema.String.pipe(Schema.check(Schema.isMinLength(1), Schema.isMaxLength(128)))),
+    name: Schema.optional(Schema.String.pipe(Schema.check(Schema.isMinLength(1), Schema.isMaxLength(128)))),
+    /** Replacement OpenAPI operation table, decoded by Forage. */
+    table: Schema.optional(Schema.Array(Schema.Unknown)),
+    baseUrl: Schema.optional(Schema.String),
+    /** Credential swap; `none` and `static` only. */
+    credential: Schema.optional(credentialSchema),
+    secret: Schema.optional(Schema.String.pipe(Schema.check(Schema.isPattern(/^[\x21-\x7e]{1,16384}$/u)))),
+});
+/** One typed OpenAPI operation call. */
+export const callInputSchema = Schema.Struct({
+    operation: Schema.String.pipe(Schema.check(Schema.isMaxLength(256))),
+    input: Schema.Unknown,
+});
 export const egressRefSchema = Schema.Struct({
     connectionId: identifier,
     grantVersion: version,