docs: update docs for JWSRegistry.guess_alg

Author: lepture

docs/changelog.rst

@@ -20,6 +20,7 @@ Changelog
 - Exporting all algorithms in ``joserfc.jwa`` module.
 - Allow re-using ``JWTClaimsRegistry`` instance, via :issue:`68`.
 - Added ``claim`` attribute on claim errors, via :issue:`69`.
+- Added ``JWSRegistry.guess_alg`` method, via :issue:`49`.
 
 **Breaking changes**:
 

docs/guide/jws.rst

@@ -325,14 +325,11 @@ JWS (JSON Web Signature) to remain unencoded, without using base64 encoding.
 To enable this option, you need to set the ``b64`` header parameter to ``false``
 in the JWS header.
 
-To utilize the unencoded payload option in joserfc, you must import the
-serialize and deserialize methods from ``joserfc.rfc7797``.
-
 Here are examples demonstrating the usage of the ``b64`` option:
 
 .. code-block:: python
 
-    from joserfc.rfc7797 import serialize_compact, deserialize_compact
+    from joserfc.jws import serialize_compact, deserialize_compact
     from joserfc.jwk import OctKey
 
     key = OctKey.import_key("secret")
@@ -351,7 +348,7 @@ characters, the compact serialization will detach the payload:
 
 .. code-block:: python
 
-    from joserfc.rfc7797 import serialize_compact, deserialize_compact
+    from joserfc.jws import serialize_compact, deserialize_compact
     from joserfc.jwk import OctKey
 
     key = OctKey.import_key("secret")
@@ -362,5 +359,19 @@ characters, the compact serialization will detach the payload:
     # payload when calling deserialize_compact
     deserialize_compact(value, key, payload="$.02")
 
-There are also methods for JSON serialization: ``serialize_json`` and
+You can also use ``b64`` header for JSON serialization: ``serialize_json`` and
 ``deserialize_json``.
+
+Guess Algorithms via Key
+------------------------
+
+If you are unsure which algorithm to use but already have a key, you can call the
+:meth:`jws.JWSRegistry.guess_alg` method to determine a suitable algorithm:
+
+.. code-block:: python
+
+    from joserfc.jws import JWSRegistry, serialize_compact
+
+    alg = JWSRegistry.guess_alg(key, JWSRegistry.Strategy.RECOMMENDED)
+    protected = {"alg": alg}
+    serialize_compact(protected, b"payload", key)

docs/index.rst

@@ -49,9 +49,10 @@ It follows RFCs with extensible API. The module has implementations of:
 - RFC7519: :ref:`JSON Web Token <jwt>`
 - RFC7520: Examples of Protecting Content Using JSON Object Signing and Encryption
 - RFC7638: ``thumbprint`` for JWK
+- RFC7797: JSON Web Signature (JWS) :ref:`Unencoded Payload Option <rfc7797>`
 - RFC8037: :ref:`OKPKey` and ``EdDSA`` algorithm
 - RFC8812: ``ES256K`` algorithm
-- RFC9278: ``thumbprint_uri`` for JWK
+- RFC9278: JWK Thumbprint URI (``thumbprint_uri``)
 
 And draft RFCs implementation of:
 

src/joserfc/_rfc7515/registry.py

@@ -31,7 +31,9 @@ class JWSRegistry:
     """
 
     class Strategy(Enum):
+        #: find the recommended algorithm
         RECOMMENDED = 1
+        #: find the most secure algorithm
         SECURITY = 2
 
     default_header_registry: HeaderRegistryDict = JWS_HEADER_REGISTRY

src/joserfc/_rfc7519/claims.py

@@ -87,7 +87,7 @@ class JWTClaimsRegistry(ClaimsRegistry):
 
     :param now: timestamp of "now" time
     :param leeway: leeway time in seconds
-    :param **kwargs: claims options
+    :param kwargs: claims options
     """
 
     def __init__(self, now: int | Callable[[], int] | None = None, leeway: int = 0, **kwargs: ClaimsOption) -> None: