portage-ucp 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c0a19a01df5cf624b7e08f79b9a8e21a8d9d348ce68469c932233f77e8f65b7
-  data.tar.gz: ab6342cc1a9045662a0caba73858f2d1fc97f253c2df1593ab1ca629cc870055
+  metadata.gz: 37b246e100783b94c0de9a89bdf4093123a45ae87b397202d63fa845847366d1
+  data.tar.gz: bfb928d1fd3e5cebff958ecd38cc5c3076ead011b0931cfd497fb2bea70fb64e
 SHA512:
-  metadata.gz: 830f760577b2d590337cb38eced77dc7d8a4b102f0e946dd6e8fcfce24078ebb754334615707217ce6b2e9ce1f966b45e830c6dfd14e7dd220515a72644375b8
-  data.tar.gz: 28139b13e1cc2716f16be0b3bfe35182e9bd48b5508a5e61f4bde1a164e93caf6d9b525d87def91153fea157b789b591fdb179251eb11d377a749b1eb6d1d413
+  metadata.gz: fce92b2376dbbce4849a2bda592a3162096f5d472f5d4b222dfe5f8449bdea62bd6ed32ff32db451864080b883c5c50fb7c5165e524dbfe10a58ee04c17e33c5
+  data.tar.gz: 9fea9246766b51b2819564732f3af0b4ac0a933a2797c97ad5fe75af88122e7eaeb95681f47631cc1f71d9528876b5c68224fce6ee055474633238c48c0a97d4

data/CHANGELOG.md

@@ -4,6 +4,75 @@ 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.
 
+## [Unreleased]
+
+## [0.11.0] - 2026-09-29
+
+- `Portage::Ucp::Check` (and `portage-ucp-check`) now follows a `<link rel="ucp" href="...">`
+  manifest pointer in the homepage when `/.well-known/ucp` is missing, the same fallback
+  `portage buy` uses. The report adds `manifest_url` when the manifest came from that link.
+
+- Documentation only, no code change. Fixes two wrong comments. `Authenticator`
+  pointed at a `mutating_only:` option that `Mcp::Server.build` doesn't have:
+  it only authenticates tools whose adapter method takes `idempotency_key:`,
+  and no option changes that. `Manifest#to_h` read as if this manifest reports
+  `"version": "2026-08-25"`. That is what live Shopify stores serve. This
+  manifest reports `UCP_VERSION`, `"2026-04-08"`.
+
+## [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

@@ -19,7 +19,7 @@ in this gem.
 | `Portage::Ucp::Adapter` | The contract your backend implements — override only the catalog/cart/checkout/order/identity methods you support; the rest stay unadvertised. |
 | `Portage::Ucp::CapabilityRegistry` | Figures out which capabilities an `Adapter` actually backs. |
 | `Portage::Ucp::Dispatcher` | Routes a capability+action call to the right `Adapter` method. |
-| `Portage::Ucp::Mcp::Server` | Wraps an `Adapter` as an MCP server — one `MCP::Tool` per advertised action, stdio or Streamable HTTP. |
+| `Portage::Ucp::Mcp::Server` | Wraps an `Adapter` as an MCP server — one `MCP::Tool` per advertised action; serve it over stdio or Streamable HTTP with the `mcp` gem's transports. |
 | `Portage::Ucp::Manifest` | Builds the signed `/.well-known/ucp` discovery document. |
 | `Portage::Ucp::Rack::ManifestEndpoint` | Serves that manifest over Rack. |
 | `Portage::Ucp::Rack::WebhookEndpoint` | HMAC-verified inbound order-lifecycle webhooks. |
@@ -32,7 +32,7 @@ in this gem.
 | `Portage::Ucp::PolicyGuard` / `Portage::Ucp::Policy` | Per-transaction/rolling/velocity caps and a merchant allowlist, checked before `complete_checkout` dispatch; configured via `portage-cli`'s `portage policy show/set`. |
 | `Portage::Ucp::Support::OfferRanking` / `Portage::Ucp::Support::Escalation` | The offer-ranking rule (buyable, then priced, then cheapest, ties stable) and the escalation rule (`requires_escalation`, then a mismatch). `portage-ucp-decision` wraps both as typed verdicts; `portage-cli` calls them directly. |
 | `Portage::Ucp::PaymentEnrollmentGuard` | Validates every `create_payment_enrollment`/`get_payment_enrollment` result an `Adapter` returns — `status` must be `"pending"` (with a `setup_url`, no `payment_token`) or `"complete"` (with a `payment_token`, no `setup_url`). Runs automatically in `Dispatcher#call`. |
-| `Portage::Ucp::Ap2::PaymentMandate` / `Portage::Ucp::Ap2::MandateGuard` | A typed shape for an AP2 payment mandate, and shape-only validation (required fields + expiry — not cryptographic verification) run automatically on any `mandate:` argument passed through `Dispatcher#call`. |
+| `Portage::Ucp::Ap2::PaymentMandate` / `Portage::Ucp::Ap2::MandateGuard` | A typed shape for an AP2 payment mandate, and validation (required fields + expiry, plus signature verification when `mandate_trusted_keys` is configured) run automatically on any `mandate:` argument passed through `Dispatcher#call`. |
 
 Security defaults are all locked down, not permissive-by-omission —
 `UnconfiguredAuthenticator` rejects every mutating call until you configure a real
@@ -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/authenticator.rb

@@ -4,10 +4,11 @@ module Portage
     #   tool call, return an auth context (any truthy value) or raise
     #   Portage::Ucp::AuthenticationError. There is deliberately no default that
     #   allows anonymous mutation — an unconfigured server rejects every
-    #   mutating capability call (see UNCONFIGURED below). Read-only catalog
-    #   calls MAY be left open at the consumer's explicit choice by not
-    #   requiring authentication for those specific actions (see
-    #   Mcp::Server.build's `mutating_only:`).
+    #   mutating capability call (see UnconfiguredAuthenticator below).
+    #   Mcp::Server.build calls it only for mutating tools: those whose
+    #   adapter method takes `idempotency_key:`. Every other tool (catalog
+    #   search, product, cart, checkout and order lookups) never reaches it,
+    #   and Server.build has no option to change that.
     class Authenticator
       def call(_server_context)
         raise NotImplementedError, "#{self.class} must implement #call"

data/lib/portage/ucp/check.rb

@@ -1,13 +1,16 @@
 require "net/http"
 require "uri"
 require "json"
+require_relative "support/connection"
 
 module Portage
   module Ucp
     # `portage-ucp-check <url>` — point it at any storefront and find out what
     # portage-ucp can do with it. Checks for a native `/.well-known/ucp`
     # manifest first (the store may already speak UCP without this gem, see
-    # README's "Why /.well-known/ucp?"); if there isn't one, detects the
+    # README's "Why /.well-known/ucp?"), then a `<link rel="ucp" href=...>`
+    # manifest pointer in the homepage (the same fallback `portage buy`
+    # follows); if there isn't one, detects the
     # commerce platform from the page itself (see Resolver) and names
     # the matching portage-ucp-<adapter> gem — probing it live when that
     # adapter's env vars are already set, so "best match" means a
@@ -29,6 +32,10 @@ module Portage
         return { url: @uri.to_s, native_ucp: manifest } if manifest
 
         body, headers = fetch_homepage
+        linked = manifest_link(body)
+        manifest = linked && fetch_json(linked)
+        return { url: @uri.to_s, native_ucp: manifest, manifest_url: linked.to_s } if manifest
+
         platform = Resolver.detect_platform(body, headers)
 
         report = { url: @uri.to_s, native_ucp: nil, platform: platform&.name, recommended_gem: platform&.gem }
@@ -41,7 +48,11 @@ module Portage
       def fetch_manifest
         manifest_uri = @uri.dup
         manifest_uri.path = MANIFEST_PATH
-        response = get(manifest_uri)
+        fetch_json(manifest_uri)
+      end
+
+      def fetch_json(uri)
+        response = get(uri)
         return nil unless response.is_a?(Net::HTTPSuccess)
 
         JSON.parse(response.body)
@@ -58,6 +69,18 @@ module Portage
         [nil, {}]
       end
 
+      # `<link rel="ucp" href="...">` in either attribute order, resolved
+      # against the store URL.
+      def manifest_link(body)
+        return nil unless body
+
+        match = body.match(/<link[^>]+rel=["']ucp["'][^>]+href=["']([^"']+)["']/i) ||
+                body.match(/<link[^>]+href=["']([^"']+)["'][^>]+rel=["']ucp["']/i)
+        match && URI.join(@uri, match[1])
+      rescue URI::Error
+        nil
+      end
+
       def probe(platform)
         env = Resolver.env_for(platform)
         missing = Resolver.missing_env(platform, env)
@@ -79,8 +102,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/manifest.rb

@@ -32,10 +32,11 @@ module Portage
       end
 
       # Nests everything under a "ucp" envelope, and keys `capabilities` by
-      # capability name (matching what live Shopify UCP rollouts — Casper,
-      # Allbirds, Glossier, and 34+ others — actually serve as of manifest
-      # "version": "2026-08-25"; see docs/well-known-ucp.md and
-      # portage-ucp-client's Client.discover, which this shape now matches).
+      # capability name. That is the shape live Shopify UCP rollouts (Casper,
+      # Allbirds, Glossier, and 34+ others) serve under their own manifest
+      # "version": "2026-08-25", and the shape portage-ucp-client's
+      # Client.discover reads. Only the shape is borrowed: `version` here is
+      # still UCP_VERSION ("2026-04-08"), the spec revision this gem targets.
       def to_h
         ucp = {
           version: UCP_VERSION,

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