confium 0.3.2 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8445c7b4b7f4fdea4740a5f22874c5a97eda59e75ebe5cf327dbc84b67ff6f2
-  data.tar.gz: 68381a40a3a7f21b5f4330611bbe86e7abbf9223602288f105f611553e86cd21
+  metadata.gz: 4c325019a3961cbf877d81c11496cfccba51959282d930b1e5e0420b25b66958
+  data.tar.gz: 91ea66bd4a9541e38ce7c01c03c26408a8372debdce0539c13ab70aee4895970
 SHA512:
-  metadata.gz: 00cf2dd64ba0bce3897db2d5f026818ccc5f90cc1ad1f27a65869827f530811df1a60c50e6fefeb9c83183859bccce81194b0e031e2fbff5b8213d53bb3cb4cb
-  data.tar.gz: a2f6509125418022a2aa3d98d86b724cc841f7f3067884c482d345f2f3b28a0adb63b51dbba34d48dd5d64aa1c827a42d8bf86be273160feb631d5e8a68b72b9
+  metadata.gz: e70d630fd442cf891ff15cdd27fc335281488ca5c5985f298337559ad9caf2dfb77bdf7993dd47f766116512bff4e3a53e2939b55cc8b91f77744176780faaf5
+  data.tar.gz: 3f389ce934ed8f8f81bb13e87346f07b49d06f48acb1196c3774e7c01f1ad810185f22b6708edb0d887193afef4d5d850c3cd4fb6c58e2b246aae09300f5e419

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.3.3] — 2026-08-23
+
+### Added
+
+- **Typed native errors everywhere**: PEM/DER, JSON, TOML, DSL, and
+  XML parse failures raise `Confium::ParseError`; out-of-range
+  sequence indexes raise `Confium::IndexError`; consistency-proof
+  failures raise `Confium::VerificationError` — each with a
+  structured `details` Hash (format, operation, index, ...).
+  Previously these surfaced as bare `RuntimeError`.
+
+### Added
+
+- `Confium::Composite::Signature.components_to_json` /
+  `.from_json` — JSON transport for composite signatures with the
+  binary fields hex-encoded on the wire (fixes the Sinatra example's
+  happy path, which called a `from_json` that did not exist).
+- Steep type checking in CI: the Steepfile never loaded before
+  (it used a `configure_code_diagnostics` API that does not exist in
+  steep 1.10). `sig/confium.rbs` now covers every pure-Ruby
+  subsystem — including the TC session machinery — and
+  `bundle exec steep check` is green and enforced. Only the FFI
+  layer is excluded (the ffi gem has no RBS signatures).
+
+### Fixed
+
+- `Confium::PKI::CMS::SignedDataBuilder#build` raised KeyError on
+  the ECDSA-P256 path (`FrostP256.sign` returns `der`/`fixed`, not
+  `signature`); it now uses the DER form, which is what CMS carries.
+- `Confium::PKI::CertificateBuilder`, `Confium::PKI::CNML`, and
+  `Confium::Transparency::OTS` were unreachable after
+  `require "confium"` (missing autoload wiring); the PKI namespace
+  file is now eager-required and registers them.
+- All five `hello_*` quickstart examples, the Sinatra example's
+  happy path, and every page under `docs/` were rewritten against
+  the real APIs (see the docs audit), and CI now runs every example
+  on every push.
+
 ## [0.3.2] — 2026-08-22
 
 Native platform gems (linux x86_64/aarch64, macOS x86_64/arm64) ship

data/README.adoc

@@ -10,7 +10,7 @@ Confium supports three deployment modes:
 * **Mode 2 — TC PKI replacement**: drop-in for existing PKI consumers (PKCS#11 server, OpenSSL 3.0 provider, JCE)
 * **Mode 3 — TC Certificate PKI**: institutional deployments with custom certificate formats (OIML CNML, BIPM, pharma, accreditation)
 
-This gem wraps the high-value Confium subsystems via a Rust native extension (built at `gem install` time with `rb_sys` + `magnus`). No separate C ABI library to install; everything is statically linked into the extension.
+This gem wraps the high-value Confium subsystems via a Rust native extension. Pre-compiled platform gems are published for Linux and macOS, so `gem install` needs no Rust toolchain there; other platforms build from source at install time with `rb_sys` + `magnus`. No separate C ABI library to install; everything is statically linked into the extension.
 
 == Installation
 
@@ -18,7 +18,7 @@ Add to your Gemfile:
 
 [source,ruby]
 ----
-gem "confium", "~> 0.1"
+gem "confium", "~> 0.3"
 ----
 
 Or install directly:
@@ -31,10 +31,18 @@ $ gem install confium
 === Prerequisites
 
 * Ruby ≥ 3.1
+* Nothing else on the pre-compiled platforms: `x86_64-linux`,
+  `aarch64-linux`, `x86_64-darwin`, `arm64-darwin` (each gem carries
+  one extension per Ruby C-ABI window)
+
+Source builds (other platforms, or installing from the repo) also
+need:
+
 * Rust stable toolchain (`rustup default stable`)
 * C toolchain (clang/gcc/Xcode CLT)
 
-The gem compiles a Rust cdylib at install time and links it into Ruby as a native extension. There is no separate `libconfium` to install.
+There is no separate `libconfium` to install — the extension
+statically links everything.
 
 == Quick start
 
@@ -76,7 +84,7 @@ recovered = Confium::TC::FrostP256.recover_secret(shares.first(3).map { |s| { "x
 recovered == kp["private_key"]  # => true
 ----
 
-== API surface (v0.1.0)
+== API surface (v0.3)
 
 === `Confium::Transparency`
 - `MerkleTree.new` / `#append(artifact_hash)` / `#root` / `#length` / `#empty?` / `#inclusion_proof(seq)`
@@ -127,7 +135,7 @@ After checking out the repo:
 ----
 $ bundle install
 $ bundle exec rake compile       # build the Rust extension
-$ bundle exec rspec              # 75+ specs
+$ bundle exec rspec              # 226 specs
 ----
 
 == Architecture

data/confium.gemspec

@@ -49,7 +49,6 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rake-compiler', '~> 1.3.0'
-  spec.add_development_dependency 'rake-compiler-dock', '~> 1.3'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop', '~> 1.0'
   spec.add_development_dependency 'steep', '~> 1.5'

data/ext/confium_native/src/attributes.rs

@@ -63,7 +63,7 @@ impl SignerWrap {
 
 fn parse(expr: String) -> Result<Obj<PredicateWrap>, Error> {
     let predicate = dsl_parse(&expr)
-        .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        .map_err(|e| crate::util::parse_error(e.to_string(), "Attributes.parse", Some("dsl"), None))?;
     let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
     Ok(ruby.obj_wrap(PredicateWrap { inner: predicate }))
 }

data/ext/confium_native/src/deployment.rs

@@ -11,7 +11,7 @@ use confium_deployment::{
     manifest::{parse_manifest, Manifest as RustManifest},
     validate::validate_manifest,
 };
-use crate::util::enforce_size;
+use crate::util::{enforce_size, parse_error};
 use magnus::{exception, function, method, typed_data::Obj, DataTypeFunctions, Error, Module, Object, Ruby, TypedData};
 
 #[derive(TypedData, DataTypeFunctions)]
@@ -24,7 +24,7 @@ impl Actor {
     fn from_json(json: String) -> Result<Obj<Self>, Error> {
         enforce_size(json.len())?;
         let actor: ActorIdentity = serde_json::from_str(&json)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| parse_error(e.to_string(), "Actor.from_json", Some("json"), None))?;
         let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
         Ok(ruby.obj_wrap(Self {
             inner: std::cell::RefCell::new(actor),
@@ -93,7 +93,7 @@ impl Manifest {
     fn from_toml(toml_str: String) -> Result<Obj<Self>, Error> {
         enforce_size(toml_str.len())?;
         let manifest = parse_manifest(&toml_str)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| parse_error(e.to_string(), "Manifest.from_toml", Some("toml"), None))?;
         let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
         Ok(ruby.obj_wrap(Self {
             inner: std::cell::RefCell::new(manifest),

data/ext/confium_native/src/openpgp.rs

@@ -26,7 +26,7 @@ fn native_armor(ruby: &Ruby, data: Value, type_str: Value) -> Result<magnus::RSt
         }
     };
     let armored = armor_bytes(&bytes, ty)
-        .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        .map_err(|e| crate::util::parse_error(e.to_string(), "OpenPGP.armor", Some("openpgp"), None))?;
     Ok(bytes_to_rstring(ruby, &armored))
 }
 
@@ -34,7 +34,7 @@ fn native_armor(ruby: &Ruby, data: Value, type_str: Value) -> Result<magnus::RSt
 fn native_dearmor(ruby: &Ruby, data: Value) -> Result<magnus::RString, Error> {
     let bytes = bytes_from_value(data)?;
     let raw = dearmor_bytes(&bytes)
-        .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        .map_err(|e| crate::util::parse_error(e.to_string(), "OpenPGP.dearmor", Some("openpgp"), None))?;
     Ok(bytes_to_rstring(ruby, &raw))
 }
 

data/ext/confium_native/src/pki.rs

@@ -10,7 +10,7 @@
 //! *building* + signing lands in a follow-up once the Rust builder API
 //! stabilizes (currently `confium_pki::cert::builder` is private).
 
-use crate::util::{bytes_from_value, bytes_to_rstring, enforce_size};
+use crate::util::{bytes_from_value, bytes_to_rstring, enforce_size, parse_error};
 use chrono::{DateTime, Utc};
 use confium_pki::{
     cert::{Certificate as RustCert, CertificateSigningRequest as RustCsr},
@@ -34,7 +34,7 @@ impl Certificate {
     fn from_der(bytes: Value) -> Result<Obj<Self>, Error> {
         let der = bytes_from_value(bytes)?;
         let cert = RustCert::from_der(&der)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| parse_error(e.to_string(), "Certificate.from_der", Some("der"), None))?;
         let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
         Ok(ruby.obj_wrap(Self { inner: cert }))
     }
@@ -42,7 +42,7 @@ impl Certificate {
     fn from_pem(pem: String) -> Result<Obj<Self>, Error> {
         enforce_size(pem.len())?;
         let cert = RustCert::from_pem(&pem)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| parse_error(e.to_string(), "Certificate.from_pem", Some("pem"), None))?;
         let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
         Ok(ruby.obj_wrap(Self { inner: cert }))
     }
@@ -102,7 +102,7 @@ impl Csr {
     fn from_der(bytes: Value) -> Result<Obj<Self>, Error> {
         let der = bytes_from_value(bytes)?;
         let csr = RustCsr::from_der(&der)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| parse_error(e.to_string(), "Csr.from_der", Some("der"), None))?;
         let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
         Ok(ruby.obj_wrap(Self { inner: csr }))
     }
@@ -110,7 +110,7 @@ impl Csr {
     fn from_pem(pem: String) -> Result<Obj<Self>, Error> {
         enforce_size(pem.len())?;
         let csr = RustCsr::from_pem(&pem)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| parse_error(e.to_string(), "Csr.from_pem", Some("pem"), None))?;
         let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
         Ok(ruby.obj_wrap(Self { inner: csr }))
     }
@@ -135,7 +135,7 @@ impl SignedData {
     fn from_json(json: String) -> Result<Obj<Self>, Error> {
         enforce_size(json.len())?;
         let sd: RustSignedData = serde_json::from_str(&json)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| parse_error(e.to_string(), "SignedData.from_json", Some("json"), None))?;
         let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
         Ok(ruby.obj_wrap(Self {
             inner: std::cell::RefCell::new(sd),
@@ -362,12 +362,12 @@ impl CertWrapper {
 
 fn xmldsig_canonicalize(xml: String) -> Result<String, Error> {
     enforce_size(xml.len())?;
-    canonicalize(&xml).map_err(|e| Error::new(exception::runtime_error(), e.to_string()))
+    canonicalize(&xml).map_err(|e| parse_error(e.to_string(), "XMLDSig.canonicalize", Some("xml"), None))
 }
 
 fn xmldsig_canonicalize_exclusive(xml: String) -> Result<String, Error> {
     enforce_size(xml.len())?;
-    canonicalize_exclusive(&xml).map_err(|e| Error::new(exception::runtime_error(), e.to_string()))
+    canonicalize_exclusive(&xml).map_err(|e| parse_error(e.to_string(), "XMLDSig.canonicalize_exclusive", Some("xml"), None))
 }
 
 pub fn init(ruby: &Ruby, parent: magnus::RModule) -> Result<(), Error> {

data/ext/confium_native/src/transparency.rs

@@ -72,7 +72,7 @@ impl MerkleTree {
             .inner
             .borrow()
             .consistency_proof(old_size)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| crate::util::index_error(e.to_string(), "MerkleTree.consistency_proof", Some(old_size as u64)))?;
         let ruby = Ruby::get()
             .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
         let arr = ruby.ary_new_capa(proof.len());
@@ -142,7 +142,7 @@ impl MerkleTree {
             .borrow()
             .verify_consistency(old_root_hash, new_root_hash, old_size, new_size, &proof_hashes)
             .map(|_| true)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))
+            .map_err(|e| crate::util::verification_error(e.to_string(), "MerkleTree.verify_consistency", None, None))
     }
 
     fn root(&self) -> Value {
@@ -155,10 +155,10 @@ impl MerkleTree {
         let tree = self.inner.borrow();
         let proof = tree
             .inclusion_proof(seq)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| crate::util::index_error(e.to_string(), "MerkleTree.inclusion_proof", Some(seq)))?;
         let entry = tree
             .entry(seq)
-            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+            .map_err(|e| crate::util::index_error(e.to_string(), "MerkleTree.inclusion_proof", Some(seq)))?;
         // Re-derive the leaf hash with the same algorithm the tree uses
         // internally (H(0x01 | entry_hash)).
         let leaf_hash = hash_leaf(entry.entry_hash());

data/ext/confium_native/src/util.rs

@@ -148,6 +148,19 @@ pub fn parse_error(msg: impl Into<String>, operation: &str, format: Option<&str>
     confium_error(msg, "ParseError", d)
 }
 
+#[allow(dead_code)]
+pub fn index_error(msg: impl Into<String>, operation: &str, index: Option<u64>) -> Error {
+    let ruby = match Ruby::get() {
+        Ok(r) => r,
+        Err(_) => return Error::new(exception::runtime_error(), msg.into()),
+    };
+    let d = new_details(&ruby);
+    let _ = d.aset("operation", operation);
+    let _ = d.aset("component", "Confium");
+    if let Some(i) = index { let _ = d.aset("index", i); }
+    confium_error(msg, "IndexError", d)
+}
+
 #[allow(dead_code)]
 pub fn validation_error(msg: impl Into<String>, operation: &str, param: &str, expected: &str, actual: &str) -> Error {
     let ruby = match Ruby::get() {

data/lib/confium/audit.rb

@@ -68,6 +68,7 @@ module Confium
       attr_reader :records
 
       def initialize
+        # @type ivar @records: Array[untyped]
         @records = []
       end
 

data/lib/confium/composite.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Confium
+  module Composite
+    # JSON transport for composite signatures. The native extension
+    # defines Signature with algorithms/component_count/verify over
+    # component Hashes (algorithm, public_key, signature) whose
+    # binary fields cannot ride JSON directly, so the wire format
+    # hex-encodes them:
+    #
+    #   json = Confium::Composite::Signature.components_to_json(components)
+    #   sig  = Confium::Composite::Signature.from_json(json)
+    #   sig.verify(message)
+    class Signature
+      BINARY_FIELDS = %w[public_key signature].freeze
+
+      def self.components_to_json(components)
+        JSON.generate(components.map do |component|
+          component.transform_values do |value|
+            value.encoding == Encoding::ASCII_8BIT ? value.unpack1('H*') : value
+          end
+        end)
+      end
+
+      # Accepts either a bare JSON array of component Hashes or a
+      # {"components": [...]} envelope, with public_key/signature
+      # hex-encoded on the wire. Takes a JSON string or an
+      # already-parsed Array/Hash.
+      def self.from_json(json)
+        data = json.is_a?(String) ? JSON.parse(json) : json
+        components = data.is_a?(Hash) ? data['components'] : data
+        unless components.is_a?(Array) && !components.empty?
+          raise ArgumentError, 'expected a non-empty "components" array'
+        end
+
+        new(components.map { |c| decode_binary_fields(c) })
+      end
+
+      def self.decode_binary_fields(component)
+        BINARY_FIELDS.each_with_object(component.dup) do |field, decoded|
+          value = component.fetch(field)
+          decoded[field] = [value].pack('H*') if value.is_a?(String)
+        end
+      end
+      private_class_method :decode_binary_fields
+    end
+  end
+end

data/lib/confium/crypto.rb

@@ -21,6 +21,7 @@
 #   Confium::Crypto.lookup(:hash)  # => Confium::Digest
 module Confium
   module Crypto
+    # @type ivar @interfaces: Hash[Symbol, untyped]
     @interfaces = {}
 
     class << self

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

@@ -33,6 +33,7 @@ module Confium
 
         def initialize
           @content = nil
+          # @type ivar @signers: Array[Hash[Symbol, untyped]]
           @signers = []
         end
 
@@ -81,7 +82,9 @@ module Confium
             result.fetch('signature')
           when :ecdsa_p256
             result = Confium::TC::FrostP256.sign(private_key, payload)
-            result.fetch('signature')
+            # CMS carries ECDSA signatures DER-encoded (DSA-Sig-Value);
+            # FrostP256.sign returns { "der" => ..., "fixed" => ... }.
+            result.fetch('der')
           else
             raise ArgumentError, "unsupported algorithm: #{algorithm.inspect}"
           end

data/lib/confium/pki.rb

@@ -9,5 +9,7 @@
 module Confium
   module PKI
     autoload :CMS, 'confium/pki/cms'
+    autoload :CertificateBuilder, 'confium/pki/certificate_builder'
+    autoload :CNML, 'confium/pki/cnml'
   end
 end

data/lib/confium/transparency.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Confium::Transparency namespace file.
+#
+# The Transparency module itself is defined by the native Rust
+# extension via magnus at require time. This file registers
+# pure-Ruby autoloads for the Transparency submodules.
+module Confium
+  module Transparency
+    autoload :OTS, 'confium/transparency/ots'
+  end
+end

data/lib/confium/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Confium
-  VERSION = '0.3.2'
+  VERSION = '0.3.3'
 end

data/lib/confium.rb

@@ -18,8 +18,7 @@ begin
   # 3.1 and 3.2 get exact-minor builds while 3.3 covers 3.3+).
   # Source builds install the extension flat, without a version
   # directory.
-  major, minor = RUBY_VERSION.split('.').first(2).map(&:to_i)
-  window = major > 3 || minor >= 3 ? '3.3' : "#{major}.#{minor}"
+  window = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.3') ? '3.3' : RUBY_VERSION[/\A\d+\.\d+/]
   begin
     require_relative "confium_native/#{window}/confium_native"
   rescue LoadError
@@ -56,9 +55,21 @@ module Confium
   autoload :PolicyViolationError, 'confium/errors/policy_violation_error'
   autoload :SecureBytes,          'confium/secure_bytes'
   autoload :Policy,               'confium/policy'
-  autoload :PKI,                  'confium/pki'
+  # PKI is native-defined, so an autoload would never fire; the
+  # namespace file is eager-required and registers the pure-Ruby
+  # submodules (CMS, CertificateBuilder, CNML) as autoloads.
+  require_relative 'confium/pki'
 end
 
+# Eager-load the Composite Signature JSON companion. The native
+# extension defines Confium::Composite; this file reopens the class
+# to add from_json transport.
+require_relative 'confium/composite'
+
+# Eager-load the Transparency namespace for the OTS autoload (the
+# module itself is native-defined).
+require_relative 'confium/transparency'
+
 # 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: confium
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.3
 platform: ruby
 authors:
 - Ribose Open
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-22 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -52,20 +52,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.3.0
-- !ruby/object:Gem::Dependency
-  name: rake-compiler-dock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -144,6 +130,7 @@ files:
 - lib/confium.rb
 - lib/confium/audit.rb
 - lib/confium/cfm.rb
+- lib/confium/composite.rb
 - lib/confium/crypto.rb
 - lib/confium/digest.rb
 - lib/confium/errors.rb
@@ -172,6 +159,7 @@ files:
 - lib/confium/tc/session.rb
 - lib/confium/tc/session_stub.rb
 - lib/confium/tc/share_file.rb
+- lib/confium/transparency.rb
 - lib/confium/transparency/ots.rb
 - lib/confium/version.rb
 homepage: https://www.confium.org