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

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

@@ -6,9 +6,21 @@ import { UserApiToken } from "./UserApiToken";
  * Must be called once at startup, before any `UsersApiTokensData*` function.
  */
 export declare function UsersApiTokensDataSetOTel(tracerIn: StandardTracer): void;
+/**
+ * One-time capability probe for the optional `users_api_tokens` columns
+ * (`expiresAt`, `lastUsedAt`) added by the documented migration.
+ */
+export declare function UsersApiTokensDataSupportsOptionalColumns(context: Span | undefined): Promise<boolean>;
 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[]>;
+/** Number of tokens owned by a user (per-user cap check). */
+export declare function UsersApiTokensDataCountByUser(context: Span | undefined, userId: string): Promise<number>;
 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>;
+/**
+ * Record a token's last successful use. Best effort: only attempted when the
+ * optional columns exist, and failures never break authentication.
+ */
+export declare function UsersApiTokensDataSetLastUsed(context: Span | undefined, id: string, lastUsedAt: string): Promise<void>;

package/dist/src/users/UsersApiTokensData.js

@@ -1,15 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UsersApiTokensDataSetOTel = UsersApiTokensDataSetOTel;
+exports.UsersApiTokensDataSupportsOptionalColumns = UsersApiTokensDataSupportsOptionalColumns;
 exports.UsersApiTokensDataGet = UsersApiTokensDataGet;
 exports.UsersApiTokensDataGetByTokenHash = UsersApiTokensDataGetByTokenHash;
 exports.UsersApiTokensDataListByUser = UsersApiTokensDataListByUser;
+exports.UsersApiTokensDataCountByUser = UsersApiTokensDataCountByUser;
 exports.UsersApiTokensDataAdd = UsersApiTokensDataAdd;
 exports.UsersApiTokensDataDelete = UsersApiTokensDataDelete;
 exports.UsersApiTokensDataDeleteByUser = UsersApiTokensDataDeleteByUser;
+exports.UsersApiTokensDataSetLastUsed = UsersApiTokensDataSetLastUsed;
 const DbUtils_1 = require("../DbUtils");
 const UserApiToken_1 = require("./UserApiToken");
 let tracer;
+/**
+ * Whether the optional `expiresAt` / `lastUsedAt` columns exist. Probed once
+ * per process so a database that did not run the documented migration never
+ * breaks the auth path.
+ */
+let optionalColumnsAvailable = null;
 /**
  * Injects the OTel tracer instance used by the API tokens data module.
  * Must be called once at startup, before any `UsersApiTokensData*` function.
@@ -17,67 +26,152 @@ let tracer;
 function UsersApiTokensDataSetOTel(tracerIn) {
     tracer = tracerIn;
 }
+/**
+ * One-time capability probe for the optional `users_api_tokens` columns
+ * (`expiresAt`, `lastUsedAt`) added by the documented migration.
+ */
+async function UsersApiTokensDataSupportsOptionalColumns(context) {
+    if (optionalColumnsAvailable === null) {
+        try {
+            await (0, DbUtils_1.DbUtilsQuerySQL)(context, 'SELECT "expiresAt" FROM users_api_tokens LIMIT 1');
+            optionalColumnsAvailable = true;
+        }
+        catch {
+            optionalColumnsAvailable = false;
+        }
+    }
+    return optionalColumnsAvailable;
+}
 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;
+    try {
+        const tokensRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_TOKEN_BY_ID, [
+            id,
+        ]);
+        if (tokensRaw.length > 0) {
+            return fromRaw(tokensRaw[0]);
+        }
+        return null;
+    }
+    finally {
+        span.end();
+    }
 }
 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]);
+    try {
+        const tokensRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_TOKEN_BY_HASH, [tokenHash]);
+        if (tokensRaw.length > 0) {
+            return fromRaw(tokensRaw[0]);
+        }
+        return null;
+    }
+    finally {
+        span.end();
     }
-    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));
+    try {
+        const tokensRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.LIST_TOKENS_BY_USER, [userId]);
+        return tokensRaw.map(fromRaw);
+    }
+    finally {
+        span.end();
+    }
+}
+/** Number of tokens owned by a user (per-user cap check). */
+async function UsersApiTokensDataCountByUser(context, userId) {
+    var _a;
+    var _b;
+    const span = tracer.startSpan("UsersApiTokensDataCountByUser", context);
+    try {
+        const rows = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.COUNT_TOKENS_BY_USER, [
+            userId,
+        ]);
+        return Number((_b = (_a = rows[0]) === null || _a === void 0 ? void 0 : _a.count) !== null && _b !== void 0 ? _b : 0);
+    }
+    finally {
+        span.end();
     }
-    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();
+    try {
+        if (apiToken.expiresAt) {
+            if (!(await UsersApiTokensDataSupportsOptionalColumns(context))) {
+                throw new Error("users_api_tokens.expiresAt does not exist: run the documented migration to enable API token expiry");
+            }
+            await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.INSERT_TOKEN_WITH_EXPIRY, [
+                apiToken.id,
+                apiToken.name,
+                apiToken.userId,
+                apiToken.tokenHash,
+                apiToken.dateCreated,
+                apiToken.expiresAt,
+            ]);
+            return;
+        }
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.INSERT_TOKEN, [
+            apiToken.id,
+            apiToken.name,
+            apiToken.userId,
+            apiToken.tokenHash,
+            apiToken.dateCreated,
+        ]);
+    }
+    finally {
+        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();
+    try {
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.DELETE_TOKEN, [id]);
+    }
+    finally {
+        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();
+    try {
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.DELETE_TOKENS_BY_USER, [userId]);
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * Record a token's last successful use. Best effort: only attempted when the
+ * optional columns exist, and failures never break authentication.
+ */
+async function UsersApiTokensDataSetLastUsed(context, id, lastUsedAt) {
+    if (!(await UsersApiTokensDataSupportsOptionalColumns(context))) {
+        return;
+    }
+    const span = tracer.startSpan("UsersApiTokensDataSetLastUsed", context);
+    try {
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.UPDATE_TOKEN_LAST_USED, [
+            lastUsedAt,
+            id,
+        ]);
+    }
+    finally {
+        span.end();
+    }
 }
 // Private Functions
 function fromRaw(tokenRaw) {
+    var _a, _b;
     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;
+    apiToken.expiresAt = (_a = tokenRaw.expiresAt) !== null && _a !== void 0 ? _a : null;
+    apiToken.lastUsedAt = (_b = tokenRaw.lastUsedAt) !== null && _b !== void 0 ? _b : null;
     return apiToken;
 }
 // SQL
@@ -87,7 +181,10 @@ 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" = ?',
+    COUNT_TOKENS_BY_USER: 'SELECT COUNT(*) as count FROM users_api_tokens WHERE "userId" = ?',
     INSERT_TOKEN: 'INSERT INTO users_api_tokens ("id", "name", "userId", "tokenHash", "dateCreated") VALUES (?, ?, ?, ?, ?)',
+    INSERT_TOKEN_WITH_EXPIRY: 'INSERT INTO users_api_tokens ("id", "name", "userId", "tokenHash", "dateCreated", "expiresAt") VALUES (?, ?, ?, ?, ?, ?)',
+    UPDATE_TOKEN_LAST_USED: 'UPDATE users_api_tokens SET "lastUsedAt" = ? WHERE "id" = ?',
     DELETE_TOKEN: 'DELETE FROM users_api_tokens WHERE "id" = ?',
     DELETE_TOKENS_BY_USER: 'DELETE FROM users_api_tokens WHERE "userId" = ?',
 };

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

@@ -8,8 +8,27 @@ import { User } from "./User";
 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[]>;
+/**
+ * List users, optionally paginated. `offset` is only applied together with a
+ * `limit` (SQLite requires a LIMIT clause for OFFSET).
+ */
+export declare function UsersDataList(context: Span | undefined, limit?: number, offset?: number): Promise<User[]>;
+/** Number of users (COUNT(*) – used instead of loading the full list). */
+export declare function UsersDataCount(context: Span | undefined): Promise<number>;
+/** Number of admin users (COUNT(*) – used by the last-admin guards). */
+export declare function UsersDataCountAdmins(context: Span | undefined): Promise<number>;
 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>;
+/**
+ * Invalidate the JWTs issued for a user by incrementing `tokenVersion`.
+ * Only called when `JWT_REVOCATION_ENABLED` is on: the column is part of the
+ * documented `users` migration and absent otherwise.
+ */
+export declare function UsersDataBumpTokenVersion(context: Span | undefined, id: string): Promise<void>;
+/**
+ * Whether an error is a unique-constraint violation (`SQLITE_CONSTRAINT*` /
+ * Postgres `23505`) – used to turn the user-name uniqueness race into a 400.
+ */
+export declare function isUniqueViolationError(error: unknown): boolean;

package/dist/src/users/UsersData.js

@@ -4,10 +4,14 @@ exports.UsersDataSetOTel = UsersDataSetOTel;
 exports.UsersDataGet = UsersDataGet;
 exports.UsersDataGetByName = UsersDataGetByName;
 exports.UsersDataList = UsersDataList;
+exports.UsersDataCount = UsersDataCount;
+exports.UsersDataCountAdmins = UsersDataCountAdmins;
 exports.UsersDataAdd = UsersDataAdd;
 exports.UsersDataUpdatePassword = UsersDataUpdatePassword;
 exports.UsersDataUpdateUser = UsersDataUpdateUser;
 exports.UsersDataDelete = UsersDataDelete;
+exports.UsersDataBumpTokenVersion = UsersDataBumpTokenVersion;
+exports.isUniqueViolationError = isUniqueViolationError;
 const DbUtils_1 = require("../DbUtils");
 const User_1 = require("./User");
 let tracer;
@@ -20,85 +24,176 @@ function UsersDataSetOTel(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;
+    try {
+        const usersRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_USER_BY_ID, [
+            id,
+        ]);
+        if (usersRaw.length > 0) {
+            return fromRaw(usersRaw[0]);
+        }
+        return null;
+    }
+    finally {
+        span.end();
+    }
 }
 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;
+    try {
+        const usersRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_USER_BY_NAME, [
+            name,
+        ]);
+        if (usersRaw.length > 0) {
+            return fromRaw(usersRaw[0]);
+        }
+        return null;
+    }
+    finally {
+        span.end();
+    }
 }
-async function UsersDataList(context) {
+/**
+ * List users, optionally paginated. `offset` is only applied together with a
+ * `limit` (SQLite requires a LIMIT clause for OFFSET).
+ */
+async function UsersDataList(context, limit, offset) {
     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));
+    try {
+        let sql = SQL_QUERIES.LIST_USERS;
+        const params = [];
+        if (limit !== undefined) {
+            sql += " LIMIT ?";
+            params.push(limit);
+            if (offset !== undefined) {
+                sql += " OFFSET ?";
+                params.push(offset);
+            }
+        }
+        const usersRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, sql, params);
+        return usersRaw.map(fromRaw);
+    }
+    finally {
+        span.end();
+    }
+}
+/** Number of users (COUNT(*) – used instead of loading the full list). */
+async function UsersDataCount(context) {
+    var _a;
+    var _b;
+    const span = tracer.startSpan("UsersDataCount", context);
+    try {
+        const rows = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.COUNT_USERS);
+        return Number((_b = (_a = rows[0]) === null || _a === void 0 ? void 0 : _a.count) !== null && _b !== void 0 ? _b : 0);
+    }
+    finally {
+        span.end();
+    }
+}
+/** Number of admin users (COUNT(*) – used by the last-admin guards). */
+async function UsersDataCountAdmins(context) {
+    var _a;
+    var _b;
+    const span = tracer.startSpan("UsersDataCountAdmins", context);
+    try {
+        const rows = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.COUNT_ADMINS);
+        return Number((_b = (_a = rows[0]) === null || _a === void 0 ? void 0 : _a.count) !== null && _b !== void 0 ? _b : 0);
+    }
+    finally {
+        span.end();
     }
-    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();
+    try {
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.INSERT_USER, [
+            user.id,
+            user.name,
+            user.passwordEncrypted,
+            user.role,
+            JSON.stringify(user.scopes),
+        ]);
+    }
+    finally {
+        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();
+    try {
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.UPDATE_PASSWORD, [
+            user.passwordEncrypted,
+            user.id,
+        ]);
+    }
+    finally {
+        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();
+    try {
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.UPDATE_USER, [
+            user.role,
+            JSON.stringify(user.scopes),
+            user.id,
+        ]);
+    }
+    finally {
+        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();
+    try {
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.DELETE_USER, [id]);
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * Invalidate the JWTs issued for a user by incrementing `tokenVersion`.
+ * Only called when `JWT_REVOCATION_ENABLED` is on: the column is part of the
+ * documented `users` migration and absent otherwise.
+ */
+async function UsersDataBumpTokenVersion(context, id) {
+    const span = tracer.startSpan("UsersDataBumpTokenVersion", context);
+    try {
+        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.BUMP_TOKEN_VERSION, [id]);
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * Whether an error is a unique-constraint violation (`SQLITE_CONSTRAINT*` /
+ * Postgres `23505`) – used to turn the user-name uniqueness race into a 400.
+ */
+function isUniqueViolationError(error) {
+    if (!error) {
+        return false;
+    }
+    const err = error;
+    if (err.code === "23505" ||
+        err.code === "SQLITE_CONSTRAINT_UNIQUE" ||
+        err.code === "SQLITE_CONSTRAINT_PRIMARYKEY") {
+        return true;
+    }
+    const message = typeof err.message === "string" ? err.message : "";
+    return (/UNIQUE constraint failed/i.test(message) ||
+        /duplicate key value violates unique constraint/i.test(message));
 }
 // Private Functions
 function fromRaw(userRaw) {
+    var _a;
     const user = new User_1.User();
     user.id = userRaw.id;
     user.name = userRaw.name;
     user.passwordEncrypted = userRaw.passwordEncrypted;
     user.role = userRaw.role || "user";
+    user.tokenVersion = Number((_a = userRaw.tokenVersion) !== null && _a !== void 0 ? _a : 0) || 0;
     if (userRaw.scopes) {
-        try {
-            user.scopes = JSON.parse(userRaw.scopes);
-        }
-        catch {
-            user.scopes = [...User_1.User.DEFAULT_SCOPES];
-        }
+        user.scopes = User_1.User.normalizeScopes(userRaw.scopes);
     }
     return user;
 }
@@ -109,8 +204,11 @@ 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",
+    COUNT_USERS: "SELECT COUNT(*) as count FROM users",
+    COUNT_ADMINS: "SELECT COUNT(*) as count FROM users WHERE \"role\" = 'admin'",
     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" = ?',
+    BUMP_TOKEN_VERSION: 'UPDATE users SET "tokenVersion" = COALESCE("tokenVersion", 0) + 1 WHERE "id" = ?',
     DELETE_USER: 'DELETE FROM users WHERE "id" = ?',
 };