@zackbart/connecta 0.5.0 → 0.6.0

package/src/toolkits.ts

@@ -4,10 +4,16 @@
 // A connecta deployment belongs to an ORG; a toolkit is the view a GROUP OF
 // TEAM MEMBERS inside that org gets — a "support" toolkit seeing Zendesk and
 // Notion, an "exec" toolkit that also sees Gmail. This module only *defines and
-// validates* scopes. Enforcement lives in one place: `ScopedRegistry`
-// (src/registry.ts), which every meta-tool inherits through `RegistryView`.
+// validates* scopes and the identity bindings that gate them. Enforcement lives
+// in two places, each with one job:
+//
+//   - WHICH toolkit an identity may open: the connect-time binding check in
+//     `resolveToolkitScope` (src/server.ts), run after the auth gate and before
+//     any scoped registry exists.
+//   - WHAT a selected toolkit may see: `ScopedRegistry` (src/registry.ts),
+//     which every meta-tool inherits through `RegistryView`.
 
-import type { Connector } from "./types.js";
+import type { Connector, InboundAuth, ToolkitBinding } from "./types.js";
 
 /** Toolkit names share the connector-id grammar: URL-safe, no separators. */
 export const TOOLKIT_NAME_RE = /^[a-z0-9_-]+$/;
@@ -121,9 +127,9 @@ function toolFilter(
  *
  * Structural mistakes THROW at construction rather than warn: a typo'd id in
  * an allowlist is a scope the operator did not write, and a scope nobody wrote
- * is not one an operator can reason about. (A toolkit scopes visibility, not
- * identity — it is not itself an access check; see the module header and
- * documentation.md §16.) Tool names are checked only for connectors that expose
+ * 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
  * `staticTools` (i.e. `api()`); a remote connector's catalog is fetched lazily
  * over the network and is unknown at construction time.
  */
@@ -213,3 +219,232 @@ export function resolveToolkits(
   }
   return resolved;
 }
+
+/**
+ * The binding half of an inbound-auth adapter's options — the shape every
+ * shipped adapter (`bearerToken`, `clerkAuth`) mixes into its own options so an
+ * operator writes one thing in one style, next to the credential it binds.
+ */
+export interface ToolkitBindingOptions {
+  /**
+   * Toolkit names this credential may select with `?toolkit=<name>`. Present ⇒
+   * the identity is BOUND: any other toolkit, and (unless `unscoped`) a
+   * connection with no `?toolkit=`, is refused at connect time. Absent ⇒
+   * unbound, exactly as before bindings existed.
+   */
+  toolkits?: readonly string[];
+  /**
+   * Also allow a connection with no `?toolkit=` (the full registry, and the
+   * deployment-wide operator surfaces). Only meaningful beside `toolkits`.
+   */
+  unscoped?: boolean;
+}
+
+/**
+ * Validate one adapter's binding options into a `ToolkitBinding`, or undefined
+ * when the adapter declares none. Structural mistakes THROW where the operator
+ * wrote them (adapter construction), for the same reason toolkit definitions do:
+ * a binding that does not say what its author meant is worse than none, because
+ * it is invisible until the day it denies — or admits — the wrong caller.
+ *
+ * Names are only checked against the *grammar* here; cross-checking them
+ * against the configured toolkits happens in `validateToolkitBindings`, which
+ * runs in `createConnecta` where both halves are finally in scope.
+ */
+export function resolveToolkitBinding(
+  source: string,
+  options: ToolkitBindingOptions,
+): ToolkitBinding | undefined {
+  const { toolkits, unscoped } = options;
+  if (toolkits === undefined) {
+    if (unscoped !== undefined) {
+      // `unscoped` alone reads like a permission but grants nothing an unbound
+      // identity does not already have, so it is almost certainly a half-written
+      // binding — the one shape here that would silently fail OPEN.
+      throw new Error(
+        `${source}: \`unscoped\` only means something beside \`toolkits\`. ` +
+          "List the toolkits this credential may open, or drop `unscoped` to " +
+          "leave the credential unbound.",
+      );
+    }
+    return undefined;
+  }
+  if (!Array.isArray(toolkits)) {
+    throw new Error(
+      `${source}: \`toolkits\` must be an array of toolkit names.`,
+    );
+  }
+  const names: string[] = [];
+  for (const name of toolkits) {
+    if (typeof name !== "string" || !TOOLKIT_NAME_RE.test(name)) {
+      // A name outside the grammar can never match a declared toolkit, so this
+      // would bind the credential to nothing selectable.
+      throw new Error(
+        `${source}: \`toolkits\` entry ${JSON.stringify(name)} is not a ` +
+          `toolkit name (must match ${TOOLKIT_NAME_RE.source}).`,
+      );
+    }
+    if (!names.includes(name)) names.push(name);
+  }
+  if (names.length === 0 && unscoped !== true) {
+    throw new Error(
+      `${source}: binds no toolkits and no unscoped access, so this credential ` +
+        "could authenticate but never connect. List at least one toolkit, or " +
+        "pass `unscoped: true` to bind it to the full registry only.",
+    );
+  }
+  return Object.freeze({
+    toolkits: Object.freeze(names) as readonly string[],
+    ...(unscoped === true ? { unscoped: true } : {}),
+  });
+}
+
+/**
+ * Coerce an arbitrary value into a `ToolkitBinding`, or null when it is not one.
+ *
+ * The shipped adapters build bindings through `resolveToolkitBinding` above, but
+ * `InboundAuth` is an open interface and `AuthResult.toolkitBinding` arrives at
+ * REQUEST time from code connecta does not own — a custom adapter, or one
+ * mapping an IdP claim. Every field is therefore re-checked here rather than
+ * trusted from the type, because each way of being wrong fails OPEN if it is
+ * merely believed:
+ *
+ * - `unscoped` is compared to `true` by identity, so a truthy non-boolean (the
+ *   string `"false"` out of an env var, say) cannot grant the full registry;
+ * - `toolkits` must be a real array — a bare string would otherwise reach
+ *   `String.prototype.includes`, where `?toolkit=sup` would "match" `"support"`
+ *   by substring;
+ * - a missing/!array `toolkits` is not treated as an empty binding, because the
+ *   caller of a null return refuses the request outright.
+ *
+ * Returns a frozen, deduplicated copy: nothing downstream can be mutated by the
+ * adapter after the check, and every name is known to fit the grammar.
+ */
+export function normalizeToolkitBinding(value: unknown): ToolkitBinding | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const { toolkits, unscoped } = value as {
+    toolkits?: unknown;
+    unscoped?: unknown;
+  };
+  if (!Array.isArray(toolkits)) return null;
+  if (unscoped !== undefined && typeof unscoped !== "boolean") return null;
+  const names: string[] = [];
+  for (const name of toolkits) {
+    if (typeof name !== "string" || !TOOLKIT_NAME_RE.test(name)) return null;
+    if (!names.includes(name)) names.push(name);
+  }
+  return Object.freeze({
+    toolkits: Object.freeze(names) as readonly string[],
+    ...(unscoped === true ? { unscoped: true } : {}),
+  });
+}
+
+/**
+ * Resolve the binding one admitted identity is actually held to, from the
+ * provider's static declaration and whatever its `authorize` returned.
+ *
+ * - Neither ⇒ unbound (undefined), the pre-binding behavior.
+ * - Declaration only ⇒ the declaration.
+ * - Per-identity only ⇒ that binding, validated. This is the custom-adapter
+ *   seam: a provider that declares nothing is asserting it resolves membership
+ *   itself, so there is nothing to check it against.
+ * - Both ⇒ the **intersection**. The declaration is a CEILING, not a default: an
+ *   adapter that maps a user-writable IdP claim to toolkits must not be able to
+ *   widen the credential's own binding, which would turn "support token" into
+ *   "any toolkit, plus the full registry" for anyone who can set that claim.
+ *   Narrowing is fine and useful (per-user subsets of the team's view).
+ *
+ * A malformed binding on either side is not silently ignored — it returns
+ * `{ ok: false }` and the caller refuses the request, because the alternative
+ * (dropping it) is the fail-open reading.
+ */
+export function resolveIdentityBinding(
+  declared: unknown,
+  perIdentity: unknown,
+):
+  | { ok: true; binding?: ToolkitBinding }
+  | { ok: false; reason: string } {
+  const ceiling =
+    declared === undefined ? undefined : normalizeToolkitBinding(declared);
+  if (declared !== undefined && !ceiling) {
+    return {
+      ok: false,
+      reason:
+        "the toolkit binding declared on the provider is malformed " +
+        "(`toolkits` must be an array of toolkit names, `unscoped` a boolean)",
+    };
+  }
+  if (perIdentity === undefined) {
+    return ceiling ? { ok: true, binding: ceiling } : { ok: true };
+  }
+  const identity = normalizeToolkitBinding(perIdentity);
+  if (!identity) {
+    return {
+      ok: false,
+      reason:
+        "the toolkit binding its authorize() returned for this identity is " +
+        "malformed (`toolkits` must be an array of toolkit names, `unscoped` " +
+        "a boolean)",
+    };
+  }
+  if (!ceiling) return { ok: true, binding: identity };
+  return {
+    ok: true,
+    binding: Object.freeze({
+      toolkits: Object.freeze(
+        identity.toolkits.filter((name) => ceiling.toolkits.includes(name)),
+      ) as readonly string[],
+      ...(identity.unscoped === true && ceiling.unscoped === true
+        ? { unscoped: true }
+        : {}),
+    }),
+  };
+}
+
+/**
+ * Cross-check every statically declared binding against the deployment's
+ * toolkits, in `createConnecta`. A name that no toolkit declares is a typo, and
+ * a typo here fails CLOSED — the credential would be refused every connection
+ * with a 403 the client reads as a transport failure — so it throws at
+ * construction rather than becoming a support ticket. A structurally malformed
+ * declaration (only reachable from a hand-written `InboundAuth`, since the
+ * shipped adapters validate their own options) throws here too, rather than
+ * waiting to refuse every request at runtime.
+ *
+ * Bindings a provider mints per-identity (`AuthResult.toolkitBinding`) do not
+ * exist yet and cannot be checked here; they are validated on arrival and capped
+ * by the declaration (`resolveIdentityBinding`).
+ */
+export function validateToolkitBindings(
+  auth: readonly InboundAuth[],
+  toolkits: ReadonlyMap<string, Toolkit> | undefined,
+): void {
+  for (const provider of auth) {
+    if (provider.toolkitBinding === undefined) continue;
+    const binding = normalizeToolkitBinding(provider.toolkitBinding);
+    if (!binding) {
+      throw new Error(
+        `Inbound auth provider "${provider.kind}" declares a malformed ` +
+          "toolkitBinding: `toolkits` must be an array of toolkit names " +
+          `(matching ${TOOLKIT_NAME_RE.source}) and \`unscoped\` a boolean.`,
+      );
+    }
+    if (!toolkits || toolkits.size === 0) {
+      throw new Error(
+        `Inbound auth provider "${provider.kind}" binds toolkits ` +
+          `(${binding.toolkits.join(", ")}) but this deployment configures no ` +
+          "toolkits. Declare them in `toolkits`, or drop the binding.",
+      );
+    }
+    for (const name of binding.toolkits) {
+      if (!toolkits.has(name)) {
+        throw new Error(
+          `Inbound auth provider "${provider.kind}" binds unknown toolkit ` +
+            `"${name}". Configured toolkits: ${[...toolkits.keys()].join(", ")}.`,
+        );
+      }
+    }
+  }
+}

package/src/types.ts

@@ -164,6 +164,19 @@ export interface Connector {
     values: ConnectorCredentialValues,
     ctx: ConnectorContext,
   ): Promise<CredentialTestResult>;
+  /**
+   * Optional: whether this connector currently holds a stored downstream
+   * credential — an OAuth grant it persisted, typically. Read only by the
+   * credential liveness checks: a connector with nothing stored has no
+   * credential whose liveness could be in question, and probing it anyway would
+   * start an authorization flow nobody asked for.
+   *
+   * Implement it on connectors that manage their own credential storage (the
+   * shipped `remoteMcp` does, for `auth: { type: "oauth" }`). Connectors whose
+   * credential lives in connecta's vault (`credential` above) need not: the
+   * vault answers for them. Must not perform downstream I/O.
+   */
+  hasStoredCredential?(ctx: ConnectorContext): Promise<boolean>;
   /**
    * Statically-known tool defs, exposed by in-code connectors (`api()`) for
    * startup convention checks. Remote connectors omit this — their tools are
@@ -239,15 +252,69 @@ export interface Executor {
   execute(code: string, providers: ExecutorProvider[]): Promise<ExecuteResult>;
 }
 
+/**
+ * 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.
+ *
+ * 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
+ * time, before any scoped registry is constructed.
+ */
+export interface ToolkitBinding {
+  /** Toolkit names this identity may select with `?toolkit=<name>`. */
+  readonly toolkits: readonly string[];
+  /**
+   * Whether this identity may also connect with no `?toolkit=` and see the full
+   * registry (and read the deployment-wide operator surfaces). Defaults to
+   * false: binding a credential to a toolkit means binding it.
+   */
+  readonly unscoped?: boolean;
+}
+
 /** Result of an inbound-auth check. */
 export type AuthResult =
-  | { ok: true; userId?: string; subjectId?: string }
+  | {
+      ok: true;
+      userId?: string;
+      subjectId?: string;
+      /**
+       * Toolkit binding resolved for THIS identity — the seam for an adapter
+       * that maps its own users (or an IdP claim) to views. Omit to inherit the
+       * provider's `toolkitBinding`.
+       *
+       * When the provider also declares one, the declaration is a **CEILING**,
+       * not a default: connecta intersects the two, and grants `unscoped` only
+       * if both do. A per-identity binding can therefore narrow the credential's
+       * view but never widen it — otherwise an adapter reading a user-writable
+       * claim would let the user name their own toolkits. When the provider
+       * declares nothing, this binding is used as given.
+       *
+       * Validated on arrival (a malformed one refuses the request with 403
+       * rather than being ignored), but never checked against the configured
+       * toolkits, which is only possible for the static declaration at startup.
+       */
+      toolkitBinding?: ToolkitBinding;
+    }
   | { ok: false; response: Response };
 
 /** Public browser-auth configuration exposed to connecta's status UI. */
 export type UiAuthConfig = {
   kind: "clerk";
   publishableKey: string;
+  /**
+   * Origin `/ui` 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
+   * that Clerk could not load, and `createConnecta` names the drop in a startup
+   * warning.
+   */
   frontendApiUrl: string;
   signInUrl?: string;
   signUpUrl?: string;
@@ -300,6 +367,14 @@ export interface InboundAuth {
    * 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`.
+   */
+  toolkitBinding?: ToolkitBinding;
   /** Serve/short-circuit .well-known + OPTIONS. Return null when not handled. */
   handleMetadata?(
     request: Request,

package/src/ui.ts

@@ -158,6 +158,44 @@ export function isSafeIconHref(href: unknown): boolean {
   }
 }
 
+/**
+ * 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;
@@ -173,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;
@@ -257,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
@@ -355,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 } : {}),
       };
     }),
@@ -389,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
@@ -411,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>
@@ -991,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.5.0";
+export const CONNECTA_VERSION = "0.6.0";