For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.

Authentication

Login (email + password)

1. User submits email and password on /login.html.
2. Backend checks credentials (e.g. bcrypt or your chosen hash) and loads the user from the database.
3. If valid, the server creates a session object (e.g. { id, role, ... }) and sets a cookie admin_session with that payload (often JSON stringified and optionally signed/encoded).
4. Redirect: admin → /admin.html (or a default admin page); non-admin → /client-dashboard.html.

Registration

• Register link on the login page sends email, username, password to /api/auth/register.
• User is created in the database with a default role (e.g. client). No auto-login is required by this doc; implement if desired.
• An admin can then change the user’s role and permissions in the panel.

Discord OAuth (optional)

1. Configure a Discord Application in the Discord Developer Portal. Add a redirect URI: https://your-domain/api/auth/callback (must match APP_BASE_URL).
2. Set in env (or Admin Settings): Discord Client ID, Client Secret, Redirect URI.
3. User clicks “Login with Discord” on the login page → redirect to Discord → after approval, Discord redirects to /api/auth/callback with a code.
4. Backend exchanges the code for an access token, fetches Discord user, finds or creates a user in your DB (by discordId), creates a session, sets cookie, redirects as in normal login.

Password reset

1. User requests reset (e.g. “Forgot password” on login page). Request goes to /api/auth/request-password-reset with email.
2. Backend finds the user, creates a PasswordReset record (token hash, expiry), and sends an email with a link: /reset-password.html?token=.... If SMTP is not configured, the link is printed in the server console (dev only).
3. User opens the link and submits a new password to /api/auth/reset-password with the token and new password.
4. Backend validates the token, updates the user’s password, invalidates the token, then redirects to login or auto-logs in (implementation-dependent).

Admin-triggered reset: Admins can request a password reset for another user (e.g. from a user management screen); same flow, but initiated by admin.

Logout

• GET (or POST) /api/auth/logout clears the session cookie and redirects to /login.html.

Protected routes

• HTML pages under pages/ that are “protected” (e.g. admin.html, commission.html, list.html, todo.html, hub.html, log.html, settings.html, client-dashboard.html, customer.html, commission-admin.html) are served only after the middleware checks the session.
• If there is no valid session → redirect to /login.html.
• If there is a session, access to each page is then restricted by role and permissions (see Permissions & Roles). For example, commission-admin.html is only allowed for admin or users with Commissions permission; commission.html is allowed if the user has at least one assigned commission or Commissions permission.

Session cookie

• Name: admin_session.
• Contains the minimal data needed to identify the user (e.g. id, role). The server loads full user (and permissions) from the database when needed.
• Ensure cookie is set with SameSite and Secure in production (HTTPS).