@zackbart/connecta 0.10.0 → 0.10.2

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/catalog-service.ts

@@ -1,9 +1,12 @@
 import {
+  compactDiscoverySchema,
   compactSchema,
   lexicalCorpusStatistics,
+  lexicalQueryTerms,
   lexicalSearchQuery,
   rankTools,
   schemaObjectKeys,
+  summarizeDiscoveryDescription,
   summarizeDescription,
 } from "./catalog.js";
 import {
@@ -25,6 +28,7 @@ import {
   normalizeTimeoutMs,
   withAbortableTimeout,
 } from "./timeout.js";
+import { isExplicitlyReadOnly } from "./tool-safety.js";
 import type {
   Connector,
   JsonSchema,
@@ -35,6 +39,8 @@ export const DEFAULT_SEARCH_LIMIT = 8;
 export const MAX_SEARCH_LIMIT = 100;
 export const MAX_DESCRIBE_ADDRESSES = 100;
 export const MAX_DISCOVERY_RESULT_BYTES = 256_000;
+const MAX_QUERY_ANALYSIS_TERMS = 8;
+const MAX_QUERY_ANALYSIS_TERM_LENGTH = 64;
 
 const encoder = new TextEncoder();
 
@@ -101,6 +107,11 @@ export function boundedDiscoveryText(value: unknown, hint: string): string {
 export interface CatalogSearchArgs {
   query?: string;
   connector?: string;
+  /**
+   * Result classification only; never changes which tools exist or what may
+   * execute. Omitted and "all" preserve the complete configured catalog.
+   */
+  safety?: "readOnly" | "approvalRequired" | "all";
   limit?: number;
   offset?: number;
   fullDescriptions?: boolean;
@@ -109,6 +120,35 @@ export interface CatalogSearchArgs {
   includeSchemaKeys?: boolean;
 }
 
+function discoverySafety(
+  value: unknown,
+): "readOnly" | "approvalRequired" | "all" {
+  if (value === undefined) return "all";
+  if (
+    value !== "readOnly" &&
+    value !== "approvalRequired" &&
+    value !== "all"
+  ) {
+    throw new DiscoveryPolicyError(
+      "invalid_args",
+      'safety must be "readOnly", "approvalRequired", or "all".',
+    );
+  }
+  return value;
+}
+
+function toolsForSafety(
+  tools: ToolDef[],
+  safety: "readOnly" | "approvalRequired" | "all",
+): ToolDef[] {
+  if (safety === "all") return tools;
+  return tools.filter((tool) =>
+    safety === "readOnly"
+      ? isExplicitlyReadOnly(tool)
+      : !isExplicitlyReadOnly(tool),
+  );
+}
+
 export interface CatalogDescribeArgs {
   addresses?: unknown;
   format?: "compact" | "json";
@@ -124,6 +164,8 @@ interface CatalogSearchEntry {
     description?: string;
     inputSchema?: unknown;
     outputSchema?: unknown;
+    inputSchemaTruncated?: true;
+    outputSchemaTruncated?: true;
     inputKeys?: string[];
     requiredInputKeys?: string[];
     outputKeys?: string[];
@@ -165,6 +207,16 @@ export interface CatalogSearchPage {
   hasMore: boolean;
   nextOffset?: number;
   matchMode?: "partial";
+  queryAnalysis?: {
+    representedTerms: string[];
+    otherResultTerms: string[];
+    unmatchedTerms: string[];
+    truncated?: true;
+    connectorScope?: string;
+    unknownConnector?: true;
+    unavailableConnectorCount?: number;
+    guidance?: string;
+  };
 }
 
 export interface CatalogDescription {
@@ -203,6 +255,15 @@ function renderSchema(schema: JsonSchema, format: "compact" | "json"): unknown {
   return format === "json" ? schema : compactSchema(schema);
 }
 
+function renderSearchSchema(
+  schema: JsonSchema,
+  format: "compact" | "json",
+): { schema: unknown; truncated: boolean } {
+  if (format === "json") return { schema, truncated: false };
+  const compact = compactDiscoverySchema(schema);
+  return { schema: compact.text, truncated: compact.truncated };
+}
+
 /**
  * Request-local catalog operations shared by MCP meta-tools and code mode.
  * Successful catalogs may be reused inside this request; failures are not
@@ -397,12 +458,16 @@ export class CatalogService {
   async search(args: CatalogSearchArgs): Promise<CatalogSearchPage> {
     const query = args.query ?? "";
     const retrievalQuery = lexicalSearchQuery(query);
+    const safety = discoverySafety(args.safety);
     const limit = discoverySearchLimit(args.limit);
     const offset = Math.max(0, Math.trunc(args.offset ?? 0));
+    const scopedConnector = args.connector
+      ? this.registry.getConnector(args.connector)
+      : undefined;
     const connectors = args.connector
-      ? [this.registry.getConnector(args.connector)].filter(
-          (connector): connector is Connector => Boolean(connector),
-        )
+      ? scopedConnector
+        ? [scopedConnector]
+        : []
       : this.registry.listConnectors();
     const catalogs = await mapSettledWithConcurrency(
       connectors,
@@ -413,6 +478,14 @@ export class CatalogService {
           `search_tools probe of "${connector.id}"`,
         ),
     );
+    const searchableCatalogs = catalogs.map((catalog) =>
+      catalog.status === "fulfilled"
+        ? {
+            status: "fulfilled" as const,
+            value: toolsForSafety(catalog.value, safety),
+          }
+        : catalog,
+    );
     const matches: Array<{
       connector: Connector;
       tool: ToolDef;
@@ -421,7 +494,7 @@ export class CatalogService {
     }> = [];
     let matchMode: "all" | "partial" = "all";
     const statistics = lexicalCorpusStatistics(
-      catalogs.flatMap((catalog) =>
+      searchableCatalogs.flatMap((catalog) =>
         catalog.status === "fulfilled" ? [catalog.value] : [],
       ),
       retrievalQuery,
@@ -429,7 +502,7 @@ export class CatalogService {
     const collectMatches = (mode: "all" | "partial") => {
       matches.length = 0;
       let orderBase = 0;
-      catalogs.forEach((catalog, connectorIndex) => {
+      searchableCatalogs.forEach((catalog, connectorIndex) => {
         const connector = connectors[connectorIndex];
         if (!connector) {
           throw new Error("Catalog result has no corresponding connector");
@@ -459,9 +532,17 @@ export class CatalogService {
       collectMatches(matchMode);
     }
     matches.sort((a, b) => b.score - a.score || a.order - b.order);
-    const entries = matches.slice(offset, offset + limit).map((match) => {
+    const pageMatches = matches.slice(offset, offset + limit);
+    const entries = pageMatches.map((match) => {
       const input = match.tool.inputSchema ?? { type: "object" };
-      const description = summarizeDescription(
+      const renderedInput = args.includeSchemas
+        ? renderSearchSchema(input, args.includeSchemas)
+        : undefined;
+      const renderedOutput =
+        args.includeSchemas && match.tool.outputSchema
+          ? renderSearchSchema(match.tool.outputSchema, args.includeSchemas)
+          : undefined;
+      const description = summarizeDiscoveryDescription(
         match.tool.description,
         args.fullDescriptions === true,
       );
@@ -476,16 +557,20 @@ export class CatalogService {
           ...(description !== undefined ? { description } : {}),
           ...(args.includeSchemas
             ? {
-                inputSchema:
-                  renderSchema(input, args.includeSchemas),
+                inputSchema: renderedInput?.schema,
               }
             : {}),
+          ...(renderedInput?.truncated
+            ? { inputSchemaTruncated: true as const }
+            : {}),
           ...(args.includeSchemas && match.tool.outputSchema
             ? {
-                outputSchema:
-                  renderSchema(match.tool.outputSchema, args.includeSchemas),
+                outputSchema: renderedOutput?.schema,
               }
             : {}),
+          ...(renderedOutput?.truncated
+            ? { outputSchemaTruncated: true as const }
+            : {}),
           ...(args.includeSchemas && args.includeSchemaKeys
             ? schemaKeyMetadata(input, match.tool.outputSchema)
             : {}),
@@ -499,6 +584,62 @@ export class CatalogService {
       offset + entries.length < matches.length
         ? offset + entries.length
         : undefined;
+    const queryTerms = lexicalQueryTerms(retrievalQuery);
+    const analyzedTerms = queryTerms.slice(0, MAX_QUERY_ANALYSIS_TERMS);
+    const displayTerm = (term: string) =>
+      term.length <= MAX_QUERY_ANALYSIS_TERM_LENGTH
+        ? term
+        : `${term.slice(0, MAX_QUERY_ANALYSIS_TERM_LENGTH - 1)}…`;
+    const pageTools = new Set(pageMatches.map((match) => match.tool));
+    const matchingTools = (term: string) =>
+      new Set([
+        ...(statistics.nameMatches.get(term) ?? []),
+        ...(statistics.descriptionMatches.get(term) ?? []),
+      ]);
+    const representedTerms: string[] = [];
+    const otherResultTerms: string[] = [];
+    const unmatchedTerms: string[] = [];
+    for (const term of analyzedTerms) {
+      const termTools = matchingTools(term);
+      if ([...termTools].some((tool) => pageTools.has(tool))) {
+        representedTerms.push(displayTerm(term));
+      } else if (termTools.size > 0) {
+        otherResultTerms.push(displayTerm(term));
+      } else {
+        unmatchedTerms.push(displayTerm(term));
+      }
+    }
+    const unavailableCatalogs = catalogs.filter(
+      (catalog) => catalog.status === "rejected",
+    ).length;
+    const safetyLabel =
+      safety === "readOnly"
+        ? "read-only "
+        : safety === "approvalRequired"
+          ? "approval-required "
+          : "";
+    const filterRecovery =
+      safety === "all" ? "" : " Change safety to inspect the other tools.";
+    const guidance =
+      queryTerms.length === 0
+        ? undefined
+        : matches.length === 0
+          ? args.connector && !scopedConnector
+            ? `Connector "${args.connector}" is not configured in this deployment. Omit connector to search all configured tools.`
+            : scopedConnector
+              ? unavailableCatalogs > 0
+                ? `Connector "${scopedConnector.id}" could not be searched because its catalog was unavailable. Retry later.`
+                : `No matching ${safetyLabel}capability was found on connector "${scopedConnector.id}". Refine terms or browse it with an empty query.${filterRecovery}`
+              : unavailableCatalogs === 0
+                ? `No matching ${safetyLabel}capability is configured in this deployment. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
+                : `No matching ${safetyLabel}capability was found in the catalogs that answered; ${unavailableCatalogs} connector catalog${unavailableCatalogs === 1 ? " was" : "s were"} unavailable. Refine terms, scope by connector, or browse with an empty query.${filterRecovery}`
+          : matchMode === "partial"
+            ? scopedConnector
+              ? `No single tool on connector "${scopedConnector.id}" matched every term. Split distinct intents into separate searches.`
+              : unavailableCatalogs === 0
+              ? "No single tool matched every term. Split distinct intents into separate searches."
+              : "No single tool matched every term in the catalogs that answered. Split distinct intents into separate searches."
+            : undefined;
     return {
       entries,
       total: matches.length,
@@ -509,6 +650,29 @@ export class CatalogService {
       ...(matchMode === "partial" && matches.length > 0
         ? { matchMode }
         : {}),
+      ...(queryTerms.length > 0 && matchMode === "partial"
+        ? {
+            queryAnalysis: {
+              representedTerms,
+              otherResultTerms,
+              unmatchedTerms,
+              ...(queryTerms.length > analyzedTerms.length ||
+              analyzedTerms.some(
+                (term) => term.length > MAX_QUERY_ANALYSIS_TERM_LENGTH,
+              )
+                ? { truncated: true as const }
+                : {}),
+              ...(args.connector ? { connectorScope: args.connector } : {}),
+              ...(args.connector && !scopedConnector
+                ? { unknownConnector: true as const }
+                : {}),
+              ...(unavailableCatalogs > 0
+                ? { unavailableConnectorCount: unavailableCatalogs }
+                : {}),
+              ...(guidance ? { guidance } : {}),
+            },
+          }
+        : {}),
     };
   }
 
@@ -592,7 +756,6 @@ export function groupedSearchResult(page: CatalogSearchPage) {
   const groups: Array<{
     id: string;
     title?: string;
-    description?: string;
     guide?: string;
     tools: CatalogSearchEntry["tool"][];
   }> = [];
@@ -605,9 +768,6 @@ export function groupedSearchResult(page: CatalogSearchPage) {
       const group: (typeof groups)[number] = {
         id: entry.connector.id,
         ...(entry.connector.title ? { title: entry.connector.title } : {}),
-        ...(entry.connector.description !== undefined
-          ? { description: entry.connector.description }
-          : {}),
         ...(entry.guide ? { guide: entry.guide } : {}),
         tools: [],
       };
@@ -624,6 +784,7 @@ export function groupedSearchResult(page: CatalogSearchPage) {
     hasMore: page.hasMore,
     ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
     ...(page.matchMode ? { matchMode: page.matchMode } : {}),
+    ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
   };
 }
 
@@ -636,5 +797,6 @@ export function flatSearchResult(page: CatalogSearchPage) {
     hasMore: page.hasMore,
     ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
     ...(page.matchMode ? { matchMode: page.matchMode } : {}),
+    ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
   };
 }