diff --git a/docs/user_guide/zh/modules/tooling/function.md b/docs/user_guide/zh/modules/tooling/function.md index 41accd45..b9b1841d 100755 --- a/docs/user_guide/zh/modules/tooling/function.md +++ b/docs/user_guide/zh/modules/tooling/function.md @@ -74,7 +74,21 @@ nodes: 3. 若函数依赖额外第三方库,可在仓库 `requirements.txt`/`pyproject.toml` 中声明,或在函数内调用 `install_python_packages`(同目录提供)动态安装。 4. 运行 `python -m tools.export_design_template ...` 以刷新前端枚举。 -## 6. 调试与排错 +## 6. 本地 API 安装 + +后端和前端开发服务器默认仅监听 `127.0.0.1`。通过 API 上传工具时,先向 +`GET /api/tools/local/session` 发送请求头 `X-ChatDev-Local: 1`,再将返回的 +`token` 放入 `POST /api/tools/local` 的 `X-ChatDev-Tool-Token` 请求头。 +前端可直接调用 `frontend/src/utils/apiFunctions.js` 中的 `uploadLocalTool()`, +它会自动完成这两个步骤,无需登录。令牌在后端进程重启后失效,不要记录或分享它。 + +两个接口均检查本地连接和 Host;浏览器 Origin 默认仅允许 +`http://localhost:5173` 和 `http://127.0.0.1:5173`。更换前端端口时, +在后端通过 `CORS_ALLOW_ORIGINS` 配置完整来源地址(逗号分隔,不支持 `*`)。 +上传的 Python 代码仍在服务器进程内执行,请仅安装自己信任的代码。 + +## 7. 调试与排错 + - 若前端/CLI 报告 “function 'xxx' not found”,检查函数名称与文件是否位于 `MAC_FUNCTIONS_DIR`(默认 `functions/function_calling/`)。 - `function_catalog` 加载失败时,`FunctionToolEntryConfig.field_specs()` 会在描述中提示错误,请先修复函数语法或依赖。 - 工具运行超时会向 Agent 返回异常文本;可通过 `timeout` 扩大限额,或在函数内部自行捕获并返回友好错误。 diff --git a/frontend/src/utils/apiFunctions.js b/frontend/src/utils/apiFunctions.js index 90a28a52..bf6b5b11 100755 --- a/frontend/src/utils/apiFunctions.js +++ b/frontend/src/utils/apiFunctions.js @@ -1,6 +1,32 @@ const apiUrl = (path) => path +// Install trusted Python code using a process-local session token. Fetch a fresh +// token for each upload so backend restarts do not require a page refresh. +export async function uploadLocalTool(filename, content, overwrite = false) { + const session = await fetch(apiUrl('/api/tools/local/session'), { + headers: { 'X-ChatDev-Local': '1' }, + cache: 'no-store', + }) + if (!session.ok) { + throw new Error(`Local tool session failed: ${session.status}`) + } + const { token } = await session.json() + const response = await fetch(apiUrl('/api/tools/local'), { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'X-ChatDev-Tool-Token': token, + }, + body: JSON.stringify({ filename, content, overwrite }), + }) + const data = await response.json() + if (!response.ok) { + throw new Error(data.detail || `Tool upload failed: ${response.status}`) + } + return data +} + const addYamlSuffix = (filename) => { const trimmed = (filename || '').trim() if (!trimmed) { diff --git a/frontend/vite.config.js b/frontend/vite.config.js index 9413b917..c017b5a4 100755 --- a/frontend/vite.config.js +++ b/frontend/vite.config.js @@ -9,7 +9,7 @@ export default defineConfig(({ mode }) => { return { plugins: [vue()], server: { - host: true, + host: '127.0.0.1', proxy: { '/api': { target: target, diff --git a/server/bootstrap.py b/server/bootstrap.py index 17942b85..b0f875e1 100755 --- a/server/bootstrap.py +++ b/server/bootstrap.py @@ -1,7 +1,6 @@ """Application bootstrap helpers for the FastAPI server.""" from fastapi import FastAPI -from fastapi.middleware.cors import CORSMiddleware from server import state from server.config_schema_router import router as config_schema_router @@ -13,14 +12,6 @@ from utils.middleware import add_middleware def init_app(app: FastAPI) -> None: """Apply shared middleware, routers, and global state to ``app``.""" - app.add_middleware( - CORSMiddleware, - allow_origins=["*"], - allow_credentials=True, - allow_methods=["*"], - allow_headers=["*"], - ) - add_exception_handlers(app) add_middleware(app) diff --git a/server/local_security.py b/server/local_security.py new file mode 100644 index 00000000..d4d003c0 --- /dev/null +++ b/server/local_security.py @@ -0,0 +1,48 @@ +"""Access checks for installing trusted Python tools in the local app.""" + +import ipaddress +import os +import secrets + +from fastapi import HTTPException, Request + + +_LOCAL_TOOL_TOKEN = secrets.token_urlsafe(32) +_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"} + + +def allowed_browser_origins() -> list[str]: + configured = os.getenv("CORS_ALLOW_ORIGINS") + if configured is not None: + # Wildcards must never authorize reading the local session token. + return [origin.strip() for origin in configured.split(",") if origin.strip() and origin.strip() != "*"] + return ["http://localhost:5173", "http://127.0.0.1:5173"] + + +def require_local_tool_access(request: Request) -> None: + try: + local_client = request.client is not None and ipaddress.ip_address(request.client.host).is_loopback + except ValueError: + local_client = False + # Check Host as well as the peer address to reject DNS rebinding. + if not local_client or request.url.hostname not in _LOCAL_HOSTS: + raise HTTPException(status_code=403, detail="Tool installation is only available locally") + + origin = request.headers.get("origin") + if origin is not None and origin not in allowed_browser_origins(): + raise HTTPException(status_code=403, detail="Browser origin is not allowed") + + +def local_tool_session(request: Request) -> dict[str, str]: + require_local_tool_access(request) + # A custom header prevents cross-origin simple requests from reading a token. + if request.headers.get("x-chatdev-local") != "1": + raise HTTPException(status_code=403, detail="Local session header is required") + return {"token": _LOCAL_TOOL_TOKEN} + + +def require_local_tool_token(request: Request) -> None: + require_local_tool_access(request) + token = request.headers.get("x-chatdev-tool-token", "") + if not secrets.compare_digest(token.encode("utf-8"), _LOCAL_TOOL_TOKEN.encode("utf-8")): + raise HTTPException(status_code=403, detail="Valid local tool token is required") diff --git a/server/routes/tools.py b/server/routes/tools.py index 71467ded..4c7a2c26 100644 --- a/server/routes/tools.py +++ b/server/routes/tools.py @@ -1,9 +1,10 @@ import re from pathlib import Path -from fastapi import APIRouter, HTTPException +from fastapi import APIRouter, Depends, HTTPException, Request, Response from pydantic import BaseModel, constr +from server.local_security import local_tool_session, require_local_tool_token from utils.function_catalog import get_function_catalog from utils.function_manager import FUNCTION_CALLING_DIR @@ -40,7 +41,13 @@ def list_local_tools(): } -@router.post("/api/tools/local") +@router.get("/api/tools/local/session") +def get_local_tool_session(request: Request, response: Response): + response.headers["Cache-Control"] = "no-store" + return local_tool_session(request) + + +@router.post("/api/tools/local", dependencies=[Depends(require_local_tool_token)]) def create_local_tool(payload: LocalToolCreateRequest): raw_name = payload.filename.strip() if not raw_name: diff --git a/server_main.py b/server_main.py index d0be04cb..aaa450d3 100755 --- a/server_main.py +++ b/server_main.py @@ -74,8 +74,8 @@ def build_parser() -> argparse.ArgumentParser: parser.add_argument( "--host", type=str, - default="0.0.0.0", - help="Server host (default: 0.0.0.0)" + default="127.0.0.1", + help="Server host (default: 127.0.0.1)" ) parser.add_argument( "--port", diff --git a/tests/test_local_tool_security.py b/tests/test_local_tool_security.py new file mode 100644 index 00000000..ffe17f05 --- /dev/null +++ b/tests/test_local_tool_security.py @@ -0,0 +1,137 @@ +"""Exercise the actual upload route without importing the workflow runtime.""" + +import importlib.util +import sys +from pathlib import Path + +import pytest +from fastapi import FastAPI +from fastapi.middleware.cors import CORSMiddleware +from fastapi.testclient import TestClient + +from server.local_security import allowed_browser_origins +from utils.function_catalog import FunctionCatalog + + +@pytest.fixture +def local_tools(tmp_path, monkeypatch): + monkeypatch.delenv("CORS_ALLOW_ORIGINS", raising=False) + spec = importlib.util.spec_from_file_location( + "local_tools_under_test", + Path(__file__).resolve().parents[1] / "server/routes/tools.py", + ) + routes = importlib.util.module_from_spec(spec) + monkeypatch.setitem(sys.modules, spec.name, routes) + spec.loader.exec_module(routes) + catalog = FunctionCatalog(tmp_path) + monkeypatch.setattr(routes, "FUNCTION_CALLING_DIR", tmp_path) + monkeypatch.setattr(routes, "get_function_catalog", lambda: catalog) + app = FastAPI() + app.include_router(routes.router) + app.add_middleware( + CORSMiddleware, + allow_origins=allowed_browser_origins(), + allow_methods=["*"], + allow_headers=["*"], + ) + return app, tmp_path + + +def client_for(app, host="127.0.0.1"): + return TestClient(app, base_url="http://127.0.0.1:8000", client=(host, 12345)) + + +def session_token(client): + response = client.get( + "/api/tools/local/session", + headers={"X-ChatDev-Local": "1", "Origin": "http://localhost:5173"}, + ) + assert response.status_code == 200 + assert response.headers["cache-control"] == "no-store" + return response.json()["token"] + + +@pytest.mark.parametrize("token", [None, "incorrect", "非有效令牌"]) +def test_unauthorized_upload_does_not_write_or_execute(local_tools, token): + app, directory = local_tools + headers = {} if token is None else {"X-ChatDev-Tool-Token": token.encode("utf-8")} + with client_for(app) as client: + response = client.post( + "/api/tools/local", headers=headers, + json={"filename": "probe.py", "content": "raise RuntimeError('must not execute')"}, + ) + assert response.status_code == 403 + assert list(directory.iterdir()) == [] + + +def test_authorized_upload_preserves_install_and_load(local_tools): + app, directory = local_tools + marker = directory / "executed.txt" + source = f"from pathlib import Path\nPath({str(marker)!r}).write_text('ok')\n" + with client_for(app) as client: + token = session_token(client) + response = client.post( + "/api/tools/local", + headers={"X-ChatDev-Tool-Token": token, "Origin": "http://localhost:5173"}, + json={"filename": "probe.py", "content": source}, + ) + assert response.status_code == 200 + assert (directory / "probe.py").read_text() == source + assert marker.read_text() == "ok" + + +@pytest.mark.parametrize("origin", ["https://evil.example", "null", "http://localhost:5174"]) +def test_disallowed_origin_cannot_get_token_or_upload(local_tools, origin): + app, directory = local_tools + with client_for(app) as client: + token = session_token(client) + headers = {"Origin": origin, "X-ChatDev-Local": "1", "X-ChatDev-Tool-Token": token} + assert client.get("/api/tools/local/session", headers=headers).status_code == 403 + response = client.post( + "/api/tools/local", headers=headers, + json={"filename": "probe", "content": "pass"}, + ) + assert response.status_code == 403 + assert list(directory.iterdir()) == [] + + +def test_session_requires_custom_header(local_tools): + app, _ = local_tools + with client_for(app) as client: + assert client.get("/api/tools/local/session").status_code == 403 + + +@pytest.mark.parametrize("peer,host", [ + ("192.0.2.10", "127.0.0.1:8000"), + ("127.0.0.1", "evil.example:8000"), +]) +def test_remote_peer_and_rebinding_host_rejected_even_with_token(local_tools, peer, host): + app, directory = local_tools + with client_for(app) as local: + token = session_token(local) + with client_for(app, peer) as client: + headers = {"Host": host, "X-ChatDev-Local": "1", "X-ChatDev-Tool-Token": token} + assert client.get("/api/tools/local/session", headers=headers).status_code == 403 + response = client.post( + "/api/tools/local", headers=headers, + json={"filename": "probe", "content": "pass"}, + ) + assert response.status_code == 403 + assert list(directory.iterdir()) == [] + + +def test_untrusted_browser_preflight_is_rejected(local_tools): + app, _ = local_tools + with client_for(app) as client: + response = client.options("/api/tools/local/session", headers={ + "Origin": "https://evil.example", + "Access-Control-Request-Method": "GET", + "Access-Control-Request-Headers": "X-ChatDev-Local", + }) + assert response.status_code == 400 + assert "access-control-allow-origin" not in response.headers + + +def test_cors_wildcard_does_not_authorize_token_access(monkeypatch): + monkeypatch.setenv("CORS_ALLOW_ORIGINS", "*,http://localhost:5173") + assert allowed_browser_origins() == ["http://localhost:5173"] diff --git a/tests/test_server_main_reload.py b/tests/test_server_main_reload.py index 92730ba9..b3d789f5 100644 --- a/tests/test_server_main_reload.py +++ b/tests/test_server_main_reload.py @@ -115,6 +115,9 @@ class TestBuildReloadKwargs: class TestParserFlags: + def test_default_host_is_loopback(self, server_main): + assert server_main.build_parser().parse_args([]).host == "127.0.0.1" + def test_reload_dir_is_repeatable(self, server_main): parser = server_main.build_parser() args = parser.parse_args(["--reload", "--reload-dir", "a", "--reload-dir", "b"]) diff --git a/utils/middleware.py b/utils/middleware.py index 90d4293c..b1b8bcf1 100755 --- a/utils/middleware.py +++ b/utils/middleware.py @@ -7,10 +7,10 @@ from fastapi.responses import JSONResponse from fastapi.middleware.cors import CORSMiddleware import time import re -import os from utils.structured_logger import get_server_logger, LogType from utils.exceptions import SecurityError +from server.local_security import allowed_browser_origins async def correlation_id_middleware(request: Request, call_next: Callable): @@ -89,24 +89,9 @@ async def rate_limit_middleware(request: Request, call_next: Callable): def add_cors_middleware(app: FastAPI) -> None: """Configure and attach CORS middleware.""" - # Dev defaults; override via CORS_ALLOW_ORIGINS (comma-separated) - default_origins = [ - "http://localhost:5173", - "http://127.0.0.1:5173", - ] - env_origins = os.getenv("CORS_ALLOW_ORIGINS") - if env_origins: - origins = [o.strip() for o in env_origins.split(",") if o.strip()] - origin_regex = None - else: - origins = default_origins - # Helpful in dev: allow localhost/127.0.0.1 on any port - origin_regex = r"^https?://(localhost|127\.0\.0\.1)(:\d+)?$" - app.add_middleware( CORSMiddleware, - allow_origins=origins, - allow_origin_regex=origin_regex, + allow_origins=allowed_browser_origins(), allow_credentials=True, allow_methods=["*"], allow_headers=["*"],