@zackbart/connecta 0.23.0 → 0.24.0

package/dist/routes/shared.js

@@ -1,5 +1,4 @@
 import { identityStorageKey, validIdentityReference } from "../identity.js";
-import { operatorPageForPath } from "../ui.js";
 export { msg } from "../errors.js";
 export function privateJson(body, init = {}) {
     const headers = new Headers(init.headers);
@@ -36,7 +35,9 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
         const identity = { actor, interactive: false };
         let connectorIds = "all";
         try {
-            connectorIds = await identityConfig?.connectorAccess?.(identity) ?? "all";
+            connectorIds = identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all";
+            if (connectorIds !== "all" && (!Array.isArray(connectorIds) || !connectorIds.every(id => typeof id === "string" && /^[a-z0-9_-]+$/.test(id))))
+                throw new Error("invalid connector permission");
         }
         catch {
             return {
@@ -44,7 +45,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 response: privateJson({ error: "identity access resolution failed" }, { status: 403 }),
             };
         }
-        return { ok: true, actor, identity, connectorIds, operator: false };
+        return { ok: true, actor, identity, connectorIds, operator: false, credentialAdministration: "none", personalConnection: "none" };
     }
     let lastResponse = null;
     for (const provider of auth) {
@@ -74,14 +75,26 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 interactive,
             };
             let operator = interactive;
+            let credentialAdministration = "none";
+            let personalConnection = "none";
             let connectorIds = "all";
             try {
-                if (identityConfig?.operatorAccess) {
+                if (identityConfig?.activityAccess) {
                     operator = interactive && principal
-                        ? await identityConfig.operatorAccess(principal)
+                        ? await identityConfig.activityAccess(principal)
                         : false;
                 }
-                connectorIds = await identityConfig?.connectorAccess?.(identity) ?? "all";
+                connectorIds = identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all";
+                if (interactive) {
+                    credentialAdministration = identityConfig?.credentialAdministration ? await identityConfig.credentialAdministration(identity) : "none";
+                    personalConnection = principal && identityConfig?.personalConnection ? await identityConfig.personalConnection(identity) : "none";
+                }
+                if (typeof operator !== "boolean")
+                    throw new Error("invalid activity permission");
+                for (const permission of [connectorIds, credentialAdministration, personalConnection]) {
+                    if (permission !== "all" && permission !== "none" && (!Array.isArray(permission) || !permission.every(id => typeof id === "string" && /^[a-z0-9_-]+$/.test(id))))
+                        throw new Error("invalid identity permission");
+                }
             }
             catch {
                 return {
@@ -100,6 +113,8 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                     ? { principalKey: await identityStorageKey(principal) }
                     : {}),
                 connectorIds,
+                credentialAdministration,
+                personalConnection,
                 operator,
                 ...(operator ? { uiAdminEligible: true } : {}),
             };
@@ -118,34 +133,6 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
             }),
     };
 }
-export async function authorizeUiAdmin(request, baseUrl, auth, purpose = "credential management", runtimeContext, identityConfig) {
-    // Operator mutation is intentionally narrower than /mcp and /ui/data: only
-    // an interactive provider may admit it. A static bearer token is useful
-    // for headless tool calls but must not become a deployment-admin key.
-    //
-    // Every interactive provider gets a turn, the way the /mcp gate does.
-    // Stopping at the first would make admission depend on config order: a failed gate or
-    // missing user may simply mean a later provider is the one meant to admit.
-    // The last refusal is returned if none do.
-    const authz = await authorizeUiIdentity(request, baseUrl, auth, purpose, runtimeContext, identityConfig);
-    if (!authz.ok)
-        return authz;
-    if (!authz.operator || !authz.actor.id) {
-        return {
-            ok: false,
-            response: privateJson({ error: `${purpose} requires operator access` }, { status: 403 }),
-        };
-    }
-    return {
-        ok: true,
-        userId: authz.identity.principal?.id ?? authz.actor.id,
-        ...(authz.identity.principal
-            ? { principal: authz.identity.principal }
-            : {}),
-        ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
-        connectorIds: authz.connectorIds,
-    };
-}
 export async function authorizeUiIdentity(request, baseUrl, auth, purpose, runtimeContext, identityConfig) {
     const providers = auth.filter((candidate) => candidate.interactiveOperator);
     if (providers.length === 0) {
@@ -181,25 +168,42 @@ export function isSameOrigin(request, baseUrl) {
         return false;
     }
 }
-export function withSecurityHeaders(response, requestUrl, path) {
+export function withSecurityHeaders(response, requestUrl, _path) {
     const headers = new Headers(response.headers);
     headers.set("X-Content-Type-Options", "nosniff");
     headers.set("Referrer-Policy", "no-referrer");
     if (requestUrl.protocol === "https:") {
         headers.set("Strict-Transport-Security", "max-age=31536000");
     }
-    if (operatorPageForPath(path) || path === "/ui") {
-        // Operator HTML responses ship their own nonce-based script CSP (which
-        // already includes frame-ancestors 'none'); only fall back to the
-        // framing-only directive when no CSP is present (for example redirects).
-        if (!headers.has("Content-Security-Policy")) {
-            headers.set("Content-Security-Policy", "frame-ancestors 'none'");
-        }
-        headers.set("X-Frame-Options", "DENY");
-    }
     return new Response(response.body, {
         status: response.status,
         statusText: response.statusText,
         headers,
     });
 }
+/** Unknown configured ids refuse the complete view, including management rights. */
+export function validateAuthPermissions(authz, registry) {
+    for (const value of [
+        authz.connectorIds,
+        authz.credentialAdministration,
+        authz.personalConnection,
+    ]) {
+        if (value === "all" || value === "none")
+            continue;
+        if (!Array.isArray(value) || value.some(id => !registry.getConnector(id))) {
+            throw new Error("invalid identity permission connector ids");
+        }
+    }
+}
+export function mayManageConnector(authz, connector) {
+    if (!authz.identity.interactive)
+        return false;
+    if (authz.connectorIds !== "all" && !authz.connectorIds.includes(connector.id)) {
+        return false;
+    }
+    const permission = connector.authScope === "personal"
+        ? authz.personalConnection
+        : authz.credentialAdministration;
+    return permission === "all" ||
+        (permission !== "none" && permission.includes(connector.id));
+}

package/dist/routes/ui.js

@@ -1,6 +1,7 @@
+import { CONNECTA_VERSION } from "../version.js";
 import { CONNECTA_FAVICON_ICO } from "../favicon.js";
-import { buildUiData, CONNECTA_FAVICON_SVG, credentialManagementCapability, operatorPageForPath, renderUiHtml, } from "../ui.js";
-import { authorize, msg, privateJson, } from "./shared.js";
+import { buildUiData, CONNECTA_FAVICON_SVG, operatorPageForPath, renderUiHtml, } from "../ui.js";
+import { authorize, mayManageConnector, validateAuthPermissions, msg, privateJson, } from "./shared.js";
 /**
  * Headers that make an operator-supplied favicon body inert on this origin.
  * The SVG route is the sharp one: `image/svg+xml` is an *active* content type,
@@ -67,7 +68,7 @@ export async function routeUi(context) {
         });
     }
     const operatorPage = operatorPageForPath(path);
-    if (operatorPage) {
+    if (operatorPage && (operatorPage !== "activity" || opts.activity?.list)) {
         if (request.method !== "GET" && request.method !== "HEAD") {
             return privateJson({ error: "method not allowed" }, { status: 405 });
         }
@@ -97,13 +98,17 @@ export async function routeUi(context) {
             },
         });
     }
-    if (path !== "/ui/data")
+    const detail = /^\/ui\/connectors\/([a-z0-9_-]+)$/.exec(path);
+    if (path !== "/ui/data" && !detail)
         return null;
+    if (request.method !== "GET")
+        return privateJson({ error: "method not allowed" }, { status: 405 });
     const authz = await authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity);
     if (!authz.ok)
         return authz.response;
     let registry;
     try {
+        validateAuthPermissions(authz, opts.registry);
         registry = opts.registry.scoped({
             connectorIds: authz.connectorIds,
             ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
@@ -113,33 +118,31 @@ export async function routeUi(context) {
     catch (error) {
         return privateJson({ error: msg(error) }, { status: 403 });
     }
-    const eligibleOperator = authz.uiAdminEligible === true;
-    const interactiveManager = authz.identity.interactive;
-    const personalManager = Boolean(interactiveManager && authz.principalKey);
-    const visibleConnectors = registry.listConnectors();
-    const hasManageableCredentialSlot = visibleConnectors.some((connector) => Boolean(connector.credential) &&
-        (connector.authScope !== "personal" || personalManager));
-    const credentialManagement = interactiveManager && hasManageableCredentialSlot
-        ? opts.credentialVault
-            ? "available"
-            : "vault_not_configured"
-        : credentialManagementCapability({
-            eligibleOperator: interactiveManager,
-            hasCredentialSlots: visibleConnectors.some((connector) => Boolean(connector.credential)),
-            hasCredentialVault: Boolean(opts.credentialVault),
-        });
-    // As with connector credentials, a Bearer-authenticated observer learns
-    // only that an interactive operator is required, not whether this deployment has opted into
-    // token issuance. Configuration topology is operator data.
-    const accessTokenManagement = !eligibleOperator
-        ? "requires_operator"
-        : opts.accessTokens
-            ? "available"
-            : "not_configured";
-    const data = await buildUiData(registry, baseUrl, opts.serverInfo, 
-    // A static headless bearer may read connector health, but only an
-    // interactive human receives credential metadata for visible connectors.
-    interactiveManager ? opts.credentialVault : undefined, Boolean(opts.activity?.list) &&
-        (!opts.identity?.operatorAccess || eligibleOperator), credentialManagement, defer, interactiveManager, opts.discoveryConcurrency, accessTokenManagement, personalManager ? authz.principalKey : undefined);
-    return privateJson(data);
+    const visible = registry.listConnectors();
+    const mayManage = (id) => { const connector = registry.getConnector(id); return Boolean(connector && mayManageConnector(authz, connector)); };
+    const permissions = (connector) => ({
+        use: true,
+        manageSharedAuth: connector.authScope !== "personal" && mayManage(connector.id),
+        connectPersonal: connector.authScope === "personal" && mayManage(connector.id),
+    });
+    const activityEnabled = Boolean(opts.activity?.list) && authz.operator;
+    const credentialManagement = visible.some(c => c.credential && mayManage(c.id))
+        ? opts.credentialVault ? "available" : "vault_not_configured"
+        : authz.identity.interactive && !visible.some(c => c.credential) ? "no_slots" : "requires_operator";
+    if (detail) {
+        const connector = registry.getConnector(detail[1]);
+        if (!connector)
+            return privateJson({ error: "unknown connector" }, { status: 404 });
+        const one = opts.registry.scoped({ connectorIds: [connector.id], ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}), ...(authz.principalKey ? { principalKey: authz.principalKey } : {}) });
+        const data = await buildUiData(one, baseUrl, opts.serverInfo, opts.credentialVault, activityEnabled, credentialManagement, defer, false, 1, authz.principalKey, { mayManage, timeoutMs: opts.probeTimeoutMs ?? 30_000, signal: request.signal });
+        return privateJson({ ...data.connectors[0], permissions: permissions(connector) });
+    }
+    return privateJson({
+        serverInfo: opts.serverInfo,
+        connectaVersion: CONNECTA_VERSION,
+        activityEnabled,
+        credentialManagement,
+        oauthManagement: visible.some(c => mayManage(c.id)),
+        connectors: visible.map(c => ({ id: c.id, ...(c.title ? { title: c.title } : {}), ...(c.description ? { description: c.description } : {}), authScope: c.authScope ?? "shared", status: "loading", toolCount: 0, tools: [], oauth: Boolean(c.startAuth && c.disconnectAuth), permissions: permissions(c) })),
+    });
 }

package/dist/server.js

@@ -1,11 +1,7 @@
 import { isAdmittingExecutor } from "./executor-admission.js";
-import { routeAccessTokens } from "./routes/access-tokens.js";
-import { routeActivity } from "./routes/activity.js";
-import { routeCredentials } from "./routes/credentials.js";
 import { createMcpRoute, MCP_CORS_HEADERS } from "./routes/mcp.js";
-import { routeOAuthCallback, routeOAuthManagement, } from "./routes/oauth.js";
+import { routeOAuthCallback, } from "./routes/oauth.js";
 import { withSecurityHeaders, } from "./routes/shared.js";
-import { routeUi } from "./routes/ui.js";
 /**
  * Build the Web-standard fetch handler.
  *
@@ -59,15 +55,9 @@ export function createFetchHandler(opts) {
         };
         const route = async () => {
             // Private mutations own OPTIONS so they never inherit wildcard CORS.
-            const accessTokens = await routeAccessTokens(context);
-            if (accessTokens)
-                return accessTokens;
-            const credentials = await routeCredentials(context);
-            if (credentials)
-                return credentials;
-            const oauthManagement = await routeOAuthManagement(context);
-            if (oauthManagement)
-                return oauthManagement;
+            const uiResponse = await opts.ui?.handle(context);
+            if (uiResponse)
+                return uiResponse;
             if (request.method === "OPTIONS") {
                 for (const provider of auth) {
                     if (provider.handleMetadata) {
@@ -123,12 +113,8 @@ export function createFetchHandler(opts) {
                         },
                         reservedRoutes: [
                             "/health",
-                            "/",
-                            "/credentials",
-                            "/tokens",
-                            "/activity",
-                            "/ui",
-                            "/ui/*",
+                            ...(opts.ui?.reservedPaths ?? []),
+                            ...(opts.ui && opts.activity?.list ? ["/activity"] : []),
                         ],
                     },
                     ...(opts.deploymentInfo ? { deployment: opts.deploymentInfo } : {}),
@@ -137,12 +123,6 @@ export function createFetchHandler(opts) {
             const oauthCallback = await routeOAuthCallback(context);
             if (oauthCallback)
                 return oauthCallback;
-            const ui = await routeUi(context);
-            if (ui)
-                return ui;
-            const activity = await routeActivity(context);
-            if (activity)
-                return activity;
             const mcp = await routeMcp(context);
             if (mcp)
                 return mcp;

package/dist/types.d.ts

@@ -132,6 +132,8 @@ export interface CredentialTestResult {
     message?: string;
 }
 export interface ConnectorContext {
+    /** Explicit downstream consent initiation, never set by status/catalog/calls. */
+    allowAuthorization?: boolean;
     /** Storage namespaced to this connector. */
     storage: KVStorage;
     logger: Logger;

package/dist/ui.d.ts

@@ -1,75 +1,12 @@
-import type { CredentialVault } from "./credentials.js";
+import type { OperatorSurface } from "./module-contracts.js";
+import type { CredentialVault } from "./credential-contract.js";
 import { type DeferredWork } from "./connector-scope.js";
-import { type CredentialManagementCapability, type AccessTokenManagementCapability, type UiData } from "./operator-ui/model.js";
+import { type CredentialManagementCapability, type UiData } from "./operator-ui/model.js";
 import type { RegistryView } from "./registry.js";
 import type { ConnectaBranding, UiAuthConfig } from "./types.js";
-export { filterUiConnectors, type AccessTokenManagementCapability, type CredentialManagementCapability, type UiConnector, type UiData, } from "./operator-ui/model.js";
-/** Connecta's default monochrome "C" mark. */
-export declare const CONNECTA_FAVICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 32 32\">\n  <style>\n    .fg { fill: #000 }\n    @media (prefers-color-scheme: dark) { .fg { fill: #fff } }\n  </style>\n  <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\"/>\n</svg>";
-interface ResolvedBranding {
-    productName: string;
-    productUrl?: string;
-    ownerName?: string;
-    ownerUrl?: string;
-    description: string;
-    /** Browser tab title and page meta name. */
-    pageTitle: string;
-    /** href for the page's icon link. */
-    faviconHref: string;
-    themeColor: string;
-}
-export declare function resolveBranding(branding?: ConnectaBranding): ResolvedBranding;
-/**
- * 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 declare function droppedBrandingUrls(branding?: ConnectaBranding): string[];
-export declare function isSafeHttpUrl(url: unknown): boolean;
-/**
- * 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 declare function isSafeIconHref(href: unknown): boolean;
-/** Absolute HTTPS gate for the `UiAuthConfig` URL fields documented in types.ts. */
-export declare function isSafeHttpsUrl(url: unknown): boolean;
-/**
- * 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 declare function droppedUiAuthUrls(uiAuth?: UiAuthConfig): string[];
-export type OperatorPage = "connections" | "credentials" | "tokens" | "activity";
+export { filterUiConnectors, type CredentialManagementCapability, type UiConnector, type UiData, } from "./operator-ui/model.js";
+export { CONNECTA_FAVICON_SVG, resolveBranding, isSafeHttpUrl, isSafeHttpsUrl, isSafeIconHref } from "./branding.js";
+export type OperatorPage = "connections" | "activity";
 export declare function operatorPageForPath(path: string): OperatorPage | undefined;
 export declare function operatorPageTitle(page: OperatorPage, configuredTitle: string): string;
 export declare function credentialManagementCapability(input: {
@@ -85,9 +22,17 @@ export declare function credentialManagementCapability(input: {
 export declare function buildUiData(registry: RegistryView, baseUrl: string, serverInfo: {
     name: string;
     version: string;
-}, credentialVault?: CredentialVault, activityEnabled?: boolean, credentialManagement?: CredentialManagementCapability, defer?: DeferredWork, oauthManagement?: boolean, discoveryConcurrency?: number, accessTokenManagement?: AccessTokenManagementCapability, personalCredentialOwner?: string): Promise<UiData>;
+}, credentialVault?: CredentialVault, activityEnabled?: boolean, credentialManagement?: CredentialManagementCapability, defer?: DeferredWork, oauthManagement?: boolean, discoveryConcurrency?: number, personalCredentialOwner?: string, detailOptions?: {
+    mayManage?: (id: string) => boolean;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}): Promise<UiData>;
 /**
  * Every operator page serves this same data-free shell. Connector, credential,
  * and activity data arrives only through the authenticated `/ui/*` APIs.
  */
 export declare function renderUiHtml(uiAuth?: UiAuthConfig, mcpUrl?: string, branding?: ConnectaBranding, nonce?: string, page?: OperatorPage): string;
+/** Mount the connection UI without enabling any storage or activity module. */
+export declare function operatorUi(options?: {
+    branding?: ConnectaBranding;
+}): OperatorSurface;