@zackbart/connecta 0.6.0 → 0.7.0

package/src/server.ts

@@ -10,6 +10,11 @@ import type {
   ActivityStore,
 } from "./activity.js";
 import { InvalidActivityCursorError } from "./activity.js";
+import {
+  credentialTestRule,
+  describeCredentialTestMismatch,
+  storedCredentialShape,
+} from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
 import { ScopedRegistry, type Registry, type RegistryView } from "./registry.js";
 import {
@@ -18,6 +23,7 @@ import {
   type Toolkit,
 } from "./toolkits.js";
 import type {
+  ConnectorContext,
   ConnectorCredentialConfig,
   ConnectorCredentialValues,
   ConnectaBranding,
@@ -30,6 +36,8 @@ import { CONNECTA_FAVICON_ICO } from "./favicon.js";
 import {
   buildUiData,
   CONNECTA_FAVICON_SVG,
+  credentialManagementCapability,
+  operatorPageForPath,
   resolveBranding,
   renderUiHtml,
 } from "./ui.js";
@@ -88,7 +96,7 @@ export interface ServerOptions {
   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. */
+  /** Encrypted connector-credential storage backing the Credentials page. */
   credentialVault?: CredentialVault;
   /** Optional browser UI and OAuth result-page labels. */
   branding?: ConnectaBranding;
@@ -103,7 +111,7 @@ 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). */
+/** Per-request base64 nonce for an operator shell's scripts (Node 20+ and Workers). */
 function uiScriptNonce(): string {
   const bytes = crypto.getRandomValues(new Uint8Array(16));
   let binary = "";
@@ -186,7 +194,7 @@ function html(
     <h1>Connection status</h1>
     <div class="copy">
       <p>${escapeHtml(body)}</p>
-      <p><a href="/ui">Return to ${escapeHtml(brand.productName)}</a></p>
+      <p><a href="/">Return to ${escapeHtml(brand.productName)}</a></p>
     </div>
   </main>
 </body>
@@ -216,7 +224,7 @@ async function authorize(
       actor: ActivityActor;
       providerKind?: string;
       userId?: string;
-      /** The admitting identity's toolkit binding, if it has one (§16). */
+      /** The admitting identity's toolkit binding (docs/toolkits.md). */
       toolkitBinding?: ToolkitBinding;
     }
   | { ok: false; response: Response }
@@ -312,10 +320,10 @@ function withSecurityHeaders(
   if (requestUrl.protocol === "https:") {
     headers.set("Strict-Transport-Security", "max-age=31536000");
   }
-  if (path === "/ui") {
-    // 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 (operatorPageForPath(path) || path === "/ui") {
+    // Operator HTML responses ship their own nonce-based script CSP (which
+    // already includes frame-ancestors 'none'); only fall back to the
+    // framing-only directive when no CSP is present (for example redirects).
     if (!headers.has("Content-Security-Policy")) {
       headers.set("Content-Security-Policy", "frame-ancestors 'none'");
     }
@@ -340,11 +348,11 @@ async function authorizeUiAdmin(
   //
   // EVERY Clerk provider gets a turn, the way the /mcp gate does, because the
   // documented per-team pattern is several `clerkAuth(...)`s that differ only in
-  // `gate` and `toolkits` (§16). Stopping at the first would make admission
-  // depend on config order: the team-bound provider listed first would refuse
-  // the operator outright, and a refusal here — a failed gate, a missing user, a
-  // toolkit-bound identity — is exactly the case where a later provider is the
-  // one meant to admit. The last refusal is returned if none do.
+  // `gate` and `toolkits` (docs/toolkits.md). Stopping at the first would make
+  // admission depend on config order: the team-bound provider listed first
+  // would refuse the operator outright, and a refusal here — a failed gate, a
+  // missing user, a toolkit-bound identity — is exactly the case where a later
+  // provider is the one meant to admit. The last refusal is returned if none do.
   const providers = auth.filter(
     (candidate) => candidate.uiAuth?.kind === "clerk",
   );
@@ -546,36 +554,48 @@ async function handleCredentialRequest(
     if (request.method !== "POST") {
       return privateJson({ error: "method not allowed" }, { status: 405 });
     }
-    if (!connector.testCredential && !connector.testCredentials) {
+    // The declared credential shape picks the hook — the same single rule the
+    // Credentials page asks for its Test affordance, so a shown button reaches
+    // that reads the shape the credential was stored in.
+    const rule = credentialTestRule(connector);
+    if (!rule.mode) {
       return privateJson(
-        { error: "this connector does not support credential testing" },
+        {
+          error: rule.mismatch
+            ? "this connector cannot test its credential: " +
+              describeCredentialTestMismatch(rule.mismatch)
+            : "this connector does not support credential testing",
+        },
         { status: 400 },
       );
     }
     try {
+      const values = await opts.credentialVault.getAll(connectorId);
+      const shape = storedCredentialShape(connector.credential, values);
+      if (shape.state === "missing") {
+        return privateJson(
+          {
+            error:
+              rule.mode === "multiple"
+                ? "configure the credentials before testing them"
+                : "configure the credential before testing it",
+          },
+          { status: 409 },
+        );
+      }
+      if (shape.state === "mismatch") {
+        return privateJson({ error: shape.message }, { status: 409 });
+      }
+      const storedValues = values!;
       const ctx = opts.registry.contextFor(connectorId, baseUrl);
       let result;
-      if (connector.testCredentials) {
-        const values = await opts.credentialVault.getAll(connectorId);
-        if (!values) {
-          return privateJson(
-            { error: "configure the credentials before testing them" },
-            { status: 409 },
-          );
-        }
-        result = await connector.testCredentials(values, ctx);
+      if (rule.mode === "multiple") {
+        result = await connector.testCredentials!(storedValues, ctx);
       } else {
-        const value = await opts.credentialVault.get(connectorId);
-        if (!value) {
-          return privateJson(
-            { error: "configure the credential before testing it" },
-            { status: 409 },
-          );
-        }
-        result = await connector.testCredential!(value, ctx);
+        result = await connector.testCredential!(storedValues.value, ctx);
       }
       // The operator just ran the very check the liveness sweep runs; record it
-      // so the cached status surfaces agree with what /ui just showed them.
+      // so cached status surfaces agree with what the operator page showed.
       await opts.registry.recordCredentialHealth(connectorId, {
         state: result.ok ? "ok" : "auth_required",
         checkedAt: new Date().toISOString(),
@@ -645,12 +665,12 @@ interface McpScope {
 
 /**
  * Bounded, escaped form of a caller-influenced value (a rejected toolkit name,
- * an identity id) for the operator log. Goes through JSON.stringify so a
- * caller-controlled newline or control character cannot forge a log line, plus a
- * hand-rolled escape for U+2028/U+2029, which JSON.stringify leaves raw even
- * though a log reader treats them as line terminators. Truncated to the same
- * length the response body echoes at, so an oversized value cannot flood the log
- * either.
+ * identity id, or OAuth callback connector id) for the operator log. Goes
+ * through JSON.stringify so a caller-controlled newline or control character
+ * cannot forge a log line, plus a hand-rolled escape for U+2028/U+2029, which
+ * JSON.stringify leaves raw even though a log reader treats them as line
+ * terminators. Truncated to a small shared cap (also the toolkit response's echo
+ * limit), so an oversized value cannot flood the log either.
  */
 function loggableValue(requested: string): string {
   const bounded = requested.slice(0, MAX_ECHOED_TOOLKIT_NAME);
@@ -700,7 +720,7 @@ function identityLabel(actor: ActivityActor): string {
 
 /**
  * Resolve `?toolkit=<name>` into the registry view this connection may see,
- * enforcing the caller's toolkit binding (§16) on the way.
+ * enforcing the caller's toolkit binding (docs/toolkits.md) on the way.
  *
  * For an UNBOUND identity (no binding configured — the pre-#37 shape):
  *
@@ -892,35 +912,105 @@ async function serveMcp(
   return transport.handleRequest(request);
 }
 
+/**
+ * Pay the storage read a real downstream-OAuth refusal pays, on the refusal
+ * paths that would otherwise pay nothing.
+ *
+ * Identical bodies do not hide a connector id if the clock still sorts them.
+ * `KvOAuthProvider.verifyState` reads `oauth:state` before it can fail, so a
+ * configured id costs one storage round trip — on the Workers deployment shape
+ * that is a real KV read, tens of milliseconds cold — while an id that names
+ * nothing used to return having touched no I/O at all. That gap is an oracle:
+ * sample the two and a wordlist recovers the connector list the flat 400 was
+ * meant to withhold. So the zero-I/O refusals read the same key in the same
+ * `conn:<id>:` namespace, which for an unconfigured id is simply a miss.
+ *
+ * This is deliberately *not* a constant-time claim, and docs/connectors.md says
+ * so in prose: a hit and a miss are not identical in a KV store, and a connector
+ * shipping its own `verifyState` may do more or less work than one read. What it
+ * removes is the order-of-magnitude "no I/O versus a round trip" difference,
+ * which is the only part of the signal that makes enumeration cheap.
+ *
+ * A throwing read is swallowed: the refusal is the answer either way, and
+ * turning it into a 500 would hand back exactly the distinguishable response
+ * this whole path exists to deny.
+ */
+async function equalizeRefusalCost(context: ConnectorContext): Promise<void> {
+  try {
+    await context.storage.get("oauth:state");
+  } catch {
+    // Deliberately ignored — see above.
+  }
+}
+
 async function handleOAuthCallback(
   url: URL,
   registry: Registry,
   baseUrl: string,
+  logger: Logger,
   branding?: ConnectaBranding,
 ): Promise<Response> {
-  const id = url.pathname.slice("/oauth/callback/".length);
-  const connector = registry.getConnector(id);
-  if (!connector || !connector.finishAuth) {
-    return html(`Unknown connector "${id}".`, 404, branding);
-  }
   const error = url.searchParams.get("error");
   if (error) return html(`Authorization denied: ${error}`, 400, branding);
   const code = url.searchParams.get("code");
   if (!code) return html("Missing authorization code.", 400, branding);
+  const id = url.pathname.slice("/oauth/callback/".length);
+  const connector = registry.getConnector(id);
+  // Safe to build before we know the id names anything: `contextFor` is a pure
+  // constructor — a namespaced storage view over `conn:<id>:` and, only for a
+  // connector that declares one, a lazy credential accessor. It neither throws
+  // nor touches storage for an unknown id, which is what lets the refusals
+  // below borrow it to equalize their cost.
   const context = registry.contextFor(id, baseUrl);
+  const refused = () =>
+    html(
+      "Authorization could not be completed. Re-run authorization from " +
+        "connecta and try again.",
+      400,
+      branding,
+    );
+  if (!connector || !connector.finishAuth) {
+    await equalizeRefusalCost(context);
+    return refused();
+  }
   // CSRF / login-fixation guard: this route is intentionally public, so verify
   // the `state` matches the flow connecta started BEFORE exchanging the code.
-  if (connector.verifyState) {
-    const state = url.searchParams.get("state");
-    const ok = await connector.verifyState(state, context);
-    if (!ok) {
-      return html(
-        "Authorization state mismatch — this callback did not originate from " +
-          "a flow started by connecta. Re-run authorization and try again.",
-        400,
-        branding,
-      );
-    }
+  if (!connector.verifyState) {
+    await equalizeRefusalCost(context);
+    logger.warn(
+      `[connecta] refused an OAuth callback for connector ` +
+        `${loggableValue(id)} with 400: it implements finishAuth but no ` +
+        "verifyState, so connecta cannot establish that it started this flow. " +
+        "No authorization code was exchanged. Implement verifyState before " +
+        "trying again.",
+    );
+    return refused();
+  }
+  const state = url.searchParams.get("state");
+  let stateMatches: boolean;
+  try {
+    stateMatches = await connector.verifyState(state, context);
+  } catch (err) {
+    logger.warn(
+      `[connecta] refused an OAuth callback for connector ` +
+        `${loggableValue(id)} with 400: verifyState threw ` +
+        `${loggableValue(msg(err))}. No authorization code was exchanged. ` +
+        "Re-run authorization from connecta and check the verifier if it " +
+        "fails again.",
+    );
+    return refused();
+  }
+  if (!stateMatches) {
+    logger.warn(
+      `[connecta] refused an OAuth callback for connector ` +
+        `${loggableValue(id)} with 400: ` +
+        (state === null
+          ? "the state parameter was missing"
+          : "the state did not match the pending authorization flow") +
+        ". No authorization code was exchanged. Re-run authorization from " +
+        "connecta and try again.",
+    );
+    return refused();
   }
   try {
     await connector.finishAuth(code, context);
@@ -995,7 +1085,10 @@ export function createFetchHandler(
       new URL(publicUrl).protocol === "https:" &&
       url.protocol === "http:"
     ) {
-      const target = new URL(`${url.pathname}${url.search}`, publicUrl);
+      // 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);
       return withSecurityHeaders(
         new Response(null, {
           status: 308,
@@ -1054,7 +1147,13 @@ export function createFetchHandler(
       }
 
       if (path.startsWith("/oauth/callback/")) {
-        return handleOAuthCallback(url, registry, baseUrl, opts.branding);
+        return handleOAuthCallback(
+          url,
+          registry,
+          baseUrl,
+          opts.logger,
+          opts.branding,
+        );
       }
 
       if (request.method === "GET" && path === "/favicon.svg") {
@@ -1078,7 +1177,23 @@ export function createFetchHandler(
       }
 
       if (path === "/ui") {
-        // Open shell — carries no data; data comes only from the gated /ui/data.
+        if (request.method !== "GET") {
+          return privateJson({ error: "method not allowed" }, { status: 405 });
+        }
+        const target = new URL(`/${url.search}`, baseUrl);
+        return new Response(null, {
+          status: 308,
+          headers: { Location: target.toString() },
+        });
+      }
+
+      const operatorPage = operatorPageForPath(path);
+      if (operatorPage) {
+        if (request.method !== "GET") {
+          return privateJson({ error: "method not allowed" }, { status: 405 });
+        }
+        // Open shell — carries no operator data; everything comes from the
+        // authenticated /ui/* APIs after the browser establishes a session.
         const uiAuth = auth.find((provider) => provider.uiAuth)?.uiAuth;
         const mcpUrl = new URL("/mcp", baseUrl).toString();
         // Nonce the page's inline script (and the Clerk loader). 'strict-dynamic'
@@ -1088,16 +1203,19 @@ export function createFetchHandler(
         // 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",
-            "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",
+        return new Response(
+          renderUiHtml(uiAuth, mcpUrl, opts.branding, nonce, operatorPage),
+          {
+            status: 200,
+            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",
+            },
           },
-        });
+        );
       }
 
       if (path === "/ui/data") {
@@ -1109,16 +1227,24 @@ 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 credentialManagement = credentialManagementCapability({
+          eligibleClerkOperator,
+          hasCredentialSlots: registry
+            .listConnectors()
+            .some((connector) => Boolean(connector.credential)),
+          hasCredentialVault: Boolean(opts.credentialVault),
+        });
         const data = await buildUiData(
           registry,
           baseUrl,
           serverInfo,
           // The static headless bearer may read connector health, but only a
           // Clerk-authenticated operator receives credential metadata.
-          authz.providerKind === "clerk" && authz.userId
-            ? opts.credentialVault
-            : undefined,
+          eligibleClerkOperator ? opts.credentialVault : undefined,
           Boolean(opts.activity?.list),
+          credentialManagement,
         );
         return privateJson(data);
       }

package/src/skills.ts

@@ -235,12 +235,12 @@ export function resolveSkill(
     return {
       found: false,
       message: connectorGuide(bare)
-        ? `Unknown skill "${name}". Connector guides are fetched as "${connectorSkillName(name)}". Available: ${available()}.`
+        ? `Unknown skill "${name}". Connector guides are fetched as "${connectorSkillName(name)}". Available skills: ${available()}.`
         : `Connector "${name}" has no usage guide. Available skills: ${available()}.`,
     };
   }
   return {
     found: false,
-    message: `Unknown skill "${name}". Available: ${available()}.`,
+    message: `Unknown skill "${name}". Available skills: ${available()}.`,
   };
 }

package/src/toolkits.ts

@@ -129,7 +129,7 @@ function toolFilter(
  * an allowlist is a scope the operator did not write, and a scope nobody wrote
  * is not one an operator can reason about. (A definition scopes visibility only;
  * WHICH identity may select it is the separate binding below — see the module
- * header and documentation.md §16.) Tool names are checked only for connectors that expose
+ * header and docs/toolkits.md.) Tool names are checked only for connectors that expose
  * `staticTools` (i.e. `api()`); a remote connector's catalog is fetched lazily
  * over the network and is unknown at construction time.
  */

package/src/types.ts

@@ -63,7 +63,7 @@ export interface ConnectorCredentialFieldConfig {
   name: string;
   /** Short field label, e.g. "Account email". */
   label: string;
-  /** Plain-language guidance shown in /ui. Never include the credential itself. */
+  /** Plain-language guidance shown in /credentials. Never include the credential itself. */
   description?: string;
   /** Input placeholder, e.g. "you@example.com". */
   placeholder?: string;
@@ -75,7 +75,7 @@ export interface ConnectorCredentialFieldConfig {
 export interface ConnectorCredentialConfig {
   /** Short group or field label, e.g. "API token" or "Service credentials". */
   label: string;
-  /** Plain-language guidance shown in /ui. Never include the credential itself. */
+  /** Plain-language guidance shown in /credentials. Never include the credential itself. */
   description?: string;
   /** Password-field placeholder, e.g. "Paste API token". */
   placeholder?: string;
@@ -100,13 +100,14 @@ export interface ConnectorContext {
   /**
    * Read-only access to this connector's operator-managed credential. Present
    * only when the connector declares `credential` and the deployment configures
-   * `credentialEncryptionKey`.
+   * `credentials.encryptionKey`.
    */
   credential?: ConnectorCredentialAccess;
   /**
    * Identity shared by connector calls that belong to one inbound request.
    * Connectors may use it to reuse request-safe resources within that request,
-   * but must never retain I/O resources beyond the scope's lifetime.
+   * but must never retain I/O resources beyond the scope's lifetime. For
+   * probe-only scopes the core owns, `Connector.closeScope` signals that end.
    *
    * Optional for custom/test contexts; the context object itself is the scope
    * when omitted.
@@ -138,7 +139,7 @@ export interface Connector {
   /**
    * 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`;
+   * paging. Overrides `ConnectaConfig.calls.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.
@@ -152,14 +153,14 @@ export interface Connector {
    * and imperative; it is read by agents, not operators.
    */
   usageGuide?: string;
-  /** Optional operator-managed credential slot rendered inside this connector's /ui card. */
+  /** Optional operator-managed credential slot rendered on /credentials. */
   credential?: ConnectorCredentialConfig;
-  /** Optional server-side check used by /ui's Test action. */
+  /** Optional server-side check used by /credentials' Test action. */
   testCredential?(
     value: string,
     ctx: ConnectorContext,
   ): Promise<CredentialTestResult>;
-  /** Optional multi-field credential check used by /ui's Test action. */
+  /** Optional multi-field credential check used by /credentials' Test action. */
   testCredentials?(
     values: ConnectorCredentialValues,
     ctx: ConnectorContext,
@@ -189,6 +190,18 @@ export interface Connector {
     args: unknown,
     ctx: ConnectorContext,
   ): Promise<unknown>;
+  /**
+   * Optional best-effort teardown for resources retained under
+   * `ctx.requestScope`. The core calls this at most once when a scope it created
+   * solely for probing ends, and never uses that scope again. Teardown gets a
+   * small, fixed best-effort completion window; a missing, rejected, or
+   * never-settling hook cannot change or hold open the operation's result
+   * beyond that bound.
+   *
+   * Per-request `/mcp` scopes are not closed through this hook: their
+   * request-local reuse remains in force until the request boundary.
+   */
+  closeScope?(ctx: ConnectorContext): Promise<void>;
   /** Optional connector-level health/auth status for list_connectors. */
   status?(ctx: ConnectorContext): Promise<ConnectorStatus>;
   /**
@@ -202,11 +215,11 @@ export interface Connector {
     opts?: { force?: boolean },
   ): Promise<ConnectorStatus>;
   /**
-   * Optional: verify the OAuth `state` returned to /oauth/callback/<id> against
-   * the value this connector generated when it started the flow. Present only
-   * on downstream-OAuth connectors. The callback MUST reject before finishAuth
-   * when this returns false — otherwise anyone holding the pending URL could
-   * complete consent with their own account.
+   * Verify the OAuth `state` returned to /oauth/callback/<id> against the value
+   * this connector generated when it started the flow. Required whenever
+   * `finishAuth` is present: the callback rejects before `finishAuth` when this
+   * hook is absent, throws, or returns false — otherwise anyone holding the
+   * pending URL could complete consent with their own account.
    */
   verifyState?(state: string | null, ctx: ConnectorContext): Promise<boolean>;
   /** Optional: complete a downstream OAuth flow (called by /oauth/callback/<id>). */
@@ -215,7 +228,8 @@ export interface Connector {
    * Optional: serve a connector-owned HTTP route — for example a signed
    * download link minted by one of the connector's tools. Called only after
    * every built-in route misses, so a connector can never shadow `/mcp`,
-   * `/ui`, `/health`, or the credential API. The first connector to return a
+   * `/`, `/credentials`, `/activity`, `/health`, or the credential API. The
+   * first connector to return a
    * Response wins, in registration order; return null to decline.
    *
    * These routes are PUBLIC: connecta applies no auth gate to them. A
@@ -254,9 +268,9 @@ export interface Executor {
 
 /**
  * Which toolkits one inbound identity may open — the membership half of the
- * deployment=org / toolkit=team framing (§16). A mapping, never a policy
- * engine: one identity → the toolkit names it may select, plus whether it may
- * connect with no `?toolkit=` at all.
+ * deployment=org / toolkit=team framing (docs/toolkits.md). A mapping, never a
+ * policy engine: one identity → the toolkit names it may select, plus whether
+ * it may connect with no `?toolkit=` at all.
  *
  * An identity with NO binding is unbound and keeps the pre-binding behavior:
  * any declared toolkit, or the full registry. A binding is enforced at connect
@@ -304,19 +318,30 @@ export type UiAuthConfig = {
   kind: "clerk";
   publishableKey: string;
   /**
-   * Origin `/ui` fetches its browser sign-in loader from. **Must be an absolute
+   * Origin the operator shell fetches its browser sign-in loader from. **Must be an absolute
    * `https:` URL** — the value lands in a `<script src>`, so the gate is
    * stricter than the branding href gate: no `http:`, no loopback exemption, and
    * no root-relative form (a relative path is rejected, not resolved). The
    * shipped `clerkAuth` adapter derives this from the publishable key and
    * Clerk's Frontend API is always https, so nothing legitimate needs a
    * carve-out. A value that fails the gate reaches neither the loader tag nor
-   * the page's inline auth config: `/ui` renders without the loader and reports
+   * the page's inline auth config: operator pages render without it and report
    * that Clerk could not load, and `createConnecta` names the drop in a startup
    * warning.
    */
   frontendApiUrl: string;
+  /**
+   * Hosted Account Portal sign-in address, handed to `Clerk.load`. **Must be an
+   * absolute `https:` URL** — the same gate `frontendApiUrl` passes, because
+   * this value is where Clerk *navigates* the operator's browser. An Account
+   * Portal address is always https, so the stricter gate costs nothing real: a
+   * value that fails it (a `javascript:`/`data:` payload, a cleartext `http:`
+   * address, a relative path) reaches no part of the page, the shell signs in
+   * through Clerk's default instead, and `createConnecta` names the drop in a
+   * startup warning.
+   */
   signInUrl?: string;
+  /** Hosted Account Portal sign-up address. Gated exactly like `signInUrl`. */
   signUpUrl?: string;
 };
 
@@ -334,7 +359,7 @@ export interface ConnectaBranding {
   ownerName?: string;
   /** Optional link for the organization or owner label. */
   ownerUrl?: string;
-  /** Status-dashboard introduction. */
+  /** Operator-page introduction and meta description. */
   description?: string;
   /**
    * Browser tab title and page meta name. Defaults to
@@ -363,16 +388,16 @@ export interface ConnectaBranding {
 export interface InboundAuth {
   kind: string;
   /**
-   * Optional browser sign-in configuration. When present, `/ui` uses this
+   * Optional browser sign-in configuration. When present, operator pages use it
    * provider instead of asking the operator to paste a static bearer secret.
    */
   uiAuth?: UiAuthConfig;
   /**
-   * Optional toolkit binding for every identity this provider admits (§16).
-   * Declared statically so `createConnecta` can validate the names against
-   * `ConnectaConfig.toolkits` and throw on a typo — a binding nobody wrote is
-   * not one an operator can reason about. An `authorize` result may narrow it
-   * per identity with its own `toolkitBinding`.
+   * Optional toolkit binding for every identity this provider admits
+   * (docs/toolkits.md). Declared statically so `createConnecta` can validate the
+   * names against `ConnectaConfig.toolkits` and throw on a typo — a binding
+   * nobody wrote is not one an operator can reason about. An `authorize` result
+   * may narrow it per identity with its own `toolkitBinding`.
    */
   toolkitBinding?: ToolkitBinding;
   /** Serve/short-circuit .well-known + OPTIONS. Return null when not handled. */