@noy-db/on-shamir 0.1.0-pre.3

package/dist/index.d.cts

@@ -0,0 +1,230 @@
+/**
+ * Arithmetic in the Galois field GF(2^8), represented as bytes 0..255.
+ *
+ * Used by Shamir Secret Sharing for byte-wise polynomial operations.
+ * Addition is XOR; multiplication uses precomputed log/exp tables
+ * against the primitive element 0x03 with irreducible polynomial
+ * 0x11b (x^8 + x^4 + x^3 + x + 1 — the AES polynomial).
+ *
+ * Constant-time is NOT a goal here — for secret sharing, the threat
+ * model assumes the combining device is trusted during
+ * reconstruction. If that assumption is wrong, no library-level
+ * constant-time hedge protects the plaintext anyway.
+ */
+/** Addition in GF(2^8) is XOR. */
+declare function gfAdd(a: number, b: number): number;
+/** Multiplication in GF(2^8). Returns 0 if either operand is 0. */
+declare function gfMul(a: number, b: number): number;
+/** Multiplicative inverse in GF(2^8). Throws on 0 (no inverse exists). */
+declare function gfInv(a: number): number;
+/** Division in GF(2^8). Throws on divide-by-zero. */
+declare function gfDiv(a: number, b: number): number;
+/**
+ * Evaluate a polynomial with coefficients `coeffs[0] + coeffs[1]*x + ...`
+ * at point `x` in GF(2^8) via Horner's method.
+ */
+declare function gfPolyEval(coeffs: readonly number[], x: number): number;
+/**
+ * Lagrange interpolation at x=0, given k distinct points `(xi, yi)`.
+ *
+ * Returns the constant term of the unique degree-(k-1) polynomial
+ * through those points — equal to the original secret byte for
+ * Shamir's construction.
+ */
+declare function lagrangeInterpolateAtZero(points: readonly [number, number][]): number;
+
+/**
+ * Shamir Secret Sharing over GF(2^8), byte-wise.
+ *
+ * For each byte of the secret, construct a random polynomial of
+ * degree k-1 whose constant term is the byte. Each share is a value
+ * of that polynomial at a distinct x-coordinate in 1..255. Any K of
+ * the N shares recombines the original bytes via Lagrange interpolation
+ * at x=0.
+ *
+ * x=0 is reserved (it would directly reveal the secret). x-coordinates
+ * are chosen from 1..255 ensuring distinctness.
+ */
+/**
+ * Split a secret into N shares. Any K of them reconstructs the secret;
+ * fewer than K leaks zero bits.
+ *
+ * @param secret - The bytes to share (e.g., a 32-byte KEK).
+ * @param k - Threshold (min shares needed to reconstruct). Must be >= 2.
+ * @param n - Total shares to produce. Must be >= k and <= 255.
+ * @param randomBytes - RNG function returning N random bytes. Defaults to
+ *   `crypto.getRandomValues`. Injectable for deterministic tests.
+ * @returns An array of `n` shares. Each share has an x-coordinate + y-bytes
+ *   parallel to the secret bytes.
+ */
+declare function splitSecret(secret: Uint8Array, k: number, n: number, randomBytes?: (count: number) => Uint8Array): RawShare[];
+/**
+ * Reconstruct a secret from K or more shares.
+ *
+ * Uses the first K shares provided; additional shares are ignored.
+ * Shares must agree on secret length and x-coordinates must be
+ * distinct (checked; throws on mismatch).
+ */
+declare function combineSecret(shares: readonly RawShare[]): Uint8Array;
+/** A raw Shamir share before serialisation. */
+interface RawShare {
+    /** x-coordinate in GF(2^8), 1..255. Zero is disallowed (it would reveal the secret). */
+    readonly x: number;
+    /** y-bytes — one per byte of the secret. */
+    readonly y: Uint8Array;
+    /** Threshold used at split time. */
+    readonly k: number;
+    /** Total shares at split time. */
+    readonly n: number;
+}
+
+/**
+ * Share serialisation — raw bytes, Base32 for printing, and JSON for
+ * structured transport (e.g. storing inside another on-* keyring).
+ *
+ * Binary layout (fixed header + secret-length y-bytes):
+ *
+ * ```
+ *   offset  size  field
+ *   0       1     version (= 1)
+ *   1       1     x-coordinate (1..255)
+ *   2       1     k (threshold)
+ *   3       1     n (total)
+ *   4       2     byteLength (big-endian uint16) — should equal y-length
+ *   6+      L     y-bytes (L = byteLength)
+ * ```
+ *
+ * Base32 adds a 26-character ULID `shareId` prefix + version/k/n
+ * metadata for human-readable diagnostics.
+ */
+
+/** Serialise a raw share into its canonical binary form. */
+declare function encodeShareBytes(share: RawShare): Uint8Array;
+/** Parse binary share bytes back into a structured share. */
+declare function decodeShareBytes(bytes: Uint8Array): RawShare;
+/**
+ * Encode a share as a Base32 string with hyphenated groups of 4.
+ *
+ * Output format: `SHAMIR_S{x}_K{k}N{n}__<base32-groups-of-4>`
+ *
+ * The prefix is not fed into the decoder — it's for eye-readability at a
+ * glance (share-number / threshold / total). The `SHAMIR` tag + `_`
+ * separators are non-Base32 characters (Base32 alphabet is A-Z2-7
+ * only), so the decoder can strip everything up to and including the
+ * last `_` before the payload. The metadata is also encoded in the
+ * share bytes themselves; the prefix is redundant-but-useful.
+ */
+declare function encodeShareBase32(share: RawShare): string;
+/**
+ * Parse a Base32 share string back into a structured share. Tolerates
+ * hyphens, whitespace, lowercase, and the optional prefix produced by
+ * `encodeShareBase32`. The metadata prefix is informational; actual
+ * share data comes from the binary bytes after the last `_`.
+ */
+declare function decodeShareBase32(input: string): RawShare;
+/**
+ * JSON-friendly form for structured storage (e.g. stash inside another
+ * on-* keyring entry, or pass over `postMessage`).
+ */
+interface ShareJSON {
+    readonly v: 1;
+    readonly x: number;
+    readonly k: number;
+    readonly n: number;
+    readonly y: string;
+}
+declare function encodeShareJSON(share: RawShare): ShareJSON;
+declare function decodeShareJSON(json: ShareJSON): RawShare;
+
+/**
+ * **@noy-db/on-shamir** — k-of-n Shamir Secret Sharing of the vault KEK.
+ *
+ * Any K of N enrolled shares recombines the original KEK; fewer than
+ * K leaks zero bits. Unlike naive multi-passphrase schemes, each
+ * share can be protected by ANY other `@noy-db/on-*` method — share
+ * 1 under a WebAuthn passkey, share 2 under an OIDC login, share 3
+ * on paper in a safe. This composability is the defining feature.
+ *
+ * Part of the `@noy-db/on-*` authentication family.
+ *
+ * ## Math
+ *
+ * Shamir Secret Sharing over GF(2^8), byte-wise. For each byte of the
+ * secret, construct a random polynomial of degree k-1 with the byte
+ * as the constant term. Each share is a value of that polynomial at
+ * a distinct x-coordinate. Lagrange interpolation at x=0 recovers
+ * the byte. Zero cryptographic dependencies — pure math in
+ * `gf256.ts` and `shamir.ts`.
+ *
+ * ## Threat model
+ *
+ * Protects against:
+ *   - Up to K-1 colluding share holders (mathematically — fewer than K shares reveals zero bits)
+ *   - Loss of up to N-K shares
+ *
+ * Does NOT protect against:
+ *   - K colluding share holders (by design — that's the threshold contract)
+ *   - Device compromise of the combining machine during reconstruction
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import {
+ *   splitKEK,
+ *   combineKEK,
+ *   encodeShareBase32,
+ *   decodeShareBase32,
+ * } from '@noy-db/on-shamir'
+ *
+ * // ENROLL — user has unlocked the vault with passphrase; now create a 2-of-3 split
+ * const shares = await splitKEK(currentKEK, { k: 2, n: 3 })
+ * const shareStrings = shares.map(encodeShareBase32)
+ * // Distribute each shareString to a different holder via any on-* method
+ *
+ * // UNLOCK — collect 2 of the 3 shares and combine
+ * const collected = [decodeShareBase32(shareA), decodeShareBase32(shareB)]
+ * const kek = await combineKEK(collected)
+ * // kek is now a non-extractable CryptoKey usable as the vault's KEK
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface SplitKEKOptions {
+    /** Threshold — minimum shares needed to reconstruct. Must be >= 2. */
+    readonly k: number;
+    /** Total shares. Must satisfy k <= n <= 255. */
+    readonly n: number;
+}
+/**
+ * Split the given KEK into N Shamir shares.
+ *
+ * The KEK must be extractable (so the raw bytes can be read for the
+ * split operation). The returned `RawShare[]` contains the raw share
+ * material — serialise each via `encodeShareBase32` / `encodeShareJSON`
+ * before distributing.
+ *
+ * The caller is responsible for:
+ * 1. Distributing the shares to their holders.
+ * 2. Writing an audit-ledger entry recording the enrollment (including
+ *    the `k`, `n`, and share x-coordinates — not the share material).
+ * 3. Securely zeroing any in-memory share/secret material after
+ *    serialisation.
+ */
+declare function splitKEK(kek: CryptoKey, options: SplitKEKOptions): Promise<RawShare[]>;
+/**
+ * Reconstruct the KEK from K or more shares.
+ *
+ * Returns a non-extractable `CryptoKey` ready to use as the vault's
+ * KEK. Internal secret bytes are zeroed after the CryptoKey is
+ * imported.
+ *
+ * Throws:
+ *   - if fewer than K shares are provided
+ *   - if shares have mismatched lengths (likely indicating shares from
+ *     different enrollments were mixed)
+ *   - if duplicate x-coordinates are detected
+ */
+declare function combineKEK(shares: readonly RawShare[]): Promise<CryptoKey>;
+
+export { type RawShare, type ShareJSON, type SplitKEKOptions, combineKEK, combineSecret, decodeShareBase32, decodeShareBytes, decodeShareJSON, encodeShareBase32, encodeShareBytes, encodeShareJSON, gfAdd, gfDiv, gfInv, gfMul, gfPolyEval, lagrangeInterpolateAtZero, splitKEK, splitSecret };

package/dist/index.d.ts

@@ -0,0 +1,230 @@
+/**
+ * Arithmetic in the Galois field GF(2^8), represented as bytes 0..255.
+ *
+ * Used by Shamir Secret Sharing for byte-wise polynomial operations.
+ * Addition is XOR; multiplication uses precomputed log/exp tables
+ * against the primitive element 0x03 with irreducible polynomial
+ * 0x11b (x^8 + x^4 + x^3 + x + 1 — the AES polynomial).
+ *
+ * Constant-time is NOT a goal here — for secret sharing, the threat
+ * model assumes the combining device is trusted during
+ * reconstruction. If that assumption is wrong, no library-level
+ * constant-time hedge protects the plaintext anyway.
+ */
+/** Addition in GF(2^8) is XOR. */
+declare function gfAdd(a: number, b: number): number;
+/** Multiplication in GF(2^8). Returns 0 if either operand is 0. */
+declare function gfMul(a: number, b: number): number;
+/** Multiplicative inverse in GF(2^8). Throws on 0 (no inverse exists). */
+declare function gfInv(a: number): number;
+/** Division in GF(2^8). Throws on divide-by-zero. */
+declare function gfDiv(a: number, b: number): number;
+/**
+ * Evaluate a polynomial with coefficients `coeffs[0] + coeffs[1]*x + ...`
+ * at point `x` in GF(2^8) via Horner's method.
+ */
+declare function gfPolyEval(coeffs: readonly number[], x: number): number;
+/**
+ * Lagrange interpolation at x=0, given k distinct points `(xi, yi)`.
+ *
+ * Returns the constant term of the unique degree-(k-1) polynomial
+ * through those points — equal to the original secret byte for
+ * Shamir's construction.
+ */
+declare function lagrangeInterpolateAtZero(points: readonly [number, number][]): number;
+
+/**
+ * Shamir Secret Sharing over GF(2^8), byte-wise.
+ *
+ * For each byte of the secret, construct a random polynomial of
+ * degree k-1 whose constant term is the byte. Each share is a value
+ * of that polynomial at a distinct x-coordinate in 1..255. Any K of
+ * the N shares recombines the original bytes via Lagrange interpolation
+ * at x=0.
+ *
+ * x=0 is reserved (it would directly reveal the secret). x-coordinates
+ * are chosen from 1..255 ensuring distinctness.
+ */
+/**
+ * Split a secret into N shares. Any K of them reconstructs the secret;
+ * fewer than K leaks zero bits.
+ *
+ * @param secret - The bytes to share (e.g., a 32-byte KEK).
+ * @param k - Threshold (min shares needed to reconstruct). Must be >= 2.
+ * @param n - Total shares to produce. Must be >= k and <= 255.
+ * @param randomBytes - RNG function returning N random bytes. Defaults to
+ *   `crypto.getRandomValues`. Injectable for deterministic tests.
+ * @returns An array of `n` shares. Each share has an x-coordinate + y-bytes
+ *   parallel to the secret bytes.
+ */
+declare function splitSecret(secret: Uint8Array, k: number, n: number, randomBytes?: (count: number) => Uint8Array): RawShare[];
+/**
+ * Reconstruct a secret from K or more shares.
+ *
+ * Uses the first K shares provided; additional shares are ignored.
+ * Shares must agree on secret length and x-coordinates must be
+ * distinct (checked; throws on mismatch).
+ */
+declare function combineSecret(shares: readonly RawShare[]): Uint8Array;
+/** A raw Shamir share before serialisation. */
+interface RawShare {
+    /** x-coordinate in GF(2^8), 1..255. Zero is disallowed (it would reveal the secret). */
+    readonly x: number;
+    /** y-bytes — one per byte of the secret. */
+    readonly y: Uint8Array;
+    /** Threshold used at split time. */
+    readonly k: number;
+    /** Total shares at split time. */
+    readonly n: number;
+}
+
+/**
+ * Share serialisation — raw bytes, Base32 for printing, and JSON for
+ * structured transport (e.g. storing inside another on-* keyring).
+ *
+ * Binary layout (fixed header + secret-length y-bytes):
+ *
+ * ```
+ *   offset  size  field
+ *   0       1     version (= 1)
+ *   1       1     x-coordinate (1..255)
+ *   2       1     k (threshold)
+ *   3       1     n (total)
+ *   4       2     byteLength (big-endian uint16) — should equal y-length
+ *   6+      L     y-bytes (L = byteLength)
+ * ```
+ *
+ * Base32 adds a 26-character ULID `shareId` prefix + version/k/n
+ * metadata for human-readable diagnostics.
+ */
+
+/** Serialise a raw share into its canonical binary form. */
+declare function encodeShareBytes(share: RawShare): Uint8Array;
+/** Parse binary share bytes back into a structured share. */
+declare function decodeShareBytes(bytes: Uint8Array): RawShare;
+/**
+ * Encode a share as a Base32 string with hyphenated groups of 4.
+ *
+ * Output format: `SHAMIR_S{x}_K{k}N{n}__<base32-groups-of-4>`
+ *
+ * The prefix is not fed into the decoder — it's for eye-readability at a
+ * glance (share-number / threshold / total). The `SHAMIR` tag + `_`
+ * separators are non-Base32 characters (Base32 alphabet is A-Z2-7
+ * only), so the decoder can strip everything up to and including the
+ * last `_` before the payload. The metadata is also encoded in the
+ * share bytes themselves; the prefix is redundant-but-useful.
+ */
+declare function encodeShareBase32(share: RawShare): string;
+/**
+ * Parse a Base32 share string back into a structured share. Tolerates
+ * hyphens, whitespace, lowercase, and the optional prefix produced by
+ * `encodeShareBase32`. The metadata prefix is informational; actual
+ * share data comes from the binary bytes after the last `_`.
+ */
+declare function decodeShareBase32(input: string): RawShare;
+/**
+ * JSON-friendly form for structured storage (e.g. stash inside another
+ * on-* keyring entry, or pass over `postMessage`).
+ */
+interface ShareJSON {
+    readonly v: 1;
+    readonly x: number;
+    readonly k: number;
+    readonly n: number;
+    readonly y: string;
+}
+declare function encodeShareJSON(share: RawShare): ShareJSON;
+declare function decodeShareJSON(json: ShareJSON): RawShare;
+
+/**
+ * **@noy-db/on-shamir** — k-of-n Shamir Secret Sharing of the vault KEK.
+ *
+ * Any K of N enrolled shares recombines the original KEK; fewer than
+ * K leaks zero bits. Unlike naive multi-passphrase schemes, each
+ * share can be protected by ANY other `@noy-db/on-*` method — share
+ * 1 under a WebAuthn passkey, share 2 under an OIDC login, share 3
+ * on paper in a safe. This composability is the defining feature.
+ *
+ * Part of the `@noy-db/on-*` authentication family.
+ *
+ * ## Math
+ *
+ * Shamir Secret Sharing over GF(2^8), byte-wise. For each byte of the
+ * secret, construct a random polynomial of degree k-1 with the byte
+ * as the constant term. Each share is a value of that polynomial at
+ * a distinct x-coordinate. Lagrange interpolation at x=0 recovers
+ * the byte. Zero cryptographic dependencies — pure math in
+ * `gf256.ts` and `shamir.ts`.
+ *
+ * ## Threat model
+ *
+ * Protects against:
+ *   - Up to K-1 colluding share holders (mathematically — fewer than K shares reveals zero bits)
+ *   - Loss of up to N-K shares
+ *
+ * Does NOT protect against:
+ *   - K colluding share holders (by design — that's the threshold contract)
+ *   - Device compromise of the combining machine during reconstruction
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import {
+ *   splitKEK,
+ *   combineKEK,
+ *   encodeShareBase32,
+ *   decodeShareBase32,
+ * } from '@noy-db/on-shamir'
+ *
+ * // ENROLL — user has unlocked the vault with passphrase; now create a 2-of-3 split
+ * const shares = await splitKEK(currentKEK, { k: 2, n: 3 })
+ * const shareStrings = shares.map(encodeShareBase32)
+ * // Distribute each shareString to a different holder via any on-* method
+ *
+ * // UNLOCK — collect 2 of the 3 shares and combine
+ * const collected = [decodeShareBase32(shareA), decodeShareBase32(shareB)]
+ * const kek = await combineKEK(collected)
+ * // kek is now a non-extractable CryptoKey usable as the vault's KEK
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+interface SplitKEKOptions {
+    /** Threshold — minimum shares needed to reconstruct. Must be >= 2. */
+    readonly k: number;
+    /** Total shares. Must satisfy k <= n <= 255. */
+    readonly n: number;
+}
+/**
+ * Split the given KEK into N Shamir shares.
+ *
+ * The KEK must be extractable (so the raw bytes can be read for the
+ * split operation). The returned `RawShare[]` contains the raw share
+ * material — serialise each via `encodeShareBase32` / `encodeShareJSON`
+ * before distributing.
+ *
+ * The caller is responsible for:
+ * 1. Distributing the shares to their holders.
+ * 2. Writing an audit-ledger entry recording the enrollment (including
+ *    the `k`, `n`, and share x-coordinates — not the share material).
+ * 3. Securely zeroing any in-memory share/secret material after
+ *    serialisation.
+ */
+declare function splitKEK(kek: CryptoKey, options: SplitKEKOptions): Promise<RawShare[]>;
+/**
+ * Reconstruct the KEK from K or more shares.
+ *
+ * Returns a non-extractable `CryptoKey` ready to use as the vault's
+ * KEK. Internal secret bytes are zeroed after the CryptoKey is
+ * imported.
+ *
+ * Throws:
+ *   - if fewer than K shares are provided
+ *   - if shares have mismatched lengths (likely indicating shares from
+ *     different enrollments were mixed)
+ *   - if duplicate x-coordinates are detected
+ */
+declare function combineKEK(shares: readonly RawShare[]): Promise<CryptoKey>;
+
+export { type RawShare, type ShareJSON, type SplitKEKOptions, combineKEK, combineSecret, decodeShareBase32, decodeShareBytes, decodeShareJSON, encodeShareBase32, encodeShareBytes, encodeShareJSON, gfAdd, gfDiv, gfInv, gfMul, gfPolyEval, lagrangeInterpolateAtZero, splitKEK, splitSecret };