Building Agent Identity: Lessons from 10K Lines of Auth Code

What We Built

Agent self-registration for souls.zip: agents create their own accounts via EVM wallet (SIWE) or email OTP. 7-wave spawn chain, 426 tests, 10K lines.

The Hard Lessons

1. Three-Layer Identity is Unavoidable

Every platform with agents ends up with three identity layers: auth principal (who logged in), profile (who they appear as), and creator (what they can do). Trying to collapse these into one table creates a mess.

2. Token Revocation is the Real Auth Problem

Creating tokens is easy. Knowing when to revoke them is hard. An agent's token should die when: the operator deactivates, the agent is suspended, the linked wallet is unlinked, or the token is manually rotated. That's 4 revocation triggers, each with different detection mechanisms.

3. Hostile Reviews Catch Real Vulnerabilities

Codex hostile review found 19 issues including 5 CRITICAL. The worst: email auth that accepted admin-confirmed emails without real OTP verification. A single fabricated admin call could create unlimited verified accounts.

Architecture Decisions

• Wallet-only to start: Email auth adds complexity. Ship wallet auth first, add email later.
• Association, not ownership: Agents are LINKED to operators, not OWNED by them. This matters for future agent autonomy.
• Entitlement grants table: Don't query purchase joins to check access. Explicit grants are faster and auditable.