synapse-mcp 1.0.0 → 1.0.2

package/dist/middleware/csrf-protection.d.ts

@@ -0,0 +1,58 @@
+import type { NextFunction, Request, Response } from "express";
+/**
+ * CSRF Protection Middleware
+ *
+ * Security: Prevents CWE-352 (Cross-Site Request Forgery) by requiring a custom header
+ * that browsers cannot send from cross-origin contexts without CORS preflight approval.
+ * @see https://cwe.mitre.org/data/definitions/352.html
+ *
+ * SECURITY (S-M6, CWE-352, CVSS 3.7): Defense-in-Depth CSRF Protection
+ * ---------------------------------------------------------------------
+ * This middleware implements the OWASP recommended "Custom Request Headers" pattern
+ * for CSRF protection in REST APIs.
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#use-of-custom-request-headers
+ *
+ * **How It Works:**
+ * 1. Requires X-Synapse-Client header on all requests
+ * 2. Custom headers trigger CORS preflight (OPTIONS request)
+ * 3. Server only approves preflight for trusted origins (or none)
+ * 4. Browsers won't send custom headers without preflight success
+ * 5. Malicious sites cannot forge requests with custom headers
+ *
+ * **Why This Works:**
+ * - Simple cross-origin requests (no custom headers) bypass preflight
+ * - But custom headers ALWAYS trigger preflight (browser security model)
+ * - Attacker sites cannot complete preflight to untrusted server
+ * - Therefore attacker cannot send X-Synapse-Client header
+ * - Requests without header are rejected by this middleware
+ *
+ * **Additional Protection:**
+ * - Sets restrictive CORS headers (Access-Control-Allow-Origin: null by default)
+ * - Optional SYNAPSE_ALLOWED_ORIGINS for trusted web clients
+ * - Only allows POST method
+ *
+ * **Complements Existing Security:**
+ * - X-API-Key authentication (S-C1) prevents unauthorized access
+ * - X-Synapse-Client header (S-M6) prevents CSRF from authenticated sessions
+ * - Together: Defense-in-depth against both direct attacks and CSRF
+ *
+ * @example
+ * ```typescript
+ * // Server setup
+ * import { csrfProtectionMiddleware } from "./middleware/csrf-protection.js";
+ * app.post("/mcp", csrfProtectionMiddleware, authMiddleware, handler);
+ *
+ * // Client request (must include custom header)
+ * fetch("http://localhost:53000/mcp", {
+ *   method: "POST",
+ *   headers: {
+ *     "Content-Type": "application/json",
+ *     "X-API-Key": "secret",
+ *     "X-Synapse-Client": "synapse-mcp-client"  // Required for CSRF protection
+ *   },
+ *   body: JSON.stringify({ method: "tools/list" })
+ * });
+ * ```
+ */
+export declare function csrfProtectionMiddleware(req: Request, res: Response, next: NextFunction): void;
+//# sourceMappingURL=csrf-protection.d.ts.map

package/dist/middleware/csrf-protection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf-protection.d.ts","sourceRoot":"","sources":["../../src/middleware/csrf-protection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAmC9F"}

package/dist/middleware/csrf-protection.js

@@ -0,0 +1,123 @@
+/**
+ * CSRF Protection Middleware
+ *
+ * Security: Prevents CWE-352 (Cross-Site Request Forgery) by requiring a custom header
+ * that browsers cannot send from cross-origin contexts without CORS preflight approval.
+ * @see https://cwe.mitre.org/data/definitions/352.html
+ *
+ * SECURITY (S-M6, CWE-352, CVSS 3.7): Defense-in-Depth CSRF Protection
+ * ---------------------------------------------------------------------
+ * This middleware implements the OWASP recommended "Custom Request Headers" pattern
+ * for CSRF protection in REST APIs.
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html#use-of-custom-request-headers
+ *
+ * **How It Works:**
+ * 1. Requires X-Synapse-Client header on all requests
+ * 2. Custom headers trigger CORS preflight (OPTIONS request)
+ * 3. Server only approves preflight for trusted origins (or none)
+ * 4. Browsers won't send custom headers without preflight success
+ * 5. Malicious sites cannot forge requests with custom headers
+ *
+ * **Why This Works:**
+ * - Simple cross-origin requests (no custom headers) bypass preflight
+ * - But custom headers ALWAYS trigger preflight (browser security model)
+ * - Attacker sites cannot complete preflight to untrusted server
+ * - Therefore attacker cannot send X-Synapse-Client header
+ * - Requests without header are rejected by this middleware
+ *
+ * **Additional Protection:**
+ * - Sets restrictive CORS headers (Access-Control-Allow-Origin: null by default)
+ * - Optional SYNAPSE_ALLOWED_ORIGINS for trusted web clients
+ * - Only allows POST method
+ *
+ * **Complements Existing Security:**
+ * - X-API-Key authentication (S-C1) prevents unauthorized access
+ * - X-Synapse-Client header (S-M6) prevents CSRF from authenticated sessions
+ * - Together: Defense-in-depth against both direct attacks and CSRF
+ *
+ * @example
+ * ```typescript
+ * // Server setup
+ * import { csrfProtectionMiddleware } from "./middleware/csrf-protection.js";
+ * app.post("/mcp", csrfProtectionMiddleware, authMiddleware, handler);
+ *
+ * // Client request (must include custom header)
+ * fetch("http://localhost:53000/mcp", {
+ *   method: "POST",
+ *   headers: {
+ *     "Content-Type": "application/json",
+ *     "X-API-Key": "secret",
+ *     "X-Synapse-Client": "synapse-mcp-client"  // Required for CSRF protection
+ *   },
+ *   body: JSON.stringify({ method: "tools/list" })
+ * });
+ * ```
+ */
+export function csrfProtectionMiddleware(req, res, next) {
+    // Handle OPTIONS preflight requests
+    if (req.method === "OPTIONS") {
+        setCORSHeaders(req, res);
+        res.status(204).end();
+        return;
+    }
+    // Set CORS headers for all other requests
+    setCORSHeaders(req, res);
+    // Require X-Synapse-Client custom header (case-insensitive)
+    const clientHeader = req.headers["x-synapse-client"];
+    if (!clientHeader || clientHeader.trim().length === 0) {
+        res.status(403).json({
+            error: "Forbidden",
+            message: "Missing required X-Synapse-Client header",
+        });
+        return;
+    }
+    // SECURITY (S-M4): Validate header value format to prevent abuse
+    // Only allow alphanumeric characters, hyphens, underscores, dots, and slashes
+    // This prevents using the header as a vector for log injection or other attacks
+    if (!/^[a-zA-Z0-9._\-/]+$/.test(clientHeader.trim())) {
+        res.status(403).json({
+            error: "Forbidden",
+            message: "Invalid X-Synapse-Client header value",
+        });
+        return;
+    }
+    // Header present, non-empty, and valid format - allow request
+    next();
+}
+/**
+ * Sets restrictive CORS headers to prevent cross-origin browser access.
+ *
+ * By default, sets Access-Control-Allow-Origin to "null" which effectively
+ * blocks all cross-origin requests from browsers.
+ *
+ * If SYNAPSE_ALLOWED_ORIGINS is set, checks request origin against allowlist
+ * and only sets matching origin if approved.
+ */
+function setCORSHeaders(req, res) {
+    const allowedOriginsEnv = process.env.SYNAPSE_ALLOWED_ORIGINS;
+    const requestOrigin = req.headers.origin;
+    if (allowedOriginsEnv && requestOrigin) {
+        // Parse comma-separated allowed origins
+        const allowedOrigins = allowedOriginsEnv.split(",").map((o) => o.trim());
+        if (allowedOrigins.includes(requestOrigin)) {
+            // Request origin is in allowlist - approve it
+            res.setHeader("Access-Control-Allow-Origin", requestOrigin);
+        }
+        else {
+            // Request origin not in allowlist - reject with "null"
+            res.setHeader("Access-Control-Allow-Origin", "null");
+        }
+    }
+    else {
+        // No allowed origins configured - block all cross-origin
+        res.setHeader("Access-Control-Allow-Origin", "null");
+    }
+    // Only allow POST method
+    res.setHeader("Access-Control-Allow-Methods", "POST");
+    // Allow required headers
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, X-API-Key, X-Synapse-Client");
+    // Tell caches that the response varies by Origin header.
+    // Without this, a cached response for one origin could be served to another.
+    res.setHeader("Vary", "Origin");
+}
+//# sourceMappingURL=csrf-protection.js.map

package/dist/middleware/csrf-protection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrf-protection.js","sourceRoot":"","sources":["../../src/middleware/csrf-protection.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,UAAU,wBAAwB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;IACtF,oCAAoC;IACpC,IAAI,GAAG,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC7B,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACzB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC;QACtB,OAAO;IACT,CAAC;IAED,0CAA0C;IAC1C,cAAc,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAEzB,4DAA4D;IAC5D,MAAM,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC,kBAAkB,CAAuB,CAAC;IAE3E,IAAI,CAAC,YAAY,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACnB,KAAK,EAAE,WAAW;YAClB,OAAO,EAAE,0CAA0C;SACpD,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,iEAAiE;IACjE,8EAA8E;IAC9E,gFAAgF;IAChF,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;YACnB,KAAK,EAAE,WAAW;YAClB,OAAO,EAAE,uCAAuC;SACjD,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IAED,8DAA8D;IAC9D,IAAI,EAAE,CAAC;AACT,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,cAAc,CAAC,GAAY,EAAE,GAAa;IACjD,MAAM,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;IAC9D,MAAM,aAAa,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC;IAEzC,IAAI,iBAAiB,IAAI,aAAa,EAAE,CAAC;QACvC,wCAAwC;QACxC,MAAM,cAAc,GAAG,iBAAiB,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAEzE,IAAI,cAAc,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;YAC3C,8CAA8C;YAC9C,GAAG,CAAC,SAAS,CAAC,6BAA6B,EAAE,aAAa,CAAC,CAAC;QAC9D,CAAC;aAAM,CAAC;YACN,uDAAuD;YACvD,GAAG,CAAC,SAAS,CAAC,6BAA6B,EAAE,MAAM,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;SAAM,CAAC;QACN,yDAAyD;QACzD,GAAG,CAAC,SAAS,CAAC,6BAA6B,EAAE,MAAM,CAAC,CAAC;IACvD,CAAC;IAED,yBAAyB;IACzB,GAAG,CAAC,SAAS,CAAC,8BAA8B,EAAE,MAAM,CAAC,CAAC;IAEtD,yBAAyB;IACzB,GAAG,CAAC,SAAS,CAAC,8BAA8B,EAAE,2CAA2C,CAAC,CAAC;IAE3F,yDAAyD;IACzD,6EAA6E;IAC7E,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAClC,CAAC"}

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Error Handler Middleware - Catches and formats all Express errors
+ *
+ * Primary middleware for catching errors from routes and returning
+ * structured JSON responses. Integrates with logError utility for
+ * comprehensive error logging with request context.
+ */
+import type { NextFunction, Request, Response } from "express";
+import "./types.js";
+/**
+ * Primary error handler middleware
+ *
+ * Catches all errors from routes and:
+ * - Logs error with full context (request ID, IP, user agent, etc.)
+ * - Maps error to appropriate HTTP status code
+ * - Formats error response with consistent structure
+ * - Includes stack traces in non-production environments
+ * - Handles headers-already-sent scenario gracefully
+ *
+ * @param error - Error thrown from route or middleware
+ * @param req - Express request object (with requestId from Phase 1)
+ * @param res - Express response object
+ * @param next - Express next function (for headers-already-sent case)
+ *
+ * @example
+ * app.use(errorHandler);
+ * app.use(fallbackErrorHandler); // Safety net
+ */
+export declare function errorHandler(error: unknown, req: Request, res: Response, next: NextFunction): void;
+/**
+ * Fallback error handler (last-resort safety net)
+ *
+ * Handles errors that occur during primary error handling.
+ * Prevents server crash if primary handler fails.
+ *
+ * This should be registered AFTER errorHandler in Express:
+ * app.use(errorHandler);
+ * app.use(fallbackErrorHandler);
+ *
+ * @param error - Error thrown during error handling
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param _next - Express next function (unused)
+ *
+ * @example
+ * app.use(fallbackErrorHandler);
+ */
+export declare function fallbackErrorHandler(error: unknown, req: Request, res: Response, _next: NextFunction): void;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/middleware/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG/D,OAAO,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACjB,IAAI,CA8BN;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,YAAY,GAClB,IAAI,CAiBN"}

package/dist/middleware/error-handler.js

@@ -0,0 +1,90 @@
+/**
+ * Error Handler Middleware - Catches and formats all Express errors
+ *
+ * Primary middleware for catching errors from routes and returning
+ * structured JSON responses. Integrates with logError utility for
+ * comprehensive error logging with request context.
+ */
+import { logError } from "../utils/errors.js";
+import { formatErrorResponse, mapErrorToStatus } from "./error-mapper.js";
+import "./types.js"; // Import Request type augmentation
+/**
+ * Primary error handler middleware
+ *
+ * Catches all errors from routes and:
+ * - Logs error with full context (request ID, IP, user agent, etc.)
+ * - Maps error to appropriate HTTP status code
+ * - Formats error response with consistent structure
+ * - Includes stack traces in non-production environments
+ * - Handles headers-already-sent scenario gracefully
+ *
+ * @param error - Error thrown from route or middleware
+ * @param req - Express request object (with requestId from Phase 1)
+ * @param res - Express response object
+ * @param next - Express next function (for headers-already-sent case)
+ *
+ * @example
+ * app.use(errorHandler);
+ * app.use(fallbackErrorHandler); // Safety net
+ */
+export function errorHandler(error, req, res, next) {
+    // Check if response already sent (can't send error response)
+    if (res.headersSent) {
+        next(error);
+        return;
+    }
+    // Get request ID from Phase 1 middleware (or fallback to 'unknown')
+    const requestId = req.requestId || "unknown";
+    // Log error with comprehensive context
+    logError(error, {
+        requestId,
+        operation: `${req.method} ${req.path}`,
+        metadata: {
+            ip: req.ip,
+            userAgent: req.headers["user-agent"],
+            forwarded: req.headers["x-forwarded-for"] || req.headers["x-real-ip"],
+        },
+    });
+    // Determine HTTP status code based on error type
+    const statusCode = mapErrorToStatus(error);
+    // Format error response (include stack trace in non-production)
+    const includeStack = process.env.NODE_ENV !== "production";
+    const errorResponse = formatErrorResponse(error, requestId, includeStack);
+    // Send JSON response
+    res.status(statusCode).json(errorResponse);
+}
+/**
+ * Fallback error handler (last-resort safety net)
+ *
+ * Handles errors that occur during primary error handling.
+ * Prevents server crash if primary handler fails.
+ *
+ * This should be registered AFTER errorHandler in Express:
+ * app.use(errorHandler);
+ * app.use(fallbackErrorHandler);
+ *
+ * @param error - Error thrown during error handling
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param _next - Express next function (unused)
+ *
+ * @example
+ * app.use(fallbackErrorHandler);
+ */
+export function fallbackErrorHandler(error, req, res, _next) {
+    // Log critical error with structured context
+    logError(error, { operation: "fallbackErrorHandler", requestId: req.requestId });
+    // Check if response already sent
+    if (res.headersSent) {
+        return;
+    }
+    // Send minimal error response
+    res.status(500).json({
+        error: {
+            message: "An unexpected error occurred",
+            code: "INTERNAL_ERROR",
+            requestId: req.requestId || "unknown",
+        },
+    });
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/middleware/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,YAAY,CAAC,CAAC,mCAAmC;AAExD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,GAAY,EACZ,GAAa,EACb,IAAkB;IAElB,6DAA6D;IAC7D,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QACpB,IAAI,CAAC,KAAK,CAAC,CAAC;QACZ,OAAO;IACT,CAAC;IAED,oEAAoE;IACpE,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,IAAI,SAAS,CAAC;IAE7C,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE;QACd,SAAS;QACT,SAAS,EAAE,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,EAAE;QACtC,QAAQ,EAAE;YACR,EAAE,EAAE,GAAG,CAAC,EAAE;YACV,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC;YACpC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC;SACtE;KACF,CAAC,CAAC;IAEH,iDAAiD;IACjD,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,CAAC;IAE3C,gEAAgE;IAChE,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,CAAC;IAC3D,MAAM,aAAa,GAAG,mBAAmB,CAAC,KAAK,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IAE1E,qBAAqB;IACrB,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAc,EACd,GAAY,EACZ,GAAa,EACb,KAAmB;IAEnB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,sBAAsB,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC;IAEjF,iCAAiC;IACjC,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QACpB,OAAO;IACT,CAAC;IAED,8BAA8B;IAC9B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;QACnB,KAAK,EAAE;YACL,OAAO,EAAE,8BAA8B;YACvC,IAAI,EAAE,gBAAgB;YACtB,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,SAAS;SACtC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/middleware/error-mapper.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Error Mapper - Translates application errors to HTTP responses
+ *
+ * Maps custom error classes to appropriate HTTP status codes and formats
+ * error responses for consistent API error handling.
+ */
+import type { ErrorCode, ErrorResponse, HTTPStatusCode } from "./types.js";
+/**
+ * Maps error instances to appropriate HTTP status codes
+ *
+ * @param error - Error instance to map
+ * @returns HTTP status code (400, 502, or 500)
+ *
+ * @example
+ * mapErrorToStatus(new ValidationError(...)) // returns 400
+ * mapErrorToStatus(new HostOperationError(...)) // returns 502
+ * mapErrorToStatus(new Error(...)) // returns 500
+ */
+export declare function mapErrorToStatus(error: unknown): HTTPStatusCode;
+/**
+ * Gets error code string for classification
+ *
+ * @param error - Error instance to classify
+ * @returns Error code string for API response
+ *
+ * @example
+ * getErrorCode(new ValidationError(...)) // returns "VALIDATION_ERROR"
+ * getErrorCode(new HostSecurityError(...)) // returns "SECURITY_ERROR"
+ */
+export declare function getErrorCode(error: unknown): ErrorCode;
+/**
+ * Formats error into structured JSON response
+ *
+ * @param error - Error to format
+ * @param requestId - Request ID for tracing
+ * @param includeStack - Whether to include stack trace (default: false)
+ * @returns Formatted error response object
+ *
+ * @example
+ * formatErrorResponse(new ValidationError(...), "req-123")
+ * // Returns: { error: { message: "...", code: "VALIDATION_ERROR", requestId: "req-123", details: {...} } }
+ */
+export declare function formatErrorResponse(error: unknown, requestId: string, includeStack?: boolean): ErrorResponse;
+//# sourceMappingURL=error-mapper.d.ts.map

package/dist/middleware/error-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-mapper.d.ts","sourceRoot":"","sources":["../../src/middleware/error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE3E;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAsB/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAsBtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,MAAM,EACjB,YAAY,UAAQ,GACnB,aAAa,CAmDf"}

package/dist/middleware/error-mapper.js

@@ -0,0 +1,127 @@
+/**
+ * Error Mapper - Translates application errors to HTTP responses
+ *
+ * Maps custom error classes to appropriate HTTP status codes and formats
+ * error responses for consistent API error handling.
+ */
+import { ZodError } from "zod";
+import { ComposeOperationError, HostOperationError, SSHCommandError, ValidationError, } from "../utils/errors.js";
+import { HostSecurityError, SSHArgSecurityError } from "../utils/path-security.js";
+/**
+ * Maps error instances to appropriate HTTP status codes
+ *
+ * @param error - Error instance to map
+ * @returns HTTP status code (400, 502, or 500)
+ *
+ * @example
+ * mapErrorToStatus(new ValidationError(...)) // returns 400
+ * mapErrorToStatus(new HostOperationError(...)) // returns 502
+ * mapErrorToStatus(new Error(...)) // returns 500
+ */
+export function mapErrorToStatus(error) {
+    // 400 Bad Request - Client input errors
+    if (error instanceof ValidationError ||
+        error instanceof HostSecurityError ||
+        error instanceof SSHArgSecurityError ||
+        error instanceof ZodError) {
+        return 400;
+    }
+    // 502 Bad Gateway - Remote host/service errors
+    if (error instanceof HostOperationError ||
+        error instanceof SSHCommandError ||
+        error instanceof ComposeOperationError) {
+        return 502;
+    }
+    // 500 Internal Server Error - Unknown/unexpected errors
+    return 500;
+}
+/**
+ * Gets error code string for classification
+ *
+ * @param error - Error instance to classify
+ * @returns Error code string for API response
+ *
+ * @example
+ * getErrorCode(new ValidationError(...)) // returns "VALIDATION_ERROR"
+ * getErrorCode(new HostSecurityError(...)) // returns "SECURITY_ERROR"
+ */
+export function getErrorCode(error) {
+    if (error instanceof ValidationError || error instanceof ZodError) {
+        return "VALIDATION_ERROR";
+    }
+    if (error instanceof HostSecurityError || error instanceof SSHArgSecurityError) {
+        return "SECURITY_ERROR";
+    }
+    if (error instanceof HostOperationError) {
+        return "HOST_OPERATION_ERROR";
+    }
+    if (error instanceof SSHCommandError) {
+        return "SSH_COMMAND_ERROR";
+    }
+    if (error instanceof ComposeOperationError) {
+        return "COMPOSE_OPERATION_ERROR";
+    }
+    return "INTERNAL_ERROR";
+}
+/**
+ * Formats error into structured JSON response
+ *
+ * @param error - Error to format
+ * @param requestId - Request ID for tracing
+ * @param includeStack - Whether to include stack trace (default: false)
+ * @returns Formatted error response object
+ *
+ * @example
+ * formatErrorResponse(new ValidationError(...), "req-123")
+ * // Returns: { error: { message: "...", code: "VALIDATION_ERROR", requestId: "req-123", details: {...} } }
+ */
+export function formatErrorResponse(error, requestId, includeStack = false) {
+    const code = getErrorCode(error);
+    let message = "Unknown error";
+    let details;
+    let stack;
+    // Extract message and details based on error type
+    if (error instanceof ValidationError) {
+        message = error.message;
+        details = {
+            handler: error.handlerName,
+            issues: error.issues,
+        };
+    }
+    else if (error instanceof ZodError) {
+        message = "Validation failed";
+        // Transform Zod errors into flat array of strings
+        details = {
+            issues: error.issues.map((err) => {
+                const path = err.path.join(".");
+                return path ? `${path}: ${err.message}` : err.message;
+            }),
+        };
+    }
+    else if (error instanceof Error) {
+        message = error.message;
+        // Don't include details for security/operational errors (may contain sensitive info)
+    }
+    else if (typeof error === "string") {
+        message = error;
+    }
+    // Include stack trace if requested and error has one
+    if (includeStack && error instanceof Error && error.stack) {
+        stack = error.stack;
+    }
+    const response = {
+        error: {
+            message,
+            code,
+            requestId,
+        },
+    };
+    if (details !== undefined) {
+        response.error.details = details;
+    }
+    if (stack !== undefined) {
+        response.error.stack = stack;
+    }
+    return response;
+}
+//# sourceMappingURL=error-mapper.js.map

package/dist/middleware/error-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-mapper.js","sourceRoot":"","sources":["../../src/middleware/error-mapper.ts"],"names":[],"mappings":"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"}

package/dist/middleware/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Express middleware exports
+ *
+ * Barrel export for all middleware components.
+ */
+export { type AsyncRouteHandler, asyncHandler } from "./async-handler.js";
+export { authMiddleware } from "./auth.js";
+export { csrfProtectionMiddleware } from "./csrf-protection.js";
+export { errorHandler, fallbackErrorHandler } from "./error-handler.js";
+export * from "./error-mapper.js";
+export { requestIdMiddleware } from "./request-id.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,iBAAiB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACxE,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,cAAc,YAAY,CAAC"}

package/dist/middleware/index.js

@@ -0,0 +1,13 @@
+/**
+ * Express middleware exports
+ *
+ * Barrel export for all middleware components.
+ */
+export { asyncHandler } from "./async-handler.js";
+export { authMiddleware } from "./auth.js";
+export { csrfProtectionMiddleware } from "./csrf-protection.js";
+export { errorHandler, fallbackErrorHandler } from "./error-handler.js";
+export * from "./error-mapper.js";
+export { requestIdMiddleware } from "./request-id.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAA0B,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACxE,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,cAAc,YAAY,CAAC"}

package/dist/middleware/request-id.d.ts

@@ -0,0 +1,22 @@
+import type { NextFunction, Request, Response } from "express";
+import "./types.js";
+/**
+ * Request ID middleware
+ *
+ * Generates a unique UUID v4 for each request and:
+ * - Attaches it to req.requestId for downstream use
+ * - Sets X-Request-ID response header for client tracking
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Express next function
+ *
+ * @example
+ * app.use(requestIdMiddleware);
+ * app.get('/api/data', (req, res) => {
+ *   console.log(`Request ID: ${req.requestId}`);
+ *   res.json({ data: 'example' });
+ * });
+ */
+export declare function requestIdMiddleware(req: Request, res: Response, next: NextFunction): void;
+//# sourceMappingURL=request-id.d.ts.map

package/dist/middleware/request-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../../src/middleware/request-id.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAYzF"}

package/dist/middleware/request-id.js

@@ -0,0 +1,31 @@
+import { randomUUID } from "node:crypto";
+import "./types.js"; // Import Request type augmentation
+/**
+ * Request ID middleware
+ *
+ * Generates a unique UUID v4 for each request and:
+ * - Attaches it to req.requestId for downstream use
+ * - Sets X-Request-ID response header for client tracking
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Express next function
+ *
+ * @example
+ * app.use(requestIdMiddleware);
+ * app.get('/api/data', (req, res) => {
+ *   console.log(`Request ID: ${req.requestId}`);
+ *   res.json({ data: 'example' });
+ * });
+ */
+export function requestIdMiddleware(req, res, next) {
+    // Generate UUID v4
+    const requestId = randomUUID();
+    // Attach to request object
+    req.requestId = requestId;
+    // Set response header
+    res.setHeader("X-Request-ID", requestId);
+    // Continue middleware chain
+    next();
+}
+//# sourceMappingURL=request-id.js.map

package/dist/middleware/request-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.js","sourceRoot":"","sources":["../../src/middleware/request-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,YAAY,CAAC,CAAC,mCAAmC;AAExD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;IACjF,mBAAmB;IACnB,MAAM,SAAS,GAAG,UAAU,EAAE,CAAC;IAE/B,2BAA2B;IAC3B,GAAG,CAAC,SAAS,GAAG,SAAS,CAAC;IAE1B,sBAAsB;IACtB,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IAEzC,4BAA4B;IAC5B,IAAI,EAAE,CAAC;AACT,CAAC"}

package/dist/middleware/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Express Request type augmentation
+ *
+ * Adds requestId property to Express Request interface.
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            requestId?: string;
+        }
+    }
+}
+/**
+ * HTTP status codes used in error responses
+ */
+export type HTTPStatusCode = 400 | 429 | 500 | 502;
+/**
+ * Error code strings for classification
+ */
+export type ErrorCode = "VALIDATION_ERROR" | "SECURITY_ERROR" | "HOST_OPERATION_ERROR" | "SSH_COMMAND_ERROR" | "COMPOSE_OPERATION_ERROR" | "INTERNAL_ERROR";
+/**
+ * Structured error response format
+ */
+export interface ErrorResponse {
+    error: {
+        message: string;
+        code: ErrorCode;
+        requestId: string;
+        details?: unknown;
+        stack?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/middleware/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB;KACF;CACF;AAED;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,sBAAsB,GACtB,mBAAmB,GACnB,yBAAyB,GACzB,gBAAgB,CAAC;AAErB;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,SAAS,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH"}