@zackbart/connecta 0.15.1 → 0.16.1

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,9 +81,10 @@ 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)) |
+| 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`](https://github.com/zackbart/connecta/blob/main/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)) |
 | Surface consolidation to seven tools | accepted | `list_connectors`, `describe_tools`, and `batch_call` fold into the program surface, deleting the routing choice between direct calls, batches, discovery, and execution; `call_tool` stays because a simple call is not cheaper through code ([#224](https://github.com/zackbart/connecta/issues/224)) |
 | Classic (executor-free) surface | removed | supersedes its provisional retention under [#224](https://github.com/zackbart/connecta/issues/224) — an executor is mandatory, and a deployment without one refuses to boot rather than serving a fallback shape ([#273](https://github.com/zackbart/connecta/issues/273)) |
 | Connector shortcut namespaces in programs | accepted | sugar over canonical addressing, kept but frozen — every expansion invents a collision class `<connectorId>.<toolName>` already solved ([#223](https://github.com/zackbart/connecta/issues/223)) |
@@ -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,97 @@ 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
+```
+
+Both are optional peers of `@zackbart/connecta` — declared in its manifest,
+never installed with it, and each carrying the range this release supports.
+`@cloudflare/codemode` is the executor behind `execute_code`, published as
+`^0.4.4 || ^0.5.0`: install a version inside that and npm stays quiet, install
+one outside and npm says so at install time instead of leaving a Worker to
+discover the skew in production ([#376](https://github.com/zackbart/connecta/issues/376)).
+
+`@clerk/backend` is the 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 +153,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 +225,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.1",
   "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",
@@ -49,6 +46,7 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./package.json": "./package.json",
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
@@ -100,10 +98,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",
@@ -117,19 +116,23 @@
   },
   "peerDependencies": {
     "@clerk/backend": "^3.12.0",
+    "@cloudflare/codemode": "^0.4.4 || ^0.5.0",
     "quickjs-emscripten": "^0.32.0"
   },
   "peerDependenciesMeta": {
     "@clerk/backend": {
       "optional": true
     },
+    "@cloudflare/codemode": {
+      "optional": true
+    },
     "quickjs-emscripten": {
       "optional": true
     }
   },
   "devDependencies": {
     "@clerk/backend": "^3.12.0",
-    "@cloudflare/codemode": "^0.4.4",
+    "@cloudflare/codemode": "^0.5.0",
     "@cloudflare/vitest-pool-workers": "^0.18.8",
     "@cloudflare/workers-types": "^4.20250101.0 || ^5.0.0",
     "@playwright/test": "^1.62.0",
@@ -137,6 +140,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=

package/templates/node/AGENTS.md

@@ -6,13 +6,28 @@ This repository is deployment configuration, not a copy of Connecta itself.
 - Keep `executor: quickJsExecutor()` for the prescribed seven-tool code-first
   surface.
 - Keep credentials in environment variables or an external secret store.
-  Never commit `.env`, `.connecta-state.json`, tokens, or credential values.
+  Never commit `.env`, `.connecta-state.json`, `.connecta-activity.jsonl`,
+  tokens, or credential values.
 - Add application logic only inside deliberate `api()` connector handlers.
   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.
 - 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
+  the same deployment, not a second one. Configuration belongs in `.env` and
+  `src/index.ts`, never in a divergent container entrypoint.
+- Moving this deployment to a newer Connecta is its own procedure, and it is
+  not a re-`init` — `connecta init` refuses to merge into an existing path on
+  purpose. Follow
+  [the upgrade guide](https://github.com/zackbart/connecta/blob/main/documentation/upgrading.md),
+  which also ships at `node_modules/@zackbart/connecta/documentation/upgrading.md`.
 
 Do not add alternate entrypoints, policy layers, generated connector catalogs,
 or runtime connector registration. Keep the deployment small enough to review

package/templates/node/Dockerfile

@@ -0,0 +1,49 @@
+# This deployment, containerized. The build context is this directory: the
+# image installs @zackbart/connecta from the registry exactly like any other
+# consumer, so nothing here depends on the Connecta repository.
+#
+#   docker compose up -d --build
+FROM node:22-slim
+
+WORKDIR /app
+
+# `connecta init` deliberately leaves no lockfile — it rewrites the Connecta
+# version pin, and a lockfile shipped in the template would already disagree
+# with it. Without one the build resolves the pin itself, which is fine but not
+# reproducible. Run `npm install` on the host and commit the `package-lock.json`
+# it writes: the build context then carries it and every later build takes the
+# `npm ci` path. A lockfile written inside this layer stays inside the image.
+# Dev dependencies stay in: tsx runs src/index.ts directly, so the deployment
+# you review is the deployment that runs.
+COPY package.json package-lock.json* ./
+RUN if [ -f package-lock.json ]; then \
+      npm ci --include=dev; \
+    else \
+      npm install --include=dev --no-audit --no-fund; \
+    fi
+
+COPY tsconfig.json ./
+COPY src ./src
+
+# State lives on a mounted volume. The image owns the mount point so a fresh
+# named volume inherits an owner the non-root user can actually write to.
+RUN mkdir -p /data && chown -R node:node /data /app
+USER node
+
+ENV NODE_ENV=production
+ENV PORT=8787
+ENV CONNECTA_STATE_FILE=/data/connecta-state.json
+# Read only once the activity block in src/index.ts is uncommented; defaulted
+# here so history lands on the volume rather than inside the container layer.
+ENV CONNECTA_ACTIVITY_FILE=/data/connecta-activity.jsonl
+EXPOSE 8787
+
+# /health is always open, so the probe never carries the bearer token and
+# never leaves the container.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||8787)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+# `node --import tsx` keeps Node itself in the foreground: no wrapper process
+# swallows SIGTERM, so `docker compose down` stops the server promptly and the
+# QuickJS children go with it.
+CMD ["node", "--import", "tsx", "src/index.ts"]