Recovery model

If the user clears their browser, switches device, or wipes the device share, they need to recover the wallet. Sigil supports two custody models for the third (recovery) share.

Customer-managed (default)

You expose a small webhook. At wallet creation Sigil POSTs the recovery share to it; you store it. At recovery time Sigil POSTs again asking for it back; you return it. Sigil never has both shares simultaneously.

Wallet created
   │
   ▼
Sigil POST your webhook
   { "op": "store_recovery_share",
     "wallet_id": "…", "user_identity": {...},
     "recovery_share": "base64", "share_index": 3 }
   ◀── you reply with { "custodian_share_id": "your-id" }

Every webhook call is signed with HMAC-SHA256 in X-Sigil-Signature: t=<unix>,v1=<hex>. Verify it in constant time before acting on the body, and reject if t is more than a few minutes off the wall clock.

Sigil-managed

If you can’t run a webhook (or don’t want to), Sigil holds the recovery share too — but encrypted with a distinct Cloud KMS purpose so the wrap/unwrap of the provider share and the wrap/unwrap of the recovery share never share material. A single key compromise can’t unwrap both.

You opt in from the portal: Recovery → Sigil managed. The portal shows a banner so you understand custody is now centralised in Sigil.

The recovery flow

1. End user opens the iframe on a device with no Device share.
2. Iframe shows a Restore wallet prompt and asks for the email.
3. Sigil sends an OTP. User enters it.
4. Sigil pulls the provider share (Cloud KMS unwrap) and the recovery share (webhook fetch or local KMS unwrap, depending on mode).
5. Iframe receives both, reconstructs the private key in memory.
6. Iframe generates a fresh polynomial and re-shares: new device share stored locally, new provider share PUT to Sigil, new recovery share POSTed to your webhook (or stored in Sigil under a new KEK wrap).
7. Old shares marked rotated.

The end user signs again with the next message; the new device share is already in place.