kessel-sdk 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f43583b533d5d6a129442d7ec9ace5ff0a868873825202638b49fe249aa84dc4
-  data.tar.gz: 3df5445af055fc5f47f092dce4c374a1aa55fa7a62e5d33d85759d4563c2a03f
+  metadata.gz: 3800bae939865b2cd83bfb60a4587e80c946506209ea91a137ffa595a94ae771
+  data.tar.gz: bfdff251174a21a9e719e1cf82ff5c861f7092c2017e0b3770aac264cfc0eee1
 SHA512:
-  metadata.gz: fc5b79adf8619a5a3e7046f915fb0216da469f98e389a3d4cf7b938959fe6376d9626d7592bdd4d275c8716e2ebdcc5cfc9fae4dc7f73c0b87a0952fb9199682
-  data.tar.gz: 0bae7e47c009b42b469dbda597785837d0a476b00b10d775c441653da7ec2019f682c20e2ddb6839d7155ee7f200897009b93651b99f9f60bfb89df777cc3c45
+  metadata.gz: 1e727e72dc99cc3f98411a0913695259fa21aefbe8189862a5c55ccab8f8419462777d8e7d7ec96453030eada05cb28ea0b85e15ad306aac9aeb547810bbf3c4
+  data.tar.gz: b80c52e4e3f8632499df4eb95f409067662e02763dfa8fc52056961ab2fd3edf8894ab8e9abf5f580792e335b43294e4a3250707efd1a14c32fb93743808c816

data/README.md

@@ -1,5 +1,7 @@
 # Kessel SDK for Ruby
 
+[![CI](https://github.com/project-kessel/kessel-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/project-kessel/kessel-sdk-ruby/actions/workflows/ci.yml)
+
 A Ruby gRPC library for connecting to [Project Kessel](https://github.com/project-kessel) services. This provides the foundational gRPC client library for Kessel Inventory API, with plans for a higher-level SDK with fluent APIs, OAuth support, and advanced features in future releases.
 
 ## Installation
@@ -22,6 +24,15 @@ Or install it yourself as:
 gem install kessel-sdk
 ```
 
+## Authentication (Optional)
+
+The SDK supports OAuth 2.0 Client Credentials flow. To use authentication features, add the OpenID Connect gem:
+
+```ruby
+gem 'kessel-sdk'
+gem 'openid_connect', '~> 2.0'  # Optional - only for authentication
+```
+
 ## Usage
 
 This library provides direct access to Kessel Inventory API gRPC services. All generated classes are available under the `Kessel::Inventory` module.
@@ -130,11 +141,22 @@ All protobuf message classes are generated and available. Key classes include:
 
 See the `examples/` directory for complete working examples.
 
+## Type Safety
+
+This library includes RBS type signatures for enhanced type safety in Ruby. The type definitions are located in the `sig/` directory and cover:
+
+- Core library interfaces
+- Configuration structures  
+- OAuth authentication classes
+- gRPC client builders
+
+To use with type checkers like Steep or Sorbet, ensure the `sig/` directory is in your type checking configuration.
+
 ## Development
 
 ### Prerequisites
 
-- Ruby 3.3 or higher
+- Ruby 3.3 or higher  
 - [buf](https://buf.build) for protobuf/gRPC code generation
 
 Install buf:
@@ -158,6 +180,22 @@ bundle install
 buf generate
 ```
 
+### Testing
+
+```bash
+# Run tests
+bundle exec rspec
+
+# Run with coverage
+COVERAGE=1 bundle exec rspec
+
+# Run linting
+bundle exec rubocop
+
+# Security audit
+bundle exec bundle-audit
+```
+
 ### Code Generation
 
 This library uses [buf](https://buf.build) to generate Ruby gRPC code from the official Kessel Inventory API protobuf definitions hosted at `buf.build/project-kessel/inventory-api`.

data/lib/kessel/auth.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'grpc'
+require 'kessel/version'
+
+module Kessel
+  # OpenID Connect authentication module for Kessel services.
+  #
+  # This module provides OIDC Client Credentials flow authentication
+  # with automatic discovery. Works seamlessly with OIDC-compliant providers.
+  #
+  # @example Basic usage
+  #   auth = Kessel::Auth::OAuth2ClientCredentials.new.new(
+  #     client_id: 'my-app',
+  #     client_secret: 'secret',
+  #     token_endpoint: 'https://my-domain/auth/realms/my-realm/protocol/openid-connect/token'
+  #   )
+  #   token = auth.get_token
+  #
+  # @author Project Kessel
+  # @since 1.0.0
+  module Auth
+    EXPIRATION_WINDOW = 300 # 5 minutes in seconds
+    DEFAULT_EXPIRES_IN = 3600 # 1 hour in seconds
+
+    # Exception raised when OAuth functionality is requested but dependencies are missing.
+    class OAuthDependencyError < StandardError
+      # Creates a new OAuth dependency error.
+      #
+      # @param message [String] Error message describing the missing dependency
+      def initialize(message = 'OAuth functionality requires the openid_connect gem')
+        super
+      end
+    end
+
+    # Exception raised when OAuth authentication fails.
+    class OAuthAuthenticationError < StandardError
+      # Creates a new OAuth authentication error.
+      #
+      # @param message [String] Error message describing the authentication failure
+      def initialize(message = 'OAuth authentication failed')
+        super
+      end
+    end
+
+    OIDCDiscoveryMetadata = Struct.new(:token_endpoint)
+    RefreshTokenResponse = Struct.new(:access_token, :expires_at)
+
+    def fetch_oidc_discovery(provider_url)
+      check_dependencies!
+      discovery = ::OpenIDConnect::Discovery::Provider::Config.discover!(provider_url)
+      OIDCDiscoveryMetadata.new(discovery.token_endpoint)
+    rescue StandardError => e
+      raise OAuthAuthenticationError, "Failed to discover OIDC configuration from #{provider_url}: #{e.message}"
+    end
+
+    # Checks if the openid_connect gem is available.
+    #
+    # @raise [OAuthDependencyError] if openid_connect gem is missing
+    # @api private
+    private
+
+    def check_dependencies!
+      require 'openid_connect'
+    rescue LoadError
+      raise OAuthDependencyError,
+            'OAuth functionality requires the openid_connect gem. Add "gem \'openid_connect\'" to your Gemfile.'
+    end
+
+    # OpenID Connect Client Credentials flow implementation using discovery.
+    #
+    # This provides a secure OIDC Client Credentials flow implementation with
+    # automatic endpoint discovery. Works seamlessly with OIDC-compliant providers
+    # that support discovery.
+    #
+    # @example
+    #   oauth = OAuth2ClientCredentials.new(
+    #     client_id: 'kessel-client',
+    #     client_secret: 'super-secret-key',
+    #     token_endpoint: 'https://my-domain/auth/realms/my-realm/protocol/openid-connect/token'
+    #   )
+    #
+    #   # Get current access token (automatically cached and refreshed)
+    #   token = oauth.get_token
+    class OAuth2ClientCredentials
+      include Kessel::Auth
+
+      # Creates a new OIDC client with specified token endpoint.
+      #
+      # @param client_id [String] OIDC client identifier
+      # @param client_secret [String] OIDC client secret
+      # @param token_endpoint [String] OIDC token endpoint URL
+      #
+      # @raise [OAuthDependencyError] if the openid_connect gem is not available
+      # @raise [OAuthAuthenticationError] if authentication fails
+      #
+      # @example
+      #   oauth = OAuth2ClientCredentials.new(
+      #     client_id: 'my-app',
+      #     client_secret: 'secret',
+      #     token_endpoint: 'https://my-domain/auth/realms/my-realm/protocol/openid-connect/token'
+      #   )
+      def initialize(client_id:, client_secret:, token_endpoint:)
+        check_dependencies!
+
+        @client_id = client_id
+        @client_secret = client_secret
+        @token_endpoint = token_endpoint
+        @token_mutex = Mutex.new
+      end
+
+      # Gets the current access token with automatic caching and refresh.
+      #
+      # Uses OIDC Client Credentials flow with automatic token caching,
+      # expiration checking, and refresh logic.
+      #
+      # @return [RefreshTokenResponse] A valid access token
+      # @raise [OAuthAuthenticationError] if token acquisition fails
+      #
+      # @example
+      #   token = oauth.get_token
+      #   # Use token in Authorization header: "Bearer #{token}"
+      def get_token(force_refresh: false)
+        return @cached_token if !force_refresh && token_valid?
+
+        @token_mutex.synchronize do
+          @cached_token = nil if force_refresh
+
+          # Double-check: another thread might have refreshed the token
+          return @cached_token if token_valid?
+
+          @cached_token = refresh
+
+          return @cached_token
+        rescue StandardError => e
+          raise OAuthAuthenticationError, "Failed to obtain client credentials token: #{e.message}"
+        end
+      end
+
+      private
+
+      def refresh
+        client = create_oidc_client
+
+        request_params = {
+          grant_type: 'client_credentials',
+          client_id: @client_id,
+          client_secret: @client_secret
+        }
+
+        token_data = client.access_token!(request_params)
+        RefreshTokenResponse.new(
+          access_token: token_data.access_token,
+          expires_at: Time.now + (token_data.expires_in || DEFAULT_EXPIRES_IN)
+        ).freeze
+      end
+
+      # Checks if we have a valid cached token.
+      #
+      # @return [Boolean] true if token exists and not expired
+      def token_valid?
+        return false unless @cached_token
+
+        expires_at = @cached_token['expires_at']
+        return false unless expires_at
+
+        Time.now.to_i + EXPIRATION_WINDOW < expires_at.to_i
+      rescue StandardError
+        false
+      end
+
+      # Creates an OIDC client using discovered configuration.
+      #
+      # @return [OpenIDConnect::Client] Configured OIDC client
+      # @api private
+      def create_oidc_client
+        ::OpenIDConnect::Client.new(
+          identifier: @client_id,
+          secret: @client_secret,
+          token_endpoint: @token_endpoint
+        )
+      end
+    end
+  end
+end

data/lib/kessel/grpc.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'kessel/auth'
+require 'grpc'
+
+module Kessel
+  module GRPC
+    def oauth2_call_credentials(auth)
+      call_credentials_proc = proc do |metadata|
+        token = auth.get_token
+        metadata.merge('authorization' => "Bearer #{token.access_token}")
+      end
+      ::GRPC::Core::CallCredentials.new(call_credentials_proc)
+    end
+  end
+end

data/lib/kessel/inventory/v1.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'kessel/inventory'
+require 'kessel/inventory/v1/health_services_pb'
+
+include Kessel::Inventory
+
+module Kessel
+  module Inventory
+    module V1
+      module KesselInventoryHealthService
+        ClientBuilder = ::Kessel::Inventory.client_builder_for_stub(Stub)
+      end
+    end
+  end
+end

data/lib/kessel/inventory/v1beta1.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'kessel/inventory'
+require 'kessel/inventory/v1beta1/relationships/k8spolicy_ispropagatedto_k8scluster_service_services_pb'
+require 'kessel/inventory/v1beta1/resources/k8s_clusters_service_services_pb'
+require 'kessel/inventory/v1beta1/resources/k8s_policies_service_services_pb'
+
+include Kessel::Inventory
+
+module Kessel
+  module Inventory
+    module V1beta1
+      module Relationships
+        module KesselK8SPolicyIsPropagatedToK8SClusterService
+          ClientBuilder = ::Kessel::Inventory.client_builder_for_stub(Stub)
+        end
+      end
+
+      module Resources
+        module KesselK8sClusterService
+          ClientBuilder = ::Kessel::Inventory.client_builder_for_stub(Stub)
+        end
+
+        module KesselK8sPolicyService
+          ClientBuilder = ::Kessel::Inventory.client_builder_for_stub(Stub)
+        end
+      end
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'kessel/inventory'
+require 'kessel/inventory/v1beta2/inventory_service_services_pb'
+
+include Kessel::Inventory
+
+module Kessel
+  module Inventory
+    module V1beta2
+      module KesselInventoryService
+        ClientBuilder = ::Kessel::Inventory.client_builder_for_stub(Stub)
+      end
+    end
+  end
+end

data/lib/kessel/inventory.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'grpc'
+require 'kessel/grpc'
+
+module Kessel
+  module Inventory
+    def client_builder_for_stub(stub_class)
+      builder_class = Class.new(ClientBuilder)
+      builder_class.instance_variable_set(:@stub_class, stub_class)
+      builder_class
+    end
+
+    class ClientBuilder
+      include Kessel::GRPC
+
+      def initialize(target)
+        @target = target
+        raise 'Invalid target type' if @target.nil? || !@target.is_a?(String)
+      end
+
+      def oauth2_client_authenticated(oauth2_client_credentials:, channel_credentials: nil)
+        @call_credentials = oauth2_call_credentials(oauth2_client_credentials)
+        @channel_credentials = channel_credentials
+        validate_credentials
+        self
+      end
+
+      def authenticated(call_credentials: nil, channel_credentials: nil)
+        @call_credentials = call_credentials
+        @channel_credentials = channel_credentials
+        validate_credentials
+        self
+      end
+
+      def unauthenticated(channel_credentials: nil)
+        @call_credentials = nil
+        @channel_credentials = channel_credentials
+        validate_credentials
+        self
+      end
+
+      def insecure
+        @call_credentials = nil
+        @channel_credentials = :this_channel_is_insecure
+        validate_credentials
+        self
+      end
+
+      def build
+        @channel_credentials = ::GRPC::Core::ChannelCredentials.new if @channel_credentials.nil?
+
+        credentials = @channel_credentials
+        credentials = credentials.compose(@call_credentials) unless @call_credentials.nil?
+        self.class.stub_class.new(@target, credentials)
+      end
+
+      private
+
+      class << self
+        attr_reader :stub_class
+      end
+
+      def validate_credentials
+        return unless @channel_credentials == :this_channel_is_insecure && !@call_credentials.nil?
+
+        raise 'Invalid credential configuration: can not authenticate with insecure channel'
+      end
+    end
+  end
+end

data/lib/kessel/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Kessel
   module Inventory
-    VERSION = "1.0.0".freeze
+    VERSION = '1.2.0'
   end
 end

data/lib/kessel-sdk.rb

@@ -1,3 +1,9 @@
-Dir.glob(File.join(__dir__, '**', '*_services_pb.rb')).sort.each do |file|
-  require file.sub(__dir__ + File::SEPARATOR, '')
-end
+# frozen_string_literal: true
+
+require 'kessel/version'
+require 'kessel/grpc'
+require 'kessel/auth'
+
+require 'kessel/inventory/v1'
+require 'kessel/inventory/v1beta1'
+require 'kessel/inventory/v1beta2'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kessel-sdk
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Project Kessel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-16 00:00:00.000000000 Z
+date: 2025-08-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: grpc
@@ -24,6 +24,174 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.73.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+- !ruby/object:Gem::Dependency
+  name: rack
+  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: rackup
+  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'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: steep
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.10.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.10.0
+- !ruby/object:Gem::Dependency
+  name: typeprof
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.30.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.30.1
 description: This is the official Ruby SDK for [Project Kessel](https://github.com/project-kessel),
   a system for unifying APIs and experiences with fine-grained authorization, common
   inventory, and CloudEvents.
@@ -41,8 +209,13 @@ files:
 - lib/google/api/field_behavior_pb.rb
 - lib/google/api/http_pb.rb
 - lib/kessel-sdk.rb
+- lib/kessel/auth.rb
+- lib/kessel/grpc.rb
+- lib/kessel/inventory.rb
+- lib/kessel/inventory/v1.rb
 - lib/kessel/inventory/v1/health_pb.rb
 - lib/kessel/inventory/v1/health_services_pb.rb
+- lib/kessel/inventory/v1beta1.rb
 - lib/kessel/inventory/v1beta1/authz/check_pb.rb
 - lib/kessel/inventory/v1beta1/authz/check_services_pb.rb
 - lib/kessel/inventory/v1beta1/authz/common_pb.rb
@@ -64,6 +237,7 @@ files:
 - lib/kessel/inventory/v1beta1/resources/metadata_pb.rb
 - lib/kessel/inventory/v1beta1/resources/reporter_data_pb.rb
 - lib/kessel/inventory/v1beta1/resources/resource_label_pb.rb
+- lib/kessel/inventory/v1beta2.rb
 - lib/kessel/inventory/v1beta2/allowed_pb.rb
 - lib/kessel/inventory/v1beta2/check_for_update_request_pb.rb
 - lib/kessel/inventory/v1beta2/check_for_update_response_pb.rb
@@ -94,8 +268,8 @@ licenses:
 - Apache-2.0
 metadata:
   homepage_uri: https://github.com/project-kessel/kessel-sdk-ruby
-  source_code_uri: https://github.com/project-kessel/kessel-sdk-ruby
   bug_tracker_uri: https://github.com/project-kessel/kessel-sdk-ruby/issues
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths: