@sylphx/lens-server 2.3.2 → 2.4.0

package/src/handlers/http.test.ts

@@ -139,12 +139,12 @@ describe("createHTTPHandler", () => {
 		expect(data.data.id).toBe("456");
 	});
 
-	it("handles CORS preflight", async () => {
+	it("handles CORS preflight in development mode", async () => {
 		const app = createApp({
 			queries: { getUser },
 			mutations: { createUser },
 		});
-		const handler = createHTTPHandler(app);
+		const handler = createHTTPHandler(app, { errors: { development: true } });
 
 		const request = new Request("http://localhost/", {
 			method: "OPTIONS",
@@ -155,6 +155,39 @@ describe("createHTTPHandler", () => {
 		expect(response.headers.get("Access-Control-Allow-Origin")).toBe("*");
 	});
 
+	it("does not allow CORS by default in production mode", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app); // Production mode is default
+
+		const request = new Request("http://localhost/", {
+			method: "OPTIONS",
+		});
+
+		const response = await handler(request);
+		expect(response.status).toBe(204);
+		// No Access-Control-Allow-Origin header in production without explicit config
+		expect(response.headers.get("Access-Control-Allow-Origin")).toBeNull();
+	});
+
+	it("allows CORS with explicit origin configuration", async () => {
+		const app = createApp({
+			queries: { getUser },
+			mutations: { createUser },
+		});
+		const handler = createHTTPHandler(app, { cors: { origin: "https://example.com" } });
+
+		const request = new Request("http://localhost/", {
+			method: "OPTIONS",
+		});
+
+		const response = await handler(request);
+		expect(response.status).toBe(204);
+		expect(response.headers.get("Access-Control-Allow-Origin")).toBe("https://example.com");
+	});
+
 	it("returns 404 for unknown paths", async () => {
 		const app = createApp({
 			queries: { getUser },
@@ -212,4 +245,196 @@ describe("createHTTPHandler", () => {
 		const data = await response.json();
 		expect(data.error).toContain("not found");
 	});
+
+	describe("health check", () => {
+		it("returns health status on GET /__lens/health", async () => {
+			const app = createApp({
+				queries: { getUser },
+				mutations: { createUser },
+			});
+			const handler = createHTTPHandler(app);
+
+			const request = new Request("http://localhost/__lens/health", {
+				method: "GET",
+			});
+
+			const response = await handler(request);
+			expect(response.status).toBe(200);
+
+			const data = await response.json();
+			expect(data.status).toBe("healthy");
+			expect(data.service).toBe("lens-server");
+			expect(data.version).toBeDefined();
+			expect(data.uptime).toBeGreaterThanOrEqual(0);
+			expect(data.timestamp).toBeDefined();
+		});
+
+		it("supports path prefix for health endpoint", async () => {
+			const app = createApp({
+				queries: { getUser },
+				mutations: { createUser },
+			});
+			const handler = createHTTPHandler(app, { pathPrefix: "/api" });
+
+			const request = new Request("http://localhost/api/__lens/health", {
+				method: "GET",
+			});
+
+			const response = await handler(request);
+			expect(response.status).toBe(200);
+
+			const data = await response.json();
+			expect(data.status).toBe("healthy");
+		});
+
+		it("supports custom health check path", async () => {
+			const app = createApp({
+				queries: { getUser },
+				mutations: { createUser },
+			});
+			const handler = createHTTPHandler(app, {
+				health: { path: "/healthz" },
+			});
+
+			const request = new Request("http://localhost/healthz", {
+				method: "GET",
+			});
+
+			const response = await handler(request);
+			expect(response.status).toBe(200);
+		});
+
+		it("can be disabled", async () => {
+			const app = createApp({
+				queries: { getUser },
+				mutations: { createUser },
+			});
+			const handler = createHTTPHandler(app, {
+				health: { enabled: false },
+			});
+
+			const request = new Request("http://localhost/__lens/health", {
+				method: "GET",
+			});
+
+			const response = await handler(request);
+			expect(response.status).toBe(404);
+		});
+
+		it("includes custom health checks", async () => {
+			const app = createApp({
+				queries: { getUser },
+				mutations: { createUser },
+			});
+			const handler = createHTTPHandler(app, {
+				health: {
+					checks: () => ({
+						database: { status: "pass", message: "Connected" },
+						cache: { status: "pass" },
+					}),
+				},
+			});
+
+			const request = new Request("http://localhost/__lens/health", {
+				method: "GET",
+			});
+
+			const response = await handler(request);
+			expect(response.status).toBe(200);
+
+			const data = await response.json();
+			expect(data.checks?.database.status).toBe("pass");
+			expect(data.checks?.cache.status).toBe("pass");
+		});
+
+		it("returns 503 when custom health check fails", async () => {
+			const app = createApp({
+				queries: { getUser },
+				mutations: { createUser },
+			});
+			const handler = createHTTPHandler(app, {
+				health: {
+					checks: () => ({
+						database: { status: "fail", message: "Connection refused" },
+					}),
+				},
+			});
+
+			const request = new Request("http://localhost/__lens/health", {
+				method: "GET",
+			});
+
+			const response = await handler(request);
+			expect(response.status).toBe(503);
+
+			const data = await response.json();
+			expect(data.status).toBe("degraded");
+			expect(data.checks?.database.status).toBe("fail");
+		});
+
+		it("handles async health checks", async () => {
+			const app = createApp({
+				queries: { getUser },
+				mutations: { createUser },
+			});
+			const handler = createHTTPHandler(app, {
+				health: {
+					checks: async () => {
+						await new Promise((r) => setTimeout(r, 10));
+						return { async: { status: "pass" } };
+					},
+				},
+			});
+
+			const request = new Request("http://localhost/__lens/health", {
+				method: "GET",
+			});
+
+			const response = await handler(request);
+			expect(response.status).toBe(200);
+
+			const data = await response.json();
+			expect(data.checks?.async.status).toBe("pass");
+		});
+
+		it("handles health check errors gracefully", async () => {
+			const app = createApp({
+				queries: { getUser },
+				mutations: { createUser },
+			});
+			const handler = createHTTPHandler(app, {
+				health: {
+					checks: () => {
+						throw new Error("Check failed");
+					},
+				},
+			});
+
+			const request = new Request("http://localhost/__lens/health", {
+				method: "GET",
+			});
+
+			const response = await handler(request);
+			expect(response.status).toBe(503);
+
+			const data = await response.json();
+			expect(data.status).toBe("degraded");
+			expect(data.checks?.healthCheck.status).toBe("fail");
+		});
+
+		it("includes Cache-Control header", async () => {
+			const app = createApp({
+				queries: { getUser },
+				mutations: { createUser },
+			});
+			const handler = createHTTPHandler(app);
+
+			const request = new Request("http://localhost/__lens/health", {
+				method: "GET",
+			});
+
+			const response = await handler(request);
+			expect(response.headers.get("Cache-Control")).toBe("no-cache, no-store, must-revalidate");
+		});
+	});
 });

package/src/handlers/http.ts

@@ -12,6 +12,64 @@ import type { LensServer } from "../server/create.js";
 // Types
 // =============================================================================
 
+/** Error sanitization options */
+export interface ErrorSanitizationOptions {
+	/**
+	 * Enable development mode - shows full error messages.
+	 * Default: false (production mode - sanitized errors only)
+	 */
+	development?: boolean;
+
+	/**
+	 * Custom error sanitizer function.
+	 * Return a safe error message to send to the client.
+	 */
+	sanitize?: (error: Error) => string;
+}
+
+/**
+ * Health check response data
+ */
+export interface HealthCheckResponse {
+	/** Overall status */
+	status: "healthy" | "degraded" | "unhealthy";
+	/** Service name */
+	service: string;
+	/** Server version */
+	version: string;
+	/** Uptime in seconds */
+	uptime: number;
+	/** Timestamp of health check */
+	timestamp: string;
+	/** Optional checks with their status */
+	checks?: Record<string, { status: "pass" | "fail"; message?: string }>;
+}
+
+/**
+ * Health check options
+ */
+export interface HealthCheckOptions {
+	/**
+	 * Enable health check endpoint.
+	 * Default: true
+	 */
+	enabled?: boolean;
+
+	/**
+	 * Custom health check path.
+	 * Default: "/__lens/health"
+	 */
+	path?: string;
+
+	/**
+	 * Custom health check function.
+	 * Return additional checks to include in the response.
+	 */
+	checks?: () =>
+		| Promise<Record<string, { status: "pass" | "fail"; message?: string }>>
+		| Record<string, { status: "pass" | "fail"; message?: string }>;
+}
+
 export interface HTTPHandlerOptions {
 	/**
 	 * Path prefix for Lens endpoints.
@@ -29,13 +87,25 @@ export interface HTTPHandlerOptions {
 
 	/**
 	 * Custom CORS headers.
-	 * Default: Allow all origins
+	 * Default: Allow all origins in development, strict in production
 	 */
 	cors?: {
 		origin?: string | string[];
 		methods?: string[];
 		headers?: string[];
 	};
+
+	/**
+	 * Error sanitization options.
+	 * Controls what error information is exposed to clients.
+	 */
+	errors?: ErrorSanitizationOptions;
+
+	/**
+	 * Health check endpoint configuration.
+	 * Enabled by default at /__lens/health
+	 */
+	health?: HealthCheckOptions;
 }
 
 export interface HTTPHandler {
@@ -75,23 +145,100 @@ export interface HTTPHandler {
  * export default { fetch: handler }
  * ```
  */
+/**
+ * Default error sanitizer - removes sensitive information from errors.
+ * Safe error messages are preserved, internal details are hidden.
+ */
+function sanitizeError(error: Error, isDevelopment: boolean): string {
+	if (isDevelopment) {
+		return error.message;
+	}
+
+	const message = error.message;
+
+	// Known safe error patterns (validation errors, business logic errors)
+	const safePatterns = [
+		/^Invalid input:/,
+		/^Missing operation/,
+		/^Not found/,
+		/^Unauthorized/,
+		/^Forbidden/,
+		/^Bad request/,
+		/^Validation failed/,
+	];
+
+	if (safePatterns.some((pattern) => pattern.test(message))) {
+		return message;
+	}
+
+	// Check for sensitive patterns
+	const sensitivePatterns = [
+		/\/[^\s]+\.(ts|js|json)/, // file paths
+		/at\s+[^\s]+\s+\(/, // stack traces
+		/ENOENT|EACCES|ECONNREFUSED/, // system errors
+		/SELECT|INSERT|UPDATE|DELETE|FROM|WHERE/i, // SQL
+		/password|secret|token|key|auth/i, // credentials
+	];
+
+	if (sensitivePatterns.some((pattern) => pattern.test(message))) {
+		return "An internal error occurred";
+	}
+
+	// Allow short, simple messages through
+	if (message.length < 100 && !message.includes("\n")) {
+		return message;
+	}
+
+	return "An internal error occurred";
+}
+
 export function createHTTPHandler(
 	server: LensServer,
 	options: HTTPHandlerOptions = {},
 ): HTTPHandler {
-	const { pathPrefix = "", cors } = options;
+	const { pathPrefix = "", cors, errors, health } = options;
+	const isDevelopment = errors?.development ?? false;
+
+	// Health check configuration
+	const healthEnabled = health?.enabled !== false; // Enabled by default
+	const healthPath = health?.path ?? "/__lens/health";
+	const startTime = Date.now();
+
+	// Error sanitization function
+	const sanitize = (error: Error): string => {
+		if (errors?.sanitize) {
+			return errors.sanitize(error);
+		}
+		return sanitizeError(error, isDevelopment);
+	};
 
 	// Build CORS headers
-	const corsHeaders: Record<string, string> = {
-		"Access-Control-Allow-Origin": cors?.origin
-			? Array.isArray(cors.origin)
-				? cors.origin.join(", ")
-				: cors.origin
-			: "*",
+	// In production, require explicit origin configuration for security
+	// In development, allow all origins for convenience
+	const allowedOrigin = cors?.origin
+		? Array.isArray(cors.origin)
+			? cors.origin.join(", ")
+			: cors.origin
+		: isDevelopment
+			? "*"
+			: ""; // No cross-origin allowed by default in production
+
+	// Base headers including security headers
+	const baseHeaders: Record<string, string> = {
+		"Content-Type": "application/json",
+		// Security headers
+		"X-Content-Type-Options": "nosniff",
+		"X-Frame-Options": "DENY",
+		// CORS headers
 		"Access-Control-Allow-Methods": cors?.methods?.join(", ") ?? "GET, POST, OPTIONS",
 		"Access-Control-Allow-Headers": cors?.headers?.join(", ") ?? "Content-Type, Authorization",
 	};
 
+	// Only add Access-Control-Allow-Origin if there's an allowed origin
+	if (allowedOrigin) {
+		baseHeaders["Access-Control-Allow-Origin"] = allowedOrigin;
+	}
+
 	const handler = async (request: Request): Promise<Response> => {
 		const url = new URL(request.url);
 		const pathname = url.pathname;
@@ -100,7 +247,52 @@ export function createHTTPHandler(
 		if (request.method === "OPTIONS") {
 			return new Response(null, {
 				status: 204,
-				headers: corsHeaders,
+				headers: baseHeaders,
+			});
+		}
+
+		// Health check endpoint: GET /__lens/health
+		const fullHealthPath = `${pathPrefix}${healthPath}`;
+		if (healthEnabled && request.method === "GET" && pathname === fullHealthPath) {
+			const metadata = server.getMetadata();
+			const uptimeSeconds = Math.floor((Date.now() - startTime) / 1000);
+
+			// Run custom health checks if provided
+			let customChecks: Record<string, { status: "pass" | "fail"; message?: string }> = {};
+			let hasFailure = false;
+
+			if (health?.checks) {
+				try {
+					customChecks = await health.checks();
+					hasFailure = Object.values(customChecks).some((c) => c.status === "fail");
+				} catch (error) {
+					customChecks.healthCheck = {
+						status: "fail",
+						message: error instanceof Error ? error.message : "Health check failed",
+					};
+					hasFailure = true;
+				}
+			}
+
+			const response: HealthCheckResponse = {
+				status: hasFailure ? "degraded" : "healthy",
+				service: "lens-server",
+				version: metadata.version,
+				uptime: uptimeSeconds,
+				timestamp: new Date().toISOString(),
+			};
+
+			if (Object.keys(customChecks).length > 0) {
+				response.checks = customChecks;
+			}
+
+			return new Response(JSON.stringify(response), {
+				status: hasFailure ? 503 : 200,
+				headers: {
+					"Content-Type": "application/json",
+					"Cache-Control": "no-cache, no-store, must-revalidate",
+					...baseHeaders,
+				},
 			});
 		}
 
@@ -110,7 +302,7 @@ export function createHTTPHandler(
 			return new Response(JSON.stringify(server.getMetadata()), {
 				headers: {
 					"Content-Type": "application/json",
-					...corsHeaders,
+					...baseHeaders,
 				},
 			});
 		}
@@ -121,13 +313,21 @@ export function createHTTPHandler(
 			request.method === "POST" &&
 			(pathname === operationPath || pathname === `${pathPrefix}/`)
 		) {
+			// Parse JSON body with proper error handling
+			let body: { operation?: string; path?: string; input?: unknown };
 			try {
-				const body = (await request.json()) as {
-					operation?: string;
-					path?: string;
-					input?: unknown;
-				};
+				body = (await request.json()) as typeof body;
+			} catch {
+				return new Response(JSON.stringify({ error: "Invalid JSON in request body" }), {
+					status: 400,
+					headers: {
+						"Content-Type": "application/json",
+						...baseHeaders,
+					},
+				});
+			}
 
+			try {
 				// Support both 'operation' and 'path' for backwards compatibility
 				const operationPath = body.operation ?? body.path;
 				if (!operationPath) {
@@ -135,7 +335,7 @@ export function createHTTPHandler(
 						status: 400,
 						headers: {
 							"Content-Type": "application/json",
-							...corsHeaders,
+							...baseHeaders,
 						},
 					});
 				}
@@ -148,11 +348,11 @@ export function createHTTPHandler(
 				);
 
 				if (result.error) {
-					return new Response(JSON.stringify({ error: result.error.message }), {
+					return new Response(JSON.stringify({ error: sanitize(result.error) }), {
 						status: 500,
 						headers: {
 							"Content-Type": "application/json",
-							...corsHeaders,
+							...baseHeaders,
 						},
 					});
 				}
@@ -160,15 +360,16 @@ export function createHTTPHandler(
 				return new Response(JSON.stringify({ data: result.data }), {
 					headers: {
 						"Content-Type": "application/json",
-						...corsHeaders,
+						...baseHeaders,
 					},
 				});
 			} catch (error) {
-				return new Response(JSON.stringify({ error: String(error) }), {
+				const err = error instanceof Error ? error : new Error(String(error));
+				return new Response(JSON.stringify({ error: sanitize(err) }), {
 					status: 500,
 					headers: {
 						"Content-Type": "application/json",
-						...corsHeaders,
+						...baseHeaders,
 					},
 				});
 			}
@@ -179,7 +380,7 @@ export function createHTTPHandler(
 			status: 404,
 			headers: {
 				"Content-Type": "application/json",
-				...corsHeaders,
+				...baseHeaders,
 			},
 		});
 	};

package/src/handlers/index.ts

@@ -40,6 +40,8 @@ export {
 
 export {
 	createHTTPHandler,
+	type HealthCheckOptions,
+	type HealthCheckResponse,
 	type HTTPHandler,
 	type HTTPHandlerOptions,
 } from "./http.js";

package/src/handlers/ws-types.ts

@@ -20,6 +20,45 @@ export interface WSHandlerOptions {
 		warn?: (message: string, ...args: unknown[]) => void;
 		error?: (message: string, ...args: unknown[]) => void;
 	};
+
+	/**
+	 * Maximum message size in bytes.
+	 * Messages larger than this will be rejected.
+	 * Default: 1MB (1024 * 1024)
+	 */
+	maxMessageSize?: number;
+
+	/**
+	 * Maximum subscriptions per client.
+	 * Prevents resource exhaustion from malicious clients.
+	 * Default: 100
+	 */
+	maxSubscriptionsPerClient?: number;
+
+	/**
+	 * Maximum connections total.
+	 * Prevents server overload.
+	 * Default: 10000
+	 */
+	maxConnections?: number;
+
+	/**
+	 * Rate limiting configuration.
+	 * Uses token bucket algorithm per client.
+	 */
+	rateLimit?: {
+		/**
+		 * Maximum messages per window.
+		 * Default: 100
+		 */
+		maxMessages?: number;
+
+		/**
+		 * Time window in milliseconds.
+		 * Default: 1000 (1 second)
+		 */
+		windowMs?: number;
+	};
 }
 
 /**