@zackbart/connecta 0.7.0 → 0.7.3

package/src/registry.ts

@@ -6,7 +6,11 @@ import type {
   Logger,
   ToolDef,
 } from "./types.js";
-import type { CredentialVault } from "./credentials.js";
+import {
+  storedCredentialShape,
+  type CredentialVault,
+} from "./credentials.js";
+import { ConnectorCallError } from "./errors.js";
 import {
   CredentialHealthChecker,
   type CredentialCheckOptions,
@@ -154,6 +158,11 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+type ConnectorOperationOptions = Pick<
+  ConnectorContext,
+  "signal" | "timeoutMs"
+>;
+
 /**
  * The registry surface a per-connection MCP server consumes: every meta-tool
  * (`src/meta-tools.ts`) and the `execute_code` sandbox bridge (`src/execute.ts`)
@@ -178,18 +187,20 @@ export interface RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions?: ConnectorOperationOptions,
   ): Promise<ToolDef[]>;
   refreshTools(
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions?: ConnectorOperationOptions,
   ): Promise<ToolDef[]>;
   peekTools(id: string): ToolDef[] | undefined;
   contextFor(
     id: string,
     baseUrl: string,
     requestScope?: object,
-    callOptions?: { signal?: AbortSignal; timeoutMs?: number },
+    callOptions?: ConnectorOperationOptions,
   ): ConnectorContext;
   resultsStorage(): KVStorage;
   recordSuccess(id: string, latencyMs: number): void;
@@ -209,6 +220,7 @@ export interface RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions?: ConnectorOperationOptions,
   ): Promise<ConnectorStatus>;
   invalidateStored(id: string): Promise<void>;
 }
@@ -352,21 +364,31 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
-    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
+    callOptions: ConnectorOperationOptions = {},
   ): ConnectorContext {
+    const credentialConfig = this.connectors.get(id)?.credential;
+    let credentialAccess: ConnectorContext["credential"];
+    if (this.opts.credentialVault && credentialConfig) {
+      const vault = this.opts.credentialVault;
+      const readValues = async () => {
+        const values = await vault.getAll(id);
+        const shape = storedCredentialShape(credentialConfig, values);
+        if (shape.state === "mismatch") {
+          throw new ConnectorCallError("auth_required", shape.message);
+        }
+        return values;
+      };
+      credentialAccess = {
+        get: async (field = "value") =>
+          (await readValues())?.[field] ?? null,
+        getAll: readValues,
+      };
+    }
     return {
       storage: namespaced(this.opts.storage, `conn:${id}:`),
       logger: this.opts.logger,
       baseUrl,
-      ...(this.opts.credentialVault && this.connectors.get(id)?.credential
-        ? {
-            credential: {
-              get: (field?: string) =>
-                this.opts.credentialVault!.get(id, field),
-              getAll: () => this.opts.credentialVault!.getAll(id),
-            },
-          }
-        : {}),
+      ...(credentialAccess ? { credential: credentialAccess } : {}),
       requestScope,
       ...callOptions,
     };
@@ -441,13 +463,14 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
     const tools = connector.staticTools
       ? connector.staticTools
       : await connector.listTools(
-          this.contextFor(id, baseUrl, requestScope),
+          this.contextFor(id, baseUrl, requestScope, callOptions),
         );
     const now = Date.now();
     const previous = this.cache.get(id);
@@ -479,6 +502,7 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     const connector = this.connectors.get(id);
     if (!connector) throw new Error(`Unknown connector "${id}"`);
@@ -512,7 +536,7 @@ export class Registry implements RegistryView {
     }
 
     try {
-      return await this.refreshTools(id, baseUrl, requestScope);
+      return await this.refreshTools(id, baseUrl, requestScope, callOptions);
     } catch (err) {
       if (stale) {
         this.opts.logger.warn(
@@ -626,10 +650,11 @@ export class Registry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ConnectorStatus> {
     const connector = this.connectors.get(id);
     if (!connector) return { state: "error", message: "Unknown connector" };
-    const ctx = this.contextFor(id, baseUrl, requestScope);
+    const ctx = this.contextFor(id, baseUrl, requestScope, callOptions);
     if (connector.status) {
       try {
         return await connector.status(ctx);
@@ -638,7 +663,7 @@ export class Registry implements RegistryView {
       }
     }
     try {
-      await this.getTools(id, baseUrl, requestScope);
+      await this.getTools(id, baseUrl, requestScope, callOptions);
       return { state: "ok" };
     } catch (err) {
       return { state: "error", message: msg(err) };
@@ -782,11 +807,12 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     if (!this.visible(id)) throw this.unknownConnector(id);
     return this.inScopeTools(
       id,
-      await this.base.getTools(id, baseUrl, requestScope),
+      await this.base.getTools(id, baseUrl, requestScope, callOptions),
     );
   }
 
@@ -794,11 +820,12 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope?: object,
+    callOptions: ConnectorOperationOptions = {},
   ): Promise<ToolDef[]> {
     if (!this.visible(id)) throw this.unknownConnector(id);
     return this.inScopeTools(
       id,
-      await this.base.refreshTools(id, baseUrl, requestScope),
+      await this.base.refreshTools(id, baseUrl, requestScope, callOptions),
     );
   }
 
@@ -812,7 +839,7 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
-    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
+    callOptions: ConnectorOperationOptions = {},
   ): ConnectorContext {
     // Unreachable through the meta-tools (they resolve first), so a throw here
     // is a loud backstop rather than a silent grant of connector storage and
@@ -897,12 +924,13 @@ export class ScopedRegistry implements RegistryView {
     id: string,
     baseUrl: string,
     requestScope: object = {},
+    callOptions: { signal?: AbortSignal; timeoutMs?: number } = {},
   ): Promise<ConnectorStatus> {
     // Same shape the unscoped registry returns for an unregistered id.
     if (!this.visible(id)) {
       return { state: "error", message: "Unknown connector" };
     }
-    return this.base.statusFor(id, baseUrl, requestScope);
+    return this.base.statusFor(id, baseUrl, requestScope, callOptions);
   }
 
   async invalidateStored(id: string): Promise<void> {

package/src/server.ts

@@ -222,8 +222,8 @@ async function authorize(
   | {
       ok: true;
       actor: ActivityActor;
-      providerKind?: string;
-      userId?: string;
+      /** True only when the admitting provider can also authorize UI mutation. */
+      uiAdminEligible?: boolean;
       /** The admitting identity's toolkit binding (docs/toolkits.md). */
       toolkitBinding?: ToolkitBinding;
     }
@@ -261,8 +261,9 @@ async function authorize(
           kind: provider.kind,
           ...(subjectId ? { id: subjectId } : {}),
         },
-        providerKind: provider.kind,
-        ...(result.userId ? { userId: result.userId } : {}),
+        ...(result.userId && provider.uiAuth?.kind === "clerk"
+          ? { uiAdminEligible: true }
+          : {}),
         ...(binding.binding ? { toolkitBinding: binding.binding } : {}),
       };
     }
@@ -1088,7 +1089,15 @@ export function createFetchHandler(
       // Canonicalize the legacy bookmark while upgrading it so an old /ui URL
       // reaches the new Connections entry point in one permanent redirect.
       const targetPath = path === "/ui" ? "/" : url.pathname;
-      const target = new URL(`${targetPath}${url.search}`, publicUrl);
+      // Assign the path and query onto the configured URL instead of resolving
+      // attacker-controlled text against it. A pathname beginning with `//`
+      // (including a backslash form normalized by URL parsing) is an authority
+      // when passed to `new URL(value, base)` and would otherwise replace the
+      // deployment host.
+      const target = new URL(publicUrl);
+      target.pathname = targetPath;
+      target.search = url.search;
+      target.hash = "";
       return withSecurityHeaders(
         new Response(null, {
           status: 308,
@@ -1189,7 +1198,7 @@ export function createFetchHandler(
 
       const operatorPage = operatorPageForPath(path);
       if (operatorPage) {
-        if (request.method !== "GET") {
+        if (request.method !== "GET" && request.method !== "HEAD") {
           return privateJson({ error: "method not allowed" }, { status: 405 });
         }
         // Open shell — carries no operator data; everything comes from the
@@ -1204,7 +1213,9 @@ export function createFetchHandler(
         // — only script execution, the XSS sink, is gated.
         const nonce = uiScriptNonce();
         return new Response(
-          renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage),
+          request.method === "HEAD"
+            ? null
+            : renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage),
           {
             status: 200,
             headers: {
@@ -1227,8 +1238,7 @@ export function createFetchHandler(
         // After the restriction check, not before: an identity that may not
         // read this surface should not get to trigger background work from it.
         sweepCredentials();
-        const eligibleClerkOperator =
-          authz.providerKind === "clerk" && Boolean(authz.userId);
+        const eligibleClerkOperator = authz.uiAdminEligible === true;
         const credentialManagement = credentialManagementCapability({
           eligibleClerkOperator,
           hasCredentialSlots: registry
@@ -1245,6 +1255,7 @@ export function createFetchHandler(
           eligibleClerkOperator ? opts.credentialVault : undefined,
           Boolean(opts.activity?.list),
           credentialManagement,
+          opts.toolkits,
         );
         return privateJson(data);
       }

package/src/timeout.ts

@@ -21,10 +21,9 @@ export function normalizeTimeoutMs(
 
 /**
  * Reject `promise` after `ms` if it has not settled, so one hung downstream
- * cannot stall a whole fan-out. NOTE: this bounds only the caller-facing wait —
- * the registry probe methods take no AbortSignal, so the underlying fetch is
- * NOT cancelled and keeps running in the background. Real cancellation
- * (AbortSignal plumbed through the registry) is a deferred follow-up.
+ * cannot stall a whole fan-out. This form bounds only the caller-facing wait;
+ * use `withAbortableTimeout` when the operation accepts an AbortSignal and the
+ * underlying work must stop too.
  */
 export function withTimeout<T>(
   promise: Promise<T>,
@@ -47,3 +46,41 @@ export function withTimeout<T>(
     );
   });
 }
+
+/**
+ * Give one operation a caller-facing deadline and the matching cancellation
+ * signal. The timeout rejects with the stable, labelled error while aborting
+ * any in-flight work that honors the signal.
+ */
+export function withAbortableTimeout<T>(
+  operation: (signal: AbortSignal) => Promise<T>,
+  ms: number,
+  label: string,
+): Promise<T> {
+  const controller = new AbortController();
+  return new Promise<T>((resolve, reject) => {
+    const timeoutError = new Error(`${label} timed out after ${ms}ms`);
+    const timer = setTimeout(() => {
+      controller.abort(timeoutError);
+      reject(timeoutError);
+    }, ms);
+    let promise: Promise<T>;
+    try {
+      promise = operation(controller.signal);
+    } catch (err) {
+      clearTimeout(timer);
+      reject(err);
+      return;
+    }
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}

package/src/toolkits.ts

@@ -41,6 +41,14 @@ export type ToolkitConfig = Record<string, ToolkitDefinition>;
 export interface Toolkit {
   readonly name: string;
   readonly description?: string;
+  /**
+   * The validated config this scope came from. Kept as immutable data so
+   * deployment-wide operator surfaces can explain the running configuration
+   * without inventing a second source of truth.
+   */
+  readonly connectors: readonly string[];
+  readonly includeTools: readonly string[];
+  readonly excludeTools: readonly string[];
   /** True when `connectorId` is inside this toolkit's scope. */
   hasConnector(connectorId: string): boolean;
   /** True when `<connectorId>.<toolName>` is inside this toolkit's scope. */
@@ -178,6 +186,9 @@ function resolveToolkit(
   return {
     name,
     ...(definition.description ? { description: definition.description } : {}),
+    connectors: Object.freeze([...connectorIds]),
+    includeTools: Object.freeze([...(definition.includeTools ?? [])]),
+    excludeTools: Object.freeze([...(definition.excludeTools ?? [])]),
     hasConnector: (connectorId) => connectorIds.has(connectorId),
     hasTool: (connectorId, toolName) => {
       if (!connectorIds.has(connectorId)) return false;

package/src/types.ts

@@ -113,9 +113,9 @@ export interface ConnectorContext {
    * when omitted.
    */
   requestScope?: object;
-  /** Best-effort cancellation signal for this individual tool call. */
+  /** Best-effort cancellation signal for this connector operation. */
   signal?: AbortSignal;
-  /** Requested tool-call deadline in milliseconds. */
+  /** Requested connector-operation deadline in milliseconds. */
   timeoutMs?: number;
 }