@bcts/shamir 1.0.0-alpha.9 → 1.0.0-beta.0

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@bcts/shamir",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0-beta.0",
   "type": "module",
   "description": "Blockchain Commons Shamir Secret Sharing for TypeScript",
   "license": "BSD-2-Clause-Patent",
-  "author": "Leonardo Custodio <leonardo@custodio.me>",
-  "homepage": "https://github.com/leonardocustodio/bcts",
+  "author": "Parity Technologies <admin@parity.io> (https://parity.io)",
+  "homepage": "https://bcts.dev",
   "repository": {
     "type": "git",
-    "url": "https://github.com/leonardocustodio/bcts",
+    "url": "https://github.com/paritytech/bcts",
     "directory": "packages/shamir"
   },
   "bugs": {
-    "url": "https://github.com/leonardocustodio/bcts/issues"
+    "url": "https://github.com/paritytech/bcts/issues"
   },
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -33,11 +33,10 @@
   ],
   "scripts": {
     "build": "tsdown",
-    "dev": "tsdown --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint": "eslint 'src/**/*.ts'",
-    "lint:fix": "eslint 'src/**/*.ts' --fix",
+    "lint": "eslint 'src/**/*.ts' 'tests/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' 'tests/**/*.ts' --fix",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "docs": "typedoc",
@@ -56,19 +55,19 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@bcts/crypto": "^1.0.0-alpha.9",
-    "@bcts/rand": "^1.0.0-alpha.9"
+    "@bcts/crypto": "^1.0.0-beta.0",
+    "@bcts/rand": "^1.0.0-beta.0"
   },
   "devDependencies": {
     "@bcts/eslint": "^0.1.0",
     "@bcts/tsconfig": "^0.1.0",
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^24.10.2",
-    "eslint": "^9.39.1",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.6.0",
+    "eslint": "^10.2.1",
     "ts-node": "^10.9.2",
-    "tsdown": "^0.17.2",
-    "typedoc": "^0.28.15",
-    "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "tsdown": "^0.21.0",
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   }
 }

package/src/error.ts

@@ -1,11 +1,33 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from bc-shamir-rust/src/error.rs
 
 /**
  * Error types for Shamir secret sharing operations.
+ *
+ * Each variant mirrors a corresponding `Error::*` enum in
+ * `bc-shamir-rust/src/error.rs` with the same trigger conditions and the
+ * same default `Display` strings.
+ *
+ * Note on `InterpolationFailure`: this variant is **reserved but
+ * unreachable** in both the Rust and TypeScript implementations.
+ * `interpolate()` in `interpolate.ts` never actually returns / throws an
+ * interpolation failure today — the Lagrange-basis math always succeeds
+ * for any well-formed input. The variant is kept for forward
+ * compatibility (e.g. should a future revision add input validation that
+ * could reject pathological cases) and to keep the TS error type a 1:1
+ * mirror of Rust's `Error` enum.
  */
 export enum ShamirErrorType {
   SecretTooLong = "SecretTooLong",
   TooManyShares = "TooManyShares",
+  /**
+   * Reserved / unreachable in both Rust and TS today. See enum doc above.
+   */
   InterpolationFailure = "InterpolationFailure",
   ChecksumFailure = "ChecksumFailure",
   SecretTooShort = "SecretTooShort",
@@ -48,4 +70,12 @@ export class ShamirError extends Error {
   }
 }
 
+/**
+ * Mirrors Rust's `Result<T, Error>` for API parity.
+ *
+ * The TypeScript port surfaces failures by throwing `ShamirError`
+ * instances rather than returning a sum type, so this alias is a no-op
+ * (`ShamirResult<T>` ≡ `T`). It is kept so signatures published in
+ * `@bcts/shamir` remain visually parallel to their Rust counterparts.
+ */
 export type ShamirResult<T> = T;

package/src/hazmat.ts

@@ -1,8 +1,35 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from bc-shamir-rust/src/hazmat.rs
-// GF(2^8) bitsliced polynomial operations for Shamir secret sharing
+// GF(2^8) bitsliced polynomial operations for Shamir secret sharing.
+//
+// **Defensive arity guards.** Each helper here checks its array-length
+// preconditions (`r.length === 8`, `x.length >= 32`, …) and throws a
+// plain `Error` on violation. These guards mirror Rust's slice-indexing
+// `panic!` semantics — they signal an internal *contract violation*
+// (programmer error), not an end-user input error, and are deliberately
+// **not** elevated to `ShamirError`: that type carries variants for
+// recoverable, user-facing failures of the public `splitSecret` /
+// `recoverSecret` APIs, and has no variant matching "wrong array arity".
+// The public Shamir API never triggers these guards in normal use.
 
 import { memzero } from "@bcts/crypto";
 
+/**
+ * Internal contract guard. Mirrors a Rust `assert!(condition, message)`
+ * panic on the boundary between hazmat helpers — kept as a bare `Error`
+ * so it cannot be confused with a `ShamirError` from the public API.
+ */
+function assertContract(condition: boolean, message: string): void {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
 /**
  * Convert an array of bytes into a bitsliced representation.
  * Takes the first 32 bytes from x and produces 8 u32 values.
@@ -11,12 +38,8 @@ import { memzero } from "@bcts/crypto";
  * @param x - Input array of at least 32 bytes
  */
 export function bitslice(r: Uint32Array, x: Uint8Array): void {
-  if (x.length < 32) {
-    throw new Error("bitslice: input must be at least 32 bytes");
-  }
-  if (r.length !== 8) {
-    throw new Error("bitslice: output must have 8 elements");
-  }
+  assertContract(x.length >= 32, "bitslice: input must be at least 32 bytes");
+  assertContract(r.length === 8, "bitslice: output must have 8 elements");
 
   memzero(r);
 
@@ -36,12 +59,8 @@ export function bitslice(r: Uint32Array, x: Uint8Array): void {
  * @param x - Input array of 8 u32 values (bitsliced representation)
  */
 export function unbitslice(r: Uint8Array, x: Uint32Array): void {
-  if (r.length < 32) {
-    throw new Error("unbitslice: output must be at least 32 bytes");
-  }
-  if (x.length !== 8) {
-    throw new Error("unbitslice: input must have 8 elements");
-  }
+  assertContract(r.length >= 32, "unbitslice: output must be at least 32 bytes");
+  assertContract(x.length === 8, "unbitslice: input must have 8 elements");
 
   memzero(r.subarray(0, 32));
 
@@ -61,9 +80,7 @@ export function unbitslice(r: Uint8Array, x: Uint32Array): void {
  * @param x - Byte value to set in all positions
  */
 export function bitsliceSetall(r: Uint32Array, x: number): void {
-  if (r.length !== 8) {
-    throw new Error("bitsliceSetall: output must have 8 elements");
-  }
+  assertContract(r.length === 8, "bitsliceSetall: output must have 8 elements");
 
   for (let idx = 0; idx < 8; idx++) {
     // JavaScript needs special handling for the arithmetic right shift
@@ -83,9 +100,7 @@ export function bitsliceSetall(r: Uint32Array, x: number): void {
  * @param x - Second operand
  */
 export function gf256Add(r: Uint32Array, x: Uint32Array): void {
-  if (r.length !== 8 || x.length !== 8) {
-    throw new Error("gf256Add: arrays must have 8 elements");
-  }
+  assertContract(r.length === 8 && x.length === 8, "gf256Add: arrays must have 8 elements");
 
   for (let i = 0; i < 8; i++) {
     r[i] ^= x[i];
@@ -103,9 +118,10 @@ export function gf256Add(r: Uint32Array, x: Uint32Array): void {
  * @param b - Second operand (must NOT overlap with r)
  */
 export function gf256Mul(r: Uint32Array, a: Uint32Array, b: Uint32Array): void {
-  if (r.length !== 8 || a.length !== 8 || b.length !== 8) {
-    throw new Error("gf256Mul: arrays must have 8 elements");
-  }
+  assertContract(
+    r.length === 8 && a.length === 8 && b.length === 8,
+    "gf256Mul: arrays must have 8 elements",
+  );
 
   // Russian Peasant multiplication on two bitsliced polynomials
   const a2 = new Uint32Array(a);
@@ -212,9 +228,7 @@ export function gf256Mul(r: Uint32Array, a: Uint32Array, b: Uint32Array): void {
  * @param x - Value to square
  */
 export function gf256Square(r: Uint32Array, x: Uint32Array): void {
-  if (r.length !== 8 || x.length !== 8) {
-    throw new Error("gf256Square: arrays must have 8 elements");
-  }
+  assertContract(r.length === 8 && x.length === 8, "gf256Square: arrays must have 8 elements");
 
   // Use the Freshman's Dream rule to square the polynomial
   // Assignments are done from 7 downto 0, because this allows
@@ -259,9 +273,7 @@ export function gf256Square(r: Uint32Array, x: Uint32Array): void {
  * @param x - Value to invert (will be modified)
  */
 export function gf256Inv(r: Uint32Array, x: Uint32Array): void {
-  if (r.length !== 8 || x.length !== 8) {
-    throw new Error("gf256Inv: arrays must have 8 elements");
-  }
+  assertContract(r.length === 8 && x.length === 8, "gf256Inv: arrays must have 8 elements");
 
   const y = new Uint32Array(8);
   const z = new Uint32Array(8);

package/src/index.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Blockchain Commons Shamir Secret Sharing
 // Ported from bc-shamir-rust
 //
@@ -29,17 +35,3 @@ export { ShamirError, ShamirErrorType, type ShamirResult } from "./error.js";
 
 // Main functions
 export { splitSecret, recoverSecret } from "./shamir.js";
-
-// Low-level operations (hazmat)
-export {
-  bitslice,
-  unbitslice,
-  bitsliceSetall,
-  gf256Add,
-  gf256Mul,
-  gf256Square,
-  gf256Inv,
-} from "./hazmat.js";
-
-// Interpolation
-export { interpolate } from "./interpolate.js";

package/src/interpolate.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from bc-shamir-rust/src/interpolate.rs
 
 import { memzero, memzeroVecVecU8 } from "@bcts/crypto";

package/src/shamir.ts

@@ -1,3 +1,9 @@
+/**
+ * Copyright © 2023-2026 Blockchain Commons, LLC
+ * Copyright © 2025-2026 Parity Technologies
+ *
+ */
+
 // Ported from bc-shamir-rust/src/shamir.rs
 
 import { hmacSha256, memzero, memzeroVecVecU8 } from "@bcts/crypto";