@zackbart/connecta 0.22.3 → 0.24.0

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.22.3";
+export const CONNECTA_VERSION = "0.24.0";

package/documentation/architecture.md

@@ -66,24 +66,21 @@ read top to bottom.
 | --- | --- | --- |
 | 0 | HTTPS upgrade | 308 to `publicUrl` when it is HTTPS and the request arrived over HTTP. Path and query are *assigned* onto the configured URL, never resolved against it, so a `//host` pathname cannot replace the deployment origin. `/health` is exempt: a loopback container probe must not depend on public DNS and TLS. `/ui` is canonicalized to `/` while upgrading. |
 | 0 | Cloudflare Access (Worker deployment, when enabled) | Edge admission before this route table. Managed OAuth owns its challenge and discovery metadata; an admitted direct invocation carries trusted identity in `ctx.access`. |
-| 1 | `/ui/access-tokens[/<id>]`, `/ui/credentials/<id>[/<action>]`, `/ui/oauth/<id>` | Private mutation routes, matched **first** so nothing can shadow them and so they own their own `OPTIONS` — they answer it with a refusal rather than inheriting the wildcard CORS preflight. |
-| 2 | `OPTIONS` | Each auth provider's `handleMetadata` gets a chance (CORS preflight for browser MCP clients); otherwise 204 with MCP CORS. |
-| 3 | `/.well-known/*` | Auth providers' `handleMetadata`, open. 404 when none handles it. |
-| 4 | `/health` | Open JSON: status, connector count, `serverInfo`, the configured executor's sanitized name when it has one, catalog-drift counts, admission snapshots, reserved route names, and `deployment` when `deploymentInfo` is set. Payload-free by construction, and it never joins the MCP queue. |
-| 5 | `/oauth/callback/<connectorId>` | Downstream-OAuth completion, open, `verifyState` before `finishAuth`. Personal flows first resolve the short-lived state hash to the principal partition. |
-| 6 | `/favicon.*`, `/ui` → `/`, the operator shells, `/ui/data` | The operator surface ([operator UI](./operator-ui.md)). The shells are open and data-free; `/ui/data` behind them is gated. Built-ins are matched before connector routes, so a connector cannot shadow a page. |
-| 7 | `/ui/activity` | Gated, plus the optional `activity.readGate`. `GET` only; 404 with no `activity.store.list`. |
-| 8 | `/mcp` | **Admission before auth**, then the auth gate, then a fresh MCP server. |
-| 9 | connector `handleRequest` | Registration order, open. Dispatched only after every built-in misses, so a connector can *add* a route and never shadow one of connecta's. First non-null response wins; a throw is a 500, not a fall-through. |
-| 10 | — | 404. |
+| 1 | Mounted UI routes | The optional UI handles its shells, assets, data, details, and auth mutations before wildcard OPTIONS. Mutation routes refuse preflight rather than inheriting MCP CORS. No UI module means none of these routes. |
+| 2 | `OPTIONS` | Auth metadata gets a chance, otherwise MCP CORS preflight. |
+| 3 | `/.well-known/*` | Auth metadata, or 404. |
+| 4 | `/health` | Open payload-free health, executor, admission, and deployment metadata; reserved routes reflect installed modules. |
+| 5 | `/oauth/callback/<connectorId>` | Core downstream OAuth completion, state verification and personal ownership checks; independent of UI. |
+| 6 | `/mcp` | Admission before auth, then a request-local MCP server. |
+| 7 | Other paths | 404. Custom HTTP routes belong to the deployment. |
+
 
 Every response leaves through `withSecurityHeaders`: `nosniff`, a no-referrer
-policy, HSTS on HTTPS, and — on the operator shells — a nonce-based script CSP
-and framing denial. `test/server-route-contracts.test.ts` pins this ordering
+policy, HSTS on HTTPS, while the UI module adds a nonce-based script CSP and framing denial to its shells. `test/server-route-contracts.test.ts` pins this ordering
 and the exact refusal bodies; it exists because the ordering is invisible in
 any one file and a reordering reads like a harmless refactor.
 
-`/mcp` itself is four steps, in this order and for these reasons:
+`/mcp` itself is five steps, in this order and for these reasons:
 
 1. **Admit.** One permit from the deployment-wide FIFO pool, taken before auth
    so an unauthenticated flood costs a permit rather than a Clerk lookup
@@ -102,8 +99,7 @@ any one file and a reordering reads like a harmless refactor.
    than silently serving the full registry. Retiring a scoping boundary into
    fail-open is the one outcome worse than the 404.
 5. **Serve.** A fresh `McpServer` per request, the seven meta-tools registered
-   against the registry, the Apps shell resource registered (and
-   `resources/list` deliberately answering with nothing), and the response
+   against the registry and the response
    handed back.
 
 ## Layers below the meta-tools
@@ -115,7 +111,7 @@ owns or hands out, and a change usually belongs in exactly one of them:
 | --- | --- |
 | `src/registry.ts` | The connector set, identity-scoped views, personal storage partitions, address resolution, catalog TTL/persistence/completeness, refresh single-flight, connector health, per-connector call limiters, and drift. Construction-time refusals live here. |
 | `src/catalog-service.ts` | Request-local tool listing, search, and describe. It coalesces reads inside one request and opts agent reads into the runtime's deferred catalog channel when one exists. |
-| `src/invocation.ts` | One tool call: argument validation, call admission, per-attempt timeout, retry with the connector's own `Retry-After` honoured exactly or declined, result unwrapping, size capping, and the activity record. |
+| `src/invocation.ts` | One tool call: argument validation, call admission, one-attempt timeout, provider retry hints, result unwrapping, size capping, and the activity record. |
 | `src/catalog.ts` | Ranking, description summarizing, and the compact schema renderer discovery shows. |
 | `src/result-shapes.ts` | Bounded runtime-only inference and merging for output shapes learned from successful read-only calls whose providers declared none. |
 
@@ -127,6 +123,19 @@ read-only check. `test/execute.test.ts` asserts that parity directly, because
 the alternative — a sandbox path that quietly diverges — is how generated code
 would mint a capability.
 
+## Optional deployment modules
+
+`createConnecta` takes closed typed `ui`, `vault`, and `activity` slots. Factories
+live at `/ui`, `/credentials`, and `/activity`; bearer auth lives at
+`/auth/bearer`. Root exports the contracts, never these implementations. There
+is no module array, runtime registration, or plugin lifecycle.
+
+Core keeps connector discovery, the executor contract, invocation, permissions,
+and OAuth callback verification together. Optional modules contribute no
+runtime work when omitted. The UI supplies credential handoff URLs only while
+mounted. Status reads never initiate OAuth, and each lazy details request owns
+its downstream scope. See [operator UI](./operator-ui.md).
+
 ## Import-graph purity
 
 Nothing reachable from `src/index.ts` may import a `node:` builtin. The core is
@@ -144,8 +153,8 @@ specific to a direct Worker invocation carrying `ctx.access`.
 
 `test/purity.test.ts` walks the relative-import graph from `src/index.ts` and
 fails on (a) any `node:` specifier in a reachable file and (b) the Node
-adapter, file storage, QuickJS parent or child, or the Clerk adapter being
-reachable at all. `test/package-surface.test.ts` and
+adapter, file storage, QuickJS parent or child, auth adapters, UI bundle,
+encrypted vault implementation, or activity implementation being reachable at all. `test/package-surface.test.ts` and
 `scripts/check-package.mjs` guard the other half — that the published tarball
 matches the same boundary.
 
@@ -162,8 +171,7 @@ src/
   server.ts           route ordering, HTTPS upgrade, security wrapper
   routes/             one file per surface; shared.ts holds the auth gate
   meta-tools.ts       the six non-execute meta-tools over the registry
-  execute.ts          execute_code, the sandbox host bridge, emit and ui
-  apps-shell.ts       the one build-time MCP Apps template
+  execute.ts          execute_code, the sandbox host bridge, emitted media
   skills.ts           MCP instructions, the usage skill, connector guides
   registry.ts         connector set, addresses, health, call limiters
   catalog-service.ts  request-local catalog access, search, and describe
@@ -172,8 +180,7 @@ src/
   invocation.ts       one tool call, end to end
   catalog-drift.ts    vetted manifests and the counts a refresh produces
   credentials.ts      the AES-GCM connector vault over KVStorage
-  access-tokens.ts    operator-issued MCP bearer tokens
-  activity.ts         payload-free event contracts + best-effort recorder
+  activity.ts         optional history factory and best-effort recorder
   call-admission.ts   connector-partitioned downstream permits and budgets
   executor-admission.ts  the portable bounded queue both pools use
   ui.ts               the served operator shell and /ui/data payload
@@ -194,8 +201,7 @@ src/
   authenticated subject. Anything cached per request still dies with it.
   Putting a downstream client or credential on the wrong side of those lines
   is the highest-severity mistake available here.
-- **Route order is behavior.** Moving a built-in below the connector dispatch
-  hands a connector the ability to shadow it. Moving a mutation route below the
+- **Route order is behavior.** Moving a mutation route below the
   wildcard `OPTIONS` opts it into CORS preflight.
 - **Admission runs before auth, on purpose.** Reordering them to "authenticate
   first" makes the cheapest possible attack the most expensive request.
@@ -203,8 +209,7 @@ src/
   the connector limiters, then the executor. Node's `listen()` calls it on
   SIGTERM/SIGINT.
 - **Structural mistakes throw at construction.** A duplicate connector id, an
-  invalid admission rule, `accessTokens` without an interactive operator provider, a missing
-  executor: all refuse to boot. A deployment that starts in the wrong shape is
+  invalid admission rule, removed `accessTokens` option, or missing executor: all refuse to boot. A deployment that starts in the wrong shape is
   worse than one that does not start.
 
 ## Tests that enforce this

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
@@ -133,14 +125,12 @@ through the
 
 Worker-level Access runs before every connecta route. Consequently:
 
-- `/health`, operator pages, downstream OAuth callbacks, connector-owned
-  routes, and `/mcp` all require Access unless a more-specific hostname/path
+- `/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 connector that intentionally exposes a public webhook needs a
-  more-specific Access application and bypass policy. Do not bypass connecta's
-  OAuth discovery paths when Managed OAuth is enabled.
+- 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.
 
 The [Worker example](../examples/worker/) carries the complete deployment shape
 and the [upgrade guide](./upgrading.md#0200--0212) gives the reversible Clerk
@@ -157,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/call-admission.md

@@ -1,7 +1,7 @@
 # Downstream call admission
 
 One admitted MCP request can fan out into many downstream calls. A program
-calls tools from loops, from `connecta.batch`, and from branches the caller
+calls tools from loops, from parallel `connecta.call` calls, and from branches the caller
 never saw. The deployment-wide request pool
 ([request admission](./request-admission.md)) bounds the envelope; it cannot
 see anything inside it. A provider that publishes "60 requests per minute"
@@ -76,16 +76,15 @@ not be a way to reset a live budget. Exhausted partition capacity is
 
 The registry owns the limiter, and `InvocationService.invoke` acquires a permit
 immediately before `Connector.callTool` and releases it in `finally`. Both call
-paths — top-level `call_tool` and a program's `connecta.call` or
-`connecta.batch` — reach that same seam, so a program cannot buy itself a
+paths, top-level `call_tool` and program calls through `connecta.call`,
+reach that same seam, so a program cannot buy itself a
 second limit by taking the other route.
 
-- **A retry is another attempt.** It reacquires and can consume another budget
-  entry, because the provider counts it that way. Backoff never holds a
-  concurrency permit.
-- **A proactive short-window `rate_limited` refusal** participates in the
-  ordinary retry policy and counts as an attempt. Activity records the final
-  outcome and the attempt count.
+- **A caller retry is another call.** It reacquires and can consume another
+  budget entry. Connecta returns retry hints without waiting or retrying.
+- **A proactive short-window `rate_limited` refusal** returns its retry hint
+  without waiting or dispatching. Activity records one failed admission attempt;
+  a caller may reissue after the window.
 - **A queued cancellation consumes nothing.** It is removed from the queue with
   no rolling-window entry charged.
 - **Caller cancellation is terminal.** It is non-retryable, releases its
@@ -114,7 +113,7 @@ from "we are throttling ourselves".
 ## Enforcement scope
 
 This is deliberately **per-runtime**. It completely contains fan-out inside one
-request, including a wide `connecta.batch` in one Worker isolate. A rolling
+request, including parallel `connecta.call` calls in one Worker isolate. A rolling
 budget is exact inside one Node process or Worker isolate, and best-effort
 across isolates, replicas, and restarts.
 
@@ -139,5 +138,5 @@ typed error code.
 | Invariant | Suite |
 | --- | --- |
 | Independent partitions, exact rolling-window reset and retry, queued cancellation charging no budget, synchronous cancel during partition derivation, validated values snapshotted rather than read from mutable config, bounded partition state and contained `partitionKey` failures, empty and multi-rule policies refused | `test/call-admission.test.ts` (controller) |
-| One base-registry limiter shared by direct and program calls, batch bounds with input order preserved, cancellation threading, no dispatch or retry or health poisoning after cancellation, short proactive windows retried without poisoning health, payload-free `/health` aggregates | `test/call-admission.test.ts` (integration, Node + Workers) |
+| One base-registry limiter shared by direct and program calls, promise concurrency with input order preserved, cancellation threading, no dispatch or retry or health poisoning after cancellation, retry hints returned without waiting or poisoning health, payload-free `/health` aggregates | `test/call-admission.test.ts` (integration, Node + Workers) |
 | Where provider budgets are allowed to come from at all | [provider conventions P12](./provider-conventions.md#p12--declare-an-admission-budget-only-when-the-provider-documents-a-number), [provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md) |

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