feat: allow to modify issued JWT headers and payloads before signing

panva · Sep 16, 2024 · 30931ba · 30931ba
1 parent 006db55
commit 30931ba
Show file tree

Hide file tree

Showing 9 changed files with 282 additions and 44 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -177,6 +177,7 @@ Support from the community to continue maintaining and improving this module is
 - [JWKS](interfaces/JWKS.md)
 - [JWKSCacheOptions](interfaces/JWKSCacheOptions.md)
 - [JWTAccessTokenClaims](interfaces/JWTAccessTokenClaims.md)
+- [ModifyAssertionFunction](interfaces/ModifyAssertionFunction.md)
 - [MTLSEndpointAliases](interfaces/MTLSEndpointAliases.md)
 - [OAuth2Error](interfaces/OAuth2Error.md)
 - [OAuth2TokenEndpointResponse](interfaces/OAuth2TokenEndpointResponse.md)
@@ -215,6 +216,7 @@ Support from the community to continue maintaining and improving this module is
 - [expectNoNonce](variables/expectNoNonce.md)
 - [expectNoState](variables/expectNoState.md)
 - [jwksCache](variables/jwksCache.md)
+- [modifyAssertion](variables/modifyAssertion.md)
 - [skipAuthTimeCheck](variables/skipAuthTimeCheck.md)
 - [skipStateCheck](variables/skipStateCheck.md)
 - [skipSubjectCheck](variables/skipSubjectCheck.md)

diff --git a/docs/interfaces/DPoPOptions.md b/docs/interfaces/DPoPOptions.md
@@ -26,6 +26,18 @@ The public key corresponding to [DPoPOptions.privateKey](DPoPOptions.md#privatek
 
 ***
 
+### \[modifyAssertion\]?
+
+• `optional` **\[modifyAssertion\]**: [`ModifyAssertionFunction`](ModifyAssertionFunction.md)
+
+Use to modify the DPoP Proof JWT right before it is signed.
+
+#### See
+
+[modifyAssertion](../variables/modifyAssertion.md)
+
+***
+
 ### nonce?
 
 • `optional` **nonce**: `string`

diff --git a/docs/interfaces/ModifyAssertionFunction.md b/docs/interfaces/ModifyAssertionFunction.md
@@ -0,0 +1,20 @@
+# Interface: ModifyAssertionFunction()
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+▸ **ModifyAssertionFunction**(`header`, `payload`): `void`
+
+## Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `header` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `undefined` \| [`JsonValue`](../type-aliases/JsonValue.md)\> | JWS Header to modify right before it is signed. |
+| `payload` | [`Record`](https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type)\<`string`, `undefined` \| [`JsonValue`](../type-aliases/JsonValue.md)\> | JWT Claims Set to modify right before it is signed. |
+
+## Returns
+
+`void`
diff --git a/docs/interfaces/PrivateKey.md b/docs/interfaces/PrivateKey.md
@@ -21,6 +21,18 @@ Its algorithm must be compatible with a supported [JWS `alg` Algorithm](../type-
 
 ***
 
+### \[modifyAssertion\]?
+
+• `optional` **\[modifyAssertion\]**: [`ModifyAssertionFunction`](ModifyAssertionFunction.md)
+
+Use to modify the JWT signed by this key right before it is signed.
+
+#### See
+
+[modifyAssertion](../variables/modifyAssertion.md)
+
+***
+
 ### kid?
 
 • `optional` **kid**: `string`

diff --git a/docs/variables/modifyAssertion.md b/docs/variables/modifyAssertion.md
@@ -0,0 +1,55 @@
+# Variable: modifyAssertion
+
+[💗 Help the project](https://github.com/sponsors/panva)
+
+Support from the community to continue maintaining and improving this module is welcome. If you find the module useful, please consider supporting the project by [becoming a sponsor](https://github.com/sponsors/panva).
+
+***
+
+• `const` **modifyAssertion**: unique `symbol`
+
+Use to mutate JWT header and payload before they are signed. Its intended use is working around
+non-conform server behaviours, such as modifying JWT "aud" (audience) claims, or otherwise
+changing fixed claims used by this library.
+
+## Examples
+
+Changing Private Key JWT client assertion audience issued from an array to a string
+
+```ts
+import * as oauth from 'oauth4webapi'
+
+// Prerequisites
+let as!: oauth.AuthorizationServer
+let client!: oauth.Client
+let parameters!: URLSearchParams
+let clientPrivateKey!: CryptoKey
+
+const response = await oauth.pushedAuthorizationRequest(as, client, parameters, {
+  clientPrivateKey: {
+    key: clientPrivateKey,
+    [oauth.modifyAssertion](header, payload) {
+      payload.aud = as.issuer
+    },
+  },
+})
+```
+
+Changing Request Object issued by [issueRequestObject](../functions/issueRequestObject.md) to have an expiration of 5 minutes
+
+```ts
+import * as oauth from 'oauth4webapi'
+
+// Prerequisites
+let as!: oauth.AuthorizationServer
+let client!: oauth.Client
+let parameters!: URLSearchParams
+let jarPrivateKey!: CryptoKey
+
+const request = await oauth.issueRequestObject(as, client, parameters, {
+  key: jarPrivateKey,
+  [oauth.modifyAssertion](header, payload) {
+    payload.exp = <number>payload.iat + 300
+  },
+})
+```