@zackbart/connecta 0.3.0 → 0.4.1

package/src/errors.ts

@@ -19,6 +19,13 @@ const RETRYABLE_BY_CODE: Record<ConnectorCallErrorCode, boolean> = {
   connector_call_failed: false,
 };
 
+/** Non-negative integer milliseconds, or undefined for anything else. */
+function normalizeRetryAfterMs(value: number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isFinite(value) || value < 0) return undefined;
+  return Math.trunc(value);
+}
+
 /**
  * Throw from `Connector.callTool` (or anything beneath it) to classify a
  * failure exactly. Untyped errors fall back to a message-text heuristic, so a
@@ -26,15 +33,28 @@ const RETRYABLE_BY_CODE: Record<ConnectorCallErrorCode, boolean> = {
  * retryable timeout — this class is the escape hatch. `retryable` defaults per
  * code (timeout, rate_limited, and unavailable retry; the rest do not) and may
  * be overridden.
+ *
+ * `retryAfterMs` carries a wait window the connector already knows — a
+ * `Retry-After` header, say — so the engine can wait that long instead of
+ * guessing, and so an agent that receives the failure can decide when to
+ * re-issue.
  */
 export class ConnectorCallError extends Error {
   readonly code: ConnectorCallErrorCode;
   readonly retryable: boolean;
+  /**
+   * Connector-known wait window in ms before this call is worth repeating,
+   * or undefined when the connector reported none. Always an own property —
+   * under ES2022 class fields the declaration itself defines it, so guarding
+   * the assignment would not keep it off the instance. Keeping the window out
+   * of the wire format is `classifyCallError`'s job, not this constructor's.
+   */
+  readonly retryAfterMs?: number;
 
   constructor(
     code: ConnectorCallErrorCode,
     message: string,
-    opts: { retryable?: boolean; cause?: unknown } = {},
+    opts: { retryable?: boolean; retryAfterMs?: number; cause?: unknown } = {},
   ) {
     super(
       message,
@@ -43,6 +63,7 @@ export class ConnectorCallError extends Error {
     this.name = "ConnectorCallError";
     this.code = code;
     this.retryable = opts.retryable ?? RETRYABLE_BY_CODE[code];
+    this.retryAfterMs = normalizeRetryAfterMs(opts.retryAfterMs);
   }
 }
 
@@ -51,6 +72,12 @@ export interface CallErrorDetails {
   code: string;
   message: string;
   retryable: boolean;
+  /**
+   * Connector-reported wait window in ms, when known. Reported verbatim — the
+   * engine bounds how long it will itself wait, but the caller sees the real
+   * window so it can schedule a re-issue.
+   */
+  retryAfterMs?: number;
 }
 
 const RETRYABLE_MESSAGE_RE =
@@ -72,7 +99,23 @@ export function classifyCallError(
   fallbackCode = "connector_call_failed",
 ): CallErrorDetails {
   if (err instanceof ConnectorCallError) {
-    return { code: err.code, message: err.message, retryable: err.retryable };
+    return {
+      code: err.code,
+      message: err.message,
+      retryable: err.retryable,
+      ...(err.retryAfterMs !== undefined
+        ? { retryAfterMs: err.retryAfterMs }
+        : {}),
+    };
+  }
+  // An aborted fetch rejects with a DOMException named "AbortError" whose
+  // message ("The operation was aborted", and variants across runtimes) matches
+  // neither heuristic below — so a call the engine itself cancelled would read
+  // as a non-retryable failure, the opposite of the truth. Note this also
+  // covers an abort the connector triggered for its own reasons; running out of
+  // time is by far the likelier cause and retryable/timeout is the safer read.
+  if (err instanceof Error && err.name === "AbortError") {
+    return { code: "timeout", message: err.message, retryable: true };
   }
   const message = err instanceof Error ? err.message : String(err);
   return {

package/src/executors/quickjs.ts

@@ -32,6 +32,14 @@ export interface QuickJsExecutorOptions {
 }
 
 const MAX_LOG_ENTRIES = 200;
+// Cap each entry AND the cumulative buffer at capture time so untrusted guest
+// code can't retain unbounded host memory: a single `console.log("x".repeat(N))`
+// otherwise copies the whole N-char guest string into a host array we hold for
+// the entire execution. 8k chars/entry is generous for glue-code logging (the
+// join in execute.ts trims the assembled log to 4k anyway), and 256k total
+// keeps the worst case — 200 maxed-out entries — bounded well under a MiB.
+const MAX_LOG_ENTRY_CHARS = 8_000;
+const MAX_LOG_TOTAL_CHARS = 256_000;
 
 function msg(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
@@ -123,12 +131,32 @@ function installBridge(
   };
   armWake(bridge);
 
+  // Running total of chars actually retained in `logs`; once the cumulative
+  // budget is spent we push one marker and drop the rest, so a flood of large
+  // entries can't grow the host array without bound.
+  let logTotalChars = 0;
+  let logBudgetSpent = false;
   const logFn = ctx.newFunction("__log", (h) => {
-    if (logs.length < MAX_LOG_ENTRIES) {
-      logs.push(ctx.getString(h));
-    } else if (logs.length === MAX_LOG_ENTRIES) {
-      logs.push(`[log truncated after ${MAX_LOG_ENTRIES} entries]`);
+    if (logs.length >= MAX_LOG_ENTRIES) {
+      if (logs.length === MAX_LOG_ENTRIES) {
+        logs.push(`[log truncated after ${MAX_LOG_ENTRIES} entries]`);
+      }
+      return;
+    }
+    if (logBudgetSpent) return;
+    // Cap the entry before retaining it: `getString` yields a transient copy,
+    // but slicing here keeps only a bounded string alive in `logs`.
+    let entry = ctx.getString(h);
+    if (entry.length > MAX_LOG_ENTRY_CHARS) {
+      entry = `${entry.slice(0, MAX_LOG_ENTRY_CHARS)}…[entry truncated]`;
+    }
+    if (logTotalChars + entry.length > MAX_LOG_TOTAL_CHARS) {
+      logs.push("[log truncated: size budget exceeded]");
+      logBudgetSpent = true;
+      return;
     }
+    logs.push(entry);
+    logTotalChars += entry.length;
   });
   ctx.setProp(ctx.global, "__log", logFn);
   logFn.dispose();

package/src/index.ts

@@ -61,6 +61,38 @@ export interface ConnectaConfig {
    * stash the full text for get_result paging. Default 50_000.
    */
   maxResultBytes?: number;
+  /**
+   * Deadline (ms) applied to call_tool/batch_call calls that pass no
+   * `timeoutMs`, giving the connector both a budget (`ctx.timeoutMs`) and a
+   * cancellation signal (`ctx.signal`). An explicit per-call `timeoutMs` always
+   * wins. **Opt-in — undefined by default**, because switching it on globally
+   * would put a deadline on every call in an existing deployment and the
+   * failure mode is a working long-running call starting to time out.
+   * `execute_code` host calls are unaffected; they already carry a 15 s bound.
+   *
+   * Bounds a single attempt, not the whole call — the same as an explicit
+   * `timeoutMs` has always done. A call that also passes `maxRetries` can
+   * therefore run to roughly `(maxRetries + 1)` times this value plus backoff.
+   * `maxRetries` defaults to 0, so this is the total for every call that does
+   * not explicitly ask to retry.
+   */
+  defaultToolTimeoutMs?: number;
+  /**
+   * Deadline (ms) applied to each individual downstream probe/catalog call that
+   * the discovery meta-tools fan out — `list_connectors` (with `probe`),
+   * `search_tools`, and `describe_tools` — so a single hung connector can no
+   * longer stall the whole meta-tool call. **Defaults to a generous 30_000**,
+   * chosen to trip only on a pathological hang, not on a realistically slow
+   * probe, so having it on by default will not break existing deployments.
+   * Bounds one downstream call, not the whole fan-out: a connector that outruns
+   * it degrades to an unavailable/errored entry while the rest are unaffected.
+   *
+   * Does NOT apply to `call_tool`/`batch_call` — those carry their own budget
+   * via `defaultToolTimeoutMs` or a per-call `timeoutMs`. Note this bounds the
+   * caller-facing wait only; the underlying fetch is not currently aborted, so
+   * real cancellation of the downstream request is a deferred follow-up.
+   */
+  probeTimeoutMs?: number;
   serverInfo?: {
     name?: string;
     version?: string;
@@ -106,6 +138,58 @@ function normalizeAuth(auth: ConnectaConfig["auth"]): InboundAuth[] {
   });
 }
 
+/**
+ * One-time construction warnings for deployment shapes that run fine but are
+ * usually unintended. Warning-only — never throws and never changes behavior;
+ * each condition emits at most one `logger.warn`. Iterates connectors once.
+ */
+function warnInsecureConfig(
+  config: ConnectaConfig,
+  inboundAuth: InboundAuth[],
+  logger: Logger,
+): void {
+  const oauthConnectors = config.connectors.filter((c) => c.finishAuth);
+  const hasCredentialConnector = config.connectors.some((c) => c.credential);
+
+  // Open mode (no inbound auth) with connectors that expose credentials or
+  // downstream OAuth: any caller reaches everything, including the vault.
+  if (
+    inboundAuth.length === 0 &&
+    (hasCredentialConnector || oauthConnectors.length > 0)
+  ) {
+    logger.warn(
+      "[connecta] running with no inbound authentication: any caller can " +
+        "invoke every connector and read or overwrite stored credentials. " +
+        "Configure `auth` (for example bearerToken(...) or Clerk) to gate access.",
+    );
+  }
+
+  // Unset publicUrl with OAuth connectors: the downstream redirect_uri is
+  // derived per-request from the attacker-influenced inbound Host header.
+  if (oauthConnectors.length > 0 && !config.publicUrl) {
+    logger.warn(
+      "[connecta] publicUrl is unset while OAuth connectors are configured: " +
+        "the downstream OAuth redirect_uri is derived per-request from the " +
+        "inbound Host header, so an attacker who controls that header can point " +
+        "it at their own host and capture the authorization code. Set " +
+        "`publicUrl` to a fixed https origin.",
+    );
+  }
+
+  // OAuth connectors whose callback performs no state/CSRF check: the public
+  // /oauth/callback/<id> route would exchange any delivered code.
+  for (const connector of oauthConnectors) {
+    if (!connector.verifyState) {
+      logger.warn(
+        `[connecta] connector "${connector.id}" has an OAuth callback with no ` +
+          `state/CSRF check: /oauth/callback/${connector.id} will exchange any ` +
+          "delivered code. Implement `verifyState` (the shipped remoteMcp " +
+          "connector already does).",
+      );
+    }
+  }
+}
+
 export function createConnecta(config: ConnectaConfig): Connecta {
   const storage = config.storage ?? memoryStorage();
   const logger = config.logger ?? defaultLogger();
@@ -127,9 +211,11 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     toolCatalogStaleSeconds: config.toolCatalogStaleSeconds,
     maxResultBytes: config.maxResultBytes,
   });
+  const inboundAuth = normalizeAuth(config.auth);
+  warnInsecureConfig(config, inboundAuth, logger);
   const handler = createFetchHandler({
     registry,
-    auth: normalizeAuth(config.auth),
+    auth: inboundAuth,
     publicUrl: config.publicUrl,
     serverInfo: {
       ...config.serverInfo,
@@ -141,6 +227,8 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     activityReadGate: config.activityReadGate,
     activityDeploymentId: config.activityDeploymentId,
     executor: config.executor,
+    defaultToolTimeoutMs: config.defaultToolTimeoutMs,
+    probeTimeoutMs: config.probeTimeoutMs,
     credentialVault,
     deploymentInfo: config.deploymentInfo,
     branding: config.branding,
@@ -161,6 +249,11 @@ export { remoteMcp } from "./connectors/remote-mcp.js";
 export { api } from "./connectors/api.js";
 export { ConnectorCallError } from "./errors.js";
 export type { ConnectorCallErrorCode, CallErrorDetails } from "./errors.js";
+// The same argument validation api() performs, usable by connectors that
+// implement the Connector interface directly. Returns the error rather than
+// throwing so the caller decides what to do with it.
+export { validateToolInput } from "./validate.js";
+export type { ValidateToolInputOptions } from "./validate.js";
 export { bearerToken } from "./auth/bearer.js";
 export { memoryStorage } from "./storage/memory.js";
 export { CONNECTA_VERSION } from "./version.js";

package/src/json-schema.ts

@@ -0,0 +1,11 @@
+// Public re-export of the JSON Schema validator connecta itself uses, so
+// downstream code that validates at build time (a manifest generator asserting
+// its own output, say) resolves the same implementation and version through an
+// explicit subpath rather than through npm hoisting.
+export { Validator } from "@cfworker/json-schema";
+export type {
+  OutputUnit,
+  Schema,
+  SchemaDraft,
+  ValidationResult,
+} from "@cfworker/json-schema";

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";
@@ -53,6 +53,85 @@ const dec = new TextDecoder();
 
 type ErrorDetails = CallErrorDetails;
 
+/**
+ * The longest the engine will park a synchronous inbound request in *waiting
+ * alone*. The engine already treats ~15 s as the outer bound of one reasonable
+ * connector call (EXECUTE_HOST_CALL_TIMEOUT_MS), so sleeping for minutes trades
+ * a fast, informative failure for a hung one. A connector-reported window this
+ * long isn't truncated — it's declined (see `retryBackoffMs`) and reported
+ * verbatim as `error.retryAfterMs`, so the agent, which can afford to wait,
+ * decides when to re-issue.
+ */
+export const MAX_RETRY_BACKOFF_MS = 10_000;
+
+/** A finite, positive integer number of milliseconds, or undefined. */
+function normalizeTimeoutMs(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value) || !(value > 0)) {
+    return 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".
+ *
+ * A connector that read a `Retry-After` header knows the window exactly, so it
+ * is honoured **exactly or not at all**: truncating an exponential *guess* is
+ * harmless, but truncating a *known* window means deliberately retrying inside
+ * a rate limit — the harm this channel exists to prevent. A window longer than
+ * `MAX_RETRY_BACKOFF_MS` therefore declines the retry rather than shortening
+ * it. (`retryAfterMs` is normalized non-negative, so `0` means "retry now".)
+ * Connectors that report no window keep the historical exponential guess.
+ *
+ * Waits are per attempt, matching the per-attempt `timeoutMs` race in
+ * `runCall`. Exported for direct testing.
+ */
+export function retryBackoffMs(
+  attempt: number,
+  retryAfterMs: number | undefined,
+): number | undefined {
+  if (retryAfterMs === undefined) {
+    return Math.min(250 * 2 ** (attempt - 1), 1_000);
+  }
+  return retryAfterMs <= MAX_RETRY_BACKOFF_MS ? retryAfterMs : undefined;
+}
+
 /** Details for failures that never reached a connector (no thrown value). */
 function errorDetails(code: string, message: string): ErrorDetails {
   return { code, message, retryable: messageLooksRetryable(message) };
@@ -260,18 +339,26 @@ export interface SkillArgs {
 /**
  * The nine meta-tool handlers over a registry. Exported for direct testing;
  * registerMetaTools() wires them onto an McpServer. `opts.maxResultBytes`
- * overrides the registry's default result-size cap. (execute_code, the optional
- * tenth tool, is registered separately by registerExecuteTool.)
+ * overrides the registry's default result-size cap; `opts.defaultToolTimeoutMs`
+ * supplies a deadline for calls that don't carry one. (execute_code, the
+ * optional tenth tool, is registered separately by registerExecuteTool.)
  */
 export function createMetaTools(
   registry: Registry,
   baseUrl: string,
   opts: {
     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.
@@ -356,10 +443,9 @@ export function createMetaTools(
     }
     const results = registry.resultsStorage();
     const fields = call.fields && call.fields.length > 0 ? call.fields : null;
-    const timeoutMs =
-      call.timeoutMs && call.timeoutMs > 0
-        ? Math.max(1, Math.trunc(call.timeoutMs))
-        : undefined;
+    // An explicit per-call deadline always wins; the config default only fills
+    // the gap, and stays off entirely when the deployment sets none.
+    const timeoutMs = normalizeTimeoutMs(call.timeoutMs) ?? defaultToolTimeoutMs;
     const maxRetries = Math.min(
       2,
       Math.max(0, Math.trunc(call.maxRetries ?? 0)),
@@ -451,12 +537,18 @@ export function createMetaTools(
         connectorMs += Date.now() - connectorStarted;
         const details = classifyCallError(err);
         if (attempts <= maxRetries && retrySafe && details.retryable) {
-          const backoffStarted = Date.now();
-          await new Promise((resolve) =>
-            setTimeout(resolve, Math.min(250 * 2 ** (attempts - 1), 1_000)),
-          );
-          backoffMs += Date.now() - backoffStarted;
-          continue;
+          const wait = retryBackoffMs(attempts, details.retryAfterMs);
+          if (wait !== undefined) {
+            const backoffStarted = Date.now();
+            if (wait > 0) {
+              await new Promise((resolve) => setTimeout(resolve, wait));
+            }
+            backoffMs += Date.now() - backoffStarted;
+            continue;
+          }
+          // The reported window is longer than the engine will park a
+          // synchronous request for. Fall through to failure with
+          // retryAfterMs reported verbatim so the agent can re-issue.
         }
         registry.recordFailure(
           resolved.connector.id,
@@ -570,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) };
@@ -635,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) => {
@@ -739,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) => {
@@ -987,11 +1111,15 @@ export function registerMetaTools(
   ctx: {
     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

@@ -47,6 +47,10 @@ export interface ServerOptions {
   activityReadGate?: ActivityReadGate;
   activityDeploymentId?: string;
   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. */
@@ -59,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;")
@@ -229,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, {
@@ -517,7 +532,12 @@ async function serveMcp(
         logger: opts.logger,
       }
     : undefined;
-  registerMetaTools(server, opts.registry, { baseUrl, activity });
+  registerMetaTools(server, opts.registry, {
+    baseUrl,
+    activity,
+    defaultToolTimeoutMs: opts.defaultToolTimeoutMs,
+    probeTimeoutMs: opts.probeTimeoutMs,
+  });
   if (opts.executor) {
     registerExecuteTool(server, opts.registry, {
       baseUrl,
@@ -687,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];