dotenv-secretsmanager 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: aff4454079cc1d1cbb65a127d128f185343e0f68527fea618e2939282db02a60
+  data.tar.gz: 570fb3b58c722c78f5d38ba24657cf299463256e78bd4fffd9832b34e760c330
+SHA512:
+  metadata.gz: f59d0999d3ce01cf9d4cc3a0afcda6eacf66b4ee89ee60d0108b2cf895c1deb9ddc99ea0c45b5b08dc02627edf292b97f788326603f40884a5bcd29efd5114e2
+  data.tar.gz: af7e008123e0b98461a01091d49d69deb4c9d994eba3f34c0b6e30e55959b1a6b9bfd0e1a00d5b453a399b804a88965fae5e83892d01e6b007cda74604bf60ca

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 key88sf
+
+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 @@
+# dotenv-secretsmanager
+
+Use AWS Secrets Manager references in your Ruby dotenv files. A `.env` value that
+begins with `aws-sm:` is resolved from AWS Secrets Manager at process boot and
+written into `ENV` in place.
+
+## Installation
+
+```ruby
+# Gemfile — require AFTER dotenv-rails so ENV is populated first
+gem "dotenv-rails"
+gem "dotenv-secretsmanager"
+```
+
+```sh
+bundle install
+```
+
+## Reference syntax
+
+```bash
+# whole plaintext secret
+RAILS_MASTER_KEY=aws-sm:myproject/master-key
+
+# one key from a JSON secret (all three share a single API call)
+DB_PASSWORD=aws-sm:myproject/prod|db_password
+YELP_SECRET=aws-sm:myproject/prod|yelp_client_secret
+TWILIO_TOKEN=aws-sm:myproject/prod|twilio_auth_token
+
+# non-reference values are left untouched
+RAILS_LOG_LEVEL=info
+```
+
+`<secret-id>` may be a friendly name or a full ARN. The optional `|<json-key>`
+selector is split on the last `|`, so ARNs (full of colons, never pipes) parse
+correctly.
+
+## Rails
+
+No wiring needed. The railtie resolves references automatically after
+`dotenv-rails` loads and before initializers and `database.yml` run.
+
+## Plain Ruby
+
+```ruby
+require "dotenv/secretsmanager"
+Dotenv::SecretsManager.resolve!(ENV)
+```
+
+## Configuration
+
+```ruby
+Dotenv::SecretsManager.configure do |c|
+  c.on_error = :raise   # :raise (default) — aggregate all failures, raise once
+                        # :warn            — log each failure, leave literal in ENV
+  c.logger   = nil      # defaults to Rails.logger if present, else $stderr
+  c.client   = nil      # inject a custom Aws::SecretsManager::Client
+end
+```
+
+Credentials and region come from the standard AWS SDK credential chain. The gem
+makes zero AWS calls and builds no client when no references are present.
+
+## Deployment (AWS Lightsail Container Service)
+
+Set only `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` as
+plaintext deployment env vars (a least-privilege IAM user with
+`secretsmanager:GetSecretValue` scoped to your secrets). Put everything else in
+`.env.production` as `aws-sm:` references. Keep `.env.development` free of
+references so local development needs no AWS access.

data/lib/dotenv/secretsmanager/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module SecretsManager
+    class Configuration
+      # :raise (default) | :warn
+      attr_accessor :on_error
+      # nil => Rails.logger if present, else a $stderr Logger (resolved at use time)
+      attr_accessor :logger
+      # nil => a default Aws::SecretsManager::Client (built lazily, only if needed)
+      attr_accessor :client
+
+      def initialize
+        @on_error = :raise
+        @logger = nil
+        @client = nil
+      end
+    end
+  end
+end

data/lib/dotenv/secretsmanager/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module SecretsManager
+    # Raised (under on_error: :raise) when one or more references cannot be
+    # resolved. The message aggregates every failing env var.
+    class ResolutionError < StandardError; end
+  end
+end

data/lib/dotenv/secretsmanager/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "dotenv/secretsmanager"
+
+module Dotenv
+  module SecretsManager
+    # Auto-resolves aws-sm: references in a Rails app. Runs in the
+    # before_configuration phase, which is after dotenv-rails populates ENV
+    # (provided this gem is required after dotenv-rails) and before initializers
+    # and database.yml consume the values.
+    class Railtie < ::Rails::Railtie
+      config.before_configuration do
+        Dotenv::SecretsManager.resolve!(ENV)
+      end
+    end
+  end
+end

data/lib/dotenv/secretsmanager/reference.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module SecretsManager
+    # Parses a single .env value into its Secrets Manager components.
+    #
+    #   aws-sm:<secret-id>             => whole secret string
+    #   aws-sm:<secret-id>|<json-key>  => one key from a JSON secret
+    #
+    # The remainder after the scheme is split on the LAST pipe, so neither a
+    # friendly name nor an ARN (which contain no pipe) is ever mis-split.
+    class Reference
+      SCHEME = "aws-sm:"
+
+      attr_reader :raw, :secret_id, :json_key
+
+      def self.reference?(value)
+        value.is_a?(String) && value.start_with?(SCHEME)
+      end
+
+      def self.parse(value)
+        new(value)
+      end
+
+      def initialize(raw)
+        @raw = raw
+        remainder = raw[SCHEME.length..] || ""
+
+        if remainder.include?("|")
+          before, _, after = remainder.rpartition("|")
+          @secret_id = before
+          @json_key = after
+        else
+          @secret_id = remainder
+          @json_key = nil
+        end
+      end
+
+      def malformed?
+        return true if @secret_id.nil? || @secret_id.empty?
+        return true if !@json_key.nil? && @json_key.empty?
+
+        false
+      end
+    end
+  end
+end

data/lib/dotenv/secretsmanager/resolver.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Dotenv
+  module SecretsManager
+    class Resolver
+      Failure = Struct.new(:env_key, :reference, :reason)
+
+      # Internal control-flow signal for a single unresolvable reference.
+      # Never escapes resolve!; the public type is ResolutionError.
+      class ResolutionFailure < StandardError; end
+
+      def initialize(env:, config:)
+        @env = env
+        @config = config
+        @secret_cache = {}
+      end
+
+      def resolve!
+        references = collect_references
+        return @env if references.empty?
+
+        failures = []
+        references.each do |env_key, reference|
+          @env[env_key] = resolve_one(reference)
+        rescue ResolutionFailure => e
+          failures << Failure.new(env_key, reference, e.message)
+        end
+
+        handle_failures(failures) unless failures.empty?
+        @env
+      end
+
+      private
+
+      def collect_references
+        @env.keys.each_with_object([]) do |key, acc|
+          value = @env[key]
+          acc << [key, Reference.parse(value)] if Reference.reference?(value)
+        end
+      end
+
+      def resolve_one(reference)
+        raise ResolutionFailure, "malformed reference" if reference.malformed?
+
+        secret = fetch(reference.secret_id)
+        reference.json_key ? extract_json_key(secret, reference) : secret
+      end
+
+      # One GetSecretValue per distinct secret-id for the whole pass. A failed
+      # fetch is cached as the failure so repeated references neither refetch nor
+      # silently succeed.
+      def fetch(secret_id)
+        @secret_cache[secret_id] = fetch_uncached(secret_id) unless @secret_cache.key?(secret_id)
+
+        result = @secret_cache[secret_id]
+        raise result if result.is_a?(ResolutionFailure)
+
+        result
+      end
+
+      def fetch_uncached(secret_id)
+        response = client.get_secret_value(secret_id: secret_id)
+        string = response.secret_string
+        return ResolutionFailure.new("secret '#{secret_id}' has no string value") if string.nil?
+
+        string
+      rescue Aws::Errors::ServiceError => e
+        ResolutionFailure.new("AWS error for '#{secret_id}': #{e.message}")
+      end
+
+      def extract_json_key(secret, reference)
+        data =
+          begin
+            JSON.parse(secret)
+          rescue JSON::ParserError
+            raise ResolutionFailure, "secret '#{reference.secret_id}' is not valid JSON"
+          end
+
+        unless data.is_a?(Hash)
+          raise ResolutionFailure, "secret '#{reference.secret_id}' is not a JSON object"
+        end
+        unless data.key?(reference.json_key)
+          raise ResolutionFailure,
+                "key '#{reference.json_key}' not found in secret '#{reference.secret_id}'"
+        end
+
+        data.fetch(reference.json_key).to_s
+      end
+
+      def handle_failures(failures)
+        if @config.on_error == :warn
+          failures.each { |f| logger.warn("[dotenv-secretsmanager] #{failure_line(f)}") }
+        else
+          raise ResolutionError, build_error_message(failures)
+        end
+      end
+
+      def failure_line(failure)
+        "#{failure.env_key} (#{failure.reference.raw}): #{failure.reason}"
+      end
+
+      def build_error_message(failures)
+        lines = failures.map { |f| "  - #{failure_line(f)}" }
+        "Failed to resolve #{failures.size} Secrets Manager reference(s):\n#{lines.join("\n")}"
+      end
+
+      def client
+        @client ||= @config.client || Aws::SecretsManager::Client.new
+      end
+
+      def logger
+        @logger ||= @config.logger || default_logger
+      end
+
+      def default_logger
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger
+        else
+          require "logger"
+          Logger.new($stderr)
+        end
+      end
+    end
+  end
+end

data/lib/dotenv/secretsmanager/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Dotenv
+  module SecretsManager
+    VERSION = "0.1.0"
+  end
+end

data/lib/dotenv/secretsmanager.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "dotenv/secretsmanager/version"
+require "dotenv/secretsmanager/errors"
+require "dotenv/secretsmanager/configuration"
+require "dotenv/secretsmanager/reference"
+require "aws-sdk-secretsmanager"
+require "dotenv/secretsmanager/resolver"
+
+module Dotenv
+  module SecretsManager
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration) if block_given?
+        configuration
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      def resolve!(env = ENV)
+        Resolver.new(env: env, config: configuration).resolve!
+      end
+    end
+  end
+end
+
+require "dotenv/secretsmanager/railtie" if defined?(Rails::Railtie)

data/lib/dotenv-secretsmanager.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "dotenv/secretsmanager"

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: dotenv-secretsmanager
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- key88sf
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-secretsmanager
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: 'Treats .env values beginning with aws-sm: as references to AWS Secrets
+  Manager secrets, resolving them into ENV at process boot. Framework-agnostic core
+  with an optional Rails railtie.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dotenv-secretsmanager.rb
+- lib/dotenv/secretsmanager.rb
+- lib/dotenv/secretsmanager/configuration.rb
+- lib/dotenv/secretsmanager/errors.rb
+- lib/dotenv/secretsmanager/railtie.rb
+- lib/dotenv/secretsmanager/reference.rb
+- lib/dotenv/secretsmanager/resolver.rb
+- lib/dotenv/secretsmanager/version.rb
+homepage: https://github.com/key88sf/dotenv-secretsmanager
+licenses:
+- MIT
+metadata: {}
+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.11
+specification_version: 4
+summary: Resolve AWS Secrets Manager references inside .env files at boot.
+test_files: []