@zackbart/connecta 0.32.0 → 0.33.0

package/documentation/auth.md

@@ -3,13 +3,14 @@
 ## Task routes
 
 [Agent index](./README.md) distinguishes endpoint operation from deployment
-and package maintenance. This guide owns identity, grants, and downstream
+and package maintenance. This guide owns identity, membership, and downstream
 credential contracts; use [deployment setup](./deploying.md) for runnable steps.
 
 | Task                                                                | Sections                                                                                                                                                                      |
 | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Connect a machine or migrate an old client                          | [Managed tokens](#managed-client-tokens-and-upgrading-from-v023), [static bearer migration](#migrating-static-bearer-clients)                                                 |
+| Connect a machine or migrate an old client                          | [Agent tokens](#agent-tokens-and-upgrading-from-earlier-tokens), [agent endpoints](#agent-endpoints), [static bearer migration](#migrating-static-bearer-clients)             |
 | Configure caller visibility, read-only endpoints, or auth ownership | [Principals and operators](#principals-visibility-and-operators), [pools](#pools), [shared and personal auth](#shared-and-personal-auth)                                      |
+| Lay out an agent's pools                                            | [Organizing an agent's pools](#organizing-an-agents-pools)                                                                                                                    |
 | Set up human sign-in                                                | [Access on Workers](#cloudflare-access-on-workers), [Clerk tokens and sessions](#clerk-oauth-tokens-and-operator-sessions), [management](#human-authentication-management)    |
 | Enable credential or connection controls                            | [Management permissions](#management-permissions), [start/restart/disconnect](#starting-restarting-and-disconnecting)                                                         |
 | Diagnose consent or token refresh                                   | [State at rest](#downstream-oauth-state-at-rest), [callbacks](#consents-and-callbacks), [refresh failures](#refresh-failures), [safe errors](#what-a-servers-errors-may-say)  |
@@ -21,6 +22,154 @@ defines refusal precedence.
 [Source and tests](#source-and-tests) points to the implementation. Migration
 sections describe upgrade procedures, not additional auth modes to enable.
 
+## Add a person
+
+People authenticate with Clerk on Node or Cloudflare Access on Workers.
+Finish [Clerk setup](#clerk-oauth-tokens-and-operator-sessions) or
+[Access setup](#cloudflare-access-on-workers) if the deployment has no human
+provider yet. A machine-only deployment cannot admit people or manage shared
+auth through the operator UI.
+
+1. Admit the person in the identity provider's sign-in policy. Obtain their
+   stable principal id there: Clerk's user id, or Access's `user_uuid` (email
+   only when no `user_uuid` is supplied). A display name or an email for a
+   Clerk user is not their principal id.
+2. Choose their role in `src/connecta.config.ts`. Add an administrator to
+   `maintainers`; they can reach plain `/mcp`, manage shared credentials and
+   agent tokens, and read activity. For a person needing selected tools, add
+   them to the intended pool's `members` instead. Maintainers need explicit
+   pool membership too if they will use `/mcp/<pool>`.
+3. Use a bare id with exactly one interactive provider, or `{ namespace, id }`
+   with several (Clerk's Frontend API URL or `cloudflare-access` as namespace).
+   Keep these stable: personal credentials are partitioned by principal.
+4. Typecheck and restart/redeploy. Sign in as the person and verify their
+   intended endpoint and tools. A pool-only member at plain `/mcp` gets 404.
+   With the UI enabled, the [member page](./operator-ui.md#use-the-member-page)
+   shows their pool URLs and client setup; `/ui/api/config` returns 200 with
+   `role: "member"`. It does not grant the maintainer pages, shared credential
+   controls, activity, or token management. For their own downstream login, use `authScope: "personal"`; they connect
+   only their own account on connectors included in their pools.
+
+For example, with one Clerk provider, Alice administers the deployment and
+Bob uses only the team pool. Replace these illustrative Clerk ids with the
+ids from that deployment's Clerk instance:
+
+```ts
+maintainers: ["user_alice"],
+pools: {
+  team: { tools: ["crm", "tickets"], members: ["user_alice", "user_bob"] },
+},
+```
+
+In the Node template and Worker example, `CONNECTA_MAINTAINERS` is a
+comma-separated list of these ids; update that environment variable when
+using their roster wiring. Pool membership remains code. To remove a person,
+remove their memberships and maintainer entry, restart/redeploy, and remove
+their sign-in admission as appropriate. Never add another person to an
+agent's `<agent>-<user>` pool; follow [the pool layout](#organizing-an-agents-pools).
+
+## Connect a shared credential
+
+Shared auth belongs to the deployment. Every admitted caller of that
+connector uses the same downstream account. Only a signed-in interactive
+maintainer can change it; an agent token cannot perform the setup.
+
+1. Configure the connector in `connectors` with `authScope: "shared"`
+   (the default) and either OAuth or a credential slot. Include it only in
+   the intended pools. For a user's account used by an agent, give it its
+   own id such as `notes_alice` and expose it only in `assistant-alice`.
+2. Enable the encrypted vault over the deployment's existing storage before
+   saving credentials or OAuth tokens. Keep its base64 32-byte key in secret
+   storage and preserve it across restarts. Node's template reads
+   `CONNECTA_CREDENTIAL_KEY`; Workers read `CREDENTIAL_ENCRYPTION_KEY`.
+   See the platform README's credential-vault setup. Enable `operatorUi()`
+   for credential-slot editing and human auth with a maintainer roster.
+3. Typecheck and restart/redeploy. Sign in as a maintainer, open the
+   connector's page, and use its Connection tab. For a credential slot, enter
+   and save the downstream token. For OAuth, connect and finish the browser
+   consent as the intended downstream account. An MCP maintainer can also
+   call `authorize_connector` for that id and follow its signed browser link;
+   that link grants no extra authority.
+4. Check connected status, then make a bounded read from the intended pool.
+   Check the downstream account, not just successful authentication. For
+   `notes_alice`, the maintainer must authorize Alice's intended account.
+
+For example, this connector expects a Bearer token entered in the UI; the
+secret never belongs in the configuration:
+
+```ts
+remoteMcp("crm", {
+  url: "https://crm.example.com/mcp",
+  authScope: "shared",
+  auth: { type: "credential", credential: { label: "CRM API token" } },
+});
+// OAuth alternative: auth: { type: "oauth" }
+```
+
+To rotate a saved token, save its replacement in the same slot; subsequent
+calls use it. Revoke the retired token at the downstream service. For OAuth,
+use Restart to authorize afresh, Continue to resume a pending consent, and
+Disconnect to invalidate the local grant and catalog. To remove a credential,
+use the connector's credential delete control. Clearing a slot with no saved
+value returns 409 with `problem: "credential_required"`; it does not revoke
+anything downstream. An unreadable stored value can still be cleared for
+recovery. These changes do not change
+pool membership. Environment-backed header auth has no editable vault slot:
+rotate that secret in the deployment's secret store and restart/redeploy.
+
+## Issue, rotate, or revoke an agent token
+
+Each declared agent has exactly one token slot. Keep `accessTokens(storage)`
+on the same database as the server. Declare the agent and its pools in code
+before issuing a token, for example:
+
+```ts
+agents: ["assistant"],
+accessTokens: accessTokens(storage),
+pools: { assistant: { tools: ["crm", "tickets"], members: ["agent:assistant"] } },
+```
+
+Typecheck and restart/redeploy, then use either procedure:
+
+- **Signed-in maintainer:** with human auth and `operatorUi()` enabled, open
+  the Access tokens page, select `assistant`, and issue, rotate, or revoke
+  its token. Save an issued secret privately immediately; it appears once.
+  The UI reads the slot revision and sends it with the operation. If the slot
+  changed, reload and decide again.
+- **Trusted local provisioning:** the Node template's
+  `npm run --silent rotate-token -- assistant` both issues and rotates.
+  Run it with the same environment and database path as the server; local
+  commands do not load `.env`. Store stdout privately. For revocation, add a
+  small trusted script such as the following to `src/revoke-token.ts` and
+  run `npx tsx src/revoke-token.ts` with that same environment. Workers use
+  the maintainer UI or trusted tooling bound to the same D1 database;
+  a local SQLite script cannot manage a Worker's slots.
+
+```ts
+import { AccessTokenManager } from "@zackbart/connecta/auth/access-tokens";
+import config from "./connecta.config.js";
+
+const { storage, agents } = config(process.env);
+const manager = new AccessTokenManager(storage!, { agents: agents ?? [] });
+const slot = (await manager.list()).find((entry) => entry.name === "assistant");
+if (!slot) throw new Error("Declare assistant before managing its token");
+await manager.revoke("assistant", { expect: slot.revision });
+```
+
+Set the client URL to `https://connecta.example.com/agent/assistant` and
+`Authorization: Bearer <saved-cta-token>`. Its one token also works on every
+personal pool listing `agent:assistant`; the client picks the pool per turn.
+Behind Access, configure the [agent bypass](./deploying.md#agent-endpoints-behind-cloudflare-access).
+Run [doctor](./deploying.md#verify-and-diagnose) with the new token. After a
+rotation, replace the client's saved secret immediately: the old token stops
+admitting on its next request. After revocation, confirm the old token gets 401. Already admitted requests are not recalled. Never put tokens in source,
+activity, or committed output, and never use `/mcp` with a `cta_` token.
+
+If a rotation reports `outcome_unknown`, inspect the slot; an issued secret
+that was not delivered cannot be recovered. Rotate again deliberately for a
+replacement. For older tokens, follow [adoption](#agent-tokens-and-upgrading-from-earlier-tokens)
+instead of assuming they still admit after an upgrade.
+
 ## Credential recognition and admission
 
 Inbound auth decides who may reach the MCP endpoint. People use `clerkAuth`
@@ -52,84 +201,236 @@ The `cta_` syntax is reserved even without the optional token verifier: it
 refuses rather than becoming an ambient human or an open anonymous request.
 Async recognition hooks fail at construction; unexpected rejected promises
 are consumed before refusal so their text cannot reach runtime output.
-Human routes reject recognized machine credentials without consulting token
-storage, then ask only interactive providers. Replace custom `final` and
+Agents reach pools only at [agent endpoints](#agent-endpoints). Every human
+route (`/mcp`, `/mcp/<pool>`, operator pages and APIs, `/connect`, OAuth
+starts and callbacks) refuses a `cta_` token before any recognition hook,
+token storage read, cookie, session, or Access context is consulted: 401 with
+the endpoint's challenge on MCP endpoints and operator data routes, and 403 on
+routes that require an interactive person. The built-in `cta_` adapter is
+never a candidate there, so a refused `cta_` token cannot fall back to an
+ambient identity. Human routes then ask only human providers. Replace custom `final` and
 `finalRefusals` handling with recognition; handshake redirects and admission
 policy refusals are provider verdicts too. Recognition grants no identity.
 
-`authorize` returns `{ ok: true, userId?, subjectId?, principal? }` or a refusal
+`authorize` returns `{ ok: true, userId?, subjectId?, principal?, agent? }` or a refusal
 carrying a `Response`. On 401, routing and challenge selection use the first
 provider that actually answers the endpoint's protected-resource metadata
 request. Its `challenge(request, baseUrl)` supplies `WWW-Authenticate`, including
 `scope`; an unrelated metadata hook does not own resource discovery. Machine-only
 endpoints challenge with `Bearer` and advertise no authorization server. With
-Clerk, even a refused `cta_` token receives Clerk's resource metadata challenge.
+Clerk, a `cta_` token refused at `/mcp` or `/mcp/<pool>` still receives Clerk's
+resource metadata challenge.
 An open deployment with connectors warns at construction.
 
 Clerk denial logs carry checked fixed reason codes. Provider user IDs, email
 addresses, and email domains stay out of denial logs, activity, and status,
 including email lookup failures and admission policy refusals.
 
-## Managed client tokens and upgrading from v0.23
+## Agent tokens and upgrading from earlier tokens
 
-`accessTokens` from `@zackbart/connecta/auth/access-tokens` installs its inbound
-adapter and, beside `ui`, the Access tokens page and `/ui/access-tokens`
-routes. Omitted, none of it loads or is served.
+Machine clients are **agents**, declared by name in code. `agents: string[]`
+lists them: each name matches `^[a-z0-9_-]+$`, at most 64 characters, and is
+unique; anything else, or agents without `accessTokens`, throws at
+construction. `describeConfig()` lists the names and never token state.
+`accessTokens` from `@zackbart/connecta/auth/access-tokens` installs the `cta_`
+inbound adapter and, beside `ui`, the Access tokens page and `/ui/access-tokens`
+routes. Omitted, none of it loads or is served. It takes no options;
+`accessTokens(storage, { maxActive })` throws, since each declared agent has
+exactly one token slot.
 
 ```ts
 import { accessTokens } from "@zackbart/connecta/auth/access-tokens";
 createConnecta({
   storage,
+  agents: ["assistant", "ci"],
   accessTokens: accessTokens(storage),
   auth: clerkAuth({ publishableKey, secretKey }),
   ui: operatorUi(),
-  identity: {
-    connectorAccess, // Keep the existing principal and token-id grant rules.
-    accessTokenManagement: ({ principal }) =>
-      principal?.namespace === "clerk:your-existing-namespace" &&
-      principal.id === "your-operator-id",
-  },
+  maintainers: ["your-operator-id"],
+  pools: { ci: { tools: ["github"], members: ["agent:ci"] } },
   connectors, executor,
   readOnly: false, // required: true refuses every write call
 });
 ```
 
-From v0.23, replace `accessTokens: true` or its options object with
-`accessTokens(storage)` on **the same storage and key namespace**, keeping the
-`access-token:v1:record:*` and `access-token:v1:lookup:*` records: unrevoked
-`cta_…` secrets keep working with no recovery, rewrite, or client rotation. Keep
-the identity namespaces and connector/pool grant callbacks too; storage
-compatibility translates no configuration and invents no grants. `access_token`
-actor ids, the `connecta:access-tokens:v1` activity namespace, friendly names,
-and stored principals carry over; a token without a principal stays unbound.
-Every request evaluates current identity, tool, and endpoint grants, and a token
-never becomes an interactive operator. Names are labels, never permissions. A
-UI-issued token belongs to the issuing human's principal, and any explicitly
-permitted token manager can list, rename, or revoke deployment tokens. Machine tokens manage neither tokens nor connection credentials; operators
-need an interactive provider.
-
-Issuance claims capacity with `compareAndSet`, because counting records before
-writing admits too many concurrent creates; every supported store provides
-it. Active
-capacity defaults to 100, configurable with
-`accessTokens(storage, { maxActive: 200 })` up to 1,000, counted by a durable
-reservation before a secret is written. A failure before lookup publication
-releases it; an uncertain lookup write keeps its metadata and capacity so an
-operator can revoke it, even if creation returned no secret. Creation is never
-retried automatically, and once new-version issuance starts, old-version
-instances must create no tokens: they ignore reservations.
-
-Secrets carry 256 random bits; only SHA-256 digests persist. Creation returns
-the secret once, list and rename never. Revocation removes the lookup before
-updating metadata and authorization caches no token, so revocation takes
-effect on the next authorization (D1 and SQLite are strongly consistent);
-admitted requests are not recalled. Management writes
-require an exact same-origin Origin; responses are private and non-cacheable.
+**Slots.** Each declared agent has one slot: `none`, `issued`, or `revoked`.
+Nothing outside code adds, renames, or rebinds an agent. An interactive
+maintainer issues the first token, rotates it, or revokes it; `AccessTokenManager` exposes
+the same `rotate(name)` and `revoke(name)` to trusted provisioning, and the
+Node template wraps rotation as `npm run --silent rotate-token -- <agent>`.
+Secrets carry 256 random bits and are returned once, on issue or rotate; only
+SHA-256 digests persist. Listing returns `{ name, state, issuedAt?, revokedAt?,
+revision }` per declared agent, never a secret, digest, or prefix.
+
+**Revisions and `expect`.** A slot's `revision` is opaque: 22 base64url
+characters, the first 128 bits of a domain-separated SHA-256 of the agent name
+and the raw stored slot (`none` hashes the absent slot). Every commit stores a
+new slot value, since an issued slot names a fresh record id and a revoked one
+carries a random `revocationId` generated once per revoking call, so the
+revision changes on every issue, rotate, revoke, and adopt and on nothing
+else. The stored slot holds a record id or revocation id and times, never a
+secret or digest, and those ids leave only hashed. The token
+routes return it on every slot: `GET /ui/access-tokens` lists it, and issue,
+rotate, and revoke return the new slot's. Operator contract v2's
+`OperatorAgent.token.revision` carries the same value.
+
+The token routes require the revision the caller decided from:
+
+| Route                                            | `expect`                                                                                          |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
+| `POST /ui/access-tokens/<agent>` (issue, rotate) | JSON body `{ "expect": "<revision>" }`, `Content-Type: application/json`                          |
+| `DELETE /ui/access-tokens/<agent>` (revoke)      | the same body, or `?expect=<revision>` for a client that cannot send a body with DELETE; not both |
+
+A missing or malformed `expect` is 400; a body that is not JSON is 415 and one
+over 1,024 characters is 413. They are checked after authorization and before
+the operation. If the slot's current revision differs, the route answers 409
+`{ "error": "…", "code": "slot_changed" }` before minting a secret or writing
+anything; reload the list and decide again. The check is part of the commit,
+not only the read: the slot's compare-and-set compares against exactly the raw
+slot whose revision matched, so a change that lands between the read and the
+commit refuses with `slot_changed` too, and this call publishes nothing. A
+revocation under `expect` never revokes a token issued after its read. A call
+decides that its own write landed only by an id no other call can produce: a
+rotation or adoption by the fresh record id its slot names, a revocation by its
+`revocationId`. Under `expect`, a compare-and-set that answers "not committed"
+is `slot_changed` at once, so of two conditional revocations of one slot,
+even within one millisecond, exactly one succeeds; an unanswered one is read
+back and succeeds only if the slot carries its own `revocationId`. Issuing
+from a `none`-era revision over a slot that now exists, or rotating over
+someone else's fresh rotation, therefore cannot happen. `aborted` (499) and
+`outcome_unknown` (503) are unchanged. `AccessTokenManager.rotate(name,
+issuedBy, { expect })`, `revoke(name, { expect })`, and `adopt(tokenId, name,
+{ expect })` take the same optional precondition and refuse with an
+`AccessTokenError` whose `code` is `slot_changed`; without `expect` they behave
+as before, which is what the template scripts use.
+
+**Admission.** A `cta_` token admits only while its record is bound to an agent
+currently declared in code and that agent's slot names it. Every other case
+refuses with the same 401 as an unknown token: an undeclared agent, a revoked or
+rotated-out token, a token bound to a human principal, and an unbound token from
+an earlier release. Removing an agent from code stops its token on the next
+request without any storage write. An admitted agent's identity is:
+
+```ts
+{
+  actor: { kind: "access_token", id: "<name>", namespace: "connecta:access-tokens:v1" },
+  subject: { namespace: "connecta:access-tokens:v1", id: "agent:<name>" },
+  agent: "<name>",
+  interactive: false,
+}
+```
+
+`identity.agent` is set only by the built-in adapter; a result from any other
+inbound provider that carries `agent` is refused like an unknown token. An
+agent has no principal, so personal connectors are absent for it and it never
+reads activity. Its subject partitions result handles per
+agent. Activity attributes its calls to the agent name. Pools list an agent as
+`"agent:<name>"`, and the agent reaches each such pool at `/agent/<pool>`
+only. An agent is never a maintainer, and every human endpoint refuses its
+token. An agent never becomes an interactive operator: machine
+tokens manage neither tokens nor connection credentials.
+
+**The slot is the only authority.** A token admits iff its digest's lookup
+names a record, that record carries a currently declared `agent`, and that
+agent's slot is `issued` naming exactly that record. Nothing else counts: a
+lookup or record the slot does not name is inert garbage. Every mutation
+commits by one `compareAndSet` on the slot and only moves forward; no security
+outcome depends on cleanup or on undoing a write.
+
+- **Rotate** writes the new record and its lookup (inert), checks the
+  request's signal, then compare-and-sets the slot from what it read to
+  `issued` with the new record. That is the commit: from it the new secret
+  admits and the previous one refuses, so after `rotate` returns the old secret
+  fails on its next request. Of concurrent rotations exactly one commits and
+  returns a secret; the others publish nothing and fail with `slot_changed`
+  under `expect` (always, on the route) or a conflict without it. An unanswered commit is read back, never assumed or replayed.
+  If the request has ended once the commit is decided, the secret cannot be
+  delivered, so the slot moves forward to `revoked` by compare-and-set; if that
+  cannot be settled, the call fails with `outcome_unknown` (503 on the
+  route), never success. After an `outcome_unknown` rotation the operator UI
+  may show the slot as `issued` although no secret was returned; that secret
+  cannot be recovered, so rotate again to get a replacement.
+- **Revoke** reads the slot, checks the signal, and compare-and-sets it to
+  `revoked`. An abort before that commit changes nothing. Without `expect`, a
+  slot that changed before the commit is revoked as it now stands; with it,
+  the revocation refuses with `slot_changed`.
+- **Nothing is deleted on the request path.** Rotate, revoke, and adopt never
+  delete or compare-and-set away a lookup or record, except the record and
+  lookup the same call just wrote while they are known to be uncommitted, each
+  removed by one conditional delete. Previous, revoked, and superseded records
+  and lookups stay behind, inert, because no slot names them. Storage therefore
+  grows by one small record (and, for rotation, one lookup) per rotation or
+  adoption, bounded by the number of agents times their rotations. An operator
+  maintenance sweep for this inert data is follow-up work.
+- **One operation deadline.** One wall-clock deadline is set when rotate,
+  revoke, or adopt starts: 2 seconds, or the request's own `deadline` option if
+  sooner. It bounds every storage await in the operation: the adoption claim
+  and its read-back, record and lookup writes before the commit, the commit's
+  own acknowledgement, and everything after it (reading back an unanswered
+  commit, revoking an undeliverable rotation, completing an adoption's lookup
+  step). Each storage call is raced against it and none starts after it. A
+  timeout before the commit reports `aborted` if the caller has left, since
+  nothing was published, and `outcome_unknown` otherwise; a pending claim
+  acknowledgement is always `outcome_unknown`, and the claim, if it landed,
+  leaves the token resumable by the same agent. An acknowledgement still
+  pending at the deadline is an unanswered commit with no time left to read it
+  back, and any success decided after the deadline is reported as
+  `outcome_unknown` instead. Records written before an uncertain commit stay.
+  An operation still in flight at the deadline is abandoned rather than
+  cancelled, which is safe: it can only be a read; a write of the call's own
+  record or lookup, inert until a slot names it; the claim, inert to admission;
+  the commit itself, whose outcome is then reported as unknown and whose slot
+  alone decides what admits; the revoke compare-and-set from `issued` naming
+  one record to `revoked`, which can only stop a token and fails if the slot
+  changed; or the adoption compare-and-set of a lookup from the legacy record to
+  the new one, which fails if anyone else moved it. If an abandoned revoke never lands, the
+  undelivered rotation secret may keep admitting, but it never left the server:
+  a liveness problem reported as `outcome_unknown`, never a credential exposure.
+
+The routes pass the request's `AbortSignal` to `rotate`, `revoke`, and `adopt`
+(`{ signal }`); a signal already aborted performs no storage call at all. Authorization caches no token, and D1 and SQLite are strongly
+consistent; admitted requests are not recalled. Management writes require an
+exact same-origin Origin; responses are private and non-cacheable.
+
+**Upgrading.** Keep `accessTokens(storage)` on **the same storage and key
+namespace**. The `access-token:v1:record:*` and `access-token:v1:lookup:*`
+records stay readable, and slots are added beside them as
+`access-token:v1:agent:<name>`. A stored token stops admitting until an agent
+adopts it. Trusted provisioning runs `AccessTokenManager.adopt(tokenId,
+agentName)`, which never changes the legacy record. It first sets a write-once
+claim, `access-token:v1:adopted:<legacy id>`, from absent to the agent's name;
+the claim is never deleted, so once any adoption has started the legacy token
+is consumed for that agent forever, even after the agent's token is revoked or
+rotated away, and a retired secret can never be adopted again. The claim is
+inert to admission: an adoption aborted after it leaves the token adoptable
+only by the same agent. It then writes a new record
+carrying the agent and the legacy digest, checks the signal, commits by
+compare-and-setting the agent's slot from none to `issued` with that record,
+then moves the digest's lookup from the legacy record to the new one by
+compare-and-set, from which the machine's existing `cta_` secret admits as the
+agent. Adopt delivers no secret, so once committed it completes even if the
+request ended. Running the same adoption again, when the slot already names a
+record with this digest, completes the lookup step and succeeds; there is no
+release step. If the lookup step cannot be confirmed the call says so and asks
+for a rerun. Adoption refuses a human-bound, revoked, or already adopted token,
+a token claimed by another agent, a token another agent's slot already carries,
+and an agent whose slot names anything else. Of two agents racing for one
+token, the claim admits one; the other is refused before its commit.
+`unboundTokens()` lists the legacy records adopt accepts: unbound, unrevoked,
+never claimed, still owning their digest's lookup, and carried by no declared
+agent's slot. The Node template wraps both as
+`npm run adopt-token`.
+Human-bound tokens, which earlier UI issuance tied to the issuing operator,
+cannot be adopted and stay refused; issue the agent a new token instead. Rows
+recorded before the upgrade keep their token-record actor ids. Grant callbacks
+that matched token record ids with `actor.id` match agent names through
+`identity.agent` instead.
 
 ## Origins
 
 `allowedOrigins?: readonly string[] | "*"` bounds which browsers may speak to
-the MCP endpoint. A disallowed `Origin` on `/mcp` or any `/mcp/<pool>` gets a
+the MCP endpoint. A disallowed `Origin` on `/mcp`, any `/mcp/<pool>`, or any
+path in the agent namespace gets a
 fixed 403 before HTTPS redirects, admission, auth, and CORS preflight — the
 check cannot depend on anything a caller has yet proved. The default admits the
 `publicUrl` origin plus HTTP(S) loopback at any port; a supplied list replaces
@@ -143,7 +444,7 @@ silently never matching. A permitted origin still has to authenticate.
 One authorization yields three roles: the **actor** identifies the caller in
 activity, the **subject** owns transient results such as `connecta.result` pages,
 and the **principal** is the human owner of personal connector auth. An
-interactive Clerk or Access user supplies all three; Access service identities are refused; machines present `cta_` tokens. The principal is an explicit
+interactive Clerk or Access user supplies all three; Access service identities are refused; machines are agents presenting `cta_` tokens, with an actor and a subject but no principal. The principal is an explicit
 `principal: { namespace, id }` from `authorize`, accepted whenever it
 validates, or else one derived from `userId` and the provider's
 `activityActorNamespace`, so only the derived path needs a namespace.
@@ -160,129 +461,143 @@ Its `subject` option, a deployment-config function from the admitted identity
 to a downstream account (a Clerk principal id to a Workspace address, say) or
 one fixed address, is applied once per call and only to a request an inbound
 provider authenticated: any `ok`, a subject-less custom credential included, never an open
-deployment's anonymous admission. Otherwise, or on `undefined`, the call fails
+deployment's anonymous admission. An agent never reaches the function; it acts
+as its pool's `owner` ([Pool owners](#pool-owners-for-google-workspace)).
+Otherwise, or on `undefined`, the call fails
 `auth_required` before any request leaves. Arguments, headers, and programs
 never reach it; a deployment's own connectors still cannot read the caller.
 
-The deployment's top-level `grant` decides who may use plain `/mcp`; named
-pools use their own grants. These endpoint decisions receive the admitted
-identity below and never widen its connector access.
-
-`identity.connectorAccess` returns `"all"` (the default) or grants, for
-discovery and use alike: a connector id opens every tool on it, a
-`connector.tool` address that tool alone, and
-`{ tool: "connector.tool", requireReadOnly: true }` that tool only while the
-loaded catalog says it is explicitly read-only, never connector-wide. Grants
-are additive, so a bare id or unrestricted address beside a guarded one wins.
-
-Tool grants are enforced in the scoped registry view, below the catalog service,
+Access is read from one place, deployment code. Top-level
+`maintainers` lists the people who reach plain `/mcp`, which serves the whole
+catalog with the deployment's `readOnly`, and the operator routes. Each pool's
+`members` lists who reaches that pool, people at `/mcp/<pool>` and agents at
+`/agent/<pool>`, which serve exactly that pool's `tools`. A maintainer opens no pool implicitly; list them as a member to use
+one. Nothing intersects these lists with anything else, and a request never
+names its own scope.
+
+A member reference is one of:
+
+- a bare principal id, `"user_2abc"`, resolved in the namespace of the
+  deployment's one interactive provider (its `activityActorNamespace`: Clerk's
+  Frontend API URL, or `"cloudflare-access"`);
+- `{ namespace, id }`, required when a deployment has zero or several
+  interactive providers, or when the id contains `:`;
+- `"agent:<name>"`, naming an agent declared in `agents` (pool `members` only).
+
+A person matches when the admitted principal equals the reference exactly; an
+agent matches by `identity.agent`, which only the built-in token adapter sets.
+Construction throws on a bare id without exactly one interactive
+provider, a bare id containing `:`, an undeclared agent, a repeated reference,
+an empty or missing pool `members`, an agent in `maintainers`, `maintainers`
+missing or empty when a provider that admits people is configured (any
+provider other than the built-in agent-token adapter), and a non-empty
+`maintainers` on a deployment with no such provider. With agents alone
+(`accessTokens` as the only inbound auth), `maintainers` stays empty, nobody
+can be a maintainer, and plain `/mcp` and every operator API admit nobody; the
+agents reach only `/agent/<pool>` for the pools that list them. With no inbound auth at all, the
+deployment is open (see [pools](#pools)). `describeConfig()` lists
+`maintainers` as `{ namespace, id }` and each pool's resolved `members`.
+
+Pool tools are enforced in the scoped registry view, below the catalog service,
 so `search_tools`, `describe_tools`, both call tools, a program's
-`connecta.search`, `connecta.describe`, and `connecta.call`, and the connection
-UI read one filtered list. Connector-level discovery, guides, and
-`authorize_connector` keep a connector when any of its tools is granted —
-`docs.read` permits the `docs` handoff. Without one it is absent: discovery
-omits it, and `authorize_connector` returns the same "Unknown connector" refusal
-as for a connector that does not exist. An ungranted tool fails exactly like one
+`connecta.search`, `connecta.describe`, and `connecta.call` read one filtered
+list. Connector-level discovery, guides, and `authorize_connector` keep a
+connector when any of its tools is in the pool — `docs.read` permits the
+`docs` handoff. Without one it is absent: discovery omits it, and
+`authorize_connector` returns the same "Unknown connector" refusal as for a
+connector that does not exist. A tool outside the pool fails exactly like one
 the connector never had: `unknown_tool`, with no hint that it exists. That is
-the whole security claim, in one place on purpose. There is no _caller-selected_
-tool set: a narrower slice is a branch in this resolver or a pool, and a bot
-needing its own is its own stored token subject. A request may never name its own
-scope.
+the whole security claim, in one place on purpose.
 
-### Team read sets
+`identity.connectorAccess`, including guarded
+`{ tool, requireReadOnly: true }` grants, the top-level `grant`, and pool
+`grant` are removed; each fails construction with a message naming its
+replacement. A guarded read grant becomes a pool with `readOnly: true`.
 
-Keep team membership in deployment code and review exact addresses:
+### Team pools
+
+Keep membership in deployment code; static lists can be built with ordinary
+code at construction:
 
 ```ts
-const engineering = new Set(["engineer-id"]);
-const marketing = new Set(["marketer-id"]);
-const engineeringGrants = ["issues", { tool: "campaigns.list", requireReadOnly: true }] as const;
-const marketingGrants = ["campaigns", { tool: "issues.search", requireReadOnly: true }] as const;
+const engineering = ["engineer-id"];
+const marketing = ["marketer-id"];
 createConnecta({
   auth: cloudflareAccessAuth(),
-  identity: {
-    connectorAccess: ({ principal }) => {
-      const id = principal?.id;
-      if (!id) return [];
-      return [...new Set([
-        ...(engineering.has(id) ? engineeringGrants : []),
-        ...(marketing.has(id) ? marketingGrants : []),
-      ])];
-    },
+  maintainers: ["owner-id"],
+  pools: {
+    engineering: { tools: ["issues", "campaigns.list"], members: engineering },
+    marketing: { tools: ["campaigns", "issues.search"], members: marketing },
+    reporting: { tools: ["issues", "campaigns"], readOnly: true, members: [...engineering, ...marketing] },
   },
   connectors: [issues, campaigns, billing], executor,
   readOnly: false, // required: true refuses every write call
 });
 ```
 
-Engineering sees all `issues` tools and only `campaigns.list`; Marketing sees all
-`campaigns` tools and only `issues.search`. Neither sees `billing`; both memberships
-grant both connectors in full. Unknown or unprincipalled identities get `[]`.
-Use a stable authenticated principal or subject, never request headers or tool
-arguments. A token's stored principal is vouched for by inbound auth. Pools narrow their endpoint, not plain `/mcp`.
-
-| Catalog change                                           | Guarded exact grant                                                                                                     | Unrestricted exact string grant                                     |
-| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
-| New name                                                 | Excluded until reviewed and added                                                                                       | Excluded until reviewed and added                                   |
-| Removed or renamed name                                  | Unreachable; warned when the scoped view reads the catalog                                                              | Same                                                                |
-| Stored write verdict after overrides and provider review | Removed from discovery and every invocation path, including `call_destructive_tool` and programs on a writable endpoint | Still granted; `call_tool` refuses writes and write paths take over |
-| Schema change alone                                      | Does not revoke, unless it breaks a reviewed digest: then it is a write, as above                                       | Same as above                                                       |
-
-The example assumes both exact tools were reviewed as read-only; names imply no safety.
-Review schemas, annotations, and downstream behavior
+Engineering's endpoint serves every `issues` tool and only `campaigns.list`;
+Marketing's every `campaigns` tool and only `issues.search`. Neither pool
+serves `billing`; only the owner's plain `/mcp` does. A person in both pools
+uses two endpoints, never a union.
+
+| Catalog change          | Exact `connector.tool` in a pool                                        |
+| ----------------------- | ----------------------------------------------------------------------- |
+| New name                | Excluded until reviewed and added                                       |
+| Removed or renamed name | Unreachable; warned when the scoped view reads the catalog              |
+| Stored write verdict    | Still in the pool; `call_tool` refuses writes and write paths take over |
+| Schema change alone     | Does not revoke, unless it breaks a reviewed digest: then it is a write |
+
+Names imply no safety. Review schemas, annotations, and downstream behavior
 before changing lists or upgrading providers. Remote catalogs can drift without
-upgrades; fresh cached facts are classified against the current review on every read; downstreams
-can change behavior while keeping read-only annotations. For `api()`, the author
-owns declarations and handlers. Connecta enforces loaded declarations, not
-absence of side effects. Restricted downstream credentials do not replace grants.
+upgrades; fresh cached facts are classified against the current review on
+every read; downstreams can change behavior while keeping read-only
+annotations. For `api()`, the author owns declarations and handlers. Connecta
+enforces loaded declarations, not absence of side effects. Restricted
+downstream credentials do not replace pools; a `readOnly` pool refuses every
+write whatever the catalog says.
 
-`[]` hides all connectors from discovery and the connection UI. Address-only or
-disqualified guarded grants can leave a connector visible with its tool unreachable.
 Failed remote loads are errors, not empty catalogs. A transient first-page tool
 listing failure may serve complete facts in the same auth partition for five
 minutes after expiry. Failed pagination, permission and auth failures do not
-use this fallback. The expired deadline cannot authorize auth recovery. Personal OAuth ownership and credential
-administration are separate from visibility; writes follow the endpoint's `readOnly` setting and client approval. `test/identity-scope.test.ts` exercises these boundaries.
+use this fallback. The expired deadline cannot authorize auth recovery.
+Personal OAuth ownership and credential administration are separate from
+endpoint access; writes follow the endpoint's `readOnly` setting and client
+approval.
 
 ## Migrating static bearer clients
 
 The `/auth/bearer` export, `bearerToken`, and its `assertedPrincipal` header
 mode are removed. Existing static secrets cannot be converted into `cta_`
-secrets. Use a separate stored token for each machine or human owner:
+secrets. Declare each machine as an agent instead:
 
 1. Configure the existing D1 or SQLite store as `storage`, and install
    `accessTokens(storage)`. Keep its existing keys and namespaces.
-2. Sign in through Clerk or Worker Access. Grant the intended token manager
-   `identity.accessTokenManagement`, then create a token on Access tokens.
-   It is bound to that human's principal. For a machine without a human owner,
-   provision `new AccessTokenManager(storage).create("machine-name", "deployment-provisioning")` from
-   trusted deployment code. The Node template provides `npm run provision-token -- machine-name`.
-3. Update `identity.connectorAccess` and pool grants to the returned token
-   metadata id with `actor.kind === "access_token"`. Names and `tokenPrefix`
-   are display labels. Keep existing human principal namespaces unchanged.
-4. Save the once-returned secret in the client's secret store and send
-   `Authorization: Bearer cta_…`. Behind Worker Access, also satisfy the edge
-   with Access service credentials; an Access-only machine no longer admits.
+2. Add the machine's name to `agents`. Issue its token from the Access tokens
+   page as a signed-in maintainer, or from trusted
+   deployment code with
+   `new AccessTokenManager(storage, { agents }).rotate("machine-name", "deployment-provisioning")`.
+   The Node template provides `npm run --silent rotate-token -- machine-name`.
+3. List `"agent:machine-name"` in the `members` of each pool it uses. Agents
+   are never maintainers, so a machine that used plain `/mcp` moves to a pool
+   holding its tools.
+4. Save the once-returned secret in the client's secret store and point the
+   client at `/agent/<pool>` with `Authorization: Bearer cta_…`. Behind Worker
+   Access, add the [agent bypass application](./deploying.md#agent-endpoints-behind-cloudflare-access)
+   so that token is the only credential; an Access-only machine no longer admits.
 5. Verify MCP initialization and the intended grants. Confirm the old static
    secret refuses, then remove its environment secret and the old import.
-   Remove `X-Connecta-Principal`; a token's stored principal cannot vary by
-   request. Provision one human-bound token per represented user instead.
-   To retain an old asserted user's personal state, trusted provisioning must
-   call `manager.create(name, { namespace: existingNamespace, id: existingId })`
-   with the exact existing namespace and canonical id, after applying the old
-   admission policy. A Clerk UI token uses the Clerk principal instead and
-   cannot inherit a different asserted namespace's partitions.
-
-Revocation acts on the next request. Rotate by creating a replacement,
-updating the client, verifying it, and revoking the old token. Keep token text
-out of logs and reports.
+   Remove `X-Connecta-Principal`. An agent has no principal, so a client that
+   acted for a human with personal connectors has no token replacement; that
+   human signs in instead.
+
+Rotation and revocation act on the next request. Keep token text out of logs
+and reports.
 
 ## Pools
 
-A pool is a named slice of the deployment served at its own endpoint,
-`/mcp/<pool>`, for when one identity needs different capability sets on different
-clients: a support agent that sees three Notion tools and Linear, a calendar bot
-that sees one tool, both over the same credentials. Private remote catalog
+A pool is a named slice of the deployment served to its members: people at
+`/mcp/<pool>` and agents at `/agent/<pool>`. A support team sees three Notion
+tools and Linear, a calendar bot sees one tool, both over the same credentials. Private remote catalog
 cache entries remain partitioned by the admitted pool.
 
 ```ts
@@ -291,56 +606,87 @@ createConnecta({
   accessTokens: accessTokens(storage),
   auth: clerkAuth({ publishableKey, secretKey }),
   readOnly: false, // required; pools without their own readOnly inherit it
-  grant: ({ actor }) => actor.kind !== "access_token", // machines use their pools
+  maintainers: ["user_owner"],
+  agents: ["calendar-bot"],
   pools: {
-    support: {
-      tools: ["linear", "notion.search_pages", "notion.fetch_page"],
-      grant: ({ principal }) => supportTeam.has(principal?.id ?? ""),
-    },
-    calendar_bot: {
-      tools: ["calendar.create_event"],
-      grant: ({ actor }) => actor.kind === "access_token" && actor.id === calendarTokenId,
-    },
-    reporting: {
-      tools: ["linear", "notion"],
-      readOnly: true,
-      grant: ({ principal }) => analysts.has(principal?.id ?? ""),
-    },
+    support: { tools: ["linear", "notion.search_pages", "notion.fetch_page"], members: supportTeam },
+    calendar_bot: { tools: ["calendar.create_event"], members: ["agent:calendar-bot"] },
+    reporting: { tools: ["linear", "notion"], readOnly: true, members: analysts },
   },
-  identity: { connectorAccess },
   connectors, executor,
 });
 ```
 
 Without configured `auth`, an open deployment has one anonymous, non-interactive
-identity; grants like these return false and every pool path 404s.
-
-The optional top-level `grant: (identity) => boolean | Promise<boolean>`
-controls plain `/mcp`. Omitted, it admits everyone who passes auth, including
-anonymous callers on an open deployment. Configured, only literal `true`
-admits; other returns and throws deny. A refusal has the same 404 status,
-body bytes, and headers as a refused or undeclared pool, after auth. The
-operator log records `default_grant_denied` or `default_grant_threw`, never
-the callback's error text. Invalid config values throw at construction.
-Named pools use only their own grants, so a caller refused at `/mcp` may
-still use a pool that grants it.
+identity. It keeps plain `/mcp` with the whole catalog, as the construction
+warning says, every pool path answers the 404 because nobody can be a member,
+and every agent endpoint answers the machine-only 401 because no agent can be
+admitted.
+
+| Rule         | Contract                                                                                                                                                                                                                                                                                                                                |
+| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Scope        | `/mcp/<pool>` and `/agent/<pool>` serve exactly the pool's `tools` (connector ids or exact `connector.tool` addresses), with the pool's `readOnly`, to its member people and member agents respectively. Plain `/mcp` serves the whole catalog to maintainers. Neither intersects with or widens anything.                              |
+| Refusal      | A non-maintainer at `/mcp`, a non-member, and an undeclared pool get an identical 404 status, body, and headers, after auth. The operator log records `not_maintainer`, `not_pool_member`, or `pool_not_declared`. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content.                   |
+| Agents       | An agent member reaches its pools only at `/agent/<pool>`, with its `cta_` token. Human endpoints refuse `cta_`; see [agent endpoints](#agent-endpoints).                                                                                                                                                                               |
+| Construction | Malformed names, unknown options or connectors, empty pools, empty or missing `members`, unresolvable member references, a non-boolean `readOnly`, an `owner` that is not a Workspace email address, a retired `trust` or `grant`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load. |
+| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                                                                                    |
+| Drift        | No wildcards; pool tools are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                                                                                       |
+
+### Agent endpoints
+
+`/agent/<pool>` is where agents use a pool. It exists for deployments behind
+Cloudflare Access, which [bypasses `/agent/*`](./deploying.md#agent-endpoints-behind-cloudflare-access)
+at the edge so an agent sends one credential, and it behaves the same on Node.
+
+- **Path.** Only a raw request pathname byte-equal to `/agent/` plus a
+  well-formed pool name (`[a-z0-9_-]+`) is an agent endpoint. Connecta routes
+  the agent namespace before every other route: any path that starts with
+  `/agent` once escapes are decoded, case is folded, and slashes are
+  collapsed (`/agent`, `/agent/`, `/agent/x/`, `/agent/x/y`, `/AGENT/x`,
+  `/%61gent/x`, `//agent/x`, `/agent/%2f..`, `/agentx`) answers the pool 404
+  before any admission or auth, so a path Access bypasses never reaches a
+  human route. The query string is not part of the match.
+- **Auth.** Only the built-in `cta_` adapter is consulted. Clerk and Access
+  adapters never run; `ctx.access`, which Access attaches even to a bypassed
+  path, is never read or passed on; cookies, Clerk handshake parameters,
+  `Cf-Access-Jwt-Assertion`, and Access service headers are ignored. A
+  missing, malformed, unknown, revoked, or non-`cta_` credential gets 401 with
+  `WWW-Authenticate: Bearer` and no `resource_metadata`.
+- **Membership.** An admitted agent must be listed in that pool's `members`.
+  A non-member agent, a pool that lists no agents, and an undeclared but
+  well-formed pool name get the identical pool 404 after auth, logged as
+  `not_pool_member` or `pool_not_declared`. Unauthenticated callers get the
+  same 401 for declared and undeclared names, so pool names are not
+  anonymously enumerable.
+- **Discovery.** Agent endpoints publish no protected-resource metadata:
+  `/.well-known/oauth-protected-resource/agent/<pool>` is the ordinary 404,
+  declared or not. Agents hold a provisioned token and never run OAuth
+  discovery, so there is no authorization server to name and no resource URL
+  worth advertising.
+- **Handles.** Result handles are bound to `/agent/<pool>`, so one minted
+  there pages nowhere else, including `/mcp/<pool>` and another agent pool.
 
 Protected-resource metadata stays public at both default aliases,
 `/.well-known/oauth-protected-resource` and
 `/.well-known/oauth-protected-resource/mcp`, just as at named-pool aliases.
-Discovery does not authenticate callers or evaluate endpoint grants, so fresh
-OAuth clients can discover how to authenticate. The grant applies after auth
-to MCP requests and result/page handles. Handles remain bound
-to their originating endpoint; paging rechecks the current endpoint grant,
-identity, and connector access. A granting pool cannot read a `/mcp` handle,
-and `/mcp` cannot read that pool's handle.
-
-`describeConfig().hasGrant` and the operator UI report whether plain `/mcp`
-has a configured grant without exposing callback source. `describeConfig()`
-does not evaluate it. Operator catalog, config, activity, and connector auth
-routes require the same default endpoint grant after their own authentication.
-A refused caller gets a private JSON 404; the UI provides no per-pool view.
-The public HTML shell carries no catalog data.
+Discovery does not authenticate callers or evaluate membership, so fresh
+OAuth clients can discover how to authenticate. Admission applies after auth
+to MCP requests and result/page handles. Handles remain bound to their
+originating endpoint; paging re-admits the caller at that endpoint. A pool
+cannot read a `/mcp` handle, and `/mcp` cannot read a pool's handle.
+
+Operator catalog (`/ui/data`, `/ui/connectors/<id>`), activity, shared
+connector auth, and access-token routes require a maintainer after their own
+authentication. Anyone else gets a private JSON 404 `{ "error": "not found" }`.
+`/ui/api/config` serves a maintainer the whole operator contract and a person
+listed in a pool's `members` only their own view: their pools without owner or
+members, and the connectors in them with the tools those pools grant, their
+own connection on personal connectors, and what they may do about it. It
+carries no shared credential state, agents, other members, owners, or
+activity. Anyone else gets the same 404, and an agent token the machine-only
+401 every human route gives it; see the
+[operator contract](./operator-ui.md#operator-data-contract). The public HTML
+shell carries no catalog data.
 
 Each endpoint is writable or read-only. The deployment's `readOnly` sets the
 plain `/mcp` endpoint and is required: a deployment that omits it fails at
@@ -355,19 +701,172 @@ through `call_destructive_tool`, still run.
 Guides are documentation, not discovery: provider `SKILL.md` and usage guides,
 surfaced through `queryAnalysis.guideSummary`, `skills`, `connecta.skill`, and
 skill `resources/read`, are the same on every endpoint and may name tools a
-read-only endpoint refuses.
-Resource reads, grants, and `connectorAccess`, including guarded
-`requireReadOnly` grants, are the same on both. The removed `trust` option fails
-construction with a message naming `readOnly`.
-
-| Rule         | Contract                                                                                                                                                                                                                                                                |
-| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Scope        | `/mcp/<pool>` intersects pool tools with the identity's `connectorAccess`, never widening it. Plain `/mcp` serves the identity's `connectorAccess` after its optional top-level `grant` admits it.                                                                      |
-| Grant        | Pool grants default to deny; only literal `true` admits. Other returns, throws, and undeclared names produce an identical 404 status, body, and headers, after auth. Names are not anonymously enumerable; valid credentials cannot distinguish these cases by content. |
-| Timing       | Declared names await grants, so timing is not hidden. Keep grants pure and fast and names unsecret; names grant no access. The operator log records the refusal reason.                                                                                                 |
-| Construction | Malformed names, unknown options or connectors, empty pools, a non-boolean `readOnly`, a retired `trust`, and addresses absent from an `api()` static catalog throw. Remote catalogs are checked at lazy load.                                                          |
-| Discovery    | Clerk's pool 401 names `/.well-known/oauth-protected-resource/mcp/<pool>` with the pool URL as `resource`, matching RFC 9728. Cloudflare Managed OAuth is application-level and needs no pool setup.                                                                    |
-| Drift        | No wildcards; tool grants are exact names. Missing live tools are unreachable and warned once while in a bounded 1,024-entry FIFO.                                                                                                                                      |
+read-only endpoint refuses. Resource reads and pool tools are the same on
+both. The removed `trust` option fails construction with a message naming
+`readOnly`.
+
+### Pool owners for Google Workspace
+
+An agent has no Workspace account. On a Workspace connector (`gmail()`,
+`drive()`, `sheets()`, `slides()`, `forms()`, `docs()`) whose `subject` is a
+mapping function, the caller decides whose account a call opens:
+
+| Caller                        | Acts as                                                                         |
+| ----------------------------- | ------------------------------------------------------------------------------- |
+| A person, in any pool         | Their own account, through the `subject` mapping. A pool `owner` never applies. |
+| An agent in a pool            | The pool's `owner`, resolved before the mapping, which never sees the agent.    |
+| An agent, pool has no `owner` | Nothing: the call fails `auth_required` before any request leaves.              |
+
+`owner` is a Workspace email address, checked at construction and listed in
+`describeConfig()` (`null` when unset). Over HTTP, `/ui/api/config` serves it
+only to an authenticated maintainer; anyone else, a pool member and an open
+deployment's anonymous caller included, reads `null`, the same as an unset
+owner. Core copies it from the pool the
+request was admitted through; no argument, header, or program can choose or
+change it, and the `auth_required` message never names an address. One
+`gmail()` then serves a pool per person:
+
+```ts
+const team = [
+  { id: "alice", email: "alice@example.com" },
+  { id: "bob", email: "bob@example.com" },
+];
+createConnecta({
+  auth: clerkAuth({ publishableKey, secretKey }),
+  storage,
+  accessTokens: accessTokens(storage),
+  readOnly: false,
+  maintainers: ["alice"],
+  agents: ["assistant"],
+  pools: Object.fromEntries(
+    team.map((person) => [
+      `assistant-${person.id}`,
+      { tools: ["gmail", "drive"], owner: person.email, members: [person.id, "agent:assistant"] },
+    ]),
+  ),
+  connectors: [
+    gmail("gmail", { purpose, serviceAccount, subject: (who) => emailOf(who.principal?.id) }),
+    drive("drive", { purpose, serviceAccount, subject: (who) => emailOf(who.principal?.id) }),
+  ],
+  executor,
+});
+```
+
+The agent harness, not the model, picks the pool for each turn, which is what
+keeps one person's mailbox from another's. Adding a person to someone else's
+pool opens nothing of the owner's Workspace account to them, since people act
+as themselves through the mapping. That holds only for Workspace mappings:
+every other connector in the pool, including a shared-auth connector holding
+the owner's own account, runs the same for every member
+([members of a personal pool](#organizing-an-agents-pools)).
+
+A fixed `subject` address is the explicit shared-account exception: every
+caller, person or agent, acts as it in every pool that lists the connector,
+and pool owners do not apply. Keep fixed-subject connectors out of pools whose
+members must not share that account.
+
+### Organizing an agent's pools
+
+Use this layout for every agent's pools. It gives each person's own accounts
+to the agent only when that person is the one talking, without a second
+connection. This section holds the complete rules.
+
+1. **One connection per agent.** Each agent has exactly one Connecta
+   connection, and its client (the harness, never the model) chooses the
+   pool's URL for each turn. Never mount a second Connecta connection beside
+   it: the model would get two sets of meta-tools, and `execute_code` cannot
+   join results across connections. The agent's one `cta_` token works on
+   every pool that lists it.
+2. **Base pool `<agent>`.** `/agent/<agent>` serves pool `<agent>`: shared and
+   organization connectors only, with no `owner`. Use it in group chats,
+   scheduled runs, and any turn without exactly one identified person.
+3. **Personal pool `<agent>-<user>`.** `/agent/<agent>-<user>` serves pool
+   `<agent>-<user>`: the base plus that user's own connectors. Use it only in
+   a one-on-one with that user. `<user>` is a short, stable handle you choose
+   (`alice`), never a provider id, principal id, or address; pool names match
+   `[a-z0-9_-]+`.
+4. **Define the base once.** Every personal pool spreads one base constant, so
+   a change to the base reaches every pool.
+5. **`owner` is the user's Workspace address.** Set `owner` on
+   `<agent>-<user>` to that user's Google Workspace email address; it is
+   checked as an address at construction, and it makes Workspace connectors
+   act as that user for the agent ([pool owners](#pool-owners-for-google-workspace)).
+   The base pool has no owner, so keep Workspace connectors out of it: there
+   they are absent, as in any pool that does not list them. (A Workspace
+   connector listed in a pool without an owner fails `auth_required` for an
+   agent.)
+6. **A user's own account is its own connector id.** Agents have no
+   principal, so `authScope: "personal"` connectors never appear for them.
+   Give each user's account its own connector id with shared auth, which a
+   maintainer connects once (`notes_alice`, `notes_bob`), and list it only in
+   that user's pool. Google Workspace is the exception: one connector whose
+   `subject` is a mapping function, with each personal pool's `owner`
+   choosing the account.
+7. **Changes stay in config.** Adding an account for a user adds its
+   connector and lists it in that user's pool `tools`; the client does not
+   change. Adding a user adds one `<agent>-<user>` pool.
+8. **No other person in a personal pool.** The only human member an
+   `<agent>-<user>` pool may have is that same user, and usually it has none.
+   Never add another person: its per-user connectors (`notes_alice`) use that
+   user's account for everyone the pool admits, so another member would read
+   and write the user's account as their own. A person's own use normally
+   goes through their own pools or plain `/mcp`, not the agent's.
+
+```ts
+import type { GoogleWorkspaceOptions } from "@zackbart/connecta/providers/gmail";
+
+const assistant = { tools: ["crm", "tickets"], members: ["agent:assistant"] };
+const emailOf = (id?: string) => (id === "user_alice" ? "alice@example.com" : undefined);
+const workspace: GoogleWorkspaceOptions = {
+  purpose: "Mail and files of the person in a one-on-one",
+  serviceAccount,
+  subject: (who) => emailOf(who.principal?.id),
+};
+
+createConnecta({
+  auth: clerkAuth({ publishableKey, secretKey }),
+  storage,
+  accessTokens: accessTokens(storage),
+  readOnly: false,
+  maintainers: ["user_alice"],
+  agents: ["assistant"],
+  pools: {
+    assistant,
+    "assistant-alice": {
+      ...assistant,
+      tools: [...assistant.tools, "notes_alice", "gmail", "drive"],
+      owner: "alice@example.com",
+    },
+    "assistant-bob": {
+      ...assistant,
+      tools: [...assistant.tools, "notes_bob", "gmail"],
+      owner: "bob@example.com",
+    },
+  },
+  connectors: [
+    crm,
+    tickets,
+    // Shared auth: a maintainer connects each user's own account once.
+    remoteMcp("notes_alice", { url: "https://notes.example.com/mcp", auth: { type: "oauth" } }),
+    remoteMcp("notes_bob", { url: "https://notes.example.com/mcp", auth: { type: "oauth" } }),
+    gmail("gmail", workspace),
+    drive("drive", workspace),
+  ],
+  executor,
+});
+```
+
+The agent's client picks the pool from who it is talking to, for example:
+
+```ts
+const handles: Record<string, string | undefined> = { "<alice's sender id>": "alice", "<bob's sender id>": "bob" };
+const user = turn.isDirect ? handles[turn.verifiedSender] : undefined;
+const url = `https://connecta.example.com/agent/${user ? `assistant-${user}` : "assistant"}`;
+```
+
+Rule 8 is why the example lists only the agent in each pool. People act as
+themselves only through a Workspace mapping; a shared-auth connector such as
+`notes_alice` acts as Alice for whoever the pool admits.
 
 ## Shared and personal auth
 
@@ -403,7 +902,7 @@ namespace: the live **epoch**, the latest consent's state digest, and one
 authorization server's client registration, tokens, and discovery. Each
 consent has a **flow record**, `oauth:flow:<sha256(state)>`, holding its
 epoch, consent URL, and PKCE verifier for fifteen minutes; the state itself is
-stored nowhere. Keys come from `src/storage/keys.ts`.
+stored nowhere.
 
 With a vault, the grant's body and each verifier are sealed with its AES-GCM
 key, the additional authenticated data naming the connector, owner partition,
@@ -819,30 +1318,57 @@ anything, so SDK hook order cannot mix servers or cross a reset.
 
 ## Management permissions
 
-Visibility grants no authentication-management permission. Two resolvers take
-`Readonly<AuthenticatedIdentity>` and return `"all"`, `"none"` (the default),
-or connector ids: `credentialAdministration` for shared credentials and OAuth
-grants, `personalConnection` for a human's own grants on personal connectors.
-Each action needs visibility _and_ the permission; both run only for an
-interactive identity, and personal actions also need a stable namespaced
-principal, whose partition they always use. Exceptions and unknown ids fail
-closed; permissions come from authenticated identity, never caller input.
-
-`identity.activityAccess` takes `Readonly<IdentityReference>` — `id` and
-`namespace` — and controls reading activity. When configured, an authenticated
-principal may pass it without an interactive session. This includes a `cta_`
-token's stored principal and a non-interactive API principal; subject-only
-callers and anonymous requests cannot qualify. The optional activity `readGate`
-also applies. Reads remain GET-only and filter connector/tool grants, personal
-ownership and recorded pool access before any actor-label lookup. Personal rows
-use the admitted principal in the existing typed actor id and namespace fields;
-rows without a provable owner are withheld. Non-interactive
-reads return typed actors without directory labels. Old rows without a pool
-remain subject to connector, tool and owner checks. Undeclared, it admits every
-interactive human, the one default here that is open, because a single-operator
-deployment would otherwise be locked out of its own event stream. Team
-deployments should set it. There is no general administrator role and no
-implicit token-management authority. `identity.accessTokenManagement` is a separate boolean permission, false by default, evaluated only for interactive humans. Lifecycle routes also require a stable principal.
+Management follows `maintainers` and pool `members`; no resolver configures it. The former `identity.credentialAdministration`,
+`identity.personalConnection`, `identity.accessTokenManagement`, and
+`identity.activityAccess` each fail construction naming their replacement,
+and so does the `identity` section itself, even empty.
+
+| Action                                    | Who may                                                                                                                                        |
+| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Shared credentials and OAuth grants       | An interactive maintainer                                                                                                                      |
+| A personal connector's own account        | An interactive person with a stable principal who is a maintainer, or a member of a pool containing that connector; always their own partition |
+| Agent tokens: list, issue, rotate, revoke | An interactive maintainer                                                                                                                      |
+| Activity reads                            | A maintainer principal, interactive or not, within the optional `readGate`                                                                     |
+
+Agents and other machine credentials manage nothing. Shared auth is
+deployment-wide, so every step on a shared connector takes an interactive
+maintainer: issuing a link through `authorize_connector`, a program's or a
+failed call's auth handoff, or an elicitation; starting it at `/connect/<id>`;
+completing the OAuth callback, which re-checks at completion; and
+`/ui/oauth/<id>` and `/ui/credentials/<id>`. A pool member may connect and
+disconnect only a personal connector in one of their pools: through
+`authorize_connector` at `/mcp/<pool>`, the `/connect/<id>` link and its
+callback, which are bound to the principal that requested them, and
+`/ui/oauth/<id>` and `/ui/credentials/<id>`, which resolve only their pools'
+connectors and refuse a shared one with 403. A person who is neither gets the
+private 404 every operator route gives. A maintainer also manages their own
+personal connectors, which plain `/mcp` includes, in their own partition. A
+maintainer's link continues in the operator UI; a member's link starts the
+authorization directly, as it does on a deployment without the UI. A member's
+operator contract names, per personal connector, the actions their permission,
+the deployment and the connector's hooks support: credential `save` with a
+vault, `clear` once their own partition holds a value, and `test` only when that
+value matches the declared shape and a matching test hook exists; OAuth
+`connect` and `restart` with `startAuth`, `finishAuth` and `verifyState`, and
+`disconnect` with `disconnectAuth`. `/ui/oauth/<id>` gates each verb on those
+same hooks, so a connector provisioned out of band can still be disconnected,
+and `/ui/credentials/<id>` refuses to clear a partition that holds nothing
+with 409 `credential_required`, for members and maintainers alike.
+
+Activity is read by maintainers alone. An authenticated maintainer principal
+reads it without an interactive session, including a non-interactive API
+principal; pool members, agents, subject-only callers, and anonymous requests
+get the private 404. The optional activity `readGate` still narrows it. Reads
+remain GET-only and filter connector/tool grants, personal ownership and
+recorded pool access before any actor-label lookup. Personal rows use the
+admitted principal in the existing typed actor id and namespace fields; rows
+without a provable owner are withheld. Non-interactive reads return typed
+actors without directory labels. Old rows without a pool remain subject to
+connector, tool and owner checks. A maintainer sees rows from plain `/mcp` and
+from every declared pool within that pool's tools; rows from a pool no longer
+declared are withheld. Agent token lifecycle routes require an interactive
+maintainer with a stable principal; they issue, rotate, and revoke declared
+agents' tokens, and never create, rename, or bind one.
 
 Personal activity rows must carry the checked `principal` actor basis as well as
 a matching principal ID and namespace. Legacy subject actors cannot prove
@@ -854,18 +1380,10 @@ boundary reads returns 503 without a cursor; cancellation starts no further read
 ```ts
 createConnecta({
   auth: cloudflareAccessAuth(),
-  identity: {
-    connectorAccess: ({ principal, actor }) =>
-      principal?.id === "owner-id"
-        ? "all"
-        : actor.id === "calendar-bot"
-          ? ["calendar.create_event"]
-          : ["shared_docs", "personal_linear", "notion.search_pages"],
-    credentialAdministration: ({ principal }) =>
-      principal?.id === "owner-id" ? "all" : "none",
-    personalConnection: () => ["personal_linear"],
-    activityAccess: ({ id }) => id === "owner-id",
-  },
+  // Administers shared credentials, agent tokens, and activity.
+  maintainers: ["owner-id"],
+  // Each member connects their own account on personal_linear.
+  pools: { team: { tools: ["shared_docs", "personal_linear", "notion.search_pages"], members: team } },
   connectors, executor,
   readOnly: false, // required: true refuses every write call
 });
@@ -889,14 +1407,18 @@ the token against the Worker-level Access application's AUD. A nonempty trusted
 `ctx.access.getIdentity()` supplies `user_uuid`, with `email` as fallback, in the
 stable `cloudflare-access` principal namespace. Missing identity, service
 identity, or unusable user ids refuse. Access service credentials can admit the
-request at the edge, but connecta requires a `cta_` token for machine identity.
+request at the edge, but connecta requires a `cta_` token at `/agent/<pool>`
+for machine identity.
 
 It never reads `Cf-Access-Jwt-Assertion`, fetches signing keys, or accepts a
-caller's JWT. Missing context or a throwing lookup fails closed on both
-runtimes. It does not support Node, a `cloudflared` origin, or a Service Binding
-hop. [Decision 0003](https://github.com/zackbart/connecta/blob/main/decisions/0003-inbound-auth.md) records that boundary
-and replaces #506's provisional verdict with supported Worker Access.
-Connecta configuration still decides connector and management permissions.
+caller's JWT. Missing or malformed trusted context returns 401. A rejected
+human identity, including a service identity or an unusable user id, returns 403. A thrown identity lookup or its five-second deadline returns retryable
+503 with `problem: "identity_unavailable"` and `Retry-After: 1`. Every refusal
+carries `Cache-Control: no-store`. None of these failures admits an identity,
+and an unavailable lookup never falls back to another provider. The operator
+UI can re-request admission after a failure without a browser reload. It does not support Node, a `cloudflared` origin, or a Service Binding
+hop.
+Connecta configuration still decides connector access and management: `maintainers` and pool `members`.
 
 Protect the Worker with a Worker-level Access application whose destination is
 `{ "type": "worker", "worker_id": "<the Worker script tag>" }`. A traditional
@@ -921,13 +1443,16 @@ covers. For another client add its exact URI or the narrowest wildcard covering
 it, never its whole origin. A missing entry lets discovery succeed and
 registration fail later, which looks like a broken MCP server, not a setting.
 
-Do not add a bypass for the discovery routes; a fully automated client uses a
+Do not add a bypass for the discovery routes or any human path. The one
+bypass connecta expects is the [agent application for `/agent/*`](./deploying.md#agent-endpoints-behind-cloudflare-access),
+behind which an agent's `cta_` token is its only credential. Worker-level
+Access runs before every other connecta route, so `/health`, operator pages,
+downstream OAuth callbacks, `/mcp`, and `/mcp/<pool>` all require Access, and a
+`cta_` token is not a standalone edge credential there because Cloudflare
+rejects the request before connecta sees it. Unattended tools that need those
+paths, such as `connecta doctor` reading `/health`, use a
 [service token](https://developers.cloudflare.com/cloudflare-one/access-controls/service-credentials/service-tokens/)
-through `CF-Access-Client-Id` and `CF-Access-Client-Secret` instead. Worker-level
-Access runs before every connecta route, so `/health`, operator pages, downstream
-OAuth callbacks, and `/mcp` all require Access unless a more-specific policy says
-otherwise, and a `cta_` token is not a standalone edge credential
-because Cloudflare rejects the request before connecta sees it. Custom public
+through `CF-Access-Client-Id` and `CF-Access-Client-Secret`. Custom public
 webhooks live outside connecta and need their own Access routing policy. The
 [Worker example](../examples/worker/) carries the whole deployment shape.
 
@@ -995,7 +1520,7 @@ with no audience/resource claim from exact client IDs dedicated to this
 deployment. Never share these clients with another resource server. A present
 malformed or mismatched binding is rejected even for an allowlisted client.
 The list does not restrict correctly bound tokens. It applies to every pool;
-identity and pool grants still narrow access. Profile scopes do not identify a
+maintainers and pool members still decide access. Profile scopes do not identify a
 resource, and `scopes` remains metadata, not an admission rule.
 
 Each new DCR registration gets a new client ID and needs an operator update
@@ -1146,8 +1671,8 @@ Clerk sign-in returns to the same link. Expired session cookies use Clerk's hand
 identity checks or code exchange; responses preserve session cookies. Access supplies trusted Worker identity
 at the edge. Protect `/connect/*` and `/oauth/callback/*` with the MCP endpoint's Access application.
 
-For both connector scopes, the browser must match the initiating principal and retain `personalConnection` or
-shared `credentialAdministration` permission. Connecta saves that principal against downstream state. The
+For both connector scopes, the browser must match the initiating principal and still be permitted to manage the
+connector: a maintainer for shared auth, or for personal auth a maintainer or a member of a pool containing it. Connecta saves that principal against downstream state. The
 callback checks state, identity, permission, and RFC 9207 `iss` before consuming
 the handoff, interpreting an error, or exchanging a code. A supplied issuer must
 exactly match the consent. A server advertising issuer-response support also
@@ -1290,7 +1815,7 @@ owner's access token as `Authorization: Bearer` with these rules:
   preventing repeated refreshes by later program calls.
 - Handlers can name no storage, sealing, or owner partition; the registry owns them.
 - The answer's `.text()` and `.json()`, clones' too, decode its bytes as UTF-8, so
-  workerd never quotes a downstream's Content-Type in its own log (INV-6).
+  workerd never quotes a downstream's Content-Type in its own log.
 
 The grant record and consents, epoch fencing, vault sealing, shared/personal ownership,
 callback state/principal checks, `authorize_connector`, Connect, Restart, and
@@ -1320,7 +1845,14 @@ is retained across requests, and rejected writes are never replayed. An omitted
 `describe()` includes neither the key nor the minted tokens. The maintained
 provider skill explains App permissions and installation prerequisites.
 
-## Source and tests
+## Contributor reference
+
+### Source and tests
+
+[Decision 0007](https://github.com/zackbart/connecta/blob/main/decisions/0007-agent-pool-layout.md)
+explains the pool layout; [decision 0006](https://github.com/zackbart/connecta/blob/main/decisions/0006-pools-are-the-access-model.md)
+explains pools as the access model. `test/identity-scope.test.ts` checks identity
+boundaries, and `src/storage/keys.ts` owns credential key families.
 
 Inbound adapters live in [src/auth](https://github.com/zackbart/connecta/tree/main/src/auth);
 [auth routes](https://github.com/zackbart/connecta/blob/main/src/routes/oauth.ts)