@zackbart/connecta 0.5.0 → 0.6.1

package/src/credentials.ts

@@ -1,4 +1,8 @@
-import type { ConnectorCredentialValues, KVStorage } from "./types.js";
+import type {
+  Connector,
+  ConnectorCredentialValues,
+  KVStorage,
+} from "./types.js";
 
 const KEY_BYTES = 32;
 const IV_BYTES = 12;
@@ -35,6 +39,72 @@ export interface CredentialMetadata {
   fields?: Record<string, CredentialFieldMetadata>;
 }
 
+/** Which hook a testable credential is checked with. */
+export type CredentialTestMode = "single" | "multiple";
+
+/** A declared credential shape whose only test hook cannot test it. */
+export interface CredentialTestMismatch {
+  /** The shape the connector declared. */
+  shape: CredentialTestMode;
+  /** The hook it implements, which that shape cannot use. */
+  hook: "testCredential" | "testCredentials";
+}
+
+export interface CredentialTestRule {
+  /** The hook to call, or null when this credential cannot be tested at all. */
+  mode: CredentialTestMode | null;
+  /** Set only when the sole implemented hook is the one the shape cannot use. */
+  mismatch?: CredentialTestMismatch;
+}
+
+/**
+ * The one rule deciding whether a connector's credential can be tested — read
+ * by /ui's `testable` flag, by the `POST /ui/credentials/<id>/test` route when
+ * it picks a hook, and by the construction-time mismatch warning, so those
+ * three cannot drift apart.
+ *
+ * The declared credential *shape* selects the hook: named `credential.fields`
+ * are tested as a set by `testCredentials`, a single-value `credential` by
+ * `testCredential` on the vault's reserved `value` field. The other hook is
+ * never substituted — it would be handed a shape the connector never declared —
+ * so a connector implementing only the mismatched hook is not testable, and
+ * says so at construction rather than under an operator's click.
+ */
+export function credentialTestRule(
+  connector: Pick<
+    Connector,
+    "credential" | "testCredential" | "testCredentials"
+  >,
+): CredentialTestRule {
+  if (!connector.credential) return { mode: null };
+  if (connector.credential.fields?.length) {
+    if (connector.testCredentials) return { mode: "multiple" };
+    return connector.testCredential
+      ? { mode: null, mismatch: { shape: "multiple", hook: "testCredential" } }
+      : { mode: null };
+  }
+  if (connector.testCredential) return { mode: "single" };
+  return connector.testCredentials
+    ? { mode: null, mismatch: { shape: "single", hook: "testCredentials" } }
+    : { mode: null };
+}
+
+/**
+ * One clause naming a mismatch, shared by the startup warning and the test
+ * route's 400 so an operator reads the same explanation in both places.
+ */
+export function describeCredentialTestMismatch(
+  mismatch: CredentialTestMismatch,
+): string {
+  return mismatch.shape === "multiple"
+    ? "it declares named credential fields, which only " +
+        "`testCredentials(values, ctx)` can test, but implements " +
+        "`testCredential`"
+    : "it declares a single-value credential, which only " +
+        "`testCredential(value, ctx)` can test, but implements " +
+        "`testCredentials`";
+}
+
 function storageKey(connectorId: string): string {
   return `conn:${connectorId}:credential:v1`;
 }

package/src/execute.ts

@@ -2,7 +2,12 @@ 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 { RegistryView } from "./registry.js";
@@ -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,

package/src/index.ts

@@ -1,11 +1,24 @@
-import { CredentialVault } from "./credentials.js";
+import {
+  CredentialVault,
+  credentialTestRule,
+  describeCredentialTestMismatch,
+} from "./credentials.js";
 import { Registry } from "./registry.js";
 import { createFetchHandler } from "./server.js";
-import { droppedBrandingUrls } from "./ui.js";
-import { resolveToolkits, type ToolkitConfig } from "./toolkits.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,
@@ -38,9 +51,11 @@ export interface ConnectaConfig {
    * adding toolkits changes nothing for connections that don't ask for one; an
    * unknown name is an error, never a silent fallback.
    *
-   * Toolkits scope VISIBILITY, not identity: they do not decide *which* team
-   * member may select which toolkit. Gate that in `auth` (per-member binding is
-   * a follow-up).
+   * 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
@@ -127,6 +142,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;
@@ -152,6 +180,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 {
@@ -175,11 +226,13 @@ function normalizeAuth(auth: ConnectaConfig["auth"]): InboundAuth[] {
 /**
  * One-time construction warnings for deployment shapes that run fine but are
  * usually unintended. Warning-only — never throws and never changes behavior;
- * each condition emits at most one `logger.warn`. Iterates connectors once.
+ * each deployment-wide condition emits at most one `logger.warn`, and each
+ * per-connector condition at most one per connector it names.
  */
 function warnInsecureConfig(
   config: ConnectaConfig,
   inboundAuth: InboundAuth[],
+  toolkits: ReadonlyMap<string, Toolkit> | undefined,
   logger: Logger,
 ): void {
   const oauthConnectors = config.connectors.filter((c) => c.finishAuth);
@@ -210,17 +263,62 @@ function warnInsecureConfig(
     );
   }
 
-  // Toolkits with no inbound auth: a toolkit is a scoped VIEW selected by the
-  // caller, not an authentication boundary. With nothing gating /mcp, any
-  // caller picks any toolkit — or omits the parameter and sees everything.
-  if (inboundAuth.length === 0 && config.toolkits) {
-    logger.warn(
-      "[connecta] toolkits are configured but there is no inbound " +
-        "authentication: a toolkit is a scoped view a client selects with " +
-        "?toolkit=, not an access check, so any caller can choose any toolkit " +
-        "or omit the parameter and see every connector. Configure `auth` " +
-        "(for example bearerToken(...) or Clerk).",
-    );
+  // 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
@@ -235,6 +333,46 @@ function warnInsecureConfig(
     );
   }
 
+  // /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 URLs reach the browser: frontendApiUrl as the loader's
+  // `<script src>`, signInUrl/signUpUrl as the addresses ClerkJS navigates to.
+  // Gate-or-drop like a branding href: rendering drops a rejected value and the
+  // dashboard then either reports that Clerk could not load or quietly signs in
+  // through Clerk's defaults — both confusing symptoms 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: every uiAuth URL reaches the ` +
+        "browser — as the sign-in loader's source, or as a place Clerk sends " +
+        "the operator — so each must be an absolute https URL. A dropped " +
+        "value reaches no part of the page: without frontendApiUrl /ui renders " +
+        "no loader and cannot start a sign-in, and without signInUrl/signUpUrl " +
+        "it signs in through Clerk's defaults.",
+    );
+  }
+
+  // A credential test hook that cannot test the declared credential shape.
+  // The shape picks the hook (see `credentialTestRule`) and the other one is
+  // never substituted, so the connector is simply not testable: /ui offers no
+  // Test action and the route answers 400. Without this line the only way to
+  // discover the mistake is to click a button that isn't there.
+  for (const connector of config.connectors) {
+    const { mismatch } = credentialTestRule(connector);
+    if (!mismatch) continue;
+    logger.warn(
+      `[connecta] connector "${connector.id}" cannot test its credential: ` +
+        `${describeCredentialTestMismatch(mismatch)}. /ui offers no Test ` +
+        `action and POST /ui/credentials/${connector.id}/test answers 400 ` +
+        "until the matching hook is implemented.",
+    );
+  }
+
   // 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) {
@@ -269,6 +407,7 @@ 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
@@ -276,7 +415,11 @@ export function createConnecta(config: ConnectaConfig): Connecta {
   // 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,
@@ -307,6 +450,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 } : {}),
+      });
+    },
   };
 }
 
@@ -320,15 +486,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`. The resolved `Toolkit`
-// and the `ScopedRegistry` that enforces it are internal factoring.
-export type { ToolkitConfig, ToolkitDefinition } from "./toolkits.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";
@@ -346,6 +527,7 @@ export type {
   Executor,
   ExecutorProvider,
   InboundAuth,
+  ToolkitBinding,
   UiAuthConfig,
   AuthResult,
   JsonSchema,