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

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();
+      }
+    });
+  });
+});

package/src/modules/secrets-vault/__tests__/oauth-live-declaration.route.test.ts

@@ -0,0 +1,218 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createSecretsVaultRoutes, InvalidSecretError, SecretOAuthError } from '../index.js';
+import type { ToolManualSummary, ToolVariable } from '../../tool-manuals/index.js';
+
+/**
+ * The tool-scoped sign-in start follows the tool file as it reads NOW
+ * (`liveDeclaration`), not the catalog's cached scan and not the copy the
+ * owner's client-secret save stored. A client the platform registered itself
+ * (oauth-auto) is described by no file and still starts from its stored row.
+ *
+ * The incident: the GTM plugin's HubSpot connector was replaced, the file got
+ * the new client id, the new secret was saved — and every sign-in still asked
+ * for consent under the old client id.
+ */
+
+const USER = 'owner@x.com';
+const ENDPOINTS = {
+  authorizationUrl: 'https://app.hubspot.example/oauth/authorize',
+  tokenUrl: 'https://api.hubspot.example/oauth/v1/token',
+};
+
+const manual = (variables: ToolVariable[], setup?: ToolManualSummary['setup']): ToolManualSummary => ({
+  slug: 'hubspot',
+  name: 'hubspot',
+  path: 'Plugins/GTM/.claude-plugin/plugin.json',
+  type: 'mcp',
+  variables,
+  ...(setup ? { setup } : {}),
+});
+const signIn = (oauth?: ToolVariable['oauth']): ToolVariable => ({
+  name: 'HUBSPOT_TOKEN',
+  scope: 'user',
+  ...(oauth ? { oauth } : {}),
+});
+
+let httpServer: HttpServer | undefined;
+afterEach(async () => {
+  await new Promise<void>((r) => (httpServer ? httpServer.close(() => r()) : r()));
+  httpServer = undefined;
+});
+
+/** One server whose catalog says `catalog` and whose file says `live`. */
+async function serve(opts: {
+  catalog: ToolManualSummary[];
+  live: { manual: ToolManualSummary; variable?: ToolVariable } | null;
+  begin?: (input: Record<string, unknown>) => Promise<{ id: string; url: string }>;
+  canWrite?: boolean;
+  varName?: string;
+  /** The live read fails outright (the workspace cannot be opened) instead of answering. */
+  liveError?: Error;
+}) {
+  const beginToolOAuthByKey = vi.fn(
+    opts.begin ?? (async () => ({ id: 'row-1', url: 'https://app.hubspot.example/oauth/authorize?client_id=x' })),
+  );
+  const putSharedOAuthClientSecret = vi.fn(async () => {});
+  const liveDeclaration = vi.fn(async () => {
+    if (opts.liveError) throw opts.liveError;
+    return opts.live;
+  });
+  const deps = {
+    secretsVault: { beginToolOAuthByKey, putSharedOAuthClientSecret },
+    toolManualService: { listAccessible: async () => opts.catalog, liveDeclaration },
+    accessControl: { canRead: async () => true, canWrite: async () => opts.canWrite ?? false },
+    connectionProbe: {},
+    kb: { defaultWorkspaceId: () => 'main' },
+    stateSecret: 'state-secret',
+    publicBackendUrl: 'http://localhost:3000',
+    publicFrontendUrl: 'http://localhost:5173',
+  } as unknown as Parameters<typeof createSecretsVaultRoutes>[0];
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userId = 'user-1';
+    req.userEmail = USER;
+    next();
+  });
+  app.use('/api', createSecretsVaultRoutes(deps));
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const base = `http://127.0.0.1:${(httpServer.address() as { port: number }).port}/api/secrets/tools/hubspot/vars/${opts.varName ?? 'HUBSPOT_TOKEN'}`;
+  return {
+    beginToolOAuthByKey,
+    putSharedOAuthClientSecret,
+    liveDeclaration,
+    start: () => fetch(`${base}/oauth/start`, { method: 'POST' }),
+    saveSecret: () =>
+      fetch(`${base}/oauth/admin`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ clientSecret: 'cs' }),
+      }),
+  };
+}
+
+describe('POST …/oauth/start — a declared sign-in follows the live declaration', () => {
+  it('hands the vault the file’s client id, endpoints, PKCE and resource, even when the catalog still says otherwise', async () => {
+    const stale = manual([signIn({ clientId: 'client-A', ...ENDPOINTS })], { kind: 'oauth-manual' });
+    const fresh = manual([signIn({ clientId: 'client-B', ...ENDPOINTS, scopes: ['crm.read'], resource: 'https://mcp.hubspot.example/' })], {
+      kind: 'oauth-manual',
+    });
+    const s = await serve({ catalog: [stale], live: { manual: fresh, variable: fresh.variables![0] } });
+
+    const res = await s.start();
+    expect(res.status).toBe(200);
+    expect(s.liveDeclaration).toHaveBeenCalledWith(USER, 'hubspot', 'HUBSPOT_TOKEN');
+    expect(s.beginToolOAuthByKey).toHaveBeenCalledWith(
+      expect.objectContaining({
+        key: 'hubspot_HUBSPOT_TOKEN',
+        scopes: ['crm.read'],
+        provider: {
+          ...ENDPOINTS,
+          clientId: 'client-B',
+          scopes: ['crm.read'],
+          authParams: undefined,
+          pkce: true,
+          resource: 'https://mcp.hubspot.example/',
+        },
+      }),
+    );
+  });
+
+  it('a declaration opting out of PKCE is handed over as such', async () => {
+    const fresh = manual([signIn({ clientId: 'client-B', ...ENDPOINTS, pkce: false })]);
+    const s = await serve({ catalog: [fresh], live: { manual: fresh, variable: fresh.variables![0] } });
+    expect((await s.start()).status).toBe(200);
+    expect(s.beginToolOAuthByKey.mock.calls[0][0]).toMatchObject({ provider: { pkce: false } });
+  });
+
+  it('refuses a declaration whose endpoints could not be discovered with the discovery reason — the save’s own wording', async () => {
+    const reason = 'no authorization-server metadata at https://mcp.hubspot.example';
+    const stuck = manual([signIn({ clientId: 'client-B' })], { kind: 'oauth-manual', reason });
+    const s = await serve({ catalog: [stuck], live: { manual: stuck, variable: stuck.variables![0] }, canWrite: true });
+
+    const res = await s.start();
+    expect(res.status).toBe(422);
+    const { error } = (await res.json()) as { error: string };
+    expect(error).toBe(`The sign-in endpoints for this server aren't known yet: ${reason}.`);
+    expect(s.beginToolOAuthByKey).not.toHaveBeenCalled();
+
+    const saved = await s.saveSecret();
+    expect(saved.status).toBe(422);
+    expect(((await saved.json()) as { error: string }).error).toBe(error);
+  });
+
+  it('refuses with "owner hasn’t finished" when the oauth block was removed from the file, never using the stored row', async () => {
+    const stale = manual([signIn({ clientId: 'client-A', ...ENDPOINTS })], { kind: 'oauth-manual' });
+    const fresh = manual([signIn()]);
+    const s = await serve({ catalog: [stale], live: { manual: fresh, variable: fresh.variables![0] } });
+
+    const res = await s.start();
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as { error: string }).error).toBe("This tool's owner hasn't finished setting this up");
+    expect(s.beginToolOAuthByKey).not.toHaveBeenCalled();
+  });
+
+  it('passes on the vault’s refusals: a missing secret, and an endpoint that fails validation', async () => {
+    const fresh = manual([signIn({ clientId: 'client-B', ...ENDPOINTS, tokenUrl: 'http://127.0.0.1/token' })]);
+    const refusing = await serve({
+      catalog: [fresh],
+      live: { manual: fresh, variable: fresh.variables![0] },
+      begin: async () => {
+        throw new InvalidSecretError('tokenUrl must use https');
+      },
+    });
+    const invalid = await refusing.start();
+    expect(invalid.status).toBe(422);
+    expect(((await invalid.json()) as { error: string }).error).toBe('tokenUrl must use https');
+    await new Promise<void>((r) => httpServer!.close(() => r()));
+
+    const unset = await serve({
+      catalog: [fresh],
+      live: { manual: fresh, variable: fresh.variables![0] },
+      begin: async () => {
+        throw new SecretOAuthError("This tool's owner hasn't finished setting this up");
+      },
+    });
+    const res = await unset.start();
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as { error: string }).error).toBe("This tool's owner hasn't finished setting this up");
+  });
+
+  it('a platform-registered sign-in (oauth-auto) starts from its stored row: no provider is handed over', async () => {
+    const auto = manual(
+      [{ name: 'MCP_OAUTH', scope: 'user', oauth: { clientId: 'dcr-1', ...ENDPOINTS } }],
+      { kind: 'oauth-auto' },
+    );
+    // The file declares no such variable: the catalog's discovery synthesised it.
+    const s = await serve({ catalog: [auto], live: { manual: manual([]) }, varName: 'MCP_OAUTH' });
+    expect((await s.start()).status).toBe(200);
+    const input = s.beginToolOAuthByKey.mock.calls[0][0];
+    expect(input).toMatchObject({ key: 'hubspot_MCP_OAUTH' });
+    expect(input.provider).toBeUndefined();
+  });
+
+  it('answers 404 when neither the file nor the catalog knows the tool', async () => {
+    const s = await serve({ catalog: [], live: null });
+    expect((await s.start()).status).toBe(404);
+    expect(s.beginToolOAuthByKey).not.toHaveBeenCalled();
+  });
+
+  it('answers 500 when the tool files cannot be read, never a misconfiguration verdict from the catalog', async () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    // The catalog still holds a declared sign-in; a live read that fails must
+    // not fall back to it and answer "owner hasn't finished" (409) or "not
+    // found" (404) for what is a server fault.
+    const stale = manual([signIn({ clientId: 'client-A', ...ENDPOINTS })], { kind: 'oauth-manual' });
+    const s = await serve({ catalog: [stale], live: null, liveError: new Error('workspace unavailable') });
+
+    const res = await s.start();
+    expect(res.status).toBe(500);
+    expect(((await res.json()) as { error: string }).error).toBe('Internal error');
+    expect(s.beginToolOAuthByKey).not.toHaveBeenCalled();
+    error.mockRestore();
+  });
+});