Passwords & Authentication Sessions
Password hashing and authentication-specific session state.
Password Hashing
Passwords are hashed using PHP PASSWORD_DEFAULT and verified against the stored user
document hash. The password controller exposes a rehash check for algorithm or cost changes.
Passwords
must never be stored as plaintext.
Authentication Session State
The authentication session controller uses the APPNETOS Core Session service rather than PHP $_SESSION.
It tracks the authenticated or pending user ID, login timestamp, temporary TOTP enrollment secret
and
email challenge state. Session identifiers are rotated on authentication transitions.
Email challenge codes are stored as HMAC hashes with expiration and attempt counters, not as
plaintext.
These authentication-specific values live inside the broader session managed by
Core\Session.
Example
use Core\Registry;
use Core\User\Auth\Password;
$password = Registry::get(Password::class);
$hash = $password->hash($plainPassword);
// Persist $hash through the concrete user document.
Public API Reference
Core\User\Auth\Password
Class & Registry
Class:
Core\User\Auth\Password
Extends:
Core\User\Auth\Password\Base
use Core\User\Auth\Password;
use Core\Registry;
$password = Registry::get(Password::class);
| Method | Description |
|---|---|
public function hash(string $password): string |
Hash password |
public function verify( UserDocument $userDocument, string $password ):
bool
|
Verify password |
public function needsRehash(UserDocument $userDocument): bool |
Check if password hash requires rehash |
Core\User\Auth\Session
Class & Registry
Class:
Core\User\Auth\Session
Extends:
Core\User\Auth\Session\Base
use Core\User\Auth\Session;
use Core\Registry;
$session = Registry::get(Session::class);
| Method | Description |
|---|---|
public function init(): void |
Initialize authentication session controller |
public function login( ObjectId|string $userId, bool $twoFactorPending = false
):
void |
Start authenticated login session |
public function completeTwoFactor(): void |
Complete two-factor authentication |
public function logout(): void |
Logout |
public function setTwoFactorSetup( string $provider, string $secret ):
void
|
Set two-factor authentication setup |
public function clearTwoFactorSetup(): void |
Clear two-factor authentication setup |
public function getTwoFactorSetupProvider(): string|null |
Get two-factor authentication setup provider |
public function getTwoFactorSetupSecret(): string|null |
Get two-factor authentication setup secret |
public function getTwoFactorSetupTime(): int |
Get two-factor authentication setup time |
public function setEmailChallenge( string $codeHash, int $lifetime ):
bool
|
Set email two-factor authentication challenge |
public function clearEmailChallenge(): void |
Clear email two-factor authentication challenge |
public function hasEmailChallenge(): bool |
Check if email two-factor authentication challenge exists |
public function isEmailChallengeExpired(): bool |
Check if email two-factor authentication challenge is expired |
public function incrementEmailChallengeAttempts(): int |
Increment email two-factor authentication challenge attempts |
public function getEmailChallengeHash(): string |
Get email two-factor authentication challenge hash |
public function getEmailChallengeCreatedAt(): int |
Get email two-factor authentication challenge creation time |
public function getEmailChallengeExpiresAt(): int |
Get email two-factor authentication challenge expiration time |
public function getEmailChallengeAttempts(): int |
Get email two-factor authentication challenge attempts |
public function getUserId(): ObjectId|null |
Get authenticated or pending user ID |
public function isAuthenticated(): bool |
Check if user is authenticated |
public function isTwoFactorPending(): bool |
Check if two-factor authentication is pending |
public function getLoginTime(): int |
Get login time |
Implementation Details
The following technical reference expands the existing guide with authentication lifecycle, state management, and provider behavior.
Password Authentication
Overview
Core\User\Auth\Password\Base provides the shared APPNETOS password cryptography
layer.
It intentionally contains no user lookup, login-state, session or two-factor authentication logic.
API
hash()
verify()
needsRehash()
Hashing
Passwords are hashed using PHP's current:
PASSWORD_DEFAULT
Example:
$hash = $password->hash($plainPassword);
Using PASSWORD_DEFAULT allows APPNETOS to follow future PHP password-hashing
recommendations without changing the public Core API.
Verification
Verification operates against the password hash persisted in the user document:
$password->verify(
$userDocument,
$plainPassword,
);
Users without a password hash cannot authenticate through the shared password controller.
Rehash Detection
$password->needsRehash($userDocument);
The method detects whether the persisted hash should be recreated with the currently active PHP password algorithm or options.
Responsibility Boundary
Password controller
→ password cryptography only
Auth controller
→ login workflow
User document
→ persisted password hash
Password policies, password-reset workflows and UI validation should remain separate from this controller.
Authentication Session
Overview
Core\User\Auth\Session\Base stores temporary authentication state in the mapped
APPNETOS
Core\Session.
The controller is context-neutral. Session persistence, cookie naming and session scope remain
responsibilities of Core\Session and Core\Cookie.
State Groups
The authentication session contains three logical state groups.
Authentication State
appnetos_auth_user_id
appnetos_auth_authenticated
appnetos_auth_2fa_pending
appnetos_auth_login_time
Temporary TOTP Setup State
appnetos_auth_2fa_setup_provider
appnetos_auth_2fa_setup_secret
appnetos_auth_2fa_setup_time
Temporary Email Challenge State
appnetos_auth_2fa_email_hash
appnetos_auth_2fa_email_created_at
appnetos_auth_2fa_email_expires_at
appnetos_auth_2fa_email_attempts
Login
On login:
- The session ID is regenerated.
- Previous TOTP setup state is cleared.
- Previous email challenge state is cleared.
- The user ID is stored.
- Authentication state is stored.
- Two-factor pending state is stored.
- Login time is stored.
Without pending 2FA:
authenticated = true
twoFactorPending = false
With pending 2FA:
authenticated = false
twoFactorPending = true
Two-Factor Completion
After successful 2FA:
- The session ID is regenerated.
- Temporary TOTP setup state is cleared.
- Temporary email challenge state is cleared.
authenticatedbecomestrue.twoFactorPendingbecomesfalse.
Logout
Logout removes all authentication and temporary 2FA state and regenerates the session ID.
TOTP Setup State
Temporary TOTP enrollment stores:
provider
secret
creation time
The temporary secret is not persisted to the user document until successful verification.
Email Challenge State
The email challenge stores only:
code hash
created timestamp
expiration timestamp
failed-attempt count
The original email code is never stored in the authentication session.
Challenge Expiration
A missing or incomplete challenge is treated as expired.
Expired challenges are removed by the authentication workflow before further verification.
Attempt Counter
Each invalid email-code verification increments the attempt counter.
The session controller only stores the count. The maximum number of allowed attempts is defined by the authentication workflow.
Session Regeneration
The authentication session ID is regenerated:
on login
after successful 2FA
on logout
This reduces session-fixation risk.