active_cipher_storage 1.0.3 → 2.0.0

data/lib/active_cipher_storage/configuration.rb

@@ -6,19 +6,21 @@ module ActiveCipherStorage
     # Supported algorithm identifiers.
     ALGORITHMS = %w[aes-256-gcm].freeze
 
-    # Bytes per plaintext chunk in streaming mode (default 5 MiB — matches the
-    # minimum S3 multipart part size, so each chunk maps to exactly one part).
+    # Minimum S3 multipart part size (except the last part). Streaming encryptors
+    # should use chunk_size >= this value when using S3 multipart.
     MINIMUM_S3_MULTIPART_PART_SIZE = 5 * 1024 * 1024
-    DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024
+    # Default plaintext bytes per chunk when a caller does not pass chunk_size.
+    DEFAULT_CHUNK_SIZE = MINIMUM_S3_MULTIPART_PART_SIZE
 
     attr_reader :config
 
     def initialize
       @config = ActiveSupport::OrderedOptions.new
       self.algorithm = "aes-256-gcm"
-      self.chunk_size = DEFAULT_CHUNK_SIZE
       self.encrypt_uploads = true
       self.logger = Logger.new($stdout, level: Logger::WARN)
+      @provider_input = nil
+      @provider = nil
     end
 
     def algorithm
@@ -29,14 +31,6 @@ module ActiveCipherStorage
       config.algorithm = value
     end
 
-    def chunk_size
-      config.chunk_size
-    end
-
-    def chunk_size=(value)
-      config.chunk_size = value
-    end
-
     def encrypt_uploads
       config.encrypt_uploads
     end
@@ -53,19 +47,33 @@ module ActiveCipherStorage
       config.logger = value
     end
 
+    # Keyword arguments for built-in providers (`:env`, `:aws_kms`, `"aws:kms"`, etc.),
+    # passed through to EnvProvider / AwsKmsProvider.
+    def provider_options
+      config.provider_options ||= ActiveSupport::OrderedOptions.new
+    end
+
     def provider
-      config.provider
+      @provider ||= resolve_provider_input
     end
 
-    # Accept a provider instance or a symbol shorthand (:env, :aws_kms).
+    # Sets the KMS provider. Use a shorthand symbol or string, or pass a custom
+    # Providers::Base instance:
+    #
+    #   config.provider = :env
+    #   config.provider = :aws_kms
+    #   config.provider = "aws:kms"
+    #   config.provider_options[:key_id] = "arn:..." # optional; see provider docs
+    #   config.provider = MyKmsProvider.new
     def provider=(value)
-      config.provider = case value
-                        when Symbol then resolve_provider(value)
-                        when Providers::Base then value
+      @provider = nil
+      @provider_input = case value
+                        when Providers::Base, Symbol, String, NilClass then value
                         else
                           raise ArgumentError,
-                                "provider must be a Providers::Base instance or " \
-                                "one of :env, :aws_kms — got #{value.inspect}"
+                                "provider must be a Providers::Base instance, " \
+                                "a supported symbol/string (:env, :aws_kms, \"aws:kms\"), " \
+                                "or nil — got #{value.inspect}"
                         end
     end
 
@@ -78,8 +86,6 @@ module ActiveCipherStorage
               "Supported: #{ALGORITHMS.join(', ')}"
       end
 
-      raise ArgumentError, "chunk_size must be positive" unless chunk_size.positive?
-
       return if [true, false].include?(encrypt_uploads)
 
       raise ArgumentError, "encrypt_uploads must be true or false"
@@ -87,12 +93,39 @@ module ActiveCipherStorage
 
     private
 
-    def resolve_provider(sym)
-      case sym
-      when :env     then Providers::EnvProvider.new
-      when :aws_kms then Providers::AwsKmsProvider.new
+    def resolve_provider_input
+      case @provider_input
+      when Providers::Base
+        @provider_input
+      when nil
+        nil
+      when Symbol, String
+        build_provider(parse_provider_name(@provider_input))
+      else
+        raise ArgumentError, "Unsupported provider #{@provider_input.inspect}"
+      end
+    end
+
+    def parse_provider_name(name)
+      case name.to_s.strip.downcase
+      when "env" then :env
+      when "aws:kms", "aws_kms", "aws-kms", "kms" then :aws_kms
+      else
+        raise ArgumentError,
+              "Unknown provider #{name.inspect}; use :env, :aws_kms, \"aws:kms\", " \
+              "or a Providers::Base subclass instance"
+      end
+    end
+
+    def build_provider(kind)
+      opts = provider_options.to_h.symbolize_keys.compact
+      case kind
+      when :env
+        Providers::EnvProvider.new(**opts)
+      when :aws_kms
+        Providers::AwsKmsProvider.new(**opts)
       else
-        raise ArgumentError, "Unknown provider shorthand: #{sym.inspect}"
+        raise ArgumentError, "Unknown provider kind #{kind.inspect}"
       end
     end
   end

data/lib/active_cipher_storage/engine.rb

@@ -6,24 +6,8 @@ module ActiveCipherStorage
 
     initializer "active_cipher_storage.setup" do
       ActiveSupport.on_load(:active_storage) do
-        # Register our service so Rails' configurator can resolve it by name.
-        # When config/storage.yml has `service: ActiveCipherStorage`, Rails
-        # looks for ActiveStorage::Service::ActiveCipherStorageService or falls
-        # back to a registered mapping.  We register both names for safety.
-        require "active_cipher_storage/adapters/active_storage_service"
-
-        # Rails 7.1+ uses Configurator#build which calls
-        # SomeServiceClass.build(configurator:, **opts) when defined.
-        # Older Rails falls back to .new(**opts).  Both are supported.
-        ActiveStorage::Service.send(:const_set,
-          :ActiveCipherStorageService,
-          ActiveCipherStorage::Adapters::ActiveStorageService
-        ) unless ActiveStorage::Service.const_defined?(:ActiveCipherStorageService, false)
+        require "active_storage/service/active_cipher_storage_service"
       end
     end
-
-    initializer "active_cipher_storage.log_subscriber" do
-      ActiveSupport::LogSubscriber.logger ||= Logger.new($stdout)
-    end
   end
 end

data/lib/active_cipher_storage/errors.rb

@@ -16,8 +16,8 @@ module ActiveCipherStorage
     # Raised when the KMS provider cannot wrap/unwrap a data key.
     class KeyManagementError < ProviderError; end
 
-    # Raised when a caller tries to use a feature the active provider doesn't
-    # implement (e.g. key rotation on EnvProvider).
+    # Raised when a caller tries to use a feature the active provider does not
+    # implement (e.g. direct upload URL when encryption is required).
     class UnsupportedOperation < Error; end
   end
 

data/lib/active_cipher_storage/multipart_upload.rb

@@ -25,11 +25,13 @@ module ActiveCipherStorage
 
     SESSION_TTL = 24 * 3600
 
-    def initialize(s3_client:, bucket:, config: nil, store: nil)
-      @s3     = s3_client
-      @bucket = bucket
-      @config = config || ActiveCipherStorage.configuration
-      @store  = store || MemorySessionStore.new
+    def initialize(s3_client:, bucket:, config: nil, store: nil,
+                   chunk_size: Configuration::DEFAULT_CHUNK_SIZE)
+      @s3         = s3_client
+      @bucket     = bucket
+      @config     = config || ActiveCipherStorage.configuration
+      @store      = store || MemorySessionStore.new
+      @chunk_size = Integer(chunk_size)
       @config.validate!
       validate_multipart_chunk_size!
     end
@@ -46,7 +48,7 @@ module ActiveCipherStorage
         version:       Format::VERSION,
         algorithm:     Format::ALGO_AES256GCM,
         chunked:       true,
-        chunk_size:    @config.chunk_size,
+        chunk_size:    @chunk_size,
         provider_id:   @config.provider.provider_id,
         encrypted_dek: dek_bundle[:encrypted_key]
       ))
@@ -75,9 +77,9 @@ module ActiveCipherStorage
       session[:pending] = (session[:pending] +
         build_frame(plaintext, session[:encrypted_dek], session[:seq])).b
 
-      while session[:pending].bytesize >= @config.chunk_size
-        flush_part(session, session[:pending].byteslice(0, @config.chunk_size))
-        session[:pending] = (session[:pending].byteslice(@config.chunk_size..) || "".b).b
+      while session[:pending].bytesize >= @chunk_size
+        flush_part(session, session[:pending].byteslice(0, @chunk_size))
+        session[:pending] = (session[:pending].byteslice(@chunk_size..) || "".b).b
       end
 
       save_session(session_id, session)
@@ -169,7 +171,7 @@ module ActiveCipherStorage
 
     def validate_multipart_chunk_size!
       min_size = Configuration::MINIMUM_S3_MULTIPART_PART_SIZE
-      return if @config.chunk_size >= min_size
+      return if @chunk_size >= min_size
 
       raise ArgumentError,
             "chunk_size must be at least 5 MiB for S3 multipart uploads"

data/lib/active_cipher_storage/providers/aws_kms_provider.rb

@@ -5,14 +5,15 @@ module ActiveCipherStorage
 
       PROVIDER_ID = "aws_kms"
 
-      def initialize(key_id: nil, region: nil, encryption_context: {}, client: nil)
-        @key_id             = key_id || ENV.fetch("AWS_KMS_KEY_ID") {
-          raise Errors::ProviderError,
-                "AwsKmsProvider requires :key_id or AWS_KMS_KEY_ID env var"
-        }
-        @region             = region
-        @encryption_context = encryption_context || {}
-        @client_override    = client
+      def initialize(key_id:, region: nil, endpoint: nil, access_key_id: nil,
+                     secret_access_key: nil, encryption_context: {}, client: nil)
+        @key_id              = key_id
+        @region              = region
+        @endpoint            = endpoint
+        @access_key_id       = access_key_id
+        @secret_access_key   = secret_access_key
+        @encryption_context  = encryption_context || {}
+        @client_override     = client
       end
 
       def provider_id = PROVIDER_ID
@@ -48,42 +49,25 @@ module ActiveCipherStorage
         resp&.plaintext&.then { |k| zero_bytes!(k) }
       end
 
-      # Encrypts an existing plaintext DEK using KMS Encrypt.
-      # Prefer rotate_data_key (ReEncrypt) when both old and new providers are AWS KMS,
-      # because ReEncrypt keeps the plaintext DEK entirely within KMS.
-      def wrap_data_key(plaintext_dek)
-        resp = kms_client.encrypt(
-          key_id:             @key_id,
-          plaintext:          plaintext_dek,
-          encryption_context: @encryption_context
-        )
-        resp.ciphertext_blob.dup
-      rescue Aws::KMS::Errors::ServiceError => e
-        raise Errors::KeyManagementError, "KMS Encrypt failed: #{e.message}"
-      end
-
-      # Uses KMS ReEncrypt — the plaintext DEK never leaves KMS.
-      def rotate_data_key(encrypted_key, destination_key_id: nil)
-        resp = kms_client.re_encrypt(
-          ciphertext_blob:                encrypted_key,
-          source_encryption_context:      @encryption_context,
-          destination_key_id:             destination_key_id || @key_id,
-          destination_encryption_context: @encryption_context
-        )
-        resp.ciphertext_blob.dup
-      rescue Aws::KMS::Errors::ServiceError => e
-        raise Errors::KeyManagementError, "KMS ReEncrypt failed: #{e.message}"
-      end
-
       private
 
       def kms_client
         @kms_client ||= begin
           require "aws-sdk-kms"
-          @client_override || Aws::KMS::Client.new(**{ region: @region }.compact)
+          if @client_override
+            @client_override
+          else
+            opts = {
+              region:            @region,
+              endpoint:          @endpoint,
+              access_key_id:     @access_key_id,
+              secret_access_key: @secret_access_key
+            }.compact
+            Aws::KMS::Client.new(**opts)
+          end
+        rescue LoadError
+          raise Errors::ProviderError, "aws-sdk-kms is required: add it to your Gemfile"
         end
-      rescue LoadError
-        raise Errors::ProviderError, "aws-sdk-kms is required: add it to your Gemfile"
       end
     end
   end

data/lib/active_cipher_storage/providers/base.rb

@@ -11,28 +11,17 @@ module ActiveCipherStorage
         raise NotImplementedError, "#{self.class}#decrypt_data_key is not implemented"
       end
 
-      # Wraps an existing plaintext DEK under this provider's master key.
-      # Used during key rotation to re-protect a DEK without re-encrypting the file.
-      def wrap_data_key(plaintext_dek)
-        raise NotImplementedError, "#{self.class}#wrap_data_key is not implemented"
-      end
-
       # Short ASCII string embedded in every encrypted file header.
       def provider_id
         raise NotImplementedError, "#{self.class}#provider_id is not implemented"
       end
 
       # Stable identifier for the specific key material in use (e.g. CMK ARN,
-      # env var name). Stored in blob metadata for rotation queries.
-      # Returns nil for providers where key identity is not meaningful.
+      # env var name). Stored in blob metadata for visibility. Return nil if
+      # your provider has no stable key identifier.
       def key_id
         nil
       end
-
-      def rotate_data_key(encrypted_key)
-        raise Errors::UnsupportedOperation,
-              "#{self.class} does not support key rotation"
-      end
     end
   end
 end

data/lib/active_cipher_storage/providers/env_provider.rb

@@ -13,16 +13,14 @@ module ActiveCipherStorage
       WRAP_IV_SIZE    = 12
       WRAP_TAG_SIZE   = 16
 
-      def initialize(env_var: "ACTIVE_CIPHER_MASTER_KEY", old_env_var: nil)
-        @env_var     = env_var
-        @old_env_var = old_env_var
+      def initialize(encryption_key:)
+        @encryption_key = encryption_key
       end
 
       def provider_id = PROVIDER_ID
-      def key_id      = @env_var
 
       def generate_data_key
-        master = read_master_key(@env_var)
+        master = read_master_key
         dek    = SecureRandom.random_bytes(Cipher::KEY_SIZE)
         { plaintext_key: dek, encrypted_key: wrap_key(dek, master) }
       ensure
@@ -30,34 +28,12 @@ module ActiveCipherStorage
       end
 
       def decrypt_data_key(encrypted_key)
-        master = read_master_key(@env_var)
+        master = read_master_key
         unwrap_key(encrypted_key, master)
       ensure
         zero_bytes!(master)
       end
 
-      def wrap_data_key(plaintext_dek)
-        master = read_master_key(@env_var)
-        wrap_key(plaintext_dek, master)
-      ensure
-        zero_bytes!(master)
-      end
-
-      def rotate_data_key(encrypted_key, old_provider: nil)
-        source = old_provider || begin
-          raise Errors::UnsupportedOperation,
-                "Supply :old_provider to rotate via EnvProvider" unless @old_env_var
-          EnvProvider.new(env_var: @old_env_var)
-        end
-
-        plaintext_dek = source.decrypt_data_key(encrypted_key)
-        new_master    = read_master_key(@env_var)
-        wrap_key(plaintext_dek, new_master)
-      ensure
-        zero_bytes!(plaintext_dek)
-        zero_bytes!(new_master)
-      end
-
       private
 
       # Wrapped DEK: [12 IV][32 ciphertext][16 auth-tag] = 60 bytes
@@ -94,11 +70,12 @@ module ActiveCipherStorage
         c
       end
 
-      def read_master_key(var_name)
-        encoded = ENV.fetch(var_name) do
+      def read_master_key
+        encoded = @encryption_key
+        if encoded.nil? || encoded.empty?
           raise Errors::ProviderError,
-                "Environment variable #{var_name.inspect} is not set. " \
-                "Generate one with: ruby -rsecurerandom -e " \
+                "provider_options[:encryption_key] must be set. " \
+                "Generate one with: ruby -rsecurerandom -rbase64 -e " \
                 "'puts Base64.strict_encode64(SecureRandom.bytes(32))'"
         end
 
@@ -106,12 +83,12 @@ module ActiveCipherStorage
           Base64.strict_decode64(encoded)
         rescue ArgumentError
           raise Errors::ProviderError,
-                "#{var_name} must be Base64-encoded (strict, no line breaks)"
+                "provider_options[:encryption_key] must be Base64-encoded (strict, no line breaks)"
         end
 
         unless key.bytesize == MASTER_KEY_SIZE
           raise Errors::ProviderError,
-                "#{var_name} must decode to exactly #{MASTER_KEY_SIZE} bytes " \
+                "provider_options[:encryption_key] must decode to exactly #{MASTER_KEY_SIZE} bytes " \
                 "(got #{key.bytesize})"
         end
 

data/lib/active_cipher_storage/stream_cipher.rb

@@ -1,15 +1,18 @@
 require "openssl"
 require "securerandom"
+require "stringio"
 
 module ActiveCipherStorage
   class StreamCipher
     include KeyUtils
 
-    def initialize(config = ActiveCipherStorage.configuration)
+    def initialize(config: ActiveCipherStorage.configuration,
+                   chunk_size: Configuration::DEFAULT_CHUNK_SIZE)
       config.validate!
       @config     = config
       @provider   = config.provider
-      @chunk_size = config.chunk_size
+      @chunk_size = Integer(chunk_size)
+      raise ArgumentError, "chunk_size must be positive" unless @chunk_size.positive?
     end
 
     def encrypt(input_io, output_io)

data/lib/active_cipher_storage/version.rb

@@ -1,3 +1,3 @@
 module ActiveCipherStorage
-  VERSION = "1.0.3"
+  VERSION = "2.0.0"
 end

data/lib/active_cipher_storage.rb

@@ -15,9 +15,7 @@ require_relative "active_cipher_storage/providers/aws_kms_provider"
 require_relative "active_cipher_storage/cipher"
 require_relative "active_cipher_storage/stream_cipher"
 require_relative "active_cipher_storage/adapters/s3_adapter"
-require_relative "active_cipher_storage/adapters/active_storage_service"
 require_relative "active_cipher_storage/blob_metadata"
-require_relative "active_cipher_storage/key_rotation"
 require_relative "active_cipher_storage/multipart_upload"
 
 # Rails Engine wires the service into ActiveStorage's service registry.

data/lib/active_storage/service/active_cipher_storage_service.rb

@@ -1,10 +1,187 @@
+# frozen_string_literal: true
+
+require "active_storage"
 require "active_storage/service"
-require "active_cipher_storage/adapters/active_storage_service"
+require "active_cipher_storage"
+require "active_cipher_storage/cipher"
+require "active_cipher_storage/stream_cipher"
+require "active_cipher_storage/errors"
+require "active_cipher_storage/format"
+require "active_cipher_storage/blob_metadata"
 
 module ActiveStorage
-  class Service
-    unless const_defined?(:ActiveCipherStorageService, false)
-      ActiveCipherStorageService = ::ActiveCipherStorage::Adapters::ActiveStorageService
+  # Encrypting wrapper around another Active Storage service (e.g. S3). Configure
+  # in +config/storage.yml+ with +service: ActiveCipherStorage+ and
+  # +wrapped_service:+ pointing at a named service.
+  #
+  # See the gem README for behavior and caveats.
+  class Service::ActiveCipherStorageService < Service
+    attr_reader :inner
+
+    def self.build(configurator:, name:, wrapped_service:, service: nil, **service_config)
+      new(wrapped_service: configurator.build(wrapped_service), **service_config).tap do |instance|
+        instance.name = name.to_s
+      end
+    end
+
+    def initialize(wrapped_service:, public: nil,
+                   chunk_size: ActiveCipherStorage::Configuration::DEFAULT_CHUNK_SIZE, **)
+      @inner = wrapped_service
+      @chunk_size    = Integer(chunk_size)
+      @cipher        = ActiveCipherStorage::Cipher.new
+      @stream_cipher = ActiveCipherStorage::StreamCipher.new(chunk_size: @chunk_size)
+      @public =
+        if public.nil?
+          wrapped_service.respond_to?(:public?) ? wrapped_service.public? : false
+        else
+          public
+        end
+    end
+
+    def upload(key, io, checksum: nil, **options)
+      instrument :upload, key: key, checksum: checksum do
+        upload_without_instrument(key, io, checksum: checksum, **options)
+      end
+    end
+
+    def download(key, &block)
+      if block_given?
+        instrument :streaming_download, key: key do
+          plain = download_without_block(key)
+          yield plain
+        end
+      else
+        instrument :download, key: key do
+          download_without_block(key)
+        end
+      end
+    end
+
+    def download_chunk(key, range)
+      instrument :download_chunk, key: key, range: range do
+        download_without_block(key).b[range]
+      end
+    end
+
+    # Returns stored ciphertext bytes (for custom tooling, backups, or migrations).
+    def download_raw(key)
+      collect_download(key)
+    end
+
+    # Writes raw ciphertext bytes without encrypting (for advanced use only).
+    def upload_raw(key, io)
+      instrument :upload, key: key, checksum: nil do
+        inner.upload(key, io, content_type: "application/octet-stream")
+      end
+    end
+
+    def delete(key)
+      instrument :delete, key: key do
+        inner.delete(key)
+      end
+    end
+
+    def delete_prefixed(prefix)
+      instrument :delete_prefixed, prefix: prefix do
+        inner.delete_prefixed(prefix)
+      end
+    end
+
+    def exist?(key)
+      instrument :exist, key: key do |payload|
+        answer = inner.exist?(key)
+        payload[:exist] = answer
+        answer
+      end
+    end
+
+    def update_metadata(key, **metadata)
+      inner.update_metadata(key, **metadata)
+    end
+
+    def compose(source_keys, destination_key, **options)
+      inner.compose(source_keys, destination_key, **options)
+    end
+
+    def path_for(key)
+      unless inner.respond_to?(:path_for)
+        raise NotImplementedError,
+              "#{inner.class.name} does not implement path_for — use a disk-backed " \
+              "inner service if you need local paths"
+      end
+
+      inner.path_for(key)
+    end
+
+    def url_for_direct_upload(*)
+      raise ActiveCipherStorage::Errors::UnsupportedOperation,
+            "Direct uploads bypass encryption — use server-side upload instead"
+    end
+
+    def headers_for_direct_upload(*) = {}
+
+    private
+
+    def private_url(key, **options)
+      inner.send(:private_url, key, **options)
+    end
+
+    def public_url(key, **options)
+      inner.send(:public_url, key, **options)
+    end
+
+    def upload_without_instrument(key, io, checksum: nil, **options)
+      unless ActiveCipherStorage.configuration.encrypt_uploads
+        inner.upload(key, io, checksum: checksum, **options)
+        ActiveCipherStorage::BlobMetadata.write_plaintext(key)
+        return
+      end
+
+      inner.upload(key, encrypt_io(io), **options,
+        checksum:     nil,
+        content_type: "application/octet-stream")
+
+      ActiveCipherStorage::BlobMetadata.write(key, ActiveCipherStorage.configuration.provider)
+    end
+
+    def download_without_block(key)
+      raw = collect_download(key)
+
+      return raw unless cipher_payload?(raw)
+
+      decrypt_raw(raw)
+    end
+
+    def encrypt_io(io)
+      if io.respond_to?(:size) && io.size && io.size > @chunk_size
+        @stream_cipher.encrypt_to_io(io)
+      else
+        StringIO.new(@cipher.encrypt(io))
+      end
+    end
+
+    def collect_download(key)
+      buffer = StringIO.new("".b)
+      result = inner.download(key) { |chunk| buffer.write(chunk) }
+      buffer.write(result.b) if buffer.pos.zero? && result.is_a?(String)
+      buffer.string
+    end
+
+    def decrypt_raw(raw)
+      io     = StringIO.new(raw.b)
+      header = ActiveCipherStorage::Format.read_header(io)
+      io.rewind
+      header.chunked ? @stream_cipher.decrypt_to_io(io).read : @cipher.decrypt(io)
+    end
+
+    def cipher_payload?(data)
+      data.b.start_with?(ActiveCipherStorage::Format::MAGIC)
+    end
+
+    # Base implementation uses +Array#third+ (ActiveSupport); loading order may not
+    # include array extensions, so we keep a stable notification label.
+    def service_name
+      "ActiveCipherStorage"
     end
   end
 end