design: #9 MSK-derived TEE key architecture — design doc

[hanwencheng]

Summary

Draft design doc for GitHub issue #9. Ships only the doc — implementation work in the Heima TEE worker is blocked on human + Kai sign-off.

What's in the doc

• Problem framing (current per-user sealed blobs → proposed single-MSK model).
• Invariants (MSK stays in TEE, derived keys zeroized, public keys NOT on chain, addresses identity-derived).
• Why the design works (single-key storage, seamless MSK rotation, safe soft derivation under TEE-only custody, TEE partitioning).
• Locked design decisions (unpair disabled, path recycling disabled, generation suffix for rotation, on-chain suspend for revocation).
• Deliverables split into: TEE worker, chain/pallet, migration, AgentKeys-side (docs + mock).
• Sequencing: Stage 8 first → Heima mods → AgentKeys docs.
• 5 open questions for the reviewer (Heima MSK existence, KDF choice, child-derivation scheme, migration cut-over strategy, external public-key verifiability requirement).

Review ask

Please review and answer the 5 open questions befo we open implementation PRs. Specifically:

• @Kailai-Wang @BillyWooo — confirm Heima MSK status and KDF/derivation-scheme preferences.
• Project lead — confirm sequencing (Stage 8 first) and migration cut-over strategy.

Test plan

Docs-only. No code impact.

Issue

Tracks #9. Design sign-off is a prerequisite for implementation work — a follow-up PR will add the code changes once the design is approved.

🤖 Generated with Claude Code

• Codex reviewer: approved (no actionable findings)

---

Codex review (2026-04-14): ✅ Approved — no actionable findings. See the codex comment above for details.

[hanwencheng]

Codex review (via gstack /codex skill, GPT-5.4 codex-high reasoning against origin/main)

Verdict

The new design note bakes in two migration assumptions that do not match the repository’s current Heima model: MSK rotation is treated as address-stable, and legacy random wallet keys are treated as re-derivable from a new MSK. Those issues should be resolved before this plan is relied on for implementation.

Full review comments:

• [P1] Rework the “zero on-chain impact” rotation assumption — /private/tmp/agentkeys-codex-review/wt-issue-9-design/docs/spec/plans/fix-9-design.md:50-57
  This section only holds if every public-facing/accounting flow is keyed off the identity-derived OmniAccount, but the rest of the spec still uses the TEE-minted EVM wallet address as the canonical public ID and as the signer for audit extrinsics (docs/spec/1-step-analysis.md §3.1a, wiki/serve-and-audit.md §4). Rotating the MSK changes user_pubkey, so those wallet addresses change too; recovery, audit attribution, and any wallet-address-based lookups would drift unless those docs/runtime pieces are changed in lockstep.

• [P1] Replace the impossible legacy-key re-derivation step — /private/tmp/agentkeys-codex-review/wt-issue-9-design/docs/spec/plans/fix-9-design.md:111-112
  The migration checklist assumes existing wallet keys can be recreated from KDF(MSK, H(identity_info)), but the current architecture docs explicitly say Heima’s per-user wallet keys were generated independently and that no MSK exists yet (wiki/blockchain-tee-architecture.md “Correction”, docs/contradictions.md §3.3). For legacy accounts, a fresh MSK-derived key will therefore produce a different pubkey/address, so this item cannot succeed as written; the plan needs an explicit remap/rotation path instead of “re-derive existing user wallet keys.”

— codex review --base main + -c 'model_reasoning_effort="high"'. Design-doc-only PR.