familia 2.3.1 → 2.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87748023c0bec120fe0b4936eac184ebe7f72651639b7ff87238782987654cc7
-  data.tar.gz: 5a3cbaf9000cf1e12cdcff9f2d35eecca57a010725e501de37485bda7cf214af
+  metadata.gz: cfb3f3aa06c0b96493a86fbe2e3c475e81b9a84d69d7b88e06025adbb597ad8e
+  data.tar.gz: c567f15b73c06a67baad7b1aff36e23d0d544de1a25308716f6edbac235a3ca9
 SHA512:
-  metadata.gz: 21847a2154326c84d70557ee62ecfc4ea960f74ae6358e41b6c1d6fb7012d58034256a35dbc9aae26778a179cc3524e54012933a84191d2dc570f9d73c400cb8
-  data.tar.gz: da077f52d0ecbeba97779470f1e6d3a51934e7e7e3e03b05005e1187794f3ef23c9386aa15fe3747113c31982bf6e56add41948bd78a0d6d2867abaef883a31b
+  metadata.gz: 66028adaf4e3004b57bb17b39a99745ad771b2af915253cce02a6ca130e028cdf39e0fc11d90c40729ffa85cc5b5fa8c2c2f1b0320a7c3e21ea74858d173c6b6
+  data.tar.gz: aa3c991ea06b0c2268034784b83fb2dfb5ab6507902de3bca2345149dba3bdb287829769abbb15350c093551c79419c3e2e79558cacac2e589161ebdadd9dd4f

data/CHANGELOG.rst

@@ -7,6 +7,35 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.3.2:
+
+2.3.2 — 2026-03-12
+==================
+
+Fixed
+-----
+
+- ``Manager#decrypt`` no longer returns ASCII-8BIT strings. Decrypted plaintext
+  is now force-encoded to UTF-8 by default, fixing compatibility with json 2.18+
+  (which rejects non-UTF-8 strings) and preventing a hard error in json 3.0.
+  When an ``encoding`` field is present in the encrypted envelope, that encoding
+  is used instead. Fixes `#228 <https://github.com/delano/familia/issues/228>`_.
+
+- ``EncryptedData.from_json`` and ``validate!`` now filter unknown keys from
+  parsed envelopes before instantiation. This prevents ``ArgumentError`` when
+  reading envelopes written by future versions that include additional fields
+  (e.g. ``encoding``, ``compression``).
+
+AI Assistance
+-------------
+
+- Claude implemented the Phase 1 defensive read strategy, added the ``encoding``
+  field to ``EncryptedData`` with nil default and ``to_h.compact`` for clean
+  serialization, and wrote 22 test cases covering encoding round-trips, legacy
+  envelope backward compatibility, unknown key filtering, and edge cases (nil
+  input, bogus encoding names, binary ASCII-8BIT content).
+  PR `#230 <https://github.com/delano/familia/pull/230>`_.
+
 .. _changelog-2.3.1:
 
 2.3.1 — 2026-03-06

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.3.1)
+    familia (2.3.2)
       concurrent-ruby (~> 1.3)
       connection_pool (>= 2.4, < 4.0)
       csv (~> 3.3)

data/lib/familia/encryption/encrypted_data.rb

@@ -4,7 +4,18 @@
 
 module Familia
   module Encryption
-    EncryptedData = Data.define(:algorithm, :nonce, :ciphertext, :auth_tag, :key_version) do
+    EncryptedData = Data.define(:algorithm, :nonce, :ciphertext, :auth_tag, :key_version, :encoding) do
+      def initialize(algorithm:, nonce:, ciphertext:, auth_tag:, key_version:, encoding: nil)
+        super
+      end
+
+      # Omit nil-valued keys from the hash representation so that
+      # the encrypted envelope stays backward-compatible (no :encoding
+      # key unless explicitly set).
+      def to_h
+        super.compact
+      end
+
       # Class methods for parsing and validation
       def self.valid?(json_string)
         return true if json_string.nil? # Allow nil values
@@ -43,7 +54,7 @@ module Familia
 
         raise EncryptionError, "Missing required fields: #{missing_fields.join(', ')}" unless missing_fields.empty?
 
-        new(**parsed)
+        new(**parsed.slice(*members))
       end
 
       def self.from_json(json_string_or_hash)
@@ -53,7 +64,7 @@ module Familia
           parsed = json_string_or_hash
           # Symbolize keys if they're strings
           parsed = parsed.transform_keys(&:to_sym) if parsed.keys.first.is_a?(String)
-          new(**parsed)
+          new(**parsed.slice(*members))
         else
           # JSON string - validate and parse
           validate!(json_string_or_hash)

data/lib/familia/encryption/manager.rb

@@ -60,7 +60,8 @@ module Familia
           ciphertext = decode_and_validate_ciphertext(data.ciphertext)
           auth_tag = decode_and_validate(data.auth_tag, provider.auth_tag_size, 'auth_tag')
 
-          provider.decrypt(ciphertext, key, nonce, auth_tag, additional_data)
+          plaintext = provider.decrypt(ciphertext, key, nonce, auth_tag, additional_data)
+          plaintext.force_encoding(data.encoding || 'UTF-8')
         rescue EncryptionError
           raise
         rescue Familia::SerializerError => e

data/lib/familia/version.rb

@@ -4,5 +4,5 @@
 
 module Familia
   # Version information for the Familia
-  VERSION = '2.3.1'
+  VERSION = '2.3.2'
 end

data/try/features/encryption/encoding_phase1_try.rb

@@ -0,0 +1,357 @@
+# try/features/encryption/encoding_phase1_try.rb
+#
+# frozen_string_literal: true
+
+# Phase 1: Defensive read -- filter unknown keys, default encoding to UTF-8 on decrypt
+# See: https://github.com/delano/familia/issues/228
+
+require_relative '../../support/helpers/test_helpers'
+require_relative '../../../lib/familia/encryption'
+require 'base64'
+
+## Decrypted value has UTF-8 encoding (not ASCII-8BIT)
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "hello world"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+decrypted = Familia::Encryption.decrypt(encrypted, context: context)
+decrypted.encoding.to_s
+#=> "UTF-8"
+
+## Round-trip preserves encoding through encrypt then decrypt
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "caf\u00e9 na\u00efve r\u00e9sum\u00e9"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+decrypted = Familia::Encryption.decrypt(encrypted, context: context)
+[decrypted, decrypted.encoding.to_s]
+#=> ["caf\u00e9 na\u00efve r\u00e9sum\u00e9", "UTF-8"]
+
+## from_json handles payloads with extra unknown keys without raising
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "unknown keys test"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Parse, inject unknown keys, re-serialize
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:future_field] = "something new"
+parsed[:version] = 99
+json_with_extras = Familia::JsonSerializer.dump(parsed)
+
+# Should decrypt without error, ignoring unknown keys
+decrypted = Familia::Encryption.decrypt(json_with_extras, context: context)
+decrypted
+#=> "unknown keys test"
+
+## from_json handles Hash input with extra unknown keys
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "hash extra keys"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Parse into hash, add unknown keys, pass hash directly
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:unknown_extra] = "ignored"
+data = Familia::Encryption::EncryptedData.from_json(parsed)
+data.algorithm
+#=> "xchacha20poly1305"
+
+## from_json handles payloads missing the encoding key (backward compat)
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "backward compat test"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Verify the envelope does not contain encoding key
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed.key?(:encoding)
+#=> false
+
+## Decryption of legacy envelope (no encoding key) defaults to UTF-8
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "legacy payload"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Simulate a legacy envelope that definitely has no encoding key
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed.delete(:encoding)
+legacy_json = Familia::JsonSerializer.dump(parsed)
+
+decrypted = Familia::Encryption.decrypt(legacy_json, context: context)
+[decrypted, decrypted.encoding.to_s]
+#=> ["legacy payload", "UTF-8"]
+
+## EncryptedData encoding field defaults to nil when not provided
+data = Familia::Encryption::EncryptedData.new(
+  algorithm: "test",
+  nonce: "nonce",
+  ciphertext: "ct",
+  auth_tag: "tag",
+  key_version: "v1"
+)
+data.encoding
+#=> nil
+
+## EncryptedData accepts encoding when provided
+data = Familia::Encryption::EncryptedData.new(
+  algorithm: "test",
+  nonce: "nonce",
+  ciphertext: "ct",
+  auth_tag: "tag",
+  key_version: "v1",
+  encoding: "ISO-8859-1"
+)
+data.encoding
+#=> "ISO-8859-1"
+
+## to_h omits encoding when nil (envelope stays clean)
+data = Familia::Encryption::EncryptedData.new(
+  algorithm: "test",
+  nonce: "nonce",
+  ciphertext: "ct",
+  auth_tag: "tag",
+  key_version: "v1"
+)
+data.to_h.key?(:encoding)
+#=> false
+
+## to_h includes encoding when explicitly set
+data = Familia::Encryption::EncryptedData.new(
+  algorithm: "test",
+  nonce: "nonce",
+  ciphertext: "ct",
+  auth_tag: "tag",
+  key_version: "v1",
+  encoding: "UTF-8"
+)
+data.to_h.key?(:encoding)
+#=> true
+
+## to_h compact output serializes to JSON without encoding null
+data = Familia::Encryption::EncryptedData.new(
+  algorithm: "test",
+  nonce: "nonce",
+  ciphertext: "ct",
+  auth_tag: "tag",
+  key_version: "v1"
+)
+json = Familia::JsonSerializer.dump(data.to_h)
+json.include?('"encoding"')
+#=> false
+
+## Future envelope with encoding key present decrypts with specified encoding
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "future format"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Simulate a future writer that includes encoding in the envelope
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:encoding] = "UTF-8"
+future_json = Familia::JsonSerializer.dump(parsed)
+
+decrypted = Familia::Encryption.decrypt(future_json, context: context)
+[decrypted, decrypted.encoding.to_s]
+#=> ["future format", "UTF-8"]
+
+## Future envelope with encoding and extra unknown keys decrypts correctly
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "full future envelope"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Simulate a future writer with encoding, compression, and version fields
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:encoding] = "UTF-8"
+parsed[:compression] = "zstd"
+parsed[:envelope_version] = 2
+future_json = Familia::JsonSerializer.dump(parsed)
+
+decrypted = Familia::Encryption.decrypt(future_json, context: context)
+decrypted
+#=> "full future envelope"
+
+## validate! filters unknown keys from JSON string input
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "validate filter test"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Add unknown keys, run through validate! directly
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:compression] = "gzip"
+parsed[:metadata] = { created_at: "2026-01-01" }
+json_with_extras = Familia::JsonSerializer.dump(parsed)
+
+data = Familia::Encryption::EncryptedData.validate!(json_with_extras)
+[data.class, data.encoding]
+#=> [Familia::Encryption::EncryptedData, nil]
+
+## from_json handles Hash with string keys and unknown extras
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "string keys test"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Build a string-keyed hash with extra keys (simulating external deserialization)
+parsed = Familia::JsonSerializer.parse(encrypted) # no symbolize_names
+parsed["unknown_key"] = "should be ignored"
+data = Familia::Encryption::EncryptedData.from_json(parsed)
+data.algorithm
+#=> "xchacha20poly1305"
+
+## from_json Hash path without encoding key defaults encoding to nil
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "hash backward compat"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Parse to hash, confirm no encoding, pass as hash
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+data = Familia::Encryption::EncryptedData.from_json(parsed)
+data.encoding
+#=> nil
+
+## valid? returns true for envelopes with extra unknown keys
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "valid check"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Add extra keys to the JSON
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:future_field] = "extra"
+parsed[:encoding] = "UTF-8"
+json_with_extras = Familia::JsonSerializer.dump(parsed)
+
+Familia::Encryption::EncryptedData.valid?(json_with_extras)
+#=> true
+
+## Decrypt of empty string returns nil without error
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+Familia::Encryption.decrypt("", context: context)
+#=> nil
+
+## Non-UTF-8 encoding in envelope is applied on decrypt
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "caf\u00e9"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Simulate a Phase 2 writer that records the original encoding
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:encoding] = "ISO-8859-1"
+future_json = Familia::JsonSerializer.dump(parsed)
+
+decrypted = Familia::Encryption.decrypt(future_json, context: context)
+[decrypted.encoding.to_s, decrypted.bytes == plaintext.bytes]
+#=> ["ISO-8859-1", true]
+
+## Decrypt of nil returns nil without error
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+Familia::Encryption.decrypt(nil, context: context)
+#=> nil
+
+## Bogus encoding name in envelope raises EncryptionError
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "bad encoding test"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Inject an invalid encoding name into the envelope
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:encoding] = "NOT-A-REAL-ENCODING"
+tampered_json = Familia::JsonSerializer.dump(parsed)
+
+begin
+  Familia::Encryption.decrypt(tampered_json, context: context)
+  "should have raised"
+rescue Familia::Encryption::EncryptionError => e
+  e.message
+end
+#=~ /Decryption failed/
+
+## Binary data round-trip preserves bytes when encoding is set to ASCII-8BIT
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "binary\x00payload\xFF".b
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+# Simulate a Phase 2 writer that records ASCII-8BIT for binary content
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:encoding] = "ASCII-8BIT"
+future_json = Familia::JsonSerializer.dump(parsed)
+
+decrypted = Familia::Encryption.decrypt(future_json, context: context)
+[decrypted.encoding.to_s, decrypted.bytes == plaintext.bytes]
+#=> ["ASCII-8BIT", true]
+
+## Multibyte UTF-8 content round-trips with correct encoding and byte count
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "\u{1F600}\u{1F389}\u{2764}"
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+decrypted = Familia::Encryption.decrypt(encrypted, context: context)
+[decrypted == plaintext, decrypted.encoding.to_s, decrypted.valid_encoding?]
+#=> [true, "UTF-8", true]
+
+# TEARDOWN
+Fiber[:familia_key_cache]&.clear if Fiber[:familia_key_cache]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.3.2
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -383,6 +383,7 @@ files:
 - try/features/encrypted_fields/universal_serialization_safety_try.rb
 - try/features/encryption/config_persistence_try.rb
 - try/features/encryption/core_try.rb
+- try/features/encryption/encoding_phase1_try.rb
 - try/features/encryption/instance_variable_scope_try.rb
 - try/features/encryption/module_loading_try.rb
 - try/features/encryption/providers/aes_gcm_provider_try.rb