feat: add JWS.verify encoding and parsing options

docs/README.md

@@ -1103,6 +1103,10 @@ Verifies the provided JWS in either serialization with a given `<JWK.Key>` or `<
     algorithms available on the keys
   - `complete`: `<boolean>` When true returns a complete object with the parsed headers and payload
     instead of just the verified payload. **Default:** 'false'
+  - `parse`: `<boolean>` When true attempts to JSON.parse the payload and falls back to returning
+    the payload encoded using the specified encoding. When false returns the payload as a Buffer.
+    **Default:** 'true'
+  - `encoding`: `string` The encoding to use for the payload. **Default:** 'utf8'
   - `crit`: `string[]` Array of Critical Header Parameter names to recognize. **Default:** '[]'
 - Returns: `<string>` &vert; `<Object>`
 

lib/help/base64url.js

@@ -26,24 +26,24 @@ const decodeToBuffer = (input) => {
   return Buffer.from(toBase64(input), 'base64')
 }
 
-const decode = (input) => {
-  return decodeToBuffer(input).toString('utf8')
+const decode = (input, encoding = 'utf8') => {
+  return decodeToBuffer(input).toString(encoding)
 }
 
 const b64uJSON = {
   encode: (input) => {
     return encode(JSON.stringify(input))
   },
-  decode: (input) => {
-    return JSON.parse(decode(input))
+  decode: (input, encoding = 'utf8') => {
+    return JSON.parse(decode(input, encoding))
   }
 }
 
-b64uJSON.decode.try = (input) => {
+b64uJSON.decode.try = (input, encoding = 'utf8') => {
   try {
-    return b64uJSON.decode(input)
+    return b64uJSON.decode(input, encoding)
   } catch (err) {
-    return decode(input)
+    return decode(input, encoding)
   }
 }
 

lib/jws/verify.js

@@ -14,7 +14,7 @@ const SINGLE_RECIPIENT = new Set(['compact', 'flattened'])
 /*
  * @public
  */
-const jwsVerify = (skipDisjointCheck, serialization, jws, key, { crit = [], complete = false, algorithms } = {}) => {
+const jwsVerify = (skipDisjointCheck, serialization, jws, key, { crit = [], complete = false, algorithms, parse = true, encoding = 'utf8' } = {}) => {
   if (!(key instanceof Key) && !(key instanceof KeyStore)) {
     throw new TypeError('key must be an instance of a key instantiated by JWK.asKey or a JWKS.KeyStore')
   }
@@ -104,7 +104,7 @@ const jwsVerify = (skipDisjointCheck, serialization, jws, key, { crit = [], comp
           const errs = []
           for (const key of keys) {
             try {
-              return jwsVerify(true, serialization, jws, key, { crit, complete, algorithms: algorithms ? [...algorithms] : undefined })
+              return jwsVerify(true, serialization, jws, key, { crit, complete, encoding, parse, algorithms: algorithms ? [...algorithms] : undefined })
             } catch (err) {
               errs.push(err)
               continue
@@ -127,7 +127,11 @@ const jwsVerify = (skipDisjointCheck, serialization, jws, key, { crit = [], comp
     }
 
     if (!combinedHeader.crit || !combinedHeader.crit.includes('b64') || combinedHeader.b64) {
-      payload = base64url.JSON.decode.try(payload)
+      if (parse) {
+        payload = base64url.JSON.decode.try(payload, encoding)
+      } else {
+        payload = base64url.decodeToBuffer(payload)
+      }
     }
 
     if (complete) {
@@ -145,7 +149,7 @@ const jwsVerify = (skipDisjointCheck, serialization, jws, key, { crit = [], comp
   const errs = []
   for (const recipient of signatures) {
     try {
-      return jwsVerify(false, 'flattened', { ...root, ...recipient }, key, { crit, complete, algorithms: algorithms ? [...algorithms] : undefined })
+      return jwsVerify(false, 'flattened', { ...root, ...recipient }, key, { crit, complete, encoding, parse, algorithms: algorithms ? [...algorithms] : undefined })
     } catch (err) {
       errs.push(err)
       continue

test/jws/encoding.test.js

@@ -0,0 +1,35 @@
+const test = require('ava')
+
+const { randomBytes } = require('crypto')
+
+const { JWK, JWS } = require('../../lib')
+
+const key = JWK.generateSync('oct')
+
+test('JWS.verify can skip parsing the payload', t => {
+  let payload = 'foo'
+  let jws = JWS.sign(payload, key)
+  t.deepEqual(JWS.verify(jws, key, { parse: false }), Buffer.from(payload))
+
+  jws = JWS.sign.flattened(payload, key)
+  t.deepEqual(JWS.verify(jws, key, { parse: false }), Buffer.from(payload))
+  t.deepEqual(JWS.verify(jws, key, { parse: false, complete: true }), { key, protected: { alg: 'HS256' }, payload: Buffer.from(payload) })
+
+  payload = randomBytes(8)
+
+  jws = JWS.sign(payload, key)
+  t.deepEqual(JWS.verify(jws, key, { parse: false }), payload)
+  t.deepEqual(JWS.verify(jws, key, { parse: false, complete: true }), { key, protected: { alg: 'HS256' }, payload: payload })
+})
+
+test('JWS.verify can parse any valid encoding', t => {
+  let jws = JWS.sign('foo', key)
+  t.deepEqual(JWS.verify(jws, key, { encoding: 'hex' }), '666f6f')
+  t.deepEqual(JWS.verify(jws, key, { encoding: 'base64' }), 'Zm9v')
+
+  jws = JWS.sign.flattened('foo', key)
+  t.deepEqual(JWS.verify(jws, key, { encoding: 'hex' }), '666f6f')
+  t.deepEqual(JWS.verify(jws, key, { complete: true, encoding: 'hex' }), { key, protected: { alg: 'HS256' }, payload: '666f6f' })
+  t.deepEqual(JWS.verify(jws, key, { encoding: 'base64' }), 'Zm9v')
+  t.deepEqual(JWS.verify(jws, key, { complete: true, encoding: 'base64' }), { key, protected: { alg: 'HS256' }, payload: 'Zm9v' })
+})

types/index.d.ts

@@ -250,21 +250,25 @@ export namespace JWS {
     function general(payload: string | Buffer | object, key: JWK.Key, protected?: object, header?: object): GeneralJWS;
   }
 
-  interface VerifyOptions<komplet> {
+  interface VerifyOptions<komplet = false, parse = true> {
     complete?: komplet;
+    parse?: parse;
+    encoding?: BufferEncoding;
     crit?: string[];
     algorithms?: string[];
   }
 
-  interface completeVerification {
-    payload: string | object;
+  interface completeVerification<T> {
+    payload: T;
     key: JWK.Key;
     protected?: object;
     header?: object;
   }
 
-  function verify(jws: string | FlattenedJWS | GeneralJWS, key: JWK.Key | JWKS.KeyStore, options?: VerifyOptions<false>): string | object;
-  function verify(jws: string | FlattenedJWS | GeneralJWS, key: JWK.Key | JWKS.KeyStore, options?: VerifyOptions<true>): completeVerification;
+  function verify(jws: string | FlattenedJWS | GeneralJWS, key: JWK.Key | JWKS.KeyStore, options?: VerifyOptions): string | object;
+  function verify(jws: string | FlattenedJWS | GeneralJWS, key: JWK.Key | JWKS.KeyStore, options?: VerifyOptions<false, false>): Buffer;
+  function verify(jws: string | FlattenedJWS | GeneralJWS, key: JWK.Key | JWKS.KeyStore, options?: VerifyOptions<true>): completeVerification<string | object>;
+  function verify(jws: string | FlattenedJWS | GeneralJWS, key: JWK.Key | JWKS.KeyStore, options?: VerifyOptions<true, false>): completeVerification<Buffer>;
 }
 
 export namespace JWE {