@zackbart/connecta 0.26.1 → 0.26.2

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to this package are documented here.
 
 ## Unreleased
 
+## 0.26.2 — 2026-09-27
+
+This patch restores named client tokens as an optional auth module. Deployments
+upgrading from v0.23 can keep their existing stored records and client secrets,
+without rotation, by configuring `accessTokens(storage)` with the same storage
+namespace and preserving their identity grants. The old boolean configuration
+must be replaced. Deployments that omit the module are unchanged. The eight MCP
+tools remain unchanged, and the Node template now pins 0.26.2.
+
+### Added
+
+- `@zackbart/connecta/auth/access-tokens` verifies v0.23 `cta_…` tokens and
+  restores create, show-once, list, rename, and revoke in the operator UI.
+  `identity.accessTokenManagement` explicitly permits interactive operators;
+  client tokens cannot administer tokens or connection credentials. New issuance
+  requires atomic storage and reserves capacity across concurrent instances.
+
+### Fixed
+
+- Existing token ids, activity labels, and principal bindings survive the upgrade.
+  Malformed or corrupt records fail closed, including principal fields that
+  JavaScript regular expressions previously coerced into strings. Revocation
+  deletes the admission lookup before updating metadata.
+
+
 ## 0.26.1 — 2026-09-26
 
 This patch fixes slow OAuth restarts, unbounded downstream authorization waits,

package/README.md

@@ -132,3 +132,14 @@ breaks and what a deployment can ignore.
 Built for its author's deployments first and published openly. Breaking
 changes are expected before 1.0. See the [changelog](./CHANGELOG.md) and
 [security policy](./SECURITY.md).
+
+### Existing client tokens
+
+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
+`documentation/auth.md` for the migration and storage requirements.

package/dist/access-tokens.d.ts

@@ -0,0 +1,38 @@
+import type { IdentityReference, InboundAuth, KVStorage } from "./types.js";
+import type { AccessTokensModule } from "./module-contracts.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 updateRecord;
+    private updateActive;
+    private authorize;
+}
+/** Opt in using the same storage namespace that held the v0.23 records. */
+export declare function accessTokens(storage: KVStorage, options?: {
+    maxActive?: number;
+}): AccessTokensModule;

package/dist/access-tokens.js

@@ -0,0 +1,294 @@
+import { routeAccessTokens } from "./routes/access-tokens.js";
+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 ACTIVE_KEY = "access-token:v1:active";
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u;
+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" ||
+            !ID_RE.test(value.id) ||
+            typeof value.name !== "string" ||
+            !value.name.trim() ||
+            Array.from(value.name).length > MAX_NAME_CHARACTERS ||
+            typeof value.tokenHash !== "string" ||
+            !/^[0-9a-f]{64}$/u.test(value.tokenHash) ||
+            typeof value.tokenPrefix !== "string" ||
+            !/^cta_[A-Za-z0-9_-]{8}$/u.test(value.tokenPrefix) ||
+            typeof value.createdAt !== "string" ||
+            !Number.isFinite(Date.parse(value.createdAt)) ||
+            typeof value.createdBy !== "string" ||
+            (value.principal !== undefined &&
+                !validIdentityReference(value.principal)) ||
+            (value.revokedAt !== undefined &&
+                (typeof value.revokedAt !== "string" || !value.revokedAt || !Number.isFinite(Date.parse(value.revokedAt)))) ||
+            (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" && ID_RE.test(value.id)
+            ? { 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).catch(() => unauthorized()),
+        };
+    }
+    async read(id) {
+        if (!ID_RE.test(id))
+            return null;
+        const raw = await this.storage.get(recordKey(id));
+        const record = raw ? parseRecord(raw) : null;
+        if (record && record.id !== id)
+            throw new Error("Stored access token id mismatch");
+        return record;
+    }
+    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);
+        if (!this.storage.compareAndSet) {
+            throw new Error("Creating access tokens requires atomic compareAndSet storage");
+        }
+        if (typeof createdBy !== "string" && !validIdentityReference(createdBy)) {
+            throw new Error("Invalid token owner");
+        }
+        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.updateActive(record.id, true);
+        await this.storage.set(recordKey(record.id), JSON.stringify(record));
+        // A failed lookup write may have committed. Keep its reservation and
+        // metadata, so a manager can revoke it without ever returning the secret.
+        await this.storage.set(lookupKey(hash), JSON.stringify({ version: 1, id: record.id }));
+        return { token, accessToken: metadata(record) };
+    }
+    async rename(id, name) {
+        const normalized = normalizeName(name);
+        const record = await this.updateRecord(id, current => ({ ...current, name: normalized }));
+        return record ? metadata(record) : null;
+    }
+    async revoke(id, revokedBy) {
+        const record = await this.read(id);
+        if (!record)
+            return null;
+        // Remove admission first. A metadata failure cannot leave a successful
+        // revocation's lookup alive. Retry deletion even if already marked revoked.
+        await this.storage.delete(lookupKey(record.tokenHash));
+        const updated = await this.updateRecord(id, current => current.revokedAt ? current : {
+            ...current, revokedAt: new Date().toISOString(), revokedBy,
+        });
+        if (this.storage.compareAndSet)
+            await this.updateActive(id, false);
+        return updated ? metadata(updated) : null;
+    }
+    async updateRecord(id, update) {
+        if (!ID_RE.test(id))
+            return null;
+        for (let attempt = 0; attempt < 32; attempt++) {
+            const raw = await this.storage.get(recordKey(id));
+            if (!raw)
+                return null;
+            const record = parseRecord(raw);
+            if (record.id !== id)
+                throw new Error("Stored access token id mismatch");
+            const next = update(record);
+            if (this.storage.compareAndSet) {
+                // A rename racing revocation must retain revokedAt, including when
+                // an in-flight create has not yet published its lookup.
+                if (!await this.storage.compareAndSet(recordKey(id), raw, JSON.stringify(next)))
+                    continue;
+            }
+            else {
+                // Legacy adapters cannot create, so no late lookup writer exists.
+                // Revocation's deleted lookup still refuses a stale metadata write.
+                await this.storage.set(recordKey(id), JSON.stringify(next));
+            }
+            return next;
+        }
+        throw new Error("Access token metadata is busy; retry the operation");
+    }
+    async updateActive(id, adding) {
+        const cas = this.storage.compareAndSet;
+        if (!cas)
+            throw new Error("Creating access tokens requires atomic compareAndSet storage");
+        for (let attempt = 0; attempt < 32; attempt++) {
+            const raw = await this.storage.get(ACTIVE_KEY);
+            const ids = raw === null
+                ? (await this.list()).filter(token => !token.revokedAt).map(token => token.id)
+                : JSON.parse(raw);
+            if (!Array.isArray(ids) || !ids.every(value => typeof value === "string" && ID_RE.test(value)) || new Set(ids).size !== ids.length) {
+                throw new Error("Stored access token capacity is invalid");
+            }
+            if (adding && ids.length >= this.maxActive)
+                throw new Error(`This deployment already has the maximum of ${this.maxActive} active access tokens`);
+            const next = adding ? [...ids, id] : ids.filter(value => value !== id);
+            if (await cas.call(this.storage, ACTIVE_KEY, raw, JSON.stringify(next)))
+                return;
+        }
+        throw new Error("Access token capacity is busy; retry the operation");
+    }
+    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 || record.tokenPrefix !== token.slice(0, 12)) {
+            return unauthorized();
+        }
+        return {
+            ok: true,
+            subjectId: record.id,
+            ...(record.principal ? { principal: { ...record.principal } } : {}),
+        };
+    }
+}
+/** Opt in using the same storage namespace that held the v0.23 records. */
+export function accessTokens(storage, options = {}) {
+    const manager = new AccessTokenManager(storage, options);
+    return { auth: manager.auth, handle: context => routeAccessTokens(context, manager) };
+}

package/dist/identity.js

@@ -2,6 +2,8 @@ const IDENTITY_PART_RE = /^[\x21-\x7e]{1,256}$/;
 const encoder = new TextEncoder();
 export function validIdentityReference(value) {
     return Boolean(value &&
+        typeof value.namespace === "string" &&
+        typeof value.id === "string" &&
         IDENTITY_PART_RE.test(value.namespace) &&
         IDENTITY_PART_RE.test(value.id));
 }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import type { CredentialVault } from "./credential-contract.js";
 import { Registry } from "./registry.js";
 import type { ConnectorGrant } from "./connector-access.js";
-import type { ActivityModule, ArtifactsModule, OperatorSurface } from "./module-contracts.js";
-export type { ActivityModule, ArtifactsModule, OperatorSurface, } from "./module-contracts.js";
+import type { AccessTokensModule, ActivityModule, ArtifactsModule, OperatorSurface } from "./module-contracts.js";
+export type { AccessTokensModule, ActivityModule, ArtifactsModule, OperatorSurface, } from "./module-contracts.js";
 export type { CredentialVault, CredentialMetadata } from "./credential-contract.js";
 import type { AuthenticatedIdentity, Connector, Executor, IdentityReference, InboundAuth, KVStorage, Logger } from "./types.js";
 /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
@@ -180,6 +180,8 @@ export interface ConnectaIdentityConfig {
     activityAccess?(principal: Readonly<IdentityReference>): boolean | Promise<boolean>;
     /** Shared credential and OAuth administration. Defaults to none. */
     credentialAdministration?(identity: Readonly<AuthenticatedIdentity>): ConnectorPermission | Promise<ConnectorPermission>;
+    /** Client-token lifecycle management by interactive humans. Defaults to false. */
+    accessTokenManagement?(identity: Readonly<AuthenticatedIdentity>): boolean | Promise<boolean>;
     /** Connecting or changing the caller's personal account. Defaults to none. */
     personalConnection?(identity: Readonly<AuthenticatedIdentity>): ConnectorPermission | Promise<ConnectorPermission>;
 }
@@ -230,6 +232,8 @@ export interface ConnectaConfig {
      * because the links it hands out are shared.
      */
     artifacts?: ArtifactsModule;
+    /** Optional managed client tokens, created by accessTokens() from /auth/access-tokens. */
+    accessTokens?: AccessTokensModule;
     /** Optional dedicated HTTPS origin that serves only artifact pages and their library. */
     artifactOrigin?: string;
     /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */

package/dist/index.js

@@ -59,6 +59,7 @@ const CONFIG_SCHEMA = {
         activityAccess: null,
         credentialAdministration: null,
         personalConnection: null,
+        accessTokenManagement: null,
     },
     pools: null,
     storage: null,
@@ -68,6 +69,7 @@ const CONFIG_SCHEMA = {
     vault: null,
     ui: null,
     artifacts: null,
+    accessTokens: null,
     artifactOrigin: null,
     discovery: {
         concurrency: null,
@@ -144,7 +146,6 @@ function rejectUnknownOptions(paths) {
     throw new Error(`Unknown Connecta configuration option${paths.length === 1 ? "" : "s"}:\n` +
         paths.map((path) => `- ${path}`).join("\n") +
         (paths.includes("ConnectaConfig.credentials") ? "\nUse vault: encryptedCredentialVault(storage, key) from @zackbart/connecta/credentials." : "") +
-        (paths.includes("ConnectaConfig.accessTokens") ? "\nConnecta-issued tokens were removed. Configure an inbound auth adapter instead." : "") +
         (paths.includes("ConnectaConfig.branding") ? "\nMove branding into ui: operatorUi({ branding }) from @zackbart/connecta/ui." : ""));
 }
 /** Reject JavaScript typos and removed options before construction does work. */
@@ -172,6 +173,12 @@ function assertKnownConfig(config) {
             typeof activity.recordTool !== "function")) {
         throw new Error("ConnectaConfig.activity must be created with activityHistory(...)");
     }
+    if (config.accessTokens !== undefined && (!config.accessTokens ||
+        typeof config.accessTokens.auth?.authorize !== "function" ||
+        config.accessTokens.auth.interactiveOperator ||
+        typeof config.accessTokens.handle !== "function")) {
+        throw new Error("ConnectaConfig.accessTokens must be created with accessTokens(storage) from @zackbart/connecta/auth/access-tokens; reuse your existing storage to preserve tokens");
+    }
     const artifacts = config.artifacts;
     if (artifacts !== undefined) {
         const connector = artifacts?.connector;
@@ -495,7 +502,10 @@ export function createConnecta(config) {
     const storage = config.storage ?? memoryStorage();
     const logger = resolveLogger(config.logger);
     const credentialVault = config.vault;
-    const configuredAuth = normalizeAuth(config.auth);
+    const configuredAuth = normalizeAuth([
+        ...(config.accessTokens ? [config.accessTokens.auth] : []),
+        ...normalizeAuth(config.auth),
+    ]);
     const serverInfo = {
         ...config.serverInfo,
         name: config.serverInfo?.name ?? "connecta",
@@ -635,6 +645,7 @@ export function createConnecta(config) {
         activity: config.activity?.store,
         activityModule: config.activity,
         artifactsModule: config.artifacts,
+        accessTokens: config.accessTokens,
         activityReadGate: config.activity?.readGate,
         activityDeploymentId: config.activity?.deploymentId,
         executor,

package/dist/module-contracts.d.ts

@@ -37,3 +37,8 @@ export interface ArtifactsModule {
     /** Bind the optional refresh runner after core has built its registry and executor. */
     bindRefresh?(runtime: ArtifactRefreshRuntime): void;
 }
+/** Optional client-token authentication and operator lifecycle. */
+export interface AccessTokensModule {
+    readonly auth: import("./types.js").InboundAuth;
+    handle(context: RouteContext): Promise<Response | null>;
+}