@forgesworn/shamir-core 0.0.0-development

package/LICENCE

@@ -0,0 +1,21 @@
+MIT Licence
+
+Copyright (c) 2026 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/dist/index.d.ts

@@ -0,0 +1,31 @@
+export declare class ShamirError extends Error {
+    constructor(message: string);
+}
+export declare class ShamirValidationError extends ShamirError {
+    constructor(message: string);
+}
+export declare class ShamirCryptoError extends ShamirError {
+    constructor(message: string);
+}
+export interface ShamirShare {
+    id: number;
+    threshold: number;
+    data: Uint8Array;
+}
+/**
+ * Split a secret into shares using Shamir's Secret Sharing over GF(256).
+ *
+ * @param secret    The secret bytes to split (any length)
+ * @param threshold Minimum shares needed to reconstruct (>= 2)
+ * @param shares    Total number of shares to create (>= threshold, <= 255)
+ * @returns Array of ShamirShare objects
+ */
+export declare function splitSecret(secret: Uint8Array, threshold: number, shares: number): ShamirShare[];
+/**
+ * Reconstruct a secret from shares using Lagrange interpolation over GF(256).
+ *
+ * @param shares    Array of shares (at least `threshold` shares)
+ * @param threshold The threshold used during splitting
+ * @returns The reconstructed secret bytes
+ */
+export declare function reconstructSecret(shares: ShamirShare[], threshold: number): Uint8Array;

package/dist/index.js

@@ -0,0 +1,214 @@
+// Shamir's Secret Sharing over GF(256)
+// Split secrets into threshold-of-n shares using polynomial interpolation
+// Zero runtime dependencies — only Web Crypto for randomness
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class ShamirError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ShamirError';
+    }
+}
+export class ShamirValidationError extends ShamirError {
+    constructor(message) {
+        super(message);
+        this.name = 'ShamirValidationError';
+    }
+}
+export class ShamirCryptoError extends ShamirError {
+    constructor(message) {
+        super(message);
+        this.name = 'ShamirCryptoError';
+    }
+}
+// ---------------------------------------------------------------------------
+// GF(256) Arithmetic — irreducible polynomial 0x11b (same as AES)
+// ---------------------------------------------------------------------------
+const IRREDUCIBLE = 0x11b;
+const GENERATOR = 0x03;
+/** Log table: log_g(i) for i in [0..255]. LOG[0] is unused. */
+const LOG = new Uint8Array(256);
+/** Exp table: g^i for i in [0..255]. EXP[255] wraps to EXP[0]. */
+const EXP = new Uint8Array(256);
+/** Carryless multiplication used only during table construction */
+function gf256MulSlow(a, b) {
+    let result = 0;
+    let aa = a;
+    let bb = b;
+    while (bb > 0) {
+        if (bb & 1)
+            result ^= aa;
+        aa <<= 1;
+        if (aa & 0x100)
+            aa ^= IRREDUCIBLE;
+        bb >>= 1;
+    }
+    return result;
+}
+// Build log/exp tables at module load time using generator 0x03
+{
+    let val = 1;
+    for (let i = 0; i < 255; i++) {
+        EXP[i] = val;
+        LOG[val] = i;
+        val = gf256MulSlow(val, GENERATOR);
+    }
+    // Wrap: makes modular indexing simpler
+    EXP[255] = EXP[0];
+}
+/** Addition in GF(256) is XOR */
+function gf256Add(a, b) {
+    return a ^ b;
+}
+/** Multiplication in GF(256) using log/exp tables */
+function gf256Mul(a, b) {
+    if (a === 0 || b === 0)
+        return 0;
+    return EXP[(LOG[a] + LOG[b]) % 255];
+}
+/** Multiplicative inverse in GF(256) */
+function gf256Inv(a) {
+    if (a === 0)
+        throw new ShamirCryptoError('No inverse for zero in GF(256)');
+    return EXP[(255 - LOG[a]) % 255];
+}
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Evaluate a polynomial at x in GF(256) using Horner's method.
+ * coeffs[0] is the constant term (the secret byte).
+ */
+function evalPoly(coeffs, x) {
+    let result = 0;
+    for (let i = coeffs.length - 1; i >= 0; i--) {
+        result = gf256Add(gf256Mul(result, x), coeffs[i]);
+    }
+    return result;
+}
+/** Zero a byte array (defence-in-depth for secret material) */
+function zeroBytes(arr) {
+    arr.fill(0);
+}
+// ---------------------------------------------------------------------------
+// Shamir's Secret Sharing
+// ---------------------------------------------------------------------------
+/**
+ * Split a secret into shares using Shamir's Secret Sharing over GF(256).
+ *
+ * @param secret    The secret bytes to split (any length)
+ * @param threshold Minimum shares needed to reconstruct (>= 2)
+ * @param shares    Total number of shares to create (>= threshold, <= 255)
+ * @returns Array of ShamirShare objects
+ */
+export function splitSecret(secret, threshold, shares) {
+    if (!(secret instanceof Uint8Array)) {
+        throw new ShamirValidationError('Secret must be a Uint8Array');
+    }
+    if (secret.length === 0) {
+        throw new ShamirValidationError('Secret must not be empty');
+    }
+    if (!Number.isSafeInteger(threshold) || !Number.isSafeInteger(shares)) {
+        throw new ShamirValidationError('Threshold and shares must be safe integers');
+    }
+    if (threshold < 2) {
+        throw new ShamirValidationError('Threshold must be at least 2');
+    }
+    if (shares < threshold) {
+        throw new ShamirValidationError('Number of shares must be >= threshold');
+    }
+    if (shares > 255) {
+        throw new ShamirValidationError('Number of shares must be <= 255');
+    }
+    const secretLen = secret.length;
+    const result = [];
+    for (let i = 0; i < shares; i++) {
+        result.push({ id: i + 1, threshold, data: new Uint8Array(secretLen) });
+    }
+    for (let byteIdx = 0; byteIdx < secretLen; byteIdx++) {
+        const coeffs = new Uint8Array(threshold);
+        coeffs[0] = secret[byteIdx];
+        const rand = new Uint8Array(threshold - 1);
+        crypto.getRandomValues(rand);
+        for (let j = 1; j < threshold; j++) {
+            coeffs[j] = rand[j - 1];
+        }
+        for (let i = 0; i < shares; i++) {
+            result[i].data[byteIdx] = evalPoly(coeffs, i + 1);
+        }
+        zeroBytes(coeffs);
+        zeroBytes(rand);
+    }
+    return result;
+}
+/**
+ * Reconstruct a secret from shares using Lagrange interpolation over GF(256).
+ *
+ * @param shares    Array of shares (at least `threshold` shares)
+ * @param threshold The threshold used during splitting
+ * @returns The reconstructed secret bytes
+ */
+export function reconstructSecret(shares, threshold) {
+    if (!Number.isSafeInteger(threshold) || threshold < 2) {
+        throw new ShamirValidationError('Threshold must be an integer >= 2');
+    }
+    if (!Array.isArray(shares) || shares.length < threshold) {
+        throw new ShamirValidationError(`Need at least ${threshold} shares, got ${Array.isArray(shares) ? shares.length : 0}`);
+    }
+    // Use only the first `threshold` shares
+    const used = shares.slice(0, threshold);
+    // Validate share structure
+    const ids = new Set();
+    let firstThreshold;
+    for (const share of used) {
+        if (!share || typeof share !== 'object') {
+            throw new ShamirValidationError('Each share must be an object with id and data properties');
+        }
+        if (!Number.isInteger(share.id) || share.id < 1 || share.id > 255) {
+            throw new ShamirValidationError('Invalid share ID: must be an integer in [1, 255]');
+        }
+        if (!(share.data instanceof Uint8Array)) {
+            throw new ShamirValidationError('Share data must be a Uint8Array');
+        }
+        if (ids.has(share.id)) {
+            throw new ShamirValidationError('Duplicate share IDs detected — each share must have a unique ID');
+        }
+        if (firstThreshold === undefined) {
+            firstThreshold = share.threshold;
+        }
+        else if (share.threshold !== firstThreshold) {
+            throw new ShamirValidationError('Inconsistent threshold metadata across shares — shares may be from different splits');
+        }
+        ids.add(share.id);
+    }
+    const secretLen = used[0].data.length;
+    if (secretLen === 0) {
+        throw new ShamirValidationError('Share data must not be empty');
+    }
+    for (const share of used) {
+        if (share.data.length !== secretLen) {
+            throw new ShamirValidationError('Inconsistent share lengths — shares may be from different secrets');
+        }
+    }
+    const result = new Uint8Array(secretLen);
+    // Lagrange interpolation at x = 0 for each byte position
+    for (let byteIdx = 0; byteIdx < secretLen; byteIdx++) {
+        let value = 0;
+        for (let i = 0; i < threshold; i++) {
+            const xi = used[i].id;
+            const yi = used[i].data[byteIdx];
+            // Lagrange basis l_i(0) = product of x_j / (x_i ^ x_j) for j != i
+            let basis = 1;
+            for (let j = 0; j < threshold; j++) {
+                if (i === j)
+                    continue;
+                const xj = used[j].id;
+                basis = gf256Mul(basis, gf256Mul(xj, gf256Inv(gf256Add(xi, xj))));
+            }
+            value = gf256Add(value, gf256Mul(yi, basis));
+        }
+        result[byteIdx] = value;
+    }
+    return result;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@forgesworn/shamir-core",
+  "version": "0.0.0-development",
+  "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",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "shamir",
+    "secret-sharing",
+    "gf256",
+    "threshold",
+    "cryptography",
+    "key-splitting",
+    "galois-field"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "author": "ForgeSworn (https://github.com/forgesworn)",
+  "contributors": [
+    "TheCryptoDonkey (https://github.com/TheCryptoDonkey)",
+    "decented (https://github.com/decented)"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://github.com/forgesworn/shamir-core",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/forgesworn/shamir-core.git"
+  },
+  "bugs": {
+    "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"
+  },
+  "funding": {
+    "type": "lightning",
+    "url": "lightning:thedonkey@strike.me"
+  }
+}

package/src/index.ts

@@ -0,0 +1,264 @@
+// Shamir's Secret Sharing over GF(256)
+// Split secrets into threshold-of-n shares using polynomial interpolation
+// Zero runtime dependencies — only Web Crypto for randomness
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+export class ShamirError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ShamirError';
+  }
+}
+
+export class ShamirValidationError extends ShamirError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ShamirValidationError';
+  }
+}
+
+export class ShamirCryptoError extends ShamirError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ShamirCryptoError';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ShamirShare {
+  id: number;          // 1-255 (the x coordinate in GF(256))
+  threshold: number;   // 2-255 (minimum shares needed to reconstruct)
+  data: Uint8Array;    // evaluated polynomial bytes
+}
+
+// ---------------------------------------------------------------------------
+// GF(256) Arithmetic — irreducible polynomial 0x11b (same as AES)
+// ---------------------------------------------------------------------------
+
+const IRREDUCIBLE = 0x11b;
+const GENERATOR = 0x03;
+
+/** Log table: log_g(i) for i in [0..255]. LOG[0] is unused. */
+const LOG = new Uint8Array(256);
+/** Exp table: g^i for i in [0..255]. EXP[255] wraps to EXP[0]. */
+const EXP = new Uint8Array(256);
+
+/** Carryless multiplication used only during table construction */
+function gf256MulSlow(a: number, b: number): number {
+  let result = 0;
+  let aa = a;
+  let bb = b;
+  while (bb > 0) {
+    if (bb & 1) result ^= aa;
+    aa <<= 1;
+    if (aa & 0x100) aa ^= IRREDUCIBLE;
+    bb >>= 1;
+  }
+  return result;
+}
+
+// Build log/exp tables at module load time using generator 0x03
+{
+  let val = 1;
+  for (let i = 0; i < 255; i++) {
+    EXP[i] = val;
+    LOG[val] = i;
+    val = gf256MulSlow(val, GENERATOR);
+  }
+  // Wrap: makes modular indexing simpler
+  EXP[255] = EXP[0]!;
+}
+
+/** Addition in GF(256) is XOR */
+function gf256Add(a: number, b: number): number {
+  return a ^ b;
+}
+
+/** Multiplication in GF(256) using log/exp tables */
+function gf256Mul(a: number, b: number): number {
+  if (a === 0 || b === 0) return 0;
+  return EXP[(LOG[a]! + LOG[b]!) % 255]!;
+}
+
+/** Multiplicative inverse in GF(256) */
+function gf256Inv(a: number): number {
+  if (a === 0) throw new ShamirCryptoError('No inverse for zero in GF(256)');
+  return EXP[(255 - LOG[a]!) % 255]!;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate a polynomial at x in GF(256) using Horner's method.
+ * coeffs[0] is the constant term (the secret byte).
+ */
+function evalPoly(coeffs: Uint8Array, x: number): number {
+  let result = 0;
+  for (let i = coeffs.length - 1; i >= 0; i--) {
+    result = gf256Add(gf256Mul(result, x), coeffs[i]!);
+  }
+  return result;
+}
+
+/** Zero a byte array (defence-in-depth for secret material) */
+function zeroBytes(arr: Uint8Array): void {
+  arr.fill(0);
+}
+
+// ---------------------------------------------------------------------------
+// Shamir's Secret Sharing
+// ---------------------------------------------------------------------------
+
+/**
+ * Split a secret into shares using Shamir's Secret Sharing over GF(256).
+ *
+ * @param secret    The secret bytes to split (any length)
+ * @param threshold Minimum shares needed to reconstruct (>= 2)
+ * @param shares    Total number of shares to create (>= threshold, <= 255)
+ * @returns Array of ShamirShare objects
+ */
+export function splitSecret(
+  secret: Uint8Array,
+  threshold: number,
+  shares: number,
+): ShamirShare[] {
+  if (!(secret instanceof Uint8Array)) {
+    throw new ShamirValidationError('Secret must be a Uint8Array');
+  }
+  if (secret.length === 0) {
+    throw new ShamirValidationError('Secret must not be empty');
+  }
+  if (!Number.isSafeInteger(threshold) || !Number.isSafeInteger(shares)) {
+    throw new ShamirValidationError('Threshold and shares must be safe integers');
+  }
+  if (threshold < 2) {
+    throw new ShamirValidationError('Threshold must be at least 2');
+  }
+  if (shares < threshold) {
+    throw new ShamirValidationError('Number of shares must be >= threshold');
+  }
+  if (shares > 255) {
+    throw new ShamirValidationError('Number of shares must be <= 255');
+  }
+
+  const secretLen = secret.length;
+  const result: ShamirShare[] = [];
+
+  for (let i = 0; i < shares; i++) {
+    result.push({ id: i + 1, threshold, data: new Uint8Array(secretLen) });
+  }
+
+  for (let byteIdx = 0; byteIdx < secretLen; byteIdx++) {
+    const coeffs = new Uint8Array(threshold);
+    coeffs[0] = secret[byteIdx]!;
+
+    const rand = new Uint8Array(threshold - 1);
+    crypto.getRandomValues(rand);
+    for (let j = 1; j < threshold; j++) {
+      coeffs[j] = rand[j - 1]!;
+    }
+
+    for (let i = 0; i < shares; i++) {
+      result[i]!.data[byteIdx] = evalPoly(coeffs, i + 1);
+    }
+
+    zeroBytes(coeffs);
+    zeroBytes(rand);
+  }
+
+  return result;
+}
+
+/**
+ * Reconstruct a secret from shares using Lagrange interpolation over GF(256).
+ *
+ * @param shares    Array of shares (at least `threshold` shares)
+ * @param threshold The threshold used during splitting
+ * @returns The reconstructed secret bytes
+ */
+export function reconstructSecret(
+  shares: ShamirShare[],
+  threshold: number,
+): Uint8Array {
+  if (!Number.isSafeInteger(threshold) || threshold < 2) {
+    throw new ShamirValidationError('Threshold must be an integer >= 2');
+  }
+  if (!Array.isArray(shares) || shares.length < threshold) {
+    throw new ShamirValidationError(
+      `Need at least ${threshold} shares, got ${Array.isArray(shares) ? shares.length : 0}`,
+    );
+  }
+
+  // Use only the first `threshold` shares
+  const used = shares.slice(0, threshold);
+
+  // Validate share structure
+  const ids = new Set<number>();
+  let firstThreshold: number | undefined;
+  for (const share of used) {
+    if (!share || typeof share !== 'object') {
+      throw new ShamirValidationError('Each share must be an object with id and data properties');
+    }
+    if (!Number.isInteger(share.id) || share.id < 1 || share.id > 255) {
+      throw new ShamirValidationError('Invalid share ID: must be an integer in [1, 255]');
+    }
+    if (!(share.data instanceof Uint8Array)) {
+      throw new ShamirValidationError('Share data must be a Uint8Array');
+    }
+    if (ids.has(share.id)) {
+      throw new ShamirValidationError('Duplicate share IDs detected — each share must have a unique ID');
+    }
+    if (firstThreshold === undefined) {
+      firstThreshold = share.threshold;
+    } else if (share.threshold !== firstThreshold) {
+      throw new ShamirValidationError(
+        'Inconsistent threshold metadata across shares — shares may be from different splits',
+      );
+    }
+    ids.add(share.id);
+  }
+
+  const secretLen = used[0]!.data.length;
+  if (secretLen === 0) {
+    throw new ShamirValidationError('Share data must not be empty');
+  }
+  for (const share of used) {
+    if (share.data.length !== secretLen) {
+      throw new ShamirValidationError('Inconsistent share lengths — shares may be from different secrets');
+    }
+  }
+
+  const result = new Uint8Array(secretLen);
+
+  // Lagrange interpolation at x = 0 for each byte position
+  for (let byteIdx = 0; byteIdx < secretLen; byteIdx++) {
+    let value = 0;
+
+    for (let i = 0; i < threshold; i++) {
+      const xi = used[i]!.id;
+      const yi = used[i]!.data[byteIdx]!;
+
+      // Lagrange basis l_i(0) = product of x_j / (x_i ^ x_j) for j != i
+      let basis = 1;
+      for (let j = 0; j < threshold; j++) {
+        if (i === j) continue;
+        const xj = used[j]!.id;
+        basis = gf256Mul(basis, gf256Mul(xj, gf256Inv(gf256Add(xi, xj))));
+      }
+
+      value = gf256Add(value, gf256Mul(yi, basis));
+    }
+
+    result[byteIdx] = value;
+  }
+
+  return result;
+}