@zackbart/connecta 0.10.0 → 0.10.2

package/dist/access-tokens.js

@@ -0,0 +1,225 @@
+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.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,
+        };
+        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 };
+    }
+}
+//# sourceMappingURL=access-tokens.js.map

package/dist/access-tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-tokens.js","sourceRoot":"","sources":["../src/access-tokens.ts"],"names":[],"mappings":"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"}

package/dist/catalog-service.d.ts

@@ -14,6 +14,11 @@ export declare function boundedDiscoveryText(value: unknown, hint: string): stri
 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;
@@ -35,6 +40,8 @@ interface CatalogSearchEntry {
         description?: string;
         inputSchema?: unknown;
         outputSchema?: unknown;
+        inputSchemaTruncated?: true;
+        outputSchemaTruncated?: true;
         inputKeys?: string[];
         requiredInputKeys?: string[];
         outputKeys?: string[];
@@ -49,6 +56,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 {
     address: string;
@@ -108,12 +125,21 @@ export declare class CatalogService {
     describe(args: CatalogDescribeArgs): Promise<CatalogDescription[]>;
 }
 export declare function groupedSearchResult(page: CatalogSearchPage): {
+    queryAnalysis?: {
+        representedTerms: string[];
+        otherResultTerms: string[];
+        unmatchedTerms: string[];
+        truncated?: true;
+        connectorScope?: string;
+        unknownConnector?: true;
+        unavailableConnectorCount?: number;
+        guidance?: string;
+    };
     matchMode?: "partial";
     nextOffset?: number;
     connectors: {
         id: string;
         title?: string;
-        description?: string;
         guide?: string;
         tools: CatalogSearchEntry["tool"][];
     }[];
@@ -123,6 +149,16 @@ export declare function groupedSearchResult(page: CatalogSearchPage): {
     hasMore: boolean;
 };
 export declare function flatSearchResult(page: CatalogSearchPage): {
+    queryAnalysis?: {
+        representedTerms: string[];
+        otherResultTerms: string[];
+        unmatchedTerms: string[];
+        truncated?: true;
+        connectorScope?: string;
+        unknownConnector?: true;
+        unavailableConnectorCount?: number;
+        guidance?: string;
+    };
     matchMode?: "partial";
     nextOffset?: number;
     tools: {
@@ -131,6 +167,8 @@ export declare function flatSearchResult(page: CatalogSearchPage): {
         description?: string;
         inputSchema?: unknown;
         outputSchema?: unknown;
+        inputSchemaTruncated?: true;
+        outputSchemaTruncated?: true;
         inputKeys?: string[];
         requiredInputKeys?: string[];
         outputKeys?: string[];

package/dist/catalog-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-service.d.ts","sourceRoot":"","sources":["../src/catalog-service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"catalog-service.d.ts","sourceRoot":"","sources":["../src/catalog-service.ts"],"names":[],"mappings":"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"}

package/dist/catalog-service.js

@@ -1,12 +1,15 @@
-import { compactSchema, lexicalCorpusStatistics, lexicalSearchQuery, rankTools, schemaObjectKeys, summarizeDescription, } from "./catalog.js";
+import { compactDiscoverySchema, compactSchema, lexicalCorpusStatistics, lexicalQueryTerms, lexicalSearchQuery, rankTools, schemaObjectKeys, summarizeDiscoveryDescription, summarizeDescription, } from "./catalog.js";
 import { mapSettledWithConcurrency, resolveDiscoveryConcurrency, } from "./concurrency.js";
 import { classifyCallError, framingError } from "./errors.js";
 import { connectorGuide, connectorSkillName, } from "./skills.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withAbortableTimeout, } from "./timeout.js";
+import { isExplicitlyReadOnly } from "./tool-safety.js";
 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();
 export class DiscoveryPolicyError extends Error {
     code;
@@ -50,6 +53,23 @@ export function boundedDiscoveryText(value, hint) {
     }
     return text;
 }
+function discoverySafety(value) {
+    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, safety) {
+    if (safety === "all")
+        return tools;
+    return tools.filter((tool) => safety === "readOnly"
+        ? isExplicitlyReadOnly(tool)
+        : !isExplicitlyReadOnly(tool));
+}
 /**
  * Code-mode key metadata for one match. Each half is omitted when its schema
  * does not resolve to an object shape, so a program reads "no metadata, use the
@@ -71,6 +91,12 @@ function schemaKeyMetadata(input, output) {
 function renderSchema(schema, format) {
     return format === "json" ? schema : compactSchema(schema);
 }
+function renderSearchSchema(schema, format) {
+    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
@@ -230,19 +256,31 @@ export class CatalogService {
     async search(args) {
         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) => Boolean(connector))
+            ? scopedConnector
+                ? [scopedConnector]
+                : []
             : this.registry.listConnectors();
         const catalogs = await mapSettledWithConcurrency(connectors, this.concurrency, (connector) => this.loadForDiscovery(connector.id, `search_tools probe of "${connector.id}"`));
+        const searchableCatalogs = catalogs.map((catalog) => catalog.status === "fulfilled"
+            ? {
+                status: "fulfilled",
+                value: toolsForSafety(catalog.value, safety),
+            }
+            : catalog);
         const matches = [];
         let matchMode = "all";
-        const statistics = lexicalCorpusStatistics(catalogs.flatMap((catalog) => catalog.status === "fulfilled" ? [catalog.value] : []), retrievalQuery);
+        const statistics = lexicalCorpusStatistics(searchableCatalogs.flatMap((catalog) => catalog.status === "fulfilled" ? [catalog.value] : []), retrievalQuery);
         const collectMatches = (mode) => {
             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");
@@ -267,9 +305,16 @@ 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(match.tool.description, args.fullDescriptions === true);
+            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);
             return {
                 connector: match.connector,
                 ...(connectorGuide(match.connector)
@@ -281,14 +326,20 @@ export class CatalogService {
                     ...(description !== undefined ? { description } : {}),
                     ...(args.includeSchemas
                         ? {
-                            inputSchema: renderSchema(input, args.includeSchemas),
+                            inputSchema: renderedInput?.schema,
                         }
                         : {}),
+                    ...(renderedInput?.truncated
+                        ? { inputSchemaTruncated: true }
+                        : {}),
                     ...(args.includeSchemas && match.tool.outputSchema
                         ? {
-                            outputSchema: renderSchema(match.tool.outputSchema, args.includeSchemas),
+                            outputSchema: renderedOutput?.schema,
                         }
                         : {}),
+                    ...(renderedOutput?.truncated
+                        ? { outputSchemaTruncated: true }
+                        : {}),
                     ...(args.includeSchemas && args.includeSchemaKeys
                         ? schemaKeyMetadata(input, match.tool.outputSchema)
                         : {}),
@@ -301,6 +352,57 @@ export class CatalogService {
         const nextOffset = 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) => 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) => new Set([
+            ...(statistics.nameMatches.get(term) ?? []),
+            ...(statistics.descriptionMatches.get(term) ?? []),
+        ]);
+        const representedTerms = [];
+        const otherResultTerms = [];
+        const unmatchedTerms = [];
+        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,
@@ -311,6 +413,27 @@ 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 }
+                            : {}),
+                        ...(args.connector ? { connectorScope: args.connector } : {}),
+                        ...(args.connector && !scopedConnector
+                            ? { unknownConnector: true }
+                            : {}),
+                        ...(unavailableCatalogs > 0
+                            ? { unavailableConnectorCount: unavailableCatalogs }
+                            : {}),
+                        ...(guidance ? { guidance } : {}),
+                    },
+                }
+                : {}),
         };
     }
     async describe(args) {
@@ -385,9 +508,6 @@ export function groupedSearchResult(page) {
             const group = {
                 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: [],
             };
@@ -404,6 +524,7 @@ export function groupedSearchResult(page) {
         hasMore: page.hasMore,
         ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
         ...(page.matchMode ? { matchMode: page.matchMode } : {}),
+        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
     };
 }
 export function flatSearchResult(page) {
@@ -415,6 +536,7 @@ export function flatSearchResult(page) {
         hasMore: page.hasMore,
         ...(page.nextOffset !== undefined ? { nextOffset: page.nextOffset } : {}),
         ...(page.matchMode ? { matchMode: page.matchMode } : {}),
+        ...(page.queryAnalysis ? { queryAnalysis: page.queryAnalysis } : {}),
     };
 }
 //# sourceMappingURL=catalog-service.js.map