@zackbart/connecta 0.28.1 → 0.30.0

package/templates/node/README.md

@@ -1,11 +1,20 @@
 # Connecta deployment
 
-This is the prescribed Node deployment — the only one. It runs locally from
-source and, unchanged, as a container. Install and run it:
+Agent setup guide for the Node deployment and its Docker packaging.
+For cross-platform setup and upgrades, use [Deploying Connecta](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md).
+For connector changes, use [Integrating services](https://github.com/zackbart/connecta/blob/main/documentation/integrating.md).
+The [agent index](https://github.com/zackbart/connecta/blob/main/documentation/README.md) routes endpoint use and package
+maintenance. This README and [local agent instructions](./AGENTS.md) own the
+runnable steps for a copied Node deployment.
+
+This is the prescribed Node deployment. It runs locally from source and as
+a container. Install, provision a machine token, then start it:
 
 ```sh
 npm install
-CONNECTA_TOKEN=dev-token npm start
+npm run --silent provision-token -- "local-machine"
+# Save the returned cta_ token privately. It is shown only once.
+npm start
 ```
 
 The manifest approves only `esbuild@0.28.2` to run its install script. `tsx`
@@ -15,8 +24,39 @@ warning, and npm 12 does not block the script. A later esbuild version needs a
 new explicit review and approval; do not replace the pinned entry with a broad
 package-name approval.
 
-Then point an MCP client at `http://localhost:8787/mcp` with
-`Authorization: Bearer dev-token`.
+Point an MCP client at `http://localhost:8787/mcp` with
+`Authorization: Bearer <returned-cta-token>`. `CONNECTA_TOKEN` is a client and
+doctor variable only. Setting it never configures server authentication.
+
+`accessTokens(storage)` is always installed. With no stored tokens and no
+Clerk keys, the server can start and answer `/health`, but every MCP request
+is refused. There is no open startup or configured static bearer fallback.
+
+## Provision machine tokens
+
+Run `npm run --silent provision-token -- "machine-name"` from this project
+on a trusted machine. `src/provision-token.ts` imports the installed package's
+`AccessTokenManager`, then calls `manager.create(name, "local-provisioning")`
+on `sqliteStorage(openSqlite(process.env.CONNECTA_DATABASE || "./.connecta.sqlite"))`.
+The server uses that same database path. If you override it, use the same
+`CONNECTA_DATABASE` for provisioning and startup:
+
+```sh
+export CONNECTA_DATABASE=/absolute/path/connecta.sqlite
+npm run --silent provision-token -- "build-agent"
+npm start
+```
+
+The local commands read the process environment; they do not load `.env`.
+Compose reads `.env` for the container commands below. Keep the returned
+secret in a client secret store and out of source control and logs. Each run
+creates a new token; it cannot recover an old secret. Only the hash persists.
+The token is unbound to a human principal and has no interactive management
+authority. Its name is a label, and deployment identity and pool rules decide
+its access on every request. To revoke it locally, use `manager.list()` to
+find its id, then `manager.revoke(id, "local-provisioning")` against that same
+storage. An explicitly permitted Clerk operator can also manage tokens.
+Never expose this provisioning script as an HTTP route or run it at startup.
 
 ## Run it in Docker
 
@@ -24,20 +64,48 @@ Same source, same configuration, one long-lived service:
 
 ```sh
 cp .env.example .env
-# edit .env — set CONNECTA_TOKEN to a long random value
-
-docker compose up -d --build
+# edit .env for the database path and any optional modules
+docker compose build
+docker compose run --rm --no-deps connecta npm run --silent provision-token -- "container-machine"
+# Save the returned cta_ token privately for clients and doctor.
+docker compose up -d
 ```
 
-`CONNECTA_TOKEN` ships empty on purpose: `up` fails on it until you set it,
-rather than starting a deployment whose bearer is a value published in this
-template. Everything else in `.env.example` has a working default.
+The provisioning container writes through the installed package API into the
+same named volume and `CONNECTA_DATABASE` as the service. An empty volume
+admits no machine client. Compose never passes `CONNECTA_TOKEN` to the server;
+no environment value can substitute for a stored token.
 
 Compose reads `.env`, publishes `PORT` (8787 by default), and keeps state on
 the named volume `connecta-state`, mounted at `/data`. `docker compose down`
 stops the service and keeps state; `down -v` wipes it. `/health` is always
 open, so the container's health probe never carries the bearer token.
 
+## Storage
+
+Every piece of state lives in one SQLite file, `CONNECTA_DATABASE`
+(`./.connecta.sqlite` locally, `/data/connecta.sqlite` in the container):
+downstream OAuth grants, sealed vault credentials, catalogs, result paging,
+access tokens and activity. `@zackbart/connecta/sqlite` uses
+Node's built-in `node:sqlite` (Node 22.13 or later), creates its tables on
+first use, and commits one row per write. Back it up as one file, together
+with its `-wal` file while the server runs. Node 22 and 23 print an
+experimental-feature warning for `node:sqlite` once at startup.
+
+Upgrading from 0.28, which kept state in `.connecta-state.json`: stop the
+server, then copy the old file into the database once, before the first start:
+
+```sh
+npx connecta migrate-state .connecta-state.json .connecta.sqlite
+```
+
+In the container, run it against the volume, e.g. `docker compose run --rm
+connecta npx connecta migrate-state /data/connecta-state.json
+/data/connecta.sqlite`. It copies every live entry with its expiry, keeps any
+key the database already holds, and never changes the old file; delete that
+once the deployment is verified. The 0.28 activity log
+(`.connecta-activity.jsonl`) is not imported; history starts fresh.
+
 A build with no lockfile in the context resolves the pinned Connecta version
 itself, and a lockfile npm writes inside the image never reaches this project.
 So commit the `package-lock.json` that the `npm install` above wrote on this
@@ -46,20 +114,19 @@ reproducible `npm ci` path.
 
 ## Select optional modules
 
-For scheduled artifact pages, uncomment the `artifacts()` module and hourly
-`setInterval` block in `src/index.ts`. The module uses the same CAS-capable
-state file and exposes `runDue()` for the timer; core starts no job on its own.
-Each tick starts at most 10 due pages. Refresh programs can call only shared
-connectors' explicitly read-only tools within the program owner's current
-grants. Revoking refresh or pool access stops future runs. Failed runs leave the last good data
-and mark the viewer stale.
+Every optional module is code in `src/connecta.config.ts`, switched by an
+environment variable: set it and the module is on, leave it empty and it is
+off. `.env.example` lists each one, and `npm run typecheck` checks every module
+whether or not it is switched on.
 
 The template explicitly enables `ui: operatorUi()` from
-`@zackbart/connecta/ui`. Open `http://localhost:8787/` and supply the configured
-bearer to inspect Connections. Omit that option and import for an API-only
+`@zackbart/connecta/ui`. Open `http://localhost:8787/` and supply a
+stored machine token to inspect Connections. Sign in with Clerk for human
+connection management. Omit that option and import for an API-only
 server. OAuth callbacks remain in core even with no UI.
 
-The page labels whether each tool runs in programs or needs approval. For
+The page labels each tool as a read or write. Trusted programs may write;
+read-only pools use `call_destructive_tool`, with approval controlled by the host. For
 classified connection failures it offers a fixed repair prompt, and its
 endpoint section has client setup commands for `/mcp` and any pool available
 to the signed-in identity. Those commands contain no bearer token.
@@ -69,21 +136,37 @@ their URLs, `description`, `pageTitle`, `favicon`, and `theme`. The theme is
 five tokens — `accent`, `radius`, `fontFamily`, `monoFamily`, and
 `colorScheme` — and every other color is mixed from them, so one accent themes
 the whole page. A value that fails its gate falls back to the default, and the
-startup warning names it. `src/index.ts` carries the full shape commented out
-above `ui: operatorUi()`.
-
-Connection management needs an interactive identity. A configured bearer is a
-client key and never authorizes browser credential mutations. To enable Clerk:
-
-```sh
-npm install @clerk/backend
-```
-
-Set `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`, enable the corresponding
-`clerkAuth` import and auth entry in `src/index.ts`, and set `PUBLIC_URL`.
-Enable Dynamic Client Registration on the Clerk instance if MCP clients should
-sign in with OAuth. Connecta no longer issues named client access tokens; keep
-the configured bearer only for clients that need it.
+startup warning names it. Pass it to `operatorUi()` in `src/connecta.config.ts`.
+
+Connection management needs an interactive identity. A machine access token
+never authorizes browser credential mutations. `@clerk/backend`
+ships as a dependency of this template. To enable Clerk, set both
+`CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY` (one without the other refuses to
+start) and set `PUBLIC_URL`.
+Enable `aud_claim_enabled: true` in Clerk's instance OAuth application settings
+(`PATCH /v1/instance/oauth_application_settings` in Clerk's Backend API), then
+read the setting back. Both JWT and opaque OAuth tokens are supported.
+Leave `allowedOAuthClientIds` omitted or `[]` to require bound tokens.
+
+Connecta's protected-resource metadata advertises the exact public `/mcp` or
+`/mcp/<pool>` URL as `resource` and Clerk as the authorization server. MCP
+hosts use that URL in their standard OAuth `resource` parameter. Enable the
+Clerk registration methods your hosts need, including DCR or CIMD. Reconnect
+after enabling audience issuance and confirm the new token's `aud` matches
+the metadata URL, MCP initialization succeeds, and refresh retains the same
+audience. Clerk's raw verification response exposes `aud` for opaque tokens.
+
+An explicit `allowedOAuthClientIds` list is only a fallback for unbound tokens
+from clients dedicated to this deployment. It never overrides a mismatched
+audience. New DCR registrations need new entries, so prefer audience binding
+for standard host onboarding. Clerk session tokens work only on operator
+routes. [Inbound auth](https://github.com/zackbart/connecta/blob/main/documentation/auth.md#clerk-oauth-tokens-and-operator-sessions)
+explains configuration, verification, and fixed rejection reason codes.
+Machine clients use connecta-issued `cta_` access tokens
+through `accessTokens(storage)`, which `src/connecta.config.ts` configures on
+the database. Grant explicit `identity.accessTokenManagement` permissions to
+let a signed-in human mint them. Trusted local provisioning above works without
+Clerk and never requires opening the server.
 
 Set the code-owned identity resolvers deliberately. `connectorAccess` governs
 use; `credentialAdministration` permits shared-auth changes, and
@@ -94,20 +177,19 @@ connector where each person should connect their own downstream account.
 
 ### Credential vault
 
-Import `encryptedCredentialVault` from `@zackbart/connecta/credentials`, then
-set `vault: encryptedCredentialVault(storage, credentialKey)` — `storage` is
-the `fileStorage` binding `src/index.ts` already passes to `createConnecta`. Set
-`CONNECTA_CREDENTIAL_KEY` to a base64 32-byte AES key:
+Set `CONNECTA_CREDENTIAL_KEY` to a base64 32-byte AES key and
+`src/connecta.config.ts` passes `encryptedCredentialVault(storage, key)` over the
+same database:
 
 ```sh
 node -e "console.log(crypto.randomBytes(32).toString('base64'))"
 ```
 
-Keep this key outside the state file. Losing it makes saved values unreadable;
+Keep this key outside the database. Losing it makes saved values unreadable;
 upgrades must reuse it. The shipped `time` connector declares no credential
 slot. Add `credential: { label: "API token" }` to an `api()` connector and read
-it through `await ctx.credential?.get()`, or use a provider such as `notion()`
-that declares its own slot. Authorized humans manage the slot inside that
+it through `await ctx.credential?.get()`, or use Notion's explicit
+`surface: "api"` integration interface, which declares its own slot. Authorized humans manage the slot inside that
 connection on `/`; there is no separate Credentials tab.
 
 In 0.25.0, this vault also seals downstream OAuth tokens on their first read.
@@ -122,26 +204,26 @@ static credential recovery reports unavailable instead of offering a dead link.
 
 ### Activity history and diagnostics
 
-Import `activityHistory` from `@zackbart/connecta/activity` and wire the template's
-`fileActivityStore` through `activity: activityHistory({ store })`. The Activity
-tab appears for authorized readers when the store supports listing. Omit this
-option and its store wiring to record no activity.
+Set `CONNECTA_ACTIVITY=on` and `src/connecta.config.ts` records activity with
+`sqliteActivityStore(database, { retentionDays: 90 })` from
+`@zackbart/connecta/sqlite`. The Activity tab appears for authorized readers.
+Leave it empty to record no activity.
 
-`src/file-activity.ts` belongs to the deployment. It appends payload-free events
-and periodically retains the newest 5,000, allowing a small slack window between
-rewrites. Docker stores the log on the state volume. It records no arguments,
-results, generated code, or raw errors. Adjust retention in that file if needed.
+Activity shares the one database file. Each write prunes a bounded batch of
+rows older than `retentionDays`, so nothing has to be scheduled; change the
+number in `src/connecta.config.ts`. It records no arguments, results, generated code, or raw errors.
 
 Diagnostics are independent. Keep the default logger or provide your own;
 `logger: "silent"` suppresses diagnostic output explicitly.
 
 The UI displays connections and current permissions. Configuration still owns
-the connector set, tool definitions, and access rules. There is no token tab,
-team roster, or policy editor.
+the connector set, tool definitions, and access rules. Access token management
+requires explicit Clerk operator permission. There is no team roster or policy editor.
 
 ## Deployment contract
 
-- Edit `src/index.ts` for connectors, auth, storage, and the public URL.
+- Edit `src/connecta.config.ts` for connectors, auth, storage, the public URL,
+  and optional modules. `src/index.ts` only starts it.
 - Keep the required `executor: quickJsExecutor()` configuration; a deployment
   without an executor refuses to boot.
 - Keep secrets in environment variables or an external secret store.
@@ -156,19 +238,19 @@ Verify a change with:
 ```sh
 npm run typecheck
 # In another terminal, while the server is running (npm start or compose):
-CONNECTA_TOKEN=dev-token npm run doctor
+CONNECTA_TOKEN='cta_REPLACE_WITH_RETURNED_SECRET' npm run doctor
 ```
 
-Doctor checks health, the executor, and the exact prescribed seven-tool
+Doctor checks health, the executor, and the exact prescribed six-tool
 model-facing surface by running a harmless sandbox program. It reads the bearer
 from `CONNECTA_TOKEN`; it never accepts the secret as a command-line argument.
 Remote URLs must use HTTPS.
 
 A fully-wired deployment reports exactly the same line as a bare one —
-connector count, QuickJS executed, seven tools, plus any catalog drift:
+connector count, QuickJS executed, six tools, plus any catalog drift:
 
 ```text
-Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed seven-tool surface.
+Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed six-tool surface.
 ```
 
 `QuickJS` is this deployment's sandbox, reported by the deployment itself —

package/templates/node/docker-compose.yml

@@ -1,6 +1,8 @@
-# One service, no database: state is the fileStorage JSON on a named volume.
+# One service, no database server: state is one SQLite file on a named volume.
 #
-#   cp .env.example .env    # then set CONNECTA_TOKEN
+#   cp .env.example .env
+#   docker compose build
+#   docker compose run --rm --no-deps connecta npm run --silent provision-token -- "machine-name"
 #   docker compose up -d --build
 #
 # Compose reads `.env` from this directory, so one file configures both the
@@ -14,23 +16,20 @@ services:
     ports:
       - "${PORT:-8787}:${PORT:-8787}"
     environment:
-      # Refuse to start without inbound auth — the same rule src/index.ts
-      # enforces, stated early enough that `up` fails before the build.
-      CONNECTA_TOKEN: ${CONNECTA_TOKEN:?set CONNECTA_TOKEN in .env}
+      # accessTokens(storage) is always installed; an empty database is closed.
+      # CONNECTA_TOKEN belongs to clients and is never configured on this server.
       PORT: ${PORT:-8787}
       # Downstream OAuth calls back to this origin. Unset is fine until this
       # deployment is reachable from somewhere other than this machine.
       PUBLIC_URL: ${PUBLIC_URL:-}
-      # Keep the state file under /data so it lands on the volume below.
-      CONNECTA_STATE_FILE: ${CONNECTA_STATE_FILE:-/data/connecta-state.json}
-      # Operator surface. Passed through so the matching blocks in
-      # src/index.ts work in the container the moment they are uncommented;
-      # until then these are unread. The activity log joins the state file on
-      # the volume for the same reason it does.
+      # Keep the database under /data so it lands on the volume below.
+      CONNECTA_DATABASE: ${CONNECTA_DATABASE:-/data/connecta.sqlite}
+      # Optional modules. Each switches its module in src/connecta.config.ts
+      # on when set and off when empty.
       CLERK_PUBLISHABLE_KEY: ${CLERK_PUBLISHABLE_KEY:-}
       CLERK_SECRET_KEY: ${CLERK_SECRET_KEY:-}
       CONNECTA_CREDENTIAL_KEY: ${CONNECTA_CREDENTIAL_KEY:-}
-      CONNECTA_ACTIVITY_FILE: ${CONNECTA_ACTIVITY_FILE:-/data/connecta-activity.jsonl}
+      CONNECTA_ACTIVITY: ${CONNECTA_ACTIVITY:-}
     volumes:
       - connecta-state:/data
     restart: unless-stopped

package/templates/node/package.json

@@ -4,18 +4,20 @@
   "version": "0.0.0",
   "type": "module",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.13.0"
   },
   "allowScripts": {
     "esbuild@0.28.2": true
   },
   "scripts": {
     "doctor": "connecta doctor",
+    "provision-token": "tsx src/provision-token.ts",
     "start": "tsx src/index.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.28.1",
+    "@clerk/backend": "^3.12.0",
+    "@zackbart/connecta": "0.30.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/connecta.config.ts

@@ -0,0 +1,119 @@
+/**
+ * This deployment's configuration: connectors, authentication, storage, public
+ * origin, and the optional operator modules. Add application logic only inside
+ * deliberate api() connector handlers.
+ *
+ * Every optional module is type-checked code switched by the environment
+ * (.env.example lists each variable): set it and the module is on, leave it
+ * empty and it is off. README.md § "Select optional modules" covers each one.
+ * Connecta validates the result when src/index.ts starts it; a mistake refuses
+ * to boot rather than running in a shape nobody chose.
+ */
+import { api, defineConfig } from "@zackbart/connecta";
+import { activityHistory } from "@zackbart/connecta/activity";
+import { accessTokens } from "@zackbart/connecta/auth/access-tokens";
+import { clerkAuth } from "@zackbart/connecta/auth/clerk";
+import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
+import { quickJsExecutor } from "@zackbart/connecta/quickjs";
+import { openSqlite, sqliteActivityStore, sqliteStorage } from "@zackbart/connecta/sqlite";
+import { operatorUi } from "@zackbart/connecta/ui";
+
+/** The variables this file reads (see .env.example). */
+export interface Env {
+  PORT?: string;
+  PUBLIC_URL?: string;
+  CONNECTA_DATABASE?: string;
+  CLERK_PUBLISHABLE_KEY?: string;
+  CLERK_SECRET_KEY?: string;
+  CONNECTA_CREDENTIAL_KEY?: string;
+  CONNECTA_ACTIVITY?: string;
+}
+
+export default defineConfig((env: Env) => {
+  // Empty is unset: an untouched `.env` passes through Compose as "".
+  const set = (name: keyof Env) => env[name] || undefined;
+  const publicUrl = set("PUBLIC_URL") ?? `http://localhost:${set("PORT") ?? 8787}`;
+
+  // Operator sign-in. Only a Clerk-authenticated human may manage connector
+  // credentials. Machine access tokens never grant interactive authority.
+  // Both keys, or neither.
+  const clerkPublishableKey = set("CLERK_PUBLISHABLE_KEY");
+  const clerkSecretKey = set("CLERK_SECRET_KEY");
+  if (Boolean(clerkPublishableKey) !== Boolean(clerkSecretKey)) {
+    throw new Error("Operator sign-in needs both CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY.");
+  }
+  const clerk =
+    clerkPublishableKey && clerkSecretKey
+      ? clerkAuth({
+          publishableKey: clerkPublishableKey,
+          secretKey: clerkSecretKey,
+          // Enable Clerk aud_claim_enabled; hosts request the MCP URL as
+          // resource. Bound JWT and opaque tokens are the default.
+          publicUrl,
+          // Restrict who may sign in with `allowedDomains: ["acme.com"]`, or
+          // `gate` for anything a domain cannot express. Absent, every
+          // authenticated Clerk user is admitted.
+        })
+      : undefined;
+  // Every piece of state — OAuth grants, sealed credentials, catalogs,
+  // paging, access tokens, activity — lives in this one file.
+  const database = openSqlite(set("CONNECTA_DATABASE") ?? "./.connecta.sqlite");
+  const storage = sqliteStorage(database);
+
+  // The credential vault. A connector that declares a `credential` slot
+  // becomes editable inside its connection on /, encrypted in the database
+  // with this key — so keep the key out of that file and out of source.
+  const credentialKey = set("CONNECTA_CREDENTIAL_KEY");
+
+  return {
+    storage,
+    publicUrl,
+    // Required: model-written programs run in a bounded QuickJS child.
+    executor: quickJsExecutor(),
+    auth: clerk ? [clerk] : [],
+    // Always installed: an empty database refuses machine requests. Provision
+    // locally with `npm run provision-token -- "machine-name"`, or grant an
+    // interactive human `identity.accessTokenManagement` for later issuance.
+    // v0.23 client tokens survive `connecta migrate-state` on this storage.
+    accessTokens: accessTokens(storage),
+    // Connection management permissions default to none, so the template
+    // grants them. Split members from operators with `connectorAccess`,
+    // `activityAccess`, and `accessTokenManagement`, each derived from the
+    // authenticated identity and never from an MCP argument.
+    identity: {
+      credentialAdministration: () => "all",
+      personalConnection: () => "all",
+    },
+    vault: credentialKey ? encryptedCredentialVault(storage, credentialKey) : undefined,
+    // Payload-free activity history at /activity: who called what, when, how
+    // long it took, and whether it worked. Each write prunes rows older than
+    // `retentionDays`; the number is yours to choose.
+    activity:
+      set("CONNECTA_ACTIVITY") === "on"
+        ? activityHistory({
+            store: sqliteActivityStore(database, { retentionDays: 90 }),
+            deploymentId: "production",
+          })
+        : undefined,
+    // The operator UI at /. Branding is code too: operatorUi({ branding }).
+    ui: operatorUi(),
+    connectors: [
+      api("time", {
+        description: "Time — current timestamp",
+        // A connector that needs an operator-managed secret declares a slot —
+        //   credential: { label: "API token" },
+        // — and reads it inside a handler with `await ctx.credential?.get()`.
+        // Telling the time needs no secret, so this one declares nothing.
+        tools: [
+          {
+            name: "get_now",
+            description: "Return the current time as an ISO 8601 timestamp.",
+            inputSchema: { type: "object", properties: {} },
+            annotations: { readOnlyHint: true },
+            handler: async () => ({ now: new Date().toISOString() }),
+          },
+        ],
+      }),
+    ],
+  };
+});

package/templates/node/src/index.ts

@@ -1,159 +1,14 @@
-import { bearerToken } from "@zackbart/connecta/auth/bearer";
-import { operatorUi } from "@zackbart/connecta/ui";
-// import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
-// import { activityHistory } from "@zackbart/connecta/activity";
 /**
- * Prescribed Connecta deployment.
- *
- * Keep this file as deployment configuration: connectors, authentication,
- * storage, and public origin. Add application logic only inside deliberate
- * api() connector handlers.
- *
- * The optional modules — operator sign-in, credential vault, activity — ship
- * here as commented configuration, because each needs a secret or a retention
- * decision this file cannot make for you. Uncomment the block you want;
- * README.md § "Select optional modules" walks through all three.
- *
- * Environment (see .env.example):
- *   CONNECTA_TOKEN           required inbound bearer token
- *   PORT                     listen port (default 8787)
- *   PUBLIC_URL               public origin; downstream OAuth calls back to it
- *   CONNECTA_STATE_FILE      fileStorage path (the container points it at /data)
- *   CLERK_PUBLISHABLE_KEY    operator sign-in, once the Clerk block is on
- *   CLERK_SECRET_KEY         operator sign-in, once the Clerk block is on
- *   CONNECTA_CREDENTIAL_KEY  vault key, once the credentials block is on
- *   CONNECTA_ACTIVITY_FILE   activity log, once the activity block is on
+ * Prescribed Connecta deployment. Configuration lives in src/connecta.config.ts;
+ * this file only starts it. The environment it reads is in .env.example.
  */
-import { api, createConnecta } from "@zackbart/connecta";
-import { fileStorage, listen } from "@zackbart/connecta/node";
-import { quickJsExecutor } from "@zackbart/connecta/quickjs";
-// import { accessTokens } from "@zackbart/connecta/auth/access-tokens";
-// import { artifacts, kvArtifactStore } from "@zackbart/connecta/artifacts";
-// Operator sign-in. Needs `npm install @clerk/backend` — it is an optional
-// peer, so it does not install with Connecta.
-// import { clerkAuth } from "@zackbart/connecta/auth/clerk";
-// Payload-free activity history, kept beside the state file.
-// import { fileActivityStore } from "./file-activity.js";
+import { createConnecta } from "@zackbart/connecta";
+import { listen } from "@zackbart/connecta/node";
+import connectaConfig from "./connecta.config.js";
 
-const token = process.env.CONNECTA_TOKEN;
-if (!token) {
-  throw new Error(
-    "CONNECTA_TOKEN is required. Refusing to start without inbound auth.",
-  );
-}
-const port = Number(process.env.PORT ?? 8787);
-// Empty is unset: an untouched `.env` passes through Compose as "", and an
-// empty state path or public origin is worse than the local default.
-const stateFile = process.env.CONNECTA_STATE_FILE || "./.connecta-state.json";
-const publicUrl = process.env.PUBLIC_URL || `http://localhost:${port}`;
-const storage = fileStorage(stateFile);
-// Optional artifact pages and refresh jobs use the same CAS-capable state file:
-// const artifactModule = artifacts({ store: kvArtifactStore(storage) });
-
-// Operator sign-in. A bearer token is a client key: it may call tools and read
-// connector status, but only a Clerk-authenticated human may write a visible
-// connector's credential. Without this block the operator UI still renders —
-// an operator pastes the bearer to read it — and connections stay read-only.
-// const clerkPublishableKey = process.env.CLERK_PUBLISHABLE_KEY;
-// const clerkSecretKey = process.env.CLERK_SECRET_KEY;
-// if (!clerkPublishableKey || !clerkSecretKey) {
-//   throw new Error(
-//     "Operator sign-in needs CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY.",
-//   );
-// }
-
-const connecta = createConnecta({
-  storage,
-  // Reuse this storage to keep v0.23 client tokens without rotating secrets.
-  // accessTokens: accessTokens(storage),
-  auth: [
-    bearerToken(token, { subjectId: "operator" }),
-    // clerkAuth({
-    //   publishableKey: clerkPublishableKey,
-    //   secretKey: clerkSecretKey,
-    //   publicUrl,
-    //   // Restrict who may sign in — or use `gate` for anything a domain
-    //   // cannot express. Absent, every authenticated Clerk user is admitted.
-    //   // allowedDomains: ["acme.com"],
-    // }),
-  ],
-  // Code-owned identity resolvers. Connection management permissions default to
-  // none, so the template grants them. The commented pair is the optional
-  // member/operator split for Clerk-backed deployments: connector access is
-  // derived from the authenticated identity and cannot be selected by an MCP
-  // argument. Leave them commented for the all-visible,
-  // all-interactive-users-read-activity behavior.
-  identity: {
-    credentialAdministration: () => "all",
-    personalConnection: () => "all",
-    // connectorAccess: ({ principal }) =>
-    //   principal?.id === "user_admin" ? "all" : ["time"],
-    // activityAccess: ({ id }) => id === "user_admin",
-    // accessTokenManagement: ({ principal }) => principal?.id === "user_admin",
-  },
-  publicUrl,
-  // Required: model-written programs run in a bounded QuickJS child.
-  executor: quickJsExecutor(),
-  // Credential vault. A connector that declares a `credential` slot becomes
-  // editable inside its connection on /, and its value is encrypted in the state file
-  // with this key — so keep the key out of that file and out of source:
-  //   node -e "console.log(crypto.randomBytes(32).toString('base64'))"
-  // Rotating a credential takes effect on the next call; no restart.
-  // vault: encryptedCredentialVault(storage, process.env.CONNECTA_CREDENTIAL_KEY!),
-  // Payload-free activity history at /activity: who called what, when, how
-  // long it took, and whether it worked. Never arguments, results, generated
-  // code, or raw error messages. Commented because retention is yours to
-  // choose — see src/file-activity.ts.
-  // activity: activityHistory({
-  //   store: fileActivityStore(
-  //     process.env.CONNECTA_ACTIVITY_FILE || "./.connecta-activity.jsonl",
-  //   ),
-  //   deploymentId: "production",
-  // }),
-  // The operator UI at /. Its branding is code, like everything else here:
-  // name, owner, description, favicon, and five theme tokens that every
-  // other color is mixed from. A value that fails its check falls back to the
-  // default, and the startup warning names it.
-  // ui: operatorUi({
-  //   branding: {
-  //     productName: "Acme Tools",
-  //     ownerName: "Acme",
-  //     theme: {
-  //       accent: "#2f5fe0", // hex only
-  //       radius: 10, // pixels, or a CSS length such as "0.5rem"
-  //       fontFamily: "Inter, system-ui, sans-serif",
-  //       monoFamily: "ui-monospace, monospace",
-  //       colorScheme: "system", // or "light" | "dark"
-  //     },
-  //   },
-  // }),
-  ui: operatorUi(),
-  // artifacts: artifactModule,
-  connectors: [
-    api("time", {
-      description: "Time — current timestamp",
-      // A connector that needs an operator-managed secret declares a slot —
-      //   credential: { label: "API token" },
-      // — and reads it inside a handler with `await ctx.credential?.get()`.
-      // Telling the time needs no secret, so this one declares nothing.
-      tools: [
-        {
-          name: "get_now",
-          description: "Return the current time as an ISO 8601 timestamp.",
-          inputSchema: { type: "object", properties: {} },
-          annotations: { readOnlyHint: true },
-          handler: async () => ({ now: new Date().toISOString() }),
-        },
-      ],
-    }),
-  ],
-});
+const config = connectaConfig(process.env);
+const connecta = createConnecta(config);
+const port = Number(process.env.PORT || 8787);
 
 listen(connecta, port);
-console.log(`connecta listening on port ${port}; MCP at ${publicUrl}/mcp`);
-// The deployment owns this timer; core starts no background work. Uncomment
-// with artifactModule above. Each tick starts at most 10 due pages.
-// const refreshTimer = setInterval(() => {
-//   void artifactModule.runDue().catch((error) => console.error("artifact refresh failed", error));
-// }, 60 * 60 * 1000);
-// refreshTimer.unref();
+console.log(`connecta listening on port ${port}; MCP at ${config.publicUrl}/mcp`);