@devopsplaybook.io/common-utils 1.3.0-beta.12.165a8d0 → 1.4.0-beta.13.4edad2b

package/AGENTS.md

@@ -20,6 +20,11 @@ src/
   PostgresDbUtils.ts        # PostgreSQL operations (pg.Pool, async/Promise)
   DbUtils.ts                # Unified facade dispatching to Sql or Postgres
   DbUtilsNoTelemetry.ts     # Same DB ops without OTel span overhead
+  User.ts / UserSession.ts  # User model, roles and application-defined scopes
+  Auth.ts                   # JWT auth (key init, guards, session decode)
+  UserPassword.ts           # bcrypt password hashing/verification
+  UsersData.ts              # Users table CRUD (SQLite/Postgres)
+  UsersRoutes.ts            # Standard fastify user management routes
   SystemCommand.ts          # Promise wrapper around child_process.exec
   Timeout.ts                # Promise wrapper around setTimeout
   *.spec.ts                 # Co-located test files
@@ -41,6 +46,7 @@ src/
 - **Tests**: Jest with `ts-jest`. Spec files live next to source (`*.spec.ts`). Run with `npm run test`. The `tsconfig.spec.json` includes jest types.
 - **No default exports**: All modules use named exports only.
 - **OTel dependency injection**: Every DB module exposes a `*SetOTel(tracer, logger)` function that must be called before `*Init()`. OTel instances are stored as module-level singletons.
+- **Auth modules**: `AuthSetOTel(tracer)` and `UsersDataSetOTel(tracer)` must be called before `AuthInit`. Application scopes are registered through `AuthInit(context, config, allScopes)`; `UsersRoutes` relies on `req.tracerSpanApi` set by the `otel-utils-fastify` hooks.
 - **ModuleLogger pattern**: `StandardLogger` only exposes `createModuleLogger(name)`. DB modules call `logger.createModuleLogger("ModuleName")` internally. Never call `.info()` or `.error()` directly on a `StandardLogger`.
 - **SQLite-first SQL**: Write SQL with `?` placeholders. The `DbUtils` facade and `DbUtilsNoTelemetry` module auto-convert to `$1, $2, ...` for Postgres via `convertToPostgresPlaceholders()`.
 - **Migration convention**: SQL files named `init-NNNN.sql`. `init-0000.sql` must create the `metadata` table. Subsequent files are applied in lexicographic order; applied versions are tracked in `metadata` for idempotency.
@@ -65,6 +71,9 @@ All three commands must pass before committing. The CI pipeline (`reusable-npm-m
 | `pg`                            | PostgreSQL client with connection pooling                                                  |
 | `uuid`                          | v14+ (ESM -- requires `jest.mock("uuid")` in tests)                                        |
 | `fs-extra`                      | Async/sync file operations, `readJson`/`ensureDir`                                         |
+| `bcrypt`                        | Password hashing (users module)                                                            |
+| `jsonwebtoken`                  | JWT signing/verification (auth module)                                                     |
+| `fastify`                       | HTTP framework types used by `UsersRoutes`                                                 |
 
 ## Known Gotchas
 

package/README.md

@@ -34,6 +34,9 @@ npm install @devopsplaybook.io/common-utils
 | `fs-extra`                      | File system helpers                                 |
 | `uuid`                          | UUID generation for JWT keys                        |
 | `axios`                         | HTTP client for the notifications integration        |
+| `bcrypt`                        | Password hashing for the users module               |
+| `jsonwebtoken`                  | JWT signing/verification for the auth module        |
+| `fastify`                       | HTTP framework types for the users routes           |
 
 ### Modules
 
@@ -333,6 +336,47 @@ await client.send({
 
 ---
 
+#### `Auth`, `User`, `UserSession`, `UserPassword`, `UsersData`, `UsersRoutes` -- Authentication and User Management
+
+Standard JWT-based authentication and user management shared across all server projects: JWT key persistence in the `metadata` table, request authentication helpers, bcrypt password hashing, users CRUD, and ready-to-register fastify routes (login, user CRUD, password change).
+
+```ts
+import {
+  AuthSetOTel,
+  AuthInit,
+  UsersDataSetOTel,
+  UsersRoutes,
+} from "@devopsplaybook.io/common-utils";
+
+// At startup, after DbUtilsInit:
+AuthSetOTel(otel.OTelTracer());
+UsersDataSetOTel(otel.OTelTracer());
+await AuthInit(span, config, ["traces", "metrics", "logs"]); // app scopes
+
+// Register the standard user routes:
+fastify.register(new UsersRoutes().getRoutes, { prefix: "/api/users" });
+```
+
+| Export                       | Description                                                            |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `AuthSetOTel`                | Injects the OTel tracer used by the auth module (before `AuthInit`)    |
+| `AuthInit`                   | Registers app scopes, loads or generates the JWT key from `metadata`   |
+| `AuthGenerateJWT`            | Signs a JWT for a user (admins get all scopes)                         |
+| `AuthMustBeAuthenticated`    | 403 guard: any valid JWT                                               |
+| `AuthMustBeAdmin`            | 403 guard: `role === "admin"`                                          |
+| `AuthHasScope`               | 403 guard: admin or JWT containing the requested scope                 |
+| `AuthGetUserSession`         | Returns the `UserSession` decoded from the request JWT                 |
+| `User`, `UserRole`, `UserScope` | User model; scopes are application-defined strings                  |
+| `UserSession`                | Decoded session: `isAuthenticated`, `userId`, `userName`, `role`, `scopes` |
+| `UserPasswordSetPassword` / `UserPasswordCheckPassword` | bcrypt hashing and verification             |
+| `UsersDataSetOTel`           | Injects the OTel tracer used by the users data module                  |
+| `UsersData*`                 | Users table CRUD (`Get`, `GetByName`, `List`, `Add`, `UpdateUser`, `UpdatePassword`, `Delete`) |
+| `UsersRoutes`                | Fastify routes: `GET /status/initialization`, `POST /session`, user CRUD, `PUT /password` |
+
+**Requirements**: a `users` table (columns `id`, `name`, `passwordEncrypted`, `role`, `scopes`) and the standard `metadata` table created by `init-0000.sql`. SQL is written SQLite-first; the `DbUtils` facade converts placeholders for Postgres.
+
+---
+
 #### `SystemCommand` -- Shell Command Execution
 
 ```ts

package/dist/index.d.ts

@@ -7,3 +7,9 @@ export * from "./src/PostgresDbUtils";
 export * from "./src/Notifications";
 export * from "./src/SystemCommand";
 export * from "./src/Timeout";
+export * from "./src/User";
+export * from "./src/UserSession";
+export * from "./src/Auth";
+export * from "./src/UserPassword";
+export * from "./src/UsersData";
+export * from "./src/UsersRoutes";

package/dist/index.js

@@ -23,3 +23,9 @@ __exportStar(require("./src/PostgresDbUtils"), exports);
 __exportStar(require("./src/Notifications"), exports);
 __exportStar(require("./src/SystemCommand"), exports);
 __exportStar(require("./src/Timeout"), exports);
+__exportStar(require("./src/User"), exports);
+__exportStar(require("./src/UserSession"), exports);
+__exportStar(require("./src/Auth"), exports);
+__exportStar(require("./src/UserPassword"), exports);
+__exportStar(require("./src/UsersData"), exports);
+__exportStar(require("./src/UsersRoutes"), exports);

package/dist/src/Auth.d.ts

@@ -0,0 +1,34 @@
+import { StandardTracer } from "@devopsplaybook.io/otel-utils";
+import { Span } from "@opentelemetry/sdk-trace-base";
+import { User, UserScope } from "./User";
+import { UserSession } from "./UserSession";
+/**
+ * Configuration subset required by the auth module.
+ */
+export interface AuthConfig {
+    JWT_KEY: string;
+    JWT_VALIDITY_DURATION: number;
+    DATABASE_TYPE: "sqlite" | "postgres";
+}
+/**
+ * Injects the OTel tracer instance used by the auth module.
+ * Must be called once at startup, before {@link AuthInit}.
+ */
+export declare function AuthSetOTel(tracerIn: StandardTracer): void;
+/**
+ * Initialise the auth module.
+ *
+ * Registers the full scope set of the host application and loads the JWT
+ * signing key from the `metadata` table. When no key is stored yet, a fresh
+ * one is generated and persisted.
+ *
+ * @param context    Parent OTel span.
+ * @param configIn   Server configuration (JWT_KEY is updated in place).
+ * @param allScopes  All scopes supported by the host application.
+ */
+export declare function AuthInit(context: Span, configIn: AuthConfig, allScopes?: UserScope[]): Promise<void>;
+export declare function AuthGenerateJWT(user: User): Promise<string>;
+export declare function AuthMustBeAuthenticated(req: any, res: any): Promise<void>;
+export declare function AuthMustBeAdmin(req: any, res: any): Promise<void>;
+export declare function AuthHasScope(req: any, res: any, scope: UserScope): Promise<void>;
+export declare function AuthGetUserSession(req: any): Promise<UserSession>;

package/dist/src/Auth.js

@@ -0,0 +1,172 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuthSetOTel = AuthSetOTel;
+exports.AuthInit = AuthInit;
+exports.AuthGenerateJWT = AuthGenerateJWT;
+exports.AuthMustBeAuthenticated = AuthMustBeAuthenticated;
+exports.AuthMustBeAdmin = AuthMustBeAdmin;
+exports.AuthHasScope = AuthHasScope;
+exports.AuthGetUserSession = AuthGetUserSession;
+const jwt = __importStar(require("jsonwebtoken"));
+const uuid_1 = require("uuid");
+const DbUtils_1 = require("./DbUtils");
+const User_1 = require("./User");
+let tracer;
+let config;
+/**
+ * Injects the OTel tracer instance used by the auth module.
+ * Must be called once at startup, before {@link AuthInit}.
+ */
+function AuthSetOTel(tracerIn) {
+    tracer = tracerIn;
+}
+/**
+ * Initialise the auth module.
+ *
+ * Registers the full scope set of the host application and loads the JWT
+ * signing key from the `metadata` table. When no key is stored yet, a fresh
+ * one is generated and persisted.
+ *
+ * @param context    Parent OTel span.
+ * @param configIn   Server configuration (JWT_KEY is updated in place).
+ * @param allScopes  All scopes supported by the host application.
+ */
+async function AuthInit(context, configIn, allScopes = []) {
+    config = configIn;
+    User_1.User.ALL_SCOPES = [...allScopes];
+    const span = tracer.startSpan("AuthInit", context);
+    const authKeyRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_AUTH_TOKEN);
+    if (authKeyRaw.length == 0) {
+        configIn.JWT_KEY = (0, uuid_1.v4)();
+        await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.INSERT_AUTH_TOKEN, [
+            configIn.JWT_KEY,
+            new Date().toISOString(),
+        ]);
+    }
+    else {
+        configIn.JWT_KEY = authKeyRaw[0].value;
+    }
+    span.end();
+}
+async function AuthGenerateJWT(user) {
+    return jwt.sign({
+        exp: Math.floor(Date.now() / 1000) + config.JWT_VALIDITY_DURATION,
+        userId: user.id,
+        userName: user.name,
+        role: user.role,
+        scopes: user.role === "admin" ? User_1.User.ALL_SCOPES : user.scopes,
+    }, config.JWT_KEY);
+}
+/**
+ * Decode JWT from request, caching result on req._jwtPayload to avoid
+ * redundant verification when multiple auth functions are called per request.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function jwtDecodeCached(req) {
+    if (req._jwtPayload) {
+        return req._jwtPayload;
+    }
+    if (!req.headers.authorization) {
+        return null;
+    }
+    try {
+        const info = jwt.verify(req.headers.authorization.split(" ")[1], config.JWT_KEY);
+        req._jwtPayload = info;
+        return info;
+    }
+    catch {
+        return null;
+    }
+}
+async function AuthMustBeAuthenticated(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+req, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+res) {
+    if (!jwtDecodeCached(req)) {
+        res.status(403).send({ error: "Access Denied" });
+        throw new Error("Access Denied");
+    }
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function AuthMustBeAdmin(req, res) {
+    const info = jwtDecodeCached(req);
+    if ((info === null || info === void 0 ? void 0 : info.role) === "admin") {
+        return;
+    }
+    res.status(403).send({ error: "Access Denied" });
+    throw new Error("Access Denied");
+}
+async function AuthHasScope(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+req, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+res, scope) {
+    const info = jwtDecodeCached(req);
+    if (!info) {
+        res.status(403).send({ error: "Access Denied" });
+        throw new Error("Access Denied");
+    }
+    if (info.role === "admin") {
+        return;
+    }
+    const scopes = info.scopes || [];
+    if (scopes.includes(scope)) {
+        return;
+    }
+    res.status(403).send({ error: "Access Denied" });
+    throw new Error("Access Denied");
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function AuthGetUserSession(req) {
+    const userSession = { isAuthenticated: false };
+    const info = jwtDecodeCached(req);
+    if (info) {
+        userSession.userId = info.userId;
+        userSession.userName = info.userName;
+        userSession.role = info.role;
+        userSession.scopes = info.scopes;
+        userSession.isAuthenticated = true;
+    }
+    return userSession;
+}
+// SQL
+// Written SQLite-first with quoted identifiers (valid for both backends);
+// the DbUtils facade converts `?` placeholders for Postgres.
+const SQL_QUERIES = {
+    GET_AUTH_TOKEN: "SELECT value FROM metadata WHERE \"type\" = 'auth_token' LIMIT 1",
+    INSERT_AUTH_TOKEN: 'INSERT INTO metadata ("type", "value", "dateCreated") VALUES (\'auth_token\', ?, ?)',
+};

package/dist/src/User.d.ts

@@ -0,0 +1,25 @@
+/**
+ * User role. `admin` bypasses scope checks; `user` is restricted
+ * to its granted scopes.
+ */
+export type UserRole = "admin" | "user";
+/**
+ * Scope identifier restricting what a non-admin user can access.
+ * Each application defines its own scope set (e.g. `"traces"`, `"metrics"`)
+ * and registers it through `AuthInit`.
+ */
+export type UserScope = string;
+export declare class User {
+    static DEFAULT_SCOPES: UserScope[];
+    /** Full scope set of the host application, registered via `AuthInit`. */
+    static ALL_SCOPES: UserScope[];
+    static fromJson(json: any): User | null;
+    id: string;
+    name: string;
+    passwordEncrypted: string;
+    role: UserRole;
+    scopes: UserScope[];
+    constructor();
+    toJson(): any;
+    toTransportJson(): any;
+}

package/dist/src/User.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.User = void 0;
+const uuid_1 = require("uuid");
+class User {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static fromJson(json) {
+        if (!json) {
+            return null;
+        }
+        const user = new User();
+        if (json.id) {
+            user.id = json.id;
+        }
+        user.id = json.id;
+        user.name = json.name;
+        user.passwordEncrypted = json.passwordEncrypted;
+        user.role = json.role || "user";
+        if (json.scopes) {
+            try {
+                user.scopes =
+                    typeof json.scopes === "string"
+                        ? JSON.parse(json.scopes)
+                        : json.scopes;
+            }
+            catch {
+                user.scopes = [...User.DEFAULT_SCOPES];
+            }
+        }
+        return user;
+    }
+    constructor() {
+        this.role = "user";
+        this.scopes = [...User.DEFAULT_SCOPES];
+        this.id = (0, uuid_1.v4)();
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toJson() {
+        return {
+            id: this.id,
+            name: this.name,
+            passwordEncrypted: this.passwordEncrypted,
+            role: this.role,
+            scopes: this.scopes,
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toTransportJson() {
+        return {
+            id: this.id,
+            name: this.name,
+            role: this.role,
+            scopes: this.scopes,
+        };
+    }
+}
+exports.User = User;
+//
+User.DEFAULT_SCOPES = [];
+/** Full scope set of the host application, registered via `AuthInit`. */
+User.ALL_SCOPES = [];

package/dist/src/UserPassword.d.ts

@@ -0,0 +1,4 @@
+import { Span } from "@opentelemetry/sdk-trace-base";
+import { User } from "./User";
+export declare function UserPasswordSetPassword(context: Span | undefined, user: User, password: string): Promise<void>;
+export declare function UserPasswordCheckPassword(context: Span | undefined, user: User, password: string): Promise<boolean>;

package/dist/src/UserPassword.js

@@ -0,0 +1,45 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserPasswordSetPassword = UserPasswordSetPassword;
+exports.UserPasswordCheckPassword = UserPasswordCheckPassword;
+const bcrypt = __importStar(require("bcrypt"));
+async function UserPasswordSetPassword(context, user, password) {
+    const salt = await bcrypt.genSalt(10);
+    user.passwordEncrypted = await bcrypt.hash(password, salt);
+}
+async function UserPasswordCheckPassword(context, user, password) {
+    return await bcrypt.compare(password, user.passwordEncrypted);
+}

package/dist/src/UserSession.d.ts

@@ -0,0 +1,8 @@
+import { UserRole, UserScope } from "./User";
+export interface UserSession {
+    isAuthenticated: boolean;
+    userId?: string;
+    userName?: string;
+    role?: UserRole;
+    scopes?: UserScope[];
+}

package/dist/src/UserSession.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/UsersData.d.ts

@@ -0,0 +1,15 @@
+import { StandardTracer } from "@devopsplaybook.io/otel-utils";
+import { Span } from "@opentelemetry/sdk-trace-base";
+import { User } from "./User";
+/**
+ * Injects the OTel tracer instance used by the users data module.
+ * Must be called once at startup, before any `UsersData*` function.
+ */
+export declare function UsersDataSetOTel(tracerIn: StandardTracer): void;
+export declare function UsersDataGet(context: Span | undefined, id: string): Promise<User | null>;
+export declare function UsersDataGetByName(context: Span | undefined, name: string): Promise<User | null>;
+export declare function UsersDataList(context: Span | undefined): Promise<User[]>;
+export declare function UsersDataAdd(context: Span | undefined, user: User): Promise<void>;
+export declare function UsersDataUpdatePassword(context: Span | undefined, user: User): Promise<void>;
+export declare function UsersDataUpdateUser(context: Span | undefined, user: User): Promise<void>;
+export declare function UsersDataDelete(context: Span | undefined, id: string): Promise<void>;

package/dist/src/UsersData.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsersDataSetOTel = UsersDataSetOTel;
+exports.UsersDataGet = UsersDataGet;
+exports.UsersDataGetByName = UsersDataGetByName;
+exports.UsersDataList = UsersDataList;
+exports.UsersDataAdd = UsersDataAdd;
+exports.UsersDataUpdatePassword = UsersDataUpdatePassword;
+exports.UsersDataUpdateUser = UsersDataUpdateUser;
+exports.UsersDataDelete = UsersDataDelete;
+const DbUtils_1 = require("./DbUtils");
+const User_1 = require("./User");
+let tracer;
+/**
+ * Injects the OTel tracer instance used by the users data module.
+ * Must be called once at startup, before any `UsersData*` function.
+ */
+function UsersDataSetOTel(tracerIn) {
+    tracer = tracerIn;
+}
+async function UsersDataGet(context, id) {
+    const span = tracer.startSpan("UsersDataGet", context);
+    const usersRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_USER_BY_ID, [
+        id,
+    ]);
+    let user = null;
+    if (usersRaw.length > 0) {
+        user = fromRaw(usersRaw[0]);
+    }
+    span.end();
+    return user;
+}
+async function UsersDataGetByName(context, name) {
+    const span = tracer.startSpan("UsersDataGetByName", context);
+    const usersRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_USER_BY_NAME, [
+        name,
+    ]);
+    let user = null;
+    if (usersRaw.length > 0) {
+        user = fromRaw(usersRaw[0]);
+    }
+    span.end();
+    return user;
+}
+async function UsersDataList(context) {
+    const span = tracer.startSpan("UsersDataList", context);
+    const usersRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.LIST_USERS);
+    const users = [];
+    for (const userRaw of usersRaw) {
+        users.push(fromRaw(userRaw));
+    }
+    span.end();
+    return users;
+}
+async function UsersDataAdd(context, user) {
+    const span = tracer.startSpan("UsersDataAdd", context);
+    await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.INSERT_USER, [
+        user.id,
+        user.name,
+        user.passwordEncrypted,
+        user.role,
+        JSON.stringify(user.scopes),
+    ]);
+    span.end();
+}
+async function UsersDataUpdatePassword(context, user) {
+    const span = tracer.startSpan("UsersDataUpdatePassword", context);
+    await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.UPDATE_PASSWORD, [
+        user.passwordEncrypted,
+        user.id,
+    ]);
+    span.end();
+}
+async function UsersDataUpdateUser(context, user) {
+    const span = tracer.startSpan("UsersDataUpdateUser", context);
+    await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.UPDATE_USER, [
+        user.role,
+        JSON.stringify(user.scopes),
+        user.id,
+    ]);
+    span.end();
+}
+async function UsersDataDelete(context, id) {
+    const span = tracer.startSpan("UsersDataDelete", context);
+    await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.DELETE_USER, [id]);
+    span.end();
+}
+// Private Functions
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function fromRaw(userRaw) {
+    const user = new User_1.User();
+    user.id = userRaw.id;
+    user.name = userRaw.name;
+    user.passwordEncrypted = userRaw.passwordEncrypted;
+    user.role = userRaw.role || "user";
+    if (userRaw.scopes) {
+        try {
+            user.scopes = JSON.parse(userRaw.scopes);
+        }
+        catch {
+            user.scopes = [...User_1.User.DEFAULT_SCOPES];
+        }
+    }
+    return user;
+}
+// SQL
+// Written SQLite-first with quoted identifiers (valid for both backends);
+// the DbUtils facade converts `?` placeholders for Postgres.
+const SQL_QUERIES = {
+    GET_USER_BY_ID: 'SELECT * FROM users WHERE "id" = ?',
+    GET_USER_BY_NAME: 'SELECT * FROM users WHERE "name" = ?',
+    LIST_USERS: "SELECT * FROM users",
+    INSERT_USER: 'INSERT INTO users ("id", "name", "passwordEncrypted", "role", "scopes") VALUES (?, ?, ?, ?, ?)',
+    UPDATE_USER: 'UPDATE users SET "role" = ?, "scopes" = ? WHERE "id" = ?',
+    UPDATE_PASSWORD: 'UPDATE users SET "passwordEncrypted" = ? WHERE "id" = ?',
+    DELETE_USER: 'DELETE FROM users WHERE "id" = ?',
+};

package/dist/src/UsersRoutes.d.ts

@@ -0,0 +1,13 @@
+import { FastifyInstance } from "fastify";
+/**
+ * Standard user management routes shared across applications:
+ * initialization status, login (session), user CRUD and password changes.
+ *
+ * Register on a fastify instance:
+ * ```ts
+ * fastify.register(new UsersRoutes().getRoutes, { prefix: "/api/users" });
+ * ```
+ */
+export declare class UsersRoutes {
+    getRoutes(fastify: FastifyInstance): Promise<void>;
+}