LiberFi 认证

使用 LiberFi 进行身份验证并管理会话。

前置检查

请参阅 [bootstrap.md](../shared/bootstrap.md) 了解 CLI 安装和连接性验证方法。

登录模式

模式 1 — 基于密钥的登录（推荐用于自动化代理）

首次使用时生成一个 P-256 密钥对；后续调用将复用已有密钥。

无需用户交互，适用于自动化和代理环境。

lfi login key --role AGENT --name "MyAgent" --json

流程：

1. 加载 ~/.liberfi/keys/default.json 或生成新的密钥对。
2. 使用本地私钥对 Date.now()（毫秒时间戳字符串）进行签名（SHA-256 + ECDSA P-256）。
3. 向 POST /v1/auth/key 发送 { publicKeyHex, uncompressedPublicKeyHex, timestampMs, signature }。
4. 服务器验证签名，并更新用户记录。
5. 若为新用户：服务器创建由 LiberFi 服务器持有的 EVM 和 SOL TEE 钱包。
6. 返回 LiberFi JWT；存储在 ~/.liberfi/session.json 中。

令牌刷新机制：

• 主动刷新：当 JWT 到期时间小于 60 秒时，CLI 会重新签名时间戳并调用 POST /v1/auth/key。
• 被动刷新：在收到任何 401 响应时，CLI 会尝试自动刷新一次，失败后再向上抛出错误。

模式 2 — 邮箱 OTP 登录（适用于人类用户）

分两步完成：发送验证码，然后验证。

步骤 1 — 发送 OTP：

lfi login user@example.com --json

预期输出：

{
  "ok": true,
  "otpId": "uuid-here",
  "message": "Verification code sent to user@example.com. It expires in 5 minutes."
}

步骤 2 — 验证 OTP：

lfi verify <otpId> <6-digit-code> --json

预期输出：

{
  "ok": true,
  "userId": "...",
  "role": "HUMAN",
  "evmAddress": "0x...",
  "solAddress": "...",
  "isNewUser": true,
  "message": "Email verified. Authenticated as ..."
}

注意事项：

• OTP 有效期为 5 分钟。
• 验证成功后，本地生成的 P-256 密钥对将作为永久身份用于后续会话自动刷新。
• 后续刷新行为与基于密钥的登录一致（无需再次发送邮箱 OTP）。

命令列表

lfi status --json

在不发起网络请求的情况下显示当前认证状态。

{
  "ok": true,
  "authenticated": true,
  "userId": "...",
  "role": "HUMAN",
  "evmAddress": "0x...",
  "solAddress": "...",
  "expiresInSecs": 82340,
  "expired": false
}

lfi whoami --json

从服务器获取当前用户资料（需要有效令牌）。

{
  "userId": "...",
  "role": "HUMAN",
  "displayName": "",
  "email": "user@example.com",
  "evmAddress": "0x...",
  "solAddress": "..."
}

lfi logout --json

清除 ~/.liberfi/session.json 文件中的内容。服务器端不会撤销该 JWT。

前置检查：认证初始化

在任何需要认证的操作开始前，请执行以下序列：

# 1. 网络连通性检测
lfi ping --json

# 2. 检查会话状态
lfi status --json

**根据 lfi status 输出结果的决策树：**

代理环境（自动化场景）：

lfi login key --role AGENT --name "AgentName" --json
lfi whoami --json

人类用户（交互式场景）：

lfi login user@example.com --json
# → 提示用户输入 6 位数字验证码
lfi verify <otpId> <otp> --json
lfi whoami --json

会话文件

这些文件以 0600 权限创建（仅所有者可读写）。

切勿共享或传输这些文件。

钱包分配

认证成功后，系统将为用户分配两个由 LiberFi 后端托管的 TEE 钱包：

这些钱包由 LiberFi 后端管理。

用户的本地 P-256 私钥 不会 用于链上签名。

网站集成

通过 LiberFi 官方网站登录（社交账号登录）的用户，可通过以下接口将身份令牌兑换为 LiberFi JWT：

POST /v1/auth/exchange
{ "identityToken": "<identity-token>" }

该过程由网站的认证处理器自动处理 —— CLI 用户无需直接调用此接口。

错误处理

安全提示

请参阅 [security-policy.md](../shared/security-policy.md) 了解通用安全规则。

本技能特有规则：

• P-256 私钥（~/.liberfi/keys/default.json）必须严格保密。

切勿记录、显示或传输其内容。

• 会话文件包含用于刷新的密钥材料 —— 应视同私钥同等敏感处理。
• OTP 代码为一次性使用，5 分钟后失效 —— 不得存储或重复使用。
• LiberFi JWT 有效期为 24 小时。长时间运行的代理应在每次 API 请求前确保调用 ensureSession()。