collavre 0.20.3 → 0.22.0

data/lib/collavre/aws_credentials.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Collavre
+  # Returns source-coherent AWS credential pairs (S3 access key id + secret,
+  # SES SMTP username + password). Both halves of a pair come from the same
+  # source — DB > ENV > Rails credentials — so a partial admin save cannot
+  # combine a DB-saved value with an ENV-only sibling and produce a
+  # mismatched pair that breaks every upload or every SMTP delivery.
+  #
+  # Each entry is `[registry_key, label, env_var, credentials_path]`.
+  # `credentials_path` may be nil when the pair has no Rails.credentials
+  # fallback (S3 keys aren't carried in credentials by convention).
+  module AwsCredentials
+    module_function
+
+    # @param boot_safe [Boolean] when true, swallow encryption errors so
+    #   `storage.yml` / env configs can boot before
+    #   `active_record_encryption.rb` runs. Runtime callers (e.g.
+    #   `SesSettingsInterceptor`) MUST leave this false so a decryption
+    #   failure surfaces instead of silently falling back to ENV.
+    # @return [Hash{Symbol => String}] coherent S3 credential pair or `{}`
+    def s3(boot_safe: false)
+      coherent_pair(
+        boot_safe,
+        [ :aws_s3_access_key_id,     :access_key_id,     "AWS_S3_ACCESS_KEY_ID",     nil ],
+        [ :aws_s3_secret_access_key, :secret_access_key, "AWS_S3_SECRET_ACCESS_KEY", nil ]
+      )
+    end
+
+    # @return [Hash{Symbol => String}] coherent SES SMTP credential pair or `{}`
+    def ses_smtp(boot_safe: false)
+      coherent_pair(
+        boot_safe,
+        [ :aws_ses_smtp_username, :user_name, "AWS_SES_SMTP_USERNAME", %i[aws smtp_username] ],
+        [ :aws_ses_smtp_password, :password,  "AWS_SES_SMTP_PASSWORD", %i[aws smtp_password] ]
+      )
+    end
+
+    def coherent_pair(boot_safe, *entries)
+      [ db_pair(entries, boot_safe), env_pair(entries), credentials_pair(entries) ]
+        .find { |pair| pair.values.all?(&:present?) } || {}
+    end
+
+    def db_pair(entries, boot_safe)
+      entries.to_h { |entry| [ entry[1], read_db(entry[0], boot_safe: boot_safe) ] }
+    end
+
+    def env_pair(entries)
+      entries.to_h { |entry| [ entry[1], ENV[entry[2]].presence ] }
+    end
+
+    def credentials_pair(entries)
+      entries.to_h do |entry|
+        path = entry[3]
+        value = path ? Rails.application.credentials.dig(*path).presence : nil
+        [ entry[1], value ]
+      end
+    end
+
+    def read_db(key, boot_safe: false)
+      return nil unless defined?(Collavre::IntegrationSetting)
+      Collavre::IntegrationSetting.find_by(key: key.to_s)&.value.presence
+    rescue ActiveRecord::StatementInvalid,
+           ActiveRecord::NoDatabaseError,
+           ActiveRecord::ConnectionNotEstablished,
+           NameError
+      nil
+    rescue StandardError => e
+      raise unless boot_safe &&
+                   defined?(ActiveRecord::Encryption::Errors::Base) &&
+                   e.is_a?(ActiveRecord::Encryption::Errors::Base)
+      nil
+    end
+  end
+end

data/lib/collavre/engine.rb

@@ -16,6 +16,56 @@ module Collavre
       root.join("app/assets/stylesheets")
     end
 
+    # Register engine-internal integration settings keys with the central
+    # registry. These keys are consumed by engine code (mailer `from`, public
+    # assets helper, MCP upload service), so the engine itself must own their
+    # registration — host apps may not include the app-level
+    # `integration_settings_app.rb` initializer when mounting the engine as a gem.
+    # `register` is idempotent, so host app re-registration remains safe.
+    initializer "collavre.integration_settings_registry", before: :load_config_initializers do
+      if defined?(Collavre::IntegrationSettings::Registry)
+        registry = Collavre::IntegrationSettings::Registry.instance
+        registry.register(:default_mailer_from, category: "mail", sensitive: false, requires_restart: true)
+        registry.register(:public_assets_host,  category: "mail", sensitive: false, requires_restart: false)
+        # LLM keys consumed by Collavre::AiClient (engine service). Owned by the
+        # engine so gem-mounted host apps don't depend on the app-level
+        # `ruby_llm.rb` initializer for ENV fallback.
+        registry.register(:gemini_api_key,    category: "llm", sensitive: true,  requires_restart: true)
+        registry.register(:openai_api_key,    category: "llm", sensitive: true,  requires_restart: false)
+        registry.register(:anthropic_api_key, category: "llm", sensitive: true,  requires_restart: false)
+        registry.register(:gemini_api_base,   category: "llm", sensitive: false, requires_restart: true)
+      end
+    end
+
+    # AWS keys are consumed by `config/environments/*.rb` (active_storage.service
+    # decision, SMTP scaffold) and `config/storage.yml` ERB, both of which evaluate
+    # during the `:load_environment_config` initializer — earlier than
+    # `:load_config_initializers`. Register them in their own block so
+    # `IntegrationSettings.fetch` can resolve the keys at that earlier point.
+    # S3 keys are `requires_restart: true` because Rails resolves the storage
+    # service once at boot; SES keys are runtime-injected by SesSettingsInterceptor.
+    initializer "collavre.integration_settings_registry.aws", before: :load_environment_config do
+      if defined?(Collavre::IntegrationSettings::Registry)
+        registry = Collavre::IntegrationSettings::Registry.instance
+        registry.register(:aws_s3_access_key_id,     category: "aws_s3",  sensitive: true,  requires_restart: true)
+        registry.register(:aws_s3_secret_access_key, category: "aws_s3",  sensitive: true,  requires_restart: true)
+        registry.register(:aws_s3_bucket,            category: "aws_s3",  sensitive: false, requires_restart: true)
+        registry.register(:aws_region,               category: "aws_s3",  sensitive: false, requires_restart: true)
+        registry.register(:aws_ses_smtp_username,    category: "aws_ses", sensitive: true,  requires_restart: false)
+        registry.register(:aws_ses_smtp_password,    category: "aws_ses", sensitive: true,  requires_restart: false)
+      end
+    end
+
+    # Register the SES SMTP settings interceptor so each outgoing mail picks up
+    # the current DB > ENV > credentials value for SES creds at send time.
+    # Hooked after ActionMailer loads to ensure Mail::SMTP is defined.
+    initializer "collavre.ses_settings_interceptor" do
+      ActiveSupport.on_load(:action_mailer) do
+        require "mail"
+        ::Mail.register_interceptor(Collavre::SesSettingsInterceptor)
+      end
+    end
+
     # Add engine migrations to main app's migration path
     # This allows migrations to live in the engine but be run from the host app
     initializer "collavre.migrations" do |app|

data/lib/collavre/integration_settings/key_definition.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Collavre
+  module IntegrationSettings
+    # Value object describing a registered integration setting key.
+    #
+    # @!attribute [r] key
+    #   @return [Symbol] canonical key identifier (e.g. :slack_client_id)
+    # @!attribute [r] category
+    #   @return [String] grouping for the admin UI (e.g. "slack", "google_oauth")
+    # @!attribute [r] sensitive
+    #   @return [Boolean] when true the value is masked in the admin UI
+    # @!attribute [r] requires_restart
+    #   @return [Boolean] when true the admin UI surfaces a "restart required" badge
+    # @!attribute [r] env_var
+    #   @return [String] name of the ENV variable used as fallback / seed source
+    # @!attribute [r] default
+    #   @return [String, nil] static default returned when neither DB nor ENV has a value
+    # @!attribute [r] input_type
+    #   @return [Symbol] admin UI input widget: :string (default, single line) or :textarea
+    # @!attribute [r] admin_visible
+    #   @return [Boolean] when false the key is resolvable but hidden from the admin UI
+    KeyDefinition = Struct.new(
+      :key,
+      :category,
+      :sensitive,
+      :requires_restart,
+      :env_var,
+      :default,
+      :input_type,
+      :admin_visible,
+      keyword_init: true
+    )
+  end
+end

data/lib/collavre/integration_settings/registry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module Collavre
+  module IntegrationSettings
+    # Singleton registry of integration setting key definitions.
+    # Engines register their keys at boot via `to_prepare`, then the
+    # admin UI and {Resolver} consult this registry.
+    class Registry
+      include Singleton
+
+      def initialize
+        @definitions = {}
+      end
+
+      # Register a key definition.
+      #
+      # @param key [Symbol, String] canonical identifier (e.g. :slack_client_id)
+      # @param category [String] grouping label (e.g. "slack")
+      # @param sensitive [Boolean] when true, value is masked in admin UI
+      # @param requires_restart [Boolean] when true, surfaces restart-required badge
+      # @param env_var [String, nil] ENV variable name (defaults to key.upcase)
+      # @param default [String, nil] static fallback used when DB & ENV blank
+      # @param input_type [Symbol] admin UI widget: :string (default) or :textarea
+      # @param admin_visible [Boolean] when false the key is resolvable but hidden from admin UI
+      # @return [KeyDefinition]
+      def register(key, category:, sensitive: true, requires_restart: false, env_var: nil, default: nil,
+                   input_type: :string, admin_visible: true)
+        key = key.to_sym
+        @definitions[key] = KeyDefinition.new(
+          key: key,
+          category: category,
+          sensitive: sensitive,
+          requires_restart: requires_restart,
+          env_var: env_var || key.to_s.upcase,
+          default: default,
+          input_type: input_type,
+          admin_visible: admin_visible
+        )
+      end
+
+      # @return [Array<KeyDefinition>] all registered definitions (frozen snapshot)
+      def all
+        @definitions.values.freeze
+      end
+
+      # @param key [Symbol, String]
+      # @return [KeyDefinition, nil]
+      def find(key)
+        @definitions[key.to_sym]
+      end
+
+      # @return [Hash{String => Array<KeyDefinition>}] definitions grouped by category
+      def by_category
+        @definitions.values.group_by(&:category)
+      end
+    end
+  end
+end

data/lib/collavre/integration_settings/resolver.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Collavre
+  module ::Collavre::IntegrationSettings
+    # Resolves the live value for a registered integration setting key.
+    #
+    # Precedence: **DB > ENV > registered default.**
+    # - DB value wins as long as an `::Collavre::IntegrationSetting` row exists with a
+    #   non-blank value (encrypted at rest via `::Collavre::IntegrationSetting`).
+    # - ENV is consulted only when no DB row exists.
+    # - The registry's static default is the final fallback.
+    #
+    # Caching:
+    # - **Sensitive** definitions are NEVER cached. `Rails.cache` may resolve
+    #   to a durable store (e.g. `:solid_cache_store` in production), which
+    #   would persist decrypted secrets outside the encrypted `value` column
+    #   and defeat at-rest encryption. Sensitive reads hit the DB every time.
+    # - **Non-sensitive** definitions are memoized in `Rails.cache` for 5
+    #   minutes under `::Collavre::IntegrationSetting.cache_key_for(key)`. The model's
+    #   `after_commit` hook invalidates this key on any write.
+    class Resolver
+      # Raised by {.get} when the key has not been registered.
+      class UnknownKeyError < StandardError; end
+
+      CACHE_TTL = 5.minutes
+
+      class << self
+        # Resolve the current value for a registered key.
+        #
+        # @param key [Symbol, String]
+        # @return [String, nil]
+        # @raise [UnknownKeyError] if the key is not registered
+        def get(key)
+          definition = Registry.instance.find(key) or
+            raise UnknownKeyError, "Unknown integration setting: #{key}"
+
+          return resolve(definition) if definition.sensitive
+
+          Rails.cache.fetch(::Collavre::IntegrationSetting.cache_key_for(definition.key), expires_in: CACHE_TTL) do
+            resolve(definition)
+          end
+        end
+
+        # Report which source currently provides the value for a key.
+        #
+        # @param key [Symbol, String]
+        # @return [Symbol] one of `:db`, `:env`, `:default`, or `:unknown`
+        def source_for(key)
+          definition = Registry.instance.find(key) or return :unknown
+          return :db  if ::Collavre::IntegrationSetting.find_by(key: definition.key)&.value.present?
+          return :env if ENV[definition.env_var].present?
+          :default
+        end
+
+        private
+
+        def resolve(definition)
+          db_value(definition) || env_value(definition) || definition.default
+        end
+
+        def db_value(definition)
+          ::Collavre::IntegrationSetting.find_by(key: definition.key)&.value.presence
+        end
+
+        def env_value(definition)
+          ENV[definition.env_var].presence
+        end
+      end
+    end
+  end
+end

data/lib/collavre/integration_settings.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Entry point for the Collavre integration settings subsystem.
+# Loads the registry value-object, registry singleton, and resolver
+# (when present). Loaded from `engines/collavre/lib/collavre.rb` so
+# constants are available before any engine `to_prepare` blocks run.
+
+require_relative "integration_settings/key_definition"
+require_relative "integration_settings/registry"
+require_relative "integration_settings/resolver"
+
+module Collavre
+  module IntegrationSettings
+    # Resolve a registered key with a safety net for boot-time consumers.
+    # Returns `Resolver.get(key)` when the registry+DB are reachable, otherwise
+    # falls back to `ENV[key.upcase]`. After the next boot, the DB value wins —
+    # matching the `requires_restart` semantics callers register.
+    #
+    # `boot_safe: true` additionally rescues `ActiveRecord::Encryption::Errors::Base`
+    # so callers reached before `config/initializers/active_record_encryption.rb`
+    # runs (e.g. `storage.yml`, `config/environments/*.rb`) cannot crash the boot
+    # if an encrypted row is unreadable. Runtime callers MUST leave this false so
+    # decryption failures surface instead of silently treating values as blank.
+    def self.fetch(key, default: nil, boot_safe: false)
+      return ENV[key.to_s.upcase].presence || default unless defined?(Resolver)
+
+      value =
+        begin
+          Resolver.get(key)
+        rescue Resolver::UnknownKeyError
+          nil
+        rescue ActiveRecord::StatementInvalid,
+               ActiveRecord::NoDatabaseError,
+               ActiveRecord::ConnectionNotEstablished,
+               NameError
+          ENV[key.to_s.upcase]
+        rescue StandardError => e
+          raise unless boot_safe &&
+                       defined?(ActiveRecord::Encryption::Errors::Base) &&
+                       e.is_a?(ActiveRecord::Encryption::Errors::Base)
+          ENV[key.to_s.upcase]
+        end
+      value.presence || default
+    end
+  end
+end

data/lib/collavre/ses_settings_interceptor.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Collavre
+  # ActionMailer interceptor that injects AWS SES SMTP settings (address,
+  # user_name, password) into each outgoing message at send time, sourced
+  # from `IntegrationSettings` (DB > ENV) with a Rails credentials fallback.
+  #
+  # Registered via `Collavre::Engine` so admins can rotate SES credentials
+  # through `/admin/integrations` without redeploying. Only acts on SMTP
+  # delivery — other delivery methods (`:test`, `:letter_opener`, etc.) pass
+  # through untouched.
+  class SesSettingsInterceptor
+    SES_ADDRESS_PATTERN = /\Aemail-smtp\.[a-z0-9-]+\.amazonaws\.com\z/
+
+    class << self
+      def delivering_email(message)
+        return unless message.delivery_method.is_a?(::Mail::SMTP)
+
+        settings = message.delivery_method.settings
+        # Scope to SES-bound messages only. The engine registers this
+        # interceptor globally, so host apps using a non-SES SMTP provider
+        # (SendGrid, Mailgun, custom relay) must pass through untouched —
+        # otherwise we'd clobber their address/user_name/password.
+        return unless ses_target?(settings)
+
+        region = resolve_region
+        creds  = Collavre::AwsCredentials.ses_smtp
+
+        settings[:address] = "email-smtp.#{region}.amazonaws.com" if region.present?
+        # `AwsCredentials.ses_smtp` returns only source-coherent pairs (both DB,
+        # both ENV, or both credentials). When admins save just one half via
+        # /admin/integrations while the other still lives in ENV, the helper
+        # drops the partial DB write and falls through to a coherent ENV/cred
+        # pair, avoiding mismatched (db-user, env-pass) injections that would
+        # break every SMTP delivery.
+        if creds[:user_name].present? && creds[:password].present?
+          settings[:user_name] = creds[:user_name]
+          settings[:password]  = creds[:password]
+        else
+          # No coherent pair available (admin reset DB and no ENV/credentials
+          # fallback). Clear stale settings so we don't keep using boot-time
+          # or previously-injected credentials — these keys are registered
+          # with requires_restart: false, so runtime reset must take effect.
+          settings.delete(:user_name)
+          settings.delete(:password)
+        end
+      end
+
+      private
+
+      # SES intent is signaled exclusively by an SES-shaped SMTP address
+      # (`email-smtp.<region>.amazonaws.com`). The boot scaffold in
+      # `config/environments/production.rb` only emits that shape when
+      # `ses_region` is resolvable, so a non-SES address — including
+      # `Mail::SMTP`'s hard-coded `"localhost"` default and explicit relays
+      # like `smtp.sendgrid.net` — means the host is using a different
+      # provider (or a real local relay). Bail in those cases so we don't
+      # clobber the host's address or wipe authenticated credentials.
+      def ses_target?(settings)
+        address = settings[:address].to_s
+        return true if address.empty?
+
+        address.match?(SES_ADDRESS_PATTERN)
+      end
+
+      def resolve_region
+        value = Collavre::IntegrationSettings.fetch(:aws_region, default: ENV["AWS_REGION"])
+        value.presence || Rails.application.credentials.dig(:aws, :region)
+      end
+    end
+  end
+end

data/lib/collavre/version.rb

@@ -1,3 +1,3 @@
 module Collavre
-  VERSION = "0.20.3"
+  VERSION = "0.22.0"
 end

data/lib/collavre.rb

@@ -3,6 +3,9 @@ require "collavre/configuration"
 require "collavre/engine"
 require "collavre/user_extensions"
 require "collavre/integration_registry"
+require "collavre/integration_settings"
+require "collavre/aws_credentials"
+require "collavre/ses_settings_interceptor"
 require "collavre/view_extensions"
 require "navigation/registry"