skeleton_key 0.1.0

data/lib/skeleton_key/derivation/bip32.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "digest"
+
+module SkeletonKey
+  module Derivation
+    module BIP32
+      # Utility modules
+      include Utils::Hashing
+      include Utils::Encoding
+
+      # Constants
+      CURVE = OpenSSL::PKey::EC.new("secp256k1")
+      GROUP = CURVE.group
+      ORDER = GROUP.order
+
+      module_function
+
+      # Create master key from seed
+      #
+      # @param seed_bytes [String] seed byte string
+      # @return [Array(Integer, String)] [master_privkey_int, master_chain_code] Master key result
+      def master_from_seed(seed_bytes)
+        i = hmac_sha512("Bitcoin seed", seed_bytes)
+
+        il = i[0, 32]
+        ir = i[32, 32]
+        k_int = parse256(il)
+
+        raise Errors::InvalidMasterKeyError if k_int <= 0 || k_int >= ORDER
+
+        [k_int, ir]
+      end
+
+      # Convert private key integer to compressed public key bytes
+      #
+      # @param k_int [Integer] private key as integer
+      # @return [String] compressed public key (33 bytes)
+      def privkey_to_pubkey_compressed(k_int)
+        raise Errors::InvalidPrivateKeyError if k_int <= 0 || k_int >= ORDER
+
+        bn = OpenSSL::BN.new(k_int.to_s(16), 16)
+        point = GROUP.generator.mul(bn)
+        point_to_bytes_compressed(point)
+      end
+
+      def privkey_to_pubkey_uncompressed(k_int)
+        raise Errors::InvalidPrivateKeyError if k_int <= 0 || k_int >= ORDER
+
+        bn = OpenSSL::BN.new(k_int.to_s(16), 16)
+        point = GROUP.generator.mul(bn)
+        point.to_octet_string(:uncompressed)
+      end
+
+      # Convert OpenSSL::PKey::EC::Point to compressed public key bytes
+      #
+      # @param point [OpenSSL::PKey::EC::Point] EC point
+      # @return [String] compressed public key (33 bytes)
+      def point_to_bytes_compressed(point)
+        point.to_octet_string(:compressed)
+      end
+
+      # Convert compressed public key bytes to OpenSSL::PKey::EC::Point
+      #
+      # @param pub_compressed [String] compressed public key (33 bytes)
+      # @return [OpenSSL::PKey::EC::Point] EC point
+      def bytes_to_point(pub_compressed)
+        # OpenSSL can parse a full EC::Point from octet string if we use PKey
+        key = OpenSSL::PKey::EC.new("secp256k1")
+        key.public_key = OpenSSL::PKey::EC::Point.new(GROUP, OpenSSL::BN.new(pub_compressed, 2))
+        key.public_key
+      end
+
+      # Compute the parent fingerprint for BIP32 serialization.
+      #
+      # Per BIP32: identifier = hash160(compressed_pubkey).
+      # The fingerprint is the first 4 bytes of this identifier.
+      #
+      # @param pubkey_compressed [String] compressed secp256k1 pubkey (33 bytes)
+      # @return [String] 4-byte binary fingerprint
+      def fingerprint_from_pubkey(pubkey_compressed)
+        hash160(pubkey_compressed)[0, 4]
+      end
+
+      # Serializes an extended private key (xprv)
+      #
+      # @param k_int [Integer] private key as integer
+      # @param chain_code [String] 32-byte chain code
+      # @param depth [Integer] depth in the derivation path
+      # @param parent_fpr [String] 4-byte parent fingerprint
+      # @param child_num [Integer] child index
+      # @param version [Integer] version byte (optional)
+      # @return [String] base58check-encoded xprv
+      def serialize_xprv(k_int, chain_code, depth:, parent_fpr:, child_num:, version: nil)
+        priv_version = version || version_byte(network: @network, purpose: @purpose, private: true)
+
+        payload = [
+          priv_version,
+          [depth].pack("C"),
+          parent_fpr,
+          ser32(child_num),
+          chain_code,
+          "\x00", ser256(k_int)
+        ].map(&:b).join
+
+        base58check_encode(payload)
+      end
+
+      # Serializes an extended public key (xpub)
+      #
+      # @param pubkey_bytes [String] compressed public key (33 bytes)
+      # @param chain_code [String] 32-byte chain code
+      # @param depth [Integer] depth in the derivation path
+      # @param parent_fpr [String] 4-byte parent fingerprint
+      # @param child_num [Integer] child index
+      # @param version [Integer] version byte (optional)
+      # @return [String] base58check-encoded xpub
+      def serialize_xpub(pubkey_bytes, chain_code, depth:, parent_fpr:, child_num:, version: nil)
+        pub_version = version || version_byte(network: @network, purpose: @purpose)
+
+        payload = [
+          pub_version,
+          [depth].pack("C"),
+          parent_fpr,
+          ser32(child_num),
+          chain_code,
+          pubkey_bytes
+        ].map(&:b).join
+
+        base58check_encode(payload)
+      end
+
+      # CDKpriv (hardened and non-hardened)
+      #
+      # @param k_parent_int [Integer] parent private key as integer
+      # @param c_parent [String] 32-byte parent chain code
+      # @param index [Integer] child index
+      # @return [Array(Integer, String)] [child_privkey_int, child_chain_code] CKDpriv result
+      def ckd_priv(k_parent_int, c_parent, index)
+        data =
+          if index >= 0x8000_0000
+            # hardened: 0x00 || ser256(k_par) || ser32(i)
+            "\x00" + ser256(k_parent_int) + ser32(index)
+          else
+            # non-hardened: serP(point(k_par)) || ser32(i)
+            pub = privkey_to_pubkey_compressed(k_parent_int)
+            pub + ser32(index)
+          end
+
+        i = hmac_sha512(c_parent, data)
+        il = parse256(i[0, 32])
+        ir = i[32, 32]
+        raise Errors::DerivationValueOutOfRangeError if il >= ORDER
+
+        child = (il + k_parent_int) % ORDER
+        raise Errors::InvalidDerivedKeyError if child == 0
+        [child, ir]
+      end
+
+      # CKDpub (non-hardened only)
+      #
+      # @param pub_parent_bytes [String] compressed public key (33 bytes)
+      # @param c_parent [String] 32-byte chain code
+      # @param index [Integer] child index (non-hardened only)
+      # @return [Array(String, String)] [child_pubkey_bytes, child_chain_code] CKDpub result
+      def ckd_pub(pub_parent_bytes, c_parent, index)
+        raise Errors::HardenedPublicDerivationError if index >= 0x8000_0000
+
+        i = hmac_sha512(c_parent, pub_parent_bytes + ser32(index))
+        il = parse256(i[0, 32])
+        ir = i[32, 32]
+        raise Errors::DerivationValueOutOfRangeError if il >= ORDER
+
+        # child_point = G*IL + K_par
+        child_point = GROUP.generator.mul(OpenSSL::BN.new(il.to_s(16), 16)) +
+                      bytes_to_point(pub_parent_bytes)
+        [point_to_bytes_compressed(child_point), ir]
+      end
+    end
+  end
+end

data/lib/skeleton_key/derivation/path.rb

@@ -0,0 +1,112 @@
+module SkeletonKey
+  module Derivation
+    # Represents a BIP32/44-style derivation path.
+    #
+    # Internally, each index is stored as a 32-bit integer.
+    # If the "hardened flag" (0x80000000) is set, the index is considered hardened.
+    # Logical values (purpose, coin_type, etc.) mask off this flag using INDEX_MASK (0x7fffffff).
+    #
+    # Example:
+    #   path = Path.new("m/44'/0'/0'/0/5")
+    #   path.purpose        # => 44
+    #   path.hardened?(0)   # => true
+    #   path.parts[0]       # => 2147483692 (raw index with hardened bit set)
+    #   path.to_s           # => "m/44'/0'/0'/0/5"
+    #
+    class Path
+      # Set if an index is hardened (2^31)
+      HARDENED_FLAG = 0x80000000
+
+      # Mask for stripping hardened flag
+      INDEX_MASK    = 0x7FFFFFFF
+
+      # Order of components in the path
+      ORDERED_KEYS  = %i[purpose coin_type account_index change address_index].freeze
+
+      # The full path string (e.g. "m/44'/0'/0'/0/0")
+      # @return [String]
+      attr_reader :original_path
+
+      # Encoded path components as integers (with hardened flag set if applicable)
+      # @return [Array<Integer>]
+      attr_reader :parts
+
+      # @param path_str [String] BIP32 path string (e.g. "m/44'/0'/0'/0/0")
+      def initialize(path_str)
+        @original_path = path_str
+        @parts = parse(path_str)
+
+        # Parse and set individual components
+        @purpose, @coin_type, @account_index, @change, @address_index = parts
+      end
+
+      # Determines if a component at the given index is hardened.
+      #
+      # @param index [Integer] index in the path array (0-based)
+      # @return [Boolean] true if hardened
+      # @raise [Errors::IndexOutOfBoundsError] if index is out of bounds
+      def hardened?(idx)
+        raise Errors::IndexOutOfBoundsError if idx < 0 || idx >= parts.size
+
+        (parts[idx] & HARDENED_FLAG) != 0
+      end
+
+      # Converts the internal representation back to a canonical string
+      #
+      # @return [String] e.g. "m/44'/0'/0'/0/0"
+      def to_s
+        parts.each_with_index.reduce('m') do |acc, (part, idx)|
+          decoded = decode(part)
+          "#{acc}/#{hardened?(idx) ? "#{decoded}'" : decoded}"
+        end
+      end
+
+      ORDERED_KEYS.each do |attr|
+        # Accessor that returns the index without the hardened flag
+        #
+        # @return [Integer] the index without hardened flag
+        define_method(attr) do
+          instance_variable_get("@#{attr}") & INDEX_MASK
+        end
+      end
+
+      private
+
+      # Parse a BIP32 path string into an array of indices
+      # @param path_str [String] BIP32 path string (e.g. "m/44'/0'/0'/0/0")
+      # @return [Array<Integer>] Array of indices
+      def parse(path_str)
+        raise Errors::InvalidPathFormatError unless path_str.start_with?("m/")
+
+        path_str.split("/").drop(1).map { |part| encode_index(part) }
+      end
+
+      # Parses the path part and hardens it accordingly
+      #
+      # @param idx_str [String] index string (e.g. "44" or "0'")
+      # @return [Integer] the encoded index
+      def encode_index(idx_str)
+        index = idx_str.to_i
+        hardened = idx_str.end_with?("'")
+        encode(index, hardened: hardened)
+      end
+
+      # Adds the hardened flag to an index if specified
+      #
+      # @param idx [Integer] the index
+      # @param hardened [Boolean] whether to harden the index
+      # @return [Integer] the encoded index
+      def encode(idx, hardened: false)
+        hardened ? idx | HARDENED_FLAG : idx
+      end
+
+      # Masks out the hardened flag from an encoded index
+      #
+      # @param raw_idx [Integer] the encoded index
+      # @return [Integer] the index without hardened flag
+      def decode(raw_idx)
+        raw_idx & INDEX_MASK
+      end
+    end
+  end
+end

data/lib/skeleton_key/derivation/slip10.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module SkeletonKey
+  module Derivation
+    ##
+    # Hardened-only SLIP-0010 derivation for Ed25519 keys.
+    #
+    # This module provides the shared derivation primitive used by Solana. It
+    # owns seed-to-master-key derivation, hardened child derivation, and
+    # deterministic Ed25519 keypair reconstruction from a 32-byte seed. It does
+    # not define any chain-specific path conventions or address formats.
+    module SLIP10
+      include Utils::Hashing
+      include Utils::Encoding
+
+      HARDENED_FLAG = 0x8000_0000
+      ED25519_PKCS8_PREFIX = "302e020100300506032b657004220420"
+      ED25519_PKCS8_PRIVATE_KEY_SIZE = 32
+      ED25519_SPKI_PUBLIC_KEY_SIZE = 32
+
+      module_function
+
+      # Derives the master key seed and chain code from a seed byte string.
+      #
+      # @param seed_bytes [String] canonical seed bytes
+      # @return [Array(String, String)] 32-byte key seed and 32-byte chain code
+      def master_from_seed(seed_bytes)
+        i = hmac_sha512("ed25519 seed", seed_bytes)
+        [i.byteslice(0, 32), i.byteslice(32, 32)]
+      end
+
+      # Derives a hardened SLIP-0010 child.
+      #
+      # Ed25519 SLIP-0010 does not support unhardened child derivation.
+      #
+      # @param parent_key [String] 32-byte parent key seed
+      # @param parent_chain_code [String] 32-byte parent chain code
+      # @param index [Integer] hardened child index
+      # @return [Array(String, String)] child key seed and child chain code
+      # @raise [Errors::UnsupportedDerivationIndexError] if a non-hardened index is requested
+      def ckd_priv(parent_key, parent_chain_code, index)
+        raise Errors::UnsupportedDerivationIndexError, "ed25519 SLIP-10 requires hardened indices" if index < HARDENED_FLAG
+
+        data = "\x00".b + parent_key + ser32(index)
+        i = hmac_sha512(parent_chain_code, data)
+        [i.byteslice(0, 32), i.byteslice(32, 32)]
+      end
+
+      # Reconstructs an Ed25519 keypair from a 32-byte seed.
+      #
+      # @param seed [String] 32-byte private seed
+      # @return [Array(String, String)] raw private key and raw public key
+      def keypair_from_seed(seed)
+        key = OpenSSL::PKey.read([ED25519_PKCS8_PREFIX + seed.unpack1("H*")].pack("H*"))
+        [raw_private_key(key), raw_public_key(key)]
+      end
+
+      # Extracts the 32-byte private seed from an Ed25519 key object.
+      #
+      # Some Ruby/OpenSSL builds expose `raw_private_key`; older builds only
+      # expose PKCS#8 DER serialization. The trailing 32 bytes of the PKCS#8
+      # structure are the original seed.
+      #
+      # @param key [OpenSSL::PKey::PKey] Ed25519 key object
+      # @return [String] 32-byte private seed
+      def raw_private_key(key)
+        return key.raw_private_key if key.respond_to?(:raw_private_key)
+
+        key.private_to_der.byteslice(-ED25519_PKCS8_PRIVATE_KEY_SIZE, ED25519_PKCS8_PRIVATE_KEY_SIZE)
+      end
+
+      # Extracts the 32-byte public key from an Ed25519 key object.
+      #
+      # Some Ruby/OpenSSL builds expose `raw_public_key`; older builds only
+      # expose SubjectPublicKeyInfo DER. The trailing 32 bytes of the SPKI
+      # structure are the Ed25519 public key bytes.
+      #
+      # @param key [OpenSSL::PKey::PKey] Ed25519 key object
+      # @return [String] 32-byte public key
+      def raw_public_key(key)
+        return key.raw_public_key if key.respond_to?(:raw_public_key)
+
+        key.public_to_der.byteslice(-ED25519_SPKI_PUBLIC_KEY_SIZE, ED25519_SPKI_PUBLIC_KEY_SIZE)
+      end
+    end
+  end
+end

data/lib/skeleton_key/errors.rb

@@ -0,0 +1,158 @@
+module SkeletonKey
+  module Errors
+    ##
+    # Base class for typed SkeletonKey failures.
+    #
+    # Typed errors are part of the repository contract. They allow callers and
+    # tests to distinguish invalid recovery material, unsupported derivation
+    # paths, and codec failures without pattern-matching free-form strings.
+    class SkeletonKeyError < StandardError; end
+
+    # Raised when seed material cannot be normalized to an allowed byte length.
+    class InvalidSeedError < SkeletonKeyError
+      def initialize(msg = "must be a byte string of length #{SkeletonKey::Constants::SEED_LENGTHS.inspect}")
+        super(msg)
+      end
+    end
+
+    # Raised when entropy length is outside the supported range.
+    class InvalidEntropyLengthError < SkeletonKeyError
+      def initialize(msg = "must be a byte string of length #{SkeletonKey::Constants::ENTROPY_LENGTHS.inspect}")
+        super(msg)
+      end
+    end
+
+    # Raised when a requested entropy output format is unsupported.
+    class InvalidEntropyFormatError < SkeletonKeyError
+      def initialize(msg = "must be one of :bytes, :hex, or :base64")
+        super(msg)
+      end
+    end
+
+    # Raised when a BIP39 mnemonic fails word-count, wordlist, or checksum validation.
+    class InvalidMnemonicError < SkeletonKeyError
+      def initialize(msg = "must be a BIP39 mnemonic with #{SkeletonKey::Constants::MNEMONIC_WORD_COUNTS.inspect} words")
+        super(msg)
+      end
+    end
+
+    # Raised when BIP39 generation parameters are invalid.
+    class InvalidMnemonicConfigurationError < SkeletonKeyError
+      def initialize(msg = "invalid BIP39 generation parameters")
+        super(msg)
+      end
+    end
+
+    # Raised when a SLIP-0039 share or share set fails validation or threshold checks.
+    class InvalidSlip39ShareError < SkeletonKeyError
+      def initialize(msg = "invalid SLIP-0039 share set")
+        super(msg)
+      end
+    end
+
+    # Raised when SLIP-0039 generation parameters are invalid.
+    class InvalidSlip39ConfigurationError < SkeletonKeyError
+      def initialize(msg = "invalid SLIP-0039 generation parameters")
+        super(msg)
+      end
+    end
+
+    # Raised when a derivation path string cannot be parsed.
+    class InvalidPathFormatError < SkeletonKeyError
+      def initialize(msg = "invalid path format")
+        super(msg)
+      end
+    end
+
+    # Raised when a caller requests a path component that does not exist.
+    class IndexOutOfBoundsError < SkeletonKeyError
+      def initialize(msg = "index out of bounds")
+        super(msg)
+      end
+    end
+
+    # Raised when seed material cannot produce a valid master key.
+    class InvalidMasterKeyError < SkeletonKeyError
+      def initialize(msg = "invalid master key")
+        super(msg)
+      end
+    end
+
+    # Raised when a private key falls outside the valid curve range.
+    class InvalidPrivateKeyError < SkeletonKeyError
+      def initialize(msg = "invalid private key")
+        super(msg)
+      end
+    end
+
+    # Raised when HMAC output yields an out-of-range derivation scalar.
+    class DerivationValueOutOfRangeError < SkeletonKeyError
+      def initialize(msg = "derived IL out of range")
+        super(msg)
+      end
+    end
+
+    # Raised when child key derivation lands on an invalid point or scalar.
+    class InvalidDerivedKeyError < SkeletonKeyError
+      def initialize(msg = "derived invalid key")
+        super(msg)
+      end
+    end
+
+    # Raised when hardened derivation is requested from public key material.
+    class HardenedPublicDerivationError < SkeletonKeyError
+      def initialize(msg = "cannot derive hardened child from public key")
+        super(msg)
+      end
+    end
+
+    # Raised when a chain account class does not support the requested purpose.
+    class UnsupportedPurposeError < SkeletonKeyError
+      def initialize(purpose)
+        super("unsupported purpose: #{purpose}")
+      end
+    end
+
+    # Raised when a purpose/network combination is not defined by the chain layer.
+    class UnsupportedPurposeNetworkError < SkeletonKeyError
+      def initialize(purpose:, network:)
+        super("unsupported purpose/network combination: purpose=#{purpose}, network=#{network}")
+      end
+    end
+
+    # Raised when Base58 input contains invalid characters or structure.
+    class InvalidBase58Error < SkeletonKeyError
+      def initialize(msg = "invalid base58 string")
+        super(msg)
+      end
+    end
+
+    # Raised when a serialized checksum does not match the payload.
+    class InvalidChecksumError < SkeletonKeyError
+      def initialize(msg = "invalid checksum")
+        super(msg)
+      end
+    end
+
+    # Raised when Bech32 or Bech32m input fails format or checksum validation.
+    class InvalidBech32Error < SkeletonKeyError
+      def initialize(msg = "invalid bech32 string")
+        super(msg)
+      end
+    end
+
+    # Raised when 5-bit/8-bit conversion cannot be performed losslessly.
+    class InvalidConvertBitsError < SkeletonKeyError
+      def initialize(msg = "invalid convert_bits input")
+        super(msg)
+      end
+    end
+
+    # Raised when a derivation family rejects the requested child index.
+    class UnsupportedDerivationIndexError < SkeletonKeyError
+      def initialize(msg = "unsupported derivation index")
+        super(msg)
+      end
+    end
+  end
+end

data/lib/skeleton_key/keyring.rb

@@ -0,0 +1,63 @@
+
+module SkeletonKey
+  ##
+  # SkeletonKey::Keyring
+  #
+  # The {Keyring} class is the entry point for working with chain-agnostic key
+  # material. It encapsulates a master {Seed} and exposes convenience accessors
+  # for deriving accounts on supported blockchains (e.g. Bitcoin, Ethereum,
+  # Solana).
+  #
+  # A {Keyring} can be initialized with:
+  # - a raw byte string (32–64 bytes),
+  # - a hex-encoded seed string,
+  # - an array of octets (Array<Integer>),
+  # - another {Seed} instance,
+  # - or nothing (in which case a new random seed will be generated).
+  #
+  # Each plugin (e.g. {SkeletonKey::Chains::Bitcoin::Account}) receives the canonical
+  # {Seed} and is responsible for deriving its own keys according to the
+  # chain’s standard derivation path (BIP44, BIP84, SLIP-10, etc.).
+  #
+  # @example Generate a new keyring with a random seed
+  #   keyring = SkeletonKey::Keyring.new
+  #   account = keyring.bitcoin
+  #
+  # @example Initialize from an existing hex seed
+  #   keyring = SkeletonKey::Keyring.new(seed: "2df1184bbb5ee0e4303d6db3b4013284")
+  #   account = keyring.bitcoin(purpose: 84, coin_type: 0, account: 0)
+  #
+  # @see SkeletonKey::Seed
+  # @see SkeletonKey::Chains::Bitcoin::Account
+  class Keyring
+    # Initializes a new Keyring with an optional seed
+    #
+    # @param seed [String, Seed, Array<Integer>, nil] the seed to initialize the Keyring with (optional)
+    # @return [Keyring] the initialized Keyring
+    def initialize(seed: nil)
+      @seed = Seed.import(seed)
+    end
+
+    # Access the Bitcoin account derived from the seed
+    #
+    # @param kwargs [Hash] options to pass to Chains::Bitcoin::Account
+    # @return [Chains::Bitcoin::Account] the derived Bitcoin account
+    def bitcoin(**)
+      SkeletonKey::Chains::Bitcoin::Account.new(seed: seed.bytes, **)
+    end
+
+    def ethereum(**)
+      SkeletonKey::Chains::Ethereum::Account.new(seed: seed.bytes, **)
+    end
+
+    def solana(**)
+      SkeletonKey::Chains::Solana::Account.new(seed: seed.bytes, **)
+    end
+
+    private
+
+    # Reader for the seed
+    # @return [Seed] the seed
+    attr_reader :seed
+  end
+end