rack-jwt-verifier 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c35bb9f8356d419cb0d0344da15e969046789c110923fdf67c5818766b542693
-  data.tar.gz: 69b50273533a7dce2ab5abd341f226b3ccafcf10e5aa7a21650d2bfaceddc86a
+  metadata.gz: 68a95279b6745f43c94283fc1c16a94cd2221fdcd7206bc07d276c50668fe742
+  data.tar.gz: 569c5fa0708beaae3109f7c80e6343e340b626e7a58f6888d10a3405d69c3111
 SHA512:
-  metadata.gz: d96ea044955d67e95bd37b2dc7575d807b2a17a8c92d5da24ce14d65f6ad45eac14c5f2cae2ffed9a9f321d126bcf64e9c4375ab761e2a74a3899f45852b6185
-  data.tar.gz: b4a0d02c27b1bcab756864585237d6881c869823aa2f1ca04e40539466bd02c2f35298fe2881f1c03dcef192e69366c0edfa98fae10faf2cfd32d6365fdbc2fe
+  metadata.gz: 60f7ec0e2955d7abd1d28db30888eec1d17d4cd3ef9106c388420f465555f197c8ee6a927157de117932f13eae18779e8c6329eb8034836c8c6952d2418ce4da
+  data.tar.gz: 33f8b1224fde05a660d1d64d6df41abeeaa8b2393044bb0668b696a4bc982cf50452958ad7e3bfdb1ba265468a87efc6fc609d111d021c63be2b237b657fa68b

data/CHANGELOG.md

@@ -7,6 +7,91 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-13
+
+Interop with [`jwt_auth_client`](https://github.com/danielefrisanco/jwt_auth_client) 0.2.0 and a
+stricter claim policy. **Breaking**: `iss` and `aud` must now be configured, tokens must carry
+`exp`, and boot-time option errors raise `ConfigurationError` instead of `ArgumentError`. See the
+upgrade notes.
+
+### Added
+- **`shared_secret:`** key source — a `String` or `{ env: "VAR_NAME" }` — enabling `HS256`/`HS384`/
+  `HS512`. This is what `jwt_auth_client` 0.2.x signs with. Guardrails, all at boot: the secret must
+  be at least 32/48/64 bytes (RFC 7518 §3.2, matching the issuer's rule); a secret cannot be given
+  alongside `public_key`/`public_key_url`/`jwks_url`; `HS*` cannot be listed without a secret nor
+  next to `RS*`/`ES*`/`PS*`; `none` is refused in any spelling, including via `decode_options`.
+  Asymmetric keys remain the default and the recommended path; HMAC is documented as the mode for a
+  small trusted set of internal services.
+- **`require_scopes:`** middleware option: a token lacking a listed scope gets `403` with an RFC
+  6750 `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"` challenge (reason
+  `:insufficient_scope` for `on_error`/JSON bodies, carrying an `InsufficientScopeError` with
+  `#required`/`#missing`). Implies `require_token: true`.
+- **`RackJwtVerifier::Scopes`** helper (`.from`, `.include?`, `.missing`) reading a `scopes` Array
+  (jwt_auth_client) or an OAuth-style space-delimited `scope` String, for per-route checks.
+- **`replay_cache:`** option (default off): `true` records each `jti` in `cache_store` (or a fresh
+  `InProcessCache`); a store object records it there. A token is accepted once until `exp` +
+  leeway; a second presentation is `401`; a token with no `jti` is `401`; an unavailable replay
+  store answers `503` (reason `:replay_cache_unavailable`) — fail closed.
+- **`require_iss_aud:`** option (default `true`); `false` restores the 0.2.0 boot warning.
+- `decode_options[:required_claims]` (default `["exp"]`).
+- `Verifier#algorithms` exposes the effective, policy-checked algorithm list.
+- Error hierarchy: `RackJwtVerifier::Error` > `ConfigurationError`, `KeyFetchError`,
+  `ReplayCacheError`, `InsufficientScopeError`; `ReplayedTokenError < JWT::InvalidJtiError`.
+- `InProcessCache`: `write(..., unless_exist: true)` (returns `false` when a live entry exists),
+  `#clear`, `#size`, and amortised eviction of expired entries so a jti-per-request workload cannot
+  grow it without bound.
+- Round-trip interop specs driving `jwt_auth_client`'s `TokenIssuer`, `Issuable` and `HttpClient`
+  output through the middleware (HS256/384/512, iss/aud, leeway, scopes, replay), plus the same
+  payload shape re-signed with RS256/ES256 + `kid` through a JWKS as a preview of jwt_auth_client
+  0.3.0. `jwt_auth_client` is an optional path development dependency (`JWT_AUTH_CLIENT_PATH`).
+- CI: Ruby 3.1–4.0 and a ruby-jwt 3 leg (`gemfiles/jwt_3.gemfile`); the gemspec allows `jwt >= 2.8, < 4`.
+- The key fetch applies `write_timeout` as well as open/read; a spec pins down that redirects are
+  never followed.
+
+### Changed
+- **Requires Ruby >= 3.1** (was 3.0, which is end-of-life; `jwt_auth_client` needs 3.1 too).
+- **`iss` and `aud` are required.** `Middleware.new` raises `ConfigurationError` unless
+  `decode_options` sets both (non-blank; `iss` may be an Array), or `require_iss_aud: false` is
+  passed. Previously a warning was logged when *neither* was set.
+- **`exp` is required.** ruby-jwt only checks `exp` when the claim is present, so a token without
+  one was previously valid forever. Override with `decode_options: { required_claims: [] }`.
+- Boot-time option errors (no/several key sources, bad URL, unparsable key, bad `skip:` rule) raise
+  `RackJwtVerifier::ConfigurationError` (was `ArgumentError`).
+- `decode_options[:algorithm]`/`[:algorithms]` are folded into the same algorithm policy as the
+  top-level `algorithms:` instead of bypassing it.
+- `decode_options[:leeway]` is validated at boot (non-negative Numeric).
+- README: `EdDSA` is no longer listed as supported — ruby-jwt 2.x only provides it through the
+  native `rbnacl` gem (3.x through `jwt-eddsa`), neither of which is a dependency.
+
+### Deprecated
+- **`RackJwtVerifier::JwtHelper`** — a second token issuer inside the verifier, minting tokens
+  without `iss`/`aud`/`nbf`/`jti` that no longer pass the claim policy. Issue tokens with
+  `jwt_auth_client`; in test suites sign with `JWT.encode` (see `spec/support/token_factory.rb`
+  for a helper to copy). It warns once per process (`RACK_JWT_VERIFIER_SILENCE_DEPRECATIONS=1`
+  silences it) and will be removed in 0.4.0.
+
+### Security
+- Algorithm confusion is ruled out at boot: HMAC and asymmetric algorithms can never be enabled
+  on the same verifier, a shared secret can never sit next to a public key, and `none` is refused
+  everywhere. ruby-jwt 2.x itself accepts any non-empty String as an HMAC key, so the RFC 7518
+  minimum length is enforced by this gem.
+- Tokens without `exp` are refused (see *Changed*).
+
+### Upgrade notes (0.2.0 → 0.3.0)
+1. Ruby 3.1 or newer is required.
+2. Set `decode_options: { iss: "...", aud: "..." }` on every middleware. If you truly cannot check
+   one of them, pass `require_iss_aud: false` and accept the boot warning.
+3. Tokens must carry `exp`. If your provider omits it, pass
+   `decode_options: { required_claims: [] }` — and reconsider the provider.
+4. Code rescuing `ArgumentError` around `Middleware.new`/`Verifier.new` should rescue
+   `RackJwtVerifier::ConfigurationError` (or `RackJwtVerifier::Error`).
+5. Replace `RackJwtVerifier::JwtHelper` with `jwt_auth_client` (or `JWT.encode` in tests) before
+   0.4.0.
+6. To verify `jwt_auth_client` tokens: `shared_secret: { env: "JWT_SERVICE_SECRET" }`,
+   `algorithms: ["HS256"]` (the issuer's `config.algorithm`), `iss:` = the issuer's
+   `config.issuer`, `aud:` = the `target_service` name. See the README's *Pairing with
+   jwt_auth_client*.
+
 ## [0.2.0] - 2026-09-12
 
 A security and correctness release. **Read the *Security* section before upgrading**: an
@@ -96,6 +181,7 @@ before), and a key outage answers `503` instead of `500`.
 - Initial release: `RackJwtVerifier::Middleware`, `Verifier` with pluggable cache store,
   `InProcessCache`, and `JwtHelper`.
 
-[Unreleased]: https://github.com/danielefrisanco/rack_jwt_verifier/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/danielefrisanco/rack_jwt_verifier/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/danielefrisanco/rack_jwt_verifier/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/danielefrisanco/rack_jwt_verifier/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/danielefrisanco/rack_jwt_verifier/releases/tag/v0.1.0

data/README.md

@@ -1,19 +1,23 @@
 RackJwtVerifier
 ===============
 
-A Rack middleware that authenticates requests with JSON Web Tokens (JWT) signed by an external identity provider (SSO / OIDC).
+A Rack middleware that authenticates requests with JSON Web Tokens (JWT) signed by an external identity provider (SSO / OIDC) or by your own internal services.
 
-It verifies the signature against the provider's public key — from a **JWKS endpoint**, a **PEM URL** or a **static key** — validates the standard claims, caches key material, handles key rotation, and puts the verified claims into the Rack environment for your application. Works with any Rack application, including Ruby on Rails.
+It verifies the signature against the provider's public key — from a **JWKS endpoint**, a **PEM URL** or a **static key** — or, as an explicit opt-in for internal services, against a **shared HMAC secret**; validates the standard claims, caches key material, handles key rotation, and puts the verified claims into the Rack environment for your application. Works with any Rack application, including Ruby on Rails.
+
+It is the verifying half of a pair: [`jwt_auth_client`](https://github.com/danielefrisanco/jwt_auth_client) issues the tokens on the calling side. See [Pairing with jwt_auth_client](#pairing-with-jwt_auth_client).
 
 Features
 --------
 
-*   **Three key sources:** `jwks_url` (what Keycloak, Auth0, Okta, Entra ID, Cognito, Google… publish), `public_key_url` (a PEM public key or X.509 certificate), or a static `public_key`.
-*   **Algorithms:** `RS256` by default; any algorithm ruby-jwt supports (`RS*`, `PS*`, `ES*`, `EdDSA`) via `algorithms:`.
-*   **Claim validation:** `exp` and `nbf` always; `iss`, `aud` and `sub` as soon as you configure them.
+*   **Key sources:** `jwks_url` (what Keycloak, Auth0, Okta, Entra ID, Cognito, Google… publish), `public_key_url` (a PEM public key or X.509 certificate), a static `public_key`, or — opt-in — a `shared_secret` for HMAC.
+*   **Algorithms:** `RS256` by default; `RS*`, `PS*`, `ES*` via `algorithms:`; `HS256`/`HS384`/`HS512` only with `shared_secret`. HS and RS/ES can never be enabled together, and `none` is always refused — at boot.
+*   **Claim validation:** `exp` (required), `nbf`, and `iss`/`aud` — which you must configure, or opt out of explicitly.
+*   **Scopes:** `require_scopes:` answers `403` with an RFC 6750 `insufficient_scope` challenge; `RackJwtVerifier::Scopes` reads scopes for per-route checks.
+*   **Replay protection:** optional `replay_cache:` remembers each `jti` until the token expires.
 *   **Key rotation:** unknown `kid` or a signature mismatch triggers a rate-limited refetch, so rotated keys are picked up without waiting for the cache TTL.
 *   **Caching:** in-process by default; plug in any `read`/`write` cache store (e.g. `ActiveSupport::Cache`) so all workers share one fetched key.
-*   **Hardened fetch:** HTTPS enforced, 5 s timeouts, 64 KB size cap, bad responses never cached.
+*   **Hardened fetch:** HTTPS enforced, redirects never followed, 5 s timeouts, 64 KB size cap, bad responses never cached.
 *   **Rack 2 and 3**, `Rack::Lint`-clean responses, RFC 6750 `WWW-Authenticate` challenges, optional JSON error bodies, path skipping, custom error hook.
 
 Installation
@@ -27,7 +31,7 @@ gem 'rack-jwt-verifier'
 $ bundle install
 ```
 
-Requires Ruby 3.0+ and Rack 2.2 or 3.x.
+Requires Ruby 3.1+, Rack 2.2 or 3.x, and ruby-jwt 2.8+ or 3.x.
 
 Quick start
 -----------
@@ -42,10 +46,14 @@ Rails.application.config.middleware.use RackJwtVerifier::Middleware,
   }
 ```
 
+`iss` and `aud` are required: the middleware refuses to boot without them (see [Claim validation](#claim-validation-decode_options)).
+
 Then, in your application:
 
 ```ruby
 claims = request.env["rack_jwt_verifier.payload"]  # Hash of claims, or nil if no token was sent
+claims["sub"]                                       # the subject
+RackJwtVerifier::Scopes.from(claims)                # => ["read:invoices", ...]
 ```
 
 Key sources
@@ -58,6 +66,7 @@ Exactly one of these must be given.
 | `:jwks_url` | A JSON Web Key Set (`{"keys":[…]}`) | Tokens are matched by their `kid` header. Recommended — this is what nearly every provider publishes. |
 | `:public_key_url` | A single PEM public key **or** an X.509 certificate | Fine for providers that expose one key. |
 | `:public_key` | A PEM string, certificate PEM, or `OpenSSL::PKey` | No network access at all. Handy for `ENV["SSO_PUBLIC_KEY"]`. |
+| `:shared_secret` | An HMAC secret: a `String`, or `{ env: "VAR_NAME" }` | Enables `HS256`/`HS384`/`HS512`. For a small trusted set of internal services only — see below. |
 
 URLs must be `https://`. Pass `allow_insecure_http: true` to permit `http://` **in development only** — over plaintext HTTP an attacker on the network path can swap the key and mint arbitrary tokens.
 
@@ -76,6 +85,25 @@ use RackJwtVerifier::Middleware,
 
 Tokens without a `kid` header are rejected when using `jwks_url`. If your provider does not set one, add `decode_options: { allow_nil_kid: true }` — the first key in the set is then used.
 
+`EdDSA` is not in scope: ruby-jwt 2.x only provides it through the native `rbnacl` gem and 3.x through `jwt-eddsa`; neither is a dependency here.
+
+### Shared secret (HMAC) — internal services only
+
+Asymmetric keys are the default and the recommended path: the verifier only ever holds a *public* key, so a compromised API cannot mint tokens. A shared secret is different — **every service holding it can mint tokens for every audience**. Use `shared_secret` for a small, trusted set of internal services that you control on both ends (this is what `jwt_auth_client` 0.2.x needs), keep the set of holders small, and move to asymmetric keys when the issuer supports them.
+
+```ruby
+use RackJwtVerifier::Middleware,
+  shared_secret: { env: "JWT_SERVICE_SECRET" },     # or the String itself: ENV.fetch("JWT_SERVICE_SECRET")
+  algorithms: ["HS256"],                           # default with shared_secret; HS384/HS512 also allowed
+  decode_options: { iss: "main_app_sso", aud: "billing_api" }
+```
+
+Guardrails, all enforced at boot with a `RackJwtVerifier::ConfigurationError`:
+
+*   The secret must be at least **32 / 48 / 64 bytes** for HS256 / HS384 / HS512 (RFC 7518 §3.2) — the same rule `jwt_auth_client` applies when signing. `openssl rand -hex 32` produces a 64-byte hex string that satisfies all three.
+*   `shared_secret` cannot be combined with `public_key`, `public_key_url` or `jwks_url`, and `HS*` cannot appear in `algorithms` without it, nor next to `RS*`/`ES*`/`PS*`. This closes the classic algorithm-confusion attack in which an attacker signs a token with `HS256` using the *public* key as the secret.
+*   `none` is refused everywhere, in any spelling, including through `decode_options`.
+
 Caching and key rotation
 ------------------------
 
@@ -108,12 +136,15 @@ Options
 | `:json_errors` | `false` | Render `401`/`503` bodies as `{"error": "...", "error_description": "..."}` with `content-type: application/json`. |
 | `:on_error` | — | `->(env, reason, exception) { … }` returning a Rack response to use instead of the default, or `nil` to keep the default. `reason` is `:missing_token`, `:invalid_token` or `:key_unavailable`. |
 | `:logger` | `env["rack.logger"]` | Rejected tokens log at `warn`, key-fetch failures at `error`. Falls back to the request's `rack.logger` (`Rails.logger` in Rails), then to silence. |
+| `:require_scopes` | `[]` | Scopes every token must grant. A token lacking one gets `403` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`. Implies `require_token: true`. See *Scopes*. |
+| `:require_iss_aud` | `true` | Refuse to boot unless `decode_options` sets both `iss` and `aud`. `false` logs a warning instead. |
+| `:replay_cache` | off | `true` to record each `jti` in `cache_store`, or a cache store to record it in. See *Replay protection*. |
 
 ### Key fetching
 
 | Option | Default | Purpose |
 | -- | -- | -- |
-| `:algorithms` | `["RS256"]` | Accepted signing algorithms. |
+| `:algorithms` | `["RS256"]` (`["HS256"]` with `shared_secret`) | Accepted signing algorithms. `HS*` only with `shared_secret`; never mixed. |
 | `:cache_store` | `InProcessCache.new` | See *Caching* above. |
 | `:cache_ttl` | `300` | Seconds to cache fetched key material. |
 | `:refetch_interval` | `60` | Minimum seconds between rotation-triggered refetches. |
@@ -128,17 +159,65 @@ Everything here is handed to `JWT.decode`.
 
 | Option | Default | Purpose |
 | -- | -- | -- |
-| `:iss` | — | **Recommended.** The issuer the token must carry. |
-| `:aud` | — | **Recommended.** The audience the token must carry. |
+| `:iss` | — | **Required.** The issuer the token must carry (a String, or an Array of accepted issuers). |
+| `:aud` | — | **Required.** The audience the token must carry. |
 | `:sub` | — | The subject the token must carry. |
 | `:leeway` | `60` | Clock-skew tolerance, in seconds, for `exp` and `nbf`. `0` for strict timing. |
+| `:required_claims` | `["exp"]` | Claims that must be present. ruby-jwt only *checks* `exp` when it is there; requiring it means a token without an expiry is refused rather than valid forever. |
 | `:verify_expiration` | `true` | Check `exp`. Leave on. |
 | `:verify_not_before` | `true` | Check `nbf`. Leave on. |
 | `:allow_nil_kid` | `false` | JWKS only: accept tokens without a `kid`. |
 
 > The `jwt` gem only checks `iss`/`aud`/`sub` when the matching `verify_iss`/`verify_aud`/`verify_sub` flag is also `true`. This middleware switches the flag on automatically whenever you supply a value, so `iss: "…"` really is enforced. An explicit `verify_iss: false` next to `iss:` is respected.
 
-The middleware logs a warning at boot if neither `iss` nor `aud` is configured: a key alone proves who *signed* a token, not who it was *for*.
+**`iss` and `aud` are required.** A key proves who *signed* a token, not who it was *for* — and a shared secret proves even less. `Middleware.new` raises `ConfigurationError` when either is missing. If you genuinely cannot check them (a provider that sets no `aud`, say), pass `require_iss_aud: false`; the middleware then logs a warning at boot instead.
+
+Scopes
+------
+
+The verified claims are in `env["rack_jwt_verifier.payload"]`, `sub` included. Scopes are read from a `scopes` claim (an Array of Strings, what `jwt_auth_client` emits) or, failing that, an OAuth-style space-delimited `scope` String.
+
+Require scopes globally on the middleware:
+
+```ruby
+use RackJwtVerifier::Middleware, jwks_url: "…", decode_options: { … },
+  require_scopes: ["read:invoices"]
+```
+
+A token lacking any of them is refused with `403` and
+
+```
+WWW-Authenticate: Bearer error="insufficient_scope", error_description="Token lacks required scope(s): read:invoices", scope="read:invoices"
+```
+
+(`reason` is `:insufficient_scope` for `on_error` and JSON bodies; the hook receives a `RackJwtVerifier::InsufficientScopeError` with `#required` and `#missing`). `require_scopes` implies `require_token: true`.
+
+For per-route checks, use the helper in your application:
+
+```ruby
+claims = request.env["rack_jwt_verifier.payload"]
+RackJwtVerifier::Scopes.from(claims)                            # => ["read:invoices"]
+RackJwtVerifier::Scopes.include?(claims, "write:invoices")      # => false
+RackJwtVerifier::Scopes.missing(claims, %w[read:x write:x])     # => ["write:x"]
+```
+
+Replay protection
+-----------------
+
+Off by default. With `replay_cache:` each verified token's `jti` is remembered until the token's `exp` (plus leeway), and a second presentation is refused with `401 invalid_token`. Tokens without a `jti` are refused too.
+
+```ruby
+use RackJwtVerifier::Middleware, …,
+  cache_store: Rails.cache,
+  replay_cache: true              # record jtis in cache_store …
+  # replay_cache: Rails.cache     # … or in a store of their own
+```
+
+*   The store is the same `read`/`write` abstraction as `cache_store`. `true` uses `cache_store` (or a fresh `InProcessCache` when none was given). An **in-process store only detects replays within one worker**; use a shared store (`Rails.cache` on Redis/Memcached) for real protection.
+*   `jwt_auth_client` mints a fresh `jti` per request by default (`token_reuse_seconds = 0`), so replay protection works out of the box; with `token_reuse_seconds > 0` on the issuer, do not enable it here.
+*   The check runs only after every other check passed, so an expired or mis-signed token cannot "burn" a `jti`.
+*   A replay store that raises makes the request fail **closed**: `503` with `Retry-After`, reason `:replay_cache_unavailable`. You asked for the guarantee; skipping it silently would be worse than a retryable error. (The key cache, by contrast, fails open — a fetch still verifies the signature.)
+*   Keys are `rack_jwt_verifier:jti:<sha256 of jti>`, written with `unless_exist: true` so stores that support it (ActiveSupport's do) close the check-then-write window.
 
 Request flow
 ------------
@@ -149,19 +228,68 @@ Request flow
 3.  Key material is read from the cache, or fetched on a miss.
 4.  Signature and claims are verified.
     *   Success: the claims are stored in `env["rack_jwt_verifier.payload"]` and the request continues.
-    *   Invalid token (expired, bad signature, wrong issuer/audience, unknown `kid`): `401` with `WWW-Authenticate: Bearer error="invalid_token", error_description="…"`.
-    *   Key material unavailable (endpoint down, timeout, not a key): `503` with `Retry-After: 5` — the failure is on our side, not the client's.
+    *   Invalid token (expired, bad signature, wrong issuer/audience, unknown `kid`, replayed `jti`): `401` with `WWW-Authenticate: Bearer error="invalid_token", error_description="…"`.
+    *   Valid token without a required scope: `403` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="…"`.
+    *   Key material unavailable (endpoint down, timeout, not a key), or the replay store down: `503` with `Retry-After: 5` — the failure is on our side, not the client's.
 
 `JWT::DecodeError`s raised by *your* application are never intercepted; only the middleware's own verification step is guarded.
 
+Errors
+------
+
+| Class | Raised when |
+| -- | -- |
+| `RackJwtVerifier::ConfigurationError` | An unusable option set, at boot (`Middleware.new` / `Verifier.new`): no or several key sources, `HS*` mixed with `RS*`, a short secret, missing `iss`/`aud`, an `http://` URL, … |
+| `RackJwtVerifier::KeyFetchError` | Key material could not be fetched or parsed. The middleware turns it into a `503`. |
+| `RackJwtVerifier::ReplayCacheError` | The replay store could not be read or written. `503`. |
+| `RackJwtVerifier::ReplayedTokenError` (`< JWT::InvalidJtiError`) | A `jti` was presented twice. `401`. |
+| `RackJwtVerifier::InsufficientScopeError` | Handed to `on_error` for a `403`; carries `#required` and `#missing`. |
+
+All but `ReplayedTokenError` inherit from `RackJwtVerifier::Error`. Token verification failures are ruby-jwt's `JWT::DecodeError` family.
+
+Pairing with jwt_auth_client
+----------------------------
+
+[`jwt_auth_client`](https://github.com/danielefrisanco/jwt_auth_client) is the issuing half: it mints `{ iss, sub, aud, scopes, iat, nbf, exp, jti, … }` tokens and sends them as `Bearer` tokens from one internal service to another. Today (0.2.x) it signs with `HS256`/`HS384`/`HS512` and a shared secret; asymmetric signing with a `kid` is planned for its 0.3.0, at which point the verifier side below becomes a `jwks_url`.
+
+Issuer (`config/initializers/jwt_auth_client.rb` in the *calling* service):
+
+```ruby
+JwtAuthClient.configure do |config|
+  config.shared_secret = ENV.fetch("JWT_SERVICE_SECRET")   # >= 32 bytes; openssl rand -hex 32
+  config.issuer = "main_app_sso"
+  config.algorithm = "HS256"
+  config.service_urls = { billing_api: "https://billing.internal" }
+end
+
+BILLING = JwtAuthClient::HttpClient.call(user_id: "etl", target_service: :billing_api, scopes: ["read:invoices"])
+```
+
+Verifier (in the *receiving* service, `billing_api`):
+
+```ruby
+Rails.application.config.middleware.use RackJwtVerifier::Middleware,
+  shared_secret: { env: "JWT_SERVICE_SECRET" },   # the same secret
+  algorithms: ["HS256"],                          # the same algorithm
+  decode_options: {
+    iss: "main_app_sso",                          # jwt_auth_client's config.issuer
+    aud: "billing_api"                            # the target_service the caller names
+  },
+  require_scopes: ["read:invoices"],              # optional
+  replay_cache: true, cache_store: Rails.cache    # optional
+```
+
+The claims then arrive as `env["rack_jwt_verifier.payload"]`: `sub` is the caller's `user_id`, `scopes` its scopes, and any custom claims from `Issuable#jwt_claims` (`user_id`, `email`, …) come through unchanged. The [interop spec](spec/rack_jwt_verifier/interop_spec.rb) exercises exactly this round trip against the real gem.
+
 Security considerations
 -----------------------
 
-*   **Always set `iss` and `aud`.** Without them any token signed by the provider — for any application — is accepted.
-*   **Use HTTPS for key URLs.** `allow_insecure_http` exists for local development only.
+*   **`iss` and `aud` are mandatory** for a reason: without them any token signed by the provider — for any application — is accepted. Opt out only when you cannot check them, and know what that means.
+*   **Use HTTPS for key URLs.** `allow_insecure_http` exists for local development only. Redirects are never followed.
 *   **Prefer `jwks_url`.** It supports multiple keys and `kid`-based rotation; a single PEM URL cannot express an overlap period.
 *   **Keep `leeway` small.** 60 s covers real clock skew; larger values extend the life of expired tokens.
-*   **Stick to asymmetric algorithms.** The middleware only ever holds public keys; do not add `HS*` to `algorithms`.
+*   **Prefer asymmetric algorithms.** With a public key the verifier cannot mint tokens; with a shared secret it can. `HS*` and `RS*`/`ES*` are never accepted together — the middleware refuses to boot if you try — so a public key can never be reinterpreted as an HMAC secret.
+*   **Replay protection needs a shared store** to mean anything across workers or hosts.
 
 Design notes
 ------------
@@ -173,19 +301,25 @@ A few choices that are not obvious from the code:
 *   **`iss`/`aud` switch their `verify_*` flag on automatically.** ruby-jwt ignores an expected claim value unless the flag is set; requiring users to pass both is how the 0.1.0 README ended up recommending a configuration that enforced nothing.
 *   **Key-fetch failures answer 503, not 401.** The client did nothing wrong; a 401 would make it discard a valid token and re-authenticate.
 *   **Rotation refetches are rate-limited** (`refetch_interval`) so a stream of forged tokens cannot be turned into a stream of requests to the provider.
+*   **The HMAC key-length rule lives here, not in ruby-jwt.** ruby-jwt 2.x verifies with any non-empty String; the RFC 7518 minimum is enforced by this gem so both halves of the pair agree.
+*   **The replay store fails closed, the key cache fails open.** A key-cache miss still ends in a verified signature; a skipped replay check silently drops a guarantee the operator asked for.
+*   **`JwtHelper` is deprecated** (removal in 0.4.0). It was a second token issuer inside the verifier, signing without `iss`/`aud`/`nbf`/`jti`. Issue with `jwt_auth_client`; in test suites sign with `JWT.encode` (see `spec/support/token_factory.rb`). It warns once per process; `RACK_JWT_VERIFIER_SILENCE_DEPRECATIONS=1` silences it.
 
 Development
 -----------
 
-RSpec, WebMock (no real network in tests), Timecop and RuboCop. CI runs the suite on Ruby 3.0–3.4 against both Rack 2 and Rack 3.
+RSpec, WebMock (no real network in tests), Timecop and RuboCop. CI runs the suite on Ruby 3.1–4.0 against Rack 2, Rack 3 and ruby-jwt 2/3.
 
 ```bash
 $ bundle install
 $ bundle exec rake            # specs + rubocop
 $ bundle exec rspec
 $ BUNDLE_GEMFILE=gemfiles/rack_2.gemfile bundle exec rspec   # the Rack 2 leg
+$ BUNDLE_GEMFILE=gemfiles/jwt_3.gemfile bundle exec rspec    # the ruby-jwt 3 leg
 ```
 
+The interop specs need a checkout of `jwt_auth_client` next to this repository (or `JWT_AUTH_CLIENT_PATH=/path/to/it`); they skip otherwise.
+
 License
 -------
 

data/lib/rack_jwt_verifier/errors.rb

@@ -1,8 +1,40 @@
 # frozen_string_literal: true
 
+require "jwt"
+
 module RackJwtVerifier
+  # Base class for every error this gem raises on its own behalf. Token
+  # verification failures keep raising ruby-jwt's JWT::DecodeError family.
+  class Error < StandardError; end
+
+  # Raised at boot for an unusable option set: no key source, a shared secret
+  # next to a public key, HS* mixed with RS*/ES*, a too-short secret, missing
+  # iss/aud, ... Raised from Middleware.new / Verifier.new, never per request.
+  class ConfigurationError < Error; end
+
   # Raised when the verification key material cannot be obtained or parsed:
   # the remote endpoint is down or slow, returned something that is not a
   # key, or the configured static key does not parse.
-  class KeyFetchError < StandardError; end
+  class KeyFetchError < Error; end
+
+  # Raised when the replay cache (jti store) cannot be read or written. The
+  # middleware answers 503: the operator asked for replay protection, so a
+  # request whose jti cannot be checked is refused rather than waved through.
+  class ReplayCacheError < Error; end
+
+  # Raised when a token's jti has already been seen. Subclasses ruby-jwt's
+  # InvalidJtiError so it travels the same 401 path as any other bad claim.
+  class ReplayedTokenError < JWT::InvalidJtiError; end
+
+  # Handed to the :on_error hook when a token lacks a scope listed in
+  # require_scopes. Carries what was required and what was missing.
+  class InsufficientScopeError < Error
+    attr_reader :required, :missing
+
+    def initialize(required:, missing:)
+      @required = required
+      @missing = missing
+      super("Token lacks required scope(s): #{missing.join(' ')}")
+    end
+  end
 end

data/lib/rack_jwt_verifier/in_process_cache.rb

@@ -12,39 +12,41 @@ module RackJwtVerifier
     # correction, DST) cannot extend or cut short an entry's life.
     MONOTONIC_CLOCK = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
 
+    # Expired entries are swept whenever the store grows past this many
+    # entries, and the threshold then doubles from whatever survived. Amortised
+    # O(1) per write, so a jti-per-request workload cannot grow the store
+    # without bound while a single-key workload never pays for a sweep.
+    SWEEP_THRESHOLD = 1024
+
     # @param clock [#call] Returns the current time in seconds; injectable for tests.
     def initialize(clock: MONOTONIC_CLOCK)
       @store = {}
       @lock = Mutex.new # Ensure thread safety for multi-threaded environments
       @clock = clock
+      @sweep_at = SWEEP_THRESHOLD
     end
 
     # Reads the value for a given key. Automatically checks for expiry.
     # @param key [String] The cache key.
     # @return [Object, nil] The cached value or nil if expired or not found.
     def read(key)
-      @lock.synchronize do
-        entry = @store[key]
-        return nil unless entry
-
-        value, expires_at = entry
-
-        # Check if the entry is expired
-        return nil if @clock.call >= expires_at
-
-        value
-      end
+      @lock.synchronize { live_value(key) }
     end
 
     # Writes a value to the cache with an optional expiration time.
     # @param key [String] The cache key.
     # @param value [Object] The value to store.
-    # @param options [Hash] Options, expecting :expires_in (seconds).
-    # @return [Object] The stored value.
+    # @param options [Hash] :expires_in (seconds); :unless_exist (true to keep
+    #   an existing live entry, as ActiveSupport stores do).
+    # @return [Object, false] The stored value, or false when :unless_exist
+    #   was given and a live entry already existed.
     def write(key, value, options = {})
       @lock.synchronize do
+        return false if options[:unless_exist] && !live_value(key).nil?
+
         expiry = options[:expires_in] || DEFAULT_EXPIRY
         @store[key] = [value, @clock.call + expiry]
+        sweep_if_needed
         value
       end
     end
@@ -58,5 +60,41 @@ module RackJwtVerifier
         entry&.first
       end
     end
+
+    # Removes every entry.
+    def clear
+      @lock.synchronize do
+        @store.clear
+        @sweep_at = SWEEP_THRESHOLD
+      end
+      nil
+    end
+
+    # Number of entries held, expired ones included until the next sweep.
+    def size
+      @lock.synchronize { @store.size }
+    end
+
+    private
+
+    # Caller holds the lock.
+    def live_value(key)
+      entry = @store[key]
+      return nil unless entry
+
+      value, expires_at = entry
+      return nil if @clock.call >= expires_at
+
+      value
+    end
+
+    # Caller holds the lock.
+    def sweep_if_needed
+      return if @store.size <= @sweep_at
+
+      now = @clock.call
+      @store.delete_if { |_, (_, expires_at)| now >= expires_at }
+      @sweep_at = [@store.size * 2, SWEEP_THRESHOLD].max
+    end
   end
 end

data/lib/rack_jwt_verifier/jwt_helper.rb

@@ -4,16 +4,49 @@ require 'jwt'
 require 'openssl'
 
 module RackJwtVerifier
-  # Issues (and, for round-trip checks, decodes) RS256 tokens from an RSA
-  # private key. This is the *signing* side: use it in tests, or in the service
-  # that mints tokens. The middleware itself only ever needs the public key.
+  # @deprecated Will be removed in 0.4.0. Issues (and, for round-trip checks,
+  #   decodes) RS256 tokens from an RSA private key.
+  #
+  # This is a second token issuer living inside the verifier: it sets neither
+  # `iss`, `aud`, `nbf` nor `jti`, so what it mints does not pass the claim
+  # policy the middleware now enforces. Issue tokens with the `jwt_auth_client`
+  # gem instead (HMAC today, RS256/ES256 from its 0.3.0); in a test suite,
+  # sign with `JWT.encode` directly — see spec/support/token_factory.rb in this
+  # repository for a helper you can copy.
   class JwtHelper
     ALGORITHM = 'RS256'
 
+    DEPRECATION = 'RackJwtVerifier::JwtHelper is deprecated and will be removed in 0.4.0: issue tokens with the ' \
+                  'jwt_auth_client gem, or sign test tokens with JWT.encode. Set ' \
+                  'RACK_JWT_VERIFIER_SILENCE_DEPRECATIONS=1 to silence this warning.'
+
+    @warned = false
+    @warn_lock = Mutex.new
+
+    class << self
+      # Emits the deprecation warning once per process.
+      def warn_deprecated
+        return if ENV['RACK_JWT_VERIFIER_SILENCE_DEPRECATIONS'] == '1'
+
+        @warn_lock.synchronize do
+          return if @warned
+
+          @warned = true
+        end
+        Kernel.warn(DEPRECATION, uplevel: 2)
+      end
+
+      # Forget that the warning was emitted. Intended for test suites.
+      def reset_deprecation_warning!
+        @warn_lock.synchronize { @warned = false }
+      end
+    end
+
     attr_reader :private_key, :public_key
 
     # @param private_key_pem [String, OpenSSL::PKey::RSA] The RSA private key used for signing.
     def initialize(private_key_pem)
+      self.class.warn_deprecated
       @private_key = private_key_pem.is_a?(OpenSSL::PKey::RSA) ? private_key_pem : OpenSSL::PKey::RSA.new(private_key_pem)
       @public_key = @private_key.public_key
     end