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

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

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { logger } from '../../../shared/logging.js';
 
 const log = logger('mcp-oauth');
-import { and, eq, gt, isNull, lt, or } from 'drizzle-orm';
+import { and, count, eq, gt, isNull, lt, or, sql } from 'drizzle-orm';
 import type { Response } from 'express';
 import type {
   AuthorizationParams,
@@ -21,7 +21,7 @@ import type {
   OAuthTokens,
 } from '@modelcontextprotocol/sdk/shared/auth.js';
 import type { Database } from '../../database/connection.js';
-import { oauthAuthCodes, oauthClients, oauthTokens, users } from '../../database/schema.js';
+import { agentConnections, oauthAuthCodes, oauthClients, oauthTokens, users } from '../../database/schema.js';
 import type { TokenCrypto } from '../../../shared/token-crypto.js';
 import { signAuthRequest, type McpAuthRequestState } from './oauth-state.js';
 
@@ -34,6 +34,13 @@ const TOKEN_BYTES = 32;
 const ACCESS_TTL_MS = 60 * 60_000; // 1 hour
 const REFRESH_TTL_MS = 30 * 24 * 60 * 60_000; // 30 days, rotated on use
 const CODE_TTL_MS = 60_000; // exchanged within seconds of Finish
+/**
+ * How often, at most, one process stamps an agent connection's `last_used_at`.
+ * The Audit log shows the instant relatively ("4 minutes ago"), so a minute's
+ * staleness is invisible, while a write per request on a chain-heavy session
+ * would serialise hundreds of requests a minute on one row.
+ */
+const CONNECTION_TOUCH_INTERVAL_MS = 60_000;
 
 export interface BevelOAuthProviderDeps {
   db: Database;
@@ -66,6 +73,8 @@ export interface BevelOAuthProviderDeps {
  */
 export class BevelOAuthProvider implements OAuthServerProvider {
   private readonly store: OAuthRegisteredClientsStore;
+  /** When this process last stamped each connection's use — see {@link noteConnectionUse}. */
+  private readonly connectionTouchedAt = new Map<string, number>();
 
   constructor(private readonly deps: BevelOAuthProviderDeps) {
     this.store = {
@@ -276,15 +285,36 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       }
       scope = scopes.join(' ');
     }
-    return this.mintTokens(row.userId, row.clientId, scope, row.resource);
+    // A refresh STAYS on its token's agent connection and is refused once
+    // that connection is revoked. The connection is the authority on whether
+    // the agent may hold tokens at all: were a refresh to look the connection
+    // up afresh, one racing a revoke would find none live, make a new one and
+    // mint an unrevoked pair — the revoke undone by a millisecond. A token
+    // from before connections existed has none to stay on and is placed
+    // under one as a first mint would be.
+    if (row.connectionId) {
+      if (!(await this.isConnectionLive(row.connectionId))) {
+        throw new InvalidGrantError('Access for this agent was revoked');
+      }
+      this.noteConnectionUse(row.connectionId);
+    }
+    return this.mintTokens(row.userId, row.clientId, scope, row.resource, row.connectionId ?? undefined);
   }
 
   async verifyAccessToken(token: string): Promise<AuthInfo> {
     const now = new Date();
+    // The agent connection is joined so a token of a REVOKED connection fails
+    // here whatever its own row says: revoking an agent marks its tokens too,
+    // but the connection is the authority, and a token minted a moment after
+    // the revoke (a refresh that raced it) is dead on arrival rather than
+    // live until its own expiry. A token from before connections existed
+    // (null `connection_id`) has no connection to be revoked and verifies on
+    // its own row alone.
     const [row] = await this.deps.db
       .select({
         id: oauthTokens.id,
         clientId: oauthTokens.clientId,
+        connectionId: oauthTokens.connectionId,
         scope: oauthTokens.scope,
         resource: oauthTokens.resource,
         expiresAt: oauthTokens.expiresAt,
@@ -293,11 +323,13 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       })
       .from(oauthTokens)
       .innerJoin(users, eq(oauthTokens.userId, users.id))
+      .leftJoin(agentConnections, eq(oauthTokens.connectionId, agentConnections.id))
       .where(
         and(
           eq(oauthTokens.accessTokenHash, hashToken(token)),
           isNull(oauthTokens.revokedAt),
           gt(oauthTokens.expiresAt, now),
+          or(isNull(oauthTokens.connectionId), isNull(agentConnections.revokedAt)),
         ),
       )
       .limit(1);
@@ -311,13 +343,22 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       .set({ lastUsedAt: now })
       .where(eq(oauthTokens.id, row.id))
       .then(undefined, (err) => log.warn('touch lastUsedAt failed:', { err }));
+    // The agent connection's own "last used" — what the Audit log shows for
+    // the agent, across every token it has held. Throttled, never awaited.
+    if (row.connectionId) this.noteConnectionUse(row.connectionId);
     return {
       token,
       clientId: row.clientId,
       scopes: (row.scope ?? '').split(' ').filter(Boolean),
       expiresAt: Math.floor(row.expiresAt.getTime() / 1000),
       resource: row.resource ? new URL(row.resource) : undefined,
-      extra: { userId: row.userId, userEmail: row.userEmail },
+      extra: {
+        userId: row.userId,
+        userEmail: row.userEmail,
+        // Null on a token minted before connections existed; the auth
+        // middleware then binds no agent and the call goes unrecorded.
+        connectionId: row.connectionId,
+      },
     };
   }
 
@@ -343,7 +384,7 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     // RFC 7009: revoking an unknown/foreign/already-revoked token is a no-op.
     // The token may be either half of a pair — one UPDATE matching either hash.
     const hash = hashToken(request.token);
-    await this.deps.db
+    const revoked = await this.deps.db
       .update(oauthTokens)
       .set({ revokedAt: new Date() })
       .where(
@@ -352,14 +393,39 @@ export class BevelOAuthProvider implements OAuthServerProvider {
           isNull(oauthTokens.revokedAt),
           or(eq(oauthTokens.accessTokenHash, hash), eq(oauthTokens.refreshTokenHash, hash)),
         ),
-      );
+      )
+      .returning({ connectionId: oauthTokens.connectionId });
+    // A client revoking its own token is signing out. When that leaves the
+    // agent connection with no live token at all, the connection is over
+    // too — disconnected by its owner, as the Audit log then says — rather
+    // than listed as live forever with nothing behind it. (The proxy's own
+    // reset of a broken sign-in goes through `revokeByAccessToken`, not
+    // here, and must NOT close the connection: that agent is being sent
+    // back to re-authorise into the same one.)
+    const connectionId = revoked.find((r) => r.connectionId)?.connectionId;
+    if (!connectionId) return;
+    const [{ live }] = await this.deps.db
+      .select({ live: count() })
+      .from(oauthTokens)
+      .where(and(eq(oauthTokens.connectionId, connectionId), isNull(oauthTokens.revokedAt)));
+    if (Number(live) > 0) return;
+    await this.deps.db
+      .update(agentConnections)
+      .set({ revokedAt: new Date(), revokedBy: 'owner' })
+      .where(and(eq(agentConnections.id, connectionId), isNull(agentConnections.revokedAt)));
   }
 
+  /**
+   * @param connectionId The agent connection the pair belongs to, when the
+   *   caller already holds one (a refresh: the consumed token's). Absent on a
+   *   first mint, which finds or makes the live connection for (user, client).
+   */
   private async mintTokens(
     userId: string,
     clientId: string,
     scope: string | null,
     resource: string | null,
+    connectionId?: string,
   ): Promise<OAuthTokens> {
     const accessToken = this.deps.tokenPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
     const refreshToken = this.refreshPrefix + randomBytes(TOKEN_BYTES).toString('base64url');
@@ -382,11 +448,13 @@ export class BevelOAuthProvider implements OAuthServerProvider {
     } catch (err) {
       log.warn('token-table prune failed (non-fatal):', { err });
     }
+    const boundTo = connectionId ?? (await this.ensureConnection(userId, clientId));
     await this.deps.db.insert(oauthTokens).values({
       accessTokenHash: hashToken(accessToken),
       refreshTokenHash: hashToken(refreshToken),
       clientId,
       userId,
+      connectionId: boundTo,
       scope,
       resource,
       expiresAt: new Date(now + ACCESS_TTL_MS),
@@ -400,6 +468,116 @@ export class BevelOAuthProvider implements OAuthServerProvider {
       ...(scope ? { scope } : {}),
     };
   }
+
+  /**
+   * The live `agent_connections` row for (user, client) — found, or made on
+   * the first mint for the pair. A refresh finds the row the sign-in made, so
+   * one connection spans every token the agent ever holds; a mint after a
+   * revoke finds nothing live and makes a fresh row, which is what keeps the
+   * revoked one's history intact.
+   *
+   * Two concurrent first mints (a client racing its own token exchange) both
+   * miss the select; the partial unique index lets exactly one insert land,
+   * the other's `ON CONFLICT DO NOTHING` returns no row, and it re-reads the
+   * winner's. The client's display name is snapshotted from its registration
+   * at that moment.
+   */
+  /**
+   * Whether an agent connection still admits requests: it exists and nobody
+   * has revoked it. Asked on every refresh, and by the MCP auth middleware on
+   * every request through the local server's exchanged grant — the one path
+   * where a token verifies statelessly and would otherwise outlive the
+   * revoke. A read, not a write: the use is stamped separately, throttled.
+   */
+  async isConnectionLive(connectionId: string): Promise<boolean> {
+    const [row] = await this.deps.db
+      .select({ id: agentConnections.id })
+      .from(agentConnections)
+      .where(and(eq(agentConnections.id, connectionId), isNull(agentConnections.revokedAt)))
+      .limit(1);
+    return row !== undefined;
+  }
+
+  /**
+   * Record that an agent connection is in use — its `last_used_at` on the
+   * Audit log — at most once a minute per connection per process, and never
+   * on the caller's critical path. The stamp is what the page shows; the
+   * liveness decision above never depends on it.
+   */
+  noteConnectionUse(connectionId: string): void {
+    const now = Date.now();
+    const last = this.connectionTouchedAt.get(connectionId);
+    if (last !== undefined && now - last < CONNECTION_TOUCH_INTERVAL_MS) return;
+    this.connectionTouchedAt.set(connectionId, now);
+    this.deps.db
+      .update(agentConnections)
+      .set({ lastUsedAt: new Date(now) })
+      .where(eq(agentConnections.id, connectionId))
+      .then(undefined, (err) => log.warn('touch connection lastUsedAt failed:', { err }));
+  }
+
+  /**
+   * The live `agent_connections` row for (user, agent) — found, or made on
+   * the first mint for the pair. The AGENT is the registered client's name,
+   * folded (see the schema): a client that registers itself afresh on every
+   * re-authorisation, as Claude does, lands every registration on the one
+   * row rather than a row per client id. A refresh finds the row the sign-in
+   * made, so one connection spans every token the agent ever holds; a mint
+   * after a revoke finds nothing live and makes a fresh row, which is what
+   * keeps the revoked one's history intact.
+   *
+   * Two concurrent first mints (a client racing its own token exchange) both
+   * miss the select; the partial unique index lets exactly one insert land,
+   * the other's `ON CONFLICT DO NOTHING` returns no row, and it re-reads the
+   * winner's. The client's display name is snapshotted from its registration
+   * at that moment.
+   */
+  private async ensureConnection(userId: string, clientId: string): Promise<string> {
+    const [client] = await this.deps.db
+      .select({ clientName: oauthClients.clientName })
+      .from(oauthClients)
+      .where(eq(oauthClients.clientId, clientId))
+      .limit(1);
+    const clientName = client?.clientName ?? null;
+    const agentKey = agentKeyFor(clientName, clientId);
+    const live = () =>
+      this.deps.db
+        .select({ id: agentConnections.id })
+        .from(agentConnections)
+        .where(
+          and(
+            eq(agentConnections.userId, userId),
+            eq(agentConnections.agentKey, agentKey),
+            isNull(agentConnections.revokedAt),
+          ),
+        )
+        .limit(1);
+    const [existing] = await live();
+    if (existing) return existing.id;
+    const [inserted] = await this.deps.db
+      .insert(agentConnections)
+      .values({ userId, clientId, clientName, agentKey })
+      .onConflictDoNothing({
+        target: [agentConnections.userId, agentConnections.agentKey],
+        where: sql`${agentConnections.revokedAt} is null`,
+      })
+      .returning({ id: agentConnections.id });
+    if (inserted) return inserted.id;
+    const [winner] = await live();
+    if (!winner) throw new Error('agent connection vanished between insert and re-read');
+    return winner.id;
+  }
+}
+
+/**
+ * What an agent connection is keyed by: the registered client name, folded
+ * (case and surrounding whitespace are not identity), or the client id for
+ * a registration that carried no name. The SAME fold the migration applied
+ * to the rows that existed before the key did.
+ */
+export function agentKeyFor(clientName: string | null, clientId: string): string {
+  const folded = (clientName ?? '').trim().toLowerCase();
+  return folded || clientId;
 }
 
 function hashToken(plaintext: string): string {

package/src/modules/settings/__tests__/deployment-settings.service.test.ts

@@ -84,6 +84,41 @@ describe('DeploymentSettingsService — precedence', () => {
   });
 });
 
+describe('DeploymentSettingsService — a blank that means the default', () => {
+  /**
+   * The rule everywhere else: a blank field leaves a setting alone. The Audit
+   * log's retention window is the exception that declares itself — its
+   * readers already treat "unset" as the default, so clearing the field is
+   * the one way back to that default, and a blank saves as a clear.
+   */
+  it('clears a blank-means-default setting on a blank save and leaves every other blank alone', async () => {
+    const { db, rows } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    await settings.save({ auditRetentionDays: '30', kbRepoUrl: 'https://example.com/stored.git' }, null);
+    expect(settings.resolve('auditRetentionDays')).toBe('30');
+
+    await settings.save({ auditRetentionDays: '', kbRepoUrl: '' }, null);
+
+    expect(settings.resolve('auditRetentionDays')).toBe('');
+    expect(settings.sourceOf('auditRetentionDays')).toBe('unset');
+    // The repository address was blank too, and blank still means "leave it".
+    expect(settings.resolve('kbRepoUrl')).toBe('https://example.com/stored.git');
+    expect(rows.some((r) => r.key === 'kbRepoUrl')).toBe(true);
+  });
+
+  it('holds the retention window to the same rule on save as the runtime reader does', async () => {
+    const { db } = makeDb();
+    const settings = new DeploymentSettingsService(db, ENC_KEY);
+    for (const bad of ['1.5', 'lots', 'ten days']) {
+      await expect(settings.save({ auditRetentionDays: bad }, null)).rejects.toBeInstanceOf(SettingsValidationError);
+    }
+    // A number of days, or zero / negative for "forever" — the reader's rule.
+    for (const ok of ['3650', '0', '-1', '99999']) {
+      await expect(settings.save({ auditRetentionDays: ok }, null)).resolves.toBeDefined();
+    }
+  });
+});
+
 describe('DeploymentSettingsService — secrets', () => {
   it('stores the token as ciphertext and reads it back', async () => {
     const { db, rows } = makeDb();

package/src/modules/settings/deployment-settings.service.ts

@@ -15,6 +15,7 @@ import {
 import { createHmac } from 'node:crypto';
 import { TokenCrypto } from '../../shared/token-crypto.js';
 import { assertKbDirNameFree } from '../kb-fs/repo-path.js';
+import { parseRetentionWindow } from '../audit/audit.contract.js';
 import { normalizeIssuerUrl } from './oidc-check.js';
 
 /**
@@ -39,7 +40,7 @@ export interface SettingDef {
    */
   envVar?: string;
   /** Which block of the setup screen it belongs to. */
-  section: 'knowledge-base' | 'sign-in';
+  section: 'knowledge-base' | 'sign-in' | 'audit';
   secret?: boolean;
   /** Applied on save; the message is shown against the field. */
   validate?(value: string): string | null;
@@ -49,6 +50,14 @@ export interface SettingDef {
    * was copied into a service at construction is not.
    */
   restartToApply?: boolean;
+  /**
+   * A blank field on save CLEARS the stored value, putting the default back.
+   * The rule everywhere else is that blank means "leave it alone" — a stray
+   * Enter must not unconfigure a repository — and that stays the rule; this
+   * is for a setting whose readers already treat "unset" as its default, so
+   * clearing it is the one way back to that default and never a loss.
+   */
+  blankMeansDefault?: boolean;
   /**
    * What an UNSET setting already means to the code that reads it — the
    * layout's defaults, the pointer consent's "on unless turned off".
@@ -285,6 +294,23 @@ export const CORE_SETTINGS: SettingDef[] = [
     section: 'sign-in',
     restartToApply: true,
   },
+
+  {
+    /**
+     * How long the Audit log keeps an agent's events: a number of days, or
+     * — blank, zero, negative — forever. Read at every prune, so it applies
+     * without a restart. The window's rule lives with the audit service and
+     * is applied here on save and there on every read, so the environment
+     * variable is held to exactly what the Deployment page is. A blanked
+     * field clears the stored value, which is how "forever" is chosen back.
+     */
+    key: 'auditRetentionDays',
+    envVar: 'AUDIT_RETENTION_DAYS',
+    section: 'audit',
+    blankMeansDefault: true,
+    validate: (v) =>
+      parseRetentionWindow(v) === null ? 'Enter a whole number of days, or 0 to keep events forever.' : null,
+  },
 ];
 
 /**
@@ -577,10 +603,13 @@ export class DeploymentSettingsService {
     entries: Record<string, string>,
     updatedBy: string | null,
   ): Promise<{ restartRequired: boolean; restartKeys: string[] }> {
-    const toWrite = this.plan(entries);
+    const { toWrite, toClear } = this.plan(entries);
 
     /** The settings this save changed that a running server cannot pick up. */
     const restartKeys: string[] = [];
+    // A blanked blank-means-default setting: its row goes, and its readers
+    // are back on the default from the next read.
+    for (const key of toClear) await this.clear(key);
     for (const { key, value, def } of toWrite) {
       // Compared against the EFFECTIVE value: a setting that was unset was
       // already running on whatever its readers make of "unset" — the layout
@@ -615,14 +644,19 @@ export class DeploymentSettingsService {
    * before letting the save happen.
    */
   resolveAfter(entries: Record<string, string>): (key: string) => string {
-    const toWrite = this.plan(entries);
-    return (key) => toWrite.find((w) => w.key === key)?.value ?? this.resolve(key);
+    const { toWrite, toClear } = this.plan(entries);
+    return (key) =>
+      toClear.includes(key) ? '' : (toWrite.find((w) => w.key === key)?.value ?? this.resolve(key));
   }
 
-  /** Validate a batch and return the writes it amounts to; throws on any problem. */
-  private plan(entries: Record<string, string>): { key: string; value: string; def: SettingDef }[] {
+  /** Validate a batch and return the writes (and the clears) it amounts to; throws on any problem. */
+  private plan(entries: Record<string, string>): {
+    toWrite: { key: string; value: string; def: SettingDef }[];
+    toClear: string[];
+  } {
     const problems: Record<string, string> = {};
     const toWrite: { key: string; value: string; def: SettingDef }[] = [];
+    const toClear: string[] = [];
 
     for (const [key, raw] of Object.entries(entries)) {
       const def = this.defs.get(key);
@@ -638,7 +672,12 @@ export class DeploymentSettingsService {
       // An empty field means "leave it alone", not "erase it". Clearing a
       // setting is not something the setup screen offers, and treating a blank
       // input as a delete would let a stray Enter unconfigure a deployment.
-      if (!value) continue;
+      // The one exception is a setting that SAYS a blank is its default (see
+      // `SettingDef.blankMeansDefault`): for it a blank clears the stored row.
+      if (!value) {
+        if (def.blankMeansDefault) toClear.push(key);
+        continue;
+      }
       const problem = def.validate?.(value);
       if (problem) {
         problems[key] = problem;
@@ -722,7 +761,7 @@ export class DeploymentSettingsService {
     }
 
     if (Object.keys(problems).length > 0) throw new SettingsValidationError(problems);
-    return toWrite;
+    return { toWrite, toClear };
   }
 
   /** Drop stored rows for settings this build no longer defines. */

package/src/modules/tool-auth/__tests__/external-api-key.service.test.ts

@@ -149,6 +149,7 @@ describe('ExternalApiKeyService', () => {
         lastUsedAt: null,
         revokedAt: null,
         revokedBy: null,
+        deletedAt: null,
       });
     });
 
@@ -303,6 +304,7 @@ describe('ExternalApiKeyService', () => {
         lastUsedAt: rows[0].lastUsedAt!.getTime(),
         revokedAt: null,
         revokedBy: null,
+        deletedAt: null,
       });
       expect(summaries[1].revokedAt).toBe(rows[1].revokedAt!.getTime());
       // sanity-check that ordering was requested (we can't introspect the
@@ -333,6 +335,7 @@ describe('ExternalApiKeyService', () => {
           lastUsedAt: aliceKey.lastUsedAt!.getTime(),
           revokedAt: null,
           revokedBy: null,
+          deletedAt: null,
           user: { id: 'u-alice', email: 'alice@example.com', name: 'Alice' },
         },
         {
@@ -343,6 +346,7 @@ describe('ExternalApiKeyService', () => {
           lastUsedAt: null,
           revokedAt: bobKey.revokedAt!.getTime(),
           revokedBy: null,
+          deletedAt: null,
           user: { id: 'u-bob', email: 'bob@example.com', name: 'Bob' },
         },
       ]);
@@ -439,9 +443,9 @@ describe('ExternalApiKeyService', () => {
   });
 
   describe('remove', () => {
-    it('validates then deletes the key (dependents cascade at the DB layer)', async () => {
-      // Queue: SELECT finds a revoked row; then the key delete consumes one.
-      const { db } = makeFakeDb([
+    it('validates then marks the key deleted — the row stays, for the Audit log', async () => {
+      // Queue: SELECT finds a revoked row; then the marking update consumes one.
+      const { db, calls } = makeFakeDb([
         [{ revokedAt: new Date('2026-02-01T00:00:00Z') }],
         undefined,
       ]);
@@ -449,12 +453,29 @@ describe('ExternalApiKeyService', () => {
 
       await service.remove('tok-1', 'user-1');
 
-      // Validation SELECT first, then ONE delete of the key row. Dependent
-      // rows (e.g. llm_usage metering) are removed by ON DELETE CASCADE —
-      // this service must not know those tables exist.
+      // Validation SELECT first, then ONE update of the key row and never a
+      // delete: the Audit log's events hang off this row, and a key's owner
+      // deleting it must not erase what it did. Only a revoked, not-yet-
+      // deleted row of the owner's is marked.
       expect((db as any).select).toHaveBeenCalledTimes(1);
-      expect((db as any).delete).toHaveBeenCalledTimes(1);
-      expect((db as any).delete).toHaveBeenCalledWith(externalApiKeys);
+      expect((db as any).delete).not.toHaveBeenCalled();
+      expect((db as any).update).toHaveBeenCalledTimes(1);
+      expect((db as any).update).toHaveBeenCalledWith(externalApiKeys);
+      expect(calls.set[0]![0].deletedAt).toBeInstanceOf(Date);
+      const mark = renderSql(calls.where[1]![0]).sql;
+      expect(mark).toMatch(/"api_tokens"."user_id" = \$2/);
+      expect(mark).toMatch(/"api_tokens"."revoked_at" is not null/);
+      expect(mark).toMatch(/"api_tokens"."deleted_at" is null/);
+    });
+
+    it('treats an already-deleted key as absent for its owner', async () => {
+      // The validation SELECT carries the not-deleted filter, so a deleted
+      // row answers nothing — and nothing is marked twice.
+      const { db, calls } = makeFakeDb([[]]);
+      const service = new ExternalApiKeyService(db, 'bevel_');
+      await expect(service.remove('tok-1', 'user-1')).rejects.toBeInstanceOf(TokenNotFoundError);
+      expect(renderSql(calls.where[0]![0]).sql).toMatch(/"api_tokens"."deleted_at" is null/);
+      expect((db as any).update).not.toHaveBeenCalled();
     });
 
     it('throws TokenStillActiveError when the token exists but was never disconnected', async () => {

package/src/modules/tool-auth/__tests__/internal-token.service.test.ts

@@ -22,6 +22,12 @@ describe('InternalTokenService', () => {
     expect(svc.verify(token)).toEqual({ userId: 'user-A', externalProxy: true });
   });
 
+  it('round-trips the connectionId claim (the agent behind an exchanged OAuth grant)', () => {
+    const svc = new InternalTokenService({ secret: 'test-secret' });
+    const token = svc.mint({ userId: 'user-A', externalProxy: true, connectionId: 'conn-1' });
+    expect(svc.verify(token)).toEqual({ userId: 'user-A', externalProxy: true, connectionId: 'conn-1' });
+  });
+
   it('round-trips the focusedBranch claim (the in-process agent workspace branch)', () => {
     const svc = new InternalTokenService({ secret: 'test-secret' });
     const token = svc.mint({ userId: 'user-A', sessionId: 'run-1', focusedBranch: 'main' });

package/src/modules/tool-auth/external-api-key.interface.ts

@@ -37,6 +37,12 @@ export interface ExternalApiKeySummary {
    * before this was recorded, which read as the owner's doing).
    */
   revokedBy: RevokedBy | null;
+  /**
+   * When the owner deleted the key for good from their own pages. Such a
+   * key is absent from the owner's listings and shown to admins as deleted;
+   * its row stays so the Audit log's events keep their principal.
+   */
+  deletedAt: number | null;
 }
 
 /** Who revoked a key: its owner, or an admin acting across the deployment. */
@@ -137,6 +143,13 @@ export interface IExternalApiKeyService {
   /** Active + revoked tokens for the user, newest-first. */
   listForUser(userId: string): Promise<ExternalApiKeySummary[]>;
 
+  /**
+   * The account a key belongs to, live or revoked, or null when no such key
+   * exists. The ownership check behind a per-key read or revoke that is
+   * offered to owners and admins alike (the Audit log's).
+   */
+  ownerOf(id: string): Promise<string | null>;
+
   /**
    * Mark a token revoked. Idempotent — revoking an already-revoked token
    * is a no-op (the row's `revokedAt` is not overwritten). Throws
@@ -161,11 +174,15 @@ export interface IExternalApiKeyService {
   revokeAny(id: string): Promise<void>;
 
   /**
-   * Permanently delete a token row, dropping its audit trail. Only permitted
-   * on an already-revoked token — an active key must be disconnected first,
-   * so a live agent's access is never yanked by a single click. Throws
-   * TokenNotFoundError if the token doesn't belong to the user, and
-   * TokenStillActiveError if it hasn't been revoked yet.
+   * Delete a token for good, from the owner's point of view: it leaves their
+   * listings and can never be used or reconnected. The row itself stays,
+   * marked deleted, so the Audit log keeps the key's events under their
+   * principal — a log its subject could erase would not be one. Only
+   * permitted on an already-revoked token — an active key must be
+   * disconnected first, so a live agent's access is never yanked by a single
+   * click. Throws TokenNotFoundError if the token doesn't belong to the user
+   * (or is already deleted), and TokenStillActiveError if it hasn't been
+   * revoked yet.
    */
   remove(id: string, userId: string): Promise<void>;
 }