@zackbart/connecta 0.20.0 → 0.21.1

package/dist/providers/stripe.js

@@ -37,16 +37,16 @@ const READ_ONLY_TOOLS = new Set([
     "stripe_api_search",
     "stripe_api_details",
     "stripe_api_read",
-    "get_stripe_account_info",
     "get_balance_summary",
+    "list_available_accounts_or_orgs",
+    "manage_stripe_accounts",
     "search_stripe_documentation",
-    "stripe_implementation_planner",
 ]);
-/** Reviewed writes, including refund rationale: `documentation/stripe.md`. */
+/** Reviewed writes, including mixed read/create tools: `documentation/stripe.md`. */
 const WRITE_TOOLS = new Map([
     ["stripe_api_write", "destructive"],
-    ["create_refund", "destructive"],
-    ["stripe_report", "additive"],
+    ["stripe_implementation_planner", "additive"],
+    ["stripe_analytics", "additive"],
     ["send_stripe_mcp_feedback", "additive"],
 ]);
 /** Release-reviewed manifest; see provider conventions P5 and P13. */
@@ -149,7 +149,8 @@ ${accountInstructions
 function sharedUsageGuide(rate) {
     return `
 - Four generic tools reach any Stripe API method. Find the method with \`stripe_api_search\`, read its parameters with \`stripe_api_details\`, then call \`stripe_api_read\` (GET) or \`stripe_api_write\` (POST/PATCH/PUT/DELETE). Never guess a path or a parameter name — \`stripe_api_details\` is cheaper than a rejected write.
-- Prefer a dedicated tool when one covers the task: \`get_stripe_account_info\` for account information, \`get_balance_summary\` for balances, \`create_refund\` for refunds, \`stripe_report\` for reports. One call instead of three, and a refund named \`create_refund\` reads far more clearly in the approval a human sees than the same refund buried in \`stripe_api_write\` arguments.
+- Prefer a dedicated tool when one covers the task: \`get_balance_summary\` for balances and \`stripe_analytics\` for Sigma or Metrics reporting. Use \`stripe_api_search\` for everything else instead of assuming a retired dedicated tool still exists.
+- \`stripe_implementation_planner\` and the query-execution intents of \`stripe_analytics\` create provider-side planning or query-run state. Connecta therefore routes both through \`call_destructive_tool\` as non-destructive writes; their retrieval paths stay behind the same tool boundary.
 - \`stripe_api_write\` carries the blast radius of the entire write API — every POST, PATCH, PUT, and DELETE, from a customer edit to a subscription cancellation. State the method and path explicitly; expect approval on every call.
 - Lists are cursor-paginated: \`limit\` defaults to 10 and caps at 100, \`starting_after\` and \`ending_before\` take an object id and are mutually exclusive, and \`has_more\` says whether to continue. Page inside \`execute_code\`.
 - Any \`stripe_api_read\` list or \`stripe_api_search\` that returns full objects belongs inside \`execute_code\`, projected to the fields the question needs before \`return\`. Neither \`limit\` nor \`expand\` substitutes for that: an unprojected list of customers or invoices truncates long before it answers, and a projected one keeps the customer's name, email, and address out of the transcript.

package/dist/routes/access-tokens.d.ts

@@ -1,6 +1,6 @@
 import { type RouteContext } from "./shared.js";
 /**
- * Clerk-only lifecycle for deployment access tokens. The access token itself
+ * Interactive-operator lifecycle for deployment access tokens. The token itself
  * is deliberately never an administrator credential and cannot reach here.
  */
 export declare function routeAccessTokens(context: RouteContext): Promise<Response | null>;

package/dist/routes/access-tokens.js

@@ -28,7 +28,7 @@ async function readName(request) {
     }
 }
 /**
- * Clerk-only lifecycle for deployment access tokens. The access token itself
+ * Interactive-operator lifecycle for deployment access tokens. The token itself
  * is deliberately never an administrator credential and cannot reach here.
  */
 export async function routeAccessTokens(context) {
@@ -46,7 +46,7 @@ export async function routeAccessTokens(context) {
     if (mutating && !isSameOrigin(request, baseUrl)) {
         return privateJson({ error: "same-origin request required" }, { status: 403 });
     }
-    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "access token management");
+    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "access token management", context.runtimeContext);
     if (!admin.ok)
         return admin.response;
     const id = match[1];

package/dist/routes/activity.js

@@ -128,13 +128,13 @@ async function enrichActivityActorLabels(page, auth) {
     };
 }
 export async function routeActivity(context) {
-    const { path, request, url, baseUrl, opts } = context;
+    const { path, request, url, baseUrl, opts, runtimeContext } = context;
     if (path !== "/ui/activity")
         return null;
     if (request.method !== "GET") {
         return privateJson({ error: "method not allowed" }, { status: 405 });
     }
-    const authz = await authorize(request, baseUrl, opts.auth);
+    const authz = await authorize(request, baseUrl, opts.auth, runtimeContext);
     if (!authz.ok)
         return authz.response;
     if (opts.activityReadGate &&

package/dist/routes/credentials.js

@@ -73,7 +73,7 @@ async function handleCredentialRequest(context, connectorId, action) {
     if (!isSameOrigin(request, baseUrl)) {
         return privateJson({ error: "same-origin request required" }, { status: 403 });
     }
-    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth);
+    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "credential management", context.runtimeContext);
     if (!admin.ok)
         return admin.response;
     const connector = opts.registry.getConnector(connectorId);

package/dist/routes/mcp.js

@@ -329,7 +329,7 @@ export function createMcpRoute(opts) {
             throw error;
         }
         try {
-            const authz = await authorize(request, baseUrl, opts.auth);
+            const authz = await authorize(request, baseUrl, opts.auth, runtimeContext);
             if (!authz.ok) {
                 return releaseAdmissionWithResponse(withMcpCors(authz.response), admission, request.signal);
             }

package/dist/routes/oauth.js

@@ -7,7 +7,7 @@ async function handleOAuthManagementRequest(context, connectorId) {
     if (!isSameOrigin(request, baseUrl)) {
         return privateJson({ error: "same-origin request required" }, { status: 403 });
     }
-    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "OAuth management");
+    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "OAuth management", context.runtimeContext);
     if (!admin.ok)
         return admin.response;
     const connector = opts.registry.getConnector(connectorId);

package/dist/routes/shared.d.ts

@@ -5,7 +5,7 @@ import type { CredentialVault } from "../credentials.js";
 import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.js";
 import type { Registry } from "../registry.js";
-import type { ConnectaBranding, Executor, InboundAuth, Logger } from "../types.js";
+import type { ConnectaBranding, Executor, InboundAuth, InboundAuthRuntimeContext, Logger } from "../types.js";
 export { msg } from "../errors.js";
 export interface ServerOptions {
     registry: Registry;
@@ -40,7 +40,7 @@ export interface ServerOptions {
     /** Optional browser UI and OAuth result-page labels. */
     branding?: ConnectaBranding | undefined;
 }
-export interface RuntimeExecutionContext {
+export interface RuntimeExecutionContext extends InboundAuthRuntimeContext {
     waitUntil(promise: Promise<unknown>): void;
 }
 export interface RouteContext {
@@ -64,7 +64,7 @@ export declare function privateJson(body: unknown, init?: ResponseInit): Respons
  */
 export declare function loggableValue(requested: string): string;
 export declare function activityActorNamespace(provider: InboundAuth): string | undefined;
-export declare function authorize(request: Request, baseUrl: string, auth: InboundAuth[]): Promise<{
+export declare function authorize(request: Request, baseUrl: string, auth: InboundAuth[], runtimeContext?: RuntimeExecutionContext): Promise<{
     ok: true;
     actor: ActivityActor;
     /** True only when the admitting provider can also authorize UI mutation. */
@@ -73,7 +73,7 @@ export declare function authorize(request: Request, baseUrl: string, auth: Inbou
     ok: false;
     response: Response;
 }>;
-export declare function authorizeUiAdmin(request: Request, baseUrl: string, auth: InboundAuth[], purpose?: string): Promise<{
+export declare function authorizeUiAdmin(request: Request, baseUrl: string, auth: InboundAuth[], purpose?: string, runtimeContext?: RuntimeExecutionContext): Promise<{
     ok: true;
     userId: string;
 } | {

package/dist/routes/shared.js

@@ -29,13 +29,13 @@ export function activityActorNamespace(provider) {
         ? provider.activityActorNamespace
         : undefined;
 }
-export async function authorize(request, baseUrl, auth) {
+export async function authorize(request, baseUrl, auth, runtimeContext) {
     if (auth.length === 0) {
         return { ok: true, actor: { kind: "anonymous" } };
     }
     let lastResponse = null;
     for (const provider of auth) {
-        const result = await provider.authorize(request, baseUrl);
+        const result = await provider.authorize(request, baseUrl, runtimeContext);
         if (result.ok) {
             const subjectId = result.subjectId ?? result.userId;
             const actorNamespace = activityActorNamespace(provider);
@@ -48,7 +48,7 @@ export async function authorize(request, baseUrl, auth) {
                         ? { namespace: actorNamespace }
                         : {}),
                 },
-                ...(result.userId && provider.uiAuth?.kind === "clerk"
+                ...(result.userId && provider.interactiveOperator
                     ? { uiAdminEligible: true }
                     : {}),
             };
@@ -67,25 +67,25 @@ export async function authorize(request, baseUrl, auth) {
             }),
     };
 }
-export async function authorizeUiAdmin(request, baseUrl, auth, purpose = "credential management") {
+export async function authorizeUiAdmin(request, baseUrl, auth, purpose = "credential management", runtimeContext) {
     // Operator mutation is intentionally narrower than /mcp and /ui/data: only
-    // an interactive Clerk provider may admit it. A static bearer token is useful
+    // 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 Clerk 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
+    // 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 providers = auth.filter((candidate) => candidate.uiAuth?.kind === "clerk");
+    const providers = auth.filter((candidate) => candidate.interactiveOperator);
     if (providers.length === 0) {
         return {
             ok: false,
-            response: privateJson({ error: `${purpose} requires Clerk authentication` }, { status: 403 }),
+            response: privateJson({ error: `${purpose} requires interactive operator authentication` }, { status: 403 }),
         };
     }
     let lastResponse = null;
     for (const provider of providers) {
-        const result = await provider.authorize(request, baseUrl);
+        const result = await provider.authorize(request, baseUrl, runtimeContext);
         if (!result.ok) {
             lastResponse = result.response;
             continue;

package/dist/routes/ui.js

@@ -37,7 +37,7 @@ function uiScriptNonce() {
     return btoa(binary);
 }
 export async function routeUi(context) {
-    const { request, url, path, baseUrl, opts, defer } = context;
+    const { request, url, path, baseUrl, opts, defer, runtimeContext } = context;
     if (request.method === "GET" && path === "/favicon.svg") {
         return new Response(opts.branding?.favicon?.svg ?? CONNECTA_FAVICON_SVG, {
             headers: {
@@ -73,7 +73,10 @@ export async function routeUi(context) {
         }
         // Open shell — carries no operator data; everything comes from the
         // authenticated /ui/* APIs after the browser establishes a session.
-        const uiAuth = opts.auth.find((provider) => provider.uiAuth)?.uiAuth;
+        const ambient = runtimeContext?.access
+            ? opts.auth.find((provider) => provider.uiAuth?.kind === "cloudflare-access")?.uiAuth
+            : undefined;
+        const uiAuth = ambient ?? opts.auth.find((provider) => provider.uiAuth && provider.uiAuth.kind !== "cloudflare-access")?.uiAuth;
         const mcpUrl = new URL("/mcp", baseUrl).toString();
         // Nonce the page's inline script (and the Clerk loader). 'strict-dynamic'
         // lets scripts the nonced Clerk loader injects at runtime execute; the
@@ -96,28 +99,28 @@ export async function routeUi(context) {
     }
     if (path !== "/ui/data")
         return null;
-    const authz = await authorize(request, baseUrl, opts.auth);
+    const authz = await authorize(request, baseUrl, opts.auth, runtimeContext);
     if (!authz.ok)
         return authz.response;
-    const eligibleClerkOperator = authz.uiAdminEligible === true;
+    const eligibleOperator = authz.uiAdminEligible === true;
     const credentialManagement = credentialManagementCapability({
-        eligibleClerkOperator,
+        eligibleOperator,
         hasCredentialSlots: opts.registry
             .listConnectors()
             .some((connector) => Boolean(connector.credential)),
         hasCredentialVault: Boolean(opts.credentialVault),
     });
     // As with connector credentials, a Bearer-authenticated observer learns
-    // only that Clerk is required—not whether this deployment has opted into
+    // only that an interactive operator is required, not whether this deployment has opted into
     // token issuance. Configuration topology is operator data.
-    const accessTokenManagement = !eligibleClerkOperator
-        ? "requires_clerk"
+    const accessTokenManagement = !eligibleOperator
+        ? "requires_operator"
         : opts.accessTokens
             ? "available"
             : "not_configured";
     const data = await buildUiData(opts.registry, baseUrl, opts.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, defer, eligibleClerkOperator, opts.discoveryConcurrency, accessTokenManagement);
+    eligibleOperator ? opts.credentialVault : undefined, Boolean(opts.activity?.list), credentialManagement, defer, eligibleOperator, opts.discoveryConcurrency, accessTokenManagement);
     return privateJson(data);
 }

package/dist/skills.d.ts

@@ -1,5 +1,5 @@
 import type { Connector } from "./types.js";
-export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. For one read at an unknown address, use search_tools then call_tool; a known address needs only call_tool. For read-only reduction, multiple or dependent calls, loops, joins, or branches, use one execute_code program that discovers, calls, and returns the reduced answer. Only readOnlyHint: true tools run there. Keep unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool. After auth_required use authorize_connector. After a truncated direct result use get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Fetch skills({ name: \"usage\" }) once for program syntax, selection, repair, examples, and runtime details.";
+export declare const CONNECTA_INSTRUCTIONS = "Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with one execute_code program that discovers, calls, and returns the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Guidance is on demand: fetch skills({ name: \"usage\" }) only when these instructions and the tool description are insufficient or a run needs repair.";
 /** Shared Connecta routing guidance, byte-identical across deployments. */
 export declare const USAGE_SKILL: string;
 /** The always-loaded MCP `instructions` string. */

package/dist/skills.js

@@ -1,11 +1,11 @@
-export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. For one read at an unknown address, use search_tools then call_tool; a known address needs only call_tool. For read-only reduction, multiple or dependent calls, loops, joins, or branches, use one execute_code program that discovers, calls, and returns the reduced answer. Only readOnlyHint: true tools run there. Keep unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool. After auth_required use authorize_connector. After a truncated direct result use get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Fetch skills({ name: "usage" }) once for program syntax, selection, repair, examples, and runtime details.';
+export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with one execute_code program that discovers, calls, and returns the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. connecta.ui(html) exists only inside execute_code, not in connector search; return the same summary data the HTML renders. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
 const USAGE_SKILL_BASE = `# Connecta usage
 
 ## The surface
 
-Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Broad discovery and multi-call work live in a program, not in top-level tools.
+Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Read-only discovery and multi-call work live in a program. Top-level search remains for catalog inspection and approval-required work.
 
-The always-loaded MCP instructions are authoritative for choosing the top-level route. Read this skill at most once per task for the program workflow and recovery details below.
+The always-loaded MCP instructions are authoritative for choosing the top-level route. Read this skill at most once, and only when their program workflow is insufficient or a run needs repair.
 
 ## Inside a program
 
@@ -23,13 +23,16 @@ The minimum guest API is:
 
 Search inside the run and finish the task there. A discovery-only program wastes a round trip. Use 2–4 distinctive action/object terms, not the full request. Use separate short searches for distinct operations.
 
-For top-level \`search_tools\`, omit \`limit\` initially (the default is 10), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and available output shapes. An observed shape carries \`outputSchemaSource: "observed"\`; treat it as routing evidence rather than a provider contract. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
+For top-level catalog inspection or approval-required discovery, omit \`limit\` initially (the default is 10), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and available output shapes. An observed shape carries \`outputSchemaSource: "observed"\`; treat it as routing evidence rather than a provider contract. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
 
 - \`connecta.search({})\` loads all catalogs. Pass \`connector: "<id>"\` when the integration is obvious. Use \`safety: "readOnly"\` for program calls. These inputs filter discovery; they grant no authority.
 - Request \`includeSchemas: "compact"\`. Check address, purpose, annotations, required inputs, truncation, safety, and available outputs. Never select only because a result ranks first or has fewer required inputs.
 - Supply every \`requiredInputKey\` from the task or a prior result. For dependencies, match the earlier \`outputKey\` to the later required key. An empty required-key list does not permit invented arguments. Missing \`outputKeys\` means inspect \`outputSchema\`.
 - Use \`connecta.describe({ address })\` or \`{ addresses }\` when a compact schema is truncated or insufficient. Use \`format: "json"\` only for exact constraints. Write the property names the schema displays; never guess positions or aliases.
 - Reduce through available output keys. Treat an observed key as a hint, since later results may omit it or add others. Do not guess collection roots such as \`items\` or \`results\`. If a match or result key is missing, inspect, re-search, or describe inside the same run instead of returning discovery for another call.
+- Match provider identifiers and names exactly after resolving them from source data or a connector guide. A broad regular expression that merely finds a plausible value is not identity resolution.
+- Preserve the schema's JSON types exactly: a numeric id is a number, not a numeric-looking string. Call the search and describe functions directly; batch accepts canonical connector tool addresses, not guest API function names.
+- Validate tabular headers, row arrays, and row widths before mapping them. Never let a header or partial row become data.
 
 Only tools explicitly annotated \`readOnlyHint: true\` are reachable. The catalog, credential, admission, and read-only gates run below the sandbox; code cannot widen its authority.
 

package/dist/types.d.ts

@@ -426,35 +426,48 @@ export type AuthResult = {
 };
 /** Public browser-auth configuration exposed to connecta's status UI. */
 export type UiAuthConfig = {
+    kind: "cloudflare-access";
+} | {
     kind: "clerk";
     publishableKey: string;
     /**
-     * Origin the operator shell fetches its browser sign-in loader from. **Must be an absolute
-     * `https:` URL** — the value lands in a `<script src>`, so the gate is
-     * stricter than the branding href gate: no `http:`, no loopback exemption, and
-     * no root-relative form (a relative path is rejected, not resolved). The
-     * shipped `clerkAuth` adapter derives this from the publishable key and
-     * Clerk's Frontend API is always https, so nothing legitimate needs a
-     * carve-out. A value that fails the gate reaches neither the loader tag nor
-     * the page's inline auth config: operator pages render without it and report
-     * that Clerk could not load, and `createConnecta` names the drop in a startup
-     * warning.
+     * Origin the operator shell fetches its browser sign-in loader from.
+     * **Must be an absolute `https:` URL** — the value lands in a `<script
+     * src>`, so the gate is stricter than the branding href gate: no `http:`,
+     * no loopback exemption, and no root-relative form (a relative path is
+     * rejected, not resolved). The shipped `clerkAuth` adapter derives this
+     * from the publishable key and Clerk's Frontend API is always https, so
+     * nothing legitimate needs a carve-out. A value that fails the gate
+     * reaches neither the loader tag nor the page's inline auth config:
+     * operator pages render without it and report that Clerk could not load,
+     * and `createConnecta` names the drop in a startup warning.
      */
     frontendApiUrl: string;
     /**
-     * Hosted Account Portal sign-in address, handed to `Clerk.load`. **Must be an
-     * absolute `https:` URL** — the same gate `frontendApiUrl` passes, because
-     * this value is where Clerk *navigates* the operator's browser. An Account
-     * Portal address is always https, so the stricter gate costs nothing real: a
-     * value that fails it (a `javascript:`/`data:` payload, a cleartext `http:`
-     * address, a relative path) reaches no part of the page, the shell signs in
-     * through Clerk's default instead, and `createConnecta` names the drop in a
-     * startup warning.
+     * Hosted Account Portal sign-in address, handed to `Clerk.load`. **Must
+     * be an absolute `https:` URL** — the same gate `frontendApiUrl` passes,
+     * because this value is where Clerk *navigates* the operator's browser.
+     * An Account Portal address is always https, so the stricter gate costs
+     * nothing real: a value that fails it (a `javascript:`/`data:` payload,
+     * a cleartext `http:` address, a relative path) reaches no part of the
+     * page, the shell signs in through Clerk's default instead, and
+     * `createConnecta` names the drop in a startup warning.
      */
     signInUrl?: string;
     /** Hosted Account Portal sign-up address. Gated exactly like `signInUrl`. */
     signUpUrl?: string;
 };
+/**
+ * Runtime identity context an inbound-auth provider may consume. The shape is
+ * deliberately structural: core stays Web-API-only while a Worker can pass
+ * Cloudflare's authenticated `ctx.access` object through unchanged.
+ */
+export interface InboundAuthRuntimeContext {
+    readonly access?: {
+        readonly aud: string;
+        getIdentity(): Promise<Record<string, unknown> | undefined>;
+    };
+}
 /**
  * Optional labels and marks used by the browser UI and OAuth result pages.
  * Every deployment-identifying string and image is configurable here — nothing
@@ -493,9 +506,11 @@ export interface ConnectaBranding {
     /** `theme-color` meta value. Defaults to "#ffffff". */
     themeColor?: string;
 }
-/** An inbound authentication provider (bearer token, Clerk, ...). */
+/** An inbound authentication provider (bearer token, interactive identity, ...). */
 export interface InboundAuth {
     kind: string;
+    /** This provider may admit a human identity to operator mutation routes. */
+    interactiveOperator?: true;
     /**
      * Stable, non-secret namespace of the identity directory behind
      * `activityActorLabel`. Stored with new activity actors so two providers with
@@ -512,13 +527,13 @@ export interface InboundAuth {
      */
     activityActorLabel?(subjectId: string): string | undefined | Promise<string | undefined>;
     /**
-     * Optional browser sign-in configuration. When present, operator pages use it
-     * provider instead of asking the operator to paste a static bearer secret.
+     * Optional browser sign-in configuration. When present, operator pages use
+     * the provider instead of asking the operator to paste a static bearer secret.
      */
     uiAuth?: UiAuthConfig;
     /** Serve/short-circuit .well-known + OPTIONS. Return null when not handled. */
     handleMetadata?(request: Request, baseUrl: string): Response | null | Promise<Response | null>;
     /** Attempt to authorize a request. */
-    authorize(request: Request, baseUrl: string): AuthResult | Promise<AuthResult>;
+    authorize(request: Request, baseUrl: string, runtimeContext?: InboundAuthRuntimeContext): AuthResult | Promise<AuthResult>;
 }
 export {};

package/dist/ui.d.ts

@@ -73,7 +73,7 @@ export type OperatorPage = "connections" | "credentials" | "tokens" | "activity"
 export declare function operatorPageForPath(path: string): OperatorPage | undefined;
 export declare function operatorPageTitle(page: OperatorPage, configuredTitle: string): string;
 export declare function credentialManagementCapability(input: {
-    eligibleClerkOperator: boolean;
+    eligibleOperator: boolean;
     hasCredentialSlots: boolean;
     hasCredentialVault: boolean;
 }): CredentialManagementCapability;

package/dist/ui.js

@@ -208,8 +208,8 @@ export function operatorPageTitle(page, configuredTitle) {
     return `${OPERATOR_PAGE_LABELS[page]} — ${configuredTitle}`;
 }
 export function credentialManagementCapability(input) {
-    if (!input.eligibleClerkOperator)
-        return "requires_clerk";
+    if (!input.eligibleOperator)
+        return "requires_operator";
     if (!input.hasCredentialSlots)
         return "no_slots";
     if (!input.hasCredentialVault)
@@ -223,7 +223,7 @@ export function credentialManagementCapability(input) {
  */
 export async function buildUiData(registry, baseUrl, serverInfo, credentialVault, activityEnabled = false, credentialManagement = credentialVault
     ? "available"
-    : "requires_clerk", defer, oauthManagement = false, discoveryConcurrency, accessTokenManagement = "not_configured") {
+    : "requires_operator", defer, oauthManagement = false, discoveryConcurrency, accessTokenManagement = "not_configured") {
     const requestScope = {};
     const connectorSet = registry.listConnectors();
     const concurrency = resolveDiscoveryConcurrency(discoveryConcurrency);

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.20.0";
+export declare const CONNECTA_VERSION = "0.21.1";

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.20.0";
+export const CONNECTA_VERSION = "0.21.1";

package/documentation/architecture.md

@@ -48,6 +48,7 @@ read top to bottom.
 | Order | Route | Notes |
 | --- | --- | --- |
 | 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. |
@@ -72,7 +73,7 @@ any one file and a reordering reads like a harmless refactor.
    ([request admission](./request-admission.md)). The permit is held until the
    response *body* completes, not until the handler returns.
 2. **Authorize.** Each `InboundAuth` provider's `authorize` in order, bearer
-   before Clerk. First `ok` admits; if all fail, the last provider's challenge
+   before interactive providers. First `ok` admits; if all fail, the last provider's challenge
    response is returned. No providers configured means open — development
    only, and it warns at construction.
 3. **Refuse `?toolkit=`.** Toolkits were removed ([#178](https://github.com/zackbart/connecta/issues/178))
@@ -116,7 +117,9 @@ The Node-touching paths are `src/node.ts` (the `node:http` adapter),
 subpath export — `@zackbart/connecta/node`, `@zackbart/connecta/quickjs` — and
 must stay unreachable from the root entry. The optional Clerk adapter is behind
 `./auth/clerk` for the adjacent reason: `@clerk/backend` is an optional peer,
-not a dependency.
+not a dependency. The zero-dependency Cloudflare Access adapter likewise stays
+behind `./auth/cloudflare-access`: it is Web-API-pure, but its trust contract is
+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
@@ -156,7 +159,7 @@ src/
   operator-ui/        the Preact app, its pure rules, and the built bundle
   connectors/         remote-mcp.ts, api.ts, guarded-fetch.ts
   providers/          the maintained prebuilt connections
-  auth/               bearer, clerk (optional peer), downstream OAuth
+  auth/               bearer, Cloudflare Access, clerk (optional peer), downstream OAuth
   executors/          the QuickJS pool and child (Node only)
   storage/            memory.ts, file.ts (Node only)
   node.ts             listen() + fileStorage re-export (Node only)
@@ -177,7 +180,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 a Clerk provider, a missing
+  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
   worse than one that does not start.
 

package/documentation/auth.md

@@ -1,8 +1,72 @@
 # Inbound auth
 
 Inbound auth decides who may reach the MCP endpoint. A deployment may admit a
-static bearer, operator-issued access tokens, Clerk identities, or a mixture.
-Static bearers are checked first.
+static bearer, operator-issued access tokens, Clerk identities, Cloudflare
+Access identities on Workers, or a mixture. Static bearers are checked first;
+the remaining providers keep configuration order. The first successful
+identity owns the activity actor for that request.
+
+## Cloudflare Access on Workers
+
+[`cloudflareAccessAuth()`](https://developers.cloudflare.com/workers/configuration/cloudflare-access/)
+is the Worker-specific path:
+
+```ts
+import { cloudflareAccessAuth } from
+  "@zackbart/connecta/auth/cloudflare-access";
+
+createConnecta({
+  auth: cloudflareAccessAuth(),
+  connectors,
+  executor,
+});
+```
+
+The adapter trusts only `ctx.access`, which Cloudflare creates after Access has
+authenticated a request that directly invokes the Worker. It calls
+`ctx.access.getIdentity()` for a human. Cloudflare returns no user identity for
+a service token and strips the service-token headers before invoking the
+Worker, so after `ctx.access` proves admission the adapter uses the Access
+application audience as the automation activity subject. Service tokens on the
+same Access application therefore share attribution. It never reads
+`Cf-Access-Jwt-Assertion`, downloads signing keys, or accepts a JWT from the
+caller. A missing context or an identity lookup that throws fails closed. This
+also means it is deliberately not a Node or `cloudflared` origin adapter, and
+it does not survive a Service Binding hop: those shapes need their own explicit
+trust boundary.
+
+A human identity gets MCP and operator access. A Cloudflare service-token
+identity gets MCP access and a stable activity subject, but no `userId`, so it
+cannot write credentials, run downstream OAuth mutations, or issue connecta
+tokens. Access policy decides who reaches the Worker; connecta does not mirror
+email domains, groups, or device posture into a second policy layer.
+
+Protect the Worker with a Worker-level Access application whose destination is
+`{ "type": "worker", "worker_id": "<the Worker script tag>" }`. A traditional
+hostname-level application blocks the URL but does not attach `ctx.access` to
+the Worker. Enable [**Managed OAuth**](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/)
+on that Worker-level application for interactive MCP clients.
+Cloudflare then owns the unauthenticated challenge and `/.well-known/`
+metadata, issues opaque RFC 8707 tokens, and resolves them into the same trusted
+Worker identity. Do not add a bypass for the discovery routes. A fully
+automated client instead uses a [Cloudflare Access service token](https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/)
+through the
+`CF-Access-Client-Id` and `CF-Access-Client-Secret` headers.
+
+Worker-level Access runs before every connecta route. Consequently:
+
+- `/health`, operator pages, downstream OAuth callbacks, connector-owned
+  routes, and `/mcp` all require Access unless a more-specific hostname/path
+  policy says otherwise;
+- a static connecta bearer and a `cta_…` token are not standalone edge
+  credentials, because Cloudflare rejects them before connecta sees them; and
+- a connector that intentionally exposes a public webhook needs a
+  more-specific Access application and bypass policy. Do not bypass connecta's
+  OAuth discovery paths when Managed OAuth is enabled.
+
+The [Worker example](../examples/worker/) carries the complete deployment shape
+and the [upgrade guide](./upgrading.md#0200--0211) gives the reversible Clerk
+migration.
 
 ## Clerk configuration is checked at construction
 
@@ -17,7 +81,7 @@ request instead of a base64 stack on every route.
 
 ## Operator-issued access tokens
 
-Set `accessTokens: {}` to let eligible Clerk operators create named Bearer
+Set `accessTokens: {}` to let eligible interactive operators create named Bearer
 tokens at `/tokens`:
 
 ```ts
@@ -41,7 +105,7 @@ Revoked records remain as metadata tombstones so historical calls keep their
 friendly attribution.
 
 Access tokens authenticate MCP clients; they are never operator credentials.
-Creation, rename, and revocation require the same eligible Clerk identity and
+Creation, rename, and revocation require the same eligible human identity and
 same-origin mutation boundary as connector credentials. `maxActive` defaults
 to 100 and can be set from 1 through 1,000.
 
@@ -51,7 +115,7 @@ effect globally without a convergence window.
 
 Operator credential mutation is a separate, narrower boundary. The
 `/credentials` shell contains no secret data before authentication, and the
-mutation API requires same-origin requests from an admitted Clerk user. An MCP
+mutation API requires same-origin requests from an admitted operator. An MCP
 bearer is never treated as an operator credential, even when it can call every
 connector.
 
@@ -59,10 +123,10 @@ This split is visible in recovery:
 
 - a bearer-authenticated agent may receive `recovery: "operator_config"` and
   pass its `operatorUrl` to a human;
-- a Clerk-authenticated operator opens that URL, signs in, and updates the
+- an interactive operator opens that URL, signs in, and updates the
   credential; and
 - a bearer-only deployment still returns the handoff honestly, but mutation
-  remains unavailable until Clerk operator auth is configured.
+  remains unavailable until interactive operator auth is configured.
 
 See [meta-tools](./meta-tools.md#authorization-recovery) for the stable recovery
 envelope and [storage and credentials](./storage-and-credentials.md) for vault