v0.7.0

How to migrate from v0.6

• Install the last version of the CLI: npm install -g @foal/cli.
• Update the dependencies in your package.json:

{
   ...
  "dependencies": {
    "@foal/core": "~0.7.0",
    "@foal/ejs": "~0.7.0",
    "@foal/typeorm": "~0.7.0",
    ...
  }
}

• Replace parsePassword with encryptPassword(password, { legacy: true })
• Remove the hook AuthenticateWithSessionAndCookie (you might need to use the LoginOptional hook in some situations)
• Import fetchUser from @foal/typeorm and replace @LoginRequired() by @LoginRequired({ user: fetchUser(User) )}
• Rename AbstractUser to UserWithPermissions and import it from @foal/typeorm
• Import EntityResourceCollection, EmailAuthenticator, emailSchema, middleware, Group, Permission and PermissionRequired from @foal/typeorm instead of @foal/core.

General Notes

The purpose of this release is to make the code of FoalTS less complex, more readable and modular and to add the support of recent technologies (JWT). It introduces some changes and improvements listed below.

The AuthenticationWithSessionAndCookie and LoginRequired hooks have been merged

In previous versions of FoalTS, AuthenticationWithSessionAndCookie and LoginRequired were both required to authenticate and restrict access to authenticated users. They have been merged into one hook LoginRequired for simplicity (and consistency with the JWTRequired hook presented below). A new hook LoginOptional has also been added in this version.

Old code:

import { AuthenticationWithSessionAndCookie, LoginRequired, Get } from '@foal/core';
...

@AuthenticationWithSessionAndCookie(User)
export class AppController {

  @Get('/')
  index(ctx) {
    const name = ctx.user ? ctx.user.name : 'you';
    return new HttpResponseOK(`Hello ${name}!`);
  }

  @Get('/home')
  @LoginRequired({ redirect: '/' })
  home(ctx) {
    return new HttpResponseOK(`Hello ${ctx.user.name}!`);
  }

}

New code:

import { LoginOptional, LoginRequired, Get } from '@foal/core';
import { fetchUser } from '@foal/typeorm';
...

export class AppController {

  @Get('/')
  @LoginOptional({ user: fetchUser(User) })
  index(ctx) {
    const name = ctx.user ? ctx.user.name : 'you';
    return new HttpResponseOK(`Hello ${name}!`);
  }

  @Get('/home')
  @LoginRequired({ redirect: '/', user: fetchUser(User) })
  home(ctx) {
    return new HttpResponseOK(`Hello ${ctx.user.name}!`);
  }

}

Support of JWT with JWTRequired and JWTOptional

This release adds the support of JWT for authentication. The two new hooks JWTRequired and JWTOptional are similar to LoginRequired and LoginOptional.

Example:

import { Get, isInFile } from '@foal/core';
import { JWTRequired } from '@foal/jwt';
import { fetchUser } from '@foal/typeorm';

export class AppController {
  @Get('/home')
  @JWTRequired()
  home(ctx) {
    return new HttpResponseOK(`Hello ${ctx.user.name}!`);
  }
}

export class AppController2 {
  @Get('/home')
  // With some options
  @JWTRequired({ user: fetchUser(User), blackList: isInFile('./blacklist') }, { audience: 'foobar' })
  home(ctx) {
    return new HttpResponseOK(`Hello ${ctx.user.name}!`);
  }
}

Password Management with encryptPassword and verifyPassword

You can now manage password encryption directly with the encryptPassword and verifyPassword functions.

Note: The parsePassword(password) util has been removed. Use its equivalent with encryptPassword: encryptPassword(password, { legacy: true }).

The controller routes are now registered after the sub-controllers routes

In the previous versions of FoalTS, the sub-controllers' routes were registered after the controller routes. Then it was hard to display a custom 404 page when a route did not exist. In the example below, requesting /home was returning a 404 instead of 200 - 'You are on the home page!'

export class ViewController {
  @Get('/')
  index() {
    return new HttpResponseOK('Hello world');
  }

  @Get('/home')
  home() {
    return new HttpResponseOK('You are on the home page!');
  }
}

export class AppController {
  subControllers = [ ViewController ];

  @Get('*')
  notFound() {
    return new HttpResponseNotFound('The page your are looking for does not exist');
  }
}

This is now changed and this example returns a success on GET /home.

TypeORM-dependent components moved in a separate package @foal/typeorm

All TypeORM-dependent components have been moved to a separate package @foal/typeorm.

These components are:

• EmailUser and EmailAuthenticator (deprecated)
• emailSchema (deprecated)
• Middleware, RelationLoader, middleware, EntityResourceCollection (deprecated)
• Group, Permission, UserWithPermissions
• PermissionRequired
• fetchUserWithPermissions, fetchUser

This way developers can use another ORM/ODM if they want (Mongoose, Sequelize, etc)

The User class and the UserWithPermissions entity (previously named AbstractUser)

The abstract class AbstractUser has been renamed into UserWithPermissions.

Because not all applications require permissions and groups, and a different ORM can be used instead of TypeORM, the User class no longer needs to extend the class UserWithPermissions.

The type of Context['user'] is now any. You can force this type with a generic parameter: Context<User>.

The deprecated components

Due to their unnecessary complexity, some components have been deprecated and will be removed in further versions:

• IAuthenticator
• Strategy, strategy, LoginController
• IResourceCollection, CollectionParams
• RestController
• EmailUser and EmailAuthenticator
• emailSchema
• Middleware, RelationLoader, middleware, EntityResourceCollection

Here are some alternatives that you might consider:

• encryptPassword and verifyPassword
• foal generate rest-api <name> (coming in a next release in January 2019)

Features

• Fix the error ctx.request.csrfToken is not a function when the CSRF protection is disabled (issue: #283) (PR: #284).
• Add support for JWT (issue: #254) (PR: #272).
• Merge AuthenticationWithSessionAndCookie and LoginRequired into LoginRequired and LoginOptional(issue: #286) (PR: #287)
• Provide two util functions encryptPassword and verifyPassword to manage password encryption(issue: #288) (PR: #300).
• Register the controller routes after its sub-controllers (issue #289) (PR: #292).
• Move EmailAuthenticator, EmailSchema, LoginController, PermissionRequired, AbstractUser, Group, Permission, fetchUser, fetchUserWithPermissions, EntityResourceCollection to the new package @foal/typeorm (issue: #290) (PR: #293 ).
• Rename AbstractUser to UserWithPermissions and simplify the definition of Context (issue: #291) (PR: #293)
• Mark as deprecated EmailUser, EmailAuthenticator, emailSchema, Middleware, RelationLoader, middleware, EntityResourceCollection, IAuthenticator, Strategy, strategy, LoginController, IResourceCollection, CollectionParams and RestController (issue: #288) (PR: #293, #295).
• [Docs] Add API reference for each package.
• Ignore WebStorm and VSCode config directories in Git (#297).
• Change the output directory name (lib/ -> build/) (issue: #296) (PR: #301)

Contributors

@LoicPoullain
@rustamwin