@zackbart/connecta 0.8.0 → 0.9.0

package/src/index.ts

@@ -6,12 +6,6 @@ import {
 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 {
@@ -20,11 +14,6 @@ import {
   withExecutorAdmission,
 } from "./executor-admission.js";
 import type { ActivityReadGate, ActivityStore } from "./activity.js";
-import type {
-  CredentialCheckResult,
-  CredentialHealthConfig,
-} from "./credential-health.js";
-import type { DeferredWork } from "./connector-scope.js";
 import type {
   Connector,
   ConnectaBranding,
@@ -50,24 +39,13 @@ export interface ConnectaActivityConfig {
   deploymentId?: string;
 }
 
-/** Operator-vault encryption and proactive credential-health tuning. */
+/** Operator-vault encryption. */
 export interface ConnectaCredentialsConfig {
   /**
    * Base64-encoded 32-byte AES key for credentials managed on /credentials.
    * Keep this in the runtime's secret store, never in KV or source control.
    */
   encryptionKey?: string;
-  /**
-   * Tuning for proactive credential liveness checks that let a connector's
-   * status flip to `auth_required` before an agent's call fails. Defaults: one
-   * check per connector per 15 minutes, four in flight, 30 seconds each,
-   * triggered opportunistically by inbound authenticated traffic.
-   *
-   * Optional even without an encryption key because downstream OAuth connectors
-   * manage their own grants. `Connecta.checkCredentials()` runs the same checks
-   * on demand for a Worker cron trigger or Node interval.
-   */
-  health?: CredentialHealthConfig;
 }
 
 /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
@@ -156,38 +134,6 @@ export interface ConnectaAdmissionConfig {
 
 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;
   /** Inbound auth adapters. Includes bearerToken(...); omit for open (dev). */
   auth?: InboundAuth | InboundAuth[];
   /** KVStorage impl. Defaults to memoryStorage(). */
@@ -199,7 +145,7 @@ export interface ConnectaConfig {
   publicUrl?: string;
   /** Payload-free tool activity storage and operator-read policy. */
   activity?: ConnectaActivityConfig;
-  /** Operator credential vault and proactive liveness-check settings. */
+  /** Operator credential vault settings. */
   credentials?: ConnectaCredentialsConfig;
   /** Tool-catalog caching, persistence, stale fallback, and probe deadlines. */
   discovery?: ConnectaDiscoveryConfig;
@@ -235,37 +181,6 @@ 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) {
-   *   const defer = ctx.waitUntil.bind(ctx);
-   *   ctx.waitUntil(build(env).checkCredentials({ defer }));
-   * }
-   * // 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
-   * `credentials.health.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[];
-    /**
-     * Runtime continuation for bounded teardown after the check result is ready.
-     * Workers should pass `ctx.waitUntil.bind(ctx)`.
-     */
-    defer?: DeferredWork;
-  }) => Promise<CredentialCheckResult[]>;
   /** Drain and release configured executor resources. Idempotent. */
   close: () => Promise<void>;
 }
@@ -318,7 +233,6 @@ const LEGACY_CONFIG_MIGRATIONS = [
   ["activityReadGate", "activity.readGate"],
   ["activityDeploymentId", "activity.deploymentId"],
   ["credentialEncryptionKey", "credentials.encryptionKey"],
-  ["credentialHealth", "credentials.health"],
   ["toolCacheTtlSeconds", "discovery.catalogTtlSeconds"],
   ["persistToolCatalog", "discovery.persistCatalog"],
   ["toolCatalogStaleSeconds", "discovery.staleCatalogSeconds"],
@@ -337,6 +251,23 @@ const hasOwn = (value: object, key: PropertyKey): boolean =>
  */
 function assertNoLegacyConfig(config: ConnectaConfig): void {
   const candidate = config as unknown as Record<PropertyKey, unknown>;
+  if (hasOwn(candidate, "toolkits")) {
+    throw new Error(
+      "ConnectaConfig.toolkits was removed in issue #178. Deploy one " +
+        "connecta instance per audience instead; see ethos.md.",
+    );
+  }
+  const credentials = candidate.credentials;
+  const hasNestedHealth =
+    typeof credentials === "object" &&
+    credentials !== null &&
+    hasOwn(credentials, "health");
+  if (hasOwn(candidate, "credentialHealth") || hasNestedHealth) {
+    throw new Error(
+      "`credentials.health` and legacy `credentialHealth` were removed in " +
+        "issue #179. Credentials now fail at use; see ethos.md.",
+    );
+  }
   const found: Array<readonly [string, string]> = [];
   if (hasOwn(candidate, "activity")) {
     const activity = candidate.activity;
@@ -376,7 +307,6 @@ function assertNoLegacyConfig(config: ConnectaConfig): void {
 function warnInsecureConfig(
   config: ConnectaConfig,
   inboundAuth: InboundAuth[],
-  toolkits: ReadonlyMap<string, Toolkit> | undefined,
   logger: Logger,
 ): void {
   const oauthConnectors = config.connectors.filter((c) => c.finishAuth);
@@ -407,64 +337,6 @@ 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.
@@ -541,8 +413,10 @@ export function createConnecta(config: ConnectaConfig): Connecta {
   const credentialConnectors = config.connectors.filter((c) => c.credential);
   const encryptionKey = config.credentials?.encryptionKey;
   if (credentialConnectors.length > 0 && !encryptionKey) {
-    throw new Error(
-      `credentials.encryptionKey is required by connector credentials: ${credentialConnectors.map((c) => c.id).join(", ")}`,
+    logger.warn(
+      "Operator-managed credentials are unavailable because " +
+        "credentials.encryptionKey is not configured for connectors: " +
+        credentialConnectors.map((c) => c.id).join(", "),
     );
   }
   const credentialVault = encryptionKey
@@ -567,21 +441,9 @@ export function createConnecta(config: ConnectaConfig): Connecta {
     ...(config.calls?.maxBatchResultBytes !== undefined
       ? { maxBatchResultBytes: config.calls.maxBatchResultBytes }
       : {}),
-    ...(config.credentials?.health !== undefined
-      ? { credentialHealth: config.credentials.health }
-      : {}),
   });
-  // 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);
-  // 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);
+  warnInsecureConfig(config, inboundAuth, logger);
   const requestAdmission = admissionController(
     config.admission?.requests,
     REQUEST_ADMISSION_DEFAULTS,
@@ -637,7 +499,6 @@ export function createConnecta(config: ConnectaConfig): Connecta {
       ? { deploymentInfo: config.deploymentInfo }
       : {}),
     ...(config.branding !== undefined ? { branding: config.branding } : {}),
-    ...(toolkits ? { toolkits } : {}),
   });
   let closePromise: Promise<void> | undefined;
   return {
@@ -649,33 +510,6 @@ 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 } : {}),
-        },
-        opts.defer,
-      );
-    },
     close: async () => {
       closePromise ??= Promise.resolve().then(async () => {
         requestAdmission.close();
@@ -705,23 +539,6 @@ export { CONNECTA_VERSION } from "./version.js";
 // 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,
@@ -750,7 +567,6 @@ export type {
   ExecutorLease,
   ExecutorProvider,
   InboundAuth,
-  ToolkitBinding,
   UiAuthConfig,
   AuthResult,
   JsonSchema,

package/src/invocation.ts

@@ -13,6 +13,7 @@ import {
   classifyCallError,
   ConnectorCallError,
   messageLooksRetryable,
+  type AuthRecoveryMode,
   type CallErrorDetails,
 } from "./errors.js";
 import { unwrapMcpResult } from "./mcp-result.js";
@@ -81,6 +82,21 @@ function callerCancelledDetails(): CallErrorDetails {
   };
 }
 
+function recoveryMode(
+  registry: RegistryView,
+  connector: ResolvedCatalogTool["connector"],
+  baseUrl: string,
+): AuthRecoveryMode {
+  if (connector.startAuth) return "oauth";
+  if (
+    connector.credential &&
+    registry.contextFor(connector.id, baseUrl).credential
+  ) {
+    return "operator_config";
+  }
+  return "unavailable";
+}
+
 function isCallerCancellation(
   error: unknown,
   signal: AbortSignal | undefined,
@@ -155,6 +171,11 @@ export class InvocationFailure extends Error {
   readonly code: string;
   readonly retryable: boolean;
   readonly retryAfterMs: number | undefined;
+  readonly connector: string | undefined;
+  readonly operation: string | undefined;
+  readonly recovery: CallErrorDetails["recovery"];
+  readonly nextAction: CallErrorDetails["nextAction"];
+  readonly retry: string | undefined;
 
   constructor(readonly details: CallErrorDetails) {
     super(details.message);
@@ -162,6 +183,11 @@ export class InvocationFailure extends Error {
     this.code = details.code;
     this.retryable = details.retryable;
     this.retryAfterMs = details.retryAfterMs;
+    this.connector = details.connector;
+    this.operation = details.operation;
+    this.recovery = details.recovery;
+    this.nextAction = details.nextAction;
+    this.retry = details.retry;
   }
 }
 
@@ -262,13 +288,36 @@ export class InvocationService {
     };
     const failed = (error: CallErrorDetails): InvocationOutcome<T> => {
       const diagnostics = timing();
+      const target = resolved ?? activityTarget;
+      const details =
+        error.code === "auth_required" && target
+          ? {
+              ...error,
+              connector: target.connector.id,
+              operation: `${target.connector.id}.${target.toolName}`,
+              recovery: recoveryMode(
+                this.registry,
+                target.connector,
+                this.catalog.baseUrl,
+              ),
+              nextAction: {
+                tool: "authorize_connector" as const,
+                arguments: { connector: target.connector.id },
+                operatorHandoff:
+                  "Give the URL and instructions it returns to the operator.",
+              },
+              retry:
+                `Retry ${target.connector.id}.${target.toolName} after ` +
+                "the operator completes recovery.",
+            }
+          : error;
       record(
-        error.code === "timeout"
+        details.code === "timeout"
           ? "timeout"
-          : error.code === "cancelled"
+          : details.code === "cancelled"
             ? "cancelled"
             : "error",
-        error.code,
+        details.code,
       );
       return {
         ok: false,
@@ -276,7 +325,7 @@ export class InvocationService {
         attempts,
         timing: diagnostics,
         ...(resolved ? { resolved } : {}),
-        error,
+        error: details,
       };
     };
 
@@ -299,12 +348,9 @@ export class InvocationService {
         // against (a revoked downstream grant, say) still reads clean from the
         // cheap `list_connectors({ probe: false })` signal.
         //
-        // Recorded HERE rather than inside the registry's catalog fetch on
-        // purpose: `registry` is this connection's VIEW, so a toolkit-scoped
-        // session records into its own log as well as the deployment-wide one,
-        // which `Registry.refreshTools` could not reach. A cache hit that
-        // avoids a live listTools call records nothing either way — it is not
-        // evidence of health, and success stays what it has always been: an
+        // Recorded HERE rather than inside the registry's catalog fetch because
+        // a cache hit that avoids a live listTools call records nothing — it is
+        // not evidence of health. Success stays what it has always been: an
         // actual downstream call that returned.
         this.registry.recordFailure(
           resolution.connector.id,
@@ -383,6 +429,13 @@ export class InvocationService {
               : {}),
           },
         );
+        if (resolved.connector.credential && !connectorContext.credential) {
+          throw new ConnectorCallError(
+            "auth_required",
+            "Operator-managed credential storage is not configured. Call " +
+              `authorize_connector({ connector: "${resolved.connector.id}" }).`,
+          );
+        }
         let rejectCancelled!: (reason: unknown) => void;
         const cancelled = controller
           ? new Promise<never>((_, reject) => {