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

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

@@ -231,8 +231,8 @@ describe('a line break in a path — one name to the gates, two object names to
   });
 
   it('refuses it through normalizePathArgs, which is where the MCP tools meet the rule', () => {
-    expect(() => normalizePathArgs({ path: INJECTED }, KB)).toThrow(/control character/);
-    expect(() => normalizePathArgs({ files: [{ path: INJECTED }] }, KB)).toThrow(/control character/);
+    expect(() => normalizePathArgs({ path: INJECTED }, KB, { tool: 'read_file' })).toThrow(/control character/);
+    expect(() => normalizePathArgs({ files: [{ path: INJECTED }] }, KB, { tool: 'read_file' })).toThrow(/control character/);
   });
 });
 
@@ -360,6 +360,8 @@ describe('assertRepoRootNameFree', () => {
 });
 
 describe('normalizePathArgs', () => {
+  const T = { tool: 'read_file' };
+
   it('normalizes every path-shaped tool argument, batch entries included', () => {
     expect(
       normalizePathArgs(
@@ -372,6 +374,7 @@ describe('normalizePathArgs', () => {
           files: [{ path: 'e.md', content: '/x' }],
         },
         KB,
+        T,
       ),
     ).toEqual({
       branch: '/main',
@@ -385,22 +388,64 @@ describe('normalizePathArgs', () => {
 
   it('leaves a spill ref alone — it belongs to no workspace', () => {
     expect(
-      normalizePathArgs({ path: '__tool_chain_spill__/abc.json' }, KB, (v) => v.startsWith('__tool_chain_spill__/')),
+      normalizePathArgs({ path: '__tool_chain_spill__/abc.json' }, KB, { tool: 'read_file', skip: (v) => v.startsWith('__tool_chain_spill__/') }),
     ).toEqual({ path: '__tool_chain_spill__/abc.json' });
   });
 
+  it('still takes the earlier call form, a skip predicate or nothing, and refuses a tmp ref in every input there', () => {
+    const spill = (v: string) => v.startsWith('__tool_chain_spill__/');
+    expect(normalizePathArgs({ path: '__tool_chain_spill__/abc.json' }, KB, spill)).toEqual({ path: '__tool_chain_spill__/abc.json' });
+    expect(normalizePathArgs({ path: 'a.md' }, KB)).toEqual({ path: 'knowledge-base/a.md' });
+    for (const legacy of [undefined, spill]) {
+      expect(() => normalizePathArgs({ path: '__tmp__/x.md' }, KB, legacy)).toThrow(/this tool does not take one there/);
+    }
+  });
+
   it('leaves an absent or empty path to the handler\'s own required-argument message', () => {
-    expect(normalizePathArgs({ path: undefined }, KB)).toEqual({ path: undefined });
-    expect(normalizePathArgs({ path: '' }, KB)).toEqual({ path: '' });
-    expect(normalizePathArgs({ branch: 'main' }, KB)).toEqual({ branch: 'main' });
+    expect(normalizePathArgs({ path: undefined }, KB, T)).toEqual({ path: undefined });
+    expect(normalizePathArgs({ path: '' }, KB, T)).toEqual({ path: '' });
+    expect(normalizePathArgs({ branch: 'main' }, KB, T)).toEqual({ branch: 'main' });
   });
 
   it('collapses the spellings so two callers take one lock row', () => {
-    expect(normalizePathArgs({ path: './knowledge-base//a.md' }, KB)).toEqual({ path: 'knowledge-base/a.md' });
+    expect(normalizePathArgs({ path: './knowledge-base//a.md' }, KB, T)).toEqual({ path: 'knowledge-base/a.md' });
+  });
+
+  it('admits a tmp ref, as written, in exactly the inputs the tool names', () => {
+    expect(normalizePathArgs({ src: '__tmp__/a.pdf', dest: 'a.pdf' }, KB, { tool: 'copy_file', tmpRefInputs: ['src'] })).toEqual({
+      src: '__tmp__/a.pdf',
+      dest: 'knowledge-base/a.pdf',
+    });
+  });
+
+  it('refuses a tmp ref in every other input, lists included, naming the tool and copy_file', () => {
+    const calls: Array<Record<string, unknown>> = [
+      { path: '__tmp__/a.md' },
+      { src: '__tmp__/a.md' },
+      { dest: '__tmp__/a.md' },
+      { destination: '__tmp__' },
+      { files: [{ path: 'ok.md' }, { path: '__tmp__/a.md' }] },
+      { paths: ['ok.md', '__tmp__/a.md'] },
+      { resolutions: [{ path: 'ok.md', choose: 'ours' }, { path: '__tmp__/a.md', content: 'x' }] },
+    ];
+    for (const args of calls) {
+      expect(() => normalizePathArgs(args, KB, { tool: 'save_file' })).toThrow(
+        /is a tmp ref, and save_file does not take one there: the workspace's tmp folder is read-only through the ref\..*copy_file/,
+      );
+    }
+    // A tool that takes a ref in `src` still refuses one in `dest`.
+    expect(() => normalizePathArgs({ dest: '__tmp__/a.md' }, KB, { tool: 'copy_file', tmpRefInputs: ['src'] })).toThrow(
+      /copy_file does not take one there/,
+    );
+  });
+
+  it('reads a path that only contains the prefix as an ordinary repository path', () => {
+    expect(normalizePathArgs({ path: 'knowledge-base/__tmp__/a.md' }, KB, T)).toEqual({ path: 'knowledge-base/__tmp__/a.md' });
+    expect(normalizePathArgs({ path: '/knowledge-base/__tmp__/a.md' }, KB, T)).toEqual({ path: 'knowledge-base/__tmp__/a.md' });
   });
 
   it('refuses a traversing tool argument', () => {
-    expect(() => normalizePathArgs({ path: '../escape.md' }, KB)).toThrow(/outside the knowledge base repository/);
+    expect(() => normalizePathArgs({ path: '../escape.md' }, KB, T)).toThrow(/outside the knowledge base repository/);
   });
 });
 

package/src/modules/kb-fs/index.ts

@@ -7,3 +7,16 @@ export type { WriteValidator } from './locking-filesystem.js';
 export { WorkspaceMutex, WorkspaceIdMutex } from './mutex.js';
 export { readRefSha, readRevSha, type RefFileAnswer } from './ref-files.js';
 export { gitDirOf, readGitfile } from './git-dir.js';
+export { normalizeWorkspacePath } from './repo-path.js';
+export { TMP_REF_PREFIX, assertTmpRefsTaken, isTmpRef, tmpRefReadOnlyRefusal } from './tmp-ref.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { BevelIgnoreStack } from './bevel-ignore.js';
+export { assertValidBranchName, assertValidRelativePath, isBranchAuthoredBy, isOwnSuggestionsBranch } from './branch-name.js';
+export { ORIGIN_FETCH_REFSPEC, SAFE_IMPLICIT_FETCH_ARGS, cloneCredentialArgs, cloneCredentialConfigArgs, cloneTrackingConfigArgs, credentialHelperValue } from './clone-config.js';
+export type { FileChangeNotifier } from './file-change-notifier.js';
+export { GitGuardedFilesystem } from './git-guarded-filesystem.js';
+export { LockingFilesystem, MoveLockedError, MoveRacedError } from './locking-filesystem.js';
+export { ReadOnlyFilesystem } from './read-only-filesystem.js';
+export { normalizeRepositoryAddress, sameRepository } from './remote-url.js';
+export { assertInsideRepo, assertKbDirNameFree, assertRepoRootNameFree, assertRepoRootNameFreeArgs, hasControlCharacter, isInsideRepo, normalizePathArgs } from './repo-path.js';
+export type { NormalizePathArgsOptions } from './repo-path.js';

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

@@ -55,7 +55,7 @@ import { DestinationTakenError, lstatOrNull, renameNoReplace, takenError } from
 import { linkedAncestor } from '../../shared/no-link-below.js';
 import { assertInsideRepo } from './repo-path.js';
 import { GitGuardedFilesystem } from './git-guarded-filesystem.js';
-import type { CreationGrantPlan, ICreatorAccess } from '../access-model/creator.js';
+import type { CreationGrantPlan, ICreatorAccess } from '../access-model/index.js';
 
 /** How many times to retry a contended acquire before giving up. */
 const ACQUIRE_RETRY_ATTEMPTS = 3;
@@ -226,9 +226,15 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     const plan = await this.planCreate(inputPath, 'file');
     if (plan?.kind === 'seed-access-md') await this.seedAccessMd(plan);
     const toWrite = content;
+    // An EXCLUSIVE write (`overwrite: false`, the `wx` flag) that finds the
+    // name taken is refused as a copy is (`asTakenRefusal`): the refusal is a
+    // `DestinationTakenError`, so the lock is released untouched. Left as the
+    // raw failure it would be a failed op, and the discard that follows resets
+    // the PATH — throwing away the winner's file, whose commit is still queued.
+    const land = () => super.writeFile(inputPath, toWrite, options);
     return this.withLock(
       inputPath,
-      () => super.writeFile(inputPath, toWrite, options),
+      () => (options?.overwrite === false ? this.asTakenRefusal(inputPath, land) : land()),
       (check || validate) &&
         (async () => {
           // The caller's verdict first: it decides whether this write happens

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

@@ -1,6 +1,7 @@
 import path from 'node:path';
 import { WorkflowValidationError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';
+import { assertTmpRefsTaken, isTmpRef } from './tmp-ref.js';
 
 /**
  * Workspace-relative paths and the repository folder.
@@ -312,6 +313,16 @@ export function assertKbDirNameFree(
   );
 }
 
+/** How {@link normalizePathArgs} treats one tool's call. */
+export interface NormalizePathArgsOptions {
+  /** The tool the call is to, named in a tmp-ref refusal. */
+  tool: string;
+  /** The inputs of `tool` that take a tmp ref (`__tmp__/…`); every other refuses one. */
+  tmpRefInputs?: readonly string[];
+  /** A value that is no workspace path at all, passed to the handler as written. */
+  skip?: (value: string) => boolean;
+}
+
 /** The tool inputs that carry a workspace path. */
 const PATH_ARG_KEYS = ['path', 'src', 'dest', 'destination'] as const;
 
@@ -321,19 +332,34 @@ const PATH_ARG_KEYS = ['path', 'src', 'dest', 'destination'] as const;
  * copy. This is where the MCP surface meets the normaliser — one call, before
  * any handler runs, so no tool keeps a resolver of its own.
  *
- * `skip` is for the one input that is not a workspace path at all: `read_file`
- * also takes a `__tool_chain_spill__/…` ref, which belongs to no workspace and
- * must reach the handler as written. An absent or non-string value is left
- * alone too — the handler's own required-argument message is better than a
- * path refusal about `undefined`.
+ * It is also where a tmp ref (`__tmp__/…`) is admitted or refused, first:
+ * {@link assertTmpRefsTaken} refuses one in every input of `tool` that
+ * `tmpRefInputs` does not name, and a ref in an input that does name it
+ * reaches the handler as written — so no tool whose paths pass through here
+ * can read the ref as the repository path `<kbDirName>/__tmp__/…`.
+ *
+ * `skip` is for the other input that is not a workspace path at all:
+ * `read_file` also takes a `__tool_chain_spill__/…` ref, which belongs to no
+ * workspace and must reach the handler as written. An absent or non-string
+ * value is left alone too — the handler's own required-argument message is
+ * better than a path refusal about `undefined`.
+ *
+ * The earlier call form — a `skip` predicate (or nothing) as the third
+ * argument — is still taken, for a distribution's own tool written against
+ * it: such a call names no tool and takes a tmp ref in no input, so the ref is
+ * refused there as read-only, under the name "this tool".
  */
 export function normalizePathArgs(
   args: Record<string, unknown>,
   kbDirName: string,
-  skip?: (value: string) => boolean,
+  options?: NormalizePathArgsOptions | ((value: string) => boolean),
 ): Record<string, unknown> {
+  const { tool, tmpRefInputs, skip } =
+    typeof options === 'object' ? options : { tool: 'this tool', tmpRefInputs: undefined, skip: options };
+  assertTmpRefsTaken(tool, args, tmpRefInputs);
+  // Every tmp ref still here is in an input that takes one.
   const one = (value: unknown): unknown =>
-    typeof value !== 'string' || value.length === 0 || skip?.(value)
+    typeof value !== 'string' || value.length === 0 || isTmpRef(value) || skip?.(value)
       ? value
       : normalizeWorkspacePath(value, kbDirName);
   const out: Record<string, unknown> = { ...args };

package/src/modules/kb-fs/tmp-ref.ts

@@ -0,0 +1,81 @@
+import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { sanitizedPath } from '../../shared/printable.js';
+
+/**
+ * The tmp ref's admission: which tool inputs may carry one, and the refusal
+ * every other input answers. What the ref REACHES is `workspace/workspace-tmp.ts`'s;
+ * whether a tool may be HANDED one is decided here, once, by
+ * {@link assertTmpRefsTaken} — which {@link normalizePathArgs} runs before it
+ * places any path under the checkout, so no tool surface that takes a path
+ * can turn `__tmp__/x` into the repository path `<kbDirName>/__tmp__/x` and
+ * write, read or show it as if the ref had been honoured. A surface that
+ * resolves its paths without the normaliser (`open_page`) calls the gate
+ * itself.
+ */
+
+/** The ref's prefix. A ref is `__tmp__/<path inside the workspace's tmp folder>`. */
+export const TMP_REF_PREFIX = '__tmp__/';
+
+/**
+ * Whether a tool argument is a tmp ref rather than a repository path: the
+ * prefix as written, or the prefix's own folder name alone (which names the
+ * folder, and is refused as such by the resolver). A path that only CONTAINS
+ * the name — `/__tmp__/x`, `knowledge-base/__tmp__/x` — is an ordinary
+ * repository path.
+ */
+export function isTmpRef(value: unknown): boolean {
+  return typeof value === 'string' && (value === TMP_REF_PREFIX.slice(0, -1) || value.startsWith(TMP_REF_PREFIX));
+}
+
+/**
+ * Why a tool refuses a tmp ref in an input that is not one of the four that
+ * take it: the folder is read-only through the ref, and a file is kept by
+ * copying it into the repository. A 400 with a `kind` to branch on, before
+ * any gate, lock or write.
+ */
+export function tmpRefReadOnlyRefusal(ref: string, tool: string): WorkflowValidationError {
+  const shown = sanitizedPath(ref);
+  return new WorkflowValidationError(
+    `"${shown}" is a tmp ref, and ${tool} does not take one there: the workspace's tmp folder is read-only through ` +
+      'the ref. read_file, file_stat and grep read the one file it names; to keep the file, copy_file it to a ' +
+      'repository path (the ref as `src`, the repository path as `dest`).',
+    { kind: 'tmp-ref-read-only', path: shown, tool },
+  );
+}
+
+/** The tool inputs that carry a workspace path as a string. */
+const PATH_INPUTS = ['path', 'src', 'dest', 'destination'] as const;
+
+/**
+ * Every path a tool call carries, with the input it came in: the string
+ * inputs, and for EVERY list input, each entry that is a path itself
+ * (`paths` of `request_file_download`) or an object carrying one in `path`
+ * (`files[].path` of a batch write, `resolutions[].path` of
+ * `update_branch`). Read by shape rather than by a list of tool inputs, so a
+ * list a tool adds later is gated without anyone remembering to name it here.
+ */
+function pathEntries(args: Record<string, unknown>): Array<[string, unknown]> {
+  const entries: Array<[string, unknown]> = PATH_INPUTS.map((key) => [key, args[key]]);
+  for (const [key, value] of Object.entries(args)) {
+    if (!Array.isArray(value)) continue;
+    for (const item of value as unknown[]) {
+      if (typeof item === 'string') {
+        if (key === 'paths') entries.push([key, item]);
+      } else if (item && typeof item === 'object') {
+        entries.push([key, (item as Record<string, unknown>).path]);
+      }
+    }
+  }
+  return entries;
+}
+
+/**
+ * Refuse a tmp ref in any input of `tool` that is not in `takes` — with
+ * {@link tmpRefReadOnlyRefusal}, before anything else runs. `takes` is empty
+ * for every tool but the four reads of the one file a ref names.
+ */
+export function assertTmpRefsTaken(tool: string, args: Record<string, unknown>, takes: readonly string[] = []): void {
+  for (const [key, value] of pathEntries(args)) {
+    if (isTmpRef(value) && !takes.includes(key)) throw tmpRefReadOnlyRefusal(value as string, tool);
+  }
+}

package/src/modules/kb-sync/kb-sync.routes.ts

@@ -2,12 +2,12 @@ import express from 'express';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('sync');
-import type { IAdminAccessService } from '../admin/admin.interface.js';
-import { assertValidBranchName } from '../kb-fs/branch-name.js';
+import type { IAdminAccessService } from '../admin/index.js';
+import { assertValidBranchName } from '../kb-fs/index.js';
 import type { IKbSyncService, SyncResult } from './kb-sync.interface.js';
 import { parseSyncPayload, type SyncPayloadSource } from './sync-payload.js';
 import { verifySyncCredential } from './sync-auth.js';
-import { AuthBackendError } from '../auth/account-admission.js';
+import { AuthBackendError } from '../auth/index.js';
 
 /**
  * Remote sync — a git host or a pipeline tells Hexis the repository changed.

package/src/modules/kb-sync/kb-sync.service.ts

@@ -2,7 +2,7 @@ import type { BranchSyncOutcome } from '@bevel-software/platform-shared';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('sync');
-import { sanitizeError } from '../workflow/sanitize-error.js';
+import { sanitizeError } from '../workflow/index.js';
 import type {
   IKbSyncService,
   LastSync,

package/src/modules/kb-sync/sync-auth.ts

@@ -1,5 +1,5 @@
 import { createHmac } from 'node:crypto';
-import { timingSafeStringEqual } from '../auth/password-hash.js';
+import { timingSafeStringEqual } from '../auth/index.js';
 
 /**
  * Who may call `POST /api/sync`, decided from the request's credentials.

package/src/modules/kb-sync/sync-payload.ts

@@ -1,4 +1,4 @@
-import { assertValidBranchName } from '../kb-fs/branch-name.js';
+import { assertValidBranchName } from '../kb-fs/index.js';
 
 /**
  * Turn whatever a caller POSTed to `/api/sync` into the branches to sync.

package/src/modules/marketplace/git-http.routes.ts

@@ -5,7 +5,7 @@ const log = logger('marketplace');
 import { spawn } from 'node:child_process';
 import type { AuthUser } from '@bevel-software/platform-shared';
 import type { MarketplaceRepoService } from './marketplace-repo.service.js';
-import '../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
+import '../tool-auth/index.js'; // Express Request augmentation (req.externalApiKeyId)
 
 /** How a bearer string resolves to a user — the connection-key service's shape. */
 export interface MarketplaceKeyResolver {

package/src/modules/marketplace/github-facade/github-facade-admin.routes.ts

@@ -2,7 +2,7 @@ import express from 'express';
 import { logger } from '../../../shared/logging.js';
 
 const log = logger('github-facade');
-import '../../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
+import '../../auth/index.js'; // Express Request.userId / userEmail augmentation
 import {
   GitHubFacadeUnavailableError,
   type GitHubFacadeCredentialsService,

package/src/modules/marketplace/github-facade/github-facade-codes.store.ts

@@ -1,6 +1,6 @@
 import { and, eq, gt, isNull } from 'drizzle-orm';
-import type { Database } from '../../database/connection.js';
-import { githubFacadeCodes } from '../../database/schema.js';
+import type { Database } from '../../database/index.js';
+import { githubFacadeCodes } from '../../database/index.js';
 
 /**
  * A one-time code the consent page issued, waiting for Anthropic's backend

package/src/modules/marketplace/github-facade/github-facade-credentials.service.ts

@@ -1,7 +1,7 @@
 import { generateKeyPairSync, randomBytes, randomInt } from 'node:crypto';
 import { and, eq } from 'drizzle-orm';
-import type { Database } from '../../database/connection.js';
-import { githubFacadeIdentity } from '../../database/schema.js';
+import type { Database } from '../../database/index.js';
+import { githubFacadeIdentity } from '../../database/index.js';
 import type { TokenCrypto } from '../../../shared/token-crypto.js';
 
 /**

package/src/modules/marketplace/github-facade/github-facade.routes.ts

@@ -3,8 +3,8 @@ import { logger } from '../../../shared/logging.js';
 
 const log = logger('github-facade');
 import type { AuthUser } from '@bevel-software/platform-shared';
-import '../../auth/auth.middleware.js'; // Express Request.userId / userEmail augmentation
-import '../../tool-auth/external-api-key.interface.js'; // Express Request augmentation (req.externalApiKeyId)
+import '../../auth/index.js'; // Express Request.userId / userEmail augmentation
+import '../../tool-auth/index.js'; // Express Request augmentation (req.externalApiKeyId)
 import type { MarketplaceRepoService } from '../marketplace-repo.service.js';
 import type { MarketplaceKeyResolver } from '../git-http.routes.js';
 import { GitHubFacadeRequestError, type GitHubFacade } from './github-facade.service.js';

package/src/modules/marketplace/github-facade/github-facade.service.ts

@@ -2,8 +2,8 @@ import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { logger } from '../../../shared/logging.js';
 
 const log = logger('github-facade');
-import type { KeyKindSpec, MintedExternalApiKey } from '../../tool-auth/external-api-key.interface.js';
-import { signAuthRequest, type McpAuthRequestState } from '../../mcp/oauth/oauth-state.js';
+import type { KeyKindSpec, MintedExternalApiKey } from '../../tool-auth/index.js';
+import { signAuthRequest, type McpAuthRequestState } from '../../mcp/index.js';
 import type { GitHubFacadeCredentialsService } from './github-facade-credentials.service.js';
 import type { GitHubFacadeCodeStore } from './github-facade-codes.store.js';
 import { printable } from '../../../shared/printable.js';

package/src/modules/marketplace/marketplace-repo.service.ts

@@ -2,8 +2,8 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn, type ChildProcess } from 'node:child_process';
-import { WorkspaceMutex } from '../kb-fs/mutex.js';
-import type { VirtualTree } from '../plugins/compile/compile-marketplace.js';
+import { WorkspaceMutex } from '../kb-fs/index.js';
+import type { VirtualTree } from '../plugins/index.js';
 import { type IGitRunner } from '../../shared/git.contract.js';
 
 /** What the repo service asks the compiler for — the one seam it has. */

package/src/modules/mcp/__tests__/connect-as.pg.test.ts

@@ -0,0 +1,137 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { eq } from 'drizzle-orm';
+import { migrate } from 'drizzle-orm/node-postgres/migrator';
+import type { OAuthClientInformationFull } from '@modelcontextprotocol/sdk/shared/auth.js';
+import { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
+import { ExternalApiKeyService } from '../../tool-auth/external-api-key.service.js';
+import { closeDb, createDb, type Database } from '../../database/connection.js';
+import { agentConnections, externalApiKeys, oauthClients, users } from '../../database/core-schema.js';
+import { coreMigrationsDir } from '../../../assets.js';
+import { PG_ADMIN_URL, PG_TEST_TIMEOUT, dropScratchDatabases, scratchDatabaseUrl } from '../../../__tests__/pg-scratch.js';
+
+/**
+ * The "Connect as" choice, through the real intermediary it is stored in: a
+ * migrated Postgres. The consent's choice goes onto the one-time code at
+ * Finish, crosses the token exchange onto the agent connection, and comes back
+ * out of every access-token verification; a key's choice goes onto its row at
+ * mint and comes back out of every key verification. Driven through the
+ * provider's and the key service's public surfaces only. Skipped without
+ * `TEST_DATABASE_URL`, as every `*.pg.test.ts` is.
+ */
+
+const PREFIX = 'bevel-mcp_';
+const REDIRECT = 'https://agent.example.com/callback';
+
+describe.skipIf(!PG_ADMIN_URL)('connecting as an agent, on a real Postgres', () => {
+  let db: Database;
+  let provider: BevelOAuthProvider;
+
+  beforeAll(async () => {
+    db = createDb(await scratchDatabaseUrl('hexis_connect_as'), { piiKey: randomBytes(32).toString('base64') });
+    await migrate(db, { migrationsFolder: coreMigrationsDir() });
+    provider = new BevelOAuthProvider({
+      db,
+      crypto: null,
+      stateSecret: 'test-state-secret',
+      publicFrontendUrl: 'https://app.example.com',
+      tokenPrefix: PREFIX,
+    });
+    vi.spyOn(console, 'log').mockImplementation(() => undefined);
+  }, PG_TEST_TIMEOUT);
+
+  afterAll(async () => {
+    vi.restoreAllMocks();
+    await closeDb(db);
+    await dropScratchDatabases();
+  }, PG_TEST_TIMEOUT);
+
+  async function person(tag: string): Promise<string> {
+    const [user] = await db
+      .insert(users)
+      .values({ email: `${tag}@example.com`, emailBidx: `${tag}@example.com`, name: tag })
+      .returning({ id: users.id });
+    return user!.id;
+  }
+
+  async function registeredClient(tag: string): Promise<OAuthClientInformationFull> {
+    const clientId = `client-${tag}-${randomBytes(4).toString('hex')}`;
+    await db.insert(oauthClients).values({ clientId, clientName: 'Claude', redirectUris: [REDIRECT] });
+    return { client_id: clientId, redirect_uris: [REDIRECT], token_endpoint_auth_method: 'none' };
+  }
+
+  /** Finish on the consent step with `agentPath` (undefined: the route's Everything), then the client's exchange. */
+  async function consent(userId: string, client: OAuthClientInformationFull, agentPath?: string | null) {
+    const st = { c: client.client_id, r: REDIRECT, cc: 'challenge', iat: Date.now() };
+    const { redirectTo } =
+      agentPath === undefined ? await provider.issueAuthCode(userId, st) : await provider.issueAuthCode(userId, st, agentPath);
+    const code = new URL(redirectTo).searchParams.get('code')!;
+    return provider.exchangeAuthorizationCode(client, code);
+  }
+
+  const connectionsOf = (userId: string) =>
+    db
+      .select({ id: agentConnections.id, agentPath: agentConnections.agentPath, revokedAt: agentConnections.revokedAt })
+      .from(agentConnections)
+      .where(eq(agentConnections.userId, userId));
+
+  it('Everything: a consent with no choice records null and verifies with none — exactly as before', async () => {
+    const userId = await person('everything');
+    const tokens = await consent(userId, await registeredClient('everything'));
+    expect(await connectionsOf(userId)).toEqual([{ id: expect.any(String), agentPath: null, revokedAt: null }]);
+    expect((await provider.verifyAccessToken(tokens.access_token)).extra?.agentPath).toBeNull();
+  });
+
+  it("the consent's choice round-trips to the connection row, and out of every verification", async () => {
+    const userId = await person('ada');
+    const client = await registeredClient('ada');
+    const tokens = await consent(userId, client, 'Agents/delivery-mechanic.agent');
+
+    const [row] = await connectionsOf(userId);
+    expect(row!.agentPath).toBe('Agents/delivery-mechanic.agent');
+    const info = await provider.verifyAccessToken(tokens.access_token);
+    expect(info.extra).toMatchObject({ connectionId: row!.id, agentPath: 'Agents/delivery-mechanic.agent' });
+
+    // A refresh keeps the connection's choice.
+    const refreshed = await provider.exchangeRefreshToken(client, tokens.refresh_token!);
+    expect((await provider.verifyAccessToken(refreshed.access_token)).extra?.agentPath).toBe('Agents/delivery-mechanic.agent');
+  });
+
+  it('re-consenting with another choice changes the live connection, and its tokens follow it', async () => {
+    const userId = await person('bea');
+    const first = await consent(userId, await registeredClient('bea'), 'Agents/a.agent');
+    // Claude registers afresh on every re-authorisation; the agent is one connection.
+    await consent(userId, await registeredClient('bea'), null);
+
+    const rows = await connectionsOf(userId);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]!.agentPath).toBeNull();
+    // The earlier pair still verifies — and now as the connection's choice.
+    expect((await provider.verifyAccessToken(first.access_token)).extra?.agentPath).toBeNull();
+
+    await consent(userId, await registeredClient('bea'), 'Agents/b.agent');
+    expect((await connectionsOf(userId))[0]!.agentPath).toBe('Agents/b.agent');
+  });
+
+  it("a key's choice is stored at mint and comes back out of every verification", async () => {
+    const userId = await person('cy');
+    const keys = new ExternalApiKeyService(db, 'bevel_');
+    const asAgent = await keys.mint(userId, 'pipeline', { agentPath: 'Agents/ops.agent' });
+    const asEverything = await keys.mint(userId, 'laptop');
+
+    expect(asAgent.summary.agentPath).toBe('Agents/ops.agent');
+    expect(asEverything.summary.agentPath).toBeNull();
+    expect((await keys.verifyAndLoadToken(asAgent.plaintext))?.agentPath).toBe('Agents/ops.agent');
+    expect((await keys.verifyAndLoadToken(asEverything.plaintext))?.agentPath).toBeNull();
+
+    const stored = await db
+      .select({ label: externalApiKeys.label, agentPath: externalApiKeys.agentPath })
+      .from(externalApiKeys)
+      .where(eq(externalApiKeys.userId, userId));
+    expect(stored.sort((a, b) => a.label.localeCompare(b.label))).toEqual([
+      { label: 'laptop', agentPath: null },
+      { label: 'pipeline', agentPath: 'Agents/ops.agent' },
+    ]);
+    expect((await keys.listForUser(userId)).map((k) => k.agentPath).sort()).toEqual(['Agents/ops.agent', null]);
+  });
+});

package/src/modules/mcp/__tests__/mcp-auth.middleware.test.ts

@@ -53,8 +53,8 @@ function makeExternalApiKeyService(
 
 function makeOAuthProvider(
   verify?: (t: string) => Promise<{ extra?: Record<string, unknown> }>,
-  /** Whether an agent connection still admits requests — true unless a test says otherwise. */
-  live?: (connectionId: string) => Promise<boolean>,
+  /** A live agent connection's current choice, or null when revoked — live as Everything unless a test says otherwise. */
+  live?: (connectionId: string) => Promise<{ agentPath: string | null } | null>,
 ) {
   return {
     looksLikeAccessToken: (t: string) => typeof t === 'string' && t.startsWith('bevel-mcp_'),
@@ -64,7 +64,7 @@ function makeOAuthProvider(
           throw new InvalidTokenError('unknown token');
         }),
     ),
-    isConnectionLive: vi.fn(live ?? (async () => true)),
+    liveConnectionChoice: vi.fn(live ?? (async () => ({ agentPath: null }))),
     noteConnectionUse: vi.fn(),
   } as unknown as BevelOAuthProvider;
 }
@@ -318,10 +318,34 @@ describe('createMcpAuthMiddleware', () => {
       expect(req.agentConnectionId).toBe('conn-7');
       // Every request through the exchanged grant asks whether the
       // connection still admits one, and counts as a use of it.
-      expect((oauth as any).isConnectionLive).toHaveBeenCalledWith('conn-7');
+      expect((oauth as any).liveConnectionChoice).toHaveBeenCalledWith('conn-7');
       expect((oauth as any).noteConnectionUse).toHaveBeenCalledWith('conn-7');
     });
 
+    it("serves an exchanged grant as its connection's CURRENT choice, not the one it was minted with", async () => {
+      const auth = makeAuthService();
+      (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({
+        id: 'user-7',
+        email: 'seven@example.com',
+      }));
+      // Minted as Everything; the person has since re-consented as an agent.
+      const everything = internal.mint({ userId: 'user-7', externalProxy: true, connectionId: 'conn-7' }, 60_000);
+      const narrowed = makeOAuthProvider(undefined, async () => ({ agentPath: 'Agents/narrow.agent' }));
+      const first = makeReqRes(`Bearer ${everything}`);
+      await makeMw({ internal, auth, oauth: narrowed })(first.req, first.res, first.next);
+      expect(first.next).toHaveBeenCalled();
+      expect(first.req.mcpAgentPath).toBe('Agents/narrow.agent');
+      // Minted as an agent; the person has since re-consented as Everything.
+      const asAgent = internal.mint(
+        { userId: 'user-7', externalProxy: true, connectionId: 'conn-7', agentPath: 'Agents/narrow.agent' },
+        60_000,
+      );
+      const second = makeReqRes(`Bearer ${asAgent}`);
+      await makeMw({ internal, auth, oauth: makeOAuthProvider() })(second.req, second.res, second.next);
+      expect(second.next).toHaveBeenCalled();
+      expect(second.req.mcpAgentPath).toBeUndefined();
+    });
+
     it('401s an exchanged grant whose agent connection was revoked — the token is stateless, the connection is not', async () => {
       const token = internal.mint({ userId: 'user-7', externalProxy: true, connectionId: 'conn-7' }, 60_000);
       const auth = makeAuthService();
@@ -329,7 +353,7 @@ describe('createMcpAuthMiddleware', () => {
         id: 'user-7',
         email: 'seven@example.com',
       }));
-      const oauth = makeOAuthProvider(undefined, async () => false);
+      const oauth = makeOAuthProvider(undefined, async () => null);
       const mw = makeMw({ internal, auth, oauth });
       const { req, res, next, status, setHeader } = makeReqRes(`Bearer ${token}`);
       await mw(req, res, next);