@zackbart/connecta 0.7.5 → 0.7.7

package/dist/server.js

@@ -8,7 +8,10 @@ import { credentialTestRule, describeCredentialTestMismatch, storedCredentialSha
 import { ScopedRegistry } from "./registry.js";
 import { resolveIdentityBinding, TOOLKIT_NAME_RE, } from "./toolkits.js";
 import { CONNECTA_FAVICON_ICO } from "./favicon.js";
-import { buildUiData, CONNECTA_FAVICON_SVG, credentialManagementCapability, operatorPageForPath, resolveBranding, renderUiHtml, } from "./ui.js";
+import { ExecutorAdmissionError, isAdmittingExecutor, } from "./executor-admission.js";
+import { buildUiData, CONNECTA_FAVICON_SVG, credentialManagementCapability, isSafeHttpUrl, operatorPageForPath, resolveBranding, renderUiHtml, } from "./ui.js";
+import { oauthValueStorageKey } from "./auth/downstream-oauth.js";
+import { closeConnectorScope, } from "./connector-scope.js";
 const CORS_HEADERS = {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
@@ -158,11 +161,15 @@ async function authorize(request, baseUrl, auth, logger) {
                     "which toolkits the identity may use.");
                 return { ok: false, response: unusableBinding() };
             }
+            const actorNamespace = activityActorNamespace(provider);
             return {
                 ok: true,
                 actor: {
                     kind: provider.kind,
                     ...(subjectId ? { id: subjectId } : {}),
+                    ...(subjectId && actorNamespace
+                        ? { namespace: actorNamespace }
+                        : {}),
                 },
                 ...(result.userId && provider.uiAuth?.kind === "clerk"
                     ? { uiAdminEligible: true }
@@ -199,13 +206,102 @@ function withMcpCors(response) {
     for (const [name, value] of Object.entries(CORS_HEADERS)) {
         headers.set(name, value);
     }
-    headers.set("Access-Control-Expose-Headers", "WWW-Authenticate, mcp-session-id, mcp-protocol-version");
+    headers.set("Access-Control-Expose-Headers", "WWW-Authenticate, Retry-After, mcp-session-id, mcp-protocol-version");
     return new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
         headers,
     });
 }
+function requestAdmissionFailure(error) {
+    const overloaded = error.code === "executor_overloaded";
+    const data = {
+        code: overloaded ? "server_overloaded" : "server_shutting_down",
+        retryable: overloaded,
+        ...(overloaded && error.retryAfterMs !== undefined
+            ? { retryAfterMs: error.retryAfterMs }
+            : {}),
+    };
+    const headers = new Headers({
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+    });
+    if (overloaded && error.retryAfterMs !== undefined) {
+        headers.set("Retry-After", String(Math.max(1, Math.ceil(error.retryAfterMs / 1_000))));
+    }
+    return new Response(JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+            code: overloaded ? -32001 : -32002,
+            message: overloaded
+                ? "Server capacity is exhausted. Retry later."
+                : "Server is shutting down.",
+            data,
+        },
+    }), { status: 503, headers });
+}
+/**
+ * A request owns its permit through the response body, not merely until the
+ * handler returns. This is what makes slow clients and response-stream failure
+ * part of the same bounded lifecycle as success, error, and cancellation.
+ */
+function releaseAdmissionWithResponse(response, lease, signal) {
+    let released = false;
+    let onAbort = () => { };
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        signal.removeEventListener("abort", onAbort);
+        lease.release();
+    };
+    if (!response.body) {
+        release();
+        return response;
+    }
+    const reader = response.body.getReader();
+    onAbort = () => {
+        // `cancel()` belongs to an operator/auth/SDK-provided stream and may
+        // reject. Consume both outcomes: `.finally(release)` would release the
+        // permit but preserve the rejection as an unhandled promise.
+        void reader.cancel(signal.reason).then(release, release);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted)
+        onAbort();
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await reader.read();
+                if (next.done) {
+                    release();
+                    controller.close();
+                }
+                else {
+                    controller.enqueue(next.value);
+                }
+            }
+            catch (error) {
+                release();
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            try {
+                await reader.cancel(reason);
+            }
+            finally {
+                release();
+            }
+        },
+    });
+    return new Response(body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
 function withSecurityHeaders(response, requestUrl, path) {
     const headers = new Headers(response.headers);
     headers.set("X-Content-Type-Options", "nosniff");
@@ -228,10 +324,10 @@ function withSecurityHeaders(response, requestUrl, path) {
         headers,
     });
 }
-async function authorizeUiAdmin(request, baseUrl, auth, logger) {
-    // Credential mutation is intentionally narrower than /mcp and /ui/data: only
+async function authorizeUiAdmin(request, baseUrl, auth, logger, purpose = "credential management") {
+    // Operator mutation is intentionally narrower than /mcp and /ui/data: only
     // an interactive Clerk provider may admit it. A static bearer token is useful
-    // for headless tool calls but must not become a vault-admin key.
+    // for headless tool calls but must not become a deployment-admin key.
     //
     // EVERY Clerk provider gets a turn, the way the /mcp gate does, because the
     // documented per-team pattern is several `clerkAuth(...)`s that differ only in
@@ -244,7 +340,7 @@ async function authorizeUiAdmin(request, baseUrl, auth, logger) {
     if (providers.length === 0) {
         return {
             ok: false,
-            response: privateJson({ error: "credential management requires Clerk authentication" }, { status: 403 }),
+            response: privateJson({ error: `${purpose} requires Clerk authentication` }, { status: 403 }),
         };
     }
     let lastResponse = null;
@@ -260,7 +356,7 @@ async function authorizeUiAdmin(request, baseUrl, auth, logger) {
         }
         const binding = resolveIdentityBinding(provider.toolkitBinding, result.toolkitBinding);
         if (!binding.ok) {
-            logger.warn(`[connecta] refused a credential-API request admitted by inbound auth ` +
+            logger.warn(`[connecta] refused an operator-mutation request admitted by inbound auth ` +
                 `provider "${provider.kind}" with 403: ${binding.reason}.`);
             lastResponse = unusableBinding();
             continue;
@@ -431,7 +527,7 @@ async function handleCredentialRequest(request, connectorId, action, opts, baseU
             const metadata = input.input.kind === "single"
                 ? await opts.credentialVault.set(connectorId, input.input.value, admin.userId)
                 : await opts.credentialVault.setAll(connectorId, input.input.values, admin.userId);
-            opts.registry.invalidate(connectorId);
+            await opts.registry.invalidateStored(connectorId);
             // The credential the last verdict judged is gone; judging its replacement
             // is the next check's job, not this one's.
             await opts.registry.clearCredentialHealth(connectorId);
@@ -443,7 +539,7 @@ async function handleCredentialRequest(request, connectorId, action, opts, baseU
     }
     if (request.method === "DELETE") {
         await opts.credentialVault.delete(connectorId);
-        opts.registry.invalidate(connectorId);
+        await opts.registry.invalidateStored(connectorId);
         await opts.registry.clearCredentialHealth(connectorId);
         return new Response(null, {
             status: 204,
@@ -455,6 +551,79 @@ async function handleCredentialRequest(request, connectorId, action, opts, baseU
     }
     return privateJson({ error: "method not allowed" }, { status: 405 });
 }
+async function handleOAuthManagementRequest(request, connectorId, opts, baseUrl, defer) {
+    if (!isSameOrigin(request, baseUrl)) {
+        return privateJson({ error: "same-origin request required" }, { status: 403 });
+    }
+    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, opts.logger, "OAuth management");
+    if (!admin.ok)
+        return admin.response;
+    const connector = opts.registry.getConnector(connectorId);
+    if (!connector?.disconnectAuth || !connector.startAuth) {
+        return privateJson({ error: "unknown OAuth connector" }, { status: 404 });
+    }
+    if (request.method !== "DELETE" && request.method !== "POST") {
+        return privateJson({ error: "method not allowed" }, { status: 405 });
+    }
+    const requestScope = {};
+    const ctx = opts.registry.contextFor(connectorId, baseUrl, requestScope);
+    try {
+        let result;
+        let operationError;
+        try {
+            if (request.method === "DELETE") {
+                await connector.disconnectAuth(ctx);
+            }
+            else {
+                result = await connector.startAuth(ctx, { force: true });
+            }
+        }
+        catch (error) {
+            operationError = error;
+        }
+        // The old grant and its catalog verdict are invalid after either operation,
+        // including a partially failed physical cleanup whose epoch fence succeeded.
+        try {
+            await opts.registry.invalidateStored(connectorId);
+            await opts.registry.clearCredentialHealth(connectorId);
+        }
+        catch (error) {
+            operationError ??= error;
+        }
+        if (operationError) {
+            return privateJson({ error: msg(operationError) }, { status: 400 });
+        }
+        if (request.method === "DELETE") {
+            return new Response(null, {
+                status: 204,
+                headers: {
+                    "Cache-Control": "no-store",
+                    "Referrer-Policy": "no-referrer",
+                },
+            });
+        }
+        const authorizationUrl = isSafeHttpUrl(result.authorizationUrl)
+            ? result.authorizationUrl
+            : undefined;
+        if (result.state === "error") {
+            return privateJson({ error: result.message || "OAuth authorization could not start" }, { status: 502 });
+        }
+        if (result.state === "auth_required" && !authorizationUrl) {
+            return privateJson({
+                error: result.message ||
+                    "OAuth authorization requires consent but no safe URL is available",
+            }, { status: 502 });
+        }
+        return privateJson({
+            state: result.state,
+            ...(result.message ? { message: result.message } : {}),
+            ...(authorizationUrl ? { authorizationUrl } : {}),
+        });
+    }
+    finally {
+        await closeConnectorScope(connector, ctx, defer);
+    }
+}
 /** Length beyond which a rejected toolkit name is not echoed back. */
 const MAX_ECHOED_TOOLKIT_NAME = 64;
 /**
@@ -504,6 +673,138 @@ function toolkitForbidden() {
 function identityLabel(actor) {
     return actor.id ? `${actor.kind} ${loggableValue(actor.id)}` : actor.kind;
 }
+const ACTIVITY_ACTOR_NAMESPACE_RE = /^[\x21-\x7e]{1,256}$/;
+const ACTIVITY_LABEL_CONCURRENCY = 8;
+const ACTIVITY_LABEL_PAGE_BUDGET_MS = 1_500;
+const ACTIVITY_LABEL_MAX_LENGTH = 160;
+function activityActorNamespace(provider) {
+    return typeof provider.activityActorNamespace === "string" &&
+        ACTIVITY_ACTOR_NAMESPACE_RE.test(provider.activityActorNamespace)
+        ? provider.activityActorNamespace
+        : undefined;
+}
+function cleanActivityActorLabel(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const compact = value.replace(/\s+/gu, " ").trim();
+    if (!compact)
+        return undefined;
+    return Array.from(compact).slice(0, ACTIVITY_LABEL_MAX_LENGTH).join("");
+}
+async function boundedActivityActorLabel(hook, id, budgetMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve(hook(id))
+                .then(cleanActivityActorLabel)
+                .catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, budgetMs);
+            }),
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Add display-only actor labels to one authorized activity page. Resolution is
+ * best-effort, bounded, and read-time only: stored events retain stable ids and
+ * a profile-provider outage falls back to those ids without failing the page.
+ */
+async function enrichActivityActorLabels(page, auth) {
+    const identities = new Map();
+    for (const event of page.events) {
+        if (!event.actor.id)
+            continue;
+        identities.set(JSON.stringify([
+            event.actor.kind,
+            event.actor.namespace,
+            event.actor.id,
+        ]), {
+            kind: event.actor.kind,
+            id: event.actor.id,
+            ...(event.actor.namespace
+                ? { namespace: event.actor.namespace }
+                : {}),
+        });
+    }
+    const queue = [...identities.entries()];
+    const labels = new Map();
+    let next = 0;
+    const deadline = Date.now() + ACTIVITY_LABEL_PAGE_BUDGET_MS;
+    const workers = Array.from({ length: Math.min(ACTIVITY_LABEL_CONCURRENCY, queue.length) }, async () => {
+        while (next < queue.length) {
+            const [key, identity] = queue[next++];
+            const sameKindProviders = auth
+                .map((provider, index) => ({ provider, index }))
+                .filter(({ provider }) => provider.kind === identity.kind);
+            const candidates = sameKindProviders.filter(({ provider }) => Boolean(provider.activityActorLabel));
+            const eligible = identity.namespace
+                ? candidates.filter(({ provider }) => activityActorNamespace(provider) === identity.namespace)
+                : (() => {
+                    const directoryKey = ({ provider, index, }) => {
+                        const namespace = activityActorNamespace(provider);
+                        return namespace === undefined
+                            ? `provider:${index}`
+                            : `namespace:${namespace}`;
+                    };
+                    // Every same-kind provider participates in the ambiguity check,
+                    // even if it cannot resolve labels. Otherwise a legacy ID owned
+                    // by a provider without a resolver could be disclosed to a
+                    // different provider that happens to have one.
+                    const directories = new Set(sameKindProviders.map(directoryKey));
+                    if (directories.size !== 1)
+                        return [];
+                    const [directory] = directories;
+                    return candidates.filter((candidate) => directoryKey(candidate) === directory);
+                })();
+            // One namespace is one directory. Use its first configured resolver so
+            // duplicate gate adapters over the same Clerk instance do not multiply
+            // the provider-level concurrency cap.
+            const provider = eligible[0]?.provider;
+            if (!provider)
+                continue;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return;
+            const label = await boundedActivityActorLabel(provider.activityActorLabel.bind(provider), identity.id, remaining);
+            if (label) {
+                labels.set(key, label);
+            }
+        }
+    });
+    await Promise.all(workers);
+    return {
+        ...page,
+        events: page.events.map((event) => {
+            const resolved = event.actor.id
+                ? labels.get(JSON.stringify([
+                    event.actor.kind,
+                    event.actor.namespace,
+                    event.actor.id,
+                ]))
+                : undefined;
+            // Never trust or echo a `label` supplied by storage. The persisted event
+            // schema has no label; only this authenticated read path may add one.
+            const actor = {
+                kind: event.actor.kind,
+                ...(event.actor.id ? { id: event.actor.id } : {}),
+                ...(event.actor.namespace
+                    ? { namespace: event.actor.namespace }
+                    : {}),
+            };
+            return {
+                ...event,
+                actor: resolved ? { ...actor, label: resolved } : actor,
+            };
+        }),
+    };
+}
 /**
  * Resolve `?toolkit=<name>` into the registry view this connection may see,
  * enforcing the caller's toolkit binding (docs/toolkits.md) on the way.
@@ -673,17 +974,16 @@ async function serveMcp(request, opts, baseUrl, actor, scope, runtimeContext) {
  * paths that would otherwise pay nothing.
  *
  * Identical bodies do not hide a connector id if the clock still sorts them.
- * `KvOAuthProvider.verifyState` reads `oauth:state` before it can fail, so a
- * configured id costs one storage round trip — on the Workers deployment shape
- * that is a real KV read, tens of milliseconds cold — while an id that names
- * nothing used to return having touched no I/O at all. That gap is an oracle:
- * sample the two and a wordlist recovers the connector list the flat 400 was
- * meant to withhold. So the zero-I/O refusals read the same key in the same
- * `conn:<id>:` namespace, which for an unconfigured id is simply a miss.
+ * `KvOAuthProvider.verifyState` reads `oauth:state` and its generation before
+ * it can reject a mismatched value, so a configured id costs two storage round
+ * trips on the ordinary path while an id naming nothing used to touch no I/O.
+ * That gap is an oracle: sample the two and a wordlist recovers the connector
+ * list the flat 400 was meant to withhold. So zero-I/O refusals read the same
+ * keys in the same `conn:<id>:` namespace, where an unconfigured id gets misses.
  *
  * This is deliberately *not* a constant-time claim, and docs/connectors.md says
  * so in prose: a hit and a miss are not identical in a KV store, and a connector
- * shipping its own `verifyState` may do more or less work than one read. What it
+ * shipping its own `verifyState` may do more or less work. What it
  * removes is the order-of-magnitude "no I/O versus a round trip" difference,
  * which is the only part of the signal that makes enumeration cheap.
  *
@@ -693,7 +993,8 @@ async function serveMcp(request, opts, baseUrl, actor, scope, runtimeContext) {
  */
 async function equalizeRefusalCost(context) {
     try {
-        await context.storage.get("oauth:state");
+        const generation = await context.storage.get("oauth:generation");
+        await context.storage.get(oauthValueStorageKey("oauth:state", generation));
     }
     catch {
         // Deliberately ignored — see above.
@@ -770,6 +1071,23 @@ async function handleOAuthCallback(url, registry, baseUrl, logger, branding) {
 /** Build the Web-standard fetch handler that serves connecta. */
 export function createFetchHandler(opts) {
     const { registry, auth, publicUrl, serverInfo } = opts;
+    let lastAdmissionWarningAt = 0;
+    let suppressedAdmissionWarnings = 0;
+    const warnAdmissionRejected = (error) => {
+        const now = Date.now();
+        if (now - lastAdmissionWarningAt < 1_000) {
+            suppressedAdmissionWarnings++;
+            return;
+        }
+        opts.logger.warn("[connecta] MCP request admission rejected", {
+            retryAfterMs: error.retryAfterMs,
+            active: opts.requestAdmission.activeCount,
+            queued: opts.requestAdmission.queuedCount,
+            suppressedSinceLastWarning: suppressedAdmissionWarnings,
+        });
+        lastAdmissionWarningAt = now;
+        suppressedAdmissionWarnings = 0;
+    };
     return async function fetch(request, runtimeContext) {
         const url = new URL(request.url);
         const baseUrl = publicUrl ?? url.origin;
@@ -843,6 +1161,13 @@ export function createFetchHandler(opts) {
                 }
                 return handleCredentialRequest(request, credentialMatch[1], credentialMatch[2], opts, baseUrl);
             }
+            const oauthManagementMatch = /^\/ui\/oauth\/([a-z0-9_-]+)$/.exec(path);
+            if (oauthManagementMatch) {
+                if (request.method === "OPTIONS") {
+                    return privateJson({ error: "method not allowed" }, { status: 405 });
+                }
+                return handleOAuthManagementRequest(request, oauthManagementMatch[1], opts, baseUrl, defer);
+            }
             if (request.method === "OPTIONS") {
                 for (const a of auth) {
                     if (a.handleMetadata) {
@@ -864,10 +1189,28 @@ export function createFetchHandler(opts) {
                 return new Response("Not Found", { status: 404 });
             }
             if (path === "/health") {
+                const codeAdmission = opts.executor && isAdmittingExecutor(opts.executor)
+                    ? opts.executor.admissionSnapshot?.()
+                    : undefined;
                 return Response.json({
                     status: "ok",
                     connectors: registry.listConnectors().length,
                     server: opts.serverInfo,
+                    admission: {
+                        policy: "global-fifo",
+                        requests: opts.requestAdmission.snapshot(),
+                        code: opts.executor
+                            ? (codeAdmission ?? { managedByExecutor: true })
+                            : null,
+                        reservedRoutes: [
+                            "/health",
+                            "/",
+                            "/credentials",
+                            "/activity",
+                            "/ui",
+                            "/ui/*",
+                        ],
+                    },
                     ...(opts.deploymentInfo ? { deployment: opts.deploymentInfo } : {}),
                 });
             }
@@ -951,7 +1294,7 @@ export function createFetchHandler(opts) {
                 const data = await buildUiData(registry, baseUrl, serverInfo, 
                 // The static headless bearer may read connector health, but only a
                 // Clerk-authenticated operator receives credential metadata.
-                eligibleClerkOperator ? opts.credentialVault : undefined, Boolean(opts.activity?.list), credentialManagement, opts.toolkits, defer);
+                eligibleClerkOperator ? opts.credentialVault : undefined, Boolean(opts.activity?.list), credentialManagement, opts.toolkits, defer, eligibleClerkOperator);
                 return privateJson(data);
             }
             if (path === "/ui/activity") {
@@ -980,7 +1323,8 @@ export function createFetchHandler(opts) {
                     ? Math.min(100, Math.max(1, Math.trunc(requestedLimit)))
                     : 50;
                 try {
-                    return privateJson(await opts.activity.list({ cursor, limit }));
+                    const page = await opts.activity.list({ cursor, limit });
+                    return privateJson(await enrichActivityActorLabels(page, auth));
                 }
                 catch (error) {
                     if (error instanceof InvalidActivityCursorError) {
@@ -991,21 +1335,55 @@ export function createFetchHandler(opts) {
                 }
             }
             if (path === "/mcp") {
-                // Authenticate BEFORE resolving ?toolkit=: an unauthenticated caller
-                // must not be able to probe which toolkit names exist.
-                const authz = await authorize(request, baseUrl, auth, opts.logger);
-                if (!authz.ok)
-                    return withMcpCors(authz.response);
-                const selected = resolveToolkitScope(url, registry, opts.toolkits, opts.logger, {
-                    actor: authz.actor,
-                    ...(authz.toolkitBinding
-                        ? { binding: authz.toolkitBinding }
-                        : {}),
-                });
-                if (!selected.ok)
-                    return withMcpCors(selected.response);
-                sweepCredentials();
-                return withMcpCors(await serveMcp(request, opts, baseUrl, authz.actor, selected.scope, runtimeContext));
+                let admission;
+                try {
+                    admission = await opts.requestAdmission.acquire({
+                        signal: request.signal,
+                    });
+                    if (admission.waitMs > 0) {
+                        opts.logger.debug("[connecta] MCP request admitted after queue wait", {
+                            waitMs: admission.waitMs,
+                            active: opts.requestAdmission.activeCount,
+                            queued: opts.requestAdmission.queuedCount,
+                        });
+                    }
+                }
+                catch (error) {
+                    if (error instanceof ExecutorAdmissionError &&
+                        error.code === "executor_cancelled") {
+                        throw request.signal.reason ?? error;
+                    }
+                    if (error instanceof ExecutorAdmissionError) {
+                        if (error.code === "executor_overloaded") {
+                            warnAdmissionRejected(error);
+                        }
+                        return withMcpCors(requestAdmissionFailure(error));
+                    }
+                    throw error;
+                }
+                try {
+                    // Authenticate BEFORE resolving ?toolkit=: an unauthenticated caller
+                    // must not be able to probe which toolkit names exist.
+                    const authz = await authorize(request, baseUrl, auth, opts.logger);
+                    if (!authz.ok) {
+                        return releaseAdmissionWithResponse(withMcpCors(authz.response), admission, request.signal);
+                    }
+                    const selected = resolveToolkitScope(url, registry, opts.toolkits, opts.logger, {
+                        actor: authz.actor,
+                        ...(authz.toolkitBinding
+                            ? { binding: authz.toolkitBinding }
+                            : {}),
+                    });
+                    if (!selected.ok) {
+                        return releaseAdmissionWithResponse(withMcpCors(selected.response), admission, request.signal);
+                    }
+                    sweepCredentials();
+                    return releaseAdmissionWithResponse(withMcpCors(await serveMcp(request, opts, baseUrl, authz.actor, selected.scope, runtimeContext)), admission, request.signal);
+                }
+                catch (error) {
+                    admission.release();
+                    throw error;
+                }
             }
             // Connector-owned public routes, dispatched last: a connector can add a
             // route but never shadow one of connecta's own. A throw here is the