{"id":47963006,"url":"https://github.com/forgesworn/shamir-words","last_synced_at":"2026-04-04T10:03:49.234Z","repository":{"id":345344959,"uuid":"1185460203","full_name":"forgesworn/shamir-words","owner":"forgesworn","description":"Split secrets into human-readable BIP-39 word shares using Shamir's Secret Sharing over GF(256)","archived":false,"fork":false,"pushed_at":"2026-03-28T15:12:59.000Z","size":439,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T17:43:40.444Z","etag":null,"topics":["backup","bip39","cryptography","galois-field","mnemonic","privacy","recovery","shamir-secret-sharing","threshold","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/forgesworn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T15:53:55.000Z","updated_at":"2026-03-28T15:13:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/forgesworn/shamir-words","commit_stats":null,"previous_names":["forgesworn/shamir-words"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/forgesworn/shamir-words","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2Fshamir-words","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2Fshamir-words/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2Fshamir-words/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2Fshamir-words/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forgesworn","download_url":"https://codeload.github.com/forgesworn/shamir-words/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forgesworn%2Fshamir-words/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31395450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T09:13:02.600Z","status":"ssl_error","status_checked_at":"2026-04-04T09:13:01.683Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["backup","bip39","cryptography","galois-field","mnemonic","privacy","recovery","shamir-secret-sharing","threshold","typescript"],"created_at":"2026-04-04T10:03:48.512Z","updated_at":"2026-04-04T10:03:49.229Z","avatar_url":"https://github.com/forgesworn.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# shamir-words\n\n**Nostr:** [`npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2`](https://njump.me/npub1mgvlrnf5hm9yf0n5mf9nqmvarhvxkc6remu5ec3vf8r0txqkuk7su0e7q2)\n\n**Split secrets into human-readable word shares that can be spoken, written down, or stored separately.**\n\nBacking 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](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing) over GF(256) with [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) word encoding, so each share becomes a list of familiar English words — just like a Bitcoin seed phrase.\n\n## Why shamir-words?\n\n- **Human-readable shares** — each share is a BIP-39 word list, not a hex blob\n- **Threshold recovery** — any _t_ of _n_ shares reconstruct the secret; fewer reveal nothing\n- **Integrity checking** — SHA-256 checksum detects transcription errors before reconstruction\n- **Minimal dependencies** — only `@noble/hashes` and `@scure/bip39` (audited cryptographic libraries)\n- **TypeScript-first** — full type safety with exported interfaces and error classes\n\n## Install\n\n```bash\nnpm install @forgesworn/shamir-words\n```\n\n## Quick Start\n\n```typescript\nimport {\n  splitSecret,\n  reconstructSecret,\n  shareToWords,\n  wordsToShare,\n} from '@forgesworn/shamir-words';\n\n// Your secret (e.g. a 32-byte private key)\nconst secret = new Uint8Array([\n  0xde, 0xad, 0xbe, 0xef, 0xca, 0xfe, 0xba, 0xbe,\n  0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef,\n]);\n\n// Split into 5 shares, any 3 can reconstruct\nconst shares = splitSecret(secret, 3, 5);\n\n// Convert each share to speakable words\nconst wordShares = shares.map(shareToWords);\n// e.g. [\"abandon\", \"ability\", \"able\", ...] — one word list per share\n\n// Later: decode words back to shares and reconstruct\nconst decoded = wordShares.map(wordsToShare);\nconst recovered = reconstructSecret(decoded, 3);\n// recovered === secret\n```\n\n## API\n\n### `splitSecret(secret, threshold, shares)`\n\nSplit a secret into Shamir shares over GF(256).\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `secret` | `Uint8Array` | The secret to split (1-255 bytes) |\n| `threshold` | `number` | Minimum shares needed to reconstruct (2-255) |\n| `shares` | `number` | Total shares to create (threshold-255) |\n\nReturns `ShamirShare[]`.\n\n### `reconstructSecret(shares, threshold)`\n\nReconstruct a secret from shares using Lagrange interpolation.\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `shares` | `ShamirShare[]` | At least `threshold` shares |\n| `threshold` | `number` | The threshold used during splitting |\n\nReturns `Uint8Array` — the original secret.\n\n### `shareToWords(share)`\n\nEncode a share as BIP-39 words. The word list embeds the share ID, threshold, data, and a SHA-256 checksum byte for integrity.\n\nReturns `string[]`.\n\n### `wordsToShare(words)`\n\nDecode BIP-39 words back to a share. Verifies the checksum and rejects corrupted or tampered input.\n\nReturns `ShamirShare`.\n\n### Types\n\n```typescript\ninterface ShamirShare {\n  id: number;        // 1-255 (the x-coordinate)\n  threshold: number; // 2-255 (minimum shares for reconstruction)\n  data: Uint8Array;  // evaluated polynomial bytes\n}\n```\n\n### Error Classes\n\n- `ShamirError` — base class for all errors\n- `ShamirValidationError` — invalid inputs (wrong types, out-of-range values)\n- `ShamirCryptoError` — cryptographic failures (e.g. GF(256) zero inverse)\n\n## Wire Format\n\nEach word-encoded share packs bytes as:\n\n```\n[data_length, threshold, share_id, ...data, checksum]\n```\n\nThe 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.\n\n## Limitations\n\n- Secret size: 1-255 bytes (covers all standard key sizes up to 255 bytes)\n- Share count: up to 255 (the GF(256) field size minus zero)\n- Threshold: 2-255 (single-share schemes are just copying, not secret sharing)\n\n## Licence\n\n[MIT](LICENCE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforgesworn%2Fshamir-words","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforgesworn%2Fshamir-words","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforgesworn%2Fshamir-words/lists"}