feat: added utility function for decoding token's protected header

package.json

@@ -235,6 +235,15 @@
       "import": "./dist/node/webcrypto/esm/util/base64url.js",
       "require": "./dist/node/webcrypto/cjs/util/base64url.js"
     },
+    "./util/decode_protected_header": {
+      "browser": "./dist/browser/util/decode_protected_header.js",
+      "import": "./dist/node/esm/util/decode_protected_header.js",
+      "require": "./dist/node/cjs/util/decode_protected_header.js"
+    },
+    "./webcrypto/util/decode_protected_header": {
+      "import": "./dist/node/webcrypto/esm/util/decode_protected_header.js",
+      "require": "./dist/node/webcrypto/cjs/util/decode_protected_header.js"
+    },
     "./util/errors": {
       "browser": "./dist/browser/util/errors.js",
       "import": "./dist/node/esm/util/errors.js",

src/util/decode_protected_header.ts

@@ -0,0 +1,58 @@
+import { ok as assert } from 'assert'
+
+import { decode as base64url } from './base64url.js'
+import { decoder } from '../lib/buffer_utils.js'
+import isObject from '../lib/is_object.js'
+import type { JWSHeaderParameters, JWEHeaderParameters } from '../types.d'
+
+export type ProtectedHeaderParameters = JWSHeaderParameters & JWEHeaderParameters
+
+/**
+ * Decodes the Protected Header of a JWE/JWS/JWT token utilizing any encoding.
+ *
+ * @example
+ * ```
+ * // ESM import
+ * import decodeProtectedHeader from 'jose/util/decode_protected_header'
+ * ```
+ *
+ * @example
+ * ```
+ * // CJS import
+ * const { default: decodeProtectedHeader } = require('jose/util/decode_protected_header')
+ * ```
+ *
+ * @example
+ * ```
+ * // usage
+ * const protectedHeader = decodeProtectedHeader(token)
+ * console.log(protectedHeader)
+ * ```
+ *
+ * @param token JWE/JWS/JWT token in any encoding.
+ */
+export default function decodeProtectedHeader(token: string | object) {
+  let protectedB64u!: string
+
+  if (typeof token === 'string') {
+    const parts = token.split('.')
+    if (parts.length === 3 || parts.length === 5) {
+      ;[protectedB64u] = parts
+    }
+  } else if (typeof token === 'object' && token) {
+    if ('protected' in token) {
+      protectedB64u = (<{ protected: string }>token).protected
+    } else {
+      throw new TypeError('Token does not contain a Protected Header')
+    }
+  }
+
+  try {
+    assert(typeof protectedB64u === 'string' && protectedB64u)
+    const result = JSON.parse(decoder.decode(base64url(protectedB64u!)))
+    assert(isObject(result))
+    return <ProtectedHeaderParameters>result
+  } catch (err) {
+    throw new TypeError('Invalid Token or Protected Header formatting')
+  }
+}

test/util/decode_protected_header.test.mjs

@@ -0,0 +1,94 @@
+import test from 'ava';
+
+const root = !('WEBCRYPTO' in process.env) ? '#dist' : '#dist/webcrypto';
+
+import(`${root}/util/decode_protected_header`).then(
+  ({ default: decodeProtectedHeader }) => {
+    test('invalid inputs', (t) => {
+      t.throws(() => decodeProtectedHeader(null), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader('.'), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader('ew..'), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader('bnVsbA..'), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader('W10..'), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader('...'), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader('ew....'), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader('bnVsbA....'), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader('W10....'), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader('.....'), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader({ protected: null }), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader({ protected: 'ew' }), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader({ protected: 'bnVsbA' }), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader({ protected: 'W10' }), {
+        instanceOf: TypeError,
+        message: 'Invalid Token or Protected Header formatting',
+      });
+
+      t.throws(() => decodeProtectedHeader({}), {
+        instanceOf: TypeError,
+        message: 'Token does not contain a Protected Header',
+      });
+
+      t.deepEqual(decodeProtectedHeader('eyJhbGciOiJIUzI1NiJ9..'), { alg: 'HS256' });
+      t.deepEqual(decodeProtectedHeader('eyJhbGciOiJIUzI1NiJ9....'), { alg: 'HS256' });
+      t.deepEqual(decodeProtectedHeader({ protected: 'eyJhbGciOiJIUzI1NiJ9' }), { alg: 'HS256' });
+    });
+  },
+  (err) => {
+    test('failed to import', (t) => {
+      console.error(err);
+      t.fail();
+    });
+  },
+);

tsconfig/base.json

@@ -28,6 +28,7 @@
     "../src/util/errors.ts",
     "../src/util/generate_key_pair.ts",
     "../src/util/generate_secret.ts",
+    "../src/util/decode_protected_header.ts",
     "../src/util/random.ts"
   ],
   "compilerOptions": {