@ti-engine/core 1.4.1 → 1.6.1

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 This document contains the list of changes made to the framework. The format is based on the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
 
+## Version 1.6.1
+
+* build(deps): update `@dotenvx/dotenvx` from ^1.73.1 to ^1.75.1
+* build(deps): remove `zeromq` as optional dependency
+
+## Version 1.6.0
+
+* refactor(exchange)!: replace the blake2 keyed hash with native `node:crypto` HMAC-SHA256 in the message integrity check
+* build(deps)!: remove the `blake2` native addon dependency (no longer builds on Node 26; replaced by the built-in `node:crypto`)
+* fix(exchange): use a constant-time comparison for the message security hash
+* fix(exchange): ship an empty default `securityHashKey` and warn (once) when the security hash is enabled with a missing/default key
+* test(exchange): add the first core test suite — message-hash determinism, tamper detection, and the constant-time comparison
+
+> **BREAKING (wire):** the message security hash changes from keyed-BLAKE2b (128 hex) to HMAC-SHA256 (64 hex). Old and new core versions produce mutually incompatible hashes. When upgrading across this version with `securityHashEnabled=true`, redeploy all services together — recommended order: set `securityHashEnabled=false` everywhere → deploy the new core to all services → re-enable. HMAC also accepts keys of any length (custom keys >64 bytes that previously failed under blake2b now work). The default `securityHashKey` is now empty: set `TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY` in any real deployment, otherwise tamper protection is ineffective.
+
+## Version 1.5.1
+
+* build(deps): update `@dotenvx/dotenvx` from ^1.66.0 to ^1.73.1
+* build(deps): update `ioredis` from ^5.10.1 to ^5.11.1
+
+## Version 1.5.0
+
+* feat(exceptions): add `E_APP_RESOURCE_ALREADY_EXISTS` (5006) for resource-creation conflicts; intended to be raised with HTTP `409`
+
+## Version 1.4.6
+
+* build(deps): update `@dotenvx/dotenvx` from ^1.65.0 to ^1.66.0
+
+## Version 1.4.5
+
+* feat(cache): add array-based path support to all `*JSON` methods — passing an array of strings as `path` treats each element as a literal key name using bracket notation, preventing misinterpretation of key names containing dots or other JSONPath special characters
+
+## Version 1.4.4
+
+* build(deps): update `@dotenvx/dotenvx` from ^1.60.0 to ^1.65.0
+
+## Version 1.4.3
+
+* build(deps): update `@dotenvx/dotenvx` from ^1.59.1 to ^1.60.0
+
+## Version 1.4.2
+
+* build(deps): update `@dotenvx/dotenvx` from ^1.55.1 to ^1.59.1
+* build(deps): update `ioredis` from ^5.10.0 to ^5.10.1
+* build(deps): update `lodash` from ^4.17.23 to ^4.18.1
+
 ## Version 1.4.1
 
 * build(deps): update `@dotenvx/dotenvx` from ^1.54.1 to ^1.55.1

package/README.md

@@ -479,12 +479,12 @@ MESSAGE_EXCHANGE_MESSAGE_STORE (Advanced)
 MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED (Advanced)
 : JSON path `messageExchange.securityHashEnabled`, type `boolean`, default `true`
 : ENV variable `TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED`
-: This setting controls whether the message exchange will use a control hash mechanism to ensure there is no tampering with the messages in between service calls. In most cases you would want to keep this enabled since it ensures the integrity of your data. If you are concerned about performance (hashing with `blake2` is rapid, but it still eats some milliseconds) you might want to try and disable this to see if it makes any notable difference.
+: This setting controls whether the message exchange will use a control hash mechanism to ensure there is no tampering with the messages in between service calls. In most cases you would want to keep this enabled since it ensures the integrity of your data. If you are concerned about performance (the keyed `HMAC-SHA256` hash is rapid, but it still eats some milliseconds) you might want to try and disable this to see if it makes any notable difference.
 
 MESSAGE_EXCHANGE_SECURITY_HASH_KEY (Advanced)
-: JSON path `messageExchange.securityHashKey`, type `string`, default `random uuid`
+: JSON path `messageExchange.securityHashKey`, type `string`, default `empty (must be set)`
 : ENV variable `TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY`
-: This setting holds the encryption key used by the message exchange control hash mechanism. By default, this has a random uuid value that can be used for development only. For production environments you absolutely must provide your own encryption key via the ENV variable. Depending on your configuration and infrastructure, it might come from a secure storage, HSM, key vault, etc.
+: This setting holds the HMAC key used by the message exchange control hash mechanism. By default it is empty, which leaves tamper protection ineffective and logs a startup warning. You absolutely must provide your own private key via the ENV variable in any real deployment. Depending on your configuration and infrastructure, it might come from a secure storage, HSM, key vault, etc.
 
 MESSAGE_EXCHANGE_TRACE_EXPIRATION_TIME
 : JSON path `messageExchange.traceExpirationTime`, type `number`, default `3600`

package/bin/settings.json

@@ -26,7 +26,7 @@
     "messageQueuePrefix": "ti:messages:",
     "messageStore": "ti:messages:store",
     "securityHashEnabled": true,
-    "securityHashKey": "23e7bdc7-a793-41f9-856e-6760332f0c73",
+    "securityHashKey": "",
     "traceExpirationTime": 3600,
     "traceLogEnabled": false,
     "traceRepository": "ti:messages:trace"

package/components/exchange/message-handler.js

@@ -8,12 +8,15 @@
 
 const ConnectionObserver = require( "#connection-observer" );
 const _ = require( "lodash" );
-const blake2 = require( "blake2" );
+const crypto = require( "node:crypto" );
 const exceptions = require( "#exceptions" );
 const logger = require( "#logger" );
 const tools = require( "#tools" );
 const config = require( "#config" );
 
+const OLD_DEFAULT_HASH_KEY = "23e7bdc7-a793-41f9-856e-6760332f0c73";
+let keyWarningEmitted = false;
+
 /**
  * An abstract class that defines a basic message handler behavior.
  * <br/>
@@ -120,10 +123,17 @@ class MessageHandler extends ConnectionObserver {
      * @public
      */
     createMessageHash( message ) {
+        let key = config.getSetting( config.setting.MESSAGE_EXCHANGE_SECURITY_HASH_KEY );
+        if ( keyWarningEmitted === false ) {
+            keyWarningEmitted = true;
+            if ( !key || key === OLD_DEFAULT_HASH_KEY ) {
+                logger.log( "Message-exchange security hash is enabled but no private key is set ('securityHashKey' is missing or the published default). Set TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY to a private value, otherwise tamper protection is ineffective.", logger.logSeverity.WARNING );
+            }
+        }
         let transformed = tools.decomposeJSON( tools.decycle( message ) );
-        let hash = blake2.createKeyedHash( "blake2b", Buffer.from( config.getSetting( config.setting.MESSAGE_EXCHANGE_SECURITY_HASH_KEY ) ) );
-        hash.update( Buffer.from( transformed ) );
-        return hash.digest( "hex" );
+        let hmac = crypto.createHmac( "sha256", Buffer.from( key ) );
+        hmac.update( Buffer.from( transformed ) );
+        return hmac.digest( "hex" );
     }
 
     /**

package/components/exchange/message-receiver.js

@@ -10,6 +10,7 @@ const MessageHandler = require( "#message-handler" );
 const logger = require( "#logger" );
 const exceptions = require( "#exceptions" );
 const config = require( "#config" );
+const tools = require( "#tools" );
 
 /**
  * An abstract class that defines a basic message receiver behavior.
@@ -161,7 +162,7 @@ class MessageReceiver extends MessageHandler {
                 let receivedHash = message.hash;
                 delete message.hash;
                 let currentHash = this.createMessageHash( message );
-                if ( receivedHash && receivedHash === currentHash ) {
+                if ( tools.constantTimeEquals( receivedHash, currentHash ) ) {
                     resolve( message );
                 } else {
                     reject( exceptions.raise( exceptions.exceptionCode.E_SEC_MESSAGE_TAMPERING_DETECTED, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ti-engine/core",
-  "version": "1.4.1",
+  "version": "1.6.1",
   "description": "The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.",
   "keywords": [
     "microservices",
@@ -26,6 +26,9 @@
     "./service-provider": "./components/service-provider.js",
     "./tools": "./utils/tools.js"
   },
+  "scripts": {
+    "test": "node --test"
+  },
   "imports": {
     "#auditing": "./components/auditing.js",
     "#cache": "./utils/cache.js",
@@ -56,14 +59,12 @@
     "#tools": "./utils/tools.js"
   },
   "dependencies": {
-    "@dotenvx/dotenvx": "^1.55.1",
-    "blake2": "^5.0.1",
-    "ioredis": "^5.10.0",
-    "lodash": "^4.17.23",
+    "@dotenvx/dotenvx": "^1.75.1",
+    "ioredis": "^5.11.1",
+    "lodash": "^4.18.1",
     "node-schedule": "^2.1.1"
   },
   "optionalDependencies": {
-    "zeromq": "^6.5.0"
   },
   "files": [
     "bin/",

package/utils/cache.js

@@ -341,12 +341,7 @@ class CommonMemoryCache extends ConnectionObserver {
     expireValue( key, seconds, name ) {
         return new Promise( ( resolve, reject ) => {
             if ( this.#isOperational === true ) {
-                let commandExpire = [];
-                if ( name ) {
-                    commandExpire = [ redis.cacheCommands.HASH_EXPIRE, name, seconds, "FIELDS", 1, key ];
-                } else {
-                    commandExpire = [ redis.cacheCommands.EXPIRE, key, seconds ];
-                }
+                let commandExpire = ( name ) ? [ redis.cacheCommands.HASH_EXPIRE, name, seconds, "FIELDS", 1, key ] : [ redis.cacheCommands.EXPIRE, key, seconds ];
                 this.#redisClient.executeCommands( [ commandExpire ] ).then( () => {
                     resolve( seconds );
                 } ).catch( ( error ) => {
@@ -632,7 +627,7 @@ class CommonMemoryCache extends ConnectionObserver {
      * @method
      * @param {string} key
      * @param {Object} value
-     * @param {string} [path="$"]
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments (use the array form when key names may contain dots or other special characters).
      * @param {number} [overrideMode=0] By default this allows full override for existing keys.
      * Option 1 will set the key only if it doesn't already exist. Option 2 will set it only if it already exists.
      * @returns {Promise}
@@ -667,7 +662,7 @@ class CommonMemoryCache extends ConnectionObserver {
      *
      * @method
      * @param {string} key
-     * @param {string} [path="$"]
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments (use the array form when key names may contain dots or other special characters).
      * @returns {Promise<Object>}
      * @public
      */
@@ -698,7 +693,7 @@ class CommonMemoryCache extends ConnectionObserver {
      * @method
      * @param {string} key
      * @param {Object} value
-     * @param {string} [path="$"]
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments (use the array form when key names may contain dots or other special characters).
      * @returns {Promise}
      * @public
      */
@@ -729,7 +724,7 @@ class CommonMemoryCache extends ConnectionObserver {
      * @method
      * @param {string} key
      * @param {Object} value
-     * @param {string} [path="$"]
+     * @param {string|string[]} [path="$"] A dot-separated JSONPath string, or an array of literal key segments (use the array form when key names may contain dots or other special characters).
      * @returns {Promise}
      * @public
      */
@@ -756,13 +751,19 @@ class CommonMemoryCache extends ConnectionObserver {
 
     /**
      * Used to normalize a JSON path.
+     * <br/>
+     * NOTE: If "path" is an array, each element is treated as a literal key name and encoded with bracket notation,
+     * which correctly handles key names that contain dots or other JSONPath special characters.
      *
      * @method
-     * @param {string} path
+     * @param {string|string[]} path
      * @returns {string}
      * @private
      */
     #normalizeJSONPath( path ) {
+        if ( Array.isArray( path ) ) {
+            return "$" + path.map( ( segment ) => `["${ String( segment ).replace( /\\/g, "\\\\" ).replace( /"/g, '\\"' ) }"]` ).join( "" );
+        }
         return ( path.startsWith( "$" ) === false ) ? ( "$." + path ) : path;
     }
 

package/utils/config.js

@@ -1,104 +1,104 @@
-/*
- * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
- * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
- * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
- * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
- * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
-
-const _ = require( "lodash" );
-const tools = require( "#tools" );
-
-/**
- * Enum for listing all system settings.
- *
- * @readonly
- * @enum {string} Keys of this ENUM are strings.
- * @typedef {string} TiSetting
- */
-const settingsEnum = tools.enum( {
-    AUDITING_LOG_CONSOLE_ENABLED: [ "auditing.logConsoleEnabled", "logConsoleEnabled", "" ],
-    AUDITING_LOG_DETAILS: [ "auditing.logDetails", "logDetails", "" ],
-    AUDITING_LOG_MIN_LEVEL: [ "auditing.logMinLevel", "logMinLevel", "" ],
-    AUDITING_LOG_USES_JSON: [ "auditing.logUsesJSON", "logUsesJSON", "" ],
-    GCLOUD_API_KEY: [ "gcloudIntegration.apiKey", "apiKey", "" ],
-    GCLOUD_PROJECT_ID: [ "gcloudIntegration.projectID", "projectID", "" ],
-    LOCALIZATION_LABELS_PATH: [ "localization.labelsPath", "labelsPath", "" ],
-    LOCALIZATION_LANGUAGE: [ "localization.language", "language", "" ],
-    MEMORY_CACHE_AUTH_KEY: [ "memoryCache.authKey", "authKey", "" ],
-    MEMORY_CACHE_REDIS_DB: [ "memoryCache.redisDB", "redisDB", "" ],
-    MEMORY_CACHE_REDIS_HOST: [ "memoryCache.redisHost", "redisHost", "" ],
-    MEMORY_CACHE_REDIS_PORT: [ "memoryCache.redisPort", "redisPort", "" ],
-    MEMORY_CACHE_RETRY_MAX_ATTEMPTS: [ "memoryCache.retryMaxAttempts", "retryMaxAttempts", "" ],
-    MEMORY_CACHE_RETRY_MAX_INTERVAL: [ "memoryCache.retryMaxInterval", "retryMaxInterval", "" ],
-    MEMORY_CACHE_USER: [ "memoryCache.user", "user", "" ],
-    MESSAGE_EXCHANGE_QUEUE_PREFIX: [ "messageExchange.messageQueuePrefix", "messageQueuePrefix", "" ],
-    MESSAGE_EXCHANGE_MESSAGE_STORE: [ "messageExchange.messageStore", "messageStore", "" ],
-    MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED: [ "messageExchange.securityHashEnabled", "securityHashEnabled", "" ],
-    MESSAGE_EXCHANGE_SECURITY_HASH_KEY: [ "messageExchange.securityHashKey", "securityHashKey", "" ],
-    MESSAGE_EXCHANGE_TRACE_EXPIRATION_TIME: [ "messageExchange.traceExpirationTime", "traceExpirationTime", "" ],
-    MESSAGE_EXCHANGE_TRACE_LOG_ENABLED: [ "messageExchange.traceLogEnabled", "traceLogEnabled", "" ],
-    MESSAGE_EXCHANGE_TRACE_REPOSITORY: [ "messageExchange.traceRepository", "traceRepository", "" ],
-    SERVICE_EXECUTION_TIMEOUT: [ "serviceConfig.executionTimeout", "executionTimeout", "" ],
-    SERVICE_HEALTH_CHECK_ADDRESS: [ "serviceConfig.healthCheckAddress", "healthCheckAddress", "" ],
-    SERVICE_HEALTH_CHECK_INTERVAL: [ "serviceConfig.healthCheckInterval", "healthCheckInterval", "" ],
-    SERVICE_HEALTH_CHECK_TIMEOUT: [ "serviceConfig.healthCheckTimeout", "healthCheckTimeout", "" ],
-    SERVICE_REGISTRY_ADDRESS: [ "serviceConfig.serviceRegistryAddress", "serviceRegistryAddress", "" ],
-    OPERATION_MODE: [ "operationMode", "operationMode", "" ]
-} );
-module.exports.setting = settingsEnum;
-
-/** @type {SettingsMain} */
-const settings = require( "#settings" );
-
-// Override the remaining settings with ENV variables (if provided):
-if ( settings.auditing ) {
-    settings.auditing.logConsoleEnabled = ( process.env.TI_AUDITING_LOG_CONSOLE_ENABLED !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_CONSOLE_ENABLED ) : settings.auditing.logConsoleEnabled;
-    settings.auditing.logDetails = ( process.env.TI_AUDITING_LOG_DETAILS !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_DETAILS ) : settings.auditing.logDetails;
-    settings.auditing.logMinLevel = ( process.env.TI_AUDITING_LOG_MIN_LEVEL !== undefined ) ? process.env.TI_AUDITING_LOG_MIN_LEVEL : settings.auditing.logMinLevel;
-    settings.auditing.logUsesJSON = ( process.env.TI_AUDITING_LOG_USES_JSON !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_USES_JSON ) : settings.auditing.logUsesJSON;
-}
-if ( settings.localization ) {
-    settings.localization.labelsPath = ( process.env.TI_LOCALIZATION_LABELS_PATH !== undefined )
-        ? process.env.TI_LOCALIZATION_LABELS_PATH.split( "," ).map( ( p ) => p.trim() ).filter( Boolean )
-        : settings.localization.labelsPath;
-    settings.localization.language = ( process.env.TI_LOCALIZATION_LANGUAGE !== undefined ) ? process.env.TI_LOCALIZATION_LANGUAGE : settings.localization.language;
-}
-if ( settings.memoryCache ) {
-    settings.memoryCache.authKey = ( process.env.TI_MEMORY_CACHE_AUTH_KEY !== undefined ) ? process.env.TI_MEMORY_CACHE_AUTH_KEY : settings.memoryCache.authKey;
-    settings.memoryCache.redisDB = ( process.env.TI_MEMORY_CACHE_REDIS_DB !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_DB ) : settings.memoryCache.redisDB;
-    settings.memoryCache.redisHost = ( process.env.TI_MEMORY_CACHE_REDIS_HOST !== undefined ) ? process.env.TI_MEMORY_CACHE_REDIS_HOST : settings.memoryCache.redisHost;
-    settings.memoryCache.redisPort = ( process.env.TI_MEMORY_CACHE_REDIS_PORT !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_PORT ) : settings.memoryCache.redisPort;
-    settings.memoryCache.retryMaxAttempts = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS ) : settings.memoryCache.retryMaxAttempts;
-    settings.memoryCache.retryMaxInterval = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL ) : settings.memoryCache.retryMaxInterval;
-    settings.memoryCache.user = ( process.env.TI_MEMORY_CACHE_USER !== undefined ) ? process.env.TI_MEMORY_CACHE_USER : settings.memoryCache.user;
-}
-if ( settings.messageExchange ) {
-    settings.messageExchange.securityHashEnabled = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED ) : settings.messageExchange.securityHashEnabled;
-    settings.messageExchange.securityHashKey = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY !== undefined ) ? process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY : settings.messageExchange.securityHashKey;
-    settings.messageExchange.traceLogEnabled = ( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED ) : settings.messageExchange.traceLogEnabled;
-}
-
-// Make sure GCloud is enabled before trying to set it up:
-if ( tools.toBool( process.env.TI_GCLOUD_ENABLED ) === true && settings.gcloudIntegration ) {
-    settings.gcloudIntegration.apiKey = ( process.env.TI_GCLOUD_API_KEY !== undefined ) ? process.env.TI_GCLOUD_API_KEY : settings.gcloudIntegration.apiKey;
-    settings.gcloudIntegration.projectID = ( process.env.TI_GCLOUD_PROJECT_ID !== undefined ) ? process.env.TI_GCLOUD_PROJECT_ID : settings.gcloudIntegration.projectID;
-}
-
-settings.operationMode = process.env.NODE_ENV || settings.operationMode;
-
-// Prevent further modifications to the settings object:
-tools.deepFreeze( settings );
-
-/**
- * A standard getter method for fetching a setting.
- *
- * @method
- * @param {string|TiSetting} setting Specifies either a dot-separated JSON path of the setting, or is a Setting from the settings enum.
- * @param {*} [defaultValue] The default value to be returned if the setting is not found in the current configuration.
- * @returns {*}
- * @public
- */
-module.exports.getSetting = ( setting, defaultValue ) => {
-    return _.get( settings, setting, defaultValue );
+/*
+ * The ti-engine is an open source, free to use—both for personal and commercial projects—framework for the creation of microservice-based solutions using node.js.
+ * Copyright © 2021-2026 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+ * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+ * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
+*/
+
+const _ = require( "lodash" );
+const tools = require( "#tools" );
+
+/**
+ * Enum for listing all system settings.
+ *
+ * @readonly
+ * @enum {string} Keys of this ENUM are strings.
+ * @typedef {string} TiSetting
+ */
+const settingsEnum = tools.enum( {
+    AUDITING_LOG_CONSOLE_ENABLED: [ "auditing.logConsoleEnabled", "logConsoleEnabled", "" ],
+    AUDITING_LOG_DETAILS: [ "auditing.logDetails", "logDetails", "" ],
+    AUDITING_LOG_MIN_LEVEL: [ "auditing.logMinLevel", "logMinLevel", "" ],
+    AUDITING_LOG_USES_JSON: [ "auditing.logUsesJSON", "logUsesJSON", "" ],
+    GCLOUD_API_KEY: [ "gcloudIntegration.apiKey", "apiKey", "" ],
+    GCLOUD_PROJECT_ID: [ "gcloudIntegration.projectID", "projectID", "" ],
+    LOCALIZATION_LABELS_PATH: [ "localization.labelsPath", "labelsPath", "" ],
+    LOCALIZATION_LANGUAGE: [ "localization.language", "language", "" ],
+    MEMORY_CACHE_AUTH_KEY: [ "memoryCache.authKey", "authKey", "" ],
+    MEMORY_CACHE_REDIS_DB: [ "memoryCache.redisDB", "redisDB", "" ],
+    MEMORY_CACHE_REDIS_HOST: [ "memoryCache.redisHost", "redisHost", "" ],
+    MEMORY_CACHE_REDIS_PORT: [ "memoryCache.redisPort", "redisPort", "" ],
+    MEMORY_CACHE_RETRY_MAX_ATTEMPTS: [ "memoryCache.retryMaxAttempts", "retryMaxAttempts", "" ],
+    MEMORY_CACHE_RETRY_MAX_INTERVAL: [ "memoryCache.retryMaxInterval", "retryMaxInterval", "" ],
+    MEMORY_CACHE_USER: [ "memoryCache.user", "user", "" ],
+    MESSAGE_EXCHANGE_QUEUE_PREFIX: [ "messageExchange.messageQueuePrefix", "messageQueuePrefix", "" ],
+    MESSAGE_EXCHANGE_MESSAGE_STORE: [ "messageExchange.messageStore", "messageStore", "" ],
+    MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED: [ "messageExchange.securityHashEnabled", "securityHashEnabled", "" ],
+    MESSAGE_EXCHANGE_SECURITY_HASH_KEY: [ "messageExchange.securityHashKey", "securityHashKey", "" ],
+    MESSAGE_EXCHANGE_TRACE_EXPIRATION_TIME: [ "messageExchange.traceExpirationTime", "traceExpirationTime", "" ],
+    MESSAGE_EXCHANGE_TRACE_LOG_ENABLED: [ "messageExchange.traceLogEnabled", "traceLogEnabled", "" ],
+    MESSAGE_EXCHANGE_TRACE_REPOSITORY: [ "messageExchange.traceRepository", "traceRepository", "" ],
+    SERVICE_EXECUTION_TIMEOUT: [ "serviceConfig.executionTimeout", "executionTimeout", "" ],
+    SERVICE_HEALTH_CHECK_ADDRESS: [ "serviceConfig.healthCheckAddress", "healthCheckAddress", "" ],
+    SERVICE_HEALTH_CHECK_INTERVAL: [ "serviceConfig.healthCheckInterval", "healthCheckInterval", "" ],
+    SERVICE_HEALTH_CHECK_TIMEOUT: [ "serviceConfig.healthCheckTimeout", "healthCheckTimeout", "" ],
+    SERVICE_REGISTRY_ADDRESS: [ "serviceConfig.serviceRegistryAddress", "serviceRegistryAddress", "" ],
+    OPERATION_MODE: [ "operationMode", "operationMode", "" ]
+} );
+module.exports.setting = settingsEnum;
+
+/** @type {SettingsMain} */
+const settings = require( "#settings" );
+
+// Override the remaining settings with ENV variables (if provided):
+if ( settings.auditing ) {
+    settings.auditing.logConsoleEnabled = ( process.env.TI_AUDITING_LOG_CONSOLE_ENABLED !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_CONSOLE_ENABLED ) : settings.auditing.logConsoleEnabled;
+    settings.auditing.logDetails = ( process.env.TI_AUDITING_LOG_DETAILS !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_DETAILS ) : settings.auditing.logDetails;
+    settings.auditing.logMinLevel = ( process.env.TI_AUDITING_LOG_MIN_LEVEL !== undefined ) ? process.env.TI_AUDITING_LOG_MIN_LEVEL : settings.auditing.logMinLevel;
+    settings.auditing.logUsesJSON = ( process.env.TI_AUDITING_LOG_USES_JSON !== undefined ) ? tools.toBool( process.env.TI_AUDITING_LOG_USES_JSON ) : settings.auditing.logUsesJSON;
+}
+if ( settings.localization ) {
+    settings.localization.labelsPath = ( process.env.TI_LOCALIZATION_LABELS_PATH !== undefined )
+        ? process.env.TI_LOCALIZATION_LABELS_PATH.split( "," ).map( ( p ) => p.trim() ).filter( Boolean )
+        : settings.localization.labelsPath;
+    settings.localization.language = ( process.env.TI_LOCALIZATION_LANGUAGE !== undefined ) ? process.env.TI_LOCALIZATION_LANGUAGE : settings.localization.language;
+}
+if ( settings.memoryCache ) {
+    settings.memoryCache.authKey = ( process.env.TI_MEMORY_CACHE_AUTH_KEY !== undefined ) ? process.env.TI_MEMORY_CACHE_AUTH_KEY : settings.memoryCache.authKey;
+    settings.memoryCache.redisDB = ( process.env.TI_MEMORY_CACHE_REDIS_DB !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_DB ) : settings.memoryCache.redisDB;
+    settings.memoryCache.redisHost = ( process.env.TI_MEMORY_CACHE_REDIS_HOST !== undefined ) ? process.env.TI_MEMORY_CACHE_REDIS_HOST : settings.memoryCache.redisHost;
+    settings.memoryCache.redisPort = ( process.env.TI_MEMORY_CACHE_REDIS_PORT !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_REDIS_PORT ) : settings.memoryCache.redisPort;
+    settings.memoryCache.retryMaxAttempts = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS ) : settings.memoryCache.retryMaxAttempts;
+    settings.memoryCache.retryMaxInterval = ( process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL !== undefined ) ? Number( process.env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL ) : settings.memoryCache.retryMaxInterval;
+    settings.memoryCache.user = ( process.env.TI_MEMORY_CACHE_USER !== undefined ) ? process.env.TI_MEMORY_CACHE_USER : settings.memoryCache.user;
+}
+if ( settings.messageExchange ) {
+    settings.messageExchange.securityHashEnabled = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED ) : settings.messageExchange.securityHashEnabled;
+    settings.messageExchange.securityHashKey = ( process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY !== undefined ) ? process.env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY : settings.messageExchange.securityHashKey;
+    settings.messageExchange.traceLogEnabled = ( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED !== undefined ) ? tools.toBool( process.env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED ) : settings.messageExchange.traceLogEnabled;
+}
+
+// Make sure GCloud is enabled before trying to set it up:
+if ( tools.toBool( process.env.TI_GCLOUD_ENABLED ) === true && settings.gcloudIntegration ) {
+    settings.gcloudIntegration.apiKey = ( process.env.TI_GCLOUD_API_KEY !== undefined ) ? process.env.TI_GCLOUD_API_KEY : settings.gcloudIntegration.apiKey;
+    settings.gcloudIntegration.projectID = ( process.env.TI_GCLOUD_PROJECT_ID !== undefined ) ? process.env.TI_GCLOUD_PROJECT_ID : settings.gcloudIntegration.projectID;
+}
+
+settings.operationMode = process.env.NODE_ENV || settings.operationMode;
+
+// Prevent further modifications to the settings object:
+tools.deepFreeze( settings );
+
+/**
+ * A standard getter method for fetching a setting.
+ *
+ * @method
+ * @param {string|TiSetting} setting Specifies either a dot-separated JSON path of the setting, or is a Setting from the settings enum.
+ * @param {*} [defaultValue] The default value to be returned if the setting is not found in the current configuration.
+ * @returns {*}
+ * @public
+ */
+module.exports.getSetting = ( setting, defaultValue ) => {
+    return _.get( settings, setting, defaultValue );
 };

package/utils/exceptions.js

@@ -60,7 +60,8 @@ const exceptionCodeEnum = tools.enum( {
     E_WEB_INVALID_REQUEST_CONTENT_ENCODING: [ 4009, "invalid request content encoding", "The request content encoding is not recognized or not supported." ],
     /** Application exceptions - codes under 5xxx */
     E_APP_RESOURCE_NOT_FOUND: [ 5004, "resource not found", "The requested resource cannot be found. See details for more information." ],
-    E_APP_SERVICE_ERROR: [ 5005, "app service error", "The application service encountered an error. See details for more information." ]
+    E_APP_SERVICE_ERROR: [ 5005, "app service error", "The application service encountered an error. See details for more information." ],
+    E_APP_RESOURCE_ALREADY_EXISTS: [ 5006, "resource already exists", "The resource cannot be created because it already exists. See details for more information." ]
 } );
 module.exports.exceptionCode = exceptionCodeEnum;
 

package/utils/tools.js

@@ -499,6 +499,26 @@ module.exports.decomposeJSON = ( input ) => {
     return decomposed;
 };
 
+/**
+ * Constant-time string comparison. Mirrors the web-framework safe-compare idiom: coerces inputs to
+ * utf8 buffers, short-circuits on length mismatch, and never throws on hostile/non-string input.
+ *
+ * @method
+ * @param {*} a
+ * @param {*} b
+ * @returns {boolean} True only when both inputs coerce to equal-length, byte-identical strings.
+ * @public
+ */
+module.exports.constantTimeEquals = ( a, b ) => {
+    try {
+        const ba = Buffer.from( String( a || "" ), "utf8" );
+        const bb = Buffer.from( String( b || "" ), "utf8" );
+        return ( ba.length !== bb.length ) ? false : crypto.timingSafeEqual( ba, bb );
+    } catch {
+        return false;
+    }
+};
+
 /**
  * Used to create retry policy for the execution of an operation.
  *