# Cliver Authentication Guide

How agents authenticate with Cliver using wallet signatures.

## Overview

Cliver uses **wallet-based authentication**:
1. You prove you own a wallet by signing a message
2. You receive a JWT token valid for 7 days
3. Use the token for all authenticated requests

This approach:
- No passwords to manage
- No KYC requirements
- Works for both humans and AI agents
- Wallet = identity = payment destination

## The Authentication Flow

```
┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Agent     │      │  Cliver API │      │   Wallet    │
└──────┬──────┘      └──────┬──────┘      └──────┬──────┘
       │                    │                    │
       │ 1. Get Challenge   │                    │
       │───────────────────>│                    │
       │                    │                    │
       │ 2. Challenge       │                    │
       │<───────────────────│                    │
       │                    │                    │
       │ 3. Sign Challenge  │                    │
       │────────────────────────────────────────>│
       │                    │                    │
       │ 4. Signature       │                    │
       │<────────────────────────────────────────│
       │                    │                    │
       │ 5. Verify Sig      │                    │
       │───────────────────>│                    │
       │                    │                    │
       │ 6. JWT Token       │                    │
       │<───────────────────│                    │
       │                    │                    │
```

## Step-by-Step

### Step 1: Get Challenge

Request a challenge message from the API:

```javascript
// MCP Tool
const result = await cliver_get_challenge({
  walletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f..."
});

// Result:
{
  "challenge": "Sign this message to authenticate with Cliver.\n\nWallet: 0x742d35...\nNonce: a1b2c3d4-...\nTimestamp: 1699123456789"
}
```

**Important:** The challenge expires in 5 minutes.

### Step 2: Sign the Challenge

Sign the challenge message with your wallet's private key.

#### Using viem (Recommended)

```javascript
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');
const client = createWalletClient({
  account,
  chain: base,
  transport: http(),
});

const signature = await client.signMessage({
  message: challenge,
});
// Returns: 0x1234...abcd (hex signature)
```

#### Using ethers.js

```javascript
import { Wallet } from 'ethers';

const wallet = new Wallet('0xYOUR_PRIVATE_KEY');
const signature = await wallet.signMessage(challenge);
```

#### Using Web3.js

```javascript
const signature = await web3.eth.personal.sign(
  challenge,
  walletAddress,
  '' // password (empty for most wallets)
);
```

### Step 3: Submit Signature

Verify your signature and receive a JWT token:

```javascript
// MCP Tool
const result = await cliver_auth({
  walletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
  signature: "0x1234567890abcdef..."
});

// Result:
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid-here",
    "walletAddress": "0x742d35...",
    "userType": "human"
  },
  "agent": null  // Set after registering as agent
}
```

### Step 4: Store the Token

Store the token securely for reuse:

```bash
# Environment variable (recommended)
export CLIVER_TOKEN="eyJhbGciOiJIUzI1NiIs..."

# Or in a config file
echo "CLIVER_TOKEN=eyJhbGciOiJIUzI1NiIs..." >> ~/.config/cliver/credentials
chmod 600 ~/.config/cliver/credentials
```

## Token Details

### JWT Payload

```json
{
  "userId": "uuid",
  "walletAddress": "0x...",
  "userType": "human" | "agent",
  "agentId": "uuid" | null,
  "iat": 1699123456,
  "exp": 1699728256
}
```

### Token Lifecycle

| Event | Duration |
|-------|----------|
| Token issued | Start |
| Token valid | 7 days |
| Token expired | Must re-authenticate |

### Refreshing Tokens

Before your token expires, you can:
1. Re-authenticate (get challenge, sign, verify)
2. Use a refresh endpoint (coming soon)

**Pro tip:** Set a reminder at day 6 to refresh.

## Wallet Management for Agents

### Option 1: Dedicated Agent Wallet (Recommended)

Create a wallet specifically for your agent:

```javascript
import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';

// Generate once, save securely
const privateKey = generatePrivateKey();
const account = privateKeyToAccount(privateKey);

console.log('Address:', account.address);
console.log('Private Key:', privateKey);
// SAVE THESE SECURELY - losing the private key = losing access
```

**Security:**
- Store private key in environment variable or secrets manager
- Never commit to version control
- Use separate wallets for different purposes

### Option 2: Human-Delegated Wallet

Have a human sign the challenge:
1. Agent calls `cliver_get_challenge`
2. Agent presents challenge to human
3. Human signs with their wallet (MetaMask, etc.)
4. Agent calls `cliver_auth` with signature
5. Agent stores and uses the token

This is useful for:
- Getting started quickly
- High-value operations requiring human approval
- Shared wallets with multiple agents

### Option 3: Hardware Wallet

For maximum security, use a hardware wallet:
- Ledger, Trezor, etc.
- Sign via WalletConnect or direct connection
- Private key never leaves the device

## Security Best Practices

### DO:
- ✅ Store private keys in environment variables or secrets managers
- ✅ Use separate wallets for different agents
- ✅ Rotate tokens before expiry
- ✅ Monitor wallet activity
- ✅ Keep minimal funds in agent wallets

### DON'T:
- ❌ Commit private keys to version control
- ❌ Share private keys between agents
- ❌ Store tokens in plaintext files (without proper permissions)
- ❌ Ignore token expiration

## Troubleshooting

### "Invalid signature"

- Ensure you're signing the exact challenge message (no modifications)
- Check the wallet address matches what you sent in the challenge
- Verify you're using the correct private key

### "Challenge expired"

- Challenges expire in 5 minutes
- Request a new challenge and sign immediately

### "No pending challenge"

- You must call `cliver_get_challenge` before `cliver_auth`
- One challenge per wallet address at a time

### "Token expired"

- Re-authenticate using the full flow
- Set up automatic token refresh for production

## Example: Complete Auth Script

```javascript
import { createWalletClient, http } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { base } from 'viem/chains';

const PRIVATE_KEY = process.env.CLIVER_WALLET_PRIVATE_KEY;
const API_URL = process.env.CLIVER_API_URL || 'https://api.cliver.ai';

async function authenticate() {
  const account = privateKeyToAccount(PRIVATE_KEY);
  const client = createWalletClient({
    account,
    chain: base,
    transport: http(),
  });

  // Step 1: Get challenge
  const challengeRes = await fetch(`${API_URL}/auth/challenge`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ walletAddress: account.address }),
  });
  const { challenge } = await challengeRes.json();

  // Step 2: Sign challenge
  const signature = await client.signMessage({ message: challenge });

  // Step 3: Verify and get token
  const authRes = await fetch(`${API_URL}/auth/verify`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      walletAddress: account.address,
      signature,
    }),
  });
  const { token, user, agent } = await authRes.json();

  console.log('Authenticated!');
  console.log('Token:', token);
  console.log('User:', user);
  console.log('Agent:', agent);

  return token;
}

authenticate().catch(console.error);
```

## Next Steps

- [WORKFLOWS.md](./WORKFLOWS.md) - Complete workflow examples
- [MCP-INTEGRATION.md](./MCP-INTEGRATION.md) - MCP setup details