@zackbart/connecta 0.23.0 → 0.24.0

package/documentation/auth.md

@@ -1,67 +1,60 @@
 # Inbound auth
 
-Inbound auth decides who may reach the MCP endpoint. A deployment may admit a
-static bearer, operator-issued access tokens, Clerk identities, Cloudflare
-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.
+Inbound auth decides who may reach the MCP endpoint. Import configured bearer
+support from `@zackbart/connecta/auth/bearer`, Clerk from `/auth/clerk`, or
+Cloudflare Access from `/auth/cloudflare-access`. Providers may be combined;
+static bearers are checked first, then other providers in configuration order.
+Connecta no longer issues `cta_` tokens or serves token-management routes.
 
 ## 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
+The actor identifies the caller in activity. The subject 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.
+Cloudflare service identity has an actor and subject but no principal.
+
+`identity.connectorAccess` returns `"all"` or declared connector ids. It governs
+discovery and use, and defaults to all connectors. Visibility alone grants no
+authentication-management permission. Two independent resolvers return
+`"all"`, `"none"`, or declared connector ids:
+
+- `credentialAdministration` allows an interactive human to manage shared
+  credentials and shared OAuth grants.
+- `personalConnection` allows an interactive human to manage their own
+  credentials and OAuth grants on personal connectors.
+
+Both default to `"none"`. Each action requires visibility and the relevant
+permission. Personal actions also require a stable namespaced principal and
+always use that principal's partition. Resolver exceptions and unknown ids
+fail closed. Permissions come from authenticated identity, never caller input.
+
+The management resolvers receive `Readonly<AuthenticatedIdentity>`.
+`identity.activityAccess` receives `Readonly<IdentityReference>` with `id` and
+`namespace`, and controls reading global activity. Its default admits
+interactive humans, so team deployments should set it explicitly if the event
+stream should be restricted. It replaces `operatorAccess`; there is no general
+administrator role or token-management authority.
 
 ```ts
 createConnecta({
   auth: cloudflareAccessAuth(),
   identity: {
     connectorAccess: ({ principal }) =>
-      principal?.id === "user_a"
-        ? ["shared_docs", "personal_linear"]
-        : ["shared_docs"],
-    operatorAccess: ({ id }) => id === "user_a",
+      principal?.id === "owner-id" ? "all" : ["shared_docs", "personal_linear"],
+    credentialAdministration: ({ principal }) =>
+      principal?.id === "owner-id" ? "all" : "none",
+    personalConnection: () => ["personal_linear"],
+    activityAccess: ({ id }) => id === "owner-id",
   },
-  connectors: [
-    remoteMcp("shared_docs", { url: "https://example.com/mcp" }),
-    remoteMcp("personal_linear", {
-      url: "https://mcp.linear.app/mcp",
-      authScope: "personal",
-      auth: { type: "oauth" },
-    }),
-  ],
+  connectors,
   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.
+Built-in Clerk and Access providers supply identity namespaces. A custom
+interactive provider must set `activityActorNamespace` before its users can
+own personal auth. Keep the namespace and principal ids stable across upgrades;
+changing them selects different personal storage partitions.
 
 ## Cloudflare Access on Workers
 
@@ -92,12 +85,11 @@ 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 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
-email domains, groups, or device posture into a second policy layer.
+A human identity gets a code-derived MCP view. Managing connection auth requires
+an explicit `credentialAdministration` or `personalConnection` grant. An Access
+service identity has no human principal and cannot mutate connection auth.
+Access decides admission and identity; Connecta configuration selects connector
+access and these narrower permissions.
 
 Protect the Worker with a Worker-level Access application whose destination is
 `{ "type": "worker", "worker_id": "<the Worker script tag>" }`. A traditional
@@ -135,8 +127,7 @@ Worker-level Access runs before every connecta route. Consequently:
 
 - `/health`, operator pages, downstream OAuth callbacks, and `/mcp` all require Access unless a more-specific hostname/path
   policy says otherwise;
-- a static connecta bearer and a `cta_…` token are not standalone edge
-  credentials, because Cloudflare rejects them before connecta sees them; and
+- a static Connecta bearer is not a standalone edge credential, because Cloudflare rejects them before connecta sees them; and
 - custom public webhooks belong to the deployment outside Connecta and need
   their own Access routing policy. Keep Connecta's OAuth discovery paths
   protected when Managed OAuth is enabled.
@@ -156,57 +147,21 @@ publishable slot, and a startup error is a log line. A deployment that builds
 per request, as the Workers shape does, sees the same error on its first
 request instead of a base64 stack on every route.
 
-## Operator-issued access tokens
+## Human authentication management
 
-Set `accessTokens: {}` to let eligible interactive operators create named Bearer
-tokens at `/tokens`:
+Credential and OAuth mutation require an admitted interactive human, connector
+visibility, the appropriate shared or personal permission, and an exact
+same-origin `Origin` for browser requests. A configured MCP bearer never becomes
+a browser management credential.
 
-```ts
-createConnecta({
-  storage,
-  auth: clerkAuth({ /* ... */ }),
-  accessTokens: {},
-  connectors,
-});
-```
+With `ui: operatorUi()` and a vault, static credential recovery can return a
+secret-free handoff to the connection UI. Without the UI, that recovery is
+`unavailable`; Connecta does not return a link to a missing page. An authorized
+interactive MCP caller can still start downstream OAuth through
+`authorize_connector` without the UI. Core owns the callback and verifies state
+and principal ownership independently of the optional browser application.
 
-The storage adapter must implement `list(prefix)`. Connecta returns each
-`cta_…` secret once and stores only its SHA-256 digest plus non-secret metadata.
-The operator can rename or revoke a token later. Revocation removes admission
-before updating its display metadata, so a partial storage failure fails
-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. 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
-same-origin mutation boundary as connector credentials. `maxActive` defaults
-to 100 and can be set from 1 through 1,000.
-
-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.
-
-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 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 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 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
-rules.
+See [meta-tools](./meta-tools.md#authorization-recovery) and
+[storage and credentials](./storage-and-credentials.md). The
+[upgrade guide](./upgrading.md#0240-optional-modules) covers moving clients
+off removed Connecta-issued tokens before changing deployment configuration.

package/documentation/cloudflare.md

@@ -135,7 +135,7 @@ Dashboard and API tabs.
 
 `verify_api_token` needs no permission beyond the token existing. In legacy
 mode, `verify_global_api_key` reads `/user` to confirm the email and key pair.
-The `/credentials` Test action runs the matching check before storage.
+The connection UI Test action at `/` runs the matching check before storage.
 
 Cloudflare rate-limits *authentication failures* aggressively and separately
 from the global limit: a few requests with a bad token return HTTP 429 with

package/documentation/connectors.md

@@ -367,7 +367,7 @@ A remote MCP connector that authenticates with a static key has two ways to
 receive one. `{ type: "headers", headers }` bakes the literal value into the
 deployment file, which suits a secret the runtime already holds.
 `{ type: "credential" }` declares the slot instead and lets an operator paste
-the key at `/credentials`, where it is encrypted at rest and rotatable without
+the key at the connection UI at `/`, where it is encrypted at rest and rotatable without
 a redeploy:
 
 ```ts

package/documentation/linear.md

@@ -88,7 +88,7 @@ configuration. A personal API key carries the acting user's full workspace
 permissions, so pair it with `access: "read-only"` unless the deployment
 genuinely writes.
 
-The same key can arrive from `/credentials` instead, which is what a deployment
+The same key can arrive from the connection UI at `/` instead, which is what a deployment
 with no secret store — or an operator who rotates keys without a redeploy —
 wants:
 

package/documentation/meta-tools.md

@@ -316,19 +316,21 @@ Every typed `auth_required` call failure uses the same envelope:
 handoff:
 
 - `oauth`: an `authorizationUrl` and consent instructions;
-- `operator_config`: an `operatorUrl` ending in `/credentials`, plus the
+- `operator_config`: an `operatorUrl` to the mounted connection UI, plus the
   declared credential label and field names/guidance; or
 - `unavailable`: an honest deployment/configuration message.
 
 The class follows what the connector declares, not how it was authored: a
 `remoteMcp()` connection using `auth: { type: "credential" }` declares a slot
-and no OAuth flow, so it lands in `operator_config` beside every `api()`
-credential.
+and no OAuth flow, so it uses `operator_config` when both vault and UI are
+configured. Without either it returns `unavailable`, never a dead UI link.
 
 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 interactive-user credential route, and only for a
-connector visible to that user. After OAuth consent or a human update, retry
+connector visible to that user with the relevant shared or personal management
+permission. OAuth start, including `force`, requires that permission too. Core
+callbacks work without the UI for authorized interactive callers. 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.
 

package/documentation/mixpanel.md

@@ -50,7 +50,7 @@ password, not ordinary configuration. Mixpanel currently labels service-account
 MCP authentication beta. Prefer OAuth unless the deployment is intentionally
 headless.
 
-The same service account can arrive from `/credentials` instead, and there the
+The same service account can arrive from the connection UI at `/` instead, and there the
 operator pastes the readable pair rather than an encoded blob:
 
 ```ts

package/documentation/notion.md

@@ -58,7 +58,7 @@ it does not assume the REST interface's endpoint budget describes MCP traffic.
 
 One operator-managed credential: an internal integration token from
 [notion.so/profile/integrations](https://www.notion.so/profile/integrations).
-The deployment needs `credentials.encryptionKey` configured, or the token
+The deployment needs `vault: encryptedCredentialVault(storage, encryptionKey)` configured, or the token
 cannot be stored and every call fails `auth_required` at use.
 
 Two Notion-specific facts decide whether a working token is enough:
@@ -69,7 +69,7 @@ Two Notion-specific facts decide whether a working token is enough:
   default. `list_comments` and `add_comment` fail with 403 until an operator
   turns them on in Notion.
 
-`/credentials` offers a Test action, which calls `GET /v1/users/me` — the
+The connection UI at `/` offers a Test action, which calls `GET /v1/users/me` — the
 cheapest call that proves a token is live — and reports the workspace it
 authenticated into.
 

package/documentation/operations.md

@@ -33,8 +33,7 @@ and `test/package-surface.test.ts` fails if the two ever drift apart.
 There are exactly two deployment shapes.
 [`templates/node/`](../templates/node/) is what `connecta init` copies — the
 one standalone Node project, Docker-ready rather than Docker-only — and
-[`examples/worker/`](../examples/worker/) is the Cloudflare shape. Both ship
-the whole operator feature set; each README walks through its own enablement.
+[`examples/worker/`](../examples/worker/) is the Cloudflare shape. Both show explicit optional modules; each README walks through enablement.
 A third scaffold that is a diff away from either is the shape
 [#344](https://github.com/zackbart/connecta/issues/344) deleted, so do not add
 one.
@@ -84,16 +83,15 @@ 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)) |
+| `identity?` | all visible; auth management denied; interactive activity reads | `{ connectorAccess?, credentialAdministration?, personalConnection?, activityAccess? }` derives separate use and management permissions ([identity](./auth.md#principals-visibility-and-operators)) |
+| `storage?` | `memoryStorage()` | connector state, catalogs, and result paging; pass storage explicitly to the optional vault ([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 }` |
-| `branding?` | neutral Connecta defaults | operator-page and OAuth result-page labels and marks |
+| `logger?` | `console`, prefixed `[connecta]` | `{ debug, info, warn, error }`, or `"silent"` to suppress diagnostic output; independent of activity history |
+| `ui?` | unset | `operatorUi({ branding? })` from `/ui`; omitted means no browser UI routes or bundle imports |
 | `serverInfo?` | `connecta` / package version | `{ name, version, title?, websiteUrl?, icons? }` per the MCP icons spec |
 | `deploymentInfo?` | unset | arbitrary metadata exposed by `/health` |
-| `activity?` | unset | `{ store, readGate?, deploymentId? }` — payload-free activity storage, an optional operator-read gate, and a stable event label |
-| `credentials.encryptionKey?` | unset | base64 32-byte AES key for the connector vault. Without it, connectors declaring `credential` warn and their slots stay unmanageable |
-| `accessTokens?` | unset | `{ maxActive? }` (default 100) for operator-issued MCP bearer tokens. Requires an interactive operator provider, or construction throws ([access tokens](./auth.md#operator-issued-access-tokens)) |
+| `activity?` | unset | `activityHistory({ store, readGate?, deploymentId? })` from `/activity`; omitted means no event recording or history reads |
+| `vault?` | unset | `CredentialVault`; `encryptedCredentialVault(storage, encryptionKey)` from `/credentials` supplies the built-in encrypted implementation |
 | `discovery.concurrency?` | 4 | connector catalogs/status probes in flight at once |
 | `discovery.catalogTtlSeconds?` | 300 | fresh TTL for cached tool lists |
 | `discovery.persistCatalog?` | true | persist serializable catalogs as a manifest plus revision-addressed chunks |
@@ -229,7 +227,6 @@ in.
 
 | Suite | Covers |
 | --- | --- |
-| `access-tokens.test.ts` | the `AccessTokenManager` — a one-time secret created, authenticated, renamed, and revoked, bounded names and active count, enumerable storage required, a deployment with no interactive operator refused — and the operator-only routes, down to historical activity still resolving a revoked token's name |
 | `activity.test.ts` | payload-free delivery: a rejected async write attaches to `waitUntil` instead of throwing, approved destructive calls record under their real entry point, result-size friction records without retaining the result, and a hallucinated connector id or invented identity is clamped so the event still cannot carry a payload |
 | `api-connector.test.ts` | `api()` — kind, description, tool defs, dispatch, default args, unknown tools, handler throws, argument validation, and the construction contract |
 | `bearer.test.ts` | constant-time bearer compare, case-insensitive scheme, 401 challenges, and the retired audience options refusing rather than silently unbinding |
@@ -252,7 +249,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, parallel-call, 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 |
+| `identity-scope.test.ts` | identity-derived connector visibility, personal credential isolation, separate shared-auth and personal-auth management permissions, 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 |
@@ -261,11 +258,12 @@ in.
 | `notion-provider.test.ts` | Notion's API and MCP construction, the hosted safety manifest and drift behavior, the deliberate REST surface including declined expanded page inputs, request construction, lean projections, both pagination conventions, error mapping, and writes |
 | `operator-boundary.test.ts` | the operator row of the decisions table, after every mutation route: authentication material managed without moving a declared structure, and the one honest exception — a credential write making a remote catalog appear, which is discovery arriving, not an operator editing the deployment |
 | `operator-store.test.ts` | `src/operator-ui/app/store.ts` against a fake browser: the Clerk listener, ambient Access requests without a browser-readable token, `gate()`, the generation fence, and the request path |
+| `optional-modules.test.ts` | absent modules, UI-free OAuth, fast lists and independent detail deadlines, explicit auth-management grants, invalid-resolver refusal, and passive OAuth consent-state protection |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
 | `provider-registry.test.ts` | all seven maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
 | `registry.test.ts` | construction and id validation, startup warnings, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
 | `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, and downstream session termination |
-| `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from `/credentials`: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, the payload-free activity event, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
+| `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from the connection UI: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, the payload-free activity event, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
 | `remote-mcp-pagination.test.ts` | the `tools/list` cursor chain in both directions — exact cursor handoff, first-wins dedup, a failed later page rejecting rather than returning its prefix, the runaway backstops, the tool-metadata re-prime across pages, and paginated catalogs reaching the discovery path |
 | `request-admission.test.ts` | `/mcp` bounded before auth, the stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, and the separate fallback code pool |
 | `result-shapes.test.ts` | passive output-shape learning: value-free bounded inference, merging, 256-entry LRU eviction, 24-hour expiry, runtime isolation, read-only admission, declared-schema precedence, definition-change invalidation, discovery provenance, and failure isolation |
@@ -287,7 +285,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, 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 |
+| `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, explicit optional modules 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 credential-free maintainer drift checker: recorded touched endpoints, heading, table, and inline MCP inventories, setup-only providers, live-schema ownership, a quiet revision bump, clear failures for unavailable inputs, `$ref` traversal, and one well-formed row per endpoint | spawns the checker against filesystem fixtures |
@@ -310,7 +308,7 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 
 | Suite | Covers |
 | --- | --- |
-| `browser/operator-ui.spec.ts` | the operator wiring in a real browser: Clerk loader order across its version redirect and a real load failure, the shell staying open until authentication, credential and access-token and OAuth flows end to end, drift shown without naming a tool, and every failure and empty state |
+| `browser/operator-ui.spec.ts` | the operator wiring in a real browser: Clerk loader order across its version redirect and a real load failure, the shell staying open until authentication, credential and OAuth flows end to end, drift shown without naming a tool, and every failure and empty state |
 
 **The `_transportFactory` seam.** `RemoteMcpOptions._transportFactory` is
 internal, not public API: when set, `remoteMcp()` uses that `Transport` instead

package/documentation/operator-ui.md

@@ -4,109 +4,87 @@ The browser surface a human uses to see what a deployment exposes and to manage
 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 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
-things a deployment cannot do are worse than no pages
-([#345](https://github.com/zackbart/connecta/issues/345)). The
-[Node template](../templates/node/) carries sign-in, vault, tokens, and
-activity as commented blocks in `src/index.ts` — plus a deployment-owned
-`src/file-activity.ts` that is compiled rather than commented — and the
-[Worker example](../examples/worker/) wires the first three and comments the
-fourth, which needs a D1 database. Each README walks through its own
-enablement.
-
-The vault is the one whose page needs a second thing. `/credentials` lists
-connector credential slots, so `credentialManagement` stays `no_slots` — and
-the nav entry stays hidden — until a connector declares `credential`, however
-well-configured the vault is. Neither shape's shipped connectors need a secret,
-so both carry the slot's shape as a comment beside a connector and say so in
-their walkthrough, which is the honest version of the same page count.
-
-## The shape
-
-| Piece | What it owns |
-| --- | --- |
-| `src/ui.ts` | The served HTML: branding, gated URLs, CSP-nonced script tags, the four page titles, and `buildUiData` — the `/ui/data` payload. |
-| `src/operator-ui/model.ts` | The transport types both sides share, plus connector filtering. |
-| `src/operator-ui/view.ts` | The app's state shape and every pure rule over it. No DOM, so `test/ui.test.ts` calls it directly. |
-| `src/operator-ui/app/` | The browser app: `store.ts` (state and every request), `main.tsx` (shell, gate, router), and one component file per page. |
-| `src/operator-ui/browser.css` | One stylesheet, inlined into the shell. |
-| `src/operator-ui/generated.ts` | The build output: the bundle and the stylesheet as two exported strings. |
-
-The server renders a mount point, not a page. Branding, the optional Clerk
-loader, and every operator-configured URL stay in `src/ui.ts`, where they are
-gated before they can become an attribute; the bundle renders everything that
-has a state. Two roots share one store: `#operatorNav` and `#operatorContent`.
-
-Cloudflare Access is ambient browser auth. When the current Worker invocation
-has `ctx.access`, the shell selects the `cloudflare-access` UI mode, emits no
-Clerk loader, and sends no browser-readable token. Same-origin fetch includes
-the HttpOnly `CF_Authorization` cookie, Access admits it at the edge, and the
-server reads the resulting runtime identity. Sign out navigates to
-`/cdn-cgi/access/logout`. Mutations still require an exact same-origin
-`Origin`; an ambient cookie does not weaken the CSRF boundary.
-
-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
-is not two same-hostname gates running in parallel. Access is upstream and a
-request it rejects never reaches Clerk. Keeping Clerk in the array preserves a
-code-level rollback after Access is detached.
-
-The Clerk loader is intentionally blocking. The inline operator bundle calls
-`boot()` as soon as the parser reaches the end of the body, so a deferred Clerk
-script would make an expected parse-time gap look like a permanent network
-failure. Blocking also preserves the existing failure path: after a real
-loader error, the parser continues and `boot()` renders the Clerk load message.
-Clerk's redirect from the major-version loader URL to its pinned asset keeps
-the same ordering.
-
-## Rules that are not obvious
-
-- **No operator data in the shell.** Every page serves the same markup. Connector,
-  credential, token, and activity data arrives only through the authenticated
-  `/ui/*` APIs, and the shell is identical whether or not a caller is signed in.
-- **One store, one identity.** `store.ts` is the only file that touches `fetch`,
-  `localStorage`, Clerk, or the ambient Access mode. Every token-bearing request carries the current session's token,
-  while Access requests deliberately carry none,
-  and every response is dropped unless the identity that asked for it is still
-  the one on screen. `resetIdentity` replaces all identity-scoped state at once
-  and bumps a generation that work already in flight compares itself against.
-- **Escaping is structural.** Components return elements; nothing builds HTML
-  from strings. A value that could be a URL passes `safeHttpHref` before it may
-  become an `href`, mirroring the server-side gate in `src/ui.ts`.
-- **Secrets are shown once.** A created access token lives in state only, and
-  leaving the page — by navigation or by `pagehide`, which covers the
-  back-forward cache — unmounts it.
-- **Every flow has four states.** Loading, error, empty, and success, with no
-  dead end: a failed save keeps the form and its typed value, a failed list
-  offers a retry, and an empty collection says what would fill it. A mutation
-  that fails is still a resolved promise — `mutate` lands the failure in state
-  rather than rejecting — so a caller that clears a form must clear it on a
-  confirmed success, never on resolution. `createAccessToken` returns that
-  answer as a boolean for exactly this reason.
-- **Drift is counts, and absence is its own answer.** The connector card reads
-  `catalogDrift` ([#343](https://github.com/zackbart/connecta/issues/343)) as
-  four category counts and a timestamp. There is no drill-down, because a tool
-  name or a schema here would make an operator page the payload surface the
-  drift model refuses to be. A connector with no report renders as *not
-  observed*, never as clean: this runtime having seen no refresh is not the
-  same claim as a refresh having found nothing.
+Read [`ethos.md`](../ethos.md) first. Code declares capabilities and access;
+the UI displays the current user's effective permissions and manages only
+authentication material explicitly permitted by that code. It never edits the
+connector set, tool catalog, annotations, OAuth scopes, or permission rules.
+
+## Enable the UI
+
+```ts
+import { operatorUi } from "@zackbart/connecta/ui";
+
+createConnecta({
+  connectors,
+  executor,
+  auth,
+  ui: operatorUi({ branding: { productName: "Team connections" } }),
+});
+```
+
+The UI module owns its browser bundle and routes. Omit `ui` to omit those
+routes and runtime imports. OAuth callbacks remain in core; authorized
+interactive MCP callers can complete consent without the UI. Branding belongs
+to `operatorUi` options, with neutral callback branding when no UI is mounted.
+
+## Connections and activity
+
+Connections is the main page. Each connection combines its status, effective
+permissions, credential metadata, and permitted OAuth or credential actions.
+There is no separate Credentials or Tokens tab. A user may see and invoke a
+shared connector without permission to replace the grant everyone uses.
+`identity.credentialAdministration` and `identity.personalConnection` select
+shared and personal management rights, and both default to none.
+
+Activity appears only when the optional history module has a readable store
+and the caller passes `identity.activityAccess` and any additional read gate.
+It is a global history, so permission to use one connector does not imply
+permission to inspect that history. There is no member roster or policy editor.
+
+The Node and Worker deployment READMEs show how to enable the modules and grant
+the intended identities access. The configured bearer in the Node template can
+read connection status but never mutate credentials as an interactive human.
+
+## Loading and request lifetime
+
+The server shell contains no connector or credential data. Authenticated
+`/ui/data` returns the configured visible connection list without waiting for
+provider status or tool discovery. Details load through `GET /ui/connectors/<id>`, independently,
+under a bounded request lifetime. Unknown and loading states stay explicit;
+a provider failure leaves the other connections usable.
+
+A status read does not start OAuth or create authorization handoffs. Connect is
+an explicit authorized POST. Successful save, reconnect, and disconnect actions
+show their result without waiting for an unrelated full-catalog reload. Server
+mutations still await catalog invalidation before replying, so another request
+cannot consume a persisted catalog from before a credential change.
+
+Each details request owns and closes its downstream connector scope. Never
+cache a transport, request signal, or awaited promise in the UI module.
+
+## Browser identity and security
+
+Cloudflare Access is ambient browser auth. When the Worker invocation has
+`ctx.access`, the shell emits no Clerk loader or browser-readable token.
+Same-origin fetch carries the HttpOnly Access cookie, and the server uses the
+trusted runtime identity. Sign out navigates to `/cdn-cgi/access/logout`.
+Clerk deployments use their configured interactive provider.
+
+Mutation requires exact same-origin `Origin`, an interactive identity,
+connector visibility, and the relevant management permission. Personal actions
+resolve only to the current principal's partition. Credential reads return
+metadata, never saved values or masked fragments. Mutation cannot change any
+declared capability. `test/operator-boundary.test.ts` checks that boundary.
+
+The browser store fences responses by identity generation. Switching identity
+clears the prior identity's state and discards its outstanding responses.
+Components render elements, not HTML strings; links pass the shared URL gate.
+Loading, failure, empty, and success states must all provide a useful next
+step. A failed mutation preserves form input and does not masquerade as success.
+
+Catalog drift remains counts and a timestamp. A missing observation means
+"not observed", not that the downstream catalog is unchanged. The UI does not
+expose tool schemas or raw payloads as diagnostics.
 
 ## Working on it
 
@@ -127,7 +105,7 @@ well as Node and there is no DOM in either:
   DOM-lib program (`tsconfig.operator-ui.json`) because it imports the store.
 - `test/browser/operator-ui.spec.ts` — the wiring, in a real browser:
   Clerk loader order across its version redirect and a real load failure, plus
-  credential, token, and OAuth flows end to end, including their failure and
+  credential and OAuth flows end to end, including their failure and
   empty states. Run it with `npm run test:browser`
   (`npm run test:browser:install` once, for Chromium). It is not part of
   `npm run check`.