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

package/README.md

@@ -22,7 +22,7 @@ Shared utility modules for [devopsplaybook.io](https://github.com/devopsplaybook
 npm install @devopsplaybook.io/common-utils
 ```
 
-**Peer dependencies** (installed automatically):
+**Dependencies** (regular dependencies, installed automatically with the package):
 
 | Package                         | Purpose                                             |
 | ------------------------------- | --------------------------------------------------- |
@@ -38,6 +38,26 @@ npm install @devopsplaybook.io/common-utils
 | `jsonwebtoken`                  | JWT signing/verification for the auth module        |
 | `fastify`                       | HTTP framework types for the users routes           |
 
+`fastify` is kept as a regular dependency (not a peer dependency) because `UsersRoutes` is typed against its `FastifyInstance` / `RequestGenericInterface` types: apps that register the routes already have fastify, and apps that don't use the routes must not be forced to add it.
+
+**Subpath imports** -- every module is also exposed as a subpath export, so importing one module never pulls in the whole barrel (and with it the native database drivers):
+
+| Subpath                                       | Module                                       |
+| --------------------------------------------- | -------------------------------------------- |
+| `@devopsplaybook.io/common-utils/otel`        | `createOTelContext`                          |
+| `@devopsplaybook.io/common-utils/config`      | `ConfigBase`                                 |
+| `@devopsplaybook.io/common-utils/db`          | `DbUtils` facade                             |
+| `@devopsplaybook.io/common-utils/db/sqlite`   | `SqlDbUtils`                                 |
+| `@devopsplaybook.io/common-utils/db/postgres` | `PostgresDbUtils` + `PostgresSchemaDbUtils`  |
+| `@devopsplaybook.io/common-utils/db/no-telemetry` | `DbUtilsNoTelemetry`                     |
+| `@devopsplaybook.io/common-utils/users`       | auth/users/routes module                     |
+| `@devopsplaybook.io/common-utils/notifications` | `NotificationsClient`                      |
+| `@devopsplaybook.io/common-utils/llm`         | `LLMClient`                                  |
+| `@devopsplaybook.io/common-utils/system`      | `SystemCommandExecute`                       |
+| `@devopsplaybook.io/common-utils/timeout`     | `TimeoutWait`                                |
+
+The root import (`@devopsplaybook.io/common-utils`) works unchanged. The published tarball contains only `dist/` (no sources, specs or workflows); requiring `package.json` through `@devopsplaybook.io/common-utils/package.json` is also allowed.
+
 ### Modules
 
 #### `OTelContext` -- Telemetry Singleton Factory
@@ -94,21 +114,29 @@ await config.reload();
 
 **Built-in fields** (pre-registered, no `addConfigField` needed):
 
-| Field                                  | Default              | Sensitive                           |
-| -------------------------------------- | -------------------- | ----------------------------------- |
-| `API_PORT`                             | `8080`               | No                                  |
-| `JWT_VALIDITY_DURATION`                | `8035200` (3 months) | No                                  |
-| `CORS_POLICY_ORIGIN`                   | `""`                 | No                                  |
-| `DATA_DIR`                             | `/data`              | No                                  |
-| `JWT_KEY`                              | `uuidv4()`           | Yes                                 |
-| `LOG_LEVEL`                            | `"info"`             | No                                  |
-| `DATABASE_TYPE`                        | `"sqlite"`           | No                                  |
-| `DATABASE_POSTGRES_HOST`               | `""`                 | No                                  |
-| `DATABASE_POSTGRES_PORT`               | `5432`               | No                                  |
-| `DATABASE_POSTGRES_USER`               | `""`                 | No                                  |
-| `DATABASE_POSTGRES_PASSWORD`           | `""`                 | Yes                                 |
-| `DATABASE_POSTGRES_DATABASE`           | `""`                 | No                                  |
-| All `OPENTELEMETRY_COLLECTOR_*` fields | Various              | No (except `_AUTHORIZATION_HEADER`) |
+| Field                                             | Default                              | Sensitive                           |
+| ------------------------------------------------- | ------------------------------------ | ----------------------------------- |
+| `VERSION`                                         | library version (`package.json`)     | No                                  |
+| `SERVICE_ID`                                      | constructor argument                 | No                                  |
+| `API_PORT`                                        | `8080`                               | No                                  |
+| `JWT_VALIDITY_DURATION`                           | `8035200` (3 months)                 | No                                  |
+| `JWT_REVOCATION_ENABLED`                          | `false`                              | No                                  |
+| `API_TOKENS_MAX_PER_USER`                         | `100`                                | No                                  |
+| `CORS_POLICY_ORIGIN`                              | `""`                                 | No                                  |
+| `DATA_DIR`                                        | `/data`                              | No                                  |
+| `JWT_KEY`                                         | `uuidv4()`                           | Yes                                 |
+| `LOG_LEVEL`                                       | `"info"`                             | No                                  |
+| `DATABASE_TYPE`                                   | `"sqlite"`                           | No                                  |
+| `DATABASE_POSTGRES_HOST`                          | `""`                                 | No                                  |
+| `DATABASE_POSTGRES_PORT`                          | `5432`                               | No                                  |
+| `DATABASE_POSTGRES_USER`                          | `""`                                 | No                                  |
+| `DATABASE_POSTGRES_PASSWORD`                      | `""`                                 | Yes                                 |
+| `DATABASE_POSTGRES_DATABASE`                      | `""`                                 | No                                  |
+| `DATABASE_POSTGRES_STATEMENT_TIMEOUT_MS`          | `0` (disabled)                       | No                                  |
+| `DATABASE_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS` | `0` (disabled)                      | No                                  |
+| All `OPENTELEMETRY_COLLECTOR_*` fields            | Various                              | No (except `_AUTHORIZATION_HEADER`) |
+
+`VERSION` is detected from the library's own `package.json` (correct also for the published layout) and can be overridden like any other field via the `VERSION` environment variable or the config file. `SERVICE_ID` can be overridden the same way. Values loaded from the environment or the config file are coerced to the type of the default value (numbers, booleans, arrays), so `"DATABASE_POSTGRES_PORT": "5433"` in `config.json` is applied as the number `5433`. An unsupported `DATABASE_TYPE` makes `DbUtilsInit` reject with an explicit error.
 
 ---
 
@@ -150,7 +178,7 @@ const changes = SqlDbUtilsExecSQL(
 | `SqlDbUtilsExecSQLFile` | `(span, filename)`             | Execute an entire SQL file                       |
 | `SqlDbUtilsGetDatabase` | `()`                           | Returns the `better-sqlite3` `Database` instance |
 
-**Migration convention**: Files named `init-NNNN.sql` in `sqlDir`, applied in order. A `metadata` table tracks applied versions for idempotent re-runs. `init-0000.sql` must exist (creates the `metadata` table).
+**Migration convention**: Files named `init-NNNN.sql` in `sqlDir`, applied in order. `init-0000.sql` must exist (it creates the `metadata` table) — a missing file rejects the init. Each migration file and its `db_version` row are applied inside a single transaction: a failing migration is rolled back, its version is **not** recorded, and it is retried on the next boot. Applied versions are compared numerically — `metadata.value` is a text-affinity column, so a plain `MAX(value)` would order `"9"` after `"10"` and re-apply the tenth and later migrations forever. SQLite has a single writer: never point two processes at the same database file while init/migrations run (Postgres is protected by an advisory lock instead).
 
 ---
 
@@ -169,7 +197,7 @@ Async (Promise-based) database operations using `pg.Pool`, with OTel tracing.
 | `PostgresDbUtilsTransactionStart`  | `(span)`                       | Begin a transaction (`BEGIN`)            |
 | `PostgresDbUtilsTransactionCommit` | `(span)`                       | Commit a transaction (`COMMIT`)          |
 
-Pool defaults: `max: 20`, `idleTimeoutMillis: 30000`, `connectionTimeoutMillis: 10000`.
+Pool defaults: `max: 20`, `idleTimeoutMillis: 30000`, `connectionTimeoutMillis: 10000`. `DATABASE_POSTGRES_STATEMENT_TIMEOUT_MS` and `DATABASE_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS` set the matching per-session settings on every pool (`0`, the default, keeps them disabled — the historical behaviour). Migrations run inside a transaction and are serialised across replicas with a Postgres advisory lock, so two pods booting at the same time cannot apply the same `init-NNNN.sql` twice. The same migration conventions as SQLite apply (`init-0000.sql` must exist, versions are compared numerically).
 
 ---
 
@@ -194,11 +222,11 @@ await DictionaryDb.initSchema(span, config, path.resolve(__dirname, "../sql/dict
 // Init shared runtime pool (call on any instance)
 AuthDb.initRuntimePool(config);
 
-// Query using the schema-specific pool
+// Query using the shared runtime pool (the default)
 const users = await AuthDb.querySQL(span, "SELECT * FROM users WHERE id = $1", [userId]);
 
-// Or use the runtime pool for non-migration queries
-const rows = await AuthDb.querySQL(span, "SELECT ...", [], false);
+// Pass useSchemaPool = true to target the schema-specific pool (migrations, admin tasks)
+const rows = await AuthDb.querySQL(span, "SELECT ...", [], true);
 
 // Transactions
 await AuthDb.transaction(span, async (client) => {
@@ -222,7 +250,7 @@ await AuthDb.closeAll();
 | `transaction(context, callback, useSchemaPool?)`  | Run callback inside a transaction                   |
 | `closeAll()`                                      | Close all pools managed by this instance            |
 
-`useSchemaPool` (default `true`) selects between the schema-specific pool (migrations) and the shared runtime pool (application queries).
+`useSchemaPool` (default `false`) selects between the shared runtime pool (application queries — call `initRuntimePool(config)` first) and the schema-specific pool created by `initSchema` (migrations, schema administration). The default is `false`; pass `true` explicitly for schema-pool access.
 
 ---
 
@@ -257,6 +285,8 @@ const rows = DbUtilsQuerySQL(span, "SELECT * FROM users WHERE id = ?", [
 | `DbUtilsGetType()`                            | Returns `"sqlite"` or `"postgres"`           |
 | `convertToPostgresPlaceholders(sql)`          | Converts `?` to `$1, $2, ...`                |
 
+`convertToPostgresPlaceholders` rewrites only real placeholder `?` characters: single- and double-quoted literals (with `''` escapes), dollar-quoted strings (`$$…$$`, `$tag$…$tag$`) and `--` / `/* */` comments are skipped. The Postgres jsonb `?` operator is **not** supported — use the function form (`jsonb_exists(column, 'key')`). `DbUtilsInit` rejects an unsupported `DATABASE_TYPE` with an explicit error.
+
 ---
 
 #### `DbUtilsNoTelemetry` -- High-Throughput Path
@@ -292,6 +322,8 @@ DbUtilsNoTelemetryBatchInsert(
 | `DbUtilsNoTelemetryQuerySQL(sql, params?, debug?)`        | Read without spans                |
 | `DbUtilsNoTelemetryBatchInsert(tableCols, numCols, rows)` | Optimized multi-row INSERT        |
 
+Repeated statements are compiled once per connection: prepared statements are cached per SQL string (bounded cache, cleared on re-init), which removes the per-call `prepare` cost on ingestion hot paths. `DbUtilsNoTelemetryBatchInsert` chunks large row sets automatically so the generated statement stays below the driver parameter limit (65535 parameters for Postgres, 32766 for SQLite) instead of failing with an opaque driver error.
+
 ---
 
 #### `Notifications` -- Central Notifications Client
@@ -402,25 +434,39 @@ fastify.register(new UsersRoutes().getRoutes, { prefix: "/api/users" });
 | Export                       | Description                                                            |
 | ---------------------------- | ---------------------------------------------------------------------- |
 | `AuthSetOTel`                | Injects the OTel tracer used by the auth module (before `AuthInit`)    |
-| `AuthInit`                   | Registers app scopes, loads or generates the JWT key from `metadata`   |
+| `AuthInit`                   | Registers app scopes, loads or generates the JWT key from `metadata` (under an advisory lock) |
 | `AuthGenerateJWT`            | Signs a JWT for a user (admins get all scopes)                         |
 | `AuthMustBeAuthenticated`    | 403 guard: any valid JWT **or user API token**                         |
 | `AuthMustBeAdmin`            | 403 guard: `role === "admin"`                                          |
 | `AuthHasScope`               | 403 guard: admin or credentials containing the requested scope         |
 | `AuthGetUserSession`         | Returns the `UserSession` decoded from the request credentials         |
+| `AuthJwtRevocationEnabled` / `AuthGetApiTokensMaxPerUser` | Current `JWT_REVOCATION_ENABLED` / `API_TOKENS_MAX_PER_USER` values |
 | `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`) |
+| `UsersData*`                 | Users table CRUD (`Get`, `GetByName`, `List`, `Count`, `CountAdmins`, `Add`, `UpdateUser`, `UpdatePassword`, `Delete`, `BumpTokenVersion`) |
+| `isUniqueViolationError`     | Detects unique-constraint violations (SQLite/Postgres)                 |
 | `UsersApiTokensDataSetOTel`  | Injects the OTel tracer used by the API tokens data module             |
-| `UsersApiTokensData*`        | API tokens table CRUD (`Get`, `GetByTokenHash`, `ListByUser`, `Add`, `Delete`, `DeleteByUser`) |
+| `UsersApiTokensData*`        | API tokens table CRUD (`Get`, `GetByTokenHash`, `ListByUser`, `CountByUser`, `Add`, `Delete`, `DeleteByUser`, `SetLastUsed`) |
 | `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`), 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.
+**Schema requirements**
+
+| Table               | Columns                                                                                     | Notes                                                                                                                              |
+| ------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `users`             | `id`, `name`, `passwordEncrypted`, `role`, `scopes`                                          | Add a **case-insensitive unique index** on the name (`CREATE UNIQUE INDEX ... ON users (LOWER("name"))`): duplicate names differing only by case (e.g. `"Admin"` / `"admin"`) are then rejected with 400. With `JWT_REVOCATION_ENABLED` also add `"tokenVersion" INTEGER DEFAULT 0`. |
+| `users_api_tokens`  | `id`, `name`, `userId`, `tokenHash`, `dateCreated`                                           | Unique index on `tokenHash` and an index on `userId`. Optional additive migration for token expiry / last use: `"expiresAt" TEXT`, `"lastUsedAt" TEXT`. |
+| `metadata`          | created by `init-0000.sql`                                                                   | Stores the JWT key, the first-admin bootstrap marker and the applied migration versions.                                           |
+
+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, expiresAt? }`); the plaintext token is returned exactly once and only its SHA-256 hash is stored. Names are limited to 255 characters and each user may hold at most `API_TOKENS_MAX_PER_USER` (default `100`) tokens. `GET /api/users/tokens` lists the caller's tokens and `DELETE /api/users/tokens/:id` revokes one (owner or admin). `expiresAt` must be a future ISO 8601 date and requires the optional `expiresAt` column — creating a token with an expiry before that migration answers 400. `lastUsedAt` is refreshed at most once per hour and requires its optional column (silently skipped otherwise). Requests authenticated with `Authorization: Bearer <api-token>` resolve the owning user's live role and scopes on every request, so role/scope changes apply immediately and revocation is instant; unknown credentials are negatively cached for a short time so a bad-token flood does not hit the database on every request.
+
+**JWT revocation (opt-in)**: `role` and `scopes` are baked into a JWT at signing time, so a token stays valid (default 3 months) after the user is deleted or their role changes. With `JWT_REVOCATION_ENABLED=true` (default `false`, the default validity is unchanged) every JWT request re-reads the user and rejects tokens whose `tokenVersion` claim is stale; password changes, role/scope changes and deletion therefore invalidate previously issued JWTs. This requires the `users.tokenVersion` column. JWTs are always verified as HS256 (`algorithms: ["HS256"]` is pinned); `iss`/`aud` are not set.
 
-**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).
+**Response conventions**: creation answers 201, reads and deletes answer 200. Malformed or bodyless writes answer 400 (`Missing: …`) instead of HTTP 500, and the last remaining admin cannot demote or delete themselves (`At least 1 admin must be defined`). `GET /` is paginated with `?limit=&offset=` (invalid values answer 400); the bootstrap emptiness check and the last-admin guards use `COUNT(*)` queries instead of loading every row. The 403 guards (`AuthMustBeAuthenticated`, `AuthMustBeAdmin`, `AuthHasScope`) **send the 403 response and then throw** — callers must wrap the guard in `try/catch` and `return` from the catch block (see the `UsersRoutes` implementations) so the route does not continue after the response.
 
 ---
 

package/dist/src/ConfigBase.d.ts

@@ -32,6 +32,10 @@ export interface ConfigDatabaseInterface {
     DATABASE_POSTGRES_USER: string;
     DATABASE_POSTGRES_PASSWORD: string;
     DATABASE_POSTGRES_DATABASE: string;
+    /** Per-session `statement_timeout` in ms (0 = disabled). */
+    DATABASE_POSTGRES_STATEMENT_TIMEOUT_MS: number;
+    /** Per-session `idle_in_transaction_session_timeout` in ms (0 = disabled). */
+    DATABASE_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS: number;
 }
 /**
  * Common server configuration fields shared across projects.
@@ -40,6 +44,8 @@ export interface ConfigCommonInterface extends ConfigOTelInterface, ConfigDataba
     CONFIG_FILE: string;
     API_PORT: number;
     JWT_VALIDITY_DURATION: number;
+    JWT_REVOCATION_ENABLED: boolean;
+    API_TOKENS_MAX_PER_USER: number;
     CORS_POLICY_ORIGIN: string;
     DATA_DIR: string;
     JWT_KEY: string;
@@ -81,6 +87,14 @@ export declare abstract class ConfigBase implements ConfigCommonInterface {
     CONFIG_FILE: string;
     API_PORT: number;
     JWT_VALIDITY_DURATION: number;
+    /**
+     * Opt-in JWT revocation: when enabled, every JWT request re-reads the user
+     * and rejects tokens whose `tokenVersion` claim is stale. Requires the
+     * `users.tokenVersion` migration (see README).
+     */
+    JWT_REVOCATION_ENABLED: boolean;
+    /** Maximum number of API tokens a single user may create. */
+    API_TOKENS_MAX_PER_USER: number;
     CORS_POLICY_ORIGIN: string;
     DATA_DIR: string;
     JWT_KEY: string;
@@ -91,6 +105,16 @@ export declare abstract class ConfigBase implements ConfigCommonInterface {
     DATABASE_POSTGRES_USER: string;
     DATABASE_POSTGRES_PASSWORD: string;
     DATABASE_POSTGRES_DATABASE: string;
+    /**
+     * Per-session `statement_timeout` applied to every Postgres pool.
+     * `0` (default) disables the timeout, preserving the historical behaviour.
+     */
+    DATABASE_POSTGRES_STATEMENT_TIMEOUT_MS: number;
+    /**
+     * Per-session `idle_in_transaction_session_timeout` applied to every
+     * Postgres pool. `0` (default) disables the timeout.
+     */
+    DATABASE_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS: number;
     /**
      * Fields registered by subclasses (or the base) that {@link reload}
      * should process.  Common / DB / OTel fields are pre-registered.
@@ -101,6 +125,13 @@ export declare abstract class ConfigBase implements ConfigCommonInterface {
      * @param configFile Optional path to the JSON config file. Defaults to `"config.json"`.
      */
     constructor(serviceId: string, configFile?: string);
+    /**
+     * Resolve the library's own version from its published manifest.
+     * `dist/src/ConfigBase.js` ships next to `../../package.json`; when running
+     * from the TypeScript sources the manifest is at `../package.json`. Falls
+     * back to `"1"` when neither resolves to this package.
+     */
+    private static detectVersion;
     /**
      * Register a configuration field so that {@link reload} processes it.
      * Call this in your subclass constructor for every project-specific field.

package/dist/src/ConfigBase.js

@@ -41,12 +41,16 @@ const fse = __importStar(require("fs-extra"));
 const uuid_1 = require("uuid");
 const path_1 = __importDefault(require("path"));
 /**
- * Coerce a string value read from an environment variable to match the
- * type of the default value (number → parseFloat, boolean → "true"/"1",
- * array → JSON.parse, etc.).  When the default is already a string or
- * there is no default, the original string is returned as-is.
+ * Coerce a value read from an environment variable (always a string) or from
+ * the config file to match the type of the default value (number →
+ * parseFloat, boolean → "true"/"1", array → JSON.parse, etc.).  Values that
+ * are already typed correctly (config file JSON) pass through unchanged; when
+ * the default is a string or there is no default, the value is returned as-is.
  */
 function coerceValue(value, defaultValue) {
+    if (typeof value !== "string") {
+        return value;
+    }
     if (defaultValue === undefined || defaultValue === null) {
         return value;
     }
@@ -120,6 +124,14 @@ class ConfigBase {
         this.OPENTELEMETRY_COLLECT_AUTHORIZATION_HEADER = "";
         this.API_PORT = 8080;
         this.JWT_VALIDITY_DURATION = 3 * 31 * 24 * 3600;
+        /**
+         * Opt-in JWT revocation: when enabled, every JWT request re-reads the user
+         * and rejects tokens whose `tokenVersion` claim is stale. Requires the
+         * `users.tokenVersion` migration (see README).
+         */
+        this.JWT_REVOCATION_ENABLED = false;
+        /** Maximum number of API tokens a single user may create. */
+        this.API_TOKENS_MAX_PER_USER = 100;
         this.CORS_POLICY_ORIGIN = "";
         this.DATA_DIR = process.env.DATA_DIR || "/data";
         this.JWT_KEY = (0, uuid_1.v4)();
@@ -131,6 +143,16 @@ class ConfigBase {
         this.DATABASE_POSTGRES_USER = "";
         this.DATABASE_POSTGRES_PASSWORD = "";
         this.DATABASE_POSTGRES_DATABASE = "";
+        /**
+         * Per-session `statement_timeout` applied to every Postgres pool.
+         * `0` (default) disables the timeout, preserving the historical behaviour.
+         */
+        this.DATABASE_POSTGRES_STATEMENT_TIMEOUT_MS = 0;
+        /**
+         * Per-session `idle_in_transaction_session_timeout` applied to every
+         * Postgres pool. `0` (default) disables the timeout.
+         */
+        this.DATABASE_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS = 0;
         /**
          * Fields registered by subclasses (or the base) that {@link reload}
          * should process.  Common / DB / OTel fields are pre-registered.
@@ -138,20 +160,15 @@ class ConfigBase {
         this._fields = [];
         this.SERVICE_ID = serviceId;
         this.CONFIG_FILE = configFile || process.env.CONFIG_FILE || "config.json";
-        // Auto-detect version from nearest package.json
-        try {
-            const pkg = fse.readJsonSync(path_1.default.resolve(__dirname, "../package.json"));
-            if (pkg && pkg.version) {
-                this.VERSION = pkg.version;
-            }
-            // eslint-disable-next-line no-unused-vars -- catch binding kept so dist/ stays byte-identical to the TS6 build
-        }
-        catch (_e) {
-            // fallback to "1"
-        }
+        this.VERSION = ConfigBase.detectVersion();
         // Pre-register base + DB + OTel fields so reload() handles them
         const baseFields = [
+            { field: "VERSION" },
+            { field: "SERVICE_ID" },
+            { field: "API_PORT" },
             { field: "JWT_VALIDITY_DURATION" },
+            { field: "JWT_REVOCATION_ENABLED" },
+            { field: "API_TOKENS_MAX_PER_USER" },
             { field: "CORS_POLICY_ORIGIN" },
             { field: "DATA_DIR" },
             { field: "JWT_KEY", sensitive: true },
@@ -166,6 +183,8 @@ class ConfigBase {
                 envAliases: ["POSTGRES_PASSWORD"],
             },
             { field: "DATABASE_POSTGRES_DATABASE", envAliases: ["POSTGRES_DB"] },
+            { field: "DATABASE_POSTGRES_STATEMENT_TIMEOUT_MS" },
+            { field: "DATABASE_POSTGRES_IDLE_IN_TRANSACTION_TIMEOUT_MS" },
             { field: "OPENTELEMETRY_COLLECTOR_HTTP_TRACES" },
             { field: "OPENTELEMETRY_COLLECTOR_HTTP_METRICS" },
             { field: "OPENTELEMETRY_COLLECTOR_HTTP_LOGS" },
@@ -185,6 +204,29 @@ class ConfigBase {
             this.addConfigField(f);
         }
     }
+    /**
+     * Resolve the library's own version from its published manifest.
+     * `dist/src/ConfigBase.js` ships next to `../../package.json`; when running
+     * from the TypeScript sources the manifest is at `../package.json`. Falls
+     * back to `"1"` when neither resolves to this package.
+     */
+    static detectVersion() {
+        for (const candidate of [
+            path_1.default.resolve(__dirname, "../../package.json"),
+            path_1.default.resolve(__dirname, "../package.json"),
+        ]) {
+            try {
+                const pkg = fse.readJsonSync(candidate);
+                if (pkg && pkg.name === "@devopsplaybook.io/common-utils" && pkg.version) {
+                    return pkg.version;
+                }
+            }
+            catch {
+                // try the next candidate
+            }
+        }
+        return "1";
+    }
     /**
      * Register a configuration field so that {@link reload} processes it.
      * Call this in your subclass constructor for every project-specific field.
@@ -246,7 +288,7 @@ class ConfigBase {
             // 4. Config file override (environment always wins, but if neither
             //    environment nor alias matched, check config file)
             if (foundValue === undefined && content[field] !== undefined) {
-                this[field] = content[field];
+                this[field] = coerceValue(content[field], defaultValue);
                 from = "config";
             }
             if (sensitive) {

package/dist/src/DbUtils.d.ts

@@ -8,6 +8,12 @@ import * as PostgresDbUtils from "./PostgresDbUtils";
 export interface DbUtilsConfig extends SqlDbUtils.SqlDbConfig, PostgresDbUtils.PostgresDbConfig {
     DATABASE_TYPE: "sqlite" | "postgres";
 }
+/**
+ * Advisory-lock purposes used by the facade. SQLite has a single writer and
+ * runs the callback directly; Postgres serialises concurrently booting
+ * replicas on the named lock.
+ */
+export type DbUtilsLockName = "auth_token" | "users_bootstrap";
 /**
  * Injects the OTel tracer and logger instances used by the DB layer.
  * Must be called once at startup, before {@link DbUtilsInit}.
@@ -24,13 +30,24 @@ export declare function DbUtilsSetOTel(tracer: StandardTracer, logger: StandardL
  * @param sqlDir   Absolute path to the directory containing SQL migration files.
  */
 export declare function DbUtilsInit(context: Span, config: DbUtilsConfig, sqlDir: string): Promise<void>;
+/**
+ * Run a bootstrap callback while holding the named advisory lock. Replicas
+ * booting concurrently serialise the callback on Postgres; SQLite has a
+ * single writer and runs it directly.
+ */
+export declare function DbUtilsWithLock<T>(lock: DbUtilsLockName, callback: () => Promise<T>): Promise<T>;
 /**
  * Returns the native database handle.
  * - SQLite: `better-sqlite3` `Database` instance
  * - Postgres: `pg` `Pool` instance
  */
 export declare function DbUtilsGetDatabase(): any;
-/** Convert SQLite `?` placeholders to PostgreSQL `$1, $2, ...` numbering. */
+/**
+ * Convert SQLite `?` placeholders to PostgreSQL `$1, $2, ...` numbering.
+ * `?` characters inside single- or double-quoted values, dollar-quoted
+ * strings and `--` / block comments are left untouched. The Postgres jsonb
+ * `?` operator is not supported: use the function form (`jsonb_exists`).
+ */
 export declare function convertToPostgresPlaceholders(sql: string): string;
 /**
  * Execute a write SQL statement with OTel tracing.
@@ -38,13 +55,13 @@ export declare function convertToPostgresPlaceholders(sql: string): string;
  *
  * @returns Number of rows changed.
  */
-export declare function DbUtilsExecSQL(context: Span, sql: string, params?: unknown[]): number | Promise<number>;
+export declare function DbUtilsExecSQL(context: Span | undefined, sql: string, params?: unknown[]): number | Promise<number>;
 /**
  * Execute a read SQL query with OTel tracing.
  * Automatically converts `?` placeholders to `$N` when using Postgres.
  *
  * @returns Array of row objects.
  */
-export declare function DbUtilsQuerySQL(context: Span, sql: string, params?: unknown[], debug?: boolean): any[] | Promise<any[]>;
+export declare function DbUtilsQuerySQL(context: Span | undefined, sql: string, params?: unknown[], debug?: boolean): any[] | Promise<any[]>;
 /** Returns the active database type (`"sqlite"` or `"postgres"`). */
 export declare function DbUtilsGetType(): "sqlite" | "postgres";

package/dist/src/DbUtils.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DbUtilsSetOTel = DbUtilsSetOTel;
 exports.DbUtilsInit = DbUtilsInit;
+exports.DbUtilsWithLock = DbUtilsWithLock;
 exports.DbUtilsGetDatabase = DbUtilsGetDatabase;
 exports.convertToPostgresPlaceholders = convertToPostgresPlaceholders;
 exports.DbUtilsExecSQL = DbUtilsExecSQL;
@@ -62,6 +63,9 @@ function DbUtilsSetOTel(tracer, logger) {
  * @param sqlDir   Absolute path to the directory containing SQL migration files.
  */
 async function DbUtilsInit(context, config, sqlDir) {
+    if (config.DATABASE_TYPE !== "sqlite" && config.DATABASE_TYPE !== "postgres") {
+        throw new Error(`Invalid DATABASE_TYPE: ${config.DATABASE_TYPE} (expected "sqlite" or "postgres")`);
+    }
     databaseType = config.DATABASE_TYPE;
     if (databaseType === "postgres") {
         await PostgresDbUtils.PostgresDbUtilsInit(context, config, sqlDir);
@@ -70,6 +74,17 @@ async function DbUtilsInit(context, config, sqlDir) {
         await SqlDbUtils.SqlDbUtilsInit(context, config, sqlDir);
     }
 }
+/**
+ * Run a bootstrap callback while holding the named advisory lock. Replicas
+ * booting concurrently serialise the callback on Postgres; SQLite has a
+ * single writer and runs it directly.
+ */
+async function DbUtilsWithLock(lock, callback) {
+    if (databaseType === "postgres") {
+        return PostgresDbUtils.PostgresDbUtilsWithAdvisoryLock(lock, callback);
+    }
+    return callback();
+}
 /**
  * Returns the native database handle.
  * - SQLite: `better-sqlite3` `Database` instance
@@ -81,10 +96,86 @@ function DbUtilsGetDatabase() {
     }
     return SqlDbUtils.SqlDbUtilsGetDatabase();
 }
-/** Convert SQLite `?` placeholders to PostgreSQL `$1, $2, ...` numbering. */
+/**
+ * Convert SQLite `?` placeholders to PostgreSQL `$1, $2, ...` numbering.
+ * `?` characters inside single- or double-quoted values, dollar-quoted
+ * strings and `--` / block comments are left untouched. The Postgres jsonb
+ * `?` operator is not supported: use the function form (`jsonb_exists`).
+ */
 function convertToPostgresPlaceholders(sql) {
+    let converted = "";
     let paramIndex = 1;
-    return sql.replace(/\?/g, () => `$${paramIndex++}`);
+    let i = 0;
+    while (i < sql.length) {
+        const char = sql[i];
+        // Single-quoted literal: '' is an escaped quote.
+        if (char === "'") {
+            const end = skipQuoted(sql, i, "'");
+            converted += sql.slice(i, end);
+            i = end;
+            continue;
+        }
+        // Double-quoted identifier, same '' escaping rule.
+        if (char === '"') {
+            const end = skipQuoted(sql, i, '"');
+            converted += sql.slice(i, end);
+            i = end;
+            continue;
+        }
+        // Dollar-quoted string: $tag$ ... $tag$ (or $$ ... $$).
+        if (char === "$") {
+            const tag = /^\$[A-Za-z_][A-Za-z0-9_]*\$|^\$\$/.exec(sql.slice(i));
+            if (tag) {
+                const closing = sql.indexOf(tag[0], i + tag[0].length);
+                const end = closing === -1 ? sql.length : closing + tag[0].length;
+                converted += sql.slice(i, end);
+                i = end;
+                continue;
+            }
+            converted += char;
+            i++;
+            continue;
+        }
+        // Line comment.
+        if (char === "-" && sql[i + 1] === "-") {
+            const newline = sql.indexOf("\n", i);
+            const end = newline === -1 ? sql.length : newline;
+            converted += sql.slice(i, end);
+            i = end;
+            continue;
+        }
+        // Block comment.
+        if (char === "/" && sql[i + 1] === "*") {
+            const closing = sql.indexOf("*/", i + 2);
+            const end = closing === -1 ? sql.length : closing + 2;
+            converted += sql.slice(i, end);
+            i = end;
+            continue;
+        }
+        if (char === "?") {
+            converted += `$${paramIndex++}`;
+            i++;
+            continue;
+        }
+        converted += char;
+        i++;
+    }
+    return converted;
+}
+/** Returns the index just past the closing quote (unterminated → end of string). */
+function skipQuoted(sql, start, quote) {
+    let i = start + 1;
+    while (i < sql.length) {
+        if (sql[i] === quote) {
+            if (sql[i + 1] === quote) {
+                i += 2;
+                continue;
+            }
+            return i + 1;
+        }
+        i++;
+    }
+    return sql.length;
 }
 /**
  * Execute a write SQL statement with OTel tracing.

package/dist/src/DbUtilsNoTelemetry.d.ts

@@ -8,7 +8,10 @@ export declare function DbUtilsNoTelemetrySetLogger(loggerIn: StandardLogger): v
  * Execute a multi-row INSERT with a flat parameter array.
  * Builds: INSERT INTO <tableCols> VALUES (?,?...),(?,?...),...
  *
- * @returns Number of rows inserted.
+ * Large inputs are chunked so the statement never exceeds the backend's
+ * bound-parameter limit (65535 on Postgres, 32766 on SQLite).
+ *
+ * @returns Number of rows inserted (summed across chunks).
  */
 export declare function DbUtilsNoTelemetryBatchInsert(tableCols: string, numCols: number, rows: any[][]): number | Promise<number>;
 /**