门禁兼容修复

docs/project/integrations/superagent-openapi.md

@@ -74,6 +74,9 @@ FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<secret>
 
 FIRE_SAFETY_CHAT_ENABLED=true
 FIRE_SAFETY_CHAT_AUTH_TOKEN=<another-secret-at-least-32-printable-ascii-characters>
+# Keep false for new environments. Only set true during a controlled migration
+# when an already-issued legacy Chat credential is shorter than 32 characters.
+FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false
 FIRE_SAFETY_CHAT_ALLOWED_ORIGINS=http://localhost:5173
 ```
 
@@ -105,7 +108,7 @@ go run ./cmd/superagent-probe
 - [`../../workflows/user-chat.md`](../../workflows/user-chat.md)
 - [`../../specs/fire-safety-ymd-chat-api-v1.md`](../../specs/fire-safety-ymd-chat-api-v1.md)
 
-`FIRE_SAFETY_CHAT_AUTH_TOKEN` 是独立的首版联调凭证：原生接口将其作为 Bearer，兼容入口将其作为 `xtoken`。它不是最终用户登录；浏览器会暴露静态 Token，因此公网真实用户入口仍必须接入身份提供方、动态授权、限流和审计。
+`FIRE_SAFETY_CHAT_AUTH_TOKEN` 是独立的首版联调凭证：原生接口将其作为 Bearer，兼容入口将其作为 `xtoken`。默认要求至少 32 个字符；如果旧客户端已经拿到且无法立即更换的凭证较短，只能在受控测试/迁移窗口显式设置 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true`。此时仍要求凭证非空、不超过 4096 字节，并且仅含 ASCII `0x21-0x7e`（无空格、控制字符或 Unicode）；该开关不影响 MCP Token 的至少 32 个字符门禁，三种凭证仍必须不同。轮换后恢复 `false`，新环境不得开启；服务会记录不含 Secret 的安全 warning 提醒清理。它不是最终用户登录；浏览器会暴露静态 Token，因此公网真实用户入口仍必须接入身份提供方、动态授权、限流和审计。
 
 ## 8. 与 MCP 的关系
 

docs/project/operations/docker-test-deployment.md

@@ -112,6 +112,9 @@ FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<superagent-open-api-key>
 
 FIRE_SAFETY_CHAT_ENABLED=true
 FIRE_SAFETY_CHAT_AUTH_TOKEN=<独立的高熵xtoken>
+# 新环境必须保持 false；仅当已交付旧客户端的短凭证无法立即更换时，
+# 才能在受控测试/迁移窗口临时设置 true，轮换后恢复 false。
+FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false
 FIRE_SAFETY_CHAT_SUBJECT_ID=fire-safety-ymd-chat-test-subject
 FIRE_SAFETY_CHAT_COMPAT_APP_ID=<与Nginx路径完全一致的公开app-id>
 # 仅浏览器实际 Origin；CLI/服务端调用可以留空
@@ -131,11 +134,13 @@ FIRE_SAFETY_POSTGIS_EXPECTED_SRID=4326
 注意：
 
 - FIRE_SAFETY_CHAT_AUTH_TOKEN 只用于兼容对话入口的 xtoken；FIRE_SAFETY_MCP_AUTH_TOKEN 只用于 SuperAgent 调用 /mcp；FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY 只用于 Go 服务访问 SuperAgent。三者必须不同。
+- Chat Token 默认至少 32 个可打印 ASCII 字符。如果已交付的旧客户端凭证较短且无法立即更换，只能临时设置 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true`；此时仍要求 Token 非空、不超过 4096 字节，并且每个字符都在 ASCII `0x21-0x7e` 范围内（无空格、控制字符或 Unicode）。该开关只影响 Chat 原生 Bearer 和兼容 `xtoken`，不放宽 MCP Token 至少 32 个可打印 ASCII 字符的要求。新环境不得开启，凭证轮换完成后必须恢复 `false`；开关启用时启动日志会记录不含 Secret 的安全 warning。
 - FIRE_SAFETY_CHAT_COMPAT_APP_ID 是公开路径标识，不是 Secret；它必须与 Nginx 的精确 location = /api/v1/apps/<app-id>/completion 完全一致。
 - 使用 FIRE_SAFETY_MCP_SCOPE_MODE=all 时，FIRE_SAFETY_MCP_ALLOWED_TOWNS 必须保持为空。all 是服务账号级的固定查询表范围，不是最终用户级授权。
 - FIRE_SAFETY_POSTGIS_MIGRATION_DSN 不应配置给运行服务；迁移凭证只供一次性迁移命令使用，完成后应移除。
 - FIRE_SAFETY_HTTP_ADDR 在容器内应为 :8080，安全边界由 Compose 的 127.0.0.1:16587:8080 和宿主机 Nginx 提供；不要在 Compose 场景设为容器内的 127.0.0.1:8080。
 - 不要用没有 --quiet 的 docker compose config 或 docker inspect 把完整环境渲染到终端、CI 日志或工单；检查 .env 权限仍为 600。
+- 修改 `.env` 后必须重新创建容器（例如 `docker compose up -d --force-recreate --no-build`）才能加载新的 Chat 兼容开关；单独 `docker compose restart` 不会重新读取容器环境。旧短凭证仅用于受控测试/迁移，完成轮换后把开关改回 `false` 并再次 recreate。
 
 ## 4. 容器访问现有 PostgreSQL/PostGIS
 
@@ -402,6 +407,7 @@ docker compose down
 - 目标机 Compose 配置校验、build、up、健康检查和无 Secret 的有限日志结果。
 - 目标机 nginx -t 和 reload 成功；443 证书、DNS、安全组及旧 location / 已确认不再生效。
 - Chat 首轮/多轮 SSE、错误凭证、未知 app/path 的实际 HTTPS 响应。
+- 若为已交付旧客户端临时开启 Chat legacy 短凭证兼容，应记录受控迁移窗口，确认启动 warning 不含 Secret，并在凭证轮换后恢复 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false`。
 - SuperAgent -> /mcp 的独立 Bearer、TLS/网络白名单、工具发现和至少一个受控只读工具调用。
 - 数据库未公开 5432，运行账号保持只读，PostGIS readiness warning 和 35 条无效面几何缺口已记录。
 

docs/project/operations/nginx-public-entry.md

@@ -55,7 +55,10 @@ FIRE_SAFETY_SUPERAGENT_BASE_URL=https://<superagent-domain>
 FIRE_SAFETY_SUPERAGENT_OPEN_API_KEY=<superagent-open-api-key>
 
 FIRE_SAFETY_CHAT_ENABLED=true
-FIRE_SAFETY_CHAT_AUTH_TOKEN=<chat-xtoken-at-least-32-printable-ascii-characters>
+FIRE_SAFETY_CHAT_AUTH_TOKEN=<chat-xtoken>
+# Keep false for new environments. Only set true in a controlled migration
+# when an already-issued legacy Chat credential is shorter than 32 characters.
+FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=false
 FIRE_SAFETY_CHAT_COMPAT_APP_ID=<same-safe-app-id-as-nginx-location>
 
 FIRE_SAFETY_MCP_ENABLED=true
@@ -67,9 +70,11 @@ FIRE_SAFETY_POSTGIS_DSN=<readonly-postgresql-dsn>
 当前仍是受控联调静态门禁：
 
 - `FIRE_SAFETY_CHAT_AUTH_TOKEN` 由用户请求的 `xtoken` Header 携带，必须与 SuperAgent Open API Key、MCP Token 使用不同值。
+- 默认要求 Chat Token 至少 32 个可打印 ASCII 字符；若已交付的旧客户端短凭证无法立即更换，只能在 Go 服务环境中显式设置 `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN=true` 做受控测试/迁移。无论开关如何，Token 都必须非空、不超过 4096 字节，并且只含 ASCII `0x21-0x7e`（无空格、控制字符或 Unicode）；轮换完成后恢复 `false`，新环境不得开启。该开关同时适用于原生 Bearer 和兼容 `xtoken`，不放宽 MCP Token 的至少 32 字符门禁。
 - `FIRE_SAFETY_MCP_AUTH_TOKEN` 只用于 SuperAgent -> Go `/mcp`，不应复用 Chat Token。
 - Chat、SuperAgent、MCP 和 PostGIS 的完整配置校验以 `.env.example` 和对应项目文档为准。
 - 浏览器会看到 `xtoken`；它不能代表最终用户身份、角色、租户或数据授权。公网真实用户入口仍需身份提供方、动态授权、限流、Secret 轮换和持久审计。
+- Nginx 不读取、比较或存储 Chat Token，也不需要为 legacy 开关增加配置；请求 Header 原样转发给 Go 校验。开关启用时 Go 仅记录不含 Secret 的安全 warning，便于迁移完成后清理。
 
 测试服务器使用 Docker Compose 的完整目录、启动、更新和回滚步骤见 [`docker-test-deployment.md`](docker-test-deployment.md)。
 

docs/project/security-access-control-boundary.md

@@ -15,7 +15,7 @@
 | 能力 | 状态 | 当前含义 |
 | --- | --- | --- |
 | `GET /health` | 已实现 | 公开的进程存活响应，不访问业务数据 |
-| 用户认证 | 仅首版联调门禁 | `/api/chat` 使用独立静态 Bearer；可选兼容路径用同一信任方向的 `xtoken`；它们不是最终用户身份，身份提供方和正式 Token 格式待确认 |
+| 用户认证 | 仅首版联调门禁 | `/api/chat` 使用独立静态 Bearer；可选兼容路径用同一信任方向的 `xtoken`；默认要求至少 32 个可打印 ASCII 字符；已交付旧短凭证仅可通过默认关闭的显式 legacy 开关在受控测试/迁移窗口暂时兼容；它们不是最终用户身份，身份提供方和正式 Token 格式待确认 |
 | 角色/区域/租户授权 | 部分实现 | MCP 使用显式服务端静态范围：默认镇街白名单，或经授权的数据库全范围；最终用户动态身份/角色/租户仍未实现 |
 | SuperAgent Open API Adapter | 已实现、模拟测试通过 | 默认关闭；Secret 仅由项目环境变量注入；真实环境未联调 |
 | 用户聊天与会话映射 | 已实现、默认关闭 | 原生 `POST /api/chat` 和可选 DashScope 风格 `completion` 路径、严格 SSE 最终回答、单进程内存映射和同会话并发冲突；无持久化、跨实例恢复或最终用户授权 |
@@ -48,6 +48,7 @@
 - 联系人、电话和精确敏感位置按字段级权限控制，不因同一记录的普通字段可见而自动可见。
 - `FIRE_SAFETY_MCP_SCOPE_MODE=all` 是 MCP 固定查询表的数据库全范围授权，只能在该 MCP 凭证确实获准读取这些表全部记录时显式使用；它不会从业务数据自动推导授权。
 - `all` 与镇街白名单不能同时配置，避免操作者误以为白名单仍限制结果；两种模式都不能由模型或工具参数修改。
+- `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` 默认必须为 `false`。只有已交付旧客户端的 Chat 凭证较短且无法立即更换时，才允许在受控测试/迁移窗口显式设为 `true`；无论开关如何，Chat 凭证必须非空、不超过 4096 字节且仅含 ASCII `0x21-0x7e`（不得包含空格、控制字符或 Unicode）。该开关只影响 Chat 原生 Bearer 和兼容入口 `xtoken`，不放宽 MCP Token 至少 32 个可打印 ASCII 字符的要求；Chat、SuperAgent Open API 和 MCP 三种凭证必须不同。轮换完成后必须恢复 `false`，新环境不得开启。启用期间仅记录不含 Secret 的安全 warning，以提示后续清理。
 - 地名搜索只读取已允许的名称、镇街、村庄和几何字段，仍应用相同服务端数据范围；不读取联系人、电话或任意表。
 - 地名匹配输出属于候选。线和面的代表点只用于帮助用户识别记录，未经用户确认不得作为演练点继续查询或形成距离结论。
 
@@ -93,6 +94,7 @@ MCP 第一阶段已按以下只读边界实现：
 - `/api/chat` 不转发消息 delta；只有 Adapter 的严格成功条件全部满足后才发送最终 `message` 和 `done`。公开进度只保留安全的 `run.*` / `tool.*` 事件、工具名和状态。
 - 兼容 `completion` 路径同样不转发消息 delta；它先返回无正文的 `finish_reason="null"`，严格成功后才发送 `finish_reason="stop"` 和最终正文。URL App ID 只是公开路由标识，不是授权依据。
 - 兼容路径的 `xtoken` 复用 Chat 入站凭证而不是 SuperAgent Key。Nginx 不保存、比较或注入任何应用 Secret，只把 Header 交给 Go 校验。
+- `FIRE_SAFETY_CHAT_ALLOW_LEGACY_SHORT_TOKEN` 是 Go 服务侧的配置，不由 Nginx 参与；Nginx 不读取、比较或存储 Chat Token，短凭证兼容规则和 warning 均由 Go 执行。
 - 同一内存会话只允许一个活动 Run。流失败或结果不确定时删除本地映射，避免继续复用可能仍在运行的 Provider Session。
 - 当前会话只在单进程内存中保存且有数量/TTL 上限；不保存消息历史。重启或多实例切换会导致旧对话不可用，不得向用户承诺持久会话。