@zackbart/connecta 0.4.1 → 0.6.0

package/src/ui.ts

@@ -24,32 +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 = branding?.productUrl?.trim();
-  const ownerUrl = branding?.ownerUrl?.trim();
+  const productUrl = trimmedString(branding?.productUrl);
+  const ownerUrl = trimmedString(branding?.ownerUrl);
+  const faviconHref = trimmedString(branding?.favicon?.href);
   return {
     productName,
     ...(productUrl && isSafeHttpUrl(productUrl) ? { productUrl } : {}),
     ...(ownerName ? { ownerName } : {}),
     ...(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
@@ -74,6 +116,86 @@ 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;
+  }
+}
+
+/**
+ * True only for an absolute `https:` URL — the gate for `uiAuth.frontendApiUrl`,
+ * the last operator-config value that lands in a URL-valued HTML position (the
+ * `<script src>` of `/ui`'s sign-in loader). `javascript:` in a `src` does not
+ * execute, so this closes a hole in the *invariant* rather than a live vector:
+ * every operator value reaching an `href`/`src` is validated, with no exception
+ * left to remember.
+ *
+ * Stricter than `isSafeHttpUrl` on purpose. There is no `http:` carve-out and no
+ * loopback carve-out, because nobody types this value: the shipped Clerk adapter
+ * derives it from the publishable key and Clerk's Frontend API is always https.
+ * A cleartext script source on the dashboard would be a downgrade even where a
+ * browser's mixed-content rules had not already blocked it.
+ */
+export function isSafeScriptSrcUrl(url: unknown): boolean {
+  if (typeof url !== "string") return false;
+  try {
+    return new URL(url).protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Names of the `uiAuth` URLs an inbound-auth provider supplied that failed their
+ * gate. Lives beside the gate for the same reason `droppedBrandingUrls` does: the
+ * startup warning cannot then drift from what rendering actually drops. Every
+ * field is read defensively rather than trusted, because a custom `InboundAuth`
+ * is untyped at a JS call site — `isSafeScriptSrcUrl` takes `unknown`, and a
+ * `uiAuth` that is not the clerk shape is reported as nothing to warn about.
+ */
+export function droppedUiAuthUrls(uiAuth?: UiAuthConfig): string[] {
+  if (!uiAuth || uiAuth.kind !== "clerk") return [];
+  return isSafeScriptSrcUrl(uiAuth.frontendApiUrl)
+    ? []
+    : ["uiAuth.frontendApiUrl"];
+}
+
 export interface UiTool {
   name: string;
   address: string;
@@ -89,6 +211,17 @@ export interface UiConnector {
   authorizationUrl?: string;
   toolCount: number;
   tools: UiTool[];
+  /**
+   * Verdict of the last proactive credential liveness check (issue #24), for the
+   * connectors that hold a credential connecta stores. Shown beside the live
+   * status so an operator can tell "checked just now" from "last verified an
+   * hour ago", and see a dead credential the page's own probe may not reach.
+   */
+  credentialCheck?: {
+    state: "ok" | "auth_required" | "error";
+    checkedAt: string;
+    message?: string;
+  };
   credential?: {
     label: string;
     description?: string;
@@ -173,6 +306,7 @@ export async function buildUiData(
   const connectors = await Promise.all(
     registry.listConnectors().map(async (c): Promise<UiConnector> => {
       const status = await registry.statusFor(c.id, baseUrl, requestScope);
+      const credentialCheck = await registry.credentialHealthFor(c.id);
       let tools: UiTool[] = [];
       // `status()` on an unauthenticated remote connector starts OAuth and
       // stores its state + PKCE verifier. Probing listTools immediately
@@ -271,6 +405,17 @@ export async function buildUiData(
           : {}),
         toolCount: tools.length,
         tools,
+        ...(credentialCheck
+          ? {
+              credentialCheck: {
+                state: credentialCheck.state,
+                checkedAt: credentialCheck.checkedAt,
+                ...(credentialCheck.message
+                  ? { message: credentialCheck.message }
+                  : {}),
+              },
+            }
+          : {}),
         ...(credential ? { credential } : {}),
       };
     }),
@@ -305,7 +450,28 @@ export function renderUiHtml(
   branding?: ConnectaBranding,
   nonce?: string,
 ): string {
-  const auth = uiAuth ?? { kind: "bearer" as const };
+  const clerk = uiAuth?.kind === "clerk" ? uiAuth : undefined;
+  // The Clerk loader's origin. A value that fails the gate is dropped rather
+  // than escaped into the page: the loader tag is simply not emitted, the gate
+  // reports that Clerk could not load, and the rest of the shell still renders —
+  // the same fallback-and-warn posture the branding URLs take, with the drop
+  // named in a startup warning (see `droppedUiAuthUrls`).
+  const clerkScriptOrigin =
+    clerk && isSafeScriptSrcUrl(clerk.frontendApiUrl)
+      ? clerk.frontendApiUrl
+      : undefined;
+  // Enumerated field by field, because this object is serialized into the page's
+  // inline script: a rejected frontendApiUrl must not reach the document through
+  // `AUTH` after being kept out of the `<script src>`.
+  const auth = clerk
+    ? {
+        kind: clerk.kind,
+        publishableKey: clerk.publishableKey,
+        ...(clerkScriptOrigin ? { frontendApiUrl: clerkScriptOrigin } : {}),
+        ...(clerk.signInUrl ? { signInUrl: clerk.signInUrl } : {}),
+        ...(clerk.signUpUrl ? { signUpUrl: clerk.signUpUrl } : {}),
+      }
+    : (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
@@ -327,8 +493,8 @@ export function renderUiHtml(
       : `<span class="product">${escapeHtmlAttr(brand.productName)}</span>`
     : "";
   const clerkScript =
-    uiAuth?.kind === "clerk"
-      ? `<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>`
+    clerk && clerkScriptOrigin
+      ? `<script${nonceAttr} defer crossorigin="anonymous" data-clerk-publishable-key="${escapeHtmlAttr(clerk.publishableKey)}" src="${escapeHtmlAttr(clerkScriptOrigin)}/npm/@clerk/clerk-js@6/dist/clerk.browser.js"></script>`
       : "";
 
   return `<!doctype html>
@@ -907,6 +1073,19 @@ function render() {
     if (c.message) {
       head += '<p class="connector-message msg">' + esc(c.message) + "</p>";
     }
+    if (c.credentialCheck) {
+      const check = c.credentialCheck;
+      const verdict = check.state === "ok"
+        ? "credential verified"
+        : check.state === "auth_required"
+          ? "credential needs authorization"
+          : "credential check failed";
+      head += '<p class="connector-check meta">Credential check: ' +
+        esc(verdict) + " · " + esc(formatDate(check.checkedAt)) +
+        (check.message && check.message !== c.message
+          ? " — " + esc(check.message)
+          : "") + "</p>";
+    }
     if (c.authorizationUrl) {
       const safe = safeHttp(c.authorizationUrl);
       head += safe

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.1";
+export const CONNECTA_VERSION = "0.6.0";