@shipfox/api-agent-access 20.2.0

package/dist/presentation/mcp-server.js

@@ -0,0 +1,171 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { agentAccessEnvelopeSchema } from '@shipfox/api-agent-access-dto';
+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 { createAgentAccessRateLimiter } from '#core/rate-limiter.js';
+import { createAgentAccessFixtureTool, createAgentAccessToolMap } from '#core/tools.js';
+import { AGENT_ACCESS_PACKAGE_VERSION } from '#version.js';
+import { createAgentAccessToolCallRecorder } from './audit.js';
+const defaultTools = ()=>[
+        createAgentAccessFixtureTool()
+    ];
+export function buildAgentAccessMcpServer(params) {
+    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,
+                    outputSchema: tool.outputSchema,
+                    annotations: {
+                        readOnlyHint: true
+                    }
+                }))
+        }));
+    server.setRequestHandler(CallToolRequestSchema, (request)=>handleAgentAccessToolCall({
+            name: request.params.name,
+            arguments: request.params.arguments,
+            context: params.context,
+            tools,
+            rateLimiter,
+            recordCall
+        }));
+    return server;
+}
+async function handleAgentAccessToolCall(params) {
+    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) {
+    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 = 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) {
+    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, toolName) {
+    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, isError) {
+    return {
+        ...isError ? {
+            isError: true
+        } : {},
+        content: [
+            {
+                type: 'text',
+                text: serializeAgentAccessEnvelope(envelope)
+            }
+        ],
+        structuredContent: envelope
+    };
+}
+function recordToolCall(recordCall, record) {
+    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) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+//# sourceMappingURL=mcp-server.js.map

package/dist/presentation/mcp-server.js.map

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

package/dist/presentation/routes.d.ts

@@ -0,0 +1,14 @@
+import { type RouteGroup } from '@shipfox/node-fastify';
+import { type AgentAccessRateLimiter } from '#core/rate-limiter.js';
+import { type AgentAccessTool } from '#core/tools.js';
+import { type AgentAccessToolCallRecorder } from './audit.js';
+export interface CreateAgentAccessRoutesOptions {
+    apiPublicUrl?: string | undefined;
+    protectedResourceMetadataUrl?: string | undefined;
+    tools?: readonly AgentAccessTool[] | undefined;
+    rateLimiter?: AgentAccessRateLimiter | undefined;
+    recordCall?: AgentAccessToolCallRecorder | undefined;
+    isOriginAllowed?: ((origin: string | undefined) => boolean) | undefined;
+}
+export declare function createAgentAccessRoutes(options?: CreateAgentAccessRoutesOptions): RouteGroup;
+//# sourceMappingURL=routes.d.ts.map

package/dist/presentation/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/presentation/routes.ts"],"names":[],"mappings":"AAIA,OAAO,EAOL,KAAK,UAAU,EAEhB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAC,KAAK,sBAAsB,EAA+B,MAAM,uBAAuB,CAAC;AAChG,OAAO,EAAC,KAAK,eAAe,EAA+B,MAAM,gBAAgB,CAAC;AAElF,OAAO,EAAC,KAAK,2BAA2B,EAAoC,MAAM,YAAY,CAAC;AAK/F,MAAM,WAAW,8BAA8B;IAC7C,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,4BAA4B,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,CAAC;IAC/C,WAAW,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;IACjD,UAAU,CAAC,EAAE,2BAA2B,GAAG,SAAS,CAAC;IACrD,eAAe,CAAC,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;CACzE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,8BAAmC,GAAG,UAAU,CA0EhG"}

package/dist/presentation/routes.js

@@ -0,0 +1,149 @@
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { AUTH_AGENT_ACCESS, requireAgentAccessContext } from '@shipfox/api-auth-context';
+import { reportError } from '@shipfox/node-error-monitoring';
+import { ClientError, createAllowedOriginMatcher, errorHandler as defaultErrorHandler, defineRoute } from '@shipfox/node-fastify';
+import { logger } from '@shipfox/node-opentelemetry';
+import { AGENT_ACCESS_MCP_PATH, AGENT_ACCESS_PROTECTED_RESOURCE_METADATA_PATH } from '#constants.js';
+import { createAgentAccessRateLimiter } from '#core/rate-limiter.js';
+import { createAgentAccessFixtureTool } from '#core/tools.js';
+import { recordAgentAccessAuthFailure } from '#metrics/index.js';
+import { createAgentAccessToolCallRecorder } from './audit.js';
+import { buildAgentAccessMcpServer } from './mcp-server.js';
+const TRAILING_SLASHES_RE = /\/+$/u;
+export function createAgentAccessRoutes(options = {}) {
+    const tools = options.tools ?? [
+        createAgentAccessFixtureTool()
+    ];
+    const rateLimiter = options.rateLimiter ?? createAgentAccessRateLimiter();
+    const recordCall = options.recordCall ?? createAgentAccessToolCallRecorder();
+    const originMatcher = options.isOriginAllowed ?? createAllowedOriginMatcher();
+    const errorHandler = createAgentAccessErrorHandler(resourceMetadataUrl(options));
+    return {
+        prefix: '',
+        routes: [
+            defineRoute({
+                method: 'GET',
+                path: AGENT_ACCESS_MCP_PATH,
+                description: 'MCP endpoint does not provide an SSE GET stream.',
+                preAuth: createOriginGuard(originMatcher),
+                handler: methodNotAllowed
+            }),
+            defineRoute({
+                method: 'DELETE',
+                path: AGENT_ACCESS_MCP_PATH,
+                description: 'MCP endpoint does not provide DELETE session operations.',
+                preAuth: createOriginGuard(originMatcher),
+                handler: methodNotAllowed
+            }),
+            defineRoute({
+                method: 'POST',
+                path: AGENT_ACCESS_MCP_PATH,
+                description: 'Stateless Streamable HTTP MCP endpoint for agent-access tools.',
+                auth: AUTH_AGENT_ACCESS,
+                preAuth: createOriginGuard(originMatcher),
+                errorHandler,
+                handler: async (request, reply)=>{
+                    const context = requireAgentAccessContext(request);
+                    const server = buildAgentAccessMcpServer({
+                        context,
+                        tools,
+                        rateLimiter,
+                        recordCall
+                    });
+                    // No sessionIdGenerator selects the SDK's stateless transport mode.
+                    const transport = new StreamableHTTPServerTransport();
+                    let connected = false;
+                    let cleanedUp = false;
+                    const cleanup = ()=>{
+                        if (cleanedUp) return;
+                        cleanedUp = true;
+                        void transport.close().catch((error)=>{
+                            logger().error({
+                                err: error
+                            }, 'Failed to close agent-access transport');
+                            reportError(error, {
+                                boundary: 'agent-access.mcp',
+                                operation: 'close-transport'
+                            });
+                        });
+                        if (connected) {
+                            void server.close().catch((error)=>{
+                                logger().error({
+                                    err: error
+                                }, 'Failed to close agent-access server');
+                                reportError(error, {
+                                    boundary: 'agent-access.mcp',
+                                    operation: 'close-server'
+                                });
+                            });
+                        }
+                    };
+                    reply.raw.once('close', cleanup);
+                    try {
+                        await server.connect(transport);
+                        connected = true;
+                        reply.hijack();
+                        await transport.handleRequest(request.raw, reply.raw, request.body);
+                    } catch (error) {
+                        cleanup();
+                        throw error;
+                    }
+                }
+            })
+        ]
+    };
+}
+function methodNotAllowed(_request, reply) {
+    return reply.code(405).header('allow', 'POST').send({
+        code: 'method-not-allowed'
+    });
+}
+function createOriginGuard(isOriginAllowed) {
+    return async (request, reply)=>{
+        if (isOriginAllowed(request.headers.origin)) return;
+        recordAgentAccessAuthFailure('origin-not-allowed');
+        await reply.code(403).send({
+            code: 'origin-not-allowed'
+        });
+    };
+}
+function createAgentAccessErrorHandler(resourceMetadataUrl) {
+    const challenge = `Bearer scope="read", resource_metadata="${escapeHeaderValue(resourceMetadataUrl)}"`;
+    return (error, request, reply)=>{
+        const status = errorStatus(error);
+        const reason = authFailureReason(error, status, request);
+        if (reason !== undefined) recordAgentAccessAuthFailure(reason);
+        if (status === 401) reply.header('www-authenticate', challenge);
+        return defaultErrorHandler(error, request, reply);
+    };
+}
+function resourceMetadataUrl(options) {
+    if (options.protectedResourceMetadataUrl !== undefined) {
+        return options.protectedResourceMetadataUrl;
+    }
+    if (options.apiPublicUrl === undefined) return AGENT_ACCESS_PROTECTED_RESOURCE_METADATA_PATH;
+    return `${options.apiPublicUrl.replace(TRAILING_SLASHES_RE, '')}${AGENT_ACCESS_PROTECTED_RESOURCE_METADATA_PATH}`;
+}
+function escapeHeaderValue(value) {
+    return value.replace(/[\\"\r\n]/gu, (character)=>{
+        if (character === '\r' || character === '\n') return '';
+        return `\\${character}`;
+    });
+}
+function errorStatus(error) {
+    if (error instanceof ClientError) return error.status ?? 400;
+    if (isRecord(error) && typeof error.statusCode === 'number') return error.statusCode;
+    return undefined;
+}
+function authFailureReason(error, status, request) {
+    if (isRecord(error) && error.code === 'auth-dependency-unavailable') {
+        return 'dependency-unavailable';
+    }
+    if (status !== 401) return undefined;
+    return request.headers.authorization === undefined ? 'missing' : 'invalid';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+
+//# sourceMappingURL=routes.js.map

package/dist/presentation/routes.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/presentation/routes.ts"],"sourcesContent":["import {StreamableHTTPServerTransport} from '@modelcontextprotocol/sdk/server/streamableHttp.js';\nimport type {Transport} from '@modelcontextprotocol/sdk/shared/transport.js';\nimport {AUTH_AGENT_ACCESS, requireAgentAccessContext} from '@shipfox/api-auth-context';\nimport {reportError} from '@shipfox/node-error-monitoring';\nimport {\n  ClientError,\n  createAllowedOriginMatcher,\n  errorHandler as defaultErrorHandler,\n  defineRoute,\n  type FastifyReply,\n  type FastifyRequest,\n  type RouteGroup,\n  type RoutePreHandler,\n} from '@shipfox/node-fastify';\nimport {logger} from '@shipfox/node-opentelemetry';\nimport {AGENT_ACCESS_MCP_PATH, AGENT_ACCESS_PROTECTED_RESOURCE_METADATA_PATH} from '#constants.js';\nimport {type AgentAccessRateLimiter, createAgentAccessRateLimiter} from '#core/rate-limiter.js';\nimport {type AgentAccessTool, createAgentAccessFixtureTool} from '#core/tools.js';\nimport {recordAgentAccessAuthFailure} from '#metrics/index.js';\nimport {type AgentAccessToolCallRecorder, createAgentAccessToolCallRecorder} from './audit.js';\nimport {buildAgentAccessMcpServer} from './mcp-server.js';\n\nconst TRAILING_SLASHES_RE = /\\/+$/u;\n\nexport interface CreateAgentAccessRoutesOptions {\n  apiPublicUrl?: string | undefined;\n  protectedResourceMetadataUrl?: string | undefined;\n  tools?: readonly AgentAccessTool[] | undefined;\n  rateLimiter?: AgentAccessRateLimiter | undefined;\n  recordCall?: AgentAccessToolCallRecorder | undefined;\n  isOriginAllowed?: ((origin: string | undefined) => boolean) | undefined;\n}\n\nexport function createAgentAccessRoutes(options: CreateAgentAccessRoutesOptions = {}): RouteGroup {\n  const tools = options.tools ?? [createAgentAccessFixtureTool()];\n  const rateLimiter = options.rateLimiter ?? createAgentAccessRateLimiter();\n  const recordCall = options.recordCall ?? createAgentAccessToolCallRecorder();\n  const originMatcher = options.isOriginAllowed ?? createAllowedOriginMatcher();\n  const errorHandler = createAgentAccessErrorHandler(resourceMetadataUrl(options));\n\n  return {\n    prefix: '',\n    routes: [\n      defineRoute({\n        method: 'GET',\n        path: AGENT_ACCESS_MCP_PATH,\n        description: 'MCP endpoint does not provide an SSE GET stream.',\n        preAuth: createOriginGuard(originMatcher),\n        handler: methodNotAllowed,\n      }),\n      defineRoute({\n        method: 'DELETE',\n        path: AGENT_ACCESS_MCP_PATH,\n        description: 'MCP endpoint does not provide DELETE session operations.',\n        preAuth: createOriginGuard(originMatcher),\n        handler: methodNotAllowed,\n      }),\n      defineRoute({\n        method: 'POST',\n        path: AGENT_ACCESS_MCP_PATH,\n        description: 'Stateless Streamable HTTP MCP endpoint for agent-access tools.',\n        auth: AUTH_AGENT_ACCESS,\n        preAuth: createOriginGuard(originMatcher),\n        errorHandler,\n        handler: async (request, reply) => {\n          const context = requireAgentAccessContext(request);\n          const server = buildAgentAccessMcpServer({context, tools, rateLimiter, recordCall});\n          // No sessionIdGenerator selects the SDK's stateless transport mode.\n          const transport = new StreamableHTTPServerTransport();\n          let connected = false;\n          let cleanedUp = false;\n\n          const cleanup = () => {\n            if (cleanedUp) return;\n            cleanedUp = true;\n            void transport.close().catch((error) => {\n              logger().error({err: error}, 'Failed to close agent-access transport');\n              reportError(error, {\n                boundary: 'agent-access.mcp',\n                operation: 'close-transport',\n              });\n            });\n            if (connected) {\n              void server.close().catch((error) => {\n                logger().error({err: error}, 'Failed to close agent-access server');\n                reportError(error, {\n                  boundary: 'agent-access.mcp',\n                  operation: 'close-server',\n                });\n              });\n            }\n          };\n\n          reply.raw.once('close', cleanup);\n          try {\n            await server.connect(transport as unknown as Transport);\n            connected = true;\n            reply.hijack();\n            await transport.handleRequest(request.raw, reply.raw, request.body);\n          } catch (error) {\n            cleanup();\n            throw error;\n          }\n        },\n      }),\n    ],\n  };\n}\n\nfunction methodNotAllowed(_request: FastifyRequest, reply: FastifyReply) {\n  return reply.code(405).header('allow', 'POST').send({code: 'method-not-allowed'});\n}\n\nfunction createOriginGuard(\n  isOriginAllowed: (origin: string | undefined) => boolean,\n): RoutePreHandler {\n  return async (request, reply) => {\n    if (isOriginAllowed(request.headers.origin)) return;\n    recordAgentAccessAuthFailure('origin-not-allowed');\n    await reply.code(403).send({code: 'origin-not-allowed'});\n  };\n}\n\nfunction createAgentAccessErrorHandler(resourceMetadataUrl: string) {\n  const challenge = `Bearer scope=\"read\", resource_metadata=\"${escapeHeaderValue(resourceMetadataUrl)}\"`;\n\n  return (error: unknown, request: FastifyRequest, reply: FastifyReply) => {\n    const status = errorStatus(error);\n    const reason = authFailureReason(error, status, request);\n    if (reason !== undefined) recordAgentAccessAuthFailure(reason);\n    if (status === 401) reply.header('www-authenticate', challenge);\n    return defaultErrorHandler(error, request, reply);\n  };\n}\n\nfunction resourceMetadataUrl(options: CreateAgentAccessRoutesOptions): string {\n  if (options.protectedResourceMetadataUrl !== undefined) {\n    return options.protectedResourceMetadataUrl;\n  }\n  if (options.apiPublicUrl === undefined) return AGENT_ACCESS_PROTECTED_RESOURCE_METADATA_PATH;\n  return `${options.apiPublicUrl.replace(TRAILING_SLASHES_RE, '')}${AGENT_ACCESS_PROTECTED_RESOURCE_METADATA_PATH}`;\n}\n\nfunction escapeHeaderValue(value: string): string {\n  return value.replace(/[\\\\\"\\r\\n]/gu, (character) => {\n    if (character === '\\r' || character === '\\n') return '';\n    return `\\\\${character}`;\n  });\n}\n\nfunction errorStatus(error: unknown): number | undefined {\n  if (error instanceof ClientError) return error.status ?? 400;\n  if (isRecord(error) && typeof error.statusCode === 'number') return error.statusCode;\n  return undefined;\n}\n\nfunction authFailureReason(\n  error: unknown,\n  status: number | undefined,\n  request: FastifyRequest,\n): 'missing' | 'invalid' | 'dependency-unavailable' | undefined {\n  if (isRecord(error) && error.code === 'auth-dependency-unavailable') {\n    return 'dependency-unavailable';\n  }\n  if (status !== 401) return undefined;\n  return request.headers.authorization === undefined ? 'missing' : 'invalid';\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null;\n}\n"],"names":["StreamableHTTPServerTransport","AUTH_AGENT_ACCESS","requireAgentAccessContext","reportError","ClientError","createAllowedOriginMatcher","errorHandler","defaultErrorHandler","defineRoute","logger","AGENT_ACCESS_MCP_PATH","AGENT_ACCESS_PROTECTED_RESOURCE_METADATA_PATH","createAgentAccessRateLimiter","createAgentAccessFixtureTool","recordAgentAccessAuthFailure","createAgentAccessToolCallRecorder","buildAgentAccessMcpServer","TRAILING_SLASHES_RE","createAgentAccessRoutes","options","tools","rateLimiter","recordCall","originMatcher","isOriginAllowed","createAgentAccessErrorHandler","resourceMetadataUrl","prefix","routes","method","path","description","preAuth","createOriginGuard","handler","methodNotAllowed","auth","request","reply","context","server","transport","connected","cleanedUp","cleanup","close","catch","error","err","boundary","operation","raw","once","connect","hijack","handleRequest","body","_request","code","header","send","headers","origin","challenge","escapeHeaderValue","status","errorStatus","reason","authFailureReason","undefined","protectedResourceMetadataUrl","apiPublicUrl","replace","value","character","isRecord","statusCode","authorization"],"mappings":"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"}