hide-protocol 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c2a953028799de42c33b2d4500308cdc35dd51f0ab3a421135869f9b7f22659f
+  data.tar.gz: b666943d4bed7075eb7899e3ac5a5b9c7475db0cd6cca222e7ed29cca8b158ee
+SHA512:
+  metadata.gz: b4e375e687c8c6dbdfec9bc487fbf0b8aedc32cf1e72f7139d018e5922ed9bf11f4951dd9cef88893b9cdd4642f46ef82e4c796a4f365135ed354228d25665aa
+  data.tar.gz: 99059cec81d10c21228681a9ea36a2985f944e3e34379e03921cc35a3a3a6106733ed26899d7ec701280e48ab897356b2a0a9acf040b299cf1f6d307400a2a25

data/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   The full license text is available at the URL above.

data/README.md

@@ -0,0 +1,177 @@
+# hide-protocol (Ruby)
+
+Ruby bindings to the HIDE core: hybrid post-quantum encryption for files and
+messages (X25519 + ML-KEM-768).
+
+## Read this before using it
+
+**This is experimental and unaudited.** Do not use it to protect data you
+cannot afford to lose or expose. The format may change.
+
+**A successful decryption proves the data was not altered. It does *not* prove
+who sent it.** Anyone holding your public key can produce a container that
+decrypts for you. If you need to know the sender, sign the message with
+`Hide::SigningIdentity` and verify it separately.
+
+A decrypted filename is attacker-controlled. Never use it to choose an output
+path.
+
+## How it binds
+
+There is no Ruby cryptography here, and no compiled extension. The gem calls
+the same Rust core as the CLI through its C ABI, using stdlib `fiddle` — so
+installing it needs no compiler and adds no runtime gem dependency.
+
+The native library is found in this order:
+
+1. `HIDE_LIBRARY`, if set — the full path to the shared library.
+2. Beside the gem, in `lib/hide_protocol/`, where the release workflow puts it.
+3. The system loader.
+
+Platform names are `hide_ffi.dll` on Windows, `libhide_ffi.dylib` on macOS and
+`libhide_ffi.so` elsewhere.
+
+### Running against a local build
+
+```sh
+cargo build -p hide-ffi
+```
+
+Then point `HIDE_LIBRARY` at the result:
+
+```sh
+# Linux
+export HIDE_LIBRARY="$PWD/target/debug/libhide_ffi.so"
+# macOS
+export HIDE_LIBRARY="$PWD/target/debug/libhide_ffi.dylib"
+```
+
+```powershell
+# Windows
+$env:HIDE_LIBRARY = "$PWD\target\debug\hide_ffi.dll"
+```
+
+## Use
+
+```ruby
+require "hide_protocol"
+
+Hide::SecretKey.generate do |secret|
+  box = Hide.encrypt(
+    File.binread("salarii.csv"),
+    recipients: [secret.public_key],
+    filename: "salarii.csv",
+    media_type: "text/csv"
+  )
+
+  opened = Hide.decrypt(box, secret)
+  opened.plaintext  # => the original bytes
+  opened.filename   # => "salarii.csv"
+  opened.media_type # => "text/csv"
+end
+```
+
+The block form always closes the key, including when the block raises. Without
+a block, call `#close` yourself.
+
+### Keys
+
+```ruby
+secret = Hide::SecretKey.generate
+public_key = secret.public_key            # 1216 bytes, binary
+
+sealed = secret.protect("a long passphrase")  # for writing to disk
+Hide.inspect_key(sealed)                      # => "protected"
+
+reopened = Hide::SecretKey.open(sealed, "a long passphrase")
+```
+
+A passphrase must be at least `Hide::MIN_PASSPHRASE_LEN` (8) characters. A
+forgotten passphrase cannot be recovered: there is no escrow.
+
+Secret key material never crosses into Ruby. `inspect` and `to_s` report only
+whether the key is open or closed, and a closed key raises on any use.
+
+### Sharing a public key
+
+```ruby
+text = Hide.armor_public_key(public_key)  # "hide-public-key:..."
+Hide.dearmor_public_key(text)             # back to bytes
+```
+
+### Signing
+
+Encryption and signing share one seed, so there is a single thing to back up.
+
+```ruby
+sealed = Hide::SigningIdentity.generate("a long passphrase")  # write this to disk
+
+Hide::SigningIdentity.open(sealed, "a long passphrase") do |signer|
+  public_key = signer.public_key                  # 1984 bytes, shareable
+  signature = signer.sign("myapp/v1 release", bytes)  # 3373 bytes
+  Hide.verify(public_key, "myapp/v1 release", bytes, signature)
+end
+```
+
+`verify` returns `nil` and raises on failure, rather than returning a boolean a
+caller could forget to test. The context string separates uses of one identity:
+never let a remote party choose it.
+
+### Proving possession live
+
+A detached signature proves possession at some point, to nobody in particular,
+and can be replayed. A challenge binds a nonce, an audience and an expiry.
+
+```ruby
+challenge = Hide.new_challenge("ssh://host.example", Time.now.to_i, 60)
+answer = signer.answer(challenge)
+
+spent = Hide::SpentNonces.new   # must outlive the request
+spent.accept(challenge, answer, public_key, Time.now.to_i)
+```
+
+The second acceptance of the same answer raises `ChallengeReplayedError`, and
+one presented after the window raises `ChallengeExpiredError`.
+
+## API
+
+| | |
+|---|---|
+| `Hide.version` | version of the native core |
+| `Hide.encrypt(plaintext, recipients:, filename: nil, media_type: nil)` | binary String |
+| `Hide.decrypt(container, secret)` | `Decrypted` with `plaintext`, `filename`, `media_type` |
+| `Hide.armor_public_key` / `Hide.dearmor_public_key` | text form of a public key |
+| `Hide.inspect_key(bytes)` | `"raw"` or `"protected"` |
+| `Hide::SecretKey.generate` / `.open(bytes, passphrase = nil)` | keys |
+| `Hide::SigningIdentity.generate(passphrase)` | sealed key file bytes |
+| `Hide::SigningIdentity.open(bytes, passphrase = nil)` | `#public_key`, `#sign`, `#answer`, `#close` |
+| `Hide.verify(public_key, context, message, signature)` | raises unless it verifies |
+| `Hide.new_challenge(audience, now, valid_for)` | challenge bytes |
+| `Hide::SpentNonces#accept(challenge, signature, public_key, now)` | accepts once |
+| `Hide::PUBLIC_KEY_LEN` (1216), `Hide::MIN_PASSPHRASE_LEN` (8) | constants |
+| `Hide::SIGNATURE_LEN` (3373), `Hide::VERIFYING_KEY_LEN` (1984), `Hide::NONCE_LEN` (32) | constants |
+
+Encryption takes between 1 and 64 recipients, each public key exactly
+`Hide::PUBLIC_KEY_LEN` bytes.
+
+All binary values in and out are ASCII-8BIT (binary) Strings. Metadata comes
+back as UTF-8.
+
+### Errors
+
+Everything raises a subclass of `Hide::Error`:
+
+`InvalidArgumentError`, `AuthenticationError` (altered data, or not a
+container), `WrongPassphraseError`, `NoMatchingRecipientError` (this key was
+not a recipient), `NotAKeyError`, `TooLargeError`, `ClosedKeyError`,
+`ChallengeExpiredError`, `ChallengeReplayedError`.
+
+## Tests
+
+```sh
+HIDE_LIBRARY=/path/to/libhide_ffi.so ruby -Ilib -Itest test/test_hide.rb
+```
+
+## Licence
+
+Apache-2.0.

data/lib/hide_protocol/binding.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "fiddle"
+require "rbconfig"
+
+module Hide
+  # Raw access to the HIDE C core.
+  #
+  # fiddle rather than the ffi gem: fiddle ships with Ruby, so installing this
+  # gem needs no compiler and adds no runtime dependency, and the ABI is
+  # described in exactly one place.
+  module Binding
+    OK = 0
+    ERR_INVALID_ARGUMENT = 1
+    ERR_WRONG_PASSPHRASE = 2
+    ERR_NOT_A_KEY = 3
+    ERR_AUTHENTICATION = 4
+    ERR_NO_MATCHING_RECIPIENT = 5
+    ERR_TOO_LARGE = 7
+    ERR_MALFORMED = 6
+    ERR_CHALLENGE_EXPIRED = 8
+    ERR_CHALLENGE_REPLAYED = 9
+    ERR_PANIC = 98
+    ERR_INTERNAL = 99
+
+    KEY_RAW = 0
+    KEY_PROTECTED = 1
+
+    PUBLIC_KEY_LEN = 1216
+    SIGNATURE_LEN = 3373
+    VERIFYING_KEY_LEN = 1984
+    NONCE_LEN = 32
+    MIN_PASSPHRASE_LEN = 8
+
+    WORD = Fiddle::SIZEOF_VOIDP
+    # HideBuffer is { uint8_t *data; size_t len; size_t capacity; }.
+    BUFFER_SIZE = WORD * 3
+    # size_t and a pointer are the same width on every platform Ruby builds on.
+    WORD_PACK = WORD == 8 ? "J" : "L"
+
+    class LibraryNotFound < StandardError; end
+
+    def self.library_names
+      case RbConfig::CONFIG["host_os"]
+      when /mswin|mingw|cygwin/ then ["hide_ffi.dll"]
+      when /darwin/ then ["libhide_ffi.dylib"]
+      else ["libhide_ffi.so"]
+      end
+    end
+
+    # Mirrors the Python binding: an explicit override, then the copy shipped
+    # beside the gem, then whatever the system loader can find.
+    def self.load_library
+      here = File.dirname(__FILE__)
+      candidates = library_names.map { |name| File.join(here, name) }
+
+      override = ENV["HIDE_LIBRARY"]
+      candidates.unshift(override) if override && !override.empty?
+
+      candidates.each do |candidate|
+        return Fiddle.dlopen(candidate) if File.exist?(candidate)
+      end
+
+      begin
+        Fiddle.dlopen(library_names.first)
+      rescue Fiddle::DLError
+        raise LibraryNotFound,
+              "the HIDE native library was not found. Install a gem that " \
+              "bundles it, or set HIDE_LIBRARY to the path of " \
+              "#{library_names.first} built by `cargo build -p hide-ffi`."
+      end
+    end
+
+    LIB = load_library
+
+    VOIDP = Fiddle::TYPE_VOIDP
+    INT32 = Fiddle::TYPE_INT
+    SIZE_T = Fiddle::TYPE_SIZE_T
+    VOID = Fiddle::TYPE_VOID
+    UINT64 = Fiddle::TYPE_LONG_LONG
+
+    SIGNATURES = {
+      hide_error_message: [[INT32], VOIDP],
+      hide_version: [[], VOIDP],
+      # A 24-byte struct return is passed through a hidden out-pointer by both
+      # the SysV and the Windows x64 ABI, so binding it this way is the
+      # portable spelling; see empty_buffer for the fallback.
+      hide_buffer_empty: [[VOIDP], VOID],
+      hide_buffer_free: [[VOIDP], VOID],
+      hide_keypair_generate: [[VOIDP, VOIDP], INT32],
+      hide_inspect_key: [[VOIDP, SIZE_T, VOIDP], INT32],
+      hide_secret_key_open: [[VOIDP, SIZE_T, VOIDP, VOIDP], INT32],
+      hide_secret_key_protect: [[VOIDP, VOIDP, VOIDP], INT32],
+      hide_secret_key_public: [[VOIDP, VOIDP], INT32],
+      hide_secret_key_free: [[VOIDP], VOID],
+      hide_public_key_armor: [[VOIDP, SIZE_T, VOIDP], INT32],
+      hide_public_key_dearmor: [[VOIDP, VOIDP], INT32],
+      hide_encrypt: [[VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, VOIDP, VOIDP], INT32],
+      hide_decrypt: [[VOIDP, SIZE_T, VOIDP, VOIDP, VOIDP, VOIDP], INT32],
+      hide_identity_generate: [[VOIDP, VOIDP], INT32],
+      hide_signing_identity_open: [[VOIDP, SIZE_T, VOIDP, VOIDP], INT32],
+      hide_signing_identity_public: [[VOIDP, VOIDP], INT32],
+      hide_signing_identity_free: [[VOIDP], VOID],
+      hide_sign_message: [[VOIDP, VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP], INT32],
+      hide_verify_message: [[VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T], INT32],
+      hide_challenge_new: [[VOIDP, UINT64, UINT64, VOIDP], INT32],
+      hide_challenge_answer: [[VOIDP, VOIDP, SIZE_T, VOIDP], INT32],
+      hide_spent_nonces_new: [[], VOIDP],
+      hide_spent_nonces_free: [[VOIDP], VOID],
+      hide_challenge_accept: [[VOIDP, VOIDP, SIZE_T, VOIDP, SIZE_T, VOIDP, SIZE_T, UINT64], INT32]
+    }.freeze
+
+    FUNCTIONS = SIGNATURES.each_with_object({}) do |(name, (args, ret)), acc|
+      acc[name] = Fiddle::Function.new(LIB[name.to_s], args, ret, name: name.to_s)
+    end.freeze
+
+    def self.call(name, *args)
+      FUNCTIONS.fetch(name).call(*args)
+    end
+
+    # A static C string owned by the library; never freed by us.
+    def self.static_string(pointer)
+      return "" if pointer.null?
+
+      Fiddle::Pointer.new(pointer.to_i).to_s.force_encoding(Encoding::UTF_8)
+    end
+
+    # Scratch space for one HideBuffer, zeroed the way hide_buffer_empty zeroes it.
+    def self.empty_buffer
+      slot = Fiddle::Pointer.malloc(BUFFER_SIZE, Fiddle::RUBY_FREE)
+      slot[0, BUFFER_SIZE] = "\x00" * BUFFER_SIZE
+      call(:hide_buffer_empty, slot)
+      slot
+    end
+
+    def self.read_word(slot, index)
+      slot[index * WORD, WORD].unpack1(WORD_PACK)
+    end
+
+    # Copies a native buffer out and frees the original. The length field is
+    # the only thing consulted: text from this library is length-prefixed, not
+    # NUL-terminated, because metadata is attacker-controlled and a NUL in it
+    # would silently truncate a C-string read.
+    def self.take(slot)
+      data = read_word(slot, 0)
+      len = read_word(slot, 1)
+      bytes =
+        if data.zero? || len.zero?
+          +""
+        else
+          Fiddle::Pointer.new(data, len)[0, len]
+        end
+      bytes.force_encoding(Encoding::BINARY)
+    ensure
+      call(:hide_buffer_free, slot)
+    end
+
+    # Metadata arrives as length-prefixed UTF-8; empty means absent.
+    def self.take_text(slot)
+      raw = take(slot)
+      return nil if raw.empty?
+
+      raw.dup.force_encoding(Encoding::UTF_8).scrub
+    end
+
+    # A slot holding one pointer-sized out-parameter.
+    def self.pointer_slot
+      slot = Fiddle::Pointer.malloc(WORD, Fiddle::RUBY_FREE)
+      slot[0, WORD] = "\x00" * WORD
+      slot
+    end
+  end
+end

data/lib/hide_protocol.rb

@@ -0,0 +1,543 @@
+# frozen_string_literal: true
+
+require_relative "hide_protocol/binding"
+
+# HIDE — encrypt to a person, not to a key.
+#
+# EXPERIMENTAL AND UNAUDITED. Do not protect data you cannot afford to lose or
+# expose. A successful decryption proves the data was not altered; it does
+# *not* prove who created it.
+#
+#   secret = Hide::SecretKey.generate
+#   box = Hide.encrypt("hello", recipients: [secret.public_key])
+#   Hide.decrypt(box, secret).plaintext # => "hello"
+module Hide
+  PUBLIC_KEY_LEN = Binding::PUBLIC_KEY_LEN
+  SIGNATURE_LEN = Binding::SIGNATURE_LEN
+  VERIFYING_KEY_LEN = Binding::VERIFYING_KEY_LEN
+  NONCE_LEN = Binding::NONCE_LEN
+  MIN_PASSPHRASE_LEN = Binding::MIN_PASSPHRASE_LEN
+
+  MAX_RECIPIENTS = 64
+
+  # Base class for every failure this library reports.
+  class Error < StandardError; end
+
+  # An argument this library refused before it reached the core.
+  class InvalidArgumentError < Error; end
+
+  # The data was altered, or is not a HIDE container.
+  class AuthenticationError < Error; end
+
+  # The passphrase is wrong, or the key file was modified.
+  class WrongPassphraseError < Error; end
+
+  # This key was not one of the recipients.
+  class NoMatchingRecipientError < Error; end
+
+  # The bytes are not a HIDE key.
+  class NotAKeyError < Error; end
+
+  # More data than the format admits.
+  class TooLargeError < Error; end
+
+  # The key has been closed and its material released.
+  class ClosedKeyError < Error; end
+
+  # The challenge expired before it was answered.
+  class ChallengeExpiredError < Error; end
+
+  # This challenge was already answered. Almost certainly a replay.
+  class ChallengeReplayedError < Error; end
+
+  ERRORS = {
+    Binding::ERR_INVALID_ARGUMENT => InvalidArgumentError,
+    Binding::ERR_WRONG_PASSPHRASE => WrongPassphraseError,
+    Binding::ERR_NOT_A_KEY => NotAKeyError,
+    Binding::ERR_AUTHENTICATION => AuthenticationError,
+    Binding::ERR_NO_MATCHING_RECIPIENT => NoMatchingRecipientError,
+    Binding::ERR_MALFORMED => AuthenticationError,
+    Binding::ERR_TOO_LARGE => TooLargeError,
+    Binding::ERR_CHALLENGE_EXPIRED => ChallengeExpiredError,
+    Binding::ERR_CHALLENGE_REPLAYED => ChallengeReplayedError
+  }.freeze
+
+  class << self
+    def version
+      Binding.static_string(Binding.call(:hide_version))
+    end
+
+    # Encrypts for 1..64 recipient public keys. Returns binary bytes.
+    def encrypt(plaintext, recipients:, filename: nil, media_type: nil)
+      joined = join_recipients(recipients)
+      plain = binary(plaintext, "plaintext")
+
+      out = Binding.empty_buffer
+      check(Binding.call(
+              :hide_encrypt,
+              buffer_arg(plain), plain.bytesize,
+              joined, recipients.length,
+              cstring(filename), cstring(media_type),
+              out
+            ))
+      Binding.take(out)
+    end
+
+    # Decrypts and verifies. Nothing is returned unless the whole payload
+    # authenticates, so a caller cannot act on unverified data.
+    def decrypt(container, secret)
+      raise TypeError, "secret must be a Hide::SecretKey" unless secret.is_a?(SecretKey)
+
+      bytes = binary(container, "container")
+      out = Binding.empty_buffer
+      filename = Binding.empty_buffer
+      media_type = Binding.empty_buffer
+      begin
+        check(Binding.call(
+                :hide_decrypt,
+                buffer_arg(bytes), bytes.bytesize,
+                secret.__handle,
+                out, filename, media_type
+              ))
+      rescue StandardError
+        # On failure the core leaves the out-parameters untouched, so these are
+        # still the empty buffers we created and freeing them is what releases
+        # the scratch space.
+        Binding.take(out)
+        Binding.take(filename)
+        Binding.take(media_type)
+        raise
+      end
+
+      Decrypted.new(
+        Binding.take(out),
+        Binding.take_text(filename),
+        Binding.take_text(media_type)
+      )
+    end
+
+    # Renders a public key as pasteable text.
+    def armor_public_key(public_key)
+      bytes = binary(public_key, "public key")
+      out = Binding.empty_buffer
+      check(Binding.call(:hide_public_key_armor, buffer_arg(bytes), bytes.bytesize, out))
+      Binding.take_text(out) || ""
+    end
+
+    def dearmor_public_key(text)
+      out = Binding.empty_buffer
+      check(Binding.call(:hide_public_key_dearmor, cstring(text.to_s), out))
+      Binding.take(out)
+    end
+
+    # Returns "raw" or "protected" without needing the passphrase.
+    def inspect_key(data)
+      bytes = binary(data, "key")
+      slot = Binding.pointer_slot
+      check(Binding.call(:hide_inspect_key, buffer_arg(bytes), bytes.bytesize, slot))
+      kind = slot[0, Binding::WORD].unpack1(Binding::WORD_PACK) & 0xFFFFFFFF
+      kind == Binding::KEY_PROTECTED ? "protected" : "raw"
+    end
+
+    def sign(identity, context, message)
+      identity.sign(context, message)
+    end
+
+    # Raises unless both the Ed25519 and the ML-DSA half verify. Nothing is
+    # returned: a caller who forgot to test a boolean would read every failure
+    # as a pass.
+    def verify(public_key, context, message, signature)
+      key = binary(public_key, "public key")
+      ctx = binary(context, "context")
+      msg = binary(message, "message")
+      sig = binary(signature, "signature")
+      check(Binding.call(
+              :hide_verify_message,
+              buffer_arg(key), key.bytesize,
+              buffer_arg(ctx), ctx.bytesize,
+              buffer_arg(msg), msg.bytesize,
+              buffer_arg(sig), sig.bytesize
+            ))
+      nil
+    end
+
+    # A detached signature proves possession at some point, to nobody in
+    # particular, and can be replayed. A challenge binds a random nonce, an
+    # audience and an expiry, so an answer is good once, here, now.
+    def new_challenge(audience, now, valid_for)
+      out = Binding.empty_buffer
+      check(Binding.call(
+              :hide_challenge_new,
+              cstring(audience), Integer(now), Integer(valid_for), out
+            ))
+      Binding.take(out)
+    end
+
+    def check(code)
+      return if code == Binding::OK
+
+      message = Binding.static_string(Binding.call(:hide_error_message, code))
+      raise ERRORS.fetch(code, Error), message
+    end
+
+    private
+
+    def join_recipients(recipients)
+      unless recipients.is_a?(Array)
+        raise InvalidArgumentError, "recipients must be an array of public keys"
+      end
+      unless recipients.length.between?(1, MAX_RECIPIENTS)
+        raise InvalidArgumentError, "there must be between 1 and #{MAX_RECIPIENTS} recipients"
+      end
+
+      recipients.each_with_object(+"") do |key, acc|
+        bytes = binary(key, "public key")
+        if bytes.bytesize != PUBLIC_KEY_LEN
+          raise InvalidArgumentError,
+                "a public key is #{PUBLIC_KEY_LEN} bytes, got #{bytes.bytesize}"
+        end
+        acc << bytes
+      end.force_encoding(Encoding::BINARY)
+    end
+
+    def binary(value, what)
+      raise InvalidArgumentError, "#{what} must be a String" unless value.is_a?(String)
+
+      value.dup.force_encoding(Encoding::BINARY)
+    end
+
+    # Fiddle passes a String as a pointer to its bytes, but a zero-length
+    # String has no address the callee may read, so give it one it can ignore.
+    def buffer_arg(bytes)
+      bytes.empty? ? Fiddle::Pointer.malloc(1, Fiddle::RUBY_FREE) : bytes
+    end
+
+    # NULL for absent, UTF-8 plus a terminator otherwise.
+    def cstring(value)
+      return nil if value.nil?
+
+      text = value.to_s
+      if text.include?("\x00")
+        raise InvalidArgumentError, "text passed to the core must not contain NUL"
+      end
+
+      "#{text.encode(Encoding::UTF_8)}\x00".force_encoding(Encoding::BINARY)
+    end
+  end
+
+  # A verified payload. Holding one of these means it authenticated.
+  #
+  # The filename is attacker-controlled: never use it to choose an output path.
+  class Decrypted
+    attr_reader :plaintext, :filename, :media_type
+
+    def initialize(plaintext, filename, media_type)
+      @plaintext = plaintext
+      @filename = filename
+      @media_type = media_type
+      freeze
+    end
+
+    alias data plaintext
+  end
+
+  # Argument coercion shared by the classes that pass byte strings to the core.
+  module Bytes
+    private
+
+    def binary(value, what)
+      raise InvalidArgumentError, "#{what} must be a String" unless value.is_a?(String)
+
+      value.dup.force_encoding(Encoding::BINARY)
+    end
+
+    # Fiddle passes a String as a pointer to its bytes, but a zero-length
+    # String has no address the callee may read, so give it one it can ignore.
+    def arg(bytes)
+      bytes.empty? ? Fiddle::Pointer.malloc(1, Fiddle::RUBY_FREE) : bytes
+    end
+  end
+
+  # A signing key. The seed stays inside the native library and is never
+  # exposed to Ruby; there is deliberately no accessor for it.
+  class SigningIdentity
+    include Bytes
+
+    class << self
+      # Creates an identity and returns the sealed key file to store. One seed
+      # backs both encryption and signing, so there is one thing to back up.
+      def generate(passphrase)
+        text = passphrase.to_s
+        if text.length < MIN_PASSPHRASE_LEN
+          raise InvalidArgumentError,
+                "the passphrase must be at least #{MIN_PASSPHRASE_LEN} characters"
+        end
+
+        out = Binding.empty_buffer
+        Hide.check(Binding.call(:hide_identity_generate, "#{text}\x00".b, out))
+        Binding.take(out)
+      end
+
+      # Loads a signing identity. A key file written before signatures existed
+      # carries no signing seed and fails rather than being downgraded.
+      def open(data, passphrase = nil, &block)
+        raise InvalidArgumentError, "key data must be a String" unless data.is_a?(String)
+
+        bytes = data.dup.force_encoding(Encoding::BINARY)
+        handle = Binding.pointer_slot
+        Hide.check(Binding.call(
+                     :hide_signing_identity_open,
+                     bytes.empty? ? Fiddle::Pointer.malloc(1, Fiddle::RUBY_FREE) : bytes,
+                     bytes.bytesize,
+                     passphrase.nil? ? nil : "#{passphrase}\x00".b,
+                     handle
+                   ))
+        identity = new(handle[0, Binding::WORD].unpack1(Binding::WORD_PACK))
+        return identity unless block
+
+        begin
+          block.call(identity)
+        ensure
+          identity.close
+        end
+      end
+
+      alias load open
+    end
+
+    def initialize(address)
+      @address = address
+    end
+
+    # The shareable verifying key, for others to check signatures with.
+    def public_key
+      alive!
+      out = Binding.empty_buffer
+      Hide.check(Binding.call(:hide_signing_identity_public, handle, out))
+      Binding.take(out)
+    end
+
+    # context separates uses of one identity, so a signature made for one
+    # purpose cannot be replayed as another. Never let a remote party choose it.
+    def sign(context, message)
+      alive!
+      ctx = binary(context, "context")
+      msg = binary(message, "message")
+      out = Binding.empty_buffer
+      Hide.check(Binding.call(
+                   :hide_sign_message,
+                   handle,
+                   arg(ctx), ctx.bytesize,
+                   arg(msg), msg.bytesize,
+                   out
+                 ))
+      Binding.take(out)
+    end
+
+    # Answers a challenge, proving possession to whoever issued it.
+    def answer(challenge)
+      alive!
+      bytes = binary(challenge, "challenge")
+      out = Binding.empty_buffer
+      Hide.check(Binding.call(:hide_challenge_answer, handle, arg(bytes), bytes.bytesize, out))
+      Binding.take(out)
+    end
+
+    def close
+      return if @address.nil? || @address.zero?
+
+      Binding.call(:hide_signing_identity_free, Fiddle::Pointer.new(@address))
+      @address = nil
+      nil
+    end
+
+    def closed?
+      @address.nil? || @address.zero?
+    end
+
+    # Never render key material, not even a fingerprint of it.
+    def inspect
+      "#<Hide::SigningIdentity #{closed? ? "closed" : "open"}>"
+    end
+
+    alias to_s inspect
+
+    private
+
+    def handle
+      Fiddle::Pointer.new(@address)
+    end
+
+    def alive!
+      raise ClosedKeyError, "this identity has been closed" if closed?
+    end
+  end
+
+  # The verifier's record of answered challenges.
+  #
+  # Replay can only be detected by the verifier: a replayed answer is a genuine
+  # signature and nothing about it is invalid on its own. This must therefore
+  # outlive a single request.
+  class SpentNonces
+    include Bytes
+
+    def self.open
+      record = new
+      return record unless block_given?
+
+      begin
+        yield record
+      ensure
+        record.close
+      end
+    end
+
+    def initialize
+      pointer = Binding.call(:hide_spent_nonces_new)
+      raise Error, "could not allocate the nonce record" if pointer.null?
+
+      @address = pointer.to_i
+    end
+
+    # Accepts an answer exactly once: raises ChallengeReplayedError the second
+    # time, ChallengeExpiredError after the window, AuthenticationError if it
+    # does not verify.
+    def accept(challenge, signature, public_key, now)
+      raise ClosedKeyError, "this record has been closed" if closed?
+
+      chal = binary(challenge, "challenge")
+      sig = binary(signature, "signature")
+      key = binary(public_key, "public key")
+      Hide.check(Binding.call(
+                   :hide_challenge_accept,
+                   Fiddle::Pointer.new(@address),
+                   arg(chal), chal.bytesize,
+                   arg(sig), sig.bytesize,
+                   arg(key), key.bytesize,
+                   Integer(now)
+                 ))
+      nil
+    end
+
+    def close
+      return if closed?
+
+      Binding.call(:hide_spent_nonces_free, Fiddle::Pointer.new(@address))
+      @address = nil
+      nil
+    end
+
+    def closed?
+      @address.nil? || @address.zero?
+    end
+  end
+
+  # A secret key. The bytes stay inside the native library and are never
+  # exposed to Ruby; there is deliberately no accessor for them.
+  class SecretKey
+    class << self
+      def generate(&block)
+        handle = Binding.pointer_slot
+        public_key = Binding.empty_buffer
+        Hide.check(Binding.call(:hide_keypair_generate, handle, public_key))
+        Binding.take(public_key)
+        wrap(handle, &block)
+      end
+
+      # Loads a key file. A protected key without its passphrase fails.
+      def open(data, passphrase = nil, &block)
+        unless data.is_a?(String)
+          raise InvalidArgumentError, "key data must be a String"
+        end
+
+        bytes = data.dup.force_encoding(Encoding::BINARY)
+        handle = Binding.pointer_slot
+        Hide.check(Binding.call(
+                     :hide_secret_key_open,
+                     bytes.empty? ? Fiddle::Pointer.malloc(1, Fiddle::RUBY_FREE) : bytes,
+                     bytes.bytesize,
+                     passphrase.nil? ? nil : "#{passphrase}\x00".b,
+                     handle
+                   ))
+        wrap(handle, &block)
+      end
+
+      alias load open
+
+      private
+
+      # With a block the key is always closed, even if the block raises.
+      def wrap(handle, &block)
+        key = new(handle[0, Binding::WORD].unpack1(Binding::WORD_PACK))
+        return key unless block
+
+        begin
+          block.call(key)
+        ensure
+          key.close
+        end
+      end
+    end
+
+    def initialize(address)
+      @address = address
+    end
+
+    def public_key
+      alive!
+      out = Binding.empty_buffer
+      Hide.check(Binding.call(:hide_secret_key_public, handle, out))
+      Binding.take(out)
+    end
+
+    # Seals this key with a passphrase, for writing to disk. A forgotten
+    # passphrase cannot be recovered: there is no escrow.
+    def protect(passphrase)
+      alive!
+      text = passphrase.to_s
+      if text.length < MIN_PASSPHRASE_LEN
+        raise InvalidArgumentError,
+              "the passphrase must be at least #{MIN_PASSPHRASE_LEN} characters"
+      end
+
+      out = Binding.empty_buffer
+      Hide.check(Binding.call(:hide_secret_key_protect, handle, "#{text}\x00".b, out))
+      Binding.take(out)
+    end
+
+    def close
+      return if @address.nil? || @address.zero?
+
+      Binding.call(:hide_secret_key_free, Fiddle::Pointer.new(@address))
+      @address = nil
+      nil
+    end
+
+    def closed?
+      @address.nil? || @address.zero?
+    end
+
+    # Never render key material, not even a fingerprint of it.
+    def inspect
+      "#<Hide::SecretKey #{closed? ? "closed" : "open"}>"
+    end
+
+    alias to_s inspect
+
+    # Internal: the raw handle, for Hide.decrypt.
+    def __handle
+      alive!
+      handle
+    end
+
+    private
+
+    def handle
+      Fiddle::Pointer.new(@address)
+    end
+
+    def alive!
+      raise ClosedKeyError, "this key has been closed" if closed?
+    end
+  end
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: hide-protocol
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- HIDE contributors
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 'Ruby bindings to the HIDE core (X25519 + ML-KEM-768). Experimental and
+  unaudited: a successful decryption proves the data was not altered, not who created
+  it.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/hide_protocol.rb
+- lib/hide_protocol/binding.rb
+homepage: https://github.com/hide-protocol/hide
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://github.com/hide-protocol/hide
+  source_code_uri: https://github.com/hide-protocol/hide
+  bug_tracker_uri: https://github.com/hide-protocol/hide/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Experimental hybrid post-quantum file and message encryption. Unaudited.
+test_files: []