Recovery model

Recovery is the answer to “what happens when the user clears their browser, switches device, or wipes the device share?”. It applies only to client-mode EOA wallets — TEE wallets have no end-user-held material and need no recovery flow; smart accounts inherit their owner’s recovery story.

Two custody models

Customer-managed (default)

You run a small webhook. At wallet creation Sigil POSTs the recovery share to it; you store it (under your own KEK, ideally). 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 { "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.

This is the strongest custody model — neither Sigil nor your infrastructure alone can rebuild a key. It’s also the most work operationally (you have to keep the recovery share secret across your fleet for the lifetime of the user).

Sigil-managed

If you can’t (or don’t want to) run a webhook, Sigil holds the recovery share too — but encrypted with a distinct Cloud KMS purpose so the unwrap material for the provider share and for the recovery share never share key 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.

This is the easiest operational model, recommended when you don’t have an existing key-management infrastructure to lean on.

The recovery flow

1. End user opens the iframe on a device with no device share.
2. Iframe shows "Restore wallet" and asks for the email.
3. Sigil sends an OTP. User enters it.
4. Sigil pulls:
     a) the provider share (Cloud KMS unwrap)
     b) the recovery share (your webhook OR Sigil's separate KMS unwrap)
5. Iframe receives both shares, reconstructs the private key in memory.
6. Iframe generates a fresh polynomial and re-shares:
     - new device share → localStorage
     - new provider share → PUT to Sigil
     - new recovery share → POST to your webhook (or Sigil's
       separate-KEK store)
7. Old shares marked rotated. Grace period, then purged.

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

Polynomial rotation

Every recovery rotates the polynomial. New shares are issued for the same private key — mathematically a fresh f(x) of degree 1 with the same f(0) — and the old shares are marked rotated. After a grace period they’re purged. A leaked old share becomes useless once rotation completes.

This means a recovery attempt — even an unauthorized one that fails verification — does not weaken the wallet. Successful recoveries invalidate the old shares; failed recoveries leave the shares intact.

Safeguards on the flow

• TTL: a recovery process expires after 15 minutes if not completed.
• OTP lockout: the verification code allows 5 attempts. After 5 failures the process is locked; the user must start over.
• Email notification: the user receives an email on recovery completion, so an unauthorized attempt is visible.
• Audit trail: the org’s audit log records initiation, verification, and completion (including failures).

Why TEE wallets don’t need recovery

A TEE wallet’s two shares both live inside Sigil’s infrastructure — the TEE share sealed to the attested workload’s identity, and the provider share in Sigil’s database. Neither is ever on a user’s device, so there’s nothing for a user to lose. Sigil’s operational procedures handle TEE share continuity during workload upgrades (multiple attested deployments in parallel during rollover); see TEE security model for details.

If you need a “delete-this-wallet” or “rotate-this-key” capability for a TEE wallet, that’s a key rotation — currently handled out of band; an in-product flow is on the roadmap.

Smart accounts and recovery

A smart account is just a contract pointed at an owner EOA. Recover the owner (via the standard flow above) and the smart account is automatically restored — same factory + same owner = deterministic CREATE2 address.

Tip

After recovery, the user can immediately keep using any smart accounts they had provisioned. The bundler accepts signatures from the recovered owner key because that key is mathematically the same as before recovery (same f(0), just a fresh polynomial).

Choosing a custody model

Property	Customer-managed	Sigil-managed
Sigil can rebuild the key alone?	No	No (requires a KEK access path Sigil ops can’t take silently)
Your infra can rebuild it alone?	No	No (you don’t have the recovery share)
Setup work	Run a webhook	Toggle in portal
Audit ownership	You control the recovery share lifecycle	Sigil controls both encrypted shares
Recommended for	Apps with existing key/secret management	Apps without that infra