rubino-agent 0.3.0

data/lib/rubino/oauth/provider.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "digest"
+require "base64"
+require "oauth2"
+
+module Rubino
+  module OAuth
+    # Abstract OAuth 2.0 provider. Subclasses declare endpoints + default scopes
+    # and implement #fetch_account_info to populate account_id/account_email
+    # after a successful token exchange.
+    #
+    # Configured per-provider with client_id, client_secret, scopes from
+    # rubino.yml. PKCE (S256) is enabled by default for the auth_code flow.
+    # The agent is stateless across the redirect: the client persists the
+    # returned +state+ and +code_verifier+ between connect and callback.
+    class Provider
+      attr_reader :client_id, :client_secret, :scopes, :metadata
+
+      def self.id
+        raise NotImplementedError
+      end
+
+      def self.display_name
+        id.to_s.capitalize
+      end
+
+      def self.site
+        raise NotImplementedError
+      end
+
+      def self.authorize_path
+        raise NotImplementedError
+      end
+
+      def self.token_path
+        raise NotImplementedError
+      end
+
+      def self.default_scopes
+        []
+      end
+
+      def initialize(client_id:, client_secret:, scopes: nil, metadata: {})
+        @client_id = client_id
+        @client_secret = client_secret
+        @scopes = (scopes || self.class.default_scopes).map(&:to_s)
+        @metadata = metadata
+      end
+
+      def id
+        self.class.id
+      end
+
+      # Build the authorize URL the client must redirect the user to.
+      #
+      # The returned +state+ and +code_verifier+ MUST be persisted by the
+      # caller and replayed on the callback — rubino keeps no per-flow
+      # session.
+      #
+      # @param redirect_uri [String] absolute callback URL registered with the provider
+      # @param scopes [Array<String>, nil] overrides the instance default scopes when present
+      # @param extra [Hash] additional query parameters appended to the authorize URL
+      # @return [Hash] with keys +:authorize_url+ (String), +:state+ (String,
+      #   urlsafe base64), +:code_verifier+ (String, PKCE verifier)
+      def build_authorize_request(redirect_uri:, scopes: nil, extra: {})
+        state = SecureRandom.urlsafe_base64(32)
+        code_verifier = SecureRandom.urlsafe_base64(64)
+        code_challenge = pkce_challenge(code_verifier)
+
+        url = oauth2_client.auth_code.authorize_url(
+          redirect_uri: redirect_uri,
+          scope: Array(scopes || @scopes).join(scope_separator),
+          state: state,
+          code_challenge: code_challenge,
+          code_challenge_method: "S256",
+          **extra
+        )
+
+        { authorize_url: url, state: state, code_verifier: code_verifier }
+      end
+
+      # Exchange the authorization code for tokens.
+      #
+      # @param code [String] authorization code returned by the provider
+      # @param redirect_uri [String] same redirect_uri used in {#build_authorize_request}
+      # @param code_verifier [String] PKCE verifier paired with the original challenge
+      # @return [Hash] with keys +:access_token+ (String), +:refresh_token+
+      #   (String, nil), +:expires_at+ (String ISO8601 UTC, nil), +:scopes+
+      #   (Array<String>)
+      def exchange_code(code:, redirect_uri:, code_verifier:)
+        token = oauth2_client.auth_code.get_token(
+          code,
+          redirect_uri: redirect_uri,
+          code_verifier: code_verifier
+        )
+        normalize(token)
+      end
+
+      def refresh(refresh_token)
+        token = OAuth2::AccessToken.new(oauth2_client, "", refresh_token: refresh_token)
+        normalize(token.refresh!)
+      end
+
+      # Provider-specific call to /userinfo (or equivalent) using the access
+      # token.
+      #
+      # @param _access_token [String]
+      # @return [Hash] with keys +:account_id+ (String), +:account_email+
+      #   (String, nil), +:metadata+ (Hash)
+      def fetch_account_info(_access_token)
+        raise NotImplementedError
+      end
+
+      private
+
+      def oauth2_client
+        @oauth2_client ||= OAuth2::Client.new(
+          @client_id,
+          @client_secret,
+          site: self.class.site,
+          authorize_url: self.class.authorize_path,
+          token_url: self.class.token_path
+        )
+      end
+
+      def scope_separator
+        " "
+      end
+
+      def normalize(token)
+        expires_at = token.expires_at ? Time.at(token.expires_at).utc.iso8601 : nil
+        {
+          access_token: token.token,
+          refresh_token: token.refresh_token,
+          expires_at: expires_at,
+          scopes: (token.params["scope"] || @scopes.join(" ")).to_s.split(/[\s,]+/).reject(&:empty?)
+        }
+      end
+
+      # PKCE S256 challenge: SHA-256 of the verifier, base64url-encoded with
+      # padding stripped (RFC 7636 §4.2 — providers reject "=" padding).
+      def pkce_challenge(verifier)
+        Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+      end
+    end
+  end
+end

data/lib/rubino/oauth/registry.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Rubino
+  module OAuth
+    # Process-wide registry of configured OAuth providers. Mutex-protected so
+    # +register+ / +reset!+ are safe under concurrent boot or reload.
+    #
+    # Hydrated from +oauth.providers.*+ in Rubino.configuration; only ids
+    # listed in {BUILTINS} are considered, and any section missing both
+    # +client_id+ and +client_secret+ is silently skipped so a partial config
+    # never raises at boot (it just hides the provider from
+    # +/v1/oauth/providers+).
+    module Registry
+      BUILTINS = {
+        github: "Rubino::OAuth::Provider::Github",
+        google: "Rubino::OAuth::Provider::Google"
+      }.freeze
+
+      class << self
+        def register(id, instance)
+          mutex.synchronize { providers[id.to_sym] = instance }
+          instance
+        end
+
+        # @param id [String, Symbol]
+        # @return [Provider]
+        # @raise [Rubino::NotFoundError] when no provider is registered for +id+
+        def fetch(id)
+          providers[id.to_sym] or raise NotFoundError.new("oauth_provider", id)
+        end
+
+        def fetch_or_nil(id)
+          providers[id.to_sym]
+        end
+
+        def all
+          providers.values
+        end
+
+        def ids
+          providers.keys
+        end
+
+        def reset!
+          mutex.synchronize { providers.clear }
+        end
+
+        # Hydrate from the loaded Rubino configuration. Reads oauth.providers.*
+        # sections; for each id matching a BUILTIN, instantiates and registers
+        # using its declared client_id/client_secret/scopes. Replaces any
+        # previously registered providers ({#reset!} runs first).
+        #
+        # @param configuration [#dig] anything responding to +dig("oauth", "providers")+
+        # @return [Array<Provider>] providers registered by this call
+        def load_from_config!(configuration = Rubino.configuration)
+          reset!
+          oauth_cfg = configuration.dig("oauth", "providers") || {}
+          oauth_cfg.each do |id, cfg|
+            klass_name = BUILTINS[id.to_sym]
+            next unless klass_name
+            next unless cfg["client_id"] && cfg["client_secret"]
+
+            klass = Object.const_get(klass_name)
+            register(id, klass.new(
+                           client_id: cfg["client_id"],
+                           client_secret: cfg["client_secret"],
+                           scopes: cfg["scopes"],
+                           metadata: cfg.reject { |k, _| %w[client_id client_secret scopes].include?(k) }
+                         ))
+          end
+          all
+        end
+
+        private
+
+        def providers
+          @providers ||= {}
+        end
+
+        def mutex
+          @mutex ||= Mutex.new
+        end
+      end
+    end
+  end
+end

data/lib/rubino/oauth/token_encryptor.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Rubino
+  module OAuth
+    # AES-256-GCM symmetric encryption for OAuth tokens at rest.
+    #
+    # Key supplied via RUBINO_ENCRYPTION_KEY env (32 raw bytes encoded as
+    # standard base64). Generate one with:
+    #   ruby -rsecurerandom -rbase64 -e 'puts Base64.strict_encode64(SecureRandom.random_bytes(32))'
+    #
+    # Wire format is Base64(IV || ciphertext || tag) with a 12-byte IV and a
+    # 16-byte GCM auth tag. {.from_env} raises {KeyMissingError} when the env
+    # var is missing or not a 32-byte key; {#decrypt} raises
+    # {InvalidCiphertextError} on tampered or truncated payloads.
+    class TokenEncryptor
+      CIPHER = "aes-256-gcm"
+      IV_LEN = 12
+      TAG_LEN = 16
+
+      class KeyMissingError < Rubino::Error
+      end
+
+      class InvalidCiphertextError < Rubino::Error
+      end
+
+      # Build an encryptor using the key in RUBINO_ENCRYPTION_KEY.
+      #
+      # @return [TokenEncryptor]
+      # @raise [KeyMissingError] if the env var is unset, empty, or does not
+      #   decode to exactly 32 bytes
+      def self.from_env
+        raw = ENV.fetch("RUBINO_ENCRYPTION_KEY", nil)
+        raise KeyMissingError, "RUBINO_ENCRYPTION_KEY not set" if raw.nil? || raw.empty?
+
+        key = Base64.strict_decode64(raw)
+        raise KeyMissingError, "RUBINO_ENCRYPTION_KEY must decode to 32 bytes" unless key.bytesize == 32
+
+        new(key)
+      end
+
+      def initialize(key)
+        raise ArgumentError, "key must be 32 bytes" unless key.bytesize == 32
+
+        @key = key
+      end
+
+      # @param plaintext [String, nil]
+      # @return [String, nil] Base64(IV || ciphertext || tag), or nil when
+      #   plaintext is nil (so nullable token columns round-trip unchanged)
+      def encrypt(plaintext)
+        return nil if plaintext.nil?
+
+        cipher = OpenSSL::Cipher.new(CIPHER).encrypt
+        cipher.key = @key
+        iv = cipher.random_iv
+        ciphertext = cipher.update(plaintext.to_s) + cipher.final
+        Base64.strict_encode64(iv + ciphertext + cipher.auth_tag)
+      end
+
+      # @param payload [String, nil] a value previously returned by {#encrypt}
+      # @return [String, nil] the original plaintext, or nil when payload is nil
+      # @raise [InvalidCiphertextError] if the payload is too short or the GCM
+      #   auth tag does not verify (tampering, wrong key, truncation)
+      def decrypt(payload)
+        return nil if payload.nil?
+
+        bytes = Base64.strict_decode64(payload)
+        raise InvalidCiphertextError, "payload too short" if bytes.bytesize <= IV_LEN + TAG_LEN
+
+        iv = bytes.byteslice(0, IV_LEN)
+        tag = bytes.byteslice(-TAG_LEN, TAG_LEN)
+        ciphertext = bytes.byteslice(IV_LEN, bytes.bytesize - IV_LEN - TAG_LEN)
+
+        cipher = OpenSSL::Cipher.new(CIPHER).decrypt
+        cipher.key = @key
+        cipher.iv = iv
+        cipher.auth_tag = tag
+        cipher.update(ciphertext) + cipher.final
+      rescue OpenSSL::Cipher::CipherError => e
+        raise InvalidCiphertextError, "decryption failed: #{e.message}"
+      end
+    end
+  end
+end

data/lib/rubino/plugins/registry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Plugins
+    # Central registry for plugins and their hooks.
+    class Registry
+      def initialize
+        @hooks = Hash.new { |h, k| h[k] = [] }
+        @plugins = []
+      end
+
+      # Registers a hook handler
+      def on(event, &block)
+        raise Error, "Unknown hook: #{event}. Valid: #{HOOKS.join(", ")}" unless HOOKS.include?(event.to_sym)
+
+        @hooks[event.to_sym] << block
+      end
+
+      # Executes all handlers for a hook, passing context through each
+      def run_hook(event, context = {})
+        @hooks[event.to_sym].each do |handler|
+          result = handler.call(context)
+          # If handler returns a hash, merge it into context
+          context = context.merge(result) if result.is_a?(Hash)
+        end
+        context
+      end
+
+      # Returns true if any handlers are registered for this hook
+      def has_hook?(event)
+        @hooks[event.to_sym].any?
+      end
+
+      # Loads a plugin from a file
+      def load_plugin(path)
+        load(path)
+        @plugins << path
+      rescue StandardError => e
+        Rubino.ui.warning("Failed to load plugin #{path}: #{e.message}")
+      end
+
+      # Loads all plugins from configured paths
+      def load_all!
+        plugin_paths.each do |dir|
+          expanded = File.expand_path(dir)
+          next unless File.directory?(expanded)
+
+          Dir.glob(File.join(expanded, "*.rb")).each do |path|
+            load_plugin(path)
+          end
+        end
+      end
+
+      # Returns count of loaded plugins
+      def plugin_count
+        @plugins.size
+      end
+
+      # Clears all hooks and plugins (for testing)
+      def reset!
+        @hooks.clear
+        @plugins.clear
+      end
+
+      private
+
+      def plugin_paths
+        [
+          ".rubino/plugins",
+          "~/.rubino/plugins"
+        ]
+      end
+    end
+  end
+end

data/lib/rubino/plugins.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Rubino
+  # Plugin system with event hooks.
+  # Plugins can subscribe to events and modify behavior.
+  #
+  # Usage:
+  #   Rubino.plugin do
+  #     on(:tool_execute_before) do |context|
+  #       # Modify or inspect tool call before execution
+  #     end
+  #
+  #     on(:tool_execute_after) do |context|
+  #       # React to tool results
+  #     end
+  #
+  #     on(:session_start) do |context|
+  #       # Do something when a session starts
+  #     end
+  #   end
+  #
+  module Plugins
+    # All supported hook points (30+)
+    HOOKS = %i[
+      tool_execute_before
+      tool_execute_after
+      tool_approval_before
+      tool_approval_after
+      tool_result_transform
+
+      shell_env
+      shell_execute_before
+      shell_execute_after
+
+      file_read_before
+      file_read_after
+      file_write_before
+      file_write_after
+
+      compaction_before
+      compaction_after
+      compaction_context_inject
+
+      session_start
+      session_end
+      session_fork
+      session_persist
+
+      message_before
+      message_after
+      message_stream_chunk
+
+      memory_extract
+      memory_save_before
+      memory_retrieve_after
+
+      job_before
+      job_after
+      job_failed
+
+      model_call_before
+      model_call_after
+      model_response_transform
+
+      prompt_assemble_before
+      prompt_assemble_after
+
+      agent_switch
+      agent_route
+
+      config_reload
+      startup
+      shutdown
+    ].freeze
+
+    class << self
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def reset!
+        @registry = nil
+      end
+    end
+  end
+end