Merge pull request #56 from QueryaHub/dev

Release 0.4.0

Author: ZhuchkaTriplesix

.github/RELEASE_NOTES_v0.4.0.md

@@ -0,0 +1,44 @@
+# OxyJWT 0.4.0
+
+**Beta** production-hardening release — security, performance, PyJWT/JWKS parity, and typing. No intentional breaking changes to the public `__all__` API beyond stricter defaults and new warnings.
+
+## Highlights
+
+### Security
+
+- JWKS: `max_bytes`, optional `require_https`, `algorithms` checked before HTTP, refresh-on-miss `kid`, `lifespan` TTL
+- Reject JWKs with `use: enc`; `PyJWKSetSkipWarning` for skipped keys
+- `InsecureDecodeWarning` for unverified decode paths
+- `strict_aud`, `verify_sub`, issuer list validation, fractional `leeway` alignment
+- Max compact JWT size (256 KiB) before parse; HMAC secret buffers zeroized after use
+
+### Features & parity
+
+- `PyJWKClient`: `headers`, `ssl_context`, `cache_keys` (default off), `lifespan`
+- RFC 7797 detached payload decode (`detached_payload` + `b64: false`)
+- Custom string JWT header parameters on `encode`
+- Public `.pyi` stubs + `py.typed`; mypy CI job
+
+### Performance
+
+- Single-parse verified `decode_complete`; fewer orjson round-trips on encode/decode
+- O(1) JWKS `kid` index; lazy `PyJWK.key`; GIL release on unverified parse
+
+### Testing & docs
+
+- `tests/test_security_regression.py`; RSA/EC JWK parity tests
+- Stricter benchmark CI gates (≥75% vs PyJWT); expanded API/security docs
+
+## Install
+
+```bash
+pip install oxyjwt==0.4.0
+```
+
+## Upgrade from 0.3.0
+
+```bash
+pip install -U oxyjwt
+```
+
+Review new warnings and stricter JWKS/JWT limits. See the full [changelog](https://github.com/QueryaHub/OxyJWT/blob/main/docs-site/docs/changelog.md#040--2026-05-22).

.github/workflows/benchmarks.yml

@@ -1,3 +1,4 @@
+# Full throughput comparison (not a hard regression gate). HS256 ratio gates run in main CI via pytest smoke.
 name: Benchmarks
 
 on:
@@ -33,7 +34,10 @@ jobs:
       - name: Build and install OxyJWT
         run: .venv/bin/maturin develop --release
 
-      - name: Run comparison script
+      - name: HS256 smoke regression (same gate as main CI)
+        run: .venv/bin/python -m pytest tests/test_benchmark_jwt_libraries.py::test_benchmark_hs256_smoke_vs_competitors -q
+
+      - name: Run full comparison script
         run: |
           mkdir -p benchmark-results
           .venv/bin/python scripts/compare_jwt_libraries.py \

.github/workflows/ci.yml

@@ -53,3 +53,22 @@ jobs:
 
       - name: Documentation build
         run: .venv/bin/mkdocs build --strict -f docs-site/mkdocs.yml
+
+  typing:
+    name: Type check (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Create virtualenv
+        run: python -m venv .venv
+
+      - name: Install typing dependencies
+        run: .venv/bin/python -m pip install -U pip mypy orjson
+
+      - name: Mypy (public stubs + smoke)
+        run: .venv/bin/python -m mypy python/oxyjwt tests/typing/test_public_api.py

.github/workflows/release.yml

@@ -1,6 +1,6 @@
 # PyPI: configure Trusted Publishing in https://pypi.org
 # and add a GitHub Environment named "pypi" in this repository.
-# Release: push an annotated or lightweight tag "v*". Example: git tag -a v0.3.0 -m "Release 0.3.0" && git push origin v0.3.0
+# Release: push an annotated or lightweight tag "v*". Example: git tag -a v0.4.0 -m "Release 0.4.0" && git push origin v0.4.0
 name: Release
 
 on:

CONTRIBUTING.md

@@ -23,6 +23,14 @@ The Python package lives under `python/`. Pytest is configured to prefer that tr
 - `pytest` (with optional `pytest --cov=oxyjwt`)
 - `mkdocs build --strict -f docs-site/mkdocs.yml` if you change documentation
 
+## Branching (0.4.0)
+
+Integration branch is **`dev`**. Feature work uses one branch per issue from `dev`, PRs target `dev`.
+
+Always sync before branching: `git fetch --all --prune` then `git pull --ff-only origin dev`. Run the full Rust + pytest suite before opening a PR.
+
+Use `gh` to set **labels** (`p0`/`p1`/`p2`, `security`, …) and milestone **0.4.0** on issues and PRs. See [docs/GITFLOW.md](docs/GITFLOW.md) and [milestone 0.4.0](https://github.com/QueryaHub/OxyJWT/milestone/1).
+
 ## Pull requests
 
 - Keep changes focused and match existing style (formatting, typing, minimal comments).

README.md

@@ -2,7 +2,7 @@
 
 OxyJWT is a Python JWT/JWS library backed by a Rust core. The public API follows **PyJWT** for `encode`, `decode`, `decode_complete`, JWK/JWKS helpers, and the `PyJWKClient`. When **signature verification** is enabled (the default), you must pass an `algorithms` allow-list, matching common PyJWT usage. Unverified decode is available only when you explicitly set `options["verify_signature"]` to `False` (treat the payload as untrusted).
 
-This project is **beta** software on the `0.3.x` line; see the [changelog](docs-site/docs/changelog.md) for **0.2.0** breaking changes (exception hierarchy) and **0.3.0** notes.
+This project is **beta** software on the `0.4.x` line; see the [changelog](docs-site/docs/changelog.md) for **0.2.0** breaking changes (exception hierarchy) and **0.4.0** production-hardening notes.
 
 ## Documentation
 

RELEASING.md

@@ -1,6 +1,6 @@
 # Releasing OxyJWT
 
-This checklist is for maintainers publishing **0.3.x** (and later) to PyPI via the GitHub Actions [Release workflow](.github/workflows/release.yml).
+This checklist is for maintainers publishing **0.4.x** (and later) to PyPI via the GitHub Actions [Release workflow](.github/workflows/release.yml).
 
 ## Before tagging
 
@@ -35,16 +35,16 @@ This checklist is for maintainers publishing **0.3.x** (and later) to PyPI via t
 ## Publish
 
 1. Commit all release-prep changes on `main`.
-2. Create and push an annotated tag (example for **0.3.0**):
+2. Merge `dev` → `main`, then create and push an annotated tag (example for **0.4.0**):
 
    ```bash
-   git tag -a v0.3.0 -m "Release 0.3.0"
-   git push origin v0.3.0
+   git tag -a v0.4.0 -m "Release 0.4.0"
+   git push origin v0.4.0
    ```
 
 3. The **Release** workflow builds wheels (Linux x86_64/aarch64, macOS, Windows) + sdist and publishes to PyPI (requires the `pypi` environment and [Trusted Publishing](https://docs.pypi.org/trusted-publishers/)).
 
-4. On GitHub, create a **Release** from the tag. Use the **0.3.0** section in `docs-site/docs/changelog.md` as the release notes body.
+4. On GitHub, create a **Release** from the tag. Use [`.github/RELEASE_NOTES_v0.4.0.md`](.github/RELEASE_NOTES_v0.4.0.md) or the **0.4.0** section in `docs-site/docs/changelog.md` as the release notes body.
 
 ## After release
 

SECURITY.md

@@ -4,11 +4,11 @@
 
 | Version line | Support |
 | --- | --- |
-| **0.3.x** (current) | Security fixes and patch releases |
-| **0.2.x** | Best-effort backports only for critical issues |
-| **0.1.x** and older | Unsupported |
+| **0.4.x** (current) | Security fixes and patch releases |
+| **0.3.x** | Best-effort backports only for critical issues |
+| **0.2.x** and older | Unsupported |
 
-Security fixes target the latest **0.3.x** release. See the [changelog](docs-site/docs/changelog.md) for release history.
+Security fixes target the latest **0.4.x** release. See the [changelog](docs-site/docs/changelog.md) for release history.
 
 ## Reporting a vulnerability
 
@@ -31,3 +31,14 @@ This policy covers the `oxyjwt` Python package and its Rust extension (`_oxyjwt`
 ## JWT usage
 
 OxyJWT implements JWT/JWS signing and verification. Correct use still depends on application choices (algorithm allow-lists, audience/issuer checks, secret management). Read the [Security](docs-site/docs/security.md) documentation before deploying to production.
+
+### JWKS (`PyJWKClient`)
+
+When loading keys from a JWKS URL: use HTTPS (`require_https=True` in production), cap response size (`max_bytes`), pass an explicit `algorithms` list to `get_signing_key_from_jwt` (checked before HTTP), and always verify tokens with `decode` after resolving the key. See [Security — JWKS](docs-site/docs/security.md#jwks-pyjwkclient) and the [API reference](docs-site/docs/api-reference.md#pyjwkclient).
+
+### `verify_signature=False`
+
+Decoding with `options["verify_signature"] = False` skips cryptographic verification. OxyJWT emits `InsecureDecodeWarning` in that case. Do not use unverified payloads for authorization.
+
+- The `subject` parameter is ignored unless `verify_sub` is explicitly `True` (it defaults to `False` when the signature is not verified).
+- `require` only checks claim **presence**, not that the token was signed by your trust anchor.

docs-site/docs/api-reference.md

@@ -20,7 +20,7 @@ Parameters:
 - `payload`: JSON-compatible mapping to place in the token claims.
 - `key`: raw HMAC secret or an `EncodingKey`.
 - `algorithm`: signing algorithm. Defaults to `HS256`.
-- `headers`: optional JWT header values such as `kid` and `typ`.
+- `headers`: optional JWT header values such as `kid`, `typ`, and custom string parameters (for example `X-Request-Id`). See [Encoding — Headers](usage/encoding.md#headers).
 
 Raises:
 
@@ -40,7 +40,7 @@ def decode(
     detached_payload: bytes | None = None,
     audience: str | Iterable[str] | None = None,
     subject: str | None = None,
-    issuer: str | None = None,
+    issuer: str | Iterable[str] | None = None,
     leeway: float | timedelta = 0,
 ) -> dict[str, Any]: ...
 ```
@@ -56,15 +56,15 @@ Parameters:
 - `algorithms`: required server-side allow-list when signature verification is on.
 - `audience`: expected `aud` value or values.
 - `subject`: expected `sub` value (passed to the native decoder when signature verification is on).
-- `issuer`: expected `iss` value.
+- `issuer`: expected `iss` value, or an iterable of allowed issuers (token `iss` must match one).
 - `leeway`: clock tolerance in seconds or as a `timedelta`.
 - `options`: validation switches (see below). Values from a `PyJWT(..., options=...)` instance are merged with per-call `options`.
-- `detached_payload`: not supported; raises `NotImplementedError` if set.
+- `detached_payload`: required when the protected header sets `b64` to `false` (RFC 7797 detached content). Pass the raw payload bytes used when the JWS was signed.
 
 Supported `options` keys (booleans unless noted):
 
 - `verify_signature` — verify the JWS signature (default `True`).
-- `verify_exp`, `verify_nbf`, `verify_iat`, `verify_aud`, `verify_iss`
+- `verify_exp`, `verify_nbf`, `verify_iat`, `verify_aud`, `verify_iss`, `verify_sub`, `strict_aud`
 - `require_exp` — require an `exp` claim in the token
 - `require` — list of claim names that must be present (may also be passed on the `PyJWT` instance)
 
@@ -145,6 +145,134 @@ class DecodingKey:
 
 Use `DecodingKey` for verifying tokens.
 
+## `PyJWKClient`
+
+HTTP client for fetching a [JWKS](https://datatracker.ietf.org/doc/html/rfc7517) document and resolving signing keys by `kid`. Uses the Python standard library (`urllib`) only — no extra HTTP dependencies.
+
+Typical flow with an identity provider that publishes rotating RSA/EC keys:
+
+```python
+import oxyjwt
+
+client = oxyjwt.PyJWKClient(
+    "https://auth.example.com/.well-known/jwks.json",
+    require_https=True,
+    headers={"Authorization": "Bearer <service-token>"},
+)
+
+token = "<compact-jwt-from-client>"
+signing_key = client.get_signing_key_from_jwt(
+    token,
+    algorithms=["RS256"],  # server-side allow-list; checked before HTTP
+)
+claims = oxyjwt.decode(
+    token,
+    signing_key.key,
+    algorithms=["RS256"],
+    audience="api",
+    issuer="https://auth.example.com",
+)
+```
+
+See also the [FastAPI cookbook](cookbooks/fastapi-jwt.md) and [Security — JWKS](security.md#jwks-pyjwkclient).
+
+### Two-tier caching
+
+| Tier | Option | Default | Behavior |
+|------|--------|---------|----------|
+| **1 — JWK Set** | `cache_jwk_set`, `lifespan` | on, 300s | Caches the parsed JWKS JSON. Refetch when TTL expires or `get_jwk_set(refresh=True)`. |
+| **2 — signing keys** | `cache_keys`, `max_cached_keys` | off, 16 | LRU of `PyJWK` objects by `kid` (no time expiry). Opt-in; matches PyJWT default. |
+
+On `get_signing_key`, if `kid` is missing from the current set, the client refetches JWKS **once** and retries (key rotation). A second miss raises `KeyError` (no further HTTP retries in that call).
+
+### Constructor
+
+```python
+class PyJWKClient:
+    def __init__(
+        self,
+        uri: str,
+        *,
+        cache_jwk_set: bool = True,
+        cache_keys: bool = False,
+        max_cached_keys: int = 16,
+        timeout: float = 30.0,
+        max_bytes: int = 262_144,
+        require_https: bool = False,
+        headers: Mapping[str, Any] | None = None,
+        ssl_context: ssl.SSLContext | None = None,
+        lifespan: float = 300.0,
+    ) -> None: ...
+```
+
+| Parameter | Description |
+|-----------|-------------|
+| `uri` | JWKS endpoint URL (`http://` or `https://`). |
+| `cache_jwk_set` | Cache the fetched JWKS document (tier 1). |
+| `lifespan` | Seconds before tier-1 cache expires; must be &gt; 0 when `cache_jwk_set=True`. |
+| `cache_keys` | Enable per-`kid` signing-key LRU (tier 2). Default `False` (PyJWT parity). |
+| `max_cached_keys` | Max LRU entries when `cache_keys=True`. |
+| `timeout` | HTTP GET timeout in seconds. |
+| `max_bytes` | Max JWKS response size (default 256 KiB). Larger bodies raise `PyJWKClientError`. |
+| `require_https` | When `True`, reject non-HTTPS `uri` values. |
+| `headers` | Extra request headers merged with `User-Agent` and `Accept: application/json`. |
+| `ssl_context` | `ssl.SSLContext` for HTTPS (default `ssl.create_default_context()`). |
+
+Raises `ValueError` for invalid `uri` / `max_bytes`; `TypeError` for invalid `ssl_context`; `PyJWKClientError` when `require_https` blocks the URI or `lifespan` is invalid.
+
+### `get_jwk_set`
+
+```python
+def get_jwk_set(self, refresh: bool = False) -> PyJWKSet: ...
+```
+
+Returns a `PyJWKSet` parsed from the endpoint. When `refresh=False` and tier-1 cache is valid, returns the cached set without HTTP. When `refresh=True`, always fetches a new document and updates the cache (clears tier-2 LRU entries).
+
+Raises `PyJWKClientConnectionError` on network/timeout failures; `PyJWKClientError` on oversized body or invalid JSON shape.
+
+### `get_signing_key`
+
+```python
+def get_signing_key(self, kid: str) -> PyJWK: ...
+```
+
+Returns the `PyJWK` for `kid`. Uses tier-1 cache, then tier-2 LRU if enabled. Refetches JWKS once on `KeyError` (rotation). Empty `kid` raises `PyJWKClientError`.
+
+### `get_signing_key_from_jwt`
+
+```python
+def get_signing_key_from_jwt(
+    self,
+    jwt: str | bytes,
+    algorithms: list[str] | None = None,
+) -> PyJWK: ...
+```
+
+Reads `kid` (and optionally `alg`) from the token header via `get_unverified_header`, then calls `get_signing_key`.
+
+When `algorithms` is provided:
+
+- empty list → `InvalidAlgorithmError`;
+- header `alg` not in the list → `InvalidAlgorithmError` **before** any JWKS HTTP request;
+- `none` → `InvalidAlgorithmError`.
+
+Missing or empty `kid` → `PyJWKClientError`.
+
+### Security notes
+
+- Pass your server-side **`algorithms`** allow-list to `get_signing_key_from_jwt` and again to `decode` — do not trust the header `alg` alone. See [Security](security.md).
+- Prefer **`require_https=True`** in production.
+- Use **`max_bytes`** to limit denial-of-service from huge JWKS responses.
+- `get_unverified_header` inside `get_signing_key_from_jwt` does not verify the signature; only use the returned `PyJWK.key` with verified `decode`. Details: [SECURITY.md](https://github.com/QueryaHub/OxyJWT/blob/main/SECURITY.md) and [Security — unverified helpers](security.md#treat-unverified-helpers-as-inspection-only).
+- Encryption keys (`use: enc`) in the JWKS are rejected when building `PyJWK`; skipped entries emit `PyJWKSetSkipWarning`.
+
+### Related exceptions
+
+- `PyJWKClientError` — invalid client configuration, JWKS shape, size limits, missing `kid`.
+- `PyJWKClientConnectionError` — HTTP/URL errors (subclass of `PyJWKClientError`).
+- `KeyError` — `kid` not found after one refresh attempt.
+- `InvalidAlgorithmError` — disallowed `alg` when `algorithms` is passed to `get_signing_key_from_jwt`.
+
 ## Exceptions
 
 All OxyJWT exceptions inherit from `OxyJWTError`. The layout matches PyJWT: `InvalidTokenError` is the common base for most decode-time errors; `DecodeError` and `InvalidSignatureError` nest under it.

docs-site/docs/benchmarks.md

@@ -2,6 +2,25 @@
 
 OxyJWT is optimized for throughput on typical JWT workloads. Numbers depend on CPU, compiler flags, Python version, and the cryptographic backend (see the root [README](https://github.com/QueryaHub/OxyJWT/blob/main/README.md) for the default `aws_lc_rs` backend and the `rust_crypto` alternative on some Linux aarch64 wheels).
 
+## Three levels of benchmarking
+
+| Level | How to run | Purpose |
+|-------|------------|---------|
+| **Smoke** | Default `pytest` (`tests/test_benchmark_jwt_libraries.py::test_benchmark_hs256_smoke_vs_competitors`) | Fast HS256 regression gate in every CI run; OxyJWT must stay ≥75% of PyJWT encode/decode throughput (was 25% / 4× slack). |
+| **Extended** | `OXYJWT_BENCHMARK=1 pytest -m benchmark` | HS256, RS256, EdDSA with moderate iterations; optional locally or before release. |
+| **Full** | Weekly [Benchmarks workflow](https://github.com/QueryaHub/OxyJWT/blob/main/.github/workflows/benchmarks.yml) or the script below | Higher iteration counts; Markdown artifact for trend spotting, not a hard gate. |
+
+## Reference ratios (HS256 smoke parameters)
+
+Measured on a typical Linux dev machine with `maturin develop --release`, 50 iterations, 1 round, warmup 8 (same as CI smoke):
+
+| Operation | OxyJWT (ops/s) | PyJWT (ops/s) | OxyJWT / PyJWT |
+|-----------|----------------|---------------|----------------|
+| encode | ~400k+ | ~130k+ | ~3× |
+| decode | ~160k+ | ~115k+ | ~1.4× |
+
+CI asserts **≥75%** of PyJWT for both operations so large regressions fail without requiring absolute ops/s parity across runners.
+
 ## Running comparisons locally
 
 The repository includes [`scripts/compare_jwt_libraries.py`](https://github.com/QueryaHub/OxyJWT/blob/main/scripts/compare_jwt_libraries.py), which benchmarks OxyJWT against PyJWT, Authlib, and python-jose where supported.
@@ -22,7 +41,9 @@ Raw JSON/Markdown outputs are gitignored; keep them local or attach them to rele
 
 ## CI artifacts
 
-The [Benchmarks workflow](https://github.com/QueryaHub/OxyJWT/blob/main/.github/workflows/benchmarks.yml) runs on a weekly schedule and on manual dispatch. It uploads a Markdown summary as a workflow artifact (smaller iteration counts than a full local run). Use it to spot large regressions over time, not as absolute performance guarantees.
+The [Benchmarks workflow](https://github.com/QueryaHub/OxyJWT/blob/main/.github/workflows/benchmarks.yml) runs on a weekly schedule and on `workflow_dispatch`. It uploads `benchmark-results/ci-bench.md` (HS256, RS256, EdDSA; 200 iterations × 2 rounds). Use it to spot large regressions over time, not as absolute performance guarantees.
+
+Main [CI](https://github.com/QueryaHub/OxyJWT/blob/main/.github/workflows/ci.yml) enforces the HS256 smoke ratios on every push/PR.
 
 ## Methodology