Feature Idea: Enhance Middleware configuration with a generic request trust validation callback

[uniho]

Hello Laravel community and core developers,

I'd like to propose a new feature for the Middleware configuration within bootstrap/app.php to enhance how Laravel applications handle request trustworthiness, especially in complex proxy environments like Cloudflare.

---

The Problem

Currently, Laravel offers robust mechanisms for handling request trustworthiness:

• TrustHosts middleware (or TrustProxies middleware): This is primarily designed to validate the Host header against a list of trusted domains/IPs, ensuring correct client IP resolution and preventing Host Header attacks.

However, a common challenge arises when using large-scale CDN/proxy services like Cloudflare. Due to their vast and often dynamic range of IP addresses, whitelisting all Cloudflare IPs in TrustedProxies becomes impractical and hard to maintain.

In such scenarios, a common security practice is to add a custom header (e.g., X-Secret: your_secret_key) at the proxy level, which the origin server (Laravel application) can then validate. This ensures that requests truly originate from the trusted proxy.

Implementing this custom header validation currently requires creating a separate, dedicated middleware class. While this is a perfectly valid and idiomatic Laravel approach, it can feel like boilerplate for simple, singular trust validation rules, especially when the core Middleware configuration in bootstrap/app.php is already handling other setup concerns.

---

The Proposed Solution

I propose adding a new, generic request trust validation hook to the Middleware configuration in bootstrap/app.php. This could be a method like $middleware->trustRequest(callable $callback):

// In bootstrap/app.php

// ...

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        // ...
    )
    ->withMiddleware(function (Middleware $middleware) {
        // Existing middleware configurations (e.g., $middleware->web(...))

        // Proposed new hook:
        $middleware->trustRequest(function (Request $request) {
            // Example: Validate a custom X-Secret header from Cloudflare
            $expectedSecret = env('APP_PROXY_SECRET');
            $receivedSecret = $request->header('X-Secret');

            if (!$receivedSecret || $receivedSecret !== $expectedSecret) {
                // If the request is deemed untrustworthy, abort the request.
                // This leverages Laravel's existing exception handling system.
                abort(403, 'Access Forbidden: Invalid proxy secret.');
            }

            // If the request is trustworthy, simply return nothing (or true).
            // The request will then proceed to the next middleware/controller.
        });

        // Other middleware configurations...
    })
    ->withExceptions(function (Exceptions $exceptions) {
        // ...
    })->create();

---

Why this is needed / Benefits

1. Enhanced Versatility: Allows developers to define trust validation rules based on any request attribute (custom headers, specific IP ranges not covered by TrustedProxies, unique request patterns, etc.), not just the Host header.
2. Centralized Trust Management: Consolidates application-specific "request trustworthiness" logic within the bootstrap/app.php file, offering a single, clear point of configuration for how the application evaluates incoming requests' reliability.
3. Reduced Boilerplate: For simple, singular trust checks (like a single X-Secret header validation), it avoids the need to create a dedicated middleware class, allowing for concise in-line configuration.
4. Alignment with Laravel's Philosophy: Similar to how withExceptions provides flexible hooks for exception handling customization, trustRequest would offer comparable flexibility for fundamental request validation at the middleware configuration level.
5. Practicality for Dynamic Proxy Environments: Directly addresses the need for robust request validation when dealing with CDN/proxy services that use dynamic or vast IP ranges, where traditional IP whitelisting is ineffective.

---

Considerations

• Complexity in Callback: While designed for simplicity, developers could potentially write overly complex logic directly within the callback, making bootstrap/app.php less readable. However, this is a developer choice, and complex logic could still be delegated to a separate service class.
• Relationship to Existing Mechanisms: This proposed feature is not intended to replace trustHosts or TrustedProxies. Instead, it aims to complement them by providing a flexible solution for custom trust validation requirements that those existing mechanisms do not cover.

I believe this feature would add significant value by providing a more flexible and intuitive way to manage application-specific request trustworthiness, especially in modern cloud deployments.

Thank you for your time and consideration.