signature-module

What is this repository for?

This JavaScript module provides tools to make the process of signing a request between servers easier. It consist on two services:

SignatureMiddleware: Node.js Express middleware in charge of checking whether a signed request is valid.

SignedRequest: Service to send signed http requests. It appends the necessary parameters to it.

How do I get set up?

1-

npm install signature-module --save

2- Include it once in your project with the sequelize instance (It is used for creating the necessary migrations)

const signature = require('signature-module')({
    appId: 'appId',
    signatureKey: 'signatureKey'
});

3- Initialize the service desired

const signatureMiddleware = signature.signatureMiddleware();

const signedRequest = signature.signedRequest('targetSecretKey');

How do I use the signatureMiddleware

Use the signatureMiddleware with your Express server to validate any incomming request.

server.use(signatureMiddleware());

How do I use the signedRequest module

Use the signed request module like you would do with the request-promise module: https://github.com/request/request-promise. The module will append the necessary values to the request (signature, appId, timestamp)

GET:

signedRequest.get({
    baseUrl: 'https://some.url.com',
    uri: `/some/uri`,
    json: true,
    qs: {
        param: 'value'
    }
})
.then(data => {})
.catch(error => {})

POST:

signedRequest.post({
    baseUrl: 'https://some.url.com',
    uri: `/some/uri`,
    json: true,
    qs: {
        param: 'value'
    },
    body: {
        param1: 'value',
        param2: 'value'
    }
})
.then(data => {})
.catch(error => {})

How does the communication between services work

Service A AppId: 'ServiceA'; IncomingSignatureKey: 'IncomingSignatureA';

Service B AppId: 'ServiceB'; IncomingSignatureKey: 'IncomingSignatureB';

To make a request from A to B Service A needs to add three extra query parameters to the request:

• appId: App Id of the sender service, in this case service A: 'ServiceA'.
• timestamp: Unix timestamp of the moment of the request
• signature: Hash containing all the request parameters signed with the Service B incomming signature key. Structure: 'stringifiedQueryParams;stringifiedBody'; Query params and body should be ordered alphabetically.

signedRequest.post('ServiceB', {
    appId: 'ServiceA',
    signature: 'SignatureHashedWithServiceBSignatureKey'
});

For Service B to validate a request coming from service A:

• Signature must have been hashed with service B incomming signature key.
• In order to validate the signature, this one (the signature) should be removed from the query string.
• The content of the request (body and query parameters) should be sorted alphabetically before stringifying it.
• AppId should be the right appId from service A.
• Timestamp should be valid (in a range of time). You can configure it initializin the signature service with the 'validOffset' option:

const signature = require('signature-module')({
    validOffset: {
        amount: 20,
        time: 'minutes'
    }
});