@zackbart/connecta 0.23.0 → 0.24.1

package/templates/node/README.md

@@ -44,79 +44,72 @@ So commit the `package-lock.json` that the `npm install` above wrote on this
 machine: from then on the build context carries it and every build takes the
 reproducible `npm ci` path.
 
-## Turn on the operator surface
+## Select optional modules
 
-Out of the box this deployment serves the seven-tool MCP surface and a
-read-only operator UI: open `http://localhost:8787/`, paste the bearer, and you
-get Connections. The other three pages are configuration away, and each one is
-a commented block in `src/index.ts` — uncomment it, set the variables it names
-in `.env`, restart. Do them in this order; the last two lean on the first, and
-Credentials wants one thing more than a block, called out in step 2.
+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
+server. OAuth callbacks remain in core even with no UI.
 
-**1. Operator sign-in (Clerk).** A bearer token is a client key. It may call
-tools and read connector status, but it may not write a credential or issue an
-access token — that would make one shared secret a deployment-admin key. An
-interactive identity is what unlocks the actionable half:
+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    # optional peer; it does not install with Connecta
+npm install @clerk/backend
 ```
 
-Set `CLERK_PUBLISHABLE_KEY` and `CLERK_SECRET_KEY`, uncomment the `clerkAuth`
-import, the two `process.env.CLERK_*` reads, and the `clerkAuth({ … })` entry in
-`auth`. Enable Dynamic Client Registration on the Clerk instance (OAuth
-Applications → DCR) if MCP clients should sign in through it too, and set
-`PUBLIC_URL` first — Clerk redirects back to it.
+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.
 
-Clerk remains the identity provider when several people share this Docker
-deployment. Uncomment the `identity` block in `src/index.ts` to give each Clerk
-principal a config-derived connector view and to choose operators. Add
-`authScope: "personal"` to a connector when each person should supply their own
-credential or finish their own downstream OAuth flow. Without those options,
-all connectors and auth stay shared exactly as before.
+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.
 
-**2. Credential vault.** Uncomment `credentials` and set
+### Credential vault
+
+Import `encryptedCredentialVault` from `@zackbart/connecta/credentials`, then
+set `vault: encryptedCredentialVault(storage, credentialKey)`. Set
 `CONNECTA_CREDENTIAL_KEY` to a base64 32-byte AES key:
 
 ```sh
 node -e "console.log(crypto.randomBytes(32).toString('base64'))"
 ```
 
-Every connector that declares a `credential` slot then becomes editable at
-`/credentials`, with values encrypted in the state file. The shipped `time`
-connector declares none — telling the time needs no secret — so the key alone
-leaves the page hidden, which is the honest state for a page with nothing on
-it. Add `credential: { label: "API token" }` to an `api()` connector (the
-commented shape is in `src/index.ts`) and read it in a handler with
-`await ctx.credential?.get()`, or use a provider connector such as `notion()`,
-which declares its own; Credentials appears for a signed-in operator on the
-next restart. Keep the key anywhere
-except that file — it is the only thing standing between a copied state file
-and the secrets in it — and note that losing it makes stored values
-unreadable. A saved replacement takes effect on the next call; nothing
-restarts, and the deployment never probes a credential to see whether it still
-works. It fails at use, loudly, and the agent is routed to `/credentials`.
-
-**3. Access tokens.** Uncomment `accessTokens: {}`. A signed-in operator can
-then mint named, revocable Bearer tokens at `/tokens` for header-capable
-clients that will not do OAuth. Secrets are shown once and only their hashes
-are stored, so a lost token is reissued, never recovered.
-
-**4. Activity.** Uncomment the `activity` block and the `fileActivityStore`
-import. `/activity` then answers with who called what, when, how long it took,
-and whether it worked — never arguments, results, generated code, or raw error
-messages, because the store is never handed one. `src/file-activity.ts` is
-yours: it appends a line per call and rewrites the log down to the newest 5,000
-events once it runs a slack window past that, so the file holds a few hundred
-more than the ceiling between rewrites rather than being rewritten on every
-call. That is a retention policy chosen for a single container and worth
-revisiting for anything busier. In Docker the log lands on the same volume as
-the state file.
-
-None of this changes what agents can reach. Operator pages manage the
-authentication material behind capabilities this file already declares; the
-connector set, the tool catalog, and its annotations are `src/index.ts`'s
-business and stay that way.
+Keep this key outside the state file. 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
+connection on `/`; there is no separate Credentials tab.
+
+A saved replacement takes effect on the next call. Connecta tests credentials
+only on an explicit action and otherwise fails at use. Without a vault or UI,
+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.
+
+`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.
+
+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.
 
 ## Deployment contract
 
@@ -153,11 +146,7 @@ Connecta doctor passed: 1 connector(s), QuickJS executed, prescribed seven-tool
 `QuickJS` is this deployment's sandbox, reported by the deployment itself —
 swap the executor and doctor names the one that actually ran the program.
 
-That is deliberate. Doctor holds a bearer, and a bearer learns the model-facing
-surface, not the deployment's configuration topology: whether this deployment
-issues access tokens or keeps a credential vault is operator data, and a client
-key is not an operator. Confirm the operator surface the way an operator will —
-sign in at `/` and check that the pages you turned on are there: Tokens and
-Activity once their blocks are uncommented, and Credentials once the vault has
-a connector credential slot to show. The nav lists a page only when this
-deployment can serve it, so an absent page is a report, not a fault.
+Doctor verifies the MCP contract. Verify UI behavior separately: sign in at `/`,
+confirm the visible connections and their permitted auth controls, and check
+Activity only when you enabled a readable history store. A missing optional
+feature should not leave a tab behind.

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.23.0",
+    "@zackbart/connecta": "0.24.1",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {

package/templates/node/src/file-activity.ts

@@ -27,7 +27,7 @@ import type {
   ActivityStore,
   ToolCallActivityEvent,
 } from "@zackbart/connecta";
-import { InvalidActivityCursorError } from "@zackbart/connecta";
+import { InvalidActivityCursorError } from "@zackbart/connecta/activity";
 
 /**
  * Events allowed past `maxEvents` before the log is rewritten. Trimming on the

package/templates/node/src/index.ts

@@ -1,3 +1,7 @@
+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.
  *
@@ -20,7 +24,7 @@
  *   CONNECTA_CREDENTIAL_KEY  vault key, once the credentials block is on
  *   CONNECTA_ACTIVITY_FILE   activity log, once the activity block is on
  */
-import { api, bearerToken, createConnecta } from "@zackbart/connecta";
+import { api, createConnecta } from "@zackbart/connecta";
 import { fileStorage, listen } from "@zackbart/connecta/node";
 import { quickJsExecutor } from "@zackbart/connecta/quickjs";
 // Operator sign-in. Needs `npm install @clerk/backend` — it is an optional
@@ -74,7 +78,7 @@ const connecta = createConnecta({
   // identity: {
   //   connectorAccess: ({ principal }) =>
   //     principal?.id === "user_admin" ? "all" : ["time"],
-  //   operatorAccess: ({ id }) => id === "user_admin",
+  //   activityAccess: ({ id }) => id === "user_admin",
   // },
   publicUrl,
   // Required: model-written programs run in a bounded QuickJS child.
@@ -84,24 +88,19 @@ const connecta = createConnecta({
   // 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.
-  // credentials: { encryptionKey: process.env.CONNECTA_CREDENTIAL_KEY },
-  //
-  // Named, revocable Bearer tokens for MCP clients, issued at /tokens by a
-  // signed-in operator. Secrets are shown once; only their hashes are stored.
-  // Requires the Clerk block above — there is nobody to authorize issuance
-  // otherwise.
-  // accessTokens: {},
-  //
+  // 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: {
+  // activity: activityHistory({
   //   store: fileActivityStore(
   //     process.env.CONNECTA_ACTIVITY_FILE || "./.connecta-activity.jsonl",
   //   ),
   //   deploymentId: "production",
-  // },
+  // }),
+  ui: operatorUi(),
+  identity: { credentialAdministration: () => "all", personalConnection: () => "all" },
   connectors: [
     api("time", {
       description: "Time — current timestamp",

package/dist/access-tokens.d.ts

@@ -1,31 +0,0 @@
-import type { IdentityReference, InboundAuth, KVStorage } from "./types.js";
-export interface AccessTokenMetadata {
-    id: string;
-    name: string;
-    tokenPrefix: string;
-    createdAt: string;
-    revokedAt?: string;
-}
-export interface CreatedAccessToken {
-    token: string;
-    accessToken: AccessTokenMetadata;
-}
-/**
- * Deployment-scoped personal access tokens. Secret material is never
- * recoverable: authentication indexes a SHA-256 digest of a random 256-bit
- * token, while separately enumerable metadata powers operator management.
- */
-export declare class AccessTokenManager {
-    private readonly storage;
-    readonly auth: InboundAuth;
-    private readonly maxActive;
-    constructor(storage: KVStorage, options?: {
-        maxActive?: number;
-    });
-    private read;
-    list(): Promise<AccessTokenMetadata[]>;
-    create(name: unknown, createdBy: string | IdentityReference): Promise<CreatedAccessToken>;
-    rename(id: string, name: unknown): Promise<AccessTokenMetadata | null>;
-    revoke(id: string, revokedBy: string): Promise<AccessTokenMetadata | null>;
-    private authorize;
-}

package/dist/access-tokens.js

@@ -1,236 +0,0 @@
-import { validIdentityReference } from "./identity.js";
-const TOKEN_PREFIX = "cta_";
-const TOKEN_BYTES = 32;
-const TOKEN_VALUE_RE = /^cta_[A-Za-z0-9_-]{43}$/;
-const RECORD_PREFIX = "access-token:v1:record:";
-const LOOKUP_PREFIX = "access-token:v1:lookup:";
-const MAX_NAME_CHARACTERS = 80;
-const DEFAULT_MAX_ACTIVE = 100;
-const MAX_CONFIGURED_ACTIVE = 1_000;
-const encoder = new TextEncoder();
-function recordKey(id) {
-    return `${RECORD_PREFIX}${id}`;
-}
-function lookupKey(hash) {
-    return `${LOOKUP_PREFIX}${hash}`;
-}
-function bytesToBase64Url(bytes) {
-    let binary = "";
-    for (const byte of bytes)
-        binary += String.fromCharCode(byte);
-    return btoa(binary)
-        .replaceAll("+", "-")
-        .replaceAll("/", "_")
-        .replace(/=+$/u, "");
-}
-function bytesToHex(bytes) {
-    return [...bytes]
-        .map((byte) => byte.toString(16).padStart(2, "0"))
-        .join("");
-}
-async function hashToken(token) {
-    return bytesToHex(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(token))));
-}
-function normalizeName(value) {
-    if (typeof value !== "string") {
-        throw new Error("Token name must be a string");
-    }
-    const compact = value.replace(/\s+/gu, " ").trim();
-    if (!compact)
-        throw new Error("Token name cannot be empty");
-    if (Array.from(compact).length > MAX_NAME_CHARACTERS) {
-        throw new Error(`Token name cannot exceed ${MAX_NAME_CHARACTERS} characters`);
-    }
-    return compact;
-}
-function parseRecord(raw) {
-    try {
-        const value = JSON.parse(raw);
-        if (value.version !== 1 ||
-            typeof value.id !== "string" ||
-            !/^[0-9a-f-]{36}$/u.test(value.id) ||
-            typeof value.name !== "string" ||
-            typeof value.tokenHash !== "string" ||
-            !/^[0-9a-f]{64}$/u.test(value.tokenHash) ||
-            typeof value.tokenPrefix !== "string" ||
-            typeof value.createdAt !== "string" ||
-            typeof value.createdBy !== "string" ||
-            (value.principal !== undefined &&
-                !validIdentityReference(value.principal)) ||
-            (value.revokedAt !== undefined &&
-                typeof value.revokedAt !== "string") ||
-            (value.revokedBy !== undefined &&
-                typeof value.revokedBy !== "string")) {
-            throw new Error("invalid token record");
-        }
-        return value;
-    }
-    catch {
-        throw new Error("Stored access token metadata is invalid or corrupted");
-    }
-}
-function parseLookup(raw) {
-    try {
-        const value = JSON.parse(raw);
-        return value.version === 1 && typeof value.id === "string"
-            ? { version: 1, id: value.id }
-            : null;
-    }
-    catch {
-        return null;
-    }
-}
-function metadata(record) {
-    return {
-        id: record.id,
-        name: record.name,
-        tokenPrefix: record.tokenPrefix,
-        createdAt: record.createdAt,
-        ...(record.revokedAt ? { revokedAt: record.revokedAt } : {}),
-    };
-}
-function unauthorized() {
-    return {
-        ok: false,
-        response: new Response(JSON.stringify({ error: "unauthorized" }), {
-            status: 401,
-            headers: {
-                "Content-Type": "application/json",
-                "WWW-Authenticate": "Bearer",
-            },
-        }),
-    };
-}
-/**
- * Deployment-scoped personal access tokens. Secret material is never
- * recoverable: authentication indexes a SHA-256 digest of a random 256-bit
- * token, while separately enumerable metadata powers operator management.
- */
-export class AccessTokenManager {
-    storage;
-    auth;
-    maxActive;
-    constructor(storage, options = {}) {
-        this.storage = storage;
-        if (!storage.list) {
-            throw new Error("accessTokens requires a storage adapter that implements list(prefix)");
-        }
-        const maxActive = options.maxActive ?? DEFAULT_MAX_ACTIVE;
-        if (!Number.isInteger(maxActive) ||
-            maxActive < 1 ||
-            maxActive > MAX_CONFIGURED_ACTIVE) {
-            throw new Error(`accessTokens.maxActive must be a whole number from 1 to ${MAX_CONFIGURED_ACTIVE}`);
-        }
-        this.maxActive = maxActive;
-        this.auth = {
-            kind: "access_token",
-            activityActorNamespace: "connecta:access-tokens:v1",
-            activityActorLabel: async (id) => {
-                try {
-                    return (await this.read(id))?.name;
-                }
-                catch {
-                    return undefined;
-                }
-            },
-            authorize: (request) => this.authorize(request),
-        };
-    }
-    async read(id) {
-        const raw = await this.storage.get(recordKey(id));
-        return raw ? parseRecord(raw) : null;
-    }
-    async list() {
-        const keys = await this.storage.list(RECORD_PREFIX);
-        const records = await Promise.all(keys.map(async (key) => {
-            const raw = await this.storage.get(key);
-            return raw ? parseRecord(raw) : null;
-        }));
-        return records
-            .filter((record) => Boolean(record))
-            .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
-            .map(metadata);
-    }
-    async create(name, createdBy) {
-        const normalizedName = normalizeName(name);
-        const active = (await this.list()).filter((token) => !token.revokedAt);
-        if (active.length >= this.maxActive) {
-            throw new Error(`This deployment already has the maximum of ${this.maxActive} active access tokens`);
-        }
-        const secretBytes = crypto.getRandomValues(new Uint8Array(TOKEN_BYTES));
-        const token = TOKEN_PREFIX + bytesToBase64Url(secretBytes);
-        const hash = await hashToken(token);
-        if (await this.storage.get(lookupKey(hash))) {
-            throw new Error("Access token collision; create another token");
-        }
-        const record = {
-            version: 1,
-            id: crypto.randomUUID(),
-            name: normalizedName,
-            tokenHash: hash,
-            tokenPrefix: token.slice(0, 12),
-            createdAt: new Date().toISOString(),
-            createdBy: typeof createdBy === "string"
-                ? createdBy
-                : `${createdBy.namespace}:${createdBy.id}`,
-            ...(typeof createdBy === "string"
-                ? {}
-                : { principal: { ...createdBy } }),
-        };
-        await this.storage.set(recordKey(record.id), JSON.stringify(record));
-        try {
-            await this.storage.set(lookupKey(hash), JSON.stringify({ version: 1, id: record.id }));
-        }
-        catch (error) {
-            await this.storage.delete(recordKey(record.id)).catch(() => { });
-            throw error;
-        }
-        return { token, accessToken: metadata(record) };
-    }
-    async rename(id, name) {
-        const record = await this.read(id);
-        if (!record)
-            return null;
-        record.name = normalizeName(name);
-        await this.storage.set(recordKey(id), JSON.stringify(record));
-        return metadata(record);
-    }
-    async revoke(id, revokedBy) {
-        const record = await this.read(id);
-        if (!record)
-            return null;
-        if (!record.revokedAt) {
-            // Admission disappears first. A metadata-write failure may leave the UI
-            // calling the record active, but can never leave a token labelled
-            // revoked while its lookup still admits requests.
-            await this.storage.delete(lookupKey(record.tokenHash));
-            record.revokedAt = new Date().toISOString();
-            record.revokedBy = revokedBy;
-            await this.storage.set(recordKey(id), JSON.stringify(record));
-        }
-        return metadata(record);
-    }
-    async authorize(request) {
-        const header = request.headers.get("authorization") ?? "";
-        const match = /^Bearer\s+(.+)$/iu.exec(header);
-        const token = match?.[1];
-        if (!token || !TOKEN_VALUE_RE.test(token))
-            return unauthorized();
-        const hash = await hashToken(token);
-        const lookupRaw = await this.storage.get(lookupKey(hash));
-        if (!lookupRaw)
-            return unauthorized();
-        const lookup = parseLookup(lookupRaw);
-        if (!lookup)
-            return unauthorized();
-        const record = await this.read(lookup.id);
-        if (!record || record.revokedAt || record.tokenHash !== hash) {
-            return unauthorized();
-        }
-        return {
-            ok: true,
-            subjectId: record.id,
-            ...(record.principal ? { principal: { ...record.principal } } : {}),
-        };
-    }
-}

package/dist/routes/access-tokens.d.ts

@@ -1,6 +0,0 @@
-import { type RouteContext } from "./shared.js";
-/**
- * Interactive-operator lifecycle for deployment access tokens. The token itself
- * is deliberately never an administrator credential and cannot reach here.
- */
-export declare function routeAccessTokens(context: RouteContext): Promise<Response | null>;

package/dist/routes/access-tokens.js

@@ -1,83 +0,0 @@
-import { authorizeUiAdmin, isSameOrigin, msg, privateJson, } from "./shared.js";
-async function readName(request) {
-    if (!request.headers
-        .get("content-type")
-        ?.toLowerCase()
-        .startsWith("application/json")) {
-        return {
-            ok: false,
-            response: privateJson({ error: "Content-Type must be application/json" }, { status: 415 }),
-        };
-    }
-    const raw = await request.text();
-    if (raw.length > 1_000) {
-        return {
-            ok: false,
-            response: privateJson({ error: "request body is too large" }, { status: 413 }),
-        };
-    }
-    try {
-        const body = JSON.parse(raw);
-        return { ok: true, name: body.name };
-    }
-    catch {
-        return {
-            ok: false,
-            response: privateJson({ error: "invalid JSON body" }, { status: 400 }),
-        };
-    }
-}
-/**
- * Interactive-operator lifecycle for deployment access tokens. The token itself
- * is deliberately never an administrator credential and cannot reach here.
- */
-export async function routeAccessTokens(context) {
-    const match = /^\/ui\/access-tokens(?:\/([0-9a-f-]{36}))?$/.exec(context.path);
-    if (!match)
-        return null;
-    const { request, baseUrl, opts } = context;
-    if (request.method === "OPTIONS") {
-        return privateJson({ error: "CORS is not allowed" }, { status: 403 });
-    }
-    if (!opts.accessTokens) {
-        return privateJson({ error: "access token management is not configured" }, { status: 404 });
-    }
-    const mutating = request.method !== "GET";
-    if (mutating && !isSameOrigin(request, baseUrl)) {
-        return privateJson({ error: "same-origin request required" }, { status: 403 });
-    }
-    const admin = await authorizeUiAdmin(request, baseUrl, opts.auth, "access token management", context.runtimeContext, opts.identity);
-    if (!admin.ok)
-        return admin.response;
-    const id = match[1];
-    try {
-        if (!id && request.method === "GET") {
-            return privateJson({ accessTokens: await opts.accessTokens.list() });
-        }
-        if (!id && request.method === "POST") {
-            const input = await readName(request);
-            if (!input.ok)
-                return input.response;
-            return privateJson(await opts.accessTokens.create(input.name, admin.principal ?? admin.userId), { status: 201 });
-        }
-        if (id && request.method === "PUT") {
-            const input = await readName(request);
-            if (!input.ok)
-                return input.response;
-            const accessToken = await opts.accessTokens.rename(id, input.name);
-            return accessToken
-                ? privateJson({ accessToken })
-                : privateJson({ error: "unknown access token" }, { status: 404 });
-        }
-        if (id && request.method === "DELETE") {
-            const accessToken = await opts.accessTokens.revoke(id, admin.userId);
-            return accessToken
-                ? privateJson({ accessToken })
-                : privateJson({ error: "unknown access token" }, { status: 404 });
-        }
-        return privateJson({ error: "method not allowed" }, { status: 405 });
-    }
-    catch (error) {
-        return privateJson({ error: msg(error) }, { status: 400 });
-    }
-}