@rapidrest/core 1.15.0 → 2.0.0

package/dist/types/JWTUtils.d.ts

@@ -122,30 +122,48 @@ export interface JWTUtilsConfig {
  * @author Jean-Philippe Steinmetz <rapidrests@gmail.com>
  */
 export declare class JWTUtils {
-    private static _parsedKeyCache;
-    /**
-     * Throws if `config.secret` looks like an asymmetric (RSA/EC) key but `config.options.algorithms` was not
-     * explicitly restricted. Signing/verifying with an asymmetric key while leaving `algorithms` unset opens the
-     * door to algorithm-confusion attacks (e.g. an attacker forging an HS256 token using the public key as the
-     * HMAC secret). HMAC secrets (plain strings/buffers that aren't PEM-encoded) are unaffected.
+    /** HMAC algorithm names that must never be permitted alongside a non-HMAC secret (see `assertSafeAlgorithm`). */
+    private static readonly HMAC_ALGORITHMS;
+    /** Maximum size, in bytes, a compressed profile is allowed to decompress to (see `finalizePayload`). Guards
+     * against a decompression bomb - a small compressed payload expanding to consume excessive memory. */
+    private static readonly MAX_DECOMPRESSED_PROFILE_BYTES;
+    /**
+     * Returns `true` if `secret` is a form that is only ever usable as a genuine HMAC secret - a plain
+     * string/Buffer that isn't PEM-encoded, or a `KeyObject` of type `"secret"`. Anything else (a PEM
+     * string/Buffer, an asymmetric `KeyObject`, a `{ key, passphrase }` wrapper, a `GetPublicKeyOrSecret`
+     * callback, a JWK-shaped object, etc.) is *not* considered safe, since it may resolve to a non-secret
+     * (public) value that an attacker could use to forge an HS256/384/512 token.
+     */
+    private static isKnownSafeHmacSecret;
+    /**
+     * Throws unless `config.secret` is a known-safe plain HMAC secret. Any other secret shape is treated
+     * conservatively as potentially asymmetric (fail closed, rather than only matching a fixed allowlist of
+     * asymmetric shapes seen so far) and requires `config.options.algorithms` to be explicitly set to a list
+     * that does not itself include an HMAC algorithm. Without this, signing/verifying with e.g. an RSA key
+     * while leaving `algorithms` unset - or restricting it to `["RS256", "HS256"]` - opens the door to
+     * algorithm-confusion attacks: an attacker holding only the public half of the key pair can forge a token
+     * by signing it with HS256 using that public value as the HMAC secret.
      *
      * @param config The JWT configuration to validate.
      */
     private static assertSafeAlgorithm;
     /**
-     * Generates a new JWT token for the given config and user object. The user object must be a valid RapidREST
-     * user.
-     *
-     * @param config The JWT configuration to use when generating the token.
-     * @param user The user to encode into the token's payload.
+     * Returns the key length, in bytes, required by `algorithm` (e.g. 32 for `aes-256-cbc`, 24 for
+     * `aes-192-cbc`), so the scrypt-derived key `deriveKey`/`deriveKeySync` produce always matches whatever
+     * cipher `passwordOptions.algorithm` actually names, instead of a length hard-coded for one specific
+     * algorithm. Throws a clear error for an algorithm Node's `crypto` module doesn't recognize, rather than
+     * letting `createCipheriv`/`createDecipheriv` fail later with an opaque "Invalid key length".
+     */
+    private static resolveKeyLength;
+    /**
+     * Derives a symmetric encryption key from `password`/`salt` for use with `algorithm`.
      */
     private static deriveKey;
     /**
-     * Generates a new JWT token for the given config and user object. The user object must be a valid RapidREST
-     * user.
-     *
-     * @param config The JWT configuration to use when generating the token.
-     * @param user The user to encode into the token's payload.
+     * Synchronous counterpart to `deriveKey()`. **Blocks the event loop** for the duration of the scrypt
+     * derivation (deliberately CPU-expensive, typically tens of milliseconds) - `createTokenSync`/
+     * `decodeTokenSync` should therefore be avoided on a request-handling path when password-based payload
+     * encryption is configured; prefer `createToken`/`decodeToken` there.
      */
     private static deriveKeySync;
     /**
@@ -159,13 +177,13 @@ export declare class JWTUtils {
      */
     private static hybridEncrypt;
     /**
-     * Returns `true` if `algorithm` is an AEAD cipher (GCM/CCM/OCB/ChaCha20-Poly1305), which produces an
-     * authentication tag that must be captured on encryption and supplied back on decryption via
-     * `getAuthTag()`/`setAuthTag()`.
-     *
-     * @param algorithm The cipher algorithm name (e.g. `aes-256-gcm`).
+     * Returns the base64-encoded authentication tag for `cipher` if it's an AEAD cipher, otherwise `""`. Rather
+     * than pattern-matching the algorithm name (which only recognizes a fixed list of known AEAD naming
+     * conventions), this asks the cipher itself via `getAuthTag()`, which throws for any non-AEAD cipher - so
+     * any AEAD cipher/alias supported by the current Node/OpenSSL build is handled correctly, including ones
+     * not known when this was last updated.
      */
-    private static isAEADCipher;
+    private static getAuthTagIfAEAD;
     /**
      * Decrypts data produced by `hybridEncrypt`.
      *
@@ -173,8 +191,34 @@ export declare class JWTUtils {
      * @param encoded The encrypted data, as produced by `hybridEncrypt`.
      */
     private static hybridDecrypt;
+    /**
+     * Builds the signable payload shared by `createToken`/`createTokenSync`: validates `config`/`user`, spreads
+     * `data`, compresses the profile if requested, and - for public-key encryption only, which has no async
+     * dependency - encrypts it. Password-based encryption is left for the caller to finish via
+     * `finishPasswordEncryption()`, since deriving the key is the one step that differs between the sync and
+     * async entry points.
+     */
+    private static preparePayload;
+    /** Finishes password-based payload encryption once `key` has been derived (sync or async). */
+    private static finishPasswordEncryption;
     static createToken(config: JWTUtilsConfig, user: JWTUser, data?: any): Promise<string>;
+    /**
+     * Synchronous counterpart to `createToken()`. **Blocks the event loop** while deriving the encryption key
+     * when password-based payload encryption is configured (see `deriveKeySync`) - prefer `createToken()` on a
+     * request-handling path in that case.
+     */
     static createTokenSync(config: JWTUtilsConfig, user: JWTUser, data?: any): string;
+    /**
+     * Verifies `token` and prepares its payload for `decodeToken`/`decodeTokenSync`: validates the signature/
+     * shape, and - for private-key decryption only, which has no async dependency - decrypts it in place.
+     * Password-based decryption is left for the caller to finish via `finishPasswordDecryption()`, since
+     * deriving the key is the one step that differs between the sync and async entry points.
+     */
+    private static preDecode;
+    /** Finishes password-based payload decryption once `key` has been derived (sync or async). */
+    private static finishPasswordDecryption;
+    /** Decompresses (if applicable) and parses the final payload profile shared by both decode entry points. */
+    private static finalizePayload;
     /**
      * Decodes the given JWT authentication token using the provided configuration. If the token is not valid an
      * error is thrown with the reason. Returns the encoded user object payload upon success.
@@ -185,8 +229,9 @@ export declare class JWTUtils {
      */
     static decodeToken(config: JWTUtilsConfig, token: string): Promise<JWTPayload>;
     /**
-     * Decodes the given JWT authentication token using the provided configuration. If the token is not valid an
-     * error is thrown with the reason. Returns the encoded user object payload upon success.
+     * Synchronous counterpart to `decodeToken()`. **Blocks the event loop** while deriving the decryption key
+     * when password-based payload encryption is configured (see `deriveKeySync`) - prefer `decodeToken()` on a
+     * request-handling path in that case.
      *
      * @param config The JWT configuration to use when validating the token.
      * @param token The JWT token to validate.

package/dist/types/MessagingUtils.d.ts

@@ -57,6 +57,10 @@ export declare class MessagingUtils {
     private _transporter;
     /** Cache of compiled Handlebars delegates keyed by "<templateName>:<field>". */
     private _compiledTemplates;
+    /** Source string each `_compiledTemplates` entry was compiled from, keyed the same way. Lets `loadTemplate()`
+     * detect when an existing field's value has changed (e.g. a live config reload editing a template's subject/
+     * text/html) and recompile, instead of only ever compiling a field once and rendering stale content forever. */
+    private _compiledTemplateSources;
     /** Names of templates already compiled into `_compiledTemplates` for this instance. See `loadTemplate()`. */
     private _loadedTemplates;
     init(): Promise<void>;
@@ -64,7 +68,7 @@ export declare class MessagingUtils {
      * Loads the template with the given name and returns its contents as a string.
      * @param name The name of the template to load.
      */
-    loadTemplate(name: string): Template;
+    loadTemplate(name: string): Promise<Template>;
     /**
      * Sends an email using the given template name and variables.
      * @param templateName The name of the email template to send.

package/dist/types/NotificationsUtils.d.ts

@@ -4,6 +4,20 @@
  * @author Jean-Philippe Steinmetz
  */
 export declare class NotificationUtils {
+    /**
+     * The redis channel `broadcastMessage()` publishes to. Namespaced (rather than a bare `"allusers"`) so it
+     * can never collide with a per-recipient channel `sendMessage()` derives from a caller-supplied uid - a
+     * client-facing "send a message to this uid" feature that passes its recipient straight through to
+     * `sendMessage()` must not be able to choose a uid that lands on the broadcast channel and reach every
+     * subscriber instead of the intended one recipient.
+     */
+    static readonly BROADCAST_CHANNEL = "broadcast:allusers";
+    /**
+     * Prefix applied to every per-recipient channel in `sendMessage()`. Combined with `BROADCAST_CHANNEL`'s own
+     * distinct `"broadcast:"` prefix, this guarantees the two channel namespaces can never overlap regardless of
+     * what uid value a caller supplies.
+     */
+    static readonly USER_CHANNEL_PREFIX = "user:";
     /** The redis client to use for broadcasting messages. */
     private redis;
     /** The logging utility to use. */
@@ -23,6 +37,9 @@ export declare class NotificationUtils {
     /**
      * Broadcasts a given message to all users.
      *
+     * Subscribers must listen on `NotificationUtils.BROADCAST_CHANNEL` (rather than a bare `"allusers"`) to
+     * receive these messages.
+     *
      * @param {any} type The type of message being sent.
      * @param {string} action The action performed on the data (if applicable).
      * @param {string} data The contents of the message to send.
@@ -31,6 +48,11 @@ export declare class NotificationUtils {
     /**
      * Sends a given message to the room or user with the specified uid(s).
      *
+     * Each recipient's channel is `NotificationUtils.USER_CHANNEL_PREFIX + uid` (rather than the bare uid), so
+     * that no caller-supplied uid can collide with `NotificationUtils.BROADCAST_CHANNEL` or any other reserved
+     * channel and be delivered to unintended subscribers. Subscribers must listen on that prefixed channel name
+     * to receive messages sent to their uid.
+     *
      * @param {string} uids The universally unique identifier of the room or user to send the message to.
      * @param {string} type The type of message being sent.
      * @param {string} action The action performed on the data (if applicable).

package/dist/types/ObjectFactory.d.ts

@@ -22,7 +22,10 @@ export declare class ObjectFactory {
     readonly classes: Map<string, any>;
     /** The global application configuration object. */
     protected config: any;
-    /** A map for the unique name to the intance of a particular class type. */
+    /** A map for the unique name to the intance of a particular class type.
+     *
+     * Note that this map is unbounded and only shrinks via an explicit `destroy()` call.
+     */
     readonly instances: Map<string, any>;
     /** The application logging utility. */
     protected logger: any;
@@ -30,6 +33,12 @@ export declare class ObjectFactory {
     private readonly _metadataCache;
     /** Secondary index: className → first registered instance key, for O(1) getInstance() fallback. */
     private readonly _firstByClass;
+    /** Tracks in-flight `initialize()` promises, keyed by registry name, for instances currently completing
+     * async initialization. `newInstance()` registers an instance in `instances` before its (possibly async)
+     * initialization completes, so a concurrent `newInstance()` call for the same name would otherwise find the
+     * entry via the instances-map fast path and receive the not-yet-initialized instance synchronously instead
+     * of waiting. Consulting this map lets that caller await the same in-flight initialization instead. */
+    private readonly _pendingInit;
     constructor(config?: any, logger?: any);
     /** Walks the prototype chain once for `obj` and caches the discovered decorator metadata on the constructor. */
     private _getOrBuildMetadata;
@@ -37,6 +46,11 @@ export declare class ObjectFactory {
      * Destroys the specified objects. If `undefined` is passed in, all objects managed by the factory are destroyed.
      */
     destroy(objs?: any | any[]): Promise<void>;
+    /** Removes `name` from `instances`. If it was the secondary index's "first" entry for its class, promotes
+     * another surviving instance of the same class if one exists, otherwise drops the entry so `getInstance()`
+     * correctly reports no instance is available. Shared by `destroy()` and `newInstance()`'s failed-initialization
+     * cleanup. */
+    private _removeInstance;
     /**
      * Deletes all instantiated objects.
      */
@@ -57,6 +71,16 @@ export declare class ObjectFactory {
      * @returns The list of functions that implements the `@Init` decorator if found, otherwise undefined.
      */
     getInitMethods(obj: any): Function[];
+    /**
+     * Derives the class name/fqn used to index `instances`/`classes` from a class type, fully qualified name
+     * string, or (defensively) a live instance. Shared by `getInstance`, `newInstance` and `register` so the
+     * three can never disagree about which string identifies a given class - a custom `.fqn` (e.g. one assigned
+     * by `ClassLoader`) always takes precedence over the bare `.name`, honored consistently everywhere a class
+     * identity is resolved.
+     *
+     * @param typeOrInstance The class type, fqn string, or instance to derive the name from.
+     */
+    private static classNameOf;
     /**
      * Returns the object instance with the given unique name. Unique names take the form `<ClassName>:<InstanceName>`.
      * It is possible to only specifiy the `<ClassName>`, doing so will automatically look for the `<ClassName>:default`

package/dist/types/ObjectUtils.d.ts

@@ -6,6 +6,10 @@ import { JWTUser } from "./JWTUtils.js";
  * @author Jean-Philippe Steinmetz
  */
 export declare class ObjectUtils {
+    /** Maximum object nesting depth `deleteScopedProps`/`validate` will recurse into with `recurse: true`. Guards
+     * against stack exhaustion from a pathologically deep (but otherwise valid, e.g. attacker-controlled JSON)
+     * object graph - cycle detection alone doesn't bound depth for a non-cyclic but very deep structure. */
+    private static readonly MAX_RECURSE_DEPTH;
     /**
      * Deletes all properties from the given object(s) that the specified user does not have scope to read.
      *

package/dist/types/StringUtils.d.ts

@@ -4,6 +4,14 @@
  * @author Jean-Philippe Steinmetz
  */
 export declare class StringUtils {
+    /**
+     * Escapes all regular expression metacharacters in `str` so it can be safely embedded in a `RegExp` pattern
+     * and matched as a literal string.
+     *
+     * @param {string} str The string to escape.
+     * @returns {string} The escaped string.
+     */
+    static escapeRegExp(str: string): string;
     /**
      * Returns a list of all parameters contained within the string. A parameter is a bracket delimited substring
      * (e.g. /my/{key}/with/{id}).

package/dist/types/TelemetryUtils.d.ts

@@ -89,4 +89,14 @@ export declare class EventUtils {
      * @param callback The function to call when an event is recorded.
      */
     static on(type: string, callback: Function): void;
+    /**
+     * Unregisters a `callback` previously registered via `on()` for the given event `type`. Since `EventUtils` is
+     * a long-lived process-wide singleton, any listener registered dynamically (rather than once at startup) must
+     * eventually be removed via this method or its closure - and anything it captures - is retained for the life
+     * of the process.
+     *
+     * @param type The type of event the callback was registered for.
+     * @param callback The exact function reference passed to `on()`.
+     */
+    static off(type: string, callback: Function): void;
 }

package/dist/types/ValidationUtils.d.ts

@@ -24,7 +24,7 @@ export declare class ValidationUtils {
      */
     static checkEmail(val: string): string;
     /**
-     * Validates that the provided array is not empty.
+     * Validates that the provided array is not empty (nor `null`/`undefined`).
      */
     static checkEmpty(val: Array<any>): Array<any>;
     /**

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./ApiError.js";
 export * from "./AlertUtils.js";
+export * from "./CacheUtils.js";
 export * from "./ClassLoader.js";
 export * from "./decorators/index.js";
 export * from "./FileUtils.js";

package/dist/types/threads/ThreadPool.d.ts

@@ -20,6 +20,13 @@ export interface WorkerOptions {
     allowTs?: boolean;
     /** The path to the worker file. This must be set when using `ThreadWorkerEntry` as the default entry file. */
     worker?: string;
+    /**
+     * The maximum amount of time, in milliseconds, to wait for all worker threads to report readiness before
+     * `start()` rejects. Default is `ThreadPool.START_TIMEOUT_MS`. Guards against a worker whose entry script
+     * hangs during its own setup and never posts online/emits an error, which would otherwise leave the
+     * returned promise hanging forever with no way to detect or recover.
+     */
+    startupTimeoutMs?: number;
 }
 /**
  * The `ThreadPool` class provides an interface for managing a pool of execution threads that can be used for parallel
@@ -51,6 +58,8 @@ export interface WorkerOptions {
 export declare class ThreadPool {
     /** The maximum amount of time, in milliseconds, `stop()` waits for a worker to exit on its own before force-terminating it. */
     private static readonly STOP_GRACE_PERIOD_MS;
+    /** The default maximum amount of time, in milliseconds, `start()` waits for all workers to report readiness before rejecting. Overridable per-call via `WorkerOptions.startupTimeoutMs`. */
+    private static readonly START_TIMEOUT_MS;
     /** The map of event types to a list of callback functions. */
     private callbacks;
     /** The index of the last worker that was assigned work. */
@@ -63,6 +72,10 @@ export declare class ThreadPool {
     readonly workers: Array<Worker>;
     /** Used to indicate that the pool is shutting down. */
     private shutdown;
+    /** Tracks workers whose "exit" event has already fired, so a dead worker left in `workers` (e.g. exited
+     * without `restartOnExit`) is never sent a message via `postMessage()`, which throws synchronously once a
+     * worker has exited. */
+    private exitedWorkers;
     /**
      * The maximum number of threads that can be created by the pool.
      */
@@ -78,6 +91,20 @@ export declare class ThreadPool {
      * @param logger The Winston logger instance to forward all worker thread logs to.
      */
     constructor(max?: number, logger?: any);
+    /**
+     * @param onRestart Invoked with the replacement `Worker` whenever `restartOnExit` recreates the worker for
+     * `idx`. Lets `start()` re-attach its readiness-tracking listeners to the replacement - without this, a
+     * worker that crashes and is restarted before ever reporting ready would leave `start()`'s returned promise
+     * hanging forever, since nothing would be listening for the *replacement's* readiness signal.
+     */
+    /**
+     * Invokes every callback registered for `type` via `on()`, passing `idx` and optional `data`. Centralizes
+     * the "look up listeners, no-op if none registered" dispatch idiom shared by every worker event handler in
+     * `createWorker()`/`stop()` below, so a future change to how listeners are invoked - or a new message type
+     * that needs routing to a given event - only has to be made in one place instead of risking a hand-copied
+     * site being missed (as happened with WorkerMessageType.ERROR previously falling through to "message").
+     */
+    private dispatch;
     private createWorker;
     /**
      * Initializes the thread pool with the initial worker threads and begins execution.
@@ -104,7 +131,9 @@ export declare class ThreadPool {
      */
     send(msg: any): void;
     /**
-     * Sends the provided message to all worker threads in the pool.
+     * Sends the provided message to all worker threads in the pool. Workers that have already exited (e.g.
+     * crashed with no `restartOnExit`) are silently skipped rather than throwing, so one dead worker doesn't
+     * prevent delivery to every worker after it in the array.
      * @param msg The message to send to all workers.
      */
     sendAll(msg: any): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rapidrest/core",
-    "version": "1.15.0",
+    "version": "2.0.0",
     "description": "A collection of common utilities and core functionality for rapidly building RESTful applications.",
     "repository": "https://github.com/rapidrest/core.git",
     "author": "RapidREST <rapidrests@gmail.com>",