@fungi.computer/veil 0.5.0 → 0.6.1

package/dist/gatekeeper.d.ts

@@ -1,12 +1,13 @@
 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
@@ -32,11 +33,17 @@ 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;
-    /** Comma-separated Nango integrations an owner may sign in through for connections. */
+    /**
+     * 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;
@@ -62,17 +69,20 @@ export type VeilBindings = ProviderKeyBindings & Readonly<{
  * 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. */
-export declare function configuredConnectionsOAuthIntegrations(env: VeilBindings): readonly string[];
-export declare function configuredGitHubState(env: VeilBindings): {
-    github: "off";
-    metadataIntegrationId?: never;
-    gitIntegrationId?: never;
-} | {
-    github: "on";
-    metadataIntegrationId: string;
-    gitIntegrationId: string;
-};
+/**
+ * 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.
@@ -122,85 +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<{
-    profile: "connections";
+    profile: "connections" | "computer-git";
     ownerId: string;
-} | {
-    operation: "creation" | "refresh_failed";
-    completion: import("./index.js").VerifiedCompletion;
-    profile: "computer-git";
-    ownerId?: never;
-} | {
-    operation: "creation" | "refresh_failed";
-    completion: import("./index.js").VerifiedCompletion;
-    profile: "agent-metadata";
-    ownerId?: never;
 }>;
 export type OpenApiHostOptions = Readonly<{
     connect: PublicConnect;

package/dist/gatekeeper.js

@@ -1,11 +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 { 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";
@@ -54,25 +53,72 @@ export function configuredConnectionsCustody(env) {
         throw new VeilError("unavailable");
     }
 }
-/** The Nango integrations an owner may sign in through for connections. */
-export function configuredConnectionsOAuthIntegrations(env) {
-    return (env.NANGO_CONNECTIONS_OAUTH_INTEGRATIONS ?? "")
-        .split(",")
-        .map((id) => id.trim())
-        .filter((id) => id.length > 0);
+/** 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));
 }
-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,
-    };
+/**
+ * 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
@@ -151,75 +197,32 @@ 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);
-    const connectionIntegrations = configuredConnectionsOAuthIntegrations(env);
-    if (state.github === "off" && connectionIntegrations.length === 0)
+    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");
-    // A connection's sign-in runs through an integration the operator listed for it.
-    if (connectionIntegrations.includes(decoded.value.providerConfigKey))
-        return {
-            profile: "connections",
-            ownerId: await verifiedConnectionOwner(env, rawBody, signature),
-        };
-    if (state.github === "off")
-        throw new VeilError("github_not_configured");
-    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),
+    };
 }
 /** The signed sign-in names the Team that began it; only a verified body is believed. */
 async function verifiedConnectionOwner(env, rawBody, signature) {
@@ -239,28 +242,6 @@ async function verifiedConnectionOwner(env, rawBody, signature) {
         throw cause;
     }
 }
-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)
-        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,
-        });
-    }
-    catch {
-        throw new VeilError("unavailable");
-    }
-}
 /** The keyring that seals OpenAPI credentials; only Gatekeeper reads the master key. */
 export function openApiCredentialKeyring(env, previous) {
     const key = env.OPENAPI_CREDENTIAL_MASTER_KEY;

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 });
+            }
+        },
+    };
+}