Overview
Mercury Core uses session-based authentication with secure cookies. All authentication endpoints are form-based and redirect on success.Login
Authenticate a user and create a session.Request
Username (case-insensitive). Must match the username validation pattern.
User password. Minimum 1 character, maximum 6969 characters.
Response
On success, sets a session cookie and redirects to/home.
Session cookie with 30-day expiration
- Name:
session - Max Age: 30 days
- Secure: true (in production)
- Path:
/
Errors
Empty string if username is invalid
“Incorrect username or password” - Generic error message for security
Implementation Details
Passwords are verified using Bun’s password verification against hashed passwords stored in the database. The implementation intentionally provides generic error messages to prevent user enumeration attacks. Source:Site/src/routes/(plain)/login/+page.server.ts:24-49
Register
Create a new user account and initiate a session.Request
Desired username. Must be unique and match validation pattern.
Email address (if enabled in configuration). Must be RFC-5321 compliant.
Password. Minimum 16 characters, maximum 6969 characters.
Password confirmation. Must match the password field.
Registration key (if enabled in configuration). Must include the configured prefix.
Response
On success, creates the user account, requests avatar render, sets session cookie, and redirects to/home.
Session cookie with 30-day expiration
Created user record with:
id: User record IDusername: Confirmed usernamepermissionLevel: 1 (standard user)bodyColours: Default body colors from config
Validation Errors
“Passwords do not match” - When password and cpassword don’t match
“This username is already in use” - Username conflict
“This email is already in use” - Email conflict (if emails enabled)
- “Registration key is invalid” - Invalid or malformed key
- “This registration key has ran out of uses” - Depleted key
Initial Account Creation
The first account created on a Mercury instance uses a special endpoint with relaxed requirements.Admin username
Minimum 1 character (relaxed requirement)
Password confirmation
permissionLevel: 5 (administrator).
Source: Site/src/routes/(plain)/register/+page.server.ts:45-154
Logout
Invalidate all user sessions and redirect to login.Request
Valid session cookie
Current password for confirmation
Response
On success, invalidates all sessions for the user, deletes the session cookie, and redirects to/login.
All user sessions are invalidated in the database
Errors
“Incorrect password” - Password verification failed
Site/src/routes/(main)/settings/+page.server.ts:88-105
Session Validation
Sessions are validated server-side on each request using thevalidateSessionToken function.
Token Validation Process
- Extract session token from cookie
- Query database for session and associated user
- Return session and user data if valid
- Return null values if invalid or expired
Session Structure
Session token (random identifier)
User object containing:
id: User record IDusername: UsernamepermissionLevel: Permission level (1-5)- Additional user properties
Authorization Levels
Theauthorise function enforces permission levels:
- Level 1: Standard user
- Level 4: Moderator
- Level 5: Administrator
/login. Requests with insufficient permissions return 403 Forbidden.
Source: Site/src/lib/server/auth.ts:11-68