LiberFi Auth

Authenticate with LiberFi and manage your session.

Pre-flight Checks

See bootstrap.md for CLI installation and connectivity verification.

Login Modes

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

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.

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

Flow:

1. Loads ~/.liberfi/keys/default.json or generates a new key pair.
2. Signs Date.now() (Unix ms string) with the local private key (SHA-256 + ECDSA P-256).
3. Sends POST /v1/auth/key with { publicKeyHex, uncompressedPublicKeyHex, timestampMs, signature }.
4. Server verifies the signature and upserts the user record.
5. If new user: server creates server-owned EVM + SOL TEE wallets.
6. 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.

Mode 2 — Email OTP Login (for human users)

Two steps: send OTP, then verify.

Step 1 — Send OTP:

lfi login [email protected] --json

Expected output:

{
  "ok": true,
  "otpId": "uuid-here",
  "message": "Verification code sent to [email protected]. It expires in 5 minutes."
}

Step 2 — Verify OTP:

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

Expected output:

{
  "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).

Commands

lfi status --json

Shows current authentication state without a network call.

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

lfi whoami --json

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

{
  "userId": "...",
  "role": "HUMAN",
  "displayName": "",
  "email": "[email protected]",
  "evmAddress": "0x...",
  "solAddress": "..."
}

lfi logout --json

Clears ~/.liberfi/session.json. The JWT is not revoked server-side.

Pre-flight: Authentication Bootstrap

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

# 1. Connectivity
lfi ping --json

# 2. Check session state
lfi status --json

Decision tree based on lfi status output: