kransekake 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0d88389afbc584e049d6d6e625861741bd28167c371ee950f506754c03517613
+  data.tar.gz: 856e4b4e1ec93f9a93a1bfb79ad53a2d8f7b3166595d0cf5751957a324adb8ac
+SHA512:
+  metadata.gz: 13d63111914bcafc4de3f523a967c2ccc4143bd9f7ed03c101712d72f457b5fc82e74fae0a4b79d713f36d73c4d7159d6a00e200aa62cf4f6ea1ad8b5dfa8330
+  data.tar.gz: 3de3b29c89357829df4d148681b39a1a7930fe4a2a515ed7f9ff351a61f44b9d02e17b403a610ceb050db08487b51784209f20b2e606480c0b98de012980a719

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Shannon Skipper
+
+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,195 @@
+# Kransekake
+
+A pure Ruby [macaroons](https://research.google/pubs/macaroons-cookies-with-contextual-caveats-for-decentralized-authorization-in-the-cloud/) implementation. Interoperable with [go-macaroon](https://github.com/go-macaroon/macaroon) v2.
+
+Named after the Norwegian ring cake, which is a type of macaroon.
+
+Macaroons are bearer tokens that support attenuation (anyone can add restrictions, no one can remove them) and third-party delegation, making them well-suited for decentralized authorization.
+
+## Installation
+
+```bash
+gem install kransekake
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "kransekake"
+```
+
+For third-party caveats, also add [rbnacl](https://github.com/RubyCrypto/rbnacl) and install [libsodium](https://doc.libsodium.org/):
+
+```ruby
+gem "rbnacl", "~> 7.0"
+```
+
+First-party-only usage works without either.
+
+## How it works
+
+Macaroons use HMAC-SHA256 chaining. The root signature is derived from a secret key and each caveat extends the chain — caveats can be added but never removed, and tampering breaks the signature.
+
+Instances are immutable `Data` objects. `add_caveat` returns a new macaroon, leaving the original unchanged.
+
+```ruby
+base = Kransekake.new(key: "secret", identifier: "we used our secret key")
+restricted = base.add_caveat("account = 3735928559")
+
+base.caveats.empty?       # => true
+restricted.caveats.size   # => 1
+```
+
+## Usage
+
+### Minting and attenuating
+
+Mint a macaroon with a secret key. Anyone can add caveats but never remove them.
+
+```ruby
+require "kransekake"
+
+key = "this is our super secret key; only we should know it"
+
+base = Kransekake.new(key:, identifier: "we used our secret key", location: "http://mybank/")
+
+macaroon = base
+  .add_caveat("account = 3735928559")
+  .add_caveat("action = deposit")
+  .add_caveat("time < 2035-01-01T00:00")
+```
+
+### Verifying
+
+Every caveat must be satisfied. Pass a string for exact match or a block for a general predicate.
+
+```ruby
+verifier = Kransekake::Verifier.new
+verifier
+  .satisfy("account = 3735928559")
+  .satisfy("action = deposit")
+  .satisfy { |caveat| caveat.start_with?("time < ") }
+
+verifier.verify(macaroon:, key:) # => true
+```
+
+A wrong key, unsatisfied caveat, missing discharge or tampered signature raises a `Kransekake::VerificationError` subclass.
+
+### Serialization
+
+Binary (v2 format), base64 and JSON.
+
+```ruby
+binary = macaroon.serialize
+Kransekake.deserialize(binary)
+
+base64 = macaroon.serialize(base64: true)
+Kransekake.deserialize(base64, base64: true)
+
+json = macaroon.to_json
+Kransekake.from_json(json)
+```
+
+### Third-party caveats
+
+Delegate verification to an external service by adding a caveat only the third party can discharge. Third-party caveats use NaCl secretbox (XSalsa20-Poly1305) to encrypt caveat keys. Requires `rbnacl` and libsodium.
+
+```ruby
+root_key   = "this is our super secret key; only we should know it"
+caveat_key = "this is a different super-secret key; never use the same secret twice"
+
+# The authorizing service adds a third-party caveat
+base = Kransekake.new(key: root_key, identifier: "we used our secret key", location: "http://mybank/")
+
+macaroon = base
+  .add_caveat("account = 3735928559")
+  .add_third_party_caveat(key: caveat_key, identifier: "auth-session-id", location: "http://auth.mybank/")
+
+# The third-party service mints a discharge macaroon
+discharge = Kransekake.new(key: caveat_key, identifier: "auth-session-id", location: "http://auth.mybank/")
+  .add_caveat("email = alice@example.org")
+
+# Bind the discharge to the authorizing macaroon before sending
+bound = macaroon.bind(discharge)
+
+# Verify with both the macaroon and its discharge
+verifier = Kransekake::Verifier.new
+verifier.satisfy("account = 3735928559")
+verifier.satisfy("email = alice@example.org")
+verifier.verify(macaroon:, key: root_key, discharges: [bound]) # => true
+```
+
+### Bundles
+
+Package a macaroon with its bound discharges for transport. Supports binary, base64 and JSON.
+
+```ruby
+bundle = macaroon.bundle(discharges: [bound])
+restored = Kransekake::Bundle.deserialize(bundle.serialize)
+
+verifier.verify(macaroon: restored.macaroon, key: root_key, discharges: restored.discharges)
+```
+
+### Signature-only verification
+
+Verify the HMAC chain without checking caveats. Returns first-party conditions.
+
+```ruby
+macaroon = Kransekake.new(key: "secret", identifier: "we used our secret key")
+  .add_caveat("account = 3735928559")
+
+verifier = Kransekake::Verifier.new
+conditions = verifier.verify_signature(macaroon:, key: "secret")
+# => ["account = 3735928559"]
+```
+
+### Trace
+
+Step-by-step trace for debugging the HMAC chain.
+
+```ruby
+macaroon = Kransekake.new(key: "secret", identifier: "we used our secret key")
+  .add_caveat("account = 3735928559")
+
+verifier = Kransekake::Verifier.new
+trace = verifier.trace(macaroon:, key: "secret")
+
+trace.ok?           # => true
+trace.map(&:type)   # => [:derive_key, :hmac, :hmac, :verify_ok]
+```
+
+Each `Kransekake::Trace::Op` has `type`, `input` and `output` attributes.
+
+### Pattern matching
+
+`Data` class, so deconstruction works:
+
+```ruby
+macaroon = Kransekake.new(key: "secret", identifier: "user:alice@example.org")
+  .add_caveat("account = 3735928559")
+
+case macaroon
+in identifier: /^user:/, caveats: {list: [Kransekake::Caveat => caveat]}
+  puts caveat.identifier # => "account = 3735928559"
+end
+```
+
+## Choosing secrets
+
+The examples above use human-readable keys for clarity. Random bytes are recommended in practice:
+
+```ruby
+key = SecureRandom.random_bytes(32)
+```
+
+## Interoperability
+
+Interoperable with [go-macaroon](https://github.com/go-macaroon/macaroon) v2. Binary and JSON serialization, first-party verification, third-party caveat encryption (NaCl secretbox) and discharge binding all work bidirectionally. The test suite includes golden vectors from `gopkg.in/macaroon.v2`.
+
+## Requirements
+
+- Ruby 4.0+
+- [rbnacl](https://github.com/RubyCrypto/rbnacl) (~> 7.0) and [libsodium](https://doc.libsodium.org/) for third-party caveats (optional)
+  - macOS: `brew install libsodium`
+  - Debian: `apt install libsodium-dev`
+  - Arch: `pacman -S libsodium`

data/Rakefile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+require "standard/rake"
+
+task default: %i[test standard]
+
+Minitest::TestTask.create

data/lib/kransekake/bundle.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Kransekake
+  Bundle = Data.define(:macaroon, :discharges) do
+    class << self
+      def deserialize(data, base64: false)
+        macaroons = Serializer.deserialize_all(base64 ? data.unpack1("m0") : data)
+        new(macaroon: macaroons.first, discharges: macaroons.drop(1))
+      end
+
+      def from_json(json)
+        macaroons = JSON.parse(json).map { |hash| Kransekake.from_json_hash(hash) }
+        new(macaroon: macaroons.first, discharges: macaroons.drop(1))
+      end
+    end
+
+    def initialize(macaroon:, discharges: []) = super(macaroon:, discharges: discharges.freeze)
+
+    def serialize(base64: false)
+      buf = macaroon.serialize
+      discharges.each { |d| buf << d.serialize }
+      base64 ? [buf].pack("m0") : buf
+    end
+
+    def to_json(*) = [macaroon, *discharges].map(&:to_json_hash).to_json(*)
+  end
+end

data/lib/kransekake/caveat.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+class Kransekake
+  Caveat = Data.define(:identifier, :vid, :location) do
+    include HexDisplay
+
+    def initialize(identifier:, vid: nil, location: nil) = super
+
+    def first_party? = vid.nil?
+    def third_party? = !first_party?
+
+    def to_json_hash
+      hash = {"i" => identifier}
+      hash["v64"] = [vid].pack("m0") if vid
+      hash["l"] = location if location
+      hash
+    end
+
+    def inspect
+      fields = ["identifier=#{identifier.inspect}"]
+      fields << "vid=#{truncate_hex(vid)}" if vid
+      fields << "location=#{location.inspect}" if location
+      "#<data #{self.class} #{fields.join(", ")}>"
+    end
+
+    def pretty_print(pp)
+      pp.group(1, "#<data #{self.class}", ">") do
+        pp.breakable
+        pp.text "identifier=#{identifier.inspect}"
+        if vid
+          pp.text ","
+          pp.breakable
+          pp.text "vid=#{vid.unpack1("H*")}"
+        end
+        if location
+          pp.text ","
+          pp.breakable
+          pp.text "location=#{location.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/kransekake/caveats.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Kransekake
+  Caveats = Data.define(:list) do
+    include Enumerable
+
+    def initialize(list: []) = super(list: list.freeze)
+
+    def add(caveat) = with(list: [*list, caveat])
+    alias_method :<<, :add
+
+    def each(&) = list.each(&)
+    def size = list.size
+    def empty? = list.empty?
+    def [](index) = list[index]
+
+    def first_party = list.filter(&:first_party?)
+    def third_party = list.filter(&:third_party?)
+
+    def inspect = "#<data Kransekake::Caveats [#{list.map(&:inspect).join(", ")}]>"
+
+    def pretty_print(pp)
+      pp.group(2, "#<data Kransekake::Caveats [", "]>") do
+        pp.breakable ""
+        pp.seplist(list) { |caveat| pp.pp caveat }
+      end
+    end
+  end
+end

data/lib/kransekake/crypto.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Kransekake
+  module Crypto
+    class DecryptionError < StandardError
+      def initialize(message = "decryption failed") = super
+    end
+
+    NONCE_SIZE = 24
+    ZERO_KEY = 0.chr * 32
+
+    module_function
+
+    def hmac(key, data) = OpenSSL::HMAC.digest("SHA256", key, data)
+    def hash2(key, d1, d2) = hmac(key, hmac(key, d1) + hmac(key, d2))
+    def derive_key(key) = hmac("macaroons-key-generator", key)
+
+    def encrypt(key, plaintext)
+      require_rbnacl
+      box = RbNaCl::SecretBox.new(key.b)
+      nonce = RbNaCl::Random.random_bytes(NONCE_SIZE)
+      nonce + box.encrypt(nonce, plaintext.b)
+    end
+
+    def decrypt(key, data)
+      require_rbnacl
+      data = data.b
+      box = RbNaCl::SecretBox.new(key.b)
+      box.decrypt(data.byteslice(0, NONCE_SIZE), data.byteslice(NONCE_SIZE..))
+    rescue ::RbNaCl::CryptoError, ::RbNaCl::LengthError => e
+      raise DecryptionError, e.message
+    end
+
+    def require_rbnacl
+      require "rbnacl"
+    rescue LoadError
+      raise LoadError, <<~MESSAGE.chomp
+        Third-party caveats require the rbnacl gem and libsodium.
+
+        Add to your Gemfile:
+          gem "rbnacl", "~> 7.0"
+
+        Install libsodium:
+          macOS:  brew install libsodium
+          Debian: apt install libsodium-dev
+          Arch:   pacman -S libsodium
+      MESSAGE
+    end
+  end
+end

data/lib/kransekake/hex_display.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class Kransekake
+  module HexDisplay
+    private
+
+    def truncate_hex(binary, max: 16)
+      hex = binary.unpack1("H*")
+      (hex.size > max) ? "#{hex[0, max]}..." : hex
+    end
+  end
+end

data/lib/kransekake/serializer/reader.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+class Kransekake
+  module Serializer
+    class Reader
+      attr_reader :pos
+
+      def initialize(data)
+        @data = data.b
+        @pos = 0
+
+        raise ArgumentError, "empty macaroon data" if @data.empty?
+
+        version = read_byte
+        raise ParseError, "unsupported macaroon version: #{version} (expected #{VERSION})" unless version == VERSION
+      end
+
+      def section
+        location = nil
+        field_type, field_data = field
+
+        if field_type == LOCATION
+          location = field_data.force_encoding(Encoding::UTF_8)
+          field_type, field_data = field
+        end
+
+        raise ParseError, "expected field type `#{IDENTIFIER}` (identifier), got `#{field_type}`" unless field_type == IDENTIFIER
+
+        [location, field_data.force_encoding(Encoding::UTF_8)]
+      end
+
+      def caveat
+        location, identifier = section
+
+        vid = nil
+        field_type, field_data = field
+
+        if field_type == VID
+          vid = field_data
+          expect_eos
+        elsif field_type != EOS
+          raise ParseError, "unexpected field type `#{field_type}` in caveat"
+        end
+
+        Caveat.new(identifier:, vid:, location:)
+      end
+
+      def signature
+        field_type, field_data = field
+
+        raise ParseError, "expected field type `#{SIGNATURE}` (signature), got `#{field_type}`" unless field_type == SIGNATURE
+        raise ParseError, "signature must be 32 bytes, got #{field_data.bytesize}" unless field_data.bytesize == 32
+
+        field_data
+      end
+
+      def eos? = @data.getbyte(@pos) == EOS
+      def skip_eos = @pos += 1
+
+      def expect_eos
+        raise ParseError, "expected EOS" if @pos >= @data.bytesize || !eos?
+
+        skip_eos
+      end
+
+      private
+
+      def read_byte
+        raise ParseError, "unexpected end of data" if @pos >= @data.bytesize
+
+        byte = @data.getbyte(@pos)
+        @pos += 1
+        byte
+      end
+
+      def field
+        field_type = decode_varint
+        return [EOS, nil] if field_type == EOS
+
+        length = decode_varint
+        raise ParseError, "field extends past end of buffer" if @pos + length > @data.bytesize
+
+        field_data = @data.byteslice(@pos, length)
+        @pos += length
+        [field_type, field_data]
+      end
+
+      def decode_varint
+        value = 0
+        shift = 0
+
+        loop do
+          byte = read_byte
+          value |= (byte & 0x7f) << shift
+          return value if byte < 0x80
+
+          shift += 7
+          raise ParseError, "varint too large" if shift > 63
+        end
+      end
+    end
+  end
+end

data/lib/kransekake/serializer/writer.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Kransekake
+  module Serializer
+    class Writer
+      def initialize
+        @buf = String.new(VERSION.chr, encoding: Encoding::BINARY, capacity: 256)
+      end
+
+      def field(type, data) = @buf << encode_varint(type) << encode_varint(data.bytesize) << data.b
+      def eos = @buf << "\x00"
+      def to_s = @buf
+
+      private
+
+      def encode_varint(value)
+        buf = String.new(encoding: Encoding::BINARY, capacity: 10)
+        while value > 0x7f
+          buf << ((value & 0x7f) | 0x80).chr
+          value >>= 7
+        end
+        buf << value.chr
+      end
+    end
+  end
+end

data/lib/kransekake/serializer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class Kransekake
+  module Serializer
+    VERSION = 2
+
+    EOS = 0
+    LOCATION = 1
+    IDENTIFIER = 2
+    VID = 4
+    SIGNATURE = 6
+
+    class << self
+      def serialize(macaroon)
+        writer = Writer.new
+
+        writer.field(LOCATION, macaroon.location) unless macaroon.location.empty?
+        writer.field(IDENTIFIER, macaroon.identifier)
+        writer.eos
+
+        macaroon.caveats.each do |caveat|
+          writer.field(LOCATION, caveat.location) if caveat.location
+          writer.field(IDENTIFIER, caveat.identifier)
+          writer.field(VID, caveat.vid) if caveat.vid
+          writer.eos
+        end
+
+        writer.eos
+        writer.field(SIGNATURE, macaroon.signature)
+
+        writer.to_s
+      end
+
+      def deserialize(data) = read_one(Reader.new(data))
+
+      def deserialize_all(data)
+        data = data.b
+        macaroons = []
+        offset = 0
+
+        while offset < data.bytesize
+          reader = Reader.new(data.byteslice(offset..))
+          macaroons << read_one(reader)
+          offset += reader.pos
+        end
+
+        macaroons
+      end
+
+      private
+
+      def read_one(reader)
+        location, identifier = reader.section
+        reader.expect_eos
+
+        caveats = Caveats.new
+        caveats <<= reader.caveat until reader.eos?
+        reader.skip_eos
+
+        Kransekake.new(location: location || "", identifier:, caveats:, signature: reader.signature)
+      end
+    end
+  end
+end

data/lib/kransekake/trace/op.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class Kransekake
+  class Trace
+    Op = Data.define(:type, :input, :output) do
+      include HexDisplay
+
+      def inspect
+        "#<data #{self.class} type=#{type.inspect}, input=#{format_field(input)}, output=#{format_field(output)}>"
+      end
+
+      def pretty_print(pp)
+        pp.group(1, "#<data #{self.class}", ">") do
+          pp.breakable
+          pp.text "type=#{type.inspect},"
+          pp.breakable
+          pp.text "input=#{format_field(input, truncate: false)},"
+          pp.breakable
+          pp.text "output=#{format_field(output, truncate: false)}"
+        end
+      end
+
+      private
+
+      def format_field(value, truncate: true)
+        if value.encoding == Encoding::BINARY
+          truncate ? truncate_hex(value) : value.unpack1("H*")
+        else
+          value.inspect
+        end
+      end
+    end
+  end
+end

data/lib/kransekake/trace.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class Kransekake
+  Trace = Data.define(:ops) do
+    include Enumerable
+
+    def each(&) = ops.each(&)
+    def size = ops.size
+    def ok? = ops.last&.type == :verify_ok
+  end
+end

data/lib/kransekake/verifier.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+class Kransekake
+  class Verifier
+    include Crypto
+
+    def initialize
+      @exact = Set.new
+      @general = []
+    end
+
+    def satisfy(predicate = nil, &)
+      if block_given?
+        @general << proc(&)
+      else
+        @exact << predicate
+      end
+      self
+    end
+
+    def verify(macaroon:, key:, discharges: [])
+      sig = hmac(derive_key(key), macaroon.identifier)
+
+      macaroon.caveats.each do |caveat|
+        sig = if caveat.third_party?
+          verify_third_party(caveat:, sig:, authorizing_signature: macaroon.signature, discharges:)
+        else
+          satisfy_caveat(predicate: caveat.identifier, sig:)
+        end
+      end
+
+      compare_signatures!(expected: sig, actual: macaroon.signature)
+      true
+    end
+
+    def verify_signature(macaroon:, key:, discharges: [])
+      conditions = []
+      sig = hmac(derive_key(key), macaroon.identifier)
+
+      macaroon.caveats.each do |caveat|
+        if caveat.third_party?
+          sig = verify_third_party_signature(caveat:, sig:, authorizing_signature: macaroon.signature,
+            discharges:, conditions:)
+        else
+          conditions << caveat.identifier
+          sig = hmac(sig, caveat.identifier)
+        end
+      end
+
+      compare_signatures!(expected: sig, actual: macaroon.signature)
+      conditions
+    end
+
+    def trace(macaroon:, key:, discharges: [])
+      ops = []
+      root_key = derive_key(key)
+      ops << Trace::Op.new(type: :derive_key, input: key, output: root_key)
+
+      sig = hmac(root_key, macaroon.identifier)
+      ops << Trace::Op.new(type: :hmac, input: macaroon.identifier, output: sig)
+
+      macaroon.caveats.each do |caveat|
+        if caveat.third_party?
+          caveat_key = decrypt(sig, caveat.vid)
+          ops << Trace::Op.new(type: :decrypt, input: caveat.identifier, output: caveat_key)
+          sig = hash2(sig, caveat.vid, caveat.identifier)
+        else
+          sig = hmac(sig, caveat.identifier)
+        end
+        ops << Trace::Op.new(type: :hmac, input: caveat.identifier, output: sig)
+      end
+
+      matched = OpenSSL.fixed_length_secure_compare(sig, macaroon.signature)
+      ops << Trace::Op.new(type: matched ? :verify_ok : :verify_fail, input: sig, output: macaroon.signature)
+
+      Trace.new(ops:)
+    end
+
+    private
+
+    def compare_signatures!(expected:, actual:)
+      raise SignatureMismatchError unless OpenSSL.fixed_length_secure_compare(expected, actual)
+    end
+
+    def satisfied?(predicate) = @exact.include?(predicate) || @general.any? { it.call(predicate) }
+
+    def satisfy_caveat(predicate:, sig:)
+      raise UnsatisfiedCaveatError.new(predicate) unless satisfied?(predicate)
+
+      hmac(sig, predicate)
+    end
+
+    def verify_third_party(caveat:, sig:, authorizing_signature:, discharges:)
+      discharge = discharges.find { it.identifier == caveat.identifier }
+      raise MissingDischargeError.new(caveat.identifier) unless discharge
+
+      caveat_key = decrypt(sig, caveat.vid)
+      verify_discharge(discharge:, key: caveat_key, authorizing_signature:, discharges:)
+
+      hash2(sig, caveat.vid, caveat.identifier)
+    end
+
+    def verify_discharge(discharge:, key:, authorizing_signature:, discharges:)
+      sig = hmac(key, discharge.identifier)
+
+      discharge.caveats.each do |caveat|
+        sig = if caveat.third_party?
+          verify_third_party(caveat:, sig:, authorizing_signature:, discharges:)
+        else
+          satisfy_caveat(predicate: caveat.identifier, sig:)
+        end
+      end
+
+      compare_signatures!(expected: hash2(ZERO_KEY, authorizing_signature, sig), actual: discharge.signature)
+    end
+
+    def verify_third_party_signature(caveat:, sig:, authorizing_signature:, discharges:, conditions:)
+      discharge = discharges.find { it.identifier == caveat.identifier }
+      raise MissingDischargeError.new(caveat.identifier) unless discharge
+
+      caveat_key = decrypt(sig, caveat.vid)
+      verify_discharge_signature(discharge:, key: caveat_key, authorizing_signature:, conditions:, discharges:)
+
+      hash2(sig, caveat.vid, caveat.identifier)
+    end
+
+    def verify_discharge_signature(discharge:, key:, authorizing_signature:, conditions:, discharges:)
+      sig = hmac(key, discharge.identifier)
+
+      discharge.caveats.each do |caveat|
+        if caveat.third_party?
+          sig = verify_third_party_signature(caveat:, sig:, authorizing_signature:, discharges:, conditions:)
+        else
+          conditions << caveat.identifier
+          sig = hmac(sig, caveat.identifier)
+        end
+      end
+
+      compare_signatures!(expected: hash2(ZERO_KEY, authorizing_signature, sig), actual: discharge.signature)
+    end
+  end
+end

data/lib/kransekake/version.rb

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

data/lib/kransekake.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+Kransekake = Data.define(:location, :identifier, :caveats, :signature)
+
+require_relative "kransekake/hex_display"
+require_relative "kransekake/caveat"
+require_relative "kransekake/caveats"
+require_relative "kransekake/crypto"
+require_relative "kransekake/serializer"
+require_relative "kransekake/serializer/writer"
+require_relative "kransekake/serializer/reader"
+require_relative "kransekake/bundle"
+require_relative "kransekake/trace"
+require_relative "kransekake/trace/op"
+require_relative "kransekake/verifier"
+require_relative "kransekake/version"
+
+class Kransekake
+  class ParseError < StandardError
+    def initialize(message = "failed to parse macaroon") = super
+  end
+
+  class VerificationError < StandardError
+    def initialize(message = "verification failed") = super
+  end
+
+  class MissingDischargeError < VerificationError
+    attr_reader :identifier
+
+    def initialize(identifier)
+      @identifier = identifier
+      super("missing discharge for caveat: #{identifier}")
+    end
+  end
+
+  class SignatureMismatchError < VerificationError
+    def initialize(message = "signature mismatch") = super
+  end
+
+  class UnsatisfiedCaveatError < VerificationError
+    attr_reader :caveat
+
+    def initialize(caveat)
+      @caveat = caveat
+      super("unsatisfied caveat: #{caveat}")
+    end
+  end
+
+  include Crypto
+  include HexDisplay
+
+  class << self
+    def deserialize(data, base64: false) = Serializer.deserialize(base64 ? data.unpack1("m0") : data)
+    def from_json(json) = from_json_hash(JSON.parse(json))
+
+    def from_json_hash(hash)
+      location = hash.fetch("l", "")
+      identifier = hash["i"] || decode64(hash.fetch("i64"))
+
+      caveats = Caveats.new
+      hash.fetch("c", []).each do |c|
+        cav_id = c["i"] || decode64(c.fetch("i64"))
+        v64 = c["v64"]
+        cav_vid = decode64(v64) if v64
+        cav_loc = c["l"]
+        caveats <<= Caveat.new(identifier: cav_id, vid: cav_vid, location: cav_loc)
+      end
+
+      signature = decode64(hash["s64"])
+      raise ParseError, "signature must be 32 bytes, got #{signature.bytesize}" unless signature.bytesize == 32
+
+      new(location:, identifier:, caveats:, signature:)
+    end
+
+    private
+
+    def decode64(data) = data.tr("-_", "+/").ljust((data.size + 3) & ~3, "=").unpack1("m0")
+  end
+
+  def initialize(identifier:, key: nil, location: "", caveats: Caveats.new, **)
+    if key
+      super(identifier:, location:, caveats:, signature: hmac(derive_key(key), identifier), **)
+    else
+      super(identifier:, location:, caveats:, **)
+    end
+  end
+
+  def add_caveat(predicate) = with(caveats: caveats.add(Caveat.new(identifier: predicate)), signature: hmac(signature, predicate))
+
+  def add_third_party_caveat(key:, identifier:, location:)
+    vid = encrypt(signature, derive_key(key))
+    sig = hash2(signature, vid, identifier)
+
+    with(caveats: caveats.add(Caveat.new(identifier:, vid:, location:)), signature: sig)
+  end
+
+  def bind(discharge) = discharge.with(signature: hash2(ZERO_KEY, signature, discharge.signature))
+
+  def inspect
+    fields = []
+    fields << "location=#{location.inspect}" unless location.empty?
+    fields << "identifier=#{identifier.inspect}"
+    fields << "caveats=#{caveats.inspect}" unless caveats.empty?
+    fields << "signature=#{truncate_hex(signature)}"
+    "#<data #{self.class} #{fields.join(", ")}>"
+  end
+
+  def pretty_print(pp)
+    pp.group(1, "#<data #{self.class}", ">") do
+      pp.breakable
+      pp.text "location=#{location.inspect}," unless location.empty?
+      pp.breakable unless location.empty?
+      pp.text "identifier=#{identifier.inspect},"
+      unless caveats.empty?
+        pp.breakable
+        pp.text "caveats="
+        pp.pp caveats
+        pp.text ","
+      end
+      pp.breakable
+      pp.text "signature=#{signature.unpack1("H*")}"
+    end
+  end
+
+  def version = Serializer::VERSION
+  def bundle(discharges: []) = Bundle.new(macaroon: self, discharges:)
+
+  def serialize(base64: false)
+    data = Serializer.serialize(self)
+    base64 ? [data].pack("m0") : data
+  end
+
+  def to_json(*) = to_json_hash.to_json(*)
+
+  def to_json_hash
+    hash = {}
+    hash["l"] = location unless location.empty?
+    hash["i"] = identifier
+    hash["c"] = caveats.map(&:to_json_hash) unless caveats.empty?
+    hash["s64"] = [signature].pack("m0")
+    hash
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: kransekake
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shannon Skipper
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A pure Ruby implementation of macaroons for flexible authorization credentials
+email:
+- shannonskipper@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/kransekake.rb
+- lib/kransekake/bundle.rb
+- lib/kransekake/caveat.rb
+- lib/kransekake/caveats.rb
+- lib/kransekake/crypto.rb
+- lib/kransekake/hex_display.rb
+- lib/kransekake/serializer.rb
+- lib/kransekake/serializer/reader.rb
+- lib/kransekake/serializer/writer.rb
+- lib/kransekake/trace.rb
+- lib/kransekake/trace/op.rb
+- lib/kransekake/verifier.rb
+- lib/kransekake/version.rb
+homepage: https://github.com/havenwood/kransekake
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/havenwood/kransekake
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.7
+specification_version: 4
+summary: A macaroon authorization credentials library
+test_files: []