skeleton_key 0.1.0

data/lib/skeleton_key/seed.rb

@@ -0,0 +1,127 @@
+require "securerandom"
+
+module SkeletonKey
+  ##
+  # Canonical seed container shared by all chain derivation entry points.
+  #
+  # {Seed} is the normalization boundary between recovery inputs
+  # (BIP39/SLIP-0039), raw entropy-like byte material, and downstream chain
+  # derivation. Callers can import from several supported input forms, but once
+  # constructed the object always wraps validated raw bytes.
+  class Seed
+    include Utils::Encoding
+    extend Utils::Encoding
+
+    # Raw seed bytes after normalization and validation.
+    #
+    # @return [String]
+    attr_reader :bytes
+
+    # @param bytes [String] raw seed bytes
+    # @raise [Errors::InvalidSeedError] if the seed length is not valid
+    def initialize(bytes)
+      @bytes = bytes
+
+      raise Errors::InvalidSeedError unless Constants::SEED_LENGTHS.include?(@bytes.bytesize)
+    end
+
+    # Returns the hex representation of the seed
+    #
+    # @return [String] hex string
+    def hex
+      bytes_to_hex(@bytes)
+    end
+
+    # Returns the array of octets (integers 0-255) representation of the seed
+    #
+    # @return [Array<Integer>] array of byte values
+    def octets
+      @bytes.bytes
+    end
+
+    class << self
+      # Loads a seed from a given value
+      #
+      # Supported inputs:
+      # - `nil` to generate a new random seed
+      # - existing {Seed}
+      # - validated {Recovery::Bip39}
+      # - hex string
+      # - mnemonic string
+      # - raw byte string
+      # - array of octets
+      #
+      # @param value [String, Seed, Recovery::Bip39, Array<Integer>, nil]
+      # @return [Seed]
+      # @raise [Errors::InvalidSeedError] if the value cannot be normalized
+      def import(value)
+        case
+        when value.nil? then generate
+        when value.is_a?(Seed) then import_from_seed(value)
+        when value.is_a?(Recovery::Bip39) then import_from_mnemonic(value)
+        when hex_string?(value) then import_from_hex(value)
+        when mnemonic_string?(value) then import_from_mnemonic(value)
+        when byte_string?(value) then import_from_bytes(value)
+        when octet_array?(value) then import_from_octets(value)
+        else
+          raise Errors::InvalidSeedError
+        end
+      end
+
+      # Generates a new random 32-byte seed
+      #
+      # @return [Seed] the generated seed
+      def generate
+        new(Core::Entropy.generate(bytes: 32))
+      end
+
+      # Creates a new seed from a byte string
+      #
+      # @param seed [String] the byte string seed
+      # @return [Seed] the created Seed
+      def import_from_bytes(bytes)
+        new(bytes)
+      end
+
+      # Creates a new seed from a hex string
+      #
+      # @param seed_hex [String] the hex string seed
+      # @return [Seed] the created Seed
+      def import_from_hex(hex)
+        new(hex_to_bytes(hex))
+      end
+
+      # Creates a new seed from an array of octets
+      #
+      # @param seed_octets [Array<Integer>] the array of octets
+      # @return [Seed] the created Seed
+      def import_from_octets(octets)
+        new(octets_to_bytes(octets))
+      end
+
+      # Creates a new seed from another Seed
+      #
+      # @param seed [Seed] the Seed to copy
+      # @return [Seed] the created Seed
+      def import_from_seed(seed)
+        new(seed.bytes)
+      end
+
+      # Recovers a seed from a BIP39 mnemonic phrase.
+      #
+      # @param mnemonic [Recovery::Bip39, String]
+      # @return [Seed]
+      def import_from_mnemonic(mnemonic)
+        Recovery::Bip39.import(mnemonic).seed
+      end
+
+      private
+
+      def mnemonic_string?(value)
+        return false unless value.is_a?(String)
+
+        Constants::MNEMONIC_WORD_COUNTS.include?(value.strip.split(/\s+/).length)
+      end
+    end
+  end
+end

data/lib/skeleton_key/skeleton_key.code-workspace

@@ -0,0 +1,11 @@
+{
+	"folders": [
+		{
+			"path": "../../../slip-39-tools"
+		},
+		{
+			"path": "../.."
+		}
+	],
+	"settings": {}
+}

data/lib/skeleton_key/utils/encoding.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Utils
+    ##
+    # Static helpers for encoding/decoding binary values
+    # into hex, base64, base58, etc.
+    #
+    # Also provides validation helpers for distinguishing
+    # between byte strings and hex strings.
+    #
+    # Usage:
+    #   SkeletonKey::Utils::Encoding.hex_to_bytes("deadbeef")
+    #   SkeletonKey::Utils::Encoding.bytes_to_hex("\xDE\xAD")
+    #   SkeletonKey::Utils::Encoding.hex_string?("zzzz") # => false
+    #
+    module Encoding
+      module_function
+
+      ##
+      # Base58Check encoding (Bitcoin alphabet)
+      #
+      # @param [String] payload binary string to encode
+      # @return [String] base58check-encoded string
+      def base58check_encode(payload)
+        Codecs::Base58Check.encode(payload)
+      end
+
+      ##
+      # Convert a hex string into raw bytes.
+      #
+      # @param [String] hex a valid hex string
+      # @return [String] binary string of bytes
+      # @raise [ArgumentError] if input is not valid hex
+      def hex_to_bytes(hex)
+        raise ArgumentError, "invalid hex string" unless hex_string?(hex)
+        [hex].pack("H*")
+      end
+
+      ##
+      # Convert raw bytes into a hex string.
+      #
+      # @param [String] bytes binary string
+      # @return [String] hex string
+      def bytes_to_hex(bytes)
+        bytes.unpack1("H*")
+      end
+
+      ##
+      # Convert an array of octets (integers 0-255) into raw bytes.
+      #
+      # @param [Array<Integer>] octets array of byte values
+      # @return [String] binary string of bytes
+      def octets_to_bytes(octets)
+        octets.pack("C*")
+      end
+
+      ##
+      # Check if a value is valid hex.
+      #
+      # @param [String] value
+      # @return [Boolean]
+      def hex_string?(value)
+        value.is_a?(String) && value.match?(/\A[0-9a-fA-F]+\z/) && value.length.even?
+      end
+
+      ##
+      # Check if a value looks like a raw byte string.
+      #
+      # @param [String] value
+      # @return [Boolean]
+      def byte_string?(value)
+        value.is_a?(String) && value.encoding == ::Encoding::BINARY
+      end
+
+      ##
+      # Checks if a value is an array of octets (integers 0-255)
+      #
+      # @param [Object] value
+      # @return [Boolean]
+      def octet_array?(value)
+        value.is_a?(Array) && value.all? { |b| b.is_a?(Integer) && b.between?(0, 255) }
+      end
+
+      ##
+      # Serialize a 32-bit unsigned integer to big-endian binary.
+      #
+      # Used in BIP32 child index encoding and serialization.
+      #
+      # @param i [Integer] integer in range 0..2^32-1
+      # @return [String] 4-byte big-endian representation
+      #
+      # @example
+      #   ser32(1)   # => "\x00\x00\x00\x01"
+      #   ser32(256) # => "\x00\x00\x01\x00"
+      def ser32(i)
+        [i].pack("N")
+      end
+
+      ##
+      # Serialize a 256-bit integer into a fixed-length 32-byte string.
+      #
+      # Pads with leading zeros if necessary. Used for private key
+      # and scalar encoding in BIP32.
+      #
+      # @param i [Integer] integer in range 0..2^256-1
+      # @return [String] 32-byte binary string
+      #
+      # @example
+      #   ser256(1).bytesize  # => 32
+      #   ser256(1).unpack1("H*") # => "0000...0001" (64 hex chars)
+      def ser256(i)
+        i.to_s(16).rjust(64, "0").scan(/../).map { |b| b.hex }.pack("C*")
+      end
+
+      ##
+      # Parse a 32-byte string into a 256-bit integer.
+      #
+      # Inverse of {#ser256}. Converts a big-endian binary
+      # string into an Integer.
+      #
+      # @param b [String] 32-byte binary string
+      # @return [Integer] integer value
+      #
+      # @example
+      #   i = 42
+      #   bin = ser256(i)
+      #   parse256(bin) # => 42
+      def parse256(b)
+        b.unpack1("H*").to_i(16)
+      end
+    end
+  end
+end

data/lib/skeleton_key/utils/hashing.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "digest"
+require "openssl"
+
+module SkeletonKey
+  module Utils
+    ##
+    # Collection of cryptographic hashing and HMAC utilities.
+    #
+    # This module wraps common digest primitives into clear,
+    # chainable methods with explicit names.
+    #
+    # These are the **building blocks** for higher-level functions
+    # like address encoding (Bitcoin), key derivation (BIP32/SLIP-10),
+    # and message authentication.
+    #
+    # @example Compute a Bitcoin address hash
+    #   pubkey = "\x02..." # compressed secp256k1 public key
+    #   addr_hash = SkeletonKey::Hashing.hash160(pubkey)
+    #
+    # @example Compute a BIP32 master key
+    #   seed = SecureRandom.random_bytes(64)
+    #   i = SkeletonKey::Hashing.hmac_sha512("Bitcoin seed", seed)
+    #
+    module Hashing
+      module_function
+      ##
+      # Generate n-byte checksum (first n bytes of double SHA256)
+      #
+      # @param payload [String] input byte string
+      # @return [String] n-byte checksum
+      def checksum(payload, length: 4)
+        double_sha256(payload)[0, length]
+      end
+
+      ##
+      # Single SHA-256 digest of data.
+      #
+      # @param data [String] input byte string
+      # @return [String] 32-byte binary digest
+      #
+      # @see https://en.wikipedia.org/wiki/SHA-2
+      def sha256(data)
+        Digest::SHA256.digest(data)
+      end
+
+      ##
+      # Single RIPEMD-160 digest of data.
+      #
+      # @param data [String] input byte string
+      # @return [String] 20-byte binary digest
+      #
+      # @see https://homes.esat.kuleuven.be/~bosselae/ripemd160/
+      def ripemd160(data)
+        Digest::RMD160.digest(data)
+      end
+
+      ##
+      # Hash160 = RIPEMD-160(SHA-256(data))
+      #
+      # Widely used in Bitcoin for address derivation from public keys.
+      #
+      # @param data [String] input byte string
+      # @return [String] 20-byte binary digest
+      #
+      # @example
+      #   SkeletonKey::Hashing.hash160(pubkey)
+      def hash160(data)
+        ripemd160(sha256(data))
+      end
+
+      ##
+      # Double SHA-256 digest.
+      #
+      # Used in Bitcoin for checksums and block header hashing.
+      #
+      # @param data [String] input byte string
+      # @return [String] 32-byte binary digest
+      #
+      # @example
+      #   SkeletonKey::Hashing.double_sha256("hello")
+      def double_sha256(data)
+        sha256(sha256(data))
+      end
+
+      ##
+      # HMAC-SHA512 keyed hash.
+      #
+      # Used in BIP32 master key and child key derivation.
+      #
+      # @param key [String] HMAC key
+      # @param data [String] message input
+      # @return [String] 64-byte binary HMAC digest
+      #
+      # @see https://en.wikipedia.org/wiki/HMAC
+      # @see https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki
+      #
+      # @example BIP32 master key
+      #   i = SkeletonKey::Hashing.hmac_sha512("Bitcoin seed", seed)
+      #   il, ir = i[0, 32], i[32, 32]
+      def hmac_sha512(key, data)
+        OpenSSL::HMAC.digest("SHA512", key, data)
+      end
+
+      def keccak256(data)
+        rate = 136
+        state = Array.new(25, 0)
+        offset = 0
+
+        while offset + rate <= data.bytesize
+          keccak_absorb_block(state, data.byteslice(offset, rate))
+          keccak_f1600(state)
+          offset += rate
+        end
+
+        tail = (data.byteslice(offset, data.bytesize - offset) || +"").b
+        tail << "\x01".b
+        tail << "\x00".b * (rate - tail.bytesize)
+        tail.setbyte(rate - 1, tail.getbyte(rate - 1) | 0x80)
+
+        keccak_absorb_block(state, tail)
+        keccak_f1600(state)
+        keccak_squeeze(state, 32)
+      end
+
+      def keccak_absorb_block(state, block)
+        (block.bytesize / 8).times do |idx|
+          lane_bytes = block.byteslice(idx * 8, 8).bytes
+          lane = lane_bytes.each_with_index.reduce(0) do |acc, (byte, byte_idx)|
+            acc | (byte << (8 * byte_idx))
+          end
+          state[idx] ^= lane
+        end
+      end
+
+      def keccak_squeeze(state, length)
+        output = +"".b
+        lane_index = 0
+
+        while output.bytesize < length
+          output << [state[lane_index]].pack("Q<")
+          lane_index += 1
+          if lane_index == 17 && output.bytesize < length
+            keccak_f1600(state)
+            lane_index = 0
+          end
+        end
+
+        output.byteslice(0, length)
+      end
+
+      def keccak_f1600(state)
+        24.times do |round|
+          c = 5.times.map do |x|
+            state[x] ^ state[x + 5] ^ state[x + 10] ^ state[x + 15] ^ state[x + 20]
+          end
+
+          d = 5.times.map do |x|
+            c[(x - 1) % 5] ^ keccak_rotl64(c[(x + 1) % 5], 1)
+          end
+
+          25.times do |idx|
+            state[idx] = (state[idx] ^ d[idx % 5]) & keccak_mask
+          end
+
+          b = Array.new(25, 0)
+          5.times do |x|
+            5.times do |y|
+              b[y + (5 * ((2 * x + 3 * y) % 5))] =
+                keccak_rotl64(state[x + (5 * y)], keccak_rotation_offsets[x][y])
+            end
+          end
+
+          5.times do |x|
+            5.times do |y|
+              idx = x + (5 * y)
+              state[idx] = b[idx] ^ ((~b[((x + 1) % 5) + (5 * y)]) & b[((x + 2) % 5) + (5 * y)])
+              state[idx] &= keccak_mask
+            end
+          end
+
+          state[0] ^= keccak_round_constants[round]
+        end
+      end
+
+      def keccak_rotl64(value, shift)
+        shift %= 64
+        return value & keccak_mask if shift.zero?
+
+        ((value << shift) | (value >> (64 - shift))) & keccak_mask
+      end
+
+      def keccak_mask
+        0xFFFF_FFFF_FFFF_FFFF
+      end
+
+      def keccak_rotation_offsets
+        [
+          [0, 36, 3, 41, 18],
+          [1, 44, 10, 45, 2],
+          [62, 6, 43, 15, 61],
+          [28, 55, 25, 21, 56],
+          [27, 20, 39, 8, 14]
+        ]
+      end
+
+      def keccak_round_constants
+        [
+          0x0000000000000001,
+          0x0000000000008082,
+          0x800000000000808A,
+          0x8000000080008000,
+          0x000000000000808B,
+          0x0000000080000001,
+          0x8000000080008081,
+          0x8000000000008009,
+          0x000000000000008A,
+          0x0000000000000088,
+          0x0000000080008009,
+          0x000000008000000A,
+          0x000000008000808B,
+          0x800000000000008B,
+          0x8000000000008089,
+          0x8000000000008003,
+          0x8000000000008002,
+          0x8000000000000080,
+          0x000000000000800A,
+          0x800000008000000A,
+          0x8000000080008081,
+          0x8000000000008080,
+          0x0000000080000001,
+          0x8000000080008008
+        ]
+      end
+    end
+  end
+end

data/lib/skeleton_key/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  # Current gem version.
+  #
+  # @return [String]
+  VERSION = "0.1.0"
+end

data/lib/skeleton_key.rb

@@ -0,0 +1,66 @@
+# Version
+require_relative "skeleton_key/version"
+
+# Main module for SkeletonKey
+require_relative "skeleton_key/constants"
+require_relative "skeleton_key/errors"
+
+# Utilities
+require_relative "skeleton_key/utils/hashing"
+require_relative "skeleton_key/utils/encoding"
+require_relative "skeleton_key/codecs/base58"
+require_relative "skeleton_key/codecs/base58_check"
+require_relative "skeleton_key/codecs/bech32"
+
+# Derivation methods
+require_relative "skeleton_key/derivation/path"
+require_relative "skeleton_key/derivation/bip32"
+require_relative "skeleton_key/derivation/slip10"
+
+# Core functionality
+require_relative "skeleton_key/core/entropy"
+require_relative "skeleton_key/recovery/slip39_support/protocol"
+require_relative "skeleton_key/recovery/slip39_support/share"
+require_relative "skeleton_key/recovery/slip39_support/bit_packing"
+require_relative "skeleton_key/recovery/slip39_support/checksum"
+require_relative "skeleton_key/recovery/slip39_support/interpolation"
+require_relative "skeleton_key/recovery/slip39_support/cipher"
+require_relative "skeleton_key/recovery/slip39_support/encoder"
+require_relative "skeleton_key/recovery/slip39_support/generated_set"
+require_relative "skeleton_key/recovery/slip39_support/decoder"
+require_relative "skeleton_key/recovery/slip39_support/secret_recovery"
+require_relative "skeleton_key/recovery/slip39_support/generator"
+require_relative "skeleton_key/recovery/slip39"
+
+# Higher-level abstractions
+require_relative "skeleton_key/recovery/bip39"
+require_relative "skeleton_key/seed"
+require_relative "skeleton_key/keyring"
+
+# Canonical chain namespace
+require_relative "skeleton_key/chains/bitcoin/support/versioning"
+require_relative "skeleton_key/chains/bitcoin/support/paths"
+require_relative "skeleton_key/chains/bitcoin/support/outputs"
+require_relative "skeleton_key/chains/bitcoin/support"
+require_relative "skeleton_key/chains/bitcoin/account_derivation"
+require_relative "skeleton_key/chains/bitcoin/account"
+require_relative "skeleton_key/chains/ethereum/support"
+require_relative "skeleton_key/chains/ethereum/account"
+require_relative "skeleton_key/chains/solana/support"
+require_relative "skeleton_key/chains/solana/account"
+
+module SkeletonKey
+  ##
+  # Top-level namespace for the SkeletonKey library.
+  #
+  # The file load order here reflects the repository architecture:
+  # - shared constants and typed errors
+  # - shared utilities and codecs
+  # - shared derivation primitives
+  # - recovery formats and seed normalization
+  # - chain-specific account implementations
+  class Error < StandardError; end
+
+  # Project root directory
+  ROOT = File.expand_path("..", __dir__)
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: skeleton_key
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sebastian Scholl
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: SkeletonKey provides deterministic wallet recovery, seed normalization,
+  and key derivation for Bitcoin, Ethereum, and Solana.
+email:
+- sebscholl@gmail.com
+executables:
+- console
+- lint
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/console
+- bin/lint
+- bin/setup
+- lib/skeleton_key.rb
+- lib/skeleton_key/chains/bitcoin/account.rb
+- lib/skeleton_key/chains/bitcoin/account_derivation.rb
+- lib/skeleton_key/chains/bitcoin/support.rb
+- lib/skeleton_key/chains/bitcoin/support/outputs.rb
+- lib/skeleton_key/chains/bitcoin/support/paths.rb
+- lib/skeleton_key/chains/bitcoin/support/versioning.rb
+- lib/skeleton_key/chains/ethereum/account.rb
+- lib/skeleton_key/chains/ethereum/support.rb
+- lib/skeleton_key/chains/solana/account.rb
+- lib/skeleton_key/chains/solana/support.rb
+- lib/skeleton_key/codecs/base58.rb
+- lib/skeleton_key/codecs/base58_check.rb
+- lib/skeleton_key/codecs/bech32.rb
+- lib/skeleton_key/constants.rb
+- lib/skeleton_key/core/entropy.rb
+- lib/skeleton_key/derivation/bip32.rb
+- lib/skeleton_key/derivation/path.rb
+- lib/skeleton_key/derivation/slip10.rb
+- lib/skeleton_key/errors.rb
+- lib/skeleton_key/keyring.rb
+- lib/skeleton_key/recovery/bip39.rb
+- lib/skeleton_key/recovery/bip39_english.txt
+- lib/skeleton_key/recovery/slip39.rb
+- lib/skeleton_key/recovery/slip39_support/bit_packing.rb
+- lib/skeleton_key/recovery/slip39_support/checksum.rb
+- lib/skeleton_key/recovery/slip39_support/cipher.rb
+- lib/skeleton_key/recovery/slip39_support/decoder.rb
+- lib/skeleton_key/recovery/slip39_support/encoder.rb
+- lib/skeleton_key/recovery/slip39_support/generated_set.rb
+- lib/skeleton_key/recovery/slip39_support/generator.rb
+- lib/skeleton_key/recovery/slip39_support/interpolation.rb
+- lib/skeleton_key/recovery/slip39_support/protocol.rb
+- lib/skeleton_key/recovery/slip39_support/secret_recovery.rb
+- lib/skeleton_key/recovery/slip39_support/share.rb
+- lib/skeleton_key/recovery/slip39_wordlist.txt
+- lib/skeleton_key/seed.rb
+- lib/skeleton_key/skeleton_key.code-workspace
+- lib/skeleton_key/utils/encoding.rb
+- lib/skeleton_key/utils/hashing.rb
+- lib/skeleton_key/version.rb
+homepage: https://github.com/sebscholl/skeleton-key
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sebscholl/skeleton-key
+  source_code_uri: https://github.com/sebscholl/skeleton-key
+  documentation_uri: https://github.com/sebscholl/skeleton-key#readme
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Deterministic wallet recovery and derivation across chains
+test_files: []