Authentication

ClawFirst implements defense-in-depth security architecture designed specifically for autonomous agent operation. This document covers the non-custodial signing service, approval policy engine, and security best practices.

Security Architecture

ClawFirst separates agent operation from private key access using a three-layer security model:

┌─────────────────────────────────────────────────────────────┐
│                     Agent Layer                              │
│  • Natural language processing                               │
│  • Payment intent extraction                                 │
│  • NO access to private keys                                 │
└────────────────────────┬────────────────────────────────────┘
                         │ MCP Tool Calls
                         │ (No cryptographic material)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   Approval Layer                             │
│  • Policy evaluation                                         │
│  • Multi-tier authorization                                  │
│  • Spending limit enforcement                                │
└────────────────────────┬────────────────────────────────────┘
                         │ Approved Transactions
                         │ (Policy-validated)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   Signing Layer (HSM)                        │
│  • Hardware-isolated private keys                            │
│  • Cryptographic signing operations                          │
│  • Never exposes keys to MCP server                          │
└─────────────────────────────────────────────────────────────┘

Non-Custodial Signing Service

Private keys never enter the ClawFirst MCP server memory space. All signing operations execute in isolated hardware security modules (HSM) or key management services.

HSM Integration

interface SigningService {
  signTransaction(
    transaction: Transaction,
    wallet_id: string,
    delegation_token?: string
  ): Promise<SignedTransaction>;
}

class HSMSigningService implements SigningService {
  async signTransaction(
    transaction: Transaction,
    wallet_id: string,
    delegation_token?: string
  ): Promise<SignedTransaction> {
    // Validate delegation token if present
    if (delegation_token) {
      const valid = await this.validateDelegationToken(delegation_token);
      if (!valid) throw new Error('Invalid or expired delegation token');
    }

    // Request signature from HSM via secure enclave
    const signature = await this.hsmClient.sign({
      key_id: wallet_id,
      message: transaction.serializeMessage(),
      algorithm: 'ed25519'
    });

    // Construct signed transaction without exposing private key
    return new SignedTransaction(transaction, signature);
  }
}

Production Key Management

AWS KMS Integration:

clawfirst serve \
  --network mainnet-beta \
  --signing-service kms://aws \
  --kms-key-id arn:aws:kms:us-east-1:123456789012:key/abc-def-123 \
  --port 3402

Google Cloud KMS Integration:

clawfirst serve \
  --network mainnet-beta \
  --signing-service kms://gcp \
  --kms-key-id projects/my-project/locations/us-east1/keyRings/clawfirst/cryptoKeys/agent-wallet \
  --port 3402

HashiCorp Vault Integration:

clawfirst serve \
  --network mainnet-beta \
  --signing-service vault://production \
  --vault-addr https://vault.company.com:8200 \
  --vault-token $VAULT_TOKEN \
  --port 3402

Approval Policy Engine

The approval policy engine enforces spending controls before transactions reach the signing service.

Multi-Tier Approval Workflow

approval_policy = {
    "tiers": [
        {
            "threshold": "100 USDC",
            "auto_approve": True,
            "description": "Automatic approval for small payments"
        },
        {
            "threshold": "1000 USDC",
            "require_human_approval": True,
            "approvers": ["[email protected]"],
            "timeout": "1 hour",
            "description": "Finance team approval for medium payments"
        },
        {
            "threshold": "10000 USDC",
            "require_multisig": True,
            "approvers": [
                "[email protected]",
                "[email protected]"
            ],
            "required_signatures": 2,
            "timeout": "24 hours",
            "description": "Executive approval for large payments"
        }
    ],
    "daily_limit": "50000 USDC",
    "monthly_limit": "500000 USDC",
    "vendor_whitelist": [
        "[email protected]",
        "[email protected]",
        "[email protected]"
    ]
}

Policy Evaluation

class ApprovalEngine {
  async evaluatePolicy(
    session: PaymentSession,
    policy: ApprovalPolicy
  ): Promise<ApprovalState> {
    // Find applicable tier
    const tier = this.findTier(session.amount, policy.tiers);

    // Check vendor whitelist
    if (policy.vendor_whitelist &&
        !policy.vendor_whitelist.includes(session.recipient)) {
      return {
        approved: false,
        reason: 'recipient_not_whitelisted',
        message: `Recipient ${session.recipient} not on approved vendor list`
      };
    }

    // Verify spending limits
    const dailySpend = await this.getDailySpend(session.agent_id);
    if (policy.daily_limit && dailySpend + session.amount > parseAmount(policy.daily_limit)) {
      return {
        approved: false,
        reason: 'daily_limit_exceeded',
        message: `Daily limit of ${policy.daily_limit} would be exceeded`
      };
    }

    // Auto-approve if within threshold
    if (tier.auto_approve) {
      return {
        approved: true,
        approval_method: 'automatic',
        tier: tier.threshold
      };
    }

    // Request human approval
    if (tier.require_human_approval) {
      const approval_token = await this.requestHumanApproval(
        session,
        tier.approvers
      );
      return {
        approved: false,
        pending_approval: true,
        approval_token,
        approvers: tier.approvers,
        timeout: tier.timeout
      };
    }

    return { approved: true };
  }
}

Circuit Breakers

Automatic suspension of agents exhibiting anomalous behavior:

circuit_breaker = {
    "max_failed_transactions": 3,
    "failure_window": "10 minutes",
    "suspend_duration": "1 hour",
    "alert_email": "[email protected]",
    "alert_slack_webhook": "https://hooks.slack.com/services/...",
    "auto_reactivate": False
}

Circuit Breaker States:

• CLOSED - Normal operation

• OPEN - Agent suspended, all transactions blocked

• HALF_OPEN - Testing recovery, limited transactions allowed

Audit Logging

All payment operations are logged with immutable audit trails:

interface AuditLog {
  timestamp: number;
  agent_id: string;
  session_id: string;
  operation: string;
  parameters: Record<string, any>;
  approval_state: ApprovalState;
  result: 'success' | 'failure';
  tx_signature?: string;
  error?: string;
  ip_address?: string;
  user_agent?: string;
}

Example Log Entry:

{
  "timestamp": 1709834400000,
  "agent_id": "ap_agent",
  "session_id": "sess_x4k9j2n8p5",
  "operation": "x402.authorize_transaction",
  "parameters": {
    "session_id": "sess_x4k9j2n8p5"
  },
  "approval_state": {
    "approved": true,
    "approval_method": "automatic",
    "tier": "100 USDC"
  },
  "result": "success",
  "tx_signature": "5KjN2x9...",
  "network_fee": "0.000005 SOL",
  "block_height": 245832910
}

MCP Server Authentication

Agents authenticate to the ClawFirst MCP server using one of three methods:

1. Mutual TLS (mTLS)

clawfirst serve \
  --network mainnet-beta \
  --wallet ~/.config/solana/agent.json \
  --tls-cert server.crt \
  --tls-key server.key \
  --client-ca client-ca.crt \
  --require-mtls

2. JWT Tokens

import { MCPClient } from '@clawfirst/client';

const client = new MCPClient({
  serverUrl: 'https://mcp.company.com',
  auth: {
    type: 'jwt',
    token: process.env.CLAWFIRST_JWT_TOKEN
  }
});

3. API Keys

curl -X POST https://api.clawfirst.xyz/v1/tools/x402.initialize_payment \
  -H "Authorization: Bearer ${CLAWFIRST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"amount": "0.5 SOL", "recipient": "[email protected]"}'

Security Best Practices

1. Never Expose Keys to Agents

# ❌ WRONG: Private key accessible to agent
provider = X402Provider(
    wallet_path="/tmp/agent-key.json"  # Agent can read this file
)

# ✓ CORRECT: Key in HSM, agent only has delegation token
provider = X402Provider(
    signing_service="hsm://production-cluster",
    delegation_policy={"max_amount": "1000 USDC", "duration": "24h"}
)

2. Implement Approval Policies

# ❌ WRONG: Unrestricted autonomous spending
provider = X402Provider(
    network="mainnet-beta",
    wallet_path="~/.config/solana/agent.json"
)

# ✓ CORRECT: Multi-tier approval workflow
provider = X402Provider(
    network="mainnet-beta",
    wallet_path="~/.config/solana/agent.json",
    approval_policy={
        "auto_approve_threshold": "100 USDC",
        "require_human_approval": True,
        "daily_limit": "5000 USDC"
    }
)

3. Enable Audit Logging

clawfirst serve \
  --network mainnet-beta \
  --wallet ~/.config/solana/agent.json \
  --audit-log-file /var/log/clawfirst/audit.jsonl \
  --audit-log-level verbose

4. Monitor for Anomalies

Set up alerting for suspicious patterns:

monitoring = {
    "alert_on_failed_transaction": True,
    "alert_on_large_transaction": "10000 USDC",
    "alert_on_velocity_spike": 20,  # transactions per hour
    "alert_channels": [
        "email:[email protected]",
        "slack:https://hooks.slack.com/...",
        "pagerduty:integration-key"
    ]
}

5. Network Segmentation

┌─────────────────────────────────────────┐
│         Public Internet                 │
└────────────────┬────────────────────────┘
                 │
┌────────────────▼────────────────────────┐
│      Agent Layer (DMZ)                  │
│  • MCP client only                      │
│  • No direct blockchain access          │
└────────────────┬────────────────────────┘
                 │ Internal Network Only
┌────────────────▼────────────────────────┐
│      ClawFirst MCP Server               │
│  • Internal only, not internet-facing   │
└────────────────┬────────────────────────┘
                 │ Isolated Network Segment
┌────────────────▼────────────────────────┐
│      Signing Service (HSM)              │
│  • Air-gapped or separate network       │
│  • Hardware security module             │
└─────────────────────────────────────────┘

Incident Response

Manual Override

Immediately suspend all agent transactions:

clawfirst emergency-suspend \
  --agent-id ap_agent \
  --reason "Suspected compromise" \
  --alert-team

Recovery Procedures

1. Identify Incident - Review audit logs and transaction history

2. Suspend Agent - Emergency suspend command

3. Investigate - Analyze anomalous behavior patterns

4. Rotate Credentials - Generate new delegation tokens

5. Resume Operations - Gradually reactivate with increased monitoring

Next Steps

• Rate Limits - Transaction throughput and quota management

• Error Handling - Fault tolerance and recovery patterns

• MCP Tools - Complete API reference