rails_outofband_keys 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c028a4ebdbf7196c3cdaa3279dfda0dd8d5d75d25a9b662c847847d650087b1d
+  data.tar.gz: 6d393b4056c6e6bfd9b63f7bdbb7dbba10a29544ca833a7e09109d71498f59c1
+SHA512:
+  metadata.gz: 8d0f2b467ced1b33e8e139843413f4e1f0c21e524a73eb41985dba3c75091a9d8818bd87976b21cab592ca4f5d325e426991720ef7d3cd62b36347ab96597202
+  data.tar.gz: 642e1b15c124d6dc4fee45991c69fee2b36ef486f6428a61b7844b371350c1b9de55b07f70d8b70e4dfd11a56ae0e5ef4ca30ebee770f65688cdaa7cab10f485

data/README.md

@@ -0,0 +1,49 @@
+# rails_outofband_keys
+
+`rails_outofband_keys` is a Rails plugin that changes **how Rails finds your credentials key files** (e.g., `production.key` or `master.key`). It allows you to keep these sensitive keys **outside of your project directory and git tree** (e.g., in `~/.config/`).
+
+It does **not** replace Rails credentials, change where `credentials.yml.enc` lives, or alter how encryption works. It only dynamically configures `config.credentials.key_path` during the boot process.
+
+## Resolution Order
+
+1. If `RAILS_MASTER_KEY` is set in the environment, Rails uses it (this gem does nothing).
+2. If `RAILS_CREDENTIALS_KEY_DIR` is set, it is used as the base directory for the app.
+3. If `RAILS_OUTOFBAND_BASE_DIR` is set, it is used as the global base directory.
+4. Otherwise, the gem fallbacks to OS defaults:
+  - **Linux/macOS**: XDG config directory (`~/.config` fallback)
+  - **Windows**: `%AppData%`
+
+The final path is constructed as:
+`base_directory / root_subdir / credentials_subdir / <environment>.key`
+`base_directory / root_subdir / credentials_subdir / master.key`
+
+## Configuration
+
+Because Rails initializes credentials very early (especially for CLI tools like `credentials:edit`), this gem is configured via a YAML file located at `config/rails_outofband_keys.yml`.
+
+### Example config/rails_outofband_keys.yml
+
+```yaml
+# The sub-folder for your application or organization
+root_subdir: "my_org/my_app"
+
+# The subdirectory where keys are stored (defaults to "credentials")
+# Set to null if keys live directly in the root_subdir
+credentials_subdir: "credentials"
+```
+
+## Permissions
+
+On Unix-like systems, key files **must** have secure permissions. They must be owner-readable and **must not** be accessible by group or others (e.g., mode `0600` or `0400`). The app will raise an `InsecureKeyPermissionsError` and refuse to boot if permissions are too open.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "rails_outofband_keys", git: "git@github.com:lholden/rails_outofband_keys.git", tag: "v0.1.1"
+```
+
+## License
+
+MIT

data/lib/rails_outofband_keys/config.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsOutofbandKeys
+  # Configuration for RailsOutofbandKeys.
+  class Config
+    attr_accessor :root_subdir, :credentials_subdir, :key_dir_env
+
+    def initialize
+      @root_subdir = nil
+      @credentials_subdir = "credentials"
+      @key_dir_env = "RAILS_CREDENTIALS_KEY_DIR"
+    end
+  end
+end

data/lib/rails_outofband_keys/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module RailsOutofbandKeys
+  class Error < StandardError; end
+
+  # Error raised when key file permissions are too open.
+  class InsecureKeyPermissionsError < Error
+    def initialize(path, mode)
+      super("Insecure permissions on #{path} (#{mode}); expected 0600 or 0400")
+    end
+  end
+end

data/lib/rails_outofband_keys/key_resolver.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require "pathname"
+require "xdg"
+
+module RailsOutofbandKeys
+  # Resolves the path to the credentials key file.
+  class KeyResolver
+    def initialize(config:, rails_env:, app_name:)
+      @config = config
+      @rails_env = rails_env
+      @app_name = app_name
+    end
+
+    def resolve_key_path
+      return nil if ENV["RAILS_MASTER_KEY"] && !ENV["RAILS_MASTER_KEY"].empty?
+
+      key = find_key_in_resolved_dir
+      enforce_permissions!(key) if key
+      key&.to_s
+    end
+
+    private
+
+    def find_key_in_resolved_dir
+      dir = resolved_key_dir
+      env_key = dir.join("#{@rails_env}.key")
+      return env_key if env_key.file?
+
+      master_key = dir.join("master.key")
+      master_key.file? ? master_key : nil
+    end
+
+    def resolved_key_dir
+      base = resolve_base_dir
+      root = @config.root_subdir || @app_name
+
+      path_parts = [base, root]
+      path_parts << @config.credentials_subdir if @config.credentials_subdir
+
+      Pathname.new(File.join(*path_parts))
+    end
+
+    public
+
+    def resolve_base_dir
+      # Specific application override
+      override = ENV[@config.key_dir_env].to_s.strip
+      return override unless override.empty?
+
+      # Global base override
+      global_base = ENV["RAILS_OUTOFBAND_BASE_DIR"].to_s.strip
+      return global_base unless global_base.empty?
+
+      return ENV.fetch("APPDATA") if Gem.win_platform?
+
+      XDG.new.config_home.to_s
+    end
+
+    def enforce_permissions!(path)
+      return if Gem.win_platform?
+
+      mode = File.stat(path).mode & 0o777
+
+      owner_only = mode.nobits?(0o077)
+      readable = mode.anybits?(0o400)
+
+      return if owner_only && readable
+
+      raise InsecureKeyPermissionsError.new(path, format("0%o", mode))
+    end
+  end
+end

data/lib/rails_outofband_keys/railtie.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require "yaml"
+
+module RailsOutofbandKeys
+  # Railtie to integrate with Rails and automatically set key_path.
+  class Railtie < Rails::Railtie
+    config.rails_outofband_keys = RailsOutofbandKeys::Config.new
+
+    config.before_configuration do |app|
+      # Load file-based configuration.
+      config_file = File.join(Dir.getwd, "config", "rails_outofband_keys.yml")
+
+      if File.exist?(config_file)
+        external_config = YAML.load_file(config_file)
+        app.config.rails_outofband_keys.root_subdir = external_config["root_subdir"]
+        app.config.rails_outofband_keys.credentials_subdir = external_config.fetch("credentials_subdir", "credentials")
+      end
+
+      # Identify the app name for path resolution.
+      app_name = app.railtie_name.to_s.underscore.sub(/_application$/, "")
+
+      resolver = KeyResolver.new(
+        config: app.config.rails_outofband_keys,
+        rails_env: Rails.env,
+        app_name: app_name
+      )
+
+      key_path = resolver.resolve_key_path
+      if key_path
+        app.config.credentials.key_path = key_path
+
+        # Clear any early-cached credentials object to ensure the new path is used.
+        app.remove_instance_variable(:@credentials) if app.instance_variable_defined?(:@credentials)
+      end
+    end
+  end
+end

data/lib/rails_outofband_keys/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsOutofbandKeys
+  VERSION = "0.1.1"
+end

data/lib/rails_outofband_keys.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "rails_outofband_keys/version"
+require_relative "rails_outofband_keys/errors"
+require_relative "rails_outofband_keys/config"
+require_relative "rails_outofband_keys/key_resolver"
+require_relative "rails_outofband_keys/railtie"

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: rails_outofband_keys
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Lori Holden
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: xdg
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+description: |
+  Configures Rails credentials key_path to load environment/master key files
+  from an out-of-band directory (XDG on Unix/MacOS, AppData on Windows).
+email:
+- git@loriholden.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rails_outofband_keys.rb
+- lib/rails_outofband_keys/config.rb
+- lib/rails_outofband_keys/errors.rb
+- lib/rails_outofband_keys/key_resolver.rb
+- lib/rails_outofband_keys/railtie.rb
+- lib/rails_outofband_keys/version.rb
+homepage: https://github.com/lholden/rails_outofband_keys
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.2
+specification_version: 4
+summary: Resolve Rails credentials key files outside the project tree (XDG/AppData
+  + overrides).
+test_files: []