llms.txt

# @forgesworn/shamir-core

> GF(256) Shamir's Secret Sharing for TypeScript. Zero runtime dependencies.

## 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

## 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.

```typescript
import { reconstructSecret } from '@forgesworn/shamir-core';
const secret = reconstructSecret([shares[0], shares[2]], 2);
```

### 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
}
```

### Errors

- ShamirError (base)
- ShamirValidationError extends ShamirError (bad inputs)
- ShamirCryptoError extends ShamirError (internal crypto)

## Key Properties

- Zero runtime dependencies (only Web Crypto for randomness)
- GF(256) with log/exp table lookup (same irreducible polynomial as AES: 0x11b)
- Polynomial coefficients zeroed after use
- Share IDs are 1-indexed (1-255), not 0-indexed
- No secret length limit
- Threshold metadata on shares is validated during reconstruction
- Node.js >= 18, browsers, Deno, Bun

## Related Packages

- @forgesworn/shamir-words: BIP-39 word encoding for shares
- dominion-protocol: epoch-based encrypted access control