docs(security+devex): off-chain encrypted vault + dev-env bootstrap

[hanwencheng]

Summary

Two themes from a security + dev-experience pass:

• Security architecture refactor. On-chain encrypted credential storage (pallet-secrets-vault) creates an unbounded harvest-now-decrypt-later window — public + immutable + permanent ciphertext means any future TEE-key compromise leaks all historical credentials. The fix is two architectural moves that compose: off-chain ciphertext (S3) + on-chain hash, plus per-epoch DEK rotation with deletion of old ciphertext. After K epochs, total TEE compromise leaks at most one epoch. Lands as new threat-model spec, new Stage 8 WIP design, and a doc sweep across docs/ + wiki/. Tracks issue #57.
• Dev-environment bootstrap. New scripts/setup-dev-env.sh — idempotent, OS-aware (macOS / apt / dnf / pacman). Installs rustup+stable, Node 20+, jj (with required identity), jq, AWS CLI v2; builds the workspace; runs smoke tests. docs/dev-setup.md §1 gets a Quick-path subsection pointing at it. Companion to issue #58 (Stage 7 broker server) which will further reduce client-side AWS-cred sprawl.

What's in the diff

docs/contradictions.md                     | +39
docs/dev-setup.md                          | +29
docs/spec/credential-backend-interface.md  | rewrite store_credential mapping rows
docs/spec/plans/development-stages.md      | renumber: insert new Stage 8, push old 8/9 → 9/10
docs/spec/ses-email-architecture.md        | cross-ref to threat model
docs/spec/threat-model-key-custody.md      | NEW (canonical security position)
docs/stage7-wip.md                         | scope-boundary note
docs/stage8-wip.md                         | NEW (operational design + rotation runbook)
scripts/setup-dev-env.sh                   | NEW
wiki/Home.md                               | link + rules 1+2 wording
wiki/blockchain-tee-architecture.md        | superseded banner + table rewrite
wiki/data-classification.md                | credential-blob row + banner
wiki/key-security.md                       | v0.1 column + banner

Two commits, one per theme.

Stage 8 design at a glance

Layer	Holds
Chain	pallet-vault-pointers row (user_wallet, service, agent, epoch, blob_id, ciphertext_hash) + per-user EpochDek { wrapped_dek } + audit extrinsics (BlobWritten, EpochRotated, EpochDestroyed)
TEE	Master seed (sealed) → shielding key → wraps per-epoch DEKs. Plaintext DEK held only per-request, never persistent across calls. New TEE-B "rotation enclave" responsibility, separate code surface from auth/decrypt.
S3 (off-chain)	Encrypted blob bytes at s3://agentkeys-vault/<wallet>/<service>/<epoch>/<blob_id>.enc, AES-256-GCM, gated by Stage 7 PrincipalTag isolation
Client	Bearer token (Stage 4); never holds AWS creds, never sees ciphertext directly

Default rotation cadence: weekly + on-revocation. Lazy re-encryption (re-wrap on next read) chosen as v0.1 default; lifecycle TTL drops idle blobs. EpochDestroyed is the audit event that bounds the forward-secrecy window.

Stage renumber

Before	After
Stage 7 (OIDC provider)	Stage 7 (unchanged)
Stage 8 (production hardening — memory hygiene)	Stage 9
Stage 9 (Heima migration holding pen)	Stage 10
—	Stage 8 (NEW) — off-chain encrypted vault

Parallelization table updated: Stage 8 + Stage 9 are independent code surfaces; can run in parallel after Stage 7.

Test plan

• bash -n scripts/setup-dev-env.sh — syntax check passes
• Detection logic dry-trace on the operator's Mac — every prerequisite already resolves; re-run would skip every installer
• Operator review: confirm the renumber + threat-model position aligns with Heima-side conversations
• Operator review: confirm pallet-vault-pointers shape is acceptable to upstream Substrate idioms before issue #57 leaves design phase
• No code changes in this PR; nothing to test in CI beyond doc-build

Out of scope (deliberately)

• No code changes — this is a doc + design refactor for a v0.1 target with no users.
• No new gap entry in heima-gaps-vs-desired-architecture.md — flagged as a follow-up in the issue and the threat-model doc; mechanically straightforward.
• The Session.token / pallet-secrets-vault references in the body of wiki/blockchain-tee-architecture.md (worked-example sections, etc.) carry the doc-level superseded banner but were not rewritten line-by-line. The banner + the §1 row update are sufficient for readers; a deeper sweep can land alongside the actual Stage 8 implementation work.
• Stage 7 broker-server implementation — tracked as issue #58; separate PR.

Related

• Issue #57 — security finding (this PR's threat model lands the doc work referenced there)
• Issue #58 — Stage 7 broker server (will absorb the dev-setup three-roles work)
• Issue #9 — master-seed HDKD (the shielding key derived at shielding/v1 becomes the wrap-DEK key in the new design)

🤖 Generated with Claude Code