@zackbart/connecta 0.28.1 → 0.30.0

package/dist/authorization-handoff.js

@@ -0,0 +1,111 @@
+import { boundedEchoText } from "./errors.js";
+function oauthFollowUp(connectorId) {
+    return `Then retry the original call; connecta.search({ connector: ${JSON.stringify(connectorId)} }) inside execute_code confirms the catalog now loads.`;
+}
+/** Shared with explicit authorization; errors never request a forced restart. */
+export async function authorizationHandoff(registry, baseUrl, requestScope, opts, args) {
+    const connector = registry.getConnector(args.connector);
+    if (!connector) {
+        throw new Error(`Unknown connector "${boundedEchoText(args.connector)}"`);
+    }
+    if (!connector.startAuth) {
+        if (!connector.credential) {
+            return {
+                connector: connector.id,
+                recovery: "unavailable",
+                message: `Connector "${connector.id}" declares neither downstream OAuth ` +
+                    "nor an operator-managed credential slot. Update the connector " +
+                    "or deployment configuration before retrying.",
+            };
+        }
+        const ctx = registry.contextFor(connector.id, baseUrl, requestScope);
+        if (!ctx.credential || !opts.credentialHandoffUrl) {
+            return {
+                connector: connector.id,
+                recovery: "unavailable",
+                message: "Credential recovery needs both a vault and the optional UI. Configure " +
+                    "vault and ui in deployment code, then call " +
+                    "authorize_connector again.",
+            };
+        }
+        const fields = connector.credential.fields?.map((field) => ({
+            name: field.name,
+            guidance: field.description ?? field.label,
+        })) ?? [
+            {
+                name: "value",
+                guidance: connector.credential.description ?? connector.credential.label,
+            },
+        ];
+        return {
+            connector: connector.id,
+            recovery: "operator_config",
+            credential: {
+                label: connector.credential.label,
+                fields,
+            },
+            operatorUrl: opts.credentialHandoffUrl,
+            instructions: "Have the operator open operatorUrl, set and test the credential, " +
+                "then retry the original call. No redeploy is needed. " +
+                (connector.authScope === "personal"
+                    ? "Credential mutation requires the signed-in principal who owns this connection."
+                    : "Shared credential mutation requires a signed-in human with access to this connector."),
+        };
+    }
+    if (opts.oauthConnectUnavailable || !opts.oauthConnectUrl)
+        return {
+            connector: connector.id,
+            recovery: "unavailable",
+            message: opts.oauthConnectUnavailable ??
+                "OAuth connection requires an interactive provider and a credential vault with a handoff signing key.",
+        };
+    if (!opts.canManageAuth?.(connector.id))
+        return {
+            connector: connector.id,
+            recovery: "unavailable",
+            message: "Your identity is not permitted to manage authentication for this connection.",
+        };
+    return {
+        connector: connector.id,
+        recovery: "oauth",
+        status: "auth_required",
+        authorizationUrl: await opts.oauthConnectUrl(connector.id, args.force),
+        instructions: "Copy authorizationUrl exactly as returned; do not decode or re-encode it. Open it in a browser and sign in as the user who requested this connection. Connecta verifies your identity and permission before starting consent. " +
+            oauthFollowUp(connector.id),
+    };
+}
+const requests = new WeakMap();
+/** Retain the admitted route's factory when program utilities share its scope. */
+export function bindAuthorizationHandoffs(scope, create) {
+    if (!requests.has(scope))
+        requests.set(scope, { create, enabled: true, handoffs: new Map() });
+}
+export function enableAuthorizationHandoffs(scope, enabled) {
+    const request = requests.get(scope);
+    if (request)
+        request.enabled = enabled;
+}
+/** One promise per connector also bounds concurrent errors in a program. */
+export async function withAuthorizationHandoff(scope, error) {
+    const request = requests.get(scope);
+    if (!request?.enabled ||
+        !error.nextAction ||
+        !("tool" in error.nextAction) ||
+        error.nextAction.tool !== "authorize_connector")
+        return error;
+    const connector = error.nextAction.arguments.connector;
+    let handoff = request.handoffs.get(connector);
+    if (!handoff) {
+        handoff = request.create(connector);
+        request.handoffs.set(connector, handoff);
+    }
+    try {
+        const value = await handoff;
+        return { ...error, ...value, message: error.message, ...(value.message ? { instructions: value.message } : {}) };
+    }
+    catch {
+        // A signing/configuration failure cannot replace the original call failure
+        // or leak an arbitrary vault exception into the recovery envelope.
+        return error;
+    }
+}

package/dist/branding.d.ts

@@ -48,25 +48,18 @@ export declare function droppedThemeTokens(theme?: ConnectaTheme): string[];
  * anything that would need escaping is dropped rather than rewritten.
  */
 export declare function themeCss(theme: ResolvedTheme): string;
-/**
- * The resolved scheme as the root element's attribute. The dark palette keys
- * off `html[data-scheme]`, so "system" leaves it off and the media query
- * decides.
- */
-export declare function schemeAttribute(theme: ResolvedTheme): string;
 /** Text or attribute value, escaped for any position in an HTML document. */
 export declare function escapeHtml(value: string): string;
 export interface PageLayout {
     /** The complete `<title>`. */
     title: string;
+    /** The SPA puts the masthead in its sidebar. */
+    operatorShell?: boolean;
     /** Whether the operator UI is mounted, and so serves `/favicon.*` and `/`. */
     uiMounted: boolean;
     /**
      * The origin that serves `/favicon.*`, for a page that may be rendered on
-     * another host: root-relative icon hrefs resolve against it. A browser 404
-     * on the artifact host passes `publicUrl`, since that host answers every
-     * non-artifact path, the favicons included, with 404. Omitted, they stay
-     * root-relative.
+     * another host: root-relative icon hrefs resolve against it. Omitted, they stay root-relative.
      */
     iconOrigin?: string | undefined;
     /** Markup after the masthead: the page's `<main>`. */
@@ -119,15 +112,14 @@ export declare const STATUS_ICONS: {
 /**
  * The 404 a browser gets for a path nothing serves, and everyone else's plain
  * `Not Found`. The body is built from deployment configuration alone and names
- * no path, so every unserved path — on the main host or an artifact host —
- * answers with the same bytes for the same `Accept`: a 404 must not tell one
+ * no path, so every unserved path answers with the same bytes for the same `Accept`: a 404 must not tell one
  * route from another. The home link appears only when the operator UI is
- * mounted to land on, and points at the public origin so an artifact host's
- * 404 does not link to another 404.
+ * mounted to land on, and points at the configured public origin.
  */
 export declare function notFoundResponse(request: Request, opts: {
-    branding?: ConnectaBranding | undefined;
-    ui?: object | undefined;
+    ui?: {
+        readonly branding?: ConnectaBranding | undefined;
+    } | undefined;
     publicUrl?: string | undefined;
 }): Response;
 /**

package/dist/branding.js

@@ -1,4 +1,5 @@
 import { PAGE_CSS, TOKENS_CSS } from "./page-styles.js";
+import { htmlSecurityHeaders } from "./html-security.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>
@@ -33,11 +34,8 @@ export function resolveBranding(branding) {
         ...(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,
+        pageTitle: trimmedString(branding?.pageTitle) ?? (ownerName ? `${productName} — ${ownerName}` : productName),
+        faviconHref: faviconHref && isSafeIconHref(faviconHref) ? faviconHref : DEFAULT_FAVICON_HREF,
         themeColor: configuredThemeColor(branding) ?? "#ffffff",
         theme: resolveTheme(branding?.theme),
     };
@@ -63,8 +61,7 @@ function isFontStack(value) {
     if (value.length > 200)
         return false;
     const names = value.split(",");
-    return names.length <= 12 &&
-        names.every((name) => FONT_NAME.test(name.trim()));
+    return names.length <= 12 && names.every((name) => FONT_NAME.test(name.trim()));
 }
 const COLOR_SCHEMES = ["system", "light", "dark"];
 /**
@@ -96,9 +93,7 @@ export function resolveTheme(theme) {
  */
 function radiusLength(radius) {
     if (typeof radius === "number") {
-        return Number.isFinite(radius) && radius >= 0 && radius <= 999
-            ? `${radius}px`
-            : undefined;
+        return Number.isFinite(radius) && radius >= 0 && radius <= 999 ? `${radius}px` : undefined;
     }
     const value = trimmedString(radius);
     if (!value || !CSS_LENGTH.test(value))
@@ -128,8 +123,7 @@ export function droppedThemeTokens(theme) {
     }
     // Compared against the trimmed value the resolver reads, so `" dark "` is
     // not reported as dropped when it was applied.
-    if (isSetValue(theme.colorScheme) &&
-        trimmedString(theme.colorScheme) !== resolved.colorScheme) {
+    if (isSetValue(theme.colorScheme) && trimmedString(theme.colorScheme) !== resolved.colorScheme) {
         dropped.push("colorScheme");
     }
     return dropped.map((token) => `theme.${token}`);
@@ -154,18 +148,12 @@ export function themeCss(theme) {
  * off `html[data-scheme]`, so "system" leaves it off and the media query
  * decides.
  */
-export function schemeAttribute(theme) {
-    return theme.colorScheme === "system"
-        ? ""
-        : ` data-scheme="${theme.colorScheme}"`;
+function schemeAttribute(theme) {
+    return theme.colorScheme === "system" ? "" : ` data-scheme="${theme.colorScheme}"`;
 }
 /** Text or attribute value, escaped for any position in an HTML document. */
 export function escapeHtml(value) {
-    return value
-        .replaceAll("&", "&amp;")
-        .replaceAll('"', "&quot;")
-        .replaceAll("<", "&lt;")
-        .replaceAll(">", "&gt;");
+    return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }
 /**
  * The masthead's `--surface` in each palette, for the browser chrome a
@@ -184,8 +172,8 @@ function themeColorMeta(branding, theme) {
     if (theme.colorScheme !== "system") {
         return `<meta name="theme-color" content="${SURFACE[theme.colorScheme]}">`;
     }
-    return `<meta name="theme-color" content="${SURFACE.light}" media="(prefers-color-scheme: light)">\n` +
-        `<meta name="theme-color" content="${SURFACE.dark}" media="(prefers-color-scheme: dark)">`;
+    return (`<meta name="theme-color" content="${SURFACE.light}" media="(prefers-color-scheme: light)">\n` +
+        `<meta name="theme-color" content="${SURFACE.dark}" media="(prefers-color-scheme: dark)">`);
 }
 /**
  * The one page layout every server-rendered page shares: the operator shell,
@@ -212,22 +200,16 @@ export function renderPage(branding, layout) {
     const owner = brand.ownerName
         ? label("brand", brand.ownerName, brand.ownerUrl)
         : label("brand", brand.productName, brand.productUrl);
-    const product = brand.ownerName
-        ? label("product", brand.productName, brand.productUrl)
-        : "";
+    const product = brand.ownerName ? label("product", brand.productName, brand.productUrl) : "";
     const customIcon = brand.faviconHref !== DEFAULT_FAVICON_HREF;
     // `isSafeIconHref` already limited a relative href to one leading slash, so
     // resolving it can only land on `iconOrigin` itself.
-    const iconHref = (href) => layout.iconOrigin && href.startsWith("/")
-        ? new URL(href, layout.iconOrigin).toString()
-        : href;
+    const iconHref = (href) => layout.iconOrigin && href.startsWith("/") ? new URL(href, layout.iconOrigin).toString() : href;
     const icons = [
         ...(customIcon || layout.uiMounted
             ? [`<link rel="icon" href="${escapeHtml(iconHref(brand.faviconHref))}" type="image/svg+xml">`]
             : []),
-        ...(layout.uiMounted
-            ? [`<link rel="shortcut icon" href="${escapeHtml(iconHref("/favicon.ico"))}">`]
-            : []),
+        ...(layout.uiMounted ? [`<link rel="shortcut icon" href="${escapeHtml(iconHref("/favicon.ico"))}">`] : []),
     ];
     const skip = layout.skipTo
         ? `<a class="skip-link" href="#${escapeHtml(layout.skipTo.id)}">${escapeHtml(layout.skipTo.label)}</a>\n`
@@ -245,7 +227,7 @@ ${icons.join("\n")}
 ${layout.head ?? ""}
 <style>${styles}${themeCss(brand.theme)}</style>
 </head>
-<body>
+<body${layout.operatorShell ? ' class="operator-shell"' : ""}>
 ${skip}<header class="masthead shell">
   <div class="masthead-inner">
     <div class="mast-nav">
@@ -278,17 +260,15 @@ function wantsHtml(request) {
 /**
  * The 404 a browser gets for a path nothing serves, and everyone else's plain
  * `Not Found`. The body is built from deployment configuration alone and names
- * no path, so every unserved path — on the main host or an artifact host —
- * answers with the same bytes for the same `Accept`: a 404 must not tell one
+ * no path, so every unserved path answers with the same bytes for the same `Accept`: a 404 must not tell one
  * route from another. The home link appears only when the operator UI is
- * mounted to land on, and points at the public origin so an artifact host's
- * 404 does not link to another 404.
+ * mounted to land on, and points at the configured public origin.
  */
 export function notFoundResponse(request, opts) {
     if (!wantsHtml(request)) {
         return new Response("Not Found", { status: 404, headers: { Vary: "Accept" } });
     }
-    const brand = resolveBranding(opts.branding);
+    const brand = resolveBranding(opts.ui?.branding);
     const uiMounted = Boolean(opts.ui);
     const homeHref = opts.publicUrl ? new URL("/", opts.publicUrl).toString() : "/";
     const home = uiMounted
@@ -305,7 +285,7 @@ export function notFoundResponse(request, opts) {
     ${home}
   </section>
 </main>`;
-    return new Response(renderPage(opts.branding, {
+    return new Response(renderPage(opts.ui?.branding, {
         title: `Page not found — ${brand.pageTitle}`,
         uiMounted,
         // Same bytes on either host: the icons, like the home link, come from
@@ -314,7 +294,7 @@ export function notFoundResponse(request, opts) {
         body,
     }), {
         status: 404,
-        headers: { "Content-Type": "text/html; charset=utf-8", Vary: "Accept" },
+        headers: htmlSecurityHeaders({ "Content-Type": "text/html; charset=utf-8", Vary: "Accept" }),
     });
 }
 /**
@@ -326,9 +306,7 @@ export function notFoundResponse(request, opts) {
  * from leaving the field alone, and both take the default silently.
  */
 function isSetValue(value) {
-    return typeof value === "string"
-        ? trimmedString(value) !== undefined
-        : value !== undefined && value !== null;
+    return typeof value === "string" ? trimmedString(value) !== undefined : value !== undefined && value !== null;
 }
 /**
  * Names of the branding URLs the operator set that failed their gate and were
@@ -342,16 +320,9 @@ export function droppedBrandingUrls(branding) {
     const resolved = resolveBranding(branding);
     const faviconHref = branding.favicon?.href;
     return [
-        ...(isSetValue(branding.productUrl) && !resolved.productUrl
-            ? ["productUrl"]
-            : []),
-        ...(isSetValue(branding.ownerUrl) && !resolved.ownerUrl
-            ? ["ownerUrl"]
-            : []),
-        ...(isSetValue(faviconHref) &&
-            trimmedString(faviconHref) !== resolved.faviconHref
-            ? ["favicon.href"]
-            : []),
+        ...(isSetValue(branding.productUrl) && !resolved.productUrl ? ["productUrl"] : []),
+        ...(isSetValue(branding.ownerUrl) && !resolved.ownerUrl ? ["ownerUrl"] : []),
+        ...(isSetValue(faviconHref) && trimmedString(faviconHref) !== resolved.faviconHref ? ["favicon.href"] : []),
     ];
 }
 /**
@@ -443,11 +414,7 @@ export function droppedUiAuthUrls(uiAuth) {
         return [];
     return [
         ...(isSafeHttpsUrl(uiAuth.frontendApiUrl) ? [] : ["uiAuth.frontendApiUrl"]),
-        ...(isSetValue(uiAuth.signInUrl) && !isSafeHttpsUrl(uiAuth.signInUrl)
-            ? ["uiAuth.signInUrl"]
-            : []),
-        ...(isSetValue(uiAuth.signUpUrl) && !isSafeHttpsUrl(uiAuth.signUpUrl)
-            ? ["uiAuth.signUpUrl"]
-            : []),
+        ...(isSetValue(uiAuth.signInUrl) && !isSafeHttpsUrl(uiAuth.signInUrl) ? ["uiAuth.signInUrl"] : []),
+        ...(isSetValue(uiAuth.signUpUrl) && !isSafeHttpsUrl(uiAuth.signUpUrl) ? ["uiAuth.signUpUrl"] : []),
     ];
 }

package/dist/byte-read-response.js

@@ -0,0 +1,39 @@
+// Web-API only, like the rest of the core: Node and workerd read a body alike.
+const decoder = new TextDecoder();
+/**
+ * A downstream's response whose `text()` and `json()` read bytes.
+ *
+ * workerd, when `.text()` (and `.json()`, which reads text) meets a body whose
+ * Content-Type it does not parse as text, prints a native warning quoting that
+ * Content-Type whole: below every console and logger, so a downstream could
+ * write into the deployment's log (INV-6, #695). No filter on the header can
+ * agree with workerd's own parser for every value a downstream can send, so
+ * connecta never asks for text: `arrayBuffer()` carries no such warning, and
+ * the bytes are decoded here exactly as `text()` would decode them (UTF-8,
+ * BOM stripped, malformed sequences replaced).
+ *
+ * The response itself is returned, its readers shadowed by own properties, so
+ * `status`, `headers`, `url`, `body`, and `instanceof Response` are unchanged,
+ * and so is everything an SDK or a handler reads. A clone is shadowed too:
+ * the pinned SDK reads a token response's `clone().json()`.
+ */
+export function byteReadResponse(response) {
+    if (!Object.isExtensible(response)) {
+        // A custom fetch that froze its response: shadow a copy instead, which
+        // keeps everything but `url` and `redirected`.
+        return byteReadResponse(new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        }));
+    }
+    const arrayBuffer = response.arrayBuffer.bind(response);
+    const clone = response.clone.bind(response);
+    const text = async () => decoder.decode(await arrayBuffer());
+    const own = (value) => ({ value, configurable: true, writable: true });
+    return Object.defineProperties(response, {
+        text: own(text),
+        json: own(async () => JSON.parse(await text())),
+        clone: own(() => byteReadResponse(clone())),
+    });
+}

package/dist/call-admission.js

@@ -1,6 +1,6 @@
 import { Deferred, Duration, Effect } from "effect";
 import { ConnectorCallError } from "./errors.js";
-import { provideCallAdmissionProgram, startCallAdmission, } from "./runtime/call-admission.js";
+import { provideCallAdmissionProgram, startCallAdmission } from "./runtime/call-admission.js";
 import { fromSignal, runEdge } from "./runtime/run.js";
 const DEFAULT_MAX_QUEUE_SIZE = 32;
 const DEFAULT_QUEUE_TIMEOUT_MS = 5_000;
@@ -28,7 +28,11 @@ export function isCallAdmissionError(error) {
 /** Sum gauges and counters without publishing connector or principal keys. */
 export function aggregateCallAdmissionSnapshots(snapshots) {
     const aggregate = {
-        rules: 0, partitions: 0, active: 0, queued: 0, closed: snapshots.length > 0,
+        rules: 0,
+        partitions: 0,
+        active: 0,
+        queued: 0,
+        closed: snapshots.length > 0,
         totals: { admitted: 0, queued: 0, rejected: 0, rateLimited: 0, cancelled: 0 },
         queueWaitMs: { count: 0, total: 0, max: 0 },
     };
@@ -88,8 +92,7 @@ export class ConnectorCallAdmissionController {
             throw new TypeError(`connector "${connectorId}" callAdmission.rules must contain exactly one rule in this release.`);
         }
         const rule = policy.rules[0];
-        if (rule.maxConcurrency === undefined &&
-            rule.budget === undefined) {
+        if (rule.maxConcurrency === undefined && rule.budget === undefined) {
             throw new TypeError(`connector "${connectorId}" callAdmission rule must declare maxConcurrency or budget.`);
         }
         this.maxConcurrency =
@@ -97,9 +100,7 @@ export class ConnectorCallAdmissionController {
                 ? undefined
                 : positiveWhole(rule.maxConcurrency, `connector "${connectorId}" callAdmission maxConcurrency`);
         if (this.maxConcurrency === undefined &&
-            (rule.maxQueueSize !== undefined ||
-                rule.queueTimeoutMs !== undefined ||
-                rule.retryAfterMs !== undefined)) {
+            (rule.maxQueueSize !== undefined || rule.queueTimeoutMs !== undefined || rule.retryAfterMs !== undefined)) {
             throw new TypeError(`connector "${connectorId}" callAdmission queue settings require maxConcurrency.`);
         }
         this.maxQueueSize = nonNegativeWhole(rule.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE, `connector "${connectorId}" callAdmission maxQueueSize`);
@@ -193,8 +194,7 @@ export class ConnectorCallAdmissionController {
     pump(state) {
         if (this.closed || this.maxConcurrency === undefined)
             return;
-        while (state.active < this.maxConcurrency &&
-            state.waiters.length > 0) {
+        while (state.active < this.maxConcurrency && state.waiters.length > 0) {
             const waiter = state.waiters.shift();
             // The waiter's signal is not read here. This runs in whichever request
             // released a slot, and on Workers reading an AbortSignal that another
@@ -248,9 +248,7 @@ export class ConnectorCallAdmissionController {
     }
     maybeDeletePartition(key, state, now) {
         this.pruneBudget(state, now);
-        if (state.active === 0 &&
-            state.waiters.length === 0 &&
-            state.admittedAt.length === 0) {
+        if (state.active === 0 && state.waiters.length === 0 && state.admittedAt.length === 0) {
             this.partitions.delete(key);
         }
     }
@@ -322,8 +320,7 @@ export class ConnectorCallAdmissionController {
                 controller.rejectedTotal++;
                 return Effect.fail(new CallAdmissionError("partition", "connector_call_failed", `Connector "${controller.connectorId}" call-admission partitionKey threw.`, { cause }));
             }
-            if (typeof key !== "string" ||
-                enc.encode(key).length > MAX_PARTITION_KEY_BYTES) {
+            if (typeof key !== "string" || enc.encode(key).length > MAX_PARTITION_KEY_BYTES) {
                 controller.rejectedTotal++;
                 return Effect.fail(new CallAdmissionError("partition", "connector_call_failed", `Connector "${controller.connectorId}" call-admission partitionKey must return a string of at most ${MAX_PARTITION_KEY_BYTES} UTF-8 bytes.`));
             }
@@ -352,8 +349,7 @@ export class ConnectorCallAdmissionController {
                 controller.rateLimitedTotal++;
                 return Effect.fail(controller.budgetLimited(budgetRetryAfterMs));
             }
-            if (controller.maxConcurrency === undefined ||
-                state.active < controller.maxConcurrency) {
+            if (controller.maxConcurrency === undefined || state.active < controller.maxConcurrency) {
                 return Effect.succeed(controller.admit(state, queuedAt, 0));
             }
             if (state.waiters.length >= controller.maxQueueSize) {