index.js

import assert from 'node:assert';
import {randomBytes} from 'node:crypto';
import Keygrip from 'keygrip';

const DESTROYED_ERROR_MSG = 'KeygripAutorotate instance is already destroyed';

/**
 * A key-signing and signature-verification helper based on Keygrip ({@link https://github.com/crypto-utils/keygrip}),
 * extended with internal auto-rotation of secrets used for signing, so any previously used secret is discarded
 * automatically after a maximum TTL.
 *
 * Signing is always done using the freshest of the secret only.
 *
 * @param {object} opts
 * @param {number} opts.totalSecrets - the number of secrets to use for signing and verification
 * @param {number} opts.ttlPerSecret - the maximum time to live per secret in millis, from its creation till being rotated out
 * @param {function():(string|Buffer)} [opts.createSecret] - function returning a new secret.
 *                                                           If omitted, secrets are auto-generated as 64 to 128 random bytes
 * @param {string} [opts.hmacAlgorithm] - defaults to 'sha256' (alternative 'sha1')
 * @param {string} [opts.encoding] - defaults to 'base64' (alternative 'hex', ... 'base64urlsafe')
 *
 * @constructor
 */
export function KeygripAutorotate(opts) {
    if (!this instanceof KeygripAutorotate) {
        throw new Error('KeygripAutorotate is a constructor');
    }

    assert(opts && typeof opts === 'object', 'invalid options');

    const {totalSecrets, ttlPerSecret, hmacAlgorithm = 'sha256', createSecret = generateRandomBytes, encoding = 'base64url'} = opts;

    assert(!isNaN(totalSecrets) && totalSecrets >= 2, 'totalSecrets should be > 2');
    assert(!isNaN(ttlPerSecret) && ttlPerSecret >= 1000, 'ttlPerSecret should be greater than 1000 (millis)');
    assert(hmacAlgorithm && typeof hmacAlgorithm === 'string', 'hmacAlgorithm must be a valid hmac algorithm or omitted');
    assert(encoding && typeof encoding === 'string', 'Invalid encoding');
    assert(typeof createSecret === 'function', 'createSecret must be a secret-generating function');
    const rotationInterval = Math.round(ttlPerSecret / totalSecrets);
    assert(rotationInterval < Math.pow(2,31), 'Secret rotation intervals over 24 days are not supported');

    const secrets = Array(totalSecrets).fill(null).map(createSecret);
    const keygrip = new Keygrip(secrets, hmacAlgorithm, encoding);

    let isDestroyed = false;

    /**
     * @type {?number} - the interval timer id while {@link periodicSecretRotate} gets called periodically.
     *                   A falsy value of `rotationTimer` means
     *                    - secrets rotation is currently paused, and
     *                    - none of the current secrets has been used for signing anything yet
     */
    let rotationTimer;

    let rotationsTillPause = 0;

    const periodicSecretRotate = function() {
        if (!rotationsTillPause) {
            clearInterval(rotationTimer);
            rotationTimer = null;
            return;
        }

        secrets.pop();
        secrets.unshift(createSecret());
        --rotationsTillPause;
    };

    /**
     * @param {string|Buffer} data
     * @return {string} a signature for data, calculated using the freshest secret
     */
    this.sign = function(data) {
        if (isDestroyed) {
            throw new Error(DESTROYED_ERROR_MSG);
        }
        rotationsTillPause = totalSecrets;
        if (!rotationTimer) {
            rotationTimer = setInterval(periodicSecretRotate, rotationInterval);
        }
        return keygrip.sign(data);
    };

    /**
     * @see https://github.com/crypto-utils/keygrip
     * @param {string|Buffer} data
     * @param {string} digest
     * @return {number} - the index of the matched secret
     */
    this.index = (data, digest) => {
        if (isDestroyed) {
            throw new Error(DESTROYED_ERROR_MSG);
        }
        return keygrip.index(data, digest);
    };

    /**
     * Verifies if the given digest was generated with any of the current secrets.
     *
     * (!) If {@link rotationTimer} is currently falsy, we know beforehand that *none* of the current secrets
     *     can have been used for signing. Let's call verify nonetheless, so the outside world can't determine
     *     the current status of rotation just through timings.
     *
     * @see https://github.com/crypto-utils/keygrip
     * @param {string|Buffer} data
     * @param {string} digest
     * @return {boolean} - true if the digest was generated with of the secrets, otherwise false
     */
    this.verify = (data, digest) => {
        if (isDestroyed) {
            throw new Error(DESTROYED_ERROR_MSG);
        }
        return keygrip.verify(data, digest) && !!rotationTimer; // ignore result if all secrets are unused
    };


    /**
     * Marks this instances destroyed and stops any running interval timer, e.g. to let the process exit without delays.
     * Subsequent calls of any other methods will throw an error.
     */
    this.destroy = function() {
        isDestroyed = true;
        if (rotationTimer) {
            clearInterval(rotationTimer)
            rotationTimer = null;
        }
    };
}

/**
 * @param {number} [minLen=64]
 * @param {number} [maxLen=128]
 * @return {Buffer}
 */
export const generateRandomBytes = (minLen = 64, maxLen = 128) => randomBytes(minLen + Math.round(Math.random() * (maxLen - minLen)));