@forgesworn/shamir-words 0.0.0-development → 1.0.1

package/LICENCE

@@ -0,0 +1,21 @@
+MIT Licence
+
+Copyright (c) 2025 Forgesworn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicence, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# shamir-words
+
+**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](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.
+
+## Why shamir-words?
+
+- **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/hashes` and `@scure/bip39` (audited cryptographic libraries)
+- **TypeScript-first** — full type safety with exported interfaces and error classes
+
+## Install
+
+```bash
+npm install @forgesworn/shamir-words
+```
+
+## Quick Start
+
+```typescript
+import {
+  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 === secret
+```
+
+## API
+
+### `splitSecret(secret, threshold, shares)`
+
+Split 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[]`.
+
+### `reconstructSecret(shares, threshold)`
+
+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.
+
+### `shareToWords(share)`
+
+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[]`.
+
+### `wordsToShare(words)`
+
+Decode BIP-39 words back to a share. Verifies the checksum and rejects corrupted or tampered input.
+
+Returns `ShamirShare`.
+
+### Types
+
+```typescript
+interface ShamirShare {
+  id: number;        // 1-255 (the x-coordinate)
+  threshold: number; // 2-255 (minimum shares for reconstruction)
+  data: Uint8Array;  // evaluated polynomial bytes
+}
+```
+
+### Error Classes
+
+- `ShamirError` — base class for all errors
+- `ShamirValidationError` — invalid inputs (wrong types, out-of-range values)
+- `ShamirCryptoError` — cryptographic failures (e.g. GF(256) zero inverse)
+
+## Wire Format
+
+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.
+
+## Limitations
+
+- 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)
+
+## Licence
+
+[MIT](LICENCE)

package/dist/index.js

@@ -1,7 +1,7 @@
 // Shamir's Secret Sharing over GF(256)
 // Split secrets into threshold-of-n shares using polynomial interpolation
 // Shares can be encoded as BIP-39 words for human-readable exchange
-import { randomBytes } from '@noble/hashes/utils.js';
+import { randomFillSync } from 'node:crypto';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { wordlist as BIP39_WORDLIST } from '@scure/bip39/wordlists/english.js';
 /** O(1) word-to-index lookup, built once at module load */
@@ -140,7 +140,8 @@ export function splitSecret(secret, threshold, shares) {
         // coeffs[0] = secret byte, coeffs[1..threshold-1] = random
         const coeffs = new Uint8Array(threshold);
         coeffs[0] = secret[byteIdx];
-        const rand = randomBytes(threshold - 1);
+        const rand = new Uint8Array(threshold - 1);
+        randomFillSync(rand);
         for (let j = 1; j < threshold; j++) {
             coeffs[j] = rand[j - 1];
         }
@@ -184,6 +185,9 @@ export function reconstructSecret(shares, threshold) {
         if (ids.has(share.id)) {
             throw new ShamirValidationError('Duplicate share IDs detected — each share must have a unique ID');
         }
+        if (Number.isInteger(share.threshold) && share.threshold !== threshold) {
+            throw new ShamirValidationError(`Share threshold (${share.threshold}) does not match supplied threshold (${threshold})`);
+        }
         ids.add(share.id);
     }
     const secretLen = used[0].data.length;
@@ -334,6 +338,12 @@ export function wordsToShare(words) {
     if (totalExpected > byteList.length) {
         throw new ShamirValidationError('Word list too short for encoded data length');
     }
+    // Verify phantom bytes (decoded from padding bits) are zero — ensures canonical encoding
+    for (let i = totalExpected; i < byteList.length; i++) {
+        if (byteList[i] !== 0) {
+            throw new ShamirValidationError('Non-zero padding bits detected — word list may be corrupted');
+        }
+    }
     // Enforce canonical encoding: word count must match expected
     const expectedWords = Math.ceil(totalExpected * 8 / 11);
     if (words.length !== expectedWords) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/shamir-words",
-  "version": "0.0.0-development",
+  "version": "1.0.1",
   "description": "Shamir's Secret Sharing over GF(256) with BIP-39 word encoding for human-readable share exchange",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,11 +33,15 @@
     "cryptography",
     "key-splitting"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "sideEffects": false,
   "license": "MIT",
   "engines": {
     "node": ">=18"
   },
+  "homepage": "https://github.com/forgesworn/shamir-words",
   "repository": {
     "type": "git",
     "url": "https://github.com/forgesworn/shamir-words.git"
@@ -49,6 +53,7 @@
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
+    "@types/node": "^25.5.0",
     "semantic-release": "^25.0.3",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"

package/src/index.ts

@@ -2,7 +2,7 @@
 // Split secrets into threshold-of-n shares using polynomial interpolation
 // Shares can be encoded as BIP-39 words for human-readable exchange
 
-import { randomBytes } from '@noble/hashes/utils.js';
+import { randomFillSync } from 'node:crypto';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { wordlist as BIP39_WORDLIST } from '@scure/bip39/wordlists/english.js';
 
@@ -172,7 +172,8 @@ export function splitSecret(
     const coeffs = new Uint8Array(threshold);
     coeffs[0] = secret[byteIdx]!;
 
-    const rand = randomBytes(threshold - 1);
+    const rand = new Uint8Array(threshold - 1);
+    randomFillSync(rand);
     for (let j = 1; j < threshold; j++) {
       coeffs[j] = rand[j - 1]!;
     }
@@ -225,6 +226,11 @@ export function reconstructSecret(
     if (ids.has(share.id)) {
       throw new ShamirValidationError('Duplicate share IDs detected — each share must have a unique ID');
     }
+    if (Number.isInteger(share.threshold) && share.threshold !== threshold) {
+      throw new ShamirValidationError(
+        `Share threshold (${share.threshold}) does not match supplied threshold (${threshold})`,
+      );
+    }
     ids.add(share.id);
   }
 
@@ -398,6 +404,13 @@ export function wordsToShare(words: string[]): ShamirShare {
     throw new ShamirValidationError('Word list too short for encoded data length');
   }
 
+  // Verify phantom bytes (decoded from padding bits) are zero — ensures canonical encoding
+  for (let i = totalExpected; i < byteList.length; i++) {
+    if (byteList[i] !== 0) {
+      throw new ShamirValidationError('Non-zero padding bits detected — word list may be corrupted');
+    }
+  }
+
   // Enforce canonical encoding: word count must match expected
   const expectedWords = Math.ceil(totalExpected * 8 / 11);
   if (words.length !== expectedWords) {