couchbase-orm 2.0.5 → 2.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f52bb1912f8b6e060c4daffc1b9ef0bd0922b7dc4035c774743839ea54abcab4
-  data.tar.gz: ba9cf86a6014a14a671c9a209f2c8ba58bd2acd8b1d54720af8c9237c4812cbc
+  metadata.gz: 8c4e1b3c58f8a68383f5e24c548e93d5a7d8ed5fd178ec932f856e64486dbe44
+  data.tar.gz: 2bc1a8a24e83a0267a114995587254e760ccc81f779382d40a7415cf832f4b6b
 SHA512:
-  metadata.gz: 1c3dc0311028fb1edf5612632f9b8bbadd89bd540416f08989331075ee052d915f58481b2879b15f946810c0e4c735b8130d994c0f796c9cae4d50bf0a0e50ea
-  data.tar.gz: '013937e07a05ec6386be0c65ef72dba41c67aa902680d5cb5f0bd936eaf592a1d5b024d7d4c6bcd06d5bc7195bb4bb44f8afc99beb010288f1be9807e117e207'
+  metadata.gz: 0164b5c46981c5303fcc7e5820918cafb073d788027aa7e5492d321073cdd1d17df8a6491ba6f1fb91ed6f2ba28ed1f03a3d7ac62da3e4905034c2b1950ce10b
+  data.tar.gz: bf5feabaaa6c4c8bec79f5ef1906519ee9da5861ecce359d25055ca806fcbcd781f6c291a98393a79ef4a17f0a85e0000536abaed6185dfcbefaab82d62d6c9d

data/README.md

@@ -113,8 +113,11 @@ The following types have been tested :
 - :datetime (stored as iso8601, use precision: n to store more decimal precision)
 - :timestamp (stored as integer)
 - :encrypted
-  - see <https://docs.couchbase.com/couchbase-lite/current/c/field-level-encryption.html>
-  - You must store a string that can be encoded in json (not binary data), use base64 if needed
+  - Provides storage format compatible with Couchbase Lite field-level encryption
+  - See <https://docs.couchbase.com/couchbase-lite/current/c/field-level-encryption.html>
+  - **Important**: CouchbaseOrm does not perform encryption/decryption - your application must encrypt data before storing it
+  - Values must be Base64-encoded strings containing pre-encrypted ciphertext
+  - See the [encryption documentation](https://couchbase-ruby-orm.com/docs/tutorial-ruby-couchbase-orm/encryption) for details
 - :array (see below)
 - :nested (see below)
 

data/couchbase-orm.gemspec

@@ -23,6 +23,7 @@ Gem::Specification.new do |gem|
   gem.add_runtime_dependency     'couchbase',    '>= 3.4.2'
   gem.add_runtime_dependency     'radix',        '~> 2.2' # converting numbers to and from any base
   gem.add_runtime_dependency     'json-schema',  '>= 3' # validating JSON against a schema
+  gem.add_runtime_dependency     'logger',       '~> 1.6' # Required from Ruby 3.5.0+
 
   gem.add_development_dependency 'rake', '~> 12.2'
   gem.add_development_dependency 'rspec', '~> 3.7'

data/docusaurus/docs/tutorial-ruby-couchbase-orm/11-encryption.md

@@ -1,13 +1,13 @@
 # Encryption
 
-CouchbaseOrm provides built-in support for encrypting sensitive data stored in your Couchbase documents. Encryption allows you to protect confidential information, such as personal data or financial details, by encrypting the values before storing them in the database and decrypting them when retrieving the data.
+CouchbaseOrm provides built-in support for storing encrypted data in your Couchbase documents using a structured format. The `:encrypted` type provides a standardized storage format compatible with Couchbase Lite's field-level encryption, but **does not perform encryption/decryption itself**. Your application is responsible for encrypting data before storing it and decrypting it after retrieval.
 
 ## 11.1. Encrypted Attributes
 
 To mark an attribute as encrypted, you can use the `:encrypted` type when defining the attribute in your model.
 
 ```ruby
-# Define the Bank model with an encrypted attribute
+# Define the Bank model with encrypted attributes
 class Bank < CouchbaseOrm::Base
   attribute :name, :string
   attribute :account_number, :encrypted
@@ -15,7 +15,7 @@ class Bank < CouchbaseOrm::Base
 end
 ```
 
-In this example, the `account_number` and `routing_number` attributes are marked as encrypted. By default, CouchbaseOrm uses the default `CB_MOBILE_CUSTOM` encryption algorithm for encrypting the values. You can specify a different encryption algorithm by providing the `alg` option.
+In this example, the `account_number` and `routing_number` attributes are marked as encrypted. The `alg` option specifies the encryption algorithm identifier that will be stored in the document metadata (default is `"CB_MOBILE_CUSTOM"`). This identifier is for documentation purposes and Couchbase Lite compatibility - CouchbaseOrm does not use it for actual encryption.
 
 ```plaintext
 {
@@ -32,83 +32,171 @@ In this example, the `account_number` and `routing_number` attributes are marked
 }
 ```
 
-When a document is saved, CouchbaseOrm stores the encrypted values in the document with a prefix of `encrypted$`. The encrypted values are stored as JSON objects containing the encryption algorithm (`alg`) and the ciphertext (`ciphertext`) of the encrypted value.
+When a document is saved, CouchbaseOrm stores encrypted attributes in the document with a prefix of `encrypted$`. The values are stored as JSON objects containing the encryption algorithm identifier (`alg`) and the ciphertext (`ciphertext`).
 
-You can assign values to encrypted attributes just like any other attribute.
+**Important**: You must provide **pre-encrypted** values to encrypted attributes. CouchbaseOrm stores these values as-is in the `ciphertext` field without performing any encryption.
 
 ```ruby
-bank = Bank.new(name: 'My Bank', account_number: '123456789', routing_number: '987654321')
+# You must encrypt the data BEFORE assigning it to the attribute
+require 'base64'
+
+# Assuming you have an encryption method (e.g., AES, Tanker, etc.)
+encrypted_account = MyEncryptor.encrypt('123456789')
+encrypted_routing = MyEncryptor.encrypt('987654321')
+
+# Values must be Base64-encoded strings
+bank = Bank.new(
+  name: 'My Bank',
+  account_number: Base64.strict_encode64(encrypted_account),
+  routing_number: Base64.strict_encode64(encrypted_routing)
+)
 ```
 
-When the document is saved, CouchbaseOrm encrypts the value of `ssn` using the configured encryption key.
+## 11.2. Complete Example with Encryption
 
-## 11.2. Encryption Process 
+Here's a complete example showing how to handle encryption in your application:
 
 ```ruby
 require 'base64'
-require 'logger'
+require 'openssl'
+
+# Example encryption helper (you should use a proper encryption library)
+class SimpleEncryptor
+  def self.encrypt(plaintext)
+    # This is a simplified example - use a proper encryption library in production
+    cipher = OpenSSL::Cipher.new('AES-256-CBC')
+    cipher.encrypt
+    cipher.key = ENV['ENCRYPTION_KEY'] # Store securely, never commit to git
+    cipher.iv = iv = cipher.random_iv
+
+    encrypted = cipher.update(plaintext) + cipher.final
+    # Prepend IV for decryption (in real implementation, handle this properly)
+    iv + encrypted
+  end
 
-Bank.all.each(&:destroy)
+  def self.decrypt(ciphertext_with_iv)
+    cipher = OpenSSL::Cipher.new('AES-256-CBC')
+    cipher.decrypt
+    cipher.key = ENV['ENCRYPTION_KEY']
 
-# Method to print serialized attributes
-def expect_serialized_attributes(bank)
-  serialized_attrs = bank.send(:serialized_attributes)
-  serialized_attrs.each do |key, value|
-    puts "#{key}: #{value}"
-  end
-  json_attrs = JSON.parse(bank.to_json)
-  json_attrs.each do |key, value|
-    puts "#{key}: #{value}"
-  end
-  bank.as_json.each do |key, value|
-    puts "#{key}: #{value}"
+    # Extract IV and ciphertext
+    iv = ciphertext_with_iv[0..15]
+    ciphertext = ciphertext_with_iv[16..]
+
+    cipher.iv = iv
+    cipher.update(ciphertext) + cipher.final
   end
 end
 
-# Create a new bank record with encrypted attributes
+# Create a bank record with encrypted attributes
+plaintext_account = "123456789"
+plaintext_routing = "987654321"
+
+# 1. Encrypt the sensitive data
+encrypted_account = SimpleEncryptor.encrypt(plaintext_account)
+encrypted_routing = SimpleEncryptor.encrypt(plaintext_routing)
+
+# 2. Encode as Base64 for storage
 bank = Bank.new(
   name: "Test Bank",
-  account_number: Base64.strict_encode64("123456789"),
-  routing_number: Base64.strict_encode64("987654321")
+  account_number: Base64.strict_encode64(encrypted_account),
+  routing_number: Base64.strict_encode64(encrypted_routing)
 )
 
-# Print serialized attributes before saving
-expect_serialized_attributes(bank)
-
-# Save the bank record to Couchbase
+# 3. Save to Couchbase
 bank.save!
 
-# Reload the bank record from Couchbase
-bank.reload
+# 4. Retrieve and decrypt
+found_bank = Bank.find(bank.id)
 
-# Print serialized attributes after reloading
-expect_serialized_attributes(bank)
+# 5. Decode Base64 and decrypt
+account_encrypted = Base64.strict_decode64(found_bank.account_number)
+routing_encrypted = Base64.strict_decode64(found_bank.routing_number)
 
-# Find the bank record by ID
-found_bank = Bank.find(bank.id)
+decrypted_account = SimpleEncryptor.decrypt(account_encrypted)
+decrypted_routing = SimpleEncryptor.decrypt(routing_encrypted)
 
-# Print serialized attributes after finding
-expect_serialized_attributes(found_bank)
+puts "Decrypted account: #{decrypted_account}"  # => "123456789"
+puts "Decrypted routing: #{decrypted_routing}"  # => "987654321"
 ```
 
-## 11.3. Encryption and Decryption Process
+## 11.3. Storage Format
+
+CouchbaseOrm handles the storage format for encrypted attributes but does not perform encryption/decryption. Here's what happens:
 
-When an encrypted attribute is assigned a value, CouchbaseOrm encrypts the value using the configured encryption key and algorithm. The encrypted value is then stored in the Couchbase document.
+**When saving:**
+1. You assign a Base64-encoded ciphertext to the encrypted attribute
+2. CouchbaseOrm wraps it in the `encrypted$` format with `alg` and `ciphertext` fields
+3. The document is stored in Couchbase with this structure
 
-When retrieving a document with encrypted attributes, CouchbaseOrm automatically decrypts the encrypted values using the same encryption key and algorithm. The decrypted values are then accessible through the model's attributes.
+**When loading:**
+1. CouchbaseOrm reads the document from Couchbase
+2. It unwraps the `encrypted$` format and extracts the `ciphertext` value
+3. The Base64-encoded ciphertext is assigned to the attribute
+4. Your application must decode and decrypt the value
 
-It's important to keep the encryption key secure and protect it from unauthorized access. If the encryption key is compromised, the encrypted data can be decrypted by anyone who obtains the key.
+**Key Points:**
+- CouchbaseOrm does **not** require or use any encryption key
+- The `alg` field is purely informational (for compatibility with Couchbase Lite)
+- All actual encryption/decryption is your application's responsibility
+- Values must be valid Base64-encoded strings
 
 ## 11.4. Considerations and Best Practices
 
-When using encryption in CouchbaseOrm, consider the following best practices:
+When using encrypted attributes in CouchbaseOrm, consider the following best practices:
+
+### Security
+- **Encryption is your responsibility**: CouchbaseOrm only provides the storage format. Choose a robust encryption library (e.g., `rbnacl`, `openssl`, or a service like AWS KMS)
+- **Key management**: Store encryption keys securely using environment variables, secret managers (AWS Secrets Manager, HashiCorp Vault), or key management services
+- **Never commit keys**: Keep encryption keys out of version control systems
+- **Key rotation**: Implement a key rotation strategy and maintain the ability to decrypt data encrypted with old keys
+- **Use authenticated encryption**: Prefer AEAD modes (like AES-GCM) that provide both confidentiality and integrity
+
+### Performance and Querying
+- **Cannot query encrypted fields**: Encrypted attributes cannot be used in WHERE clauses or indexed effectively
+- **Consider searchable encryption**: If you need to search encrypted data, investigate specialized solutions like searchable encryption schemes or external encrypted search indexes
+- **Selective encryption**: Only encrypt truly sensitive fields to minimize performance overhead
+
+### Implementation Patterns
+- **Wrap in accessors**: Create getter/setter methods that automatically handle encryption/decryption:
+  ```ruby
+  class Bank < CouchbaseOrm::Base
+    attribute :account_number, :encrypted
+
+    def account_number=(plaintext)
+      encrypted = MyEncryptor.encrypt(plaintext)
+      super(Base64.strict_encode64(encrypted))
+    end
+
+    def account_number
+      encrypted = Base64.strict_decode64(super)
+      MyEncryptor.decrypt(encrypted)
+    end
+  end
+  ```
+
+- **Separate concerns**: Consider using a concern or module to encapsulate encryption logic:
+  ```ruby
+  module EncryptedAttributes
+    def encrypted_attribute(name)
+      define_method("#{name}=") do |plaintext|
+        encrypted = MyEncryptor.encrypt(plaintext)
+        super(Base64.strict_encode64(encrypted))
+      end
+
+      define_method(name) do
+        encrypted = Base64.strict_decode64(super())
+        MyEncryptor.decrypt(encrypted)
+      end
+    end
+  end
+  ```
 
-- Keep the encryption key secure and protect it from unauthorized access. Store the key securely and avoid committing it to version control systems.
-- Use strong and unique encryption keys for each environment (development, staging, production) to prevent cross-environment access to encrypted data.
-- Be cautious when querying encrypted attributes as it may impact performance. Consider indexing encrypted attributes separately if frequent querying is required.
-- If you need to search or query encrypted data frequently, consider using a separate encrypted search index or a dedicated encryption service.
-- Ensure that the encryption key is properly rotated and managed. If the encryption key is compromised, you should generate a new key and re-encrypt the affected data.
+### Compatibility
+- The `encrypted$` format is compatible with Couchbase Lite's field-level encryption
+- The `alg` field helps document which encryption algorithm was used, aiding in key rotation and auditing
+- Ensure your encryption implementation is compatible across all platforms that access the data (web, mobile, etc.)
 
-Encryption is a powerful tool for protecting sensitive data, but it should be used judiciously. Encrypting every attribute in your model may not be necessary or practical. Focus on encrypting the most sensitive and confidential data while balancing the trade-offs between security and performance.
+Encryption is a powerful tool for protecting sensitive data, but it should be used judiciously. Focus on encrypting the most sensitive and confidential data while balancing the trade-offs between security, performance, and functionality.
 
 In the next section, we'll explore logging in CouchbaseOrm and how you can configure and customize logging to monitor and debug your application.

data/lib/couchbase-orm/base.rb

@@ -46,6 +46,7 @@ module CouchbaseOrm
         include Encrypt
 
         extend Enum
+        extend IgnoredProperties
 
         define_model_callbacks :initialize, :only => :after
 
@@ -134,7 +135,6 @@ module CouchbaseOrm
         extend EnsureUnique
         extend HasMany
         extend Index
-        extend IgnoredProperties
         extend JsonSchema::Validation
         extend PropertiesAlwaysExistsInDocument
 

data/lib/couchbase-orm/types/nested.rb

@@ -26,14 +26,29 @@ module CouchbaseOrm
             def cast(value)
                 return nil if value.nil?
                 return value if value.is_a?(@model_class)
-                return @model_class.new(value) if value.is_a?(Hash)
+
+                if value.is_a?(Hash)
+                    # Filter out ignored properties before creating the nested instance
+                    # Optimization: only call .except if there are properties to ignore
+                    ignored = @model_class.ignored_properties
+                    filtered_value = ignored.empty? ? value : value.except(*ignored)
+                    return @model_class.new(filtered_value)
+                end
 
                 raise ArgumentError, "Nested: #{value.inspect} (#{value.class}) is not supported for cast"
             end
         
             def serialize(value)
                 return nil if value.nil?
-                value = @model_class.new(value) if value.is_a?(Hash)
+
+                if value.is_a?(Hash)
+                    # Filter out ignored properties before creating the nested instance
+                    # Optimization: only call .except if there are properties to ignore
+                    ignored = @model_class.ignored_properties
+                    filtered_value = ignored.empty? ? value : value.except(*ignored)
+                    value = @model_class.new(filtered_value)
+                end
+
                 return value.send(:serialized_attributes) if value.is_a?(@model_class)
 
                 raise ArgumentError, "Nested: #{value.inspect} (#{value.class}) is not supported for serialization"

data/lib/couchbase-orm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true, encoding: ASCII-8BIT
 
 module CouchbaseOrm
-  VERSION = '2.0.5'
+  VERSION = '2.0.6'
 end

data/spec/type_nested_spec.rb

@@ -188,4 +188,64 @@ describe CouchbaseOrm::Types::Nested do
             expect(obj.child.child.errors[:name]).to eq ["can't be blank"]
         end
     end
+
+    describe "Ignored Properties" do
+        class SubTypeWithIgnoredProperties < CouchbaseOrm::NestedDocument
+            self.ignored_properties = [:deprecated_property]
+            attribute :name, :string
+            attribute :value, :string
+        end
+
+        class ParentWithNestedIgnoredProperties < CouchbaseOrm::Base
+            self.ignored_properties = [:deprecated_at_root]
+            attribute :title, :string
+            attribute :nested, :nested, type: SubTypeWithIgnoredProperties
+        end
+
+        it "should ignore deprecated properties in nested documents on reload" do
+            # Create and save a parent with nested document
+            parent = ParentWithNestedIgnoredProperties.new
+            parent.title = "Test Parent"
+            parent.nested = SubTypeWithIgnoredProperties.new(name: "Nested", value: "Valid")
+            parent.save!
+
+            # Manually add a deprecated property to the nested document in the database
+            doc_id = parent.id
+            raw_doc = ParentWithNestedIgnoredProperties.bucket.default_collection.get(doc_id).content
+            raw_doc["nested"]["deprecated_property"] = "This should be ignored"
+            ParentWithNestedIgnoredProperties.bucket.default_collection.replace(doc_id, raw_doc)
+
+            # Reload the parent
+            parent.reload
+
+            # The deprecated property should NOT be present in the nested document
+            expect(parent.nested.attributes.keys).not_to include("deprecated_property")
+            expect(parent.nested.name).to eq("Nested")
+            expect(parent.nested.value).to eq("Valid")
+        end
+
+        it "should ignore deprecated properties in deeply nested documents" do
+            # Create a parent with nested documents that have a child
+            parent = ParentWithNestedIgnoredProperties.new
+            parent.title = "Test Parent"
+            parent.nested = SubTypeWithIgnoredProperties.new(name: "Parent Nested", value: "Parent Value")
+            parent.save!
+
+            # Manually add deprecated properties at multiple levels
+            doc_id = parent.id
+            raw_doc = ParentWithNestedIgnoredProperties.bucket.default_collection.get(doc_id).content
+            raw_doc["deprecated_at_root"] = "Should be ignored at root level"
+            raw_doc["nested"]["deprecated_property"] = "Should be ignored in nested"
+            ParentWithNestedIgnoredProperties.bucket.default_collection.replace(doc_id, raw_doc)
+
+            # Reload the parent
+            parent.reload
+
+            # Deprecated properties should not be present at any level
+            expect(parent.attributes.keys).not_to include("deprecated_at_root")
+            expect(parent.nested.attributes.keys).not_to include("deprecated_property")
+            expect(parent.nested.name).to eq("Parent Nested")
+            expect(parent.nested.value).to eq("Parent Value")
+        end
+    end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: couchbase-orm
 version: !ruby/object:Gem::Version
-  version: 2.0.5
+  version: 2.0.6
 platform: ruby
 authors:
 - Stephen von Takach
@@ -68,6 +68,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '3'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement