Nova Aegis Admin Ip Access Laravel Package

Getting Started

This package gates administrative access behind an IP whitelist and ships recovery commands so an operator can restore access without a database console (typically AddIpToWhitelist and DisableAdminIpAccess invoked via Artisan). The v1.2.0 release is an internal refactor only — the recovery commands now delegate to dedicated action classes — so no application changes are required to upgrade.

Minimal first steps:

1. Install and publish config: composer require <vendor>/<package> then php artisan vendor:publish --tag=<package>-config.
2. Add your current public IP to the whitelist before enabling enforcement, or you will lock yourself out of the admin entry point.
3. Enable the guard/middleware on the admin route group (or panel provider) and verify access from a whitelisted and non-whitelisted IP.
4. Confirm the recovery commands are registered: php artisan list | grep -i ip.

First use case: protect /admin (or a Filament panel) so only office/VPN egress IPs can authenticate, with a documented break-glass path using the recovery commands.

Implementation Patterns

Route-level enforcement. Apply the package middleware to the admin route group rather than globally, so public routes and health checks are unaffected. If you use Filament, register it on the panel's middleware stack.

Config-driven allowlist. Keep persistent IPs in the published config and treat runtime additions (via the whitelist action/command) as temporary operational state. This keeps infrastructure-as-code reviewable and avoids drift between environments.

Programmatic use via actions. The v1.2.0 refactor surfaces AddIpToWhitelist and DisableAdminIpAccess as injectable actions. Resolve them from the container in your own commands, jobs, or onboarding flows instead of shelling out to Artisan:

app(AddIpToWhitelist::class)->handle($request->ip(), $note = 'onboarding');

This is the cleanest integration point for provisioning new team members' static IPs or auto-whitelisting a CI runner.

Break-glass runbook. Document the recovery command sequence (add IP → verify → re-enable) alongside your incident playbook. Test it in staging, not production, and confirm the command works when the admin UI itself is inaccessible.

Environment-aware configuration. Disable enforcement locally and in testing (APP_ENV checks in config), enable it in staging to exercise the middleware, and keep production enabled with a known-good static IP plus VPN range.

Testing. Use Laravel's request IP faking ($this->withServerVariables(['REMOTE_ADDR' => '203.0.113.10']) or Request::create(..., server: ['REMOTE_ADDR' => ...])) to assert both allowed and denied paths, and cover the recovery command with a feature test.

Gotchas and Tips

• Lockout is the primary risk. Adding the middleware before whitelisting your own IP is the most common first-run mistake. Always seed an allowlist entry first.
• Proxy and load balancer IPs. Behind Cloudflare, an ALB, or a reverse proxy, $request->ip() returns the proxy address unless TrustProxies is configured correctly. Verify what the middleware sees before trusting the whitelist.
• IPv6 vs IPv4. 127.0.0.1 does not match ::1. Store both forms where relevant, and normalise input (CIDR support varies by package — check the config/docs).
• Config caching in production. After changing the whitelist config, run php artisan config:cache (and config:clear during debugging). Stale cached config is a frequent "why is my IP still blocked" cause.
• Recovery commands need production shell access. If your platform has no SSH/console (some PaaS setups), plan an alternative — a tinker session, an env-var kill switch, or a deployment-time invocation.
• v1.2.0 specifically: the action extraction is internal and behaviour-preserving. If you had extended or overrode the recovery commands, re-run your tests — command internals now route through actions, so any monkey-patching or subclassing of command logic should be reviewed against the new action classes. Otherwise, upgrade is a no-op.
• Extension points. Overriding the action classes (binding your own implementations in a service provider) is now the idiomatic way to customise whitelist persistence or add audit logging — prefer this over editing published command code, which will be overwritten on updates.