traylinx_auth_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d479f011cde37bff0d312edef21f32c3cab5e7947971f57c5d165aa1e6b57df3
+  data.tar.gz: c5016a5a0bef8c57563210630a488d8196d8ce835b44c2d466710434440b8210
+SHA512:
+  metadata.gz: 263b96fef7fe57aa4b69ea3f2c5399bf78cd492f84ab7aa0ef7e8fd442a3e9b7126a4709b6bb17cdd2b2cf46ddd2429a4a10bd067b53579a5b9c84b8007f3709
+  data.tar.gz: 5d1d2659cfb940f4713fa4321e45a22444dfe65f455bf693896739bbd85c042f06d7cb7e8c6bccfab99711bbc67dc2624d454d4f3449431b5b2707eee4366643

data/PUBLISHING.md

@@ -0,0 +1,85 @@
+# Publishing `traylinx_auth_client`
+
+This guide details how to build and publish the `traylinx_auth_client` Ruby gem.
+
+## Prerequisites
+
+- Ruby installed (2.7+)
+- `bundler` installed
+- Access to the target Gem repository (RubyGems.org or private)
+
+## 1. Verify Metadata
+
+Ensure `traylinx_auth_client.gemspec` has the correct version and metadata.
+
+```bash
+# Check version
+grep "spec.version" traylinx_auth_client.gemspec
+```
+
+## 2. Build the Gem
+
+Navigate to the SDK directory and build the gem package.
+
+```bash
+cd traylinx_core/sdks/ruby_sentinel
+gem build traylinx_auth_client.gemspec
+```
+
+This will output a file named like `traylinx_auth_client-0.1.0.gem`.
+
+## 3. Local Verification (Optional)
+
+You can install the built gem locally to verify it.
+
+```bash
+gem install ./traylinx_auth_client-0.1.0.gem
+```
+
+## 4. Publish to RubyGems
+
+If publishing to the public RubyGems.org:
+
+```bash
+gem push traylinx_auth_client-0.1.0.gem
+```
+
+## 5. Publish to Private Registry (e.g., GitHub Packages)
+
+If using GitHub Packages, you need to configure your `~/.gem/credentials` or use the command line.
+
+```bash
+# Example for GitHub Packages
+gem push --key github --host https://rubygems.pkg.github.com/StartTraylinx traylinx_auth_client-0.1.0.gem
+```
+
+## 6. Automating with CI/CD
+
+For automated publishing via GitHub Actions, ensure you have the `RUBYGEMS_API_KEY` secret set up in your repository.
+
+```yaml
+# .github/workflows/publish_gem.yml
+name: Publish Ruby Gem
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.0'
+      
+      - name: Build and Publish
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          gem build *.gemspec
+          gem push *.gem
+```

data/README.md

@@ -0,0 +1,180 @@
+# Traylinx Auth Client (Ruby)
+
+[![Gem Version](https://badge.fury.io/rb/traylinx-auth-client.svg)](https://badge.fury.io/rb/traylinx-auth-client)
+[![Ruby](https://img.shields.io/badge/ruby-2.7+-ruby.svg)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A robust, enterprise-grade Ruby library for Traylinx Sentinel Agent-to-Agent (A2A) authentication. This client provides secure token management, automatic retry logic, comprehensive error handling, and Rack middleware integration.
+
+## 🚀 Features
+
+- **🔐 Dual Token Authentication**: Handles both `access_token` and `agent_secret_token` with automatic refresh
+- **🛡️ Enterprise Security**: Input validation, secure credential handling, and comprehensive error management
+- **⚡ High Performance**: Thread-safe implementation, token caching, and connection pooling
+- **🔄 Async Support**: Built on Faraday for flexible adapters (Async/EM possible)
+- **🎯 Rack Integration**: Simple middleware for protecting endpoints with A2A authentication
+- **📡 JSON-RPC Support**: Support for A2A RPC method calls
+- **🔧 Zero Configuration**: Works with environment variables out of the box
+
+## 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'traylinx_auth_client'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install traylinx_auth_client
+```
+
+## ⚡ Quick Start (5 lines)
+
+```ruby
+require 'traylinx_auth_client'
+
+# Set ENV: TRAYLINX_CLIENT_ID, TRAYLINX_CLIENT_SECRET, 
+# TRAYLINX_API_BASE_URL, TRAYLINX_AGENT_USER_ID
+
+# Make authenticated request to another agent
+client = TraylinxAuthClient.client
+response = client.make_a2a_request(:get, "https://other-agent.com/api/data")
+puts response # JSON response body
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+Set these environment variables for your agent:
+
+```bash
+export TRAYLINX_CLIENT_ID="your-client-id"
+export TRAYLINX_CLIENT_SECRET="your-client-secret"  
+export TRAYLINX_API_BASE_URL="https://auth.traylinx.com"
+export TRAYLINX_AGENT_USER_ID="12345678-..."
+```
+
+### Programmatic Configuration
+
+```ruby
+require 'traylinx_auth_client'
+
+TraylinxAuthClient.configure do |config|
+  config.client_id = "your-client-id"
+  config.client_secret = "your-client-secret"
+  config.api_base_url = "https://auth.traylinx.com"
+  config.agent_user_id = "1234..."
+  
+  config.timeout = 30           # Seconds
+  config.max_retries = 3
+  config.cache_tokens = true
+  config.log_level = :info
+end
+```
+
+## 📖 Usage Examples
+
+### Making Authenticated Requests
+
+```ruby
+client = TraylinxAuthClient.client
+
+# GET request
+data = client.make_a2a_request(:get, "https://other-agent.com/api/users")
+
+# POST request with JSON
+result = client.make_a2a_request(:post, "https://other-agent.com/api/process", 
+  json: { items: ['item1', 'item2'] },
+  timeout: 60
+)
+```
+
+### Manual Header Management
+
+```ruby
+# Get all headers (for Auth Service)
+headers = client.get_request_headers
+# => { "Authorization" => "Bearer ...", "X-Agent-Secret-Token" => "...", ... }
+
+# Get Agent headers (for A2A)
+agent_headers = client.get_agent_request_headers
+# => { "X-Agent-Secret-Token" => "...", "X-Agent-User-Id" => "..." }
+```
+
+### Rack Middleware (Rails/Sinatra)
+
+Protect your application endpoints with A2A authentication.
+
+```ruby
+# config.ru or application.rb
+require 'traylinx_auth_client'
+
+use TraylinxAuthClient::Middleware
+```
+
+Or with specific validation path:
+
+```ruby
+use TraylinxAuthClient::Middleware, validation_path: /^\/api\/protected/
+```
+
+### JSON-RPC Calls
+
+```ruby
+# Introspect a token
+active = client.validate_token("some-agent-token", "agent-user-id")
+
+# Generic RPC call
+result = client.rpc_call("custom_method", { param: "value" })
+```
+
+### 🌌 Stargate P2P Identity (New)
+
+The client supports Stargate P2P identity certification for peer-to-peer communication.
+
+```ruby
+# 1. Get a challenge from Sentinel
+challenge = client.get_p2p_challenge(peer_id)
+
+# 2. Sign the challenge with your private key (implementation depends on your crypto lib)
+signature = sign_challenge(challenge, private_key)
+
+# 3. Certify identity
+cert = client.certify_p2p_identity(peer_id, public_key_base64, signature, challenge)
+
+puts cert[:certificate] # JWT Certificate
+puts cert[:expires_at]  # Expiration
+```
+
+## 🔐 Authentication Flow
+
+1. **Token Acquisition**: Automatically exchanges `client_id` + `client_secret` for OAuth tokens.
+2. **Token Caching**: Caches `access_token` and `agent_secret_token` in a thread-safe Map.
+3. **Auto Refresh**: Refreshes tokens 60 seconds before expiration.
+
+## 🛡️ Error Handling
+
+The client raises specific exceptions rooted in `TraylinxAuthClient::TraylinxAuthError`.
+
+```ruby
+begin
+  client.make_a2a_request(:get, url)
+rescue TraylinxAuthClient::AuthenticationError => e
+  puts "Auth failed: #{e.message}"
+rescue TraylinxAuthClient::NetworkError => e
+  puts "Network error: #{e.message}"
+end
+```
+
+## License
+
+MIT License.

data/lib/traylinx_auth_client/client.rb

@@ -0,0 +1,377 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "concurrent"
+require "json"
+require "time"
+
+require_relative "configuration"
+require_relative "errors"
+
+module TraylinxAuthClient
+  # Main client for interacting with Traylinx Sentinel Authentication.
+  # Handles token acquisition, management, and validation.
+  class Client
+    attr_reader :config
+
+    # Initializes the Client with configuration options.
+    #
+    # @param options [Hash, Configuration] Hash of options or Configuration object
+    # @option options [String] :client_id
+    # @option options [String] :client_secret
+    # @option options [String] :api_base_url
+    # @option options [String] :agent_user_id
+    def initialize(options = {})
+      @config = options.is_a?(Configuration) ? options : Configuration.new(options)
+      
+      # Token storage
+      @tokens = Concurrent::Map.new
+      @tokens[:access_token] = nil
+      @tokens[:agent_secret_token] = nil
+      @tokens[:expires_at] = nil
+      
+      # Mutex for token refresh synchronization
+      @refresh_mutex = Mutex.new
+
+      setup_connection
+    end
+
+    # Retrieves a valid Access Token (for Auth Service interaction).
+    # Refreshes the token if expired.
+    #
+    # @return [String] The JWT access token
+    # @raise [TokenExpiredError] if token cannot be obtained
+    def get_access_token
+      ensure_valid_tokens!
+      token = @tokens[:access_token]
+      raise TokenExpiredError, "Failed to obtain access token" unless token
+      token
+    end
+
+    # Retrieves a valid Agent Secret Token (for A2A communication).
+    # Refreshes the token if expired.
+    #
+    # @return [String] The agent secret token
+    # @raise [TokenExpiredError] if token cannot be obtained
+    def get_agent_secret_token
+      ensure_valid_tokens!
+      token = @tokens[:agent_secret_token]
+      raise TokenExpiredError, "Failed to obtain agent secret token" unless token
+      token
+    end
+
+    def get_request_headers
+      {
+        "Authorization" => "Bearer #{get_access_token}",
+        "X-Agent-Secret-Token" => get_agent_secret_token,
+        "X-Agent-User-Id" => @config.agent_user_id
+      }
+    end
+
+    def get_agent_request_headers
+      {
+        "X-Agent-Secret-Token" => get_agent_secret_token,
+        "X-Agent-User-Id" => @config.agent_user_id
+      }
+    end
+
+    def get_a2a_headers
+      {
+        "Authorization" => "Bearer #{get_agent_secret_token}",
+        "X-Agent-User-Id" => @config.agent_user_id
+      }
+    end
+
+    # Helper to perform a validated HTTP request to another agent.
+    # Automatically injects A2A headers (X-Agent-Secret-Token).
+    #
+    # @param method [Symbol] :get, :post, :put, :delete
+    # @param url [String] The full URL to call
+    # @param options [Hash] Request options
+    # @option options [Hash] :headers Additional headers
+    # @option options [Hash] :json JSON payload (for POST/PUT)
+    # @option options [Hash] :params Query parameters
+    # @option options [Integer] :timeout Request timeout
+    # @return [Hash, String] The response body (parsed JSON if applicable)
+    def make_a2a_request(method, url, options = {})
+      headers = get_agent_request_headers.merge(options[:headers] || {})
+      
+      response = Faraday.new(url: url) do |f|
+        f.request :json
+        f.response :json
+        f.adapter Faraday.default_adapter
+      end.send(method.to_s.downcase) do |req|
+        req.headers = headers
+        req.body = options[:json] if options[:json]
+        req.params = options[:params] if options[:params]
+        req.options.timeout = options[:timeout] || @config.timeout
+      end
+
+      handle_response(response)
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      raise NetworkError.new("Connection failed: #{e.message}", error_code: "CONNECTION_ERROR")
+    end
+
+    # Validates an Agent Secret Token against the Sentinel Introspection endpoint.
+    # Usage: When receiving a request from another agent.
+    #
+    # @param agent_secret_token [String] The token to validate
+    # @param agent_user_id [String] The agent ID claiming the token
+    # @return [Boolean] true if valid, false otherwise
+    def validate_token(agent_secret_token, agent_user_id)
+      # Validates against /oauth/agent/introspect using Access Token
+      
+      headers = {
+        "Authorization" => "Bearer #{get_access_token}",
+        "Content-Type" => "application/x-www-form-urlencoded"
+      }
+      
+      data = {
+        agent_secret_token: agent_secret_token,
+        agent_user_id: agent_user_id
+      }
+
+      response = @connection.post("oauth/agent/introspect") do |req|
+        req.headers = headers
+        req.body = data # Let middleware handle encoding
+        req.options.timeout = @config.timeout
+      end
+
+      if response.status == 200
+        body = response.body.is_a?(String) ? (JSON.parse(response.body) rescue {}) : response.body
+        return body["active"] == true
+      elsif response.status == 401
+        raise AuthenticationError.new("Access token invalid for token validation", status_code: 401)
+      else
+        handle_response(response) # Will raise appropriate error
+      end
+    rescue Faraday::Error => e
+      raise NetworkError.new("Token validation failed: #{e.message}")
+    end
+
+    def detect_auth_mode(headers)
+      # Normalize headers keys to downcase
+      headers = headers.transform_keys { |k| k.to_s.downcase }
+      
+      if headers["authorization"]&.start_with?("Bearer ")
+        "bearer"
+      elsif headers["x-agent-secret-token"]
+        "custom"
+      else
+        "none"
+      end
+    end
+
+    def validate_a2a_request(headers)
+      headers = headers.transform_keys { |k| k.to_s.downcase }
+      
+      # 1. Try Bearer token
+      if headers["authorization"]&.start_with?("Bearer ")
+        token = headers["authorization"].split(" ").last
+        agent_id = headers["x-agent-user-id"]
+        return validate_token(token, agent_id) if token && agent_id
+      end
+
+      # 2. Try Custom Header
+      token = headers["x-agent-secret-token"]
+      agent_id = headers["x-agent-user-id"]
+      
+      if token && agent_id
+        return validate_token(token, agent_id)
+      end
+
+      false
+    end
+
+    # =========================================================================
+    # Stargate P2P Identity Methods
+    # =========================================================================
+
+    def get_p2p_challenge(peer_id)
+      headers = {
+        "Authorization" => "Bearer #{get_access_token}",
+        "Content-Type" => "application/json"
+      }
+
+      response = @connection.get("a2a/p2p/challenge") do |req|
+        req.params = { peer_id: peer_id }
+        req.headers = headers
+        req.options.timeout = @config.timeout
+      end
+
+      body = handle_response(response)
+      body["challenge"]
+    rescue Faraday::Error => e
+      raise NetworkError.new("Failed to fetch P2P challenge: #{e.message}")
+    end
+
+    def certify_p2p_identity(peer_id, public_key, signature, challenge)
+      headers = {
+        "Authorization" => "Bearer #{get_access_token}",
+        "Content-Type" => "application/json"
+      }
+      
+      payload = {
+        peer_id: peer_id,
+        public_key: public_key,
+        signature: signature,
+        challenge: challenge
+      }
+
+      response = @connection.post("a2a/p2p/certify") do |req|
+        req.headers = headers
+        req.body = payload.to_json
+        req.options.timeout = @config.timeout
+      end
+
+      body = handle_response(response)
+      {
+        certificate: body["certificate"],
+        expires_at: body["expires_at"]
+      }
+    rescue Faraday::Error => e
+      raise NetworkError.new("Failed to certify P2P identity: #{e.message}")
+    end
+
+    # Generic RPC call
+    def rpc_call(method, params, rpc_url: nil, include_agent_credentials: nil)
+      default_rpc_url = "#{@config.api_base_url.chomp('/')}/a2a/rpc"
+      url = rpc_url || default_rpc_url
+      
+      # Auto-detect defaults matching Python SDK logic
+      if include_agent_credentials.nil?
+        # If URL is NOT the default Auth Service RPC URL, assume it's another agent => use agent creds
+        include_agent_credentials = (url != default_rpc_url)
+      end
+      
+      headers = {
+        "Content-Type" => "application/json"
+      }
+
+      if include_agent_credentials
+        headers["X-Agent-Secret-Token"] = get_agent_secret_token
+        headers["X-Agent-User-Id"] = @config.agent_user_id
+      else
+        headers["Authorization"] = "Bearer #{get_access_token}"
+      end
+
+      payload = {
+        jsonrpc: "2.0",
+        method: method,
+        params: params,
+        id: SecureRandom.uuid
+      }
+
+      response = Faraday.new(url: url) do |f|
+        f.request :json
+        f.response :json
+        f.adapter Faraday.default_adapter
+      end.post do |req|
+        req.headers = headers
+        req.body = payload
+        req.options.timeout = @config.timeout
+      end
+
+      body = handle_response(response)
+      
+      if body.is_a?(Hash) && body["error"]
+        raise TraylinxAuthError.new("RPC Error: #{body['error']['message']}", error_code: body['error']['code'])
+      end
+
+      body.is_a?(Hash) ? body["result"] : body
+    end
+
+    private
+
+    def setup_connection
+      base_url = @config.api_base_url
+      base_url = "#{base_url}/" unless base_url.end_with?("/")
+
+      @connection = Faraday.new(url: base_url) do |f|
+        f.request :json
+        f.request :url_encoded
+        f.response :json
+        f.request :retry, {
+          max: @config.max_retries,
+          interval: @config.retry_delay,
+          backoff_factor: 2,
+          retry_statuses: [429, 500, 502, 503, 504],
+          exceptions: [
+            Faraday::ConnectionFailed,
+            Faraday::TimeoutError,
+            Faraday::SSLError
+          ]
+        }
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def ensure_valid_tokens!
+      # return if tokens are valid (and we cache tokens)
+      return if @config.cache_tokens && valid_tokens?
+
+      @refresh_mutex.synchronize do
+        # double check inside lock
+        return if @config.cache_tokens && valid_tokens?
+        refresh_tokens!
+      end
+    end
+
+    def valid_tokens?
+      return false unless @tokens[:access_token]
+      return false unless @tokens[:expires_at]
+      
+      # Buffer of 60 seconds
+      Time.now.utc < (@tokens[:expires_at] - 60)
+    end
+
+    def refresh_tokens!
+      # Use relative path to ensure correct appending to base URL
+      response = @connection.post("oauth/token") do |req|
+        req.headers["Content-Type"] = "application/json"
+        req.body = {
+          grant_type: "client_credentials",
+          client_id: @config.client_id,
+          client_secret: @config.client_secret,
+          scope: "a2a"
+        }
+      end
+
+      if response.status == 200
+        data = response.body
+        # data keys might be strings or symbols depending on middleware
+        # Faraday middleware response :json parses with string keys by default usually?
+        # Actually standard practice is string keys unless configged
+        
+        # Safe access
+        data = data.transform_keys(&:to_s)
+        
+        @tokens[:access_token] = data["access_token"]
+        @tokens[:agent_secret_token] = data["agent_secret_token"]
+        
+        expires_in = data["expires_in"].to_i
+        @tokens[:expires_at] = Time.now.utc + expires_in
+      else
+        raise AuthenticationError.new(
+          "Valid credentials failed: #{response.body}",
+          status_code: response.status
+        )
+      end
+    rescue Faraday::Error => e
+      raise NetworkError.new("Network error during token refresh: #{e.message}")
+    end
+
+    def handle_response(response)
+      if response.success?
+        response.body
+      elsif response.status == 401
+        raise AuthenticationError.new("Authentication failed", status_code: 401)
+      elsif response.status == 403
+        raise AuthenticationError.new("Permission denied", status_code: 403)
+      else
+        raise NetworkError.new("Request failed: #{response.status}", status_code: response.status)
+      end
+    end
+  end
+end

data/lib/traylinx_auth_client/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module TraylinxAuthClient
+  # Configuration class for the client
+  class Configuration
+    attr_accessor :client_id, :client_secret, :api_base_url, :agent_user_id,
+                 :timeout, :max_retries, :retry_delay, :cache_tokens, :log_level
+
+    # Defaults matching Python/JS SDKs
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_RETRY_DELAY = 1.0
+    DEFAULT_CACHE_TOKENS = true
+    DEFAULT_LOG_LEVEL = :info
+
+    def initialize(options = {})
+      @client_id = options[:client_id] || ENV["TRAYLINX_CLIENT_ID"]
+      @client_secret = options[:client_secret] || ENV["TRAYLINX_CLIENT_SECRET"]
+      @api_base_url = options[:api_base_url] || ENV["TRAYLINX_API_BASE_URL"]
+      @agent_user_id = options[:agent_user_id] || ENV["TRAYLINX_AGENT_USER_ID"]
+      
+      @timeout = options[:timeout] || DEFAULT_TIMEOUT
+      @max_retries = options[:max_retries] || DEFAULT_MAX_RETRIES
+      @retry_delay = options[:retry_delay] || DEFAULT_RETRY_DELAY
+      @cache_tokens = options.key?(:cache_tokens) ? options[:cache_tokens] : DEFAULT_CACHE_TOKENS
+      @log_level = options[:log_level] || DEFAULT_LOG_LEVEL
+
+      validate!
+    end
+
+    def validate!
+      missing = []
+      missing << "client_id" unless @client_id
+      missing << "client_secret" unless @client_secret
+      missing << "api_base_url" unless @api_base_url
+      
+      # agent_user_id is needed for A2A but maybe valid to init without it for Auth 
+      # service checks? Following strict parity mostly requires it.
+      # For now, we'll mark it optional at init but required for A2A calls.
+      
+      unless missing.empty?
+        raise ValidationError.new("Missing required configuration: #{missing.join(', ')}")
+      end
+    end
+  end
+end

data/lib/traylinx_auth_client/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module TraylinxAuthClient
+  # Base error class for all TraylinxAuthClient errors
+  class TraylinxAuthError < StandardError
+    attr_reader :error_code, :status_code
+
+    def initialize(message, error_code: nil, status_code: nil)
+      super(message)
+      @error_code = error_code
+      @status_code = status_code
+    end
+  end
+
+  # Thrown for input validation failures
+  class ValidationError < TraylinxAuthError; end
+
+  # Thrown for authentication-related failures
+  class AuthenticationError < TraylinxAuthError; end
+
+  # Thrown when tokens are expired or unavailable
+  class TokenExpiredError < TraylinxAuthError; end
+
+  # Thrown for network-related issues
+  class NetworkError < TraylinxAuthError; end
+end

data/lib/traylinx_auth_client/middleware.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "client"
+
+module TraylinxAuthClient
+  # Rack Middleware for protecting endpoints with A2A auth.
+  # Intercepts requests and validates Authentication headers.
+  class Middleware
+    # @param app [Object] The Rack application
+    # @param client [TraylinxAuthClient::Client, nil] Optional pre-configured client
+    # @param validation_path [Regexp, String, nil] Optional regex/string to match paths requiring auth
+    def initialize(app, client: nil, validation_path: nil)
+      @app = app
+      @client = client || Client.new
+      @validation_path = validation_path
+    end
+
+    # Handles the incoming Rack request.
+    # @param env [Hash] The Rack environment
+    def call(env)
+      # Only validate if no specific path filtering is set, or if path matches
+      # This is simplified. Real middleware often takes an optional block or regex.
+      # For now, we assume if mounted, it protects everything unless configured.
+      
+      request = Rack::Request.new(env)
+      
+      # If validation_path is provided, only apply to that path
+      if @validation_path && !request.path.match?(@validation_path)
+        return @app.call(env)
+      end
+
+      # 1. Construct headers map from Rack environment
+      headers = extract_headers(request)
+
+      # 2. Validate using the unified client logic
+      # This handles Bearer tokens and custom headers with correct priority
+      if @client.validate_a2a_request(headers)
+        @app.call(env)
+      else
+        unauthorized_response("Invalid authentication credentials")
+      end
+    rescue => e
+      # Log error if possible
+      unauthorized_response("Authentication error: #{e.message}")
+    end
+
+    private
+
+    def extract_headers(request)
+      # Rack stores headers as HTTP_UPPERCASE_NAME
+      # We just need to reconstruct the relevant ones or pass a predictable hash
+      # validate_a2a_request handles case-insensitivity, so we just pass keys.
+      
+      {
+        "Authorization" => request.get_header("HTTP_AUTHORIZATION"),
+        "X-Agent-Secret-Token" => request.get_header("HTTP_X_AGENT_SECRET_TOKEN"),
+        "X-Agent-User-Id" => request.get_header("HTTP_X_AGENT_USER_ID")
+      }
+    end
+
+    def unauthorized_response(message)
+      [401, { "Content-Type" => "application/json" }, [{ error: message }.to_json]]
+    end
+  end
+end

data/lib/traylinx_auth_client/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TraylinxAuthClient
+  VERSION = "0.1.0"
+end

data/lib/traylinx_auth_client.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "traylinx_auth_client/version"
+require_relative "traylinx_auth_client/configuration"
+require_relative "traylinx_auth_client/client"
+require_relative "traylinx_auth_client/errors"
+require_relative "traylinx_auth_client/middleware"
+
+module TraylinxAuthClient
+  class << self
+    def configure
+      yield configuration
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def client
+      @client ||= Client.new(configuration)
+    end
+
+    # Reset client and configuration (useful for testing)
+    def reset!
+      @configuration = nil
+      @client = nil
+    end
+
+    # Proxy helper methods to the default client
+    def make_a2a_request(method, url, options = {})
+      client.make_a2a_request(method, url, options)
+    end
+  end
+end

metadata

@@ -0,0 +1,194 @@
+--- !ruby/object:Gem::Specification
+name: traylinx_auth_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Traylinx Team
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-01-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.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: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: A robust Ruby client for Traylinx Sentinel A2A authentication. Provides
+  secure token management, OAuth2 exchange, and Rack middleware.
+email:
+- dev@traylinx.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- PUBLISHING.md
+- README.md
+- lib/traylinx_auth_client.rb
+- lib/traylinx_auth_client/client.rb
+- lib/traylinx_auth_client/configuration.rb
+- lib/traylinx_auth_client/errors.rb
+- lib/traylinx_auth_client/middleware.rb
+- lib/traylinx_auth_client/version.rb
+homepage: https://github.com/traylinx/traylinx-auth-client-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/traylinx/traylinx-auth-client-ruby
+  source_code_uri: https://github.com/traylinx/traylinx-auth-client-ruby
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.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: Traylinx Sentinel Agent-to-Agent Authentication Client
+test_files: []