@ti-engine/core 1.3.13 → 1.6.0

package/CHANGELOG.md

@@ -1,6 +1,75 @@
 # ti-engine changelog
 
-This document will contain 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.
+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.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
+
+## Version 1.4.0
+
+* feat(redis integration): implement support for `JSON.MERGE` and `JSON.MGET` commands
+* feat(cache): add `editJSON` method
+* feat(cache): implement consistent RedisJSON path handling and uniform error wrapping
+* feat(exceptions): add new standardized exception code `E_GEN_NOT_IMPLEMENTED` to use for cases where a feature is not yet implemented
+* feat(exceptions): add new optional, flexible parameter `httpCode` to the `raise` method
+* refactor(exceptions)!: rename the exception class from `Exception` to `TiException` in all referred places
+* refactor(definitions): move all object definitions to a new `definitions.types.js` file
+* refactor(gcloud integration)!: remove file `gcloud-integration.js` and all related functionality (as it was obsolete and a security vulnerability)
+* fix(cache): fix a bug where RedisJSON methods would return `E_GEN_FEATURE_UNSUPPORTED` error while discarding the details of that error
+* fix(config): fix the ENV `TI_LOCALIZATION_LABELS_PATH` to properly support multiple paths to label files
+* build(deps): update `@dotenvx/dotenvx` from ^1.52.0 to ^1.54.1
+* build(deps): update `ioredis` from ^5.9.2 to ^5.10.0
+* build(deps)!: remove `@google-cloud/error-reporting`
+
+## Version 1.3.14
+
+* build(deps): update `@dotenvx/dotenvx` from ^1.51.1 to ^1.52.0
+* build(deps): update `blake2` from ^5.0.0 to ^5.0.1
+* build(deps): update `ioredis` from ^5.8.2 to ^5.9.2
+* build(deps): update `lodash` from ^4.17.21 to ^4.17.23
+* build(engines): update Node.js requirement from >=18.0.0 to >=20.0.0
 
 ## Version 1.3.13
 

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/localization/labels.json

@@ -34,6 +34,9 @@
       "1009": {
         "en": "Attempt to override a protected or private method or property detected."
       },
+      "1010": {
+        "en": "The requested functionality is not yet implemented."
+      },
       "2000": {
         "en": "Invalid authorization token provided."
       },
@@ -108,6 +111,12 @@
       },
       "4009": {
         "en": "The request content encoding is not recognized or not supported."
+      },
+      "5004": {
+        "en": "The requested resource cannot be found. See details for more information."
+      },
+      "5005": {
+        "en": "The application service encountered an error. See details for more information."
       }
     }
   }

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/auditing.js

@@ -1,6 +1,6 @@
 /*
  * 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-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * 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/>.
@@ -11,20 +11,8 @@ const _ = require( "lodash" );
 const tools = require( "#tools" );
 const logger = require( "#logger" );
 const config = require( "#config" );
-const gcloud = require( "#gcloud-integration" );
 const ServiceInstance = require( "#service-instance" );
 
-/**
- * @typedef {Object} TiLogEntry
- * @property {string} _id Unique identifier that can be used to identify the document in a NoSQL database.
- * @property {TiLogSeverity} severity The log severity level.
- * @property {string} thread The categorization of the log message.
- * @property {string} reporter
- * @property {string} message The actual log message.
- * @property {number} timestamp The timestamp of the log entry in UTC time.
- * @property {Object} data Additional JSON data to go with the message.
- */
-
 /**
  * Used to create and/or return an Auditing System singleton instance.
  *
@@ -72,11 +60,6 @@ class Auditing {
                 if ( config.getSetting( config.setting.AUDITING_LOG_CONSOLE_ENABLED ) === true && console ) {
                     Auditing.#logToConsole( logEntry );
                 }
-
-                // If this is an actual error, then send it to GCloud error reporting system as well:
-                if ( logEntry.severity >= logger.logSeverity.WARNING && data instanceof Error && gcloud.isEnabled() ) {
-                    gcloud.reportError( data );
-                }
             }
         } catch {
             // do nothing here for now...

package/components/connection-observer.js

@@ -1,6 +1,6 @@
 /*
  * 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-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * 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/>.
@@ -19,7 +19,7 @@ class ConnectionObserver {
 
     /**
      * @constructor
-     * @throws {Exception.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
      */
     constructor() {
         // make sure this abstract class cannot be instantiated:

package/components/definitions.types.js

@@ -0,0 +1,248 @@
+/*
+ * 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/>.
+*/
+
+// Configuration Definitions:
+
+/**
+ * @typedef {string} EnvironmentVariable
+ */
+
+/**
+ * @typedef {NodeJS.Process} Environment
+ * @property {ProcessEnv} env
+ * @property {EnvironmentVariable} env.TI_GCLOUD_API_KEY
+ * @property {EnvironmentVariable} env.TI_GCLOUD_ENABLED
+ * @property {EnvironmentVariable} env.TI_GCLOUD_PROJECT_ID
+ * @property {EnvironmentVariable} env.TI_INSTANCE_CLASS
+ * @property {EnvironmentVariable} env.TI_INSTANCE_CONFIG
+ * @property {EnvironmentVariable} env.TI_INSTANCE_ID
+ * @property {EnvironmentVariable} env.TI_INSTANCE_NAME
+ * @property {EnvironmentVariable} env.TI_AUDITING_LOG_CONSOLE_ENABLED
+ * @property {EnvironmentVariable} env.TI_AUDITING_LOG_DETAILS
+ * @property {EnvironmentVariable} env.TI_AUDITING_LOG_MIN_LEVEL
+ * @property {EnvironmentVariable} env.TI_AUDITING_LOG_USES_JSON
+ * @property {EnvironmentVariable} env.TI_LOCALIZATION_LABELS_PATH
+ * @property {EnvironmentVariable} env.TI_LOCALIZATION_LANGUAGE
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_AUTH_KEY
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_DB
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_HOST
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_REDIS_PORT
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_RETRY_MAX_ATTEMPTS
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_RETRY_MAX_INTERVAL
+ * @property {EnvironmentVariable} env.TI_MEMORY_CACHE_USER
+ * @property {EnvironmentVariable} env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_ENABLED
+ * @property {EnvironmentVariable} env.TI_MESSAGE_EXCHANGE_SECURITY_HASH_KEY
+ * @property {EnvironmentVariable} env.TI_MESSAGE_EXCHANGE_TRACE_LOG_ENABLED
+ */
+
+/**
+ * @typedef {Object} SettingsMain
+ * @property {SettingsAuditing} auditing
+ * @property {SettingsGcloudIntegration} gcloudIntegration
+ * @property {SettingsLocalization} localization
+ * @property {SettingsMemoryCache} memoryCache
+ * @property {SettingsMessageExchange} messageExchange
+ * @property {SettingsServiceConfig} serviceConfig
+ * @property {string} operationMode
+ */
+
+/**
+ * @typedef {Object} SettingsAuditing
+ * @property {boolean} logConsoleEnabled
+ * @property {boolean} logDetails
+ * @property {TiLogSeverity} logMinLevel
+ * @property {boolean} logUsesJSON
+ */
+
+/**
+ * @typedef {Object} SettingsGcloudIntegration
+ * @property {string} apiKey
+ * @property {string} projectID
+ */
+
+/**
+ * @typedef {Object} SettingsLocalization
+ * @property {Array<string>} labelsPath
+ * @property {TiLocalizationLanguage} language
+ */
+
+/**
+ * @typedef {Object} SettingsMemoryCache
+ * @property {string} authKey
+ * @property {number} redisDB
+ * @property {string} redisHost
+ * @property {number} redisPort
+ * @property {number} retryMaxAttempts
+ * @property {number} retryMaxInterval
+ * @property {string} user
+ */
+
+/**
+ * @typedef {Object} SettingsMessageExchange
+ * @property {string} messageQueuePrefix
+ * @property {string} messageStore
+ * @property {boolean} securityHashEnabled
+ * @property {string} securityHashKey
+ * @property {number} traceExpirationTime
+ * @property {boolean} traceLogEnabled
+ * @property {string} traceRepository
+ */
+
+/**
+ * @typedef {Object} SettingsServiceConfig
+ * @property {number} executionTimeout
+ * @property {string} healthCheckAddress
+ * @property {CronString} healthCheckInterval
+ * @property {number} healthCheckTimeout
+ * @property {string} serviceRegistryAddress
+ */
+
+// Utility Definitions:
+
+/**
+ * @typedef {string} CronString
+ */
+
+/**
+ * @typedef {Object} TiEnumValue
+ * @property {number|string} value
+ * @property {string} name
+ * @property {string} [description]
+ */
+
+/**
+ * @typedef {Object} TiEnum
+ * @property {Object.<number|string,TiEnumValue>} properties
+ * @property {function( (number|string), [string] ): (string|undefined)} name
+ * @property {function( (number|string), [string] ): (string|undefined)} description
+ * @property {function( (number|string) ): boolean} contains
+ */
+
+/**
+ * @typedef {Object} TiLogEntry
+ * @property {string} _id Unique identifier that can be used to identify the document in a NoSQL database.
+ * @property {TiLogSeverity} severity The log severity level.
+ * @property {string} thread The categorization of the log message.
+ * @property {string} reporter
+ * @property {string} message The actual log message.
+ * @property {number} timestamp The timestamp of the log entry in UTC time.
+ * @property {Object} data Additional JSON data to go with the message.
+ */
+
+/**
+ * @typedef {Object} TiTraceEntry
+ * @property {string} chainID
+ * @property {string} dispatchEvent
+ * @property {string} fromAddress
+ * @property {string} messageID
+ * @property {Object} messageSnapshot
+ * @property {string} messageState
+ * @property {string} messageType
+ * @property {string} toAddress
+ * @property {string} traceID
+ * @property {number} traceTimestamp
+ */
+
+/**
+ * The key of this object is the language code, and the value is the textual representation of the label.
+ *
+ * @typedef {Object<TiLocalizationLanguage, string>} TiLocalizedLabel
+ */
+
+/**
+ * A nested labels tree where intermediate nodes are objects and leaf nodes are language-to-text maps.
+ *
+ * @typedef {Object<string, TiLocalizedLabel | TiLabelsTree>} TiLabelsTree
+ */
+
+// Service Bus Definitions:
+
+/**
+ * @typedef {Object} ServiceAddress
+ * @property {string} serviceAlias A valid service alias.
+ * @property {string} serviceDomainName A valid service domain name.
+ * @property {number|undefined} serviceVersion Optional service version. If not provided, the latest version will be assumed as a target.
+ */
+
+/**
+ * @typedef {Object} ServiceExecContext
+ * @property {string|undefined} authToken A valid authentication token that initialized the service call (if applicable).
+ * @property {ServiceCallPredecessor|undefined} previousServiceCall The previous service call in the execution chain (if such exists).
+ */
+
+/**
+ * @typedef {Message} ServiceCallPredecessor
+ * @property {string} predecessor The {@link Message.messageID} of the predecessor in the service call tree.
+ * @property {ServiceAddress} serviceAddress The address of the service that has to process the service call.
+ * @property {Object|undefined} serviceParams The named params to be provided to the API service.
+ */
+
+/**
+ * @typedef {ServiceCallPredecessor} ServiceCall
+ * @property {string} authToken A valid authentication token that initialized the service call.
+ * @property {number} createdOn A unix timestamp taken at creation time of the service call.
+ * @property {number} executionTime The total execution time of this service call in milliseconds.
+ * @property {Object|undefined} exception If there was exception during the service call processing, it will be set here. Otherwise, it will be 'undefined'.
+ * @property {number|undefined} finishedOn A unix timestamp taken at finish time of the service call.
+ * @property {boolean} isCompleted Flag to indicate if this service call has been completed.
+ * @property {boolean|undefined} isSuccessful A flag indicating if this service call can be considered successful or not. Will be 'undefined' until the service call is processed.
+ * @property {string[]} successors The service call IDs of the successors in the service call tree.
+ */
+
+/**
+ * @typedef {Object} ServiceCallResult
+ * @property {TiException|undefined} exception If there was exception during the service call processing, it will be set here. Otherwise, it will be 'undefined'.
+ * @property {boolean} isSuccessful A flag indicating if this service call can be considered successful or not.
+ * @property {Object|string|undefined} payload The payload containing the results from the service call processing. If a string, it is ID of the payload in the memory cache instead.
+ */
+
+/**
+ * @typedef {Object} ServiceDefinition
+ * @property {string} serviceAlias Service alias.
+ * @property {string} serviceFile The JS file containing the service itself. This has to be exposed via package.json import structure!
+ * @property {number} [serviceVersion] Service version.
+ */
+
+/**
+ * @typedef {Object.<string, ServiceInterfaceVersion>} ServiceInterface
+ */
+
+/**
+ * @typedef {Object.<number, ServiceHandlerMethod>} ServiceInterfaceVersion
+ */
+
+/**
+ * @typedef {Object} ServiceConfiguration
+ * @property {ServiceDefinition[]} [services] A list of service definitions to be registered with the {@link ServiceProvider}.
+ */
+
+// Message Exchange Definitions:
+
+/**
+ * @typedef {Object} MessageDestination
+ * @property {string|undefined} [instanceID] The instance ID of the message exchange by which the message was received (available after acceptance).
+ * @property {string} route The route to destination for the message. The exact structure will depend on the implementation of the message exchange.
+ */
+
+/**
+ * @typedef {Object} MessageSource
+ * @property {string} instanceID The instance ID of the message exchange from which the service call originated.
+ * @property {string} route The route from source of the message. The exact structure will depend on the implementation of the message exchange.
+ */
+
+/**
+ * @typedef {Object} Message
+ * @property {string} chainID Unique identifier of the message chain if the message is part of one.
+ * @property {number} chainLevel The node level of this message in the message chain tree.
+ * @property {MessageDestination} destination The destination of the message.
+ * @property {string} [hash] Security hash for the message if the mechanism is enabled.
+ * @property {string} messageID Unique message identifier.
+ * @property {Object|string|undefined} payload The message contents to be processed in destination. If a string, it is ID of the payload in the memory cache instead.
+ * Note that if this is not an Object or a string, there is no guarantee that it will be delivered in the same/proper format!
+ * @property {MessageSource} source The source of the message.
+ */

package/components/exchange/message-dispatcher.js

@@ -1,6 +1,6 @@
 /*
  * 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-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * 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/>.

package/components/exchange/message-exchange.js

@@ -1,6 +1,6 @@
 /*
  * 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-2023 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * 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/>.
@@ -11,34 +11,10 @@ const _ = require( "lodash" );
 const exceptions = require( "#exceptions" );
 const messageTracer = require( "#message-tracer" );
 
-/**
- * @typedef {Object} MessageDestination
- * @property {string|undefined} [instanceID] The instance ID of the message exchange by which the message was received (available after acceptance).
- * @property {string} route The route to destination for the message. Exact structure will depend on the implementation of the message exchange.
- */
-
-/**
- * @typedef {Object} MessageSource
- * @property {string} instanceID The instance ID of the message exchange from which the service call originated.
- * @property {string} route The route from source of the message. Exact structure will depend on the implementation of the message exchange.
- */
-
-/**
- * @typedef {Object} Message
- * @property {string} chainID Unique identifier of the message chain if the message is part of one.
- * @property {number} chainLevel The node level of this message in the message chain tree.
- * @property {MessageDestination} destination The destination of the message.
- * @property {string} [hash] Security hash for the message if the mechanism is enabled.
- * @property {string} messageID Unique message identifier.
- * @property {Object|string|undefined} payload The message contents to be processed in destination. If string it is ID of the payload in the memory cache instead.
- * Note that if this is not an Object or a string, there is no guarantee that it will be delivered in the same/proper format!
- * @property {MessageSource} source The source of the message.
- */
-
 /**
  * An abstract class that defines a message exchange behavior.
  * <br/>
- * NOTE: While this sets the basis frame for the message based communication between microservices, it has to be inherited and
+ * NOTE: While this sets the basis frame for the message-based communication between microservices, it has to be inherited and
  * extended with additional logic that is NOT implemented here. For a working example please see {@link DefaultMessageExchange} class.
  * <br/>
  * NOTE: This class and its children are designed to be used internally by the {@link MessageDispatcher} and its related classes.
@@ -72,7 +48,7 @@ class MessageExchange extends MessageObserver {
      * @constructor
      * @param {string} instanceID The unique identifier of the microservice instance using the message exchange.
      * @param {string} serviceDomainName The domain name of the microservice using the message exchange.
-     * @throws {Exception.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
      */
     constructor( instanceID, serviceDomainName ) {
         super( 9 );
@@ -408,7 +384,7 @@ class MessageExchange extends MessageObserver {
     }
 
     /**
-     * Used only for the purposes of the message tracer.
+     * Used only for the message tracer.
      *
      * @method
      * @param {string} identifier The identifier of the observed connection.
@@ -443,7 +419,7 @@ class MessageExchange extends MessageObserver {
 
     /**
      * Used to send a message request. Override of this method assumes that the message itself contains enough
-     * information to determine the send destination.
+     * information to determine the sending destination.
      *
      * @method
      * @param {Message} message The message request to send.
@@ -457,7 +433,7 @@ class MessageExchange extends MessageObserver {
 
     /**
      * Used to send a message response. Override of this method assumes that the message itself contains enough
-     * information to determine the send destination.
+     * information to determine the sending destination.
      *
      * @method
      * @param {Message} message The message response to send.

package/components/exchange/message-handler.js

@@ -1,6 +1,6 @@
 /*
  * 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-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * 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/>.
@@ -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/>
@@ -33,7 +36,7 @@ class MessageHandler extends ConnectionObserver {
     /**
      * @constructor
      * @param {string} identifier An identifier for this message handler. Should be unique in the context of the message exchange.
-     * @throws {Exception.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
      */
     constructor( identifier ) {
         super();
@@ -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-memory-cache.js

@@ -1,6 +1,6 @@
 /*
  * 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-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * 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/>.

package/components/exchange/message-observer.js

@@ -1,6 +1,6 @@
 /*
  * 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-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * 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/>.
@@ -27,7 +27,7 @@ class MessageObserver extends ConnectionObserver {
     /**
      * @constructor
      * @param {number} [priority=0] The priority of this observer. Higher values indicate higher priority.
-     * @throws {Exception.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
      */
     constructor( priority = 0 ) {
         super();

package/components/exchange/message-receiver.js

@@ -1,6 +1,6 @@
 /*
  * 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-2025 Boris Kostadinov <kostadinov.boris@gmail.com>
+ * 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/>.
@@ -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.
@@ -28,7 +29,7 @@ class MessageReceiver extends MessageHandler {
      * @constructor
      * @param {string} identifier An identifier for this message handler. Should be unique in the context of the message exchange.
      * @param {string} receiveQueue The queue from which the messages will be received.
-     * @throws {Exception.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
+     * @throws {TiException.E_GEN_ABSTRACT_CLASS_INIT} If this class is instantiated directly.
      */
     constructor( identifier, receiveQueue ) {
         super( identifier );
@@ -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, {