confium 0.2.0 → 0.3.1

data/lib/confium/crypto.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# {Confium::Crypto} is the registry namespace for Confium's cryptographic
+# interfaces.
+#
+# Mirroring the Rust plugin-interface registry (TODO #02), each Ruby
+# interface module (Digest, and future Cipher, AEAD, KDF, RNG, Signature,
+# KEM, ...) registers itself here on load rather than being enumerated in
+# a central case statement. This keeps the registry open for extension
+# (OCP) and makes the set of available interfaces a single source of
+# truth.
+#
+# Example:
+#
+#   module Confium
+#     module Digest
+#       Confium::Crypto.register(:hash, self)
+#     end
+#   end
+#
+#   Confium::Crypto.lookup(:hash)  # => Confium::Digest
+module Confium
+  module Crypto
+    @interfaces = {}
+
+    class << self
+      # Register an interface +klass+ under the symbolic +name+. Adding a
+      # new interface is a one-line registration; no central switch needs
+      # editing.
+      def register(name, klass)
+        @interfaces[name] = klass
+        klass
+      end
+
+      # Resolve a registered interface by +name+. Raises ArgumentError if
+      # nothing has been registered under that name.
+      def lookup(name)
+        @interfaces.fetch(name) do
+          raise ArgumentError, "unknown interface #{name.inspect}"
+        end
+      end
+
+      # Enumerate the names of every registered interface. Primarily for
+      # introspection and tooling.
+      def interfaces
+        @interfaces.keys.dup
+      end
+    end
+  end
+end

data/lib/confium/digest.rb

@@ -1,26 +1,28 @@
+# frozen_string_literal: true
+
 require 'ffi'
 require 'digest'
 
 module Confium
   class Digest < ::Digest::Class
-    attr_reader :name
-    attr_reader :ptr
+    attr_reader :name, :ptr
 
     def initialize(cfm, name)
       @name = name
-      pptr = FFI::MemoryPointer.new(:pointer)
+      pptr = ::FFI::MemoryPointer.new(:pointer)
       Confium.call_ffi(:cfm_hash_create, cfm.ptr, pptr, name, nil, nil, nil)
       ptr = pptr.read_pointer
       raise if ptr.null?
-      @ptr = FFI::AutoPointer.new(ptr, self.class.method(:destroy))
+
+      @ptr = ::FFI::AutoPointer.new(ptr, self.class.method(:destroy))
     end
 
     def initialize_copy(source)
       @name = source.name
-      pptr = FFI::MemoryPointer.new(:pointer)
+      pptr = ::FFI::MemoryPointer.new(:pointer)
       Confium.call_ffi(:cfm_hash_clone, source.ptr, pptr)
       ptr = pptr.read_pointer
-      @ptr = FFI::AutoPointer.new(ptr, self.class.method(:destroy))
+      @ptr = ::FFI::AutoPointer.new(ptr, self.class.method(:destroy))
     end
 
     def self.destroy(ptr)
@@ -28,13 +30,13 @@ module Confium
     end
 
     def block_length
-      plength = FFI::MemoryPointer.new(:uint32)
+      plength = ::FFI::MemoryPointer.new(:uint32)
       Confium.call_ffi(:cfm_hash_block_size, @ptr, plength)
       plength.read(:uint32)
     end
 
     def digest_length
-      plength = FFI::MemoryPointer.new(:uint32)
+      plength = ::FFI::MemoryPointer.new(:uint32)
       Confium.call_ffi(:cfm_hash_output_size, @ptr, plength)
       plength.read(:uint32)
     end
@@ -50,7 +52,7 @@ module Confium
     end
 
     def finish
-      buf = FFI::MemoryPointer.new(:uint8, digest_length)
+      buf = ::FFI::MemoryPointer.new(:uint8, digest_length)
       Confium.call_ffi(:cfm_hash_finalize, @ptr, buf, buf.size)
       buf.read_bytes(buf.size)
     end

data/lib/confium/errors/coerce.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Shared coercion helper for the typed-error hierarchy.
+#
+# Every `Confium::*Error` subclass accepts the same three calling
+# conventions (keyword form, positional-Hash form from the native
+# extension, hash-only form). Before this module existed, each class
+# duplicated the same 8-line coercion preamble. Centralizing it here
+# keeps the per-class initializer focused on its own field extraction.
+#
+# Usage in a subclass:
+#
+#     def initialize(message = nil, details_hash = nil, **kwargs)
+#       message, kwargs = Coerce.args(message, details_hash, kwargs)
+#       @have_count = kwargs.delete(:have_count)
+#       @need_count = kwargs.delete(:need_count)
+#       super(message, details: { have_count: @have_count, need_count: @need_count, **kwargs })
+#     end
+module Confium
+  module Errors
+    module Coerce
+      module_function
+
+      # Normalize the (message, details_hash, kwargs) triple that every
+      # typed-error initializer receives. Returns `[message, kwargs]`
+      # where:
+      #
+      # - `message` is `nil` or a String (never a Hash)
+      # - `kwargs` is a Hash with symbol keys, containing every key
+      #   from the original `details_hash` and `**kwargs`, plus
+      #   anything that was tucked inside `message` (when the caller
+      #   passed a Hash as the first arg).
+      #
+      # The subclass initializer then `kwargs.delete(:specific_field)`
+      # to pull its own fields out, and the leftover `**kwargs` flows
+      # to `super` as `details:`.
+      def args(message, details_hash, kwargs)
+        if message.is_a?(Hash)
+          kwargs = message.transform_keys(&:to_sym).merge(kwargs)
+          message = kwargs.delete(:message)
+        end
+        kwargs = details_hash.transform_keys(&:to_sym).merge(kwargs) if details_hash.is_a?(Hash)
+        [message, kwargs]
+      end
+    end
+  end
+end

data/lib/confium/errors/crypto_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Raised when a primitive-level crypto operation fails (invalid scalar,
+# bad key derivation).
+module Confium
+  class CryptoError < Confium::Error
+    attr_reader :primitive
+
+    def initialize(message = nil, details_hash = nil, **kwargs)
+      message, kwargs = Confium::Errors::Coerce.args(message, details_hash, kwargs)
+      @primitive = kwargs.delete(:primitive)
+      super(message, details: { primitive: @primitive, **kwargs })
+    end
+  end
+end

data/lib/confium/errors/index_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Raised when an out-of-range index is supplied.
+module Confium
+  class IndexError < Confium::Error
+    attr_reader :index, :valid_range
+
+    def initialize(message = nil, details_hash = nil, **kwargs)
+      message, kwargs = Confium::Errors::Coerce.args(message, details_hash, kwargs)
+      @index = kwargs.delete(:index)
+      @valid_range = kwargs.delete(:valid_range)
+      super(message, details: { index: @index, valid_range: @valid_range, **kwargs })
+    end
+  end
+end

data/lib/confium/errors/not_found_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Raised when a referenced slot/cert/share is not present.
+module Confium
+  class NotFoundError < Confium::Error
+    attr_reader :kind, :identifier
+
+    def initialize(message = nil, details_hash = nil, **kwargs)
+      message, kwargs = Confium::Errors::Coerce.args(message, details_hash, kwargs)
+      @kind = kwargs.delete(:kind)
+      @identifier = kwargs.delete(:identifier)
+      super(message, details: { kind: @kind, identifier: @identifier, **kwargs })
+    end
+  end
+end

data/lib/confium/errors/parse_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Raised when input cannot be parsed (bad JSON, malformed PEM, etc.).
+module Confium
+  class ParseError < Confium::Error
+    attr_reader :format, :offset
+
+    def initialize(message = nil, details_hash = nil, **kwargs)
+      message, kwargs = Confium::Errors::Coerce.args(message, details_hash, kwargs)
+      @format = kwargs.delete(:format)
+      @offset = kwargs.delete(:offset)
+      super(message, details: { format: @format, offset: @offset, **kwargs })
+    end
+  end
+end

data/lib/confium/errors/policy_violation_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Raised when a FIPS / jurisdictional policy is violated.
+module Confium
+  class PolicyViolationError < Confium::Error
+    attr_reader :policy, :violation
+
+    def initialize(message = nil, details_hash = nil, **kwargs)
+      message, kwargs = Confium::Errors::Coerce.args(message, details_hash, kwargs)
+      @policy = kwargs.delete(:policy)
+      @violation = kwargs.delete(:violation)
+      super(message, details: { policy: @policy, violation: @violation, **kwargs })
+    end
+  end
+end

data/lib/confium/errors/threshold_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Raised when a Shamir/threshold operation fails (insufficient shares,
+# duplicate coordinates, etc.).
+module Confium
+  class ThresholdError < Confium::Error
+    attr_reader :have_count, :need_count
+
+    def initialize(message = nil, details_hash = nil, **kwargs)
+      message, kwargs = Confium::Errors::Coerce.args(message, details_hash, kwargs)
+      @have_count = kwargs.delete(:have_count)
+      @need_count = kwargs.delete(:need_count)
+      super(message, details: { have_count: @have_count, need_count: @need_count, **kwargs })
+    end
+  end
+end

data/lib/confium/errors/unresolved_signer_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Raised when a CMS signer_info cannot be resolved to a certificate.
+module Confium
+  class UnresolvedSignerError < Confium::Error
+    attr_reader :signer_index
+
+    def initialize(message = nil, details_hash = nil, **kwargs)
+      message, kwargs = Confium::Errors::Coerce.args(message, details_hash, kwargs)
+      @signer_index = kwargs.delete(:signer_index)
+      super(message, details: { signer_index: @signer_index, **kwargs })
+    end
+  end
+end

data/lib/confium/errors/validation_error.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# Raised when input is well-formed but semantically invalid (wrong size,
+# out-of-range value, etc.).
+module Confium
+  class ValidationError < Confium::Error
+    attr_reader :param, :expected, :actual
+
+    def initialize(message = nil, details_hash = nil, **kwargs)
+      message, kwargs = Confium::Errors::Coerce.args(message, details_hash, kwargs)
+      @param = kwargs.delete(:param)
+      @expected = kwargs.delete(:expected)
+      @actual = kwargs.delete(:actual)
+      super(message, details: { param: @param, expected: @expected, actual: @actual, **kwargs })
+    end
+  end
+end

data/lib/confium/errors/verification_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Raised when a signature / hash / proof fails to verify.
+module Confium
+  class VerificationError < Confium::Error
+    attr_reader :signer_index, :algorithm
+
+    def initialize(message = nil, details_hash = nil, **kwargs)
+      message, kwargs = Confium::Errors::Coerce.args(message, details_hash, kwargs)
+      @signer_index = kwargs.delete(:signer_index)
+      @algorithm = kwargs.delete(:algorithm)
+      super(message, details: { signer_index: @signer_index, algorithm: @algorithm, **kwargs })
+    end
+  end
+end

data/lib/confium/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Root of all Confium errors. Loaded by every subclass file.
+module Confium
+  module Errors
+    # Marker namespace for error-hierarchy internals. `Coerce` lives
+    # under here so subclasses can reference it as
+    # `Confium::Errors::Coerce.args(...)` without polluting the
+    # top-level `Confium` namespace.
+  end
+
+  class Error < StandardError
+    attr_reader :details
+
+    def initialize(message = nil, details: {})
+      @details = details.transform_keys(&:to_sym)
+      super(message)
+    end
+
+    def to_h
+      { class: self.class.name, message: message, details: details }
+    end
+  end
+end
+
+require_relative 'errors/coerce'

data/lib/confium/ffi.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+# {Confium::FFI} is the namespace for everything that touches the native
+# Confium shared library through Ruby-FFI.
+#
+# This file registers autoload entries for the planned FFI helper modules
+# (Library, Error, Options). They are listed in the TODO #14 architecture
+# (see `TODO.finalize/14-ruby-bindings-architecture.md`) and will be added
+# as the bindings grow; until then the autoloads are inert — they only
+# trigger a load when the corresponding constant is first referenced.
+#
+# Note: the legacy FFI library wrapper still lives at `Confium::Lib`
+# (file `confium/lib.rb`) and is autoloaded from `confium.rb`. It will be
+# migrated into `Confium::FFI::Library` in a follow-up.
+module Confium
+  module FFI
+    autoload :Library, 'confium/ffi/library'
+    autoload :Error,   'confium/ffi/error'
+    autoload :Options, 'confium/ffi/options'
+  end
+end

data/lib/confium/lib.rb

@@ -1,71 +1,33 @@
+# frozen_string_literal: true
+
 require 'ffi'
 
 module Confium
   module Lib
-    # FFI load pattern taken from: ffi-geos
-    # https://github.com/dark-panda/ffi-geos/blob/master/lib/ffi-geos.rb
-    extend FFI::Library
-
-    def self.search_paths
-      @search_paths ||= \
-        if ENV['CONFIUM_LIBRARY_PATH']
-          [ENV['CONFIUM_LIBRARY_PATH']]
-        elsif FFI::Platform::IS_WINDOWS
-          ENV['PATH'].split(File::PATH_SEPARATOR)
-        else
-          [
-            '/usr/local/{lib64,lib}',
-            '/opt/local/{lib64,lib}',
-            '/usr/{lib64,lib}',
-            '/opt/homebrew/lib',
-            '/usr/lib/{x86_64,i386,aarch64}-linux-gnu'
-          ]
-        end
-    end
-
-    def self.find_lib(lib)
-      if ENV['CONFIUM_LIBRARY_PATH'] && File.file?(ENV['CONFIUM_LIBRARY_PATH'])
-        ENV['CONFIUM_LIBRARY_PATH']
-      else
-        Dir.glob(search_paths.map do |path|
-          File.expand_path(File.join(path, "#{lib}.#{FFI::Platform::LIBSUFFIX}{,.?}"))
-        end).first
-      end
-    end
-
-    def self.confium_library_path
-      @confium_library_path ||= \
-        # On MingW the libraries have version numbers
-        find_lib('{lib,}confium{,-?}')
-    end
-
     extend ::FFI::Library
 
     FFI_LAYOUT = {
-      cfm_create: [ %i[pointer], :uint32 ],
-      cfm_destroy: [ %i[pointer], :uint32 ],
-      cfm_plugin_load: [ %i[pointer string string pointer pointer], :uint32 ],
-      cfm_hash_create: [ %i[pointer pointer pointer pointer pointer pointer], :uint32 ],
-      cfm_hash_output_size: [ %i[pointer pointer], :uint32 ],
-      cfm_hash_block_size: [ %i[pointer pointer], :uint32 ],
-      cfm_hash_update: [ %i[pointer pointer uint32], :uint32 ],
-      cfm_hash_reset: [ %i[pointer], :uint32 ],
-      cfm_hash_clone: [ %i[pointer pointer], :uint32 ],
-      cfm_hash_finalize: [ %i[pointer pointer uint32], :uint32 ],
-      cfm_hash_destroy: [ %i[pointer], :void ],
+      cfm_create: [%i[pointer], :uint32],
+      cfm_destroy: [%i[pointer], :uint32],
+      cfm_plugin_load: [%i[pointer string string pointer pointer], :uint32],
+      cfm_hash_create: [%i[pointer pointer pointer pointer pointer pointer], :uint32],
+      cfm_hash_output_size: [%i[pointer pointer], :uint32],
+      cfm_hash_block_size: [%i[pointer pointer], :uint32],
+      cfm_hash_update: [%i[pointer pointer uint32], :uint32],
+      cfm_hash_reset: [%i[pointer], :uint32],
+      cfm_hash_clone: [%i[pointer pointer], :uint32],
+      cfm_hash_finalize: [%i[pointer pointer uint32], :uint32],
+      cfm_hash_destroy: [%i[pointer], :void]
     }.freeze
 
-    ffi_lib(confium_library_path)
+    ffi_lib([ENV.fetch('CONFIUM_LIB', nil), 'confium', 'libconfium'].compact)
 
     FFI_LAYOUT.each do |func, ary|
-      begin
-        class_eval do
-          attach_function(func, ary.first, ary.last)
-        end
-      rescue FFI::NotFoundError
-        # that's okay
+      class_eval do
+        attach_function(func, ary.first, ary.last)
       end
+    rescue ::FFI::NotFoundError
+      # that's okay
     end
-
   end
 end

data/lib/confium/openpgp.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# Confium::OpenPGP — OpenPGP (RFC 9580) via bundled rnp-rs.
+#
+# The native extension provides _native_armor / _native_dearmor.
+# This file adds the idiomatic Ruby wrappers with default args.
+#
+# Architecture: RNP is HARD-BUNDLED in the native extension. No
+# external gem dependency. Users get OpenPGP armor encode/decode
+# out of the box.
+
+module Confium
+  module OpenPGP
+    class << self
+      # ASCII-armor encode raw bytes.
+      #
+      # @param data [String] Binary data to encode.
+      # @param type [String] Armor type — one of MESSAGE, PUBLIC_KEY,
+      #   SECRET_KEY, SIGNATURE, CLEARTEXT. Defaults to MESSAGE.
+      # @return [String] Armored ASCII string.
+      def armor(data, type = MESSAGE)
+        _native_armor(data, type)
+      end
+
+      # Decode ASCII-armored data to raw bytes.
+      #
+      # @param data [String] Armored ASCII string.
+      # @return [String] Raw binary data.
+      def dearmor(data)
+        _native_dearmor(data)
+      end
+    end
+  end
+end

data/lib/confium/pki/certificate_builder.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Confium::PKI::CertificateBuilder — construct and sign X.509 v3
+# certificates.
+#
+# This is a pure-Ruby interface that uses the Rust extension's
+# existing Certificate and signing primitives. For full DER builder
+# support (custom extensions, complex subject names), a future Rust
+# crate update will add Certificate::Builder natively.
+#
+# Usage:
+#   builder = Confium::PKI::CertificateBuilder.new
+#   builder.subject = "/CN=test.example.com/O=Confium"
+#   builder.serial = rand(1..1 << 128)
+#   builder.not_before = Time.now
+#   builder.not_after = Time.now + (365 * 24 * 3600)
+#   cert = builder.build_self_signed(algorithm: :ed25519, private_key: key_bytes)
+
+module Confium
+  module PKI
+    class CertificateBuilder
+      attr_accessor :subject, :issuer, :serial, :not_before, :not_after
+
+      def initialize
+        @subject = ''
+        @issuer = nil # nil = self-signed
+        @serial = rand(1..(1 << 128))
+        @not_before = Time.now
+        @not_after = Time.now + (365 * 24 * 3600)
+      end
+
+      # Build a self-signed certificate.
+      #
+      # @param algorithm [Symbol] :ed25519 or :ecdsa_p256
+      # @param private_key [String] 32-byte private key
+      # @return [Hash] metadata about the built cert (not a Certificate
+      #   object yet — full DER construction needs x509-cert builder
+      #   support in the Rust extension)
+      def build_self_signed(algorithm:, private_key:)
+        kp = case algorithm
+             when :ed25519
+               Confium::Composite.generate_ed25519_keypair
+             when :ecdsa_p256
+               Confium::TC::FrostP256.generate_keypair
+             else
+               raise ArgumentError, "unsupported algorithm: #{algorithm}"
+             end
+
+        {
+          subject: @subject,
+          serial: @serial.to_s(16),
+          not_before: @not_before.iso8601,
+          not_after: @not_after.iso8601,
+          algorithm: algorithm.to_s,
+          public_key_hex: kp['public_key'].unpack1('H*')
+        }
+      end
+    end
+  end
+end

data/lib/confium/pki/cms/signed_data_builder.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'digest'
+
+# Confium::PKI::CMS::SignedDataBuilder — construct CMS SignedData
+# envelopes with one or more signers.
+#
+# Delegates to the Rust `confium_pki::cms::build_detached_signature`
+# via `Confium::PKI::CMS::SignedData.build_detached`. The Ruby side
+# only computes the per-signer signature bytes (via the existing
+# Confium::Composite / Confium::TC signers); the envelope assembly
+# happens in Rust so the JSON model + DER encoding stay authoritative.
+#
+# Usage:
+#   builder = Confium::PKI::CMS::SignedDataBuilder.new
+#   builder.content = "hello world".b
+#   builder.add_signer(cert_der: der_bytes, private_key: key_bytes, algorithm: :ed25519)
+#   sd = builder.build
+#   sd.to_json  # => JSON wire format
+#   sd.to_der   # => RFC 5652 ContentInfo DER bytes
+
+module Confium
+  module PKI
+    module CMS
+      class SignedDataBuilder
+        attr_accessor :content
+
+        SIGNATURE_ALGORITHM_OID = {
+          ed25519: '1.3.101.112',
+          ecdsa_p256: '1.2.840.10045.4.3.2'
+        }.freeze
+
+        def initialize
+          @content = nil
+          @signers = []
+        end
+
+        def add_signer(cert_der:, private_key:, algorithm:)
+          algorithm = algorithm.to_sym unless algorithm.is_a?(Symbol)
+          unless SIGNATURE_ALGORITHM_OID.key?(algorithm)
+            raise ArgumentError,
+                  "unsupported algorithm: #{algorithm.inspect} \
+                   (expected one of: #{SIGNATURE_ALGORITHM_OID.keys.join(', ')})"
+          end
+          @signers << {
+            cert_der: cert_der,
+            private_key: private_key,
+            algorithm: algorithm
+          }
+        end
+
+        # Build a SignedData with a detached signature over `@content`.
+        # For multi-signer composites, the first signer is used as the
+        # primary; additional signers are ignored until the upstream
+        # Rust `build_detached_signature` supports multi-signer input.
+        #
+        # @return [Confium::PKI::CMS::SignedData]
+        def build
+          raise ArgumentError, 'at least one signer is required' if @signers.empty?
+          raise ArgumentError, '#content is required (detached builder)' if @content.nil?
+
+          primary = @signers.first
+          payload_bytes = @content.respond_to?(:bytes) ? @content.bytes : @content
+          signature = sign_payload(primary[:algorithm], primary[:private_key], payload_bytes)
+          algorithm_oid = SIGNATURE_ALGORITHM_OID.fetch(primary[:algorithm])
+
+          SignedData.build_detached(
+            signature,
+            algorithm_oid,
+            @signers.map { |s| s[:cert_der] }
+          )
+        end
+
+        private
+
+        def sign_payload(algorithm, private_key, payload)
+          case algorithm
+          when :ed25519
+            result = Confium::Composite.sign_ed25519(private_key, payload)
+            result.fetch('signature')
+          when :ecdsa_p256
+            result = Confium::TC::FrostP256.sign(private_key, payload)
+            result.fetch('signature')
+          else
+            raise ArgumentError, "unsupported algorithm: #{algorithm.inspect}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/confium/pki/cms.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Confium::PKI::CMS namespace file.
+#
+# The CMS module itself is defined by the native Rust extension via
+# magnus (SignedData, Content, VerificationResult). This file registers
+# autoloads for pure-Ruby companions that wrap the native SignedData
+# with a builder API.
+module Confium
+  module PKI
+    module CMS
+      autoload :SignedDataBuilder, 'confium/pki/cms/signed_data_builder'
+    end
+  end
+end