CONTEXT.md

Rama main · réplica de lectura del repositorio original.

# Easy Auth

Easy Auth 为一个身份域中的账户提供统一身份入口，并最终向受信任应用签发身份。

## Language

**身份域（Identity Domain）**：
共享同一身份信任边界的一组账户与应用；一个 Easy Auth 实例只代表一个身份域。
_避免_：租户、Realm、组织

**账户（Account，界面概念）**：
身份域中可被识别并登录的自然人；账户可拥有一种或多种登录方式，并始终保留至少一种可用登录方式。所有面向使用者的界面和消息均使用“账户”。
_避免_：用户、成员、User

**管理员（Administrator）**：
被授予管理身份域能力的账户；OAuth 客户端的整个生命周期仅由管理员管理。
_避免_：管理员用户、超级用户、Admin User

**普通账户（Standard Account）**：
未被授予管理员身份的账户；管理员只能对普通账户执行封禁、解封和会话处置。
_避免_：普通用户、Standard User

**授权服务器（Authorization Server）**：
Easy Auth 面向受信任应用提供 OAuth 2.1 授权与 OIDC 身份签发时承担的角色；不同于确认关联身份的 GitHub 等外部身份提供方。
_避免_：OAuth Provider、外部身份提供方

**受信任应用（Trusted Application）**：
经管理员审核并登记、可向 Easy Auth 请求账户授权的应用；不按其与 Easy Auth 是否由同一运营方控制进行分类。
_避免_：第一方应用、第三方应用

**OAuth 客户端（OAuth Client）**：
受信任应用在身份域中的 OAuth 注册身份，用于向 Easy Auth 请求账户授权；它由创建它的管理员管理，不代表自然人账户。
_避免_：OAuth 账户、关联身份

**机密客户端（Confidential Client）**：
能够安全保管客户端密钥，并以该密钥向 Easy Auth 证明自身身份的 OAuth 客户端。
_避免_：私有客户端、后端客户端

**公共客户端（Public Client）**：
无法安全保管客户端密钥，必须依靠 PKCE 保护授权码交换的 OAuth 客户端。
_避免_：公开客户端、无密钥客户端

**应用形态（Application Type）**：
OAuth 客户端登记时确定的运行形态（Web 或 Native），用于界定允许的 Redirect URI；它与公共或机密认证能力相互独立，登记后不可变。
_避免_：认证能力、客户端预设、可编辑类型

**禁用客户端（Disabled Client）**：
暂时不能发起新授权、交换或刷新 token、执行客户端认证或使用既有 access token 的 OAuth 客户端；应用授权继续保留，重新启用会恢复尚未过期且未撤销 token 的可用性。
_避免_：已撤销应用授权、已删除客户端

**应用授权（Application Authorization）**：
账户明确允许受信任应用取得一组身份 scope 的长期决定；首次授权与扩大 scope 均需确认，只有账户主动撤销才删除该决定。普通退出、密码重置和封禁均保留该决定，但封禁会撤销已签发的 OAuth token。
_避免_：登录、会话、应用权限、OAuth 登录方式

**账户封禁（Account Ban）**：
管理员基于明确原因阻止普通账户建立会话的安全处置；封禁可设期限或永久有效，并立即终止既有会话以及 OAuth token 的授权能力，但保留应用授权。管理员账户只能由运维处置。
_避免_：删除账户、禁用客户端、撤销应用授权

**管理活动（Management Activity）**：
管理员对自己拥有的 OAuth 客户端执行登记、配置更新、启停、密钥轮换或删除后留下的不可变活动记录；客户端删除后仍保留，且仅该管理员可查看。
_避免_：安全活动、Timeline、Audit history、应用授权记录

**安全活动（Security Activity）**：
管理员对身份域普通账户执行封禁、解封或会话撤销后留下的不可变活动记录；它面向整个身份域，独立于管理员个人的 OAuth 客户端管理活动。
_避免_：管理活动、登录记录、会话

**用户（User，数据库概念）**：
持久化账户身份的数据库记录；一个账户对应一条 User 记录。该术语仅用于数据库、API 类型和实现代码，不作为界面称呼。
_界面展示_：账户（Account）

**登录方式（Sign-in Method）**：
账户证明自身身份并建立会话的方式；本地密码、已关联的外部身份与通行密钥是不同的登录方式，账户可以仅保留通行密钥。
_避免_：凭据、Account

**通行密钥（Passkey）**：
账户持有的、通过设备 PIN 或生物识别等用户验证后可独立建立会话的登录方式；一个账户可拥有多个通行密钥，使用它登录不追加双重验证。
_避免_：双重验证、备用码、可信设备

**双重验证（Two-Factor Authentication，2FA）**：
账户完成本地密码验证后，还必须使用独立的第二因子完成的附加身份验证；所有已设置本地密码的账户均可自行启用或停用。它不代表新增登录方式，也不介入由外部身份提供方自身保护的外部身份登录或通行密钥登录。
_避免_：两步登录、双因素登录、登录方式、GitHub 双重验证

**可信设备（Trusted Device）**：
账户完成双重验证时明确选择在一段期限内信任的浏览器；有效期内，该浏览器使用本地密码登录时可跳过第二因子验证。可信状态独立于 Session，终止 Session 不会撤销可信状态。
_避免_：会话、已登录设备、永久信任

**双重验证恢复（2FA Recovery）**：
账户同时失去验证器应用与可用备用码后，由运维在线下确认账户身份并恢复其本地密码登录能力的安全处置；它不是密码重置、账户自助流程或管理员面板能力。
_避免_：密码重置、邮箱恢复、管理员重置

**验证器应用（Authenticator App）**：
账户持有的、基于共享密钥生成限时一次性密码（TOTP）的应用，是 Easy Auth 支持的第二因子。
_避免_：OTP 邮件、密码管理器、登录方式

**备用码（Backup Code）**：
启用双重验证时签发给账户、在验证器应用不可用时可替代第二因子的一次性恢复凭据；每个备用码成功使用后即失效，重新签发整组备用码会使旧组全部失效。
_避免_：恢复密码、验证码、登录方式

**关联身份（Linked Identity）**：
由外部身份提供方确认、并由已登录账户明确关联到自身的身份；其邮箱必须已验证，但可与登录邮箱不同，相同邮箱本身也不构成关联。一个账户对同一外部身份提供方至多关联一个身份。
_避免_：第三方账户、社交账户、Social Account

**解除关联（Unlink Identity）**：
移除关联身份，使其不能再作为该账户的登录方式；不代表撤销外部身份提供方一侧的授权。
_避免_：删除账户、注销 GitHub

**开放注册（Open Registration）**：
未登录访问者无需邀请或管理员批准，即可在身份域中创建账户。
_避免_：邀请注册、管理员开户

**账户资料（Account Profile）**：
用于呈现账户身份的姓名、登录邮箱与可选头像；账户可维护姓名和头像，登录邮箱保持只读。
_避免_：用户资料、User Profile

**登录邮箱验证（Login Email Verification）**：
确认账户能够接收登录邮箱所投递消息的证明；未完成验证的登录邮箱不能用于建立会话。
_避免_：邮箱激活、账户激活

**密码重置（Password Reset）**：
账户通过重新证明对登录邮箱的控制来建立新的本地密码；完成后，该账户的既有会话全部失效。
_避免_：找回密码、恢复旧密码

**账户面板（Account Panel）**：
当前账户查看并维护账户资料、登录方式与应用授权的登录后区域。
_避免_：用户面板、User Panel

**管理面板（Admin Panel）**：
管理员管理身份域账户及其所拥有 OAuth 客户端的登录后区域；账户管理面向整个身份域，OAuth 客户端仍仅由其创建者管理。它与账户面板共用侧边栏，但位于独立的“Admin”分组。
_避免_：账户面板、管理员账户面板

**管理总览（Admin Dashboard）**：
管理面板的入口，用于概括身份域的运行状态并通往各项管理能力；具体账户操作在独立的账户管理页面中完成。
_避免_：账户列表、管理员账户面板

**应用发起的退出（Application-initiated Sign-out）**：
受信任应用请求结束账户在当前浏览器中的会话；完成后可将账户送回该应用登记的登出后跳回地址，无法确认请求对应当前会话时须由账户确认。它只结束会话，不撤销应用授权。
_避免_：注销账户、撤销应用授权、单点登出

**会话（Session）**：
从成功登录开始，直到账户退出或登录状态失效的一段已认证交互；它与受信任应用持有的 OAuth token 及账户授予的应用授权相互独立。
_避免_：账户、登录记录、OAuth token、应用授权