docs: add ECKey.derive_key and OKPKey.derive_key on guide

Author: lepture

README.md

@@ -22,12 +22,12 @@
 A quick and simple JWT encoding and decoding would look something like this:
 
 ```python
-from joserfc import jwt
+from joserfc import jwt, jwk
 from joserfc.jwk import OctKey
 
-key = OctKey.import_key("secret")
+key = jwk.import_key("your-secret-key", "oct")
 encoded = jwt.encode({"alg": "HS256"}, {"k": "value"}, key)
-# 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrIjoidmFsdWUifQ.ni-MJXnZHpFB_8L9P9yllj3RNDfzmD4yBKAyefSctMY'
+# 'eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrIjoidmFsdWUifQ._M8ViO_GK6TnZ9G9eqdlS7IpNWzhoGwaYYDQ3hEwwmA'
 
 token = jwt.decode(encoded, key)
 print(token.header)

docs/changelog.rst

@@ -12,7 +12,7 @@ Changelog
 .. module:: joserfc
     :noindex:
 
-1.x.x
+1.6.0
 -----
 
 **Unreleased**
@@ -23,6 +23,7 @@ Changelog
 - Improve ``generate_private_key`` method on Key's binding class.
 - Raise ``InvalidKeyCurveError`` when generating ECKey with an invalid curve.
 - Allow import key from cryptography native key types.
+- Add ``ECKey.derive_key`` and ``OKPKey.derive_key`` class methods.
 
 1.5.0
 -----

docs/guide/jwk.rst

@@ -174,6 +174,31 @@ You can import an ``ECKey`` from string, bytes and a JWK (in dict).
         "d": "Hndv7ZZjs_ke8o9zXYo3iq-Yr8SewI5vrqd0pAvEPqg"
     })
 
+Derive an "EC" Key
+~~~~~~~~~~~~~~~~~~
+
+``joserfc`` provides deterministic key derivation helpers for EC key.
+This method allows applications to derive a *stable* JWK from an application
+secret (for example, ``SECRET_KEY`` in a web framework), while still producing
+valid cryptographic keys for use in JWS/JWE.
+
+.. code-block:: python
+
+    from joserfc.jwk import ECKey
+
+    ECKey.derive_key("your-secret-key", "P-256")
+    ECKey.derive_key("your-secret-key", "P-256", kdf_name="HKDF")
+
+Supported key derivation functions:
+
+- **HKDF** (recommended)
+- **PBKDF2** (password-based, may require higher iteration counts)
+
+.. warning::
+    Deterministic keys are useful for applications that want a stable default JWK,
+    but **they should not be used where random key generation is required**.
+
+
 .. _OKPKey:
 
 OKPKey
@@ -224,6 +249,24 @@ You can import an ``OKPKey`` from string, bytes and a JWK (in dict).
         "kid": "5V_IcL-iX5IbaNz9vg0CjXtWLZiJ94-ESnHI-HN1L2Y"
     })
 
+Derive an "OKP" Key
+~~~~~~~~~~~~~~~~~~~
+
+Just like above ``ECKey``, ``joserfc`` provides a ``OKPKey.derive_key`` method
+to derive a *stable* JWK.
+
+.. code-block:: python
+
+    from joserfc.jwk import OKPKey
+
+    OKPKey.derive_key("your-secret-key", "Ed25519")
+    OKPKey.derive_key("your-secret-key", "Ed25519", kdf_name="HKDF")
+
+Supported key derivation functions:
+
+- **HKDF** (recommended)
+- **PBKDF2** (password-based, may require higher iteration counts)
+
 Key Set
 -------