@devopsplaybook.io/common-utils 1.8.0 → 1.9.0

package/AGENTS.md

@@ -23,10 +23,12 @@ src/
   users/                    # Auth & user management module set
     User.ts                 # User model, roles and application-defined scopes
     UserSession.ts          # Decoded JWT session
-    Auth.ts                 # JWT auth (key init, guards, session decode)
+    UserApiToken.ts         # User API token model (SHA-256 hash only)
+    Auth.ts                 # JWT auth (key init, guards, session decode) + API token resolution
     UserPassword.ts         # bcrypt password hashing/verification
     UsersData.ts            # Users table CRUD (SQLite/Postgres)
-    UsersRoutes.ts          # Standard fastify user management routes
+    UsersApiTokensData.ts   # users_api_tokens table CRUD (SQLite/Postgres)
+    UsersRoutes.ts          # Standard fastify user management routes (incl. self-service API tokens)
   SystemCommand.ts          # Promise wrapper around child_process.exec
   Timeout.ts                # Promise wrapper around setTimeout
   LLM.ts                    # OpenAI-compatible chat completions client (LLMClient)

package/README.md

@@ -404,18 +404,23 @@ fastify.register(new UsersRoutes().getRoutes, { prefix: "/api/users" });
 | `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                                               |
+| `AuthMustBeAuthenticated`    | 403 guard: any valid JWT **or user API token**                         |
 | `AuthMustBeAdmin`            | 403 guard: `role === "admin"`                                          |
-| `AuthHasScope`               | 403 guard: admin or JWT containing the requested scope                 |
-| `AuthGetUserSession`         | Returns the `UserSession` decoded from the request JWT                 |
+| `AuthHasScope`               | 403 guard: admin or credentials containing the requested scope         |
+| `AuthGetUserSession`         | Returns the `UserSession` decoded from the request credentials         |
 | `User`, `UserRole`, `UserScope` | User model; scopes are application-defined strings                  |
 | `UserSession`                | Decoded session: `isAuthenticated`, `userId`, `userName`, `role`, `scopes` |
+| `UserApiToken`               | API token model (only the SHA-256 hash is persisted)                   |
 | `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` |
+| `UsersApiTokensDataSetOTel`  | Injects the OTel tracer used by the API tokens data module             |
+| `UsersApiTokensData*`        | API tokens table CRUD (`Get`, `GetByTokenHash`, `ListByUser`, `Add`, `Delete`, `DeleteByUser`) |
+| `UsersRoutes`                | Fastify routes: `GET /status/initialization`, `POST /session`, user CRUD, `PUT /password`, API tokens (`POST/GET /tokens`, `DELETE /tokens/:id`) |
 
-**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.
+**Requirements**: a `users` table (columns `id`, `name`, `passwordEncrypted`, `role`, `scopes`), the standard `metadata` table created by `init-0000.sql`, and a `users_api_tokens` table (columns `id`, `name`, `userId`, `tokenHash`, `dateCreated`, with a unique index on `tokenHash` and an index on `userId`) for the API token feature. SQL is written SQLite-first; the `DbUtils` facade converts placeholders for Postgres.
+
+**API tokens**: users create their own API tokens via `POST /api/users/tokens` (body `{ name }`); the plaintext token is returned exactly once and only its SHA-256 hash is stored. `GET /api/users/tokens` lists the caller's tokens and `DELETE /api/users/tokens/:id` revokes one (owner or admin). Requests authenticated with `Authorization: Bearer <api-token>` resolve to the owning user's live role and scopes on every request, so role/scope changes apply immediately and revocation is instant. Tokens are valid until revoked (no expiry).
 
 ---
 

package/dist/index.d.ts

@@ -10,7 +10,9 @@ export * from "./src/SystemCommand";
 export * from "./src/Timeout";
 export * from "./src/users/User";
 export * from "./src/users/UserSession";
+export * from "./src/users/UserApiToken";
 export * from "./src/users/Auth";
 export * from "./src/users/UserPassword";
 export * from "./src/users/UsersData";
+export * from "./src/users/UsersApiTokensData";
 export * from "./src/users/UsersRoutes";

package/dist/index.js

@@ -26,7 +26,9 @@ __exportStar(require("./src/SystemCommand"), exports);
 __exportStar(require("./src/Timeout"), exports);
 __exportStar(require("./src/users/User"), exports);
 __exportStar(require("./src/users/UserSession"), exports);
+__exportStar(require("./src/users/UserApiToken"), exports);
 __exportStar(require("./src/users/Auth"), exports);
 __exportStar(require("./src/users/UserPassword"), exports);
 __exportStar(require("./src/users/UsersData"), exports);
+__exportStar(require("./src/users/UsersApiTokensData"), exports);
 __exportStar(require("./src/users/UsersRoutes"), exports);

package/dist/src/users/Auth.js

@@ -40,10 +40,13 @@ exports.AuthMustBeAuthenticated = AuthMustBeAuthenticated;
 exports.AuthMustBeAdmin = AuthMustBeAdmin;
 exports.AuthHasScope = AuthHasScope;
 exports.AuthGetUserSession = AuthGetUserSession;
+const crypto_1 = require("crypto");
 const jwt = __importStar(require("jsonwebtoken"));
 const uuid_1 = require("uuid");
 const DbUtils_1 = require("../DbUtils");
 const User_1 = require("./User");
+const UsersApiTokensData_1 = require("./UsersApiTokensData");
+const UsersData_1 = require("./UsersData");
 let tracer;
 let config;
 /**
@@ -91,11 +94,18 @@ async function AuthGenerateJWT(user) {
     }, config.JWT_KEY);
 }
 /**
- * Decode JWT from request, caching result on req._jwtPayload to avoid
- * redundant verification when multiple auth functions are called per request.
+ * 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).
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function jwtDecodeCached(req) {
+async function jwtDecodeCached(req) {
     if (req._jwtPayload) {
         return req._jwtPayload;
     }
@@ -108,22 +118,57 @@ function jwtDecodeCached(req) {
         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.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+async function resolveApiToken(authorizationHeader) {
+    const token = authorizationHeader.split(" ")[1];
+    if (!token) {
+        return null;
+    }
+    const span = tracer.startSpan("AuthResolveApiToken");
+    const tokenHash = (0, crypto_1.createHash)("sha256").update(token).digest("hex");
+    const apiToken = await (0, UsersApiTokensData_1.UsersApiTokensDataGetByTokenHash)(span, tokenHash);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let payload = null;
+    if (apiToken) {
+        const user = await (0, UsersData_1.UsersDataGet)(span, apiToken.userId);
+        if (user) {
+            payload = {
+                userId: user.id,
+                userName: user.name,
+                role: user.role,
+                scopes: user.role === "admin" ? [...User_1.User.ALL_SCOPES] : user.scopes,
+            };
+        }
+    }
+    span.end();
+    return payload;
+}
 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)) {
+    if (!(await 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);
+    const info = await jwtDecodeCached(req);
     if ((info === null || info === void 0 ? void 0 : info.role) === "admin") {
         return;
     }
@@ -135,7 +180,7 @@ async function AuthHasScope(
 req, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 res, scope) {
-    const info = jwtDecodeCached(req);
+    const info = await jwtDecodeCached(req);
     if (!info) {
         res.status(403).send({ error: "Access Denied" });
         throw new Error("Access Denied");
@@ -153,7 +198,7 @@ res, scope) {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 async function AuthGetUserSession(req) {
     const userSession = { isAuthenticated: false };
-    const info = jwtDecodeCached(req);
+    const info = await jwtDecodeCached(req);
     if (info) {
         userSession.userId = info.userId;
         userSession.userName = info.userName;

package/dist/src/users/UserApiToken.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare class UserApiToken {
+    static fromJson(json: any): UserApiToken | null;
+    id: string;
+    name: string;
+    userId: string;
+    tokenHash: string;
+    dateCreated: string;
+    constructor();
+    toJson(): any;
+    toTransportJson(): any;
+}

package/dist/src/users/UserApiToken.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserApiToken = void 0;
+const uuid_1 = require("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).
+ */
+class UserApiToken {
+    //
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    static fromJson(json) {
+        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;
+    }
+    constructor() {
+        this.id = (0, uuid_1.v4)();
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toJson() {
+        return {
+            id: this.id,
+            name: this.name,
+            userId: this.userId,
+            tokenHash: this.tokenHash,
+            dateCreated: this.dateCreated,
+        };
+    }
+    // Transport representation: never exposes the token hash.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    toTransportJson() {
+        return {
+            id: this.id,
+            name: this.name,
+            userId: this.userId,
+            dateCreated: this.dateCreated,
+        };
+    }
+}
+exports.UserApiToken = UserApiToken;

package/dist/src/users/UsersApiTokensData.d.ts

@@ -0,0 +1,14 @@
+import { StandardTracer } from "@devopsplaybook.io/otel-utils";
+import { Span } from "@opentelemetry/sdk-trace-base";
+import { UserApiToken } from "./UserApiToken";
+/**
+ * Injects the OTel tracer instance used by the API tokens data module.
+ * Must be called once at startup, before any `UsersApiTokensData*` function.
+ */
+export declare function UsersApiTokensDataSetOTel(tracerIn: StandardTracer): void;
+export declare function UsersApiTokensDataGet(context: Span | undefined, id: string): Promise<UserApiToken | null>;
+export declare function UsersApiTokensDataGetByTokenHash(context: Span | undefined, tokenHash: string): Promise<UserApiToken | null>;
+export declare function UsersApiTokensDataListByUser(context: Span | undefined, userId: string): Promise<UserApiToken[]>;
+export declare function UsersApiTokensDataAdd(context: Span | undefined, apiToken: UserApiToken): Promise<void>;
+export declare function UsersApiTokensDataDelete(context: Span | undefined, id: string): Promise<void>;
+export declare function UsersApiTokensDataDeleteByUser(context: Span | undefined, userId: string): Promise<void>;

package/dist/src/users/UsersApiTokensData.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsersApiTokensDataSetOTel = UsersApiTokensDataSetOTel;
+exports.UsersApiTokensDataGet = UsersApiTokensDataGet;
+exports.UsersApiTokensDataGetByTokenHash = UsersApiTokensDataGetByTokenHash;
+exports.UsersApiTokensDataListByUser = UsersApiTokensDataListByUser;
+exports.UsersApiTokensDataAdd = UsersApiTokensDataAdd;
+exports.UsersApiTokensDataDelete = UsersApiTokensDataDelete;
+exports.UsersApiTokensDataDeleteByUser = UsersApiTokensDataDeleteByUser;
+const DbUtils_1 = require("../DbUtils");
+const UserApiToken_1 = require("./UserApiToken");
+let tracer;
+/**
+ * Injects the OTel tracer instance used by the API tokens data module.
+ * Must be called once at startup, before any `UsersApiTokensData*` function.
+ */
+function UsersApiTokensDataSetOTel(tracerIn) {
+    tracer = tracerIn;
+}
+async function UsersApiTokensDataGet(context, id) {
+    const span = tracer.startSpan("UsersApiTokensDataGet", context);
+    const tokensRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_TOKEN_BY_ID, [
+        id,
+    ]);
+    let apiToken = null;
+    if (tokensRaw.length > 0) {
+        apiToken = fromRaw(tokensRaw[0]);
+    }
+    span.end();
+    return apiToken;
+}
+async function UsersApiTokensDataGetByTokenHash(context, tokenHash) {
+    const span = tracer.startSpan("UsersApiTokensDataGetByTokenHash", context);
+    const tokensRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_TOKEN_BY_HASH, [tokenHash]);
+    let apiToken = null;
+    if (tokensRaw.length > 0) {
+        apiToken = fromRaw(tokensRaw[0]);
+    }
+    span.end();
+    return apiToken;
+}
+async function UsersApiTokensDataListByUser(context, userId) {
+    const span = tracer.startSpan("UsersApiTokensDataListByUser", context);
+    const tokensRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.LIST_TOKENS_BY_USER, [userId]);
+    const apiTokens = [];
+    for (const tokenRaw of tokensRaw) {
+        apiTokens.push(fromRaw(tokenRaw));
+    }
+    span.end();
+    return apiTokens;
+}
+async function UsersApiTokensDataAdd(context, apiToken) {
+    const span = tracer.startSpan("UsersApiTokensDataAdd", context);
+    await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.INSERT_TOKEN, [
+        apiToken.id,
+        apiToken.name,
+        apiToken.userId,
+        apiToken.tokenHash,
+        apiToken.dateCreated,
+    ]);
+    span.end();
+}
+async function UsersApiTokensDataDelete(context, id) {
+    const span = tracer.startSpan("UsersApiTokensDataDelete", context);
+    await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.DELETE_TOKEN, [id]);
+    span.end();
+}
+async function UsersApiTokensDataDeleteByUser(context, userId) {
+    const span = tracer.startSpan("UsersApiTokensDataDeleteByUser", context);
+    await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.DELETE_TOKENS_BY_USER, [userId]);
+    span.end();
+}
+// Private Functions
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function fromRaw(tokenRaw) {
+    const apiToken = new UserApiToken_1.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" = ?',
+};

package/dist/src/users/UsersRoutes.js

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UsersRoutes = void 0;
+const crypto_1 = require("crypto");
+const uuid_1 = require("uuid");
 const Auth_1 = require("./Auth");
 const User_1 = require("./User");
+const UserApiToken_1 = require("./UserApiToken");
 const UserPassword_1 = require("./UserPassword");
 const UsersData_1 = require("./UsersData");
+const UsersApiTokensData_1 = require("./UsersApiTokensData");
 /**
  * Retrieves the OTel span attached to the request by the
  * `@devopsplaybook.io/otel-utils-fastify` hooks.
@@ -198,8 +202,61 @@ class UsersRoutes {
                 }
             }
             await (0, UsersData_1.UsersDataDelete)(context, req.params.id);
+            await (0, UsersApiTokensData_1.UsersApiTokensDataDeleteByUser)(context, req.params.id);
             res.status(201).send({});
         });
+        fastify.post("/tokens", 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" });
+            }
+            if (!req.body || !req.body.name) {
+                return res.status(400).send({ error: "Missing: Name" });
+            }
+            const apiToken = new UserApiToken_1.UserApiToken();
+            apiToken.name = req.body.name;
+            // isAuthenticated implies userId is set
+            apiToken.userId = userSession.userId;
+            apiToken.dateCreated = new Date().toISOString();
+            const token = (0, uuid_1.v4)();
+            apiToken.tokenHash = (0, crypto_1.createHash)("sha256").update(token).digest("hex");
+            await (0, UsersApiTokensData_1.UsersApiTokensDataAdd)(context, apiToken);
+            // The plaintext token is returned once; only its hash is stored.
+            return res.status(201).send({
+                token,
+                ...apiToken.toTransportJson(),
+            });
+        });
+        fastify.get("/tokens", 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" });
+            }
+            const apiTokens = await (0, UsersApiTokensData_1.UsersApiTokensDataListByUser)(context, userSession.userId);
+            return res
+                .status(200)
+                .send(apiTokens.map((t) => t.toTransportJson()));
+        });
+        fastify.delete("/tokens/:id", 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" });
+            }
+            const apiToken = await (0, UsersApiTokensData_1.UsersApiTokensDataGet)(context, req.params.id);
+            if (!apiToken) {
+                return res.status(404).send({ error: "API Token Not Found" });
+            }
+            // Owner can always revoke; admins can revoke any token
+            if (apiToken.userId !== userSession.userId &&
+                userSession.role !== "admin") {
+                return res.status(403).send({ error: "Access Denied" });
+            }
+            await (0, UsersApiTokensData_1.UsersApiTokensDataDelete)(context, apiToken.id);
+            return res.status(201).send({});
+        });
     }
 }
 exports.UsersRoutes = UsersRoutes;

package/index.ts

@@ -10,7 +10,9 @@ export * from "./src/SystemCommand";
 export * from "./src/Timeout";
 export * from "./src/users/User";
 export * from "./src/users/UserSession";
+export * from "./src/users/UserApiToken";
 export * from "./src/users/Auth";
 export * from "./src/users/UserPassword";
 export * from "./src/users/UsersData";
+export * from "./src/users/UsersApiTokensData";
 export * from "./src/users/UsersRoutes";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devopsplaybook.io/common-utils",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Shared utility modules for devopsplaybook.io projects (DB, Config, OTel context, auth/users, notifications, LLM, system helpers)",
   "keywords": [
     "Open Telemetry",

package/src/users/Auth.spec.ts

@@ -0,0 +1,268 @@
+jest.mock("uuid", () => ({
+  v4: () => "mock-uuid-1234",
+}));
+
+jest.mock("../DbUtils", () => ({
+  DbUtilsQuerySQL: jest.fn(),
+  DbUtilsExecSQL: jest.fn(),
+}));
+
+jest.mock("./UsersApiTokensData", () => ({
+  UsersApiTokensDataGetByTokenHash: jest.fn(),
+}));
+
+jest.mock("./UsersData", () => ({
+  UsersDataGet: jest.fn(),
+}));
+
+import { StandardTracer } from "@devopsplaybook.io/otel-utils";
+import { DbUtilsExecSQL, DbUtilsQuerySQL } from "../DbUtils";
+import {
+  AuthGenerateJWT,
+  AuthGetUserSession,
+  AuthHasScope,
+  AuthInit,
+  AuthMustBeAdmin,
+  AuthMustBeAuthenticated,
+  AuthSetOTel,
+} from "./Auth";
+import { User } from "./User";
+import { UsersApiTokensDataGetByTokenHash } from "./UsersApiTokensData";
+import { UsersDataGet } from "./UsersData";
+
+const mockedGetByHash = UsersApiTokensDataGetByTokenHash as jest.Mock;
+const mockedUsersDataGet = UsersDataGet as jest.Mock;
+const mockedQuery = DbUtilsQuerySQL as jest.Mock;
+const mockedExec = DbUtilsExecSQL as jest.Mock;
+
+const mockTracer = {
+  startSpan: () => ({ end: () => undefined }),
+} as unknown as StandardTracer;
+
+function mockRes() {
+  const res = {
+    status: jest.fn().mockReturnThis(),
+    send: jest.fn(),
+  };
+  return res;
+}
+
+function mockReq(authorization?: string) {
+  return {
+    headers: authorization ? { authorization } : {},
+  };
+}
+
+async function expectAccessDenied(guard: Promise<void>, res: ReturnType<typeof mockRes>) {
+  await expect(guard).rejects.toThrow("Access Denied");
+  expect(res.status).toHaveBeenCalledWith(403);
+  expect(res.send).toHaveBeenCalledWith({ error: "Access Denied" });
+}
+
+beforeAll(async () => {
+  AuthSetOTel(mockTracer);
+  const config = {
+    JWT_KEY: "",
+    JWT_VALIDITY_DURATION: 3600,
+    DATABASE_TYPE: "sqlite" as const,
+  };
+  mockedQuery.mockResolvedValue([]);
+  await AuthInit(null as never, config, ["traces", "metrics", "logs"]);
+});
+
+beforeEach(() => {
+  mockedGetByHash.mockReset();
+  mockedUsersDataGet.mockReset();
+});
+
+describe("JWT authentication", () => {
+  it("should authenticate a valid JWT", async () => {
+    const user = new User();
+    user.name = "jwt-user";
+    user.role = "user";
+    user.scopes = ["traces"];
+    const jwt = await AuthGenerateJWT(user);
+
+    const res = mockRes();
+    await AuthMustBeAuthenticated(mockReq(`Bearer ${jwt}`), res);
+
+    expect(res.status).not.toHaveBeenCalled();
+  });
+
+  it("should reject a request without authorization header", async () => {
+    const res = mockRes();
+    await expectAccessDenied(
+      AuthMustBeAuthenticated(mockReq(), res),
+      res,
+    );
+  });
+
+  it("should reject an invalid JWT", async () => {
+    const res = mockRes();
+    await expectAccessDenied(
+      AuthMustBeAuthenticated(mockReq("Bearer not-a-jwt"), res),
+      res,
+    );
+    expect(mockedGetByHash).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("API token authentication", () => {
+  it("should authenticate a valid API token and resolve the owning user session", async () => {
+    const user = new User();
+    user.id = "user-1";
+    user.name = "token-user";
+    user.role = "user";
+    user.scopes = ["traces"];
+    const apiToken = new User();
+    apiToken.id = "token-1";
+    mockedGetByHash.mockResolvedValue(apiToken);
+    mockedUsersDataGet.mockResolvedValue(user);
+
+    const res = mockRes();
+    await AuthMustBeAuthenticated(mockReq("Bearer plain-api-token"), res);
+    expect(res.status).not.toHaveBeenCalled();
+
+    const session = await AuthGetUserSession(mockReq("Bearer plain-api-token"));
+    expect(session.isAuthenticated).toBe(true);
+    expect(session.userId).toBe("user-1");
+    expect(session.userName).toBe("token-user");
+    expect(session.role).toBe("user");
+    expect(session.scopes).toEqual(["traces"]);
+  });
+
+  it("should pass AuthMustBeAdmin for an API token owned by an admin", async () => {
+    const admin = new User();
+    admin.id = "admin-1";
+    admin.name = "token-admin";
+    admin.role = "admin";
+    mockedGetByHash.mockResolvedValue(new User());
+    mockedUsersDataGet.mockResolvedValue(admin);
+
+    const res = mockRes();
+    await AuthMustBeAdmin(mockReq("Bearer admin-api-token"), res);
+    expect(res.status).not.toHaveBeenCalled();
+
+    // Admin tokens get the full scope set, mirroring JWT semantics
+    const session = await AuthGetUserSession(mockReq("Bearer admin-api-token"));
+    expect(session.scopes).toEqual(["traces", "metrics", "logs"]);
+  });
+
+  it("should fail AuthMustBeAdmin for an API token owned by a non-admin", async () => {
+    const user = new User();
+    user.id = "user-1";
+    user.name = "token-user";
+    user.role = "user";
+    user.scopes = ["traces"];
+    mockedGetByHash.mockResolvedValue(new User());
+    mockedUsersDataGet.mockResolvedValue(user);
+
+    const res = mockRes();
+    await expectAccessDenied(
+      AuthMustBeAdmin(mockReq("Bearer user-api-token"), res),
+      res,
+    );
+  });
+
+  it("should pass AuthHasScope when the owning user has the scope", async () => {
+    const user = new User();
+    user.id = "user-1";
+    user.name = "token-user";
+    user.role = "user";
+    user.scopes = ["traces"];
+    mockedGetByHash.mockResolvedValue(new User());
+    mockedUsersDataGet.mockResolvedValue(user);
+
+    const res = mockRes();
+    await AuthHasScope(mockReq("Bearer scoped-api-token"), res, "traces");
+    expect(res.status).not.toHaveBeenCalled();
+  });
+
+  it("should fail AuthHasScope when the owning user lacks the scope", async () => {
+    const user = new User();
+    user.id = "user-1";
+    user.name = "token-user";
+    user.role = "user";
+    user.scopes = ["traces"];
+    mockedGetByHash.mockResolvedValue(new User());
+    mockedUsersDataGet.mockResolvedValue(user);
+
+    const res = mockRes();
+    await expectAccessDenied(
+      AuthHasScope(mockReq("Bearer scoped-api-token"), res, "metrics"),
+      res,
+    );
+  });
+
+  it("should reject an unknown or revoked API token", async () => {
+    mockedGetByHash.mockResolvedValue(null);
+
+    const res = mockRes();
+    await expectAccessDenied(
+      AuthMustBeAuthenticated(mockReq("Bearer revoked-token"), res),
+      res,
+    );
+    expect(mockedUsersDataGet).not.toHaveBeenCalled();
+  });
+
+  it("should reject an API token whose user no longer exists", async () => {
+    mockedGetByHash.mockResolvedValue(new User());
+    mockedUsersDataGet.mockResolvedValue(null);
+
+    const res = mockRes();
+    await expectAccessDenied(
+      AuthMustBeAuthenticated(mockReq("Bearer orphan-token"), res),
+      res,
+    );
+  });
+
+  it("should resolve the token only once per request (payload caching)", async () => {
+    const user = new User();
+    user.id = "user-1";
+    user.name = "token-user";
+    user.role = "user";
+    user.scopes = ["traces"];
+    mockedGetByHash.mockResolvedValue(new User());
+    mockedUsersDataGet.mockResolvedValue(user);
+
+    const req = mockReq("Bearer cached-token");
+    await AuthMustBeAuthenticated(req, mockRes());
+    await AuthHasScope(req, mockRes(), "traces");
+    await AuthGetUserSession(req);
+
+    expect(mockedGetByHash).toHaveBeenCalledTimes(1);
+    expect(mockedUsersDataGet).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("AuthInit", () => {
+  it("should load the existing JWT key from metadata", async () => {
+    mockedExec.mockReset();
+    mockedQuery.mockReset();
+    const config = {
+      JWT_KEY: "",
+      JWT_VALIDITY_DURATION: 3600,
+      DATABASE_TYPE: "sqlite" as const,
+    };
+    mockedQuery.mockResolvedValue([{ value: "stored-key" }]);
+    await AuthInit(null as never, config, ["traces"]);
+
+    expect(config.JWT_KEY).toBe("stored-key");
+    expect(mockedExec).not.toHaveBeenCalled();
+  });
+
+  it("should generate and persist a JWT key when none is stored", async () => {
+    mockedExec.mockReset();
+    mockedQuery.mockReset();
+    const config = {
+      JWT_KEY: "",
+      JWT_VALIDITY_DURATION: 3600,
+      DATABASE_TYPE: "sqlite" as const,
+    };
+    mockedQuery.mockResolvedValue([]);
+    await AuthInit(null as never, config, ["traces"]);
+
+    expect(config.JWT_KEY).toBe("mock-uuid-1234");
+    expect(mockedExec).toHaveBeenCalledTimes(1);
+  });
+});

package/src/users/Auth.ts

@@ -1,3 +1,4 @@
+import { createHash } from "crypto";
 import { StandardTracer } from "@devopsplaybook.io/otel-utils";
 import { Span } from "@opentelemetry/sdk-trace-base";
 import * as jwt from "jsonwebtoken";
@@ -5,6 +6,8 @@ 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.
@@ -72,11 +75,18 @@ export async function AuthGenerateJWT(user: User): Promise<string> {
 }
 
 /**
- * Decode JWT from request, caching result on req._jwtPayload to avoid
- * redundant verification when multiple auth functions are called per request.
+ * 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).
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-function jwtDecodeCached(req: any): any | null {
+async function jwtDecodeCached(req: any): Promise<any | null> {
   if (req._jwtPayload) {
     return req._jwtPayload;
   }
@@ -91,17 +101,53 @@ function jwtDecodeCached(req: any): any | null {
     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.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+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);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  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(
   // 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)) {
+  if (!(await jwtDecodeCached(req))) {
     res.status(403).send({ error: "Access Denied" });
     throw new Error("Access Denied");
   }
@@ -109,7 +155,7 @@ export async function AuthMustBeAuthenticated(
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function AuthMustBeAdmin(req: any, res: any): Promise<void> {
-  const info = jwtDecodeCached(req);
+  const info = await jwtDecodeCached(req);
   if (info?.role === "admin") {
     return;
   }
@@ -124,7 +170,7 @@ export async function AuthHasScope(
   res: any,
   scope: UserScope,
 ): Promise<void> {
-  const info = jwtDecodeCached(req);
+  const info = await jwtDecodeCached(req);
   if (!info) {
     res.status(403).send({ error: "Access Denied" });
     throw new Error("Access Denied");
@@ -143,7 +189,7 @@ export async function AuthHasScope(
 // 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);
+  const info = await jwtDecodeCached(req);
   if (info) {
     userSession.userId = info.userId;
     userSession.userName = info.userName;

package/src/users/UserApiToken.ts

@@ -0,0 +1,58 @@
+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 {
+  //
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  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();
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  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.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  public toTransportJson(): any {
+    return {
+      id: this.id,
+      name: this.name,
+      userId: this.userId,
+      dateCreated: this.dateCreated,
+    };
+  }
+}

package/src/users/UsersApiTokensData.spec.ts

@@ -0,0 +1,158 @@
+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

@@ -0,0 +1,126 @@
+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
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+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" = ?',
+};

package/src/users/UsersRoutes.ts

@@ -1,7 +1,10 @@
+import { createHash } from "crypto";
 import { Span } from "@opentelemetry/sdk-trace-base";
 import { FastifyInstance, RequestGenericInterface } from "fastify";
+import { v4 as uuidv4 } from "uuid";
 import { AuthGenerateJWT, AuthGetUserSession, AuthMustBeAdmin } from "./Auth";
 import { User } from "./User";
+import { UserApiToken } from "./UserApiToken";
 import {
   UserPasswordCheckPassword,
   UserPasswordSetPassword,
@@ -15,6 +18,13 @@ import {
   UsersDataUpdatePassword,
   UsersDataUpdateUser,
 } from "./UsersData";
+import {
+  UsersApiTokensDataAdd,
+  UsersApiTokensDataDelete,
+  UsersApiTokensDataDeleteByUser,
+  UsersApiTokensDataGet,
+  UsersApiTokensDataListByUser,
+} from "./UsersApiTokensData";
 
 /**
  * Retrieves the OTel span attached to the request by the
@@ -286,7 +296,80 @@ export class UsersRoutes {
       }
 
       await UsersDataDelete(context, req.params.id);
+      await UsersApiTokensDataDeleteByUser(context, req.params.id);
       res.status(201).send({});
     });
+
+    // ==================== API TOKENS (self-service) ====================
+
+    interface PostApiToken extends RequestGenericInterface {
+      Body: {
+        name: string;
+      };
+    }
+    fastify.post<PostApiToken>("/tokens", async (req, res) => {
+      const context = requestSpan(req);
+      const userSession = await AuthGetUserSession(req);
+      if (!userSession.isAuthenticated) {
+        return res.status(403).send({ error: "Access Denied" });
+      }
+      if (!req.body || !req.body.name) {
+        return res.status(400).send({ error: "Missing: Name" });
+      }
+      const apiToken = new UserApiToken();
+      apiToken.name = req.body.name;
+      // isAuthenticated implies userId is set
+      apiToken.userId = userSession.userId as string;
+      apiToken.dateCreated = new Date().toISOString();
+      const token = uuidv4();
+      apiToken.tokenHash = createHash("sha256").update(token).digest("hex");
+      await UsersApiTokensDataAdd(context, apiToken);
+      // The plaintext token is returned once; only its hash is stored.
+      return res.status(201).send({
+        token,
+        ...apiToken.toTransportJson(),
+      });
+    });
+
+    fastify.get("/tokens", async (req, res) => {
+      const context = requestSpan(req);
+      const userSession = await AuthGetUserSession(req);
+      if (!userSession.isAuthenticated) {
+        return res.status(403).send({ error: "Access Denied" });
+      }
+      const apiTokens = await UsersApiTokensDataListByUser(
+        context,
+        userSession.userId as string,
+      );
+      return res
+        .status(200)
+        .send(apiTokens.map((t) => t.toTransportJson()));
+    });
+
+    interface DeleteApiToken extends RequestGenericInterface {
+      Params: {
+        id: string;
+      };
+    }
+    fastify.delete<DeleteApiToken>("/tokens/:id", async (req, res) => {
+      const context = requestSpan(req);
+      const userSession = await AuthGetUserSession(req);
+      if (!userSession.isAuthenticated) {
+        return res.status(403).send({ error: "Access Denied" });
+      }
+      const apiToken = await UsersApiTokensDataGet(context, req.params.id);
+      if (!apiToken) {
+        return res.status(404).send({ error: "API Token Not Found" });
+      }
+      // Owner can always revoke; admins can revoke any token
+      if (
+        apiToken.userId !== userSession.userId &&
+        userSession.role !== "admin"
+      ) {
+        return res.status(403).send({ error: "Access Denied" });
+      }
+      await UsersApiTokensDataDelete(context, apiToken.id);
+      return res.status(201).send({});
+    });
   }
 }