feat: configure network access policies through environment

apps/api/.env.example

@@ -1,11 +1,86 @@
+# 将本文件复制为 apps/api/.env，再填写实际配置。不要提交真实 .env。
+# 下面是当前需要的开放网络配置。API 和网页开发服务共同读取此文件。
+# 修改网络配置后重启 API 和网页服务；已有监听进程不会自动重新读取 .env。
+
+# 运行环境：development 为开发，production 为上线。
+# 未明确设置的网络开关会按环境采用默认值；本示例明确设置的开关优先。
+NODE_ENV=development
+
+# MySQL 连接字符串：替换用户名、密码、主机、端口及数据库名。
+# 密码中的特殊字符需要进行 URL 编码。
 DATABASE_URL="mysql://USER:PASSWORD@HOST:3306/worthpath"
+
+# API 监听地址：0.0.0.0 接收所有本机 IPv4 网卡连接；127.0.0.1 仅本机访问。
+API_HOST=0.0.0.0
+# API 监听端口。
 PORT=3100
-# Local tunnel testing may use WEB_ORIGIN=*. Production requires an exact origin.
-WEB_ORIGIN=http://localhost:5173
-COOKIE_SECURE=false
-# Canonical OAuth protected resource. Production must use HTTPS.
+# API 请求 Host 白名单：* 允许所有主机；收紧时填写主机及端口，逗号分隔，不带协议。
+API_ALLOWED_HOSTS=*
+
+# 网页开发服务监听地址：0.0.0.0 允许局域网访问；127.0.0.1 仅本机。
+WEB_HOST=0.0.0.0
+# 网页开发服务端口；生产静态页面由部署服务器或反向代理决定端口。
+WEB_PORT=5173
+# 网页开发服务允许的主机名：* 允许全部；收紧时填写域名或 IP，逗号分隔，不带协议和端口。
+WEB_ALLOWED_HOSTS=*
+# 网页开发服务将 /api 请求转发到此地址；这是服务器访问的地址，可保留本机地址。
+WEB_API_PROXY=http://127.0.0.1:3100
+# 网页 API 的浏览器来源白名单：填写完整协议、主机和端口，逗号分隔。
+# * 表示所有来源，同时需要 NETWORK_ALLOW_WILDCARD_ORIGINS=true。
+WEB_ORIGIN=*
+
+# MCP 对外服务的固定完整地址，路径必须为 /mcp。
+# 其他电脑访问时，将 localhost 改为其可访问的 IP 或域名；不要填写 *。
+# OAuth 资源校验和复制给助手的配置提示词使用此地址。
 MCP_PUBLIC_URL=http://localhost:3100/mcp
-# Web confirmation page, normally the same origin as WEB_ORIGIN.
+# OAuth 授权和草稿确认网页的固定地址，通常与实际打开的网站地址一致。
+# 其他电脑使用时同样需要可访问的 IP 或域名，不要填写 *。
 MCP_WEB_URL=http://localhost:5173
-# Exact browser Origin allowlist; never use *. Non-browser clients may omit Origin.
-MCP_ALLOWED_ORIGINS=http://localhost:5173
+# MCP 请求 Host 白名单：* 放开所有 IP/域名；精确值包含端口，逗号分隔。
+# 留空时仅允许固定 MCP 地址的 Host，以及开关允许的本机地址。
+MCP_ALLOWED_HOSTS=*
+# MCP 浏览器请求来源白名单：完整协议、主机、端口，逗号分隔。
+# * 放开所有来源；不携带 Origin 的非浏览器 MCP 客户端仍可请求。
+MCP_ALLOWED_ORIGINS=*
+# MCP Host 白名单留空时，是否额外允许 localhost 和 127.0.0.1 的对应端口。
+# 使用显式白名单或 * 时，此开关不扩大该白名单。
+MCP_ALLOW_LOOPBACK_HOSTS=true
+
+# 是否允许固定 MCP 服务地址和网页授权地址使用 HTTP；false 要求 HTTPS。
+# 同时控制 SDK 的 HTTP 授权服务配置，无需额外设置 SDK 内部变量。
+NETWORK_ALLOW_HTTP=true
+# 是否允许 OAuth 客户端登记非本机 HTTP 回调地址。
+# false 时只允许 HTTPS 或本机回环 HTTP 回调；回调地址仍须精确匹配登记内容。
+NETWORK_ALLOW_HTTP_REDIRECTS=true
+# 是否允许 WEB_ORIGIN、MCP_ALLOWED_ORIGINS 中使用 *。
+# false 时需填写精确来源列表，上线时建议关闭。
+NETWORK_ALLOW_WILDCARD_ORIGINS=true
+# 是否要求登录 Cookie 必须开启 Secure；true 时 COOKIE_SECURE=false 会阻止 API 启动。
+NETWORK_REQUIRE_SECURE_COOKIE=false
+# 是否发送 HSTS 响应头，告知浏览器以后仅使用 HTTPS；HTTP 开发环境设 false。
+NETWORK_HSTS=false
+# 是否发送 CSP 的 upgrade-insecure-requests 指令，让浏览器升级 HTTP 子资源请求。
+# HTTP 开发环境设 false；使用 HTTPS 上线时可设 true。
+NETWORK_UPGRADE_INSECURE_REQUESTS=false
+
+# 登录 Cookie 是否只通过 HTTPS 传输；HTTP 环境设 false，HTTPS 上线设 true。
+COOKIE_SECURE=false
+# 登录 Cookie 的跨站发送策略：strict、lax、none，默认 strict。
+# 同站网页通过 /api 代理访问可保持 strict；跨站 none 必须同时 COOKIE_SECURE=true。
+COOKIE_SAME_SITE=strict
+
+# 上线参考：NODE_ENV=production，NETWORK_ALLOW_HTTP=false，
+# NETWORK_ALLOW_HTTP_REDIRECTS=false，NETWORK_ALLOW_WILDCARD_ORIGINS=false，
+# NETWORK_REQUIRE_SECURE_COOKIE=true，COOKIE_SECURE=true，
+# NETWORK_HSTS=true，NETWORK_UPGRADE_INSECURE_REQUESTS=true。
+# 同时将三个 Host 和两个 Origin 白名单改为实际值，MCP 两个固定地址改为 HTTPS。
+# 这些设置控制应用访问策略；公网访问还取决于防火墙、路由或反向代理是否放行端口。
+
+# 是否启用登录及 OAuth 授权端点的请求限流；true 启用，false 关闭。
+NETWORK_RATE_LIMIT_ENABLED=true
+# 同一来源累计请求的时间窗口，单位毫秒；900000 为 15 分钟。
+NETWORK_RATE_LIMIT_WINDOW_MS=900000
+# 每个来源在窗口内可尝试的登录、注册或安全操作次数；上线可按需收紧。
+NETWORK_AUTH_RATE_LIMIT_MAX=30
+# 每个来源在窗口内访问单个 OAuth 授权、令牌、撤销或注册端点的次数。
+MCP_AUTH_RATE_LIMIT_MAX=100