kuzzle 2.56.0 → 2.57.0-beta.2

package/dist/lib/api/httpRoutes.d.ts

@@ -1,17 +1,22 @@
-export = routes;
-declare const routes: ({
-    verb: string;
+/**
+ * A native Kuzzle HTTP route, as exposed through `config.http.routes`.
+ *
+ * `url` is not declared in the literals below: it is derived from `path` by the
+ * loop at the end of this file, and kept as a (deprecated) alias for it.
+ */
+interface KuzzleHttpRoute {
+    verb: "get" | "post" | "put" | "patch" | "delete";
     path: string;
     controller: string;
     action: string;
-    deprecated?: undefined;
-} | {
-    verb: string;
-    path: string;
-    controller: string;
-    action: string;
-    deprecated: {
+    /** Set when the route is superseded by another one. */
+    deprecated?: {
         since: string;
         message: string;
     };
-})[];
+    /** Alias of `path`, populated below. */
+    url?: string;
+    openapi?: Record<string, any>;
+}
+declare const routes: KuzzleHttpRoute[];
+export = routes;

package/dist/lib/api/httpRoutes.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,8 +19,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-/* eslint sort-keys: 0 */
-"use strict";
 const routes = [
     // GET (idempotent)
     { verb: "get", path: "/_me", controller: "auth", action: "getCurrentUser" },
@@ -941,12 +940,180 @@ const routes = [
         path: "/users/:userId/api-keys/_create",
         controller: "security",
         action: "createApiKey",
+        openapi: {
+            description: "Creates a new API key for a user. The clear-text token is only ever returned in this response; it cannot be retrieved afterwards. If you are looking to manage your own API keys, use the `auth` controller instead.",
+            parameters: [
+                {
+                    in: "path",
+                    name: "userId",
+                    schema: { type: "string" },
+                    required: true,
+                    description: "User kuid",
+                },
+                {
+                    in: "query",
+                    name: "_id",
+                    schema: { type: "string" },
+                    required: false,
+                    description: "API key unique ID (auto-generated if not provided)",
+                },
+                {
+                    in: "query",
+                    name: "expiresIn",
+                    schema: { type: "integer", default: -1 },
+                    required: false,
+                    description: "Expiration duration in milliseconds (-1 for no expiration)",
+                },
+                {
+                    in: "query",
+                    name: "refresh",
+                    schema: {
+                        type: "string",
+                        enum: ["wait_for", "false"],
+                        default: "wait_for",
+                    },
+                    required: false,
+                    description: "If set to `wait_for`, waits for the API key to be indexed before responding",
+                },
+            ],
+            requestBody: {
+                required: true,
+                content: {
+                    "application/json": {
+                        schema: {
+                            type: "object",
+                            required: ["description"],
+                            properties: {
+                                description: {
+                                    type: "string",
+                                    description: "API key description",
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            responses: {
+                200: {
+                    description: "The created API key, including its clear-text token",
+                    content: {
+                        "application/json": {
+                            schema: {
+                                type: "object",
+                                properties: {
+                                    _id: { type: "string", description: "API key ID" },
+                                    _source: {
+                                        type: "object",
+                                        properties: {
+                                            userId: { type: "string" },
+                                            description: { type: "string" },
+                                            expiresAt: { type: "integer" },
+                                            ttl: { type: "integer" },
+                                            fingerprint: {
+                                                type: "string",
+                                                description: "SHA256 hash of the token",
+                                            },
+                                            token: {
+                                                type: "string",
+                                                description: "Authentication token",
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
     },
     {
         verb: "post",
         path: "/users/:userId/api-keys/_search",
         controller: "security",
         action: "searchApiKeys",
+        openapi: {
+            description: "Searches for a user's API keys. Supports the Elasticsearch Query DSL, or the Koncorde Filters DSL when `lang` is set to `koncorde`. If you are looking to manage your own API keys, use the `auth` controller instead.",
+            parameters: [
+                {
+                    in: "path",
+                    name: "userId",
+                    schema: { type: "string" },
+                    required: true,
+                    description: "User kuid",
+                },
+                {
+                    in: "query",
+                    name: "from",
+                    schema: { type: "integer", default: 0 },
+                    required: false,
+                    description: "Offset of the first result to return",
+                },
+                {
+                    in: "query",
+                    name: "size",
+                    schema: { type: "integer" },
+                    required: false,
+                    description: "Maximum number of API keys to return",
+                },
+                {
+                    in: "query",
+                    name: "lang",
+                    schema: {
+                        type: "string",
+                        enum: ["elasticsearch", "koncorde"],
+                        default: "elasticsearch",
+                    },
+                    required: false,
+                    description: "Query language used in the request body",
+                },
+            ],
+            requestBody: {
+                required: false,
+                content: {
+                    "application/json": {
+                        schema: {
+                            type: "object",
+                            description: "Search query (Elasticsearch Query DSL or Koncorde filters). Leave empty to match all of the user's API keys.",
+                        },
+                    },
+                },
+            },
+            responses: {
+                200: {
+                    description: "Matching API keys",
+                    content: {
+                        "application/json": {
+                            schema: {
+                                type: "object",
+                                properties: {
+                                    hits: {
+                                        type: "array",
+                                        items: {
+                                            type: "object",
+                                            properties: {
+                                                _id: { type: "string" },
+                                                _source: {
+                                                    type: "object",
+                                                    properties: {
+                                                        userId: { type: "string" },
+                                                        description: { type: "string" },
+                                                        expiresAt: { type: "integer" },
+                                                        ttl: { type: "integer" },
+                                                        fingerprint: { type: "string" },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                    total: { type: "integer" },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
     },
     {
         verb: "post",
@@ -1295,6 +1462,109 @@ const routes = [
         path: "/users/:userId/api-keys/:_id",
         controller: "security",
         action: "deleteApiKey",
+        openapi: {
+            description: "Deletes a user API key, identified by its `_id`. If you are looking to manage your own API keys, use the `auth` controller instead.",
+            parameters: [
+                {
+                    in: "path",
+                    name: "userId",
+                    schema: { type: "string" },
+                    required: true,
+                    description: "User kuid",
+                },
+                {
+                    in: "path",
+                    name: "_id",
+                    schema: { type: "string" },
+                    required: true,
+                    description: "API key unique ID",
+                },
+                {
+                    in: "query",
+                    name: "refresh",
+                    schema: {
+                        type: "string",
+                        enum: ["wait_for", "false"],
+                        default: "wait_for",
+                    },
+                    required: false,
+                    description: "If set to `wait_for`, waits for the deletion to be indexed before responding",
+                },
+            ],
+            responses: {
+                200: {
+                    description: "The deleted API key ID",
+                    content: {
+                        "application/json": {
+                            schema: {
+                                type: "object",
+                                properties: {
+                                    _id: { type: "string" },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    {
+        verb: "delete",
+        path: "/users/:userId/api-keys",
+        controller: "security",
+        action: "deleteApiKey",
+        openapi: {
+            description: "Deletes a user API key, identified by its clear-text `key` or its `fingerprint` instead of its `_id`. Exactly one of `key` or `fingerprint` must be provided. If you are looking to manage your own API keys, use the `auth` controller instead.",
+            parameters: [
+                {
+                    in: "path",
+                    name: "userId",
+                    schema: { type: "string" },
+                    required: true,
+                    description: "User kuid",
+                },
+                {
+                    in: "query",
+                    name: "key",
+                    schema: { type: "string" },
+                    required: false,
+                    description: "Clear-text API key to delete",
+                },
+                {
+                    in: "query",
+                    name: "fingerprint",
+                    schema: { type: "string" },
+                    required: false,
+                    description: "SHA256 fingerprint of the API key to delete",
+                },
+                {
+                    in: "query",
+                    name: "refresh",
+                    schema: {
+                        type: "string",
+                        enum: ["wait_for", "false"],
+                        default: "wait_for",
+                    },
+                    required: false,
+                    description: "If set to `wait_for`, waits for the deletion to be indexed before responding",
+                },
+            ],
+            responses: {
+                200: {
+                    description: "The deleted API key ID",
+                    content: {
+                        "application/json": {
+                            schema: {
+                                type: "object",
+                                properties: {
+                                    _id: { type: "string" },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
     },
     {
         verb: "delete",

package/dist/lib/api/openapi/OpenApiManager.d.ts

@@ -1,4 +1,4 @@
-import { OpenApiDefinition } from "../../types/OpenApiDefinition";
+import type { OpenApiDefinition } from "../../types/OpenApiDefinition";
 export declare class OpenApiManager {
     kuzzleDefinition: OpenApiDefinition;
     applicationDefinition: OpenApiDefinition;

package/dist/lib/api/openapi/openApiGenerator.d.ts

@@ -1,4 +1,4 @@
-import { JSONObject } from "kuzzle-sdk";
+import type { JSONObject } from "../../types/JSONObject";
 /**
  * Generates JSON OpenApi object
  *

package/dist/lib/api/rateLimiter.d.ts

@@ -1,8 +1,9 @@
-export = RateLimiter;
+import type { KuzzleRequest } from "./request";
 declare class RateLimiter {
-    loginsPerSecond: number;
-    frame: {};
-    frameResetTimer: NodeJS.Timeout;
+    private readonly loginsPerSecond;
+    private frame;
+    private frameResetTimer;
+    constructor();
     init(): void;
     /**
      * Return a boolean indicating whether a request execution is allowed as per
@@ -14,5 +15,14 @@ declare class RateLimiter {
      * @param  {Request}  request
      * @returns {Boolean}
      */
-    isAllowed(request: Request): boolean;
+    isAllowed(request: KuzzleRequest): Promise<boolean>;
+    /**
+     * The rate limit a user's profiles impose, as a single number: 0 is
+     * unlimited, and one unlimited profile makes the whole set unlimited.
+     *
+     * Extracted from isAllowed(), whose cognitive complexity this loop pushed
+     * past the gate once the null-user branch above was added.
+     */
+    private profilesLimit;
 }
+export = RateLimiter;

package/dist/lib/api/rateLimiter.js

@@ -1,3 +1,4 @@
+"use strict";
 /*
  * Kuzzle, a backend software, self-hostable and ready to use
  * to power modern apps
@@ -18,7 +19,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-"use strict";
 class RateLimiter {
     constructor() {
         this.loginsPerSecond = global.kuzzle.config.limits.loginsPerSecond;
@@ -41,34 +41,62 @@ class RateLimiter {
     async isAllowed(request) {
         const { controller, action } = request.input;
         let count = 0;
-        let limit = -1;
+        // Assigned in both branches below, before the only read at the end.
+        let limit;
         if (controller === "auth" && action === "login") {
-            const cid = request.context.connection.id;
+            // A request context can carry no connection id — internal requests do
+            // not have one. They have always shared a single bucket under the
+            // stringified `null`; keeping that key preserves the limit rather than
+            // quietly lifting it for whoever can reach this without a connection.
+            const cid = request.context.connection.id ?? "null";
             count = this.frame[cid] = (this.frame[cid] || 0) + 1;
             limit = this.loginsPerSecond;
         }
         else {
-            const { _id, profileIds } = request.context.user;
+            const user = request.getUser();
+            // No user resolved means no profile, and a profile's rateLimit is the
+            // only thing this branch reads. Falling through would leave `limit` at
+            // -1 and deny the request, which is not what "unlimited" means.
+            if (user === null) {
+                return true;
+            }
+            // A user resolved from a request has been stored, so it has an id; the
+            // fallback is what makes the frame key readable to the compiler, and it
+            // is the same key an id-less user would have produced before.
+            const { profileIds } = user;
+            const _id = user._id ?? "null";
             // By definition, auth:logout should be unrestricted
             if (_id !== "-1" && controller === "auth" && action === "logout") {
                 return true;
             }
-            const profiles = await global.kuzzle.ask("core:security:profile:mGet", profileIds);
-            for (let i = 0; i < profiles.length; i++) {
-                const { rateLimit = 0 } = profiles[i];
-                if (limit === 0 || rateLimit === 0) {
-                    limit = 0;
-                }
-                else {
-                    limit = Math.max(limit, rateLimit);
-                }
-            }
+            limit = await this.profilesLimit(profileIds);
             if (limit > 0) {
                 count = this.frame[_id] = (this.frame[_id] || 0) + 1;
             }
         }
         return limit === 0 || count <= limit;
     }
+    /**
+     * The rate limit a user's profiles impose, as a single number: 0 is
+     * unlimited, and one unlimited profile makes the whole set unlimited.
+     *
+     * Extracted from isAllowed(), whose cognitive complexity this loop pushed
+     * past the gate once the null-user branch above was added.
+     */
+    async profilesLimit(profileIds) {
+        const profiles = await global.kuzzle.ask("core:security:profile:mGet", profileIds);
+        let limit = -1;
+        for (const profile of profiles) {
+            const { rateLimit = 0 } = profile;
+            if (limit === 0 || rateLimit === 0) {
+                limit = 0;
+            }
+            else {
+                limit = Math.max(limit, rateLimit);
+            }
+        }
+        return limit;
+    }
 }
 module.exports = RateLimiter;
 //# sourceMappingURL=rateLimiter.js.map

package/dist/lib/api/request/kuzzleRequest.d.ts

@@ -1,9 +1,19 @@
-import { JSONObject } from "kuzzle-sdk";
+import type { JSONObject } from "../../types/JSONObject";
 import { RequestInput } from "./requestInput";
 import { RequestResponse } from "./requestResponse";
 import { RequestContext } from "./requestContext";
 import { KuzzleError } from "../../kerror/errors";
-import { Deprecation } from "../../types";
+import type { Deprecation } from "../../types";
+import type { User } from "../../model/security/user";
+declare const _internalId = "internalId\u200B";
+declare const _status = "status\u200B";
+declare const _input = "input\u200B";
+declare const _error = "error\u200B";
+declare const _result = "result\u200B";
+declare const _context = "context\u200B";
+declare const _timestamp = "timestamp\u200B";
+declare const _response = "response\u200B";
+declare const _deprecations = "deprecations\u200B";
 /**
  * The `KuzzleRequest` class represents a request being processed by Kuzzle.
  *
@@ -16,6 +26,15 @@ export declare class KuzzleRequest {
      * Request external ID (specified by "requestId" or random uuid)
      */
     id: string;
+    [_internalId]: string;
+    [_status]: number;
+    [_input]: RequestInput;
+    [_context]: RequestContext;
+    [_error]: KuzzleError | null;
+    [_result]: unknown;
+    [_response]: RequestResponse | null;
+    [_deprecations]: Deprecation[] | undefined;
+    [_timestamp]: number;
     constructor(data: any, options?: any);
     /**
      * Request internal ID
@@ -25,6 +44,13 @@ export declare class KuzzleRequest {
      * Deprecation warnings for the API action
      */
     get deprecations(): Deprecation[] | void;
+    /**
+     * The setter `RequestResponse.deprecations` has always assigned through to
+     * here, and there was no setter to assign to: in a module — which is strict
+     * mode — writing to an accessor-only property throws a TypeError. Nothing in
+     * the tree exercised it, so the throw was never seen.
+     */
+    set deprecations(deprecations: Deprecation[] | undefined);
     /**
      * Request timestamp (in Epoch-micro)
      */
@@ -65,7 +91,7 @@ export declare class KuzzleRequest {
     /**
      * Sets the request result and status
      *
-     * @deprecated Use request.response.configure instead
+     * @deprecated Use `request.response.configure({ result, status, headers, format })`
      *
      * @param result Request result. Will be converted to JSON unless `raw` option is set to `true`
      * @param options Additional options
@@ -87,6 +113,18 @@ export declare class KuzzleRequest {
          */
         raw?: boolean;
     }): void;
+    /**
+     * Sets the result and nothing else, after the checks every result goes
+     * through. What `response.configure({ result })` calls; plugins use that.
+     *
+     * @internal
+     */
+    assignResult(result: unknown): void;
+    /**
+     * @throws {InternalError} if the result is an Error
+     * @throws {api.assert.forbidden_stream} for an HttpStream outside HTTP
+     */
+    private assertResultAllowed;
     /**
      * Add a deprecation for a used component, this can be action/controller/parameters...
      *
@@ -108,12 +146,16 @@ export declare class KuzzleRequest {
      *
      * This can be used to match Koncorde filter rather than the Request object
      * because it has properties defined with invisible unicode characters.
+     *
+     * The `!`s are not claims: each of these may be `null`, as on the request
+     * itself. The copy is typed as v2.56.0 typed it, non-nullable, because
+     * nullable members broke code compiled against that.
      */
     pojo(): {
         context: {
             connection: import("./requestContext").Connection;
-            token: import("../../model/security/token").Token;
-            user: import("../../model/security/user").User;
+            token: import("../../..").KuzzleToken;
+            user: User;
         };
         deprecations: void | Deprecation[];
         error: KuzzleError;
@@ -137,10 +179,17 @@ export declare class KuzzleRequest {
     };
     /**
      * Return the requested controller
+     *
+     * `null` on a request built without one. Declared `string` all the same,
+     * as v2.56.0 declared it: a `string | null` return broke code compiled
+     * against it. `input.controller` is the nullable form.
      */
     getController(): string;
     /**
      * Returns the requested controller's action
+     *
+     * `null` and declared `string` as {@link getController} is;
+     * `input.action` is the nullable form.
      */
     getAction(): string;
     /**
@@ -278,13 +327,15 @@ export declare class KuzzleRequest {
      */
     getArray(name: string, def?: [] | undefined): any[];
     /**
-     * @deprecated do not use, Use getArray instead
-     *
-     * Gets a parameter from a request arguments and checks that it is an array
-     *
-     * If the request argument is a String instead of an array, it will be JSON parsed
-     * and returned if it is a valid JSON array, otherwise it will return the string splitted on `,`.
+     * Gets a parameter from a request arguments as an array, also accepting a
+     * **comma-separated string** — the form the API documents for `ids` on
+     * `document:mGet`, `document:mExists` and `security:mGetUsers`, and the only
+     * form it documents for `server:healthCheck`'s `services`.
      *
+     * An array is returned as is. A string is, over HTTP only, first parsed as a
+     * JSON array — the one way to pass an element that contains a comma — and
+     * otherwise split on `,`, on every protocol. Unlike `getArray`, a single
+     * query-string value (`?ids=a`) is therefore a one-element array.
      *
      * @param name parameter name
      * @param def default value to return if the parameter is not set
@@ -293,6 +344,12 @@ export declare class KuzzleRequest {
      *                                       value provided
      * @throws {api.assert.invalid_type} If the fetched parameter is not an array or a string
      */
+    getArrayOrCsv(name: string, def?: [] | undefined): unknown[];
+    /**
+     * @deprecated Use {@link getArrayOrCsv}, which it is an alias of: same
+     * behaviour, named after what it does. Kept because `KuzzleRequest` is part
+     * of the public plugin API.
+     */
     getArrayLegacy(name: string, def?: [] | undefined): any[];
     /**
      * Gets a parameter from a request arguments and checks that it is an object
@@ -331,12 +388,20 @@ export declare class KuzzleRequest {
     getTimestamp(name: string): number;
     /**
      * Returns the index specified in the request
+     *
+     * With `{ required: false }` and no index, this returns `null`. It is
+     * declared `string` all the same: that is what v2.56.0 declared, and a
+     * `string | null` overload broke code compiled against it — so Kuzzle's own
+     * callers of the optional form annotate the result `string | null`.
      */
     getIndex({ required }?: {
         required?: boolean;
     }): string;
     /**
      * Returns the collection specified in the request
+     *
+     * `null` under the same conditions as {@link getIndex}, and declared
+     * `string` for the same reason.
      */
     getCollection({ required }?: {
         required?: boolean;
@@ -364,6 +429,8 @@ export declare class KuzzleRequest {
      *    - `ifMissing`: method behavior if the ID is missing (default: 'error')
      *    - `generator`: function used to generate an ID (default: 'uuid.v4')
      *
+     * With `ifMissing: 'ignore'` and no ID, this returns `null`. It is declared
+     * `string` all the same, for the reason given on {@link getIndex}.
      */
     getId(options?: {
         ifMissing?: "error" | "generate" | "ignore";
@@ -375,8 +442,11 @@ export declare class KuzzleRequest {
     getKuid(): string | null;
     /**
      * Returns the current user
+     *
+     * `null` when the request carries none. Declared `User`, as v2.56.0
+     * declared it; `context.user` is the nullable form.
      */
-    getUser(): import("../../model/security/user").User;
+    getUser(): User;
     /**
      * Returns the search body query according to the http method
      */
@@ -467,3 +537,4 @@ export declare class KuzzleRequest {
 }
 export declare class Request extends KuzzleRequest {
 }
+export {};