@zackbart/connecta 0.23.0 → 0.24.0

package/dist/ui.js

@@ -1,64 +1,15 @@
-import { credentialTestRule, describeUndeclaredCredentialFields, storedCredentialShape, } from "./credentials.js";
+import { routeUi } from "./routes/ui.js";
+import { routeCredentials } from "./routes/credentials.js";
+import { routeOAuthManagement } from "./routes/oauth-management.js";
+import { withDeadline } from "./timeout.js";
+import { credentialTestRule, describeUndeclaredCredentialFields, storedCredentialShape, } from "./credential-rules.js";
 import { closeConnectorScope, } from "./connector-scope.js";
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
 import { OPERATOR_UI_CSS, OPERATOR_UI_SCRIPT, } from "./operator-ui/generated.js";
 import { CONNECTA_VERSION } from "./version.js";
 export { filterUiConnectors, } from "./operator-ui/model.js";
-/** Connecta's default monochrome "C" mark. */
-export const CONNECTA_FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
-  <style>
-    .fg { fill: #000 }
-    @media (prefers-color-scheme: dark) { .fg { fill: #fff } }
-  </style>
-  <path class="fg" d="M27 9.4A13 13 0 1 0 27 22.6l-4.4-2.5a8 8 0 1 1 0-8.2z"/>
-</svg>`;
-const DEFAULT_FAVICON_HREF = "/favicon.svg";
-/**
- * Branding arrives from operator config, which is untyped at a JS call site, so
- * every field is treated as `unknown`: a non-string is read as unset rather than
- * throwing on `.trim()`. Rendering must degrade to defaults for a malformed
- * value, never fail — `createConnecta` calls this during construction.
- */
-function trimmedString(value) {
-    return typeof value === "string" ? value.trim() || undefined : undefined;
-}
-export function resolveBranding(branding) {
-    const productName = trimmedString(branding?.productName) ?? "Connecta";
-    const ownerName = trimmedString(branding?.ownerName);
-    // Operator branding URLs become masthead/callback hrefs, so a non-http(s)
-    // scheme (javascript:, data:) is dropped the same as an unset URL — the
-    // callers already render a <span> instead of an <a> when it is absent.
-    const productUrl = trimmedString(branding?.productUrl);
-    const ownerUrl = trimmedString(branding?.ownerUrl);
-    const faviconHref = trimmedString(branding?.favicon?.href);
-    return {
-        productName,
-        ...(productUrl && isSafeHttpUrl(productUrl) ? { productUrl } : {}),
-        ...(ownerName ? { ownerName } : {}),
-        ...(ownerUrl && isSafeHttpUrl(ownerUrl) ? { ownerUrl } : {}),
-        description: trimmedString(branding?.description) ??
-            `Manage the services this ${productName} instance makes available to agents.`,
-        pageTitle: trimmedString(branding?.pageTitle) ??
-            (ownerName ? `${productName} — ${ownerName}` : productName),
-        faviconHref: faviconHref && isSafeIconHref(faviconHref)
-            ? faviconHref
-            : DEFAULT_FAVICON_HREF,
-        themeColor: trimmedString(branding?.themeColor) ?? "#ffffff",
-    };
-}
-/**
- * Whether the operator meant to supply a value here — the question every
- * dropped-URL warning asks before naming a field, and one definition so the
- * branding and `uiAuth` warnings cannot answer it differently. A non-string
- * counts as set: the intent was there and is exactly what the warning reports
- * on. A blank or whitespace-only string does not; that is indistinguishable
- * from leaving the field alone, and both take the default silently.
- */
-function isSetUrlValue(value) {
-    return typeof value === "string"
-        ? trimmedString(value) !== undefined
-        : value !== undefined && value !== null;
-}
+import { resolveBranding, isSafeHttpsUrl } from "./branding.js";
+export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
 /**
  * A JS string literal safe to inline in a script element. Escaping `/` keeps
  * an operator-supplied `</script>` from terminating the element early.
@@ -66,140 +17,13 @@ function isSetUrlValue(value) {
 function stringForInlineScript(value) {
     return JSON.stringify(value).replace(/\//g, "\\/");
 }
-/**
- * Names of the branding URLs the operator set that failed their gate and were
- * replaced by a default. Lives beside the gates so the startup warning cannot
- * drift from them, and takes `unknown` fields for the same reason
- * `resolveBranding` does — a warning helper must never throw.
- */
-export function droppedBrandingUrls(branding) {
-    if (!branding)
-        return [];
-    const resolved = resolveBranding(branding);
-    const faviconHref = branding.favicon?.href;
-    return [
-        ...(isSetUrlValue(branding.productUrl) && !resolved.productUrl
-            ? ["productUrl"]
-            : []),
-        ...(isSetUrlValue(branding.ownerUrl) && !resolved.ownerUrl
-            ? ["ownerUrl"]
-            : []),
-        ...(isSetUrlValue(faviconHref) &&
-            trimmedString(faviconHref) !== resolved.faviconHref
-            ? ["favicon.href"]
-            : []),
-    ];
-}
-/**
- * True only for absolute `http:`/`https:` URLs. Downstream connectors control
- * their `authorizationUrl`, so a hostile/misconfigured one could hand back a
- * `javascript:` (or other) scheme; gate it before it can become an href.
- */
-function safeUrl(url, schemes) {
-    if (typeof url !== "string")
-        return false;
-    try {
-        return schemes.includes(new URL(url).protocol);
-    }
-    catch {
-        return false;
-    }
-}
-export function isSafeHttpUrl(url) {
-    return safeUrl(url, ["http:", "https:"]);
-}
-/**
- * Only the second check's base; any origin works because the check is whether
- * the href stays on whatever origin it is resolved against. It is deliberately
- * never the sole gate: a value whose own authority equals this host (say
- * `//connecta.invalid/x`) would resolve to this exact origin and pass, so the
- * structural check below runs first and is what actually rejects `//host`.
- */
-const SAME_ORIGIN_PROBE = "https://connecta.invalid";
-/** Removed anywhere in a URL by the parser, so a gate must ignore them too. */
-const URL_STRIPPED_CHARS = /[\t\n\r]/g;
-/**
- * True for values allowed in the page's `<link rel="icon" href>`: an absolute
- * `http(s)` URL (an icon the operator hosts elsewhere) or a path rooted at this
- * origin. The relative carve-out is deliberate rather than accidental — the
- * default href is the relative `/favicon.svg`, which `isSafeHttpUrl` alone would
- * reject — and it is kept narrow on both ends.
- *
- * Root-relative only, because operator and OAuth callback pages sit at
- * different depths and a document-relative path would resolve differently.
- *
- * "Root-relative" is enforced structurally: exactly one leading `/` followed by
- * a character that is neither `/` nor `\`. Both of those would make the value an
- * authority (`//host`, and `/\host` because the URL parser folds `\` to `/` in
- * special schemes), pointing at an origin this server does not control. The test
- * runs on a copy with tab/newline/CR removed, since the parser strips those
- * anywhere and `/\t/host` would otherwise slip through as single-slash. The
- * origin comparison that follows is defense in depth, not the authority check —
- * on its own it would accept an authority that happened to equal the probe host.
- */
-export function isSafeIconHref(href) {
-    if (typeof href !== "string")
-        return false;
-    if (isSafeHttpUrl(href))
-        return true;
-    if (!/^\/(?![/\\])/.test(href.replace(URL_STRIPPED_CHARS, "")))
-        return false;
-    try {
-        return new URL(href, SAME_ORIGIN_PROBE).origin === SAME_ORIGIN_PROBE;
-    }
-    catch {
-        return false;
-    }
-}
-/** Absolute HTTPS gate for the `UiAuthConfig` URL fields documented in types.ts. */
-export function isSafeHttpsUrl(url) {
-    return safeUrl(url, ["https:"]);
-}
-/**
- * Names of the `uiAuth` URLs an inbound-auth provider supplied that failed their
- * gate. Lives beside the gate for the same reason `droppedBrandingUrls` does: the
- * startup warning cannot then drift from what rendering actually drops. Every
- * field is read defensively rather than trusted, because a custom `InboundAuth`
- * is untyped at a JS call site — `isSafeHttpsUrl` takes `unknown`, and a
- * `uiAuth` that is not the clerk shape is reported as nothing to warn about.
- *
- * `frontendApiUrl` is required, so anything that fails its gate is a drop.
- * `signInUrl` and `signUpUrl` are optional, so only a value the operator
- * *supplied* and the gate then rejected is worth a warning — an unset field
- * took no default away from anyone. `isSetUrlValue` decides that, the same way
- * and for the same reasons it decides it for the branding URLs: a warning that
- * fires for one and not the other would be reporting on the field rather than
- * on the operator's intent. Rendering is not consulted for this: it drops on
- * the gate alone, and a blank string fails that gate too — it is simply not
- * *reported*, because a blank is indistinguishable from leaving the field
- * alone.
- */
-export function droppedUiAuthUrls(uiAuth) {
-    if (!uiAuth || uiAuth.kind !== "clerk")
-        return [];
-    return [
-        ...(isSafeHttpsUrl(uiAuth.frontendApiUrl) ? [] : ["uiAuth.frontendApiUrl"]),
-        ...(isSetUrlValue(uiAuth.signInUrl) && !isSafeHttpsUrl(uiAuth.signInUrl)
-            ? ["uiAuth.signInUrl"]
-            : []),
-        ...(isSetUrlValue(uiAuth.signUpUrl) && !isSafeHttpsUrl(uiAuth.signUpUrl)
-            ? ["uiAuth.signUpUrl"]
-            : []),
-    ];
-}
 const OPERATOR_PAGE_LABELS = {
     connections: "Connections",
-    credentials: "Credentials",
-    tokens: "Access tokens",
     activity: "Activity",
 };
 export function operatorPageForPath(path) {
     if (path === "/")
         return "connections";
-    if (path === "/credentials")
-        return "credentials";
-    if (path === "/tokens")
-        return "tokens";
     if (path === "/activity")
         return "activity";
     return undefined;
@@ -223,151 +47,157 @@ export function credentialManagementCapability(input) {
  */
 export async function buildUiData(registry, baseUrl, serverInfo, credentialVault, activityEnabled = false, credentialManagement = credentialVault
     ? "available"
-    : "requires_operator", defer, oauthManagement = false, discoveryConcurrency, accessTokenManagement = "not_configured", personalCredentialOwner) {
+    : "requires_operator", defer, oauthManagement = false, discoveryConcurrency, personalCredentialOwner, detailOptions = {}) {
     const requestScope = {};
     const connectorSet = registry.listConnectors();
     const concurrency = resolveDiscoveryConcurrency(discoveryConcurrency);
     const settled = await mapSettledWithConcurrency(connectorSet, concurrency, async (c) => {
-        const drift = await registry.credentialDriftFor(c.id);
-        const status = drift
-            ? { state: "auth_required", message: drift }
-            : await registry.statusFor(c.id, baseUrl, requestScope);
-        if (status.authorizationUrl) {
-            await registry.bindOAuthHandoff(c.id, status.authorizationUrl);
-        }
-        let tools = [];
-        // `status()` on an unauthenticated remote connector starts OAuth and
-        // stores its state + PKCE verifier. Probing listTools immediately
-        // afterward would start a second flow, overwrite that state, and return
-        // the now-stale first URL to the operator. Only inspect tools after
-        // status proves the connector is healthy.
-        if (status.state === "ok") {
-            try {
-                tools = (await registry.getTools(c.id, baseUrl, requestScope)).map((t) => ({
-                    name: t.name,
-                    address: `${c.id}.${t.name}`,
-                    ...(t.description !== undefined
-                        ? { description: t.description }
-                        : {}),
-                }));
-            }
-            catch {
-                // broken connector: reported via status "error", tools stay empty
-            }
-        }
-        let credential;
-        const mayManageAuth = c.authScope === "personal"
-            ? Boolean(personalCredentialOwner)
-            : oauthManagement;
-        if (c.credential && credentialVault && mayManageAuth) {
-            // One rule, shared with the test route: only the hook matching the
-            // declared credential shape can run, so the button is offered only
-            // where a click can succeed (src/credentials.ts).
-            const testRule = credentialTestRule(c);
-            const credentialFields = (metadata) => c.credential?.fields?.map((field) => {
-                const fieldMetadata = metadata?.fields?.[field.name];
+        try {
+            return await withDeadline(async (outerSignal) => {
+                const drift = await registry.credentialDriftFor(c.id);
+                outerSignal.throwIfAborted();
+                let tools = [];
+                let status;
+                try {
+                    status = await withDeadline(async (signal) => {
+                        if (drift)
+                            return { state: "auth_required", message: drift };
+                        const current = await registry.statusFor(c.id, baseUrl, requestScope, { signal });
+                        if (current.state === "ok" && !signal.aborted) {
+                            try {
+                                tools = (await registry.getTools(c.id, baseUrl, requestScope, { signal })).map(t => ({ name: t.name, address: `${c.id}.${t.name}`, ...(t.description ? { description: t.description } : {}) }));
+                            }
+                            catch { /* The registry owns the failed catalog observation. */ }
+                        }
+                        return current;
+                    }, { timeoutMs: detailOptions.timeoutMs ?? 30_000, signal: outerSignal, timeoutError: new Error("Connection details timed out. Retry this connection.") });
+                }
+                catch (error) {
+                    status = { state: "error", message: error instanceof Error ? error.message : "Connection details unavailable" };
+                }
+                let credential;
+                const mayManageAuth = detailOptions.mayManage?.(c.id) ?? (c.authScope === "personal" ? Boolean(personalCredentialOwner) : oauthManagement);
+                if (c.credential && credentialVault && mayManageAuth) {
+                    // One rule, shared with the test route: only the hook matching the
+                    // declared credential shape can run, so the button is offered only
+                    // where a click can succeed (src/credentials.ts).
+                    const testRule = credentialTestRule(c);
+                    const credentialFields = (metadata) => c.credential?.fields?.map((field) => {
+                        const fieldMetadata = metadata?.fields?.[field.name];
+                        return {
+                            name: field.name,
+                            label: field.label,
+                            ...(field.description
+                                ? { description: field.description }
+                                : {}),
+                            ...(field.placeholder
+                                ? { placeholder: field.placeholder }
+                                : {}),
+                            inputType: field.inputType ?? "password",
+                            configured: Boolean(fieldMetadata),
+                            ...(fieldMetadata
+                                ? {
+                                    lastFour: fieldMetadata.lastFour,
+                                    updatedAt: fieldMetadata.updatedAt,
+                                }
+                                : {}),
+                        };
+                    });
+                    const credentialCard = {
+                        label: c.credential.label,
+                        ...(c.credential.description
+                            ? { description: c.credential.description }
+                            : {}),
+                        ...(c.credential.placeholder
+                            ? { placeholder: c.credential.placeholder }
+                            : {}),
+                    };
+                    try {
+                        const metadata = await credentialVault.metadata(c.id, c.authScope === "personal" ? personalCredentialOwner : undefined);
+                        const fields = credentialFields(metadata);
+                        const shape = storedCredentialShape(c.credential, metadata?.fields ?? null);
+                        credential = {
+                            ...credentialCard,
+                            ...(fields?.length ? { fields } : {}),
+                            configured: shape.state === "valid",
+                            removable: Boolean(metadata),
+                            ...(metadata
+                                ? {
+                                    lastFour: metadata.lastFour,
+                                    updatedAt: metadata.updatedAt,
+                                }
+                                : {}),
+                            testable: testRule.mode !== null && shape.state !== "mismatch",
+                            ...(shape.state === "mismatch"
+                                ? { error: shape.message }
+                                : {}),
+                            // A dropped field leaves its secret in the vault, and the field
+                            // list below only renders fields the connector still declares —
+                            // so without this line there is nowhere an operator could see it.
+                            ...(shape.state === "valid" && shape.undeclared.length
+                                ? {
+                                    notice: describeUndeclaredCredentialFields(shape.undeclared),
+                                }
+                                : {}),
+                        };
+                    }
+                    catch {
+                        const fields = credentialFields();
+                        credential = {
+                            ...credentialCard,
+                            ...(fields?.length ? { fields } : {}),
+                            configured: false,
+                            removable: true,
+                            testable: testRule.mode !== null,
+                            error: "Stored credential could not be read.",
+                        };
+                    }
+                }
+                outerSignal.throwIfAborted();
                 return {
-                    name: field.name,
-                    label: field.label,
-                    ...(field.description
-                        ? { description: field.description }
+                    id: c.id,
+                    authScope: c.authScope ?? "shared",
+                    ...(c.title ? { title: c.title } : {}),
+                    ...(c.description !== undefined
+                        ? { description: c.description }
                         : {}),
-                    ...(field.placeholder
-                        ? { placeholder: field.placeholder }
-                        : {}),
-                    inputType: field.inputType ?? "password",
-                    configured: Boolean(fieldMetadata),
-                    ...(fieldMetadata
-                        ? {
-                            lastFour: fieldMetadata.lastFour,
-                            updatedAt: fieldMetadata.updatedAt,
-                        }
+                    status: status.state,
+                    ...(status.message ? { message: status.message } : {}),
+                    toolCount: tools.length,
+                    tools,
+                    // Counts only, and only when a refresh in this runtime produced them.
+                    // `Registry.statusFor` already rebuilt the report through
+                    // `boundedCatalogDrift`, so what lands here cannot carry a name or a
+                    // schema even if the plugin seam returned one.
+                    ...(status.catalogDrift ? { catalogDrift: status.catalogDrift } : {}),
+                    ...(status.catalogAccess
+                        ? { catalogAccess: status.catalogAccess }
                         : {}),
+                    oauth: Boolean(c.startAuth && c.disconnectAuth),
+                    ...(credential ? { credential } : {}),
                 };
+            }, {
+                timeoutMs: detailOptions.timeoutMs ?? 30_000,
+                ...(detailOptions.signal ? { signal: detailOptions.signal } : {}),
+                timeoutError: new Error("Connection details timed out. Retry this connection."),
             });
-            const credentialCard = {
-                label: c.credential.label,
-                ...(c.credential.description
-                    ? { description: c.credential.description }
-                    : {}),
-                ...(c.credential.placeholder
-                    ? { placeholder: c.credential.placeholder }
-                    : {}),
+        }
+        catch (error) {
+            return {
+                id: c.id,
+                ...(c.title ? { title: c.title } : {}),
+                authScope: c.authScope ?? "shared",
+                status: "error",
+                oauth: Boolean(c.startAuth && c.disconnectAuth),
+                message: error instanceof Error ? error.message : "Connection details unavailable",
+                toolCount: 0,
+                tools: [],
             };
-            try {
-                const metadata = await credentialVault.metadata(c.id, c.authScope === "personal" ? personalCredentialOwner : undefined);
-                const fields = credentialFields(metadata);
-                const shape = storedCredentialShape(c.credential, metadata?.fields ?? null);
-                credential = {
-                    ...credentialCard,
-                    ...(fields?.length ? { fields } : {}),
-                    configured: shape.state === "valid",
-                    removable: Boolean(metadata),
-                    ...(metadata
-                        ? {
-                            lastFour: metadata.lastFour,
-                            updatedAt: metadata.updatedAt,
-                        }
-                        : {}),
-                    testable: testRule.mode !== null && shape.state !== "mismatch",
-                    ...(shape.state === "mismatch"
-                        ? { error: shape.message }
-                        : {}),
-                    // A dropped field leaves its secret in the vault, and the field
-                    // list below only renders fields the connector still declares —
-                    // so without this line there is nowhere an operator could see it.
-                    ...(shape.state === "valid" && shape.undeclared.length
-                        ? {
-                            notice: describeUndeclaredCredentialFields(shape.undeclared),
-                        }
-                        : {}),
-                };
-            }
-            catch {
-                const fields = credentialFields();
-                credential = {
-                    ...credentialCard,
-                    ...(fields?.length ? { fields } : {}),
-                    configured: false,
-                    removable: true,
-                    testable: testRule.mode !== null,
-                    error: "Stored credential could not be read.",
-                };
-            }
         }
-        return {
-            id: c.id,
-            authScope: c.authScope ?? "shared",
-            ...(c.title ? { title: c.title } : {}),
-            ...(c.description !== undefined
-                ? { description: c.description }
-                : {}),
-            status: status.state,
-            ...(status.message ? { message: status.message } : {}),
-            ...(isSafeHttpUrl(status.authorizationUrl)
-                ? { authorizationUrl: status.authorizationUrl }
-                : {}),
-            toolCount: tools.length,
-            tools,
-            // Counts only, and only when a refresh in this runtime produced them.
-            // `Registry.statusFor` already rebuilt the report through
-            // `boundedCatalogDrift`, so what lands here cannot carry a name or a
-            // schema even if the plugin seam returned one.
-            ...(status.catalogDrift ? { catalogDrift: status.catalogDrift } : {}),
-            ...(status.catalogAccess
-                ? { catalogAccess: status.catalogAccess }
-                : {}),
-            ...(c.disconnectAuth &&
-                c.startAuth &&
-                (oauthManagement ||
-                    c.authScope === "personal" ||
-                    !personalCredentialOwner)
-                ? { oauth: true }
-                : {}),
-            ...(credential ? { credential } : {}),
-        };
+        finally {
+            await closeConnectorScope(c, registry.contextFor(c.id, baseUrl, requestScope), defer);
+        }
     });
-    await mapSettledWithConcurrency(connectorSet, concurrency, (connector) => closeConnectorScope(connector, registry.contextFor(connector.id, baseUrl, requestScope), defer));
     const connectors = settled.map((result) => {
         if (result.status === "rejected")
             throw result.reason;
@@ -379,7 +209,6 @@ export async function buildUiData(registry, baseUrl, serverInfo, credentialVault
         connectors,
         activityEnabled,
         credentialManagement,
-        accessTokenManagement,
         oauthManagement: oauthManagement || Boolean(personalCredentialOwner),
     };
 }
@@ -498,3 +327,33 @@ ${OPERATOR_UI_SCRIPT}</script>
 </body>
 </html>`;
 }
+/** Mount the connection UI without enabling any storage or activity module. */
+export function operatorUi(options = {}) {
+    return {
+        ...options,
+        reservedPaths: ["/", "/ui", "/ui/*", "/favicon.svg", "/favicon.ico"],
+        credentialHandoffUrl(baseUrl) {
+            return new URL("/", baseUrl).toString();
+        },
+        async handle(context) {
+            const routes = [
+                ...(context.opts.credentialVault ? [routeCredentials] : []),
+                routeOAuthManagement,
+                routeUi,
+            ];
+            for (const route of routes) {
+                const response = await route(context);
+                if (response) {
+                    if (operatorPageForPath(context.path) || context.path === "/ui") {
+                        response.headers.set("X-Frame-Options", "DENY");
+                        if (!response.headers.has("Content-Security-Policy")) {
+                            response.headers.set("Content-Security-Policy", "frame-ancestors 'none'");
+                        }
+                    }
+                    return response;
+                }
+            }
+            return context.opts.activityModule?.handle(context) ?? null;
+        },
+    };
+}

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.23.0";
+export declare const CONNECTA_VERSION = "0.24.0";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.23.0";
+export const CONNECTA_VERSION = "0.24.0";

package/documentation/architecture.md

@@ -66,19 +66,17 @@ read top to bottom.
 | --- | --- | --- |
 | 0 | HTTPS upgrade | 308 to `publicUrl` when it is HTTPS and the request arrived over HTTP. Path and query are *assigned* onto the configured URL, never resolved against it, so a `//host` pathname cannot replace the deployment origin. `/health` is exempt: a loopback container probe must not depend on public DNS and TLS. `/ui` is canonicalized to `/` while upgrading. |
 | 0 | Cloudflare Access (Worker deployment, when enabled) | Edge admission before this route table. Managed OAuth owns its challenge and discovery metadata; an admitted direct invocation carries trusted identity in `ctx.access`. |
-| 1 | `/ui/access-tokens[/<id>]`, `/ui/credentials/<id>[/<action>]`, `/ui/oauth/<id>` | Private mutation routes, matched **first** so nothing can shadow them and so they own their own `OPTIONS` — they answer it with a refusal rather than inheriting the wildcard CORS preflight. |
-| 2 | `OPTIONS` | Each auth provider's `handleMetadata` gets a chance (CORS preflight for browser MCP clients); otherwise 204 with MCP CORS. |
-| 3 | `/.well-known/*` | Auth providers' `handleMetadata`, open. 404 when none handles it. |
-| 4 | `/health` | Open JSON: status, connector count, `serverInfo`, the configured executor's sanitized name when it has one, catalog-drift counts, admission snapshots, reserved route names, and `deployment` when `deploymentInfo` is set. Payload-free by construction, and it never joins the MCP queue. |
-| 5 | `/oauth/callback/<connectorId>` | Downstream-OAuth completion, open, `verifyState` before `finishAuth`. Personal flows first resolve the short-lived state hash to the principal partition. |
-| 6 | `/favicon.*`, `/ui` → `/`, the operator shells, `/ui/data` | The operator surface ([operator UI](./operator-ui.md)). The shells are open and data-free; `/ui/data` behind them is gated. |
-| 7 | `/ui/activity` | Gated, plus the optional `activity.readGate`. `GET` only; 404 with no `activity.store.list`. |
-| 8 | `/mcp` | **Admission before auth**, then the auth gate, then a fresh MCP server. |
-| 9 | — | 404. Custom HTTP routes belong to the deployment. |
+| 1 | Mounted UI routes | The optional UI handles its shells, assets, data, details, and auth mutations before wildcard OPTIONS. Mutation routes refuse preflight rather than inheriting MCP CORS. No UI module means none of these routes. |
+| 2 | `OPTIONS` | Auth metadata gets a chance, otherwise MCP CORS preflight. |
+| 3 | `/.well-known/*` | Auth metadata, or 404. |
+| 4 | `/health` | Open payload-free health, executor, admission, and deployment metadata; reserved routes reflect installed modules. |
+| 5 | `/oauth/callback/<connectorId>` | Core downstream OAuth completion, state verification and personal ownership checks; independent of UI. |
+| 6 | `/mcp` | Admission before auth, then a request-local MCP server. |
+| 7 | Other paths | 404. Custom HTTP routes belong to the deployment. |
+
 
 Every response leaves through `withSecurityHeaders`: `nosniff`, a no-referrer
-policy, HSTS on HTTPS, and — on the operator shells — a nonce-based script CSP
-and framing denial. `test/server-route-contracts.test.ts` pins this ordering
+policy, HSTS on HTTPS, while the UI module adds a nonce-based script CSP and framing denial to its shells. `test/server-route-contracts.test.ts` pins this ordering
 and the exact refusal bodies; it exists because the ordering is invisible in
 any one file and a reordering reads like a harmless refactor.
 
@@ -125,6 +123,19 @@ read-only check. `test/execute.test.ts` asserts that parity directly, because
 the alternative — a sandbox path that quietly diverges — is how generated code
 would mint a capability.
 
+## Optional deployment modules
+
+`createConnecta` takes closed typed `ui`, `vault`, and `activity` slots. Factories
+live at `/ui`, `/credentials`, and `/activity`; bearer auth lives at
+`/auth/bearer`. Root exports the contracts, never these implementations. There
+is no module array, runtime registration, or plugin lifecycle.
+
+Core keeps connector discovery, the executor contract, invocation, permissions,
+and OAuth callback verification together. Optional modules contribute no
+runtime work when omitted. The UI supplies credential handoff URLs only while
+mounted. Status reads never initiate OAuth, and each lazy details request owns
+its downstream scope. See [operator UI](./operator-ui.md).
+
 ## Import-graph purity
 
 Nothing reachable from `src/index.ts` may import a `node:` builtin. The core is
@@ -142,8 +153,8 @@ specific to a direct Worker invocation carrying `ctx.access`.
 
 `test/purity.test.ts` walks the relative-import graph from `src/index.ts` and
 fails on (a) any `node:` specifier in a reachable file and (b) the Node
-adapter, file storage, QuickJS parent or child, or the Clerk adapter being
-reachable at all. `test/package-surface.test.ts` and
+adapter, file storage, QuickJS parent or child, auth adapters, UI bundle,
+encrypted vault implementation, or activity implementation being reachable at all. `test/package-surface.test.ts` and
 `scripts/check-package.mjs` guard the other half — that the published tarball
 matches the same boundary.
 
@@ -169,8 +180,7 @@ src/
   invocation.ts       one tool call, end to end
   catalog-drift.ts    vetted manifests and the counts a refresh produces
   credentials.ts      the AES-GCM connector vault over KVStorage
-  access-tokens.ts    operator-issued MCP bearer tokens
-  activity.ts         payload-free event contracts + best-effort recorder
+  activity.ts         optional history factory and best-effort recorder
   call-admission.ts   connector-partitioned downstream permits and budgets
   executor-admission.ts  the portable bounded queue both pools use
   ui.ts               the served operator shell and /ui/data payload
@@ -199,8 +209,7 @@ src/
   the connector limiters, then the executor. Node's `listen()` calls it on
   SIGTERM/SIGINT.
 - **Structural mistakes throw at construction.** A duplicate connector id, an
-  invalid admission rule, `accessTokens` without an interactive operator provider, a missing
-  executor: all refuse to boot. A deployment that starts in the wrong shape is
+  invalid admission rule, removed `accessTokens` option, or missing executor: all refuse to boot. A deployment that starts in the wrong shape is
   worse than one that does not start.
 
 ## Tests that enforce this