has_helpers 5.0.2

data/lib/has_helpers/service_trust/capability.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module ServiceTrust
+    class Capability
+      class << self
+        def parse(string_or_array)
+          Array(string_or_array).flat_map { |entry| entry.to_s.split(/\s+/) }.
+            reject(&:blank?).
+            uniq
+        end
+
+        def effective(token_caps:, allowed_caps:)
+          allowed = parse(allowed_caps)
+          token = parse(token_caps)
+          return allowed if token.empty?
+
+          token & allowed
+        end
+
+        def includes?(capability_set, required)
+          parse(capability_set).include?(required.to_s)
+        end
+
+        def any_match?(capability_set, required_list)
+          set = parse(capability_set)
+          Array(required_list).any? { |required| set.include?(required.to_s) }
+        end
+      end
+    end
+  end
+end

data/lib/has_helpers/service_trust/client/response.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module ServiceTrust
+    class Client
+      Response = Struct.new(:status, :headers, :body, :parsed, keyword_init: true) do
+        def success?
+          (200..299).cover?(status)
+        end
+      end
+    end
+  end
+end

data/lib/has_helpers/service_trust/client/retry.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module ServiceTrust
+    class Client
+      module Retry
+        DEFAULT_DELAYS = [0.2, 1.0, 5.0].freeze
+
+        module_function
+
+        def with_backoff(retries:, retry_on_status:)
+          attempt = 0
+
+          loop do
+            attempt += 1
+            begin
+              response = yield
+              return response if response.success?
+              raise ClientHTTPError.new(response.status, response.body) unless retry_on_status.include?(response.status)
+              raise ClientHTTPError.new(response.status, response.body) if attempt > retries
+            rescue ClientTimeoutError
+              raise if attempt > retries
+            end
+
+            sleep_for(attempt)
+          end
+        end
+
+        def sleep_for(attempt)
+          sleep(DEFAULT_DELAYS.fetch(attempt - 1, DEFAULT_DELAYS.last))
+        end
+      end
+    end
+  end
+end

data/lib/has_helpers/service_trust/client.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module HasHelpers
+  module ServiceTrust
+    class Client
+      HTTP_METHODS = {
+        get: Net::HTTP::Get,
+        post: Net::HTTP::Post,
+        put: Net::HTTP::Put,
+        delete: Net::HTTP::Delete
+      }.freeze
+
+      # @param retries [Integer] number of additional retry attempts; total attempts up to retries + 1.
+      def initialize(audience:, base_url:, timeout: 5, retries: 3, retry_on_status: [502, 503, 504])
+        @audience = audience
+        @base_url = base_url
+        @timeout = timeout
+        @retries = retries
+        @retry_on_status = retry_on_status
+      end
+
+      def get(path, capability: nil, headers: {}, query: nil)
+        call(:get, path, capability: capability, headers: headers, query: query)
+      end
+
+      def post(path, body:, capability: nil, headers: {})
+        call(:post, path, capability: capability, headers: headers, body: body)
+      end
+
+      def put(path, body:, capability: nil, headers: {})
+        call(:put, path, capability: capability, headers: headers, body: body)
+      end
+
+      def delete(path, capability: nil, headers: {}, query: nil)
+        call(:delete, path, capability: capability, headers: headers, query: query)
+      end
+
+      private
+
+      def call(method, path, capability:, headers:, body: nil, query: nil)
+        uri = build_uri(path, query)
+        enforce_tls!(uri)
+
+        Retry.with_backoff(retries: @retries, retry_on_status: @retry_on_status) do
+          response = perform(method, uri, headers: headers, body: body, capability: capability)
+          audit_response(response)
+          response
+        end
+      end
+
+      def perform(method, uri, headers:, body:, capability:)
+        request_class = HTTP_METHODS.fetch(method)
+        request = request_class.new(uri.request_uri)
+        BearerToken.apply!(request, Signer.bearer_header(audience: @audience, capability: capability))
+        headers.each { |key, value| request[key] = value }
+
+        if body
+          request["Content-Type"] ||= "application/json"
+          request.body = body.is_a?(String) ? body : JSON.generate(body)
+        end
+
+        raw = Net::HTTP.start(
+          uri.host,
+          uri.port,
+          use_ssl: uri.scheme == "https",
+          verify_mode: OpenSSL::SSL::VERIFY_PEER,
+          open_timeout: @timeout,
+          read_timeout: @timeout
+        ) { |http| http.request(request) }
+
+        Response.new(
+          status: raw.code.to_i,
+          headers: raw.to_hash,
+          body: raw.body,
+          parsed: safe_parse_json(raw.body)
+        )
+      rescue *JwksClient::NETWORK_ERRORS, Timeout::Error => e
+        raise ClientTimeoutError, "#{e.class}: #{e.message}"
+      end
+
+      def build_uri(path, query)
+        base = @base_url.end_with?("/") ? @base_url : "#{@base_url}/"
+        uri = URI.join(base, path.to_s.delete_prefix("/"))
+        params = query.to_h
+        uri.query = URI.encode_www_form(params) if params.any?
+        uri
+      end
+
+      def enforce_tls!(uri)
+        return if uri.scheme == "https"
+        return if uri.scheme == "http" && localhost?(uri.host) && dev_or_test?
+
+        raise OutboundTLSError, "service trust client endpoint must use HTTPS"
+      end
+
+      def safe_parse_json(body)
+        return nil if body.blank?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def audit_response(response)
+        Audit.record!(
+          payload: { "iss" => HasHelpers::ServiceTrust.config.issuer, "aud" => @audience },
+          outcome: response.success? ? "accepted" : "rejected",
+          direction: "outbound",
+          rejection_reason: response.success? ? nil : "HTTP#{response.status}"
+        )
+      end
+
+      def localhost?(host)
+        ["localhost", "127.0.0.1", "::1", "host.docker.internal"].include?(host)
+      end
+
+      def dev_or_test?
+        env = HasHelpers::ServiceTrust.config.environment.to_s
+        env == "development" || env == "test"
+      end
+    end
+  end
+end

data/lib/has_helpers/service_trust/configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module ServiceTrust
+    TrustedIssuer = Struct.new(:name, :url, :allowed_capabilities, keyword_init: true)
+
+    class Configuration
+      attr_accessor :issuer,
+                    :environment,
+                    :private_key_env,
+                    :kid_env,
+                    :key_environment_env,
+                    :token_ttl,
+                    :max_token_ttl,
+                    :clock_skew,
+                    :replay_cache_redis,
+                    :rate_limit_per_issuer,
+                    :audit_log_retention,
+                    :audit_async,
+                    :jwks_cache_ttl,
+                    :jwks_stale_ttl
+
+      def initialize
+        @issuer = nil
+        @environment = defined?(Rails) ? Rails.env : "development"
+        @private_key_env = "SERVICE_TRUST_PRIVATE_KEY"
+        @kid_env = "SERVICE_TRUST_KEY_ID"
+        @key_environment_env = "SERVICE_TRUST_KEY_ENVIRONMENT"
+        @token_ttl = 60.seconds
+        @max_token_ttl = 5.minutes
+        @clock_skew = 30.seconds
+        @trusted_issuer_block = nil
+        @replay_cache_redis = -> { RedisConf.current }
+        @rate_limit_per_issuer = { requests: 100, per: 1.minute }
+        @audit_log_retention = 30.days
+        @audit_async = false
+        @jwks_cache_ttl = 1.hour
+        @jwks_stale_ttl = 5.minutes
+      end
+
+      def trusted_issuers(&block)
+        @trusted_issuer_block = block if block
+        resolved_trusted_issuers
+      end
+
+      def trusted?(issuer_name)
+        trusted_issuer(issuer_name).present?
+      end
+
+      def trusted_issuer(issuer_name)
+        resolved_trusted_issuers[issuer_name.to_s]
+      end
+
+      def env
+        environment.respond_to?(:to_sym) && defined?(ActiveSupport::StringInquirer) ? ActiveSupport::StringInquirer.new(environment.to_s) : environment
+      end
+
+      private
+
+      def resolved_trusted_issuers
+        registry = {}
+        return registry unless @trusted_issuer_block
+
+        register = lambda do |name, url:, allowed_capabilities: []|
+          registry[name.to_s] = TrustedIssuer.new(
+            name: name.to_s,
+            url: url.to_s,
+            allowed_capabilities: Capability.parse(allowed_capabilities)
+          )
+        end
+        @trusted_issuer_block.call(env, register)
+        registry
+      end
+    end
+  end
+end

data/lib/has_helpers/service_trust/engine.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module ServiceTrust
+    class Engine < ::Rails::Engine
+      isolate_namespace HasHelpers::ServiceTrust
+      config.paths["config/routes.rb"] = "config/service_trust_routes.rb"
+    end
+  end
+end

data/lib/has_helpers/service_trust/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module ServiceTrust
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+    class UntrustedIssuerError < Error; end
+    class InvalidTokenError < Error; end
+    class InvalidSignatureError < Error; end
+    class TokenExpiredError < Error; end
+    class AudienceMismatchError < Error; end
+    class ReplayDetectedError < Error; end
+    class RateLimitedError < Error; end
+    class TLSRequiredError < Error; end
+    class OutboundTLSError < Error; end
+    class JwksUnavailableError < Error; end
+    class InsufficientCapabilityError < Error; end
+    class ClientError < Error; end
+    class ClientTimeoutError < ClientError; end
+    class GraphQLClientError < ClientError; end
+
+    class ClientHTTPError < ClientError
+      attr_reader :status, :body
+
+      def initialize(status, body, message = nil)
+        @status = status
+        @body = body
+        super(message || "HTTP #{status}")
+      end
+    end
+  end
+end

data/lib/has_helpers/service_trust/graphql/authorizable.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module ServiceTrust
+    module GraphQL
+      module Authorizable
+        extend ActiveSupport::Concern
+
+        included do
+          class_attribute :_service_trust_capability, default: nil
+          class_attribute :_service_trust_capability_any, default: nil
+        end
+
+        class_methods do
+          def service_trust_capability(name)
+            self._service_trust_capability = name
+            self._service_trust_capability_any = nil
+          end
+
+          def service_trust_capability_any(list)
+            array = Array(list)
+            if array.include?(:none)
+              raise ArgumentError,
+                    "service_trust_capability_any does not accept :none; use service_trust_capability :none for identity-only operations"
+            end
+            self._service_trust_capability_any = array.map(&:to_s)
+            self._service_trust_capability = nil
+          end
+
+          def declared_service_trust_capability
+            _service_trust_capability
+          end
+
+          def declared_service_trust_capability_any
+            _service_trust_capability_any
+          end
+        end
+
+        def authorized?(*args)
+          return super unless context[:service_trust]
+
+          authorize_service_trust!
+          super()
+        rescue HasHelpers::ServiceTrust::InsufficientCapabilityError => e
+          raise ::GraphQL::ExecutionError, e.message
+        end
+
+        private
+
+        def authorize_service_trust!
+          single = self.class.declared_service_trust_capability
+          any = self.class.declared_service_trust_capability_any
+
+          if single.nil? && any.nil?
+            raise HasHelpers::ServiceTrust::InsufficientCapabilityError,
+                  "service_trust_capability not declared for #{self.class.name}"
+          end
+
+          caps = context[:service_trust][:capabilities] || []
+
+          if single
+            HasHelpers::ServiceTrust::Authorization.require!({ capabilities: caps }, capability: single)
+          elsif any
+            HasHelpers::ServiceTrust::Authorization.require_any!({ capabilities: caps }, capabilities: any)
+          end
+        end
+      end
+    end
+
+    Graphql = GraphQL unless const_defined?(:Graphql, false)
+  end
+end

data/lib/has_helpers/service_trust/graphql_client.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module ServiceTrust
+    class GraphQLClient
+      Result = Struct.new(:data, :errors, :extensions, keyword_init: true) do
+        def success?
+          errors.blank?
+        end
+
+        def raise_on_errors!
+          return if success?
+
+          raise GraphQLClientError, "GraphQL errors: #{errors.map { |error| error['message'] }.join('; ')}"
+        end
+      end
+
+      def initialize(audience:, base_url:, path: "/internal_graphql", client: nil)
+        @audience = audience
+        @path = path
+        @client = client || Client.new(audience: audience, base_url: base_url)
+      end
+
+      def query(document, variables: {}, operation_name: nil, capability: nil)
+        response = @client.post(
+          @path,
+          body: { query: document, variables: variables, operationName: operation_name }.compact,
+          capability: capability
+        )
+        raise GraphQLClientError, "HTTP #{response.status}" unless response.success?
+
+        parsed = response.parsed || {}
+        result = Result.new(data: parsed["data"], errors: parsed["errors"] || [], extensions: parsed["extensions"])
+        record_graphql_errors!(result)
+        result
+      end
+
+      private
+
+      def record_graphql_errors!(result)
+        return if result.success?
+
+        Audit.record!(
+          payload: { "iss" => HasHelpers::ServiceTrust.config.issuer, "aud" => @audience },
+          outcome: "rejected",
+          direction: "outbound",
+          rejection_reason: "GraphQLErrors"
+        )
+      end
+    end
+
+    GraphqlClient = GraphQLClient unless const_defined?(:GraphqlClient, false)
+  end
+end

data/lib/has_helpers/service_trust/jwks_client.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "openssl"
+require "monitor"
+
+module HasHelpers
+  module ServiceTrust
+    class JwksClient
+      CacheEntry = Struct.new(:keys, :expires_at, :stale_until, keyword_init: true)
+
+      NETWORK_ERRORS = [
+        Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+        Errno::ENETUNREACH, Errno::ETIMEDOUT, EOFError, IOError,
+        SocketError, Timeout::Error,
+        Net::OpenTimeout, Net::ReadTimeout, Net::HTTPError,
+        OpenSSL::SSL::SSLError
+      ].freeze
+
+      class << self
+        def public_key_for(issuer, kid)
+          stub = Test.public_key_for(issuer, kid) if Test.enabled?
+          return stub if stub
+
+          jwk = fetch_keys_for(issuer).find { |key| key["kid"] == kid.to_s }
+          raise InvalidSignatureError, "unknown key id" unless jwk
+
+          JWT::JWK.import(jwk).public_key
+        rescue JWT::JWKError => e
+          raise InvalidSignatureError, e.message
+        end
+
+        def fetch_keys_for(issuer)
+          trusted = HasHelpers::ServiceTrust.config.trusted_issuer(issuer)
+          raise UntrustedIssuerError, "untrusted issuer" unless trusted
+
+          cache_key = issuer.to_s
+
+          fresh = monitor.synchronize { cache_hit(cache_key) }
+          return fresh if fresh
+
+          begin
+            fetch_and_cache(cache_key, trusted.url)
+          rescue *NETWORK_ERRORS => e
+            stale = monitor.synchronize { stale_hit(cache_key) }
+            return stale if stale
+
+            raise JwksUnavailableError, "jwks fetch failed: #{e.class}: #{e.message}"
+          rescue OutboundTLSError, JwksUnavailableError
+            stale = monitor.synchronize { stale_hit(cache_key) }
+            return stale if stale
+
+            raise
+          end
+        end
+
+        def clear_cache!
+          monitor.synchronize { memory_cache.clear }
+        end
+
+        private
+
+        def cache_hit(cache_key)
+          entry = memory_cache[cache_key]
+          return nil unless entry
+          return entry.keys if Time.current < entry.expires_at
+
+          nil
+        end
+
+        def stale_hit(cache_key)
+          entry = memory_cache[cache_key]
+          return nil unless entry
+          return entry.keys if Time.current < entry.stale_until
+
+          nil
+        end
+
+        def fetch_and_cache(cache_key, base_url)
+          uri = URI.join(base_url.end_with?("/") ? base_url : "#{base_url}/", ".well-known/jwks.json")
+          enforce_tls!(uri)
+          response = http_get(uri)
+          raise JwksUnavailableError, "jwks endpoint returned #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+          parsed = JSON.parse(response.body)
+          keys = parsed.fetch("keys")
+          monitor.synchronize do
+            memory_cache[cache_key] = CacheEntry.new(
+              keys: keys,
+              expires_at: Time.current + HasHelpers::ServiceTrust.config.jwks_cache_ttl,
+              stale_until: Time.current + HasHelpers::ServiceTrust.config.jwks_cache_ttl + HasHelpers::ServiceTrust.config.jwks_stale_ttl
+            )
+          end
+          keys
+        rescue JSON::ParserError, KeyError => e
+          Rails.logger.error("ServiceTrust JWKS parse failure: #{e.message}") if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          raise JwksUnavailableError, "invalid jwks response"
+        end
+
+        def enforce_tls!(uri)
+          return if uri.scheme == "https"
+          return if uri.scheme == "http" && localhost?(uri.host) && dev_or_test?
+
+          raise OutboundTLSError, "jwks endpoint must use HTTPS"
+        end
+
+        def http_get(uri)
+          Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", verify_mode: OpenSSL::SSL::VERIFY_PEER) do |http|
+            http.get(uri.request_uri)
+          end
+        end
+
+        def localhost?(host)
+          ["localhost", "127.0.0.1", "::1", "host.docker.internal"].include?(host)
+        end
+
+        def dev_or_test?
+          env = HasHelpers::ServiceTrust.config.environment.to_s
+          env == "development" || env == "test"
+        end
+
+        def memory_cache
+          @memory_cache ||= {}
+        end
+
+        def monitor
+          @monitor ||= Monitor.new
+        end
+      end
+    end
+  end
+end

data/lib/has_helpers/service_trust/jwt_codec.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module ServiceTrust
+    class JwtCodec
+      ALLOWED_ALGORITHMS = %w[RS256 EdDSA].freeze
+
+      class << self
+        def encode(payload, private_key, kid, alg: "RS256")
+          assert_allowed_algorithm!(alg)
+          JWT.encode(payload, private_key, alg, kid: kid, typ: "JWT")
+        end
+
+        def peek(token)
+          payload, header = JWT.decode(token, nil, false)
+          [header, payload]
+        rescue JWT::DecodeError => e
+          raise InvalidTokenError, e.message
+        end
+
+        def decode!(token, public_key, alg:)
+          assert_allowed_algorithm!(alg)
+          payload, = JWT.decode(
+            token,
+            public_key,
+            true,
+            algorithm: alg,
+            leeway: HasHelpers::ServiceTrust.config.clock_skew.to_i
+          )
+          payload
+        rescue JWT::ExpiredSignature => e
+          raise TokenExpiredError, e.message
+        rescue JWT::ImmatureSignature, JWT::DecodeError => e
+          raise InvalidSignatureError, e.message
+        end
+
+        def assert_allowed_algorithm!(alg)
+          return if ALLOWED_ALGORITHMS.include?(alg.to_s)
+
+          raise InvalidSignatureError, "unsupported JWT algorithm"
+        end
+      end
+    end
+  end
+end