portage-ucp 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c0a19a01df5cf624b7e08f79b9a8e21a8d9d348ce68469c932233f77e8f65b7
-  data.tar.gz: ab6342cc1a9045662a0caba73858f2d1fc97f253c2df1593ab1ca629cc870055
+  metadata.gz: 7888232b409966ef29fae287d17d6af418dd676e12ad53a7ef7d30d7178f6ae6
+  data.tar.gz: e967bbb103d6911ca4ed8d4fb1204687cd8a2c7a51e3ab7675db5420b7eb0623
 SHA512:
-  metadata.gz: 830f760577b2d590337cb38eced77dc7d8a4b102f0e946dd6e8fcfce24078ebb754334615707217ce6b2e9ce1f966b45e830c6dfd14e7dd220515a72644375b8
-  data.tar.gz: 28139b13e1cc2716f16be0b3bfe35182e9bd48b5508a5e61f4bde1a164e93caf6d9b525d87def91153fea157b789b591fdb179251eb11d377a749b1eb6d1d413
+  metadata.gz: 3f78f566ac2ee41da063ae9a96a658707bf481f8f9ee791e288fc2d78ce0325ed147c2423a137b06350b3ddb5f64f09c17a5ba6967894e7795ef72c90d6f1384
+  data.tar.gz: 61a0ec7f01125fb8da2e0eb74fdc03b50d4fc94e38a3863e8366b1932cc871ab3787253d3199845a4a18a1902245fb7b2d3ca336b2bd896a82c4ce011d187f5b

data/CHANGELOG.md

@@ -4,6 +4,60 @@ All notable changes to this project are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
 pre-1.0, so APIs may still shift between minor versions.
 
+## [0.10.0] - 2026-09-25
+
+- **Proxy support** (`docs/plans/proxy-support.md` Phases 1 and 3).
+  `Support::Connection.start(uri, route:, proxy: ProxyConfig.current, ...)`
+  replaces every raw `Net::HTTP.start` call site. It resolves
+  `HTTPS_PROXY`/`https_proxy` for https targets (Net::HTTP's own `:ENV`
+  mode never read them) and honors `NO_PROXY`. It also supports
+  `ProxyConfig` routes and named chains: `:forward` proxies (natively, or
+  through a hand-rolled CONNECT tunnel when `proxy_headers` are set or
+  hops are chained), `:gateway` mode, `ca_file` and timeout overrides.
+  A hop failure raises `Portage::Ucp::ProxyError` naming the hop and the
+  redacted proxy host. `ProxyConfig::Profile` refuses `Authorization`,
+  `User-Agent`, `X-Shopify-*-Access-Token` and `X-Payment-Token` in
+  proxy/forward headers. `Support::HttpClient#json_request` takes
+  `route:` (default `:platform`); `Check` uses `:probe` and
+  `Support::TokenExchange` uses `:payment`.
+- `Rack::ForwardedRequest`, a fail-closed helper that trusts
+  `X-Forwarded-*`/`Forwarded` only from a configured `trusted_proxies`
+  list, resolves the right-most untrusted hop as the client IP, and lets
+  `X-Forwarded-Host` replace an endpoint's origin only for a trusted peer
+  and an allowlisted host. `Rack::WebhookEndpoint` uses it.
+- `Support::PassthroughContext`, a fiber-local scope that carries an
+  inbound request's allowlisted, trusted-peer-only headers and
+  `Forwarded`/`X-Forwarded-For` chain onto the outbound
+  `Support::Connection` calls made while serving it.
+- Adapter and CLI gems that call `Support::Connection` need `~> 0.10`.
+
+- `Support::TransactionLog#reserve`/`#complete` accept a fixed allowlist of
+  optional attributes (`OPTIONAL_ATTRIBUTES`: `settled_by`, `handoff_reason`,
+  `store_url`, `expires_at`, `resolution`, `counts_toward_caps`) beyond
+  their existing keywords, raising `ArgumentError` on anything else — the
+  extension point `docs/plans/handoff-reconcile.md`'s Phase 1/2 use to
+  record and settle a shopper-completed hand-off as a transaction record,
+  not a parallel path. `#completed_since` now excludes
+  `counts_toward_caps: false` records (Phase 2's `warn` spend mode); a
+  record with neither field set reads exactly as before. No change to any
+  existing caller.
+- Fix: `Support::HttpClient#json_request` opened every request with no
+  `open_timeout`/`read_timeout` of its own, so a hung upstream fell back to
+  Net::HTTP's own 60s defaults on both — a full minute an agent loop could
+  be stuck mid-checkout before anything reacted. It now defaults to a 5s
+  open / 30s read timeout (mirroring `Check#get`'s own explicit precedent),
+  overridable per call via `open_timeout:`/`read_timeout:` keywords.
+  `Support::Retry#retryable_error?` now also treats `Net::OpenTimeout` and
+  `Net::ReadTimeout` as retryable — neither carries a `status`, but both are
+  exactly the "the upstream didn't do the work, try again" case the module
+  exists for.
+- Documentation only, no code change. Fixes the README's "Usage" snippet:
+  it called `server.start` on the `MCP::Server` `Mcp::Server.build` returns,
+  but that class (mcp gem 0.25.0) has no `#start` — only
+  `MCP::Server::Transports::StdioTransport#open` reads stdio frames. Every
+  bundled adapter's `exe/` had the same bug; this just fixes the README to
+  match.
+
 ## [0.9.0] - 2026-09-23
 
 - New `Support::OfferRanking` and `Support::Escalation`: the offer-ranking

data/README.md

@@ -73,7 +73,7 @@ Portage::Ucp.configure do |config|
 end
 
 server = Portage::Ucp::Mcp::Server.build(adapter: MyAdapter.new)
-server.start
+MCP::Server::Transports::StdioTransport.new(server).open
 ```
 
 See the root README's [Usage](https://github.com/tomtom87/Portage#usage)

data/lib/portage/ucp/check.rb

@@ -1,6 +1,7 @@
 require "net/http"
 require "uri"
 require "json"
+require_relative "support/connection"
 
 module Portage
   module Ucp
@@ -79,8 +80,7 @@ module Portage
       def get(uri, limit = REDIRECT_LIMIT)
         raise Portage::Ucp::Error, "too many redirects" if limit.zero?
 
-        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                                                       open_timeout: 5, read_timeout: 5) do |http|
+        response = Support::Connection.start(uri, route: :probe, open_timeout: 5, read_timeout: 5) do |http|
           http.get(uri.request_uri, { "User-Agent" => "portage-ucp-check" })
         end
 

data/lib/portage/ucp/confirmer.rb

@@ -129,10 +129,10 @@ module Portage
         #   or status HTTP call itself fails.
         # @return [Hash] `{approved: true}` on approval.
         def confirm!(amount:, currency:, merchant:, idempotency_key:)
-          json_request(Net::HTTP::Post, @confirm_url,
-                       body: { amount: amount, currency: currency, merchant: merchant,
-                               idempotency_key: idempotency_key },
-                       headers: @headers)
+          json_request(Net::HTTP::Post, @confirm_url, route: :notify,
+                                                      body: { amount: amount, currency: currency, merchant: merchant,
+                                                              idempotency_key: idempotency_key },
+                                                      headers: @headers)
 
           status = @wait ? @wait.call(idempotency_key) : poll(idempotency_key)
           return { approved: true } if status == "approved"
@@ -146,7 +146,7 @@ module Portage
           deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout_seconds
 
           loop do
-            response = json_request(Net::HTTP::Get, status_url_for(idempotency_key), headers: @headers)
+            response = json_request(Net::HTTP::Get, status_url_for(idempotency_key), route: :notify, headers: @headers)
             return response["status"] if %w[approved denied].include?(response["status"])
             return "timeout" if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
 

data/lib/portage/ucp/errors.rb

@@ -87,5 +87,40 @@ module Portage
         @decision = decision
       end
     end
+
+    # Raised by Support::Connection (docs/plans/proxy-support.md Phase 1)
+    # when any hop of a proxy connection fails — a plain-forward/gateway
+    # dial that can't reach its proxy at all, or (most commonly) a
+    # hand-rolled CONNECT tunnel hop answering anything but 200. Named by
+    # 1-indexed hop position (never 0-indexed — "hop 2" means the second
+    # proxy a request passes through, matching how a human would describe a
+    # chain) and the *redacted* proxy host (`host:port`, or
+    # `http://***@host:port` when the profile carried credentials) — never
+    # the real credentials, same posture as `doctor`'s proxy_finding in
+    # portage-cli. `status` is the CONNECT response's HTTP status when the
+    # hop answered at all (e.g. 407 for "proxy authentication required"),
+    # or nil when the hop never answered (DNS failure, connection refused).
+    class ProxyError < Error
+      attr_reader :hop_index, :status
+
+      def initialize(hop_index:, host:, status: nil, detail: nil)
+        @hop_index = hop_index
+        @status = status
+        super(build_message(host, detail))
+      end
+
+      private
+
+      def build_message(host, detail)
+        redacted = Support::Connection.redact(host)
+        outcome = if status
+                    reason = Support::Connection::REASONS[status]
+                    "CONNECT failed with #{status}#{" (#{reason})" if reason}"
+                  else
+                    "CONNECT failed#{" (#{detail})" if detail}"
+                  end
+        "hop #{hop_index} (#{redacted}): #{outcome}"
+      end
+    end
   end
 end

data/lib/portage/ucp/rack/forwarded_request.rb

@@ -0,0 +1,258 @@
+require "ipaddr"
+require "rack"
+
+module Portage
+  module Ucp
+    module Rack
+      # Phase 3 of docs/plans/proxy-support.md: the one seam every inbound
+      # Rack endpoint (WebMCP's CallEndpoint, Rack::WebhookEndpoint, and
+      # whatever HTTP transport fronts Mcp::Server) uses to make sense of
+      # `X-Forwarded-*`/`Forwarded` (RFC 7239) headers a reverse proxy sits
+      # in front of them adds.
+      #
+      # Fail-closed by construction: with no `trusted_proxies` configured
+      # (the default — `[]`), or when the immediate socket peer isn't in
+      # that list, every method here answers exactly as if no forwarded
+      # headers were present at all — behavior stays unchanged from before
+      # this class existed. Only once the peer itself is a trusted proxy do
+      # `X-Forwarded-*`/`Forwarded` get any say in the resolved client IP,
+      # scheme, or host.
+      #
+      # A consumer sets `trusted_proxies:` wherever it builds one of the
+      # endpoints above — e.g. `CallEndpoint.new(catalog: catalog,
+      # trusted_proxies: ["10.0.0.0/8"])` — naming the CIDR(s) of its own
+      # load balancer/reverse proxy, never a wildcard or the public
+      # Internet.
+      class ForwardedRequest
+        FOR_HEADER = "HTTP_X_FORWARDED_FOR".freeze
+        HOST_HEADER = "HTTP_X_FORWARDED_HOST".freeze
+        PROTO_HEADER = "HTTP_X_FORWARDED_PROTO".freeze
+        FORWARDED_HEADER = "HTTP_FORWARDED".freeze
+
+        # @raise [Portage::Ucp::Support::ProxyConfig::ConfigError] naming the
+        #   offending header, same posture as every other protected-header
+        #   check in the proxy-support plan — a passthrough list can never
+        #   contain Authorization/User-Agent/X-Shopify-*-Access-Token/
+        #   X-Payment-Token, checked once here at config-resolution time
+        #   rather than silently dropped per-request later.
+        def self.validate_passthrough!(header_names)
+          offender = Array(header_names).find { |name| Support::ProxyConfig.protected_header?(name) }
+          return unless offender
+
+          raise Support::ProxyConfig::ConfigError,
+                "#{offender} is a protected header and cannot be set via passthrough.headers"
+        end
+
+        # @param request [Rack::Request]
+        # @param trusted_proxies [Array<String>] CIDR blocks (or bare IPs,
+        #   which IPAddr treats as a /32 or /128) naming the reverse proxies
+        #   allowed to set forwarding headers. Empty (the default) means
+        #   fail-closed: nothing is ever trusted.
+        def initialize(request, trusted_proxies: [])
+          @request = request
+          @trusted_proxies = Array(trusted_proxies).filter_map { |cidr| safe_ipaddr(cidr) }
+        end
+
+        # @return [Boolean] whether the immediate socket peer is one of the
+        #   configured `trusted_proxies`. Reads `REMOTE_ADDR` straight off
+        #   the env (`Rack::Request#get_header`, not `#ip`) rather than
+        #   `request.ip` — Rack::Request#ip applies its *own*, separate
+        #   `Rack::Request.ip_filter` (a process-wide default that already
+        #   trusts RFC 1918/loopback ranges out of the box, independent of
+        #   whatever this class is configured with) and would otherwise let
+        #   Rack itself decide a header is trustworthy before this class
+        #   ever gets a say. Fail-closed has to mean fail-closed regardless
+        #   of Rack's own defaults.
+        def peer_trusted?
+          return @peer_trusted if defined?(@peer_trusted)
+
+          @peer_trusted = trusted_ip?(raw_remote_addr)
+        end
+
+        # @return [String] the resolved client IP: standard reverse-proxy
+        #   chain parsing, walking the `X-Forwarded-For`/`Forwarded` chain
+        #   from the right and skipping any entry that is itself a trusted
+        #   proxy — the first untrusted entry from the right is the real
+        #   client. Falls back to the plain socket peer when the peer isn't
+        #   trusted, no forwarding header is present, or every entry in the
+        #   chain is itself a trusted proxy (nothing untrusted to report).
+        def client_ip
+          return strip_port(raw_remote_addr) unless peer_trusted?
+
+          chain = forwarded_for_chain
+          return strip_port(raw_remote_addr) if chain.empty?
+
+          chain.reverse_each { |candidate| return candidate unless trusted_ip?(candidate) }
+          chain.first
+        end
+
+        # @return [String] "http"/"https" — from `X-Forwarded-Proto`/
+        #   `Forwarded;proto=` only when the peer is trusted, the raw
+        #   connection scheme otherwise (never Rack::Request#scheme, which
+        #   is itself forwarded-header-aware via Rack's own ip_filter — see
+        #   #peer_trusted?).
+        def scheme
+          return raw_scheme unless peer_trusted?
+
+          header_value(PROTO_HEADER) || forwarded_pair("proto") || raw_scheme
+        end
+
+        # @return [String] "host[:port]" — from `X-Forwarded-Host`/
+        #   `Forwarded;host=` only when the peer is trusted, the raw `Host`
+        #   header otherwise (never Rack::Request#host_with_port, same
+        #   reason as #scheme above).
+        def host
+          return raw_host unless peer_trusted?
+
+          header_value(HOST_HEADER) || forwarded_pair("host") || raw_host
+        end
+
+        # @return [Boolean] true only when the peer is trusted AND the
+        #   forwarded host is itself in `allowed` — the gate that keeps a
+        #   spoofed `X-Forwarded-Host` from ever widening what "own origin"
+        #   means unless a consumer explicitly opted that host in.
+        def forwarded_host_allowed?(allowed)
+          return false unless peer_trusted?
+
+          forwarded_host = header_value(HOST_HEADER) || forwarded_pair("host")
+          return false if forwarded_host.nil?
+
+          Array(allowed).map(&:to_s).include?(forwarded_host)
+        end
+
+        # @return [String] what a same-origin check should compare against
+        #   for "the endpoint's own origin" — the raw scheme/host unchanged,
+        #   unless `forwarded_host_allowed?(forwarded_host_allowed)` says
+        #   the forwarded host is explicitly trusted for this purpose, in
+        #   which case the forwarded scheme/host replace it. Never widens
+        #   `allowed_origins` itself — only ever changes what "own origin"
+        #   resolves to.
+        def own_origin(forwarded_host_allowed: [])
+          return "#{raw_scheme}://#{raw_host}" unless forwarded_host_allowed?(forwarded_host_allowed)
+
+          "#{scheme}://#{host}"
+        end
+
+        # @param header_names [Array<String>] allowlisted inbound header
+        #   names (already validated with .validate_passthrough! at
+        #   config-resolution time). Returns {} from an untrusted peer, no
+        #   matter what the caller asks for.
+        # @return [Hash{String=>String}]
+        def passthrough_headers(header_names)
+          return {} unless peer_trusted?
+
+          Array(header_names).each_with_object({}) do |name, out|
+            value = @request.get_header(rack_env_key(name))
+            out[name.to_s] = value if value
+          end
+        end
+
+        private
+
+        # The literal `REMOTE_ADDR`/`HTTP_HOST`/scheme env entries, bypassing
+        # Rack::Request's own forwarded-aware `#ip`/`#host`/`#scheme` (see
+        # #peer_trusted?'s comment) — this class makes its own trust
+        # decision from `trusted_proxies` alone, never Rack's separate
+        # `Rack::Request.ip_filter` default.
+        def raw_remote_addr
+          @request.get_header("REMOTE_ADDR").to_s
+        end
+
+        def raw_host
+          host_port = @request.get_header("HTTP_HOST") ||
+                      "#{@request.get_header('SERVER_NAME')}:#{@request.get_header('SERVER_PORT')}"
+          strip_default_port(host_port)
+        end
+
+        def raw_scheme
+          return "https" if @request.get_header("HTTPS") == "on"
+
+          @request.get_header("rack.url_scheme") || "http"
+        end
+
+        # Mirrors Rack::Request#host_with_port's own "omit :80/:443 for the
+        # matching scheme" behavior, so #own_origin's unforwarded fallback
+        # matches what a plain, un-proxied request's origin has always
+        # looked like.
+        def strip_default_port(host_port)
+          host, port = host_port.to_s.split(":", 2)
+          return host_port if port.nil?
+          return host if raw_scheme == "http" && port == "80"
+          return host if raw_scheme == "https" && port == "443"
+
+          host_port
+        end
+
+        def rack_env_key(name)
+          "HTTP_#{name.to_s.upcase.tr('-', '_')}"
+        end
+
+        def header_value(env_key)
+          value = @request.get_header(env_key)
+          value.nil? || value.empty? ? nil : value
+        end
+
+        def forwarded_for_chain
+          xff = header_value(FOR_HEADER)
+          return xff.split(",").map { |entry| strip_port(entry) }.reject(&:empty?) if xff
+
+          forwarded_pairs("for").map { |value| strip_port(value) }
+        end
+
+        # Extracts every `for=` value, in order (oldest hop first, per RFC
+        # 7239 — each proxy appends, never prepends).
+        def forwarded_pairs(key)
+          raw = header_value(FORWARDED_HEADER)
+          return [] unless raw
+
+          raw.split(",").filter_map { |element| pair_from(element, key) }
+        end
+
+        # The single most-recent (right-most) `Forwarded` element's value
+        # for `key` — used for scheme/host, which only the immediate
+        # (trusted) hop's own element should set.
+        def forwarded_pair(key)
+          raw = header_value(FORWARDED_HEADER)
+          return nil unless raw
+
+          raw.split(",").filter_map { |element| pair_from(element, key) }.last
+        end
+
+        def pair_from(element, key)
+          match = element.match(/#{key}="?([^;,"]+)"?/i)
+          return nil unless match
+
+          match[1].strip.sub(/\A\[/, "").sub(/\]\z/, "")
+        end
+
+        def trusted_ip?(ip_string)
+          return false if @trusted_proxies.empty?
+
+          addr = safe_ipaddr(strip_port(ip_string))
+          return false unless addr
+
+          @trusted_proxies.any? { |cidr| cidr.include?(addr) }
+        end
+
+        def safe_ipaddr(value)
+          IPAddr.new(value.to_s)
+        rescue IPAddr::Error
+          nil
+        end
+
+        # Handles a bracketed IPv6 literal (`[::1]:8080`), a plain
+        # `host:port` pair, and a bare address (IPv4, or IPv6 with no
+        # port) — an unbracketed IPv6 address has more than one colon, so
+        # only a single colon is ever treated as a port separator.
+        def strip_port(value)
+          value = value.to_s.strip
+          return value if value.empty?
+          return value[/\A\[(.*)\]/, 1] || value if value.start_with?("[")
+          return value.split(":").first if value.count(":") == 1
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/rack/webhook_endpoint.rb

@@ -1,6 +1,7 @@
 require "json"
 require "openssl"
 require "rack"
+require_relative "forwarded_request"
 
 module Portage
   module Ucp
@@ -20,42 +21,77 @@ module Portage
       # a logger threaded to it, not a reason to invent a second config
       # option: `logger:` already exists on Portage::Ucp.configuration and
       # every other collaborator that logs takes it the same way.
+      #
+      # Phase 3 of docs/plans/proxy-support.md: `trusted_proxies:` lets a
+      # consumer behind a reverse proxy get the real client IP into its own
+      # logs/`on_order_event` handling (`ForwardedRequest#client_ip`, fail-
+      # closed with no config change otherwise) and, when
+      # `passthrough_headers:` is also set, forwards that request's
+      # allowlisted headers (trusted peer only) to any outbound call
+      # `on_order_event` makes via Support::Connection, through the same
+      # fiber-local Support::PassthroughContext CallEndpoint uses — cleared
+      # again once `on_order_event` returns.
       class WebhookEndpoint
+        # @param trusted_proxies [Array<String>] CIDRs of the consumer's own
+        #   reverse proxy/load balancer — see ForwardedRequest.
+        # @param passthrough_headers [Array<String>] inbound header names to
+        #   forward to outbound calls made from `on_order_event`, from a
+        #   trusted peer only. Never a protected header (raises at
+        #   construction time — see ForwardedRequest.validate_passthrough!).
+        # @param passthrough_forwarded ["append", "replace", "drop"] see
+        #   Support::PassthroughContext.
         def initialize(secret:, on_order_event:, signature_header: "HTTP_X_UCP_SIGNATURE",
-                       logger: Portage::Ucp.configuration.logger)
+                       logger: Portage::Ucp.configuration.logger, trusted_proxies: [],
+                       passthrough_headers: [], passthrough_forwarded: "drop")
           @secret = secret
           @on_order_event = on_order_event
           @signature_header = signature_header
           @logger = logger
+          @trusted_proxies = trusted_proxies
+          @passthrough_headers = passthrough_headers
+          @passthrough_forwarded = passthrough_forwarded
+          ForwardedRequest.validate_passthrough!(@passthrough_headers)
         end
 
         def call(env)
           request = ::Rack::Request.new(env)
           return respond(404, error: "not_found") unless request.post?
 
+          forwarded = ForwardedRequest.new(request, trusted_proxies: @trusted_proxies)
           body = request.body.read
           unless valid_signature?(body, env[@signature_header])
-            Portage::Ucp::Observability.log(@logger, "order_webhook_rejected", reason: "invalid_signature")
+            Portage::Ucp::Observability.log(@logger, "order_webhook_rejected", reason: "invalid_signature",
+                                                                               client_ip: forwarded.client_ip)
             return respond(401, error: "invalid_signature")
           end
 
-          handle_order_event(body)
+          handle_order_event(body, forwarded)
         end
 
         private
 
-        def handle_order_event(body)
+        def handle_order_event(body, forwarded)
           payload = JSON.parse(body, symbolize_names: true)
           order = Portage::Ucp::Order.new(**payload)
           Portage::Ucp::Observability.log(@logger, "order_webhook_received", order_id: order.id,
-                                                                             checkout_id: order.checkout_id)
-          @on_order_event.call(order)
+                                                                             checkout_id: order.checkout_id,
+                                                                             client_ip: forwarded.client_ip)
+          with_passthrough(forwarded) { @on_order_event.call(order) }
           respond(200, ok: true)
         rescue JSON::ParserError, ArgumentError
-          Portage::Ucp::Observability.log(@logger, "order_webhook_rejected", reason: "bad_request")
+          Portage::Ucp::Observability.log(@logger, "order_webhook_rejected", reason: "bad_request",
+                                                                             client_ip: forwarded.client_ip)
           respond(400, error: "bad_request")
         end
 
+        def with_passthrough(forwarded, &)
+          return yield unless forwarded.peer_trusted? && @passthrough_headers.any?
+
+          headers = forwarded.passthrough_headers(@passthrough_headers)
+          Portage::Ucp::Support::PassthroughContext.with(headers: headers, forwarded: @passthrough_forwarded,
+                                                         chain_entry: forwarded.client_ip, &)
+        end
+
         def valid_signature?(body, signature)
           return false unless signature