@bevel-software/platform-core-backend 0.12.0 → 0.13.1

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/clone-config.ts

@@ -1,6 +1,13 @@
 /**
- * The git configuration a per-branch workspace clone must have for its branch
- * to track exactly ONE upstream ref.
+ * The git configuration a per-branch workspace clone must carry: the tracking
+ * config that pins its branch to exactly ONE upstream ref, and the credential
+ * helper its remote operations authenticate with.
+ *
+ * Both are stamped at clone time AND re-stamped when an existing clone is
+ * adopted from disk, so a clone created by an older build — or by a path that
+ * only authenticated its own invocation — is repaired rather than left broken.
+ *
+ * On the tracking half:
  *
  * Why this exists: a clone's config is append-only from git's point of view,
  * and several things write to it:
@@ -69,3 +76,91 @@ export function cloneTrackingConfigArgs(branch: string): string[][] {
     ['config', '--replace-all', `branch.${branch}.merge`, `refs/heads/${branch}`],
   ];
 }
+
+/**
+ * The inline credential helper a workspace clone authenticates its remote
+ * operations with, or null when the deployment has no git token configured.
+ *
+ * The snippet reads `$GITHUB_TOKEN` at CALL time, so the secret itself never
+ * enters argv, the clone's `.git/config`, or any error message quoting either.
+ * `GITHUB_TOKEN` is the normalised name — `CoreConfig` collapses `GIT_TOKEN` /
+ * `GH_TOKEN` onto it at boot, and `DeploymentSettingsService.syncGitTokenEnv`
+ * publishes a token supplied through the setup screen to the same place — so
+ * this one name covers every way a token can arrive.
+ *
+ * The username is provider-specific (GitHub `x-access-token`, GitLab `oauth2`,
+ * Bitbucket `x-token-auth`); the token is always the Basic-auth password,
+ * which every major host accepts.
+ */
+export function credentialHelperValue(gitUsername: string): string | null {
+  if (!process.env.GITHUB_TOKEN) return null;
+  // Interpolated into a shell snippet that git will execute. `CoreConfig` and
+  // `DeploymentSettingsService` both reject a username outside this charset
+  // before it can get this far, so reaching the throw means an unvalidated
+  // fourth path appeared — fail closed rather than emit an injectable helper.
+  if (!/^[A-Za-z0-9._-]+$/.test(gitUsername)) {
+    throw new Error(`git username must match [A-Za-z0-9._-]+; got "${gitUsername}"`);
+  }
+  // printf '%s' rather than echo: POSIX leaves echo's handling of backslash
+  // escapes implementation-defined (dash interprets \c as "stop output"), so
+  // a token containing a backslash sequence could be silently truncated on
+  // the way to git. printf %s passes the bytes through verbatim. The literal
+  // `password=$GITHUB_TOKEN` stays in the snippet, which is what
+  // APP_HELPER_VALUE_PATTERN keys on — echo-era helpers stamped by earlier
+  // builds still match it and get replaced on the next stamp.
+  return `!f() { printf '%s\\n' "username=${gitUsername}" "password=$GITHUB_TOKEN"; }; f`;
+}
+
+/**
+ * `git clone` arguments that PERSIST the credential helper into the repository
+ * being created. Position is load-bearing: these belong AFTER the `clone`
+ * subcommand, where `--config` means "write this into the new repo's config".
+ * The same pair placed BEFORE it is git's per-invocation `-c`, which
+ * authenticates that one clone and leaves the resulting repo with no helper at
+ * all — so every later `git push` from that clone prompts for a username,
+ * finds no tty, and dies. That was a real outage: a self-hosted deployment
+ * cloned fine, committed fine, and silently pushed nothing for two days.
+ *
+ * Empty when no token is configured, matching the un-authenticated clone the
+ * rest of the layer already supports.
+ */
+export function cloneCredentialArgs(gitUsername: string): string[] {
+  const helper = credentialHelperValue(gitUsername);
+  return helper ? ['--config', `credential.helper=${helper}`] : [];
+}
+
+/**
+ * `git` argument lists that bring a clone's credential helper into line with
+ * the deployment's current config — the repair path for clones on disk (see
+ * `cloneCredentialArgs`), applied wherever `cloneTrackingConfigArgs` is:
+ * `--replace-all` when a token is configured (idempotent re-stamp, stale
+ * values collapse), `--unset-all` when the deployment lost its token (a
+ * leftover helper answering with an empty password must not shadow whatever
+ * auth the operator fell back to; unset of a missing value exits non-zero
+ * and callers tolerate it — see `stampCredentialHelper`). Both operations
+ * are scoped by the value pattern below so only app-owned helpers are
+ * touched. Returns the arguments rather than running them, for the same
+ * reason `cloneTrackingConfigArgs` does.
+ */
+/**
+ * Value pattern (a POSIX ERE, as `git config`'s optional value-pattern
+ * argument expects) that matches ONLY helpers this application stamped —
+ * every one of ours reads `password=$GITHUB_TOKEN`, and no operator-authored
+ * helper has a reason to contain that literal. Scoping both the replace and
+ * the unset to it means an operator's own clone-local helper (`store`,
+ * `cache`, something custom) is never collapsed away or deleted by our
+ * stamping: git chains all configured helpers in order, so ours and theirs
+ * coexist.
+ */
+const APP_HELPER_VALUE_PATTERN = 'password=\\$GITHUB_TOKEN';
+
+export function cloneCredentialConfigArgs(gitUsername: string): string[][] {
+  const helper = credentialHelperValue(gitUsername);
+  // `--replace-all key value pattern` replaces every line MATCHING the
+  // pattern with the one value (adding it when none match) and leaves
+  // non-matching values — operator helpers — untouched. Same scoping on the
+  // unset: only app-stamped values are removed when the token goes away.
+  return helper
+    ? [['config', '--replace-all', 'credential.helper', helper, APP_HELPER_VALUE_PATTERN]]
+    : [['config', '--unset-all', 'credential.helper', APP_HELPER_VALUE_PATTERN]];
+}

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`, {