openreceive-server 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 815016906827bfc710461c1d68490612651e561647e844490366a835efd4ec5b
+  data.tar.gz: 35be8788e0f8bbcc83b2fdf6771e0bbce272267ef6c76151b739e23639ff56fe
+SHA512:
+  metadata.gz: 96c1bbbea13c33b366f6f09a30104fa3340b49500ee6ecfd97475155c0b280981a534ba20df800b362d193cdc6cd11c4bbe6c16a6c8bd20e9e8083b6f0a5d9af
+  data.tar.gz: cfb1f18622c9e424e0f10754da453c7be4300137a204f8e6742cdd38f37587b37afa782a4b6bbc4bf6e55cc5e51727f2d6d9f459806fb4a5db5a8741efd00bdd

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.2.1 - 2026-08-24
+
+The Ruby gems release in lockstep with the npm workspace version. The full
+release narrative lives in the repository-root
+[CHANGELOG](https://github.com/openreceive/openreceive/blob/master/CHANGELOG.md);
+entries here are scoped to this gem.
+
+- Packaging only: `npm run release:gem:build` now names the built `.gem` with
+  the version RubyGems actually mints, so prerelease versions build and push.
+
+## 0.1.1 - 2026-08-18
+
+- First packaged release of `openreceive-server`: the storage-free Service
+  mirroring the Node engine and the framework-agnostic Rack app implementing
+  the shipped HTTP routes.
+- FixedFloat swap provider with LSC auto-wiring
+  (`LSC_URI_PRIMARY`/`LSC_URI_BACKUP`), amount-aware swap options, and
+  primary/backup failover; the Service defaults to the built-in live price
+  feed when the host injects no provider.
+- `payments/check` whitelists public transaction fields (preimage/invoice
+  never reach the payer); 405/503/500 wire parity with the Node engine; the
+  rate limiter buckets IPv6 clients by /64.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenReceive contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,46 @@
+# openreceive-server
+
+Storage-free Ruby service and Rack handler. Configure a receive-only NWC client. The host
+authorizes requests, resolves order amounts, commits payment hashes before responding, and
+consumes at-least-once verified payment events by hash. The service refuses to start when the
+NWC connection advertises spend methods (`pay_invoice`, `multi_pay_invoice`,
+`pay_keysend`, `multi_pay_keysend`) unless
+`allow_spend_capable_wallet` or `OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC` overrides it; the
+shared reconciliation decision table lives in `OpenReceive::Server::Reconciliation`.
+
+## Minimal Rack example
+
+```ruby
+# config.ru — run with: rackup
+require "openreceive/server"
+
+service = OpenReceive::Server::Service.new(nwc_client: MyNwcClient.new)
+
+run OpenReceive::Server::RackApp.new(
+  service: service,
+  # context is a Hash: context[:action] is the route name ("checkout.create",
+  # "payment.check", …), context[:request] is the Rack env, and
+  # context[:resource] is { reference:, payment_hash: } copied from the
+  # payer's body — it names an order, it does not prove ownership.
+  # Return true to allow, false for a 403.
+  authorize: ->(context) { my_policy_allows?(context) },
+  resolve_checkout: lambda do |action:, request:, reference:, input:, pay_in_asset: nil|
+    order = MyOrders.find(reference) or raise OpenReceive::Server::NotFoundError, "Unknown reference."
+    { "amount" => { "currency" => "USD", "value" => order.total } }
+    # Return payment_hash/checkout/swap_data for committed attempts on
+    # non-create actions; see the Rails engine for a full repository.
+  end,
+  on_checkout_created: ->(reference:, payment_hash:, checkout:, swap_data: nil, client_ip: nil) {
+    MyPayments.commit!(reference:, payment_hash:, checkout:, swap_data:, client_ip:)
+  },
+  on_paid: ->(event) { MyPayments.settle_once!(event) }
+)
+```
+
+Rack hosts own attempt persistence and replay-safe settlement (the Rails
+engine ships both; see `openreceive-rails`). Rack hosts that want opportunistic
+settlement run their own gated pass from middleware: feed the pending attempts
+they store to `service.reconcile_payments({ attempts:, max_pages:, deadline: })`
+and apply the per-hash results through `on_paid` — `RackApp` deliberately has
+no built-in hook, and the durable-gate convenience (`OpenReceive.maybe_reconcile!`)
+ships only with the Rails engine.

data/lib/openreceive/server/client_ip.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  module Server
+    # Client-IP bucketing shared by rate limiting and attempt-row stamping.
+    # Ports the JS clientIpBucket exactly: the same input string
+    # must produce the same bucket string in both engines (mirrored tests in
+    # tests/rate-limit.test.mjs and the Ruby server tests).
+    #
+    # - IPv4-mapped IPv6 (`::ffff:a.b.c.d`) collapses to the plain IPv4, so
+    #   the same client never gets two independent budgets.
+    # - IPv6 buckets to its /64 (`2001:db8:1:2::/64`): privacy extensions
+    #   rotate the low 64 bits freely, so per-address budgets would hand every
+    #   IPv6 payer an unlimited stream of fresh budgets.
+    # - IPv4 and already-bucketed values pass through unchanged (idempotent).
+    # - Unparsable input passes through as-is — an odd value still gets SOME
+    #   consistent bucket rather than disabling the limit.
+    module ClientIp
+      module_function
+
+      # nil/empty-safe wrapper mirroring the JS handler's extractClientIp:
+      # no attributable IP stays nil (the limiter fails open); anything else
+      # is normalized into the bucket that is both stored and counted.
+      def attributed(raw)
+        value = raw.to_s
+        return nil if value.strip.empty?
+        bucket(value)
+      end
+
+      def bucket(ip)
+        value = ip.to_s.strip.downcase
+        value = value.delete_prefix("::ffff:") if value.start_with?("::ffff:") && value.include?(".")
+        return value unless value.include?(":")
+        return value if value.end_with?("/64")
+        address = value.split("%", -1).first || ""
+        hextets = expand_ipv6(address)
+        return value if hextets.nil?
+        "#{hextets.first(4).join(':')}::/64"
+      end
+
+      def expand_ipv6(value)
+        parts = value.split("::", -1)
+        return nil if parts.length > 2 || value.empty?
+        head = hextets_of(parts[0] || "")
+        tail = parts.length == 2 ? hextets_of(parts[1] || "") : []
+        return nil if head.nil? || tail.nil?
+        return head.length == 8 ? head : nil if parts.length == 1
+        missing = 8 - head.length - tail.length
+        return nil if missing < 1
+        head + Array.new(missing, "0") + tail
+      end
+
+      def hextets_of(segment)
+        return [] if segment == ""
+        groups = []
+        segment.split(":", -1).each do |group|
+          if /\A[0-9a-f]{1,4}\z/.match?(group)
+            groups << group.sub(/\A0+(?=.)/, "")
+          elsif /\A\d{1,3}(\.\d{1,3}){3}\z/.match?(group)
+            octets = group.split(".").map { |octet| Integer(octet, 10) }
+            return nil if octets.any? { |octet| octet > 255 }
+            # Embedded IPv4 tail expands to two hextets.
+            groups << (((octets[0] << 8) | octets[1]).to_s(16))
+            groups << (((octets[2] << 8) | octets[3]).to_s(16))
+          else
+            return nil
+          end
+        end
+        groups
+      end
+    end
+  end
+end

data/lib/openreceive/server/config.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "openreceive/server/swap"
+
+module OpenReceive
+  module Server
+    class Config
+      attr_reader :nwc, :lsc_connections
+
+      def self.load(env: ENV)
+        new(env: env)
+      end
+
+      def initialize(env: ENV)
+        @nwc = clean(env["NWC_URI"])
+        @lsc_connections = OpenReceive::Server::LscUri.read_environment(env)
+        freeze
+      end
+
+      # FixedFloat-compatible providers for the parsed LSC connections, in
+      # env order (primary first, backup second) — the same providers the
+      # Service auto-builds when constructed without swap_providers.
+      def swap_providers(http: nil, now: nil)
+        OpenReceive::Server::Swap.providers_from_connections(@lsc_connections, http: http, now: now)
+      end
+
+      def to_h
+        {
+          "NWC_URI" => @nwc.nil? ? nil : "[REDACTED]",
+          "LSC_URI_connections" => @lsc_connections.length
+        }
+      end
+
+      def inspect
+        "#<OpenReceive::Server::Config storage=none nwc=#{@nwc.nil? ? 'missing' : '[REDACTED]'}>"
+      end
+
+      private
+
+      def clean(value)
+        text = value.to_s.strip
+        text.empty? ? nil : text
+      end
+    end
+  end
+end

data/lib/openreceive/server/errors.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module OpenReceive
+  module Server
+    # Server-layer errors. Every error carries
+    # #status and #code so the Rack layer can map to an error.schema.json body directly.
+
+    # Generic service error carrying an explicit HTTP status + canonical code,
+    # the Ruby analogue of the JS ServiceError. Used where the JS
+    # service raises serviceError(status, code, message) — e.g. the swap flows
+    # — so both engines put the same status/code/message on the wire.
+    class ServiceError < StandardError
+      attr_reader :status, :code, :retryable, :details
+
+      def initialize(status, code, message, retryable: nil, details: nil)
+        super(message)
+        @status = status
+        @code = code
+        @retryable = retryable
+        @details = details
+      end
+    end
+
+    # 400 — the request body/params were malformed or violated a contract rule.
+    class ValidationError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "Invalid request.")
+        super(message)
+        @status = 400
+        @code = "INVALID_REQUEST"
+      end
+    end
+
+    # 403 — the host application did not authorize this request. FORBIDDEN,
+    # not UNAUTHORIZED: that name belongs to the NIP-47 wallet layer.
+    class ForbiddenError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "Forbidden.")
+        super(message)
+        @status = 403
+        @code = "FORBIDDEN"
+      end
+    end
+
+    # 404 — the order or checkout was not found.
+    class NotFoundError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "Not found.")
+        super(message)
+        @status = 404
+        @code = "NOT_FOUND"
+      end
+    end
+
+    class ConflictError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "Conflict.")
+        super(message)
+        @status = 409
+        @code = "CONFLICT"
+      end
+    end
+
+    # 405 — a known OpenReceive path called with the wrong HTTP method.
+    # Mirrors the JS router exactly: INVALID_REQUEST, no Allow header.
+    class MethodNotAllowedError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "This OpenReceive route does not support that HTTP method.")
+        super(message)
+        @status = 405
+        @code = "INVALID_REQUEST"
+      end
+    end
+
+    # 500 INTERNAL raised deliberately (for example: the host resolved an
+    # order without an amount). Unlike an unexpected exception, the message is
+    # payer-safe by construction and stays on the wire — mirroring the JS
+    # handler's HttpError(500, "INTERNAL", ...).
+    class InternalHostError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "Internal server error.")
+        super(message)
+        @status = 500
+        @code = "INTERNAL"
+      end
+    end
+
+    # 503 — infrastructure failed to persist the payment attempt (database
+    # down, host hook bug). Mirrors the JS handler's commit(): a retryable
+    # INTERNAL, never a payer-blaming conflict; the invoice is still withheld.
+    class HostPersistenceError < StandardError
+      attr_reader :status, :code, :retryable
+
+      def initialize(message = "The host could not persist this payment attempt; " \
+                               "payer instructions were withheld. Please retry.")
+        super(message)
+        @status = 503
+        @code = "INTERNAL"
+        @retryable = true
+      end
+    end
+
+    # 413 — contract bodies are tiny; anything larger is rejected before any
+    # host callback runs (mirrors the JS handler's pre-auth body cap).
+    class PayloadTooLargeError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "Request body is too large.")
+        super(message)
+        @status = 413
+        @code = "INVALID_REQUEST"
+      end
+    end
+
+    # 415 — the body-bearing routes accept `application/json` only. This is the
+    # CSRF-equivalent on cookie-authenticated mounts: a cross-site HTML form
+    # cannot set a JSON content type, and a cross-origin fetch that does is
+    # non-simple (CORS-preflighted, which the library never grants), so a
+    # forgery can never reach `authorize` with the victim's session. Rejected
+    # before authorize, like the body cap. Mirrors the JS handler.
+    class UnsupportedMediaTypeError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "Request content type must be application/json.")
+        super(message)
+        @status = 415
+        @code = "INVALID_REQUEST"
+      end
+    end
+
+    # 429 — the payer exceeded the configured invoice-creation budget. Mirrors
+    # the JS handler: RATE_LIMITED with retryable: true so clients back off
+    # and retry instead of treating it as a permanent failure, plus a
+    # `Retry-After` hint (seconds) emitted as a response header.
+    class RateLimitedError < StandardError
+      attr_reader :status, :code, :retryable, :retry_after_seconds
+
+      def initialize(message = "Too many requests.")
+        super(message)
+        @status = 429
+        @code = "RATE_LIMITED"
+        @retryable = true
+        @retry_after_seconds = 60
+      end
+    end
+
+    # 501 — the host has not configured the capability this route needs
+    # (for example GET /rates without a price provider).
+    class NotImplementedHttpError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "Not implemented.")
+        super(message)
+        @status = 501
+        @code = "NOT_IMPLEMENTED"
+      end
+    end
+
+    # Wallet/relay failure normalized per the shared error-normalization
+    # vectors. Carries the canonical code and retryable flag so browsers can
+    # distinguish "retry" from "bug" against Rails exactly as against Node.
+    class WalletFailureError < StandardError
+      attr_reader :status, :code, :retryable, :details
+
+      def initialize(normalized)
+        super(normalized.fetch("message"))
+        @code = normalized.fetch("code")
+        @retryable = normalized.fetch("retryable", false)
+        @details = normalized["details"]
+        @status = @retryable ? 503 : 502
+      end
+    end
+
+    # 502 — the wallet responded but violated the receive-checkout contract
+    # (for example minting an invoice that ignores the requested expiry).
+    class WalletContractError < StandardError
+      attr_reader :status, :code
+
+      def initialize(message = "Wallet violated the receive-checkout contract.")
+        super(message)
+        @status = 502
+        @code = "UNSUPPORTED_METHOD"
+      end
+    end
+
+    # Boot-time refusal: the connection offered an info method but preflight
+    # could not clear it — the read failed, the wallet cannot receive, or it
+    # speaks no encryption mode we support. Booting blind would defer the
+    # failure to the first customer checkout, so preflight fails closed
+    # (mirrors the JS WALLET_PREFLIGHT_FAILED config error).
+    class WalletPreflightError < StandardError
+      def initialize(reason)
+        super(
+          "OpenReceive wallet preflight failed: #{reason} Use a receive-only " \
+          "NWC connection advertising make_invoice and list_transactions."
+        )
+      end
+    end
+
+    # Boot-time refusal: the configured NWC connection advertises spend methods.
+    # OpenReceive is receive-only; a spend-capable code in a receive deployment
+    # is a live theft risk, so preflight fails closed instead of booting.
+    class SpendCapableWalletError < StandardError
+      def initialize(methods)
+        super(
+          "The configured NWC connection advertises spend methods " \
+          "(#{Array(methods).join(', ')}). OpenReceive is receive-only; use a " \
+          "receive-only NWC code, or override explicitly with " \
+          "config.allow_spend_capable_wallet = true or " \
+          "OPENRECEIVE_ALLOW_SPEND_CAPABLE_NWC=1."
+        )
+      end
+    end
+  end
+end

data/lib/openreceive/server/lsc_uri.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module OpenReceive
+  module Server
+    module LscUri
+      SCHEME = "lightning+swapconnect"
+      ENV_NAMES = %w[LSC_URI_PRIMARY LSC_URI_BACKUP].freeze
+      QUERY_PARAMETERS = %w[key secret].freeze
+      MAX_URI_LENGTH = 8192
+      MAX_CREDENTIAL_LENGTH = 2048
+
+      module_function
+
+      def parse(value)
+        input = credential(value, "LSC URI", MAX_URI_LENGTH)
+        uri = URI.parse(input)
+        raise ArgumentError, "LSC URI must use #{SCHEME}://." unless uri.scheme == SCHEME
+        raise ArgumentError, "LSC URI must not use URI userinfo." unless uri.userinfo.nil?
+        raise ArgumentError, "LSC URI requires a provider hostname." if uri.host.to_s.empty?
+        raise ArgumentError, "LSC URI must not contain a fragment." unless uri.fragment.nil?
+        raise ArgumentError, "LSC URI query encoding is invalid." if uri.query.to_s.match?(/%(?![0-9a-f]{2})/i)
+
+        begin
+          pairs = URI.decode_www_form(uri.query.to_s)
+        rescue ArgumentError
+          raise ArgumentError, "LSC URI query encoding is invalid."
+        end
+        unsupported = pairs.map(&:first).find { |name| !QUERY_PARAMETERS.include?(name) }
+        raise ArgumentError, "LSC URI contains an unsupported query parameter." unless unsupported.nil?
+
+        key = credential(single_parameter(pairs, "key"), "LSC URI key", MAX_CREDENTIAL_LENGTH)
+        secret = credential(single_parameter(pairs, "secret"), "LSC URI secret", MAX_CREDENTIAL_LENGTH)
+        path = normalize_path(uri.path)
+        port = uri.port.nil? ? "" : ":#{uri.port}"
+
+        {
+          "uri_protocol" => "#{SCHEME}:",
+          "base_url" => "https://#{uri.host}#{port}#{path}",
+          "provider_id" => provider_id(uri),
+          "key" => key,
+          "secret" => secret
+        }.freeze
+      rescue URI::InvalidURIError
+        raise ArgumentError, "LSC URI is not a valid absolute URI."
+      end
+
+      def read_environment(env = ENV)
+        provider_ids = {}
+        ENV_NAMES.each_with_object([]) do |name, connections|
+          value = env[name].to_s.strip
+          next if value.empty?
+
+          connection = parse(value)
+          id = connection.fetch("provider_id")
+          raise ArgumentError, "#{name} duplicates another LSC provider id." if provider_ids[id]
+
+          provider_ids[id] = true
+          connections << connection
+        rescue ArgumentError => e
+          raise ArgumentError, "#{name} is invalid: #{e.message}"
+        end.freeze
+      end
+
+      def single_parameter(pairs, name)
+        values = pairs.each_with_object([]) do |(key, value), matches|
+          matches << value if key == name
+        end
+        raise ArgumentError, "LSC URI requires exactly one #{name} parameter." unless values.length == 1
+
+        values.first
+      end
+      private_class_method :single_parameter
+
+      def credential(value, label, maximum_length)
+        normalized = value.to_s.strip
+        raise ArgumentError, "#{label} must not be empty." if normalized.empty?
+        raise ArgumentError, "#{label} is too long." if normalized.length > maximum_length
+
+        normalized
+      end
+      private_class_method :credential
+
+      def normalize_path(path)
+        return "/" if path.to_s.empty? || path == "/"
+
+        path.end_with?("/") ? path : "#{path}/"
+      end
+      private_class_method :normalize_path
+
+      def provider_id(uri)
+        path = uri.path.to_s.split("/").reject(&:empty?).join("-")
+        port = uri.port.nil? ? "" : "-#{uri.port}"
+        raw = "#{uri.host}#{port}#{path.empty? ? '' : "-#{path}"}"
+              .downcase.gsub(/[^a-z0-9_-]+/, "-").gsub(/\A-+|-+\z/, "")[0, 64]
+        raise ArgumentError, "LSC URI could not derive a provider id." if raw.to_s.empty?
+
+        raw
+      end
+      private_class_method :provider_id
+    end
+  end
+end

data/lib/openreceive/server/rack_app.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+require "openreceive/server/client_ip"
+require "openreceive/server/request_handler"
+
+module OpenReceive
+  module Server
+    class RackApp
+      # Route paths (method-independent), used to answer a known path called
+      # with the wrong method with 405 instead of 404 — mirrors the JS router.
+      KNOWN_PATHS = [
+        "/checkouts/prepare", "/checkouts", "/payments/check", "/swaps/quote",
+        "/swaps", "/swaps/status", "/swaps/refunds", "/rates"
+      ].freeze
+
+      def initialize(service:, authorize:, resolve_checkout:, on_checkout_created:, on_paid:,
+                     rate_limit: nil, client_ip: nil, prefix: "/openreceive")
+        @prefix = prefix.to_s.chomp("/")
+        raw_client_ip = client_ip || ->(request) { request.is_a?(Hash) ? request["REMOTE_ADDR"] : nil }
+        @handler = RequestHandler.new(
+          service: service,
+          authorize: authorize,
+          resolve_checkout: resolve_checkout,
+          on_checkout_created: on_checkout_created,
+          on_paid: on_paid,
+          rate_limit: rate_limit,
+          # Stamped IPs are normalized into the same bucket the limiter counts
+          # with (IPv6 /64, v4-mapped collapsed) — mirrors the JS handler.
+          client_ip: ->(request) { ClientIp.attributed(raw_client_ip.call(request)) }
+        )
+      end
+
+      def call(env)
+        # Always server-generated (matches JS): a client-supplied X-Request-Id
+        # is unvalidated content and must not be reflected into headers/logs.
+        request_id = "req_#{SecureRandom.uuid}"
+        path = env["PATH_INFO"].to_s
+        return response(@handler.error_response(NotFoundError.new("No OpenReceive route matched this method and path."), request_id)) unless path.start_with?(@prefix)
+        relative = path.delete_prefix(@prefix).sub(%r{/\z}, "")
+        # The body is read only after a route matches (an unknown path stays a
+        # 404 no matter how large the body is), mirroring the JS dispatch order.
+        triple = case [env["REQUEST_METHOD"], relative]
+                 when ["POST", "/checkouts/prepare"] then @handler.prepare_checkout(raw_body: read_body(env), request: env, request_id: request_id)
+                 when ["POST", "/checkouts"] then @handler.create_checkout(raw_body: read_body(env), request: env, request_id: request_id)
+                 when ["POST", "/payments/check"] then @handler.check_payment(raw_body: read_body(env), request: env, request_id: request_id)
+                 when ["POST", "/swaps/quote"] then @handler.quote_swap(raw_body: read_body(env), request: env, request_id: request_id)
+                 when ["POST", "/swaps"] then @handler.create_swap(raw_body: read_body(env), request: env, request_id: request_id)
+                 when ["POST", "/swaps/status"] then @handler.get_swap(raw_body: read_body(env), request: env, request_id: request_id)
+                 when ["POST", "/swaps/refunds"] then @handler.refund_swap(raw_body: read_body(env), request: env, request_id: request_id)
+                 when ["GET", "/rates"] then @handler.read_rates(query_string: env["QUERY_STRING"], request: env, request_id: request_id)
+                 else @handler.error_response(unmatched_route_error(relative), request_id)
+                 end
+        response(triple)
+      rescue StandardError => e
+        response(@handler.error_response(e, request_id))
+      end
+
+      private
+
+      # 405 INVALID_REQUEST for a known path with the wrong method, 404
+      # NOT_FOUND otherwise — status, code, and messages match the JS router
+      # (which sets no Allow header).
+      def unmatched_route_error(relative)
+        if KNOWN_PATHS.include?(relative)
+          MethodNotAllowedError.new
+        else
+          NotFoundError.new("No OpenReceive route matched this method and path.")
+        end
+      end
+
+      # Pre-auth body cap, mirroring the JS readJsonBody: an over-declared
+      # Content-Length is rejected before any read, and the read itself stops
+      # one byte past the cap — an unauthenticated payer can never stream an
+      # unbounded (chunked) body into memory.
+      def read_body(env)
+        input = env["rack.input"]
+        return "" if input.nil?
+        raise PayloadTooLargeError if env["CONTENT_LENGTH"].to_i > RequestHandler::MAX_BODY_BYTES
+        value = input.read(RequestHandler::MAX_BODY_BYTES + 1) || ""
+        input.rewind if input.respond_to?(:rewind)
+        raise PayloadTooLargeError if value.bytesize > RequestHandler::MAX_BODY_BYTES
+        value
+      end
+
+      def response(triple)
+        status, headers, body = triple
+        [status, headers, [JSON.generate(body)]]
+      end
+    end
+  end
+end