@cfworker/jwt 3.0.0 → 4.0.0

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,11 +22,11 @@ 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] || {};

package/dist/parse.js

@@ -115,10 +115,10 @@ export async function parseJwt(encodedToken, issuer, audience, resolveKey = getK
     try {
         key = await resolveKey(decoded);
     }
-    catch {
+    catch (e) {
         return {
             valid: false,
-            reason: `Error retrieving public key to verify JWT signature.`
+            reason: `Error retrieving public key to verify JWT signature: ${e instanceof Error ? e.message : e}`
         };
     }
     if (!key) {

package/dist/types.d.ts

@@ -34,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": "3.0.0",
+  "version": "4.0.0",
   "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',

package/src/parse.ts

@@ -149,10 +149,12 @@ export async function parseJwt(
   let key: CryptoKey | null;
   try {
     key = await resolveKey(decoded);
-  } catch {
+  } catch (e) {
     return {
       valid: false,
-      reason: `Error retrieving public key to verify JWT signature.`
+      reason: `Error retrieving public key to verify JWT signature: ${
+        e instanceof Error ? e.message : e
+      }`
     };
   }
   if (!key) {

package/src/types.ts

@@ -48,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;