maquina_credentials 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 77da8a494d686b452f4ca9745d69aaa3ce3bff688c7010ef651ed078604e5495
+  data.tar.gz: 88d37fea885f62326aa550411ab702856c98079170f2c62caa35aa53b426e77e
+SHA512:
+  metadata.gz: ca1c6f06ff9cca2c67bd5438e57397cf9a80cd6ad59da3668d0e8b3d4edac1c2a13ab7af8235c64634f55b353a53d1d7b129a17bb08ace881835ad876335dd08
+  data.tar.gz: 5df16514d996d6fed68bb431c8c528c305eb1cedafa67dc47fb0298150b6b1e0559f2f015d065a6398345232a350cae4f41e8ab28a081dc4e41d71d49f18d6a4

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-24
+
+- Initial release
+- Encrypt and decrypt a `credentials.yml.enc` file with AES-256-GCM
+- `mcr` command line tool with `generate`, `read`, and `write` commands
+- Ruby API via `Maquina::Credentials`

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"maquina_credentials" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["mario.chavez@gmail.com"](mailto:"mario.chavez@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Mario Alberto Chávez Cárdenas (https://maquina.app)
+
+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,153 @@
+# Maquina Credentials
+
+Encrypt and decrypt a single `credentials.yml.enc` file with AES-256-GCM.
+
+`maquina_credentials` is a small, dependency-free gem for storing secrets in an
+encrypted file that can safely travel with your source or container image. The
+master key never lives in the file — it is supplied at runtime through the
+`MAQUINA_MASTER_KEY` environment variable. Reading a missing key returns an
+empty string and never raises, so it is safe to call in code paths that may run
+without credentials configured.
+
+It is inspired by Rails' encrypted credentials, distilled down to a single file,
+a command line tool, and a plain Ruby API — with no dependency on Rails or
+Active Support.
+
+## Installation
+
+Add it to your `Gemfile`:
+
+```ruby
+gem "maquina_credentials"
+```
+
+Then run `bundle install`. Or install it directly:
+
+```sh
+gem install maquina_credentials
+```
+
+Requires Ruby >= 3.2.0.
+
+## Master key
+
+Generate a master key once and store it as a secret (never commit it):
+
+```sh
+mcr generate
+```
+
+This prints a fresh random key built from `SecureRandom.hex(32)`. If you do not
+have the executable handy, the equivalent in plain Ruby is:
+
+```sh
+ruby -e "require 'securerandom'; puts SecureRandom.hex(32)"
+```
+
+Provide the key to every command through `MAQUINA_MASTER_KEY`. Any 32-byte key
+is used directly; keys of any other length (including the 64-character hex
+string above) are run through HKDF-SHA256 to derive the encryption key.
+
+## Command line
+
+The gem installs an `mcr` executable.
+
+Read a value (dot-paths traverse nested keys):
+
+```sh
+MAQUINA_MASTER_KEY=<key> mcr read database.password
+```
+
+Write credentials from piped YAML:
+
+```sh
+MAQUINA_MASTER_KEY=<key> printf "database:\n  password: prod-secret\n" | mcr write
+```
+
+Use a specific encrypted file:
+
+```sh
+mcr --file /path/to/credentials.yml.enc read database.password
+```
+
+Generate a new master key:
+
+```sh
+mcr generate
+```
+
+Show help:
+
+```sh
+mcr help
+```
+
+### File selection
+
+The encrypted file is resolved in this order:
+
+1. The `--file PATH` option, when given.
+2. The `MAQUINA_CREDENTIALS_FILE` environment variable.
+3. `credentials.yml.enc` in the current working directory.
+
+## Ruby API
+
+The same class is available through `require "maquina_credentials"`.
+
+```ruby
+credentials = Maquina::Credentials.new
+credentials.read("anthropic_key")
+credentials.read("database.password")  # dot-path traversal
+
+# Writing replaces the whole file from a full hash:
+Maquina::Credentials.write({
+  anthropic_key: "sk-ant-...",
+  database: {password: "prod-secret"}
+})
+```
+
+- Missing credential paths return an empty string (`""`), never `nil`.
+- All values are returned as strings.
+- A missing or empty `MAQUINA_MASTER_KEY` raises
+  `Maquina::Credentials::MasterKeyMissing` (only when a credentials file
+  actually exists).
+- A wrong key, tampered, truncated, or otherwise unreadable file raises
+  `Maquina::Credentials::DecryptionFailed`.
+- An instance decrypts once and caches the result for the life of the object.
+
+## Security notes
+
+- Cipher is AES-256-GCM; the wire format is strict-base64 of
+  `IV (12 bytes) || ciphertext || GCM auth tag (16 bytes)`.
+- A fresh random IV is generated on every write.
+- Writes are atomic (temp file renamed into place) and the file is set to mode
+  `0600`.
+- YAML is parsed with `safe_load(permitted_classes: [])` on both read and write,
+  so a tampered file cannot instantiate arbitrary Ruby objects.
+
+## Container workflow
+
+```sh
+# 1. Generate the master key once and store it as a secret.
+mcr generate
+
+# 2. Write credentials locally.
+MAQUINA_MASTER_KEY=<key> printf "anthropic_key: sk-ant-...\n" | mcr write
+
+# 3. Commit credentials.yml.enc into the image — the key never goes in.
+docker build -t my-app .
+
+# 4. Inject the key at runtime (or via orchestrator secrets).
+docker run -e MAQUINA_MASTER_KEY=<key> my-app
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`bundle exec rake` to run the tests and Standard Ruby. Use `bin/console` for an
+interactive prompt with the gem preloaded.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/exe/mcr

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "maquina_credentials"
+require "maquina/credentials/cli"
+
+exit Maquina::Credentials::CLI.start(ARGV)

data/lib/maquina/credentials/cli.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "securerandom"
+require "yaml"
+
+module Maquina
+  class Credentials
+    class CLI
+      def self.start(argv, stdout: $stdout, stderr: $stderr, stdin: $stdin)
+        new(argv, stdout: stdout, stderr: stderr, stdin: stdin).run
+      end
+
+      def initialize(argv, stdout:, stderr:, stdin:)
+        @argv = argv.dup
+        @stdout = stdout
+        @stderr = stderr
+        @stdin = stdin
+        @credentials_path = nil
+      end
+
+      def run
+        command = parser.parse!(@argv).first
+
+        case command
+        when "help", nil
+          @stdout.puts parser
+          0
+        when "generate"
+          generate
+        when "read"
+          read(@argv[1])
+        when "write"
+          write
+        else
+          @stderr.puts parser
+          command ? 1 : 0
+        end
+      rescue OptionParser::ParseError => error
+        @stderr.puts error.message
+        @stderr.puts parser
+        1
+      rescue MasterKeyMissing
+        @stderr.puts "MAQUINA_MASTER_KEY is required"
+        1
+      rescue DecryptionFailed
+        @stderr.puts "Failed to decrypt credentials"
+        1
+      rescue Psych::Exception
+        @stderr.puts "Input must be a valid YAML hash"
+        1
+      end
+
+      private
+
+      def parser
+        @parser ||= OptionParser.new do |options|
+          options.banner = <<~TEXT.chomp
+            Usage:
+              mcr help
+              mcr generate
+              mcr read KEY [--file PATH]
+              mcr write [--file PATH] < credentials.yml
+
+            Commands:
+              help      Show this help text.
+              generate  Print a new random master key to stdout.
+              read      Print a credential value to stdout.
+              write     Encrypt YAML from stdin and write it to the credentials file.
+
+            File selection:
+              Use --file PATH to read or write a specific file.
+              Without --file, mcr uses credentials.yml.enc in the current directory.
+
+            Examples:
+              mcr generate
+              mcr read database.password
+              mcr --file /tmp/credentials.yml.enc write < credentials.yml
+              mcr help
+          TEXT
+
+          options.on("-f", "--file PATH", "Credentials file path") do |path|
+            @credentials_path = path
+          end
+
+          options.on("-h", "--help", "Print this help") do
+            @stdout.puts options
+            exit 0
+          end
+        end
+      end
+
+      def generate
+        @stdout.puts SecureRandom.hex(32)
+        0
+      end
+
+      def read(key)
+        unless key
+          @stderr.puts "Missing KEY"
+          return 1
+        end
+
+        @stdout.puts Credentials.new(credentials_path: @credentials_path).read(key)
+        0
+      end
+
+      def write
+        input = @stdin.read
+        hash = YAML.safe_load(input, permitted_classes: [], symbolize_names: false)
+
+        unless hash.is_a?(Hash)
+          @stderr.puts "Input must be a YAML hash"
+          return 1
+        end
+
+        Credentials.write(hash, credentials_path: @credentials_path)
+        0
+      end
+    end
+  end
+end

data/lib/maquina/credentials.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "openssl"
+require "securerandom"
+require "yaml"
+
+module Maquina
+  class Credentials
+    class MasterKeyMissing < StandardError; end
+    class DecryptionFailed < StandardError; end
+
+    DEFAULT_CREDENTIALS_PATH = "credentials.yml.enc"
+    ENV_KEY = "MAQUINA_MASTER_KEY"
+    FILE_ENV_KEY = "MAQUINA_CREDENTIALS_FILE"
+    CIPHER = "aes-256-gcm"
+    KEY_LENGTH = 32
+    IV_LENGTH = 12
+    AUTH_TAG_LENGTH = 16
+    HKDF_INFO = "maquina-credentials-v1"
+
+    def self.write(hash, credentials_path: nil)
+      credentials_path = resolve_credentials_path(credentials_path)
+      payload = YAML.dump(deep_stringify(hash))
+      encrypted = encrypt(payload, master_key)
+      tmp_path = "#{credentials_path}.tmp.#{Process.pid}"
+
+      FileUtils.mkdir_p(File.dirname(credentials_path))
+      File.write(tmp_path, encrypted)
+      File.rename(tmp_path, credentials_path)
+      File.chmod(0o600, credentials_path)
+    ensure
+      File.delete(tmp_path) if tmp_path && File.exist?(tmp_path)
+    end
+
+    def self.encrypt(payload, raw_key)
+      cipher = OpenSSL::Cipher.new(CIPHER)
+      cipher.encrypt
+      cipher.key = derive_key(raw_key)
+      iv = cipher.random_iv
+      cipher.iv = iv
+      cipher.auth_data = ""
+
+      ciphertext = cipher.update(payload) + cipher.final
+      strict_base64_encode(iv + ciphertext + cipher.auth_tag)
+    end
+
+    def self.decrypt(encrypted, raw_key)
+      decoded = strict_base64_decode(encrypted)
+      raise DecryptionFailed if decoded.bytesize < IV_LENGTH + AUTH_TAG_LENGTH
+
+      iv = decoded.byteslice(0, IV_LENGTH)
+      auth_tag = decoded.byteslice(-AUTH_TAG_LENGTH, AUTH_TAG_LENGTH)
+      ciphertext = decoded.byteslice(IV_LENGTH, decoded.bytesize - IV_LENGTH - AUTH_TAG_LENGTH)
+
+      cipher = OpenSSL::Cipher.new(CIPHER)
+      cipher.decrypt
+      cipher.key = derive_key(raw_key)
+      cipher.iv = iv
+      cipher.auth_tag = auth_tag
+      cipher.auth_data = ""
+      cipher.update(ciphertext) + cipher.final
+    rescue ArgumentError, OpenSSL::Cipher::CipherError
+      raise DecryptionFailed
+    end
+
+    def self.strict_base64_encode(bytes)
+      [bytes].pack("m0")
+    end
+
+    def self.strict_base64_decode(encoded)
+      unless encoded.match?(/\A(?:[A-Za-z0-9+\/]{4})*(?:[A-Za-z0-9+\/]{2}==|[A-Za-z0-9+\/]{3}=)?\z/)
+        raise ArgumentError
+      end
+
+      encoded.unpack1("m0")
+    end
+
+    def self.derive_key(raw_key)
+      raw_key = raw_key.b
+      return raw_key[0, KEY_LENGTH] if raw_key.bytesize == KEY_LENGTH
+
+      OpenSSL::KDF.hkdf(
+        raw_key,
+        salt: "",
+        info: HKDF_INFO,
+        length: KEY_LENGTH,
+        hash: "SHA256"
+      )
+    end
+
+    def self.master_key
+      key = ENV[ENV_KEY]
+      raise MasterKeyMissing if key.nil? || key.empty?
+
+      key
+    end
+
+    def self.resolve_credentials_path(credentials_path = nil)
+      return credentials_path unless credentials_path.nil? || credentials_path.empty?
+
+      env_path = ENV[FILE_ENV_KEY]
+      return env_path unless env_path.nil? || env_path.empty?
+
+      File.join(Dir.pwd, DEFAULT_CREDENTIALS_PATH)
+    end
+
+    def self.deep_stringify(obj)
+      case obj
+      when Hash
+        obj.transform_keys(&:to_s).transform_values { |value| deep_stringify(value) }
+      when Array
+        obj.map { |value| deep_stringify(value) }
+      else
+        obj
+      end
+    end
+
+    def initialize(credentials_path: nil)
+      @credentials_path = self.class.resolve_credentials_path(credentials_path)
+      @credentials = nil
+      @loaded = false
+    end
+
+    def read(path)
+      return "" if path.nil? || path.empty?
+
+      value = path.split(".").reduce(credentials) do |current, key|
+        break unless current.is_a?(Hash)
+
+        current[key]
+      end
+
+      value.nil? ? "" : value.to_s
+    end
+
+    private
+
+    attr_reader :credentials_path
+
+    def credentials
+      return @credentials if @loaded
+
+      @credentials = load_credentials
+      @loaded = true
+      @credentials
+    end
+
+    def load_credentials
+      return {} unless File.exist?(credentials_path)
+
+      decrypted = self.class.decrypt(File.read(credentials_path), self.class.master_key)
+      loaded = YAML.safe_load(decrypted, permitted_classes: [], symbolize_names: false)
+      raise DecryptionFailed unless loaded.is_a?(Hash)
+
+      self.class.deep_stringify(loaded)
+    rescue Psych::Exception
+      raise DecryptionFailed
+    end
+  end
+end

data/lib/maquina_credentials/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Maquina
+  class Credentials
+    VERSION = "0.1.0"
+  end
+end

data/lib/maquina_credentials.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "maquina_credentials/version"
+require_relative "maquina/credentials"

data/sig/maquina_credentials.rbs

@@ -0,0 +1,23 @@
+module Maquina
+  class Credentials
+    VERSION: String
+
+    class MasterKeyMissing < StandardError
+    end
+
+    class DecryptionFailed < StandardError
+    end
+
+    def self.write: (Hash[untyped, untyped] hash, ?credentials_path: String? credentials_path) -> void
+
+    def self.encrypt: (String payload, String raw_key) -> String
+
+    def self.decrypt: (String encrypted, String raw_key) -> String
+
+    def self.resolve_credentials_path: (?String? credentials_path) -> String
+
+    def initialize: (?credentials_path: String? credentials_path) -> void
+
+    def read: (String? path) -> String
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: maquina_credentials
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Mario Alberto Chávez Cárdenas
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.16'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.55'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.55'
+description: A small, dependency-free gem that encrypts and decrypts a single credentials.yml.enc
+  file with AES-256-GCM. Ships an `mcr` command line tool for reading and writing
+  values, plus a Ruby API. Designed for container and server workflows where the encrypted
+  file travels with the image and the master key is injected at runtime via MAQUINA_MASTER_KEY.
+email:
+- mario.chavez@gmail.com
+executables:
+- mcr
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- exe/mcr
+- lib/maquina/credentials.rb
+- lib/maquina/credentials/cli.rb
+- lib/maquina_credentials.rb
+- lib/maquina_credentials/version.rb
+- sig/maquina_credentials.rbs
+homepage: https://maquina.app
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://maquina.app
+  source_code_uri: https://github.com/maquina-app/maquina_credentials
+  documentation_uri: https://github.com/maquina-app/maquina_credentials/blob/main/README.md
+  changelog_uri: https://github.com/maquina-app/maquina_credentials/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/maquina-app/maquina_credentials/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: Encrypted credentials for the command line
+test_files: []