docs: update createLocalJWKSet and createRemoteJWKSet documentation

panva · Nov 2, 2023 · de98085 · de98085
1 parent 887dd3c
commit de98085
Show file tree

Hide file tree

Showing 2 changed files with 12 additions and 6 deletions.
diff --git 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
@@ -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