rack-jwt-verifier 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e35869423f2fe2b5072d382a8c3404d899f4d1eb67ca2ac8026b341d6f055b52
-  data.tar.gz: 2367980ac3f213c2340ffd7af9158a16262c69d73e09a75762c593017ac3df2e
+  metadata.gz: c35bb9f8356d419cb0d0344da15e969046789c110923fdf67c5818766b542693
+  data.tar.gz: 69b50273533a7dce2ab5abd341f226b3ccafcf10e5aa7a21650d2bfaceddc86a
 SHA512:
-  metadata.gz: b2c4f85b03428e8ff39073083dda5090101dfbbd2e1c8dec51a0c89e08ca6efffea64802042ddbee7f29f6ff5372f12b6c1ec1417498fd08890aedb7e876fbc7
-  data.tar.gz: 4a5d3e3e6f4e4039ed0622644dda9e2db72f83d57a645f38e9eee2893fa68cfbac6f6656a82390399ee7c68570e790e5757b4c56a1bef85643230303a5b39c8e
+  metadata.gz: d96ea044955d67e95bd37b2dc7575d807b2a17a8c92d5da24ce14d65f6ad45eac14c5f2cae2ffed9a9f321d126bcf64e9c4375ab761e2a74a3899f45852b6185
+  data.tar.gz: b4a0d02c27b1bcab756864585237d6881c869823aa2f1ca04e40539466bd02c2f35298fe2881f1c03dcef192e69366c0edfa98fae10faf2cfd32d6365fdbc2fe

data/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-09-12
+
+A security and correctness release. **Read the *Security* section before upgrading**: an
+`http://` key URL now fails at boot, `iss`/`aud` are enforced when set (they silently were not
+before), and a key outage answers `503` instead of `500`.
+
+### Added
+- **`jwks_url:`** — verify against a JSON Web Key Set, matching tokens by `kid`. An unknown `kid`
+  triggers a rate-limited refetch so rotated keys are picked up immediately. A set with no keys,
+  or a body that is not JSON, is rejected before it can be cached.
+- **`public_key:`** — a static PEM public key, X.509 certificate PEM, or `OpenSSL::PKey`; no
+  network access.
+- X.509 certificate PEMs are accepted from `public_key_url` (what Keycloak/Auth0 `.pem` endpoints
+  serve). EC and Ed keys parse too.
+- Key rotation for `public_key_url`: on a signature mismatch the key is refetched once and the
+  token retried. `refetch_interval:` (default 60 s) rate-limits rotation-triggered refetches.
+- `algorithms:` option (default `["RS256"]`). A list given in `decode_options` is no longer
+  silently overridden by the `RS256` default (ruby-jwt reads `:algorithm` before `:algorithms`).
+- `cache_ttl:` option.
+- Middleware: `skip:` (exact path, regexp or callable), `env_key:`, `json_errors:` and an
+  `on_error:` hook receiving `(env, reason, exception)`.
+- The `401` challenge now carries `error_description` (sanitised to RFC 6750's quoted-string
+  alphabet).
+- Cache keys are scoped to the URL, so two verifiers sharing one cache store no longer read each
+  other's key.
+- Single-flight fetching on a cold cache; parsed key material is memoised per body instead of
+  re-parsing the PEM on every request.
+- `require_token:` middleware option — reject requests that carry no token with a bare
+  `WWW-Authenticate: Bearer` challenge instead of passing them through.
+- `logger:` middleware option; falls back to `env["rack.logger"]`, then to silence. Rejected
+  tokens log at `warn`, key-fetch failures at `error`. Replaces the unconditional `Kernel#warn`.
+- A one-time boot warning when neither `iss` nor `aud` is configured.
+- `content-length` on the middleware's own responses.
+- `allow_insecure_http:` and `http_timeout:` middleware options.
+- The key fetch sends `User-Agent: rack_jwt_verifier/<version>` and an `Accept` header.
+
+### Changed
+- Requires Ruby >= 3.0 and Rack >= 2.2 (< 4). Depends on the `logger` gem explicitly, as it leaves
+  Ruby's default gems in 4.0.
+- A failing cache store (Redis down) no longer breaks authentication: reads are treated as
+  misses and writes as no-ops, logged at `warn`; key material is fetched per request until the
+  store recovers.
+- `InProcessCache` measures expiry on the monotonic clock, so wall-clock jumps cannot extend or
+  cut short an entry; the clock is injectable for tests.
+- `JwtHelper#encode` normalises claim keys so a caller's `'exp'` and the generated `:exp` cannot
+  both land in the JSON; `#decode` accepts extra `JWT.decode` options; an `OpenSSL::PKey::RSA` is
+  accepted in place of a PEM.
+- `KeyFetchError` is now `RackJwtVerifier::KeyFetchError`; `Verifier::KeyFetchError` still
+  resolves to the same class.
+- Giving none, or more than one, of `public_key`, `public_key_url`, `jwks_url` raises
+  `ArgumentError` at boot (previously a `KeyError` for the missing URL).
+
+### Security
+- `iss`, `aud` and `sub` values in `decode_options` are now actually enforced. Previously the
+  underlying `jwt` gem silently ignored them unless `verify_iss`/`verify_aud`/`verify_sub` was
+  also set — a token from any issuer was accepted even with `iss:` configured. The matching
+  `verify_*` flag is now enabled automatically whenever a value is supplied.
+- `public_key_url` must be an `https://` URL. A plaintext `http://` URL is rejected at boot
+  unless `allow_insecure_http: true` is passed, since a key fetched over HTTP can be
+  substituted by an on-path attacker.
+- The public key fetch now has a 5-second open/read timeout (configurable via `http_timeout:`)
+  and refuses response bodies over 64 KB, so a slow or misbehaving SSO endpoint cannot pin
+  request threads.
+- `JWT::DecodeError` raised by the downstream application is no longer caught by the
+  middleware and turned into a 401; only the middleware's own verification step is guarded.
+
+### Fixed
+- Response headers are lowercase (`content-type`, `www-authenticate`), as Rack 3 requires;
+  `Rack::Lint` previously rejected the 401 response.
+- A `200` response whose body is not a valid key (e.g. an HTML maintenance page) is no longer
+  written to the cache. Previously it poisoned the cache for the full TTL, failing every
+  request for five minutes after the SSO had recovered.
+- A key-fetch failure (endpoint down, timeout, bad key) now yields `503 Service Unavailable`
+  with `Retry-After: 5` instead of an unhandled `KeyFetchError` (a 500).
+- `require "rack_jwt_verifier/verifier"` on its own no longer raises `NameError` for
+  `InProcessCache`; the file requires its own dependencies.
+- `gem "rack-jwt-verifier"` now loads without a `require:` override: a `lib/rack-jwt-verifier.rb`
+  shim matches the gem name. The README install snippet pointed at a non-existent gem name.
+- The `Bearer` scheme is matched case-insensitively (RFC 7235) and whitespace around the token
+  is tolerated. `bearer <token>` was previously treated as "no token" and passed through.
+- `InProcessCache#delete` returns the deleted value, as documented, rather than the internal
+  `[value, expires_at]` pair.
+
+## [0.1.0] - 2025-10-20
+
+### Added
+- 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
+[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,136 +1,192 @@
 RackJwtVerifier
 ===============
 
-A robust and production-ready Rack middleware for authenticating requests using JSON Web Tokens (JWT) signed by an external Single Sign-On (SSO) provider.
+A Rack middleware that authenticates requests with JSON Web Tokens (JWT) signed by an external identity provider (SSO / OIDC).
 
-This gem handles the cryptographic verification, caching of public keys, and integration into 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** — 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.
 
 Features
 --------
 
-*   **Cryptographic Verification:** Verifies the JWT signature using the `RS256` algorithm and public keys fetched from a remote URL.
-    
-*   **Flexible Caching:** Uses a configurable cache store for public keys, defaulting to in-memory caching but easily upgradable to **Redis** or **Memcached** for multi-process environments.
-    
-*   **Claim Validation:** Enforces standard JWT claims, including expiration (`exp`) and not-before (`nbf`).
-    
-*   **Rack Middleware:** Protects application routes by halting unauthorized requests with a `401 Unauthorized` response.
-    
+*   **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 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.
+*   **Rack 2 and 3**, `Rack::Lint`-clean responses, RFC 6750 `WWW-Authenticate` challenges, optional JSON error bodies, path skipping, custom error hook.
 
 Installation
 ------------
 
-Add this line to your application's `Gemfile`:
-
 ```ruby
-gem 'rack_jwt_verifier'
+gem 'rack-jwt-verifier'
 ```
 
-And then execute:
-
 ```bash
 $ bundle install
 ```
 
-Usage and Integration
----------------------
+Requires Ruby 3.0+ and Rack 2.2 or 3.x.
 
-### 1\. Basic Setup (In-Memory Caching)
+Quick start
+-----------
 
-The simplest way to integrate is by providing the URL where your SSO provider exposes its public key (usually a PEM-encoded RSA key). The public key will be cached in memory for **5 minutes** per worker process.
+```ruby
+# config/application.rb (Rails) or config.ru (plain Rack)
+Rails.application.config.middleware.use RackJwtVerifier::Middleware,
+  jwks_url: "https://sso.example.com/.well-known/jwks.json",
+  decode_options: {
+    iss: "https://sso.example.com",   # who must have issued the token
+    aud: "my-api"                     # who the token must be for
+  }
+```
 
-**In `config/application.rb` (for Rails) or `config.ru` (for generic Rack):**
+Then, in your application:
 
 ```ruby
-# Requires `rack_jwt_verifier` implicitly in Rails, or explicitly in config.ru
-# Replace the URL with your actual SSO Public Key endpoint
-PUBLIC_KEY_URL = "https://sso.example.com/api/v1/public_key"
-Rails.application.config.middleware.use RackJwtVerifier::Middleware,
-                                        public_key_url: PUBLIC_KEY_URL
+claims = request.env["rack_jwt_verifier.payload"]  # Hash of claims, or nil if no token was sent
 ```
-### 2\. Production Setup with Redis Caching
 
-For horizontally scaled applications (e.g., using Puma or multiple Docker containers), the default in-memory cache is inefficient. To prevent a "cache stampede" where all workers simultaneously fetch the key, you must use a distributed cache like Redis.
+Key sources
+-----------
 
-**Prerequisites:** You need a Redis client library installed (e.g., `redis-rails` or `connection\_pool`).
+Exactly one of these must be given.
 
-#### Example: Using Redis as the Cache Store
+| Option | What it serves | Notes |
+| -- | -- | -- |
+| `: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"]`. |
 
-The `RackJwtVerifier` expects a cache object that responds to the standard Ruby cache interface: `#read(key)` and `#write(key, value, expires\_in: ttl)`.
+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.
 
-**Example using `ActiveSupport::Cache::RedisCacheStore` (Common in Rails apps):**
+```ruby
+# Static key from the environment
+use RackJwtVerifier::Middleware,
+  public_key: ENV.fetch("SSO_PUBLIC_KEY"),
+  decode_options: { iss: "https://sso.example.com", aud: "my-api" }
+
+# EC keys need the algorithm list widened
+use RackJwtVerifier::Middleware,
+  jwks_url: "https://sso.example.com/.well-known/jwks.json",
+  algorithms: %w[RS256 ES256],
+  decode_options: { iss: "https://sso.example.com", aud: "my-api" }
+```
+
+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.
+
+Caching and key rotation
+------------------------
+
+Fetched key material is cached for `cache_ttl` seconds (default 300). The default store is a per-process `InProcessCache`; for multi-process or multi-host deployments pass any object with the standard cache-store interface — `read(key)` and `write(key, value, expires_in: seconds)` — so the provider is contacted once per TTL rather than once per worker:
 
 ```ruby
-# In config/initializers/rack_jwt_verifier.rb
-
-# 1. Configure your Redis cache client
-# This example assumes you have Redis configured via Rails:
-REDIS_CACHE_CLIENT = ActiveSupport::Cache.lookup_store(:redis_cache_store, {
-    url: ENV.fetch("REDIS_URL", "redis://localhost:6379/1"),
-    reconnect_attempts: 1  })
-# 2. Configure the Verifier with the Redis client
+# config/initializers/rack_jwt_verifier.rb
 Rails.application.config.middleware.use RackJwtVerifier::Middleware,
-  public_key_url: ENV.fetch("SSO_PUBLIC_KEY_URL"),
-  cache_store: REDIS_CACHE_CLIENT
+  jwks_url: ENV.fetch("SSO_JWKS_URL"),
+  cache_store: Rails.cache,               # any ActiveSupport::Cache::Store works
+  decode_options: { iss: ENV.fetch("SSO_ISSUER"), aud: "my-api" }
 ```
 
-By passing the Redis cache client via the `cache\_store` option, all your application workers will share a single cache, ensuring the public key is fetched from the network only once every 5 minutes (or whatever TTL is configured internally).
+The object must be a cache **store**, not a raw client — a `redis-rb` connection does not respond to `read`/`write`; wrap it in `ActiveSupport::Cache::RedisCacheStore`. Cache keys are namespaced (`rack_jwt_verifier:jwks:<url digest>`) so several middlewares can share one store.
 
-### 3\. Customizing JWT Decoding
+**Rotation.** When a token's `kid` is not in the cached set (JWKS), or its signature does not verify against the cached key (PEM), the middleware refetches once and retries. Refetches are rate-limited to one per `refetch_interval` seconds (default 60) so a flood of forged tokens cannot become a flood of requests to your provider.
 
-You can pass a `:decode\_options` hash to the middleware to override the default settings for the JWT gem.
+Within one process only one thread performs a fetch on a cold cache; the others wait for it.
 
-| Option | Default Value | Purpose | 
-| -- | -- | -- | 
-| `:leeway` | `60` seconds | Sets clock skew tolerance for `exp` and `nbf` checks. Set to `0` for strict timing. | 
-| `:algorithm` | `"RS256"` | The expected signing algorithm. | 
-| `:iss` | (None) | **RECOMMENDED**: Set this to enforce a specific issuer claim. | 
-| `:aud` | (None) | **RECOMMENDED**: Set this to enforce an audience claim. | 
+Options
+-------
 
-**Example: Strict Expiration and Issuer Check:**
+### Middleware
 
-```ruby
-Rails.application.config.middleware.use RackJwtVerifier::Middleware,
-  public_key_url: ENV.fetch("SSO_PUBLIC_KEY_URL"),
-  decode_options: {
-    # No clock skew tolerance
-    leeway: 0,
-    # Ensure the token was issued by our expected SSO provider
-    iss: "[https://my-sso.com/token-service](https://my-sso.com/token-service)"
-  }
-```
+| Option | Default | Purpose |
+| -- | -- | -- |
+| `:require_token` | `false` | `true`: a request with no `Bearer` token gets a `401`. `false`: it is passed through with no payload set, and your application decides. |
+| `:skip` | `[]` | Paths that bypass the middleware entirely: exact strings (`"/health"`), regexps (`%r{\A/public/}`), or callables on the env (`->(env) { env["REQUEST_METHOD"] == "OPTIONS" }`). Matched against `SCRIPT_NAME + PATH_INFO`. |
+| `:env_key` | `"rack_jwt_verifier.payload"` | Rack env key that receives the verified claims. |
+| `: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. |
+
+### Key fetching
+
+| Option | Default | Purpose |
+| -- | -- | -- |
+| `:algorithms` | `["RS256"]` | Accepted signing algorithms. |
+| `: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. |
+| `:http_timeout` | `5` | Open and read timeout, in seconds, for the key fetch. |
+| `:allow_insecure_http` | `false` | Permit a plain `http://` URL. Development only. |
+
+Responses over 64 KB are refused — a PEM key is under 1 KB and a JWKS a few KB.
+
+### Claim validation (`:decode_options`)
+
+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. |
+| `:sub` | — | The subject the token must carry. |
+| `:leeway` | `60` | Clock-skew tolerance, in seconds, for `exp` and `nbf`. `0` for strict timing. |
+| `: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.
 
-How it Works
+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*.
+
+Request flow
 ------------
 
-1.  **Request Flow:** On every incoming HTTP request, the middleware intercepts the call.
-    
-2.  **Token Extraction:** It looks for a token in the `Authorization: Bearer <token>` header.
-    
-3.  **Key Retrieval:** The Verifier attempts to read the public key PEM string from the configured `cache\_store` (Redis or In-Memory).
-    *   If the key is present, it's used immediately.
-    *   If the key is missing or expired, a network request is made to the `public\_key\_url`, and the key is written back to the cache for 5 minutes.
-        
-4.  **Verification:** The public key is used to cryptographically verify the JWT's signature and validate its claims (`exp`, `nbf`, `iss`, etc.).
-    
-5.  **Authorization:**
-    *   If verification succeeds, the request passes to your application.
-    *   If verification fails (e.g., token expired, bad signature, or missing token), the request is halted, and a `401 Unauthorized` response is immediately returned.
-        
+1.  If the path matches a `:skip` rule, the request goes straight through.
+2.  The token is read from `Authorization: Bearer <token>` (scheme matched case-insensitively).
+    *   No token: passed through with no payload — or `401` with `WWW-Authenticate: Bearer` if `require_token: true`.
+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.
+
+`JWT::DecodeError`s raised by *your* application are never intercepted; only the middleware's own verification step is guarded.
+
+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.
+*   **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`.
+
+Design notes
+------------
+
+A few choices that are not obvious from the code:
+
+*   **The gem is `rack-jwt-verifier`, the require path `rack_jwt_verifier`.** The hyphenated name was published first and is what users already depend on, so it stays; `lib/rack-jwt-verifier.rb` is a one-line shim so Bundler's auto-require works.
+*   **Options are a positional hash, not keyword arguments.** `middleware.use Klass, hash` hands the hash over positionally, so a keyword signature would break Rails users on Ruby 3.
+*   **`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.
 
 Development
 -----------
 
-The testing setup uses RSpec, WebMock for network request mocking, and Timecop for robust time-dependent testing (like expiration checks).
-
-To run the full suite:
+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.
 
 ```bash
 $ bundle install
+$ bundle exec rake            # specs + rubocop
 $ bundle exec rspec
+$ BUNDLE_GEMFILE=gemfiles/rack_2.gemfile bundle exec rspec   # the Rack 2 leg
 ```
 
 License
 -------
 
-The gem is available as open source under the terms of the [MIT License](https://www.google.com/search?q=LICENSE.txt).
+MIT — see [LICENSE.md](LICENSE.md).

data/lib/rack-jwt-verifier.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Bundler auto-requires a gem by its name, so `gem "rack-jwt-verifier"` looks
+# for this file. The real entry point lives under the underscore name.
+require_relative "rack_jwt_verifier"

data/lib/rack_jwt_verifier/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module RackJwtVerifier
+  # 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
+end

data/lib/rack_jwt_verifier/in_process_cache.rb

@@ -8,9 +8,15 @@ module RackJwtVerifier
     # The cache lifespan in seconds (5 minutes)
     DEFAULT_EXPIRY = 300
 
-    def initialize
+    # Expiry is measured on the monotonic clock, so a wall-clock jump (NTP
+    # correction, DST) cannot extend or cut short an entry's life.
+    MONOTONIC_CLOCK = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+    # @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
     end
 
     # Reads the value for a given key. Automatically checks for expiry.
@@ -22,10 +28,10 @@ module RackJwtVerifier
         return nil unless entry
 
         value, expires_at = entry
-        
+
         # Check if the entry is expired
-        return nil if Time.now.to_i >= expires_at
-        
+        return nil if @clock.call >= expires_at
+
         value
       end
     end
@@ -38,8 +44,7 @@ module RackJwtVerifier
     def write(key, value, options = {})
       @lock.synchronize do
         expiry = options[:expires_in] || DEFAULT_EXPIRY
-        expires_at = Time.now.to_i + expiry
-        @store[key] = [value, expires_at]
+        @store[key] = [value, @clock.call + expiry]
         value
       end
     end
@@ -49,7 +54,8 @@ module RackJwtVerifier
     # @return [Object, nil] The deleted entry value or nil.
     def delete(key)
       @lock.synchronize do
-        @store.delete(key)
+        entry = @store.delete(key)
+        entry&.first
       end
     end
   end

data/lib/rack_jwt_verifier/jwt_helper.rb

@@ -3,53 +3,44 @@
 require 'jwt'
 require 'openssl'
 
-# A helper class for handling JWT creation and verification using RSA keys (RS256).
-# This is typically used by the application or a separate service to *create* tokens.
 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.
   class JwtHelper
-    # The private_key must be an OpenSSL::PKey::RSA object (or similar).
+    ALGORITHM = 'RS256'
+
     attr_reader :private_key, :public_key
 
-    # Initializes the helper with the RSA Private Key used for signing.
-    #
-    # @param private_key_pem [String] The PEM string of the RSA Private Key.
+    # @param private_key_pem [String, OpenSSL::PKey::RSA] The RSA private key used for signing.
     def initialize(private_key_pem)
-      # !! IMPORTANT !!
-      # This key signs the tokens.
-      @private_key = OpenSSL::PKey::RSA.new(private_key_pem)
+      @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
 
-    # Encodes a payload into a JWT.
+    # Encodes a payload into a JWT, adding `iat` and `exp`.
     #
-    # @param payload [Hash] The data to be encoded in the JWT (e.g., user ID, roles).
-    # @param expires_in [Integer] Time in seconds until the token expires (default: 1 hour).
+    # @param payload [Hash] Claims (string or symbol keys; an explicit `exp` in the payload wins).
+    # @param expires_in [Integer] Seconds until the token expires (default: 1 hour).
     # @return [String] The signed JWT string.
     def encode(payload, expires_in = 3600)
-      # Set standard expiration time (exp) and issued-at time (iat) claims
-      time = Time.now.to_i
-      payload_with_claims = payload.merge({
-        iat: time,
-        exp: time + expires_in
-      })
-
-      JWT.encode(payload_with_claims, @private_key, 'RS256')
+      now = Time.now.to_i
+      # Normalise to string keys first so a caller's 'exp' and our :exp cannot
+      # both end up in the JSON as duplicate "exp" members.
+      claims = { 'iat' => now, 'exp' => now + expires_in }.merge(payload.transform_keys(&:to_s))
+      JWT.encode(claims, @private_key, ALGORITHM)
     end
 
-    # Decodes and verifies a JWT using the public key.
-    #
-    # NOTE: This method is used primarily for self-testing in the application
-    # but the primary verification logic for the middleware is in the Verifier class.
+    # Decodes and verifies a JWT with the public key. Meant for self-checks;
+    # the middleware's verification lives in Verifier.
     #
     # @param token [String] The JWT string to decode.
+    # @param options [Hash] Extra options for JWT.decode (leeway, iss, verify_iss, ...).
     # @return [Hash] The decoded payload if verification is successful.
-    # @raise [JWT::VerificationError, JWT::DecodeError] If the token is invalid or expired.
-    def decode(token)
-      # Decodes using the public key, performs signature verification (true),
-      # and restricts the algorithm to 'RS256'.
-      decoded = JWT.decode(token, @public_key, true, { algorithm: 'RS256' })
-      # Returns only the payload (the first element of the array).
-      decoded.first
+    # @raise [JWT::DecodeError] If the token is invalid or expired.
+    def decode(token, options = {})
+      payload, _header = JWT.decode(token, @public_key, true, { algorithm: ALGORITHM }.merge(options))
+      payload
     end
   end
 end