Nostr: npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2
Split secrets into human-readable word shares that can be spoken, written down, or stored separately.
Backing up cryptographic keys is hard. Raw byte shares are error-prone to transcribe and impossible to read over the phone. shamir-words combines Shamir's Secret Sharing over GF(256) with BIP-39 word encoding, so each share becomes a list of familiar English words — just like a Bitcoin seed phrase.
- Human-readable shares — each share is a BIP-39 word list, not a hex blob
- Threshold recovery — any t of n shares reconstruct the secret; fewer reveal nothing
- Integrity checking — SHA-256 checksum detects transcription errors before reconstruction
- Minimal dependencies — only
@noble/hashesand@scure/bip39(audited cryptographic libraries) - TypeScript-first — full type safety with exported interfaces and error classes
npm install @forgesworn/shamir-wordsimport {
splitSecret,
reconstructSecret,
shareToWords,
wordsToShare,
} from '@forgesworn/shamir-words';
// Your secret (e.g. a 32-byte private key)
const secret = new Uint8Array([
0xde, 0xad, 0xbe, 0xef, 0xca, 0xfe, 0xba, 0xbe,
0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef,
]);
// Split into 5 shares, any 3 can reconstruct
const shares = splitSecret(secret, 3, 5);
// Convert each share to speakable words
const wordShares = shares.map(shareToWords);
// e.g. ["abandon", "ability", "able", ...] — one word list per share
// Later: decode words back to shares and reconstruct
const decoded = wordShares.map(wordsToShare);
const recovered = reconstructSecret(decoded, 3);
// recovered === secretSplit a secret into Shamir shares over GF(256).
| Parameter | Type | Description |
|---|---|---|
secret |
Uint8Array |
The secret to split (1-255 bytes) |
threshold |
number |
Minimum shares needed to reconstruct (2-255) |
shares |
number |
Total shares to create (threshold-255) |
Returns ShamirShare[].
Reconstruct a secret from shares using Lagrange interpolation.
| Parameter | Type | Description |
|---|---|---|
shares |
ShamirShare[] |
At least threshold shares |
threshold |
number |
The threshold used during splitting |
Returns Uint8Array — the original secret.
Encode a share as BIP-39 words. The word list embeds the share ID, threshold, data, and a SHA-256 checksum byte for integrity.
Returns string[].
Decode BIP-39 words back to a share. Verifies the checksum and rejects corrupted or tampered input.
Returns ShamirShare.
interface ShamirShare {
id: number; // 1-255 (the x-coordinate)
threshold: number; // 2-255 (minimum shares for reconstruction)
data: Uint8Array; // evaluated polynomial bytes
}ShamirError— base class for all errorsShamirValidationError— invalid inputs (wrong types, out-of-range values)ShamirCryptoError— cryptographic failures (e.g. GF(256) zero inverse)
Each word-encoded share packs bytes as:
[data_length, threshold, share_id, ...data, checksum]
The byte stream is split into 11-bit groups, each mapped to a BIP-39 word. The checksum is the first byte of SHA-256 over the preceding bytes.
- Secret size: 1-255 bytes (covers all standard key sizes up to 255 bytes)
- Share count: up to 255 (the GF(256) field size minus zero)
- Threshold: 2-255 (single-share schemes are just copying, not secret sharing)