feat(filter): add jwt_auth filter with JWKS validation

[yossiovadia]

What

Adds a jwt_auth filter that validates JWT bearer tokens against a JWKS endpoint and injects verified claims as request headers.

• Fetches and caches JWKS from a configured URL, keyed by kid
• Validates signature, expiry, and issuer
• Maps configured claims to request headers and filter metadata
• Strips the bearer token before forwarding upstream
• Supports RS256/384/512 and ES256 (via jsonwebtoken with rust_crypto)

Why / relationship to #708

This is the temporary bridge discussed in #708. As noted there, JWT validation is not the long-term target architecture — the core CPEX engine is the intended home. But this filter is fully self-contained and unblocks JWT/OIDC-fronted deployments today. Per the discussion, no other filter should take a dependency on it, so it can be cleanly retired once CPEX covers this path.

Closes #708

Tests

• 11 unit tests: valid token passes and writes metadata, bearer-prefix extraction, token stripped from upstream request, expired / wrong-issuer / unknown-kid / garbage / missing tokens rejected, config validation (empty JWKS URL, empty claim headers, unknown fields)
• 4 integration tests (tests/integration/.../examples/jwt_auth.rs): config parses, valid token allowed + stripped, missing/garbage tokens rejected
• Example config (examples/configs/jwt-auth.yaml), filter docs (docs/filters/jwt_auth.md), reference table entry

cargo test, cargo clippy, and cargo +nightly fmt --check all pass locally.

Notes for reviewers

• Test key material: filters/src/jwt_auth/test_fixtures/rsa_private.pem is a throwaway RSA keypair generated solely to sign tokens in unit tests (include_str!, clearly labeled test-only). It signs nothing real and protects nothing — happy to switch to in-memory keygen if you'd prefer no committed key.
• Cargo.lock: adds only jsonwebtoken's rust_crypto transitive crypto crates (rsa, ecdsa, ed25519, p256/p384, der, spki, etc.). jsonwebtoken 10.4.0 was already in the lock via the CPEX subtree; the diff is add-only (no packages removed).

[rikatz]

I would probably accept this configuration just if a flag is also set to allow http instead of https. Overall, IMO the intention of the user of not using https for something like a jwks endpoint should be a very conscious decision

[rikatz]

maybe not for now, but the metadata can be an arbitrary set of object<string, object>

As an example, Kubernetes JWT token for a SA can be decoded into:

{
  "aud": [
    "https://kubernetes.default.svc.cluster.local"
  ],
  "exp": 1787326909,
  "iat": 1787323309,
  "iss": "https://kubernetes.default.svc.cluster.local",
  "jti": "170964fe-f262-45f7-be60-594c62e70c7a",
  "kubernetes.io": {
    "namespace": "default",
    "serviceaccount": {
      "name": "mygateway",
      "uid": "48c32fc6-a3c8-4e14-ad09-6219c381d4b4"
    }
  },
  "nbf": 1787323309,
  "sub": "system:serviceaccount:default:mygateway"
}

I am not sure if it would make sense to support some more arbitrary structure, or something like a "jsonpath'ish" for these metadata

[rikatz]

we will not now (or never) support symmetric JWT tokens, right? like a shared signing key. I will try to take a look if there is some existing architectural proposal for it, but though would be good to check

[rikatz]

this is very nit, but a fixture private key may cause lots of alarms on code scanners. Just consider maybe if it is possible to generate this during the test and cleanup after the test

[rikatz]

is this really required? I mean, a inner filter could use just the subject for authorization

[rikatz]

maybe make this configurable on the filter?

[rikatz]

nit (possible followup)

I think it makes sense to have the TTL also configurable. Overall:

• An insecure environment, public you may want to have the TTL lowered, in case you need to revoke the keypair signing the JWT tokens you can react fast
• A safe airgapped cluster could probably use of some bigger refresh time for the JWKS

[rikatz]

I was wondering if the cooldown for failures should be somehow an exponential backoff until you hit the max REFRESH_COOLDOWN.

my concern here is that some unavailability on the jwks server will block requests for 30s, while those can be transitive. This could cause an overall unavailability of your authentication workflow.

[yossiovadia]

Good call — implemented in f2c78d8. A successful refresh keeps the 30s anti-stampede cooldown, but a failed one now backs off starting at 1s and doubling per consecutive failure, capped at 30s. So a transient JWKS blip recovers in ~1s instead of blocking auth for a full 30s, while a sustained outage still isn't hammered. Added a test that proves recovery after the short backoff (would fail under the old flat cooldown).

[rikatz]

not sure if this was just added or if I missed it, but resolves my comment on the backoff, thanks!

[rikatz]

more like a consistency concern: would it make sense to not make user assumptions, but instead explicit choices?

As an example, per RFC-6750 the authorization header is always of format "Bearer" 1*SP b64token so a header like "x-api-key: bearer xpto" doesn't really match this expectations.

I would put on a different way:

• If the token_header is named "Authorization" you expect its value to be "Bearer <1 space only> value"
• If the token is something else, you get its value directly

In case some other format is required I would consider it a followup.

[rikatz]

this is some info from previous debug, or left intentionally?

[praxis-bot]

Re-Review: Exponential Backoff Changes

Reviewed commit f2c78d8 (exponential backoff on JWKS refresh failure) and found 2 new issues.

Severity	Count
Large	1
Medium	1

All findings have inline placement.

[praxis-bot]

[Large] The exponential backoff starts from when the refresh STARTS, not when it COMPLETES. In refresh(), last_refresh is set at line 209 before the fetch begins. On success, it's correctly updated again at line 266 after the fetch completes, so the 30s cooldown starts from completion time. But on failure, this branch (line 181-191) does NOT update last_refresh again, so the backoff is measured from the START of the failed fetch.

This means if a JWKS fetch takes T seconds to timeout/fail and the configured backoff is B seconds, the effective backoff is max(0, B - T). For example, with the default 10-second HTTP timeout (line 106) and 1-second initial backoff (line 33), a slow or unresponsive IdP will have failed fetches retried immediately after each 10-second timeout, creating a stampede of long-running timeout requests instead of spacing them 1 second apart.

The test at line 583-635 doesn't catch this because it uses a 503 response (which fails immediately) rather than a timeout.

Fix: Add keys.last_refresh = Some(Instant::now()); after line 188 so the failure backoff starts from when the fetch completed, matching the success case behavior at line 266.

[praxis-bot]

[Medium] The exponential backoff test only verifies single-failure recovery. It doesn't test:

1. Multiple consecutive failures growing the backoff exponentially (1s → 2s → 4s → 8s → 16s → 30s cap)
2. The backoff cap at REFRESH_COOLDOWN (30s)
3. Success resetting consecutive_failures to 0 after multiple failures
4. Backoff timing when the fetch takes significant time to fail (e.g., 5-10 second timeout)

Add tests covering these scenarios to ensure the backoff behaves correctly and prevent regressions. The multi-failure growth test is particularly important since that logic (line 186-188 in jwks.rs) has non-trivial math that should be verified.

[shaneutt]

Temporary hold here for some discussion