crystal-cbor-fido

Memory-safe, zero-dependency Canonical CBOR (RFC 8949 §4.2 and CTAP2 §6) encoder and decoder for Crystal with IEEE 754 float narrowing and strict validation.

GitLab Project Metadata:

• Description: Memory-safe Canonical CBOR (RFC 8949 §4.2 and CTAP2 §6) encoder and decoder for Crystal with IEEE 754 float narrowing and strict validation.
• Topics and Tags: crystal, crystal-lang, cbor, fido2, ctap2, webauthn, rfc8949, serialization, security, gplv3

Overview

crystal-cbor-fido provides a deterministic, zero-dependency, and hardened Canonical CBOR (RFC 8949 §4.2 and FIDO2 CTAP2 §6) encoder and decoder for Crystal, purpose-built for FIDO2, WebAuthn, and COSE protocol compliance.

Key Highlights

1. Strict Canonical CBOR Compliance: Enforces minimal integer and floating-point widths, deterministic CTAP2 map key ordering (shorter byte length first, then unsigned byte-wise lexicographical order), duplicate serialized key rejection on both encode and decode, and top-level trailing-byte rejection.
2. Compile-Time CBOR::Serializable Macro: Zero-boilerplate struct and class serialization via include CBOR::Serializable, @[CBOR::Field(key: ..., ignore: ...)], and @[CBOR::Serializable::Options(strict: Bool = true)] supporting integer COSE labels (1, 3, -1, -2, -3) and UTF-8 string keys.
3. IEEE 754 Half-Precision (Float16) Narrowing: Lossless Float64 -> Float32 -> Float16 narrowing with exact subnormal precision ($1 \times 2^{-24} \approx 5.96 \times 10^{-8}$), round-to-nearest-even bit manipulation with guard and sticky bit inspection, canonical 0x7e00 NaN, and +0.0 0x0000 normalization.
4. Bounded Streaming IO & Defensive Resource Limits: Supports direct IO streaming with configurable max_depth : Int32 = 16, max_bytes : UInt64 = 1_048_576_u64 (bounded by MAX_LEN = 10_000_000_u64), and eof_check : Bool = true, verified against the RFC 8949 Appendix A test vector corpus.

Installation

Add crystal-cbor-fido to your application's shard.yml:

dependencies:
  crystal-cbor-fido:
    gitlab: renich/crystal-cbor-fido
    version: ~> 0.2.2

Then install the shard:

shards install

Usage

require "crystal-cbor-fido"

# 1. Strongly-typed FIDO2/COSE structs via CBOR::Serializable
struct CoseEc2Key
  include CBOR::Serializable

  @[CBOR::Field(key: 1_i64)]
  getter kty : Int64

  @[CBOR::Field(key: 3_i64)]
  getter alg : Int64

  @[CBOR::Field(key: -1_i64)]
  getter crv : Int64

  def initialize(@kty : Int64, @alg : Int64, @crv : Int64) : Nil
  end
end

key = CoseEc2Key.new(kty: 2_i64, alg: -7_i64, crv: 1_i64)
wire_bytes = key.to_cbor
restored = CoseEc2Key.from_cbor(wire_bytes)

# 2. Dynamic maps and bounded IO streaming
io = IO::Memory.new
Crystal::Cbor::Fido.encode({"rp_id" => "evalinux.com", "uv" => true} of CBOR::Value => CBOR::Value, io)
io.rewind
decoded_data = Crystal::Cbor::Fido.decode(io, max_bytes: 65_536_u64, eof_check: true)
puts "Decoded Data: #{decoded_data.inspect}"

Build System Targets

The repository includes a standard GNUmakefile:

Documentation

Full architectural blueprints, functional specifications, D2 diagrams, and operational playbooks are maintained under docs/:

Contributing & Code of Honor

All contributions must adhere to the Universal Code of Honor and Contributing Guidelines.

License

• Software: GNU General Public License v3.0 or later (LICENSE).
• Documentation: GNU Free Documentation License v1.3 or later (LICENSE-DOCS).

Copyleft © 2026 Rénich Bon Ćirić <renich@evalinux.com>.

Support & Donations

If you find this shard useful and wish to support its ongoing development, please consider donating: