@devopsplaybook.io/common-utils 1.10.1 → 1.11.0

package/dist/src/SqlDbUtils.d.ts

@@ -17,7 +17,12 @@ export declare function SqlDbUtilsSetOTel(tracerIn: StandardTracer, loggerIn: St
  *
  * Migration files must follow the naming convention `init-NNNN.sql` and are
  * applied in lexicographic order.  A `metadata` table tracks which migrations
- * have already been applied so they are idempotent.
+ * have already been applied so they are idempotent.  Each migration file and
+ * its `db_version` row are applied inside a single transaction; a failing
+ * migration is rolled back and never recorded.
+ *
+ * SQLite only supports a single writer: run exactly one instance against a
+ * given database file.
  *
  * @param context  Parent OTel span.
  * @param config   Configuration with `DATA_DIR`.
@@ -30,11 +35,14 @@ export declare function SqlDbUtilsGetDatabase(): Database.Database;
  * Execute a write SQL statement with OTel tracing.
  * @returns Number of rows changed.
  */
-export declare function SqlDbUtilsExecSQL(context: Span, sql: string, params?: unknown[]): number;
-/** Execute an entire SQL file (used for migrations). */
+export declare function SqlDbUtilsExecSQL(context: Span | undefined, sql: string, params?: unknown[]): number;
+/**
+ * Execute an entire SQL file (used for migrations).
+ * Migration files must not contain their own transaction control statements.
+ */
 export declare function SqlDbUtilsExecSQLFile(context: Span, filename: string): void;
 /**
  * Execute a read SQL query with OTel tracing.
  * @returns Array of row objects.
  */
-export declare function SqlDbUtilsQuerySQL(context: Span, sql: string, params?: unknown[], debug?: boolean): any[];
+export declare function SqlDbUtilsQuerySQL(context: Span | undefined, sql: string, params?: unknown[], debug?: boolean): any[];

package/dist/src/SqlDbUtils.js

@@ -48,6 +48,27 @@ const api_1 = require("@opentelemetry/api");
 let database;
 let tracer;
 let logger;
+/**
+ * Compiled statements are cached: `better-sqlite3` has no internal cache and
+ * `prepare()` is the dominant cost on hot paths.  The cache is bounded and is
+ * reset by {@link SqlDbUtilsInit} (statements belong to one `Database` handle).
+ */
+const PREPARED_STATEMENT_CACHE_MAX = 100;
+let preparedStatements = new Map();
+function prepareCached(sql) {
+    let statement = preparedStatements.get(sql);
+    if (!statement) {
+        if (preparedStatements.size >= PREPARED_STATEMENT_CACHE_MAX) {
+            const oldest = preparedStatements.keys().next().value;
+            if (oldest !== undefined) {
+                preparedStatements.delete(oldest);
+            }
+        }
+        statement = database.prepare(sql);
+        preparedStatements.set(sql, statement);
+    }
+    return statement;
+}
 /**
  * Injects the OTel tracer and logger instances used by all SQL operations.
  * Must be called once at startup, before {@link SqlDbUtilsInit}.
@@ -61,7 +82,12 @@ function SqlDbUtilsSetOTel(tracerIn, loggerIn) {
  *
  * Migration files must follow the naming convention `init-NNNN.sql` and are
  * applied in lexicographic order.  A `metadata` table tracks which migrations
- * have already been applied so they are idempotent.
+ * have already been applied so they are idempotent.  Each migration file and
+ * its `db_version` row are applied inside a single transaction; a failing
+ * migration is rolled back and never recorded.
+ *
+ * SQLite only supports a single writer: run exactly one instance against a
+ * given database file.
  *
  * @param context  Parent OTel span.
  * @param config   Configuration with `DATA_DIR`.
@@ -69,29 +95,43 @@ function SqlDbUtilsSetOTel(tracerIn, loggerIn) {
  */
 async function SqlDbUtilsInit(context, config, sqlDir) {
     const span = tracer.startSpan("SqlDbUtilsInit", context);
-    await fs.ensureDir(config.DATA_DIR);
-    database = new better_sqlite3_1.default(`${config.DATA_DIR}/database.db`);
-    SqlDbUtilsExecSQLFile(span, `${sqlDir}/init-0000.sql`);
-    const initFiles = (await fs.readdir(sqlDir)).sort();
-    let dbVersionApplied = 0;
-    const rows = SqlDbUtilsQuerySQL(span, "SELECT MAX(value) as maxVersion FROM metadata WHERE type='db_version'");
-    if (rows.length > 0 && rows[0].maxVersion) {
-        dbVersionApplied = Number(rows[0].maxVersion);
-    }
-    logger.info(`Current DB Version: ${dbVersionApplied}`, span);
-    for (const initFile of initFiles) {
-        const regex = /init-(\d+).sql/g;
-        const match = regex.exec(initFile);
-        if (match) {
-            const dbVersionInitFile = Number(match[1]);
-            if (dbVersionInitFile > dbVersionApplied) {
-                logger.info(`Loading init file: ${initFile}`, span);
-                SqlDbUtilsExecSQLFile(span, `${sqlDir}/${initFile}`);
-                SqlDbUtilsExecSQL(span, "INSERT INTO metadata (type, value, dateCreated) VALUES ('db_version',?,?)", [dbVersionInitFile, new Date().toISOString()]);
+    try {
+        await fs.ensureDir(config.DATA_DIR);
+        database = new better_sqlite3_1.default(`${config.DATA_DIR}/database.db`);
+        preparedStatements = new Map();
+        SqlDbUtilsExecSQLFile(span, `${sqlDir}/init-0000.sql`);
+        const initFiles = (await fs.readdir(sqlDir)).sort();
+        let dbVersionApplied = 0;
+        // `metadata.value` has text affinity: a plain MAX(value) is lexicographic and
+        // ranks "9" above "10", which re-applies init-0010.sql on every boot.
+        const rows = SqlDbUtilsQuerySQL(span, "SELECT MAX(CAST(value AS INTEGER)) as maxVersion FROM metadata WHERE type='db_version'");
+        if (rows.length > 0 && rows[0].maxVersion !== null && rows[0].maxVersion !== undefined) {
+            dbVersionApplied = Number(rows[0].maxVersion);
+        }
+        logger.info(`Current DB Version: ${dbVersionApplied}`, span);
+        for (const initFile of initFiles) {
+            const regex = /init-(\d+)\.sql/g;
+            const match = regex.exec(initFile);
+            if (match) {
+                const dbVersionInitFile = Number(match[1]);
+                if (dbVersionInitFile > dbVersionApplied) {
+                    logger.info(`Loading init file: ${initFile}`, span);
+                    applyMigration(span, `${sqlDir}/${initFile}`, dbVersionInitFile);
+                }
             }
         }
     }
-    span.end();
+    finally {
+        span.end();
+    }
+}
+/** Apply one migration file and record its version atomically. */
+function applyMigration(context, filename, version) {
+    const apply = database.transaction(() => {
+        SqlDbUtilsExecSQLFile(context, filename);
+        SqlDbUtilsExecSQL(context, "INSERT INTO metadata (type, value, dateCreated) VALUES ('db_version',?,?)", [version, new Date().toISOString()]);
+    });
+    apply();
 }
 /** Returns the underlying `better-sqlite3` Database instance. */
 function SqlDbUtilsGetDatabase() {
@@ -104,33 +144,38 @@ function SqlDbUtilsGetDatabase() {
 function SqlDbUtilsExecSQL(context, sql, params = []) {
     const span = tracer.startSpan("SqlDbUtilsExecSQL", context);
     try {
-        const stmt = database.prepare(sql);
+        const stmt = prepareCached(sql);
         const result = stmt.run(params);
         span.addEvent(`Impacted Rows: ${result.changes}`);
-        span.end();
         return result.changes;
     }
     catch (error) {
         const err = error;
         span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
-        span.end();
         throw error;
     }
+    finally {
+        span.end();
+    }
 }
-/** Execute an entire SQL file (used for migrations). */
+/**
+ * Execute an entire SQL file (used for migrations).
+ * Migration files must not contain their own transaction control statements.
+ */
 function SqlDbUtilsExecSQLFile(context, filename) {
     const span = tracer.startSpan("SqlDbUtilsExecSQLFile", context);
     try {
         const sql = fs.readFileSync(filename).toString();
         database.exec(sql);
-        span.end();
     }
     catch (error) {
         const err = error;
         span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
-        span.end();
         throw error;
     }
+    finally {
+        span.end();
+    }
 }
 /**
  * Execute a read SQL query with OTel tracing.
@@ -142,15 +187,16 @@ function SqlDbUtilsQuerySQL(context, sql, params = [], debug = false) {
         console.log(sql);
     }
     try {
-        const stmt = database.prepare(sql);
+        const stmt = prepareCached(sql);
         const rows = stmt.all(params);
-        span.end();
         return rows;
     }
     catch (error) {
         const err = error;
         span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: err.message });
-        span.end();
         throw error;
     }
+    finally {
+        span.end();
+    }
 }

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

@@ -9,18 +9,28 @@ export interface AuthConfig {
     JWT_KEY: string;
     JWT_VALIDITY_DURATION: number;
     DATABASE_TYPE: "sqlite" | "postgres";
+    /** Opt-in JWT revocation (requires the `users.tokenVersion` migration). */
+    JWT_REVOCATION_ENABLED?: boolean;
+    /** Per-user API token cap (defaults to 100 when unset). */
+    API_TOKENS_MAX_PER_USER?: number;
 }
 /**
  * Injects the OTel tracer instance used by the auth module.
  * Must be called once at startup, before {@link AuthInit}.
  */
 export declare function AuthSetOTel(tracerIn: StandardTracer): void;
+/** Whether the opt-in `JWT_REVOCATION_ENABLED` config flag is on. */
+export declare function AuthJwtRevocationEnabled(): boolean;
+/** Configured per-user API token cap (`API_TOKENS_MAX_PER_USER`). */
+export declare function AuthGetApiTokensMaxPerUser(): number;
 /**
  * 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.
+ * one is generated and persisted. The read/create sequence runs under an
+ * advisory lock on Postgres so concurrently booting replicas agree on a
+ * single key; SQLite has a single writer (see README).
  *
  * @param context    Parent OTel span.
  * @param configIn   Server configuration (JWT_KEY is updated in place).

package/dist/src/users/Auth.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthSetOTel = AuthSetOTel;
+exports.AuthJwtRevocationEnabled = AuthJwtRevocationEnabled;
+exports.AuthGetApiTokensMaxPerUser = AuthGetApiTokensMaxPerUser;
 exports.AuthInit = AuthInit;
 exports.AuthGenerateJWT = AuthGenerateJWT;
 exports.AuthMustBeAuthenticated = AuthMustBeAuthenticated;
@@ -47,6 +49,20 @@ const DbUtils_1 = require("../DbUtils");
 const User_1 = require("./User");
 const UsersApiTokensData_1 = require("./UsersApiTokensData");
 const UsersData_1 = require("./UsersData");
+/** Default per-user API token cap when the config field is not set. */
+const DEFAULT_API_TOKENS_MAX_PER_USER = 100;
+/**
+ * Rejected non-JWT credentials are remembered for a short time so that a
+ * flood of bad tokens does not hit the database twice per request. Only the
+ * SHA-256 hash of the presented value is stored, never the plaintext.
+ */
+const REJECTED_CREDENTIALS_MAX = 1024;
+const REJECTED_CREDENTIALS_TTL_MS = 60000;
+const rejectedCredentials = new Map();
+/** `lastUsedAt` is written at most once per hour per token. */
+const LAST_USED_UPDATE_INTERVAL_MS = 60 * 60 * 1000;
+const LAST_USED_TRACKED_MAX = 4096;
+const lastUsedWrites = new Map();
 let tracer;
 let config;
 /**
@@ -56,12 +72,23 @@ let config;
 function AuthSetOTel(tracerIn) {
     tracer = tracerIn;
 }
+/** Whether the opt-in `JWT_REVOCATION_ENABLED` config flag is on. */
+function AuthJwtRevocationEnabled() {
+    return (config === null || config === void 0 ? void 0 : config.JWT_REVOCATION_ENABLED) === true;
+}
+/** Configured per-user API token cap (`API_TOKENS_MAX_PER_USER`). */
+function AuthGetApiTokensMaxPerUser() {
+    var _a;
+    return (_a = config === null || config === void 0 ? void 0 : config.API_TOKENS_MAX_PER_USER) !== null && _a !== void 0 ? _a : DEFAULT_API_TOKENS_MAX_PER_USER;
+}
 /**
  * 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.
+ * one is generated and persisted. The read/create sequence runs under an
+ * advisory lock on Postgres so concurrently booting replicas agree on a
+ * single key; SQLite has a single writer (see README).
  *
  * @param context    Parent OTel span.
  * @param configIn   Server configuration (JWT_KEY is updated in place).
@@ -71,87 +98,176 @@ async function AuthInit(context, configIn, allScopes = []) {
     config = configIn;
     User_1.User.ALL_SCOPES = [...allScopes];
     const span = tracer.startSpan("AuthInit", context);
-    const authKeyRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_AUTH_TOKEN);
-    if (authKeyRaw.length == 0) {
-        configIn.JWT_KEY = (0, uuid_1.v4)();
-        await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.INSERT_AUTH_TOKEN, [
-            configIn.JWT_KEY,
-            new Date().toISOString(),
-        ]);
-    }
-    else {
-        configIn.JWT_KEY = authKeyRaw[0].value;
-    }
-    span.end();
+    try {
+        await (0, DbUtils_1.DbUtilsWithLock)("auth_token", async () => {
+            const authKeyRaw = await (0, DbUtils_1.DbUtilsQuerySQL)(span, SQL_QUERIES.GET_AUTH_TOKEN);
+            if (authKeyRaw.length == 0) {
+                configIn.JWT_KEY = (0, uuid_1.v4)();
+                await (0, DbUtils_1.DbUtilsExecSQL)(span, SQL_QUERIES.INSERT_AUTH_TOKEN, [
+                    configIn.JWT_KEY,
+                    new Date().toISOString(),
+                ]);
+            }
+            else {
+                configIn.JWT_KEY = authKeyRaw[0].value;
+            }
+        });
+    }
+    finally {
+        span.end();
+    }
 }
 async function AuthGenerateJWT(user) {
+    var _a;
     return jwt.sign({
         exp: Math.floor(Date.now() / 1000) + config.JWT_VALIDITY_DURATION,
         userId: user.id,
         userName: user.name,
         role: user.role,
         scopes: user.role === "admin" ? User_1.User.ALL_SCOPES : user.scopes,
-    }, config.JWT_KEY);
+        tokenVersion: (_a = user.tokenVersion) !== null && _a !== void 0 ? _a : 0,
+    }, config.JWT_KEY, { algorithm: "HS256" });
 }
 /**
  * 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).
+ * A `Bearer` credential is first verified as a JWT (HS256 only). 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 or expires).
+ *
+ * When `JWT_REVOCATION_ENABLED` is on, the live user is re-read after
+ * verification and the token is rejected when the user is gone or its
+ * `tokenVersion` differs from the claim.
  */
 async function jwtDecodeCached(req) {
+    var _a;
     if (req._jwtPayload) {
         return req._jwtPayload;
     }
-    if (!req.headers.authorization) {
+    const authorization = (_a = req.headers) === null || _a === void 0 ? void 0 : _a.authorization;
+    if (!authorization) {
         return null;
     }
+    const token = authorization.split(" ")[1];
+    if (!token) {
+        return null;
+    }
+    let info;
     try {
-        const info = jwt.verify(req.headers.authorization.split(" ")[1], config.JWT_KEY);
-        req._jwtPayload = info;
-        return info;
+        info = jwt.verify(token, config.JWT_KEY, { algorithms: ["HS256"] });
     }
     catch {
-        const info = await resolveApiToken(req.headers.authorization);
-        if (info) {
-            req._jwtPayload = info;
-            return info;
+        const apiInfo = await resolveApiToken(token);
+        if (apiInfo) {
+            req._jwtPayload = apiInfo;
+            return apiInfo;
         }
         return null;
     }
+    if (config.JWT_REVOCATION_ENABLED && !(await isTokenVersionCurrent(info))) {
+        return null;
+    }
+    req._jwtPayload = info;
+    return info;
+}
+/** Re-read the user and compare its live `tokenVersion` with the claim. */
+async function isTokenVersionCurrent(info) {
+    var _a, _b;
+    const span = tracer.startSpan("AuthCheckTokenVersion");
+    try {
+        const user = await (0, UsersData_1.UsersDataGet)(span, info.userId);
+        if (!user) {
+            return false;
+        }
+        return Number((_a = user.tokenVersion) !== null && _a !== void 0 ? _a : 0) === Number((_b = info.tokenVersion) !== null && _b !== void 0 ? _b : 0);
+    }
+    finally {
+        span.end();
+    }
+}
+function isKnownRejectedCredential(tokenHash) {
+    const expiresAt = rejectedCredentials.get(tokenHash);
+    if (expiresAt === undefined) {
+        return false;
+    }
+    if (expiresAt <= Date.now()) {
+        rejectedCredentials.delete(tokenHash);
+        return false;
+    }
+    return true;
+}
+function rememberRejectedCredential(tokenHash) {
+    if (rejectedCredentials.size >= REJECTED_CREDENTIALS_MAX) {
+        const oldest = rejectedCredentials.keys().next().value;
+        if (oldest !== undefined) {
+            rejectedCredentials.delete(oldest);
+        }
+    }
+    rejectedCredentials.set(tokenHash, Date.now() + REJECTED_CREDENTIALS_TTL_MS);
+}
+function shouldWriteLastUsed(tokenId) {
+    const lastWrite = lastUsedWrites.get(tokenId);
+    const now = Date.now();
+    if (lastWrite !== undefined && now - lastWrite < LAST_USED_UPDATE_INTERVAL_MS) {
+        return false;
+    }
+    if (lastUsedWrites.size >= LAST_USED_TRACKED_MAX) {
+        const oldest = lastUsedWrites.keys().next().value;
+        if (oldest !== undefined) {
+            lastUsedWrites.delete(oldest);
+        }
+    }
+    lastUsedWrites.set(tokenId, now);
+    return true;
 }
 /**
  * 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) {
-    const token = authorizationHeader.split(" ")[1];
-    if (!token) {
+async function resolveApiToken(token) {
+    const tokenHash = (0, crypto_1.createHash)("sha256").update(token).digest("hex");
+    if (isKnownRejectedCredential(tokenHash)) {
         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);
-    let payload = null;
-    if (apiToken) {
+    try {
+        const apiToken = await (0, UsersApiTokensData_1.UsersApiTokensDataGetByTokenHash)(span, tokenHash);
+        if (!apiToken) {
+            rememberRejectedCredential(tokenHash);
+            return null;
+        }
+        if (apiToken.expiresAt && Date.parse(apiToken.expiresAt) <= Date.now()) {
+            rememberRejectedCredential(tokenHash);
+            return null;
+        }
         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,
-            };
+        if (!user) {
+            rememberRejectedCredential(tokenHash);
+            return null;
+        }
+        if (shouldWriteLastUsed(apiToken.id)) {
+            try {
+                await (0, UsersApiTokensData_1.UsersApiTokensDataSetLastUsed)(span, apiToken.id, new Date().toISOString());
+            }
+            catch {
+                // Best effort: a failed lastUsedAt write never breaks authentication.
+            }
         }
+        return {
+            userId: user.id,
+            userName: user.name,
+            role: user.role,
+            scopes: user.role === "admin" ? [...User_1.User.ALL_SCOPES] : user.scopes,
+        };
+    }
+    finally {
+        span.end();
     }
-    span.end();
-    return payload;
 }
 async function AuthMustBeAuthenticated(req, res) {
     if (!(await jwtDecodeCached(req))) {
@@ -199,6 +315,6 @@ async function AuthGetUserSession(req) {
 // 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",
+    GET_AUTH_TOKEN: "SELECT value FROM metadata WHERE \"type\" = 'auth_token' ORDER BY \"dateCreated\" DESC LIMIT 1",
     INSERT_AUTH_TOKEN: 'INSERT INTO metadata ("type", "value", "dateCreated") VALUES (\'auth_token\', ?, ?)',
 };

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

@@ -13,12 +13,22 @@ export declare class User {
     static DEFAULT_SCOPES: UserScope[];
     /** Full scope set of the host application, registered via `AuthInit`. */
     static ALL_SCOPES: UserScope[];
+    /**
+     * Coerce a stored scope value to an array: JSON string and array columns
+     * are both accepted, anything else falls back to the default scopes.
+     */
+    static normalizeScopes(value: unknown): UserScope[];
     static fromJson(json: any): User | null;
     id: string;
     name: string;
     passwordEncrypted: string;
     role: UserRole;
     scopes: UserScope[];
+    /**
+     * Incremented on password/role/scope changes when JWT revocation is
+     * enabled; JWTs carry the value they were issued with.
+     */
+    tokenVersion: number;
     constructor();
     toJson(): any;
     toTransportJson(): any;

package/dist/src/users/User.js

@@ -3,7 +3,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.User = void 0;
 const uuid_1 = require("uuid");
 class User {
+    /**
+     * Coerce a stored scope value to an array: JSON string and array columns
+     * are both accepted, anything else falls back to the default scopes.
+     */
+    static normalizeScopes(value) {
+        if (Array.isArray(value)) {
+            return [...value];
+        }
+        if (typeof value === "string") {
+            try {
+                const parsed = JSON.parse(value);
+                if (Array.isArray(parsed)) {
+                    return parsed;
+                }
+            }
+            catch {
+                // fall through to the default scopes
+            }
+        }
+        return [...User.DEFAULT_SCOPES];
+    }
     static fromJson(json) {
+        var _a;
         if (!json) {
             return null;
         }
@@ -11,26 +33,23 @@ class 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";
+        user.tokenVersion = Number((_a = json.tokenVersion) !== null && _a !== void 0 ? _a : 0) || 0;
         if (json.scopes) {
-            try {
-                user.scopes =
-                    typeof json.scopes === "string"
-                        ? JSON.parse(json.scopes)
-                        : json.scopes;
-            }
-            catch {
-                user.scopes = [...User.DEFAULT_SCOPES];
-            }
+            user.scopes = User.normalizeScopes(json.scopes);
         }
         return user;
     }
     constructor() {
         this.role = "user";
         this.scopes = [...User.DEFAULT_SCOPES];
+        /**
+         * Incremented on password/role/scope changes when JWT revocation is
+         * enabled; JWTs carry the value they were issued with.
+         */
+        this.tokenVersion = 0;
         this.id = (0, uuid_1.v4)();
     }
     toJson() {
@@ -40,6 +59,7 @@ class User {
             passwordEncrypted: this.passwordEncrypted,
             role: this.role,
             scopes: this.scopes,
+            tokenVersion: this.tokenVersion,
         };
     }
     toTransportJson() {

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

@@ -13,6 +13,10 @@ export declare class UserApiToken {
     userId: string;
     tokenHash: string;
     dateCreated: string;
+    /** Optional ISO expiry (`null` = never expires). */
+    expiresAt: string | null;
+    /** Last successful authentication with this token (best effort). */
+    lastUsedAt: string | null;
     constructor();
     toJson(): any;
     toTransportJson(): any;

package/dist/src/users/UserApiToken.js

@@ -13,6 +13,7 @@ const uuid_1 = require("uuid");
 class UserApiToken {
     //
     static fromJson(json) {
+        var _a, _b;
         if (!json) {
             return null;
         }
@@ -22,9 +23,15 @@ class UserApiToken {
         apiToken.userId = json.userId;
         apiToken.tokenHash = json.tokenHash;
         apiToken.dateCreated = json.dateCreated;
+        apiToken.expiresAt = (_a = json.expiresAt) !== null && _a !== void 0 ? _a : null;
+        apiToken.lastUsedAt = (_b = json.lastUsedAt) !== null && _b !== void 0 ? _b : null;
         return apiToken;
     }
     constructor() {
+        /** Optional ISO expiry (`null` = never expires). */
+        this.expiresAt = null;
+        /** Last successful authentication with this token (best effort). */
+        this.lastUsedAt = null;
         this.id = (0, uuid_1.v4)();
     }
     toJson() {
@@ -34,6 +41,8 @@ class UserApiToken {
             userId: this.userId,
             tokenHash: this.tokenHash,
             dateCreated: this.dateCreated,
+            expiresAt: this.expiresAt,
+            lastUsedAt: this.lastUsedAt,
         };
     }
     // Transport representation: never exposes the token hash.
@@ -43,6 +52,8 @@ class UserApiToken {
             name: this.name,
             userId: this.userId,
             dateCreated: this.dateCreated,
+            expiresAt: this.expiresAt,
+            lastUsedAt: this.lastUsedAt,
         };
     }
 }