# 安全模型与威胁分析

## 信任边界与安全默认值

- HTTP 默认只监听 `127.0.0.1:8765`。公网部署必须由 Caddy/Nginx 终止 TLS。
- 仅信任显式配置 CIDR 中反向代理发送的转发头；其他来源的 `Forwarded`/`X-Forwarded-*` 一律忽略。
- 首个 owner 只能在物理终端生成的十分钟单次引导码下创建；系统禁止删除最后一个 owner。
- owner 不由 OP 自动获得。offline-mode 玩家保留原版 OP 权限，但未认证身份不能通过策略 `GRANT` 获得超出当前 OP 等级的权限；危险 Web 权限只可来自 Web owner 或物理终端。
- Web 控制台默认关闭，仅 owner 可用；当前会话必须由 TOTP 建立二要素保证，并且密码重新验证仍在短时窗内。它只能执行 Minecraft 命令，永不执行 OS Shell 或任意文件操作。TOTP、恢复码及绑定确认按账户统一限制为 10 分钟内最多 3 次失败尝试，超过后服务端返回 HTTP 429；成功验证会清除该账户的失败计数。
- administrator 可创建普通触发器，但含 `server_command` 或 `player_command` 的触发器等价于控制台权限，只允许具备 `CONSOLE_EXECUTE` 的 owner 保存。所有触发器写入都要求 CSRF、TOTP 与近期认证。

## 主要威胁与缓解

| 威胁 | 缓解 |
|---|---|
| 口令撞库/暴力破解 | Argon2id、按账号与来源限流、恒定路径校验、会话撤销 |
| 会话窃取 | Secure/HttpOnly/SameSite Cookie、短闲置超时、CSRF 与 Origin 校验、敏感操作重新认证 |
| 代理头伪造 | 仅信任配置 CIDR；会话管理只显示 `loopback`/`remote`/`unknown` 脱敏来源类别 |
| 命令策略绕过 | Brigadier AST、规范化命名空间/redirect/别名、递归 `execute run`、默认拒绝函数间接执行 |
| 权限提升失败后仍执行 | 提权命令在审计不可用时 fail closed；以受限权限重解析后再执行 |
| 触发器变相取得控制台 | 任意命令动作保存时额外检查 owner-only `CONSOLE_EXECUTE`；执行前审计准入失败即拒绝，普通管理员使用结构化动作 |
| 玩家输入触发正则拒绝服务 | 脚本长度和步骤数有界；正则在保存时编译，并拒绝回溯组、反向引用、环视和过量可变重复 |
| 批量目标漂移 | 预览解析后的 UUID 集合、确认令牌、幂等键、执行前重新校验 |
| 背包并发覆盖 | 槽位 revision + compare-and-swap，前后 diff 审计 |
| SQLite/磁盘拖慢 tick | 世界日志与安全审计使用隔离的有界写队列，配合低水位保护、优先级降载和 gap 告警；世界事件突发不得占满审计通道 |
| 控制库迁移失败导致旧策略失效 | HTTP/写路径停用；只读恢复经 checksum 与规则校验的最后发布策略，且提权因无审计而拒绝 |
| 回滚破坏新修改 | 固定 watermark、乐观状态比对、冲突跳过、强制覆盖必须重新预览且 owner-only |
| SSRF/Webhook 泄密 | 固定目的地、HTTPS、HMAC、超时、无自动重定向、敏感字段脱敏 |

## 密钥与个人数据

生产环境应把配置、数据库和 master key 放在仅服务账号可读目录。应用会在支持 POSIX 权限的平台尝试把新建密钥文件收紧到 `0600`；Windows 和其他非 POSIX 文件系统不会自动修复任意继承 ACL，部署者必须预先将数据目录限制为 Minecraft 服务账号（并按运维需要保留 SYSTEM/Administrators），再核验 `master.key`、指标令牌和数据库 ACL。备份 master key 与 `control.db` 时采用不同介质并加密。审计不得保存口令、令牌、TOTP secret、恢复码、完整 IP、原始危险物品数据或未脱敏命令。恢复码只保存哈希。

## 管理员上线清单

1. 在终端生成引导码，并从本机创建首个 owner。
2. 为 owner 启用 TOTP，下载并离线保存恢复码。
3. 发布安全预设前先验证、模拟影响并审阅 diff。
4. 若启用反向代理，配置 TLS、来源访问控制和精确 trusted CIDR。
5. 配置磁盘低水位、数据库保留期、外部备份及告警 Webhook。
6. 启用控制台前确认 owner 最近重新认证与 TOTP 流程可用。
7. 审核触发器组，尤其是 owner 创建的命令动作和第三方模组发布的 `custom.*` 事件上下文。
8. 在 Windows 上检查数据目录没有从上级目录继承面向普通用户的读取权限，并以服务账号验证密钥文件 ACL。

安全漏洞请按仓库 `SECURITY.md` 私下报告，不要把凭据或利用细节写入公开 issue。