@zackbart/connecta 0.20.0 → 0.21.0

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to this package are documented here.
 
+## 0.21.0 — 2026-08-28
+
+Cloudflare Access becomes the canonical interactive-auth path for Worker
+deployments. It authenticates both MCP clients and human operators before the
+Worker runs, while connecta consumes only the trusted runtime identity. Clerk
+is unchanged and remains supported: existing deployments can add Access,
+verify the edge cutover, and remove Clerk later, with no storage migration or
+token conversion. Node deployments can ignore this release beyond the version
+pin.
+
+### Added
+
+- **Direct Worker Access auth.** `cloudflareAccessAuth()` ships from
+  `@zackbart/connecta/auth/cloudflare-access` with no dependency and no JWT
+  verifier. Human `ctx.access` identities may use MCP and operator routes;
+  service-token identities may use MCP but cannot mutate operator state. Since
+  Cloudflare exposes no user identity for a service token, its Access
+  application audience is the shared activity subject. The same suite runs
+  under Node and workerd (#506).
+- **Ambient operator sessions.** The operator shell selects Cloudflare Access
+  when the current invocation carries it, sends no browser-readable token, and
+  signs out through Cloudflare. A co-configured Clerk provider remains the
+  shell before Access is attached and the rollback path after it is detached
+  (#506).
+- **Access-aware doctor.** `connecta doctor` accepts
+  `CF_ACCESS_CLIENT_ID`/`CF_ACCESS_CLIENT_SECRET` and sends the pair to health
+  and MCP requests. A partial pair fails before network access (#506).
+
+### Changed
+
+- **Cold reads stay in code mode.** One known canonical address still uses
+  `call_tool`, while an unknown-address read now starts with one
+  `execute_code` program and keeps discovery results off the model-facing
+  route. The current-version benchmark is reset to four deterministic
+  whole-agent cases covering both routes, exact provider semantics, private
+  pagination, forwarding bytes, tokens, and latency.
+- **Worker deployment path.** The shipped Worker example uses Access and
+  Managed OAuth through a Worker-level `worker` destination, carries a local
+  `access.dev` identity, and documents service tokens for unattended callers.
+  A hostname-only Access application gates the URL but does not supply
+  `ctx.access`. The Clerk shape stays beside the provider as the reversible
+  migration seam. Static connecta and operator-issued bearers remain supported
+  by core but are not standalone credentials through a whole-Worker Access
+  gate (#506).
+- **Operator capability is vendor-neutral.** Inbound auth providers now declare
+  interactive-operator capability explicitly, and runtime context reaches
+  their authorization hook as an optional third argument. Existing custom
+  providers with the two-argument hook remain source-compatible (#506).
+
 ## 0.20.0 — 2026-08-26
 
 This release removes the two side languages that had grown around the seven

package/README.md

@@ -78,7 +78,9 @@ Fifty issues in, one small object out. Your context window notices.
 
 There is also an operator surface, off until you turn it on: sign-in, an
 encrypted credential vault with rotation, revocable per-client tokens, and a
-payload-free activity log.
+payload-free activity log. Worker deployments can use Cloudflare Access for
+both MCP and operator identity; Node deployments and existing Workers can use
+Clerk.
 
 Connecta is not a platform, a marketplace, a policy engine, or a multi-tenant
 service. Those are decisions, and the [ethos](./ethos.md) records each one

package/bin/connecta.mjs

@@ -27,7 +27,8 @@ function shellCd(path) {
 function usage() {
   console.log(`Usage:
   connecta init [directory]
-  CONNECTA_TOKEN=<bearer> connecta doctor [--url http://localhost:8787]`);
+  CONNECTA_TOKEN=<bearer> connecta doctor [--url http://localhost:8787]
+  CF_ACCESS_CLIENT_ID=<id> CF_ACCESS_CLIENT_SECRET=<secret> connecta doctor --url https://worker.example`);
 }
 
 async function init() {
@@ -169,19 +170,35 @@ async function doctor() {
     !loopbackHosts.has(parsedUrl.hostname)
   ) {
     throw new Error(
-      "Refusing to send a bearer token over remote plaintext HTTP. Use HTTPS.",
+      "Refusing to send authentication credentials over remote plaintext HTTP. Use HTTPS.",
     );
   }
   const baseUrl = requestedUrl.replace(/\/+$/, "");
   const token = process.env.CONNECTA_TOKEN;
-  if (!token) {
+  const accessClientId = process.env.CF_ACCESS_CLIENT_ID;
+  const accessClientSecret = process.env.CF_ACCESS_CLIENT_SECRET;
+  if (Boolean(accessClientId) !== Boolean(accessClientSecret)) {
     throw new Error(
-      "Set CONNECTA_TOKEN so doctor can inspect the MCP surface.",
+      "Set both CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET.",
     );
   }
+  if (!token && !accessClientId) {
+    throw new Error(
+      "Set CONNECTA_TOKEN or a CF_ACCESS_CLIENT_ID/CF_ACCESS_CLIENT_SECRET pair so doctor can inspect the MCP surface.",
+    );
+  }
+  const authHeaders = {
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    ...(accessClientId && accessClientSecret
+      ? {
+          "CF-Access-Client-Id": accessClientId,
+          "CF-Access-Client-Secret": accessClientSecret,
+        }
+      : {}),
+  };
 
   const health = await jsonResponse(
-    await doctorFetch(`${baseUrl}/health`),
+    await doctorFetch(`${baseUrl}/health`, { headers: authHeaders }),
   );
   if (health.status !== "ok") {
     throw new Error(`Unexpected health status: ${String(health.status)}`);
@@ -206,7 +223,7 @@ async function doctor() {
       await doctorFetch(`${baseUrl}/mcp`, {
       method: "POST",
       headers: {
-        Authorization: `Bearer ${token}`,
+        ...authHeaders,
         "Content-Type": "application/json",
         Accept: "application/json, text/event-stream",
       },

package/dist/auth/bearer.d.ts

@@ -5,7 +5,7 @@ export interface BearerTokenOptions {
 }
 /**
  * Static bearer-token inbound auth. Constant-time compares the Bearer token
- * against `secret`. Checked BEFORE the Clerk gate in the server; a mismatch
- * falls through so a co-configured Clerk provider can still admit the request.
+ * against `secret`. Checked before interactive providers in the server; a
+ * mismatch falls through so another configured provider can admit the request.
  */
 export declare function bearerToken(secret: string, options?: BearerTokenOptions): InboundAuth;

package/dist/auth/bearer.js

@@ -16,8 +16,8 @@ function timingSafeEqual(a, b) {
 }
 /**
  * Static bearer-token inbound auth. Constant-time compares the Bearer token
- * against `secret`. Checked BEFORE the Clerk gate in the server; a mismatch
- * falls through so a co-configured Clerk provider can still admit the request.
+ * against `secret`. Checked before interactive providers in the server; a
+ * mismatch falls through so another configured provider can admit the request.
  */
 export function bearerToken(secret, options = {}) {
     assertNoRetiredToolkitOptions("bearerToken", options);

package/dist/auth/clerk.js

@@ -366,6 +366,7 @@ export function clerkAuth(opts) {
     };
     return {
         kind: "clerk",
+        interactiveOperator: true,
         activityActorNamespace: frontendApiUrl,
         activityActorLabel: resolveActivityLabel,
         uiAuth: {

package/dist/auth/cloudflare-access.d.ts

@@ -0,0 +1,8 @@
+import type { InboundAuth } from "../types.js";
+/**
+ * Trust the identity Cloudflare Access attached to this direct Worker
+ * invocation. Access has already validated the browser session, Managed OAuth
+ * token, or service-token headers before the Worker runs; this adapter does
+ * not accept or parse a caller-supplied JWT.
+ */
+export declare function cloudflareAccessAuth(): InboundAuth;

package/dist/auth/cloudflare-access.js

@@ -0,0 +1,66 @@
+function identityString(identity, field) {
+    const value = identity[field];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function unauthorized() {
+    return {
+        ok: false,
+        response: Response.json({ error: "Cloudflare Access authentication required" }, { status: 401 }),
+    };
+}
+/**
+ * Trust the identity Cloudflare Access attached to this direct Worker
+ * invocation. Access has already validated the browser session, Managed OAuth
+ * token, or service-token headers before the Worker runs; this adapter does
+ * not accept or parse a caller-supplied JWT.
+ */
+export function cloudflareAccessAuth() {
+    return {
+        kind: "cloudflare-access",
+        interactiveOperator: true,
+        activityActorNamespace: "cloudflare-access",
+        uiAuth: { kind: "cloudflare-access" },
+        async authorize(_request, _baseUrl, runtimeContext) {
+            const access = runtimeContext?.access;
+            if (!access)
+                return unauthorized();
+            let identity;
+            try {
+                identity = await access.getIdentity();
+            }
+            catch {
+                return unauthorized();
+            }
+            if (!identity) {
+                // Access service-token policies authenticate the request and attach
+                // ctx.access, but getIdentity() is a user-identity API and returns
+                // undefined. Cloudflare strips the service-token headers before the
+                // Worker, so the Access application audience is the only trusted,
+                // stable service attribution available without parsing a JWT.
+                return { ok: true, subjectId: access.aud };
+            }
+            const userId = identityString(identity, "user_uuid") ??
+                identityString(identity, "email");
+            const commonName = identityString(identity, "common_name");
+            const serviceTokenId = identityString(identity, "service_token_id");
+            if (identity.service_token_status === true ||
+                serviceTokenId ||
+                (!userId && commonName)) {
+                const subjectId = serviceTokenId ?? commonName;
+                return subjectId
+                    ? { ok: true, subjectId }
+                    : {
+                        ok: false,
+                        response: Response.json({ error: "Cloudflare Access service identity required" }, { status: 403 }),
+                    };
+            }
+            if (!userId) {
+                return {
+                    ok: false,
+                    response: Response.json({ error: "Cloudflare Access user identity required" }, { status: 403 }),
+                };
+            }
+            return { ok: true, userId, subjectId: userId };
+        },
+    };
+}

package/dist/execute.js

@@ -6,7 +6,7 @@ import { guardExecuteResultValue, MAX_EXECUTE_LOG_CHARS, truncateExecuteText, }
 import { ExecutorAdmissionError, ExecutorExecutionError, isAdmittingExecutor, } from "./executor-admission.js";
 import { boundedEchoText, classifyCallError, msg } from "./errors.js";
 import { InvocationFailure, InvocationService, } from "./invocation.js";
-import { hasConnectorGuides } from "./skills.js";
+import { connectorGuide, connectorGuideRequired, connectorSkillName, hasConnectorGuides, } from "./skills.js";
 /** Keep one model-written program from amplifying into an unbounded fan-out. */
 const EXECUTE_MAX_HOST_CALLS = 20;
 export const EXECUTE_MAX_BATCH_CALLS = 10;
@@ -856,9 +856,15 @@ function connectorInventory(connectors) {
         return `${prefix}none.`;
     const entries = connectors.map((connector) => {
         const shortcut = sanitizeIdentifier(connector.id);
-        return shortcut === connector.id
+        const address = shortcut === connector.id
             ? connector.id
             : `${connector.id} (shortcut ${shortcut})`;
+        if (!connectorGuide(connector))
+            return address;
+        const requirement = connectorGuideRequired(connector)
+            ? "required guide"
+            : "guide";
+        return `${address} (${requirement} ${connectorSkillName(connector.id)})`;
     });
     const shown = [];
     for (let index = 0; index < entries.length; index++) {
@@ -879,18 +885,18 @@ function connectorInventory(connectors) {
         return `${prefix}${shown.join(", ")}.`;
     return `${prefix}${shown.join(", ")}${shown.length > 0 ? "; " : ""}+${omitted} more.`;
 }
-const executeDescription = (emitBudgets, connectorGuides, connectors) => `Choose the route before discovery. Exactly one unknown-address read uses top-level search_tools then call_tool. execute_code is the primary surface for everything wider: make exactly one execute_code call that searches, selects, calls, and reduces. A discovery-only program wastes its round trip: finish here, don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
+const executeDescription = (emitBudgets, connectorGuides, connectors) => `Choose the route before discovery. A known address uses call_tool. Unknown-address and wider read-only work use exactly one execute_code call that discovers, calls, and returns the answer. Finish in that program; don't return catalog matches for a later call. Only readOnlyHint: true tools are available. Limits: ${EXECUTE_MAX_HOST_CALLS} host calls per run, ${EXECUTE_MAX_BATCH_CALLS} per batch, ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second host deadline.
 
 ${connectorInventory(connectors)}
 
-Write one plain-JavaScript async arrow function. Use only:
+Fetch required guides named above before executing. Write one plain-JavaScript async arrow function. Use only:
 - <connectorId>.<toolName>(args) for a sanitized shortcut, or connecta.call(address, args) for a canonical address.
-- connecta.search(args), connecta.describe(args), and connecta.batch(calls) for discovery and independent read-only calls.
+- connecta.search(args) returns { tools }; connecta.describe(args) returns { tools }; use entry key lists. connecta.batch(calls) accepts canonical connector addresses only.
 - connecta.emit(block) — { type: "text", text } or { type: "image" | "audio", data (base64), mimeType }. Success-only; ${emitBudgets.maxBlocks} blocks/${emitBudgets.maxBytes} bytes; invalid/over-budget throws.
 - connecta.ui(html) for one display-only, success-only view; return the same summary the HTML renders.
 - console.log(...) — captured.
 
-Programs have no portable ambient capabilities. Return JSON and reduce large results before they truncate. Fetch skills({ name: "usage" }) once for selection rules, exact result shapes, repair, examples, guide handling${connectorGuides ? ", connector-guide rules" : ""}, and runtime differences.`;
+No portable ambient capabilities. Return JSON; reduce large results before truncation. Build arguments from required input keys and schemas, never descriptions or output keys. Fetch skills({ name: "usage" }) only when this is insufficient or repair is needed; it has full rules, examples${connectorGuides ? ", guide handling" : ""}, and runtime details.`;
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(server, registry, ctx) {
     // Resolved once so the description and the collector cannot disagree about

package/dist/index.d.ts

@@ -132,7 +132,7 @@ export interface ConnectaConfig {
     credentials?: ConnectaCredentialsConfig;
     /**
      * Named, revocable Bearer tokens for MCP clients. Creation and mutation
-     * require an eligible Clerk operator; token secrets are returned once.
+     * require an eligible interactive operator; token secrets are returned once.
      */
     accessTokens?: ConnectaAccessTokensConfig;
     /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
@@ -192,6 +192,6 @@ export { CONNECTA_VERSION } from "./version.js";
 export type { Registry } from "./registry.js";
 export type { RemoteMcpOptions, RemoteMcpAuth, RemoteMcpRedirectPolicy, } from "./connectors/remote-mcp.js";
 export type { ApiOptions, ApiTool } from "./connectors/api.js";
-export type { CatalogDriftCounts, CatalogDriftReport, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectaBranding, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, UiAuthConfig, AuthResult, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
+export type { CatalogDriftCounts, CatalogDriftReport, Connector, ConnectorCallAdmissionInput, ConnectorCallAdmissionPolicy, ConnectorCallAdmissionRule, ConnectorRollingWindowBudget, ConnectaBranding, ConnectorCredentialAccess, ConnectorCredentialConfig, ConnectorCredentialFieldConfig, ConnectorCredentialValues, ConnectorContext, ConnectorUsageGuide, ConnectorStatus, CredentialTestResult, AdmittingExecutor, AdmissionSnapshot, ExecuteResult, Executor, ExecutorLease, ExecutorProvider, InboundAuth, InboundAuthRuntimeContext, UiAuthConfig, AuthResult, JsonSchema, KVStorage, Logger, ToolDef, ToolAnnotations, } from "./types.js";
 export type { ActivityActor, ActivityCallSource, ActivityOutcome, ActivityPage, ActivityReadActor, ActivityReadEvent, ActivityReader, ActivityReadGate, ActivityReadPage, ActivitySink, ActivityStore, AgentFriction, CatalogDriftActivityEvent, ToolCallActivityEvent, } from "./activity.js";
 export { InvalidActivityCursorError } from "./activity.js";

package/dist/index.js

@@ -262,8 +262,8 @@ export function createConnecta(config) {
         ? new AccessTokenManager(storage, config.accessTokens)
         : undefined;
     if (accessTokens &&
-        !configuredAuth.some((provider) => provider.uiAuth?.kind === "clerk")) {
-        throw new Error("accessTokens requires a Clerk auth provider: only an eligible Clerk " +
+        !configuredAuth.some((provider) => provider.interactiveOperator)) {
+        throw new Error("accessTokens requires an interactive operator auth provider: only an eligible " +
             "operator may create, rename, or revoke deployment access tokens");
     }
     const serverInfo = {

package/dist/meta-tools.js

@@ -515,12 +515,12 @@ export function createMetaTools(registry, baseUrl, opts = {}) {
         },
     };
 }
-const SEARCH_DESC = `Use top-level search for one unknown-address read before call_tool, or for approval-required work before call_destructive_tool. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds direct or program calls; "approvalRequired" finds the fail-closed complement. These filters grant no authority. For multiple, dependent, or reduced read-only calls, use one execute_code program instead. Empty query browses.`;
-const CALL_DESC = 'Call one tool explicitly annotated readOnlyHint: true. Use execute_code for multiple, dependent, or reduced read-only calls. Unannotated or write-capable tools fail closed to call_destructive_tool. A truncated result carries a get_result action.';
+const SEARCH_DESC = `Use top-level search for catalog inspection or approval-required work before call_destructive_tool. Unknown-address read-only work belongs in one execute_code program that searches, calls, and returns the answer. Use 2–4 action/object terms and includeSchemas="compact"; the default limit is ${DEFAULT_SEARCH_LIMIT}. Set connector when known. safety="readOnly" finds direct or program calls; "approvalRequired" finds the fail-closed complement. These filters grant no authority. Empty query browses.`;
+const CALL_DESC = 'Call one known-address tool explicitly annotated readOnlyHint: true. Use execute_code for unknown-address, multiple, dependent, or reduced read-only work. Unannotated or write-capable tools fail closed to call_destructive_tool. A truncated result carries a get_result action.';
 const CALL_DESTRUCTIVE_DESC = "Call any tool not explicitly annotated readOnlyHint: true. Include a short reason for the human reviewer after checking the schema and consequences. The reason grants no authority and is not sent downstream.";
 const GET_RESULT_DESC = "Page a truncated direct-call result by id and byte offset. A program result is never paged; reduce it inside execute_code. Returns text, offset, nextOffset when more remains, and totalBytes.";
 const AUTHORIZE_DESC = "Use after auth_required. Returns an OAuth or operator-credential handoff, or reports required deployment configuration. force=true restarts OAuth only; this tool never accepts credentials.";
-const SKILLS_DESC = 'List or fetch on-demand guidance. Fetch usage once per task for program syntax, selection, repair, examples, and runtime details.';
+const SKILLS_DESC = 'List or fetch on-demand guidance. Fetch usage only when the always-loaded instructions are insufficient or a program needs repair.';
 /**
  * Sentences appended to a meta-tool description only when this connection
  * actually has connector guides. Tool descriptions are always-loaded context,