Authentication and account security#

Elang's Auth Starter includes registration, session login, verification, password recovery, profile updates, password rotation, and scoped API tokens. Enable it with AuthProvider; the starter already does that for you.

Create an authenticated application#

elang new my-app --starter=auth
cd my-app
php elang serve

After one-time installer setup, this command creates the application through Composer. Dependencies, the application key, schema migrations, and doctor checks are part of project setup. Open /register to create your own account. No shared administrator password is included.

Sessions and protected routes#

AuthProvider groups browser account routes behind session, CSRF, and rate-limit middleware. Login regenerates the session identifier and CSRF token. Logout invalidates the session. Request bodies and authorization values are not recorded by Elang Studio.

Use RequireAuth on private browser routes after SessionMiddleware. It sets the current User in the _user request attribute. A temporary password redirects the user to /password before private features can be used.

$router->get('/private', fn () => ['message' => 'Signed in'])
    ->middleware(SessionMiddleware::class, RequireAuth::class);

Use the complete middleware group shown in the starter for state-changing forms, including CsrfMiddleware. A protected route still needs application-specific ownership or policy checks.

Passwords and recovery#

Public passwords require at least 12 characters and support long passphrases. The stored value is an Argon2id hash. A trusted terminal can create a temporary password that must be changed at first sign-in.

Recovery and verification links use random one-time tokens. Only token hashes are stored in the database, with purpose and expiry. A successful password change invalidates other sessions and revokes API tokens. Resetting a password does not silently sign the user into a new browser.

Local email and production email#

With APP_ENV=local and the null mail transport, account messages are stored encrypted in the private development mailbox. Open /_elang/studio/mail locally to use a verification or reset link.

In production, configure MAILER_DSN and MAIL_FROM. A null transport does not claim to deliver account mail; recovery reports that service is unavailable. The local mailbox and Studio are not exposed in production.

Authorization and roles#

Registration always creates a normal user. Submitted role fields are not accepted. Trusted provisioning can create an administrator, and RequireAdmin also requires email verification. Gate lets an application define explicit policies:

$gate->define('post.update', fn (User $user, Post $post) =>
    $post->author_id === $user->id
);
$gate->authorize('post.update', $user, $post);

Scope database queries by the current user's identifier, including reads, updates, and deletes. The complete blog, workspace, and API starters demonstrate this boundary.

API tokens#

Create tokens from the account page after verification and password confirmation. The raw token is displayed once. Database rows store a SHA-256 digest, explicit scopes, owner, and expiry. BearerAuth authenticates a token; RequireScope checks the route's _scope default. Token ownership never comes from a request body.