Inspired by the tiny and super useful python module "itsdangerous", used to encrypt and/or sign (JSON) data into temporary tokens for untrusted environments.

There are a symmetric encryption method and a HMAC data signing. As well as the "itsdangerous" python module, "temporary-stamp" can be really useful when sensitive data are sent thru untrusted environments before reaching the server again.

Use cases:

Encrypt an user ID for unsubscribing of newsletters into URLs. This way you don’t need to generate one-time tokens and store them in the database. Same thing with any kind of activation link for accounts and similar things.

Encrypted and/or signed objects can be stored in cookies or other untrusted sources which means you don’t need to have sessions stored on the server, which reduces the number of necessary database queries.

Signed information can safely do a roundtrip between server and client in general which makes them useful for passing server-side state to a client and then back.

$ npm install @phtdacosta/temporary-stamp --save

Why use "temporary-stamp" over crypto plain simple cipher functions?

That's why there is "temporary" in the module name. The module aims to create tokens that expire over time. It's useful specially when the data can be changed within certain time, invalidating them, or the data have to be consumed in a hurry.

This module aims to work with JSON-formatted data!

Basic usage:

The simplest use example:

Default parameters under the hood are secure enough for most use cases.

const temporaryStamp = require ( ' temporary-stamp ' ) ; const stamp = new temporaryStamp ( ) ; const token = stamp . setupToken ( 1000 , { name : ' Reeve ' , } ) ; const solved = stamp . solveToken ( token ) ;

Advanced usage:

For advanced use, further information can be set:

Only use if you really know what you are doing, otherwise any mistake or misconception will create security holes over your application.

const temporaryStamp = require ( ' temporary-stamp ' ) ; const key = crypto . randomBytes ( 32 ) ; const cipher = ' aes-256-ctr ' ; const hash = ' sha512 ' ; const iv = crypto . randomBytes ( 16 ) ; const stamp = new temporaryStamp ( key , cipher , hash , iv ) ; const token = stamp . setupToken ( 1000 , { name : ' Reeve ' , month : ' June ' , height : 188 } ) ; console . log ( stamp . verifyToken ( token ) ) ; const solve = stamp . solveToken ( token ) ;

For now, the encryption/decryption methods only use ciphers with initializing vectors (iv).

Only the symmetric encryption method supports time expiring data. Extending the support to HMAC signing is planned for the future. There are already usable HMAC signing functions, by the way their usability will be extended for the next updates.

Error handling: