active_cipher_storage 1.0.3 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9e4e6edf34d0d997fcc28765c599526e07eba891aabf24dfa6b739663002b51
-  data.tar.gz: 3de2f77f7bf9dd3f70049ffb2d4f988b49008ae294d1b4b9af493247fe557cdf
+  metadata.gz: a7be8276c5d35fdb04507dc28393359978c61f96c02d34e68241e7850f890d03
+  data.tar.gz: d2989e928d470c23443ec09e9d09a731a240fe177c38e18ee80c5439a94d4cc0
 SHA512:
-  metadata.gz: 90621f0a221f638a47587884a3fbdce8c303edb3e64c56b7aba96a1721408118aa9fb6c66cae3491aa30e7e33484d779615e088c48e5778590d3bdc8ba1e34bf
-  data.tar.gz: 7989b6cb3630975d9a03c48f067f7a8985b89c6fb287f4f43717d21d79c002b046281cbcd2028ff0aea2d0afde29baad6241c584c08d0f9f618b6e92c5552127
+  metadata.gz: 201051afeef8762eb3f8562224de9f0b76f74acf61a51b195d2a8eaf458d78cf716c8b1fa99c662479113061140bd4d6867ad25400dd6f7248ccd9df51375d5f
+  data.tar.gz: b919b79931e8f8162646e7e291909c6e6ccc35d7681b4a42788d028e206078154cd00ec05cf73419ffd7d80b598dbf1b203b117f11d05219a63e346988cbc13d

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [2.0.0] - 2026-06-01
+
+### Added
+
+- **`Configuration#provider_options`**: keyword options for built-in providers are forwarded to **`EnvProvider.new`** / **`AwsKmsProvider.new`** (`Hash`/`OrderedOptions`, no separate `aws_kms` / `env_provider` accessors).
+- **Breaking:** **`EnvProvider`** now accepts **`encryption_key:`** directly; pass **`provider_options[:encryption_key] = ENV.fetch("ACTIVE_CIPHER_MASTER_KEY")`** instead of configuring an env-var name.
+- Provider **`String`** aliases **`"aws:kms"`**, **`"env"`**, and related spellings (see **`Configuration`**).
+- **`AwsKmsProvider`** accepts **`endpoint`**, **`access_key_id`**, **`secret_access_key`**, builds **`Aws::KMS::Client`** internally; **`key_id:`** is required (configure via **`provider_options`** or pass a custom instance).
+
+### Changed
+
+- **Breaking:** Global **`Configuration#chunk_size`** removed — pass **`chunk_size`** into **`StreamCipher`**, **`S3Adapter`**, **`EncryptedMultipartUpload`**, and the **`ActiveCipherStorage`** Active Storage service (`storage.yml`).
+- **Breaking:** Built-in provider config is **`provider_options`** only (removed **`#aws_kms`** / **`#env_provider`**). **`AwsKmsProvider`** no longer reads **`ENV`** for KMS settings; set **`provider_options`** from your app.
+- **Blob metadata:** Rescue **`StandardError`** only; re-raise in **`Rails.env.development?`** so misconfiguration surfaces during development.
+- **Engine:** Remove global **`ActiveSupport::LogSubscriber.logger`** assignment (host apps use **`Rails.logger`** / **`ActiveStorage.logger`**).
+- **Engine:** Load **`ActiveStorage::Service::ActiveCipherStorageService`** directly from the Rails Active Storage hook.
+- **`ActiveCipherStorageService`:** Raise **`NotImplementedError`** for **`path_for`** when the inner service does not implement it (e.g. S3).
+
+### Removed
+
+- **`ActiveCipherStorage::KeyRotation`** and related rotation orchestration.
+- **Breaking:** Legacy **`ActiveCipherStorage::Adapters::ActiveStorageService`** alias and **`active_cipher_storage/active_storage_integration`** shim.
+- **`ActiveCipherStorageService#rekey`**, **`BlobMetadata.blobs_for`**, **`BlobMetadata.update_after_rotation`**.
+- Provider methods **`wrap_data_key`** and **`rotate_data_key`** from **`Providers::Base`**, **`EnvProvider`**, and **`AwsKmsProvider`**. Key or provider changes are left to the application (e.g. AWS KMS, custom jobs).
+
 ## [1.0.3] - 2026-04-25
 
 ### Changed
@@ -25,11 +50,6 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 - 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
@@ -45,7 +65,8 @@ 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.3...HEAD
+[Unreleased]: https://github.com/codebyjass/active-cipher-storage/compare/v2.0.0...HEAD
+[2.0.0]: https://github.com/codebyjass/active-cipher-storage/compare/v1.0.3...v2.0.0
 [1.0.3]: https://github.com/codebyjass/active-cipher-storage/compare/v1.0.2...v1.0.3
 [1.0.2]: https://github.com/codebyjass/active-cipher-storage/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/codebyjass/active-cipher-storage/compare/v1.0.0...v1.0.1

data/CONTRIBUTING.md

@@ -33,7 +33,6 @@ Use focused tests for:
 - Active Storage legacy plaintext fallback.
 - S3 multipart and streaming behavior.
 - Provider error handling.
-- Key rotation behavior.
 
 Security-sensitive fixes should include a regression test that fails without the fix.
 

data/README.md

@@ -19,7 +19,6 @@ It works with normal Rails Active Storage attachments, direct S3 uploads from Ru
 - Handles large files with streaming AES-256-GCM encryption.
 - Supports backend-managed multipart uploads for frontend chunk upload flows.
 - Uses pluggable key providers: environment variables, AWS KMS, or custom KMS providers.
-- Supports header-only key rotation without rewriting the full file body.
 
 ## Use Cases
 
@@ -43,18 +42,17 @@ It works with normal Rails Active Storage attachments, direct S3 uploads from Ru
 9. [Manual encrypt / decrypt](#manual-encrypt--decrypt)
 10. [Blob metadata](#blob-metadata)
 11. [KMS providers](#kms-providers)
-   - [Environment-variable provider](#environment-variable-provider)
-   - [AWS KMS provider](#aws-kms-provider)
-   - [Custom provider](#custom-provider)
-12. [Key rotation](#key-rotation)
-13. [Configuration reference](#configuration-reference)
-14. [Encryption format](#encryption-format)
-15. [Security notes](#security-notes)
-16. [Testing](#testing)
-17. [Contributing](#contributing)
-18. [Security reports](#security-reports)
-19. [License](#license)
-20. [Ruby and Rails compatibility](#ruby-and-rails-compatibility)
+    - [Environment-variable provider](#environment-variable-provider)
+    - [AWS KMS provider](#aws-kms-provider)
+    - [Custom provider](#custom-provider)
+12. [Configuration reference](#configuration-reference)
+13. [Encryption format](#encryption-format)
+14. [Security notes](#security-notes)
+15. [Testing](#testing)
+16. [Contributing](#contributing)
+17. [Security reports](#security-reports)
+18. [License](#license)
+19. [Ruby and Rails compatibility](#ruby-and-rails-compatibility)
 
 ## How it works
 
@@ -101,23 +99,27 @@ Your model, controller, and view code can keep using normal Active Storage APIs.
 ```ruby
 # config/initializers/active_cipher_storage.rb
 ActiveCipherStorage.configure do |config|
-  # Choose one provider:
-
-  # Option A — environment variable (development / staging)
-  config.provider = :env    # reads ACTIVE_CIPHER_MASTER_KEY
-
-  # Option B — AWS KMS (production)
-  config.provider = ActiveCipherStorage::Providers::AwsKmsProvider.new(
-    key_id: Rails.application.credentials.dig(:aws, :kms_key_id),
-    region: "us-east-1"
-  )
+  # Built-ins: :env, :aws_kms, "env", or "aws:kms". Custom: pass a Providers::Base instance.
+  config.provider = :env
+  config.provider_options[:encryption_key] = ENV.fetch("ACTIVE_CIPHER_MASTER_KEY")
+  # KMS-only apps often use:
+  # config.provider = "aws:kms"
+
+  # Provider-specific keyword args (see EnvProvider / AwsKmsProvider).
+  # config.provider_options[:key_id] = Rails.application.credentials.dig(:aws, :kms_key_id)
+  # config.provider_options[:region] = "us-east-1"
+  # config.provider_options[:endpoint] = "http://localhost:4566"   # e.g. LocalStack
+  # config.provider_options[:access_key_id] = "..."
+  # config.provider_options[:secret_access_key] = "..."
+  # config.provider_options[:encryption_context] = { "app" => "my-app" }
 
   # 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
 ```
 
+Streaming / multipart plaintext chunk size is **not** global: set `chunk_size` on the **`ActiveCipherStorage`** service in `storage.yml`, and pass `chunk_size` / `multipart_threshold` into **`S3Adapter`** / **`EncryptedMultipartUpload`** when you construct them (default **5 MiB**, `ActiveCipherStorage::Configuration::DEFAULT_CHUNK_SIZE`).
+
 Generate a master key for local development:
 
 ```bash
@@ -137,8 +139,9 @@ ACTIVE_CIPHER_MASTER_KEY=<base64-encoded-key>
 # config/storage.yml
 
 encrypted_s3:
-  service: ActiveCipherStorage   # resolved by the Engine
+  service: ActiveCipherStorage   # resolves to ActiveStorage::Service::ActiveCipherStorageService
   wrapped_service: s3            # name of another service in this file
+  chunk_size: 6291456            # plaintext bytes per stream chunk (>= 5 MiB for S3 multipart)
 
 s3:
   service: S3
@@ -181,12 +184,14 @@ This is useful for background jobs, service objects, scripts, or non-Rails Ruby
 require "active_cipher_storage"
 
 ActiveCipherStorage.configure do |c|
-  c.provider = ActiveCipherStorage::Providers::EnvProvider.new
+  c.provider = :env
+  c.provider_options[:encryption_key] = ENV.fetch("ACTIVE_CIPHER_MASTER_KEY")
 end
 
 s3 = ActiveCipherStorage::Adapters::S3Adapter.new(
-  bucket: "my-bucket",
-  region: "us-east-1"
+  bucket:     "my-bucket",
+  region:     "us-east-1",
+  chunk_size: ActiveCipherStorage::Configuration::DEFAULT_CHUNK_SIZE
 )
 
 # Encrypt before upload
@@ -204,7 +209,8 @@ Large files are automatically uploaded via S3 multipart when the payload exceeds
 ```ruby
 s3 = ActiveCipherStorage::Adapters::S3Adapter.new(
   bucket:              "my-bucket",
-  multipart_threshold: 50 * 1024 * 1024   # 50 MiB
+  multipart_threshold: 50 * 1024 * 1024,   # 50 MiB
+  chunk_size:          5 * 1024 * 1024
 )
 ```
 
@@ -216,10 +222,13 @@ Active Cipher Storage supports that flow, but the browser still does not get enc
 
 Use `EncryptedMultipartUpload` for this backend-managed upload flow.
 
+**Memory behavior:** the app does not assemble the whole file before uploading. Each `upload_part` call reads the incoming frontend chunk, encrypts that chunk into an authenticated ACS frame, and flushes encrypted bytes to S3 multipart upload parts as soon as the S3 minimum part size is reached. Keep frontend chunks bounded (for example 256 KiB to 5 MiB); a single frontend chunk is read into memory for that request.
+
 ```ruby
 uploader = ActiveCipherStorage::EncryptedMultipartUpload.new(
-  s3_client: Aws::S3::Client.new(region: "us-east-1"),
-  bucket:    "my-bucket"
+  s3_client:  Aws::S3::Client.new(region: "us-east-1"),
+  bucket:     "my-bucket",
+  chunk_size: 5 * 1024 * 1024
 )
 
 # Request 1: start the upload
@@ -263,8 +272,9 @@ class UploadsController < ApplicationController
 
   def set_uploader
     @uploader = ActiveCipherStorage::EncryptedMultipartUpload.new(
-      s3_client: s3_client,
-      bucket:    ENV.fetch("S3_BUCKET")
+      s3_client:  s3_client,
+      bucket:     ENV.fetch("S3_BUCKET"),
+      chunk_size: 5 * 1024 * 1024
     )
   end
 end
@@ -279,9 +289,10 @@ For multi-process deployments where chunks for the same active upload may land o
 ```ruby
 # Rails.cache backed by Redis allows cross-worker active upload sessions.
 uploader = ActiveCipherStorage::EncryptedMultipartUpload.new(
-  s3_client: s3_client,
-  bucket:    "my-bucket",
-  store:     Rails.cache        # any object with read/write/delete
+  s3_client:  s3_client,
+  bucket:     "my-bucket",
+  chunk_size: 5 * 1024 * 1024,
+  store:      Rails.cache        # any object with read/write/delete
 )
 ```
 
@@ -293,10 +304,13 @@ Use `stream_decrypted` when you need to send a large encrypted file to a client
 
 The adapter reads encrypted bytes from S3, decrypts authenticated chunks as they arrive, and yields plaintext chunks to your block. Memory usage stays bounded by one Active Cipher Storage chunk, which is 5 MiB by default.
 
+Use `stream_decrypted` for huge files. `get_decrypted` returns an IO for convenience, but it buffers the encrypted object before decrypting and is intended for small objects or tooling, not large client downloads.
+
 ```ruby
 s3 = ActiveCipherStorage::Adapters::S3Adapter.new(
-  bucket: "my-bucket",
-  region: "us-east-1"
+  bucket:     "my-bucket",
+  region:     "us-east-1",
+  chunk_size: ActiveCipherStorage::Configuration::DEFAULT_CHUNK_SIZE
 )
 
 # Stream directly into a Rails response
@@ -334,7 +348,8 @@ Use `Cipher` for small files and `StreamCipher` for large files:
 require "active_cipher_storage"
 
 ActiveCipherStorage.configure do |c|
-  c.provider = ActiveCipherStorage::Providers::EnvProvider.new
+  c.provider = :env
+  c.provider_options[:encryption_key] = ENV.fetch("ACTIVE_CIPHER_MASTER_KEY")
 end
 
 # Small files
@@ -374,71 +389,74 @@ When using the Rails Active Storage adapter, encryption metadata is automaticall
 }
 ```
 
-This metadata powers:
+This metadata supports:
 
-- **Key rotation queries** — find every blob encrypted under a given KMS key without scanning blob bodies
 - **Backward compatibility** — blobs uploaded before encryption was enabled are detected by the absence of the `ACS\x01` magic header and served as raw bytes
-- **Operational auditing** — know which key protects which blobs at a glance
+- **Operational auditing** — see which provider and key identifier were used when the blob was stored
 
 The binary file header remains the ground truth for decryption; metadata is informational only and a mismatch does not affect correctness.
 
-**Single-blob re-key** (re-wrap DEK without touching the file body):
+Changing KMS keys or providers for existing blobs is **not** handled by this gem: implement your own migration (for example using AWS KMS `ReEncrypt`, custom jobs, or by reading/writing raw storage keys via your Active Storage service’s **`download_raw`** / **`upload_raw`** if you need byte-level access). The [Encryption format](#encryption-format) section documents the on-disk layout.
 
-```ruby
-svc = ActiveCipherStorage::Adapters::ActiveStorageService.new(wrapped_service: inner)
+## KMS providers
 
-result = svc.rekey(
-  "storage/key/for/blob",
-  old_provider: old_provider,
-  new_provider: new_provider
-)
-# => { status: :rotated }
-```
+### Environment-variable provider
 
-**Batch key rotation** across all blobs for a provider:
+**Configure block (recommended)**
 
 ```ruby
-ActiveCipherStorage::KeyRotation.rotate(
-  old_provider: old_kms,
-  new_provider: new_kms,
-  service:      MyEncryptedStorageService.new
-) do |blob, result|
-  Rails.logger.info "#{blob.key}: #{result[:status]}"
+ActiveCipherStorage.configure do |config|
+  config.provider = :env
+  config.provider_options[:encryption_key] = ENV.fetch("ACTIVE_CIPHER_MASTER_KEY")
 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
+**Manual constructor** (tests, advanced use)
 
 ```ruby
-# Default env var: ACTIVE_CIPHER_MASTER_KEY
-provider = ActiveCipherStorage::Providers::EnvProvider.new
-
-# Custom env var name
 provider = ActiveCipherStorage::Providers::EnvProvider.new(
-  env_var: "MYAPP_ENCRYPTION_KEY"
+  encryption_key: ENV.fetch("ACTIVE_CIPHER_MASTER_KEY")
 )
 ```
 
-The master key wraps each per-file DEK with AES-256-GCM.  The wrapped DEK is stored in the file header; the plaintext DEK exists only during the encrypt/decrypt operation.
+The encryption key is a Base64-encoded 32-byte master key. It wraps each per-file DEK with AES-256-GCM. The wrapped DEK is stored in the file header; the plaintext DEK exists only during the encrypt/decrypt operation.
 
 ### AWS KMS provider
 
+The gem builds `Aws::KMS::Client` inside `AwsKmsProvider`. Pass settings via `ActiveCipherStorage.configure` (recommended) or construct the provider directly.
+
+**Configure block (recommended)**
+
+```ruby
+ActiveCipherStorage.configure do |config|
+  config.provider = :aws_kms   # or "aws:kms"
+
+  config.provider_options[:key_id] = "arn:aws:kms:us-east-1:123456789:key/mrk-abc123"
+  config.provider_options[:region] = "us-east-1"
+  # Optional — LocalStack or static keys when not using the default credential chain:
+  # config.provider_options[:endpoint] = "http://127.0.0.1:4566"
+  # config.provider_options[:access_key_id] = "test"
+  # config.provider_options[:secret_access_key] = "test"
+  # config.provider_options[:encryption_context] = { "app" => "my-app", "env" => Rails.env }
+end
+```
+
+Set `provider_options` from your app (e.g. `Rails.application.credentials`, `ENV`, etc.). The gem forwards them as keyword arguments to **`AwsKmsProvider`**.
+
+**Manual constructor** (tests, advanced use)
+
 ```ruby
 provider = ActiveCipherStorage::Providers::AwsKmsProvider.new(
   key_id:             "arn:aws:kms:us-east-1:123456789:key/mrk-abc123",
   region:             "us-east-1",
-
-  # Bind the DEK to a specific resource.  The same context must be
-  # present on decrypt — different context = decryption failure.
+  endpoint:           "http://127.0.0.1:4566",
+  access_key_id:      "test",
+  secret_access_key:  "test",
   encryption_context: { "app" => "my-app", "env" => Rails.env }
 )
 ```
 
-AWS credentials are resolved through the standard SDK chain (env vars, `~/.aws/credentials`, instance profile, EKS IRSA, etc.).
+You can still pass `client:` to inject a custom `Aws::KMS::Client` (e.g. in tests).
 
 ### Custom provider
 
@@ -460,10 +478,6 @@ class MyVaultProvider < ActiveCipherStorage::Providers::Base
     vault_client.decrypt(encrypted_key)
   end
 
-  def wrap_data_key(plaintext_dek)
-    vault_client.encrypt(plaintext_dek)
-  end
-
   private
 
   def vault_client
@@ -478,59 +492,23 @@ end
 
 The `provider_id` is embedded in every encrypted file. Routing at decrypt time is handled by whichever provider is configured — it is the application's responsibility to configure the right provider for each environment.
 
-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
-
-Enable automatic key rotation on the CMK in the AWS Console or via CLI. AWS transparently re-wraps all data keys on the next use — no application changes needed.
-
-### Cross-key and cross-provider rotation
-
-Use `KeyRotation.rotate` (covered in [Blob metadata](#blob-metadata)) to batch re-wrap all blobs under a new key. For AWS KMS → AWS KMS rotations the plaintext DEK never leaves KMS (`ReEncrypt` API). Cross-provider rotations (e.g. `EnvProvider` → `AwsKmsProvider`) briefly hold the plaintext DEK in process memory and zero it immediately after.
-
-**Dry-run mode** — validate headers without uploading:
-
-```ruby
-ActiveCipherStorage::KeyRotation.rotate(
-  old_provider: old_kms,
-  new_provider: new_kms,
-  service:      svc,
-  dry_run:      true
-) do |blob, result|
-  puts "#{blob.key}: #{result[:status]}"   # :validated or :failed
-end
-```
-
-### Low-level DEK re-wrapping
-
-```ruby
-# AWS KMS → AWS KMS (ReEncrypt, no plaintext in memory)
-old_provider = ActiveCipherStorage::Providers::AwsKmsProvider.new(key_id: "arn:...old")
-new_provider = ActiveCipherStorage::Providers::AwsKmsProvider.new(key_id: "arn:...new")
-new_dek = old_provider.rotate_data_key(encrypted_dek, destination_key_id: new_provider.key_id)
-
-# EnvProvider → EnvProvider
-old_provider = ActiveCipherStorage::Providers::EnvProvider.new(env_var: "OLD_KEY")
-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
 ActiveCipherStorage.configure do |config|
-  # Required.  A Providers::Base instance or :env / :aws_kms shorthand.
+  # Required. Providers::Base instance, or :env / :aws_kms / "env" / "aws:kms".
   config.provider   = :env
 
+  # Keyword options forwarded to the built-in provider’s `.new` (see KMS providers).
+  # config.provider_options[:encryption_key] = ENV.fetch("ACTIVE_CIPHER_MASTER_KEY")
+  # config.provider_options[:key_id] = "..."
+  # config.provider_options[:region] = "us-east-1"
+  # config.provider_options[:endpoint] = nil
+  # config.provider_options[:encryption_context] = {}
+
   # Encryption algorithm.  Currently only "aes-256-gcm" is supported.
   config.algorithm  = "aes-256-gcm"
 
-  # Plaintext bytes per chunk in StreamCipher mode.
-  # 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
@@ -605,7 +583,7 @@ Integration tests use in-memory fakes for both Active Storage and S3 — no real
 
 Contributions are welcome. Please read `CONTRIBUTING.md` before opening a pull request.
 
-For changes that affect encryption, streaming, providers, key rotation, or storage behavior, include focused specs that prove both the success path and the failure/tamper path. Run the full suite before submitting:
+For changes that affect encryption, streaming, providers, or storage behavior, include focused specs that prove both the success path and the failure/tamper path. Run the full suite before submitting:
 
 ```bash
 bundle exec rspec

data/lib/active_cipher_storage/adapters/s3_adapter.rb

@@ -8,13 +8,16 @@ module ActiveCipherStorage
       DEFAULT_MULTIPART_THRESHOLD = 100 * 1024 * 1024
 
       def initialize(bucket:, region: nil, multipart_threshold: DEFAULT_MULTIPART_THRESHOLD,
-                     s3_client: nil, config: nil)
+                     s3_client: nil, config: nil,
+                     chunk_size: Configuration::DEFAULT_CHUNK_SIZE)
         @bucket              = bucket
         @region              = region
         @multipart_threshold = multipart_threshold
         @client_override     = s3_client
         @config              = config || ActiveCipherStorage.configuration
+        @chunk_size          = Integer(chunk_size)
         @config.validate!
+        raise ArgumentError, "chunk_size must be positive" unless @chunk_size.positive?
       end
 
       def put_encrypted(key, io, **options)
@@ -89,7 +92,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.fetch(:encrypted_key)
         ))
@@ -97,8 +100,8 @@ module ActiveCipherStorage
         seq  = 0
         done = false
         until done
-          chunk     = input_io.read(@config.chunk_size) || "".b
-          done      = chunk.bytesize < @config.chunk_size
+          chunk     = input_io.read(@chunk_size) || "".b
+          done      = chunk.bytesize < @chunk_size
           seq      += 1
           frame_seq = done ? Format::FINAL_SEQ : seq
           iv        = SecureRandom.random_bytes(Format::IV_SIZE)
@@ -107,7 +110,7 @@ module ActiveCipherStorage
           ct = chunk.empty? ? c.final : (c.update(chunk.b) + c.final)
           Format.write_chunk(buffer, seq: frame_seq, iv: iv, ciphertext: ct, auth_tag: c.auth_tag)
 
-          next unless buffer.pos >= @config.chunk_size || done
+          next unless buffer.pos >= @chunk_size || done
 
           buffer.rewind
           part_number += 1
@@ -125,7 +128,7 @@ module ActiveCipherStorage
       def decrypt_io(io)
         header = Format.read_header(io)
         io.rewind
-        header.chunked ? StreamCipher.new(@config).decrypt_to_io(io)
+        header.chunked ? StreamCipher.new(config: @config, chunk_size: header.chunk_size).decrypt_to_io(io)
                        : StringIO.new(Cipher.new(@config).decrypt(io))
       end
 
@@ -149,7 +152,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"
@@ -235,6 +238,7 @@ module ActiveCipherStorage
         def drain_frames(&block)
           until @done
             break if @buffer.bytesize < FRAME_PREFIX_SIZE
+            # Length prefix at byte 16: seq(4) + iv(12).
             ct_len     = @buffer.byteslice(16, 4).unpack1("N")
             frame_size = FRAME_PREFIX_SIZE + ct_len + Format::AUTH_TAG_SIZE
             break if @buffer.bytesize < frame_size

data/lib/active_cipher_storage/blob_metadata.rb

@@ -5,11 +5,10 @@ module ActiveCipherStorage
   #   encrypted      => true
   #   cipher_version => Integer  (Format::VERSION)
   #   provider_id    => String   (e.g. "aws_kms", "env")
-  #   kms_key_id     => String   (CMK ARN, env-var name, or nil)
+  #   kms_key_id     => String   (CMK ARN, provider key identifier, or nil)
   #
-  # These are for operational visibility — rotation queries, auditing,
-  # backward-compat detection. The encrypted file header is always the
-  # authoritative source for decryption.
+  # These are for operational visibility and auditing. The encrypted file header
+  # is always the authoritative source for decryption.
   module BlobMetadata
     def self.write(storage_key, provider)
       return unless active_storage_available?
@@ -25,10 +24,8 @@ module ActiveCipherStorage
           "kms_key_id"     => provider.key_id
         ).compact
       )
-    rescue => e
-      ActiveCipherStorage.configuration.logger.warn(
-        "[ActiveCipherStorage] Could not write blob metadata for #{storage_key}: #{e.message}"
-      )
+    rescue StandardError => e
+      log_metadata_failure(storage_key, "write", e)
     end
 
     def self.write_plaintext(storage_key)
@@ -45,28 +42,8 @@ module ActiveCipherStorage
           "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?
-
-      blob = ActiveStorage::Blob.find_by(key: storage_key)
-      return unless blob
-
-      blob.update_columns(
-        metadata: blob.metadata.merge(
-          "provider_id" => new_provider.provider_id,
-          "kms_key_id"  => new_provider.key_id
-        ).compact
-      )
-    rescue => e
-      ActiveCipherStorage.configuration.logger.warn(
-        "[ActiveCipherStorage] Could not update rotation metadata for #{storage_key}: #{e.message}"
-      )
+    rescue StandardError => e
+      log_metadata_failure(storage_key, "write_plaintext", e)
     end
 
     # Returns the metadata hash for a blob, or nil if AR is unavailable.
@@ -75,29 +52,21 @@ module ActiveCipherStorage
       ActiveStorage::Blob.find_by(key: storage_key)&.metadata
     end
 
-    # Finds all blobs whose metadata matches the given provider.
-    # Iterates in batches to avoid loading all blobs into memory.
-    # Yields each matching blob.
-    #
-    # For large tables, add a DB-level index on `metadata->>'kms_key_id'`
-    # and narrow the scope before passing to this method.
-    def self.blobs_for(provider)
-      return enum_for(:blobs_for, provider) unless block_given?
-      return unless active_storage_available?
+    private_class_method def self.log_metadata_failure(storage_key, operation, error)
+      raise error if reraise_metadata_errors?
 
-      ActiveStorage::Blob.find_each do |blob|
-        meta = blob.metadata
-        next unless meta["encrypted"] == true
-        next unless meta["provider_id"] == provider.provider_id
-        next if provider.key_id && meta["kms_key_id"] != provider.key_id
+      ActiveCipherStorage.configuration.logger.warn(
+        "[ActiveCipherStorage] Blob metadata failed (#{operation}) for #{storage_key}: #{error.message}"
+      )
+    end
 
-        yield blob
-      end
+    private_class_method def self.reraise_metadata_errors?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.development?
     end
 
     private_class_method def self.active_storage_available?
       defined?(ActiveStorage::Blob) && ActiveStorage::Blob.table_exists?
-    rescue
+    rescue StandardError
       false
     end
   end