capybara-simulated 0.6.0 → 0.7.0

data/lib/capybara/simulated/browser.rb

@@ -9,11 +9,13 @@ require 'net/http'
 require 'openssl'
 require 'rack/mock'
 require 'securerandom'
+require 'set'
 require 'socket'
 require 'thread'
 require 'time'
 require 'uri'
 require 'uri/idna'   # WHATWG/UTS46 domain-to-ASCII/Unicode (uri-idna gem)
+require 'zlib'
 require_relative 'asset_cache'
 require_relative 'errors'
 require_relative 'stack_resolver'
@@ -54,6 +56,18 @@ module Capybara
       # `Last-Modified` per RFC 9111.
       @@asset_cache = AssetCache.new
 
+      # Opt-in: capture each request's author header names verbatim on the Rack env
+      # (`csim.raw_request_headers`) so the WPT .py-handler harness can replay them with
+      # exact casing / token chars (inspect-headers / echo-headers). OFF for real app
+      # traffic — nothing there consumes the list, so it would only allocate per request.
+      @@capture_raw_request_headers = false
+      def self.capture_raw_request_headers
+        @@capture_raw_request_headers
+      end
+      def self.capture_raw_request_headers=(v)
+        @@capture_raw_request_headers = v
+      end
+
       attr_writer :timers_active
 
       # The Driver's handle for the window this Browser backs (set right after
@@ -271,6 +285,7 @@ module Capybara
         @ticking                      = false
         @history                      = []
         @history_idx                  = -1
+        @cors_preflight_cache         = {}
         @modal_handlers               = []
         # Geolocation override (CDP-ish). nil = no override configured →
         # navigator.geolocation reports POSITION_UNAVAILABLE. Ruby-backed so
@@ -2468,7 +2483,13 @@ module Capybara
           body << "--#{boundary}--\r\n"
           [body, "multipart/form-data; boundary=#{boundary}"]
         else
-          pairs = entries.map {|e| [e['name'].to_s, e['file'] ? e['filename'].to_s : e['value'].to_s] }
+          # The urlencoded / text-plain encoders normalize CR/LF → CRLF in each entry's
+          # name and value (a file entry's filename is the value) — the entry list itself
+          # stays raw, so normalization lives here, matching the JS encoders and real
+          # browsers (newline-normalization.html).
+          pairs = entries.map {|e|
+            [normalize_form_newlines(e['name']), normalize_form_newlines(e['file'] ? e['filename'] : e['value'])]
+          }
           if enctype == 'text/plain'
             [pairs.map {|name, value| "#{name}=#{value}\r\n" }.join, 'text/plain']
           else
@@ -2477,6 +2498,12 @@ module Capybara
         end
       end
 
+      # HTML form-submission newline normalization: every lone CR, lone LF, and CRLF in an
+      # entry name/value becomes a CRLF (the JS encoders' `normalizeNL` counterpart).
+      def normalize_form_newlines(s)
+        s.to_s.gsub(/\r\n?|\n/, "\r\n")
+      end
+
       # Resolve a threaded file entry's on-disk path via the `@file_picks` slot
       # recorded at `attach_file` time (handle/index). nil for a purely in-memory
       # `new File(['bytes'], …)` (no slot) — a CLASSIC (non-Turbo) submit then
@@ -2599,6 +2626,11 @@ module Capybara
         reset_frame_scope
         @history.clear
         @history_idx     = -1
+        @cors_preflight_cache = {}   # CORS-preflight cache is per browsing context
+        # A JS-driven history.back()/go() that scheduled a deferred traverse but
+        # never drained (the page navigated away first) must not survive the reset
+        # — otherwise the stale target replays against the NEXT page's fresh history.
+        @pending_history_traverse = nil
         @file_picks      = {} if @file_picks
         # Hand the live trace off to `@pending_trace` so an after-hook
         # running after `reset_session!` (Capybara's per-test teardown
@@ -3728,26 +3760,13 @@ module Capybara
       end
 
       def blob_resolve(url)
-        local = @blob_registry_lock.synchronize { @blob_registry[url.to_s] }
-        return local if local
-        # Not in this window's registry: a blob created in ANOTHER window/isolate is
-        # fetchable only from the SAME storage partition (cross-partition.https
-        # "fetched from a same-partition iframe" succeeds; a cross-partition fetch
-        # fails). Resolve the bytes cross-isolate from the creator and hand them back
-        # as base64 (resolveBlobBytes decodes them). The cross-isolate read enters the
-        # creator's V8 isolate, so only do it on the MAIN thread — a worker thread
-        # can't safely enter another isolate (so a same-partition WORKER fetch of a
-        # blob owned elsewhere isn't supported; a cross-partition one correctly fails).
-        # CAVEAT: bytes-only — resolveBlobBytes types a host-resolved blob as
-        # application/octet-stream (the cross-window path loses the Blob's `type`); no
-        # in-scope test reads the type on this path, and carrying it would change the
-        # __csim_blobResolve string protocol.
-        return nil unless @driver.respond_to?(:blob_partition_site_of) && @driver.respond_to?(:blob_bytes_for)
-        site = @driver.blob_partition_site_of(url.to_s)
-        return nil if site.nil? || site != blob_partition_site   # unknown / revoked / cross-partition
-        return nil if Thread.current[:csim_worker_handle]
-        data = @driver.blob_bytes_for(url.to_s, self)
-        data && Base64.strict_encode64(data[:bytes].to_s.b)
+        # A same-partition blob created in another window/isolate is spec-fetchable
+        # cross-window, but resolving its bytes means a real-time cross-isolate read
+        # (+ worker round-trips for the worker variants) that races the per-example
+        # timeout under suite load — flaky in the gate. So we only resolve a blob from
+        # THIS window's registry; the cross-window same-partition fetch is a backlog
+        # item (cross-partition.https "fetched from a same-partition {iframe,worker}").
+        @blob_registry_lock.synchronize { @blob_registry[url.to_s] }
       end
 
       # The SITE (scheme + registrable domain) of this window's top-level document.
@@ -4225,15 +4244,134 @@ module Capybara
         end
       end
 
+      # Fetch caps a request at 20 redirects: the 21st is a network error (redirect-count).
+      # The loop below runs one iteration PER dispatch, so it needs 20 redirect hops plus
+      # the final response — MAX_FETCH_REDIRECTS + 1 iterations — to let exactly 20 succeed.
       MAX_FETCH_REDIRECTS = 20
+      # Request cache modes that never READ the store (always hit the network), and modes that
+      # serve a STORED response even when stale. Frozen so the hot rack_fetch path allocates no
+      # throwaway arrays per hop (perf).
+      CACHE_MODES_SKIP_READ  = %w[no-store reload].freeze
+      CACHE_MODES_SERVE_STALE = %w[force-cache only-if-cached].freeze
+      # Fetch "bad port" blocklist (https://fetch.spec.whatwg.org/#port-blocking) —
+      # ports tied to non-HTTP protocols a request must never reach. Frozen Set for
+      # O(1) membership on the rack_fetch path.
+      BAD_PORTS = Set[
+        0, 1, 7, 9, 11, 13, 15, 17, 19, 20, 21, 22, 23, 25, 37, 42, 43, 53, 69, 77,
+        79, 87, 95, 101, 102, 103, 104, 109, 110, 111, 113, 115, 117, 119, 123, 135,
+        137, 139, 143, 161, 179, 389, 427, 465, 512, 513, 514, 515, 526, 530, 531,
+        532, 540, 548, 554, 556, 563, 587, 601, 636, 989, 990, 993, 995, 1719, 1720,
+        1723, 2049, 3659, 4045, 4190, 5060, 5061, 6000, 6566, 6665, 6666, 6667, 6668,
+        6669, 6679, 6697, 10080
+      ].freeze
+
+      REFERRER_POLICIES = %w[
+        no-referrer no-referrer-when-downgrade origin origin-when-cross-origin
+        same-origin strict-origin strict-origin-when-cross-origin unsafe-url
+      ].freeze
+
+      # The `Referer` value a request carries under a Referrer-Policy — nil = send none
+      # (https://w3c.github.io/webappsec-referrer-policy/#determine-requests-referrer).
+      # `referrer_url` is the request's referrer (the initiating document); `target_url`
+      # its destination. "full" is the referrer stripped of fragment + credentials;
+      # "origin" is scheme://host[:port]/. An empty / unknown policy → the default
+      # (strict-origin-when-cross-origin).
+      def compute_referrer(policy, referrer_url, target_url)
+        return nil if referrer_url.nil? || referrer_url.to_s.empty?
+        policy = 'strict-origin-when-cross-origin' unless REFERRER_POLICIES.include?(policy)
+        return nil if policy == 'no-referrer'
+        # The referrer is almost always the (constant) document URL — memoise its parse
+        # so the rack_fetch hot path doesn't re-parse it per request (rule 3).
+        ref = parse_referrer_url(referrer_url)
+        return nil unless ref && %w[http https].include?(ref.scheme)
+        full        = -> { u = ref.dup; u.fragment = nil; u.password = nil; u.user = nil; u.to_s }
+        origin_only = -> {
+          default_port = ref.scheme == 'https' ? 443 : 80
+          port         = ref.port && ref.port != default_port ? ":#{ref.port}" : ''
+          "#{ref.scheme}://#{ref.host}#{port}/"
+        }
+        return full.call        if policy == 'unsafe-url'
+        return origin_only.call if policy == 'origin'
+        # The remaining policies need the target to know same-origin / downgrade.
+        tgt = (URI.parse(target_url) rescue nil)
+        return nil unless tgt
+        same_origin = ref.scheme == tgt.scheme && ref.host == tgt.host && ref.port == tgt.port
+        downgrade   = ref.scheme == 'https' && tgt.scheme == 'http'
+        case policy
+        when 'origin-when-cross-origin'        then same_origin ? full.call : origin_only.call
+        when 'same-origin'                     then same_origin ? full.call : nil
+        when 'strict-origin'                   then downgrade ? nil : origin_only.call
+        when 'no-referrer-when-downgrade'      then downgrade ? nil : full.call
+        when 'strict-origin-when-cross-origin' then same_origin ? full.call : (downgrade ? nil : origin_only.call)
+        end
+      end
+
+      # Parse a referrer URL, memoising the last one (the referrer is the document URL
+      # for nearly every request, so this caches across the whole page's subresources).
+      def parse_referrer_url(url)
+        return @referrer_parsed if defined?(@referrer_parsed_for) && @referrer_parsed_for == url
+        @referrer_parsed_for = url
+        @referrer_parsed     = (URI.parse(url) rescue nil)
+      end
+
+      # Whether a request to `url_str` must be blocked as a Fetch "bad port". Cheap
+      # pre-gate: only URLs whose authority carries an explicit `:<digit>` are parsed
+      # (the vast majority don't), so the rack_fetch hot path — every asset / xhr /
+      # fetch, cache hits included — skips URI.parse entirely.
+      def bad_port?(url_str)
+        return false unless url_str =~ %r{\A[a-z]+://[^/]*:\d}i
+        port = URI.parse(url_str).port
+        port && BAD_PORTS.include?(port)
+      rescue URI::Error
+        false
+      end
+
       # URLs we won't even try to route through Rack: anything that
       # isn't http(s) (data: / mailto: / about:) plus pseudo-tokens
       # like V8's `<snapshot>` that sourcemap libraries pull out of
       # error stacks and feed straight to `fetch()` / `xhr.open()`.
-      def rack_fetch(method, url, body, headers, redirect_mode, env_extras: nil)
+      def rack_fetch(method, url, body, headers, redirect_mode, cors_mode = nil, credentials: 'same-origin', env_extras: nil, referrer_policy: nil, referrer: nil, cache_mode: 'default')
+        # NB: a relative fetch/XHR URL is resolved against the document's API base URL
+        # at OPEN time (XHR open() / fetch()), in JS, NOT here — resolving at send time
+        # would wrongly pick up a `<base href>` inserted after open() (open-url-base
+        # -inserted-after-open). So this resolves only against the document URL.
         target = resolve_against_current(url.to_s)
         return nil unless target.is_a?(String) && target.match?(%r{\Ahttps?://}i)
-        method = (method || 'GET').to_s.upcase
+        # Fetch "port blocking" (https://fetch.spec.whatwg.org/#port-blocking): a
+        # request to a blocked port is a network error before any connection —
+        # fetch() rejects with TypeError, a sync XHR throws NetworkError
+        # (request-bad-port). Re-checked per redirect hop below ("HTTP-redirect fetch"
+        # re-runs the block), so a 3xx Location to a bad port is refused too.
+        return nil if bad_port?(target)
+        # CORS enforcement (preflight + Access-Control checks) applies only to cors_mode
+        # 'cors' — sent by XHR and by fetch()'s default mode. fetch() also threads
+        # 'no-cors' / 'same-origin' (mode semantics below), and a form-submission
+        # navigation threads 'navigate'; other callers (sendBeacon, ESM, workers, the
+        # internal asset GET) pass nil → no CORS and no mode semantics. The document's
+        # origin is the request's origin; a different target origin is cross-origin.
+        cors        = cors_mode == 'cors'
+        req_origin  = cors ? url_origin(@current_url) : nil
+        # Fetch request "mode" (fetch threads it; XHR is always 'cors'; a non-fetch/xhr
+        # caller passes nil → no mode semantics, a plain 'basic' response). `no-cors`
+        # filters a cross-origin response to opaque; `same-origin` makes a cross-origin
+        # request a network error. `doc_origin` detects cross-origin for the response
+        # TYPE regardless of whether CORS enforcement (cors) runs; `crossed` latches once
+        # any hop leaves the document origin.
+        no_cors_mode     = cors_mode == 'no-cors'
+        same_origin_mode = cors_mode == 'same-origin'
+        # Only the real fetch request modes carry cross-origin semantics; a 'navigate'
+        # (form submission) or a nil-mode internal caller gets a plain readable response.
+        doc_origin       = %w[cors no-cors same-origin].include?(cors_mode) ? url_origin(@current_url) : nil
+        crossed          = false
+        # A request is "credentialed" (cookies + the credentialed CORS check) only in
+        # `include` mode; `same-origin` (default) and `omit` are uncredentialed for the
+        # CORS check, while the cookie decision below distinguishes all three.
+        with_credentials = credentials == 'include'
+        # Use the method's case AS GIVEN: the JS callers already applied the spec
+        # normalization (XHR open() / Fetch upper-case the known methods, preserving
+        # an unknown method's case — open-method-case-sensitive). Upper-casing here
+        # would clobber a custom method like `xUNIcorn`.
+        method = (method || 'GET').to_s
         redirected = false
         # JS-side base64-encodes Blob/File bodies (raw bytes survive
         # the engine's UTF-8 string boundary that way); decode before
@@ -4242,22 +4380,117 @@ module Capybara
           body = Base64.decode64(body.to_s)
           headers = headers.reject {|k, _| k == 'X-Csim-Body-B64' }
         end
-        MAX_FETCH_REDIRECTS.times do
+        # The request's origin starts as the document origin; a cross-origin REDIRECT
+        # taints it to an opaque origin (serialized "null") per Fetch "HTTP-redirect
+        # fetch". `effective_origin` IS that origin — it's what the Origin header
+        # carries and what the CORS check / preflight compare against from that hop on
+        # ('null' once tainted, so the server must then allow 'null' or '*').
+        effective_origin = req_origin
+        # An author conditional (If-None-Match / …) means the caller is doing its own
+        # revalidation, so the UA cache must step aside (computed once — the headers
+        # carrying it survive every redirect hop unchanged).
+        skip_cache = request_has_conditional_headers?(headers)
+        ref_policy = referrer_policy   # may be overridden per hop by a response Referrer-Policy
+        # The referrer is stripped PROGRESSIVELY: each hop applies its (possibly
+        # overridden) policy to the referrer the PREVIOUS hop sent, not to the original
+        # document — so once a hop reduces it to an origin (or drops it), a later, laxer
+        # policy can't widen it back (redirect-referrer-override). The initial source is
+        # the request's referrer: an explicit `init.referrer` URL when given, else the
+        # document URL ("client"); an empty referrer means no-referrer (compute_referrer
+        # maps a blank source to nil).
+        ref_source = referrer.nil? ? @current_url : referrer
+        (MAX_FETCH_REDIRECTS + 1).times do
           t0 = @trace && Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          # GET-only cache shortcut (RFC 9111). Fresh hit → skip @app.call
-          # entirely; stale-but-revalidatable → fall through with conditional
-          # headers added so the server can return 304.
-          cache_entry = method == 'GET' ? @@asset_cache.lookup(target) : nil
-          if cache_entry&.fresh?
-            # Cached static asset — log headers/type/size but skip the (boring) body.
+          # Cross-origin-ness for the request mode/type, latched across hops. Computed
+          # BEFORE the cache so a cross-origin request never takes the cache fast path
+          # (which would bypass the opaque filter / same-origin-mode error / cors type).
+          crossed ||= !!(doc_origin && (effective_origin == 'null' || url_origin(target) != doc_origin))
+          return nil if same_origin_mode && crossed   # 'same-origin' mode forbids a cross-origin hop
+          # HTTP cache (RFC 9111 + Fetch "HTTP-network-or-cache fetch"), gated by the request's
+          # cache MODE. GET-only, same-origin (a cross-origin hop always redispatches so the mode
+          # filtering below runs), and stepped aside when the author sent their own conditional.
+          #   - no-store / reload    : never read the store — always hit the network, no conditional
+          #   - force-cache / only-if-cached : serve a stored response even when STALE, no revalidation
+          #                                    (only-if-cached with nothing stored is a network error)
+          #   - no-cache             : always revalidate, even a fresh entry
+          #   - default              : serve fresh; revalidate stale (fall through with conditionals)
+          read_cache  = method == 'GET' && !skip_cache && !crossed && !CACHE_MODES_SKIP_READ.include?(cache_mode)
+          cache_entry = read_cache ? @@asset_cache.lookup(target) : nil
+          serve_stored = cache_entry &&
+            (CACHE_MODES_SERVE_STALE.include?(cache_mode) || (cache_entry.fresh? && cache_mode != 'no-cache'))
+          if serve_stored
+            if REDIRECT_STATUSES.include?(cache_entry.status.to_i)
+              # A cached REDIRECT obeys the redirect mode exactly like a fresh one: `error` is a
+              # network error, `manual` is an opaque-redirect, and `follow` follows it THROUGH
+              # the cache — resolve the Location and continue so the next hop serves the cached
+              # target (request-cache "uses cached … redirects"). only-if-cached / force-cache
+              # reach this only same-origin GET (read_cache excludes cross-origin), so there's no
+              # method rewrite / origin taint.
+              raise StandardError, '[capybara-simulated] fetch: redirect blocked by redirect=error mode' if redirect_mode == 'error'
+              if redirect_mode != 'follow'
+                return response_hash(0, {}, '', target, false, type: 'opaqueredirect', body_null: true)
+              end
+              if (loc = redirect_location(cache_entry.status, cache_entry.headers))
+                trace_network(method, target, cache_entry.status, headers, body, cache_entry.headers, nil, t0, true)
+                redirected = true
+                next_url   = resolve_against(loc, target)
+                return nil unless next_url.to_s.match?(%r{\Ahttps?://}i)
+                target = carry_fragment(target, next_url)
+                return nil if bad_port?(target)   # a cached redirect to a blocked port is still a network error
+                next
+              end
+            end
+            # Cached asset — log headers/type/size but skip the (boring) body.
             trace_network(method, target, cache_entry.status, headers, body, cache_entry.headers, nil, t0, false)
             return response_hash(cache_entry.status, cache_entry.headers, cache_entry.body, target, redirected)
           end
+          # only-if-cached forbids the network: no usable stored response → a network error.
+          return nil if cache_mode == 'only-if-cached'
 
           env = Rack::MockRequest.env_for(target, method: method, input: body || '')
+          env['REQUEST_METHOD'] = method   # env_for upcases the method; restore the exact case (open-method-case-sensitive)
+          # A GET/HEAD request carries no body, so it sends no Content-Length (env_for
+          # always sets it to the input bytesize, i.e. 0). A POST/PUT with an empty body
+          # keeps Content-Length: 0 (send-entity-body-none / -empty).
+          env.delete('CONTENT_LENGTH') if %w[GET HEAD].include?(method.to_s.upcase)
           apply_request_headers(env, headers) if headers
           apply_request_headers(env, @@asset_cache.revalidation_headers(cache_entry)) if cache_entry
-          apply_default_request_env(env, referer: @current_url, force: false)
+          # The Referer follows the request's Referrer-Policy (a redirect response can
+          # override the policy for the next hop — see below). `hop_referer` also becomes
+          # the source the NEXT hop strips from.
+          hop_referer = compute_referrer(ref_policy, ref_source, target)
+          apply_default_request_env(env, referer: hop_referer, force: false)
+          # Whether this hop is cross-origin (cors only): a tainted (opaque) origin is
+          # cross-origin to every real target; otherwise compare the target to the
+          # document origin. Drives the Origin header, preflight, and the CORS check.
+          cross_origin = cors && (effective_origin == 'null' || url_origin(target) != req_origin)
+          # Fetch credentials mode decides cookie attachment, independent of the CORS
+          # mode: `omit` never sends them; `include` always does; `same-origin` (default)
+          # sends them only to a same-origin target — so an uncredentialed cross-origin
+          # hop (cors OR no-cors) must not leak the document's cookies
+          # (cors-redirect-credentials / cors-cookies). A navigation / internal caller has
+          # no doc_origin, so it counts as same-origin and keeps them.
+          hop_cross_origin = !!(doc_origin && (effective_origin == 'null' || url_origin(target) != doc_origin))
+          send_cookies     = credentials == 'include' || (credentials != 'omit' && !hop_cross_origin)
+          env.delete('HTTP_COOKIE') unless send_cookies
+          # A CORS request to a URL carrying credentials (`user:pass@`) is a network
+          # error (access-control-and-redirects "user info" subtest).
+          return nil if cross_origin && url_has_userinfo?(target)
+          # CORS-preflight, re-evaluated PER HOP: a cross-origin non-simple request (a
+          # non-safelisted method / header / Content-Type) must pass an OPTIONS preflight
+          # first — so a same-origin request redirected cross-origin to an unsafe resource
+          # is preflighted on the NEW origin (send-redirect-to-cors), not just an initially
+          # cross-origin one (access-control-basic-get-fail-non-simple / preflight-*).
+          if cross_origin && cors_unsafe_request?(method, headers)
+            return nil unless cors_preflight_ok?(target, method, headers, effective_origin, with_credentials, hop_referer)
+          end
+          # Send the (effective) Origin — the UA owns this header — on a cors request when
+          # the hop is cross-origin OR the method is not GET/HEAD (Fetch appends Origin to
+          # every non-GET/HEAD request, so a same-origin POST carries it too). After a
+          # cross-origin redirect the origin is the opaque "null".
+          if cross_origin || (req_origin && !%w[GET HEAD].include?(method.to_s.upcase))
+            env['HTTP_ORIGIN'] = effective_origin
+          end
           env.merge!(env_extras) if env_extras
           status, resp_headers, resp_body = dispatch_rack_or_http(target, env, method: method, body: body)
           merge_set_cookie(resp_headers)
@@ -4267,23 +4500,119 @@ module Capybara
             @@asset_cache.refresh(cache_entry, resp_headers)
             return response_hash(cache_entry.status, cache_entry.headers, cache_entry.body, target, redirected)
           end
-          if redirect_mode != 'manual' && (loc = redirect_location(status, resp_headers))
+          # Fetch "CORS check" runs on EVERY cross-origin response — including a 3xx the
+          # UA is about to follow (a redirect whose response lacks a valid Access-Control
+          # -Allow-Origin is itself a network error: access-control-and-redirects). A
+          # credentialed request additionally forbids `*` and needs Allow-Credentials.
+          if cross_origin && !cors_response_ok?(resp_headers, effective_origin, with_credentials)
+            resp_body.close if resp_body.respond_to?(:close)
+            return nil
+          end
+          # A redirect-status response in a NON-follow mode is handled without following,
+          # keyed on the status ALONE (the Location is never parsed): `error` is a network
+          # error; `manual` is an opaque-redirect filtered response (status 0, empty
+          # statusText/headers, the ORIGINAL request URL, type 'opaqueredirect'). The CORS
+          # check above runs first, so a cross-origin redirect that fails CORS is a network
+          # error either way (redirect-mode / -location).
+          if redirect_mode != 'follow' && REDIRECT_STATUSES.include?(status.to_i)
+            resp_body.close if resp_body.respond_to?(:close)
             raise StandardError, '[capybara-simulated] fetch: redirect blocked by redirect=error mode' if redirect_mode == 'error'
+            # A no-cors request may not even opaquely expose a CROSS-origin redirect — a
+            # no-cors non-follow redirect to a cross-origin target is a network error,
+            # while a same-origin one still yields an opaque-redirect.
+            return nil if no_cors_mode && crossed
+            return response_hash(0, {}, '', target, false, type: 'opaqueredirect', body_null: true)
+          end
+          if (loc = redirect_location(status, resp_headers))
             # Log this hop (3xx) before method/body are rewritten for the next.
             trace_network(method, target, status, headers, body, resp_headers, nil, t0, true)
+            # Cache the redirect itself (a cacheable 3xx with freshness) BEFORE following it —
+            # the follow does `next`, which would otherwise skip the store below — so a later
+            # only-if-cached / force-cache request can follow the redirect chain from the cache
+            # (request-cache "uses cached … redirects"). Same store gate as the terminal hop.
+            @@asset_cache.store(target, status, resp_headers, '') if method == 'GET' && cache_mode != 'no-store' && !skip_cache
             redirected = true
-            preserve = [307, 308].include?(status)
+            ref_source = hop_referer   # the next hop strips from what THIS hop sent
+            # A redirect response's Referrer-Policy overrides the policy for the next hop
+            # (redirect-referrer-override): the last valid token of the header wins.
+            if (rp = resp_headers['referrer-policy'] || resp_headers['Referrer-Policy'])
+              tok = Array(rp).join(',').split(',').map(&:strip).reverse.find {|t| REFERRER_POLICIES.include?(t) }
+              ref_policy = tok if tok
+            end
             next_url = resolve_against(loc, target)
+            # The UA only follows http(s) redirects: a Location that resolves to a
+            # non-HTTP(S) URL (data:, an `invalidurl:` scheme, …) is a network error
+            # (redirect-location data/invalid in follow mode).
+            unless next_url.to_s.match?(%r{\Ahttps?://}i)
+              resp_body.close if resp_body.respond_to?(:close)
+              return nil
+            end
+            # A cross-origin redirect taints the request's origin to opaque ("null") only
+            # once the request was ALREADY cross-origin (response tainting "cors", i.e.
+            # `crossed`) and the hop changes origin — so a subsequent hop sends Origin: null
+            # and the CORS check demands the server allow "null"/"*". The FIRST cross-origin
+            # hop out of a same-origin request keeps the real origin (redirect-origin
+            # "same origin to other origin" sends the document origin, not null).
+            effective_origin = 'null' if cors && crossed && url_origin(next_url) != url_origin(target)
             target = carry_fragment(target, next_url)
-            method = 'GET' unless preserve
-            body = nil unless preserve
+            if bad_port?(target)   # a redirect to a blocked port is a network error too
+              resp_body.close if resp_body.respond_to?(:close)
+              return nil
+            end
+            # Fetch "HTTP-redirect fetch": the method changes to GET (dropping the
+            # body + its Content-* headers) ONLY for 301/302 of a POST, or 303 of a
+            # non-GET/HEAD. Otherwise method, body, and headers are preserved — so a
+            # GET/HEAD redirected via 301/302/303 keeps its method and Content-Type,
+            # and 307/308 always preserve (xhr send-redirect basics).
+            up = method.to_s.upcase
+            if ([301, 302].include?(status) && up == 'POST') || (status == 303 && !%w[GET HEAD].include?(up))
+              method  = 'GET'
+              body    = nil
+              headers = headers.reject {|k, _| REDIRECT_DROPPED_HEADERS.include?(k.to_s.downcase) } if headers.is_a?(Hash)
+            end
             resp_body.close if resp_body.respond_to?(:close)
             next
           end
+          # A follow-mode redirect whose Location header IS present but EMPTY parses to the
+          # request URL — a self-redirect that would loop until the redirect limit trips a
+          # network error. redirect_location returns nil for it (empty ⇒ no followable
+          # target, so navigation keeps rendering the 3xx), so recognize it here and fail
+          # directly — fetch-only (redirect-empty-location follow mode).
+          if REDIRECT_STATUSES.include?(status.to_i)
+            raw_loc = resp_headers['location'] || resp_headers['Location']
+            raw_loc = raw_loc.first if raw_loc.is_a?(Array)
+            if raw_loc && raw_loc.to_s.empty?
+              resp_body.close if resp_body.respond_to?(:close)
+              return nil
+            end
+          end
           body_str = read_rack_body(resp_body)
+          # A HEAD response, and a null-body status (204/205/304), have NO body — the UA
+          # discards whatever the server sent and exposes response.body as null
+          # (response-method HEAD; response-null-body). `null_body` flags it so the JS
+          # Response reports a null body + empty text.
+          null_body = method.to_s.upcase == 'HEAD' || NULL_BODY_STATUSES.include?(status.to_i)
+          body_str = '' if null_body
+          # The UA transparently decodes a Content-Encoding'd body (gzip/deflate); the
+          # header stays, the bytes are inflated (response-data-gzip / -deflate).
+          body_str = decode_content_encoding(body_str, resp_headers)
+          # A cross-origin response only EXPOSES (getResponseHeader / getAllResponseHeaders)
+          # the CORS-safelisted response headers plus those named in Access-Control-Expose
+          # -Headers (`*` = all). content-type stays safelisted, so response decoding is
+          # unaffected. (Filtered for script exposure only — trace / set-cookie / cache see
+          # the full set.) The CORS check itself already ran above (incl. on 3xx hops).
+          exposed_headers = cross_origin ? cors_exposed_headers(resp_headers) : resp_headers
           trace_network(method, target, status, headers, body, resp_headers, body_str, t0, false)
-          @@asset_cache.store(target, status, resp_headers, body_str) if method == 'GET'
-          return response_hash(status, resp_headers, body_str, target, redirected)
+          # A no-store request must not write the cache (RFC 9111 §5.2.1.5); a request carrying
+          # the author's own conditional bypasses the UA cache entirely (read AND write) — it's
+          # "treated similarly to no-store" (request-cache-default-conditional). Every other mode
+          # (incl. reload, which refreshes it) stores a cacheable GET response.
+          @@asset_cache.store(target, status, resp_headers, body_str) if method == 'GET' && cache_mode != 'no-store' && !skip_cache
+          # A no-cors cross-origin response is OPAQUE: status 0, empty body, no exposed
+          # headers, empty URL (cors-basic "Opaque filter"). Otherwise the type is 'cors'
+          # for a cross-origin (CORS-allowed) response, else 'basic'.
+          return response_hash(0, {}, '', '', false, type: 'opaque', body_null: true) if no_cors_mode && crossed
+          return response_hash(status, exposed_headers, body_str, target, redirected, type: crossed ? 'cors' : 'basic', body_null: null_body)
         end
         raise StandardError, "[capybara-simulated] fetch exceeded #{MAX_FETCH_REDIRECTS} redirects"
       rescue StandardError => e
@@ -4304,7 +4633,7 @@ module Capybara
         return unless @trace
         ct = resp_headers && (resp_headers['content-type'] || resp_headers['Content-Type'])
         ct = ct.first if ct.is_a?(Array)  # Rack 3 permits array-valued header fields
-        ct = ct.split(';', 2).first.strip if ct.is_a?(String)
+        ct = ct.split(';', 2).first&.strip if ct.is_a?(String)   # "" → split is [] → first is nil
         size = if resp_body
                  resp_body.bytesize
                elsif (cl = resp_headers && (resp_headers['content-length'] || resp_headers['Content-Length']))
@@ -4345,7 +4674,13 @@ module Capybara
 
       def normalize_trace_headers(headers)
         return nil unless headers
-        headers.each_with_object({}) {|(k, v), out| out[k.to_s] = v.is_a?(Array) ? v.join(', ') : v.to_s }
+        headers.each_with_object({}) do |(k, v), out|
+          # `x-csim-status-text` is an internal sentinel carrying the HTTP reason
+          # phrase (response_hash lifts it into statusText); it's never a real wire
+          # header, so keep it out of the trace.
+          next if k.to_s.downcase == 'x-csim-status-text'
+          out[k.to_s] = v.is_a?(Array) ? v.join(', ') : v.to_s
+        end
       end
 
       # CGI convention: `Content-Type` and `Content-Length` land in env
@@ -4356,7 +4691,14 @@ module Capybara
       # `@rails/request.js` never deserialise and the server reads an
       # empty params hash.
       def apply_request_headers(env, headers)
+        # Preserve the author's exact header names (casing + token chars) alongside the
+        # CGI-mangled HTTP_* keys: the Rack env upcases names and drops non-alphanumerics
+        # (Status-URI → HTTP_STATUS_URI, a tchar-only name → an unrecoverable key), but a
+        # .py echo handler (inspect-headers / echo-headers) reports the names verbatim.
+        # run_py_handler reads this side list to emit the original names.
+        raw = (env['csim.raw_request_headers'] ||= []) if @@capture_raw_request_headers
         headers.each {|k, v|
+          raw << [k.to_s, v.to_s] if raw
           name = k.to_s.upcase.tr('-', '_')
           case name
           when 'CONTENT_TYPE', 'CONTENT_LENGTH' then env[name] = v.to_s
@@ -4375,9 +4717,13 @@ module Capybara
       # text body when `body_b64` is absent.
       TEXT_CONTENT_TYPE_PREFIXES = %w[text/ application/json application/javascript application/ecmascript application/xml image/svg+xml].freeze
 
-      def response_hash(status, headers, body, url, redirected)
+      def response_hash(status, headers, body, url, redirected, type: 'basic', body_null: false)
         raw     = body.to_s
         hdrs    = stringify(headers)
+        # A NUL in a header value is not a valid HTTP message; a real server can't
+        # put it on the wire, so the fetch is a network error (nil → status 0 / a
+        # thrown NetworkError for a sync XHR). See headers-normalize-response.
+        return nil if hdrs.any? {|_, v| v.include?("\u0000") }
         is_text = text_response?(hdrs)
         # `body` crosses as TEXT — `responseText` semantics: the bytes decoded
         # as UTF-8 with invalid sequences replaced (a leading BOM selects the
@@ -4392,18 +4738,43 @@ module Capybara
           else
             RuntimeShared.utf8_text(raw)
           end
+        # statusText = the HTTP reason phrase: a custom one carried on the internal
+        # x-csim-status-text header (status.py), else the status code's standard
+        # reason (xhr status/statusText tests). Strip the internal header either way.
+        custom_reason = hdrs.delete('x-csim-status-text')
+        # Rack::Utils::HTTP_STATUS_CODES values are ASCII-8BIT (binary) strings — the V8
+        # bridge marshals a binary string as a byte array, not a JS string, so statusText
+        # would arrive as [79,75] instead of "OK" (abort-during-loading reads statusText
+        # on a static-file response). utf8_text re-tags + scrubs to a clean JS string, the
+        # same path the body and every header value already take.
+        reason = RuntimeShared.utf8_text(custom_reason || Rack::Utils::HTTP_STATUS_CODES[status.to_i] || '')
+        # HTTP/2 has no reason phrase, so statusText is always the empty string there (a WPT
+        # `.h2` test document's fetches run over h2). We don't model the h2 transport, so key
+        # off the document URL — the same signal WPT uses to serve the resource over h2
+        # (fetch/xhr status.h2 "statusText over H2 … should be the empty string").
+        reason = '' if @current_url.to_s.include?('.h2.')
         out = {
           'status'     => status,
+          'statusText' => reason,
           'headers'    => hdrs,
           'body'       => text,
           'url'        => url,
           'redirected' => redirected,
-          'type'       => 'basic'
+          'type'       => type
         }
+        out['body_null'] = true if body_null   # null-body status / HEAD → response.body is null
         # The BOM-detected encoding (if any) — a frame load pins its document's
         # characterSet to it (see __csimFrameWindow); highest-precedence signal.
         out['charset']  = bom_charset if bom_charset
-        out['body_b64'] = Base64.strict_encode64(raw) unless is_text
+        # Hand the raw bytes to the (XHR) client UNLESS the response is pure-ASCII text.
+        # ASCII decodes identically under every encoding — so responseText is already
+        # correct from the UTF-8 `body`, and it round-trips byte-for-byte as an
+        # ArrayBuffer/Blob. Any NON-ASCII body needs the bytes: a non-UTF-8 charset or an
+        # XML-prolog / <meta charset>-sniffed encoding (responseText), or multibyte UTF-8
+        # read as arraybuffer/blob — the client decodes them with the final encoding
+        # (decodeResponseBytes). `ascii_only?` is a cheap C-level scan, so the dominant
+        # pure-ASCII app JSON/HTML traffic keeps the fast path and pays no base64.
+        out['body_b64'] = Base64.strict_encode64(raw) unless is_text && raw.ascii_only?
         out
       end
 
@@ -4479,6 +4850,34 @@ module Capybara
         buf
       end
 
+      # Transparently decode a Content-Encoding'd response body (HTTP "content coding"):
+      # gzip / x-gzip via Zlib.gunzip; deflate via zlib-wrapped inflate, falling back to
+      # raw DEFLATE (the "deflate" coding is ambiguously used for both). Unknown codings
+      # (e.g. br) and malformed data are left untouched — best-effort, like a browser that
+      # would error, but we keep the bytes so the caller still sees a response.
+      def decode_content_encoding(body, headers)
+        return body if body.nil? || body.empty?
+        raw = headers.find {|k, _| k.to_s.downcase == 'content-encoding' }&.last
+        enc = (raw.is_a?(Array) ? raw.join(',') : raw.to_s).strip.downcase   # Rack 3 may hand the value as an array
+        # The decoded bytes re-enter the UTF-8 text pipeline the same as an
+        # un-encoded body (read_rack_body yields UTF-8), so re-tag them — Zlib
+        # output is ASCII-8BIT, which would otherwise marshal to V8 as a byte array.
+        decoded =
+          case enc
+          when 'gzip', 'x-gzip' then Zlib.gunzip(body.b)
+          when 'deflate'
+            begin
+              Zlib::Inflate.inflate(body.b)
+            rescue Zlib::Error
+              Zlib::Inflate.new(-Zlib::MAX_WBITS).inflate(body.b)   # raw (header-less) DEFLATE
+            end
+          else return body
+          end
+        decoded.force_encoding('UTF-8')
+      rescue Zlib::Error
+        body
+      end
+
       # Defer the navigation: doing it from inside the running V8 call
       # would dispose the Context mid-call. tick_real_time drains
       # after the call returns. Same pattern as `__csimPendingFormSubmit`.
@@ -5555,18 +5954,40 @@ module Capybara
       end
 
       # Header names/values are TEXT (RFC 9110: field values are ASCII); Rack
-      # hands them over BINARY-tagged (see `RuntimeShared.utf8_text`).
+      # hands them over BINARY-tagged (see `RuntimeShared.utf8_text`). Per-value HTTP
+      # -whitespace normalization happens upstream, BEFORE duplicate values are
+      # combined (WptRunner.combine_headers) — not here, where a combined value like
+      # `", "` (two empty fields) would wrongly lose its trailing space. An
+      # Array-valued header (a Rack app emitting a repeated field) is combined with
+      # `, ` — the WHATWG "combine" separator getAllResponseHeaders exposes, matching
+      # both real browsers and the harness's combine_headers.
       def stringify(headers)
         out = {}
         headers.each do |k, v|
-          out[k.to_s] = RuntimeShared.utf8_text(v.is_a?(Array) ? v.join(',') : v.to_s)
+          out[k.to_s] = RuntimeShared.utf8_text(v.is_a?(Array) ? v.join(', ') : v.to_s)
         end
         out
       end
 
+      # The Fetch "redirect status" set — ONLY these are followed. 300 (multiple
+      # choice), 304 (not modified), 305/306 (deprecated) are NOT redirects: the 3xx
+      # response is returned to the caller as-is (xhr send-redirect basics).
+      REDIRECT_STATUSES = [301, 302, 303, 307, 308].freeze
+      # Statuses whose response has no body (Fetch "null body status") — the body is dropped
+      # and response.body is null (response-null-body). (101 is unreachable here.)
+      NULL_BODY_STATUSES = [204, 205, 304].freeze
+      # Request-body headers removed when a redirect nulls the body (method → GET).
+      REDIRECT_DROPPED_HEADERS = %w[content-encoding content-language content-location content-type content-length].freeze
       def redirect_location(status, headers)
-        return nil unless (300..399).include?(status.to_i)
-        headers['location'] || headers['Location']
+        return nil unless REDIRECT_STATUSES.include?(status.to_i)
+        loc = headers['location'] || headers['Location']
+        loc = loc.first if loc.is_a?(Array)   # Rack 3 permits array-valued header fields
+        # A blank (or absent) Location has no FOLLOWABLE target: an empty value parses back
+        # to the current URL, so following it would just self-redirect. Return nil so a
+        # caller renders the 3xx as-is rather than looping — the several navigation handlers
+        # rely on this. (The fetch redirect loop recognizes a present-but-empty Location
+        # separately and turns it into a network error per Fetch — see rack_fetch.)
+        loc unless loc.to_s.empty?
       end
 
       def resolve_against_current(url, use_base: false)
@@ -5596,6 +6017,218 @@ module Capybara
         dom_call('__csimBaseHref').to_s
       end
 
+      # Fetch "CORS-safelisted method" / "…request-header" / "…Content-Type". A request
+      # is "simple" (no preflight) iff its method is safelisted AND every author header is
+      # safelisted (Content-Type only for a urlencoded / multipart / text/plain value).
+      CORS_SAFELISTED_METHODS = %w[GET HEAD POST].freeze
+      CORS_SAFELISTED_HEADERS = %w[accept accept-language content-language content-type].freeze
+      # RFC 7230 `token` (tchar+) — a valid HTTP method / field-name. Used to reject a
+      # preflight whose Access-Control-Allow-Methods / -Headers carries a malformed value.
+      HTTP_TOKEN = /\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/.freeze
+      CORS_SAFELISTED_CTYPES  = %w[application/x-www-form-urlencoded multipart/form-data text/plain].freeze
+
+      # The sorted, lowercased author header names that are NOT CORS-safelisted (a
+      # non-safe Content-Type counts). These are echoed in Access-Control-Request-Headers
+      # for the preflight and must be covered by Access-Control-Allow-Headers.
+      def cors_unsafe_headers(headers)
+        (headers || {}).filter_map {|k, v|
+          name = k.to_s.downcase
+          next if name.start_with?('x-csim') || name == 'content-length'
+          if name == 'content-type'
+            essence = v.to_s.split(';', 2).first.to_s.strip.downcase
+            CORS_SAFELISTED_CTYPES.include?(essence) ? nil : name
+          else
+            CORS_SAFELISTED_HEADERS.include?(name) ? nil : name
+          end
+        }.uniq.sort
+      end
+
+      def cors_unsafe_request?(method, headers)
+        !CORS_SAFELISTED_METHODS.include?(method.to_s.upcase) || !cors_unsafe_headers(headers).empty?
+      end
+
+      # Fetch "CORS check" on a cross-origin response: it must allow the request's
+      # (effective) origin via Access-Control-Allow-Origin. A NON-credentialed request
+      # accepts `*` or the exact origin; a CREDENTIALED one (withCredentials) forbids
+      # `*` — the ACAO must be the exact origin AND Access-Control-Allow-Credentials
+      # must be `true` (access-control-and-redirects-async-same-origin credentials cases).
+      def cors_response_ok?(resp_headers, origin, credentialed)
+        acao = cors_header(resp_headers, 'access-control-allow-origin')
+        return false if acao.nil?
+        if credentialed
+          return false unless acao == origin
+          cors_header(resp_headers, 'access-control-allow-credentials').to_s.downcase == 'true'
+        else
+          acao == '*' || acao == origin
+        end
+      end
+
+      # Whether a URL carries userinfo (`user[:password]@`). A CORS request to such a
+      # URL is a network error (access-control-and-redirects "user info" subtest).
+      def url_has_userinfo?(url)
+        u = URI.parse(url.to_s)
+        !u.userinfo.to_s.empty?
+      rescue URI::InvalidURIError
+        false
+      end
+
+      # An author-set conditional header means the CALLER is doing its own revalidation,
+      # so the UA cache must step aside: the request reaches the origin and the server's
+      # own 304/200 decision is returned (send-conditional), not a cached hit.
+      CONDITIONAL_REQUEST_HEADERS = %w[if-none-match if-modified-since if-match if-unmodified-since if-range].freeze
+      def request_has_conditional_headers?(headers)
+        headers.is_a?(Hash) && headers.any? {|k, _| CONDITIONAL_REQUEST_HEADERS.include?(k.to_s.downcase) }
+      end
+
+      # Run the CORS preflight unless a cached result already covers this request (Fetch
+      # "CORS-preflight cache"): a prior preflight to the same (origin, url) within its
+      # Access-Control-Max-Age that allows this method + headers lets the actual request
+      # skip the OPTIONS (access-control-basic-allow-preflight-cache). Returns false (=
+      # network error) only when a fresh preflight is needed AND fails.
+      def cors_preflight_ok?(target, method, headers, req_origin, credentialed, referer)
+        return true if cors_preflight_cached?(target, req_origin, method, headers, credentialed)
+        result = cors_run_preflight(target, method, headers, req_origin, credentialed, referer)
+        return false unless result
+        # Cache the grant for Max-Age seconds so a covered follow-up skips the preflight.
+        # The key is (origin, url, credentialed): a credentialed grant (ACAO echoing the
+        # origin, no `*` matching) can't cover an uncredentialed follow-up or vice versa,
+        # so the two are cached apart. Expiry uses the REAL monotonic clock (not the
+        # virtual one), so a test that virtual-sleeps past Max-Age to force a re-preflight
+        # isn't caught yet.
+        @cors_preflight_cache[[req_origin, target, credentialed]] = result.merge(stored_at: Process.clock_gettime(Process::CLOCK_MONOTONIC)) if result[:max_age].positive?
+        true
+      end
+
+      # Whether a cached preflight grant covers this request (not expired + method/headers
+      # allowed). A method/header the cache doesn't cover — or an expired entry — forces a
+      # fresh preflight (cache-invalidation-by-method / -header / -timeout).
+      def cors_preflight_cached?(target, req_origin, method, headers, credentialed)
+        entry = @cors_preflight_cache[[req_origin, target, credentialed]]
+        return false unless entry
+        return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) - entry[:stored_at] >= entry[:max_age]
+        cors_grant_allows?(entry[:methods], entry[:headers], method, cors_unsafe_headers(headers), credentialed)
+      end
+
+      # `Authorization` is Fetch's sole "CORS non-wildcard request-header name": a preflight
+      # `Access-Control-Allow-Headers: *` never covers it — it must be listed by name — even
+      # for an uncredentialed request (cors-preflight "authorization not covered by wildcard").
+      CORS_NON_WILDCARD_REQUEST_HEADERS = %w[authorization].freeze
+
+      # Does a preflight grant (its Access-Control-Allow-Methods / -Headers) cover this
+      # request: the method is allowed / `*` / CORS-safelisted, and every unsafe header is
+      # allowed / `*`. Shared by the fresh-preflight accept check and the cache-hit check.
+      # For a CREDENTIALED request the wildcard loses its meaning — Fetch's "CORS-preflight
+      # fetch" matches `*` against no method/header when credentials mode is include, so a
+      # non-listed method or unsafe header is rejected (cors-preflight-star credentialed).
+      def cors_grant_allows?(allow_methods, allow_headers, method, unsafe_headers, credentialed = false)
+        # The method match is byte-CASE-SENSITIVE (Fetch normalizes the request method but
+        # compares it verbatim against Access-Control-Allow-Methods): `delete` in the grant
+        # does not cover a `DELETE` request. Safelisted GET/HEAD/POST pass regardless
+        # (they're always normalized to upper-case) (cors-preflight-star method-case).
+        m = method.to_s
+        method_ok = allow_methods.include?(m) || CORS_SAFELISTED_METHODS.include?(m) || (!credentialed && allow_methods.include?('*'))
+        return false unless method_ok
+        wildcard_headers = !credentialed && allow_headers.include?('*')
+        unsafe_headers.all? {|h|
+          allow_headers.include?(h) || (wildcard_headers && !CORS_NON_WILDCARD_REQUEST_HEADERS.include?(h))
+        }
+      end
+
+      # Fetch "CORS-preflight fetch": send an OPTIONS with Access-Control-Request-Method
+      # / -Headers + Origin; on success (ok-status, ACAO match, and the grant covers the
+      # method + unsafe headers) return the grant {methods, headers, max_age} for the
+      # cache, else nil. A credentialed preflight additionally requires the response to
+      # allow credentials (ACAC:true) and forbids `*` in the origin/method/header grants.
+      def cors_run_preflight(target, method, headers, req_origin, credentialed, referer)
+        unsafe = cors_unsafe_headers(headers)
+        env    = Rack::MockRequest.env_for(target, method: 'OPTIONS')
+        env['REQUEST_METHOD'] = 'OPTIONS'
+        # The preflight's Referer is the request's referrer under its referrer policy —
+        # the SAME value the actual request sends (computed by the caller), not the raw
+        # document URL (cors-preflight-referrer).
+        apply_default_request_env(env, referer: referer, force: false)
+        # A CORS-preflight is a fetch, so it carries fetch's default `Accept: */*` (NOT
+        # the navigation Accept apply_default_request_env sets) — some handlers reject a
+        # preflight whose Accept isn't */* (preflight.py).
+        env['HTTP_ACCEPT'] = '*/*'
+        # A CORS-preflight is always uncredentialed — it carries no cookies, even when the
+        # actual request that follows is credentialed.
+        env.delete('HTTP_COOKIE')
+        env['HTTP_ORIGIN'] = req_origin
+        # Access-Control-Request-Method carries the request's (already-normalized) method
+        # VERBATIM — `patch` stays `patch`, matching the byte-case-sensitive grant check.
+        env['HTTP_ACCESS_CONTROL_REQUEST_METHOD'] = method.to_s
+        env['HTTP_ACCESS_CONTROL_REQUEST_HEADERS'] = unsafe.join(',') unless unsafe.empty?
+        status, ph, pbody = dispatch_rack_or_http(target, env, method: 'OPTIONS', body: nil)
+        pbody.close if pbody.respond_to?(:close)
+        return nil unless (200..299).include?(status.to_i)
+        acao = cors_header(ph, 'access-control-allow-origin')
+        # A credentialed preflight can't be allowed by the wildcard origin and must carry
+        # Access-Control-Allow-Credentials: true (cors-preflight-star credentialed).
+        return nil unless credentialed ? acao == req_origin : (acao == '*' || acao == req_origin)
+        return nil if credentialed && cors_header(ph, 'access-control-allow-credentials') != 'true'
+        allow_methods = cors_list(cors_header(ph, 'access-control-allow-methods'))
+        allow_headers = cors_list(cors_header(ph, 'access-control-allow-headers')).map(&:downcase)
+        # Fetch "extract header list values" fails when a grant contains a malformed token
+        # (`Access-Control-Allow-Methods: Bad value` — a space isn't a tchar), and a failed
+        # extraction is a network error (cors-preflight-response-validation). Methods and
+        # header names are both HTTP tokens; `*` is a valid tchar so the wildcard passes.
+        return nil unless (allow_methods + allow_headers).all? {|t| t.match?(HTTP_TOKEN) }
+        return nil unless cors_grant_allows?(allow_methods, allow_headers, method, unsafe, credentialed)
+        {methods: allow_methods, headers: allow_headers, max_age: cors_header(ph, 'access-control-max-age').to_i}
+      end
+
+      # Fetch "CORS-safelisted response-header name" — always exposed to script for a
+      # cross-origin response, without being listed in Access-Control-Expose-Headers.
+      CORS_SAFELISTED_RESPONSE_HEADERS = %w[
+        cache-control content-language content-length content-type expires last-modified pragma
+      ].freeze
+
+      # The response headers a cross-origin "cors" response exposes to getResponseHeader /
+      # getAllResponseHeaders: the CORS-safelisted set plus any named in Access-Control
+      # -Expose-Headers (`*` exposes all — only valid without credentials, which these
+      # cases don't use).
+      def cors_exposed_headers(headers)
+        # set-cookie / set-cookie2 are forbidden response-header names — NEVER exposed to
+        # script, even under `Access-Control-Expose-Headers: *`. x-csim-status-text is our
+        # internal reason-phrase sentinel (response_hash lifts it into statusText, which
+        # IS exposed cross-origin, then strips it from the script-visible map), so it must
+        # survive the filter.
+        forbidden = %w[set-cookie set-cookie2]
+        expose    = cors_list(cors_header(headers, 'access-control-expose-headers')).map(&:downcase)
+        return headers.reject {|k, _| forbidden.include?(k.to_s.downcase) } if expose.include?('*')
+        allowed = CORS_SAFELISTED_RESPONSE_HEADERS + expose + ['x-csim-status-text']
+        headers.select {|k, _| allowed.include?(k.to_s.downcase) }
+      end
+
+      # Case-insensitive response-header lookup + comma-list split for the CORS checks.
+      def cors_header(headers, name)
+        pair = headers.find {|k, _| k.to_s.downcase == name }
+        pair&.last.to_s
+      end
+
+      def cors_list(value)
+        value.to_s.split(',').map(&:strip).reject(&:empty?)
+      end
+
+      # The origin of a URL — `scheme://host[:port]` with the default port (80/443)
+      # elided — for the CORS same/cross-origin comparison. nil for a non-http(s) or
+      # unparseable URL (about:blank / data: / a relative current_url) so CORS never
+      # treats those as a comparable origin.
+      def url_origin(url)
+        u = URI.parse(url.to_s)
+        return nil unless u.scheme && u.host && u.scheme.match?(/\Ahttps?\z/i)
+        # An origin is (scheme, host, port) compared case-insensitively on scheme+host —
+        # so canonicalize both to lowercase, else http://Example.com vs http://example.com
+        # would mis-classify a same-origin request as cross-origin.
+        scheme  = u.scheme.downcase
+        default = scheme == 'https' ? 443 : 80
+        port    = u.port && u.port != default ? ":#{u.port}" : ''
+        "#{scheme}://#{u.host.downcase}#{port}"
+      rescue URI::InvalidURIError
+        nil
+      end
+
       def carry_fragment(from_url, to_url)
         from = URI.parse(from_url.to_s)
         to   = URI.parse(to_url.to_s)