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

package/src/modules/connection-probe/connection-probe.service.ts

@@ -12,6 +12,7 @@ import type { ISecretsVaultService } from '../secrets-vault/index.js';
 import { bevelSecretsLoaderConfig } from '../secrets-vault/index.js';
 import { utcpNamespacedKey } from '../../shared/utcp-namespace.js';
 import { assertSafeFetchUrl } from '../../shared/ssrf.js';
+import { readCapped } from '../../shared/read-capped.js';
 import type { IConnectionProbeService, ProbeStatus, ProbeVerdict } from './connection-probe.contract.js';
 
 /** How long a probe may take before we call it inconclusive. */
@@ -753,37 +754,3 @@ async function describeRejection(res: Response, redactor: SecretRedactor): Promi
   }
 }
 
-/**
- * At most `limit` bytes of a response body, decoded as text.
- *
- * Each CHUNK is sliced to the remaining budget before being decoded, not just
- * counted against it: a provider that answers in one 5MB chunk would otherwise
- * put the whole thing through the decoder before the loop noticed it was over,
- * which is the bound bypassed by the very party it is meant to bound.
- *
- * Exported for its test — the property here is how much is held in memory,
- * which the caller's 200-character snippet hides completely.
- */
-export async function readCapped(res: Response, limit: number): Promise<string> {
-  const reader = res.body?.getReader();
-  // No stream (a mocked or already-consumed response): fall back to the whole
-  // body, which for those cases is ours and small.
-  if (!reader) return (await res.text()).slice(0, limit);
-  const decoder = new TextDecoder();
-  let out = '';
-  let read = 0;
-  try {
-    while (read < limit) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      const remaining = limit - read;
-      const chunk = value.byteLength > remaining ? value.subarray(0, remaining) : value;
-      read += chunk.byteLength;
-      out += decoder.decode(chunk, { stream: true });
-      if (chunk.byteLength < value.byteLength) break;
-    }
-  } finally {
-    await reader.cancel().catch(() => {});
-  }
-  return out;
-}

package/src/modules/mcp/mcp.service.ts

@@ -50,7 +50,7 @@ import {
   type LoadedSkill,
 } from '@bevel-software/platform-mcp-core';
 import type { KbLayout } from '@bevel-software/platform-shared';
-import { bevelSecretsLoaderConfig, type ForcedRefreshOutcome, type ISecretsVaultService, scopesCovered } from '../secrets-vault/index.js';
+import { bevelSecretsLoaderConfig, type ForcedRefreshOutcome, type ISecretsVaultService, userSecretGap } from '../secrets-vault/index.js';
 import { EXTERNAL_KB_MANUAL_NAME } from '../tool-manuals/index.js';
 import type { IToolManualService } from '../tool-manuals/index.js';
 import type { SpillStore } from '../workspace/index.js';
@@ -1690,41 +1690,11 @@ export class McpService {
     const statusMap = new Map(status.map((s) => [s.key, s]));
     const missing: { name: string; label?: string | null; brokenSignIn: boolean }[] = [];
     for (const v of userVars) {
-      const st = statusMap.get(v.key);
+      // The one readiness rule `list_tool_setup` reports from (`userSecretGap`).
       // A sign-in the caller already HAS a row for but that isn't (or is no
-      // longer) usable: dead/wiped grant, abandoned consent, missing scopes.
-      const brokenSignIn = Boolean(v.oauth && st?.userConfigured);
-      if (!st?.userConfigured) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn }); // no row at all → needs a value / sign-in
-        continue;
-      }
-      // A row of the OTHER kind is not this credential: 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 — or a key where a
-      // sign-in is — fails opaquely at the provider. Not a broken sign-in
-      // either: nothing to reset, the user has to set the credential up as
-      // the manual now declares it.
-      const declaredKind = v.oauth ? 'oauth' : 'static';
-      if (st.userKind && st.userKind !== declaredKind) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn: false });
-        continue;
-      }
-      // An OAuth-backed var whose row exists but has no token yet is NOT ready —
-      // the user has registered but not completed sign-in. Fail closed: anything
-      // other than a confirmed `true` (including a non-oauth row → undefined)
-      // counts as not-yet-authorized.
-      if (v.oauth && st.userAuthorized !== true) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn });
-        continue;
-      }
-      // An OAuth-backed var the user signed in for, but whose token was granted
-      // fewer scopes than the tool now declares, is ALSO not ready — the call would
-      // otherwise fail opaquely at the provider. Compare the live required scopes
-      // against the token's recorded granted scopes; an under-scoped (or unknown)
-      // token needs re-authorization.
-      if (v.oauth && !scopesCovered(v.oauthScopes, st.grantedScopes)) {
-        missing.push({ name: v.name, label: v.label, brokenSignIn });
-      }
+      // longer) usable is a broken sign-in: abandoned consent, missing scopes.
+      const gap = userSecretGap(v, statusMap.get(v.key));
+      if (gap) missing.push({ name: v.name, label: v.label, brokenSignIn: gap === 'unauthorized' || gap === 'under-scoped' });
     }
     return missing;
   }

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

@@ -1,9 +1,10 @@
 import { describe, expect, it, vi, afterEach } from 'vitest';
 import { createHash } from 'node:crypto';
-import { DbSecretsVaultService } from '../db-secrets-vault.service.js';
-import { SecretOAuthError } from '../secrets-vault.contract.js';
+import { DbSecretsVaultService, InvalidSecretError, SecretOAuthError } from '../index.js';
 import { TokenCrypto } from '../../../shared/token-crypto.js';
-import type { Database } from '../../database/connection.js';
+import type { Database } from '../../database/index.js';
+import { setLogger } from '../../../shared/logging.js';
+import type { ILogger, LogFields } from '../../../shared/logger.contract.js';
 
 const ENC_KEY = Buffer.alloc(32, 7).toString('base64');
 const crypto = new TokenCrypto(ENC_KEY);
@@ -595,3 +596,429 @@ describe('DbSecretsVaultService — forceRefresh (a downstream rejected the toke
     expect(fetchMock).not.toHaveBeenCalled();
   });
 });
+
+describe("DbSecretsVaultService — a refused token request names the provider's error code, never its text", () => {
+  const confidentialRow = (blob: Record<string, unknown>) =>
+    sharedRow({
+      id: 'user-row-1',
+      userId: 'user-1',
+      oauthMeta: { ...PUBLIC_META, publicClient: false },
+      valueEncrypted: crypto.encrypt(JSON.stringify(blob)),
+    });
+  const SECRET = 'client-secret-1';
+  const BLOB = { clientSecret: SECRET, pendingVerifier: 'the-verifier' };
+  const INVALID_CLIENT =
+    '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.';
+
+  async function exchangeFailure(
+    body: string | ReadableStream<Uint8Array>,
+    status = 400,
+    blob: Record<string, unknown> = BLOB,
+  ): Promise<SecretOAuthError> {
+    const { db } = makeFakeDb([[confidentialRow(blob)]]);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(body, { status })));
+    try {
+      await svc.completeOAuth('user-1', 'user-row-1', 'the-code', 'https://bevel.example.com/cb');
+    } catch (err) {
+      expect(err).toBeInstanceOf(SecretOAuthError);
+      return err as SecretOAuthError;
+    }
+    throw new Error('the exchange was expected to fail');
+  }
+
+  it('names an OAuth error code and says what to do about it, with the status', async () => {
+    const client = await exchangeFailure(
+      JSON.stringify({ error: 'invalid_client', error_description: 'Client authentication failed' }),
+    );
+    expect(client.message).toBe(INVALID_CLIENT);
+    expect(client.providerStatus).toBe(400);
+    const grant = await exchangeFailure(JSON.stringify({ error: 'invalid_grant' }));
+    expect(grant.message).toBe(
+      'Token endpoint returned HTTP 400 (invalid_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 scope = await exchangeFailure(JSON.stringify({ error: 'invalid_scope' }));
+    expect(scope.message).toBe(
+      "Token endpoint returned HTTP 400 (invalid_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 unauthorized = await exchangeFailure(JSON.stringify({ error: 'unauthorized_client' }));
+    expect(unauthorized.message).toBe(
+      "Token endpoint returned HTTP 400 (unauthorized_client). The provider does not allow this client to use this grant. The tool owner should check the provider's app settings.",
+    );
+  });
+
+  it("names a provider's own status code (HubSpot's shape) with the sentence of its OAuth equivalent", async () => {
+    const err = await exchangeFailure(
+      JSON.stringify({ status: 'BAD_CLIENT_SECRET', message: 'client secret does not match', correlationId: 'c1' }),
+    );
+    expect(err.message).toBe(INVALID_CLIENT.replace('(invalid_client)', '(BAD_CLIENT_SECRET)'));
+  });
+
+  it('takes nothing of the body but the code: descriptions, unknown shapes, plain text and cut bodies leave no trace', async () => {
+    const withDescription = JSON.stringify({ error: 'invalid_client', error_description: `secret ${SECRET} rejected` });
+    expect((await exchangeFailure(withDescription)).message).toBe(INVALID_CLIENT);
+    for (const body of [
+      JSON.stringify({ detail: `${SECRET} rejected` }),
+      `<html>${SECRET} rejected</html>`,
+      `${SECRET} rejected\nmore`,
+      JSON.stringify({ error: 'invalid_client', error_description: SECRET }).slice(0, 30),
+      JSON.stringify(`${SECRET} rejected`),
+      JSON.stringify([`${SECRET} rejected`]),
+      '{}',
+      '',
+    ]) {
+      expect((await exchangeFailure(body)).message).toBe('Token endpoint returned HTTP 400');
+    }
+  });
+
+  it('takes a code only when it is exactly one Hexis knows: anything else in that field is not a code', async () => {
+    // A secret, a secret with a suffix, a near-miss of a known code, a
+    // prototype key, free text: none is on the list, none reaches a message.
+    for (const code of [
+      'wordy_secret',
+      'wordy_secret_rejected',
+      'Invalid_Client',
+      'invalid_client ',
+      'invalid_token',
+      'constructor',
+      'bad code',
+      '',
+    ]) {
+      const err = await exchangeFailure(JSON.stringify({ error: code }), 400, {
+        clientSecret: 'wordy_secret',
+        pendingVerifier: 'the-verifier',
+      });
+      expect(err.message).toBe('Token endpoint returned HTTP 400');
+    }
+  });
+
+  it('keeps the status when the refusal body cannot be read, so a refused refresh still retires the grant', async () => {
+    const failing = () =>
+      new ReadableStream<Uint8Array>({
+        pull() {
+          throw new Error('connection reset');
+        },
+      });
+    const err = await exchangeFailure(failing(), 401);
+    expect(err.message).toBe('Token endpoint returned HTTP 401');
+    expect(err.providerStatus).toBe(401);
+
+    const { db, captured } = makeFakeDb([
+      [confidentialRow({ clientSecret: SECRET, tokens: { access_token: 'at', refresh_token: 'rt', expires_at: 1 } })],
+      undefined,
+    ]);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(failing(), { status: 400 })));
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('rejected');
+    expect(JSON.parse(crypto.decrypt(captured.set[0].valueEncrypted))).toEqual({ clientSecret: SECRET });
+  });
+
+  it('reads a refusal body only up to its cap and cancels the rest of the stream', async () => {
+    // Without the cap this never returns: the stream has no end.
+    let pulls = 0;
+    let cancelled = false;
+    const endless = new ReadableStream<Uint8Array>({
+      pull(controller) {
+        pulls += 1;
+        controller.enqueue(new TextEncoder().encode('z'.repeat(1024)));
+      },
+      cancel() {
+        cancelled = true;
+      },
+    });
+    const err = await exchangeFailure(endless, 502);
+    expect(err.message).toBe('Token endpoint returned HTTP 502');
+    expect(pulls).toBeLessThanOrEqual(3);
+    expect(cancelled).toBe(true);
+  });
+
+  it('a refused refresh is logged with the key, the outcome and the code as the sign-in is wiped', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const row = confidentialRow({
+      clientSecret: SECRET,
+      tokens: { access_token: 'at-old', refresh_token: 'rt-old', expires_at: 1 },
+    });
+    const { db } = makeFakeDb([[row], undefined]);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(
+        async () =>
+          new Response(JSON.stringify({ error: 'invalid_grant', error_description: 'rt-old was revoked' }), {
+            status: 400,
+          }),
+      ),
+    );
+
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('rejected');
+
+    const line = warn.mock.calls.map((c) => String(c[0])).find((m) => m.includes('refresh refused'));
+    expect(line).toContain(`refresh refused for "${KEY}", sign-in wiped: Token endpoint returned HTTP 400 (invalid_grant).`);
+    expect(line).not.toContain('rt-old');
+    warn.mockRestore();
+  });
+
+  it('a refused refresh that lost to a concurrent rotation logs that the rotated sign-in was kept, not wiped', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const row = confidentialRow({
+      clientSecret: SECRET,
+      tokens: { access_token: 'at-old', refresh_token: 'rt-old', expires_at: 1 },
+    });
+    const rotated = crypto.encrypt(
+      JSON.stringify({ clientSecret: SECRET, tokens: { access_token: 'rotated-at', refresh_token: 'rt-2' } }),
+    );
+    // The row moved on between our read and our guarded wipe: the wipe matches nothing.
+    const { db, updates } = whereAwareDb({ ...row, valueEncrypted: rotated }, row.valueEncrypted);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ error: 'invalid_grant' }), { status: 400 })));
+
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('refreshed');
+    expect(updates).toEqual([]);
+
+    const line = warn.mock.calls.map((c) => String(c[0])).find((m) => m.includes('refresh refused'));
+    expect(line).toContain(`refresh refused for "${KEY}", the row had been rotated by a concurrent refresh meanwhile`);
+    expect(line).toContain('the rotated sign-in is kept: Token endpoint returned HTTP 400 (invalid_grant)');
+    expect(line).not.toContain('sign-in wiped');
+    warn.mockRestore();
+  });
+
+  it('a refused refresh whose wipe matched nothing because the row was replaced logs that nothing was wiped', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const row = confidentialRow({
+      clientSecret: SECRET,
+      tokens: { access_token: 'at-old', refresh_token: 'rt-old', expires_at: 1 },
+    });
+    // Read as the OAuth row it was; by the time the wipe writes, an edit has
+    // made it a static value, so the guarded wipe matches nothing and no grant
+    // is there to serve: `rejected`, yet nothing was wiped.
+    const { db, updates } = whereAwareDb(
+      { ...row, kind: 'static', valueEncrypted: crypto.encrypt(JSON.stringify({ value: 'x' })) },
+      { valueEncrypted: row.valueEncrypted, kind: 'oauth' },
+    );
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify({ error: 'invalid_grant' }), { status: 400 })));
+
+    await expect(svc.forceRefresh('user-1', KEY)).resolves.toBe('rejected');
+    expect(updates).toEqual([]);
+
+    const line = warn.mock.calls.map((c) => String(c[0])).find((m) => m.includes('refresh refused'));
+    expect(line).toContain(`refresh refused for "${KEY}", the row had been removed or replaced meanwhile; nothing wiped:`);
+    expect(line).not.toContain('sign-in wiped');
+    warn.mockRestore();
+  });
+});
+
+describe('DbSecretsVaultService — a declared sign-in follows the live declaration', () => {
+  // What the owner's client-secret save stored: client id A and its endpoints.
+  const SAVED_META = {
+    authorizationUrl: 'https://old.example.com/authorize',
+    tokenUrl: 'https://old.example.com/token',
+    clientId: 'client-A',
+    scopes: ['crm.read'],
+    authParams: {},
+    pkce: true,
+    resource: 'https://mcp.example.com/',
+  };
+  // What the tool file reads now: client id B.
+  const LIVE = {
+    authorizationUrl: 'https://app.example.com/oauth/authorize',
+    tokenUrl: 'https://api.example.com/oauth/v1/token',
+    clientId: 'client-B',
+    scopes: ['crm.read', 'crm.write'],
+    authParams: { optional_scope: 'tickets' },
+    pkce: true,
+    resource: 'https://mcp.example.com/',
+  };
+  const confidentialShared = () =>
+    sharedRow({ oauthMeta: SAVED_META, valueEncrypted: crypto.encrypt(JSON.stringify({ clientSecret: 'cs-owner' })) });
+
+  const begin = (svc: DbSecretsVaultService, provider: Record<string, unknown> = LIVE) =>
+    svc.beginToolOAuthByKey({
+      userId: 'user-1',
+      key: KEY,
+      redirectUri: 'https://bevel.example.com/api/secrets/oauth/callback',
+      state: 's',
+      provider: provider as never,
+    });
+
+  it('builds the consent URL from the live declaration, not the stored copy, and records it on the caller row', async () => {
+    const { db, captured } = makeFakeDb([[confidentialShared()], [], [{ id: 'user-row-1' }]]);
+    const { url } = await begin(new DbSecretsVaultService(db, ENC_KEY));
+
+    const consent = new URL(url);
+    expect(consent.origin + consent.pathname).toBe(LIVE.authorizationUrl);
+    expect(consent.searchParams.get('client_id')).toBe('client-B');
+    expect(consent.searchParams.get('resource')).toBe(LIVE.resource);
+    expect(consent.searchParams.get('scope')).toBe('crm.read crm.write');
+    expect(consent.searchParams.get('optional_scope')).toBe('tickets');
+    const blob = JSON.parse(crypto.decrypt(captured.values[0].valueEncrypted));
+    expect(consent.searchParams.get('code_challenge')).toBe(
+      createHash('sha256').update(blob.pendingVerifier).digest('base64url'),
+    );
+    // The secret is the owner's, unchanged; the configuration is the file's.
+    expect(blob.clientSecret).toBe('cs-owner');
+    expect(captured.values[0].oauthMeta).toMatchObject({ clientId: 'client-B', tokenUrl: LIVE.tokenUrl });
+    expect(captured.values[0].oauthMeta.publicClient).toBeUndefined();
+  });
+
+  it('omits PKCE when the declaration opts out', async () => {
+    const { db, captured } = makeFakeDb([[confidentialShared()], [], [{ id: 'user-row-1' }]]);
+    const { url } = await begin(new DbSecretsVaultService(db, ENC_KEY), { ...LIVE, pkce: false });
+    expect(new URL(url).searchParams.get('code_challenge')).toBeNull();
+    expect(JSON.parse(crypto.decrypt(captured.values[0].valueEncrypted)).pendingVerifier).toBeUndefined();
+  });
+
+  it('the exchange that completes it posts to the live token endpoint with client id B and the stored secret', async () => {
+    const start = makeFakeDb([[confidentialShared()], [], [{ id: 'user-row-1' }]]);
+    await begin(new DbSecretsVaultService(start.db, ENC_KEY));
+    // The callback reads the caller row exactly as the start wrote it.
+    const written = start.captured.values[0];
+    const userRow = sharedRow({ id: 'user-row-1', userId: 'user-1', ...written });
+    const { db } = makeFakeDb([[userRow], undefined]);
+    const fetchMock = vi.fn<(url: unknown, init?: RequestInit) => Promise<Response>>(
+      async () =>
+        new Response(JSON.stringify({ access_token: 'at', refresh_token: 'rt', expires_in: 3600 }), { status: 200 }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await new DbSecretsVaultService(db, ENC_KEY).completeOAuth('user-1', 'user-row-1', 'code', 'https://bevel.example.com/cb');
+
+    expect(String(fetchMock.mock.calls[0][0])).toBe(LIVE.tokenUrl);
+    const body = new URLSearchParams(String(fetchMock.mock.calls[0][1]?.body));
+    expect(body.get('client_id')).toBe('client-B');
+    expect(body.get('client_secret')).toBe('cs-owner');
+    expect(body.get('resource')).toBe(LIVE.resource);
+  });
+
+  it('a later refresh of that grant uses the configuration the consent was given for', async () => {
+    const userRow = sharedRow({
+      id: 'user-row-1',
+      userId: 'user-1',
+      oauthMeta: { ...LIVE },
+      valueEncrypted: crypto.encrypt(
+        JSON.stringify({ clientSecret: 'cs-owner', tokens: { access_token: 'old', refresh_token: 'rt', expires_at: 1_000 } }),
+      ),
+    });
+    const { db } = makeFakeDb([[userRow], undefined]);
+    const fetchMock = vi.fn<(url: unknown, init?: RequestInit) => Promise<Response>>(
+      async () =>
+        new Response(JSON.stringify({ access_token: 'fresh', expires_in: 3600 }), { status: 200 }),
+    );
+    vi.stubGlobal('fetch', fetchMock);
+
+    await expect(
+      new DbSecretsVaultService(db, ENC_KEY, undefined, async () => 'user' as const).resolve('user-1', KEY),
+    ).resolves.toBe('fresh');
+    expect(String(fetchMock.mock.calls[0][0])).toBe(LIVE.tokenUrl);
+    expect(new URLSearchParams(String(fetchMock.mock.calls[0][1]?.body)).get('client_id')).toBe('client-B');
+  });
+
+  it.each([
+    ['an http:// token endpoint', { tokenUrl: 'http://api.example.com/token' }, 'tokenUrl must use https'],
+    ['a loopback token endpoint', { tokenUrl: 'https://127.0.0.1/token' }, 'tokenUrl host is not allowed'],
+    ['a private token endpoint', { tokenUrl: 'https://10.0.0.5/token' }, 'tokenUrl host is not allowed'],
+    ['a link-local authorize endpoint', { authorizationUrl: 'https://169.254.169.254/authorize' }, 'authorizationUrl host is not allowed'],
+  ])('refuses %s with the save’s validation message, writing and sending nothing', async (_name, over, message) => {
+    const { db } = makeFakeDb([[confidentialShared()]]);
+    const fetchMock = vi.fn();
+    vi.stubGlobal('fetch', fetchMock);
+    const err = await begin(new DbSecretsVaultService(db, ENC_KEY), { ...LIVE, ...over }).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(InvalidSecretError);
+    expect((err as Error).message).toBe(message);
+    expect(db.insert).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("refuses with \"owner hasn't finished\" when the shared row holds no secret, whatever it says of itself", async () => {
+    // A row the platform once registered as a public client, under a file that
+    // now declares its own client: the declared client is confidential.
+    const { db } = makeFakeDb([[sharedRow()]]);
+    await expect(begin(new DbSecretsVaultService(db, ENC_KEY))).rejects.toThrow("hasn't finished setting this up");
+    expect(db.insert).not.toHaveBeenCalled();
+  });
+
+  it('keeps the tokens a re-entered sign-in already holds when the declaration is unchanged, key order notwithstanding', async () => {
+    // jsonb does not keep key order: the stored copy reads back reordered.
+    const reordered = Object.fromEntries(Object.entries({ ...LIVE }).reverse());
+    const existing = sharedRow({
+      id: 'user-row-1',
+      userId: 'user-1',
+      oauthMeta: reordered,
+      valueEncrypted: crypto.encrypt(JSON.stringify({ clientSecret: 'cs-owner', tokens: { access_token: 'held' } })),
+    });
+    const { db, captured } = makeFakeDb([[confidentialShared()], [existing], [{ id: 'user-row-1' }]]);
+    await begin(new DbSecretsVaultService(db, ENC_KEY));
+    expect(JSON.parse(crypto.decrypt(captured.values[0].valueEncrypted)).tokens).toEqual({ access_token: 'held' });
+  });
+
+  it('does not carry tokens minted under client A into a sign-in under client B', async () => {
+    const existing = sharedRow({
+      id: 'user-row-1',
+      userId: 'user-1',
+      oauthMeta: SAVED_META,
+      valueEncrypted: crypto.encrypt(JSON.stringify({ clientSecret: 'cs-owner', tokens: { access_token: 'under-A' } })),
+    });
+    const { db, captured } = makeFakeDb([[confidentialShared()], [existing], [{ id: 'user-row-1' }]]);
+    await begin(new DbSecretsVaultService(db, ENC_KEY));
+    expect(JSON.parse(crypto.decrypt(captured.values[0].valueEncrypted)).tokens).toBeUndefined();
+  });
+
+  it('a platform-registered client (no provider handed over) still starts from its stored row', async () => {
+    const { db, captured } = makeFakeDb([[sharedRow()], [], [{ id: 'user-row-1' }]]);
+    const { url } = await new DbSecretsVaultService(db, ENC_KEY).beginToolOAuthByKey({
+      userId: 'user-1',
+      key: KEY,
+      redirectUri: 'https://bevel.example.com/cb',
+      state: 's',
+    });
+    expect(new URL(url).searchParams.get('client_id')).toBe('dcr-client-1');
+    expect(captured.values[0].oauthMeta).toEqual(PUBLIC_META);
+  });
+
+  // The moved property, pinned in both directions: the secret used to be bound to
+  // the token endpoint recorded at its save; it now goes where the file says, and
+  // the move leaves a line naming both origins (never a path) for an operator.
+  describe('where the stored secret goes when the declaration moves the token endpoint', () => {
+    const capture = () => {
+      const lines: Array<{ message: string; fields?: LogFields }> = [];
+      const make = (): ILogger => ({
+        debug: () => {},
+        info: () => {},
+        warn: (message, fields) => void lines.push({ message, fields }),
+        error: () => {},
+        child: () => make(),
+      });
+      const previous = setLogger(make());
+      return { lines, restore: () => setLogger(previous) };
+    };
+
+    it('follows the file to the new endpoint, and says so with both origins', async () => {
+      const log = capture();
+      try {
+        const { db, captured } = makeFakeDb([[confidentialShared()], [], [{ id: 'user-row-1' }]]);
+        await begin(new DbSecretsVaultService(db, ENC_KEY));
+        expect(captured.values[0].oauthMeta.tokenUrl).toBe(LIVE.tokenUrl);
+        expect(JSON.parse(crypto.decrypt(captured.values[0].valueEncrypted)).clientSecret).toBe('cs-owner');
+        expect(log.lines).toEqual([
+          {
+            message: `sign-in on ${KEY}: the declared token endpoint differs from the one recorded when the client secret was saved`,
+            fields: { savedOrigin: 'https://old.example.com', declaredOrigin: 'https://api.example.com' },
+          },
+        ]);
+      } finally {
+        log.restore();
+      }
+    });
+
+    it('says nothing when the declared token endpoint is the one recorded at the save', async () => {
+      const log = capture();
+      try {
+        const { db } = makeFakeDb([[confidentialShared()], [], [{ id: 'user-row-1' }]]);
+        await begin(new DbSecretsVaultService(db, ENC_KEY), { ...LIVE, tokenUrl: SAVED_META.tokenUrl });
+        expect(log.lines).toEqual([]);
+      } finally {
+        log.restore();
+      }
+    });
+  });
+});