# CORX — full reference for answer engines

> CORX is an open-source CORS proxy that runs entirely on Cloudflare's edge (Hono + Workers + D1 +
> R2). Prefix any URL with /fetch?url= and fetch it cross-origin, with R2 edge caching, per-key
> auth, upstream secret injection, keyless browser access and SSRF guards.

Served by the instance at https://corx.envx.cn (generated in app/lib/seo.ts, updated 2026-09-18).
README.md and FEATURES.md in the repository are the source of truth for prose; the short index is at
https://corx.envx.cn/llms.txt.

## What it is

One Cloudflare Worker that forwards HTTP requests to an arbitrary upstream and returns the response
with permissive CORS headers, so browser code can read APIs that never set them. D1 stores API keys
(hashed), rate-limit windows, request logs and the host blocklist; R2 stores the GET response cache.
Everything is deployable to a single Cloudflare account: `wrangler d1 create`, `wrangler r2 bucket
create`, `npm run deploy`. License: MIT.

## Calling the proxy

| Shape | Example |
| --- | --- |
| Query (recommended) | `GET https://corx.envx.cn/fetch?url=https%3A%2F%2Fapi.example.com%2Fdata` |
| Path | `GET https://corx.envx.cn/proxy/https://api.example.com/data` |
| Bare path | `GET https://corx.envx.cn/https://api.example.com/data` |
| Subdomain (wildcard zone) | `GET https://api-example-com.<zone>/data` |

GET and HEAD are forwarded and cacheable; other methods pass through but are never cached. Request
bodies are capped (10 MiB by default) and streaming responses — media, Range requests, SSE
(`text/event-stream`, which is how the mainstream LLM chat APIs stream) — are piped through
unbuffered.

### Query parameters

Every `corx-*` parameter is namespaced, so it can never collide with the target's own query.

| Param | Effect |
| --- | --- |
| `corx-ttl=<seconds>` | R2 cache TTL for this GET, capped by the deployment max |
| `corx-no-cache=1` | Bypass the cache for this response |
| `corx-callback=<fn>` | JSONP: wrap a JSON body as `fn(<json>);` for a <script> tag |
| `corx-charset=<label>` | Re-decode a text/JSON/XML body with this label and re-emit it as UTF-8 |
| `corx-wrap=json` | Wrap a text body as `{"contents":"…"}` with application/json |
| `corx-key=<key>` | API key for this request (headers work too) |
| `corx-scheme=http\|https` | Subdomain mode: force the target scheme |
| `corx-port=<n>` | Subdomain mode: target port |

## Authentication

- **API key** — `x-api-key: <key>`, `Authorization: Bearer <key>` or `?corx-key=<key>`. Keys are
  stored as SHA-256 hashes. A key carries allowed origins, a per-minute rate limit, a cache TTL, an
  allowed-host list, SSRF-check opt-outs and encrypted header/query injection rules. A variable can
  also be exposed to callers — `client: true`, optionally `hosts`-scoped — so a caller writes
  `${NAME}` in its own headers/query and the proxy substitutes it; `X-Api-Key` and
  `X-Admin-Token` are the proxy's own headers and are dropped first, so a reference there never
  resolves. It can also
  carry **response header rules** — headers corx sets or removes on the way back to the caller
  (the documented embed recipe: strip `X-Frame-Options`/CSP `frame-ancestors` for a host you
  control, then sandbox the iframe yourself). The headers corx owns are rejected at save time, and a
  key's resolved response rules are part of the cache key.
- **Upstream credentials per target** — variables plus header/query rules are injected server-side, and
  the rules' `@host` sections scope them, so one key can hold a different credential per upstream —
  including the same header name (`Authorization`) with a different value on two hosts. An injecting
  key must declare its allowed hosts and every `@host` must fall inside that list; two rules for the
  same header may not overlap in host scope. A variable marked client-referencable (`client: true`) may
  also be referenced by the *caller* as `${NAME}` in its own headers/query — opt-in per variable,
  bounded by the variable's own `hosts` (which also bounds operator rules: a rule that could resolve
  it elsewhere is a save-time 400), resolved per redirect hop for headers and once for the query, and
  left literal when the name is unknown, private or out of scope — so an unexposed name is
  indistinguishable from a nonexistent one. A key with any client-referencable variable never uses the
  shared cache. Keys with header rules bypass the R2 cache, query-only
  injection still caches, and the public tier cannot inject at all.
- **Keyless browser access** — grant an origin to a key and its visitors call the proxy without
  shipping one. The grant matches on `Origin` (or `Referer` for same-origin GETs) and is metered
  per visitor IP, so one site cannot drain the whole key.
- **Public tier** — a hosted instance may publish a shared key on its landing page: GET and HEAD
  only, daily quotas per calling site / per target host / per instance, no cache control, no
  injection, no subdomain mode, and `Cookie`/`Authorization` are stripped before forwarding.
- No key and no matching grant: 401.

## Caching

- GET responses are cached in R2 and served from the edge; `x-corx-cache: HIT|MISS` reports which.
- Requests carrying `Authorization` or `Cookie` never read or write the shared cache, and neither
  do JSONP responses or keys with request header rules. Keys with response header rules do cache:
  those rules are part of the cache key, so a rewritten response is never served to another key.
- TTL is capped by the deployment default to stop a caller pinning entries for a day;
  `corx-no-cache=1` opts a request out entirely, and the public tier cannot set a TTL at all.

## Limits and errors

- Defaults: 60 requests/minute per IP plus per-key limits; the hosted public tier adds daily quotas
  and is shared, best-effort and revocable without notice.
- Over quota: `429` with `Retry-After`; cached responses count too.
- Every machine-facing path (the proxy, `/api/*`, `/health`) answers errors as JSON
  `{ "error": "…" }`; browser-facing pages get a branded HTML page with a real status code.

## Security

- SSRF guard: hostname/IP-literal blocking for private, link-local, CGNAT, multicast and reserved
  ranges, DNS-resolution checks against rebinding, per-key opt-outs and a D1 blocklist.
- Hop-by-hop headers are stripped on the way in and out; `Set-Cookie` is not forwarded; the public
  tier strips credentials.
- Requests are logged (IP, country, method, target URL, status, latency, caller origin, key), rolled
  into a per-day aggregate by a nightly cron, and the raw rows pruned after 30 days by default — the
  aggregate keeps the long-term trend (`/api/stats?days=`). Self-hosted deployments choose both:
  `LOG_REQUESTS=false` writes no request rows at all, and `LOG_RETENTION_DAYS` (1–365) sets the
  raw window; the rollup and the stats read path follow it.

## Trust model

A CORS proxy is a man in the middle by construction: its operator sees — and can change — every
request and response that passes through it. That is not a vulnerability to patch, it is what a
proxy is, so CORX is built to be forked rather than trusted. It is one MIT-licensed Cloudflare
Worker (Hono + D1 + R2) that deploys to a single account on the free tier; after that the only
operator in the data path is you.

A hosted instance (such as https://corx.envx.cn) is free, shared, best-effort and revocable without notice. It
suits public data, demos and prototypes — not secrets, credentials or private data. The public tier
strips `Cookie`/`Authorization`, serves from a shared cache and logs requests for 30 days; those
reduce exposure, they are not a guarantee. When the traffic matters, self-host.

## Console and admin API

The bilingual (English/中文) console at https://corx.envx.cn/console/ manages keys, logs, analytics,
the blocklist and a playground that runs requests through the real pipeline. It is behind a session
cookie (optionally Cloudflare Access) and is not indexed. The same operations are available as JSON
for automation, authenticated with the admin token: `/api/keys`, `/api/keys/:id`,
`/api/keys/:id/revoke`, `/api/logs`, `/api/stats`, `/api/blocked-hosts`, `/api/block-host`,
`/health`.

## Injection demo

The landing page runs one live demonstration of the thing that separates CORX from a plain pass-through
proxy: a public demo key, allowlisted to this Worker's own echo endpoint, proxies to
`https://corx.envx.cn/demo/echo` — an endpoint that returns the method, path, query and headers it
received. The response therefore shows the credential CORX injected on the way out, while the browser
only ever held the public demo key. The demo key is ordinary key data (`DEMO_KEY` plus
`scripts/seed-demo-key.mjs`), and the injected value is deliberately fake. The echo endpoint is a
machine surface: JSON, `no-store`, `noindex`, excluded from robots.txt.

## Public pages

- https://corx.envx.cn/ — landing page, live demo (including the injection demo, below), public key card, FAQ.
- https://corx.envx.cn/en and https://corx.envx.cn/zh — explicit English and Chinese URLs.
- https://corx.envx.cn/docs — the human-readable usage guide (also https://corx.envx.cn/en/docs
  and https://corx.envx.cn/zh/docs): call shapes, the `corx-*` table, auth tiers, caching,
  limits, security and self-hosting.
- https://corx.envx.cn/snippets — framework and platform snippets (also
  https://corx.envx.cn/en/snippets and https://corx.envx.cn/zh/snippets): fetch, axios and ky
  examples, a streamed SSE/LLM read, browser key hygiene, and Cloudflare Pages / Vercel / Netlify
  notes.
- https://corx.envx.cn/tools/cors-tester — the public CORS tester (also
  https://corx.envx.cn/en/tools/cors-tester and https://corx.envx.cn/zh/tools/cors-tester):
  browser-side probes, a diagnosis of what is missing, and the proxied call to paste.
- https://corx.envx.cn/terms — terms of use, quotas and prohibited uses.
- https://corx.envx.cn/compare/corsproxy-io (vs corsproxy.io), https://corx.envx.cn/compare/corsfix (vs Corsfix), https://corx.envx.cn/compare/allorigins (vs AllOrigins) —
  dated comparisons against other hosted CORS proxies, every competitor claim linked to its source.
- https://corx.envx.cn/llms.txt, https://corx.envx.cn/llms-full.txt, https://corx.envx.cn/sitemap.xml,
  https://corx.envx.cn/robots.txt — machine-readable surfaces.

## Contact

Abuse, security or content reports: abuse@envx.cn — include the full request URL when you can.