@zackbart/connecta 0.6.0 → 0.7.0

package/src/credential-health.ts

@@ -5,7 +5,7 @@
 // something *observed* a failure, so an expired or revoked token surfaced
 // mid-task as a failed agent call. A liveness check asks the connector whether
 // the credential it holds still works, records the verdict, and lets the cached
-// status surfaces (`list_connectors({ probe: false })`, `/ui`) report
+// status surfaces (`list_connectors({ probe: false })`, operator pages) report
 // `auth_required` BEFORE a real call discovers it.
 //
 // Runtime-agnostic on purpose: nothing here schedules itself. The core exposes a
@@ -15,7 +15,12 @@
 // There is no background daemon and no long-lived timer, so Workers and Node run
 // the same code.
 
+import {
+  credentialTestRule,
+  storedCredentialShape,
+} from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
+import { closeConnectorScope } from "./connector-scope.js";
 import { DEFAULT_PROBE_TIMEOUT_MS, normalizeTimeoutMs, withTimeout } from "./timeout.js";
 import type {
   Connector,
@@ -48,8 +53,9 @@ export interface CredentialHealthRecord {
  *   through an explicit `ids` request, and reported rather than dropped so a
  *   typo in a scheduled check is visible instead of silent.
  * - `not_checkable` — it stores no credential connecta manages, or exposes no
- *   usable way to ask: neither `status()` nor a credential test hook that fits
- *   the stored value's shape.
+ *   usable way to ask: neither `status()` nor a credential test hook the
+ *   declared credential shape can use (`credentialTestRule`), against a value
+ *   actually stored under it.
  * - `no_credential` — checkable, but nothing is stored yet: there is no
  *   credential whose liveness could be in question, and probing would start an
  *   OAuth flow nobody asked for.
@@ -326,7 +332,10 @@ export interface CredentialCheckOptions {
   force?: boolean;
   /** Restrict the sweep to these connector ids. Default: every connector. */
   ids?: string[];
-  /** Request-scope identity to reuse a connector's per-request resources. */
+  /**
+   * Internal scope identity supplied by an existing owner. When omitted, the
+   * check creates and ends its own probe scope.
+   */
   requestScope?: object;
 }
 
@@ -337,46 +346,66 @@ export interface CredentialCheckOptions {
  * Deliberately narrow. `listTools`/`callTool` are NOT liveness probes here: a
  * tool call may mutate downstream state, and the catalog path is already covered
  * by the existing probe. So a connector is checkable only through the two hooks
- * that exist to answer exactly this question — `testCredential(s)` (what /ui's
+ * that exist to answer exactly this question — `testCredential(s)` (what the
  * Test button runs) and `status()` — and only when it has a credential of ours
  * to be asked about: an operator-managed `credential`, or a stored downstream
  * grant it reports via `hasStoredCredential`. A static-token connector stores
  * nothing here and is never probed on a timer.
+ *
+ * Whether a test hook counts is `credentialTestRule`'s call, not this function's
+ * Credentials Test button and the credential API read (issue #55), so
+ * a credential the operator cannot test by hand is not one a sweep tests behind
+ * their back. A connector whose only hook cannot test its declared shape is
+ * checkable only if it also implements `status()`.
  */
 export function isCheckableConnector(connector: Connector): boolean {
   const hasCredentialStore = Boolean(
     connector.credential || connector.hasStoredCredential,
   );
   const canAsk = Boolean(
-    (connector.credential &&
-      (connector.testCredentials || connector.testCredential)) ||
-      connector.status,
+    credentialTestRule(connector).mode !== null || connector.status,
   );
   return hasCredentialStore && canAsk;
 }
 
 /**
- * The credential test that fits the STORED value's shape, or undefined.
+ * The credential test the connector's DECLARED shape selects, bound to what is
+ * actually stored — or undefined when there is no honest question to put.
  *
  * `isCheckableConnector` answers the static question ("could this connector be
- * asked at all"); this answers it against what is actually in the vault. The gap
- * that matters is a connector with named fields but only the single-value
- * `testCredential` hook: handing it `values.value` — the reserved single-value
- * field, absent here — would test the empty string and record a confident
- * `auth_required` about a credential nothing examined. The credential API
- * refuses that same shape with a 409 rather than testing it; here the connector
- * is skipped rather than given an invented verdict.
+ * asked at all"); this answers it against the vault. The hook itself is picked
+ * by `credentialTestRule` (src/credentials.ts, issue #55), the one rule the UI's
+ * `testable` flag and `POST /ui/credentials/<id>/test` also read: named
+ * `credential.fields` are tested as a set by `testCredentials`, a single-value
+ * `credential` by `testCredential` on the vault's reserved `value` field, and
+ * the other hook is never substituted. Substituting it is what a sweep must not
+ * do quietly — handing `testCredential` a `values.value` that named fields never
+ * wrote would test the empty string and record a confident `auth_required` about
+ * a credential nothing examined, and handing `testCredentials` the reserved
+ * `{ value }` map would call a hook with a shape its connector never declared.
+ * Either way the connector is skipped (`not_checkable`) rather than given an
+ * invented verdict, and `createConnecta` already warned about the mismatch at
+ * construction.
  */
 function testHookFor(
   connector: Connector,
   values: ConnectorCredentialValues | null,
 ): ((ctx: ConnectorContext) => Promise<CredentialTestResult>) | undefined {
-  if (!values) return undefined;
-  if (connector.testCredentials) {
-    return (ctx) => connector.testCredentials!(values, ctx);
+  if (
+    !connector.credential ||
+    storedCredentialShape(connector.credential, values).state !== "valid"
+  ) {
+    return undefined;
+  }
+  const storedValues = values!;
+  const { mode } = credentialTestRule(connector);
+  if (mode === "multiple") {
+    return (ctx) => connector.testCredentials!(storedValues, ctx);
   }
-  if (connector.testCredential && typeof values.value === "string") {
-    return (ctx) => connector.testCredential!(values.value, ctx);
+  // A single-value shape with nothing under the reserved field is still nothing
+  // to test, so the stored value gets the last word even when the rule fits.
+  if (mode === "single" && typeof storedValues.value === "string") {
+    return (ctx) => connector.testCredential!(storedValues.value, ctx);
   }
   return undefined;
 }
@@ -417,8 +446,8 @@ async function mapWithConcurrency<T, R>(
  *    triggered sweep per interval per isolate, and never two at once, so a burst
  *    of requests costs one sweep, not one per request.
  * 4. **Deadline + fan-out bound** — each check is bounded by `timeoutMs` and at
- *    most `concurrency` run together (the same shape as the `probeTimeoutMs`
- *    bound on the discovery fan-out, issue #19).
+ *    most `concurrency` run together (the same shape as the
+ *    `discovery.probeTimeoutMs` bound on the discovery fan-out, issue #19).
  */
 export class CredentialHealthChecker {
   private readonly store: CredentialHealthStore;
@@ -557,16 +586,12 @@ export class CredentialHealthChecker {
         ...(await this.recordOrNothing(connectorId)),
       };
     }
-    if (!opts.force) {
-      const current = await this.store.get(connectorId);
-      if (
-        current &&
-        Date.now() - Date.parse(current.checkedAt) < this.intervalMs
-      ) {
-        return { connectorId, skipped: "fresh", record: current };
-      }
-    }
-    const run = this.runCheck(connector, baseUrl, opts.requestScope);
+    const run = this.runCheck(
+      connector,
+      baseUrl,
+      opts.force ?? false,
+      opts.requestScope,
+    );
     this.inFlight.set(connectorId, run);
     try {
       return await run;
@@ -585,63 +610,118 @@ export class CredentialHealthChecker {
   private async runCheck(
     connector: Connector,
     baseUrl: string,
+    force: boolean,
     requestScope?: object,
   ): Promise<CredentialCheckResult> {
     const connectorId = connector.id;
     const started = Date.now();
-    // Captured BEFORE anything downstream happens: everything after this point
-    // is a window in which the operator may replace the very credential being
-    // judged, and `settle` fences the write against exactly that.
+    // Captured BEFORE anything downstream happens — including the vault read
+    // below: everything after this point is a window in which the operator may
+    // replace the very credential being judged, and `settle` fences the write
+    // against exactly that. It cannot move later to save a read on the fresh
+    // path; a generation sampled AFTER the values would miss a `clear` that
+    // landed between the two and let a verdict about the replaced credential
+    // through the fence.
     const generation = await this.store.generation(connectorId);
-    const ctx = this.deps.contextFor(connectorId, baseUrl, requestScope);
     let values: ConnectorCredentialValues | null = null;
+    let credentialReadError: unknown;
     if (connector.credential && this.deps.credentialVault) {
       try {
         values = await this.deps.credentialVault.getAll(connectorId);
       } catch (err) {
-        // A stored credential that cannot be decrypted (rotated key, corrupt
-        // envelope) is exactly the kind of dead credential this feature exists
-        // to surface early, so it is a verdict rather than a skip.
+        credentialReadError = err;
+      }
+      const shape = storedCredentialShape(connector.credential, values);
+      if (shape.state === "mismatch") {
+        // Drift is a persistent operator-error state, not an event: left
+        // outside the freshness gate it would spend a write on every sweep in
+        // every isolate, forever, against exactly the deployments this feature
+        // is meant to help (and on Cloudflare KV those writes are metered).
+        // Once the SAME drift verdict is already stored and still fresh, this
+        // is the rate limit doing its job, same as a fresh `ok`. A stored
+        // verdict that says anything else — a pre-redeploy `ok`, a different
+        // message — is still replaced immediately, which is the whole point of
+        // checking the shape before the gate.
+        if (!force) {
+          const current = await this.store.get(connectorId);
+          if (
+            current &&
+            current.state === "error" &&
+            current.message === shape.message &&
+            Date.now() - Date.parse(current.checkedAt) < this.intervalMs
+          ) {
+            return { connectorId, skipped: "fresh", record: current };
+          }
+        }
         return this.settle(connectorId, started, generation, {
-          state: "auth_required",
+          state: "error",
           checkedAt: new Date().toISOString(),
-          message: msg(err),
+          message: shape.message,
         });
       }
     }
-    const stored = connector.hasStoredCredential
-      ? await connector
-          .hasStoredCredential(ctx)
-          .catch(() => values !== null)
-      : values !== null;
-    if (!stored) return { connectorId, skipped: "no_credential" };
-    if (!this.canAsk(connector, values)) {
-      return { connectorId, skipped: "not_checkable" };
+    // Shape drift is checked before this shortcut so an old, still-fresh `ok`
+    // cannot survive a redeploy that changed the credential declaration.
+    if (!force) {
+      const current = await this.store.get(connectorId);
+      if (
+        current &&
+        Date.now() - Date.parse(current.checkedAt) < this.intervalMs
+      ) {
+        return { connectorId, skipped: "fresh", record: current };
+      }
     }
-
+    const ownsScope = requestScope === undefined;
+    const scope = requestScope ?? {};
+    const ctx = this.deps.contextFor(connectorId, baseUrl, scope);
     try {
-      const verdict = await withTimeout(
-        this.probe(connector, ctx, values),
-        this.timeoutMs,
-        `credential check of "${connectorId}"`,
-      );
-      return await this.settle(connectorId, started, generation, {
-        ...verdict,
-        checkedAt: new Date().toISOString(),
-      });
-    } catch (err) {
-      return await this.settle(connectorId, started, generation, {
-        state: "error",
-        checkedAt: new Date().toISOString(),
-        message: msg(err),
-      });
+      if (credentialReadError) {
+        // A stored credential that cannot be decrypted (rotated key, corrupt
+        // envelope) is exactly the kind of dead credential this feature
+        // exists to surface early, so it is a verdict rather than a skip.
+        return this.settle(connectorId, started, generation, {
+          state: "auth_required",
+          checkedAt: new Date().toISOString(),
+          message: msg(credentialReadError),
+        });
+      }
+      const stored = connector.hasStoredCredential
+        ? await connector
+            .hasStoredCredential(ctx)
+            .catch(() => values !== null)
+        : values !== null;
+      if (!stored) return { connectorId, skipped: "no_credential" };
+      if (!this.canAsk(connector, values)) {
+        return { connectorId, skipped: "not_checkable" };
+      }
+
+      try {
+        const verdict = await withTimeout(
+          this.probe(connector, ctx, values),
+          this.timeoutMs,
+          `credential check of "${connectorId}"`,
+        );
+        return await this.settle(connectorId, started, generation, {
+          ...verdict,
+          checkedAt: new Date().toISOString(),
+        });
+      } catch (err) {
+        return await this.settle(connectorId, started, generation, {
+          state: "error",
+          checkedAt: new Date().toISOString(),
+          message: msg(err),
+        });
+      }
+    } finally {
+      if (ownsScope) await closeConnectorScope(connector, ctx);
     }
   }
 
   /**
-   * `isCheckableConnector` re-asked against what is actually stored: a hook that
-   * fits the value's shape (see {@link testHookFor}), or a `status()` to fall
-   * back on. Neither ⇒ there is no honest question to put to this connector.
+   * `isCheckableConnector` re-asked against what is actually stored: the hook
+   * the declared shape selects, bound to a value that fits it (see
+   * {@link testHookFor}), or a `status()` to fall back on. Neither ⇒ there is no
+   * honest question to put to this connector.
    */
   private canAsk(
     connector: Connector,
@@ -670,12 +750,12 @@ export class CredentialHealthChecker {
       }
       // A rejected stored credential needs an operator, not a retry — the same
       // actionable state a revoked OAuth grant reports. There is no consent URL
-      // for a vault credential; /ui's credential form is where it is replaced.
+      // for a vault credential; /credentials is where it is replaced.
       return {
         state: "auth_required",
         message:
           result.message ??
-          "Stored credential was rejected by the connector — replace it in /ui.",
+          "Stored credential was rejected by the connector — replace it in /credentials.",
       };
     }
     const status = await connector.status!(ctx);

package/src/credentials.ts

@@ -1,4 +1,9 @@
-import type { ConnectorCredentialValues, KVStorage } from "./types.js";
+import type {
+  Connector,
+  ConnectorCredentialConfig,
+  ConnectorCredentialValues,
+  KVStorage,
+} from "./types.js";
 
 const KEY_BYTES = 32;
 const IV_BYTES = 12;
@@ -35,6 +40,164 @@ export interface CredentialMetadata {
   fields?: Record<string, CredentialFieldMetadata>;
 }
 
+/** Which hook a testable credential is checked with. */
+export type CredentialTestMode = "single" | "multiple";
+
+/** Operator-safe explanation shared by every surface that detects shape drift. */
+export const STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR =
+  "Stored credential fields do not match this connector's current declaration. Replace the credential before using or testing this connector.";
+
+export type StoredCredentialShape =
+  | { state: "missing" }
+  | {
+      state: "valid";
+      mode: CredentialTestMode;
+      /**
+       * Stored keys the connector no longer declares, sorted. Harmless — the
+       * credential works — but worth telling an operator about, since nothing
+       * else in `/ui` can show a field the declaration has stopped naming.
+       */
+      undeclared: string[];
+    }
+  | {
+      state: "mismatch";
+      mode: CredentialTestMode;
+      message: typeof STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR;
+    };
+
+/**
+ * Compare a connector's current declaration with the keys in its stored
+ * credential. Values are deliberately ignored: callers may pass decrypted
+ * values or `/credentials`' masked field metadata and get the same answer.
+ *
+ * The test is CONTAINMENT, not equality: the stored key set is compatible when
+ * it holds every field currently declared — the reserved `value` key for a
+ * single-value declaration, every declared name for a named one. Anything the
+ * declaration asks for and the vault does not have is `mismatch`, which is
+ * precisely what a renamed field, a newly added field, or a swap between the
+ * two shapes produces. The swap needs no special case: `value` is never one of
+ * the declared names, so single→named and named→single each leave the declared
+ * side unsatisfied. An empty stored map (reachable through a hand-written
+ * plaintext) satisfies nothing and is a mismatch too.
+ *
+ * Extra keys are NOT drift. They are what *dropping* a field leaves behind, and
+ * every accessor a connector actually uses — `ctx.credential.get("apiKey")`,
+ * `getAll().apiKey` — keeps returning the right secret across that redeploy.
+ * Calling it drift would order an operator to re-enter a working secret that
+ * many providers will not reissue in readable form. The leftovers come back as
+ * `undeclared` instead, for a surface to mention without blocking anything.
+ */
+export function storedCredentialShape(
+  config: ConnectorCredentialConfig,
+  stored: Readonly<Record<string, unknown>> | null,
+): StoredCredentialShape {
+  if (!stored) return { state: "missing" };
+  const mode: CredentialTestMode = config.fields?.length
+    ? "multiple"
+    : "single";
+  const declared = new Set(
+    mode === "multiple" ? config.fields!.map((field) => field.name) : ["value"],
+  );
+  const actual = Object.keys(stored);
+  const present = new Set(actual);
+  for (const field of declared) {
+    if (!present.has(field)) {
+      return {
+        state: "mismatch",
+        mode,
+        message: STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR,
+      };
+    }
+  }
+  return {
+    state: "valid",
+    mode,
+    undeclared: actual.filter((field) => !declared.has(field)).sort(),
+  };
+}
+
+/** How many leftover field names an advisory names before it summarizes. */
+const UNDECLARED_SAMPLE = 5;
+
+/**
+ * The one sentence describing leftover stored fields, so every surface words it
+ * the same way. Names only — the values stay in the vault, and a field name from
+ * a previous declaration is not a secret. Deliberately reassuring: nothing is
+ * broken, and the only thing an operator gains by acting is that a connector
+ * iterating `getAll()` stops seeing a field its code no longer knows about.
+ */
+export function describeUndeclaredCredentialFields(fields: string[]): string {
+  const shown = fields.slice(0, UNDECLARED_SAMPLE);
+  const rest = fields.length - shown.length;
+  const named = shown.join(", ") + (rest > 0 ? `, and ${rest} more` : "");
+  return fields.length === 1
+    ? `Stored credential also holds a field this connector no longer declares (${named}). It keeps working; replace the credential to drop it.`
+    : `Stored credential also holds fields this connector no longer declares (${named}). It keeps working; replace the credential to drop them.`;
+}
+
+/** 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 /credentials' `testable` flag, by `POST /ui/credentials/<id>/test` 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`;
 }
@@ -51,7 +214,7 @@ function base64ToBytes(value: string): Uint8Array {
     binary = atob(value);
   } catch {
     throw new Error(
-      "credentialEncryptionKey must be a base64-encoded 32-byte key",
+      "credentials.encryptionKey must be a base64-encoded 32-byte key",
     );
   }
   return Uint8Array.from(binary, (char) => char.charCodeAt(0));
@@ -146,7 +309,7 @@ export class CredentialVault {
     const raw = base64ToBytes(encryptionKey.trim());
     if (raw.byteLength !== KEY_BYTES) {
       throw new Error(
-        "credentialEncryptionKey must be a base64-encoded 32-byte key",
+        "credentials.encryptionKey must be a base64-encoded 32-byte key",
       );
     }
     this.key = crypto.subtle.importKey(