Express Router, Authentication & Testing

Static Content

We can make a web application out of our REST-API. First you need to create a folder at the root of your application, and name it for example "public". When you add an index.html file there, with the example below it will served when you send a GET request to our server.

import express from 'express'

const server = express()
server.use(express.static('public')) // defaults to root route '/'

server.get('/route', (req: Request, res: Response) => {
  res.send('OK')
})

server.listen(PORT, () => console.log('Listening to port', PORT))

Router

Express Router

Until now we have been building our routes to index.ts. This is fine for VERY small applications, but we'd like to keep our code readable even if our application grows in size.

Routers are Express classes that are dedicated to route handling. We can use them to group routes to meaningful units that share functionality. Routers do not require any installation since they are native express classes.

The following application, while still being extremely simple, already has a problem: index.ts file is doing several things.

It handles two kinds of routes and starts the server. Usually it also adds middleware and some configuration.

Most of the time it is best to separate the route handling to dedicated routers.

import express from 'express'
import authors from './approvedAuthors.js'
import articles from './articlesDao.js'

const server = express()

server.get('/authors', (req: Request, res: Response) => {
  res.send(authors)
})
server.get('/authors/:id', (req: Request, res: Response) => {
  const author = authors.find(author => author.id = req.params.id)
  res.send(author)
})
server.get('/articles', (req: Request, res: Response) => {
  res.send(articles.getAll())
})
server.post('/article', (req: Request, res: Response) => {
  const { author, article } = req.body
  const newArticle = articles.add({ author, article})
  res.send(newArticle)
})
server.listen(3000, () => console.log('Listening to port 3000'))

We create two routers, one for each logical unit: authorsRouter.ts and articlesRouter.ts. The only difference in the route definition is in the route paths.

//authorsRouter.ts
import express from 'express'
import authors from './approvedAuthors.js'

const router = express.Router()
  router.get('/', (req: Request, res: Response) => {
  res.send(authors)
})

router.get('/:id', (req: Request, res: Response) => {
  const author = authors.find(author => author.id = req.params.id)
  res.send(author)
})

export default router

//articlesRouter.ts
import express from 'express'
import articles from './articlesDao.js'

const router = express.Router()

router.get('/', (req: Request, res: Response) => {
  res.send(articles.getAll())
})

router.post('/', (req: Request, res: Response) => {
  const { author, article } = req.body
  const newArticle = articles.add({ author, article})
  res.send(newArticle)
})

export default router

Then we define index.ts to use those routers like any middleware.

Each route gets a path designation that will be used as prefix in the router.

import express from 'express'
import authorsRouter from './authorsRouter.js'
import articlesRouter from './articlesRouter.js'

const server = express()
server.use('/authors', authorsRouter)
server.use('/articles', articlesRouter)

server.listen(3000, () => {
  console.log('Listening to port 3000')
})

Authentication & authorization

Token based login

• Currently our applications are accessible for anyone, which often is not a desired state of things.
• If you don't restrict access to your endpoints, something like this might happen !!!
• Authentication & Authorization help here
  • Authentication: Verifying that you are indeed you
  • Authorization: Determining access rights based on your privileges
• We shall first look at password authorization, and later token-based authentication.

Storing passwords

Password Hashing

Passwords should never be stored as plain text in to a database. Instead a password hash should be stored instead.

Hash function maps data of any size (in our case a password) to a hash of fixed length.

Hash functions are one-way functions, which means they can not be reversed. This means that you can not deduce the original password from the hash.

We can use (a variant of) the original hash function to compare a password and the hash and deduce if the hash matches the password or not.

Salting

Bare hash functions produce identical results from identical inputs.

To add complexity, a some random data is added to the input. This data is called salt and the process of adding the salt is called salting.

This means two identical passwords produce different hashes, since both have unique salt.

Salt can be stored in the hash or it can be stored separately. The hash function needs to know the salt in order to verify passwords against the hash.

Hashing a password

We will use Argon library to do our hashing and comparing. Install Argon with npm install argon2

Using Argon to hash passwords is very straightforward. Salting is done automatically (although you can configure it in more detail if you wish to do so) and the salt is added to the hash.

import argon2 from 'argon2'

const password = process.argv[2]
argon2.hash(password)
  .then(result => console.log(result))

You can of course also use async/await syntax instead of .then()

Comparing hashes

Notice if you run the example from the previous slide multiple times, you always get a different result. In order to verify that a particular password matches the hash, Argon's verify function is used.

Verify returns a promise that resolves to either true, if the password matches the hash, or false if it doesn't.

import argon2 from 'argon2'

const hash = '$argon2id$v=19$m=4096,t=3,p=1$+OM8yk1Kd3M/709t0Hy1vg$E3aii3UmOQOp6jFJVd9xDpakMOF1O6TDd1gS1i/98HE'
const password = process.argv[2]

argon2.verify(hash, password)
  .then(passwordMatchesHash => console.log(passwordMatchesHash ? 'Correct' : 'Incorrect'))

Environment variables

dotenv Library

With dotenv library, we can create environment variables that can be loaded into process.env. We can access the environment variables in our application with process.env.<variable_name>.

To use dotenv

1. Install dotenv package with npm install dotenv
2. Create a .env file in to the root folder of your application where the values are declared
3. Import the dotenv configuration in the project import 'dotenv/config'
4. Access the variables defined in .env file const PORT = process.env.PORT

.env File

The custom environment variables are declared in the .env file. The file must be located in the folder from where the program is ran. This is usually the root folder.

The variables are declared as in the example below, separated by line changes. All values are strings (even if JS parses some automatically).

Notice there are no spaces around the equals (=) sign, nor any kind of quotation marks.

API_URL=https://cataas.com
PORT=3000

dotenv in Development

• In many cases the environment variables are configured on the platform from where the program is ran. In those cases you might want to run dotenv only in development mode.
• Install as dev dependency npm install --save-dev dotenv
• Create .env file as usual.
  • Optionally include ENVIRONMENT=development variable
• Run your application from package.json script that preloads dotenv "dev": "nodemon -r dotenv/config index.js"
• Access environment variables as usual const PORT = process.env.PORT

Token-based authentication

JSON Web Token

After verifying the identity of our user, we create a token that we send to the client. The client stores that token and attaches it to all future requests. This token is enough to identify the request as authorized.

Since the tokens are signed by us, we can also include data (such as user id) in the token. On all future requests we can rely that the id is correct since the JWT will be verified on every request.

Tokens can (and should be) equipped with expiration dates.

Creating a Token

Install the JSON Web Token package as dependency npm install jsonwebtoken

Tokens are created with the sign function that takes two parameters:

• Payload: the data we want to include in the token. It can be empty.
• Secret: either a string or a private key.

It can also accept an optional options parameter. In that we can define the expiration date, compression algorithm, or many other things.

import 'dotenv/config'
import jwt from 'jsonwebtoken'

const payload = { username: 'sugarplumfairy' }
const secret = process.env.SECRET
const options = { expiresIn: '1h'}

const token = jwt.sign(payload, secret, options)
console.log(token)

The created JWT has three parts separated by period: header, payload and signature.

Verifying a Token

Tokens are verified using the verify function that takes two parameters:

• Token: the token to be verified
• Secret: the secret that was used to create the token

The verify function can also accept an optional options parameter.

The verify function returns a decoded token. Since it has been verified against our secret, we know that the information has not been altered.

If the token is invalid, the verify function throws an error. If this error is not caught, the program crashes.

Bearer Tokens

When a user has received a token, it can be used to authenticate all future requests.

Do this by adding the field Authorization to the request header.

The value is "Bearer " plus the token.

This header can be added to requests generated by Fetch, Axios, or any other JS request library, or by API clients like Postman or Insomnia.

Then protected routes can check that the authorization header is valid, and if not, send an error message. This is usually done using authorization middleware.

Authentication Middleware

A common way is to have user routes, such as login, logout or user creation in a separate router, which requires no token.

Then all protected routes are set to use the authentication middleware.

The request parameter user is set to the verified token data and can then be used in the actual route.

const authenticate = (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
  const auth = req.get('Authorization')
  if (!auth?.startsWith('Bearer ')) {
    return res.status(401).send('Invalid token')
  }

  const token = auth.substring(7)
  const secret = process.env.SECRET

  try {
    const decodedToken = jwt.verify(token, secret)
    req.user = decodedToken
    next()
  } catch (error) {
    return res.status(401).send('Invalid token')
  }
}

router.get('/protected', authenticate, (req: Request, res: Response) => {
  res.send(`${req.user.username} accessed protected route`)
})

TypeScript: Extending Request

The above example uses a custom AuthenticatedRequest instead of regular Request as the type of the req object. This is because in TypeScript, if we try to add a new parameter, in this case "user", to a Request object, we get an error

Property 'user' does not exist on type 
'Request<ParamsDictionary, any, any, ParsedQs, Record<string, any>>'

We are trying to set a value to request property "user", but request objects are well defined objects that have no such property.

We can not add or use properties that an object does not have. This is part of the type safety that TypeScript is here to enforce. If an object is of type Request, we know exactly what the properties are.

The solution is to create an interface that extends the existing Request type. The new interface will have all the properties the Request has, plus the ones we define ourself.

interface AuthenticatedRequest extends Request {
  user?: { username: string }
}

Now our AuthenticatedRequest object can be used as a regular Request object (and hence is acceptable as a parameter to our Express route functions), and it can be used to store an object holding the authenticated username.

Supertest

Testing APIs with Supertest

Supertest is a library for testing API's. Let's see how to use it with Jest to test an Express app. Install supertest, ts-jest and the required TypeScript types with

npm install --save-dev supertest @types/supertest ts-jest

When using ESLint, also add "jest": true to .eslintrc's "env" object

import express from 'express'

const server = express()

server.get('/', (req: Request, res: Response) => {
  res.send('Hello World!')
})

server.listen(3000, () => {
  console.log('Listening to port 3000')
})

Also, add to package.json:

"jest": {
  "preset": "ts-jest",
  "testEnvironment": "node"
},

Preparing the App for Testing

We need to import our express application to the tests.

We will separate our application in two files. The server.ts defines the API server, and index.ts only starts the application.

Now we can test the server with Supertest. The startup file has no functionality we want to test.

//index.ts
import server from './server.js'

server.listen(3000, () => {
  console.log('Listening to port 3000')
})

//server.ts
import express from 'express'

const server = express()

server.get('/', (req: Request, res: Response) => {
  res.send('Hello World!')
})

export default server

Common Resources

https://www.npmjs.com/package/jest → Official repository

https://www.npmjs.com/package/supertest → Official repository

https://jestjs.io/docs/api → Jest API Docs. Very handy!

https://github.com/visionmedia/supertest → Supertest's github repository. Includes guides for basic use cases.