Merge pull request #6 from cwirving/jose-header-extra-fields

Add the ability to provide arbitrary custom header claims

README.md

@@ -79,6 +79,13 @@ const data = await validateJWT(jwt, false);
 const unsafeData = unsafeParseJWT(jwt);
 ```
 
+- **`unsafeParseJOSEHeader(jwt: string): JOSEHeader`**
+
+```javascript
+// "unsafely" parse the JOSE header of a JWT without cryptokey.
+const unsafeData = unsafeParseJOSEHeader(jwt);
+```
+
 **Helper Functions**
 
 - **`generateKey(keyStr: string, optionsOrAlgorithm?: SupportedKeyAlgorithms | Options): Promise<CryptoKey>`**
@@ -187,9 +194,21 @@ interface JWTOptions {
     //A duration string (e.g., "5m") specifying the "not before" time claim relative to the current time.
     //Cannot be used if the `nbf` claim is explicitly set in the payload.
     notBefore?: string;
+    // Additional claims to include as part of the JWT's JOSE header.
+    additionalHeaderClaims?: JOSEHeader;
 }
 ```
 
+**Working with JWT Headers**
+
+Some usage scenarios, such as interoperating with OIDC providers that set key identifier (`kid`) header claims in the
+JWTs they issue, require JWT header introspection. Similarly, it is sometimes necessary to create tokens with additional
+header claims or override existing claims (e.g., the `typ` claim).
+
+The `additionalHeaderClaims` property in the `JWTOptions` provide the means to set/override header claims in tokens
+created through `signJWT`. Conversely, the `unsafeParseJOSEHeader` function reads the header claims of a token without
+validating it.
+
 ## Supported algorithms
 
 | Algorithm | Description                                    |

mod.test.ts

@@ -136,7 +136,7 @@ test("signJWT() supports additional header claims", async () => {
     const payload = { foo: "bar", baz: 42 };
     const jwtString = await signJWT(payload, privateKey, {
         algorithm: algorithm,
-        additionalHeaderClaims: { typ: "JOSE", kid: "abc123" },
+        additionalHeaderClaims: { typ: "JOSE", kid: "abc123", someOther: [1, 2, 3] },
     });
 
     const unsafeHeader = unsafeParseJOSEHeader(jwtString);
@@ -145,7 +145,7 @@ test("signJWT() supports additional header claims", async () => {
 
     assertEquals(unsafePayload, payload);
     assertEquals(decodedPayload, payload);
-    const expectedHeader: JOSEHeader = { alg: algorithm, typ: "JOSE", kid: "abc123" };
+    const expectedHeader: JOSEHeader = { alg: algorithm, typ: "JOSE", kid: "abc123", someOther: [1, 2, 3] };
     assertEquals(unsafeHeader, expectedHeader);
 });
 
@@ -173,7 +173,7 @@ test("validateJWT() throws JWTValidationError on stripped token", async () => {
     // unsigned token as the real item.
     const jwtString = await signJWT(payload, false);
 
-    assertRejects(
+    await assertRejects(
         () => validateJWT(jwtString, keyPair.publicKey),
         JWTValidationError,
     );

src/standardclaims.ts

@@ -30,6 +30,12 @@ export interface JOSEHeader {
      * (see RFC 7519 section 5.1, RFC 7515 section 4.1.9, RFC 7516 section 4.1.11)
      */
     typ?: string;
+
+    /**
+     * Allows for the inclusion of other header properties with string keys and values of any type.
+     */
+    // deno-lint-ignore no-explicit-any
+    [key: string]: any;
 }
 
 /**