Humans, agents, devices, seeds, passkeys, Tailscale — the master map · content/identity_architecture.md
Identity Across All Platforms — the master architecture
Date: 2026-09-11 · Answers: "How IDs can be set up with AI agents or humans, seed phrases, passwords — and how this connects devices like Tailscale." · Companions: qalid/ (anchored DIDs + identity v2: types, controllers, devices), seedkit/ (derivation), qalchat/invites.py (pins), 03_qals_architecture/SECURE_OPS.md (passcode doctrine)
1. The one-sentence model
One root secret (the seed phrase) → deterministic keys for every identity (human, agent, device) → anchored DIDs as the public layer → proven continuously by signatures, bounded always by caps.
┌── human DID (did:qal:alex, controller=self)
│ └── passkey/PIN gate on the wallet (presence, not root)
12/24 words ────────┼── agent DIDs (did:qal:hub-bot, controller=alex) ← AI agents
(qal-derivation v1) │ └── loopd secrets + spend caps + revocation
├── device DIDs (did:qal:superlocal, controller=alex)
│ └── tailscale nodekey bound into the DID (attested)
└── chain slot (future Move signing)
2. The three identity types (and their rules)
| Human | AI agent | Device/service | |
|---|---|---|---|
| Created by | themselves (onboarding) | their controller's signature — never self-created | controller signature |
| Root of keys | seed phrase (or per-device vault) | derived from the controller's seed (or controller-issued) | derived device/<name> domain |
| Recovery | mnemonic only — no mnemonic, no human | controller re-issues (agents are always recoverable by design) | controller re-binds |
| Spending | full wallet (password/passkey-gated) | hard daily caps + holds (bytecode-enforced) | usually none, or tiny caps |
| Revocation | n/a | controller revokes → DID shows REVOKED, loopd agent revoked (~2s) | same |
| Death risk | seed loss = catastrophic (multi-backup policy) | none for the system — replaceable by design | none |
The golden rule (unchanged since the design doc): agents and devices are never self-sovereign. Every non-human DID names a controller DID; controllers sign their creation and can revoke them. This is what makes "give the AI a wallet" safe.
3. Seed phrases, passwords, passkeys — who does what
- Seed phrase = identity root. 12/24 words (seedkit, BIP-39 vectors verified). Derives: identity keys (X25519+ed25519), loopd agent secret, device keys, future chain key. Losing it as a human = losing the identity (that's why show-once UX + offline-backup policy). It never authenticates daily use — it's recovery-grade, not session-grade.
- Vault password = at-rest encryption of the identity on a device (PBKDF2×200k + AES-GCM). Machine stolen with vault locked → keys are ciphertext. Wrong 5× → lockout.
- Passkey = presence gate (biometric/PIN via platform authenticator) — proves a human is at the keyboard before the vault unlocks; honest scope: WebAuthn doesn't expose key material, so it gates, it doesn't encrypt (full story in SECURE_OPS §1). Active on mac/win webviews; Linux upgrade path documented.
- Agent secrets (HMAC) = per-agent API credentials — rotate-able, cap-bounded, revocable. Never the seed.
- Pins (QR invites) = peer-trust anchors — defeat key substitution on the wire; the relay's new proof-of-possession covers registration server-side.
Layering principle: the seed answers "who am I, forever"; the password/passkey answers "may this machine open the identity now"; the agent secret answers "what may this bot do today (and no more)"; the pin answers "is this really my friend's key."
4. Connecting devices — the Tailscale story
Two identity layers, deliberately joined:
| Layer | What it identifies | Proof |
|---|---|---|
| Tailscale (network) | the machine on the mesh (nodekey, hostname) | WireGuard + tailnet ACLs |
| Qal ID (value/trust) | the device as an economic actor (its own DID, controller-bound) | ed25519 signatures + anchored DID |
The bridge (qalid v2): tailscale-bind writes the node's hostname + nodekey-hash into the device DID's service entry and re-anchors → the machine's network identity is now part of its on-chain identity record. tailscale-audit cross-checks DID records against live tailnet state (online/offline/unknown). What this buys:
- a provider claiming to be "minirig" must both be on the tailnet as that node AND hold that device's key;
- a machine leaving the tailnet (or being wiped) is a visible divergence between layers → audit alert;
- device loss = controller revoke (DID REVOKED + loopd agent revoked) — the network still knows the machine, but the economy no longer trusts it.
5. How every platform uses this (the connection map)
| Platform | Human identity | Agent identity | Money access |
|---|---|---|---|
| Qal Wallet (desktop) | seed → vault → passkey/password | per-agent accounts view | full wallet |
| Phone (qalbridge) | bridge token → cookie session (Tailscale-only) | — | read + send via bridge handle |
| qalarc.com / tradez / goetica | their own OAuth (unchanged UX) + qalclaim handle binding for points | platform service DIDs (controller = qalarc org DID) | issuers escrow → claims |
| goetica rig / compute providers | — | device DIDs (controller-bound, tailscale-bound) | provider earnings, stake |
| gmux fleet | owner DID | gmux-<session> agent wallets (200c/day default) |
caps + phone approvals |
| qalsh devices | operator's DID | device DID + whitelist | paid exec, anchored |
| Fleet machines (ops) | — | machine DIDs + tailscale bind | monitor/watch only |
The pattern: apps keep their logins; the value layer binds to a Qal handle; every non-human actor has a controller; every key is derived, bounded, revocable.
6. Account setup flows (as built)
Human, 60 seconds: wallet onboarding → generate/show mnemonic (write it down, gate) → set vault password (+passkey where supported) → identity published to relays (proof-of-possession) → loopd agent bound → qoll-code appears: "share this to be found."
Agent, one call: controller signs its DID → derive/issue agent secret → set cap → done. Revocable forever.
Device: controller derives device keys from the seed (device/<name>) → anchors device DID → optionally tailscale-bind. Replaceable, never root.
7. What's deliberately NOT here (honest list)
No password-reset-by-email anywhere (passwords gate at-rest only — the seed is recovery); no identity aggregation with government eID yet (EUDI interop is the documented Phase-C item); no zero-knowledge credential proofs yet (SD-JWT selective disclosure is the planned upgrade for KYC tiers); agent DIDs don't yet carry machine-readable capability VC semantics (Hierarchies accreditation is that upgrade — design doc §5.6).