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 array of persistent numeric permission IDs; 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.

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.
Permissions assigned through user administration must be existing persistent numeric permission IDs 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 permission ID 1 cannot lose that permission 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`
Administrator authorization permission ID	`1`	Authorization contract used by administrator-only operations.
`UserController::USERNAME_CONSTRAINT`	`uq_users_username`	`src/OpenMind/Api/UserController.php`