node-server-engine 1.0.5

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

@@ -0,0 +1,205 @@
+/* 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,
+  authAdmin,
+  RequestUser,
+  FileUploaderConfig,
+  RequestAdminProps
+} from 'middleware';
+
+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',
+  ADMIN = 'admin'
+}
+
+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>;
+
+/** Auth related parameters used with Admin authentication  */
+interface EndpointAuthAdminParams {
+  /** [Admin] User permission required to use this endpoint */
+  permission: string;
+}
+
+/** 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;
+  /** Auth parameters for admin token authentication */
+  [EndpointAuthType.ADMIN]: EndpointAuthAdminParams;
+}
+
+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,
+  /** Auth handler for admin token authentication */
+  [EndpointAuthType.ADMIN]: authAdmin
+};
+
+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>;
+  /** 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: RequestUser;
+}
+
+/** 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>;
+}
+
+/** Request type when using HMAC authentication */
+export interface AdminRequest<
+  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 */
+  admin: RequestAdminProps;
+}
+
+/** 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;
+  /** Auth handler for admin token authentication */
+  [EndpointAuthType.ADMIN]: AdminRequest;
+}
+
+export type SafeMiddleWareChain = Array<
+  RequestHandler | ErrorRequestHandler | SafeMiddleWareChain
+>;

package/src/entities/Endpoint/index.ts

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

package/src/entities/EngineError/EngineError.ts

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,15 @@
+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

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

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

@@ -0,0 +1,126 @@
+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.ADMIN_API_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

@@ -0,0 +1,172 @@
+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

@@ -0,0 +1,28 @@
+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

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

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

@@ -0,0 +1,48 @@
+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

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,5 @@
+/** 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

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