Site Guard Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require mylonia/site-guard
   

2. Set Password Add to .env:

   SITE_GUARD_PASSWORD=your-secure-password
   

3. Apply Middleware Register in AppServiceProvider (or another provider):

   use Mylonia\SiteGuard\SiteGuardMiddleware;
   
   public function boot(Router $router): void
   {
       $router->pushMiddlewareToGroup('web', SiteGuardMiddleware::class);
   }
   

4. Test Visit any route—you should see the password prompt.

First Use Case

• Local/Staging Protection: Enable Site Guard only in non-production environments to block unauthorized access during development or testing.
• Quick Deployment Check: Use it to verify that sensitive routes (e.g., /admin) are protected before going live.

Implementation Patterns

Workflows

1. Environment-Based Activation Conditionally apply middleware based on Laravel’s environment:

   if ($this->app->environment(['staging', 'local'])) {
       $router->pushMiddlewareToGroup('web', SiteGuardMiddleware::class);
   }
   

2. Route Exclusions Publish the config and whitelist routes in config/site-guard.php:

   'except' => [
       'health-check',
       'api/*',
   ],
   

3. Custom Password Page Override the default view by publishing assets:

   php artisan vendor:publish --provider="Mylonia\SiteGuard\SiteGuardServiceProvider" --tag="views"
   

   Then modify resources/views/vendor/site-guard/password.blade.php.

4. Dynamic Passwords Store the password in the database (e.g., configurations table) and fetch it dynamically in the middleware:

   $password = Configuration::where('key', 'site_guard_password')->value('value');
   

Integration Tips

• Combine with Other Middleware: Chain with auth or throttle for layered security:

  $router->pushMiddlewareToGroup('web', [
      SiteGuardMiddleware::class,
      \App\Http\Middleware\ThrottleRequests::class,
  ]);
  

• API Endpoints: Exclude API routes from Site Guard by using a separate middleware group:

  $router->middlewareGroup('api', [
      'throttle:api',
      // Exclude SiteGuard for API
  ]);
  

• Laravel Forge/Envoyer: Use environment variables to toggle Site Guard across deployments:

  SITE_GUARD_ENABLED=${APP_ENVIRONMENT} == 'production' ? 'false' : 'true'
  

Gotchas and Tips

Pitfalls

1. Middleware Order Matters

   • Place SiteGuardMiddleware before route-specific middleware (e.g., auth) to avoid bypassing the password check.
   • Example of incorrect order (password prompt may not show):

     $router->pushMiddlewareToGroup('web', [
         \App\Http\Middleware\Authenticate::class, // Runs first!
         SiteGuardMiddleware::class,
     ]);
     

2. Caching Issues

   • If using Laravel’s cache (e.g., config_cache), clear it after publishing config:

     php artisan config:clear
     

   • Ensure SITE_GUARD_PASSWORD is not cached in .env files stored in version control.

3. Case Sensitivity

   • The password comparison is case-sensitive by default. Use strtolower() if needed:

     if (strtolower($inputPassword) !== strtolower($configPassword)) { ... }
     

4. CSRF Token Mismatch

   • The password form may fail if CSRF protection is enabled. Ensure the form includes:

     @csrf
     

Debugging

• Check Middleware Application Verify the middleware is registered by inspecting the web middleware group:

  php artisan route:list --show-middleware
  

• Log Failed Attempts Add logging to SiteGuardMiddleware to track brute-force attempts:

  \Log::warning('Failed Site Guard attempt for IP: ' . request()->ip());
  

• Test in Incognito Mode Clear cookies/cache when testing to avoid cached password prompts.

Extension Points

1. Custom Validation Logic Extend the middleware to add rate-limiting or IP restrictions:

   if ($this->isBlockedIp(request()->ip())) {
       abort(403, 'Access denied.');
   }
   

2. Multi-Password Support Store multiple passwords in the database and validate against them:

   $validPasswords = Password::where('active', true)->pluck('password')->toArray();
   if (!in_array($inputPassword, $validPasswords)) { ... }
   

3. Password Reset Endpoint Add a /reset-site-guard-password route with admin-only access to update the password dynamically.

4. Two-Factor Integration Combine with Laravel’s two-factor middleware for additional security:

   $router->pushMiddlewareToGroup('web', [
       SiteGuardMiddleware::class,
       \App\Http\Middleware\EnsureTwoFactorAuth::class,
   ]);