zeroclick-sellers 0.1.0

data/lib/zeroclick/sellers/usage.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "contracts"
+require_relative "errors"
+
+module ZeroClick
+  module Sellers
+    # The two ZeroClick usage endpoints.
+    #
+    # Transport and interpretation are deliberately separate: the build_* and
+    # interpret_* functions are pure, so every decision about what a response
+    # means is testable without a socket, and the client cannot drift from them.
+    module Usage
+      CHECK_PATH = "/v1/usage/check"
+      REPORT_PATH = "/v1/usage"
+
+      # report_usage answers these with a typed denial reason rather than an
+      # opaque failure, so they are read as JSON instead of treated as noise.
+      TYPED_REPORT_STATUSES = [402, 404, 409].freeze
+
+      # Errors that mean the request never got an answer. Anything raised here
+      # that is NOT in this list is a bug in the SDK, not an outage, and must
+      # not be laundered into a fail-open allow.
+      TRANSPORT_ERRORS = [
+        IOError,
+        SocketError,
+        SystemCallError,
+        Timeout::Error,
+        Net::HTTPBadResponse,
+        Net::HTTPHeaderSyntaxError,
+        OpenSSL::SSL::SSLError
+      ].freeze
+
+      module_function
+
+      def request_headers(api_key)
+        {
+          "accept" => "application/json",
+          "authorization" => "Bearer #{api_key}",
+          "content-type" => "application/json"
+        }
+      end
+
+      # ------------------------------------------------------------- build
+
+      def build_check_payload(zc_request_id:, service_slug:, usage:)
+        items = Sellers.normalize_usage(usage, operation: "check_allowance", allow_empty: false)
+        {
+          "zcRequestId" => zc_request_id,
+          "serviceSlug" => service_slug,
+          "usage" => items.map(&:to_wire)
+        }
+      end
+
+      def build_report_payload(zc_agent_id:, idempotency_key:, service_slug:, meter_slug:, quantity:,
+                               occurred_at: nil)
+        payload = {
+          "zcAgentId" => zc_agent_id,
+          "idempotencyKey" => idempotency_key,
+          "serviceSlug" => service_slug,
+          "meterSlug" => meter_slug,
+          "quantity" => quantity
+        }
+        payload["occurredAt"] = occurred_at unless occurred_at.nil?
+        payload
+      end
+
+      # --------------------------------------------------------- interpret
+
+      def decode(body, operation:, status:)
+        JSON.parse(body)
+      rescue JSON::ParserError
+        raise Error.new("api_response_invalid", operation: operation, status: status)
+      end
+
+      def interpret_check(status, body)
+        raise Error.new("api_status_error", operation: "check_allowance", status: status) if status >= 400
+
+        payload = decode(body, operation: "check_allowance", status: status)
+        unless payload.is_a?(Hash) && [true, false].include?(payload["allowed"])
+          raise Error.new("api_response_invalid", operation: "check_allowance", status: status)
+        end
+
+        reason = payload["reason"]
+        if !reason.nil? && !USAGE_DENIAL_REASONS.include?(reason)
+          raise Error.new("api_response_invalid", operation: "check_allowance", status: status, reason: reason)
+        end
+
+        AllowanceDecision.new(allowed: payload["allowed"], reason: reason)
+      end
+
+      def interpret_report(status, body)
+        if status >= 400
+          unless TYPED_REPORT_STATUSES.include?(status)
+            raise Error.new("api_status_error", operation: "report_usage", status: status)
+          end
+
+          payload = decode(body, operation: "report_usage", status: status)
+          reason = payload.is_a?(Hash) ? payload["error"] : nil
+          unless USAGE_DENIAL_REASONS.include?(reason)
+            raise Error.new("api_response_invalid", operation: "report_usage", status: status)
+          end
+
+          raise Error.new("api_status_error", operation: "report_usage", status: status, reason: reason)
+        end
+
+        payload = decode(body, operation: "report_usage", status: status)
+        unless payload.is_a?(Hash) &&
+               payload["recorded"] == true &&
+               [true, false].include?(payload["duplicate"]) &&
+               payload["usageEvent"].is_a?(Hash)
+          raise Error.new("api_response_invalid", operation: "report_usage", status: status)
+        end
+
+        ReportUsageResult.new(
+          recorded: true,
+          duplicate: payload["duplicate"],
+          usage_event: payload["usageEvent"]
+        )
+      end
+
+      # --------------------------------------------------------- transport
+
+      # Returns [status, body]. Raises only api_transport_error — an HTTP status
+      # is data here, not a failure, and interpretation happens above.
+      def post(base_url:, path:, api_key:, payload:, timeout:, operation:)
+        uri = URI.join(base_url, path)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        # Both halves, or a server that accepts the connection and then stalls
+        # hangs the request past the caller's budget.
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+
+        request = Net::HTTP::Post.new(uri)
+        request_headers(api_key).each { |name, value| request[name] = value }
+        request.body = JSON.generate(payload)
+
+        response = http.request(request)
+        [response.code.to_i, response.body.to_s]
+      rescue *TRANSPORT_ERRORS => e
+        raise Error.new("api_transport_error", operation: operation, cause: e.message)
+      ensure
+        http&.finish if http&.started?
+      end
+    end
+  end
+end

data/lib/zeroclick/sellers/verify.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+require_relative "contracts"
+require_relative "errors"
+require_relative "responses"
+
+module ZeroClick
+  module Sellers
+    # zc-signature verification. The algorithm is pinned by
+    # test/vectors/signing-vectors.json, which every SDK executes.
+    module Verify
+      # Bounded on purpose. Ruby's Integer() would happily convert an unbounded
+      # digit run, and a multi-megabyte one turns an unauthenticated request
+      # into a denial-of-service. 20 digits is far past any real epoch second and
+      # matches the other SDKs, which reject anything longer as malformed.
+      TIMESTAMP_RE = /\A\d{1,20}\z/
+      HEX_64_RE = /\A[0-9a-f]{64}\z/
+
+      module_function
+
+      # Parse `t=<unix>,kid=<id>,v1=<64 lowercase hex>`.
+      #
+      # Unknown members are IGNORED, deliberately. The proxy extends this header
+      # additively — `sb=1` marks sandbox traffic today — while signing a
+      # canonical string that is byte-identical either way. Demanding exactly
+      # three members failed every sandbox request as malformed_signature, so a
+      # seller on this SDK could never finish sandbox testing.
+      #
+      # What prevents an attacker smuggling a second v1 is DUPLICATE rejection,
+      # not the member count. Each check below defends one property:
+      #
+      # - the `=` and empty-key checks reject a structurally malformed member;
+      # - the duplicate check means a key can only ever be bound once, so a
+      #   later member cannot shadow an earlier one;
+      # - the three-key presence check is what the discarded member count only
+      #   ever implied;
+      # - only those three are returned, so an unknown member never reaches the
+      #   caller.
+      def parse_signature_header(value)
+        # -1 keeps trailing empty fields, so "t=1,kid=k,v1=x," stays malformed
+        # rather than silently losing its empty member.
+        entries = value.split(",", -1)
+        return nil if entries.length < 3
+
+        parsed = {}
+        entries.each do |entry|
+          separator = entry.index("=")
+          return nil if separator.nil? || separator.zero?
+
+          key = entry[0...separator].strip
+          return nil if key.empty?
+          return nil if parsed.key?(key)
+
+          parsed[key] = entry[(separator + 1)..].strip
+        end
+
+        return nil unless parsed.key?("t") && parsed.key?("kid") && parsed.key?("v1")
+        return nil unless TIMESTAMP_RE.match?(parsed["t"])
+        return nil unless HEX_64_RE.match?(parsed["v1"])
+
+        kid = parsed["kid"]
+        return nil if kid.empty? || kid != kid.strip
+
+        { "t" => parsed["t"], "kid" => kid, "v1" => parsed["v1"] }
+      end
+
+      # The exact bytes that get signed: six newline-joined fields.
+      def canonical_string(timestamp:, method:, path_and_query:, body:, zc_request_id:, zc_agent_id:)
+        [
+          timestamp,
+          method.upcase,
+          path_and_query,
+          OpenSSL::Digest::SHA256.hexdigest(body),
+          zc_request_id,
+          zc_agent_id || ""
+        ].join("\n")
+      end
+
+      # Verify a ZeroClick-signed request.
+      #
+      # Returns a value rather than raising: an unsigned or badly signed request
+      # is an expected event. VerifyFailure#response is ready to return as-is.
+      #
+      # A verified request whose zc_agent_id is nil is a signed anonymous probe,
+      # which is valid — not a failure.
+      #
+      # Provide exactly one of +signing_secrets+ (a Hash of kid => secret) or
+      # +resolve_signing_secret+ (a callable taking a kid, returning the secret
+      # or nil).
+      def call(request,
+               signing_secrets: nil,
+               resolve_signing_secret: nil,
+               tolerance_seconds: DEFAULT_TOLERANCE_SECONDS,
+               clock: -> { Time.now.to_i })
+        if signing_secrets.nil? == resolve_signing_secret.nil?
+          raise Error.new("malformed_input", operation: "verify_request",
+                                             message: "Provide exactly one of signing_secrets or resolve_signing_secret")
+        end
+        unless request.is_a?(Request)
+          raise Error.new("malformed_input", operation: "verify_request",
+                                             message: "request must be a ZeroClick::Sellers::Request")
+        end
+
+        resolve = resolve_signing_secret || ->(kid) { (signing_secrets || {})[kid] }
+
+        signature_header = request.header("zc-signature")
+        return VerifyFailure.new("missing_signature", Responses.invalid_zeroclick_signature) if signature_header.nil?
+
+        signature = parse_signature_header(signature_header)
+        return VerifyFailure.new("malformed_signature", Responses.invalid_zeroclick_signature) if signature.nil?
+
+        timestamp = Integer(signature["t"], 10)
+        now_seconds = clock.call.to_i
+        if (now_seconds - timestamp).abs > tolerance_seconds
+          return VerifyFailure.new("stale_timestamp", Responses.invalid_zeroclick_signature)
+        end
+
+        zc_request_id = request.header("zc-request-id")
+        if zc_request_id.nil? || zc_request_id.empty?
+          return VerifyFailure.new("missing_request_id", Responses.invalid_zeroclick_signature)
+        end
+
+        zc_agent_id = request.header("zc-agent-id")
+
+        begin
+          secret = resolve.call(signature["kid"])
+        rescue StandardError => e
+          raise Error.new("signing_secret_resolution_failed", operation: "verify_request",
+                                                              kid: signature["kid"], cause: e.message)
+        end
+
+        return VerifyFailure.new("unknown_kid", Responses.invalid_zeroclick_signature) if secret.nil?
+
+        unless secret.is_a?(String) && !secret.empty?
+          raise Error.new("signing_secret_resolution_failed", operation: "verify_request",
+                                                              kid: signature["kid"])
+        end
+
+        expected = OpenSSL::HMAC.hexdigest(
+          "SHA256",
+          secret,
+          canonical_string(
+            timestamp: signature["t"],
+            method: request.method,
+            path_and_query: request.path_and_query,
+            body: request.body,
+            zc_request_id: zc_request_id,
+            zc_agent_id: zc_agent_id
+          )
+        )
+
+        # Constant time: a byte-at-a-time compare leaks the signature prefix.
+        unless OpenSSL.secure_compare(expected, signature["v1"])
+          return VerifyFailure.new("invalid_signature", Responses.invalid_zeroclick_signature)
+        end
+
+        VerifyOk.new(
+          ZeroClickContext.new(
+            zc_request_id: zc_request_id,
+            zc_agent_id: zc_agent_id,
+            timestamp: timestamp,
+            kid: signature["kid"],
+            zc_anonymous_id: request.header("zc-anonymous-id"),
+            zc_buyer_id: request.header("zc-buyer-id")
+          )
+        )
+      end
+    end
+
+    # Verify a ZeroClick-signed request. See Verify.call.
+    def self.verify_request(request, **options)
+      Verify.call(request, **options)
+    end
+  end
+end

data/lib/zeroclick/sellers/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module ZeroClick
+  module Sellers
+    # Bump this to publish. The workflow reads it, asks RubyGems whether this
+    # version already exists, and publishes only when it does not.
+    VERSION = "0.1.0"
+  end
+end

data/lib/zeroclick/sellers.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "sellers/version"
+require_relative "sellers/errors"
+require_relative "sellers/contracts"
+require_relative "sellers/responses"
+require_relative "sellers/verify"
+require_relative "sellers/usage"
+require_relative "sellers/client"
+require_relative "sellers/middleware"
+
+# The ZeroClick billing guard for Ruby backends.
+#
+# It verifies that a request really came from ZeroClick, checks that the buyer
+# can pay before you do the work, builds the refusal responses ZeroClick
+# expects, and reports what was used.
+#
+# The core is stdlib-only — openssl, json, net/http — so it adds nothing to your
+# dependency graph. The Rack middleware is duck-typed and needs no rack require;
+# `zeroclick/sellers/railtie` is opt-in and is the only file that touches Rails.
+module ZeroClick
+  module Sellers
+    class << self
+      # Create a seller client. See Client#initialize for the options.
+      def create(**options)
+        Client.new(**options)
+      end
+
+      # Store the options a later .seller call will build from. Used by the
+      # Railtie; call it directly in a non-Rails app if you want the same
+      # process-wide singleton.
+      def configure(**options)
+        @config = options
+        @seller = nil
+        self
+      end
+
+      # The process-wide client built from .configure. Lazy, so boot does not
+      # depend on credentials being present in every environment.
+      def seller
+        @seller ||= begin
+          if @config.nil? || @config.empty?
+            raise Error.new("malformed_input", operation: "seller",
+                                               message: "Call ZeroClick::Sellers.configure first (or config.zeroclick under Rails)")
+          end
+          create(**@config)
+        end
+      end
+
+      # Parse ZEROCLICK_SIGNING_SECRETS, formatted `kid1:secret1,kid2:secret2`.
+      #
+      # Rotation is why this is a map rather than a single secret: during a
+      # rotation both the old and the new kid must verify, or every in-flight
+      # request fails.
+      def secrets_from_env(value = ENV.fetch("ZEROCLICK_SIGNING_SECRETS", nil))
+        if value.nil? || value.strip.empty?
+          raise Error.new("malformed_input", operation: "secrets_from_env",
+                                             message: "ZEROCLICK_SIGNING_SECRETS is unset or empty")
+        end
+
+        value.split(",").each_with_object({}) do |pair, out|
+          kid, separator, secret = pair.partition(":")
+          kid = kid.strip
+          secret = secret.strip
+          if separator.empty? || kid.empty? || secret.empty?
+            raise Error.new("malformed_input", operation: "secrets_from_env",
+                                               message: "Expected ZEROCLICK_SIGNING_SECRETS as kid1:secret1,kid2:secret2")
+          end
+          out[kid] = secret
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: zeroclick-sellers
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ZeroClick
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Verify that a request really came from ZeroClick, check that the buyer can
+  pay before you do the work, return the refusal responses ZeroClick expects,
+  and report what was used. Ships Rack middleware, so it works in Rails,
+  Sinatra, Hanami and Roda alike.
+email:
+- support@zeroclick.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/zeroclick/sellers.rb
+- lib/zeroclick/sellers/client.rb
+- lib/zeroclick/sellers/contracts.rb
+- lib/zeroclick/sellers/errors.rb
+- lib/zeroclick/sellers/middleware.rb
+- lib/zeroclick/sellers/railtie.rb
+- lib/zeroclick/sellers/responses.rb
+- lib/zeroclick/sellers/usage.rb
+- lib/zeroclick/sellers/verify.rb
+- lib/zeroclick/sellers/version.rb
+homepage: https://zeroclick.io
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://zeroclick.io
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: The ZeroClick billing guard for Ruby and Rails backends
+test_files: []