confium 0.2.0 → 0.3.1

data/lib/confium/pki/cnml.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+# OIML CNML certificate profile definition.
+#
+# Defines the required X.509 extensions for measuring instrument
+# certificates per OIML R 76 (non-automatic weighing instruments)
+# and the broader CNML framework.
+#
+# This is an interface definition — the actual OIML R 76 PDF is a
+# paid publication. The extension OIDs listed here are from public
+# OIML documentation and the BIPM/CIPM MRA framework.
+
+module Confium
+  module PKI
+    module CNML
+      # Required X.509 v3 extensions for a CNML certificate.
+      REQUIRED_EXTENSIONS = {
+        # Standard X.509 extensions required by CNML:
+        '2.5.29.19' => 'basicConstraints (CA=true for IA certs, CA=false for leaf)',
+        '2.5.29.15' => 'keyUsage (digitalSignature for signing certs)',
+        '2.5.29.37' => 'extKeyUsage (id-kp-OCSPSigning or custom CNML OIDs)',
+        '2.5.29.14' => 'subjectKeyIdentifier (required for CMS signer resolution)',
+        '2.5.29.35' => 'authorityKeyIdentifier (required for chain building)'
+      }.freeze
+
+      # Optional but recommended extensions.
+      OPTIONAL_EXTENSIONS = {
+        '2.5.29.31' => 'cRLDistributionPoints (for revocation checking)',
+        '2.5.29.32' => 'certificatePolicies (CNML policy OID)',
+        '1.3.6.1.5.5.7.1.1' => 'authorityInfoAccess (OCSP responder URL)'
+      }.freeze
+
+      # CNML certificate roles (maps to ActorType in Confium::Identity).
+      CERT_ROLES = %i[
+        manufacturer
+        testing_lab
+        issuing_authority_officer
+        biml_director
+        quorum_coordinator
+        verifier
+      ].freeze
+
+      # Validate that a certificate has the required CNML extensions.
+      # This is a structural check (extension OID presence), not a
+      # semantic check (extension value correctness). Full validation
+      # requires the OIML R 76 specification.
+      #
+      # @param cert [Confium::PKI::Certificate] the cert to check
+      # @return [Array<String>] list of missing required extension OIDs
+      def self.missing_extensions(_cert)
+        # Full implementation requires parsing the cert's extensions,
+        # which needs the x509-cert crate exposed through the Ruby
+        # extension. For now, returns an empty array (no validation).
+        #
+        # TODO: when confium-pki exposes Certificate#extensions, walk
+        # the extension list and cross-reference against
+        # REQUIRED_EXTENSIONS.
+        []
+      end
+
+      # The list of required extension OIDs.
+      # @return [Array<String>]
+      def self.required_extension_oids
+        REQUIRED_EXTENSIONS.keys
+      end
+
+      # The list of optional extension OIDs.
+      # @return [Array<String>]
+      def self.optional_extension_oids
+        OPTIONAL_EXTENSIONS.keys
+      end
+
+      # All known CNML certificate roles.
+      # @return [Array<Symbol>]
+      def self.cert_roles
+        CERT_ROLES
+      end
+    end
+  end
+end

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.nil?
+        @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,126 @@
+# 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.
+
+module Confium
+  class 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
+end

data/lib/confium/tc/coordinator.rb

@@ -0,0 +1,68 @@
+# 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: 14_400)
+        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 }
+        return unless session[:commitments].length >= session[:threshold]
+
+        session[:state] = :commitments_collected
+      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,51 @@
+# 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.1'
 end