@bevel-software/platform-core-backend 0.12.1 → 0.13.3

package/src/modules/kb-fs/__tests__/repo-path.test.ts

@@ -0,0 +1,106 @@
+import { describe, it, expect } from 'vitest';
+import { assertInsideRepo, isInsideRepo } from '../repo-path.js';
+import { WorkflowValidationError } from '../../../shared/domain-errors.js';
+
+const KB = 'knowledge-base';
+
+describe('isInsideRepo', () => {
+  it('accepts the repository folder and anything under it', () => {
+    expect(isInsideRepo('knowledge-base', KB)).toBe(true);
+    expect(isInsideRepo('knowledge-base/KnowledgeBase/Foo.md', KB)).toBe(true);
+    expect(isInsideRepo('knowledge-base/roles.yaml', KB)).toBe(true);
+  });
+
+  it('refuses a repo-relative path: it would land beside the repository, where git never looks', () => {
+    expect(isInsideRepo('KnowledgeBase/Reviews/PR-12.html', KB)).toBe(false);
+    expect(isInsideRepo('review.log', KB)).toBe(false);
+    expect(isInsideRepo('tmp/spill.txt', KB)).toBe(false);
+  });
+
+  it('matches the folder as a whole segment, not as a string prefix', () => {
+    expect(isInsideRepo('knowledge-based/x.md', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base-old/x.md', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base.bak', KB)).toBe(false);
+  });
+
+  it('refuses traversal that starts under the prefix and climbs back out', () => {
+    // `knowledge-base/../stray.md` starts with the clone folder but resolves
+    // beside it: the containment check is against the WORKSPACE dir, so the
+    // filesystem would accept it and the bytes would land outside git.
+    expect(isInsideRepo('knowledge-base/../stray.md', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base/KnowledgeBase/../../stray.md', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base/./x.md', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base//x.md', KB)).toBe(false);
+  });
+
+  it('refuses backslashes anywhere: on Windows they separate segments too, and the commit layer rejects them', () => {
+    expect(isInsideRepo('knowledge-base/foo\\..\\..\\outside.md', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base\\KnowledgeBase\\x.md', KB)).toBe(false);
+    expect(isInsideRepo('knowledge-base/KnowledgeBase/a\\b.md', KB)).toBe(false);
+  });
+
+  it('tolerates a trailing slash on a directory path', () => {
+    expect(isInsideRepo('knowledge-base/', KB)).toBe(true);
+    expect(isInsideRepo('knowledge-base/KnowledgeBase/Projects/', KB)).toBe(true);
+  });
+
+  it('refuses dressed-up forms of the prefix that the commit layer would reject anyway', () => {
+    expect(isInsideRepo('./knowledge-base/x.md', KB)).toBe(false);
+    expect(isInsideRepo('/knowledge-base/x.md', KB)).toBe(false);
+    expect(isInsideRepo('', KB)).toBe(false);
+  });
+});
+
+describe('assertInsideRepo', () => {
+  it('passes silently for a path inside the repository', () => {
+    expect(() => assertInsideRepo('knowledge-base/KnowledgeBase/Foo.md', KB)).not.toThrow();
+  });
+
+  it('throws a 400 that names the prefix and spells out the corrected path', () => {
+    let err: unknown;
+    try {
+      assertInsideRepo('KnowledgeBase/Reviews/PR-12.html', KB);
+    } catch (e) {
+      err = e;
+    }
+    expect(err).toBeInstanceOf(WorkflowValidationError);
+    const e = err as WorkflowValidationError;
+    expect(e.status).toBe(400);
+    // The offending path, the rule, and the exact path to use instead: an
+    // agent reading this error can retry without guessing.
+    expect(e.message).toContain('"KnowledgeBase/Reviews/PR-12.html"');
+    expect(e.message).toContain('"knowledge-base/"');
+    expect(e.message).toContain('"knowledge-base/KnowledgeBase/Reviews/PR-12.html"');
+    expect(e.payload).toMatchObject({
+      kind: 'path-outside-repo',
+      path: 'KnowledgeBase/Reviews/PR-12.html',
+      kbDirName: KB,
+      // On its own as well: the pending-commits worker's notice reads it from
+      // here, because the message it keeps is truncated.
+      corrected: 'knowledge-base/KnowledgeBase/Reviews/PR-12.html',
+    });
+  });
+
+  it('suggests the path with the traversal collapsed, back under the prefix', () => {
+    expect(() => assertInsideRepo('knowledge-base/../stray.md', KB)).toThrow('"knowledge-base/stray.md"');
+    expect(() => assertInsideRepo('knowledge-base/../../escape.md', KB)).toThrow('"knowledge-base/escape.md"');
+  });
+
+  it('suggests a forward-slash path for a backslash one', () => {
+    expect(() => assertInsideRepo('knowledge-base/foo\\..\\..\\outside.md', KB)).toThrow('"knowledge-base/outside.md"');
+    expect(() => assertInsideRepo('KnowledgeBase\\Reviews\\PR-12.html', KB)).toThrow('"knowledge-base/KnowledgeBase/Reviews/PR-12.html"');
+  });
+
+  it('never suggests a path that still climbs: a bare `..` corrects to the repository folder', () => {
+    for (const p of ['..', '../', '../..', '../../', 'knowledge-base/..']) {
+      let message = '';
+      try {
+        assertInsideRepo(p, KB);
+      } catch (e) {
+        message = (e as Error).message;
+      }
+      expect(message, p).toContain('Use "knowledge-base/" instead');
+      expect(message, p).not.toMatch(/Use "[^"]*\.\.[^"]*" instead/);
+    }
+  });
+});

package/src/modules/kb-fs/locking-filesystem.ts

@@ -44,6 +44,7 @@ import {
 import type { AuthUser, Change, IWorkflowService } from '@bevel-software/platform-shared';
 import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
 import type { FileChangeNotifier } from './file-change-notifier.js';
+import { assertInsideRepo } from './repo-path.js';
 import type { CreationGrantPlan, ICreatorAccess } from '../access-model/creator.js';
 
 /** How many times to retry a contended acquire before giving up. */
@@ -62,6 +63,16 @@ export interface LockingFilesystemContext {
   workspaceId: string;
   branch: string;
   user: AuthUser;
+  /**
+   * The clone folder at the workspace root (`knowledge-base`). The filesystem
+   * is rooted one level ABOVE the repository, so containment alone lets a
+   * repo-relative path (`KnowledgeBase/…`) land beside the clone, where git
+   * never sees it and the release commit quietly no-ops. Every op that
+   * creates or modifies bytes is refused unless its path starts with this
+   * folder; removals stay open so a stray the old behaviour left there can
+   * still be cleaned up.
+   */
+  kbDirName: string;
   /**
    * Optional pre-disk write validator. Invoked with the (workspace-relative
    * path, full content) of every WHOLE-FILE write BEFORE the bytes land. Throw
@@ -104,6 +115,7 @@ export class LockingFilesystem extends LocalFilesystem {
     content: FileContent,
     options?: WriteOptions,
   ): Promise<void> {
+    this.assertInsideRepo(inputPath);
     // Pre-disk gate (e.g. reject a roles.yaml edit that would lock out admins).
     // Runs OUTSIDE the lock so a refusal never acquires/holds one.
     this.lockContext.validateWrite?.(inputPath, content);
@@ -121,6 +133,7 @@ export class LockingFilesystem extends LocalFilesystem {
   }
 
   override async appendFile(inputPath: string, content: FileContent): Promise<void> {
+    this.assertInsideRepo(inputPath);
     return this.withLock(inputPath, () => super.appendFile(inputPath, content));
   }
 
@@ -129,12 +142,16 @@ export class LockingFilesystem extends LocalFilesystem {
   }
 
   override async copyFile(src: string, dest: string, options?: CopyOptions): Promise<void> {
+    this.assertInsideRepo(dest);
     // Lock on `dest`. `src` is read-only from this op's perspective — copy
     // creates a new file at dest without disturbing src on disk.
     return this.withLock(dest, () => super.copyFile(src, dest, options));
   }
 
   override async moveFile(src: string, dest: string, options?: CopyOptions): Promise<void> {
+    // Only the destination is gated: moving a stray INTO the repository is how
+    // a file the old behaviour left beside the clone gets rescued.
+    this.assertInsideRepo(dest);
     // A move mutates two paths: the source is deleted and the destination
     // is created. Only locking `dest` would let a concurrent writer hold
     // the source's lock and mutate it under us, and would also leave the
@@ -183,6 +200,9 @@ export class LockingFilesystem extends LocalFilesystem {
     deletes: string[] = [],
   ): Promise<Change | null> {
     const { workflow, workspaceId, branch, user } = this.lockContext;
+    // Fail the whole batch before any plan, validator or lock: one stray path
+    // must not let its siblings land while it silently misses git.
+    for (const w of writes) this.assertInsideRepo(w.path);
     // Creator read grants for the batch: transform new markdown files'
     // content in place, and fold any subtree access.md seeds into the SAME
     // atomic batch (deduped — several files landing in one new folder share
@@ -479,6 +499,7 @@ export class LockingFilesystem extends LocalFilesystem {
   }
 
   override async mkdir(inputPath: string, options?: { recursive?: boolean }): Promise<void> {
+    this.assertInsideRepo(inputPath);
     // Creator read grant: planned BEFORE the dir exists (the plan's
     // new-directory detection needs the pre-creation tree), seeded right
     // after — so the new folder's access.md names the acting user under
@@ -527,6 +548,15 @@ export class LockingFilesystem extends LocalFilesystem {
     );
   }
 
+  /**
+   * Refuse a path that would put bytes beside the repository instead of in
+   * it. Runs before any side effect (plan, validator, lock, disk) so a refusal
+   * leaves nothing behind. See `LockingFilesystemContext.kbDirName`.
+   */
+  private assertInsideRepo(inputPath: string): void {
+    assertInsideRepo(inputPath, this.lockContext.kbDirName);
+  }
+
   /**
    * Land a `seed-access-md` creation-grant plan: under the access.md's own
    * lock (single acquire+release cycle → one commit), re-read the CURRENT

package/src/modules/kb-fs/repo-path.ts

@@ -0,0 +1,56 @@
+import path from 'node:path';
+import { WorkflowValidationError } from '../../shared/domain-errors.js';
+
+/**
+ * Workspace-relative paths and the repository folder.
+ *
+ * A workspace directory holds the git clone as `<kbDirName>/` (plus transient
+ * scratch such as `tmp/`). The agent filesystem, the lock keys and the human
+ * editor all speak WORKSPACE-relative paths, so a path reaches git only when
+ * it starts with that folder. `KnowledgeBase/Foo.md` on its own is not a
+ * shorthand for `knowledge-base/KnowledgeBase/Foo.md`: it is a different
+ * location, beside the clone, that nothing commits and nothing pushes.
+ */
+
+/**
+ * True when `wsPath` is the repository folder or lies under it.
+ *
+ * Judged segment by segment, not by string prefix: `knowledge-base/../x.md`
+ * starts with the folder yet resolves beside it, and the filesystem's own
+ * containment is against the WORKSPACE dir, so it would accept that path.
+ * `.` and `..` segments (and empty ones from `//`) are therefore refused
+ * outright, and so is any backslash: on Windows it separates segments too,
+ * so `foo\..\..` would climb the same way. Both match what the commit layer
+ * accepts. A single trailing slash on a directory path is tolerated.
+ */
+export function isInsideRepo(wsPath: string, kbDirName: string): boolean {
+  if (typeof wsPath !== 'string' || wsPath.includes('\\')) return false;
+  const segments = wsPath.replace(/\/$/, '').split('/');
+  if (segments[0] !== kbDirName) return false;
+  return segments.every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+}
+
+/**
+ * Refuse a workspace-relative path that would land outside the repository.
+ * The message carries the corrected path so an agent can retry without
+ * guessing; the payload carries a typed discriminator for callers that
+ * switch on it, plus the same corrected path on its own, for a consumer
+ * that cannot rely on the message surviving intact (the pending-commits
+ * worker stores a sanitized, truncated copy).
+ */
+export function assertInsideRepo(wsPath: string, kbDirName: string): void {
+  if (isInsideRepo(wsPath, kbDirName)) return;
+  // The suggestion collapses what made the path wrong: backslashes, leading
+  // `./` or `/`, and any `..` climbing back out (a bare `..` included, so the
+  // suggestion is never itself a climb). The agent gets a path it can use.
+  const normalized = path.posix
+    .normalize(String(wsPath).replace(/\\/g, '/').replace(/^(\.\/|\/)+/, ''))
+    .replace(/^(\.\.(\/|$))+/, '')
+    .replace(/^\.$/, '');
+  const corrected = isInsideRepo(normalized, kbDirName) ? normalized : `${kbDirName}/${normalized}`;
+  throw new WorkflowValidationError(
+    `"${wsPath}" is outside the knowledge base repository: paths are workspace-relative, must start with "${kbDirName}/" and may not contain "." or ".." segments or backslashes. ` +
+      `Use "${corrected}" instead. A file written without that prefix lands beside the repository, where it is never committed or pushed.`,
+    { kind: 'path-outside-repo', path: wsPath, kbDirName, corrected },
+  );
+}

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

@@ -151,6 +151,96 @@ describe('DbSecretsVaultService — PKCE + public-client tool OAuth', () => {
     expect(stored.tokens.access_token).toBe('at-1');
     expect(stored.pendingVerifier).toBeUndefined();
   });
+
+  it('beginToolOAuthByKey remembers the scopes it asked for, and completeOAuth takes them as granted when the provider echoes none', async () => {
+    // RFC 6749 §5.1: `scope` in the token response is OPTIONAL when identical
+    // to what was requested. A provider that omits it (HubSpot) granted the
+    // request, not nothing — reading it as nothing would flag every declared
+    // scope as missing and block the tool behind a permanent "sign in again".
+    const begin = makeFakeDb([[sharedRow()], [], [{ id: 'user-row-1' }]]);
+    const svc = new DbSecretsVaultService(begin.db, ENC_KEY);
+    const { url } = await svc.beginToolOAuthByKey({
+      userId: 'user-1',
+      key: KEY,
+      redirectUri: 'https://bevel.example.com/cb',
+      state: 's',
+      scopes: ['crm.objects.contacts.read', 'crm.objects.companies.read'],
+    });
+    expect(new URL(url).searchParams.get('scope')).toBe('crm.objects.contacts.read crm.objects.companies.read');
+    const pending = JSON.parse(crypto.decrypt(begin.captured.values[0].valueEncrypted));
+    expect(pending.pendingScopes).toBe('crm.objects.contacts.read crm.objects.companies.read');
+
+    const complete = async (tokenResponse: Record<string, unknown>) => {
+      const userRow = sharedRow({
+        id: 'user-row-1',
+        userId: 'user-1',
+        valueEncrypted: crypto.encrypt(
+          JSON.stringify({ pendingVerifier: 'v', pendingScopes: 'crm.objects.contacts.read crm.objects.companies.read' }),
+        ),
+      });
+      const { db, captured } = makeFakeDb([[userRow], undefined]);
+      vi.stubGlobal(
+        'fetch',
+        vi.fn(async () => new Response(JSON.stringify(tokenResponse), { status: 200, headers: { 'Content-Type': 'application/json' } })),
+      );
+      await new DbSecretsVaultService(db, ENC_KEY).completeOAuth('user-1', 'user-row-1', 'code', 'https://bevel.example.com/cb');
+      return JSON.parse(crypto.decrypt(captured.set[0].valueEncrypted));
+    };
+
+    // No `scope` echoed → the requested scopes are the granted ones.
+    const silent = await complete({ access_token: 'at-1', expires_in: 3600 });
+    expect(silent.tokens.scope).toBe('crm.objects.contacts.read crm.objects.companies.read');
+    expect(silent.pendingScopes).toBeUndefined(); // one-time, like the verifier
+    // An echoed `scope` is the provider's word and wins — a narrower grant stays visible.
+    const echoed = await complete({ access_token: 'at-2', expires_in: 3600, scope: 'crm.objects.contacts.read' });
+    expect(echoed.tokens.scope).toBe('crm.objects.contacts.read');
+    // …and so does an EXPLICIT empty grant: only an absent field means "as requested".
+    const empty = await complete({ access_token: 'at-3', expires_in: 3600, scope: '' });
+    expect(empty.tokens.scope).toBe('');
+  });
+
+  it('beginOAuth never writes a stale blob over tokens a concurrent refresh just rotated', async () => {
+    // The standalone flow stashes the pending verifier/scopes with a
+    // read-modify-write. Between its read and its write a refresh persists
+    // rotated tokens; the guarded update misses (0 rows), the row is re-read,
+    // and the pending fields are merged onto THOSE tokens.
+    const stale = sharedRow({
+      id: 'secret-1',
+      userId: 'user-1',
+      oauthMeta: { ...PUBLIC_META, pkce: false },
+      valueEncrypted: crypto.encrypt(JSON.stringify({ tokens: { access_token: 'old', refresh_token: 'rt-old' } })),
+    });
+    const rotated = {
+      ...stale,
+      valueEncrypted: crypto.encrypt(JSON.stringify({ tokens: { access_token: 'new', refresh_token: 'rt-new' } })),
+    };
+    const { db, captured } = makeFakeDb([
+      [stale], // requireRow
+      [], // guarded update: the ciphertext changed underneath us
+      [rotated], // re-read
+      [{ id: 'secret-1' }], // guarded update against the fresh ciphertext
+    ]);
+    const url = await new DbSecretsVaultService(db, ENC_KEY).beginOAuth('user-1', 'secret-1', 'https://bevel.example.com/cb', 's');
+    expect(new URL(url).searchParams.get('scope')).toBe('mcp.read');
+    expect(captured.set).toHaveLength(2);
+    const persisted = JSON.parse(crypto.decrypt(captured.set[1].valueEncrypted));
+    expect(persisted.tokens).toEqual({ access_token: 'new', refresh_token: 'rt-new' });
+    expect(persisted.pendingScopes).toBe('mcp.read');
+
+    // Only a token rotation is merge-able: a row that meanwhile became another
+    // provider's sign-in (or a static value) aborts, since the consent URL was
+    // built for the provider we read first.
+    for (const changed of [
+      { ...rotated, oauthMeta: { ...PUBLIC_META, pkce: false, clientId: 'someone-else' } },
+      { ...rotated, kind: 'static' },
+    ]) {
+      const race = makeFakeDb([[stale], [], [changed]]);
+      await expect(
+        new DbSecretsVaultService(race.db, ENC_KEY).beginOAuth('user-1', 'secret-1', 'https://bevel.example.com/cb', 's'),
+      ).rejects.toBeInstanceOf(SecretOAuthError);
+      expect(race.captured.set).toHaveLength(1); // nothing written onto the changed row
+    }
+  });
 });
 
 describe('DbSecretsVaultService — dead-grant detection on refresh', () => {
@@ -210,6 +300,20 @@ describe('DbSecretsVaultService — dead-grant detection on refresh', () => {
     expect(onMutation).toHaveBeenCalledWith('user-1');
   });
 
+  it('a refresh keeps the recorded grant when `scope` is absent, and takes an echoed one — empty included', async () => {
+    // Same rule as the code exchange: only an ABSENT field means "unchanged".
+    const refreshWith = async (body: Record<string, unknown>) => {
+      const { db, captured } = makeFakeDb([[userRow()], undefined]);
+      const svc = new DbSecretsVaultService(db, ENC_KEY, undefined, userScope);
+      vi.stubGlobal('fetch', vi.fn(async () => new Response(JSON.stringify(body), { status: 200 })));
+      await svc.resolve('user-1', KEY);
+      return JSON.parse(crypto.decrypt(captured.set[0].valueEncrypted)).tokens.scope;
+    };
+    expect(await refreshWith({ access_token: 'a', expires_in: 3600 })).toBe('mcp.read');
+    expect(await refreshWith({ access_token: 'a', expires_in: 3600, scope: 'mcp.read mcp.write' })).toBe('mcp.read mcp.write');
+    expect(await refreshWith({ access_token: 'a', expires_in: 3600, scope: '' })).toBe('');
+  });
+
   it('putSharedOAuthProvider notifies mutation listeners with null (shared → everyone)', async () => {
     const { db } = makeFakeDb([undefined]); // provider upsert
     const svc = new DbSecretsVaultService(db, ENC_KEY);

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

@@ -147,10 +147,62 @@ describe('McpOAuthDiscoveryService', () => {
     });
     const res = await makeService(vault, fetchFn).statusFor('notion', MCP_URL);
     expect(res.status).toBe('unsupported');
+    // The reason is the admin's to-do list: it names the redirect URI to
+    // register and where the client id goes, because that is the next step.
+    expect(res).toMatchObject({ reason: expect.stringContaining(REDIRECT_URI) });
+    expect(res).toMatchObject({ reason: expect.stringContaining('client id') });
     expect(vault.putSharedOAuthProvider).not.toHaveBeenCalled();
     warn.mockRestore();
   });
 
+  it('completes an owner-declared client from the server metadata — no registration, nothing persisted', async () => {
+    const vault = makeVault();
+    const { fetchFn, calls } = makeFetch({
+      [MCP_URL]: () => json({}, 401),
+      [PRM_URL]: () => json(PRM),
+      [AS_META_URL]: () => json({ ...AS_META, registration_endpoint: undefined }),
+    });
+    const svc = makeService(vault, fetchFn);
+    const res = await svc.providerForDeclaredClient('hubspot', MCP_URL, 'owner-app-1');
+    expect(res).toEqual({
+      status: 'oauth',
+      provider: {
+        authorizationUrl: 'https://auth.example.com/authorize',
+        tokenUrl: 'https://auth.example.com/token',
+        clientId: 'owner-app-1',
+        scopes: ['mcp.read'],
+        pkce: true,
+        resource: MCP_URL,
+      },
+    });
+    expect(calls).not.toContain('https://auth.example.com/register');
+    expect(vault.putSharedOAuthProvider).not.toHaveBeenCalled();
+    // The metadata walk is per server, so a second declared client on the
+    // same URL costs no network — and gets ITS client id, not the first one's.
+    const before = calls.length;
+    const again = await svc.providerForDeclaredClient('hubspot_eu', MCP_URL, 'owner-app-2');
+    expect(again).toMatchObject({ status: 'oauth', provider: { clientId: 'owner-app-2' } });
+    expect(calls.length).toBe(before);
+  });
+
+  it('refuses to complete a declared client when the server is open or publishes no metadata', async () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const open = makeService(makeVault(), makeFetch({ [MCP_URL]: () => json({ ok: true }) }).fetchFn);
+    expect(await open.providerForDeclaredClient('x', MCP_URL, 'c')).toMatchObject({
+      status: 'unsupported',
+      reason: expect.stringContaining('authorizationUrl'),
+    });
+    const noMeta = makeService(
+      makeVault(),
+      makeFetch({ [MCP_URL]: () => json({}, 401), [PRM_URL]: () => json(PRM) }).fetchFn,
+    );
+    expect(await noMeta.providerForDeclaredClient('x', MCP_URL, 'c')).toMatchObject({
+      status: 'unsupported',
+      reason: expect.stringContaining('no authorization-server metadata'),
+    });
+    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',

package/src/modules/secrets-vault/__tests__/tool-owner-gate.route.test.ts

@@ -25,6 +25,7 @@ const toolManualService = {
       name: 'weather',
       path: TOOL_PATH,
       type: 'mcp' as const,
+      setup: { kind: 'oauth-manual' as const, reason: 'no authorization-server metadata at https://weather.example' },
       variables: [
         { name: 'SHARED_KEY', scope: 'admin' as const, label: 'Org key' },
         {
@@ -37,6 +38,19 @@ const toolManualService = {
             clientId: 'client-1',
           },
         },
+        {
+          name: 'LEGACY',
+          scope: 'user' as const,
+          oauth: {
+            authorizationUrl: 'https://auth.example.com/authorize',
+            tokenUrl: 'https://auth.example.com/token',
+            clientId: 'client-2',
+            pkce: false,
+            resource: 'https://weather.example/mcp',
+          },
+        },
+        // Declared by client id alone, and discovery could NOT fill the endpoints in.
+        { name: 'BYO', scope: 'user' as const, oauth: { clientId: 'owner-app' } },
       ],
     },
   ],
@@ -125,11 +139,44 @@ describe('tool owner gate — shared config requires WRITE on the `.tool` file',
       expect.objectContaining({
         key: 'weather_SIGNIN',
         clientSecret: 'cs-123',
-        provider: expect.objectContaining({ clientId: 'client-1' }),
+        // PKCE rides along by default — the MCP spec requires it and a
+        // provider without it ignores the parameters. No `resource` declared.
+        provider: expect.objectContaining({ clientId: 'client-1', pkce: true, resource: undefined }),
       }),
     );
   });
 
+  it('pins the declaration\'s PKCE opt-out and resource indicator with the secret', async () => {
+    const base = await baseUrlAs(WRITER);
+    const res = await fetch(`${base}/api/secrets/tools/weather/vars/LEGACY/oauth/admin`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ clientSecret: 'cs-456' }),
+    });
+    expect(res.status).toBe(201);
+    expect(putSharedOAuthClientSecret).toHaveBeenCalledWith(
+      expect.objectContaining({
+        key: 'weather_LEGACY',
+        provider: expect.objectContaining({ clientId: 'client-2', pkce: false, resource: 'https://weather.example/mcp' }),
+      }),
+    );
+  });
+
+  it('refuses the secret while the sign-in endpoints are still unknown, naming why (422)', async () => {
+    const base = await baseUrlAs(WRITER);
+    const res = await fetch(`${base}/api/secrets/tools/weather/vars/BYO/oauth/admin`, {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ clientSecret: 'cs-789' }),
+    });
+    expect(res.status).toBe(422);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain('no authorization-server metadata at https://weather.example');
+    // Pinning a provider with no endpoints would make every later sign-in
+    // fail with a far vaguer error than this one.
+    expect(putSharedOAuthClientSecret).not.toHaveBeenCalled();
+  });
+
   it('a non-writer cannot set the client secret (403)', async () => {
     const base = await baseUrlAs(READER);
     const res = await fetch(`${base}/api/secrets/tools/weather/vars/SIGNIN/oauth/admin`, {

package/src/modules/secrets-vault/db-secrets-vault.service.ts

@@ -34,10 +34,13 @@ interface OAuthTokenSet {
   expires_at?: number;
   token_type?: string;
   /**
-   * Space-delimited scopes the provider actually granted (echoed on the token
-   * response). The durable record of what this token can do, so a later check can
-   * tell whether it still covers a tool whose required scopes have grown. Absent
-   * on tokens minted before this was captured (treated as "covers nothing").
+   * Space-delimited scopes the provider actually granted. The durable record of
+   * what this token can do, so a later check can tell whether it still covers a
+   * tool whose required scopes have grown. Taken from the token response's
+   * `scope` when echoed; when the provider stays silent, RFC 6749 §5.1 says the
+   * grant is identical to the request, so the scopes asked for at `begin*` time
+   * are recorded instead. Absent only on tokens minted before this was captured
+   * (treated as "covers nothing").
    */
   scope?: string;
 }
@@ -51,6 +54,13 @@ interface OAuthBlob {
    * it's a one-time secret binding the pending consent to this server.
    */
   pendingVerifier?: string;
+  /**
+   * The space-delimited `scope` the pending consent asked for — what the
+   * token is deemed granted when the provider's token response echoes none
+   * (RFC 6749 §5.1: `scope` is optional when identical to the request). One-time
+   * like the verifier: consumed by the exchange it was minted for.
+   */
+  pendingScopes?: string;
 }
 
 /**
@@ -281,16 +291,39 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     // PKCE (S256): same as the tool path — mint the verifier, stash it on the
     // row (so `completeOAuth` echoes it at the token exchange), and put only
     // the derived challenge in the consent URL. A provider registered pkce
-    // would otherwise fail the exchange from this standalone flow.
-    let pendingVerifier: string | undefined;
-    if (meta.pkce) {
-      pendingVerifier = randomBytes(32).toString('base64url');
-      const blob = this.readBlob(row.valueEncrypted);
-      const next: OAuthBlob = { ...blob, pendingVerifier };
-      await this.db
-        .update(secrets)
-        .set({ valueEncrypted: this.crypto().encrypt(JSON.stringify(next)), updatedAt: new Date() })
-        .where(and(eq(secrets.id, id), eq(secrets.userId, userId)));
+    // would otherwise fail the exchange from this standalone flow. The
+    // requested scopes ride along for the same exchange (see `pendingScopes`).
+    const pendingVerifier = meta.pkce ? randomBytes(32).toString('base64url') : undefined;
+    const pendingScopes = meta.scopes && meta.scopes.length ? meta.scopes.join(' ') : undefined;
+    if (pendingVerifier || pendingScopes) {
+      // Read-modify-write on the blob, guarded on the ciphertext we read: a
+      // refresh running concurrently (the row is a live credential) may have
+      // persisted ROTATED tokens in between, and writing our copy over them
+      // would leave the row holding a dead refresh token if this consent is
+      // then abandoned. On a miss (0 rows), re-read and merge onto the fresh
+      // blob; bounded so a row that keeps changing fails loudly, not forever.
+      let current = row;
+      for (let attempt = 0; ; attempt++) {
+        const blob = this.readBlob(current.valueEncrypted);
+        const next: OAuthBlob = { ...blob, pendingVerifier, pendingScopes };
+        const written = await this.db
+          .update(secrets)
+          .set({ valueEncrypted: this.crypto().encrypt(JSON.stringify(next)), updatedAt: new Date() })
+          .where(
+            and(eq(secrets.id, id), eq(secrets.userId, userId), eq(secrets.valueEncrypted, current.valueEncrypted)),
+          )
+          .returning({ id: secrets.id });
+        if (!Array.isArray(written) || written.length > 0) break;
+        if (attempt >= 2) throw new SecretOAuthError('The sign-in changed while starting — try again');
+        current = await this.requireRow(userId, id);
+        // Only a token rotation is merge-able. A row that is no longer this
+        // OAuth secret — re-registered against another provider, or replaced by
+        // a static value — would have the consent URL built above pointing at
+        // one provider and the pending fields stashed for another.
+        if (current.kind !== 'oauth' || JSON.stringify(current.oauthMeta) !== JSON.stringify(row.oauthMeta)) {
+          throw new SecretOAuthError('The sign-in changed while starting — try again');
+        }
+      }
     }
 
     const url = new URL(meta.authorizationUrl);
@@ -340,7 +373,14 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     if (meta.resource) body.set('resource', meta.resource);
 
     const tokens = await this.tokenRequest(meta.tokenUrl, body);
-    // The verifier is one-time — never carried past the exchange it was minted for.
+    // A silent token response granted what was asked (RFC 6749 §5.1) — record
+    // the request as the grant, or every declared scope would read as missing
+    // and the sign-in would be flagged "again" forever. An echoed `scope` is
+    // the provider's own word and wins — narrower grants included, and so does
+    // an explicit empty one: only an ABSENT field means "as requested".
+    if (tokens.scope === undefined && blob.pendingScopes) tokens.scope = blob.pendingScopes;
+    // The verifier and the requested scopes are one-time — never carried past
+    // the exchange they were minted for.
     const next: OAuthBlob = { clientSecret: blob.clientSecret, tokens };
     await this.db
       .update(secrets)
@@ -433,11 +473,22 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     // only the derived challenge in the consent URL. `completeOAuth` echoes the
     // verifier at the token exchange and drops it.
     const pendingVerifier = meta.pkce ? randomBytes(32).toString('base64url') : undefined;
+    // The scopes this consent asks for: the caller may override from the live
+    // tool file (`input.scopes`) so an owner adding a permission takes effect
+    // without re-setting the secret. Remembered on the row so a token response
+    // that echoes no `scope` is read as granting exactly this (RFC 6749 §5.1).
+    const requestedScopes = input.scopes && input.scopes.length ? input.scopes : meta.scopes;
+    const pendingScopes = requestedScopes && requestedScopes.length ? requestedScopes.join(' ') : undefined;
 
     // Provision (or reset) the caller's own oauth row for this key from the shared
     // provider meta + secret, preserving any existing tokens. Keyed `<manual>_<VAR>`
     // so `resolve` (scope 'user') returns the token once sign-in completes.
-    const blob: OAuthBlob = { clientSecret: sharedBlob.clientSecret, tokens: existingTokens, pendingVerifier };
+    const blob: OAuthBlob = {
+      clientSecret: sharedBlob.clientSecret,
+      tokens: existingTokens,
+      pendingVerifier,
+      pendingScopes,
+    };
     const valueEncrypted = this.crypto().encrypt(JSON.stringify(blob));
     const [row] = await this.db
       .insert(secrets)
@@ -449,10 +500,8 @@ export class DbSecretsVaultService implements ISecretsVaultService {
       .returning();
 
     // Build the consent URL exactly as beginOAuth does, from the stored meta —
-    // EXCEPT the requested scopes, which the caller may override from the live tool
-    // file (`input.scopes`) so an owner adding a permission takes effect without
-    // re-setting the secret. Client id, addresses, and secret stay owner-pinned.
-    const requestedScopes = input.scopes && input.scopes.length ? input.scopes : meta.scopes;
+    // EXCEPT the requested scopes (above). Client id, addresses, and secret
+    // stay owner-pinned.
     const url = new URL(meta.authorizationUrl);
     url.searchParams.set('response_type', 'code');
     url.searchParams.set('client_id', meta.clientId);
@@ -572,8 +621,10 @@ export class DbSecretsVaultService implements ISecretsVaultService {
     // Some providers omit the refresh_token on refresh — keep the old one.
     if (!refreshed.refresh_token) refreshed.refresh_token = tokens.refresh_token;
     // Likewise, a refresh response often omits `scope` — keep the granted scopes
-    // recorded at sign-in so coverage checks don't regress to "unknown".
-    if (!refreshed.scope) refreshed.scope = tokens.scope;
+    // recorded at sign-in so coverage checks don't regress to "unknown". Same
+    // rule as the exchange: only an ABSENT field means "unchanged"; an echoed
+    // value, empty included, is the provider's word.
+    if (refreshed.scope === undefined) refreshed.scope = tokens.scope;
     const next: OAuthBlob = { clientSecret: blob.clientSecret, tokens: refreshed };
 
     // Optimistic concurrency: only persist if the stored ciphertext is unchanged,