Alt Google 2Fa Addon Laravel Package

Getting Started

This is a Statamic addon (not a plain Laravel package), so treat it as a CP-level authentication feature rather than something you wire into your own controllers.

1. Install

   composer require alt-design/alt-google-2fa-addon
   

   v1.1.3 only bumps Statamic version constraints (PR #9), so if you were pinned to an older Statamic patch you may need composer update alt-design/alt-google-2fa-addon statamic/cms to pick it up. No migrations or breaking changes are announced in this release.

2. Publish and configure

   php artisan vendor:publish --tag=alt-google-2fa-addon-config
   

   Review the published config for enable/enforce flags and any route or view overrides before touching anything else.

3. Clear caches — Statamic aggressively caches config and the Stache. After install or config edits:

   php artisan config:clear && php artisan cache:clear && php artisan statamic:stache:clear
   

4. First use case: log into the Control Panel as a super user, open your user profile/security area, enable 2FA, scan the QR with Google Authenticator (or any TOTP app), confirm the 6-digit code, and save the recovery codes somewhere real (a password manager, not a Slack DM).

Look first at: the published config file, the addon's service provider (to see what it registers — middleware, listeners, routes), and the CP views if you plan to restyle the enrolment screen.

Implementation Patterns

Per-user opt-in vs. enforced rollout. The usual pattern is to enable 2FA for super users/editors first, verify the flow end-to-end in staging, then flip the enforce flag in config for everyone. Enforcing before users know how to enrol creates a support queue on day one — announce it, then enforce.

Config is the integration surface. Most behaviour (enforcement, allowed windows, view overrides) lives in the published config rather than in code. Commit the config file to the repo with env-driven values (e.g. ALT_2FA_ENFORCE=false locally, true in production) so environments differ without code changes.

Deployment checklist. The TOTP secret is tied to APP_KEY if stored encrypted — never rotate APP_KEY casually on a site with 2FA enabled, or every enrolled user is locked out. Ensure your deploy pipeline runs php artisan config:cache after env vars are in place, and that storage/ and the database are backed up before rolling out.

Testing. In feature tests, either seed a user as already-enrolled and stub the TOTP verification, or keep 2FA disabled in the testing environment via config. For deterministic TOTP assertions, freeze time (Carbon::setTestNow()) so the generated code is stable within a window.

Locked-out users. Have a documented recovery path before you need it: recovery/backup codes, plus a Tinker-based reset (User::find(...)->save() after clearing the relevant 2FA fields) or a config kill-switch. Write this into your runbook.

Extending. Standard Laravel extension points apply: publish and override the addon's views if you need branding, and listen for the addon's events (or hook Statamic's Statamic\Events\UserAuthenticated / login events) if you want to audit 2FA enrolments into your own table or logging pipeline.

Gotchas and Tips

• Version constraint conflicts are the main upgrade risk. v1.1.3 is a Statamic-version bump only. If Composer refuses to move, check composer why-not statamic/cms — a locked older Statamic is usually the culprit, not the addon.
• Stale caches cause "config changes do nothing". Statamic's config and Stache caching will happily serve the old enforcement setting. Clear caches after every config edit; this is the #1 source of "the addon is broken" reports.
• TOTP clock drift. Codes fail if the server clock drifts. Keep NTP running; if you see intermittent "invalid code" reports from a subset of users, check server time before blaming the addon.
• APP_KEY rotation = mass lockout. Encrypted secrets become undecryptable. Rotate only with a planned migration of the 2FA fields, or accept re-enrolment for everyone.
• Recovery codes are single-use. Users who burn through them silently have no fallback. Consider surfacing remaining-code count in your profile template, or document a regeneration step.
• Local dev friction. Being prompted for 2FA on every local login is noise. Gate enforcement behind an env flag and default it off in local/testing.
• Don't log secrets. Audit any custom logging or exception reporting around the login path — TOTP codes, secrets, and recovery codes must never hit your log aggregator.
• Upgrade cadence. This addon's release history is small and version-pin oriented; re-read the changelog on every bump and test the enrolment + login flow in staging rather than assuming a patch release is inert.