@dyyz1993/create-agent 2.0.0 → 2.1.0

package/templates/general/src/shared/lib/web-server.ts

@@ -0,0 +1,128 @@
+import { createServer, type Server } from "http";
+import { networkInterfaces } from "os";
+import { createHttpHandler } from "../http-routes";
+import { createWsHandler } from "../../gateway/ws-handler";
+import { createLogger } from "./logger";
+
+const log = createLogger("web-server");
+
+export interface WebServerConfig {
+	port: number;
+	authToken: string;
+	maxUploadSize: number;
+	corsOrigin: string;
+}
+
+export interface WebServerResult {
+	httpServer: Server;
+	wss: ReturnType<typeof createWsHandler>;
+	port: number;
+	authToken: string;
+	close: () => Promise<void>;
+}
+
+export function getLocalIP(): string {
+	const nets = networkInterfaces();
+	for (const name of Object.keys(nets)) {
+		const interfaces = nets[name];
+		if (!interfaces) continue;
+		for (const net of interfaces) {
+			if (net.family === "IPv4" && !net.internal) {
+				return net.address;
+			}
+		}
+	}
+	return "127.0.0.1";
+}
+
+function checkPort(port: number): Promise<number> {
+	return new Promise((resolve, reject) => {
+		const testServer = createServer();
+		testServer.once("error", (err: NodeJS.ErrnoException) => {
+			testServer.close();
+			reject(err);
+		});
+		testServer.once("listening", () => {
+			testServer.close();
+			resolve(port);
+		});
+		testServer.listen(port);
+	});
+}
+
+export async function findAvailablePort(startPort: number, maxRetries = 10): Promise<number> {
+	for (let port = startPort; port < startPort + maxRetries; port++) {
+		try {
+			await checkPort(port);
+			return port;
+		} catch {
+			continue;
+		}
+	}
+	throw new Error(`No available port found after ${maxRetries} retries starting from ${startPort}`);
+}
+
+function getFreePort(): Promise<number> {
+	return new Promise((resolve, reject) => {
+		const s = createServer();
+		s.listen(0, () => {
+			const addr = s.address();
+			s.close(() => {
+				if (typeof addr === "object" && addr) {
+					resolve(addr.port);
+				} else {
+					reject(new Error("Failed to allocate port"));
+				}
+			});
+		});
+		s.on("error", reject);
+	});
+}
+
+export async function createWebServer(config: WebServerConfig): Promise<WebServerResult> {
+	const port = config.port === 0 ? await getFreePort() : await findAvailablePort(config.port);
+
+	const httpServer = createServer();
+
+	const wss = createWsHandler(httpServer, {
+		config: {
+			port,
+			authToken: config.authToken,
+			maxUploadSize: config.maxUploadSize,
+		},
+	});
+
+	httpServer.on(
+		"request",
+		createHttpHandler({
+			config: {
+				port,
+				authToken: config.authToken,
+				maxUploadSize: config.maxUploadSize,
+				corsOrigin: config.corsOrigin,
+			},
+			getWebSocketClientCount: () => wss.clients.size,
+		})
+	);
+
+	return new Promise((resolve, reject) => {
+		httpServer.listen(port, () => {
+			log.info("Web server started", { port, corsOrigin: config.corsOrigin });
+
+			resolve({
+				httpServer,
+				wss,
+				port,
+				authToken: config.authToken,
+				close: () =>
+					new Promise<void>((res) => {
+						wss.clients.forEach((ws) => ws.close());
+						wss.close(() => {
+							httpServer.close(() => res());
+						});
+					}),
+			});
+		});
+		httpServer.on("error", reject);
+	});
+}

package/templates/general/src/shared/modules/debug.ts

@@ -0,0 +1,8 @@
+export interface DebugMethods {
+	"debug.subscriptions": {
+		params: {};
+		result: {
+			subscriptions: Array<{ id: string; eventType: string; filter: Record<string, unknown> }>;
+		};
+	};
+}

package/templates/general/src/shared/rpc-schema.ts

@@ -5,6 +5,7 @@ import type { TimerMethods, TimerEvents } from "./modules/timer";
 import type { ChatMethods, ChatEvents } from "./modules/chat";
 import type { GitMethods } from "./modules/git";
 import type { FeedMethods, FeedEvents } from "./modules/feed";
+import type { DebugMethods } from "./modules/debug";
 
 /**
  * RPC 方法定义 — 前后端共享的唯一类型入口
@@ -16,7 +17,16 @@ import type { FeedMethods, FeedEvents } from "./modules/feed";
  * handlers/ 自动发现，无需修改 register-all-handlers.ts
  * 入口文件（bun/index.ts, server.ts）无需修改
  */
-export interface RPCMethods extends AnyMethods, SystemMethods, FileMethods, TimerMethods, ChatMethods, GitMethods, FeedMethods {}
+export interface RPCMethods
+	extends
+		AnyMethods,
+		SystemMethods,
+		FileMethods,
+		TimerMethods,
+		ChatMethods,
+		GitMethods,
+		FeedMethods,
+		DebugMethods {}
 
 /**
  * RPC 事件定义 — 合并所有模块事件
@@ -27,5 +37,5 @@ export interface RPCEvents extends TimerEvents, ChatEvents, FeedEvents {}
  * Handler 注册选项
  */
 export interface HandlerOptions {
-  platform: "desktop" | "web";
+	platform: "desktop" | "web";
 }

package/templates/general/tsconfig.ipc.json

@@ -0,0 +1,14 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"skipLibCheck": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitReturns": true,
+		"noFallthroughCasesInSwitch": true,
+		"strict": true
+	},
+	"include": ["src/bun", "src/gateway/ipc-transport.ts", "src/shared"],
+	"exclude": ["node_modules", "dist", "build", "**/__tests__/**", "**/*.test.ts", "**/*.test.tsx"]
+}

package/templates/general/tsconfig.json

@@ -19,8 +19,18 @@
 		"paths": {
 			"@dyyz1993/rpc-core": ["../packages/rpc-core/src/index.ts"],
 			"@shared/*": ["../shared/*"]
-		}
+		},
+		"noUncheckedIndexedAccess": true,
+		"noImplicitReturns": true
 	},
 	"include": ["src", "../shared"],
-	"exclude": ["node_modules", "dist", "build", "../../package/dist", "**/__tests__/**", "**/*.test.ts", "**/*.test.tsx"]
+	"exclude": [
+		"node_modules",
+		"dist",
+		"build",
+		"../../package/dist",
+		"**/__tests__/**",
+		"**/*.test.ts",
+		"**/*.test.tsx"
+	]
 }

package/templates/shared/__tests__/cors-security.test.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+function mockRes() {
+	const state = { statusCode: 200, body: "", headers: {} as Record<string, string> };
+	const res = {
+		setHeader(key: string, val: string) {
+			state.headers[key] = val;
+		},
+		writeHead(code: number, hdrs?: Record<string, string>) {
+			state.statusCode = code;
+			if (hdrs) Object.assign(state.headers, hdrs);
+			return res;
+		},
+		end(data?: string) {
+			if (data !== undefined) state.body = data;
+		},
+	};
+	return { res, state };
+}
+
+function mockReq(url: string, opts?: { method?: string; headers?: Record<string, string> }) {
+	return {
+		url,
+		method: opts?.method ?? "GET",
+		headers: {
+			"content-length": "0",
+			...opts?.headers,
+		},
+		[Symbol.asyncIterator]() {
+			return { next: () => Promise.resolve({ done: true }) };
+		},
+	};
+}
+
+describe("CORS 安全", () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("混合模式下默认 CORS 允许所有来源", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config: {
+				port: 3000,
+				authToken: "test-token",
+				maxUploadSize: 1024 * 1024,
+				corsOrigin: "*",
+			},
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(mockReq("/health"), res);
+
+		expect(state.headers["Access-Control-Allow-Origin"]).toBe("*");
+	});
+
+	it("显式设置 CORS_ORIGIN 时只允许指定来源", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config: {
+				port: 3000,
+				authToken: "test-token",
+				maxUploadSize: 1024 * 1024,
+				corsOrigin: "http://localhost:5173",
+			},
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(mockReq("/health"), res);
+
+		expect(state.headers["Access-Control-Allow-Origin"]).toBe("http://localhost:5173");
+		expect(state.headers["Access-Control-Allow-Origin"]).not.toBe("*");
+	});
+
+	it("OPTIONS 预检请求返回正确的 CORS headers", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config: {
+				port: 3000,
+				authToken: "test-token",
+				maxUploadSize: 1024 * 1024,
+				corsOrigin: "http://localhost:5173",
+			},
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(mockReq("/file/some/path", { method: "OPTIONS" }), res);
+
+		expect(state.statusCode).toBe(204);
+		expect(state.headers["Access-Control-Allow-Origin"]).toBe("http://localhost:5173");
+		expect(state.headers["Access-Control-Allow-Methods"]).toBe("GET, POST, OPTIONS");
+		expect(state.headers["Access-Control-Allow-Headers"]).toContain("Authorization");
+		expect(state.headers["Access-Control-Allow-Headers"]).toContain("Content-Type");
+	});
+
+	it("非预检请求也返回 CORS headers", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config: {
+				port: 3000,
+				authToken: "test-token",
+				maxUploadSize: 1024 * 1024,
+				corsOrigin: "http://localhost:5173",
+			},
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq("/info/nonexistent", {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect(state.statusCode).not.toBe(204);
+		expect(state.headers["Access-Control-Allow-Origin"]).toBe("http://localhost:5173");
+	});
+
+	it("401 响应也包含 CORS headers（浏览器需要）", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config: {
+				port: 3000,
+				authToken: "test-token",
+				maxUploadSize: 1024 * 1024,
+				corsOrigin: "http://localhost:5173",
+			},
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(mockReq("/file/test.txt"), res);
+
+		expect(state.statusCode).toBe(401);
+		expect(state.headers["Access-Control-Allow-Origin"]).toBe("http://localhost:5173");
+	});
+
+	it("CORS headers 在所有路径上均存在（包括 404）", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config: {
+				port: 3000,
+				authToken: "test-token",
+				maxUploadSize: 1024 * 1024,
+				corsOrigin: "http://localhost:5173",
+			},
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq("/unknown", {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect(state.statusCode).toBe(404);
+		expect(state.headers["Access-Control-Allow-Origin"]).toBe("http://localhost:5173");
+	});
+});

package/templates/shared/__tests__/file-path-security.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { resolve } from "path";
+
+function mockRes() {
+	const state = { statusCode: 200, body: "", headers: {} as Record<string, string> };
+	const res = {
+		setHeader(key: string, val: string) {
+			state.headers[key] = val;
+		},
+		writeHead(code: number, hdrs?: Record<string, string>) {
+			state.statusCode = code;
+			if (hdrs) Object.assign(state.headers, hdrs);
+			return res;
+		},
+		end(data?: string) {
+			if (data !== undefined) state.body = data;
+		},
+	};
+	return { res, state };
+}
+
+function mockReq(url: string, opts?: { method?: string; headers?: Record<string, string> }) {
+	return {
+		url,
+		method: opts?.method ?? "GET",
+		headers: {
+			"content-length": "0",
+			...opts?.headers,
+		},
+		[Symbol.asyncIterator]() {
+			return { next: () => Promise.resolve({ done: true }) };
+		},
+	};
+}
+
+const CWD = resolve(process.cwd());
+const config = {
+	port: 3000,
+	authToken: "test-token",
+	maxUploadSize: 1024 * 1024 * 10,
+	corsOrigin: "*",
+};
+
+describe("文件路径安全", () => {
+	beforeEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	it("不允许访问项目根目录以外的文件（路径穿越 ../ 阻断）", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const traversalPaths = [
+			`/file/${encodeURIComponent(CWD + "/../../../etc/passwd")}`,
+			`/file/${encodeURIComponent("../../../etc/passwd")}`,
+			`/file/${encodeURIComponent(CWD + "/../../tmp/evil")}`,
+		];
+
+		for (const path of traversalPaths) {
+			const { res, state } = mockRes();
+			await handler(
+				mockReq(path, {
+					headers: { authorization: "Bearer test-token" },
+				}),
+				res
+			);
+			expect(state.statusCode, `Expected 403 for path: ${path}`).toBe(403);
+			expect(JSON.parse(state.body).error).toBe("Path not allowed");
+		}
+	});
+
+	it("不允许访问绝对路径 /etc/passwd", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/file/${encodeURIComponent("/etc/passwd")}`, {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect(state.statusCode).toBe(403);
+	});
+
+	it("不允许访问系统目录 /tmp", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/file/${encodeURIComponent("/tmp/evil-file")}`, {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect(state.statusCode).toBe(403);
+	});
+
+	it("/info 端点同样阻止路径穿越", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/info/${encodeURIComponent("/etc/passwd")}`, {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect(state.statusCode).toBe(403);
+	});
+
+	it("URL 编码绕过 %2e%2e%2f 被阻断", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const doubleEncodedPath = "%252e%252e%252f" + "etc%252fpasswd";
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/file/${doubleEncodedPath}`, {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		const isBlocked = state.statusCode === 403 || state.statusCode === 404;
+		expect(isBlocked, `Expected 403 or 404, got ${state.statusCode}`).toBe(true);
+	});
+
+	it("允许访问项目根目录内的文件", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/file/${encodeURIComponent(CWD + "/package.json")}`, {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect(state.statusCode).not.toBe(403);
+	});
+
+	it("允许访问子目录内的文件", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/file/${encodeURIComponent(CWD + "/src/some-file.txt")}`, {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect(state.statusCode).not.toBe(403);
+	});
+
+	it("上传文件路径也受 ALLOWED_ROOTS 限制", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/file/upload?path=${encodeURIComponent("/tmp/evil-upload.txt")}`, {
+				method: "POST",
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect(state.statusCode).toBe(403);
+		expect(JSON.parse(state.body).error).toBe("Path not allowed");
+	});
+
+	it("上传文件到项目目录内被允许（不会 403）", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/file/upload?path=${encodeURIComponent(CWD + "/test-upload.txt")}`, {
+				method: "POST",
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect(state.statusCode).not.toBe(403);
+	});
+
+	it("空路径被拒绝", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/file/`, {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect([403, 404, 500].includes(state.statusCode)).toBe(true);
+	});
+
+	it("Windows 风格反斜杠路径被正确处理", async () => {
+		const { createHttpHandler } = await import("../http-routes");
+		const handler = createHttpHandler({
+			config,
+			getWebSocketClientCount: () => 0,
+		});
+
+		const { res, state } = mockRes();
+		await handler(
+			mockReq(`/file/${encodeURIComponent("..\\..\\etc\\passwd")}`, {
+				headers: { authorization: "Bearer test-token" },
+			}),
+			res
+		);
+
+		expect([403, 404].includes(state.statusCode)).toBe(true);
+	});
+});