1.3.1: Refactor schema extension and permission validation:

Elschnagoo · Elschnagoo · commit 57e1ef9368a6 · 2026-01-17T21:38:29.000+01:00
- Replace legacy `EntitySchemaExtender` with `SPathUtil.extendEntitySchema`.
- Update `permissionValidation` to accept a `ValidationRequest` payload.
- Adjust all imports, interfaces, and test usage accordingly.
- Add `ValidationRequest` type documentation.
- Update Swagger‑Mate dependency to 1.3.2 and bump package version to 1.3.1.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@grandlinex/kernel",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "GrandLineX is an out-of-the-box server framework on top of ExpressJs.",
   "type": "module",
   "exports": {
@@ -47,7 +47,7 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@grandlinex/core": "1.3.1",
-    "@grandlinex/swagger-mate": "1.3.1",
+    "@grandlinex/swagger-mate": "1.3.2",
     "@types/jsonwebtoken": "9.0.10",
     "@types/ms": "2.1.0",
     "body-parser": "2.2.1",
diff --git a/src/classes/BaseAction.ts b/src/classes/BaseAction.ts
@@ -1,9 +1,15 @@
-import { CoreAction, IDataBase } from '@grandlinex/core';
+import {
+  CoreAction,
+  CoreEntity,
+  IDataBase,
+  instanceOfEntity,
+} from '@grandlinex/core';
 import {
   ActionMode,
   ErrorType,
   isErrorType,
   isSwaggerRef,
+  SPathUtil,
   SSchemaEl,
 } from '@grandlinex/swagger-mate';
 import {
@@ -33,7 +39,7 @@ export default abstract class BaseAction<
 
   forceDebug: boolean;
 
-  requestSchema: SSchemaEl | null;
+  requestSchema: SSchemaEl | CoreEntity | string | null;
 
   constructor(chanel: string, module: IBaseKernelModule<K, T, P, C, E>) {
     super(chanel, module);
@@ -47,15 +53,21 @@ export default abstract class BaseAction<
 
   static validateSchema(
     error: ErrorType,
-    schema: SSchemaEl,
+    inputSchema: SSchemaEl | CoreEntity | string,
     key: string,
     field: any,
     required: boolean = true,
   ) {
-    if (isSwaggerRef(schema)) {
+    let schema: SSchemaEl | string;
+    if (instanceOfEntity(inputSchema)) {
+      schema = SPathUtil.schemaFromEntity(inputSchema)!;
+    } else {
+      schema = inputSchema;
+    }
+    if (isSwaggerRef(schema) || typeof schema === 'string') {
       error.field?.push({
         key,
-        message: `Ref schema body validation is not supported yet`,
+        message: `Ref or string schema body validation is not supported yet`,
       });
       return;
     }
@@ -185,6 +197,7 @@ export default abstract class BaseAction<
           body = this.bodyValidation(req);
         }
         if (isErrorType(body)) {
+          this.debug(body);
           res.status(400).send(body);
           return;
         }
@@ -221,6 +234,7 @@ export default abstract class BaseAction<
           body = this.bodyValidation(req);
         }
         if (isErrorType(body)) {
+          this.debug(body);
           res.status(400).send(body);
           return;
         }
@@ -253,6 +267,7 @@ export default abstract class BaseAction<
           body = this.bodyValidation(req);
         }
         if (isErrorType(body)) {
+          this.debug(body);
           res.status(400).send(body);
           return;
         }
diff --git a/src/classes/BaseAuthProvider.ts b/src/classes/BaseAuthProvider.ts
@@ -1,5 +1,6 @@
 import * as jwt from 'jsonwebtoken';
 import { XRequest } from '../lib/express.js';
+import { ValidationRequest } from '../lib/index.js';
 
 export type JwtExtend = {
   username: string;
@@ -20,7 +21,7 @@ export interface IAuthProvider<T extends JwtExtend> {
     requestType: string,
   ): Promise<AuthResult>;
 
-  validateAccess(token: JwtToken<T>, requestType: string): Promise<boolean>;
+  validateAccess(request: ValidationRequest<T>): Promise<boolean>;
 
   bearerTokenValidation(req: XRequest): Promise<JwtToken<T> | number>;
 
@@ -39,10 +40,7 @@ export default abstract class BaseAuthProvider<T extends JwtExtend = JwtExtend>
     requestType: string,
   ): Promise<AuthResult>;
 
-  abstract validateAccess(
-    token: JwtToken<T>,
-    requestType: string,
-  ): Promise<boolean>;
+  abstract validateAccess(request: ValidationRequest<T>): Promise<boolean>;
 
   abstract bearerTokenValidation(req: XRequest): Promise<JwtToken<T> | number>;
 
diff --git a/src/classes/BaseEndpoint.ts b/src/classes/BaseEndpoint.ts
@@ -46,11 +46,7 @@ export default abstract class BaseEndpoint<
 
   protected port: number;
 
-  constructor(
-    chanel: string,
-    module: IBaseKernelModule<any, any, any, any>,
-    port: number,
-  ) {
+  constructor(chanel: string, module: IBaseKernelModule<any>, port: number) {
     super(`endpoint-${chanel}`, module);
     this.port = port;
     this.appServer = express();
@@ -60,7 +56,7 @@ export default abstract class BaseEndpoint<
   }
 
   private setAppHeader() {
-    this.appServer.use((req, res, next) => {
+    this.appServer.use((_, res, next) => {
       res.setHeader('X-Powered-By', 'GrandLineX');
       next();
     });
diff --git a/src/lib/EntitySchemaExtender.ts b/src/lib/EntitySchemaExtender.ts
diff --git a/src/lib/index.ts b/src/lib/index.ts
@@ -16,37 +16,95 @@ import express from 'express';
 import * as jwt from 'jsonwebtoken';
 import { IAuthProvider, JwtExtend, JwtToken } from '../classes/index.js';
 
-import EntitySchemaExtender from './EntitySchemaExtender.js';
-
 import { XActionEvent, XRequest } from './express.js';
 
-export { EntitySchemaExtender };
+/**
+ * Represents a request for validating a JWT token with optional constraints.
+ *
+ * @template T - The shape of the JWT claims, extending {@link JwtExtend}.
+ *
+ * This type includes:
+ * - **token**: the JWT token to validate.
+ * - **requestType**: an array of request type identifiers that the token must satisfy.
+ * - **required** (optional): indicates whether the token is mandatory for the request; if omitted, the token is considered required.
+ */
+export type ValidationRequest<T extends JwtExtend = JwtExtend> = {
+  token: JwtToken<T>;
+  requestType: string[];
+  required?: boolean;
+};
 
 export interface ICClient<T extends JwtExtend = JwtExtend>
   extends ICoreCClient {
+  /**
+   * Assigns the authentication provider responsible for handling authentication operations.
+   *
+   * @param provider The authentication provider to use.
+   * @return True if the provider was set successfully; otherwise, false.
+   */
   setAuthProvider(provider: IAuthProvider<T>): boolean;
 
+  /**
+   * Verifies a JWT access token and returns the decoded payload or an error code.
+   *
+   * @param token - The JWT access token string to verify.
+   * @return A promise that resolves to the decoded token payload of type {@link JwtToken<T>} if verification succeeds, or a numeric error code if verification fails.
+   */
   jwtVerifyAccessToken(token: string): Promise<JwtToken<T> | number>;
 
+  /**
+   * Decodes a JWT access token and returns its payload.
+   *
+   * @param {string} token - The JWT access token to decode.
+   * @returns {jwt.JwtPayload | null} The decoded payload if the token is valid, otherwise null.
+   */
   jwtDecodeAccessToken(token: string): jwt.JwtPayload | null;
 
+  /**
+   * Generates a signed JWT access token.
+   *
+   * @param {JwtToken<T>} data - The payload data for the token.
+   * @param {Record<string, any>} [extend] - Optional additional fields to merge into the token payload.
+   * @param {string|number} [expire] - Optional expiration time for the token, expressed in seconds or as an ISO 8601 duration string.
+   * @return {Promise<string>} A promise that resolves to the generated JWT token string.
+   */
   jwtGenerateAccessToken(
     data: JwtToken<T>,
     extend?: Record<string, any>,
     expire?: string | number,
   ): Promise<string>;
 
+  /**
+   * Validates an API token for a specified user and request type.
+   *
+   * @param {string} username - The username associated with the token.
+   * @param {string} token - The API token to validate.
+   * @param {string} requestType - The type of request for which the token is being validated.
+   * @returns {Promise<{ valid: boolean; userId: string | null }>} A promise that resolves to an object containing a boolean indicating whether the token is valid and the user ID if validation succeeds; otherwise, `null` is returned for the user ID.
+   */
   apiTokenValidation(
     username: string,
     token: string,
     requestType: string,
   ): Promise<{ valid: boolean; userId: string | null }>;
 
-  permissionValidation(
-    token: JwtToken<T>,
-    requestType: string,
-  ): Promise<boolean>;
-
+  /**
+   * Validates user permissions according to the supplied validation request.
+   *
+   * @param {ValidationRequest<T>} request - The request object containing the necessary
+   *   data for permission evaluation, such as user identity, requested action,
+   *   and contextual parameters.
+   *
+   * @return {Promise<boolean>} A promise that resolves to `true` if the permissions
+   *   are valid for the specified request, otherwise resolves to `false`.
+   */
+  permissionValidation(request: ValidationRequest<T>): Promise<boolean>;
+
+  /**
+   * Validates the bearer token present in the provided request.
+   * @param {XRequest} req - The HTTP request containing the Authorization header.
+   * @return {Promise<JwtToken<T> | number>} A promise that resolves to the decoded JWT payload if the token is valid, or a numeric status code (e.g., 401) if validation fails.
+   */
   bearerTokenValidation(req: XRequest): Promise<JwtToken<T> | number>;
 }
 
diff --git a/src/modules/crypto/CryptoClient.ts b/src/modules/crypto/CryptoClient.ts
@@ -1,7 +1,7 @@
 import { CoreCryptoClient } from '@grandlinex/core';
 import * as jwt from 'jsonwebtoken';
 import { type StringValue } from 'ms';
-import { ICClient, IKernel } from '../../lib/index.js';
+import { ICClient, IKernel, ValidationRequest } from '../../lib/index.js';
 import { IAuthProvider, JwtExtend, JwtToken } from '../../classes/index.js';
 import { XRequest } from '../../lib/express.js';
 
@@ -95,12 +95,9 @@ export default class CryptoClient<T extends JwtExtend = JwtExtend>
     };
   }
 
-  async permissionValidation(
-    token: JwtToken<T>,
-    requestType: string,
-  ): Promise<boolean> {
+  async permissionValidation(request: ValidationRequest<T>): Promise<boolean> {
     if (this.authProvider) {
-      return this.authProvider.validateAccess(token, requestType);
+      return this.authProvider.validateAccess(request);
     }
     return false;
   }
diff --git a/src/tests/DebugClasses.ts b/src/tests/DebugClasses.ts
@@ -6,7 +6,7 @@ import {
   BaseApiAction,
   BaseAuthProvider,
   ICClient,
-  JwtToken,
+  JwtToken, ValidationRequest,
   XActionEvent,
   XRequest
 } from '../index.js';
@@ -52,7 +52,7 @@ export class TestAuthProvider extends BaseAuthProvider {
     username: string,
     token: string,
     requestType: string
-  ): Promise< AuthResult> {
+  ): Promise<AuthResult> {
 
     const valid=username === 'admin' && token === 'admin' && requestType === 'api';
     return {
@@ -61,8 +61,9 @@ export class TestAuthProvider extends BaseAuthProvider {
     };
   }
 
-  async validateAccess(token: JwtToken, requestType: string): Promise<boolean> {
-    return token.username === 'admin' && requestType === 'api';
+  async validateAccess(request:ValidationRequest<any>): Promise<boolean> {
+    const { token, requestType } = request;
+    return token.username === 'admin' && requestType.includes('api');
   }
 
   async bearerTokenValidation(req: XRequest): Promise<JwtToken | number> {
diff --git a/src/tests/kernel.test.ts b/src/tests/kernel.test.ts
