active_cipher_storage 1.0.2 → 2.0.0

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_cipher_storage
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Jaspreet Singh
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-25 00:00:00.000000000 Z
+date: 2026-06-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -194,7 +194,6 @@ files:
 - SECURITY.md
 - active_cipher_storage.gemspec
 - lib/active_cipher_storage.rb
-- lib/active_cipher_storage/adapters/active_storage_service.rb
 - lib/active_cipher_storage/adapters/s3_adapter.rb
 - lib/active_cipher_storage/blob_metadata.rb
 - lib/active_cipher_storage/cipher.rb
@@ -202,7 +201,6 @@ files:
 - lib/active_cipher_storage/engine.rb
 - lib/active_cipher_storage/errors.rb
 - lib/active_cipher_storage/format.rb
-- lib/active_cipher_storage/key_rotation.rb
 - lib/active_cipher_storage/key_utils.rb
 - lib/active_cipher_storage/multipart_upload.rb
 - lib/active_cipher_storage/providers/aws_kms_provider.rb

data/lib/active_cipher_storage/adapters/active_storage_service.rb

@@ -1,140 +0,0 @@
-module ActiveCipherStorage
-  module Adapters
-    # Active Storage service that transparently encrypts uploads and decrypts
-    # downloads. Configure in config/storage.yml:
-    #
-    #   encrypted_s3:
-    #     service: ActiveCipherStorage
-    #     wrapped_service: s3
-    #
-    # Backward compatibility
-    # ───────────────────────
-    # Blobs uploaded before encryption was enabled are detected via the "ACS\x01"
-    # magic header.  If the magic is absent the raw bytes are returned as-is,
-    # so the service is safe to enable on a bucket with existing plaintext objects.
-    #
-    # Range requests (download_chunk) must decrypt the full blob first because
-    # GCM authentication requires the complete ciphertext before any plaintext
-    # can be safely released.
-    class ActiveStorageService
-      BlobRef = Struct.new(:key)
-
-      attr_reader :inner
-
-      def self.build(configurator:, wrapped_service:, **kwargs)
-        new(wrapped_service: configurator.build(wrapped_service), **kwargs)
-      end
-
-      def initialize(wrapped_service:, **_kwargs)
-        @inner         = wrapped_service
-        @cipher        = Cipher.new
-        @stream_cipher = StreamCipher.new
-      end
-
-      def upload(key, io, checksum: nil, content_type: nil, filename: nil,
-                 disposition: nil, custom_metadata: {})
-        unless ActiveCipherStorage.configuration.encrypt_uploads
-          @inner.upload(key, io,
-            checksum:        checksum,
-            content_type:    content_type,
-            filename:        filename,
-            disposition:     disposition,
-            custom_metadata: custom_metadata)
-          BlobMetadata.write_plaintext(key)
-          return
-        end
-
-        @inner.upload(key, encrypt_io(io),
-          checksum:        nil,  # checksum is over plaintext; skip for ciphertext
-          content_type:    "application/octet-stream",
-          filename:        filename,
-          disposition:     disposition,
-          custom_metadata: custom_metadata)
-
-        BlobMetadata.write(key, ActiveCipherStorage.configuration.provider)
-      end
-
-      def download(key, &block)
-        raw = collect_download(key)
-
-        # Legacy plaintext blob — no magic header present.
-        return (block ? yield(raw) : raw) unless cipher_payload?(raw)
-
-        plaintext = decrypt_raw(raw)
-        block ? yield(plaintext) : plaintext
-      end
-
-      def download_chunk(key, range)
-        download(key).b[range]
-      end
-
-      # Used by KeyRotation to fetch raw ciphertext without decrypting.
-      def download_raw(key)
-        collect_download(key)
-      end
-
-      # Used by KeyRotation to overwrite a blob's bytes without re-encrypting.
-      def upload_raw(key, io)
-        @inner.upload(key, io, content_type: "application/octet-stream")
-      end
-
-      # Re-wraps the DEK in a single blob's header under new_provider without
-      # decrypting or re-encrypting the file body.
-      def rekey(key, old_provider:, new_provider:)
-        KeyRotation.rotate_blob(
-          BlobRef.new(key),
-          old_provider: old_provider,
-          new_provider: new_provider,
-          service:      self
-        )
-      end
-
-      def delete(key)          = @inner.delete(key)
-      def delete_prefixed(pfx) = @inner.delete_prefixed(pfx)
-      def exist?(key)          = @inner.exist?(key)
-
-      def url(key, expires_in:, filename:, content_type:, disposition:, **)
-        @inner.url(key, expires_in: expires_in, filename: filename,
-                        content_type: content_type, disposition: disposition)
-      end
-
-      def url_for_direct_upload(*)
-        raise Errors::UnsupportedOperation,
-              "Direct uploads bypass encryption — use server-side upload instead"
-      end
-
-      def headers_for_direct_upload(*) = {}
-
-      private
-
-      def encrypt_io(io)
-        config = ActiveCipherStorage.configuration
-        if io.respond_to?(:size) && io.size && io.size > config.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) }
-        # Some services return data instead of yielding; handle both.
-        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 = 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?(Format::MAGIC)
-      end
-    end
-  end
-end

data/lib/active_cipher_storage/key_rotation.rb

@@ -1,121 +0,0 @@
-module ActiveCipherStorage
-  # Re-wraps the per-file Data Encryption Key (DEK) stored in encrypted file
-  # headers without decrypting or re-encrypting the file body.
-  #
-  # Why this matters
-  # ─────────────────
-  # Every encrypted file stores its DEK in the header, wrapped by the KMS
-  # master key.  When you rotate the master key, only the wrapped DEK in the
-  # header needs to change — the AES-256-GCM ciphertext body stays untouched.
-  # This makes rotation O(n blobs) in API calls but O(header size) in data
-  # transferred per file, not O(file size).
-  #
-  # AWS KMS optimisation
-  # ─────────────────────
-  # When both providers are AwsKmsProvider, KeyRotation uses KMS ReEncrypt.
-  # The plaintext DEK never leaves KMS — it is re-wrapped entirely server-side.
-  # Cross-provider rotations (e.g. EnvProvider → AwsKmsProvider) must briefly
-  # hold the plaintext DEK in process memory, zeroed immediately after use.
-  #
-  # Usage
-  # ─────
-  #   old_kms = ActiveCipherStorage::Providers::AwsKmsProvider.new(key_id: old_arn)
-  #   new_kms = ActiveCipherStorage::Providers::AwsKmsProvider.new(key_id: new_arn)
-  #
-  #   ActiveCipherStorage::KeyRotation.rotate(
-  #     old_provider: old_kms,
-  #     new_provider: new_kms,
-  #     service:      MyEncryptedStorageService.new
-  #   ) do |blob, result|
-  #     Rails.logger.info "rotated #{blob.key}: #{result[:status]}"
-  #   end
-  #
-  module KeyRotation
-    extend self
-
-    # Rotates every blob associated with old_provider.
-    # Yields (blob, result_hash) for each blob processed so callers can log
-    # progress and handle per-blob failures without aborting the batch.
-    #
-    # Options:
-    #   dry_run: true  — parse headers and validate, but skip the upload step.
-    def rotate(old_provider:, new_provider:, service:, dry_run: false)
-      BlobMetadata.blobs_for(old_provider) do |blob|
-        result = rotate_blob(blob, old_provider: old_provider,
-                                   new_provider: new_provider,
-                                   service:      service,
-                                   dry_run:      dry_run)
-        yield blob, result if block_given?
-      end
-    end
-
-    # Rotates a single blob. Returns { status: :rotated | :skipped | :failed, ... }.
-    def rotate_blob(blob, old_provider:, new_provider:, service:, dry_run: false)
-      encrypted = service.download_raw(blob.key)
-
-      unless Format::MAGIC == encrypted.b[0, 4]
-        return { status: :skipped, reason: "not an encrypted blob" }
-      end
-
-      new_payload = rewrite_dek(encrypted, old_provider: old_provider, new_provider: new_provider)
-
-      unless dry_run
-        service.upload_raw(blob.key, StringIO.new(new_payload))
-        BlobMetadata.update_after_rotation(blob.key, new_provider)
-      end
-
-      { status: dry_run ? :validated : :rotated }
-    rescue => e
-      { status: :failed, error: e.message }
-    end
-
-    # Rewrites the encrypted DEK inside an encrypted payload's header.
-    # The IV, ciphertext, and auth tag(s) are copied byte-for-byte unchanged.
-    def rewrite_dek(encrypted_data, old_provider:, new_provider:)
-      io     = StringIO.new(encrypted_data.b)
-      header = Format.read_header(io)
-      body_offset = io.pos
-
-      new_encrypted_dek = re_wrap_dek(
-        header.encrypted_dek,
-        old_provider: old_provider,
-        new_provider: new_provider
-      )
-
-      out = StringIO.new("".b)
-      Format.write_header(out, Format::Header.new(
-        version:       header.version,
-        algorithm:     header.algorithm,
-        chunked:       header.chunked,
-        chunk_size:    header.chunk_size,
-        provider_id:   new_provider.provider_id,
-        encrypted_dek: new_encrypted_dek
-      ))
-      out.write(encrypted_data.b[body_offset..])
-      out.string
-    end
-
-    private
-
-    # Chooses the optimal re-wrap strategy:
-    # - Both AWS KMS → ReEncrypt (plaintext DEK stays in KMS)
-    # - Otherwise    → decrypt with old, wrap with new (plaintext DEK in memory)
-    def re_wrap_dek(encrypted_dek, old_provider:, new_provider:)
-      if old_provider.is_a?(Providers::AwsKmsProvider) &&
-         new_provider.is_a?(Providers::AwsKmsProvider)
-        return old_provider.rotate_data_key(encrypted_dek,
-                                            destination_key_id: new_provider.key_id)
-      end
-
-      plaintext_dek = old_provider.decrypt_data_key(encrypted_dek)
-      new_provider.wrap_data_key(plaintext_dek)
-    ensure
-      zero_bytes!(plaintext_dek) if defined?(plaintext_dek)
-    end
-
-    def zero_bytes!(str)
-      return unless str.is_a?(String)
-      str.bytesize.times { |i| str.setbyte(i, 0) }
-    end
-  end
-end