ahmetenesdur/authenticate-wallet

Wallet Authentication

Manage the authentication session for the fibx CLI. Supports two methods: email OTP (via Privy server wallets) and private key import (local wallet).

Prerequisites

• No active session required — this skill creates one

Rules

1. For email login, NEVER ask the user for a private key.
2. For private key import, warn the user: "Your private key will be encrypted with AES-256-GCM and stored locally. The encryption key is auto-generated per machine. Shall I proceed?"
3. You MUST complete auth login before auth verify. They are sequential steps.
4. After successful auth verify or auth import, ALWAYS run npx fibx@latest status to confirm the session is active.
5. NEVER store or log private keys, OTP codes, or session tokens in conversation history.

Commands

Email OTP Login (2-step)

# Step 1: Send OTP to email
npx fibx@latest auth login <email>

# Step 2: Verify OTP code
npx fibx@latest auth verify <email> <code>

Private Key Import

npx fibx@latest auth import

INTERACTIVE COMMAND: This opens a prompt for the user to paste their private key. The agent CANNOT pass the key as a CLI argument. Instruct the user to enter it in the terminal prompt, or run it via the agent's terminal tool and let the user type the key.

Session Management

# Check current session status
npx fibx@latest status

# End session
npx fibx@latest auth logout

Parameters

| Parameter | Type | Description | Required | | --------- | ------ | ------------------------------------ | ----------------- | | email | string | User's email address | Yes (email OTP) | | code | string | One-time password received via email | Yes (verify step) |

Session Details

• Privy sessions: JWT-based, 7-day expiry. After expiry, the user must re-authenticate via auth login.
• Private key sessions: No expiry. Session persists until auth logout.
• Storage: Sessions are stored in an OS-dependent config directory (e.g. ~/.config/fibx-nodejs/session.json on Linux, ~/Library/Preferences/fibx-nodejs/session.json on macOS).
• Encryption: Private keys are encrypted at rest using AES-256-GCM. The encryption key is auto-generated per machine in the OS config directory (e.g. ~/.config/fibx-nodejs/encryption-key on Linux). Legacy plaintext keys are auto-migrated on first load.
• CI/Docker: Set FIBX_SESSION_SECRET environment variable (64-char hex) to use a custom encryption key instead of the auto-generated one.

Examples

User: "Log me in with [email protected]"

npx fibx@latest auth login [email protected]
# Wait for user to provide the OTP code (e.g. "123456")
npx fibx@latest auth verify [email protected] 123456
npx fibx@latest status

User: "Import my private key"

# Warn user first, then:
npx fibx@latest auth import
npx fibx@latest status

User: "Log me out"

npx fibx@latest auth logout

Error Handling

| Error | Action | | ------------------- | ------------------------------------------------------ | | Invalid code | Ask the user to check their email and retry verify. | | Rate limit | Wait 60 seconds before retrying. | | Session expired | Privy JWT expired (7 days). Restart from auth login. | | Not authenticated | Run the full login flow before other skills. |

Related Skills

• Use status to verify your session is active before any operation.
• Run balance after authentication to see available funds.
• Run portfolio after authentication to see a full cross-chain overview with USD values.