active_cipher_storage 1.0.2 → 2.0.0

data/README.md

@@ -1,83 +1,86 @@
-# ActiveCipherStorage
+# Active Cipher Storage
 
 [![CI](https://github.com/codebyjass/active-cipher-storage/actions/workflows/ruby.yml/badge.svg)](https://github.com/codebyjass/active-cipher-storage/actions/workflows/ruby.yml)
 
-ActiveCipherStorage is a Ruby gem for Rails Active Storage encryption and decryption. It encrypts files before they are stored, decrypts them when they are read, and supports AWS S3, streaming downloads, multipart uploads, AES-256-GCM envelope encryption, AWS KMS, and custom key providers.
+Active Cipher Storage is published as the `active_cipher_storage` Ruby gem.
 
-ActiveCipherStorage supports three upload paths:
+It adds Rails Active Storage encryption and decryption without changing the way your Rails app attaches files. Files are encrypted before they are stored in AWS S3 or another storage service, and decrypted when your app reads them back.
 
-- **Rails Active Storage** — application code keeps using normal attachment APIs while the storage service encrypts on upload and decrypts on download.
-- **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.
+This solves a common Rails security problem: sensitive files should be protected before they leave your application.
+
+It works with normal Rails Active Storage attachments, direct S3 uploads from Ruby service objects, streaming downloads, and backend-managed multipart uploads for large files.
+
+## Features
+
+- Encrypt files before uploading them to S3 or Active Storage.
+- Decrypt files automatically when downloading.
+- Works with Rails Active Storage.
+- Supports direct AWS S3 client usage.
+- 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.
+
+## Use Cases
+
+- Encrypt user documents before storing them in S3.
+- Secure financial records, contracts, medical files, invoices, and other sensitive uploads.
+- Add application-level encryption on top of AWS S3 server-side encryption.
+- Keep Rails Active Storage APIs while storing encrypted files.
+- Stream large encrypted files from S3 without loading the whole file into memory.
+- Meet compliance and privacy requirements around PII, GDPR, HIPAA-style data, or internal security policies.
 
 ## Contents
 
-1. [How it works](#how-it-works)
-2. [Installation](#installation)
-3. [Rails / Active Storage setup](#rails--active-storage-setup)
-4. [Standalone S3 usage](#standalone-s3-usage)
-5. [Chunked multipart upload](#chunked-multipart-upload)
-6. [Streaming download](#streaming-download)
-7. [Manual encrypt / decrypt](#manual-encrypt--decrypt)
-8. [Blob metadata](#blob-metadata)
-9. [KMS providers](#kms-providers)
-   - [Environment-variable provider](#environment-variable-provider)
-   - [AWS KMS provider](#aws-kms-provider)
-   - [Custom provider](#custom-provider)
-10. [Key rotation](#key-rotation)
-11. [Configuration reference](#configuration-reference)
-12. [Encryption format](#encryption-format)
-13. [Security notes](#security-notes)
-14. [Testing](#testing)
-15. [Contributing](#contributing)
-16. [Security reports](#security-reports)
-17. [License](#license)
-18. [Ruby and Rails compatibility](#ruby-and-rails-compatibility)
+1. [Features](#features)
+2. [Use Cases](#use-cases)
+3. [How it works](#how-it-works)
+4. [Installation](#installation)
+5. [Rails / Active Storage setup](#rails--active-storage-setup)
+6. [Standalone S3 usage](#standalone-s3-usage)
+7. [Chunked multipart upload](#chunked-multipart-upload)
+8. [Streaming download](#streaming-download)
+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. [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
 
-Every encrypted file is self-contained.  No external metadata store is needed.
+Every file gets its own random data encryption key. The file is encrypted with AES-256-GCM, and that data key is wrapped by your configured key provider.
 
-```
-┌─────────────────────────────────────────────────────────┐
-│  Plaintext file                                         │
-└────────────────────────┬────────────────────────────────┘
-                         │
-          ┌──────────────▼──────────────┐
-          │  1. Generate random DEK      │  (32 bytes, AES-256)
-          │     per-file, per-operation  │
-          └──────────────┬──────────────┘
-                         │
-          ┌──────────────▼──────────────┐
-          │  2. Encrypt file with DEK    │  AES-256-GCM
-          │     unique IV per operation  │  + auth tag
-          └──────────────┬──────────────┘
-                         │
-          ┌──────────────▼──────────────┐
-          │  3. Wrap DEK with KMS        │  ENV, AWS KMS,
-          │     master key               │  or custom
-          └──────────────┬──────────────┘
-                         │
-          ┌──────────────▼──────────────┐
-          │  4. Binary payload           │  Header + IV +
-          │     (stored in S3)           │  Ciphertext + Auth tag
-          └─────────────────────────────┘
-```
+The encrypted file is self-contained. It stores:
 
-Decryption reverses the flow: the KMS provider unwraps the DEK from the header, then AES-GCM verifies the auth tag and decrypts the ciphertext.
+- a small Active Cipher Storage header,
+- the encrypted data key,
+- the ciphertext,
+- authentication tags used to detect tampering.
 
-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.
+When the file is downloaded, the gem reads the header, asks the key provider to unwrap the data key, verifies the AES-GCM authentication tag, and returns plaintext to your app.
+
+The same format is used for Rails Active Storage uploads, direct S3 uploads, streaming downloads, and multipart upload flows.
 
 ## Installation
 
+Add the gem to your Gemfile:
+
 ```ruby
-# Gemfile
 gem "active_cipher_storage"
+```
 
-# For AWS KMS provider:
-gem "aws-sdk-kms"
+If you use AWS KMS or the direct S3 adapter, add the AWS SDK gems you need:
 
-# For standalone S3 adapter:
+```ruby
+gem "aws-sdk-kms"
 gem "aws-sdk-s3"
 ```
 
@@ -87,28 +90,36 @@ bundle install
 
 ## Rails / Active Storage setup
 
-### 1. Configure a KMS provider
+Use this path when you want Rails Active Storage to encrypt attachments automatically.
+
+Your model, controller, and view code can keep using normal Active Storage APIs. The only change is the storage service configuration.
+
+### 1. Configure a key provider
 
 ```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
@@ -128,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
@@ -154,7 +166,9 @@ user.document.attach(io: file, filename: "report.pdf")
 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.
+Active Storage now 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.
 
 `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.
 
@@ -162,26 +176,30 @@ Direct Active Storage browser uploads are intentionally disabled because they by
 
 ## Standalone S3 usage
 
-No Rails required.
+You can also use Active Cipher Storage without Rails.
+
+This is useful for background jobs, service objects, scripts, or non-Rails Ruby apps that upload encrypted files directly to S3.
 
 ```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 and upload
+# Encrypt before upload
 File.open("contract.pdf", "rb") do |f|
   s3.put_encrypted("legal/contract-2026.pdf", f)
 end
 
-# Download and decrypt — returns an IO
+# Download and decrypt
 io = s3.get_decrypted("legal/contract-2026.pdf")
 File.binwrite("decrypted_contract.pdf", io.read)
 ```
@@ -191,30 +209,36 @@ 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
 )
 ```
 
 ## 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.
+For large files, many apps upload from the browser in chunks.
+
+Active Cipher Storage supports that flow, but the browser still does not get encryption keys. The frontend sends plaintext chunks to your Rails app, and your backend encrypts those chunks before uploading encrypted multipart parts to S3.
 
-This flow is backend-managed. The frontend never receives encryption keys and never uploads plaintext directly to S3.
+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 ---
+# Request 1: start the upload
 session_id = uploader.initiate(key: "uploads/video.mp4")
 # Keep session_id for this active upload lifecycle.
 
-# --- Requests 2..N: send chunks (any size) ---
+# Requests 2..N: send chunks
 uploader.upload_part(session_id: session_id, chunk_io: request.body)
 
-# --- Final request: seal and complete ---
+# Final request: seal and complete
 result = uploader.complete(session_id: session_id)
 # => { status: :completed, key: "uploads/video.mp4", parts_count: 12 }
 ```
@@ -248,37 +272,45 @@ 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
 ```
 
-**Session storage:**
+**Session storage**
+
 By default, session state is held in process memory (`MemorySessionStore`). This is intended for one active backend-managed upload lifecycle and is not durable across process restarts or deploys.
 
 For multi-process deployments where chunks for the same active upload may land on different workers or hosts, pass a shared store:
 
 ```ruby
-# Rails.cache backed by Redis — allows cross-worker active upload sessions
+# 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
 )
 ```
 
-**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.
+**Security:** The plaintext data key is never stored in the session. Only the KMS-wrapped encrypted data key 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.
+Use `stream_decrypted` when you need to send a large encrypted file to a client without loading the whole file into memory.
+
+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
@@ -302,22 +334,25 @@ File.open("output.bin", "wb") do |f|
 end
 ```
 
-`stream_decrypted` handles S3 delivering data in any chunk size — the internal `StreamingDecryptor` buffers incoming bytes and emits plaintext only when a complete, authenticated ACS frame is available.
+`stream_decrypted` handles S3 delivering data in any chunk size. The internal decryptor buffers incoming bytes and emits plaintext only when a complete, authenticated frame is available.
 
 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):
+If you do not need Rails or S3 integration, you can use the lower-level cipher classes directly.
+
+Use `Cipher` for small files and `StreamCipher` for large files:
 
 ```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
 
-# ── In-memory (small files) ─────────────────────────────
+# Small files
 cipher    = ActiveCipherStorage::Cipher.new
 encrypted = cipher.encrypt(File.open("secret.txt", "rb"))
 # => Binary String with embedded header, IV, ciphertext, auth tag
@@ -325,7 +360,7 @@ encrypted = cipher.encrypt(File.open("secret.txt", "rb"))
 plaintext = cipher.decrypt(encrypted)
 # => Original plaintext String
 
-# ── Streaming (large files) ─────────────────────────────
+# Large files
 stream = ActiveCipherStorage::StreamCipher.new
 
 File.open("large.bin", "rb") do |input|
@@ -354,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
 
@@ -440,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
@@ -458,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
@@ -585,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