@cfworker/jwt 4.0.6 → 5.1.0

package/README.md

@@ -15,7 +15,7 @@ const jwt = request.headers.get('Authorization');
 const issuer = '...'; // Auth0 origin.
 const audience = '...'; // Auth0 client id.
 
-const result = await parseJwt(jwt, issuer, audience);
+const result = await parseJwt({ jwt, issuer, audience });
 if (!result.valid) {
   console.log(result.reason); // Invalid issuer/audience, expired, etc
 } else {

package/dist/parse.d.ts

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

package/dist/parse.js

@@ -2,40 +2,52 @@ import { algs, algToHash } from './algs.js';
 import { decodeJwt } from './decode.js';
 import { getKey } from './jwks.js';
 import { verifyJwtSignature } from './verify.js';
-const skewMs = 30 * 1000;
-export async function parseJwt(encodedToken, issuer, audience, resolveKey = getKey) {
+const defaultSkewMs = 60 * 1000;
+export async function parseJwt({ jwt, issuer, audience, resolveKey = getKey, skewMs = defaultSkewMs }) {
     let decoded;
     try {
-        decoded = decodeJwt(encodedToken);
+        decoded = decodeJwt(jwt);
     }
     catch {
-        return { valid: false, reason: `Unable to decode JWT.` };
+        return {
+            valid: false,
+            reason: `Unable to decode JWT.`,
+            reasonCode: 0
+        };
     }
     const { typ, alg } = decoded.header;
     if (typeof typ !== 'undefined' && typ !== 'JWT') {
         return {
             valid: false,
-            reason: `Invalid JWT type ${JSON.stringify(typ)}. Expected "JWT".`
+            reason: `Invalid JWT type ${JSON.stringify(typ)}. Expected "JWT".`,
+            reasonCode: 0,
+            decoded
         };
     }
     if (!algToHash[alg]) {
         return {
             valid: false,
-            reason: `Invalid JWT algorithm ${JSON.stringify(alg)}. Supported: ${algs}.`
+            reason: `Invalid JWT algorithm ${JSON.stringify(alg)}. Supported: ${algs}.`,
+            reasonCode: 0,
+            decoded
         };
     }
     const { sub, aud, iss, iat, exp, nbf } = decoded.payload;
     if (typeof sub !== 'string') {
         return {
             valid: false,
-            reason: `Subject claim (sub) is required and must be a string. Received ${JSON.stringify(sub)}.`
+            reason: `Subject claim (sub) is required and must be a string. Received ${JSON.stringify(sub)}.`,
+            reasonCode: 0,
+            decoded
         };
     }
     if (typeof aud === 'string') {
         if (aud !== audience) {
             return {
                 valid: false,
-                reason: `Invalid JWT audience claim (aud) ${JSON.stringify(aud)}. Expected "${audience}".`
+                reason: `Invalid JWT audience claim (aud) ${JSON.stringify(aud)}. Expected "${audience}".`,
+                reasonCode: 0,
+                decoded
             };
         }
     }
@@ -45,26 +57,34 @@ export async function parseJwt(encodedToken, issuer, audience, resolveKey = getK
         if (!aud.includes(audience)) {
             return {
                 valid: false,
-                reason: `Invalid JWT audience claim array (aud) ${JSON.stringify(aud)}. Does not include "${audience}".`
+                reason: `Invalid JWT audience claim array (aud) ${JSON.stringify(aud)}. Does not include "${audience}".`,
+                reasonCode: 0,
+                decoded
             };
         }
     }
     else {
         return {
             valid: false,
-            reason: `Invalid JWT audience claim (aud) ${JSON.stringify(aud)}. Expected a string or a non-empty array of strings.`
+            reason: `Invalid JWT audience claim (aud) ${JSON.stringify(aud)}. Expected a string or a non-empty array of strings.`,
+            reasonCode: 0,
+            decoded
         };
     }
     if (!(iss === issuer || (Array.isArray(issuer) && issuer.includes(iss)))) {
         return {
             valid: false,
-            reason: `Invalid JWT issuer claim (iss) ${JSON.stringify(decoded.payload.iss)}. Expected ${JSON.stringify(issuer)}.`
+            reason: `Invalid JWT issuer claim (iss) ${JSON.stringify(decoded.payload.iss)}. Expected ${JSON.stringify(issuer)}.`,
+            reasonCode: 0,
+            decoded
         };
     }
     if (typeof exp !== 'number') {
         return {
             valid: false,
-            reason: `Invalid JWT expiry date claim (exp) ${JSON.stringify(exp)}. Expected number.`
+            reason: `Invalid JWT expiry date claim (exp) ${JSON.stringify(exp)}. Expected number.`,
+            reasonCode: 0,
+            decoded
         };
     }
     const currentDate = new Date(Date.now());
@@ -74,14 +94,18 @@ export async function parseJwt(encodedToken, issuer, audience, resolveKey = getK
     if (expired) {
         return {
             valid: false,
-            reason: `JWT is expired. Expiry date: ${expiryDate}; Current date: ${currentDate};`
+            reason: `JWT is expired. Expiry date: ${expiryDate}; Current date: ${currentDate};`,
+            reasonCode: 1,
+            decoded
         };
     }
     if (nbf !== undefined) {
         if (typeof nbf !== 'number') {
             return {
                 valid: false,
-                reason: `Invalid JWT not before date claim (nbf) ${JSON.stringify(nbf)}. Expected number.`
+                reason: `Invalid JWT not before date claim (nbf) ${JSON.stringify(nbf)}. Expected number.`,
+                reasonCode: 0,
+                decoded
             };
         }
         const notBeforeDate = new Date(0);
@@ -90,7 +114,9 @@ export async function parseJwt(encodedToken, issuer, audience, resolveKey = getK
         if (early) {
             return {
                 valid: false,
-                reason: `JWT cannot be used prior to not before date claim (nbf). Not before date: ${notBeforeDate}; Current date: ${currentDate};`
+                reason: `JWT cannot be used prior to not before date claim (nbf). Not before date: ${notBeforeDate}; Current date: ${currentDate};`,
+                reasonCode: 0,
+                decoded
             };
         }
     }
@@ -98,7 +124,9 @@ export async function parseJwt(encodedToken, issuer, audience, resolveKey = getK
         if (typeof iat !== 'number') {
             return {
                 valid: false,
-                reason: `Invalid JWT issued at date claim (iat) ${JSON.stringify(iat)}. Expected number.`
+                reason: `Invalid JWT issued at date claim (iat) ${JSON.stringify(iat)}. Expected number.`,
+                reasonCode: 0,
+                decoded
             };
         }
         const issuedAtDate = new Date(0);
@@ -107,7 +135,9 @@ export async function parseJwt(encodedToken, issuer, audience, resolveKey = getK
         if (postIssued) {
             return {
                 valid: false,
-                reason: `JWT issued at date claim (iat) is in the future. Issued at date: ${issuedAtDate}; Current date: ${currentDate};`
+                reason: `JWT issued at date claim (iat) is in the future. Issued at date: ${issuedAtDate}; Current date: ${currentDate};`,
+                reasonCode: 0,
+                decoded
             };
         }
     }
@@ -118,13 +148,17 @@ export async function parseJwt(encodedToken, issuer, audience, resolveKey = getK
     catch (e) {
         return {
             valid: false,
-            reason: `Error retrieving public key to verify JWT signature: ${e instanceof Error ? e.message : e}`
+            reason: `Error retrieving public key to verify JWT signature: ${e instanceof Error ? e.message : e}`,
+            reasonCode: 0,
+            decoded
         };
     }
     if (!key) {
         return {
             valid: false,
-            reason: `Unable to resolve public key to verify JWT signature.`
+            reason: `Unable to resolve public key to verify JWT signature.`,
+            reasonCode: 0,
+            decoded
         };
     }
     let signatureValid;
@@ -132,11 +166,21 @@ export async function parseJwt(encodedToken, issuer, audience, resolveKey = getK
         signatureValid = await verifyJwtSignature(decoded, key);
     }
     catch {
-        return { valid: false, reason: `Error verifying JWT signature.` };
+        return {
+            valid: false,
+            reason: `Error verifying JWT signature.`,
+            reasonCode: 0,
+            decoded
+        };
     }
     if (!signatureValid) {
-        return { valid: false, reason: `JWT signature is invalid.` };
+        return {
+            valid: false,
+            reason: `JWT signature is invalid.`,
+            reasonCode: 0,
+            decoded
+        };
     }
-    const payload = decoded.payload;
-    return { valid: true, payload };
+    const { header, payload } = decoded;
+    return { valid: true, header, payload };
 }

package/dist/types.d.ts

@@ -29,11 +29,18 @@ export interface JsonWebKeyset {
 }
 export interface ValidJwtParseResult {
     valid: true;
+    header: JwtHeader;
     payload: JwtPayload;
 }
 export interface InvalidJwtParseResult {
     valid: false;
     reason: string;
+    reasonCode: InvalidJwtReasonCode;
+    decoded?: DecodedJwt;
+}
+export declare const enum InvalidJwtReasonCode {
+    Other = 0,
+    Expired = 1
 }
 export interface IssuerMetadata {
     issuer: string;
@@ -61,4 +68,4 @@ export interface MtlsEndpointAliases {
     introspection_endpoint?: string;
     device_authorization_endpoint?: string;
 }
-export declare type JwtParseResult = ValidJwtParseResult | InvalidJwtParseResult;
+export type JwtParseResult = ValidJwtParseResult | InvalidJwtParseResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfworker/jwt",
-  "version": "4.0.6",
+  "version": "5.1.0",
   "description": "Tiny lib for decoding JWTs and verifying signatures, using native crypto APIs",
   "keywords": [
     "jwt",
@@ -31,19 +31,19 @@
   "scripts": {
     "build": "tsc --build",
     "clean": "tsc --build --clean",
-    "test": "cfworker test test/**/*.spec.ts --nocheck"
+    "pretest": "esbuild test/test.ts --target=esnext --bundle --format=esm --conditions=worker,browser --outdir=dist-test --ignore-annotations",
+    "test": "node ../../test.mjs"
   },
   "dependencies": {
-    "@cfworker/worker-types": "^1.12.3",
-    "@cloudflare/workers-types": "^2.2.2",
-    "rfc4648": "^1.5.2"
+    "rfc4648": "^1.5.3"
   },
   "devDependencies": {
-    "@cfworker/dev": "^1.14.2",
-    "@types/chai": "^4.3.3",
-    "@types/mocha": "^10.0.0",
-    "chai": "^4.3.6",
-    "mocha": "^10.0.0",
-    "typescript": "^4.8.4"
+    "@types/chai": "^4.3.17",
+    "@types/mocha": "^10.0.7",
+    "chai": "^5.1.1",
+    "esbuild": "^0.23.1",
+    "mocha": "^10.7.3",
+    "typescript": "^5.5.4",
+    "wrangler": "^3.72.0"
   }
 }

package/src/declarations.d.ts

@@ -0,0 +1,6 @@
+interface JsonWebKey {
+  x5c?: string[];
+  kid?: string;
+  x5t?: string;
+  n?: string;
+}

package/src/parse.ts

@@ -1,31 +1,72 @@
 import { algs, algToHash } from './algs.js';
 import { decodeJwt } from './decode.js';
 import { getKey } from './jwks.js';
-import { DecodedJwt, JwtParseResult } from './types.js';
+import { DecodedJwt, InvalidJwtReasonCode, JwtParseResult } from './types.js';
 import { verifyJwtSignature } from './verify.js';
 
-const skewMs = 30 * 1000;
+const defaultSkewMs = 60 * 1000;
+
+export interface JwtParseOptions {
+  /**
+   * The JWT to parse.
+   */
+  jwt: string;
+
+  /**
+   * Permitted issuer(s) of the JWT. Used to validate the iss claim.
+   * Note: if you're using the default resolveKey function, OIDC discovery will be used
+   * to fetch the public key(s) for the issuer.
+   */
+  issuer: string | string[];
+
+  /**
+   * Expected audience of the JWT.
+   */
+  audience: string;
+
+  /**
+   * Given a decoded (but not fully verified) JWT, resolve the public key that
+   * should be used to verify the signature. Typical implementations will use
+   * the "kid" claim to look up the key in a JWKS endpoint or other key store.
+   * If the key cannot be resolved, the function should return null.
+   * @param decoded The decoded (but not fully verified / unsafe) JWT.
+   */
+  resolveKey?: (decoded: DecodedJwt) => Promise<CryptoKey | null>;
+
+  /**
+   * The maximum skew in milliseconds to allow when validating iat, nbf, and exp claims.
+   * Defaults to 60 seconds.
+   */
+  skewMs?: number;
+}
 
 /**
  * Parse a JWT.
  */
-export async function parseJwt(
-  encodedToken: string,
-  issuer: string | string[],
-  audience: string,
-  resolveKey: (decoded: DecodedJwt) => Promise<CryptoKey | null> = getKey
-): Promise<JwtParseResult> {
+export async function parseJwt({
+  jwt,
+  issuer,
+  audience,
+  resolveKey = getKey,
+  skewMs = defaultSkewMs
+}: JwtParseOptions): Promise<JwtParseResult> {
   let decoded: DecodedJwt;
   try {
-    decoded = decodeJwt(encodedToken);
+    decoded = decodeJwt(jwt);
   } catch {
-    return { valid: false, reason: `Unable to decode JWT.` };
+    return {
+      valid: false,
+      reason: `Unable to decode JWT.`,
+      reasonCode: InvalidJwtReasonCode.Other
+    };
   }
   const { typ, alg } = decoded.header;
   if (typeof typ !== 'undefined' && typ !== 'JWT') {
     return {
       valid: false,
-      reason: `Invalid JWT type ${JSON.stringify(typ)}. Expected "JWT".`
+      reason: `Invalid JWT type ${JSON.stringify(typ)}. Expected "JWT".`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
     };
   }
   if (!algToHash[alg]) {
@@ -33,7 +74,9 @@ export async function parseJwt(
       valid: false,
       reason: `Invalid JWT algorithm ${JSON.stringify(
         alg
-      )}. Supported: ${algs}.`
+      )}. Supported: ${algs}.`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
     };
   }
 
@@ -43,7 +86,9 @@ export async function parseJwt(
       valid: false,
       reason: `Subject claim (sub) is required and must be a string. Received ${JSON.stringify(
         sub
-      )}.`
+      )}.`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
     };
   }
 
@@ -53,7 +98,9 @@ export async function parseJwt(
         valid: false,
         reason: `Invalid JWT audience claim (aud) ${JSON.stringify(
           aud
-        )}. Expected "${audience}".`
+        )}. Expected "${audience}".`,
+        reasonCode: InvalidJwtReasonCode.Other,
+        decoded
       };
     }
   } else if (
@@ -66,7 +113,9 @@ export async function parseJwt(
         valid: false,
         reason: `Invalid JWT audience claim array (aud) ${JSON.stringify(
           aud
-        )}. Does not include "${audience}".`
+        )}. Does not include "${audience}".`,
+        reasonCode: InvalidJwtReasonCode.Other,
+        decoded
       };
     }
   } else {
@@ -74,7 +123,9 @@ export async function parseJwt(
       valid: false,
       reason: `Invalid JWT audience claim (aud) ${JSON.stringify(
         aud
-      )}. Expected a string or a non-empty array of strings.`
+      )}. Expected a string or a non-empty array of strings.`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
     };
   }
 
@@ -83,7 +134,9 @@ export async function parseJwt(
       valid: false,
       reason: `Invalid JWT issuer claim (iss) ${JSON.stringify(
         decoded.payload.iss
-      )}. Expected ${JSON.stringify(issuer)}.`
+      )}. Expected ${JSON.stringify(issuer)}.`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
     };
   }
 
@@ -92,7 +145,9 @@ export async function parseJwt(
       valid: false,
       reason: `Invalid JWT expiry date claim (exp) ${JSON.stringify(
         exp
-      )}. Expected number.`
+      )}. Expected number.`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
     };
   }
   const currentDate = new Date(Date.now());
@@ -102,7 +157,9 @@ export async function parseJwt(
   if (expired) {
     return {
       valid: false,
-      reason: `JWT is expired. Expiry date: ${expiryDate}; Current date: ${currentDate};`
+      reason: `JWT is expired. Expiry date: ${expiryDate}; Current date: ${currentDate};`,
+      reasonCode: InvalidJwtReasonCode.Expired,
+      decoded
     };
   }
 
@@ -112,7 +169,9 @@ export async function parseJwt(
         valid: false,
         reason: `Invalid JWT not before date claim (nbf) ${JSON.stringify(
           nbf
-        )}. Expected number.`
+        )}. Expected number.`,
+        reasonCode: InvalidJwtReasonCode.Other,
+        decoded
       };
     }
     const notBeforeDate = new Date(0);
@@ -121,7 +180,9 @@ export async function parseJwt(
     if (early) {
       return {
         valid: false,
-        reason: `JWT cannot be used prior to not before date claim (nbf). Not before date: ${notBeforeDate}; Current date: ${currentDate};`
+        reason: `JWT cannot be used prior to not before date claim (nbf). Not before date: ${notBeforeDate}; Current date: ${currentDate};`,
+        reasonCode: InvalidJwtReasonCode.Other,
+        decoded
       };
     }
   }
@@ -132,7 +193,9 @@ export async function parseJwt(
         valid: false,
         reason: `Invalid JWT issued at date claim (iat) ${JSON.stringify(
           iat
-        )}. Expected number.`
+        )}. Expected number.`,
+        reasonCode: InvalidJwtReasonCode.Other,
+        decoded
       };
     }
     const issuedAtDate = new Date(0);
@@ -141,7 +204,9 @@ export async function parseJwt(
     if (postIssued) {
       return {
         valid: false,
-        reason: `JWT issued at date claim (iat) is in the future. Issued at date: ${issuedAtDate}; Current date: ${currentDate};`
+        reason: `JWT issued at date claim (iat) is in the future. Issued at date: ${issuedAtDate}; Current date: ${currentDate};`,
+        reasonCode: InvalidJwtReasonCode.Other,
+        decoded
       };
     }
   }
@@ -154,24 +219,38 @@ export async function parseJwt(
       valid: false,
       reason: `Error retrieving public key to verify JWT signature: ${
         e instanceof Error ? e.message : e
-      }`
+      }`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
     };
   }
   if (!key) {
     return {
       valid: false,
-      reason: `Unable to resolve public key to verify JWT signature.`
+      reason: `Unable to resolve public key to verify JWT signature.`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
     };
   }
   let signatureValid: boolean;
   try {
     signatureValid = await verifyJwtSignature(decoded, key);
   } catch {
-    return { valid: false, reason: `Error verifying JWT signature.` };
+    return {
+      valid: false,
+      reason: `Error verifying JWT signature.`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
+    };
   }
   if (!signatureValid) {
-    return { valid: false, reason: `JWT signature is invalid.` };
+    return {
+      valid: false,
+      reason: `JWT signature is invalid.`,
+      reasonCode: InvalidJwtReasonCode.Other,
+      decoded
+    };
   }
-  const payload = decoded.payload;
-  return { valid: true, payload };
+  const { header, payload } = decoded;
+  return { valid: true, header, payload };
 }

package/src/types.ts

@@ -41,12 +41,20 @@ export interface JsonWebKeyset {
 
 export interface ValidJwtParseResult {
   valid: true;
+  header: JwtHeader;
   payload: JwtPayload;
 }
 
 export interface InvalidJwtParseResult {
   valid: false;
   reason: string;
+  reasonCode: InvalidJwtReasonCode;
+  decoded?: DecodedJwt;
+}
+
+export const enum InvalidJwtReasonCode {
+  Other = 0,
+  Expired = 1
 }
 
 export interface IssuerMetadata {

package/tsconfig.json

@@ -1,17 +1,11 @@
 {
   "extends": "../../tsconfig-base",
   "compilerOptions": {
-    "target": "ES2021",
+    "target": "ESNext",
     "lib": ["ESNext", "WebWorker", "Webworker.Iterable"],
-    "types": [
-      "chai",
-      "mocha",
-      "@cfworker/worker-types",
-      "@cloudflare/workers-types"
-    ],
     "outDir": "dist",
     "rootDir": "./src"
   },
   "include": ["src"],
-  "references": [{ "path": "../base64url" }]
+  "references": []
 }