Headers & CORS
On this page 10 sections
HTTP header reference
Headers are conditional: not every core response or upstream passthrough includes QSCS diagnostics. Names are HTTP headers; values below describe the current implementation. Ignore unknown diagnostic values safely and use status plus Content-Type to handle the response.
Client request headers
| Header | Value / purpose |
|---|---|
X-QSCS-Client-Uuid | Client identifier, conventionally 32 lowercase hex characters. Identifies the key binding; not authentication by itself. |
X-QSCS-Ts | Unix milliseconds as decimal digits. |
X-QSCS-Nonce | Fresh 16-byte random nonce encoded as 32 lowercase hex characters. |
X-QSCS-Sig | Base64 Ed25519 signature over the canonical request. See signing reference. |
X-QSCS-Delta | Decoder capability: 1 for legacy deltas, 2 for JSON byte-delta support. Omit without a compatible decoder. |
X-QSCS-Base-Hash | FNV-1a 32-bit hash of the exact retained baseline bytes, encoded as eight lowercase hex digits. Scoped to the requested URL and client. |
X-QSCS-Base-Key | Legacy input; current client-delta baseline selection does not use it for cross-URL reconstruction. |
X-QSCS-Stream | 1 requests API Boost streaming on the same signed GET. |
X-QSCS-Stream-Delta | 2 opts into stream delta frames; requires a compatible decoder. |
X-QSCS-Stream-Base | Retained stream payload’s SHA-256 as 64 lowercase hex characters. Different algorithm from X-QSCS-Base-Hash. |
X-QSCS-Browser-Navigation | 1 is used by the packaged navigation worker; not needed by a normal API client. |
Response headers
| Header | Meaning / availability |
|---|---|
X-QSCS-Mode | Delivery diagnostic. See values below; absence is valid on some routes. |
X-QSCS-Encoding | base64 for encoded client delta bodies. |
X-QSCS-Payload-Bytes | Logical complete payload size when emitted. |
X-QSCS-Wire-Bytes | Path-specific transfer accounting. Negotiated client deltas report transferred delta/body bytes; some cache/peer paths report upstream or substrate bytes saved even while sending a full body to the caller. It is not a universal HTTP download-size counter. |
X-QSCS-Origin-State | unchanged indicates an origin comparison; the current response may still contain a complete body. |
X-QSCS-Cache | HIT, PERSISTED or PEER on relevant cache paths. |
X-QSCS-Cache-Mode | api-boost, until-invalidated or timed on federated cache hits. |
X-QSCS-Cache-Age | Saved response age in seconds on API Boost hits. |
X-QSCS-TTL-Remaining | Remaining configured reuse time in seconds on timed hits. |
X-QSCS-Stream | 1 on an API event stream. Event payloads carry their own ids; stream bytes are not ordinary response-delta frames. |
X-QSCS-Headless-Reason | Fallback or outage reason; see HEADLESS response table. |
X-QSCS-Headless-Age | Seconds since the fallback cache entry’s refresh, where emitted. |
X-QSCS-Headless-Session | degraded on listener fallback responses; not a session token and not emitted on every fallback path. |
X-QSCS-Browser-Navigation | on or off for processed HTML navigation policy. |
X-QSCS-Browser-Cache | eligible or bypass for processed HTML navigation baselines. |
Mode values
| Value | Interpretation |
|---|---|
full | Full representation. |
incremental | Delta processing occurred; use content type/encoding to distinguish a client delta from a reconstructed full body. |
nochange | Unchanged state. On a negotiated client response with an empty body, reuse the verified baseline. |
hit | Timed cache response. |
persisted | PersistCache response. |
peerpull | State recovered from a peer. |
federated-identity-hit | Account-partitioned cache hit; further client negotiation may replace this mode. |
negcache | Negative-cache response, such as a cached 404. |
passthrough | Live/bypass path or application-specific unavailable response. |
headless | Origin fallback; check HTTP status and reason. |
Verified headers sent to your backend
HTTP — verified upstream context
X-QSCS-Identity: <client UUID>
X-QSCS-Authenticated-Subject: account:42
X-QSCS-Identity-Issuer: app.example.com
QSCS removes client-supplied copies on its proxy path before adding verified values. Accept them only through restricted QSCS ingress. Resolve the subject and enforce account status and permissions in your backend. These are upstream authorization context, not credentials for a client to set.
Inspect a response
Shell / curl — response headers
curl -sS -D - -o /dev/null 'https://app.example.com/'
For browser JavaScript, the edge must expose headers the client reads; see Headers & CORS. X-QSCS-Reconstructed: 1 is added by the browser adapter to its reconstructed Response and is not a core wire header.
Browser CORS contract
CORS is enforced by browsers and is independent of backend language. Native and server clients still need valid authentication even though they do not enforce browser CORS. A successful preflight neither authenticates a caller nor confirms that the target application endpoint exists.
OPTIONS /{path}
Authentication: none. Body: none. Core answers before origin routing without calling the backend. The public proxy may intercept OPTIONS or replace its response.
HTTP request
OPTIONS /api/report HTTP/1.1
Host: api.example.com
Origin: https://app.example.com
Access-Control-Request-Method: GET
Access-Control-Request-Headers: x-qscs-client-uuid,x-qscs-ts,x-qscs-nonce,x-qscs-sig
Default core response — selected headers
HTTP/1.1 200 OK
Content-Length: 0
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Cache-Control, Content-Type, X-QSCS-Client-Uuid, X-QSCS-Ts, X-QSCS-Nonce, X-QSCS-Sig, X-QSCS-Delta, X-QSCS-Base-Hash, X-QSCS-Stream, X-QSCS-Stream-Delta, X-QSCS-Stream-Base
Access-Control-Expose-Headers: X-QSCS-Mode, X-QSCS-Encoding, X-QSCS-Wire-Bytes, X-QSCS-Payload-Bytes, X-QSCS-Cache
Access-Control-Max-Age: 86400
Response policy and proxy configuration
Core applies its default CORS policy on normal listener/proxy paths. API stream responses expose X-QSCS-Stream. Not every early error or runtime-asset response has the same header set, so verify the actual public response.
- Choose one CORS policy at the public edge and avoid duplicate or conflicting Allow-Origin values.
- Preserve the signature, delta and stream request headers shown above.
- Expose
X-QSCS-Streamfor browser streaming. AddX-QSCS-Cache-Mode,X-QSCS-Cache-Age,X-QSCS-TTL-Remainingor outage diagnostics if your application reads them. - For conditional status reads, allow
If-None-Matchand exposeETag; they are not in the default lists above. - For cookies, configure an explicit allowed origin and credential policy. A wildcard Allow-Origin does not permit credentialed browser reads. The packaged signed API client uses credentials omitted.
- Keep origin authentication and backend access restrictions in place. CORS is not an authorization mechanism.
The default preflight does not advertise arbitrary application headers such as Authorization, or unsupported write methods. Configure required application headers explicitly at the edge; adding a method to CORS does not add daemon support for that method.
Check the public preflight
Shell / curl
curl -i -X OPTIONS 'https://api.example.com/api/report' \
-H 'Origin: https://app.example.com' \
-H 'Access-Control-Request-Method: GET' \
-H 'Access-Control-Request-Headers: x-qscs-client-uuid,x-qscs-ts,x-qscs-nonce,x-qscs-sig'
Also inspect the actual GET, including its error responses. curl displays the headers but does not enforce browser CORS.