env_bro 0.1.0

data/lib/env_bro/credentials.rb

@@ -0,0 +1,135 @@
+require "yaml"
+
+module EnvBro
+  # Decrypted credentials as a nested hash, addressed with dotted key paths
+  # ("aws.access_key_id"). The EnvBro metadata key is kept apart from the rest.
+  class Credentials
+    SEGMENT = /\A[A-Za-z0-9_\-]+\z/
+
+    attr_reader :data
+
+    def self.parse(yaml)
+      data = YAML.respond_to?(:unsafe_load) ? YAML.unsafe_load(yaml) : YAML.load(yaml)
+      data = {} if data.blank?
+      raise Error, "Credentials must be a YAML mapping at the top level" unless data.is_a?(Hash)
+      new(data)
+    end
+
+    def self.split(path)
+      segments = path.to_s.strip.split(".")
+      if segments.empty? || segments.any? { |s| !s.match?(SEGMENT) }
+        raise InvalidChange, "Invalid key #{path.inspect}. Use letters, digits, _ and -, nested with dots (aws.secret_key)."
+      end
+      segments
+    end
+
+    def initialize(data)
+      @data = data
+    end
+
+    def metadata
+      key = EnvBro.config.metadata_key
+      key ? (data[key] || data[key.to_sym]) : nil
+    end
+
+    def metadata=(value)
+      key = EnvBro.config.metadata_key or return
+      data.delete(key.to_sym)
+      data[key] = value
+    end
+
+    # One line of the YAML-like outline shown to proposers: a group ("aws:") or a key.
+    Line = Struct.new(:path, :name, :depth, :group, keyword_init: true)
+
+    # { "aws.access_key_id" => "AKIA...", "secret_key_base" => "..." }, without metadata.
+    def flatten
+      flatten_hash(without_metadata)
+    end
+
+    # Groups and keys in file order, with their nesting depth. No values.
+    def outline(hash = without_metadata, prefix = nil, depth = 0, lines = [])
+      hash.each do |key, value|
+        path = [ prefix, key.to_s ].compact.join(".")
+        group = value.is_a?(Hash) && value.any?
+        lines << Line.new(path: path, name: key.to_s, depth: depth, group: group)
+        outline(value, path, depth + 1, lines) if group
+      end
+      lines
+    end
+
+    def key_paths
+      flatten.keys
+    end
+
+    def key?(path)
+      flatten.key?(path)
+    end
+
+    def set(path, value)
+      *parents, leaf = self.class.split(path)
+      node = data
+      parents.each do |segment|
+        key = find_key(node, segment) || segment
+        if node[key].nil?
+          node = node[key] = {}
+        elsif node[key].is_a?(Hash)
+          node = node[key]
+        else
+          raise InvalidChange, "Cannot set #{path}: #{segment} already holds a value, not a group of keys."
+        end
+      end
+      existing_leaf = find_key(node, leaf)
+      if existing_leaf && node[existing_leaf].is_a?(Hash)
+        raise InvalidChange, "Cannot set #{path}: it is a group of keys, set one of its children instead."
+      end
+      node[existing_leaf || leaf] = value
+    end
+
+    def delete(path)
+      *parents, leaf = self.class.split(path)
+      chain = [ data ]
+      parents.each do |segment|
+        child = chain.last[find_key(chain.last, segment)]
+        raise InvalidChange, "Cannot remove #{path}: key does not exist." unless child.is_a?(Hash)
+        chain << child
+      end
+      existing_leaf = find_key(chain.last, leaf)
+      raise InvalidChange, "Cannot remove #{path}: key does not exist." if existing_leaf.nil?
+      chain.last.delete(existing_leaf)
+
+      # Drop groups left empty by the removal.
+      parents.reverse.each_with_index do |segment, i|
+        parent = chain[-(i + 2)]
+        key = find_key(parent, segment)
+        parent.delete(key) if parent[key].is_a?(Hash) && parent[key].empty?
+      end
+    end
+
+    def to_yaml
+      YAML.dump(data)
+    end
+
+    private
+      def without_metadata
+        data.except(EnvBro.config.metadata_key, EnvBro.config.metadata_key&.to_sym)
+      end
+
+      # Credentials keys are usually strings but may be symbols (":foo:" in YAML).
+      def find_key(hash, segment)
+        if hash.key?(segment) then segment
+        elsif hash.key?(segment.to_sym) then segment.to_sym
+        end
+      end
+
+      def flatten_hash(hash, prefix = nil)
+        hash.each_with_object({}) do |(key, value), out|
+          path = [ prefix, key.to_s ].compact.join(".")
+          if value.is_a?(Hash) && value.any?
+            out.merge!(flatten_hash(value, path))
+          else
+            out[path] = value
+          end
+        end
+      end
+  end
+end

data/lib/env_bro/deployments.rb

@@ -0,0 +1,41 @@
+module EnvBro
+  # Rails reads credentials once, at boot. On boot we look at the credentials file
+  # this app is running with and, if it came from an EnvBro proposal, record when
+  # that proposal went live.
+  module Deployments
+    module_function
+
+    # Returns the proposal_deployed event created, or nil. Never raises: this
+    # runs during boot and must not take the app down (no DB during
+    # assets:precompile, migrations not run yet, ...).
+    def track
+      return unless EnvBro.config.track_deployments
+      return unless AuditEvent.table_exists?
+
+      environment = Environment.current
+      return unless environment.ready?
+
+      digest = Environment.digest(environment.current_cipher_text)
+      proposal = AuditEvent.proposals.find_by(file_digest: digest)
+      modified = false
+
+      # The file was re-encrypted after review but still carries the proposal's id.
+      if proposal.nil?
+        token = environment.current_credentials.metadata.to_h["proposal_id"]
+        proposal = AuditEvent.proposals.find_by(proposal_token: token) if token.present?
+        modified = proposal.present?
+      end
+
+      return if proposal.nil? || AuditEvent.deployments.exists?(proposal_id: proposal.id)
+
+      Audit.record(:proposal_deployed, user: "deploy",
+        columns: { proposal: proposal, file_digest: digest },
+        modified_after_review: modified)
+    rescue ActiveRecord::RecordNotUnique
+      nil # another process recorded it first
+    rescue StandardError => e
+      Rails.logger&.warn("[EnvBro] could not check deployed credentials: #{e.class}: #{e.message}")
+      nil
+    end
+  end
+end

data/lib/env_bro/differ.rb

@@ -0,0 +1,58 @@
+module EnvBro
+  # Compares two decrypted credentials (base vs proposed) key by key.
+  class Differ
+    Entry = Struct.new(:key, :status, :old_value, :new_value, keyword_init: true) do
+      def changed?
+        status != :unchanged
+      end
+    end
+
+    STATUS_ORDER = { added: 0, changed: 1, removed: 2, unchanged: 3 }.freeze
+
+    attr_reader :base, :proposed
+
+    def initialize(base, proposed)
+      @base = base
+      @proposed = proposed
+    end
+
+    def entries
+      @entries ||= begin
+        old_flat = base.flatten
+        new_flat = proposed.flatten
+        keys = (old_flat.keys | new_flat.keys)
+
+        keys.map do |key|
+          status =
+            if !old_flat.key?(key) then :added
+            elsif !new_flat.key?(key) then :removed
+            elsif old_flat[key] == new_flat[key] then :unchanged
+            else :changed
+            end
+          Entry.new(key: key, status: status, old_value: old_flat[key], new_value: new_flat[key])
+        end.sort_by { |e| [ STATUS_ORDER[e.status], e.key ] }
+      end
+    end
+
+    def changes
+      entries.select(&:changed?)
+    end
+
+    def counts
+      entries.group_by(&:status).transform_values(&:size)
+    end
+
+    def proposed_metadata
+      proposed.metadata.is_a?(Hash) ? proposed.metadata : nil
+    end
+
+    # :current  - proposal was built on the base we compare against
+    # :stale    - proposal was built on a different version of the file
+    # :unknown  - proposal carries no EnvBro metadata (made by hand, or an old file)
+    def base_status(base_digest)
+      recorded = proposed_metadata&.fetch("base_digest", nil)
+      return :unknown if recorded.blank?
+      recorded == base_digest ? :current : :stale
+    end
+  end
+end

data/lib/env_bro/editor.rb

@@ -0,0 +1,104 @@
+require "time"
+require "securerandom"
+
+module EnvBro
+  # Applies a list of changes to an environment's current credentials, in memory,
+  # and returns the re-encrypted file. Nothing is written to disk.
+  class Editor
+    ACTIONS = %w[set delete].freeze
+
+    Change = Struct.new(:action, :key, :value, keyword_init: true) do
+      def description
+        action == "delete" ? "remove #{key}" : "set #{key}"
+      end
+    end
+
+    Result = Struct.new(:cipher_text, :filename, :changes, :base_digest, :proposal_token, keyword_init: true) do
+      # SHA-256 of the file handed out; seeing it deployed means the proposal is live.
+      def file_digest
+        Environment.digest(cipher_text)
+      end
+    end
+
+    attr_reader :environment
+
+    def initialize(environment)
+      @environment = environment
+    end
+
+    # changes: array of hashes/Changes with action ("set"/"delete"), key and value.
+    def apply(changes, author:)
+      changes = normalize(changes)
+      raise InvalidChange, "Add at least one change." if changes.empty?
+
+      base_cipher_text = environment.current_cipher_text
+      credentials = environment.decrypt(base_cipher_text)
+
+      changes.each do |change|
+        if change.action == "delete"
+          credentials.delete(change.key)
+        else
+          credentials.set(change.key, change.value)
+        end
+      end
+
+      base_digest = Environment.digest(base_cipher_text)
+      proposal_token = SecureRandom.uuid
+      credentials.metadata = {
+        "proposal_id" => proposal_token,
+        "base_digest" => base_digest,
+        "proposed_by" => author.to_s,
+        "proposed_at" => Time.now.utc.iso8601,
+        "changes" => changes.map(&:description)
+      }
+
+      Result.new(
+        cipher_text: environment.encrypt(credentials),
+        filename: environment.filename,
+        changes: changes,
+        base_digest: base_digest,
+        proposal_token: proposal_token
+      )
+    end
+
+    private
+      def normalize(changes)
+        changes = Array(changes).map { |c| c.is_a?(Change) ? c : Change.new(**c.to_h.symbolize_keys.slice(:action, :key, :value)) }
+        changes = changes.reject { |c| c.key.blank? && c.value.blank? }
+
+        changes.each do |change|
+          change.action = change.action.presence || "set"
+          change.key = change.key.to_s.strip
+          raise InvalidChange, "Unknown action #{change.action.inspect}." unless ACTIONS.include?(change.action)
+          Credentials.split(change.key)
+          if metadata_key?(change.key)
+            raise InvalidChange, "#{change.key} is reserved for EnvBro metadata."
+          end
+
+          if change.action == "set"
+            change.value = clean_value(change.value)
+            raise InvalidChange, "#{change.key} needs a value." if change.value.empty?
+          else
+            change.value = nil
+          end
+        end
+
+        duplicates = changes.map(&:key).tally.select { |_, n| n > 1 }.keys
+        raise InvalidChange, "Each key can only be changed once per proposal: #{duplicates.join(', ')}." if duplicates.any?
+
+        changes
+      end
+
+      # Browsers send textarea newlines as CRLF. Single-line values are stripped
+      # because a stray space or newline in an API key is a classic bug.
+      def clean_value(value)
+        value = value.to_s.gsub("\r\n", "\n").sub(/\n+\z/, "")
+        value.include?("\n") ? value : value.strip
+      end
+
+      def metadata_key?(key)
+        meta = EnvBro.config.metadata_key
+        meta && Credentials.split(key).first == meta
+      end
+  end
+end

data/lib/env_bro/encrypted_blob.rb

@@ -0,0 +1,18 @@
+require "active_support/encrypted_file"
+
+module EnvBro
+  # Reuses Rails' own EncryptedFile (cipher, serializer, key lookup) but lets us
+  # encrypt/decrypt arbitrary strings in memory instead of writing to disk.
+  class EncryptedBlob < ActiveSupport::EncryptedFile
+    def encrypt_string(plain)
+      encrypt(plain)
+    end
+
+    def decrypt_string(cipher_text)
+      decrypt(cipher_text.to_s.strip)
+    rescue ActiveSupport::MessageEncryptor::InvalidMessage, ArgumentError
+      raise DecryptionError, "This file could not be decrypted with the #{content_path.basename} key. " \
+        "It is either for another environment or corrupted."
+    end
+  end
+end

data/lib/env_bro/engine.rb

@@ -0,0 +1,15 @@
+module EnvBro
+  class Engine < ::Rails::Engine
+    isolate_namespace EnvBro
+
+    # Secret values and uploaded files must never end up in the host's logs.
+    initializer "env_bro.filter_parameters" do |app|
+      app.config.filter_parameters += %i[secret_value proposed_file base_file proposed_enc base_enc]
+    end
+
+    # Credentials are read at boot, so this is when a merged proposal takes effect.
+    config.after_initialize do
+      EnvBro::Deployments.track
+    end
+  end
+end

data/lib/env_bro/environment.rb

@@ -0,0 +1,74 @@
+require "digest"
+require "pathname"
+
+module EnvBro
+  # The credentials file of the environment the app runs in, located exactly the
+  # way Rails finds it (config.credentials.content_path, RAILS_MASTER_KEY, ...).
+  class Environment
+    attr_reader :name, :content_path, :key_path, :env_key
+
+    def self.current
+      credentials = Rails.application.credentials
+      new(name: Rails.env, content_path: credentials.content_path, key_path: credentials.key_path, env_key: credentials.env_key)
+    end
+
+    def initialize(name:, content_path:, key_path:, env_key:)
+      @name = name.to_s
+      @content_path = Pathname.new(content_path.to_s)
+      @key_path = Pathname.new(key_path.to_s)
+      @env_key = env_key
+    end
+
+    def filename
+      content_path.basename.to_s
+    end
+
+    def exists?
+      content_path.exist?
+    end
+
+    def key?
+      blob(raise_if_missing_key: false).key?.present?
+    end
+
+    # :ready, :missing_file, :missing_key or :wrong_key.
+    def status
+      return :missing_file unless exists?
+      return :missing_key unless key?
+      current_credentials
+      :ready
+    rescue DecryptionError, ActiveSupport::EncryptedFile::InvalidKeyLengthError
+      :wrong_key
+    end
+
+    def ready?
+      status == :ready
+    end
+
+    # Encrypted bytes as deployed on this server.
+    def current_cipher_text
+      content_path.binread.strip
+    end
+
+    def current_credentials
+      decrypt(current_cipher_text)
+    end
+
+    def decrypt(cipher_text)
+      Credentials.parse(blob.decrypt_string(cipher_text))
+    end
+
+    def encrypt(credentials)
+      blob.encrypt_string(credentials.to_yaml)
+    end
+
+    def self.digest(cipher_text)
+      Digest::SHA256.hexdigest(cipher_text.to_s.strip)
+    end
+
+    private
+      def blob(raise_if_missing_key: true)
+        EncryptedBlob.new(content_path: content_path, key_path: key_path, env_key: env_key, raise_if_missing_key: raise_if_missing_key)
+      end
+  end
+end

data/lib/env_bro/version.rb

@@ -0,0 +1,3 @@
+module EnvBro
+  VERSION = "0.1.0"
+end

data/lib/env_bro.rb

@@ -0,0 +1,40 @@
+require "env_bro/version"
+require "env_bro/configuration"
+require "env_bro/environment"
+require "env_bro/encrypted_blob"
+require "env_bro/credentials"
+require "env_bro/editor"
+require "env_bro/differ"
+require "env_bro/audit"
+require "env_bro/deployments"
+require "env_bro/engine"
+
+module EnvBro
+  class Error < StandardError; end
+  class DecryptionError < Error; end
+  class InvalidChange < Error; end
+  class Forbidden < StandardError; end
+
+  # Problems we show to the user instead of raising a 500.
+  USER_FACING_ERRORS = [
+    Error,
+    ActiveSupport::EncryptedFile::MissingKeyError,
+    ActiveSupport::EncryptedFile::InvalidKeyLengthError,
+    Errno::ENOENT,
+    Psych::SyntaxError
+  ].freeze
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def reset_config!
+      @config = nil
+    end
+  end
+end

data/lib/generators/env_bro/install/install_generator.rb

@@ -0,0 +1,41 @@
+require "rails/generators"
+
+module EnvBro
+  module Generators
+    # bin/rails generate env_bro:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Adds the EnvBro initializer, mounts the engine and copies its migrations."
+
+      class_option :mount_path, type: :string, default: "/admin/env", desc: "Where to mount EnvBro"
+
+      def copy_initializer
+        copy_file "env_bro.rb", "config/initializers/env_bro.rb"
+      end
+
+      def mount_engine
+        routes = File.join(destination_root, "config/routes.rb")
+        if File.exist?(routes) && File.read(routes).include?("EnvBro::Engine")
+          say_status :skip, "EnvBro::Engine is already mounted", :yellow
+        else
+          route %(mount EnvBro::Engine => "#{options[:mount_path]}")
+        end
+      end
+
+      def copy_migrations
+        rails_command "env_bro:install:migrations", inline: true
+      end
+
+      def next_steps
+        say <<~TEXT
+
+          EnvBro is installed. Next:
+            1. bin/rails db:migrate
+            2. Set who may propose, review and reveal in config/initializers/env_bro.rb
+            3. Visit #{options[:mount_path]}
+        TEXT
+      end
+    end
+  end
+end

data/lib/generators/env_bro/install/templates/env_bro.rb

@@ -0,0 +1,25 @@
+# EnvBro lets people propose changes to this environment's encrypted credentials
+# without holding the key.
+EnvBro.configure do |config|
+  # Who may do what. Each lambda gets the signed in user (nil when signed out).
+  # Everything is denied until you change these.
+  config.can_propose = ->(user) { false } # e.g. user&.developer?
+  config.can_review = ->(user) { false }  # e.g. user&.admin?
+  config.can_reveal = ->(user) { false }  # see actual values in a review (audited)
+
+  # How EnvBro finds the signed in user. Engine controllers inherit from
+  # parent_controller, so its authentication (before_actions) applies too.
+  # config.parent_controller = "::ApplicationController"
+  # config.current_user = ->(controller) { controller.send(:current_user) }
+  # config.user_label = ->(user) { user.email }
+
+  # Reject plain HTTP (secret values travel through the browser).
+  # config.require_ssl = Rails.env.production?
+
+  # Top-level credentials key holding proposal metadata. nil disables it, along
+  # with the outdated-base warning and deployment tracking by proposal id.
+  # config.metadata_key = "env_bro"
+
+  # Record on boot when the running credentials came from an EnvBro proposal.
+  # config.track_deployments = true
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: env_bro
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ruby Dev SRL
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: 'A mountable Rails engine: team members with permission build a re-encrypted
+  credentials file with their changes and open a PR; reviewers upload the file and
+  see a masked diff.'
+email:
+- office@rubydev.ro
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/env_bro/application_controller.rb
+- app/controllers/env_bro/audit_controller.rb
+- app/controllers/env_bro/home_controller.rb
+- app/controllers/env_bro/proposals_controller.rb
+- app/controllers/env_bro/reviews_controller.rb
+- app/helpers/env_bro/application_helper.rb
+- app/models/env_bro/application_record.rb
+- app/models/env_bro/audit_event.rb
+- app/views/env_bro/audit/index.html.erb
+- app/views/env_bro/proposals/_new_key_row.html.erb
+- app/views/env_bro/proposals/new.html.erb
+- app/views/env_bro/reviews/new.html.erb
+- app/views/env_bro/reviews/show.html.erb
+- app/views/env_bro/shared/_script.html.erb
+- app/views/env_bro/shared/_styles.html.erb
+- app/views/env_bro/shared/forbidden.html.erb
+- app/views/env_bro/shared/not_ready.html.erb
+- app/views/layouts/env_bro/application.html.erb
+- config/routes.rb
+- db/migrate/20261029000000_create_env_bro_audit_events.rb
+- lib/env_bro.rb
+- lib/env_bro/audit.rb
+- lib/env_bro/configuration.rb
+- lib/env_bro/credentials.rb
+- lib/env_bro/deployments.rb
+- lib/env_bro/differ.rb
+- lib/env_bro/editor.rb
+- lib/env_bro/encrypted_blob.rb
+- lib/env_bro/engine.rb
+- lib/env_bro/environment.rb
+- lib/env_bro/version.rb
+- lib/generators/env_bro/install/install_generator.rb
+- lib/generators/env_bro/install/templates/env_bro.rb
+homepage: https://www.rubydev.ro
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://www.rubydev.ro
+  source_code_uri: https://github.com/rubydevro/env_bro
+  bug_tracker_uri: https://github.com/rubydevro/env_bro/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.22
+specification_version: 4
+summary: Propose changes to Rails encrypted credentials without holding the keys.
+test_files: []