skeleton_key 0.1.0

data/lib/skeleton_key/chains/ethereum/support.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Chains
+    module Ethereum
+      ##
+      # Ethereum-specific serialization and address helpers.
+      #
+      # This module owns the Ethereum-facing parts of account derivation:
+      # - extended key version bytes used by the current API surface
+      # - EIP-55 checksum address rendering
+      # - rendering of Ethereum child paths below an account node
+      #
+      # It intentionally does not own the underlying secp256k1 arithmetic.
+      module Support
+        extend Utils::Hashing
+        extend Utils::Encoding
+
+        XPUB_VERSION = 0x0488B21E
+        XPRV_VERSION = 0x0488ADE4
+
+        module_function
+
+      # Returns the four-byte version used for serialized extended private keys.
+      #
+      # @return [String] big-endian 4-byte version
+        def extended_private_version
+          [XPRV_VERSION].pack("N")
+        end
+
+      # Returns the four-byte version used for serialized extended public keys.
+      #
+      # @return [String] big-endian 4-byte version
+        def extended_public_version
+          [XPUB_VERSION].pack("N")
+        end
+
+      # Converts an uncompressed secp256k1 public key into a checksummed
+      # Ethereum address per EIP-55.
+      #
+      # @param pubkey_uncompressed [String] 65-byte uncompressed public key
+      # @return [String] checksummed `0x...` Ethereum address
+        def to_checksum_address(pubkey_uncompressed)
+          address_bytes = keccak256(pubkey_uncompressed.byteslice(1, 64)).byteslice(-20, 20)
+          address_hex = bytes_to_hex(address_bytes)
+          address_hash = bytes_to_hex(keccak256(address_hex))
+
+          checksummed = address_hex.chars.each_with_index.map do |char, idx|
+            next char if char.match?(/[0-9]/)
+
+            address_hash[idx].hex >= 8 ? char.upcase : char
+          end.join
+
+          "0x#{checksummed}"
+        end
+
+      # Derives a child node below the current account/root node and returns the
+      # Ethereum-facing representation of that child.
+      #
+      # @param change [Integer] branch index
+      # @param index [Integer] child index within the branch
+      # @param hardened_change [Boolean] whether the branch step is hardened
+      # @param hardened_index [Boolean] whether the address step is hardened
+      # @return [Hash] rendered path, private key, public keys, address, and chain code
+        def derive_address_from_node(change: 0, index: 0, hardened_change: false, hardened_index: false)
+          k_int, chain_code = derived[:k_int], derived[:c]
+          change_index = hardened_change ? change | Derivation::Path::HARDENED_FLAG : change
+          address_index = hardened_index ? index | Derivation::Path::HARDENED_FLAG : index
+
+          k_int, chain_code = ckd_priv(k_int, chain_code, change_index)
+          k_int, chain_code = ckd_priv(k_int, chain_code, address_index)
+
+        pubkey_compressed = privkey_to_pubkey_compressed(k_int)
+        pubkey_uncompressed = privkey_to_pubkey_uncompressed(k_int)
+        ethereum_public_key = pubkey_uncompressed.byteslice(1, 64)
+
+          {
+            path: build_derived_path(change: change, index: index, hardened_change: hardened_change, hardened_index: hardened_index),
+            private_key: ser256(k_int).unpack1("H*"),
+            public_key: ethereum_public_key.unpack1("H*"),
+            compressed_public_key: pubkey_compressed.unpack1("H*"),
+            address: to_checksum_address(pubkey_uncompressed),
+            chain_code: chain_code,
+            privkey: k_int,
+            pubkey: ethereum_public_key
+          }
+        end
+
+      # Derives and serializes a branch node directly beneath the current
+      # account/root prefix.
+      #
+      # @param change [Integer] branch index
+      # @param hardened_change [Boolean] whether the branch child is hardened
+      # @return [Hash] branch path with serialized xprv/xpub
+        def derive_branch_extended_keys(change: 0, hardened_change: false)
+          parent_key = derived[:k_int]
+          parent_chain_code = derived[:c]
+          parent_pubkey = privkey_to_pubkey_compressed(parent_key)
+          child_num = hardened_change ? change | Derivation::Path::HARDENED_FLAG : change
+          branch_key, branch_chain_code = ckd_priv(parent_key, parent_chain_code, child_num)
+          branch_pubkey = privkey_to_pubkey_compressed(branch_key)
+
+          {
+            path: branch_derived_path(change: change, hardened_change: hardened_change),
+            xprv: serialize_xprv(
+              branch_key,
+              branch_chain_code,
+              depth: legacy_root_branch? ? 1 : 4,
+              parent_fpr: fingerprint_from_pubkey(parent_pubkey),
+              child_num: child_num,
+              version: extended_private_version
+            ),
+            xpub: serialize_xpub(
+              branch_pubkey,
+              branch_chain_code,
+              depth: legacy_root_branch? ? 1 : 4,
+              parent_fpr: fingerprint_from_pubkey(parent_pubkey),
+              child_num: child_num,
+              version: extended_public_version
+            )
+          }
+        end
+
+      # Renders the derived child path in canonical BIP32 string form.
+      #
+      # @return [String]
+        def build_derived_path(change:, index:, hardened_change:, hardened_index:)
+          rendered_change = hardened_change ? "#{change}'" : change.to_s
+          rendered_index = hardened_index ? "#{index}'" : index.to_s
+          "#{path}/#{rendered_change}/#{rendered_index}"
+        end
+
+      # Renders the derived branch path in canonical BIP32 string form.
+      #
+      # @return [String]
+        def branch_derived_path(change:, hardened_change:)
+          rendered_change = hardened_change ? "#{change}'" : change.to_s
+          "#{path}/#{rendered_change}"
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/chains/solana/account.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Chains
+    module Solana
+      ##
+      # Solana account derivation using hardened SLIP-0010 Ed25519 paths.
+      #
+      # Solana in SkeletonKey is intentionally hardened-only. This class owns the
+      # Solana path convention and turns a shared seed into Ed25519 key material
+      # and Base58 addresses, while the underlying SLIP-0010 math remains in the
+      # derivation layer.
+      #
+      # @example Derive the default wallet-style Solana address
+      #   account = SkeletonKey::Chains::Solana::Account.new(seed: seed.bytes)
+      #   account.address(change: 0)
+      class Account
+        include Support
+        include Derivation::SLIP10
+
+        # @return [Integer] derivation purpose, fixed at 44
+        # @return [Integer] SLIP-0044 coin type, fixed at 501 for Solana
+        # @return [Integer] account index within the Solana namespace
+        # @return [Hash] cached account-level key seed and chain code
+        attr_reader :purpose, :coin_type, :account_index, :derived
+
+        DEFAULT_PURPOSE = 44
+        SOLANA_COIN = 501
+        LEGACY_CHANGELESS_PURPOSE = 44
+
+        # @param seed [String] canonical seed bytes
+        # @param purpose [Integer] derivation purpose, fixed at 44
+        # @param coin_type [Integer] SLIP-0044 coin type, fixed at 501
+        # @param account_index [Integer] hardened account index
+        # @raise [Errors::UnsupportedPurposeError] if non-Solana path parameters are requested
+        def initialize(seed:, purpose: DEFAULT_PURPOSE, coin_type: SOLANA_COIN, account_index: 0)
+          @purpose = purpose
+          @coin_type = coin_type
+          @account_index = account_index
+          @derived = derive_from_seed(seed, purpose: purpose, coin_type: coin_type, account: account_index)
+        end
+
+        # Returns the hardened account prefix for future child derivation.
+        #
+        # @return [String]
+        def path
+          derived[:path_prefix]
+        end
+
+        # Derives a hardened Solana child path below the account prefix.
+        #
+        # In practice this supports both the shorter account-root convention and
+        # the wallet-style `.../change'/index'` convention used by many tools.
+        #
+        # @param change [Integer, nil] hardened child directly beneath the account
+        # @param index [Integer, nil] hardened child beneath the change node
+        # @return [Hash] path, private key, public key, address, and chain code
+        def address(change: 0, index: nil)
+          key_seed, chain_code = derived[:key_seed], derived[:chain_code]
+          current_path = path
+
+          unless change.nil?
+            current_path = "#{current_path}/#{change}'"
+            key_seed, chain_code = ckd_priv(key_seed, chain_code, hardened(change))
+          end
+
+          unless index.nil?
+            current_path = "#{current_path}/#{index}'"
+            key_seed, chain_code = ckd_priv(key_seed, chain_code, hardened(index))
+          end
+
+          private_key, public_key = keypair_from_seed(key_seed)
+
+          {
+            path: current_path,
+            private_key: private_key.unpack1("H*"),
+            public_key: public_key.unpack1("H*"),
+            address: to_address(public_key),
+            chain_code: chain_code
+          }
+        end
+
+        private
+
+        def derive_from_seed(seed_bytes, purpose:, coin_type:, account:)
+          raise Errors::UnsupportedPurposeError.new(purpose) unless purpose == 44
+          raise Errors::UnsupportedPurposeError.new(coin_type) unless coin_type == SOLANA_COIN
+
+          key_seed, chain_code = master_from_seed(seed_bytes)
+          # Every Solana child step is hardened. The path prefix stored here is
+          # the account node from which wallet-style descendants are derived.
+          [
+            hardened(purpose),
+            hardened(coin_type),
+            hardened(account)
+          ].each do |index|
+            key_seed, chain_code = ckd_priv(key_seed, chain_code, index)
+          end
+
+          {
+            path_prefix: "m/#{purpose}'/#{coin_type}'/#{account}'",
+            key_seed: key_seed,
+            chain_code: chain_code
+          }
+        end
+
+        # Encodes a child index as a hardened SLIP-0010 index.
+        #
+        # @param index [Integer]
+        # @return [Integer]
+        def hardened(index)
+          index | Derivation::SLIP10::HARDENED_FLAG
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/chains/solana/support.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Chains
+    module Solana
+      ##
+      # Solana-specific address helpers.
+      #
+      # Solana addresses are the raw Ed25519 public key bytes encoded with the
+      # Bitcoin-style Base58 alphabet. No hashing or script construction is
+      # applied at the address layer.
+      module Support
+        extend Utils::Encoding
+
+        module_function
+
+        # Encodes a 32-byte Ed25519 public key as a Solana address.
+        #
+        # @param public_key_bytes [String] 32-byte Ed25519 public key
+        # @return [String] Base58-encoded Solana address
+        def to_address(public_key_bytes)
+          Codecs::Base58.encode(public_key_bytes)
+        end
+      end
+    end
+  end
+end

data/lib/skeleton_key/codecs/base58.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Codecs
+    ##
+    # Raw Base58 codec using the Bitcoin alphabet.
+    #
+    # This module performs plain Base58 conversion only. It does not append or
+    # validate checksums; callers that need Base58Check should use
+    # {Base58Check}. The implementation preserves leading zero bytes as `"1"`
+    # characters to match Bitcoin-compatible tooling.
+    module Base58
+      ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz".freeze
+      INDEXES = ALPHABET.chars.each_with_index.to_h.freeze
+
+      module_function
+
+      # Encodes raw bytes as a Base58 string.
+      #
+      # @param bytes [String] binary payload
+      # @return [String] Base58 string
+      def encode(bytes)
+        return "" if bytes.empty?
+
+        zero_prefixes = bytes.bytes.take_while(&:zero?).size
+        value = bytes.unpack1("H*").to_i(16)
+        encoded = +""
+
+        while value.positive?
+          value, remainder = value.divmod(58)
+          encoded.prepend(ALPHABET[remainder])
+        end
+
+        ("1" * zero_prefixes) + encoded
+      end
+
+      # Decodes a Base58 string into raw bytes.
+      #
+      # @param encoded [String] Base58 string
+      # @return [String] decoded binary payload
+      # @raise [Errors::InvalidBase58Error] if the string contains invalid characters
+      def decode(encoded)
+        raise Errors::InvalidBase58Error if encoded.nil?
+        raise Errors::InvalidBase58Error unless encoded.is_a?(String)
+        raise Errors::InvalidBase58Error if encoded.empty?
+
+        value = 0
+        encoded.each_char do |char|
+          digit = INDEXES[char]
+          raise Errors::InvalidBase58Error unless digit
+
+          value = (value * 58) + digit
+        end
+
+        hex = value.to_s(16)
+        hex = "0#{hex}" if hex.length.odd?
+        decoded = hex.empty? ? +"".b : [hex].pack("H*")
+
+        leading_zeroes = encoded.each_char.take_while { |char| char == "1" }.size
+        ("\x00".b * leading_zeroes) + decoded
+      end
+    end
+  end
+end

data/lib/skeleton_key/codecs/base58_check.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Codecs
+    ##
+    # Base58Check codec used by Bitcoin-facing serialization.
+    #
+    # Base58Check appends a four-byte double-SHA256 checksum to the payload
+    # before Base58 encoding. This module owns checksum construction and
+    # verification, while {Base58} handles the underlying alphabet conversion.
+    module Base58Check
+      extend Utils::Hashing
+
+      module_function
+
+      # Encodes a payload with a four-byte checksum.
+      #
+      # @param payload [String] raw bytes to encode
+      # @return [String] Base58Check string
+      def encode(payload)
+        Base58.encode(payload + checksum(payload))
+      end
+
+      # Decodes and verifies a Base58Check string.
+      #
+      # @param encoded [String] Base58Check string
+      # @return [String] decoded payload without checksum bytes
+      # @raise [Errors::InvalidBase58Error] if the string is malformed
+      # @raise [Errors::InvalidChecksumError] if the checksum does not match
+      def decode(encoded)
+        decoded = Base58.decode(encoded)
+        raise Errors::InvalidBase58Error if decoded.bytesize < 4
+
+        payload = decoded.byteslice(0, decoded.bytesize - 4)
+        observed_checksum = decoded.byteslice(-4, 4)
+        raise Errors::InvalidChecksumError unless checksum(payload) == observed_checksum
+
+        payload
+      end
+    end
+  end
+end

data/lib/skeleton_key/codecs/bech32.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  module Codecs
+    ##
+    # Local Bech32 and Bech32m codec implementation.
+    #
+    # This module implements the exact checksum and charset rules needed for
+    # Bitcoin SegWit address encoding. It is intentionally generic at the codec
+    # boundary: HRP handling, checksum creation, and bit conversion live here,
+    # while script semantics remain in the Bitcoin layer.
+    module Bech32
+      CHARSET = "qpzry9x8gf2tvdw0s3jn54khce6mua7l".freeze
+      CHARSET_INDEX = CHARSET.chars.each_with_index.to_h.freeze
+      GENERATOR = [0x3b6a57b2, 0x26508e6d, 0x1ea119fa, 0x3d4233dd, 0x2a1462b3].freeze
+      SEPARATOR = "1"
+      MAX_LENGTH = 90
+
+      module Encoding
+        BECH32 = :bech32
+        BECH32M = :bech32m
+      end
+
+      module_function
+
+      # Encodes an HRP and 5-bit data words into a Bech32 or Bech32m string.
+      #
+      # @param hrp [String] human-readable prefix
+      # @param data [Array<Integer>] data words in the range 0..31
+      # @param encoding [Symbol] {Encoding::BECH32} or {Encoding::BECH32M}
+      # @return [String] encoded Bech32 string
+      def encode(hrp, data, encoding = Encoding::BECH32)
+        validate_hrp!(hrp)
+        validate_data!(data)
+
+        hrp = hrp.downcase
+        combined = data + create_checksum(hrp, data, encoding)
+        "#{hrp}#{SEPARATOR}#{combined.map { |value| CHARSET[value] }.join}"
+      end
+
+      # Decodes a Bech32/Bech32m string and validates its checksum.
+      #
+      # @param bech [String] encoded Bech32 string
+      # @return [Array(String, Array<Integer>, Symbol)] HRP, data words, encoding type
+      # @raise [Errors::InvalidBech32Error] if the string is malformed or the checksum fails
+      def decode(bech)
+        raise Errors::InvalidBech32Error unless bech.is_a?(String)
+        raise Errors::InvalidBech32Error if bech.empty? || bech.length > MAX_LENGTH
+
+        has_lower = bech.match?(/[a-z]/)
+        has_upper = bech.match?(/[A-Z]/)
+        raise Errors::InvalidBech32Error if has_lower && has_upper
+
+        normalized = bech.downcase
+        separator_index = normalized.rindex(SEPARATOR)
+        raise Errors::InvalidBech32Error if separator_index.nil?
+        raise Errors::InvalidBech32Error if separator_index < 1
+        raise Errors::InvalidBech32Error if separator_index + 7 > normalized.length
+
+        hrp = normalized[0...separator_index]
+        data_part = normalized[(separator_index + 1)..]
+        raise Errors::InvalidBech32Error if hrp.empty? || data_part.empty?
+
+        data = data_part.chars.map do |char|
+          value = CHARSET_INDEX[char]
+          raise Errors::InvalidBech32Error unless value
+
+          value
+        end
+
+        encoding = verify_checksum(hrp, data)
+        raise Errors::InvalidBech32Error unless encoding
+
+        [hrp, data[0...-6], encoding]
+      end
+
+      # Converts a stream of fixed-width integers into another width.
+      #
+      # This is the normalization step required when moving between raw bytes
+      # (8-bit values) and Bech32 witness program words (5-bit values).
+      #
+      # @param data [Array<Integer>] source values
+      # @param from_bits [Integer] bit width of each source value
+      # @param to_bits [Integer] desired bit width of each output value
+      # @param pad [Boolean] whether trailing zero padding is permitted
+      # @return [Array<Integer>]
+      # @raise [Errors::InvalidConvertBitsError] if the input cannot be losslessly converted
+      def convert_bits(data, from_bits, to_bits, pad)
+        acc = 0
+        bits = 0
+        result = []
+        maxv = (1 << to_bits) - 1
+        max_acc = (1 << (from_bits + to_bits - 1)) - 1
+
+        data.each do |value|
+          raise Errors::InvalidConvertBitsError if value.negative? || (value >> from_bits) != 0
+
+          acc = ((acc << from_bits) | value) & max_acc
+          bits += from_bits
+          while bits >= to_bits
+            bits -= to_bits
+            result << ((acc >> bits) & maxv)
+          end
+        end
+
+        if pad
+          result << ((acc << (to_bits - bits)) & maxv) if bits.positive?
+        elsif bits >= from_bits || ((acc << (to_bits - bits)) & maxv) != 0
+          raise Errors::InvalidConvertBitsError
+        end
+
+        result
+      end
+
+      # Creates the six checksum words for the given payload.
+      #
+      # @return [Array<Integer>]
+      def create_checksum(hrp, data, encoding)
+        constant = checksum_constant(encoding)
+        values = hrp_expand(hrp) + data
+        polymod = polymod(values + [0, 0, 0, 0, 0, 0]) ^ constant
+        6.times.map { |idx| (polymod >> (5 * (5 - idx))) & 31 }
+      end
+
+      # Verifies the checksum and returns the detected Bech32 encoding family.
+      #
+      # @return [Symbol, nil]
+      def verify_checksum(hrp, data)
+        value = polymod(hrp_expand(hrp) + data)
+        return Encoding::BECH32 if value == 1
+        return Encoding::BECH32M if value == 0x2bc830a3
+
+        nil
+      end
+
+      # Returns the checksum constant for the selected encoding family.
+      #
+      # @return [Integer]
+      def checksum_constant(encoding)
+        case encoding
+        when Encoding::BECH32 then 1
+        when Encoding::BECH32M then 0x2bc830a3
+        else
+          raise Errors::InvalidBech32Error, "unsupported bech32 encoding"
+        end
+      end
+
+      # Computes the Bech32 polymod checksum accumulator.
+      #
+      # @return [Integer]
+      def polymod(values)
+        chk = 1
+        values.each do |value|
+          top = chk >> 25
+          chk = ((chk & 0x1ffffff) << 5) ^ value
+          5.times do |idx|
+            chk ^= GENERATOR[idx] if ((top >> idx) & 1) == 1
+          end
+        end
+        chk
+      end
+
+      # Expands the HRP into the form required by the Bech32 checksum.
+      #
+      # @return [Array<Integer>]
+      def hrp_expand(hrp)
+        hrp.bytes.map { |byte| byte >> 5 } + [0] + hrp.bytes.map { |byte| byte & 31 }
+      end
+
+      def validate_hrp!(hrp)
+        raise Errors::InvalidBech32Error unless hrp.is_a?(String)
+        raise Errors::InvalidBech32Error if hrp.empty?
+        raise Errors::InvalidBech32Error unless hrp.bytes.all? { |byte| byte.between?(33, 126) }
+      end
+
+      def validate_data!(data)
+        raise Errors::InvalidBech32Error unless data.is_a?(Array)
+        raise Errors::InvalidBech32Error unless data.all? { |value| value.is_a?(Integer) && value.between?(0, 31) }
+      end
+    end
+  end
+end

data/lib/skeleton_key/constants.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module SkeletonKey
+  ##
+  # Core constants shared across the SkeletonKey library.
+  #
+  # These constants define valid seed and entropy lengths
+  # according to BIP-39 (mnemonics), SLIP-39 (Shamir mnemonics),
+  # and common cryptographic practice.
+  #
+  # @see https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki BIP-39
+  # @see https://github.com/satoshilabs/slips/blob/master/slip-0039.md SLIP-39
+  module Constants
+    ##
+    # Valid entropy lengths for mnemonic generation.
+    #
+    # BIP-39 specifies entropy sizes of 128–256 bits,
+    # in steps of 32 bits. These map to 12–24 words.
+    #
+    # @return [Array<Integer>] allowed entropy sizes in bytes
+    ENTROPY_LENGTHS = [16, 20, 24, 28, 32].freeze
+
+    ##
+    # Valid BIP39 mnemonic lengths in words.
+    #
+    # BIP39 supports 12, 15, 18, 21, and 24 word phrases.
+    #
+    # @return [Array<Integer>] allowed mnemonic word counts
+    MNEMONIC_WORD_COUNTS = [12, 15, 18, 21, 24].freeze
+
+    ##
+    # Valid master secret lengths for SLIP-39.
+    #
+    # SLIP-39 supports secrets of 128, 192, or 256 bits,
+    # which are represented as 16, 24, or 32 bytes.
+    #
+    # @return [Array<Integer>] allowed SLIP-39 master secret sizes
+    SLIP39_SECRET_LENGTHS = [16, 24, 32].freeze
+
+    ##
+    # Valid seed lengths for wallet derivation.
+    #
+    # - BIP-39 seeds are produced by PBKDF2 and are always 64 bytes (512 bits).
+    # - SLIP-39 master secrets are used directly and may be 16, 24, or 32 bytes.
+    #
+    # @return [Array<Integer>] allowed seed sizes in bytes
+    SEED_LENGTHS = (SLIP39_SECRET_LENGTHS + [64]).freeze
+
+    ##
+    # Standard length of a private key (secp256k1 or Ed25519).
+    #
+    # Both Bitcoin/Ethereum (secp256k1) and Solana (Ed25519)
+    # use 32-byte private keys.
+    #
+    # @return [Integer]
+    PRIVATE_KEY_LENGTH = 32
+
+    ##
+    # Standard length of a public key (compressed Ed25519 or secp256k1).
+    #
+    # - Ed25519 public keys are 32 bytes.
+    # - Compressed secp256k1 public keys are 33 bytes,
+    #   but the underlying X coordinate is 32 bytes.
+    #
+    # @return [Integer]
+    PUBLIC_KEY_LENGTH = 32
+  end
+end

data/lib/skeleton_key/core/entropy.rb

@@ -0,0 +1,37 @@
+module SkeletonKey
+  module Core
+    ##
+    # Cryptographically secure entropy generation.
+    #
+    # This module is the raw randomness boundary for SkeletonKey. It generates
+    # entropy suitable for seed creation and mnemonic generation, but it does
+    # not interpret that entropy as a chain-specific key or address.
+    module Entropy
+      # Generates cryptographically secure random entropy
+      #
+      # @param bytes [Integer] the number of random bytes to generate (default: 32)
+      # @param format [Symbol] the format of the output (:bytes, :octets, :hex)
+      # @return [String, Array<Integer>] the generated entropy in the specified format
+      # @raise [ArgumentError] if bytes is not a valid entropy length or format is invalid
+      def self.generate(bytes: 32, format: :bytes)
+        raise SkeletonKey::Errors::InvalidEntropyLengthError unless valid_entropy_lengths.include?(bytes)
+        raw = SecureRandom.random_bytes(bytes)
+
+        case format
+        when :bytes  then raw.freeze                  # binary string (32 bytes)
+        when :octets then raw.bytes.freeze            # array of byte values (32 integers)
+        when :hex    then raw.unpack1("H*")           # 64 hex chars for 32 bytes
+        else
+          raise SkeletonKey::Errors::InvalidEntropyFormatError
+        end
+      end
+
+      # Returns the valid byte sizes for entropy generation
+      #
+      # @return [Array<Integer>] valid byte sizes
+      def self.valid_entropy_lengths
+        SkeletonKey::Constants::ENTROPY_LENGTHS
+      end
+    end
+  end
+end