@zackbart/connecta 0.10.0 → 0.10.1

package/dist/version.d.ts

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.10.0";
+export declare const CONNECTA_VERSION = "0.10.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -4,5 +4,5 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.10.0";
+export const CONNECTA_VERSION = "0.10.1";
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",

package/src/access-tokens.ts

@@ -0,0 +1,289 @@
+import type { AuthResult, InboundAuth, KVStorage } from "./types.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();
+
+interface StoredAccessToken {
+  version: 1;
+  id: string;
+  name: string;
+  tokenHash: string;
+  tokenPrefix: string;
+  createdAt: string;
+  createdBy: string;
+  revokedAt?: string;
+  revokedBy?: string;
+}
+
+interface TokenLookup {
+  version: 1;
+  id: string;
+}
+
+export interface AccessTokenMetadata {
+  id: string;
+  name: string;
+  tokenPrefix: string;
+  createdAt: string;
+  revokedAt?: string;
+}
+
+export interface CreatedAccessToken {
+  token: string;
+  accessToken: AccessTokenMetadata;
+}
+
+function recordKey(id: string): string {
+  return `${RECORD_PREFIX}${id}`;
+}
+
+function lookupKey(hash: string): string {
+  return `${LOOKUP_PREFIX}${hash}`;
+}
+
+function bytesToBase64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/u, "");
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return [...bytes]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+async function hashToken(token: string): Promise<string> {
+  return bytesToHex(
+    new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(token))),
+  );
+}
+
+function normalizeName(value: unknown): string {
+  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: string): StoredAccessToken {
+  try {
+    const value = JSON.parse(raw) as Partial<StoredAccessToken>;
+    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.revokedAt !== undefined &&
+        typeof value.revokedAt !== "string") ||
+      (value.revokedBy !== undefined &&
+        typeof value.revokedBy !== "string")
+    ) {
+      throw new Error("invalid token record");
+    }
+    return value as StoredAccessToken;
+  } catch {
+    throw new Error("Stored access token metadata is invalid or corrupted");
+  }
+}
+
+function parseLookup(raw: string): TokenLookup | null {
+  try {
+    const value = JSON.parse(raw) as Partial<TokenLookup>;
+    return value.version === 1 && typeof value.id === "string"
+      ? { version: 1, id: value.id }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function metadata(record: StoredAccessToken): AccessTokenMetadata {
+  return {
+    id: record.id,
+    name: record.name,
+    tokenPrefix: record.tokenPrefix,
+    createdAt: record.createdAt,
+    ...(record.revokedAt ? { revokedAt: record.revokedAt } : {}),
+  };
+}
+
+function unauthorized(): AuthResult {
+  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 {
+  readonly auth: InboundAuth;
+  private readonly maxActive: number;
+
+  constructor(
+    private readonly storage: KVStorage,
+    options: { maxActive?: number } = {},
+  ) {
+    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),
+    };
+  }
+
+  private async read(id: string): Promise<StoredAccessToken | null> {
+    const raw = await this.storage.get(recordKey(id));
+    return raw ? parseRecord(raw) : null;
+  }
+
+  async list(): Promise<AccessTokenMetadata[]> {
+    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): record is StoredAccessToken => Boolean(record))
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+      .map(metadata);
+  }
+
+  async create(name: unknown, createdBy: string): Promise<CreatedAccessToken> {
+    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: StoredAccessToken = {
+      version: 1,
+      id: crypto.randomUUID(),
+      name: normalizedName,
+      tokenHash: hash,
+      tokenPrefix: token.slice(0, 12),
+      createdAt: new Date().toISOString(),
+      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 } satisfies TokenLookup),
+      );
+    } catch (error) {
+      await this.storage.delete(recordKey(record.id)).catch(() => {});
+      throw error;
+    }
+    return { token, accessToken: metadata(record) };
+  }
+
+  async rename(
+    id: string,
+    name: unknown,
+  ): Promise<AccessTokenMetadata | null> {
+    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: string,
+    revokedBy: string,
+  ): Promise<AccessTokenMetadata | null> {
+    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);
+  }
+
+  private async authorize(request: Request): Promise<AuthResult> {
+    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 };
+  }
+}

package/src/index.ts

@@ -3,6 +3,7 @@ import {
   credentialTestRule,
   describeCredentialTestMismatch,
 } from "./credentials.js";
+import { AccessTokenManager } from "./access-tokens.js";
 import { Registry } from "./registry.js";
 import { createFetchHandler } from "./server.js";
 import { droppedBrandingUrls, droppedUiAuthUrls } from "./ui.js";
@@ -49,6 +50,12 @@ export interface ConnectaCredentialsConfig {
   encryptionKey?: string;
 }
 
+/** Operator-issued credentials for clients connecting to this deployment. */
+export interface ConnectaAccessTokensConfig {
+  /** Maximum simultaneously active access tokens. Defaults to 100. */
+  maxActive?: number;
+}
+
 /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
 export interface ConnectaDiscoveryConfig {
   /**
@@ -148,6 +155,11 @@ export interface ConnectaConfig {
   activity?: ConnectaActivityConfig;
   /** Operator credential vault settings. */
   credentials?: ConnectaCredentialsConfig;
+  /**
+   * Named, revocable Bearer tokens for MCP clients. Creation and mutation
+   * require an eligible Clerk operator; token secrets are returned once.
+   */
+  accessTokens?: ConnectaAccessTokensConfig;
   /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
   discovery?: ConnectaDiscoveryConfig;
   /** Deployment-wide call deadlines and result paging threshold. */
@@ -468,6 +480,19 @@ export function createConnecta(config: ConnectaConfig): Connecta {
   const credentialVault = encryptionKey
     ? new CredentialVault(storage, encryptionKey)
     : undefined;
+  const configuredAuth = normalizeAuth(config.auth);
+  const accessTokens = config.accessTokens
+    ? new AccessTokenManager(storage, config.accessTokens)
+    : undefined;
+  if (
+    accessTokens &&
+    !configuredAuth.some((provider) => provider.uiAuth?.kind === "clerk")
+  ) {
+    throw new Error(
+      "accessTokens requires a Clerk auth provider: only an eligible Clerk " +
+        "operator may create, rename, or revoke deployment access tokens",
+    );
+  }
   const registry = new Registry(config.connectors, {
     storage,
     logger,
@@ -488,7 +513,9 @@ export function createConnecta(config: ConnectaConfig): Connecta {
       ? { maxBatchResultBytes: config.calls.maxBatchResultBytes }
       : {}),
   });
-  const inboundAuth = normalizeAuth(config.auth);
+  const inboundAuth = normalizeAuth(
+    accessTokens ? [accessTokens.auth, ...configuredAuth] : configuredAuth,
+  );
   warnInsecureConfig(config, inboundAuth, logger);
   const requestAdmission = admissionController(
     config.admission?.requests,
@@ -542,6 +569,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
       ? { discoveryConcurrency: config.discovery.concurrency }
       : {}),
     ...(credentialVault !== undefined ? { credentialVault } : {}),
+    ...(accessTokens !== undefined ? { accessTokens } : {}),
     ...(config.deploymentInfo !== undefined
       ? { deploymentInfo: config.deploymentInfo }
       : {}),
@@ -580,6 +608,10 @@ export { validateToolInput } from "./validate.js";
 export type { ValidateToolInputOptions } from "./validate.js";
 export { bearerToken } from "./auth/bearer.js";
 export type { BearerTokenOptions } from "./auth/bearer.js";
+export type {
+  AccessTokenMetadata,
+  CreatedAccessToken,
+} from "./access-tokens.js";
 export { memoryStorage } from "./storage/memory.js";
 export { CONNECTA_VERSION } from "./version.js";
 // Registry is reachable through `Connecta.registry`, so its type is public;

package/src/operator-ui/browser.css

@@ -285,6 +285,69 @@
   .credential-field input { min-width: 0; width: 100%; }
   .danger { text-decoration-style: double; }
 
+  .token-create {
+    border-bottom: 1px solid var(--rule);
+    border-top: 1px solid var(--rule);
+    padding: .75rem 0;
+  }
+  .token-create > label {
+    display: block;
+    margin-bottom: .5rem;
+  }
+  .token-create input { flex: 1 1 18rem; }
+  .token-create button,
+  .token-card button,
+  .token-reveal button {
+    align-items: center;
+    display: inline-flex;
+    min-height: 2.75rem;
+  }
+  .token-reveal {
+    background: var(--ink);
+    color: var(--paper);
+    margin-top: 1.5rem;
+    padding: 1rem 1.25rem;
+  }
+  .token-reveal .meta,
+  .token-reveal .cap { color: #bbb; }
+  .token-reveal-head,
+  .token-card-head {
+    align-items: baseline;
+    display: flex;
+    flex-wrap: wrap;
+    gap: .25rem var(--gap);
+    justify-content: space-between;
+  }
+  .token-secret {
+    border-bottom: 1px solid #555;
+    border-top: 1px solid #555;
+    margin-top: .75rem;
+  }
+  .token-secret code {
+    color: var(--paper);
+    user-select: all;
+  }
+  .token-ledger {
+    border-bottom: 1px solid var(--rule);
+    margin-top: 1.5rem;
+  }
+  .token-card {
+    border-top: 1px solid var(--rule);
+    padding: .75rem 0 .75rem 1.25rem;
+    position: relative;
+  }
+  .token-card::before {
+    background: var(--ink);
+    bottom: 0;
+    content: "";
+    left: .25rem;
+    position: absolute;
+    top: 0;
+    width: 1px;
+  }
+  .token-card.revoked { color: var(--muted); }
+  .token-card.revoked::before { background: var(--rule); }
+
   details { margin-top: .75rem; }
   summary { cursor: pointer; list-style: none; width: max-content; }
   summary::-webkit-details-marker { display: none; }