@devopsplaybook.io/common-utils 1.10.1-beta.23.b1906d7 → 1.11.0-beta.24.d8f9aef

package/src/users/Auth.ts

@@ -1,202 +0,0 @@
-import { createHash } from "crypto";
-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 { DbUtilsExecSQL, DbUtilsQuerySQL } from "../DbUtils";
-import { User, UserScope } from "./User";
-import { UserSession } from "./UserSession";
-import { UsersApiTokensDataGetByTokenHash } from "./UsersApiTokensData";
-import { UsersDataGet } from "./UsersData";
-
-/**
- * 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 DbUtilsExecSQL(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 credentials from request, caching result on req._jwtPayload to
- * avoid redundant resolution when multiple auth functions are called per
- * request.
- *
- * A `Bearer` credential is first verified as a JWT. When JWT verification
- * fails, the credential is resolved as a user API token: the value is
- * SHA-256 hashed and looked up in `users_api_tokens`; on match, a payload
- * mirroring the owning user's live role and scopes is built (valid until
- * the token is revoked).
- */
-async function jwtDecodeCached(req: any): Promise<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 {
-    const info = await resolveApiToken(req.headers.authorization);
-    if (info) {
-      req._jwtPayload = info;
-      return info;
-    }
-    return null;
-  }
-}
-
-/**
- * Resolve an API token bearer credential to a user-backed payload.
- * Permissions are read from the user record at resolution time, so
- * role/scope changes apply to existing tokens immediately.
- */
-async function resolveApiToken(authorizationHeader: string): Promise<any | null> {
-  const token = authorizationHeader.split(" ")[1];
-  if (!token) {
-    return null;
-  }
-  const span = tracer.startSpan("AuthResolveApiToken");
-  const tokenHash = createHash("sha256").update(token).digest("hex");
-  const apiToken = await UsersApiTokensDataGetByTokenHash(span, tokenHash);
-  let payload: any | null = null;
-  if (apiToken) {
-    const user = await UsersDataGet(span, apiToken.userId);
-    if (user) {
-      payload = {
-        userId: user.id,
-        userName: user.name,
-        role: user.role,
-        scopes: user.role === "admin" ? [...User.ALL_SCOPES] : user.scopes,
-      };
-    }
-  }
-  span.end();
-  return payload;
-}
-
-export async function AuthMustBeAuthenticated(
-  req: any,
-  res: any,
-): Promise<void> {
-  if (!(await jwtDecodeCached(req))) {
-    res.status(403).send({ error: "Access Denied" });
-    throw new Error("Access Denied");
-  }
-}
-
-export async function AuthMustBeAdmin(req: any, res: any): Promise<void> {
-  const info = await jwtDecodeCached(req);
-  if (info?.role === "admin") {
-    return;
-  }
-  res.status(403).send({ error: "Access Denied" });
-  throw new Error("Access Denied");
-}
-
-export async function AuthHasScope(
-  req: any,
-  res: any,
-  scope: UserScope,
-): Promise<void> {
-  const info = await 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");
-}
-
-export async function AuthGetUserSession(req: any): Promise<UserSession> {
-  const userSession: UserSession = { isAuthenticated: false };
-  const info = await 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/users/User.ts

@@ -1,75 +0,0 @@
-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[] = [];
-
-  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();
-  }
-
-  public toJson(): any {
-    return {
-      id: this.id,
-      name: this.name,
-      passwordEncrypted: this.passwordEncrypted,
-      role: this.role,
-      scopes: this.scopes,
-    };
-  }
-
-  public toTransportJson(): any {
-    return {
-      id: this.id,
-      name: this.name,
-      role: this.role,
-      scopes: this.scopes,
-    };
-  }
-}

package/src/users/UserApiToken.ts

@@ -1,55 +0,0 @@
-import { v4 as uuidv4 } from "uuid";
-
-/**
- * User-scoped API token.
- *
- * Only the SHA-256 hash of the token value is ever stored; the plaintext
- * value is generated at creation time and shown to the user exactly once.
- * A token grants the same permissions as the user it belongs to, resolved
- * live on each request (role/scope changes apply immediately).
- */
-export class UserApiToken {
-  //
-  public static fromJson(json: any): UserApiToken | null {
-    if (!json) {
-      return null;
-    }
-    const apiToken = new UserApiToken();
-    apiToken.id = json.id;
-    apiToken.name = json.name;
-    apiToken.userId = json.userId;
-    apiToken.tokenHash = json.tokenHash;
-    apiToken.dateCreated = json.dateCreated;
-    return apiToken;
-  }
-
-  public id: string;
-  public name!: string;
-  public userId!: string;
-  public tokenHash!: string;
-  public dateCreated!: string;
-
-  constructor() {
-    this.id = uuidv4();
-  }
-
-  public toJson(): any {
-    return {
-      id: this.id,
-      name: this.name,
-      userId: this.userId,
-      tokenHash: this.tokenHash,
-      dateCreated: this.dateCreated,
-    };
-  }
-
-  // Transport representation: never exposes the token hash.
-  public toTransportJson(): any {
-    return {
-      id: this.id,
-      name: this.name,
-      userId: this.userId,
-      dateCreated: this.dateCreated,
-    };
-  }
-}

package/src/users/UserPassword.spec.ts

@@ -1,28 +0,0 @@
-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/users/UserPassword.ts

@@ -1,20 +0,0 @@
-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/users/UserSession.ts

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

package/src/users/UsersApiTokensData.spec.ts

@@ -1,158 +0,0 @@
-jest.mock("uuid", () => ({
-  v4: () => "mock-uuid-1234",
-}));
-
-jest.mock("../DbUtils", () => ({
-  DbUtilsQuerySQL: jest.fn(),
-  DbUtilsExecSQL: jest.fn(),
-}));
-
-import { StandardTracer } from "@devopsplaybook.io/otel-utils";
-import { DbUtilsExecSQL, DbUtilsQuerySQL } from "../DbUtils";
-import { UserApiToken } from "./UserApiToken";
-import {
-  UsersApiTokensDataAdd,
-  UsersApiTokensDataDelete,
-  UsersApiTokensDataDeleteByUser,
-  UsersApiTokensDataGet,
-  UsersApiTokensDataGetByTokenHash,
-  UsersApiTokensDataListByUser,
-  UsersApiTokensDataSetOTel,
-} from "./UsersApiTokensData";
-
-const mockedQuery = DbUtilsQuerySQL as jest.Mock;
-const mockedExec = DbUtilsExecSQL as jest.Mock;
-
-const mockTracer = {
-  startSpan: () => ({ end: () => undefined }),
-} as unknown as StandardTracer;
-
-beforeAll(() => {
-  UsersApiTokensDataSetOTel(mockTracer);
-});
-
-beforeEach(() => {
-  mockedQuery.mockReset();
-  mockedExec.mockReset();
-});
-
-describe("UsersApiTokensData", () => {
-  it("should add a token storing only its hash", async () => {
-    const apiToken = new UserApiToken();
-    apiToken.name = "CI token";
-    apiToken.userId = "user-1";
-    apiToken.tokenHash = "abc123hash";
-    apiToken.dateCreated = "2026-09-14T00:00:00.000Z";
-
-    await UsersApiTokensDataAdd(undefined, apiToken);
-
-    expect(mockedExec).toHaveBeenCalledTimes(1);
-    const [, sql, params] = mockedExec.mock.calls[0];
-    expect(sql).toContain("INSERT INTO users_api_tokens");
-    expect(params).toEqual([
-      "mock-uuid-1234",
-      "CI token",
-      "user-1",
-      "abc123hash",
-      "2026-09-14T00:00:00.000Z",
-    ]);
-    expect(sql).toContain("tokenHash");
-  });
-
-  it("should get a token by hash", async () => {
-    mockedQuery.mockResolvedValue([
-      {
-        id: "token-1",
-        name: "CI token",
-        userId: "user-1",
-        tokenHash: "abc123hash",
-        dateCreated: "2026-09-14T00:00:00.000Z",
-      },
-    ]);
-
-    const apiToken = await UsersApiTokensDataGetByTokenHash(
-      undefined,
-      "abc123hash",
-    );
-
-    expect(mockedQuery).toHaveBeenCalledTimes(1);
-    const [, sql, params] = mockedQuery.mock.calls[0];
-    expect(sql).toBe('SELECT * FROM users_api_tokens WHERE "tokenHash" = ?');
-    expect(params).toEqual(["abc123hash"]);
-    expect(apiToken?.id).toBe("token-1");
-    expect(apiToken?.userId).toBe("user-1");
-  });
-
-  it("should return null when no token matches the hash", async () => {
-    mockedQuery.mockResolvedValue([]);
-
-    const apiToken = await UsersApiTokensDataGetByTokenHash(
-      undefined,
-      "unknown-hash",
-    );
-
-    expect(apiToken).toBeNull();
-  });
-
-  it("should get a token by id", async () => {
-    mockedQuery.mockResolvedValue([
-      {
-        id: "token-1",
-        name: "CI token",
-        userId: "user-1",
-        tokenHash: "abc123hash",
-        dateCreated: "2026-09-14T00:00:00.000Z",
-      },
-    ]);
-
-    const apiToken = await UsersApiTokensDataGet(undefined, "token-1");
-
-    const [, sql, params] = mockedQuery.mock.calls[0];
-    expect(sql).toBe('SELECT * FROM users_api_tokens WHERE "id" = ?');
-    expect(params).toEqual(["token-1"]);
-    expect(apiToken?.name).toBe("CI token");
-  });
-
-  it("should list tokens of a user without exposing the hash in transport json", async () => {
-    mockedQuery.mockResolvedValue([
-      {
-        id: "token-1",
-        name: "CI token",
-        userId: "user-1",
-        tokenHash: "abc123hash",
-        dateCreated: "2026-09-14T00:00:00.000Z",
-      },
-    ]);
-
-    const apiTokens = await UsersApiTokensDataListByUser(undefined, "user-1");
-
-    const [, sql, params] = mockedQuery.mock.calls[0];
-    expect(sql).toBe('SELECT * FROM users_api_tokens WHERE "userId" = ?');
-    expect(params).toEqual(["user-1"]);
-    expect(apiTokens.length).toBe(1);
-    const transport = apiTokens[0].toTransportJson();
-    expect(transport).toEqual({
-      id: "token-1",
-      name: "CI token",
-      userId: "user-1",
-      dateCreated: "2026-09-14T00:00:00.000Z",
-    });
-    expect(transport.tokenHash).toBeUndefined();
-  });
-
-  it("should delete a token by id", async () => {
-    await UsersApiTokensDataDelete(undefined, "token-1");
-
-    const [, sql, params] = mockedExec.mock.calls[0];
-    expect(sql).toBe('DELETE FROM users_api_tokens WHERE "id" = ?');
-    expect(params).toEqual(["token-1"]);
-  });
-
-  it("should delete all tokens of a user", async () => {
-    await UsersApiTokensDataDeleteByUser(undefined, "user-1");
-
-    const [, sql, params] = mockedExec.mock.calls[0];
-    expect(sql).toBe('DELETE FROM users_api_tokens WHERE "userId" = ?');
-    expect(params).toEqual(["user-1"]);
-  });
-});

package/src/users/UsersApiTokensData.ts

@@ -1,125 +0,0 @@
-import { StandardTracer } from "@devopsplaybook.io/otel-utils";
-import { Span } from "@opentelemetry/sdk-trace-base";
-import { DbUtilsExecSQL, DbUtilsQuerySQL } from "../DbUtils";
-import { UserApiToken } from "./UserApiToken";
-
-let tracer: StandardTracer;
-
-/**
- * Injects the OTel tracer instance used by the API tokens data module.
- * Must be called once at startup, before any `UsersApiTokensData*` function.
- */
-export function UsersApiTokensDataSetOTel(tracerIn: StandardTracer): void {
-  tracer = tracerIn;
-}
-
-export async function UsersApiTokensDataGet(
-  context: Span | undefined,
-  id: string,
-): Promise<UserApiToken | null> {
-  const span = tracer.startSpan("UsersApiTokensDataGet", context);
-  const tokensRaw = await DbUtilsQuerySQL(span, SQL_QUERIES.GET_TOKEN_BY_ID, [
-    id,
-  ]);
-  let apiToken: UserApiToken | null = null;
-  if (tokensRaw.length > 0) {
-    apiToken = fromRaw(tokensRaw[0]);
-  }
-  span.end();
-  return apiToken;
-}
-
-export async function UsersApiTokensDataGetByTokenHash(
-  context: Span | undefined,
-  tokenHash: string,
-): Promise<UserApiToken | null> {
-  const span = tracer.startSpan("UsersApiTokensDataGetByTokenHash", context);
-  const tokensRaw = await DbUtilsQuerySQL(
-    span,
-    SQL_QUERIES.GET_TOKEN_BY_HASH,
-    [tokenHash],
-  );
-  let apiToken: UserApiToken | null = null;
-  if (tokensRaw.length > 0) {
-    apiToken = fromRaw(tokensRaw[0]);
-  }
-  span.end();
-  return apiToken;
-}
-
-export async function UsersApiTokensDataListByUser(
-  context: Span | undefined,
-  userId: string,
-): Promise<UserApiToken[]> {
-  const span = tracer.startSpan("UsersApiTokensDataListByUser", context);
-  const tokensRaw = await DbUtilsQuerySQL(
-    span,
-    SQL_QUERIES.LIST_TOKENS_BY_USER,
-    [userId],
-  );
-  const apiTokens: UserApiToken[] = [];
-  for (const tokenRaw of tokensRaw) {
-    apiTokens.push(fromRaw(tokenRaw));
-  }
-  span.end();
-  return apiTokens;
-}
-
-export async function UsersApiTokensDataAdd(
-  context: Span | undefined,
-  apiToken: UserApiToken,
-): Promise<void> {
-  const span = tracer.startSpan("UsersApiTokensDataAdd", context);
-  await DbUtilsExecSQL(span, SQL_QUERIES.INSERT_TOKEN, [
-    apiToken.id,
-    apiToken.name,
-    apiToken.userId,
-    apiToken.tokenHash,
-    apiToken.dateCreated,
-  ]);
-  span.end();
-}
-
-export async function UsersApiTokensDataDelete(
-  context: Span | undefined,
-  id: string,
-): Promise<void> {
-  const span = tracer.startSpan("UsersApiTokensDataDelete", context);
-  await DbUtilsExecSQL(span, SQL_QUERIES.DELETE_TOKEN, [id]);
-  span.end();
-}
-
-export async function UsersApiTokensDataDeleteByUser(
-  context: Span | undefined,
-  userId: string,
-): Promise<void> {
-  const span = tracer.startSpan("UsersApiTokensDataDeleteByUser", context);
-  await DbUtilsExecSQL(span, SQL_QUERIES.DELETE_TOKENS_BY_USER, [userId]);
-  span.end();
-}
-
-// Private Functions
-
-function fromRaw(tokenRaw: any): UserApiToken {
-  const apiToken = new UserApiToken();
-  apiToken.id = tokenRaw.id;
-  apiToken.name = tokenRaw.name;
-  apiToken.userId = tokenRaw.userId;
-  apiToken.tokenHash = tokenRaw.tokenHash;
-  apiToken.dateCreated = tokenRaw.dateCreated;
-  return apiToken;
-}
-
-// SQL
-// Written SQLite-first with quoted identifiers (valid for both backends);
-// the DbUtils facade converts `?` placeholders for Postgres.
-
-const SQL_QUERIES = {
-  GET_TOKEN_BY_ID: 'SELECT * FROM users_api_tokens WHERE "id" = ?',
-  GET_TOKEN_BY_HASH: 'SELECT * FROM users_api_tokens WHERE "tokenHash" = ?',
-  LIST_TOKENS_BY_USER: 'SELECT * FROM users_api_tokens WHERE "userId" = ?',
-  INSERT_TOKEN:
-    'INSERT INTO users_api_tokens ("id", "name", "userId", "tokenHash", "dateCreated") VALUES (?, ?, ?, ?, ?)',
-  DELETE_TOKEN: 'DELETE FROM users_api_tokens WHERE "id" = ?',
-  DELETE_TOKENS_BY_USER: 'DELETE FROM users_api_tokens WHERE "userId" = ?',
-};