@zackbart/connecta 0.21.1 → 0.22.0

package/examples/worker/README.md

@@ -46,15 +46,56 @@ wrangler deploy
 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.
+that Access application for interactive MCP clients, turn on Dynamic Client
+Registration, and add these three entries under **Allowed redirect URIs**:
+
+```text
+https://claude.ai/api/mcp/auth_callback
+https://chatgpt.com/connector_platform_oauth_redirect
+https://chatgpt.com/connector/oauth/*
+```
+
+The Claude entry is its fixed hosted-MCP callback. ChatGPT may register either
+its stable callback or a callback-id URL, so both forms are intentional. These
+are Managed OAuth application settings, represented by
+`oauth_configuration.dynamic_client_registration.allowed_uris` in the Access
+API; they do not belong in the Access Allow policy that decides who may sign
+in. Leaving the list empty is a footgun: discovery still works, then Dynamic
+Client Registration fails because the callback is not allowed. If either
+client presents a new redirect URI, copy that exact value from the registration
+attempt and add the narrowest matching entry rather than allowing its entire
+origin.
+
+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.
+
+Through the API, the relevant part of the application is:
+
+```json
+{
+  "oauth_configuration": {
+    "enabled": true,
+    "dynamic_client_registration": {
+      "enabled": true,
+      "allowed_uris": [
+        "https://claude.ai/api/mcp/auth_callback",
+        "https://chatgpt.com/connector_platform_oauth_redirect",
+        "https://chatgpt.com/connector/oauth/*"
+      ]
+    }
+  }
+}
+```
 
 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.
 
+[`AGENTS.md`](./AGENTS.md) repeats the callback invariant for coding agents
+working in a copied deployment. Do not remove the entries there when changing
+the Access policy or application.
+
 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.
@@ -75,13 +116,9 @@ connecta's manifest but never installed with it, and published as
 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)).
 
-`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
-```
+`cloudflareAccessAuth()` has no dependency of its own. This Worker example has
+no Clerk import, secret, package, or fallback provider. Docker deployments keep
+the Clerk path in the Node template.
 
 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
@@ -96,9 +133,21 @@ as deployed; the fourth needs a database, so it is commented in place.
 
 **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.
+MCP and human-management pages; a service-token identity can use MCP but cannot
+write a credential, run downstream OAuth, or issue a connecta token. Cloudflare
+still owns the outer application admission policy, but Connecta's user roster,
+connector access, and deployment roles stay in `src/index.ts`.
+
+**Several users** need no second auth system or Connecta account dashboard.
+Uncomment the `identity` block in `src/index.ts` to derive connector ids and
+deployment-operator membership from the Access principal. Connectors remain
+visible to everyone and every human remains an operator when that block is
+absent. A signed-in human may edit auth for every connector their view includes.
+Add `authScope: "personal"` when each user should connect a different downstream
+account; leave it shared only when any user with connector access may rotate the
+deployment-wide grant. Static headers stay shared because their value lives in
+deployment configuration. See [inbound identity](../../documentation/auth.md#principals-visibility-and-operators)
+for the resolver contract.
 
 **The credential vault** is `credentials: { encryptionKey: … }`, backed by the
 same KV namespace as everything else and encrypted with the

package/examples/worker/src/index.ts

@@ -17,15 +17,17 @@
  *   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` instead. Codemode is
- *      an optional peer; a migrating deployment also keeps `@clerk/backend`
- *      until it removes the commented rollback provider below.
+ *      an optional peer.
  *   2. Create a KV namespace and put its id in wrangler.jsonc under `kv_namespaces`.
  *   3. Set secrets:
  *        wrangler secret put DOWNSTREAM_TOKEN
  *        wrangler secret put CREDENTIAL_ENCRYPTION_KEY
  *      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.
+ *   4. Attach Cloudflare Access to this Worker. Enable Managed OAuth and
+ *      Dynamic Client Registration. Its Allowed redirect URIs must include
+ *      Claude's https://claude.ai/api/mcp/auth_callback plus ChatGPT's
+ *      https://chatgpt.com/connector_platform_oauth_redirect and
+ *      https://chatgpt.com/connector/oauth/* forms (see ../AGENTS.md).
  *   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`.
@@ -37,17 +39,12 @@ import {
   remoteMcp,
 } from "@zackbart/connecta";
 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;
-  // 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,20 +72,24 @@ function build(env: Env) {
       // 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
-    // saved replacement takes effect on the next call — no redeploy, and no
-    // liveness probe: credentials fail at use.
+    // Optional code-owned roster. Access proves the identity; connecta derives
+    // connector visibility and deployment-operator status from the stable id
+    // it supplies. A signed-in human may manage auth for every connector this
+    // view includes. Omit the block to keep every connector visible and every
+    // human a deployment operator.
+    // identity: {
+    //   connectorAccess: ({ principal }) =>
+    //     principal?.id === "ACCESS_USER_UUID"
+    //       ? ["notion", "echo"]
+    //       : ["echo"],
+    //   operatorAccess: ({ id }) => id === "ACCESS_USER_UUID",
+    // },
+    // Connectors that declare a `credential` slot become editable by every
+    // signed-in human who can see that connector at /credentials, encrypted
+    // with this key before anything reaches KV. A saved replacement takes
+    // effect on the next call — no redeploy, and no liveness probe:
+    // credentials fail at use.
     //
     // The key is the vault, not the page: /credentials is a list of connector
     // slots, so it stays hidden until a connector declares one. Neither
@@ -123,6 +124,9 @@ function build(env: Env) {
           //   type: "credential",
           //   credential: { label: "Notion internal integration token" },
         },
+        // Use `authScope: "personal"` with OAuth or credential auth when each
+        // Access user connects their own downstream account. Literal headers
+        // are deployment-owned and cannot be personal.
       }),
       api("echo", {
         description: "Echo — text transforms",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.21.1",
+  "version": "0.22.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.",

package/templates/node/README.md

@@ -68,6 +68,13 @@ import, the two `process.env.CLERK_*` reads, and the `clerkAuth({ … })` entry
 Applications → DCR) if MCP clients should sign in through it too, and set
 `PUBLIC_URL` first — Clerk redirects back to it.
 
+Clerk remains the identity provider when several people share this Docker
+deployment. Uncomment the `identity` block in `src/index.ts` to give each Clerk
+principal a config-derived connector view and to choose operators. Add
+`authScope: "personal"` to a connector when each person should supply their own
+credential or finish their own downstream OAuth flow. Without those options,
+all connectors and auth stay shared exactly as before.
+
 **2. Credential vault.** Uncomment `credentials` and set
 `CONNECTA_CREDENTIAL_KEY` to a base64 32-byte AES key:
 

package/templates/node/package.json

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

package/templates/node/src/index.ts

@@ -42,10 +42,10 @@ const stateFile = process.env.CONNECTA_STATE_FILE || "./.connecta-state.json";
 const publicUrl = process.env.PUBLIC_URL || `http://localhost:${port}`;
 
 // Operator sign-in. A bearer token is a client key: it may call tools and read
-// connector status, but only a Clerk-authenticated operator may write a
-// credential or issue an access token. Without this block the operator pages
-// still render — an operator pastes the bearer to read them — and Credentials
-// and Tokens stay read-only.
+// connector status, but only a Clerk-authenticated human may write a visible
+// connector's credential, and only an operator may issue an access token.
+// Without this block the operator pages still render — an operator pastes the
+// bearer to read them — and Credentials and Tokens stay read-only.
 // const clerkPublishableKey = process.env.CLERK_PUBLISHABLE_KEY;
 // const clerkSecretKey = process.env.CLERK_SECRET_KEY;
 // if (!clerkPublishableKey || !clerkSecretKey) {
@@ -67,6 +67,15 @@ const connecta = createConnecta({
     //   // allowedDomains: ["acme.com"],
     // }),
   ],
+  // Optional member/operator split for Clerk-backed Docker deployments.
+  // Connector access is derived from the authenticated identity and cannot be
+  // selected by an MCP argument. Omit this block for the legacy all-visible,
+  // all-interactive-users-are-operators behavior.
+  // identity: {
+  //   connectorAccess: ({ principal }) =>
+  //     principal?.id === "user_admin" ? "all" : ["time"],
+  //   operatorAccess: ({ id }) => id === "user_admin",
+  // },
   publicUrl,
   // Required: model-written programs run in a bounded QuickJS child.
   executor: quickJsExecutor(),