Password Management

Purpose and Scope

This document covers password management functionality in the Light framework, including password expiration policies, password reset flows with JWT-based verification codes, and password change operations.

For basic password authentication and verification during login, see Password Authentication. For token generation after successful authentication, see JWT Token System.

---

Password Expiration System

The framework supports configurable password expiration policies that force users to update their passwords periodically. This feature is controlled through database configuration settings and enforced at both login time and through dedicated password change endpoints.

Configuration

Password expiration is controlled by two configuration keys stored in the Config model:

Configuration Key	Type	Default	Description
password_expiration	boolean	false	Enables/disables password expiration enforcement
password_expiration_duration	integer	90	Number of days before password expires

Password Age Tracking

Each User record maintains a password_dt timestamp field that records when the password was last changed. This field is updated automatically when:

• A new user is created during initial login src/Controller/AuthController.php387
• A password is reset via resetPassword mutation src/Controller/AuthController.php587-591
• A password is changed via changeExpiredPassword mutation src/Controller/AuthController.php94-99

Expiration Enforcement at Login

During the standard login flow, the system checks password expiration before issuing JWT tokens:

Expiration Check During Login Flow

Sources: src/Controller/AuthController.php446-452

changeExpiredPassword Mutation

The changeExpiredPassword mutation allows users to update expired passwords without authentication:

Method Signature:

Flow Diagram:

changeExpiredPassword Mutation Flow

Key Security Features:

• Requires old password verification even when expired
• Enforces password policy validation via System.isValidPassword() src/Controller/AuthController.php89
• Updates password_dt timestamp to current datetime src/Controller/AuthController.php96
• Uses direct table update to bypass audit trail for security operations src/Controller/AuthController.php94-99

Sources: src/Controller/AuthController.php64-102

---

Password Reset Flow

The password reset system uses a secure JWT-based verification code mechanism that allows users to reset forgotten passwords via email. The flow involves three mutations working together to provide a secure, rate-limited reset process.

System Architecture

Password Reset System Components

Sources: src/Controller/AuthController.php533-635

Step 1: Initiating Password Reset (forgetPassword)

The forgetPassword mutation initiates the reset process by generating a verification code, sending it via email, and returning a JWT token.

Method Signature:

Process Flow:

forgetPassword Mutation Sequence

JWT Payload Structure:

Email Configuration:

The email sent to the user is configured via the Config model:

Config Key	Default	Description
forget_password_email_subject	"Password Reset Code"	Email subject line
forget_password_email_template	"Your password reset code is: {code}"	Email body template with {code} placeholder

Security Features:

• Silent failure (returns empty string) when user not found to prevent username enumeration src/Controller/AuthController.php603
• Code is hashed with JWT_SECRET before storing in JWT src/Controller/AuthController.php621
• JWT expires after 10 minutes (600 seconds) src/Controller/AuthController.php627
• Original code sent via email, hash stored in JWT payload

Sources: src/Controller/AuthController.php597-635

Step 2: Verifying Reset Code (forgetPasswordVerifyCode)

The forgetPasswordVerifyCode mutation validates the user-entered code against the JWT payload with rate limiting.

Method Signature:

Verification Flow:

Code Verification Flow with Rate Limiting

Rate Limiting Mechanism:

• Each unique code_hash allows maximum 5 verification attempts src/Controller/AuthController.php546
• Attempt counter stored in cache with key reset_code_attempt_{code_hash} src/Controller/AuthController.php542
• Counter expires after 10 minutes (600 seconds) src/Controller/AuthController.php549
• Prevents brute force attacks on 6-digit codes (1,000,000 possibilities)

Sources: src/Controller/AuthController.php533-552

Step 3: Completing Password Reset (resetPassword)

The resetPassword mutation completes the reset process by validating the code and updating the user's password.

Method Signature:

Reset Flow Diagram:

resetPassword Mutation Flow

Security Features:

• JWT type validation ensures token is for password reset src/Controller/AuthController.php564
• Calls forgetPasswordVerifyCode for rate-limited verification src/Controller/AuthController.php568
• Additional hash verification as security belt src/Controller/AuthController.php578
• Password policy validation via System.isValidPassword() src/Controller/AuthController.php583
• Direct table update to set new password src/Controller/AuthController.php587-591

Note: The password_dt field is NOT updated during password reset, only during changeExpiredPassword. This is an implementation detail that may need review.

Sources: src/Controller/AuthController.php555-594

Complete Password Reset Sequence

End-to-End Password Reset Flow

Sources: src/Controller/AuthController.php533-635

---

Password Validation and Policy

The framework enforces password policies through the System::isValidPassword() method, which is called before:

• Setting a new password during reset src/Controller/AuthController.php583
• Changing an expired password src/Controller/AuthController.php89

The specific validation rules are implemented in the Light\Type\System class (not shown in provided files, but referenced in the code).

Password Hashing

All passwords are hashed using PHP's password_hash() function with PASSWORD_DEFAULT algorithm:

This currently uses bcrypt, but will automatically upgrade to stronger algorithms as PHP evolves.

Sources: src/Controller/AuthController.php383 src/Controller/AuthController.php588 src/Controller/AuthController.php95

---

Legacy Password Migration

The framework includes detection for legacy password hashes that used older algorithms (SHA-256/SHA-512 crypt formats).

Legacy Hash Detection

The PasswordVerify private method checks for legacy hash prefixes:

Legacy Password Detection Flow

Legacy Hash Formats:

• $5 prefix: SHA-256 crypt
• $6 prefix: SHA-512 crypt

When detected, the system requires manual password reset by an administrator rather than attempting to verify or migrate automatically. This prevents potential security issues with legacy hash algorithms.

Sources: src/Controller/AuthController.php458-465

---

Integration with Other Authentication Features

Login Integration

Password expiration is checked during the standard login mutation after successful password verification but before JWT token generation src/Controller/AuthController.php446-452 If the password is expired, the login fails with error "password is expired", prompting the user to call changeExpiredPassword.

Initial User Creation

When the system has zero users (first-time setup), the login mutation automatically creates an initial administrator user with:

• Username and password from login attempt
• Default language: "en"
• Initial password_dt set to current datetime src/Controller/AuthController.php387
• Automatically added to "Administrators" role src/Controller/AuthController.php390-393

This allows bootstrapping the system without pre-existing user accounts.

Sources: src/Controller/AuthController.php378-394 src/Controller/AuthController.php446-452

---

Summary of Mutations

Mutation	Parameters	Authentication Required	Purpose
changeExpiredPassword	username, old_password, new_password	No	Update expired password (requires old password)
forgetPassword	username, email	No	Initiate password reset, returns JWT
forgetPasswordVerifyCode	jwt, code	No	Verify reset code (rate-limited)
resetPassword	jwt, password, code	No	Complete password reset with new password

All mutations that modify passwords enforce validation via System.isValidPassword() and use password_hash() with PASSWORD_DEFAULT algorithm.

Sources: src/Controller/AuthController.php64-102 src/Controller/AuthController.php533-635