@zackbart/connecta 0.15.1 → 0.16.0

package/documentation/request-admission.md

@@ -1,7 +1,169 @@
 # Request admission
 
-> **Stub.** The old manual was retired in the phase-1 docs restructure. This
-> document will be rewritten as an agent-facing guide — what the subsystem is
-> for, how to work on it, and what it must never do — once the ideas in
-> [ethos.md](../ethos.md) settle. The prior text lives in git history as
-> `docs/request-admission.md`.
+Connecta bounds work at the Web-standard request boundary — before inbound
+auth, before the MCP server exists, before any catalog is touched. A burst
+therefore meets an explicit active count and an explicit queue instead of
+asking traffic shape and the runtime allocator to pick the process high-water
+mark.
+
+There are two pools here and a third elsewhere. This guide covers the first
+two: the deployment-wide `/mcp` pool and the fallback code pool. Per-connector
+downstream bounds are [call admission](./call-admission.md), which is a
+different question — request admission bounds the whole MCP envelope, call
+admission bounds the individual `Connector.callTool` attempts fanned out inside
+it.
+
+## The pools
+
+Every non-preflight `/mcp` request takes one permit from a deployment-wide FIFO
+pool. Initialization, discovery, ordinary calls, and `execute_code` all pay it.
+A program then takes a *second* permit from the deliberately smaller code pool,
+so one request cannot trade ordinary capacity for an unbounded number of
+sandboxes.
+
+```ts
+const connecta = createConnecta({
+  admission: {
+    requests: { concurrency: 16, maxQueueSize: 32, queueTimeoutMs: 5_000, retryAfterMs: 1_000 },
+    code:     { concurrency: 2,  maxQueueSize: 8,  queueTimeoutMs: 5_000, retryAfterMs: 1_000 },
+  },
+  // …
+});
+```
+
+Those values are the defaults, and both pools are the same
+`AdmissionController` (`src/executor-admission.ts`) with different numbers.
+`maxQueueSize: 0` is the fail-fast shape. Every value is a finite whole number;
+concurrency and the queue timeout must be positive, while queue size and the
+retry hint may be zero. Invalid bounds throw at construction rather than
+silently removing the deployment's memory boundary — a pool that quietly became
+unbounded is worse than a deployment that refuses to boot.
+
+`admission.code` is a *fallback*. An executor that implements `acquire()` is an
+`AdmittingExecutor` and already owns a bounded pool, so its own settings win and
+connecta warns that `admission.code` was ignored. `quickJsExecutor()` is one of
+those: it defaults to one active execution and 32 queued callers, configured on
+the executor rather than here. Cloudflare's `DynamicWorkerExecutor` is not, so
+a Worker deployment gets the fallback pool wrapped around it at construction —
+which is also why `/health` always has a code-admission shape to report.
+
+The request pool is global FIFO across identities. It is a capacity boundary,
+not tenant fairness: one busy caller can occupy it. Per-tenant fairness needs a
+policy above connecta, and one deployment serves one audience anyway
+([`ethos.md`](../ethos.md)), so a global queue is not pretending to supply
+something it does not.
+
+## Admission before auth
+
+`/mcp` acquires its permit *before* running the auth gate. This looks backwards
+until you price it: authenticating first means an unauthenticated flood buys a
+Clerk network lookup per request, so the cheapest possible attack becomes the
+most expensive request the server can serve. Admitting first means it buys a
+queue slot and a 503.
+
+The permit is released with the response *body*, not when the handler returns.
+A slow client draining a large result still counts as active work, because its
+bytes and its socket still exist. `releaseAdmissionWithResponse` re-wraps the
+response stream to do this, absorbs a rejecting `cancel()` rather than leaking
+an unhandled rejection, and releases exactly once — release is idempotent, and
+`test/request-admission.test.ts` pins both the stream-cancel path and the
+double-release case.
+
+Every other route bypasses the pool entirely. `/health` and the operator
+surface stay responsive while MCP is saturated, which is the whole point: an
+operator diagnosing an overload must not have to queue behind it. `/health`
+names the exempt routes in `admission.reservedRoutes` so the claim is checkable
+from outside.
+
+## Overload, cancellation, shutdown
+
+A full queue or an expired queue deadline answers HTTP 503 with `Retry-After`,
+CORS headers, and a stable JSON-RPC error:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": null,
+  "error": {
+    "code": -32001,
+    "message": "Server capacity is exhausted. Retry later.",
+    "data": { "code": "server_overloaded", "retryable": true, "retryAfterMs": 1000 }
+  }
+}
+```
+
+`Retry-After` is that hint rounded up to at least one whole second. It is
+advice, not a reservation. Shutdown uses `-32002` / `server_shutting_down` and
+is not retryable. Code-pool overload never reaches this layer: it surfaces as
+an ordinary MCP tool error with `executor_overloaded`, `retryable: true`, and
+the executor's own `retryAfterMs`.
+
+A cancelled queued request is removed immediately and never receives a later
+permit — cancelling and then being admitted would hold capacity for a caller
+that is gone. An admitted request keeps its permit until its body completes,
+errors, or is cancelled.
+
+`connecta.close()` closes both queues before releasing executor resources:
+queued and future MCP work is rejected with `server_shutting_down` while
+admitted work drains. Node's `listen()` calls it on SIGTERM or SIGINT, stops
+accepting connections, drains, and enforces `shutdownTimeoutMs` (10 s default)
+— SIGTERM arrives on every `docker compose up` recreate, and Node's default
+response to it is to die mid-request.
+
+## What admission is not
+
+The Node adapter's `maxBodyBytes` (10 MiB default) is a separate ingress guard.
+It caps the HTTP body while constructing the Web `Request`, which happens
+*before* the portable `/mcp` boundary can run. Admission bounds MCP, auth,
+catalog, and response work; it is not a byte budget for many simultaneous slow
+or near-limit uploads. Hostile public traffic wants an ingress proxy with a
+body-rate limit in front, and `maxBodyBytes` set to the smallest value the
+deployment actually needs.
+
+The rejection warning is rate-limited to one per second, and each line reports
+how many were suppressed since the last one. The `/health` totals count every
+rejection, so the log is a sample and the counters are the record. Queue waits
+log at debug level. Nothing on this path records or exposes request bodies,
+tool arguments, identities, or results.
+
+## Observations
+
+`/health` exposes payload-free snapshots under `admission.requests`,
+`admission.code`, and `admission.downstreamCalls`. The first two carry
+configured bounds, current active and queued counts, cumulative
+admitted/queued/rejected/cancelled/closed totals, and queue-wait count, total,
+and maximum. The request policy is labelled `global-fifo`; downstream policy is
+labelled `connector-partitioned-per-runtime`. An executor that owns its own
+pool and exposes no snapshot reports `{ managedByExecutor: true }`.
+
+With `execute_code({ diagnostics: true })`, a caller sees the same split from
+the inside: `admissionMs` is time spent waiting for a permit and `connectorMs`
+is the admitted attempt.
+
+## Measuring capacity
+
+`npm run load:admission` builds the package, then starts server and generator
+in separate processes over real loopback TCP, warms a 10,000-tool catalog,
+verifies every returned value, and records throughput, p50/p95/p99, server-only
+peak RSS, RSS after forced GC, and live heap after GC. Each matrix cell gets a
+fresh server so an earlier allocator high-water mark cannot contaminate the
+next baseline; the three-round soak deliberately reuses one, because allocator
+high-water retention and a live-object climb look identical in a single run and
+different across three.
+
+`CONNECTA_LOAD_CATALOG_SIZE`, `CONNECTA_LOAD_CONCURRENCY`, and
+`CONNECTA_LOAD_MAX_QUEUE_SIZE` change catalog size, server concurrency, and
+queue depth. The script prints its own numbers; no baseline is checked in,
+deliberately. A laptop matrix is an example capacity profile, not a portable
+SLO, and downstream payload size moves it more than any setting here does — pin
+a runner before enforcing a regression ratio, and measure the connector mix the
+deployment actually runs.
+
+## Tests that enforce this
+
+| Invariant | Suite |
+| --- | --- |
+| FIFO bounds, active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown | `test/executor-admission.test.ts` (Node + Workers) |
+| `/mcp` bounded before auth, stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, the separate fallback code pool | `test/request-admission.test.ts` |
+| A client disconnect propagating through the Web `Request` into a program's connector call, releasing both permits | `test/node.test.ts` |
+| The `/health` admission payload alongside the drift counts | `test/catalog-drift.test.ts`, `test/server.test.ts` |

package/documentation/rich-output-design.md

@@ -208,5 +208,4 @@ count of what was discarded (`M4`).
 
 The implementation issue carries these as acceptance criteria; the clauses
 fold into `code-mode.md` under a new "Emitted output" section when it closes,
-and the test-map row in [`operations.md`](./operations.md) lands with the
-suite.
+and the suite takes its row in the [test map](./operations.md#the-test-map).

package/documentation/stripe.md

@@ -158,6 +158,14 @@ serves, an unclassified and unannotated `create_customer` lands on the approval
 path. Expect the undocumented Treasury tools Stripe alludes to to arrive
 unclassified as well — annotated ones will be taken at their word.
 
+The upshot is that this account's tool list is not a fixed set, and the usage
+guide tells the agent so: search this connector for what it actually exposes
+rather than assuming a documented tool is present. The guide also names the id
+discipline the downstream schemas cannot enforce — Stripe ids are typed
+prefixes (`cus_`, `sub_`, `ch_`, `pi_`, `in_`, `acct_`), a plausible-looking one
+belongs to a different object or to nobody, and the id a write takes comes from
+`stripe_api_search` or a list read rather than from a guess.
+
 Stripe publishes no stability or deprecation policy for this tool set and
 invites tool requests by email, so treat the list as unversioned. `get_balance_summary`
 is Treasury, which Stripe labels public preview and gates behind an access
@@ -200,3 +208,10 @@ about rather than read:
   are Stripe's documented API conventions; how they thread through the generic
   tools' arguments is not documented. The guide states them because an agent
   that ignores them is wrong either way.
+
+## Conventions
+
+This connection is audited against
+[the provider conventions](./provider-conventions.md). Its verdict per
+convention, including every recorded exception, is the Stripe section of
+[the provider audit](./provider-audit.md).

package/ethos.md

@@ -38,22 +38,22 @@ order, and amending it is a design decision, not a drive-by edit.
 - **One fetch-native core, two runtimes.** The same code runs unchanged on
   Cloudflare Workers and in Node — a Worker or a Docker stack, your pick. Web
   APIs only in the core; Node touches live behind explicit subpaths.
-- **Observable, never administrable.** Operator pages show connector status,
-  masked credentials, and payload-free activity. They can rotate a secret;
-  they cannot add a connector, change policy, or alter what an agent can call.
+- **Observable, actionable only over authentication material.** Operator pages
+  show connector status, masked credentials, and payload-free activity — and
+  they act: rotate a credential, issue or revoke an access token, run a
+  downstream OAuth flow. Declared capability is what they cannot touch.
 
 ## What this isn't
 
 - **Not a platform.** No runtime connector registration, no admin UI that
-  changes behavior, no policy engine, no approvals, no pauses.
+  changes declared capability, no policy engine, no approvals, no pauses.
 - **Not a schema ingester.** No OpenAPI or GraphQL → tools. Generated tool
   sprawl is the disease the meta-tools treat, not a feature to add.
 - **Not multi-tenant.** No accounts dimension, no per-user credential store,
   no org hierarchy. Two accounts on one service are two connector instances.
 - **Not stateful.** No protocol sessions, no server push. Scope resolves per
   request — which is also where the MCP spec itself has now arrived.
-- **Not a nanny.** Credentials are stored safely and fail loudly at use;
-  connecta doesn't probe them behind your back.
+- **Not a nanny.** Credentials fail loudly at use; connecta never probes one.
 - **Not a promise to strangers — yet.** Built for its author's deployments
   first, published openly. Breaking changes are cheap and the version number
   signals change, not stability.
@@ -71,6 +71,7 @@ proposing one without a new argument is not.
 | Runtime connector registration | refused | config-as-code is the security model |
 | Prebuilt connections as the preferred authoring path | accepted | an a-la-carte provider constructor, imported and constructed in the deployment file, encodes maintained defaults for providers connecta actually uses — preferred *when maintained*, with no promise of one per provider; it returns exactly one ordinary `Connector` with no extra privileges — never a bundle, a group, a preset, or a registry — its tools are hand-written or proxied from a downstream MCP catalog, never generated from a schema document; its vetted annotations classify what the downstream leaves unannotated and otherwise preserve explicit annotations, with one fail-closed exception: a release-reviewed destructive classification outranks a contradictory downstream `readOnlyHint: true`, because Connecta has independently established that the tool mutates existing state; `remoteMcp()` and `api()` stay first-class ([#297](https://github.com/zackbart/connecta/issues/297), [#315](https://github.com/zackbart/connecta/issues/315)) |
 | Guarded raw REST escape hatches in a prebuilt connection | accepted | a large, fast-moving provider cannot be honestly represented by a small frozen list: a GET-only tool may expose provider-relative reads, while JSON mutations and explicit-content uploads stay separate and always cross the destructive boundary; the connector owns authentication, rate limits, error mapping, URL confinement, and safe method classification, while the provider token remains the capability boundary — this is not schema ingestion, runtime connector registration, or permission widening |
+| Hosted-provider drift detection during catalog refreshes | accepted | a vetted classification is a claim about somebody else's catalog, and an allowlist nobody can tell is stale is an allowlist that is wrong — so each maintained hosted-MCP proxy ships the tool names, classifications, and (once a release records them) schemas it reviewed, and compares them against the live listing *inside* a catalog refresh the deployment already asked for; the boundary is the piggyback itself, which is what keeps this from being proactive credential liveness wearing a new hat ([#179](https://github.com/zackbart/connecta/issues/179)): no scheduled job, no background request, no credential probe, and not one byte of network traffic that would not have happened anyway; what it produces is four counts — unclassified additions, names no longer served, explicit annotation conflicts, schema changes — on connector status, `connecta doctor`, and one payload-free activity event with nowhere to put a tool name or a schema; the two read surfaces answer for the runtime that served the refresh, because the observation is isolate-local and only the activity event is durable, and unknown tools already fail closed, so drift costs approval round trips and stale guidance rather than capability ([#343](https://github.com/zackbart/connecta/issues/343)) |
 | Provider registry / integration marketplace | refused | prebuilt connections are imports, not listings; discovery happens in documentation, never at runtime ([#297](https://github.com/zackbart/connecta/issues/297)) |
 | Protocol sessions & server push | refused | stateless per request |
 | Resources & prompts aggregation | refused | tools only; connecta's own Apps shell is the one `resources/read` carve-out ([#266](https://github.com/zackbart/connecta/issues/266)) |
@@ -80,6 +81,7 @@ proposing one without a new argument is not.
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Agent credential recovery | accepted | one `auth_required` route through `authorize_connector`; only an operator handles secrets ([#192](https://github.com/zackbart/connecta/issues/192)) |
 | Operator-issued MCP access tokens | accepted | named, revocable authentication gives header-capable clients a small alternative to OAuth; tokens identify callers but never scope tools or become operator credentials |
+| Operator boundary reworded: authentication material, never declared capability | accepted | supersedes "observable, never administrable", which had stopped describing the surface: operator routes already rotate credentials, issue and revoke access tokens, and drive downstream OAuth, each under its own accepted row, and the owner has decided the surface stays actionable — so the boundary now says what is actually true, that operator routes may manage authentication material for capabilities declared in deployment configuration and may not change the connector set, the declared tool catalog or annotations, requested OAuth scopes, admission policy, authorization rules, or caller tool scope; the claim is deliberately about *declared* capability, and twice so, because replacing an API token with a broader-scoped one widens downstream reach and no browser page can honestly promise otherwise, and because a remote MCP server's catalog is discovered rather than declared — connecta declares the connector, its credential slot, and its admission policy, while the tools that server serves are its own answer, so storing a credential or finishing an OAuth flow can legitimately take an `mcp()` connector from no tools to N, which is discovery arriving, not an operator editing the deployment ([#338](https://github.com/zackbart/connecta/issues/338)) |
 | Structured result surface | accepted | canonical `structuredContent` plus complete compact `content`; summary-only text is gated on host-forwarding evidence ([#191](https://github.com/zackbart/connecta/issues/191)) |
 | Code mode (`execute_code`) | accepted | the primary read, discovery, and composition surface: smaller serialized definitions, far smaller results once composition and projection happen before the model sees them, and a cold-start model that read the interface without help ([exploration](./documentation/code-first-exploration.md), [#224](https://github.com/zackbart/connecta/issues/224)) |
 | Code-first as the default; the eval gate retired | accepted | owner decision, 2026-07-30: one operator, no deploy-time flip; [`eval/code-first-gate`](./eval/code-first-gate/README.md) survives as measurement, but nothing waits on its verdict ([#222](https://github.com/zackbart/connecta/issues/222), [#224](https://github.com/zackbart/connecta/issues/224)) |
@@ -132,8 +134,11 @@ Breaking one is not a bug fix — it is a design change wearing a disguise.
   `node:` builtin.
 - **The published surface is a boundary.** Heavyweight or platform-bound code
   goes behind an optional-peer subpath, never into core.
-- **No runtime admin.** If a browser could change what an agent can reach,
-  that feature is a non-goal wearing a disguise.
+- **Operator routes manage authentication material, never declared
+  capability.** Authenticating a declared capability is allowed; the connector
+  set, declared catalog and annotations, OAuth scopes, admission, authorization
+  rules, and caller tool scope take a config edit. A downstream catalog is
+  discovered, not declared — remote MCP tools appear when its credential does.
 - **Structural mistakes throw at construction.** A deployment that boots into
   the wrong shape is worse than one that refuses to boot.
 

package/examples/worker/README.md

@@ -8,7 +8,7 @@ and requires the Workers Paid plan.
 This is also the **starting template for a deployment**: a real deployment
 should be its own repository that pins an exact `@zackbart/connecta` version and
 owns only its connector configuration, auth policy, domain, bindings,
-migrations, and secrets. See [deployment architecture](../../documentation/operations.md).
+migrations, and secrets. See [the Cloudflare guide](../../documentation/cloudflare.md).
 
 ## Files
 
@@ -41,6 +41,7 @@ wrangler secret put SUPPORT_TOKEN                # one headless client
 wrangler secret put EXEC_TOKEN                   # another headless client
 wrangler secret put CLERK_SECRET_KEY
 wrangler secret put DOWNSTREAM_TOKEN
+wrangler secret put CREDENTIAL_ENCRYPTION_KEY   # base64 32-byte AES key
 wrangler deploy
 ```
 
@@ -49,9 +50,91 @@ Enable Dynamic Client Registration on the Clerk instance (OAuth Applications →
 DCR) so Claude/Cursor can self-register — full walkthrough in
 [setting up Clerk](../../documentation/auth.md).
 
+### Copied into its own repository
+
+The `npm install` above is the connecta repository's, which already has every
+dependency this file imports. A copy with its own `package.json` installs three
+things, because two of them are not part of connecta and never install with it:
+
+```sh
+npm install @zackbart/connecta @cloudflare/codemode @clerk/backend
+```
+
+`@cloudflare/codemode` is the executor behind `execute_code`, and
+`@clerk/backend` is the optional peer behind `@zackbart/connecta/auth/clerk` —
+which `src/index.ts` imports at the top level, so wrangler must resolve it at
+build time. Miss it and the build stops at
+`Could not resolve "@clerk/backend"`, which is a missing peer rather than a
+broken example. Drop `clerkAuth` from `auth` if this deployment has no operator
+sign-in, and the peer goes with it — but read
+[the operator surface](#the-operator-surface) first, because a deployment
+without it can never write a credential or issue an access token.
+
 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 `/`.
+`/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 `clerkAuth` entry in `src/index.ts`, alongside two
+static bearers. The split is deliberate: a bearer is a client key that may call
+tools and read connector status, while writing a credential or issuing an
+access token requires an interactive Clerk identity. Narrow who that can be
+with `allowedDomains`, or with a `gate` for anything a domain cannot express.
+
+**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:
+
+```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 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.
+
+**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)). It carries a bearer, and a
+bearer learns the model-facing surface rather than the deployment's
+configuration topology. 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.
 
 ## Code mode
 
@@ -64,20 +147,19 @@ The required Worker Loader binding is checked into `wrangler.jsonc`:
 ```
 
 `src/index.ts` constructs `DynamicWorkerExecutor` from `env.LOADER` and serves
-the seven-tool surface. A deployment copied into its own repository must also
-install the executor package:
-
-```sh
-npm install @cloudflare/codemode
-```
+the seven-tool surface. The executor package is one of the installs a copied
+deployment owns — see
+[copied into its own repository](#copied-into-its-own-repository).
 
 ## Activity history (optional)
 
 `src/d1-activity.ts` is a complete `ActivityStore` over D1 — keyset paging on
-`(occurred_at_ms, id)` plus a batched retention pass — but it is **not wired
-into `src/index.ts`**, so the example deploys without a database. To enable it:
+`(occurred_at_ms, id)` plus a batched retention pass — but the wiring in
+`src/index.ts` is **commented out**, so the example deploys without a database.
+To enable it:
 
-1. Create the database and bind it in `wrangler.jsonc`:
+1. Create the database and uncomment the `d1_databases` binding in
+   `wrangler.jsonc`, pasting in the id it prints:
 
    ```sh
    wrangler d1 create connecta-activity
@@ -137,7 +219,9 @@ into `src/index.ts`**, so the example deploys without a database. 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. Pass the store to `createConnecta`:
+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:
 
    ```ts
    import { d1ActivityStore } from "./d1-activity.js";

package/examples/worker/src/index.ts

@@ -6,16 +6,25 @@
  * namespace. The required Worker Loader binding in wrangler.jsonc backs the
  * seven-tool surface.
  *
+ * The operator surface is wired here except for activity history, which needs
+ * a database this example does not create for you: sign-in, the credential
+ * vault, and access-token issuance are on, and activity is three commented
+ * lines below. README.md § "The operator surface" walks through all four.
+ *
  * Setup (this example has no package.json of its own — it self-references the
  * installed `@zackbart/connecta` package):
  *   1. `npm install` in the connecta package root (../../ from here) so the
- *      package import and wrangler resolve.
+ *      package import and wrangler resolve. A copy in its own repository
+ *      installs `@zackbart/connecta @cloudflare/codemode @clerk/backend`
+ *      instead — the last two are not part of connecta, and the Clerk import
+ *      below is an optional peer wrangler resolves at build time.
  *   2. Create a KV namespace and put its id in wrangler.jsonc under `kv_namespaces`.
  *   3. Set secrets:
  *        wrangler secret put SUPPORT_TOKEN
  *        wrangler secret put EXEC_TOKEN
  *        wrangler secret put CLERK_SECRET_KEY
  *        wrangler secret put DOWNSTREAM_TOKEN
+ *        wrangler secret put CREDENTIAL_ENCRYPTION_KEY
  *      and CLERK_PUBLISHABLE_KEY + PUBLIC_URL as plain vars in wrangler.jsonc.
  *   4. Enable Dynamic Client Registration in the Clerk dashboard
  *        (OAuth Applications -> DCR toggle) so Claude/Cursor can self-register.
@@ -32,6 +41,8 @@ import {
 } from "@zackbart/connecta";
 import { clerkAuth } from "@zackbart/connecta/auth/clerk";
 import { cloudflareKvStorage } from "./cloudflare-kv.js";
+// Activity history, off by default because it needs a D1 database.
+// import { d1ActivityStore } from "./d1-activity.js";
 
 interface Env {
   CONNECTA_KV: KVNamespace;
@@ -41,8 +52,16 @@ interface Env {
   EXEC_TOKEN: string;
   CLERK_PUBLISHABLE_KEY: string;
   CLERK_SECRET_KEY: string;
+  /**
+   * Base64 32-byte AES key encrypting operator-managed credentials in KV.
+   * Unset means no vault: /credentials stays read-only and connecta says so at
+   * startup. Never put it in KV — it is what protects KV.
+   */
+  CREDENTIAL_ENCRYPTION_KEY: string;
   DOWNSTREAM_TOKEN: string;
   PUBLIC_URL: string;
+  /** Uncomment with the `d1_databases` binding to enable activity history. */
+  // ACTIVITY_DB: D1Database;
   /**
    * Worker Loader binding (wrangler.jsonc `worker_loaders`) powering
    * execute_code. Dynamic Workers require the Workers Paid plan.
@@ -73,9 +92,30 @@ function build(env: Env) {
         // allowedDomains: ["acme.com"],
       }),
     ],
+    // Connectors that declare a `credential` slot become editable at
+    // /credentials, encrypted with this key before anything reaches KV. A
+    // saved replacement takes effect on the next call — no redeploy, and no
+    // liveness probe: credentials fail at use.
+    //
+    // The key is the vault, not the page: /credentials is a list of connector
+    // slots, so it stays hidden until a connector declares one. Neither
+    // connector below does — Notion here carries a deployment-owned static
+    // header and echo has no secret at all — so this example ships the vault
+    // 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 },
     // Eligible Clerk operators can create named, revocable MCP Bearer tokens
     // at /tokens. Secrets are shown once; only their hashes enter KV.
     accessTokens: {},
+    // 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: {
+    //   store: d1ActivityStore(env.ACTIVITY_DB),
+    //   deploymentId: "production",
+    // },
     connectors: [
       remoteMcp("notion", {
         url: "https://mcp.notion.com/mcp",
@@ -87,6 +127,11 @@ function build(env: Env) {
       }),
       api("echo", {
         description: "Echo — text transforms",
+        // What a vault-backed connector adds — an operator edits this slot at
+        // /credentials and the handler reads it with
+        // `await ctx.credential?.get()`, so the secret never lives in source
+        // or in a Worker variable:
+        //   credential: { label: "API token" },
         tools: [
           {
             name: "shout",

package/examples/worker/wrangler.jsonc

@@ -7,7 +7,8 @@
   "observability": { "enabled": true },
 
   // Plain vars. Secrets (SUPPORT_TOKEN, EXEC_TOKEN, CLERK_SECRET_KEY,
-  // DOWNSTREAM_TOKEN) are set with `wrangler secret put <NAME>`, not here.
+  // CREDENTIAL_ENCRYPTION_KEY, DOWNSTREAM_TOKEN) are set with
+  // `wrangler secret put <NAME>`, not here.
   "vars": {
     "PUBLIC_URL": "https://connecta.example.workers.dev",
     "CLERK_PUBLISHABLE_KEY": "pk_test_replace-me"
@@ -18,6 +19,18 @@
     { "binding": "CONNECTA_KV", "id": "replace-with-kv-namespace-id" }
   ],
 
+  // Activity history. Create with `wrangler d1 create connecta-activity`,
+  // paste the id, apply the schema in README.md, then uncomment the matching
+  // lines in src/index.ts. Off by default so this example deploys without a
+  // database.
+  // "d1_databases": [
+  //   {
+  //     "binding": "ACTIVITY_DB",
+  //     "database_name": "connecta-activity",
+  //     "database_id": "replace-with-d1-database-id"
+  //   }
+  // ],
+
   // Required by execute_code; Dynamic Workers use the Workers Paid plan.
   "worker_loaders": [{ "binding": "LOADER" }]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.15.1",
+  "version": "0.16.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.",
@@ -31,10 +31,7 @@
   "files": [
     "bin",
     "dist",
-    "src",
-    "assets",
     "documentation",
-    "examples/node",
     "examples/worker",
     "templates",
     "AGENTS.md",
@@ -100,10 +97,11 @@
     "check:docs": "node scripts/check-doc-links.mjs",
     "check:lint": "oxlint -D correctness --report-unused-disable-directives .",
     "check:unused": "knip --include dependencies,unlisted,exports,nsExports,types,nsTypes",
-    "check:examples": "tsc -p tsconfig.examples.node.json && tsc -p tsconfig.examples.worker.json",
+    "check:examples": "tsc -p tsconfig.template.node.json && tsc -p tsconfig.examples.worker.json",
     "check:security": "npm audit --omit=dev --audit-level=moderate",
     "check:package": "node scripts/check-package.mjs",
     "load:admission": "npm run build && node scripts/admission-load.mjs",
+    "drift:check": "tsx scripts/drift-check.mjs",
     "check": "npm run check:docs && npm run check:operator-ui && npm run check:lint && npm run check:unused && npm run typecheck && npm run test && npm run build && npm run check:examples",
     "release:check": "npm run check && npm run check:security && npm run check:package",
     "prepack": "npm run check",
@@ -137,6 +135,7 @@
     "esbuild": "^0.28.0",
     "knip": "^6.29.0",
     "oxlint": "^1.76.0",
+    "preact": "^10.29.8",
     "quickjs-emscripten": "^0.32.0",
     "tsx": "^4.23.1",
     "typescript": "^5.6.0",

package/templates/node/.dockerignore

@@ -0,0 +1,10 @@
+# The image installs its own dependencies and never needs local state or
+# secrets in the build context.
+node_modules
+.git
+.env
+.connecta-state.json
+.connecta-activity.jsonl
+*.log
+Dockerfile
+docker-compose.yml

package/templates/node/.env.example

@@ -1,5 +1,42 @@
-# Required. Use a long random value and keep it out of source control.
-CONNECTA_TOKEN=replace-me
+# Required, and deliberately empty. Both Compose and src/index.ts refuse to
+# start while it is, so a copied .env cannot become a running deployment on a
+# placeholder printed in this template. Use a long random value and keep it out
+# of source control:
+#   node -e "console.log(crypto.randomBytes(32).toString('base64url'))"
+CONNECTA_TOKEN=
 
-# Optional. Defaults to 8787.
+# Optional. Defaults to 8787. Compose publishes this port on the host too.
 PORT=8787
+
+# Optional. The origin this deployment answers on, once it answers on more
+# than this machine: downstream OAuth calls back to
+# <PUBLIC_URL>/oauth/callback/<connectorId>. Defaults to http://localhost:<PORT>.
+PUBLIC_URL=
+
+# Optional. Where fileStorage keeps downstream-OAuth tokens and catalogs.
+# Defaults to ./.connecta-state.json locally and /data/connecta-state.json in
+# the container — keep the container path under /data so state lands on the
+# named volume and survives a rebuild.
+CONNECTA_STATE_FILE=
+
+# --- Operator surface ---------------------------------------------------
+# Each of these is read only once the matching block in src/index.ts is
+# uncommented. Setting one on its own changes nothing.
+
+# Operator sign-in with Clerk. Only a signed-in operator may write a credential
+# or issue an access token; the bearer above is a client key, not an admin key.
+# Also run `npm install @clerk/backend` — it is an optional peer.
+CLERK_PUBLISHABLE_KEY=
+CLERK_SECRET_KEY=
+
+# Credential vault. Base64-encoded 32-byte AES key encrypting the values an
+# operator saves at /credentials. Generate one with:
+#   node -e "console.log(crypto.randomBytes(32).toString('base64'))"
+# Keep it here or in a secret store — never in the state file it protects, and
+# never in source control. Losing it makes stored credentials unreadable.
+CONNECTA_CREDENTIAL_KEY=
+
+# Payload-free activity history. Defaults to ./.connecta-activity.jsonl locally
+# and /data/connecta-activity.jsonl in the container — same reasoning as the
+# state file: keep it under /data so history survives a rebuild.
+CONNECTA_ACTIVITY_FILE=