Typing stubs for jwcrypto (types-jwcrypto)

1.5.7.20260409 · active · verified Fri Apr 10

types-jwcrypto provides static type annotations for the jwcrypto library, enabling type checkers like Mypy and Pyright to validate code that uses jwcrypto. jwcrypto is a Python implementation of the JOSE (Javascript Object Signing and Encryption) Web Standards, including JWK, JWS, JWE, and JWT, and leverages the Cryptography package for its cryptographic operations. This stub package is part of the typeshed project and is released automatically, often daily. The current version is 1.5.7.20260409, targeting jwcrypto==1.5.*.

Warnings

breaking jwcrypto versions 1.4.x introduced breaking changes to JWT validation (CVE-2022-3102 fix). The `JWT` constructor and `validate` method now include an `expect_type` argument, defaulting to 'JWS' or 'JWE' based on context. If the token type doesn't match the expected type, an `InvalidJWSToken` or `InvalidJWEToken` exception is raised. An optional `born-deprecated` module-level variable can temporarily restore old behavior, but its use is strongly discouraged due to security implications.
Fix: Explicitly set the `expect_type` argument (e.g., `jwt.JWT(jwt=token_str, key=public_key, expect_type='JWS')`) or ensure your application handles the new validation exceptions. Refactor code to avoid relying on implicit type detection.
deprecated The `RSA1_5` algorithm is considered deprecated in jwcrypto due to known security vulnerabilities (Bleichenbacher RSA padding oracle attack). Using it can lead to severe issues like decryption of intercepted messages or forged signatures.
Fix: Avoid using `RSA1_5` for encryption or signing. Migrate to more secure algorithms like `RSA-OAEP` for encryption or `RSASSA-PSS` for signing, which are generally recommended by the JOSE standards.
breaking jwcrypto versions prior to 1.5.6 were vulnerable to a Denial of Service (DoS) attack (CVE-2024-28102) where a malicious JWE token with a high compression ratio could consume excessive memory and processing time. This could impact application availability.
Fix: Upgrade the underlying `jwcrypto` library to version 1.5.6 or higher. The `types-jwcrypto` package targets `jwcrypto==1.5.*`, so ensuring `jwcrypto` is updated within that minor version range is crucial.
gotcha Typeshed stub package versions (like types-jwcrypto) typically encode the upstream library's major and minor version, followed by a calendar version (e.g., `1.5.0.20260402` for `jwcrypto==1.5.*`). This means that `types-jwcrypto` may not precisely track patch versions of `jwcrypto` that introduce API changes or bug fixes relevant to typing. Discrepancies between the exact runtime version and stub version can lead to type-checking errors.
Fix: It is best practice to keep the version of `types-jwcrypto` synchronized with the minor version of your `jwcrypto` dependency. Pin your `types-jwcrypto` dependency to match the `jwcrypto` minor version (e.g., `types-jwcrypto~=1.5.0` if `jwcrypto~=1.5.0`) and regularly update both, verifying with your type checker.

Install

pip install types-jwcrypto jwcrypto Install stubs and runtime library

Imports

JWK
```
from jwcrypto.jwk import JWK
```
JWS
```
from jwcrypto.jws import JWS
```
JWE
```
from jwcrypto.jwe import JWE
```
JWT
```
from jwcrypto.jwt import JWT
```

Quickstart

This quickstart demonstrates how to generate a symmetric key, create claims, sign a JSON Web Token (JWT) using that key, serialize it into its compact form, and then deserialize and validate it. For asymmetric keys (RSA, EC), the key generation and signing steps would differ slightly, requiring separate public/private key components.

from jwcrypto import jwk, jwt
import json

# 1. Generate a symmetric key
key = jwk.JWK.generate(kty='oct', size=256)

# 2. Define claims (payload)
claims = {
    'iss': 'my-app',
    'aud': 'your-service',
    'sub': 'user123',
    'exp': 1678886400  # Example expiration time (Unix timestamp)
}

# 3. Create a JWT object with header and claims
token = jwt.JWT(header={'alg': 'HS256'}, claims=claims)

# 4. Sign the token
token.make_signed_token(key)

# 5. Serialize the token to a compact string
compact_token = token.serialize()
print(f"Generated JWT: {compact_token}")

# 6. Deserialize and validate the token
# In a real application, you would receive 'compact_token' from a client
# and validate it with a trusted key.

decoded_token = jwt.JWT(jwt=compact_token, key=key)
# No explicit validate() call needed if key is provided during instantiation
# However, it's good practice to call it if you deserialize without a key first.
# decoded_token.validate(key) # This can be used if `jwt` was created without `key`

print(f"Decoded claims: {json.dumps(json.loads(decoded_token.claims), indent=2)}")

view raw JSON →