rails_credentials_cipher 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 412dc01065aa8cd5f4fde42a2ee138a9d16309feee95cc8f662b83cead22804d
+  data.tar.gz: 20bd9b1fe47fb6f5fbe266e79a84cb08aed3ae06bae71ea83ecb17bd72cf5cb2
+SHA512:
+  metadata.gz: 96e844c86ab106d790a1ec44117581e0dd1418a8b14bd8de9e60afd4125fba385264b0cd5bc62617c61f693e4e1fcbde39e8a0334eedd9887108812beaea964e
+  data.tar.gz: d1519c0a71b45fa7422822f7840ba0ed2b1ca5847b9c5dd43fc293de556622834b0872a9b8534e3a0b1ceaa482296cb0718764a894db4ba60e1b71d5ec6c08a5

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,21 @@
+plugins:
+  - rubocop-on-rbs
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  # The oldest Ruby the gem supports (required_ruby_version), not the one in .tool-versions
+  TargetRubyVersion: 3.3
+  NewCops: enable
+
+# Do not enforce documentation
+Style/Documentation:
+  Enabled: false
+
+# A round trip is one behaviour with a return value, a file on disk and a message
+RSpec/MultipleExpectations:
+  Max: 3
+
+# A round trip needs its setup, the call and the check on disk
+RSpec/ExampleLength:
+  Enabled: false

data/.tool-versions

@@ -0,0 +1 @@
+ruby 4.0.5

data/AGENTS.md

@@ -0,0 +1,27 @@
+# RailsCredentialsCipher
+
+@README.md
+
+A gem that adds `credentials:decrypt` and `credentials:encrypt` rake tasks to Rails applications.
+
+## Instructions
+
+- MUST pass `bundle exec rspec`, `bundle exec rubocop` and `bundle exec steep check` before finishing. MUST NOT disable a cop or a Steep diagnostic without the reason next to it.
+- MUST NOT print or log decrypted content; messages name paths only.
+- Specs MUST NOT need a Rails application; `stub_rails` in `spec/spec_helper.rb` stands in for it.
+- `sig/rails_credentials_cipher.rbs` types the gem and `sig/external/` the slice of Rails it calls; Steep checks `lib/` against both, so a method is not done until its signature is. `sig/external/` is not shipped with the gem.
+- Ruby floor is the oldest version still maintained (3.3): `required_ruby_version`, `TargetRubyVersion` and the CI matrix move together, and `TargetRubyVersion` stays below `.tool-versions` on purpose.
+
+## Development
+
+```sh
+mise install && bin/setup                 # Ruby from .tool-versions, then bundle install
+bundle exec rspec                         # tests; add a path or path:line for one file or example
+bundle exec rubocop -A                    # lint with auto-fix, RBS files included
+bundle exec steep check                   # types: lib/ against sig/
+bundle exec bundler-audit check --update  # dependency audit
+```
+
+To try it in a Rails application, add `gem "rails_credentials_cipher", path: "../rails_credentials_cipher", group: :development` to its Gemfile and run `bin/rails credentials:decrypt` there with its `config/master.key` present.
+
+Release: bump `lib/rails_credentials_cipher/version.rb`, `bundle install` so `Gemfile.lock` follows, commit, then `bundle exec rake release`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 thisismydesign
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,70 @@
+# RailsCredentialsCipher
+
+#### Decrypt, edit, and encrypt Rails credentials.
+
+Rails keeps your credentials encrypted and only lets you change them through `bin/rails credentials:edit`, which opens them in a terminal editor. This gem lets you take them out as a plain file, edit that file with whatever you like — your IDE, a coding agent, a script — and encrypt it back.
+
+## Installation
+
+Add to your application's Gemfile:
+
+```rb
+gem "rails_credentials_cipher", group: :development
+```
+
+Then keep the decrypted files out of git:
+
+```sh
+bin/rails generate rails_credentials_cipher:install
+```
+
+This adds to `.gitignore`:
+
+```gitignore
+/config/credentials.yml
+/config/credentials/*.yml
+```
+
+## Usage
+
+```sh
+bin/rails credentials:decrypt    # config/credentials.yml.enc -> config/credentials.yml
+# edit config/credentials.yml
+bin/rails credentials:encrypt    # config/credentials.yml -> config/credentials.yml.enc
+```
+
+For per-environment credentials, add the environment:
+
+```sh
+bin/rails credentials:decrypt:production    # config/credentials/production.yml.enc -> config/credentials/production.yml
+bin/rails credentials:encrypt:production
+```
+
+## Development
+
+```sh
+mise install && bin/setup     # Ruby from .tool-versions, then bundle install
+bundle exec rspec             # tests
+bundle exec rubocop -A        # lint with auto-fix
+bundle exec steep check       # types: lib/ against sig/
+```
+
+To try it in a Rails application, point its Gemfile at your checkout and run the tasks there:
+
+```rb
+gem "rails_credentials_cipher", path: "../rails_credentials_cipher", group: :development
+```
+
+To release, bump the version in `lib/rails_credentials_cipher/version.rb`, run `bundle install` so `Gemfile.lock` follows, commit, then:
+
+```sh
+bundle exec rake release      # tags v<version>, pushes the commits and the tag, pushes the gem to rubygems.org
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/thisismydesign/rails_credentials_cipher.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module RailsCredentialsCipher
+  module Generators
+    # bin/rails generate rails_credentials_cipher:install
+    class InstallGenerator < Rails::Generators::Base
+      desc 'Adds the decrypted credentials files to .gitignore'
+
+      IGNORES = ['/config/credentials.yml', '/config/credentials/*.yml'].freeze
+
+      def ignore_decrypted_credentials
+        missing = IGNORES.reject { |pattern| ignored?(pattern) }
+        return say_status :identical, '.gitignore already ignores the decrypted credentials', :blue if missing.empty?
+
+        lines = "# Decrypted credentials, see rails_credentials_cipher\n#{missing.join("\n")}\n"
+        if File.exist?(gitignore_path)
+          append_to_file '.gitignore', "\n#{lines}"
+        else
+          create_file '.gitignore', lines
+        end
+      end
+
+      private
+
+      def gitignore_path
+        File.join(destination_root, '.gitignore')
+      end
+
+      # A pattern with or without the leading slash covers the same file at the root.
+      def ignored?(pattern)
+        return false unless File.exist?(gitignore_path)
+
+        File.readlines(gitignore_path, chomp: true).map { |line| line.strip.delete_prefix('/') }
+            .include?(pattern.delete_prefix('/'))
+      end
+    end
+  end
+end

data/lib/rails_credentials_cipher/cipher.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'active_support'
+require 'active_support/encrypted_file'
+
+module RailsCredentialsCipher
+  # Moves one encrypted file between its encrypted form (`config/credentials.yml.enc`)
+  # and a plain file next to it (`config/credentials.yml`), using the same
+  # ActiveSupport::EncryptedFile that Rails reads the credentials with.
+  class Cipher
+    attr_reader :encrypted_path, :key_path, :env_key, :plain_path
+
+    def initialize(encrypted_path:, key_path:, env_key: 'RAILS_MASTER_KEY', plain_path: nil)
+      @encrypted_path = Pathname(encrypted_path)
+      @key_path = Pathname(key_path)
+      @env_key = env_key
+      @plain_path = plain_path ? Pathname(plain_path) : default_plain_path
+    end
+
+    # Writes the decrypted content to the plain path. Returns the plain path.
+    def decrypt
+      plain_path.binwrite(encrypted_file.read)
+      plain_path
+    end
+
+    # Encrypts the plain file over the encrypted path. Returns the encrypted
+    # path when it was rewritten and nil when the content was already the same,
+    # so an unchanged file does not get a new ciphertext.
+    def encrypt
+      raise Error, "#{plain_path} does not exist, decrypt first" unless plain_path.exist?
+
+      contents = plain_path.binread
+      return if unchanged?(contents)
+
+      encrypted_file.write(contents)
+      encrypted_path
+    end
+
+    private
+
+    def default_plain_path
+      unless encrypted_path.extname == '.enc'
+        raise Error,
+              "cannot derive a plain path from #{encrypted_path}, pass plain_path:"
+      end
+
+      encrypted_path.sub_ext('')
+    end
+
+    def unchanged?(contents)
+      encrypted_path.exist? && encrypted_file.read == contents
+    rescue ActiveSupport::MessageEncryptor::InvalidMessage
+      false
+    end
+
+    def encrypted_file
+      @encrypted_file ||= ActiveSupport::EncryptedFile.new(
+        content_path: encrypted_path,
+        key_path: key_path,
+        env_key: env_key,
+        raise_if_missing_key: true
+      )
+    end
+  end
+end

data/lib/rails_credentials_cipher/railtie.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module RailsCredentialsCipher
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path('../tasks/credentials.rake', File.dirname(__FILE__))
+    end
+  end
+end

data/lib/rails_credentials_cipher/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsCredentialsCipher
+  VERSION = '1.0.0'
+end

data/lib/rails_credentials_cipher.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'English'
+require_relative 'rails_credentials_cipher/version'
+require_relative 'rails_credentials_cipher/cipher'
+require_relative 'rails_credentials_cipher/railtie' if defined?(Rails::Railtie)
+
+module RailsCredentialsCipher
+  class Error < StandardError; end
+
+  class << self
+    # Decrypts the application's credentials into a plain file next to the
+    # encrypted one, and warns when that file is not ignored by git.
+    def decrypt(environment: nil, out: $stdout)
+      cipher = cipher(environment:)
+      explaining(cipher) { cipher.decrypt }
+      out.puts "Decrypted #{relative(cipher.encrypted_path)} to #{relative(cipher.plain_path)}"
+      out.puts "Warning: #{relative(cipher.plain_path)} is not ignored by git" if git_tracked?(cipher.plain_path)
+      cipher.plain_path
+    end
+
+    # Encrypts the plain file back over the application's credentials.
+    def encrypt(environment: nil, out: $stdout)
+      cipher = cipher(environment:)
+      if explaining(cipher) { cipher.encrypt }
+        out.puts "Encrypted #{relative(cipher.plain_path)} to #{relative(cipher.encrypted_path)}"
+      else
+        out.puts "#{relative(cipher.encrypted_path)} already matches #{relative(cipher.plain_path)}, nothing to do"
+      end
+      cipher.encrypted_path
+    end
+
+    # The environments the application defines, which is what Rails' own
+    # credentials command offers for --environment.
+    def environments
+      Dir[Rails.root.join('config/environments/*.rb').to_s].map { |file| File.basename(file, '.rb') }.sort
+    end
+
+    # The cipher for the credentials the running application would use, or for
+    # the given environment's `config/credentials/<environment>.yml.enc`. The key
+    # falls back from `config/credentials/<environment>.key` to `config/master.key`
+    # the way Rails does; `RAILS_MASTER_KEY` wins over both.
+    def cipher(environment: nil)
+      encrypted_path, key_path = paths(environment:)
+      Cipher.new(encrypted_path:, key_path:)
+    end
+
+    private
+
+    # Turns the encryption errors into one Error whose message says what to do.
+    def explaining(cipher)
+      yield
+    rescue ActiveSupport::EncryptedFile::MissingKeyError
+      raise Error, "No key for #{relative(cipher.encrypted_path)}: " \
+                   "set #{cipher.env_key} or write it to #{relative(cipher.key_path)}"
+    rescue ActiveSupport::MessageEncryptor::InvalidMessage
+      raise Error, "Could not decrypt #{relative(cipher.encrypted_path)}: " \
+                   "the key in #{cipher.env_key} or #{relative(cipher.key_path)} is not the one it was encrypted with"
+    rescue ActiveSupport::EncryptedFile::MissingContentError
+      raise Error, "#{relative(cipher.encrypted_path)} does not exist"
+    end
+
+    def paths(environment:)
+      return app_paths unless environment
+
+      key_path = Rails.root.join("config/credentials/#{environment}.key")
+      key_path = Rails.root.join('config/master.key') unless key_path.exist?
+      [Rails.root.join("config/credentials/#{environment}.yml.enc"), key_path]
+    end
+
+    def app_paths
+      config = Rails.application.config.credentials
+      [Rails.root.join(config.content_path), Rails.root.join(config.key_path)]
+    end
+
+    def relative(path)
+      path.relative_path_from(Rails.root)
+    end
+
+    # True only when git says the file is not ignored; a missing git or a
+    # directory outside any repository is not a reason to warn.
+    def git_tracked?(path)
+      system('git', 'check-ignore', '-q', path.to_s, chdir: Rails.root.to_s, out: File::NULL, err: File::NULL)
+      $CHILD_STATUS&.exitstatus == 1
+    end
+  end
+end

data/lib/tasks/credentials.rake

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# Stops with the explanation instead of a stack trace.
+abort_on_error = lambda do |&work|
+  work.call
+rescue RailsCredentialsCipher::Error => e
+  abort e.message
+end
+
+namespace :credentials do
+  desc 'Decrypt the credentials into a plain file for editing'
+  task decrypt: :environment do
+    abort_on_error.call { RailsCredentialsCipher.decrypt }
+  end
+
+  desc 'Encrypt the plain file back over the credentials'
+  task encrypt: :environment do
+    abort_on_error.call { RailsCredentialsCipher.encrypt }
+  end
+
+  RailsCredentialsCipher.environments.each do |env|
+    namespace :decrypt do
+      desc "Decrypt config/credentials/#{env}.yml.enc into a plain file for editing"
+      task env => :environment do
+        abort_on_error.call { RailsCredentialsCipher.decrypt(environment: env) }
+      end
+    end
+
+    namespace :encrypt do
+      desc "Encrypt the plain file back over config/credentials/#{env}.yml.enc"
+      task env => :environment do
+        abort_on_error.call { RailsCredentialsCipher.encrypt(environment: env) }
+      end
+    end
+  end
+end

data/sig/rails_credentials_cipher.rbs

@@ -0,0 +1,58 @@
+module RailsCredentialsCipher
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  interface _Puts
+    def puts: (*untyped) -> void
+  end
+
+  type paths = [Pathname, Pathname]
+
+  def self.decrypt: (?environment: String?, ?out: _Puts) -> Pathname
+  def self.encrypt: (?environment: String?, ?out: _Puts) -> Pathname
+  def self.environments: () -> Array[String]
+  def self.cipher: (?environment: String?) -> Cipher
+
+  def self.explaining: [T] (Cipher cipher) { () -> T } -> T
+  def self.paths: (environment: String?) -> paths
+  def self.app_paths: () -> paths
+  def self.relative: (Pathname path) -> Pathname
+  def self.git_tracked?: (Pathname path) -> bool
+
+  class Cipher
+    attr_reader encrypted_path: Pathname
+    attr_reader key_path: Pathname
+    attr_reader env_key: String
+    attr_reader plain_path: Pathname
+
+    @encrypted_file: ActiveSupport::EncryptedFile?
+
+    def initialize: (encrypted_path: String | Pathname, key_path: String | Pathname, ?env_key: String, ?plain_path: (String | Pathname)?) -> void
+    def decrypt: () -> Pathname
+    def encrypt: () -> Pathname?
+
+    private
+
+    def default_plain_path: () -> Pathname
+    def unchanged?: (String contents) -> bool
+    def encrypted_file: () -> ActiveSupport::EncryptedFile
+  end
+
+  class Railtie < Rails::Railtie
+  end
+
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      IGNORES: Array[String]
+
+      def ignore_decrypted_credentials: () -> void
+
+      private
+
+      def gitignore_path: () -> String
+      def ignored?: (String pattern) -> bool
+    end
+  end
+end

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification
+name: rails_credentials_cipher
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- thisismydesign
+bindir: exe
+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: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+email:
+- git.thisismydesign@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".tool-versions"
+- AGENTS.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/rails_credentials_cipher/install/install_generator.rb
+- lib/rails_credentials_cipher.rb
+- lib/rails_credentials_cipher/cipher.rb
+- lib/rails_credentials_cipher/railtie.rb
+- lib/rails_credentials_cipher/version.rb
+- lib/tasks/credentials.rake
+- sig/rails_credentials_cipher.rbs
+homepage: https://github.com/thisismydesign/rails_credentials_cipher
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/thisismydesign/rails_credentials_cipher
+  source_code_uri: https://github.com/thisismydesign/rails_credentials_cipher
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: Decrypt, edit, and encrypt Rails credentials.
+test_files: []