nn: Nonce-Next

Real Nonce (Number used only once) for node.

Install

npm install --save nonce-next

Getting Started

Easy breezy:

let nn = require('nonce-next');
 
// Generate a nonce
let nonce = nn.generate();
console.log(nonce); // Something like 123456789123
 
// Validate
console.log(nn.compare(nonce)); // True!
 
// Only once!
console.log(nn.compare(nonce)); // False!!!

How it works... And what for?

nn generates a different number every time it is called, based on your timestamp and an increasing counter.

Nonces get saved to a LRU memory store, to avoid memory leaks, and to expire automagically.

When checked, nn invalidates the last nonce, to make sure it is used only once.

Because that's the whole point!

Use for securing websites forms, like so:

routes/post-message.js

route.get('/form', (req, res, next) => {
  res.render('form', {
    nonce: nn.generate()
  });
});
 
route.post('/add', (req, res, next) => {
  if (!req.body.nonce || !req.body.message) {
    // missing params
    res.send('Fail! - missing params');
  }
 
  // compare nonce
  if(!nn.compare(req.body.nonce)) {
    // OOPS, not valid!
    res.send('Fail! - Invalid nonce');
  }
 
  res.send('OK! - Nonce is valid and message is: ', req.body.message);
});
 

views/form.ejs

<form action="/add" method="post">
  <input type="hidden" name="nonce" value="<%= nonce %>">
  <input type="text" name="message">
  <input type="submit">
</form>

Scoped nonces

Scoped nonces are a way to add an extra layer of security and organize your code

You can give your nonces one or more scopes, all of which must be present when compared:

 
let n = nn.generate({
  scope: 'A scope!'
});
 
nn.peekCompare(n);              // False!
nn.peekCompare(n, 'A scope!');  // True!
 

Docs

nn.generate([{Number} maxAge=1000*60*60*24 | {Object} props])

Generates and saves persists a nonce to LRU memory store

Can optionally receive a props object, or number specifying max age.

A number will set the nonce expiration in milliseconds.

An object may contain any of the following properties:

• {Number} expires

  Expiration, does the same as passing a number directly

• {String|String[]} scope

  A string or array of strings which will scope the nonce

Examples:

nn.generate(60000);  	// will expire in a minute
 
nn.generate({
 expires: 60000,    	// expires in a minute
 scope: 'api'       	// scoped to 'api'
});
 
nn.generate({
 scope: ['api', 'file'] // scoped to 'api' and 'file'
});

nn.compare({Number} nonce[, {String|String[]} scope])

Compares nonce, removing it from the store never to be used again!

May pass optional string of array of strings to check scope. Scope must match all strings.

Example:

let nonce1 = nn.generate({ scope: 'transaction' });
 
nn.compare(nonce1);					// False
nn.compare(nonce1, 'transaction'); 	// True
 
 
let nonce2 = nn.generate({ scope: ['transaction', 'payment'] });
 
nn.compare(nonce2);								// False
nn.compare(nonce2, 'transaction'); 				// False
nn.compare(nonce2, ['transaction', 'payment']);	// True

nn.peekCompare({Number} nonce[, {String|String[]} scope])

Compares nonce without removing it from database.

May pass optional string or array of strings to check scope. Scope must match all strings.

See nn.compare for example

nn.remove({Number} nonce)

Removes nonce from the store.

Returns the removed nonce

nn.cache

The LRU cache object, to bet down, dirty and low level