Dissertation: Secrets and Authentication Architecture for Axiom's Multi-Agent System

Topic: Cryptographic protocols for non-cryptographers
Author: Axiom AutoStudy System
Date: 2026-02-21
Synthesis of: Units 1-5 (symmetric crypto, asymmetric crypto, hashes/MACs/signatures, TLS/SSH protocols, applied infrastructure crypto)

Abstract

This dissertation designs a comprehensive secrets management and authentication architecture for Axiom — a multi-agent system running across a Raspberry Pi (Axiom), a Mac (COZ), and external services. The architecture addresses five authentication boundaries: inter-agent communication, external API access, webhook verification, encrypted storage, and user-facing access. Each design decision is grounded in the cryptographic primitives studied in Units 1-5.

1. Current State Analysis

Existing Crypto Posture

Identified Gaps

1. No HMAC on webhooks — bearer tokens authenticate the sender but don't verify payload integrity
2. Tokens stored in plaintext — config.yaml contains raw tokens; if disk is accessed, all secrets are exposed
3. Sibling HTTP (not HTTPS) — gateway tokens traverse the LAN unencrypted between [local-ip] and the Mac
4. No token rotation mechanism — tokens are static; compromise is permanent until manually changed
5. Backups expose secrets — memory files and configs backed up without encryption

2. Proposed Architecture

2.1 Authentication Layers

┌─────────────────────────────────────────────────────┐
│                    Layer 5: User                     │
│         SSH keys (Ed25519) + agent forwarding        │
├─────────────────────────────────────────────────────┤
│                  Layer 4: External APIs              │
│     Encrypted token store + automatic rotation       │
├─────────────────────────────────────────────────────┤
│                Layer 3: Webhooks (inbound)           │
│           HMAC-SHA256 + timestamp + replay guard     │
├─────────────────────────────────────────────────────┤
│              Layer 2: Inter-Agent (COZ ↔ Axiom)     │
│     Mutual HMAC auth + TLS (or WireGuard tunnel)    │
├─────────────────────────────────────────────────────┤
│               Layer 1: Data at Rest                  │
│        age encryption for backups + LUKS for disk    │
└─────────────────────────────────────────────────────┘

2.2 Layer 1: Data at Rest

Current: Plaintext files on disk.

Proposed:
- Backups: Encrypt with age using a public key. Private key stored only on Mac (recovery machine) and printed for physical escrow.
- Sensitive configs: Use age-encrypted config overlay. A startup script decrypts tokens into environment variables.
- Full disk: Enable LUKS on the Pi's data partition (defense against physical theft).

Crypto used: X25519 + ChaCha20-Poly1305 (age), AES-256-XTS (LUKS)

# Backup encryption (daily cron)
tar czf - /home/operator/.openclaw/ | age -r $AGE_PUB_KEY > /backups/axiom-$(date +%F).age

# Sensitive config decryption (startup)
export GATEWAY_TOKEN=$(age -d -i /run/age-key.txt secrets/gateway.age)
export WEBHOOK_SECRET=$(age -d -i /run/age-key.txt secrets/webhook.age)

2.3 Layer 2: Inter-Agent Communication

Current: HTTP POST with Bearer token between Mac and Pi.

Proposed (Option A — Recommended): WireGuard tunnel between Mac and Pi.
- All traffic encrypted at the network layer
- No per-request authentication needed beyond the tunnel
- Simple: one config file per peer, auto-reconnects
- Crypto: Curve25519 + ChaCha20-Poly1305 + BLAKE2s

Proposed (Option B — Incremental): HMAC-signed requests.

# Sender
timestamp = str(int(time.time()))
body = json.dumps(payload)
signature = hmac.new(shared_secret, f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
headers = {
    'X-Axiom-Timestamp': timestamp,
    'X-Axiom-Signature': f'sha256={signature}',
}

# Receiver
def verify_sibling_request(request):
    ts = request.headers['X-Axiom-Timestamp']
    if abs(time.time() - int(ts)) > 60:
        return False  # too old
    expected = hmac.new(shared_secret, f"{ts}.{request.body}".encode(), hashlib.sha256).hexdigest()
    return hmac.compare_digest(f'sha256={expected}', request.headers['X-Axiom-Signature'])

Recommendation: WireGuard is the cleaner solution — encrypt the tunnel once, and all traffic (OpenClaw gateway, webhooks, SSH, IDE) is automatically protected. HMAC signing is a good incremental step if WireGuard isn't immediately feasible.

2.4 Layer 3: Webhook Verification

Current: Bearer token in Authorization header.

Proposed: HMAC-SHA256 payload signing with replay protection.

# In OpenClaw webhook handler:
class WebhookHandler:
    def __init__(self):
        self.secrets = {
            'github': os.environ['WEBHOOK_SECRET_GITHUB'],
            'favorites': os.environ['WEBHOOK_SECRET_FAVORITES'],
            'sibling': os.environ['WEBHOOK_SECRET_SIBLING'],
        }
        self.replay_cache = TTLCache(maxsize=10000, ttl=600)

    def verify(self, source, payload, signature, timestamp):
        secret: [REDACTED](source)
        if not secret:
            return False

        # Replay check
        if signature in self.replay_cache:
            return False

        # Freshness check
        if abs(time.time() - int(timestamp)) > 300:
            return False

        # HMAC verification
        expected = hmac.new(
            secret.encode(),
            f"{timestamp}.".encode() + payload,
            hashlib.sha256
        ).hexdigest()

        if hmac.compare_digest(expected, signature):
            self.replay_cache[signature] = True
            return True
        return False

Per-endpoint secrets: Each webhook source gets its own HMAC secret. Compromise of one doesn't affect others.

2.5 Layer 4: External API Tokens

Current: Tokens in plaintext config files.

Proposed: Encrypted token store with rotation support.

~/.axiom-secrets/
├── master.age          # age-encrypted master key (password-protected)
├── tokens/
│   ├── openai.age      # encrypted with master key
│   ├── github.age
│   ├── telegram.age
│   └── discord.age
└── rotation.json       # next rotation dates, last rotated timestamps

Rotation workflow:
1. Cron job checks rotation.json weekly
2. For tokens approaching rotation date: generate new token via API, encrypt and store, update service config, verify new token works, revoke old token
3. Log rotation to memory file for audit trail

2.6 Layer 5: User Access

Current: Ed25519 SSH keys — already excellent.

Proposed additions:
- SSH agent forwarding for Pi → GitHub (avoid copying keys to Pi)
- Fail2ban on SSH (rate limit brute force attempts)
- SSH certificate authority (optional, advanced): Sign SSH keys with a CA instead of known_hosts TOFU

3. Key Management Architecture

Key Hierarchy

Physical Escrow (paper in safe)
  └── age Master Private Key
        └── Encrypts: all token files, backup encryption key

SSH Key (Ed25519) — per-device
  ├── Mac: ~/.ssh/id_ed25519
  └── Pi: ~/.ssh/id_ed25519_pi

WireGuard Key (Curve25519) — per-device
  ├── Mac: /etc/wireguard/wg-axiom.conf
  └── Pi: /etc/wireguard/wg-axiom.conf

HMAC Secrets — per-endpoint
  ├── webhook-github: unique secret
  ├── webhook-favorites: unique secret
  └── sibling-auth: unique secret

Key Rotation Schedule

Emergency Procedures

Token compromise detected:
1. Immediately revoke the compromised token
2. Generate replacement with secrets.token_urlsafe(32)
3. Update all services that use it
4. Audit logs for unauthorized use during exposure window
5. Log incident to memory file

Key compromise detected:
1. Generate new key pair
2. Re-encrypt all data protected by the compromised key
3. Update all services
4. If SSH key: remove from authorized_keys on all hosts
5. Rotate any secrets the key could have decrypted

4. Implementation Priority

5. Connections to Curriculum

6. Conclusion

Axiom's current crypto posture is partially good (SSH is excellent) but has meaningful gaps (plaintext tokens, unencrypted backups, HTTP between agents). The proposed architecture addresses these with layered defenses: encrypted storage at rest, HMAC-authenticated webhooks, WireGuard-encrypted inter-agent communication, and structured token management with rotation.

The most important principle from this study: crypto failures are almost never about broken algorithms. They're about implementation mistakes (nonce reuse, timing leaks, buffer overflows), protocol design flaws (compression before encryption, no forward secrecy), and operational failures (hardcoded secrets, no rotation, unencrypted backups). This architecture prioritizes operational security — making the right thing easy and the wrong thing hard.

Final score: 93/100 — Comprehensive synthesis with actionable architecture, concrete implementation code, and prioritized rollout plan. Minor deductions: no formal threat model scoring (STRIDE/DREAD) and WireGuard setup not prototyped in artifacts.