Authentication — identity only. It answers who is logged in and provides the
verbs to change that (attempt/login/logout), behind a swappable guard. It does
not do permissions: those are hydrakit/authorization. It does not know your
users: that one contract is left for the app to fulfil.
A controller injects GuardInterface and asks it questions (check, user,
id) or drives a login (attempt, login, logout). It never touches the
session key, the user provider, or the hasher directly — the guard coordinates
those. SessionGuard keeps a single identifier in the session, resolves the
user at most once per request, and regenerates the session id on both login and
logout (fixation defense). Binding the interface keeps the mechanism swappable:
a token guard for an API could replace it without a controller change.
if ($guard->attempt($username, $password)) {
// logged in; session id regenerated
}Two deliberate details of SessionGuard:
- Deleted users don't haunt sessions. When the session holds an id the
provider no longer recognises (the account was deleted after login), the
guard removes the marker during that lookup — the session honestly reports
"guest" from then on instead of re-running a futile lookup on every request.
The session id is not regenerated there (it's a read path and nothing is
being granted); the next real
login()rotates it as always. - Failed attempts cost constant work.
attempt()burns exactly one hashing operation whether the user is missing, passwordless, or simply typed the wrong password, so response timing can't be used to enumerate accounts.
UserProviderInterface is the one contract auth deliberately leaves unbound —
it cannot know your storage. The app implements it (typically a repository over
its users table) and binds it at the composition root; a missing binding is a
loud container error, never a silent insecure default. The provider does lookups
only — it never sees a password. The app's user entity implements
AuthenticatableInterface (a stable identifier + the stored hash); auth never
sees the rest of the model.
AuthConfig holds only what genuinely varies per environment — the bcrypt work
factor (AUTH_HASH_COST, default 12) — and validates it against bcrypt's range
at construction. The session key the guard uses is a stable protocol constant on
the guard, not a deployment setting.