Referer Security Model

When protecting image assets from unauthorized embedding, the HTTP Referer header is a surprisingly effective tool — if you understand its trust boundaries. This article explains when and why Referer is trustworthy, and how OptStuff leverages it as a supplementary anti-hotlinking layer.

What is the Referer header?

When a browser loads a resource (image, script, stylesheet, etc.), it typically includes a Referer header in the HTTP request that tells the server which page triggered the load.

GET /api/v1/my-blog/w_800,f_webp/cdn.example.com/photo.jpg HTTP/1.1
Host: optstuff.example.com
Referer: https://my-blog.com/posts/hello-world

The header is set automatically by the browser. JavaScript on the page cannot override it — this is a fundamental browser security guarantee.

Why is Referer trustworthy in browsers?

The browser enforces it — JavaScript cannot

The Fetch specification defines Referer as a forbidden header name. This means:

• fetch() and XMLHttpRequest silently ignore any attempt to set it manually.
• The browser always fills it in based on the actual page origin.

// This does NOT work — the browser ignores the custom Referer
fetch("https://optstuff.example.com/api/v1/...", {
  headers: { Referer: "https://evil.com" }, // silently dropped
});

A page on https://evil.com cannot forge a request that claims to come from https://my-blog.com. The browser guarantees the Referer reflects the real origin.

Browser extensions can — but that's fine

A browser extension or modified browser can alter the header. However, this requires explicit user action (installing an extension), which puts it in the same category as "the user can right-click → Save Image As." You're protecting against unauthorized websites, not against determined individual users.

The Fetch spec's referrer policy

Sites can restrict how much Referer information they send via the Referrer-Policy header. The available policies range from sending the full URL to sending nothing at all:

The default browser policy (strict-origin-when-cross-origin) sends the origin on cross-origin requests, which is exactly the information OptStuff needs for domain validation.

A site can choose no-referrer, which makes the header absent. But a site cannot make the header claim a different origin. This is the key distinction: a site can hide its identity, but it cannot impersonate another site.

When is Referer absent?

The Referer header is null in several legitimate scenarios:

These are all legitimate, non-malicious scenarios. Blocking them would create false positives without improving security — the signed URL already authenticates the request.

OptStuff's layered security model

OptStuff uses defense-in-depth with distinct layers, each protecting against a specific threat:

Why this separation matters

Signed URLs are the real authentication. They cryptographically prove that someone with the secret key authorized this specific image request. This is the primary security gate.

Referer validation is supplementary. It solves a narrower problem: even with a valid signed URL, you may want to prevent it from being embedded on websites you don't control. Referer is the right tool for this because:

1. It works against the actual threat (unauthorized websites embedding your images)
2. The browser enforces it — the unauthorized site cannot bypass it
3. It doesn't interfere with legitimate server-side usage

Absent Referer = allowed

When the Referer header is absent, OptStuff allows the request (assuming the signature is valid). This is the correct behavior because:

• The signed URL already authenticates the request. If someone has a valid signed URL, they were authorized to use it.
• Null Referer doesn't indicate hotlinking. It indicates a non-browser context (server-side rendering, API calls) or a privacy-stripping browser policy — none of which are the threat Referer validation targets.
• Blocking null Referer creates false positives. It breaks SSR blur placeholders, cron-based pre-warming, health checks, and users with strict privacy settings — all without preventing any real attack.

An attacker who strips their own Referer to bypass the check could just as easily download the image with curl and self-host it. The Referer check isn't meant to stop that — it stops the much more common scenario of someone copy-pasting your <img> tag onto their website, where the browser will send the real Referer.

Summary

Related documentation

• Domain Whitelisting — Configure referer and source domain allowlists (both project-level)
• URL Signing — How HMAC-SHA256 signatures work
• Security Best Practices — Full defense-in-depth overview