@zackbart/connecta 0.4.0 → 0.4.1

package/src/meta-tools.ts

@@ -15,7 +15,7 @@ import {
 } from "./errors.js";
 import type { Registry } from "./registry.js";
 import { AVAILABLE_SKILLS } from "./skills.js";
-import type { KVStorage, ToolDef } from "./types.js";
+import type { ConnectorStatus, KVStorage, ToolDef } from "./types.js";
 
 interface TextContent {
   type: "text";
@@ -72,6 +72,42 @@ function normalizeTimeoutMs(value: number | undefined): number | undefined {
   return Math.max(1, Math.trunc(value));
 }
 
+/**
+ * Generous default bound for a single downstream probe/catalog call in the
+ * list/search/describe fan-out. High enough to trip only on a pathological
+ * hang, not a realistically slow probe.
+ */
+const DEFAULT_PROBE_TIMEOUT_MS = 30_000;
+
+/**
+ * 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.
+ */
+function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  label: string,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      },
+    );
+  });
+}
+
 /**
  * How long to wait before the next attempt, or `undefined` for "don't retry".
  *
@@ -314,11 +350,15 @@ export function createMetaTools(
     maxResultBytes?: number;
     /** Deadline applied when a call passes no `timeoutMs`. Off when unset. */
     defaultToolTimeoutMs?: number;
+    /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
+    probeTimeoutMs?: number;
     activity?: ActivityRequestContext;
   } = {},
 ) {
   const cap = opts.maxResultBytes ?? registry.maxResultBytes;
   const defaultToolTimeoutMs = normalizeTimeoutMs(opts.defaultToolTimeoutMs);
+  const probeTimeoutMs =
+    normalizeTimeoutMs(opts.probeTimeoutMs) ?? DEFAULT_PROBE_TIMEOUT_MS;
   // createMetaTools() is called once per inbound MCP request. Sharing this
   // identity lets remote connectors reuse one downstream client inside that
   // request without leaking request-bound I/O into the next one.
@@ -622,25 +662,45 @@ export function createMetaTools(
           const checkedAt = new Date().toISOString();
           const statusStarted = Date.now();
           const observed = registry.healthFor(c.id);
-          let status = probe
-            ? await registry.statusFor(c.id, baseUrl, requestScope)
-            : {
-                state:
-                  observed?.consecutiveFailures &&
-                  observed.consecutiveFailures > 0
-                    ? ("error" as const)
-                    : observed?.lastSuccessAt || c.kind === "api"
-                      ? ("ok" as const)
-                      : ("unknown" as const),
-                ...(observed?.lastError ? { message: observed.lastError } : {}),
-              };
+          let status:
+            | ConnectorStatus
+            | { state: "ok" | "error" | "unknown"; message?: string };
+          if (probe) {
+            try {
+              status = await withTimeout(
+                registry.statusFor(c.id, baseUrl, requestScope),
+                probeTimeoutMs,
+                `list_connectors probe of "${c.id}"`,
+              );
+            } catch (err) {
+              // A probe that outran probeTimeoutMs (or otherwise threw)
+              // degrades this connector to an error status rather than
+              // hanging the whole list_connectors call.
+              status = { state: "error", message: msg(err) };
+            }
+          } else {
+            status = {
+              state:
+                observed?.consecutiveFailures &&
+                observed.consecutiveFailures > 0
+                  ? ("error" as const)
+                  : observed?.lastSuccessAt || c.kind === "api"
+                    ? ("ok" as const)
+                    : ("unknown" as const),
+              ...(observed?.lastError ? { message: observed.lastError } : {}),
+            };
+          }
           let tools = registry.peekTools(c.id);
           // An auth_required status may have just started OAuth. A second
           // listTools probe would overwrite its state/verifier while returning
           // the first (now stale) authorization URL.
           if (probe && status.state === "ok") {
             try {
-              tools = await registry.refreshTools(c.id, baseUrl, requestScope);
+              tools = await withTimeout(
+                registry.refreshTools(c.id, baseUrl, requestScope),
+                probeTimeoutMs,
+                `list_connectors catalog refresh of "${c.id}"`,
+              );
               registry.recordSuccess(c.id, Date.now() - statusStarted);
             } catch (err) {
               status = { state: "error" as const, message: msg(err) };
@@ -687,7 +747,13 @@ export function createMetaTools(
         order: number;
       }> = [];
       const catalogs = await Promise.allSettled(
-        conns.map((c) => registry.getTools(c.id, baseUrl, requestScope)),
+        conns.map((c) =>
+          withTimeout(
+            registry.getTools(c.id, baseUrl, requestScope),
+            probeTimeoutMs,
+            `search_tools probe of "${c.id}"`,
+          ),
+        ),
       );
       let orderBase = 0;
       catalogs.forEach((catalog, connectorIndex) => {
@@ -791,7 +857,13 @@ export function createMetaTools(
         ),
       ];
       const loaded = await Promise.allSettled(
-        connectorIds.map((id) => registry.getTools(id, baseUrl, requestScope)),
+        connectorIds.map((id) =>
+          withTimeout(
+            registry.getTools(id, baseUrl, requestScope),
+            probeTimeoutMs,
+            `describe_tools probe of "${id}"`,
+          ),
+        ),
       );
       const catalogs = new Map<string, ToolDef[] | Error>();
       loaded.forEach((result, index) => {
@@ -1040,12 +1112,14 @@ export function registerMetaTools(
     baseUrl: string;
     maxResultBytes?: number;
     defaultToolTimeoutMs?: number;
+    probeTimeoutMs?: number;
     activity?: ActivityRequestContext;
   },
 ): void {
   const mt = createMetaTools(registry, ctx.baseUrl, {
     maxResultBytes: ctx.maxResultBytes,
     defaultToolTimeoutMs: ctx.defaultToolTimeoutMs,
+    probeTimeoutMs: ctx.probeTimeoutMs,
     activity: ctx.activity,
   });
 

package/src/server.ts

@@ -49,6 +49,8 @@ export interface ServerOptions {
   deploymentInfo?: Record<string, unknown>;
   /** Deadline for call_tool/batch_call calls that pass no timeoutMs. Off when unset. */
   defaultToolTimeoutMs?: number;
+  /** Per-connector deadline for the list/search/describe probe fan-out. Default 30_000. */
+  probeTimeoutMs?: number;
   /** When set, the execute_code meta-tool is registered on top of the nine. */
   executor?: Executor;
   /** Encrypted connector-credential storage backing the authenticated /ui controls. */
@@ -61,6 +63,14 @@ function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+/** Per-request base64 nonce for the /ui page's inline scripts (Node 20+ and Workers). */
+function uiScriptNonce(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
 function escapeHtml(s: string): string {
   return s
     .replaceAll("&", "&amp;")
@@ -231,9 +241,12 @@ function withSecurityHeaders(
     headers.set("Strict-Transport-Security", "max-age=31536000");
   }
   if (path === "/ui") {
-    // A directive-only CSP does not interfere with the UI's existing scripts,
-    // while preventing the authenticated operator surface from being framed.
-    headers.set("Content-Security-Policy", "frame-ancestors 'none'");
+    // The /ui GET response ships its own nonce-based script CSP (which already
+    // includes frame-ancestors 'none'); only fall back to the framing-only
+    // directive when no CSP is present (e.g. HTTPS redirects, error responses).
+    if (!headers.has("Content-Security-Policy")) {
+      headers.set("Content-Security-Policy", "frame-ancestors 'none'");
+    }
     headers.set("X-Frame-Options", "DENY");
   }
   return new Response(response.body, {
@@ -523,6 +536,7 @@ async function serveMcp(
     baseUrl,
     activity,
     defaultToolTimeoutMs: opts.defaultToolTimeoutMs,
+    probeTimeoutMs: opts.probeTimeoutMs,
   });
   if (opts.executor) {
     registerExecuteTool(server, opts.registry, {
@@ -693,9 +707,22 @@ export function createFetchHandler(
         // Open shell — carries no data; data comes only from the gated /ui/data.
         const uiAuth = auth.find((provider) => provider.uiAuth)?.uiAuth;
         const mcpUrl = new URL("/mcp", baseUrl).toString();
-        return new Response(renderUiHtml(uiAuth, mcpUrl, opts.branding), {
+        // Nonce the page's inline script (and the Clerk loader). 'strict-dynamic'
+        // lets scripts the nonced Clerk loader injects at runtime execute; the
+        // https:/'unsafe-inline' fallbacks are ignored by CSP3 browsers that
+        // honour the nonce and only cover legacy ones. No default-src, so Clerk's
+        // style/font/network needs and the page's inline <style> stay unrestricted
+        // — only script execution, the XSS sink, is gated.
+        const nonce = uiScriptNonce();
+        return new Response(renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce), {
           status: 200,
-          headers: { "Content-Type": "text/html; charset=utf-8" },
+          headers: {
+            "Content-Type": "text/html; charset=utf-8",
+            "Content-Security-Policy":
+              `script-src 'nonce-${nonce}' 'strict-dynamic' https: 'unsafe-inline'; ` +
+              "object-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+            "X-Content-Type-Options": "nosniff",
+          },
         });
       }
 

package/src/storage/file.ts

@@ -1,4 +1,5 @@
 import {
+  chmodSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -28,8 +29,20 @@ export function fileStorage(
   opts: FileStorageOptions = {},
 ): KVStorage {
   const logger: Logger = opts.logger ?? console;
+  // The state file holds downstream OAuth access/refresh tokens in cleartext,
+  // so keep it owner-only. Repair is best-effort: chmod is a no-op or throws on
+  // non-POSIX filesystems, and a loose mode must never keep the store from
+  // starting.
+  const tighten = () => {
+    try {
+      chmodSync(path, 0o600);
+    } catch {
+      // Non-POSIX filesystem or a race on the file — leave the mode as-is.
+    }
+  };
   let data: Record<string, Entry> = {};
   if (existsSync(path)) {
+    tighten();
     try {
       data = JSON.parse(readFileSync(path, "utf8")) as Record<string, Entry>;
     } catch (error) {
@@ -60,10 +73,13 @@ export function fileStorage(
   }
   const persist = () => {
     const dir = dirname(path);
-    if (dir) mkdirSync(dir, { recursive: true });
+    if (dir) mkdirSync(dir, { recursive: true, mode: 0o700 });
     const tmp = `${path}.tmp`;
-    writeFileSync(tmp, JSON.stringify(data));
+    // 0o600 on the tmp file; the atomic rename below preserves it, so the live
+    // state file is never briefly world-readable.
+    writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
     renameSync(tmp, path);
+    tighten();
   };
   const fresh = (key: string): Entry | null => {
     const e = data[key];

package/src/ui.ts

@@ -29,15 +29,16 @@ export function resolveBranding(
 ): ResolvedBranding {
   const productName = branding?.productName?.trim() || "Connecta";
   const ownerName = branding?.ownerName?.trim();
+  // Operator branding URLs become masthead/callback hrefs, so a non-http(s)
+  // scheme (javascript:, data:) is dropped the same as an unset URL — the
+  // callers already render a <span> instead of an <a> when it is absent.
+  const productUrl = branding?.productUrl?.trim();
+  const ownerUrl = branding?.ownerUrl?.trim();
   return {
     productName,
-    ...(branding?.productUrl?.trim()
-      ? { productUrl: branding.productUrl.trim() }
-      : {}),
+    ...(productUrl && isSafeHttpUrl(productUrl) ? { productUrl } : {}),
     ...(ownerName ? { ownerName } : {}),
-    ...(branding?.ownerUrl?.trim()
-      ? { ownerUrl: branding.ownerUrl.trim() }
-      : {}),
+    ...(ownerUrl && isSafeHttpUrl(ownerUrl) ? { ownerUrl } : {}),
     description:
       branding?.description?.trim() ||
       `Manage the services this ${productName} instance makes available to agents.`,
@@ -302,10 +303,14 @@ export function renderUiHtml(
   uiAuth?: UiAuthConfig,
   mcpUrl = "/mcp",
   branding?: ConnectaBranding,
+  nonce?: string,
 ): string {
   const auth = uiAuth ?? { kind: "bearer" as const };
   const brand = resolveBranding(branding);
   const title = brand.pageTitle;
+  // When the /ui response ships a nonce-based CSP, every <script> it emits must
+  // carry that nonce to run; without a nonce the markup is unchanged.
+  const nonceAttr = nonce ? ` nonce="${nonce}"` : "";
   // Top-left corner. With an owner set it reads "<owner> <product>"; without
   // one the product label stands alone. Either half links out when the
   // matching URL is configured.
@@ -323,7 +328,7 @@ export function renderUiHtml(
     : "";
   const clerkScript =
     uiAuth?.kind === "clerk"
-      ? `<script defer crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(uiAuth.publishableKey)}" src="${escapeHtmlAttr(uiAuth.frontendApiUrl)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
+      ? `<script${nonceAttr} defer crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(uiAuth.publishableKey)}" src="${escapeHtmlAttr(uiAuth.frontendApiUrl)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
       : "";
 
   return `<!doctype html>
@@ -683,7 +688,7 @@ ${clerkScript}
   </section>
 </main>
 
-<script>
+<script${nonceAttr}>
 const AUTH = ${jsonForInlineScript(auth)};
 const MCP_URL = ${jsonForInlineScript(mcpUrl)};
 const filterUiConnectors = ${filterUiConnectors.toString()};

package/src/validate.ts

@@ -13,6 +13,28 @@ export interface ValidateToolInputOptions {
    * unusable. Default console.
    */
   logger?: Logger;
+  /**
+   * Fail-closed on a schema the validator cannot evaluate (default false =
+   * today's fail-open behavior). When true, a schema that cannot be compiled —
+   * or that only fails on first use, e.g. an unresolvable `$ref` — yields a
+   * non-retryable `invalid_args` error instead of passing the raw arguments
+   * through, so unvalidated input is never silently admitted. The happy path
+   * (a schema that compiles and validates) is unaffected.
+   */
+  failClosed?: boolean;
+}
+
+export interface PrecompileValidatorOptions {
+  /**
+   * Tool address used in the warning text, conventionally
+   * `"connectorId.toolName"`.
+   */
+  address: string;
+  /**
+   * Destination for the warning emitted when the schema cannot be compiled.
+   * Default console.
+   */
+  logger?: Logger;
 }
 
 // Lazy validator cache keyed by the schema object itself; null marks a schema
@@ -21,6 +43,13 @@ export interface ValidateToolInputOptions {
 // connector are collectable, the same pattern compactSchema uses.
 const validators = new WeakMap<JsonSchema, Validator | null>();
 
+function unevaluableSchema(address: string): ConnectorCallError {
+  return new ConnectorCallError(
+    "invalid_args",
+    `Cannot validate arguments for "${address}": its inputSchema could not be evaluated`,
+  );
+}
+
 function disableValidation(
   schema: JsonSchema,
   address: string,
@@ -47,7 +76,9 @@ function disableValidation(
  *
  * A schema the validator cannot compile (or that only fails on first use, e.g.
  * an unresolvable `$ref`) is warned about once and then passed through — a
- * broken schema should not break an otherwise working tool.
+ * broken schema should not break an otherwise working tool. Pass
+ * `failClosed: true` to instead reject such calls with `invalid_args`, for
+ * callers that would rather refuse a call than forward unvalidated arguments.
  *
  * The compiled validator is cached by **schema object identity**, so pass a
  * stable object: hold the parsed manifest and hand the same schema back on
@@ -74,12 +105,18 @@ export function validateToolInput(
       validator = null;
     }
   }
+  // A schema the validator could not compile (or that a prior call disabled):
+  // pass through by default, refuse when the caller opted into fail-closed.
+  if (validator === null) {
+    return opts.failClosed ? unevaluableSchema(opts.address) : null;
+  }
   let result;
   try {
-    result = validator?.validate(args);
+    result = validator.validate(args);
   } catch (err) {
     // e.g. an unresolvable $ref — surfaces on first validate, not compile.
     disableValidation(schema, opts.address, logger, err);
+    return opts.failClosed ? unevaluableSchema(opts.address) : null;
   }
   if (result && !result.valid) {
     const units = result.errors.filter((u) => u.instanceLocation !== "#");
@@ -94,3 +131,24 @@ export function validateToolInput(
   }
   return null;
 }
+
+/**
+ * Eagerly compile and cache a tool's inputSchema so a schema the validator
+ * cannot use surfaces once at connector construction rather than silently on
+ * the first call. Reuses the same module-level cache `validateToolInput` reads,
+ * so the runtime path hits the cache. Warning-only: it never throws and never
+ * changes call behavior. A schema that only fails on first `validate()` (e.g.
+ * an unresolvable `$ref`) still slips through here and is caught at call time.
+ */
+export function precompileValidator(
+  schema: JsonSchema,
+  opts: PrecompileValidatorOptions,
+): void {
+  if (validators.has(schema)) return;
+  const logger = opts.logger ?? console;
+  try {
+    validators.set(schema, new Validator(schema as never, "2020-12", false));
+  } catch (err) {
+    disableValidation(schema, opts.address, logger, err);
+  }
+}

package/src/version.ts

@@ -4,4 +4,4 @@
  * 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.4.0";
+export const CONNECTA_VERSION = "0.4.1";