Otp Auth Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package> (check the release notes for the exact package name), then publish config and migrations: php artisan vendor:publish --tag=otp-config and php artisan migrate.
• Add the package trait to your App\Models\User model (typically HasOtpAuthentication) and confirm the otp guard/middleware is registered.
• First place to look: config/otp.php for driver selection (TOTP, email, SMS), recovery settings, and the recoveryAction route/controller binding.
• First use case: enable OTP for a user, verify the initial code, then protect a route group with the package middleware. The recovery flow is the second integration point — especially after 1.2.4, which makes recoveryAction fail loudly when the user has no OTP authentication configured.

Implementation Patterns

• Enrollment: generate a secret, render the QR/provisioning URI, require a valid code before persisting otp_enabled_at. Do not mark OTP as enabled until verification succeeds.
• Login challenge: after primary credentials pass, redirect to an OTP challenge route rather than issuing a session immediately. Verify the code, then regenerate the session and mark the OTP challenge as passed.
• Middleware protection: apply the package middleware to authenticated route groups. Keep the recovery route reachable only through its own signed URL or token flow, not by guessing user IDs.
• Recovery: wrap recoveryAction calls in a guard that checks OTP enrollment. In 1.2.4 this action now throws when the user has not enabled OTP, so either catch that exception and redirect to enrollment, or hide recovery links for non-OTP users.
• Integration with Breeze/Fortify/Jetstream: replace the final authentication step with the OTP challenge. Keep the original password validation intact; OTP is a second factor, not a replacement.
• Testing: fake the OTP driver in tests, freeze time for TOTP, and assert that recoveryAction throws for users without OTP authentication after upgrading to 1.2.4.

Gotchas and Tips

• 1.2.4 hotfix: recoveryAction now throws an exception if the user has no OTP authentication. This is a behavior change from any silent/no-op path. Guard the route or catch the exception; otherwise users without OTP may see a 500 instead of a helpful redirect.
• Encrypt OTP secrets at rest and never log them in production. Use the package’s local/debug logging only in development.
• TOTP clock drift: configure the verification window and ensure server time is synchronized.
• Rate-limit OTP verification attempts; the package may not enforce this by default.
• Clear config cache after changing drivers or recovery settings (php artisan config:clear).
• Recovery codes should be one-time-use and stored hashed. Regenerate and invalidate old codes when OTP is re-enrolled.
• Extension points: custom OTP drivers, notification channels for delivering codes, and overridden recovery code generators. Check the package’s service provider bindings before forking behavior.