jwt_auth_client 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a68ca9dd3459f00b139bd71b8a52a5a24112fab256c0aadeebb594f4704159e8
-  data.tar.gz: 8a9dfabd1723a404c01fa213fd2589abf8f6f5a4500a7a42f25ce90f5d1938ee
+  metadata.gz: c01a3a1fcd5ad0c6e46b7802a105e2c129a9705a0004358ab1c4970076b3dde7
+  data.tar.gz: 73b684a98f9f583c4223d118e73c094366f6a5bb08e90293a981cc80fe2b1f6e
 SHA512:
-  metadata.gz: 3014ed4df9591c1a3115380a78c222df936ca0e81c46cb22fa1721308f582e563049eaa6fe9a602505b90daf38a792cd60f0c5ab73883ba140cf4332cedac407
-  data.tar.gz: c59efce14020d02c89c77c7ac18fed487f618862e4150f93d63c7e6d41f9bbb9c3dc46724360f756e758d0a2455836c3811753b1640c7fca00410549c99716bd
+  metadata.gz: bd7348b5b0377f94aedc6dbd87651d2d1b02b1c6cb88e228dcedd20515db829ea22ea285174f51a73135b493420fe0215d43de97f21f006374b56b9216ec5475
+  data.tar.gz: b8c916e4122f642a82630dad2ed0c3f1945556230494e9ad1ff1f098e07e5afebbd47215ec3fba5021f2d61644c416ac35684baa97c3d30dcfa909094c2ed054

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-09-13
+
+Security-hardening release. Several changes are **breaking**; see the upgrade notes below.
+
+### Security
+- **No more default secret.** `shared_secret` now defaults to `ENV["JWT_SERVICE_SECRET"]` with no
+  literal fallback. A missing, empty or too-short secret raises `ConfigurationError` at
+  `JwtAuthClient.configure` time (was: silently signing with `"development_secret"`).
+- **Algorithm allow-list.** Only `HS256`, `HS384` and `HS512` are accepted; `none` and anything else
+  raise `ConfigurationError` (was: passed straight to `JWT.encode`, so `none` produced unsigned tokens).
+- **Minimum key length** enforced per RFC 7518 §3.2 (32/48/64 bytes for HS256/384/512).
+- `issuer` is now required (was: silently `"main_sso_app"`).
+- Tokens now carry an `nbf` claim (= `iat`).
+- `user_id` (the `sub` claim) must be present; `nil`/empty raises `ArgumentError` (was: `"sub": null`).
+- Custom claims can never override the registered claims `iss`, `sub`, `iat`, `nbf`, `exp`, `jti`.
+
+### Fixed
+- **Expired tokens on long-lived connections.** The JWT was minted once when the connection was built
+  and memoised, so any connection held longer than `default_expiry_seconds` sent expired tokens. The
+  token is now issued lazily per request (via Faraday's callable authorization header).
+- `scopes: nil` raised `NoMethodError`; it is now treated as no scopes.
+- JSON response parsing failed with `Faraday::ParsingError` when the `json` gem >= 3.0 was installed
+  (Faraday passes a positional options hash that `json` 3 rejects). A small decoder shim forwards
+  options as keywords and works with both `json` 2.x and 3.x.
+- `raise_error` now runs after JSON parsing, so `Faraday::Error#response[:body]` contains the decoded
+  body instead of a raw string.
+- Documentation: `HttpClient.call` returns a `Faraday::Connection`, not a response; the README's
+  "base_url only" example (which raised `ArgumentError`) has been corrected.
+
+### Added
+- `JwtAuthClient::Issuable` mixin: `include` it in a model, define `#jwt_claims`, and call
+  `#to_jwt(expiry_seconds: nil, target_service: nil, scopes: [])`.
+- `TokenIssuer.call` accepts `claims:` (extra custom claims) and `expiry_seconds:` (per-call override).
+- Configurable HTTP timeouts: `open_timeout` (2 s), `read_timeout` (5 s), `write_timeout` (5 s).
+- Opt-in retries via `retry_options` (requires the `faraday-retry` gem).
+- Opt-in token reuse via `token_reuse_seconds` (default `0` = fresh `jti` per request); tokens are
+  always re-issued within 30 s of expiry.
+- `HttpClient.call` yields the Faraday connection so callers can add middleware.
+- Error hierarchy: `JwtAuthClient::Error` > `ConfigurationError` > `UnknownServiceError`, and `TokenError`.
+- `Configuration#validate!` and `JwtAuthClient.reset_configuration!` (handy in test suites).
+- `required_ruby_version >= 3.1`, CI matrix on Ruby 3.1–3.4, `rubygems_mfa_required` metadata, LICENSE file.
+
+### Changed
+- **`BillingClient` removed from the gem** and moved to `examples/billing_client.rb`. It hard-coded an
+  application-specific service into a generic library; copy the example into your app instead.
+- `Configuration#base_url_for` raises `UnknownServiceError` (a `ConfigurationError`) instead of `ArgumentError`.
+- `activesupport` is no longer a runtime dependency (it was required but never used).
+- Development dependencies are declared in the gemspec only; `Gemfile.lock` and built `.gem` files
+  are no longer tracked.
+
+### Upgrade notes (0.1.x → 0.2.0)
+1. Set a real secret of at least 32 bytes (`openssl rand -hex 32`) in `JWT_SERVICE_SECRET` or
+   `config.shared_secret`, and set `config.issuer`. Boot will fail loudly until you do.
+2. If you rescued `ArgumentError` around `HttpClient.call` for unknown services, rescue
+   `JwtAuthClient::UnknownServiceError` (or `JwtAuthClient::Error`) instead.
+3. If you used `JwtAuthClient::BillingClient`, copy `examples/billing_client.rb` into your application.
+4. Verifiers should now expect `nbf` and can apply a small leeway (e.g. 30 s) for clock skew.
+
+## [0.1.0] - 2025-10-25
+
+- Initial release: `TokenIssuer`, `Configuration`, `HttpClient`, `BillingClient`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniele Frisanco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,116 +1,205 @@
-JwtAuthClient
-=============
+# JwtAuthClient
 
-A minimal, robust Ruby client for internal service-to-service authentication using JSON Web Tokens (JWTs).
+A small, hardened Ruby client for issuing short-lived JWTs and sending them as `Bearer` tokens
+between your own services.
 
-This gem simplifies the process of creating, signing, and injecting short-lived JWTs into outgoing HTTP requests, ensuring secure communication between your internal microservices.
+- **Token issuing** — `iss`, `sub`, `iat`, `nbf`, `exp`, `jti`, plus optional `aud`, `scopes` and
+  custom claims. HMAC only (`HS256`/`HS384`/`HS512`) with enforced key length; `none` is rejected.
+- **Faraday client** — a connection that mints a fresh token per request, with timeouts,
+  JSON encode/decode, error raising and opt-in retries.
+- **`Issuable` mixin** — give a model a `#to_jwt` method (e.g. an SSO hub handing an identity
+  token to a client app).
+- **Fails at boot, not at runtime** — misconfiguration raises `JwtAuthClient::ConfigurationError`
+  from `JwtAuthClient.configure`.
 
-Features
---------
+Requires Ruby >= 3.1. Pairs with a verifier such as `rack_jwt_verifier` on the receiving side.
 
-*   **Token Generation:** Creates industry-standard JWTs with required claims (`iss`, `sub`, `iat`, `exp`, `jti`).
-    
-*   **Service-Specific Scopes:** Allows injection of custom claims (`aud`, `scopes`) to authorize access for specific target services.
-    
-*   **Faraday Integration:** Wraps around Faraday to automatically attach the generated JWT as a `Bearer` token in the `Authorization` header.
-    
-*   **High-Level Clients:** Supports creating specialized clients (e.g., `BillingClient`) for clean API consumption.
-    
-
-Installation
-------------
-
-Add this line to your application's Gemfile:
+## Installation
 
 ```ruby
-gem 'jwt_auth_client', '~> 0.1.0'
+gem "jwt_auth_client", "~> 0.2"
+# optional, only if you enable retries:
+# gem "faraday-retry"
 ```
 
-And then execute:
-
-```bash
-$ bundle install
-```
+## Configuration
 
-Configuration
--------------
+Configure once at boot (e.g. `config/initializers/jwt_auth_client.rb`). The block is validated
+when it returns, so a bad configuration fails the boot.
 
-You must configure the client once in your application's initialization file (e.g., `config/initializers/jwt_auth_client.rb` in a Rails app).
+```ruby
+JwtAuthClient.configure do |config|
+  # Required. >= 32 bytes for HS256 (48 for HS384, 64 for HS512). Generate with:
+  #   openssl rand -hex 32
+  # Defaults to ENV["JWT_SERVICE_SECRET"]; there is deliberately NO fallback value.
+  config.shared_secret = ENV.fetch("JWT_SERVICE_SECRET")
 
-Setting | Type | Description |
- | - | - | - |
- | **shared_secret** | String | The cryptographic key known to all services (used for signing and verification). **CRITICAL.**
- | **algorithm** | String | The JWT signing algorithm (e.g., '`HS256`').
- | **default_expiry_seconds** | Integer | Default lifespan for the tokens (e.g., `300` seconds = 5 minutes).
- | **issuer** | String | The identifier of the application issuing the token (e.g., '`main_sso_app`').
- | **service_urls** | Hash | Map of internal service keys to their base URLs.
+  # Required. Identifies this application in the `iss` claim.
+  config.issuer = "main_app_sso"
 
-```ruby
-# config/initializers/jwt_auth_client.rb
+  config.algorithm = "HS256"           # HS256 | HS384 | HS512  (default HS256)
+  config.default_expiry_seconds = 300  # token lifetime (default 300)
 
-JwtAuthClient.configure do |config|
-  # Load the secret from an environment variable!
-  config.shared_secret = ENV.fetch('JWT_SERVICE_SECRET') { 'a_fallback_secret_for_dev' }
-  config.algorithm = 'HS256'
-  config.default_expiry_seconds = 300 # 5 minutes
-  config.issuer = 'main_app_sso'
-  # Configure base URLs for your internal services
+  # Service name => base URL, used by HttpClient. Always use https:// in production.
   config.service_urls = {
-    billing_api: 'http://billing-service.internal',
-    user_data_api: 'http://user-service.internal'
+    billing_api:   "https://billing.internal",
+    user_data_api: "https://users.internal"
   }
+
+  # HTTP timeouts in seconds (defaults: 2 / 5 / 5)
+  config.open_timeout  = 2
+  config.read_timeout  = 5
+  config.write_timeout = 5
+
+  # Optional: reuse a token for up to N seconds instead of signing one per request.
+  # 0 (default) = fresh token and fresh `jti` per request, best for replay detection.
+  config.token_reuse_seconds = 0
+
+  # Optional: retries (needs the faraday-retry gem). nil (default) = no retries.
+  # config.retry_options = { max: 2, interval: 0.1, backoff_factor: 2, retry_statuses: [502, 503, 504] }
 end
 ```
 
-Usage
------
+| Setting | Type | Default | Notes |
+|---|---|---|---|
+| `shared_secret` | String | `ENV["JWT_SERVICE_SECRET"]` | **Required.** Min 32/48/64 bytes for HS256/384/512. |
+| `issuer` | String | — | **Required.** The `iss` claim. |
+| `algorithm` | String | `"HS256"` | One of `HS256`, `HS384`, `HS512`. |
+| `default_expiry_seconds` | Integer | `300` | Token lifetime. |
+| `service_urls` | Hash | `{}` | `{ service_name: "https://..." }` |
+| `open_timeout` / `read_timeout` / `write_timeout` | Numeric | `2` / `5` / `5` | Seconds. |
+| `token_reuse_seconds` | Integer | `0` | Reuse window for a minted token; always re-issued within 30 s of expiry. |
+| `retry_options` | Hash / nil | `nil` | Passed to Faraday's `:retry` middleware. |
 
-### 1\. High-Level Service Client (Recommended)
+## Usage
 
-Use the built-in or custom client wrappers for clean dependency management. These clients automatically use the configured `target_service`.
+### Authenticated HTTP client
+
+`HttpClient.call` returns a `Faraday::Connection`. Build it once per service and keep it —
+the token is issued lazily on each request, so a long-lived connection never sends an expired token.
 
 ```ruby
-# The BillingClient is a specialized wrapper around HttpClient
-# it defaults target_service to :billing_api 
-client = JwtAuthClient::BillingClient.call(
-  user_id: 'user-id-456',
-  scopes: ['read:invoices', 'write:payments']
+BILLING = JwtAuthClient::HttpClient.call(
+  user_id: "service-account-etl",   # `sub` claim
+  target_service: :billing_api,     # `aud` claim; must be a key in service_urls
+  scopes: ["read:invoices"]         # `scopes` claim
 )
 
-# client is a Faraday connection object
-response = client.get('/v1/invoices/latest')
-if response.success?
-  puts "Invoices: #{response.body}"
-end
+response = BILLING.get("/v1/invoices/latest")   # => Faraday::Response, body already parsed
+response.body["total"]
+
+BILLING.post("/v1/payments", { amount: 10 })    # body encoded as JSON automatically
 ```
 
-### 2\. General HTTP Client (Advanced)
+4xx/5xx responses raise `Faraday::ClientError` / `Faraday::ServerError` with the parsed body available
+as `error.response[:body]`.
 
-If you need dynamic control over the target service, you can use the base `HttpClient`.
+Override *where* the request goes (a canary host, a test server) without changing *who the token
+is for* — `target_service` is always required so every token carries an `aud`:
 
 ```ruby
-client = JwtAuthClient::HttpClient.call(
-  user_id: 'service-account-etl',
-  target_service: :user_data_api, # Must be a key defined in service_urls
-  scopes: ['read:all_users']
-)
-# Override the base URL dynamically if needed
-override_client = JwtAuthClient::HttpClient.call(
-  user_id: 'guest',
-  base_url: 'http://temporary-api.test' # Overrides configured service_urls
+canary = JwtAuthClient::HttpClient.call(
+  user_id: "etl", target_service: :billing_api, base_url: "https://billing-canary.internal"
 )
 ```
 
-### 3\. Token Generation Only
+Add your own middleware (logging, instrumentation) with a block; it runs before the adapter is set:
+
+```ruby
+client = JwtAuthClient::HttpClient.call(user_id: "etl", target_service: :billing_api) do |conn|
+  conn.response :logger, Rails.logger, headers: false
+end
+```
+
+A service-specific wrapper keeps call sites short — see [`examples/billing_client.rb`](examples/billing_client.rb):
+
+```ruby
+class BillingClient < JwtAuthClient::HttpClient
+  def self.call(user_id:, scopes: [], base_url: nil, &block)
+    super(user_id: user_id, target_service: :billing_api, scopes: scopes, base_url: base_url, &block)
+  end
+end
+```
+
+### Token only
 
-If you only need the raw JWT string for non-HTTP purposes (e.g., message queues), use the `TokenIssuer`.
+For non-HTTP transports (message queues, redirects, ...):
 
 ```ruby
 token = JwtAuthClient::TokenIssuer.call(
-  user_id: 'system-job-id',
-  target_service: 'data_pipeline',
-  scopes: ['process:orders']
+  user_id: "system-job-id",
+  target_service: :data_pipeline,     # optional `aud`
+  scopes: ["process:orders"],         # optional
+  claims: { tenant: "acme" },         # optional custom claims (registered claims are protected)
+  expiry_seconds: 60                  # optional, overrides default_expiry_seconds
 )
-# token will be the signed JWT string
-# puts token
-```
+```
+
+### `Issuable` — tokens from a model
+
+```ruby
+class User < ApplicationRecord
+  include JwtAuthClient::Issuable
+
+  def jwt_claims
+    { user_id: sso_id, email: email }
+  end
+end
+
+user.to_jwt                                     # sub = jwt_claims[:user_id] (falls back to #id)
+user.to_jwt(expiry_seconds: 60, target_service: :client_app)
+```
+
+Override `#jwt_subject` to choose a different `sub`.
+
+### Token payload
+
+```json
+{
+  "iss": "main_app_sso",
+  "sub": "service-account-etl",
+  "aud": "billing_api",
+  "scopes": ["read:invoices"],
+  "iat": 1700000000,
+  "nbf": 1700000000,
+  "exp": 1700000300,
+  "jti": "9c1a3f0e-..."
+}
+```
+
+## Errors
+
+| Class | Raised when |
+|---|---|
+| `JwtAuthClient::ConfigurationError` | Configuration is missing/invalid (secret, algorithm, issuer, timeouts, ...). |
+| `JwtAuthClient::UnknownServiceError` (< `ConfigurationError`) | `target_service` has no entry in `service_urls` and no `base_url` was given. |
+| `JwtAuthClient::TokenError` | The `jwt` gem failed to sign the payload. |
+| `ArgumentError` | Bad call arguments (`user_id`/`target_service` blank, invalid `expiry_seconds`, ...). |
+
+All gem errors inherit from `JwtAuthClient::Error`.
+
+## Security notes
+
+- **Transport:** bearer tokens are credentials. Only send them over TLS (or an mTLS service mesh);
+  never set `ssl: { verify: false }` on the connection.
+- **Secret handling:** load the secret from the environment or a secret manager, rotate it, and never
+  commit it. Every service holding the secret can mint tokens for every `aud`, so keep the set of
+  holders small. Asymmetric signing (RS256/ES256, private key on the issuer only) is planned.
+- **Verifier side:** verify the signature *and* `iss`, `aud`, `exp`, `nbf`; allow a small leeway
+  (e.g. 30 s) for clock skew; optionally track `jti` to detect replays.
+- **Lifetime:** keep `default_expiry_seconds` short (minutes). Use `expiry_seconds:` for one-off tokens
+  that should live even less.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rake build   # builds pkg/jwt_auth_client-x.y.z.gem
+```
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes and upgrade steps.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/lib/jwt_auth_client/configuration.rb

@@ -1,48 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
 module JwtAuthClient
   class Configuration
-    # The cryptographic key known to all internal services
+    # Only HMAC algorithms are supported until asymmetric signing lands.
+    # "none" is deliberately absent: it produces unsigned tokens.
+    SUPPORTED_ALGORITHMS = %w[HS256 HS384 HS512].freeze
+
+    # RFC 7518 §3.2: an HMAC key must be at least as long as the hash output.
+    MIN_SECRET_BYTES = { "HS256" => 32, "HS384" => 48, "HS512" => 64 }.freeze
+
+    # The cryptographic key shared with the verifying services. Required.
+    # Defaults to ENV["JWT_SERVICE_SECRET"]; there is intentionally no literal fallback.
     attr_accessor :shared_secret
-    
-    # The algorithm used for signing (e.g., 'HS256')
+
+    # The signing algorithm; one of SUPPORTED_ALGORITHMS.
     attr_accessor :algorithm
-    
-    # Default token validity period in seconds (e.g., 300 seconds = 5 minutes)
+
+    # Token validity period in seconds.
     attr_accessor :default_expiry_seconds
-    
-    # The issuer of the token (conventionally the main application ID)
+
+    # The `iss` claim identifying the issuing application. Required.
     attr_accessor :issuer
 
-    # The mapping of target service names (Symbol) to their base URLs (String)
+    # Mapping of target service names (Symbol) to base URLs (String).
     attr_accessor :service_urls
 
+    # HTTP timeouts (seconds) applied to every HttpClient connection.
+    attr_accessor :open_timeout, :read_timeout, :write_timeout
+
+    # How long (seconds) an HttpClient may reuse a token before issuing a new
+    # one. 0 (default) issues a fresh token — and a fresh `jti` — per request,
+    # which is best for replay detection on the verifier side. Raise it on hot
+    # paths to skip the per-request signature. Tokens are always re-issued
+    # within HttpClient::REFRESH_MARGIN_SECONDS of expiry regardless.
+    attr_accessor :token_reuse_seconds
+
+    # Options for Faraday's :retry middleware (requires the faraday-retry gem),
+    # e.g. { max: 2, interval: 0.1, backoff_factor: 2 }. nil disables retries.
+    attr_accessor :retry_options
+
     def initialize
-      @algorithm = 'HS256'
-      @default_expiry_seconds = 300 
-      @issuer = 'main_sso_app'
-      # Added a default value for local testing if ENV variable is missing
-      @shared_secret = ENV['JWT_SERVICE_SECRET'] || 'development_secret' 
+      @shared_secret = ENV.fetch("JWT_SERVICE_SECRET", nil)
+      @algorithm = "HS256"
+      @default_expiry_seconds = 300
+      @issuer = nil
       @service_urls = {}
+      @open_timeout = 2
+      @read_timeout = 5
+      @write_timeout = 5
+      @token_reuse_seconds = 0
+      @retry_options = nil
     end
 
     # Retrieves the base URL for a given target service.
-    # The HttpClient relies on this method to determine where to send the request.
     #
-    # @param target_service [Symbol, String] The name of the service (e.g., :billing_api).
-    # @return [String] The base URL.
-    # @raise [ArgumentError] If the service is not configured.
+    # @param target_service [Symbol, String]
+    # @return [String]
+    # @raise [UnknownServiceError] if the service is not configured.
     def base_url_for(target_service)
-      url = service_urls[target_service.to_sym]
-      raise ArgumentError, "Base URL for service '#{target_service}' is not configured in JwtAuthClient.service_urls." unless url
-      url
+      key = target_service.to_s
+      raise UnknownServiceError, "target_service must not be blank" if key.empty?
+
+      service_urls[key.to_sym] or
+        raise UnknownServiceError,
+              "Base URL for service '#{key}' is not configured in JwtAuthClient.configuration.service_urls."
     end
-  end
 
-  # Class method to expose the configuration object and the configuration block
-  def self.configuration
-    @configuration ||= Configuration.new
+    # Validates the configuration, raising on the first problem found.
+    #
+    # @return [self]
+    # @raise [ConfigurationError]
+    def validate!
+      validate_algorithm!
+      validate_shared_secret!
+      validate_issuer!
+      validate_expiry!
+      validate_service_urls!
+      validate_http_options!
+      self
+    end
+
+    private
+
+    def validate_algorithm!
+      return if SUPPORTED_ALGORITHMS.include?(algorithm)
+
+      raise ConfigurationError,
+            "algorithm must be one of #{SUPPORTED_ALGORITHMS.join(', ')} (got #{algorithm.inspect})"
+    end
+
+    def validate_shared_secret!
+      unless shared_secret.is_a?(String) && !shared_secret.empty?
+        raise ConfigurationError,
+              "shared_secret is required (set JwtAuthClient.configuration.shared_secret or JWT_SERVICE_SECRET)"
+      end
+
+      min = MIN_SECRET_BYTES.fetch(algorithm)
+      return if shared_secret.bytesize >= min
+
+      raise ConfigurationError,
+            "shared_secret must be at least #{min} bytes for #{algorithm} (got #{shared_secret.bytesize})"
+    end
+
+    def validate_issuer!
+      return if issuer.is_a?(String) && !issuer.empty?
+
+      raise ConfigurationError, "issuer is required"
+    end
+
+    def validate_expiry!
+      return if default_expiry_seconds.is_a?(Integer) && default_expiry_seconds.positive?
+
+      raise ConfigurationError, "default_expiry_seconds must be a positive Integer"
+    end
+
+    def validate_service_urls!
+      return if service_urls.is_a?(Hash)
+
+      raise ConfigurationError, "service_urls must be a Hash of service name => base URL"
+    end
+
+    def validate_http_options!
+      { open_timeout: open_timeout, read_timeout: read_timeout, write_timeout: write_timeout }.each do |name, value|
+        next if value.is_a?(Numeric) && value.positive?
+
+        raise ConfigurationError, "#{name} must be a positive number of seconds"
+      end
+
+      unless token_reuse_seconds.is_a?(Integer) && token_reuse_seconds >= 0
+        raise ConfigurationError, "token_reuse_seconds must be a non-negative Integer"
+      end
+
+      return if retry_options.nil? || retry_options.is_a?(Hash)
+
+      raise ConfigurationError, "retry_options must be nil or a Hash"
+    end
   end
 
-  def self.configure
-    yield(configuration)
+  class << self
+    # @return [Configuration] the global configuration.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the global configuration and validates it afterwards, so
+    # misconfiguration surfaces at boot rather than on the first request.
+    #
+    # @yieldparam config [Configuration]
+    # @return [Configuration]
+    # @raise [ConfigurationError]
+    def configure
+      yield(configuration)
+      configuration.validate!
+    end
+
+    # Discards the global configuration. Intended for test suites.
+    def reset_configuration!
+      @configuration = nil
+    end
   end
 end

data/lib/jwt_auth_client/errors.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module JwtAuthClient
+  # Base class for all errors raised by this gem.
+  class Error < StandardError; end
+
+  # Raised when the global configuration is missing or invalid.
+  class ConfigurationError < Error; end
+
+  # Raised when a target service has no base URL configured.
+  class UnknownServiceError < ConfigurationError; end
+
+  # Raised when a token cannot be issued (wraps errors from the jwt gem).
+  class TokenError < Error; end
+end