File Gate | Wilkes & Liberty

File Gate is for Drupal site owners, content teams, and frontend engineers who need to distribute a private file only after a visitor has satisfied a real access condition. Wilkes & Liberty maintains the GPL-licensed module for Drupal 11.4 and Drupal 12. It works with coupled Drupal, headless applications, and hybrid sites because the access decision and byte delivery stay in Drupal while the visitor experience can live anywhere.

Why File Gate exists

Drupal's private file system protects storage paths; it does not automatically implement a business gate. If anonymous visitors may view a published entity that references a private file, core can allow the referenced download. That is correct for Drupal's entity-access model, but it is not enough for a report that requires a lead form, a file limited to authenticated users, a purchased deliverable, or a document that requires hardware-backed assurance.

Decoupled sites make the gap easier to miss. A form, storefront, or identity flow may run in Next.js while Drupal stores the file. File Gate supplies the missing trust boundary: the frontend proves that its gate succeeded, Drupal mints a short-lived grant for one file, and File Gate—not the frontend—verifies the grant and streams the bytes.

Who should use it, and when

Content and demand-generation teams distributing reports after a lead-capture form without exposing a permanent file URL.
Membership and customer portals where login, role, purchase, or entitlement should govern a download.
Regulated or high-assurance environments that need OIDC claims, PIV/CAC, FIDO2/WebAuthn, DPoP, or an edge mTLS signal before delivery.
Headless Drupal teams that want the frontend to own the experience while Drupal remains the policy and delivery authority.
Module developers who need a reusable gate plugin rather than another bespoke download controller.

Use File Gate when the condition for receiving a file is stronger than “the visitor can view this page.” Do not use it as digital-rights management: once an authorized recipient has the bytes, the module cannot prevent copying or redistribution.

Where it sits in the architecture

An editor uploads a file to a field configured as gated. File Gate forces that field onto Drupal's private file system.
The ordinary private-file route is denied for the protected reference. A guessed or leaked raw path is not the delivery path.
The visitor completes the site's chosen gate in Drupal or in another frontend.
A trusted backend—or an approved Drupal session—requests a grant for the file or media UUID. Secrets used to mint grants remain server-side.
File Gate returns a relative, signed URL containing the file UUID, expiration, gate method, and any usage constraints. It never exposes the private:// URI.
The browser redeems that URL. File Gate validates the signature and gate-specific evidence, consumes any one-time allowance, and streams a private, no-store response.

The module separates proving eligibility from delivering bytes. A site can replace its form provider, identity provider, storefront, or frontend framework without rewriting the signing and streaming core.

Eight shipped gate methods

The base module provides five methods:

Signed URL for server-approved, short-lived download links.
Authenticated access for a Drupal user session with permission to receive the file.
Revocable or pre-shared token for controlled external workflows.
One-time passcode for a challenge delivered out of band.
Referrer/origin lock for a narrow same-site delivery constraint; this is defense in depth, not identity.

Optional submodules add three more:

File Gate Form records a Webform submission and issues a grant after the form succeeds. It includes submission fingerprinting and abuse controls, but the site still owns consent text, retention, and lead-processing policy.
File Gate Commerce checks Drupal Commerce orders or a replaceable entitlement service. It gates access; it is not DRM.
File Gate Assurance accepts bounded identity assurance from OIDC or native WebAuthn. It supports IdP-first hardware authentication, optional per-user binding, DPoP, and trusted edge mTLS signals without pretending that possession of a signed link is identity.

Each method implements the same GateMethod plugin contract, so a site can add a mission-specific decision without forking the download pipeline.

Security and operational controls

Fail closed: if the required signing material is absent or invalid, minting returns an error and protected downloads remain denied.
Scoped secrets: minting and download signing can use separate current and previous secrets, allowing rotation without invalidating every in-flight grant.
Short life and bounded use: per-field TTLs, absolute availability windows, and usage limits—including one-time links—are bound into the signed grant.
Revocation: operators can revoke individual grants or bulk-revoke active grants through the API.
Audit seams: the module logs mints, deliveries, denials, and configuration failures. When Audit Chain is enabled, those events can also enter a durable tamper-evident trail.
Editor workflow: a narrowly assigned bypass permission lets trusted editors inspect protected files in Drupal without weakening anonymous delivery.

What File Gate does not do

File Gate cannot recover confidentiality after an authorized download, replace identity-proofing policy, decide whether a purchase should be refunded, or make referrer headers trustworthy. It does not move public files into private storage retroactively; operators must migrate existing files deliberately. A frontend must never expose minting credentials to the browser. Reverse proxies and CDNs must preserve the module's private cache headers and must not cache authenticated delivery responses.

The assurance submodule verifies specific claims and cryptographic evidence; it does not certify an identity provider, a PIV program, or an organization's compliance posture. Operators remain responsible for token audience, issuer, key rotation, consent, retention, and incident response.

Requirements and installation

PHP 8.3 or newer.
Drupal 11.4 or Drupal 12. The 11.4 floor comes from core's FileReferenceResolver.
A configured private file system.
Signing material injected through environment-backed configuration, not exported YAML.

composer require drupal/file_gate
drush en file_gate

Configure a field under Drupal's field settings, choose the gate method, set the TTL and usage rules, then integrate the mint endpoint from a trusted server-side route. The repository includes the HTTP API contract, plugin API, audit guidance, assurance deployment model, secret-rotation runbook, and manual end-to-end checklists.

Project, source, support, and deeper reading

File Gate is maintained by Jeremy Michael Cerda and Wilkes & Liberty. Contributions are welcome under GPL-2.0-or-later. The checked source release for this page is 1.6.1.