confium 0.2.0 → 0.3.0

data/lib/confium/pki.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Confium::PKI namespace file.
+#
+# The PKI module itself is defined by the native Rust extension via
+# magnus at require time (see ext/confium_native/src/pki.rs). This file
+# registers pure-Ruby autoloads for the PKI submodules that wrap or
+# extend the native surface.
+module Confium
+  module PKI
+    autoload :CMS, "confium/pki/cms"
+  end
+end

data/lib/confium/policy.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Jurisdictional policy enforcement for Confium.
+#
+# Different jurisdictions require different algorithms and key sizes:
+#   - EU: no RSA < 2048, ECDSA P-256+ accepted, Ed25519 accepted
+#   - US: SHA-1 legacy accepted, ECDSA P-256 accepted
+#   - China: SM2/SM3/SM4 required (not currently implemented)
+#
+# Set the active policy via:
+#   Confium::Policy.jurisdiction = :eu
+#
+# When a policy is active, cert verification and signing operations
+# check the algorithm/key-size against the policy's allowed list.
+# Violations raise Confium::PolicyViolationError.
+
+module Confium
+  module Policy
+    @jurisdiction = nil
+    @fips_mode = false
+
+    # Built-in jurisdictional policies. Each is a Hash mapping
+    # algorithm name to minimum key bits.
+    JURISDICTIONS = {
+      # EU: eIDAS + GDPR alignment. RSA >= 2048, ECDSA P-256+.
+      eu: {
+        rsa:       2048,
+        ecdsa_p256: 256,
+        ecdsa_p384: 384,
+        ed25519:   256,
+        name:      "European Union (eIDAS)",
+      },
+      # US: NIST SP 800-131A. RSA >= 2048, ECDSA P-256+, SHA-1 legacy.
+      us: {
+        rsa:       2048,
+        ecdsa_p256: 256,
+        ecdsa_p384: 384,
+        ed25519:   256,
+        sha1_legacy: true,
+        name:      "United States (NIST SP 800-131A)",
+      },
+      # OIML CNML: international, follows BIPM recommendations.
+      cnml: {
+        rsa:       2048,
+        ecdsa_p256: 256,
+        ecdsa_p384: 384,
+        ed25519:   256,
+        name:      "OIML CNML (BIPM)",
+      },
+    }.freeze
+
+    class << self
+      # @return [Symbol, nil] the active jurisdiction (:eu, :us, :cnml)
+      attr_reader :jurisdiction
+
+      # @return [Boolean] whether FIPS 140 mode is enabled
+      attr_reader :fips_mode
+
+      # Set the active jurisdiction. When non-nil, all signing and
+      # verification operations check algorithms against the policy.
+      # @param value [Symbol, nil] one of JURISDICTIONS.keys or nil
+      # @raise [ArgumentError] if value is not a known jurisdiction
+      def jurisdiction=(value)
+        if value.nil?
+          @jurisdiction = nil
+          return
+        end
+        unless JURISDICTIONS.key?(value.to_sym)
+          raise ArgumentError,
+                "unknown jurisdiction: #{value} (known: #{JURISDICTIONS.keys.join(', ')})"
+        end
+        @jurisdiction = value.to_sym
+      end
+
+      # Enable/disable FIPS 140 mode. When enabled, only FIPS-approved
+      # algorithms are accepted. Ed25519 is NOT FIPS-approved (as of
+      # FIPS 186-5 draft); ECDSA P-256/P-384 are.
+      # @param value [Boolean]
+      def fips_mode=(value)
+        @fips_mode = !!value
+        @jurisdiction = :us if @fips_mode && @jurisdiction.nil?
+      end
+
+      # Check whether an algorithm + key size is allowed under the
+      # active policy.
+      # @param algorithm [String, Symbol] e.g. "rsa", "ecdsa_p256"
+      # @param key_bits [Integer] the key size in bits
+      # @return [Boolean]
+      # @raise [Confium::PolicyViolationError] if the algorithm is
+      #   disallowed or the key size is too small
+      def check!(algorithm, key_bits:)
+        alg = algorithm.to_sym
+
+        if @fips_mode
+          # FIPS mode: only FIPS-approved algorithms.
+          fips_approved = %i[ecdsa_p256 ecdsa_p384 rsa]
+          unless fips_approved.include?(alg)
+            raise Confium::PolicyViolationError.new(
+              "algorithm #{alg} is not FIPS-approved",
+              policy: :fips,
+              violation: :unapproved_algorithm,
+            )
+          end
+        end
+
+        return true unless @jurisdiction
+
+        policy = JURISDICTIONS[@jurisdiction]
+        return true unless policy
+
+        min_bits = policy[alg]
+        return true if min_bits.nil?
+
+        if key_bits < min_bits
+          raise Confium::PolicyViolationError.new(
+            "#{alg} key size #{key_bits} below #{min_bits} for #{@jurisdiction}",
+            policy: @jurisdiction,
+            violation: :key_too_small,
+          )
+        end
+
+        true
+      end
+
+      # The list of known jurisdiction identifiers.
+      # @return [Array<Symbol>]
+      def known_jurisdictions
+        JURISDICTIONS.keys
+      end
+
+      # Reset all policies to defaults (no jurisdiction, no FIPS).
+      def reset!
+        @jurisdiction = nil
+        @fips_mode = false
+      end
+    end
+  end
+end

data/lib/confium/secure_bytes.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# SecureBytes wraps sensitive cryptographic byte data (private keys,
+# Shamir shares, shared secrets) with zeroize-on-clear semantics.
+#
+# MRI Ruby's String is backed by a heap-allocated char buffer that
+# persists until GC. SecureBytes overwrites that buffer with zeros
+# when #clear is called (explicitly or via finalizer).
+#
+# Usage:
+#   key = Confium::SecureBytes.wrap(raw_bytes)
+#   key.bytes  # non-destructive read
+#   key.clear  # zeroize + deallocate
+#
+# After #clear, #bytes raises Confium::ClearedError.
+
+class Confium::SecureBytes
+  # Raised when #bytes is called after #clear.
+  class ClearedError < Confium::Error
+    def initialize(message = "SecureBytes already cleared")
+      super(message, details: {})
+    end
+  end
+
+  # Create a SecureBytes wrapping a copy of the given String.
+  # The original String's contents are NOT modified; callers should
+  # zeroize the original separately if needed.
+  # @param raw [String] binary String (any encoding; bytes are copied)
+  # @return [Confium::SecureBytes]
+  def self.wrap(raw)
+    new(raw)
+  end
+
+  # @api private
+  def initialize(raw)
+    @buffer = raw.dup.force_encoding(Encoding::ASCII_8BIT)
+    @cleared = false
+    # Register finalizer to zeroize if the object is GC'd without
+    # an explicit #clear call.
+    ObjectSpace.define_finalizer(self, finalizer_proc)
+  end
+
+  # Non-destructive read of the wrapped bytes.
+  # @return [String] binary String (ASCII-8BIT encoding)
+  # @raise [ClearedError] if #clear was already called
+  def bytes
+    raise ClearedError if @cleared
+
+    @buffer.dup
+  end
+
+  # Destructive read: returns a copy, then zeroizes the original.
+  # @return [String] binary String
+  # @raise [ClearedError] if #clear was already called
+  def bytes!
+    raise ClearedError if @cleared
+
+    copy = @buffer.dup
+    clear
+    copy
+  end
+
+  # Number of bytes. Returns 0 after #clear.
+  # @return [Integer]
+  def length
+    @cleared ? 0 : @buffer.bytesize
+  end
+
+  alias size length
+
+  # Whether the buffer has been cleared.
+  # @return [Boolean]
+  def cleared?
+    @cleared
+  end
+
+  # Zeroize the buffer immediately. Idempotent.
+  # @return [self]
+  def clear
+    return self if @cleared
+
+    # Overwrite every byte with 0x00 in place.
+    @buffer.replace("\x00" * @buffer.bytesize)
+    @buffer = nil
+    @cleared = true
+    self
+  end
+
+  # String representation for debugging. Does NOT expose the raw bytes.
+  # @return [String]
+  def inspect
+    if @cleared
+      "#<Confium::SecureBytes:0x#{object_id.to_s(16)} CLEARED>"
+    else
+      "#<Confium::SecureBytes:0x#{object_id.to_s(16)} #{length} bytes>"
+    end
+  end
+
+  private
+
+  # Finalizer proc that zeroizes the buffer if GC collects this
+  # object without an explicit #clear. Uses object_id to find the
+  # buffer — but since the buffer is an instance variable that may
+  # already be collected, this is a best-effort path. Explicit #clear
+  # is the recommended path.
+  # @return [Proc]
+  def finalizer_proc
+    method(:finalize)
+  end
+
+  # Called by the GC finalizer.
+  def finalize(_id)
+    # Best-effort: the buffer may already be collected by the time
+    # the finalizer runs. If @buffer still exists, zeroize it.
+    # This is a closure over the instance — MRI guarantees the
+    # finalizer runs after the object is unreachable but before
+    # the buffer's memory is reused.
+    return if @cleared
+
+    @buffer&.replace("\x00" * @buffer.bytesize)
+    @buffer = nil
+    @cleared = true
+  end
+end

data/lib/confium/tc/coordinator.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Confium::TC::Coordinator wraps the async session coordinator service.
+#
+# The coordinator enables globally distributed threshold signers to
+# participate when convenient — no simultaneity required.
+#
+# Usage:
+#   coordinator = Confium::TC::Coordinator.new(quorum_id: "biml-root")
+#   session_id = coordinator.create_session(message: data,
+#                                           threshold: 5,
+#                                           unlock_window: 14400)
+#   coordinator.submit_commitment(session_id, signer_id, commitment_bytes)
+#   # ... wait for T commitments ...
+#   coordinator.submit_share(session_id, signer_id, share_bytes)
+#   # ... wait for T shares ...
+#   signature = coordinator.aggregate(session_id)
+module Confium
+  module TC
+    class Coordinator
+      attr_reader :quorum_id, :sessions
+
+      def initialize(quorum_id:)
+        @quorum_id = quorum_id
+        @sessions = {}
+      end
+
+      def create_session(message:, threshold:, unlock_window: 14400)
+        session_id = "session-#{@sessions.length + 1}"
+        @sessions[session_id] = {
+          message: message,
+          threshold: threshold,
+          unlock_window: unlock_window,
+          state: :pending,
+          commitments: [],
+          shares: [],
+        }
+        session_id
+      end
+
+      def session_state(session_id)
+        @sessions.dig(session_id, :state)
+      end
+
+      def submit_commitment(session_id, signer_id, commitment_bytes)
+        session = @sessions[session_id] or raise "Unknown session: #{session_id}"
+        session[:commitments] << { signer_id: signer_id, bytes: commitment_bytes }
+        if session[:commitments].length >= session[:threshold]
+          session[:state] = :commitments_collected
+        end
+      end
+
+      def submit_share(session_id, signer_id, share_bytes)
+        session = @sessions[session_id] or raise "Unknown session: #{session_id}"
+        session[:shares] << { signer_id: signer_id, bytes: share_bytes }
+      end
+
+      def aggregate(session_id)
+        session = @sessions[session_id] or raise "Unknown session: #{session_id}"
+        raise "Threshold not met" if session[:shares].length < session[:threshold]
+        session[:state] = :completed
+        # In real implementation, calls FFI to aggregate shares
+        session[:shares].map { |s| s[:bytes] }.join
+      end
+    end
+  end
+end

data/lib/confium/tc/session.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "confium/lib"
+
+# Confium::TC::Session wraps a threshold cryptography session.
+#
+# A session represents one signing or decryption operation involving
+# T-of-N parties. The session goes through states: pending →
+# commitments_collected → shares_collected → completed.
+#
+# Usage:
+#   session = Confium::TC::Session.new(scheme: "FROST-ed25519",
+#                                      threshold: 3,
+#                                      num_parties: 5,
+#                                      party_index: 0)
+#   session.set_local_share(share_bytes)
+#   session.round(incoming_messages) # returns outgoing messages
+#   result = session.result if session.complete?
+module Confium
+  module TC
+    class Session
+      attr_reader :scheme, :threshold, :num_parties, :party_index, :state
+
+      def initialize(scheme:, threshold:, num_parties:, party_index:)
+        @scheme = scheme
+        @threshold = threshold
+        @num_parties = num_parties
+        @party_index = party_index
+        @state = :pending
+        @local_share = nil
+        @result = nil
+      end
+
+      def set_local_share(share_bytes)
+        raise ArgumentError, "share must be a String" unless share_bytes.is_a?(String)
+        @local_share = share_bytes
+      end
+
+      def complete?
+        @state == :completed
+      end
+
+      def result
+        raise "Session not complete" unless complete?
+        @result
+      end
+    end
+  end
+end

data/lib/confium/tc/session_stub.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Confium::TC::SessionStub — placeholder for the multi-party TC session
+# interface. The full Session implementation wraps
+# confium_tc::session::Session which drives 3-round FROST/CMP20/GG18
+# signing ceremonies.
+#
+# This stub provides the interface shape so consumers can write code
+# against it. The actual session orchestration will be wired through
+# magnus in a future PR (TODO.completion/009-multi-party-tc-sessions.md).
+
+module Confium
+  module TC
+    class SessionStub
+      attr_reader :scheme, :threshold, :party_count, :this_party_idx, :round
+
+      def initialize(scheme:, threshold:, party_count:, this_party_idx:)
+        @scheme = scheme
+        @threshold = threshold
+        @party_count = party_count
+        @this_party_idx = this_party_idx
+        @round = 0
+        @complete = false
+      end
+
+      def complete?
+        @complete
+      end
+
+      # Stub: returns an empty RoundResult. Real implementation will
+      # call confium_tc::session::Session::round_step.
+      def round_step(_incoming_messages)
+        @round += 1
+        @complete = @round >= 3  # FROST is 3 rounds
+        { outgoing: [], complete: @complete }
+      end
+
+      def result
+        nil  # Real implementation returns the signature/secret bytes.
+      end
+    end
+  end
+end

data/lib/confium/tc/share_file.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Confium
+  module TC
+    # Filesystem-backed share persistence.
+    #
+    # Share blobs produced by `Confium::TC::Cmp20.keygen` /
+    # `Confium::TC::Gg18.keygen` are 71-byte binary strings. This
+    # class wraps them in a JSON envelope so they can be saved to
+    # disk, transferred between hosts, and loaded back without
+    # encoding ambiguity.
+    #
+    # The envelope format:
+    #
+    #     {
+    #       "scheme":      "CMP20-ECDSA-P256",
+    #       "threshold":   3,
+    #       "party_count": 5,
+    #       "public_key":  "<33-byte hex>",
+    #       "shares":      ["<71-byte hex>", ...]
+    #     }
+    #
+    # The format is identical to what the Python binding's
+    # `confium.tc.ShareFile` produces, so shares saved from one
+    # binding can be loaded by the other.
+    class ShareFile
+      attr_reader :scheme, :threshold, :party_count, :public_key, :shares
+
+      def initialize(scheme:, threshold:, party_count:, public_key:, shares:)
+        @scheme = scheme
+        @threshold = threshold
+        @party_count = party_count
+        @public_key = public_key
+        @shares = shares
+      end
+
+      # Load a ShareFile from a JSON file at `path`.
+      def self.load(path)
+        from_json(File.read(path))
+      end
+
+      # Parse a ShareFile from a JSON string.
+      def self.from_json(json)
+        d = JSON.parse(json)
+        new(
+          scheme: d.fetch("scheme"),
+          threshold: d.fetch("threshold"),
+          party_count: d.fetch("party_count"),
+          public_key: [d.fetch("public_key")].pack("H*"),
+          shares: d.fetch("shares").map { |h| [h].pack("H*") },
+        )
+      end
+
+      # Save to `path` as JSON. Creates parent directories if missing.
+      def save(path)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, to_json)
+        self
+      end
+
+      # Serialize to a JSON string.
+      def to_json(*_args)
+        JSON.generate(
+          scheme: scheme,
+          threshold: threshold,
+          party_count: party_count,
+          public_key: public_key.unpack1("H*"),
+          shares: shares.map { |s| s.unpack1("H*") },
+        )
+      end
+
+      # Build a ShareFile from a CMP20 / GG18 keygen result Hash.
+      def self.from_keygen(scheme_name, keygen_result)
+        new(
+          scheme: scheme_name,
+          threshold: nil,        # not carried by the keygen Hash; caller knows
+          party_count: keygen_result["shares"].length,
+          public_key: keygen_result["public_key"],
+          shares: keygen_result["shares"],
+        )
+      end
+    end
+  end
+end

data/lib/confium/tc.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Confium::TC provides Ruby access to the threshold cryptography
+# interface exposed by the Confium Rust workspace.
+#
+# This module is loaded lazily via autoload from lib/confium.rb.
+# It wraps the C FFI surface for threshold sessions, coordinator,
+# re-sharing, and KEM operations.
+#
+# See: TODO.roadmap/04-threshold-cryptography.md in the main confium repo
+# for the full interface specification.
+module Confium
+  module TC
+    autoload :Session, "confium/tc/session"
+    autoload :Coordinator, "confium/tc/coordinator"
+  end
+end

data/lib/confium/transparency/ots.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Confium::Transparency::OTS — OpenTimestamps client interface.
+#
+# Wraps confium-transparency::ots::Client for anchoring Merkle tree
+# roots in the Bitcoin blockchain via OTS calendar servers.
+#
+# This is a pure-Ruby stub that defines the interface. The actual
+# OTS stamping requires network access to calendar servers and
+# will be wired through the Rust extension in a future PR
+# (TODO.completion/011-ots-ers-exposure.md).
+
+module Confium
+  module Transparency
+    module OTS
+      # Default OTS calendar servers (from opentimestamps.org).
+      DEFAULT_CALENDARS = %w[
+        https://a.pool.opentimestamps.org
+        https://b.pool.opentimestamps.org
+        https://a.pool.eternitywall.com
+      ].freeze
+
+      # An OTS receipt proving that a hash was anchored in Bitcoin
+      # at a specific block height.
+      class Receipt
+        attr_reader :bytes, :block_height
+
+        def initialize(bytes:, block_height: nil)
+          @bytes = bytes
+          @block_height = block_height
+        end
+
+        def to_bytes
+          @bytes
+        end
+      end
+
+      # Stamp a 32-byte hash via OTS calendar servers.
+      # Returns a Receipt (stub: returns nil — requires network).
+      #
+      # @param hash [String] 32-byte SHA-256 hash to anchor
+      # @return [Receipt, nil]
+      def self.stamp(_hash)
+        # Real implementation: calls the Rust OTS client which
+        # submits the hash to calendar servers and returns a
+        # merged proof. Requires network access.
+        nil
+      end
+
+      # Verify an OTS receipt against a hash.
+      # Returns true if the receipt proves the hash was anchored.
+      #
+      # @param receipt [Receipt, String] the OTS proof
+      # @param hash [String] the 32-byte hash
+      # @return [Boolean]
+      def self.verify(_receipt, _hash)
+        # Real implementation: calls the Rust OTS verifier which
+        # walks the Bitcoin blockchain proof.
+        false
+      end
+    end
+  end
+end

data/lib/confium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Confium
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/confium.rb

@@ -1,29 +1,59 @@
 # frozen_string_literal: true
 
-require_relative "confium/version"
+# Confium is the Ruby entry point for the Confium cryptographic framework.
+#
+# The native Rust extension is loaded first; everything else (Cert, CMS,
+# Composite, Transparency, TC::*, etc.) is registered by the extension
+# via magnus when this file is required.
+#
+# Pure-Ruby companions (the error hierarchy, Enumerable mixins, etc.)
+# are loaded lazily via autoload — see lib/confium/<name>.rb.
 
-module Confium
-  # class Error < StandardError; end
+require_relative "confium/version"
 
-  # def self.context
-  #   cfm = Confium::CFM.new
-  #   cfm.load_plugin('botan', ENV['CFM_HASH_BOTAN_PLUGIN_PATH'])
-  #   cfm
-  # end
+begin
+  require_relative "confium_native/confium_native"
+rescue LoadError => e
+  warn "confium: native extension not built — run `bundle exec rake compile`"
+  raise e
+end
 
-  def self.call_ffi_rc(fn, *args)
-    rc = Confium::Lib.method(fn).call(*args)
-    raise "FFI call to #{fn} failed (rc: #{rc})" unless rc.zero?
-    rc
-  end
+# Register autoloads on the native-defined PKI::CMS module so Ruby
+# companions like SignedDataBuilder load on first reference. Eager-
+# required because the module already exists at this point.
+require_relative "confium/pki/cms"
 
-  def self.call_ffi(fn, *args)
-    call_ffi_rc(fn, *args)
-    nil
-  end
+# The native extension defines Confium::OpenPGP with _native_armor /
+# _native_dearmor. This file adds the idiomatic Ruby wrappers with
+# default args. Eager-required for the same reason as PKI::CMS.
+require_relative "confium/openpgp"
 
+module Confium
+  # Error hierarchy autoloads. Each subclass lives in its own file so
+  # callers can `autoload :FooError, "confium/errors/foo"` and avoid
+  # loading the whole hierarchy if they only rescue one type.
+  autoload :Error,                "confium/errors"
+  autoload :ParseError,           "confium/errors/parse_error"
+  autoload :ValidationError,      "confium/errors/validation_error"
+  autoload :VerificationError,    "confium/errors/verification_error"
+  autoload :ThresholdError,       "confium/errors/threshold_error"
+  autoload :CryptoError,          "confium/errors/crypto_error"
+  autoload :NotFoundError,        "confium/errors/not_found_error"
+  autoload :IndexError,           "confium/errors/index_error"
+  autoload :UnresolvedSignerError,"confium/errors/unresolved_signer_error"
+  autoload :PolicyViolationError, "confium/errors/policy_violation_error"
+  autoload :SecureBytes,          "confium/secure_bytes"
+  autoload :Policy,               "confium/policy"
+  autoload :PKI,                  "confium/pki"
 end
 
-require_relative 'confium/lib'
-require_relative 'confium/cfm'
-require_relative 'confium/digest'
+# Eager-load the Audit Ruby companion. The native extension registers
+# `Confium::Audit` as a Ruby module with the `record`/`sink=`/`sink`
+# methods; the companion file defines the Sink class hierarchy on top
+# of that module.
+require_relative "confium/audit"
+
+# Eager-load the TC ShareFile Ruby companion. The native extension
+# defines `Confium::TC` as a Ruby module; this file adds the
+# `ShareFile` class for filesystem-backed share persistence.
+require_relative "confium/tc/share_file"