feat: add opt-in objects to verify using embedded JWS Header public keys

docs/README.md

@@ -52,6 +52,8 @@ If you or your business use `jose`, please consider becoming a [sponsor][support
 - [JWK.generateSync(kty[, crvOrSize[, options[, private]]])](#jwkgeneratesynckty-crvorsize-options-private)
 - [JWK.isKey(object)](#jwkiskeyobject)
 - [JWK.None](#jwknone)
+- [JWK.EmbeddedJWK](#jwkembeddedjwk)
+- [JWK.EmbeddedX5C](#jwkembeddedx5c)
 <!-- TOC JWK END -->
 
 All sign and encrypt operations require `<JWK.Key>` or `JWK.asKey()` compatible input. 
@@ -623,6 +625,28 @@ JWS.verify(unsecuredJWS, None)
 
 ---
 
+#### `JWK.EmbeddedJWK`
+
+`JWK.EmbeddedJWK` is a special key object that can be used with the JWS/JWT verify operations
+whenever you want to opt-in to verify signatures with a public key embedded in the JWS Header `jwk`
+parameter. It is recommended to combine this with the verify `algorithms` option to whitelist
+JWS algorithms to accept as well as the `complete` option set to `true` if you need to work with the
+instantiated `JWK.Key` from the token.
+
+---
+
+#### `JWK.EmbeddedX5C`
+
+`JWK.EmbeddedX5C` is a special key object that can be used with the JWS/JWT verify operations
+whenever you want to opt-in to verify signatures with a public key embedded in the first JWS Header
+`x5c` parameter. It is recommended to combine this with the verify `algorithms` option to whitelist
+JWS algorithms to accept as well as the `complete` option set to `true` if you need to work with the
+instantiated `JWK.Key` from the token. ⚠️ the x5c members are all validated to be certificates but
+their chain or trust is not validated. Unfortunately Node.js does not have any good tools to do that
+reliably.
+
+---
+
 ## JWKS (JSON Web Key Set)
 
 <!-- TOC JWKS START -->

lib/help/key_object.js

@@ -30,7 +30,7 @@ if (keyObjectSupported) {
  }
 
  const pemToDer = pem => Buffer.from(pem.replace(/(?:-----(?:BEGIN|END)(?: (?:RSA|EC))? (?:PRIVATE|PUBLIC) KEY-----|\s)/g, ''), 'base64')
- const derToPem = (der, label) => `-----BEGIN ${label}-----${EOL}${der.toString('base64').match(/.{1,64}/g).join(EOL)}${EOL}-----END ${label}-----`
+ const derToPem = (der, label) => `-----BEGIN ${label}-----${EOL}${(der.toString('base64').match(/.{1,64}/g) || []).join(EOL)}${EOL}-----END ${label}-----`
  const unsupported = (input) => {
  const label = typeof input === 'string' ? input : `OID ${input.join('.')}`
  throw new errors.JOSENotSupported(`${label} is not supported in your Node.js runtime version`)

lib/help/key_utils.js

@@ -10,7 +10,7 @@ const asn1 = require('./asn1')
 const computePrimes = require('./rsa_primes')
 const { OKP_CURVES, EC_CURVES } = require('../registry')
 
-const formatPem = (base64pem, descriptor) => `-----BEGIN ${descriptor} KEY-----${EOL}${base64pem.match(/.{1,64}/g).join(EOL)}${EOL}-----END ${descriptor} KEY-----`
+const formatPem = (base64pem, descriptor) => `-----BEGIN ${descriptor} KEY-----${EOL}${(base64pem.match(/.{1,64}/g) || []).join(EOL)}${EOL}-----END ${descriptor} KEY-----`
 
 const okpToJWK = {
  private (crv, keyObject) {

lib/jwk/index.js

@@ -1,13 +1,17 @@
 const Key = require('./key/base')
 const None = require('./key/none')
+const EmbeddedJWK = require('./key/embedded.jwk')
+const EmbeddedX5C = require('./key/embedded.x5c')
 const importKey = require('./import')
 const generate = require('./generate')
 
 module.exports = {
  ...generate,
  asKey: importKey,
  isKey: input => input instanceof Key,
- None
+ None,
+ EmbeddedJWK,
+ EmbeddedX5C
 }
 
 /* deprecated */

lib/jwk/key/base.js

@@ -61,7 +61,7 @@ class Key {
  let publicKey
  try {
  publicKey = createPublicKey({
- key: `-----BEGIN CERTIFICATE-----${EOL}${cert.match(/.{1,64}/g).join(EOL)}${EOL}-----END CERTIFICATE-----`, format: 'pem'
+ key: `-----BEGIN CERTIFICATE-----${EOL}${(cert.match(/.{1,64}/g) || []).join(EOL)}${EOL}-----END CERTIFICATE-----`, format: 'pem'
  })
  } catch (err) {
  throw new errors.JWKInvalid(`\`x5c\` member at index ${i} is not a valid base64-encoded DER PKIX certificate`)

lib/jwk/key/embedded.jwk.js

@@ -0,0 +1,27 @@
+const { inspect } = require('util')
+
+const Key = require('./base')
+
+class EmbeddedJWK extends Key {
+ constructor () {
+ super({ type: 'embedded' })
+ Object.defineProperties(this, {
+ kid: { value: undefined },
+ kty: { value: undefined },
+ thumbprint: { value: undefined },
+ toJWK: { value: undefined },
+ toPEM: { value: undefined }
+ })
+ }
+
+ /* c8 ignore next 3 */
+ [inspect.custom] () {
+ return 'Embedded.JWK {}'
+ }
+
+ algorithms () {
+ return new Set()
+ }
+}
+
+module.exports = new EmbeddedJWK()

lib/jwk/key/embedded.x5c.js

@@ -0,0 +1,27 @@
+const { inspect } = require('util')
+
+const Key = require('./base')
+
+class EmbeddedX5C extends Key {
+ constructor () {
+ super({ type: 'embedded' })
+ Object.defineProperties(this, {
+ kid: { value: undefined },
+ kty: { value: undefined },
+ thumbprint: { value: undefined },
+ toJWK: { value: undefined },
+ toPEM: { value: undefined }
+ })
+ }
+
+ /* c8 ignore next 3 */
+ [inspect.custom] () {
+ return 'Embedded.X5C {}'
+ }
+
+ algorithms () {
+ return new Set()
+ }
+}
+
+module.exports = new EmbeddedX5C()

lib/jwk/key/none.js

@@ -7,6 +7,7 @@ class NoneKey extends Key {
  super({ type: 'unsecured' }, { alg: 'none' })
  Object.defineProperties(this, {
  kid: { value: undefined },
+ kty: { value: undefined },
  thumbprint: { value: undefined },
  toJWK: { value: undefined },
  toPEM: { value: undefined }
@@ -30,4 +31,4 @@ class NoneKey extends Key {
  }
 }
 
-module.exports = new NoneKey({ type: 'unsecured' }, { alg: 'none' })
+module.exports = new NoneKey()

lib/jwks/keystore.js

@@ -3,7 +3,7 @@ const { deprecate, inspect } = require('util')
 const isObject = require('../help/is_object')
 const { generate, generateSync } = require('../jwk/generate')
 const { USES_MAPPING } = require('../help/consts')
-const { None, isKey, asKey: importKey } = require('../jwk')
+const { isKey, asKey: importKey } = require('../jwk')
 
 const keyscore = (key, { alg, use, ops }) => {
  let score = 0
@@ -35,7 +35,7 @@ class KeyStore {
  return acc
  }, [])
  }
- if (keys.some(k => !isKey(k) || k === None)) {
+ if (keys.some(k => !isKey(k) || !k.kty)) {
  throw new TypeError('all keys must be instances of a key instantiated by JWK.asKey')
  }
 
@@ -107,7 +107,7 @@ class KeyStore {
  }
 
  add (key) {
- if (!isKey(key) || key === None) {
+ if (!isKey(key) || !key.kty) {
  throw new TypeError('key must be an instance of a key instantiated by JWK.asKey')
  }
 

lib/jws/verify.js

@@ -1,10 +1,14 @@
+const { EOL } = require('os')
+
 const base64url = require('../help/base64url')
 const isDisjoint = require('../help/is_disjoint')
+const isObject = require('../help/is_object')
 let validateCrit = require('../help/validate_crit')
 const getKey = require('../help/get_key')
 const { KeyStore } = require('../jwks')
 const errors = require('../errors')
 const { check, verify } = require('../jwa')
+const JWK = require('../jwk')
 
 const { detect: resolveSerialization } = require('./serializers')
 
@@ -125,6 +129,24 @@ const jwsVerify = (skipDisjointCheck, serialization, jws, key, { crit = [], comp
  }
  }
 
+ if (key === JWK.EmbeddedJWK) {
+ if (!isObject(combinedHeader.jwk)) {
+ throw new errors.JWSInvalid('JWS Header Parameter "jwk" must be a JSON object')
+ }
+ key = JWK.asKey(combinedHeader.jwk)
+ if (key.type !== 'public') {
+ throw new errors.JWSInvalid('JWS Header Parameter "jwk" must be a public key')
+ }
+ } else if (key === JWK.EmbeddedX5C) {
+ if (!Array.isArray(combinedHeader.x5c) || !combinedHeader.x5c.length || combinedHeader.x5c.some(c => typeof c !== 'string' || !c)) {
+ throw new errors.JWSInvalid('JWS Header Parameter "x5c" must be a JSON array of certificate value strings')
+ }
+ key = JWK.asKey(
+ `-----BEGIN CERTIFICATE-----${EOL}${(combinedHeader.x5c[0].match(/.{1,64}/g) || []).join(EOL)}${EOL}-----END CERTIFICATE-----`,
+ { x5c: combinedHeader.x5c }
+ )
+ }
+
  check(key, 'verify', alg)
 
  const toBeVerified = Buffer.concat([