@fungi.computer/veil 0.5.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/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" | "pending" | "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;
@@ -164,6 +168,16 @@ export type CustodyAdapter = Readonly<{
      * 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;
@@ -173,6 +187,14 @@ export type CustodyAdapter = Readonly<{
         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
@@ -181,6 +203,8 @@ export type CustodyAdapter = Readonly<{
 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;
 }>;
@@ -210,6 +234,16 @@ export type StaticOAuthProvider = Readonly<{
         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;
@@ -242,6 +276,11 @@ export type ConnectionsOptions = Readonly<{
         /** 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;
 }>;

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)));

package/dist/connections/core.d.ts

@@ -5,6 +5,7 @@ export declare function createConnections(options: ConnectionsOptions): {
     begin: (actor: string, input: ConnectionDraft) => Effect.Effect<{
         connectionId: string;
         authorizeUrl: string | null;
+        attemptId: string | null;
     }, ConnectionsError, never>;
     complete: (actor: string, input: import("./contract.js").CompleteInput) => Effect.Effect<{
         connectionId: string;
@@ -95,4 +96,6 @@ export declare function createConnections(options: ConnectionsOptions): {
     }, ConnectionsError, never>;
     sweep: () => Effect.Effect<void, ConnectionsError, never>;
     cleanupPending: () => number;
+    reconcilePending: () => Effect.Effect<string[], ConnectionsError, never>;
+    awaitingCustody: () => number;
 };

package/dist/connections/core.js

@@ -2,7 +2,7 @@ import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import { assertPublicHostName } from "../model-key-network.js";
 import { createPublicEgressPolicy } from "../public-egress-policy.js";
-import { ConnectionsError, callInputSchema, completeInputSchema, draftSchema, egressRefSchema, grantInputSchema, identifier, toolsSchema, } from "./contract.js";
+import { ConnectionsError, attemptTtlMs, 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";
@@ -10,7 +10,6 @@ import { attemptRow, connectionRow, count, decode, io, json, registryRow, sync,
 import { createOAuthFlow } from "./oauth-flow.js";
 import { listMcpTools } from "./discover.js";
 import { createUpdate } from "./update.js";
-const attemptTtlMs = 10 * 60 * 1000;
 const grantRow = Schema.Struct({
     connectionId: identifier,
     agentId: identifier,
@@ -24,6 +23,7 @@ const receiptRow = Schema.Struct({
     result: json(Schema.Struct({
         connectionId: identifier,
         authorizeUrl: Schema.optional(Schema.String),
+        attemptId: Schema.optional(Schema.String),
         version: Schema.optional(Schema.Number),
     })),
 });
@@ -72,6 +72,19 @@ export function createConnections(options) {
             throw new ConnectionsError("denied");
         return row;
     };
+    /** The origins a named provider's credential may reach, or nothing when this host does not hold it. */
+    const providerOrigins = (provider) => options.oauth?.providers?.[provider]?.apiOrigins ??
+        options.custodyProviders?.[provider]?.apiOrigins;
+    const assertProviderOrigin = (credential, target, refusal) => {
+        if (credential.kind !== "oauth" || credential.provider === undefined)
+            return;
+        const origins = providerOrigins(credential.provider);
+        // A provider this host no longer holds must be connected again.
+        if (origins === undefined)
+            throw new ConnectionsError("reconnect_required");
+        if (!origins.includes(new URL(target).origin))
+            throw new ConnectionsError(refusal);
+    };
     /** 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];
@@ -144,7 +157,9 @@ export function createConnections(options) {
                             parsed.credential.clientId !== undefined ||
                             (options.oauth?.providers?.[parsed.credential.provider] ===
                                 undefined
-                                ? options.custody.connect === undefined
+                                ? options.custody.connect === undefined ||
+                                    options.custodyProviders?.[parsed.credential.provider] ===
+                                        undefined
                                 : parsed.surface.kind !== "openapi"))))
                 throw new ConnectionsError("invalid_input");
             return parsed;
@@ -161,13 +176,18 @@ export function createConnections(options) {
             return {
                 connectionId: replay.connectionId,
                 authorizeUrl: replay.authorizeUrl ?? null,
+                attemptId: replay.attemptId ?? null,
             };
         yield* sync(() => {
             assertNameFree(draft.name, null);
         });
-        const endpoint = yield* sync(() => publicUrl(draft.surface.kind === "mcp"
-            ? draft.surface.url
-            : draft.surface.baseUrl));
+        const endpoint = yield* sync(() => publicUrl(draft.surface.kind === "openapi"
+            ? draft.surface.baseUrl
+            : draft.surface.url));
+        // A provider's credential is sent only to the origins its operator declared.
+        yield* sync(() => {
+            assertProviderOrigin(draft.credential, endpoint, "invalid_input");
+        });
         const surface = draft.surface;
         const decoded = surface.kind === "openapi"
             ? yield* io(() => decodeTable(surface.table))
@@ -179,7 +199,7 @@ export function createConnections(options) {
             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.beginCustody(actor, draft, draft.credential, endpoint, fingerprint(draft), table, draft.surface.kind)
                 : oauthFlow.begin(actor, draft, draft.credential, endpoint, fingerprint(draft), table);
         }
         const connectionId = options.ids();
@@ -218,7 +238,7 @@ export function createConnections(options) {
             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();
-            return { connectionId, authorizeUrl: null };
+            return { connectionId, authorizeUrl: null, attemptId: null };
         })).pipe(Effect.tapError(() => sync(() => {
             enqueueCleanup(stored);
         })));
@@ -235,17 +255,19 @@ export function createConnections(options) {
                 sql.exec("INSERT INTO veil_connection_receipts VALUES (?, ?, ?)", input.requestId, input.fingerprint, JSON.stringify({
                     connectionId: stored.id,
                     authorizeUrl: input.authorizeUrl,
+                    attemptId: input.state,
                 }));
                 bump();
             });
         },
-        claimCustody: (state) => transactionSync(() => {
+        claimCustody: (state, principalId) => 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)
+                attempt.pkceVerifierSealed !== null ||
+                attempt.actor !== principalId)
                 throw new ConnectionsError("denied");
             if (attempt.expiresAt <= options.clock()) {
                 retireAttempt(attempt, "expired");
@@ -461,6 +483,9 @@ export function createConnections(options) {
             !(yield* io(() => verdict(grantor, { agentId, connectionId: row.id, tools }, operation))))
             return yield* Effect.fail(new ConnectionsError("denied"));
         yield* sync(admit);
+        yield* sync(() => {
+            assertProviderOrigin(row.credential, request.url, "denied");
+        });
         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.
@@ -482,10 +507,13 @@ export function createConnections(options) {
         }
         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 fetchThrough = (admit, target, init) => Effect.runPromise(deliver(admit, (row, tools) => {
+        const { kind, url } = row.surface;
+        return kind === "openapi" && tools !== "all"
+            ? // Effect and name grants are enforced per operation, by `call`.
+                Effect.fail(new ConnectionsError("denied"))
+            : io(() => admitRequest({ kind, 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) => fetchThrough(() => admitted(agentId, ref), target, init);
@@ -563,6 +591,44 @@ export function createConnections(options) {
             return yield* Effect.fail(new ConnectionsError("unsupported"));
         return yield* io(() => decodeTable(row.surface.table));
     });
+    /**
+     * A custodian's signed completion can be lost. Ask it directly about each
+     * open sign-in it is running and settle the ones it finished; bounded, and
+     * harmless to repeat because the attempt is single use.
+     */
+    const awaitingCustody = () => rows(attemptRow, "SELECT * FROM veil_connection_attempts WHERE status = 'pending' AND pkceVerifierSealed IS NULL AND issuer LIKE 'custody:%' AND expiresAt > ? ORDER BY expiresAt LIMIT 16", options.clock());
+    const reconcileAttempt = (attempt) => Effect.gen(function* () {
+        const find = options.custody.find;
+        if (find === undefined)
+            return null;
+        const row = yield* sync(() => connection(attempt.connectionId));
+        const found = yield* find(address(row), {
+            state: attempt.state,
+            actor: attempt.actor,
+            integrationId: (attempt.issuer ?? "").slice("custody:".length),
+        });
+        if (found.status === "ambiguous")
+            return yield* Effect.fail(new ConnectionsError("conflict"));
+        if (found.status === "unresolved")
+            return null;
+        const done = yield* oauthFlow.completeCustody({
+            state: attempt.state,
+            locator: found.locator,
+            principalId: attempt.actor,
+            integrationId: (attempt.issuer ?? "").slice("custody:".length),
+        });
+        return done.connectionId;
+    });
+    /** The connections a custodian finished that no webhook told us about. */
+    const reconcilePending = () => Effect.gen(function* () {
+        const settled = [];
+        for (const attempt of yield* sync(awaitingCustody)) {
+            const outcome = yield* reconcileAttempt(attempt).pipe(Effect.result);
+            if (outcome._tag === "Success" && outcome.success !== null)
+                settled.push(outcome.success);
+        }
+        return settled;
+    });
     const update = createUpdate({
         ownerId,
         custody: options.custody,
@@ -627,5 +693,7 @@ export function createConnections(options) {
         update,
         sweep,
         cleanupPending,
+        reconcilePending,
+        awaitingCustody: () => awaitingCustody().length,
     };
 }

package/dist/connections/nango.js

@@ -1,6 +1,6 @@
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
-import { authWebhookSchema, connectDocument, publicUrl, sessionSchema, webhookEnvelopeSchema, } from "../nango.js";
+import { authWebhookSchema, connectDocument, publicUrl, sessionSchema, tagsSchema, webhookEnvelopeSchema, } from "../nango.js";
 import { createNangoCustodyHttp } from "../nango-custody-http.js";
 import { VeilError } from "../index.js";
 import { ConnectionsError, } from "./contract.js";
@@ -22,6 +22,17 @@ const outage = (cause) => cause instanceof ConnectionsError
             : "unavailable", { cause })
         : new ConnectionsError("unavailable", { cause });
 const attempt = (body) => Effect.tryPromise({ try: body, catch: outage });
+const connectionsSchema = Schema.Struct({
+    connections: Schema.Array(Schema.Struct({
+        connection_id: Schema.NonEmptyString,
+        provider_config_key: Schema.NonEmptyString,
+        tags: tagsSchema,
+        end_user: Schema.Struct({
+            id: Schema.NonEmptyString,
+            organization: Schema.Struct({ id: Schema.NonEmptyString }),
+        }),
+    })),
+});
 /**
  * Nango as a `CustodyAdapter`: `put` imports an API-key connection, `inject`
  * sends through Nango's proxy (which attaches and refreshes the credential),
@@ -105,6 +116,37 @@ export function createNangoCustody(options) {
                 expiresAt: data.expires_at.getTime(),
             };
         }),
+        find: (address, session) => attempt(async () => {
+            const query = new URLSearchParams({
+                integrationId: session.integrationId,
+                endUserId: session.actor,
+                endUserOrganizationId: address.ownerId,
+                limit: "2",
+                page: "0",
+            });
+            query.set("tags[veil_team_id]", address.ownerId);
+            query.set("tags[veil_attempt_id]", session.state);
+            query.set("tags[veil_principal_id]", session.actor);
+            const response = await http.call(`/connections?${query.toString()}`, signal(), {});
+            if (!response.ok)
+                throw new ConnectionsError("unavailable");
+            const { connections } = decode(connectionsSchema, await response.text());
+            // The server filters before its limit; two rows prove ambiguity.
+            for (const row of connections)
+                if (row.provider_config_key !== session.integrationId ||
+                    row.end_user.id !== session.actor ||
+                    row.end_user.organization.id !== address.ownerId ||
+                    row.tags.veil_team_id !== address.ownerId ||
+                    row.tags.veil_attempt_id !== session.state ||
+                    row.tags.veil_principal_id !== session.actor)
+                    throw new ConnectionsError("invalid_response");
+            const [only, second] = connections;
+            if (only === undefined)
+                return { status: "unresolved" };
+            if (second !== undefined)
+                return { status: "ambiguous" };
+            return { status: "found", locator: only.connection_id };
+        }),
         verifyCompletion: async (rawBody, signature) => {
             // Maintained HMAC over the raw body first; only then decode the event.
             const { Nango } = await import("@nangohq/node");
@@ -129,6 +171,7 @@ export function createNangoCustody(options) {
                 ownerId: row.tags.veil_team_id,
                 state: row.tags.veil_attempt_id,
                 locator: row.connectionId,
+                principalId: row.tags.veil_principal_id,
                 integrationId: row.providerConfigKey,
             };
         },

package/dist/connections/oauth-flow.d.ts

@@ -27,7 +27,7 @@ export type OAuthStore = Readonly<{
         expired: boolean;
     };
     /** Consume a live attempt the custodian runs; expired ones retire. */
-    claimCustody: (state: string) => {
+    claimCustody: (state: string, principalId: string) => {
         attempt: AttemptRow;
         expired: boolean;
     };
@@ -61,15 +61,17 @@ export declare function createOAuthFlow(deps: {
     }> | null) => Effect.Effect<{
         connectionId: string;
         authorizeUrl: string;
+        attemptId: string;
     }, ConnectionsError, never>;
     beginCustody: (actor: string, draft: ConnectionDraft, credential: Extract<ConnectionDraft["credential"], {
         kind: "oauth";
     }>, endpoint: string, fingerprint: string, openapi: Readonly<{
         table: readonly unknown[];
         digest: string;
-    }> | null) => Effect.Effect<{
+    }> | null, kind: "mcp" | "openapi") => Effect.Effect<{
         connectionId: string;
         authorizeUrl: string;
+        attemptId: string;
     }, ConnectionsError, never>;
     complete: (actor: string, input: CompleteInput) => Effect.Effect<{
         connectionId: string;

package/dist/connections/oauth-flow.js

@@ -71,7 +71,7 @@ export function createOAuthFlow(deps) {
         catch: (cause) => new ConnectionsError("reconnect_required", { cause }),
     })));
     /** The custodian runs the authorization: we hold only the page to send the owner to. */
-    const beginCustody = (actor, draft, credential, endpoint, fingerprint, openapi) => Effect.gen(function* () {
+    const beginCustody = (actor, draft, credential, endpoint, fingerprint, openapi, kind) => Effect.gen(function* () {
         const connect = custody.connect;
         const integrationId = credential.provider;
         if (connect === undefined || integrationId === undefined)
@@ -89,7 +89,7 @@ export function createOAuthFlow(deps) {
             authorityVersion: 1,
             version: 1,
             surface: {
-                kind: openapi === null ? "mcp" : "openapi",
+                kind,
                 url: endpoint,
                 table: openapi?.table ?? null,
                 digest: openapi?.digest ?? null,
@@ -107,7 +107,11 @@ export function createOAuthFlow(deps) {
                 fingerprint,
                 authorizeUrl: session.connectUrl,
             });
-            return { connectionId, authorizeUrl: session.connectUrl };
+            return {
+                connectionId,
+                authorizeUrl: session.connectUrl,
+                attemptId: state,
+            };
         });
     });
     /**
@@ -116,7 +120,7 @@ export function createOAuthFlow(deps) {
      * connection is not live until this settles it.
      */
     const completeCustody = (input) => Effect.gen(function* () {
-        const claimed = yield* sync(() => store.claimCustody(input.state));
+        const claimed = yield* sync(() => store.claimCustody(input.state, input.principalId));
         if (claimed.expired)
             return yield* Effect.fail(new ConnectionsError("denied"));
         if (claimed.attempt.issuer !== `custody:${input.integrationId}`)
@@ -193,7 +197,11 @@ export function createOAuthFlow(deps) {
                 fingerprint,
                 authorizeUrl: started.authorizeUrl,
             });
-            return { connectionId, authorizeUrl: started.authorizeUrl };
+            return {
+                connectionId,
+                authorizeUrl: started.authorizeUrl,
+                attemptId: state,
+            };
         }).pipe(Effect.tapError(() => sync(() => {
             store.discard(connectionId, attemptLocator, credential);
         })));