fix!: harden audit routes and unify login gate (BREAKING — release as v0.5.0)

[bherila]

Summary

Four integration bugs were surfaced in a consuming app (vora). This PR fixes the three findings that the package itself can prevent; the fourth is purely app-side.

Finding 1 (P1) — Access-control bypass on audit routes: FIXED

Root cause: The package's audit routes were protected by auth middleware only. If a consuming app's Gate ability for audit.admin_ability only checked is_admin without verifying approved_at/is_disabled, a pending or disabled admin could reach the cross-user admin endpoint.

Fix:

• Added AuthUserPolicy::canLogin(Authenticatable $user, Request $request): bool to the contract — the single gate for all account-state checks (active, approved, not disabled, etc.).
• DefaultAuthUserPolicy::canLogin() duck-types $user->canLogin(), falls back to is_disabled, defaults to true. canPasskeyLogin() now delegates to canLogin() so both share one implementation.
• New RequireActiveUser middleware aborts 403 when the authenticated user fails canLogin(). Applied automatically on all package audit routes (in addition to auth).
• Added a warning comment in bherila-auth.php config that admin_ability gate definitions must check account state as well as role.

Finding 2 (P1) — Lockout-after-migration of approved_at: DOCUMENTED

Root cause: Apps adding an approved_at (nullable, null = pending) column to their users table leave all existing rows as null after migration, instantly locking out every current user.

Why package can't fully fix this: The approved_at column is app-owned — the package does not ship a migration for the user table. There is nothing to backfill in this repo.

Fix: Added a prominent README section with a copy-paste backfill snippet explaining the requirement and the risk.

Finding 3 (P2) — Post-verification redirect divergence: DOCUMENTED

Root cause: A consuming app hardcoded /pending in its email-verification callback instead of calling AuthUserPolicy::redirectAfterLogin(), so an already-approved user who verified their email was falsely shown the pending page.

Why package can't fully fix this: The package does not ship an email-verification controller — that is app-owned. The bug was in vora's controller.

Fix: Added README guidance that after email verification the app must call redirectAfterLogin() (not a hardcoded path), and that canLogin() should be checked at every entry point including verification callbacks.

Finding 4 (P3) — Dropdown outside-click bug: NOT APPLICABLE

The package ships no navbar, dropdown, or menu components. The bug was in vora's own React component. No change.

Test plan

• All 40 existing tests continue to pass (composer test)
• 7 new assertions in RequireActiveUserTest cover: canLogin() default allow, canLogin() via duck-typed canLogin() method, is_disabled fallback, canPasskeyLogin() delegation to canLogin(), middleware pass-through for active user, middleware 403 for inactive user, middleware pass-through for unauthenticated (lets auth middleware handle it)
• Squash-merge this PR (single logical change)

🤖 Generated with Claude Code

[bherila]

⚠️ Breaking change — must be tagged v0.5.0, not v0.4.x.

This PR adds a required canLogin(Authenticatable, Request): bool method to the AuthUserPolicy contract. Direct implementers of that interface (e.g. vora's VoraAuthUserPolicy) will fatal until they add the method, so the upgrade must be opt-in.

The package versions via git tags (latest v0.4.3) and consumers pin ^0.4 (>=0.4.0 <0.5.0). Tagging this as v0.4.4 would auto-upgrade those consumers and break them. Tag the merge as v0.5.0. Consumer migration steps are in the new README “Upgrading to v0.5.0” section.

Squash-merge per repo convention.