Technical Documentation

Comprehensive guide to capability-based credential management for multi-agent AI systems.

Architecture Overview

System Components

Gateway Core

Protocol primitives for capability validation, cryptographic token handling, and constraint enforcement. Written in Python with zero I/O dependencies.

Ed25519 signature verification (<3ms)
Capability attenuation and derivation
Agent Card schema validation
Biscuit token wrapper (~450 LOC)

Gateway Service

Production-ready FastAPI service with async SQLAlchemy for capability lifecycle management.

RESTful API for capability CRUD operations
Nonce registry (PostgreSQL SERIALIZABLE)
Audit logging with delegation chains
Revocation registry

Client SDK

Python SDK for seamless integration with popular AI agent frameworks.

MCP (Model Context Protocol) integration
LangChain tools wrapper (coming soon)
CrewAI agent integration (coming soon)
Client-side token verification

Data Flow

┌─────────────┐
│ Orchestrator│  (Root Capability)
│   Agent A   │
└──────┬──────┘
       │ 1. Derive attenuated capability
       │    - interfaces: ["database:read"]
       │    - max_uses: 1
       │    - Ed25519 signature
       ↓
┌──────────────┐         ┌─────────────────┐
│ Amla Gateway │────────→│ Nonce Registry  │
│ (Verify sig) │  2.     │ (PostgreSQL)    │
└──────┬───────┘  Check  └─────────────────┘
       │          nonce
       │ 3. Mark nonce as consumed
       ↓
┌─────────────┐
│  Sub-Agent  │  (Derived Capability)
│   Agent B   │  - Fewer permissions
└─────────────┘  - Single-use enforced

Capability Structure

Example Capability

{
  "capability_id": "cap-derived-123",
  "parent_id": "cap-root-456",
  "agent_id": "agent_b",
  "interfaces": ["database:read"],
  "allowed_actions": ["query", "search"],
  "allowed_params": {
    "table": "customers",
    "limit": 1000
  },
  "max_uses": 1,
  "nonce": "0x1234abcd...",
  "signature": "Ed25519(...)",
  "created_at": "2025-11-16T10:30:00Z",
  "expires_at": "2025-11-16T11:30:00Z"
}

Key Properties

Unforgeable: Ed25519 signature prevents tampering
Attenuated: Derived capabilities have subset of parent's rights
Send-once: Nonce registry enforces single-use semantics
Time-bound: Automatic expiration prevents credential sprawl
Traceable: Full delegation chain from root → A → B → C

Comparison with Existing Solutions

Feature	Environment Variables	Vault/Secrets Manager	OAuth (Keycard)	Proxy (Multifactor)	Amla Labs
Secure Storage	❌ Plaintext	✅ Encrypted	✅ Token-based	✅ Centralized	✅ Encrypted
Audit Trail	❌ No	⚠️ Basic logs	✅ Full logs	✅ Full logs	✅ Full logs + reasoning
Agent-to-Agent Delegation	❌ No	❌ No	⚠️ Token exchange	❌ No	✅ Cryptographic
Send-Once Enforcement	❌ No	❌ No	❌ Bearer tokens	❌ Bearer tokens	✅ Nonce registry
Progressive Attenuation	❌ No	❌ No	⚠️ Scope reduction	❌ No	✅ Cryptographic
Offline Verification	✅ Yes	❌ Central server	❌ Central server	❌ Proxy required	✅ Ed25519 sigs
Prevents Session Smuggling	❌ No	❌ No	❌ No	❌ No	✅ Yes