ciborium 0.1.0-x86_64-linux-gnu

data/lib/ciborium/compat/unpacker.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  module Compat
+    # CBOR::Unpacker of the cbor gem, reading through Ciborium::Decoder. Input passes through
+    # buffer, which also reads from io when more is needed.
+    class Unpacker
+      # @rbs @buffer: Buffer
+      # @rbs @decoder: Ciborium::Decoder
+
+      attr_reader :buffer #: Buffer
+
+      # options takes symbolize_keys, and the Buffer options.
+      #
+      #: (?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
+        @buffer = Buffer.new(io, options)
+        @decoder = Ciborium::Decoder.new(**Compat.decode_options, symbolize_keys: !!options&.[](:symbolize_keys))
+      end
+
+      #: (String data) -> self
+      def feed(data)
+        @buffer << data
+        self
+      end
+
+      #: () -> untyped
+      def read
+        with_input { @decoder.read }
+      end
+
+      alias_method :unpack, :read
+
+      #: () -> nil
+      def skip
+        with_input { @decoder.skip }
+        nil
+      end
+
+      # Whether the next item is null. Consumes nothing.
+      #
+      #: () -> bool
+      def skip_nil
+        with_input { @decoder.next_nil? }
+      end
+
+      #: () -> Integer
+      def read_array_header
+        with_input { @decoder.read_array_header }
+      end
+
+      #: () -> Integer
+      def read_map_header
+        with_input { @decoder.read_map_header }
+      end
+
+      # Yields each item until the input runs out, leaving a partial item buffered.
+      #
+      #: () { (untyped) -> void } -> nil
+      #: () -> Enumerator[untyped, nil]
+      def each
+        return enum_for(:each) unless block_given?
+
+        loop do
+          item = begin
+            read
+          rescue ::EOFError
+            break
+          end
+          yield item
+        end
+        nil
+      end
+
+      #: (String data) { (untyped) -> void } -> nil
+      def feed_each(data, &block)
+        feed(data)
+        each(&block)
+      end
+
+      #: () -> nil
+      def reset
+        @buffer.clear
+        @decoder.reset
+        nil
+      end
+
+      # Runs the block on the decoder, moving more input into it until the block stops raising
+      # IncompleteError or the input ends.
+      #
+      #: [T] () { () -> T } -> T
+      private def with_input
+        Compat.translate_errors do
+          @decoder.feed(@buffer.read_all(@buffer.size)) unless @buffer.empty?
+          yield
+        rescue IncompleteError
+          chunk = @buffer.read(Buffer::DEFAULT_IO_BUFFER_SIZE)
+          raise unless chunk
+
+          @decoder.feed(chunk)
+          retry
+        end
+      end
+    end
+  end
+end

data/lib/ciborium/compat.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require_relative "../ciborium"
+require_relative "compat/errors"
+require_relative "compat/buffer"
+require_relative "compat/packer"
+require_relative "compat/unpacker"
+
+module Ciborium
+  # The interface of the cbor gem (CBOR), implemented on top of Ciborium. Tag extensions follow
+  # Compat.extensions, so a tag that is not allowlisted decodes to Tagged. require
+  # "ciborium/replace" to install it as CBOR.
+  module Compat
+    Tagged = Ciborium::Tagged
+    Simple = Ciborium::Simple
+
+    # Nothing is allowlisted until the application opts in, as with Ciborium itself.
+    DEFAULT_EXTENSIONS = [] #: Array[extension]
+    DEFAULT_EXTENSIONS.freeze
+
+    # @rbs self.@extensions: Array[extension]
+    @extensions = DEFAULT_EXTENSIONS
+
+    # The extensions every Compat entry point uses, process-wide.
+    #
+    #: () -> Array[extension]
+    def self.extensions = @extensions
+
+    #: (Array[extension] extensions) -> void
+    def self.extensions=(extensions)
+      Extensions.resolve(extensions)
+      @extensions = extensions.dup.freeze
+    end
+
+    # Options for Ciborium::Encoder that reproduce the cbor gem's encoding.
+    #
+    #: () -> Hash[Symbol, untyped]
+    def self.encode_options
+      {extensions:, fallback: FALLBACK}
+    end
+
+    # Options for Ciborium::Decoder that reproduce the cbor gem's decoding.
+    #
+    #: () -> Hash[Symbol, untyped]
+    def self.decode_options
+      {extensions:, duplicate_keys: :last_wins}
+    end
+
+    # Encodes object, or writes it to io and returns nil when io is given.
+    #
+    #: (untyped object, ?untyped io) -> String?
+    def self.encode(object, io = nil)
+      bytes = Ciborium.encode(object, **encode_options)
+      return bytes unless io
+
+      io.write(bytes)
+      nil
+    end
+
+    # Decodes a single item from a String, or from all that an IO holds.
+    #
+    # options is {symbolize_keys: true}, or :keys_as_symbols.
+    #
+    #: (untyped source, ?(Hash[Symbol, untyped] | Symbol)? options) -> untyped
+    def self.decode(source, options = nil)
+      symbolize_keys = case options
+      when nil
+        false
+      when :keys_as_symbols
+        true
+      when Hash
+        !!options[:symbolize_keys]
+      else
+        raise ArgumentError, "expected a Hash for options, got #{options.inspect}"
+      end
+      bytes = source.respond_to?(:read) ? source.read : source
+      translate_errors { Ciborium.decode(bytes, **decode_options, symbolize_keys:) }
+    end
+
+    class << self
+      alias_method :pack, :encode
+      alias_method :dump, :encode
+      alias_method :unpack, :decode
+      alias_method :load, :decode
+    end
+
+    # Encodes an object Ciborium cannot represent through its own to_cbor(packer), as the cbor
+    # gem does.
+    FALLBACK = ->(object) do
+      unless object.respond_to?(:to_cbor) && object.method(:to_cbor).owner != CoreExt
+        raise EncodeError, "cannot encode an instance of #{object.class}"
+      end
+
+      packer = Packer.new
+      object.to_cbor(packer)
+      Encoded.new(packer.to_s)
+    end #: ^(untyped) -> untyped
+
+    # to_cbor for the classes the cbor gem extends. Installed by ciborium/replace.
+    module CoreExt
+      #: (?untyped packer_or_io) -> untyped
+      def to_cbor(packer_or_io = nil)
+        return packer_or_io.write(self) if packer_or_io.is_a?(Packer)
+
+        Compat.encode(self, packer_or_io)
+      end
+    end
+  end
+end

data/lib/ciborium/decode_options.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  DEFAULT_MAX_DEPTH = 128 #: Integer
+  MAX_DEPTH_LIMIT = 10_000 #: Integer
+
+  # Encoding rules a profile enforces beyond well-formedness. :ctap2 is the CTAP2 canonical CBOR
+  # encoding form that WebAuthn requires: no tags, no indefinite lengths, arguments in their
+  # shortest form, and map keys ordered without duplicates.
+  PROFILES = [:ctap2].freeze #: Array[Symbol]
+
+  # Decoding options, validated and packed into the arguments the native decoder takes.
+  DecodeOptions = Data.define(
+    :max_depth, #: Integer
+    :flags, #: Integer
+    :handlers, #: Hash[Integer, ^(Integer, untyped) -> untyped]?
+  )
+
+  class DecodeOptions
+    # extensions lists the allowlisted extensions (see Extensions); every other tag decodes to
+    # Tagged. profile rejects input that breaks one of PROFILES.
+    #
+    #: (?extensions: Array[extension], ?symbolize_keys: bool, ?max_depth: Integer, ?duplicate_keys: Symbol, ?profile: Symbol?) -> DecodeOptions
+    def self.build(extensions: [], symbolize_keys: false, max_depth: DEFAULT_MAX_DEPTH, duplicate_keys: :error,
+      profile: nil)
+      unless max_depth.is_a?(Integer) && max_depth.between?(1, MAX_DEPTH_LIMIT)
+        raise ArgumentError, "max_depth must be an Integer in 1..#{MAX_DEPTH_LIMIT}, got #{max_depth.inspect}"
+      end
+
+      flags = 0
+      flags |= Native::FLAG_SYMBOLIZE_KEYS if symbolize_keys
+      case duplicate_keys
+      when :error
+        # rejected by default
+      when :last_wins
+        flags |= Native::FLAG_LAST_WINS
+      else
+        raise ArgumentError, "duplicate_keys must be :error or :last_wins, got #{duplicate_keys.inspect}"
+      end
+      flags |= Native::FLAG_CTAP2 if DecodeOptions.check_profile(profile, extensions)
+      new(max_depth:, flags:, handlers: Extensions.tag_handlers(Extensions.resolve(extensions)))
+    end
+
+    # Returns whether profile is :ctap2.
+    #
+    #: (Symbol? profile, untyped extensions) -> bool
+    def self.check_profile(profile, extensions)
+      case profile
+      when nil
+        return false
+      when *PROFILES
+        raise ArgumentError, "the #{profile} profile allows no tags, so takes no extensions" unless extensions.empty?
+      else
+        raise ArgumentError, "profile must be one of #{PROFILES.inspect}, got #{profile.inspect}"
+      end
+
+      true
+    end
+  end
+end

data/lib/ciborium/decoder.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  # Decodes data items from input that arrives in parts. Nothing is consumed until a whole item
+  # has arrived, so reads that raise IncompleteError can be retried after feeding more.
+  class Decoder
+    include Enumerable #[untyped]
+
+    # Consumed bytes are dropped from the buffer once they exceed this size.
+    COMPACT_THRESHOLD = 4096 #: Integer
+
+    # @rbs @options: DecodeOptions
+    # @rbs @buffer: String
+    # @rbs @pos: Integer
+    # @rbs @scan_state: Native::ScanState
+
+    # Options are those of DecodeOptions.build.
+    #
+    #: (**untyped options) -> void
+    def initialize(**options)
+      @options = DecodeOptions.build(**options)
+      @buffer = "".b
+      @pos = 0
+      @scan_state = Native::ScanState.new
+    end
+
+    #: (String bytes) -> self
+    def feed(bytes)
+      compact
+      @buffer << bytes.b
+      self
+    end
+
+    # Decodes the next item. Raises IncompleteError when it has not fully arrived.
+    #
+    #: () -> untyped
+    def read
+      item_end
+      value, pos = Native.decode(@buffer, @pos, @options.max_depth, @options.flags, @options.handlers)
+      advance(pos)
+      value
+    end
+
+    # Yields each item that has fully arrived, leaving a partial one buffered.
+    #
+    #: () { (untyped) -> void } -> self
+    #: () -> Enumerator[untyped, self]
+    def each
+      return enum_for(:each) unless block_given?
+
+      yield read while buffered_bytes > 0 && Native.scan(@buffer, @pos, @options.max_depth, @scan_state)
+      self
+    end
+
+    # Skips the next item without decoding it.
+    #
+    #: () -> self
+    def skip
+      advance(item_end)
+      self
+    end
+
+    # Reads the head of a definite-length array and returns its length, leaving the elements to
+    # be read one by one.
+    #
+    #: () -> Integer
+    def read_array_header
+      read_container_head(4, "array")
+    end
+
+    # Reads the head of a definite-length map and returns its number of pairs.
+    #
+    #: () -> Integer
+    def read_map_header
+      read_container_head(5, "map")
+    end
+
+    # Whether the next item is null. Consumes nothing.
+    #
+    #: () -> bool
+    def next_nil?
+      byte = @buffer.getbyte(@pos)
+      raise IncompleteError, "unexpected end of input" unless byte
+
+      byte == 0xf6
+    end
+
+    #: () -> Integer
+    def buffered_bytes
+      @buffer.bytesize - @pos
+    end
+
+    # Drops all buffered input.
+    #
+    #: () -> self
+    def reset
+      @buffer = "".b
+      advance(0)
+      self
+    end
+
+    #: () -> Integer
+    private def item_end
+      Native.scan(@buffer, @pos, @options.max_depth, @scan_state) or
+        raise IncompleteError, "unexpected end of input"
+    end
+
+    # Moves to the next item, whose scan starts afresh.
+    #
+    #: (Integer pos) -> void
+    private def advance(pos)
+      @pos = pos
+      @scan_state.clear
+    end
+
+    #: (Integer major, String name) -> Integer
+    private def read_container_head(major, name)
+      head = Native.read_head(@buffer, @pos)
+      raise IncompleteError, "unexpected end of input" unless head
+
+      actual, length, pos = head
+      unless actual == major && length
+        raise UnexpectedTypeError, "expected a definite-length #{name}, got major type #{actual}"
+      end
+
+      advance(pos)
+      length
+    end
+
+    # The scan state is relative to @pos, so it stays valid.
+    #
+    #: () -> void
+    private def compact
+      return if @pos < COMPACT_THRESHOLD
+
+      @buffer = @buffer.byteslice(@pos..) || "".b
+      @pos = 0
+    end
+  end
+end

data/lib/ciborium/encode_options.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  # Encoding options, validated into the arguments the native encoder takes.
+  EncodeOptions = Data.define(
+    :max_depth, #: Integer
+    :flags, #: Integer
+    :fallback, #: Proc?
+    :class_handlers, #: Array[[Module, ^(untyped) -> untyped]]?
+  )
+
+  class EncodeOptions
+    # extensions lists the allowlisted extensions (see Extensions). fallback is called with each
+    # object neither the encoder nor an extension can represent, and returns an object to encode
+    # in its place. profile makes the output follow one of PROFILES, sorting map keys.
+    #
+    #: (?extensions: Array[extension], ?max_depth: Integer, ?fallback: (^(untyped) -> untyped)?, ?profile: Symbol?) -> EncodeOptions
+    def self.build(extensions: [], max_depth: DEFAULT_MAX_DEPTH, fallback: nil, profile: nil)
+      unless max_depth.is_a?(Integer) && max_depth.between?(1, MAX_DEPTH_LIMIT)
+        raise ArgumentError, "max_depth must be an Integer in 1..#{MAX_DEPTH_LIMIT}, got #{max_depth.inspect}"
+      end
+
+      new(
+        max_depth:,
+        flags: DecodeOptions.check_profile(profile, extensions) ? Native::FLAG_CTAP2 : 0,
+        fallback: fallback && wrap_fallback(fallback),
+        class_handlers: Extensions.class_handlers(Extensions.resolve(extensions)),
+      )
+    end
+
+    #: (^(untyped) -> untyped fallback) -> Proc
+    private_class_method def self.wrap_fallback(fallback)
+      ->(object) do
+        fallback.call(object)
+      rescue StandardError
+        raise EncodeError, "fallback failed for an instance of #{object.class}"
+      end
+    end
+  end
+end

data/lib/ciborium/encoded.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  # A data item that is already encoded, written out as-is by the encoder. The encoder checks
+  # that bytes hold exactly one well-formed item.
+  Encoded = Data.define(
+    :bytes, #: String
+  )
+end

data/lib/ciborium/encoder.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  # Writes data items one after another into a buffer, for output built in parts.
+  class Encoder
+    # @rbs @options: EncodeOptions
+    # @rbs @buffer: String
+
+    # Options are those of EncodeOptions.build.
+    #
+    #: (**untyped options) -> void
+    def initialize(**options)
+      @options = EncodeOptions.build(**options)
+      @buffer = "".b
+    end
+
+    #: (untyped object) -> self
+    def write(object)
+      @buffer << Native.encode(object, @options.max_depth, @options.flags, @options.fallback, @options.class_handlers)
+      self
+    end
+
+    # Writes the head of an array whose length items the caller writes next.
+    #
+    #: (Integer length) -> self
+    def write_array_header(length)
+      write_head(4, length)
+    end
+
+    # Writes the head of a map whose length key-value pairs the caller writes next.
+    #
+    #: (Integer length) -> self
+    def write_map_header(length)
+      write_head(5, length)
+    end
+
+    # Writes a tag head; the caller writes the tag content next.
+    #
+    #: (Integer tag) -> self
+    def write_tag(tag)
+      raise EncodeError, "tags are not allowed by the ctap2 profile" if @options.flags & Native::FLAG_CTAP2 != 0
+
+      write_head(6, tag)
+    end
+
+    # A copy of everything written so far.
+    #
+    #: () -> String
+    def bytes
+      @buffer.dup
+    end
+
+    #: () -> Integer
+    def size
+      @buffer.bytesize
+    end
+
+    #: () -> bool
+    def empty?
+      @buffer.empty?
+    end
+
+    #: () -> self
+    def clear
+      @buffer.clear
+      self
+    end
+
+    #: (Integer major, Integer argument) -> self
+    private def write_head(major, argument)
+      unless argument.is_a?(Integer) && argument.between?(0, Tagged::MAX_TAG)
+        raise ArgumentError, "argument must be an Integer in 0..2**64-1, got #{argument.inspect}"
+      end
+
+      @buffer << Native.encode_head(major, argument)
+      self
+    end
+  end
+end

data/lib/ciborium/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  class Error < StandardError; end
+
+  class DecodeError < Error; end
+
+  # The input is not well-formed CBOR, or breaks a rule the decoder enforces.
+  class MalformedError < DecodeError; end
+
+  # The input ends in the middle of a data item.
+  class IncompleteError < DecodeError; end
+
+  # Containers and tags are nested deeper than max_depth.
+  class DepthError < DecodeError; end
+
+  # An allowlisted extension failed to decode a tag's content. The cause holds the original error.
+  class ExtensionError < DecodeError; end
+
+  # A Decoder head reader found an item of another type.
+  class UnexpectedTypeError < DecodeError; end
+
+  class EncodeError < Error; end
+end

data/lib/ciborium/extensions/bignum.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  module Extensions
+    # Tags 2 and 3 (RFC 8949 section 3.4.3): integers outside -2**64..2**64-1 as byte strings.
+    class BigInteger
+      #: () -> Array[Integer]
+      def tags = [2, 3]
+
+      #: () -> Array[Module]
+      def classes = [Integer]
+
+      #: (Integer tag, untyped value) -> Integer
+      def decode(tag, value)
+        unless value.is_a?(String) && value.encoding == Encoding::BINARY
+          raise ArgumentError, "tag #{tag} content must be a byte string"
+        end
+
+        # unpack1 is typed as any directive's result; "H*" always yields a String.
+        hex = value.unpack1("H*") #: String
+        n = hex.empty? ? 0 : hex.to_i(16)
+        tag == 2 ? n : -1 - n
+      end
+
+      #: (Integer object) -> Tagged
+      def encode(object)
+        tag, n = object.negative? ? [3, -1 - object] : [2, object]
+        hex = n.to_s(16)
+        hex = "0#{hex}" if hex.size.odd?
+        Tagged.new(tag, [hex].pack("H*"))
+      end
+    end
+  end
+end

data/lib/ciborium/extensions/regexp.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+module Ciborium
+  module Extensions
+    # Tag 35 as Regexp. Compiling a pattern from untrusted input risks ReDoS, so pass a timeout
+    # unless Regexp.timeout is set.
+    class Regexp
+      FLAGS = ::Regexp::IGNORECASE | ::Regexp::EXTENDED | ::Regexp::MULTILINE #: Integer
+
+      # @rbs @timeout: Float?
+
+      #: (?timeout: Float?) -> void
+      def initialize(timeout: nil)
+        @timeout = timeout
+      end
+
+      #: () -> Array[Integer]
+      def tags = [35]
+
+      #: () -> Array[Module]
+      def classes = [::Regexp]
+
+      #: (Integer tag, untyped value) -> ::Regexp
+      def decode(tag, value)
+        raise ArgumentError, "tag #{tag} content must be text" unless value.is_a?(String)
+
+        ::Regexp.new(value, timeout: @timeout)
+      end
+
+      # Tag 35 has no place for flags, so a Regexp with any is refused rather than changed.
+      #
+      #: (::Regexp object) -> Tagged
+      def encode(object)
+        raise ArgumentError, "cannot encode #{object.inspect}: tag 35 carries no flags" if object.options & FLAGS != 0
+
+        Tagged.new(35, object.source)
+      end
+    end
+  end
+end

data/lib/ciborium/extensions/time.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+require "time"
+
+module Ciborium
+  module Extensions
+    # Tag 0 (RFC 3339 text) and tag 1 (seconds since the epoch) as Time.
+    class Time
+      #: () -> Array[Integer]
+      def tags = [0, 1]
+
+      #: () -> Array[Module]
+      def classes = [::Time]
+
+      #: (Integer tag, untyped value) -> ::Time
+      def decode(tag, value)
+        if tag == 0
+          raise ArgumentError, "tag 0 content must be text" unless value.is_a?(String)
+
+          return ::Time.iso8601(value)
+        end
+
+        unless value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)
+          raise ArgumentError, "tag 1 content must be an Integer or a finite Float"
+        end
+
+        ::Time.at(value)
+      end
+
+      # Whole seconds are written as an Integer, anything finer as a Float.
+      #
+      #: (::Time object) -> Tagged
+      def encode(object)
+        Tagged.new(1, object.subsec.zero? ? object.to_i : object.to_f)
+      end
+    end
+  end
+end