@bevel-software/platform-core-backend 0.1.0

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

@@ -0,0 +1,277 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+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.
+ */
+
+// One tool with a mix of scopes; one of its user vars is set, one isn't.
+const toolManualService = {
+  listAccessible: async () => [
+    {
+      slug: 'weather',
+      name: 'weather',
+      path: 'Tools/weather.tool',
+      type: 'http' as const,
+      variables: [
+        { name: 'API_KEY', scope: 'user' as const, label: 'Weather API key' },
+        { name: 'USER_TOKEN', scope: 'user' as const, label: null },
+        { name: 'SHARED_KEY', scope: 'admin' as const, label: 'Org key' },
+      ],
+    },
+  ],
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
+
+const secretsVault = {
+  statusFor: async (_userId: string, keys: string[]) =>
+    keys.map((key) => ({
+      key,
+      adminConfigured: false,
+      userConfigured: key === 'weather_API_KEY', // one set, the other not
+    })),
+  list: async () => [
+    {
+      id: 'oauth-1',
+      key: 'notion_NOTION_TOKEN',
+      kind: 'oauth' as const,
+      label: 'Notion',
+      authorized: false,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    },
+    {
+      id: 'static-1',
+      key: 'weather_API_KEY',
+      kind: 'static' as const,
+      label: null,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    },
+  ],
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
+
+const accessControl = {
+  canWrite: async () => false,
+  canRead: async () => true,
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['accessControl'];
+
+let httpServer: HttpServer | undefined;
+
+async function baseUrlWith(auth: { userId?: string; email?: string }): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    if (auth.userId) req.userId = auth.userId;
+    if (auth.email) req.userEmail = auth.email;
+    next();
+  });
+  app.use(
+    '/api',
+    createSecretsVaultRoutes({
+      secretsVault,
+      toolManualService,
+      accessControl,
+      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;
+  return `http://127.0.0.1:${port}`;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+});
+
+describe('GET /api/connect/pending', () => {
+  it('returns only the caller’s per-user items with set/not-set, plus OAuth secrets', 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 }[];
+    };
+
+    // The admin-scoped SHARED_KEY must NOT appear — only the two user vars.
+    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
+
+    // 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 }]);
+  });
+
+  it('401s an unauthenticated caller', async () => {
+    const base = await baseUrlWith({});
+    const res = await fetch(`${base}/api/connect/pending`);
+    expect(res.status).toBe(401);
+  });
+});
+
+describe('GET /api/connect/pending — OAuth scope coverage', () => {
+  // A tool with an OAuth-backed var that now requires two scopes.
+  const oauthTool = {
+    listAccessible: async () => [
+      {
+        slug: 'google',
+        name: 'google',
+        path: 'Tools/google.tool',
+        type: 'inline' as const,
+        variables: [
+          {
+            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',
+              scopes: ['openid', 'https://www.googleapis.com/auth/calendar.readonly'],
+            },
+          },
+        ],
+      },
+    ],
+  } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
+
+  const vaultWithGranted = (grantedScopes?: string) =>
+    ({
+      statusFor: async (_userId: string, keys: string[]) =>
+        keys.map((key) => ({
+          key,
+          adminConfigured: false,
+          userConfigured: true,
+          userAuthorized: true,
+          grantedScopes,
+        })),
+      list: async () => [],
+    }) as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
+
+  async function pendingWith(grantedScopes?: string) {
+    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: vaultWithGranted(grantedScopes),
+        toolManualService: oauthTool,
+        accessControl,
+        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`);
+    return (await res.json()) as {
+      toolOAuth: { key: string; authorized: boolean; needsReauth: boolean }[];
+    };
+  }
+
+  it('flags needsReauth when the token’s granted scopes under-cover the tool', async () => {
+    const body = await pendingWith('openid'); // missing calendar.readonly
+    const item = body.toolOAuth.find((o) => o.key === 'google_GOOGLE_TOKEN')!;
+    expect(item.authorized).toBe(true);
+    expect(item.needsReauth).toBe(true);
+  });
+
+  it('does not flag needsReauth when the token covers every required scope', async () => {
+    const body = await pendingWith('openid https://www.googleapis.com/auth/calendar.readonly');
+    const item = body.toolOAuth.find((o) => o.key === 'google_GOOGLE_TOKEN')!;
+    expect(item.authorized).toBe(true);
+    expect(item.needsReauth).toBe(false);
+  });
+
+  it('flags needsReauth when granted scopes are unknown (legacy token)', async () => {
+    const body = await pendingWith(undefined);
+    const item = body.toolOAuth.find((o) => o.key === 'google_GOOGLE_TOKEN')!;
+    expect(item.needsReauth).toBe(true);
+  });
+});
+
+describe('GET /api/connect/pending — tool sign-ins are not double-listed as standalone secrets', () => {
+  it('excludes a tool-var-keyed oauth row from the standalone list', async () => {
+    // Authorizing a tool sign-in provisions a per-user oauth row under the
+    // tool-var key — it must render ONCE (as toolOAuth), not again as a
+    // "standalone" secret. A genuinely standalone secret still shows.
+    const oauthTool = {
+      listAccessible: async () => [
+        {
+          slug: 'notion',
+          name: 'notion',
+          path: 'Tools/notion.tool',
+          type: 'mcp' as const,
+          variables: [
+            {
+              name: 'MCP_OAUTH',
+              scope: 'user' as const,
+              label: 'notion sign-in',
+              oauth: { authorizationUrl: 'https://a.example/auth', tokenUrl: 'https://a.example/token', clientId: 'cid' },
+            },
+          ],
+        },
+      ],
+    } 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 })),
+      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() },
+        // A directly-registered secret — must stay.
+        { id: 's-own', key: 'MY_TOKEN', kind: 'oauth' as const, label: 'Mine', authorized: false, createdAt: new Date(), updatedAt: new Date() },
+      ],
+    } as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
+
+    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: vault,
+        toolManualService: oauthTool,
+        accessControl,
+        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 body = (await (await fetch(`http://127.0.0.1:${port}/api/connect/pending`)).json()) as {
+      oauth: { id: string }[];
+      toolOAuth: { key: string }[];
+    };
+
+    expect(body.toolOAuth.map((o) => o.key)).toEqual(['notion_MCP_OAUTH']);
+    expect(body.oauth.map((o) => o.id)).toEqual(['s-own']);
+  });
+});

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

@@ -0,0 +1,206 @@
+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 { TokenCrypto } from '../../../shared/token-crypto.js';
+import type { Database } from '../../database/connection.js';
+
+const ENC_KEY = Buffer.alloc(32, 7).toString('base64');
+const crypto = new TokenCrypto(ENC_KEY);
+
+const KEY = 'notion_MCP_OAUTH';
+const RESOURCE = 'https://mcp.example.com/mcp';
+
+/** PUBLIC-client provider meta, as auto-discovery persists it. */
+const PUBLIC_META = {
+  authorizationUrl: 'https://auth.example.com/authorize',
+  tokenUrl: 'https://auth.example.com/token',
+  clientId: 'dcr-client-1',
+  scopes: ['mcp.read'],
+  authParams: {},
+  pkce: true,
+  publicClient: true,
+  resource: RESOURCE,
+};
+
+/** Fake drizzle chain (same shape as external-api-key.service.test.ts), capturing
+ * `values`/`set` payloads so encrypted blobs can be decrypted and asserted. */
+function makeFakeDb(queue: any[]) {
+  const captured: { values: any[]; set: any[] } = { values: [], set: [] };
+  function nextChain() {
+    const result = queue.shift();
+    const chain: any = {};
+    const passthrough = (recorder?: (args: any[]) => void) =>
+      vi.fn((...args: any[]) => {
+        recorder?.(args);
+        return chain;
+      });
+    chain.values = passthrough((a) => captured.values.push(a[0]));
+    chain.set = passthrough((a) => captured.set.push(a[0]));
+    chain.where = passthrough();
+    chain.limit = passthrough();
+    chain.from = passthrough();
+    chain.returning = passthrough();
+    chain.onConflictDoUpdate = passthrough();
+    chain.then = (onF: any, onR: any) => Promise.resolve(result).then(onF, onR);
+    return chain;
+  }
+  const db = {
+    insert: vi.fn(() => nextChain()),
+    select: vi.fn(() => nextChain()),
+    update: vi.fn(() => nextChain()),
+    delete: vi.fn(() => nextChain()),
+  } as unknown as Database;
+  return { db, captured };
+}
+
+function sharedRow(over: Partial<Record<string, unknown>> = {}) {
+  return {
+    id: 'shared-1',
+    userId: null,
+    key: KEY,
+    kind: 'oauth',
+    label: 'notion sign-in',
+    valueEncrypted: crypto.encrypt(JSON.stringify({})), // no clientSecret — public client
+    oauthMeta: PUBLIC_META,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+    ...over,
+  };
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('DbSecretsVaultService — PKCE + public-client tool OAuth', () => {
+  it('beginToolOAuthByKey works for a secret-less PUBLIC client and adds PKCE + resource', async () => {
+    const { db, captured } = makeFakeDb([
+      [sharedRow()], // shared row lookup
+      [], // no existing user row
+      [{ id: 'user-row-1' }], // provisioned row
+    ]);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+
+    const { id, url } = await svc.beginToolOAuthByKey({
+      userId: 'user-1',
+      key: KEY,
+      redirectUri: 'https://bevel.example.com/api/secrets/oauth/callback',
+      state: 'signed-state',
+    });
+
+    expect(id).toBe('user-row-1');
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get('code_challenge_method')).toBe('S256');
+    expect(parsed.searchParams.get('resource')).toBe(RESOURCE);
+    expect(parsed.searchParams.get('client_id')).toBe('dcr-client-1');
+
+    // The challenge in the URL must be S256(verifier stored on the row).
+    const blob = JSON.parse(crypto.decrypt(captured.values[0].valueEncrypted));
+    expect(typeof blob.pendingVerifier).toBe('string');
+    const expectedChallenge = createHash('sha256').update(blob.pendingVerifier).digest('base64url');
+    expect(parsed.searchParams.get('code_challenge')).toBe(expectedChallenge);
+  });
+
+  it('still refuses a CONFIDENTIAL client whose owner has not set the secret', async () => {
+    const meta = { ...PUBLIC_META, pkce: false, publicClient: false };
+    const { db } = makeFakeDb([[sharedRow({ oauthMeta: meta })]]);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+    await expect(
+      svc.beginToolOAuthByKey({
+        userId: 'user-1',
+        key: KEY,
+        redirectUri: 'https://bevel.example.com/cb',
+        state: 's',
+      }),
+    ).rejects.toBeInstanceOf(SecretOAuthError);
+  });
+
+  it('completeOAuth sends the PKCE verifier + resource and drops the verifier after the exchange', async () => {
+    const userRow = sharedRow({
+      id: 'user-row-1',
+      userId: 'user-1',
+      valueEncrypted: crypto.encrypt(JSON.stringify({ pendingVerifier: 'the-verifier' })),
+    });
+    const { db, captured } = makeFakeDb([
+      [userRow], // requireRow
+      undefined, // token persist update
+    ]);
+    const svc = new DbSecretsVaultService(db, ENC_KEY);
+
+    let tokenBody: URLSearchParams | null = null;
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (_url: unknown, init?: RequestInit) => {
+        tokenBody = new URLSearchParams(String(init?.body));
+        return new Response(
+          JSON.stringify({ access_token: 'at-1', refresh_token: 'rt-1', expires_in: 3600, scope: 'mcp.read' }),
+          { status: 200, headers: { 'Content-Type': 'application/json' } },
+        );
+      }),
+    );
+
+    await svc.completeOAuth('user-1', 'user-row-1', 'the-code', 'https://bevel.example.com/cb');
+
+    expect(tokenBody!.get('code_verifier')).toBe('the-verifier');
+    expect(tokenBody!.get('resource')).toBe(RESOURCE);
+    expect(tokenBody!.get('client_secret')).toBeNull(); // public client — PKCE only
+
+    // Verifier is one-time: the persisted blob carries tokens but no verifier.
+    const stored = JSON.parse(crypto.decrypt(captured.set[0].valueEncrypted));
+    expect(stored.tokens.access_token).toBe('at-1');
+    expect(stored.pendingVerifier).toBeUndefined();
+  });
+});
+
+describe('DbSecretsVaultService — dead-grant detection on refresh', () => {
+  const expiredTokens = {
+    access_token: 'stale-at',
+    refresh_token: 'dead-rt',
+    expires_at: 1_000, // long past
+    scope: 'mcp.read',
+  };
+  const userRow = () =>
+    sharedRow({
+      id: 'user-row-1',
+      userId: 'user-1',
+      valueEncrypted: crypto.encrypt(JSON.stringify({ tokens: expiredTokens })),
+    });
+  const userScope = async () => 'user' as const;
+
+  it('a definitive 400/401 refresh rejection wipes the token set and resolves null', async () => {
+    const { db, captured } = makeFakeDb([
+      [userRow()], // resolve row lookup
+      undefined, // wipe update
+    ]);
+    const svc = new DbSecretsVaultService(db, ENC_KEY, undefined, userScope);
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () => new Response(JSON.stringify({ error: 'invalid_grant' }), { status: 400 })),
+    );
+
+    await expect(svc.resolve('user-1', KEY)).resolves.toBeNull();
+
+    // The persisted blob keeps the client secret slot but no tokens — so
+    // statusFor reports not-authorized and every fail-closed surface (pre-call
+    // check, /connect, listing filter) routes the user to re-authorize.
+    const stored = JSON.parse(crypto.decrypt(captured.set[0].valueEncrypted));
+    expect(stored.tokens).toBeUndefined();
+  });
+
+  it('a transient failure (network / 5xx) keeps the tokens and returns the stale one', async () => {
+    for (const impl of [
+      async () => new Response('bad gateway', { status: 502 }),
+      async () => {
+        throw new TypeError('fetch failed');
+      },
+    ]) {
+      const { db, captured } = makeFakeDb([[userRow()]]);
+      const svc = new DbSecretsVaultService(db, ENC_KEY, undefined, userScope);
+      vi.stubGlobal('fetch', vi.fn(impl));
+
+      await expect(svc.resolve('user-1', KEY)).resolves.toBe('stale-at');
+      expect(captured.set).toEqual([]); // nothing wiped
+    }
+  });
+});

package/src/modules/secrets-vault/__tests__/mcp-oauth-discovery.service.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, it, vi } from 'vitest';
+import { McpOAuthDiscoveryService } from '../mcp-oauth-discovery.service.js';
+import type { ISecretsVaultService, OAuthProviderConfig } from '../secrets-vault.contract.js';
+
+const MCP_URL = 'https://mcp.example.com/mcp';
+const REDIRECT_URI = 'https://bevel.example.com/api/secrets/oauth/callback';
+
+const PRM_URL = 'https://mcp.example.com/.well-known/oauth-protected-resource/mcp';
+const AS_META_URL = 'https://auth.example.com/.well-known/oauth-authorization-server';
+
+const PRM = {
+  resource: MCP_URL,
+  authorization_servers: ['https://auth.example.com'],
+  scopes_supported: ['mcp.read'],
+};
+const AS_META = {
+  issuer: 'https://auth.example.com',
+  authorization_endpoint: 'https://auth.example.com/authorize',
+  token_endpoint: 'https://auth.example.com/token',
+  registration_endpoint: 'https://auth.example.com/register',
+};
+
+function json(body: unknown, status = 200, headers?: Record<string, string>) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json', ...headers },
+  });
+}
+
+/** Route-table fetch: each URL maps to a responder; unrouted URLs 404. */
+function makeFetch(routes: Record<string, (init?: RequestInit) => Response>) {
+  const calls: string[] = [];
+  const fetchFn = (async (url: unknown, init?: RequestInit) => {
+    const key = String(url);
+    calls.push(key);
+    const handler = routes[key];
+    return handler ? handler(init) : new Response('not found', { status: 404 });
+  }) as typeof fetch;
+  return { fetchFn, calls };
+}
+
+function makeVault(existing: OAuthProviderConfig | null = null) {
+  return {
+    getSharedOAuthProvider: vi.fn(async () => existing),
+    putSharedOAuthProvider: vi.fn(async () => {}),
+  } as unknown as ISecretsVaultService & {
+    getSharedOAuthProvider: ReturnType<typeof vi.fn>;
+    putSharedOAuthProvider: ReturnType<typeof vi.fn>;
+  };
+}
+
+function makeService(
+  vault: ReturnType<typeof makeVault>,
+  fetchFn: typeof fetch,
+  now?: () => number,
+) {
+  return new McpOAuthDiscoveryService({ secretsVault: vault, redirectUri: REDIRECT_URI, fetchFn, now });
+}
+
+describe('McpOAuthDiscoveryService', () => {
+  it('reports open when the server answers the probe without a 401', async () => {
+    const vault = makeVault();
+    const { fetchFn } = makeFetch({ [MCP_URL]: () => json({ ok: true }) });
+    const res = await makeService(vault, fetchFn).statusFor('notion', MCP_URL);
+    expect(res).toEqual({ status: 'open' });
+    expect(vault.putSharedOAuthProvider).not.toHaveBeenCalled();
+  });
+
+  it('treats a 200 initialize as needing auth when the server publishes PRM (Google gmail/calendar)', async () => {
+    // Google's MCP servers answer an unauthenticated `initialize` with 200 but
+    // still require OAuth for tool calls, advertised via the well-known PRM doc.
+    const vault = makeVault();
+    const { fetchFn } = makeFetch({
+      [MCP_URL]: () => json({ ok: true }), // 200, no WWW-Authenticate
+      [PRM_URL]: () => json(PRM), // path-aware well-known PRM exists
+      [AS_META_URL]: () => json(AS_META),
+      ['https://auth.example.com/register']: () => json({ client_id: 'dcr-g' }, 201),
+    });
+    const res = await makeService(vault, fetchFn).statusFor('gmail', MCP_URL);
+    expect(res.status).toBe('oauth');
+    expect(vault.putSharedOAuthProvider).toHaveBeenCalled();
+  });
+
+  it('walks 401 → resource metadata → AS metadata → DCR and persists a public PKCE client', async () => {
+    const vault = makeVault();
+    let registration: Record<string, unknown> | null = null;
+    const { fetchFn } = makeFetch({
+      [MCP_URL]: () =>
+        json({ error: 'unauthorized' }, 401, {
+          'WWW-Authenticate': `Bearer resource_metadata="${PRM_URL}"`,
+        }),
+      [PRM_URL]: () => json(PRM),
+      [AS_META_URL]: () => json(AS_META),
+      ['https://auth.example.com/register']: (init) => {
+        registration = JSON.parse(String(init?.body));
+        return json({ client_id: 'dcr-client-1' }, 201);
+      },
+    });
+
+    const res = await makeService(vault, fetchFn).statusFor('notion', MCP_URL);
+
+    expect(res.status).toBe('oauth');
+    if (res.status !== 'oauth') return;
+    expect(res.provider).toMatchObject({
+      authorizationUrl: 'https://auth.example.com/authorize',
+      tokenUrl: 'https://auth.example.com/token',
+      clientId: 'dcr-client-1',
+      pkce: true,
+      publicClient: true,
+      resource: MCP_URL,
+      scopes: ['mcp.read'],
+    });
+    // Registered as a PUBLIC client against OUR callback.
+    expect(registration).toMatchObject({
+      redirect_uris: [REDIRECT_URI],
+      token_endpoint_auth_method: 'none',
+      grant_types: ['authorization_code', 'refresh_token'],
+    });
+    // Persisted under the synthetic key so the standard tool-OAuth flow can run.
+    expect(vault.putSharedOAuthProvider).toHaveBeenCalledWith(
+      expect.objectContaining({
+        key: 'notion_MCP_OAUTH',
+        provider: expect.objectContaining({ clientId: 'dcr-client-1', pkce: true }),
+      }),
+    );
+  });
+
+  it('falls back to the well-known PRM path when the 401 carries no resource_metadata', async () => {
+    const vault = makeVault();
+    const { fetchFn } = makeFetch({
+      [MCP_URL]: () => json({}, 401),
+      [PRM_URL]: () => json(PRM), // path-aware well-known location
+      [AS_META_URL]: () => json(AS_META),
+      ['https://auth.example.com/register']: () => json({ client_id: 'dcr-client-2' }, 201),
+    });
+    const res = await makeService(vault, fetchFn).statusFor('notion', MCP_URL);
+    expect(res.status).toBe('oauth');
+  });
+
+  it('reports unsupported when the AS offers no dynamic client registration', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const vault = makeVault();
+    const { fetchFn } = makeFetch({
+      [MCP_URL]: () => json({}, 401),
+      [PRM_URL]: () => json(PRM),
+      [AS_META_URL]: () => json({ ...AS_META, registration_endpoint: undefined }),
+    });
+    const res = await makeService(vault, fetchFn).statusFor('notion', MCP_URL);
+    expect(res.status).toBe('unsupported');
+    expect(vault.putSharedOAuthProvider).not.toHaveBeenCalled();
+    warn.mockRestore();
+  });
+
+  it('short-circuits on an already-persisted registration — never re-registers a client', async () => {
+    const existing: OAuthProviderConfig = {
+      authorizationUrl: 'https://auth.example.com/authorize',
+      tokenUrl: 'https://auth.example.com/token',
+      clientId: 'previously-registered',
+      pkce: true,
+      publicClient: true,
+    };
+    const vault = makeVault(existing);
+    const { fetchFn, calls } = makeFetch({});
+    const res = await makeService(vault, fetchFn).statusFor('notion', MCP_URL);
+    expect(res).toEqual({ status: 'oauth', provider: existing });
+    expect(calls).toEqual([]); // no network at all
+  });
+
+  it('caches results — a second lookup makes no further requests', async () => {
+    const vault = makeVault();
+    const { fetchFn, calls } = makeFetch({ [MCP_URL]: () => json({ ok: true }) });
+    const svc = makeService(vault, fetchFn);
+    await svc.statusFor('notion', MCP_URL);
+    const afterFirst = calls.length;
+    await svc.statusFor('notion', MCP_URL);
+    expect(calls.length).toBe(afterFirst);
+  });
+});