error caching ttl (nearform#277)

* feat: error caching ttl

* feat: errorCacheTTL as function

* format: changed arrowParens to avoid

* feat: error codes exported

* fix: improved documentation

Author: marco-ippolito

README.md

@@ -56,6 +56,7 @@ The payload must be an object.
 If the `key` option is a function, the signer will also accept a Node style callback and will return a promise, supporting therefore both callback and async/await styles.
 
 If the `key` is a passphrase protected private key, the `algorithm` option must be provided and must be either a `RS*` or `ES*` encoded key and the `key` option must be an object with the following structure:
+
 ```js
 {
   key: '<YOUR_RSA_ENCRYPTED_PRIVATE_KEY>',
@@ -147,6 +148,8 @@ Create a verifier function by calling `createVerifier` and providing one or more
 
 - `cacheTTL`: The maximum time to live of a cache entry (in milliseconds). If the token has a earlier expiration or the verifier has a shorter `maxAge`, the earlier takes precedence. The default is `600000`, which is 10 minutes.
 
+- `errorCacheTTL`: A number or function `function (tokenError) => number` that represents the maximum time to live of a cache error entry (in milliseconds). Example: the `key` function fails or does not return a secret or public key. By default **errors are not cached**, the `errorCacheTTL` default value is `0`.
+
 - `allowedJti`: A string, a regular expression, an array of strings or an array of regular expressions containing allowed values for the id claim (`jti`). By default, all values are accepted.
 
 - `allowedAud`: A string, a regular expression, an array of strings or an array of regular expressions containing allowed values for the audience claim (`aud`). By default, all values are accepted.
@@ -176,7 +179,7 @@ If the `key` option is a function, the signer will also accept a Node style call
 #### Examples
 
 ```javascript
-const { createVerifier } = require('fast-jwt')
+const { createVerifier, TOKEN_ERROR_CODES } = require('fast-jwt')
 const token =
   'eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhIjoxLCJiIjoyLCJjIjozLCJpYXQiOjE1Nzk1MjEyMTJ9.mIcxteEVjbh2MnKQ3EQlojZojGSyA_guqRBYHQURcfnCSSBTT2OShF8lo9_ogjAv-5oECgmCur_cDWB7x3X53g'
 
@@ -186,7 +189,7 @@ const payload = verifySync(token)
 // => { a: 1, b: 2, c: 3, iat: 1579521212 }
 
 // Callback style with complete return
-const verifyWithCallback = createVerifier({ key: (callback) => callback(null, 'secret'), complete: true })
+const verifyWithCallback = createVerifier({ key: callback => callback(null, 'secret'), complete: true })
 
 verifyWithCallback(token, (err, sections) => {
   /*
@@ -206,6 +209,19 @@ async function test() {
   const payload = await verifyWithPromise(token)
   // => { a: 1, b: 2, c: 3, iat: 1579521212 }
 }
+
+// custom errorCacheTTL verifier
+const verifier = createVerifier({
+  key: 'secret',
+  cache: true,
+  errorCacheTTL: tokenError => {
+    // customize the ttl based on the error code
+    if (tokenError.code === TOKEN_ERROR_CODES.invalidKey) {
+      return 1000
+    }
+    return 2000
+  }
+})
 ```
 
 ## Algorithms supported
@@ -235,12 +251,18 @@ fast-jwt supports caching of verified tokens.
 
 The cache layer, powered by [mnemonist](https://www.npmjs.com/package/mnemonist), is a LRU cache which dimension is controlled by the user, as described in the options list.
 
-When caching is enabled, verified tokens are always stored in cache. If the verification fails once, the error is cached as well and the operation is not retried.
+When caching is enabled, verified tokens are always stored in cache. If the verification fails once, the error is cached as well for the time set by `errorCacheTTL` and the operation is not retried.
 
 For verified tokens, caching considers the time sensitive claims of the token (`iat`, `nbf` and `exp`) and make sure the verification is retried after a token becomes valid or after a token becomes expired.
 
 Performances improvements varies by uses cases and by the type of the operation performed and the algorithm used.
 
+> **_Note:_** Errors are not cached by default, to change this behaviour use the `errorCacheTTL` option.
+
+## Token Error Codes
+
+[Error codes](https://github.com/nearform/fast-jwt/blob/master/src/error.js) exported by `TOKEN_ERROR_CODES`.
+
 ## JWKS
 
 JWKS is supported via [get-jwks](https://github.com/nearform/get-jwks). Check out the documentation for integration examples.

prettier.config.js

@@ -3,5 +3,6 @@ module.exports = {
   semi: false,
   singleQuote: true,
   bracketSpacing: true,
-  trailingComma: 'none'
+  trailingComma: 'none',
+  arrowParens: 'avoid'
 }

src/crypto.js

@@ -18,7 +18,7 @@ const {
 let { sign: directSign, verify: directVerify } = require('crypto')
 const { joseToDer, derToJose } = require('ecdsa-sig-formatter')
 const Cache = require('mnemonist/lru-cache')
-const TokenError = require('./error')
+const { TokenError } = require('./error')
 
 const useNewCrypto = typeof directSign === 'function'
 

src/decoder.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const TokenError = require('./error')
+const { TokenError } = require('./error')
 
 function decode({ complete, checkTyp }, token) {
   // Make sure the token is a string or a Buffer - Other cases make no sense to even try to validate

src/error.js

@@ -1,5 +1,25 @@
 'use strict'
 
+const TOKEN_ERROR_CODES = {
+  invalidType: 'FAST_JWT_INVALID_TYPE', //  Invalid token type
+  invalidOption: 'FAST_JWT_INVALID_OPTION', // The option object is not valid
+  invalidAlgorithm: 'FAST_JWT_INVALID_ALGORITHM', //  The token algorithm is invalid
+  invalidClaimType: 'FAST_JWT_INVALID_CLAIM_TYPE', // The claim type is not supported
+  invalidClaimValue: 'FAST_JWT_INVALID_CLAIM_VALUE', // The claim type is not a positive integer or an number array
+  invalidKey: 'FAST_JWT_INVALID_KEY', // The key is not a string or a buffer or is unsupported
+  invalidSignature: 'FAST_JWT_INVALID_SIGNATURE', //  The token signature is invalid
+  invalidPayload: 'FAST_JWT_INVALID_PAYLOAD', // The payload to be decoded must be an object
+  malformed: 'FAST_JWT_MALFORMED', // The token is malformed
+  inactive: 'FAST_JWT_INACTIVE', // The token is not valid yet
+  expired: 'FAST_JWT_EXPIRED', // The token is expired
+  missingKey: 'FAST_JWT_MISSING_KEY', // The key option is missing
+  keyFetchingError: 'FAST_JWT_KEY_FETCHING_ERROR', // Could not retrieve the key
+  signError: 'FAST_JWT_SIGN_ERROR', // Cannot create the signature
+  verifyError: 'FAST_JWT_VERIFY_ERROR', // Cannot verify the signature
+  missingRequiredClaim: 'FAST_JWT_MISSING_REQUIRED_CLAIM', // A required claim is missing
+  missingSignature: 'FAST_JWT_MISSING_SIGNATURE' // The token signature is missing
+}
+
 class TokenError extends Error {
   constructor(code, message, additional) {
     super(message)
@@ -15,31 +35,17 @@ class TokenError extends Error {
   }
 }
 
-TokenError.codes = {
-  invalidType: 'FAST_JWT_INVALID_TYPE',
-  invalidOption: 'FAST_JWT_INVALID_OPTION',
-  invalidAlgorithm: 'FAST_JWT_INVALID_ALGORITHM',
-  invalidClaimType: 'FAST_JWT_INVALID_CLAIM_TYPE',
-  invalidClaimValue: 'FAST_JWT_INVALID_CLAIM_VALUE',
-  invalidKey: 'FAST_JWT_INVALID_KEY',
-  invalidSignature: 'FAST_JWT_INVALID_SIGNATURE',
-  invalidPayload: 'FAST_JWT_INVALID_PAYLOAD',
-  malformed: 'FAST_JWT_MALFORMED',
-  inactive: 'FAST_JWT_INACTIVE',
-  expired: 'FAST_JWT_EXPIRED',
-  missingKey: 'FAST_JWT_MISSING_KEY',
-  keyFetchingError: 'FAST_JWT_KEY_FETCHING_ERROR',
-  signError: 'FAST_JWT_SIGN_ERROR',
-  verifyError: 'FAST_JWT_VERIFY_ERROR',
-  missingRequiredClaim: 'FAST_JWT_MISSING_REQUIRED_CLAIM'
-}
+TokenError.codes = TOKEN_ERROR_CODES
 
-TokenError.wrap = function(originalError, code, message) {
+TokenError.wrap = function (originalError, code, message) {
   if (originalError instanceof TokenError) {
     return originalError
   }
 
   return new TokenError(code, message, { originalError })
 }
 
-module.exports = TokenError
+module.exports = {
+  TokenError,
+  TOKEN_ERROR_CODES
+}

src/index.d.ts

@@ -16,8 +16,26 @@ export type Algorithm =
   | 'PS512'
   | 'EdDSA'
 
+export type TokenValidationErrorCode =
+  | 'FAST_JWT_INVALID_TYPE'
+  | 'FAST_JWT_INVALID_OPTION'
+  | 'FAST_JWT_INVALID_ALGORITHM'
+  | 'FAST_JWT_INVALID_CLAIM_TYPE'
+  | 'FAST_JWT_INVALID_CLAIM_VALUE'
+  | 'FAST_JWT_INVALID_KEY'
+  | 'FAST_JWT_INVALID_SIGNATURE'
+  | 'FAST_JWT_INVALID_PAYLOAD'
+  | 'FAST_JWT_MALFORMED'
+  | 'FAST_JWT_INACTIVE'
+  | 'FAST_JWT_EXPIRED'
+  | 'FAST_JWT_MISSING_KEY'
+  | 'FAST_JWT_KEY_FETCHING_ERROR'
+  | 'FAST_JWT_SIGN_ERROR'
+  | 'FAST_JWT_VERIFY_ERROR'
+  | 'FAST_JWT_MISSING_SIGNATURE'
+
 declare class TokenError extends Error {
-  static wrap(originalError: Error, code: string, message: string): TokenError
+  static wrap(originalError: Error, code: TokenValidationErrorCode, message: string): TokenError
   static codes: {
     invalidType: 'FAST_JWT_INVALID_TYPE'
     invalidOption: 'FAST_JWT_INVALID_OPTION'
@@ -34,9 +52,10 @@ declare class TokenError extends Error {
     keyFetchingError: 'FAST_JWT_KEY_FETCHING_ERROR'
     signError: 'FAST_JWT_SIGN_ERROR'
     verifyError: 'FAST_JWT_VERIFY_ERROR'
+    missingSignature: 'FAST_JWT_MISSING_SIGNATURE'
   }
 
-  code: string;
+  code: TokenValidationErrorCode;
   [key: string]: any
 }
 
@@ -94,6 +113,7 @@ export interface VerifierOptions {
   complete: boolean
   cache: boolean | number
   cacheTTL: number
+  errorCacheTTL: number | ((tokenError: TokenError) => number)
   allowedJti: string | RegExp | Array<string | RegExp>
   allowedAud: string | RegExp | Array<string | RegExp>
   allowedIss: string | RegExp | Array<string | RegExp>

src/index.js

@@ -1,12 +1,13 @@
 'use strict'
 
-const TokenError = require('./error')
+const { TokenError, TOKEN_ERROR_CODES } = require('./error')
 const createDecoder = require('./decoder')
 const createVerifier = require('./verifier')
 const createSigner = require('./signer')
 
 module.exports = {
   TokenError,
+  TOKEN_ERROR_CODES,
   createDecoder,
   createVerifier,
   createSigner

src/signer.js

@@ -11,7 +11,7 @@ const {
   detectPrivateKeyAlgorithm,
   createSignature
 } = require('./crypto')
-const TokenError = require('./error')
+const { TokenError } = require('./error')
 const { getAsyncKey, ensurePromiseCallback } = require('./utils')
 const { createPrivateKey, createSecretKey } = require('crypto')
 

src/verifier.js

@@ -5,7 +5,7 @@ const Cache = require('mnemonist/lru-cache')
 
 const { useNewCrypto, hsAlgorithms, verifySignature, detectPublicKeyAlgorithms } = require('./crypto')
 const createDecoder = require('./decoder')
-const TokenError = require('./error')
+const { TokenError } = require('./error')
 const { getAsyncKey, ensurePromiseCallback, hashToken } = require('./utils')
 
 const defaultCacheSize = 1000
@@ -70,19 +70,38 @@ function createCache(rawSize) {
 }
 
 function cacheSet(
-  { cache, token, cacheTTL, payload, ignoreExpiration, ignoreNotBefore, maxAge, clockTimestamp, clockTolerance },
+  {
+    cache,
+    token,
+    cacheTTL,
+    payload,
+    ignoreExpiration,
+    ignoreNotBefore,
+    maxAge,
+    clockTimestamp,
+    clockTolerance,
+    errorCacheTTL
+  },
   value
 ) {
   if (!cache) {
     return value
   }
 
   const cacheValue = [value, 0, 0]
+
+  if (value instanceof TokenError) {
+    const ttl = typeof errorCacheTTL === 'function' ? errorCacheTTL(value) : errorCacheTTL
+    cacheValue[2] = (clockTimestamp || Date.now()) + clockTolerance + ttl
+    cache.set(hashToken(token), cacheValue)
+    return value
+  }
+
   const hasIat = payload && typeof payload.iat === 'number'
 
   // Add time range of the token
   if (hasIat) {
-    cacheValue[1] = !ignoreNotBefore && typeof payload.nbf === 'number' ? (payload.nbf * 1000 - clockTolerance) : 0
+    cacheValue[1] = !ignoreNotBefore && typeof payload.nbf === 'number' ? payload.nbf * 1000 - clockTolerance : 0
 
     if (!ignoreExpiration) {
       if (typeof payload.exp === 'number') {
@@ -233,7 +252,8 @@ function verify(
     validators,
     decode,
     cache,
-    requiredClaims
+    requiredClaims,
+    errorCacheTTL
   },
   token,
   cb
@@ -244,6 +264,7 @@ function verify(
     cache,
     token,
     cacheTTL,
+    errorCacheTTL,
     payload: undefined,
     ignoreExpiration,
     ignoreNotBefore,
@@ -258,9 +279,14 @@ function verify(
     const now = clockTimestamp || Date.now()
 
     // Validate time range
-    if (typeof value !== 'undefined' &&
-      (min === 0 || (now < min && value.code === 'FAST_JWT_INACTIVE') || (now >= min && value.code !== 'FAST_JWT_INACTIVE')) &&
-      (max === 0 || now <= max)) {
+    if (
+      /* istanbul ignore next */
+      typeof value !== 'undefined' &&
+      (min === 0 ||
+        (now < min && value.code === 'FAST_JWT_INACTIVE') ||
+        (now >= min && value.code !== 'FAST_JWT_INACTIVE')) &&
+      (max === 0 || now <= max)
+    ) {
       // Cache hit
       return handleCachedResult(value, callback, promise)
     }
@@ -349,6 +375,7 @@ module.exports = function createVerifier(options) {
     complete,
     cache: cacheSize,
     cacheTTL,
+    errorCacheTTL,
     checkTyp,
     clockTimestamp,
     clockTolerance,
@@ -361,7 +388,7 @@ module.exports = function createVerifier(options) {
     allowedSub,
     allowedNonce,
     requiredClaims
-  } = { cacheTTL: 600000, clockTolerance: 0, ...options }
+  } = { cacheTTL: 600000, clockTolerance: 0, errorCacheTTL: 0, ...options }
 
   // Validate options
   if (!Array.isArray(allowedAlgorithms)) {
@@ -401,6 +428,16 @@ module.exports = function createVerifier(options) {
     throw new TokenError(TokenError.codes.invalidOption, 'The cacheTTL option must be a positive number.')
   }
 
+  if (
+    (errorCacheTTL && typeof errorCacheTTL !== 'function' && typeof errorCacheTTL !== 'number') ||
+    errorCacheTTL < 0
+  ) {
+    throw new TokenError(
+      TokenError.codes.invalidOption,
+      'The errorCacheTTL option must be a positive number or a function.'
+    )
+  }
+
   if (requiredClaims && !Array.isArray(requiredClaims)) {
     throw new TokenError(TokenError.codes.invalidOption, 'The requiredClaims option must be an array.')
   }
@@ -409,11 +446,24 @@ module.exports = function createVerifier(options) {
   const validators = []
 
   if (!ignoreNotBefore) {
-    validators.push({ type: 'date', claim: 'nbf', errorCode: 'inactive', errorVerb: 'will be active', greater: true, modifier: -clockTolerance })
+    validators.push({
+      type: 'date',
+      claim: 'nbf',
+      errorCode: 'inactive',
+      errorVerb: 'will be active',
+      greater: true,
+      modifier: -clockTolerance
+    })
   }
 
   if (!ignoreExpiration) {
-    validators.push({ type: 'date', claim: 'exp', errorCode: 'expired', errorVerb: 'has expired', modifier: +clockTolerance })
+    validators.push({
+      type: 'date',
+      claim: 'exp',
+      errorCode: 'expired',
+      errorVerb: 'has expired',
+      modifier: +clockTolerance
+    })
   }
 
   if (typeof maxAge === 'number') {
@@ -450,6 +500,7 @@ module.exports = function createVerifier(options) {
     allowedAlgorithms,
     complete,
     cacheTTL,
+    errorCacheTTL,
     checkTyp: normalizedTyp,
     clockTimestamp,
     clockTolerance,