@villedemontreal/jwt-validator/README.md

Module to validate JWT (JSON Web Tokens)

# @villedemontreal/jwt-validator

Module to validate JWT generated by Kong

## Availabililty

https://bitbucket.org/villemontreal/core-jwt-validator-nodejs-lib

## Installation

```shell
    npm install --save @villedemontreal/jwt-validator
    yarn add @villedemontreal/jwt-validator
```

## Usage

### Initialisation

Un code utilisant cette librarie doit premièrement la configurer en appellant la fonction
"`ìnit(...)`" exportée par le fichier "`src/config/init.ts`".

```typescript
import { init as initJwtValidationLib } from '@villedemontreal/jwt-validator';
import { createLogger } from './utils/logger';
import { correlationIdService, init as initCidUtils } from '@villedemontreal/correlation-id';

// ...

export async function initComponents() {
  initJwtValidationLib(
    createLogger,
    () => {
      return correlationIdService.getId();
    },
    configs.security.jwt.host, // Optional: already defined
    configs.security.jwt.endPoint // Optional: already defined
  );

  //...
}
```

Notez qu'une fonction "`isInited()`" est exportée et permet au code appelant de valider que la librairie a été
configurée correctement!

### JWT Validation With Middleware

Route definition:

```typescript
import { jwtValidationMiddleware } from '@villedemontreal/jwt-validator';

export function getAPIRoutes(): IHandlerRoute[] {
  return [
    // Get Account Information
    {
      method: HttpMethods.GET,
      path: '/v1/accounts/:id',
      handler: accountsController.getAccount,
      middlewares: [jwtValidationMiddleware()]
    }
  ];
}
```

Global definition in `app.ts`:

```typescript
export async function createApp(apiRoutes: IHandlerRoute[]): Promise<express.Express> {
  // ...

  if (configs.security.jwt.enable) {
    let jwtMiddleware = jwtValidationMiddleware();
    app.use(function(req: express.Request, res: express.Response, next: express.NextFunction) {
      if (req && req.path && req.path.toLowerCase().startsWith(constants.EnpointTypeRoots.API)) {
        jwtMiddleware(req, res, next);
      } else {
        next();
      }
    });
  }

  // ...
}
```

#### User validation

Then in the controller, it's possible to check the ID inside the JWT:

```typescript
import { UserValidator } from "@villedemontreal/jwt-validator";

// Controller to update an account: PUT /accounts/:inum
public async update(req: express.Request, res: express.Response, next: express.NextFunction): Promise<void> {

    // Get inum from request
    let inum: string = req.params.id;

    let userValidator: UserValidator = new UserValidator(req);

    // Return if the ID is the same or not
    let same: boolean = userValidator.isUser(inum);

    // Throw an exception if the ID is not the same
    userValidator.verifyUser(inum);
}
```

#### Get JWT content

To get the JWT content, you have to cast the `req` variable with the custom type `Request` .

```typescript
import { IJWTPayload, IRequestWithJwt } from "@villedemontreal/jwt-validator";

// Controller to update an account: PUT /accounts/:inum
public async update(req: express.Request, res: express.Response, next: express.NextFunction): Promise<void> {

    // Get JWT content
    let jwtPayload: IJWTPayload = (<IRequestWithJwt>req).jwt;
}
```

### Manual JWT Validation

Validate a JWT and a JWT and the ID inside the JWT

```typescript
import { jwtValidator, IJWTPayload } from "@villedemontreal/jwt-validator";

// Controller to update an account: PUT /accounts/:inum
public async update(req: express.Request, res: express.Response, next: express.NextFunction): Promise<void> {

    // Get inum from request
    let inum: string = req.params.id;

    // Validate Authorization header, check inum in JWT and get JWT content
    let jwtPayload: IJWTPayload = await jwtValidator.verifyAuthorizationHeader(req.header('Authorization'));

    // Check the ID inside the JWT
    assert.strictEqual(jwtPayload.sub, inum);
}
```

It is also possible to check to validate directly the JWT value:

```typescript
import { jwtValidator, IJWTPayload } from '@villedemontreal/jwt-validator';

let jwt: string = '...';

// Validate JWT and get JWT content
let jwtPayload: IJWTPayload = await jwtValidator.verifyToken(jwt);
```

### Token transformation middleware

When working locally, you do not have all the infrastructure required to simulate the translation between an access token and a JWT (ex: Kong).

Prior to usage of the `jwtValidationMiddleware`, you can use the `token transformation middleware` which do an API call to exchange your access token for an extended jwt and update the authorization header.

```typescript
export async function createApp(apiRoutes: IHandlerRoute[]): Promise<express.Express> {
  // ...

  if (configs.security.jwt.enable) {
    if (configs.environment.isLocal) {
      // Required prior to the jwtValidationMiddleware
      app.use(tokenTransformationMiddleware(config));
    }

    // ...
    app.use(jwtValidationMiddleware())
  }

  // ...
}
```

## Usage For Tests

This library provides a mock tool to generate your own JWT with a signature which it will be correcly validated.

There are two parts to do this:

- The method `mockPublicKeys`, clean the public keys cache and intercept the first request to get the public keys. Then, our mock keys are inserted in the pubic keys cache.

- The method `generateJwt` allows to produce your own JWT signed with a private key.

Example of tests with mocha:

```typescript
import { jwtMock } from '@villedemontreal/jwt-validator';

describe('Test', function() {
  before(async function() {
    // Mock the public keys
    await jwtMock.mockPublicKeys();

    // Generate JWT
    let jwtToken = jwtMock.generateJwt();

    // Generate a JWT with your custom value:
    let jwtToken = jwtMock.generateJwt({
      accessToken: 'c9ba5a95-d7f9-41f9-9a24-a7e41882f7ef',
      iss: 'jwt-mock',

      // From Introspect
      exp: Date.now() + 3600,
      iat: Date.now(),
      // Use this keyId to have a valid public key
      keyId: 5,
      /*
                Key ID:
                - 1: Public Key expired with the status as "expired"
                - 2: Public Key expired WITHOUT the status as "expired"
                - 3: Public Key revoked
                - 4: Public Key still active but an expiration date is set
                - 5: Public Key active without an expiration date
            */

      // From ClientInfo
      displayName: 'Service Account',
      aud: '@!4025.CA62.9BB6.16C5!0001!2212.0010!0008!2212.0010',

      // From UserInfo
      name: 'Guillaume Smaha',
      sub: '@!4025.CA62.9BB6.16C5!0001!2212.0010!0000!0000.0001',
      inum: '@!4025.CA62.9BB6.16C5!0001!2212.0010!0000!0000.0001',
      userName: 'xsmahgu@ville.montreal.qc.ca',
      givenName: 'Guillaume',
      familyName: 'Smaha',

      customData: {
        // Role, permission, ...
      }
    });
  });

  it('should accept JWT and update password user', async function() {
    let payload: any = {
      oldPassword: 'testTest2',
      password: 'testTest3'
    };

    let response = await request(testApp)
      .put(`/api${configs.api.domainPath}/v1/accounts/${userInum}`)
      .set('Authorization', 'Bearer ' + jwtToken)
      .send(payload);

    assert.strictEqual(response.status, 200);
  });
});
```

# Builder le projet

**Note**: Sur Linux/Mac assurz-vous que le fichier `run` est exécutable. Autrement, lancez `chmod +x ./run`.

Pour lancer le build :

- > `run compile` ou `./run compile` (sur Linux/Mac)

Pour lancer les tests :

- > `run test` ou `./run test` (sur Linux/Mac)

# Mode Watch

Lors du développement, il est possible de lancer `run watch` (ou `./run watch` sur Linux/mac) dans un terminal
externe pour démarrer la compilation incrémentale. Il est alors possible de lancer certaines _launch configuration_
comme `Debug current tests file - fast` dans VsCode et ainsi déboguer le fichier de tests présentement ouvert sans
avoir à (re)compiler au préalable (la compilation incrémentale s'en sera chargé).

Notez que, par défaut, des _notifications desktop_ sont activées pour indiquer visuellement si la compilation
incrémentale est un succès ou si une erreur a été trouvée. Vous pouvez désactiver ces notifications en utilisant
`run watch --dn` (`d`isable `n`otifications).

# Déboguer le projet

Trois "_launch configurations_" sont founies pour déboguer le projet dans VSCode :

- "`Debug all tests`", la launch configuration par défaut. Lance les tests en mode debug. Vous pouvez mettre
  des breakpoints et ils seront respectés.

- "`Debug a test file`". Lance _un_ fichier de tests en mode debug. Vous pouvez mettre
  des breakpoints et ils seront respectés. Pour changer le fichier de tests à être exécuté, vous devez modifier la ligne appropriée dans le fichier "`.vscode/launch.json`".

- "`Debug current tests file`". Lance le fichier de tests _présentement ouvert_ dans VSCode en mode debug. Effectue la compîlation au préalable.

- "`Debug current tests file - fast`". Lance le fichier de tests _présentement ouvert_ dans VSCode en mode debug. Aucune compilation
  n'est effectuée au préalable. Cette launch configuration doit être utilisée lorsque la compilation incrémentale roule (voir la section "`Mode Watch`" plus haut)

# Test et publication de la librairie sur Nexus

En mergant une pull request dans la branche `develop`, un artifact "`-pre.build`" sera créé automatiquement dans Nexus. Vous
pouvez utiliser cette version temporaire de la librairie pour bien la tester dans un réel projet.

Une fois mergée dans `master`, la librairie est définitiement publiée dans Nexus, en utilisant la version spécifiée dans
le `package.json`.

## Artifact Nexus privé, lors du développement

Lors du développement d'une nouvelle fonctionnalité, sur une branche `feature`, il peut parfois être
utile de déployer une version temporaire de la librairie dans Nexus. Ceci permet de bien tester
l'utilisation de la librairie modifiée dans un vrai projet, ou même dans une autre librairie
elle-même par la suite utilisée dans un vrai projet.

Si le code à tester est terminé et prêt à être mis en commun avec d'autres développeurs, la solution
de base, comme spécifiée à la section précédante, est de merger sur `develop`: ceci créera
automatiquement un artifact "`-pre-build`" dans Nexus. Cependant, si le code est encore en développement
et vous désirez éviter de polluer la branche commune `develop` avec du code temporaire, il y a une
solution permettant de générer un artifact "`[votre prénom]-pre-build`" temporaire dans Nexus,
à partir d'une branche `feature` directement:

1. Checkoutez votre branche `feature` dans une branche nommée "`nexus`". Ce nom est
   important et correspond à une entrée dans le `Jenkinsfile`.
2. Une fois sur la branche `nexus`, ajoutez un suffixe "`-[votre prénom]`" à
   la version dans le `package.json`, par exemple: "`5.15.0-roger`".
   Ceci permet d'éviter tout conflit dans Nexus et exprime clairement qu'il
   s'agit d'une version temporaire pour votre développement privé.
3. Commitez et poussez la branche `nexus`.
4. Une fois le build Jenkins terminé, un artifact pour votre version aura été
   déployé dans Nexus. Détruire votre branche dans Bitbucket pour permettre aux
   autres developpeurs d'utiliser cette approche.

**Notez** que, lors du développement dans une branche `feature`, l'utilisation d'un simple
`npm link` local peut souvent être suffisant! Mais cette solution a ses limites, par exemple si
vous désirez tester la librairie modifiée _dans un container Docker_.

# Aide / Contributions

Pour obtenir de l'aide avec cette librairie, vous pouvez poster sur la salle Google Chat [dev-discussions](https://chat.google.com/room/AAAASmiQveI).

Notez que les contributions sous forme de pull requests sont bienvenues.