jwt_auth_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a68ca9dd3459f00b139bd71b8a52a5a24112fab256c0aadeebb594f4704159e8
+  data.tar.gz: 8a9dfabd1723a404c01fa213fd2589abf8f6f5a4500a7a42f25ce90f5d1938ee
+SHA512:
+  metadata.gz: 3014ed4df9591c1a3115380a78c222df936ca0e81c46cb22fa1721308f582e563049eaa6fe9a602505b90daf38a792cd60f0c5ab73883ba140cf4332cedac407
+  data.tar.gz: c59efce14020d02c89c77c7ac18fed487f618862e4150f93d63c7e6d41f9bbb9c3dc46724360f756e758d0a2455836c3811753b1640c7fca00410549c99716bd

data/Gemfile

@@ -0,0 +1,27 @@
+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

data/Gemfile.lock

@@ -0,0 +1,109 @@
+PATH
+  remote: .
+  specs:
+    jwt_auth_client (0.1.0)
+      activesupport (>= 6.0)
+      faraday (~> 2.9)
+      jwt (~> 2.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (8.1.0)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    base64 (0.3.0)
+    bigdecimal (3.3.1)
+    coderay (1.1.3)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.4)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    ethon (0.15.0)
+      ffi (>= 1.15.0)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.1)
+      net-http (>= 0.5.0)
+    faraday-retry (2.3.2)
+      faraday (~> 2.0)
+    faraday-typhoeus (1.1.0)
+      faraday (~> 2.0)
+      typhoeus (~> 1.4)
+    ffi (1.17.2-x86_64-linux-gnu)
+    hashdiff (1.2.1)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    json (2.15.1)
+    jwt (2.10.2)
+      base64
+    logger (1.7.0)
+    method_source (1.1.0)
+    minitest (5.26.0)
+    net-http (0.6.0)
+      uri
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    public_suffix (6.0.2)
+    rake (13.3.0)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    securerandom (0.4.1)
+    timecop (0.9.10)
+    typhoeus (1.5.0)
+      ethon (>= 0.9.0, < 0.16.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.0.4)
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (~> 2.0)
+  faraday (~> 2.7)
+  faraday-retry (~> 2.0)
+  faraday-typhoeus
+  jwt_auth_client!
+  pry (~> 0.14)
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  timecop (~> 0.9)
+  webmock (~> 3.19)
+
+BUNDLED WITH
+   2.4.22

data/README.md

@@ -0,0 +1,116 @@
+JwtAuthClient
+=============
+
+A minimal, robust Ruby client for internal service-to-service authentication using JSON Web Tokens (JWTs).
+
+This gem simplifies the process of creating, signing, and injecting short-lived JWTs into outgoing HTTP requests, ensuring secure communication between your internal microservices.
+
+Features
+--------
+
+*   **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:
+
+```ruby
+gem 'jwt_auth_client', '~> 0.1.0'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Configuration
+-------------
+
+You must configure the client once in your application's initialization file (e.g., `config/initializers/jwt_auth_client.rb` in a Rails app).
+
+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.
+
+```ruby
+# config/initializers/jwt_auth_client.rb
+
+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
+  config.service_urls = {
+    billing_api: 'http://billing-service.internal',
+    user_data_api: 'http://user-service.internal'
+  }
+end
+```
+
+Usage
+-----
+
+### 1\. High-Level Service Client (Recommended)
+
+Use the built-in or custom client wrappers for clean dependency management. These clients automatically use the configured `target_service`.
+
+```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']
+)
+
+# client is a Faraday connection object
+response = client.get('/v1/invoices/latest')
+if response.success?
+  puts "Invoices: #{response.body}"
+end
+```
+
+### 2\. General HTTP Client (Advanced)
+
+If you need dynamic control over the target service, you can use the base `HttpClient`.
+
+```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
+)
+```
+
+### 3\. Token Generation Only
+
+If you only need the raw JWT string for non-HTTP purposes (e.g., message queues), use the `TokenIssuer`.
+
+```ruby
+token = JwtAuthClient::TokenIssuer.call(
+  user_id: 'system-job-id',
+  target_service: 'data_pipeline',
+  scopes: ['process:orders']
+)
+# token will be the signed JWT string
+# puts token
+```

data/Rakefile

@@ -0,0 +1,27 @@
+require 'rake'
+require 'rake/testtask'
+require 'rspec/core/rake_task'
+require 'rubygems/package_task'
+require "bundler/gem_tasks"
+
+# Load the gemspec to get gem metadata
+spec = Gem::Specification.load("jwt_auth_client.gemspec")
+
+# Task to run all RSpec tests
+RSpec::Core::RakeTask.new(:spec) do |t|
+  # Use RSpec's command-line options
+  t.rspec_opts = "--color --format documentation"
+  # Specify the files to run
+  t.pattern = 'spec/**/*_spec.rb'
+end
+
+# Define 'test' as an alias for 'spec'
+task :test => :spec
+
+# Define a task for building the gem (creates the .gem file)
+Gem::PackageTask.new(spec) do |pkg|
+  # Optional: Customize the package task if necessary
+end
+
+# Default task is usually to run tests
+task :default => :spec

data/lib/jwt_auth_client/billing_client.rb

@@ -0,0 +1,13 @@
+require_relative 'http_client'
+
+module JwtAuthClient
+  # A high-level, service-specific client that inherits from HttpClient
+  # and automatically sets the target_service to :billing_api.
+  class BillingClient < HttpClient
+    # The public entry point, mirroring the service object pattern,
+    # but hardcoding the target_service.
+    def self.call(user_id:, scopes: [], base_url: nil)
+      super(user_id: user_id, target_service: :billing_api, scopes: scopes, base_url: base_url)
+    end
+  end
+end

data/lib/jwt_auth_client/configuration.rb

@@ -0,0 +1,48 @@
+module JwtAuthClient
+  class Configuration
+    # The cryptographic key known to all internal services
+    attr_accessor :shared_secret
+    
+    # The algorithm used for signing (e.g., 'HS256')
+    attr_accessor :algorithm
+    
+    # Default token validity period in seconds (e.g., 300 seconds = 5 minutes)
+    attr_accessor :default_expiry_seconds
+    
+    # The issuer of the token (conventionally the main application ID)
+    attr_accessor :issuer
+
+    # The mapping of target service names (Symbol) to their base URLs (String)
+    attr_accessor :service_urls
+
+    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' 
+      @service_urls = {}
+    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.
+    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
+    end
+  end
+
+  # Class method to expose the configuration object and the configuration block
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/jwt_auth_client/http_client.rb

@@ -0,0 +1,63 @@
+require 'faraday'
+
+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.
+  class HttpClient
+    # The public entry point for making requests.
+    #
+    # @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
+    end
+
+    attr_reader :user_id, :target_service, :scopes, :base_url
+
+    # Initializes the client instance.
+    def initialize(user_id, target_service, scopes, base_url = nil)
+      @user_id = user_id
+      @target_service = target_service
+      @scopes = scopes
+      @base_url = base_url
+      @config = JwtAuthClient.configuration
+    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.
+    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
+      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
+      )
+    end
+  end
+end

data/lib/jwt_auth_client/token_issuer.rb

@@ -0,0 +1,60 @@
+require 'jwt'
+require 'securerandom'
+
+module JwtAuthClient
+  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 
+    end
+
+    # initialize is public by default.
+    def initialize(user_id, target_service, scopes)
+      @user_id = user_id
+      @target_service = target_service
+      @scopes = scopes
+      @config = JwtAuthClient.configuration
+    end
+
+    # --- Public Instance Method (Called by self.call) ---
+    def issue
+      encode
+    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[:scopes] = @scopes unless @scopes.empty?
+
+      payload
+    end
+  end
+end

data/lib/jwt_auth_client/version.rb

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

data/lib/jwt_auth_client.rb

@@ -0,0 +1,16 @@
+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'
+
+module JwtAuthClient
+  # Main module definition
+end
+
+module JwtAuthClient
+  # Main module definition
+end

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: jwt_auth_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniele Frisanco
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-10-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  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.
+email:
+- daniele.frisanco@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- 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/http_client.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: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Secure client for generating and sending internal service-to-service JWTs.
+test_files: []