@bevel-software/platform-core-backend 0.15.1 → 0.19.0

package/src/modules/secrets-vault/__tests__/connect-pending.route.test.ts

@@ -4,10 +4,17 @@ import { afterEach, describe, expect, it } from 'vitest';
 import { createSecretsVaultRoutes } from '../secrets-vault.routes.js';
 
 /**
- * The aggregated `/connect/pending` surface: only the caller's PER-USER items
- * (never admin/shared), plus their OAuth secrets. Exercised with stub services
- * behind a fake-auth middleware over a real loopback server (no DB / JWT), the
- * same lightweight harness style the MCP proxy tests use.
+ * The aggregated `/connect/pending` surface: everything standing between the
+ * caller and the tools they can READ — their own keys and sign-ins, and the
+ * workspace values somebody else may have to set — plus their OAuth secrets.
+ * Exercised with stub services behind a fake-auth middleware over a real
+ * loopback server (no DB / JWT), the same lightweight harness style the MCP
+ * proxy tests use.
+ *
+ * The admin tier is here because the Library's plugin banner counts an
+ * integration waiting on one, and the page this feeds is where that banner
+ * sends people. What the tier does NOT do is widen who sees what: every item
+ * still comes from `listAccessible`.
  */
 
 // One tool with a mix of scopes; one of its user vars is set, one isn't.
@@ -32,7 +39,12 @@ const secretsVault = {
     keys.map((key) => ({
       key,
       adminConfigured: false,
+      adminKind: null,
       userConfigured: key === 'weather_API_KEY', // one set, the other not
+      // The kind the row is really stored as — the vault reports it, and
+      // `/connect/pending` only calls a variable configured when the row backs
+      // the shape the manual declares. These are plain keys, so: static.
+      userKind: key === 'weather_API_KEY' ? ('static' as const) : null,
     })),
   list: async () => [
     {
@@ -97,22 +109,39 @@ afterEach(async () => {
   httpServer = undefined;
 });
 
+interface PendingBody {
+  tools: {
+    slug: string;
+    canWrite: boolean;
+    variables: { name: string; scope: string; configured: boolean; ownerOnly: boolean }[];
+  }[];
+  oauth: { id: string; key: string; label: string | null; authorized: boolean }[];
+}
+
 describe('GET /api/connect/pending', () => {
-  it('returns only the caller’s per-user items with set/not-set, plus OAuth secrets', async () => {
+  it('returns the caller’s own items AND the workspace ones, set/not-set', async () => {
     const base = await baseUrlWith({ userId: 'u1', email: 'a@x.com' });
     const res = await fetch(`${base}/api/connect/pending`);
     expect(res.status).toBe(200);
-    const body = (await res.json()) as {
-      tools: { slug: string; variables: { name: string; configured: boolean }[] }[];
-      oauth: { id: string; key: string; label: string | null; authorized: boolean }[];
-    };
+    const body = (await res.json()) as PendingBody;
 
-    // The admin-scoped SHARED_KEY must NOT appear — only the two user vars.
+    // All three: the admin-scoped SHARED_KEY is unset, so it is outstanding for
+    // somebody — and the banner that links here counts the tool for it.
     const tool = body.tools.find((t) => t.slug === 'weather')!;
-    expect(tool.variables.map((v) => v.name).sort()).toEqual(['API_KEY', 'USER_TOKEN']);
-    const byName = Object.fromEntries(tool.variables.map((v) => [v.name, v.configured]));
-    expect(byName.API_KEY).toBe(true); // configured
-    expect(byName.USER_TOKEN).toBe(false); // outstanding
+    expect(tool.variables.map((v) => v.name).sort()).toEqual([
+      'API_KEY',
+      'SHARED_KEY',
+      'USER_TOKEN',
+    ]);
+    const byName = Object.fromEntries(tool.variables.map((v) => [v.name, v]));
+    expect(byName.API_KEY.configured).toBe(true); // configured
+    expect(byName.USER_TOKEN.configured).toBe(false); // outstanding
+    // This caller cannot write the `.tool`, so the shared one is not theirs to set.
+    expect(tool.canWrite).toBe(false);
+    expect(byName.SHARED_KEY).toMatchObject({ scope: 'admin', configured: false, ownerOnly: true });
+    // …and their own vars are never owner-only, whatever they may write.
+    expect(byName.API_KEY.ownerOnly).toBe(false);
+    expect(byName.USER_TOKEN.ownerOnly).toBe(false);
 
     // OAuth secrets are surfaced with their authorized state (static ones filtered out).
     expect(body.oauth).toEqual([{ id: 'oauth-1', key: 'notion_NOTION_TOKEN', label: 'Notion', authorized: false }]);
@@ -125,6 +154,184 @@ describe('GET /api/connect/pending', () => {
   });
 });
 
+describe('GET /api/connect/pending — the workspace tier', () => {
+  /** The same one tool, with the caller's write verdict and the vault's answers dialled. */
+  async function pendingFor(opts: {
+    canWrite: boolean;
+    adminConfigured?: boolean;
+  }): Promise<PendingBody> {
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+      req.userId = 'u1';
+      req.userEmail = 'a@x.com';
+      next();
+    });
+    app.use(
+      '/api',
+      createSecretsVaultRoutes({
+        secretsVault: {
+          statusFor: async (_u: string, keys: string[]) =>
+            keys.map((key) => ({
+              key,
+              adminConfigured: opts.adminConfigured ?? false,
+              adminKind: opts.adminConfigured ? ('static' as const) : null,
+              userConfigured: false,
+              userKind: null,
+            })),
+          list: async () => [],
+        } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'],
+        toolManualService: {
+          listAccessible: async () => [
+            {
+              slug: 'salesforce',
+              name: 'salesforce',
+              path: 'Plugins/GTM/salesforce.tool',
+              type: 'http' as const,
+              variables: [{ name: 'ORG_TOKEN', scope: 'admin' as const, label: null }],
+            },
+          ],
+        } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'],
+        accessControl: {
+          canWrite: async () => opts.canWrite,
+          canRead: async () => true,
+        } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['accessControl'],
+        connectionProbe: {
+          probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+        },
+        stateSecret: 'test-secret',
+        publicBackendUrl: 'http://localhost:3000',
+        publicFrontendUrl: 'http://localhost:5173',
+      }),
+    );
+    httpServer = await new Promise<HttpServer>((resolve) => {
+      const s = app.listen(0, () => resolve(s));
+    });
+    const port = (httpServer.address() as { port: number }).port;
+    const res = await fetch(`http://127.0.0.1:${port}/api/connect/pending`);
+    // An error body parses as JSON too, and `body.tools` would then be undefined
+    // — a confusing crash where the tests below mean to read a verdict.
+    expect(res.status).toBe(200);
+    return (await res.json()) as PendingBody;
+  }
+
+  it('flags an unset workspace key the caller cannot write', async () => {
+    const body = await pendingFor({ canWrite: false });
+    const tool = body.tools.find((t) => t.slug === 'salesforce')!;
+    expect(tool.canWrite).toBe(false);
+    expect(tool.variables).toEqual([
+      expect.objectContaining({ name: 'ORG_TOKEN', scope: 'admin', ownerOnly: true }),
+    ]);
+  });
+
+  it('gives the OWNER the same key as an ordinary one to set', async () => {
+    const body = await pendingFor({ canWrite: true });
+    const tool = body.tools.find((t) => t.slug === 'salesforce')!;
+    expect(tool.canWrite).toBe(true);
+    expect(tool.variables[0].ownerOnly).toBe(false);
+  });
+
+  it('drops a workspace key that is already set — outstanding for nobody', async () => {
+    // And with nothing left, the tool itself drops out: an integration that
+    // needs no one is not on a page about what needs someone, and the banner
+    // does not count it either.
+    const body = await pendingFor({ canWrite: false, adminConfigured: true });
+    expect(body.tools).toEqual([]);
+  });
+});
+
+describe('GET /api/connect/pending — readability', () => {
+  /**
+   * A catalog that really withholds: `blackbox` exists, needs a workspace key,
+   * and only `owner@x.com` may read it. The workspace tier is exactly the kind
+   * of addition that could leak a name — the item is listed for the benefit of
+   * people who cannot act on it — so the gate is asserted from both sides.
+   */
+  async function listingFor(email: string): Promise<PendingBody> {
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+      req.userId = 'u1';
+      req.userEmail = email;
+      next();
+    });
+    app.use(
+      '/api',
+      createSecretsVaultRoutes({
+        secretsVault: {
+          statusFor: async (_u: string, keys: string[]) =>
+            keys.map((key) => ({
+              key,
+              adminConfigured: false,
+              adminKind: null,
+              userConfigured: false,
+              userKind: null,
+            })),
+          list: async () => [],
+        } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'],
+        toolManualService: {
+          listAccessible: async (who: string) =>
+            [
+              {
+                slug: 'weather',
+                name: 'weather',
+                path: 'Tools/weather.tool',
+                type: 'http' as const,
+                variables: [{ name: 'API_KEY', scope: 'user' as const, label: null }],
+              },
+              {
+                slug: 'blackbox',
+                name: 'blackbox',
+                path: 'Tools/blackbox.tool',
+                type: 'http' as const,
+                variables: [{ name: 'ORG_TOKEN', scope: 'admin' as const, label: null }],
+              },
+            ].filter((m) => m.slug !== 'blackbox' || who === 'owner@x.com'),
+        } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'],
+        accessControl,
+        connectionProbe: {
+          probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+        },
+        stateSecret: 'test-secret',
+        publicBackendUrl: 'http://localhost:3000',
+        publicFrontendUrl: 'http://localhost:5173',
+      }),
+    );
+    httpServer = await new Promise<HttpServer>((resolve) => {
+      const s = app.listen(0, () => resolve(s));
+    });
+    const port = (httpServer.address() as { port: number }).port;
+    const res = await fetch(`http://127.0.0.1:${port}/api/connect/pending`);
+    // Asserted here, once, for every caller of this helper: a 500 body would
+    // otherwise sail through the assertions below as "the tool is not listed",
+    // which is the one wrong answer that looks like the right one.
+    expect(res.status).toBe(200);
+    return (await res.json()) as PendingBody;
+  }
+
+  it('never names a tool the caller cannot read, in any state', async () => {
+    const body = await listingFor('a@x.com');
+    // The parsed listing, not the raw text: `expect(raw).not.toContain(…)` also
+    // passes when `tools` moved, emptied or errored, and the contract under test
+    // is what the client reads off the payload.
+    expect(body.tools.map((t) => t.slug)).toEqual(['weather']);
+  });
+
+  it('lists it, owner-only, for somebody who can read it', async () => {
+    // The previous test would also pass if the route had simply dropped every
+    // owner-only item; this is what says it did not.
+    const body = await listingFor('owner@x.com');
+    const blackbox = body.tools.find((t) => t.slug === 'blackbox');
+    expect(blackbox).toBeDefined();
+    expect(blackbox!.variables).toEqual([
+      expect.objectContaining({ name: 'ORG_TOKEN', scope: 'admin', ownerOnly: true }),
+    ]);
+    // …and `ownerOnly` is a verdict, not a constant: the readable tool this
+    // caller CAN act on is listed in the same payload without it.
+    expect(body.tools.find((t) => t.slug === 'weather')!.variables[0].ownerOnly).toBe(false);
+  });
+});
+
 describe('GET /api/connect/pending — OAuth scope coverage', () => {
   // A tool with an OAuth-backed var that now requires two scopes.
   const oauthTool = {
@@ -157,7 +364,9 @@ describe('GET /api/connect/pending — OAuth scope coverage', () => {
         keys.map((key) => ({
           key,
           adminConfigured: false,
+          adminKind: null,
           userConfigured: true,
+          userKind: 'oauth' as const,
           userAuthorized: true,
           grantedScopes,
         })),
@@ -243,7 +452,14 @@ describe('GET /api/connect/pending — tool sign-ins are not double-listed as st
     } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
     const vault = {
       statusFor: async (_u: string, keys: string[]) =>
-        keys.map((key) => ({ key, adminConfigured: true, userConfigured: true, userAuthorized: true })),
+        keys.map((key) => ({
+          key,
+          adminConfigured: true,
+          adminKind: 'oauth' as const, // the provider registration, as the flow needs it
+          userConfigured: true,
+          userKind: 'oauth' as const,
+          userAuthorized: true,
+        })),
       list: async () => [
         // The provisioned per-user row for the TOOL sign-in — must be excluded.
         { id: 's-tool', key: 'notion_MCP_OAUTH', kind: 'oauth' as const, label: 'notion sign-in', authorized: true, createdAt: new Date(), updatedAt: new Date() },
@@ -287,3 +503,131 @@ describe('GET /api/connect/pending — tool sign-ins are not double-listed as st
     expect(body.oauth.map((o) => o.id)).toEqual(['s-own']);
   });
 });
+
+describe('GET /api/connect/pending — a row of the wrong KIND is not "set up"', () => {
+  /**
+   * A `.tool` can be edited to turn a plain shared key into an OAuth variable,
+   * or back, and the row set for the previous shape outlives the edit. The two
+   * are not interchangeable — `beginToolOAuthByKey` refuses a `static` shared
+   * row outright — so "a row exists" must not be reported as "configured", or
+   * the page offers an Authorize that cannot open and a key that nobody set
+   * disappears from the list of what is missing.
+   */
+  type Status = {
+    key: string;
+    adminConfigured: boolean;
+    adminKind: 'static' | 'oauth' | null;
+    userConfigured: boolean;
+    userKind: 'static' | 'oauth' | null;
+  };
+
+  async function pendingWith(opts: {
+    variables: unknown[];
+    status: (key: string) => Status;
+  }): Promise<{
+    tools: { slug: string; variables: { name: string; configured: boolean }[] }[];
+    toolOAuth: { varName: string; ownerConfigured: boolean; ownerOnly: boolean }[];
+  }> {
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+      req.userId = 'u1';
+      req.userEmail = 'a@x.com';
+      next();
+    });
+    app.use(
+      '/api',
+      createSecretsVaultRoutes({
+        secretsVault: {
+          statusFor: async (_u: string, keys: string[]) => keys.map(opts.status),
+          list: async () => [],
+        } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'],
+        toolManualService: {
+          listAccessible: async () => [
+            {
+              slug: 'google',
+              name: 'google',
+              path: 'Tools/google.tool',
+              type: 'inline' as const,
+              variables: opts.variables,
+            },
+          ],
+        } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'],
+        accessControl,
+        connectionProbe: {
+          probe: async () => ({ status: 'unverifiable' as const, detail: null, checkedAt: new Date() }),
+        },
+        stateSecret: 'test-secret',
+        publicBackendUrl: 'http://localhost:3000',
+        publicFrontendUrl: 'http://localhost:5173',
+      }),
+    );
+    httpServer = await new Promise<HttpServer>((resolve) => {
+      const s = app.listen(0, () => resolve(s));
+    });
+    const port = (httpServer.address() as { port: number }).port;
+    const res = await fetch(`http://127.0.0.1:${port}/api/connect/pending`);
+    expect(res.status).toBe(200);
+    return (await res.json()) as Awaited<ReturnType<typeof pendingWith>>;
+  }
+
+  const oauthVar = [
+    {
+      name: 'GOOGLE_TOKEN',
+      scope: 'user' as const,
+      label: 'Google',
+      oauth: {
+        authorizationUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+        tokenUrl: 'https://oauth2.googleapis.com/token',
+        clientId: 'cid',
+      },
+    },
+  ];
+
+  it('does not call an OAuth var registered when the shared row is a leftover static key', async () => {
+    const body = await pendingWith({
+      variables: oauthVar,
+      status: (key) => ({
+        key,
+        adminConfigured: true, // a row is there…
+        adminKind: 'static', // …but it is the key from before this var was OAuth
+        userConfigured: false,
+        userKind: null,
+      }),
+    });
+    const signIn = body.toolOAuth.find((o) => o.varName === 'GOOGLE_TOKEN')!;
+    // No consent screen exists behind that row, so the page must show the
+    // owner's job, not an Authorize the flow would reject.
+    expect(signIn.ownerConfigured).toBe(false);
+    expect(signIn.ownerOnly).toBe(true); // this caller cannot write the `.tool`
+  });
+
+  it('calls it registered when the shared row is the OAuth one the flow reads', async () => {
+    const body = await pendingWith({
+      variables: oauthVar,
+      status: (key) => ({
+        key,
+        adminConfigured: true,
+        adminKind: 'oauth',
+        userConfigured: false,
+        userKind: null,
+      }),
+    });
+    expect(body.toolOAuth.find((o) => o.varName === 'GOOGLE_TOKEN')!.ownerConfigured).toBe(true);
+  });
+
+  it('does not call a plain key configured when the caller’s row is a leftover OAuth one', async () => {
+    const body = await pendingWith({
+      variables: [{ name: 'API_KEY', scope: 'user' as const, label: null }],
+      status: (key) => ({
+        key,
+        adminConfigured: false,
+        adminKind: null,
+        userConfigured: true, // a row is there…
+        userKind: 'oauth', // …holding a token set, where this var wants a value
+      }),
+    });
+    const apiKey = body.tools.find((t) => t.slug === 'google')!.variables[0];
+    expect(apiKey.configured).toBe(false);
+  });
+});

package/src/modules/secrets-vault/__tests__/db-secrets-vault.oauth.test.ts

@@ -54,6 +54,93 @@ function makeFakeDb(queue: any[]) {
   return { db, captured };
 }
 
+/**
+ * A drizzle stub that ANSWERS FROM THE WHERE-CLAUSE, for the one assertion the
+ * sequential `makeFakeDb` cannot make: that the optimistic-concurrency guard
+ * (`eq(valueEncrypted, <the ciphertext we read>)`) is what stops a stale write.
+ *
+ * `current` is the row as it is NOW — already rotated by a concurrent refresh.
+ * `stale` is the ciphertext the caller read a moment before that, which the
+ * FIRST select hands back; any later select sees `current`. An UPDATE is
+ * applied unless its where-clause binds `stale`, i.e. unless it is guarded on
+ * a version the row has moved past. Remove the guard from the code under test
+ * and the UPDATE lands — which is what makes such a test fail.
+ */
+function whereAwareDb(
+  current: Record<string, unknown> & { valueEncrypted: string },
+  /** The ciphertext the caller read first — or the whole row as it read then, when more than the ciphertext has since changed. */
+  staleRead: string | (Partial<Record<string, unknown>> & { valueEncrypted: string }),
+) {
+  const updates: Array<Record<string, unknown>> = [];
+  let row = { ...current };
+  let firstSelect = true;
+  const staleRow = typeof staleRead === 'string' ? { valueEncrypted: staleRead } : staleRead;
+  const stale = staleRow.valueEncrypted;
+  // Drizzle builds the condition into an SQL object whose bound parameters sit
+  // in nested `queryChunks`; the test only needs to know WHETHER a given
+  // ciphertext was bound, so it scans the object graph for that string.
+  const binds = (cond: unknown, value: string): boolean => {
+    const seen = new Set<unknown>();
+    const walk = (node: unknown): boolean => {
+      if (node === value) return true;
+      if (node === null || typeof node !== 'object' || seen.has(node)) return false;
+      seen.add(node);
+      return Object.values(node as Record<string, unknown>).some(walk);
+    };
+    return walk(cond);
+  };
+  type Thenable<T> = { then: (onF: (v: T) => unknown, onR?: (e: unknown) => unknown) => Promise<unknown> };
+  type SelectChain = Thenable<Array<Record<string, unknown>>> & {
+    from: () => SelectChain;
+    where: () => SelectChain;
+    limit: () => SelectChain;
+  };
+  type UpdateChain = Thenable<Array<{ id: unknown }>> & {
+    set: (values: Record<string, unknown>) => UpdateChain;
+    where: (cond: unknown) => UpdateChain;
+    returning: () => UpdateChain;
+  };
+  const db = {
+    select: (): SelectChain => {
+      const chain: SelectChain = {
+        from: () => chain,
+        where: () => chain,
+        limit: () => chain,
+        then: (onF, onR) => {
+          const seen = firstSelect ? { ...row, ...staleRow } : row;
+          firstSelect = false;
+          return Promise.resolve([seen]).then(onF, onR);
+        },
+      };
+      return chain;
+    },
+    update: (): UpdateChain => {
+      let payload: Record<string, unknown> = {};
+      let matched = true;
+      const chain: UpdateChain = {
+        set: (values) => {
+          payload = values;
+          return chain;
+        },
+        where: (cond) => {
+          matched = !binds(cond, stale) || stale === row.valueEncrypted;
+          return chain;
+        },
+        returning: () => chain,
+        then: (onF, onR) => {
+          if (matched) {
+            updates.push(payload);
+            row = { ...row, ...payload } as typeof row;
+          }
+          return Promise.resolve(matched ? [{ id: row.id }] : []).then(onF, onR);
+        },
+      };
+      return chain;
+    },
+  };
+  return { db: db as unknown as Database, updates };
+}
+
 function sharedRow(over: Partial<Record<string, unknown>> = {}) {
   return {
     id: 'shared-1',
@@ -347,3 +434,164 @@ describe('DbSecretsVaultService — dead-grant detection on refresh', () => {
     }
   });
 });
+
+describe('DbSecretsVaultService — forceRefresh (a downstream rejected the token)', () => {
+  // NOT expired by its own account: the stored expiry is an hour away. The
+  // downstream's 401 is what says the token is dead.
+  const liveTokens = () => ({
+    access_token: 'rejected-at',
+    refresh_token: 'rt-1',
+    expires_at: Date.now() + 3_600_000,
+    scope: 'mcp.read',
+  });
+  const userRow = (blob: Record<string, unknown> = { clientSecret: 'client-secret-1', tokens: liveTokens() }) =>
+    sharedRow({ id: 'user-row-1', userId: 'user-1', valueEncrypted: crypto.encrypt(JSON.stringify(blob)) });
+
+  it('refreshes ignoring the stored expiry, persists the fresh tokens and notifies', async () => {
+    const { db, captured } = makeFakeDb([[userRow()], undefined]);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    const onMutation = vi.fn();
+    svc.onMutation(onMutation);
+    const fetchMock = vi.fn(async () =>
+      new Response(JSON.stringify({ access_token: 'fresh-at', expires_in: 3600 }), { status: 200 }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('refreshed');
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const stored = JSON.parse(crypto.decrypt(captured.set[0].valueEncrypted));
+    expect(stored.tokens.access_token).toBe('fresh-at');
+    expect(stored.tokens.refresh_token).toBe('rt-1'); // provider omitted it — kept
+    expect(stored.clientSecret).toBe('client-secret-1');
+    expect(onMutation).toHaveBeenCalledWith('user-1');
+  });
+
+  it('a definitive rejection wipes the tokens, keeps the client secret, and the sign-in reads not connected', async () => {
+    for (const status of [400, 401]) {
+      const { db, captured } = makeFakeDb([[userRow()], undefined]);
+      const svc = new DbSecretsVaultService(db, ENC_KEY);
+      const onMutation = vi.fn();
+      svc.onMutation(onMutation);
+      vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ error: 'invalid_grant' }), { status })));
+
+      await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('rejected');
+
+      const wiped = captured.set[0].valueEncrypted;
+      const stored = JSON.parse(crypto.decrypt(wiped));
+      expect(stored).toEqual({ clientSecret: 'client-secret-1' });
+      expect(onMutation).toHaveBeenCalledWith('user-1');
+
+      // What list_tool_setup and /connect read: the row exists, the sign-in does not.
+      const status2 = makeFakeDb([[{ key: KEY, userId: 'user-1', kind: 'oauth', valueEncrypted: wiped }]]);
+      const [row] = await new DbSecretsVaultService(status2.db, ENC_KEY).statusFor('user-1', [KEY]);
+      expect(row).toMatchObject({ userConfigured: true, userAuthorized: false });
+    }
+  });
+
+  it('a transient failure (network / 5xx) keeps the token untouched', async () => {
+    for (const impl of [
+      async () => new Response('bad gateway', { status: 503 }),
+      async () => {
+        throw new TypeError('fetch failed');
+      },
+    ]) {
+      const { db, captured } = makeFakeDb([[userRow()]]);
+      const svc = new DbSecretsVaultService(db, ENC_KEY);
+      vi.stubGlobal('fetch', vi.fn(impl));
+
+      await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('transient');
+      expect(captured.set).toEqual([]);
+    }
+  });
+
+  it('a rejected token with no refresh token to try is a dead grant: wiped', async () => {
+    const { access_token } = liveTokens();
+    const { db, captured } = makeFakeDb([[userRow({ tokens: { access_token } })], undefined]);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('rejected');
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(JSON.parse(crypto.decrypt(captured.set[0].valueEncrypted)).tokens).toBeUndefined();
+  });
+
+  it('a concurrent refresh that already rotated the tokens wins over our stale rejection', async () => {
+    const rotated = crypto.encrypt(JSON.stringify({ tokens: { access_token: 'rotated-at', refresh_token: 'rt-2' } }));
+    // Not the sequential stub: this one READS the where-clause, so the wipe
+    // matches nothing precisely BECAUSE the row's ciphertext moved on. Drop the
+    // optimistic-concurrency guard from `wipeTokens` and the UPDATE matches, the
+    // rotated grant is wiped, and this test fails — which is the point of it.
+    const { db, updates } = whereAwareDb({ ...userRow(), valueEncrypted: rotated }, userRow().valueEncrypted);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    vi.stubGlobal('fetch', vi.fn(async () => new Response('{}', { status: 400 })));
+
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('refreshed');
+    expect(updates).toEqual([]); // the guarded wipe never matched the rotated row
+  });
+
+  it('a refresh whose write loses the same race serves what the winner stored, not our unwritten token', async () => {
+    const rotated = crypto.encrypt(JSON.stringify({ tokens: { access_token: 'rotated-at', refresh_token: 'rt-2' } }));
+    const { db, updates } = whereAwareDb({ ...userRow(), valueEncrypted: rotated }, userRow().valueEncrypted);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    const onMutation = vi.fn();
+    svc.onMutation(onMutation);
+    // Our OWN refresh succeeds — but the row moved on while it was in flight.
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ access_token: 'ours-at', expires_in: 3600 }), { status: 200 })),
+    );
+
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('refreshed');
+
+    // Nothing persisted, so nothing is announced and `resolve` keeps serving
+    // the winner's token — never the one that exists only in this call frame.
+    expect(updates).toEqual([]);
+    expect(onMutation).not.toHaveBeenCalled();
+  });
+
+  it('a refresh that loses the race to a WIPE reports the grant not connected', async () => {
+    const wipedOut = crypto.encrypt(JSON.stringify({ clientSecret: 'client-secret-1' }));
+    const { db, updates } = whereAwareDb({ ...userRow(), valueEncrypted: wipedOut }, userRow().valueEncrypted);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ access_token: 'ours-at', expires_in: 3600 }), { status: 200 })),
+    );
+
+    // A concurrent path found the grant dead and wiped it; the stored truth is
+    // "not connected", and that is what the caller is told.
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('rejected');
+    expect(updates).toEqual([]);
+  });
+
+  it('a refresh that loses the race to a row turned STATIC reports not connected, whatever the value parses as', async () => {
+    // The edit that replaced the sign-in stored a static value shaped exactly
+    // like a token blob. It is not a grant, and must not be served as one.
+    const lookalike = crypto.encrypt(JSON.stringify({ tokens: { access_token: 'not-a-grant' } }));
+    // Read as the OAuth row it was; by the time the refresh writes, it is static.
+    const { db, updates } = whereAwareDb(
+      { ...userRow(), kind: 'static', valueEncrypted: lookalike },
+      { valueEncrypted: userRow().valueEncrypted, kind: 'oauth' },
+    );
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ access_token: 'ours-at', expires_in: 3600 }), { status: 200 })),
+    );
+
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('rejected');
+    expect(updates).toEqual([]);
+  });
+
+  it('nothing to refresh — no row, or never signed in — is skipped without a provider call', async () => {
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+    for (const rows of [[], [userRow({ clientSecret: 'client-secret-1' })]]) {
+      const { db } = makeFakeDb([rows]);
+      await expect(new DbSecretsVaultService(db, ENC_KEY).forceRefresh('user-1', KEY)).resolves.toBe('skipped');
+    }
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});