@bevel-software/platform-core-backend 0.19.0 → 0.21.0

package/src/modules/mcp/__tests__/bevel-oauth-provider.test.ts

@@ -2,9 +2,12 @@ import { describe, expect, it, vi } from 'vitest';
 import { createHash } from 'node:crypto';
 import { InvalidGrantError, InvalidScopeError, InvalidTokenError } from '@modelcontextprotocol/sdk/server/auth/errors.js';
 import type { OAuthClientInformationFull } from '@modelcontextprotocol/sdk/shared/auth.js';
-import { BevelOAuthProvider } from '../oauth/bevel-oauth-provider.js';
+import type { SQL } from 'drizzle-orm';
+import { PgDialect } from 'drizzle-orm/pg-core';
+import { BevelOAuthProvider, agentKeyFor } from '../oauth/bevel-oauth-provider.js';
 import { signAuthRequest, verifyAuthRequest } from '../oauth/oauth-state.js';
 import type { Database } from '../../database/connection.js';
+import { agentConnections, oauthTokens } from '../../database/schema.js';
 
 const STATE_SECRET = 'test-state-secret';
 const PREFIX = 'bevel-mcp_';
@@ -12,9 +15,19 @@ const FRONTEND = 'https://app.example.com';
 
 /** Same fake drizzle chain as external-api-key.service.test.ts: every
  * chainable method returns the chain, the chain is thenable, and each
- * db.insert/select/update pops the next queued result. */
+ * db.insert/select/update pops the next queued result. What the provider
+ * WRITES and WHERE it writes it are captured too — `set`, `values`, the
+ * `update` target and every `where` predicate (rendered to SQL by
+ * {@link render}) — so a test can pin the row a statement lands on, not
+ * merely that a statement ran. */
 function makeFakeDb(queue: any[]) {
-  const captured: { values: any[]; set: any[] } = { values: [], set: [] };
+  const captured: {
+    values: any[];
+    set: any[];
+    where: SQL[];
+    updateTargets: unknown[];
+    onConflict: any[];
+  } = { values: [], set: [], where: [], updateTargets: [], onConflict: [] };
 
   function nextChain() {
     const result = queue.shift();
@@ -26,11 +39,13 @@ function makeFakeDb(queue: any[]) {
       });
     chain.values = passthrough((a) => captured.values.push(a[0]));
     chain.set = passthrough((a) => captured.set.push(a[0]));
-    chain.where = passthrough();
+    chain.where = passthrough((a) => captured.where.push(a[0]));
     chain.limit = passthrough();
     chain.innerJoin = passthrough();
+    chain.leftJoin = passthrough();
     chain.from = passthrough();
     chain.returning = passthrough();
+    chain.onConflictDoNothing = passthrough((a) => captured.onConflict.push(a[0]));
     chain.then = (onF: any, onR: any) => Promise.resolve(result).then(onF, onR);
     return chain;
   }
@@ -38,12 +53,23 @@ function makeFakeDb(queue: any[]) {
   const db = {
     insert: vi.fn(() => nextChain()),
     select: vi.fn(() => nextChain()),
-    update: vi.fn(() => nextChain()),
+    update: vi.fn((table: unknown) => {
+      captured.updateTargets.push(table);
+      return nextChain();
+    }),
+    // The mint-time prune of expired token rows; nothing here queues for it.
+    delete: vi.fn(() => nextChain()),
   } as unknown as Database;
 
   return { db, captured };
 }
 
+/** A captured predicate as the SQL it would send, with its parameters. */
+function render(fragment: SQL): { sql: string; params: unknown[] } {
+  const q = new PgDialect().sqlToQuery(fragment);
+  return { sql: q.sql, params: q.params };
+}
+
 function makeProvider(queue: any[] = []) {
   const { db, captured } = makeFakeDb(queue);
   const provider = new BevelOAuthProvider({
@@ -183,7 +209,15 @@ describe('BevelOAuthProvider', () => {
       clientId: 'client-1', userId: 'user-1', redirectUri: 'https://agent.example.com/callback',
       scope: 'mcp', resource: null,
     };
-    const { provider, captured } = makeProvider([[consumed] /* update.returning */, undefined /* insert */]);
+    const { provider, captured } = makeProvider([
+      [consumed] /* update.returning */,
+      undefined /* prune: expired tokens */,
+      undefined /* prune: expired codes */,
+      [{ clientName: 'Claude' }] /* the client's registration */,
+      [] /* no live agent connection yet for (user, "claude") */,
+      [{ id: 'conn-1' }] /* connection insert.returning */,
+      undefined /* token insert */,
+    ]);
 
     const tokens = await provider.exchangeAuthorizationCode(
       CLIENT, 'the-code', undefined, 'https://agent.example.com/callback',
@@ -194,15 +228,51 @@ describe('BevelOAuthProvider', () => {
     expect(tokens.refresh_token!.startsWith(`${PREFIX}r_`)).toBe(true);
     expect(tokens.expires_in).toBe(3600);
     expect(tokens.scope).toBe('mcp');
-    // The token row stores hashes of exactly what was returned.
-    expect(captured.values[0]).toMatchObject({
+    // A first mint for (user, agent) makes the durable agent connection,
+    // keyed by the client's folded name and snapshotting the name shown…
+    expect(captured.values[0]).toEqual({ userId: 'user-1', clientId: 'client-1', clientName: 'Claude', agentKey: 'claude' });
+    // …looked up by that key, so a later registration of "Claude" by this
+    // person lands on the same row instead of making a sixth one.
+    // (where[0] consumed the code, [1]/[2] are the prunes, [3] read the client.)
+    expect(render(captured.where[4])).toMatchObject({ params: ['user-1', 'claude'] });
+    expect(render(captured.where[4]).sql).toMatch(/"agent_connections"."agent_key" = \$2/);
+    // …and the token row stores hashes of exactly what was returned, bound to it.
+    expect(captured.values[1]).toMatchObject({
       accessTokenHash: sha256(tokens.access_token),
       refreshTokenHash: sha256(tokens.refresh_token!),
       clientId: 'client-1',
       userId: 'user-1',
+      connectionId: 'conn-1',
     });
   });
 
+  it('a mint that loses the race for the first connection re-reads the winner instead of failing', async () => {
+    const consumed = { clientId: 'client-1', userId: 'user-1', redirectUri: 'https://agent.example.com/callback', scope: null, resource: null };
+    const { provider, captured } = makeProvider([
+      [consumed],
+      undefined, undefined, /* prunes */
+      [{ clientName: 'Claude' }],
+      [] /* no live connection at first look */,
+      [] /* insert: ON CONFLICT DO NOTHING returned no row */,
+      [{ id: 'conn-winner' }] /* the re-read finds the other mint's row */,
+      undefined /* token insert */,
+    ]);
+    await provider.exchangeAuthorizationCode(CLIENT, 'the-code', undefined, 'https://agent.example.com/callback');
+    expect(captured.values[1]).toMatchObject({ connectionId: 'conn-winner' });
+    // The insert really did stand down on the conflict — on the live-agent
+    // index, not any other — rather than the fake merely answering "no row".
+    expect(captured.onConflict).toHaveLength(1);
+    expect(captured.onConflict[0].target).toEqual([agentConnections.userId, agentConnections.agentKey]);
+    expect(render(captured.onConflict[0].where).sql).toMatch(/"revoked_at" is null/);
+  });
+
+  it('keys a connection by the folded client name, so re-registrations of one agent share a row; a nameless client keys by its id', () => {
+    expect(agentKeyFor('Claude', 'c-1')).toBe('claude');
+    expect(agentKeyFor('  Claude Code ', 'c-2')).toBe('claude code');
+    expect(agentKeyFor(null, 'c-3')).toBe('c-3');
+    expect(agentKeyFor('   ', 'c-4')).toBe('c-4');
+  });
+
   it('exchangeAuthorizationCode rejects a spent/unknown code and a redirect_uri mismatch', async () => {
     await expect(
       makeProvider([[]]).provider.exchangeAuthorizationCode(CLIENT, 'spent'),
@@ -216,12 +286,30 @@ describe('BevelOAuthProvider', () => {
 
   it('exchangeRefreshToken rotates (revokes old row, mints new pair) and only narrows scope', async () => {
     const oldRow = {
-      clientId: 'client-1', userId: 'user-1', scope: 'mcp extra', resource: null,
+      clientId: 'client-1', userId: 'user-1', connectionId: 'conn-1', scope: 'mcp extra', resource: null,
       refreshExpiresAt: new Date(Date.now() + 60_000),
     };
-    const { provider } = makeProvider([[oldRow] /* revoke.returning */, undefined /* insert */]);
+    const { provider, captured, db } = makeProvider([
+      [oldRow] /* revoke.returning */,
+      [{ id: 'conn-1' }] /* the token's connection, still live */,
+      undefined /* the (throttled) use stamp */,
+      undefined, undefined, /* prunes */
+      undefined /* token insert */,
+    ]);
     const tokens = await provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old', ['mcp']);
     expect(tokens.scope).toBe('mcp');
+    // A refresh STAYS on its token's connection: one connection spans every
+    // token the agent holds, nothing is looked up by (user, agent) and no
+    // second row is inserted for it.
+    expect(captured.values).toHaveLength(1);
+    expect(captured.values[0]).toMatchObject({ connectionId: 'conn-1' });
+    // The liveness check is a read of THAT connection, live rows only…
+    expect((db as any).select).toHaveBeenCalledTimes(1);
+    expect(render(captured.where[1])).toMatchObject({ params: ['conn-1'] });
+    expect(render(captured.where[1]).sql).toMatch(/"agent_connections"."revoked_at" is null/);
+    // …and the use is stamped separately, off the refresh's own path.
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections]);
+    expect(Object.keys(captured.set[1])).toEqual(['lastUsedAt']);
 
     // Widening is refused.
     await expect(
@@ -234,18 +322,100 @@ describe('BevelOAuthProvider', () => {
     ).rejects.toBeInstanceOf(InvalidGrantError);
   });
 
+  it('exchangeRefreshToken refuses a token whose agent connection was revoked, minting nothing', async () => {
+    // The race a revoke cannot otherwise win: the refresh consumed its old
+    // token a moment before the revoke landed. Looking the connection up
+    // afresh would find none live and make a new one; staying on the token's
+    // own connection finds it revoked and stops.
+    const oldRow = {
+      clientId: 'client-1', userId: 'user-1', connectionId: 'conn-1', scope: 'mcp', resource: null,
+      refreshExpiresAt: new Date(Date.now() + 60_000),
+    };
+    const { provider, captured } = makeProvider([[oldRow], [] /* connection revoked or gone */]);
+    await expect(provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old')).rejects.toBeInstanceOf(InvalidGrantError);
+    expect(captured.values).toHaveLength(0);
+    expect(captured.onConflict).toHaveLength(0);
+  });
+
+  it('exchangeRefreshToken places a token from before connections existed under one, as a first mint would', async () => {
+    const oldRow = {
+      clientId: 'client-1', userId: 'user-1', connectionId: null, scope: 'mcp', resource: null,
+      refreshExpiresAt: new Date(Date.now() + 60_000),
+    };
+    const { provider, captured } = makeProvider([
+      [oldRow],
+      undefined, undefined, /* prunes */
+      [{ clientName: 'Claude' }],
+      [] /* no live connection */,
+      [{ id: 'conn-new' }] /* connection insert.returning */,
+      undefined /* token insert */,
+    ]);
+    await provider.exchangeRefreshToken(CLIENT, 'bevel-mcp_r_old');
+    expect(captured.values[0]).toEqual({ userId: 'user-1', clientId: 'client-1', clientName: 'Claude', agentKey: 'claude' });
+    expect(captured.values[1]).toMatchObject({ connectionId: 'conn-new' });
+  });
+
   it('verifyAccessToken resolves a live token to AuthInfo carrying the Bevel user', async () => {
     const row = {
-      id: 'tok-row-1', clientId: 'client-1', scope: 'mcp', resource: null,
+      id: 'tok-row-1', clientId: 'client-1', connectionId: 'conn-1', scope: 'mcp', resource: null,
       expiresAt: new Date(Date.now() + 60_000), userId: 'user-1', userEmail: 'alice@example.com',
     };
-    const { provider } = makeProvider([[row] /* select */, undefined /* lastUsedAt touch */]);
+    const { provider, captured } = makeProvider([
+      [row] /* select */,
+      undefined /* token lastUsedAt touch */,
+      undefined /* connection lastUsedAt touch */,
+      [row] /* a second verify a moment later */,
+      undefined /* its token touch — and NO second connection touch */,
+    ]);
 
     const info = await provider.verifyAccessToken('bevel-mcp_live');
 
     expect(info.clientId).toBe('client-1');
     expect(info.scopes).toEqual(['mcp']);
-    expect(info.extra).toMatchObject({ userId: 'user-1', userEmail: 'alice@example.com' });
+    // The agent connection rides along, for the auth middleware to bind.
+    expect(info.extra).toMatchObject({ userId: 'user-1', userEmail: 'alice@example.com', connectionId: 'conn-1' });
+    // The lookup admits a token only while its connection is unrevoked — or
+    // has none to be revoked (a token from before connections existed).
+    const lookup = render(captured.where[0]).sql;
+    expect(lookup).toMatch(/"oauth_tokens"."connection_id" is null or "agent_connections"."revoked_at" is null/);
+    // Both "last used" marks are touched: the token's row, and THIS token's
+    // agent connection.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections]);
+    expect(captured.set.map((s) => Object.keys(s))).toEqual([['lastUsedAt'], ['lastUsedAt']]);
+    expect(render(captured.where[1])).toMatchObject({ params: ['tok-row-1'] });
+    expect(render(captured.where[2])).toMatchObject({ params: ['conn-1'] });
+    expect(render(captured.where[2]).sql).toMatch(/"agent_connections"."id" = \$1/);
+    // The connection's stamp is throttled: a verify a moment later touches
+    // the token row again but not the connection — a minute has not passed.
+    await provider.verifyAccessToken('bevel-mcp_live');
+    await new Promise((r) => setTimeout(r, 0));
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections, oauthTokens]);
+  });
+
+  it('revokeToken (RFC 7009) ends the agent connection once no live token remains on it, as the owner\'s doing', async () => {
+    const { provider, captured } = makeProvider([
+      [{ connectionId: 'conn-1' }] /* the revoked pair's row */,
+      [{ live: 0 }] /* nothing else live on the connection */,
+      undefined /* connection close */,
+    ]);
+    await provider.revokeToken(CLIENT, { token: 'bevel-mcp_r_old', token_type_hint: 'refresh_token' });
+    expect(captured.updateTargets).toEqual([oauthTokens, agentConnections]);
+    expect(captured.set[1]).toMatchObject({ revokedBy: 'owner' });
+    expect(captured.set[1].revokedAt).toBeInstanceOf(Date);
+    expect(render(captured.where[2])).toMatchObject({ params: ['conn-1'] });
+    expect(render(captured.where[2]).sql).toMatch(/"agent_connections"."revoked_at" is null/);
+
+    // Another live pair on the connection (the agent signed in twice): the
+    // connection stays.
+    const busy = makeProvider([[{ connectionId: 'conn-1' }], [{ live: 1 }]]);
+    await busy.provider.revokeToken(CLIENT, { token: 'bevel-mcp_r_other' });
+    expect(busy.captured.updateTargets).toEqual([oauthTokens]);
+
+    // An unknown or foreign token revokes nothing and touches no connection.
+    const unknown = makeProvider([[]]);
+    await unknown.provider.revokeToken(CLIENT, { token: 'bevel-mcp_r_gone' });
+    expect(unknown.captured.updateTargets).toEqual([oauthTokens]);
   });
 
   it('verifyAccessToken throws InvalidTokenError for unknown/revoked/expired tokens', async () => {

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

@@ -48,6 +48,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>,
 ) {
   return {
     looksLikeAccessToken: (t: string) => typeof t === 'string' && t.startsWith('bevel-mcp_'),
@@ -57,6 +59,8 @@ function makeOAuthProvider(
           throw new InvalidTokenError('unknown token');
         }),
     ),
+    isConnectionLive: vi.fn(live ?? (async () => true)),
+    noteConnectionUse: vi.fn(),
   } as unknown as BevelOAuthProvider;
 }
 
@@ -179,7 +183,7 @@ describe('createMcpAuthMiddleware', () => {
     const auth = makeAuthService();
     const externalApiKeys = makeExternalApiKeyService();
     const oauth = makeOAuthProvider(async () => ({
-      extra: { userId: 'user-5', userEmail: 'eve@example.com' },
+      extra: { userId: 'user-5', userEmail: 'eve@example.com', connectionId: 'conn-5' },
     }));
     const mw = makeMw({ auth, keys: externalApiKeys, oauth });
     const { req, res, next } = makeReqRes('Bearer bevel-mcp_token123');
@@ -188,14 +192,28 @@ describe('createMcpAuthMiddleware', () => {
 
     expect(req.userId).toBe('user-5');
     expect(req.userEmail).toBe('eve@example.com');
-    // OAuth sessions are unmetered like JWT sessions — no connection key id.
+    // OAuth sessions are unmetered like JWT sessions — no connection key id…
     expect(req.externalApiKeyId).toBeUndefined();
+    // …but they ARE attributed to the agent behind the grant, for the Audit log.
+    expect(req.agentConnectionId).toBe('conn-5');
     expect(next).toHaveBeenCalled();
     // Neither the connection-key nor the JWT path may see this token shape.
     expect((externalApiKeys as any).verifyAndLoadToken).not.toHaveBeenCalled();
     expect((auth as any).verifyToken).not.toHaveBeenCalled();
   });
 
+  it('binds no agent for an OAuth token minted before connections existed, and still admits it', async () => {
+    const oauth = makeOAuthProvider(async () => ({
+      extra: { userId: 'user-5', userEmail: 'eve@example.com', connectionId: null },
+    }));
+    const mw = makeMw({ oauth });
+    const { req, res, next } = makeReqRes('Bearer bevel-mcp_token123');
+    await mw(req, res, next);
+    expect(req.userId).toBe('user-5');
+    expect(req.agentConnectionId).toBeUndefined();
+    expect(next).toHaveBeenCalled();
+  });
+
   it('401s with the discovery challenge when the OAuth token is invalid/expired/revoked', async () => {
     const mw = makeMw();
     const { req, res, next, setHeader, status } = makeReqRes('Bearer bevel-mcp_expired');
@@ -276,6 +294,46 @@ describe('createMcpAuthMiddleware', () => {
       expect(next).toHaveBeenCalled();
       expect(req.userId).toBe('user-7');
       expect(req.userEmail).toBe('seven@example.com');
+      // A plain loopback identity names no agent.
+      expect(req.agentConnectionId).toBeUndefined();
+    });
+
+    it('carries the agent connection of an exchanged grant, so the local server stays attributed', async () => {
+      const token = internal.mint({ userId: 'user-7', externalProxy: true, connectionId: 'conn-7' }, 60_000);
+      const auth = makeAuthService();
+      (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({
+        id: 'user-7',
+        email: 'seven@example.com',
+      }));
+      const oauth = makeOAuthProvider();
+      const mw = makeMw({ internal, auth, oauth });
+      const { req, res, next } = makeReqRes(`Bearer ${token}`);
+      await mw(req, res, next);
+      expect(next).toHaveBeenCalled();
+      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).noteConnectionUse).toHaveBeenCalledWith('conn-7');
+    });
+
+    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();
+      (auth.getUserById as ReturnType<typeof vi.fn>) = vi.fn(async () => ({
+        id: 'user-7',
+        email: 'seven@example.com',
+      }));
+      const oauth = makeOAuthProvider(undefined, async () => false);
+      const mw = makeMw({ internal, auth, oauth });
+      const { req, res, next, status, setHeader } = makeReqRes(`Bearer ${token}`);
+      await mw(req, res, next);
+      expect(next).not.toHaveBeenCalled();
+      expect(status).toHaveBeenCalledWith(401);
+      expect(setHeader).toHaveBeenCalledWith('WWW-Authenticate', expect.stringContaining('resource_metadata'));
+      expect(req.agentConnectionId).toBeUndefined();
+      // A refused request is no use of the connection.
+      expect((oauth as any).noteConnectionUse).not.toHaveBeenCalled();
     });
 
     it('401s an expired internal token', async () => {

package/src/modules/mcp/__tests__/mcp.routes.local-token.test.ts

@@ -74,7 +74,7 @@ async function exchange(baseUrl: string, authorization?: string): Promise<Respon
 describe('POST /mcp/local-token', () => {
   it('exchanges a valid OAuth access token for an internal token with the loopback identity + TTL', async () => {
     const oauth = makeOAuthProvider(async () => ({
-      extra: { userId: 'user-5', userEmail: 'eve@example.com' },
+      extra: { userId: 'user-5', userEmail: 'eve@example.com', connectionId: 'conn-9' },
       // A grant with plenty of life left: the loopback constant is the binding cap.
       expiresAt: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
     }));
@@ -88,21 +88,41 @@ describe('POST /mcp/local-token', () => {
     // above outlives it, so the constant is the cap that binds.
     expect(body.expiresInMs).toBe(MCP_LOOPBACK_TOKEN_TTL_MS);
     // The minted token verifies to the resolved user with the externalProxy
-    // flag — identical shape to the hosted session's loopback bearer.
-    expect(internalTokens.verify(body.token)).toEqual({ userId: 'user-5', externalProxy: true });
+    // flag — identical shape to the hosted session's loopback bearer — plus
+    // the grant's agent connection, so the local server's calls stay
+    // attributed to that agent in the Audit log.
+    expect(internalTokens.verify(body.token)).toEqual({
+      userId: 'user-5',
+      externalProxy: true,
+      connectionId: 'conn-9',
+    });
     // …and the tool-auth verifier resolves it to source 'external', exactly
     // how /api/agent/* will treat the local server.
     const verify = createTokenVerifier(
       { looksLikeExternalApiKey: () => false } as unknown as IExternalApiKeyService,
       internalTokens,
     );
+    // …carrying the agent connection, which the REST recorder attributes
+    // the local server's direct tool calls to.
     await expect(verify(body.token)).resolves.toEqual({
       ok: true,
-      auth: { source: 'external', userId: 'user-5', scope: 'write' },
+      auth: { source: 'external', userId: 'user-5', connectionId: 'conn-9', scope: 'write' },
     });
     expect((oauth as any).verifyAccessToken).toHaveBeenCalledWith('bevel-mcp_valid123');
   });
 
+  it('mints without a connection claim for a grant that carries none (a token from before connections existed)', async () => {
+    const oauth = makeOAuthProvider(async () => ({
+      extra: { userId: 'user-5', userEmail: 'eve@example.com' },
+      expiresAt: Math.floor(Date.now() / 1000) + 24 * 60 * 60,
+    }));
+    const { baseUrl, internalTokens } = await mount(oauth);
+    const res = await exchange(baseUrl, 'Bearer bevel-mcp_valid123');
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { token: string };
+    expect(internalTokens.verify(body.token)).toEqual({ userId: 'user-5', externalProxy: true });
+  });
+
   /**
    * The binding that keeps the exchange from OUTLIVING its grant: an access
    * token with less life left than the loopback constant caps the minted

package/src/modules/mcp/__tests__/mcp.routes.stateless.test.ts

@@ -108,7 +108,7 @@ describe('POST /mcp (stateless)', () => {
     expect((await messagesOf(res))[0].result.serverInfo.name).toBe('stub');
     // The messages reach the service, so it can tell an initialize apart.
     expect(mcpService.createRequestServer).toHaveBeenCalledWith(
-      { userId: 'user-A', tokenId: null, bearer: '' },
+      { userId: 'user-A', tokenId: null, connectionId: null, bearer: '' },
       INITIALIZE,
     );
   });

package/src/modules/mcp/__tests__/mcp.service.test.ts

@@ -12,6 +12,7 @@ import { createManualRoutes } from '../../tool-registry/manual.routes.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { toolDef } from '../../tool-helpers/tool-def.js';
 import { PLATFORM_HEADER, TOOL_PREFIX_LINE } from '../../agent-instructions/index.js';
+import type { AgentEventInput, IAgentEventRecorder } from '../../audit/audit.contract.js';
 
 /**
  * End-to-end proxy test: a real express app serving the registry-driven tool
@@ -43,6 +44,10 @@ async function setup(deps?: {
   readAgentPreamble?: () => Promise<string | null>;
   /** Extra echo tools to register under these names (the four KB tools, in the prefix tests). */
   extraTools?: string[];
+  /** The Audit log's recorder, when a test watches what gets recorded. */
+  auditRecorder?: IAgentEventRecorder;
+  /** The agent connection an OAuth caller arrived through (with `tokenId: null`). */
+  connectionId?: string | null;
 }) {
   const registry = new ToolRegistry();
   registry.registerExternalTool(
@@ -91,6 +96,16 @@ async function setup(deps?: {
     res.json({ text: `echo: ${b.prompt}`, sessionId: typeof b.sessionId === 'string' ? b.sessionId : 'new-sess' });
   });
   app.post('/api/agent/tools/boom', (_req, res) => res.status(500).json({ error: 'kaboom' }));
+  // The two the Audit log's skill classification reads through: a catalog of
+  // one skill, and a file read that answers for any path (registered as
+  // tools only by the tests that need them, via `extraTools`).
+  app.post('/api/agent/tools/list_skills', (_req, res) =>
+    res.json({ skills: [{ name: 'rfi', description: 'RFI answers', path: 'Plugins/Sales/rfi' }] }),
+  );
+  app.post('/api/agent/tools/read_file', (req, res) => {
+    const b = (req.body ?? {}) as { path?: string };
+    res.json({ content: `contents of ${b.path}` });
+  });
   // A live UTCP manual a catalog entry can point at — one tool, dispatched back
   // to the echo above. Mounted always (it costs one route) so a test can add a
   // MANUAL to the served catalog, not merely a tool to the registry: what a
@@ -149,10 +164,11 @@ async function setup(deps?: {
     deps?.toolManuals as any,
     undefined, // internalTokens — the fake loopback here accepts any bearer
     deps?.revokeOAuthAccess,
+    deps?.auditRecorder,
   );
   lastService = mcp;
   const tokenId = deps?.tokenId === undefined ? 'tok-1' : deps.tokenId;
-  return connectClient(mcp, tokenId);
+  return connectClient(mcp, tokenId, deps?.connectionId ?? null);
 }
 
 /** The service `setup` built last — for a test that needs a SECOND request against the same service. */
@@ -165,9 +181,9 @@ let lastService: McpService | undefined;
  * The initialize message is passed so the server carries instructions,
  * exactly as the route's initialize request would.
  */
-async function connectClient(mcp: McpService, tokenId: string | null): Promise<Client> {
+async function connectClient(mcp: McpService, tokenId: string | null, connectionId: string | null = null): Promise<Client> {
   const server = await mcp.createRequestServer(
-    { userId: 'user-A', tokenId, bearer: 'bevel_testkey' },
+    { userId: 'user-A', tokenId, connectionId, bearer: 'bevel_testkey' },
     { jsonrpc: '2.0', id: 0, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'test-client', version: '0.0.0' } } },
   );
 
@@ -680,3 +696,104 @@ describe('McpService — a collision ends when its sibling is renamed away', ()
     expect(survivor.some((m) => m.startsWith('[mcp] skipping manual "notion-eu": ') && !m.includes('rewrites to'))).toBe(true);
   });
 });
+
+describe('McpService — the Audit log records what an agent calls', () => {
+  /** A recorder that keeps every event, and the same thing as the proxy's collaborator type. */
+  function spyRecorder(): IAgentEventRecorder & { events: AgentEventInput[] } {
+    const events: AgentEventInput[] = [];
+    return { events, record: (e) => void events.push(e) };
+  }
+  const text = (res: Awaited<ReturnType<Client['callTool']>>) => (res.content as Array<{ text: string }>)[0].text;
+  // Recording is fire-and-forget behind the call; give the microtasks a turn.
+  const settle = () => new Promise((r) => setTimeout(r, 10));
+
+  it('records a direct platform tool call as a hexis capability under the connection key, with its outcome', async () => {
+    const recorder = spyRecorder();
+    const client = await setup({ auditRecorder: recorder });
+
+    await client.callTool({ name: 'ask', arguments: { body: { prompt: 'hello' } } });
+    await client.callTool({ name: 'boom', arguments: {} });
+    await settle();
+
+    expect(recorder.events).toHaveLength(2);
+    expect(recorder.events[0]).toMatchObject({
+      userId: 'user-A',
+      principal: { kind: 'key', id: 'tok-1' },
+      kind: 'capability',
+      manual: null,
+      name: 'ask',
+      outcome: 'ok',
+    });
+    expect(typeof recorder.events[0].durationMs).toBe('number');
+    // The tool answered with an error result — recorded as such, not as ok.
+    expect(recorder.events[1]).toMatchObject({ kind: 'capability', name: 'boom', outcome: 'error' });
+  });
+
+  it('records a chain as a capability AND each call made inside it', async () => {
+    const recorder = spyRecorder();
+    const client = await setup({ auditRecorder: recorder });
+
+    await client.callTool({
+      name: 'call_tool_chain',
+      arguments: { code: "KNOWLEDGE_BASE.ask({ body: { prompt: 'one' } }); return KNOWLEDGE_BASE.ask({ body: { prompt: 'two' } });" },
+    });
+    await settle();
+
+    const names = recorder.events.map((e) => `${e.kind}:${e.name}:${e.outcome}`);
+    // The two inner calls finish (and are recorded) before the chain itself.
+    expect(names).toEqual(['capability:ask:ok', 'capability:ask:ok', 'capability:call_tool_chain:ok']);
+  });
+
+  it('attributes an OAuth caller to its agent connection, and records nothing for a caller with neither', async () => {
+    const asAgent = spyRecorder();
+    const agent = await setup({ auditRecorder: asAgent, tokenId: null, connectionId: 'conn-1' });
+    await agent.callTool({ name: 'ask', arguments: { body: { prompt: 'hi' } } });
+    await settle();
+    expect(asAgent.events[0]).toMatchObject({ principal: { kind: 'agent', id: 'conn-1' }, name: 'ask' });
+
+    const nobody = spyRecorder();
+    const jwt = await setup({ auditRecorder: nobody, tokenId: null, connectionId: null });
+    await jwt.callTool({ name: 'ask', arguments: { body: { prompt: 'hi' } } });
+    await settle();
+    expect(nobody.events).toEqual([]);
+  });
+
+  it('records a read inside a skill folder as that skill, and a read elsewhere as the read', async () => {
+    const recorder = spyRecorder();
+    const client = await setup({ auditRecorder: recorder, extraTools: ['read_file', 'list_skills'] });
+
+    await client.callTool({ name: 'read_file', arguments: { body: { path: 'Plugins/Sales/rfi/SKILL.md' } } });
+    await client.callTool({ name: 'read_file', arguments: { body: { path: 'KnowledgeBase/Product/roadmap.md' } } });
+    await settle();
+
+    expect(recorder.events[0]).toMatchObject({ kind: 'skill', manual: 'Plugins/Sales/rfi', name: 'rfi', outcome: 'ok' });
+    expect(recorder.events[1]).toMatchObject({ kind: 'capability', manual: null, name: 'read_file', outcome: 'ok' });
+  });
+
+  it('records a prompt read as a skill, with an error outcome when the skill is unknown', async () => {
+    const recorder = spyRecorder();
+    const client = await setup({ auditRecorder: recorder });
+    // The harness serves no get_skill endpoint, so every prompt is unknown here.
+    await expect(client.getPrompt({ name: 'rfi' })).rejects.toThrow(/Unknown skill/);
+    await settle();
+    expect(recorder.events[0]).toMatchObject({ kind: 'skill', name: 'rfi', outcome: 'error' });
+  });
+
+  it('records a call refused for a missing sign-in as denied, without running the tool', async () => {
+    const recorder = spyRecorder();
+    const vault = { statusFor: async (_u: string, keys: string[]) => keys.map((key) => ({ key, adminConfigured: false, userConfigured: false })) };
+    const manuals = {
+      userScopedKeysForManual: async (manual: string) =>
+        manual === 'KNOWLEDGE_BASE' ? [{ key: 'KNOWLEDGE_BASE_API_KEY', name: 'API_KEY', label: 'Your API key', oauth: false }] : [],
+    };
+    const client = await setup({ auditRecorder: recorder, secretsVault: vault, toolManuals: manuals });
+
+    const res = await client.callTool({ name: 'ask', arguments: { body: { prompt: 'hello' } } });
+    await settle();
+
+    expect(text(res)).not.toMatch(/echo:/);
+    expect(recorder.events).toEqual([
+      expect.objectContaining({ kind: 'capability', name: 'ask', outcome: 'denied', durationMs: null }),
+    ]);
+  });
+});