active_cipher_storage 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 561cba3b474dd5c35b19324c325216fe452e2670e1d1bea42f719f368331672a
-  data.tar.gz: 9e776a018104013b07e2da60e18eeb7ead76d2fa37d0bce929f0fe3b0cfab11f
+  metadata.gz: fabc72461d7687d4fe0f17c6d22979b637012b3d160b0d5b21dbd775facd6498
+  data.tar.gz: 0a16cf1345eaf8a7962fe086113fc04e9c76350445769a8c809213c9535cfc44
 SHA512:
-  metadata.gz: a9da8b50775c261cd00047bc1af09f57aad8523e672e4c70e544ca49ce3166294778c53fdbd55a9c89fb2ff16aeb6d8b3cdb8bce5403261701c685f8895be74e
-  data.tar.gz: 23f93a25b27f7a6bad2a233ffebe0134b0a513426931cbaf2f70beec923b8152d2beff878017403da5305c1119cf3707281f22699d03d459a0c476912e197366
+  metadata.gz: 7bc1e4f3f4721a294bd28043a9672843b5a2bd26b932b2cd7390f16cbf79bec98b3b62bfd9169e6f9267f429d9fccf896309d4dae7e389bc3a6c8284c44988dc
+  data.tar.gz: 22e3bc0328636ee8078cd679ace9f49c5ab83617ba814191f2c7d80886e19429061d7bc193f751af2202175d1af444b3b3a5d8c45fc6d9ab8ae77eeb510529f6

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-04-25
+
+### Changed
+
+- Back gem configuration with Rails-style ActiveSupport options while preserving the existing public configuration API.
+- Document the Active Storage upload encryption flag and plaintext read compatibility behavior.
+
+### Fixed
+
+- Reject reordered streaming frames and trailing bytes after the final encrypted frame.
+- Validate S3 multipart chunk sizes before upload so invalid part sizes fail early.
+- Mark plaintext Active Storage uploads explicitly when encryption is disabled.
+
 ## [1.0.0] - 2026-04-25
 
 ### Added
@@ -20,5 +33,6 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 - Header-only key rotation for re-wrapping encrypted DEKs.
 - Unit and integration coverage for crypto, providers, Active Storage, S3, multipart upload, streaming, metadata, and key rotation.
 
-[Unreleased]: https://github.com/codebyjass/active-cipher-storage/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/codebyjass/active-cipher-storage/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/codebyjass/active-cipher-storage/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/codebyjass/active-cipher-storage/releases/tag/v1.0.0

data/README.md

@@ -10,8 +10,6 @@ ActiveCipherStorage supports three upload paths:
 - **Direct S3 clients** — service objects and non-Rails apps can call `put_encrypted`, `get_decrypted`, and `stream_decrypted`.
 - **Frontend chunk uploads** — the frontend sends plaintext chunks to your backend; the backend encrypts those chunks and uploads encrypted S3 multipart parts.
 
----
-
 ## Contents
 
 1. [How it works](#how-it-works)
@@ -36,8 +34,6 @@ ActiveCipherStorage supports three upload paths:
 17. [License](#license)
 18. [Ruby and Rails compatibility](#ruby-and-rails-compatibility)
 
----
-
 ## How it works
 
 Every encrypted file is self-contained.  No external metadata store is needed.
@@ -72,8 +68,6 @@ Decryption reverses the flow: the KMS provider unwraps the DEK from the header,
 
 Every encrypted payload uses the same self-describing format, whether it came from Active Storage, the direct S3 adapter, or the backend chunk upload API.
 
----
-
 ## Installation
 
 ```ruby
@@ -91,8 +85,6 @@ gem "aws-sdk-s3"
 bundle install
 ```
 
----
-
 ## Rails / Active Storage setup
 
 ### 1. Configure a KMS provider
@@ -113,6 +105,7 @@ ActiveCipherStorage.configure do |config|
 
   # Tuning (optional)
   config.chunk_size = 5 * 1024 * 1024   # 5 MiB per chunk (default)
+  config.encrypt_uploads = true         # set false to store new Active Storage uploads as plaintext
 end
 ```
 
@@ -163,9 +156,9 @@ url = rails_blob_url(user.document)
 
 Active Storage transparently encrypts on upload and decrypts on download. Existing plaintext objects are still readable: if a blob does not start with the `ACS\x01` magic header, the service returns it unchanged.
 
-Direct Active Storage browser uploads are intentionally disabled because they bypass the backend encryption layer.
+`config.encrypt_uploads` controls new Active Storage writes only. When disabled, new uploads are stored as plaintext and marked with `"encrypted": false` metadata. Reads continue to auto-detect by payload header, so existing encrypted blobs still decrypt correctly and existing plaintext blobs still download unchanged.
 
----
+Direct Active Storage browser uploads are intentionally disabled because they bypass the backend encryption layer.
 
 ## Standalone S3 usage
 
@@ -202,8 +195,6 @@ s3 = ActiveCipherStorage::Adapters::S3Adapter.new(
 )
 ```
 
----
-
 ## Chunked multipart upload
 
 For large files where the frontend sends data in separate HTTP requests, use `EncryptedMultipartUpload`. Each frontend chunk is encrypted by the backend as an authenticated ACS frame and buffered until the S3 multipart minimum part size is met, then flushed as an encrypted S3 multipart part.
@@ -280,8 +271,6 @@ uploader = ActiveCipherStorage::EncryptedMultipartUpload.new(
 
 **Security:** The plaintext DEK is never stored in the session. Only the KMS-wrapped encrypted DEK is persisted; it is decrypted fresh for each chunk and zeroed immediately after use.
 
----
-
 ## Streaming download
 
 `stream_decrypted` pipes S3 bytes through the decryptor and yields plaintext chunks on the fly. Memory usage is bounded by one ACS chunk (default 5 MiB) regardless of file size.
@@ -317,8 +306,6 @@ end
 
 Use `stream_decrypted` for chunked ACS objects. If the object is non-chunked, call `get_decrypted`; streaming a non-chunked or non-ACS/plaintext object raises `InvalidFormat` with a clear error.
 
----
-
 ## Manual encrypt / decrypt
 
 Use `Cipher` (in-memory) or `StreamCipher` (chunked, constant memory):
@@ -354,8 +341,6 @@ File.open("large.bin.enc", "rb") do |input|
 end
 ```
 
----
-
 ## Blob metadata
 
 When using the Rails Active Storage adapter, encryption metadata is automatically written to `ActiveStorage::Blob#metadata` after each upload:
@@ -404,8 +389,6 @@ end
 
 Only the encrypted DEK in the file header is rewritten — the IV, ciphertext, and auth tags are copied byte-for-byte. This makes rotation O(header size) in data transferred per file, not O(file size). For AWS KMS → AWS KMS rotations, the plaintext DEK never leaves KMS (uses `ReEncrypt` API).
 
----
-
 ## KMS providers
 
 ### Environment-variable provider
@@ -477,8 +460,6 @@ The `provider_id` is embedded in every encrypted file. Routing at decrypt time i
 
 Implement `rotate_data_key(encrypted_key)` as well if the provider can re-wrap encrypted DEKs without exposing plaintext key material.
 
----
-
 ## Key rotation
 
 ### AWS KMS automatic rotation
@@ -516,8 +497,6 @@ new_provider = ActiveCipherStorage::Providers::EnvProvider.new(env_var: "NEW_KEY
 new_dek = new_provider.rotate_data_key(encrypted_dek, old_provider: old_provider)
 ```
 
----
-
 ## Configuration reference
 
 ```ruby
@@ -532,13 +511,15 @@ ActiveCipherStorage.configure do |config|
   # Must be >= 5 MiB for S3 multipart uploads (except the last part).
   config.chunk_size = 5 * 1024 * 1024
 
+  # Controls new Active Storage uploads only. Downloads always auto-detect
+  # encrypted vs. plaintext payloads by the ACS header.
+  config.encrypt_uploads = true
+
   # Logger instance.  Defaults to STDOUT at WARN level.
   config.logger     = Rails.logger
 end
 ```
 
----
-
 ## Encryption format
 
 Every encrypted payload is a self-describing binary blob:
@@ -575,8 +556,6 @@ CHUNKED PAYLOAD (repeated until final frame)
 - Auth tag failure raises `DecryptionError` immediately — no partial plaintext is returned.
 - Unsupported format versions, algorithms, and header flags raise `InvalidFormat` instead of being parsed permissively.
 
----
-
 ## Security notes
 
 | Risk | Mitigation |
@@ -587,8 +566,6 @@ CHUNKED PAYLOAD (repeated until final frame)
 | Partial-read oracle | `DecryptionError` is always raised from `cipher.final`; no partial plaintext is ever returned. |
 | Accidental plaintext upload | All upload paths go through the cipher layer; there is no bypass. |
 
----
-
 ## Testing
 
 ```bash
@@ -604,8 +581,6 @@ bundle exec rake spec:integration
 
 Integration tests use in-memory fakes for both Active Storage and S3 — no real AWS credentials or S3 bucket required.
 
----
-
 ## Contributing
 
 Contributions are welcome. Please read `CONTRIBUTING.md` before opening a pull request.
@@ -618,22 +593,16 @@ bundle exec rspec
 
 Do not commit secrets, credentials, `.env` files, local coverage output, or generated gems.
 
----
-
 ## Security reports
 
 Please do not open public GitHub issues for vulnerabilities. Follow `SECURITY.md` and use GitHub private vulnerability reporting if it is available for the repository:
 
 https://github.com/codebyjass/active-cipher-storage/security/advisories/new
 
----
-
 ## License
 
 The gem is available as open source under the terms of the MIT License. See `LICENSE`.
 
----
-
 ## Ruby and Rails compatibility
 
 | | Version |

data/active_cipher_storage.gemspec

@@ -38,6 +38,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Core — no runtime dep on Rails or AWS
+  spec.add_dependency "activesupport",  ">= 7.0", "< 9.0"
   spec.add_dependency "concurrent-ruby", "~> 1.2"
 
   # Optional integrations — loaded only when the relevant adapter is used

data/lib/active_cipher_storage/adapters/active_storage_service.rb

@@ -33,6 +33,17 @@ module ActiveCipherStorage
 
       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",

data/lib/active_cipher_storage/adapters/s3_adapter.rb

@@ -65,7 +65,7 @@ module ActiveCipherStorage
       end
 
       def multipart_put(key, io, **options)
-        require "aws-sdk-s3"
+        validate_multipart_chunk_size!
         upload_id = s3.create_multipart_upload(bucket: @bucket, key: key,
                                                **upload_options(options)).upload_id
         parts = stream_multipart_parts(key, io, upload_id)
@@ -147,6 +147,14 @@ module ActiveCipherStorage
         c
       end
 
+      def validate_multipart_chunk_size!
+        min_size = Configuration::MINIMUM_S3_MULTIPART_PART_SIZE
+        return if @config.chunk_size >= min_size
+
+        raise ArgumentError,
+              "chunk_size must be at least 5 MiB for S3 multipart uploads"
+      end
+
       def s3
         @s3 ||= begin
           require "aws-sdk-s3"
@@ -180,10 +188,16 @@ module ActiveCipherStorage
           @dek         = nil
           @header_done = false
           @done        = false
+          @expected_seq = 1
         end
 
         def push(bytes, &block)
-          return if @done
+          if @done
+            raise Errors::InvalidFormat, "Trailing bytes after final frame" unless bytes.empty?
+
+            return
+          end
+
           @buffer += bytes.b
           try_parse_header unless @header_done
           drain_frames(&block) if @header_done
@@ -191,6 +205,7 @@ module ActiveCipherStorage
 
         def finish!
           raise Errors::InvalidFormat, "Stream ended before final frame" unless @done
+          raise Errors::InvalidFormat, "Trailing bytes after final frame" unless @buffer.empty?
         ensure
           zero_bytes!(@dek)
         end
@@ -227,12 +242,21 @@ module ActiveCipherStorage
             frame   = Format.read_chunk(StringIO.new(@buffer.byteslice(0, frame_size)))
             @buffer = (@buffer.byteslice(frame_size..) || "".b).b
 
+            validate_frame_sequence!(frame[:seq])
             plaintext = decrypt_frame(frame)
             block.call(plaintext) unless plaintext.empty?
             @done = (frame[:seq] == Format::FINAL_SEQ)
+            @expected_seq += 1 unless @done
           end
         end
 
+        def validate_frame_sequence!(seq)
+          return if [Format::FINAL_SEQ, @expected_seq].include?(seq)
+
+          raise Errors::InvalidFormat,
+                "Unexpected chunk sequence: expected #{@expected_seq}, got #{seq}"
+        end
+
         def decrypt_frame(frame)
           c = OpenSSL::Cipher.new(Cipher::OPENSSL_ALGO)
           c.decrypt

data/lib/active_cipher_storage/blob_metadata.rb

@@ -31,6 +31,26 @@ module ActiveCipherStorage
       )
     end
 
+    def self.write_plaintext(storage_key)
+      return unless active_storage_available?
+
+      blob = ActiveStorage::Blob.find_by(key: storage_key)
+      return unless blob
+
+      blob.update_columns(
+        metadata: blob.metadata.merge(
+          "encrypted" => false,
+          "cipher_version" => nil,
+          "provider_id" => nil,
+          "kms_key_id" => nil
+        ).compact
+      )
+    rescue => e
+      ActiveCipherStorage.configuration.logger.warn(
+        "[ActiveCipherStorage] Could not write plaintext blob metadata for #{storage_key}: #{e.message}"
+      )
+    end
+
     def self.update_after_rotation(storage_key, new_provider)
       return unless active_storage_available?
 

data/lib/active_cipher_storage/configuration.rb

@@ -1,4 +1,5 @@
 require "logger"
+require "active_support/ordered_options"
 
 module ActiveCipherStorage
   class Configuration
@@ -7,40 +8,81 @@ module ActiveCipherStorage
 
     # 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 = 5 * 1024 * 1024
     DEFAULT_CHUNK_SIZE = 5 * 1024 * 1024
 
-    attr_reader   :provider
-    attr_accessor :algorithm, :chunk_size, :logger
+    attr_reader :config
 
     def initialize
-      @algorithm  = "aes-256-gcm"
-      @chunk_size = DEFAULT_CHUNK_SIZE
-      @provider   = nil
-      @logger     = Logger.new($stdout, level: Logger::WARN)
+      @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)
+    end
+
+    def algorithm
+      config.algorithm
+    end
+
+    def algorithm=(value)
+      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
+
+    def encrypt_uploads=(value)
+      config.encrypt_uploads = value
+    end
+
+    def logger
+      config.logger
+    end
+
+    def logger=(value)
+      config.logger = value
+    end
+
+    def provider
+      config.provider
     end
 
     # Accept a provider instance or a symbol shorthand (:env, :aws_kms).
     def provider=(value)
-      @provider = case value
-                  when Symbol then resolve_provider(value)
-                  when Providers::Base then value
-                  else
-                    raise ArgumentError,
-                          "provider must be a Providers::Base instance or " \
-                          "one of :env, :aws_kms — got #{value.inspect}"
-                  end
+      config.provider = case value
+                        when Symbol then resolve_provider(value)
+                        when Providers::Base then value
+                        else
+                          raise ArgumentError,
+                                "provider must be a Providers::Base instance or " \
+                                "one of :env, :aws_kms — got #{value.inspect}"
+                        end
     end
 
     def validate!
       raise ProviderError, "No KMS provider configured. " \
-            "Set ActiveCipherStorage.configuration.provider." unless @provider
+            "Set ActiveCipherStorage.configuration.provider." unless provider
 
-      unless ALGORITHMS.include?(@algorithm)
-        raise ArgumentError, "Unsupported algorithm: #{@algorithm.inspect}. " \
+      unless ALGORITHMS.include?(algorithm)
+        raise ArgumentError, "Unsupported algorithm: #{algorithm.inspect}. " \
               "Supported: #{ALGORITHMS.join(', ')}"
       end
 
-      raise ArgumentError, "chunk_size must be positive" unless @chunk_size.positive?
+      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"
     end
 
     private

data/lib/active_cipher_storage/multipart_upload.rb

@@ -31,6 +31,7 @@ module ActiveCipherStorage
       @config = config || ActiveCipherStorage.configuration
       @store  = store || MemorySessionStore.new
       @config.validate!
+      validate_multipart_chunk_size!
     end
 
     # Starts a new multipart upload. Returns an opaque session_id.
@@ -166,6 +167,14 @@ module ActiveCipherStorage
       @store.write(id, data, expires_in: SESSION_TTL)
     end
 
+    def validate_multipart_chunk_size!
+      min_size = Configuration::MINIMUM_S3_MULTIPART_PART_SIZE
+      return if @config.chunk_size >= min_size
+
+      raise ArgumentError,
+            "chunk_size must be at least 5 MiB for S3 multipart uploads"
+    end
+
     # Thread-safe in-memory session store backed by Concurrent::Map.
     # Replace with a Rails.cache wrapper for multi-process deployments.
     class MemorySessionStore

data/lib/active_cipher_storage/stream_cipher.rb

@@ -47,13 +47,19 @@ module ActiveCipherStorage
       raise Errors::InvalidFormat, "Payload is not chunked; use Cipher#decrypt" unless header.chunked
 
       key = @provider.decrypt_data_key(header.encrypted_dek)
+      expected_seq = 1
       loop do
         frame = Format.read_chunk(input_io)
         raise Errors::InvalidFormat, "Unexpected end of stream — missing final frame" if frame.nil?
 
+        validate_frame_sequence!(frame[:seq], expected_seq)
         output_io.write(decrypt_chunk(frame[:ciphertext], key, frame[:iv], frame[:auth_tag], frame[:seq]))
         break if frame[:seq] == Format::FINAL_SEQ
+
+        expected_seq += 1
       end
+
+      ensure_no_trailing_bytes!(input_io)
     ensure
       zero_bytes!(key)
     end
@@ -89,6 +95,20 @@ module ActiveCipherStorage
             "Authentication failed on chunk seq=#{seq} — data may be tampered"
     end
 
+    def validate_frame_sequence!(seq, expected_seq)
+      return if seq == Format::FINAL_SEQ || seq == expected_seq
+
+      raise Errors::InvalidFormat,
+            "Unexpected chunk sequence: expected #{expected_seq}, got #{seq}"
+    end
+
+    def ensure_no_trailing_bytes!(input_io)
+      trailing = input_io.read(1)
+      return if trailing.nil? || trailing.empty?
+
+      raise Errors::InvalidFormat, "Trailing bytes after final frame"
+    end
+
     def build_cipher(mode, key, iv, auth_tag, seq)
       c = OpenSSL::Cipher.new(Cipher::OPENSSL_ALGO)
       mode == :encrypt ? c.encrypt : c.decrypt

data/lib/active_cipher_storage/version.rb

@@ -1,3 +1,3 @@
 module ActiveCipherStorage
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_cipher_storage
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Jaspreet Singh
@@ -10,6 +10,26 @@ bindir: bin
 cert_chain: []
 date: 2026-04-25 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
   requirement: !ruby/object:Gem::Requirement