Source: BRCs-250/wallet/0250.md · sha256 81c08d3a565d

BRC-250: Device Login and Recovery

Brandon Cryderman / HandCash (brandongcryderman@gmail.com)

Status: Draft (proposed number, not a BSVA assignment)

Abstract

This standard lets a user sign in to a self-custodial wallet on a new device with their email address, and get the wallet back with that email alone after losing every device and every written backup. Nothing stored off the user's devices can open the wallet by itself: the host validates, relays and keeps one recovery share it cannot use alone.

1. The new device obtains a login proof: a zero-knowledge proof of the user's email, bound to a key only that device holds and validated by a pinned host. The user can paste it into the wallet from their email or from a browser.
2. The proof asks the user's existing devices for approval.
3. An existing device checks the proof itself, has the user type the comparison code shown on the new device, and sends the vault master straight to the new device, encrypted to that device's key.

If none of the user's devices has been online for seven days, the same login proof starts a recovery (§9):

4. The host waits seven days, alerting every enrolled device and the user's inbox. Any device that appears turns the request back into an approval, and any refusal ends it.
5. After the wait, the host releases its share, sealed to the new device's key. The user pastes the second share from an email they sent themselves at enrollment, and the new device rebuilds the wallet from the two.

A user who still has their recovery phrase or offline slice restores at once, with no wait.

Overview

1. The new device creates a one-time login key L and a secret random value, and commits to both.
2. The user signs in to the host (handcash.io). The host signs an identifier naming the account, L and that commitment. The identifier's hash is the binding.
3. The user proves their email in zero knowledge, bound to the binding:
   • Any address: send one email to login+<binding>@handcash.io, then paste its source into the wallet (or let the host relay it).
   • Google accounts: sign in with Google, in the wallet or in the browser, then paste the resulting proof into the wallet.
4. The wallet sends the login proof to the host. The host validates it and alerts the user's signed-in devices.
5. A signed-in device verifies the proof itself. It then exchanges random values with the new device, and the new device shows an 8-digit comparison code. The user types the code from the new device into the signed-in device, which then sends the vault master, sealed to L.
6. If no device has been online in the last seven days, the request becomes a recovery. After seven more days with no device appearing and no refusal, the host releases its share sealed to L, and the user pastes the mailbox share (§9).

Transfer rule. A signed-in device sends the vault master only when both of these hold:

• the login proof verifies on that device (§6), for the email it enrolled;
• the user types the comparison code shown on the new device, and it matches the code that device computed (§8).

Release rule. The host releases its recovery share only to L, only after a seven-day wait with no enrolled device online and no refusal (§9.2).

Terminology

Specification

1. Conventions

• Signature: a 64-byte compact secp256k1 ECDSA signature over SHA-256 of a UTF-8 message, hex.
• Public key: compressed secp256k1, hex.
• pack_n(s): the UTF-8 bytes of s, right-padded with zero bytes to 31·n, as n big-endian BN254 field elements.
• Poseidon: circomlib Poseidon over BN254.
• Email commitment: Poseidon(pack_9(lowercase(address)), salt), where salt is one field element.

The host MUST refuse an at more than 300 seconds from its clock.

2. Host manifest

The host serves https://<host>/.well-known/brc250.json:

{
  "v": 1,
  "attesterKey": "<public key>",
  "loginMailbox": { "localPart": "login", "domain": "handcash.io" },
  "googleClientIds": ["<OAuth client id>"],
  "circuits": {
    "email-zk": { "id": "<hex SHA-256 of the Groth16 verifying key>", "url": "<verifying key>" },
    "oauth-zk": { "id": "<…>", "url": "<…>" }
  }
}

The mail domain MUST accept mail for <localPart>+<anything>@<domain>. Each device fetches the manifest over TLS at enrollment and pins it. A pinned manifest changes only by re-enrollment.

3. Keys

• Device authority key: the BRC-42 child of account 0's identity key for protocol [2, "brc250 device"], key id 1, counterparty self.
• Login key: fresh for each login, discarded when the login completes or fails.

Each install keeps a random deviceId (BRC-249) and a label such as MacBook · Desktop.

4. Enrollment

A device enrolls when the wallet is created or when the user turns on email login:

1. It picks a random salt, obtains an identifier with purpose enroll, and builds a login proof for it (§6). This proves the address before it is used.
2. It cuts recovery shares (§9.1).
3. It sends POST /enroll to the host:

{
  "loginProof": "<brc250:…>",
  "salt": "<hex>",
  "deviceAuthorityKey": "<public key>",
  "device": { "deviceId": "<hex>", "label": "<text>" },
  "hostShare": "<BRC-140 backup share>",
  "reenrollSignature": "<required if the account is already enrolled>"
}

The host verifies the proof and stores accountRef, the email commitment, salt, the device authority key, the device and the host share, replacing any earlier host share. It MUST require the reenroll signature to change an enrolled account, so a host session alone cannot replace the email.

Every signed-in device keeps the address, salt and pinned manifest, so it can verify login proofs without the host.

5. Identifier

The new device creates L. The user signs in to the host either in the wallet, or on the host's login page at https://<host>/login#<L>, which the wallet opens in a browser. The host MUST issue identifiers only for the signed-in account:

{
  "v": 1,
  "purpose": "login" | "enroll",
  "accountRef": "<hex SHA-256 of \"brc250-account\\n\" + host account id>",
  "loginKey": "<L>",
  "commitment": "<hex SHA-256 of \"brc250-commit\\n\" + L + \"\\n\" + rA>",
  "context": "<client type and approximate location, as the host saw them>",
  "refuseHash": "<hex SHA-256 of the refuse code>",
  "iat": 0,
  "exp": 0,
  "nonce": "<16 random bytes, hex>",
  "signature": "<identifier signature>"
}

The preimage is the following lines joined with \n. context has no line breaks and is at most 200 bytes. exp − iat MUST be at most 900 seconds.

brc250-identifier
v1
<purpose>
<accountRef>
<loginKey>
<commitment>
<context>
<refuseHash>
<iat>
<exp>
<nonce>

rA is 32 random bytes in hex. The new device generates it with L and keeps it secret until §8.

For every identifier, the host MUST email the account's address. The email states context, carries a refuse link with the refuse code, and has Reply-To: <localPart>+<binding>@<domain>. It MUST NOT contain a comparison code: the code is only ever shown by the two devices.

6. Login proof

6.1 Format

A login proof is the string brc250: followed by base64url JSON:

{
  "identifier": { },
  "method": "email-zk" | "oauth-zk",
  "proof": { },
  "publicSignals": [ ]
}

It is safe to paste and to display. It works only with L, which never leaves the new device, and only to request approval.

Before using a login proof, the new device MUST check that its identifier names the device's own L and commitment, and MUST reject it otherwise. A proof made for someone else's login cannot be slipped in.

The proof is a Groth16 proof under the pinned circuit for its method. Whoever builds it needs the salt. The host returns the salt from POST /login/salt only for a valid login identifier, so addresses cannot be guessed against the commitment.

6.2 email-zk (any address)

The user sends one email from the enrolled address to <localPart>+<binding>@<domain>. They can reply to the host's notice, or use a mailto: that the wallet or the login page opens. Subject and body are ignored.

The wallet gets the signed message either way:

• Paste: the user copies the message source from their Sent folder ("Show original" or "View source") into the wallet.
• Relay: the host's inbound mail keeps the raw message until exp, and the wallet or login page fetches it with the host session.

The wallet, or the login page in the browser, then builds the proof. The circuit takes the signed header block and the salt as private inputs. It proves:

1. A DKIM-Signature with a=rsa-sha256 verifies over the relaxed-canonicalized headers it signs, under a 2048-bit RSA modulus with Poseidon hash dkimKeyHash.
2. Its d= is dkimDomain, its s= is selector, and its h= includes from and to.
3. The From address's domain is dkimDomain or a subdomain of it.
4. The To header contains toAddress.
5. emailCommitment is the commitment of the From address.

Public signals: dkimKeyHash, pack_9(dkimDomain), pack_3(selector), pack_9(toAddress), emailCommitment.

A verifier MUST check:

• the proof, under the pinned email-zk circuit;
• that the key at <selector>._domainkey.<dkimDomain> hashes to dkimKeyHash, fetched over DNSSEC or from two independent DNS-over-HTTPS resolvers that agree;
• that toAddress is <localPart>+<binding>@<domain> from the pinned manifest;
• that emailCommitment is the enrolled commitment.

6.3 oauth-zk (Google accounts)

The user obtains a Google ID token whose nonce is the binding, for one of the pinned googleClientIds. They can do this either way:

• In the wallet: the wallet runs the sign-in itself, with PKCE (RFC 7636), and builds the proof.
• In a browser: on the host's login page (§5), after the host sign-in and the Google sign-in, the page builds the proof in the browser and shows the login proof to copy into the wallet.

The circuit takes the token and the salt as private inputs. It proves:

1. The RS256 signature verifies under a modulus with Poseidon hash googleKeyHash.
2. iss is https://accounts.google.com, email_verified is true, and aud, nonce and exp equal the public signals.
3. emailCommitment is the commitment of the email claim.

Public signals: googleKeyHash, pack_5(aud), pack_2(nonce), exp, emailCommitment.

A verifier MUST check:

• the proof, under the pinned oauth-zk circuit;
• that googleKeyHash matches a key in Google's JWKS that is current or retired within 24 hours;
• that aud is in the pinned googleClientIds;
• that nonce is the binding;
• that emailCommitment is the enrolled commitment.

6.4 Verifying a login proof

A verifier (the host, or a signed-in device) MUST also check:

• that the identifier signature verifies under the pinned attester key;
• that purpose is as expected;
• that the binding is the one being requested.

Only email the user sends counts, because the user's provider signs it. Verifiers MUST NOT accept a proof built from an email the host sent to the user, such as a verification code or link. The host signs those itself and keeps a copy, so it could build such a proof without the user. Addresses whose provider does not sign with an aligned 2048-bit RSA key cannot use email-zk. More OpenID Connect issuers MAY be added, each with its own circuit.

7. Presence

While unlocked and online, each signed-in device sends POST /presence to the host, at least daily and at most hourly:

{ "deviceId": "<hex>", "label": "<text>", "state": "active" | "signedOut", "at": 0, "signature": "<presence>" }

at MUST increase per device. The host records lastSeen, and drops the device on signedOut. A device is recent if now − lastSeen < 7 days.

8. Login

Request

The new device sends POST /login/start with { loginProof }. The host:

1. verifies it (§6, purpose login, now < exp);
2. opens a request keyed by the binding, replacing any open request for the account. If no enrolled device is recent, the request is a recovery and gets releaseAt, seven days after it opened (§9.2). A request stays open for at most seven days, or a recovery until a day after releaseAt;
3. sends a BRC-33 message to every enrolled device authority key's messagebox;
4. answers:

{
  "binding": "<base64url>",
  "deviceAuthorityKey": "<public key>",
  "recentDevices": [{ "label": "<text>", "lastSeen": 0 }],
  "releaseAt": 0
}

releaseAt is present only for a recovery. The new device shows "Approve on (seen )". If recentDevices is empty, it shows "None of your devices has been online in 7 days. You can get your wallet back on ", and offers to restore at once from the recovery phrase or offline slice (§9.3).

Approve

A signed-in device finds the request through the messagebox, or through GET /login/pending sent with a pending signature. The user opens it there.

1. Verify. The device verifies the login proof itself (§6), against its own pinned manifest, address and salt. It MUST NOT rely on the host's verification.
2. Challenge. It generates 32 random bytes rB and sends POST /login/challenge with { binding, rB }. It MUST send one challenge per request, and only after step 1.
3. Reveal. The new device receives rB from GET /login/status, then sends POST /login/reveal with { binding, rA }. It MUST reveal only after receiving rB, and only once.
4. Check. The signed-in device receives rA and checks it against the identifier's commitment. It MUST refuse on a mismatch.
5. Compare. Both devices compute the comparison code, uint64(SHA-256("brc250-code\n" + binding + "\n" + rA + "\n" + rB)[0..8]) mod 100000000, as eight digits shown in two groups of four. The new device displays it. The signed-in device shows context and asks the user to type the code shown on the new device. It MUST NOT display the code itself.
6. Decide. On a wrong code, the device sends refuse. On the right code and confirmation, it sends the vault master to L: a BRC-78 message from its device authority key to L, delivered through L's BRC-33 messagebox at the host. It then sends POST /login/close with { binding, signature } (sent).

The host fixes everything in the identifier, including L and the commitment, before rB exists. The new device fixes rA before it sees rB. So no relay can choose a request whose code matches the one on the user's new device. A substituted request matches with probability 10⁻⁸.

Refuse

POST /login/close with { binding, signature } (refuse) from a device, or { binding, refuseCode } from the inbox link, closes the request. After a device refusal, the host SHOULD refuse new requests for the account for 24 hours.

Complete

The new device polls GET /login/status?binding=, which returns the state (open, waiting, sent, released or refused), rB once present, and releaseAt for a recovery. It reads L's messagebox, and MUST:

1. decrypt the message, and check that the master derives deviceAuthorityKey, discarding it otherwise;
2. discard L, enroll its presence, and find its accounts by BRC-208 discovery and open only those none of the user's other devices holds (BRC-249).

Later unlocks are local. Signing out wipes the vault and sends signedOut.

9. Recovery

Two ways back when no signed-in device can approve: with only the email (§9.2), or from the user's own backup (§9.3). Neither gives the host the vault.

9.1 Recovery shares

At enrollment, and again on every re-enrollment, the device splits the vault entropy with toBackupShares(2, 3) (BRC-157, BRC-140):

• Host share: sent with POST /enroll. The host keeps at most one share per account, as a BRC-154 backup service does, and releases it only under §9.2.
• Mailbox share: the wallet opens a mailto: from the enrolled address to itself, subject HandCash recovery share, body brc250-share:<share>. The user sends it, then pastes it back from their inbox, and the device checks that it combines with the host share to the vault entropy. The message passes through the user's mail provider only. The host never sees it.
• User share: shown to the user as a key slice to keep offline, or deposited with an independent BRC-154 service. The wallet MAY discard it.

A device MUST NOT give any party two shares of one split, and MUST NOT send the mailbox or user share to the host. A new split does not revoke an old one, because shares of the same split still combine. On re-enrollment the host MUST delete the old host share, which leaves the old mailbox and user shares one short.

9.2 With only the email

1. Start. The new device sends a login request (§8). With no recent device, the host answers with releaseAt and the request waits. The host alerts every enrolled device and emails the address, with the refuse link, when the request opens and again a day before releaseAt.
2. Wait. A device that comes online during the wait finds the request (§8) and approves or refuses it. Any presence from an enrolled device turns the request into an ordinary login, which then completes only by that device's approval. A refusal from a device or from the email link closes it.
3. Release. At releaseAt, if the request is still open and no enrolled device has sent presence since seven days before it opened, the new device sends POST /login/release with { binding, signature } (release). The host answers with its share as a BRC-78 message to L, and closes the request. It MUST NOT release earlier, or to any key but L.
4. Rebuild. The user pastes the mailbox share, or the user share. The device combines the two shares and decodes the entropy (BRC-157). It MUST check that the master derives deviceAuthorityKey, and discard both shares and the master otherwise. It then discards L.
5. Rejoin. The device cuts new recovery shares and re-enrolls (§4) with the reenroll signature, which deletes the released host share. It sends presence, and chooses accounts to hold as at the end of a login (§8).

9.3 From the user's own backup

A user who still has their recovery phrase, or two of their own key slices, restores at once. The backup already proves custody, so there is no wait.

1. Restore. The device restores the vault master from the phrase or the slices (BRC-157), and derives the device authority key (§3).
2. Match. It sends POST /restore with { at, signature } (restore). The host answers with the account's email commitment and salt, or 404 if the key was never enrolled. The user types their email address. The device MUST check that the commitment of that address under the returned salt equals the returned commitment, and asks again otherwise. It then keeps the address, the salt and the manifest it pins now. Because the device checks the address the user typed, the host cannot substitute another.
3. Close. If the device opened a login request or a recovery, it sends POST /login/close with { binding, signature } (restored). The host closes it without the cooldown that follows a refusal.
4. Rejoin. It sends presence (§7). If the user no longer controls the enrolled address, or the host answered 404, the device enrolls a new address (§4) with the restored key's reenroll signature. Any other signed-in device adopts a replaced address as in step 2, once the user types it there, and refuses login proofs for the new address until then.
5. Hold. It chooses accounts to hold as at the end of a login (§8).

A recovered or restored device is a signed-in device from then on, and can approve later logins.

10. Host endpoints

Security considerations

• A device that approves already holds the wallet, so one approval suffices. Refusing never moves funds, so one refusal suffices.
• The circuits are part of the trusted base. Each MUST be audited, and its trusted setup published, before devices accept it.
• The host enforces the wait. It stops an inbox takeover while the host is honest, not a host working with the mail provider (see above).
• Wallets SHOULD keep at least one device sending presence, so a recovery the user did not start meets a device that can refuse it.

Rationale

• Two shares, two parties. The vault moves only from a device that already holds it, or is rebuilt on the new device from two shares that no single party holds: the host's, released after a public wait, and the one in the user's own mailbox. The host can never hand out the vault, because it never has it.
• A seven-day wait. Recovery with only an email makes the email the last key. The wait gives every device, and the user's inbox, a week to stop a recovery the user did not start, and a device that appears turns it back into an approval.
• Devices verify for themselves. The host's check filters spam. The device's own check is what matters, so a dishonest host can only drop requests.
• Pasting is safe. A login proof grants nothing but a prompt on the user's own devices, bound to a key the attacker does not hold.
• A committed comparison code. A short code derived only from the request can be ground by whoever creates requests: about 100 tries for two digits. Here the new device commits to rA before the approving device sends rB, as in Bluetooth numeric comparison, so nobody in the middle can steer the code. Typing it, rather than picking it from a list, removes guessing.
• Prefer the in-wallet Google sign-in. It never runs host-served code. The browser path is also safe under the comparison code, but the in-wallet path keeps the host out entirely.
• Provider signatures. Without them, the host could put convincing prompts on any user's devices. DKIM and Google signatures come from outside the host.
• Binding in the recipient address. Every email the user sends carries a DKIM signature. Requiring the binding in the To address at the pinned host means only mail sent to the host for this login counts.
• Not mail from the host. The host holds its own DKIM key and keeps copies of what it sends, so it could forge those.
• Zero knowledge. Proofs can be pasted, relayed and logged without exposing the address.

References

• BRC-33: PeerServ Message Relay Interface
• BRC-42: BSV Key Derivation Scheme
• BRC-78: Serialization Format for Portable Encrypted Messages
• BRC-140: Threshold Key Sharing and Backup via Shamir's Secret Sharing Scheme
• BRC-154: Pluggable Backup Services for BRC-140 Share Vaults
• BRC-157: Entropy-Rooted Backup and Recovery with Mnemonics and Backup Shares
• BRC-208: Vault Sub-Accounts
• OpenID Connect Core 1.0, §3.1.2.1
• RFC 6376: DKIM Signatures
• RFC 7489: DMARC, §3.1 (alignment)
• RFC 7636: PKCE
• Groth16