feat: use InvalidHeaderValueError in registry header validation

docs/guide/jwt.rst

@@ -291,7 +291,7 @@ Algorithms & Registry
 
 The :meth:`encode` and :meth:`decode` accept an ``algorithms`` parameter for
 specifying the allowed algorithms. By default, it only allows your to use
-recommended algorithms.
+**recommended** algorithms.
 
 You can find out the recommended algorithms at:
 

docs/guide/registry.rst

@@ -73,13 +73,13 @@ the value type.
     >>> jws.serialize_compact({"alg": "HS256", "kid": 123}, "hello", key)
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
-      File "$/joserfc/jws.py", line 98, in serialize_compact
+      File ".../joserfc/jws.py", line 111, in serialize_compact
         registry.check_header(protected)
-      File "$/joserfc/rfc7515/registry.py", line 63, in check_header
+      File ".../joserfc/rfc7515/registry.py", line 68, in check_header
         validate_registry_header(self.header_registry, header)
-      File "$/joserfc/registry.py", line 193, in validate_registry_header
-        raise ValueError(f'"{key}" in header {error}')
-    ValueError: "kid" in header must be a str
+      File ".../joserfc/registry.py", line 194, in validate_registry_header
+        raise InvalidHeaderValueError(f"'{key}' in header {error}")
+    joserfc.errors.InvalidHeaderValueError: invalid_header_value: 'kid' in header must be a str
 
 In the above example, ``kid`` MUST be a string instead of an integer. The default
 registry validates the ``kid`` before processing the serialization.
@@ -99,13 +99,13 @@ indicating that they must be present. For example:
     >>> jws.serialize_compact({"alg": "HS256", "crit": ["kid"]}, "hello", key)
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
-      File "$/joserfc/jws.py", line 98, in serialize_compact
+      File ".../joserfc/jws.py", line 111, in serialize_compact
         registry.check_header(protected)
-      File "$/joserfc/rfc7515/registry.py", line 62, in check_header
+      File ".../joserfc/rfc7515/registry.py", line 67, in check_header
         check_crit_header(header)
-      File "$/joserfc/registry.py", line 195, in check_crit_header
-        raise ValueError(f'"{k}" is a critical header')
-    ValueError: "kid" is a critical header
+      File ".../joserfc/registry.py", line 202, in check_crit_header
+        raise MissingCritHeaderError(k)
+    joserfc.errors.MissingCritHeaderError: missing_crit_header: Missing critical 'kid' value in header
 
 Since "kid" is listed as a critical (``crit``) header parameter, it is mandatory
 and must be included in the header.
@@ -124,13 +124,13 @@ Any additional header beyond those supported by the algorithm will result in an
     >>> jws.serialize_compact({"alg": "HS256", "custom": "hi"}, "hello", key)
     Traceback (most recent call last):
       File "<stdin>", line 1, in <module>
-      File "/home/lepture/authlib/joserfc/src/joserfc/jws.py", line 98, in serialize_compact
+      File ".../joserfc/jws.py", line 111, in serialize_compact
         registry.check_header(protected)
-      File "/home/lepture/authlib/joserfc/src/joserfc/rfc7515/registry.py", line 65, in check_header
+      File ".../joserfc/rfc7515/registry.py", line 70, in check_header
         check_supported_header(self.header_registry, header)
-      File "/home/lepture/authlib/joserfc/src/joserfc/registry.py", line 175, in check_supported_header
-        raise ValueError(f'Unsupported "{unsupported_keys} in header')
-    ValueError: Unsupported {'custom'} in header
+      File ".../joserfc/registry.py", line 183, in check_supported_header
+        raise UnsupportedHeaderError(f"Unsupported {unsupported_keys} in header")
+    joserfc.errors.UnsupportedHeaderError: unsupported_header: Unsupported {'custom'} in header
 
 To resolve this error, you have two options. First, you can register the
 additional header parameters with the registry. This allows the registry

docs/locales/zh/LC_MESSAGES/api.po

@@ -8,7 +8,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version:  joserfc\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2025-02-28 11:54+0900\n"
+"POT-Creation-Date: 2025-04-20 18:35+0900\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language: zh\n"
@@ -43,25 +43,45 @@ msgstr "该错误是为 JWS/JWT 设计的，当签名不匹配时触发。"
 #: joserfc.errors.InvalidEncryptedKeyError.error:1
 #: joserfc.errors.InvalidEncryptionAlgorithmError.error:1
 #: joserfc.errors.InvalidExchangeKeyError.error:1
+#: joserfc.errors.InvalidHeaderValueError.error:1
+#: joserfc.errors.InvalidKeyIdError.error:1
 #: joserfc.errors.InvalidKeyLengthError.error:1
 #: joserfc.errors.InvalidKeyTypeError.error:1
 #: joserfc.errors.InvalidPayloadError.error:1
 #: joserfc.errors.InvalidTokenError.error:1 joserfc.errors.JoseError.error:1
 #: joserfc.errors.MissingAlgorithmError.error:1
 #: joserfc.errors.MissingClaimError.error:1
+#: joserfc.errors.MissingCritHeaderError.error:1
 #: joserfc.errors.MissingEncryptionError.error:1
+#: joserfc.errors.MissingHeaderError.error:1
+#: joserfc.errors.MissingKeyError.error:1
+#: joserfc.errors.MissingKeyTypeError.error:1
+#: joserfc.errors.UnsupportedAlgorithmError.error:1
+#: joserfc.errors.UnsupportedHeaderError.error:1
 #: joserfc.errors.UnsupportedKeyAlgorithmError.error:1
 #: joserfc.errors.UnsupportedKeyOperationError.error:1
 #: joserfc.errors.UnsupportedKeyUseError.error:1 of
 msgid "short-string error code"
 msgstr "短字符串错误代码"
 
+#: joserfc.errors.DecodeError:1 of
+#, fuzzy
+msgid ""
+"This error is designed for JWS/JWE. It is raised when deserialization and"
+" decryption fails."
+msgstr "该错误是为 JWS/JWT 设计的，当签名不匹配时触发。"
+
 #: joserfc.errors.ExceededSizeError:1 of
 msgid ""
 "This error is designed for DEF zip algorithm. It raised when the "
 "compressed data exceeds the maximum allowed length."
 msgstr "该错误是为 DEF 压缩算法设计的，当压缩数据超过允许的最大长度时触发。"
 
+#: joserfc.errors.ExpiredTokenError:1 of
+#, fuzzy
+msgid "This error is designed for JWT. It raised when the token is expired."
+msgstr "该错误是为 JWS/JWT 设计的，当签名不匹配时触发。"
+
 #: ../../docstring joserfc.errors.ExpiredTokenError.description:1
 #: joserfc.errors.InvalidCEKLengthError.description:1
 #: joserfc.errors.InvalidEncryptedKeyError.description:1
@@ -73,16 +93,64 @@ msgstr "该错误是为 DEF 压缩算法设计的，当压缩数据超过允许
 msgid "long-string to describe this error"
 msgstr "描述此错误的长字符串"
 
+#: joserfc.errors.InsecureClaimError:1 of
+#, fuzzy
+msgid ""
+"This error is designed for JWT. It raised when the claim contains "
+"sensitive information."
+msgstr "该错误是为 JWS/JWT 设计的，当签名不匹配时触发。"
+
+#: joserfc.errors.InvalidClaimError:1 of
+#, fuzzy
+msgid ""
+"This error is designed for JWT. It raised when the claim contains invalid"
+" values or types."
+msgstr "该错误是为 JWS/JWT 设计的，当签名不匹配时触发。"
+
 #: joserfc.errors.InvalidEncryptionAlgorithmError:1 of
 msgid ""
 "This error is designed for JWE. It is raised when \"enc\" value does not "
 "work together with \"alg\" value."
 msgstr "该错误是为 JWE 设计的，当 \"enc\" 值与 \"alg\" 值不兼容时触发。"
 
+#: joserfc.errors.InvalidPayloadError:1 of
+#, fuzzy
+msgid ""
+"This error is designed for JWT. It raised when the payload is not a valid"
+" JSON object."
+msgstr "该错误是为 JWS/JWT 设计的，当签名不匹配时触发。"
+
+#: joserfc.errors.InvalidTokenError:1 of
+#, fuzzy
+msgid "This error is designed for JWT. It raised when the token is not valid yet."
+msgstr "该错误是为 JWS/JWT 设计的，当签名不匹配时触发。"
+
 #: joserfc.errors.JoseError:1 of
 msgid "Base Exception for all errors in joserfc."
 msgstr "joserfc 中所有错误的基类异常。"
 
+#: joserfc.errors.MissingClaimError:1 of
+#, fuzzy
+msgid ""
+"This error is designed for JWT. It raised when the required claims are "
+"missing."
+msgstr "该错误是为 JWS/JWT 设计的，当签名不匹配时触发。"
+
+#: joserfc.errors.MissingCritHeaderError:1 of
+msgid "This error happens when the critical header does not exist."
+msgstr ""
+
+#: joserfc.errors.MissingEncryptionError:1 of
+#, fuzzy
+msgid ""
+"This error is designed for JWE. It is raised when the 'enc' value in "
+"header is missing."
+msgstr "该错误是为 JWE 设计的，当 \"enc\" 值与 \"alg\" 值不兼容时触发。"
+
+#: joserfc.errors.MissingHeaderError:1 of
+msgid "This error happens when the required header does not exist."
+msgstr ""
+
 #: ../../api/index.rst:2
 msgid "API References"
 msgstr "API 参考"
@@ -729,8 +797,8 @@ msgid ""
 "represents digitally signed or MACed content as a JSON object. This "
 "representation is neither optimized for compactness nor URL-safe."
 msgstr ""
-"生成 JWS JSON 序列化（字典形式）。JWS JSON 序列化将数字签名或 MAC 内容表示为 JSON 对象。"
-"此表示既不优化紧凑性，也不 URL 安全。"
+"生成 JWS JSON 序列化（字典形式）。JWS JSON 序列化将数字签名或 MAC 内容表示为 JSON 对象。此表示既不优化紧凑性，也不 "
+"URL 安全。"
 
 #: joserfc.jws.serialize_json:5 of
 msgid "A general JWS JSON Serialization contains:"
@@ -876,6 +944,10 @@ msgid "a ``JWSRegistry`` or ``JWERegistry`` to use"
 msgstr "要使用的 ``JWSRegistry`` 或 ``JWERegistry``"
 
 #: joserfc.jwt.decode:8 of
+msgid "A JSONDecoder subclass to use"
+msgstr ""
+
+#: joserfc.jwt.decode:9 of
 msgid "BadSignatureError"
 msgstr "BadSignatureError"
 
@@ -895,3 +967,7 @@ msgstr "用来编码的字典形式的 JWT claims 部分"
 msgid "key used to sign the signature"
 msgstr "用于签名的密钥"
 
+#: joserfc.jwt.encode:8 of
+msgid "A JSONEncoder subclass to use"
+msgstr ""
+