verikloak 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d16d7e5f8602a8484837e30752c190825e5f83b3ad9cb6b90d5e827b910b0daa
+  data.tar.gz: 135a5eadb529463081cfcf414d48ce13328fecf13b95963eff010a211f541c8f
+SHA512:
+  metadata.gz: 5d476daca7174cb474771005affced764ad2093d633809c4206d54e5d0467b45e903bf998cbbca5cb9e25802e29cfaae20dd04d2820d53fc59c844af5cd886c7
+  data.tar.gz: f66dba005f8ad96afb0de678ab65e76a99d4f08dbcc98d4bc7468a6c5183781b10f10c4916a24c28ab7e8b459e6f252dbac01fc536f5d0f99e116a38d7c24485

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# 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).
+
+---
+
+## [0.1.1] - 2025-08-24
+
+### Changed
+
+- Updated dependency constraints in gemspec (`json` ~> 2.6, `jwt` ~> 2.7) for better compatibility control
+- Updated README badges (Gem version, Ruby version, downloads)
+
+---
+
+## [0.1.0] - 2025-08-17
+
+### Added
+
+- Initial release of `verikloak`
+- Rack middleware for verifying JWT access tokens from Keycloak
+- Support for OpenID Connect Discovery (`.well-known/openid-configuration`)
+  - Handles up to 3 HTTP redirects and resolves relative `Location` headers
+- JWKS fetching with in-memory caching and ETag validation
+- RS256 JWT verification with `kid` matching
+- Claim validation: `aud`, `iss`, `exp`, `nbf`
+- Configurable via `discovery_url`, `audience`, and `skip_paths` options
+  - `skip_paths` supports `/`, literal paths, and `*` wildcards (e.g. `/public/*`, `/rails/*`)
+- Environment keys set by middleware:
+  - `env["verikloak.user"]` for decoded claims
+  - `env["verikloak.token"]` for the raw Bearer token
+- Comprehensive RSpec test suite:
+  - `TokenDecoder` unit tests
+  - `Discovery` behavior (redirects, invalid JSON, required fields)
+  - `JwksCache` behavior (ETag/304, parse/validation errors)
+  - Rack middleware integration tests (401/503 mapping, header parsing)
+- Docker-based development and CI-ready setup
+- RuboCop static analysis configuration
+- Structured error handling & responses:
+  - Token/auth errors → **401 Unauthorized** with `WWW-Authenticate` header (RFC 6750)
+  - Discovery/JWKS errors → **503 Service Unavailable**
+  - Structured error codes: `invalid_token`, `expired_token`, `not_yet_valid`,
+    `invalid_issuer`, `invalid_audience`, `unsupported_algorithm`,
+    `jwks_fetch_failed`, `jwks_parse_failed`, `jwks_cache_miss`,
+    `discovery_metadata_fetch_failed`, `discovery_metadata_invalid`,
+    `discovery_redirect_error`

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2025 taiyaky
+
+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

@@ -0,0 +1,324 @@
+# Verikloak
+
+[![CI](https://github.com/taiyaky/verikloak/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/taiyaky/verikloak/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/verikloak)](https://rubygems.org/gems/verikloak)
+![Ruby Version](https://img.shields.io/gem/rt/ruby/verikloak)
+[![Downloads](https://img.shields.io/gem/dt/verikloak)](https://rubygems.org/gems/verikloak)
+
+A lightweight Rack middleware for verifying Keycloak JWT access tokens via OpenID Connect.
+
+Verikloak is a plug-and-play solution for Ruby (especially Rails API) apps that need to validate incoming `Bearer` tokens issued by Keycloak. It uses OpenID Connect Discovery and JWKS to fetch the public keys and verify JWT signatures securely.
+
+---
+
+## Features
+
+- OpenID Connect Discovery (`.well-known/openid-configuration`)
+- JWKs auto-fetch and in-memory caching with ETag support
+- RS256 JWT verification using `kid`
+- `aud`, `iss`, `exp`, `nbf` claim validation
+- Rails/Rack middleware support
+- Faraday-based customizable HTTP layer
+
+---
+
+## Installation
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem "verikloak"
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+---
+
+## Usage
+
+### Rails (API mode)
+
+Add the middleware in `config/application.rb`:
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: "https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration",
+  audience: "your-client-id",
+  skip_paths: ['/skip_path']
+```
+
+#### Handling Authentication Failures
+
+By default, invalid or missing tokens will raise a `Verikloak::Errors::InvalidToken` error.  
+In a Rails app, you can rescue this globally and return a consistent JSON response:
+
+```ruby
+class ApplicationController < ActionController::API
+  rescue_from Verikloak::Errors::InvalidToken do |e|
+    render json: { error: e.message }, status: :unauthorized
+  end
+end
+```
+
+This ensures clients always receive a structured `401 Unauthorized` response.
+
+---
+
+#### Recommended: use environment variables in production
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV.fetch("DISCOVERY_URL"),
+  audience: ENV.fetch("CLIENT_ID"),
+  skip_paths: ['/', '/health', '/public/*', '/rails/*']
+```
+#### In production, set these variables in your environment for security and flexibility.
+
+This makes the configuration secure and flexible across environments.
+
+```ruby
+request.env["verikloak.user"]  # => JWT claims hash
+request.env["verikloak.token"] # => Raw JWT string
+```
+---
+### Accessing claims in controllers
+
+Once the middleware is enabled, Verikloak adds the decoded token and raw JWT to the Rack environment.  
+You can access them in any Rails controller:
+
+```ruby
+class Api::V1::NotesController < ApplicationController
+  def index
+    user_claims = request.env["verikloak.user"]    # Hash of decoded Keycloak JWT claims
+    token       = request.env["verikloak.token"]   # Raw JWT token string
+    
+    # Example: use claims for authorization or logging
+    render json: { sub: user_claims["sub"], email: user_claims["email"] }
+  end
+end
+```
+---
+### Standalone Rack app
+
+```ruby
+# config.ru example for a standalone Rack app
+require "verikloak"
+
+use Verikloak::Middleware,
+  discovery_url: "https://keycloak.example.com/realms/myrealm/.well-known/openid-configuration",
+  audience: "my-client-id"
+
+run ->(env) {
+  user = env["verikloak.user"] # Decoded JWT claims hash (if token is valid)
+  [200, { "Content-Type" => "application/json" }, [user.to_json]]
+}
+```
+---
+
+## How It Works
+
+1. Extracts the `Authorization: Bearer <token>` header
+2. Fetches the OIDC discovery document (only once or when expired)
+3. Downloads JWKS public keys from the provided `jwks_uri`
+4. Matches the `kid` from JWT header to select the right JWK
+5. Decodes and verifies the JWT using `RS256`
+6. Validates the following claims:
+   - `aud` (audience)
+   - `iss` (issuer)
+   - `exp` (expiration)
+   - `nbf` (not before)
+7. Makes the decoded payload available in `env["verikloak.user"]`
+
+---
+
+## Error Responses
+
+Verikloak returns JSON error responses in a consistent format with structured error codes. The HTTP status code reflects the nature of the error: 401 for client-side authentication issues, 503 for server-side discovery/JWKS errors, and 500 for unexpected internal errors.
+
+### Common HTTP Responses
+
+- `401 Unauthorized`: The access token is missing, invalid, expired, or otherwise not valid.
+- `503 Service Unavailable`: Discovery or JWKS fetch/parsing failed (server-side issue).
+- `500 Internal Server Error`: An unexpected error occurred.
+
+### Representative Examples
+
+```json
+{
+  "error": "invalid_token",
+  "message": "The access token is missing or invalid"
+}
+```
+
+```json
+{
+  "error": "expired_token",
+  "message": "The access token has expired"
+}
+```
+
+```json
+{
+  "error": "jwks_fetch_failed",
+  "message": "Failed to fetch JWKS keys"
+}
+```
+
+```json
+{
+  "error": "jwks_parse_failed",
+  "message": "Failed to parse JWKS keys"
+}
+```
+
+```json
+{
+  "error": "discovery_metadata_fetch_failed",
+  "message": "Failed to fetch OIDC discovery document"
+}
+```
+
+```json
+{
+  "error": "discovery_metadata_invalid",
+  "message": "Failed to parse OIDC discovery document"
+}
+```
+
+### Error Types
+
+| Error Code                 | HTTP Status               | Description                                                                                   |
+|----------------------------|---------------------------|-----------------------------------------------------------------------------------------------|
+| `invalid_token`            | 401 Unauthorized          | The token is missing, malformed, or invalid                                                  |
+| `expired_token`            | 401 Unauthorized          | The token has expired                                                                        |
+| `missing_authorization_header` | 401 Unauthorized      | The `Authorization` header is missing                                                        |
+| `invalid_authorization_header` | 401 Unauthorized      | The `Authorization` header format is invalid                                                 |
+| `unsupported_algorithm`    | 401 Unauthorized          | The token’s signing algorithm is not supported                                               |
+| `invalid_signature`        | 401 Unauthorized          | The token signature could not be verified                                                    |
+| `invalid_issuer`           | 401 Unauthorized          | Invalid `iss` claim                                                                          |
+| `invalid_audience`         | 401 Unauthorized          | Invalid `aud` claim                                                                          |
+| `not_yet_valid`            | 401 Unauthorized          | The token is not yet valid (`nbf` in the future)                                             |
+| `jwks_fetch_failed`        | 503 Service Unavailable   | Failed to fetch JWKS keys                                                                    |
+| `jwks_parse_failed`        | 503 Service Unavailable   | Failed to parse JWKS keys                                                                    |
+| `jwks_cache_miss`          | 503 Service Unavailable   | JWKS cache is empty (e.g., 304 Not Modified without prior cache)                             |
+| `discovery_metadata_fetch_failed` | 503 Service Unavailable   | Failed to fetch OIDC discovery document                                               |
+| `discovery_metadata_invalid` | 503 Service Unavailable   | Failed to parse OIDC discovery document                                                    |
+| `discovery_redirect_error` | 503 Service Unavailable   | Discovery response was a redirect without a valid Location header                           |
+| `internal_server_error`    | 500 Internal Server Error | Unexpected internal error (catch-all)                                                        |
+
+> Note: The `decode_with_public_key` method ensures consistent error codes for all JWT verification failures.  
+> It may raise `invalid_signature`, `unsupported_algorithm`, `expired_token`, `invalid_issuer`, `invalid_audience`, or `not_yet_valid` depending on the verification outcome.
+
+For a full list of error cases and detailed explanations, please see the [ERRORS.md](ERRORS.md) file.
+
+## Configuration Options
+
+| Key             | Required | Description                                 |
+| --------------- | -------- | ------------------------------------------- |
+| `discovery_url` | Yes   | Full URL to your realm's OIDC discovery doc |
+| `audience`      | Yes   | Your client ID (checked against `aud`)      |
+| `skip_paths`    | No       | Array of paths or wildcards to skip authentication, e.g. `['/', '/health', '/public/*']`. **Note:** Regex patterns are not supported. |
+| `discovery`     | No       | Inject custom Discovery instance (advanced/testing) |
+| `jwks_cache`    | No       | Inject custom JwksCache instance (advanced/testing) |
+
+#### Option: `skip_paths`
+
+`skip_paths` lets you specify paths (or wildcard patterns) where authentication should be **skipped**.  
+For example:
+
+```ruby
+skip_paths: ['/', '/health', '/public/*', '/rails/*']
+```
+- `'/'` matches only the root path.
+- `'/foo/*'` matches `/foo` and any subpath like `/foo/bar` or `/foo/bar/baz`.
+- `'/api/public'` matches **only** `/api/public` (for subpaths, use `'/api/public/*'`).
+- `'/rails/*'` matches `/rails` itself as well as `/rails/foo`, `/rails/foo/bar`, etc.
+
+Paths **not matched** by any `skip_paths` entry will require a valid JWT.
+
+**Note:** Regex patterns are not supported. Only literal paths and `*` wildcards are allowed.  
+Internally, `*` expands to match nested paths, so patterns like `/rails/*` are valid. This differs from regex — for example, `'/rails'` alone matches only `/rails`, while `'/rails/*'` covers both `/rails` and deeper subpaths.
+
+---
+
+## Architecture
+
+Verikloak consists of modular components, each with a focused responsibility:
+
+| Component       | Responsibility                                        | Layer        |
+|----------------|--------------------------------------------------------|--------------|
+| `Middleware`    | Rack-compatible entry point for token validation     | Rack layer   |
+| `Discovery`     | Fetches OIDC discovery metadata (`.well-known`)      | Network layer|
+| `JwksCache`     | Fetches & caches JWKS public keys (with ETag)        | Cache layer  |
+| `TokenDecoder`  | Decodes and verifies JWTs (signature, exp, nbf, iss, aud) | Crypto layer |
+| `Errors`        | Centralized error hierarchy                          | Core layer   |
+
+This separation enables better testing, modular reuse, and flexibility.
+
+---
+
+## Development (for contributors)
+
+Clone and install dependencies:
+
+```bash
+git clone https://github.com/taiyaky/verikloak.git
+cd verikloak
+bundle install
+```
+See **Testing** below to run specs and RuboCop. For releasing, see **Publishing**.
+
+---
+
+## Testing
+
+All pull requests and pushes are automatically tested with [RSpec](https://rspec.info/) and [RuboCop](https://rubocop.org/) via GitHub Actions.
+See the CI badge at the top for current build status.
+
+To run the test suite locally:
+
+```bash
+docker compose run --rm dev rspec
+docker compose run --rm dev rubocop
+```
+---
+
+## Contributing
+
+Bug reports and pull requests are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+---
+
+## Security
+
+If you find a security vulnerability, please follow the instructions in [SECURITY.md](SECURITY.md).
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+---
+
+## Publishing (for maintainers)
+
+Gem release instructions are documented separately in [MAINTAINERS.md](MAINTAINERS.md).
+
+---
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+---
+
+## References
+
+- [OpenID Connect Discovery 1.0 Spec](https://openid.net/specs/openid-connect-discovery-1_0.html)  
+- [Keycloak Documentation: Securing Apps](https://www.keycloak.org/docs/latest/securing_apps/#openid-connect)  
+- [JWT RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519) 

data/lib/verikloak/discovery.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+require 'uri'
+
+module Verikloak
+  # Fetches and caches the OpenID Connect Discovery document.
+  #
+  # This class retrieves the discovery metadata from an OpenID Connect provider
+  # (e.g., Keycloak) using the `.well-known/openid-configuration` endpoint.
+  # It validates required fields such as `jwks_uri` and `issuer`, and supports:
+  #
+  # - Dependency Injection of Faraday connection for testing and middleware
+  # - In-memory caching with configurable TTL
+  # - Thread safety via Mutex
+  # - Automatic handling of common HTTP statuses (including multi-hop redirects)
+  #
+  # ### Thread-safety
+  # `#fetch!` is synchronized, so concurrent callers share the same cached value and refresh.
+  #
+  # ### Errors
+  # Raises {Verikloak::DiscoveryError} with one of the following `code`s:
+  # - `invalid_discovery_url`
+  # - `discovery_metadata_fetch_failed`
+  # - `discovery_metadata_invalid`
+  # - `discovery_redirect_error`
+  #
+  # @example Basic usage
+  #   discovery = Verikloak::Discovery.new(
+  #     discovery_url: "https://keycloak.example.com/realms/demo/.well-known/openid-configuration"
+  #   )
+  #   json = discovery.fetch!
+  #   json["issuer"]   #=> "https://keycloak.example.com/realms/demo"
+  #   json["jwks_uri"] #=> "https://keycloak.example.com/realms/demo/protocol/openid-connect/certs"
+  class Discovery
+    # Required keys that must be present in the discovery document.
+    # @return [Array<String>]
+    REQUIRED_FIELDS = %w[jwks_uri issuer].freeze
+
+    # @param discovery_url [String] The full URL to the `.well-known/openid-configuration`.
+    # @param connection [Faraday::Connection] Optional Faraday client (for DI/tests). Defaults to `Faraday.new`.
+    # @param cache_ttl [Integer] Cache TTL in seconds (default: 3600).
+    # @raise [DiscoveryError] when `discovery_url` is not a valid HTTP(S) URL
+    def initialize(discovery_url:, connection: Faraday.new, cache_ttl: 3600)
+      unless discovery_url.is_a?(String) && discovery_url.strip.match?(%r{^https?://})
+        raise DiscoveryError.new('Invalid discovery URL: must be a non-empty HTTP(S) URL',
+                                 code: 'invalid_discovery_url')
+      end
+
+      @discovery_url = discovery_url
+      @conn          = connection
+      @cache_ttl     = cache_ttl
+      @cached_json   = nil
+      @fetched_at    = nil
+      @mutex         = Mutex.new
+    end
+
+    # Fetches and parses the discovery document, using the in-memory cache if fresh.
+    #
+    # Cache freshness is determined by `cache_ttl` from initialization.
+    #
+    # @return [Hash] Parsed JSON object containing discovery metadata.
+    # @raise [DiscoveryError] if the request fails, the response is invalid, or required fields are missing.
+    def fetch!
+      @mutex.synchronize do
+        # Return cached if within TTL
+        return @cached_json if @cached_json && (Time.now - @fetched_at) < @cache_ttl
+
+        # Fetch fresh document
+        json = with_error_handling { fetch_and_parse_json_from_url }
+        validate_required_fields!(json)
+
+        # Update cache
+        @cached_json = json
+        @fetched_at  = Time.now
+        json
+      end
+    end
+
+    private
+
+    # Performs the initial HTTP GET and handles redirects, returning the parsed JSON.
+    # @api private
+    # @return [Hash]
+    def fetch_and_parse_json_from_url
+      response = @conn.get(@discovery_url)
+      response = follow_redirects(response, max_hops: 3, base_url: @discovery_url)
+      handle_final_response(response)
+    end
+
+    # Handles terminal (non-redirect) responses and parses JSON on 200 OK.
+    # Maps common failure statuses to {DiscoveryError} with appropriate codes.
+    # @api private
+    # @param response [Faraday::Response]
+    # @return [Hash]
+    # @raise [DiscoveryError]
+    def handle_final_response(response)
+      status = response.status
+      return parse_json(response.body) if status == 200
+
+      if status == 404
+        # If the 404 occurred after a redirect (final URL differs from the original discovery URL),
+        # keep the generic message to align with redirect tests; otherwise use a specific "not found" message.
+        final_url = response.respond_to?(:env) && response.env&.url ? response.env.url.to_s : nil
+        message = if final_url && final_url != @discovery_url
+                    'Failed to fetch discovery document: status 404'
+                  else
+                    'Discovery document not found (404)'
+                  end
+        raise DiscoveryError.new(message, code: 'discovery_metadata_fetch_failed')
+      end
+      if (500..599).cover?(status)
+        raise DiscoveryError.new("Discovery endpoint server error: status #{status}",
+                                 code: 'discovery_metadata_fetch_failed')
+      end
+
+      raise DiscoveryError.new("Failed to fetch discovery document: status #{status}",
+                               code: 'discovery_metadata_fetch_failed')
+    end
+
+    # Follows HTTP redirects up to `max_hops`, resolving relative `Location` values.
+    # @api private
+    # @param response [Faraday::Response]
+    # @param max_hops [Integer]
+    # @param base_url [String]
+    # @return [Faraday::Response] the final (non-redirect) response
+    # @raise [DiscoveryError] when exceeding hops or encountering invalid/missing Location
+    def follow_redirects(response, max_hops:, base_url:)
+      hops = 0
+      current = response
+      base = base_url
+
+      while redirect_status?(current.status)
+        if hops >= max_hops
+          raise DiscoveryError.new("Too many redirects (max #{max_hops})",
+                                   code: 'discovery_redirect_error')
+        end
+
+        location = location_from(current)
+        url = absolutize_location(location, base)
+        current = @conn.get(url)
+        base = url
+        hops += 1
+      end
+
+      current
+    end
+
+    # Returns true if status is an HTTP redirect.
+    # @api private
+    # @param status [Integer]
+    # @return [Boolean]
+    def redirect_status?(status)
+      [301, 302, 303, 307, 308].include?(status)
+    end
+
+    # Extracts and normalizes the Location header, raising when missing.
+    # @api private
+    # @param response [Faraday::Response]
+    # @return [String] absolute or relative URL string
+    # @raise [DiscoveryError]
+    def location_from(response)
+      raw = response.headers || {}
+      headers = {}
+      raw.each { |k, v| headers[k.to_s.downcase] = v }
+      location = headers['location'].to_s.strip
+      raise DiscoveryError.new('Redirect without Location header', code: 'discovery_redirect_error') if location.empty?
+
+      location
+    end
+
+    # Resolves a possibly-relative Location value to an absolute URL string.
+    # @api private
+    # @param location [String]
+    # @param base_url [String]
+    # @return [String] absolute URL
+    # @raise [DiscoveryError] when location is an invalid URI
+    def absolutize_location(location, base_url)
+      uri = URI.parse(location)
+      return location if uri.absolute?
+
+      base = URI.parse(base_url)
+      URI.join(base, location).to_s
+    rescue URI::InvalidURIError => e
+      raise DiscoveryError.new("Redirect Location is invalid: #{e.message}", code: 'discovery_redirect_error')
+    end
+
+    # Parses a JSON string and maps parse errors to {DiscoveryError}.
+    # @api private
+    # @param body [String]
+    # @return [Hash]
+    # @raise [DiscoveryError]
+    def parse_json(body)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise DiscoveryError.new('Discovery response is not valid JSON', code: 'discovery_metadata_invalid')
+    end
+
+    # Validates HTTP response success status (helper, currently unused).
+    # @api private
+    # @param response [Faraday::Response]
+    # @return [void]
+    # @raise [DiscoveryError]
+    def validate_http_status!(response)
+      return if response.success?
+
+      raise DiscoveryError.new("Failed to fetch discovery document: status #{response.status}",
+                               code: 'discovery_metadata_fetch_failed')
+    end
+
+    # Wraps a block with network and parsing error handling and re-raising as {DiscoveryError}.
+    # @api private
+    # @yield
+    # @return [Object] the block result
+    # @raise [DiscoveryError]
+    def with_error_handling
+      yield
+    rescue Verikloak::DiscoveryError
+      # Re-raise library-specific discovery errors without altering their code/message
+      raise
+    rescue Faraday::ConnectionFailed
+      raise DiscoveryError.new('Could not connect to discovery endpoint', code: 'discovery_metadata_fetch_failed')
+    rescue Faraday::TimeoutError
+      raise DiscoveryError.new('Discovery endpoint request timed out', code: 'discovery_metadata_fetch_failed')
+    rescue Faraday::Error => e
+      raise DiscoveryError.new("Discovery request failed: #{e.message}", code: 'discovery_metadata_fetch_failed')
+    rescue StandardError => e
+      raise DiscoveryError.new("Unexpected discovery error: #{e.message}", code: 'discovery_metadata_fetch_failed')
+    end
+
+    # Ensures all required fields exist in the discovery JSON document.
+    # @api private
+    # @param json [Hash]
+    # @return [void]
+    # @raise [DiscoveryError]
+    def validate_required_fields!(json)
+      REQUIRED_FIELDS.each do |field|
+        unless json[field]
+          raise DiscoveryError.new("Discovery document is missing '#{field}'",
+                                   code: 'discovery_metadata_invalid')
+        end
+      end
+    end
+  end
+end