@forgesworn/shamir-words 0.0.0-development → 1.0.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgesworn/shamir-words",
-  "version": "0.0.0-development",
+  "version": "1.0.0",
   "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"