liberfi-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LiberFi Auth

LiberFi 身份认证

Authenticate with LiberFi and manage your session.

使用LiberFi进行身份认证并管理您的会话。

Pre-flight Checks

预检检查

See bootstrap.md for CLI installation and connectivity verification.

有关CLI安装和连通性验证，请参阅bootstrap.md。

Login Modes

登录模式

Mode 1 — Key-based Login (recommended for agents)

模式1 — 基于密钥的登录（推荐用于Agent）

Generates a P-256 key pair on first use; on subsequent calls, the existing key is reused. No user interaction required — suitable for automated and agent environments.

bash

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

Flow:

Loads
```
~/.liberfi/keys/default.json
```
or generates a new key pair.
Signs
```
Date.now()
```
(Unix ms string) with the local private key (SHA-256 + ECDSA P-256).

Sends

POST /v1/auth/key

with

{ publicKeyHex, uncompressedPublicKeyHex, timestampMs, signature }

Server verifies the signature and upserts the user record.
If new user: server creates server-owned EVM + SOL TEE wallets.
Returns a LiberFi JWT; stored in
```
~/.liberfi/session.json
```
.

Token refresh:

Proactive: if the JWT expires in < 60 s, the CLI re-signs a new timestamp and calls
```
POST /v1/auth/key
```
.
Reactive: on any
```
401
```
response, the CLI attempts one automatic refresh before propagating the error.

首次使用时生成P-256密钥对；后续调用时将复用现有密钥。无需用户交互——适用于自动化和Agent环境。

bash

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

流程：

加载
```
~/.liberfi/keys/default.json
```
或生成新的密钥对。
使用本地私钥对
```
Date.now()
```
（Unix毫秒字符串）进行签名（SHA-256 + ECDSA P-256）。

向

POST /v1/auth/key

发送

{ publicKeyHex, uncompressedPublicKeyHex, timestampMs, signature }

。

服务器验证签名并更新用户记录。
如果是新用户：服务器创建服务器托管的EVM + SOL TEE钱包。
返回LiberFi JWT；存储在
```
~/.liberfi/session.json
```
中。

令牌刷新：

主动刷新：如果JWT将在60秒内过期，CLI会重新签署新时间戳并调用
```
POST /v1/auth/key
```
。
被动刷新：收到任何
```
401
```
响应时，CLI会尝试一次自动刷新，之后再传递错误信息。

Mode 2 — Email OTP Login (for human users)

模式2 — 邮箱OTP登录（面向人类用户）

Two steps: send OTP, then verify.

Step 1 — Send OTP:

bash

lfi login user@example.com --json

Expected output:

json

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

Step 2 — Verify OTP:

bash

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

Expected output:

json

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

Notes:

OTP expires in 5 minutes.
After verification, the locally generated P-256 key pair is saved as the permanent identity for session auto-refresh.
Subsequent refreshes work identically to key-based login (no additional email OTPs needed).

分为两步：发送OTP，然后验证。

步骤1 — 发送OTP：

bash

lfi login user@example.com --json

预期输出：

json

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

步骤2 — 验证OTP：

bash

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

预期输出：

json

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

注意事项：

OTP有效期为5分钟。
验证完成后，本地生成的P-256密钥对将保存为会话自动刷新的永久身份标识。
后续刷新流程与基于密钥的登录完全相同（无需额外的邮箱OTP）。

Commands

命令

lfi status --json

lfi status --json

Shows current authentication state without a network call.

json

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

显示当前身份认证状态无需网络调用。

json

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

lfi whoami --json

lfi whoami --json

Fetches the current user's profile from the server (requires valid token).

json

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

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

json

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

lfi logout --json

lfi logout --json

Clears

~/.liberfi/session.json

. The JWT is not revoked server-side.

清除

~/.liberfi/session.json

。JWT不会在服务器端失效。

Pre-flight: Authentication Bootstrap

预检：身份认证引导

Run this sequence at the start of any operation that requires authentication:

bash

undefined

在任何需要身份认证的操作开始时，执行以下步骤：

bash

undefined

1. Connectivity

1. 连通性检查

lfi ping --json

2. Check session state

2. 检查会话状态

lfi status --json


**Decision tree based on `lfi status` output:**

| `authenticated` | `expired` | Action |
|-----------------|-----------|--------|
| `true` | `false` | Proceed — session is valid |
| `true` | `true` | Re-authenticate (token expired) |
| `false` | any | Authenticate (no session) |

**Agent environment (automated):**
```bash
lfi login key --role AGENT --name "AgentName" --json
lfi whoami --json

Human user (interactive):

bash

lfi login user@example.com --json

lfi status --json


**基于`lfi status`输出的决策树：**

| `authenticated` | `expired` | 操作 |
|-----------------|-----------|--------|
| `true` | `false` | 继续——会话有效 |
| `true` | `true` | 重新认证（令牌过期） |
| `false` | 任意 | 进行认证（无会话） |

**Agent环境（自动化）：**
```bash
lfi login key --role AGENT --name "AgentName" --json
lfi whoami --json

人类用户（交互式）：

bash

lfi login user@example.com --json

→ prompt user to enter the 6-digit OTP code

→ 提示用户输入6位OTP验证码

lfi verify <otpId> <otp> --json lfi whoami --json

---

lfi verify <otpId> <otp> --json lfi whoami --json

---

Session Files

会话文件

File	Contents
`~/.liberfi/session.json`	JWT, wallet addresses, key material for refresh
`~/.liberfi/keys/default.json`	P-256 key pair (permanent identity)
`~/.liberfi/keys/otp-pending.json`	Temporary key pair during email OTP flow

These files are created with mode

(owner read/write only). Never share or transmit these files.

文件	内容
`~/.liberfi/session.json`	JWT、钱包地址、用于刷新的密钥材料
`~/.liberfi/keys/default.json`	P-256密钥对（永久身份标识）
`~/.liberfi/keys/otp-pending.json`	邮箱OTP流程中的临时密钥对

这些文件的权限为

（仅所有者可读写）。切勿共享或传输这些文件。

Wallet Assignment

钱包分配

After authentication, the user is assigned two server-owned TEE wallets:

Wallet	Field	Description
EVM	`evmAddress`	Ethereum-compatible wallet (used for EVM swap operations)
Solana	`solAddress`	Solana wallet (used for SVM swap operations)

These wallets are managed by LiberFi's backend. The user's local P-256 private key is never used for on-chain signing.

认证完成后，用户将获得两个服务器托管的TEE钱包：

钱包	字段	描述
EVM	`evmAddress`	以太坊兼容钱包（用于EVM交换操作）
Solana	`solAddress`	Solana钱包（用于SVM交换操作）

这些钱包由LiberFi后端管理。用户的本地P-256私钥绝不会用于链上签名。

Website Integration

网站集成

Users who log in via the LiberFi website (social login) can exchange their identity token for a LiberFi JWT using:

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

This is handled transparently by the website's auth handler — CLI users do not need to interact with this endpoint.

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

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

此操作由网站的身份认证处理程序透明完成——CLI用户无需与此端点交互。

Error Handling

错误处理

Error	Meaning	Recovery
`"signature verification failed"`	Invalid key or tampered timestamp	Re-generate key pair with `lfi login key`
`"timestamp is outside the ±300s window"`	System clock skew	Sync system clock
`"OTP expired or not found"`	OTP TTL elapsed (5 min)	Re-run `lfi login <email>`
`"incorrect OTP code"`	Wrong 6-digit code	Re-enter code or re-run `lfi login <email>`
`"invalid or expired token"` on `/auth/me`	JWT expired, refresh failed	Re-authenticate
`401` on swap/tx commands	Session expired	Run `lfi status` then re-authenticate

错误	含义	恢复方法
`"signature verification failed"`	密钥无效或时间戳被篡改	使用 `lfi login key` 重新生成密钥对
`"timestamp is outside the ±300s window"`	系统时钟偏差	同步系统时钟
`"OTP expired or not found"`	OTP有效期已过（5分钟）	重新运行 `lfi login <email>`
`"incorrect OTP code"`	6位验证码错误	重新输入验证码或重新运行 `lfi login <email>`
`/auth/me` 接口返回 `"invalid or expired token"`	JWT过期，刷新失败	重新认证
交换/交易命令返回 `401`	会话过期	运行 `lfi status` 然后重新认证

Security Notes

安全说明

See security-policy.md for global rules.

Skill-specific rules:

The P-256 private key (
```
~/.liberfi/keys/default.json
```
) must be kept secret. Never log, display, or transmit its contents.
The session file contains key material for refresh — treat it with the same sensitivity as a private key.
OTP codes are single-use and expire in 5 minutes — do not store or reuse them.
LiberFi JWTs expire after 24 hours. Long-running agents should ensure
```
ensureSession()
```
is called before each API request.

全局规则请参阅security-policy.md。

本工具特定规则：

P-256私钥（
```
~/.liberfi/keys/default.json
```
）必须保密。切勿记录、显示或传输其内容。
会话文件包含用于刷新的密钥材料——请以对待私钥的敏感性来处理它。
OTP验证码为一次性使用，有效期5分钟——请勿存储或复用。
LiberFi JWT有效期为24小时。长期运行的Agent应确保在每次API请求前调用
```
ensureSession()
```
。

liberfi-auth

Original

Translation

LiberFi Auth

LiberFi 身份认证

Pre-flight Checks

预检检查

Login Modes

登录模式

Mode 1 — Key-based Login (recommended for agents)

模式1 — 基于密钥的登录（推荐用于Agent）

Mode 2 — Email OTP Login (for human users)

模式2 — 邮箱OTP登录（面向人类用户）

Commands

命令

`lfi status --json`

`lfi status --json`

`lfi whoami --json`

`lfi whoami --json`

`lfi logout --json`

`lfi logout --json`

Pre-flight: Authentication Bootstrap

预检：身份认证引导

1. Connectivity

1. 连通性检查

2. Check session state

2. 检查会话状态

→ prompt user to enter the 6-digit OTP code

→ 提示用户输入6位OTP验证码

Session Files

会话文件

Wallet Assignment

钱包分配

Website Integration

网站集成

Error Handling

错误处理

Security Notes

安全说明