@zackbart/connecta 0.4.1 → 0.6.0

package/src/execute.ts

@@ -2,10 +2,15 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { compactSchema, rankTools, summarizeDescription } from "./catalog.js";
 import { recordToolActivity, type ActivityRequestContext } from "./activity.js";
-import { errorResult, jsonResult, type ToolResult } from "./meta-tools.js";
+import {
+  errorResult,
+  jsonResult,
+  serializeResultText,
+  type ToolResult,
+} from "./meta-tools.js";
 import { classifyCallError, ConnectorCallError } from "./errors.js";
 import { unwrapMcpResult } from "./mcp-result.js";
-import type { Registry } from "./registry.js";
+import type { RegistryView } from "./registry.js";
 import type {
   Connector,
   Executor,
@@ -98,7 +103,7 @@ export function unwrapForSandbox(
  * the raw-address escape hatch. Broken connectors are skipped, not fatal.
  */
 export async function buildSandboxProviders(
-  registry: Registry,
+  registry: RegistryView,
   baseUrl: string,
   logger: Logger,
   activity?: ActivityRequestContext,
@@ -132,6 +137,7 @@ export async function buildSandboxProviders(
     "__log",
   ]);
   const connectors = registry.listConnectors();
+  const catalogStarted = Date.now();
   const loaded = await Promise.allSettled(
     connectors.map((connector) =>
       registry.getTools(connector.id, baseUrl, requestScope),
@@ -249,8 +255,25 @@ export async function buildSandboxProviders(
     }
     const loadedTools = loaded[i];
     if (loadedTools.status === "rejected") {
+      // Same health accounting as the call_tool catalog catch: a connector whose
+      // catalog cannot be fetched is unusable, and dropping its namespace with
+      // only a warn would leave the cheap `list_connectors({ probe: false })`
+      // signal clean for a code-mode deployment whose downstream grant was
+      // revoked. Recorded through `registry` — this run's view — so a
+      // toolkit-scoped execute_code lands in that toolkit's log as well.
+      registry.recordFailure(
+        connector.id,
+        Date.now() - catalogStarted,
+        loadedTools.reason,
+      );
+      // classifyCallError so a typed auth_required thrown while listing tools
+      // keeps its code where an operator can see it; health stores the message.
+      const details = classifyCallError(
+        loadedTools.reason,
+        "catalog_lookup_failed",
+      );
       logger.warn(
-        `[connecta] execute_code: connector "${connector.id}" skipped: ${msg(loadedTools.reason)}`,
+        `[connecta] execute_code: connector "${connector.id}" skipped (${details.code}): ${msg(loadedTools.reason)}`,
       );
       continue;
     }
@@ -446,8 +469,9 @@ function truncate(text: string, max: number): string {
 }
 
 function guardResultValue(value: unknown): unknown {
-  const serialized = JSON.stringify(value, null, 2);
-  const text = serialized === undefined ? String(value) : serialized;
+  // Same serialization the call_tool guards measure, so a program returning
+  // nothing is rendered one way across every result path (issue #42).
+  const text = serializeResultText(value);
   if (text.length <= MAX_RESULT_CHARS) return value;
   return {
     truncated: true,
@@ -459,7 +483,7 @@ function guardResultValue(value: unknown): unknown {
 
 /** The execute_code handler. Exported for direct testing. */
 export function createExecuteTool(
-  registry: Registry,
+  registry: RegistryView,
   baseUrl: string,
   executor: Executor,
   logger: Logger,
@@ -527,7 +551,7 @@ Example: async () => { const r = await crm.search({ query: "roadmap" }); return
 /** Register the execute_code meta-tool. Only called when an executor is configured. */
 export function registerExecuteTool(
   server: McpServer,
-  registry: Registry,
+  registry: RegistryView,
   ctx: {
     baseUrl: string;
     executor: Executor;

package/src/index.ts

@@ -1,9 +1,20 @@
 import { CredentialVault } from "./credentials.js";
 import { Registry } from "./registry.js";
 import { createFetchHandler } from "./server.js";
+import { droppedBrandingUrls, droppedUiAuthUrls } from "./ui.js";
+import {
+  resolveToolkits,
+  validateToolkitBindings,
+  type Toolkit,
+  type ToolkitConfig,
+} from "./toolkits.js";
 import { memoryStorage } from "./storage/memory.js";
 import { CONNECTA_VERSION } from "./version.js";
 import type { ActivityReadGate, ActivityStore } from "./activity.js";
+import type {
+  CredentialCheckResult,
+  CredentialHealthConfig,
+} from "./credential-health.js";
 import type {
   Connector,
   ConnectaBranding,
@@ -15,6 +26,38 @@ import type {
 
 export interface ConnectaConfig {
   connectors: Connector[];
+  /**
+   * Named scoped views over `connectors`, selected per client connection with
+   * `?toolkit=<name>` on the `/mcp` URL. One deployment belongs to one org;
+   * a toolkit is the slice of it a group of team members sees.
+   *
+   * ```ts
+   * toolkits: {
+   *   support: { connectors: ["zendesk", "notion"] },
+   *   exec: {
+   *     connectors: ["zendesk", "notion", "gmail"],
+   *     excludeTools: ["gmail.send_message"],
+   *   },
+   * }
+   * ```
+   *
+   * Inside a toolkit-scoped session every meta-tool behaves as if out-of-scope
+   * connectors and tools do not exist, and an out-of-scope address fails
+   * exactly as a nonexistent one does. No `?toolkit=` ⇒ the full registry, so
+   * adding toolkits changes nothing for connections that don't ask for one; an
+   * unknown name is an error, never a silent fallback.
+   *
+   * Selection is self-service until a toolkit is BOUND to an inbound identity:
+   * pass `toolkits` to an auth adapter — `bearerToken(secret, { toolkits:
+   * ["support"] })` — and that credential may open only those toolkits, and may
+   * not connect unscoped unless it also passes `unscoped: true`. An unbound
+   * identity keeps the self-service behavior.
+   *
+   * Definitions are validated at construction: an unknown connector id, an
+   * empty connector selection, an empty `includeTools`, a malformed tool
+   * address, or an address naming no tool on an in-code connector all throw.
+   */
+  toolkits?: ToolkitConfig;
   /**
    * Privacy-minimal downstream tool activity storage. Writes are best-effort
    * and never change tool results. Implement `list` to enable the Activity UI.
@@ -58,7 +101,9 @@ export interface ConnectaConfig {
   toolCatalogStaleSeconds?: number;
   /**
    * Max inline result size (bytes) before call_tool/batch_call truncate and
-   * stash the full text for get_result paging. Default 50_000.
+   * stash the full text for get_result paging. Must be a whole number of bytes
+   * >= 1; anything else (0, negative, fractional, NaN, Infinity) warns at
+   * startup and falls back to the default 50_000.
    */
   maxResultBytes?: number;
   /**
@@ -93,6 +138,19 @@ export interface ConnectaConfig {
    * real cancellation of the downstream request is a deferred follow-up.
    */
   probeTimeoutMs?: number;
+  /**
+   * Tuning for the proactive credential liveness checks (issue #24) that let a
+   * connector's status flip to `auth_required` *before* an agent's call fails.
+   * Defaults are safe to leave alone: at most one check per connector per 15
+   * minutes, four in flight, 30 s each, triggered opportunistically by inbound
+   * authenticated traffic. Only connectors holding a credential connecta stores
+   * — an operator-managed `credential`, or a downstream-OAuth grant — are ever
+   * checked, and a check never calls a downstream tool.
+   *
+   * `Connecta.checkCredentials()` is the same check on demand, for a Worker cron
+   * trigger or a Node interval.
+   */
+  credentialHealth?: CredentialHealthConfig;
   serverInfo?: {
     name?: string;
     version?: string;
@@ -118,6 +176,29 @@ export interface Connecta {
   /** Web-standard fetch handler. Usable as `export default { fetch: connecta.fetch }`. */
   fetch: (request: Request, env?: unknown, ctx?: unknown) => Promise<Response>;
   registry: Registry;
+  /**
+   * Check the stored downstream credentials now — the scheduler-facing half of
+   * credential health (issue #24). Wire it to whatever timer the runtime has:
+   *
+   * ```ts
+   * // Cloudflare Workers (wrangler.jsonc: "triggers": { "crons": ["*\/15 * * * *"] })
+   * async scheduled(_c, env, ctx) { ctx.waitUntil(build(env).checkCredentials()); }
+   * // Node
+   * setInterval(() => void connecta.checkCredentials(), 15 * 60_000).unref();
+   * ```
+   *
+   * Returns one outcome per connector considered, including why a connector was
+   * skipped (`fresh` is the rate limit: a connector checked less than
+   * `credentialHealth.intervalSeconds` ago is not re-checked unless `force`).
+   * Never rejects on a connector failure — a broken connector becomes an `error`
+   * verdict. Needs a base URL for connector contexts: `publicUrl` supplies it,
+   * or pass one.
+   */
+  checkCredentials: (opts?: {
+    baseUrl?: string;
+    force?: boolean;
+    ids?: string[];
+  }) => Promise<CredentialCheckResult[]>;
 }
 
 function defaultLogger(): Logger {
@@ -146,6 +227,7 @@ function normalizeAuth(auth: ConnectaConfig["auth"]): InboundAuth[] {
 function warnInsecureConfig(
   config: ConnectaConfig,
   inboundAuth: InboundAuth[],
+  toolkits: ReadonlyMap<string, Toolkit> | undefined,
   logger: Logger,
 ): void {
   const oauthConnectors = config.connectors.filter((c) => c.finishAuth);
@@ -176,6 +258,95 @@ function warnInsecureConfig(
     );
   }
 
+  // Toolkits that nothing binds to an identity: selection is then self-service,
+  // and the boundary organizes the surface rather than protecting it. Three
+  // distinct shapes, so three distinct warnings — an operator can only act on
+  // the one they are actually in.
+  //
+  // All are keyed off the RESOLVED toolkits, which is the same map `?toolkit=`
+  // resolves against, rather than the presence of the config key: `toolkits: {}`
+  // is a truthy object that resolves to nothing selectable, so warning about a
+  // choice no caller can make would name a risk that does not exist.
+  if (toolkits) {
+    const unbound = inboundAuth.filter((provider) => !provider.toolkitBinding);
+    if (inboundAuth.length === 0) {
+      // No auth at all ⇒ no identity exists to bind, so binding is not even the
+      // fix here. The open-mode warning above covers the wider exposure.
+      logger.warn(
+        "[connecta] toolkits are configured but there is no inbound " +
+          "authentication: with no identity to bind a toolkit to, any caller " +
+          "can choose any toolkit or omit ?toolkit= and see every connector. " +
+          "Configure `auth` (for example bearerToken(...) or Clerk), then bind " +
+          "each credential with `toolkits: [...]`.",
+      );
+    } else if (unbound.length === inboundAuth.length) {
+      // Authenticated, but every credential may still select every view. This is
+      // the shape issue #37 exists to close, and it is invisible without a line
+      // saying so: nothing fails, the teams are simply not separated.
+      logger.warn(
+        "[connecta] toolkits are configured but no inbound identity is bound " +
+          "to one: every credential `auth` admits can select any toolkit, or " +
+          "omit ?toolkit= and see the whole deployment, so a token handed to " +
+          "one team also opens the others' views. Bind each credential with " +
+          "`toolkits: [...]` on its auth adapter (add `unscoped: true` for an " +
+          "operator credential that should still see everything).",
+      );
+    } else if (unbound.length > 0) {
+      // The dangerous middle: SOME credentials are bound, which is exactly when
+      // an operator believes the deployment is separated — while one forgotten
+      // provider still opens every view and the whole deployment-wide surface.
+      // Naming the unbound providers is the point; an intentionally unrestricted
+      // credential says so with `unscoped: true` and stops appearing here.
+      const counted = new Map<string, number>();
+      for (const provider of unbound) {
+        counted.set(provider.kind, (counted.get(provider.kind) ?? 0) + 1);
+      }
+      const named = [...counted]
+        .map(([kind, count]) => (count > 1 ? `${kind} x${count}` : kind))
+        .join(", ");
+      logger.warn(
+        `[connecta] toolkits are bound on some inbound auth providers but not ` +
+          `all: ${named} ${unbound.length === 1 ? "declares" : "declare"} no ` +
+          "binding, so a caller that provider admits can still select any " +
+          "toolkit, connect unscoped, and read the deployment-wide operator " +
+          "surfaces — whatever the bound credentials beside it allow. Bind it " +
+          "too, or declare the exemption with `toolkits: [...], unscoped: true` " +
+          "if it is meant to be an operator credential.",
+      );
+    }
+  }
+
+  // Branding URLs that failed their scheme gate. Rendering silently falls back
+  // (a bad URL must not take the page down), so this warning is the only way an
+  // operator learns their value never reached the page.
+  const dropped = droppedBrandingUrls(config.branding);
+  if (dropped.length > 0) {
+    logger.warn(
+      `[connecta] branding ${dropped.join(", ")} dropped: a branding URL is ` +
+        "used as an href, so it must be an absolute http(s) URL (favicon.href " +
+        "may also be a root-relative path). The default is rendered instead.",
+    );
+  }
+
+  // /ui renders exactly one provider's browser sign-in config — the first that
+  // offers one, which is the same `find` the /ui route performs — and that
+  // provider's frontendApiUrl becomes the loader's `<script src>`. Gate-or-drop
+  // like a branding href: rendering omits the loader for a rejected value and
+  // the dashboard then reports that Clerk could not load, a confusing symptom
+  // without this line naming the cause. Checking only the rendered provider
+  // keeps the claim true — a later provider's uiAuth never reaches the page, so
+  // there is nothing there to warn about.
+  const uiAuthProvider = inboundAuth.find((provider) => provider.uiAuth);
+  const droppedUiAuth = droppedUiAuthUrls(uiAuthProvider?.uiAuth);
+  if (uiAuthProvider && droppedUiAuth.length > 0) {
+    logger.warn(
+      `[connecta] inbound auth provider "${uiAuthProvider.kind}" had ` +
+        `${droppedUiAuth.join(", ")} dropped: the browser sign-in loader is ` +
+        "fetched from this origin, so it must be an absolute https URL. /ui " +
+        "renders without the loader and cannot start a sign-in.",
+    );
+  }
+
   // 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) {
@@ -210,9 +381,19 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     persistToolCatalog: config.persistToolCatalog,
     toolCatalogStaleSeconds: config.toolCatalogStaleSeconds,
     maxResultBytes: config.maxResultBytes,
+    credentialHealth: config.credentialHealth,
   });
+  // Throws on every structural mistake it can see (see resolveToolkits): a
+  // typo must not become a scope the operator never wrote. Note this is about
+  // the scope being *intended*, not about it being an access check — a toolkit
+  // scopes visibility, and `auth` remains the thing deciding who gets in.
+  const toolkits = resolveToolkits(config.toolkits, config.connectors);
   const inboundAuth = normalizeAuth(config.auth);
-  warnInsecureConfig(config, inboundAuth, logger);
+  // Same contract for the identity half: a binding that names a toolkit this
+  // deployment does not declare would deny that credential every connection,
+  // with a 403 its client reports as a transport failure. Throw here instead.
+  validateToolkitBindings(inboundAuth, toolkits);
+  warnInsecureConfig(config, inboundAuth, toolkits, logger);
   const handler = createFetchHandler({
     registry,
     auth: inboundAuth,
@@ -232,6 +413,7 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     credentialVault,
     deploymentInfo: config.deploymentInfo,
     branding: config.branding,
+    ...(toolkits ? { toolkits } : {}),
   });
   return {
     fetch: (request, _env, ctx) =>
@@ -242,6 +424,29 @@ export function createConnecta(config: ConnectaConfig): Connecta {
           : undefined,
       ),
     registry,
+    checkCredentials: (opts = {}) => {
+      // A scheduled check has no inbound request to derive an origin from, and
+      // a connector context without one would mint OAuth redirect URIs against
+      // a guess. Say so instead: the fix is one config line.
+      const baseUrl = opts.baseUrl ?? config.publicUrl;
+      if (!baseUrl) {
+        // Rejected, not thrown: the callers this is written for are
+        // `ctx.waitUntil(...)` and `.catch(...)` on the returned promise, and a
+        // synchronous throw escapes both — it would take down a scheduled
+        // handler instead of being reported by it.
+        return Promise.reject(
+          new Error(
+            "checkCredentials() needs a base URL: set `publicUrl` on the " +
+              "config (recommended — it is also what downstream OAuth " +
+              "callbacks use) or pass checkCredentials({ baseUrl }).",
+          ),
+        );
+      }
+      return registry.checkCredentialHealth(baseUrl, {
+        ...(opts.force !== undefined ? { force: opts.force } : {}),
+        ...(opts.ids ? { ids: opts.ids } : {}),
+      });
+    },
   };
 }
 
@@ -255,12 +460,30 @@ export type { ConnectorCallErrorCode, CallErrorDetails } from "./errors.js";
 export { validateToolInput } from "./validate.js";
 export type { ValidateToolInputOptions } from "./validate.js";
 export { bearerToken } from "./auth/bearer.js";
+export type { BearerTokenOptions } from "./auth/bearer.js";
 export { memoryStorage } from "./storage/memory.js";
 export { CONNECTA_VERSION } from "./version.js";
 // Registry is reachable through `Connecta.registry`, so its type is public;
 // the class itself, the credential vault, and the meta-tool/sandbox factories
 // are internal factoring and are deliberately not part of the API surface.
 export type { Registry } from "./registry.js";
+// Config-as-code shapes for `ConnectaConfig.toolkits` and the identity bindings
+// that gate them. The resolved `Toolkit` and the `ScopedRegistry` that enforces
+// it are internal factoring.
+export type {
+  ToolkitBindingOptions,
+  ToolkitConfig,
+  ToolkitDefinition,
+} from "./toolkits.js";
+// Credential health: the config shape, and the result shape a scheduled
+// `checkCredentials()` returns. The checker itself is internal factoring.
+export type {
+  CredentialCheckResult,
+  CredentialCheckSkip,
+  CredentialCheckState,
+  CredentialHealthConfig,
+  CredentialHealthRecord,
+} from "./credential-health.js";
 
 export type { RemoteMcpOptions, RemoteMcpAuth } from "./connectors/remote-mcp.js";
 export type { ApiOptions, ApiTool } from "./connectors/api.js";
@@ -278,6 +501,7 @@ export type {
   Executor,
   ExecutorProvider,
   InboundAuth,
+  ToolkitBinding,
   UiAuthConfig,
   AuthResult,
   JsonSchema,