docu

Author: orangecoding

lib/services/storage/userStorage.js

@@ -3,6 +3,16 @@ import * as hasher from '../security/hash.js';
 import { nanoid } from 'nanoid';
 import SqliteConnection from './SqliteConnection.js';
 
+/**
+ * Get all users.
+ *
+ * Notes:
+ * - Password hashes are omitted by default to avoid leaking them to callers that don’t need them.
+ * - numberOfJobs is computed via a subquery for each user.
+ *
+ * @param {boolean} withPassword - If true, include the hashed password in the returned objects; otherwise set password to null.
+ * @returns {User[]} Array of users ordered by username.
+ */
 export const getUsers = (withPassword) => {
   const rows = SqliteConnection.query(
     `SELECT u.id, u.username, u.password, u.last_login AS lastLogin, u.is_admin AS isAdmin,
@@ -17,6 +27,12 @@ export const getUsers = (withPassword) => {
   }));
 };
 
+/**
+ * Get a single user by id.
+ *
+ * @param {string} id - User id (primary key).
+ * @returns {User|null} The user when found; otherwise null. The password field is included but callers should not expose it.
+ */
 export const getUser = (id) => {
   const rows = SqliteConnection.query(
     `SELECT u.id, u.username, u.password, u.last_login AS lastLogin, u.is_admin AS isAdmin,
@@ -31,6 +47,21 @@ export const getUser = (id) => {
   return { ...u, isAdmin: !!u.isAdmin };
 };
 
+/**
+ * Insert a new user or update an existing one.
+ *
+ * Behavior:
+ * - When userId is provided and exists: updates username and isAdmin. Password is only updated when a non-empty password is provided.
+ * - When userId is missing or does not exist: inserts a new user with a freshly generated id. last_login is initialized to null.
+ * - Passwords are hashed using the same hashing function used for login comparison.
+ *
+ * @param {Object} params
+ * @param {string} params.username - Username (must be unique in DB).
+ * @param {string} [params.password] - Plain text password to set; if omitted on update, existing hash is preserved.
+ * @param {string} [params.userId] - Existing user id to update; if missing, a new id is generated.
+ * @param {boolean} params.isAdmin - Whether the user should have admin privileges.
+ * @returns {void}
+ */
 export const upsertUser = ({ username, password, userId, isAdmin }) => {
   const id = userId || nanoid();
   // Check if user exists
@@ -64,18 +95,39 @@ export const upsertUser = ({ username, password, userId, isAdmin }) => {
   }
 };
 
+/**
+ * Update the last_login timestamp to now for the given user.
+ *
+ * @param {{userId: string}} params - Parameters.
+ * @param {string} params.userId - The user's id.
+ * @returns {void}
+ */
 export const setLastLoginToNow = ({ userId }) => {
   SqliteConnection.execute(`UPDATE users SET last_login = @now WHERE id = @id`, { id: userId, now: Date.now() });
 };
 
+/**
+ * Remove a user by id.
+ *
+ * Notes:
+ * - In the SQLite schema, jobs reference users with ON DELETE CASCADE, so jobs (and their listings via jobs) are removed automatically.
+ *
+ * @param {string} userId - The id of the user to remove.
+ * @returns {void}
+ */
 export const removeUser = (userId) => {
   SqliteConnection.execute(`DELETE FROM users WHERE id = @id`, { id: userId });
 };
 
 /**
  * Ensure the demo user matches the demo mode setting.
+ *
+ * Behavior:
  * - When config.demoMode is false: remove the demo user (and its cascading data via FKs).
  * - When config.demoMode is true: ensure a 'demo' user exists with password 'demo' and admin rights.
+ *
+ * Security: The demo user's password is set to a known value ('demo') and should only be enabled in demoMode.
+ * @returns {void}
  */
 export const ensureDemoUserExists = () => {
   if (!config.demoMode) {
@@ -96,9 +148,13 @@ export const ensureDemoUserExists = () => {
 
 /**
  * Ensure there is at least one administrator in the system.
+ *
  * Behavior:
  * - If there are no users at all, create default 'admin' user with password 'admin'.
  * - If users exist but none is admin, promote the first existing user to admin.
+ *
+ * Security: On a fresh instance, a default admin/admin is created; change this password immediately.
+ * @returns {void}
  */
 export const ensureAdminUserExists = () => {
   const anyUser = SqliteConnection.query(`SELECT id FROM users LIMIT 1`).length > 0;