longfellow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2421e8e860bf25c8098ed549c1e80af167266f5501e83339584b1e6ecbd5a3d
+  data.tar.gz: 668f55d3772117c37918aa76374251e64c3c848680a2bb87e59eebb2b97f7ef7
+SHA512:
+  metadata.gz: bc45c228cd8f9aa0e3f09c88cf98459318bd9e55fb2d82c8fe04762a2857406b33ac3dd969f6e041f829a38b065473643f4d783d1277d458ca8a36adfeb1f270
+  data.tar.gz: a68ed9796d63d4792feea36c1deff8fb178e0065e7d0509a7526d92020c192bb445b5f94e89b43bce4b4c7d1d965ffc2597c2629f594dfae529ab5e74fb0c3f5

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"longfellow" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["azuchi@chaintope.com"](mailto:"azuchi@chaintope.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 azuchi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# Longfellow
+
+Ruby bindings for Google's [longfellow-zk](https://github.com/google/longfellow-zk),
+the zero-knowledge library for identity protocols. This gem lets you generate
+and verify zero-knowledge proofs over ISO **mdoc / mDL** verifiable credentials
+directly from Ruby.
+
+The bindings load the upstream C ABI (`run_mdoc_prover`, `run_mdoc_verifier`,
+`generate_circuit`, ...) through [Ruby-FFI](https://github.com/ffi/ffi). The
+native library is compiled from the vendored upstream sources at install time.
+
+## Supported version
+
+This gem vendors **[google/longfellow-zk](https://github.com/google/longfellow-zk)
+`v0.9`**, pinned as a git submodule (`vendor/longfellow-zk`). The native library
+is built from exactly that revision, and the ZK system it exposes is
+`longfellow-libzk-v1`.
+
+Only the ISO **mdoc / mDL** C ABI (`circuits/mdoc/mdoc_zk.h`) is wrapped. JWT and
+W3C Verifiable Credentials are not supported, because upstream provides no C ABI
+for them (they exist only as experimental C++ circuit templates).
+
+## Requirements
+
+The native library is built from source during installation, so the build
+toolchain must be available:
+
+- A C++17 compiler (`clang++` preferred, `g++` works)
+- [CMake](https://cmake.org/) >= 3.13
+- OpenSSL (libcrypto) development headers
+- zstd (libzstd) development headers
+
+On Debian/Ubuntu:
+
+```bash
+sudo apt-get install build-essential cmake clang libssl-dev libzstd-dev
+```
+
+## Installation
+
+This gem vendors longfellow-zk as a git submodule, so a source checkout must
+initialize submodules before building:
+
+```bash
+git clone https://github.com/azuchi/longfellow.git
+cd longfellow
+git submodule update --init --recursive
+bundle install
+bundle exec rake compile
+```
+
+Add it to a project's Gemfile from git:
+
+```ruby
+gem "longfellow", git: "https://github.com/azuchi/longfellow.git", submodules: true
+```
+
+## Usage
+
+```ruby
+require "longfellow"
+
+# 1. Pick a ZK specification (these are hardcoded in the native library).
+#    Each spec fixes the circuit format and the number of attributes it opens.
+spec = Longfellow.zk_specs.first        # 1 attribute, longfellow-libzk v7
+# or look one up by system name + circuit hash that a peer advertised:
+# spec = Longfellow.find_zk_spec("longfellow-libzk-v1", "8d0792...")
+
+# 2. Generate the circuit bytes for that spec. This is deterministic and can be
+#    cached and shared between provers and verifiers.
+circuit = Longfellow.generate_circuit(spec)
+Longfellow.circuit_id(circuit, spec).unpack1("H*")  # == spec.circuit_hash
+
+# 3. Describe the claims to open.
+attribute = Longfellow::Attribute.new(
+  namespace_id: "org.iso.18013.5.1",
+  id:           "age_over_18",
+  cbor_value:   "\xF5".b              # CBOR true
+)
+
+# 4. Prover side: produce a proof.
+proof = Longfellow.prove(
+  circuit:      circuit,
+  mdoc:         mdoc_bytes,           # the full mdoc/mDL
+  public_key_x: issuer_pkx,           # string representation of the issuer key
+  public_key_y: issuer_pky,
+  transcript:   session_transcript,
+  attributes:   [attribute],
+  now:          "2024-01-30T09:00:00Z",
+  zk_spec:      spec
+)
+
+# 5. Verifier side: check it. Returns true, or raises Longfellow::VerifierError.
+Longfellow.verify(
+  circuit:      circuit,
+  public_key_x: issuer_pkx,
+  public_key_y: issuer_pky,
+  transcript:   session_transcript,
+  attributes:   [attribute],
+  now:          "2024-01-30T09:00:00Z",
+  proof:        proof,
+  doc_type:     Longfellow::DEFAULT_DOC_TYPE,
+  zk_spec:      spec
+)
+```
+
+`Attribute`s may also be passed as plain hashes:
+
+```ruby
+attributes: [{ namespace_id: "org.iso.18013.5.1", id: "age_over_18", cbor_value: "\xF5".b }]
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `Longfellow.zk_specs` | All ZK specifications compiled into the library. |
+| `Longfellow.find_zk_spec(system, hash)` | Look up a spec by system name and circuit hash (`nil` if unknown). |
+| `Longfellow.generate_circuit(spec)` | Compressed circuit bytes for a spec. |
+| `Longfellow.circuit_id(circuit, spec)` | 32-byte SHA-256 identifier of a circuit bundle. |
+| `Longfellow.prove(...)` | Generate a proof; raises `Longfellow::ProverError` on failure. |
+| `Longfellow.verify(...)` | Verify a proof; returns `true` or raises `Longfellow::VerifierError`. |
+
+Errors carry a stable `#symbol` and the raw native `#code`:
+
+```ruby
+begin
+  Longfellow.verify(...)
+rescue Longfellow::VerifierError => e
+  e.symbol  # e.g. :general_failure
+  e.code    # the raw MdocVerifierErrorCode integer
+end
+```
+
+## Development
+
+```bash
+bundle exec rake compile          # build the native library
+bundle exec rspec --tag ~slow     # fast unit specs
+bundle exec rspec --tag slow      # full prove/verify round trip (~13s)
+```
+
+The slow integration spec exercises a real prover → verifier round trip against
+an mdoc test vector extracted from the upstream examples.
+
+## License
+
+This gem is available under the [MIT License](LICENSE.txt).
+
+The vendored upstream library, [google/longfellow-zk](https://github.com/google/longfellow-zk),
+is distributed under the Apache License 2.0; see
+`vendor/longfellow-zk/LICENSE`.

data/ext/longfellow/CMakeLists.txt

@@ -0,0 +1,76 @@
+# Self-contained build of the longfellow-zk mdoc ZK C ABI as a single shared
+# library suitable for loading via Ruby-FFI.
+#
+# Upstream's top-level CMake pulls in GoogleTest/Benchmark via
+# find_package(... REQUIRED), which we do not want as install-time
+# dependencies. Instead we compile only the translation units that make up the
+# upstream `mdoc_static` target (mdoc + flatsha + ec + algebra + util) and link
+# against the system OpenSSL (crypto) and zstd. Everything else used by the
+# prover/verifier (ligero, sumcheck, zk, gf2k, cbor, ...) is header-only
+# template code and needs no separate compilation.
+cmake_minimum_required(VERSION 3.13)
+project(longfellow_native CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+# Root of the vendored upstream tree (include paths are relative to lib/).
+get_filename_component(LFZK_ROOT
+  "${CMAKE_CURRENT_SOURCE_DIR}/../../vendor/longfellow-zk/lib" ABSOLUTE)
+
+if(NOT EXISTS "${LFZK_ROOT}/circuits/mdoc/mdoc_zk.h")
+  message(FATAL_ERROR
+    "vendored longfellow-zk sources not found at ${LFZK_ROOT}. "
+    "Run: git submodule update --init --recursive")
+endif()
+
+# Mirror the architecture-specific flags upstream uses (carry-less multiply for
+# the GF(2^128) arithmetic, etc.).
+string(TOLOWER "${CMAKE_SYSTEM_PROCESSOR}" LFZK_ARCH)
+if(LFZK_ARCH MATCHES "x86_64|amd64")
+  set(ARCH_FLAGS -mpclmul)
+elseif(LFZK_ARCH MATCHES "i386|i686")
+  set(ARCH_FLAGS -msse2 -mpclmul)
+elseif(LFZK_ARCH MATCHES "aarch64|arm64")
+  set(ARCH_FLAGS -march=armv8-a+crypto)
+elseif(LFZK_ARCH MATCHES "armv7")
+  set(ARCH_FLAGS -march=armv7-a -mfpu=neon-vfpv4 -mfloat-abi=hard)
+else()
+  set(ARCH_FLAGS "")
+  message(STATUS "Unrecognized architecture '${LFZK_ARCH}', no ISA flags added.")
+endif()
+
+set(LFZK_SOURCES
+  ${LFZK_ROOT}/util/log.cc
+  ${LFZK_ROOT}/util/crypto.cc
+  ${LFZK_ROOT}/algebra/nat.cc
+  ${LFZK_ROOT}/algebra/crt.cc
+  ${LFZK_ROOT}/ec/p256.cc
+  ${LFZK_ROOT}/ec/p256k1.cc
+  ${LFZK_ROOT}/circuits/sha/flatsha256_witness.cc
+  ${LFZK_ROOT}/circuits/sha/sha256_constants.cc
+  ${LFZK_ROOT}/circuits/mdoc/mdoc_zk.cc
+  ${LFZK_ROOT}/circuits/mdoc/mdoc_decompress.cc
+  ${LFZK_ROOT}/circuits/mdoc/mdoc_generate_circuit.cc
+  ${LFZK_ROOT}/circuits/mdoc/mdoc_circuit_id.cc
+  ${LFZK_ROOT}/circuits/mdoc/zk_spec.cc
+)
+
+add_library(longfellow_native SHARED ${LFZK_SOURCES})
+target_include_directories(longfellow_native PRIVATE ${LFZK_ROOT})
+target_compile_options(longfellow_native PRIVATE
+  $<$<COMPILE_LANGUAGE:CXX>:${ARCH_FLAGS}>)
+
+# The upstream C ABI lives in extern "C" functions compiled with default
+# visibility, so they are exported from the shared object as-is.
+
+find_package(OpenSSL REQUIRED)
+target_link_libraries(longfellow_native PRIVATE OpenSSL::Crypto)
+
+find_library(ZSTD_LIBRARY NAMES zstd libzstd REQUIRED)
+target_link_libraries(longfellow_native PRIVATE ${ZSTD_LIBRARY})

data/ext/longfellow/extconf.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# This is not a conventional mkmf C extension. The native artifact is the
+# longfellow-zk C ABI compiled (via CMake) into a single shared object that the
+# pure-Ruby FFI layer loads at runtime. RubyGems still drives extension builds
+# through `extconf.rb` + `make`, so here we:
+#
+#   1. run CMake to build ext/longfellow/build/liblongfellow_native.{so,dylib}
+#   2. copy the result next to the Ruby sources (lib/longfellow/)
+#   3. emit a trivial Makefile whose `all`/`install`/`clean` targets succeed
+#
+# so the standard `gem install` flow works unchanged.
+
+require "fileutils"
+require "rbconfig"
+
+ext_dir   = __dir__
+gem_root  = File.expand_path("../..", ext_dir)
+build_dir = File.join(ext_dir, "build")
+lib_out   = File.join(gem_root, "lib", "longfellow")
+vendor    = File.join(gem_root, "vendor", "longfellow-zk", "lib", "circuits",
+                      "mdoc", "mdoc_zk.h")
+
+abort_msg = lambda do |msg|
+  warn "[longfellow] #{msg}"
+  exit(1)
+end
+
+unless File.exist?(vendor)
+  abort_msg.call(
+    "vendored longfellow-zk sources are missing. When installing from a git " \
+    "checkout run: git submodule update --init --recursive"
+  )
+end
+
+def find_tool(*names)
+  names.each do |name|
+    path = `command -v #{name} 2>/dev/null`.strip
+    return path unless path.empty?
+  end
+  nil
+end
+
+cmake = find_tool("cmake")
+abort_msg.call("cmake was not found in PATH; it is required to build longfellow.") unless cmake
+
+# Prefer clang++ to match upstream, but fall back to the platform default.
+cxx = find_tool("clang++", "g++")
+
+config_cmd = [cmake, "-S", ext_dir, "-B", build_dir, "-DCMAKE_BUILD_TYPE=Release"]
+config_cmd << "-DCMAKE_CXX_COMPILER=#{cxx}" if cxx
+
+puts "[longfellow] configuring native library..."
+system(*config_cmd) || abort_msg.call("cmake configure failed")
+
+puts "[longfellow] building native library..."
+jobs = (ENV["MAKEFLAGS"].to_s[/-j\s*(\d+)/, 1] || 4)
+system(cmake, "--build", build_dir, "--parallel", jobs.to_s) ||
+  abort_msg.call("cmake build failed")
+
+so = Dir[File.join(build_dir, "liblongfellow_native.{so,dylib,bundle}")].first
+abort_msg.call("native library was not produced") unless so
+
+FileUtils.mkdir_p(lib_out)
+FileUtils.cp(so, lib_out)
+puts "[longfellow] installed #{File.basename(so)} -> lib/longfellow/"
+
+# A no-op Makefile so that `make` and `make install` invoked by RubyGems pass.
+File.write(File.join(ext_dir, "Makefile"), <<~MAKEFILE)
+  all:
+  \t@true
+  install:
+  \t@true
+  clean:
+  \t@true
+  .PHONY: all install clean
+MAKEFILE

data/lib/longfellow/attribute.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Longfellow
+  # A claim that the prover must open and the verifier checks: a single mdoc
+  # attribute identified by its namespace and element identifier, together with
+  # the expected value encoded as the raw bytes of its CBOR representation.
+  #
+  # Mirrors the C `RequestedAttribute` struct. The fixed-size C buffers bound the
+  # lengths: namespace_id <= 64, id <= 32, cbor_value <= 64 bytes.
+  class Attribute
+    MAX_NAMESPACE = 64
+    MAX_ID = 32
+    MAX_CBOR_VALUE = 64
+
+    attr_reader :namespace_id, :id, :cbor_value
+
+    # @param namespace_id [String] e.g. "org.iso.18013.5.1"
+    # @param id [String] element identifier, e.g. "age_over_18"
+    # @param cbor_value [String] raw CBOR-encoded value bytes
+    def initialize(namespace_id:, id:, cbor_value:)
+      @namespace_id = String(namespace_id).b
+      @id = String(id).b
+      @cbor_value = String(cbor_value).b
+      validate!
+    end
+
+    # Coerce a Hash or Attribute into an Attribute.
+    def self.coerce(obj)
+      case obj
+      when Attribute then obj
+      when Hash then new(**obj.transform_keys(&:to_sym))
+      else
+        raise ArgumentError,
+              "expected Longfellow::Attribute or Hash, got #{obj.class}"
+      end
+    end
+
+    # Populate a C::RequestedAttribute struct (backed by zeroed memory).
+    def write_to(struct)
+      ptr = struct.to_ptr
+      ptr.put_bytes(struct.offset_of(:namespace_id), @namespace_id) unless @namespace_id.empty?
+      ptr.put_bytes(struct.offset_of(:id), @id) unless @id.empty?
+      ptr.put_bytes(struct.offset_of(:cbor_value), @cbor_value) unless @cbor_value.empty?
+      struct[:namespace_len] = @namespace_id.bytesize
+      struct[:id_len] = @id.bytesize
+      struct[:cbor_value_len] = @cbor_value.bytesize
+      struct
+    end
+
+    private
+
+    def validate!
+      check_length(:namespace_id, @namespace_id, MAX_NAMESPACE)
+      check_length(:id, @id, MAX_ID)
+      check_length(:cbor_value, @cbor_value, MAX_CBOR_VALUE)
+    end
+
+    def check_length(name, value, max)
+      return if value.bytesize <= max
+
+      raise ArgumentError,
+            "#{name} is #{value.bytesize} bytes, exceeds maximum of #{max}"
+    end
+  end
+end

data/lib/longfellow/c.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module Longfellow
+  # Low-level FFI binding to the longfellow-zk C ABI declared in
+  # `lib/circuits/mdoc/mdoc_zk.h`. Application code should prefer the
+  # high-level helpers on {Longfellow}; this module mirrors the C surface
+  # one-to-one and performs no validation or memory management of its own.
+  module C
+    extend FFI::Library
+
+    # The shared object produced by ext/longfellow during installation lives
+    # next to this file.
+    LIBRARY_PATH = File.expand_path(
+      "liblongfellow_native.#{FFI::Platform::LIBSUFFIX}", __dir__
+    )
+
+    unless File.exist?(LIBRARY_PATH)
+      raise LoadError,
+            "longfellow native library not found at #{LIBRARY_PATH}. " \
+            "Reinstall the gem or run `rake compile` after checking out the " \
+            "git submodule (git submodule update --init --recursive)."
+    end
+
+    # The native library is searched first; libc provides `free` for the
+    # prover/circuit buffers the C ABI hands back to us.
+    ffi_lib [LIBRARY_PATH, FFI::Library::LIBC]
+
+    # enum { kNumZkSpecs = 12 };
+    NUM_ZK_SPECS = 12
+
+    # kSHA256DigestSize
+    CIRCUIT_ID_SIZE = 32
+
+    # typedef struct { ... } ZkSpecStruct;
+    class ZkSpecStruct < FFI::Struct
+      layout(
+        :system,         :pointer,
+        :circuit_hash,   [:char, 65],
+        :num_attributes, :size_t,
+        :version,        :size_t,
+        :block_enc_hash, :size_t,
+        :block_enc_sig,  :size_t
+      )
+    end
+
+    # typedef struct { ... } RequestedAttribute;
+    class RequestedAttribute < FFI::Struct
+      layout(
+        :namespace_id,    [:uint8, 64],
+        :id,              [:uint8, 32],
+        :cbor_value,      [:uint8, 64],
+        :namespace_len,   :size_t,
+        :id_len,          :size_t,
+        :cbor_value_len,  :size_t
+      )
+    end
+
+    # MdocProverErrorCode run_mdoc_prover(...)
+    attach_function :run_mdoc_prover, [
+      :pointer, :size_t,  # bcp, bcsz
+      :pointer, :size_t,  # mdoc, mdoc_len
+      :string,  :string,  # pkx, pky
+      :pointer, :size_t,  # transcript, tr_len
+      :pointer, :size_t,  # attrs, attrs_len
+      :string,            # now
+      :pointer, :pointer, # prf (uint8_t**), proof_len (size_t*)
+      :pointer            # zk_spec_version
+    ], :int
+
+    # MdocVerifierErrorCode run_mdoc_verifier(...)
+    attach_function :run_mdoc_verifier, [
+      :pointer, :size_t,  # bcp, bcsz
+      :string,  :string,  # pkx, pky
+      :pointer, :size_t,  # transcript, tr_len
+      :pointer, :size_t,  # attrs, attrs_len
+      :string,            # now
+      :pointer, :size_t,  # zkproof, proof_len
+      :string,            # docType
+      :pointer            # zk_spec_version
+    ], :int
+
+    # CircuitGenerationErrorCode generate_circuit(zk_spec, cb, clen)
+    attach_function :generate_circuit, [:pointer, :pointer, :pointer], :int
+
+    # int circuit_id(id[32], bcp, bcsz, zk_spec)
+    attach_function :circuit_id, [:pointer, :pointer, :size_t, :pointer], :int
+
+    # const ZkSpecStruct* find_zk_spec(system_name, circuit_hash)
+    attach_function :find_zk_spec, [:string, :string], :pointer
+
+    # void free(void*) — releases buffers allocated by the prover / circuit gen.
+    attach_function :c_free, :free, [:pointer], :void
+
+    # The hardcoded `kZkSpecs[kNumZkSpecs]` global. Returns the FFI structs that
+    # point into the library's static storage (do not free or mutate them).
+    def self.zk_specs
+      base = ffi_libraries.first.find_variable("kZkSpecs")
+      Array.new(NUM_ZK_SPECS) do |i|
+        ZkSpecStruct.new(base + (i * ZkSpecStruct.size))
+      end
+    end
+  end
+end

data/lib/longfellow/errors.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Longfellow
+  # Base class for every error raised by this gem.
+  class Error < StandardError; end
+
+  # Raised when a native call fails. Carries the raw return {#code} from the C
+  # ABI and a stable {#symbol} for programmatic handling.
+  class NativeError < Error
+    attr_reader :code, :symbol
+
+    def initialize(symbol, code, context)
+      @symbol = symbol
+      @code = code
+      super("#{context} failed: #{symbol} (code #{code})")
+    end
+  end
+
+  # run_mdoc_prover failure (MdocProverErrorCode).
+  class ProverError < NativeError; end
+
+  # run_mdoc_verifier failure (MdocVerifierErrorCode).
+  class VerifierError < NativeError; end
+
+  # generate_circuit failure (CircuitGenerationErrorCode).
+  class CircuitGenerationError < NativeError; end
+
+  # Maps the C ABI return enums to symbols and raises on non-success. The arrays
+  # below are ordered to match the enum declarations in mdoc_zk.h exactly.
+  module Errors
+    PROVER_CODES = %i[
+      success null_input invalid_input circuit_parsing_failure
+      hash_parsing_failure witness_creation_failure general_failure
+      memory_allocation_failure invalid_zk_spec_version root_decoding_failure
+      documents_missing document_0_missing doctype_missing
+      issuer_signed_missing issuer_auth_missing mso_missing nsig_missing
+      namespaces_missing device_signed_missing device_auth_missing
+      device_signature_missing device_key_missing mso_decoding_failure
+      validity_info_missing device_key_info_missing attribute_decode_failure
+      attribute_ei_missing attribute_ev_missing attribute_did_missing
+      signature_failure device_signature_failure attribute_not_found
+      attribute_too_long tagged_mso_too_big version_not_supported
+      attribute_random_missing
+    ].freeze
+
+    VERIFIER_CODES = %i[
+      success circuit_parsing_failure proof_too_small hash_parsing_failure
+      signature_parsing_failure general_failure null_input invalid_input
+      arguments_too_small attribute_number_mismatch invalid_zk_spec_version
+      invalid_cbor
+    ].freeze
+
+    CIRCUIT_CODES = %i[
+      success null_input zlib_failure general_failure invalid_zk_spec_version
+    ].freeze
+
+    module_function
+
+    def check_prover!(code)
+      check!(code, PROVER_CODES, ProverError, "run_mdoc_prover")
+    end
+
+    def check_verifier!(code)
+      check!(code, VERIFIER_CODES, VerifierError, "run_mdoc_verifier")
+    end
+
+    def check_circuit!(code)
+      check!(code, CIRCUIT_CODES, CircuitGenerationError, "generate_circuit")
+    end
+
+    def check!(code, table, klass, context)
+      return if code.zero?
+
+      symbol = table[code] || :unknown
+      raise klass.new(symbol, code, context)
+    end
+  end
+end

data/lib/longfellow/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Longfellow
+  VERSION = "0.1.0"
+end

data/lib/longfellow/zk_spec.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Longfellow
+  # Immutable view over a `ZkSpecStruct` entry owned by the native library.
+  #
+  # A ZK specification identifies a circuit format/interpretation that a prover
+  # and verifier must agree on. Instances are obtained from {Longfellow.zk_specs}
+  # or {Longfellow.find_zk_spec}; they wrap a pointer into the library's static
+  # `kZkSpecs` storage and are passed back into the prover, verifier and circuit
+  # generator.
+  class ZkSpec
+    attr_reader :system, :circuit_hash, :num_attributes, :version,
+                :block_enc_hash, :block_enc_sig
+
+    # @param struct [Longfellow::C::ZkSpecStruct]
+    def initialize(struct)
+      @struct = struct
+      system_ptr = struct[:system]
+      @system = system_ptr.null? ? nil : system_ptr.read_string
+      # circuit_hash is a NUL-terminated 64-char hex string in a [65]char field.
+      @circuit_hash = struct[:circuit_hash].to_ptr.read_string
+      @num_attributes = struct[:num_attributes]
+      @version = struct[:version]
+      @block_enc_hash = struct[:block_enc_hash]
+      @block_enc_sig = struct[:block_enc_sig]
+    end
+
+    # @return [FFI::Pointer] pointer to the underlying ZkSpecStruct, for passing
+    #   into native calls.
+    def to_ptr
+      @struct.to_ptr
+    end
+
+    def to_s
+      "#<Longfellow::ZkSpec #{@system} v#{@version} " \
+        "attrs=#{@num_attributes} hash=#{@circuit_hash}>"
+    end
+    alias inspect to_s
+  end
+end