From 0ddbcc6725ecb2d68efdaf0951cec4db31cc9b16 Mon Sep 17 00:00:00 2001
From: Filip Skokan <panva.ip@gmail.com>
Date: Sat, 5 Mar 2022 14:47:56 +0100
Subject: [PATCH] feat: mark APIs and parameters that can lead to footguns as
 deprecated

---
 src/jwe/compact/encrypt.ts   | 11 +++++++----
 src/jwe/flattened/encrypt.ts | 11 +++++++----
 src/jwt/encrypt.ts           | 11 +++++++----
 src/types.d.ts               | 20 ++++++++++++++++++--
 4 files changed, 39 insertions(+), 14 deletions(-)

diff --git a/src/jwe/compact/encrypt.ts b/src/jwe/compact/encrypt.ts
index 6f7a74d852..ea6f331233 100644
--- a/src/jwe/compact/encrypt.ts
+++ b/src/jwe/compact/encrypt.ts
@@ -35,10 +35,11 @@ export class CompactEncrypt {
   /**
    * Sets a content encryption key to use, by default a random suitable one
    * is generated for the JWE enc" (Encryption Algorithm) Header Parameter.
-   * You do not need to invoke this method, it is only really intended for
-   * test and vector validation purposes.
    *
    * @param cek JWE Content Encryption Key.
+   *
+   * @deprecated You should not use this method. It is only really intended
+   * for test and vector validation purposes.
    */
   setContentEncryptionKey(cek: Uint8Array) {
     this._flattened.setContentEncryptionKey(cek)
@@ -48,10 +49,12 @@ export class CompactEncrypt {
   /**
    * Sets the JWE Initialization Vector to use for content encryption, by default
    * a random suitable one is generated for the JWE enc" (Encryption Algorithm)
-   * Header Parameter. You do not need to invoke this method, it is only really
-   * intended for test and vector validation purposes.
+   * Header Parameter.
    *
    * @param iv JWE Initialization Vector.
+   *
+   * @deprecated You should not use this method. It is only really intended
+   * for test and vector validation purposes.
    */
   setInitializationVector(iv: Uint8Array) {
     this._flattened.setInitializationVector(iv)
diff --git a/src/jwe/flattened/encrypt.ts b/src/jwe/flattened/encrypt.ts
index 9980dd93dd..6ed98e6fff 100644
--- a/src/jwe/flattened/encrypt.ts
+++ b/src/jwe/flattened/encrypt.ts
@@ -134,10 +134,11 @@ export class FlattenedEncrypt {
   /**
    * Sets a content encryption key to use, by default a random suitable one
    * is generated for the JWE enc" (Encryption Algorithm) Header Parameter.
-   * You do not need to invoke this method, it is only really intended for
-   * test and vector validation purposes.
    *
    * @param cek JWE Content Encryption Key.
+   *
+   * @deprecated You should not use this method. It is only really intended
+   * for test and vector validation purposes.
    */
   setContentEncryptionKey(cek: Uint8Array) {
     if (this._cek) {
@@ -150,10 +151,12 @@ export class FlattenedEncrypt {
   /**
    * Sets the JWE Initialization Vector to use for content encryption, by default
    * a random suitable one is generated for the JWE enc" (Encryption Algorithm)
-   * Header Parameter. You do not need to invoke this method, it is only really
-   * intended for test and vector validation purposes.
+   * Header Parameter.
    *
    * @param iv JWE Initialization Vector.
+   *
+   * @deprecated You should not use this method. It is only really intended
+   * for test and vector validation purposes.
    */
   setInitializationVector(iv: Uint8Array) {
     if (this._iv) {
diff --git a/src/jwt/encrypt.ts b/src/jwt/encrypt.ts
index 37cdae6f11..ef0bb5fb7d 100644
--- a/src/jwt/encrypt.ts
+++ b/src/jwt/encrypt.ts
@@ -73,10 +73,11 @@ export class EncryptJWT extends ProduceJWT {
   /**
    * Sets a content encryption key to use, by default a random suitable one
    * is generated for the JWE enc" (Encryption Algorithm) Header Parameter.
-   * You do not need to invoke this method, it is only really intended for
-   * test and vector validation purposes.
    *
    * @param cek JWE Content Encryption Key.
+   *
+   * @deprecated You should not use this method. It is only really intended
+   * for test and vector validation purposes.
    */
   setContentEncryptionKey(cek: Uint8Array) {
     if (this._cek) {
@@ -89,10 +90,12 @@ export class EncryptJWT extends ProduceJWT {
   /**
    * Sets the JWE Initialization Vector to use for content encryption, by default
    * a random suitable one is generated for the JWE enc" (Encryption Algorithm)
-   * Header Parameter. You do not need to invoke this method, it is only really
-   * intended for test and vector validation purposes.
+   * Header Parameter.
    *
    * @param iv JWE Initialization Vector.
+   *
+   * @deprecated You should not use this method. It is only really intended
+   * for test and vector validation purposes.
    */
   setInitializationVector(iv: Uint8Array) {
     if (this._iv) {
diff --git a/src/types.d.ts b/src/types.d.ts
index 739dfc3297..25bd8f62c7 100644
--- a/src/types.d.ts
+++ b/src/types.d.ts
@@ -319,10 +319,26 @@ export interface JWSHeaderParameters extends JoseHeaderParameters {
 export interface JWEKeyManagementHeaderParameters {
   apu?: Uint8Array
   apv?: Uint8Array
-  epk?: KeyLike
-  iv?: Uint8Array
+  /**
+   * @deprecated You should not use this parameter. It is only really intended
+   * for test and vector validation purposes.
+   */
   p2c?: number
+  /**
+   * @deprecated You should not use this parameter. It is only really intended
+   * for test and vector validation purposes.
+   */
   p2s?: Uint8Array
+  /**
+   * @deprecated You should not use this parameter. It is only really intended
+   * for test and vector validation purposes.
+   */
+  iv?: Uint8Array
+  /**
+   * @deprecated You should not use this parameter. It is only really intended
+   * for test and vector validation purposes.
+   */
+  epk?: KeyLike
 }
 
 /**