jwt_auth_client 0.1.0 → 0.2.0

data/lib/jwt_auth_client/http_client.rb

@@ -1,63 +1,126 @@
-require 'faraday'
+# frozen_string_literal: true
+
+require "faraday"
+require_relative "errors"
+require_relative "json_decoder"
+require_relative "token_issuer"
 
 module JwtAuthClient
-  # HttpClient is a thin wrapper around Faraday that automatically issues a JWT
-  # for the given user/scopes and injects it into the Authorization header
-  # for secure inter-service communication.
+  # A thin wrapper around Faraday that issues a JWT for the given user/scopes
+  # and injects it as a Bearer token on every outgoing request.
+  #
+  # The returned connection is safe to keep and reuse for the lifetime of the
+  # process: the token is (re)issued lazily per request, so a long-lived
+  # connection never sends an expired token.
   class HttpClient
-    # The public entry point for making requests.
+    # Tokens are re-issued when they are this close to expiring, even when
+    # token reuse is enabled.
+    REFRESH_MARGIN_SECONDS = 30
+
+    # Builds an authenticated Faraday connection.
     #
-    # @param user_id [String] The ID of the user to impersonate for this request.
-    # @param target_service [String] The specific backend service the token is intended for (used for 'aud' claim).
-    # @param scopes [Array<String>] The permissions required for the request.
-    # @param base_url [String] The base URL of the service to call (overrides global config if provided).
-    # @return [Faraday::Response] The response object from the HTTP request.
-    def self.call(user_id:, target_service:, scopes: [], base_url: nil)
-      new(user_id, target_service, scopes, base_url).connection
+    # @param user_id [String] the subject the token is issued for. Required.
+    # @param target_service [Symbol, String] the audience; must be a key of
+    #   `configuration.service_urls` unless `base_url` is given. Required.
+    # @param scopes [Array<String>] permissions to embed in the token.
+    # @param base_url [String, nil] overrides the configured URL for `target_service`
+    #   (e.g. a canary host). It does not change the `aud` claim.
+    # @yieldparam conn [Faraday::Connection] to add middleware (logging,
+    #   instrumentation, ...) before the adapter is set.
+    # @return [Faraday::Connection]
+    def self.call(user_id:, target_service:, scopes: [], base_url: nil, &customize)
+      new(user_id, target_service, scopes, base_url, &customize).connection
     end
 
     attr_reader :user_id, :target_service, :scopes, :base_url
 
-    # Initializes the client instance.
-    def initialize(user_id, target_service, scopes, base_url = nil)
+    def initialize(user_id, target_service, scopes, base_url = nil, &customize)
+      raise ArgumentError, "user_id is required" if user_id.nil? || user_id.to_s.empty?
+      raise ArgumentError, "target_service is required" if target_service.nil? || target_service.to_s.empty?
+
       @user_id = user_id
       @target_service = target_service
-      @scopes = scopes
+      @scopes = Array(scopes)
       @base_url = base_url
+      @customize = customize
       @config = JwtAuthClient.configuration
+      @token_mutex = Mutex.new
     end
 
-    # Builds and memoizes the Faraday connection object.
-    # The JWT is issued and included in a request header during this connection setup.
-    #
-    # @return [Faraday::Connection] The pre-configured Faraday connection.
+    # @return [Faraday::Connection] the memoised, pre-configured connection.
     def connection
-      @connection ||= Faraday.new(url: determined_base_url) do |conn|
-        # Inject the Authorization header with the JWT before every request
-        conn.request :authorization, 'Bearer', jwt_token 
-
-        # Other standard middleware
-        conn.request :json
-        conn.response :json, content_type: /\bjson$/
-        conn.response :raise_error # Raise exceptions on 4xx/5xx responses
-        conn.adapter Faraday.default_adapter
+      @connection ||= begin
+        @config.validate!
+        Faraday.new(url: determined_base_url) do |conn|
+          configure_timeouts(conn)
+
+          # Evaluated on every request, so the token is always fresh.
+          conn.request :authorization, "Bearer", -> { bearer_token }
+          conn.request :json
+
+          # Response middleware runs innermost-first, so declaration order matters:
+          #   raise_error  - outermost: raises on 4xx/5xx once retries are exhausted,
+          #                  with the already-parsed JSON body attached to the error.
+          #   retry        - (opt-in) sees raw statuses, so `retry_statuses` works.
+          #   json         - innermost: parses the body before anything else sees it.
+          conn.response :raise_error
+          configure_retry(conn)
+          conn.response :json, parser_options: { decoder: [JsonDecoder, :parse] }
+
+          @customize&.call(conn)
+          conn.adapter Faraday.default_adapter
+        end
+      end
+    end
+
+    # Returns a valid token, issuing a new one when there is none, when the
+    # cached one is within REFRESH_MARGIN_SECONDS of expiry, or when
+    # `configuration.token_reuse_seconds` has elapsed since it was issued.
+    #
+    # @return [String]
+    def bearer_token
+      @token_mutex.synchronize do
+        issue_token! if token_stale?
+        @token
       end
     end
 
     private
 
-    # Determines the base URL, preferring the local override if provided.
     def determined_base_url
       base_url || @config.base_url_for(target_service)
     end
 
-    # Uses the TokenIssuer service to generate the authenticated token.
-    def jwt_token
-      @jwt_token ||= TokenIssuer.call(
-        user_id: user_id,
-        target_service: target_service,
-        scopes: scopes
-      )
+    def configure_timeouts(conn)
+      conn.options.open_timeout  = @config.open_timeout
+      conn.options.read_timeout  = @config.read_timeout
+      conn.options.write_timeout = @config.write_timeout
+      conn.options.timeout       = @config.read_timeout # for adapters that only honour :timeout
+    end
+
+    def configure_retry(conn)
+      return unless @config.retry_options
+
+      begin
+        require "faraday/retry"
+      rescue LoadError
+        raise ConfigurationError, "retry_options is set but the faraday-retry gem is not available"
+      end
+      conn.request :retry, **@config.retry_options
+    end
+
+    def token_stale?
+      return true if @token.nil?
+
+      now = Time.now.to_i
+      now >= @token_expires_at - REFRESH_MARGIN_SECONDS ||
+        now >= @token_issued_at + @config.token_reuse_seconds
+    end
+
+    def issue_token!
+      @token_issued_at = Time.now.to_i
+      @token_expires_at = @token_issued_at + @config.default_expiry_seconds
+      @token = TokenIssuer.call(user_id: user_id, target_service: target_service, scopes: scopes)
     end
   end
 end

data/lib/jwt_auth_client/issuable.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "token_issuer"
+
+module JwtAuthClient
+  # Mixin for objects (typically a User model) that can be turned into a JWT,
+  # e.g. by an SSO hub handing a signed identity token to a client app.
+  #
+  #   class User < ApplicationRecord
+  #     include JwtAuthClient::Issuable
+  #
+  #     def jwt_claims
+  #       { user_id: sso_id, email: email }
+  #     end
+  #   end
+  #
+  #   user.to_jwt                      # => "eyJhbGciOi..."
+  #   user.to_jwt(expiry_seconds: 60)
+  #
+  # The registered claims (iss, sub, iat, nbf, exp, jti) are always set by the
+  # gem; `jwt_claims` cannot override them. `sub` comes from `jwt_subject`,
+  # which defaults to `jwt_claims[:user_id]`, falling back to `id`.
+  module Issuable
+    # Custom claims to embed in the token. Override in the including class.
+    #
+    # @return [Hash]
+    def jwt_claims
+      raise NotImplementedError, "#{self.class} must define #jwt_claims returning a Hash of claims"
+    end
+
+    # The `sub` claim. Override to use a different identifier.
+    #
+    # @return [String, Integer]
+    def jwt_subject
+      claims = jwt_claims
+      claims[:user_id] || claims["user_id"] || (respond_to?(:id) ? id : nil)
+    end
+
+    # @param expiry_seconds [Integer, nil] overrides the configured default expiry.
+    # @param target_service [Symbol, String, nil] optional `aud` claim.
+    # @param scopes [Array<String>] optional `scopes` claim.
+    # @return [String] the signed JWT.
+    def to_jwt(expiry_seconds: nil, target_service: nil, scopes: [])
+      TokenIssuer.call(
+        user_id: jwt_subject,
+        target_service: target_service,
+        scopes: scopes,
+        claims: jwt_claims,
+        expiry_seconds: expiry_seconds
+      )
+    end
+  end
+end

data/lib/jwt_auth_client/json_decoder.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "json"
+
+module JwtAuthClient
+  # Adapter handed to Faraday's :json response middleware.
+  #
+  # Faraday (<= 2.14) calls `decoder.parse(body, options_hash)` with a positional
+  # options hash, which `json` >= 3.0 no longer accepts. Forwarding the options as
+  # keywords keeps response parsing working on both json 2.x and 3.x.
+  module JsonDecoder
+    module_function
+
+    def parse(body, options = {})
+      ::JSON.parse(body, **options)
+    end
+  end
+end

data/lib/jwt_auth_client/token_issuer.rb

@@ -1,60 +1,72 @@
-require 'jwt'
-require 'securerandom'
+# frozen_string_literal: true
+
+require "jwt"
+require "securerandom"
+require_relative "errors"
 
 module JwtAuthClient
+  # Issues short-lived, signed JWTs carrying the registered claims
+  # (iss, sub, iat, nbf, exp, jti) plus the optional `aud`, `scopes` and any
+  # caller-supplied custom claims.
   class TokenIssuer
-    # This is the ONLY public class method API. It initializes and calls the public instance method.
-    def self.call(user_id:, target_service: nil, scopes: [])
-      new(user_id, target_service, scopes).issue 
+    # Claims that are always set by the issuer and can never be overridden by
+    # caller-supplied custom claims.
+    REGISTERED_CLAIMS = %i[iss sub iat nbf exp jti].freeze
+
+    # @param user_id [String] the subject (`sub`) of the token. Required.
+    # @param target_service [Symbol, String, nil] the audience (`aud`).
+    # @param scopes [Array<String>, nil] permissions granted by the token.
+    # @param claims [Hash] extra custom claims (e.g. email); registered claims
+    #   in this hash are ignored.
+    # @param expiry_seconds [Integer, nil] overrides `configuration.default_expiry_seconds`.
+    # @return [String] the signed JWT.
+    def self.call(user_id:, target_service: nil, scopes: [], claims: {}, expiry_seconds: nil)
+      new(user_id, target_service, scopes, claims: claims, expiry_seconds: expiry_seconds).issue
     end
 
-    # initialize is public by default.
-    def initialize(user_id, target_service, scopes)
+    def initialize(user_id, target_service, scopes, claims: {}, expiry_seconds: nil)
+      raise ArgumentError, "user_id is required" if user_id.nil? || user_id.to_s.empty?
+      raise ArgumentError, "claims must be a Hash" unless claims.is_a?(Hash)
+      unless expiry_seconds.nil? || (expiry_seconds.is_a?(Integer) && expiry_seconds.positive?)
+        raise ArgumentError, "expiry_seconds must be a positive Integer"
+      end
+
       @user_id = user_id
       @target_service = target_service
-      @scopes = scopes
+      @scopes = Array(scopes)
+      @claims = claims
+      @expiry_seconds = expiry_seconds
       @config = JwtAuthClient.configuration
     end
 
-    # --- Public Instance Method (Called by self.call) ---
+    # @return [String] the signed JWT.
+    # @raise [ConfigurationError] if the configuration is invalid.
+    # @raise [TokenError] if the jwt gem fails to sign the payload.
     def issue
-      encode
+      @config.validate!
+      JWT.encode(build_payload, @config.shared_secret, @config.algorithm)
+    rescue JWT::EncodeError, JWT::DecodeError => e
+      # The jwt gem reports bad HMAC keys as DecodeError even on encode.
+      raise TokenError, "Failed to sign token: #{e.message}"
     end
 
-    # --- Private Helper Methods ---
     private
-    
-    def encode
-      payload = build_payload
-      
-      # Use the JWT gem to encode the token
-      JWT.encode(payload, @config.shared_secret, @config.algorithm)
-    end
 
-    # Uses conditional merging to ensure keys for optional claims (aud, scopes)
-    # are only included if they have a non-nil/non-empty value.
     def build_payload
-      # Standard JWT Claims (Must include these for security/verification)
       issued_at = Time.now.to_i
-      expiry = issued_at + @config.default_expiry_seconds
-
-      # 1. Start with Required Claims
-      payload = {
-        iss: @config.issuer,                      # Issuer (e.g., main_sso_app)
-        sub: @user_id,                            # Subject (The user being impersonated)
-        iat: issued_at,                           # Issued At Time
-        exp: expiry,                              # Expiration Time (CRITICAL: short-lived)
-        jti: SecureRandom.uuid,                   # JWT ID (For optional replay attack prevention)
-      }
-      
-      # 2. Conditionally merge Optional Claims
-      # Audience is nil by default
-      payload[:aud] = @target_service if @target_service
-      
-      # Scopes are [] by default, so check if the array is not empty
+
+      payload = @claims.transform_keys(&:to_sym).reject { |key, _| REGISTERED_CLAIMS.include?(key) }
+      payload[:aud] = @target_service.to_s unless @target_service.nil? || @target_service.to_s.empty?
       payload[:scopes] = @scopes unless @scopes.empty?
 
-      payload
+      payload.merge!(
+        iss: @config.issuer,
+        sub: @user_id,
+        iat: issued_at,
+        nbf: issued_at,
+        exp: issued_at + (@expiry_seconds || @config.default_expiry_seconds),
+        jti: SecureRandom.uuid
+      )
     end
   end
 end

data/lib/jwt_auth_client/version.rb

@@ -1,3 +1,3 @@
 module JwtAuthClient
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/jwt_auth_client.rb

@@ -1,16 +1,11 @@
-require 'jwt' # Core dependency
-require 'active_support/core_ext/numeric/time' # For N.minutes.from_now logic
-require 'securerandom' # Added for SecureRandom.uuid dependency
-require 'jwt_auth_client/version'
-require 'jwt_auth_client/configuration'
-require 'jwt_auth_client/token_issuer' 
-require 'jwt_auth_client/http_client'
-require 'jwt_auth_client/billing_client'
+# frozen_string_literal: true
 
-module JwtAuthClient
-  # Main module definition
-end
+require "jwt_auth_client/version"
+require "jwt_auth_client/errors"
+require "jwt_auth_client/configuration"
+require "jwt_auth_client/token_issuer"
+require "jwt_auth_client/issuable"
+require "jwt_auth_client/http_client"
 
 module JwtAuthClient
-  # Main module definition
-end
+end

metadata

@@ -1,136 +1,140 @@
 --- !ruby/object:Gem::Specification
 name: jwt_auth_client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniele Frisanco
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2025-10-25 00:00:00.000000000 Z
+date: 2026-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: jwt
+  name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '2.9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.8'
+        version: '2.9'
 - !ruby/object:Gem::Dependency
-  name: faraday
+  name: jwt
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.9'
+        version: '2.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.9'
+        version: '2.8'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: faraday-retry
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
-  type: :runtime
+        version: '2.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '3.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '3.12'
 - !ruby/object:Gem::Dependency
-  name: rspec
+  name: timecop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.19'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: Generates short-lived, signed JWTs for internal API calls authenticated
-  via a shared secret.
+        version: '3.19'
+description: Generates short-lived, signed JWTs for internal API calls and injects
+  them into Faraday requests as Bearer tokens.
 email:
 - daniele.frisanco@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- Gemfile
-- Gemfile.lock
+- CHANGELOG.md
+- LICENSE
 - README.md
-- Rakefile
 - lib/jwt_auth_client.rb
-- lib/jwt_auth_client/billing_client.rb
 - lib/jwt_auth_client/configuration.rb
+- lib/jwt_auth_client/errors.rb
 - lib/jwt_auth_client/http_client.rb
+- lib/jwt_auth_client/issuable.rb
+- lib/jwt_auth_client/json_decoder.rb
 - lib/jwt_auth_client/token_issuer.rb
 - lib/jwt_auth_client/version.rb
-- pkg/jwt_auth_client-0.1.0.gem
 homepage: https://github.com/danielefrisanco/jwt_auth_client
 licenses:
 - MIT
-metadata: {}
+metadata:
+  homepage_uri: https://github.com/danielefrisanco/jwt_auth_client
+  source_code_uri: https://github.com/danielefrisanco/jwt_auth_client
+  changelog_uri: https://github.com/danielefrisanco/jwt_auth_client/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -139,14 +143,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.3.26
 signing_key: 
 specification_version: 4
 summary: Secure client for generating and sending internal service-to-service JWTs.

data/Gemfile

@@ -1,27 +0,0 @@
-source "https://rubygems.org"
-gemspec
-group :development, :test do
-  gem 'pry', '~> 0.14'
-
-  # Core HTTP Client
-  gem 'faraday', '~> 2.7' 
-  
-  # For conn.request :retry (now typically part of the faraday-excon or faraday-net_http gems)
-  # gem 'faraday-retry' # You might need this explicitly if on an older version of Faraday 2+
-  
-  gem 'webmock', '~> 3.19' # For HTTP stubbing/testing
-  gem 'timecop', '~> 0.9'  # For time-based testing
-  # Testing tools
-  gem 'rspec', '~> 3.0'
-
-  # Faraday and required middleware
-  # The core faraday gem is already included via gemspec
-  # We must explicitly add the middleware that replaced faraday-middleware and faraday-json
-  gem 'faraday-typhoeus' # A robust adapter
-  gem 'faraday-retry', '~> 2.0' # Explicit gem for the :retry middleware
-  
-  # Note: JSON encoding/decoding middleware is often implicitly handled 
-  # by faraday v2, or included in faraday-typhoeus or a different gem 
-  # depending on the setup. Explicitly adding :json requests/responses
-  # in the HttpClient often just needs the `json` gem itself.
-end