安全¶
生态系统的所有平台都建立在同一条安全基线之上。本页定义这条基线——新增平台 时，请把以下各项视为要求，而不是可选项。
纵深防御¶
按照「任何单一层次都不足以自保」的原则逐层叠加：
| 层次 | 防护 |
|---|---|
| Edge（nginx） | TLS、HSTS、限流、请求体大小限制 |
| 应用（HTTP） | 安全响应头、CORS 白名单、CSRF、超时 |
| 应用（逻辑） | RBAC、权限校验、输入校验 |
| 数据库 | RLS、参数化查询 |
| 审计 | 哈希链式审计日志 |
令牌不会进入客户端 JS¶
BFF（Backend-for-Frontend）模式是前端安全的根基。
浏览器从不直接访问后端——只与同域下的 Next.js 路由通信，再由后者在服务端侧 代理到后端。令牌存放在 httpOnly cookie 中。
结果是：XSS 不再是窃取令牌的途径。 即便攻击者成功执行了 JavaScript， 也拿不到令牌。
在此之上还有双重 CSRF 防护：自定义请求头加 origin 校验。
安全响应头¶
在所有响应中：
| 响应头 | 作用 |
|---|---|
Content-Security-Policy |
封堵 XSS 的执行途径 |
Strict-Transport-Security |
强制 HTTPS（HSTS） |
Cross-Origin-Opener-Policy |
隔离跨窗口攻击 |
Cross-Origin-Embedder-Policy |
管控外部资源 |
Cross-Origin-Resource-Policy |
限制资源被外部使用 |
CORS 一律走白名单——绝不使用 *。
Postgres 行级安全（RLS）¶
机构与用户数据的隔离在数据库层面强制执行，而不是靠应用代码里的 WHERE
条件。
原因：应用代码里只要漏掉一处 WHERE user_id = ?，数据就会泄露。RLS 会把这项
校验施加到每一条查询上，与代码是否写错无关。
启动时的可执行性守卫
应用启动时会校验 RLS 是否真的生效。若缺少 policy，或连接所用的用户 拥有绕过 RLS 的权限，应用会拒绝启动。
因为 RLS 悄无声息地失效是最危险的情形——表面上一切都像在正常运行。
SQL¶
- 参数化查询——不做字符串拼接。
- 不使用 ORM——基于
pgx手写 SQL。每一条查询都清晰可见。
限流与超时¶
| 防护 | 位置 |
|---|---|
| 登录认证限流（严格） | /login、/oauth、/auth、/api/auth 等路径 |
| 应用整体限流（宽松） | 其余路径 |
| API 限流 | /v1/* 之类的公开 API |
| HTTP 服务端超时 | read · write · idle · header——均已配置 |
| 请求体大小限制 | 在 edge 层 |
严格限流只用于认证路径
若把严格的认证限流施加到所有路径，Next.js 的 RSC prefetch 就会突破
限额并返回 503。因此严格限额只加在认证路径上，其余路径使用宽松限额。
机密管理¶
- 令牌加密——第三方 OAuth 令牌（Google Drive、Dropbox 等）以 AES-256-GCM 加密存储。
- 密码学密钥——存放于 HSM；本地 HSM 与云端 HSM 互为故障转移。
- 应用机密配置——通过环境变量提供，绝不进入 git。
切勿把机密写进仓库
服务器凭据、API key、client secret、HSM PIN——这些绝不写入任何仓库、 脚本或文档。部署脚本只通过环境变量接收机密。
一旦机密意外泄露：(1) 立即轮换；(2) 检查访问日志； (3) 迁移到机密管理系统中。
生产环境中关闭的 endpoint¶
/metrics 与 /swagger 会暴露内部结构与 endpoint 清单。在生产环境中它们
由 bearer token 保护。
审计日志¶
哈希链式、仅追加的日志。每条记录都包含前一条的哈希值。
其含义是：中间的任何一条记录都无法删除或篡改——链条会断裂，完整性校验 随之失败。仅管理员可读；另有单独的操作用于校验完整性。
签名与不可否认性¶
具有法律后果的行为要求 PIN2 签名——仅有登录认证（PIN1）并不足够。 详见认证与授权页面。
签名私钥以 2-of-2 门限 ECDSA 拆分——任何一方都无法单独完成签名。
测试¶
- 单元测试——业务逻辑与权限校验。
- testcontainers 集成测试——对接真实的 PostgreSQL/Redis，真刀真枪地 校验 RLS。
- golden vector 测试——密码学协议层兼容性。
安全检查清单¶
新平台上生产之前：
- [ ] TLS + HSTS 已启用，证书自动续期
- [ ] 安全响应头全部配置（CSP · HSTS · COOP · COEP · CORP）
- [ ] CORS 白名单——不含
* - [ ] 限流：认证从严，其余从宽
- [ ] HTTP 服务端各项超时全部配置
- [ ] RLS 已启用，启动守卫正常工作
- [ ] 所有查询均为参数化
- [ ] 令牌存于 httpOnly cookie，不进入客户端 JS
- [ ] 双重 CSRF 防护
- [ ]
/metrics、/swagger已关闭 - [ ] 审计日志正常写入，完整性可校验
- [ ] 机密配置经环境变量提供，仓库中不存在
- [ ] 集成测试确实在校验 RLS