Aura Starter Kit Laravel Package

Getting Started

Scaffold a project with the kit rather than installing it into an existing app:

laravel new my-app --using=bluestarsystem/aura-starter-kit
cd my-app
npm install && npm run build
php artisan migrate
php artisan serve

The kit is a starting point you own, not a dependency you update — once scaffolded, the code lives in your repo and Composer no longer tracks it.

Where to look first, in order:

1. routes/settings.php (or routes/web.php) — the /settings routes for profile, password, and two-factor.
2. config/fortify.php — the feature flags (two-factor-authentication, email-verification, update-profile-information, update-passwords). This file decides which of the new screens are actually reachable.
3. app/Actions/Fortify/ — CreateNewUser, UpdateUserProfileInformation, UpdateUserPassword. This is where behaviour is customised.
4. resources/js/Pages/Settings/ — the Inertia pages for profile, password, and two-factor.
5. tests/Feature/Settings/ — 24 tests that double as documentation of the expected flows.

First real use case: register an account, walk to /settings, enable two-factor, scan or copy the secret, confirm with a TOTP code, then log the recovery codes. That single pass exercises nearly everything in this release.

Implementation Patterns

Adding a new settings screen. Copy the existing shape rather than inventing one: add the route inside the authenticated settings group, a controller (or Fortify action if it touches auth state), a FormRequest for validation, and an Inertia page under resources/js/Pages/Settings/. Reuse the existing layout and the shared UpdateProfileInformation-style form components so flash messages and validation errors behave identically.

Protecting sensitive settings with password confirmation. The two-factor page re-asks for the password because Fortify's endpoints sit behind password.confirm. The moment you add anything similarly sensitive (email change, deleting an account, API token rotation), wrap the route in the same password.confirm middleware and reuse the existing confirm-password modal component. Consistency here is cheap and users notice when it isn't there.

Extending the two-factor flow. Don't hand-roll enable/disable/confirm — call through Fortify's endpoints (user/two-factor-authentication, user/confirmed-two-factor-authentication, user/two-factor-recovery-codes). Your job is the UI around them: showing the QR code, exposing the plaintext secret for manual entry, and rendering the decrypted recovery codes. If you need different behaviour on confirm, use Fortify's action hooks rather than duplicating the controller logic.

Turning on email verification. The release deliberately registers the verification screen while leaving the feature off. Enabling it is: flip Features::emailVerification() in config/fortify.php, add MustVerifyEmail to App\Models\User, and confirm the verified middleware is applied where you want it. That's the "one uncommented line" claim — treat it as a two-line change at minimum, because the model interface is easy to forget and the failure mode is silent.

Customising Fortify behaviour. Profile updates and password changes flow through UpdateUserProfileInformation and UpdateUserPassword. Adding a field to the profile form means updating the action, the FormRequest, the Inertia page, and the feature test — four places, and the test will tell you if you missed one.

Mirroring CI locally. The GitHub Actions workflow builds assets before running the suite. If your tests render pages that use @vite, a missing manifest produces a confusing 500 rather than a clean failure. Run npm run build (or keep npm run dev alive) before php artisan test when you're touching anything front-end.

Gotchas and Tips

Password confirmation will break your tests before it breaks your app. Tests hitting the two-factor endpoints need the confirmation session value set, e.g. $this->withSession(['auth.password_confirmed_at' => time()]), or they'll redirect instead of doing what you expect. If you see 302s to a confirm-password page in a feature test, this is almost always why.

Feature flags gate routes, not just UI. With two-factor-authentication disabled in config/fortify.php, the endpoints 404 regardless of whether the page exists. Symptom: the settings page renders and the buttons do nothing useful. Check the config before debugging the controller.

Recovery codes are encrypted at rest, not hashed. Use Fortify's accessors to read them — $user->recoveryCodes() decrypts. Attempting to compare a submitted code against the raw DB column will never match. Related: rotating APP_KEY silently invalidates every stored 2FA secret and recovery code set, locking out all 2FA users. Back up the key and plan for a re-enrolment path.

The QR code depends on built assets. If /settings/two-factor renders a blank box where the QR should be, you're looking at a stale Vite manifest or the dev server isn't running — not a Fortify bug. The plaintext secret is the intended fallback; make sure your UI keeps it visible and copyable, that's the entire point of shipping it alongside the QR.

Email verification is off, so don't assume the screen is working. Verify the flow end-to-end after enabling the feature, including the resend link and the signed URL. It's untested-by-default territory in this kit precisely because the feature ships disabled.

Passkeys are not supported. Fortify ships them, but they need a WebAuthn ceremony in JavaScript this kit doesn't include. Enabling the Fortify passkeys feature will give you routes with no working front end. Leave it off unless you're prepared to build the client-side registration and assertion flows yourself.

Don't try to composer update the starter kit. It's a scaffold, not a package. Pulling a new kit release into an existing app means diffing the repo by hand and porting what you want. Pin the version in your scaffolding notes if you care about reproducing the baseline later.

Treat the 24 tests as the contract. Before modifying the settings pages, read the corresponding feature test — it encodes the exact redirect, session, and validation expectations. When you extend a settings screen, extend its test in the same commit; the suite is small enough that regressions are otherwise easy to miss.

Where to extend rather than edit. Custom Fortify behaviour belongs in app/Actions/Fortify/ and config; editing the kit's Inertia pages is fine and expected, but keep auth-state logic out of them so a future manual port from upstream stays tractable.