active_cipher_storage 1.0.0

data/lib/active_cipher_storage/providers/env_provider.rb

@@ -0,0 +1,122 @@
+require "openssl"
+require "securerandom"
+require "base64"
+
+module ActiveCipherStorage
+  module Providers
+    class EnvProvider < Base
+      include KeyUtils
+
+      PROVIDER_ID     = "env"
+      WRAP_ALGO       = "aes-256-gcm"
+      MASTER_KEY_SIZE = 32
+      WRAP_IV_SIZE    = 12
+      WRAP_TAG_SIZE   = 16
+
+      def initialize(env_var: "ACTIVE_CIPHER_MASTER_KEY", old_env_var: nil)
+        @env_var     = env_var
+        @old_env_var = old_env_var
+      end
+
+      def provider_id = PROVIDER_ID
+      def key_id      = @env_var
+
+      def generate_data_key
+        master = read_master_key(@env_var)
+        dek    = SecureRandom.random_bytes(Cipher::KEY_SIZE)
+        { plaintext_key: dek, encrypted_key: wrap_key(dek, master) }
+      ensure
+        zero_bytes!(master)
+      end
+
+      def decrypt_data_key(encrypted_key)
+        master = read_master_key(@env_var)
+        unwrap_key(encrypted_key, master)
+      ensure
+        zero_bytes!(master)
+      end
+
+      def wrap_data_key(plaintext_dek)
+        master = read_master_key(@env_var)
+        wrap_key(plaintext_dek, master)
+      ensure
+        zero_bytes!(master)
+      end
+
+      def rotate_data_key(encrypted_key, old_provider: nil)
+        source = old_provider || begin
+          raise Errors::UnsupportedOperation,
+                "Supply :old_provider to rotate via EnvProvider" unless @old_env_var
+          EnvProvider.new(env_var: @old_env_var)
+        end
+
+        plaintext_dek = source.decrypt_data_key(encrypted_key)
+        new_master    = read_master_key(@env_var)
+        wrap_key(plaintext_dek, new_master)
+      ensure
+        zero_bytes!(plaintext_dek)
+        zero_bytes!(new_master)
+      end
+
+      private
+
+      # Wrapped DEK: [12 IV][32 ciphertext][16 auth-tag] = 60 bytes
+      def wrap_key(dek, master)
+        iv     = SecureRandom.random_bytes(WRAP_IV_SIZE)
+        c      = new_cipher(:encrypt, master, iv)
+        ct     = c.update(dek) + c.final
+        iv + ct + c.auth_tag
+      end
+
+      def unwrap_key(wrapped, master)
+        expected = WRAP_IV_SIZE + Cipher::KEY_SIZE + WRAP_TAG_SIZE
+        unless wrapped.bytesize == expected
+          raise Errors::InvalidFormat, "Wrapped DEK has unexpected size #{wrapped.bytesize}"
+        end
+
+        iv  = wrapped.byteslice(0, WRAP_IV_SIZE)
+        ct  = wrapped.byteslice(WRAP_IV_SIZE, Cipher::KEY_SIZE)
+        tag = wrapped.byteslice(-WRAP_TAG_SIZE, WRAP_TAG_SIZE)
+
+        new_cipher(:decrypt, master, iv, tag).then { |c| c.update(ct) + c.final }
+      rescue OpenSSL::Cipher::CipherError
+        raise Errors::KeyManagementError,
+              "Master-key authentication failed — wrong key or tampered DEK"
+      end
+
+      def new_cipher(mode, key, iv, auth_tag = nil)
+        c = OpenSSL::Cipher.new(WRAP_ALGO)
+        mode == :encrypt ? c.encrypt : c.decrypt
+        c.key      = key
+        c.iv       = iv
+        c.auth_tag = auth_tag if auth_tag
+        c.auth_data = ""
+        c
+      end
+
+      def read_master_key(var_name)
+        encoded = ENV.fetch(var_name) do
+          raise Errors::ProviderError,
+                "Environment variable #{var_name.inspect} is not set. " \
+                "Generate one with: ruby -rsecurerandom -e " \
+                "'puts Base64.strict_encode64(SecureRandom.bytes(32))'"
+        end
+
+        key = begin
+          Base64.strict_decode64(encoded)
+        rescue ArgumentError
+          raise Errors::ProviderError,
+                "#{var_name} must be Base64-encoded (strict, no line breaks)"
+        end
+
+        unless key.bytesize == MASTER_KEY_SIZE
+          raise Errors::ProviderError,
+                "#{var_name} must decode to exactly #{MASTER_KEY_SIZE} bytes " \
+                "(got #{key.bytesize})"
+        end
+
+        key
+      end
+    end
+  end
+end

data/lib/active_cipher_storage/stream_cipher.rb

@@ -0,0 +1,102 @@
+require "openssl"
+require "securerandom"
+
+module ActiveCipherStorage
+  class StreamCipher
+    include KeyUtils
+
+    def initialize(config = ActiveCipherStorage.configuration)
+      config.validate!
+      @config     = config
+      @provider   = config.provider
+      @chunk_size = config.chunk_size
+    end
+
+    def encrypt(input_io, output_io)
+      dek_bundle = @provider.generate_data_key
+      key        = dek_bundle.fetch(:plaintext_key)
+
+      Format.write_header(output_io, Format::Header.new(
+        version:       Format::VERSION,
+        algorithm:     Format::ALGO_AES256GCM,
+        chunked:       true,
+        chunk_size:    @chunk_size,
+        provider_id:   @provider.provider_id,
+        encrypted_dek: dek_bundle.fetch(:encrypted_key)
+      ))
+
+      seq  = 0
+      done = false
+      until done
+        plaintext = input_io.read(@chunk_size) || "".b
+        done      = plaintext.bytesize < @chunk_size
+        seq      += 1
+        frame_seq = done ? Format::FINAL_SEQ : seq
+        iv        = SecureRandom.random_bytes(Format::IV_SIZE)
+        ct, tag   = encrypt_chunk(plaintext, key, iv, frame_seq)
+        Format.write_chunk(output_io, seq: frame_seq, iv: iv, ciphertext: ct, auth_tag: tag)
+      end
+
+      seq
+    ensure
+      zero_bytes!(key)
+    end
+
+    def decrypt(input_io, output_io)
+      header = Format.read_header(input_io)
+      raise Errors::InvalidFormat, "Payload is not chunked; use Cipher#decrypt" unless header.chunked
+
+      key = @provider.decrypt_data_key(header.encrypted_dek)
+      loop do
+        frame = Format.read_chunk(input_io)
+        raise Errors::InvalidFormat, "Unexpected end of stream — missing final frame" if frame.nil?
+
+        output_io.write(decrypt_chunk(frame[:ciphertext], key, frame[:iv], frame[:auth_tag], frame[:seq]))
+        break if frame[:seq] == Format::FINAL_SEQ
+      end
+    ensure
+      zero_bytes!(key)
+    end
+
+    def encrypt_to_io(io)
+      out = StringIO.new("".b)
+      encrypt(io, out)
+      out.rewind
+      out
+    end
+
+    def decrypt_to_io(io)
+      out = StringIO.new("".b)
+      decrypt(io, out)
+      out.rewind
+      out
+    end
+
+    private
+
+    def encrypt_chunk(plaintext, key, iv, seq)
+      c   = build_cipher(:encrypt, key, iv, nil, seq)
+      # OpenSSL raises "data must not be empty" on update(""); call final directly.
+      ct  = plaintext.empty? ? c.final : (c.update(plaintext.b) + c.final)
+      [ct, c.auth_tag]
+    end
+
+    def decrypt_chunk(ciphertext, key, iv, auth_tag, seq)
+      c = build_cipher(:decrypt, key, iv, auth_tag, seq)
+      ciphertext.empty? ? c.final : (c.update(ciphertext) + c.final)
+    rescue OpenSSL::Cipher::CipherError
+      raise Errors::DecryptionError,
+            "Authentication failed on chunk seq=#{seq} — data may be tampered"
+    end
+
+    def build_cipher(mode, key, iv, auth_tag, seq)
+      c = OpenSSL::Cipher.new(Cipher::OPENSSL_ALGO)
+      mode == :encrypt ? c.encrypt : c.decrypt
+      c.key      = key
+      c.iv       = iv
+      c.auth_tag = auth_tag if auth_tag
+      c.auth_data = [seq].pack("N")  # seq as AAD prevents chunk reordering attacks
+      c
+    end
+  end
+end

data/lib/active_cipher_storage/version.rb

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

data/lib/active_cipher_storage.rb

@@ -0,0 +1,43 @@
+require "openssl"
+require "securerandom"
+require "base64"
+require "stringio"
+require "concurrent"
+
+require_relative "active_cipher_storage/version"
+require_relative "active_cipher_storage/errors"
+require_relative "active_cipher_storage/key_utils"
+require_relative "active_cipher_storage/format"
+require_relative "active_cipher_storage/configuration"
+require_relative "active_cipher_storage/providers/base"
+require_relative "active_cipher_storage/providers/env_provider"
+require_relative "active_cipher_storage/providers/aws_kms_provider"
+require_relative "active_cipher_storage/cipher"
+require_relative "active_cipher_storage/stream_cipher"
+require_relative "active_cipher_storage/adapters/s3_adapter"
+require_relative "active_cipher_storage/adapters/active_storage_service"
+require_relative "active_cipher_storage/blob_metadata"
+require_relative "active_cipher_storage/key_rotation"
+require_relative "active_cipher_storage/multipart_upload"
+
+# Rails Engine wires the service into ActiveStorage's service registry.
+require_relative "active_cipher_storage/engine" if defined?(Rails)
+
+module ActiveCipherStorage
+  @config_mutex  = Mutex.new
+  @configuration = Configuration.new
+
+  class << self
+    def configuration
+      @configuration
+    end
+
+    def configure
+      @config_mutex.synchronize { yield @configuration }
+    end
+
+    def reset_configuration!
+      @config_mutex.synchronize { @configuration = Configuration.new }
+    end
+  end
+end

data/lib/active_storage/service/active_cipher_storage_service.rb

@@ -0,0 +1,10 @@
+require "active_storage/service"
+require "active_cipher_storage/adapters/active_storage_service"
+
+module ActiveStorage
+  class Service
+    unless const_defined?(:ActiveCipherStorageService, false)
+      ActiveCipherStorageService = ::ActiveCipherStorage::Adapters::ActiveStorageService
+    end
+  end
+end

metadata

@@ -0,0 +1,224 @@
+--- !ruby/object:Gem::Specification
+name: active_cipher_storage
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jaspreet Singh
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-04-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  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: aws-sdk-kms
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-s3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rspec-mocks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: |
+  active_cipher_storage provides AES-256-GCM envelope encryption for files stored
+  via Rails Active Storage or directly via the AWS S3 SDK. Key management is
+  delegated to pluggable KMS providers: environment-variable keys, AWS KMS,
+  or any custom provider implementing the base interface.
+email:
+- codebyjass@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- SECURITY.md
+- active_cipher_storage.gemspec
+- lib/active_cipher_storage.rb
+- lib/active_cipher_storage/adapters/active_storage_service.rb
+- lib/active_cipher_storage/adapters/s3_adapter.rb
+- lib/active_cipher_storage/blob_metadata.rb
+- lib/active_cipher_storage/cipher.rb
+- lib/active_cipher_storage/configuration.rb
+- lib/active_cipher_storage/engine.rb
+- lib/active_cipher_storage/errors.rb
+- lib/active_cipher_storage/format.rb
+- lib/active_cipher_storage/key_rotation.rb
+- lib/active_cipher_storage/key_utils.rb
+- lib/active_cipher_storage/multipart_upload.rb
+- lib/active_cipher_storage/providers/aws_kms_provider.rb
+- lib/active_cipher_storage/providers/base.rb
+- lib/active_cipher_storage/providers/env_provider.rb
+- lib/active_cipher_storage/stream_cipher.rb
+- lib/active_cipher_storage/version.rb
+- lib/active_storage/service/active_cipher_storage_service.rb
+homepage: https://github.com/codebyjass/active-cipher-storage
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/codebyjass/active-cipher-storage/issues
+  changelog_uri: https://github.com/codebyjass/active-cipher-storage/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/codebyjass/active-cipher-storage
+  homepage_uri: https://github.com/codebyjass/active-cipher-storage
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/codebyjass/active-cipher-storage
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Transparent file encryption for Active Storage and S3 with pluggable KMS
+  providers
+test_files: []