@zackbart/connecta 0.31.0 → 0.33.0

package/templates/node/README.md

@@ -8,11 +8,12 @@ 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:
+a container. Install, issue the declared `local-machine` agent's token, then
+start it:
 
 ```sh
 npm install
-npm run --silent provision-token -- "local-machine"
+npm run --silent rotate-token -- local-machine
 # Save the returned cta_ token privately. It is shown only once.
 npm start
 ```
@@ -24,39 +25,57 @@ 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.
 
-Point an MCP client at `http://localhost:8787/mcp` with
-`Authorization: Bearer <returned-cta-token>`. `CONNECTA_TOKEN` is a client and
+Point an agent's MCP client at `http://localhost:8787/agent/local-machine`, the agent
+endpoint of the pool that lists `agent:local-machine`, with
+`Authorization: Bearer <returned-cta-token>`. Agents use only `/agent/<pool>`:
+`/mcp` and `/mcp/<pool>` are for people and refuse `cta_` tokens, and plain
+`/mcp` serves only the `maintainers`. `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.
+`accessTokens(storage)` is always installed. With no issued agent token 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
+## Agent 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:
+Machine clients are agents, declared by name in `agents` in
+`src/connecta.config.ts`; the template declares `local-machine`. Each agent
+has one token. Run `npm run --silent rotate-token -- <agent>` from this
+project on a trusted machine to issue it, or to rotate it: the previous secret
+stops working on its next request. `src/rotate-token.ts` loads the same
+configuration the server does, so it uses the same database and refuses an
+agent the configuration does not declare. If you override the database path,
+use the same `CONNECTA_DATABASE` for rotation and startup:
 
 ```sh
 export CONNECTA_DATABASE=/absolute/path/connecta.sqlite
-npm run --silent provision-token -- "build-agent"
+npm run --silent rotate-token -- local-machine
 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.
+secret in a client secret store and out of source control and logs. A
+rotation cannot recover an old secret; only the hash persists. An agent has no
+human principal, no personal connectors, and no interactive management
+authority; deployment identity and pool rules decide its access on every
+request through `identity.agent`. To stop an agent, remove its name from
+`agents` and restart, or revoke its token with
+`new AccessTokenManager(storage, { agents }).revoke(name)` against the same
+storage. An explicitly permitted Clerk operator can also issue, rotate, and
+revoke from the operator UI. Never expose these scripts as an HTTP route or
+run them at startup.
+
+### Tokens issued before agents
+
+Tokens from earlier releases stay in storage but stop admitting until they are
+bound to an agent. Declare the agent, then run `npm run adopt-token` with no
+arguments to list the machine tokens that can be bound, and
+`npm run adopt-token -- <token-id> <agent>` to bind one, so that machine's
+existing secret keeps working. A token binds once, and only to an agent whose
+token was never issued. Human-bound tokens issued from the operator UI cannot
+be adopted and stay refused; issue the agent a new token instead.
 
 ## Run it in Docker
 
@@ -66,12 +85,12 @@ Same source, same configuration, one long-lived service:
 cp .env.example .env
 # 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"
+docker compose run --rm --no-deps connecta npm run --silent rotate-token -- local-machine
 # Save the returned cta_ token privately for clients and doctor.
 docker compose up -d
 ```
 
-The provisioning container writes through the installed package API into the
+The rotation 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.
@@ -121,12 +140,14 @@ whether or not it is switched on.
 
 The template explicitly enables `ui: operatorUi()` from
 `@zackbart/connecta/ui`. Open `http://localhost:8787/` and supply a
-stored machine token to inspect Connections. Sign in with Clerk for human
+declared agent's 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 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
+The page labels each tool as a read or write and each endpoint as writable or
+read-only. `src/connecta.config.ts` must set `readOnly`: a read-only endpoint
+refuses every write call and leaves write tools out of search, and the host
+controls approval on a writable one. 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.
@@ -142,7 +163,10 @@ 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`.
+start), set `PUBLIC_URL`, and list your Clerk user id in `CONNECTA_MAINTAINERS`
+(comma-separated; startup refuses Clerk without a maintainer). Maintainers
+alone use plain `/mcp` and the operator UI; add other people to a pool's
+`members` in `src/connecta.config.ts`.
 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.
@@ -162,18 +186,20 @@ 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
+Machine clients are the declared `agents`, each using a connecta-issued
+`cta_` token through `accessTokens(storage)`, which `src/connecta.config.ts`
+configures on the database. A signed-in maintainer issues, rotates, and
+revokes them from the operator UI. Trusted local rotation 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
-`personalConnection` permits the signed-in principal's personal-auth changes.
-Both management permissions default to none. Use `authScope: "personal"` for a
-connector where each person should connect their own downstream account.
-`activityAccess` separately selects readers of global activity.
+Set who uses what in code: `maintainers` for plain `/mcp` and the operator UI,
+and each pool's `members` for `/mcp/<pool>` (people) and `/agent/<pool>`
+(agents), which serve exactly that pool's `tools`. Agent endpoints publish no
+protected-resource metadata and accept only `cta_` tokens. Maintainers alone
+administer shared credentials and OAuth grants, manage agent tokens, and read
+activity. Use `authScope: "personal"` for a connector where each person should
+connect their own downstream account: a member connects their own account on
+the personal connectors in their pools.
 
 ### Credential vault
 
@@ -218,7 +244,7 @@ Diagnostics are independent. Keep the default logger or provide your own;
 
 The UI displays connections and current permissions. Configuration still owns
 the connector set, tool definitions, and access rules. Access token management
-requires explicit Clerk operator permission. There is no team roster or policy editor.
+requires a signed-in Clerk maintainer. There is no team roster or policy editor.
 
 ## Deployment contract
 
@@ -266,8 +292,9 @@ feature should not leave a tab behind.
 Upgrading from v0.23 does not require rotating managed `cta_…` tokens. Import
 `accessTokens` from `@zackbart/connecta/auth/access-tokens`, replace the old
 `accessTokens: true` with `accessTokens: accessTokens(storage)`, and keep the
-same persistent storage namespace and identity/tool/pool grant rules. Enable
-`identity.accessTokenManagement` only for the interactive operators who should
-manage tokens. New issuance needs storage with atomic `compareAndSet`; older
-storage adapters can still verify existing tokens. See the package's
+same persistent storage namespace. From 0.33 `maintainers` and pool `members`
+replace `identity.connectorAccess` and every `grant`, and maintainers replace
+the four `identity` management permissions; delete them and the `identity`
+section, and follow the package's `documentation/migration-0.33.md`. From 0.33 a stored token admits only once it is bound to a
+declared agent: follow "Tokens issued before agents" above. See the package's
 `documentation/auth.md` for the migration and storage requirements.

package/templates/node/docker-compose.yml

@@ -2,7 +2,7 @@
 #
 #   cp .env.example .env
 #   docker compose build
-#   docker compose run --rm --no-deps connecta npm run --silent provision-token -- "machine-name"
+#   docker compose run --rm --no-deps connecta npm run --silent rotate-token -- local-machine
 #   docker compose up -d --build
 #
 # Compose reads `.env` from this directory, so one file configures both the
@@ -16,7 +16,7 @@ services:
     ports:
       - "${PORT:-8787}:${PORT:-8787}"
     environment:
-      # accessTokens(storage) is always installed; an empty database is closed.
+      # accessTokens(storage) is always installed; an agent with no issued token 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
@@ -28,6 +28,7 @@ services:
       # on when set and off when empty.
       CLERK_PUBLISHABLE_KEY: ${CLERK_PUBLISHABLE_KEY:-}
       CLERK_SECRET_KEY: ${CLERK_SECRET_KEY:-}
+      CONNECTA_MAINTAINERS: ${CONNECTA_MAINTAINERS:-}
       CONNECTA_CREDENTIAL_KEY: ${CONNECTA_CREDENTIAL_KEY:-}
       CONNECTA_ACTIVITY: ${CONNECTA_ACTIVITY:-}
     volumes:

package/templates/node/package.json

@@ -10,14 +10,15 @@
     "esbuild@0.28.2": true
   },
   "scripts": {
-    "doctor": "connecta doctor",
-    "provision-token": "tsx src/provision-token.ts",
+    "adopt-token": "tsx src/adopt-token.ts",
+    "doctor": "connecta doctor --pool local-machine",
+    "rotate-token": "tsx src/rotate-token.ts",
     "start": "tsx src/index.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@clerk/backend": "^3.12.0",
-    "@zackbart/connecta": "0.31.0",
+    "@zackbart/connecta": "0.33.0",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/adopt-token.ts

@@ -0,0 +1,23 @@
+/**
+ * Trusted one-time migration: bind a machine token issued before agents to a
+ * declared agent, so that machine's existing cta_ secret keeps working. Run
+ * with no arguments to list the tokens that can be adopted. A token binds
+ * once, only to an agent that has never been issued one; human-bound tokens
+ * are refused and stop admitting.
+ */
+import { AccessTokenManager } from "@zackbart/connecta/auth/access-tokens";
+import connectaConfig from "./connecta.config.js";
+
+const [tokenId, agent] = process.argv.slice(2);
+const { storage, agents } = connectaConfig(process.env);
+const manager = new AccessTokenManager(storage!, { agents: agents ?? [] });
+if (tokenId === undefined) {
+  for (const token of await manager.unboundTokens()) {
+    process.stdout.write(`${token.id}  ${token.createdAt}  ${token.name}\n`);
+  }
+} else if (!agent || process.argv.length !== 4) {
+  throw new Error("Usage: npm run adopt-token -- [<token-id> <agent>]");
+} else {
+  await manager.adopt(tokenId, agent);
+  process.stdout.write(`${agent} now uses token ${tokenId}\n`);
+}

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

@@ -25,6 +25,7 @@ export interface Env {
   CONNECTA_DATABASE?: string;
   CLERK_PUBLISHABLE_KEY?: string;
   CLERK_SECRET_KEY?: string;
+  CONNECTA_MAINTAINERS?: string;
   CONNECTA_CREDENTIAL_KEY?: string;
   CONNECTA_ACTIVITY?: string;
 }
@@ -68,22 +69,42 @@ export default defineConfig((env: Env) => {
   return {
     storage,
     publicUrl,
+    // Required: can /mcp write? false lets call_destructive_tool and programs
+    // write, with the MCP client approving; true leaves write tools out of
+    // search and describe and refuses every write call. Pools inherit it
+    // unless they set their own readOnly. Startup fails without it.
+    readOnly: false,
     // 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.
+    // Required with Clerk: the Clerk user ids (comma-separated in
+    // CONNECTA_MAINTAINERS) who use plain /mcp, which serves every connector,
+    // and the operator UI. They alone administer shared credentials, manage
+    // agent tokens, and read activity. Everyone else uses a pool that lists
+    // them. Agents are never maintainers.
+    maintainers: clerk
+      ? (set("CONNECTA_MAINTAINERS") ?? "")
+          .split(",")
+          .map((id) => id.trim())
+          .filter(Boolean)
+      : [],
+    // Each pool serves exactly its tools to its members: Clerk user ids at
+    // /mcp/<name>, and "agent:<name>" for a declared agent at /agent/<name>.
+    // A member connects their own account on the pool's personal connectors.
+    // `npm run doctor` checks /agent/local-machine with its token. The starter
+    // pool is the agent's base pool (shared connectors, no owner), named after
+    // the agent as the agent pool layout requires.
+    pools: { "local-machine": { tools: ["time"], members: ["agent:local-machine"] } },
+    // Machine clients are agents declared here by name, each with one cta_
+    // token. Issue or rotate one locally with
+    // `npm run --silent rotate-token -- local-machine`, or as a signed-in
+    // maintainer from the operator UI. Removing a name stops its token on the
+    // next request.
+    agents: ["local-machine"],
+    // Always installed: a slot with no issued token refuses every request.
+    // Tokens from before agents stop admitting until `npm run adopt-token`
+    // binds each machine's token to an agent; human-bound tokens never do.
     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

package/templates/node/src/rotate-token.ts

@@ -0,0 +1,17 @@
+/**
+ * Trusted local provisioning: issue or rotate one declared agent's token
+ * against the same configuration and database the server uses. The previous
+ * secret stops working on its next request.
+ */
+import { AccessTokenManager } from "@zackbart/connecta/auth/access-tokens";
+import connectaConfig from "./connecta.config.js";
+
+const agent = process.argv[2];
+if (!agent || process.argv.length !== 3) {
+  throw new Error("Usage: npm run --silent rotate-token -- <agent>");
+}
+const { storage, agents } = connectaConfig(process.env);
+const manager = new AccessTokenManager(storage!, { agents: agents ?? [] });
+const { token } = await manager.rotate(agent, "local-provisioning");
+// The secret is returned once. Keep stdout private; storage holds its hash.
+process.stdout.write(`${token}\n`);

package/dist/tool-safety.d.ts

@@ -1,9 +0,0 @@
-import type { ToolDef, ToolVerdict } from "./types.js";
-export type PoolTrust = "trusted" | "read-only";
-/** Deployment override, then verified provider review, then fail-closed hints. */
-export declare function classifyTool(definition: ToolDef, override?: "read" | "write", review?: {
-    verdict: ToolVerdict;
-    stale?: boolean;
-}): "read" | "write";
-/** The only permission decision for a connector call. Approval is host-owned. */
-export declare function surfaceAllowsTool(classification: ToolDef["classification"], surface: string, trust?: PoolTrust): boolean;

package/templates/node/src/provision-token.ts

@@ -1,17 +0,0 @@
-/** Trusted local provisioning against the same database the server uses. */
-import { AccessTokenManager } from "@zackbart/connecta/auth/access-tokens";
-import { openSqlite, sqliteStorage } from "@zackbart/connecta/sqlite";
-
-const name = process.argv[2];
-if (!name || process.argv.length !== 3) {
-  throw new Error('Usage: npm run provision-token -- "machine-name"');
-}
-const database = openSqlite(process.env.CONNECTA_DATABASE || "./.connecta.sqlite");
-try {
-  const manager = new AccessTokenManager(sqliteStorage(database));
-  const { token } = await manager.create(name, "local-provisioning");
-  // The secret is returned once. Keep stdout private; storage holds its hash.
-  process.stdout.write(`${token}\n`);
-} finally {
-  database.close();
-}