confium 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 604e0df1709827705bdca8fabd5ac2c5bdb70eb1e32b550e7ad7bfca143d7dcc
-  data.tar.gz: b1d4eea58189c4e1acf7613c27efc23ea7a76ea6afb9a32b911f27d56dc45a7c
+  metadata.gz: 80f1cc9387a28284e32d2c8b92fbdb5555f675f05e2ec8e6c38cd213a65e215f
+  data.tar.gz: d9ccaaf8e4297e8a731be6e19be9a5ee6566d3aa24d8398598f48fd6b2cf50fa
 SHA512:
-  metadata.gz: e07456a3f0a1c4499290372d238fd15e173e578deabb01de7bea5c5b6c014495eab86b962c71f33fb3f21c9d2f9124dd982373c5e7df404c011955180d136b1f
-  data.tar.gz: 2ee41a6707200f709086c9ae63d73554f2aa8836abf06c732a1ac904fded30baece97813b50a8229c2a351ea3cf0430d2265d3f93b06aa49daa4f8447c67e037
+  metadata.gz: b0fe995dbf54fcbc0b8fe57d815eedcba6abb10f8c4b26cd1713b62042798390861eb6faaf96168dcfcc8baa03dd54dd1d5c89d0f826f3d68f1a2bfb60416096
+  data.tar.gz: 4dde75f2b6d9c9143c546facb59bd249a1d87b6451d18a6036c1deec428773a553e2aedb8f9047465c4d0933e9f502d9d63341b74dac34ddfab3b31abafbd572

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.7.1] — UNRELEASED (code on main; release on the owner's tag)
+
+### Added
+
+- `Confium::Transparency::OTS` is now the real OpenTimestamps
+  wire-protocol binding (confium-transparency 0.9): `OTS::Client#stamp`
+  POSTs the 32-byte digest to the calendar pool and returns a `Proof`
+  carrying the parsed partial proof; `#upgrade` polls for a confirmed
+  one; `Proof#verify` replays the op tree and classifies attestations
+  (pending URIs, Bitcoin/Litecoin heights, `anchored`). Module-level
+  `OTS.stamp`/`verify`/`upgrade` over the default calendar pool.
+  Network failures raise (`IOError`/`ParseError`) — the stub-era
+  silent nil is gone.
+- The calendar round trip releases the GVL (direct
+  `rb_thread_call_without_gvl` trampoline — magnus 0.8 does not wrap
+  it), so a slow calendar never freezes the VM.
+
+### Fixed
+
+- The workspace's OTS file magic was missing its final two salt bytes
+  (29 vs 31; shifted every parse offset for real .ots files) — caught
+  by this binding's cross-checked specs, fixed in confium-transparency
+  v0.9.1.
+
 ## [0.7.0] — 2026-09-07
 
 ### Added

data/Cargo.lock

@@ -775,17 +775,18 @@ dependencies = [
 
 [[package]]
 name = "confium-transparency"
-version = "0.4.0"
+version = "0.9.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "874cdab3dded22c22980d3a5b1f802301739368a32e9196bc645600329c07dcf"
+checksum = "b4ec484381b582f508f774babbc1bf1b4a98c6aadd43cde806952c6e416b62ca"
 dependencies = [
  "chrono",
- "data-encoding",
+ "hex",
  "serde",
  "serde_json",
- "sha2 0.10.9",
- "snafu 0.8.9",
- "thiserror 1.0.69",
+ "sha2 0.11.0",
+ "subtle",
+ "thiserror 2.0.20",
+ "ureq",
 ]
 
 [[package]]

data/README.adoc

@@ -103,7 +103,7 @@ end
 === `Confium::Transparency`
 - `MerkleTree.new` / `#append(artifact_hash)` / `#root` / `#length` / `#empty?` / `#inclusion_proof(seq)`
 - `InclusionProof#sequence` / `#steps` / `#verify(root)`
-- `Ots.stamp(hash)` / `Ots.verify(receipt, hash)` — OpenTimestamps anchoring interface (pure-Ruby stub; calendar-server wiring lands with the Rust client)
+- `Ots.stamp(hash)` / `Ots.verify(proof)` / `Ots.upgrade(proof)` — real OpenTimestamps anchoring over the wire protocol (calendar HTTP, servers tried in order; the network round trip releases the GVL). `Ots::Client.new(servers)` for a custom pool; `Ots::Proof#verify` replays the op tree and classifies attestations. Network failures raise — there is no silent nil
 
 === `Confium::Composite` — PQ migration
 - `.generate_ed25519_keypair` → `{ private_key:, public_key: }`

data/ext/confium_native/Cargo.toml

@@ -36,7 +36,7 @@ magnus = { version = "0.8", features = ["bytes"] }
 
 # Confium crates — all from crates.io so gem install works without workspace checkout.
 confium-core = "0.2"
-confium-transparency = "0.4"
+confium-transparency = { version = "0.9", features = ["calendar"] }
 confium-composite = "0.3.1"
 confium-attributes = "0.3.1"
 confium-pki = "0.5.6"

data/ext/confium_native/src/gvl.rs

@@ -0,0 +1,56 @@
+//! GVL release for long blocking calls.
+//!
+//! magnus 0.8 does not wrap `rb_thread_call_without_gvl`, so the OTS
+//! calendar round trip (up to 30s) would hold the GVL and freeze the
+//! entire Ruby VM — including any Ruby thread serving as the peer.
+//! This is the standard MRI mechanism: release the GVL for the
+//! duration of a blocking FFI call, reacquire before touching Ruby
+//! objects again. The closure must not touch the Ruby API.
+
+use std::ffi::c_void;
+
+unsafe extern "C" {
+    fn rb_thread_call_without_gvl(
+        func: extern "C" fn(*mut c_void) -> *mut c_void,
+        data1: *mut c_void,
+        ubf: Option<extern "C" fn(*mut c_void) -> *mut c_void>,
+        data2: *mut c_void,
+    ) -> *mut c_void;
+}
+
+struct CallBox<F: FnOnce() -> T, T> {
+    func: Option<F>,
+    out: Option<T>,
+}
+
+extern "C" fn trampoline<F: FnOnce() -> T, T>(data: *mut c_void) -> *mut c_void {
+    // SAFETY: data points at the CallBox constructed by without_gvl,
+    // live for the duration of the call, on this same thread.
+    let box_ = unsafe { &mut *(data as *mut CallBox<F, T>) };
+    let func = box_.func.take().expect("trampoline runs once");
+    box_.out = Some(func());
+    std::ptr::null_mut()
+}
+
+/// Run `func` with the GVL released. Reacquires before returning.
+///
+/// # Safety (caller obligations)
+///
+/// `func` must not call the Ruby C API (no Ruby objects) and must be
+/// callable from this thread while the GVL is released.
+pub unsafe fn without_gvl<F: FnOnce() -> T, T>(func: F) -> T {
+    let mut call = CallBox {
+        func: Some(func),
+        out: None,
+    };
+    // SAFETY: the trampoline and box are used per the contract above.
+    unsafe {
+        rb_thread_call_without_gvl(
+            trampoline::<F, T>,
+            &mut call as *mut CallBox<F, T> as *mut c_void,
+            None,
+            std::ptr::null_mut(),
+        );
+    }
+    call.out.take().expect("trampoline stored the result")
+}

data/ext/confium_native/src/lib.rs

@@ -9,12 +9,14 @@ mod attributes;
 mod composite;
 mod deployment;
 mod ers;
+mod gvl;
 mod openpgp_verify;
 mod path;
 mod pki;
 mod store;
 mod tc;
 mod net;
+mod ots;
 mod tc_session;
 mod transparency;
 mod util;
@@ -66,6 +68,8 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     native.define_module_function("winsock_probe", function!(winsock_probe_fn, 1))?;
 
     transparency::init(ruby, confium)?;
+    let transparency = confium.define_module("Transparency")?;
+    ots::init(ruby, transparency)?;
     openpgp_verify::init(ruby, confium)?;
     #[cfg(feature = "pgp")]
     openpgp_verify::init_pgp(ruby, &confium)?;

data/ext/confium_native/src/ots.rs

@@ -0,0 +1,183 @@
+//! Confium::Transparency::OTS — OpenTimestamps calendar client.
+//!
+//! Binds confium-transparency's real wire-protocol client (0.9):
+//! `stamp` POSTs the 32-byte digest to a calendar server and parses
+//! the returned partial proof (op stream + pending attestation);
+//! `upgrade` fetches a more complete proof; `verify` replays the op
+//! tree from the digest and classifies the attestations. Network
+//! errors surface as Ruby exceptions — there is no silent nil.
+
+use std::cell::RefCell;
+
+use confium_transparency::ots::OtsClient;
+use confium_transparency::ots::wire;
+use magnus::prelude::*;
+use magnus::Error;
+use magnus::RHash;
+use magnus::RString;
+use magnus::Ruby;
+use magnus::TypedData;
+use magnus::DataTypeFunctions;
+
+/// An OTS proof: the raw .ots file bytes plus the digest it anchors.
+#[derive(TypedData, DataTypeFunctions)]
+#[magnus(class = "Confium::Transparency::OTS::Proof", size)]
+pub struct OtsProof {
+    digest: Vec<u8>,
+    bytes: Vec<u8>,
+}
+
+fn digest_arg_error() -> Error {
+    Error::new(magnus::exception::arg_error(), "digest must be exactly 32 bytes")
+}
+
+impl OtsProof {
+    fn initialize(_ruby: &Ruby, digest: RString, bytes: RString) -> Result<Self, Error> {
+        let digest = digest.to_bytes().to_vec();
+        if digest.len() != 32 {
+            return Err(digest_arg_error());
+        }
+        Ok(Self {
+            digest,
+            bytes: bytes.to_bytes().to_vec(),
+        })
+    }
+
+    fn digest(&self) -> RString {
+        RString::from_slice(&self.digest)
+    }
+
+    fn to_bytes(&self) -> RString {
+        RString::from_slice(&self.bytes)
+    }
+
+    /// Replay the proof tree and classify attestations. Returns a Hash:
+    /// { pending: [uri, ...], bitcoin: [height, ...],
+    ///   litecoin: [height, ...], anchored: bool }
+    fn verify(&self) -> Result<RHash, Error> {
+        let ruby = Ruby::get().map_err(|_| Error::new(magnus::exception::runtime_error(), "not on Ruby thread"))?;
+        let file = wire::parse(&self.digest, &self.bytes)
+            .map_err(|e| Error::new(parse_error_class(&ruby), format!("invalid OTS proof: {e}")))?;
+        let summary = wire::verify(&file)
+            .map_err(|e| Error::new(ruby.exception_runtime_error(), format!("replay failed: {e}")))?;
+
+        let out = RHash::new();
+        let pending: Vec<String> = summary
+            .pending
+            .iter()
+            .map(|(_, uri)| uri.clone())
+            .collect();
+        out.aset(
+            "pending",
+            ruby.into_value(ruby.ary_from_vec(pending)),
+        )?;
+        let bitcoin: Vec<i64> = summary.bitcoin.iter().map(|(_, h)| i64::from(*h)).collect();
+        out.aset(
+            "bitcoin",
+            ruby.into_value(ruby.ary_from_vec(bitcoin)),
+        )?;
+        let litecoin: Vec<i64> = summary.litecoin.iter().map(|(_, h)| i64::from(*h)).collect();
+        out.aset(
+            "litecoin",
+            ruby.into_value(ruby.ary_from_vec(litecoin)),
+        )?;
+        // Bitcoin/Litecoin attestations are on-chain anchors; pending
+        // means recorded at a calendar awaiting confirmation.
+        let anchored = !summary.bitcoin.is_empty() || !summary.litecoin.is_empty();
+        out.aset("anchored", ruby.into_value(anchored))?;
+        Ok(out)
+    }
+}
+
+/// A calendar client bound to a server pool.
+#[derive(TypedData, DataTypeFunctions)]
+#[magnus(class = "Confium::Transparency::OTS::Client", size)]
+pub struct Client {
+    inner: RefCell<OtsClient>,
+}
+
+impl Client {
+    fn initialize(_ruby: &Ruby, servers: Vec<String>) -> Result<Self, Error> {
+        Ok(Self {
+            inner: RefCell::new(OtsClient::with_servers(servers)),
+        })
+    }
+
+    /// Submit a 32-byte digest to the calendar pool. Returns a Proof
+    /// carrying the returned partial proof (pending attestation).
+    fn stamp(&self, digest: RString) -> Result<OtsProof, Error> {
+        let ruby = Ruby::get().map_err(|_| Error::new(magnus::exception::runtime_error(), "not on Ruby thread"))?;
+        let digest = digest.to_bytes().to_vec();
+        if digest.len() != 32 {
+            return Err(digest_arg_error());
+        }
+        let arr: [u8; 32] = digest.as_slice().try_into().map_err(|_| digest_arg_error())?;
+        let mut inner = self.inner.borrow_mut();
+        // Release the GVL for the network round trip: calendars take
+        // seconds-to-tens-of-seconds, and holding the VM would freeze
+        // every Ruby thread (including any in-process peer).
+        let stamped = unsafe {
+            crate::gvl::without_gvl(|| inner.stamp_wire(arr))
+        };
+        let file = stamped
+            .map_err(|e| Error::new(ruby.exception_io_error(), format!("calendar stamp failed: {e}")))?;
+        let bytes = wire::serialize(&file).map_err(|e| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("calendar returned an unserializable proof: {e}"),
+            )
+        })?;
+        Ok(OtsProof { digest, bytes })
+    }
+
+    /// Fetch a more complete proof for a pending attestation. Returns
+    /// the upgraded Proof (replaces the pending one).
+    fn upgrade(&self, proof: &OtsProof) -> Result<OtsProof, Error> {
+        let ruby = Ruby::get().map_err(|_| Error::new(magnus::exception::runtime_error(), "not on Ruby thread"))?;
+        let file = wire::parse(&proof.digest, &proof.bytes)
+            .map_err(|e| Error::new(parse_error_class(&ruby), format!("invalid OTS proof: {e}")))?;
+        let mut inner = self.inner.borrow_mut();
+        let upgraded_result = unsafe { crate::gvl::without_gvl(|| inner.upgrade(&file)) };
+        let upgraded = upgraded_result
+            .map_err(|e| Error::new(ruby.exception_io_error(), format!("calendar upgrade failed: {e}")))?;
+        let bytes = wire::serialize(&upgraded).map_err(|e| {
+            Error::new(
+                ruby.exception_runtime_error(),
+                format!("calendar returned an unserializable proof: {e}"),
+            )
+        })?;
+        Ok(OtsProof {
+            digest: proof.digest.clone(),
+            bytes,
+        })
+    }
+}
+
+pub fn init(ruby: &Ruby, parent: magnus::RModule) -> Result<(), Error> {
+    let ots = parent.define_module("OTS")?;
+    let parse_error = ots.define_error("ParseError", ruby.exception_standard_error())?;
+    ots.const_set("PARSE_ERROR", parse_error)?;
+
+    let proof = ots.define_class("Proof", ruby.class_object())?;
+    proof.define_singleton_method("new", magnus::function!(OtsProof::initialize, 2))?;
+    proof.define_method("digest", magnus::method!(OtsProof::digest, 0))?;
+    proof.define_method("to_bytes", magnus::method!(OtsProof::to_bytes, 0))?;
+    proof.define_method("verify", magnus::method!(OtsProof::verify, 0))?;
+
+    let client = ots.define_class("Client", ruby.class_object())?;
+    client.define_singleton_method("new", magnus::function!(Client::initialize, 1))?;
+    client.define_method("stamp", magnus::method!(Client::stamp, 1))?;
+    client.define_method("upgrade", magnus::method!(Client::upgrade, 1))?;
+
+    Ok(())
+}
+
+fn parse_error_class(ruby: &Ruby) -> magnus::ExceptionClass {
+    ruby
+        .class_object()
+        .const_get::<_, magnus::RModule>("Confium")
+        .and_then(|m| m.const_get::<_, magnus::RModule>("Transparency"))
+        .and_then(|m| m.const_get::<_, magnus::RModule>("OTS"))
+        .and_then(|m| m.const_get::<_, magnus::ExceptionClass>("PARSE_ERROR"))
+        .unwrap_or_else(|_| ruby.exception_runtime_error())
+}

data/lib/confium/transparency/ots.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
-# Confium::Transparency::OTS — OpenTimestamps client interface.
+# Confium::Transparency::OTS — OpenTimestamps calendar client.
 #
-# 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).
+# Real wire-protocol implementation over the native extension
+# (confium-transparency 0.8.5+): stamps POST the 32-byte digest to a
+# calendar server and parse the returned partial proof; verification
+# replays the op tree from the digest and classifies attestations.
+# Network failures raise (Confium::Transparency::OTS is backed by a
+# real HTTP client) — there is no silent nil.
 
 module Confium
   module Transparency
@@ -20,44 +19,48 @@ module Confium
         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
+      class << self
+        # Stamp a 32-byte digest via the default calendar pool.
+        # Returns a Proof (pending attestation — Bitcoin confirmation
+        # arrives later; poll with #upgrade).
+        #
+        # @param hash [String] 32-byte SHA-256 digest to anchor
+        # @return [Confium::Transparency::OTS::Proof]
+        # @raise [IOError, ArgumentError]
+        def stamp(hash)
+          default_client.stamp(hash)
+        end
 
-        def initialize(bytes:, block_height: nil)
-          @bytes = bytes
-          @block_height = block_height
+        # Verify a proof: replay its op tree from the digest and
+        # classify the attestations.
+        #
+        # @param proof [Proof, String] the proof (or raw .ots bytes —
+        #   pass the digest alongside for the String form)
+        # @param digest [String, nil] required when proof is bytes
+        # @return [Hash] { pending: [uri], bitcoin: [height],
+        #   litecoin: [height], anchored: bool }
+        def verify(proof, digest = nil)
+          proof = Proof.new(digest, proof) if digest && proof.is_a?(String)
+          proof.verify
         end
 
-        def to_bytes
-          @bytes
+        # Upgrade a pending proof (fetch a more complete one).
+        #
+        # @return [Proof]
+        def upgrade(proof)
+          default_client.upgrade(proof)
         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
+        private
 
-      # 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
+        def default_client
+          @default_client ||= Client.new(DEFAULT_CALENDARS)
+        end
       end
+
+      # The native Client is defined by the extension
+      # (Confium::Transparency::OTS::Client) with #stamp / #upgrade;
+      # the Proof class carries #digest / #to_bytes / #verify.
     end
   end
 end

data/lib/confium/transparency.rb

@@ -5,8 +5,8 @@
 # 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
+# `require`, not `autoload`: the native extension defines the OTS
+# constant at load time, which would shadow the autoload entry and
+# keep this file from ever running — the Ruby-level convenience
+# methods would silently vanish.
+require 'confium/transparency/ots'

data/lib/confium/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: confium
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Ribose Open
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys
@@ -120,9 +120,11 @@ files:
 - ext/confium_native/src/composite.rs
 - ext/confium_native/src/deployment.rs
 - ext/confium_native/src/ers.rs
+- ext/confium_native/src/gvl.rs
 - ext/confium_native/src/lib.rs
 - ext/confium_native/src/net.rs
 - ext/confium_native/src/openpgp_verify.rs
+- ext/confium_native/src/ots.rs
 - ext/confium_native/src/path.rs
 - ext/confium_native/src/pki.rs
 - ext/confium_native/src/store.rs