From de98085a0f7d89a24ec840c73aa7a435704ff442 Mon Sep 17 00:00:00 2001
From: Filip Skokan <panva.ip@gmail.com>
Date: Thu, 2 Nov 2023 11:06:25 +0100
Subject: [PATCH] docs: update createLocalJWKSet and createRemoteJWKSet
 documentation

---
 src/jwks/local.ts  |  7 +++++--
 src/jwks/remote.ts | 11 +++++++----
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/src/jwks/local.ts b/src/jwks/local.ts
index ece0bd02b8..3fe40a7745 100644
--- a/src/jwks/local.ts
+++ b/src/jwks/local.ts
@@ -174,8 +174,8 @@ async function importWithAlgCache<KeyLikeType extends KeyLike = KeyLike>(
 }
 
 /**
- * Returns a function that resolves to a key object from a locally stored, or otherwise available,
- * JSON Web Key Set.
+ * Returns a function that resolves a JWS JOSE Header to a public key object from a locally stored,
+ * or otherwise available, JSON Web Key Set.
  *
  * It uses the "alg" (JWS Algorithm) Header Parameter to determine the right JWK "kty" (Key Type),
  * then proceeds to match the JWK "kid" (Key ID) with one found in the JWS Header Parameters (if
@@ -186,6 +186,9 @@ async function importWithAlgCache<KeyLikeType extends KeyLike = KeyLike>(
  * multiple keys get matched it is possible to opt-in to iterate over the matched keys and attempt
  * verification in an iterative manner.
  *
+ * Note: The function's purpose is to resolve public keys used for verifying signatures and will not
+ * work for public encryption keys.
+ *
  * @example
  *
  * ```js
diff --git a/src/jwks/remote.ts b/src/jwks/remote.ts
index d0236d15a8..060c19fce3 100644
--- a/src/jwks/remote.ts
+++ b/src/jwks/remote.ts
@@ -163,10 +163,10 @@ class RemoteJWKSet<KeyLikeType extends KeyLike = KeyLike> extends LocalJWKSet<Ke
 }
 
 /**
- * Returns a function that resolves to a key object downloaded from a remote endpoint returning a
- * JSON Web Key Set, that is, for example, an OAuth 2.0 or OIDC jwks_uri. The JSON Web Key Set is
- * fetched when no key matches the selection process but only as frequently as the
- * `cooldownDuration` option allows to prevent abuse.
+ * Returns a function that resolves a JWS JOSE Header to a public key object downloaded from a
+ * remote endpoint returning a JSON Web Key Set, that is, for example, an OAuth 2.0 or OIDC
+ * jwks_uri. The JSON Web Key Set is fetched when no key matches the selection process but only as
+ * frequently as the `cooldownDuration` option allows to prevent abuse.
  *
  * It uses the "alg" (JWS Algorithm) Header Parameter to determine the right JWK "kty" (Key Type),
  * then proceeds to match the JWK "kid" (Key ID) with one found in the JWS Header Parameters (if
@@ -177,6 +177,9 @@ class RemoteJWKSet<KeyLikeType extends KeyLike = KeyLike> extends LocalJWKSet<Ke
  * multiple keys get matched it is possible to opt-in to iterate over the matched keys and attempt
  * verification in an iterative manner.
  *
+ * Note: The function's purpose is to resolve public keys used for verifying signatures and will not
+ * work for public encryption keys.
+ *
  * @example
  *
  * ```js