@shipfox/api-agent-access 20.2.0

package/src/presentation/audit.ts

@@ -0,0 +1,45 @@
+import type {AgentAccessContext} from '@shipfox/api-auth-context';
+import {logger} from '@shipfox/node-opentelemetry';
+import {type AgentAccessToolCallOutcome, recordAgentAccessToolCall} from '#metrics/index.js';
+
+export interface AgentAccessToolCallAuditRecord {
+  tool: string;
+  outcome: AgentAccessToolCallOutcome;
+  errorCode: string;
+  context: AgentAccessContext;
+}
+
+export type AgentAccessToolCallRecorder = (record: AgentAccessToolCallAuditRecord) => void;
+
+export interface CreateAgentAccessToolCallRecorderOptions {
+  recordMetric?: typeof recordAgentAccessToolCall;
+  logInfo?:
+    | ((context: Record<string, unknown>, message: 'agent access tool call audited') => void)
+    | undefined;
+}
+
+export function createAgentAccessToolCallRecorder(
+  options: CreateAgentAccessToolCallRecorderOptions = {},
+): AgentAccessToolCallRecorder {
+  const recordMetric = options.recordMetric ?? recordAgentAccessToolCall;
+  const logInfo = options.logInfo ?? ((context, message) => logger().info(context, message));
+
+  return (record) => {
+    recordMetric({tool: record.tool, outcome: record.outcome});
+    logInfo(auditLogContext(record), 'agent access tool call audited');
+  };
+}
+
+function auditLogContext(record: AgentAccessToolCallAuditRecord): Record<string, unknown> {
+  const credential = record.context.credential;
+  return {
+    tool: record.tool,
+    outcome: record.outcome,
+    errorCode: record.errorCode,
+    userId: record.context.userId,
+    workspaceId: record.context.workspaceId,
+    credentialKind: credential.kind,
+    credentialId: credential.kind === 'oauth_grant' ? credential.grantId : credential.patId,
+    clientId: credential.kind === 'oauth_grant' ? credential.clientId : null,
+  };
+}

package/src/presentation/mcp-server.test.ts

@@ -0,0 +1,168 @@
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {InMemoryTransport} from '@modelcontextprotocol/sdk/inMemory.js';
+import {CallToolResultSchema} from '@modelcontextprotocol/sdk/types.js';
+import {agentAccessEnvelopeSchema} from '@shipfox/api-agent-access-dto';
+import type {AgentAccessContext} from '@shipfox/api-auth-context';
+import {agentAccessSuccess} from '#core/envelope.js';
+import {createAgentAccessRateLimiter} from '#core/rate-limiter.js';
+import {createAgentAccessFixtureTool} from '#core/tools.js';
+import {AGENT_ACCESS_PACKAGE_VERSION} from '#version.js';
+import {buildAgentAccessMcpServer} from './mcp-server.js';
+
+const context: AgentAccessContext = {
+  userId: 'user-1',
+  workspaceId: 'workspace-1',
+  scopes: ['read'],
+  credential: {kind: 'pat', patId: 'pat-1'},
+};
+
+describe('buildAgentAccessMcpServer', () => {
+  test('lists only the fixture tool and returns a schema-valid serialized envelope', async () => {
+    const {client, close} = await connectClient();
+
+    const tools = await client.listTools();
+    const result = await client.callTool(
+      {name: 'agent_access_fixture', arguments: {message: 'hello'}},
+      CallToolResultSchema,
+    );
+    await close();
+
+    expect(client.getServerVersion()).toEqual({
+      name: 'shipfox',
+      version: AGENT_ACCESS_PACKAGE_VERSION,
+    });
+    expect(tools.tools).toHaveLength(1);
+    expect(tools.tools[0]).toMatchObject({
+      name: 'agent_access_fixture',
+      annotations: {readOnlyHint: true},
+      outputSchema: {type: 'object'},
+    });
+    expect(tools.tools[0]?.outputSchema).not.toHaveProperty('oneOf');
+    expect(result.isError).not.toBe(true);
+    expect(agentAccessEnvelopeSchema.safeParse(result.structuredContent).success).toBe(true);
+    expect(result.content).toEqual([
+      {type: 'text', text: JSON.stringify(result.structuredContent)},
+    ]);
+  });
+
+  test('returns a tool error with retry metadata without raising a JSON-RPC error', async () => {
+    const limiter = createAgentAccessRateLimiter({limit: 1, now: () => 1_000});
+    const {client, close} = await connectClient(limiter);
+
+    await client.listTools();
+    const first = await client.callTool(
+      {name: 'agent_access_fixture', arguments: {message: 'first'}},
+      CallToolResultSchema,
+    );
+    const second = await client.callTool(
+      {name: 'agent_access_fixture', arguments: {message: 'second'}},
+      CallToolResultSchema,
+    );
+    await close();
+
+    expect(first.isError).not.toBe(true);
+    expect(second.isError).toBe(true);
+    expect(second.structuredContent).toEqual({
+      ok: false,
+      error: {code: 'rate-limited', retry_after_seconds: 60},
+    });
+    expect(second.content).toEqual([
+      {type: 'text', text: JSON.stringify(second.structuredContent)},
+    ]);
+  });
+
+  test('records only the exception when serializing a tool result fails', async () => {
+    const recordCall = vi.fn();
+    const fixture = createAgentAccessFixtureTool();
+    const unserializableTool = {
+      ...fixture,
+      name: 'unserializable_fixture',
+      execute: () => agentAccessSuccess({value: BigInt(1)}),
+    };
+    const {client, close} = await connectClient(
+      createAgentAccessRateLimiter(),
+      [unserializableTool],
+      recordCall,
+    );
+
+    const result = await client.callTool(
+      {name: 'unserializable_fixture', arguments: {message: 'ignored'}},
+      CallToolResultSchema,
+    );
+    await close();
+
+    expect(result.isError).toBe(true);
+    expect(result.structuredContent).toEqual({ok: false, error: {code: 'tool-failed'}});
+    expect(recordCall).toHaveBeenCalledTimes(1);
+    expect(recordCall).toHaveBeenCalledWith(
+      expect.objectContaining({
+        tool: 'unserializable_fixture',
+        outcome: 'exception',
+      }),
+    );
+  });
+
+  test('returns schema-valid tool errors with the serialized envelope duplicate', async () => {
+    const {client, close} = await connectClient();
+
+    const result = await client.callTool(
+      {name: 'agent_access_fixture', arguments: {message: 123}},
+      CallToolResultSchema,
+    );
+    await close();
+
+    expect(result.isError).toBe(true);
+    expect(agentAccessEnvelopeSchema.safeParse(result.structuredContent).success).toBe(true);
+    expect(result.structuredContent).toEqual({
+      ok: false,
+      error: {
+        code: 'invalid-request',
+        message: 'message must be a string of at most 256 characters with no extra properties',
+      },
+    });
+    expect(result.content).toEqual([
+      {type: 'text', text: JSON.stringify(result.structuredContent)},
+    ]);
+  });
+
+  test('does not count tool discovery against the credential window', async () => {
+    const limiter = createAgentAccessRateLimiter({limit: 1, now: () => 1_000});
+    const {client, close} = await connectClient(limiter);
+
+    await client.listTools();
+    const result = await client.callTool(
+      {name: 'agent_access_fixture', arguments: {message: 'discovery is free'}},
+      CallToolResultSchema,
+    );
+    await close();
+
+    expect(result.isError).not.toBe(true);
+    expect(result.structuredContent).toMatchObject({ok: true});
+  });
+});
+
+async function connectClient(
+  rateLimiter = createAgentAccessRateLimiter(),
+  tools = [createAgentAccessFixtureTool()],
+  recordCall?: Parameters<typeof buildAgentAccessMcpServer>[0]['recordCall'],
+): Promise<{client: Client; close: () => Promise<void>}> {
+  const server = buildAgentAccessMcpServer({
+    context,
+    tools,
+    rateLimiter,
+    recordCall,
+  });
+  const client = new Client({name: 'test-client', version: '0.0.0'});
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+  await server.connect(serverTransport);
+  await client.connect(clientTransport);
+
+  return {
+    client,
+    close: async () => {
+      await client.close();
+      await server.close();
+    },
+  };
+}

package/src/presentation/mcp-server.ts

@@ -0,0 +1,212 @@
+import {Server} from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  type CallToolResult,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import {agentAccessEnvelopeSchema} from '@shipfox/api-agent-access-dto';
+import type {AgentAccessContext} from '@shipfox/api-auth-context';
+import {reportError} from '@shipfox/node-error-monitoring';
+import {logger} from '@shipfox/node-opentelemetry';
+import {AGENT_ACCESS_MCP_INSTRUCTIONS, AGENT_ACCESS_MCP_SERVER_NAME} from '#constants.js';
+import {agentAccessError, serializeAgentAccessEnvelope} from '#core/envelope.js';
+import {type AgentAccessRateLimiter, createAgentAccessRateLimiter} from '#core/rate-limiter.js';
+import {
+  type AgentAccessTool,
+  type AgentAccessToolMap,
+  createAgentAccessFixtureTool,
+  createAgentAccessToolMap,
+} from '#core/tools.js';
+import type {AgentAccessToolCallOutcome} from '#metrics/index.js';
+import {AGENT_ACCESS_PACKAGE_VERSION} from '#version.js';
+import {type AgentAccessToolCallRecorder, createAgentAccessToolCallRecorder} from './audit.js';
+
+export interface BuildAgentAccessMcpServerParams {
+  context: AgentAccessContext;
+  tools?: readonly AgentAccessTool[] | undefined;
+  rateLimiter?: AgentAccessRateLimiter | undefined;
+  recordCall?: AgentAccessToolCallRecorder | undefined;
+}
+
+const defaultTools = (): readonly AgentAccessTool[] => [createAgentAccessFixtureTool()];
+
+export function buildAgentAccessMcpServer(params: BuildAgentAccessMcpServerParams): Server {
+  const tools = createAgentAccessToolMap(params.tools ?? defaultTools());
+  const rateLimiter = params.rateLimiter ?? createAgentAccessRateLimiter();
+  const recordCall = params.recordCall ?? createAgentAccessToolCallRecorder();
+  const server = new Server(
+    {name: AGENT_ACCESS_MCP_SERVER_NAME, version: AGENT_ACCESS_PACKAGE_VERSION},
+    {
+      capabilities: {tools: {}},
+      instructions: AGENT_ACCESS_MCP_INSTRUCTIONS,
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, () => ({
+    tools: [...tools.values()].map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema as {
+        type: 'object';
+        properties?: Record<string, object> | undefined;
+        required?: string[] | undefined;
+      },
+      outputSchema: tool.outputSchema as {
+        type: 'object';
+        properties?: Record<string, object> | undefined;
+        required?: string[] | undefined;
+      },
+      annotations: {readOnlyHint: true},
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, (request) =>
+    handleAgentAccessToolCall({
+      name: request.params.name,
+      arguments: request.params.arguments,
+      context: params.context,
+      tools,
+      rateLimiter,
+      recordCall,
+    }),
+  );
+
+  return server;
+}
+
+interface HandleAgentAccessToolCallParams {
+  name: string;
+  arguments?: Record<string, unknown> | undefined;
+  context: AgentAccessContext;
+  tools: AgentAccessToolMap;
+  rateLimiter: AgentAccessRateLimiter;
+  recordCall: AgentAccessToolCallRecorder;
+}
+
+async function handleAgentAccessToolCall(
+  params: HandleAgentAccessToolCallParams,
+): Promise<CallToolResult> {
+  const tool = params.tools.get(params.name);
+  const rateLimit = params.rateLimiter.consume(params.context.credential);
+  if (!rateLimit.allowed) {
+    recordToolCall(params.recordCall, {
+      tool: tool?.name ?? 'unknown',
+      outcome: 'rate-limited',
+      errorCode: 'rate-limited',
+      context: params.context,
+    });
+    return toolResult(
+      agentAccessError(
+        'rate-limited',
+        rateLimit.retry_after_seconds === undefined
+          ? {}
+          : {retryAfterSeconds: rateLimit.retry_after_seconds},
+      ),
+      true,
+    );
+  }
+  if (tool === undefined) return unknownToolResult(params);
+
+  const input = params.arguments ?? {};
+  if (!isRecord(input)) return invalidArgumentsResult(params, tool.name);
+  return await executeAgentAccessTool({
+    tool,
+    input,
+    context: params.context,
+    recordCall: params.recordCall,
+  });
+}
+
+async function executeAgentAccessTool(params: {
+  tool: AgentAccessTool;
+  input: Record<string, unknown>;
+  context: AgentAccessContext;
+  recordCall: AgentAccessToolCallRecorder;
+}): Promise<CallToolResult> {
+  try {
+    const response = await params.tool.execute({context: params.context, arguments: params.input});
+    const envelope = agentAccessEnvelopeSchema.safeParse(response);
+    if (!envelope.success) {
+      recordToolCall(params.recordCall, {
+        tool: params.tool.name,
+        outcome: 'exception',
+        errorCode: 'invalid-tool-response',
+        context: params.context,
+      });
+      return toolResult(agentAccessError('invalid-tool-response'), true);
+    }
+
+    const outcome: AgentAccessToolCallOutcome = envelope.data.ok ? 'success' : 'tool-error';
+    const result = toolResult(envelope.data, !envelope.data.ok);
+    recordToolCall(params.recordCall, {
+      tool: params.tool.name,
+      outcome,
+      errorCode: envelope.data.ok ? 'none' : (envelope.data.error?.code ?? 'unknown'),
+      context: params.context,
+    });
+    return result;
+  } catch (error) {
+    recordToolCall(params.recordCall, {
+      tool: params.tool.name,
+      outcome: 'exception',
+      errorCode: 'unknown',
+      context: params.context,
+    });
+    logger().error({err: error, tool: params.tool.name}, 'Agent-access tool execution failed');
+    reportError(error, {boundary: 'agent-access.mcp', operation: 'tool-call'});
+    return toolResult(agentAccessError('tool-failed'), true);
+  }
+}
+
+function unknownToolResult(params: HandleAgentAccessToolCallParams): CallToolResult {
+  recordToolCall(params.recordCall, {
+    tool: 'unknown',
+    outcome: 'invalid-request',
+    errorCode: 'unknown-tool',
+    context: params.context,
+  });
+  return toolResult(agentAccessError('unknown-tool', {message: 'Tool is not available'}), true);
+}
+
+function invalidArgumentsResult(
+  params: HandleAgentAccessToolCallParams,
+  toolName: string,
+): CallToolResult {
+  recordToolCall(params.recordCall, {
+    tool: toolName,
+    outcome: 'invalid-request',
+    errorCode: 'invalid-request',
+    context: params.context,
+  });
+  return toolResult(
+    agentAccessError('invalid-request', {message: 'Tool arguments must be an object'}),
+    true,
+  );
+}
+
+function toolResult(
+  envelope: ReturnType<typeof agentAccessError>,
+  isError: boolean,
+): CallToolResult {
+  return {
+    ...(isError ? {isError: true} : {}),
+    content: [{type: 'text', text: serializeAgentAccessEnvelope(envelope)}],
+    structuredContent: envelope as Record<string, unknown>,
+  };
+}
+
+function recordToolCall(
+  recordCall: AgentAccessToolCallRecorder,
+  record: Parameters<AgentAccessToolCallRecorder>[0],
+): void {
+  try {
+    recordCall(record);
+  } catch (error) {
+    logger().error({err: error}, 'Failed to record agent-access tool audit event');
+    reportError(error, {boundary: 'agent-access.mcp', operation: 'audit'});
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/presentation/routes.test.ts

@@ -0,0 +1,193 @@
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {StreamableHTTPClientTransport} from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import type {Transport} from '@modelcontextprotocol/sdk/shared/transport.js';
+import {CallToolResultSchema} from '@modelcontextprotocol/sdk/types.js';
+import {
+  type AgentAccessContext,
+  AUTH_AGENT_ACCESS,
+  setAgentAccessContext,
+} from '@shipfox/api-auth-context';
+import {
+  type AuthMethod,
+  ClientError,
+  closeApp,
+  createApp,
+  type FastifyRequest,
+} from '@shipfox/node-fastify';
+import {createAgentAccessRateLimiter} from '#core/rate-limiter.js';
+import {createAgentAccessRoutes} from './routes.js';
+
+const context: AgentAccessContext = {
+  userId: 'user-1',
+  workspaceId: 'workspace-1',
+  scopes: ['read'],
+  credential: {kind: 'oauth_grant', grantId: 'grant-1', clientId: 'client-1'},
+};
+
+let authCalls = 0;
+
+const testAuth: AuthMethod = {
+  name: AUTH_AGENT_ACCESS,
+  authenticate: (request: FastifyRequest) => {
+    authCalls += 1;
+    if (request.headers.authorization !== 'Bearer valid-token') {
+      throw new ClientError('Missing or invalid Authorization header', 'unauthorized', {
+        status: 401,
+      });
+    }
+    setAgentAccessContext(request, context);
+    return Promise.resolve();
+  },
+};
+
+describe('agent-access MCP routes', () => {
+  beforeEach(async () => {
+    await closeApp();
+    authCalls = 0;
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  test('returns 405 for allowed GET and DELETE requests', async () => {
+    const app = await createTestApp();
+
+    const getResponse = await app.inject({
+      method: 'GET',
+      url: '/mcp',
+      headers: {origin: 'https://allowed.example.test'},
+    });
+    const deleteResponse = await app.inject({
+      method: 'DELETE',
+      url: '/mcp',
+      headers: {origin: 'https://allowed.example.test'},
+    });
+
+    expect(getResponse.statusCode).toBe(405);
+    expect(deleteResponse.statusCode).toBe(405);
+    expect(getResponse.headers.allow).toBe('POST');
+    expect(deleteResponse.headers.allow).toBe('POST');
+    expect(authCalls).toBe(0);
+  });
+
+  test('rejects a disallowed Origin before agent authentication', async () => {
+    const app = await createTestApp();
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/mcp',
+      headers: {origin: 'https://evil.example.test'},
+      payload: {},
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json()).toEqual({code: 'origin-not-allowed'});
+    expect(authCalls).toBe(0);
+  });
+
+  test('allows an Origin-less request to proceed to authentication', async () => {
+    const app = await createTestApp();
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/mcp',
+      headers: {authorization: 'Bearer valid-token'},
+      payload: {},
+    });
+
+    expect(response.statusCode).toBe(406);
+    expect(authCalls).toBe(1);
+  });
+
+  test('challenges unauthenticated requests with protected-resource metadata', async () => {
+    const app = await createTestApp();
+
+    const response = await app.inject({
+      method: 'POST',
+      url: '/mcp',
+      headers: {origin: 'https://allowed.example.test'},
+      payload: {},
+    });
+
+    expect(response.statusCode).toBe(401);
+    expect(response.headers['www-authenticate']).toBe(
+      'Bearer scope="read", resource_metadata="https://api.example.test/.well-known/oauth-protected-resource"',
+    );
+    expect(response.json()).toEqual({code: 'unauthorized'});
+    expect(authCalls).toBe(1);
+  });
+
+  test('serves stateless Streamable HTTP with the fixture tool', async () => {
+    const app = await createTestApp();
+    const address = await app.listen({port: 0, host: '127.0.0.1'});
+    const client = new Client({name: 'test-http-client', version: '0.0.0'});
+    const transport = new StreamableHTTPClientTransport(new URL('/mcp', address), {
+      requestInit: {headers: {authorization: 'Bearer valid-token'}},
+    });
+
+    await client.connect(transport as unknown as Transport);
+    const tools = await client.listTools();
+    const result = await client.callTool(
+      {name: 'agent_access_fixture', arguments: {message: 'hello over HTTP'}},
+      CallToolResultSchema,
+    );
+    await client.close();
+
+    expect(tools.tools.map((tool) => tool.name)).toEqual(['agent_access_fixture']);
+    expect(client.getServerVersion()?.name).toBe('shipfox');
+    expect(result.isError).not.toBe(true);
+    expect(result.structuredContent).toEqual({
+      ok: true,
+      result: {message: 'hello over HTTP'},
+    });
+    expect(result.content).toEqual([
+      {type: 'text', text: JSON.stringify(result.structuredContent)},
+    ]);
+    expect(authCalls).toBeGreaterThan(0);
+  });
+
+  test('returns an MCP tool error when the credential exceeds its window', async () => {
+    const app = await createTestApp(createAgentAccessRateLimiter({limit: 1, now: () => 1_000}));
+    const address = await app.listen({port: 0, host: '127.0.0.1'});
+    const client = new Client({name: 'test-http-client', version: '0.0.0'});
+    const transport = new StreamableHTTPClientTransport(new URL('/mcp', address), {
+      requestInit: {headers: {authorization: 'Bearer valid-token'}},
+    });
+
+    await client.connect(transport as unknown as Transport);
+    await client.listTools();
+    await client.callTool(
+      {name: 'agent_access_fixture', arguments: {message: 'first'}},
+      CallToolResultSchema,
+    );
+    const overLimit = await client.callTool(
+      {name: 'agent_access_fixture', arguments: {message: 'second'}},
+      CallToolResultSchema,
+    );
+    await client.close();
+
+    expect(overLimit.isError).toBe(true);
+    expect(overLimit.structuredContent).toEqual({
+      ok: false,
+      error: {code: 'rate-limited', retry_after_seconds: 60},
+    });
+  });
+});
+
+async function createTestApp(rateLimiter = createAgentAccessRateLimiter()) {
+  const app = await createApp({
+    auth: [testAuth],
+    routes: [
+      createAgentAccessRoutes({
+        apiPublicUrl: 'https://api.example.test',
+        isOriginAllowed: (origin) =>
+          origin === undefined || origin === 'https://allowed.example.test',
+        rateLimiter,
+      }),
+    ],
+    swagger: false,
+  });
+  await app.ready();
+  return app;
+}