@fungi.computer/veil 0.0.0-stage → 0.0.1

package/dist/gatekeeper.js

@@ -0,0 +1,231 @@
+import { createOpenApiDoor, } from "./openapi.js";
+import { createOpenApiEffects } from "./openapi-effect.js";
+import { createDnsOverHttpsResolver } from "./model-key-network.js";
+import { createNangoCustodian } from "./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";
+import { createModelKeyEgress, createModelKeyGrants, } from "./model-key-grants.js";
+import { VeilError } from "./index.js";
+import { createProviderEgress, providerFetch, } from "./provider-egress.js";
+import * as Schema from "effect/Schema";
+import * as Exit from "effect/Exit";
+/**
+ * The Gatekeeper: the one place the Hub's Nango key, webhook signing key,
+ * provider/model-key integration ids, and platform provider keys (Camel, the
+ * AI Gateway token, Parallel) are read out of the Worker environment and
+ * turned into a custodian or egress. These `configured*` functions are the custody
+ * boundary (`V1`): the Hub hands them its own `env` object opaquely and gets
+ * back an opaque custodian/egress handle, never the secret values themselves.
+ * No file outside `packages/veil` may read `env.NANGO_*` or
+ * `env.WEBHOOK_TRIGGER_MASTER_KEY`, `env.CAMEL_API_KEY`,
+ * `env.AI_GATEWAY_AUTH_TOKEN` or `env.PARALLEL_API_KEY` directly; the static
+ * boundary test `apps/hub/test/veil-custody-boundary.test.ts` enforces it.
+ * 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,
+    };
+}
+/**
+ * `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.
+ * `fetch` is only the final transport (telemetry, or a test double).
+ */
+export function configuredProviderEgress(env, options = {}) {
+    return createProviderEgress(env, options);
+}
+/** The Worker secret is the only custody root for per-trigger signing bytes. */
+export function configuredWebhookTriggerSecrets(env) {
+    if (!env.WEBHOOK_TRIGGER_MASTER_KEY)
+        return { kind: "unavailable" };
+    try {
+        return {
+            kind: "ready",
+            custodian: createWebhookTriggerSecrets(env.WEBHOOK_TRIGGER_MASTER_KEY),
+        };
+    }
+    catch (cause) {
+        return { kind: "unavailable", cause };
+    }
+}
+/** Model API keys use their own integrations; none are required to boot. */
+export function configuredModelKeyCustodian(env) {
+    if (!env.NANGO_SERVER_URL || !env.NANGO_API_KEY)
+        throw new VeilError("unavailable");
+    const integrations = {};
+    if (env.NANGO_ANTHROPIC_KEY_INTEGRATION_ID)
+        integrations.anthropic = env.NANGO_ANTHROPIC_KEY_INTEGRATION_ID;
+    if (env.NANGO_OPENAI_KEY_INTEGRATION_ID)
+        integrations.openai = env.NANGO_OPENAI_KEY_INTEGRATION_ID;
+    if (env.NANGO_OPENROUTER_KEY_INTEGRATION_ID)
+        integrations.openrouter = env.NANGO_OPENROUTER_KEY_INTEGRATION_ID;
+    if (env.NANGO_OPENAI_COMPATIBLE_KEY_INTEGRATION_ID)
+        integrations["openai-compatible"] =
+            env.NANGO_OPENAI_COMPATIBLE_KEY_INTEGRATION_ID;
+    return createNangoModelKeyCustodian({
+        serverUrl: env.NANGO_SERVER_URL,
+        apiKey: env.NANGO_API_KEY,
+        integrations,
+    });
+}
+/**
+ * Model-key grants are sealed under a key derived from the custodian's own
+ * Nango credential, so only a holder of custody can issue or open one.
+ */
+export function configuredModelKeyGrants(env) {
+    if (!env.NANGO_API_KEY)
+        throw new VeilError("unavailable");
+    return createModelKeyGrants({ custodySecret: env.NANGO_API_KEY });
+}
+/** World-seat tokens use their own integration; it is not required to boot. */
+export function configuredWorldSeatCustodian(env) {
+    if (!env.NANGO_SERVER_URL ||
+        !env.NANGO_API_KEY ||
+        !env.NANGO_WORLD_INTEGRATION_ID)
+        throw new VeilError("unavailable");
+    return createNangoWorldSeatCustodian({
+        serverUrl: env.NANGO_SERVER_URL,
+        apiKey: env.NANGO_API_KEY,
+        integrationId: env.NANGO_WORLD_INTEGRATION_ID,
+        allowLocalDev: env.HUB_LOCAL_MODE === "enabled",
+    });
+}
+/** The seat endpoint rule for this host: public HTTPS, or loopback when local. */
+export function configuredWorldSeatEndpoint(env) {
+    const allowLocalDev = env.HUB_LOCAL_MODE === "enabled";
+    return (endpoint) => worldSeatEndpoint(endpoint, { allowLocalDev });
+}
+/** Final model egress a runner reaches with a delivered grant, never via TeamDO. */
+export function configuredModelKeyEgress(env, options) {
+    return createModelKeyEgress({
+        grants: configuredModelKeyGrants(env),
+        custodian: () => configuredModelKeyCustodian(env),
+        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. */
+export async function verifyVeilWebhook(env, rawBody, signature) {
+    const state = configuredGitHubState(env);
+    if (state.github === "off")
+        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");
+}
+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");
+    }
+}
+/** Gatekeeper owns the common opaque configuration for both runtime facades. */
+function openApiHostConfiguration(env, options) {
+    const doorOptions = {
+        connect: options.connect,
+        resolve: createDnsOverHttpsResolver(options.fetch),
+        networkPolicy: options.networkPolicy ?? {},
+    };
+    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,
+        };
+    return doorOptions;
+}
+/** Anonymous calls need no secret; API-key/bearer calls require configured Veil custody. */
+export function configuredOpenApiDoor(env, options) {
+    return createOpenApiDoor(openApiHostConfiguration(env, options));
+}
+/** Owned composition retains canonical Effects; secrets are read only by Gatekeeper. */
+export function configuredOpenApiEffects(env, options) {
+    return createOpenApiEffects(openApiHostConfiguration(env, options));
+}

package/dist/index.d.ts

@@ -0,0 +1,254 @@
+import * as Schema from "effect/Schema";
+/** The repository identity selected by the Team, never by model input. */
+export declare const RepositoryScopeSchema: Schema.Struct<{
+    readonly id: Schema.Number;
+    readonly owner: Schema.NonEmptyString;
+    readonly name: Schema.NonEmptyString;
+}>;
+export type RepositoryScope = Schema.Schema.Type<typeof RepositoryScopeSchema>;
+/** Bounded, credential-free metadata returned by the GitHub operation. */
+export declare const GitHubRepositorySchema: Schema.Struct<{
+    readonly id: Schema.Number;
+    readonly name: Schema.NonEmptyString;
+    readonly fullName: Schema.NonEmptyString;
+    readonly private: Schema.Boolean;
+    readonly defaultBranch: Schema.NonEmptyString;
+}>;
+export type GitHubRepository = Schema.Schema.Type<typeof GitHubRepositorySchema>;
+export declare const ConnectInputSchema: Schema.Struct<{
+    readonly requestId: Schema.NonEmptyString;
+    readonly actorUserId: Schema.NonEmptyString;
+    readonly holderAgentId: Schema.NonEmptyString;
+    readonly repository: Schema.Struct<{
+        readonly id: Schema.Number;
+        readonly owner: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>;
+}>;
+export type ConnectInput = Schema.Schema.Type<typeof ConnectInputSchema>;
+export declare const AttemptSchema: Schema.Struct<{
+    readonly teamId: Schema.NonEmptyString;
+    readonly attemptId: Schema.NonEmptyString;
+    readonly connectionId: Schema.NonEmptyString;
+    readonly integrationId: Schema.NonEmptyString;
+    readonly expiresAt: Schema.Number;
+    readonly requestId: Schema.NonEmptyString;
+    readonly actorUserId: Schema.NonEmptyString;
+    readonly holderAgentId: Schema.NonEmptyString;
+    readonly repository: Schema.Struct<{
+        readonly id: Schema.Number;
+        readonly owner: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>;
+}>;
+export type ConnectionAttempt = Schema.Schema.Type<typeof AttemptSchema>;
+/** Custody correlation is independent of the resource receiving the Connection. */
+export type CustodyCorrelation = Pick<ConnectionAttempt, "teamId" | "attemptId" | "actorUserId" | "integrationId">;
+/** Produced only by a custodian's verified completion boundary. */
+export declare const CompletionSchema: Schema.Struct<{
+    readonly teamId: Schema.NonEmptyString;
+    readonly attemptId: Schema.NonEmptyString;
+    readonly principalId: Schema.NonEmptyString;
+    readonly integrationId: Schema.NonEmptyString;
+    readonly locator: Schema.NonEmptyString;
+}>;
+export type VerifiedCompletion = Schema.Schema.Type<typeof CompletionSchema>;
+export declare const ConnectionReceiptSchema: Schema.Struct<{
+    readonly requestId: Schema.NonEmptyString;
+    readonly connectionId: Schema.NonEmptyString;
+    readonly holderAgentId: Schema.NonEmptyString;
+    readonly repository: Schema.Struct<{
+        readonly id: Schema.Number;
+        readonly owner: Schema.NonEmptyString;
+        readonly name: Schema.NonEmptyString;
+    }>;
+    readonly authorityVersion: Schema.Number;
+    readonly status: Schema.Literals<readonly ["active", "disconnected"]>;
+    readonly cleanup: Schema.Literals<readonly ["none", "pending"]>;
+}>;
+export type ConnectionReceipt = Schema.Schema.Type<typeof ConnectionReceiptSchema>;
+export declare const ReadBindingSchema: Schema.Struct<{
+    readonly teamId: Schema.NonEmptyString;
+    readonly holderAgentId: Schema.NonEmptyString;
+    readonly connectionId: Schema.NonEmptyString;
+    readonly repositoryId: Schema.Number;
+}>;
+export type ReadBinding = Schema.Schema.Type<typeof ReadBindingSchema>;
+export declare const DisconnectInputSchema: Schema.Struct<{
+    readonly requestId: Schema.NonEmptyString;
+    readonly actorUserId: Schema.NonEmptyString;
+    readonly connectionId: Schema.NonEmptyString;
+}>;
+export type DisconnectInput = Schema.Schema.Type<typeof DisconnectInputSchema>;
+/** Private to the Team owner and its trusted custodian adapter. */
+export type RepositoryAccess = Readonly<{
+    locator: string;
+    repository: RepositoryScope;
+}>;
+export type PreparedCompletion = Readonly<{
+    status: "pending";
+    attempt: ConnectionAttempt;
+}> | Readonly<{
+    status: "completed";
+    receipt: ConnectionReceipt;
+}>;
+/** Why a verified completion's Nango connection is not held by the Team. */
+export type OrphanCode = "expired" | "denied" | "conflict" | "reconnect_required";
+/** A verified completion is held (completed), still activatable (pending), or an
+ * orphan whose external connection the Team will never hold. */
+export type CompletionDecision = PreparedCompletion | Readonly<{
+    status: "orphaned";
+    code: OrphanCode;
+}>;
+/** Terminal custodian evidence that the held credential no longer works. */
+export type ReconnectReason = "refresh_failed" | "provider_unauthorized";
+export type ReconnectOutcome = Readonly<{
+    status: "reconnect_required";
+    connectionId: string;
+}> | Readonly<{
+    status: "not_held";
+}>;
+/** Signed Nango auth webhooks this Team handles; every other operation is refused. */
+export type VerifiedWebhook = Readonly<{
+    operation: "creation" | "refresh_failed";
+    completion: VerifiedCompletion;
+}>;
+export type CleanupWork = Readonly<{
+    connectionId: string;
+    authorityVersion: number;
+    locator: string;
+}>;
+declare const completionLookupSchema: 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;
+    }>;
+}>]>;
+/** Private Team operations. Mutations may await the native SQL+wake commit. */
+export type TeamConnectionsOwner = Readonly<{
+    begin: (input: ConnectInput) => PreparedCompletion;
+    readAttempt: (input: ConnectInput) => PreparedCompletion;
+    prepareCompletion: (input: VerifiedCompletion) => CompletionDecision;
+    /** Records the settled external deletion of a connection the Team never held. */
+    recordOrphan: (input: VerifiedCompletion, code: OrphanCode, custody: "deleted" | "absent") => void;
+    /** Marks the active Connection holding this locator as needing reconnection. */
+    requireReconnect: (locator: string, reason: ReconnectReason) => ReconnectOutcome;
+    activate: (input: VerifiedCompletion, repository: GitHubRepository) => ConnectionReceipt | Promise<ConnectionReceipt>;
+    authorize: (binding: ReadBinding) => RepositoryAccess;
+    disconnect: (input: DisconnectInput) => ConnectionReceipt | Promise<ConnectionReceipt>;
+    nextCleanup: () => CleanupWork | undefined;
+    acknowledgeCleanup: (work: CleanupWork) => void;
+}>;
+/** Ordinary Promise port. Only this trusted edge touches external custody. */
+export type CredentialCustodian = Readonly<{
+    openSession: (input: Readonly<{
+        teamId: string;
+        attemptId: string;
+        principalId: string;
+        integrationId: string;
+    }>, signal: AbortSignal) => Promise<Readonly<{
+        token: string;
+        connectUrl: string;
+        expiresAt: number;
+    }>>;
+    /** Connection creation only; refuses every other signed operation. */
+    verifyCompletion: (rawBody: string, signature: string) => Promise<VerifiedCompletion>;
+    verifyWebhook: (rawBody: string, signature: string) => Promise<VerifiedWebhook>;
+    /** Verified means supported complete correlation, never an arbitrary list-page candidate. */
+    findCompletion: (attempt: CustodyCorrelation, signal: AbortSignal) => Promise<Schema.Schema.Type<typeof completionLookupSchema>>;
+    /** Only confirmed deletion or a specifically decoded missing-connection result settles cleanup. */
+    deleteConnection: (locator: string, signal: AbortSignal) => Promise<"deleted" | "absent">;
+    readRepository: (access: RepositoryAccess, signal: AbortSignal) => Promise<string>;
+}>;
+/** Sanitized public failure; an optional cause is retained internally only. */
+export declare class VeilError extends Error {
+    readonly code: "denied" | "invalid_input" | "invalid_completion" | "invalid_response" | "conflict" | "ambiguous" | "expired" | "unavailable" | "github_not_configured" | "cancelled" | "reconnect_required" | "unsupported"
+    /** GitHub refused the repository: it is outside the App installation. */
+     | "repository_not_installed"
+    /** The provider's rate limit refused this request; retry later. */
+     | "rate_limited";
+    constructor(code: "denied" | "invalid_input" | "invalid_completion" | "invalid_response" | "conflict" | "ambiguous" | "expired" | "unavailable" | "github_not_configured" | "cancelled" | "reconnect_required" | "unsupported"
+    /** GitHub refused the repository: it is outside the App installation. */
+     | "repository_not_installed"
+    /** The provider's rate limit refused this request; retry later. */
+     | "rate_limited", cause?: unknown);
+}
+/** One Effect policy behind the ordinary connect and GitHub Gatekeeper calls. */
+export declare function createGitHubConnections(options: Readonly<{
+    owner: TeamConnectionsOwner;
+    custodian: CredentialCustodian;
+}>): {
+    connect: (input: ConnectInput, signal?: AbortSignal) => Promise<Readonly<{
+        status: "completed";
+        receipt: ConnectionReceipt;
+    }> | {
+        token: string;
+        connectUrl: string;
+        expiresAt: number;
+        status: "pending";
+        attemptId: string;
+    }>;
+    /** The one entry for signed custodian webhooks: activation or reconnect evidence. */
+    complete: (rawBody: string, signature: string, signal?: AbortSignal) => Promise<{
+        readonly requestId: string;
+        readonly connectionId: string;
+        readonly holderAgentId: string;
+        readonly repository: {
+            readonly id: number;
+            readonly owner: string;
+            readonly name: string;
+        };
+        readonly authorityVersion: number;
+        readonly status: "active" | "disconnected";
+        readonly cleanup: "none" | "pending";
+    } | ReconnectOutcome>;
+    reconcile: (input: ConnectInput, signal?: AbortSignal) => Promise<Readonly<{
+        status: "completed";
+        receipt: ConnectionReceipt;
+    }> | {
+        status: "pending";
+        attemptId: string;
+    }>;
+    /** One bounded host recovery call; durable pending work survives interrupted or uncertain deletion. */
+    cleanupOne: (signal?: AbortSignal) => Promise<{
+        status: "idle";
+        connectionId?: never;
+        authorityVersion?: never;
+        custody?: never;
+    } | {
+        status: "completed";
+        connectionId: string;
+        authorityVersion: number;
+        custody: "deleted" | "absent";
+    }>;
+    readRepository: (binding: ReadBinding, signal?: AbortSignal) => Promise<{
+        id: number;
+        name: string;
+        fullName: string;
+        private: boolean;
+        defaultBranch: string;
+    }>;
+    disconnect: (input: DisconnectInput) => Promise<{
+        readonly requestId: string;
+        readonly connectionId: string;
+        readonly holderAgentId: string;
+        readonly repository: {
+            readonly id: number;
+            readonly owner: string;
+            readonly name: string;
+        };
+        readonly authorityVersion: number;
+        readonly status: "active" | "disconnected";
+        readonly cleanup: "none" | "pending";
+    }>;
+};
+export type GitHubConnections = ReturnType<typeof createGitHubConnections>;
+export {};