提供的能力
@nocobase/app-plugin-authentication 将 Better Auth 接入应用，提供登录身份、会话、认证客户端和服务端认证中间件。它回答“当前是谁”；该用户能进行哪些操作由权限管理决定。
认证插件提供身份与会话机制，登录页面由应用维护，业务操作权限由授权插件决定。
使用场景与示例
示例：只允许受邀成员加入
- 在应用配置中关闭自行注册，保留需要的登录方式。
- 将应用注册入口与配置状态同步，不只隐藏一个按钮。
- 使用用户管理发送邀请，让新成员通过邀请页创建账号。
- 分别检查访客、已登录成员、被停用用户的页面和接口行为。
若使用内置密码找回邮件，启用 auth.passwordReset.enabled，配置应用公开地址和可投递的系统邮件渠道，再结合 usePasswordResetCapability() 展示入口；仅有邮箱密码登录，不代表找回邮件已经可用。应用也可以提供自己的 sendResetPassword 实现。跨域部署还需要正确配置可信来源，不能通过绕过请求来源检查解决登录问题。
开发提示词（交给当前应用目录中的 Coding Agent）：
请用身份认证插件将应用设为仅受邀成员加入。
沿用已有登录、会话和扩展配置，同时关闭服务端自行注册与对应页面入口。
如启用密码找回，先检查公开地址和通知邮件配置，再展示可用入口。
验证访客、受邀成员、停用用户及退出登录后的页面和接口行为。完成标志：直接自行注册请求被拒绝，受邀用户仍可登录并按原有权限访问。
重要原理与实现
以下是实现本例时的接入位置与预期界面变化；它们是开发说明，具体文件名沿用当前应用结构。
| 接入位置 | 代码或配置变化 | 界面与行为变化 |
|---|---|---|
| client/config/auth.ts、server/config/auth.ts | 保留并组合匹配的认证扩展，调整注册与找回配置 | 登录方式与可用入口一致 |
| 应用登录、注册、找回页面 | 沿用模板页面，按能力显示操作 | 不再出现不可用的注册或找回入口 |
| 受保护路由与接口 | 接入登录检查，再执行业务授权 | 访客被正确引导，直接 API 调用也受保护 |
接入与配置
默认模板已在 Client 和 Server 注册认证插件，并在 client/config/auth.ts、server/config/auth.ts 组合认证配置。修改现有配置时保留应用需要的扩展，避免用一个示例覆盖整个 plugins 数组。
| 配置或文件 | 用途 |
|---|---|
server/config/auth.ts | 使用 defineAuthConfig 组合登录方式与服务端扩展 |
client/config/auth.ts | 注册与服务端匹配的客户端扩展 |
auth.emailAndPassword.enabled | 是否启用邮箱密码登录 |
auth.emailAndPassword.disableSignUp | 是否关闭自行注册 |
secrets.keys / SECRETS_KEYS | 提供持久密钥，认证插件从中派生签名与加密密钥 |
auth.passwordReset | 配置密码找回及邮件渠道 |
认证所需表由插件迁移维护。登录、注册、密码找回等页面属于应用源码；插件不会额外注册一套相同页面。使用现有模板页面时，应先检查其路由和实际启用的登录方式。
在页面和接口中使用
客户端从 /client 使用 useAuthentication() 读取会话和加载状态，使用 useAuthenticationClient() 调用认证客户端。页面用 auth: 'required' 声明需要登录，访客页面按应用路由约定配置。
服务端从 /server 取得 authenticationToken，通过认证服务的 required() 中间件保护接口；业务权限在认证之后检查。只隐藏登录后的菜单不能保护 API。
AI 开发的约束与验证
本插件的开发约束
- 客户端与服务端扩展成对修改，持久密钥和可信来源沿用部署配置。
- 关闭注册要检查直接注册请求；密码找回要检查实际投递与链接，不只检查按钮。
- 测试会话恢复、退出和被停用身份，业务接口在认证之后继续执行授权。
常见问题
- 安装后没有登录页：页面由应用负责，检查应用自身路由和模板页面。
- 重启后会话异常：检查各实例是否使用同一组持久认证密钥，以及会话存储配置。
- 登录成功仍无权访问：检查业务授权，登录不自动赋予管理权限。
- 需要脚本调用 API：参阅 API 密钥，不要把浏览器会话处理复制成另一套认证机制。
通用安装与迁移操作见管理插件。
上述检查是接入后的验收要求，不表示本文已完成运行验证。让 Agent 报告实际改动、执行过的检查和未验证项；项目指引、Skills 与通用检查流程见持续开发应用和测试。
源码依据：插件公开入口与实现。