active_cipher_storage 1.0.0

data/lib/active_cipher_storage/engine.rb

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

data/lib/active_cipher_storage/errors.rb

@@ -0,0 +1,31 @@
+module ActiveCipherStorage
+  module Errors
+    # Base class for all gem errors.
+    class Error < StandardError; end
+
+    # Raised when the binary header is malformed or the magic bytes are wrong.
+    class InvalidFormat < Error; end
+
+    # Raised when GCM authentication tag verification fails (data tampered or
+    # wrong key). Deliberately vague to avoid oracle attacks.
+    class DecryptionError < Error; end
+
+    # Raised when a required KMS provider is not configured.
+    class ProviderError < Error; end
+
+    # Raised when the KMS provider cannot wrap/unwrap a data key.
+    class KeyManagementError < ProviderError; end
+
+    # Raised when a caller tries to use a feature the active provider doesn't
+    # implement (e.g. key rotation on EnvProvider).
+    class UnsupportedOperation < Error; end
+  end
+
+  # Convenience aliases at the top-level namespace.
+  Error              = Errors::Error
+  InvalidFormat      = Errors::InvalidFormat
+  DecryptionError    = Errors::DecryptionError
+  ProviderError      = Errors::ProviderError
+  KeyManagementError = Errors::KeyManagementError
+  UnsupportedOperation = Errors::UnsupportedOperation
+end

data/lib/active_cipher_storage/format.rb

@@ -0,0 +1,126 @@
+module ActiveCipherStorage
+  # Binary format v1:
+  #
+  # Header
+  #   [4]  Magic "ACS\x01"
+  #   [1]  Version (0x01)
+  #   [1]  Algorithm (0x01 = AES-256-GCM)
+  #   [1]  Flags    (bit 0 = chunked)
+  #   [4]  Chunk-size hint (uint32 BE; 0 if non-chunked)
+  #   [2]  Provider-ID length (uint16 BE)
+  #   [N]  Provider ID (UTF-8)
+  #   [2]  Encrypted DEK length (uint16 BE)
+  #   [M]  Encrypted DEK bytes
+  #
+  # Non-chunked payload:  [12 IV] [K ciphertext] [16 auth-tag]
+  #
+  # Chunked payload (repeat until seq == FINAL_SEQ):
+  #   [4]  Sequence number (1-based; FINAL_SEQ = 0xFFFFFFFF marks last frame)
+  #   [12] Chunk IV
+  #   [4]  Ciphertext length (uint32 BE)
+  #   [K]  Ciphertext
+  #   [16] Auth tag
+  #
+  # The final frame may carry zero-length ciphertext when the plaintext length
+  # is an exact multiple of chunk_size.
+  module Format
+    MAGIC          = "ACS\x01".b.freeze
+    VERSION        = 0x01
+    ALGO_AES256GCM = 0x01
+    FLAG_CHUNKED   = 0x01
+    IV_SIZE        = 12
+    AUTH_TAG_SIZE  = 16
+    FINAL_SEQ      = 0xFFFF_FFFF
+
+    Header = Struct.new(
+      :version, :algorithm, :chunked, :chunk_size, :provider_id, :encrypted_dek,
+      keyword_init: true
+    )
+
+    def self.write_header(io, header)
+      provider_bytes = header.provider_id.encode("UTF-8").b
+      flags = header.chunked ? FLAG_CHUNKED : 0x00
+
+      io.write(MAGIC)
+      io.write([VERSION].pack("C"))
+      io.write([ALGO_AES256GCM].pack("C"))
+      io.write([flags].pack("C"))
+      io.write([header.chunk_size.to_i].pack("N"))
+      io.write([provider_bytes.bytesize].pack("n"))
+      io.write(provider_bytes)
+      io.write([header.encrypted_dek.bytesize].pack("n"))
+      io.write(header.encrypted_dek)
+    end
+
+    def self.read_header(io)
+      magic = safe_read(io, 4)
+      raise Errors::InvalidFormat, "Invalid magic bytes" unless magic == MAGIC
+
+      version   = safe_read(io, 1).unpack1("C")
+      algorithm = safe_read(io, 1).unpack1("C")
+      flags     = safe_read(io, 1).unpack1("C")
+      chunk_sz  = safe_read(io, 4).unpack1("N")
+
+      validate_header_fields!(version, algorithm, flags)
+
+      provider_len  = safe_read(io, 2).unpack1("n")
+      provider_id   = safe_read(io, provider_len).force_encoding("UTF-8")
+
+      dek_len       = safe_read(io, 2).unpack1("n")
+      encrypted_dek = safe_read(io, dek_len)
+
+      Header.new(
+        version:       version,
+        algorithm:     algorithm,
+        chunked:       (flags & FLAG_CHUNKED) != 0,
+        chunk_size:    chunk_sz,
+        provider_id:   provider_id,
+        encrypted_dek: encrypted_dek
+      )
+    end
+
+    def self.write_chunk(io, seq:, iv:, ciphertext:, auth_tag:)
+      io.write([seq].pack("N"))
+      io.write(iv)
+      io.write([ciphertext.bytesize].pack("N"))
+      io.write(ciphertext)
+      io.write(auth_tag)
+    end
+
+    # Returns { seq:, iv:, ciphertext:, auth_tag: } or nil on clean EOF.
+    def self.read_chunk(io)
+      seq_bytes = io.read(4)
+      return nil if seq_bytes.nil? || seq_bytes.empty?
+
+      seq        = seq_bytes.unpack1("N")
+      iv         = safe_read(io, IV_SIZE)
+      ct_len     = safe_read(io, 4).unpack1("N")
+      ciphertext = ct_len.positive? ? safe_read(io, ct_len) : "".b
+      auth_tag   = safe_read(io, AUTH_TAG_SIZE)
+
+      { seq: seq, iv: iv, ciphertext: ciphertext, auth_tag: auth_tag }
+    end
+
+    private_class_method def self.safe_read(io, n)
+      data = io.read(n)
+      unless data && data.bytesize == n
+        raise Errors::InvalidFormat,
+              "Unexpected end of stream: expected #{n} bytes, got #{data&.bytesize || 0}"
+      end
+      data
+    end
+
+    private_class_method def self.validate_header_fields!(version, algorithm, flags)
+      raise Errors::InvalidFormat, "Unsupported version: #{version}" unless version == VERSION
+
+      unless algorithm == ALGO_AES256GCM
+        raise Errors::InvalidFormat, "Unsupported algorithm: #{algorithm}"
+      end
+
+      unknown_flags = flags & ~FLAG_CHUNKED
+      return if unknown_flags.zero?
+
+      raise Errors::InvalidFormat, "Unsupported flags: 0x#{unknown_flags.to_s(16)}"
+    end
+  end
+end

data/lib/active_cipher_storage/key_rotation.rb

@@ -0,0 +1,121 @@
+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

data/lib/active_cipher_storage/key_utils.rb

@@ -0,0 +1,12 @@
+module ActiveCipherStorage
+  module KeyUtils
+    private
+
+    # Best-effort in-place zeroing. Ruby GC may retain copies, but this
+    # reduces the window during which a key sits in heap memory.
+    def zero_bytes!(str)
+      return unless str.is_a?(String)
+      str.bytesize.times { |i| str.setbyte(i, 0) }
+    end
+  end
+end

data/lib/active_cipher_storage/multipart_upload.rb

@@ -0,0 +1,190 @@
+require "openssl"
+require "securerandom"
+require "concurrent"
+
+module ActiveCipherStorage
+  # Session-based multipart upload where the caller sends plaintext chunks
+  # across separate HTTP requests. Each chunk is encrypted as an ACS frame
+  # before being accumulated and flushed to S3.
+  #
+  # S3 requires every part except the last to be >= 5 MiB. Chunks can be any
+  # size — this class buffers encrypted frames and flushes S3 parts only when
+  # the buffer reaches chunk_size (default 5 MiB).
+  #
+  # Flow:
+  #   uploader = EncryptedMultipartUpload.new(s3_client:, bucket:)
+  #   session_id = uploader.initiate(key: "uploads/doc.pdf")
+  #   uploader.upload_part(session_id:, chunk_io: io1)   # repeat per chunk
+  #   uploader.complete(session_id:)
+  #
+  # Session state is kept in an in-memory store by default.
+  # For multi-process deployments pass store: Rails.cache (or any object
+  # that responds to read/write/delete with the same keyword signatures).
+  class EncryptedMultipartUpload
+    include KeyUtils
+
+    SESSION_TTL = 24 * 3600
+
+    def initialize(s3_client:, bucket:, config: nil, store: nil)
+      @s3     = s3_client
+      @bucket = bucket
+      @config = config || ActiveCipherStorage.configuration
+      @store  = store || MemorySessionStore.new
+      @config.validate!
+    end
+
+    # Starts a new multipart upload. Returns an opaque session_id.
+    def initiate(key:, metadata: {})
+      dek_bundle = @config.provider.generate_data_key
+      s3_opts    = { content_type: "application/octet-stream" }
+      s3_opts[:metadata] = metadata unless metadata.empty?
+      upload_id  = @s3.create_multipart_upload(bucket: @bucket, key: key, **s3_opts).upload_id
+
+      header_io = StringIO.new("".b)
+      Format.write_header(header_io, Format::Header.new(
+        version:       Format::VERSION,
+        algorithm:     Format::ALGO_AES256GCM,
+        chunked:       true,
+        chunk_size:    @config.chunk_size,
+        provider_id:   @config.provider.provider_id,
+        encrypted_dek: dek_bundle[:encrypted_key]
+      ))
+
+      session_id = SecureRandom.urlsafe_base64(24)
+      save_session(session_id, {
+        upload_id:     upload_id,
+        key:           key,
+        encrypted_dek: dek_bundle[:encrypted_key],
+        seq:           0,
+        parts:         [],
+        pending:       header_io.string
+      })
+      session_id
+    ensure
+      zero_bytes!(dek_bundle&.dig(:plaintext_key))
+    end
+
+    # Encrypts a chunk and buffers it. Flushes complete S3 parts (>= chunk_size)
+    # automatically. Returns { status: :ok, parts_uploaded: N }.
+    def upload_part(session_id:, chunk_io:)
+      session   = load_session!(session_id)
+      plaintext = chunk_io.read.b
+      session[:seq] += 1
+
+      session[:pending] = (session[:pending] +
+        build_frame(plaintext, session[:encrypted_dek], session[:seq])).b
+
+      while session[:pending].bytesize >= @config.chunk_size
+        flush_part(session, session[:pending].byteslice(0, @config.chunk_size))
+        session[:pending] = (session[:pending].byteslice(@config.chunk_size..) || "".b).b
+      end
+
+      save_session(session_id, session)
+      { status: :ok, parts_uploaded: session[:parts].length }
+    ensure
+      zero_bytes!(plaintext)
+    end
+
+    # Writes a zero-byte FINAL_SEQ sentinel frame, flushes remaining bytes as
+    # the last S3 part, and completes the multipart upload.
+    # Returns { status: :completed, key:, parts_count: }.
+    def complete(session_id:)
+      session = load_session!(session_id)
+
+      # Zero-byte final frame signals end-of-stream to the decryptor.
+      session[:pending] = (session[:pending] +
+        build_frame("".b, session[:encrypted_dek], Format::FINAL_SEQ)).b
+
+      flush_part(session, session[:pending]) unless session[:pending].empty?
+      session[:pending] = "".b
+
+      @s3.complete_multipart_upload(
+        bucket: @bucket, key: session[:key],
+        upload_id: session[:upload_id],
+        multipart_upload: { parts: session[:parts] }
+      )
+      @store.delete(session_id)
+      { status: :completed, key: session[:key], parts_count: session[:parts].length }
+    rescue StandardError
+      abort_s3(session)
+      @store.delete(session_id)
+      raise
+    end
+
+    # Aborts the in-progress S3 multipart upload and discards the session.
+    def abort(session_id:)
+      session = @store.read(session_id)
+      return unless session
+      abort_s3(session)
+      @store.delete(session_id)
+    end
+
+    private
+
+    def build_frame(plaintext, encrypted_dek, seq)
+      dek = @config.provider.decrypt_data_key(encrypted_dek)
+      iv  = SecureRandom.random_bytes(Format::IV_SIZE)
+      c   = chunk_cipher(dek, iv, seq)
+      ct  = plaintext.empty? ? c.final : (c.update(plaintext) + c.final)
+      buf = StringIO.new("".b)
+      Format.write_chunk(buf, seq: seq, iv: iv, ciphertext: ct, auth_tag: c.auth_tag)
+      buf.string
+    ensure
+      zero_bytes!(dek)
+    end
+
+    def flush_part(session, bytes)
+      pn   = session[:parts].length + 1
+      etag = @s3.upload_part(bucket: @bucket, key: session[:key],
+                              upload_id: session[:upload_id],
+                              part_number: pn, body: bytes).etag
+      session[:parts] << { part_number: pn, etag: etag }
+    end
+
+    def abort_s3(session)
+      @s3.abort_multipart_upload(bucket: @bucket, key: session[:key],
+                                  upload_id: session[:upload_id])
+    rescue StandardError
+      nil # best-effort abort
+    end
+
+    def chunk_cipher(key, iv, seq)
+      c = OpenSSL::Cipher.new(Cipher::OPENSSL_ALGO)
+      c.encrypt
+      c.key       = key
+      c.iv        = iv
+      c.auth_data = [seq].pack("N")
+      c
+    end
+
+    def load_session!(id)
+      @store.read(id) or
+        raise Errors::Error, "Upload session not found or expired: #{id}"
+    end
+
+    def save_session(id, data)
+      @store.write(id, data, expires_in: SESSION_TTL)
+    end
+
+    # Thread-safe in-memory session store backed by Concurrent::Map.
+    # Replace with a Rails.cache wrapper for multi-process deployments.
+    class MemorySessionStore
+      def initialize
+        @data = Concurrent::Map.new
+      end
+
+      def read(id)
+        entry = @data[id]
+        return nil unless entry
+        return nil if entry[:expires_at] && Time.now.to_i > entry[:expires_at]
+        entry[:data]
+      end
+
+      def write(id, data, expires_in: nil)
+        @data[id] = { data: data, expires_at: expires_in && Time.now.to_i + expires_in }
+      end
+
+      def delete(id) = @data.delete(id)
+    end
+  end
+end

data/lib/active_cipher_storage/providers/aws_kms_provider.rb

@@ -0,0 +1,90 @@
+module ActiveCipherStorage
+  module Providers
+    class AwsKmsProvider < Base
+      include KeyUtils
+
+      PROVIDER_ID = "aws_kms"
+
+      def initialize(key_id: nil, region: nil, encryption_context: {}, client: nil)
+        @key_id             = key_id || ENV.fetch("AWS_KMS_KEY_ID") {
+          raise Errors::ProviderError,
+                "AwsKmsProvider requires :key_id or AWS_KMS_KEY_ID env var"
+        }
+        @region             = region
+        @encryption_context = encryption_context || {}
+        @client_override    = client
+      end
+
+      def provider_id = PROVIDER_ID
+      def key_id      = @key_id
+
+      def generate_data_key
+        resp = kms_client.generate_data_key(
+          key_id:             @key_id,
+          key_spec:           "AES_256",
+          encryption_context: @encryption_context
+        )
+        { plaintext_key: resp.plaintext.dup, encrypted_key: resp.ciphertext_blob.dup }
+      rescue Aws::KMS::Errors::ServiceError => e
+        raise Errors::KeyManagementError, "KMS GenerateDataKey failed: #{e.message}"
+      ensure
+        # AWS SDK may retain a reference to resp.plaintext; zero our copy too.
+        resp&.plaintext&.then { |k| zero_bytes!(k) }
+      end
+
+      def decrypt_data_key(encrypted_key)
+        resp = kms_client.decrypt(
+          ciphertext_blob:    encrypted_key,
+          encryption_context: @encryption_context
+        )
+        resp.plaintext.dup
+      rescue Aws::KMS::Errors::InvalidCiphertextException,
+             Aws::KMS::Errors::IncorrectKeyException => e
+        raise Errors::KeyManagementError,
+              "KMS Decrypt failed — wrong key or tampered DEK: #{e.message}"
+      rescue Aws::KMS::Errors::ServiceError => e
+        raise Errors::KeyManagementError, "KMS Decrypt failed: #{e.message}"
+      ensure
+        resp&.plaintext&.then { |k| zero_bytes!(k) }
+      end
+
+      # Encrypts an existing plaintext DEK using KMS Encrypt.
+      # Prefer rotate_data_key (ReEncrypt) when both old and new providers are AWS KMS,
+      # because ReEncrypt keeps the plaintext DEK entirely within KMS.
+      def wrap_data_key(plaintext_dek)
+        resp = kms_client.encrypt(
+          key_id:             @key_id,
+          plaintext:          plaintext_dek,
+          encryption_context: @encryption_context
+        )
+        resp.ciphertext_blob.dup
+      rescue Aws::KMS::Errors::ServiceError => e
+        raise Errors::KeyManagementError, "KMS Encrypt failed: #{e.message}"
+      end
+
+      # Uses KMS ReEncrypt — the plaintext DEK never leaves KMS.
+      def rotate_data_key(encrypted_key, destination_key_id: nil)
+        resp = kms_client.re_encrypt(
+          ciphertext_blob:                encrypted_key,
+          source_encryption_context:      @encryption_context,
+          destination_key_id:             destination_key_id || @key_id,
+          destination_encryption_context: @encryption_context
+        )
+        resp.ciphertext_blob.dup
+      rescue Aws::KMS::Errors::ServiceError => e
+        raise Errors::KeyManagementError, "KMS ReEncrypt failed: #{e.message}"
+      end
+
+      private
+
+      def kms_client
+        @kms_client ||= begin
+          require "aws-sdk-kms"
+          @client_override || Aws::KMS::Client.new(**{ region: @region }.compact)
+        end
+      rescue LoadError
+        raise Errors::ProviderError, "aws-sdk-kms is required: add it to your Gemfile"
+      end
+    end
+  end
+end

data/lib/active_cipher_storage/providers/base.rb

@@ -0,0 +1,38 @@
+module ActiveCipherStorage
+  module Providers
+    class Base
+      # Returns { plaintext_key: String (32 bytes), encrypted_key: String }
+      def generate_data_key
+        raise NotImplementedError, "#{self.class}#generate_data_key is not implemented"
+      end
+
+      # Returns the plaintext DEK (32 bytes). Caller must zero it after use.
+      def decrypt_data_key(encrypted_key)
+        raise NotImplementedError, "#{self.class}#decrypt_data_key is not implemented"
+      end
+
+      # Wraps an existing plaintext DEK under this provider's master key.
+      # Used during key rotation to re-protect a DEK without re-encrypting the file.
+      def wrap_data_key(plaintext_dek)
+        raise NotImplementedError, "#{self.class}#wrap_data_key is not implemented"
+      end
+
+      # Short ASCII string embedded in every encrypted file header.
+      def provider_id
+        raise NotImplementedError, "#{self.class}#provider_id is not implemented"
+      end
+
+      # Stable identifier for the specific key material in use (e.g. CMK ARN,
+      # env var name). Stored in blob metadata for rotation queries.
+      # Returns nil for providers where key identity is not meaningful.
+      def key_id
+        nil
+      end
+
+      def rotate_data_key(encrypted_key)
+        raise Errors::UnsupportedOperation,
+              "#{self.class} does not support key rotation"
+      end
+    end
+  end
+end