2.5.1

.editorconfig

@@ -4,7 +4,12 @@ root = true
 end_of_line = lf
 insert_final_newline = false
 
-[src/**/*.ts]
+[{src,tests}/*.ts]
+charset = utf-8
+indent_style = space
+indent_size = 4
+
+[{src,tests}/**/*.ts]
 charset = utf-8
 indent_style = space
 indent_size = 4

README.md

@@ -85,10 +85,12 @@ Signs a payload and returns the token.
 #### Arguments
 
 Argument                 | Type               | Status   | Default     | Description
------------ | -------- | -------- | ------- | -----------
+------------------------ | ------------------ | -------- | ----------- | -----------
 `payload`                | `object`           | required | -           | The payload object. To use `nbf` (Not Before) and/or `exp` (Expiration Time) add `nbf` and/or `exp` to the payload.
 `secret`                 | `string`           | required | -           | A string which is used to sign the payload.
-`options`   | `object` | optional | `{ algorithm: 'HS256' }` | The options object supporting `algorithm` and `keyid`. (See [Available Algorithms](#available-algorithms))
+`options`                | `string`, `object` | optional | `HS256`     | Either the `algorithm` string or an object.
+`options.algorithm`      | `string`           | optional | `HS256`     | See [Available Algorithms](#available-algorithms)
+`options.keyid`          | `string`           | optional | `undefined` | The `keyid` or `kid` to be set in the header of the resulting JWT.
 
 #### `return`
 Returns token as a `string`.
@@ -101,10 +103,14 @@ Returns token as a `string`.
 Verifies the integrity of the token and returns a boolean value.
 
 Argument                 | Type               | Status   | Default | Description
------------ | -------- | -------- | ------- | -----------
+------------------------ | ------------------ | -------- | ------- | -----------
 `token`                  | `string`           | required | -       | The token string generated by `jwt.sign()`.
 `secret`                 | `string`           | required | -       | The string which was used to sign the payload.
-`options`   | `object` | optional | `{ algorithm: 'HS256', skipValidation: false, throwError: false }` | The options object supporting `algorithm`, `skipValidation` and `throwError`. (See [Available Algorithms](#available-algorithms))
+`options`                | `string`, `object` | optional | `HS256` | Either the `algorithm` string or an object.
+`options.algorithm`      | `string`           | optional | `HS256` | See [Available Algorithms](#available-algorithms)
+`options.clockTolerance` | `number`           | optional | `0`     | Clock tolerance in seconds, to help with slighly out of sync systems.
+`options.throwError`     | `boolean`          | optional | `false` | By default this we will only throw implementation errors, only set this to `true` if you want verification errors to be thrown as well.
+
 
 #### `throws`
 If `options.throwError` is `true` and the token is invalid, an error will be thrown.

package-lock.json

@@ -1,18 +1,16 @@
 {
   "name": "@tsndr/cloudflare-worker-jwt",
-  "version": "2.4.7",
+  "version": "2.5.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@tsndr/cloudflare-worker-jwt",
-      "version": "2.4.7",
+      "version": "2.5.1",
       "license": "MIT",
       "devDependencies": {
         "@cloudflare/workers-types": "^4.20240208.0",
         "@edge-runtime/vm": "^3.2.0",
-        "@types/node": "^20.11.19",
-        "ts-node": "^10.9.2",
         "typescript": "^5.3.3",
         "vitest": "^1.3.1"
       }
@@ -23,18 +21,6 @@
       "integrity": "sha512-MVGTTjZpJu4kJONvai5SdJzWIhOJbuweVZ3goI7FNyG+JdoQH41OoB+nMhLsX626vPLZVWGPIWsiSo/WZHzgQw==",
       "dev": true
     },
-    "node_modules/@cspotcode/source-map-support": {
-      "version": "0.8.1",
-      "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
-      "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==",
-      "dev": true,
-      "dependencies": {
-        "@jridgewell/trace-mapping": "0.3.9"
-      },
-      "engines": {
-        "node": ">=12"
-      }
-    },
     "node_modules/@edge-runtime/primitives": {
       "version": "4.1.0",
       "resolved": "https://registry.npmjs.org/@edge-runtime/primitives/-/primitives-4.1.0.tgz",
@@ -436,31 +422,12 @@
         "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
       }
     },
-    "node_modules/@jridgewell/resolve-uri": {
-      "version": "3.1.2",
-      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
-      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
-      "dev": true,
-      "engines": {
-        "node": ">=6.0.0"
-      }
-    },
     "node_modules/@jridgewell/sourcemap-codec": {
       "version": "1.4.15",
       "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.4.15.tgz",
       "integrity": "sha512-eF2rxCRulEKXHTRiDrDy6erMYWqNw4LPdQ8UQA4huuxaQsVeRPFl2oM8oDGxMFhJUWZf9McpLtJasDDZb/Bpeg==",
       "dev": true
     },
-    "node_modules/@jridgewell/trace-mapping": {
-      "version": "0.3.9",
-      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz",
-      "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==",
-      "dev": true,
-      "dependencies": {
-        "@jridgewell/resolve-uri": "^3.0.3",
-        "@jridgewell/sourcemap-codec": "^1.4.10"
-      }
-    },
     "node_modules/@rollup/rollup-android-arm-eabi": {
       "version": "4.12.0",
       "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.12.0.tgz",
@@ -636,30 +603,6 @@
       "integrity": "sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==",
       "dev": true
     },
-    "node_modules/@tsconfig/node10": {
-      "version": "1.0.9",
-      "resolved": "https://registry.npmjs.org/@tsconfig/node10/-/node10-1.0.9.tgz",
-      "integrity": "sha512-jNsYVVxU8v5g43Erja32laIDHXeoNvFEpX33OK4d6hljo3jDhCBDhx5dhCCTMWUojscpAagGiRkBKxpdl9fxqA==",
-      "dev": true
-    },
-    "node_modules/@tsconfig/node12": {
-      "version": "1.0.11",
-      "resolved": "https://registry.npmjs.org/@tsconfig/node12/-/node12-1.0.11.tgz",
-      "integrity": "sha512-cqefuRsh12pWyGsIoBKJA9luFu3mRxCA+ORZvA4ktLSzIuCUtWVxGIuXigEwO5/ywWFMZ2QEGKWvkZG1zDMTag==",
-      "dev": true
-    },
-    "node_modules/@tsconfig/node14": {
-      "version": "1.0.3",
-      "resolved": "https://registry.npmjs.org/@tsconfig/node14/-/node14-1.0.3.tgz",
-      "integrity": "sha512-ysT8mhdixWK6Hw3i1V2AeRqZ5WfXg1G43mqoYlM2nc6388Fq5jcXyr5mRsqViLx/GJYdoL0bfXD8nmF+Zn/Iow==",
-      "dev": true
-    },
-    "node_modules/@tsconfig/node16": {
-      "version": "1.0.4",
-      "resolved": "https://registry.npmjs.org/@tsconfig/node16/-/node16-1.0.4.tgz",
-      "integrity": "sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==",
-      "dev": true
-    },
     "node_modules/@types/estree": {
       "version": "1.0.5",
       "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.5.tgz",
@@ -671,6 +614,8 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-20.11.19.tgz",
       "integrity": "sha512-7xMnVEcZFu0DikYjWOlRq7NTPETrm7teqUT2WkQjrTIkEgUyyGdWsj/Zg8bEJt5TNklzbPD1X3fqfsHw3SpapQ==",
       "dev": true,
+      "optional": true,
+      "peer": true,
       "dependencies": {
         "undici-types": "~5.26.4"
       }
@@ -777,12 +722,6 @@
         "url": "https://github.com/chalk/ansi-styles?sponsor=1"
       }
     },
-    "node_modules/arg": {
-      "version": "4.1.3",
-      "resolved": "https://registry.npmjs.org/arg/-/arg-4.1.3.tgz",
-      "integrity": "sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==",
-      "dev": true
-    },
     "node_modules/assertion-error": {
       "version": "1.1.0",
       "resolved": "https://registry.npmjs.org/assertion-error/-/assertion-error-1.1.0.tgz",
@@ -831,12 +770,6 @@
         "node": "*"
       }
     },
-    "node_modules/create-require": {
-      "version": "1.1.1",
-      "resolved": "https://registry.npmjs.org/create-require/-/create-require-1.1.1.tgz",
-      "integrity": "sha512-dcKFX3jn0MpIaXjisoRvexIJVEKzaq7z2rZKxf+MSr9TkdmHmsU4m2lcLojrj/FHl8mk5VxMmYA+ftRkP/3oKQ==",
-      "dev": true
-    },
     "node_modules/cross-spawn": {
       "version": "7.0.3",
       "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.3.tgz",
@@ -880,15 +813,6 @@
         "node": ">=6"
       }
     },
-    "node_modules/diff": {
-      "version": "4.0.2",
-      "resolved": "https://registry.npmjs.org/diff/-/diff-4.0.2.tgz",
-      "integrity": "sha512-58lmxKSA4BNyLz+HHMUzlOEpg09FV+ev6ZMe3vJihgdxzgcwZ8VoEEPmALCZG9LmqfVoNMMKpttIYTVG6uDY7A==",
-      "dev": true,
-      "engines": {
-        "node": ">=0.3.1"
-      }
-    },
     "node_modules/diff-sequences": {
       "version": "29.6.3",
       "resolved": "https://registry.npmjs.org/diff-sequences/-/diff-sequences-29.6.3.tgz",
@@ -1079,12 +1003,6 @@
         "node": ">=12"
       }
     },
-    "node_modules/make-error": {
-      "version": "1.3.6",
-      "resolved": "https://registry.npmjs.org/make-error/-/make-error-1.3.6.tgz",
-      "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==",
-      "dev": true
-    },
     "node_modules/merge-stream": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",
@@ -1425,49 +1343,6 @@
         "node": ">=14.0.0"
       }
     },
-    "node_modules/ts-node": {
-      "version": "10.9.2",
-      "resolved": "https://registry.npmjs.org/ts-node/-/ts-node-10.9.2.tgz",
-      "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==",
-      "dev": true,
-      "dependencies": {
-        "@cspotcode/source-map-support": "^0.8.0",
-        "@tsconfig/node10": "^1.0.7",
-        "@tsconfig/node12": "^1.0.7",
-        "@tsconfig/node14": "^1.0.0",
-        "@tsconfig/node16": "^1.0.2",
-        "acorn": "^8.4.1",
-        "acorn-walk": "^8.1.1",
-        "arg": "^4.1.0",
-        "create-require": "^1.1.0",
-        "diff": "^4.0.1",
-        "make-error": "^1.1.1",
-        "v8-compile-cache-lib": "^3.0.1",
-        "yn": "3.1.1"
-      },
-      "bin": {
-        "ts-node": "dist/bin.js",
-        "ts-node-cwd": "dist/bin-cwd.js",
-        "ts-node-esm": "dist/bin-esm.js",
-        "ts-node-script": "dist/bin-script.js",
-        "ts-node-transpile-only": "dist/bin-transpile.js",
-        "ts-script": "dist/bin-script-deprecated.js"
-      },
-      "peerDependencies": {
-        "@swc/core": ">=1.2.50",
-        "@swc/wasm": ">=1.2.50",
-        "@types/node": "*",
-        "typescript": ">=2.7"
-      },
-      "peerDependenciesMeta": {
-        "@swc/core": {
-          "optional": true
-        },
-        "@swc/wasm": {
-          "optional": true
-        }
-      }
-    },
     "node_modules/type-detect": {
       "version": "4.0.8",
       "resolved": "https://registry.npmjs.org/type-detect/-/type-detect-4.0.8.tgz",
@@ -1500,13 +1375,9 @@
       "version": "5.26.5",
       "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-5.26.5.tgz",
       "integrity": "sha512-JlCMO+ehdEIKqlFxk6IfVoAUVmgz7cU7zD/h9XZ0qzeosSHmUJVOzSQvvYSYWXkFXC+IfLKSIffhv0sVZup6pA==",
-      "dev": true
+      "dev": true,
-    },
+      "optional": true,
-    "node_modules/v8-compile-cache-lib": {
+      "peer": true
-      "version": "3.0.1",
-      "resolved": "https://registry.npmjs.org/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz",
-      "integrity": "sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==",
-      "dev": true
     },
     "node_modules/vite": {
       "version": "5.1.4",
@@ -1681,15 +1552,6 @@
         "node": ">=8"
       }
     },
-    "node_modules/yn": {
-      "version": "3.1.1",
-      "resolved": "https://registry.npmjs.org/yn/-/yn-3.1.1.tgz",
-      "integrity": "sha512-Ux4ygGWsu2c7isFWe8Yu1YluJmqVhxqK2cLXNQA5AcC3QfbGNpM7fu0Y8b/z16pXLnFxZYvWhd3fhBY9DLmC6Q==",
-      "dev": true,
-      "engines": {
-        "node": ">=6"
-      }
-    },
     "node_modules/yocto-queue": {
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-1.0.0.tgz",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsndr/cloudflare-worker-jwt",
-  "version": "2.4.7",
+  "version": "2.5.1",
   "description": "A lightweight JWT implementation with ZERO dependencies for Cloudflare Worker",
   "type": "module",
   "exports": "./index.js",
@@ -32,8 +32,6 @@
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20240208.0",
     "@edge-runtime/vm": "^3.2.0",
-    "@types/node": "^20.11.19",
-    "ts-node": "^10.9.2",
     "typescript": "^5.3.3",
     "vitest": "^1.3.1"
   }

src/index.ts

@@ -99,6 +99,11 @@ export type JwtSignOptions<T> = {
  * @prop {boolean} [throwError=false] If `true` throw error if checks fail. (default: `false`)
  */
 export type JwtVerifyOptions = {
+    /**
+    * Clock tolerance to help with slightly out of sync systems
+    */
+    clockTolerance?: number
+
     /**
      * If `true` throw error if checks fail. (default: `false`)
      *
@@ -178,11 +183,10 @@ export async function sign<Payload = {}, Header = {}>(payload: JwtPayload<Payloa
  * @throws {Error | string} Throws an error `string` if the token is invalid or an `Error-Object` if there's a validation issue.
  * @returns {Promise<boolean>} Returns `true` if signature, `nbf` (if set) and `exp` (if set) are valid, otherwise returns `false`.
  */
-export async function verify(token: string, secret: string | JsonWebKey | CryptoKey, options: JwtVerifyOptions | JwtAlgorithm = { algorithm: 'HS256', throwError: false }): Promise<boolean> {
+export async function verify(token: string, secret: string | JsonWebKey | CryptoKey, options: JwtVerifyOptions | JwtAlgorithm = 'HS256'): Promise<boolean> {
     if (typeof options === 'string')
-        options = { algorithm: options, throwError: false }
+        options = { algorithm: options }
-
+    options = { algorithm: 'HS256', clockTolerance: 0, throwError: false, ...options }
-    options = { algorithm: 'HS256', throwError: false, ...options }
 
     if (typeof token !== 'string')
         throw new Error('token must be a string')
@@ -215,10 +219,12 @@ export async function verify(token: string, secret: string | JsonWebKey | Crypto
         if (!payload)
             throw new Error('PARSE_ERROR')
 
-        if (payload.nbf && payload.nbf > Math.floor(Date.now() / 1000))
+        const now = Math.floor(Date.now() / 1000)
+
+        if (payload.nbf && payload.nbf > now && Math.abs(payload.nbf - now) > (options.clockTolerance ?? 0))
             throw new Error('NOT_YET_VALID')
 
-        if (payload.exp && payload.exp <= Math.floor(Date.now() / 1000))
+        if (payload.exp && payload.exp <= now && Math.abs(payload.exp - now) > (options.clockTolerance ?? 0))
             throw new Error('EXPIRED')
 
         const key = secret instanceof CryptoKey ? secret : await importKey(secret, algorithm, ['verify'])

tests/index.spec.ts

@@ -120,3 +120,37 @@ describe.each(Object.entries(data) as [JwtAlgorithm, Dataset][])('%s', (algorith
         expect(verified).toBeTruthy()
     })
 })
+
+describe('Verify', async () => {
+    const secret = 'super-secret'
+
+    const now = Math.floor(Date.now() / 1000)
+    const offset = 30 // 30 seconds
+
+    const validToken = await jwt.sign({ sub: 'me', nbf: now - offset }, secret)
+    const notYetExpired = await jwt.sign({ sub: 'me', exp: now + offset }, secret)
+
+    const notYetValidToken = await jwt.sign({ sub: 'me', nbf: now + offset }, secret)
+    const expiredToken = await jwt.sign({ sub: 'me', exp: now - offset }, secret)
+
+    test('Valid', () => {
+        expect(jwt.verify(validToken, secret, { throwError: true })).resolves.toBe(true)
+    })
+
+    test('Not yet expired', () => {
+        expect(jwt.verify(notYetExpired, secret, { throwError: true })).resolves.toBe(true)
+    })
+
+    test('Not yet valid', () => {
+        expect(jwt.verify(notYetValidToken, secret, { throwError: true })).rejects.toThrowError('NOT_YET_VALID')
+    })
+
+    test('Expired', () => {
+        expect(jwt.verify(expiredToken, secret, { throwError: true })).rejects.toThrowError('EXPIRED')
+    })
+
+    test('Clock offset', () => {
+        expect(jwt.verify(notYetValidToken, secret, { clockTolerance: offset, throwError: true })).resolves.toBe(true)
+        expect(jwt.verify(expiredToken, secret, { clockTolerance: offset, throwError: true })).resolves.toBe(true)
+    })
+})