zeroclick-sellers 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06b9bd195b7dc0b39d12660feeb511f4260c2b6627270d8dc643576e69b005a0
-  data.tar.gz: d5e7a552b95d6f7664a96185de1446a0d215735fdcdf40e18479de90c7c30d1b
+  metadata.gz: 21a687776a099cffab368909929c6181de3425e83d6fe94bcfaba52cc40e76a8
+  data.tar.gz: 15b009873e6410a7703a6385ebdfc0d737f1be8d3d475b18ed22e96683117904
 SHA512:
-  metadata.gz: 117c713bf87542ba54035ce2fa1d256716716f2297cd2cbab53739da2350c7b9ae9fa30e9f252ade7f660666bf93a5e61871e11cf976205cf66bb6559cf1cc25
-  data.tar.gz: 01b80f728b183fa5d9d55aed65c25592c40bf77649bae4e6917ad0300e27c2ae3021aea45110bb708919175be2d74ca75c92e79b345a11b925d365d7127bd010
+  metadata.gz: 10cc75f795e921fa55d77b5dce9f101d1f3c4afadb191fe70546db9bd01dd309fe8453cfedd24de1d1991e1716567de26378b17cb87fb8338866f1132d4e96bd
+  data.tar.gz: 82a1860e38b1a2b53195b1aa0c17830b60f2c7ad5cdc80efc280c6547678f74771ed799a42ddabaf405c1df3f00f36de6344402e3c104c03078cc94e2d00f90e

data/README.md

@@ -161,6 +161,80 @@ The idempotency key is yours to derive and must be stable for the request. The
 SDK never invents one and never retries on your behalf — a retry that changed
 the key would double-bill.
 
+## Encrypted bodies
+
+When ZeroClick encrypts a request body to your public key, decrypt it before
+doing anything else — the signature covers the *ciphertext*, so verify first,
+decrypt second.
+
+```ruby
+require "zeroclick/sellers/encryption"
+
+envelope = ZeroClick::Sellers.decrypt_request(
+  request.body,
+  resolve_private_key: ->(kid) { MY_JWKS[kid] }
+)
+
+envelope.plaintext  # the decrypted body, UTF-8
+envelope.cty        # the plaintext's media type, when declared
+envelope.reply_jwk  # present when the buyer wants an encrypted reply
+
+# Returns the response unchanged when no reply key was offered.
+ZeroClick::Sellers.encrypt_response(response, envelope)
+```
+
+The suite is pinned to `ECDH-ES+A256KW` / `A256GCM`, and anything else is
+refused rather than negotiated — accepting another algorithm is how an attacker
+downgrades to one they can break. A reply JWK carrying private material
+(`d`, `p`, `q`, …) is rejected outright with its own error code.
+
+**Still no runtime dependencies.** This is built on OpenSSL from the standard
+library; the one primitive it lacks, Concat KDF, is a short SHA-256 loop. Even
+base64 is done with core `pack`/`unpack1` rather than the `base64` stdlib,
+which stops being a default gem in Ruby 3.4.
+
+## Stateful sellers
+
+If purchases provision a standing account — credits, a subscription, API keys —
+rather than settling one call, `require "zeroclick/sellers/stateful"`.
+
+```ruby
+response = ZeroClick::Sellers::Stateful.handle_access_request(
+  request,
+  base_path: "/zeroclick/access",
+  remint_policy: "additive",       # or "rotating" — one live key at a time
+  signing_secrets: ZeroClick::Sellers.secrets_from_env,
+  on_write: ->(input) { ... ZeroClick::Sellers::Stateful::WriteResult.new(lifecycle: "active") },
+  on_mint: ->(input) { ZeroClick::Sellers::Stateful::MintKey.new(api_key: "sk_...") }
+)
+
+# nil means the route is not ours — serve it normally.
+return serve_normally if response.nil?
+```
+
+The credit arithmetic is **cumulative, not incremental**: both grants and
+reversals are monotonic totals, so a delivery that arrives twice, out of order,
+or after a gap converges on the same purse.
+
+```ruby
+delta = ZeroClick::Sellers::Stateful::Entitlement.derive_credit_delta(stored, entitlement)
+delta.outcome    # "credit", "debit", "replay", or "no_credit_dimension"
+delta.delta_usd  # what to move
+delta.next       # persist ATOMICALLY with the purse, or a retry double-applies
+```
+
+Three properties worth internalising before you wire it up:
+
+- **The signature is a different one.** Stateful requests sign a *seven*-field
+  canonical string whose trailing purpose segment comes from the matched route.
+  An ordinary proxy signature is invalid here, and vice versa — deliberately.
+- **A matched route always answers.** A handler that raises becomes the `503`
+  ZeroClick retries, never an exception escaping into your request path.
+- **Money is a six-decimal string, capped at 2^53−1.** Ruby's Integer is
+  arbitrary precision, so that ceiling is a contract rule here rather than a
+  language limit — without it Ruby would accept amounts the TypeScript SDK
+  cannot represent.
+
 ## Behaviour worth knowing
 
 - **Verify first, always.** Every entry point verifies `zc-signature` before

data/lib/zeroclick/sellers/encryption.rb

@@ -0,0 +1,392 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "securerandom"
+
+require_relative "contracts"
+require_relative "errors"
+
+module ZeroClick
+  module Sellers
+    # Encrypted request and response bodies.
+    #
+    # ZeroClick can encrypt a buyer's request body to the seller's public key
+    # and ask for the reply encrypted back. The suite is pinned —
+    # `ECDH-ES+A256KW` key management, `A256GCM` content encryption — and the
+    # proxy carries its reply key in a custom protected-header parameter.
+    #
+    # Implemented on the standard library alone: OpenSSL provides P-256 ECDH,
+    # AES key wrap (RFC 3394) and AES-256-GCM, and the one missing piece —
+    # NIST SP 800-56A Concat KDF — is a short SHA-256 loop. That matters: the
+    # gem promises zero runtime dependencies and CI fails the build if one
+    # appears, so reaching for a JOSE gem here would have cost the property
+    # outright. (The Go SDK could not manage this and isolates go-jose in a
+    # separate package to keep its own core clean.)
+    #
+    # Interoperates with @zeroclickai/sellers; test/vectors/jwe-vectors.json is
+    # real TypeScript output and is what keeps them that way.
+    module Encryption
+      ALG = "ECDH-ES+A256KW"
+      ENC = "A256GCM"
+      REPLY_JWK_PARAM = "https://zeroclick.io/jwe/reply-jwk"
+
+      CURVE = "prime256v1"
+      # RFC 3394's fixed initial value for AES key wrap.
+      KEY_WRAP_IV = ["A6A6A6A6A6A6A6A6"].pack("H*")
+      KEY_WRAP_ROUNDS = 6
+
+      # Members whose presence means a JWK carries private key material. A
+      # reply key arriving with any of them is a protocol violation, not a key
+      # to quietly use.
+      PRIVATE_JWK_MEMBERS = %w[d p q dp dq qi oth k].freeze
+      ALLOWED_REPLY_JWK_MEMBERS = %w[kty crv kid x y use alg].freeze
+
+      MESSAGES = {
+        "invalid_compact_jwe" => "The request body is not a valid Compact JWE",
+        "unsupported_jwe_suite" => "The Compact JWE uses an unsupported algorithm suite",
+        "jwe_kid_required" => "The Compact JWE protected header requires a key ID",
+        "invalid_reply_jwk" => "The reply JWK is not a public P-256 key",
+        "private_reply_jwk" => "The reply JWK must not contain private key material",
+        "private_key_not_found" => "No private key was found for the Compact JWE key ID",
+        "private_key_resolution_failed" => "The private key could not be resolved",
+        "decryption_failed" => "The encrypted request could not be decrypted",
+        "encryption_failed" => "The response could not be encrypted"
+      }.freeze
+
+      # A decrypted request, plus what is needed to encrypt the reply.
+      class Envelope
+        attr_reader :plaintext, :protected_header, :cty, :reply_jwk
+
+        def initialize(plaintext:, protected_header:, cty: nil, reply_jwk: nil)
+          @plaintext = plaintext
+          @protected_header = protected_header.freeze
+          @cty = cty
+          @reply_jwk = reply_jwk&.freeze
+          freeze
+        end
+      end
+
+      module_function
+
+      def error(code, operation, **context)
+        Error.new(code, operation: operation, message: MESSAGES.fetch(code), **context)
+      end
+
+      # base64url, on core String/Array only.
+      #
+      # Deliberately NOT the base64 stdlib: it stops being a default gem in
+      # Ruby 3.4, so requiring it would force this gem to declare a runtime
+      # dependency — and the point of implementing JWE here rather than behind
+      # a JOSE gem is that it needs none.
+      def b64u_decode(value)
+        raise ArgumentError, "not base64url" unless value.is_a?(String)
+        raise ArgumentError, "not base64url" unless value.match?(/\A[A-Za-z0-9_-]*\z/)
+
+        padded = value.tr("-_", "+/")
+        padded += "=" * ((4 - (padded.length % 4)) % 4)
+        decoded = padded.unpack1("m0")
+        raise ArgumentError, "not base64url" if decoded.nil?
+
+        decoded
+      end
+
+      def b64u_encode(bytes)
+        [bytes].pack("m0").tr("+/", "-_").delete("=")
+      end
+
+      # NIST SP 800-56A Concat KDF, the one primitive OpenSSL does not expose.
+      #
+      # Single round only: the suite derives 256 bits and SHA-256 produces
+      # exactly that, so the counter never advances past 1. A wider key would
+      # need the loop.
+      def concat_kdf(shared_secret, key_bits, algorithm_id)
+        other_info = [algorithm_id.bytesize].pack("N") + algorithm_id +
+                     [0].pack("N") + [0].pack("N") + [key_bits].pack("N")
+        OpenSSL::Digest::SHA256.digest([1].pack("N") + shared_secret + other_info)[0, key_bits / 8]
+      end
+
+      # AES Key Wrap (RFC 3394), built on AES-ECB.
+      #
+      # NOT OpenSSL's "aes-256-wrap" cipher: that is absent from some builds —
+      # it works on macOS and raises `unsupported cipher algorithm` on the
+      # Ubuntu runners — so relying on it made the SDK's portability depend on
+      # how the host happened to compile OpenSSL. AES-ECB is everywhere, and
+      # the wrapping itself is a short, fully specified loop.
+      #
+      # ECB is safe here precisely because RFC 3394 is what supplies the
+      # structure: each block is chained through the A register, and the fixed
+      # IV check on unwrap is what authenticates the result.
+      def aes_ecb(key, mode)
+        cipher = OpenSSL::Cipher.new("aes-256-ecb")
+        mode == :encrypt ? cipher.encrypt : cipher.decrypt
+        cipher.key = key
+        cipher.padding = 0
+        cipher
+      end
+
+      def aes_key_wrap(kek, plaintext)
+        raise ArgumentError, "key to wrap must be a multiple of 8 bytes" unless (plaintext.bytesize % 8).zero?
+
+        blocks = plaintext.scan(/.{8}/m)
+        a = KEY_WRAP_IV
+        cipher = aes_ecb(kek, :encrypt)
+
+        KEY_WRAP_ROUNDS.times do |round|
+          blocks.each_with_index do |block, index|
+            b = cipher.update(a + block) + cipher.final
+            counter = (blocks.length * round) + index + 1
+            a = xor_counter(b[0, 8], counter)
+            blocks[index] = b[8, 8]
+          end
+        end
+
+        a + blocks.join
+      end
+
+      def aes_key_unwrap(kek, ciphertext)
+        raise ArgumentError, "wrapped key must be a multiple of 8 bytes" unless (ciphertext.bytesize % 8).zero?
+
+        blocks = ciphertext.scan(/.{8}/m)
+        a = blocks.shift
+        cipher = aes_ecb(kek, :decrypt)
+
+        (KEY_WRAP_ROUNDS - 1).downto(0) do |round|
+          (blocks.length - 1).downto(0) do |index|
+            counter = (blocks.length * round) + index + 1
+            b = cipher.update(xor_counter(a, counter) + blocks[index]) + cipher.final
+            a = b[0, 8]
+            blocks[index] = b[8, 8]
+          end
+        end
+
+        # The fixed IV is the integrity check: a wrong KEK produces a different
+        # A, so this is what makes unwrapping fail closed rather than return
+        # plausible garbage.
+        raise ArgumentError, "key unwrap integrity check failed" unless a == KEY_WRAP_IV
+
+        blocks.join
+      end
+
+      def xor_counter(block, counter)
+        counter_bytes = [0, counter].pack("NN")
+        block.bytes.each_with_index.map { |byte, i| byte ^ counter_bytes.getbyte(i) }.pack("C*")
+      end
+
+      # Build an OpenSSL EC key from a JWK.
+      #
+      # Ruby 3.x has no JWK importer and EC keys are immutable, so the key is
+      # assembled as ASN.1 and parsed back — the only route from raw
+      # coordinates to a usable key.
+      def ec_key_from_jwk(jwk, private: false)
+        group = OpenSSL::PKey::EC::Group.new(CURVE)
+        x = b64u_decode(jwk["x"] || jwk[:x])
+        y = b64u_decode(jwk["y"] || jwk[:y])
+        point = OpenSSL::PKey::EC::Point.new(
+          group, OpenSSL::BN.new("04#{x.unpack1("H*")}#{y.unpack1("H*")}", 16)
+        )
+
+        unless private
+          sequence = OpenSSL::ASN1::Sequence([
+                                               OpenSSL::ASN1::Sequence([
+                                                                         OpenSSL::ASN1::ObjectId("id-ecPublicKey"),
+                                                                         OpenSSL::ASN1::ObjectId(CURVE)
+                                                                       ]),
+                                               OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed))
+                                             ])
+          return OpenSSL::PKey::EC.new(sequence.to_der)
+        end
+
+        d = b64u_decode(jwk["d"] || jwk[:d])
+        sequence = OpenSSL::ASN1::Sequence([
+                                             OpenSSL::ASN1::Integer(1),
+                                             OpenSSL::ASN1::OctetString(d),
+                                             OpenSSL::ASN1::ObjectId(CURVE, 0, :EXPLICIT),
+                                             OpenSSL::ASN1::BitString(point.to_octet_string(:uncompressed), 1, :EXPLICIT)
+                                           ])
+        OpenSSL::PKey::EC.new(sequence.to_der)
+      end
+
+      def jwk_from_ec_public(key, extra = {})
+        point = key.public_key.to_octet_string(:uncompressed)
+        # Uncompressed point: 0x04 || X || Y, 32 bytes each for P-256.
+        { "kty" => "EC", "crv" => "P-256",
+          "x" => b64u_encode(point[1, 32]), "y" => b64u_encode(point[33, 32]) }.merge(extra)
+      end
+
+      def decode_protected_header(compact_jwe)
+        segments = compact_jwe.split(".", -1)
+        # The ciphertext segment (index 3) may legitimately be empty — an empty
+        # plaintext is a real case. No other segment may be.
+        if segments.length != 5 || segments.each_with_index.any? { |seg, i| seg.empty? && i != 3 }
+          raise error("invalid_compact_jwe", "decrypt_request")
+        end
+
+        header = JSON.parse(b64u_decode(segments[0]))
+        raise error("invalid_compact_jwe", "decrypt_request") unless header.is_a?(Hash)
+
+        [header, segments]
+      rescue ArgumentError, JSON::ParserError
+        raise error("invalid_compact_jwe", "decrypt_request")
+      end
+
+      def validated_reply_jwk(header)
+        value = header[REPLY_JWK_PARAM]
+        return nil if value.nil?
+        raise error("invalid_reply_jwk", "decrypt_request") unless value.is_a?(Hash)
+
+        # Checked before shape: a key carrying private material is a different
+        # and more serious problem than a malformed one, and earns its own code.
+        raise error("private_reply_jwk", "decrypt_request") if PRIVATE_JWK_MEMBERS.any? { |member| value.key?(member) }
+
+        raise error("invalid_reply_jwk", "decrypt_request") unless (value.keys - ALLOWED_REPLY_JWK_MEMBERS).empty?
+        raise error("invalid_reply_jwk", "decrypt_request") unless value["kty"] == "EC" && value["crv"] == "P-256"
+
+        %w[x y].each do |coordinate|
+          candidate = value[coordinate]
+          # 43 chars is exactly a base64url-encoded 32-byte P-256 coordinate.
+          raise error("invalid_reply_jwk", "decrypt_request") unless candidate.is_a?(String) && candidate.length == 43
+        end
+
+        raise error("invalid_reply_jwk", "decrypt_request") if value.key?("use") && value["use"] != "enc"
+        raise error("invalid_reply_jwk", "decrypt_request") if value.key?("alg") && value["alg"] != ALG
+
+        kid = value["kid"]
+        if !kid.nil? && (!kid.is_a?(String) || kid.strip.empty? || kid.length > 128)
+          raise error("invalid_reply_jwk", "decrypt_request")
+        end
+
+        value
+      end
+
+      # Decrypt a Compact JWE request body.
+      #
+      # +body+ is the raw request bytes, which for an encrypted request are the
+      # ASCII Compact JWE rather than JSON.
+      #
+      # +resolve_private_key+ is a callable taking the header's `kid` and
+      # returning that key's JWK (or nil when the kid is unknown).
+      def decrypt_request(body, resolve_private_key:)
+        compact_jwe = body.is_a?(String) ? body.dup.force_encoding(Encoding::UTF_8) : body.to_s
+        raise error("invalid_compact_jwe", "decrypt_request") unless compact_jwe.valid_encoding?
+
+        header, segments = decode_protected_header(compact_jwe)
+
+        raise error("unsupported_jwe_suite", "decrypt_request") unless header["alg"] == ALG && header["enc"] == ENC
+
+        kid = header["kid"]
+        raise error("jwe_kid_required", "decrypt_request") unless kid.is_a?(String) && !kid.empty?
+
+        cty = header["cty"]
+        raise error("invalid_compact_jwe", "decrypt_request") if !cty.nil? && !cty.is_a?(String)
+
+        reply_jwk = validated_reply_jwk(header)
+
+        begin
+          private_jwk = resolve_private_key.call(kid)
+        rescue StandardError => e
+          raise error("private_key_resolution_failed", "decrypt_request", kid: kid, cause: e.message)
+        end
+        raise error("private_key_not_found", "decrypt_request", kid: kid) if private_jwk.nil?
+
+        plaintext = decrypt_segments(segments, header, private_jwk, kid)
+
+        Envelope.new(plaintext: plaintext, protected_header: header, cty: cty, reply_jwk: reply_jwk)
+      end
+
+      def decrypt_segments(segments, header, private_jwk, kid)
+        header_b64, encrypted_key, iv, ciphertext, tag = segments
+
+        private_key = ec_key_from_jwk(private_jwk, private: true)
+        epk = header["epk"]
+        raise error("decryption_failed", "decrypt_request", kid: kid) unless epk.is_a?(Hash)
+
+        shared = private_key.dh_compute_key(ec_key_from_jwk(epk).public_key)
+        kek = concat_kdf(shared, 256, ALG)
+
+        cek = aes_key_unwrap(kek, b64u_decode(encrypted_key))
+
+        decipher = OpenSSL::Cipher.new("aes-256-gcm").decrypt
+        decipher.key = cek
+        decipher.iv = b64u_decode(iv)
+        decipher.auth_tag = b64u_decode(tag)
+        # The AAD is the RAW protected header segment, not a re-encoding of it.
+        decipher.auth_data = header_b64
+        # An empty ciphertext is a real case (the empty_plaintext vector), and
+        # OpenSSL::Cipher#update rejects an empty string on older openssl gems
+        # — Ruby 3.1 raises where 3.3 does not. Skip straight to #final, which
+        # still verifies the GCM tag.
+        encrypted_bytes = b64u_decode(ciphertext)
+        raw = encrypted_bytes.empty? ? decipher.final : decipher.update(encrypted_bytes) + decipher.final
+
+        # OpenSSL hands back ASCII-8BIT. The plaintext is a request body, and
+        # leaving it binary makes `==` against any UTF-8 string false for every
+        # non-ASCII byte — which is exactly how the unicode vector fails while
+        # the bytes are identical.
+        raw.force_encoding(Encoding::UTF_8)
+        raw.valid_encoding? ? raw : raw.force_encoding(Encoding::BINARY)
+      rescue OpenSSL::OpenSSLError, ArgumentError => e
+        raise error("decryption_failed", "decrypt_request", kid: kid, cause: e.message)
+      end
+
+      # Encrypt a response back to the buyer's reply key.
+      #
+      # When the request carried no reply key the response is returned
+      # unchanged — the buyer did not ask for an encrypted reply.
+      def encrypt_response(response, envelope)
+        return response if envelope.reply_jwk.nil?
+
+        protected_header = { "alg" => ALG, "enc" => ENC }
+        content_type = response.headers["content-type"] || response.headers["Content-Type"]
+        protected_header["cty"] = content_type if content_type
+
+        compact = encrypt_compact(protected_header, response.body, envelope.reply_jwk)
+
+        headers = response.headers.reject { |name, _| %w[content-type content-length].include?(name.to_s.downcase) }
+        headers["content-type"] = "application/jose"
+
+        Response.new(status: response.status, body: compact, headers: headers)
+      end
+
+      def encrypt_compact(protected_header, plaintext, recipient_jwk)
+        recipient = ec_key_from_jwk(recipient_jwk)
+
+        # A fresh ephemeral key per message: ECDH-ES derives the KEK from it,
+        # so reusing one would reuse the KEK across messages.
+        ephemeral = OpenSSL::PKey::EC.generate(CURVE)
+        shared = ephemeral.dh_compute_key(recipient.public_key)
+        kek = concat_kdf(shared, 256, ALG)
+
+        cek = SecureRandom.bytes(32)
+        encrypted_key = aes_key_wrap(kek, cek)
+
+        header = protected_header.merge("epk" => jwk_from_ec_public(ephemeral))
+        header_b64 = b64u_encode(JSON.generate(header))
+
+        iv = SecureRandom.bytes(12)
+        cipher = OpenSSL::Cipher.new("aes-256-gcm").encrypt
+        cipher.key = cek
+        cipher.iv = iv
+        cipher.auth_data = header_b64
+        # Same empty-input constraint as the decrypt path above.
+        plain_bytes = plaintext.to_s.dup.force_encoding(Encoding::BINARY)
+        ciphertext = plain_bytes.empty? ? cipher.final : cipher.update(plain_bytes) + cipher.final
+
+        [header_b64, b64u_encode(encrypted_key), b64u_encode(iv),
+         b64u_encode(ciphertext), b64u_encode(cipher.auth_tag)].join(".")
+      rescue OpenSSL::OpenSSLError, ArgumentError => e
+        raise error("encryption_failed", "encrypt_response", cause: e.message)
+      end
+    end
+
+    # Decrypt a Compact JWE request body. See Encryption.decrypt_request.
+    def self.decrypt_request(body, resolve_private_key:)
+      Encryption.decrypt_request(body, resolve_private_key: resolve_private_key)
+    end
+
+    # Encrypt a response to the buyer's reply key. See Encryption.encrypt_response.
+    def self.encrypt_response(response, envelope)
+      Encryption.encrypt_response(response, envelope)
+    end
+  end
+end

data/lib/zeroclick/sellers/stateful/contracts.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "money"
+
+module ZeroClick
+  module Sellers
+    module Stateful
+      # suspended is recoverable; closed is terminal — revoke live keys, stop
+      # serving, keep your records.
+      ACCESS_STATUSES = %w[active suspended closed].freeze
+
+      # zod v4's `iso.datetime({offset: true})` grammar, transcribed verbatim —
+      # as the Python and Go SDKs also transcribe it. Seconds and the fraction
+      # are optional, the calendar is validated (leap years included), and the
+      # zone must be Z or ±HH:MM.
+      #
+      # Copied rather than approximated on purpose: an SDK that accepts a
+      # timestamp ZeroClick rejects (or the reverse) turns a valid entitlement
+      # into a 400 nobody can reproduce.
+      ISO_DATETIME_RE = /
+        \A(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00
+        |[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])
+        |(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))
+        T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?
+        (?:Z|(?:[+-](?:[01]\d|2[0-3]):[0-5]\d)))\z
+      /x
+
+      AccessPeriod = Struct.new(:start, :end, keyword_init: true)
+      EntitlementPlan = Struct.new(:slug, :name, :billing_mode, :interval, :base_price_usd, keyword_init: true)
+      MintKeyRequest = Struct.new(:agent_id, :buyer_id, keyword_init: true)
+
+      ParsedEntitlement = Struct.new(
+        :access_id, :agent_id, :buyer_id, :buyer_email, :idempotency_key,
+        :state_version, :plan, :period, :status,
+        :lifetime_credit_granted_usd, :lifetime_credit_reversed_usd,
+        :base_price_usd_micros, :lifetime_credit_granted_usd_micros, :lifetime_credit_reversed_usd_micros,
+        keyword_init: true
+      )
+
+      module Contracts
+        module_function
+
+        def iso_datetime?(value)
+          value.is_a?(String) && ISO_DATETIME_RE.match?(value)
+        end
+
+        def non_empty_string?(value)
+          value.is_a?(String) && !value.empty?
+        end
+
+        # A non-negative integer. JSON `1.0` counts; `true` and `"1"` do not.
+        def as_version(value)
+          return nil if value.is_a?(TrueClass) || value.is_a?(FalseClass)
+          return value.negative? ? nil : value if value.is_a?(Integer)
+
+          if value.is_a?(Float) && value.finite? && (value % 1).zero?
+            version = value.to_i
+            return version.negative? ? nil : version
+          end
+
+          nil
+        end
+
+        # Required but nullable: a missing key is an error, null is not.
+        # Returns [value, ok].
+        def nullable_id(container, key)
+          return [nil, false] unless container.key?(key)
+
+          value = container[key]
+          return [nil, true] if value.nil?
+          return [value, true] if non_empty_string?(value)
+
+          [nil, false]
+        end
+
+        def parse_mint_key_request(body)
+          return nil unless body.is_a?(Hash) && non_empty_string?(body["agentId"])
+
+          buyer_id, ok = nullable_id(body, "buyerId")
+          return nil unless ok
+
+          MintKeyRequest.new(agent_id: body["agentId"], buyer_id: buyer_id)
+        end
+
+        def parse_plan(value, issues)
+          unless value.is_a?(Hash)
+            issues << "plan: expected an object"
+            return nil
+          end
+
+          before = issues.length
+          %w[slug name billingMode interval].each do |key|
+            issues << "plan.#{key}: expected a string" unless value[key].is_a?(String)
+          end
+          issues << "plan.basePriceUsd: expected a six-decimal USD string" unless Money.money_usd?(value["basePriceUsd"])
+          return nil if issues.length != before
+
+          EntitlementPlan.new(
+            slug: value["slug"], name: value["name"], billing_mode: value["billingMode"],
+            interval: value["interval"], base_price_usd: value["basePriceUsd"]
+          )
+        end
+
+        def parse_period(value, issues)
+          unless value.is_a?(Hash)
+            issues << "state.period: expected an object"
+            return nil
+          end
+
+          before = issues.length
+          start = value["start"]
+          issues << "state.period.start: expected an ISO datetime" unless iso_datetime?(start)
+          # Required but nullable: absence is a different mistake from null,
+          # and only absence is an error.
+          issues << "state.period.end: required (may be null)" unless value.key?("end")
+          finish = value["end"]
+          issues << "state.period.end: expected an ISO datetime or null" if !finish.nil? && !iso_datetime?(finish)
+
+          return nil if issues.length != before
+
+          AccessPeriod.new(start: start, end: finish)
+        end
+
+        def parse_money_field(container, key, issues:)
+          unless container.key?(key)
+            issues << "state.#{key}: required (may be null)"
+            return nil
+          end
+
+          value = container[key]
+          return nil if value.nil?
+          return value if Money.money_usd?(value)
+
+          issues << "state.#{key}: expected a six-decimal USD string or null"
+          nil
+        end
+      end
+    end
+  end
+end