Secure Headers Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require bepsvpt/secure-headers
   

   Laravel auto-discovers the package if using Laravel 5.5+. For older versions, add to config/app.php under providers:

   Bepsvpt\SecureHeaders\SecureHeadersServiceProvider::class,
   

2. Publish Config (optional but recommended):

   php artisan vendor:publish --provider="Bepsvpt\SecureHeaders\SecureHeadersServiceProvider" --tag="config"
   

   This generates config/secure-headers.php.

3. First Use Case:

   • Headers are automatically applied to all responses after installation.
   • Verify via browser dev tools (Network tab) or tools like SecurityHeaders.com.

Implementation Patterns

Core Workflows

1. Default Configuration: The package ships with sensible defaults (e.g., Content-Security-Policy, X-Frame-Options, X-XSS-Protection). Modify config/secure-headers.php to adjust:

   'headers' => [
       'Content-Security-Policy' => [
           'default-src' => "'self'",
           // Custom directives...
       ],
       'X-Frame-Options' => 'DENY',
   ],
   

2. Dynamic Headers: Override headers per route or request using middleware:

   // app/Http/Middleware/SetCustomHeaders.php
   public function handle($request, Closure $next) {
       $response = $next($request);
       $response->headers->set('X-Custom-Header', 'dynamic-value');
       return $response;
   }
   

3. Conditional Application: Disable headers for specific routes (e.g., APIs or admin panels):

   // config/secure-headers.php
   'except' => [
       'api/*',
       'admin/*',
   ],
   

4. Environment-Specific Rules: Use Laravel’s environment config to toggle headers:

   // config/secure-headers.php
   'enabled' => env('APP_ENV') !== 'local',
   

5. Integration with Middleware: Extend the package’s middleware to add logic:

   // app/Http/Middleware/ApplySecureHeaders.php
   use Bepsvpt\SecureHeaders\SecureHeadersMiddleware;
   
   class ApplySecureHeaders extends SecureHeadersMiddleware {
       protected function getHeaders() {
           $headers = parent::getHeaders();
           $headers['X-My-Custom-Header'] = 'value';
           return $headers;
       }
   }
   

Pro Tips

• CSP (Content Security Policy): Start with a restrictive policy and gradually loosen directives (e.g., script-src 'self' → script-src 'self' https://cdn.example.com). Test using Report-Only mode:

  'Content-Security-Policy' => [
      'report-uri' => '/csp-report-endpoint',
      'default-src' => "'self'",
  ],
  

• Performance: Cache headers for static assets (e.g., Cache-Control) separately from security headers.

• Testing: Use Laravel’s Http::fake() to assert headers in tests:

  $response = $this->get('/');
  $response->assertHeader('X-Frame-Options', 'DENY');
  

Gotchas and Tips

Pitfalls

1. CSP Misconfiguration:

   • Gotcha: Overly restrictive CSPs break functionality (e.g., blocked inline scripts or external resources).
   • Fix: Use Report-Only mode first, then monitor reports via /csp-report-endpoint.

2. Header Conflicts:

   • Gotcha: Other middleware (e.g., App\Http\Middleware\TrustProxies) may override headers.
   • Fix: Ensure SecureHeadersMiddleware runs last in your middleware stack.

3. Local Development:

   • Gotcha: Headers like HSTS or X-Frame-Options can break local workflows (e.g., iframes, mixed content).
   • Fix: Disable headers in local environment:

     'enabled' => env('APP_ENV') !== 'local',
     

4. Non-HTTP Responses:

   • Gotcha: Headers won’t apply to non-HTTP responses (e.g., JSON:API, GraphQL).
   • Fix: Exclude non-HTTP routes via except or manually set headers in responses.

5. Caching Headers:

   • Gotcha: Headers like Cache-Control may conflict with Laravel’s caching logic.
   • Fix: Explicitly set cache headers in your middleware if needed.

Debugging

1. Verify Headers: Use dd($response->headers->all()) or browser dev tools to inspect headers.

2. Log Headers: Add debug logging in middleware:

   \Log::debug('Secure Headers Applied:', $this->getHeaders());
   

3. Common Issues:

   • Missing Headers: Ensure SecureHeadersServiceProvider is registered.
   • Header Overrides: Check for middleware that modifies headers post-SecureHeadersMiddleware.
   • CSP Reports: Set up a report endpoint (e.g., using Laravel CSP Reporter).

Extension Points

1. Custom Headers: Extend the SecureHeadersMiddleware class to add dynamic headers:

   protected function getHeaders() {
       $headers = parent::getHeaders();
       $headers['X-Dynamic-Header'] = $this->request->ip();
       return $headers;
   }
   

2. Header Factories: Create a factory for complex headers (e.g., CSP with environment variables):

   // app/Providers/SecureHeadersServiceProvider.php
   public function boot() {
       $this->app->bind(\Bepsvpt\SecureHeaders\HeaderFactory::class, function () {
           return new CustomHeaderFactory();
       });
   }
   

3. Event-Based Headers: Listen to Laravel events (e.g., Illuminate\Http\Events\RequestHandled) to modify headers dynamically:

   Event::listen(RequestHandled::class, function ($request) {
       if ($request->routeIs('admin.dashboard')) {
           $request->getOriginalRequest()->headers->set('X-Admin-Access', 'true');
       }
   });
   

4. Header Validation: Validate headers in config/secure-headers.php using Laravel’s validation rules:

   'headers' => [
       'Content-Security-Policy' => [
           'default-src' => ['required', 'string'],
       ],
   ],