@cfworker/jwt 1.12.1 → 3.0.0

package/README.md

@@ -8,7 +8,7 @@
 
 Tiny lib for decoding JWTs and verifying signatures, using native crypto APIs.
 
-Currently supports `alg:'RS256'` only.
+Currently supports RS256, RS384, and RS512.
 
 ```js
 const jwt = request.headers.get('Authorization');

package/dist/algs.d.ts

@@ -0,0 +1,2 @@
+export declare const algToHash: Record<string, string>;
+export declare const algs: string[];

package/dist/algs.js

@@ -0,0 +1,6 @@
+export const algToHash = {
+    RS256: 'SHA-256',
+    RS384: 'SHA-384',
+    RS512: 'SHA-512'
+};
+export const algs = Object.keys(algToHash);

package/dist/decode.js

@@ -1,10 +1,11 @@
-import { decode } from '@cfworker/base64url';
+import { base64url } from 'rfc4648';
 export function decodeJwt(token) {
     const [header, payload, signature] = token.split('.');
+    const decoder = new TextDecoder();
     return {
-        header: JSON.parse(decode(header)),
-        payload: JSON.parse(decode(payload)),
-        signature: decode(signature),
+        header: JSON.parse(decoder.decode(base64url.parse(header, { loose: true }))),
+        payload: JSON.parse(decoder.decode(base64url.parse(payload, { loose: true }))),
+        signature: base64url.parse(signature, { loose: true }),
         raw: { header, payload, signature }
     };
 }

package/dist/jwks.js

@@ -1,3 +1,4 @@
+import { algToHash } from './algs.js';
 export async function getJwks(issuer) {
     const url = new URL(issuer);
     if (!url.pathname.endsWith('/')) {
@@ -12,16 +13,16 @@ export async function getJwks(issuer) {
 }
 const importedKeys = {};
 export async function importKey(iss, jwk) {
-    const input = {
-        kty: 'RSA',
-        e: 'AQAB',
-        n: jwk.n,
-        alg: 'RS256',
-        ext: true
-    };
-    const key = await crypto.subtle.importKey('jwk', input, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['verify']);
+    if (jwk.kty !== 'RSA') {
+        throw new Error(`Unsupported jwk key type (kty) "${jwk.kty}".`);
+    }
+    const hash = jwk.alg ? algToHash[jwk.alg] : null;
+    if (!hash) {
+        throw new Error(`Unsupported jwk Algorithm (alg) "${jwk.alg}".`);
+    }
+    const key = await crypto.subtle.importKey('jwk', jwk, { name: 'RSASSA-PKCS1-v1_5', hash }, false, ['verify']);
     importedKeys[iss] = importedKeys[iss] || {};
-    importedKeys[iss][jwk.kid || 'default'] = key;
+    importedKeys[iss][jwk.kid ?? 'default'] = key;
 }
 export async function getKey(decoded) {
     let { header: { kid = 'default' }, payload: { iss } } = decoded;

package/dist/parse.d.ts

@@ -1,2 +1,2 @@
-import { JwtParseResult } from './types.js';
-export declare function parseJwt(encodedToken: string, issuer: string, audience: string): Promise<JwtParseResult>;
+import { DecodedJwt, JwtParseResult } from './types.js';
+export declare function parseJwt(encodedToken: string, issuer: string, audience: string, resolveKey?: (decoded: DecodedJwt) => Promise<CryptoKey | null>): Promise<JwtParseResult>;

package/dist/parse.js

@@ -1,7 +1,9 @@
+import { algs, algToHash } from './algs.js';
 import { decodeJwt } from './decode.js';
 import { getKey } from './jwks.js';
 import { verifyJwtSignature } from './verify.js';
-export async function parseJwt(encodedToken, issuer, audience) {
+const skewMs = 30 * 1000;
+export async function parseJwt(encodedToken, issuer, audience, resolveKey = getKey) {
     let decoded;
     try {
         decoded = decodeJwt(encodedToken);
@@ -9,57 +11,120 @@ export async function parseJwt(encodedToken, issuer, audience) {
     catch {
         return { valid: false, reason: `Unable to decode JWT.` };
     }
-    if (typeof decoded.header.typ !== 'undefined' &&
-        decoded.header.typ !== 'JWT') {
+    const { typ, alg } = decoded.header;
+    if (typeof typ !== 'undefined' && typ !== 'JWT') {
         return {
             valid: false,
-            reason: `Invalid JWT type "${decoded.header.typ}". Expected "JWT".`
+            reason: `Invalid JWT type ${JSON.stringify(typ)}. Expected "JWT".`
         };
     }
-    if (decoded.header.alg !== 'RS256') {
+    if (!algToHash[alg]) {
         return {
             valid: false,
-            reason: `Invalid JWT algorithm "${decoded.header.alg}". Expected "RS256".`
+            reason: `Invalid JWT algorithm ${JSON.stringify(alg)}. Supported: ${algs}.`
         };
     }
-    if (typeof decoded.payload.aud === 'string' &&
-        decoded.payload.aud !== audience) {
+    const { sub, aud, iss, iat, exp, nbf } = decoded.payload;
+    if (typeof sub !== 'string') {
         return {
             valid: false,
-            reason: `Invalid JWT audience "${decoded.payload.aud}". Expected "${audience}".`
+            reason: `Subject claim (sub) is required and must be a string. Received ${JSON.stringify(sub)}.`
         };
     }
-    else if (Array.isArray(decoded.payload.aud) &&
-        !decoded.payload.aud.includes(audience)) {
+    if (typeof aud === 'string') {
+        if (aud !== audience) {
+            return {
+                valid: false,
+                reason: `Invalid JWT audience claim (aud) ${JSON.stringify(aud)}. Expected "${audience}".`
+            };
+        }
+    }
+    else if (Array.isArray(aud) &&
+        aud.length > 0 &&
+        aud.every(a => typeof a === 'string')) {
+        if (!aud.includes(audience)) {
+            return {
+                valid: false,
+                reason: `Invalid JWT audience claim array (aud) ${JSON.stringify(aud)}. Does not include "${audience}".`
+            };
+        }
+    }
+    else {
         return {
             valid: false,
-            reason: `Invalid JWT audience in array "${decoded.payload.aud}". Does not include "${audience}".`
+            reason: `Invalid JWT audience claim (aud) ${JSON.stringify(aud)}. Expected a string or a non-empty array of strings.`
         };
     }
-    if (decoded.payload.iss !== issuer) {
+    if (iss !== issuer) {
         return {
             valid: false,
-            reason: `Invalid JWT issuer "${decoded.payload.iss}". Expected "${issuer}".`
+            reason: `Invalid JWT issuer claim (iss) ${JSON.stringify(decoded.payload.iss)}. Expected "${issuer}".`
+        };
+    }
+    if (typeof exp !== 'number') {
+        return {
+            valid: false,
+            reason: `Invalid JWT expiry date claim (exp) ${JSON.stringify(exp)}. Expected number.`
         };
     }
-    const expiryDate = new Date(0);
-    expiryDate.setUTCSeconds(decoded.payload.exp);
     const currentDate = new Date(Date.now());
-    const expired = expiryDate <= currentDate;
+    const expiryDate = new Date(0);
+    expiryDate.setUTCSeconds(exp);
+    const expired = expiryDate.getTime() <= currentDate.getTime() - skewMs;
     if (expired) {
         return {
             valid: false,
             reason: `JWT is expired. Expiry date: ${expiryDate}; Current date: ${currentDate};`
         };
     }
+    if (nbf !== undefined) {
+        if (typeof nbf !== 'number') {
+            return {
+                valid: false,
+                reason: `Invalid JWT not before date claim (nbf) ${JSON.stringify(nbf)}. Expected number.`
+            };
+        }
+        const notBeforeDate = new Date(0);
+        notBeforeDate.setUTCSeconds(nbf);
+        const early = notBeforeDate.getTime() > currentDate.getTime() + skewMs;
+        if (early) {
+            return {
+                valid: false,
+                reason: `JWT cannot be used prior to not before date claim (nbf). Not before date: ${notBeforeDate}; Current date: ${currentDate};`
+            };
+        }
+    }
+    if (iat !== undefined) {
+        if (typeof iat !== 'number') {
+            return {
+                valid: false,
+                reason: `Invalid JWT issued at date claim (iat) ${JSON.stringify(iat)}. Expected number.`
+            };
+        }
+        const issuedAtDate = new Date(0);
+        issuedAtDate.setUTCSeconds(iat);
+        const postIssued = issuedAtDate.getTime() > currentDate.getTime() + skewMs;
+        if (postIssued) {
+            return {
+                valid: false,
+                reason: `JWT issued at date claim (iat) is in the future. Issued at date: ${issuedAtDate}; Current date: ${currentDate};`
+            };
+        }
+    }
     let key;
     try {
-        key = await getKey(decoded);
+        key = await resolveKey(decoded);
     }
     catch {
         return {
             valid: false,
-            reason: `Error retrieving key to verify JWT signature.`
+            reason: `Error retrieving public key to verify JWT signature.`
+        };
+    }
+    if (!key) {
+        return {
+            valid: false,
+            reason: `Unable to resolve public key to verify JWT signature.`
         };
     }
     let signatureValid;

package/dist/types.d.ts

@@ -4,6 +4,8 @@ export interface JwtPayload {
     aud: string | Array<string>;
     iat: number;
     exp: number;
+    nbf?: number;
+    jti?: string;
 }
 export interface JwtHeader {
     typ?: string;
@@ -18,7 +20,7 @@ export interface RawJwt {
 export interface DecodedJwt {
     header: JwtHeader;
     payload: JwtPayload;
-    signature: string;
+    signature: Uint8Array;
     raw: RawJwt;
 }
 export interface JsonWebKeyset {

package/dist/verify.js

@@ -1,6 +1,5 @@
 export async function verifyJwtSignature(decoded, key) {
     const encoder = new TextEncoder();
     const data = encoder.encode(`${decoded.raw.header}.${decoded.raw.payload}`);
-    const signature = new Uint8Array(Array.from(decoded.signature).map(c => c.charCodeAt(0)));
-    return crypto.subtle.verify('RSASSA-PKCS1-v1_5', key, signature, data);
+    return crypto.subtle.verify('RSASSA-PKCS1-v1_5', key, decoded.signature, data);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfworker/jwt",
-  "version": "1.12.1",
+  "version": "3.0.0",
   "description": "Tiny lib for decoding JWTs and verifying signatures, using native crypto APIs",
   "keywords": [
     "jwt",
@@ -34,16 +34,16 @@
     "test": "cfworker test test/**/*.spec.ts --nocheck"
   },
   "dependencies": {
-    "@cfworker/base64url": "^1.12.1",
     "@cfworker/worker-types": "^1.12.1",
-    "@cloudflare/workers-types": "^2.2.2"
+    "@cloudflare/workers-types": "^2.2.2",
+    "rfc4648": "^1.5.1"
   },
   "devDependencies": {
-    "@cfworker/dev": "^1.13.1",
+    "@cfworker/dev": "^1.14.0",
     "@types/chai": "^4.3.0",
     "@types/mocha": "^9.1.0",
-    "chai": "^4.3.4",
-    "mocha": "^9.1.4",
+    "chai": "^4.3.6",
+    "mocha": "^9.2.1",
     "typescript": "^4.5.5"
   }
 }

package/src/algs.ts

@@ -0,0 +1,7 @@
+export const algToHash: Record<string, string> = {
+  RS256: 'SHA-256',
+  RS384: 'SHA-384',
+  RS512: 'SHA-512'
+};
+
+export const algs = Object.keys(algToHash);

package/src/decode.ts

@@ -1,4 +1,4 @@
-import { decode } from '@cfworker/base64url';
+import { base64url } from 'rfc4648';
 import { DecodedJwt } from './types.js';
 
 /**
@@ -6,10 +6,15 @@ import { DecodedJwt } from './types.js';
  */
 export function decodeJwt(token: string): DecodedJwt {
   const [header, payload, signature] = token.split('.');
+  const decoder = new TextDecoder();
   return {
-    header: JSON.parse(decode(header)),
-    payload: JSON.parse(decode(payload)),
-    signature: decode(signature),
+    header: JSON.parse(
+      decoder.decode(base64url.parse(header, { loose: true }))
+    ),
+    payload: JSON.parse(
+      decoder.decode(base64url.parse(payload, { loose: true }))
+    ),
+    signature: base64url.parse(signature, { loose: true }),
     raw: { header, payload, signature }
   };
 }

package/src/jwks.ts

@@ -1,3 +1,4 @@
+import { algToHash } from './algs.js';
 import { DecodedJwt, JsonWebKeyset } from './types.js';
 
 /**
@@ -26,22 +27,22 @@ const importedKeys: Record<string, Record<string, CryptoKey>> = {};
  * @param jwks The JsonWebKeyset to import.
  */
 export async function importKey(iss: string, jwk: JsonWebKey) {
-  const input = {
-    kty: 'RSA',
-    e: 'AQAB',
-    n: jwk.n,
-    alg: 'RS256',
-    ext: true
-  };
+  if (jwk.kty !== 'RSA') {
+    throw new Error(`Unsupported jwk key type (kty) "${jwk.kty}".`);
+  }
+  const hash = jwk.alg ? algToHash[jwk.alg] : null;
+  if (!hash) {
+    throw new Error(`Unsupported jwk Algorithm (alg) "${jwk.alg}".`);
+  }
   const key = await crypto.subtle.importKey(
     'jwk',
-    input,
-    { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+    jwk,
+    { name: 'RSASSA-PKCS1-v1_5', hash },
     false,
     ['verify']
   );
   importedKeys[iss] = importedKeys[iss] || {};
-  importedKeys[iss][jwk.kid || 'default'] = key;
+  importedKeys[iss][jwk.kid ?? 'default'] = key;
 }
 
 /**

package/src/parse.ts

@@ -1,15 +1,19 @@
+import { algs, algToHash } from './algs.js';
 import { decodeJwt } from './decode.js';
 import { getKey } from './jwks.js';
 import { DecodedJwt, JwtParseResult } from './types.js';
 import { verifyJwtSignature } from './verify.js';
 
+const skewMs = 30 * 1000;
+
 /**
  * Parse a JWT.
  */
 export async function parseJwt(
   encodedToken: string,
   issuer: string,
-  audience: string
+  audience: string,
+  resolveKey: (decoded: DecodedJwt) => Promise<CryptoKey | null> = getKey
 ): Promise<JwtParseResult> {
   let decoded: DecodedJwt;
   try {
@@ -17,62 +21,144 @@ export async function parseJwt(
   } catch {
     return { valid: false, reason: `Unable to decode JWT.` };
   }
-  if (
-    typeof decoded.header.typ !== 'undefined' &&
-    decoded.header.typ !== 'JWT'
-  ) {
+  const { typ, alg } = decoded.header;
+  if (typeof typ !== 'undefined' && typ !== 'JWT') {
     return {
       valid: false,
-      reason: `Invalid JWT type "${decoded.header.typ}". Expected "JWT".`
+      reason: `Invalid JWT type ${JSON.stringify(typ)}. Expected "JWT".`
     };
   }
-  if (decoded.header.alg !== 'RS256') {
+  if (!algToHash[alg]) {
     return {
       valid: false,
-      reason: `Invalid JWT algorithm "${decoded.header.alg}". Expected "RS256".`
+      reason: `Invalid JWT algorithm ${JSON.stringify(
+        alg
+      )}. Supported: ${algs}.`
     };
   }
-  if (
-    typeof decoded.payload.aud === 'string' &&
-    decoded.payload.aud !== audience
-  ) {
+
+  const { sub, aud, iss, iat, exp, nbf } = decoded.payload;
+  if (typeof sub !== 'string') {
     return {
       valid: false,
-      reason: `Invalid JWT audience "${decoded.payload.aud}". Expected "${audience}".`
+      reason: `Subject claim (sub) is required and must be a string. Received ${JSON.stringify(
+        sub
+      )}.`
     };
+  }
+
+  if (typeof aud === 'string') {
+    if (aud !== audience) {
+      return {
+        valid: false,
+        reason: `Invalid JWT audience claim (aud) ${JSON.stringify(
+          aud
+        )}. Expected "${audience}".`
+      };
+    }
   } else if (
-    Array.isArray(decoded.payload.aud) &&
-    !decoded.payload.aud.includes(audience)
+    Array.isArray(aud) &&
+    aud.length > 0 &&
+    aud.every(a => typeof a === 'string')
   ) {
+    if (!aud.includes(audience)) {
+      return {
+        valid: false,
+        reason: `Invalid JWT audience claim array (aud) ${JSON.stringify(
+          aud
+        )}. Does not include "${audience}".`
+      };
+    }
+  } else {
     return {
       valid: false,
-      reason: `Invalid JWT audience in array "${decoded.payload.aud}". Does not include "${audience}".`
+      reason: `Invalid JWT audience claim (aud) ${JSON.stringify(
+        aud
+      )}. Expected a string or a non-empty array of strings.`
     };
   }
 
-  if (decoded.payload.iss !== issuer) {
+  if (iss !== issuer) {
     return {
       valid: false,
-      reason: `Invalid JWT issuer "${decoded.payload.iss}". Expected "${issuer}".`
+      reason: `Invalid JWT issuer claim (iss) ${JSON.stringify(
+        decoded.payload.iss
+      )}. Expected "${issuer}".`
+    };
+  }
+
+  if (typeof exp !== 'number') {
+    return {
+      valid: false,
+      reason: `Invalid JWT expiry date claim (exp) ${JSON.stringify(
+        exp
+      )}. Expected number.`
     };
   }
-  const expiryDate = new Date(0);
-  expiryDate.setUTCSeconds(decoded.payload.exp);
   const currentDate = new Date(Date.now());
-  const expired = expiryDate <= currentDate;
+  const expiryDate = new Date(0);
+  expiryDate.setUTCSeconds(exp);
+  const expired = expiryDate.getTime() <= currentDate.getTime() - skewMs;
   if (expired) {
     return {
       valid: false,
       reason: `JWT is expired. Expiry date: ${expiryDate}; Current date: ${currentDate};`
     };
   }
-  let key: CryptoKey;
+
+  if (nbf !== undefined) {
+    if (typeof nbf !== 'number') {
+      return {
+        valid: false,
+        reason: `Invalid JWT not before date claim (nbf) ${JSON.stringify(
+          nbf
+        )}. Expected number.`
+      };
+    }
+    const notBeforeDate = new Date(0);
+    notBeforeDate.setUTCSeconds(nbf);
+    const early = notBeforeDate.getTime() > currentDate.getTime() + skewMs;
+    if (early) {
+      return {
+        valid: false,
+        reason: `JWT cannot be used prior to not before date claim (nbf). Not before date: ${notBeforeDate}; Current date: ${currentDate};`
+      };
+    }
+  }
+
+  if (iat !== undefined) {
+    if (typeof iat !== 'number') {
+      return {
+        valid: false,
+        reason: `Invalid JWT issued at date claim (iat) ${JSON.stringify(
+          iat
+        )}. Expected number.`
+      };
+    }
+    const issuedAtDate = new Date(0);
+    issuedAtDate.setUTCSeconds(iat);
+    const postIssued = issuedAtDate.getTime() > currentDate.getTime() + skewMs;
+    if (postIssued) {
+      return {
+        valid: false,
+        reason: `JWT issued at date claim (iat) is in the future. Issued at date: ${issuedAtDate}; Current date: ${currentDate};`
+      };
+    }
+  }
+
+  let key: CryptoKey | null;
   try {
-    key = await getKey(decoded);
+    key = await resolveKey(decoded);
   } catch {
     return {
       valid: false,
-      reason: `Error retrieving key to verify JWT signature.`
+      reason: `Error retrieving public key to verify JWT signature.`
+    };
+  }
+  if (!key) {
+    return {
+      valid: false,
+      reason: `Unable to resolve public key to verify JWT signature.`
     };
   }
   let signatureValid: boolean;

package/src/types.ts

@@ -4,6 +4,8 @@ export interface JwtPayload {
   aud: string | Array<string>;
   iat: number;
   exp: number;
+  nbf?: number;
+  jti?: string;
 }
 
 export interface JwtHeader {
@@ -28,7 +30,7 @@ export interface RawJwt {
 export interface DecodedJwt {
   header: JwtHeader;
   payload: JwtPayload;
-  signature: string;
+  signature: Uint8Array;
   raw: RawJwt;
 }
 

package/src/verify.ts

@@ -7,9 +7,11 @@ import { DecodedJwt } from './types.js';
 export async function verifyJwtSignature(decoded: DecodedJwt, key: CryptoKey) {
   const encoder = new TextEncoder();
   const data = encoder.encode(`${decoded.raw.header}.${decoded.raw.payload}`);
-  const signature = new Uint8Array(
-    Array.from(decoded.signature).map(c => c.charCodeAt(0))
-  );
 
-  return crypto.subtle.verify('RSASSA-PKCS1-v1_5', key, signature, data);
+  return crypto.subtle.verify(
+    'RSASSA-PKCS1-v1_5',
+    key,
+    decoded.signature,
+    data
+  );
 }