@prairielearn/signed-token

A package for generating signed tokens. Useful for CSRF tokens or generally to round-trip trusted data through an untrusted client.

Usage

import {
  generateSignedToken,
  getCheckedSignedTokenData,
  checkSignedToken,
} from '@prairielearn/signed-token';

const token = generateSignedToken({ foo: 'bar' }, 'SECRET_KEY');

console.log(getCheckedSignedTokenData(token, 'SECRET_KEY', { maxAge: 60 * 1000 }));
// { foo: 'bar' }

console.log(checkSignedToken(token, { foo: 'bar' }, 'SECRET_KEY', { maxAge: 60 * 1000 }));
// true

console.log(checkSignedToken(token, { foo: 'baz' }, 'SECRET_KEY', { maxAge: 60 * 1000 }));
// false

The key argument can also be an ordered, nonempty array. New tokens are always signed with the first key, while verification accepts a signature from any configured key. This supports rotation without invalidating tokens that were signed before a key change:

const oldToken = generateSignedToken({ foo: 'bar' }, 'OLD_SECRET_KEY');
const token = generateSignedToken({ foo: 'bar' }, ['NEW_SECRET_KEY', 'OLD_SECRET_KEY']);

console.log(checkSignedToken(token, { foo: 'bar' }, 'NEW_SECRET_KEY'));
// true

console.log(getCheckedSignedTokenData(oldToken, ['NEW_SECRET_KEY', 'OLD_SECRET_KEY']));
// { foo: 'bar' }