@zackbart/connecta 0.20.0 → 0.21.0

package/documentation/operations.md

@@ -45,6 +45,10 @@ one.
 npx @zackbart/connecta init my-deployment
 cd my-deployment && npm install && npm start
 CONNECTA_TOKEN=… npx connecta doctor --url http://localhost:8787
+
+# A Worker protected by Cloudflare Access
+CF_ACCESS_CLIENT_ID=… CF_ACCESS_CLIENT_SECRET=… \
+  npx connecta doctor --url https://connecta.example.workers.dev
 ```
 
 `init` copies the template, pins the generated deployment to the CLI package's
@@ -59,12 +63,17 @@ on the way out: `QuickJS` on the Node template, `DynamicWorkerExecutor` on the
 Worker example, and `code executed` when an executor identifies as nothing —
 a checker that asserts a sandbox it never saw is worse than one that says it
 does not know ([#368](https://github.com/zackbart/connecta/issues/368)). It
-refuses to send a bearer token over remote plaintext HTTP, and it
+refuses to send authentication credentials over remote plaintext HTTP, and it
 *reports* catalog drift without failing on it — an unclassified downstream tool
 already fails closed onto `call_destructive_tool`, so drift is a maintainer's
 next task rather than a broken deployment
 ([#343](https://github.com/zackbart/connecta/issues/343)).
 
+For an Access-protected Worker, doctor sends the service-token pair to both
+`/health` and `/mcp`; Access authenticates those requests before connecta runs.
+`CONNECTA_TOKEN` remains the Node and legacy Worker path, and may be supplied
+alongside the Access pair during rollback testing. A partial pair is refused.
+
 ### Configuration
 
 Structural seams stay top-level; tuning is grouped by subsystem. Every group is
@@ -74,7 +83,7 @@ optional.
 | --- | --- | --- |
 | `connectors` | — (required) | the connector set ([connectors](./connectors.md)) |
 | `executor` | — (required) | the sandbox `execute_code` runs in ([code mode](./code-mode.md#what-an-executor-must-implement)) |
-| `auth?` | none ⇒ open (dev only) | one `InboundAuth` or an array; bearer providers are checked before Clerk ([inbound auth](./auth.md)) |
+| `auth?` | none ⇒ open (dev only) | one `InboundAuth` or an array; bearer providers are checked before interactive providers ([inbound auth](./auth.md)) |
 | `storage?` | `memoryStorage()` | the one state seam for catalogs, result paging, credentials, and access tokens ([storage](./storage-and-credentials.md)) |
 | `publicUrl?` | per-request origin | public base URL; an HTTPS value also redirects inbound HTTP |
 | `logger?` | `console`, prefixed `[connecta]` | `{ debug, info, warn, error }` |
@@ -83,7 +92,7 @@ optional.
 | `deploymentInfo?` | unset | arbitrary metadata exposed by `/health` |
 | `activity?` | unset | `{ store, readGate?, deploymentId? }` — payload-free activity storage, an optional operator-read gate, and a stable event label |
 | `credentials.encryptionKey?` | unset | base64 32-byte AES key for the connector vault. Without it, connectors declaring `credential` warn and their slots stay unmanageable |
-| `accessTokens?` | unset | `{ maxActive? }` (default 100) for operator-issued MCP bearer tokens. Requires a Clerk provider, or construction throws ([access tokens](./auth.md#operator-issued-access-tokens)) |
+| `accessTokens?` | unset | `{ maxActive? }` (default 100) for operator-issued MCP bearer tokens. Requires an interactive operator provider, or construction throws ([access tokens](./auth.md#operator-issued-access-tokens)) |
 | `discovery.concurrency?` | 4 | connector catalogs/status probes in flight at once |
 | `discovery.catalogTtlSeconds?` | 300 | fresh TTL for cached tool lists |
 | `discovery.persistCatalog?` | true | persist serializable catalogs as a manifest plus revision-addressed chunks |
@@ -214,7 +223,7 @@ in.
 
 | Suite | Covers |
 | --- | --- |
-| `access-tokens.test.ts` | the `AccessTokenManager` — a one-time secret created, authenticated, renamed, and revoked, bounded names and active count, enumerable storage required, a deployment with no Clerk operator refused — and the Clerk-only routes, down to historical activity still resolving a revoked token's name |
+| `access-tokens.test.ts` | the `AccessTokenManager` — a one-time secret created, authenticated, renamed, and revoked, bounded names and active count, enumerable storage required, a deployment with no interactive operator refused — and the operator-only routes, down to historical activity still resolving a revoked token's name |
 | `activity.test.ts` | payload-free delivery: a rejected async write attaches to `waitUntil` instead of throwing, approved destructive calls record under their real entry point, result-size friction records without retaining the result, and a hallucinated connector id or invented identity is clamped so the event still cannot carry a payload |
 | `api-connector.test.ts` | `api()` — kind, description, tool defs, dispatch, default args, unknown tools, handler throws, argument validation, and the construction contract |
 | `bearer.test.ts` | constant-time bearer compare, case-insensitive scheme, 401 challenges, and the retired audience options refusing rather than silently unbinding |
@@ -223,6 +232,7 @@ in.
 | `catalog-drift.test.ts` | `vettedCatalog()`, `detectCatalogDrift()`, and `withVettedCatalog()`; drift on the registry surface and on `/health`; the connector seam projected rather than echoed; and the drift types being public |
 | `catalog.test.ts` | lexical ranking and the compact schema renderer — `const`, `allOf` beside siblings, `$ref`, the depth limit, per-schema caching, and 2020-12 keyword compatibility |
 | `clerk.test.ts` | protected-resource metadata, the browser sign-in config, OAuth and session tokens, cached best-effort activity labels with their caps, the hand-applied `azp` rejection, and the `allowedDomains` allowlist including every lookalike that must not be repaired into a match |
+| `cloudflare-access-auth.test.ts` | trusted `ctx.access` human and service identities, absent/error fail-closed behavior, service-token MCP admission without operator mutation, human same-origin mutation, and the Clerk-to-ambient shell switch |
 | `cloudflare-provider.test.ts` | `cloudflare()` construction, tool surface, request building, projections, typed failures, and credential test |
 | `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and `connecta.ui` findable before connector search |
 | `codemode-compat.test.ts` | the `Executor` seam staying structurally compatible with `@cloudflare/codemode`'s `DynamicWorkerExecutor`, enforced by `tsc` |
@@ -244,7 +254,7 @@ in.
 | `mixpanel-provider.test.ts` | the Mixpanel proxy, its conditional-input guide and complete reviewed schema-digest manifest |
 | `notion-provider.test.ts` | Notion's deliberate tool surface, including declined expanded page inputs, request construction, lean projections, both pagination conventions, error mapping, and writes |
 | `operator-boundary.test.ts` | the operator row of the decisions table, after every mutation route: authentication material managed without moving a declared structure, and the one honest exception — a credential write making a remote catalog appear, which is discovery arriving, not an operator editing the deployment |
-| `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, `gate()`, the generation fence, and the request path |
+| `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, ambient Access requests without a browser-readable token, `gate()`, the generation fence, and the request path |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
 | `provider-registry.test.ts` | all six maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
 | `registry.test.ts` | construction and id validation, startup warnings, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
@@ -272,13 +282,13 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | --- | --- | --- |
 | `deployment-shapes.test.ts` | the Worker as the only example with a loader-only sandbox, one Node template that is also its own container, the same source running locally and in the container, the Node template's pinned esbuild install-script approval, the full operator surface in both, a template that cannot start on its own `.env.example`, a Worker README naming every optional peer its entrypoint imports, and the initializer's `.gitignore` staying in step | walks the template and example trees with Node filesystem APIs |
 | `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, repository URLs resolved back to the checkout, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
-| `doctor-cli.test.ts` | `connecta doctor`'s executor line end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, and a hostile name is bounded and stripped before it reaches a terminal | spawns the CLI against a Node HTTP deployment over real sockets |
+| `doctor-cli.test.ts` | `connecta doctor`'s executor line and credentials end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, a hostile name is bounded, and a complete Cloudflare Access service-token pair is accepted while a partial pair is refused | spawns the CLI against a Node HTTP deployment over real sockets |
 | `drift-check.test.ts` | the maintainer drift checker — hosted-provider credential framing, recorded touched endpoints, a quiet revision bump, clear failures for an unavailable spec/manifest/credential, `$ref` traversal, and one well-formed row per endpoint | spawns the Node checker against filesystem fixtures |
 | `file-storage.test.ts` | `fileStorage()` across instances, logical TTL plus physical pruning without clobbering a newer value, and corrupt-file quarantine | exercises the Node filesystem storage adapter |
 | `guest-api-contract-quickjs.test.ts` | the shared guest-contract cases on the real QuickJS executor, including identical caught failure codes and inline describe recovery, its exact absent globals, and blocked runtime imports | runs the contract cases on the Node QuickJS executor |
 | `node.test.ts` | the `listen()` adapter propagating an HTTP client disconnect through the Web `Request` and the MCP handler into a program's connector call, releasing both admission permits | exercises the Node HTTP adapter over real TCP sockets |
 | `packed-links.test.ts` | the packed-link gate itself — shipped targets and repository URLs accepted, relative links into unshipped paths and directories rejected with the citation to write instead, reference definitions seen, fenced examples ignored, the changelog exempt | spawns the Node packed-link gate against filesystem fixtures |
-| `package-surface.test.ts` | the published boundary — built output shipped, the `exports` map carrying exactly the documented subpaths plus `./package.json`, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, every provider independently importable, and the Cloudflare provider free of bare specifiers | walks the package tree with Node filesystem APIs |
+| `package-surface.test.ts` | the published boundary — built output shipped, the `exports` map carrying exactly the documented subpaths plus `./package.json`, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, dependency-free Cloudflare Access behind its Worker subpath, every provider independently importable, and the Cloudflare API provider free of bare specifiers | walks the package tree with Node filesystem APIs |
 | `purity.test.ts` | the import-graph guardrail ([architecture](./architecture.md#import-graph-purity)) — the core stays Workers-clean | walks the source import graph with Node filesystem APIs |
 | `quickjs-child-entry.test.ts` | a missing QuickJS child entry failing before `fork()`, with the expected path and the bundler-externalization constraint | mocks Node child-process and filesystem APIs |
 | `quickjs-child-stderr.test.ts` | abnormal child exits retaining only an 8 KiB stderr tail, included in the parent-side diagnostic | mocks Node child-process streams |
@@ -319,10 +329,15 @@ confinement does too.
 - **A connector with no `verifyState` refuses every callback.** That is the
   designed behavior, not a bug: handing an unverified code to `finishAuth` is
   the vulnerability. The startup warning names the connector.
-- **401 loops from a client that cannot discover auth.** The client must reach
+- **401 loops from a Clerk client that cannot discover auth.** The client must reach
   the open `/.well-known/oauth-protected-resource` (and the `/mcp` variant);
   confirm CORS and the Clerk keys, and that DCR is enabled on the Clerk
   instance.
+- **An Access-protected MCP client receives redirects or loops.** Enable Managed
+  OAuth on the Access application and use an RFC 8707-capable client. Access,
+  not connecta, must answer the unauthenticated challenge and `/.well-known/`
+  metadata. Do not bypass those routes. For unattended automation, use an
+  Access Service Auth policy and service-token headers instead.
 - **No sessions and no server push, by design.** The transport is stateless.
   Scope resolves per request, which is also where the MCP spec has arrived.
 - **A tool that should be callable from a program is not.** Only tools

package/documentation/operator-ui.md

@@ -39,10 +39,25 @@ their walkthrough, which is the honest version of the same page count.
 | `src/operator-ui/browser.css` | One stylesheet, inlined into the shell. |
 | `src/operator-ui/generated.ts` | The build output: the bundle and the stylesheet as two exported strings. |
 
-The server renders a mount point, not a page. Branding, the Clerk loader, and
-every operator-configured URL stay in `src/ui.ts`, where they are gated before
-they can become an attribute; the bundle renders everything that has a state.
-Two roots share one store: `#operatorNav` and `#operatorContent`.
+The server renders a mount point, not a page. Branding, the optional Clerk
+loader, and every operator-configured URL stay in `src/ui.ts`, where they are
+gated before they can become an attribute; the bundle renders everything that
+has a state. Two roots share one store: `#operatorNav` and `#operatorContent`.
+
+Cloudflare Access is ambient browser auth. When the current Worker invocation
+has `ctx.access`, the shell selects the `cloudflare-access` UI mode, emits no
+Clerk loader, and sends no browser-readable token. Same-origin fetch includes
+the HttpOnly `CF_Authorization` cookie, Access admits it at the edge, and the
+server reads the resulting runtime identity. Sign out navigates to
+`/cdn-cgi/access/logout`. Mutations still require an exact same-origin
+`Origin`; an ambient cookie does not weaken the CSRF boundary.
+
+This runtime selection is the Clerk migration seam. A deployment may contain
+both providers: before Worker-level Access is attached, the data-free shell
+selects Clerk; after Access supplies `ctx.access`, it selects ambient auth. That
+is not two same-hostname gates running in parallel. Access is upstream and a
+request it rejects never reaches Clerk. Keeping Clerk in the array preserves a
+code-level rollback after Access is detached.
 
 The Clerk loader is intentionally blocking. The inline operator bundle calls
 `boot()` as soon as the parser reaches the end of the body, so a deferred Clerk
@@ -58,7 +73,8 @@ the same ordering.
   credential, token, and activity data arrives only through the authenticated
   `/ui/*` APIs, and the shell is identical whether or not a caller is signed in.
 - **One store, one identity.** `store.ts` is the only file that touches `fetch`,
-  `localStorage`, or Clerk. Every request carries the current session's token,
+  `localStorage`, Clerk, or the ambient Access mode. Every token-bearing request carries the current session's token,
+  while Access requests deliberately carry none,
   and every response is dropped unless the identity that asked for it is still
   the one on screen. `resetIdentity` replaces all identity-scoped state at once
   and bumps a generation that work already in flight compares itself against.

package/documentation/upgrading.md

@@ -57,7 +57,7 @@ exist so far:
 | --- | --- | --- |
 | **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
 | **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
-| **B** | 0.16.0 – 0.20.0 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+| **B** | 0.16.0 – 0.21.0 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -106,7 +106,7 @@ know what to preserve, once to know what to re-verify at the end.
 ### Bump the pin and install
 
 ```sh
-npm pkg set dependencies.@zackbart/connecta=0.20.0
+npm pkg set dependencies.@zackbart/connecta=0.21.0
 npm install
 ```
 
@@ -130,7 +130,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.20.0 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.21.0 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -186,7 +186,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.20.0 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.21.0 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -207,6 +207,78 @@ first, so cross them bottom-up: start at the oldest one still above this
 deployment's pin and work back up the page, because each boundary assumes the
 older ones are already done.
 
+### 0.20.0 → 0.21.0
+
+This is additive for Node and existing Clerk deployments. The new Worker path
+uses Cloudflare Access identity directly and removes Clerk only after the edge
+cutover has been verified. An agent can perform every repository edit; a human
+must attach Access, choose its policy, create service credentials, and enable
+Managed OAuth in the Cloudflare dashboard.
+
+For a Worker currently using Clerk, keep rollback live through the cutover:
+
+1. Bump and install 0.21.0. Add the new provider **before** the existing Clerk
+   provider, but remove nothing:
+
+   ```ts
+   import { cloudflareAccessAuth } from
+     "@zackbart/connecta/auth/cloudflare-access";
+   import { clerkAuth } from "@zackbart/connecta/auth/clerk";
+
+   auth: [
+     cloudflareAccessAuth(),
+     // Keep the deployment's existing options and secrets unchanged.
+     clerkAuth({ /* existing configuration */ }),
+   ],
+   ```
+
+   Before Access is attached, the new provider fails closed and the operator
+   shell selects Clerk. Deploy this state and run doctor with the existing
+   `CONNECTA_TOKEN`. This separates the package/code change from the edge
+   change and proves the old path still works.
+
+2. In Cloudflare, attach Access to the Worker itself, apply the intended human
+   policy, and enable Managed OAuth. Through the API this is an Access
+   application destination of `{ "type": "worker", "worker_id": "<script
+   tag>" }`, not a hostname application for the `workers.dev` URL: the latter
+   gates traffic but does not provide `ctx.access`. Create an Access service
+   token and a **Service Auth** policy for doctor and fully unattended clients.
+   Do not create a bypass for `/.well-known/*`; Managed OAuth owns that
+   discovery surface.
+
+3. Reconnect interactive MCP clients to `<PUBLIC_URL>/mcp`. Their old Clerk
+   OAuth tokens are not Cloudflare credentials, so each client performs one new
+   browser authorization. An agent can edit client configuration and start the
+   flow; the user still completes the identity-provider prompt. Move CI, cron,
+   and server-to-server callers from connecta bearers to the two Access service
+   headers. The cutover warning is literal: once Access is attached, a static
+   bearer or `cta_…` token by itself is stopped at the edge before connecta can
+   inspect it.
+
+4. Verify the edge path:
+
+   ```sh
+   CF_ACCESS_CLIENT_ID=… CF_ACCESS_CLIENT_SECRET=… \
+     npx connecta doctor --url https://connecta.example.workers.dev
+   ```
+
+   Open `/` as a human and exercise any enabled credential, token, and OAuth
+   controls. A service token may pass doctor and MCP but must receive 403 from
+   operator mutations.
+
+5. After an observation window, remove `clerkAuth`, its import,
+   `@clerk/backend`, and the Clerk variables/secrets. Until then they are inert
+   behind Access but preserve rollback. Rollback order matters: detach Access
+   first, then the untouched Clerk sessions and connecta bearers reach the
+   Worker again. Reverting code first cannot help a request the edge still
+   blocks. There is no storage migration and no token-format conversion.
+
+If the Worker exposes an intentionally public connector route, create a
+more-specific hostname/path Access application with a Bypass policy for that
+route only. `/health`, downstream OAuth callbacks, operator shells, and MCP are
+private under the canonical whole-Worker shape; doctor knows how to authenticate
+its health request.
+
 ### 0.19.0 → 0.20.0
 
 Three intake paths become deliberately strict. None changes storage, the two

package/ethos.md

@@ -1,9 +1,7 @@
 # connecta — ethos
 
 What connecta is, what it refuses to be, and the invariants every change must
-preserve. Deliberately terse: when a change contradicts a line here, either the
-change is wrong or this file needs amending — in that order, and amending it is
-a design decision, not a drive-by edit.
+preserve. A contradiction needs a design decision, not a drive-by edit.
 
 ## What this is
 
@@ -78,6 +76,7 @@ CHANGELOG, not here.
 | MRTR / `input_required` passthrough | gated | relayable statelessly; no host or downstream emits it yet ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | needs refresh-churn evidence ([#206](https://github.com/zackbart/connecta/issues/206)) |
 | Downstream MCP Apps template passthrough | gated | needs a downstream that ships one ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Worker Access inbound auth | provisional | Managed OAuth and Clerk migration need production evidence ([#506](https://github.com/zackbart/connecta/issues/506)) |
 | Program UI tool calls | removed | the read bridge added a second contract without improving agent data retrieval; views are display-only again ([#287](https://github.com/zackbart/connecta/issues/287), [#484](https://github.com/zackbart/connecta/issues/484)) |
 
 ## Invariants

package/examples/worker/README.md

@@ -1,9 +1,9 @@
 # connecta — Cloudflare Worker example
 
 A deployable Worker that aggregates a downstream remote MCP and an in-code HTTP
-API connector, guarded by Clerk OAuth *and* a static bearer token, with state in
-a KV namespace. Its required Worker Loader binding backs the seven-tool surface
-and requires the Workers Paid plan.
+API connector, guarded by Cloudflare Access, with state in a KV namespace. Its
+required Worker Loader binding backs the seven-tool surface and requires the
+Workers Paid plan.
 
 This is also the **starting template for a deployment**: a real deployment
 should be its own repository that pins an exact `@zackbart/connecta` version and
@@ -37,18 +37,27 @@ npm install                                    # from the package root
 wrangler kv namespace create CONNECTA_KV       # paste the id into wrangler.jsonc
 
 cd examples/worker
-wrangler secret put SUPPORT_TOKEN                # one headless client
-wrangler secret put EXEC_TOKEN                   # another headless client
-wrangler secret put CLERK_SECRET_KEY
 wrangler secret put DOWNSTREAM_TOKEN
 wrangler secret put CREDENTIAL_ENCRYPTION_KEY   # base64 32-byte AES key
 wrangler deploy
 ```
 
-`PUBLIC_URL` and `CLERK_PUBLISHABLE_KEY` are plain vars in `wrangler.jsonc`.
-Enable Dynamic Client Registration on the Clerk instance (OAuth Applications →
-DCR) so Claude/Cursor can self-register — full walkthrough in
-[setting up Clerk](../../documentation/auth.md).
+`PUBLIC_URL` is a plain var in `wrangler.jsonc`. After the first deploy, attach
+Cloudflare Access to the Worker itself (the API destination type is `worker`,
+not a hostname application) and choose the account, email-domain, or
+advanced Zero Trust policy that owns admission. Enable **Managed OAuth** on
+that Access application for interactive MCP clients. Access then serves OAuth
+discovery and turns the client's opaque token into the trusted `ctx.access`
+identity connecta reads. A cron job or CI client uses an Access service token
+instead.
+
+Cloudflare's [Worker Access guide](https://developers.cloudflare.com/workers/configuration/cloudflare-access/)
+owns the dashboard/API steps; its [Managed OAuth guide](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/managed-oauth/)
+owns client registration, redirect allowlists, and token lifetimes.
+
+The checked-in `access.dev` block gives `wrangler dev` a local operator
+identity. Remove the block to test the missing-Access refusal. It has no effect
+on a deployed Worker's production identity.
 
 ### Copied into its own repository
 
@@ -57,24 +66,22 @@ dependency this file imports. A copy with its own `package.json` installs three
 things, because two of them are not part of connecta and never install with it:
 
 ```sh
-npm install @zackbart/connecta @cloudflare/codemode @clerk/backend
+npm install @zackbart/connecta @cloudflare/codemode
 ```
 
-Both are optional peers of `@zackbart/connecta` — declared in its manifest,
-never installed with it, and each carrying the range this release supports.
-`@cloudflare/codemode` is the executor behind `execute_code`, published as
+`@cloudflare/codemode` is the optional peer behind `execute_code`, declared in
+connecta's manifest but never installed with it, and published as
 `^0.4.4 || ^0.5.0`: install a version inside that and npm stays quiet, install
 one outside and npm says so at install time instead of leaving a Worker to
 discover the skew in production ([#376](https://github.com/zackbart/connecta/issues/376)).
 
-`@clerk/backend` is the peer behind `@zackbart/connecta/auth/clerk`, which
-`src/index.ts` imports at the top level, so wrangler must resolve it at
-build time. Miss it and the build stops at
-`Could not resolve "@clerk/backend"`, which is a missing peer rather than a
-broken example. Drop `clerkAuth` from `auth` if this deployment has no operator
-sign-in, and the peer goes with it — but read
-[the operator surface](#the-operator-surface) first, because a deployment
-without it can never write a credential or issue an access token.
+`cloudflareAccessAuth()` has no dependency of its own. A deployment keeping
+Clerk for rollback still installs `@clerk/backend` and keeps the commented
+provider shape in `src/index.ts` until the migration is verified.
+
+```sh
+npm install @clerk/backend   # migration window only
+```
 
 Then point an MCP client at `<PUBLIC_URL>/mcp`, and open `<PUBLIC_URL>/` for
 Connections. Credentials is at `/credentials`, named MCP access tokens are at
@@ -87,11 +94,11 @@ the next section for what turns each one on.
 This example ships the whole operator feature set. Three quarters of it is on
 as deployed; the fourth needs a database, so it is commented in place.
 
-**Operator sign-in** is the `clerkAuth` entry in `src/index.ts`, alongside two
-static bearers. The split is deliberate: a bearer is a client key that may call
-tools and read connector status, while writing a credential or issuing an
-access token requires an interactive Clerk identity. Narrow who that can be
-with `allowedDomains`, or with a `gate` for anything a domain cannot express.
+**Operator sign-in** is the `cloudflareAccessAuth()` entry in `src/index.ts`.
+Access authenticates before the Worker runs. A human Access identity can use
+MCP and operator pages; a service-token identity can use MCP but cannot write a
+credential, run downstream OAuth, or issue a connecta token. Narrow admission
+in the Access policy rather than repeating email domains or groups in code.
 
 **The credential vault** is `credentials: { encryptionKey: … }`, backed by the
 same KV namespace as everything else and encrypted with the
@@ -116,12 +123,18 @@ shape on `echo` is exactly it) or use a provider connector such as `notion()`,
 which declares its own, and Credentials appears for a signed-in operator on the
 next load.
 
-**Access tokens** are `accessTokens: {}`. A signed-in operator mints named,
+**Access tokens** are `accessTokens: {}`. A signed-in human operator mints named,
 revocable Bearer tokens at `/tokens` for header-capable clients that will not do
 OAuth. Secrets are shown once and only their hashes enter KV; a lost token is
 reissued, never recovered. Note the KV caveat above — revocation is visible
 everywhere only as fast as the namespace converges.
 
+Worker-level Access still runs before these tokens. A `cta_…` token therefore
+does not reach connecta by itself; retain the feature as a rollback path or for
+a caller that already supplies separate Access service-token headers. Normal
+interactive MCP clients should use Managed OAuth, and unattended clients should
+use Access service tokens.
+
 **Activity** is the commented block in `src/index.ts` and the commented
 `d1_databases` binding in `wrangler.jsonc`; the section below creates the
 database and applies the schema.
@@ -134,10 +147,17 @@ never the connector set, the tool catalog, or its annotations.
 this on: connector count, executor, seven tools. The executor it names is this
 one — `DynamicWorkerExecutor executed`, not the Node template's QuickJS, which
 is what doctor used to claim everywhere
-([#368](https://github.com/zackbart/connecta/issues/368)). It carries a bearer, and a
-bearer learns the model-facing surface rather than the deployment's
-configuration topology. Confirm the operator surface the way an operator will:
-sign in at `<PUBLIC_URL>/` and check that Tokens is live. Credentials joins it
+([#368](https://github.com/zackbart/connecta/issues/368)). Against Access it
+carries `CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET`, and the service
+identity learns the model-facing surface rather than deployment topology:
+
+```sh
+CF_ACCESS_CLIENT_ID=… CF_ACCESS_CLIENT_SECRET=… \
+  npx connecta doctor --url "$PUBLIC_URL"
+```
+
+Confirm the operator surface the way an operator will: sign in at
+`<PUBLIC_URL>/` and check that Tokens is live. Credentials joins it
 once a connector declares a `credential` slot, and Activity once the D1 wiring
 below is on — the nav shows a page when the deployment can actually serve it,
 so a missing page is the honest report that its half is still off.

package/examples/worker/src/index.ts

@@ -2,9 +2,10 @@
  * connecta on Cloudflare Workers.
  *
  * One MCP endpoint aggregating a downstream remote MCP and an HTTP API, guarded
- * by Clerk OAuth *and* a static bearer token, with OAuth/cache state in a KV
- * namespace. The required Worker Loader binding in wrangler.jsonc backs the
- * seven-tool surface.
+ * by Cloudflare Access, with OAuth/cache state in a KV namespace. Access
+ * authenticates the request before this Worker runs and supplies the trusted
+ * identity through ctx.access. The required Worker Loader binding in
+ * wrangler.jsonc backs the seven-tool surface.
  *
  * The operator surface is wired here except for activity history, which needs
  * a database this example does not create for you: sign-in, the credential
@@ -15,19 +16,16 @@
  * installed `@zackbart/connecta` package):
  *   1. `npm install` in the connecta package root (../../ from here) so the
  *      package import and wrangler resolve. A copy in its own repository
- *      installs `@zackbart/connecta @cloudflare/codemode @clerk/backend`
- *      instead — the last two are not part of connecta, and the Clerk import
- *      below is an optional peer wrangler resolves at build time.
+ *      installs `@zackbart/connecta @cloudflare/codemode` instead. Codemode is
+ *      an optional peer; a migrating deployment also keeps `@clerk/backend`
+ *      until it removes the commented rollback provider below.
  *   2. Create a KV namespace and put its id in wrangler.jsonc under `kv_namespaces`.
  *   3. Set secrets:
- *        wrangler secret put SUPPORT_TOKEN
- *        wrangler secret put EXEC_TOKEN
- *        wrangler secret put CLERK_SECRET_KEY
  *        wrangler secret put DOWNSTREAM_TOKEN
  *        wrangler secret put CREDENTIAL_ENCRYPTION_KEY
- *      and CLERK_PUBLISHABLE_KEY + PUBLIC_URL as plain vars in wrangler.jsonc.
- *   4. Enable Dynamic Client Registration in the Clerk dashboard
- *        (OAuth Applications -> DCR toggle) so Claude/Cursor can self-register.
+ *      and PUBLIC_URL as a plain var in wrangler.jsonc.
+ *   4. Attach Cloudflare Access to this Worker. Enable Managed OAuth on the
+ *      Access application for interactive MCP clients.
  *   5. Use the Workers Paid plan required by the `worker_loaders` binding.
  *   6. `wrangler deploy` from this folder (examples/worker), where wrangler.jsonc
  *      lives. Point your MCP client at `<PUBLIC_URL>/mcp`.
@@ -35,23 +33,21 @@
 import { DynamicWorkerExecutor } from "@cloudflare/codemode";
 import {
   api,
-  bearerToken,
   createConnecta,
   remoteMcp,
 } from "@zackbart/connecta";
-import { clerkAuth } from "@zackbart/connecta/auth/clerk";
+import { cloudflareAccessAuth } from "@zackbart/connecta/auth/cloudflare-access";
+// Rollback for a deployment migrating from Clerk:
+// import { clerkAuth } from "@zackbart/connecta/auth/clerk";
 import { cloudflareKvStorage } from "./cloudflare-kv.js";
 // Activity history, off by default because it needs a D1 database.
 // import { d1ActivityStore } from "./d1-activity.js";
 
 interface Env {
   CONNECTA_KV: KVNamespace;
-  /** Bearer token for one headless client in this deployment's audience. */
-  SUPPORT_TOKEN: string;
-  /** Bearer token for another headless client in the same audience. */
-  EXEC_TOKEN: string;
-  CLERK_PUBLISHABLE_KEY: string;
-  CLERK_SECRET_KEY: string;
+  // Keep these during a Clerk migration until Access has been verified:
+  // CLERK_PUBLISHABLE_KEY: string;
+  // CLERK_SECRET_KEY: string;
   /**
    * Base64 32-byte AES key encrypting operator-managed credentials in KV.
    * Unset means no vault: /credentials stays read-only and connecta says so at
@@ -75,22 +71,19 @@ function build(env: Env) {
     storage: cloudflareKvStorage(env.CONNECTA_KV),
     executor: new DynamicWorkerExecutor({ loader: env.LOADER }),
     auth: [
-      // Multiple credentials may identify callers in one deployment. Every
-      // admitted caller reaches this deployment's deliberate connector set.
-      bearerToken(env.SUPPORT_TOKEN, {
-        subjectId: "support-team",
-      }),
-      bearerToken(env.EXEC_TOKEN, {
-        subjectId: "exec-team",
-      }),
-      // The operator signs in with Clerk. Restrict who may sign in with
-      // `allowedDomains` (or a `gate`, for anything a domain cannot express).
-      clerkAuth({
-        publishableKey: env.CLERK_PUBLISHABLE_KEY,
-        secretKey: env.CLERK_SECRET_KEY,
-        publicUrl: env.PUBLIC_URL,
-        // allowedDomains: ["acme.com"],
-      }),
+      // Access owns admission policy. A human identity may use MCP and the
+      // operator pages; a service token may use MCP but cannot mutate operator
+      // state. Neither path asks connecta to parse a JWT.
+      cloudflareAccessAuth(),
+      // Leave the previous Clerk provider below this entry during migration.
+      // It is a rollback path until Worker-level Access is detached; Access
+      // itself decides whether a request reaches this array.
+      // clerkAuth({
+      //   publishableKey: env.CLERK_PUBLISHABLE_KEY,
+      //   secretKey: env.CLERK_SECRET_KEY,
+      //   publicUrl: env.PUBLIC_URL,
+      //   allowedDomains: ["acme.com"],
+      // }),
     ],
     // Connectors that declare a `credential` slot become editable at
     // /credentials, encrypted with this key before anything reaches KV. A
@@ -105,8 +98,9 @@ function build(env: Env) {
     // `echo`, or use a provider connector like `notion()`, which declares its
     // own) and the page appears on the next load.
     credentials: { encryptionKey: env.CREDENTIAL_ENCRYPTION_KEY },
-    // Eligible Clerk operators can create named, revocable MCP Bearer tokens
-    // at /tokens. Secrets are shown once; only their hashes enter KV.
+    // Eligible human operators can create named, revocable MCP Bearer tokens
+    // at /tokens. Under Worker-level Access those tokens are a rollback tool,
+    // not standalone edge credentials: Access still runs before connecta.
     accessTokens: {},
     // Payload-free activity at /activity, off until a database exists to hold
     // it. Uncomment the `d1_databases` binding in wrangler.jsonc, apply the

package/examples/worker/wrangler.jsonc

@@ -6,12 +6,20 @@
   "compatibility_flags": ["nodejs_compat"],
   "observability": { "enabled": true },
 
-  // Plain vars. Secrets (SUPPORT_TOKEN, EXEC_TOKEN, CLERK_SECRET_KEY,
-  // CREDENTIAL_ENCRYPTION_KEY, DOWNSTREAM_TOKEN) are set with
+  // Plain vars. Secrets (CREDENTIAL_ENCRYPTION_KEY, DOWNSTREAM_TOKEN) are set with
   // `wrangler secret put <NAME>`, not here.
   "vars": {
-    "PUBLIC_URL": "https://connecta.example.workers.dev",
-    "CLERK_PUBLISHABLE_KEY": "pk_test_replace-me"
+    "PUBLIC_URL": "https://connecta.example.workers.dev"
+  },
+
+  // Local-only Access identity. Remove this block to exercise the
+  // unauthenticated path in `wrangler dev`; production identity comes from the
+  // Worker-level Access application, not from this file.
+  "access": {
+    "dev": {
+      "aud": "connecta-local",
+      "identity": { "email": "operator@example.com" }
+    }
   },
 
   // Create with `wrangler kv namespace create CONNECTA_KV` and paste the id.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
@@ -63,6 +63,10 @@
       "types": "./dist/auth/clerk.d.ts",
       "import": "./dist/auth/clerk.js"
     },
+    "./auth/cloudflare-access": {
+      "types": "./dist/auth/cloudflare-access.d.ts",
+      "import": "./dist/auth/cloudflare-access.js"
+    },
     "./providers/cloudflare": {
       "types": "./dist/providers/cloudflare.d.ts",
       "import": "./dist/providers/cloudflare.js"

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.20.0",
+    "@zackbart/connecta": "0.21.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {