@mcp-weave/nestjs 0.2.0 → 0.3.0

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { ToolInputSchema, PromptArgument, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata } from '@mcp-weave/core';
 export { METADATA_KEYS, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata, ScannedMetadata, extractMetadata } from '@mcp-weave/core';
+import { IncomingMessage, ServerResponse, Server } from 'http';
 import { Server as Server$1 } from '@modelcontextprotocol/sdk/server/index.js';
-import { Server } from 'http';
 
 /**
  * Options for @McpServer decorator
@@ -205,6 +205,122 @@ declare function getPromptsMetadata(target: Function): McpPromptMetadata[];
  */
 declare function getParamsMetadata(target: Function): McpParamMetadata[];
 
+/**
+ * @mcp-weave/nestjs - Authentication Module
+ * Provides API key authentication and request tracking
+ */
+
+/**
+ * API Key configuration
+ */
+interface ApiKeyConfig {
+    /** The API key value */
+    key: string;
+    /** Human-readable name for the key (for logging) */
+    name?: string;
+    /** Optional metadata associated with this key */
+    metadata?: Record<string, unknown>;
+    /** Scopes/permissions for this key */
+    scopes?: string[];
+}
+/**
+ * Authentication options for MCP servers
+ */
+interface McpAuthOptions {
+    /**
+     * Enable authentication (default: false)
+     */
+    enabled?: boolean;
+    /**
+     * API keys allowed to access the server
+     * Can be a single key string, array of keys, or array of ApiKeyConfig objects
+     */
+    apiKeys?: string | string[] | ApiKeyConfig[];
+    /**
+     * Header name for the API key (default: 'x-api-key')
+     */
+    headerName?: string;
+    /**
+     * Query parameter name for the API key (default: 'api_key')
+     */
+    queryParamName?: string;
+    /**
+     * Custom authentication function
+     * Return true to allow, false to deny, or an AuthResult object
+     */
+    authenticate?: (token: string | undefined, request: IncomingMessage) => boolean | AuthResult | Promise<boolean | AuthResult>;
+    /**
+     * Called when authentication fails
+     */
+    onAuthFailure?: (request: IncomingMessage, reason: string) => void;
+    /**
+     * Called when authentication succeeds
+     */
+    onAuthSuccess?: (request: IncomingMessage, result: AuthResult) => void;
+}
+/**
+ * Result of authentication
+ */
+interface AuthResult {
+    /** Whether authentication succeeded */
+    success: boolean;
+    /** Client identifier (for tracking) */
+    clientId?: string;
+    /** Client name (for logging) */
+    clientName?: string;
+    /** Scopes/permissions granted */
+    scopes?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Request context with authentication info
+ */
+interface AuthenticatedRequest {
+    /** The original request */
+    request: IncomingMessage;
+    /** Authentication result */
+    auth: AuthResult;
+    /** Request ID for tracking */
+    requestId: string;
+    /** Timestamp of the request */
+    timestamp: Date;
+}
+/**
+ * Normalize API keys configuration to ApiKeyConfig array
+ */
+declare function normalizeApiKeys(keys: string | string[] | ApiKeyConfig[] | undefined): ApiKeyConfig[];
+/**
+ * Extract API key from request
+ */
+declare function extractApiKey(req: IncomingMessage, headerName?: string, queryParamName?: string): string | undefined;
+/**
+ * Validate API key against configured keys
+ */
+declare function validateApiKey(token: string | undefined, apiKeys: ApiKeyConfig[]): AuthResult;
+/**
+ * Hash a token for safe logging (shows first 4 and last 4 chars)
+ */
+declare function hashToken(token: string): string;
+/**
+ * Generate a unique request ID
+ */
+declare function generateRequestId(): string;
+/**
+ * Create an authentication middleware for HTTP requests
+ */
+declare function createAuthMiddleware(options?: McpAuthOptions): (req: IncomingMessage, res: ServerResponse) => Promise<AuthenticatedRequest | null>;
+/**
+ * Send unauthorized response
+ */
+declare function sendUnauthorized(res: ServerResponse, message?: string, requestId?: string): void;
+/**
+ * Generate a random API key
+ */
+declare function generateApiKey(prefix?: string): string;
+
 /**
  * Options for MCP runtime server
  */
@@ -221,6 +337,10 @@ interface McpRuntimeOptions {
      * Endpoint path for SSE/WebSocket (default: '/sse' or '/ws')
      */
     endpoint?: string;
+    /**
+     * Authentication options
+     */
+    auth?: McpAuthOptions;
 }
 /**
  * Runtime MCP server that wraps a decorated class
@@ -229,7 +349,9 @@ declare class McpRuntimeServer {
     private server;
     private instance;
     private metadata;
-    constructor(target: Function, _options?: McpRuntimeOptions);
+    private authOptions;
+    private authMiddleware;
+    constructor(target: Function, options?: McpRuntimeOptions);
     private setupHandlers;
     private setupToolHandlers;
     private setupResourceHandlers;
@@ -284,4 +406,4 @@ declare function createMcpServer(target: Function, options?: McpRuntimeOptions):
 
 declare const VERSION = "0.1.0";
 
-export { McpInput, McpParam, McpPrompt, McpPromptArg, type McpPromptOptions, McpResource, type McpResourceOptions, type McpRuntimeOptions, McpRuntimeServer, McpServer, type McpServerOptions, McpTool, type McpToolOptions, VERSION, createMcpServer, getMcpServers, getParamsMetadata, getPromptsMetadata, getResourcesMetadata, getServerMetadata, getToolsMetadata, isMcpServer };
+export { type ApiKeyConfig, type AuthResult, type AuthenticatedRequest, type McpAuthOptions, McpInput, McpParam, McpPrompt, McpPromptArg, type McpPromptOptions, McpResource, type McpResourceOptions, type McpRuntimeOptions, McpRuntimeServer, McpServer, type McpServerOptions, McpTool, type McpToolOptions, VERSION, createAuthMiddleware, createMcpServer, extractApiKey, generateApiKey, generateRequestId, getMcpServers, getParamsMetadata, getPromptsMetadata, getResourcesMetadata, getServerMetadata, getToolsMetadata, hashToken, isMcpServer, normalizeApiKeys, sendUnauthorized, validateApiKey };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ToolInputSchema, PromptArgument, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata } from '@mcp-weave/core';
 export { METADATA_KEYS, McpParamMetadata, McpPromptMetadata, McpResourceMetadata, McpServerMetadata, McpToolMetadata, ScannedMetadata, extractMetadata } from '@mcp-weave/core';
+import { IncomingMessage, ServerResponse, Server } from 'http';
 import { Server as Server$1 } from '@modelcontextprotocol/sdk/server/index.js';
-import { Server } from 'http';
 
 /**
  * Options for @McpServer decorator
@@ -205,6 +205,122 @@ declare function getPromptsMetadata(target: Function): McpPromptMetadata[];
  */
 declare function getParamsMetadata(target: Function): McpParamMetadata[];
 
+/**
+ * @mcp-weave/nestjs - Authentication Module
+ * Provides API key authentication and request tracking
+ */
+
+/**
+ * API Key configuration
+ */
+interface ApiKeyConfig {
+    /** The API key value */
+    key: string;
+    /** Human-readable name for the key (for logging) */
+    name?: string;
+    /** Optional metadata associated with this key */
+    metadata?: Record<string, unknown>;
+    /** Scopes/permissions for this key */
+    scopes?: string[];
+}
+/**
+ * Authentication options for MCP servers
+ */
+interface McpAuthOptions {
+    /**
+     * Enable authentication (default: false)
+     */
+    enabled?: boolean;
+    /**
+     * API keys allowed to access the server
+     * Can be a single key string, array of keys, or array of ApiKeyConfig objects
+     */
+    apiKeys?: string | string[] | ApiKeyConfig[];
+    /**
+     * Header name for the API key (default: 'x-api-key')
+     */
+    headerName?: string;
+    /**
+     * Query parameter name for the API key (default: 'api_key')
+     */
+    queryParamName?: string;
+    /**
+     * Custom authentication function
+     * Return true to allow, false to deny, or an AuthResult object
+     */
+    authenticate?: (token: string | undefined, request: IncomingMessage) => boolean | AuthResult | Promise<boolean | AuthResult>;
+    /**
+     * Called when authentication fails
+     */
+    onAuthFailure?: (request: IncomingMessage, reason: string) => void;
+    /**
+     * Called when authentication succeeds
+     */
+    onAuthSuccess?: (request: IncomingMessage, result: AuthResult) => void;
+}
+/**
+ * Result of authentication
+ */
+interface AuthResult {
+    /** Whether authentication succeeded */
+    success: boolean;
+    /** Client identifier (for tracking) */
+    clientId?: string;
+    /** Client name (for logging) */
+    clientName?: string;
+    /** Scopes/permissions granted */
+    scopes?: string[];
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Error message if authentication failed */
+    error?: string;
+}
+/**
+ * Request context with authentication info
+ */
+interface AuthenticatedRequest {
+    /** The original request */
+    request: IncomingMessage;
+    /** Authentication result */
+    auth: AuthResult;
+    /** Request ID for tracking */
+    requestId: string;
+    /** Timestamp of the request */
+    timestamp: Date;
+}
+/**
+ * Normalize API keys configuration to ApiKeyConfig array
+ */
+declare function normalizeApiKeys(keys: string | string[] | ApiKeyConfig[] | undefined): ApiKeyConfig[];
+/**
+ * Extract API key from request
+ */
+declare function extractApiKey(req: IncomingMessage, headerName?: string, queryParamName?: string): string | undefined;
+/**
+ * Validate API key against configured keys
+ */
+declare function validateApiKey(token: string | undefined, apiKeys: ApiKeyConfig[]): AuthResult;
+/**
+ * Hash a token for safe logging (shows first 4 and last 4 chars)
+ */
+declare function hashToken(token: string): string;
+/**
+ * Generate a unique request ID
+ */
+declare function generateRequestId(): string;
+/**
+ * Create an authentication middleware for HTTP requests
+ */
+declare function createAuthMiddleware(options?: McpAuthOptions): (req: IncomingMessage, res: ServerResponse) => Promise<AuthenticatedRequest | null>;
+/**
+ * Send unauthorized response
+ */
+declare function sendUnauthorized(res: ServerResponse, message?: string, requestId?: string): void;
+/**
+ * Generate a random API key
+ */
+declare function generateApiKey(prefix?: string): string;
+
 /**
  * Options for MCP runtime server
  */
@@ -221,6 +337,10 @@ interface McpRuntimeOptions {
      * Endpoint path for SSE/WebSocket (default: '/sse' or '/ws')
      */
     endpoint?: string;
+    /**
+     * Authentication options
+     */
+    auth?: McpAuthOptions;
 }
 /**
  * Runtime MCP server that wraps a decorated class
@@ -229,7 +349,9 @@ declare class McpRuntimeServer {
     private server;
     private instance;
     private metadata;
-    constructor(target: Function, _options?: McpRuntimeOptions);
+    private authOptions;
+    private authMiddleware;
+    constructor(target: Function, options?: McpRuntimeOptions);
     private setupHandlers;
     private setupToolHandlers;
     private setupResourceHandlers;
@@ -284,4 +406,4 @@ declare function createMcpServer(target: Function, options?: McpRuntimeOptions):
 
 declare const VERSION = "0.1.0";
 
-export { McpInput, McpParam, McpPrompt, McpPromptArg, type McpPromptOptions, McpResource, type McpResourceOptions, type McpRuntimeOptions, McpRuntimeServer, McpServer, type McpServerOptions, McpTool, type McpToolOptions, VERSION, createMcpServer, getMcpServers, getParamsMetadata, getPromptsMetadata, getResourcesMetadata, getServerMetadata, getToolsMetadata, isMcpServer };
+export { type ApiKeyConfig, type AuthResult, type AuthenticatedRequest, type McpAuthOptions, McpInput, McpParam, McpPrompt, McpPromptArg, type McpPromptOptions, McpResource, type McpResourceOptions, type McpRuntimeOptions, McpRuntimeServer, McpServer, type McpServerOptions, McpTool, type McpToolOptions, VERSION, createAuthMiddleware, createMcpServer, extractApiKey, generateApiKey, generateRequestId, getMcpServers, getParamsMetadata, getPromptsMetadata, getResourcesMetadata, getServerMetadata, getToolsMetadata, hashToken, isMcpServer, normalizeApiKeys, sendUnauthorized, validateApiKey };