Read this when changing authentication, sessions, CSRF, roles, users, or user-management endpoints.

Identity and User Management

Purpose

This subsystem authenticates database-backed users into PHP sessions and lets administrators manage accounts and roles without exposing credentials.

Entity	Field	Type / storage	Notes
`users`	`id`	auto-increment integer	Account identifier.
`users`	`username`	`varchar(255)`, unique	Login identity and password-hash input.
`users`	`saltedpassword`	`varchar(255)`	Bcrypt hash of `username
`users`	`roles`	`varchar(4096)`	PHP-serialized role array; unserialized with classes disabled.
PHP session	`SESSION.user`	integer	Current authenticated user ID.
PHP session	`SESSION.csrf_token`	64-character hex string	Random 32-byte token used for state-changing API requests.
F3 global	`USERROLES`	array of strings	Runtime role registry populated by plugins.

Authentication loads by username and verifies username|password against the stored bcrypt hash.
Login starts a session when required, regenerates its ID, then stores only the user ID. Session responses include a CSRF token for anonymous and authenticated callers.
Server-side state-changing protected operations require a CSRF token using hash_equals; client route guards never replace this check.
Roles assigned through user administration must be strings in the current runtime role registry and are deduplicated.
Usernames are trimmed and must be non-empty. The unique database constraint is authoritative under concurrency.
If a username changes, a non-empty replacement password is required because the username is part of the password-hash input.
An administrator cannot delete their own account. The final account with the admin role cannot lose that role or be deleted.
Update/delete serialize final-admin checks with a transaction and SELECT id FROM users FOR UPDATE; failures roll back the transaction.
Public DTOs return only id, username, and, for administrator management, roles. Password hashes and serialized persistence fields never leave the API.

Constant	Value	Location
`User::PASSWORD_SEPARATOR`	`	`
`Controller::CSRF_SESSION_KEY`	`SESSION.csrf_token`	`src/OpenMind/Api/Controller.php`
`Controller::CSRF_HEADER`	`HTTP_X_CSRF_TOKEN`	`src/OpenMind/Api/Controller.php`
`UserController::ADMIN_ROLE`	`admin`	`src/OpenMind/Api/UserController.php`
`UserController::USERNAME_CONSTRAINT`	`uq_users_username`	`src/OpenMind/Api/UserController.php`