Intruduction

Puremvc-Express module is a bootstrap kit to help you to build backend service. Especially for developers who are familiar with Puremvc and Express.

Usage

Initial

/** index.js */
const fs = require('fs');
const winston = require('winston');
let { CORE_EVENTS, App } = require('puremvc-express');
let options = require('./options');
let app = new App('test', options);

app.start();

/** options.js */
const winston = require('winston');
const { format } = require('winston');
const fs = require('fs');
const options = {
    httpServer: {
        port: 3000,
        sslPort: 3002,
        credentials: {
            key: fs.readFileSync('./ssl/key.pem', 'utf8'),
            cert: fs.readFileSync('./ssl/cert.pem', 'utf8')
        },
        cors: {
            credentials: true,
            origin: [
                'https://localhost:8080'
            ]
        }
    },
    database: {
        host: 'database.your.domain',
        user: 'dbuser',
        password: 'dbpassword',
        database: 'dbname',
        connectionLimit: 2
    },
    memCache: {
        host: 'redis.your.domain',
        port: 6379
    },
    firebase: {
        apiKey: 'yourFirebaseApiKey',
        authDomain: 'yourAuthDomain.firebaseapp.com',
        databaseURL: 'https://yourFirebaseProjectId.firebaseio.com',
        projectId: 'yourFirebaseProjectId',
        storageBucket: 'yourFirebaseProjectId.appspot.com',
        messagingSenderId: '1234567890',
        appId: '1:1234567890:web:0123456789abcdef',
        measurementId: 'G-0123456789'
    },
    passport: {
        jwt: {
            secret: 'yourJwtSecret',
            signOptions: {
                algorithm: 'algorithm-you-want',
                expiresIn: '900s'
            }
        },
        local: {
            usernameField: 'username',
            passwordField: 'password'
        },
        facebook: {
            clientID: 'facebookID',
            secret: 'facebookSecret',
            callbackURL: 'https://localhost:3000/auth/facebook/callback'
        },
        twitter: {
            consumerKey: 'twitterKey',
            consumerSecret: '',
            callbackURL: ''
        },
        google: {
            consumerKey: 'googleKey',
            consumerSecret: '',
            callbackURL: ''
        }
    },
    session: {
        secret: 'some secret',
        resave: false,
        saveUninitialized: false
    },
    di: {
        m_appData: 'CORE:APP-DATA',
        m_httpServer: 'CORE:HTTP-SERVER',
        m_database: 'CORE:DATABASE',
        m_passport: 'CORE:PASSPORT',
        m_memCache: 'CORE:MEM-CACHE',
        m_logger: 'CORE:LOGGER',
        m_users: 'CORE:USERS'
    },
    logger: {
        level: 'info',
        transports: [
            new winston.transports.Console({
                format: format.combine(
                    format.colorize(),
                    format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
                    format.printf(info => `${info.timestamp} ${info.level} [${info.class}]: ${info.message}`)
                )
            }),
            new winston.transports.File({
                format: format.combine(
                    format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
                    format.prettyPrint(),
                ),
                filename: 'logs/app.log'
            })
        ]
    },
    users: [
        { id: 1, username: 'root', password: 'p4s5w0rD', role: 'admin' },
        { id: 2, username: 'trumpjojo', password: '9453', role: 'author' },
        { id: 3, username: 'ingrid', password: '0908', role: 'people\'s gf' },
        { id: 4, username: 'dora', password: '9ido', role: 'amon' }
    ]
}

export default options;

Dependency Injection

This feature supports inject object which extends {puremvc.Proxy} For example

import { Mediator } from 'puremvc';
import { CORE_EVENTS } from 'puremvc-express';

export default class MyMediator extends Mediator {
    m_logger = undefined;
    logger;
    constructor () {
        super('NAME')
    }

    onRegister () {
        this.sendNotification(CORE_EVENTS.DI, this);
        // Now you can access this.m_logger
    }
}

Object injected depends on values under di of options, corresponding to the string assigned to super method. This feature use retrieveProxy in puremvc class to approach.

    consturctor () {
        super('NAME USE TO INJECT');
    }

Logger

Puremvc-Express uses Winston as logging tool, we wrap it to similar as Log4js. By following example, you can learn how to use it.

class YourClass extends SimpleCommand {
    m_logger = undefined;
    logger;

    constructor () {
        super('NAME');
    }

    execute (notification) {
        this.sendNotification(CORE_EVENTS.DI, this);
        this.logger = this.m_logger.getLogger(this.constructor.name);
        this.logger.info('Hello World');
        //2021-03-02 13:44:24.643 info [YourClass]: Hello World
    }
}

Register your customized Proxy, Mediator, Command

After puremvc-express was constructed, you can access its facade member then register following three commnand to prepare your Proxy, Mediator and Command.

let { CORE_EVENTS, App } = require('puremvc-express');

let app = new App('AppName');
let facade = app.facade;

facade.registerCommand(CORE_EVENTS.INIT_COMMANDS, YourCommandRegistor);
facade.registerCommand(CORE_EVENTS.INIT_MEDIATORS, YourMediatorRegistor);
facade.registerCommand(CORE_EVENTS.INIT_PROXIES, YourProxyRegistor);

app.options = {...options};
app.start();

Serving static files

Puremvc-express defaults serve 'public' folder

Local stretagy of Passport

In order to maping to you user data verifing, please register a command whic listening to CORE_EVENTS.USER_VERIFY.

class UserVerify extends SimpleCommand {
    m_database = undefined;
    m_logger = undefined;
    logger;

    constructor() {
        super()
    };

    async execute(notification) {
        this.sendNotification(CORE_EVENTS.DI, this);
        this.logger = this.m_logger.getLogger('UserVerify');
        let { username, password, done } = notification.body;
        let result = await this.m_database.query(
            `SELECT * from users where username like "${username}";`
        );

        let hit = await result.filter((obj, idx, ary) => {
            return obj.loginID == username;
        })
        if (hit.length && await bcrypt.compare(password, hit[0].password)) {
            done(null, hit[0]);
        } else
            done(null, false);

    }
}

facade.registerCommand(CORE_EVENTS.USER_VERIFY, UserVerify);

Authenticate required path

Puremvc-Express default provides bearer token checking mechanism for every request paths under http://localhost:3000/auth/..., the request header will need bearer token curl -H 'authorization: bearer <token>' ...

Simple Users

This kit provides you a simple way to setup your user list, assign a users key in option json, and assign an array to it.

    users: [
        { "id": 1, "username": "root", "password": "p4s5w0rD", "role": "admin" },
        { "id": 2, "username": "user001", "password": "letmein", "role": "user" },
        { "id": 3, "username": "audit001", "password": "iamwaching", "role": "audit" },
        { "id": 4, "username": "guest001", "password": "takealook", "role": "guest" }
    ]

Included API's

Sign in

This API sends notifcation CORE_EVENTS.AUTH_SIGNIN with parameter req, res, next. If there has the event name registered.

• Path: /auth/signin
• Method: POST

Sign up

This API sends notification CORE_EVENTS.AUTH_SIGNUP with parameter req, res, next. If there has the event name registered.

• Path: /auth/signup
• Method: POST

Sign JWT

• Path: /auth/signjwt
• Method: POST
• Header: content-type: application/json
• Body:

  {
      username: 'user', 
      password: 'pwd', 
      payload: {
          your:'data'
      }
  }

• Return: Bearer token using payload object.
• CURL:

  curl -H "content-type: application/json" -d '{"username":"root","password":"p4s5w0rD","payload":{"your":"data"}}' localhost:3000/auth/signjwt

Echo message

• Path: /echo/:message
• Method: ALL
• Return: message
• CURL:

  curl localhost:3000/echo/hello%20world

Authorized echo message

• Path: /api/echo/:message
• Method: ALL
• Header: authorization: bearer <token>
• Return: message
• CURL:

  curl -H "authorization: bearer <token>" localhost:3000/api/echo/hello%20world

2 Factor Authorization

Puremve-express's 2FA scheme needs two commands registered via puremvc's registerCommand. Which events was CORE_EVENTS.AUTH_REGISTER_TOTP_SECRET and CORE_EVENTS.AUTH_RETRIEVE_TOTP_SECRET, you have to use these two events to manipulate your totp secret of user.

Options

    {
        auth: {
            twofa: {
                qrCodeFormat: '[png | svg] default: png'
            }
        }
    }

Router middleware

    routerAuth.get('/path/to', passport.authenticate('2fa-totp'), (req,res,next) => yourMethod);)

class RegisterTotpSec extends SimpleCommand {
    //...
    execute(notifcation) {
        let {res, username, totpSecret} = notifcation.body;
        let user = Users.findOne(x => x.username == username);
        user.totpSecret = totpSecret;
        // Your logic here to decide what http code should be return.
        res.status(200).end()
    }
}

class RetrieveTotpSec extends SimpleCommand {
    //...
    execute(notification) {
        let {user, done} = notification.body;
        let dbUser = Users.findOne(x => x.username == user.username);
        user.totpSecret = dbUser.totpSecret;
        done(user);
    }
}

And a resource under /api/auth/2fa, it's means request to this needs with bearer token.

Retrieve QR code.

• Path: /api/auth/2fa
• Method: GET
• Header: authorization: bearer <token>
• Return: png image
  • Header: set-cookie: <cookie>
• CURL:

  curl -H "authorizatoin: bearer <token>" localhost:3000/api/auth/2fa

Confirm and register totp secret.

• Path: /api/auth/2fa
• Method: POST
• Header: authorization: bearer <token>, cookie: <cookie>
• Return: 200
• CURL:

  curl -H "authorization: bearer <token>" -H "cookie: <cookie>" -XPOST localhost:3000/api/auth/2fa

Verify totp

• Path: /api/echo/2fa/:message
• Method: GET
• Header: authorization: bearer <token>
• Return: message
• CURL:

  curl -H "authorization: bearer <token>" -d "code=<code>" localhost:3000/api/echo/2fa/message

Significant events

Puremvc-express fires following events after some specific process done. Before using these events, simply import CORE_EVENTS e.g. let { CORE_EVENTS } from 'puremvc-express'; and listen to it.

• DATABASE_CONNECTED
  Database connected.
• INIT_COMMANDS
  Time to register your own commands.
• INIT_DATABASE_TABLE
  When no tables exists in database.
• INIT_MEDIATORS
  Time to register your own mediators.
• INIT_PROXIES
  Time to register your own proxies.
• PRE_INIT_PROXIES
  Useless event unless you want override logger what we provided.
• SERVER_STARTED
  HTTP server started, it's time to register your http resource.
• USER_VERIFY
  Verfiy user via passport's local strategy, listen this event and query your own user database.

Log levels

Winston's default log levels.

• error
• warn
• info
• http
• verbose
• debug
• silly

Environment preparation

Database

docker run -d --name db \
-p 3306:3306 \
-p 33060:33060 \
-e MYSQL_ROOT_PASSWORD=rootpwd \
-e MYSQL_DATABASE=mydb \
-e MYSQL_USER=user \
-e MYSQL_PASSWORD=userpwd \
mariadb \
--character-set-server=utf8mb4 \
--collation-server=utf8mb4_unicode_ci \
--default-authentication-plugin=mysql_native_password

Sign your own SSL certificate

refer: https://github.com/FiloSottile/mkcert

docker run \
 -d \
 --rm \
 -e "domain=*.yourdo.main,yourdo.main,127.0.0.1,localhost" \
 --name mkcert \
 -v $(pwd)/ssl/:/root/.local/share/mkcert \
 vishnunair/docker-mkcert