@zackbart/connecta 0.21.1 → 0.22.0

package/documentation/auth.md

@@ -6,6 +6,63 @@ Access identities on Workers, or a mixture. Static bearers are checked first;
 the remaining providers keep configuration order. The first successful
 identity owns the activity actor for that request.
 
+## Principals, visibility, and operators
+
+Connecta distinguishes three identities. The actor is the exact caller written
+to activity. The subject is any stable authenticated caller and owns transient
+results such as `get_result` pages. The principal is the human owner of personal
+connector auth. An interactive Clerk or Access user supplies all three. A
+Cloudflare service identity has an actor and subject but no principal. A
+connecta access token has its own actor and subject and inherits the principal
+that created it, so agents using that token reach the creator's personal
+connections without becoming operators.
+
+`identity.connectorAccess` derives the connector ids a caller may discover and
+invoke. The resolver receives authenticated identity data, never request input,
+and returns `"all"` or a list of ids declared in `connectors`. An unknown id or
+a thrown resolver fails the request closed.
+
+`identity.connectorAccess` is also the credential-management boundary. A
+signed-in human may save, test, disconnect, and authorize every visible
+connector: personal auth changes only that principal's partition, while shared
+auth changes the deployment-wide grant for everyone who can see the connector.
+Use `authScope: "personal"` when one member must not rotate another member's
+connection.
+
+`identity.operatorAccess` separately reserves deployment-wide administration:
+access-token creation and global activity history. Omit the resolver to
+preserve the prior rule that every interactive human is an operator. When it is
+configured, activity history is operator-only because its global event stream
+contains other principals' connector names and actors.
+
+```ts
+createConnecta({
+  auth: cloudflareAccessAuth(),
+  identity: {
+    connectorAccess: ({ principal }) =>
+      principal?.id === "user_a"
+        ? ["shared_docs", "personal_linear"]
+        : ["shared_docs"],
+    operatorAccess: ({ id }) => id === "user_a",
+  },
+  connectors: [
+    remoteMcp("shared_docs", { url: "https://example.com/mcp" }),
+    remoteMcp("personal_linear", {
+      url: "https://mcp.linear.app/mcp",
+      authScope: "personal",
+      auth: { type: "oauth" },
+    }),
+  ],
+  executor,
+});
+```
+
+Identity namespaces matter. Built-in Clerk and Access providers supply one.
+A custom interactive provider must set `activityActorNamespace` before its
+users can own personal auth. It may still use the legacy operator behavior
+without one, but connecta will not merge unnamespaced users into personal
+storage.
+
 ## Cloudflare Access on Workers
 
 [`cloudflareAccessAuth()`](https://developers.cloudflare.com/workers/configuration/cloudflare-access/)
@@ -35,7 +92,8 @@ also means it is deliberately not a Node or `cloudflared` origin adapter, and
 it does not survive a Service Binding hop: those shapes need their own explicit
 trust boundary.
 
-A human identity gets MCP and operator access. A Cloudflare service-token
+A human identity gets MCP and personal-connection access. It gets operator
+access unless `identity.operatorAccess` says otherwise. A Cloudflare service-token
 identity gets MCP access and a stable activity subject, but no `userId`, so it
 cannot write credentials, run downstream OAuth mutations, or issue connecta
 tokens. Access policy decides who reaches the Worker; connecta does not mirror
@@ -48,7 +106,27 @@ the Worker. Enable [**Managed OAuth**](https://developers.cloudflare.com/cloudfl
 on that Worker-level application for interactive MCP clients.
 Cloudflare then owns the unauthenticated challenge and `/.well-known/`
 metadata, issues opaque RFC 8707 tokens, and resolves them into the same trusted
-Worker identity. Do not add a bypass for the discovery routes. A fully
+Worker identity. Managed OAuth allows no hosted client callback by default, so
+enable Dynamic Client Registration and add all three values to **Allowed
+redirect URIs**:
+
+```text
+https://claude.ai/api/mcp/auth_callback
+https://chatgpt.com/connector_platform_oauth_redirect
+https://chatgpt.com/connector/oauth/*
+```
+
+Cloudflare exposes that list as
+`oauth_configuration.dynamic_client_registration.allowed_uris`. It belongs to
+the Access application's Managed OAuth settings, not the Access policy that
+selects admitted identities. Claude uses the fixed first value. ChatGPT may use
+its stable callback or a callback-id path covered by the third value. If a
+client registers a different redirect, add that exact URI or the narrowest path
+wildcard that covers it; do not allow the client's whole origin. Without these
+entries discovery succeeds and client registration fails later, which makes a
+missing allowlist look like a broken MCP server.
+
+Do not add a bypass for the discovery routes. A fully
 automated client instead uses a [Cloudflare Access service token](https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/)
 through the
 `CF-Access-Client-Id` and `CF-Access-Client-Secret` headers.
@@ -65,7 +143,7 @@ Worker-level Access runs before every connecta route. Consequently:
   OAuth discovery paths when Managed OAuth is enabled.
 
 The [Worker example](../examples/worker/) carries the complete deployment shape
-and the [upgrade guide](./upgrading.md#0200--0211) gives the reversible Clerk
+and the [upgrade guide](./upgrading.md#0200--0212) gives the reversible Clerk
 migration.
 
 ## Clerk configuration is checked at construction
@@ -102,7 +180,9 @@ secure.
 Each token has an immutable ID. Activity records store that ID and resolve its
 current friendly name only while an authorized operator reads activity.
 Revoked records remain as metadata tombstones so historical calls keep their
-friendly attribution.
+friendly attribution. New tokens also retain the creating principal. Their MCP
+requests use that principal's connector visibility and personal auth while the
+token itself remains the activity actor and result owner.
 
 Access tokens authenticate MCP clients; they are never operator credentials.
 Creation, rename, and revocation require the same eligible human identity and
@@ -113,20 +193,20 @@ Issuance and revocation inherit the consistency guarantees of the configured
 storage adapter. Use strongly consistent storage when either change must take
 effect globally without a convergence window.
 
-Operator credential mutation is a separate, narrower boundary. The
+Human credential mutation is a separate, narrower boundary. The
 `/credentials` shell contains no secret data before authentication, and the
-mutation API requires same-origin requests from an admitted operator. An MCP
-bearer is never treated as an operator credential, even when it can call every
-connector.
+mutation API requires same-origin requests from an admitted interactive human.
+That human may mutate only visible connector slots. An MCP bearer is never
+treated as a browser credential, even when it can call every connector.
 
 This split is visible in recovery:
 
 - a bearer-authenticated agent may receive `recovery: "operator_config"` and
   pass its `operatorUrl` to a human;
-- an interactive operator opens that URL, signs in, and updates the
+- an interactive human with connector access opens that URL, signs in, and updates the
   credential; and
 - a bearer-only deployment still returns the handoff honestly, but mutation
-  remains unavailable until interactive operator auth is configured.
+  remains unavailable until interactive user auth is configured.
 
 See [meta-tools](./meta-tools.md#authorization-recovery) for the stable recovery
 envelope and [storage and credentials](./storage-and-credentials.md) for vault

package/documentation/code-mode.md

@@ -746,7 +746,7 @@ Worker renders arguments with `String()` (so an object logs as
 latter two. Only the three captured everywhere are contract (`R5`); rendering is
 not.
 
-**X5. Leftover authority.** QuickJS blocks imports and has no `fetch`, `process`, timers, `crypto`, or `WebSocket`. A Dynamic Worker has those globals plus a non-contract set of runtime builtins through `import()` and `process.getBuiltinModule()`, including `node:path`, `node:crypto`, `node:net`, `node:tls`, `node:dns`, `node:module`, and `cloudflare:workers`. The upstream set can drift; this list is not an allowlist.
+**X5. Leftover authority.** QuickJS blocks imports and has no `fetch`, `process`, timers, `crypto`, or `WebSocket`. Its Node child starts with an explicitly empty process environment rather than inheriting deployment variables or `NODE_OPTIONS`. A Dynamic Worker has those globals plus a non-contract set of runtime builtins through `import()` and `process.getBuiltinModule()`, including `node:path`, `node:crypto`, `node:net`, `node:tls`, `node:dns`, `node:module`, and `cloudflare:workers`. The upstream set can drift; this list is not an allowlist.
 The supported Worker construction is exactly `new DynamicWorkerExecutor({ loader })`. Do not pass `bindings`, `modules`, or `globalOutbound`: each can grant ambient configuration, code, or egress. Under it, `process.env`, lexical `this.env`, and `cloudflare:workers.env` are empty; `node:fs`, `node:http`, and `node:https` are unavailable through either access route; external `fetch`, `WebSocket`, `node:net`, and `node:tls` fail with workerd's outbound-denial error; DNS lookup ends unresolved; and `fetch("data:...")` resolves locally.
 `P2` is the portable contract. Programs use none of this runtime-only authority, including timers and `crypto`, because the same code fails on QuickJS. The `execute_code` description and served `usage` skill say so before an agent writes code.
 
@@ -785,8 +785,8 @@ The human message is unchanged; a mismatched frame is ordinary untyped prose.
 
 ## Changes from earlier code mode
 
-Six behaviors changed with this contract, matching the changelog's Unreleased
-entry. Programs that ran before still run.
+Six behaviors changed with this contract, matching the 0.10.0 release notes.
+Programs that ran before still run.
 
 - **Caught Connecta failures expose their classification** (`E1`, `X11`). Their human message and thrown semantics stay unchanged; `code`, `retryable`, and `details` are additive.
 
@@ -832,7 +832,7 @@ the upstream `Executor` shape assignable.
 | Clauses | Test |
 | --- | --- |
 | `P1`, `P5` | `test/guest-api-contract.test.ts` (TypeScript syntax), `test/quickjs-executor.test.ts` (`normalizeCode`) |
-| `P2`, `X5` | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.test.ts` (exact absent globals and blocked imports), `test/deployment-shapes.test.ts` (loader-only Worker construction) |
+| `P2`, `X5` | `test/guest-api-contract.test.ts` (Dynamic globals plus loader-only filesystem, HTTP, environment, egress, DNS, and local `data:` boundaries), `test/guest-api-contract-quickjs.test.ts` (exact absent globals and blocked imports), `test/quickjs-child-stderr.test.ts` (empty child-process environment), `test/deployment-shapes.test.ts` (loader-only Worker construction) |
 | `P3`, `X9` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` |
 | `P4` | `test/guest-api-contract.test.ts` (no cross-run leakage), `test/execute.test.ts` (one catalog load per connector per execution) |
 | `A1`, `A2` | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (sanitizing), `test/server.test.ts` (bounded live connector inventory) |

package/documentation/connectors.md

@@ -1,5 +1,18 @@
 # Connectors
 
+Every connector may set `authScope: "shared" | "personal"`. Shared is the
+default and keeps one deployment-wide downstream grant. Personal auth requires
+a stable human principal and partitions connector state, credentials, OAuth,
+catalogs, and observed shapes by that principal. Connector visibility is a
+separate deployment rule under `identity.connectorAccess`; hiding a connector
+does not change who owns its auth. See [shared and personal auth](./storage-and-credentials.md#shared-and-personal-auth).
+
+`authScope` partitions connecta-owned context, not arbitrary variables captured
+by connector code. A custom personal connector must read auth from
+`ctx.credential` or `ctx.storage`; a secret closed over by its handler remains
+shared JavaScript state. `remoteMcp()` rejects the equivalent mistake when
+literal headers are combined with personal scope.
+
 Connectors are the boundary between Connecta's fixed meta-tool surface and
 downstream capabilities. Prefer a prebuilt connection when Connecta maintains
 one for the provider. Use `api()` to define a deliberate HTTP API surface and

package/documentation/meta-tools.md

@@ -307,9 +307,10 @@ credential.
 
 The tool accepts no secret. `force` applies only to OAuth and may discard its
 stored grant before restarting consent. Static credential values are written
-only through the same-origin, Clerk-operator credential route. After OAuth
-consent or an operator update, retry the original operation; a static update is
-read from the vault on the next call and needs no redeploy.
+only through the same-origin interactive-user credential route, and only for a
+connector visible to that user. After OAuth consent or a human update, retry
+the original operation; a static update is read from the vault on the next call
+and needs no redeploy.
 
 ## Routing recovery
 

package/documentation/operations.md

@@ -84,6 +84,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 interactive providers ([inbound auth](./auth.md)) |
+| `identity?` | all connectors; every interactive human is an operator | `{ connectorAccess?, operatorAccess? }` derives the request's connector view and shared-auth authority from its authenticated identity ([principals](./auth.md#principals-visibility-and-operators)) |
 | `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 }` |
@@ -239,7 +240,7 @@ in.
 | `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and unknown own-properties rejected by their complete path before construction does work |
 | `credentials.test.ts` | the pure stored-shape classifier (containment, not equality) and the AES-GCM vault: round-trip, ciphertext bound to its connector id, named field sets, masked metadata, wrong-key rejection, deletion, coexistence with OAuth keys |
 | `d1-activity-example.test.ts` | the Worker example's deployment-owned D1 activity store: actor namespace round-trip, payload-free friction reconstructed from the persisted code, and agreement with the package's friction table |
-| `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and races, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
+| `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and generation races, runtime-local rotating-token refresh coordination across request scopes, refresh failure/retry, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
 | `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, and framing errors |
 | `execute.test.ts` | the code-mode host bridge: identifier sanitization, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
 | `execute-emit.test.ts` | `connecta.emit` (M1–M10) — block validation, budgets, the provider, delivery after the result envelope on success only, and the defaults |
@@ -247,6 +248,7 @@ in.
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
 | `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
 | `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, batch, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
+| `identity-scope.test.ts` | identity-derived connector visibility, personal credential isolation, shared-auth operator control, and personal OAuth callback ownership |
 | `linear-provider.test.ts` | the Linear proxy's construction, guide, plan-aware catalog superset, and current workspace, template, and issue-sharing classifications |
 | `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
 | `meta-tools-search.test.ts` | registry-backed discovery: bounded search with page and address maxima, compact and JSON schemas with constraints, typed describe recovery and suggestions, and structured-result compatibility |
@@ -280,7 +282,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 
 | Suite | Covers | Why Node |
 | --- | --- | --- |
-| `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 |
+| `deployment-shapes.test.ts` | the Worker as the only example with a loader-only sandbox, its agent instructions and setup guide pinning Claude and both ChatGPT Managed OAuth callback forms, 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 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 |
@@ -291,7 +293,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `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 |
+| `quickjs-child-stderr.test.ts` | the QuickJS child-process boundary: an explicitly empty environment despite parent secrets and `NODE_OPTIONS`, plus abnormal exits retaining only an 8 KiB stderr tail in the parent-side diagnostic | mocks Node child-process streams |
 | `quickjs-executor.test.ts` | the child-process sandbox — code normalization, lazy namespace proxies, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection | runs the Node QuickJS child-process executor |
 | `quickjs-log-limits.test.ts` | bounded `console.*` capture — per-entry cut, cumulative character and transport budgets, escape-heavy floods preserving the guest result | runs the Node QuickJS child-process executor |
 | `suite-partition.test.ts` | this partition, including itself: every `*.test.ts` in exactly one list, stale entries and empty reasons refused | walks the test directory to guard the partition |

package/documentation/operator-ui.md

@@ -5,10 +5,10 @@ the authentication material behind it. It is a small Preact app compiled by the
 repository's own esbuild step and inlined into a data-free server shell.
 
 Read [`ethos.md`](../ethos.md) first. The boundary this subsystem lives inside
-is the operator row in its decisions table: **operator routes may manage
-authentication material for capabilities declared in deployment configuration,
-and may not change the connector set, the tool catalog or annotations, requested
-OAuth scopes, admission policy, authorization rules, or caller tool scope.**
+is the human-management invariant: **members may manage authentication material
+for every connector their code-derived view includes, operators may also manage
+deployment tokens and global activity, and neither may change the connector set, tool catalog,
+annotations, requested OAuth scopes, admission policy, or identity rules.**
 `test/operator-boundary.test.ts` proves it after every mutation route.
 
 Both deployment shapes ship the whole feature set behind it, because pages for
@@ -52,6 +52,15 @@ 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.
 
+The shell is shared by members and operators. `/ui/data` uses the same
+identity-scoped registry view as `/mcp`, so it cannot list a connector the
+current caller cannot discover. A member sees credential and OAuth controls for
+every visible connector. Personal actions resolve to that member's principal
+partition; shared actions change the deployment-wide grant. The access-token
+and global activity pages require `identity.operatorAccess`. Existing
+deployments that omit that resolver keep every interactive human as an
+operator.
+
 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

package/documentation/request-admission.md

@@ -49,7 +49,8 @@ which is also why `/health` always has a code-admission shape to report.
 
 The request pool is global FIFO across identities. It is a capacity boundary,
 not tenant fairness: one busy caller can occupy it. Per-tenant fairness needs a
-policy above connecta, and one deployment serves one audience anyway
+policy above connecta, and one deployment still serves one tenant even when
+identity rules give its principals different connector views
 ([`ethos.md`](../ethos.md)), so a global queue is not pretending to supply
 something it does not.
 

package/documentation/storage-and-credentials.md

@@ -6,7 +6,7 @@ token is an independent record rather than one shared, race-prone manifest.
 The built-in memory and file adapters implement it, as does the Cloudflare KV
 example.
 
-Connectors may declare an operator-managed `credential` slot. When
+Connectors may declare a human-managed `credential` slot. When
 `credentials.encryptionKey` is configured, Connecta encrypts values in the
 deployment storage and exposes read-only access only through that connector's
 `ctx.credential`. Values, masked values, call arguments, and raw errors never
@@ -27,13 +27,40 @@ Credential mutation is intentionally narrower than MCP access:
 
 - a static bearer may call tools and receive the operator handoff, but it
   cannot write credentials;
-- only an admitted Clerk user may use the same-origin credential mutation
-  routes; and
+- an admitted interactive human may mutate credentials for every visible
+  connector: their own partition for personal auth, or the deployment-wide
+  value for shared auth; and
 - saving, replacing, testing, or removing a value never returns that value.
 
-The vault is read for each call. Once an operator saves a replacement,
+The vault is read for each call. Once a signed-in human saves a replacement,
 the agent can retry immediately without restarting or redeploying Connecta.
 
+## Shared and personal auth
+
+Connector auth defaults to `authScope: "shared"`. Its credential, OAuth state,
+tokens, catalog cache, and connector storage belong to the deployment. Set
+`authScope: "personal"` when every human principal needs a separate downstream
+account:
+
+```ts
+remoteMcp("linear", {
+  url: "https://mcp.linear.app/mcp",
+  authScope: "personal",
+  auth: { type: "oauth" },
+});
+```
+
+Personal connectors disappear from a request that has no stable human
+principal. For a principal that can see one, connecta partitions connector
+storage, encrypted vault records, catalog caches, OAuth generations, and
+observed result shapes under an opaque SHA-256 identity key. Results used by
+`get_result` are partitioned by the authenticated subject, so one token cannot
+page another token's call even when both tokens belong to the same principal.
+
+Literal `auth: { type: "headers" }` cannot be personal because its secret lives
+in deployment code. `remoteMcp()` refuses that combination at construction.
+Use operator-managed credential auth or OAuth instead.
+
 ## A remote MCP connector's static credential
 
 `remoteMcp()` accepts a third auth shape beside OAuth and literal headers:
@@ -97,6 +124,17 @@ Registration and token envelopes are bound to the validated authorization
 server `issuer`. An unbound pre-0.9 envelope is upgraded in place on its first
 issuer-aware read, preserving the existing grant.
 
+For personal OAuth, the authorization handoff also stores a 15-minute mapping
+from a SHA-256 digest of `state` to the principal partition. The public callback
+uses that mapping before it verifies state or exchanges the code. Neither the
+browser nor a callback parameter can select a principal. The callback deletes
+the mapping before it exchanges the code, so a second callback cannot replay
+the principal handoff in strongly consistent storage. Cloudflare KV deletion
+is eventually consistent, so handoff consumption there is best-effort across
+PoPs; the downstream authorization code remains single-use. If the callback
+request also carries an interactive identity, Connecta refuses it when that
+principal did not start the flow.
+
 If later discovery resolves a different issuer, Connecta does not send the old
 client identifier or tokens to it. The provider publishes a new generation
 epoch, makes every older credential namespace unreadable, cleans up the retired
@@ -107,3 +145,38 @@ the retired grant.
 The OAuth callback verifies the one-shot `state` first, then hands the complete
 query string—including RFC 9207 `iss`—to the SDK transport. One-shot state,
 verifier, and pending URL are cleared only after a successful exchange.
+
+Within one `remoteMcp()` runtime, one request scope owns refresh-token
+redemption for an OAuth generation. Concurrent scopes wait for the owner's
+token save or bounded failure, then either read storage again or receive that
+failure. A scope that had already read the retired refresh token reuses the
+newly stored rotating token locally instead of sending the retired value
+upstream. Force reauthorization retires the old generation's gate, and a
+failed flow releases ownership for a later attempt. The coordinator retains
+only a completion signal and one temporary owner-abort listener until that
+exact flight settles, never the token response or downstream transport. A
+follower may stop waiting when its own request is cancelled without cancelling
+the owner or poisoning the generation for later callers. If the owner's
+credential mutation fails, joined callers receive that same bounded failure
+instead of waking to redeem the unchanged token; a later independent call may
+retry. Non-success and malformed token responses settle current waiters at the
+fetch boundary, before any later authorization callback can itself fail.
+Cancelling the owner aborts its fetch and fails current joiners rather than
+promoting one: once a request reaches the authorization server, repeating its
+old refresh token is not known to be safe. If that cancellation lands while
+the valid response's credential write is already running, a same-generation
+attempt receives `temporarily_unavailable` until the exact write succeeds or
+fails. This mutation marker contains no retained promise; force
+reauthorization removes it when the old generation becomes unreadable.
+An additional opaque success identity lets a request recognize a refresh that
+completed after its issuer-aware token read even when the authorization server
+returned byte-identical credentials. The identity is generation-scoped and is
+discarded with the retired generation. Every authoritative storage-generation
+read also retires coordinator state from other epochs, so an externally
+advanced generation cannot be overwritten in runtime state by late old work.
+
+This guarantee is runtime-local. `KVStorage` has no atomic lock or
+compare-and-set operation, so separate processes or Worker isolates can still
+redeem the same refresh token concurrently. Generation envelopes continue to
+fence their writes, but Connecta does not claim cross-isolate exactly-once
+refresh.

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.21.1 | 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.22.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.21.1
+npm pkg set dependencies.@zackbart/connecta=0.22.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.21.1 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.22.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.21.1 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.22.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,9 +207,25 @@ 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.1
+### 0.21.2 → 0.22.0
 
-0.21.1 adds no deployment migration beyond 0.21.0. The boundary is additive
+Connector and user policy remain config-as-code. If `identity.connectorAccess`
+is configured, every interactive human may now manage the authentication of
+each connector that resolver makes visible. A personal connector changes only
+that principal's partition; a shared connector changes the deployment-wide
+grant. Keep shared connectors out of a member's view, or change them to
+`authScope: "personal"`, when that member must not rotate the shared grant.
+`identity.operatorAccess` continues to govern deployment access tokens and
+global activity.
+
+Paged results also move under the authenticated subject's storage partition.
+Finish any important in-flight `get_result` sequence before upgrading; its old
+result id is not readable from the new partition after deployment. No persisted
+connector catalog or credential migration is required.
+
+### 0.20.0 → 0.21.2
+
+0.21.2 adds no deployment migration beyond 0.21.0. The boundary 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
@@ -218,7 +234,7 @@ Managed OAuth in the Cloudflare dashboard.
 
 For a Worker currently using Clerk, keep rollback live through the cutover:
 
-1. Bump and install 0.21.1. Add the new provider **before** the existing Clerk
+1. Bump and install 0.21.2. Add the new provider **before** the existing Clerk
    provider, but remove nothing:
 
    ```ts
@@ -244,6 +260,21 @@ For a Worker currently using Clerk, keep rollback live through the cutover:
    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.
+   In the application's Managed OAuth settings, enable Dynamic Client
+   Registration and add these three **Allowed redirect URIs**:
+
+   ```text
+   https://claude.ai/api/mcp/auth_callback
+   https://chatgpt.com/connector_platform_oauth_redirect
+   https://chatgpt.com/connector/oauth/*
+   ```
+
+   They map to
+   `oauth_configuration.dynamic_client_registration.allowed_uris` in the
+   Access API, not to the identity policy. The two ChatGPT entries cover its
+   stable and callback-id forms. An empty list fails client registration only
+   after discovery, so do not treat a working `/.well-known/*` response as
+   proof that this step is complete.
    Do not create a bypass for `/.well-known/*`; Managed OAuth owns that
    discovery surface.
 

package/ethos.md

@@ -8,8 +8,8 @@ preserve. A contradiction needs a design decision, not a drive-by edit.
 - **One MCP endpoint, one programmable surface.** Every integration you chose
   sits behind a capability catalog that agents reach by writing JavaScript,
   ringed by a few explicit tools for the boundaries code must not cross.
-- **A deployment is a small config-as-code file.** Changing what agents can
-  reach is an edit and a redeploy. One deployment, one tenant, one audience.
+- **A deployment is config-as-code.** One tenant and connector set; principals
+  receive config-derived views.
 - **Curated when available, open when not.** Prefer a maintained prebuilt
   connection; `remoteMcp()` and `api()` stay first-class for everything else.
   Every path yields the same `Connector` with the same rules.
@@ -30,8 +30,8 @@ preserve. A contradiction needs a design decision, not a drive-by edit.
 - **Not a platform.** No runtime registration, admin-editable capability,
   policy engine, approvals, or pauses.
 - **Not a schema ingester.** No OpenAPI or GraphQL → tools.
-- **Not multi-tenant.** No account model or per-user credential store; scope
-  stays connector-level, and ambiguity stops rather than guesses.
+- **Not multi-tenant.** No accounts, groups, or sessions. Inbound auth owns
+  identity; personal state stays within one tenant.
 - **Not stateful.** No protocol sessions, no server push; scope resolves per
   request.
 - **Not a nanny.** Credentials fail loudly at use; nothing probes one.
@@ -47,7 +47,7 @@ CHANGELOG, not here.
 | Decision | Verdict | Why |
 | --- | --- | --- |
 | OpenAPI / GraphQL ingestion | refused | the disease is a tool nobody chose — a document authored it; hand-written literals, even through a shared factory, are still authorship |
-| Multi-tenancy / account model | refused | one deployment per tenant; deploy again |
+| Multi-tenancy / account model | refused | one deployment per tenant; inbound auth owns identity |
 | Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
 | Runtime connector registration | refused | config-as-code is the security model |
 | Provider registry / marketplace | refused | prebuilt connections are imports; discovery happens in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
@@ -67,7 +67,7 @@ CHANGELOG, not here.
 | Legacy embedded `UIResource` delivery | refused | superseded upstream, rendered by no client we face ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Effect as the core effect system | refused | −4% of the core for +75 KB gzip and a second async paradigm; re-measure at v4 stable ([#470](https://github.com/zackbart/connecta/issues/470)) |
 | Shared bounded queue under both admission controllers | refused | built and measured −17 lines for a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
-| Toolkits (scoped views) | removed | deploy per audience ([#178](https://github.com/zackbart/connecta/issues/178)) |
+| Caller-selected toolkits | removed | only config may derive an identity's connector view ([#178](https://github.com/zackbart/connecta/issues/178)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
 | Per-result lexical query coverage | removed | did not earn its response bytes in a precommitted gate ([#323](https://github.com/zackbart/connecta/issues/323)) |
@@ -91,10 +91,10 @@ Breaking one is a design change wearing a disguise.
 - **A downstream catalog is complete or it is a failure.** A partial catalog is never cached, persisted, or served.
 - **Activity is payload-free by construction.** The event type has nowhere to put arguments, results, code, or raw errors.
 - **An observed shape is never a declaration.** Names and broad types only, labeled, and gone behind any declared schema.
-- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector, rendered by nothing.
+- **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector and, for personal auth, its owning principal; rendered by nothing.
 - **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin.
 - **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath.
-- **Operator routes manage authentication material, never declared capability.** A downstream catalog is discovered, not declared.
+- **Human routes manage auth, never capability.** Signed-in humans manage auth for visible connectors; operators also manage tokens and global activity.
 - **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 
 Connecta began as a radical simplification of

package/examples/worker/AGENTS.md

@@ -0,0 +1,44 @@
+# Working on this Connecta Worker deployment
+
+This repository is deployment configuration, not a copy of Connecta itself.
+
+- Edit `src/index.ts` for connectors, authentication, storage, and public URL.
+- Keep `cloudflareAccessAuth()` as the inbound auth provider. Cloudflare Access
+  authenticates the request before the Worker runs; do not add JWT parsing or a
+  second Worker-side identity gate.
+- Attach Access to the Worker itself, not only its hostname. Enable Managed
+  OAuth and Dynamic Client Registration on that Access application.
+- Managed OAuth's **Allowed redirect URIs** must contain all three entries
+  below. This is application configuration under
+  `oauth_configuration.dynamic_client_registration.allowed_uris`, not an
+  Access Allow policy:
+
+  ```text
+  https://claude.ai/api/mcp/auth_callback
+  https://chatgpt.com/connector_platform_oauth_redirect
+  https://chatgpt.com/connector/oauth/*
+  ```
+
+  The first is Claude's hosted MCP callback. The two ChatGPT entries cover its
+  stable callback and its callback-id form. An empty allowlist lets Access
+  discovery work but makes client registration fail with `redirect_uri` not
+  allowed. If a client presents a different callback, copy that exact URI from
+  its registration attempt and add the narrowest matching entry rather than
+  broadening the allowlist to an entire origin.
+- Keep `new DynamicWorkerExecutor({ loader: env.LOADER })` loader-only. Do not
+  add bindings, modules, or outbound access to generated code.
+- Keep credentials in Worker secrets. Never commit credential values, Access
+  service-token secrets, or `CREDENTIAL_ENCRYPTION_KEY`.
+- Add application logic only inside deliberate `api()` connector handlers.
+  Do not copy or modify Connecta package internals here.
+- Prefer `api()` when the agent must see an exact reviewed capability set;
+  `remoteMcp()` follows the downstream server's evolving tool catalog.
+- Use Access service credentials for `connecta doctor` and unattended clients.
+  A `cta_` token or static Connecta bearer cannot cross the Access edge alone.
+- Run the repository's `npm run check:examples` after configuration changes.
+  After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and
+  complete their browser authorization flows before calling setup complete.
+
+Do not add alternate entrypoints, policy layers, generated connector catalogs,
+or runtime connector registration. Keep the deployment small enough to review
+as configuration.