@juspay/neurolink 9.30.0 → 9.31.0

package/dist/client/server/middleware/deprecation.js

@@ -0,0 +1,190 @@
+/**
+ * Route Deprecation Middleware
+ * Adds RFC 8594 deprecation headers to responses for deprecated routes
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8594 - The 'Deprecation' HTTP Header Field
+ */
+/**
+ * Build a lookup map of deprecated routes
+ * Key format: "METHOD:path" (e.g., "GET:/api/v1/users")
+ */
+function buildDeprecatedRoutesMap(routes) {
+    const map = new Map();
+    for (const route of routes) {
+        if (route.deprecated?.enabled) {
+            const key = `${route.method}:${route.path}`;
+            map.set(key, {
+                method: route.method,
+                path: route.path,
+                deprecation: route.deprecated,
+            });
+        }
+    }
+    return map;
+}
+/**
+ * Normalize a path with parameters to match against route patterns
+ * Converts "/users/123" to match "/users/:id" pattern
+ */
+function normalizePathForMatching(actualPath, routePatterns) {
+    // Try exact match first
+    if (routePatterns.includes(actualPath)) {
+        return actualPath;
+    }
+    // Try pattern matching for parameterized routes
+    for (const pattern of routePatterns) {
+        if (matchesRoutePattern(actualPath, pattern)) {
+            return pattern;
+        }
+    }
+    return null;
+}
+/**
+ * Check if an actual path matches a route pattern with parameters
+ */
+function matchesRoutePattern(actualPath, pattern) {
+    const patternParts = pattern.split("/");
+    const actualParts = actualPath.split("/");
+    if (patternParts.length !== actualParts.length) {
+        return false;
+    }
+    for (let i = 0; i < patternParts.length; i++) {
+        const patternPart = patternParts[i];
+        const actualPart = actualParts[i];
+        // Parameter parts start with ":"
+        if (patternPart.startsWith(":")) {
+            continue; // Parameter matches any value
+        }
+        if (patternPart !== actualPart) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Format a date for the Deprecation header (RFC 7231 HTTP-date format)
+ * Example: "Sun, 06 Nov 1994 08:49:37 GMT"
+ */
+function formatHttpDate(date) {
+    return date.toUTCString();
+}
+/**
+ * Parse a version string to estimate a sunset date
+ * This is a simple heuristic - in production you'd want actual dates
+ */
+function estimateSunsetDate(removeIn) {
+    if (!removeIn) {
+        return null;
+    }
+    // Default to 6 months from now if version specified
+    const sunsetDate = new Date();
+    sunsetDate.setMonth(sunsetDate.getMonth() + 6);
+    return sunsetDate;
+}
+/**
+ * Create deprecation middleware
+ *
+ * This middleware adds RFC 8594 compliant deprecation headers to responses
+ * for routes marked as deprecated:
+ *
+ * - `Deprecation`: RFC 8594 header indicating the route is deprecated
+ * - `Sunset`: RFC 8594 header indicating when the route will be removed
+ * - `Link`: Header pointing to the alternative route (rel="successor-version")
+ * - `X-Deprecation-Notice`: Custom header with a human-readable message
+ *
+ * @example
+ * ```typescript
+ * const routes: RouteDefinition[] = [
+ *   {
+ *     method: "GET",
+ *     path: "/api/v1/users",
+ *     handler: handleUsers,
+ *     deprecated: {
+ *       enabled: true,
+ *       since: "2.0.0",
+ *       removeIn: "3.0.0",
+ *       alternative: "/api/v2/users",
+ *       message: "Use /api/v2/users instead",
+ *     },
+ *   },
+ * ];
+ *
+ * const deprecationMiddleware = createDeprecationMiddleware({ routes });
+ * server.registerMiddleware(deprecationMiddleware);
+ * ```
+ */
+export function createDeprecationMiddleware(config) {
+    const { routes, noticeHeader = "X-Deprecation-Notice", includeLink = true, } = config;
+    // Build lookup map of deprecated routes
+    const deprecatedRoutes = buildDeprecatedRoutesMap(routes);
+    // Extract route patterns for matching (key format is "METHOD:path")
+    // We need to handle paths that may contain ":" for parameters
+    const routePatterns = Array.from(deprecatedRoutes.keys()).map((key) => {
+        const colonIndex = key.indexOf(":");
+        return key.slice(colonIndex + 1);
+    });
+    return {
+        name: "deprecation",
+        order: 100, // Run late, after route handling
+        handler: async (ctx, next) => {
+            // Execute the route handler first
+            const result = await next();
+            // Check if current route is deprecated
+            const matchedPattern = normalizePathForMatching(ctx.path, routePatterns);
+            if (!matchedPattern) {
+                return result;
+            }
+            const routeKey = `${ctx.method}:${matchedPattern}`;
+            const deprecatedRoute = deprecatedRoutes.get(routeKey);
+            if (!deprecatedRoute) {
+                return result;
+            }
+            const { deprecation } = deprecatedRoute;
+            // Initialize response headers if not present
+            ctx.responseHeaders = ctx.responseHeaders || {};
+            // Add RFC 8594 Deprecation header
+            // Value is either "true" or an HTTP-date when deprecated
+            if (deprecation.since) {
+                // Use a date representation if we have version info
+                ctx.responseHeaders["Deprecation"] = "true";
+            }
+            else {
+                ctx.responseHeaders["Deprecation"] = "true";
+            }
+            // Add Sunset header if removeIn is specified
+            if (deprecation.removeIn) {
+                const sunsetDate = estimateSunsetDate(deprecation.removeIn);
+                if (sunsetDate) {
+                    ctx.responseHeaders["Sunset"] = formatHttpDate(sunsetDate);
+                }
+            }
+            // Add Link header for alternative route
+            if (includeLink && deprecation.alternative) {
+                // RFC 8594 recommends rel="successor-version" for replacement resources
+                ctx.responseHeaders["Link"] =
+                    `<${deprecation.alternative}>; rel="successor-version"`;
+            }
+            // Add custom deprecation notice header
+            let notice = "This endpoint is deprecated";
+            if (deprecation.since) {
+                notice += ` since version ${deprecation.since}`;
+            }
+            if (deprecation.removeIn) {
+                notice += ` and will be removed in version ${deprecation.removeIn}`;
+            }
+            if (deprecation.message) {
+                notice = deprecation.message;
+            }
+            ctx.responseHeaders[noticeHeader] = notice;
+            // Store deprecation info in metadata for logging/telemetry
+            ctx.metadata.deprecation = {
+                route: matchedPattern,
+                method: ctx.method,
+                since: deprecation.since,
+                removeIn: deprecation.removeIn,
+                alternative: deprecation.alternative,
+            };
+            return result;
+        },
+    };
+}

package/dist/client/server/middleware/mcpBodyAttachment.js

@@ -0,0 +1,63 @@
+/**
+ * MCP Body Attachment Middleware for Fastify
+ * Attaches parsed body to raw request for MCP SDK compatibility
+ */
+/**
+ * Create MCP body attachment middleware for Fastify.
+ * The MCP SDK reads body from request.raw.body, but Fastify
+ * parses body separately. This middleware bridges the gap.
+ *
+ * @returns Middleware that attaches body to raw request
+ *
+ * @example
+ * ```typescript
+ * // In Fastify adapter
+ * const mcpBodyMiddleware = createMCPBodyAttachmentMiddleware();
+ * server.registerMiddleware(mcpBodyMiddleware);
+ * ```
+ */
+export function createMCPBodyAttachmentMiddleware() {
+    return {
+        name: "mcp-body-attachment",
+        order: 10, // After body parsing, before route handlers
+        handler: async (ctx, next) => {
+            attachBodyToRawRequest(ctx);
+            return next();
+        },
+    };
+}
+/**
+ * Attach parsed body to raw request object.
+ * Supports Fastify's request structure.
+ */
+function attachBodyToRawRequest(ctx) {
+    const rawRequest = ctx.rawRequest;
+    if (!rawRequest) {
+        return;
+    }
+    // Fastify structure: request.raw is the Node.js IncomingMessage
+    if (rawRequest.raw && rawRequest.body !== undefined) {
+        rawRequest.raw.body = rawRequest.body;
+    }
+}
+/**
+ * Fastify-specific preHandler hook.
+ * Use this directly with Fastify for optimal integration.
+ *
+ * This is a lower-level hook that works directly with Fastify
+ * request objects rather than the unified ServerContext.
+ *
+ * @param request - Fastify request object
+ * @returns Promise that resolves when body is attached
+ *
+ * @example
+ * ```typescript
+ * // In Fastify adapter initialization
+ * fastify.addHook('preHandler', fastifyMCPBodyHook);
+ * ```
+ */
+export async function fastifyMCPBodyHook(request) {
+    if (request.body !== undefined) {
+        request.raw.body = request.body;
+    }
+}

package/dist/client/server/middleware/rateLimit.js

@@ -0,0 +1,227 @@
+/**
+ * Rate Limiting Middleware
+ * Provides configurable rate limiting for server adapters
+ */
+import { RateLimitError as ServerRateLimitError } from "../errors.js";
+/**
+ * In-memory rate limit store
+ */
+export class InMemoryRateLimitStore {
+    store = new Map();
+    cleanupInterval;
+    constructor() {
+        // Clean up expired entries periodically
+        this.cleanupInterval = setInterval(() => this.cleanup(), 60000);
+    }
+    async get(key) {
+        const record = this.store.get(key);
+        if (!record) {
+            return undefined;
+        }
+        // Check if expired
+        if (Date.now() > record.resetAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        return record;
+    }
+    async set(key, entry) {
+        this.store.set(key, entry);
+    }
+    async increment(key, windowMs) {
+        const now = Date.now();
+        let record = this.store.get(key);
+        if (!record || now > record.resetAt) {
+            record = { count: 0, resetAt: now + windowMs };
+            this.store.set(key, record);
+        }
+        record.count++;
+        return { count: record.count, resetAt: record.resetAt };
+    }
+    async reset(key) {
+        this.store.delete(key);
+    }
+    cleanup() {
+        const now = Date.now();
+        for (const [key, record] of this.store.entries()) {
+            if (now > record.resetAt) {
+                this.store.delete(key);
+            }
+        }
+    }
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+        }
+        this.store.clear();
+    }
+}
+/**
+ * Create rate limiting middleware
+ *
+ * Response headers set on all requests:
+ * - `X-RateLimit-Limit`: Maximum requests allowed per window
+ * - `X-RateLimit-Remaining`: Requests remaining in current window
+ * - `X-RateLimit-Reset`: Unix timestamp when the window resets
+ *
+ * Additional headers on rate limit exceeded (HTTP 429):
+ * - `Retry-After`: Seconds to wait before retrying
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = createRateLimitMiddleware({
+ *   maxRequests: 100,
+ *   windowMs: 15 * 60 * 1000, // 15 minutes
+ *   skipPaths: ["/api/health"],
+ * });
+ *
+ * server.registerMiddleware(rateLimiter);
+ * ```
+ */
+export function createRateLimitMiddleware(config) {
+    const { maxRequests, windowMs, message = "Too many requests, please try again later", skipPaths = [], keyGenerator = defaultKeyGenerator, onRateLimitExceeded, store = new InMemoryRateLimitStore(), } = config;
+    return {
+        name: "rate-limit",
+        order: 5, // Run early
+        excludePaths: skipPaths,
+        handler: async (ctx, next) => {
+            const key = keyGenerator(ctx);
+            const { count, resetAt } = await store.increment(key, windowMs);
+            // Set rate limit headers in responseHeaders (adapters read from here)
+            ctx.responseHeaders = ctx.responseHeaders || {};
+            ctx.responseHeaders["X-RateLimit-Limit"] = String(maxRequests);
+            ctx.responseHeaders["X-RateLimit-Remaining"] = String(Math.max(0, maxRequests - count));
+            ctx.responseHeaders["X-RateLimit-Reset"] = String(Math.ceil(resetAt / 1000));
+            if (count > maxRequests) {
+                const retryAfter = Math.ceil((resetAt - Date.now()) / 1000);
+                // Add Retry-After header for 429 responses
+                ctx.responseHeaders["Retry-After"] = String(Math.max(0, retryAfter));
+                if (onRateLimitExceeded) {
+                    return onRateLimitExceeded(ctx, retryAfter);
+                }
+                // Throw a rate limit error that adapters can catch
+                throw new ServerRateLimitError(retryAfter * 1000, message, ctx.requestId);
+            }
+            return next();
+        },
+    };
+}
+/**
+ * Default key generator using IP address
+ */
+function defaultKeyGenerator(ctx) {
+    return (ctx.headers["x-forwarded-for"]?.split(",")[0].trim() ||
+        ctx.headers["x-real-ip"] ||
+        "unknown");
+}
+/**
+ * Re-export RateLimitError from errors for convenience
+ */
+export { RateLimitError } from "../errors.js";
+/**
+ * Create a sliding window rate limiter
+ * More accurate than fixed window but slightly more complex
+ */
+export function createSlidingWindowRateLimitMiddleware(config) {
+    const { maxRequests, windowMs, message = "Too many requests, please try again later", skipPaths = [], keyGenerator = defaultKeyGenerator, onRateLimitExceeded, subWindows = 10, } = config;
+    // Store: key -> array of timestamps
+    const store = new Map();
+    const subWindowMs = windowMs / subWindows;
+    // Cleanup interval
+    setInterval(() => {
+        const now = Date.now();
+        for (const [key, timestamps] of store.entries()) {
+            const valid = timestamps.filter((t) => now - t < windowMs);
+            if (valid.length === 0) {
+                store.delete(key);
+            }
+            else {
+                store.set(key, valid);
+            }
+        }
+    }, subWindowMs);
+    return {
+        name: "sliding-window-rate-limit",
+        order: 5,
+        excludePaths: skipPaths,
+        handler: async (ctx, next) => {
+            const key = keyGenerator(ctx);
+            const now = Date.now();
+            // Get existing timestamps and filter old ones
+            let timestamps = store.get(key) || [];
+            timestamps = timestamps.filter((t) => now - t < windowMs);
+            // Calculate count
+            const count = timestamps.length;
+            // Set rate limit headers in responseHeaders (adapters read from here)
+            ctx.responseHeaders = ctx.responseHeaders || {};
+            ctx.responseHeaders["X-RateLimit-Limit"] = String(maxRequests);
+            ctx.responseHeaders["X-RateLimit-Remaining"] = String(Math.max(0, maxRequests - count - 1));
+            ctx.responseHeaders["X-RateLimit-Reset"] = String(Math.ceil((now + windowMs) / 1000));
+            if (count >= maxRequests) {
+                const oldestTimestamp = timestamps[0] || now;
+                const retryAfter = Math.ceil((oldestTimestamp + windowMs - now) / 1000);
+                // Add Retry-After header for 429 responses
+                ctx.responseHeaders["Retry-After"] = String(Math.max(0, retryAfter));
+                if (onRateLimitExceeded) {
+                    return onRateLimitExceeded(ctx, retryAfter);
+                }
+                throw new ServerRateLimitError(retryAfter * 1000, message, ctx.requestId);
+            }
+            // Add current request timestamp
+            timestamps.push(now);
+            store.set(key, timestamps);
+            return next();
+        },
+    };
+}
+// ============================================
+// Compatibility Aliases
+// ============================================
+/**
+ * Alias for InMemoryRateLimitStore for compatibility
+ */
+export { InMemoryRateLimitStore as MemoryRateLimitStore };
+/**
+ * Create fixed window rate limit middleware
+ *
+ * Accepts config and optional store as separate parameters for compatibility.
+ * Returns rate limit headers in the response object.
+ *
+ * @example
+ * ```typescript
+ * const store = new MemoryRateLimitStore();
+ * const middleware = createFixedWindowRateLimitMiddleware(
+ *   { windowMs: 60000, maxRequests: 10 },
+ *   store
+ * );
+ * ```
+ */
+export function createFixedWindowRateLimitMiddleware(config, store) {
+    const { maxRequests, windowMs, message = "Too many requests, please try again later", skipPaths = [], keyGenerator = defaultKeyGenerator, onRateLimitExceeded, } = config;
+    const rateLimitStore = store ?? new InMemoryRateLimitStore();
+    return {
+        name: "fixed-window-rate-limit",
+        order: 5,
+        excludePaths: skipPaths,
+        handler: async (ctx, next) => {
+            const key = keyGenerator(ctx);
+            const { count, resetAt } = await rateLimitStore.increment(key, windowMs);
+            // Set rate limit headers in responseHeaders (adapters read from here)
+            ctx.responseHeaders = ctx.responseHeaders || {};
+            ctx.responseHeaders["X-RateLimit-Limit"] = String(maxRequests);
+            ctx.responseHeaders["X-RateLimit-Remaining"] = String(Math.max(0, maxRequests - count));
+            ctx.responseHeaders["X-RateLimit-Reset"] = String(Math.ceil(resetAt / 1000));
+            if (count > maxRequests) {
+                const retryAfter = Math.ceil((resetAt - Date.now()) / 1000);
+                // Add Retry-After header for 429 responses
+                ctx.responseHeaders["Retry-After"] = String(Math.max(0, retryAfter));
+                if (onRateLimitExceeded) {
+                    return onRateLimitExceeded(ctx, retryAfter);
+                }
+                throw new ServerRateLimitError(retryAfter * 1000, message, ctx.requestId);
+            }
+            // Call next handler - headers are already in ctx.responseHeaders for adapters
+            return next();
+        },
+    };
+}