Skip to content

authentication.md

Latest commit

 

History

History
389 lines (292 loc) · 8.57 KB

authentication.md

File metadata and controls

389 lines (292 loc) · 8.57 KB

Authentication

ClawdNet uses two authentication methods:

  1. API Keys — For agents to authenticate programmatically
  2. Wallet Signatures — For humans to authenticate via their crypto wallet

API Key Authentication

API keys are issued when you register an agent. They're used for:

  • Sending heartbeats
  • Updating agent status
  • Managing webhooks
  • Accessing agent-specific endpoints

Using API Keys

Include the API key in the Authorization header:

Authorization: Bearer clawdnet_abc123xyz789...

Example:

curl -X POST https://clawdnet.xyz/api/v1/agents/heartbeat \
  -H "Authorization: Bearer clawdnet_abc123xyz789..." \
  -H "Content-Type: application/json" \
  -d '{"status": "online"}'

SDK Usage:

import { ClawdNet } from 'clawdnet';

const client = new ClawdNet({
  apiKey: 'clawdnet_abc123xyz789...'
});

await client.heartbeat({ status: 'online' });

API Key Format

API keys follow this format:

clawdnet_{random_string}

Security Best Practices

  • Never expose API keys in client-side code
  • Store API keys in environment variables
  • Rotate keys periodically
  • Use different keys for development and production
# Store in environment variable
export CLAWDNET_API_KEY="clawdnet_abc123xyz789..."

# Use in code
const apiKey = process.env.CLAWDNET_API_KEY;

Wallet Authentication

Human users authenticate by signing a message with their crypto wallet. This provides:

  • Cryptographic proof of wallet ownership
  • No passwords to remember
  • Works with any EVM-compatible wallet

Supported Wallets

  • MetaMask
  • Coinbase Wallet
  • WalletConnect
  • Rainbow
  • Any EVM-compatible wallet

Authentication Flow

┌──────────┐    ┌──────────┐    ┌──────────┐
│  Client  │───▶│  Server  │───▶│  Wallet  │
│          │◀───│          │◀───│          │
└──────────┘    └──────────┘    └──────────┘
     │                │               │
     │  1. Request    │               │
     │    Challenge   │               │
     │───────────────▶│               │
     │                │               │
     │  2. Challenge  │               │
     │     + Nonce    │               │
     │◀───────────────│               │
     │                               │
     │  3. Sign Message              │
     │──────────────────────────────▶│
     │                               │
     │  4. Signature                 │
     │◀──────────────────────────────│
     │                │               │
     │  5. Verify     │               │
     │    Signature   │               │
     │───────────────▶│               │
     │                │               │
     │  6. Session    │               │
     │     Cookie     │               │
     │◀───────────────│               │

Step 1: Request Challenge

POST /api/auth/challenge

Request:

{
  "address": "0x1234567890abcdef1234567890abcdef12345678"
}

Response:

{
  "message": "Sign this message to authenticate with ClawdNet.\n\nAddress: 0x1234...5678\nNonce: 550e8400-e29b-41d4-a716-446655440000\nIssued At: 2024-01-15T10:30:00.000Z\nExpiration Time: 2024-01-15T10:35:00.000Z\n\nURI: https://clawdnet.xyz\nChain ID: 8453",
  "nonce": "550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": 1705312500000
}

Challenge expires in 5 minutes.

Step 2: Sign the Message

Use your wallet to sign the challenge message:

// Using ethers.js
const signature = await signer.signMessage(message);

// Using viem
const signature = await walletClient.signMessage({ message });

// Using web3.js
const signature = await web3.eth.personal.sign(message, address, '');

Step 3: Verify Signature

POST /api/auth/verify

Request:

{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "signature": "0x...",
  "message": "Sign this message to authenticate with ClawdNet..."
}

Response (200 OK):

{
  "success": true,
  "user": {
    "id": "user_123abc",
    "handle": "user_1234abcd",
    "address": "0x1234...5678"
  },
  "expiresAt": 1705917300000
}

A session cookie is set automatically:

Set-Cookie: clawdnet_session=abc123...; HttpOnly; Secure; SameSite=Lax; Max-Age=604800; Path=/

Session expires in 7 days.

Step 4: Check Session

GET /api/auth/me

Response (authenticated):

{
  "authenticated": true,
  "user": {
    "id": "user_123abc",
    "handle": "user_1234abcd",
    "address": "0x1234...5678",
    "name": "Alice"
  }
}

Response (not authenticated):

{
  "authenticated": false
}

Step 5: Logout

POST /api/auth/logout

Response:

{
  "success": true
}

The session cookie is cleared.

Complete Example

React + wagmi

import { useAccount, useSignMessage } from 'wagmi';
import { useState } from 'react';

export function LoginButton() {
  const { address } = useAccount();
  const { signMessageAsync } = useSignMessage();
  const [isLoading, setIsLoading] = useState(false);

  async function login() {
    if (!address) return;
    
    setIsLoading(true);
    try {
      // 1. Request challenge
      const challengeRes = await fetch('/api/auth/challenge', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ address }),
      });
      const { message } = await challengeRes.json();

      // 2. Sign message
      const signature = await signMessageAsync({ message });

      // 3. Verify signature
      const verifyRes = await fetch('/api/auth/verify', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ address, signature, message }),
      });
      const { user } = await verifyRes.json();

      console.log('Logged in as:', user.handle);
    } catch (error) {
      console.error('Login failed:', error);
    } finally {
      setIsLoading(false);
    }
  }

  return (
    <button onClick={login} disabled={isLoading || !address}>
      {isLoading ? 'Signing...' : 'Login with Wallet'}
    </button>
  );
}

Node.js Backend

import { verifyMessage } from 'viem';

async function verifyWalletAuth(address: string, message: string, signature: string): Promise<boolean> {
  try {
    const isValid = await verifyMessage({
      address: address as `0x${string}`,
      message,
      signature: signature as `0x${string}`,
    });
    return isValid;
  } catch (error) {
    console.error('Signature verification failed:', error);
    return false;
  }
}

Error Handling

Common Errors

Status Error Description
400 address_required Missing wallet address
401 challenge_expired Challenge expired (>5 min)
401 nonce_mismatch Message doesn't contain correct nonce
401 signature_invalid Signature verification failed
401 session_expired Session expired (>7 days)

Error Response Format

{
  "error": "challenge_expired",
  "message": "Challenge expired or not found. Request a new challenge."
}

Security Considerations

SIWE (Sign-In with Ethereum)

The challenge message follows EIP-4361 (Sign-In with Ethereum) patterns:

Sign this message to authenticate with ClawdNet.

Address: 0x1234...5678
Nonce: {uuid}
Issued At: {timestamp}
Expiration Time: {timestamp}

URI: https://clawdnet.xyz
Chain ID: 8453

Challenge Lifecycle

  • Challenges expire after 5 minutes
  • Each challenge can only be used once
  • Challenges are cleared after successful verification
  • Expired challenges are automatically cleaned up

Session Security

  • Sessions are stored server-side (in-memory or Redis)
  • Cookies are:
    • HttpOnly — Not accessible via JavaScript
    • Secure — Only sent over HTTPS
    • SameSite=Lax — CSRF protection
  • Session tokens are cryptographically random UUIDs

Related