familia 2.3.2 → 2.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfb3f3aa06c0b96493a86fbe2e3c475e81b9a84d69d7b88e06025adbb597ad8e
-  data.tar.gz: c567f15b73c06a67baad7b1aff36e23d0d544de1a25308716f6edbac235a3ca9
+  metadata.gz: 715c43e8b2b403b23fdb6ffbb33c8558a8dbccb6c9cc9dc80a5892a193cdf8c6
+  data.tar.gz: 89a9fafdd21877562178d8b4b103f7fe119b6ee12d50ebec9397691bffbf3094
 SHA512:
-  metadata.gz: 66028adaf4e3004b57bb17b39a99745ad771b2af915253cce02a6ca130e028cdf39e0fc11d90c40729ffa85cc5b5fa8c2c2f1b0320a7c3e21ea74858d173c6b6
-  data.tar.gz: aa3c991ea06b0c2268034784b83fb2dfb5ab6507902de3bca2345149dba3bdb287829769abbb15350c093551c79419c3e2e79558cacac2e589161ebdadd9dd4f
+  metadata.gz: b05dcefb1c009d499f6f41918fe01e29dc7604468365f0b1b6de02ea61544b3948d2e4aa3d8909069b833d413e915a6e489af0228fa4976299b9d00f074a4e3c
+  data.tar.gz: 0b90e00e99299f33f48a689a58dca2a941d3db7bf53c455990a8989768aca41f0837941db7ea71a0568b9f2598f4777acff5570d834d2e8ac188112cc6a67d15

data/CHANGELOG.rst

@@ -7,6 +7,47 @@ The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.1.0/>`
 
    <!--scriv-insert-here-->
 
+.. _changelog-2.3.3:
+
+2.3.3 — 2026-03-30
+==================
+
+Added
+-----
+
+- Encrypt now records the original plaintext encoding in the EncryptedData
+  envelope (``encoding`` field), completing the Phase 2 encoding round-trip
+  fix. Decrypt (Phase 1, #228) already falls back to UTF-8 when the field
+  is absent, so this change is backward-compatible. PR #229
+
+Fixed
+-----
+
+- ``build_aad`` now produces consistent AAD (Additional Authenticated Data)
+  regardless of whether the record has been persisted. Previously, encrypted
+  fields with ``aad_fields`` used different AAD computation paths before and
+  after save, making ``reveal`` fail on any record created via ``create!``.
+  Issue #232, PR #234. No migration needed — the previous behavior was
+  broken (AAD mismatch prevented decryption), so no valid ciphertexts
+  exist under the old inconsistent paths.
+
+- ``build_aad`` no longer uses ``.compact`` on AAD field values. Previously,
+  nil fields were silently dropped, shifting later values left and producing
+  a different hash once the field was populated. Now each field is coerced
+  via ``.to_s`` so that nil and empty string both occupy a fixed position
+  in the joined AAD string. Issue #232, PR #234.
+
+AI Assistance
+-------------
+
+- Implementation and test authoring delegated to backend-dev agents, with
+  orchestration and Phase 1 test fixups handled in the main session. Claude
+  Opus 4.6.
+
+- Claude assisted with implementing the fix, updating affected tests, and
+  writing the round-trip regression test. The issue analysis, root cause
+  identification, and suggested fix were provided in the issue by the author.
+
 .. _changelog-2.3.2:
 
 2.3.2 — 2026-03-12

data/Gemfile.lock

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

data/docs/guides/feature-relationships-indexing.md

@@ -5,6 +5,7 @@ Indexing provides O(1) field-to-object lookups using Redis data structures, enab
 ## Core Concepts
 
 Indexing creates fast lookups for finding objects by field values:
+
 - **O(1) performance** - Hash/Set-based constant-time access
 - **Automatic management** - Class indexes update on save/destroy
 - **Flexible scoping** - Global or parent-scoped uniqueness
@@ -12,12 +13,12 @@ Indexing creates fast lookups for finding objects by field values:
 
 ## Index Types
 
-| Type | Scope | Use Case | Structure |
-|------|-------|----------|-----------|
-| `unique_index` | Class | Global unique fields | Redis HashKey |
-| `unique_index` | Instance | Parent-scoped unique | Redis HashKey |
-| `multi_index` | Class (default) | Global non-unique groupings | Redis Set per value |
-| `multi_index` | Instance | Parent-scoped groupings | Redis Set per value |
+| Type           | Scope           | Use Case                    | Structure           |
+| -------------- | --------------- | --------------------------- | ------------------- |
+| `unique_index` | Class           | Global unique fields        | Redis HashKey       |
+| `unique_index` | Instance        | Parent-scoped unique        | Redis HashKey       |
+| `multi_index`  | Class (default) | Global non-unique groupings | Redis Set per value |
+| `multi_index`  | Instance        | Parent-scoped groupings     | Redis Set per value |
 
 ## Class-Level Unique Indexing
 
@@ -47,12 +48,12 @@ User.find_by_email('alice.smith@example.com')  # => nil
 
 ### Generated Methods
 
-| Method | Description |
-|--------|-------------|
-| `User.find_by_email(email)` | O(1) lookup |
-| `User.index_email_for(user)` | Manual index |
+| Method                         | Description       |
+| ------------------------------ | ----------------- |
+| `User.find_by_email(email)`    | O(1) lookup       |
+| `User.index_email_for(user)`   | Manual index      |
 | `User.unindex_email_for(user)` | Remove from index |
-| `User.reindex_email_for(user)` | Update index |
+| `User.reindex_email_for(user)` | Update index      |
 
 ## Instance-Scoped Unique Indexing
 
@@ -139,20 +140,20 @@ Customer.role_index_for('user').dbkey   # => "customer:role_index:user"
 
 ### Generated Class Methods
 
-| Method | Description |
-|--------|-------------|
-| `Customer.role_index_for(value)` | Factory returning `Familia::UnsortedSet` for the field value |
-| `Customer.find_all_by_role(value)` | Find all objects with that field value |
-| `Customer.sample_from_role(value, count)` | Random sample of objects |
-| `Customer.rebuild_role_index` | Rebuild the entire index from source data |
+| Method                                    | Description                                                  |
+| ----------------------------------------- | ------------------------------------------------------------ |
+| `Customer.role_index_for(value)`          | Factory returning `Familia::UnsortedSet` for the field value |
+| `Customer.find_all_by_role(value)`        | Find all objects with that field value                       |
+| `Customer.sample_from_role(value, count)` | Random sample of objects                                     |
+| `Customer.rebuild_role_index`             | Rebuild the entire index from source data                    |
 
 ### Generated Instance Methods
 
-| Method | Description |
-|--------|-------------|
-| `customer.add_to_class_role_index` | Add this object to its field value's index |
-| `customer.remove_from_class_role_index` | Remove this object from its field value's index |
-| `customer.update_in_class_role_index(old_value)` | Move object from old index to new index |
+| Method                                           | Description                                     |
+| ------------------------------------------------ | ----------------------------------------------- |
+| `customer.add_to_class_role_index`               | Add this object to its field value's index      |
+| `customer.remove_from_class_role_index`          | Remove this object from its field value's index |
+| `customer.update_in_class_role_index(old_value)` | Move object from old index to new index         |
 
 ### Update Operations
 
@@ -271,24 +272,28 @@ todays_events = user.find_all_by_daily_partition(today)
 ### Class vs Instance Scoping
 
 **Class-level unique (`unique_index :email, :email_lookup`):**
+
 - Automatic indexing on save/destroy
 - System-wide uniqueness
 - No parent context needed
 - Examples: emails, usernames, API keys
 
 **Class-level multi (`multi_index :role, :role_index`):**
+
 - Default behavior (no `within:` needed)
 - Groups all objects by field value at class level
 - Manual indexing via instance methods
 - Examples: roles, categories, statuses
 
 **Instance-scoped (`unique_index :badge, :badge_index, within: Company`):**
+
 - Manual indexing required
 - Unique within parent only
 - Requires parent context
 - Examples: employee IDs, project names per team
 
 **Instance-scoped multi (`multi_index :dept, :dept_index, within: Company`):**
+
 - Groups objects by field value within parent scope
 - Same field value allowed across different parents
 - Manual indexing with parent context
@@ -297,11 +302,13 @@ todays_events = user.find_all_by_daily_partition(today)
 ### Unique vs Multi Indexing
 
 **Unique index (`unique_index`):**
+
 - 1:1 field-to-object mapping
 - Returns single object or nil
 - Enforces uniqueness within scope
 
 **Multi index (`multi_index`):**
+
 - 1:many field-to-objects mapping
 - Returns array of objects
 - Allows duplicate values
@@ -325,6 +332,7 @@ These methods work because **indexes are derived data** - they're computed from
 > **Important:** Participation data (like `@team.members`) cannot be rebuilt automatically because participations represent business decisions, not derived data. See [Why Participations Can't Be Rebuilt](../../lib/familia/features/relationships/participation/rebuild_strategies.md) for the critical distinction between indexes and participations.
 
 **When to rebuild indexes:**
+
 - After data migrations or bulk imports
 - Recovering from index corruption
 - Adding indexes to existing data
@@ -372,26 +380,29 @@ Index values (the object identifiers stored in hash keys and sets) are raw strin
 
 ## Redis Key Patterns
 
-| Type | Pattern | Example |
-|------|---------|---------|
-| Class unique | `{class}:{index_name}` | `user:email_lookup` |
-| Class multi | `{class}:{index_name}:{value}` | `customer:role_index:admin` |
-| Instance unique | `{scope}:{id}:{index_name}` | `company:123:badge_index` |
-| Instance multi | `{scope}:{id}:{index_name}:{value}` | `company:123:dept_index:engineering` |
+| Type            | Pattern                             | Example                              |
+| --------------- | ----------------------------------- | ------------------------------------ |
+| Class unique    | `{class}:{index_name}`              | `user:email_lookup`                  |
+| Class multi     | `{class}:{index_name}:{value}`      | `customer:role_index:admin`          |
+| Instance unique | `{scope}:{id}:{index_name}`         | `company:123:badge_index`            |
+| Instance multi  | `{scope}:{id}:{index_name}:{value}` | `company:123:dept_index:engineering` |
 
 ## Troubleshooting
 
 ### Common Issues
 
 **Query methods not generated:**
+
 - Check `query: true` (default) or explicitly set
 - Verify `feature :relationships` declared
 
 **Index not updating:**
+
 - Class indexes: automatic on save/destroy
 - Instance indexes: require manual `add_to_*` calls
 
 **Duplicate key errors:**
+
 - Use `multi_index` for non-unique values
 - Consider instance-scoped for contextual uniqueness
 

data/lib/familia/encryption/manager.rb

@@ -15,7 +15,8 @@ module Familia
       end
 
       def encrypt(plaintext, context:, additional_data: nil)
-        return nil if plaintext.to_s.empty?
+        plaintext = plaintext.to_s
+        return nil if plaintext.empty?
 
         key = derive_key(context)
 
@@ -26,7 +27,8 @@ module Familia
           nonce: Base64.strict_encode64(result[:nonce]),
           ciphertext: Base64.strict_encode64(result[:ciphertext]),
           auth_tag: Base64.strict_encode64(result[:auth_tag]),
-          key_version: current_key_version
+          key_version: current_key_version,
+          encoding: plaintext.encoding.name,
         ).to_h
 
         Familia::JsonSerializer.dump(encrypted_data)
@@ -35,7 +37,9 @@ module Familia
       end
 
       def decrypt(encrypted_json_or_hash, context:, additional_data: nil)
-        return nil if encrypted_json_or_hash.nil? || (encrypted_json_or_hash.respond_to?(:empty?) && encrypted_json_or_hash.empty?)
+        if encrypted_json_or_hash.nil? || (encrypted_json_or_hash.respond_to?(:empty?) && encrypted_json_or_hash.empty?)
+          return nil
+        end
 
         # Increment counter immediately to track all decryption attempts, even failed ones
         Familia::Encryption.derivation_count.increment

data/lib/familia/features/encrypted_fields/encrypted_field_type.rb

@@ -221,16 +221,18 @@ module Familia
       if @aad_fields.empty?
         # When no AAD fields specified, use class:field:identifier
         base_components.join(':')
-      elsif record.exists?
-        # For unsaved records, don't enforce AAD fields since they can change
-        # For saved records, include field values for tamper protection
-        values = @aad_fields.map { |field| record.send(field) }
-        all_components = [*base_components, *values].compact
-        Digest::SHA256.hexdigest(all_components.join(':'))
-      # Include specified field values in AAD for persisted records
       else
-        # For unsaved records, only use class:field:identifier for context isolation
-        base_components.join(':')
+        # Always include aad_field values regardless of persistence state.
+        # The field values are available on the record before save and must
+        # produce identical AAD at both encrypt and decrypt time.
+        #
+        # .to_s coerces nil to "" so that every declared AAD field occupies
+        # a fixed position in the join. Without this, a nil field would
+        # shift later values left and produce a different hash once the
+        # field is populated — making existing ciphertext undecryptable.
+        values = @aad_fields.map { |field| record.send(field).to_s }
+        all_components = [*base_components, *values]
+        Digest::SHA256.hexdigest(all_components.join(':'))
       end
     end
   end

data/lib/familia/horreum/persistence.rb

@@ -275,12 +275,11 @@ module Familia
       # Optionally updates the key's expiration time if the feature is enabled
       # for the object's class.
       #
-      # Unlike +save+, this method does NOT add the object to the class-level
-      # +instances+ sorted set, does not run +prepare_for_save+ (timestamps,
-      # unique index guards), and does not update class indexes. Use this for
-      # updating fields on an object that is already persisted and tracked.
-      # If the object's hash key was created via +commit_fields+ alone, it
-      # will exist in the DB but won't appear in +instances.to_a+ listings.
+      # Unlike +save+, this method does not run +prepare_for_save+ (timestamps,
+      # unique index guards) and does not update class indexes. It does update
+      # the class-level +instances+ sorted set via +touch_instances!+, so the
+      # object will appear in +instances.to_a+ listings. Use this for updating
+      # fields on an object that is already persisted and tracked.
       #
       # @param update_expiration [Boolean] Whether to update the expiration time
       #   of the Valkey key. Defaults to true.

data/lib/familia/version.rb

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

data/try/features/encrypted_fields/aad_nil_fields_try.rb

@@ -0,0 +1,114 @@
+# try/features/encrypted_fields/aad_nil_fields_try.rb
+#
+# frozen_string_literal: true
+
+# Verifies build_aad behavior when AAD field values are nil or empty.
+# Covers edge cases around nil vs empty string AAD consistency.
+
+require 'base64'
+require 'digest'
+require_relative '../../support/helpers/test_helpers'
+
+test_keys = {
+  v1: Base64.strict_encode64('a' * 32),
+}
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+class AADNilFieldModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  field :email
+  encrypted_field :api_key, aad_fields: [:email]
+end
+
+# Model with multiple AAD fields to test positional stability
+class AADMultiFieldModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  field :org
+  field :role
+  field :region
+  encrypted_field :token, aad_fields: [:org, :role, :region]
+end
+
+Familia.dbclient.flushdb
+
+## Encrypt with nil AAD field and reveal without changing it succeeds
+record = AADNilFieldModel.new(id: 'nil-aad-1')
+record.api_key = 'nil-aad-secret'
+decrypted = nil
+record.api_key.reveal { |pt| decrypted = pt }
+decrypted
+#=> "nil-aad-secret"
+
+## Encrypt with nil AAD field then set field to non-nil causes reveal to fail
+record2 = AADNilFieldModel.new(id: 'nil-aad-2')
+record2.api_key = 'bound-to-nil'
+record2.email = 'now-set@example.com'
+result = begin
+  record2.api_key.reveal { |pt| pt }
+  'UNEXPECTED SUCCESS'
+rescue Familia::EncryptionError
+  'Familia::EncryptionError'
+end
+result
+#=> "Familia::EncryptionError"
+
+## Encrypt with non-nil AAD field then set to nil causes reveal to fail
+record3 = AADNilFieldModel.new(id: 'nil-aad-3', email: 'was-set@example.com')
+record3.api_key = 'bound-to-email'
+record3.email = nil
+result3 = begin
+  record3.api_key.reveal { |pt| pt }
+  'UNEXPECTED SUCCESS'
+rescue Familia::EncryptionError
+  'Familia::EncryptionError'
+end
+result3
+#=> "Familia::EncryptionError"
+
+## Encrypt with empty string AAD field and reveal succeeds
+# Note: the setter treats empty string as nil for the encrypted field itself,
+# but the AAD field (email) is a regular field that can hold empty string.
+record4 = AADNilFieldModel.new(id: 'nil-aad-4', email: '')
+record4.api_key = 'empty-email-secret'
+decrypted4 = nil
+record4.api_key.reveal { |pt| decrypted4 = pt }
+decrypted4
+#=> "empty-email-secret"
+
+## nil and empty string AAD fields produce identical AAD (both are "no value")
+record_nil = AADNilFieldModel.new(id: 'aad-cmp-1')
+record_empty = AADNilFieldModel.new(id: 'aad-cmp-1', email: '')
+field_type = AADNilFieldModel.field_types[:api_key]
+aad_nil = field_type.send(:build_aad, record_nil)
+aad_empty = field_type.send(:build_aad, record_empty)
+aad_nil == aad_empty
+#=> true
+
+## Nil AAD fields preserve position: [A, nil, C] differs from [A, C]
+# With the old .compact, a nil middle field would shift later values left,
+# producing the same hash as a model where that field never existed.
+# With .to_s, nil becomes "" and holds its position: "A::C" != "A:C".
+@ft = AADMultiFieldModel.field_types[:token]
+rec_nil_middle = AADMultiFieldModel.new(id: 'pos-1', org: 'acme', role: nil, region: 'us')
+rec_no_middle  = AADMultiFieldModel.new(id: 'pos-1', org: 'acme', role: 'us')
+aad_with_nil = @ft.send(:build_aad, rec_nil_middle)
+aad_shifted  = @ft.send(:build_aad, rec_no_middle)
+aad_with_nil != aad_shifted
+#=> true
+
+## Adjacent nil fields are distinguishable from a single nil
+rec_two_nils = AADMultiFieldModel.new(id: 'pos-2', org: 'acme')
+rec_one_nil  = AADMultiFieldModel.new(id: 'pos-2', org: 'acme', region: 'eu')
+aad_two = @ft.send(:build_aad, rec_two_nils)
+aad_one = @ft.send(:build_aad, rec_one_nil)
+aad_two != aad_one
+#=> true
+
+Familia.dbclient.flushdb
+Familia.config.encryption_keys = nil
+Familia.config.current_key_version = nil

data/try/features/encrypted_fields/aad_protection_try.rb

@@ -28,16 +28,15 @@ Familia.dbclient.flushdb
 
 ## AAD prevents field substitution attacks - proper cross-record test
 @victim = AADProtectedModel.new(id: 'victim-1', email: 'victim@example.com')
-@victim.save  # Need to save first for AAD to be active
 @victim.api_key = 'victim-secret-key'
-@victim.save  # Save the encrypted value
+@victim.save
 
 # Extract the raw encrypted JSON data (not the ConcealedString object)
 @victim_encrypted_data = @victim.api_key.encrypted_value
 
 # Create an attacker record with different AAD context (different email)
 @attacker = AADProtectedModel.new(id: 'attacker-1', email: 'attacker@evil.com')
-@attacker.save  # Need to save for AAD to be active
+@attacker.save
 
 # Simulate database tampering: set attacker's field to victim's encrypted data
 # This simulates what an attacker with database access might try to do
@@ -67,7 +66,6 @@ end
 
 ## Cross-record attack with same email (should still fail due to different identifiers)
 victim2 = AADProtectedModel.new(id: 'victim-2', email: 'shared@example.com')
-victim2.save
 victim2.api_key = 'victim2-secret'
 victim2.save
 
@@ -89,21 +87,24 @@ end
 @result3
 #=> "Familia::EncryptionError"
 
-## Without saving, AAD is not enforced (no database context)
+## AAD fields are enforced on unsaved records - changing aad_field breaks reveal
 unsaved_model = AADProtectedModel.new(id: 'unsaved-1', email: 'test@example.com')
 unsaved_model.api_key = 'test-key'
 
-# Change email after encryption but before save - should still work
+# Change email after encryption - AAD mismatch should cause decryption failure
 unsaved_model.email = 'changed@example.com'
-decrypted = nil
-unsaved_model.api_key.reveal { |plaintext| decrypted = plaintext }
-decrypted
-#=> "test-key"
+@result_unsaved = begin
+  unsaved_model.api_key.reveal { |plaintext| plaintext }
+  "UNEXPECTED SUCCESS"
+rescue Familia::EncryptionError => error
+  error.class.name
+end
+@result_unsaved
+#=> "Familia::EncryptionError"
 
 ## Cross-model attack with raw encrypted JSON
 # Demonstrate that raw encrypted data can't be moved between models
 @json_victim = AADProtectedModel.new(id: 'json-victim-1', email: 'jsonvictim@example.com')
-@json_victim.save
 @json_victim.api_key = 'json-victim-secret'
 
 # Get the raw encrypted JSON and create a new ConcealedString for different record
@@ -126,7 +127,6 @@ end
 
 ## Successful decryption with correct context (control test)
 legitimate_user = AADProtectedModel.new(id: 'legitimate-1', email: 'legit@example.com')
-legitimate_user.save
 legitimate_user.api_key = 'legitimate-secret'
 legitimate_user.save
 

data/try/features/encrypted_fields/aad_roundtrip_try.rb

@@ -0,0 +1,102 @@
+# try/features/encrypted_fields/aad_roundtrip_try.rb
+#
+# frozen_string_literal: true
+
+# Verifies that encrypted fields with aad_fields survive the
+# create! -> reveal and create! -> load -> reveal round-trips.
+# Regression test for GitHub issue #232.
+
+require 'base64'
+require_relative '../../support/helpers/test_helpers'
+
+test_keys = {
+  v1: Base64.strict_encode64('a' * 32),
+}
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+class AADRoundtripModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :domain_id
+  field :domain_id
+  field :email
+  encrypted_field :api_key, aad_fields: [:domain_id]
+end
+
+class AADRoundtripEnforcementModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  field :email
+  encrypted_field :api_key, aad_fields: [:email]
+end
+
+Familia.dbclient.flushdb
+
+## reveal succeeds on in-memory object after create! with aad_fields
+config = AADRoundtripModel.create!(domain_id: 'dom-001', api_key: 'secret-abc')
+decrypted = nil
+config.api_key.reveal { |pt| decrypted = pt }
+decrypted
+#=> "secret-abc"
+
+## reveal succeeds on object reloaded from Redis after create!
+config2 = AADRoundtripModel.create!(domain_id: 'dom-002', api_key: 'secret-xyz')
+reloaded = AADRoundtripModel.load('dom-002')
+decrypted2 = nil
+reloaded.api_key.reveal { |pt| decrypted2 = pt }
+decrypted2
+#=> "secret-xyz"
+
+## build_aad produces identical AAD before and after save
+unsaved = AADRoundtripModel.new(domain_id: 'dom-003', email: 'test@example.com')
+field_type = AADRoundtripModel.field_types[:api_key]
+aad_before = field_type.send(:build_aad, unsaved)
+unsaved.save
+aad_after = field_type.send(:build_aad, unsaved)
+aad_before == aad_after
+#=> true
+
+## round-trip works with new + manual save pattern
+manual = AADRoundtripModel.new(domain_id: 'dom-004')
+manual.api_key = 'manual-secret'
+manual.save
+decrypted3 = nil
+manual.api_key.reveal { |pt| decrypted3 = pt }
+decrypted3
+#=> "manual-secret"
+
+## round-trip works with new + save + load pattern
+manual2 = AADRoundtripModel.new(domain_id: 'dom-005')
+manual2.api_key = 'reload-secret'
+manual2.save
+reloaded2 = AADRoundtripModel.load('dom-005')
+decrypted4 = nil
+reloaded2.api_key.reveal { |pt| decrypted4 = pt }
+decrypted4
+#=> "reload-secret"
+
+## AAD fields are enforced on unsaved records - unchanged field decrypts successfully
+unsaved2 = AADRoundtripEnforcementModel.new(id: 'enforce-1', email: 'stable@example.com')
+unsaved2.api_key = 'bound-secret'
+decrypted5 = nil
+unsaved2.api_key.reveal { |pt| decrypted5 = pt }
+decrypted5
+#=> "bound-secret"
+
+## AAD fields are enforced on unsaved records - changed field breaks reveal
+unsaved3 = AADRoundtripEnforcementModel.new(id: 'enforce-2', email: 'original@example.com')
+unsaved3.api_key = 'enforced-secret'
+unsaved3.email = 'tampered@example.com'
+result_enforced = begin
+  unsaved3.api_key.reveal { |pt| pt }
+  'UNEXPECTED SUCCESS'
+rescue Familia::EncryptionError
+  'Familia::EncryptionError'
+end
+result_enforced
+#=> "Familia::EncryptionError"
+
+Familia.dbclient.flushdb
+Familia.config.encryption_keys = nil
+Familia.config.current_key_version = nil

data/try/features/encrypted_fields/fast_writer_try.rb

@@ -0,0 +1,69 @@
+# try/features/encrypted_fields/fast_writer_try.rb
+#
+# frozen_string_literal: true
+
+# Tests the fast writer path (model.field_name! 'value') for encrypted fields.
+# Verifies immediate persistence, nil guard, and equivalence with normal setter.
+
+require 'base64'
+require_relative '../../support/helpers/test_helpers'
+
+test_keys = {
+  v1: Base64.strict_encode64('a' * 32),
+}
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+
+class EncryptedFastWriterModel < Familia::Horreum
+  feature :encrypted_fields
+  identifier_field :id
+  field :id
+  encrypted_field :secret
+end
+
+Familia.dbclient.flushdb
+
+## Fast write persists and can be revealed after reload
+record = EncryptedFastWriterModel.new(id: 'fast-1')
+record.save
+record.secret! 'fast-value'
+reloaded = EncryptedFastWriterModel.load('fast-1')
+decrypted = nil
+reloaded.secret.reveal { |pt| decrypted = pt }
+decrypted
+#=> "fast-value"
+
+## Fast write with nil raises ArgumentError
+record2 = EncryptedFastWriterModel.new(id: 'fast-2')
+record2.save
+result = begin
+  record2.secret! nil
+  'UNEXPECTED SUCCESS'
+rescue ArgumentError => e
+  e.class.name
+end
+result
+#=> "ArgumentError"
+
+## Fast write and normal setter produce equivalent decryptable results
+record_fast = EncryptedFastWriterModel.new(id: 'fast-3')
+record_fast.save
+record_fast.secret! 'shared-value'
+
+record_normal = EncryptedFastWriterModel.new(id: 'normal-3')
+record_normal.secret = 'shared-value'
+record_normal.save
+
+loaded_fast = EncryptedFastWriterModel.load('fast-3')
+loaded_normal = EncryptedFastWriterModel.load('normal-3')
+
+decrypted_fast = nil
+decrypted_normal = nil
+loaded_fast.secret.reveal { |pt| decrypted_fast = pt }
+loaded_normal.secret.reveal { |pt| decrypted_normal = pt }
+decrypted_fast == decrypted_normal && decrypted_fast == 'shared-value'
+#=> true
+
+Familia.dbclient.flushdb
+Familia.config.encryption_keys = nil
+Familia.config.current_key_version = nil

data/try/features/encryption/encoding_phase1_try.rb

@@ -72,16 +72,18 @@ data.algorithm
 ## 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
+# Simulate a pre-Phase-2 envelope by constructing one without encoding
+legacy_hash = {
+  algorithm: "xchacha20poly1305",
+  nonce: Base64.strict_encode64('n' * 24),
+  ciphertext: Base64.strict_encode64('c' * 32),
+  auth_tag: Base64.strict_encode64('t' * 16),
+  key_version: "v1"
+}
+data = Familia::Encryption::EncryptedData.from_json(legacy_hash)
+data.encoding
+#=> nil
 
 ## Decryption of legacy envelope (no encoding key) defaults to UTF-8
 test_keys = { v1: Base64.strict_encode64('a' * 32) }
@@ -214,7 +216,7 @@ json_with_extras = Familia::JsonSerializer.dump(parsed)
 
 data = Familia::Encryption::EncryptedData.validate!(json_with_extras)
 [data.class, data.encoding]
-#=> [Familia::Encryption::EncryptedData, nil]
+#=> [Familia::Encryption::EncryptedData, "UTF-8"]
 
 ## from_json handles Hash with string keys and unknown extras
 test_keys = { v1: Base64.strict_encode64('a' * 32) }
@@ -233,17 +235,15 @@ 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)
+# Simulate a pre-Phase-2 envelope by constructing one without encoding
+legacy_hash = {
+  algorithm: "xchacha20poly1305",
+  nonce: Base64.strict_encode64('n' * 24),
+  ciphertext: Base64.strict_encode64('c' * 32),
+  auth_tag: Base64.strict_encode64('t' * 16),
+  key_version: "v1"
+}
+data = Familia::Encryption::EncryptedData.from_json(legacy_hash)
 data.encoding
 #=> nil
 

data/try/features/encryption/encoding_phase2_try.rb

@@ -0,0 +1,108 @@
+# try/features/encryption/encoding_phase2_try.rb
+#
+# frozen_string_literal: true
+
+# Phase 2: Write encoding on encrypt -- the encrypt method now includes
+# encoding: plaintext.encoding.name in the EncryptedData envelope.
+# See: https://github.com/delano/familia/issues/229
+
+require_relative '../../support/helpers/test_helpers'
+require_relative '../../../lib/familia/encryption'
+require 'base64'
+
+## Encrypted payload includes encoding key
+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)
+
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed.key?(:encoding)
+#=> true
+
+## Encoding value matches plaintext encoding for UTF-8 string
+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)
+
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:encoding]
+#=> "UTF-8"
+
+## ISO-8859-1 encoding captured correctly
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "caf\u00e9".encode("ISO-8859-1")
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:encoding]
+#=> "ISO-8859-1"
+
+## ASCII-8BIT (binary) encoding captured
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "binary\x00\xFF".b
+
+Familia.config.encryption_keys = test_keys
+Familia.config.current_key_version = :v1
+encrypted = Familia::Encryption.encrypt(plaintext, context: context)
+
+parsed = Familia::JsonSerializer.parse(encrypted, symbolize_names: true)
+parsed[:encoding]
+#=> "ASCII-8BIT"
+
+## Round-trip preserves UTF-8 encoding
+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 == plaintext, decrypted.encoding.to_s]
+#=> [true, "UTF-8"]
+
+## Round-trip preserves non-UTF-8 encoding
+test_keys = { v1: Base64.strict_encode64('a' * 32) }
+context = "TestModel:secret_field:user123"
+plaintext = "caf\u00e9".encode("ISO-8859-1")
+
+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, decrypted.bytes == plaintext.bytes]
+#=> ["ISO-8859-1", true]
+
+## Legacy envelopes without encoding still decrypt 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)
+
+# Strip the encoding key to simulate a Phase 1 (or older) envelope
+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"]
+
+# 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.2
+  version: 2.3.3
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -364,7 +364,9 @@ files:
 - try/features/count_any_edge_cases_try.rb
 - try/features/count_any_methods_try.rb
 - try/features/dirty_tracking_try.rb
+- try/features/encrypted_fields/aad_nil_fields_try.rb
 - try/features/encrypted_fields/aad_protection_try.rb
+- try/features/encrypted_fields/aad_roundtrip_try.rb
 - try/features/encrypted_fields/concealed_string_core_try.rb
 - try/features/encrypted_fields/context_isolation_try.rb
 - try/features/encrypted_fields/encrypted_fields_core_try.rb
@@ -372,6 +374,7 @@ files:
 - try/features/encrypted_fields/encrypted_fields_no_cache_security_try.rb
 - try/features/encrypted_fields/encrypted_fields_security_try.rb
 - try/features/encrypted_fields/error_conditions_try.rb
+- try/features/encrypted_fields/fast_writer_try.rb
 - try/features/encrypted_fields/fresh_key_derivation_try.rb
 - try/features/encrypted_fields/fresh_key_try.rb
 - try/features/encrypted_fields/key_rotation_try.rb
@@ -384,6 +387,7 @@ files:
 - try/features/encryption/config_persistence_try.rb
 - try/features/encryption/core_try.rb
 - try/features/encryption/encoding_phase1_try.rb
+- try/features/encryption/encoding_phase2_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