@fungi.computer/veil 0.4.0 → 0.5.0

package/dist/connections/oauth-flow.js

@@ -0,0 +1,322 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import { assertPublicHostName } from "../model-key-network.js";
+import { ConnectionsError, identifier, } from "./contract.js";
+import { decode, io, sync, } from "./internal.js";
+import { finishStaticAuthorization, refreshStaticTokens, startStaticAuthorization, } from "./oauth-provider.js";
+import { finishAuthorization, oauthBundleJson, oauthClientJson, refreshTokens, startAuthorization, tokenExpired, } from "./oauth.js";
+/** Discovery, sign-in, token refresh and the registered-client record for OAuth connections. */
+export function createOAuthFlow(deps) {
+    const { ownerId, custody, store } = deps;
+    const address = (row) => ({
+        ownerId,
+        connectionId: row.id,
+        credential: row.credential,
+    });
+    const oauthPorts = () => {
+        const ports = deps.oauth;
+        const open = custody.open;
+        if (ports === undefined || open === undefined)
+            throw new ConnectionsError("unsupported");
+        return { ...ports, open };
+    };
+    /** Every discovery, registration and token request meets the same destination rules. */
+    const guardedFetch = async (url, init) => {
+        const ports = oauthPorts();
+        const request = new Request(url, { ...init, redirect: "error" });
+        const target = new URL(request.url);
+        if (target.protocol !== "https:" || target.username || target.password)
+            throw new ConnectionsError("denied");
+        try {
+            assertPublicHostName(target.hostname);
+            deps.policy.destination(target);
+        }
+        catch (cause) {
+            throw new ConnectionsError("denied", { cause });
+        }
+        return ports.fetch(request);
+    };
+    /** The operator's registered provider by id; a bundle naming one this host no longer holds cannot be used. */
+    const staticProvider = (id) => {
+        if (id === undefined)
+            return undefined;
+        const found = deps.oauth?.providers?.[id];
+        if (found === undefined)
+            throw new ConnectionsError("reconnect_required");
+        return found;
+    };
+    const clientAddress = () => ({
+        ownerId,
+        connectionId: "oauth-clients",
+        credential: { kind: "oauth" },
+    });
+    /** One registered client per authorization server, sealed in custody. */
+    const registry = {
+        lookup: (issuer) => Effect.runPromise(Effect.gen(function* () {
+            const found = yield* sync(() => store.clientLocator(issuer));
+            if (found === undefined)
+                return undefined;
+            const raw = yield* sync(oauthPorts).pipe(Effect.flatMap((ports) => ports.open(clientAddress(), found)));
+            return yield* sync(() => decode(oauthClientJson, raw));
+        })),
+        save: (issuer, client) => Effect.runPromise(Effect.gen(function* () {
+            const locator = yield* custody.put(clientAddress(), Schema.encodeSync(oauthClientJson)(client));
+            yield* sync(() => {
+                store.saveClientLocator(issuer, locator);
+            });
+        })),
+    };
+    const readBundle = (row, locator) => sync(oauthPorts).pipe(Effect.flatMap((ports) => ports.open(address(row), locator)), Effect.flatMap((raw) => Effect.try({
+        try: () => Schema.decodeUnknownSync(oauthBundleJson)(raw),
+        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 connect = custody.connect;
+        const integrationId = credential.provider;
+        if (connect === undefined || integrationId === undefined)
+            return yield* Effect.fail(new ConnectionsError("unsupported"));
+        const connectionId = deps.ids();
+        const state = `${ownerId}.${deps.ids()}`;
+        yield* sync(() => decode(identifier, connectionId));
+        const session = yield* connect({ ownerId, connectionId, credential }, { state, actor, integrationId });
+        const stored = {
+            id: connectionId,
+            name: draft.name,
+            credential,
+            locator: null,
+            state: "pending",
+            authorityVersion: 1,
+            version: 1,
+            surface: {
+                kind: openapi === null ? "mcp" : "openapi",
+                url: endpoint,
+                table: openapi?.table ?? null,
+                digest: openapi?.digest ?? null,
+                label: draft.label ?? draft.name,
+            },
+        };
+        return yield* sync(() => {
+            store.recordPending({
+                actor,
+                connection: stored,
+                state,
+                attemptLocator: null,
+                issuer: `custody:${integrationId}`,
+                requestId: draft.requestId,
+                fingerprint,
+                authorizeUrl: session.connectUrl,
+            });
+            return { connectionId, authorizeUrl: session.connectUrl };
+        });
+    });
+    /**
+     * The custodian says an authorization finished. The host has already
+     * verified its signature; the state is single use and expiring, and the
+     * connection is not live until this settles it.
+     */
+    const completeCustody = (input) => Effect.gen(function* () {
+        const claimed = yield* sync(() => store.claimCustody(input.state));
+        if (claimed.expired)
+            return yield* Effect.fail(new ConnectionsError("denied"));
+        if (claimed.attempt.issuer !== `custody:${input.integrationId}`)
+            return yield* Effect.fail(new ConnectionsError("denied"));
+        const row = yield* sync(() => store.connection(claimed.attempt.connectionId));
+        const activated = yield* sync(() => store.activate(row, claimed.attempt, input.locator));
+        if (!activated) {
+            yield* sync(() => {
+                store.discard(row.id, input.locator, row.credential);
+            });
+            return yield* Effect.fail(new ConnectionsError("revoked"));
+        }
+        yield* deps.sweep();
+        return { connectionId: row.id };
+    });
+    const begin = (actor, draft, credential, endpoint, fingerprint, 
+    /** The decoded operation table of a REST connection, when that is what signs in. */
+    openapi) => Effect.gen(function* () {
+        const ports = yield* sync(oauthPorts);
+        const connectionId = deps.ids();
+        const state = `${ownerId}.${deps.ids()}`;
+        yield* sync(() => decode(identifier, connectionId));
+        let client;
+        if (credential.clientId !== undefined) {
+            client = { client_id: credential.clientId };
+            if (draft.secret !== undefined)
+                client.client_secret = draft.secret;
+        }
+        const started = yield* io(() => {
+            const provider = staticProvider(credential.provider);
+            return provider === undefined
+                ? startAuthorization({
+                    serverUrl: endpoint,
+                    scope: credential.scope,
+                    client,
+                    callbackUrl: ports.callbackUrl,
+                    state,
+                    registry,
+                    fetch: guardedFetch,
+                })
+                : startStaticAuthorization({
+                    providerId: credential.provider ?? "",
+                    provider,
+                    scope: credential.scope,
+                    callbackUrl: ports.callbackUrl,
+                    state,
+                });
+        });
+        const attemptLocator = yield* custody.put({ ownerId, connectionId, credential }, Schema.encodeSync(oauthBundleJson)(started.bundle));
+        const stored = {
+            id: connectionId,
+            name: draft.name,
+            credential,
+            locator: null,
+            state: "pending",
+            authorityVersion: 1,
+            version: 1,
+            surface: {
+                kind: openapi === null ? "mcp" : "openapi",
+                url: endpoint,
+                table: openapi?.table ?? null,
+                digest: openapi?.digest ?? null,
+                label: draft.label ?? draft.name,
+            },
+        };
+        return yield* sync(() => {
+            store.recordPending({
+                actor,
+                connection: stored,
+                state,
+                attemptLocator,
+                issuer: started.bundle.authorizationServerUrl,
+                requestId: draft.requestId,
+                fingerprint,
+                authorizeUrl: started.authorizeUrl,
+            });
+            return { connectionId, authorizeUrl: started.authorizeUrl };
+        }).pipe(Effect.tapError(() => sync(() => {
+            store.discard(connectionId, attemptLocator, credential);
+        })));
+    });
+    /**
+     * The browser's return from the authorization server. The state is single
+     * use, expiring and bound to the actor who began; the SDK checks the issuer
+     * and PKCE before the code is redeemed.
+     */
+    const complete = (actor, input) => Effect.gen(function* () {
+        const ports = yield* sync(oauthPorts);
+        const claimed = yield* sync(() => store.claim(actor, input));
+        if (claimed.expired)
+            return yield* Effect.fail(new ConnectionsError("denied"));
+        const { attempt, wanted } = claimed;
+        const row = yield* sync(() => store.connection(attempt.connectionId));
+        const attemptLocator = attempt.pkceVerifierSealed ?? "";
+        const settled = Effect.gen(function* () {
+            const bundle = yield* readBundle(row, attemptLocator);
+            const provider = staticProvider(bundle.provider);
+            const next = yield* io(() => provider === undefined
+                ? finishAuthorization({
+                    serverUrl: row.surface.url,
+                    callbackUrl: ports.callbackUrl,
+                    bundle,
+                    code: wanted.code,
+                    iss: wanted.iss,
+                    now: deps.clock(),
+                    fetch: guardedFetch,
+                })
+                : finishStaticAuthorization({
+                    provider,
+                    bundle,
+                    callbackUrl: ports.callbackUrl,
+                    code: wanted.code,
+                    iss: wanted.iss,
+                    now: deps.clock(),
+                    fetch: guardedFetch,
+                }));
+            return yield* custody.put(address(row), Schema.encodeSync(oauthBundleJson)(next));
+        }).pipe(Effect.tapError(() => sync(() => {
+            store.fail(attempt);
+        })));
+        const locator = yield* settled;
+        const activated = yield* sync(() => store.activate(row, attempt, locator));
+        if (!activated) {
+            // Revoked while the code was in flight: nothing may come back to life.
+            yield* sync(() => {
+                store.discard(row.id, locator, row.credential);
+            });
+            return yield* Effect.fail(new ConnectionsError("revoked"));
+        }
+        yield* deps.sweep();
+        return { connectionId: row.id };
+    });
+    /** One refresh at a time per connection; later callers share its outcome. */
+    const flights = new Map();
+    const refreshLocator = (id, stale) => {
+        const running = flights.get(id);
+        if (running !== undefined)
+            return running;
+        const flight = Effect.runPromise(refreshOnce(id, stale)).finally(() => {
+            flights.delete(id);
+        });
+        flights.set(id, flight);
+        return flight;
+    };
+    const refreshOnce = (id, stale) => Effect.gen(function* () {
+        const row = yield* sync(() => store.connection(id));
+        if (row.state === "revoked")
+            return yield* Effect.fail(new ConnectionsError("revoked"));
+        if (row.state !== "active" || row.locator === null)
+            return yield* Effect.fail(new ConnectionsError("reconnect_required"));
+        // A flight that just ended already replaced the token this caller saw.
+        if (row.locator !== stale)
+            return row.locator;
+        const held = row.locator;
+        const bundle = yield* readBundle(row, held);
+        const provider = staticProvider(bundle.provider);
+        const next = yield* io(() => provider === undefined
+            ? refreshTokens({ bundle, now: deps.clock(), fetch: guardedFetch })
+            : refreshStaticTokens({
+                provider,
+                bundle,
+                now: deps.clock(),
+                fetch: guardedFetch,
+            }));
+        // Persist the rotated token before anything uses it.
+        const locator = yield* custody.put(address(row), Schema.encodeSync(oauthBundleJson)(next));
+        const outcome = yield* sync(() => store.swap(row, held, locator));
+        if (outcome !== "applied") {
+            // Revoked or replaced during the refresh: the new token never lives.
+            yield* sync(() => {
+                store.discard(id, locator, row.credential);
+            });
+            return yield* Effect.fail(new ConnectionsError(outcome === "revoked" ? "revoked" : "conflict"));
+        }
+        return locator;
+    });
+    const unauthorized = (response) => io(async () => {
+        await response.body?.cancel();
+    });
+    /** Send with the live token: refresh early when it is about to expire, and once on a 401. */
+    const send = (row, request) => Effect.gen(function* () {
+        let locator = row.locator;
+        if (locator === null)
+            return yield* Effect.fail(new ConnectionsError("reconnect_required"));
+        const bundle = yield* readBundle(row, locator);
+        if (tokenExpired(bundle, deps.clock())) {
+            const stale = locator;
+            locator = yield* io(() => refreshLocator(row.id, stale));
+        }
+        const first = yield* custody.inject(address(row), locator, request.clone());
+        if (first.status !== 401)
+            return first;
+        yield* unauthorized(first);
+        const stale = locator;
+        const fresh = yield* io(() => refreshLocator(row.id, stale));
+        const second = yield* custody.inject(address(row), fresh, request.clone());
+        if (second.status !== 401)
+            return second;
+        yield* unauthorized(second);
+        return yield* Effect.fail(new ConnectionsError("reconnect_required"));
+    });
+    return { begin, beginCustody, complete, completeCustody, send };
+}

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

@@ -0,0 +1,31 @@
+import type { FetchLike } from "@modelcontextprotocol/client";
+import { type StaticOAuthProvider } from "./contract.js";
+import type { OAuthBundle } from "./oauth.js";
+/** PKCE redirect for an operator-registered provider. */
+export declare function startStaticAuthorization(input: {
+    providerId: string;
+    provider: StaticOAuthProvider;
+    scope: string | undefined;
+    callbackUrl: string;
+    state: string;
+}): Promise<{
+    authorizeUrl: string;
+    bundle: OAuthBundle;
+}>;
+/** Redeem the code; the SDK validates `iss` against the provider's issuer. */
+export declare function finishStaticAuthorization(input: {
+    provider: StaticOAuthProvider;
+    bundle: OAuthBundle;
+    callbackUrl: string;
+    code: string;
+    iss: string | undefined;
+    now: number;
+    fetch: FetchLike;
+}): Promise<OAuthBundle>;
+/** One refresh grant against the provider's own token endpoint. */
+export declare function refreshStaticTokens(input: {
+    provider: StaticOAuthProvider;
+    bundle: OAuthBundle;
+    now: number;
+    fetch: FetchLike;
+}): Promise<OAuthBundle>;

package/dist/connections/oauth-provider.js

@@ -0,0 +1,96 @@
+import { ConnectionsError } from "./contract.js";
+const metadataOf = (provider) => ({
+    issuer: provider.issuer,
+    authorization_endpoint: provider.authorizationEndpoint,
+    token_endpoint: provider.tokenEndpoint,
+    response_types_supported: ["code"],
+    code_challenge_methods_supported: ["S256"],
+    token_endpoint_auth_methods_supported: [
+        provider.client.client_secret === undefined ? "none" : "client_secret_post",
+    ],
+});
+const clientOf = (client) => client.client_secret === undefined
+    ? { client_id: client.client_id }
+    : { client_id: client.client_id, client_secret: client.client_secret };
+/** PKCE redirect for an operator-registered provider. */
+export async function startStaticAuthorization(input) {
+    const sdk = await import("@modelcontextprotocol/client");
+    const scope = input.scope ?? input.provider.scope;
+    const request = {
+        metadata: metadataOf(input.provider),
+        clientInformation: clientOf(input.provider.client),
+        redirectUrl: input.callbackUrl,
+        state: input.state,
+    };
+    if (scope !== undefined)
+        request.scope = scope;
+    const started = await sdk.startAuthorization(input.provider.issuer, request);
+    return {
+        authorizeUrl: started.authorizationUrl.href,
+        bundle: {
+            authorizationServerUrl: input.provider.issuer,
+            provider: input.providerId,
+            client: input.provider.client,
+            codeVerifier: started.codeVerifier,
+            resource: undefined,
+            tokens: undefined,
+        },
+    };
+}
+/** Redeem the code; the SDK validates `iss` against the provider's issuer. */
+export async function finishStaticAuthorization(input) {
+    const { bundle } = input;
+    if (bundle.codeVerifier === undefined)
+        throw new ConnectionsError("denied");
+    const sdk = await import("@modelcontextprotocol/client");
+    const request = {
+        metadata: metadataOf(input.provider),
+        clientInformation: clientOf(input.provider.client),
+        authorizationCode: input.code,
+        codeVerifier: bundle.codeVerifier,
+        redirectUri: input.callbackUrl,
+        fetchFn: input.fetch,
+    };
+    if (input.iss !== undefined)
+        request.iss = input.iss;
+    const tokens = await sdk.exchangeAuthorization(input.provider.issuer, request);
+    return {
+        ...bundle,
+        codeVerifier: undefined,
+        tokens: {
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token,
+            expires_in: tokens.expires_in,
+            obtainedAt: input.now,
+        },
+    };
+}
+/** One refresh grant against the provider's own token endpoint. */
+export async function refreshStaticTokens(input) {
+    const held = input.bundle.tokens?.refresh_token;
+    if (held === undefined)
+        throw new ConnectionsError("reconnect_required");
+    const sdk = await import("@modelcontextprotocol/client");
+    try {
+        const fresh = await sdk.refreshAuthorization(input.provider.issuer, {
+            metadata: metadataOf(input.provider),
+            clientInformation: clientOf(input.provider.client),
+            refreshToken: held,
+            fetchFn: input.fetch,
+        });
+        return {
+            ...input.bundle,
+            tokens: {
+                access_token: fresh.access_token,
+                refresh_token: fresh.refresh_token ?? held,
+                expires_in: fresh.expires_in,
+                obtainedAt: input.now,
+            },
+        };
+    }
+    catch (cause) {
+        if (sdk.OAuthError.isInstance(cause) && cause.code === "invalid_grant")
+            throw new ConnectionsError("reconnect_required", { cause });
+        throw cause;
+    }
+}

package/dist/connections/oauth.d.ts

@@ -0,0 +1,93 @@
+import type { FetchLike } from "@modelcontextprotocol/client";
+import * as Schema from "effect/Schema";
+declare const clientSchema: Schema.Struct<{
+    readonly client_id: Schema.String;
+    readonly client_secret: Schema.optional<Schema.String>;
+}>;
+/**
+ * Everything custody seals for one OAuth connection or attempt: the client,
+ * the authorization server it was issued by, the PKCE verifier while an
+ * attempt is pending, and the token set once it completes.
+ */
+declare const oauthBundleSchema: Schema.Struct<{
+    readonly authorizationServerUrl: Schema.String;
+    /** The operator-registered provider this was issued by, when there is one. */
+    readonly provider: Schema.optional<Schema.String>;
+    readonly resource: Schema.optional<Schema.String>;
+    readonly client: Schema.Struct<{
+        readonly client_id: Schema.String;
+        readonly client_secret: Schema.optional<Schema.String>;
+    }>;
+    readonly codeVerifier: Schema.optional<Schema.String>;
+    readonly tokens: Schema.optional<Schema.Struct<{
+        readonly access_token: Schema.String;
+        readonly refresh_token: Schema.optional<Schema.String>;
+        /** Seconds the access token lives, as the authorization server said. */
+        readonly expires_in: Schema.optional<Schema.Number>;
+        readonly obtainedAt: Schema.Number;
+    }>>;
+}>;
+export type OAuthBundle = typeof oauthBundleSchema.Type;
+export type OAuthClient = typeof clientSchema.Type;
+export declare const oauthClientJson: Schema.fromJsonString<Schema.Struct<{
+    readonly client_id: Schema.String;
+    readonly client_secret: Schema.optional<Schema.String>;
+}>>;
+export declare const oauthBundleJson: Schema.fromJsonString<Schema.Struct<{
+    readonly authorizationServerUrl: Schema.String;
+    /** The operator-registered provider this was issued by, when there is one. */
+    readonly provider: Schema.optional<Schema.String>;
+    readonly resource: Schema.optional<Schema.String>;
+    readonly client: Schema.Struct<{
+        readonly client_id: Schema.String;
+        readonly client_secret: Schema.optional<Schema.String>;
+    }>;
+    readonly codeVerifier: Schema.optional<Schema.String>;
+    readonly tokens: Schema.optional<Schema.Struct<{
+        readonly access_token: Schema.String;
+        readonly refresh_token: Schema.optional<Schema.String>;
+        /** Seconds the access token lives, as the authorization server said. */
+        readonly expires_in: Schema.optional<Schema.Number>;
+        readonly obtainedAt: Schema.Number;
+    }>>;
+}>>;
+/** Registered clients are reused for every connection to the same issuer. */
+export type ClientRegistry = Readonly<{
+    lookup: (issuer: string) => Promise<OAuthClient | undefined>;
+    save: (issuer: string, client: OAuthClient) => Promise<void>;
+}>;
+export declare const tokenExpired: (bundle: OAuthBundle, now: number) => boolean;
+export type OAuthStart = Readonly<{
+    serverUrl: string;
+    scope: string | undefined;
+    client: OAuthClient | undefined;
+    callbackUrl: string;
+    state: string;
+    registry: ClientRegistry;
+    fetch: FetchLike;
+}>;
+/** Discovery, registration and PKCE through the SDK; returns the redirect and the sealed attempt. */
+export declare function startAuthorization(input: OAuthStart): Promise<{
+    authorizeUrl: string;
+    bundle: OAuthBundle;
+}>;
+/** Redeem the code; the SDK validates `iss` and PKCE. The issuer must be the one the attempt began with. */
+export declare function finishAuthorization(input: {
+    serverUrl: string;
+    callbackUrl: string;
+    bundle: OAuthBundle;
+    code: string;
+    iss: string | undefined;
+    now: number;
+    fetch: FetchLike;
+}): Promise<OAuthBundle>;
+/**
+ * One refresh grant. A rotated refresh token replaces the old one; the caller
+ * persists the returned bundle before using the new access token.
+ */
+export declare function refreshTokens(input: {
+    bundle: OAuthBundle;
+    now: number;
+    fetch: FetchLike;
+}): Promise<OAuthBundle>;
+export {};