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

package/src/modules/secrets-vault/__tests__/managed-sign-in.route.test.ts

@@ -0,0 +1,351 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createSecretsVaultRoutes } from '../secrets-vault.routes.js';
+import type { ManagedSignInPort } from '../secrets-vault.contract.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
+
+/**
+ * The routes' side of a MANAGED sign-in: a sign-in whose `oauth` block names
+ * a connector goes through the distribution's port, unless an owner pinned
+ * the deployment's own app; a workspace connection is a writer's to make;
+ * and the Connect page is told what each row is. Stub services behind a
+ * fake-auth middleware over a loopback server, as the connect-pending suite.
+ */
+type Deps = Parameters<typeof createSecretsVaultRoutes>[0];
+
+const PERSONAL = {
+  slug: 'microsoft365',
+  name: 'microsoft365',
+  path: 'Plugins/Sales/software.bevel.hexis/tools/microsoft365.tool',
+  type: 'inline' as const,
+  variables: [
+    {
+      name: 'ACCESS_TOKEN',
+      scope: 'user' as const,
+      label: 'Microsoft 365 sign-in',
+      oauth: {
+        authorizationUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+        tokenUrl: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+        scopes: ['Mail.Read'],
+        managed: { connectorId: 'microsoft365', scopeSet: 'read' },
+      },
+    },
+  ],
+};
+const SHARED = {
+  ...PERSONAL,
+  slug: 'hubspot',
+  name: 'hubspot',
+  path: 'Plugins/Sales/software.bevel.hexis/tools/hubspot.tool',
+  variables: [
+    {
+      ...PERSONAL.variables[0],
+      scope: 'admin' as const,
+      label: 'HubSpot sign-in',
+      oauth: { ...PERSONAL.variables[0].oauth, scopes: ['crm.objects.contacts.read'], managed: { connectorId: 'hubspot', scopeSet: 'read' } },
+    },
+  ],
+};
+const CARD = {
+  displayName: 'Microsoft 365',
+  icon: 'Mail',
+  description: 'Lets Hexis read your mail.',
+  permissions: ['Read your mail.'],
+  scopeSetLabel: 'Read',
+  dataResidency: 'EU',
+  subprocessor: 'Microsoft',
+};
+
+/** A status row per key, with what each test says the vault holds. */
+type Status = Partial<{
+  userConfigured: boolean;
+  userAuthorized: boolean;
+  grantedScopes: string;
+  userAccount: string;
+  adminConfigured: boolean;
+  adminKind: 'static' | 'oauth' | null;
+  adminAuthorized: boolean;
+  adminGrantedScopes: string;
+  adminAccount: string;
+  adminBringsOwnApp: boolean;
+}>;
+
+/** Every server a test opened; all are closed after it, so a test may serve twice. */
+const servers: HttpServer[] = [];
+
+async function serve(opts: {
+  auth: { userId: string; email: string };
+  manuals?: (typeof PERSONAL)[];
+  status?: Status;
+  canWrite?: boolean;
+  port?: ManagedSignInPort | null;
+}) {
+  const manuals = opts.manuals ?? [PERSONAL];
+  const status = opts.status ?? {};
+  const beginToolOAuthByKey = vi.fn(async () => ({ id: 'row-1', url: 'https://provider.example/authorize?x=1' }));
+  const putSharedOAuthClientSecret = vi.fn(async () => undefined);
+  const secretsVault = {
+    statusFor: async (_userId: string, keys: string[]) =>
+      keys.map((key) => ({ key, adminConfigured: false, adminKind: null, userConfigured: false, userKind: null, ...status })),
+    list: async () => [],
+    beginToolOAuthByKey,
+    putSharedOAuthClientSecret,
+  } as unknown as Deps['secretsVault'];
+  const toolManualService = {
+    listAccessible: async () => manuals,
+    listAccessibleCatalog: async () => ({ tools: manuals, invalid: [] }),
+    liveDeclaration: async (_email: string, slug: string, varName: string) => {
+      const manual = manuals.find((m) => m.slug === slug);
+      const variable = manual?.variables.find((v) => v.name === varName);
+      return manual ? { manual, variable } : null;
+    },
+  } as unknown as Deps['toolManualService'];
+  const accessControl = {
+    canWrite: async () => opts.canWrite ?? false,
+    canRead: async () => true,
+  } as unknown as Deps['accessControl'];
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    req.userId = opts.auth.userId;
+    req.userEmail = opts.auth.email;
+    next();
+  });
+  app.use(
+    '/api',
+    createSecretsVaultRoutes({
+      kb: testKbContext(),
+      secretsVault,
+      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',
+      managedSignIns: () => (opts.port === undefined ? port : opts.port),
+    }),
+  );
+  const httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  servers.push(httpServer);
+  const base = `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+  return { base, beginToolOAuthByKey, putSharedOAuthClientSecret };
+}
+
+/** The distribution's port, available and answering a URL. */
+const start = vi.fn(async () => ({ url: 'https://connect.bevel.test/go?state=abc' }));
+const port: ManagedSignInPort = {
+  available: () => true,
+  describe: () => CARD,
+  start,
+};
+const unavailable: ManagedSignInPort = { ...port, available: () => false };
+/** A broker that is up, for a connector this distribution has no card for. */
+const unknownConnector: ManagedSignInPort = { ...port, describe: () => null };
+
+afterEach(async () => {
+  start.mockClear();
+  for (const s of servers.splice(0)) await new Promise<void>((r) => s.close(() => r()));
+});
+
+const startSignIn = (base: string, slug: string, body?: unknown) =>
+  fetch(`${base}/api/secrets/tools/${slug}/vars/ACCESS_TOKEN/oauth/start`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+
+describe('POST /api/secrets/tools/:slug/vars/:var/oauth/start on a managed sign-in', () => {
+  it('delegates a personal sign-in to the port, with the caller, the vault key and the return path', async () => {
+    const { base, beginToolOAuthByKey } = await serve({ auth: { userId: 'u1', email: 'a@x.com' } });
+    const res = await startSignIn(base, 'microsoft365', { returnTo: '/skills-and-tools/connect' });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ url: 'https://connect.bevel.test/go?state=abc' });
+    expect(start).toHaveBeenCalledWith({
+      userId: 'u1',
+      key: 'microsoft365_ACCESS_TOKEN',
+      ref: { connectorId: 'microsoft365', scopeSet: 'read' },
+      returnTo: '/skills-and-tools/connect',
+    });
+    expect(beginToolOAuthByKey).not.toHaveBeenCalled();
+  });
+
+  it('refuses a connector the distribution does not know, broker or no broker, and never asks the port to start it', async () => {
+    const { base } = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, port: unknownConnector });
+    const res = await startSignIn(base, 'microsoft365', { returnTo: '/skills-and-tools/connect' });
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as { error: string }).error).toMatch(/does not offer the connector/);
+    expect(start).not.toHaveBeenCalled();
+  });
+
+  it('falls back to /connect for an unsafe return path', async () => {
+    const { base } = await serve({ auth: { userId: 'u1', email: 'a@x.com' } });
+    await startSignIn(base, 'microsoft365', { returnTo: 'https://evil.example/' });
+    expect(start).toHaveBeenCalledWith(expect.objectContaining({ returnTo: '/connect' }));
+  });
+
+  it('answers 409 when no broker is reachable, and when no port is wired at all', async () => {
+    const { base } = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, port: unavailable });
+    const res = await startSignIn(base, 'microsoft365');
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as { error: string }).error).toMatch(/not connected to a connector broker/);
+    expect(start).not.toHaveBeenCalled();
+    const none = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, port: null });
+    expect((await startSignIn(none.base, 'microsoft365')).status).toBe(409);
+  });
+
+  it('a workspace connection: a reader is refused with 403, a writer opens it for the workspace (no person)', async () => {
+    const reader = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, manuals: [SHARED], canWrite: false });
+    expect((await startSignIn(reader.base, 'hubspot')).status).toBe(403);
+    expect(start).not.toHaveBeenCalled();
+    const writer = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, manuals: [SHARED], canWrite: true });
+    expect((await startSignIn(writer.base, 'hubspot')).status).toBe(200);
+    expect(start).toHaveBeenCalledWith(expect.objectContaining({ userId: null, key: 'hubspot_ACCESS_TOKEN', ref: { connectorId: 'hubspot', scopeSet: 'read' } }));
+  });
+
+  it('an owner’s own app on a personal sign-in runs the ordinary flow, not the port', async () => {
+    const { base, beginToolOAuthByKey } = await serve({
+      auth: { userId: 'u1', email: 'a@x.com' },
+      status: { adminConfigured: true, adminKind: 'oauth', adminBringsOwnApp: true },
+    });
+    const res = await startSignIn(base, 'microsoft365');
+    expect(res.status).toBe(200);
+    expect(start).not.toHaveBeenCalled();
+    expect(beginToolOAuthByKey).toHaveBeenCalledTimes(1);
+    const url = new URL(((await res.json()) as { url: string }).url);
+    expect(url.origin).toBe('https://provider.example');
+    expect(url.searchParams.get('state')).toMatch(/\./);
+  });
+
+  it('an owner’s own app on a workspace connection is refused with 422: its tokens would land where nobody reads', async () => {
+    const { base, beginToolOAuthByKey } = await serve({
+      auth: { userId: 'u1', email: 'a@x.com' },
+      manuals: [SHARED],
+      canWrite: true,
+      status: { adminConfigured: true, adminKind: 'oauth', adminBringsOwnApp: true },
+    });
+    const res = await startSignIn(base, 'hubspot');
+    expect(res.status).toBe(422);
+    expect(((await res.json()) as { error: string }).error).toMatch(/workspace connection cannot use your own OAuth app/);
+    expect(start).not.toHaveBeenCalled();
+    expect(beginToolOAuthByKey).not.toHaveBeenCalled();
+  });
+
+  it('a tool the caller cannot read is a 404, so a managed sign-in is never started through a name alone', async () => {
+    const { base } = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, manuals: [] });
+    expect((await startSignIn(base, 'microsoft365')).status).toBe(404);
+    expect(start).not.toHaveBeenCalled();
+  });
+});
+
+interface PendingRow {
+  slug: string;
+  authorized: boolean;
+  needsReauth: boolean;
+  ownerConfigured: boolean;
+  ownerOnly: boolean;
+  canWrite?: boolean;
+  managed?: { connectorId: string; tokenScope: string; account: string | null; ownApp: boolean; available: boolean; displayName: string; permissions: string[] };
+}
+
+describe('GET /api/connect/pending with managed sign-ins', () => {
+  const pending = async (base: string) =>
+    ((await (await fetch(`${base}/api/connect/pending`)).json()) as { toolOAuth: PendingRow[] }).toolOAuth;
+
+  it('carries the connector’s card from the port, and a personal sign-in is the caller’s own, broker or no broker', async () => {
+    const { base } = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, port: unavailable });
+    const [row] = await pending(base);
+    expect(row).toMatchObject({
+      slug: 'microsoft365',
+      authorized: false,
+      ownerConfigured: false,
+      ownerOnly: false,
+      canWrite: false,
+      managed: { connectorId: 'microsoft365', tokenScope: 'user', available: false, ownApp: false, displayName: 'Microsoft 365', permissions: ['Read your mail.'] },
+    });
+  });
+
+  it('a stored token counts as configured while the broker is unreachable, with the account the sign-in named', async () => {
+    const { base } = await serve({
+      auth: { userId: 'u1', email: 'a@x.com' },
+      port: unavailable,
+      status: { userConfigured: true, userAuthorized: true, grantedScopes: 'Mail.Read', userAccount: 'alice@acme.example' },
+    });
+    const [row] = await pending(base);
+    expect(row).toMatchObject({ authorized: true, needsReauth: false, ownerConfigured: true, managed: { account: 'alice@acme.example' } });
+  });
+
+  it('a workspace connection is listed for a reader as the owner’s to make, and for a writer as theirs', async () => {
+    const reader = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, manuals: [SHARED], canWrite: false, status: { adminAuthorized: false } });
+    expect((await pending(reader.base))[0]).toMatchObject({ slug: 'hubspot', ownerOnly: true, canWrite: false, managed: { tokenScope: 'shared' } });
+    const writer = await serve({
+      auth: { userId: 'u1', email: 'a@x.com' },
+      manuals: [SHARED],
+      canWrite: true,
+      status: { adminConfigured: true, adminKind: 'oauth', adminAuthorized: true, adminGrantedScopes: 'crm.objects.contacts.read', adminAccount: 'acme.hubspot.com' },
+    });
+    expect((await pending(writer.base))[0]).toMatchObject({ ownerOnly: false, canWrite: true, authorized: true, managed: { account: 'acme.hubspot.com' } });
+  });
+
+  it('without a port the card is bare and the sign-in is listed as waiting on the deployment', async () => {
+    const { base } = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, port: null });
+    const [row] = await pending(base);
+    expect(row.managed).toMatchObject({ displayName: 'Microsoft 365 sign-in', available: false, permissions: [] });
+    expect(row.ownerConfigured).toBe(false);
+  });
+
+  it('a connector the distribution does not know is not startable, though its broker is up', async () => {
+    const { base } = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, port: unknownConnector });
+    const [row] = await pending(base);
+    expect(row.managed).toMatchObject({ displayName: 'Microsoft 365 sign-in', available: false });
+  });
+});
+
+describe('PUT /api/secrets/tools/:slug/vars/:var/oauth/admin on a managed sign-in', () => {
+  const putSecret = (base: string, slug: string, body: unknown) =>
+    fetch(`${base}/api/secrets/tools/${slug}/vars/ACCESS_TOKEN/oauth/admin`, {
+      method: 'PUT',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+
+  it('an owner pins the deployment’s own app: the client id sent with the secret is what the shared row records', async () => {
+    const { base, putSharedOAuthClientSecret } = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, canWrite: true });
+    const res = await putSecret(base, 'microsoft365', { clientSecret: 'own-secret', clientId: ' own-client ' });
+    expect(res.status).toBe(201);
+    expect(putSharedOAuthClientSecret).toHaveBeenCalledWith({
+      key: 'microsoft365_ACCESS_TOKEN',
+      clientSecret: 'own-secret',
+      provider: expect.objectContaining({ clientId: 'own-client', authorizationUrl: PERSONAL.variables[0].oauth.authorizationUrl }),
+    });
+  });
+
+  it('a secret without a client id is refused: the managed app has none, and a pinned row needs its own', async () => {
+    const { base, putSharedOAuthClientSecret } = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, canWrite: true });
+    const res = await putSecret(base, 'microsoft365', { clientSecret: 'own-secret' });
+    expect(res.status).toBe(422);
+    expect(((await res.json()) as { error: string }).error).toMatch(/send its client id with the secret/);
+    expect(putSharedOAuthClientSecret).not.toHaveBeenCalled();
+  });
+
+  it('a reader cannot pin an app on a managed sign-in', async () => {
+    const { base, putSharedOAuthClientSecret } = await serve({ auth: { userId: 'u1', email: 'a@x.com' }, canWrite: false });
+    expect((await putSecret(base, 'microsoft365', { clientSecret: 's', clientId: 'c' })).status).toBe(403);
+    expect(putSharedOAuthClientSecret).not.toHaveBeenCalled();
+  });
+});
+
+describe('GET /api/secrets/tools with a managed sign-in', () => {
+  it('reports the owner row’s kind beside the managed card', async () => {
+    const { base } = await serve({
+      auth: { userId: 'u1', email: 'a@x.com' },
+      status: { adminConfigured: true, adminKind: 'static' },
+    });
+    const body = (await (await fetch(`${base}/api/secrets/tools`)).json()) as {
+      tools: { variables: { adminConfigured: boolean; adminKind: string | null; managed?: { connectorId: string } }[] }[];
+    };
+    expect(body.tools[0].variables[0]).toMatchObject({ adminConfigured: true, adminKind: 'static', managed: { connectorId: 'microsoft365' } });
+  });
+});

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

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.',
     );