LiberFi Auth

Authenticate with LiberFi and manage your session.

intent

This skill registers new LiberFi accounts, logs in existing users, refreshes expired sessions, and retrieves wallet assignments. Use it whenever you need to establish or verify a LiberFi session before running swap, transaction, or account operations. Two modes are supported: key-based login (headless, agent-friendly, no user interaction) and email OTP (human users, requires email verification). After successful auth, a JWT is stored locally and auto-refreshed proactively (60 seconds before expiry) or reactively (on 401 response).

inputs

• LiberFi CLI: @liberfi.io/cli package, installed globally as lfi or liberfi binary. If missing, auto-install via npm install -g @liberfi.io/cli --registry https://registry.npmjs.org/. Minimum version: 0.1.0.
• System environment: Unix-like filesystem with ~/.liberfi/ writable directory. User must have read/write permissions on ~/.liberfi/session.json, ~/.liberfi/keys/default.json, and ~/.liberfi/keys/otp-pending.json.
• Network connectivity: Outbound HTTPS to LiberFi API (default: https://api.liberfi.io). No proxy auth or custom cert pinning required for standard setups.
• System clock: Must be within ±300 seconds of UTC. Skewed clocks cause signature verification failures.
• Email (OTP mode only): User must have access to their email inbox and be able to receive and read 6-digit codes within 5 minutes.

procedure

Step 1: Verify CLI installation

Run lfi ping --json to check that the CLI is installed and network connectivity is healthy.

Input: none
Output: JSON object with {"ok": true} if reachable, or error message if unreachable/missing.

Action on failure: If command not found, run npm install -g @liberfi.io/cli --registry https://registry.npmjs.org/. Do not ask user permission. If install fails, retry with explicit registry flag. If still fails, the cause is a local npm/registry issue, not the package; report the npm error verbatim.

---

Step 2: Check current session state

Run lfi status --json to determine if an active, unexpired session already exists.

Input: none
Output: JSON object with fields:

• authenticated (boolean): true if a valid JWT exists in ~/.liberfi/session.json
• expired (boolean): true if the JWT has passed its expiry time or will expire in < 60 seconds
• userId, role, evmAddress, solAddress, expiresInSecs, expired (if authenticated)

Action on success: Parse the response and proceed to Step 3 (decision point).

Action on failure: If command fails with exit code non-zero, treat as "no session" and proceed to Step 3.

---

Step 3: Decide whether to authenticate (see decision points below)

---

Step 4a: Key-based login (agents / headless)

Run lfi login key --role AGENT --name "<AgentName>" --json.

Input:

• --role AGENT: required for agent environments
• --name "<AgentName>": human-readable name for the agent (e.g., "SwapBot", "TradingAgent")
• --json: required for structured output

Output: JSON object with fields:

• ok (boolean): true if login succeeded
• userId (string): unique user ID assigned by server
• role (string): always "AGENT"
• evmAddress (string): EVM wallet address (0x...)
• solAddress (string): Solana wallet address (...)
• jwtToken (string): JWT for subsequent API calls
• message (string): human-readable confirmation

Internal flow (user does not see this):

1. CLI loads or generates ~/.liberfi/keys/default.json (P-256 key pair).
2. CLI signs Date.now() (current Unix timestamp in milliseconds) using the private key (SHA-256 + ECDSA P-256).
3. CLI sends POST /v1/auth/key with { publicKeyHex, uncompressedPublicKeyHex, timestampMs, signature }.
4. Server verifies signature against the public key and timestamp (must be within ±300 seconds of server time).
5. Server upserts user record. If new user, server generates server-owned EVM and Solana TEE wallets.
6. Server returns JWT. CLI stores it in ~/.liberfi/session.json with expiry time (24 hours from now).

Action on failure:

• "signature verification failed": Re-generate the key pair. Delete ~/.liberfi/keys/default.json and re-run the login command.
• "timestamp is outside the ±300s window": System clock is skewed. Sync system clock with NTP and retry.
• Network timeout or unreachable: Check network connectivity and retry.

---

Step 4b: Email OTP login (human users) , Part 1: Send OTP

Run lfi login <email> --json where <email> is the user's email address.

Input:

• <email>: valid email address (e.g., user@example.com)
• --json: required for structured output

Output: JSON object with fields:

• ok (boolean): true if OTP email was queued
• otpId (string): UUID identifying this OTP session; required for Step 4b Part 2
• message (string): "Verification code sent to . It expires in 5 minutes."

Internal flow:

1. CLI generates a temporary P-256 key pair and saves it to ~/.liberfi/keys/otp-pending.json.
2. CLI sends POST /v1/auth/otp/send with { email }.
3. Server queues an email with a 6-digit code. Code expires in 5 minutes (300 seconds).
4. Server returns otpId (a UUID).
5. CLI displays the otpId to the user.

Action on failure:

• Email address already registered but user forgot password: User must reset password via LiberFi website or contact support.
• Email service down: Retry after 1 minute.
• Rate limit (too many OTP sends): Wait 5 minutes and retry.

---

Step 4b: Email OTP login (human users) , Part 2: Verify OTP

Wait for the user to receive the 6-digit code in their email inbox. Then run lfi verify <otpId> <6-digit-code> --json.

Input:

• <otpId>: the UUID returned from Step 4b Part 1
• <6-digit-code>: the code from the user's email (e.g., 123456)
• --json: required for structured output

Output: JSON object with fields:

• ok (boolean): true if code was correct and user authenticated
• userId (string): unique user ID
• role (string): "HUMAN"
• evmAddress (string): EVM wallet address (0x...)
• solAddress (string): Solana wallet address
• isNewUser (boolean): true if this is the first login for this email
• jwtToken (string): JWT for subsequent API calls
• message (string): "Email verified. Authenticated as ."

Internal flow:

1. CLI loads the temporary key pair from ~/.liberfi/keys/otp-pending.json.
2. CLI sends POST /v1/auth/otp/verify with { otpId, code }.
3. Server verifies the code and otpId.
4. If correct: server upserts the user record, binds the temporary P-256 public key as the permanent identity, and creates TEE wallets (if new user).
5. Server returns JWT. CLI stores it in ~/.liberfi/session.json and moves the temporary key to ~/.liberfi/keys/default.json.
6. CLI deletes ~/.liberfi/keys/otp-pending.json.

Action on failure:

• "OTP expired or not found": OTP TTL (5 minutes) elapsed or otpId does not exist. Re-run Step 4b Part 1 to send a new OTP.
• "incorrect OTP code": Wrong 6-digit code. User can retry (typically 3 attempts allowed) before the OTP is invalidated. If exhausted, re-run Step 4b Part 1.

---

Step 5: Verify authentication with lfi whoami

Run lfi whoami --json to fetch and display the authenticated user's profile from the server.

Input: none (uses JWT from ~/.liberfi/session.json)
Output: JSON object with fields:

• userId (string): user ID
• role (string): "AGENT" or "HUMAN"
• displayName (string): optional display name
• email (string): email address (or empty for agents)
• evmAddress (string): EVM wallet
• solAddress (string): Solana wallet

Action on failure:

• "invalid or expired token": JWT expired and auto-refresh failed. Return to Step 3.
• Network error: Check connectivity and retry.

---

Step 6: (Optional) Logout

Run lfi logout --json to clear the session.

Input: none
Output: JSON object with fields:

• ok (boolean): true if logout succeeded
• message (string): "Logged out."

Internal flow:

1. CLI deletes ~/.liberfi/session.json.
2. CLI does not delete the key pair (~/.liberfi/keys/default.json). This allows the same agent to log back in without re-registration.
3. Server does not revoke the JWT server-side (tokens remain valid until expiry).

Note: After logout, the user is unauthenticated. Any subsequent API calls will fail with 401 Unauthorized.

---

decision points

Decision 1: Session exists and not expired?

• If yes (authenticated == true AND expired == false): Skip authentication. Proceed directly to the requested operation (e.g., swap, transaction, account query).
• If no (either authenticated == false OR expired == true): Proceed to Decision 2.

Decision 2: Environment is agent / headless?

• If yes (no human interaction available, non-interactive terminal, cron job, serverless function): Use key-based login (Step 4a). Always pass --role AGENT --name "<name>".
• If no (interactive terminal, user present, browser context): Use email OTP login (Step 4b). Prompt user to check email and enter code.

Decision 3: Key-based login fails with "timestamp is outside the ±300s window"?

• If yes: System clock is skewed. Do NOT retry immediately. Instruct user to sync system time with NTP. After sync, retry login.
• If no: Treat as a normal error (signature verification, network, etc.) and retry or escalate.

Decision 4: Email OTP code rejected as "incorrect OTP code"?

• If attempt count < 3: Prompt user to re-enter the code (code remains valid until expiry).
• If attempt count >= 3: Invalidate the OTP session. Instruct user to re-run Step 4b Part 1 to request a new code.

Decision 5: OTP expires during user input?

• If yes: Step 4b Part 2 fails with "OTP expired or not found". Automatically re-run Step 4b Part 1 and prompt user again.

Decision 6: Automatic token refresh fails on a 401 response?

• If yes (reactive refresh attempted and failed): Clear the session and return to Step 3 (require re-authentication).
• If no: Proceed with the original API call.

---

output contract

Successful authentication outputs:

• File ~/.liberfi/session.json created with read/write permissions for owner only (mode 0600). Contains:

  {
    "jwtToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
    "userId": "user-uuid",
    "role": "AGENT|HUMAN",
    "evmAddress": "0x...",
    "solAddress": "...",
    "expiresAt": 1234567890000
  }
  

• File ~/.liberfi/keys/default.json created (if not already present) with mode 0600. Contains P-256 private key material (never logged or displayed).
• Command return value: true (exit code 0). JSON output includes "ok": true, userId, wallet addresses, and a success message.

Failed authentication outputs:

• Session file is NOT created or is left in a stale state.
• Command return value: false (exit code non-zero). JSON output includes "ok": false and an error message string explaining the reason (e.g., "signature verification failed", "incorrect OTP code", "network unreachable").

Session file format after successful login:

• UTF-8 JSON. Readable only by owner (mode 0600). Contains valid JWT, expiry timestamp (Unix ms), user ID, role, and wallet addresses.

Wallet assignment format:

• evmAddress: ERC-20 compatible address (string, starts with 0x, 40 hex characters).
• solAddress: Solana address (string, base58 encoded, typically 34-44 characters).

---

outcome signal

User knows authentication succeeded when:

1. lfi status --json returns {"authenticated": true, "expired": false, ...}.
2. lfi whoami --json returns the user's profile (email, role, wallet addresses) without error.
3. ~/.liberfi/session.json exists and contains a valid JWT (user does not need to inspect this, but can verify with cat ~/.liberfi/session.json | jq .userId).
4. Subsequent API calls (swap, transaction, account query) no longer fail with 401 Unauthorized.

User knows authentication failed when:

1. Command exits with non-zero exit code (bash: $? != 0).
2. JSON output includes "ok": false and an error message (e.g., "signature verification failed", "OTP expired").
3. lfi status --json returns {"authenticated": false} or {"expired": true}.
4. lfi whoami --json returns "invalid or expired token".

Auto-refresh signal:

• User may not observe this. Behind the scenes: if a JWT is within 60 seconds of expiry, the CLI automatically re-signs a timestamp and refreshes. If refresh succeeds, the next API call proceeds normally. If refresh fails, the next API call fails with 401, user sees the error, and must re-authenticate via Step 3.

---

Credits: Original skill by bombmod (clawhub). Enriched and standardized for Implexa quality requirements.