DEV Community

Cover image for Argon2id Master Passwords: Securing Your Self-Hosted AI Agent Wallet
Wallet Guy
Wallet Guy

Posted on

Argon2id Master Passwords: Securing Your Self-Hosted AI Agent Wallet

#security #selfhosted #web3 #tutorial

Securing AI agent wallets with Argon2id master passwords isn't just about hashing—it's about building defense-in-depth around autonomous systems that can move real money. When your AI agent has direct access to crypto wallets, password security becomes the foundation of a multi-layer protection system that includes session controls, policy enforcement, and human oversight channels.

Why Master Password Security Matters for AI Agents

Traditional password security focuses on protecting human access to applications. But AI agent wallets face a different threat model: autonomous systems making financial decisions at machine speed, often without direct human supervision. A compromised master password doesn't just expose user data—it potentially gives attackers control over an AI agent that can drain wallets, approve unlimited token spending, or bypass all security policies.

The stakes are higher because AI agents operate continuously. While a human might log in once per day, an AI agent might authenticate thousands of times, creating more attack surface. And unlike humans, AI agents can't recognize social engineering or suspicious requests—they follow their programming.

WAIaaS Security Architecture: Beyond Just Password Hashing

WAIaaS implements a 3-layer security model where Argon2id master passwords serve as the foundation:

Layer 1: Argon2id Master Authentication
The master password uses Argon2id hashing—the winner of the Password Hashing Competition and the algorithm recommended by OWASP. Unlike bcrypt or PBKDF2, Argon2id resists both time-memory trade-off attacks and GPU/ASIC acceleration.

Layer 2: Session-Based Agent Authentication
AI agents receive JWT tokens with configurable TTL, maxRenewals, and absoluteLifetime. This creates a clear separation: humans control wallet creation and policies via master auth, while agents operate within bounded sessions.

Layer 3: Policy Enforcement and Human Approval
Default-deny policies block transactions unless explicitly allowed. Spending limits trigger 4 security tiers: INSTANT (small amounts), NOTIFY (medium amounts), DELAY (large amounts with cancellation window), and APPROVAL (human authorization required).

Here's how the authentication system works in practice:

# Master auth: Create wallet and set policies (human administrator)
curl -X POST http://127.0.0.1:3100/v1/wallets \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secure-password" \
  -d '{"name": "ai-trading-bot", "chain": "solana", "environment": "mainnet"}'

# Create bounded session for AI agent
curl -X POST http://127.0.0.1:3100/v1/sessions \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secure-password" \
  -d '{"walletId": "<wallet-uuid>", "ttl": 3600, "maxRenewals": 24}'
Enter fullscreen mode Exit fullscreen mode

The AI agent receives a session token that cannot create new wallets, modify policies, or access other wallets:

# Agent can only operate within session bounds
curl -X POST http://127.0.0.1:3100/v1/transactions/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wai_sess_eyJhbGciOiJIUzI1NiJ9..." \
  -d '{
    "type": "TRANSFER",
    "to": "recipient-address",
    "amount": "0.1"
  }'
Enter fullscreen mode Exit fullscreen mode

Policy-Based Protection: Default-Deny by Design

Even with a compromised session token, WAIaaS policies limit damage. The system implements default-deny enforcement: transactions are blocked unless explicitly allowed by policy configuration.

Setting up a spending limit policy with Argon2id-protected master auth:

curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secure-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "SPENDING_LIMIT",
    "rules": {
      "instant_max_usd": 10,
      "notify_max_usd": 100,
      "delay_max_usd": 1000,
      "delay_seconds": 900,
      "daily_limit_usd": 5000
    }
  }'
Enter fullscreen mode Exit fullscreen mode

WAIaaS supports 21 policy types across 4 security tiers. Critical policies include:

  • ALLOWED_TOKENS: Whitelist specific tokens (blocks transactions to unlisted tokens)
  • CONTRACT_WHITELIST: Restrict contract interactions to approved addresses
  • APPROVED_SPENDERS: Control which contracts can receive token approvals
  • RATE_LIMIT: Prevent transaction spam attacks
  • TIME_RESTRICTION: Limit agent activity to specific hours

For token transfers, you must explicitly allow each token:

# Without this policy, all token transfers are blocked
curl -X POST http://127.0.0.1:3100/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-Master-Password: my-secure-password" \
  -d '{
    "walletId": "<wallet-uuid>",
    "type": "ALLOWED_TOKENS",
    "rules": {
      "tokens": [
        {"address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbol": "USDC", "chain": "solana"}
      ]
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Secure Deployment with Docker and Auto-Provisioning

WAIaaS supports secure deployment patterns that protect the Argon2id-hashed master password. For development, you can set passwords manually, but production deployments should use auto-provisioning:

# Auto-generate cryptographically secure master password
docker run -d \
  --name waiaas \
  -p 127.0.0.1:3100:3100 \
  -v waiaas-data:/data \
  -e WAIAAS_AUTO_PROVISION=true \
  ghcr.io/minhoyoo-iotrust/waiaas:latest

# Retrieve the generated password (store securely, then delete from container)
docker exec waiaas cat /data/recovery.key
Enter fullscreen mode Exit fullscreen mode

For production environments with secrets management:

# docker-compose.secrets.yml
services:
  daemon:
    secrets:
      - master_password
    environment:
      - WAIAAS_MASTER_PASSWORD_FILE=/run/secrets/master_password

secrets:
  master_password:
    file: ./secrets/master_password.txt
Enter fullscreen mode Exit fullscreen mode

The master password protects wallet private keys, policy configurations, and session management. Even with container access, an attacker cannot decrypt wallet data without the password.

Human-in-the-Loop Approval Channels

For transactions exceeding policy limits, WAIaaS routes approval requests through secure human channels. The system supports 3 signing channels:

  1. WalletConnect: Mobile wallet approval with cryptographic signatures
  2. Telegram Bot: Encrypted approval messages
  3. Push Notifications: Real-time transaction alerts

When an AI agent attempts a large transaction:

# Agent tries to send $5000 (exceeds delay_max_usd from policy above)
curl -X POST http://127.0.0.1:3100/v1/transactions/send \
  -H "Authorization: Bearer wai_sess_<token>" \
  -d '{"type": "TRANSFER", "to": "...", "amount": "5000"}'

# Response: {"id": "tx_123", "status": "PENDING_APPROVAL", "reason": "SPENDING_LIMIT"}
Enter fullscreen mode Exit fullscreen mode

The transaction enters APPROVAL tier, sending a notification to configured channels. Humans can approve using owner authentication:

# Human approves with cryptographic signature (not master password)
curl -X POST http://127.0.0.1:3100/v1/transactions/tx_123/approve \
  -H "X-Owner-Signature: <ed25519-signature>" \
  -H "X-Owner-Message: <signed-message>"
Enter fullscreen mode Exit fullscreen mode

This creates separation of concerns: master passwords protect system configuration, while owner signatures authorize individual transactions.

Session Management and Token Security

WAIaaS issues JWT tokens using HS256 signing. Session tokens include wallet binding, expiration, and renewal limits:

{
  "walletId": "019c47d6-51ef-7f43-a76b-d50e875d95f4",
  "ttl": 3600,
  "maxRenewals": 24,
  "absoluteLifetime": 86400,
  "permissions": ["TRANSACTION", "BALANCE_READ"]
}
Enter fullscreen mode Exit fullscreen mode

AI agents can renew tokens without master password access, but cannot:

  • Create new wallets
  • Modify policies
  • Access other wallets
  • Extend beyond absoluteLifetime

Session revocation happens immediately across all API endpoints.

Quick Start: Secure AI Agent Wallet Setup

  1. Install and Initialize with Auto-Provisioning 
npm install -g @waiaas/cli
waiaas init --auto-provision  # Generates secure master password
waiaas start
Enter fullscreen mode Exit fullscreen mode
  1. Create Wallet and Security Policies 
# Retrieve auto-generated password
waiaas status --show-recovery-key

# Create wallet (uses auto-generated master password)
waiaas wallet create --name ai-agent --chain ethereum --network mainnet

# Set default-deny spending policy
waiaas quickset --mode mainnet  # Creates policies automatically
Enter fullscreen mode Exit fullscreen mode
  1. Deploy with Docker Secrets (Production) 
# Generate secure master password
openssl rand -base64 32 > secrets/master_password.txt
chmod 600 secrets/master_password.txt

# Deploy with secrets
docker compose -f docker-compose.yml -f docker-compose.secrets.yml up -d
Enter fullscreen mode Exit fullscreen mode
  1. Create Bounded Session for AI Agent 
# Session expires in 1 hour, renewable 24 times, absolute limit 24 hours
waiaas session create --ttl 3600 --max-renewals 24
Enter fullscreen mode Exit fullscreen mode
  1. Configure MCP for Claude/AI Frameworks 
waiaas mcp setup --all  # Auto-registers with Claude Desktop
Enter fullscreen mode Exit fullscreen mode

Your AI agent now operates within security boundaries: Argon2id-protected configuration, session-based access, default-deny policies, and human approval for large transactions.

What's Next

Security in AI agent wallets requires ongoing attention as attack vectors evolve. Consider implementing additional monitoring through WAIaaS's transaction pipeline and exploring ERC-8004 onchain reputation systems for agent validation.

WAIaaS is open-source and self-hosted, giving you complete control over your AI agent wallet security. Get started at GitHub or visit waiaas.ai for documentation and deployment guides.

Top comments (0)