Referer Security Model

When protecting image assets from unauthorized embedding, the HTTP Referer header is useful only within clear trust boundaries. This article explains when Referer is trustworthy, where it is absent, and how OptStuff enforces 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. They matter because OptStuff treats them differently depending on whether you configured an Authorized Websites allowlist.

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 gives projects an explicit strict mode: configure allowed referer origins only when every expected browser request can send one

How absent Referer is handled

When allowedRefererDomains is empty, OptStuff does not apply a referer restriction, so requests without Referer are allowed after signature verification.

When allowedRefererDomains is non-empty, OptStuff requires the request to include a Referer whose origin matches the allowlist. A missing Referer is rejected with 403 Forbidden: Invalid referer.

This is intentionally stricter than pure best-effort hotlinking protection. Use an empty Authorized Websites list for server-to-server calls, privacy-stripping clients, pre-warming jobs, or health checks. Configure allowedRefererDomains only when you want browser requests without a matching referer to fail closed.

Summary

Related documentation

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