Merge commit from fork

jpadilla · web-flow · commit 051ea341b557 · 2026-03-12T12:46:08.000-04:00
Co-authored-by: José Padilla &lt;jpadilla@users.noreply.github.com&gt;
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -7,12 +7,16 @@ This project adheres to `Semantic Versioning <https://semver.org/>`__.
 `Unreleased <https://github.com/jpadilla/pyjwt/compare/2.11.0...HEAD>`__
 ------------------------------------------------------------------------
 
+`v2.12.0 <https://github.com/jpadilla/pyjwt/compare/2.11.0...2.12.0>`__
+-----------------------------------------------------------------------
+
 Fixed
 ~~~~~
 
 - Annotate PyJWKSet.keys for pyright by @tamird in `#1134 <https://github.com/jpadilla/pyjwt/pull/1134>`__
 - Close ``HTTPError`` response to prevent ``ResourceWarning`` on Python 3.14 by @veeceey in `#1133 <https://github.com/jpadilla/pyjwt/pull/1133>`__
 - Do not keep ``algorithms`` dict in PyJWK instances by @akx in `#1143 <https://github.com/jpadilla/pyjwt/pull/1143>`__
+- Validate the crit (Critical) Header Parameter defined in RFC 7515 §4.1.11. by @dmbs335 in `GHSA-752w-5fwx-jx9f <https://github.com/jpadilla/pyjwt/security/advisories/GHSA-752w-5fwx-jx9f>`__
 
 Added
 ~~~~~
diff --git a/jwt/__init__.py b/jwt/__init__.py
@@ -28,7 +28,7 @@
 from .jwks_client import PyJWKClient
 from .warnings import InsecureKeyLengthWarning
 
-__version__ = "2.11.0"
+__version__ = "2.12.0"
 
 __title__ = "PyJWT"
 __description__ = "JSON Web Token implementation in Python"
diff --git a/jwt/api_jws.py b/jwt/api_jws.py
@@ -150,7 +150,7 @@ def encode(
         header: dict[str, Any] = {"typ": self.header_typ, "alg": algorithm_}
 
         if headers:
-            self._validate_headers(headers)
+            self._validate_headers(headers, encoding=True)
             header.update(headers)
 
         if not header["typ"]:
@@ -232,6 +232,8 @@ def decode_complete(
 
         payload, signing_input, header, signature = self._load(jwt)
 
+        self._validate_headers(header)
+
         if header.get("b64", True) is False:
             if detached_payload is None:
                 raise DecodeError(
@@ -358,14 +360,35 @@ def _verify_signature(
         if not alg_obj.verify(signing_input, prepared_key, signature):
             raise InvalidSignatureError("Signature verification failed")
 
-    def _validate_headers(self, headers: dict[str, Any]) -> None:
+    # Extensions that PyJWT actually understands and supports
+    _supported_crit: set[str] = {"b64"}
+
+    def _validate_headers(
+        self, headers: dict[str, Any], *, encoding: bool = False
+    ) -> None:
         if "kid" in headers:
             self._validate_kid(headers["kid"])
+        if not encoding and "crit" in headers:
+            self._validate_crit(headers)
 
     def _validate_kid(self, kid: Any) -> None:
         if not isinstance(kid, str):
             raise InvalidTokenError("Key ID header parameter must be a string")
 
+    def _validate_crit(self, headers: dict[str, Any]) -> None:
+        crit = headers["crit"]
+        if not isinstance(crit, list) or len(crit) == 0:
+            raise InvalidTokenError("Invalid 'crit' header: must be a non-empty list")
+        for ext in crit:
+            if not isinstance(ext, str):
+                raise InvalidTokenError("Invalid 'crit' header: values must be strings")
+            if ext not in self._supported_crit:
+                raise InvalidTokenError(f"Unsupported critical extension: {ext}")
+            if ext not in headers:
+                raise InvalidTokenError(
+                    f"Critical extension '{ext}' is missing from headers"
+                )
+
 
 _jws_global_obj = PyJWS()
 encode = _jws_global_obj.encode
diff --git a/tests/test_api_jws.py b/tests/test_api_jws.py
@@ -995,3 +995,103 @@ def test_decode_complete_warns_on_unuspported_kwarg(
         ]
         assert len(deprecation_warnings) == 1
         assert "foo" in str(deprecation_warnings[0].message)
+
+    def test_decode_rejects_unknown_crit_extension(
+        self, jws: PyJWS, payload: bytes
+    ) -> None:
+        secret = "secret"
+        token = jws.encode(
+            payload,
+            secret,
+            algorithm="HS256",
+            headers={"crit": ["x-custom-policy"], "x-custom-policy": "require-mfa"},
+        )
+
+        with pytest.raises(InvalidTokenError, match="Unsupported critical extension"):
+            jws.decode(token, secret, algorithms=["HS256"])
+
+    def test_decode_rejects_empty_crit(self, jws: PyJWS, payload: bytes) -> None:
+        secret = "secret"
+        token = jws.encode(
+            payload,
+            secret,
+            algorithm="HS256",
+            headers={"crit": []},
+        )
+
+        with pytest.raises(InvalidTokenError, match="must be a non-empty list"):
+            jws.decode(token, secret, algorithms=["HS256"])
+
+    def test_decode_rejects_non_list_crit(self, jws: PyJWS, payload: bytes) -> None:
+        secret = "secret"
+        token = jws.encode(
+            payload,
+            secret,
+            algorithm="HS256",
+            headers={"crit": "b64"},
+        )
+
+        with pytest.raises(InvalidTokenError, match="must be a non-empty list"):
+            jws.decode(token, secret, algorithms=["HS256"])
+
+    def test_decode_rejects_crit_with_non_string_values(
+        self, jws: PyJWS, payload: bytes
+    ) -> None:
+        secret = "secret"
+        token = jws.encode(
+            payload,
+            secret,
+            algorithm="HS256",
+            headers={"crit": [123]},
+        )
+
+        with pytest.raises(InvalidTokenError, match="values must be strings"):
+            jws.decode(token, secret, algorithms=["HS256"])
+
+    def test_decode_rejects_crit_extension_missing_from_header(
+        self, jws: PyJWS, payload: bytes
+    ) -> None:
+        secret = "secret"
+        token = jws.encode(
+            payload,
+            secret,
+            algorithm="HS256",
+            headers={"crit": ["b64"]},
+        )
+
+        with pytest.raises(InvalidTokenError, match="missing from headers"):
+            jws.decode(token, secret, algorithms=["HS256"])
+
+    def test_decode_accepts_supported_crit_extension(
+        self, jws: PyJWS, payload: bytes
+    ) -> None:
+        secret = "secret"
+        token = jws.encode(
+            payload,
+            secret,
+            algorithm="HS256",
+            headers={"crit": ["b64"], "b64": False},
+            is_payload_detached=True,
+        )
+
+        decoded = jws.decode(
+            token,
+            secret,
+            algorithms=["HS256"],
+            detached_payload=payload,
+        )
+        assert decoded == payload
+
+    def test_get_unverified_header_rejects_unknown_crit(
+        self, jws: PyJWS, payload: bytes
+    ) -> None:
+        secret = "secret"
+        token = jws.encode(
+            payload,
+            secret,
+            algorithm="HS256",
+            headers={"crit": ["x-unknown"], "x-unknown": "value"},
+        )
+
+        with pytest.raises(InvalidTokenError, match="Unsupported critical extension"):
+            jws.get_unverified_header(token)
diff --git a/tests/test_api_jwt.py b/tests/test_api_jwt.py
@@ -1065,3 +1065,21 @@ def test_validate_iss_with_non_str_issuer(self, jwt: PyJWT) -> None:
                 payload,
                 issuer=123,  # type: ignore[arg-type]
             )
+
+    # -------------------- Crit Header Tests --------------------
+
+    def test_decode_rejects_token_with_unknown_crit_extension(self, jwt: PyJWT) -> None:
+        """RFC 7515 §4.1.11: tokens with unsupported critical extensions MUST be rejected."""
+        from jwt.exceptions import InvalidTokenError
+
+        secret = "secret"
+        payload = {"sub": "attacker", "role": "admin"}
+        token = jwt.encode(
+            payload,
+            secret,
+            algorithm="HS256",
+            headers={"crit": ["x-custom-policy"], "x-custom-policy": "require-mfa"},
+        )
+
+        with pytest.raises(InvalidTokenError, match="Unsupported critical extension"):
+            jwt.decode(token, secret, algorithms=["HS256"])
