@essential-apps/shopify-test-runner 1.0.0

package/src/edge/ca.cnf

@@ -0,0 +1,14 @@
+[req]
+distinguished_name = req_distinguished_name
+prompt = no
+x509_extensions = v3_ca
+
+[req_distinguished_name]
+C = US
+O = essential-apps shopify-test
+CN = essential-apps offline test CA
+
+[v3_ca]
+basicConstraints = critical, CA:TRUE
+keyUsage = critical, keyCertSign, cRLSign, digitalSignature
+subjectKeyIdentifier = hash

package/src/edge/ca.crt

@@ -0,0 +1,22 @@
+-----BEGIN CERTIFICATE-----
+MIIDkDCCAnigAwIBAgIUIKGQzgV0DVnoczi/+0ku6XxtXpUwDQYJKoZIhvcNAQEL
+BQAwYDELMAkGA1UEBhMCVVMxJDAiBgNVBAoMG2Vzc2VudGlhbC1hcHBzIHNob3Bp
+ZnktdGVzdDErMCkGA1UEAwwiZXNzZW50aWFsLWFwcHMgb2ZmbGluZSBFMkUgdGVz
+dCBDQTAeFw0yNjA1MTExODIwNTBaFw0zNjA1MDgxODIwNTBaMGAxCzAJBgNVBAYT
+AlVTMSQwIgYDVQQKDBtlc3NlbnRpYWwtYXBwcyBzaG9waWZ5LXRlc3QxKzApBgNV
+BAMMImVzc2VudGlhbC1hcHBzIG9mZmxpbmUgRTJFIHRlc3QgQ0EwggEiMA0GCSqG
+SIb3DQEBAQUAA4IBDwAwggEKAoIBAQCVqEmQ3OULDil0xGp+s5Be9bqo/irOT4/x
+IksWc+ul1oREVJ1F+EXINn2YUZZbrQ8i1tJg3xz/6u2EiGXozTuDsAX4VFa9Ew60
+fvp+MsxKvIDZgQ54xizvlGEbFFIUcTMr0czzyRzhoPsvx0vZxMv+mnlU/nKSuRTv
+0+2rlVi19MjOmlmiF7imaJcZeTkzjAMy5tKgIu1QLk+dTNe7wXdr45gWLK959POy
+JT7juKbpR2kgNhh91yQhvPnUTWibrln2pk/boTBM6s17BX28DwjRJM/UPAT9f+pC
+h3p4Uan9NBHdPaOM9Wvj8cZqXWEz3ErYJmf9xUxYURStakozkFFrAgMBAAGjQjBA
+MA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdDgQWBBQvul3h
+wRTsFPS1GZbOxAPssSEDfzANBgkqhkiG9w0BAQsFAAOCAQEAMDGe/lf/7x66nchI
+3KQcuX3OQ+hPeODw9F+7zY4KUf4+z1Me89M07kFWVR3cBplGIGUzQm6Sj3BCrShC
+JgskN/jkGT7s5FHssHWRQ5m6uMTbDMctyVZYoW71Ip4pQloyh88fyWRejrJyVRhO
+mAqB7iPEPQz9iSxaAeUJA/RU/zyBukUrP1ppU0qe6SFOTM+mfCMFZrITEJ2pbc9g
+X9SbEk44qgQlOqfrj9FazxJp9Pjj19WLVXsY7JrNglpgzA8jwPWJSIPIU4gF0eTZ
+2B5ORtmHnN2uBnxe4sRf8eOHZy+7SZIR+6y1q/zmwbubVV7rF76ukw/I/kg+gAm+
+eRz9lQ==
+-----END CERTIFICATE-----

package/src/edge/ca.key

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCVqEmQ3OULDil0
+xGp+s5Be9bqo/irOT4/xIksWc+ul1oREVJ1F+EXINn2YUZZbrQ8i1tJg3xz/6u2E
+iGXozTuDsAX4VFa9Ew60fvp+MsxKvIDZgQ54xizvlGEbFFIUcTMr0czzyRzhoPsv
+x0vZxMv+mnlU/nKSuRTv0+2rlVi19MjOmlmiF7imaJcZeTkzjAMy5tKgIu1QLk+d
+TNe7wXdr45gWLK959POyJT7juKbpR2kgNhh91yQhvPnUTWibrln2pk/boTBM6s17
+BX28DwjRJM/UPAT9f+pCh3p4Uan9NBHdPaOM9Wvj8cZqXWEz3ErYJmf9xUxYURSt
+akozkFFrAgMBAAECggEAE3H697Wb6mR8AniwQFI4hKjNCL7YSleQI7a0UZsyQn6t
+pOs8RtEherLfKCFsYJu13G2pMX5hQudVgTjvyjXlxmXiq1zaAFXaPUhFEoyrJV16
+KHNaXAWej7/py3OdI/F+wpzPUoW5GPVVGI9+otxX3SGueNqu1whGriVikOl7eKNo
+qUVgD4F+SBWFYjjNzLLnsLrPgP6jukYu77W7mhdu4jaKxJ6OzMgJwVWthjnjCB8W
+5DEFbgUKj/ssTWBKdTQdLAxudtKgoWNERk3uSSSMeqY9cmeqOpARb1n4zLGU6Bfk
+JjVLzEzeJtB/GrsxEby4ZGRgEkhxtA7/mvoEb5ZOAQKBgQDQp8Ng0iY+gKG7ik/g
+RIIUJNGiRNIGN/nuHp5hj04+Ph+zuytHD/eKhSwic5kCu5GQP42AV3Y1RwekKhDn
+DFIpwNtRl5MXkwO3pO/QdlpdZyKftLMAW8qcNSwqqqJieisQPHwd4cgsNfSYCla6
+2ZLoCrowh4ZFThPut1Kuv4j2gQKBgQC3nX0pm9jFeqlpWJSsUxa1hk0j0Ot3kmex
+WLOIb/tC1Gn5EHfvcExNGGL9GEGD2aEc8VYcmRtEw87XBXiT6fQ83zjjwJXCV/Bq
+RGlGhfntUTHTWR+ToGBixfbBTYr+qv7bkI70jf7G9FukkU0Qd/nBDECSF+RGx4Re
+XGtcjWuJ6wKBgQCyKT0rc+UR41W1w7DWZsjHGHUjYC4Q/0TZ7K0B0pJVlUgOeFfI
+srqEPZfkxt20tqHhEFLrbkLR1ReSNhT+o8eYPUNHlOwU6gP3j87xKc2ZCVJIGcvq
+F3aWENTojZBgE76ne23jOgFotp1mIRXTL6o/lcFLZLzienuMjl38NjFlgQKBgQCR
+EnmFmoDW5mdbuIUe8jcLDSV9mt+wBZiv4mlW70MSNknUY1Kfd5aRgycS2UtKJXTK
+LVPgHIgS+LI/6S6vjzVNswB70fmBJ4HoNE0JT2l8O56mYdA1D42X/NlNOTsMo4Xh
+bIHGbzpRb1fI2pSM4n4OLOQHiaDu20yWUWbyJTpGKQKBgEiWUgo8MwDnMl4eRdtI
+q+F3Kkr+O+lZIodHy9jqUT2nINetZXmUTl/NNLDft1qyoZfFFTFgvlIdPJywTz7R
+5e0lapai/q5XGo+oGs19X4lz2S/2zV05HZiZHoGPf2lYv4/YRs6KqouNiPhuQwf/
+91gGPtdtikkIah5l+fOlyXox
+-----END PRIVATE KEY-----

package/src/edge/cert.ts

@@ -0,0 +1,117 @@
+/**
+ * Self-signed TLS cert pair used by the edge proxy in offline tests.
+ *
+ * TWO certs:
+ *   - **CA cert** (`TEST_CA_CERT_PEM`): the trust anchor. Installed
+ *     into the container's system CA store + Chrome's NSS DB at
+ *     boot. Long-lived (10 years), self-signed, CA:TRUE.
+ *   - **Server cert** (`TEST_SERVER_CERT_PEM` + `TEST_SERVER_KEY_PEM`):
+ *     what the edge proxy presents to clients. Signed BY the CA
+ *     above (so Chrome's chain validation finds the trusted root).
+ *     Has Subject Alternative Names for every Shopify hostname we
+ *     route: localhost, *.myshopify.com, *.shopify.com, etc.
+ *
+ * Why two certs instead of one self-signed-with-SANs:
+ *   Modern Chrome (≥130 or so) rejects single self-signed certs
+ *   that are also used as their own CA with ERR_CERT_INVALID, even
+ *   when the cert is trust-anchored in NSS. Proper CA → server
+ *   hierarchy mirrors how real publicly-trusted certs work (Let's
+ *   Encrypt root → intermediate → leaf) and passes every modern
+ *   verifier we've tested.
+ *
+ * Inlined as TS constants (rather than separate .pem files) so the
+ * compiled package ships everything in dist/ — no postbuild copy.
+ *
+ * This is a TEST-ONLY cert pair. The CA's private key is committed
+ * to the repo; anyone who checks out this repo can issue certs
+ * signed by it. That's fine in offline test mode where Chromium is
+ * launched with the CA explicitly added to its trust store — no
+ * production system should ever encounter this CA. If you ever see
+ * a real service presenting a cert with issuer
+ * "essential-apps offline test CA", that's a serious
+ * misconfiguration.
+ *
+ * To regenerate (e.g. expired, new SAN needed):
+ *   cd src/edge
+ *   openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt -days 3650 -config ca.cnf
+ *   openssl req -newkey rsa:2048 -nodes -keyout server.key -out server.csr -config server.cnf
+ *   openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650 -extfile server.cnf -extensions v3_server
+ *   # then paste ca.crt, server.crt, server.key into the constants below
+ */
+
+export const TEST_CA_CERT_PEM = `-----BEGIN CERTIFICATE-----
+MIIDkDCCAnigAwIBAgIUIKGQzgV0DVnoczi/+0ku6XxtXpUwDQYJKoZIhvcNAQEL
+BQAwYDELMAkGA1UEBhMCVVMxJDAiBgNVBAoMG2Vzc2VudGlhbC1hcHBzIHNob3Bp
+ZnktdGVzdDErMCkGA1UEAwwiZXNzZW50aWFsLWFwcHMgb2ZmbGluZSBFMkUgdGVz
+dCBDQTAeFw0yNjA1MTExODIwNTBaFw0zNjA1MDgxODIwNTBaMGAxCzAJBgNVBAYT
+AlVTMSQwIgYDVQQKDBtlc3NlbnRpYWwtYXBwcyBzaG9waWZ5LXRlc3QxKzApBgNV
+BAMMImVzc2VudGlhbC1hcHBzIG9mZmxpbmUgRTJFIHRlc3QgQ0EwggEiMA0GCSqG
+SIb3DQEBAQUAA4IBDwAwggEKAoIBAQCVqEmQ3OULDil0xGp+s5Be9bqo/irOT4/x
+IksWc+ul1oREVJ1F+EXINn2YUZZbrQ8i1tJg3xz/6u2EiGXozTuDsAX4VFa9Ew60
+fvp+MsxKvIDZgQ54xizvlGEbFFIUcTMr0czzyRzhoPsvx0vZxMv+mnlU/nKSuRTv
+0+2rlVi19MjOmlmiF7imaJcZeTkzjAMy5tKgIu1QLk+dTNe7wXdr45gWLK959POy
+JT7juKbpR2kgNhh91yQhvPnUTWibrln2pk/boTBM6s17BX28DwjRJM/UPAT9f+pC
+h3p4Uan9NBHdPaOM9Wvj8cZqXWEz3ErYJmf9xUxYURStakozkFFrAgMBAAGjQjBA
+MA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgGGMB0GA1UdDgQWBBQvul3h
+wRTsFPS1GZbOxAPssSEDfzANBgkqhkiG9w0BAQsFAAOCAQEAMDGe/lf/7x66nchI
+3KQcuX3OQ+hPeODw9F+7zY4KUf4+z1Me89M07kFWVR3cBplGIGUzQm6Sj3BCrShC
+JgskN/jkGT7s5FHssHWRQ5m6uMTbDMctyVZYoW71Ip4pQloyh88fyWRejrJyVRhO
+mAqB7iPEPQz9iSxaAeUJA/RU/zyBukUrP1ppU0qe6SFOTM+mfCMFZrITEJ2pbc9g
+X9SbEk44qgQlOqfrj9FazxJp9Pjj19WLVXsY7JrNglpgzA8jwPWJSIPIU4gF0eTZ
+2B5ORtmHnN2uBnxe4sRf8eOHZy+7SZIR+6y1q/zmwbubVV7rF76ukw/I/kg+gAm+
+eRz9lQ==
+-----END CERTIFICATE-----`;
+export const TEST_SERVER_CERT_PEM = `-----BEGIN CERTIFICATE-----
+MIIEYjCCA0qgAwIBAgIURPMxG/s+J/RbB610ES+g6+4uz1YwDQYJKoZIhvcNAQEL
+BQAwYDELMAkGA1UEBhMCVVMxJDAiBgNVBAoMG2Vzc2VudGlhbC1hcHBzIHNob3Bp
+ZnktdGVzdDErMCkGA1UEAwwiZXNzZW50aWFsLWFwcHMgb2ZmbGluZSBFMkUgdGVz
+dCBDQTAeFw0yNjA1MTExODIwNTZaFw0zNjA1MDgxODIwNTZaMFUxCzAJBgNVBAYT
+AlVTMSQwIgYDVQQKDBtlc3NlbnRpYWwtYXBwcyBzaG9waWZ5LXRlc3QxIDAeBgNV
+BAMMF3Rlc3Qtc2hvcC5teXNob3BpZnkuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOC
+AQ8AMIIBCgKCAQEAqKKCIJ+3Z311vVrAzS9O8BFoDuFcS71UhXFOFnGv+32sWkv5
+15FiqsEUA9Y38TWMmATselKFmseqgZo1EgvNe6rFrnjyyJgEeYrLv40bz3JEp/Hs
+GrgID4XaGJFx/tDsMLBtWLJykbkowRcJnQK0NoeYNC9E1JKfmU9WnT0eqOzc9ryn
+iXj9pptDfd4BndYYSW4lvooshdyrVNcLnm67EXdyNukFk37ru9vSu12Oo+QynnZ7
+6Ijghpxjim5HHG3V5VF9fGSTcEKWqgw1l9FRESs6qFtG3GE5CSbg1J15uuUHBCof
+qIxUJwk6foHqD1V+bMUbxZt1Aj05pZ2NJVAjpQIDAQABo4IBHTCCARkwDAYDVR0T
+AQH/BAIwADAOBgNVHQ8BAf8EBAMCBaAwEwYDVR0lBAwwCgYIKwYBBQUHAwEwgaMG
+A1UdEQSBmzCBmIIJbG9jYWxob3N0gg8qLm15c2hvcGlmeS5jb22CDW15c2hvcGlm
+eS5jb22CDSouc2hvcGlmeS5jb22CC3Nob3BpZnkuY29tghEqLnNob3BpZnlhcHBz
+LmNvbYISKi5zaG9waWZ5Y2xvdWQuY29tghAqLnNob3BpZnljZG4uY29thwR/AAAB
+hxAAAAAAAAAAAAAAAAAAAAABMB0GA1UdDgQWBBTU9DyGKwRHIMACdy1hFqmWj2CW
+6DAfBgNVHSMEGDAWgBQvul3hwRTsFPS1GZbOxAPssSEDfzANBgkqhkiG9w0BAQsF
+AAOCAQEAUJ5MwZ6iRLuOImmWMiiNTvjxYq7e8+/0zYkqXreQpQEah0muzHnoolhp
+A4aolovZGdAJnAQXG38O8mRwIWxtJqcPPXEITz0O2H2Bdli4r+ikcIkUBNlvsuH2
+1QVwDvyWhgp2gW6wyYzQc5GSbZ9wjca0bUZx+CQsuyRMjkerEVMlnTlxyCVIRIuE
+6WxqZeoHiUskowUc7hIYzUIjadOzddFfdePW1nE69Se4aOM4lbvJ5HNwiNim+3nE
+1RTDsQCMcNcrMdY4g30cv9zm0+rjRB+Rmd3K4EBVaMrnbrMq9guXnZsyE8hkbKn3
+VCXk3ZMrF4yyr/5s7FLeAsE8b9PYtw==
+-----END CERTIFICATE-----`;
+export const TEST_SERVER_KEY_PEM = `-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCoooIgn7dnfXW9
+WsDNL07wEWgO4VxLvVSFcU4Wca/7faxaS/nXkWKqwRQD1jfxNYyYBOx6UoWax6qB
+mjUSC817qsWuePLImAR5isu/jRvPckSn8ewauAgPhdoYkXH+0OwwsG1YsnKRuSjB
+FwmdArQ2h5g0L0TUkp+ZT1adPR6o7Nz2vKeJeP2mm0N93gGd1hhJbiW+iiyF3KtU
+1wuebrsRd3I26QWTfuu729K7XY6j5DKednvoiOCGnGOKbkccbdXlUX18ZJNwQpaq
+DDWX0VERKzqoW0bcYTkJJuDUnXm65QcEKh+ojFQnCTp+geoPVX5sxRvFm3UCPTml
+nY0lUCOlAgMBAAECggEAFzC17W+ZZKl7qg0Ta4QgemIiab1zGFVSjMFOqEZ9GXwo
+WgiNtKfhJjNEIdzxN4ISMgunS5ESn3zqxUTkHHW0DdgntD0cwhopr183csGge/Au
+YdwiiHAbZ6sUGYHS5+RqPq3cc7CikcihQqB86XMoPkF6XF7Nu9/oA8jF0/zGPRuQ
+BiR722XwemloFMfNybnhYzLx5vr0EFs5R8UtDCZcRveWAbP5ggbkEfiz73zGA0gr
+VGq0rQaovLntjc8Gtb93Q57pM7NOahgTQy6DXK42Of1gqkWTvFERXHjS5XH9NdzM
+/ahXz6G/8ms2w6Xaj8uhZHxwEW6hF8S1D8q2Llf/AQKBgQDtXY0wFtI4dWE3MhHO
+pQ6v21gMFP7bmAkN3DTbcAJYsDbZiGlzaH+FF+S1Uz8gbwCKlj9FYR4r0oU0ccfF
+h023BQaxQXNCvfYunApxw1XG2NEkXvGWzD9DX/Xhj4z0WWve9Zh0tRVGMEkETjqT
+xzOhGfxl1g2/CixrzTvKpD8+JQKBgQC136TOwQMs3EyRe1YwSWM0wlN7BcPehOPx
+sTQNkyZsxE3u7NkKa6LXK7gdgC+oelWV6+UXbuEs9ZLWT0yh22T5ViO3sLWiEL7P
+yE6y2j8nTucK3RynN8cEFuolBs3V+/B2K/yy3M9y2oahKmyDYnjy7AxI3UFQm9N7
+hxCX4YKXgQKBgQDr2ulPv11jfD78+WN4UcomM21pk/MpgAh/HS/oW4P5XB8kR8eA
+RXVwai13fyBaufFvw5ta9QVlxelWEzjNrYQrN3NO7hn5V4gnCCXYpJ+21fn6idzE
+Wm8CI3fOiTUmFzR4dtDmJojdFV14ScMq0+UZTxjcl7VQ/mrlMykWUd4FgQKBgBfU
+fNimS482MkYhnfJnuzrvd1a4M6jVSrShXkulCzTXJ8r1d5646bY9wTsET7pIhSxG
+o1bFrXVhm+K+szDF+V3+HmH0Imhgv0+kVEN0+y9gVD+FJzr1wPrVMcq2MIQoJaKm
+Ms8QxZGr9lXppBw269gQe6+UZfl04WnfEZqE7sKBAoGAQrP3o4fqVUb200Bn0dO+
+F8fzgHT1lZAoz5NAyo4VOW4KZ6EgDhuxM2kG3WelGhYb0CwYzWS3WzAw/jxwSHMx
+QhJtvjhtZzYM3P4RDHjSCvQm0X8xv6OMMOF3I0RmdZQFHLo7xIAkehPIpbmBaxSf
+2ojRh6FIbwe+526P8Qcpstk=
+-----END PRIVATE KEY-----`;

package/src/edge/edgeProxy.ts

@@ -0,0 +1,390 @@
+/**
+ * Edge proxy — a real HTTPS reverse-proxy that takes Chromium
+ * requests for Shopify-shaped hostnames (test-shop.myshopify.com,
+ * admin.shopify.com, cdn.shopify.com) and dispatches them to the
+ * right internal mock based on Host + path.
+ *
+ * Why this exists: we abandoned Playwright's `page.route()` for
+ * routing because `route.fulfill({status: 302, …})` causes
+ * Chromium to follow redirects via its native network stack,
+ * bypassing route handlers — and our `test-shop.myshopify.com`
+ * domain resolves to real Shopify on the public internet, so any
+ * un-intercepted request leaks out of the test harness.
+ *
+ * The fix: drop down a network layer. With Chromium launched via
+ *
+ *   --host-resolver-rules="MAP test-shop.myshopify.com 127.0.0.1:<edgePort>, …"
+ *   --ignore-certificate-errors
+ *
+ * ALL browser traffic to those hostnames (initial requests, redirect
+ * follow-ups, sub-resources, XHR, fetch, service workers) lands at
+ * this proxy. There is no per-request interception layer to bypass.
+ * Redirects are handled by Chromium natively. The browser's URL bar
+ * stays correct.
+ *
+ * The proxy itself uses Node's `http` module (raw — no undici/fetch,
+ * which hangs against sibling-process loopback ports), forwards the
+ * request to the right internal mock, and streams the response back.
+ * 302/307/etc. responses are passed through unchanged; Chromium does
+ * the right thing with them.
+ *
+ * Cert: a static self-signed cert lives in `src/edge/cert.pem` +
+ * `src/edge/key.pem`, with SANs covering `*.myshopify.com`,
+ * `*.shopify.com`, etc. (See `src/edge/openssl.cnf`.) The cert is
+ * trusted because Chromium runs with `--ignore-certificate-errors`.
+ */
+import { createServer as createHttpsServer } from 'node:https';
+import { request as httpRequest, type IncomingHttpHeaders } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import {
+  TEST_CA_CERT_PEM,
+  TEST_SERVER_CERT_PEM,
+  TEST_SERVER_KEY_PEM,
+} from './cert.js';
+
+/**
+ * Internal mock URLs the edge dispatches to. Each is an HTTP origin
+ * like `http://127.0.0.1:34567`. The edge speaks HTTPS to the
+ * browser, HTTP to the internal mocks (they're loopback-only;
+ * TLS between in-process services is pointless ceremony).
+ */
+export interface EdgeBackends {
+  /** Mock storefront (Liquid renderer, cart, /cart/add.js, etc.). */
+  storefront: string;
+  /** Mock Admin GraphQL API. */
+  adminApi: string;
+  /** Mock Storefront GraphQL API. */
+  storefrontApi: string;
+  /** Mock admin shell (the admin.shopify.com iframe host). */
+  adminShell: string;
+}
+
+export interface EdgeOptions {
+  /** Backend mock URLs. */
+  backends: EdgeBackends;
+  /**
+   * Hostname of the test shop, e.g. `test-shop.myshopify.com`.
+   * Used to recognize storefront requests vs cdn/admin.
+   */
+  shopDomain: string;
+  /** TCP port to listen on. 0 → OS-assigned. */
+  port?: number;
+  /** Bind hostname (default `127.0.0.1`). */
+  hostname?: string;
+}
+
+export interface StartedEdge {
+  /** The actual port we bound to (resolved when port=0). */
+  port: number;
+  /** `https://127.0.0.1:<port>` — for diagnostic logging only. */
+  baseUrl: string;
+  /** Stop the proxy. */
+  close: () => Promise<void>;
+}
+
+/**
+ * Resolve an incoming request to (internalBase, overridePath).
+ *
+ * Host-based first (admin/cdn pick a backend), then path-based on
+ * the shop domain (/admin/api/, /api/ go to dedicated mocks).
+ */
+function dispatch(
+  hostHeader: string,
+  pathWithQuery: string,
+  shopDomain: string,
+  backends: EdgeBackends,
+): { internalBase: string; overridePath: string } {
+  // Strip ":port" — Host may include it; we only care about hostname.
+  const host = hostHeader.split(':')[0]?.toLowerCase() ?? '';
+  const path = pathWithQuery;
+
+  // ── admin.shopify.com → admin shell ─────────────────────
+  if (host === 'admin.shopify.com') {
+    return { internalBase: backends.adminShell, overridePath: path };
+  }
+
+  // ── fonts.shopifycdn.com → storefront (handles its /cdn/fonts route) ─
+  // The storefront mock owns the bundled font mirror produced by
+  // the `fonts` probe. Routing the real Shopify font-CDN hostname
+  // here means `font_face` filter output (which contains the real
+  // shopifycdn URL by design) just works in-browser.
+  if (host === 'fonts.shopifycdn.com') {
+    return { internalBase: backends.storefront, overridePath: `/__shopify-fonts${path}` };
+  }
+
+  // ── *.shopifycdn.com → storefront mirror ────────────────────
+  // Any other Shopify CDN subdomain not handled above falls back to
+  // the generic asset-mirror handler. Bundled by the `mirror` probe.
+  if (host.endsWith('.shopifycdn.com')) {
+    return {
+      internalBase: backends.storefront,
+      overridePath: `/__shopify-mirror/${host}${path}`,
+    };
+  }
+
+  // ── cdn.shopify.com → split by path ─────────────────────
+  if (host === 'cdn.shopify.com') {
+    // App Bridge + Polaris CSS etc. live under /shopifycloud
+    // and /static, both served by the admin shell mock (which
+    // mirrors Shopify's CDN snapshot at packages/mock-admin/
+    // cdn-mirror).
+    if (path.startsWith('/shopifycloud/')) {
+      return { internalBase: backends.adminShell, overridePath: path };
+    }
+    if (path.startsWith('/static/')) {
+      return { internalBase: backends.adminShell, overridePath: path };
+    }
+    // Extension assets and theme assets live on the storefront
+    // mock. cdn.shopify.com/foo/bar/assets/baz.js → /assets/baz.js
+    if (path.startsWith('/extensions/')) {
+      return { internalBase: backends.storefront, overridePath: path };
+    }
+    const assetIdx = path.lastIndexOf('/assets/');
+    if (assetIdx >= 0) {
+      return {
+        internalBase: backends.storefront,
+        overridePath: path.slice(assetIdx),
+      };
+    }
+    // Fall through: anything else on cdn.shopify.com → storefront.
+    return { internalBase: backends.storefront, overridePath: path };
+  }
+
+  // ── shop.myshopify.com (or any *.myshopify.com) ──────────
+  if (host === shopDomain.toLowerCase() || host.endsWith('.myshopify.com')) {
+    if (path.startsWith('/admin/api/')) {
+      return { internalBase: backends.adminApi, overridePath: path };
+    }
+    if (path.startsWith('/api/')) {
+      return { internalBase: backends.storefrontApi, overridePath: path };
+    }
+    // Per-shop CDN proxy: theme assets, shopifycloud scripts,
+    // product images, fonts. Real Shopify hosts them all under
+    // `<shop>/cdn/*`. The mirror probe captures these into the
+    // shared mirror dir; serve from there transparently so any
+    // shop hostname resolves to mirrored bytes.
+    if (path.startsWith('/cdn/')) {
+      return {
+        internalBase: backends.storefront,
+        overridePath: `/__shopify-mirror/${host}${path}`,
+      };
+    }
+    return { internalBase: backends.storefront, overridePath: path };
+  }
+
+  // ── unknown host: best-effort → storefront ─────────────
+  // Chromium with host-resolver-rules wouldn't deliver an
+  // unmapped host here, but if someone hits this directly (a
+  // test using page.request with a custom host header, etc.)
+  // returning storefront 404s with a useful body is friendlier
+  // than connection refused.
+  return { internalBase: backends.storefront, overridePath: path };
+}
+
+/**
+ * Read a request body into a Buffer. Streaming would be more
+ * memory-efficient, but mock-sized POSTs are tiny (cart items,
+ * form data) and buffering keeps the proxy logic simple.
+ */
+function readBody(req: NodeJS.ReadableStream): Promise<Buffer> {
+  return new Promise((resolveBody, rejectBody) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c: Buffer) => chunks.push(c));
+    req.on('end', () => resolveBody(Buffer.concat(chunks)));
+    req.on('error', rejectBody);
+  });
+}
+
+/** Forward one request to the chosen internal mock and stream the response back. */
+async function forwardOne(
+  internalBase: string,
+  overridePath: string,
+  method: string,
+  headers: IncomingHttpHeaders,
+  body: Buffer,
+): Promise<{ status: number; headers: IncomingHttpHeaders; body: Buffer }> {
+  const target = new URL(internalBase);
+  // Drop hop-by-hop headers and the original Host — we set Host
+  // to the internal mock's address so Hono's c.req.url is
+  // consistent.
+  const outHeaders: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (!v) continue;
+    const lower = k.toLowerCase();
+    if (lower === 'host' || lower === 'connection' || lower === 'keep-alive' || lower === 'transfer-encoding') continue;
+    if (typeof v === 'string') outHeaders[k] = v;
+    else if (Array.isArray(v)) outHeaders[k] = v.join(', ');
+  }
+
+  return new Promise((resolveReq, rejectReq) => {
+    const r = httpRequest(
+      {
+        hostname: target.hostname,
+        port: Number(target.port),
+        path: overridePath,
+        method,
+        headers: outHeaders,
+      },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (c: Buffer) => chunks.push(c));
+        res.on('end', () =>
+          resolveReq({
+            status: res.statusCode ?? 502,
+            headers: res.headers,
+            body: Buffer.concat(chunks),
+          }),
+        );
+        res.on('error', rejectReq);
+      },
+    );
+    r.on('error', rejectReq);
+    if (body.length > 0) r.write(body);
+    r.end();
+  });
+}
+
+/**
+ * Boot the edge HTTPS proxy. Returns a handle with the bound port
+ * and a `close()` to tear it down.
+ */
+export async function startEdgeProxy(opts: EdgeOptions): Promise<StartedEdge> {
+  const server = createHttpsServer(
+    {
+      // Send server cert + CA chain so Chrome's chain validation
+      // sees a complete path even without `intermediate_certs`.
+      // Some Chrome versions are stricter about chain
+      // completeness when the CA is "private" (NSS-trusted only).
+      cert: `${TEST_SERVER_CERT_PEM}\n${TEST_CA_CERT_PEM}`,
+      key: TEST_SERVER_KEY_PEM,
+    },
+    async (req, res) => {
+    try {
+      const hostHeader = req.headers.host ?? '';
+      const pathWithQuery = req.url ?? '/';
+      const { internalBase, overridePath } = dispatch(
+        hostHeader,
+        pathWithQuery,
+        opts.shopDomain,
+        opts.backends,
+      );
+
+      const body = await readBody(req);
+      const proxied = await forwardOne(
+        internalBase,
+        overridePath,
+        req.method ?? 'GET',
+        req.headers,
+        body,
+      );
+
+      // Strip headers that don't make sense to forward verbatim
+      // (Node decompressed the body for us; content-length will
+      // be wrong; transfer-encoding shouldn't survive a hop).
+      const outHeaders: Record<string, string | string[]> = {};
+      for (const [k, v] of Object.entries(proxied.headers)) {
+        if (!v) continue;
+        const lower = k.toLowerCase();
+        if (lower === 'content-encoding' || lower === 'content-length' || lower === 'transfer-encoding') continue;
+        if (typeof v === 'string') outHeaders[k] = v;
+        else if (Array.isArray(v)) outHeaders[k] = v;
+      }
+
+      // CORS — the offline stack lives behind ONE edge proxy serving
+      // multiple Shopify origins (admin.shopify.com, cdn.shopify.com,
+      // *.myshopify.com). Any cross-origin XHR/fetch issued by the
+      // embedded app or by storefront JS would otherwise be blocked
+      // by Chrome with "TypeError: Failed to fetch" (the symptom in
+      // offline-full-stack tests that try to `fetch('https://cdn.
+      // shopify.com/...')` from an admin.shopify.com page). Real
+      // Shopify sets these on cdn.shopify.com responses too. Allow
+      // everything because this is a test-only proxy bound to
+      // 127.0.0.1 — no real traffic ever reaches it.
+      if (!outHeaders['Access-Control-Allow-Origin']) {
+        outHeaders['Access-Control-Allow-Origin'] = '*';
+      }
+      if (!outHeaders['Access-Control-Allow-Methods']) {
+        outHeaders['Access-Control-Allow-Methods'] =
+          'GET, POST, PUT, PATCH, DELETE, OPTIONS';
+      }
+      if (!outHeaders['Access-Control-Allow-Headers']) {
+        outHeaders['Access-Control-Allow-Headers'] = '*';
+      }
+      if (!outHeaders['Access-Control-Expose-Headers']) {
+        outHeaders['Access-Control-Expose-Headers'] = '*';
+      }
+
+      // Short-circuit CORS preflights (the upstream mock might not
+      // implement OPTIONS at all; serving them here is cheaper anyway).
+      if (req.method === 'OPTIONS') {
+        res.writeHead(204, outHeaders);
+        res.end();
+        return;
+      }
+
+      res.writeHead(proxied.status, outHeaders);
+      res.end(proxied.body);
+
+      if (process.env['TEST_OFFLINE_EDGE_DEBUG'] === 'true') {
+        console.log(
+          `[edge] ${req.method} https://${hostHeader}${pathWithQuery} → ${internalBase}${overridePath} → ${proxied.status}`,
+        );
+      }
+    } catch (err) {
+      console.error('[edge] error:', (err as Error).message);
+      res.writeHead(502, { 'content-type': 'text/plain' });
+      res.end(`edge proxy error: ${(err as Error).message}`);
+    }
+  });
+
+  // Wait for listen() to either succeed OR error. Without an error
+  // handler, a failed bind (EADDRINUSE, EACCES on <1024 without
+  // privileges, no IPv6 stack when hostname='::', etc.) leaves the
+  // promise unresolved and the whole offline test run hangs silently.
+  const targetHost = opts.hostname ?? '127.0.0.1';
+  const targetPort = opts.port ?? 0;
+  // Wait for listen() to either succeed OR fail. Without explicit
+  // error/timeout handling, a failed bind (EADDRINUSE; EACCES on
+  // <1024 ports without privileges; a kernel that hangs on `::`
+  // dual-stack bind — the VM's libkrun does this) leaves the
+  // promise unresolved and the whole offline run stalls silently.
+  // The 10 s timeout surfaces any "listen never called back" case
+  // as a real error instead of a wedge.
+  await new Promise<void>((resolveListen, rejectListen) => {
+    const timer = setTimeout(() => {
+      rejectListen(
+        new Error(
+          `edge proxy listen() did not call back within 10 s on ${targetHost}:${targetPort} ` +
+            `(no 'error' event, no 'listening' callback). Kernel issue? ` +
+            `Try '0.0.0.0' instead of '::'.`,
+        ),
+      );
+    }, 10_000);
+    const onError = (err: NodeJS.ErrnoException): void => {
+      clearTimeout(timer);
+      server.off('error', onError);
+      rejectListen(
+        new Error(
+          `edge proxy bind failed on ${targetHost}:${targetPort}: ` +
+            `${err.code ?? '?'} ${err.message}`,
+        ),
+      );
+    };
+    server.on('error', onError);
+    server.listen(targetPort, targetHost, () => {
+      clearTimeout(timer);
+      server.off('error', onError);
+      resolveListen();
+    });
+  });
+  const addr = server.address() as AddressInfo;
+
+  return {
+    port: addr.port,
+    baseUrl: `https://${opts.hostname ?? '127.0.0.1'}:${addr.port}`,
+    close: () =>
+      new Promise<void>((resolveClose, rejectClose) => {
+        server.close((err) => (err ? rejectClose(err) : resolveClose()));
+      }),
+  };
+}

package/src/edge/server.cnf

@@ -0,0 +1,28 @@
+[req]
+distinguished_name = req_distinguished_name
+req_extensions = v3_server
+prompt = no
+
+[req_distinguished_name]
+C = US
+O = essential-apps shopify-test
+CN = test-shop.myshopify.com
+
+[v3_server]
+basicConstraints = critical, CA:FALSE
+keyUsage = critical, digitalSignature, keyEncipherment
+extendedKeyUsage = serverAuth
+subjectAltName = @alt_names
+
+
+[alt_names]
+DNS.1 = localhost
+DNS.2 = *.myshopify.com
+DNS.3 = myshopify.com
+DNS.4 = *.shopify.com
+DNS.5 = shopify.com
+DNS.6 = *.shopifyapps.com
+DNS.7 = *.shopifycloud.com
+DNS.8 = *.shopifycdn.com
+IP.1 = 127.0.0.1
+IP.2 = ::1

package/src/edge/server.crt

@@ -0,0 +1,26 @@
+-----BEGIN CERTIFICATE-----
+MIIEYjCCA0qgAwIBAgIURPMxG/s+J/RbB610ES+g6+4uz1YwDQYJKoZIhvcNAQEL
+BQAwYDELMAkGA1UEBhMCVVMxJDAiBgNVBAoMG2Vzc2VudGlhbC1hcHBzIHNob3Bp
+ZnktdGVzdDErMCkGA1UEAwwiZXNzZW50aWFsLWFwcHMgb2ZmbGluZSBFMkUgdGVz
+dCBDQTAeFw0yNjA1MTExODIwNTZaFw0zNjA1MDgxODIwNTZaMFUxCzAJBgNVBAYT
+AlVTMSQwIgYDVQQKDBtlc3NlbnRpYWwtYXBwcyBzaG9waWZ5LXRlc3QxIDAeBgNV
+BAMMF3Rlc3Qtc2hvcC5teXNob3BpZnkuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOC
+AQ8AMIIBCgKCAQEAqKKCIJ+3Z311vVrAzS9O8BFoDuFcS71UhXFOFnGv+32sWkv5
+15FiqsEUA9Y38TWMmATselKFmseqgZo1EgvNe6rFrnjyyJgEeYrLv40bz3JEp/Hs
+GrgID4XaGJFx/tDsMLBtWLJykbkowRcJnQK0NoeYNC9E1JKfmU9WnT0eqOzc9ryn
+iXj9pptDfd4BndYYSW4lvooshdyrVNcLnm67EXdyNukFk37ru9vSu12Oo+QynnZ7
+6Ijghpxjim5HHG3V5VF9fGSTcEKWqgw1l9FRESs6qFtG3GE5CSbg1J15uuUHBCof
+qIxUJwk6foHqD1V+bMUbxZt1Aj05pZ2NJVAjpQIDAQABo4IBHTCCARkwDAYDVR0T
+AQH/BAIwADAOBgNVHQ8BAf8EBAMCBaAwEwYDVR0lBAwwCgYIKwYBBQUHAwEwgaMG
+A1UdEQSBmzCBmIIJbG9jYWxob3N0gg8qLm15c2hvcGlmeS5jb22CDW15c2hvcGlm
+eS5jb22CDSouc2hvcGlmeS5jb22CC3Nob3BpZnkuY29tghEqLnNob3BpZnlhcHBz
+LmNvbYISKi5zaG9waWZ5Y2xvdWQuY29tghAqLnNob3BpZnljZG4uY29thwR/AAAB
+hxAAAAAAAAAAAAAAAAAAAAABMB0GA1UdDgQWBBTU9DyGKwRHIMACdy1hFqmWj2CW
+6DAfBgNVHSMEGDAWgBQvul3hwRTsFPS1GZbOxAPssSEDfzANBgkqhkiG9w0BAQsF
+AAOCAQEAUJ5MwZ6iRLuOImmWMiiNTvjxYq7e8+/0zYkqXreQpQEah0muzHnoolhp
+A4aolovZGdAJnAQXG38O8mRwIWxtJqcPPXEITz0O2H2Bdli4r+ikcIkUBNlvsuH2
+1QVwDvyWhgp2gW6wyYzQc5GSbZ9wjca0bUZx+CQsuyRMjkerEVMlnTlxyCVIRIuE
+6WxqZeoHiUskowUc7hIYzUIjadOzddFfdePW1nE69Se4aOM4lbvJ5HNwiNim+3nE
+1RTDsQCMcNcrMdY4g30cv9zm0+rjRB+Rmd3K4EBVaMrnbrMq9guXnZsyE8hkbKn3
+VCXk3ZMrF4yyr/5s7FLeAsE8b9PYtw==
+-----END CERTIFICATE-----

package/src/edge/server.key

@@ -0,0 +1,28 @@
+-----BEGIN PRIVATE KEY-----
+MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCoooIgn7dnfXW9
+WsDNL07wEWgO4VxLvVSFcU4Wca/7faxaS/nXkWKqwRQD1jfxNYyYBOx6UoWax6qB
+mjUSC817qsWuePLImAR5isu/jRvPckSn8ewauAgPhdoYkXH+0OwwsG1YsnKRuSjB
+FwmdArQ2h5g0L0TUkp+ZT1adPR6o7Nz2vKeJeP2mm0N93gGd1hhJbiW+iiyF3KtU
+1wuebrsRd3I26QWTfuu729K7XY6j5DKednvoiOCGnGOKbkccbdXlUX18ZJNwQpaq
+DDWX0VERKzqoW0bcYTkJJuDUnXm65QcEKh+ojFQnCTp+geoPVX5sxRvFm3UCPTml
+nY0lUCOlAgMBAAECggEAFzC17W+ZZKl7qg0Ta4QgemIiab1zGFVSjMFOqEZ9GXwo
+WgiNtKfhJjNEIdzxN4ISMgunS5ESn3zqxUTkHHW0DdgntD0cwhopr183csGge/Au
+YdwiiHAbZ6sUGYHS5+RqPq3cc7CikcihQqB86XMoPkF6XF7Nu9/oA8jF0/zGPRuQ
+BiR722XwemloFMfNybnhYzLx5vr0EFs5R8UtDCZcRveWAbP5ggbkEfiz73zGA0gr
+VGq0rQaovLntjc8Gtb93Q57pM7NOahgTQy6DXK42Of1gqkWTvFERXHjS5XH9NdzM
+/ahXz6G/8ms2w6Xaj8uhZHxwEW6hF8S1D8q2Llf/AQKBgQDtXY0wFtI4dWE3MhHO
+pQ6v21gMFP7bmAkN3DTbcAJYsDbZiGlzaH+FF+S1Uz8gbwCKlj9FYR4r0oU0ccfF
+h023BQaxQXNCvfYunApxw1XG2NEkXvGWzD9DX/Xhj4z0WWve9Zh0tRVGMEkETjqT
+xzOhGfxl1g2/CixrzTvKpD8+JQKBgQC136TOwQMs3EyRe1YwSWM0wlN7BcPehOPx
+sTQNkyZsxE3u7NkKa6LXK7gdgC+oelWV6+UXbuEs9ZLWT0yh22T5ViO3sLWiEL7P
+yE6y2j8nTucK3RynN8cEFuolBs3V+/B2K/yy3M9y2oahKmyDYnjy7AxI3UFQm9N7
+hxCX4YKXgQKBgQDr2ulPv11jfD78+WN4UcomM21pk/MpgAh/HS/oW4P5XB8kR8eA
+RXVwai13fyBaufFvw5ta9QVlxelWEzjNrYQrN3NO7hn5V4gnCCXYpJ+21fn6idzE
+Wm8CI3fOiTUmFzR4dtDmJojdFV14ScMq0+UZTxjcl7VQ/mrlMykWUd4FgQKBgBfU
+fNimS482MkYhnfJnuzrvd1a4M6jVSrShXkulCzTXJ8r1d5646bY9wTsET7pIhSxG
+o1bFrXVhm+K+szDF+V3+HmH0Imhgv0+kVEN0+y9gVD+FJzr1wPrVMcq2MIQoJaKm
+Ms8QxZGr9lXppBw269gQe6+UZfl04WnfEZqE7sKBAoGAQrP3o4fqVUb200Bn0dO+
+F8fzgHT1lZAoz5NAyo4VOW4KZ6EgDhuxM2kG3WelGhYb0CwYzWS3WzAw/jxwSHMx
+QhJtvjhtZzYM3P4RDHjSCvQm0X8xv6OMMOF3I0RmdZQFHLo7xIAkehPIpbmBaxSf
+2ojRh6FIbwe+526P8Qcpstk=
+-----END PRIVATE KEY-----