docs/identity-backup-recovery.md documents a complete BIP39 backup and recovery API — generateMnemonic, isValidMnemonic, mnemonicToSeed, and a mnemonic option on Kernel.make — and there is no UI anywhere that calls it. Grepping for mnemonic outside packages/ocap-kernel/src finds only a Node test helper.
So in practice no extension user has ever backed up their kernel identity, and by default they cannot: the kernel generates a random seed on first init (remotes/kernel/remote-comms.ts:106-112) and random seeds cannot be converted to a mnemonic, which the doc itself notes. Recovery has to be arranged before first init or not at all.
Why now
#989 changes the failure mode. Today a lost or unreadable seed tends to produce a silently regenerated identity; after #989 it is a hard startup error that names the cause. That is the right behaviour, and it converts a silent corruption into a visible dead end — which is only acceptable if there is a way to have prepared for it.
Scope
Product/UX call as much as engineering:
- A first-run affordance in the extension to generate a mnemonic and prompt the user to record it, before the identity is created.
- A recovery path that takes a mnemonic and reinitialises (
resetStorage: true plus mnemonic, per the existing doc).
- Verification before committing to a recovery, so a user can check a phrase produces the expected peer ID rather than discovering otherwise afterwards — the doc sketches this under "Scenario 4".
- Decide what happens for identities that already exist with random seeds, which cannot be retrofitted with a mnemonic. Probably: surface that they are unrecoverable, and offer a deliberate identity reset for anyone who wants a recoverable one.
Note on the derivation
Separately from the UX, mnemonicToSeed (packages/ocap-kernel/src/utils/bip39.ts:50-57) takes the raw first 32 bytes of the BIP39 512-bit seed with an empty passphrase and no derivation path. That is not a wallet-key compromise, but it means a reused mnemonic has two systems deriving from one secret with no declared separation. Raised on #777, which owns the fix; worth settling before a UI encourages people to record and reuse these phrases.
Related: #989 (custody), #777 (derivation).
docs/identity-backup-recovery.mddocuments a complete BIP39 backup and recovery API —generateMnemonic,isValidMnemonic,mnemonicToSeed, and amnemonicoption onKernel.make— and there is no UI anywhere that calls it. Grepping formnemonicoutsidepackages/ocap-kernel/srcfinds only a Node test helper.So in practice no extension user has ever backed up their kernel identity, and by default they cannot: the kernel generates a random seed on first init (
remotes/kernel/remote-comms.ts:106-112) and random seeds cannot be converted to a mnemonic, which the doc itself notes. Recovery has to be arranged before first init or not at all.Why now
#989 changes the failure mode. Today a lost or unreadable seed tends to produce a silently regenerated identity; after #989 it is a hard startup error that names the cause. That is the right behaviour, and it converts a silent corruption into a visible dead end — which is only acceptable if there is a way to have prepared for it.
Scope
Product/UX call as much as engineering:
resetStorage: trueplusmnemonic, per the existing doc).Note on the derivation
Separately from the UX,
mnemonicToSeed(packages/ocap-kernel/src/utils/bip39.ts:50-57) takes the raw first 32 bytes of the BIP39 512-bit seed with an empty passphrase and no derivation path. That is not a wallet-key compromise, but it means a reused mnemonic has two systems deriving from one secret with no declared separation. Raised on #777, which owns the fix; worth settling before a UI encourages people to record and reuse these phrases.Related: #989 (custody), #777 (derivation).