@zackbart/connecta 0.4.0 → 0.5.0

package/src/types.ts

@@ -135,6 +135,23 @@ export interface Connector {
   /** How call_tool wraps results. "mcp" passes the content array through; anything else is JSON-wrapped. */
   kind?: "mcp" | "api";
   description?: string;
+  /**
+   * Max inline result size (bytes) for this connector's tools before
+   * call_tool/batch_call truncate and stash the full text for get_result
+   * paging. Overrides the deployment-wide `ConnectaConfig.maxResultBytes`;
+   * omit to inherit it (which itself defaults to 50_000). Must be a whole
+   * number of bytes >= 1; anything else warns at startup and is ignored, so
+   * the connector inherits the deployment-wide cap.
+   */
+  maxResultBytes?: number;
+  /**
+   * Optional agent-facing usage guide (markdown) for this connector — preferred
+   * tools, address quirks, pagination conventions, rate-limit etiquette, good
+   * query patterns. Listed by the `skills` meta-tool as `connector:<id>` and
+   * returned verbatim by `skills({ name: "connector:<id>" })`. Keep it concise
+   * and imperative; it is read by agents, not operators.
+   */
+  usageGuide?: string;
   /** Optional operator-managed credential slot rendered inside this connector's /ui card. */
   credential?: ConnectorCredentialConfig;
   /** Optional server-side check used by /ui's Test action. */
@@ -262,7 +279,9 @@ export interface ConnectaBranding {
    * `/favicon.svg`, `ico` at `/favicon.ico`; omit either to keep the default
    * for that format. Use `href` instead to point the page at an icon you host
    * elsewhere (it replaces the `/favicon.svg` link in the page head; the
-   * `/favicon.*` routes still serve whatever `svg`/`ico` provide).
+   * `/favicon.*` routes still serve whatever `svg`/`ico` provide). `href` must
+   * be an absolute `http(s)` URL or a root-relative path; anything else falls
+   * back to the default mark.
    */
   favicon?: {
     svg?: string;

package/src/ui.ts

@@ -24,31 +24,74 @@ interface ResolvedBranding {
   themeColor: string;
 }
 
+export const DEFAULT_FAVICON_HREF = "/favicon.svg";
+
+/**
+ * Branding arrives from operator config, which is untyped at a JS call site, so
+ * every field is treated as `unknown`: a non-string is read as unset rather than
+ * throwing on `.trim()`. Rendering must degrade to defaults for a malformed
+ * value, never fail — `createConnecta` calls this during construction.
+ */
+function trimmedString(value: unknown): string | undefined {
+  return typeof value === "string" ? value.trim() || undefined : undefined;
+}
+
 export function resolveBranding(
   branding?: ConnectaBranding,
 ): ResolvedBranding {
-  const productName = branding?.productName?.trim() || "Connecta";
-  const ownerName = branding?.ownerName?.trim();
+  const productName = trimmedString(branding?.productName) ?? "Connecta";
+  const ownerName = trimmedString(branding?.ownerName);
+  // 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 = trimmedString(branding?.productUrl);
+  const ownerUrl = trimmedString(branding?.ownerUrl);
+  const faviconHref = trimmedString(branding?.favicon?.href);
   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() ||
+      trimmedString(branding?.description) ??
       `Manage the services this ${productName} instance makes available to agents.`,
     pageTitle:
-      branding?.pageTitle?.trim() ||
+      trimmedString(branding?.pageTitle) ??
       (ownerName ? `${productName} — ${ownerName}` : productName),
-    faviconHref: branding?.favicon?.href?.trim() || "/favicon.svg",
-    themeColor: branding?.themeColor?.trim() || "#ffffff",
+    faviconHref:
+      faviconHref && isSafeIconHref(faviconHref)
+        ? faviconHref
+        : DEFAULT_FAVICON_HREF,
+    themeColor: trimmedString(branding?.themeColor) ?? "#ffffff",
   };
 }
 
+/**
+ * Names of the branding URLs the operator set that failed their gate and were
+ * replaced by a default. Lives beside the gates so the startup warning cannot
+ * drift from them, and takes `unknown` fields for the same reason
+ * `resolveBranding` does — a warning helper must never throw.
+ */
+export function droppedBrandingUrls(branding?: ConnectaBranding): string[] {
+  if (!branding) return [];
+  const resolved = resolveBranding(branding);
+  // A non-string still counts as "set": the operator meant to supply a URL, and
+  // that intent is exactly what the warning reports on. A blank string does not.
+  const isSet = (value: unknown) =>
+    typeof value === "string"
+      ? trimmedString(value) !== undefined
+      : value !== undefined && value !== null;
+  const faviconHref = branding.favicon?.href;
+  return [
+    ...(isSet(branding.productUrl) && !resolved.productUrl ? ["productUrl"] : []),
+    ...(isSet(branding.ownerUrl) && !resolved.ownerUrl ? ["ownerUrl"] : []),
+    ...(isSet(faviconHref) &&
+    trimmedString(faviconHref) !== resolved.faviconHref
+      ? ["favicon.href"]
+      : []),
+  ];
+}
+
 /**
  * A JS string literal safe to inline in a <script> block. JSON.stringify alone
  * leaves `/` untouched, so a value containing "</script>" would close the
@@ -73,6 +116,48 @@ export function isSafeHttpUrl(url: unknown): boolean {
   }
 }
 
+/**
+ * Only the second check's base; any origin works because the check is whether
+ * the href stays on whatever origin it is resolved against. It is deliberately
+ * never the sole gate: a value whose own authority equals this host (say
+ * `//connecta.invalid/x`) would resolve to this exact origin and pass, so the
+ * structural check below runs first and is what actually rejects `//host`.
+ */
+const SAME_ORIGIN_PROBE = "https://connecta.invalid";
+
+/** Removed anywhere in a URL by the parser, so a gate must ignore them too. */
+const URL_STRIPPED_CHARS = /[\t\n\r]/g;
+
+/**
+ * True for values allowed in the page's `<link rel="icon" href>`: an absolute
+ * `http(s)` URL (an icon the operator hosts elsewhere) or a path rooted at this
+ * origin. The relative carve-out is deliberate rather than accidental — the
+ * default href is the relative `/favicon.svg`, which `isSafeHttpUrl` alone would
+ * reject — and it is kept narrow on both ends.
+ *
+ * Root-relative only, because `/ui` and `/oauth/callback/<id>` sit at different
+ * depths and a document-relative path would resolve differently on each.
+ *
+ * "Root-relative" is enforced structurally: exactly one leading `/` followed by
+ * a character that is neither `/` nor `\`. Both of those would make the value an
+ * authority (`//host`, and `/\host` because the URL parser folds `\` to `/` in
+ * special schemes), pointing at an origin this server does not control. The test
+ * runs on a copy with tab/newline/CR removed, since the parser strips those
+ * anywhere and `/\t/host` would otherwise slip through as single-slash. The
+ * origin comparison that follows is defense in depth, not the authority check —
+ * on its own it would accept an authority that happened to equal the probe host.
+ */
+export function isSafeIconHref(href: unknown): boolean {
+  if (typeof href !== "string") return false;
+  if (isSafeHttpUrl(href)) return true;
+  if (!/^\/(?![/\\])/.test(href.replace(URL_STRIPPED_CHARS, ""))) return false;
+  try {
+    return new URL(href, SAME_ORIGIN_PROBE).origin === SAME_ORIGIN_PROBE;
+  } catch {
+    return false;
+  }
+}
+
 export interface UiTool {
   name: string;
   address: string;
@@ -302,10 +387,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 +412,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 +772,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.5.0";