StaffAuth
概述
StaffAuth 用于保护管理员账号。当玩家加入并拥有管理员权限（默认为 security.admin）时，他们会被冻结，直到通过认证：他们无法移动、交互、破坏或放置方块、打开物品栏、聊天、战斗，也无法使用 /staffauth 之外的命令。没有密码的管理员会在首次加入时注册一个密码；之后他们用它来登录。
密码永远不会作为命令参数发送，也不会在聊天中输入。它们在 Paper 对话框输入框中，或在可选的数字键盘菜单上输入，并且仅以 BCrypt 哈希的形式存储在 TypeWriter artifact 中。失败的尝试会受到速率限制，冷却时间会逐渐增加，并且可以踢出该玩家。
在加入时，每个人都会被静默地保持约一个 tick，以便加载他们的权限，这样即使权限后端很慢，也不会有管理员未经检查就进入。随后非管理员的玩家会被释放；如果在 10 秒内没有建立权限，该玩家会被踢出并附带说明。
功能
- 加入时冻结 — 未认证的管理员无法移动、交互、建造、丢弃、拾取、消耗、钓鱼、受到或造成伤害、聊天或运行命令。
- 注册和登录 — 首次使用的管理员通过两次输入密码来注册；其他人则登录。
- 哈希存储 — 只保存 BCrypt 哈希，成本因子可配置。
- 尝试次数限制 — 每次失败后冷却时间翻倍（最长 60 秒），并在失败
maxAttempts次后踢出。 - 会话超时 — 可选地在若干分钟后让已认证的管理员回到登录界面。
- 对话框或键盘 — 默认使用 Paper 对话框输入，另外还可选用由 GUI 布局构建的数字键盘菜单。
- 管理工具 — 重置已存储的密码，或强制登出。
- 可选的 Permissions 扩展 — 在判断谁是管理员之前，等待权限加载完成。
安装
- 安装 GUI 扩展：登录对话框和键盘菜单是通过它打开的。没有它，
/staffauth会回复界面不可用。 - 如果你的服务器从数据库加载权限，可选择安装 BTC Permissions 扩展；StaffAuth 会自动检测它。
- 将 StaffAuth 的 JAR 放入
plugins/Typewriter/extensions/，然后重启服务器。 - 将管理员权限（
security.admin）授予必须进行认证的账号。
快速上手
- 在 TypeWriter 网页面板中，打开一个 static 页面，添加一个 Staff Auth Passwords artifact。此后永远不要更改它的
artifactId，否则已存储的密码会丢失。 - 在同一个页面上添加一个 Staff Auth Config 条目。检查
staffPermission、adminPermission、maxAttempts、minPasswordLength、bcryptCost和各项消息。 - 发布。StaffAuth 需要这两个条目：没有配置它什么都不会做，没有 artifact 则会放行管理员（并记录一个错误）。
- 使用一个拥有管理员权限的测试账号加入。你会被冻结并被要求注册：在对话框中输入密码，然后确认。
- 重新连接：对话框现在会询问密码。
- 可选：添加一个 Staff Auth Menu 动作来使用键盘。见下文。
StaffAuth 会使用它找到的第一个 Staff Auth Config 和第一个 Staff Auth Passwords artifact。请不要创建多个。
工作原理
认证会持续到玩家离开服务器（状态只保存在内存中）或可选的会话超时到期。在受限期间，唯一允许使用的命令是 /staffauth（以及 /sa，它只是被排除在拦截之外；并没有被注册为别名）。
菜单
加入、/staffauth、login 和 register 会打开一个带有文本输入框的 Paper 对话框。注册时，对话框会再显示一次，用于确认密码。提示文本来自 guiLoginPrompt，标题来自 guiTitle。
Staff Auth Menu 动作则会打开一个物品栏键盘（仅限数字）。如果你更喜欢这种外观，可以从动作链中触发它。在它的 layoutPool 中，为物品指定按钮类型，把它们变成按键：
| 按钮类型 | 功能 |
|---|---|
DIGIT_0 到 DIGIT_9 | 向密码中添加一个数字。 |
PASSWORD_DISPLAY | 为每个已输入的数字显示一个圆点。 |
LOGIN / REGISTER | 提交密码；当玩家还没有密码时，标签为 Register。 |
BACKSPACE | 删除最后一个数字。 |
CANCEL | 清除输入并关闭菜单。 |
键盘只能输入数字，并且密码仍必须满足 minPasswordLength。useGuiWhenAvailable 控制是否在加入时自动打开对话框。
配置
一切都在条目中设置。在消息字段中，使用 {attempts}、{max} 和 {length} 作为占位符（花括号，而不是 MiniMessage 标签）：wrongPasswordMessage 中使用 {attempts} 和 {max}，maxAttemptsKickMessage 中使用 {attempts}，passwordTooShortMessage 中使用 {length}（最小值）和 {max}。
密码保存在由 artifactId 选定的 artifact 文件中，格式为从玩家 UUID 到 BCrypt 哈希的 JSON 映射。该 artifact 会被缓存 5 秒。
命令
命令名称来自配置的 commandName 字段（默认为 staffauth）。基础命令没有注册权限：任何人都可以运行它，但它只对管理员生效。管理员子命令需要 adminPermission 中设置的权限。
| 命令 | 说明 |
|---|---|
/staffauth | 打开登录或注册对话框。 |
/staffauth open, login, register | 与上面相同。 |
/staffauth logout | 结束你的认证，并再次显示对话框。 |
/staffauth status | 显示你的状态、你是否拥有管理员权限，以及 GUI 是否可用。 |
/staffauth reset <player> | 删除某位玩家（名称或 UUID）已存储的密码，该玩家必须重新注册。需要 adminPermission。 |
/staffauth force-logout <player> | 让一位在线玩家登出，并向其显示对话框。需要 adminPermission。 |
权限
这些权限是可配置的字段，而不是固定的节点。
| 权限 | 授予 |
|---|---|
security.admin（staffPermission） | 将玩家标记为管理员：他们必须进行认证。 |
security.staffauth.admin（adminPermission） | /staffauth reset 和 /staffauth force-logout。 |
条目
3 个条目，由扩展源码生成。
动作1
- Staff Auth MenuStaff Auth Menu
命令1
- Staff Auth ConfigStaff Auth Config
构件1
- Staff Auth DataStaff Auth Passwords
故障排查
管理员直接进入，没有被要求输入密码。 请检查配置和 artifact 是否都已发布。没有 artifact 时，StaffAuth 会放行管理员并记录 StaffAuth has no artifact entry。同时检查该玩家是否确实拥有 staffPermission（/staffauth status 会输出它）。
玩家被踢出，并附带关于权限的消息。 Permissions 扩展没有在 10 秒内发出该玩家的权限已加载的信号。请重新连接；如果问题依然存在，请在日志中检查 Permissions 后端。
The StaffAuth interface is unavailable. 没有加载 GUI 扩展。请安装它并重启。
密码消失了。 artifact 的 artifactId 被更改了，或者该条目被重新创建了。请恢复之前的 id。存储的值如果不是有效的 UUID 或 BCrypt 字符串，会导致加载失败，并被记录为 StaffAuth artifact could not be loaded；该玩家会保持冻结，并被告知其状态无法读取。
注册被拒绝。 密码长度必须在 minPasswordLength（6）和 maxPasswordLength（128）个字符之间，并且不能包含空格或控制字符。两次输入必须一致。
玩家在多次登录失败后被踢出。 在失败 maxAttempts（默认 5）次之后，玩家会被踢出，并附带 maxAttemptsKickMessage。将 maxAttempts 设为 0 可禁用踢出；冷却仍然适用。/staffauth reset <player> 可以清除被遗忘的密码。
相关扩展
- GUI — 打开登录对话框和键盘菜单。