@zackbart/connecta 0.22.3 → 0.24.0

package/ethos.md

@@ -1,48 +1,33 @@
 # connecta — ethos
 
-What connecta is, what it refuses to be, and the invariants every change must
-preserve. A contradiction needs a design decision, not a drive-by edit.
+Connecta’s scope, refusals, and invariants. Contradictions require a design decision.
 
 ## What this is
 
-- **One MCP endpoint, one programmable surface.** Every integration you chose
-  sits behind a capability catalog that agents reach by writing JavaScript,
-  ringed by a few explicit tools for the boundaries code must not cross.
-- **A deployment is config-as-code.** One tenant and connector set; principals
-  receive config-derived views.
-- **Curated when available, open when not.** Prefer a maintained prebuilt
-  connection; `remoteMcp()` and `api()` stay first-class for everything else.
-  Every path yields the same `Connector` with the same rules.
-- **Seven tools, an executor required.** The primary surface is a program, so
-  every deployment runs an executor and one without refuses to boot. A
-  capability earns a top-level tool only by being inexpressible as a program.
-- **Safe by default.** Only tools explicitly annotated read-only run without
-  crossing `call_destructive_tool`, where the host can ask a human. Approval is
-  the host's job; connecta makes the question visible.
-- **One fetch-native core, two runtimes.** Web APIs only in the core; Node
-  touches live behind explicit subpaths. Cloudflare Worker or Docker, your pick.
-- **Observable, actionable only over authentication material.** Operator pages
-  show status and payload-free activity and may rotate credentials, issue
-  tokens, and run OAuth. Declared capability they cannot touch.
+- **One MCP endpoint.** Agents reach configured connectors through JavaScript
+  and seven meta-tools. Every deployment requires an executor.
+- **Config-as-code.** One tenant and connector set; identities receive
+  config-derived views. Maintained providers, `remoteMcp()`, and `api()` obey
+  the same connector contract.
+- **Safe by default.** Only explicitly read-only tools run inside a program.
+  Others cross `call_destructive_tool`; the host owns human approval.
+- **One fetch-native core.** Web APIs support Node and Workers. Platform code
+  and optional features use explicit subpath imports.
+- **Human auth management.** Optional pages show status and payload-free history.
+  Explicit permissions allow credential changes and OAuth. Capabilities stay in code.
 
 ## What this isn't
 
-- **Not a platform.** No runtime registration, admin-editable capability,
-  policy engine, approvals, or pauses.
-- **Not a schema ingester.** No OpenAPI or GraphQL → tools.
-- **Not multi-tenant.** No accounts, groups, or sessions. Inbound auth owns
-  identity; personal state stays within one tenant.
-- **Not stateful.** No protocol sessions, no server push; scope resolves per
-  request.
-- **Not a nanny.** Credentials fail loudly at use; nothing probes one.
-- **Not a promise to strangers — yet.** Breaking changes are cheap; the version
-  number signals change, not stability.
+No runtime registration, admin-editable capabilities, policy engine, approvals,
+or pauses. No schema ingestion, accounts, groups, protocol sessions, or server
+push. Inbound providers own identity; personal state remains within one tenant.
+Credentials fail at use, without background probes. Breaking changes remain
+acceptable; version numbers signal change, not stability.
 
 ## Decisions
 
-Shapes considered and turned down. Proposing one again without a new argument
-is not allowed. Accepted designs live in their subsystem guide and the
-CHANGELOG, not here.
+Revisiting a verdict requires a new argument. Accepted designs live in
+subsystem guides and the CHANGELOG.
 
 | Decision | Verdict | Why |
 | --- | --- | --- |
@@ -50,10 +35,13 @@ CHANGELOG, not here.
 | Multi-tenancy / account model | refused | one deployment per tenant; inbound auth owns identity |
 | Policy engine, approvals, pauses | refused | the host asks the human; connecta only annotates |
 | Runtime connector registration | refused | config-as-code is the security model |
+| Optional deployment modules | accepted | explicit imports and typed config slots select UI, activity history, credential vault, and inbound auth; discovery, execution, invocation, and enforcement stay in core |
+| Generic plugin lifecycle or marketplace | refused | modules organize deployment code; runtime installation and discovery add no required behavior |
+| Connecta-issued access tokens | removed | inbound identity providers own client authentication; configured bearer auth remains an optional adapter |
 | Provider registry / marketplace | refused | prebuilt connections are imports; discovery happens in docs ([#297](https://github.com/zackbart/connecta/issues/297)) |
 | Expanded Notion page create/update options | refused | different workflows, not missing fields; use `api()` ([#408](https://github.com/zackbart/connecta/issues/408)) |
 | Protocol sessions & server push | refused | stateless per request |
-| Resources & prompts aggregation | refused | tools only; the Apps shell is the one `resources/read` carve-out ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Resources & prompts aggregation | refused | tools only; clients own presentation ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Elicitation passthrough | refused | no route through a stateless aggregator |
 | Repository formatter | refused | style is authored, not enforced |
 | Host-side projection of program results | refused | a program projects; a heuristic drops fields invisibly ([#223](https://github.com/zackbart/connecta/issues/223)) |
@@ -67,6 +55,11 @@ CHANGELOG, not here.
 | Legacy embedded `UIResource` delivery | refused | superseded upstream, rendered by no client we face ([#266](https://github.com/zackbart/connecta/issues/266)) |
 | Effect as the core effect system | refused | −4% of the core for +75 KB gzip and a second async paradigm; re-measure at v4 stable ([#470](https://github.com/zackbart/connecta/issues/470)) |
 | Shared bounded queue under both admission controllers | refused | built and measured −17 lines for a hook-parameterised abstraction ([#453](https://github.com/zackbart/connecta/issues/453)) |
+| MCP Apps rendering and `connecta.ui` | removed | clients render returned data |
+| Connector shortcut globals | removed | canonical addresses need no sanitization |
+| `connecta.batch` | removed | JavaScript promises suffice |
+| Automatic direct-call retries | removed | callers own retry timing |
+| Connector HTTP routes | removed | deployments own custom routes |
 | Caller-selected toolkits | removed | only config may derive an identity's connector view ([#178](https://github.com/zackbart/connecta/issues/178)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
@@ -75,14 +68,14 @@ CHANGELOG, not here.
 | Semantic tool search | gated | keyword search has not been shown to fail ([#27](https://github.com/zackbart/connecta/issues/27)) |
 | MRTR / `input_required` passthrough | gated | relayable statelessly; no host or downstream emits it yet ([#176](https://github.com/zackbart/connecta/issues/176)) |
 | Downstream `ttlMs` cache hints | gated | needs refresh-churn evidence ([#206](https://github.com/zackbart/connecta/issues/206)) |
-| Downstream MCP Apps template passthrough | gated | needs a downstream that ships one ([#266](https://github.com/zackbart/connecta/issues/266)) |
+| Downstream MCP Apps template passthrough | refused | clients own presentation; Connecta serves tools and data |
 | Worker Access inbound auth | provisional | Managed OAuth and Clerk migration need production evidence ([#506](https://github.com/zackbart/connecta/issues/506)) |
-| Program UI tool calls | removed | the read bridge added a second contract without improving agent data retrieval; views are display-only again ([#287](https://github.com/zackbart/connecta/issues/287), [#484](https://github.com/zackbart/connecta/issues/484)) |
+| Program UI tool calls | removed | duplicated calls without improving retrieval ([#287](https://github.com/zackbart/connecta/issues/287), [#484](https://github.com/zackbart/connecta/issues/484)) |
 
 ## Invariants
 
-One line each; the enforcing tests live beside the subsystem documentation.
-Breaking one is a design change wearing a disguise.
+Tests beside subsystem documentation enforce these invariants. Breaking one
+requires a design decision.
 
 - **Fail-closed read-only.** A missing, false, or contradictory annotation never gets the benefit of the doubt.
 - **Generated code cannot mint capabilities.** Admission, credentials, and classification are enforced below the sandbox.
@@ -94,9 +87,9 @@ Breaking one is a design change wearing a disguise.
 - **Credentials never leave the host.** Encrypted at rest, readable only by the owning connector and, for personal auth, its owning principal; rendered by nothing.
 - **Import-graph purity.** Nothing reachable from the root entry imports a `node:` builtin.
 - **The published surface is a boundary.** Heavyweight or platform-bound code goes behind an optional-peer subpath.
-- **Human routes manage auth, never capability.** Signed-in humans manage auth for visible connectors; operators also manage tokens and global activity.
+- **Human routes manage auth, never capability.** Visibility grants use, not credential administration. Shared and personal auth mutations require separate config-derived permissions, both denied by default. Activity has its own read permission.
+- **Omitted modules do no work.** Core imports no UI bundle, encrypted vault implementation, activity implementation, or bearer adapter. OAuth callbacks remain available without UI.
+- **Status reads do not start authorization.** OAuth starts through an explicit authorized action; loading the UI never creates a consent flow.
 - **Structural mistakes throw at construction.** Booting into the wrong shape is worse than not booting.
 
-Connecta began as a radical simplification of
-[executor](https://github.com/UsefulSoftwareCo/executor); this file is the
-record of that simplification holding.
+Connecta simplifies [executor](https://github.com/UsefulSoftwareCo/executor).

package/examples/worker/AGENTS.md

@@ -34,7 +34,9 @@ This repository is deployment configuration, not a copy of Connecta itself.
 - Prefer `api()` when the agent must see an exact reviewed capability set;
   `remoteMcp()` follows the downstream server's evolving tool catalog.
 - Use Access service credentials for `connecta doctor` and unattended clients.
-  A `cta_` token or static Connecta bearer cannot cross the Access edge alone.
+  A configured Connecta bearer cannot cross the Access edge alone. Connecta-issued
+  tokens are removed. UI, vault, and activity use explicit optional imports;
+  auth changes require code-derived shared or personal management permissions.
 - Run the repository's `npm run check:examples` after configuration changes.
   After deployment, connect both Claude and ChatGPT to `<PUBLIC_URL>/mcp` and
   complete their browser authorization flows before calling setup complete.

package/examples/worker/README.md

@@ -120,96 +120,80 @@ discover the skew in production ([#376](https://github.com/zackbart/connecta/iss
 no Clerk import, secret, package, or fallback provider. Docker deployments keep
 the Clerk path in the Node template.
 
-Then point an MCP client at `<PUBLIC_URL>/mcp`, and open `<PUBLIC_URL>/` for
-Connections. Credentials is at `/credentials`, named MCP access tokens are at
-`/tokens`, Activity is at `/activity`, and legacy `/ui` redirects to `/`. Each
-of those three appears in the nav only when this deployment can serve it — see
-the next section for what turns each one on.
-
-## The operator surface
-
-This example ships the whole operator feature set. Three quarters of it is on
-as deployed; the fourth needs a database, so it is commented in place.
-
-**Operator sign-in** is the `cloudflareAccessAuth()` entry in `src/index.ts`.
-Access authenticates before the Worker runs. A human Access identity can use
-MCP and human-management pages; a service-token identity can use MCP but cannot
-write a credential, run downstream OAuth, or issue a connecta token. Cloudflare
-still owns the outer application admission policy, but Connecta's user roster,
-connector access, and deployment roles stay in `src/index.ts`.
-
-**Several users** need no second auth system or Connecta account dashboard.
-Uncomment the `identity` block in `src/index.ts` to derive connector ids and
-deployment-operator membership from the Access principal. Connectors remain
-visible to everyone and every human remains an operator when that block is
-absent. A signed-in human may edit auth for every connector their view includes.
-Add `authScope: "personal"` when each user should connect a different downstream
-account; leave it shared only when any user with connector access may rotate the
-deployment-wide grant. Static headers stay shared because their value lives in
-deployment configuration. See [inbound identity](../../documentation/auth.md#principals-visibility-and-operators)
-for the resolver contract.
-
-**The credential vault** is `credentials: { encryptionKey: … }`, backed by the
-same KV namespace as everything else and encrypted with the
-`CREDENTIAL_ENCRYPTION_KEY` secret before a value reaches it. Generate one with:
+Then point an MCP client at `<PUBLIC_URL>/mcp`. The example explicitly enables
+`ui: operatorUi()`; open `<PUBLIC_URL>/` for Connections and each connection's
+authentication controls. There is no separate Credentials or Tokens tab.
+
+## Select optional modules
+
+`cloudflareAccessAuth()` reads trusted identity after Access admits the Worker
+request. Humans may use their code-derived connector view; service identities
+can use MCP but cannot manage personal or shared auth as an interactive human.
+Keep users, groups, and admission in Access. Connector visibility and management
+permissions belong in `src/index.ts`.
+
+`identity.connectorAccess` selects discoverable and callable connectors.
+`credentialAdministration` separately allows shared credential and OAuth
+management, while `personalConnection` allows a human to connect their own
+account. Both management permissions default to none. Grant the intended
+owner's shared permissions explicitly, and grant users personal permissions
+only for connectors configured with `authScope: "personal"`. Static headers
+remain deployment configuration. `activityAccess` governs global history reads.
+See [inbound identity](../../documentation/auth.md#principals-visibility-and-operators).
+
+### UI and encrypted credentials
+
+Import `operatorUi` from `@zackbart/connecta/ui` and set `ui: operatorUi()`.
+Branding belongs in `operatorUi({ branding })`. Omit the import and option to
+serve no UI routes; OAuth callbacks still work in core for authorized
+interactive MCP callers.
+
+Import `encryptedCredentialVault` from `@zackbart/connecta/credentials` and set
+`vault: encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY)` when
+the secret is configured. Keep this base64 32-byte key in Worker secrets:
 
 ```sh
 node -e "console.log(crypto.randomBytes(32).toString('base64'))"
 ```
 
-Leave the secret unset and the deployment still runs — `/credentials` stays
-read-only and connecta says so at startup. Keep the key in Worker secrets and
-nowhere near KV: it is the only thing that makes a copied namespace useless.
-Rotation takes effect on the next call, with no redeploy and no liveness probe,
-because credentials fail at use.
-
-The vault is ready here, and the Credentials page is still hidden, because that
-page lists connector credential slots rather than deployments. Neither
-connector in `src/index.ts` declares one — Notion carries a deployment-owned
-static header and echo has no secret — so nothing would be on the page. Add
-`credential: { label: "API token" }` to an `api()` connector (the commented
-shape on `echo` is exactly it) or use a provider connector such as `notion()`,
-which declares its own, and Credentials appears for a signed-in operator on the
-next load.
-
-**Access tokens** are `accessTokens: {}`. A signed-in human operator mints named,
-revocable Bearer tokens at `/tokens` for header-capable clients that will not do
-OAuth. Secrets are shown once and only their hashes enter KV; a lost token is
-reissued, never recovered. Note the KV caveat above — revocation is visible
-everywhere only as fast as the namespace converges.
-
-Worker-level Access still runs before these tokens. A `cta_…` token therefore
-does not reach connecta by itself; retain the feature as a rollback path or for
-a caller that already supplies separate Access service-token headers. Normal
-interactive MCP clients should use Managed OAuth, and unattended clients should
-use Access service tokens.
-
-**Activity** is the commented block in `src/index.ts` and the commented
-`d1_databases` binding in `wrangler.jsonc`; the section below creates the
-database and applies the schema.
-
-None of these change what agents can reach. Operator routes manage the
-authentication material behind capabilities `src/index.ts` already declares —
-never the connector set, the tool catalog, or its annotations.
-
-`connecta doctor` reports the same line here as for a deployment with none of
-this on: connector count, executor, seven tools. The executor it names is this
-one — `DynamicWorkerExecutor executed`, not the Node template's QuickJS, which
-is what doctor used to claim everywhere
-([#368](https://github.com/zackbart/connecta/issues/368)). Against Access it
-carries `CF_ACCESS_CLIENT_ID` and `CF_ACCESS_CLIENT_SECRET`, and the service
-identity learns the model-facing surface rather than deployment topology:
+Reuse the same key and KV namespace during upgrades. Without the secret, omit
+the vault; declared credential slots remain unmanageable. Keep the key outside
+KV because it protects a copied namespace. Credential replacement takes effect
+on the next call without redeploying; no liveness probe runs in the background.
+
+The shipped Notion connector uses a deployment-owned static header and echo
+needs no secret. To exercise vault controls, declare a `credential` slot on an
+`api()` connector or use a provider such as `notion()` that declares its own.
+Authorized users manage that slot inside the connection. Configuring a vault
+does not create credentials or permissions by itself.
+
+### Client authentication and activity
+
+Interactive MCP clients use Access Managed OAuth. Unattended clients use Access
+service tokens when needed. Connecta-issued `cta_` tokens and their management
+routes are removed; a configured Connecta bearer cannot cross the Access edge
+alone. See the [migration guide](../../documentation/upgrading.md#0240-optional-modules)
+if an older deployment still issues tokens.
+
+Activity uses `activityHistory({ store: d1ActivityStore(env.ACTIVITY_DB) })`
+from `@zackbart/connecta/activity`. Enable the database and bindings described
+below. Omit the module and store wiring to record no history and show no
+Activity tab. Diagnostics remain independent; `logger: "silent"` suppresses
+them explicitly.
+
+Verify MCP health and the exact seven tools with:
 
 ```sh
 CF_ACCESS_CLIENT_ID=… CF_ACCESS_CLIENT_SECRET=… \
   npx connecta doctor --url "$PUBLIC_URL"
 ```
 
-Confirm the operator surface the way an operator will: sign in at
-`<PUBLIC_URL>/` and check that Tokens is live. Credentials joins it
-once a connector declares a `credential` slot, and Activity once the D1 wiring
-below is on — the nav shows a page when the deployment can actually serve it,
-so a missing page is the honest report that its half is still off.
+Doctor reports the configured `DynamicWorkerExecutor`, not a presumed Node
+executor. Verify the UI separately as a human: check visible connections,
+explicit shared and personal auth permissions, and Activity only when enabled.
+The configured list loads before live connector checks; a slow provider must
+not prevent other connections from appearing. All capability and access changes
+still require a deployment-code change.
 
 ## Code mode
 
@@ -295,19 +279,19 @@ To enable it:
    the failure and returns the tool result unharmed — so the symptom is not an
    error your agent sees, it is an activity log that quietly stops recording.
 
-3. In `src/index.ts`, uncomment the `d1ActivityStore` import, the `ACTIVITY_DB`
-   field on `Env`, and the `activity` block — the three commented fragments
-   that together read:
+3. In `src/index.ts`, enable the `activityHistory` and `d1ActivityStore` imports,
+   the `ACTIVITY_DB` field on `Env`, and the `activity` option:
 
    ```ts
+   import { activityHistory } from "@zackbart/connecta/activity";
    import { d1ActivityStore } from "./d1-activity.js";
 
    createConnecta({
      // …
-     activity: {
+     activity: activityHistory({
        store: d1ActivityStore(env.ACTIVITY_DB),
        deploymentId: "production",
-     },
+     }),
    });
    ```
 

package/examples/worker/src/d1-activity.ts

@@ -2,7 +2,7 @@ import type {
   ActivityPage,
   ActivityStore,
 } from "@zackbart/connecta";
-import { InvalidActivityCursorError } from "@zackbart/connecta";
+import { InvalidActivityCursorError } from "@zackbart/connecta/activity";
 import {
   activityEventToRow,
   activityRowToEvent,

package/examples/worker/src/index.ts

@@ -1,3 +1,6 @@
+import { operatorUi } from "@zackbart/connecta/ui";
+// import { activityHistory } from "@zackbart/connecta/activity";
+import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
 /**
  * connecta on Cloudflare Workers.
  *
@@ -63,9 +66,10 @@ interface Env {
 }
 
 function build(env: Env) {
+  const storage = cloudflareKvStorage(env.CONNECTA_KV);
   return createConnecta({
     publicUrl: env.PUBLIC_URL,
-    storage: cloudflareKvStorage(env.CONNECTA_KV),
+    storage,
     executor: new DynamicWorkerExecutor({ loader: env.LOADER }),
     auth: [
       // Access owns admission policy. A human identity may use MCP and the
@@ -83,7 +87,7 @@ function build(env: Env) {
     //     principal?.id === "ACCESS_USER_UUID"
     //       ? ["notion", "echo"]
     //       : ["echo"],
-    //   operatorAccess: ({ id }) => id === "ACCESS_USER_UUID",
+    //   activityAccess: ({ id }) => id === "ACCESS_USER_UUID",
     // },
     // Connectors that declare a `credential` slot become editable by every
     // signed-in human who can see that connector at /credentials, encrypted
@@ -98,19 +102,20 @@ function build(env: Env) {
     // ready and the page empty. Declare a slot (see the commented shape on
     // `echo`, or use a provider connector like `notion()`, which declares its
     // own) and the page appears on the next load.
-    credentials: { encryptionKey: env.CREDENTIAL_ENCRYPTION_KEY },
+    vault: encryptedCredentialVault(storage, env.CREDENTIAL_ENCRYPTION_KEY),
     // Eligible human operators can create named, revocable MCP Bearer tokens
     // at /tokens. Under Worker-level Access those tokens are a rollback tool,
     // not standalone edge credentials: Access still runs before connecta.
-    accessTokens: {},
+    ui: operatorUi(),
+    identity: { credentialAdministration: () => "all", personalConnection: () => "all" },
     // Payload-free activity at /activity, off until a database exists to hold
     // it. Uncomment the `d1_databases` binding in wrangler.jsonc, apply the
     // schema in README.md § "Activity history", then these three lines and the
     // import above.
-    // activity: {
+    // activity: activityHistory({
     //   store: d1ActivityStore(env.ACTIVITY_DB),
     //   deploymentId: "production",
-    // },
+    // }),
     connectors: [
       remoteMcp("notion", {
         url: "https://mcp.notion.com/mcp",

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.22.3",
+  "version": "0.24.0",
   "type": "module",
   "sideEffects": false,
-  "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
+  "description": "One MCP to rule them all \u2014 a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",
   "license": "MIT",
   "engines": {
     "node": ">=22.0.0"
@@ -94,6 +94,22 @@
     "./providers/vercel": {
       "types": "./dist/providers/vercel.d.ts",
       "import": "./dist/providers/vercel.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "import": "./dist/ui.js"
+    },
+    "./credentials": {
+      "types": "./dist/credentials.d.ts",
+      "import": "./dist/credentials.js"
+    },
+    "./activity": {
+      "types": "./dist/activity.d.ts",
+      "import": "./dist/activity.js"
+    },
+    "./auth/bearer": {
+      "types": "./dist/auth/bearer.d.ts",
+      "import": "./dist/auth/bearer.js"
     }
   },
   "scripts": {

package/templates/node/AGENTS.md

@@ -12,12 +12,14 @@ This repository is deployment configuration, not a copy of Connecta itself.
   Do not copy or modify Connecta package internals here.
 - Prefer `api()` when the agent must see an exact reviewed capability surface;
   `remoteMcp()` follows the downstream server's evolving tool catalog.
-- The operator surface — Clerk sign-in, credential vault, access tokens,
-  activity — ships as commented blocks in `src/index.ts`. Enable one by
-  uncommenting it and setting the variables it names in `.env`, never by
-  inventing a parallel configuration path. `README.md` § "Turn on the operator
-  surface" is the walkthrough; `src/file-activity.ts` is the deployment-owned
-  activity store the activity block wires.
+- The UI, encrypted credential vault, and activity history use explicit module
+  imports and typed `ui`, `vault`, and `activity` options in `src/index.ts`.
+  Follow README "Select optional modules". Auth management requires explicit
+  `credentialAdministration` or `personalConnection` permissions; visibility
+  alone never grants it. Configured bearer auth is a client option, not a human
+  management identity. Connecta-issued access tokens are removed.
+  `src/file-activity.ts` remains the deployment-owned history store.
+
 - Run `npm run typecheck` after configuration changes. With the server running,
   run `CONNECTA_TOKEN=... npm run doctor` before calling setup complete.
 - `Dockerfile` and `docker-compose.yml` containerize *this* source; they are