datasette-referrer-policy 0.1: A Plugin for a Real Problem

On May 5th, Simon Willison posted a brief but instructive entry on his weblog: the public demo of Datasette with global power plant data (global-power-plants) stopped displaying OpenStreetMap tiles correctly. What seemed like a minor issue turned out to be two separate bugs that, together, rendered the map unusable.

This type of incident is more common than it appears: a reasonable privacy decision clashes with a legitimate policy from an external service, resulting in broken functionality with no clear error message for the user.

What Happened Exactly

The first problem was a CAPTCHA. Willison had integrated datasette-turnstile into the site a few weeks prior. The CAPTCHA was also triggered by `.json` requests that the maps plugin makes in the background to fetch geospatial data. Since these requests aren't HTML, the user never saw the challenge and therefore couldn't solve it. The requests were silently blocked. The fix involved excluding those routes from the CAPTCHA logic.

The second problem was structural: Datasette sends the `Referrer-Policy: no-referrer` header by default in all its HTTP responses. It's a coherent privacy decision—it prevents leaking the origin URL in requests to third parties—but OpenStreetMap explicitly blocks tile requests that arrive without a `Referer` header. Their reasoning is also legitimate: they need to know which domain requests are coming from to enforce their terms of use and detect abuse.

The Solution: A Dedicated Plugin

Instead of changing Datasette's global behavior, which would have affected any installation that updates the framework, Willison opted to create datasette-referrer-policy 0.1, a plugin that allows configuring the referrer policy at the instance level without touching the core.

The approach makes sense from a software design perspective: Datasette's default behavior remains as private as possible, and anyone who needs a different policy, for example to serve maps with OpenStreetMap tiles, can install the plugin and adjust the header according to their needs (`strict-origin-when-cross-origin` would typically be the option in this case).

Why It Matters Beyond Datasette

This incident is a good reminder of something teams deploying tools with external integrations often underestimate: HTTP security and privacy headers have side effects on third-party services that depend on that information to function correctly.

It's not a problem unique to Datasette. Any application that uses `Content-Security-Policy`, `Referrer-Policy`, or `Permissions-Policy` aggressively can encounter similar friction with map APIs, payment widgets, analytics services, or embedded media players. The difference lies in whether the framework offers a granular escape route, as Datasette now does with this plugin, or forces you to lower your guard globally.

For teams using Datasette as a visualization layer for open data, this plugin is a small but practical piece. For everyone else, the story serves as a mental checklist: before integrating OpenStreetMap tiles (or similar services), it's worth reviewing what headers your application is sending and whether any of them might conflict with the provider's requirements.

---

We've seen similar situations at ClaudeWave in integrations with MCP servers that call external APIs with CORS policies or origin-based authentication. Willison's solution, an opt-in plugin rather than changing the default, is exactly the kind of design decision that prevents unpleasant surprises for users who don't need the functionality.