@forgesworn/shamir-core 1.0.2 → 1.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheCryptoDonkey
+
+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, sublicense, 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

@@ -1,5 +1,7 @@
 # @forgesworn/shamir-core
 
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/TheCryptoDonkey?logo=githubsponsors&color=ea4aaa&label=Sponsor)](https://github.com/sponsors/TheCryptoDonkey)
+
 GF(256) Shamir's Secret Sharing for TypeScript. Split a secret into threshold-of-n shares and reconstruct from any threshold-sized subset.
 
 **Zero runtime dependencies.** Pure TypeScript, Web Crypto only.
@@ -10,6 +12,29 @@ GF(256) Shamir's Secret Sharing for TypeScript. Split a secret into threshold-of
 npm install @forgesworn/shamir-core
 ```
 
+## Requirements
+
+**Node.js 19 or later**, or any runtime with a global Web Crypto `crypto.getRandomValues` (current browsers, Deno, Bun). `splitSecret` calls the global `crypto` directly, and Node.js only exposes it without a flag from version 19. Node.js 19 is end-of-life, so in practice use a maintained release.
+
+On Node.js 18, `splitSecret` throws a plain `ReferenceError` (not a Shamir error) because `crypto` is undefined. Either start Node with `--experimental-global-webcrypto`, or define the global before calling it:
+
+```javascript
+import { webcrypto } from 'node:crypto';
+globalThis.crypto ??= webcrypto;
+```
+
+These are workarounds, not a supported configuration. `reconstructSecret` does not use `crypto`.
+
+**ESM only.** The package has `"type": "module"` and its `exports` map has only an `import` condition. `require('@forgesworn/shamir-core')` therefore fails with `ERR_PACKAGE_PATH_NOT_EXPORTED` on every Node.js version, including those that can otherwise `require()` ES modules. From CommonJS, use dynamic `import()`:
+
+```javascript
+async function main() {
+  const { splitSecret, reconstructSecret } = await import('@forgesworn/shamir-core');
+  const shares = splitSecret(new Uint8Array([1, 2, 3]), 2, 3);
+  return reconstructSecret(shares.slice(0, 2), 2);
+}
+```
+
 ## Quick Start
 
 ```typescript
@@ -19,13 +44,27 @@ import { splitSecret, reconstructSecret } from '@forgesworn/shamir-core';
 const secret = crypto.getRandomValues(new Uint8Array(32));
 const shares = splitSecret(secret, 3, 5);
 
-// Reconstruct from any 3 shares
-const recovered = reconstructSecret([shares[0], shares[2], shares[4]], 3);
-// recovered is identical to secret
+// Reconstruct from shares 1, 3 and 5 (any 3 shares will do)
+const subset = shares.filter((share) => [1, 3, 5].includes(share.id));
+const recovered = reconstructSecret(subset, 3);
+// recovered holds the same bytes as secret
 ```
 
 ## API
 
+Everything is a named export of the package entry point. There is no default export.
+
+```typescript
+import {
+  splitSecret,
+  reconstructSecret,
+  ShamirError,
+  ShamirValidationError,
+  ShamirCryptoError,
+  type ShamirShare, // type only, erased at compile time
+} from '@forgesworn/shamir-core';
+```
+
 ### `splitSecret(secret, threshold, shares)`
 
 Split a secret into Shamir shares.
@@ -61,21 +100,62 @@ interface ShamirShare {
 }
 ```
 
-### Error Classes
+The interpolation uses only `id` and `data`. `threshold` is metadata for callers and encoders, but `reconstructSecret` cross-checks it against its own `threshold` argument whenever the share carries an integer value (see below). At runtime a share with a missing or non-integer `threshold` skips that check.
 
-- `ShamirError` -- base class
-- `ShamirValidationError` -- invalid parameters
-- `ShamirCryptoError` -- internal crypto errors
+### Errors
+
+All errors extend `Error`, and the two specific classes extend `ShamirError`, so `catch (err) { if (err instanceof ShamirError) ... }` covers every error the library throws on purpose.
+
+- `ShamirError`: base class, never thrown directly.
+- `ShamirValidationError`: invalid input. Every error the public functions can currently throw is this class.
+- `ShamirCryptoError`: internal arithmetic failure. Its only throw site is the GF(256) inverse of zero, which the duplicate-ID and ID-range checks make unreachable through the public API as currently implemented. It is exported so that callers can catch it, but do not expect to see it.
+
+`splitSecret` throws `ShamirValidationError` when:
+
+- `secret` is not a `Uint8Array` (a Node.js `Buffer` is accepted)
+- `secret` is empty
+- `threshold` or `shares` is not a safe integer
+- `threshold` is outside 2--255
+- `shares` is less than `threshold` or greater than 255
+
+`reconstructSecret` throws `ShamirValidationError` when:
+
+- its `threshold` argument is not a safe integer of at least 2
+- `shares` is not an array, or holds fewer than `threshold` shares (too few shares)
+- any of the first `threshold` entries is not an object, or has an `id` that is not an integer in 1--255 (so id 0 is rejected)
+- any of those entries has `data` that is not a `Uint8Array`
+- two of those entries share an `id` (duplicate IDs)
+- any of those entries has an integer `threshold` that differs from the `threshold` argument
+- the data of the first of those entries is empty
+- those entries have `data` of different lengths
+
+Only the first `threshold` entries are validated or used. Later entries are ignored, even if malformed.
+
+Some failures do not throw a Shamir error. If `crypto.getRandomValues` is unavailable, `splitSecret` throws whatever the runtime raises (a `ReferenceError` on Node.js 18 without the flag). Wrong data is not detected at all: see Security notes.
 
 ## Why This Library
 
 - **Zero dependencies.** No transitive supply chain. Only Web Crypto (`crypto.getRandomValues`).
 - **GF(256) log/exp table lookup.** O(1) field multiplication, same polynomial as AES (0x11b).
-- **Memory zeroing.** Polynomial coefficients are zeroed after use (defence-in-depth).
-- **Strict validation.** Duplicate share IDs, threshold mismatches, and malformed inputs are caught with typed errors.
+- **Memory zeroing.** Internal polynomial coefficients and random bytes are zeroed after use (defence-in-depth). Secrets, shares and results you hold are yours to zero; see Security notes.
+- **Strict validation.** Duplicate share IDs, out-of-range IDs, mismatched lengths, and malformed inputs are caught with typed errors. Threshold mismatches are caught when the share carries a threshold.
 - **No secret length limit.** Split any size secret. The maths has no ceiling.
 - **TypeScript-first.** Strict mode, `noUncheckedIndexedAccess`, full type declarations.
 
+## Security notes
+
+- **No integrity check.** Shares carry no checksum, MAC or signature. A corrupted or tampered share, shares from different splits, or a `threshold` argument that is too low for shares without `threshold` metadata all return wrong bytes without any error. Verify the reconstructed secret at the application level (for example with a hash, a MAC, or by successfully decrypting something with it).
+- **Not constant-time.** GF(256) multiplication uses log/exp table lookups indexed by secret-dependent bytes and returns early when an operand is zero. Timing and cache side channels are possible, and JavaScript runtimes give no constant-time guarantee in any case. Do not run it where an attacker can measure its timing at fine granularity.
+- **Zeroing is partial.** `splitSecret` zeroes its internal polynomial coefficient and random-byte buffers. It does not touch your `secret` array or the `data` of the shares it returns. `reconstructSecret` zeroes nothing: it reads the share `data` arrays in place and returns a new array that you own. Call `.fill(0)` on the secret, the shares and the reconstructed result when you have finished with them. Even then, the runtime may have copied the bytes elsewhere, and numeric intermediates cannot be zeroed.
+- **Randomness.** Coefficients come only from `crypto.getRandomValues`. There is no fallback generator and no seeding.
+- **What a share reveals.** `data` has the same length as the secret, and `id` and `threshold` are stored in the clear.
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+## More documentation
+
+[`llms.txt`](llms.txt) is a short machine-readable summary. [`llms-full.txt`](llms-full.txt) is the full reference with more examples and implementation details. Both ship in the npm package.
+
 ## Ecosystem
 
 | Package | Purpose |
@@ -83,6 +163,23 @@ interface ShamirShare {
 | [`@forgesworn/shamir-words`](https://github.com/forgesworn/shamir-words) | BIP-39 word encoding for shares (depends on this package) |
 | [`dominion-protocol`](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control (depends on this package) |
 
+## Part of the ForgeSworn Toolkit
+
+[ForgeSworn](https://forgesworn.dev) builds open-source cryptographic identity, payments, and coordination tools for Nostr.
+
+| Library | What it does |
+|---------|-------------|
+| [nsec-tree](https://github.com/forgesworn/nsec-tree) | Deterministic sub-identity derivation |
+| [ring-sig](https://github.com/forgesworn/ring-sig) | SAG/LSAG ring signatures on secp256k1 |
+| [range-proof](https://github.com/forgesworn/range-proof) | Pedersen commitment range proofs |
+| [canary-kit](https://github.com/forgesworn/canary-kit) | Coercion-resistant spoken verification |
+| [spoken-token](https://github.com/forgesworn/spoken-token) | Human-speakable verification tokens |
+| [toll-booth](https://github.com/forgesworn/toll-booth) | L402 payment middleware |
+| [geohash-kit](https://github.com/forgesworn/geohash-kit) | Geohash toolkit with polygon coverage |
+| [nostr-attestations](https://github.com/forgesworn/nostr-attestations) | NIP-VA verifiable attestations |
+| [dominion](https://github.com/forgesworn/dominion) | Epoch-based encrypted access control |
+| [nostr-veil](https://github.com/forgesworn/nostr-veil) | Privacy-preserving Web of Trust |
+
 ## Licence
 
 MIT

package/llms-full.txt

@@ -0,0 +1,269 @@
+# @forgesworn/shamir-core — Full AI Reference
+
+> GF(256) Shamir's Secret Sharing for TypeScript. Zero runtime dependencies.
+> Version: see package.json. Repository: https://github.com/forgesworn/shamir-core
+
+---
+
+## What It Is
+
+`@forgesworn/shamir-core` implements Shamir's Secret Sharing (SSS) over GF(256) — the 256-element Galois field. It splits any `Uint8Array` into n shares such that any threshold-sized subset can reconstruct the original, and fewer than threshold shares reveal nothing about the secret.
+
+**Use it when:**
+- You need threshold key splitting (e.g. split an encryption key across 5 custodians, require 3)
+- You want a zero-dependency cryptographic primitive with no supply chain risk
+- You need to split secrets of arbitrary byte length
+- You are building a BIP-39 mnemonic share scheme (see `@forgesworn/shamir-words`)
+- You are building epoch-based encrypted access control (see `dominion-protocol`)
+
+**Do not use it when:**
+- You need secret sharing over a large prime field (e.g. for integer secrets requiring >256 parties)
+- You need authenticated encryption of shares — this library provides information-theoretic secrecy but no integrity/authentication of share data; layer HMAC or AEAD on top if you need that
+
+---
+
+## Install
+
+```
+npm install @forgesworn/shamir-core
+```
+
+Requires Node.js >= 19, or any browser/runtime with a global `crypto.getRandomValues` (Bun, Deno, all modern browsers). `splitSecret` uses the bare global `crypto`, which Node.js only exposes without a flag from version 19. On Node.js 18 it throws a plain `ReferenceError` (not a Shamir error) unless Node is started with `--experimental-global-webcrypto`, or `globalThis.crypto ??= webcrypto` (from `node:crypto`) runs first. Those are workarounds, not a supported configuration. `reconstructSecret` does not use `crypto`.
+
+The package is ESM only: `package.json` has `"type": "module"` and its `exports` map has only an `import` condition. `require('@forgesworn/shamir-core')` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED` on every Node.js version, including those that can otherwise `require()` ES modules. From CommonJS, call `await import('@forgesworn/shamir-core')` inside an async function.
+
+All exports are named exports of the entry point (no default export):
+
+```typescript
+import {
+  splitSecret,
+  reconstructSecret,
+  ShamirError,
+  ShamirValidationError,
+  ShamirCryptoError,
+  type ShamirShare, // type only, erased at compile time
+} from '@forgesworn/shamir-core';
+```
+
+---
+
+## Full API Surface
+
+### splitSecret
+
+```typescript
+function splitSecret(
+  secret: Uint8Array,    // Secret bytes to split (any length, must be non-empty)
+  threshold: number,     // Minimum shares needed to reconstruct — integer in [2, 255]
+  shares: number,        // Total shares to create — integer in [threshold, 255]
+): ShamirShare[]
+```
+
+Splits `secret` into `shares` shares using a random degree-(threshold-1) polynomial over GF(256), evaluated independently for each byte of the secret. The constant term of each polynomial is the secret byte; the remaining threshold-1 coefficients are drawn from `crypto.getRandomValues`.
+
+Returns an array of `ShamirShare` objects with `id` values 1 through `shares`. Polynomial coefficients are zeroed from memory after each byte is processed.
+
+Throws `ShamirValidationError` when:
+- `secret` is not a `Uint8Array` (a Node.js `Buffer` is accepted)
+- `secret` is empty
+- `threshold` or `shares` is not a safe integer
+- `threshold` is outside [2, 255]
+- `shares` is less than `threshold` or greater than 255
+
+If `crypto.getRandomValues` is unavailable it throws whatever the runtime raises, not a Shamir error. It does not modify `secret`, and it does not zero `secret` or the returned shares.
+
+### reconstructSecret
+
+```typescript
+function reconstructSecret(
+  shares: ShamirShare[],  // At least threshold shares from the same split
+  threshold: number,      // The threshold used during splitting — integer >= 2
+): Uint8Array
+```
+
+Reconstructs the secret using Lagrange interpolation at x=0 over GF(256). Only the first `threshold` entries in `shares` are used; extras are silently ignored.
+
+Only the first `threshold` entries are validated or used; later entries are ignored even if malformed. It throws `ShamirValidationError` when:
+- the `threshold` argument is not a safe integer of at least 2
+- `shares` is not an array, or has fewer than `threshold` entries (too few shares)
+- any of the first `threshold` entries is not an object
+- an entry's `id` is not an integer in [1, 255] (so id 0 is rejected)
+- an entry's `data` is not a `Uint8Array`
+- two entries have the same `id` (duplicate IDs)
+- an entry's `threshold` is an integer that differs from the `threshold` argument (a missing or non-integer value skips this check)
+- the first entry's `data` is empty
+- the entries' `data` arrays have different lengths
+
+Each share's `id`, `threshold` and `data` are read once and only those snapshotted values are validated and used, which prevents TOCTOU attacks via Proxy objects with side-effecting getters.
+
+It does not zero anything: it reads the share `data` arrays in place and returns a new array that the caller owns.
+
+### ShamirShare
+
+```typescript
+interface ShamirShare {
+  id: number;        // 1–255 — the x-coordinate in GF(256) (evaluation point)
+  threshold: number; // 2–255 — minimum shares needed; metadata, not used in maths
+  data: Uint8Array;  // Same length as the original secret; the y-value for each byte
+}
+```
+
+### Error Classes
+
+```typescript
+class ShamirError extends Error {}            // Base class, never thrown directly
+class ShamirValidationError extends ShamirError {}  // Bad inputs, out-of-range params
+class ShamirCryptoError extends ShamirError {}      // Internal GF(256) zero-inverse guard
+```
+
+All error classes are exported and can be caught individually. Every deliberate throw from `splitSecret` and `reconstructSecret` is currently a `ShamirValidationError`. `ShamirCryptoError` is thrown only by the internal inverse of zero in GF(256); the duplicate-ID and ID-range checks make that unreachable through the public API as currently implemented, so it exists as a guard that callers can catch. Catching `ShamirError` covers both.
+
+---
+
+## GF(256) Implementation Details
+
+The library implements GF(2^8) — the field with 256 elements — using the same irreducible polynomial as AES:
+
+```
+p(x) = x^8 + x^4 + x^3 + x + 1  →  0x11b
+```
+
+**Generator:** 0x03
+
+**Arithmetic:**
+- Addition: XOR (`a ^ b`)
+- Multiplication: log/exp table lookup, O(1). It is not constant-time: it returns early when an operand is zero and the table indices depend on secret bytes
+- Inverse: `EXP[(255 - LOG[a]) % 255]`
+
+**Table construction:** Log and exp tables are built once at module load using generator 0x03 with carryless (peasant) multiplication. `EXP[255]` is aliased to `EXP[0]` to simplify modular index arithmetic.
+
+**Polynomial evaluation:** Horner's method — evaluates a degree-(threshold-1) polynomial at a given x using (threshold-1) multiplications and (threshold-1) additions.
+
+**Lagrange interpolation:** Reconstructs f(0) from threshold (x, y) pairs. The basis polynomial for each share is computed as the product of `x_j / (x_i XOR x_j)` for all j != i, all in GF(256).
+
+---
+
+## Security Notes
+
+**Memory zeroing:** Polynomial coefficients (the `coeffs` and `rand` arrays) are zeroed with `Uint8Array.fill(0)` in a `finally` block after each byte is processed. This is defence-in-depth and is partial. It does not guarantee the JavaScript engine retains no other copies, and numeric intermediates cannot be zeroed. The library does not zero the caller's `secret`, the `data` of the shares `splitSecret` returns, or the array `reconstructSecret` returns; call `.fill(0)` on those when finished.
+
+**Not constant-time:** GF(256) multiplication uses log/exp table lookups indexed by secret-dependent bytes and returns early when an operand is zero. Timing and cache side channels are possible, and JavaScript runtimes give no constant-time guarantee in any case.
+
+**Share IDs are 1-indexed:** Valid share IDs are 1–255. Zero is not a valid evaluation point in this scheme because f(0) is the secret itself.
+
+**No authentication:** Shares have no MAC or signature. A tampered share, shares from different splits, or a too-low `threshold` argument on shares without `threshold` metadata will silently produce a wrong secret, not an error. If you need share integrity, add a HMAC or encrypt shares with an AEAD cipher, and verify the reconstructed secret.
+
+**Threshold metadata:** The `threshold` field on `ShamirShare` is stored for bookkeeping by callers (e.g. `@forgesworn/shamir-words` encodes it in the BIP-39 share). It is not mathematically required: the interpolation only needs the `id` and `data`. `reconstructSecret` does compare it with its `threshold` argument, but only when the share's value is an integer. A missing or non-integer value skips the check.
+
+**TOCTOU hardening:** `reconstructSecret` reads `id`, `threshold`, and `data` once from each share object and validates and uses only those snapshotted values. This prevents a malicious Proxy from returning different values on subsequent reads.
+
+**What a share reveals:** `data` has the same length as the secret, and `id` and `threshold` are stored in the clear.
+
+**Randomness:** Relies solely on `crypto.getRandomValues` for coefficient generation. There is no fallback and no seeding — callers cannot influence the randomness.
+
+**No secret length limit:** The library imposes no upper bound on `secret.length`. Consumers may impose their own (e.g. `@forgesworn/shamir-words` limits secret length to what can be BIP-39 encoded).
+
+---
+
+## Code Examples
+
+### Basic split and reconstruct
+
+```typescript
+import { splitSecret, reconstructSecret } from '@forgesworn/shamir-core';
+
+// Split a 32-byte key: 5 shares, any 3 can reconstruct
+const secret = crypto.getRandomValues(new Uint8Array(32));
+const shares = splitSecret(secret, 3, 5);
+
+// shares[0] = { id: 1, threshold: 3, data: Uint8Array(32) }
+// shares[4] = { id: 5, threshold: 3, data: Uint8Array(32) }
+
+// Reconstruct from shares 2, 4 and 5 (any 3 shares, in any order)
+const subset = shares.filter((share) => [2, 4, 5].includes(share.id));
+const recovered = reconstructSecret(subset, 3);
+// recovered holds the same bytes as secret
+```
+
+### 2-of-2 split (both shares required)
+
+```typescript
+import { splitSecret, reconstructSecret } from '@forgesworn/shamir-core';
+
+const secret = new TextEncoder().encode('hunter2');
+const shares = splitSecret(secret, 2, 2);
+
+// Later:
+const recovered = reconstructSecret(shares, 2);
+console.log(new TextDecoder().decode(recovered)); // 'hunter2'
+```
+
+### Catching errors
+
+```typescript
+import {
+  splitSecret,
+  reconstructSecret,
+  ShamirError,
+  ShamirValidationError,
+} from '@forgesworn/shamir-core';
+
+const mySecret = new Uint8Array([1, 2, 3]);
+
+try {
+  const shares = splitSecret(mySecret, 3, 5);
+  const recovered = reconstructSecret(shares.slice(0, 2), 3); // only 2, needs 3
+} catch (err) {
+  if (err instanceof ShamirValidationError) {
+    console.error('Bad inputs:', err.message);
+  } else if (err instanceof ShamirError) {
+    console.error('Library error:', err.message); // ShamirCryptoError is not expected here
+  } else {
+    throw err; // for example a missing global crypto on Node.js 18
+  }
+}
+```
+
+### Checking share identity
+
+```typescript
+import { splitSecret } from '@forgesworn/shamir-core';
+
+// Share IDs are 1-indexed. After a 5-share split:
+const secret = new Uint8Array([1, 2, 3]);
+const shares = splitSecret(secret, 3, 5);
+console.log(shares.map(s => s.id)); // [1, 2, 3, 4, 5]
+
+// Do NOT use index 0 as an ID — it is not a valid evaluation point.
+// The id field on the share is authoritative.
+```
+
+---
+
+## Gotchas
+
+- **Share IDs start at 1, not 0.** The id field on each share is its GF(256) evaluation point. Zero is not used (f(0) is the secret itself). Always use `share.id`, not the array index.
+- **`reconstructSecret` uses only the first `threshold` shares.** If you pass 5 shares with threshold 3, only the first 3 are used. Order matters for which shares are consumed, but not for correctness — any threshold-sized subset of the original shares produces the same secret.
+- **Threshold mismatch is validated when the share carries a threshold.** If the integer `threshold` field on any of the first `threshold` shares does not match the `threshold` argument, a `ShamirValidationError` is thrown. A share with a missing or non-integer `threshold` skips the check, so a wrong `threshold` argument then silently returns wrong bytes.
+- **Only the first `threshold` shares are validated.** Later entries are ignored even if malformed.
+- **Duplicate share IDs are rejected.** Passing two shares with the same `id` throws `ShamirValidationError`.
+- **Inconsistent or empty data is rejected.** All shares used by `reconstructSecret` must have the same non-zero `data.length`.
+- **No authentication.** A corrupted share silently produces a wrong result. Layer integrity checks at the application level.
+- **Zeroing is the caller's job** for the secret, the shares and the reconstructed result.
+- **ESM only, and Node.js >= 19.** `require()` fails and Node.js 18 has no global `crypto` without a flag.
+
+---
+
+## Ecosystem
+
+| Package | Role |
+|---------|------|
+| `@forgesworn/shamir-core` | This library — raw GF(256) split/reconstruct |
+| `@forgesworn/shamir-words` | BIP-39 word encoding for shares (depends on this package) |
+| `dominion-protocol` | Epoch-based encrypted access control (depends on this package) |
+
+---
+
+## Licence
+
+MIT — https://github.com/forgesworn/shamir-core/blob/main/LICENSE

package/llms.txt

@@ -0,0 +1,101 @@
+# @forgesworn/shamir-core
+
+> GF(256) Shamir's Secret Sharing for TypeScript. Zero runtime dependencies.
+
+Full reference with more examples and implementation notes: llms-full.txt (shipped in this package, also at https://github.com/forgesworn/shamir-core/blob/main/llms-full.txt).
+
+## What It Does
+
+Splits a secret (any Uint8Array) into n shares where any threshold-sized subset can reconstruct the original. Uses Shamir's Secret Sharing over GF(256) with Lagrange interpolation.
+
+## Install
+
+npm install @forgesworn/shamir-core
+
+## Requirements
+
+- Node.js >= 19, or any runtime with a global crypto.getRandomValues (browsers, Deno, Bun). splitSecret uses the global crypto directly. On Node.js 18 it throws a ReferenceError unless Node is started with --experimental-global-webcrypto (workaround, not supported). reconstructSecret does not use crypto.
+- ESM only. require('@forgesworn/shamir-core') fails with ERR_PACKAGE_PATH_NOT_EXPORTED because the exports map has only an import condition. From CommonJS use `await import('@forgesworn/shamir-core')` inside an async function.
+
+## Imports
+
+All exports are named exports of the package entry point. There is no default export.
+
+```typescript
+import {
+  splitSecret,
+  reconstructSecret,
+  ShamirError,
+  ShamirValidationError,
+  ShamirCryptoError,
+  type ShamirShare, // type only
+} from '@forgesworn/shamir-core';
+```
+
+## API
+
+### splitSecret(secret: Uint8Array, threshold: number, shares: number): ShamirShare[]
+
+Split a secret into shares. threshold must be in [2, 255]. shares must be in [threshold, 255].
+
+```typescript
+import { splitSecret } from '@forgesworn/shamir-core';
+const shares = splitSecret(new Uint8Array([1, 2, 3]), 2, 3);
+// shares[0] = { id: 1, threshold: 2, data: Uint8Array }
+```
+
+### reconstructSecret(shares: ShamirShare[], threshold: number): Uint8Array
+
+Reconstruct from at least threshold shares. Uses first threshold shares only; later entries are neither used nor validated.
+
+```typescript
+import { splitSecret, reconstructSecret } from '@forgesworn/shamir-core';
+const shares = splitSecret(new Uint8Array([1, 2, 3]), 2, 3);
+const secret = reconstructSecret(shares.filter((s) => s.id !== 2), 2);
+// secret = Uint8Array [1, 2, 3]
+```
+
+### ShamirShare
+
+```typescript
+interface ShamirShare {
+  id: number;        // 1-255 (GF(256) evaluation point)
+  threshold: number; // 2-255 (minimum shares to reconstruct)
+  data: Uint8Array;  // same length as original secret
+}
+```
+
+The maths uses only id and data. reconstructSecret checks threshold against its threshold argument only when the share's threshold is an integer; a missing or non-integer value skips the check.
+
+### Errors
+
+- ShamirError (base, never thrown directly)
+- ShamirValidationError extends ShamirError (bad inputs; the only class the public functions currently throw)
+- ShamirCryptoError extends ShamirError (internal GF(256) zero-inverse guard; unreachable through the public API with current validation)
+
+splitSecret throws ShamirValidationError when: secret is not a Uint8Array or is empty; threshold or shares is not a safe integer; threshold is outside 2-255; shares is below threshold or above 255.
+
+reconstructSecret throws ShamirValidationError when, among the first threshold entries: the threshold argument is not an integer >= 2; shares is not an array or has fewer than threshold entries; an entry is not an object; an id is not an integer in 1-255 (id 0 is rejected); data is not a Uint8Array; two ids are equal; an integer threshold on a share differs from the argument; the first entry's data is empty; data lengths differ.
+
+If crypto.getRandomValues is missing, splitSecret throws the runtime's own error, not a Shamir error.
+
+## Key Properties
+
+- Zero runtime dependencies (only Web Crypto for randomness)
+- GF(256) with log/exp table lookup (same irreducible polynomial as AES: 0x11b)
+- Internal polynomial coefficients and random bytes zeroed after use; the caller's secret, the returned shares and the reconstructed secret are not zeroed by the library
+- Share IDs are 1-indexed (1-255), not 0-indexed
+- No secret length limit
+- Threshold metadata on shares is validated during reconstruction when present as an integer
+- Node.js >= 19, browsers, Deno, Bun
+
+## Security Notes
+
+- No integrity check: a wrong, corrupted or mixed-up share returns wrong bytes without an error. Verify the result at application level.
+- Not constant-time: table lookups are indexed by secret-dependent bytes and multiplication returns early on zero operands.
+- No fallback randomness: only crypto.getRandomValues.
+
+## Related Packages
+
+- @forgesworn/shamir-words: BIP-39 word encoding for shares
+- dominion-protocol: epoch-based encrypted access control

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forgesworn/shamir-core",
-  "version": "1.0.2",
-  "description": "GF(256) Shamir's Secret Sharing — split and reconstruct secrets with threshold schemes",
+  "version": "1.0.5",
+  "description": "GF(256) Shamir's Secret Sharing: split and reconstruct secrets with threshold schemes",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -12,7 +12,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "llms.txt",
+    "llms-full.txt"
   ],
   "scripts": {
     "build": "tsc",
@@ -31,7 +33,8 @@
     "galois-field"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "sideEffects": false,
   "author": "ForgeSworn (https://github.com/forgesworn)",
@@ -41,7 +44,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=18"
+    "node": ">=19"
   },
   "homepage": "https://github.com/forgesworn/shamir-core",
   "repository": {
@@ -52,14 +55,11 @@
     "url": "https://github.com/forgesworn/shamir-core/issues"
   },
   "devDependencies": {
-    "@semantic-release/changelog": "^6.0.3",
-    "@semantic-release/git": "^10.0.1",
-    "semantic-release": "^25.0.3",
     "typescript": "^5.7.0",
-    "vitest": "^4.1.0"
+    "vitest": "^5.0.0"
   },
   "funding": {
     "type": "lightning",
-    "url": "lightning:thedonkey@strike.me"
+    "url": "lightning:profusemeat89@walletofsatoshi.com"
   }
 }