@zackbart/connecta 0.7.0 → 0.7.3

package/src/connectors/remote-mcp.ts

@@ -1,8 +1,13 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type {
+  FetchLike,
+  Transport,
+} from "@modelcontextprotocol/sdk/shared/transport.js";
+import { ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
 import { CfWorkerJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/cfworker";
+import { z } from "zod";
 import { KvOAuthProvider } from "../auth/downstream-oauth.js";
 import { ConnectorCallError } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
@@ -18,6 +23,8 @@ export type RemoteMcpAuth =
   | { type: "headers"; headers: Record<string, string> }
   | { type: "oauth" };
 
+export type RemoteMcpRedirectPolicy = "none" | "same-origin";
+
 export interface RemoteMcpOptions {
   url: string;
   /** Human-readable display name; the connector id remains the address prefix. */
@@ -37,6 +44,14 @@ export interface RemoteMcpOptions {
    */
   usageGuide?: string;
   auth?: RemoteMcpAuth;
+  /**
+   * Downstream HTTP redirect policy. Defaults to `"none"`: every redirect is
+   * rejected. `"same-origin"` follows at most five redirects while preserving
+   * standard 301/302/303/307/308 method semantics. Cross-origin redirects and
+   * HTTPS downgrades are always refused, so credentials never cross the
+   * configured request's origin.
+   */
+  redirects?: RemoteMcpRedirectPolicy;
   /**
    * Refuse to connect to a non-`https://` `url` at construction (default
    * false). Loopback hosts (`localhost`, `127.0.0.1`, `[::1]`) are always
@@ -102,27 +117,33 @@ const MAX_TOOLS = 100_000;
  * is a definite loop, two consecutive pages that add no new tools are a server
  * going nowhere, and MAX_TOOLS caps what any of it can accumulate. This exists
  * only so the loop is finite even if a downstream somehow satisfies all three
- * forever, because the caller's probe deadline abandons the *caller*, not the
- * loop. Set high enough that no honest server reaches it.
+ * forever on a path with no discovery deadline. Set high enough that no honest
+ * server reaches it.
  */
 const MAX_TOOL_PAGES = 10_000;
 
 /** One entry of the SDK's `tools/list` result, before it becomes a ToolDef. */
 type ListedTool = Awaited<ReturnType<Client["listTools"]>>["tools"][number];
 
+/**
+ * Compatibility concession for hand-rolled servers that serialize
+ * end-of-pagination as `null`. Only the cursor is widened; every tool and every
+ * other result field still passes through the SDK's pinned schema.
+ */
+const CompatibleListToolsResultSchema = ListToolsResultSchema.extend({
+  nextCursor: z.string().nullable().optional(),
+});
+
 /**
  * Re-prime an SDK client's tool-metadata cache from the *full* walked catalog.
  *
- * `Client.listTools()` ends by calling its private `cacheToolMetadata`, which
- * **clears** the output-schema validators and the task-support sets before
- * repopulating them from the page it just received. Call it once per page —
- * which walking the chain necessarily does — and the request-scoped client is
- * left holding metadata for the *last* page alone. `callTool` then finds no
- * validator for every earlier-page tool and silently skips both the "declared
- * an outputSchema but returned no structuredContent" check and the
- * structured-content validation, and finds no task requirement so a
- * required-task tool is dispatched as a plain `tools/call`. Enforcement would
- * depend on which page a tool happened to land on, which is not enforcement.
+ * The SDK's `Client.listTools()` caches one page at a time and **clears** the
+ * output-schema validators and task-support sets before each replacement.
+ * This walk uses `Client.request()` so it can make the narrow null-cursor
+ * compatibility concession above, then primes the metadata exactly once from
+ * the complete chain. Otherwise `callTool` would find no validator or task
+ * requirement for earlier-page tools and enforcement would depend on where a
+ * tool happened to land, which is not enforcement.
  *
  * So hand the whole aggregated list back deliberately, once, at the end. The
  * SDK types the method `private`, hence the cast; the SDK version is pinned
@@ -141,9 +162,9 @@ function primeToolMetadata(client: Client, tools: ListedTool[]): void {
 }
 
 /**
- * True for a result-parse failure caused by the page's `nextCursor` itself —
- * in practice `nextCursor: null`, a very common JSON idiom for "no more pages"
- * that the MCP schema does not accept (the chain ends on an *absent* cursor).
+ * True for a result-parse failure caused by the page's `nextCursor` itself.
+ * `null` is accepted deliberately; other non-string values remain a named
+ * downstream nonconformance instead of surfacing as a raw validation dump.
  * Duck-typed rather than `instanceof ZodError`: the SDK may parse with its own
  * zod instance, and cross-instance `instanceof` is a coin flip.
  */
@@ -208,6 +229,127 @@ function isLoopbackHost(hostname: string): boolean {
   );
 }
 
+export const MAX_REMOTE_REDIRECT_HOPS = 5;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const BODY_HEADERS = [
+  "content-encoding",
+  "content-language",
+  "content-length",
+  "content-location",
+  "content-type",
+  "transfer-encoding",
+];
+
+export class RemoteMcpRedirectError extends ConnectorCallError {
+  constructor(connectorId: string, reason: string) {
+    super(
+      "connector_call_failed",
+      `Connector "${connectorId}" redirect policy rejected the downstream response: ${reason}.`,
+    );
+    this.name = "RemoteMcpRedirectError";
+  }
+}
+
+function redirectedInit(init: RequestInit, status: number): RequestInit {
+  const method = (init.method ?? "GET").toUpperCase();
+  const becomesGet =
+    (status === 303 && method !== "GET" && method !== "HEAD") ||
+    ((status === 301 || status === 302) && method === "POST");
+  if (!becomesGet) return init;
+  const headers = new Headers(init.headers);
+  for (const name of BODY_HEADERS) headers.delete(name);
+  return { ...init, method: "GET", body: undefined, headers };
+}
+
+/**
+ * Wrap fetch with explicit, bounded redirect handling.
+ *
+ * The starting URL of each fetch call is trusted by its caller (the configured
+ * MCP endpoint, or an OAuth URL discovered by the pinned SDK). Only Location
+ * values are policy-controlled here. No rejected target is ever fetched, so
+ * arbitrary static header names receive the same protection as Authorization.
+ */
+export function redirectSafeFetch(
+  connectorId: string,
+  policy: RemoteMcpRedirectPolicy = "none",
+  baseFetch: FetchLike = fetch,
+): FetchLike {
+  return async (input, initialInit = {}) => {
+    let current = new URL(input);
+    let init = initialInit;
+    const seen = new Set<string>([current.href]);
+    let hops = 0;
+
+    while (true) {
+      const response = await baseFetch(current, {
+        ...init,
+        redirect: "manual",
+      });
+      if (!REDIRECT_STATUSES.has(response.status)) return response;
+
+      const location = response.headers.get("location");
+      await response.body?.cancel().catch(() => {});
+      if (!location) {
+        throw new RemoteMcpRedirectError(
+          connectorId,
+          `HTTP ${response.status} carried no Location header`,
+        );
+      }
+      if (policy === "none") {
+        throw new RemoteMcpRedirectError(
+          connectorId,
+          `HTTP ${response.status} redirects are disabled`,
+        );
+      }
+      if (hops >= MAX_REMOTE_REDIRECT_HOPS) {
+        throw new RemoteMcpRedirectError(
+          connectorId,
+          `the redirect chain exceeded ${MAX_REMOTE_REDIRECT_HOPS} hops`,
+        );
+      }
+
+      let next: URL;
+      try {
+        next = new URL(location, current);
+      } catch {
+        throw new RemoteMcpRedirectError(
+          connectorId,
+          `HTTP ${response.status} carried an invalid Location header`,
+        );
+      }
+      if (current.protocol === "https:" && next.protocol !== "https:") {
+        throw new RemoteMcpRedirectError(
+          connectorId,
+          "an HTTPS-to-HTTP downgrade is not allowed",
+        );
+      }
+      if (next.origin !== current.origin) {
+        throw new RemoteMcpRedirectError(
+          connectorId,
+          "a cross-origin redirect is not allowed",
+        );
+      }
+      if (next.username || next.password) {
+        throw new RemoteMcpRedirectError(
+          connectorId,
+          "a redirect target containing URL credentials is not allowed",
+        );
+      }
+      if (seen.has(next.href)) {
+        throw new RemoteMcpRedirectError(
+          connectorId,
+          "the redirect chain loops",
+        );
+      }
+
+      seen.add(next.href);
+      hops++;
+      init = redirectedInit(init, response.status);
+      current = next;
+    }
+  };
+}
+
 interface ConnectionState {
   client: Client | null;
   transport: Transport | null;
@@ -238,6 +380,9 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
   // transport, response bodies, AbortSignals, or connection promise reachable
   // from the isolate singleton. Those are request-bound in Cloudflare Workers.
   const states = new WeakMap<object, ConnectionState>();
+  // Closing is terminal even after `states.delete`: a late or future lookup
+  // must not recreate an ownerless connection under the ended scope.
+  const closedScopes = new WeakSet<object>();
   const isOauth = opts.auth?.type === "oauth";
   const logger = opts.logger ?? console;
 
@@ -273,22 +418,33 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     new Error(`Connector "${id}" scope ended during connection.`);
 
   /**
-   * One `tools/list` request. The only thing wrapped here is the diagnosis of a
-   * `nextCursor` the MCP result schema refuses — overwhelmingly `null`, which
-   * plenty of servers use to mean "no more pages" but the spec spells as an
-   * *absent* cursor. The SDK surfaces that as a raw validation dump about a
-   * field the operator never sees; say which server broke which rule instead.
-   * Accepting `null` as end-of-chain outright is issue #99.
+   * One `tools/list` request. The SDK schema is retained wholesale except for
+   * accepting `null` as the common, unambiguous end-of-chain spelling. Other
+   * cursor shapes still get a useful connector-level diagnosis.
    */
-  const listPage = async (client: Client, cursor: string | undefined) => {
+  const listPage = async (
+    client: Client,
+    cursor: string | undefined,
+    ctx: ConnectorContext,
+  ) => {
     try {
-      return await client.listTools(
-        cursor === undefined ? undefined : { cursor },
+      return await client.request(
+        {
+          method: "tools/list",
+          ...(cursor === undefined ? {} : { params: { cursor } }),
+        },
+        CompatibleListToolsResultSchema,
+        ctx.timeoutMs || ctx.signal
+          ? {
+              ...(ctx.timeoutMs ? { timeout: ctx.timeoutMs } : {}),
+              ...(ctx.signal ? { signal: ctx.signal } : {}),
+            }
+          : undefined,
       );
     } catch (err) {
       if (!isCursorShapeError(err)) throw err;
       throw new Error(
-        `Connector "${id}" returned a tools/list page whose nextCursor is neither a string nor absent (a null cursor is the usual culprit) — MCP ends pagination on an absent nextCursor, so this catalog cannot be walked.`,
+        `Connector "${id}" returned a tools/list page whose nextCursor is neither a string, null, nor absent — this catalog cannot be walked.`,
         { cause: err },
       );
     }
@@ -296,6 +452,7 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
 
   const stateFor = (ctx: ConnectorContext): ConnectionState => {
     const scope = ctx.requestScope ?? ctx;
+    if (closedScopes.has(scope)) throw scopeEndedError();
     let state = states.get(scope);
     if (!state) {
       state = {
@@ -324,30 +481,27 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     return state.provider;
   };
 
-  // NOTE: StreamableHTTPClientTransport speaks over fetch, which transparently
-  // follows 3xx redirects. A malicious or compromised downstream MCP could
-  // redirect to an internal address (e.g. http://169.254.169.254/…) and fetch
-  // would re-issue the request — potentially carrying static auth headers. The
-  // scheme check above only guards the first hop; a fully robust guard (manual
-  // redirect handling + per-hop re-validation + stripping auth headers cross-
-  // origin) lives in the SDK transport and is deferred to a future non-patch
-  // release rather than reimplemented here.
   const buildTransport = (
     ctx: ConnectorContext,
     state: ConnectionState,
   ): Transport => {
     if (opts._transportFactory) return opts._transportFactory(ctx);
     const url = new URL(opts.url);
+    const guardedFetch = redirectSafeFetch(id, opts.redirects);
     if (opts.auth?.type === "oauth") {
       return new StreamableHTTPClientTransport(url, {
         authProvider: getProvider(ctx, state),
+        fetch: guardedFetch,
       });
     }
     const headers =
       opts.auth?.type === "headers" ? opts.auth.headers : undefined;
     return new StreamableHTTPClientTransport(
       url,
-      headers ? { requestInit: { headers } } : undefined,
+      {
+        ...(headers ? { requestInit: { headers } } : {}),
+        fetch: guardedFetch,
+      },
     );
   };
 
@@ -364,6 +518,14 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
     ctx: ConnectorContext,
     state: ConnectionState,
   ): Promise<void> => {
+    // A 401 after connect is a verdict for the whole request scope, not merely
+    // for the one call that observed it. Do not let the still-cached client make
+    // a later status or call in the same scope report healthy.
+    if (state.authRequired) {
+      throw authRequiredError(
+        new UnauthorizedError("Downstream authorization is no longer valid."),
+      );
+    }
     // Cross-isolate force re-auth: another isolate bumped the KV generation and
     // wiped credentials. This request's cached client still speaks the old
     // token — drop it so the next connect runs against current state.
@@ -495,64 +657,76 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
       /** Consecutive pages that advertised a successor but added nothing. */
       let barren = 0;
       let complete = false;
-      for (let page = 0; page < MAX_TOOL_PAGES; page++) {
-        // The scope can end between pages (probe timeout, teardown). Stop
-        // rather than keep paging into a transport that is being closed.
-        if (state.closed) throw scopeEndedError();
-        // Page one sends no params at all, so a non-paginated server sees
-        // exactly the request it saw before pagination existed.
-        const res = await listPage(client, cursor);
-        let added = 0;
-        for (const t of res.tools) {
-          // First page wins. An unstable cursor can serve the same tool on two
-          // pages — a failure mode that did not exist while only page one was
-          // read — and a duplicate would inflate `toolCount`, double the tool's
-          // `search_tools` row, and churn the registry's catalog-changed
-          // comparison into a persistence write on every refresh.
-          if (names.has(t.name)) continue;
-          names.add(t.name);
-          listed.push(t);
-          added++;
-        }
-        // Pagination ends when `nextCursor` is ABSENT — not when it is falsy.
-        // An empty string is a legal cursor and means "keep going"; `if
-        // (!next)` here would silently truncate that server's catalog.
-        const next = res.nextCursor;
-        if (typeof next !== "string") {
-          complete = true;
-          break;
-        }
-        // A page that adds nothing and still claims a successor made no
-        // progress. Allow exactly one: the widespread idiom is to advertise a
-        // cursor whenever a page came back full and then serve one empty page
-        // to terminate, and that server is conformant. Two in a row is a
-        // downstream going nowhere, and this kills a "fresh cursor forever, no
-        // tools" adversary in a couple of round trips instead of thousands.
-        if (added === 0 && ++barren > 1) {
-          throw new Error(
-            `Connector "${id}" returned two consecutive tools/list pages that added no tools and still advertised another — the catalog is not advancing.`,
-          );
-        }
-        if (added > 0) barren = 0;
-        // A cursor handed back a second time is not a slow server, it is a
-        // loop. Fail now rather than walking it until a ceiling notices.
-        if (spent.has(next)) {
-          throw new Error(
-            `Connector "${id}" handed back a tools/list cursor it had already issued — the pagination chain loops.`,
-          );
+      try {
+        for (let page = 0; page < MAX_TOOL_PAGES; page++) {
+          // The scope can end between pages (probe timeout, teardown). Stop
+          // rather than keep paging into a transport that is being closed.
+          if (state.closed) throw scopeEndedError();
+          // A discovery deadline uses the same signal for the whole chain.
+          // Check it before issuing each page as well as passing it to the
+          // in-flight SDK request, so expiry never starts one more round trip.
+          if (ctx.signal?.aborted) {
+            throw ctx.signal.reason instanceof Error
+              ? ctx.signal.reason
+              : new Error(`Connector "${id}" catalog deadline expired.`);
+          }
+          // Page one sends no params at all, so a non-paginated server sees
+          // exactly the request it saw before pagination existed.
+          const res = await listPage(client, cursor, ctx);
+          let added = 0;
+          for (const t of res.tools) {
+            // First page wins. An unstable cursor can serve the same tool on
+            // two pages — a duplicate would inflate `toolCount`, double the
+            // `search_tools` row, and churn catalog persistence.
+            if (names.has(t.name)) continue;
+            names.add(t.name);
+            listed.push(t);
+            added++;
+          }
+          // Pagination ends when `nextCursor` is absent or null — never merely
+          // falsy. Empty string is present and means "keep going".
+          const next = res.nextCursor;
+          if (next === undefined || next === null) {
+            complete = true;
+            break;
+          }
+          // A page that adds nothing and still claims a successor made no
+          // progress. Allow exactly one: the widespread idiom is to advertise
+          // a cursor whenever a page came back full and then serve one empty
+          // page to terminate. Two in a row is a downstream going nowhere.
+          if (added === 0 && ++barren > 1) {
+            throw new Error(
+              `Connector "${id}" returned two consecutive tools/list pages that added no tools and still advertised another — the catalog is not advancing.`,
+            );
+          }
+          if (added > 0) barren = 0;
+          // A cursor handed back a second time is a loop, not a slow server.
+          if (spent.has(next)) {
+            throw new Error(
+              `Connector "${id}" handed back a tools/list cursor it had already issued — the pagination chain loops.`,
+            );
+          }
+          // Checked here rather than on arrival: this bounds what a *walk* may
+          // accumulate; a one-page server was always free to send its page.
+          if (listed.length > MAX_TOOLS) {
+            throw new Error(
+              `Connector "${id}" advertised further tools/list pages past ${listed.length} tools, over the ${MAX_TOOLS}-tool ceiling one catalog refresh will collect.`,
+            );
+          }
+          // Opaque by contract: handed straight back, never parsed, rewritten,
+          // or persisted.
+          spent.add(next);
+          cursor = next;
         }
-        // Checked here rather than on arrival: this bounds what a *walk* may
-        // accumulate, and a server that answers in one page was always free to
-        // send whatever it sends.
-        if (listed.length > MAX_TOOLS) {
-          throw new Error(
-            `Connector "${id}" advertised further tools/list pages past ${listed.length} tools, over the ${MAX_TOOLS}-tool ceiling one catalog refresh will collect.`,
-          );
+      } catch (err) {
+        // A grant can be revoked after connect and after any earlier page.
+        // Classify that exactly like connect-time and call-time authorization
+        // failures, and latch it for the rest of this request scope.
+        if (err instanceof UnauthorizedError) {
+          state.authRequired = true;
+          throw authRequiredError(err);
         }
-        // Opaque by contract: handed straight back, never parsed, rewritten,
-        // or persisted.
-        spent.add(next);
-        cursor = next;
+        throw err;
       }
       // Fail the refresh outright. Returning what we have would publish a
       // partial catalog that looks complete; throwing lets the registry keep
@@ -603,11 +777,13 @@ export function remoteMcp(id: string, opts: RemoteMcpOptions): Connector {
 
     async closeScope(ctx) {
       const scope = ctx.requestScope ?? ctx;
+      // Tombstone before any lookup or await. This also makes close-before-use
+      // terminal rather than allowing the scope to spring into existence later.
+      closedScopes.add(scope);
       const state = states.get(scope);
       if (!state) return;
 
-      // Delete before awaiting: a duplicate teardown is a no-op, and no later
-      // lookup can reuse the state while its client is closing.
+      // Delete before awaiting: a duplicate teardown is a no-op.
       states.delete(scope);
       state.closed = true;
       const client = state.client;

package/src/credential-health.ts

@@ -17,6 +17,7 @@
 
 import {
   credentialTestRule,
+  STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR,
   storedCredentialShape,
 } from "./credentials.js";
 import type { CredentialVault } from "./credentials.js";
@@ -333,8 +334,8 @@ export interface CredentialCheckOptions {
   /** Restrict the sweep to these connector ids. Default: every connector. */
   ids?: string[];
   /**
-   * Internal scope identity supplied by an existing owner. When omitted, the
-   * check creates and ends its own probe scope.
+   * @deprecated Ignored. Credential checks always create and close their own
+   * probe scope; no core path supplies an existing request scope.
    */
   requestScope?: object;
 }
@@ -586,12 +587,7 @@ export class CredentialHealthChecker {
         ...(await this.recordOrNothing(connectorId)),
       };
     }
-    const run = this.runCheck(
-      connector,
-      baseUrl,
-      opts.force ?? false,
-      opts.requestScope,
-    );
+    const run = this.runCheck(connector, baseUrl, opts.force ?? false);
     this.inFlight.set(connectorId, run);
     try {
       return await run;
@@ -611,7 +607,6 @@ export class CredentialHealthChecker {
     connector: Connector,
     baseUrl: string,
     force: boolean,
-    requestScope?: object,
   ): Promise<CredentialCheckResult> {
     const connectorId = connector.id;
     const started = Date.now();
@@ -633,7 +628,7 @@ export class CredentialHealthChecker {
       }
       const shape = storedCredentialShape(connector.credential, values);
       if (shape.state === "mismatch") {
-        // Drift is a persistent operator-error state, not an event: left
+        // Drift is a persistent operator-reconfiguration state, not an event:
         // 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).
@@ -646,7 +641,7 @@ export class CredentialHealthChecker {
           const current = await this.store.get(connectorId);
           if (
             current &&
-            current.state === "error" &&
+            current.state === "auth_required" &&
             current.message === shape.message &&
             Date.now() - Date.parse(current.checkedAt) < this.intervalMs
           ) {
@@ -654,7 +649,9 @@ export class CredentialHealthChecker {
           }
         }
         return this.settle(connectorId, started, generation, {
-          state: "error",
+          // Unlike a failed check, this is a completed static classification:
+          // the current declaration cannot consume what the vault holds.
+          state: "auth_required",
           checkedAt: new Date().toISOString(),
           message: shape.message,
         });
@@ -671,8 +668,9 @@ export class CredentialHealthChecker {
         return { connectorId, skipped: "fresh", record: current };
       }
     }
-    const ownsScope = requestScope === undefined;
-    const scope = requestScope ?? {};
+    // Credential checks are always probe owners. No caller may lend them an
+    // ordinary request scope and thereby suppress the teardown below.
+    const scope = {};
     const ctx = this.deps.contextFor(connectorId, baseUrl, scope);
     try {
       if (credentialReadError) {
@@ -713,7 +711,7 @@ export class CredentialHealthChecker {
         });
       }
     } finally {
-      if (ownsScope) await closeConnectorScope(connector, ctx);
+      await closeConnectorScope(connector, ctx);
     }
   }
 
@@ -797,9 +795,12 @@ export class CredentialHealthChecker {
  *    blip. Error verdicts stay visible in `credentialCheck` (an operator wants
  *    to know checks are failing) but the status keeps coming from observed real
  *    calls, which is evidence.
- * 2. **A successful real call retires the verdict.** Traffic beats a background
- *    probe, so a `lastSuccessAt` at or after `checkedAt` means the credential
- *    demonstrably works whatever the check concluded. The next check re-decides.
+ * 2. **A successful real call retires the verdict, except static shape drift.**
+ *    Traffic beats a background probe, so a `lastSuccessAt` at or after
+ *    `checkedAt` normally means the credential demonstrably works. Stored-shape
+ *    drift is different: a credential-independent tool can succeed without
+ *    making a missing declared field appear, so only replacement/removal clears
+ *    that verdict.
  *
  * `auth_required` deliberately outranks an observed real-call *failure*: both
  * say something is wrong, and only one of them carries the URL that fixes it.
@@ -810,6 +811,7 @@ export function credentialVerdictApplies(
   lastSuccessAt: string | undefined,
 ): boolean {
   if (!record || record.state !== "auth_required") return false;
+  if (record.message === STORED_CREDENTIAL_SHAPE_MISMATCH_ERROR) return true;
   if (!lastSuccessAt) return true;
   const success = Date.parse(lastSuccessAt);
   return Number.isNaN(success) || success < Date.parse(record.checkedAt);