Skip to content

HSM: design a key-loss recovery story (reset-and-rotate, not decryption recovery) #180

Description

@juniperbevensee

Question from Juniper (2026-07-24): can a user recover HSM dashboard access if they lose their decryption key? People WILL lose keys; losing everything with it is not acceptable.

Reality check: if the encryption is doing its job, lost key = the ciphertext is gone — there is no honest "recover the plaintext" path, and building a backdoor would defeat the vault. But HSM's contents are almost entirely API keys and tokens, which are rotatable. So the right recovery story is probably not decryption recovery but a reset-and-rotate flow:

  1. Operator proves identity out-of-band (org admin action, not a self-serve password reset)
  2. HSM issues a fresh keypair / operator token
  3. Dashboard walks through every stored provider entry as a rotation checklist — old values marked unrecoverable, operator re-mints each upstream (GitHub App key, OpenRouter, Telegram, …) and pastes the new ones
  4. Assigned agents' .envs regenerate + containers recreate, same as a normal key update

Optional hardening for org installs: Shamir-split a recovery key across 2–3 org members, or an org-admin escrow key — decide deliberately, it's a real trust tradeoff.

Also worth: a "break-glass inventory" export — a plaintext-free list of what providers/keys exist and where they're used, so a reset never turns into archaeology.

Flagging for the gardener lane per Juniper.

🤖 Generated with Claude Code

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions