2.4.0

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@tsndr/cloudflare-worker-jwt",
-  "version": "2.2.10",
+  "version": "2.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@tsndr/cloudflare-worker-jwt",
-      "version": "2.2.10",
+      "version": "2.4.0",
       "license": "MIT",
       "devDependencies": {
         "@cloudflare/workers-types": "^4.20231025.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsndr/cloudflare-worker-jwt",
-  "version": "2.2.10",
+  "version": "2.4.0",
   "description": "A lightweight JWT implementation with ZERO dependencies for Cloudflare Worker",
   "type": "module",
   "exports": "./index.js",

src/index.spec.ts

@@ -14,6 +14,11 @@ type Data = {
     [key in JwtAlgorithm]: Dataset
 }
 
+type Payload = {
+    sub: string
+    name: string
+}
+
 const data: Data = {
     'ES256': {
         public: '-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9\nq9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg==\n-----END PUBLIC KEY-----',
@@ -63,11 +68,16 @@ const data: Data = {
 
 }
 
-const payload = {
+const payload: Payload = {
     sub: "1234567890",
     name: "John Doe",
 }
 
+const unicodePayload: Payload = {
+    sub: "1234567890",
+    name: "John Doe 😎",
+}
+
 describe.each(Object.entries(data) as [JwtAlgorithm, Dataset][])('%s', (algorithm, data) => {
     let token = ''
 
@@ -77,18 +87,23 @@ describe.each(Object.entries(data) as [JwtAlgorithm, Dataset][])('%s', (algorith
     })
 
     test('decode external', async () => {
-        const decoded = jwt.decode(data.token)
+        const decoded = jwt.decode<Payload>(data.token)
         expect({
             sub: payload.sub,
             name: payload.name
         }).toMatchObject({
-            sub: decoded.payload.sub,
+            sub: decoded.payload?.sub,
             name: payload.name
         })
     })
 
     test('sign internal', async () => {
-        token = await jwt.sign(payload, data.private, algorithm)
+        token = await jwt.sign<Payload>(payload, data.private, algorithm)
+        expect(token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/)
+    })
+
+    test('sign unciode', async () => {
+        token = await jwt.sign<Payload>(unicodePayload, data.private, algorithm)
         expect(token).toMatch(/^[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+\.[a-zA-Z0-9\-_]+$/)
     })
 
@@ -98,7 +113,7 @@ describe.each(Object.entries(data) as [JwtAlgorithm, Dataset][])('%s', (algorith
             sub: payload.sub,
             name: payload.name
         }).toMatchObject({
-            sub: decoded.payload.sub,
+            sub: decoded.payload?.sub,
             name: payload.name
         })
     })

src/index.ts

@@ -3,14 +3,14 @@ if (typeof crypto === 'undefined' || !crypto.subtle)
 
 /**
  * @typedef JwtAlgorithm
- * @type {'ES256'|'ES384'|'ES512'|'HS256'|'HS384'|'HS512'|'RS256'|'RS384'|'RS512'}
+ * @type {'ES256' | 'ES384' | 'ES512' | 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512'}
  */
-export type JwtAlgorithm = 'ES256'|'ES384'|'ES512'|'HS256'|'HS384'|'HS512'|'RS256'|'RS384'|'RS512'
+export type JwtAlgorithm = 'ES256' | 'ES384' | 'ES512' | 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512'
 
 /**
  * @typedef JwtAlgorithms
  */
-export interface JwtAlgorithms {
+export type JwtAlgorithms = {
     [key: string]: SubtleCryptoImportKeyAlgorithm
 }
 
@@ -18,16 +18,14 @@ export interface JwtAlgorithms {
  * @typedef JwtHeader
  * @prop {string} [typ] Type
  */
-export interface JwtHeader {
+export type JwtHeader<T = {}> = {
     /**
      * Type (default: `"JWT"`)
      *
      * @default "JWT"
      */
     typ?: string
-
+} & T
-    [key: string]: any
-}
 
 /**
  * @typedef JwtPayload
@@ -39,7 +37,7 @@ export interface JwtHeader {
  * @prop {string} [iat] Issued At
  * @prop {string} [jti] JWT ID
  */
-export interface JwtPayload {
+export type JwtPayload<T = {}> = {
     /** Issuer */
     iss?: string
 
@@ -62,13 +60,13 @@ export interface JwtPayload {
     jti?: string
 
     [key: string]: any
-}
+} & T
 
 /**
  * @typedef JwtOptions
  * @prop {JwtAlgorithm | string} algorithm
  */
-export interface JwtOptions {
+export type JwtOptions = {
     algorithm?: JwtAlgorithm | string
 }
 
@@ -77,37 +75,32 @@ export interface JwtOptions {
  * @extends JwtOptions
  * @prop {JwtHeader} [header]
  */
-export interface JwtSignOptions extends JwtOptions {
+export type JwtSignOptions<T> = {
-    header?: JwtHeader
+    header?: JwtHeader<T>
-}
+} & JwtOptions
 
 /**
  * @typedef JwtVerifyOptions
  * @extends JwtOptions
  * @prop {boolean} [throwError=false] If `true` throw error if checks fail. (default: `false`)
  */
-export interface JwtVerifyOptions extends JwtOptions {
+export type JwtVerifyOptions = {
-    /**
-     * If `true` all expiry checks will be skipped
-    */
-    skipValidation?: boolean
-
     /**
      * If `true` throw error if checks fail. (default: `false`)
      *
      * @default false
     */
     throwError?: boolean
-}
+} & JwtOptions
 
 /**
  * @typedef JwtData
  * @prop {JwtHeader} header
  * @prop {JwtPayload} payload
  */
-export interface JwtData {
+export type JwtData<Payload = {}, Header = {}> = {
-    header: JwtHeader
+    header?: JwtHeader<Header>
-    payload: JwtPayload
+    payload?: JwtPayload<Payload>
 }
 
 const algorithms: JwtAlgorithms = {
@@ -164,7 +157,10 @@ function base64UrlToArrayBuffer(b64url: string): ArrayBuffer {
 }
 
 function textToBase64Url(str: string): string {
-    return btoa(str).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_')
+    const encoder = new TextEncoder();
+    const charCodes = encoder.encode(str);
+    const binaryStr = String.fromCharCode(...charCodes);
+    return btoa(binaryStr).replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_')
 }
 
 function pemToBinary(pem: string): ArrayBuffer {
@@ -203,35 +199,77 @@ async function importKey(key: string | JsonWebKey, algorithm: SubtleCryptoImport
     return importTextSecret(key, algorithm)
 }
 
-function decodePayload(raw: string): JwtHeader | JwtPayload | null {
+function decodePayload<T = any>(raw: string): T | undefined {
     try {
-        raw += '='.repeat(4-(raw.length % 4))
+        const bytes = Array.from(atob(raw), char => char.charCodeAt(0));
-        return JSON.parse(atob(raw))
+        const decodedString = new TextDecoder('utf-8').decode(new Uint8Array(bytes));
+
+        return JSON.parse(decodedString);
     } catch {
-        return null
+        return
     }
 }
 
+/**
+ * Signs a payload and returns the token
+ *
+ * @param {JwtPayload} payload The payload object. To use `nbf` (Not Before) and/or `exp` (Expiration Time) add `nbf` and/or `exp` to the payload.
+ * @param {string | JsonWebKey | CryptoKey} secret A string which is used to sign the payload.
+ * @param {JwtSignOptions | JwtAlgorithm | string} [options={ algorithm: 'HS256', header: { typ: 'JWT' } }] The options object or the algorithm.
+ * @throws {Error} If there's a validation issue.
+ * @returns {Promise<string>} Returns token as a `string`.
+ */
+export async function sign<Payload = {}, Header = {}>(payload: JwtPayload<Payload>, secret: string | JsonWebKey, options: JwtSignOptions<Header> | JwtAlgorithm = 'HS256'): Promise<string> {
+    if (typeof options === 'string')
+        options = { algorithm: options }
+
+    options = { algorithm: 'HS256', header: { typ: 'JWT' } as JwtHeader<Header>, ...options }
+
+    if (!payload || typeof payload !== 'object')
+        throw new Error('payload must be an object')
+
+    if (!secret || (typeof secret !== 'string' && typeof secret !== 'object'))
+        throw new Error('secret must be a string, a JWK object or a CryptoKey object')
+
+    if (typeof options.algorithm !== 'string')
+        throw new Error('options.algorithm must be a string')
+
+    const algorithm: SubtleCryptoImportKeyAlgorithm = algorithms[options.algorithm]
+
+    if (!algorithm)
+        throw new Error('algorithm not found')
+
+    if (!payload.iat)
+        payload.iat = Math.floor(Date.now() / 1000)
+
+    const partialToken = `${textToBase64Url(JSON.stringify({ ...options.header, alg: options.algorithm }))}.${textToBase64Url(JSON.stringify(payload))}`
+
+    const key = secret instanceof CryptoKey ? secret : await importKey(secret, algorithm)
+    const signature = await crypto.subtle.sign(algorithm, key, textToArrayBuffer(partialToken))
+
+    return `${partialToken}.${arrayBufferToBase64Url(signature)}`
+}
+
 /**
  * Verifies the integrity of the token and returns a boolean value.
  *
  * @param {string} token The token string generated by `jwt.sign()`.
- * @param {string | JsonWebKey} secret The string which was used to sign the payload.
+ * @param {string | JsonWebKey | CryptoKey} secret The string which was used to sign the payload.
  * @param {JWTVerifyOptions | JWTAlgorithm} options The options object or the algorithm.
  * @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, options: JwtVerifyOptions | JwtAlgorithm = { algorithm: 'HS256', skipValidation: false, throwError: false }): Promise<boolean> {
+export async function verify(token: string, secret: string | JsonWebKey | CryptoKey, options: JwtVerifyOptions | JwtAlgorithm = { algorithm: 'HS256', throwError: false }): Promise<boolean> {
     if (typeof options === 'string')
         options = { algorithm: options, throwError: false }
 
-    options = { algorithm: 'HS256', skipValidation: false, throwError: false, ...options }
+    options = { algorithm: 'HS256', throwError: false, ...options }
 
     if (typeof token !== 'string')
         throw new Error('token must be a string')
 
     if (typeof secret !== 'string' && typeof secret !== 'object')
-        throw new Error('secret must be a string or a JWK object')
+        throw new Error('secret must be a string, a JWK object or a CryptoKey object')
 
     if (typeof options.algorithm !== 'string')
         throw new Error('options.algorithm must be a string')
@@ -248,69 +286,25 @@ export async function verify(token: string, secret: string | JsonWebKey, options
 
     const { payload } = decode(token)
 
-    if (!options.skipValidation && !payload) {
+    try {
+        if (!payload)
+            throw new Error('PARSE_ERROR')
+
+        if (payload.nbf && payload.nbf > Math.floor(Date.now() / 1000))
+            throw new Error('NOT_YET_VALID')
+
+        if (payload.exp && payload.exp <= Math.floor(Date.now() / 1000))
+            throw new Error('EXPIRED')
+
+        const key = secret instanceof CryptoKey ? secret : await importKey(secret, algorithm)
+
+        return await crypto.subtle.verify(algorithm, key, base64UrlToArrayBuffer(tokenParts[2]), textToArrayBuffer(`${tokenParts[0]}.${tokenParts[1]}`))
+    } catch(err) {
         if (options.throwError)
-            throw 'PARSE_ERROR'
+            throw err
 
         return false
     }
-
-    if (!options.skipValidation && payload.nbf && payload.nbf > Math.floor(Date.now() / 1000)) {
-        if (options.throwError)
-            throw 'NOT_YET_VALID'
-
-        return false
-    }
-
-    if (!options.skipValidation && payload.exp && payload.exp <= Math.floor(Date.now() / 1000)) {
-        if (options.throwError)
-            throw 'EXPIRED'
-
-        return false
-    }
-
-    const key = await importKey(secret, algorithm)
-
-    return await crypto.subtle.verify(algorithm, key, base64UrlToArrayBuffer(tokenParts[2]), textToArrayBuffer(`${tokenParts[0]}.${tokenParts[1]}`))
-}
-
-/**
- * Signs a payload and returns the token
- *
- * @param {JwtPayload} payload The payload object. To use `nbf` (Not Before) and/or `exp` (Expiration Time) add `nbf` and/or `exp` to the payload.
- * @param {string | JsonWebKey} secret A string which is used to sign the payload.
- * @param {JwtSignOptions | JwtAlgorithm | string} [options={ algorithm: 'HS256', header: { typ: 'JWT' } }] The options object or the algorithm.
- * @throws {Error} If there's a validation issue.
- * @returns {Promise<string>} Returns token as a `string`.
- */
-export async function sign(payload: JwtPayload, secret: string | JsonWebKey, options: JwtSignOptions | JwtAlgorithm = 'HS256'): Promise<string> {
-    if (typeof options === 'string')
-        options = { algorithm: options }
-    options = { algorithm: 'HS256', header: { typ: 'JWT' }, ...options }
-
-    if (!payload || typeof payload !== 'object')
-        throw new Error('payload must be an object')
-
-    if (!secret || (typeof secret !== 'string' && typeof secret !== 'object'))
-        throw new Error('secret must be a string or a JWK object')
-
-    if (typeof options.algorithm !== 'string')
-        throw new Error('options.algorithm must be a string')
-
-    const algorithm: SubtleCryptoImportKeyAlgorithm = algorithms[options.algorithm]
-
-    if (!algorithm)
-        throw new Error('algorithm not found')
-
-    if (!payload.iat)
-        payload.iat = Math.floor(Date.now() / 1000)
-
-    const partialToken = `${textToBase64Url(JSON.stringify({ ...options.header, alg: options.algorithm }))}.${textToBase64Url(JSON.stringify(payload))}`
-
-    const key = await importKey(secret, algorithm)
-    const signature = await crypto.subtle.sign(algorithm, key, textToArrayBuffer(partialToken))
-
-    return `${partialToken}.${arrayBufferToBase64Url(signature)}`
 }
 
 /**
@@ -319,10 +313,10 @@ export async function sign(payload: JwtPayload, secret: string | JsonWebKey, opt
  * @param {string} token The token string generated by `jwt.sign()`.
  * @returns {JwtData} Returns an `object` containing `header` and `payload`.
  */
-export function decode(token: string): JwtData {
+export function decode<Payload = {}, Header = {}>(token: string): JwtData<Payload, Header> {
     return {
-        header: decodePayload(token.split('.')[0].replace(/-/g, '+').replace(/_/g, '/')) as JwtHeader,
+        header: decodePayload<JwtHeader<Header>>(token.split('.')[0].replace(/-/g, '+').replace(/_/g, '/')),
-        payload: decodePayload(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')) as JwtPayload
+        payload: decodePayload<JwtPayload<Payload>>(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/'))
     }
 }