Webtask micro-service

Reference implementation of a secure serverless micro-service built on top of ExpressJS, Webtask and Auth0.

Status

Description

This is a reference implementation of a well structured and completely tested serveless micro-service built on top of Express, Webtask and JWT/Auth0, that aims to delivery ease for developing RESTful APIs and to remove as much roadblocks as possible on the way to production, while guaranteeing quality predictable outcome by pairing high testability/extensibility.

This implementation is used in a wider integration comprised of:

• A Zapier task that searches for #exploit on twitter every 5 minutes and sends what it found to a deployment of this codebase on Webtask
• This Webtask deployment, which receives data from Zapier or whatever authenticated source, and then sends it to a Slack channel properly formatted
• A Slack Channel where all messages posted by the webtask deployment can be seen

You can see a live demo here.

Features

• Standardized root module namespacing
• Extensible middleware definition
• Extensible resource definition
• Incoming request payload validation
• Incoming request payload json parsing
• Helmet enabled by default
• Extensible error handling definition
• Error handling for validation issues
• Error handling for authentication/authorization issues
• Support for ES7 async/await on middlewares
• Configuration based JWT authentication middleware
• Granular authorization requirements through OAuth 2.0 scopes at endpoint level
• Unit testing setup using Mocha/Chai/Sinon
• Integration testing setup using Postman/Newman
• Transparent encryptation for environment files using git-crypt with multiple keys

Getting started

Dependencies

• git-crypt >= 0.5.0
• node >= v8.1.3
• npm >= 5.1.0

Unlocking environments

In case you have access to a symetric key to unencrypted environment files on this repository, do as follows:

git-crypt unlock path/to/key

In order to see if it worked:

find . -name "*.env" | awk '!/node/ {print $0}' | while read secret_file; do echo "\n$secret_file" && cat "$secret_file"; done

If it worked, this will output some environment file's content in plain text. In case you don't have access to the symetric key:

cat env.example > local.env

This will copy the template env.example into local.env, which you should go ahead and fill with your data as follows:

$EDITOR local.env # or open with your favorite editor

Once you have a local.env properly configured, before you go any further, it is EXTREMELY important that you generate a dev key to transparently encrypt local.env, to do so you must run:

git-crypt init -k dev

This will initiate the proper key and you should be all set.

Running locally

Once you have a local.env properly configured, and your encryption key in place, just starts the application as follows:

npm install
npm start

You should see a similar output:

$ npm start
...
...
...
Listening on port 8080

Go grab your favorite API client and hack around!

Note: there is a postman collection at tests/integration/integration.postman_collection.json

Testing

Unit testing

In order to run the unit tests, just do:

npm test -- --reporter nyan # you don't actually need --reporter nyan, but I like it :)

Integration testing

In order to run the integration tests, you first need to unlock test/integration/test.postman_environment.json file, if you have access to the symetric key used to encrypt it, and you have been following the steps, it should already be decrypted, try the following:

cat test/integration/test.postman_environment.json

You should see the content of the file in plain text, in case you don't see it, create one yourself as follows:

cat test/integration/example.postman_environment.json > test/integration/test.postman_environment.json

Import it on postman and edit it to contain a valid configuration for you test environment. Once you are done, export it and replace the existent file with the same name.

You should be good to go, run the following:

npm run test:integration # no fancy flying cats here :(

Development

See DEVELOPMENT.md

Deploying

In order to deploy, you need a prod.env file unlocked, if you have access to the symetric key used to encrypt it, and you have been following the steps, it should already be decrypted, try the following:

cat prod.env

You should see the content of the file in plain text, in case you don't see it, create one yourself as follows:

cat env.example > prod.env

Edit it to contain a valid configuration for you production environment and move on to the next step.

Before you can deploy your application to webtask.io, you also need to have the wt-cli proper configured, verify it with the following command:

node_modules/.bin/wt profile ls

You should see something similar to:

Profile:     default
URL:         https://webtask.it.auth0.com
Container:   wt-2835e352db07966831e69908cbe682a4-1

If you don't have one yet, just run the command bellow and follow its instructions:

node_modules/.bin/wt init

Once you have a proper configured wt-cli, all you have to do is:

npm run deploy

This will output your webtask url, go ahead and test it out!

Future features

What will be coming soon?

• Mongoose integration
• Logs to ELK stack
• Extract library utilities to their own npm package
• Yeoman Generator

Do you miss something? Feel free to open an issue!

Configuration

Currently the following configuration is expected to be found:

AUTH=<ON or OFF>
AUTH_ISSUER=<your Auth0 domain here>
AUTH_AUDIENCE=<your Api identifier here>
AUTH_ALGORITHM=<signing algorithm here (RS256 is recommended)>
LOGGER=<ON or OFF>

# this is used on src/resources/twitter-monitor.js and can be remove if you don't need it
SLACK_URL=<your slack incoming webhook url>

Contributing

If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.

Make sure you write tests for anything you add, mainly unitary but also integration when relevant.

We follow code standard, please do the same when sending pull requests.

Licensing

The code in this project is licensed under MIT license. See LICENSE.