Sites Relay

English | Chinese

Sites Relay is a policy-constrained, fixed-upstream relay for ChatGPT Sites, with JSON/SSE streaming and an optional sanitized static web mirror. Server-side runtime values define every upstream destination.

ChatGPT Sites can keep runtime secrets on the server, but every application still needs a safe boundary between visitors and its upstream. Sites Relay packages that boundary as a reusable, fail-closed project:

• keep upstream credentials in server-side runtime values
• authenticate with either a proxy token or an exact ChatGPT user allowlist
• permit only configured method-path pairs and query keys
• stream JSON and Server-Sent Events as chunks arrive
• optionally expose sanitized, read-only HTML/CSS/image/font content

Typical uses include streaming AI applications, internal dashboards backed by one private API, and authenticated documentation or status mirrors. Read the copy-paste examples and project roadmap.

Use Sites Relay when a Site needs one trusted HTTPS upstream, protected credentials, JSON/SSE streaming, and an explicit server-side policy. A dedicated remote-browser architecture provides authenticated, full browser compatibility.

The primary API relay is designed for JSON APIs and Server-Sent Events (SSE), including AI APIs with streaming responses. The upstream origin, client access mode, method-path policy, query policy, and upstream credentials are controlled by server-side runtime values.

The optional static web mirror serves sanitized HTML, rewritten CSS, images, and fonts from the same fixed upstream. Enable it explicitly for GET and HEAD access to policy-approved static content. See docs/static-web-mirror.md for its complete contract.

The current relay remains fixed-upstream and application-layer only. See docs/web-compatibility-direction.md for the separate remote-browser architecture proposed for authenticated, full web compatibility.

Node.js 22.13 or later is required.

Copy-Item .env.example .env.local
npm install
npm run dev

Edit .env.local, then open http://localhost:3000. The runtime panel reports static configuration state; use a side-effect-free relay request to verify upstream reachability.

This is the canonical runtime configuration contract. Store production secrets in Sites runtime values and local secrets in .env.local.

.env.example mirrors this contract. Manage production values through Sites runtime values.

The endpoint is /api/proxy/*. After the method-path policy passes, the proxy path is appended to the fixed upstream origin; every query parameter must be explicitly allowed. Each request retains the server-configured upstream scheme, host, and port.

In the default token mode, clients send x-proxy-token. In sites-user mode, same-origin browser requests authenticate through the Sites identity and the exact PROXY_ALLOWED_USER_EMAILS allowlist. Both modes authenticate before route policy is evaluated.

curl -N "$SITE_URL/api/proxy/v1/responses" \
  -H "x-proxy-token: $PROXY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"model":"your-model","input":"Hello"}'

Request limits:

• Forwarded methods: GET, HEAD, and POST; OPTIONS terminates locally as CORS preflight.
• The method and path must match PROXY_ALLOWED_ROUTES; query access starts from an empty allowlist.
• POST bodies use non-empty, uncompressed UTF-8 JSON up to 1 MiB.
• Forwarded request headers: Accept, Content-Type, Last-Event-ID, and a validated Idempotency-Key.
• The relay rebuilds upstream headers from the documented forwarded header set and server-side upstream credentials.
• Upstream responses are limited to application/json, application/*+json, and text/event-stream.
• Upstream 3xx responses terminate with upstream_redirect_blocked.
• The upstream connection wait is limited to 15 seconds; JSON is limited to 8 MiB/60 seconds and SSE to 64 MiB/15 minutes.

Response bodies stream as chunks arrive. Byte and time limits bound every streamed response.

The optional /web/* surface provides authenticated, sanitized static content from the same configured upstream.

Read docs/static-web-mirror.md before enabling it. The mirror combines Sites access control with an exact ChatGPT user email allowlist.

GET /api/health returns a secret-free configuration summary:

• setup_required: required runtime values are missing
• invalid: values are present but invalid
• ready: configuration passed static validation; verify reachability with a live side-effect-free request

ready returns HTTP 200; setup_required and invalid return HTTP 503. OPTIONS is reported separately as the local preflight method.

Set EXPOSE_UPSTREAM_HOST=true to display the exact upstream hostname; the default public status returns upstreamHost: null.

API errors use stable English error codes. Common errors include:

The proxy fails closed: missing or invalid configuration stops forwarding. It authenticates either a proxy token or an exact Sites user email before applying method-path policy, rebuilds upstream headers, separates client access from upstream credentials, rejects multiply encoded path bypasses and response types that could execute as same-origin content, and marks every response no-store.

Sites-user authentication and the static mirror trust identity only when it is supplied behind the Sites dispatcher. A direct local or Worker request can forge an ordinary identity header and must not be treated as an equivalent production boundary. Keep identity-protected deployments behind Sites access controls.

Configure a hostname you control or trust, enforce quotas and rate limits upstream, and pair client authentication with the Sites access policy.

The repository includes a Codex Skill at .agents/skills/operate-sites-relay/. Future agents can invoke $operate-sites-relay to load the architecture, security contract, validation commands, and private Sites deployment workflow.

See docs/CONTRIBUTING.md for the development setup, validation workflow, pull request checklist, and Conventional Commits rules.

• Examples
• Roadmap
• Static web mirror contract
• Custom domains and named-user access
• Full web compatibility direction
• Security policy

1. Open this project in ChatGPT and build it with the built-in Sites capability.
2. Keep the first deployment owner-only.
3. Set all required runtime values in Sites, then save and deploy a new version.
4. Check /api/health, then call a side-effect-free allowed path. Treat the upstream as reachable only after a real request succeeds.

npm run typecheck
npm run lint
npm test

npm test runs the production build first.

After deployment, also verify:

• missing config, wrong tokens or disallowed Sites users, out-of-policy paths, and invalid origins all fail as expected
• cookies, client Authorization, and identity headers do not reach the upstream
• JSON returns normally and the first SSE chunk arrives before the stream ends
• the API relay does not pass through HTML, redirects, or Set-Cookie
• when the static mirror is enabled, anonymous and non-allowlisted users are denied before policy checks, active content is removed, and only allowed paths, queries, assets, and same-policy redirects remain