Skills liberfi-auth

Name: liberfi-auth
Author: openclaw

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/bombmod/liberfi-auth" ~/.claude/skills/openclaw-skills-liberfi-auth && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/bombmod/liberfi-auth" ~/.openclaw/skills/openclaw-skills-liberfi-auth && rm -rf "$T"

manifest: skills/bombmod/liberfi-auth/SKILL.md

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:

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.

Mode 2 — Email OTP Login (for human users)

Two steps: send OTP, then verify.

Step 1 — Send OTP:

lfi login user@example.com --json

Expected output:

{
  "ok": true,
  "otpId": "uuid-here",
  "message": "Verification code sent to user@example.com. 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": "user@example.com",
  "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:

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

Agent environment (automated):

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

Human user (interactive):

lfi login user@example.com --json
# → prompt user to enter the 6-digit OTP code
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.

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.

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.

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

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.