🚨 No longer maintained. Moved to @reallyland/node_mod. 🚨

signatur

Sign and unsign HTTP request with ease

---

It is always a recommended best practice to sign every HTTP request that contains any payload to ensure that the payload that sends along has not been tampered with. This module provides some handy methods to sign and unsign the data payload.

Table of contents

• Table of contents
• Pre-requisites
• Setup
  • Install
  • Usage
    • Node.js
    • Native ES modules or TypeScript
• API Reference
  • SignaturError
  • SignaturOptions
  • sign(data, secret[, options])
  • unsign(signature, secret[, options])
  • signSync(data, secret[, options])
  • unsignSync(data, secret[, options])
• License

Pre-requisites

• Node.js >= 8.9.0
• NPM >= 5.5.1 (NPM comes with Node.js so there is no need to install separately.)

Setup

Install

# Install via NPM
$ npm install --save @motss/signatur

Usage

Node.js

const {
  sign,
  unsign,

  // signSync,
  // unsignSync,
} = require('@motss/signatur');

void async main() {
  const payload = {
    id: 'b4cd8c1',
    t: '1580581220222',
  };
  const signedRequest = await sign(payload, {
    secret: 'fixed-secret',
    separator: ':',
  });

  assert.strictEqual(
    signedRequest,
    'eyJpZCI6ImI0Y2Q4YzEiLCJ0IjoiMTU4MDU4MTIyMDIyMiJ9:vXRKs8XZlLq1iJrPaYDsBsrLegjedzUCd3pnQqMB2Qg'
  ); // OK

  try {
    await unsign(
      'eyJpZCI6ImI0Y2Q4YzEiLCJ0IjoiMTU4MDU4MTIyMDIyMiJ9:vXRKs8XZlLq1iJrPaYDsBsrLegjedzUCd3pnQqMB2Qg',
      {
        secret: 'fixed-secret',
        // separator: ':',
        // error: new Error('Bad signature detected'),
      }
    );
  } catch (e) {
    assert.deepEqual(e, {
      error: {
        type: 'invalid-signature',
        message: 'Signature not match',
      },
    }); // OK
  }
}()

Native ES modules or TypeScript

// @ts-check

import {
  sign,
  unsign,

  // signSync,
  // unsignSync,
} from '@motss/signatur';

void async main() {
  const payload = {
    id: 'b4cd8c1',
    t: '1580581220222',
  };
  const signedRequest = await sign(payload, {
    secret: 'fixed-secret',
    separator: ':',
  });

  assert.strictEqual(
    signedRequest,
    'eyJpZCI6ImI0Y2Q4YzEiLCJ0IjoiMTU4MDU4MTIyMDIyMiJ9:vXRKs8XZlLq1iJrPaYDsBsrLegjedzUCd3pnQqMB2Qg'
  ); // OK

  try {
    await unsign(
      'eyJpZCI6ImI0Y2Q4YzEiLCJ0IjoiMTU4MDU4MTIyMDIyMiJ9:vXRKs8XZlLq1iJrPaYDsBsrLegjedzUCd3pnQqMB2Qg',
      {
        secret: 'fixed-secret',
        // separator: ':',
        // error: new Error('Bad signature detected'),
      }
    );
  } catch (e) {
    assert.deepEqual(e, {
      error: {
        type: 'invalid-signature',
        message: 'Signature not match',
      },
    }); // OK
  }
}()

API Reference

SignaturError

• error <Object> Error object for bad signature.
  • type <string> Error type. Defaults to invalid-signature.
  • message <string> Error message. Defauls to Signature not match.

SignaturOptions

• separator <?string> Optional separator. Defaults to period (.).

---

sign(data, secret[, options])

• data <T> Raw data payload in the type of T.
• secret <string> Secret used to encrypt the data payload.
• options <?SignaturOptions> Options for signing the payload.
• returns: <Promise<string>> Promise which resolves with a URL-safe base64 encoded HMAC-SHA256 signature that encrypts the raw data payload with a required secret key.

unsign(signature, secret[, options])

• signature <string> URL-safe signature.
• secret <string> Secret used to encrypt the data payload.
• options <?SignaturOptions> Options for signing the payload.
• returns: <Promise<T>> Promise which resolves with decoded data payload in the type of T.

Throws a error object for bad signature in the type of SignaturError.

signSync(data, secret[, options])

This methods works the same as sign(data, secret[, options]) except that this is the synchronous version.

unsignSync(data, secret[, options])

This methods works the same as unsign(signature, secret[, options]) except that this is the synchronous version.

License

MIT License © Rong Sen Ng