confium 0.2.0 → 0.3.0

data/ext/confium_native/src/transparency.rs

@@ -0,0 +1,341 @@
+//! Confium::Transparency — Ruby surface for `confium_transparency`.
+//!
+//! Exposes:
+//!   - `Confium::Transparency::MerkleTree` — append-only Merkle tree with
+//!     RFC 6962 inclusion proofs (wraps `confium_transparency::merkle::MerkleTree`).
+//!   - `Confium::Transparency::InclusionProof` — proof object with `#verify(root)`.
+
+use confium_transparency::{
+    entry::{ArtifactType, MerkleEntry},
+    merkle::{Hash, InclusionProof as RustInclusionProof, MerkleTree as RustMerkleTree, Side},
+};
+use magnus::{
+    exception, function, method, prelude::*, typed_data::Obj, DataTypeFunctions, Error, IntoValue,
+    Module, Object, RHash, RString, Ruby, TryConvert, TypedData, Value,
+};
+
+#[derive(TypedData, DataTypeFunctions)]
+#[magnus(class = "Confium::Transparency::MerkleTree", size)]
+pub struct MerkleTree {
+    inner: std::cell::RefCell<RustMerkleTree>,
+}
+
+impl MerkleTree {
+    fn new() -> Self {
+        Self {
+            inner: std::cell::RefCell::new(RustMerkleTree::new()),
+        }
+    }
+
+    fn append(&self, artifact_hash: Value) -> Result<u64, Error> {
+        let bytes = bytes_from_value(artifact_hash)?;
+        if bytes.len() != 32 {
+            return Err(Error::new(
+                exception::arg_error(),
+                format!("artifact_hash must be exactly 32 bytes, got {}", bytes.len()),
+            ));
+        }
+        let mut artifact_hash = [0u8; 32];
+        artifact_hash.copy_from_slice(&bytes);
+        let entry = MerkleEntry::new(0, ArtifactType::CertificateIssuance, artifact_hash);
+        let seq = self.inner.borrow_mut().append(entry);
+        Ok(seq)
+    }
+
+    fn len(&self) -> usize {
+        self.inner.borrow().len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.inner.borrow().is_empty()
+    }
+
+    /// Return all inclusion proofs as an Array. Use #to_a or #entries
+    /// to iterate: `tree.to_a.map(&:sequence)` etc.
+    fn entries(&self) -> Result<magnus::RArray, Error> {
+        let len = self.inner.borrow().len();
+        let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        let arr = ruby.ary_new_capa(len);
+        for i in 0..(len as u64) {
+            let proof = self.inclusion_proof(i)?;
+            arr.push(proof)?;
+        }
+        Ok(arr)
+    }
+
+    /// Compute a consistency proof (RFC 6962 §2.1.2).
+    /// Proves that the first `old_size` entries hash to the same root
+    /// as a tree of exactly `old_size` entries.
+    /// Returns an Array of 32-byte binary Strings.
+    fn consistency_proof(&self, old_size: usize) -> Result<magnus::RArray, Error> {
+        let proof = self
+            .inner
+            .borrow()
+            .consistency_proof(old_size)
+            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        let ruby = Ruby::get()
+            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        let arr = ruby.ary_new_capa(proof.len());
+        for h in &proof {
+            arr.push(bytes_to_rstring(&ruby, h))?;
+        }
+        Ok(arr)
+    }
+
+    /// Verify a consistency proof (RFC 6962 §2.1.2).
+    ///
+    /// Brute-force verifier: recomputes this tree's root at `old_size`
+    /// and its current root, compares to `old_root` and `new_root`.
+    ///
+    /// Ruby signature:
+    ///   tree.verify_consistency(old_root, new_root, old_size, new_size, proof)
+    ///
+    /// - old_root: 32-byte binary String (root of tree at old_size)
+    /// - new_root: 32-byte binary String (root of current tree)
+    /// - old_size: Integer
+    /// - new_size: Integer (must equal `tree.size`)
+    /// - proof:    Array of 32-byte binary Strings from `consistency_proof`
+    ///
+    /// Returns true if valid, raises RuntimeError otherwise.
+    fn verify_consistency(
+        &self,
+        old_root: Value,
+        new_root: Value,
+        old_size: usize,
+        new_size: usize,
+        proof: magnus::RArray,
+    ) -> Result<bool, Error> {
+        let old_bytes = bytes_from_value(old_root)?;
+        if old_bytes.len() != 32 {
+            return Err(Error::new(
+                exception::arg_error(),
+                format!("old_root must be 32 bytes, got {}", old_bytes.len()),
+            ));
+        }
+        let new_bytes = bytes_from_value(new_root)?;
+        if new_bytes.len() != 32 {
+            return Err(Error::new(
+                exception::arg_error(),
+                format!("new_root must be 32 bytes, got {}", new_bytes.len()),
+            ));
+        }
+        let mut old_root_hash: Hash = [0u8; 32];
+        old_root_hash.copy_from_slice(&old_bytes);
+        let mut new_root_hash: Hash = [0u8; 32];
+        new_root_hash.copy_from_slice(&new_bytes);
+
+        let mut proof_hashes: Vec<Hash> = Vec::with_capacity(proof.len());
+        for item in proof.each() {
+            let bytes = bytes_from_value(item?)?;
+            if bytes.len() != 32 {
+                return Err(Error::new(
+                    exception::arg_error(),
+                    format!("proof entries must be 32 bytes, got {}", bytes.len()),
+                ));
+            }
+            let mut h: Hash = [0u8; 32];
+            h.copy_from_slice(&bytes);
+            proof_hashes.push(h);
+        }
+
+        self.inner
+            .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()))
+    }
+
+    fn root(&self) -> Value {
+        let ruby = Ruby::get().expect("Ruby must be available");
+        let bytes = self.inner.borrow().root();
+        bytes_to_rstring(&ruby, &bytes).as_value()
+    }
+
+    fn inclusion_proof(&self, seq: u64) -> Result<Obj<InclusionProofWrap>, Error> {
+        let tree = self.inner.borrow();
+        let proof = tree
+            .inclusion_proof(seq)
+            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        let entry = tree
+            .entry(seq)
+            .map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        // 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());
+        let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        Ok(ruby.obj_wrap(InclusionProofWrap {
+            inner: proof,
+            leaf_hash,
+        }))
+    }
+}
+
+#[derive(TypedData, DataTypeFunctions)]
+#[magnus(class = "Confium::Transparency::InclusionProof", size)]
+pub struct InclusionProofWrap {
+    pub inner: RustInclusionProof,
+    /// The leaf hash (entry_hash run through the leaf-domain hash) at the
+    /// time the proof was generated. Stored alongside the proof so that
+    /// `#verify(root)` doesn't need to recompute it (which would require
+    /// the original entry, including its timestamp).
+    pub leaf_hash: Hash,
+}
+
+impl InclusionProofWrap {
+    fn sequence(&self) -> u64 {
+        self.inner.sequence
+    }
+
+    fn steps(&self) -> Result<Value, Error> {
+        let ruby = Ruby::get().map_err(|e| Error::new(exception::runtime_error(), e.to_string()))?;
+        let result = ruby.hash_new();
+        for (i, step) in self.inner.steps.iter().enumerate() {
+            let step_hash = ruby.hash_new();
+            step_hash.aset("sibling", bytes_to_rstring(&ruby, &step.sibling))?;
+            step_hash.aset(
+                "side",
+                match step.side {
+                    Side::Left => "left",
+                    Side::Right => "right",
+                },
+            )?;
+            result.aset(i, step_hash)?;
+        }
+        Ok(result.into_value_with(&ruby))
+    }
+
+    fn verify(&self, root_bytes: Value) -> Result<bool, Error> {
+        let bytes = bytes_from_value(root_bytes)?;
+        if bytes.len() != 32 {
+            return Err(Error::new(
+                exception::arg_error(),
+                format!("root must be exactly 32 bytes, got {}", bytes.len()),
+            ));
+        }
+        let mut root: Hash = [0u8; 32];
+        root.copy_from_slice(&bytes);
+        let mut current = self.leaf_hash;
+        for step in &self.inner.steps {
+            current = match step.side {
+                Side::Left => hash_internal(step.sibling, current),
+                Side::Right => hash_internal(current, step.sibling),
+            };
+        }
+        Ok(current == root)
+    }
+
+    /// External-auditor inclusion verification. Accepts an explicit
+    /// leaf_hash (32 bytes) instead of using the stored one. Use when
+    /// the auditor independently computed the leaf hash from the log's
+    /// published (sequence, timestamp, artifact_hash) fields.
+    ///
+    /// Ruby: `proof.verify_with_leaf(leaf_hash, root)`
+    fn verify_with_leaf(&self, leaf_bytes: Value, root_bytes: Value) -> Result<bool, Error> {
+        let leaf = bytes_from_value(leaf_bytes)?;
+        if leaf.len() != 32 {
+            return Err(Error::new(
+                exception::arg_error(),
+                format!("leaf_hash must be exactly 32 bytes, got {}", leaf.len()),
+            ));
+        }
+        let root_raw = bytes_from_value(root_bytes)?;
+        if root_raw.len() != 32 {
+            return Err(Error::new(
+                exception::arg_error(),
+                format!("root must be exactly 32 bytes, got {}", root_raw.len()),
+            ));
+        }
+        let mut current: Hash = [0u8; 32];
+        current.copy_from_slice(&leaf);
+        let mut root: Hash = [0u8; 32];
+        root.copy_from_slice(&root_raw);
+        for step in &self.inner.steps {
+            current = match step.side {
+                Side::Left => hash_internal(step.sibling, current),
+                Side::Right => hash_internal(current, step.sibling),
+            };
+        }
+        Ok(current == root)
+    }
+}
+
+fn bytes_from_value(v: Value) -> Result<Vec<u8>, Error> {
+    // Accept either a binary String (preferred for byte data) or an Array
+    // of small integers (also commonly used in Ruby crypto code).
+    if let Ok(s) = RString::try_convert(v) {
+        // SAFETY: we treat the string's raw bytes as opaque cryptographic
+        // input — we never interpret them as a UTF-8 string. Encoding is
+        // irrelevant for hash input.
+        return Ok(unsafe { s.as_slice() }.to_vec());
+    }
+    let arr: Vec<i64> = Vec::<i64>::try_convert(v)?;
+    arr.into_iter()
+        .map(|i| {
+            if !(0..=255).contains(&i) {
+                Err(Error::new(
+                    exception::arg_error(),
+                    format!("byte out of range 0..255: {i}"),
+                ))
+            } else {
+                Ok(i as u8)
+            }
+        })
+        .collect()
+}
+
+fn bytes_to_rstring(_ruby: &Ruby, bytes: &[u8]) -> RString {
+    let s = RString::buf_new(0);
+    s.cat(bytes);
+    s
+}
+
+fn hash_leaf(entry_hash: Hash) -> Hash {
+    use sha2::{Digest, Sha256};
+    let mut h = Sha256::new();
+    h.update([0x01]);
+    h.update(entry_hash);
+    let r = h.finalize();
+    let mut out = [0u8; 32];
+    out.copy_from_slice(&r);
+    out
+}
+
+fn hash_internal(left: Hash, right: Hash) -> Hash {
+    use sha2::{Digest, Sha256};
+    let mut h = Sha256::new();
+    h.update([0x02]);
+    h.update(left);
+    h.update(right);
+    let r = h.finalize();
+    let mut out = [0u8; 32];
+    out.copy_from_slice(&r);
+    out
+}
+
+pub fn init(ruby: &Ruby, parent: magnus::RModule) -> Result<(), Error> {
+    let transparency = parent.define_module("Transparency")?;
+
+    let tree_class = transparency.define_class("MerkleTree", ruby.class_object())?;
+    tree_class.define_singleton_method("new", function!(MerkleTree::new, 0))?;
+    tree_class.define_method("append", method!(MerkleTree::append, 1))?;
+    tree_class.define_method("length", method!(MerkleTree::len, 0))?;
+    tree_class.define_method("size", method!(MerkleTree::len, 0))?;
+    tree_class.define_method("empty?", method!(MerkleTree::is_empty, 0))?;
+    tree_class.define_method("root", method!(MerkleTree::root, 0))?;
+    tree_class.define_method("inclusion_proof", method!(MerkleTree::inclusion_proof, 1))?;
+    tree_class.define_method("entries", method!(MerkleTree::entries, 0))?;
+    tree_class.define_method("to_a", method!(MerkleTree::entries, 0))?;
+    tree_class.define_method("consistency_proof", method!(MerkleTree::consistency_proof, 1))?;
+    tree_class.define_method(
+        "verify_consistency",
+        method!(MerkleTree::verify_consistency, 5),
+    )?;
+
+    let proof_class = transparency.define_class("InclusionProof", ruby.class_object())?;
+    proof_class.define_method("sequence", method!(InclusionProofWrap::sequence, 0))?;
+    proof_class.define_method("steps", method!(InclusionProofWrap::steps, 0))?;
+    proof_class.define_method("verify", method!(InclusionProofWrap::verify, 1))?;
+    proof_class.define_method("verify_with_leaf", method!(InclusionProofWrap::verify_with_leaf, 2))?;
+
+    Ok(())
+}

data/ext/confium_native/src/util.rs

@@ -0,0 +1,196 @@
+//! Shared utilities for the confium-ruby native extension.
+//!
+//! DRY consolidation: a single `bytes_from_value` + size cap + string
+//! conversion + typed-error helper shared by every subsystem module
+//! (composite, pki, tc, transparency, deployment, attributes).
+
+use magnus::prelude::*;
+use magnus::{exception, Error, RHash, RString, Ruby, TryConvert, Value};
+
+/// Maximum byte length for any input we accept from Ruby. Inputs larger
+/// than this are rejected before they reach an allocator-capable codepath
+/// (DoS guard). 1 MiB is generous for any current Confium operation
+/// (cert bodies, sig material, JSON envelopes) and small enough to
+/// prevent trivial memory-exhaustion attacks.
+pub const MAX_INPUT_SIZE: usize = 1 << 20;
+
+/// Convert a Ruby value to bytes. Accepts a binary `String` (any
+/// encoding) or an `Array<Integer>`. Enforces a 1 MiB size cap.
+pub fn bytes_from_value(v: Value) -> Result<Vec<u8>, Error> {
+    if let Ok(s) = RString::try_convert(v) {
+        // SAFETY: we treat the string's raw bytes as opaque cryptographic
+        // input — we never interpret them as a UTF-8 string. Encoding is
+        // irrelevant for hash input.
+        let bytes = unsafe { s.as_slice() }.to_vec();
+        enforce_size(bytes.len())?;
+        return Ok(bytes);
+    }
+    let arr: Vec<i64> = Vec::<i64>::try_convert(v)?;
+    enforce_size(arr.len())?;
+    arr.into_iter()
+        .map(|i| {
+            if !(0..=255).contains(&i) {
+                Err(Error::new(
+                    exception::arg_error(),
+                    format!("byte out of range 0..255: {i}"),
+                ))
+            } else {
+                Ok(i as u8)
+            }
+        })
+        .collect()
+}
+
+/// Reject a byte input larger than `MAX_INPUT_SIZE` with a clear
+/// `ArgumentError`. Used at every byte-input boundary to prevent
+/// memory-exhaustion attacks.
+pub fn enforce_size(len: usize) -> Result<(), Error> {
+    if len > MAX_INPUT_SIZE {
+        return Err(Error::new(
+            exception::arg_error(),
+            format!("input size {0} exceeds max {MAX_INPUT_SIZE}", len),
+        ));
+    }
+    Ok(())
+}
+
+/// Build a Ruby binary `String` from a byte slice. Avoids the UTF-8
+/// round-trip in `RString::buf_new` + `cat` for already-binary input.
+pub fn bytes_to_rstring(_ruby: &Ruby, bytes: &[u8]) -> RString {
+    let s = RString::buf_new(0);
+    s.cat(bytes);
+    s
+}
+
+/// Construct a typed `Confium::*Error` instance with the given message
+/// and details Hash, ready to be raised.
+///
+/// `subclass` is the Ruby class name under `Confium::` (e.g. "ThresholdError").
+/// Falls back to `Confium::Error` if the subclass can't be resolved, then
+/// to Ruby's `RuntimeError` if even the base class is unavailable.
+///
+/// ## Design
+///
+/// Each typed error class accepts `(message, details_hash)` positionally,
+/// where `details_hash` is a plain Ruby Hash carrying the structured
+/// fields (`have_count`, `need_count`, `algorithm`, etc.). The class's
+/// initializer extracts its specific keys from the Hash and assigns them
+/// to ivars exposed via `attr_reader`. This pattern survives Ruby 3's
+/// removal of automatic positional-Hash-to-kwargs conversion.
+///
+/// ## Autoload caveat
+///
+/// The Ruby side registers error subclasses via `autoload`. We resolve
+/// the constant by walking the path step by step (`Confium` →
+/// `ThresholdError`) rather than `Object.const_get("Confium::ThresholdError")`,
+/// because the latter does not trigger autoload.
+pub fn confium_error(message: impl Into<String>, subclass: &str, details: RHash) -> Error {
+    let ruby = match Ruby::get() {
+        Ok(r) => r,
+        Err(_) => return Error::new(exception::runtime_error(), message.into()),
+    };
+    let class = resolve_confium_subclass(&ruby, subclass);
+    let msg: String = message.into();
+    // Construct via `class.new(msg, details_hash)`. The typed subclasses
+    // route the Hash through their initializer, which assigns ivars
+    // exposed via attr_reader (have_count, need_count, etc.). If the
+    // call fails for any reason we fall back to bare RuntimeError with
+    // the original message so the binding stays usable.
+    match class.funcall::<_, _, magnus::Exception>("new", (msg.as_str(), details)) {
+        Ok(exc) => Error::from(exc),
+        Err(_) => Error::new(exception::runtime_error(), msg),
+    }
+}
+
+/// Resolve a `Confium::*Error` subclass by short name (e.g. "ThresholdError").
+/// Walks the constant path segment by segment so autoload triggers
+/// correctly. Falls back to `Confium::Error` if the named subclass is
+/// missing, then to Ruby's `RuntimeError` if even the base class is
+/// unavailable.
+fn resolve_confium_subclass(ruby: &Ruby, subclass: &str) -> magnus::ExceptionClass {
+    let confium_mod: magnus::RModule = match ruby
+        .class_object()
+        .const_get::<_, magnus::RModule>("Confium")
+    {
+        Ok(m) => m,
+        Err(_) => return exception::runtime_error(),
+    };
+    confium_mod
+        .const_get::<_, magnus::ExceptionClass>(subclass)
+        .or_else(|_| confium_mod.const_get::<_, magnus::ExceptionClass>("Error"))
+        .unwrap_or_else(|_| exception::runtime_error())
+}
+
+/// Build an empty `RHash` for the `details:` argument to a Confium
+/// error. The Hash is owned by the Ruby GC; callers add keys via
+/// `aset` before passing to [`confium_error`].
+pub fn new_details(ruby: &Ruby) -> RHash {
+    ruby.hash_new()
+}
+
+// ===== Typed error helpers (TODO 013) =====
+// Each function builds a details Hash with the right shape for its
+// error class, then delegates to confium_error(). Call sites pass
+// only the domain-specific fields; :operation and :component are
+// filled automatically.
+
+pub fn parse_error(msg: impl Into<String>, operation: &str, format: Option<&str>, offset: Option<usize>) -> 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(f) = format { let _ = d.aset("format", f); }
+    if let Some(o) = offset { let _ = d.aset("offset", o); }
+    confium_error(msg, "ParseError", d)
+}
+
+pub fn validation_error(msg: impl Into<String>, operation: &str, param: &str, expected: &str, actual: &str) -> 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("param", param);
+    let _ = d.aset("expected", expected);
+    let _ = d.aset("actual", actual);
+    confium_error(msg, "ValidationError", d)
+}
+
+pub fn verification_error(msg: impl Into<String>, operation: &str, signer_index: Option<usize>, algorithm: Option<&str>) -> 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);
+    if let Some(si) = signer_index { let _ = d.aset("signer_index", si); }
+    if let Some(alg) = algorithm { let _ = d.aset("algorithm", alg); }
+    confium_error(msg, "VerificationError", d)
+}
+
+pub fn crypto_error(msg: impl Into<String>, operation: &str, primitive: &str) -> 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("primitive", primitive);
+    confium_error(msg, "CryptoError", d)
+}
+
+pub fn threshold_error(msg: impl Into<String>, operation: &str, have: usize, need: usize) -> 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("have_count", have);
+    let _ = d.aset("need_count", need);
+    confium_error(msg, "ThresholdError", d)
+}

data/lib/confium/audit.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+# Audit log sink hierarchy.
+#
+# Sinks receive an audit record Hash for every signed event. The Rust
+# extension fires events on every signing / verification / encryption
+# op; the Ruby side routes them to the configured sink via
+# {Confium::Audit.sink=}.
+#
+# Three reference sinks are shipped: {FileSink} (append-only file),
+# {MemorySink} (in-memory, for testing), {StderrSink} (one-line JSON
+# per record). Custom sinks can subclass {Sink} for HTTP / syslog /
+# Kafka backends.
+
+require "json"
+require "time"
+
+module Confium
+  module Audit
+    # Base class for audit sinks. Subclasses override {#write} and
+    # optionally {#close}. The contract:
+    #
+    # - #write(record) — synchronously emit the record. Raise on
+    #   failure; the exception propagates back through the caller.
+    # - #close — flush and release resources. Safe to call multiple
+    #   times.
+    class Sink
+      # Persist an audit record Hash. The Hash has these keys
+      # (all Strings):
+      #
+      # - `"timestamp"`      — ISO8601 UTC, e.g. `"2026-07-30T22:00:00Z"`
+      # - `"operation"`      — short slug like `"composite_sign"`
+      # - `"actor"`          — optional String
+      # - `"algorithm"`      — optional String
+      # - `"payload_hash"`   — hex SHA-256 of the signed bytes
+      # - `"result"`         — `"success"` or `"failure"`
+      # - `"error"`          — optional String
+      def write(_record)
+        raise NotImplementedError, "#{self.class} must implement #write"
+      end
+
+      # Treat the Sink as a callable — delegates to {#write}. The Rust
+      # extension's audit module fires events by calling `.call(record)`
+      # on whatever is in `Confium::Audit.sink`, so this lets both
+      # Proc-based and Object-based sinks work through the same
+      # dispatch point.
+      def call(record)
+        write(record)
+      end
+
+      def close
+        # default no-op
+      end
+    end
+
+    # In-memory sink. Records are collected in `#records` and inspected
+    # in specs. Implements `#clear` for resetting between tests.
+    #
+    # Includes Enumerable so callers can iterate, filter, and reduce
+    # over recorded events directly:
+    #
+    #     sink.select { |r| r["operation"] == "composite_sign" }
+    #     sink.count { |r| r["result"] == "failure" }
+    #     sink.find { |r| r["actor"] == "director-1" }
+    class MemorySink < Sink
+      include Enumerable
+
+      attr_reader :records
+
+      def initialize
+        @records = []
+      end
+
+      def write(record)
+        @records << record
+        self
+      end
+
+      def clear
+        @records.clear
+      end
+
+      # Enumerable contract: yield each record in insertion order.
+      def each(&block)
+        @records.each(&block)
+      end
+    end
+
+    # Stderr sink — emits each record as a one-line JSON object.
+    # Suitable for development and CI; for production prefer
+    # {FileSink} or a structured-logging sink.
+    class StderrSink < Sink
+      def initialize(io: $stderr)
+        @io = io
+      end
+
+      def write(record)
+        @io.puts(JSON.generate(record))
+      end
+    end
+
+    # Append-only file sink. The path is opened in append mode; each
+    # record is written as a single line followed by a newline.
+    # Concurrent writes from multiple processes are NOT supported —
+    # serialize audit traffic through this sink to a single writer for
+    # multi-process deployments.
+    class FileSink < Sink
+      attr_reader :path
+
+      def initialize(path)
+        @path = path
+        @io = File.open(path, "a")
+        @io.sync = true
+      end
+
+      def write(record)
+        @io.puts(JSON.generate(record))
+      end
+
+      def close
+        @io.close unless @io.closed?
+      end
+    end
+  end
+end

data/lib/confium/cfm.rb

@@ -5,11 +5,9 @@ module Confium
     attr_reader :ptr
 
     def initialize
-      pptr = FFI::MemoryPointer.new(:pointer)
+      pptr = ::FFI::MemoryPointer.new(:pointer)
       Confium.call_ffi(:cfm_create, pptr)
-      @ptr = FFI::AutoPointer.new(pptr.read_pointer, self.class.method(:destroy))
-
-      load_plugin('botan', ENV['CFM_HASH_BOTAN_PLUGIN_PATH'])
+      @ptr = ::FFI::AutoPointer.new(pptr.read_pointer, self.class.method(:destroy))
     end
 
     def self.destroy(ptr)