User & Session Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The User & Session Endpoints module manages user authentication, authorization levels, and profile management within the HX-Music ecosystem. It provides the necessary infrastructure for user registration, secure login via token-based authentication, and administrative control over user accounts. Sources: HX-Music-Server/doc/api.md:255-257, HX-Music-Server/include/api/UserApi.hpp:38-41
The system follows a Client-Server architecture where the Server handles database operations and credential validation, while the Client manages local session state and token storage. It supports three distinct permission levels: Administrator, Regular User, and Read-Only User. Sources: README.md:12-14, HX-Music-Server/include/api/UserApi.hpp:81-83
Authentication Architecture
HX-Music uses a token-based session management system. Upon successful login, the server generates a unique token that the client must include in subsequent requests for protected resources. Sources: HX-Music-Server/include/api/UserApi.hpp:115-125
Login Flow
When a user attempts to log in, the server validates the username against the database, retrieves the user's unique salt, and verifies the MD5 hash of the salted password. If valid, the server returns a token containing the user ID and session expiration details. Sources: HX-Music-Server/include/api/UserApi.hpp:104-129
The following sequence diagram illustrates the authentication flow between the Client Controller, the API layers, and the Server-side data access objects (DAO):
User Management Endpoints
The server exposes endpoints for account creation, deletion, and retrieval. Access to administrative functions like adding or deleting other users is restricted to accounts with the Administrator permission level. Sources: HX-Music-Server/include/api/UserApi.hpp:78-80, HX-Music-Server/include/api/UserApi.hpp:195-197
User Operations Table
| Endpoint | Method | Permission | Description |
|---|---|---|---|
/user/add | POST | Administrator | Registers a new user with a specified permission level. |
/user/login | POST | Public | Validates credentials and returns an authentication token. |
/user/del/{id} | DELETE | Administrator | Removes a user account by its unique ID. |
/user/selectAll | GET | Administrator | Retrieves a list of all registered users and their metadata. |
/user/testToken | GET | ReadOnlyUser | Validates the current session token. |
Sources: HX-Music-Server/include/api/UserApi.hpp:51-210, HX-Music-Server/doc/api.md:255-321
Profile and Identity Management
Users can modify their own identity information, including usernames, passwords, and avatars. Password updates trigger a "session invalidation" by regenerating the user's internal login UUID, effectively logging out all current sessions using the old credentials. Sources: HX-Music-Server/include/api/UserApi.hpp:157-175, HX-Music-Server/doc/api.md:280-285
Security Measures
- Salted Hashing: The server generates a unique V4 UUID as a salt for every new user and password update. Sources: HX-Music-Server/include/api/UserApi.hpp:90-95
- MD5 Validation: Passwords are never stored in plain text; only the MD5 hash of the
password + saltconcatenation is persisted. Sources: HX-Music-Server/include/api/UserApi.hpp:100-101 - Permission Interceptors: Endpoints are wrapped in
TokenInterceptortemplates to enforce access control at the network layer. Sources: HX-Music-Server/include/api/UserApi.hpp:53, HX-Music-Server/include/api/UserApi.hpp:131
Avatar Management Flow
The avatar system allows users to upload and retrieve profile pictures. Avatars are stored on the server filesystem as .jpg files named after the user's ID. Sources: HX-Music-Server/include/api/UserApi.hpp:58-75
Client-Side Session Control
The UserController class serves as the primary interface for the UI to interact with user sessions. It monitors the GlobalSingleton for backend configuration and emits signals to update the UI when login states change. Sources: HX-Music-Client/include/controller/UserController.h:32-50
Session Monitoring
Upon initialization, the controller executes testToken(). If the local token is invalid or expired, it automatically triggers a logout and redirects the user to the login view. Sources: HX-Music-Client/include/controller/UserController.h:54-68
// HX-Music-Client/include/controller/UserController.h:54-61
void testToken() {
UserApi::testTokenReq().thenTry([this](https://github.com/HengXin666/HX-Music/blob/d7b754c61fdd03dee10b8856dba281b53017e573/auto%20t) {
QMetaObject::invokeMethod(
QCoreApplication::instance(),
[this, _t = std::move(t)] {
if (!_t) {
MessageController::get().show<MsgType::Warning>("Token invalid, please login again");
logoutReq();
Sources: HX-Music-Client/include/controller/UserController.h:54-61
Summary
The User & Session Endpoints provide a secure framework for managing access to HX-Music. By combining salted MD5 hashing, token-based session tracking, and server-side permission interceptors, the system ensures that user data and administrative functions are protected. The architecture facilitates seamless identity management for the client while maintaining strict control over user permissions and session validity on the server. Sources: HX-Music-Server/include/api/UserApi.hpp:38-45, README.md:12-14