APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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:

  1. The session ID is regenerated.
  2. Previous TOTP setup state is cleared.
  3. Previous email challenge state is cleared.
  4. The user ID is stored.
  5. Authentication state is stored.
  6. Two-factor pending state is stored.
  7. Login time is stored.

Without pending 2FA:

authenticated = true
twoFactorPending = false

With pending 2FA:

authenticated = false
twoFactorPending = true

Two-Factor Completion

After successful 2FA:

  1. The session ID is regenerated.
  2. Temporary TOTP setup state is cleared.
  3. Temporary email challenge state is cleared.
  4. authenticated becomes true.
  5. twoFactorPending becomes false.

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.

Next Steps

Previous

Authentication

Explore Authentication

Next

Two-Factor Authentication

Explore Two-Factor Authentication