active_sanction 1.0.0

data/lib/active_sanction/snapshot/bundle/header.rb

@@ -0,0 +1,302 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "json"
+require "time"
+require "active_sanction/error"
+require "active_sanction/snapshot"
+require "active_sanction/sources"
+require "active_sanction/version"
+
+module ActiveSanction
+  class Snapshot
+    module Bundle
+      # What a bundle says about itself, in one line, before any of its records
+      # are read.
+      #
+      #   header = ActiveSanction::Snapshot::Bundle.header(io)
+      #
+      #   header.source             # => :ofac_sdn
+      #   header.record_count       # => 19015
+      #   header.snapshot_checksum  # => "sha256:9f86d081884c7d65..."
+      #   header.generator          # => "active_sanction/1.0.0"
+      #   header.fetched_at         # => 2026-08-28 09:30:00 UTC
+      #
+      # This is Storage::Meta's job for a file somebody sent you, and the two
+      # are deliberately the same shape: small, cheap, and answerable without
+      # inflating tens of megabytes. `active_sanction import` prints one, a
+      # mirror indexes them, and a deploy decides whether it already holds this
+      # list version by comparing `snapshot_checksum` against what it stored.
+      #
+      # ### It is the thing that gets signed
+      #
+      # A signature covers these bytes and nothing else -- see Bundle::Signature.
+      # It can, because `payload_digest` is a SHA-256 over every record in the
+      # file: signing ~300 bytes here transitively covers all 19,015 of them,
+      # and a verifier settles who published a bundle before it inflates a byte
+      # of what they sent.
+      #
+      # So every field that could change what the payload *means* is in here,
+      # and a field whose value is not reproducible from the snapshot is not:
+      # there is no written-at timestamp, because two writes of one snapshot
+      # have to produce identical files.
+      #
+      # Instances are frozen on construction and compare by value.
+      class Header
+        extend T::Sig
+
+        # Canonical member order. This is the order #to_h builds and #to_line
+        # serializes, and it is part of the format: a reader in another language
+        # that emits these keys in another order produces a different file.
+        #
+        # @api private
+        MEMBERS = T.let(
+          %i[format_version gem_version generator source schema_version snapshot_checksum record_count
+             fetched_at source_version payload_encoding payload_compression payload_digest payload_bytes].freeze,
+          T::Array[Symbol]
+        )
+
+        # The one field a publisher may leave out, because plenty of lists
+        # publish no version of their own. It still serializes, as null: the
+        # key order is the format, so nothing is omitted from the line.
+        #
+        # @api private
+        OPTIONAL_MEMBERS = T.let(%i[source_version].freeze, T::Array[Symbol])
+
+        # `sha256:` and 64 hex digits, the form this library quotes every digest
+        # in -- a snapshot's checksum, a cached payload's, and both of the ones
+        # here.
+        #
+        # @api private
+        DIGEST_PATTERN = T.let(/\A#{Snapshot::ALGORITHM}:\h{64}\z/, Regexp)
+
+        # Who wrote the file, defaulted to this gem and this version. A
+        # publisher that is not this gem -- a commercial mirror, a bank's
+        # internal pipeline -- overrides it, which is the point of the field:
+        # `gem_version` says what code serialized the records, and this says
+        # whose bundle it is.
+        sig { returns(String) }
+        def self.default_generator = -"active_sanction/#{VERSION}"
+
+        # The header for a snapshot about to be written, given what the payload
+        # came to. Both payload values are measurements of bytes that already
+        # exist rather than promises about bytes to come -- see Bundle.write.
+        sig do
+          params(snapshot: Snapshot, payload_digest: String, payload_bytes: Integer,
+                 generator: T.untyped).returns(T.attached_class)
+        end
+        def self.from_snapshot(snapshot, payload_digest:, payload_bytes:, generator: nil)
+          new(format_version: FORMAT_VERSION, gem_version: VERSION, generator: generator || default_generator,
+              source: snapshot.source, schema_version: snapshot.schema_version,
+              snapshot_checksum: snapshot.checksum, record_count: snapshot.record_count,
+              fetched_at: snapshot.fetched_at, source_version: snapshot.source_version,
+              payload_digest: payload_digest, payload_bytes: payload_bytes)
+        end
+
+        # Reads one serialized header line. Everything that can be wrong with it
+        # raises -- an unknown key, a missing one, a digest that is not a
+        # digest -- because a header this code half understands is a header it
+        # cannot say the signature covers.
+        sig { params(line: T.untyped).returns(T.attached_class) }
+        def self.parse(line)
+          parsed = JSON.parse(line.to_s)
+          raise InvalidArgument, "a bundle header is a JSON object, got #{parsed.class}" unless parsed.is_a?(Hash)
+
+          from_h(parsed)
+        end
+
+        # Rebuilds from #to_h output, accepting string keys so a header
+        # survives the round-trip through JSON.
+        sig { params(hash: T.untyped).returns(T.attached_class) }
+        def self.from_h(hash)
+          attributes = hash.to_h.transform_keys(&:to_sym)
+          unknown = attributes.keys - MEMBERS
+          raise InvalidArgument, "unknown bundle header field(s): #{unknown.join(", ")}" if unknown.any?
+
+          missing = MEMBERS - attributes.keys - OPTIONAL_MEMBERS
+          raise InvalidArgument, "bundle header is missing #{missing.join(", ")}" if missing.any?
+
+          # `new(**hash)` past required keyword parameters is one of the few
+          # things Sorbet cannot check statically. #initialize validates what
+          # arrives, which is where a bad header is caught.
+          T.unsafe(self).new(**attributes)
+        end
+
+        sig { returns(Integer) }
+        attr_reader :format_version
+
+        # The active_sanction that serialized the records, which is what a
+        # `schema_version` this reader does not know is diagnosed against.
+        sig { returns(String) }
+        attr_reader :gem_version
+
+        sig { returns(String) }
+        attr_reader :generator
+
+        sig { returns(Symbol) }
+        attr_reader :source
+
+        # Snapshot::SCHEMA_VERSION the records were written under.
+        sig { returns(Integer) }
+        attr_reader :schema_version
+
+        # The checksum of the list itself: content only, and identical to what
+        # the snapshot had before it was ever written to a file. This is what a
+        # stored MatchResult cites, so a bundle can be matched to a screening
+        # decision made years earlier.
+        sig { returns(String) }
+        attr_reader :snapshot_checksum
+
+        sig { returns(Integer) }
+        attr_reader :record_count
+
+        # UTC, truncated to the second: when the publisher's file was fetched,
+        # not when this bundle was written.
+        sig { returns(Time) }
+        attr_reader :fetched_at
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :source_version
+
+        # How the records are laid out once decompressed. `ndjson` in v1, and
+        # named so that a later version can add another without a reader having
+        # to guess which it is looking at.
+        sig { returns(String) }
+        attr_reader :payload_encoding
+
+        # `deflate` in v1: a raw zlib stream, RFC 1950.
+        sig { returns(String) }
+        attr_reader :payload_compression
+
+        # SHA-256 over the *uncompressed* payload. Over the uncompressed bytes
+        # because that is the half of the file two machines can be held to:
+        # zlib builds differ in what they emit for identical input, and the
+        # records do not.
+        sig { returns(String) }
+        attr_reader :payload_digest
+
+        # The length of the uncompressed payload. Checked as a reader inflates,
+        # so a bundle that decompresses to more than it declared is refused part
+        # way through rather than absorbed.
+        sig { returns(Integer) }
+        attr_reader :payload_bytes
+
+        sig do
+          params(format_version: T.untyped, gem_version: T.untyped, generator: T.untyped, source: T.untyped,
+                 schema_version: T.untyped, snapshot_checksum: T.untyped, record_count: T.untyped,
+                 fetched_at: T.untyped, payload_digest: T.untyped, payload_bytes: T.untyped,
+                 source_version: T.untyped, payload_encoding: T.untyped, payload_compression: T.untyped).void
+        end
+        def initialize(format_version:, gem_version:, generator:, source:, schema_version:, snapshot_checksum:,
+                       record_count:, fetched_at:, payload_digest:, payload_bytes:, source_version: nil,
+                       payload_encoding: ENCODING, payload_compression: COMPRESSION)
+          @format_version = T.let(version!(:format_version, format_version), Integer)
+          @gem_version = T.let(string!(:gem_version, gem_version), String)
+          @generator = T.let(string!(:generator, generator), String)
+          @source = T.let(Sources::Definition.key!(source), Symbol)
+          @schema_version = T.let(version!(:schema_version, schema_version), Integer)
+          @snapshot_checksum = T.let(digest!(:snapshot_checksum, snapshot_checksum), String)
+          @record_count = T.let(count!(:record_count, record_count), Integer)
+          @fetched_at = T.let(time!(fetched_at), Time)
+          @source_version = T.let(string_or_nil(source_version), T.nilable(String))
+          @payload_encoding = T.let(string!(:payload_encoding, payload_encoding), String)
+          @payload_compression = T.let(string!(:payload_compression, payload_compression), String)
+          @payload_digest = T.let(digest!(:payload_digest, payload_digest), String)
+          @payload_bytes = T.let(count!(:payload_bytes, payload_bytes), Integer)
+          freeze
+        end
+
+        # The documented shape, in the documented order.
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {
+            format_version: format_version, gem_version: gem_version, generator: generator,
+            source: source.to_s, schema_version: schema_version, snapshot_checksum: snapshot_checksum,
+            record_count: record_count, fetched_at: fetched_at.iso8601, source_version: source_version,
+            payload_encoding: payload_encoding, payload_compression: payload_compression,
+            payload_digest: payload_digest, payload_bytes: payload_bytes
+          }
+        end
+
+        # The exact bytes that go into the file, and the exact bytes a
+        # signature is computed over. No trailing newline: the newline is the
+        # container's, not the header's, so a reader that strips line endings
+        # differently still verifies.
+        sig { returns(String) }
+        def to_line = JSON.generate(to_h)
+
+        sig { params(other: T.untyped).returns(T::Boolean) }
+        def ==(other)
+          return false unless other.instance_of?(self.class)
+
+          to_h == other.to_h
+        end
+        alias eql? ==
+
+        sig { returns(Integer) }
+        def hash = [self.class, to_h].hash
+
+        sig { returns(String) }
+        def inspect
+          "#<#{self.class} #{source} #{record_count} entities #{snapshot_checksum} by #{generator}>"
+        end
+
+        private
+
+        sig { params(member: Symbol, value: T.untyped).returns(Integer) }
+        def version!(member, value)
+          integer = Integer(value)
+          raise InvalidArgument, "#{member} must be positive, got #{integer}" unless integer.positive?
+
+          integer
+        end
+
+        sig { params(member: Symbol, value: T.untyped).returns(String) }
+        def string!(member, value)
+          string = value.to_s.strip
+          raise InvalidArgument, "#{member} is required" if string.empty?
+
+          -string
+        end
+
+        sig { params(member: Symbol, value: T.untyped).returns(String) }
+        def digest!(member, value)
+          string = value.to_s.strip
+          return -string if DIGEST_PATTERN.match?(string)
+
+          raise InvalidArgument, "#{member} is not a #{Snapshot::ALGORITHM} digest: #{value.inspect}"
+        end
+
+        sig { params(member: Symbol, value: T.untyped).returns(Integer) }
+        def count!(member, value)
+          integer = Integer(value)
+          raise InvalidArgument, "#{member} cannot be negative, got #{integer}" if integer.negative?
+
+          integer
+        end
+
+        # Truncated to the second, the precision #to_h serializes, so a header
+        # read back is equal to the one that was written.
+        sig { params(value: T.untyped).returns(Time) }
+        def time!(value)
+          time = case value
+                 when Time then value
+                 when String then Time.parse(value)
+                 else raise InvalidArgument, "fetched_at is not a time: #{value.inspect}"
+                 end
+          Time.at(time.to_i).utc
+        end
+
+        sig { params(value: T.untyped).returns(T.nilable(String)) }
+        def string_or_nil(value)
+          return nil if value.nil?
+
+          string = value.to_s.strip
+          string.empty? ? nil : -string
+        end
+      end
+    end
+  end
+end

data/lib/active_sanction/snapshot/bundle/payload.rb

@@ -0,0 +1,185 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "digest"
+require "zlib"
+require "active_sanction/error"
+
+module ActiveSanction
+  class Snapshot
+    module Bundle
+      # The records half of a bundle: newline-delimited JSON, deflated, with a
+      # SHA-256 over what it says before it was compressed.
+      #
+      # Two rules are worth stating outright, because between them they are why
+      # a bundle can be published once and trusted everywhere.
+      #
+      # ### The digest is over the uncompressed bytes
+      #
+      # zlib builds disagree. The same records fed to zlib 1.3 and to zlib-ng
+      # at the same level can come out as different bytes, so a digest over the
+      # compressed stream would make "the same snapshot produces the same
+      # bundle" a claim about which Linux distribution built somebody's Ruby.
+      # Over the records it is a claim about the records, which is the one worth
+      # signing.
+      #
+      # ### Reading never holds the whole list
+      #
+      # `.unpack` inflates in 64 KiB pieces and yields one record at a time, so
+      # a 25 MB EU bundle is read with a buffer of one chunk plus one line
+      # rather than with a decompressed copy beside the entities being built
+      # from it. The digest is accumulated on the way past.
+      #
+      # It also refuses to inflate more than the header declared. A file that
+      # says it holds 48 MB and keeps producing bytes at 49 MB is either damaged
+      # or built to exhaust whoever opens it, and either way there is nothing to
+      # gain by decompressing the rest of it.
+      #
+      # @api private
+      module Payload
+        extend T::Sig
+        extend T::Helpers
+
+        # Called as `Payload.pack` -- module functions on a module, which is an
+        # Object, which is where `raise` comes from.
+        requires_ancestor { Kernel }
+
+        # How much compressed input is inflated at a time. The same 64 KiB
+        # PayloadCache digests a download in, and for the same reason.
+        CHUNK_SIZE = T.let(64 * 1024, Integer)
+
+        # Named rather than Zlib::DEFAULT_COMPRESSION, which is -1 and means
+        # "whatever this build calls default". Two writers of one snapshot
+        # should not produce different files because one of them linked a
+        # different zlib, and a level in the specification is what a non-Ruby
+        # implementation has to be told anyway.
+        COMPRESSION_LEVEL = T.let(6, Integer)
+
+        module_function
+
+        # Compresses `records` -- JSON strings, one per entity, in the order
+        # they belong in -- and returns the compressed bytes, the digest of the
+        # uncompressed stream, and its length.
+        #
+        # Compressed output is buffered rather than streamed to the file,
+        # because the header that has to be written *before* it states its
+        # digest and its length, and neither is known until the last record has
+        # gone past. The snapshot is already wholly in memory by then; this adds
+        # the compressed copy of it, which for the largest list published is
+        # about 25 MB and is released as soon as it is written.
+        sig { params(records: T::Enumerable[String]).returns([String, String, Integer]) }
+        def pack(records)
+          digest = Digest::SHA256.new
+          deflate = Zlib::Deflate.new(COMPRESSION_LEVEL)
+          bytes = T.let(0, Integer)
+          compressed = String.new(encoding: Encoding::BINARY)
+          begin
+            records.each do |record|
+              line = "#{record}\n"
+              digest << line
+              bytes += line.bytesize
+              compressed << deflate.deflate(line)
+            end
+            compressed << deflate.finish
+          ensure
+            deflate.close
+          end
+          [compressed, -"#{Snapshot::ALGORITHM}:#{digest.hexdigest}", bytes]
+        end
+
+        # Inflates the rest of `io`, yielding each record as the JSON string it
+        # was written as, and returns the digest and length of what it read so
+        # a caller can hold them against what the header promised.
+        sig do
+          params(io: T.untyped, limit: Integer, block: T.proc.params(record: String).void).returns([String, Integer])
+        end
+        def unpack(io, limit:, &block)
+          digest = Digest::SHA256.new
+          bytes = T.let(0, Integer)
+          buffer = String.new(encoding: Encoding::BINARY)
+          inflate = Zlib::Inflate.new
+          fed = T.let(0, Integer)
+          begin
+            while (chunk = io.read(CHUNK_SIZE))
+              fed += chunk.bytesize
+              buffer << inflate!(inflate, chunk)
+              bytes = drain(buffer, bytes, limit, digest, &block)
+            end
+            bytes = finish(inflate, buffer, bytes, limit, digest, &block)
+            trailing!(fed, inflate.total_in)
+          ensure
+            inflate.close unless inflate.closed?
+          end
+          [-"#{Snapshot::ALGORITHM}:#{digest.hexdigest}", bytes]
+        end
+
+        # Every complete line the buffer now holds, leaving any partial one
+        # behind for the next chunk.
+        sig do
+          params(buffer: String, bytes: Integer, limit: Integer, digest: Digest::SHA256,
+                 block: T.proc.params(record: String).void).returns(Integer)
+        end
+        def drain(buffer, bytes, limit, digest, &block)
+          total = bytes
+          while (index = buffer.index("\n"))
+            line = T.must(buffer.slice!(0, index + 1))
+            digest << line
+            total += line.bytesize
+            oversized!(total, limit)
+            block.call(line.chomp.force_encoding(Encoding::UTF_8))
+          end
+          total
+        end
+
+        # What is left when the compressed stream ends: nothing, if the writer
+        # terminated its last record. A trailing partial line is a truncated
+        # file and says so.
+        sig do
+          params(inflate: Zlib::Inflate, buffer: String, bytes: Integer, limit: Integer, digest: Digest::SHA256,
+                 block: T.proc.params(record: String).void).returns(Integer)
+        end
+        def finish(inflate, buffer, bytes, limit, digest, &block)
+          buffer << inflate.finish unless inflate.finished?
+          total = drain(buffer, bytes, limit, digest, &block)
+          return total if buffer.empty?
+
+          raise Corrupt, "the last record in this bundle is unterminated, so the payload was cut short"
+        rescue Zlib::Error => e
+          raise Corrupt, "this bundle's payload ends mid-stream and cannot be decompressed (#{e.message})"
+        end
+
+        sig { params(inflate: Zlib::Inflate, chunk: String).returns(String) }
+        def inflate!(inflate, chunk)
+          inflate.inflate(chunk)
+        rescue Zlib::Error => e
+          raise Corrupt, "this bundle's payload is not readable as #{COMPRESSION} (#{e.message})"
+        end
+
+        # Bytes after the end of the compressed stream. zlib stops reading at
+        # the end of what it was given and would let them pass unmentioned,
+        # which would make a bundle somebody appended to indistinguishable from
+        # the one that was signed.
+        sig { params(fed: Integer, consumed: Integer).void }
+        def trailing!(fed, consumed)
+          return if fed <= consumed
+
+          raise Corrupt,
+                "this bundle carries #{fed - consumed} bytes after the end of its payload. Nothing was written " \
+                "there, so something else put them there"
+        end
+
+        sig { params(total: Integer, limit: Integer).void }
+        def oversized!(total, limit)
+          return if total <= limit
+
+          raise Corrupt,
+                "this bundle's payload decompresses to more than the #{limit} bytes its header declares. " \
+                "Nothing further is read: a file that lies about its own size is either damaged or built to " \
+                "exhaust whoever opens it"
+        end
+      end
+    end
+  end
+end

data/lib/active_sanction/snapshot/bundle/signature.rb

@@ -0,0 +1,201 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "sorbet-runtime"
+
+require "openssl"
+require "active_sanction/error"
+
+module ActiveSanction
+  class Snapshot
+    module Bundle
+      # The third line of a bundle: who says this is the file they published.
+      #
+      #   key = OpenSSL::PKey::EC.generate("prime256v1")
+      #   Bundle.write(snapshot, io: io, sign_with: key)
+      #   Bundle.read(io, verify_with: key)   # => Snapshot, trusted?
+      #
+      # ### Detached, and over the header only
+      #
+      # The signed bytes are the header line's, without its newline. That line
+      # carries `payload_digest`, a SHA-256 over every record in the file, so
+      # ~300 bytes of signature input stand for all 19,015 of them. Three things
+      # follow, and all three are the reason it is done this way:
+      #
+      # - **A verifier settles who published a bundle before inflating a byte
+      #   of it.** Compressed data from a party you have not yet authenticated
+      #   is exactly what you do not want to expand.
+      # - **Verification costs the same for OFAC and for the EU.** One
+      #   signature over a fixed-size line, not over 25 MB.
+      # - **A bundle without a signature is still a bundle.** The line reads
+      #   `-`, everything else about the file is unchanged, and a reader that
+      #   was given no key never looks at it. Signing is a claim about
+      #   provenance laid on top of a format that works without one.
+      #
+      # ### What it does not cover
+      #
+      # Nothing about the file that is not in the header. A bundle re-compressed
+      # at a different level still verifies, because the digest is over the
+      # uncompressed records -- which is correct: the claim is about the list,
+      # not about the packing. Tampering with the records themselves fails, but
+      # it fails as corruption (the digest) rather than as a bad signature, and
+      # Bundle raises two different errors to say which.
+      #
+      # ### Keys
+      #
+      # RSA and EC, both of which every OpenSSL this gem can run against
+      # supports. `ed25519` is reserved as an algorithm name and deliberately
+      # not implemented yet: support for it varies by OpenSSL build, and a
+      # format whose signatures verify on some machines is worse than one that
+      # signs with a key everybody has.
+      #
+      # Note that an ECDSA signature is randomized -- signing one snapshot twice
+      # with one key produces two different lines. Determinism is a property of
+      # the magic line, the header and the payload; see Bundle.
+      #
+      # @api private
+      module Signature
+        extend T::Sig
+        extend T::Helpers
+
+        # Called as `Signature.sign` -- module functions on a module, which is
+        # an Object, which is where `raise` comes from.
+        requires_ancestor { Kernel }
+
+        # What an unsigned bundle carries. A literal, rather than an empty
+        # line, so that a truncated file cannot read as an unsigned one.
+        NONE = T.let("-", String)
+
+        # The algorithm names the format defines, and the kind of OpenSSL key
+        # each one is produced by. `ed25519` is reserved and not in here: a name
+        # a v1 reader rejects is a name a v1 reader cannot get wrong.
+        ALGORITHMS = T.let({ "rsa-sha256" => OpenSSL::PKey::RSA, "ecdsa-sha256" => OpenSSL::PKey::EC }.freeze,
+                           T::Hash[String, T.untyped])
+
+        # Reserved, and refused with a message that says so rather than with
+        # "unknown algorithm", so a bundle from a newer publisher diagnoses
+        # itself.
+        RESERVED_ALGORITHMS = T.let(%w[ed25519].freeze, T::Array[String])
+
+        DIGEST = T.let("SHA256", String)
+
+        module_function
+
+        # The signature line for a header, or NONE when there is no key.
+        sig { params(header_line: String, key: T.untyped).returns(String) }
+        def sign(header_line, key)
+          return NONE if key.nil?
+
+          pkey = key!(key)
+          algorithm = algorithm_for(pkey)
+          "#{algorithm} #{[pkey.sign(OpenSSL::Digest.new(DIGEST), header_line)].pack("m0")}"
+        end
+
+        # Whether a line carries a signature at all.
+        sig { params(line: T.untyped).returns(T::Boolean) }
+        def signed?(line) = !line.nil? && line.to_s.strip != NONE && !line.to_s.strip.empty?
+
+        # True when the signature on `line` was made over `header_line` by the
+        # holder of `key`. Raises rather than answering false: a caller that
+        # asked for verification and got a boolean it forgot to check would
+        # screen against unverified data believing otherwise.
+        sig { params(line: T.untyped, header_line: String, key: T.untyped).returns(T::Boolean) }
+        def verify!(line, header_line, key)
+          raise Unsigned, unsigned_message unless signed?(line)
+
+          algorithm, encoded = split!(line)
+          pkey = key!(key)
+          expected!(algorithm, pkey)
+          verified = begin
+            pkey.verify(OpenSSL::Digest.new(DIGEST), decode!(encoded), header_line)
+          rescue OpenSSL::OpenSSLError
+            false
+          end
+          return true if verified
+
+          raise UntrustedSignature, mismatch_message(algorithm)
+        end
+
+        # An OpenSSL key from what a caller supplied: a key, or a PEM.
+        sig { params(value: T.untyped).returns(OpenSSL::PKey::PKey) }
+        def key!(value)
+          return value if value.is_a?(OpenSSL::PKey::PKey)
+
+          if value.is_a?(String)
+            begin
+              return OpenSSL::PKey.read(value)
+            rescue OpenSSL::OpenSSLError => e
+              raise InvalidArgument, "the key given is not a readable PEM (#{e.message})"
+            end
+          end
+
+          raise InvalidArgument,
+                "a bundle is signed and verified with an OpenSSL::PKey or a PEM string, got #{value.class}. " \
+                "Read a key file yourself -- OpenSSL::PKey.read(File.read(\"public.pem\"))"
+        end
+
+        # The format's name for the key's algorithm.
+        sig { params(pkey: OpenSSL::PKey::PKey).returns(String) }
+        def algorithm_for(pkey)
+          name = ALGORITHMS.find { |_, kind| pkey.is_a?(kind) }&.first
+          return name if name
+
+          raise UnsupportedError,
+                "a bundle cannot be signed with a #{pkey.class} key. The format defines " \
+                "#{ALGORITHMS.keys.join(" and ")}, and reserves #{RESERVED_ALGORITHMS.join(", ")}"
+        end
+
+        # The two fields of a signature line.
+        sig { params(line: T.untyped).returns([String, String]) }
+        def split!(line)
+          algorithm, encoded = line.to_s.strip.split(" ", 2)
+          raise Corrupt, "#{line.to_s.strip.inspect} is not a signature line" if algorithm.nil? || encoded.nil?
+
+          [algorithm, encoded]
+        end
+
+        # A signature this reader could verify if it had the right key, or the
+        # exception that says why it never could.
+        sig { params(algorithm: String, pkey: OpenSSL::PKey::PKey).void }
+        def expected!(algorithm, pkey)
+          unless ALGORITHMS.key?(algorithm)
+            raise UnsupportedFormat, unsupported_message(algorithm) if RESERVED_ALGORITHMS.include?(algorithm)
+
+            raise Corrupt, "#{algorithm.inspect} is not a signature algorithm this format defines"
+          end
+          return if pkey.is_a?(ALGORITHMS.fetch(algorithm))
+
+          raise UntrustedSignature,
+                "this bundle is signed #{algorithm}, and the key supplied is a #{pkey.class}. It was signed " \
+                "by somebody else, or verification was pointed at the wrong key"
+        end
+
+        sig { params(encoded: String).returns(String) }
+        def decode!(encoded)
+          encoded.unpack1("m0")
+        rescue ArgumentError
+          raise Corrupt, "the signature is not base64"
+        end
+
+        sig { params(algorithm: String).returns(String) }
+        def unsupported_message(algorithm)
+          "this bundle is signed #{algorithm}, which active_sanction #{VERSION} reserves but does not verify. " \
+            "Upgrade the gem, or read the bundle without verify_with: and accept that it is unverified"
+        end
+
+        sig { params(algorithm: String).returns(String) }
+        def mismatch_message(algorithm)
+          "this bundle's #{algorithm} signature was not made by the key supplied. The file is intact -- its " \
+            "records still hash to what its header says -- but somebody other than the expected publisher " \
+            "signed it, so nothing here says where it came from"
+        end
+
+        sig { returns(String) }
+        def unsigned_message
+          "this bundle carries no signature, and a key was supplied to verify one. An unsigned bundle is " \
+            "readable without verify_with:, but then nothing attests to who published it"
+        end
+      end
+    end
+  end
+end