skeleton_key 0.1.0

data/lib/skeleton_key/recovery/slip39.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "securerandom"
+
+module SkeletonKey
+  module Recovery
+    ##
+    # SLIP-0039 Shamir-share recovery for master secrets.
+    #
+    # This class validates SLIP-0039 mnemonic shares, enforces group and member
+    # thresholds, can generate new share sets from a master secret, reconstructs
+    # the encrypted master secret, and decrypts it into a {Seed}. It belongs to
+    # the recovery layer and intentionally stops before any downstream chain
+    # derivation begins.
+    #
+    # Caller input is a **flat array of share strings**. The caller does not
+    # supply nested groups. Instead, each share encodes its own group metadata,
+    # and {Slip39} reconstructs the group structure internally during recovery.
+    #
+    # In other words, the protocol is multi-group, but the Ruby interface is:
+    # - `Array<String>` of shares
+    # - optional ASCII passphrase
+    # - return a recovered {Seed}
+    #
+    # @example Recover a seed from a single-group threshold set
+    #   seed = SkeletonKey::Recovery::Slip39.recover(shares, passphrase: "")
+    #
+    # @example Recover a seed from a multi-group threshold set
+    #   shares = [
+    #     group_0_share_0,
+    #     group_0_share_1,
+    #     group_2_share_0,
+    #     group_2_share_1
+    #   ]
+    #
+    #   # Group membership is inferred from the encoded SLIP-0039 share data.
+    #   seed = SkeletonKey::Recovery::Slip39.recover(shares, passphrase: "PASS8")
+    class Slip39
+      extend Utils::Encoding
+
+      WORDLIST_PATH = File.expand_path("slip39_wordlist.txt", __dir__)
+      include Slip39Support::Protocol
+
+      class << self
+        # Generates SLIP-0039 mnemonic shares from a master secret.
+        #
+        # For single-group sharing, provide `member_threshold` and
+        # `member_count`. For advanced multi-group sharing, provide `groups:`
+        # and `group_threshold:`.
+        #
+        # @param master_secret [String, Array<Integer>, Seed] 16, 24, or 32-byte master secret
+        # @param member_threshold [Integer, nil] single-group member threshold
+        # @param member_count [Integer, nil] single-group member count
+        # @param groups [Array<Hash>, nil] multi-group member thresholds/counts
+        # @param group_threshold [Integer] number of groups required for recovery
+        # @param passphrase [String] optional SLIP-0039 passphrase
+        # @param extendable [Boolean]
+        # @param iteration_exponent [Integer]
+        # @param random_bytes [#call, nil] optional deterministic random-byte source
+        # @return [Slip39Support::GeneratedSet]
+        def generate(
+          master_secret:,
+          member_threshold: nil,
+          member_count: nil,
+          groups: nil,
+          group_threshold: 1,
+          passphrase: "",
+          extendable: true,
+          iteration_exponent: 1,
+          random_bytes: nil
+        )
+          group_config = normalize_groups(member_threshold:, member_count:, groups:)
+          generator = Slip39Support::Generator.new(
+            wordlist: wordlist,
+            customization_string: method(:customization_string_for),
+            cipher: Slip39Support::Cipher.new(
+              customization_string_orig: Slip39Support::Protocol::CUSTOMIZATION_STRING_ORIG
+            ),
+            random_bytes: random_bytes || SecureRandom.method(:random_bytes)
+          )
+
+          generator.generate(
+            master_secret: normalize_master_secret(master_secret),
+            group_threshold: group_threshold,
+            groups: group_config,
+            passphrase: passphrase,
+            extendable: extendable,
+            iteration_exponent: iteration_exponent
+          )
+        end
+
+        # Recovers a master secret from a set of SLIP-0039 mnemonics.
+        #
+        # The input is a flat list of share strings. Grouping is inferred from
+        # the metadata encoded inside each share rather than from caller-supplied
+        # nesting.
+        #
+        # @param mnemonics [Array<String>] flat threshold set of SLIP-0039 shares
+        # @param passphrase [String] optional SLIP-0039 passphrase
+        # @return [Seed]
+        def recover(mnemonics, passphrase: "")
+          new(mnemonics).recover(passphrase: passphrase)
+        end
+
+        # Loads the canonical SLIP-0039 wordlist.
+        #
+        # @return [Array<String>] frozen list of 1024 words
+        # @raise [Errors::InvalidSlip39ShareError] if the vendored wordlist is malformed
+        def wordlist
+          @wordlist ||= begin
+            words = File.readlines(WORDLIST_PATH, chomp: true)
+            raise Errors::InvalidSlip39ShareError, "invalid SLIP-0039 wordlist length" unless words.length == Slip39Support::Protocol::RADIX
+
+            words.freeze
+          end
+        end
+
+        # Maps each word to its 10-bit index.
+        #
+        # @return [Hash{String => Integer}]
+        def word_index
+          @word_index ||= wordlist.each_with_index.to_h.freeze
+        end
+
+        def customization_string_for(extendable)
+          if extendable
+            Slip39Support::Protocol::CUSTOMIZATION_STRING_EXTENDABLE
+          else
+            Slip39Support::Protocol::CUSTOMIZATION_STRING_ORIG
+          end
+        end
+
+        private
+
+        def normalize_groups(member_threshold:, member_count:, groups:)
+          if groups
+            raise Errors::InvalidSlip39ConfigurationError, "pass either groups or member_threshold/member_count, not both" unless member_threshold.nil? && member_count.nil?
+
+            return groups.map do |group|
+              {
+                member_threshold: group.fetch(:member_threshold),
+                member_count: group.fetch(:member_count)
+              }
+            end
+          end
+
+          if member_threshold.nil? || member_count.nil?
+            raise Errors::InvalidSlip39ConfigurationError,
+                  "single-group generation requires member_threshold and member_count"
+          end
+
+          [{ member_threshold: member_threshold, member_count: member_count }]
+        end
+
+        def normalize_master_secret(master_secret)
+          if master_secret.is_a?(Seed)
+            return master_secret.bytes
+          end
+
+          return octets_to_bytes(master_secret) if octet_array?(master_secret)
+          return hex_to_bytes(master_secret) if hex_string?(master_secret)
+          return master_secret if byte_string?(master_secret)
+
+          raise Errors::InvalidSlip39ConfigurationError, "master_secret must be bytes, hex, octets, or Seed"
+        end
+      end
+
+      def initialize(mnemonics)
+        @mnemonics = Array(mnemonics)
+        @decoder = Slip39Support::Decoder.new(
+          word_index: self.class.word_index,
+          customization_string: method(:customization_string)
+        )
+        @secret_recovery = Slip39Support::SecretRecovery.new
+        @cipher = Slip39Support::Cipher.new(
+          customization_string_orig: CUSTOMIZATION_STRING_ORIG
+        )
+      end
+
+      # Validates the share set and recovers the decrypted master secret.
+      #
+      # Shares may span one or more protocol groups, but callers still pass a
+      # single flat array. This method decodes the embedded group metadata and
+      # reconstructs the required group/member threshold structure internally.
+      #
+      # @param passphrase [String] optional SLIP-0039 passphrase
+      # @return [Seed]
+      # @raise [Errors::InvalidSlip39ShareError] if the share set is invalid or insufficient
+      def recover(passphrase: "")
+        raise Errors::InvalidSlip39ShareError, "the list of SLIP-0039 shares is empty" if @mnemonics.empty?
+
+        groups = @decoder.decode(@mnemonics)
+        encrypted_master_secret = @secret_recovery.recover_encrypted_master_secret(groups)
+        validate_passphrase!(passphrase)
+        Seed.import_from_bytes(
+          @cipher.decrypt(
+            encrypted_master_secret.fetch(:ciphertext),
+            passphrase.b,
+            encrypted_master_secret.fetch(:iteration_exponent),
+            encrypted_master_secret.fetch(:identifier),
+            encrypted_master_secret.fetch(:extendable)
+          )
+        )
+      end
+
+      private
+
+      def validate_passphrase!(passphrase)
+        return if passphrase.bytes.all? { |byte| byte.between?(32, 126) }
+
+        raise Errors::InvalidSlip39ShareError, "SLIP-0039 passphrase must contain only printable ASCII characters"
+      end
+
+      def customization_string(extendable)
+        extendable ? CUSTOMIZATION_STRING_EXTENDABLE : CUSTOMIZATION_STRING_ORIG
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/bit_packing.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # Integer and byte packing helpers used by SLIP-0039 parsing and recovery.
+      module BitPacking
+        module_function
+
+        def int_from_indices(indices, radix)
+          indices.reduce(0) { |value, index| (value * radix) + index }
+        end
+
+        def int_to_indices(value, length, radix_bits)
+          mask = (1 << radix_bits) - 1
+          (0...length).map do |offset|
+            shift = (length - offset - 1) * radix_bits
+            (value >> shift) & mask
+          end
+        end
+
+        def bits_to_bytes(bit_count)
+          (bit_count + 7) / 8
+        end
+
+        def bits_to_words(bit_count, radix_bits)
+          (bit_count + radix_bits - 1) / radix_bits
+        end
+
+        def xor_bytes(left, right)
+          left.bytes.zip(right.bytes).map { |a, b| a ^ b }.pack("C*")
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/checksum.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # RS1024 checksum implementation for SLIP-0039 mnemonics.
+      module Checksum
+        GENERATORS = [
+          0xE0E040,
+          0x1C1C080,
+          0x3838100,
+          0x7070200,
+          0xE0E0009,
+          0x1C0C2412,
+          0x38086C24,
+          0x3090FC48,
+          0x21B1F890,
+          0x3F3F120
+        ].freeze
+
+        module_function
+
+        def create(data, customization)
+          values = customization.bytes + data + [0] * Protocol::CHECKSUM_LENGTH_WORDS
+          checksum = polymod(values) ^ 1
+          Protocol::CHECKSUM_LENGTH_WORDS.times.map do |offset|
+            shift = 10 * (Protocol::CHECKSUM_LENGTH_WORDS - offset - 1)
+            (checksum >> shift) & 1023
+          end
+        end
+
+        def verify(data, customization)
+          polymod(customization.bytes + data) == 1
+        end
+
+        def polymod(values)
+          checksum = 1
+
+          values.each do |value|
+            top = checksum >> 20
+            checksum = ((checksum & 0xFFFFF) << 10) ^ value
+            10.times do |index|
+              checksum ^= GENERATORS[index] if ((top >> index) & 1) == 1
+            end
+          end
+
+          checksum
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/cipher.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # Feistel cipher used to encrypt and decrypt SLIP-0039 master secrets.
+      class Cipher
+        include Protocol
+
+        def initialize(customization_string_orig:)
+          @customization_string_orig = customization_string_orig
+        end
+
+        # Encrypts a master secret into an encrypted master secret payload.
+        #
+        # @param master_secret [String] even-length byte string
+        # @param passphrase [String] printable ASCII passphrase bytes
+        # @param iteration_exponent [Integer]
+        # @param identifier [Integer]
+        # @param extendable [Boolean]
+        # @return [String]
+        def encrypt(master_secret, passphrase, iteration_exponent, identifier, extendable)
+          raise Errors::InvalidSlip39ConfigurationError, "SLIP-0039 master secret must have even byte length" if master_secret.bytesize.odd?
+
+          left = master_secret.byteslice(0, master_secret.bytesize / 2)
+          right = master_secret.byteslice(master_secret.bytesize / 2, master_secret.bytesize / 2)
+          salt = slip39_salt(identifier, extendable)
+
+          ROUND_COUNT.times do |round|
+            feistel = OpenSSL::PKCS5.pbkdf2_hmac(
+              [round].pack("C") + passphrase,
+              salt + right,
+              (BASE_ITERATION_COUNT << iteration_exponent) / ROUND_COUNT,
+              left.bytesize,
+              "sha256"
+            )
+            left, right = right, BitPacking.xor_bytes(left, feistel)
+          end
+
+          right + left
+        end
+
+        # Decrypts an encrypted master secret into the original master secret.
+        #
+        # @param encrypted_master_secret [String] even-length byte string
+        # @return [String]
+        def decrypt(encrypted_master_secret, passphrase, iteration_exponent, identifier, extendable)
+          raise Errors::InvalidSlip39ShareError, "SLIP-0039 master secret must have even byte length" if encrypted_master_secret.bytesize.odd?
+
+          left = encrypted_master_secret.byteslice(0, encrypted_master_secret.bytesize / 2)
+          right = encrypted_master_secret.byteslice(encrypted_master_secret.bytesize / 2, encrypted_master_secret.bytesize / 2)
+          salt = slip39_salt(identifier, extendable)
+
+          (ROUND_COUNT - 1).downto(0) do |round|
+            feistel = OpenSSL::PKCS5.pbkdf2_hmac(
+              [round].pack("C") + passphrase,
+              salt + right,
+              (BASE_ITERATION_COUNT << iteration_exponent) / ROUND_COUNT,
+              left.bytesize,
+              "sha256"
+            )
+            left, right = right, BitPacking.xor_bytes(left, feistel)
+          end
+
+          right + left
+        end
+
+        private
+
+        def slip39_salt(identifier, extendable)
+          return "".b if extendable
+
+          @customization_string_orig + [identifier].pack("n")
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/decoder.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "set"
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # Decodes flat SLIP-0039 share strings into validated grouped share objects.
+      class Decoder
+        include Protocol
+
+        def initialize(word_index:, customization_string:)
+          @word_index = word_index
+          @customization_string = customization_string
+        end
+
+        def decode(mnemonics)
+          common_params = Set.new
+          groups = Hash.new { |hash, key| hash[key] = [] }
+
+          mnemonics.each do |mnemonic|
+            share = share_from_mnemonic(mnemonic)
+            common_params << share.common_parameters
+            groups[share.group_index] << share
+          end
+
+          if common_params.length != 1
+            raise Errors::InvalidSlip39ShareError,
+                  "all SLIP-0039 shares must have matching identifier, group threshold, and group count"
+          end
+
+          groups.transform_values { |shares| dedupe_and_validate_group(shares) }
+        end
+
+        private
+
+        def dedupe_and_validate_group(shares)
+          unique = shares.uniq { |share| share.index }
+          if unique.length != shares.length
+            raise Errors::InvalidSlip39ShareError, "SLIP-0039 share indices must be unique within a group"
+          end
+
+          group_parameters = unique.first.group_parameters
+          unless unique.all? { |share| share.group_parameters == group_parameters }
+            raise Errors::InvalidSlip39ShareError, "SLIP-0039 group parameters do not match"
+          end
+
+          unique
+        end
+
+        def share_from_mnemonic(mnemonic)
+          indices = mnemonic_to_indices(mnemonic)
+          if indices.length < MIN_MNEMONIC_LENGTH_WORDS
+            raise Errors::InvalidSlip39ShareError,
+                  "invalid SLIP-0039 mnemonic length: must be at least #{MIN_MNEMONIC_LENGTH_WORDS} words"
+          end
+
+          padding_length = (RADIX_BITS * (indices.length - METADATA_LENGTH_WORDS)) % 16
+          raise Errors::InvalidSlip39ShareError, "invalid SLIP-0039 mnemonic length" if padding_length > 8
+
+          id_exp_int = BitPacking.int_from_indices(indices.first(ID_EXP_LENGTH_WORDS), RADIX)
+          identifier = id_exp_int >> (EXTENDABLE_FLAG_LENGTH_BITS + ITERATION_EXP_LENGTH_BITS)
+          extendable = ((id_exp_int >> ITERATION_EXP_LENGTH_BITS) & 1) == 1
+          iteration_exponent = id_exp_int & ((1 << ITERATION_EXP_LENGTH_BITS) - 1)
+
+          unless Checksum.verify(indices, @customization_string.call(extendable))
+            raise Errors::InvalidSlip39ShareError, "invalid SLIP-0039 checksum"
+          end
+
+          share_params_int = BitPacking.int_from_indices(indices[ID_EXP_LENGTH_WORDS, 2], RADIX)
+          group_index, group_threshold_minus_one, group_count_minus_one, index, member_threshold_minus_one =
+            BitPacking.int_to_indices(share_params_int, 5, 4)
+
+          if group_count_minus_one < group_threshold_minus_one
+            raise Errors::InvalidSlip39ShareError, "SLIP-0039 group threshold cannot exceed group count"
+          end
+
+          value_indices = indices[(ID_EXP_LENGTH_WORDS + 2)...-CHECKSUM_LENGTH_WORDS]
+          value_byte_count = BitPacking.bits_to_bytes(RADIX_BITS * value_indices.length - padding_length)
+          value_int = BitPacking.int_from_indices(value_indices, RADIX)
+          value = [value_int.to_s(16).rjust(value_byte_count * 2, "0")].pack("H*")
+
+          Share.new(
+            identifier: identifier,
+            extendable: extendable,
+            iteration_exponent: iteration_exponent,
+            group_index: group_index,
+            group_threshold: group_threshold_minus_one + 1,
+            group_count: group_count_minus_one + 1,
+            index: index,
+            member_threshold: member_threshold_minus_one + 1,
+            value: value
+          )
+        rescue RangeError
+          raise Errors::InvalidSlip39ShareError, "invalid SLIP-0039 mnemonic padding"
+        end
+
+        def mnemonic_to_indices(mnemonic)
+          mnemonic.split.map do |word|
+            @word_index.fetch(word.downcase)
+          rescue KeyError
+            raise Errors::InvalidSlip39ShareError, "invalid SLIP-0039 mnemonic word: #{word}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/encoder.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # Encodes structured SLIP-0039 shares back into mnemonic word strings.
+      class Encoder
+        include Protocol
+
+        def initialize(wordlist:, customization_string:)
+          @wordlist = wordlist
+          @customization_string = customization_string
+        end
+
+        def mnemonic_for_share(share)
+          share_data = encode_id_exp(share) + encode_share_params(share) + encode_value(share.value)
+          checksum = Checksum.create(share_data, @customization_string.call(share.extendable))
+          (share_data + checksum).map { |index| @wordlist.fetch(index) }.join(" ")
+        end
+
+        private
+
+        def encode_id_exp(share)
+          id_exp_int = share.identifier << (ITERATION_EXP_LENGTH_BITS + EXTENDABLE_FLAG_LENGTH_BITS)
+          id_exp_int += (share.extendable ? 1 : 0) << ITERATION_EXP_LENGTH_BITS
+          id_exp_int += share.iteration_exponent
+          BitPacking.int_to_indices(id_exp_int, ID_EXP_LENGTH_WORDS, RADIX_BITS)
+        end
+
+        def encode_share_params(share)
+          value = share.group_index
+          value = (value << 4) + (share.group_threshold - 1)
+          value = (value << 4) + (share.group_count - 1)
+          value = (value << 4) + share.index
+          value = (value << 4) + (share.member_threshold - 1)
+          BitPacking.int_to_indices(value, 2, 10)
+        end
+
+        def encode_value(bytes)
+          word_count = BitPacking.bits_to_words(bytes.bytesize * 8, RADIX_BITS)
+          value_int = bytes.unpack1("H*").to_i(16)
+          BitPacking.int_to_indices(value_int, word_count, RADIX_BITS)
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/recovery/slip39_support/generated_set.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Recovery
+    module Slip39Support
+      ##
+      # Return object for generated SLIP-0039 shares.
+      class GeneratedSet
+        attr_reader :identifier, :extendable, :iteration_exponent, :group_threshold, :groups, :mnemonic_groups
+
+        def initialize(identifier:, extendable:, iteration_exponent:, group_threshold:, groups:, mnemonic_groups:)
+          @identifier = identifier
+          @extendable = extendable
+          @iteration_exponent = iteration_exponent
+          @group_threshold = group_threshold
+          @groups = groups
+          @mnemonic_groups = mnemonic_groups
+        end
+
+        # Returns every generated share in a single flat array.
+        #
+        # @return [Array<String>]
+        def all_shares
+          mnemonic_groups.flatten
+        end
+
+        # Returns a simple threshold-satisfying recovery subset by taking the
+        # first required members from the first required groups.
+        #
+        # @return [Array<String>]
+        def recovery_set
+          mnemonic_groups.first(group_threshold).each_with_index.flat_map do |shares, index|
+            shares.first(groups.fetch(index).fetch(:member_threshold))
+          end
+        end
+      end
+    end
+  end
+end