@bevel-software/platform-core-backend 0.33.0 → 0.35.0

package/src/modules/secrets-vault/__tests__/oauth-return-to.route.test.ts

@@ -2,11 +2,11 @@ import type { Server as HttpServer } from 'node:http';
 import { createHmac } from 'node:crypto';
 import express from 'express';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import {
-  createSecretsVaultRoutes,
-  createSecretsVaultPublicRoutes,
-  isSafeReturnPath,
-} from '../secrets-vault.routes.js';
+import { createSecretsVaultRoutes, createSecretsVaultPublicRoutes, SecretOAuthError } from '../index.js';
+// The one deliberate white-box reach: the open-redirect predicate is pinned as
+// a unit table as well as end-to-end (see below), and it is on no entry because
+// nothing outside the routes should decide what a safe return path is.
+import { isSafeReturnPath } from '../secrets-vault.routes.js';
 
 /**
  * OAUTH `returnTo`: a sign-in started from a page other than /connect must land
@@ -54,6 +54,11 @@ const MANUALS = [
 
 const toolManualService = {
   listAccessible: async () => MANUALS,
+  // The sign-in start reads the declaration from the file; here it reads as the catalog does.
+  liveDeclaration: async (_who: string, slug: string, varName: string) => {
+    const manual = MANUALS.find((m) => m.slug === slug);
+    return manual ? { manual, variable: manual.variables.find((v) => v.name === varName) } : null;
+  },
 } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
 
 const accessControl = {
@@ -254,7 +259,35 @@ describe('GET /api/secrets/oauth/callback — where the browser lands', () => {
     const state = signState({ u: 'u1', i: 'secret-1', n: 'nonce', r: RETURN_TO });
     const location = await callback(base, state);
     expect(location.startsWith(`${FRONTEND}${RETURN_TO}#error=`)).toBe(true);
-    // The user-facing message is generic — provider detail stays in the log.
+    // A failure that is not the provider's word stays generic: only the
+    // vault's own error carries a reason that was scrubbed for the page.
+    expect(decodeURIComponent(location.split('#error=')[1])).toBe(
+      'Authorization failed. Check the provider configuration and try again.',
+    );
+  });
+
+  it("carries the provider's error code and Hexis's sentence to the page when the exchange was refused", async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    const refusal =
+      'Token endpoint returned HTTP 400 (invalid_client). The client id or client secret this sign-in uses is not accepted by the provider. The tool owner should check the declared client id and set the client secret again.';
+    completeOAuth.mockImplementation(async () => {
+      throw new SecretOAuthError(refusal, 400);
+    });
+    const base = await baseUrl();
+    const state = signState({ u: 'u1', i: 'secret-1', n: 'nonce', r: RETURN_TO });
+    const location = await callback(base, state);
+    expect(decodeURIComponent(location.split('#error=')[1])).toBe(`Authorization failed. ${refusal}`);
+  });
+
+  it("keeps the generic message for the vault's own TRANSPORT errors, which quote what fetch said", async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    completeOAuth.mockImplementation(async () => {
+      // No provider status: not a provider's word, and never scrubbed.
+      throw new SecretOAuthError('Token endpoint request failed: fetch failed https://user:pw@provider.example/token');
+    });
+    const base = await baseUrl();
+    const state = signState({ u: 'u1', i: 'secret-1', n: 'nonce', r: RETURN_TO });
+    const location = await callback(base, state);
     expect(decodeURIComponent(location.split('#error=')[1])).toBe(
       'Authorization failed. Check the provider configuration and try again.',
     );

package/src/modules/secrets-vault/db-secrets-vault.service.ts

@@ -1,4 +1,5 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('vault');
@@ -7,6 +8,8 @@ import type { Database } from '../database/index.js';
 import { secrets } from '../database/index.js';
 import { TokenCrypto } from '../../shared/token-crypto.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
+import { readCapped } from '../../shared/read-capped.js';
+import { standardTokenErrorCode } from '../../shared/oauth-token-error.js';
 import {
   type ISecretsVaultService,
   type SecretSummary,
@@ -16,6 +19,7 @@ import {
   type PutSharedStaticSecretInput,
   type CreateOAuthSecretInput,
   type OAuthProviderConfig,
+  type DeclaredOAuthProvider,
   type VariableScopeResolver,
   type NamespaceSecretCount,
   isKeyInNamespace,
@@ -32,6 +36,79 @@ const MAX_VALUE_LEN = 100_000;
 const REFRESH_SKEW_MS = 60_000;
 /** Upper bound on a token-endpoint round-trip, so a hung provider can't block callers. */
 const TOKEN_REQUEST_TIMEOUT_MS = 10_000;
+/** How much of a refusing token endpoint's body is read for its error code: an OAuth error object, never a whole error page. */
+const TOKEN_ERROR_BODY_MAX_BYTES = 2048;
+// Hexis's own sentences for a refused token request: what to change, in our
+// words, never the provider's.
+const HINT_CLIENT =
+  'The client id or client secret this sign-in uses is not accepted by the provider. The tool owner should check the declared client id and set the client secret again.';
+const HINT_GRANT =
+  'The provider refused the grant: for a sign-in, a redirect URL mismatch or an expired or reused authorization code; for a refresh, a refresh token that has expired or been revoked. Sign in again.';
+const HINT_SCOPE =
+  "The provider refused the scopes this sign-in asks for. The tool owner should check the declared scopes against the provider's app.";
+const HINT_UNAUTHORIZED =
+  "The provider does not allow this client to use this grant. The tool owner should check the provider's app settings.";
+const HINT_REQUEST =
+  'The provider found the token request malformed. The tool owner should check the declared endpoints and parameters.';
+const HINT_PROVIDER = 'The provider could not serve the token request. Try again later.';
+
+/**
+ * Hexis's sentence for each error code a refusing token endpoint may answer:
+ * the standard ones (`shared/oauth-token-error.ts` is the one list of those,
+ * read here and by the OIDC configuration check) in `error`, and the ones
+ * HubSpot's token endpoint answers in its `status` field. Only a code from
+ * those lists is ever taken, exactly, so no other string a provider puts in a
+ * field — a secret, a secret with a suffix, free text — can reach a message.
+ * Nothing else of the body is ever taken: no description, no message, no first
+ * line. That is why a message built here needs no scrubbing, cutting or
+ * decoding, and why every spelling a secret could reach a log in (escaped,
+ * encoded, cut) stays inexpressible. A standard code without a sentence here
+ * (`access_denied`) is named and left unexplained.
+ */
+const TOKEN_ERROR_HINTS: ReadonlyMap<string, string> = new Map([
+  ['invalid_request', HINT_REQUEST],
+  ['invalid_client', HINT_CLIENT],
+  ['invalid_grant', HINT_GRANT],
+  ['unauthorized_client', HINT_UNAUTHORIZED],
+  ['unsupported_grant_type', HINT_UNAUTHORIZED],
+  ['invalid_scope', HINT_SCOPE],
+  ['server_error', HINT_PROVIDER],
+  ['temporarily_unavailable', HINT_PROVIDER],
+  ['BAD_CLIENT_ID', HINT_CLIENT],
+  ['BAD_CLIENT_SECRET', HINT_CLIENT],
+  ['BAD_AUTH_CODE', HINT_GRANT],
+  ['BAD_REDIRECT_URI', HINT_GRANT],
+]);
+
+/** The codes HubSpot's token endpoint answers in `status` instead of a standard `error`. */
+const HUBSPOT_STATUS_CODES: ReadonlySet<string> = new Set(['BAD_CLIENT_ID', 'BAD_CLIENT_SECRET', 'BAD_AUTH_CODE', 'BAD_REDIRECT_URI']);
+
+/**
+ * The known error code a refusing token endpoint answered, or null: a standard
+ * `error` (RFC 6749 §5.2), else HubSpot's own `status`, when it is exactly one
+ * of the codes known. Without even the code, a bare "HTTP 400" cannot tell a
+ * client the provider does not accept from a refused grant.
+ */
+export function tokenEndpointErrorCode(bodyText: string): string | null {
+  const standard = standardTokenErrorCode(bodyText);
+  if (standard !== null) return standard;
+  let json: unknown;
+  try {
+    json = JSON.parse(bodyText);
+  } catch {
+    return null;
+  }
+  if (!json || typeof json !== 'object' || Array.isArray(json)) return null;
+  const { status } = json as Record<string, unknown>;
+  return typeof status === 'string' && HUBSPOT_STATUS_CODES.has(status) ? status : null;
+}
+
+/** The refusal in one message: the status, the known code when there is one, and Hexis's sentence for it. */
+export function describeTokenEndpointRefusal(status: number, code: string | null): string {
+  const base = `Token endpoint returned HTTP ${status}`;
+  const hint = code === null ? undefined : TOKEN_ERROR_HINTS.get(code);
+  return hint ? `${base} (${code}). ${hint}` : base;
+}
 
 /**
  * How a row is stored, or `null` when there is no row — the column is a plain
@@ -487,8 +564,9 @@ export class DbSecretsVaultService implements ISecretsVaultService {
       throw new InvalidSecretError('clientSecret is required');
     }
     // Validate the provider config the same way createOAuth does (SSRF-safe https
-    // URLs). Store the client secret AND the provider meta together on the shared
-    // row so a later `.tool` edit can't redirect the secret to another endpoint.
+    // URLs) and store it beside the secret as a record of what was saved — what
+    // `statusFor` and the setup surfaces read. A declared sign-in does not run
+    // from it: `beginToolOAuthByKey` is handed the declaration as it reads now.
     const provider = this.requireProvider({ ...input.provider, clientSecret: input.clientSecret });
     const blob: OAuthBlob = { clientSecret: provider.clientSecret };
     const valueEncrypted = this.crypto().encrypt(JSON.stringify(blob));
@@ -510,11 +588,15 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     redirectUri: string;
     state: string;
     scopes?: string[];
+    provider?: DeclaredOAuthProvider;
   }): Promise<{ id: string; url: string }> {
     const userId = this.requireUserId(input.userId);
     const key = this.requireKey(input.key);
-    // The shared row holds the owner-set client secret + the provider meta it was
-    // set for. Both are read from HERE, never from the live `.tool`.
+    // The shared row holds the owner-set client secret. For a client the
+    // platform registered itself it also holds the provider configuration, the
+    // only description of that client there is; for a declared sign-in the
+    // configuration it holds is a record of the save, and `input.provider` (the
+    // tool file as it reads now) is what the sign-in follows.
     const [shared] = await this.db
       .select()
       .from(secrets)
@@ -524,11 +606,43 @@ export class DbSecretsVaultService implements ISecretsVaultService {
       throw new SecretOAuthError("This tool's owner hasn't finished setting this up");
     }
     const sharedBlob = this.readBlob(shared.valueEncrypted);
-    const meta = this.readMeta(shared.oauthMeta);
-    // A missing secret is "not set up yet" ONLY for confidential clients — a
-    // dynamically-registered PUBLIC client (PKCE-only) never has one.
-    if (!sharedBlob.clientSecret && !meta.publicClient) {
-      throw new SecretOAuthError("This tool's owner hasn't finished setting this up");
+    let meta: OAuthProviderConfig;
+    let oauthMeta: typeof shared.oauthMeta;
+    if (input.provider) {
+      // A declared client is confidential: without the owner's secret there is
+      // nothing to sign in with, whatever the stored row says of itself.
+      if (!sharedBlob.clientSecret) {
+        throw new SecretOAuthError("This tool's owner hasn't finished setting this up");
+      }
+      // The save's own validation (https, no private or local address), BEFORE
+      // the caller's row is written or a URL built: a declaration that fails it
+      // sends nothing anywhere.
+      meta = this.requireProvider({ ...input.provider, publicClient: false });
+      oauthMeta = this.publicProviderMeta(meta);
+      // A MOVED PROPERTY, decided on the ticket (OAuth-Sign-In-Follows-The-Live-
+      // Declaration, 2026-10-27): the secret used to be bound to the token
+      // endpoint pinned at its save, so a later file edit could not send it
+      // anywhere else; now it goes where the file says at each start, so a
+      // writer of the tool file can move it (to an https, public host — the
+      // validation above still holds). Nothing refuses that; this line is the
+      // trail an operator reads when a secret went somewhere new.
+      const recorded = (shared.oauthMeta ?? {}) as { tokenUrl?: unknown };
+      if (typeof recorded.tokenUrl === 'string' && recorded.tokenUrl !== meta.tokenUrl) {
+        // Origins only: a path or query is the file's to say, not the log's.
+        const origin = (u: string) => (URL.canParse(u) ? new URL(u).origin : '(unparseable)');
+        log.warn(`sign-in on ${key}: the declared token endpoint differs from the one recorded when the client secret was saved`, {
+          savedOrigin: origin(recorded.tokenUrl),
+          declaredOrigin: origin(meta.tokenUrl),
+        });
+      }
+    } else {
+      meta = this.readMeta(shared.oauthMeta);
+      oauthMeta = shared.oauthMeta;
+      // A missing secret is "not set up yet" ONLY for confidential clients — a
+      // dynamically-registered PUBLIC client (PKCE-only) never has one.
+      if (!sharedBlob.clientSecret && !meta.publicClient) {
+        throw new SecretOAuthError("This tool's owner hasn't finished setting this up");
+      }
     }
 
     // Carry forward any tokens the caller already holds so re-entering the flow
@@ -543,12 +657,12 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     // encKey must degrade to "start fresh", not crash the recovery flow — and (b)
     // they were minted under the SAME provider config we're about to (re)write, or
     // a refresh_token for a stale client id/secret would silently fail once carried
-    // into this row after an owner rotates the shared secret.
+    // into this row after an owner rotates the shared secret or edits the
+    // declaration. Compared as values, not as serialised text: the stored side
+    // has been through jsonb, which does not keep key order, and a declared
+    // sign-in's side is built here.
     let existingTokens: OAuthTokenSet | undefined;
-    if (
-      existingUserRow?.kind === 'oauth' &&
-      JSON.stringify(existingUserRow.oauthMeta) === JSON.stringify(shared.oauthMeta)
-    ) {
+    if (existingUserRow?.kind === 'oauth' && isDeepStrictEqual(existingUserRow.oauthMeta, oauthMeta)) {
       try {
         existingTokens = this.readBlob(existingUserRow.valueEncrypted).tokens;
       } catch {
@@ -567,9 +681,13 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     const requestedScopes = input.scopes && input.scopes.length ? input.scopes : meta.scopes;
     const pendingScopes = requestedScopes && requestedScopes.length ? requestedScopes.join(' ') : undefined;
 
-    // Provision (or reset) the caller's own oauth row for this key from the shared
-    // provider meta + secret, preserving any existing tokens. Keyed `<manual>_<VAR>`
-    // so `resolve` (scope 'user') returns the token once sign-in completes.
+    // Provision (or reset) the caller's own oauth row for this key from the provider
+    // configuration this start uses + the shared secret, preserving any existing
+    // tokens. The row records that configuration because `completeOAuth` and every
+    // later refresh of this grant read it from HERE: the exchange goes to the token
+    // endpoint, under the client id, that the consent was given for. Keyed
+    // `<manual>_<VAR>` so `resolve` (scope 'user') returns the token once sign-in
+    // completes.
     const blob: OAuthBlob = {
       clientSecret: sharedBlob.clientSecret,
       tokens: existingTokens,
@@ -579,16 +697,15 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     const valueEncrypted = this.crypto().encrypt(JSON.stringify(blob));
     const [row] = await this.db
       .insert(secrets)
-      .values({ userId, key, kind: 'oauth', label: shared.label, valueEncrypted, oauthMeta: shared.oauthMeta })
+      .values({ userId, key, kind: 'oauth', label: shared.label, valueEncrypted, oauthMeta })
       .onConflictDoUpdate({
         target: [secrets.userId, secrets.key],
-        set: { kind: 'oauth', valueEncrypted, oauthMeta: shared.oauthMeta, updatedAt: new Date() },
+        set: { kind: 'oauth', valueEncrypted, oauthMeta, updatedAt: new Date() },
       })
       .returning();
 
-    // Build the consent URL exactly as beginOAuth does, from the stored meta —
-    // EXCEPT the requested scopes (above). Client id, addresses, and secret
-    // stay owner-pinned.
+    // Build the consent URL exactly as beginOAuth does, from the configuration
+    // this start uses, with the requested scopes chosen above.
     const url = new URL(meta.authorizationUrl);
     url.searchParams.set('response_type', 'code');
     url.searchParams.set('client_id', meta.clientId);
@@ -732,7 +849,18 @@ export class DbSecretsVaultService implements ISecretsVaultService {
         err instanceof SecretOAuthError &&
         (err.providerStatus === 400 || err.providerStatus === 401)
       ) {
-        return this.wipeTokens(row, blob);
+        // The only trace of a sign-in that silently turns into "not connected":
+        // say which one, the provider's reason, and what the guarded wipe did —
+        // a concurrent refresh may have rotated the tokens first, in which case
+        // nothing was wiped and the rotated grant is served.
+        const result = await this.wipeTokens(row, blob);
+        const did = result.wiped
+          ? 'sign-in wiped'
+          : result.outcome === 'refreshed'
+            ? 'the row had been rotated by a concurrent refresh meanwhile; the rotated sign-in is kept'
+            : 'the row had been removed or replaced meanwhile; nothing wiped';
+        log.warn(`refresh refused for "${row.key}", ${did}: ${err.message}`);
+        return result;
       }
       return { outcome: 'transient' };
     }
@@ -794,7 +922,10 @@ export class DbSecretsVaultService implements ISecretsVaultService {
   private async wipeTokens(
     row: typeof secrets.$inferSelect,
     blob: OAuthBlob,
-  ): Promise<{ outcome: 'refreshed'; accessToken: string } | { outcome: 'rejected'; accessToken: null }> {
+  ): Promise<
+    | { outcome: 'refreshed'; accessToken: string; wiped: false }
+    | { outcome: 'rejected'; accessToken: null; wiped: boolean }
+  > {
     const next: OAuthBlob = { clientSecret: blob.clientSecret };
     // Guarded on the ciphertext we read, so a concurrent refresh that
     // already persisted ROTATED tokens can't be wiped by our stale
@@ -807,13 +938,17 @@ export class DbSecretsVaultService implements ISecretsVaultService {
       .where(and(eq(secrets.id, row.id), eq(secrets.valueEncrypted, row.valueEncrypted)))
       .returning({ id: secrets.id });
     if (Array.isArray(wiped) && wiped.length === 0) {
+      // `wiped: false` either way: this write matched nothing, and the caller
+      // reports what it did, not what it set out to do.
       const fresh = await this.currentAccessToken(row.id);
-      return fresh ? { outcome: 'refreshed', accessToken: fresh } : { outcome: 'rejected', accessToken: null };
+      return fresh
+        ? { outcome: 'refreshed', accessToken: fresh, wiped: false }
+        : { outcome: 'rejected', accessToken: null, wiped: false };
     }
     // The sign-in just became not-connected — let credential-validity caches
     // (pooled downstream connections dialed with the dead token) drop it now.
     this.notifyMutation(row.userId);
-    return { outcome: 'rejected', accessToken: null };
+    return { outcome: 'rejected', accessToken: null, wiped: true };
   }
 
   async putSharedOAuthProvider(input: {
@@ -887,7 +1022,15 @@ export class DbSecretsVaultService implements ISecretsVaultService {
       throw new SecretOAuthError(msg);
     }
     if (!res.ok) {
-      throw new SecretOAuthError(`Token endpoint returned HTTP ${res.status}`, res.status);
+      // The provider's error CODE rides in the message: the callback route and
+      // the refresh path log that message, and it is the one line that says
+      // WHY a sign-in failed (a client the provider does not accept, a refused
+      // authorization code). Best effort: the STATUS is the contract (the
+      // refresh path reads 400/401 off it to retire a dead grant), and a body
+      // that fails to read must not turn a definitive refusal into an
+      // unclassified error.
+      const code = tokenEndpointErrorCode(await readCapped(res, TOKEN_ERROR_BODY_MAX_BYTES).catch(() => ''));
+      throw new SecretOAuthError(describeTokenEndpointRefusal(res.status, code), res.status);
     }
     const json = (await res.json()) as Record<string, unknown>;
     const accessToken = typeof json.access_token === 'string' ? json.access_token : '';

package/src/modules/secrets-vault/index.ts

@@ -27,4 +27,4 @@ export {
   DEFAULT_SECRETS_SCOPE,
 } from './secrets-variable-loader.js';
 // Reached by other modules; exported here so they stop importing the files.
-export { scopesCovered } from './secrets-vault.contract.js';
+export { scopesCovered, userSecretGap, type UserSecretGap } from './secrets-vault.contract.js';

package/src/modules/secrets-vault/secrets-vault.contract.ts

@@ -74,6 +74,13 @@ export interface SecretConfigStatus {
   grantedScopes?: string;
 }
 
+/**
+ * A declared sign-in's public provider configuration, as the tool file reads it:
+ * everything but the secret (only the owner's shared row holds it) and the
+ * public-client flag (a declared client is confidential by definition).
+ */
+export type DeclaredOAuthProvider = Omit<OAuthProviderConfig, 'clientSecret' | 'publicClient'>;
+
 /**
  * How a secret is provisioned — mirrors `ToolVariableScope` in the tool-manuals
  * contract, redeclared here to keep the vault free of a tool-manuals import.
@@ -186,8 +193,10 @@ export interface ISecretsVaultService {
   /**
    * Set the confidential client secret + provider config for a tool's OAuth-backed
    * variable, on the SHARED row (`user_id NULL`) for `key`. The provider meta is
-   * stored ALONGSIDE the secret so a later `.tool` edit can't redirect it. Owner-
-   * gated by the route (write access on the `.tool`).
+   * stored ALONGSIDE the secret as a record of the save; a sign-in follows the
+   * declaration as the tool file reads when it starts (`beginToolOAuthByKey`'s
+   * `provider`), not this copy. Owner-gated by the route (write access on the
+   * `.tool`).
    */
   putSharedOAuthClientSecret(input: {
     key: string;
@@ -212,16 +221,26 @@ export interface ISecretsVaultService {
    */
   getSharedOAuthProvider(key: string): Promise<OAuthProviderConfig | null>;
   /**
-   * Provision (if needed) the caller's per-user oauth row for `key` from the SHARED
-   * row's stored provider meta + client secret, then build the consent URL. 409 if
-   * the owner hasn't set the client secret. Returns the provisioned row's id (to
-   * sign into the callback state) and the consent url.
+   * Provision (if needed) the caller's per-user oauth row for `key` and build the
+   * consent URL. 409 if the owner hasn't set the client secret. Returns the
+   * provisioned row's id (to sign into the callback state) and the consent url.
    *
-   * `scopes`, when given, are the permissions to REQUEST on the consent screen —
-   * supplied by the caller from the live tool file so a scope added there takes
-   * effect without the owner re-entering the secret. Only the requested scopes
-   * follow the tool file; the client id, addresses, and secret are still read from
-   * the owner-set shared row. Omitted → the shared row's stored scopes are used.
+   * Where the provider configuration comes from depends on who registered the
+   * client, and each kind of sign-in has exactly one source:
+   *   - `provider` given — a DECLARED sign-in: the client id, endpoints, PKCE,
+   *     resource and authorize params are the declaration as the tool file reads
+   *     now, handed over by the caller. They are validated as the client-secret
+   *     save validates them (https, no private or local address) before anything
+   *     is written or built, and they are what the caller's row records, so the
+   *     token exchange and later refreshes of this grant use the configuration
+   *     the consent was given for. The shared row contributes the client secret
+   *     only, and must hold one.
+   *   - `provider` absent — a client the platform registered itself (dynamic
+   *     client registration): nothing in a file describes it, so the shared
+   *     row's stored configuration is used.
+   *
+   * `scopes`, when given, are the permissions to REQUEST on the consent screen
+   * (the live tool file's); omitted → the provider configuration's own scopes.
    */
   beginToolOAuthByKey(input: {
     userId: string;
@@ -229,6 +248,7 @@ export interface ISecretsVaultService {
     redirectUri: string;
     state: string;
     scopes?: string[];
+    provider?: DeclaredOAuthProvider;
   }): Promise<{ id: string; url: string }>;
 
   /**
@@ -342,6 +362,36 @@ export function scopesCovered(required: string[] | undefined, granted: string |
   return missingScopes(required, granted).length === 0;
 }
 
+/** Why a caller's own value for a per-user variable is not ready yet; see {@link userSecretGap}. */
+export type UserSecretGap = 'missing' | 'wrong-kind' | 'unauthorized' | 'under-scoped';
+
+/**
+ * Whether the CALLER's own value for a per-user variable is ready, and if not,
+ * why: the one rule the MCP proxy hides a tool by and `list_tool_setup` reports
+ * from, so the two cannot disagree. `null` when it is ready.
+ *
+ * - `missing`: no row at all, so it needs a value or a sign-in.
+ * - `wrong-kind`: a row of the OTHER kind than the manual now declares. A
+ *   `.tool` edited from an OAuth sign-in to a plain key (or back) leaves the
+ *   old row behind, and serving a token where a key is declared fails
+ *   opaquely at the provider. The credential has to be set up again.
+ * - `unauthorized`: an OAuth row with no token yet: registered, sign-in not
+ *   completed. Fail closed: anything but a confirmed `true` counts.
+ * - `under-scoped`: a token granted fewer scopes than the tool now declares,
+ *   so the call would fail at the provider; it needs signing in again.
+ */
+export function userSecretGap(
+  declared: { oauth: boolean; oauthScopes?: string[] },
+  status: Pick<SecretConfigStatus, 'userConfigured' | 'userAuthorized' | 'grantedScopes'> & { userKind?: SecretKind | null } | undefined,
+): UserSecretGap | null {
+  if (!status?.userConfigured) return 'missing';
+  const declaredKind: SecretKind = declared.oauth ? 'oauth' : 'static';
+  if (status.userKind && status.userKind !== declaredKind) return 'wrong-kind';
+  if (declared.oauth && status.userAuthorized !== true) return 'unauthorized';
+  if (declared.oauth && !scopesCovered(declared.oauthScopes, status.grantedScopes)) return 'under-scoped';
+  return null;
+}
+
 /**
  * Is the stored row the KIND the manual now declares — i.e. would the thing the
  * UI is about to offer actually work?