node-server-engine 1.0.5

package/src/utils/filter/filter.ts

@@ -0,0 +1,17 @@
+/**
+ * Filters an object, returns a copy of that object with only the keys specified in the whitelist
+ * @param object - The object to filter
+ * @param whitelist - A list of keys to keep
+ */
+export function filter<T extends Record<string, unknown>>(
+  object: T,
+  whitelist: Array<string>
+): T {
+  const copy: Record<string, unknown> = {};
+  for (const key of Object.keys(object)) {
+    if (whitelist.includes(key)) {
+      copy[key] = object[key];
+    }
+  }
+  return copy as T;
+}

package/src/utils/filter/index.ts

@@ -0,0 +1 @@
+export * from './filter';

package/src/utils/getDynamicLink/getDynamicLink.test.ts

@@ -0,0 +1,51 @@
+import { AxiosRequestConfig, AxiosResponse } from 'axios';
+import chai, { expect } from 'chai';
+import { faker } from '@faker-js/faker';
+import { stub, SinonStub, match } from 'sinon';
+import sinonChai from 'sinon-chai';
+import { getDynamicLink } from './getDynamicLink';
+import { DynamicLinkResponseBody } from './getDynamicLink.types';
+import * as tlsRequest from 'utils/tlsRequest/tlsRequest';
+
+chai.use(sinonChai);
+
+describe('Utils - Get Dynamic Link', () => {
+  let expectedPayload: AxiosRequestConfig;
+  let path: string;
+  let requestStub: SinonStub;
+  let link: string;
+
+  beforeEach(() => {
+    link = faker.internet.url();
+    requestStub = stub(tlsRequest, 'tlsRequest').resolves({
+      data: { link }
+    } as AxiosResponse<DynamicLinkResponseBody>);
+    path = faker.system.directoryPath();
+    expectedPayload = {
+      method: 'get',
+      url: '/link',
+      baseURL: process.env.LINKS_SERVICE_URL,
+      params: {
+        path
+      }
+    };
+  });
+
+  it('should get a dynamic link', async () => {
+    // should return a link from the res
+    const dynamicLink = await getDynamicLink(path);
+    expect(dynamicLink).to.equal(link);
+    expect(requestStub).to.have.been.calledOnceWithExactly(
+      match(expectedPayload)
+    );
+  });
+
+  it('should get a dynamic link with custom settings', async () => {
+    // should return a link from the res
+    const dynamicLink = await getDynamicLink(path, { short: false });
+    expect(dynamicLink).to.equal(link);
+    expect(requestStub).to.have.been.calledOnceWithExactly(
+      match({ ...expectedPayload, params: { path, short: false } })
+    );
+  });
+});

package/src/utils/getDynamicLink/getDynamicLink.ts

@@ -0,0 +1,28 @@
+import { AxiosRequestConfig } from 'axios';
+import {
+  getDynamicLinksOptions,
+  DynamicLinkResponseBody
+} from './getDynamicLink.types';
+import { validateDynamicLinkEnvironment } from './getDynamicLink.validate';
+import { tlsRequest } from 'utils/tlsRequest';
+
+/** Fetch a dynamic link from the links service */
+export async function getDynamicLink(
+  path: string,
+  options: getDynamicLinksOptions = {}
+): Promise<string> {
+  validateDynamicLinkEnvironment();
+  const option: AxiosRequestConfig = {
+    method: 'get',
+    url: '/link',
+    baseURL: process.env.LINKS_SERVICE_URL,
+    params: {
+      path,
+      short: options.short ?? true
+    }
+  };
+  const {
+    data: { link }
+  } = await tlsRequest<DynamicLinkResponseBody>(option);
+  return link;
+}

package/src/utils/getDynamicLink/getDynamicLink.types.ts

@@ -0,0 +1,11 @@
+/** Options to fetch dynamic links */
+export interface getDynamicLinksOptions {
+  /** Make a shortened link */
+  short?: boolean;
+}
+
+/** Dynamic link query server response */
+export interface DynamicLinkResponseBody {
+  /** The generated dynamic link */
+  link: string;
+}

package/src/utils/getDynamicLink/getDynamicLink.validate.ts

@@ -0,0 +1,6 @@
+import { assertEnvironment, envAssert } from 'utils';
+
+/** Environment variable validator for get dynamic link from LinkService */
+export function validateDynamicLinkEnvironment(): void {
+  assertEnvironment({ LINKS_SERVICE_URL: envAssert.isURL() });
+}

package/src/utils/getDynamicLink/index.ts

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

package/src/utils/hmac/checkEnv/checkEnv.test.ts

@@ -0,0 +1,18 @@
+import { expect } from 'chai';
+import { assertPayloadSignatureSecret } from './checkEnv';
+
+describe('Utils - HMAC - Check environment', () => {
+  it('should pass if environment variables are set', () => {
+    process.env.PAYLOAD_SIGNATURE_SECRET = 'secret';
+    expect(() => {
+      assertPayloadSignatureSecret();
+    }).to.not.throw();
+  });
+
+  it('should throw an error if the environment vairable is not set', () => {
+    delete process.env.PAYLOAD_SIGNATURE_SECRET;
+    expect(() => {
+      assertPayloadSignatureSecret();
+    }).to.throw();
+  });
+});

package/src/utils/hmac/checkEnv/checkEnv.ts

@@ -0,0 +1,9 @@
+import { assertEnvironment } from 'utils/checkEnvironment';
+import { envAssert } from 'utils/envAssert';
+
+/**
+ * Check that secret used to sign payloads is properly set in the environment
+ */
+export function assertPayloadSignatureSecret(): void {
+  assertEnvironment({ PAYLOAD_SIGNATURE_SECRET: envAssert.isString() });
+}

package/src/utils/hmac/checkEnv/index.ts

@@ -0,0 +1 @@
+export * from './checkEnv';

package/src/utils/hmac/createHmac/createHmac.ts

@@ -0,0 +1,33 @@
+import crypto from 'crypto';
+import { assertPayloadSignatureSecret } from '../checkEnv';
+import { HmacOptions } from '../index.types';
+import { createSortedObject } from 'utils/createSortedObject';
+
+/** Calculates the HMAC signature for a given payload */
+export function createHmac(
+  payload: unknown,
+  options: HmacOptions = {}
+): Buffer | string {
+  // Check env if no secret is specified
+  if (!options.secret) {
+    assertPayloadSignatureSecret();
+  }
+  // Set default values
+  const settings = {
+    algorithm: options.algorithm ?? 'sha512',
+    sort: options.sort ?? true,
+    encode: options.encode,
+    secret: options.secret ?? (process.env.PAYLOAD_SIGNATURE_SECRET as string)
+  };
+
+  // Stringify the payload
+  const sortedPayload = settings.sort ? createSortedObject(payload) : payload;
+  const stringifiedPayload = JSON.stringify(sortedPayload);
+
+  // Calculate the hash
+  const hmac = crypto
+    .createHmac(settings.algorithm, settings.secret)
+    .update(stringifiedPayload);
+
+  return settings.encode ? hmac.digest(settings.encode) : hmac.digest();
+}

package/src/utils/hmac/createHmac/index.ts

@@ -0,0 +1 @@
+export * from './createHmac';

package/src/utils/hmac/index.ts

@@ -0,0 +1,4 @@
+export * from './signPayload';
+export * from './verifySignature';
+export * from './createHmac';
+export * from './index.types';

package/src/utils/hmac/index.types.ts

@@ -0,0 +1,13 @@
+import { BinaryToTextEncoding } from 'crypto';
+
+/** HMAC calculation options  */
+export interface HmacOptions {
+  /** Secret used to sign the payload */
+  secret?: string;
+  /** Hashing algorithm to use (default: SHA-512) */
+  algorithm?: string;
+  /** Should the object keys be sorted alphabetically (default: true) */
+  sort?: boolean;
+  /** The encoding of the signature (default: base64) */
+  encode?: BinaryToTextEncoding;
+}

package/src/utils/hmac/signPayload/index.ts

@@ -0,0 +1 @@
+export * from './signPayload';

package/src/utils/hmac/signPayload/signPayload.ts

@@ -0,0 +1,16 @@
+import { createHmac } from '../createHmac';
+import { HmacOptions } from '../index.types';
+
+/** Add signature to a payload */
+export function signPayload<T>(
+  payload: T,
+  options: HmacOptions = {}
+): T & {
+  /** HMAC signature of the payload */
+  signature: string;
+} {
+  return {
+    ...payload,
+    signature: createHmac(payload, { ...options, encode: 'base64' }) as string
+  };
+}

package/src/utils/hmac/verifySignature/index.ts

@@ -0,0 +1 @@
+export * from './verifySignature';

package/src/utils/hmac/verifySignature/verifySignature.ts

@@ -0,0 +1,24 @@
+import crypto from 'crypto';
+import { createHmac } from '../createHmac';
+import { HmacOptions } from '../index.types';
+
+/** Checks the signature of a payload */
+export function verifySignature(
+  payload: Record<string, unknown>,
+  signature: string,
+  options: HmacOptions = {}
+): boolean {
+  if (!payload || !signature) return false;
+  // Obtain a buffer digest
+  const digest = createHmac(payload, {
+    ...options,
+    encode: undefined
+  }) as Buffer;
+  // Transform the signature to buffer
+  const checksum = Buffer.from(signature, options.encode ?? 'base64');
+  // Compare signature with the calculated digest
+  return (
+    checksum.length === digest.length &&
+    crypto.timingSafeEqual(digest, checksum)
+  );
+}

package/src/utils/index.ts

@@ -0,0 +1,26 @@
+// general
+export * from './report';
+export * from './filter';
+export * from './semverCompare';
+export * from './dbMigration';
+
+// env
+export * from './checkEnvironment';
+export * from './envAssert';
+
+// auth
+export * from './createSortedObject';
+export * from './jwt';
+export * from './hmac';
+
+// Networking
+export * from './createHttpServer';
+export * from './request';
+export * from './tlsConfig';
+export * from './tlsRequest';
+export * from './sendPush';
+export * from './getDynamicLink';
+export * from './sendEmail';
+
+// String manipulation
+export * from './trimPathSlash';

package/src/utils/jwt/index.ts

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

package/src/utils/jwt/jwt.test.ts

@@ -0,0 +1,41 @@
+import { randomUUID } from 'crypto';
+import { generateAccessToken } from 'backend-test-tools';
+import { expect } from 'chai';
+import { faker } from '@faker-js/faker';
+import { jwtVerify } from './jwt';
+import { TokenIssuer } from 'const';
+
+describe('Utils - JWT', () => {
+  it('should pass a default token', async () => {
+    const id = randomUUID();
+    const token = generateAccessToken(id);
+    const result = await jwtVerify(token);
+    expect(result.sub).to.equal(id);
+  });
+
+  it('should pass a token with one correct audience [Auth-service]', async () => {
+    const id = randomUUID();
+    const token = generateAccessToken(id, {
+      audience: [
+        process.env.ACCESS_TOKEN_AUDIENCE as string,
+        faker.lorem.word()
+      ],
+      issuer: process.env.ACCESS_TOKEN_ISSUER
+    });
+    const result = await jwtVerify(token, TokenIssuer.AUTH_SERVICE);
+    expect(result.sub).to.equal(id);
+  });
+
+  it('should pass a token with one correct audience [Admin-API]', async () => {
+    const id = randomUUID();
+    const token = generateAccessToken(id, {
+      audience: [
+        process.env.ADMIN_API_ACCESS_TOKEN_AUDIENCE as string,
+        faker.lorem.word()
+      ],
+      issuer: process.env.ADMIN_ACCESS_TOKEN_ISSUER
+    });
+    const result = await jwtVerify(token, TokenIssuer.ADMIN_API);
+    expect(result.sub).to.equal(id);
+  });
+});

package/src/utils/jwt/jwt.ts

@@ -0,0 +1,204 @@
+import {
+  verify,
+  JwtHeader,
+  SigningKeyCallback,
+  Algorithm,
+  VerifyOptions,
+  sign
+} from 'jsonwebtoken';
+import fs from 'fs';
+import path from 'path';
+import { UserTokenPayload } from './jwt.types';
+import { TokenIssuer } from 'const';
+import { EngineError } from 'entities/EngineError';
+import { KeySet } from 'entities/KeySet';
+import { WebError } from 'entities/WebError';
+import { assertEnvironment } from 'utils/checkEnvironment';
+import { envAssert } from 'utils/envAssert';
+import { reportDebug } from 'utils/report';
+
+export let keySet: KeySet | undefined;
+export let adminKeySet: KeySet | undefined;
+
+const namespace = 'engine:utils:jwt';
+
+/** Initiate key fetching mechanism */
+export async function initKeySets(): Promise<void> {
+  // Create the KeySet instance
+  // The auth-service fetches its key from its disk and not from a network request
+  // This prevents fetch failures the first time the auth-service is started
+  if (process.env.CHART === 'auth-service') {
+    if (!process.env.ECDSA_PUBLIC_KEY)
+      throw new EngineError({
+        message: 'Environment variable "ECDSA_PUBLIC_KEY" is not defined'
+      });
+    keySet = new KeySet(process.env.ECDSA_PUBLIC_KEY, { file: true });
+  } else {
+    if (process.env.AUTH_SERVICE_URL)
+      keySet = new KeySet(
+        `${process.env.AUTH_SERVICE_URL}/.well-known/jwks.json`,
+        { internal: true }
+      );
+    else
+      keySet = new KeySet(`./keys/jwks.json`, { internal: true, file: true });
+
+    if (!keySet)
+      throw new EngineError({
+        message:
+          'Environment variable "AUTH_SERVICE_URL" is not defined or JWKS not found'
+      });
+  }
+  const promise = [keySet.init.bind(keySet)()];
+
+  // Load the key set for the admin api
+  if (!process.env.ADMIN_API_ECDSA_PUBLIC_KEY)
+    throw new EngineError({
+      message:
+        "Admin API's authentication JWT signing public key is not defined"
+    });
+  adminKeySet = new KeySet(process.env.ADMIN_API_ECDSA_PUBLIC_KEY, {
+    pem: true
+  });
+  promise.push(adminKeySet.init.bind(adminKeySet)());
+
+  await Promise.all(promise);
+}
+
+/** Stop fetching keys regularly */
+export function shutdownKeySets(): void {
+  if (keySet) keySet.shutdown.bind(keySet)();
+  if (adminKeySet) adminKeySet.shutdown.bind(adminKeySet)();
+}
+
+/** Get the JWT public key */
+function jwtGetKey(header: JwtHeader, callback: SigningKeyCallback): void {
+  // In test environment we return the symmetric signature secret
+  if (process.env.NODE_ENV === 'test') {
+    callback(null, process.env.JWT_SECRET);
+    return;
+  }
+  // Check that KeySet has been initialized
+  if (!keySet || !adminKeySet) {
+    callback(new EngineError({ message: 'KeySet has not been initialized' }));
+    return;
+  }
+  // Check that the token has a key ID
+  if (!header.kid) {
+    callback(
+      new EngineError({
+        message:
+          'Token has not key ID in header, impossible to match with known key',
+        data: header
+      })
+    );
+    return;
+  }
+
+  // In test environment we use a symmetrical secret bases signature
+  if (process.env.NODE_ENV === 'test') {
+    callback(null, process.env.JWT_SECRET);
+    return;
+  }
+  reportDebug({
+    namespace,
+    message: `Looking for key with ID "${header.kid}"`
+  });
+  // Go through each key set to check if the token's key is in one of them
+  let key;
+  try {
+    key = keySet.getKey(header.kid);
+  } catch (error: Error | null | unknown) {
+    callback(error instanceof Error ? error : null);
+    return;
+  }
+
+  if (key) {
+    reportDebug({ namespace, message: `Found key with ID "${header.kid}"` });
+    callback(null, key);
+    return;
+  }
+  callback(
+    new WebError({
+      statusCode: 401,
+      errorCode: 'unauthorized',
+      message: 'Could not find the tokens key in any key set',
+      data: { kid: header.kid }
+    })
+  );
+}
+
+/** Verify an user Json Web Token */
+export async function jwtVerify(
+  token: string,
+  issuer: TokenIssuer = TokenIssuer.AUTH_SERVICE
+): Promise<UserTokenPayload> {
+  let algorithms = ['ES256' as Algorithm];
+  if (process.env.NODE_ENV === 'test') {
+    assertEnvironment({ JWT_SECRET: envAssert.isString() });
+    algorithms = ['HS256' as Algorithm];
+  }
+  assertEnvironment({
+    ACCESS_TOKEN_AUDIENCE: envAssert.isString(),
+    ACCESS_TOKEN_ISSUER: envAssert.isString(),
+    ADMIN_API_ACCESS_TOKEN_AUDIENCE: envAssert.isString(),
+    ADMIN_ACCESS_TOKEN_ISSUER: envAssert.isString()
+  });
+  let options: VerifyOptions | undefined;
+
+  switch (issuer) {
+    case TokenIssuer.AUTH_SERVICE:
+      options = {
+        audience: [process.env.ACCESS_TOKEN_AUDIENCE as string],
+        issuer: [process.env.ACCESS_TOKEN_ISSUER as string],
+        algorithms
+      };
+      break;
+    case TokenIssuer.ADMIN_API:
+      options = {
+        audience: [process.env.ADMIN_API_ACCESS_TOKEN_AUDIENCE as string],
+        issuer: [process.env.ADMIN_ACCESS_TOKEN_ISSUER as string],
+        algorithms
+      };
+      break;
+    default:
+      throw new EngineError({
+        message: `Invalid token issuer specified "${issuer as string}"`
+      });
+  }
+
+  return new Promise<UserTokenPayload>((resolve, reject) => {
+    verify(token, jwtGetKey, options, (error, result) => {
+      if (error) {
+        reject(
+          new WebError({
+            errorCode: 'unauthorized',
+            statusCode: 401,
+            message: 'Invalid token supplied',
+            data: { token },
+            error: error instanceof Error ? error : undefined
+          })
+        );
+        return;
+      }
+      resolve(result as UserTokenPayload);
+    });
+  });
+}
+
+export function generateJwtToken(user: unknown) {
+  const signOptions = {
+    algorithm: 'ES256' as const, // or 'ES256' as Algorithm
+    expiresIn: '1h',
+    issuer: process.env.ACCESS_TOKEN_ISSUER,
+    audience: process.env.ACCESS_TOKEN_AUDIENCE,
+    keyid: Object.keys(keySet?.getKeys() ?? {})[0]
+  };
+
+  const privateKey = fs.readFileSync(
+    process.env.PRIVATE_KEY_PATH ?? 'keys/private-key.pem',
+    'utf8'
+  );
+  const token = sign({ user }, privateKey, signOptions);
+
+  return token;
+}

package/src/utils/jwt/jwt.types.ts

@@ -0,0 +1,21 @@
+import { RequestUser } from "middleware/authJwt/authJwt.types";
+
+/** Content of the payload of user authentication tokens */
+export interface UserTokenPayload {
+  /** ID of the user */
+  sub: string;
+  /** URL of the service that issued the token */
+  iss: string;
+  /** URL of the services that can consume the token */
+  aud: Array<string> | string;
+  /** Unique ID of the token */
+  jti: string;
+  /** ID of the device the token was issued to */
+  dev: string;
+  /** Timestamp at which the token will expire */
+  exp: number;
+  /** List of permissions that the user has (only on the admin API) */
+  per?: Array<string> | string;
+  /** User */
+  user: RequestUser;
+}

package/src/utils/report/index.ts

@@ -0,0 +1,3 @@
+export * from './report';
+export * from './output.types';
+export * from './report.types';

package/src/utils/report/output.ts

@@ -0,0 +1,45 @@
+import { randomUUID } from 'crypto';
+import callsite from 'callsite';
+import stringify from 'json-stringify-safe';
+import { LogEntry, FullLogEntry } from './output.types';
+
+// NOTE: Server instance id (helpful for distributed logs)
+export const INSTANCE_ID = randomUUID();
+
+/** Add metadata to the log entry and print it */
+export function output(data: LogEntry): FullLogEntry {
+  // Gather useful information about where the logger was called from
+  const call = callsite()[2];
+
+  // Append additional metadata to the log entry
+  const fullEntry: FullLogEntry = {
+    ...data,
+    lineNumber: call.getLineNumber(),
+    fileName: call
+      .getFileName()
+      .replace(/.*node_modules\//, '')
+      .replace(/.*src\//, 'src/'),
+    serviceContext: {
+      service: process.env.CHART ?? process.env.HOSTNAME,
+      version: process.env.BUILD_ID,
+      environment: process.env.NODE_ENV,
+      instance: process.env.KUBERNETES_POD_NAME ?? INSTANCE_ID
+    }
+  };
+
+  const entry = stringify(fullEntry);
+  // Ignore when silenced
+  if (process.env.SILENCE_REPORT) return fullEntry;
+
+  if (process.env.NODE_ENV === 'test') {
+    // In test mode pretty print
+    console.dir(fullEntry, { depth: 5 });
+  } else if (data.statusCode && data.statusCode >= 500) {
+    // Log to stderr when it is a 500+ error
+    console.error(entry);
+  } else {
+    // Default to regular logging
+    console.log(entry);
+  }
+  return fullEntry;
+}