node-server-engine 1.4.9 → 1.5.0

package/src/entities/Endpoint/Endpoint.types.ts

@@ -1,181 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import {
-  ErrorRequestHandler,
-  Request,
-  Response,
-  NextFunction,
-  RequestHandler
-} from 'express';
-import { ParamsDictionary } from 'express-serve-static-core';
-import { Schema } from 'express-validator';
-import { ParsedQs } from 'qs';
-
-import {
-  authJwt,
-  authHmac,
-  authTls,
-  authStatic,
-  FileUploaderConfig
-} from 'middleware';
-import { MultiPartFileUploaderConfig } from 'middleware/multiPartFileUploader/multiPartFileUploader.types';
-
-export enum EndpointMethod {
-  GET = 'get',
-  POST = 'post',
-  PUT = 'put',
-  PATCH = 'patch',
-  DELETE = 'delete',
-  HEAD = 'head',
-  ALL = 'all'
-}
-
-export const EndpointMethods = Object.values(EndpointMethod);
-
-export enum EndpointAuthType {
-  NONE = 'none',
-  JWT = 'jwt',
-  TLS = 'tls',
-  HMAC = 'hmac',
-  STATIC = 'static'
-}
-
-export const EndpointAuthTypes = Object.values(EndpointAuthType);
-
-export type Middleware<T extends EndpointAuthType> = (
-  request: EndpointRequestType[T],
-  response: Response,
-  next: NextFunction
-) => unknown | Promise<unknown>;
-
-export type MiddlewareChainElement<T extends EndpointAuthType> =
-  | Array<Middleware<T>>
-  | Middleware<T>
-  | any;
-
-/** Auth related parameters used with HMAC authentication  */
-interface EndpointAuthHmacParams {
-  /** [HMAC] Secret used for signature */
-  secret?: string;
-  /** [HMAC] For Github webhook, the standard differs slightly, so this option must be selected */
-  isGithub?: boolean;
-}
-
-/** Auth related parameters used with mTLS authentication  */
-interface EndpointAuthTlsParams {
-  /** [TLS] List oh hosts that are allowed to use the endpoint, this is compared to the claims in the certificate */
-  whitelist?: Array<string>;
-}
-
-/** Mapping used to get auth specific parameters depending on the auth type used  */
-interface EndpointAuthSpecificParams {
-  /** Auth parameters for no authentication */
-  [EndpointAuthType.NONE]: any;
-  /** Auth parameters for JWT authentication */
-  [EndpointAuthType.JWT]: any;
-  /** Auth parameters for mTLS authentication */
-  [EndpointAuthType.TLS]: EndpointAuthTlsParams;
-  /** Auth parameters for HMAC authentication */
-  [EndpointAuthType.HMAC]: EndpointAuthHmacParams;
-  /** Auth parameters for static authentication */
-  [EndpointAuthType.STATIC]: any;
-}
-
-export type EndpointAuthParams<T extends EndpointAuthType> =
-  EndpointAuthSpecificParams[T] & {
-    /** This will allow the business logic to run event if the authentication fails */
-    acceptInvalid?: boolean;
-  };
-
-export type EndpointAuthHandler<T extends EndpointAuthType> = (
-  options?: EndpointAuthParams<T>
-) => (
-  request: Request,
-  response: Response,
-  next: NextFunction
-) => void | Promise<void>;
-
-export const EndpointAuthHandlers = {
-  /** Auth handler for no authentication */
-  [EndpointAuthType.NONE]: undefined,
-  /** Auth handler for JWT authentication */
-  [EndpointAuthType.JWT]: authJwt,
-  /** Auth handler for mTLS authentication */
-  [EndpointAuthType.TLS]: authTls,
-  /** Auth handler for HMAC authentication */
-  [EndpointAuthType.HMAC]: authHmac,
-  /** Auth handler for static authentication */
-  [EndpointAuthType.STATIC]: authStatic
-};
-
-export type EndpointHandler<T extends EndpointAuthType> = (
-  request: EndpointRequestType[T],
-  response: Response
-) => void | Promise<void>;
-
-/** Endpoint initialization options */
-export interface EndpointOptions<T extends EndpointAuthType> {
-  /** Path at which the endpoint is reachable */
-  path: string;
-  /** HTTP method of the endpoint */
-  method: EndpointMethod;
-  /** Function handling the endpoint's business logic */
-  handler: EndpointHandler<T>;
-  /** Validation schema that the request must pass before reaching the handler */
-  validator: Schema;
-  /** Authentication system required by this endpoint */
-  authType: T;
-  /** Authentication related options for this endpoint */
-  authParams?: EndpointAuthParams<T>;
-  /** @deprecated Setting to upload a file through this endpoint */
-  file?: FileUploaderConfig;
-  /** Settings to upload files through this endpoint (this will automatically switch the expected request to be a multipart) */
-  files?: Array<FileUploaderConfig>;
-  /** Settings to upload file parts (Chunks) through this endpoint (this will automatically switch the expected request to be a multipart) */
-  multiPartFile?: MultiPartFileUploaderConfig;
-  /** Express request handlers that should run on this endpoint before the business logic, they will run after the global middleware */
-  middleware?: MiddlewareChainElement<T>;
-  /** Express error handlers that should be registered for this endpoint. they will run before the global error handler */
-  errorMiddleware?: ErrorRequestHandler | Array<ErrorRequestHandler>;
-}
-
-/** Request type when using JWT authentication */
-export interface JwtRequest<
-  P = ParamsDictionary,
-  ResBody = any,
-  ReqBody = any,
-  ReqQuery = ParsedQs,
-  Locals extends Record<string, any> = Record<string, any>
-> extends Request<P, ResBody, ReqBody, ReqQuery, Locals> {
-  /** User that identified using a JWT */
-  user: Record<string, any> | any;
-}
-
-/** Request type when using mTLS authentication */
-export interface TlsRequest<
-  P = ParamsDictionary,
-  ResBody = any,
-  ReqBody = any,
-  ReqQuery = ParsedQs,
-  Locals extends Record<string, any> = Record<string, any>
-> extends Request<P, ResBody, ReqBody, ReqQuery, Locals> {
-  /** Host names provided by the mTLS authenticated client */
-  hosts: Array<string>;
-}
-
-/** Mapping of request types in endpoints based on auth type used */
-export interface EndpointRequestType {
-  /** Request type for no authentication */
-  [EndpointAuthType.NONE]: Request;
-  /** Request type when using JWT authentication */
-  [EndpointAuthType.JWT]: JwtRequest;
-  /** Request type when using mTLS authentication */
-  [EndpointAuthType.TLS]: TlsRequest;
-  /** Request type when using HMAC authentication */
-  [EndpointAuthType.HMAC]: Request;
-  /** Auth handler for static authentication */
-  [EndpointAuthType.STATIC]: Request;
-}
-
-export type SafeMiddleWareChain = Array<
-  RequestHandler | ErrorRequestHandler | SafeMiddleWareChain
->;

package/src/entities/Endpoint/index.ts

@@ -1,2 +0,0 @@
-export * from './Endpoint';
-export * from './Endpoint.types';

package/src/entities/EngineError/EngineError.ts

@@ -1,28 +0,0 @@
-import { EngineErrorOptions } from './EngineError.types';
-import { LogSeverity } from 'const';
-
-/**
- * Base error type for engine related errors
- */
-export class EngineError extends Error {
-  /** Severity of the log entry */
-  public severity: LogSeverity;
-  /** If this error is wrapping another one, this will contain the original error */
-  public error?: Error;
-  /** Additional contextual data for debugging */
-  public data?: unknown;
-  /** Human readable error message sent to the client */
-  public hint?: unknown;
-
-  /** Create an EngineError, these errors represent errors in the engine itself */
-  public constructor(config: EngineErrorOptions | string) {
-    const options: EngineErrorOptions =
-      typeof config === 'string' ? { message: config } : config;
-    super(options.message);
-
-    this.severity = options.severity ?? LogSeverity.CRITICAL;
-    this.data = options.data;
-    this.error = options.error;
-    this.hint = options.hint;
-  }
-}

package/src/entities/EngineError/EngineError.types.ts

@@ -1,15 +0,0 @@
-import { LogSeverity } from 'const';
-
-/** EngineError initialization options */
-export interface EngineErrorOptions {
-  /** Main logged message */
-  message: string;
-  /** Severity of the log entry */
-  severity?: LogSeverity;
-  /** If this error is wrapping another one, this will contain the original error */
-  error?: Error;
-  /** Additional contextual data for debugging */
-  data?: unknown;
-  /** Human readable error message sent to the client */
-  hint?: unknown;
-}

package/src/entities/EngineError/index.ts

@@ -1,2 +0,0 @@
-export * from './EngineError';
-export * from './EngineError.types';

package/src/entities/KeySet/KeySet.test.ts

@@ -1,126 +0,0 @@
-import { randomUUID, createPublicKey } from 'crypto';
-import { readFileSync } from 'fs';
-import { readFile } from 'fs/promises';
-import { AxiosResponse } from 'axios';
-import { expect } from 'chai';
-import { faker } from '@faker-js/faker';
-import { stub, SinonStub } from 'sinon';
-import { KeySet } from './KeySet';
-import { JWKS } from './KeySet.types';
-import * as request from 'utils/request/request';
-import * as tlsRequest from 'utils/tlsRequest/tlsRequest';
-
-// We test with both an RSA key and an EC key
-const TEST_JWKS = {
-  data: {
-    keys: [
-      {
-        alg: 'RS256',
-        kty: 'RSA',
-        use: 'sig',
-        n:
-          'u18mjw63ELk8xA4C2Qbi1WTtqcx853iRv9Gfd-zKKmlU2wStnOGnIfnHkrNbl5y8vTMNBKNuqLh3Y_el' +
-          'PVSUIWGcy3KByw7VRnBTAze2bsmI0Dvz-89Ar1C2g0Ui6DOYyEa0iiXer4gSQgJ5ddsbIAMJMBT5j96G' +
-          '1mhbjM2mqekORRyjCZHGeNbofnTvKcJRTStsBPXQ2WEkAf6J1eNZ2-QnNYMVVO44-KXfhQsfaqRoporj' +
-          '4LvTkNX0kkxyfC3V1R8Qrk-_pHhzPtKtQxiRj2axTVXFoj5I1Po7WgQz2_vBZnWZ-0AIzHXN6F_fmMhy' +
-          'PBPk3pbuN7cHBe2cKh_nHQ',
-        e: 'AQAB',
-        kid: 'Q0ZCQzEwRTFCOUE3QjI0MUZEREQ0N0I4MTI3OTVFRDkyNTIxQjQ3MA'
-      },
-      {
-        crv: 'P-256',
-        kty: 'EC',
-        x: 'ruky13qVa2GM9jnWsBYP_OTsk6fyV_HWC2AjvUkyCv8',
-        y: 'kIAW58dw6pjO1dy4czpNdsaL8DUc3RKo6Hmses5O_Bc',
-        kid: '3d-GYUhTwkAfCi9JdvMieQ',
-        alg: 'EC256',
-        use: 'sig'
-      }
-    ]
-  }
-};
-
-const TEST_PEMS = TEST_JWKS.data.keys.map((key) =>
-  createPublicKey({ key, format: 'jwk' }).export({
-    format: 'pem',
-    type: 'spki'
-  })
-);
-
-describe('Entity - KeySet', function () {
-  let url: string;
-  let requestStub: SinonStub;
-  let tlsRequestStub: SinonStub;
-
-  beforeEach(() => {
-    url = faker.internet.url();
-
-    requestStub = stub(request, 'request').resolves(
-      TEST_JWKS as unknown as AxiosResponse<JWKS>
-    );
-    tlsRequestStub = stub(tlsRequest, 'tlsRequest').resolves(
-      TEST_JWKS as unknown as AxiosResponse<JWKS>
-    );
-  });
-
-  it('should create a key set when fetching', async () => {
-    const keySet = new KeySet(url);
-    await keySet.init();
-
-    const keys = keySet.getKeys();
-    expect(Object.values(keys)).to.have.length(2);
-    Object.values(keys).forEach((key) => {
-      expect(TEST_PEMS).to.include(key);
-    });
-  });
-
-  it('should make a regular request by default', async () => {
-    const keySet = new KeySet(url);
-
-    await keySet.init();
-
-    expect(requestStub).to.have.been.calledOnceWithExactly({
-      url,
-      method: 'get'
-    });
-    expect(tlsRequestStub).to.not.have.been.called;
-  });
-
-  it('should make a TLS request for internal keysets', async () => {
-    const keySet = new KeySet(url, { internal: true });
-
-    await keySet.init();
-
-    expect(tlsRequestStub).to.have.been.calledOnceWithExactly({
-      url,
-      method: 'get'
-    });
-    expect(requestStub).to.not.have.been.called;
-  });
-
-  it('should read a key from a PEM string', async () => {
-    const pem = await readFile(
-      process.env.ECDSA_PUBLIC_KEY as string,
-      'utf-8'
-    );
-
-    const keySet = new KeySet(pem, { pem: true });
-
-    await keySet.init();
-
-    expect(tlsRequestStub).to.not.have.been.called;
-    expect(requestStub).to.not.have.been.called;
-    expect(Object.keys(keySet.getKeys())).to.have.length(1);
-    for (const key of Object.values(keySet.getKeys())) {
-      expect(key).to.equal(pem);
-    }
-  });
-
-  it('should not fail if the init did not complete and a key is asked', () => {
-    const keySet = new KeySet(faker.internet.url());
-
-    const result = keySet.getKey(randomUUID());
-
-    expect(result).to.be.undefined;
-  });
-});

package/src/entities/KeySet/KeySet.ts

@@ -1,172 +0,0 @@
-import { createPublicKey, createHash } from 'crypto';
-import { readFileSync } from 'fs';
-import { Method } from 'axios';
-import { KeySetOptions, KeySetValues, JWKS } from './KeySet.types';
-import { LogSeverity } from 'const';
-import { EngineError } from 'entities/EngineError';
-import { reportDebug, reportError } from 'utils/report';
-import { request } from 'utils/request';
-import { tlsRequest } from 'utils/tlsRequest';
-
-const namespace = 'engine:keySet';
-
-// Number of seconds between each key refresh
-const KEY_REFRESH_INTERVAL = 300;
-
-/**
- * Fetch Json Web Key Sets and cache them
- * Keys can then be used for Json Web Token authentication
- */
-export class KeySet {
-  /** Latest known value for the keys in the set, indexed by the key id */
-  private keySet: KeySetValues = {};
-  /** URL at which the key set can be fetched */
-  private url: string;
-  /** This resource is located on a service inside of our private cluster */
-  private internal: boolean;
-  /** This URL is actually a path to a local key file encoded in PEM  */
-  private file: boolean;
-  /** This input is actually a full PEM string representation of a key */
-  private pem: boolean;
-  /** Timer for the key fetching interval */
-  private interval?: NodeJS.Timeout | string | number | undefined;
-
-  /** Create a new Key Set */
-  public constructor(url: string, options: KeySetOptions = {}) {
-    this.url = url;
-    this.internal = options.internal ?? false;
-    this.file = options.file ?? false;
-    this.pem = options.pem ?? false;
-  }
-
-  /** Calculate key ID from PEM string */
-  private static calculateKeyId(pem: string): string {
-    // We use the md5 hash of the PEM file to defined the key ID
-    const hash = createHash('md5');
-    hash.update(pem.trim());
-    const kid = hash.digest('base64url');
-    reportDebug({
-      namespace,
-      message: `Calculated Key ID: "${kid}"`,
-      data: { key: pem }
-    });
-    return kid;
-  }
-
-  /** Initialize a KeySet, should be run on server startup to avoid any misconfiguration */
-  public async init(): Promise<void> {
-    await this.fetch();
-    this.interval = setInterval(() => {
-      (async (): Promise<void> => {
-        try {
-          await this.fetch();
-        } catch (error) {
-          reportError(error);
-        }
-      })().catch((error) => {
-        reportError(error);
-      });
-    }, KEY_REFRESH_INTERVAL * 1000);
-  }
-
-  /** Clear any pending timers to avoid pending process */
-  public shutdown(): void {
-    if (this.interval) clearInterval(this.interval);
-  }
-
-  /** Get the PEM encoded version of a key by its id */
-  public getKey(keyId: string): string | undefined {
-    return this.keySet[keyId];
-  }
-
-  /** Get all the keys in the set mapped by their ID */
-  public getKeys(): KeySetValues {
-    return this.keySet;
-  }
-
-  /** Fetch the latest version of the key set */
-  private async fetch(): Promise<void> {
-    reportDebug({
-      namespace,
-      message: `Fetching JWKS`,
-      data: { url: this.url }
-    });
-
-    if (this.pem) {
-      // Read the key from the parameter directly
-      reportDebug({
-        namespace,
-        message: 'Processing key from given PEM string'
-      });
-
-      const kid = KeySet.calculateKeyId(this.url);
-
-      this.keySet = { [kid]: this.url };
-    } else if (this.file) {
-      // Read the key from a file
-      reportDebug({
-        namespace,
-        message: `Reading key on disk at path "${this.url}"`
-      });
-      const set = JSON.parse(readFileSync(this.url, 'utf-8'));
-
-      // Check that the returned data has the shape of a JWKS
-      if (!(set.keys && set.keys instanceof Array))
-        throw new EngineError({
-          severity: LogSeverity.ERROR,
-          message: 'Fetched key set is not in an appropriate format',
-          data: { url: this.url, set }
-        });
-
-      // Create a node.crypto public key object for each key in the set
-      this.keySet = set.keys.reduce(
-        (set: { [x: string]: string; }, key: { kid: string | number; }) => {
-          set[key.kid] = createPublicKey({ key, format: 'jwk' }).export({
-            format: 'pem',
-            type: 'spki'
-          }) as string;
-          return set;
-        },
-        {} as Record<string, string>
-      );
-    } else {
-      // Fetch key by making a network request
-      reportDebug({
-        namespace,
-        message: `Making network request to "${this.url}"`
-      });
-
-      const requestOptions = { url: this.url, method: 'get' as Method };
-      // For services inside of our cluster we use the TLS authenticated request method
-      const { data: set } = await (this.internal
-        ? tlsRequest<JWKS>(requestOptions)
-        : request<JWKS>(requestOptions));
-
-      // Check that the returned data has the shape of a JWKS
-      if (!(set.keys && set.keys instanceof Array))
-        throw new EngineError({
-          severity: LogSeverity.ERROR,
-          message: 'Fetched key set is not in an appropriate format',
-          data: { url: this.url, set }
-        });
-
-      // Create a node.crypto public key object for each key in the set
-      this.keySet = set.keys.reduce(
-        (set, key) => {
-          set[key.kid] = createPublicKey({ key, format: 'jwk' }).export({
-            format: 'pem',
-            type: 'spki'
-          }) as string;
-          return set;
-        },
-        {} as Record<string, string>
-      );
-    }
-
-    reportDebug({
-      namespace,
-      message: `Stored ${Object.keys(this.keySet).length} keys`,
-      data: { keyIds: Object.keys(this.keySet) }
-    });
-  }
-}

package/src/entities/KeySet/KeySet.types.ts

@@ -1,28 +0,0 @@
-import { JsonWebKey } from 'crypto';
-
-/** KeySet initialization options */
-export interface KeySetOptions {
-  /** This resource is located on a service inside of our private cluster */
-  internal?: boolean;
-  /** This URL is actually a path to a local key file encoded in PEM  */
-  file?: boolean;
-  /** This input is actually a full PEM string representation of a key */
-  pem?: boolean;
-}
-
-/** Keep a mapping ok keyId => PEM */
-export interface KeySetValues {
-  [id: string]: string;
-}
-
-/** Object holding JWK keys */
-export interface JWKS {
-  /** Key set is JWKS format */
-  keys: Array<JWK>;
-}
-
-/** JWK key with custom claims */
-interface JWK extends JsonWebKey {
-  /** ID of the key */
-  kid: string;
-}

package/src/entities/KeySet/index.ts

@@ -1,2 +0,0 @@
-export * from './KeySet';
-export * from './KeySet.types';

package/src/entities/LifecycleController/LifecycleController.test.ts

@@ -1,48 +0,0 @@
-import { expect } from 'chai';
-import { Request, Response } from 'express';
-import { stub, SinonStub } from 'sinon';
-import { Endpoint, EndpointMethod, EndpointAuthType } from '../Endpoint';
-import { runningInstances } from './LifecycleController';
-import { Localizator } from 'entities/Localizator';
-import { redisClient } from 'entities/Redis/Redis';
-import { Server } from 'entities/Server';
-import { stubPubSub } from 'test';
-
-describe('Entity - LifecycleController', function () {
-  let localizatorShutdownStub: SinonStub;
-
-  beforeEach(() => {
-    stubPubSub();
-    stub(Localizator, 'synchronize').resolves();
-    localizatorShutdownStub = stub(Localizator, 'shutdown').resolves();
-  });
-
-  it('Shutdown the running entities', async () => {
-    const server = new Server({
-      endpoints: [
-        new Endpoint({
-          method: EndpointMethod.GET,
-          authType: EndpointAuthType.NONE,
-          validator: {},
-          path: '/',
-          handler: (req: Request, res: Response): void => {
-            res.json({ message: 'success' });
-          }
-        })
-      ],
-      initCallbacks: [
-        Localizator.init.bind(Localizator)
-      ]
-    });
-
-    await server.init();
-
-    // Redis will always have been init
-    expect([...runningInstances]).to.include(Localizator);
-
-    await server.shutdown();
-
-    expect(localizatorShutdownStub).to.have.been.calledOnce;
-    expect(redisClient).to.be.undefined;
-  });
-});

package/src/entities/LifecycleController/LifecycleController.ts

@@ -1,24 +0,0 @@
-import { LifecycleControlledInstance } from './LifecycleController.types';
-
-/**  List of initialized entities */
-export const runningInstances: Set<LifecycleControlledInstance> = new Set();
-
-/** LifecycleController is used to shutdown all the entities on server shutdown */
-export const LifecycleController = {
-  /** Add the initialized instances into the runningInstance property */
-  register(instance: LifecycleControlledInstance): void {
-    runningInstances.add(instance);
-  },
-
-  /** Shutdown all the running instances */
-  async shutdownRunningInstances(): Promise<void> {
-    const promises = [];
-    for (const instance of runningInstances) {
-      if (instance) {
-        promises.push(instance.shutdown.bind(instance)());
-      }
-    }
-    await Promise.all(promises);
-    runningInstances.clear();
-  }
-};

package/src/entities/LifecycleController/LifecycleController.types.ts

@@ -1,5 +0,0 @@
-/** Service instance that can be auto-shutdown by the Lifecycle Controller */
-export interface LifecycleControlledInstance {
-  /** Function that will be called on server shutdown, should trigger the instance cleanup */
-  shutdown: () => void | Promise<void>;
-}

package/src/entities/LifecycleController/index.ts

@@ -1,2 +0,0 @@
-export { LifecycleController } from './LifecycleController';
-export * from './LifecycleController.types';