@villedemontreal/jwt-validator 5.7.7

package/src/jwtValidator.ts

@@ -0,0 +1,162 @@
+import { utils } from '@villedemontreal/general-utils';
+import * as jwt from 'jsonwebtoken';
+import * as moment from 'moment';
+import { constants } from './config/constants';
+import { createInvalidAuthHeaderError, createInvalidJwtError } from './models/customError';
+import { IJWTPayload, isJWTPayload } from './models/jwtPayload';
+import { IPublicKey, PublicKeyState } from './models/publicKey';
+import { cachedPublicKeyRepository } from './repositories/cachedPublicKeyRepository';
+
+/**
+ * JWT validator
+ */
+export interface IJwtValidator {
+  /**
+   * Verifies an "Authorization" header containing a JWT, checks
+   * the JWT with the public key and returns the decoded payload.
+   *
+   * @param {string} header
+   * @return {Promise<IJWTPayload>}
+   */
+  verifyAuthorizationHeader(header: string): Promise<IJWTPayload>;
+
+  /**
+   * Verifies a JWT with the public key and returns the decoded payload.
+   * @param {string} token
+   * @return {Promise<IJWTPayload>}
+   */
+  verifyToken(token: string): Promise<IJWTPayload>;
+}
+
+/**
+ * JWT Validator
+ */
+class JwtValidator implements IJwtValidator {
+  public async verifyAuthorizationHeader(header: string): Promise<IJWTPayload> {
+    if (utils.isBlank(header)) {
+      throw createInvalidAuthHeaderError({
+        code: constants.errors.codes.NULL_VALUE,
+        target: 'Authorization header',
+        message: 'Empty Authorization header',
+      });
+    }
+
+    const parts: string[] = header.trim().split(' ');
+    if (parts[0] !== 'Bearer') {
+      throw createInvalidAuthHeaderError({
+        code: constants.errors.codes.INVALID_VALUE,
+        target: 'Authorization header',
+        message: 'Bad authentication scheme, "Bearer" required',
+      });
+    }
+
+    return await this.verifyToken(parts[1]);
+  }
+
+  public async verifyToken(token: string): Promise<IJWTPayload> {
+    const payload = this.parseJwt(token);
+
+    const key = await this.getJwtPublicKey(payload);
+
+    this.validateJwtCreationTimestamp(payload, key);
+    this.validateJwtExpirationTimestamp(payload, key);
+
+    return this.verifyJwt(token, key.publicKey);
+  }
+
+  private parseJwt(token: string): IJWTPayload {
+    const payload: IJWTPayload = jwt.decode(token) as IJWTPayload;
+    if (!payload) {
+      throw createInvalidJwtError({
+        code: constants.errors.codes.INVALID_VALUE,
+        target: 'jwt',
+        message: 'jwt malformed',
+      });
+    }
+    return payload;
+  }
+
+  private verifyJwt(token: string, publicKey: string): IJWTPayload {
+    let payload: any;
+    try {
+      payload = jwt.verify(token, publicKey);
+    } catch (err) {
+      throw createInvalidJwtError({
+        code: constants.errors.codes.INVALID_VALUE,
+        target: 'jwt',
+        message: err.message,
+      });
+    }
+
+    if (isJWTPayload(payload)) {
+      return payload;
+    }
+    throw createInvalidJwtError({
+      code: constants.errors.codes.INVALID_VALUE,
+      target: 'jwt',
+      message: 'expected a valid JWT payload',
+    });
+  }
+
+  private async getJwtPublicKey(payload: IJWTPayload): Promise<IPublicKey> {
+    const keyId = payload.keyId;
+    if (!keyId || keyId <= 0) {
+      throw createInvalidJwtError({
+        code: constants.errors.codes.INVALID_VALUE,
+        target: 'jwt',
+        message: 'missing public key ID',
+      });
+    }
+
+    const key: IPublicKey = await cachedPublicKeyRepository.getOne(keyId);
+
+    // Check key state
+    if (!key || key.state !== PublicKeyState.ACTIVE) {
+      throw createInvalidJwtError({
+        code: constants.errors.codes.INVALID_VALUE,
+        target: 'jwt',
+        message: 'this keyId is no longer active',
+      });
+    }
+    return key;
+  }
+
+  private validateJwtCreationTimestamp(payload: IJWTPayload, key: IPublicKey) {
+    // Check the jwt was not created before the creation date of the key
+    const payloadIat: moment.Moment = moment.utc(payload.iat * 1000);
+    const keyCreatedAt: moment.Moment = moment.utc(key.createdAt);
+    if (payloadIat.diff(keyCreatedAt) < 0) {
+      throw createInvalidJwtError({
+        code: constants.errors.codes.INVALID_VALUE,
+        target: 'jwt',
+        message: "this jwt can't be created before the public key",
+      });
+    }
+  }
+
+  private validateJwtExpirationTimestamp(payload: IJWTPayload, key: IPublicKey) {
+    // Check expiration date
+    if (key.expiresAt) {
+      const keyexpiresAt: moment.Moment = moment.utc(key.expiresAt);
+      if (moment.utc().diff(keyexpiresAt) > 0) {
+        throw createInvalidJwtError({
+          code: constants.errors.codes.INVALID_VALUE,
+          target: 'jwt',
+          message: 'this keyId is expired',
+        });
+      }
+
+      // Check the jwt was not created after the expiration date of the key
+      const payloadIat: moment.Moment = moment.utc(payload.iat * 1000);
+      if (payloadIat.diff(keyexpiresAt) > 0) {
+        throw createInvalidJwtError({
+          code: constants.errors.codes.INVALID_VALUE,
+          target: 'jwt',
+          message: "this jwt can't be created after the expiration of the public key",
+        });
+      }
+    }
+  }
+}
+
+export const jwtValidator: IJwtValidator = new JwtValidator();

package/src/middleware/jwtMiddleware.ts

@@ -0,0 +1,33 @@
+import * as express from 'express';
+import httpHeaderFieldsTyped from 'http-header-fields-typed';
+import { constants } from '../config/constants';
+import { jwtValidator } from '../jwtValidator';
+
+/**
+ * JWT validation Middleware
+ *
+ * @param {boolean} mandatoryValidation Defines if the JWT is mandatory. Defaults to true.
+ */
+export const jwtValidationMiddleware: (
+  mandatoryValidation?: boolean
+) => (req: express.Request, res: express.Response, next: express.NextFunction) => Promise<void> = (
+  mandatoryValidation = true
+) => {
+  return async (
+    req: express.Request,
+    res: express.Response,
+    next: express.NextFunction
+  ): Promise<void> => {
+    try {
+      const authHeader: string = req.get(httpHeaderFieldsTyped.AUTHORIZATION);
+      if (mandatoryValidation || authHeader) {
+        req[constants.requestExtraVariables.JWT] = await jwtValidator.verifyAuthorizationHeader(
+          authHeader
+        );
+      }
+      next();
+    } catch (err) {
+      next(err);
+    }
+  };
+};

package/src/models/customError.ts

@@ -0,0 +1,37 @@
+import { createError, IApiError, IApiErrorAndInfo } from '@villedemontreal/general-utils';
+import { LogLevel } from '@villedemontreal/logger';
+import * as HttpStatusCodes from 'http-status-codes';
+import { constants } from '../config/constants';
+
+/**
+ * Easily creates an "InvalidJWT" error (401). To throw when
+ * the user has a bad/expired JWT
+ */
+export function createInvalidJwtError(detail: IApiError): IApiErrorAndInfo {
+  return createError(constants.errors.codes.INVALID_JWT, 'Invalid JWT')
+    .httpStatus(HttpStatusCodes.UNAUTHORIZED)
+    .target('Authorization header')
+    .publicMessage('Invalid JWT')
+    .logLevel(LogLevel.ERROR)
+    .logStackTrace(false)
+    .addDetail(detail)
+    .build();
+}
+
+/**
+ * Easily creates an "invalidAuthHedaer" error (401). To throw when
+ * the user has a bad authorization header
+ */
+export function createInvalidAuthHeaderError(detail: IApiError): IApiErrorAndInfo {
+  return createError(
+    constants.errors.codes.INVALID_AUTHORIZATION_HEADER,
+    'Invalid Authorization header'
+  )
+    .httpStatus(HttpStatusCodes.UNAUTHORIZED)
+    .target('Authorization header')
+    .publicMessage('Invalid Authorization header')
+    .logLevel(LogLevel.ERROR)
+    .logStackTrace(false)
+    .addDetail(detail)
+    .build();
+}

package/src/models/expressRequest.ts

@@ -0,0 +1,27 @@
+/**
+ * Extend Express Request object
+ */
+import * as express from 'express';
+import * as _ from 'lodash';
+import { constants } from '../config/constants';
+import { IJWTPayload } from '../models/jwtPayload';
+
+export interface IRequestWithJwt extends express.Request {
+  /**
+   * The JSON Web Token of the request.
+   */
+  jwt: IJWTPayload;
+}
+
+/**
+ * Request with JWT Type Guard
+ */
+export const isRequestWithJwt = (obj: any): obj is IRequestWithJwt => {
+  return (
+    obj &&
+    _.isObject(obj) &&
+    'get' in obj &&
+    'headers' in obj &&
+    constants.requestExtraVariables.JWT in obj
+  );
+};

package/src/models/gluuUserType.ts

@@ -0,0 +1,9 @@
+/**
+ * The possible values of the "userType", in a JWT.
+ * Note that an empty (or non existent) "userType"
+ * means it is the JWT of a regular citizen.
+ */
+export enum GluuUserType {
+  EMPLOYEE = 'employee',
+  SERVICE_ACCOUNT = 'serviceAccount',
+}

package/src/models/jwtPayload.ts

@@ -0,0 +1,58 @@
+import * as _ from 'lodash';
+
+/**
+ * A JWT payload
+ */
+export interface IJWTPayload {
+  // TODO more comments on those properties!
+
+  accessToken: string;
+  iss: string;
+
+  // JWT information
+  // From Introspect
+  exp: number;
+  iat: number;
+  keyId: number;
+
+  // From ClientInfo
+  displayName: string;
+  aud: string;
+
+  // From UserInfo
+  name: string;
+  sub: string;
+
+  /**
+   * @deprecated Please use mtlIdentityId or userName instead.
+   */
+  inum: string;
+
+  userName: string;
+  givenName: string;
+  familyName: string;
+  userType: string;
+  email?: string;
+
+  // Corresponds to oro identity-id or inum
+  mtlIdentityId?: string;
+  // available only for employees
+  employeeNumber?: string;
+  customData?: any;
+}
+
+/**
+ * IJWTPayload Type Guard
+ */
+export const isJWTPayload = (obj: any): obj is IJWTPayload => {
+  return (
+    obj &&
+    _.isObject(obj) &&
+    'accessToken' in obj &&
+    'iss' in obj &&
+    'exp' in obj &&
+    'iat' in obj &&
+    'sub' in obj &&
+    'keyId' in obj
+  );
+};

package/src/models/pagination.ts

@@ -0,0 +1,26 @@
+/**
+ * Represents a paginated result set. This follows the doc :
+ * https://villemontreal.atlassian.net/wiki/display/AES/REST+API#RESTAPI-Pagination.1
+ */
+export interface IPaginatedResult<T> {
+  paging: {
+    offset: number;
+    limit: number;
+    totalCount: number;
+  };
+  items: T[];
+}
+
+/**
+ * IPaginatedResult Type Guard
+ */
+export const isPaginatedResult = (obj: any): obj is IPaginatedResult<any> => {
+  return (
+    obj &&
+    'paging' in obj &&
+    'offset' in obj.paging &&
+    'limit' in obj.paging &&
+    'totalCount' in obj.paging &&
+    'items' in obj
+  );
+};

package/src/models/publicKey.ts

@@ -0,0 +1,33 @@
+/**
+ * The content of public key
+ */
+export interface IPublicKey {
+  id: number;
+  algorithm: string;
+  publicKey: string;
+  state: PublicKeyState;
+  createdAt?: string;
+  expiresAt?: string;
+}
+
+/**
+ * List of public key with keyId as key
+ */
+export interface IPublicKeys {
+  [keyId: number]: IPublicKey;
+}
+
+/**
+ * Array of public key
+ */
+// tslint:disable-next-line:no-empty-interface
+export type IPublicKeysList = Array<IPublicKey>;
+
+/**
+ * Public key state
+ */
+export enum PublicKeyState {
+  ACTIVE = 'active',
+  EXPIRED = 'expired',
+  REVOKED = 'revoked',
+}

package/src/repositories/cachedPublicKeyRepository.ts

@@ -0,0 +1,121 @@
+import { ApiErrorAndInfo } from '@villedemontreal/general-utils/dist/src';
+import { extend } from 'lodash';
+import * as moment from 'moment';
+import { configs } from '../config/configs';
+import { IPublicKey, IPublicKeys } from '../models/publicKey';
+import { createLogger } from '../utils/logger';
+import { IPublicKeyRepository, publicKeyRepository } from './publicKeyRepository';
+const logger = createLogger('CachedPublicKeyRepository');
+
+/**
+ * Cached Public Key repository
+ */
+export interface ICachedPublicKeyRepository extends IPublicKeyRepository {
+  /**
+   * Clears the public keys in cache
+   */
+  clearCache(): void;
+}
+
+export class CachedPublicKeyRepository implements ICachedPublicKeyRepository {
+  /**
+   * Next update
+   */
+  private _nextUpdate: moment.Moment;
+
+  /**
+   * Cached public keys
+   */
+  private _cachedKeys: IPublicKeys = {};
+
+  /**
+   * Clears the public keys in cache
+   */
+  public clearCache(): void {
+    this._cachedKeys = {};
+    this._nextUpdate = moment.utc();
+  }
+
+  /**
+   * Return the last public keys
+   * @return {Promise<IPublicKeys>}
+   */
+  public async getAll(): Promise<IPublicKeys> {
+    if (!this.isValidCache()) {
+      const keysList: IPublicKeys = await publicKeyRepository.getAll();
+
+      if (keysList) {
+        this.updateNextCacheUpdate();
+        this._cachedKeys = extend(this._cachedKeys, keysList);
+      }
+    }
+    return this._cachedKeys;
+  }
+
+  /**
+   * Return one public key
+   * @param {number} keyId
+   * @return {Promise<IPublicKey>}
+   */
+  public async getOne(keyId: number): Promise<IPublicKey> {
+    if (!this._cachedKeys[keyId] || !this.isValidCache()) {
+      // In case of network error while getting key, return the cached one
+      try {
+        const key: IPublicKey = await publicKeyRepository.getOne(keyId);
+        if (key) {
+          this.updateNextCacheUpdate();
+          this._cachedKeys[keyId] = key;
+        }
+      } catch (err) {
+        if (!this._cachedKeys[keyId] || !this.isTransientError(err)) {
+          throw err;
+        }
+        logger.error(
+          JSON.stringify(err),
+          `[getOne] There was an error getting key ${keyId}, cached value was sent as result`
+        );
+      }
+    }
+    return this._cachedKeys[keyId];
+  }
+
+  /**
+   * Check if the error is a network error, server error or
+   * If true, do not throw error
+   * @return {boolean}
+   */
+  private isTransientError(err: any): boolean {
+    if (err instanceof ApiErrorAndInfo) {
+      if (err.httpStatus >= 500 || err.httpStatus === 429) return true;
+      return false;
+    }
+    // No status on a superagent network error
+    if (!err.status) return true;
+    const errStatus: number = +err.status;
+    if (errStatus >= 500 || errStatus === 429) return true;
+    return false;
+  }
+
+  /**
+   * Check if the cache is stil valid
+   * @return {boolean}
+   */
+  private isValidCache(): boolean {
+    if (!this._nextUpdate || moment.utc().diff(this._nextUpdate) >= 0) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Update the date of the next update
+   * @return
+   */
+  private updateNextCacheUpdate(): void {
+    this._nextUpdate = moment.utc().add(configs.getCacheDuration(), 'seconds');
+  }
+}
+
+export const cachedPublicKeyRepository: ICachedPublicKeyRepository =
+  new CachedPublicKeyRepository();

package/src/repositories/publicKeyRepository.ts

@@ -0,0 +1,75 @@
+import { httpUtils } from '@villedemontreal/http-request';
+import { isArray, keyBy } from 'lodash';
+import * as superagent from 'superagent';
+
+import { createError } from '@villedemontreal/general-utils';
+import { configs } from '../config/configs';
+import { constants } from '../config/constants';
+import { IPaginatedResult } from '../models/pagination';
+import { IPublicKey, IPublicKeys } from '../models/publicKey';
+
+/**
+ * Public Key repository
+ */
+export interface IPublicKeyRepository {
+  /**
+   * Return the last public keys
+   * @return {Promise<IPublicKeys>}
+   */
+  getAll(): Promise<IPublicKeys>;
+
+  /**
+   * Returns one public key.
+   * Returns null if not found.
+   * @param {number} keyId
+   * @return {Promise<IPublicKey>}
+   */
+  getOne(keyId: number): Promise<IPublicKey>;
+}
+
+class PublicKeyRepository implements IPublicKeyRepository {
+  public async getAll(): Promise<IPublicKeys> {
+    const url = `${httpUtils.urlJoin(
+      configs.getHost(),
+      configs.getEndpoint()
+    )}?${configs.getFetchKeysParameters()}`;
+    const request = superagent.get(url);
+
+    const response = await httpUtils.send(request);
+    if (!response.ok) {
+      throw new Error(`An error occured calling ${url} : ${response.error}`);
+    }
+
+    const data: IPaginatedResult<IPublicKey> = response.body;
+    if (data && data.items && isArray(data.items)) {
+      const newKeys: IPublicKeys = keyBy(data.items, (item) => item.id);
+      return newKeys;
+    }
+    return null;
+  }
+
+  public async getOne(keyId: number): Promise<IPublicKey> {
+    const url = httpUtils.urlJoin(configs.getHost(), configs.getEndpoint(), keyId.toString());
+    const request = superagent.get(url);
+
+    const response = await httpUtils.send(request);
+    if (!response.ok) {
+      // ==========================================
+      // Not found: we return null
+      // ==========================================
+      if (response.status === 404) {
+        return null;
+      }
+
+      throw createError(
+        constants.errors.codes.UNABLE_TO_GET_PUBLIC_KEY,
+        `An error occured calling ${url} : ${response.error}`
+      )
+        .httpStatus(response.status)
+        .build();
+    }
+    return response.body;
+  }
+}
+
+export const publicKeyRepository: IPublicKeyRepository = new PublicKeyRepository();