File Gate | Wilkes & Liberty

File Gate is a free, open-source Drupal module from Wilkes & Liberty that turns a "private" file into a genuinely gated one: deny the ordinary download, and deliver the bytes only through a short-lived, server-minted signed URL that the browser redeems after your front end's gate. Headless-first, and it fails closed.

The problem it solves

Out of the box, Drupal grants a private-file download to anyone who can view the entity that references it. Because anonymous visitors can view published content, a private:// file attached to published media is effectively public to anyone with the link — private:// means "not sitting in a public directory," not "gated." That is exactly the gap that bites lead-gen documents, gated reports, and paywalled deliverables, and it is sharpest on a decoupled site, where the gate (a form, a login, a purchase) lives in a different system from the file. File Gate closes the gap for any front end.

What it does

Denies the raw path. A hard veto on /system/files for any private file a gated field references — overriding core's permissive private-file access. Delivery never happens there.
Delivers through a signed route. The bytes stream from the module's own endpoint only after a gate method approves the request, as a private, no-store binary response.
Mints server-to-server. Your back end calls the mint endpoint with a shared secret and the file/media UUID; File Gate returns a relative, short-lived, HMAC-signed path for the browser to redeem. The secret never reaches the browser.
Never leaks the path. The signed URL carries the file UUID, not the private:// location — so your JSON:API/GraphQL layer can expose that a document exists, its name, type, and size, without a directly resolvable file URL.
Front-end agnostic. Nothing about React, Next.js, Vue, or a coupled Twig theme is assumed. Works for decoupled, coupled, and hybrid sites.
Pluggable gate methods. A clean GateMethod plugin type decides how a request proves it passed the gate. Ships with Signed URL (HMAC) and Authenticated access; add your own in a few lines.
Expiry & usage controls. Per-field TTL, an absolute availability window, and usage limits (including one-time links) — all bound into the signature, so a client cannot alter them.
Per-field, private-safe. Marking a field gated forces and locks the private file system, so a gated field can never silently store public files. The setting travels with your exported configuration.
Fails closed. With no signing secret configured, minting returns 503 and every gated file is denied.
Editors keep working. A Bypass file gate permission lets trusted staff download gated files normally through the admin UI.
Auditable. A dedicated log channel records security events (denied downloads, failed mint auth, fail-closed refusals) and usage events (mints, deliveries).

How it works

An editor uploads a file to a private, gated field. A visitor passes your gate — a lead form, a login, a purchase — entirely in your front end. Your back end then asks File Gate to mint a signed URL for that specific file, and hands the browser the public link to redeem. File Gate verifies the signature (and any usage limit) and streams the file; the raw /system/files path stays denied to the public throughout. File Gate never decides how you gate — it only mints and verifies.

// Server-side only — never expose the secret to the browser:
const res = await fetch(`${DRUPAL_INTERNAL_ORIGIN}/api/file-gate/mint`, {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + Buffer.from(':' + process.env.DRUPAL_FILE_GATE_SECRET).toString('base64'),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ media: mediaUuid }),
});
const { path } = await res.json();
// Hand the browser the public URL to redeem:
const downloadUrl = `${DRUPAL_PUBLIC_FILE_ORIGIN}${path}`;

Requirements

Drupal 11.4+ (it builds on core's FileReferenceResolver, introduced in 11.4)
A configured private file system
A signing secret, injected from the environment (never stored in configuration)
Core file only — Media is optional

Get it

Install with Composer:

composer require drupal/file_gate
drush en file_gate

Then inject the signing secret in settings.php and generate a strong value:

$config['file_gate.settings']['download_secret'] = getenv('DRUPAL_FILE_GATE_SECRET');
// openssl rand -hex 32  → set DRUPAL_FILE_GATE_SECRET in your environment

Source and contributions: github.com/Wilkes-Liberty/file_gate
Project page and releases: drupal.org/project/file_gate

The current release is 1.0.0-beta1. Contributions are welcome, and the module is released under the GPL-2.0-or-later license. For the engineering story and the principles behind it, read our whitepaper Gating Private Files in a Headless CMS.