@fungi.computer/veil 0.4.0 → 0.6.0

package/dist/connections/update.js

@@ -0,0 +1,81 @@
+import * as Effect from "effect/Effect";
+import { ConnectionsError, updateInputSchema, } from "./contract.js";
+import { decode, io, sync } from "./internal.js";
+import { decodeTable } from "./openapi.js";
+/** Owner edits guarded by the version the owner last saw; replays are idempotent. */
+export function createUpdate(deps) {
+    const { store } = deps;
+    return (actor, raw) => Effect.gen(function* () {
+        const input = yield* sync(() => {
+            store.authorize(actor);
+            const parsed = decode(updateInputSchema, raw);
+            if (parsed.credential?.kind === "oauth" ||
+                (parsed.credential?.kind === "static") !==
+                    (parsed.secret !== undefined))
+                throw new ConnectionsError(parsed.credential === undefined ? "invalid_input" : "unsupported");
+            return parsed;
+        });
+        const stamp = JSON.stringify([
+            "update",
+            input.connectionId,
+            input.expectedVersion,
+            input.name ?? null,
+            input.label ?? null,
+            input.baseUrl ?? null,
+            input.table === undefined ? null : JSON.stringify(input.table),
+            input.credential ?? null,
+            input.secret !== undefined,
+        ]);
+        const replay = yield* sync(() => {
+            const receipt = store.receipt(input.requestId);
+            if (receipt !== null && receipt.stamp !== stamp)
+                throw new ConnectionsError("conflict");
+            return receipt;
+        });
+        if (replay !== null)
+            return { connectionId: replay.connectionId, version: replay.version };
+        const row = yield* sync(() => {
+            const found = store.connection(input.connectionId);
+            if (found.version !== input.expectedVersion)
+                throw new ConnectionsError("conflict");
+            if (found.state === "revoked" || found.state === "pending")
+                throw new ConnectionsError(found.state === "revoked" ? "revoked" : "pending");
+            if ((input.table !== undefined || input.baseUrl !== undefined) &&
+                found.surface.kind !== "openapi")
+                throw new ConnectionsError("invalid_input");
+            // A new destination must not inherit a credential sealed for the old one.
+            if (input.baseUrl !== undefined &&
+                input.credential === undefined &&
+                found.credential.kind !== "none" &&
+                new URL(input.baseUrl).href !== found.surface.url)
+                throw new ConnectionsError("invalid_input");
+            if (input.name !== undefined)
+                store.checkName(input.name, found.id);
+            return found;
+        });
+        const baseUrl = yield* sync(() => input.baseUrl === undefined
+            ? row.surface.url
+            : store.publicUrl(input.baseUrl));
+        const next = input.table === undefined
+            ? null
+            : yield* io(() => decodeTable(input.table));
+        const credential = input.credential ?? row.credential;
+        const locator = input.secret === undefined
+            ? row.locator
+            : yield* deps.custody.put({ ownerId: deps.ownerId, connectionId: row.id, credential }, input.secret);
+        return yield* sync(() => store.commit({
+            actor,
+            update: input,
+            stamp,
+            row,
+            baseUrl,
+            table: next?.operations ?? row.surface.table,
+            digest: next?.digest ?? row.surface.digest ?? null,
+            credential,
+            locator,
+        })).pipe(Effect.tapError(() => sync(() => {
+            if (input.secret !== undefined && locator !== null)
+                store.discard(row.id, locator, credential);
+        })));
+    });
+}

package/dist/gatekeeper.d.ts

@@ -1,11 +1,13 @@
-import { type OpenApiCredentialStore, type OpenApiOAuthProvider, type OpenApiDoorOptions } from "./openapi.js";
+import { type OpenApiCredentialKeyring, type OpenApiCredentialStore, type OpenApiOAuthProvider, type OpenApiDoorOptions } from "./openapi.js";
 import { type OpenApiEffects } from "./openapi-effect.js";
 import type { PublicConnect } from "./public-fetch.js";
+import { type CustodyProvider } from "./connections/contract.js";
+import { type GitHubAppCustody } from "./github-app.js";
+import { type ConnectionsCustodian } from "./connections/nango.js";
 import { type WorldSeatCustodian } from "./world-seat.js";
 import type { ModelKeyCustodian } from "./model-keys.js";
 import { createModelKeyEgress, type ModelKeyGrants } from "./model-key-grants.js";
 import { providerFetch, type ProviderEgress, type ProviderKeyBindings, type ProviderRoute } from "./provider-egress.js";
-import * as Schema from "effect/Schema";
 /**
  * The Gatekeeper: the one place the Hub's Nango key, webhook signing key,
  * provider/model-key integration ids, and platform provider keys (Camel, the
@@ -21,6 +23,7 @@ import * as Schema from "effect/Schema";
  */
 export { providerFetch };
 export type { ProviderEgress, ProviderRoute };
+export type { ConnectionsCustodian };
 /** Private Worker bindings, never Team storage or public response fields. */
 export type VeilBindings = ProviderKeyBindings & Readonly<{
     WEBHOOK_TRIGGER_MASTER_KEY?: string;
@@ -30,8 +33,18 @@ export type VeilBindings = ProviderKeyBindings & Readonly<{
     NANGO_SERVER_URL?: string;
     NANGO_API_KEY?: string;
     NANGO_WEBHOOK_SIGNING_KEY?: string;
+    /** The GitHub REST sign-in integration; it joins the connections sign-in list. */
     NANGO_GITHUB_INTEGRATION_ID?: string;
-    NANGO_GITHUB_GIT_INTEGRATION_ID?: string;
+    /** The Nango `github-app` integration that hands a Computer its installation token. */
+    NANGO_GITHUB_APP_INTEGRATION_ID?: string;
+    /** API-key integration that holds pasted credentials for Team connections. */
+    NANGO_CONNECTIONS_INTEGRATION_ID?: string;
+    /**
+     * Nango integrations an owner may sign in through for connections, as a
+     * JSON object from integration id to `{ "apiOrigins": ["https://…"] }`:
+     * the only origins that integration's credential is sent to.
+     */
+    NANGO_CONNECTIONS_OAUTH_INTEGRATIONS?: string;
     /** Public Connect UI base that Nango's issued links must stay under. */
     NANGO_CONNECT_BASE_URL?: string;
     /** Public Nango API origin the Connect UI in the browser must call. */
@@ -51,15 +64,25 @@ export type VeilBindings = ProviderKeyBindings & Readonly<{
      */
     HUB_LOCAL_MODE?: string;
 }>;
-export declare function configuredGitHubState(env: VeilBindings): {
-    github: "off";
-    metadataIntegrationId?: never;
-    gitIntegrationId?: never;
-} | {
-    github: "on";
-    metadataIntegrationId: string;
-    gitIntegrationId: string;
-};
+/**
+ * Optional Nango custody for Team connections. A Hub with none of the Nango
+ * bindings keeps sealed custody and still connects OAuth MCP and OpenAPI.
+ */
+export declare function configuredConnectionsCustody(env: VeilBindings): ConnectionsCustodian | undefined;
+/**
+ * The Nango integrations an owner may sign in through for connections, each
+ * pinned to the origins its credential may reach. Absent or malformed means
+ * none: a sign-in through an undeclared integration is refused, never guessed.
+ */
+export declare function configuredConnectionsCustodyProviders(env: VeilBindings): Readonly<Record<string, CustodyProvider>>;
+/**
+ * The Nango `github-app` integration through which a Computer's git gets its
+ * installation token. It is its own thing: never in the generic list, and
+ * never the same integration as GitHub REST.
+ */
+export declare function configuredGitHubAppIntegration(env: VeilBindings): string | undefined;
+/** Nango's GitHub App custody for Computers; absent when any binding is. */
+export declare function configuredGitHubAppCustody(env: VeilBindings): GitHubAppCustody | undefined;
 /**
  * `veil.fetch` for platform provider keys. The Hub names a route and sends a
  * credential-free request; Veil checks the destination and attaches the key.
@@ -109,80 +132,13 @@ export declare function configuredModelKeyEgress(env: VeilBindings, options: Rea
         provider: import("./model-keys.js").ModelKeyProvider;
     }>, request: Request): Promise<Response>;
 };
-export declare function configuredVeilCustodian(env: VeilBindings): Readonly<{
-    openSession: (input: Readonly<{
-        teamId: string;
-        attemptId: string;
-        principalId: string;
-        integrationId: string;
-    }>, signal: AbortSignal) => Promise<Readonly<{
-        token: string;
-        connectUrl: string;
-        expiresAt: number;
-    }>>;
-    verifyCompletion: (rawBody: string, signature: string) => Promise<import("./index.js").VerifiedCompletion>;
-    verifyWebhook: (rawBody: string, signature: string) => Promise<import("./index.js").VerifiedWebhook>;
-    findCompletion: (attempt: import("./index.js").CustodyCorrelation, signal: AbortSignal) => Promise<Schema.Schema.Type<Schema.Union<readonly [Schema.Struct<{
-        readonly status: Schema.Literal<"unresolved">;
-    }>, Schema.Struct<{
-        readonly status: Schema.Literal<"ambiguous">;
-    }>, Schema.Struct<{
-        readonly status: Schema.Literal<"verified">;
-        readonly completion: Schema.Struct<{
-            readonly teamId: Schema.NonEmptyString;
-            readonly attemptId: Schema.NonEmptyString;
-            readonly principalId: Schema.NonEmptyString;
-            readonly integrationId: Schema.NonEmptyString;
-            readonly locator: Schema.NonEmptyString;
-        }>;
-    }>]>>>;
-    deleteConnection: (locator: string, signal: AbortSignal) => Promise<"deleted" | "absent">;
-    readRepository: (access: import("./index.js").RepositoryAccess, signal: AbortSignal) => Promise<string>;
-}>;
-/** Git Connect/cleanup and final egress use the same Git-profile integration.
- * No metadata Connection locator is translated into this profile. Veil confines
- * the issued Connect document to the configured public Connect URLs. */
-export declare function configuredComputerGitCustodian(env: VeilBindings): {
-    integrationId: string;
-    openSession: (input: Readonly<{
-        teamId: string;
-        attemptId: string;
-        principalId: string;
-        integrationId: string;
-    }>, signal: AbortSignal) => Promise<Readonly<{
-        token: string;
-        connectUrl: string;
-        expiresAt: number;
-    }>>;
-    verifyCompletion: (rawBody: string, signature: string) => Promise<import("./index.js").VerifiedCompletion>;
-    verifyWebhook: (rawBody: string, signature: string) => Promise<import("./index.js").VerifiedWebhook>;
-    findCompletion: (attempt: import("./index.js").CustodyCorrelation, signal: AbortSignal) => Promise<Schema.Schema.Type<Schema.Union<readonly [Schema.Struct<{
-        readonly status: Schema.Literal<"unresolved">;
-    }>, Schema.Struct<{
-        readonly status: Schema.Literal<"ambiguous">;
-    }>, Schema.Struct<{
-        readonly status: Schema.Literal<"verified">;
-        readonly completion: Schema.Struct<{
-            readonly teamId: Schema.NonEmptyString;
-            readonly attemptId: Schema.NonEmptyString;
-            readonly principalId: Schema.NonEmptyString;
-            readonly integrationId: Schema.NonEmptyString;
-            readonly locator: Schema.NonEmptyString;
-        }>;
-    }>]>>>;
-    deleteConnection: (locator: string, signal: AbortSignal) => Promise<"deleted" | "absent">;
-    readGit: (access: import("./nango-git.js").GitRepositoryAccess, request: Request) => Promise<Response>;
-};
-/** The decoded key selects one of the two configured profiles only. The
- * selected maintained custodian still verifies the original signed body. */
+/** The decoded key must name an integration this host runs a sign-in through;
+ * the maintained custodian then verifies the original signed body. The GitHub
+ * App integration settles only a Computer's git, a generic one only a
+ * connection: neither can settle the other's attempt. */
 export declare function verifyVeilWebhook(env: VeilBindings, rawBody: string, signature: string): Promise<{
-    operation: "creation" | "refresh_failed";
-    completion: import("./index.js").VerifiedCompletion;
-    profile: "computer-git";
-} | {
-    operation: "creation" | "refresh_failed";
-    completion: import("./index.js").VerifiedCompletion;
-    profile: "agent-metadata";
+    profile: "connections" | "computer-git";
+    ownerId: string;
 }>;
 export type OpenApiHostOptions = Readonly<{
     connect: PublicConnect;
@@ -192,6 +148,8 @@ export type OpenApiHostOptions = Readonly<{
     previousCredentialKeys?: Readonly<Record<string, string>>;
     oauthProviders?: Readonly<Record<string, OpenApiOAuthProvider>>;
 }>;
+/** The keyring that seals OpenAPI credentials; only Gatekeeper reads the master key. */
+export declare function openApiCredentialKeyring(env: VeilBindings, previous?: Readonly<Record<string, string>>): OpenApiCredentialKeyring | undefined;
 /** Anonymous calls need no secret; API-key/bearer calls require configured Veil custody. */
 export declare function configuredOpenApiDoor(env: VeilBindings, options: OpenApiHostOptions): Readonly<{
     seal: (access: import("./openapi-contract.js").OpenApiAccess, credential: string, signal: AbortSignal) => Promise<void>;

package/dist/gatekeeper.js

@@ -1,9 +1,10 @@
 import { createOpenApiDoor, } from "./openapi.js";
 import { createOpenApiEffects } from "./openapi-effect.js";
 import { createDnsOverHttpsResolver } from "./model-key-network.js";
-import { createNangoCustodian } from "./nango.js";
+import { ConnectionsError, } from "./connections/contract.js";
+import { createGitHubAppCustody } from "./github-app.js";
+import { createNangoCustody, } from "./connections/nango.js";
 import { createWebhookTriggerSecrets } from "./webhook-trigger-secrets.js";
-import { createNangoGitCustodian } from "./nango-git.js";
 import { createNangoModelKeyCustodian } from "./nango-model-keys.js";
 import { createNangoWorldSeatCustodian } from "./nango-world-seat.js";
 import { worldSeatEndpoint } from "./world-seat.js";
@@ -26,18 +27,98 @@ import * as Exit from "effect/Exit";
  * Hub code reaches a provider only through `configuredProviderEgress`.
  */
 export { providerFetch };
-export function configuredGitHubState(env) {
-    const metadataIntegrationId = env.NANGO_GITHUB_INTEGRATION_ID;
-    const gitIntegrationId = env.NANGO_GITHUB_GIT_INTEGRATION_ID;
-    if (!metadataIntegrationId ||
-        !gitIntegrationId ||
-        metadataIntegrationId === gitIntegrationId)
-        return { github: "off" };
-    return {
-        github: "on",
-        metadataIntegrationId,
-        gitIntegrationId,
-    };
+/**
+ * Optional Nango custody for Team connections. A Hub with none of the Nango
+ * bindings keeps sealed custody and still connects OAuth MCP and OpenAPI.
+ */
+export function configuredConnectionsCustody(env) {
+    if (!env.NANGO_SERVER_URL ||
+        !env.NANGO_API_KEY ||
+        !env.NANGO_WEBHOOK_SIGNING_KEY ||
+        !env.NANGO_CONNECT_BASE_URL ||
+        !env.NANGO_PUBLIC_API_URL ||
+        !env.NANGO_CONNECTIONS_INTEGRATION_ID)
+        return undefined;
+    try {
+        return createNangoCustody({
+            serverUrl: env.NANGO_SERVER_URL,
+            apiKey: env.NANGO_API_KEY,
+            webhookSigningKey: env.NANGO_WEBHOOK_SIGNING_KEY,
+            staticIntegrationId: env.NANGO_CONNECTIONS_INTEGRATION_ID,
+            connectBaseUrl: env.NANGO_CONNECT_BASE_URL,
+            publicApiUrl: env.NANGO_PUBLIC_API_URL,
+        });
+    }
+    catch {
+        throw new VeilError("unavailable");
+    }
+}
+/** GitHub's REST API: the only place the GitHub REST integration's token may go. */
+const GITHUB_REST_ORIGIN = "https://api.github.com";
+const custodyProvidersJson = Schema.fromJsonString(Schema.Record(Schema.String.pipe(Schema.check(Schema.isPattern(/^[A-Za-z0-9_.:-]{1,128}$/u))), Schema.Struct({
+    apiOrigins: Schema.Array(Schema.String).pipe(Schema.check(Schema.isMinLength(1), Schema.isMaxLength(16))),
+})));
+const isHttpsOrigin = (value) => URL.canParse(value) &&
+    new URL(value).protocol === "https:" &&
+    new URL(value).origin === value;
+/**
+ * The Nango integrations an owner may sign in through for connections, each
+ * pinned to the origins its credential may reach. Absent or malformed means
+ * none: a sign-in through an undeclared integration is refused, never guessed.
+ */
+export function configuredConnectionsCustodyProviders(env) {
+    const raw = env.NANGO_CONNECTIONS_OAUTH_INTEGRATIONS;
+    const decoded = raw === undefined || raw.trim() === ""
+        ? undefined
+        : Schema.decodeUnknownExit(custodyProvidersJson)(raw);
+    const operator = decoded === undefined || Exit.isFailure(decoded) ? {} : decoded.value;
+    const declared = {};
+    for (const [id, provider] of Object.entries(operator))
+        if (provider.apiOrigins.every(isHttpsOrigin))
+            declared[id] = provider;
+    // GitHub REST is pinned to its API host whatever the operator declared.
+    const rest = env.NANGO_GITHUB_INTEGRATION_ID;
+    if (rest !== undefined && rest !== "")
+        declared[rest] = { apiOrigins: [GITHUB_REST_ORIGIN] };
+    const app = configuredGitHubAppIntegration(env);
+    return Object.fromEntries(Object.entries(declared).filter(([id]) => id !== app));
+}
+/**
+ * The Nango `github-app` integration through which a Computer's git gets its
+ * installation token. It is its own thing: never in the generic list, and
+ * never the same integration as GitHub REST.
+ */
+export function configuredGitHubAppIntegration(env) {
+    const id = env.NANGO_GITHUB_APP_INTEGRATION_ID;
+    if (id === undefined || id === "" || id === env.NANGO_GITHUB_INTEGRATION_ID)
+        return undefined;
+    return id;
+}
+/** Nango's GitHub App custody for Computers; absent when any binding is. */
+export function configuredGitHubAppCustody(env) {
+    const appIntegrationId = configuredGitHubAppIntegration(env);
+    if (appIntegrationId === undefined ||
+        !env.NANGO_SERVER_URL ||
+        !env.NANGO_API_KEY ||
+        !env.NANGO_WEBHOOK_SIGNING_KEY ||
+        !env.NANGO_CONNECT_BASE_URL ||
+        !env.NANGO_PUBLIC_API_URL ||
+        !env.NANGO_CONNECTIONS_INTEGRATION_ID)
+        return undefined;
+    try {
+        return createGitHubAppCustody({
+            serverUrl: env.NANGO_SERVER_URL,
+            apiKey: env.NANGO_API_KEY,
+            webhookSigningKey: env.NANGO_WEBHOOK_SIGNING_KEY,
+            staticIntegrationId: env.NANGO_CONNECTIONS_INTEGRATION_ID,
+            connectBaseUrl: env.NANGO_CONNECT_BASE_URL,
+            publicApiUrl: env.NANGO_PUBLIC_API_URL,
+            appIntegrationId,
+        });
+    }
+    catch {
+        throw new VeilError("unavailable");
+    }
 }
 /**
  * `veil.fetch` for platform provider keys. The Hub names a route and sends a
@@ -116,89 +197,59 @@ export function configuredModelKeyEgress(env, options) {
         ownerIsMember: options.ownerIsMember,
     });
 }
-export function configuredVeilCustodian(env) {
-    const state = configuredGitHubState(env);
-    if (state.github === "off")
-        throw new VeilError("github_not_configured");
-    return configuredCustodian(env, state.metadataIntegrationId);
-}
-/** Git Connect/cleanup and final egress use the same Git-profile integration.
- * No metadata Connection locator is translated into this profile. Veil confines
- * the issued Connect document to the configured public Connect URLs. */
-export function configuredComputerGitCustodian(env) {
-    const state = configuredGitHubState(env);
-    if (state.github === "off")
-        throw new VeilError("github_not_configured");
-    const custody = configuredCustodian(env, state.gitIntegrationId);
-    if (!env.NANGO_SERVER_URL || !env.NANGO_API_KEY)
-        throw new VeilError("unavailable");
-    try {
-        const git = createNangoGitCustodian({
-            serverUrl: env.NANGO_SERVER_URL,
-            apiKey: env.NANGO_API_KEY,
-            integrationId: state.gitIntegrationId,
-        });
-        return {
-            integrationId: state.gitIntegrationId,
-            openSession: custody.openSession,
-            verifyCompletion: custody.verifyCompletion,
-            verifyWebhook: custody.verifyWebhook,
-            findCompletion: custody.findCompletion,
-            deleteConnection: custody.deleteConnection,
-            readGit: git.readGit.bind(git),
-        };
-    }
-    catch {
-        throw new VeilError("unavailable");
-    }
-}
-/** The decoded key selects one of the two configured profiles only. The
- * selected maintained custodian still verifies the original signed body. */
+/** The decoded key must name an integration this host runs a sign-in through;
+ * the maintained custodian then verifies the original signed body. The GitHub
+ * App integration settles only a Computer's git, a generic one only a
+ * connection: neither can settle the other's attempt. */
 export async function verifyVeilWebhook(env, rawBody, signature) {
-    const state = configuredGitHubState(env);
-    if (state.github === "off")
+    const generic = Object.keys(configuredConnectionsCustodyProviders(env));
+    const app = configuredGitHubAppIntegration(env);
+    if (generic.length === 0 && app === undefined)
         throw new VeilError("github_not_configured");
     const decoded = Schema.decodeUnknownExit(Schema.fromJsonString(Schema.Struct({
         providerConfigKey: Schema.NonEmptyString,
     })))(rawBody);
     if (Exit.isFailure(decoded))
         throw new VeilError("invalid_completion");
-    if (decoded.value.providerConfigKey === state.gitIntegrationId) {
-        return {
-            profile: "computer-git",
-            ...(await configuredComputerGitCustodian(env).verifyWebhook(rawBody, signature)),
-        };
-    }
-    if (decoded.value.providerConfigKey === state.metadataIntegrationId) {
-        return {
-            profile: "agent-metadata",
-            ...(await configuredVeilCustodian(env).verifyWebhook(rawBody, signature)),
-        };
-    }
-    throw new VeilError("invalid_completion");
+    const key = decoded.value.providerConfigKey;
+    const profile = generic.includes(key)
+        ? "connections"
+        : key === app
+            ? "computer-git"
+            : undefined;
+    if (profile === undefined)
+        throw new VeilError("invalid_completion");
+    return {
+        profile,
+        ownerId: await verifiedConnectionOwner(env, rawBody, signature),
+    };
 }
-function configuredCustodian(env, integrationId) {
-    if (!env.NANGO_SERVER_URL ||
-        !env.NANGO_API_KEY ||
-        !env.NANGO_WEBHOOK_SIGNING_KEY ||
-        !env.NANGO_CONNECT_BASE_URL ||
-        !env.NANGO_PUBLIC_API_URL ||
-        !integrationId)
+/** The signed sign-in names the Team that began it; only a verified body is believed. */
+async function verifiedConnectionOwner(env, rawBody, signature) {
+    const custody = configuredConnectionsCustody(env);
+    if (custody === undefined)
         throw new VeilError("unavailable");
     try {
-        return createNangoCustodian({
-            serverUrl: env.NANGO_SERVER_URL,
-            apiKey: env.NANGO_API_KEY,
-            webhookSigningKey: env.NANGO_WEBHOOK_SIGNING_KEY,
-            integrationId,
-            connectBaseUrl: env.NANGO_CONNECT_BASE_URL,
-            publicApiUrl: env.NANGO_PUBLIC_API_URL,
-        });
+        return (await custody.verifyCompletion(rawBody, signature)).ownerId;
     }
-    catch {
-        throw new VeilError("unavailable");
+    catch (cause) {
+        if (cause instanceof ConnectionsError)
+            throw new VeilError(cause.code === "unsupported"
+                ? "unsupported"
+                : cause.code === "unavailable"
+                    ? "unavailable"
+                    : "invalid_completion", { cause });
+        throw cause;
     }
 }
+/** The keyring that seals OpenAPI credentials; only Gatekeeper reads the master key. */
+export function openApiCredentialKeyring(env, previous) {
+    const key = env.OPENAPI_CREDENTIAL_MASTER_KEY;
+    if (!key)
+        return undefined;
+    const id = env.OPENAPI_CREDENTIAL_KEY_ID ?? "primary";
+    return { activeKeyId: id, keys: { ...previous, [id]: key } };
+}
 /** Gatekeeper owns the common opaque configuration for both runtime facades. */
 function openApiHostConfiguration(env, options) {
     const doorOptions = {
@@ -208,17 +259,9 @@ function openApiHostConfiguration(env, options) {
     };
     if (options.oauthProviders)
         doorOptions.oauthProviders = options.oauthProviders;
-    if (env.OPENAPI_CREDENTIAL_MASTER_KEY)
-        doorOptions.custody = {
-            keys: {
-                activeKeyId: env.OPENAPI_CREDENTIAL_KEY_ID ?? "primary",
-                keys: {
-                    ...options.previousCredentialKeys,
-                    [env.OPENAPI_CREDENTIAL_KEY_ID ?? "primary"]: env.OPENAPI_CREDENTIAL_MASTER_KEY,
-                },
-            },
-            store: options.store,
-        };
+    const keys = openApiCredentialKeyring(env, options.previousCredentialKeys);
+    if (keys)
+        doorOptions.custody = { keys, store: options.store };
     return doorOptions;
 }
 /** Anonymous calls need no secret; API-key/bearer calls require configured Veil custody. */

package/dist/github-app.d.ts

@@ -0,0 +1,44 @@
+import { type CustodyLookup } from "./connections/contract.js";
+import { type NangoCustodyOptions } from "./connections/nango.js";
+/** A completion Nango signed for the GitHub App sign-in, once verified. */
+export type GitHubAppCompletion = Readonly<{
+    teamId: string;
+    state: string;
+    principalId: string;
+    locator: string;
+}>;
+/**
+ * Nango's `github-app` integration as the one source of a Computer's GitHub
+ * token. Nango holds the App's credentials and returns an installation token
+ * limited to the repositories the person picked at install. The token is read
+ * here, in memory, to be placed on a request to `github.com`; it is never
+ * stored, listed or sent anywhere else.
+ */
+export declare function createGitHubAppCustody(options: NangoCustodyOptions & Readonly<{
+    appIntegrationId: string;
+}>): {
+    integrationId: string;
+    /** The page that sends the member to GitHub's installation consent. */
+    connect: (ownerId: string, session: {
+        state: string;
+        actor: string;
+    }) => Promise<Readonly<{
+        connectUrl: string;
+        expiresAt: number;
+    }>>;
+    /** The signed completion, and only one for this App integration. */
+    verifyCompletion: (rawBody: string, signature: string) => Promise<GitHubAppCompletion>;
+    /** Ask Nango whether a sign-in finished whose signed completion was lost. */
+    find: (ownerId: string, session: {
+        state: string;
+        actor: string;
+    }) => Promise<CustodyLookup>;
+    remove: (ownerId: string, locator: string) => Promise<"absent" | "deleted">;
+    /**
+     * A current installation token. `fresh` asks Nango to refresh it first.
+     * A connection Nango no longer holds, or whose App access GitHub ended,
+     * is `reconnect_required`; an outage is `unavailable`.
+     */
+    token: (locator: string, fresh: boolean, signal: AbortSignal) => Promise<string>;
+};
+export type GitHubAppCustody = ReturnType<typeof createGitHubAppCustody>;

package/dist/github-app.js

@@ -0,0 +1,93 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { ConnectionsError, } from "./connections/contract.js";
+import { createNangoCustody, } from "./connections/nango.js";
+import { createNangoCustodyHttp } from "./nango-custody-http.js";
+const tokenResponse = Schema.Struct({
+    credentials: Schema.Struct({
+        access_token: Schema.NonEmptyString,
+        expires_at: Schema.optional(Schema.String),
+    }),
+});
+/**
+ * Nango's `github-app` integration as the one source of a Computer's GitHub
+ * token. Nango holds the App's credentials and returns an installation token
+ * limited to the repositories the person picked at install. The token is read
+ * here, in memory, to be placed on a request to `github.com`; it is never
+ * stored, listed or sent anywhere else.
+ */
+export function createGitHubAppCustody(options) {
+    const nango = createNangoCustody(options);
+    const http = createNangoCustodyHttp(options);
+    const address = (ownerId) => ({
+        ownerId,
+        connectionId: "github-app",
+        credential: { kind: "oauth", provider: options.appIntegrationId },
+    });
+    const run = (effect) => Effect.runPromise(effect);
+    const connect = nango.connect;
+    if (connect === undefined)
+        throw new ConnectionsError("unsupported");
+    const find = nango.find;
+    if (find === undefined)
+        throw new ConnectionsError("unsupported");
+    return {
+        integrationId: options.appIntegrationId,
+        /** The page that sends the member to GitHub's installation consent. */
+        connect: (ownerId, session) => run(connect(address(ownerId), {
+            ...session,
+            integrationId: options.appIntegrationId,
+        })),
+        /** The signed completion, and only one for this App integration. */
+        verifyCompletion: async (rawBody, signature) => {
+            const verified = await nango.verifyCompletion(rawBody, signature);
+            if (verified.integrationId !== options.appIntegrationId)
+                throw new ConnectionsError("denied");
+            return {
+                teamId: verified.ownerId,
+                state: verified.state,
+                principalId: verified.principalId,
+                locator: verified.locator,
+            };
+        },
+        /** Ask Nango whether a sign-in finished whose signed completion was lost. */
+        find: (ownerId, session) => run(find(address(ownerId), {
+            ...session,
+            integrationId: options.appIntegrationId,
+        })),
+        remove: (ownerId, locator) => run(nango.remove(address(ownerId), locator)),
+        /**
+         * A current installation token. `fresh` asks Nango to refresh it first.
+         * A connection Nango no longer holds, or whose App access GitHub ended,
+         * is `reconnect_required`; an outage is `unavailable`.
+         */
+        token: async (locator, fresh, signal) => {
+            const query = new URLSearchParams({
+                provider_config_key: options.appIntegrationId,
+            });
+            if (fresh)
+                query.set("force_refresh", "true");
+            let response;
+            try {
+                response = await http.call(`/connection/${encodeURIComponent(locator)}?${query.toString()}`, signal, {});
+            }
+            catch (cause) {
+                throw new ConnectionsError("unavailable", { cause });
+            }
+            if ([400, 401, 403, 404].includes(response.status)) {
+                await response.body?.cancel();
+                throw new ConnectionsError("reconnect_required");
+            }
+            if (!response.ok) {
+                await response.body?.cancel();
+                throw new ConnectionsError("unavailable");
+            }
+            try {
+                return Schema.decodeUnknownSync(Schema.fromJsonString(tokenResponse))(await response.text()).credentials.access_token;
+            }
+            catch (cause) {
+                throw new ConnectionsError("invalid_response", { cause });
+            }
+        },
+    };
+}