ct_merkle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a8fad35cd7103e96959b20d2175ae595debd401af2bb04339f6fc23fc85779bb
+  data.tar.gz: 68fad29c11401c6d9a83d6b0edaddfd48038b6de074e581043705ba648b04852
+SHA512:
+  metadata.gz: cca6fa98c9e29508d1b42b0083bbeda86d460edb845292e72d06121abde03a09617ba16bde3a854f7e95b89fd27de0cc5806d39fbd6b0f666d29b4b65aad2fd4
+  data.tar.gz: 3e44639499247aa25ec5e9ea238a55c72d58ef495c001a39bdd14720bcbae54e8db62b925fc120b172f1b6a96db11ca0e3b1217423cd220d1601a6a03e326802

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ken Tanaka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# ct_merkle
+
+[RFC 6962](https://www.rfc-editor.org/rfc/rfc6962) / [RFC 9162](https://www.rfc-editor.org/rfc/rfc9162) §2.1（Certificate Transparency）に準拠した、追記型マークルツリーの Ruby 実装。
+
+## 機能
+
+- 文字列または任意のハッシュ値を葉としてマークルツリーを作成
+- マークルツリーよりルートのハッシュ、包含証明、整合性証明を取得可能(過去の任意のサイズ時点のツリーからも取得可)
+- 外部から与えられた包含証明、整合性証明を検証可能
+- 検証手順は RFC 9162 §2.1.3.2 / §2.1.4.2 に準拠
+- [transparency-dev/merkle](https://github.com/transparency-dev/merkle) のテストベクタで動作を検証済み
+- 依存ライブラリなし
+
+## インストール
+
+```bash
+gem install ct_merkle
+
+# or
+
+bundle add ct_merkle
+```
+
+## 使い方
+
+### ツリー作成、包含証明
+
+```ruby
+# ツリーを作成
+tree  = CTMerkle::Tree.new(["a", "b", "c", "d"])
+
+# ルートハッシュ、"c"(=index:2)の包含証明を取得
+root  = tree.root
+proof = tree.inclusion_proof(2)
+
+# 包含証明の検証
+proof.verify(leaf_data: "c", root: root)   # => true
+proof.verify(leaf_data: "x", root: root)   # => false
+```
+
+### 追記型ログの整合性証明
+
+```ruby
+tree = CTMerkle::Tree.new
+tree.append("e0")
+tree << "e1" << "e2" << "e3" << "e4"
+tree.tree_size                        # => 5
+
+# ルートハッシュの取得(tree_sizeを指定するとその時点のルートハッシュを取得)
+root3 = tree.root(tree_size: 3)
+root5 = tree.root
+
+# 現在のツリーと tree_size:3 の時点のツリーの整合性証明
+cproof = tree.consistency_proof(3)
+cproof.verify(old_root: root3, new_root: root5)   # => true
+```
+
+### ツリーのスナップショット
+
+```ruby
+# tree.at(n)` は `tree_size: n` 時点の読み取り専用ツリーを返却する
+snap = tree.at(4)
+snap.root                    # tree.root(tree_size: 4) と同じ
+snap.inclusion_proof(0)      # tree.inclusion_proof(0, tree_size: 4) と同じ
+snap.consistency_proof(3)    # tree.consistency_proof(3, tree_size: 4) と同じ
+```
+
+### ハッシュ値からインデックスを取得
+
+```ruby
+h = CTMerkle::Hasher::SHA256.leaf("e2")
+tree.index_of(h)                  # => 2
+tree.inclusion_proof_by_hash(h)   # tree.inclusion_proof(2) と同じ
+```
+
+### 証明の検証
+
+```ruby
+## 包含証明
+# leaf_hash, leaf_index, tree_size, inclusion_path, root_hex が与えられた状態で
+# leaf_hash が root_hex のツリーに含まれることを検証する
+proof = CTMerkle::InclusionProof.new(
+  leaf_index: 2,
+  tree_size: 5,
+  inclusion_path: path_hex.map { CTMerkle::Digest.from_hex(_1) },
+)
+proof.verify!(leaf_hash: leaf_hash, root: CTMerkle::Digest.from_hex(root_hex))
+
+## 整合性証明
+# old_size, new_size, consistency_path, old_root_hex, new_root_hex が与えられた状態で
+# old_root_hex のツリーが new_root_hex のツリーの先頭部分そのままであることを検証する
+cproof = CTMerkle::ConsistencyProof.new(
+  old_size: 3,
+  new_size: 5,
+  consistency_path: path_hex.map { CTMerkle::Digest.from_hex(_1) },
+)
+cproof.verify!(
+  old_root: CTMerkle::Digest.from_hex(old_root_hex),
+  new_root: CTMerkle::Digest.from_hex(new_root_hex),
+)
+```
+
+### ハッシュ値
+
+ルートのハッシュ値は `CTMerkle::Digest` クラスで表現される。hex, base64, binary 文字列と相互変換可能
+
+```ruby
+d = tree.root
+d.to_hex       # => "33376a3b..."
+d.to_base64    # => "MzdqO9Y+..."
+d.to_binary    # => 生のバイト列（BINARY エンコーディング）
+
+CTMerkle::Digest.from_hex("33376a3b...")
+CTMerkle::Digest.from_base64("MzdqO9Y+...")
+```
+
+### 直列化
+
+包含証明、整合性証明は `to_h` / `from_h` で Hash と相互変換可能
+
+```ruby
+require "json"
+
+json = JSON.generate(tree.inclusion_proof(2).to_h)   # to_h はデフォルトでハッシュ値を hex でエンコーディングする
+# {"leaf_index":2,"tree_size":5,"inclusion_path":["...", "..."]}
+
+proof = CTMerkle::InclusionProof.from_h(JSON.parse(json))
+proof.to_h(encoding: :base64)                        # base64 エンコーディングを指定
+```
+
+Hashのキーは RFC 9162 の `InclusionProofDataV2` / `ConsistencyProofDataV2` のフィールド名に準拠
+
+### CT ログからの検証
+
+[RFC 6962 の JSON API](https://www.rfc-editor.org/rfc/rfc6962#section-4) の例
+
+```ruby
+# GET /ct/v1/get-sth
+sth  = JSON.parse(sth_body)
+root = CTMerkle::Digest.from_base64(sth["sha256_root_hash"])
+
+# GET /ct/v1/get-proof-by-hash?hash=...&tree_size=<sth["tree_size"]>
+res = JSON.parse(proof_body)
+proof = CTMerkle::InclusionProof.new(
+  leaf_index: res["leaf_index"],
+  tree_size: sth["tree_size"],
+  inclusion_path: res["audit_path"].map { CTMerkle::Digest.from_base64(_1) },
+)
+proof.verify(leaf_hash: leaf_hash, root: root)
+```
+
+### 参照
+
+- 各クラス・メソッドの仕様は [docs/reference.md](docs/reference.md) を参照
+
+## 開発
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+Docker を使う場合：
+
+```bash
+docker compose run --rm test        # Ruby 4.0
+docker compose run --rm test-3.x    # Ruby 3.x
+```
+
+`test/fixtures/transparency-dev` にあるテストベクタは [transparency-dev/merkle](https://github.com/transparency-dev/merkle) から取得したもの
+
+## ライセンス
+
+[MIT License](LICENSE.txt)

data/lib/ct_merkle/consistency_proof.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CTMerkle
+  # Proof that the tree of size old_size is a prefix of the tree of size
+  # new_size (RFC 9162 ConsistencyProofDataV2 without log_id).
+  ConsistencyProof = Data.define(:old_size, :new_size, :consistency_path) do
+    def self.from_h(hash, encoding: :hex)
+      h = Serialization.normalize_keys(hash, members)
+      new(
+        old_size: h[:old_size],
+        new_size: h[:new_size],
+        consistency_path: Serialization.decode_path(h[:consistency_path], encoding, "consistency_path"),
+      )
+    end
+
+    def initialize(old_size:, new_size:, consistency_path:)
+      raise ArgumentError, "old_size must be an Integer, got #{old_size.class}" unless old_size.is_a?(Integer)
+      raise ArgumentError, "new_size must be an Integer, got #{new_size.class}" unless new_size.is_a?(Integer)
+      unless consistency_path.is_a?(Array)
+        raise ArgumentError, "consistency_path must be an Array, got #{consistency_path.class}"
+      end
+
+      path = consistency_path.each_with_index.map { |h, i| Digest.wrap(h, "consistency_path[#{i}]") }.freeze
+      super(old_size: old_size, new_size: new_size, consistency_path: path)
+    end
+
+    def verify(old_root:, new_root:, hasher: Hasher::SHA256)
+      verify!(old_root: old_root, new_root: new_root, hasher: hasher)
+    rescue VerificationError
+      false
+    end
+
+    def verify!(old_root:, new_root:, hasher: Hasher::SHA256)
+      Verifier.verify_consistency!(
+        old_size: old_size,
+        new_size: new_size,
+        old_root: old_root,
+        new_root: new_root,
+        consistency_path: consistency_path,
+        hasher: hasher,
+      )
+    end
+
+    def to_h(encoding: :hex)
+      {
+        old_size: old_size,
+        new_size: new_size,
+        consistency_path: consistency_path.map { |d| Serialization.encode(d, encoding) },
+      }
+    end
+  end
+end

data/lib/ct_merkle/digest.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module CTMerkle
+  # An immutable hash value. The bytes are always held as a frozen BINARY
+  # String.
+  class Digest
+    HEX_PATTERN = /\A(?:[0-9a-fA-F]{2})*\z/
+
+    class << self
+      def from_hex(str)
+        raise ArgumentError, "hex must be a String, got #{str.class}" unless str.is_a?(String)
+        raise ArgumentError, "invalid hex string: #{str.inspect}" unless HEX_PATTERN.match?(str)
+
+        new([str].pack("H*"))
+      end
+
+      def from_base64(str)
+        raise ArgumentError, "base64 must be a String, got #{str.class}" unless str.is_a?(String)
+
+        bytes = begin
+          str.unpack1("m0")
+        rescue ArgumentError
+          raise ArgumentError, "invalid base64 string: #{str.inspect}"
+        end
+        new(bytes)
+      end
+
+      # Returns the bytes of a Digest or a String as a frozen BINARY String.
+      # Used internally to accept both kinds of arguments.
+      def bytes_of(value, name = "hash")
+        case value
+        when Digest then value.to_binary
+        when String then value.b.freeze
+        else raise ArgumentError, "#{name} must be a CTMerkle::Digest or a binary String, got #{value.class}"
+        end
+      end
+
+      # Wraps a Digest or a binary String as a Digest.
+      def wrap(value, name = "hash")
+        value.is_a?(Digest) ? value : new(bytes_of(value, name))
+      end
+    end
+
+    def initialize(bytes)
+      raise ArgumentError, "bytes must be a String, got #{bytes.class}" unless bytes.is_a?(String)
+
+      @bytes = bytes.b.freeze
+      freeze
+    end
+
+    def to_binary
+      @bytes
+    end
+
+    def to_hex
+      @bytes.unpack1("H*")
+    end
+
+    def to_base64
+      [@bytes].pack("m0")
+    end
+
+    alias to_s to_hex
+
+    def inspect
+      "#<#{self.class.name} #{to_hex}>"
+    end
+
+    def bytesize
+      @bytes.bytesize
+    end
+
+    # Compares bytes with another Digest or a String (encoding is ignored).
+    def ==(other)
+      case other
+      when Digest then @bytes == other.to_binary
+      when String then @bytes == other.b
+      else false
+      end
+    end
+
+    # Only Digests are eql?, so that #hash stays consistent.
+    def eql?(other)
+      other.is_a?(Digest) && @bytes.eql?(other.to_binary)
+    end
+
+    def hash
+      [Digest, @bytes].hash
+    end
+  end
+end

data/lib/ct_merkle/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CTMerkle
+  # Base class of all errors raised by this library.
+  # Invalid arguments are reported with the standard ArgumentError instead.
+  class Error < StandardError; end
+
+  # Raised by verify! when a proof does not verify.
+  class VerificationError < Error; end
+
+  # The proof is structurally invalid: wrong path length, index out of range,
+  # hash of the wrong size, and so on.
+  class MalformedProofError < VerificationError; end
+
+  # The root computed from the proof does not match the expected root.
+  class RootMismatchError < VerificationError; end
+end

data/lib/ct_merkle/hasher.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module CTMerkle
+  # Hashing strategies. A hasher responds to #leaf, #node, #empty_root and
+  # #digest_size, and works on binary Strings (not CTMerkle::Digest) because it
+  # is called for every node of the tree.
+  module Hasher
+    # The RFC 6962 / RFC 9162 hashing strategy with SHA-256.
+    module SHA256
+      LEAF_PREFIX = "\x00".b.freeze
+      NODE_PREFIX = "\x01".b.freeze
+      EMPTY_ROOT = ::Digest::SHA256.digest("").freeze
+
+      module_function
+
+      # HASH(0x00 || data)
+      def leaf(data)
+        d = ::Digest::SHA256.new
+        d.update(LEAF_PREFIX)
+        d.update(data)
+        d.digest
+      end
+
+      # HASH(0x01 || left || right)
+      def node(left, right)
+        d = ::Digest::SHA256.new
+        d.update(NODE_PREFIX)
+        d.update(left)
+        d.update(right)
+        d.digest
+      end
+
+      # HASH("") — the root of an empty tree.
+      def empty_root
+        EMPTY_ROOT
+      end
+
+      def digest_size
+        32
+      end
+    end
+  end
+end

data/lib/ct_merkle/inclusion_proof.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module CTMerkle
+  # Proof that a leaf is included in the tree of size tree_size
+  # (RFC 9162 InclusionProofDataV2 without log_id).
+  InclusionProof = Data.define(:leaf_index, :tree_size, :inclusion_path) do
+    def self.from_h(hash, encoding: :hex)
+      h = Serialization.normalize_keys(hash, members)
+      new(
+        leaf_index: h[:leaf_index],
+        tree_size: h[:tree_size],
+        inclusion_path: Serialization.decode_path(h[:inclusion_path], encoding, "inclusion_path"),
+      )
+    end
+
+    def initialize(leaf_index:, tree_size:, inclusion_path:)
+      raise ArgumentError, "leaf_index must be an Integer, got #{leaf_index.class}" unless leaf_index.is_a?(Integer)
+      raise ArgumentError, "tree_size must be an Integer, got #{tree_size.class}" unless tree_size.is_a?(Integer)
+      raise ArgumentError, "inclusion_path must be an Array, got #{inclusion_path.class}" unless inclusion_path.is_a?(Array)
+
+      path = inclusion_path.each_with_index.map { |h, i| Digest.wrap(h, "inclusion_path[#{i}]") }.freeze
+      super(leaf_index: leaf_index, tree_size: tree_size, inclusion_path: path)
+    end
+
+    # Exactly one of leaf_data: or leaf_hash: must be given.
+    def verify(root:, leaf_data: nil, leaf_hash: nil, hasher: Hasher::SHA256)
+      verify!(root: root, leaf_data: leaf_data, leaf_hash: leaf_hash, hasher: hasher)
+    rescue VerificationError
+      false
+    end
+
+    def verify!(root:, leaf_data: nil, leaf_hash: nil, hasher: Hasher::SHA256)
+      if leaf_data.nil? == leaf_hash.nil?
+        raise ArgumentError, "specify exactly one of leaf_data: or leaf_hash:"
+      end
+
+      unless leaf_data.nil? || leaf_data.is_a?(String)
+        raise ArgumentError, "leaf_data must be a String, got #{leaf_data.class}"
+      end
+
+      Verifier.verify_inclusion!(
+        leaf_hash: leaf_hash || hasher.leaf(leaf_data),
+        leaf_index: leaf_index,
+        tree_size: tree_size,
+        inclusion_path: inclusion_path,
+        root: root,
+        hasher: hasher,
+      )
+    end
+
+    def to_h(encoding: :hex)
+      {
+        leaf_index: leaf_index,
+        tree_size: tree_size,
+        inclusion_path: inclusion_path.map { |d| Serialization.encode(d, encoding) },
+      }
+    end
+  end
+end

data/lib/ct_merkle/serialization.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module CTMerkle
+  # Shared helpers for to_h / from_h of the proof classes.
+  module Serialization
+    ENCODINGS = %i[hex base64].freeze
+
+    module_function
+
+    def encode(digest, encoding)
+      case check_encoding!(encoding)
+      when :hex then digest.to_hex
+      when :base64 then digest.to_base64
+      end
+    end
+
+    def decode(value, encoding, name)
+      raise ArgumentError, "#{name} must be a String, got #{value.class}" unless value.is_a?(String)
+
+      case check_encoding!(encoding)
+      when :hex then Digest.from_hex(value)
+      when :base64 then Digest.from_base64(value)
+      end
+    end
+
+    def check_encoding!(encoding)
+      return encoding if ENCODINGS.include?(encoding)
+
+      raise ArgumentError, "encoding must be one of #{ENCODINGS.inspect}, got #{encoding.inspect}"
+    end
+
+    # Normalizes keys to Symbols and checks that exactly the expected keys exist.
+    def normalize_keys(hash, keys)
+      raise ArgumentError, "expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+      normalized = hash.to_h { |k, v| [k.is_a?(String) ? k.to_sym : k, v] }
+      raise ArgumentError, "duplicate keys in #{hash.keys.inspect}" if normalized.size != hash.size
+
+      missing = keys - normalized.keys
+      unknown = normalized.keys - keys
+      raise ArgumentError, "missing keys: #{missing.join(", ")}" unless missing.empty?
+      raise ArgumentError, "unknown keys: #{unknown.join(", ")}" unless unknown.empty?
+
+      normalized
+    end
+
+    def decode_path(value, encoding, name)
+      raise ArgumentError, "#{name} must be an Array, got #{value.class}" unless value.is_a?(Array)
+
+      value.each_with_index.map { |v, i| decode(v, encoding, "#{name}[#{i}]") }
+    end
+  end
+  private_constant :Serialization
+end

data/lib/ct_merkle/snapshot.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module CTMerkle
+  # A read-only view of a Tree at a fixed tree size, returned by Tree#at.
+  #
+  # The tree is append-only, so appending to the original Tree does not change
+  # what a Snapshot returns.
+  class Snapshot
+    attr_reader :tree_size
+    alias size tree_size
+
+    # Use Tree#at instead of calling this directly.
+    def initialize(tree, tree_size)
+      @tree = tree
+      @tree_size = tree_size
+      freeze
+    end
+
+    def root
+      @tree.root(tree_size: @tree_size)
+    end
+
+    def leaf_hash(index)
+      check_index!(index)
+      @tree.leaf_hash(index)
+    end
+
+    def index_of(leaf_hash)
+      index = @tree.index_of(leaf_hash)
+      index if index && index < @tree_size
+    end
+
+    def inclusion_proof(index)
+      @tree.inclusion_proof(index, tree_size: @tree_size)
+    end
+
+    def inclusion_proof_by_hash(leaf_hash)
+      @tree.inclusion_proof_by_hash(leaf_hash, tree_size: @tree_size)
+    end
+
+    def consistency_proof(old_size)
+      @tree.consistency_proof(old_size, tree_size: @tree_size)
+    end
+
+    def inspect
+      "#<#{self.class.name} tree_size=#{@tree_size}>"
+    end
+
+    private
+
+    def check_index!(index)
+      raise ArgumentError, "index must be an Integer, got #{index.class}" unless index.is_a?(Integer)
+      return if index.between?(0, @tree_size - 1)
+
+      raise ArgumentError, "index must be between 0 and #{@tree_size - 1}, got #{index}"
+    end
+  end
+end

data/lib/ct_merkle/tree.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module CTMerkle
+  # An append-only Merkle tree (RFC 6962 / RFC 9162 §2.1), held in memory.
+  #
+  # Every complete subtree hash is cached as leaves are appended, so the root
+  # and proofs for any past tree size are computed in O(log n).
+  class Tree
+    attr_reader :hasher
+
+    def initialize(leaves = [], hasher: Hasher::SHA256)
+      @hasher = hasher
+      # @levels[l][i] is the hash of the complete subtree that covers
+      # leaves [i * 2**l, (i + 1) * 2**l). @levels[0] holds the leaf hashes.
+      @levels = [[]]
+      @index = {}
+      leaves.each { |data| append(data) }
+    end
+
+    # Appends raw leaf data and returns the index of the new leaf.
+    def append(data)
+      raise ArgumentError, "leaf data must be a String, got #{data.class}" unless data.is_a?(String)
+
+      add_leaf_hash(@hasher.leaf(data).freeze)
+    end
+
+    def <<(data)
+      append(data)
+      self
+    end
+
+    # Appends an already computed leaf hash and returns the index of the new leaf.
+    def append_leaf_hash(leaf_hash)
+      add_leaf_hash(leaf_hash_bytes(leaf_hash))
+    end
+
+    def tree_size
+      @levels[0].size
+    end
+    alias size tree_size
+
+    def root(tree_size: self.tree_size)
+      check_tree_size!(tree_size)
+      Digest.new(tree_size.zero? ? @hasher.empty_root : subtree_hash(0, tree_size))
+    end
+
+    def leaf_hash(index)
+      check_index!(index, tree_size)
+      Digest.new(@levels[0][index])
+    end
+
+    # Index of the first leaf whose hash is leaf_hash, or nil.
+    def index_of(leaf_hash)
+      @index[leaf_hash_bytes(leaf_hash)]
+    end
+
+    def at(tree_size)
+      check_tree_size!(tree_size)
+      Snapshot.new(self, tree_size)
+    end
+
+    def inclusion_proof(index, tree_size: self.tree_size)
+      check_tree_size!(tree_size)
+      check_index!(index, tree_size)
+      path = audit_path(index, 0, tree_size).map { |h| Digest.new(h) }
+      InclusionProof.new(leaf_index: index, tree_size: tree_size, inclusion_path: path)
+    end
+
+    # Inclusion proof for the first leaf whose hash is leaf_hash, or nil when no
+    # such leaf exists in the tree of size tree_size.
+    def inclusion_proof_by_hash(leaf_hash, tree_size: self.tree_size)
+      check_tree_size!(tree_size)
+      index = index_of(leaf_hash)
+      return nil if index.nil? || index >= tree_size
+
+      inclusion_proof(index, tree_size: tree_size)
+    end
+
+    def consistency_proof(old_size, tree_size: self.tree_size)
+      check_tree_size!(tree_size)
+      raise ArgumentError, "old_size must be an Integer, got #{old_size.class}" unless old_size.is_a?(Integer)
+      raise ArgumentError, "old_size must be positive, got #{old_size}" unless old_size.positive?
+      if old_size > tree_size
+        raise ArgumentError, "old_size (#{old_size}) must not exceed tree_size (#{tree_size})"
+      end
+
+      path = old_size == tree_size ? [] : subproof(old_size, 0, tree_size, true)
+      ConsistencyProof.new(old_size: old_size, new_size: tree_size,
+                           consistency_path: path.map { |h| Digest.new(h) })
+    end
+
+    def inspect
+      "#<#{self.class.name} tree_size=#{tree_size}>"
+    end
+
+    private
+
+    def add_leaf_hash(bytes)
+      index = @levels[0].size
+      @levels[0] << bytes
+      @index[bytes] = index unless @index.key?(bytes)
+
+      # Cache every complete subtree that this leaf closes.
+      level = 0
+      i = index
+      while i.odd?
+        @levels[level + 1] ||= []
+        @levels[level + 1] << @hasher.node(@levels[level][i - 1], @levels[level][i]).freeze
+        level += 1
+        i >>= 1
+      end
+      index
+    end
+
+    # MTH(D[start:finish]). The ranges produced by the RFC 6962 recursion start
+    # at a multiple of the largest power of two that fits, so complete
+    # subtrees can be looked up directly.
+    def subtree_hash(start, finish)
+      n = finish - start
+      if n.nobits?(n - 1) # power of two: a cached complete subtree
+        level = n.bit_length - 1
+        return @levels[level][start >> level]
+      end
+
+      k = largest_power_of_two_below(n)
+      @hasher.node(subtree_hash(start, start + k), subtree_hash(start + k, finish))
+    end
+
+    # PATH(m, D[start:finish]) from RFC 9162 §2.1.3.1.
+    def audit_path(m, start, finish)
+      n = finish - start
+      return [] if n == 1
+
+      k = largest_power_of_two_below(n)
+      if m < k
+        audit_path(m, start, start + k) << subtree_hash(start + k, finish)
+      else
+        audit_path(m - k, start + k, finish) << subtree_hash(start, start + k)
+      end
+    end
+
+    # SUBPROOF(m, D[start:finish], b) from RFC 9162 §2.1.4.1.
+    def subproof(m, start, finish, complete)
+      n = finish - start
+      if m == n
+        return complete ? [] : [subtree_hash(start, finish)]
+      end
+
+      k = largest_power_of_two_below(n)
+      if m <= k
+        subproof(m, start, start + k, complete) << subtree_hash(start + k, finish)
+      else
+        subproof(m - k, start + k, finish, false) << subtree_hash(start, start + k)
+      end
+    end
+
+    # The largest power of two smaller than n (n > 1).
+    def largest_power_of_two_below(n)
+      1 << ((n - 1).bit_length - 1)
+    end
+
+    def leaf_hash_bytes(leaf_hash)
+      bytes = Digest.bytes_of(leaf_hash, "leaf_hash")
+      unless bytes.bytesize == @hasher.digest_size
+        raise ArgumentError, "leaf_hash must be #{@hasher.digest_size} bytes, got #{bytes.bytesize}"
+      end
+
+      bytes
+    end
+
+    def check_tree_size!(tree_size)
+      raise ArgumentError, "tree_size must be an Integer, got #{tree_size.class}" unless tree_size.is_a?(Integer)
+      return if tree_size.between?(0, self.tree_size)
+
+      raise ArgumentError, "tree_size must be between 0 and #{self.tree_size}, got #{tree_size}"
+    end
+
+    def check_index!(index, tree_size)
+      raise ArgumentError, "index must be an Integer, got #{index.class}" unless index.is_a?(Integer)
+      return if index.between?(0, tree_size - 1)
+
+      raise ArgumentError, "index must be between 0 and #{tree_size - 1}, got #{index}"
+    end
+  end
+end

data/lib/ct_merkle/verifier.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module CTMerkle
+  # Proof verification that does not need the tree itself.
+  #
+  # The algorithms follow RFC 9162 §2.1.3.2 (inclusion) and §2.1.4.2
+  # (consistency). Hash arguments accept CTMerkle::Digest or binary Strings.
+  module Verifier
+    module_function
+
+    # Returns true or false.
+    def verify_inclusion(leaf_hash:, leaf_index:, tree_size:, inclusion_path:, root:, hasher: Hasher::SHA256)
+      verify_inclusion!(leaf_hash: leaf_hash, leaf_index: leaf_index, tree_size: tree_size,
+                        inclusion_path: inclusion_path, root: root, hasher: hasher)
+    rescue VerificationError
+      false
+    end
+
+    # Returns true, or raises MalformedProofError / RootMismatchError.
+    def verify_inclusion!(leaf_hash:, leaf_index:, tree_size:, inclusion_path:, root:, hasher: Hasher::SHA256)
+      check_integer!(leaf_index, "leaf_index")
+      check_integer!(tree_size, "tree_size")
+      leaf = hash_bytes(leaf_hash, "leaf_hash", hasher)
+      expected_root = hash_bytes(root, "root", hasher)
+      path = path_bytes(inclusion_path, "inclusion_path", hasher)
+
+      if leaf_index.negative? || tree_size.negative?
+        raise MalformedProofError, "leaf_index and tree_size must not be negative"
+      end
+      # Step 1
+      if leaf_index >= tree_size
+        raise MalformedProofError, "leaf_index (#{leaf_index}) must be less than tree_size (#{tree_size})"
+      end
+
+      # Steps 2-3
+      fn = leaf_index
+      sn = tree_size - 1
+      r = leaf
+
+      # Step 4
+      path.each do |p|
+        raise MalformedProofError, "inclusion_path is too long" if sn.zero?
+
+        if fn.odd? || fn == sn
+          r = hasher.node(p, r)
+          until fn.odd? || fn.zero?
+            fn >>= 1
+            sn >>= 1
+          end
+        else
+          r = hasher.node(r, p)
+        end
+        fn >>= 1
+        sn >>= 1
+      end
+
+      # Step 5
+      raise MalformedProofError, "inclusion_path is too short" unless sn.zero?
+      raise RootMismatchError, "calculated root does not match the expected root" unless r == expected_root
+
+      true
+    end
+
+    # Returns true or false.
+    def verify_consistency(old_size:, new_size:, old_root:, new_root:, consistency_path:, hasher: Hasher::SHA256)
+      verify_consistency!(old_size: old_size, new_size: new_size, old_root: old_root, new_root: new_root,
+                          consistency_path: consistency_path, hasher: hasher)
+    rescue VerificationError
+      false
+    end
+
+    # Returns true, or raises MalformedProofError / RootMismatchError.
+    def verify_consistency!(old_size:, new_size:, old_root:, new_root:, consistency_path:, hasher: Hasher::SHA256)
+      check_integer!(old_size, "old_size")
+      check_integer!(new_size, "new_size")
+      first_hash = hash_bytes(old_root, "old_root", hasher)
+      second_hash = hash_bytes(new_root, "new_root", hasher)
+      path = path_bytes(consistency_path, "consistency_path", hasher)
+
+      raise MalformedProofError, "old_size and new_size must not be negative" if old_size.negative? || new_size.negative?
+      raise MalformedProofError, "old_size (#{old_size}) is greater than new_size (#{new_size})" if old_size > new_size
+      raise MalformedProofError, "a consistency proof from an empty tree is not defined" if old_size.zero?
+
+      if old_size == new_size
+        raise MalformedProofError, "consistency_path must be empty when old_size == new_size" unless path.empty?
+        raise RootMismatchError, "old_root and new_root differ although the sizes are equal" unless first_hash == second_hash
+
+        return true
+      end
+
+      # Step 1
+      raise MalformedProofError, "consistency_path is empty" if path.empty?
+
+      # Step 2
+      path = [first_hash, *path] if power_of_two?(old_size)
+
+      # Step 3
+      fn = old_size - 1
+      sn = new_size - 1
+
+      # Step 4
+      while fn.odd?
+        fn >>= 1
+        sn >>= 1
+      end
+
+      # Step 5
+      fr = sr = path.first
+
+      # Step 6
+      path.drop(1).each do |c|
+        raise MalformedProofError, "consistency_path is too long" if sn.zero?
+
+        if fn.odd? || fn == sn
+          fr = hasher.node(c, fr)
+          sr = hasher.node(c, sr)
+          until fn.odd? || fn.zero?
+            fn >>= 1
+            sn >>= 1
+          end
+        else
+          sr = hasher.node(sr, c)
+        end
+        fn >>= 1
+        sn >>= 1
+      end
+
+      # Step 7
+      raise MalformedProofError, "consistency_path is too short" unless sn.zero?
+      raise RootMismatchError, "calculated old root does not match old_root" unless fr == first_hash
+      raise RootMismatchError, "calculated new root does not match new_root" unless sr == second_hash
+
+      true
+    end
+
+    def power_of_two?(n)
+      n.positive? && n.nobits?(n - 1)
+    end
+
+    def check_integer!(value, name)
+      raise ArgumentError, "#{name} must be an Integer, got #{value.class}" unless value.is_a?(Integer)
+    end
+
+    def hash_bytes(value, name, hasher)
+      bytes = Digest.bytes_of(value, name)
+      unless bytes.bytesize == hasher.digest_size
+        raise MalformedProofError, "#{name} must be #{hasher.digest_size} bytes, got #{bytes.bytesize}"
+      end
+
+      bytes
+    end
+
+    def path_bytes(path, name, hasher)
+      raise ArgumentError, "#{name} must be an Array, got #{path.class}" unless path.is_a?(Array)
+
+      path.each_with_index.map { |h, i| hash_bytes(h, "#{name}[#{i}]", hasher) }
+    end
+
+    private_class_method :power_of_two?, :check_integer!, :hash_bytes, :path_bytes
+  end
+end

data/lib/ct_merkle/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CTMerkle
+  VERSION = "0.1.0"
+end

data/lib/ct_merkle.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "ct_merkle/version"
+require_relative "ct_merkle/errors"
+require_relative "ct_merkle/hasher"
+require_relative "ct_merkle/digest"
+require_relative "ct_merkle/serialization"
+require_relative "ct_merkle/verifier"
+require_relative "ct_merkle/inclusion_proof"
+require_relative "ct_merkle/consistency_proof"
+require_relative "ct_merkle/tree"
+require_relative "ct_merkle/snapshot"
+
+# RFC 6962 / RFC 9162 Merkle trees.
+module CTMerkle
+  # Computes the root of a tree built from leaves (raw data) in one call.
+  def self.root(leaves, hasher: Hasher::SHA256)
+    Tree.new(leaves, hasher: hasher).root
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: ct_merkle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ken Tanaka
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Merkle tree hashing, inclusion proofs and consistency proofs as defined
+  in RFC 6962 and RFC 9162 (Certificate Transparency), with no runtime dependencies.
+email:
+- tanaka-ken@netlab.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/ct_merkle.rb
+- lib/ct_merkle/consistency_proof.rb
+- lib/ct_merkle/digest.rb
+- lib/ct_merkle/errors.rb
+- lib/ct_merkle/hasher.rb
+- lib/ct_merkle/inclusion_proof.rb
+- lib/ct_merkle/serialization.rb
+- lib/ct_merkle/snapshot.rb
+- lib/ct_merkle/tree.rb
+- lib/ct_merkle/verifier.rb
+- lib/ct_merkle/version.rb
+homepage: https://github.com/xketanaka/ct_merkle
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/xketanaka/ct_merkle
+  bug_tracker_uri: https://github.com/xketanaka/ct_merkle/issues
+  documentation_uri: https://github.com/xketanaka/ct_merkle/blob/main/README.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Append-only Merkle trees compliant with RFC 6962 / RFC 9162
+test_files: []