kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/core/plugin/pluginsManager.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,30 +19,77 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
-const assert = require("assert");
-const path = require("path");
-const fs = require("fs");
-const Bluebird = require("bluebird");
-const _ = require("lodash");
-const kerror = require("../../kerror");
-const didYouMean = require("../../util/didYouMean");
-const { Inflector } = require("../../util/Inflector");
-const debug = require("../../util/debug")("kuzzle:plugins");
-const { KuzzleError } = require("../../kerror/errors");
-const { has, get, isPlainObject } = require("../../util/safeObject");
-const { BaseController } = require("../../api/controllers/baseController");
-const Plugin = require("./plugin");
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_assert_1 = __importDefault(require("node:assert"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const bluebird_1 = __importDefault(require("bluebird"));
+const lodash_1 = require("lodash");
+const baseController_1 = require("../../api/controllers/baseController");
+const kerror = __importStar(require("../../kerror"));
+const errors_1 = require("../../kerror/errors");
+const debug_1 = __importDefault(require("../../util/debug"));
+const didYouMean_1 = __importDefault(require("../../util/didYouMean"));
+const Inflector_1 = require("../../util/Inflector");
+const safeObject_1 = require("../../util/safeObject");
+const thrown_1 = require("../../util/thrown");
+const plugin_1 = __importDefault(require("./plugin"));
+const debug = (0, debug_1.default)("kuzzle:plugins");
 const assertionError = kerror.wrap("plugin", "assert");
 const runtimeError = kerror.wrap("plugin", "runtime");
 const strategyError = kerror.wrap("plugin", "strategy");
 const controllerError = kerror.wrap("plugin", "controller");
 // Without those plugins, Kuzzle won't start at all.
-const CORE_PLUGINS = ["kuzzle-plugin-auth-passport-local"];
+const CORE_PLUGINS = new Set(["kuzzle-plugin-auth-passport-local"]);
 /**
- * @class PluginsManager
- * @param {Kuzzle} kuzzle
+ * The `id` of whatever was thrown, when it carries one.
  */
+function idOf(thrown) {
+    if (typeof thrown === "object" &&
+        thrown !== null &&
+        "id" in thrown &&
+        typeof thrown.id === "string") {
+        return thrown.id;
+    }
+    return undefined;
+}
+/**
+ * Whatever was thrown, as the `KuzzleError` the caller is about to forward.
+ * A plugin's own KuzzleError passes through untouched — that is the contract
+ * these two handlers have always honoured.
+ */
+function asKuzzleError(thrown) {
+    if (thrown instanceof errors_1.KuzzleError) {
+        return thrown;
+    }
+    const cause = (0, thrown_1.causeOf)(thrown);
+    return runtimeError.getFrom(cause, "unexpected_error", cause.message);
+}
 class PluginsManager {
     constructor() {
         Reflect.defineProperty(this, "kuzzle", {
@@ -52,8 +100,8 @@ class PluginsManager {
         this.controllers = new Map();
         this.strategies = {};
         this.routes = [];
-        this.pluginsEnabledDir = path.resolve(path.join(global.kuzzle.rootPath, "plugins", "enabled"));
-        this.pluginsAvailableDir = path.resolve(path.join(global.kuzzle.rootPath, "plugins", "available"));
+        this.pluginsEnabledDir = node_path_1.default.resolve(node_path_1.default.join(global.kuzzle.rootPath, "plugins", "enabled"));
+        this.pluginsAvailableDir = node_path_1.default.resolve(node_path_1.default.join(global.kuzzle.rootPath, "plugins", "available"));
         /**
          * @example
          * {
@@ -80,16 +128,53 @@ class PluginsManager {
         this.loadedPlugins = [];
     }
     set application(plugin) {
-        assert(this._plugins.size === 0, "The application plugin can only be set before every other plugins are loaded");
-        assert(plugin.application, 'The application plugin must have the "application" property equals to true');
+        (0, node_assert_1.default)(this._plugins.size === 0, "The application plugin can only be set before every other plugins are loaded");
+        (0, node_assert_1.default)(plugin.application, 'The application plugin must have the "application" property equals to true');
         this._plugins.set(plugin.name, plugin);
     }
     get plugins() {
         return Array.from(this._plugins.values()).filter((plugin) => !plugin.application);
     }
+    /**
+     * The application plugin, once `kuzzle.start` has registered one.
+     *
+     * `undefined` before that, and the shutdown path already read it that way —
+     * `pluginsManager?.application?.instance?.log?.flush?.()` defends against a
+     * start that failed before the assignment. The declared `Plugin` was the
+     * half of that the three eager readers assumed.
+     */
     get application() {
         return Array.from(this._plugins.values()).find((plugin) => plugin.application);
     }
+    /**
+     * The plugin registered under `pluginName`, which is the only thing the
+     * strategy methods below can act on. Pre-Kaaf plugin names may carry upper
+     * case, hence the lowercasing every call site did for itself.
+     *
+     * The three callers dereferenced the map's answer unchecked — a strategy
+     * registered for an unknown plugin read `undefined.initCalled`. The error
+     * is the one `Backend.plugin.get` already raises for the same question.
+     */
+    getPlugin(pluginName) {
+        const plugin = this._plugins.get(pluginName.toLowerCase());
+        if (plugin === undefined) {
+            throw assertionError.get("plugin_not_found", pluginName, (0, didYouMean_1.default)(pluginName, Array.from(this._plugins.keys())));
+        }
+        return plugin;
+    }
+    /**
+     * The strategy registered under `strategyName`. Reading it off the record
+     * and dereferencing straight away is what `getStrategyFields` and
+     * `getStrategyMethod` did; `hasStrategyMethod` is the guard that existed,
+     * and only one of the two call sites used it.
+     */
+    getStrategy(strategyName) {
+        const strategy = this.strategies[strategyName];
+        if (strategy === undefined) {
+            throw strategyError.get("strategy_not_found", strategyName);
+        }
+        return strategy;
+    }
     /**
      * Giving a controller name, tells if exists
      *
@@ -116,7 +201,11 @@ class PluginsManager {
      * @returns {Array}
      */
     getActions(controller) {
-        return Array.from(this.controllers.get(controller)._actions);
+        const registered = this.controllers.get(controller);
+        // An unregistered controller has no actions. Reading `._actions` off the
+        // map's answer raised a TypeError instead, which is what `isAction`
+        // answered for a controller `isController` says does not exist.
+        return registered === undefined ? [] : Array.from(registered._actions);
     }
     /**
      * Returns an array filled with controller names
@@ -167,8 +256,7 @@ class PluginsManager {
         const loadPlugins = [];
         const defaultImports = {};
         for (const plugin of this._plugins.values()) {
-            if (this.config.common.failsafeMode &&
-                !CORE_PLUGINS.includes(plugin.name)) {
+            if (this.config.common.failsafeMode && !CORE_PLUGINS.has(plugin.name)) {
                 this.logger.info(`Failsafe mode activated, skipping plugin "${plugin.name}"`);
                 continue;
             }
@@ -177,9 +265,17 @@ class PluginsManager {
             }
             const { initTimeout } = this.config.common;
             debug('[%s] starting plugin in "%s" mode', plugin.name, plugin.config.privileged ? "privileged" : "standard");
-            const promise = Bluebird.resolve((async () => {
+            const { init } = plugin.instance;
+            // Both loaders — `loadPlugins` here and `Backend.plugin.use` — refuse a
+            // plugin without one, so this is the third statement of the same
+            // precondition rather than a new one. It is the type of `init` on a
+            // user-supplied object that makes it appear.
+            if (!isPluginMethod(init)) {
+                throw assertionError.get("init_not_found", plugin.name);
+            }
+            const promise = bluebird_1.default.resolve((async () => {
                 try {
-                    await plugin.instance.init(plugin.config, plugin.context);
+                    await init.call(plugin.instance, plugin.config, plugin.context);
                 }
                 catch (error) {
                     throw runtimeError.get("failed_init", plugin.name, error);
@@ -188,34 +284,34 @@ class PluginsManager {
                 .timeout(initTimeout, `${plugin.logPrefix} Initialization timed out after ${initTimeout}ms. Try to increase the configuration "plugins.common.initTimeout".`)
                 .then(async () => {
                 plugin.initCalled = true;
-                if (!_.isEmpty(plugin.instance.controllers) &&
-                    !_.isEmpty(plugin.instance.api)) {
+                if (!(0, lodash_1.isEmpty)(plugin.instance.controllers) &&
+                    !(0, lodash_1.isEmpty)(plugin.instance.api)) {
                     throw assertionError.get("duplicated_api_definition");
                 }
-                if (!_.isEmpty(plugin.instance.controllers)) {
+                if (!(0, lodash_1.isEmpty)(plugin.instance.controllers)) {
                     this._initControllers(plugin);
                 }
-                if (!_.isEmpty(plugin.instance.api)) {
+                if (!(0, lodash_1.isEmpty)(plugin.instance.api)) {
                     await this._initApi(plugin);
                 }
-                if (!_.isEmpty(plugin.instance.authenticators)) {
+                if (!(0, lodash_1.isEmpty)(plugin.instance.authenticators)) {
                     this._initAuthenticators(plugin);
                 }
-                if (!_.isEmpty(plugin.instance.strategies)) {
+                if (!(0, lodash_1.isEmpty)(plugin.instance.strategies)) {
                     this._initStrategies(plugin);
                 }
-                if (!_.isEmpty(plugin.instance.hooks)) {
+                if (!(0, lodash_1.isEmpty)(plugin.instance.hooks)) {
                     this._initHooks(plugin);
                 }
-                if (!_.isEmpty(plugin.instance.pipes)) {
+                if (!(0, lodash_1.isEmpty)(plugin.instance.pipes)) {
                     this._initPipes(plugin);
                 }
                 debug("[%s] plugin started", plugin.name);
                 if (!plugin.application) {
                     this.loadedPlugins.push(plugin.name);
                 }
-                if (!_.isEmpty(plugin.instance.imports)) {
-                    _.merge(defaultImports, plugin.instance.imports);
+                if (!(0, lodash_1.isEmpty)(plugin.instance.imports)) {
+                    (0, lodash_1.merge)(defaultImports, plugin.instance.imports);
                 }
                 return null;
             });
@@ -230,7 +326,7 @@ class PluginsManager {
      * @returns {string[]}
      */
     getStrategyFields(strategyName) {
-        return this.strategies[strategyName].strategy.config.fields || [];
+        return this.getStrategy(strategyName).strategy.config.fields || [];
     }
     /**
      * @param {string} strategyName
@@ -238,8 +334,10 @@ class PluginsManager {
      * @returns {boolean}
      */
     hasStrategyMethod(strategyName, methodName) {
-        const strategy = get(this.strategies, strategyName);
-        return strategy && has(strategy.methods, methodName);
+        const strategy = (0, safeObject_1.has)(this.strategies, strategyName)
+            ? this.strategies[strategyName]
+            : undefined;
+        return strategy !== undefined && (0, safeObject_1.has)(strategy.methods, methodName);
     }
     /**
      * @param {string} strategyName
@@ -247,7 +345,7 @@ class PluginsManager {
      * @returns {function}
      */
     getStrategyMethod(strategyName, methodName) {
-        return this.strategies[strategyName].methods[methodName];
+        return this.getStrategy(strategyName).methods[methodName];
     }
     /**
      * Returns the list of registered passport strategies
@@ -266,51 +364,50 @@ class PluginsManager {
      */
     validateStrategy(pluginName, strategyName, strategy) {
         const errorPrefix = `[${pluginName}] Strategy ${strategyName}:`;
-        if (!isPlainObject(strategy)) {
+        if (!(0, safeObject_1.isPlainObject)(strategy)) {
             throw strategyError.get("invalid_description", errorPrefix, strategy);
         }
-        if (!isPlainObject(strategy.methods)) {
+        if (!(0, safeObject_1.isPlainObject)(strategy.methods)) {
             throw strategyError.get("invalid_methods", errorPrefix, strategy.methods);
         }
-        const plugin = this._plugins.get(pluginName.toLowerCase());
+        const plugin = this.getPlugin(pluginName);
         // required methods check
         ["exists", "create", "update", "delete", "validate", "verify"].forEach((methodName) => {
-            if (!_.isString(strategy.methods[methodName])) {
+            if (!(0, lodash_1.isString)(strategy.methods[methodName])) {
                 throw strategyError.get("invalid_method_type", errorPrefix, methodName, strategy.methods[methodName]);
             }
-            if (!_.isFunction(plugin.instance[strategy.methods[methodName]])) {
+            if (!(0, lodash_1.isFunction)(plugin.instance[strategy.methods[methodName]])) {
                 throw strategyError.get("missing_method_function", errorPrefix, strategy.methods[methodName]);
             }
         });
         // optional methods check
         ["getInfo", "getById", "afterRegister"].forEach((name) => {
             const optionalMethodName = strategy.methods[name];
-            if (!_.isNil(optionalMethodName)) {
-                if (!_.isString(optionalMethodName)) {
+            if (!(0, lodash_1.isNil)(optionalMethodName)) {
+                if (!(0, lodash_1.isString)(optionalMethodName)) {
                     throw strategyError.get("invalid_method_type", errorPrefix, name, optionalMethodName);
                 }
-                if (!_.isFunction(plugin.instance[optionalMethodName])) {
+                if (!(0, lodash_1.isFunction)(plugin.instance[optionalMethodName])) {
                     throw strategyError.get("missing_method_function", errorPrefix, optionalMethodName);
                 }
             }
         });
-        if (!isPlainObject(strategy.config)) {
+        if (!(0, safeObject_1.isPlainObject)(strategy.config)) {
             throw strategyError.get("invalid_config", errorPrefix, strategy.config);
         }
         if (typeof strategy.config.authenticator !== "string") {
             throw strategyError.get("invalid_authenticator", errorPrefix, strategy.config.authenticator);
         }
-        else if (!this.authenticators[pluginName] ||
-            !this.authenticators[pluginName][strategy.config.authenticator]) {
+        else if (!this.authenticators[pluginName]?.[strategy.config.authenticator]) {
             throw strategyError.get("unknown_authenticator", errorPrefix, strategy.config.authenticator);
         }
         for (const optionName of ["strategyOptions", "authenticateOptions"]) {
             const options = strategy.config[optionName];
-            if (!_.isNil(options) && !isPlainObject(options)) {
+            if (!(0, lodash_1.isNil)(options) && !(0, safeObject_1.isPlainObject)(options)) {
                 throw strategyError.get("invalid_option", errorPrefix, optionName, options);
             }
         }
-        if (!_.isNil(strategy.config.fields) &&
+        if (!(0, lodash_1.isNil)(strategy.config.fields) &&
             !Array.isArray(strategy.config.fields)) {
             throw strategyError.get("invalid_fields", errorPrefix, strategy.config.fields);
         }
@@ -331,11 +428,19 @@ class PluginsManager {
             ? plugin.config.pipeWarnTime
             : this.config.common.pipeWarnTime;
         const wrapper = (...data) => {
-            const now = warnDelay ? Date.now() : null;
+            const startedAt = warnDelay ? Date.now() : null;
             const callback = data.pop();
+            // The pipe runner always calls a registered pipe with a trailing
+            // callback — the same narrowing `wrapStrategyVerify` makes, and the
+            // same branch that cannot be taken.
+            if (!isPluginMethod(callback)) {
+                return;
+            }
             const cb = (error, result) => {
-                if (warnDelay) {
-                    const elapsed = Date.now() - now;
+                // `startedAt !== null` is `warnDelay` truthy, said in the form that
+                // proves there is a timestamp to subtract.
+                if (startedAt !== null) {
+                    const elapsed = Date.now() - startedAt;
                     if (elapsed > warnDelay) {
                         this.logger.warn(`${plugin.logPrefix} pipe for event '${event}' is slow (${elapsed}ms)`);
                     }
@@ -344,10 +449,7 @@ class PluginsManager {
             };
             try {
                 const pipeResponse = data.length === 0 ? handler(null, cb) : handler(...data, cb);
-                if (typeof pipeResponse === "object" &&
-                    pipeResponse !== null &&
-                    typeof pipeResponse.then === "function" &&
-                    typeof pipeResponse.catch === "function") {
+                if (isThenable(pipeResponse)) {
                     pipeResponse
                         .then((result) => {
                         cb(null, result);
@@ -357,9 +459,7 @@ class PluginsManager {
                 }
             }
             catch (error) {
-                cb(error instanceof KuzzleError
-                    ? error
-                    : runtimeError.getFrom(error, "unexpected_error", error.message));
+                cb(asKuzzleError(error));
             }
         };
         return global.kuzzle.registerPluginPipe(event, wrapper);
@@ -379,8 +479,7 @@ class PluginsManager {
      *                                     registration fails
      */
     registerStrategy(pluginName, strategyName, strategy) {
-        // prior to Kaaf, plugin names can contains upper case
-        const plugin = this._plugins.get(pluginName.toLowerCase());
+        const plugin = this.getPlugin(pluginName);
         // only add the strategy to the strategies object if the init method
         // has not been called
         if (!plugin.initCalled) {
@@ -389,7 +488,7 @@ class PluginsManager {
             return;
         }
         this.validateStrategy(plugin.name, strategyName, strategy);
-        if (has(this.strategies, strategyName)) {
+        if ((0, safeObject_1.has)(this.strategies, strategyName)) {
             this.unregisterStrategy(plugin.name, strategyName);
         }
         const methods = {};
@@ -399,14 +498,11 @@ class PluginsManager {
         for (const methodName of Object.keys(strategy.methods).filter((name) => name !== "verify")) {
             methods[methodName] = async (...args) => {
                 try {
-                    const boundFunction = plugin.instance[strategy.methods[methodName]].bind(plugin.instance);
+                    const boundFunction = bindPluginMethod(plugin.instance, strategy.methods[methodName]);
                     return await boundFunction(...args);
                 }
                 catch (error) {
-                    if (error instanceof KuzzleError) {
-                        throw error;
-                    }
-                    throw runtimeError.getFrom(error, "unexpected_error", error.message);
+                    throw asKuzzleError(error);
                 }
             };
         }
@@ -414,7 +510,7 @@ class PluginsManager {
             ...strategy.config.strategyOptions,
             passReqToCallback: true,
         };
-        const verifyAdapter = this.wrapStrategyVerify(plugin.logPrefix, strategyName, plugin.instance[strategy.methods.verify].bind(plugin.instance));
+        const verifyAdapter = this.wrapStrategyVerify(plugin.logPrefix, strategyName, bindPluginMethod(plugin.instance, strategy.methods.verify));
         try {
             const Ctor = this.authenticators[plugin.name][strategy.config.authenticator], instance = new Ctor(opts, verifyAdapter);
             this.strategies[strategyName] = { methods, owner: plugin.name, strategy };
@@ -424,7 +520,8 @@ class PluginsManager {
             }
         }
         catch (e) {
-            throw strategyError.getFrom(e, "failed_registration", strategyName, e.message);
+            const cause = (0, thrown_1.causeOf)(e);
+            throw strategyError.getFrom(cause, "failed_registration", strategyName, cause.message);
         }
     }
     /**
@@ -453,90 +550,70 @@ class PluginsManager {
      */
     _initPipes(plugin) {
         const methodsList = getMethods(plugin.instance);
-        for (const [event, fn] of Object.entries(plugin.instance.pipes)) {
+        // `?? {}`: every member of a plugin's object is optional, and `init`
+        // guards each of these loops with an `isEmpty` the compiler cannot read.
+        for (const [event, fn] of Object.entries(plugin.instance.pipes ?? {})) {
             const list = Array.isArray(fn) ? fn : [fn];
             for (const target of list) {
-                if (typeof target !== "function" &&
-                    typeof plugin.instance[target] !== "function") {
-                    const message = typeof target === "string" ? didYouMean(target, methodsList) : "";
-                    throw assertionError.get("invalid_pipe", event, target, message);
-                }
-                let handler = target;
-                if (typeof target === "string") {
-                    // @deprecated - warn about using a string representing an instance method
-                    plugin.printDeprecation("Defining pipe handler using a string is deprecated. Pass a function instead.");
-                    handler = plugin.instance[target].bind(plugin.instance);
-                }
-                // if the function handler is a plugin instance method,
-                // bound the context to the plugin instance
-                if (target.name && typeof plugin.instance[target.name] === "function") {
-                    handler = target.bind(plugin.instance);
-                }
+                const handler = this.resolveEventHandler(plugin, event, target, methodsList, "invalid_pipe", "Defining pipe handler using a string is deprecated. Pass a function instead.");
                 this.registerPipe(plugin, event, handler);
             }
         }
     }
+    /**
+     * Resolves one pipe or hook target — a function, or the name of a plugin
+     * method — into the handler to register.
+     *
+     * Shared by `_initPipes` and `_initHooks`, which carried the same twenty
+     * lines with two words changed. The `.js` → `.ts` rename re-scored both as
+     * new code, so the gate asked for the deduplication the files already wanted.
+     *
+     * @throws {PluginImplementationError} when the target names nothing callable
+     */
+    resolveEventHandler(plugin, event, target, methodsList, errorId, deprecation) {
+        if (typeof target !== "function" &&
+            typeof plugin.instance[target] !== "function") {
+            const message = typeof target === "string" ? (0, didYouMean_1.default)(target, methodsList) : "";
+            throw assertionError.get(errorId, event, target, message);
+        }
+        // @deprecated - warn about using a string representing an instance method
+        if (typeof target === "string") {
+            plugin.printDeprecation(deprecation);
+            return bindPluginMethod(plugin.instance, target);
+        }
+        // if the function handler is a plugin instance method,
+        // bound the context to the plugin instance
+        if (target.name && typeof plugin.instance[target.name] === "function") {
+            return target.bind(plugin.instance);
+        }
+        return target;
+    }
     /**
      * @param {object} plugin
      */
     _initHooks(plugin) {
         const methodsList = getMethods(plugin.instance);
-        for (const [event, fn] of Object.entries(plugin.instance.hooks)) {
+        for (const [event, fn] of Object.entries(plugin.instance.hooks ?? {})) {
             const list = Array.isArray(fn) ? fn : [fn];
             for (const target of list) {
-                if (typeof target !== "function" &&
-                    typeof plugin.instance[target] !== "function") {
-                    const message = typeof target === "string" ? didYouMean(target, methodsList) : "";
-                    throw assertionError.get("invalid_hook", event, target, message);
-                }
                 debug('[%s] register hook on event "%s"', plugin.name, event);
-                let handler = target;
-                // @deprecated - warn about using a string representing an instance method
-                if (typeof target === "string") {
-                    plugin.printDeprecation("Defining hook handler using a string is deprecated. Pass a function instead.");
-                    handler = plugin.instance[target].bind(plugin.instance);
-                }
-                // if the function handler is a plugin instance method,
-                // bound the context to the plugin instance
-                if (target.name && typeof plugin.instance[target.name] === "function") {
-                    handler = target.bind(plugin.instance);
-                }
+                const handler = this.resolveEventHandler(plugin, event, target, methodsList, "invalid_hook", "Defining hook handler using a string is deprecated. Pass a function instead.");
                 global.kuzzle.registerPluginHook(plugin.name, event, handler);
             }
         }
     }
     async _initApi(plugin) {
-        for (const [controller, definition] of Object.entries(plugin.instance.api)) {
+        for (const [controller, definition] of Object.entries(plugin.instance.api ?? {})) {
             debug("[%s][%s] starting api controller registration", plugin.name, controller);
             if (await global.kuzzle.ask("kuzzle:api:funnel:controller:isNative", controller)) {
                 throw assertionError.get("invalid_controller_definition", controller, "Native controllers cannot be overriden");
             }
-            Plugin.checkControllerDefinition(controller, definition);
+            plugin_1.default.checkControllerDefinition(controller, definition);
             for (const [action, actionDefinition] of Object.entries(definition.actions)) {
-                let apiController = this.controllers.get(controller);
-                if (!apiController) {
-                    apiController = new BaseController();
-                    this.controllers.set(controller, apiController);
-                }
-                let handler = actionDefinition.handler;
-                // if the function handler is a plugin instance method,
-                // bind the context to the plugin instance
-                if (handler.name &&
-                    typeof plugin.instance[handler.name] === "function") {
-                    handler = handler.bind(plugin.instance);
-                }
-                apiController._addAction(action, handler);
-                const httpRoutes = actionDefinition.http || [];
-                // Define default HTTP route if none have been provided
-                if (httpRoutes.length === 0) {
-                    httpRoutes.push({
-                        path: `${Inflector.kebabCase(controller)}/${Inflector.kebabCase(action)}`,
-                        verb: "get",
-                    });
-                }
+                const httpRoutes = this.registerApiAction(plugin, controller, action, actionDefinition);
                 for (const httpRoute of httpRoutes) {
                     debug('[%s] binding HTTP route "%s" to controller "%s"', plugin.name, httpRoute.path, controller);
-                    const routePath = httpRoute.path.charAt(0) === "/"
+                    const routePath = httpRoute.path.startsWith("/")
                         ? httpRoute.path
                         : `/_/${httpRoute.path}`;
                     this.routes.push({
@@ -558,39 +635,23 @@ class PluginsManager {
      */
     _initControllers(plugin) {
         // @deprecated - warn about using the obsolete "controllers" object
-        if (!_.isEmpty(plugin.instance.controllers)) {
+        if (!(0, lodash_1.isEmpty)(plugin.instance.controllers)) {
             plugin.printDeprecation('Defining controllers using the "controllers" object is deprecated. You should use the "api" object instead.');
         }
-        for (const controller of Object.keys(plugin.instance.controllers)) {
+        const legacyControllers = plugin.instance.controllers ?? {};
+        for (const controller of Object.keys(legacyControllers)) {
             debug("[%s][%s] starting controller registration", plugin.name, controller);
             const methodsList = getMethods(plugin.instance);
             const controllerName = `${plugin.name}/${controller}`;
-            const definition = plugin.instance.controllers[controller];
+            const definition = legacyControllers[controller];
             const errorControllerPrefix = `Unable to inject controller "${controller}" from plugin "${plugin.name}":`;
-            if (!isPlainObject(definition)) {
+            if (!(0, safeObject_1.isPlainObject)(definition)) {
                 // @todo deprecate all those errors and use plugin.assert.invalid_controller_definition
                 throw controllerError.get("invalid_description", errorControllerPrefix, typeof definition);
             }
             for (const action of Object.keys(definition)) {
                 debug("[%s][%s][%s] starting action controller registration", plugin.name, controller, action);
-                if (typeof definition[action] !== "function" &&
-                    typeof plugin.instance[definition[action]] !== "function") {
-                    const suggestion = typeof definition[action] === "string"
-                        ? didYouMean(definition[action], methodsList)
-                        : "";
-                    throw controllerError.get("invalid_action", errorControllerPrefix, controller, action, suggestion);
-                }
-                let apiController = this.controllers.get(controllerName);
-                if (!apiController) {
-                    apiController = new BaseController();
-                    this.controllers.set(controllerName, apiController);
-                }
-                if (typeof definition[action] === "function") {
-                    apiController._addAction(action, definition[action]);
-                }
-                else {
-                    apiController._addAction(action, plugin.instance[definition[action]].bind(plugin.instance));
-                }
+                this.registerLegacyAction(plugin, definition[action], { action, controller, controllerName, errorControllerPrefix }, methodsList);
             }
         }
         const httpVerbs = [
@@ -603,34 +664,21 @@ class PluginsManager {
             "options",
         ];
         const routeProperties = ["verb", "url", "controller", "action", "path"];
-        const controllerNames = Object.keys(plugin.instance.controllers);
+        const controllerNames = Object.keys(legacyControllers);
         // @deprecated - warn about using the obsolete "routes" object
-        if (!_.isEmpty(plugin.instance.routes)) {
+        if (!(0, lodash_1.isEmpty)(plugin.instance.routes)) {
             plugin.printDeprecation('Defining routes using the "routes" object is deprecated. You should use the "api" object instead.');
         }
         for (const route of plugin.instance.routes || []) {
             const controller = `${plugin.name}/${route.controller}`;
             const errorRoutePrefix = `Unable to inject API route "${JSON.stringify(route)}" from plugin "${plugin.name}":`;
-            for (const key of Object.keys(route)) {
-                if (routeProperties.indexOf(key) === -1) {
-                    throw controllerError.get("unexpected_route_property", errorRoutePrefix, key, didYouMean(key, routeProperties));
-                }
-                if (typeof route[key] !== "string" ||
-                    (route[key].length === 0 && key !== "url")) {
-                    throw controllerError.get("invalid_route_property", errorRoutePrefix, key);
-                }
-            }
-            const apiController = this.controllers.get(controller);
-            if (!apiController) {
-                throw controllerError.get("undefined_controller", errorRoutePrefix, route.controller, didYouMean(route.controller, controllerNames));
-            }
-            if (!apiController._isAction(route.action)) {
-                const actionNames = Array.from(apiController._actions);
-                throw controllerError.get("undefined_action", errorRoutePrefix, route.action, didYouMean(route.action, actionNames));
-            }
-            if (httpVerbs.indexOf(route.verb.toLowerCase()) === -1) {
-                throw controllerError.get("unsupported_verb", errorRoutePrefix, httpVerbs.join(", "), didYouMean(route.verb, httpVerbs));
-            }
+            this.checkLegacyRoute(route, {
+                controller,
+                controllerNames,
+                errorRoutePrefix,
+                httpVerbs,
+                routeProperties,
+            });
             // @deprecated route.url is deprecated
             if (route.url) {
                 plugin.printDeprecation('Usage of "url" property for routes is deprecated. Use "path" instead.');
@@ -655,13 +703,116 @@ class PluginsManager {
             });
         }
     }
+    /**
+     * Registers one action of the `api` object and answers the HTTP routes to
+     * bind for it — the declared ones, or the single default route built from the
+     * controller and action names.
+     *
+     * Lifted verbatim out of `_initApi` for the same gate reason as its siblings.
+     */
+    registerApiAction(plugin, controller, action, actionDefinition) {
+        let apiController = this.controllers.get(controller);
+        if (!apiController) {
+            apiController = new baseController_1.BaseController();
+            this.controllers.set(controller, apiController);
+        }
+        let handler = actionDefinition.handler;
+        // if the function handler is a plugin instance method,
+        // bind the context to the plugin instance
+        if (handler.name && typeof plugin.instance[handler.name] === "function") {
+            handler = handler.bind(plugin.instance);
+        }
+        apiController._addAction(action, handler);
+        const httpRoutes = actionDefinition.http || [];
+        // Define default HTTP route if none have been provided
+        if (httpRoutes.length === 0) {
+            httpRoutes.push({
+                path: `${Inflector_1.Inflector.kebabCase(controller)}/${Inflector_1.Inflector.kebabCase(action)}`,
+                verb: "get",
+            });
+        }
+        return httpRoutes;
+    }
+    /**
+     * Checks one entry of the deprecated `routes` object: its properties, the
+     * controller and action it names, and its HTTP verb.
+     *
+     * Lifted verbatim out of `_initControllers`, second half of the same
+     * gate-driven split as `registerLegacyAction`.
+     *
+     * @throws {PluginImplementationError}
+     */
+    checkLegacyRoute(route, names) {
+        const { controller, controllerNames, errorRoutePrefix, httpVerbs, routeProperties, } = names;
+        for (const key of Object.keys(route)) {
+            if (!routeProperties.includes(key)) {
+                throw controllerError.get("unexpected_route_property", errorRoutePrefix, key, (0, didYouMean_1.default)(key, routeProperties));
+            }
+            if (typeof route[key] !== "string" ||
+                (route[key].length === 0 && key !== "url")) {
+                throw controllerError.get("invalid_route_property", errorRoutePrefix, key);
+            }
+        }
+        const apiController = this.controllers.get(controller);
+        if (!apiController) {
+            throw controllerError.get("undefined_controller", errorRoutePrefix, route.controller, (0, didYouMean_1.default)(route.controller, controllerNames));
+        }
+        if (!apiController._isAction(route.action)) {
+            const actionNames = Array.from(apiController._actions);
+            throw controllerError.get("undefined_action", errorRoutePrefix, route.action, (0, didYouMean_1.default)(route.action, actionNames));
+        }
+        if (!httpVerbs.includes(route.verb.toLowerCase())) {
+            throw controllerError.get("unsupported_verb", errorRoutePrefix, httpVerbs.join(", "), (0, didYouMean_1.default)(route.verb, httpVerbs));
+        }
+    }
+    /**
+     * Registers one action of the pre-Kaaf `controllers` object: a handler given
+     * either as a function or as the name of a plugin method.
+     *
+     * Lifted verbatim out of `_initControllers`, whose cognitive complexity the
+     * `.js` → `.ts` rename re-scored as new code.
+     *
+     * @throws {PluginImplementationError} when the target names nothing callable
+     */
+    registerLegacyAction(plugin, 
+    /**
+     * Unvalidated: it arrives from the plugin's own `controllers` object, which
+     * is `JSONObject`. The first check below is what makes the declared shape
+     * true, and is the reason this parameter may claim it.
+     */
+    target, names, methodsList) {
+        const { action, controller, controllerName, errorControllerPrefix } = names;
+        // Nested rather than one flat condition: what the throw leaves standing
+        // is "a function, or a name that resolves to one", and written this way
+        // that is what the compiler carries down to the two branches below —
+        // where the `null` the previous spelling introduced had to be asserted
+        // away again.
+        if (typeof target !== "function") {
+            if (typeof target !== "string" ||
+                typeof plugin.instance[target] !== "function") {
+                const suggestion = typeof target === "string" ? (0, didYouMean_1.default)(target, methodsList) : "";
+                throw controllerError.get("invalid_action", errorControllerPrefix, controller, action, suggestion);
+            }
+        }
+        let apiController = this.controllers.get(controllerName);
+        if (!apiController) {
+            apiController = new baseController_1.BaseController();
+            this.controllers.set(controllerName, apiController);
+        }
+        if (typeof target === "function") {
+            apiController._addAction(action, target);
+        }
+        else {
+            apiController._addAction(action, bindPluginMethod(plugin.instance, target));
+        }
+    }
     /**
      * @param {object} plugin
      * @throws {PluginImplementationError} If strategies registration fails
      */
     _initStrategies(plugin) {
-        if (!isPlainObject(plugin.instance.strategies) ||
-            _.isEmpty(plugin.instance.strategies)) {
+        if (!(0, safeObject_1.isPlainObject)(plugin.instance.strategies) ||
+            (0, lodash_1.isEmpty)(plugin.instance.strategies)) {
             throw strategyError.get("invalid_definition", plugin.logPrefix);
         }
         for (const name of Object.keys(plugin.instance.strategies)) {
@@ -673,7 +824,7 @@ class PluginsManager {
      * @throws {PluginImplementationError} If strategies registration fails
      */
     _initAuthenticators(plugin) {
-        if (!isPlainObject(plugin.instance.authenticators)) {
+        if (!(0, safeObject_1.isPlainObject)(plugin.instance.authenticators)) {
             throw kerror.get("plugin", "authenticators", "not_an_object", plugin.logPrefix);
         }
         for (const authenticator of Object.keys(plugin.instance.authenticators)) {
@@ -681,7 +832,7 @@ class PluginsManager {
                 throw kerror.get("plugin", "authenticators", "invalid_authenticator", plugin.logPrefix, authenticator);
             }
         }
-        this.authenticators[plugin.name] = Object.assign({}, plugin.instance.authenticators);
+        this.authenticators[plugin.name] = { ...plugin.instance.authenticators };
     }
     /**
      * Load detected plugins in memory
@@ -692,7 +843,7 @@ class PluginsManager {
         const loadedPlugins = new Map();
         // first load plugins from Backend.plugin.use
         for (const [name, { plugin: instance, options }] of Object.entries(plugins)) {
-            const plugin = new Plugin(instance, { name, ...options });
+            const plugin = new plugin_1.default(instance, { name, ...options });
             // the plugin cluster can be loaded in the startup script
             // and we need the manifest
             plugin.manifest = plugin.manifest || options.manifest;
@@ -703,23 +854,26 @@ class PluginsManager {
             loadedPlugins.set(plugin.name, plugin);
         }
         // then try to load plugins from the filesystem
-        if (!fs.existsSync(this.pluginsEnabledDir)) {
+        if (!node_fs_1.default.existsSync(this.pluginsEnabledDir)) {
             return loadedPlugins;
         }
-        let pluginsPath = [];
+        let pluginsPath;
         try {
-            pluginsPath = fs
+            pluginsPath = node_fs_1.default
                 .readdirSync(this.pluginsEnabledDir)
-                .map((name) => path.join(this.pluginsEnabledDir, name))
-                .filter((filePath) => fs.statSync(filePath).isDirectory());
+                .map((name) => node_path_1.default.join(this.pluginsEnabledDir, name))
+                .filter((filePath) => node_fs_1.default.statSync(filePath).isDirectory());
         }
         catch (e) {
-            throw assertionError.get("invalid_plugins_dir", this.pluginsEnabledDir, e.message);
+            throw assertionError.get("invalid_plugins_dir", this.pluginsEnabledDir, (0, thrown_1.causeOf)(e).message);
         }
         debug("loading plugins: %a", pluginsPath);
         for (const relativePluginPath of pluginsPath) {
-            const plugin = Plugin.loadFromDirectory(relativePluginPath);
-            plugin.init(plugin.manifest.raw.name);
+            const plugin = plugin_1.default.loadFromDirectory(relativePluginPath);
+            // `loadFromDirectory` has already read the name out of the manifest —
+            // `manifest.load()` throws `missing_name` rather than leave it unset —
+            // so this is the same string without two nullable dereferences.
+            plugin.init(plugin.name);
             if (loadedPlugins.has(plugin.name)) {
                 throw assertionError.get("name_already_exists", plugin.name);
             }
@@ -738,11 +892,16 @@ class PluginsManager {
     wrapStrategyVerify(pluginName, strategyName, verifyMethod) {
         const prefix = `${pluginName} Strategy ${strategyName}:`;
         return async (...args) => {
-            const callback = args[args.length - 1];
+            const callback = args.at(-1);
+            // passport always calls the adapter with a trailing callback; the
+            // narrowing is what lets it be invoked, and the branch cannot be taken.
+            if (!isPluginMethod(callback)) {
+                return;
+            }
             const ret = verifyMethod(...args.slice(0, -1));
             // catching plugins returning non-thenable content
             // @todo - with async/await we might consider allowing non-promise results
-            if (!ret || !_.isFunction(ret.then)) {
+            if (!hasThen(ret)) {
                 callback(strategyError.get("invalid_verify_return", prefix, ret));
                 return;
             }
@@ -754,63 +913,141 @@ class PluginsManager {
                 callback(e);
                 return;
             }
-            if (result === false) {
-                callback(null, result, { message: null });
-                return;
-            }
-            if (!isPlainObject(result)) {
-                callback(strategyError.get("invalid_verify_resolve", prefix));
-                return;
-            }
-            if (result.kuid !== null && result.kuid !== undefined) {
-                if (typeof result.kuid === "string") {
-                    try {
-                        const user = await global.kuzzle.ask("core:security:user:get", result.kuid);
-                        callback(null, user);
-                    }
-                    catch (e) {
-                        if (e.id === "security.user.not_found") {
-                            callback(strategyError.get("unknown_kuid", prefix));
-                        }
-                        else {
-                            callback(e);
-                        }
-                    }
-                    return;
-                }
-                callback(strategyError.get("invalid_kuid", prefix, typeof result.kuid));
-                return;
-            }
-            let message;
-            if (result.message && typeof result.message === "string") {
-                message = result.message;
-            }
-            else {
-                message = `Unable to log in using the strategy "${strategyName}"`;
-            }
-            callback(null, false, { message });
+            await resolveVerifiedUser(result, prefix, strategyName, callback);
         };
     }
 }
 /**
- * Test if the provided argument is a constructor or not
+ * Turns what a strategy's `verify` resolved into the passport callback call it
+ * stands for: the authenticated user, an explicit refusal, or an error.
  *
- * @param  {*} arg
- * @returns {Boolean}
+ * Lifted verbatim out of `wrapStrategyVerify`, whose cognitive complexity the
+ * `.js` → `.ts` rename re-scored as new code.
  */
+async function resolveVerifiedUser(result, prefix, strategyName, callback) {
+    if (result === false) {
+        callback(null, result, { message: null });
+        return;
+    }
+    if (!(0, safeObject_1.isPlainObject)(result)) {
+        callback(strategyError.get("invalid_verify_resolve", prefix));
+        return;
+    }
+    if (result.kuid !== null && result.kuid !== undefined) {
+        await resolveKuid(result.kuid, prefix, callback);
+        return;
+    }
+    const message = typeof result.message === "string" && result.message
+        ? result.message
+        : `Unable to log in using the strategy "${strategyName}"`;
+    callback(null, false, { message });
+}
+/**
+ * Loads the user a strategy named by `kuid` and hands it to the passport
+ * callback, turning a missing user into the dedicated `unknown_kuid` error.
+ *
+ * Split out of `resolveVerifiedUser` to keep both under the cognitive
+ * complexity ceiling the `.js` → `.ts` rename re-scores as new code.
+ */
+async function resolveKuid(kuid, prefix, callback) {
+    if (typeof kuid !== "string") {
+        callback(strategyError.get("invalid_kuid", prefix, typeof kuid));
+        return;
+    }
+    try {
+        const user = await global.kuzzle.ask("core:security:user:get", kuid);
+        callback(null, user);
+    }
+    catch (e) {
+        // Duck-typed, as it always was: `core:security:user:get` rejects with a
+        // KuzzleError, but the id is all this branch reads and narrowing to the
+        // class would change which errors it recognises.
+        if (idOf(e) === "security.user.not_found") {
+            callback(strategyError.get("unknown_kuid", prefix));
+        }
+        else {
+            callback(e);
+        }
+    }
+}
+/**
+ * Resolves a handler a plugin referenced by name and binds it to the instance.
+ *
+ * `plugin.instance[name]` is `unknown` — a plugin may expose anything — so the
+ * `typeof` check is what makes the result callable. Every call site had already
+ * made that check; this is the same one, in the place that needs it.
+ *
+ * The name resolving to nothing callable is unreachable — all four call sites
+ * establish it first — and the previous annotation said so by answering
+ * `undefined`, deferring the choice to the day this file had to pass strict
+ * (TD-54, #2757). That is this slice: the branch throws, so
+ * the three callers that would each have had to guard a value that cannot
+ * exist do not, and the one thing that could produce it — a plugin whose
+ * member stopped being a function between the check and the bind — says so
+ * instead of returning something uncallable.
+ */
+function bindPluginMethod(instance, name) {
+    const method = instance[name];
+    if (!isPluginMethod(method)) {
+        throw runtimeError.get("unexpected_error", `plugin member "${name}" is not a function`);
+    }
+    return method.bind(instance);
+}
+/**
+ * A declared narrowing from `unknown` to "callable", the same shape
+ * `safeObject.isPlainObject` has. A predicate rather than an assertion: it is
+ * what lets a plugin's member — `unknown` by construction — be invoked without
+ * an `as`, which TD-43's `casts` ratchet now prices.
+ */
+function isPluginMethod(value) {
+    return typeof value === "function";
+}
+/**
+ * The duck-typed promise check `registerPipe` has always made: a plugin's pipe
+ * may answer a promise, a value, or nothing, and only the first is awaited.
+ * A guard rather than an inline `typeof` chain so the branch narrows.
+ *
+ * `Promise` rather than `Bluebird`: nothing here proves the plugin returned a
+ * Bluebird, and `then`/`catch` — which is exactly what the guard tests and what
+ * `registerPipe` calls — is all of `Promise` the callers need (TD-56, #2759).
+ */
+function isThenable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "then" in value &&
+        typeof value.then === "function" &&
+        "catch" in value &&
+        typeof value.catch === "function");
+}
+/**
+ * What `wrapStrategyVerify` has always accepted from a strategy's `verify`:
+ * anything with a callable `then`, which is all `await` needs. Looser than
+ * `isThenable` on purpose — that one also requires `catch`, because
+ * `registerPipe` calls it; reusing it here (#2748) had started rejecting the
+ * `then`-only thenables v2.56.0 awaited.
+ */
+function hasThen(value) {
+    return ((typeof value === "object" || typeof value === "function") &&
+        value !== null &&
+        "then" in value &&
+        typeof value.then === "function");
+}
 function isConstructor(arg) {
+    if (typeof arg !== "function") {
+        return false;
+    }
     try {
         Reflect.construct(Object, [], arg);
     }
-    catch (e) {
+    catch {
         return false;
     }
     return true;
 }
 function getMethods(object) {
     const prototype = Object.getPrototypeOf(object);
-    const instanceMethods = Object.getOwnPropertyNames(prototype).filter((method) => ["init", "constructor"].indexOf(method) === -1);
-    const objectMethods = Object.getOwnPropertyNames(object).filter((key) => typeof object[key] === "function");
+    const instanceMethods = Object.getOwnPropertyNames(prototype).filter((method) => !["init", "constructor"].includes(method));
+    const objectMethods = Object.getOwnPropertyNames(object).filter((key) => typeof Reflect.get(object, key) === "function");
     return [...instanceMethods, ...objectMethods];
 }
 module.exports = PluginsManager;