@kortix/agent-tunnel 0.1.4 → 0.12.7

package/src/server/ws-handler.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, test } from 'bun:test';
+import { signMessage } from '../shared/crypto';
+import { TunnelRelay } from './relay';
+import { createWsHandlers } from './ws-handler';
+
+interface FakeSocket extends WebSocket {
+  sent: string[];
+  closes: Array<{ code?: number; reason?: string }>;
+}
+
+function fakeWs(): FakeSocket {
+  const socket = {
+    readyState: WebSocket.OPEN,
+    sent: [] as string[],
+    closes: [] as Array<{ code?: number; reason?: string }>,
+    send(data: string) {
+      this.sent.push(data);
+    },
+    close(code?: number, reason?: string) {
+      this.closes.push({ code, reason });
+    },
+  };
+  return socket as unknown as FakeSocket;
+}
+
+function throwingWs(): FakeSocket {
+  const socket = fakeWs();
+  socket.send = () => {
+    throw new Error('socket closed');
+  };
+  return socket;
+}
+
+describe('tunnel WebSocket identity binding', () => {
+  test('passes the exact live capability registration into authentication', async () => {
+    const relay = new TunnelRelay();
+    let receivedAuth: unknown;
+    const handlers = createWsHandlers(relay, {
+      onAuthenticate: async (_tunnelId, _token, auth) => {
+        receivedAuth = auth;
+        return { signingKey: 'session-key', metadata: { capabilities: auth.capabilities } };
+      },
+    });
+    const socket = fakeWs();
+    handlers.onOpen('tunnel-1', socket);
+    await handlers.onMessage(
+      'tunnel-1',
+      socket,
+      JSON.stringify({
+        type: 'auth',
+        token: 'legitimate-token',
+        capabilities: ['filesystem', 'desktop'],
+        agentVersion: '0.1.2',
+      }),
+    );
+
+    expect(receivedAuth).toEqual({
+      type: 'auth',
+      token: 'legitimate-token',
+      capabilities: ['filesystem', 'desktop'],
+      agentVersion: '0.1.2',
+    });
+    expect(relay.getAgentMetadata('tunnel-1')?.capabilities).toEqual([
+      'filesystem',
+      'desktop',
+    ]);
+  });
+
+  test('authenticates the socket that supplied the credential during a same-tunnel race', async () => {
+    const relay = new TunnelRelay();
+    const handlers = createWsHandlers(relay, {
+      onAuthenticate: async (_tunnelId, token) =>
+        token === 'legitimate-token' ? { signingKey: 'session-key' } : null,
+    });
+    const legitimate = fakeWs();
+    const racing = fakeWs();
+
+    handlers.onOpen('tunnel-1', legitimate);
+    handlers.onOpen('tunnel-1', racing);
+    await handlers.onMessage(
+      'tunnel-1',
+      legitimate,
+      JSON.stringify({ type: 'auth', token: 'legitimate-token' }),
+    );
+
+    expect(legitimate.sent).toHaveLength(1);
+    expect(JSON.parse(legitimate.sent[0]!)).toEqual({
+      type: 'auth_ok',
+      signingKey: 'session-key',
+    });
+    expect(racing.sent).toEqual([]);
+    expect(relay.isConnected('tunnel-1')).toBe(true);
+
+    await handlers.onMessage(
+      'tunnel-1',
+      racing,
+      JSON.stringify({ type: 'auth', token: 'wrong-token' }),
+    );
+    expect(racing.closes).toContainEqual({ code: 4001, reason: 'authentication failed' });
+    expect(relay.isConnected('tunnel-1')).toBe(true);
+  });
+
+  test('discards signed messages from a socket after that socket was replaced', () => {
+    const relay = new TunnelRelay();
+    const first = fakeWs();
+    const second = fakeWs();
+    const pongs: unknown[] = [];
+    relay.on('message:pong', (event) => pongs.push(event));
+    relay.registerAgent('tunnel-1', first, 'old-key');
+    relay.registerAgent('tunnel-1', second, 'new-key');
+
+    const payload = {
+      jsonrpc: '2.0' as const,
+      method: 'tunnel.pong',
+      params: { source: 'old-socket' },
+    };
+    const raw = JSON.stringify({
+      ...payload,
+      _sig: signMessage('old-key', JSON.stringify(payload), 1),
+      _nonce: 1,
+    });
+    relay.handleAgentMessage('tunnel-1', first, raw);
+
+    expect(pongs).toEqual([]);
+  });
+
+  test('does not register a socket that cannot receive the session key', async () => {
+    const relay = new TunnelRelay();
+    const handlers = createWsHandlers(relay, {
+      onAuthenticate: async () => ({ signingKey: 'session-key' }),
+    });
+    const socket = throwingWs();
+    handlers.onOpen('tunnel-1', socket);
+
+    await handlers.onMessage(
+      'tunnel-1',
+      socket,
+      JSON.stringify({ type: 'auth', token: 'legitimate-token' }),
+    );
+
+    expect(relay.isConnected('tunnel-1')).toBe(false);
+    expect(socket.closes).toContainEqual({
+      code: 4001,
+      reason: 'authentication response failed',
+    });
+  });
+
+  test('closes an authenticated socket after an oversized message', () => {
+    const relay = new TunnelRelay();
+    const handlers = createWsHandlers(relay, { maxMessageSize: 8 });
+    const socket = fakeWs();
+    relay.registerAgent('tunnel-1', socket, 'session-key');
+
+    handlers.onMessage('tunnel-1', socket, '123456789');
+
+    expect(socket.closes).toContainEqual({ code: 4002, reason: 'message too large' });
+  });
+});

package/src/server/ws-handler.ts

@@ -5,14 +5,18 @@ import type { TunnelAuthMessage, AuthResult } from '../shared/types';
 export interface WsHandlerOptions {
   heartbeat?: HeartbeatManager;
   maxMessageSize?: number;
-  onAuthenticate?: (tunnelId: string, token: string) => Promise<AuthResult | null>;
+  onAuthenticate?: (
+    tunnelId: string,
+    token: string,
+    auth: TunnelAuthMessage,
+  ) => Promise<AuthResult | null>;
   authTimeoutMs?: number;
 }
 
 export interface WsHandlers {
   onOpen(tunnelId: string, ws: WebSocket): void;
-  onMessage(tunnelId: string, message: string | Buffer): void;
-  onClose(tunnelId: string): void;
+  onMessage(tunnelId: string, ws: WebSocket, message: string | Buffer): void;
+  onClose(tunnelId: string, ws?: WebSocket): void;
 }
 
 export function createWsHandlers(relay: TunnelRelay, opts?: WsHandlerOptions): WsHandlers {
@@ -21,96 +25,150 @@ export function createWsHandlers(relay: TunnelRelay, opts?: WsHandlerOptions): W
   const onAuthenticate = opts?.onAuthenticate;
   const authTimeoutMs = opts?.authTimeoutMs ?? 10_000;
 
-  const pendingConnections = new Map<string, { ws: WebSocket; timer: ReturnType<typeof setTimeout> }>();
+  const pendingConnections = new Map<
+    WebSocket,
+    {
+      tunnelId: string;
+      timer: ReturnType<typeof setTimeout>;
+      authenticating: boolean;
+    }
+  >();
 
   return {
     onOpen(tunnelId: string, ws: WebSocket) {
       const timer = setTimeout(() => {
-        pendingConnections.delete(tunnelId);
-        try { ws.close(4001, 'auth timeout'); } catch {}
+        pendingConnections.delete(ws);
+        try {
+          ws.close(4001, 'auth timeout');
+        } catch {}
       }, authTimeoutMs);
 
-      pendingConnections.set(tunnelId, { ws, timer });
+      pendingConnections.set(ws, { tunnelId, timer, authenticating: false });
     },
 
-    async onMessage(tunnelId: string, message: string | Buffer) {
+    async onMessage(tunnelId: string, ws: WebSocket, message: string | Buffer) {
       const msgStr = typeof message === 'string' ? message : message.toString('utf-8');
-      const msgSize = typeof message === 'string' ? message.length : (message as Buffer).byteLength;
+      const msgSize =
+        typeof message === 'string'
+          ? Buffer.byteLength(message, 'utf8')
+          : (message as Buffer).byteLength;
 
       if (msgSize > maxMessageSize) {
-        console.warn(`[tunnel-ws] Oversized message from ${tunnelId}: ${msgSize} bytes (limit: ${maxMessageSize})`);
-        const pending = pendingConnections.get(tunnelId);
-        const ws = pending?.ws;
-        if (ws) {
-          try { ws.close(4002, 'message too large'); } catch {}
+        console.warn(
+          `[tunnel-ws] Oversized message from ${tunnelId}: ${msgSize} bytes (limit: ${maxMessageSize})`,
+        );
+        try {
+          ws.close(4002, 'message too large');
+        } catch {}
+        if (pendingConnections.has(ws)) {
+          const pending = pendingConnections.get(ws);
+          if (pending) clearTimeout(pending.timer);
+          pendingConnections.delete(ws);
         }
         return;
       }
 
-      const pending = pendingConnections.get(tunnelId);
+      const pending = pendingConnections.get(ws);
       if (pending) {
+        if (pending.tunnelId !== tunnelId) {
+          clearTimeout(pending.timer);
+          pendingConnections.delete(ws);
+          try {
+            ws.close(4001, 'tunnel identity mismatch');
+          } catch {}
+          return;
+        }
+        if (pending.authenticating) return;
         let authMsg: TunnelAuthMessage;
         try {
           authMsg = JSON.parse(msgStr);
         } catch {
-          try { pending.ws.close(4001, 'invalid auth message'); } catch {}
+          try {
+            ws.close(4001, 'invalid auth message');
+          } catch {}
           clearTimeout(pending.timer);
-          pendingConnections.delete(tunnelId);
+          pendingConnections.delete(ws);
           return;
         }
 
         if (authMsg.type !== 'auth' || !authMsg.token) {
-          try { pending.ws.close(4001, 'expected auth message'); } catch {}
+          try {
+            ws.close(4001, 'expected auth message');
+          } catch {}
           clearTimeout(pending.timer);
-          pendingConnections.delete(tunnelId);
+          pendingConnections.delete(ws);
           return;
         }
 
-        clearTimeout(pending.timer);
-        pendingConnections.delete(tunnelId);
-
         if (!onAuthenticate) {
-          try { pending.ws.close(4001, 'no authenticator configured'); } catch {}
+          clearTimeout(pending.timer);
+          pendingConnections.delete(ws);
+          try {
+            ws.close(4001, 'no authenticator configured');
+          } catch {}
           return;
         }
 
+        pending.authenticating = true;
         try {
-          const result = await onAuthenticate(tunnelId, authMsg.token);
+          const result = await onAuthenticate(tunnelId, authMsg.token, authMsg);
+          if (pendingConnections.get(ws) !== pending || ws.readyState !== WebSocket.OPEN) {
+            return;
+          }
+          clearTimeout(pending.timer);
+          pendingConnections.delete(ws);
           if (!result) {
-            try { pending.ws.close(4001, 'authentication failed'); } catch {}
+            try {
+              ws.close(4001, 'authentication failed');
+            } catch {}
             return;
           }
 
-          // Send signing key to agent so it never needs the server secret
+          // Send signing key to agent so it never needs the server secret.
+          // A socket that cannot receive the key must never become active.
           try {
-            pending.ws.send(JSON.stringify({ type: 'auth_ok', signingKey: result.signingKey }));
-          } catch {}
+            ws.send(
+              JSON.stringify({
+                type: 'auth_ok',
+                signingKey: result.signingKey,
+              }),
+            );
+          } catch {
+            try {
+              ws.close(4001, 'authentication response failed');
+            } catch {}
+            return;
+          }
 
-          relay.registerAgent(tunnelId, pending.ws, result.signingKey, result.metadata);
+          relay.registerAgent(tunnelId, ws, result.signingKey, result.metadata);
           if (heartbeat) {
             heartbeat.register(tunnelId);
           }
         } catch (err) {
+          clearTimeout(pending.timer);
+          pendingConnections.delete(ws);
           console.error(`[tunnel-ws] Auth error for ${tunnelId}:`, err);
-          try { pending.ws.close(4001, 'authentication error'); } catch {}
+          try {
+            ws.close(4001, 'authentication error');
+          } catch {}
         }
 
         return;
       }
 
-      relay.handleAgentMessage(tunnelId, message);
+      relay.handleAgentMessage(tunnelId, ws, message);
     },
 
-    onClose(tunnelId: string) {
-      const pending = pendingConnections.get(tunnelId);
+    onClose(tunnelId: string, ws?: WebSocket) {
+      const pending = ws ? pendingConnections.get(ws) : undefined;
       if (pending) {
         clearTimeout(pending.timer);
-        pendingConnections.delete(tunnelId);
+        pendingConnections.delete(ws!);
         return;
       }
 
-      relay.unregisterAgent(tunnelId);
-      if (heartbeat) {
+      const removed = relay.unregisterAgent(tunnelId, ws);
+      if (removed && heartbeat) {
         heartbeat.unregister(tunnelId);
       }
     },

package/src/shared/crypto.ts

@@ -1,12 +1,11 @@
-import { createHash, createHmac, timingSafeEqual, randomBytes } from 'crypto';
+import { createHash, createHmac, timingSafeEqual, randomInt } from 'crypto';
 
 const CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
 
 function randomAlphanumeric(length: number): string {
-  const bytes = randomBytes(length);
   let result = '';
   for (let i = 0; i < length; i++) {
-    result += CHARS[bytes[i]! % CHARS.length];
+    result += CHARS[randomInt(CHARS.length)];
   }
   return result;
 }

package/src/shared/index.ts

@@ -33,3 +33,11 @@ export type {
 } from './types';
 
 export { TunnelErrorCode, TunnelMethods } from './types';
+export {
+  capabilityForMethod,
+  desktopFeatureForMethod,
+  isTunnelCapability,
+  operationForMethod,
+  validateTunnelPermissionScope,
+} from './permissions';
+export type { PermissionScopeValidationResult } from './permissions';

package/src/shared/permissions.ts

@@ -0,0 +1,292 @@
+import { TunnelMethods, type TunnelCapability } from './types';
+
+const VALID_CAPABILITIES = new Set<TunnelCapability>(['filesystem', 'shell', 'desktop']);
+const VALID_FILESYSTEM_OPERATIONS = new Set(['read', 'write', 'list', 'delete']);
+const VALID_DESKTOP_FEATURES = new Set([
+  'screenshot',
+  'mouse',
+  'keyboard',
+  'windows',
+  'apps',
+  'clipboard',
+  'accessibility',
+  'computer_use',
+]);
+
+export interface PermissionScopeValidationResult {
+  valid: boolean;
+  error?: string;
+  sanitized?: Record<string, unknown>;
+}
+
+const DESKTOP_METHOD_FEATURES: Readonly<Record<string, string>> = {
+  'desktop.cua.ensure': 'computer_use',
+  'desktop.cua.start_daemon': 'computer_use',
+  'desktop.cua.status': 'computer_use',
+  'desktop.cua.version': 'computer_use',
+  'desktop.cua.list_tools': 'computer_use',
+  'desktop.cua.describe': 'computer_use',
+  'desktop.cua.bring_to_front': 'windows',
+  'desktop.cua.check_for_update': 'computer_use',
+  'desktop.cua.check_permissions': 'computer_use',
+  'desktop.cua.click': 'mouse',
+  'desktop.cua.double_click': 'mouse',
+  'desktop.cua.drag': 'mouse',
+  'desktop.cua.end_session': 'computer_use',
+  'desktop.cua.get_accessibility_tree': 'accessibility',
+  'desktop.cua.get_agent_cursor_state': 'mouse',
+  'desktop.cua.get_config': 'computer_use',
+  'desktop.cua.get_cursor_position': 'mouse',
+  'desktop.cua.get_recording_state': 'computer_use',
+  'desktop.cua.get_screen_size': 'screenshot',
+  'desktop.cua.get_window_state': 'accessibility',
+  'desktop.cua.hotkey': 'keyboard',
+  'desktop.cua.kill_app': 'apps',
+  'desktop.cua.launch_app': 'apps',
+  'desktop.cua.list_apps': 'apps',
+  'desktop.cua.list_windows': 'windows',
+  'desktop.cua.move_cursor': 'mouse',
+  'desktop.cua.page': 'accessibility',
+  'desktop.cua.press_key': 'keyboard',
+  'desktop.cua.replay_trajectory': 'computer_use',
+  'desktop.cua.right_click': 'mouse',
+  'desktop.cua.scroll': 'keyboard',
+  'desktop.cua.set_agent_cursor_enabled': 'mouse',
+  'desktop.cua.set_agent_cursor_motion': 'mouse',
+  'desktop.cua.set_agent_cursor_style': 'mouse',
+  'desktop.cua.set_config': 'computer_use',
+  'desktop.cua.set_value': 'accessibility',
+  'desktop.cua.start_recording': 'screenshot',
+  'desktop.cua.install_ffmpeg': 'computer_use',
+  'desktop.cua.start_session': 'computer_use',
+  'desktop.cua.stop_recording': 'screenshot',
+  'desktop.cua.type_text': 'keyboard',
+  'desktop.cua.zoom': 'screenshot',
+};
+
+export function capabilityForMethod(method: string): TunnelCapability | null {
+  const capability = (TunnelMethods as Readonly<Record<string, TunnelCapability | null>>)[method];
+  return capability ?? null;
+}
+
+export function isTunnelCapability(value: string): value is TunnelCapability {
+  return VALID_CAPABILITIES.has(value as TunnelCapability);
+}
+
+/**
+ * Validate permission scopes at every trust boundary.
+ *
+ * An empty object is the explicit unrestricted scope. A present restriction
+ * field must contain at least one value. This prevents `{ commands: [] }`,
+ * `{ paths: [] }`, or `{ features: [] }` from silently becoming unrestricted.
+ */
+export function validateTunnelPermissionScope(
+  capability: string,
+  input: unknown,
+): PermissionScopeValidationResult {
+  if (!isTunnelCapability(capability)) {
+    return { valid: false, error: `Unknown capability: ${capability}` };
+  }
+  if (!isPlainRecord(input)) {
+    return { valid: false, error: 'Scope must be an object' };
+  }
+  if (Object.keys(input).length === 0) {
+    return { valid: true, sanitized: {} };
+  }
+
+  switch (capability) {
+    case 'filesystem':
+      return validateFilesystemScope(input);
+    case 'shell':
+      return validateShellScope(input);
+    case 'desktop':
+      return validateDesktopScope(input);
+  }
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function rejectUnknownFields(
+  scope: Record<string, unknown>,
+  allowed: readonly string[],
+): PermissionScopeValidationResult | null {
+  const unknown = Object.keys(scope).find((key) => !allowed.includes(key));
+  return unknown ? { valid: false, error: `Unknown scope field: "${unknown}"` } : null;
+}
+
+function copyScopeLabel(
+  scope: Record<string, unknown>,
+  sanitized: Record<string, unknown>,
+): PermissionScopeValidationResult | null {
+  if (!('scope' in scope)) return null;
+  if (typeof scope.scope !== 'string' || scope.scope.length === 0 || scope.scope.length > 255) {
+    return { valid: false, error: 'scope.scope must be a string between 1 and 255 characters' };
+  }
+  sanitized.scope = scope.scope;
+  return null;
+}
+
+function validateNonEmptyStringArray(
+  value: unknown,
+  field: string,
+  options: { maxItems?: number; maxLength?: number } = {},
+): PermissionScopeValidationResult | string[] {
+  const maxItems = options.maxItems ?? 100;
+  const maxLength = options.maxLength ?? 4096;
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    value.length > maxItems ||
+    !value.every(
+      (item) =>
+        typeof item === 'string' &&
+        item.length > 0 &&
+        item.length <= maxLength,
+    ) ||
+    new Set(value).size !== value.length
+  ) {
+    return {
+      valid: false,
+      error: `scope.${field} must contain 1-${maxItems} unique non-empty strings`,
+    };
+  }
+  return [...value];
+}
+
+function validateFilesystemScope(scope: Record<string, unknown>): PermissionScopeValidationResult {
+  const unknown = rejectUnknownFields(scope, [
+    'scope',
+    'paths',
+    'operations',
+    'excludePatterns',
+    'maxFileSize',
+  ]);
+  if (unknown) return unknown;
+  const sanitized: Record<string, unknown> = {};
+  const labelError = copyScopeLabel(scope, sanitized);
+  if (labelError) return labelError;
+
+  if ('paths' in scope) {
+    const paths = validateNonEmptyStringArray(scope.paths, 'paths');
+    if (!Array.isArray(paths)) return paths;
+    sanitized.paths = paths;
+  }
+  if ('operations' in scope) {
+    const operations = validateNonEmptyStringArray(scope.operations, 'operations', {
+      maxItems: VALID_FILESYSTEM_OPERATIONS.size,
+      maxLength: 16,
+    });
+    if (!Array.isArray(operations)) return operations;
+    const invalid = operations.find((operation) => !VALID_FILESYSTEM_OPERATIONS.has(operation));
+    if (invalid) return { valid: false, error: `Invalid filesystem operation: "${invalid}"` };
+    sanitized.operations = operations;
+  }
+  if ('excludePatterns' in scope) {
+    if (!Array.isArray(scope.excludePatterns)) {
+      return { valid: false, error: 'scope.excludePatterns must be an array of strings' };
+    }
+    if (
+      scope.excludePatterns.length > 100 ||
+      !scope.excludePatterns.every(
+        (pattern) => typeof pattern === 'string' && pattern.length > 0 && pattern.length <= 1024,
+      ) ||
+      new Set(scope.excludePatterns).size !== scope.excludePatterns.length
+    ) {
+      return {
+        valid: false,
+        error: 'scope.excludePatterns must contain at most 100 unique non-empty strings',
+      };
+    }
+    sanitized.excludePatterns = [...scope.excludePatterns];
+  }
+  if ('maxFileSize' in scope) {
+    if (
+      typeof scope.maxFileSize !== 'number' ||
+      !Number.isSafeInteger(scope.maxFileSize) ||
+      scope.maxFileSize <= 0
+    ) {
+      return { valid: false, error: 'scope.maxFileSize must be a positive safe integer' };
+    }
+    sanitized.maxFileSize = scope.maxFileSize;
+  }
+  return { valid: true, sanitized };
+}
+
+function validateShellScope(scope: Record<string, unknown>): PermissionScopeValidationResult {
+  const unknown = rejectUnknownFields(scope, ['scope', 'commands', 'workingDir', 'maxTimeout']);
+  if (unknown) return unknown;
+  const sanitized: Record<string, unknown> = {};
+  const labelError = copyScopeLabel(scope, sanitized);
+  if (labelError) return labelError;
+
+  if ('commands' in scope) {
+    const commands = validateNonEmptyStringArray(scope.commands, 'commands', {
+      maxItems: 100,
+      maxLength: 4096,
+    });
+    if (!Array.isArray(commands)) return commands;
+    sanitized.commands = commands;
+  }
+  if ('workingDir' in scope) {
+    if (
+      typeof scope.workingDir !== 'string' ||
+      scope.workingDir.length === 0 ||
+      scope.workingDir.length > 4096
+    ) {
+      return { valid: false, error: 'scope.workingDir must be a non-empty string' };
+    }
+    sanitized.workingDir = scope.workingDir;
+  }
+  if ('maxTimeout' in scope) {
+    if (
+      typeof scope.maxTimeout !== 'number' ||
+      !Number.isSafeInteger(scope.maxTimeout) ||
+      scope.maxTimeout <= 0
+    ) {
+      return { valid: false, error: 'scope.maxTimeout must be a positive safe integer' };
+    }
+    sanitized.maxTimeout = scope.maxTimeout;
+  }
+  return { valid: true, sanitized };
+}
+
+function validateDesktopScope(scope: Record<string, unknown>): PermissionScopeValidationResult {
+  const unknown = rejectUnknownFields(scope, ['scope', 'features']);
+  if (unknown) return unknown;
+  const sanitized: Record<string, unknown> = {};
+  const labelError = copyScopeLabel(scope, sanitized);
+  if (labelError) return labelError;
+
+  if ('features' in scope) {
+    const features = validateNonEmptyStringArray(scope.features, 'features', {
+      maxItems: VALID_DESKTOP_FEATURES.size,
+      maxLength: 32,
+    });
+    if (!Array.isArray(features)) return features;
+    const invalid = features.find((feature) => !VALID_DESKTOP_FEATURES.has(feature));
+    if (invalid) return { valid: false, error: `Invalid desktop feature: "${invalid}"` };
+    sanitized.features = features;
+  }
+  return { valid: true, sanitized };
+}
+
+export function operationForMethod(method: string): string {
+  if (method === 'fs.stat') return 'read';
+  const separator = method.indexOf('.');
+  return separator === -1 ? method : method.slice(separator + 1);
+}
+
+export function desktopFeatureForMethod(
+  method: string,
+  args: Record<string, unknown> = {},
+): string | undefined {
+  if (method === 'desktop.cua.call') {
+    const tool = args.tool;
+    if (typeof tool !== 'string' || tool.length === 0) return undefined;
+    const toolMethod = tool.startsWith('desktop.cua.') ? tool : `desktop.cua.${tool}`;
+    return DESKTOP_METHOD_FEATURES[toolMethod];
+  }
+  return DESKTOP_METHOD_FEATURES[method];
+}