ciborium 0.1.0-x64-mingw-ucrt

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8f29d51c0cd4eed79549b18990c61d7da8b410432dd8192f683d75a77e504021
+  data.tar.gz: 4c8236bd9bb86fba40e8c6823f7e6b9bdf13bbd7a56f3850ef15c5954ea8c3af
+SHA512:
+  metadata.gz: 72ed8d457a4b7d73e61fd8bc875f1bca032b719872cb199cf49e08007573450d28fa20b74fe815f5db44f01f2284904ff905634092beb962c468a635164f1cf7
+  data.tar.gz: fa70c6c9c1baf19c4f836fc535fa4e7c0f65b44b81e90585cc35c9f80f531d99f0c5a043a6c7ca9c6e0a6b83f840696c2f7a3716c76b641496cdf33374d73611

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (2026-11-11)
+
+- Initial release: a CBOR encoder and decoder backed by a Rust extension, where tags carry meaning only through allowlisted extensions.
+- Built-in extensions for bignums, Time, URI and Regexp.
+- `profile: :ctap2` for the CTAP2 canonical CBOR encoding form that WebAuthn uses.
+- `Ciborium::Compat` and `ciborium/replace`, a stand-in for the cbor gem's interface.
+- RBS signatures under `sig/`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Sorah Fukumori
+
+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/NOTICE.md

@@ -0,0 +1,26 @@
+# Notices
+
+## Compiled into the native extension
+
+| Crate | License |
+|---|---|
+| [ciborium-ll](https://github.com/enarx/ciborium), ciborium-io | Apache-2.0 |
+| [magnus](https://github.com/matsadler/magnus) | MIT |
+| [rb-sys](https://github.com/oxidize-rb/rb-sys) | MIT OR Apache-2.0 |
+| [half](https://github.com/VoidStarKat/half-rs) | MIT OR Apache-2.0 |
+| [cfg-if](https://github.com/rust-lang/cfg-if) | MIT OR Apache-2.0 |
+| [zerocopy](https://github.com/google/zerocopy) | BSD-2-Clause OR Apache-2.0 OR MIT |
+
+The source gem builds these from crates.io. Precompiled gems carry their license texts under
+`licenses/`.
+
+## Test fixtures
+
+`spec/fixtures/webauthn/` holds attestation objects taken from the test suite of
+[webauthn-ruby](https://github.com/cedarcode/webauthn-ruby) (`spec/support/seeds.rb` at v3.5.0),
+which is available under the MIT License.
+
+`spec/upstream/` holds the specs of [cbor-ruby](https://github.com/cabo/cbor-ruby) (the cbor gem,
+`spec/` at commit 89e94f3b059deb58478eab51996f764fcc6ecd82), copied unmodified except for
+`spec_helper.rb`, which is replaced. cbor-ruby is available under the Apache License 2.0, a copy
+of which is in `spec/upstream/LICENSE.txt`.

data/README.md

@@ -0,0 +1,221 @@
+# Ciborium: CBOR for Ruby without surprises from the input
+
+Ciborium is a [CBOR](https://www.rfc-editor.org/rfc/rfc8949) encoder and decoder for Ruby, backed by a Rust extension built on [ciborium-ll](https://crates.io/crates/ciborium-ll).
+
+It also ships a compatibility layer for the [cbor](https://rubygems.org/gems/cbor) gem. `require "ciborium/replace"` makes `CBOR` refer to Ciborium, so gems written against the cbor gem, such as [webauthn](https://github.com/cedarcode/webauthn-ruby) and [cose](https://github.com/cedarcode/cose-ruby), run on Ciborium unchanged.
+
+## Why
+
+The cbor gem is a fork of msgpack-ruby's C extension with CBOR support added on top, and has not followed the memory-safety fixes msgpack-ruby made since.
+
+Ciborium is a fresh implementation:
+
+- **Memory safety**: parsing and serialization happen in Rust. Nesting is bounded by `max_depth` in both directions, and the decoder needs no recursion.
+- **Strict by default**: tags are not interpreted unless an extension is allowlisted, and invalid UTF-8, malformed simple values, duplicate map keys and trailing bytes all raise.
+- **CTAP2 canonical form**: `profile: :ctap2` validates and produces the encoding WebAuthn requires.
+- **RBS signatures** are shipped in `sig/`.
+
+## Installation
+
+```
+bundle add ciborium
+```
+
+Ciborium requires Ruby 3.3 or later.
+
+| Platform | Precompiled gem |
+|---|---|
+| Linux x86_64 and aarch64, glibc 2.34 or later | `x86_64-linux-gnu`, `aarch64-linux-gnu` |
+| Linux x86_64 and aarch64, musl | `x86_64-linux-musl`, `aarch64-linux-musl` |
+| Linux armv7, glibc 2.31 or later | `arm-linux-gnu` |
+| macOS 11 or later on Apple silicon | `arm64-darwin` |
+| Windows x64 | `x64-mingw-ucrt` |
+
+The precompiled gems carry the extension for Ruby 3.3, 3.4 and 4.0. Anywhere else the source gem builds the extension, which needs a Rust toolchain and libclang (for [rb-sys](https://github.com/oxidize-rb/rb-sys)).
+
+## Usage
+
+```ruby
+require "ciborium"
+
+bytes = Ciborium.encode({"name" => "ciborium", "tags" => [1, 2.5, nil]})
+Ciborium.decode(bytes) #=> {"name" => "ciborium", "tags" => [1, 2.5, nil]}
+
+Ciborium.decode("\xd8\x23\x63a*b".b) #=> #<data Ciborium::Tagged tag=35, value="a*b">
+```
+
+`decode` raises when bytes follow the item. `decode_prefix` returns the item and the number of bytes it took instead, and `decode_sequence` reads an [RFC 8742](https://www.rfc-editor.org/rfc/rfc8742) sequence:
+
+```ruby
+Ciborium.decode_prefix("\x82\x01\x02\xff".b) #=> [[1, 2], 3]
+Ciborium.decode_sequence("\x01\x02".b)        #=> [1, 2]
+```
+
+### Decoding options
+
+```ruby
+Ciborium.decode(bytes,
+  extensions: [],           # allowlisted extensions, see below
+  symbolize_keys: false,    # text map keys as (garbage-collectable) Symbols
+  max_depth: 128,           # nesting limit for arrays, maps and tags
+  duplicate_keys: :error,   # or :last_wins
+  profile: nil,             # or :ctap2
+)
+```
+
+### Encoding
+
+| Ruby | CBOR |
+|---|---|
+| `nil`, `true`, `false` | simple values 22, 21, 20 |
+| `Integer` in `-2**64...2**64` | major type 0 or 1, in the shortest form |
+| `Float` | the narrowest float that keeps the value exactly |
+| `String` in `ASCII-8BIT` | byte string |
+| other `String`, `Symbol` | text string, transcoded to UTF-8 |
+| `Array`, `Hash` | array, map, in insertion order |
+| `Ciborium::Tagged`, `Ciborium::Simple` | tag, simple value |
+| `Ciborium::Encoded` | its bytes as-is, after checking they hold one well-formed item |
+
+Anything else raises `Ciborium::EncodeError`, unless an extension encodes it or a `fallback` returns something to encode in its place:
+
+```ruby
+Ciborium.encode(Date.today, fallback: ->(date) { date.iso8601 })
+```
+
+### Streaming
+
+```ruby
+decoder = Ciborium::Decoder.new(symbolize_keys: true)
+until io.eof?
+  decoder.feed(io.readpartial(4096))
+  decoder.each { |item| handle(item) }  # yields only complete items
+end
+
+encoder = Ciborium::Encoder.new
+encoder.write_array_header(2).write(1).write("two")
+encoder.bytes #=> "\x82\x01ctwo"
+```
+
+`Decoder` also reads headers (`read_array_header`, `read_map_header`), and offers `skip` and `next_nil?`.
+
+### Errors
+
+| Class | Raised when |
+|---|---|
+| `Ciborium::MalformedError` | the input is not well-formed, breaks a strictness rule or the profile, or has trailing bytes |
+| `Ciborium::IncompleteError` | the input ends inside an item |
+| `Ciborium::DepthError` | nesting exceeds `max_depth` |
+| `Ciborium::ExtensionError` | an extension failed to decode a tag; the original error is the `cause` |
+| `Ciborium::UnexpectedTypeError` | a `Decoder` header reader found another type |
+| `Ciborium::EncodeError` | an object cannot be encoded, or an extension or fallback failed |
+
+All of them inherit from `Ciborium::Error`, and the decoding ones also from `Ciborium::DecodeError`.
+
+## Extensions
+
+An extension gives a tag meaning in both directions. Pass the built-in ones by name:
+
+```ruby
+Ciborium.decode(bytes, extensions: [:bignum, :time])
+Ciborium.encode(Time.now, extensions: [:time])
+```
+
+| Name | Tags | Ruby |
+|---|---|---|
+| `:bignum` | 2, 3 | `Integer` outside `-2**64...2**64` |
+| `:time` | 0, 1 | `Time`. It encodes as tag 1, using an Integer for whole seconds and a Float otherwise |
+| `:uri` | 32 | `URI::Generic` |
+| `:regexp` | 35 | `Regexp` without flags. `Ciborium::Extensions::Regexp.new(timeout: 0.1)` sets a match timeout |
+
+An extension builds Ruby objects from the input, so allowlist only those you trust the input with.
+
+Any object that responds to `tags`, `classes`, `decode(tag, value)` and `encode(object)` is an extension too:
+
+```ruby
+class PointExtension
+  def tags = [40_000]
+  def classes = [Point]
+  def decode(_tag, (x, y)) = Point.new(x, y)
+  def encode(point) = Ciborium::Tagged.new(40_000, [point.x, point.y])
+end
+
+Ciborium.decode(bytes, extensions: [PointExtension.new])
+```
+
+## WebAuthn and the CTAP2 profile
+
+WebAuthn encodes everything in the CTAP2 canonical CBOR encoding form ([CTAP 2.2 section 8](https://fidoalliance.org/specs/fido-v2.2-ps-20250714/fido-client-to-authenticator-protocol-v2.2-ps-20250714.html#ctap2-canonical-cbor-encoding-form)). That form uses no tags at all, so WebAuthn data needs no extension. With `profile: :ctap2`, decoding rejects anything outside that form: tags, indefinite lengths, arguments longer than needed, and map keys that are out of order or duplicated. Encoding sorts map keys into canonical order and refuses tags.
+
+```ruby
+attestation = Ciborium.decode(attestation_object, profile: :ctap2)
+
+# The credential public key in authenticator data is followed by extension data.
+cose_key, length = Ciborium.decode_prefix(credential_public_key_and_rest, profile: :ctap2)
+```
+
+## Replacing the cbor gem
+
+`Ciborium::Compat` implements the cbor gem's interface on top of Ciborium:
+
+- `CBOR.encode`, `CBOR.decode` and their `pack`, `dump`, `unpack` and `load` aliases
+- `Packer`, `Unpacker` and `Buffer`
+- `Tagged`, `Simple`, its error classes, and `to_cbor`
+
+`ciborium/replace` installs it as `CBOR` and marks the cbor gem as loaded, so a later `require "cbor"` does nothing. Keep whatever depends on the cbor gem in the Gemfile, and add ciborium without letting Bundler require it:
+
+```ruby
+# Gemfile
+gem "webauthn"
+gem "ciborium", require: false
+```
+
+Then require `ciborium/replace` after Bundler sets up the load path, and before anything requires `cbor`. In a Rails app, that is between these two lines of `config/application.rb`:
+
+```ruby
+# config/application.rb
+require_relative "boot"
+require "rails/all"
+
+require "ciborium/replace"
+Bundler.require(*Rails.groups)
+```
+
+Outside Rails, put it after `require "bundler/setup"` and before `Bundler.require` or the first `require "webauthn"`. If the cbor gem was loaded first anyway, `ciborium/replace` warns and replaces `CBOR` regardless.
+
+Because callers of the cbor gem cannot pass options, Compat takes its extensions from one process-wide setting. Nothing is allowlisted by default, so big Integers (tags 2 and 3) decode to `Tagged` until `:bignum` is allowlisted:
+
+```ruby
+Ciborium::Compat.extensions = [:bignum, :time]
+```
+
+The specs of webauthn-ruby and cose-ruby run against Compat in CI with this default, so neither needs any tag extension. The cbor gem's own specs run too, both with no extensions and with every built-in one allowlisted.
+
+### Behaviour of Compat
+
+Compat follows Ciborium's rules rather than reproducing the cbor gem exactly:
+
+- Tags decode to `Tagged` unless allowlisted in `Compat.extensions`, and Integers outside `-2**64...2**64` encode only with `:bignum` allowlisted.
+- Input that is not well-formed or breaks Ciborium's strictness rules raises `MalformedFormatError`, as does an extension failure, with the original error as the `cause`.
+- Encoding raises `EncodeError` on invalid UTF-8, and on a `Regexp` with flags.
+- `Time` encodes subseconds as a Float.
+- `Tagged` and `Simple` are immutable `Data`.
+- `Unpacker#buffer` holds input that has not yet reached the decoder.
+
+## Development
+
+```
+mise install
+bin/setup
+bundle exec rake compile spec spec:upstream steep
+hk check --all
+```
+
+The Rust extension lives in `ext/ciborium`. Signatures are written inline with rbs-inline and generated into `sig/generated` by `rake rbs`. That directory is committed, and CI checks it is current.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sorah/ciborium-ruby.
+
+## License
+
+MIT License, see [LICENSE.txt](./LICENSE.txt). Third-party code compiled into the extension, and test fixtures taken from other projects, are listed in [NOTICE.md](./NOTICE.md).

data/Rakefile

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rake/extensiontask"
+
+GEMSPEC = Bundler.load_gemspec("ciborium.gemspec")
+
+# No gemspec: precompiled gems are assembled by rakelib/native.rake.
+Rake::ExtensionTask.new("ciborium_native") do |ext|
+  ext.ext_dir = "ext/ciborium"
+  ext.lib_dir = "lib/ciborium"
+  ext.source_pattern = "{Cargo.toml,Cargo.lock,build.rs,src/**/*.rs}"
+  # Platforms without a native CI runner are cross-compiled inside rb-sys-dock
+  # images (see .github/workflows/native.yml).
+  ext.cross_compile = true
+  ext.cross_platform = %w[x86_64-linux-musl aarch64-linux-musl arm-linux-gnueabihf]
+end
+
+RSpec::Core::RakeTask.new(:spec)
+task spec: :compile
+
+namespace :spec do
+  desc "Run the cbor gem's specs against Ciborium::Compat, with default and with all extensions"
+  task upstream: :compile do
+    ["default", "all"].each do |mode|
+      sh(
+        {"CIBORIUM_UPSTREAM_EXTENSIONS" => mode}, "rspec", "--options", "spec/upstream/.rspec", "-I", "spec/upstream",
+        "--default-path", "spec/upstream", "spec/upstream"
+      )
+    end
+  end
+end
+
+desc "Regenerate inline RBS signatures under sig/generated"
+task :rbs do
+  sh "rbs-inline --output=sig/generated lib"
+  sh "rbs -r time -r uri -I sig/generated -I sig/manual -I sig-stub validate"
+end
+
+desc "Type check lib against the RBS signatures"
+task steep: :rbs do
+  sh "steep check"
+end
+
+task default: [:spec, "spec:upstream", :steep]

data/lib/ciborium/compat/buffer.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  module Compat
+    # A byte queue in front of an optional IO, as CBOR::Buffer of the cbor gem: reads refill from
+    # the IO when the queue runs dry, and writes go out to it once the queue fills.
+    class Buffer
+      DEFAULT_IO_BUFFER_SIZE = 32 * 1024 #: Integer
+
+      # @rbs @io: untyped
+      # @rbs @io_buffer_size: Integer
+      # @rbs @data: String
+      # @rbs @pos: Integer
+
+      attr_reader :io #: untyped
+
+      # The cbor gem's read_reference_threshold and write_reference_threshold tune its chunk
+      # sharing, which this buffer does not do, so they are accepted and ignored.
+      #
+      #: (?untyped io, ?Hash[Symbol, untyped]? options) -> void
+      def initialize(io = nil, options = nil)
+        if options.nil? && io.is_a?(Hash)
+          options = io
+          io = nil
+        end
+        @io = io
+        @io_buffer_size = Integer(options ? options.fetch(:io_buffer_size, DEFAULT_IO_BUFFER_SIZE) : DEFAULT_IO_BUFFER_SIZE)
+        @data = "".b
+        @pos = 0
+      end
+
+      #: () -> nil
+      def clear
+        @data = "".b
+        @pos = 0
+        nil
+      end
+
+      #: () -> Integer
+      def size
+        @data.bytesize - @pos
+      end
+
+      #: () -> bool
+      def empty?
+        size.zero?
+      end
+
+      #: (String data) -> Integer
+      def write(data)
+        @data << data.b
+        flush if @io && size >= @io_buffer_size
+        data.bytesize
+      end
+
+      #: (String data) -> self
+      def <<(data)
+        write(data)
+        self
+      end
+
+      # Consumes up to n bytes, or everything without n, refilling from the IO until it ends.
+      # Returns nil when n is positive and nothing is left.
+      #
+      #: (?Integer? n, ?String? out) -> String?
+      def read(n = nil, out = nil)
+        return read_all(nil, out) if n.nil?
+        return replace(out, "".b) if n.zero?
+
+        fill(n)
+        return if empty?
+
+        replace(out, take(n))
+      end
+
+      # Consumes exactly n bytes, or everything without n. Raises EOFError, consuming nothing,
+      # when fewer than n bytes are left.
+      #
+      #: (?Integer? n, ?String? out) -> String
+      def read_all(n = nil, out = nil)
+        if n.nil?
+          fill(nil)
+          return replace(out, take(size))
+        end
+        return replace(out, "".b) if n.zero?
+
+        fill(n)
+        raise ::EOFError, "end of buffer reached" if size < n
+
+        replace(out, take(n))
+      end
+
+      # Consumes up to n bytes and returns how many it consumed.
+      #
+      #: (Integer n) -> Integer
+      def skip(n)
+        fill(n)
+        take(n).bytesize
+      end
+
+      # Consumes exactly n bytes, or raises EOFError consuming nothing.
+      #
+      #: (Integer n) -> self
+      def skip_all(n)
+        fill(n)
+        raise ::EOFError, "end of buffer reached" if size < n
+
+        take(n)
+        self
+      end
+
+      #: () -> String
+      def to_str
+        @data.byteslice(@pos..) || "".b
+      end
+
+      alias_method :to_s, :to_str
+
+      #: () -> Array[String]
+      def to_a
+        [to_str]
+      end
+
+      # Writes the queued bytes to the IO, if there is one.
+      #
+      #: () -> self
+      def flush
+        write_to(@io) if @io
+        self
+      end
+
+      #: () -> nil
+      def close
+        @io&.close
+        nil
+      end
+
+      # Writes the queued bytes to io and consumes them.
+      #
+      #: (untyped io) -> Integer
+      def write_to(io)
+        data = take(size)
+        io.write(data)
+        data.bytesize
+      end
+
+      #: (Integer? n) -> void
+      private def fill(n)
+        return unless @io
+
+        while n.nil? || size < n
+          chunk = read_io
+          break unless chunk
+
+          @data << chunk.b
+        end
+      end
+
+      #: () -> String?
+      private def read_io
+        if @io.respond_to?(:readpartial)
+          @io.readpartial(@io_buffer_size)
+        else
+          @io.read(@io_buffer_size)
+        end
+      rescue ::EOFError
+        nil
+      end
+
+      #: (Integer n) -> String
+      private def take(n)
+        data = @data.byteslice(@pos, n) || "".b
+        @pos += data.bytesize
+        if @pos == @data.bytesize
+          @data = "".b
+          @pos = 0
+        end
+        data
+      end
+
+      #: (String? out, String data) -> String
+      private def replace(out, data)
+        return data unless out
+
+        out.replace(data)
+      end
+    end
+  end
+end

data/lib/ciborium/compat/errors.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  module Compat
+    class UnpackError < StandardError; end
+
+    class MalformedFormatError < UnpackError; end
+
+    class StackError < UnpackError; end
+
+    # Raised by Unpacker#read_array_header and #read_map_header on an item of another type.
+    class TypeError < StandardError; end
+
+    # Raises the cbor gem's exception for a Ciborium decoding failure, keeping it as the cause.
+    #
+    #: [T] () { () -> T } -> T
+    def self.translate_errors
+      yield
+    rescue IncompleteError
+      raise ::EOFError, "end of buffer reached"
+    rescue DepthError
+      raise StackError, "nesting too deep"
+    rescue UnexpectedTypeError
+      raise TypeError, "unexpected type"
+    rescue DecodeError
+      raise MalformedFormatError, "malformed CBOR"
+    end
+  end
+end

data/lib/ciborium/compat/packer.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  module Compat
+    # CBOR::Packer of the cbor gem, writing through Ciborium::Encoder.
+    class Packer
+      # @rbs @buffer: Buffer
+      # @rbs @encoder: Ciborium::Encoder
+
+      attr_reader :buffer #: Buffer
+
+      #: (?untyped io, ?Hash[Symbol, untyped]? options) -> void
+      def initialize(io = nil, options = nil)
+        @buffer = Buffer.new(io, options)
+        @encoder = Ciborium::Encoder.new(**Compat.encode_options)
+      end
+
+      #: (untyped object) -> self
+      def write(object)
+        @encoder.write(object)
+        drain
+      end
+
+      alias_method :pack, :write
+
+      #: () -> self
+      def write_nil
+        write(nil)
+      end
+
+      #: (Integer length) -> self
+      def write_array_header(length)
+        @encoder.write_array_header(length)
+        drain
+      end
+
+      #: (Integer length) -> self
+      def write_map_header(length)
+        @encoder.write_map_header(length)
+        drain
+      end
+
+      #: () -> self
+      def flush
+        @buffer.flush
+        self
+      end
+
+      #: () -> nil
+      def clear
+        @buffer.clear
+      end
+
+      #: () -> Integer
+      def size
+        @buffer.size
+      end
+
+      #: () -> bool
+      def empty?
+        @buffer.empty?
+      end
+
+      #: (untyped io) -> Integer
+      def write_to(io)
+        @buffer.write_to(io)
+      end
+
+      #: () -> String
+      def to_str
+        @buffer.to_str
+      end
+
+      alias_method :to_s, :to_str
+
+      #: () -> Array[String]
+      def to_a
+        @buffer.to_a
+      end
+
+      #: () -> self
+      private def drain
+        @buffer << @encoder.bytes
+        @encoder.clear
+        self
+      end
+    end
+  end
+end