Headers · XB Field Notes

Cache freshness is judged against a clock

Fri, 03 Dec 2027 00:00:00 +0000

A cache does not receive a new freshness allowance every time another cache forwards a response. It must account for age already accumulated along the delivery path, then add its own residence time. Otherwise a chain of individually plausible sixty-second caches can keep old content reusable much longer than the origin intended.

Count the age

Age estimates seconds since generation or successful validation, including time in caches and transit. The received Age field is therefore an input to current age, not a counter that stays frozen while the response sits locally. Date supplies the response’s origination timestamp. Clock synchronization and measured request/response timing matter when relating those values.

RFC 9111 describes an apparent age from response receipt minus Date, clamped at zero, and a corrected age value from received Age plus response delay. Its conservative calculation takes the larger value, then adds residence time. For request time 100, receipt 102, Date 95, received Age 10, and current time 107, those values are 7, 12, and finally 17 seconds. Reading only the original Age would miss seven seconds.

Freshness lifetime has a precedence order: shared caches use s-maxage when present; otherwise max-age takes precedence over Expires minus Date. Private caches ignore s-maxage. Without explicit expiration, a permitted heuristic might apply, but its duration is not universally fixed. A response is fresh only while its applicable lifetime is greater than current age; equality is already the stale boundary.

When it breaks

Fresh does not mean usable for every request. Storage permission, URL and Vary matching, and validation requirements still apply. No-cache requires validation before reuse even when an explicit lifetime looks generous. An ETag supplies a validator, not permission to skip validation. Successfully revalidating can update stored metadata without transferring the body; simply receiving a cached response cannot reset its age.

Stale delivery is a separate permission, not an automatic response to an outage. Must-revalidate prohibits reuse once stale until validation succeeds, including when disconnected. Stale-while-revalidate permits a bounded stale interval while validation proceeds, subject to applicable restrictions. It does not turn stale content fresh. RFC 9111 also obsoletes Warning, so absence of the old Warning: 110 field is not evidence of freshness.

Do not confuse storage retention with freshness. Keeping bytes after expiration can be useful for validation or an allowed stale window. A backend’s eviction TTL may therefore exceed the direct-reuse lifetime. If the caller treats that TTL as permission to serve, it can deliver stale responses outside the intended policy.

Check it quickly

Use Node.js and npm; the tested versions are Node 26.0.0 and http-cache-semantics 4.2.0. Install the library below, then execute the JavaScript with NODE_PATH="$freshness_lab/node_modules" node. The test overrides the library’s clock, not the system clock. It uses synthetic metadata, performs no requests, and needs no sleeping; only installation requires the network.

freshness_lab=$(mktemp -d)
npm install --prefix "$freshness_lab" --ignore-scripts --no-audit --no-fund --package-lock=false http-cache-semantics@4.2.0

const assert = require("node:assert/strict");
const CachePolicy = require("http-cache-semantics");

const start = Date.parse("2026-09-07T00:00:00Z");
let clock = start;
class TestPolicy extends CachePolicy {
 now() { return clock; }
}
const request = { url: "https://example.test/news", method: "GET", headers: {} };
const headers = {
 date: new Date(start).toUTCString(),
 age: "20",
 expires: new Date(start + 3600000).toUTCString(),
 "cache-control": "public, max-age=60, s-maxage=30",
};
const shared = new TestPolicy(request, { headers }, { shared: true });
const single = new TestPolicy(request, { headers }, { shared: false });
assert.equal(shared.maxAge(), 30);
assert.equal(single.maxAge(), 60);
for (const [elapsed, sharedHit, privateHit] of [
 [0, true, true], [9, true, true], [10, false, true], [40, false, false],
]) {
 clock = start + elapsed * 1000;
 assert.equal(shared.age(), 20 + elapsed);
 assert.equal(shared.responseHeaders().age, String(20 + elapsed));
 assert.equal(shared.satisfiesWithoutRevalidation(request), sharedHit);
 assert.equal(single.satisfiesWithoutRevalidation(request), privateHit);
 console.log("elapsed:", elapsed, "age:", shared.age(), "reuse:", sharedHit, privateHit);
}

clock = start;
const background = new TestPolicy(request, { headers: {
 age: "20", "cache-control": "public, max-age=30, stale-while-revalidate=20",
} });
clock += 15000;
const decision = background.evaluateRequest(request);
assert.equal(background.timeToLive(), 15000);
assert.equal(background.satisfiesWithoutRevalidation(request), false);
assert(decision.response);
assert.equal(decision.revalidation.synchronous, false);
console.log("stale window: retain 15000 ms, serve and revalidate");
clock += 15000;
assert.equal(background.evaluateRequest(request).response, undefined);
assert.equal(background.evaluateRequest(request).revalidation.synchronous, true);

clock = start;
const oldDate = new TestPolicy(request, { headers: {
 date: new Date(start - 3600000).toUTCString(),
 "cache-control": "public, max-age=60",
} });
assert.equal(oldDate.age(), 0);
assert.equal(oldDate.satisfiesWithoutRevalidation(request), true);
console.log("library limitation: old Date alone does not increase age");

At elapsed times zero, nine, ten, and forty seconds, the calculated ages are twenty, twenty-nine, thirty, and sixty. Both modes initially reuse the response. Shared reuse stops exactly at age thirty; private reuse stops at sixty. The future Expires date does not override either explicit lifetime. Updated outgoing Age is checked as well as the reuse decision.

The separate stale-window fixture reaches age thirty-five, five seconds beyond freshness. Its remaining retention allowance is fifteen thousand milliseconds, but validation is still required. The library permits a response together with asynchronous revalidation; it does not perform that network operation itself. At age fifty, that permission ends and validation becomes synchronous.

The final check exposes an important implementation limit: this library deliberately ignores server Date when calculating age. An hour-old Date with no Age still starts at zero here. Its documented model adds received Age and local residence, not measured response delay or the conservative apparent-age branch above. Consequently, these passing assertions establish the pinned library’s decisions, not complete RFC age-calculation conformance. Test actual intermediary timing and header propagation separately before using a measured cache lifetime as a delivery guarantee.

Sources

RFC 9111: freshness, lifetime precedence, current age, and stale-response restrictions, checked 2026-09-07.
MDN: Cache-Control, freshness and stale-while-revalidate directives, checked 2026-09-07.
http-cache-semantics 4.2.0, retention TTL, revalidation decisions, and the documented server-Date limitation, checked 2026-09-07.

The Link header relates adjacent resources

Fri, 04 Dec 2026 00:00:00 +0000

The Link response field describes relationships between the current resource and other resources. An API returning JSON can advertise its next page without making clients scrape HTML or invent a query parameter. The field supplies a target and a relation; whether to follow it remains a client decision. It is useful metadata, not a command that every browser or crawler must execute.

A link has a context and a target

A value such as </items?cursor=b>; rel="next" links the response’s context resource to a target URI reference. With no explicit anchor parameter, the context is normally the requested resource. Resolve relative targets against the effective request URI after redirects, not against the client’s current working directory or an assumed API root. A query-only target changes the query while preserving the path.

The rel parameter names the relationship. Registered relations include next, prev, alternate, and canonical; extension relations can use URI identifiers. Additional parameters describe the target, for example type="application/json". They do not change the actual response’s Content-Type, grant access, or prove that the target is trustworthy. An anchor can change the context, so clients that cannot honor that context must not silently attach the link to the original resource.

Relations also have different consumers. A crawler may interpret canonical when selecting a preferred indexing URL, while a browser can use supported preload hints to begin fetching assets. Neither relation redirects the current request. Test the behavior of the intended consumer separately from checking field syntax; an ordinary HTTP library may correctly expose the header and take no further action.

Follow pagination as a server contract

For pagination, the server decides whether a continuation exists and supplies its exact target. A cursor may encode ordering, filters, and a position in a snapshot. Treat it as opaque: guessing the next page number or changing cursor bytes can skip results, repeat rows, or invalidate the request. Preserve the returned query rather than rebuilding it from assumptions about today’s API implementation.

A missing next relation normally terminates that API’s traversal, subject to its documented pagination contract. It does not prove the collection is immutable. Concurrent insertions and deletions can still change membership between requests unless the API provides snapshot semantics. Bound requests and detect repeated continuation targets so a server bug cannot create an endless crawl.

When it breaks

Multiple links can appear in separate Link field lines or a comma-separated field value. Naively splitting on every comma is incorrect: quoted parameter values and URI references can contain commas. Use a parser implementing Web Linking, retain multiple values, and interpret relation tokens correctly. A proxy that overwrites repeated fields can silently remove the pagination link even while the response body remains valid.

Following an absolute target blindly is another failure. An authenticated API client must apply its destination and credential-forwarding policy before requesting a different origin; a link is not authorization to send tokens elsewhere. For browser code, successful CORS access to the body does not automatically expose Link. The server must include it in Access-Control-Expose-Headers when cross-origin JavaScript needs to read it.

Check it quickly

This Python 3 experiment creates a two-page loopback API. The first response has separate next and alternate fields; the terminal response has no links. It examines the wire values and resolves the known fixture target with the standard URL library. It deliberately does not implement a general Link parser.

from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
from urllib.parse import urljoin, urlsplit

class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 self.send_response(200)
 self.send_header("Content-Length", "2")
 if self.path == "/items?cursor=a":
 self.send_header("Link", '<?cursor=b>; rel="next"')
 self.send_header("Link", '</items.csv>; rel="alternate"')
 self.end_headers()
 self.wfile.write(b"[]")

 def log_message(self, *args):
 pass

with ThreadingHTTPServer(("127.0.0.1", 0), Handler) as server:
 worker = Thread(target=server.serve_forever, daemon=True)
 worker.start()
 client = HTTPConnection(*server.server_address, timeout=3)
 try:
 client.request("GET", "/items?cursor=a")
 response = client.getresponse()
 links = response.headers.get_all("Link")
 assert response.read() == b"[]"
 assert links == ['<?cursor=b>; rel="next"',
 '</items.csv>; rel="alternate"']
 base = f"http://127.0.0.1:{server.server_port}/items?cursor=a"
 target = urlsplit(urljoin(base, "?cursor=b"))
 client.request("GET", target.path + "?" + target.query)
 response = client.getresponse()
 assert response.read() == b"[]"
 assert response.headers.get_all("Link") is None
 print("two fields preserved; terminal page has no next link")
 finally:
 client.close()
 server.shutdown()
 worker.join()

Expect the final confirmation line without an assertion failure. The query-only target should resolve to /items?cursor=b, and both first-page fields should survive. This verifies response construction, repeated-field retrieval, and relative resolution. A production client additionally needs parser tests for quoted commas, redirects, multiple relation tokens, cross-origin targets, and pagination loops. Browser header exposure must be checked from the actual calling origin; this standard-library client does not enforce CORS.

Sources

RFC 8288: Web Linking, link context, relation types, and field grammar, checked 2026-09-06.
MDN: Link header, syntax and relative URL resolution, checked 2026-09-06.
MDN: Access-Control-Expose-Headers, exposing response metadata to cross-origin browser code, checked 2026-09-06.

Server-Timing exposes named measurements to the browser

Sat, 07 Nov 2026 00:00:00 +0000

The Server-Timing response header lets a server attach named measurements to a response. Browser developer tools and performance APIs can then associate those measurements with the resource request. It is useful when the network waterfall shows a long wait but cannot explain whether backend work involved a database call, rendering, or another measured operation. The header supplies server-selected observations, not an independent browser measurement of those operations.

The duration syntax is db;dur=42, render;dur=81, with durations expressed in milliseconds. A bare db=42 is not the duration syntax. Each metric has a name and can include duration and description parameters. Use stable names that readers can interpret, and derive values from actual instrumentation in production. A description can clarify the measurement, but should not contain raw queries, identifiers, or internal details that the response should not disclose.

Match the number to its interval

Server measurements do not necessarily add up to the browser’s request duration. They may cover nested operations, overlapping work, or only part of the handling path. Adding database and rendering time is valid only when their definitions justify that addition. Network transport, queuing outside the measured interval, caching, and client-side processing can explain differences without either clock being wrong.

The header also does not create a distributed trace. It names measurements on one response without automatically supplying parent-child relationships, propagation, or collector storage. Use it to expose a small set of useful request measurements, then follow trace or log correlation when a deeper explanation is needed. When responses pass through a cache or proxy, inspect the delivered header and establish which component produced the numbers.

When it breaks

For cross-origin resources, reading a response header in JavaScript and receiving detailed Resource Timing data are separate permissions. CORS allows the response to be read, and Access-Control-Expose-Headers can expose Server-Timing to response.headers. Timing-Allow-Origin controls the corresponding detailed timing exposure. A successful header read therefore does not prove that PerformanceResourceTiming.serverTiming will contain the same measurements.

Another failure is confusing a parser demonstration with measured performance. Sending a fixed duration establishes what the browser parses, not how long the handler ran. Likewise, an empty timing array does not prove that the server did no work. First check origin permissions and the actual wire header, then inspect measurement placement. Keep public names and descriptions appropriate for their audience; an operationally useful timing hint should not accidentally reveal sensitive backend structure.

Check it quickly

Save this as server-timing.py and run python3 server-timing.py --serve. Python 3.14.4 was used for execution. It starts two loopback HTTP origins on separate temporary ports and prints the page URL to open. The page fetches two resources and displays the header values alongside the browser’s parsed timing entries. Press Control-C to close both servers. Without --serve, the script checks response headers and exits without running a browser.

import json
import sys
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Event, Thread
from urllib.request import Request, urlopen

timing = "db;dur=42, render;dur=81"


class API(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def do_GET(self):
 body = b"synthetic timing fixture\n"
 self.send_response(200)
 self.send_header("Content-Type", "text/plain; charset=utf-8")
 self.send_header("Content-Length", str(len(body)))
 self.send_header("Cache-Control", "no-store")
 self.send_header("Access-Control-Allow-Origin", app_origin)
 self.send_header("Access-Control-Expose-Headers", "Server-Timing")
 self.send_header("Server-Timing", timing)
 if self.path.split("?", 1)[0] == "/allow":
 self.send_header("Timing-Allow-Origin", app_origin)
 self.end_headers()
 self.wfile.write(body)


class App(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def do_GET(self):
 body = ("""<!doctype html><meta charset="utf-8"><title>Server-Timing lab</title>
<h1>Cross-origin Server-Timing</h1><pre id="result">Running...</pre>
<script>
const api = """ + json.dumps(api_origin) + """;
async function run() {
 performance.clearResourceTimings();
 const results = {};
 for (const path of ['deny', 'allow']) {
 const url = api + '/' + path;
 const response = await fetch(url, {cache:'no-store'});
 await response.text();
 await new Promise(resolve => requestAnimationFrame(resolve));
 const entry = performance.getEntriesByName(url).at(-1);
 results[path] = {header:response.headers.get('Server-Timing'),
 timing:entry.serverTiming.map(item => ({name:item.name, duration:item.duration}))};
 }
 window.labResult = results;
 document.getElementById('result').textContent = JSON.stringify(results, null, 2);
}
run().catch(error => {window.labError=String(error); document.getElementById('result').textContent=String(error);});
</script>""").encode()
 self.send_response(200)
 self.send_header("Content-Type", "text/html; charset=utf-8")
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)


api = HTTPServer(("127.0.0.1", 0), API)
app = HTTPServer(("127.0.0.1", 0), App)
api_origin = f"http://127.0.0.1:{api.server_port}"
app_origin = f"http://127.0.0.1:{app.server_port}"
threads = [Thread(target=server.serve_forever, daemon=True) for server in (api, app)]
for thread in threads:
 thread.start()
try:
 for path in ("deny", "allow"):
 with urlopen(Request(api_origin + "/" + path, headers={"Origin": app_origin}), timeout=5) as response:
 assert response.headers["Server-Timing"] == timing
 assert response.headers["Access-Control-Allow-Origin"] == app_origin
 assert response.headers["Access-Control-Expose-Headers"] == "Server-Timing"
 assert response.headers.get("Timing-Allow-Origin") == (app_origin if path == "allow" else None)
 response.read()
 print(json.dumps({"app_url": app_origin, "api_url": api_origin,
 "wire_checks": "PASS", "durations_are_synthetic": True}), flush=True)
 if "--serve" in sys.argv:
 Event().wait()
except KeyboardInterrupt:
 pass
finally:
 for server in (api, app):
 server.shutdown()
 server.server_close()
 for thread in threads:
 thread.join(timeout=5)

Both responses allow the page’s origin through CORS, expose Server-Timing, and carry the same synthetic database and rendering durations. Only /allow adds Timing-Allow-Origin. In Chrome 152, both displayed header strings were db;dur=42, render;dur=81; the denied timing array was empty, while the allowed array contained db with duration 42 and render with duration 81. This browser result was checked separately from the Python wire assertions.

The fixed numbers intentionally test syntax and visibility rather than elapsed backend time. This local example does not verify another browser, production proxies, cached responses, or a real database measurement. To deploy the idea, measure well-defined intervals, emit the header before the response headers are committed, and repeat the check through the actual delivery path. Explain the timing names and overlap rules so readers can interpret the numbers without inventing an additive breakdown the server never promised.

Sources

W3C Server Timing, header parameters and PerformanceServerTiming exposure, checked 2026-09-13.
MDN Server-Timing, duration syntax, browser use, and disclosure considerations, checked 2026-09-13.
MDN Timing-Allow-Origin, permission for detailed cross-origin resource timing, checked 2026-09-13.

Content-Type tells the reader what it is

Sat, 10 Oct 2026 00:00:00 +0000

Content-Type describes the representation a sender intends to provide. It does not inspect the body, convert its bytes, or guarantee that every recipient will process it identically. A reliable endpoint keeps its serializer, declared media type, and consumer expectations in agreement, including when an error takes a different path through the server.

Describe the representation, not the filename

For a normal response carrying content, application/json identifies JSON data and text/html identifies HTML. The type applies after content codings have been decoded. A gzipped JSON response therefore retains Content-Type: application/json and adds Content-Encoding: gzip. Content coding is a property of the representation, distinct from HTTP message transfer framing such as chunked transfer coding. Renaming a file or changing its extension does not perform either transformation.

Media types contain a type, subtype, and optional parameters. The type and subtype are case-insensitive; parameter meanings belong to the particular media type. Use an existing header parser instead of comparing the complete field to one literal string. Also inspect whether the field was actually present: some parsers supply a default that can hide missing metadata. Multiple conflicting Content-Type fields are an origin or proxy defect, not a useful list of alternatives.

For UTF-8 HTML, text/html; charset=utf-8 describes both format and character encoding. Do not append a charset indiscriminately to every format. RFC 8259 requires UTF-8 for JSON exchanged outside a closed ecosystem, and the application/json registration defines no charset parameter. A generic policy saying that every textual payload needs that parameter would misdescribe JSON’s contract.

When it breaks

A reverse proxy can replace an API response with an HTML login page while returning a successful status. A consumer that immediately parses JSON reports a syntax error, hiding the more useful fact that it received a different representation. Conversely, an error handler can send an HTML body while retaining the JSON header. Checking only the header then passes a response that cannot be parsed. Inspect status, metadata, and body together.

Missing metadata does not make all recipients reject the response. RFC 9110 permits treating an untyped body as opaque binary data or examining it to determine a type. Some user agents can override a supplied type through sniffing. Browser behavior also depends on the processing context, so a command-line JSON client is not a browser security test. Correct labels neither sanitize HTML nor establish that an uploaded file is safe to publish.

Check it quickly

Run this with Python 3.11 or newer. It creates an ephemeral loopback server, sends four real HTTP requests, and shuts the server down. There are no external requests or dependencies. The example consumer deliberately accepts only the application/json media type and then decodes UTF-8 and parses JSON; it is not a general media-type negotiation implementation.

import json
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread

cases = {
 "/ok": ("application/json", b'{"ok":true}'),
 "/wrong-type": ("text/plain", b'{"ok":true}'),
 "/bad-body": ("application/json", b"not JSON"),
 "/missing-type": (None, b'{"ok":true}'),
}


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 media, body = cases[self.path]
 self.send_response(200)
 if media is not None:
 self.send_header("Content-Type", media)
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)

 def log_message(self, *args):
 pass


server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
worker = Thread(target=server.serve_forever)
worker.start()
try:
 outcomes = []
 for route in cases:
 connection = HTTPConnection("127.0.0.1", server.server_port, timeout=3)
 try:
 connection.request("GET", route)
 response = connection.getresponse()
 body = response.read()
 assert response.status == 200
 if response.headers.get("Content-Type") is None:
 outcome = "missing type"
 elif response.headers.get_content_type() != "application/json":
 outcome = "wrong type"
 else:
 try:
 value = json.loads(body.decode("utf-8"))
 except (UnicodeDecodeError, json.JSONDecodeError):
 outcome = "invalid body"
 else:
 assert value == {"ok": True}
 outcome = "accepted"
 outcomes.append(outcome)
 print(route, outcome)
 finally:
 connection.close()
 assert outcomes == ["accepted", "wrong type", "invalid body", "missing type"]
finally:
 server.shutdown()
 server.server_close()
 worker.join()

The output is accepted, wrong type, invalid body, and missing type, in path order. The first, second, and fourth bodies are identical: their different outcomes isolate the declaration check. The third response has an acceptable declaration but fails JSON syntax, isolating body validation. These are the consumer’s explicit rules, not HTTP requirements that every client must reject these fixtures in this way.

For a real incident, capture a GET response from the same authenticated or anonymous path that fails, while keeping credentials out of diagnostic output. Record the final URL after redirects too: the intended resource and its login destination are different endpoints. Compare the origin response with the proxy response and check error routes as well as success routes. HEAD metadata alone cannot establish that a body parses. Fix the component that introduced the mismatch, then repeat the request and parsing check through the complete delivery path. Avoid solving a mislabeled error page by teaching the client to guess around it.

Sources

RFC 9110: Content-Type, media types, missing fields, sniffing, and the adjacent content-coding definition, checked 2026-09-07.
RFC 8259: JSON, UTF-8 interchange and the application/json registration, checked 2026-09-07.

HSTS makes the browser remember HTTPS

Thu, 08 Oct 2026 00:00:00 +0000

HTTP Strict Transport Security tells a supporting client to use HTTPS for a remembered hostname. It can eliminate the insecure HTTP request before a redirect, but only when the client already knows the policy, through an earlier authenticated response or a supported preload mechanism. Merely adding a header cannot retroactively protect an unknown client’s first HTTP visit.

The client remembers a host

A valid Strict-Transport-Security header received over error-free HTTPS establishes or refreshes the policy. max-age is a duration in seconds measured from receipt. A header sent over plaintext HTTP cannot establish this trust, and omitting the header later does not erase an unexpired entry. Each client maintains its own state; browsers do not share one universal cache.

The scope is a DNS hostname, not an HTTP origin or an individual port. includeSubDomains extends coverage downward, not to a parent or sibling name. For an upgraded URL, explicit port 80 becomes 443, while other explicit ports remain unchanged. An HTTP-only service on an alternate port can therefore break after policy is learned.

The policy changes the client’s URL handling; it does not turn a plaintext listener into a TLS listener. The upgraded destination must already support HTTPS. The fixture below deliberately sends HSTS over HTTP as a negative test, not deployment advice. Neither server redirects: reaching the TLS handler from an HTTP URL demonstrates client-side upgrading, not a successful redirect chain.

This is an upgrade rule, not a certificate bypass. Supporting browsers must still validate HTTPS and do not offer their usual click-through escape for an HSTS certificate error. HSTS cannot fix an expired certificate, restore an unavailable TLS endpoint, or prove that the application behind an authenticated connection is trustworthy.

When it breaks

A long lifetime or includeSubDomains can reach forgotten services, delegated subdomains, and internal hostnames. Inventory those dependencies before expanding coverage. Begin with a deliberately short policy, validate real entry points, and ensure certificate renewal works. Scanner recommendations are not evidence that every covered host can honor the commitment.

Recovery requires precision. An authenticated max-age=0 response removes that host’s dynamic policy for clients receiving it; it does not clear independently stored child policies or immediately update offline clients. Removing the header alone is insufficient. Browser preload distribution and removal are separate processes, not instant consequences of toggling a response field.

Testing only header presence misses client behavior. Use an isolated state store and verify both the initial visit and later HTTP URLs. Keep such a test away from personal browser profiles, and never disable certificate verification just to obtain a reassuring upgrade result. Different clients and preload configurations need their own checks.

Check it quickly

Save this as hsts_probe.go and run go run hsts_probe.go with Go 1.23 or newer and an HSTS-enabled curl supporting –hsts. The program creates two loopback servers and a temporary P-256 CA. It writes only the public CA certificate and curl’s cache to a private temporary directory, removes that directory on exit, and keeps private keys in memory.

package main

import (
 "context"
 "crypto/ecdsa"
 "crypto/elliptic"
 "crypto/rand"
 "crypto/tls"
 "crypto/x509"
 "crypto/x509/pkix"
 "encoding/pem"
 "errors"
 "fmt"
 "io"
 "log"
 "math/big"
 "net/http"
 "net/http/httptest"
 "net/url"
 "os"
 "os/exec"
 "path/filepath"
 "runtime"
 "strings"
 "sync/atomic"
 "time"
)

func must(err error) {
 if err != nil {
 panic(err)
 }
}

func check(ok bool, message string) {
 if !ok {
 panic(message)
 }
}

func issue(template, parent *x509.Certificate, public any, signer *ecdsa.PrivateKey) *x509.Certificate {
 der, err := x509.CreateCertificate(rand.Reader, template, parent, public, signer)
 must(err)
 certificate, err := x509.ParseCertificate(der)
 must(err)
 return certificate
}

func main() {
 curl, err := exec.LookPath("curl")
 must(err)
 versionCommand := exec.Command(curl, "--disable", "--version")
 versionCommand.Env = append(os.Environ(), "SSLKEYLOGFILE=")
 version, err := versionCommand.Output()
 must(err)
 check(strings.Contains(string(version), "HSTS"), "curl must support HSTS")
 caKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
 must(err)
 leafKey, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
 must(err)
 now := time.Now()
 template := &x509.Certificate{
 SerialNumber: big.NewInt(1), Subject: pkix.Name{CommonName: "HSTS fixture CA"},
 NotBefore: now.Add(-time.Minute), NotAfter: now.Add(time.Hour),
 IsCA: true, BasicConstraintsValid: true, KeyUsage: x509.KeyUsageCertSign,
 }
 ca := issue(template, template, caKey.Public(), caKey)
 host, child := "hsts.example.test", "child.hsts.example.test"
 leaf := issue(&x509.Certificate{
 SerialNumber: big.NewInt(2), DNSNames: []string{host, child},
 NotBefore: now.Add(-time.Minute), NotAfter: now.Add(time.Hour),
 KeyUsage: x509.KeyUsageDigitalSignature, ExtKeyUsage: []x509.ExtKeyUsage{x509.ExtKeyUsageServerAuth},
 }, ca, leafKey.Public(), caKey)
 folder, err := os.MkdirTemp("", "hsts-probe-")
 must(err)
 defer func() { must(os.RemoveAll(folder)) }()
 caFile, cacheFile := filepath.Join(folder, "ca.pem"), filepath.Join(folder, "hsts.txt")
 must(os.WriteFile(caFile, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: ca.Raw}), 0600))

 var plainCount, secureCount atomic.Int64
 plain := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 plainCount.Add(1)
 if r.URL.Path == "/learn" {
 w.Header().Set("Strict-Transport-Security", "max-age=3600; includeSubDomains")
 }
 fmt.Fprint(w, "plain")
 }))
 defer plain.Close()
 secure := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 secureCount.Add(1)
 check(r.TLS != nil, "secure handler requires TLS")
 switch r.URL.Path {
 case "/learn":
 w.Header().Set("Strict-Transport-Security", "max-age=3600; includeSubDomains")
 case "/clear":
 w.Header().Set("Strict-Transport-Security", "max-age=0")
 }
 fmt.Fprint(w, "secure")
 }))
 secure.Config.ErrorLog = log.New(io.Discard, "", 0)
 secure.TLS = &tls.Config{
 MinVersion: tls.VersionTLS12,
 Certificates: []tls.Certificate{{Certificate: [][]byte{leaf.Raw}, PrivateKey: leafKey, Leaf: leaf}},
 }
 secure.StartTLS()
 defer secure.Close()
 plainURL, err := url.Parse(plain.URL)
 must(err)
 secureURL, err := url.Parse(secure.URL)
 must(err)
 check(plainURL.Hostname() == "127.0.0.1" && secureURL.Hostname() == "127.0.0.1", "IPv4 loopback fixtures required")
 request := func(scheme, name, port, route string, trust bool) (string, error) {
 ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 defer cancel()
 args := []string{
 "--disable", "--noproxy", "*", "--silent", "--show-error", "--fail",
 "--max-time", "3", "--hsts", cacheFile, "--resolve", name + ":" + port + ":127.0.0.1",
 }
 if trust {
 args = append(args, "--cacert", caFile)
 }
 args = append(args, scheme+"://"+name+":"+port+route)
 command := exec.CommandContext(ctx, curl, args...)
 command.Env = append(os.Environ(), "SSLKEYLOGFILE=")
 output, err := command.CombinedOutput()
 return string(output), err
 }
 _, err = request("https", host, secureURL.Port(), "/learn", false)
 var exit *exec.ExitError
 check(errors.As(err, &exit) && exit.ExitCode() == 60, "untrusted HTTPS must fail certificate verification")
 for _, test := range []struct {
 label, scheme, name, port, route, expected string
 }{
 {"HTTP cannot seed HSTS", "http", host, plainURL.Port(), "/learn", "plain"},
 {"still HTTP", "http", host, plainURL.Port(), "/probe", "plain"},
 {"trusted HTTPS seeds HSTS", "https", host, secureURL.Port(), "/learn", "secure"},
 {"HTTP URL upgrades", "http", host, secureURL.Port(), "/probe", "secure"},
 {"child inherits upgrade", "http", child, secureURL.Port(), "/probe", "secure"},
 {"authenticated removal", "https", host, secureURL.Port(), "/clear", "secure"},
 {"parent HTTP restored", "http", host, plainURL.Port(), "/probe", "plain"},
 {"child HTTP restored", "http", child, plainURL.Port(), "/probe", "plain"},
 } {
 output, err := request(test.scheme, test.name, test.port, test.route, true)
 check(err == nil, fmt.Sprintf("curl failed: %v: %s", err, output))
 check(output == test.expected, "wrong transport result")
 fmt.Println(test.label, "->", output)
 }
 check(plainCount.Load() == 4 && secureCount.Load() == 4, "expected four plaintext and four authenticated TLS requests")
 fmt.Println(strings.SplitN(string(version), "\n", 2)[0])
 fmt.Println(runtime.Version())
}

All test hostnames resolve explicitly to loopback through –resolve; no public DNS or external site is used. –disable is curl’s first argument, so personal curl configuration is not loaded. –noproxy avoids configured proxies. Every curl child clears SSLKEYLOGFILE to disable inherited TLS key logging. Each transfer has a three-second limit and an outer five-second process deadline. The test CA is supplied per request, never installed globally.

The first HTTPS attempt lacks that CA and must fail with curl certificate-verification exit code 60. Plain HTTP then remains plain even after receiving an HSTS header. A trusted HTTPS response seeds the shared test cache; subsequent HTTP URLs for both the parent and child reach the TLS handler.

A trusted max-age=0 response removes the parent entry. Parent and child HTTP requests then reach the plaintext handler because this fixture never gives the child an independent policy. Exactly four plaintext and four authenticated TLS requests reach handlers; the failed certificate attempt reaches neither application handler. The nonstandard TLS port is preserved during upgrade.

All assertions passed on macOS with Go 1.27.0 and curl 8.7.1. This is real curl HSTS behavior, not a browser-policy acceptance test. It does not exercise browser preload lists, separate child policies, expiry waiting, port-80 mapping, certificate-error UI, or production rollout. The temporary cache intentionally disappears afterward; no persistent user HSTS setting is changed.

Sources

RFC 6797: HTTP Strict Transport Security, authenticated policy processing, host scope, and port mapping, checked 2026-09-09.
MDN: Strict-Transport-Security, subdomain policy, removal, and preload boundaries, checked 2026-09-09.
curl manual, –hsts, explicit name resolution, CA selection, and configuration isolation, checked 2026-09-09.

Security headers need observable browser behavior

Wed, 30 Sep 2026 00:00:00 +0000

Security response headers ask a supporting browser to enforce specific rules. Their value comes from the behavior those rules change, not from the length of a header checklist. A static site still has document loading, scripts or styles, embedding, navigation, and transport boundaries to consider. Select policies that match the actual page and delivery path, then verify both intended restrictions and legitimate functionality.

Content Security Policy can restrict resource loading and script execution, while frame-ancestors specifies which ancestors may embed the protected document. Referrer-Policy controls how much source-URL information is sent with applicable requests. Permissions-Policy restricts selected browser features. These are related controls, but none establishes an authenticated business permission simply by being present. A policy appropriate for one response category may be irrelevant or disruptive on another.

Understand the boundary each header owns

HSTS tells the browser to use HTTPS for its applicable host policy. Browsers learn that policy from a valid HTTPS response; an HTTP response cannot establish it. Including subdomains affects more than the current application and requires those hosts to support the intended transport. HSTS does not issue certificates or repair an expired certificate. Transport configuration must already be sound before a lasting browser policy is relied upon.

Cross-Origin-Opener-Policy affects browsing-context and opener isolation, whereas Cross-Origin-Resource-Policy restricts certain cross-origin resource loads. Treating both as a generic switch that isolates every window confuses their contracts. Likewise, CORS response exposure is a separate mechanism. Verify integrations that depend on popups, embedded resources, or cross-origin access when changing the relevant policy, rather than copying every available header into one undifferentiated rule.

When it breaks

X-Content-Type-Options: nosniff makes declared content types matter to browser processing. For script and stylesheet destinations, the browser rejects responses whose MIME type is not appropriate for that destination. A deployment that serves JavaScript as plain text can therefore stop working when nosniff is enabled. The repair is to serve the intended bytes with an appropriate type and status, not simply remove the restriction until the symptom disappears.

Another common failure is a route that returns an HTML error page where a script or stylesheet was expected. A correct policy may expose that existing delivery mistake. Inspect the actual response after redirects, caches, and routing, including Content-Type and status. A header-presence test cannot tell whether the response is the right asset, and a successful homepage request cannot prove that error responses and static resources follow their intended contracts.

Check it quickly

Save this as nosniff.py and run python3 nosniff.py --serve. Open the printed URL with ?mode=correct, then try ?mode=strict and ?mode=loose. Python 3.14.4 and Chrome 152 were used. The temporary loopback server sends identical classic-script bytes in all three cases, varying the MIME type and nosniff header. The page reports whether the script executed and whether its load failed. Control-C closes the server.

import json
import sys
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Event, Thread
from urllib.parse import parse_qs, urlsplit
from urllib.request import urlopen


class Handler(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def do_GET(self):
 url = urlsplit(self.path)
 mode = parse_qs(url.query).get("mode", ["correct"])[0]
 assert mode in {"correct", "strict", "loose"}
 headers = {"Cache-Control": "no-store"}
 if url.path == "/payload.js":
 body = b"window.payloadExecuted = true;"
 headers["Content-Type"] = "application/javascript" if mode == "correct" else "text/plain"
 if mode != "loose":
 headers["X-Content-Type-Options"] = "nosniff"
 else:
 body = ("""<!doctype html><meta charset="utf-8"><title>MIME policy lab</title>
<h1>Script MIME policy</h1><pre id="result">Running...</pre><script>
const mode=""" + json.dumps(mode) + """;
const script=document.createElement('script');
script.src='/payload.js?mode='+mode;
function done(failed) {
 window.labResult={mode,executed:window.payloadExecuted===true,loadFailed:failed};
 document.getElementById('result').textContent=JSON.stringify(window.labResult,null,2);
}
script.onload=()=>done(false);script.onerror=()=>done(true);document.head.append(script);
</script>""").encode()
 headers["Content-Type"] = "text/html; charset=utf-8"
 self.send_response(200)
 self.send_header("Content-Length", str(len(body)))
 for key, value in headers.items():
 self.send_header(key, value)
 self.end_headers()
 self.wfile.write(body)


server = HTTPServer(("127.0.0.1", 0), Handler)
thread = Thread(target=server.serve_forever, daemon=True)
thread.start()
origin = f"http://127.0.0.1:{server.server_port}"
try:
 for mode in ("correct", "strict", "loose"):
 with urlopen(origin + "/payload.js?mode=" + mode, timeout=5) as response:
 assert response.read() == b"window.payloadExecuted = true;"
 assert response.headers["Content-Type"] == ("application/javascript" if mode == "correct" else "text/plain")
 assert response.headers.get("X-Content-Type-Options") == (None if mode == "loose" else "nosniff")
 print(json.dumps({"app_url": origin, "wire_mime_checks": "PASS"}), flush=True)
 if "--serve" in sys.argv:
 Event().wait()
except KeyboardInterrupt:
 pass
finally:
 server.shutdown()
 thread.join(timeout=5)
 server.server_close()

In correct mode, the response uses a JavaScript MIME type with nosniff, and the script executes. Strict mode labels those same bytes as text/plain with nosniff; execution is false and the load-error flag is true. Loose mode removes nosniff from that plain-text response, and this tested browser executes the classic script. The wire probe separately confirms that the bytes are identical and that only the relevant response fields differ.

This browser comparison verifies one concrete MIME boundary. It does not test HSTS persistence, every resource type, opener isolation, or other browsers, and it does not imply that removing nosniff guarantees execution everywhere. For the deployed site, retain focused negative cases alongside functional checks of real pages and assets. Confirm the headers delivered by the final serving layer, and connect each expected value to the browser behavior it is intended to preserve or prohibit.

Sources

MDN X-Content-Type-Options, MIME enforcement for script and style destinations, checked 2026-09-13.
OWASP HTTP Headers Cheat Sheet, the distinct purposes and deployment tradeoffs of security headers, checked 2026-09-13.
MDN Strict-Transport-Security, HTTPS delivery, host scope, and transport-policy behavior, checked 2026-09-13.

CSP makes browser execution rules explicit

Thu, 10 Sep 2026 00:00:00 +0000

Content Security Policy tells a supporting browser which actions a document permits. Fetch directives govern categories such as scripts, styles, and images; other directives cover different boundaries. The policy is supplied with the document, commonly through a response header. It adds constraints to browser behavior, but does not repair an injection bug, authenticate application users, or promise that every possible form of script execution has been eliminated.

An omitted directive is not universally a denial. Some fetch directives fall back to default-src, while directives such as frame-ancestors, base-uri, and form-action need their own consideration. A policy containing only a script restriction is not automatically a complete restriction on images, framing, and form submission. Read each directive’s scope instead of treating the presence of a CSP header as one indivisible security guarantee.

Authorize the intended script

A nonce policy gives specifically selected script elements an unpredictable value also named in the policy. Generate a fresh value for each response and place it only on the scripts the server intends to authorize. Automatically adding a nonce to every discovered script element would also bless injected elements. A reused build-time nonce loses the per-response unpredictability that this design depends on.

Source expressions in one directive generally express alternatives. Combining an allowed host with a nonce does not mean a script must satisfy both conditions. Fixed static pages can instead use hashes for approved script contents, with changes to the exact content requiring corresponding policy updates. Choose a policy suited to how the page is produced; weakening it with broad inline execution permission can remove the protection the nonce was supposed to provide.

When it breaks

Legitimate inline scripts, event handlers, generated content, or previously unnoticed dependencies can stop working when enforcement begins. Content-Security-Policy-Report-Only helps observe violations while permitting the actions, so successful execution under report-only is not proof that an enforcing policy will permit the page. Reports also require interpretation: an image violation is not evidence that the tested inline script was blocked.

Multiple enforcing policies apply together. Adding a more permissive header at a proxy does not relax an existing restrictive policy; an action must satisfy every applicable enforcing policy. This can explain a valid-looking nonce that still fails. Inspect all delivered policy headers and the browser’s effective directive. Fix the policy’s intended boundary or the legitimate resource usage rather than assuming the last header replaces every earlier restriction.

Check it quickly

Save the script as csp-nonce.py, run python3 csp-nonce.py --serve, and open the printed URL with ?mode=enforce. Python 3.14.4 and Chrome 152 were used. The server generates a new random nonce for each document and deliberately leaves one script without it. The loopback reporting receiver accepts and discards report bodies; the displayed evidence comes from browser violation events. Press Control-C when finished.

import base64
import json
import secrets
import sys
from http.server import BaseHTTPRequestHandler, HTTPServer
from threading import Event, Thread
from urllib.parse import parse_qs, urlsplit
from urllib.request import urlopen


class Handler(BaseHTTPRequestHandler):
 def log_message(self, *args):
 pass

 def do_POST(self):
 self.rfile.read(int(self.headers.get("Content-Length", "0")))
 self.send_response(204)
 self.send_header("Content-Length", "0")
 self.end_headers()

 def do_GET(self):
 mode = parse_qs(urlsplit(self.path).query).get("mode", ["enforce"])[0]
 assert mode in {"enforce", "report", "intersect"}
 nonce = base64.b64encode(secrets.token_bytes(18)).decode()
 policy = ("default-src 'none'; script-src 'nonce-" + nonce + "'; "
 "base-uri 'none'; object-src 'none'; report-uri /reports")
 body = ("""<!doctype html><meta charset="utf-8"><title>CSP nonce lab</title>
<h1>Nonce, report-only, and policy intersection</h1>
<pre id="result">If both scripts are blocked, this text stays unchanged.</pre>
<script nonce=""" + '"' + nonce + '"' + """>
window.allowed=true; window.violations=[];
document.addEventListener('securitypolicyviolation',event=>{
 window.violations.push({directive:event.effectiveDirective,disposition:event.disposition,blocked:event.blockedURI});
});
</script>
<script>window.unapproved=true;</script>
<script nonce=""" + '"' + nonce + '"' + """>
setTimeout(()=>{
 window.labResult={allowed:window.allowed===true,unapproved:window.unapproved===true,violations:window.violations};
 document.getElementById('result').textContent=JSON.stringify(window.labResult,null,2);
},100);
</script>""").encode()
 self.send_response(200)
 self.send_header("Content-Type", "text/html; charset=utf-8")
 self.send_header("Content-Length", str(len(body)))
 self.send_header("Cache-Control", "no-store")
 self.send_header("Content-Security-Policy-Report-Only" if mode == "report" else "Content-Security-Policy", policy)
 if mode == "intersect":
 self.send_header("Content-Security-Policy", "script-src 'none'")
 self.end_headers()
 self.wfile.write(body)


server = HTTPServer(("127.0.0.1", 0), Handler)
thread = Thread(target=server.serve_forever, daemon=True)
thread.start()
origin = f"http://127.0.0.1:{server.server_port}"
try:
 policies = []
 for mode in ("enforce", "enforce", "report", "intersect"):
 with urlopen(origin + "/?mode=" + mode, timeout=5) as response:
 key = "Content-Security-Policy-Report-Only" if mode == "report" else "Content-Security-Policy"
 values = response.headers.get_all(key)
 assert len(values) == (2 if mode == "intersect" else 1)
 assert "'nonce-" in values[0]
 policies.append(values[0])
 response.read()
 assert policies[0] != policies[1]
 print(json.dumps({"app_url": origin, "nonce_changes_per_response": True,
 "wire_policy_checks": "PASS"}), flush=True)
 if "--serve" in sys.argv:
 Event().wait()
except KeyboardInterrupt:
 pass
finally:
 server.shutdown()
 thread.join(timeout=5)
 server.server_close()

In enforce mode, the authorized script sets allowed to true, while unapproved remains false. The relevant violation has effective directive script-src-elem, blocked value inline, and disposition enforce. Change the URL to ?mode=report: both script flags become true, and the violation’s disposition becomes report. Additional resource violations may appear, so identify the relevant event by its fields instead of assuming a fixed total report count.

Finally open ?mode=intersect. A second enforcing header says script-src 'none'; all three script elements are blocked, including those with the matching nonce. The explanatory text stays unchanged, and browser inspection confirms both globals are absent. The Python probe separately verifies changing nonce values and the two header fields. This exercise uses the older report-uri transport for its local sink, not a production reporting service. It establishes nonce, reporting, and intersection behavior for these documents; representative application pages still need their own functional checks before enforcement changes.

Sources

MDN Content Security Policy guide, nonce and hash policies, directive scope, and deployment, checked 2026-09-13.
MDN CSP script-src, script sources and authorization of inline scripts, checked 2026-09-13.
W3C Content Security Policy Level 3, enforced and report-only policies and the intersection of multiple policies, checked 2026-09-13.

Headers · XB Field Notes

Cache freshness is judged against a clock

Count the age

When it breaks

Check it quickly

Sources

The Link header relates adjacent resources

A link has a context and a target

When it breaks

Check it quickly

Sources

Server-Timing exposes named measurements to the browser

Match the number to its interval

When it breaks

Check it quickly

Sources

Content-Type tells the reader what it is

Describe the representation, not the filename

When it breaks

Check it quickly

Sources

HSTS makes the browser remember HTTPS

The client remembers a host

When it breaks

Check it quickly

Further reading

Sources

Security headers need observable browser behavior

Understand the boundary each header owns

When it breaks

Check it quickly

Further reading

Sources

CSP makes browser execution rules explicit

Authorize the intended script

When it breaks

Check it quickly

Sources