安全模型与威胁分析

信任边界与安全默认值

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、原始危险物品数据或未脱敏命令。恢复码只保存哈希。

管理员上线清单

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

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