@bcts/sskr 1.0.0-alpha.10

package/src/encoding.ts

@@ -0,0 +1,326 @@
+// Ported from bc-sskr-rust/src/encoding.rs
+
+import type { RandomNumberGenerator } from "@bcts/rand";
+import { SecureRandomNumberGenerator } from "@bcts/rand";
+import { splitSecret, recoverSecret, ShamirError } from "@bcts/shamir";
+
+import { SSKRError, SSKRErrorType } from "./error.js";
+import { Secret } from "./secret.js";
+import type { Spec } from "./spec.js";
+import { SSKRShare } from "./share.js";
+import { METADATA_SIZE_BYTES } from "./index.js";
+
+/**
+ * Generates SSKR shares for the given Spec and Secret.
+ *
+ * @param spec - The Spec instance that defines the group and member thresholds.
+ * @param masterSecret - The Secret instance to be split into shares.
+ * @returns A vector of groups, each containing a vector of shares,
+ *   each of which is a Uint8Array.
+ */
+export function sskrGenerate(spec: Spec, masterSecret: Secret): Uint8Array[][] {
+  const rng = new SecureRandomNumberGenerator();
+  return sskrGenerateUsing(spec, masterSecret, rng);
+}
+
+/**
+ * Generates SSKR shares for the given Spec and Secret using the provided
+ * random number generator.
+ *
+ * @param spec - The Spec instance that defines the group and member thresholds.
+ * @param masterSecret - The Secret instance to be split into shares.
+ * @param randomGenerator - The random number generator to use for generating
+ *   shares.
+ * @returns A vector of groups, each containing a vector of shares,
+ *   each of which is a Uint8Array.
+ */
+export function sskrGenerateUsing(
+  spec: Spec,
+  masterSecret: Secret,
+  randomGenerator: RandomNumberGenerator,
+): Uint8Array[][] {
+  const groupsShares = generateShares(spec, masterSecret, randomGenerator);
+
+  const result: Uint8Array[][] = groupsShares.map((group) => group.map(serializeShare));
+
+  return result;
+}
+
+/**
+ * Combines the given SSKR shares into a Secret.
+ *
+ * @param shares - A array of SSKR shares to be combined.
+ * @returns The reconstructed Secret.
+ * @throws SSKRError if the shares do not meet the necessary quorum of groups
+ *   and member shares within each group.
+ */
+export function sskrCombine(shares: Uint8Array[]): Secret {
+  const sskrShares: SSKRShare[] = [];
+
+  for (const share of shares) {
+    const sskrShare = deserializeShare(share);
+    sskrShares.push(sskrShare);
+  }
+
+  return combineShares(sskrShares);
+}
+
+function serializeShare(share: SSKRShare): Uint8Array {
+  // pack the id, group and member data into 5 bytes:
+  // 76543210        76543210        76543210
+  //         76543210        76543210
+  // ----------------====----====----====----
+  // identifier: 16
+  //                 group-threshold: 4
+  //                     group-count: 4
+  //                         group-index: 4
+  //                             member-threshold: 4
+  //                                 reserved (MUST be zero): 4
+  //                                     member-index: 4
+
+  const valueData = share.value().getData();
+  const result = new Uint8Array(valueData.length + METADATA_SIZE_BYTES);
+
+  const id = share.identifier();
+  const gt = (share.groupThreshold() - 1) & 0xf;
+  const gc = (share.groupCount() - 1) & 0xf;
+  const gi = share.groupIndex() & 0xf;
+  const mt = (share.memberThreshold() - 1) & 0xf;
+  const mi = share.memberIndex() & 0xf;
+
+  const id1 = id >> 8;
+  const id2 = id & 0xff;
+
+  result[0] = id1;
+  result[1] = id2;
+  result[2] = (gt << 4) | gc;
+  result[3] = (gi << 4) | mt;
+  result[4] = mi;
+  result.set(valueData, METADATA_SIZE_BYTES);
+
+  return result;
+}
+
+function deserializeShare(source: Uint8Array): SSKRShare {
+  if (source.length < METADATA_SIZE_BYTES) {
+    throw new SSKRError(SSKRErrorType.ShareLengthInvalid);
+  }
+
+  const groupThreshold = (source[2] >> 4) + 1;
+  const groupCount = (source[2] & 0xf) + 1;
+
+  if (groupThreshold > groupCount) {
+    throw new SSKRError(SSKRErrorType.GroupThresholdInvalid);
+  }
+
+  const identifier = (source[0] << 8) | source[1];
+  const groupIndex = source[3] >> 4;
+  const memberThreshold = (source[3] & 0xf) + 1;
+  const reserved = source[4] >> 4;
+  if (reserved !== 0) {
+    throw new SSKRError(SSKRErrorType.ShareReservedBitsInvalid);
+  }
+  const memberIndex = source[4] & 0xf;
+  const value = Secret.new(source.subarray(METADATA_SIZE_BYTES));
+
+  return new SSKRShare(
+    identifier,
+    groupIndex,
+    groupThreshold,
+    groupCount,
+    memberIndex,
+    memberThreshold,
+    value,
+  );
+}
+
+function generateShares(
+  spec: Spec,
+  masterSecret: Secret,
+  randomGenerator: RandomNumberGenerator,
+): SSKRShare[][] {
+  // assign a random identifier
+  const identifierBytes = new Uint8Array(2);
+  randomGenerator.fillRandomData(identifierBytes);
+  const identifier = (identifierBytes[0] << 8) | identifierBytes[1];
+
+  const groupsShares: SSKRShare[][] = [];
+
+  let groupSecrets: Uint8Array[];
+  try {
+    groupSecrets = splitSecret(
+      spec.groupThreshold(),
+      spec.groupCount(),
+      masterSecret.getData(),
+      randomGenerator,
+    );
+  } catch (e) {
+    if (e instanceof ShamirError) {
+      throw SSKRError.fromShamirError(e);
+    }
+    throw e;
+  }
+
+  for (let groupIndex = 0; groupIndex < spec.groups().length; groupIndex++) {
+    const group = spec.groups()[groupIndex];
+    const groupSecret = groupSecrets[groupIndex];
+
+    let memberSecrets: Uint8Array[];
+    try {
+      memberSecrets = splitSecret(
+        group.memberThreshold(),
+        group.memberCount(),
+        groupSecret,
+        randomGenerator,
+      );
+    } catch (e) {
+      if (e instanceof ShamirError) {
+        throw SSKRError.fromShamirError(e);
+      }
+      throw e;
+    }
+
+    const memberSSKRShares: SSKRShare[] = memberSecrets.map((memberSecret, memberIndex) => {
+      const secret = Secret.new(memberSecret);
+      return new SSKRShare(
+        identifier,
+        groupIndex,
+        spec.groupThreshold(),
+        spec.groupCount(),
+        memberIndex,
+        group.memberThreshold(),
+        secret,
+      );
+    });
+
+    groupsShares.push(memberSSKRShares);
+  }
+
+  return groupsShares;
+}
+
+interface Group {
+  groupIndex: number;
+  memberThreshold: number;
+  memberIndexes: number[];
+  memberShares: Secret[];
+}
+
+function combineShares(shares: SSKRShare[]): Secret {
+  let identifier = 0;
+  let groupThreshold = 0;
+  let groupCount = 0;
+
+  if (shares.length === 0) {
+    throw new SSKRError(SSKRErrorType.SharesEmpty);
+  }
+
+  let nextGroup = 0;
+  const groups: Group[] = [];
+  let secretLen = 0;
+
+  for (let i = 0; i < shares.length; i++) {
+    const share = shares[i];
+
+    if (i === 0) {
+      // on the first one, establish expected values for common metadata
+      identifier = share.identifier();
+      groupCount = share.groupCount();
+      groupThreshold = share.groupThreshold();
+      secretLen = share.value().len();
+    } else {
+      // on subsequent shares, check that common metadata matches
+      if (
+        share.identifier() !== identifier ||
+        share.groupThreshold() !== groupThreshold ||
+        share.groupCount() !== groupCount ||
+        share.value().len() !== secretLen
+      ) {
+        throw new SSKRError(SSKRErrorType.ShareSetInvalid);
+      }
+    }
+
+    // sort shares into member groups
+    let groupFound = false;
+    for (const group of groups) {
+      if (share.groupIndex() === group.groupIndex) {
+        groupFound = true;
+        if (share.memberThreshold() !== group.memberThreshold) {
+          throw new SSKRError(SSKRErrorType.MemberThresholdInvalid);
+        }
+        for (const memberIndex of group.memberIndexes) {
+          if (share.memberIndex() === memberIndex) {
+            throw new SSKRError(SSKRErrorType.DuplicateMemberIndex);
+          }
+        }
+        if (group.memberIndexes.length < group.memberThreshold) {
+          group.memberIndexes.push(share.memberIndex());
+          group.memberShares.push(share.value().clone());
+        }
+      }
+    }
+
+    if (!groupFound) {
+      const g: Group = {
+        groupIndex: share.groupIndex(),
+        memberThreshold: share.memberThreshold(),
+        memberIndexes: [share.memberIndex()],
+        memberShares: [share.value().clone()],
+      };
+      groups.push(g);
+      nextGroup++;
+    }
+  }
+
+  // Check that we have enough groups to recover the master secret
+  if (nextGroup < groupThreshold) {
+    throw new SSKRError(SSKRErrorType.NotEnoughGroups);
+  }
+
+  // Here, all of the shares are unpacked into member groups. Now we go
+  // through each group and recover the group secret, and then use the
+  // result to recover the master secret
+  const masterIndexes: number[] = [];
+  const masterShares: Uint8Array[] = [];
+
+  for (const group of groups) {
+    // Only attempt to recover the group secret if we have enough shares
+    if (group.memberIndexes.length < group.memberThreshold) {
+      continue;
+    }
+
+    // Recover the group secret
+    try {
+      const memberSharesData = group.memberShares.map((s) => s.getData());
+      const groupSecret = recoverSecret(group.memberIndexes, memberSharesData);
+      masterIndexes.push(group.groupIndex);
+      masterShares.push(groupSecret);
+    } catch {
+      // If we can't recover this group, just skip it
+      continue;
+    }
+
+    // Stop if we have enough groups to recover the master secret
+    if (masterIndexes.length === groupThreshold) {
+      break;
+    }
+  }
+
+  // If we don't have enough groups to recover the master secret, return an error
+  if (masterIndexes.length < groupThreshold) {
+    throw new SSKRError(SSKRErrorType.NotEnoughGroups);
+  }
+
+  // Recover the master secret
+  let masterSecretData: Uint8Array;
+  try {
+    masterSecretData = recoverSecret(masterIndexes, masterShares);
+  } catch (e) {
+    if (e instanceof ShamirError) {
+      throw SSKRError.fromShamirError(e);
+    }
+    throw e;
+  }
+
+  return Secret.new(masterSecretData);
+}

package/src/error.ts

@@ -0,0 +1,82 @@
+// Ported from bc-sskr-rust/src/error.rs
+
+import type { ShamirError } from "@bcts/shamir";
+
+/**
+ * Error types for SSKR operations.
+ */
+export enum SSKRErrorType {
+  DuplicateMemberIndex = "DuplicateMemberIndex",
+  GroupSpecInvalid = "GroupSpecInvalid",
+  GroupCountInvalid = "GroupCountInvalid",
+  GroupThresholdInvalid = "GroupThresholdInvalid",
+  MemberCountInvalid = "MemberCountInvalid",
+  MemberThresholdInvalid = "MemberThresholdInvalid",
+  NotEnoughGroups = "NotEnoughGroups",
+  SecretLengthNotEven = "SecretLengthNotEven",
+  SecretTooLong = "SecretTooLong",
+  SecretTooShort = "SecretTooShort",
+  ShareLengthInvalid = "ShareLengthInvalid",
+  ShareReservedBitsInvalid = "ShareReservedBitsInvalid",
+  SharesEmpty = "SharesEmpty",
+  ShareSetInvalid = "ShareSetInvalid",
+  ShamirError = "ShamirError",
+}
+
+/**
+ * Error class for SSKR operations.
+ */
+export class SSKRError extends Error {
+  readonly type: SSKRErrorType;
+  readonly shamirError?: ShamirError | undefined;
+
+  constructor(type: SSKRErrorType, message?: string, shamirError?: ShamirError) {
+    super(message ?? SSKRError.defaultMessage(type, shamirError));
+    this.type = type;
+    this.shamirError = shamirError;
+    this.name = "SSKRError";
+  }
+
+  private static defaultMessage(type: SSKRErrorType, shamirError?: ShamirError): string {
+    switch (type) {
+      case SSKRErrorType.DuplicateMemberIndex:
+        return "When combining shares, the provided shares contained a duplicate member index";
+      case SSKRErrorType.GroupSpecInvalid:
+        return "Invalid group specification";
+      case SSKRErrorType.GroupCountInvalid:
+        return "When creating a split spec, the group count is invalid";
+      case SSKRErrorType.GroupThresholdInvalid:
+        return "SSKR group threshold is invalid";
+      case SSKRErrorType.MemberCountInvalid:
+        return "SSKR member count is invalid";
+      case SSKRErrorType.MemberThresholdInvalid:
+        return "SSKR member threshold is invalid";
+      case SSKRErrorType.NotEnoughGroups:
+        return "SSKR shares did not contain enough groups";
+      case SSKRErrorType.SecretLengthNotEven:
+        return "SSKR secret is not of even length";
+      case SSKRErrorType.SecretTooLong:
+        return "SSKR secret is too long";
+      case SSKRErrorType.SecretTooShort:
+        return "SSKR secret is too short";
+      case SSKRErrorType.ShareLengthInvalid:
+        return "SSKR shares did not contain enough serialized bytes";
+      case SSKRErrorType.ShareReservedBitsInvalid:
+        return "SSKR shares contained invalid reserved bits";
+      case SSKRErrorType.SharesEmpty:
+        return "SSKR shares were empty";
+      case SSKRErrorType.ShareSetInvalid:
+        return "SSKR shares were invalid";
+      case SSKRErrorType.ShamirError:
+        return shamirError != null
+          ? `SSKR Shamir error: ${shamirError.message}`
+          : "SSKR Shamir error";
+    }
+  }
+
+  static fromShamirError(error: ShamirError): SSKRError {
+    return new SSKRError(SSKRErrorType.ShamirError, undefined, error);
+  }
+}
+
+export type SSKRResult<T> = T;

package/src/index.ts

@@ -0,0 +1,60 @@
+// Blockchain Commons Sharded Secret Key Reconstruction (SSKR)
+// Ported from bc-sskr-rust
+//
+// Sharded Secret Key Reconstruction (SSKR) is a protocol for splitting a
+// secret into a set of shares across one or more groups, such that the
+// secret can be reconstructed from any combination of shares totaling or
+// exceeding a threshold number of shares within each group and across all
+// groups. SSKR is a generalization of Shamir's Secret Sharing (SSS) that
+// allows for multiple groups and multiple thresholds.
+
+import {
+  MIN_SECRET_LEN as SHAMIR_MIN_SECRET_LEN,
+  MAX_SECRET_LEN as SHAMIR_MAX_SECRET_LEN,
+  MAX_SHARE_COUNT as SHAMIR_MAX_SHARE_COUNT,
+} from "@bcts/shamir";
+
+/**
+ * The minimum length of a secret.
+ */
+export const MIN_SECRET_LEN = SHAMIR_MIN_SECRET_LEN;
+
+/**
+ * The maximum length of a secret.
+ */
+export const MAX_SECRET_LEN = SHAMIR_MAX_SECRET_LEN;
+
+/**
+ * The maximum number of shares that can be generated from a secret.
+ */
+export const MAX_SHARE_COUNT = SHAMIR_MAX_SHARE_COUNT;
+
+/**
+ * The maximum number of groups in a split.
+ */
+export const MAX_GROUPS_COUNT = MAX_SHARE_COUNT;
+
+/**
+ * The number of bytes used to encode the metadata for a share.
+ */
+export const METADATA_SIZE_BYTES = 5;
+
+/**
+ * The minimum number of bytes required to encode a share.
+ */
+export const MIN_SERIALIZE_SIZE_BYTES = METADATA_SIZE_BYTES + MIN_SECRET_LEN;
+
+// Error types
+export { SSKRError, SSKRErrorType, type SSKRResult } from "./error.js";
+
+// Secret
+export { Secret } from "./secret.js";
+
+// Specifications
+export { GroupSpec, Spec } from "./spec.js";
+
+// Share
+export { SSKRShare } from "./share.js";
+
+// Encoding/Decoding
+export { sskrGenerate, sskrGenerateUsing, sskrCombine } from "./encoding.js";

package/src/secret.ts

@@ -0,0 +1,90 @@
+// Ported from bc-sskr-rust/src/secret.rs
+
+import { MIN_SECRET_LEN, MAX_SECRET_LEN } from "./index.js";
+import { SSKRError, SSKRErrorType } from "./error.js";
+
+/**
+ * A secret to be split into shares.
+ */
+export class Secret {
+  private readonly data: Uint8Array;
+
+  private constructor(data: Uint8Array) {
+    this.data = data;
+  }
+
+  /**
+   * Creates a new Secret instance with the given data.
+   *
+   * @param data - The secret data to be split into shares.
+   * @returns A new Secret instance.
+   * @throws SSKRError if the length of the secret is less than
+   *   MIN_SECRET_LEN, greater than MAX_SECRET_LEN, or not even.
+   */
+  static new(data: Uint8Array | string): Secret {
+    const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+    const len = bytes.length;
+
+    if (len < MIN_SECRET_LEN) {
+      throw new SSKRError(SSKRErrorType.SecretTooShort);
+    }
+    if (len > MAX_SECRET_LEN) {
+      throw new SSKRError(SSKRErrorType.SecretTooLong);
+    }
+    if ((len & 1) !== 0) {
+      throw new SSKRError(SSKRErrorType.SecretLengthNotEven);
+    }
+
+    return new Secret(new Uint8Array(bytes));
+  }
+
+  /**
+   * Returns the length of the secret.
+   */
+  len(): number {
+    return this.data.length;
+  }
+
+  /**
+   * Returns true if the secret is empty.
+   */
+  isEmpty(): boolean {
+    return this.len() === 0;
+  }
+
+  /**
+   * Returns a reference to the secret data.
+   */
+  getData(): Uint8Array {
+    return this.data;
+  }
+
+  /**
+   * Returns the secret data as a Uint8Array.
+   */
+  asRef(): Uint8Array {
+    return this.data;
+  }
+
+  /**
+   * Check equality with another Secret.
+   */
+  equals(other: Secret): boolean {
+    if (this.data.length !== other.data.length) {
+      return false;
+    }
+    for (let i = 0; i < this.data.length; i++) {
+      if (this.data[i] !== other.data[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Clone the secret.
+   */
+  clone(): Secret {
+    return new Secret(new Uint8Array(this.data));
+  }
+}

package/src/share.ts

@@ -0,0 +1,62 @@
+// Ported from bc-sskr-rust/src/share.rs
+
+import type { Secret } from "./secret.js";
+
+/**
+ * A share in the SSKR scheme.
+ */
+export class SSKRShare {
+  private readonly _identifier: number;
+  private readonly _groupIndex: number;
+  private readonly _groupThreshold: number;
+  private readonly _groupCount: number;
+  private readonly _memberIndex: number;
+  private readonly _memberThreshold: number;
+  private readonly _value: Secret;
+
+  constructor(
+    identifier: number,
+    groupIndex: number,
+    groupThreshold: number,
+    groupCount: number,
+    memberIndex: number,
+    memberThreshold: number,
+    value: Secret,
+  ) {
+    this._identifier = identifier;
+    this._groupIndex = groupIndex;
+    this._groupThreshold = groupThreshold;
+    this._groupCount = groupCount;
+    this._memberIndex = memberIndex;
+    this._memberThreshold = memberThreshold;
+    this._value = value;
+  }
+
+  identifier(): number {
+    return this._identifier;
+  }
+
+  groupIndex(): number {
+    return this._groupIndex;
+  }
+
+  groupThreshold(): number {
+    return this._groupThreshold;
+  }
+
+  groupCount(): number {
+    return this._groupCount;
+  }
+
+  memberIndex(): number {
+    return this._memberIndex;
+  }
+
+  memberThreshold(): number {
+    return this._memberThreshold;
+  }
+
+  value(): Secret {
+    return this._value;
+  }
+}