joserfc

joserfc is a Python library from the Authlib project that implements the full family of JSON Object Signing and Encryption (JOSE) RFCs — JWS (7515), JWE (7516), JWK (7517), JWA (7518), and JWT (7519) — plus companion specs for thumbprints (7638, 9278), unencoded payloads (7797), OKP/EdDSA (8037, 9864), and secp256k1 (8812). It succeeds Authlib’s older jose module, adding strict typing, an explicit registry-based algorithm system, and RFC-test-vector-verified encoding and decoding for JWS, JWE, and JWT.

The library centers on four typed key classes (OctKey, RSAKey, ECKey, OKPKey) and a KeySet abstraction for multi-key scenarios like JWKS rotation, with high-level jwt.encode/decode helpers that wrap lower-level JWS/JWE primitives. Every header and key parameter passes through a registry-based validator, and unsupported algorithms are rejected by default — a deliberate security posture that requires explicit allow-listing before non-default algorithms such as RSA1_5 can be used.

What You Get

• Full JWS/JWE/JWK/JWA/JWT implementations covering RFC7515–7519 plus companion RFCs (7638, 7797, 8037, 8812, 9278, 9864)
• Typed key classes (OctKey, RSAKey, ECKey, OKPKey) with import, generation, and PEM/SSH parsing built in
• A KeySet abstraction for JWKS-style multi-key rotation and kid-based key resolution
• High-level jwt.encode/decode helpers plus lower-level JWS/JWE compact and JSON serialization APIs
• A registry-based algorithm allowlist (JWSRegistry/JWERegistry) that rejects unregistered or insecure algorithms unless explicitly enabled
• Draft RFC implementations (ChaCha20/XChaCha20-Poly1305, ECDH-1PU) available as an opt-in extra

Common Use Cases

• Issuing and verifying JWTs for API authentication and session tokens
• Encrypting sensitive payloads with JWE for secure data exchange between services
• Managing rotating signing keys via JWKS endpoints using the KeySet API
• Implementing OAuth 2.0 / OIDC token handling that requires strict RFC compliance
• Migrating from PyJWT or python-jose when stricter typing and algorithm control are needed

Under The Hood

Architecture The library is organized as a layered, RFC-namespaced module tree: public-facing modules (jws.py, jwe.py, jwk.py, jwt.py, jwa.py, registry.py, errors.py, util.py) sit atop private per-RFC implementation packages (_rfc7515 through _rfc9864, plus _keys.py and drafts/) that each isolate a single specification’s model, compact/JSON serialization, and registry logic. jwt.py is a thin orchestration layer — encode/decode dispatch to jws.serialize_compact/deserialize_compact or jwe.encrypt_compact/decrypt_compact based on whether a JWERegistry was passed, with claims converted and validated via _rfc7519.claims and _rfc7519.security before being wrapped in a Token object. Key resolution flows through jwk.guess_key, which accepts a raw key, a KeySet, or a callable, and defers per-algorithm lookups to the typed key classes in _rfc7517/_rfc7518/_rfc8037. The core abstraction that would be costly to change is the HeaderParameter/registry validation system in registry.py, since every module builds its allowed-header set by merging JWS_HEADER_REGISTRY into JWE_HEADER_REGISTRY.

Tech Stack joserfc targets Python 3.10+ and depends on a single runtime dependency, cryptography, for all elliptic-curve, RSA, and symmetric primitives; draft algorithms (ChaCha20, ECDH-1PU) pull in pycryptodome as an optional extra. The build system is setuptools with a src/ layout and dynamic versioning read from joserfc.version. Development tooling is Ruff for linting/formatting and mypy in strict mode for type checking, orchestrated through tox environments and pre-commit. Documentation is built with Sphinx using the Shibuya theme and myst-parser, with sponsored releases published to both PyPI and conda-forge, and SonarCloud tracking maintainability and security ratings.

Code Quality The project has an extensive test suite organized by RFC domain (jws/, jwe/, jwk/, jwt/) run with pytest and branch coverage tracked via coverage.py; several tests assert directly against official RFC example vectors byte-for-byte, a strong correctness signal rather than incidental testing. mypy runs in strict mode across the entire source tree with error codes enabled, and the package ships a py.typed marker so downstream consumers get full type inference. Error handling is explicit and hierarchical — every exception subclasses a common JoseError with a short machine-readable error code and human description, rather than swallowing or generically re-raising. CI runs a dedicated lint job (ruff + mypy) as a required gate before the test matrix, and deprecation warnings are configured to fail tests outright.

What Makes It Unique joserfc’s main differentiator versus other Python JWT libraries is its registry-based algorithm allowlisting — unregistered or historically-insecure algorithms are rejected by default and must be explicitly opted into via a custom registry, closing a common class of “algorithm confusion” vulnerabilities that other JWT libraries have shipped by default. It also implements the full JWE spec, including JSON serialization with multiple recipients, which lighter-weight JWT libraries typically skip, and separates low-level JWS/JWE primitives from the high-level encode/decode convenience layer so advanced users can drop to compact or JSON serialization directly. These are solid, security-conscious engineering choices rather than a novel algorithmic contribution — the underlying cryptography is delegated entirely to the cryptography library.