@cfworker/jwt 2.0.0 → 4.0.1

package/dist/discovery.d.ts

@@ -0,0 +1,2 @@
+import { IssuerMetadata } from './types';
+export declare function getIssuerMetadata(issuer: string): Promise<IssuerMetadata>;

package/dist/discovery.js

@@ -0,0 +1,12 @@
+export async function getIssuerMetadata(issuer) {
+    const url = new URL(issuer);
+    if (!url.pathname.endsWith('/')) {
+        url.pathname += '/';
+    }
+    url.pathname += '.well-known/openid-configuration';
+    const response = await fetch(url.href);
+    if (!response.ok) {
+        throw new Error(`Error loading OpenID discovery document at ${url.href}. ${response.status} ${response.statusText}`);
+    }
+    return response.json();
+}

package/dist/jwks.js

@@ -1,10 +1,18 @@
 import { algToHash } from './algs.js';
+import { getIssuerMetadata } from './discovery.js';
 export async function getJwks(issuer) {
-    const url = new URL(issuer);
-    if (!url.pathname.endsWith('/')) {
-        url.pathname += '/';
+    const issuerMetadata = await getIssuerMetadata(issuer);
+    let url;
+    if (issuerMetadata.jwks_uri) {
+        url = new URL(issuerMetadata.jwks_uri);
+    }
+    else {
+        url = new URL(issuer);
+        if (!url.pathname.endsWith('/')) {
+            url.pathname += '/';
+        }
+        url.pathname += '.well-known/jwks.json';
     }
-    url.pathname += '.well-known/jwks.json';
     const response = await fetch(url.href);
     if (!response.ok) {
         throw new Error(`Error loading jwks at ${url.href}. ${response.status} ${response.statusText}`);
@@ -14,21 +22,28 @@ export async function getJwks(issuer) {
 const importedKeys = {};
 export async function importKey(iss, jwk) {
     if (jwk.kty !== 'RSA') {
-        throw new Error(`Unsupported jwk key type (kty) "${jwk.kty}".`);
+        throw new Error(`Unsupported jwk key type (kty) "${jwk.kty}": Full JWK was ${JSON.stringify(jwk)}`);
     }
-    const hash = jwk.alg ? algToHash[jwk.alg] : null;
+    const hash = jwk.alg ? algToHash[jwk.alg] : 'SHA-256';
     if (!hash) {
-        throw new Error(`Unsupported jwk Algorithm (alg) "${jwk.alg}".`);
+        throw new Error(`Unsupported jwk Algorithm (alg) "${jwk.alg}": Full JWK was ${JSON.stringify(jwk)}`);
     }
     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;
 }
+const jwksImports = {};
 export async function getKey(decoded) {
-    let { header: { kid = 'default' }, payload: { iss } } = decoded;
+    const { header: { kid = 'default' }, payload: { iss } } = decoded;
     if (!importedKeys[iss]) {
-        const jwks = await getJwks(iss);
-        await Promise.all(jwks.keys.map(jwk => importKey(iss, jwk)));
+        if (!jwksImports[iss]) {
+            jwksImports[iss] = getJwks(iss)
+                .then(jwks => Promise.all(jwks.keys.map(jwk => importKey(iss, jwk))))
+                .finally(() => {
+                delete jwksImports[iss];
+            });
+        }
+        await jwksImports[iss];
     }
     const key = importedKeys[iss][kid];
     if (!key) {

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

@@ -2,7 +2,8 @@ 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);
@@ -10,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 (!algToHash[decoded.header.alg]) {
+    if (!algToHash[alg]) {
         return {
             valid: false,
-            reason: `Invalid JWT algorithm "${decoded.header.alg}". Supported: ${algs}.`
+            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 {
+    catch (e) {
+        return {
+            valid: false,
+            reason: `Error retrieving public key to verify JWT signature: ${e instanceof Error ? e.message : e}`
+        };
+    }
+    if (!key) {
         return {
             valid: false,
-            reason: `Error retrieving key to verify JWT signature.`
+            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;
@@ -32,4 +34,30 @@ export interface InvalidJwtParseResult {
     valid: false;
     reason: string;
 }
+export interface IssuerMetadata {
+    issuer: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    jwks_uri?: string;
+    userinfo_endpoint?: string;
+    revocation_endpoint?: string;
+    end_session_endpoint?: string;
+    registration_endpoint?: string;
+    token_endpoint_auth_methods_supported?: string[];
+    token_endpoint_auth_signing_alg_values_supported?: string[];
+    introspection_endpoint_auth_methods_supported?: string[];
+    introspection_endpoint_auth_signing_alg_values_supported?: string[];
+    revocation_endpoint_auth_methods_supported?: string[];
+    revocation_endpoint_auth_signing_alg_values_supported?: string[];
+    request_object_signing_alg_values_supported?: string[];
+    mtls_endpoint_aliases?: MtlsEndpointAliases;
+    [key: string]: unknown;
+}
+export interface MtlsEndpointAliases {
+    token_endpoint?: string;
+    userinfo_endpoint?: string;
+    revocation_endpoint?: string;
+    introspection_endpoint?: string;
+    device_authorization_endpoint?: string;
+}
 export declare type JwtParseResult = ValidJwtParseResult | InvalidJwtParseResult;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfworker/jwt",
-  "version": "2.0.0",
+  "version": "4.0.1",
   "description": "Tiny lib for decoding JWTs and verifying signatures, using native crypto APIs",
   "keywords": [
     "jwt",

package/src/discovery.ts

@@ -0,0 +1,21 @@
+import { IssuerMetadata } from './types';
+
+/**
+ * Fetch an oidc discovery document
+ */
+export async function getIssuerMetadata(
+  issuer: string
+): Promise<IssuerMetadata> {
+  const url = new URL(issuer);
+  if (!url.pathname.endsWith('/')) {
+    url.pathname += '/';
+  }
+  url.pathname += '.well-known/openid-configuration';
+  const response = await fetch(url.href);
+  if (!response.ok) {
+    throw new Error(
+      `Error loading OpenID discovery document at ${url.href}. ${response.status} ${response.statusText}`
+    );
+  }
+  return response.json();
+}

package/src/jwks.ts

@@ -1,15 +1,24 @@
 import { algToHash } from './algs.js';
+import { getIssuerMetadata } from './discovery.js';
 import { DecodedJwt, JsonWebKeyset } from './types.js';
 
 /**
  * Fetch a json web keyset.
  */
 export async function getJwks(issuer: string): Promise<JsonWebKeyset> {
-  const url = new URL(issuer);
-  if (!url.pathname.endsWith('/')) {
-    url.pathname += '/';
+  const issuerMetadata = await getIssuerMetadata(issuer);
+
+  let url;
+  if (issuerMetadata.jwks_uri) {
+    url = new URL(issuerMetadata.jwks_uri);
+  } else {
+    url = new URL(issuer);
+    if (!url.pathname.endsWith('/')) {
+      url.pathname += '/';
+    }
+    url.pathname += '.well-known/jwks.json';
   }
-  url.pathname += '.well-known/jwks.json';
+
   const response = await fetch(url.href);
   if (!response.ok) {
     throw new Error(
@@ -28,11 +37,22 @@ const importedKeys: Record<string, Record<string, CryptoKey>> = {};
  */
 export async function importKey(iss: string, jwk: JsonWebKey) {
   if (jwk.kty !== 'RSA') {
-    throw new Error(`Unsupported jwk key type (kty) "${jwk.kty}".`);
+    throw new Error(
+      `Unsupported jwk key type (kty) "${
+        jwk.kty
+      }": Full JWK was ${JSON.stringify(jwk)}`
+    );
   }
-  const hash = jwk.alg ? algToHash[jwk.alg] : null;
+  // alg is not mandatory in a JWK but is available in the JWT, for now we default to
+  // SHA-256 (RS256) because this is the most common but evaluating the key length
+  // of the JWKS is probably an ideal way of identifying what the alg is.
+  const hash = jwk.alg ? algToHash[jwk.alg] : 'SHA-256';
   if (!hash) {
-    throw new Error(`Unsupported jwk Algorithm (alg) "${jwk.alg}".`);
+    throw new Error(
+      `Unsupported jwk Algorithm (alg) "${
+        jwk.alg
+      }": Full JWK was ${JSON.stringify(jwk)}`
+    );
   }
   const key = await crypto.subtle.importKey(
     'jwk',
@@ -45,18 +65,26 @@ export async function importKey(iss: string, jwk: JsonWebKey) {
   importedKeys[iss][jwk.kid ?? 'default'] = key;
 }
 
+const jwksImports: Record<string, Promise<unknown>> = {};
+
 /**
  * Get the CryptoKey associated with the JWT's issuer.
  */
 export async function getKey(decoded: DecodedJwt): Promise<CryptoKey> {
-  let {
+  const {
     header: { kid = 'default' },
     payload: { iss }
   } = decoded;
 
   if (!importedKeys[iss]) {
-    const jwks = await getJwks(iss);
-    await Promise.all(jwks.keys.map(jwk => importKey(iss, jwk)));
+    if (!jwksImports[iss]) {
+      jwksImports[iss] = getJwks(iss)
+        .then(jwks => Promise.all(jwks.keys.map(jwk => importKey(iss, jwk))))
+        .finally(() => {
+          delete jwksImports[iss];
+        });
+    }
+    await jwksImports[iss];
   }
 
   const key = importedKeys[iss][kid];

package/src/parse.ts

@@ -4,13 +4,16 @@ 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 {
@@ -18,62 +21,146 @@ 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 (!algToHash[decoded.header.alg]) {
+  if (!algToHash[alg]) {
     return {
       valid: false,
-      reason: `Invalid JWT algorithm "${decoded.header.alg}". Supported: ${algs}.`
+      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);
-  } catch {
+    key = await resolveKey(decoded);
+  } catch (e) {
+    return {
+      valid: false,
+      reason: `Error retrieving public key to verify JWT signature: ${
+        e instanceof Error ? e.message : e
+      }`
+    };
+  }
+  if (!key) {
     return {
       valid: false,
-      reason: `Error retrieving key to verify JWT signature.`
+      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 {
@@ -46,4 +48,32 @@ export interface InvalidJwtParseResult {
   reason: string;
 }
 
+export interface IssuerMetadata {
+  issuer: string;
+  authorization_endpoint?: string;
+  token_endpoint?: string;
+  jwks_uri?: string;
+  userinfo_endpoint?: string;
+  revocation_endpoint?: string;
+  end_session_endpoint?: string;
+  registration_endpoint?: string;
+  token_endpoint_auth_methods_supported?: string[];
+  token_endpoint_auth_signing_alg_values_supported?: string[];
+  introspection_endpoint_auth_methods_supported?: string[];
+  introspection_endpoint_auth_signing_alg_values_supported?: string[];
+  revocation_endpoint_auth_methods_supported?: string[];
+  revocation_endpoint_auth_signing_alg_values_supported?: string[];
+  request_object_signing_alg_values_supported?: string[];
+  mtls_endpoint_aliases?: MtlsEndpointAliases;
+  [key: string]: unknown;
+}
+
+export interface MtlsEndpointAliases {
+  token_endpoint?: string;
+  userinfo_endpoint?: string;
+  revocation_endpoint?: string;
+  introspection_endpoint?: string;
+  device_authorization_endpoint?: string;
+}
+
 export type JwtParseResult = ValidJwtParseResult | InvalidJwtParseResult;