Seed XOR

TypeScript/JavaScript implementation of Seed XOR: A simple way of securing seeds.

DISCLAIMER

This project is in an early development phase and has not been audited or reviewed. Use it at your own risk.

Description

Seed XOR allows you to split up your seed into multiple parts. The parts can then be used to reconstruct the original seed.

Read more about the concepts behind SeedXOR on the official website: Seed XOR

Installation

npm install seed-xor

Example

import { combine, split } from 'seed-xor';

const original =
  'abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon art';

(async () => {
  console.log('Original:', original);

  const [share1, share2, share3] = await split(original, 3, true);

  console.log('Share 1:', share1);
  console.log('Share 2:', share2);
  console.log('Share 3:', share3);

  const recovered = await combine([share1, share2, share3]);

  console.log('Recovered:', recovered);
})();

For more examples, check the examples folder or the tests.

Documentation

This library exports two methods, split and combine.

Split

split is used to split an existing seed into multiple shares. It takes 3 parameters:

split(mnemonic: string, numberOfShares: 2 | 3 | 4 = 2, useRandom = false): Promise<string[]>

mnemonic: The seed that should be split. numberOfShares: The number of shares that you want to split your mnemonic into. You need ALLx shares to recover your seed phrase. useRandom: If set to true, the shares will be generated randomly. This means that if you use SeedXOR with the same seed multiple times, you will get different shares. If set to false, you will always get the same shares.

Combine

combine is used to combine SeedXOR shares and reconstruct the original seed phrase. Remember: You need ALL shares to recover your seed phrase.

split(shares: string[]): Promise<string>

shares: An array of shares that will be used to recover the original seed phrase.

Testing

npm install
npm test

-------------|---------|----------|---------|---------|-------------------
File         | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-------------|---------|----------|---------|---------|-------------------
All files    |   98.52 |    93.75 |     100 |   98.03 |
 index.ts    |     100 |      100 |     100 |     100 |
 seed-xor.ts |     100 |      100 |     100 |     100 |
 utils.ts    |   97.22 |       50 |     100 |   96.42 | 29
-------------|---------|----------|---------|---------|-------------------

TODOs

• [ ] Fix sonarsource coverage not working
• [ ] Audit/review of library by 3rd party

Dependencies

We try to use only a minimal set of dependencies to reduce the attack surface of malicious code being added by one of those dependencies.

There are only 2 (non-dev) dependencies:

• bip39
• create-hash

1 of those repositories is owned by the bitcoinjs organization, one of them is managed by crypto-browserify.

Usages

Currently, the following wallets support or are working on integrating SeedXOR:

• Coldcard
• AirGap Vault (planned)

Credits

The project setup has been inspired by multiple bitcoinjs libraries, such as bip39 and bip85.

LICENSE

MIT