feat: mark APIs and parameters that can lead to footguns as deprecated

panva · Mar 6, 2022 · 0ddbcc6 · 0ddbcc6
1 parent 17e30f7
commit 0ddbcc6
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 14 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
 }
 
 /**