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

package/dist/src/UsersRoutes.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsersRoutes = void 0;
+const Auth_1 = require("./Auth");
+const User_1 = require("./User");
+const UserPassword_1 = require("./UserPassword");
+const UsersData_1 = require("./UsersData");
+/**
+ * Retrieves the OTel span attached to the request by the
+ * `@devopsplaybook.io/otel-utils-fastify` hooks.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function requestSpan(req) {
+    return req === null || req === void 0 ? void 0 : req.tracerSpanApi;
+}
+/**
+ * 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" });
+ * ```
+ */
+class UsersRoutes {
+    //
+    async getRoutes(fastify) {
+        //
+        fastify.get("/status/initialization", async (req, res) => {
+            if ((await (0, UsersData_1.UsersDataList)(requestSpan(req))).length === 0) {
+                res.status(201).send({ initialized: false });
+            }
+            else {
+                res.status(201).send({ initialized: true });
+            }
+        });
+        fastify.post("/session", async (req, res) => {
+            let user;
+            // From token
+            const userSession = await (0, Auth_1.AuthGetUserSession)(req);
+            if (userSession.isAuthenticated) {
+                // isAuthenticated implies userId is set
+                user = await (0, UsersData_1.UsersDataGet)(requestSpan(req), userSession.userId);
+                if (!user) {
+                    return res.status(403).send({ error: "Authentication Failed" });
+                }
+                return res.status(201).send({
+                    success: true,
+                    token: await (0, Auth_1.AuthGenerateJWT)(user),
+                    user: user.toTransportJson(),
+                });
+            }
+            // From User/Pass
+            if (!req.body.name) {
+                return res.status(400).send({ error: "Missing: Name" });
+            }
+            if (!req.body.password) {
+                return res.status(400).send({ error: "Missing: Password" });
+            }
+            user = await (0, UsersData_1.UsersDataGetByName)(requestSpan(req), req.body.name);
+            if (!user) {
+                return res.status(403).send({ error: "Authentication Failed" });
+            }
+            else if (await (0, UserPassword_1.UserPasswordCheckPassword)(requestSpan(req), user, req.body.password)) {
+                return res.status(201).send({
+                    success: true,
+                    token: await (0, Auth_1.AuthGenerateJWT)(user),
+                    user: user.toTransportJson(),
+                });
+            }
+            else {
+                return res.status(403).send({ error: "Authentication Failed" });
+            }
+        });
+        // ==================== LIST USERS (Admin only) ====================
+        fastify.get("/", async (req, res) => {
+            try {
+                await (0, Auth_1.AuthMustBeAdmin)(req, res);
+            }
+            catch {
+                return;
+            }
+            const users = await (0, UsersData_1.UsersDataList)(requestSpan(req));
+            return res.status(200).send(users.map((u) => u.toTransportJson()));
+        });
+        fastify.post("/", async (req, res) => {
+            const context = requestSpan(req);
+            let isInitialized = true;
+            if ((await (0, UsersData_1.UsersDataList)(context)).length === 0) {
+                isInitialized = false;
+            }
+            // If initialized, only admin can create users
+            if (isInitialized) {
+                try {
+                    await (0, Auth_1.AuthMustBeAdmin)(req, res);
+                }
+                catch {
+                    return;
+                }
+            }
+            if (!req.body.name) {
+                return res.status(400).send({ error: "Missing: Name" });
+            }
+            if (!req.body.password) {
+                return res.status(400).send({ error: "Missing: Password" });
+            }
+            if (await (0, UsersData_1.UsersDataGetByName)(context, req.body.name)) {
+                return res.status(400).send({ error: "Username Already Exists" });
+            }
+            const newUser = new User_1.User();
+            newUser.name = req.body.name;
+            // First user is always admin
+            if (isInitialized) {
+                newUser.role = req.body.role === "admin" ? "admin" : "user";
+                if (req.body.scopes && Array.isArray(req.body.scopes)) {
+                    newUser.scopes = req.body.scopes.filter((s) => User_1.User.ALL_SCOPES.includes(s));
+                }
+            }
+            else {
+                newUser.role = "admin";
+                newUser.scopes = [...User_1.User.ALL_SCOPES];
+            }
+            await (0, UserPassword_1.UserPasswordSetPassword)(context, newUser, req.body.password);
+            await (0, UsersData_1.UsersDataAdd)(context, newUser);
+            res.status(201).send({ user: newUser.toTransportJson() });
+        });
+        fastify.put("/password", async (req, res) => {
+            const context = requestSpan(req);
+            const userSession = await (0, Auth_1.AuthGetUserSession)(req);
+            if (!userSession.isAuthenticated) {
+                return res.status(403).send({ error: "Access Denied" });
+            }
+            // isAuthenticated implies userId is set
+            const user = await (0, UsersData_1.UsersDataGet)(context, userSession.userId);
+            if (!user) {
+                return res.status(403).send({ error: "Access Denied" });
+            }
+            if (!req.body.password) {
+                return res.status(400).send({ error: "Missing: Password" });
+            }
+            if (!(await (0, UserPassword_1.UserPasswordCheckPassword)(context, user, req.body.passwordOld))) {
+                return res.status(403).send({ error: "Old Password Wrong" });
+            }
+            await (0, UserPassword_1.UserPasswordSetPassword)(context, user, req.body.password);
+            await (0, UsersData_1.UsersDataUpdatePassword)(context, user);
+            res.status(201).send({});
+        });
+        fastify.put("/:id", async (req, res) => {
+            const context = requestSpan(req);
+            try {
+                await (0, Auth_1.AuthMustBeAdmin)(req, res);
+            }
+            catch {
+                return;
+            }
+            const user = await (0, UsersData_1.UsersDataGet)(context, req.params.id);
+            if (!user) {
+                return res.status(404).send({ error: "User Not Found" });
+            }
+            if (req.body.role) {
+                user.role = req.body.role === "admin" ? "admin" : "user";
+            }
+            if (req.body.scopes && Array.isArray(req.body.scopes)) {
+                user.scopes = req.body.scopes.filter((s) => User_1.User.ALL_SCOPES.includes(s));
+            }
+            await (0, UsersData_1.UsersDataUpdateUser)(context, user);
+            // If password change requested
+            if (req.body.password) {
+                await (0, UserPassword_1.UserPasswordSetPassword)(context, user, req.body.password);
+                await (0, UsersData_1.UsersDataUpdatePassword)(context, user);
+            }
+            res.status(201).send({ user: user.toTransportJson() });
+        });
+        fastify.delete("/:id", async (req, res) => {
+            const context = requestSpan(req);
+            try {
+                await (0, Auth_1.AuthMustBeAdmin)(req, res);
+            }
+            catch {
+                return;
+            }
+            const userSession = await (0, Auth_1.AuthGetUserSession)(req);
+            // Cannot delete yourself
+            if (userSession.userId === req.params.id) {
+                return res.status(400).send({ error: "Cannot Delete Yourself" });
+            }
+            const user = await (0, UsersData_1.UsersDataGet)(context, req.params.id);
+            if (!user) {
+                return res.status(404).send({ error: "User Not Found" });
+            }
+            // Check that at least 1 admin remains
+            if (user.role === "admin") {
+                const admins = (await (0, UsersData_1.UsersDataList)(context)).filter((u) => u.role === "admin");
+                if (admins.length <= 1) {
+                    return res
+                        .status(400)
+                        .send({ error: "At least 1 admin must be defined" });
+                }
+            }
+            await (0, UsersData_1.UsersDataDelete)(context, req.params.id);
+            res.status(201).send({});
+        });
+    }
+}
+exports.UsersRoutes = UsersRoutes;

package/index.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/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@devopsplaybook.io/common-utils",
-  "version": "1.3.0-beta.12.165a8d0",
-  "description": "Shared utility modules for devopsplaybook.io projects (DB, Config, OTel context, notifications, system helpers)",
+  "version": "1.4.0-beta.13.4edad2b",
+  "description": "Shared utility modules for devopsplaybook.io projects (DB, Config, OTel context, auth/users, notifications, system helpers)",
   "keywords": [
     "Open Telemetry",
     "OTel",
     "SQLite",
     "Postgres",
     "Config",
+    "Auth",
+    "JWT",
+    "Users",
     "Notifications",
     "Utilities"
   ],
@@ -26,16 +29,21 @@
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/sdk-trace-base": "^2.10.0",
     "axios": "^1.19.0",
+    "bcrypt": "^6.0.0",
     "better-sqlite3": "^13.0.3",
+    "fastify": "^5.12.1",
     "fs-extra": "^11.4.0",
+    "jsonwebtoken": "^9.0.3",
     "pg": "^8.23.0",
     "uuid": "^14.0.2"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@types/bcrypt": "^6.0.0",
     "@types/better-sqlite3": "^9.6.0",
     "@types/fs-extra": "^11.0.4",
     "@types/jest": "^30.0.0",
+    "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^26.2.0",
     "@types/pg": "^8.23.1",
     "@types/uuid": "^11.0.0",

package/src/Auth.ts

@@ -0,0 +1,165 @@
+import { StandardTracer } from "@devopsplaybook.io/otel-utils";
+import { Span } from "@opentelemetry/sdk-trace-base";
+import * as jwt from "jsonwebtoken";
+import { v4 as uuidv4 } from "uuid";
+import { DbUtilsQuerySQL } from "./DbUtils";
+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";
+}
+
+let tracer: StandardTracer;
+let config: AuthConfig;
+
+/**
+ * Injects the OTel tracer instance used by the auth module.
+ * Must be called once at startup, before {@link AuthInit}.
+ */
+export function AuthSetOTel(tracerIn: StandardTracer): void {
+  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.
+ */
+export async function AuthInit(
+  context: Span,
+  configIn: AuthConfig,
+  allScopes: UserScope[] = [],
+): Promise<void> {
+  config = configIn;
+  User.ALL_SCOPES = [...allScopes];
+  const span = tracer.startSpan("AuthInit", context);
+  const authKeyRaw = await DbUtilsQuerySQL(span, SQL_QUERIES.GET_AUTH_TOKEN);
+  if (authKeyRaw.length == 0) {
+    configIn.JWT_KEY = uuidv4();
+    await DbUtilsQuerySQL(span, SQL_QUERIES.INSERT_AUTH_TOKEN, [
+      configIn.JWT_KEY,
+      new Date().toISOString(),
+    ]);
+  } else {
+    configIn.JWT_KEY = authKeyRaw[0].value;
+  }
+  span.end();
+}
+
+export async function AuthGenerateJWT(user: User): Promise<string> {
+  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.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: any): any | null {
+  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;
+  }
+}
+
+export async function AuthMustBeAuthenticated(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  req: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  res: any,
+): Promise<void> {
+  if (!jwtDecodeCached(req)) {
+    res.status(403).send({ error: "Access Denied" });
+    throw new Error("Access Denied");
+  }
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function AuthMustBeAdmin(req: any, res: any): Promise<void> {
+  const info = jwtDecodeCached(req);
+  if (info?.role === "admin") {
+    return;
+  }
+  res.status(403).send({ error: "Access Denied" });
+  throw new Error("Access Denied");
+}
+
+export async function AuthHasScope(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  req: any,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  res: any,
+  scope: UserScope,
+): Promise<void> {
+  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: UserScope[] = 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
+export async function AuthGetUserSession(req: any): Promise<UserSession> {
+  const userSession: 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/src/User.ts

@@ -0,0 +1,78 @@
+import { v4 as uuidv4 } from "uuid";
+
+/**
+ * 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 class User {
+  //
+  public static DEFAULT_SCOPES: UserScope[] = [];
+  /** Full scope set of the host application, registered via `AuthInit`. */
+  public static ALL_SCOPES: UserScope[] = [];
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public static fromJson(json: any): User | null {
+    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;
+  }
+
+  public id: string;
+  public name!: string;
+  public passwordEncrypted!: string;
+  public role: UserRole = "user";
+  public scopes: UserScope[] = [...User.DEFAULT_SCOPES];
+
+  constructor() {
+    this.id = uuidv4();
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public toJson(): any {
+    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
+  public toTransportJson(): any {
+    return {
+      id: this.id,
+      name: this.name,
+      role: this.role,
+      scopes: this.scopes,
+    };
+  }
+}

package/src/UserPassword.spec.ts

@@ -0,0 +1,28 @@
+jest.mock("uuid", () => ({
+  v4: () => "mock-uuid-1234",
+}));
+
+import { User } from "./User";
+import {
+  UserPasswordCheckPassword,
+  UserPasswordSetPassword,
+} from "./UserPassword";
+
+test("Password should be successfully verified if it's the same", async () => {
+  const password = "testPassword1234";
+  const user = new User();
+  await UserPasswordSetPassword(null as never, user, password);
+  expect(
+    await UserPasswordCheckPassword(null as never, user, password),
+  ).toBeTruthy();
+});
+
+test("Password should be faile to be verified if it's not the same", async () => {
+  const password = "testPassword1234";
+  const passwordWrong = "testPassword12345";
+  const user = new User();
+  await UserPasswordSetPassword(null as never, user, password);
+  expect(
+    await UserPasswordCheckPassword(null as never, user, passwordWrong),
+  ).toBeFalsy();
+});

package/src/UserPassword.ts

@@ -0,0 +1,20 @@
+import { Span } from "@opentelemetry/sdk-trace-base";
+import * as bcrypt from "bcrypt";
+import { User } from "./User";
+
+export async function UserPasswordSetPassword(
+  context: Span | undefined,
+  user: User,
+  password: string,
+): Promise<void> {
+  const salt = await bcrypt.genSalt(10);
+  user.passwordEncrypted = await bcrypt.hash(password, salt);
+}
+
+export async function UserPasswordCheckPassword(
+  context: Span | undefined,
+  user: User,
+  password: string,
+): Promise<boolean> {
+  return await bcrypt.compare(password, user.passwordEncrypted);
+}

package/src/UserSession.ts

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