zeroclick-sellers 0.1.0

data/lib/zeroclick/sellers/contracts.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "errors"
+
+module ZeroClick
+  module Sellers
+    DEFAULT_API_BASE_URL = "https://api.zeroclick.io"
+    DEFAULT_TOLERANCE_SECONDS = 300
+    DEFAULT_CHECK_TIMEOUT_SECONDS = 1.5
+
+    # Reasons the allowance API gives for refusing. Any other reason on the wire
+    # is treated as a malformed response rather than silently passed through.
+    USAGE_DENIAL_REASONS = %w[
+      service_not_found
+      access_not_found
+      access_inactive
+      plan_expired
+      meter_not_found
+      meter_not_priced
+      usage_exhausted
+    ].freeze
+
+    ALLOWANCE_UNAVAILABLE_POLICIES = %w[allow deny throw].freeze
+
+    # A framework-neutral view of an inbound request.
+    #
+    # The SDK never loads Rails, Sinatra or Rack — everything flows through
+    # Request and Response, and each adapter does the (small) translation. That
+    # is what keeps one implementation serving every Ruby web framework.
+    class Request
+      attr_reader :method, :path_and_query, :headers, :body
+
+      # +path_and_query+ must be the RAW, percent-encoded path and query exactly
+      # as it arrived. Frameworks that hand you a decoded path will break
+      # verification for any route containing an encoded character — see
+      # Middleware.path_and_query_from_env.
+      #
+      # +body+ must be the raw bytes as received. Decode nothing before verifying.
+      def initialize(method:, path_and_query:, headers: {}, body: "")
+        unless body.is_a?(String)
+          raise Error.new("malformed_input", operation: "Request",
+                                             message: "body must be a String of raw bytes; decode nothing before verifying")
+        end
+
+        @method = method
+        @path_and_query = path_and_query
+        @headers = headers.each_with_object({}) { |(k, v), out| out[k.to_s.downcase] = v }.freeze
+        # ASCII-8BIT so the SHA-256 below hashes bytes, never a re-encoding.
+        @body = body.dup.force_encoding(Encoding::BINARY).freeze
+        freeze
+      end
+
+      def header(name)
+        @headers[name.to_s.downcase]
+      end
+    end
+
+    # A framework-neutral response the caller is expected to return as-is.
+    class Response
+      attr_reader :status, :body, :headers
+
+      def initialize(status:, body:, headers: {})
+        @status = status
+        @body = body
+        @headers = headers.freeze
+        freeze
+      end
+
+      def self.json(payload, status: 200, headers: {})
+        new(
+          status: status,
+          # Compact separators, matching the other SDKs byte for byte.
+          body: JSON.generate(payload),
+          headers: { "content-type" => "application/json" }.merge(headers)
+        )
+      end
+
+      def json_body
+        JSON.parse(@body)
+      end
+    end
+
+    # Proven facts about a verified request.
+    ZeroClickContext = Struct.new(
+      :zc_request_id,
+      :zc_agent_id,
+      :timestamp,
+      :kid,
+      # Same value as zc_agent_id, read from the header that will replace
+      # zc-agent-id.
+      :zc_anonymous_id,
+      # The buyer that owns zc_agent_id, present only once claimed. Unlike the
+      # other three it is NOT covered by the signature.
+      :zc_buyer_id,
+      keyword_init: true
+    )
+
+    # -- verification results ------------------------------------------------
+
+    class VerifyOk
+      attr_reader :context
+
+      def initialize(context)
+        @context = context
+        freeze
+      end
+
+      def ok? = true
+    end
+
+    class VerifyFailure
+      attr_reader :reason, :response
+
+      def initialize(reason, response)
+        @reason = reason
+        @response = response
+        freeze
+      end
+
+      def ok? = false
+    end
+
+    # -- guard results -------------------------------------------------------
+
+    class Allow
+      attr_reader :context, :allowance
+
+      # +allowance+ is "allowed", "unavailable" or "not_required" — how the
+      # decision was reached, which matters when the outage policy is fail-open.
+      def initialize(context, allowance)
+        @context = context
+        @allowance = allowance
+        freeze
+      end
+
+      def allow? = true
+    end
+
+    class Deny
+      attr_reader :reason, :response
+
+      def initialize(reason, response)
+        @reason = reason
+        @response = response
+        freeze
+      end
+
+      def allow? = false
+    end
+
+    AllowanceDecision = Struct.new(:allowed, :reason, keyword_init: true) do
+      def allowed? = allowed
+    end
+
+    ReportUsageResult = Struct.new(:recorded, :duplicate, :usage_event, keyword_init: true) do
+      def recorded? = recorded
+      def duplicate? = duplicate
+    end
+
+    # What a request will be charged for.
+    #
+    # Exactly one of +quantity+ or +max_quantity+, or neither to defer to the
+    # meter's configured per-request ceiling. Declaring both is meaningless.
+    class UsageItem
+      attr_reader :meter_slug, :quantity, :max_quantity
+
+      def initialize(meter_slug:, quantity: nil, max_quantity: nil)
+        Sellers.require_slug!(meter_slug, "meter_slug", "UsageItem")
+        if !quantity.nil? && !max_quantity.nil?
+          raise Error.new("malformed_input", operation: "UsageItem",
+                                             message: "Provide at most one of quantity or max_quantity",
+                                             meter_slug: meter_slug)
+        end
+        Sellers.require_positive_integer!(quantity, "quantity", "UsageItem") unless quantity.nil?
+        Sellers.require_positive_integer!(max_quantity, "max_quantity", "UsageItem") unless max_quantity.nil?
+
+        @meter_slug = meter_slug
+        @quantity = quantity
+        @max_quantity = max_quantity
+        freeze
+      end
+
+      def to_wire
+        wire = { "meterSlug" => @meter_slug }
+        wire["quantity"] = @quantity unless @quantity.nil?
+        wire["maxQuantity"] = @max_quantity unless @max_quantity.nil?
+        wire
+      end
+    end
+
+    # Actual usage reported alongside a successful response.
+    class SyncUsageItem
+      attr_reader :service_slug, :meter_slug, :quantity
+
+      def initialize(service_slug:, meter_slug:, quantity:)
+        Sellers.require_slug!(service_slug, "service_slug", "SyncUsageItem")
+        Sellers.require_slug!(meter_slug, "meter_slug", "SyncUsageItem")
+        Sellers.require_positive_integer!(quantity, "quantity", "SyncUsageItem")
+
+        @service_slug = service_slug
+        @meter_slug = meter_slug
+        @quantity = quantity
+        freeze
+      end
+
+      def to_wire
+        { "serviceSlug" => @service_slug, "meterSlug" => @meter_slug, "quantity" => @quantity }
+      end
+    end
+
+    class << self
+      def require_slug!(value, field_name, operation)
+        return if value.is_a?(String) && !value.empty? && value == value.strip
+
+        raise Error.new("malformed_input", operation: operation,
+                                           message: "#{field_name} must be a non-empty string without surrounding whitespace")
+      end
+
+      def require_positive_integer!(value, field_name, operation)
+        # true is not an Integer in Ruby, so unlike Python there is no bool
+        # subclass to exclude here.
+        return if value.is_a?(Integer) && value.positive?
+
+        raise Error.new("malformed_input", operation: operation,
+                                           message: "#{field_name} must be a positive integer")
+      end
+
+      def normalize_usage(usage, operation:, allow_empty:)
+        items = Array(usage)
+        if items.empty? && !allow_empty
+          raise Error.new("malformed_input", operation: operation,
+                                             message: "usage must declare at least one meter")
+        end
+
+        seen = {}
+        items.each do |item|
+          unless item.is_a?(UsageItem)
+            raise Error.new("malformed_input", operation: operation,
+                                               message: "usage entries must be UsageItem instances")
+          end
+          if seen.key?(item.meter_slug)
+            raise Error.new("malformed_input", operation: operation,
+                                               message: "Duplicate meterSlug entries are not allowed",
+                                               meter_slug: item.meter_slug)
+          end
+          seen[item.meter_slug] = true
+        end
+        items.freeze
+      end
+    end
+  end
+end

data/lib/zeroclick/sellers/errors.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ZeroClick
+  module Sellers
+    # Verification outcomes are *values*, not exceptions — a request with a bad
+    # signature is an expected event, not a programming mistake. Error is
+    # reserved for what the caller got wrong (malformed input) or what the
+    # environment did (the ZeroClick API unreachable or answering nonsense).
+    class Error < StandardError
+      DEFAULT_MESSAGES = {
+        "api_response_invalid" => "The ZeroClick API response is malformed",
+        "api_status_error" => "The ZeroClick API returned an unsuccessful status",
+        "api_transport_error" => "The ZeroClick API request failed",
+        "malformed_input" => "The SDK input is malformed",
+        "signing_secret_resolution_failed" => "The signing secret could not be resolved"
+      }.freeze
+
+      # A stable machine code. Match on this, never on the message.
+      attr_reader :code, :operation, :context
+
+      def initialize(code, operation:, message: nil, **context)
+        code = code.to_s
+        super(message || DEFAULT_MESSAGES.fetch(code))
+        @code = code
+        @operation = operation
+        @context = { operation: operation }.merge(context).freeze
+      end
+
+      def inspect
+        "#<ZeroClick::Sellers::Error code=#{@code.inspect} context=#{@context.inspect}>"
+      end
+    end
+
+    # Errors meaning "the allowance API did not give us an answer", as opposed to
+    # "the allowance API said no". Only these are subject to the configured
+    # allowance-unavailable policy; anything else propagates.
+    ALLOWANCE_API_ERROR_CODES = %w[
+      api_transport_error
+      api_status_error
+      api_response_invalid
+    ].freeze
+
+    # True when +error+ is an SDK error, optionally of a specific code.
+    def self.error?(error, code = nil)
+      error.is_a?(Error) && (code.nil? || error.code == code.to_s)
+    end
+  end
+end

data/lib/zeroclick/sellers/middleware.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+require_relative "contracts"
+require_relative "errors"
+require_relative "responses"
+
+module ZeroClick
+  module Sellers
+    # Rack middleware. Rails is a Rack app, so this covers Rails, Sinatra,
+    # Hanami, Roda and anything else Rack — one implementation, every framework.
+    #
+    # Deliberately named Middleware rather than Rack: a nested ::ZeroClick::Sellers::Rack
+    # would shadow the real ::Rack for every constant lookup inside this file.
+    #
+    # Nothing here requires the rack gem. A Rack middleware is duck-typed — an
+    # object with #call(env) returning [status, headers, body] — so the SDK adds
+    # no runtime dependency, and these are testable with a plain Hash.
+    module Middleware
+      # What a guarded request proved about its caller, in the Rack env:
+      #
+      #   zc = env["zeroclick.context"]
+      #   zc.zc_agent_id    # the buyer
+      #   zc.zc_request_id  # correlates with ZeroClick's logs; use for idempotency
+      CONTEXT_ENV_KEY = "zeroclick.context"
+
+      # Bounds the request body a guarded endpoint will read.
+      #
+      # Verification covers the whole body, so the whole body must be held in
+      # memory to check the signature. Without a ceiling that is an
+      # unauthenticated memory DoS: the attacker does not need a valid signature
+      # to make us buffer.
+      DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024 # 10 MiB
+
+      # Characters legal unencoded in a path, which must survive a re-encode.
+      PATH_SAFE = %r{[^a-zA-Z0-9/~\-._!$&'()*+,;=:@%]}
+
+      # Servers that expose the raw request target set one of these. First match
+      # wins; each carries the full target, query string included.
+      #
+      # Puma sets REQUEST_URI. Rails copies it to ORIGINAL_FULLPATH.
+      RAW_TARGET_KEYS = %w[REQUEST_URI ORIGINAL_FULLPATH].freeze
+
+      module_function
+
+      # Recover the raw, percent-encoded request target from a Rack env.
+      #
+      # Prefers the server's raw target. Falls back to re-encoding PATH_INFO,
+      # which is exact for every character except an encoded separator: a server
+      # that decodes %2F to / before we are called leaves nothing downstream
+      # able to tell that apart from a literal /. Deploy behind Puma (which sets
+      # REQUEST_URI) if your routes can contain one.
+      def path_and_query_from_env(env)
+        RAW_TARGET_KEYS.each do |key|
+          raw = env[key]
+          next if raw.nil? || raw.empty?
+
+          # Some servers give absolute-form ("http://host/path?q"). The
+          # signature covers the path and query only.
+          return raw.sub(%r{\Ahttps?://[^/]+}, "")
+        end
+
+        path = "#{env["SCRIPT_NAME"]}#{env["PATH_INFO"]}"
+        encoded = path.gsub(PATH_SAFE) { |char| format("%%%02X", char.ord) }
+        query = env["QUERY_STRING"]
+        query.nil? || query.empty? ? encoded : "#{encoded}?#{query}"
+      end
+
+      # Build a Request from a Rack env, and leave rack.input readable by the
+      # app behind us.
+      #
+      # It REPLACES rack.input rather than rewinding it. Rack 3 dropped the
+      # requirement that input be rewindable — a streaming server's input is
+      # consumed once and #rewind either raises or silently does nothing, which
+      # hands the application an empty body. Since verification must read the
+      # whole body anyway, handing back a fresh stream over those same bytes is
+      # both correct and free.
+      #
+      # Returns [request, too_large].
+      def request_from_env(env, max_body_bytes: DEFAULT_MAX_BODY_BYTES)
+        headers = {}
+        env.each do |key, value|
+          next unless key.is_a?(String) && key.start_with?("HTTP_")
+
+          headers[key[5..].tr("_", "-").downcase] = value
+        end
+        headers["content-type"] = env["CONTENT_TYPE"] if env["CONTENT_TYPE"]
+        headers["content-length"] = env["CONTENT_LENGTH"] if env["CONTENT_LENGTH"]
+
+        input = env["rack.input"]
+        body = +""
+        if input
+          # Read one byte past the ceiling so an over-size body is detected
+          # rather than silently truncated into an invalid signature.
+          body = input.read(max_body_bytes + 1) || +""
+          body = body.dup.force_encoding(Encoding::BINARY)
+          env["rack.input"] = StringIO.new(body)
+        end
+
+        [
+          Request.new(
+            method: env["REQUEST_METHOD"] || "GET",
+            path_and_query: path_and_query_from_env(env),
+            headers: headers,
+            body: body
+          ),
+          body.bytesize > max_body_bytes
+        ]
+      end
+
+      # Shared wire-up. Subclasses decide what guarding means.
+      class Base
+        # +seller+ may be a client, a callable returning one, or omitted.
+        #
+        # Omitting it is the Rails path, and the reason it is optional at all:
+        # `config.middleware.use` evaluates its arguments in the Application
+        # class body, which runs BEFORE the Railtie initializer that reads
+        # `config.zeroclick`. Passing `seller: ZeroClick::Sellers.seller` there
+        # raises on boot, every time. Omit it and the process-wide client is
+        # resolved on the first request instead, by which point configuration
+        # exists.
+        def initialize(app, service_slug:, seller: nil, max_body_bytes: DEFAULT_MAX_BODY_BYTES)
+          @app = app
+          @seller_source = seller
+          @service_slug = service_slug
+          @max_body_bytes = max_body_bytes
+        end
+
+        def call(env)
+          request, too_large = Middleware.request_from_env(env, max_body_bytes: @max_body_bytes)
+          # Before verification on purpose: an unauthenticated caller must not be
+          # able to make us buffer more than the ceiling.
+          return to_rack(Response.json({ "error" => "payload_too_large" }, status: 413)) if too_large
+
+          decision = decide(request)
+          return to_rack(decision.response) unless decision.allow?
+
+          env[CONTEXT_ENV_KEY] = decision.context
+          respond(env, decision)
+        end
+
+        private
+
+        # Resolved once, on first use rather than at wire-up. See #initialize.
+        def seller
+          @seller ||= if @seller_source.nil?
+                        Sellers.seller
+                      elsif @seller_source.respond_to?(:call)
+                        @seller_source.call
+                      else
+                        @seller_source
+                      end
+        end
+
+        # Default: the guard decided nothing further is owed.
+        def respond(env, _decision)
+          @app.call(env)
+        end
+
+        def to_rack(response)
+          [response.status, response.headers.dup, [response.body]]
+        end
+      end
+
+      # Guards a billable endpoint: verifies the signature, confirms the buyer
+      # can pay, and — if the app responds 2xx — reports the usage.
+      #
+      #   use ZeroClick::Sellers::Middleware::Meter,
+      #       seller: SELLER, service_slug: "extractor",
+      #       usage: [ZeroClick::Sellers::UsageItem.new(meter_slug: "requests", quantity: 1)]
+      #
+      # Inside the app, the request body still reads normally: verification
+      # consumes rack.input and this replaces it with a fresh stream over the
+      # same bytes.
+      #
+      # Every usage item must carry an explicit quantity, and it refuses the
+      # others at wire-up. Meter settles usage automatically from what it
+      # declared, so an item with only a max_quantity ceiling — or with neither
+      # quantity nor max_quantity — has no settled amount, and inventing one
+      # would silently mis-bill a delivered 200. That is the exact failure this
+      # SDK exists to prevent, so it fails when you build the middleware rather
+      # than in production: declare a fixed quantity here and report the
+      # variable part with Client#report_usage.
+      class Meter < Base
+        def initialize(app, service_slug:, usage:, seller: nil, plan_slug: nil,
+                       max_body_bytes: DEFAULT_MAX_BODY_BYTES)
+          super(app, seller: seller, service_slug: service_slug, max_body_bytes: max_body_bytes)
+          @usage = Sellers.normalize_usage(usage, operation: "Middleware::Meter", allow_empty: false)
+          @plan_slug = plan_slug
+
+          # Meter settles usage from what it declared, so every item must carry
+          # a definite quantity. An item that does not — a max_quantity ceiling,
+          # or one that defers to the meter's configured per-request default —
+          # has no settled amount here, and inventing one would silently
+          # mis-bill a delivered 200. That is the exact failure this SDK exists
+          # to prevent, so it fails at wire-up rather than in production.
+          indefinite = @usage.find { |item| item.quantity.nil? }
+          return unless indefinite
+
+          raise Error.new("malformed_input", operation: "Middleware::Meter",
+                                             meter_slug: indefinite.meter_slug,
+                                             message: "Middleware::Meter needs an explicit quantity on every usage item, and " \
+                                                      "#{indefinite.meter_slug} has none. It settles usage from what it " \
+                                                      "declares, so an item carrying a max_quantity ceiling — or neither " \
+                                                      "quantity nor max_quantity — has no settled amount to report. Declare a " \
+                                                      "fixed quantity here and report the variable part with Client#report_usage.")
+        end
+
+        private
+
+        def decide(request)
+          seller.guard(request, service_slug: @service_slug, usage: @usage, plan_slug: @plan_slug)
+        end
+
+        def respond(env, _decision)
+          status, headers, body = @app.call(env)
+          # Only a delivered response is billed. A 4xx/5xx did not do the work.
+          return [status, headers, body] unless (200..299).cover?(status.to_i)
+
+          headers = headers.dup
+          headers["zc-usage"] = Responses.usage_header(
+            @usage.map do |item|
+              SyncUsageItem.new(
+                service_slug: @service_slug,
+                meter_slug: item.meter_slug,
+                # Never nil: the constructor refused every item without one.
+                quantity: item.quantity
+              )
+            end
+          )
+          [status, headers, body]
+        end
+      end
+
+      # Guards a free endpoint that must still know which buyer is calling — a
+      # limits or account route. Makes no network call.
+      class Identify < Base
+        private
+
+        def decide(request)
+          seller.guard_identity(request, service_slug: @service_slug)
+        end
+      end
+    end
+  end
+end

data/lib/zeroclick/sellers/railtie.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+require_relative "../sellers"
+
+module ZeroClick
+  module Sellers
+    # Rails ergonomics on top of the Rack middleware.
+    #
+    # Deliberately thin, and deliberately NOT loaded by `require "zeroclick/sellers"`
+    # — the gem must stay usable from Sinatra, Hanami and plain Rack without
+    # Rails on the load path. Rails apps opt in:
+    #
+    #   # config/application.rb
+    #   require "zeroclick/sellers/railtie"
+    #
+    #   config.zeroclick.api_key = ENV.fetch("ZEROCLICK_API_KEY")
+    #   config.zeroclick.signing_secrets = ZeroClick::Sellers.secrets_from_env
+    #
+    # Then guard routes in the usual Rails way:
+    #
+    # Note there is no `seller:` — `config.middleware.use` evaluates its
+    # arguments in the Application class body, which runs BEFORE the
+    # initializer below, so no client exists yet. The middleware resolves one
+    # on the first request instead.
+    #
+    #   config.middleware.use ZeroClick::Sellers::Middleware::Meter,
+    #     service_slug: "extractor",
+    #     usage: [ZeroClick::Sellers::UsageItem.new(meter_slug: "requests", quantity: 1)]
+    #
+    # Inside a controller, the verified caller is on the request env:
+    #
+    #   zc = request.env["zeroclick.context"]
+    class Railtie < ::Rails::Railtie
+      config.zeroclick = ActiveSupport::OrderedOptions.new
+
+      # Hands the app's config to the gem. The client itself is built lazily by
+      # ZeroClick::Sellers.seller, so boot does not depend on credentials being
+      # present in, say, a test or asset-precompile environment.
+      initializer "zeroclick.seller" do |app|
+        ZeroClick::Sellers.configure(**app.config.zeroclick.to_h.compact)
+      end
+    end
+  end
+end

data/lib/zeroclick/sellers/responses.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "contracts"
+require_relative "errors"
+
+module ZeroClick
+  module Sellers
+    # The exact responses ZeroClick expects a seller to return.
+    module Responses
+      module_function
+
+      # The 402 body ZeroClick answers with a payment challenge.
+      #
+      # An empty +usage+ is meaningful, not a mistake: it is the free
+      # identity-scoped refusal, which the proxy answers with a $0 identity
+      # challenge and retries with zc-agent-id attached.
+      def payment_required(service_slug:, usage:, plan_slug: nil)
+        items = Sellers.normalize_usage(usage, operation: "payment_required", allow_empty: true)
+        body = { "error" => "payment_required", "serviceSlug" => service_slug }
+        body["planSlug"] = plan_slug unless plan_slug.nil?
+        # Key order matters only for readability; the proxy parses by name.
+        body["usage"] = items.map(&:to_wire)
+        Response.json(body, status: 402)
+      end
+
+      def invalid_zeroclick_signature
+        Response.json({ "error" => "invalid_zeroclick_signature" }, status: 401)
+      end
+
+      def allowance_unavailable
+        Response.json({ "error" => "allowance_unavailable" }, status: 503)
+      end
+
+      # Build the zc-usage header value.
+      #
+      # Returned as a string rather than applied to a response object, so each
+      # adapter can attach it to its own framework's response without the SDK
+      # ever having to reconstruct one.
+      def usage_header(usage)
+        items = Array(usage)
+        items.each do |item|
+          unless item.is_a?(SyncUsageItem)
+            raise Error.new("malformed_input", operation: "usage_header",
+                                               message: "usage entries must be SyncUsageItem instances")
+          end
+        end
+        JSON.generate(items.map(&:to_wire))
+      end
+
+      # Attach reported usage to a successful response.
+      def with_usage(response, usage)
+        Response.new(
+          status: response.status,
+          body: response.body,
+          headers: response.headers.merge("zc-usage" => usage_header(usage))
+        )
+      end
+    end
+  end
+end