feat: add JWT.verify "typ" option for checking JWT Type Header parameter

docs/README.md

@@ -893,6 +893,9 @@ Verifies the claims and signature of a JSON Web Token.
     `subject` depending on the use-case.
   - `audience`: `<string>` &vert; `string[]` Expected audience value(s). When string an exact match must
     be found in the payload, when array at least one must be matched.
+  - `typ`: `<string>` Expected JWT "typ" Header Parameter value. An exact match must be found in the
+    JWT header. **Default:** 'undefined' unless a `profile` with a specific value is used, in which
+    case this option will be ignored.
   - `clockTolerance`: `<string>` Clock Tolerance for comparing timestamps, provided as timespan
     string e.g. `120s`, `2 minutes`, etc. **Default:** no clock tolerance
   - `complete`: `<Boolean>` When false only the parsed payload is returned, otherwise an object with

lib/jwt/verify.js

@@ -40,7 +40,7 @@ const isNotArrayOfStrings = val => !Array.isArray(val) || val.length === 0 || va
 const validateOptions = ({
   algorithms, audience, clockTolerance, complete = false, crit, ignoreExp = false,
   ignoreIat = false, ignoreNbf = false, issuer, jti, maxAuthAge, maxTokenAge, nonce, now = new Date(),
-  profile, subject
+  profile, subject, typ
 }) => {
   isOptionString(profile, 'options.profile')
 
@@ -66,6 +66,7 @@ const validateOptions = ({
   isOptionString(maxAuthAge, 'options.maxAuthAge')
   isOptionString(jti, 'options.jti')
   isOptionString(clockTolerance, 'options.clockTolerance')
+  isOptionString(typ, 'options.typ')
 
   if (audience !== undefined && (isNotString(audience) && isNotArrayOfStrings(audience))) {
     throw new TypeError('options.audience must be a string or an array of strings')
@@ -109,6 +110,8 @@ const validateOptions = ({
         throw new TypeError('"audience" option is required to validate a JWT Access Token')
       }
 
+      typ = ATJWT
+
       break
     case LOGOUTTOKEN:
       if (!issuer) {
@@ -142,7 +145,8 @@ const validateOptions = ({
     nonce,
     now,
     profile,
-    subject
+    subject,
+    typ
   }
 }
 
@@ -156,15 +160,15 @@ const validateTypes = ({ header, payload }, profile, options) => {
   isPayloadString(payload.jti, '"jti" claim', 'jti', profile === LOGOUTTOKEN || !!options.jti)
   isPayloadString(payload.acr, '"acr" claim', 'acr')
   isPayloadString(payload.nonce, '"nonce" claim', 'nonce', !!options.nonce)
-  isPayloadString(payload.iss, '"iss" claim', 'iss', profile === IDTOKEN || profile === ATJWT || profile === LOGOUTTOKEN || !!options.issuer)
+  isPayloadString(payload.iss, '"iss" claim', 'iss', !!options.issuer)
   isPayloadString(payload.sub, '"sub" claim', 'sub', profile === IDTOKEN || profile === ATJWT || !!options.subject)
-  isStringOrArrayOfStrings(payload.aud, 'aud', profile === IDTOKEN || profile === ATJWT || profile === LOGOUTTOKEN || !!options.audience)
+  isStringOrArrayOfStrings(payload.aud, 'aud', !!options.audience)
   isPayloadString(payload.azp, '"azp" claim', 'azp', profile === IDTOKEN && Array.isArray(payload.aud) && payload.aud.length > 1)
   isStringOrArrayOfStrings(payload.amr, 'amr')
+  isPayloadString(header.typ, '"typ" header parameter', 'typ', !!options.typ)
 
   if (profile === ATJWT) {
     isPayloadString(payload.client_id, '"client_id" claim', 'client_id', true)
-    isPayloadString(header.typ, '"typ" header parameter', 'typ', true)
   }
 
   if (profile === LOGOUTTOKEN) {
@@ -221,7 +225,7 @@ module.exports = (token, key, options = {}) => {
 
   const {
     algorithms, audience, clockTolerance, complete, crit, ignoreExp, ignoreIat, ignoreNbf, issuer,
-    jti, maxAuthAge, maxTokenAge, nonce, now, profile, subject
+    jti, maxAuthAge, maxTokenAge, nonce, now, profile, subject, typ
   } = options = validateOptions(options)
 
   const decoded = decode(token, { complete: true })
@@ -257,6 +261,10 @@ module.exports = (token, key, options = {}) => {
     throw new JWTClaimInvalid('unexpected "aud" claim value', 'aud', 'check_failed')
   }
 
+  if (typ && decoded.header.typ !== typ) {
+    throw new JWTClaimInvalid('unexpected "typ" JWT header value', 'typ', 'check_failed')
+  }
+
   const tolerance = clockTolerance ? secs(clockTolerance) : 0
 
   if (maxAuthAge) {
@@ -295,9 +303,5 @@ module.exports = (token, key, options = {}) => {
     throw new JWTClaimInvalid('unexpected "azp" claim value', 'azp', 'check_failed')
   }
 
-  if (profile === ATJWT && decoded.header.typ !== ATJWT) {
-    throw new JWTClaimInvalid('invalid JWT typ header value for the used validation profile', 'typ', 'check_failed')
-  }
-
   return complete ? decoded : decoded.payload
 }

test/jwt/verify.test.js

@@ -153,9 +153,9 @@ test('options.ignoreIat & options.maxTokenAge may not be used together', t => {
 
 Object.entries({
   issuer: 'iss',
+  jti: 'jti',
   nonce: 'nonce',
-  subject: 'sub',
-  jti: 'jti'
+  subject: 'sub'
 }).forEach(([option, claim]) => {
   test(`option.${option} validation fails`, t => {
     let err
@@ -181,6 +181,29 @@ Object.entries({
   })
 })
 
+test('option.typ validation fails', t => {
+  let err
+  err = t.throws(() => {
+    const invalid = JWT.sign({}, key, { header: { typ: 'foo' } })
+    JWT.verify(invalid, key, { typ: 'bar' })
+  }, { instanceOf: errors.JWTClaimInvalid, message: 'unexpected "typ" JWT header value' })
+  t.is(err.claim, 'typ')
+  t.is(err.reason, 'check_failed')
+
+  err = t.throws(() => {
+    const invalid = JWS.sign({}, key, { header: { typ: undefined } })
+    JWT.verify(invalid, key, { typ: 'bar' })
+  }, { instanceOf: errors.JWTClaimInvalid, message: '"typ" header parameter is missing' })
+  t.is(err.claim, 'typ')
+  t.is(err.reason, 'missing')
+})
+
+test('option.typ validation success', t => {
+  const token = JWT.sign({}, key, { header: { typ: 'foo' } })
+  JWT.verify(token, key, { typ: 'foo' })
+  t.pass()
+})
+
 test('option.audience validation fails', t => {
   let err
   err = t.throws(() => {
@@ -822,7 +845,7 @@ test('must be a supported value', t => {
         key,
         { profile: 'at+JWT', issuer: 'issuer', audience: 'RS' }
       )
-    }, { instanceOf: errors.JWTClaimInvalid, message: 'invalid JWT typ header value for the used validation profile' })
+    }, { instanceOf: errors.JWTClaimInvalid, message: 'unexpected "typ" JWT header value' })
     t.is(err.claim, 'typ')
     t.is(err.reason, 'check_failed')
   })

types/index.d.ts

@@ -431,6 +431,7 @@ export namespace JWT {
     audience?: string | string[];
     algorithms?: string[];
     nonce?: string;
+    typ?: string;
     now?: Date;
     crit?: string[];
     profile?: JWTProfiles;