@zackbart/connecta 0.19.0 → 0.21.0

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,7 +76,8 @@ 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)) |
-| View-initiated mutation calls from program UI | gated | a click is not approval ([#287](https://github.com/zackbart/connecta/issues/287)) |
+| 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.19.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.19.0",
+    "@zackbart/connecta": "0.21.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {