familia 2.0.0.pre4 → 2.0.0.pre5

data/lib/familia/features/quantization.rb

@@ -1,8 +1,11 @@
 # lib/familia/features/quantization.rb
 
 module Familia::Features
-
   module Quantization
+    def self.included(base)
+      Familia.ld "[#{base}] Loaded #{self}"
+      base.extend ClassMethods
+    end
 
     module ClassMethods
       # Generates a quantized timestamp based on the given parameters.
@@ -25,9 +28,7 @@ module Familia::Features
       #
       def qstamp(quantum = nil, pattern: nil, time: nil)
         # Handle default values and array input
-        if quantum.is_a?(Array)
-          quantum, pattern = quantum
-        end
+        quantum, pattern = quantum if quantum.is_a?(Array)
 
         # Previously we erronously included `@opts.fetch(:quantize, nil)` in
         # the list of default values here, but @opts is for horreum instances
@@ -46,11 +47,6 @@ module Familia::Features
       end
     end
 
-    def self.included base
-      Familia.ld "[#{base}] Loaded #{self}"
-      base.extend ClassMethods
-    end
-
     def qstamp(quantum = nil, pattern: nil, time: nil)
       self.class.qstamp(quantum || self.class.default_expiration, pattern: pattern, time: time)
     end

data/lib/familia/features/relatable_objects.rb

@@ -9,9 +9,6 @@ module V2
     # Provides the standard core object fields and methods.
     #
     module RelatableObject
-      klass = self
-      err_klass = V2::Features::RelatableObjectError
-
       def self.included(base)
         base.class_sorted_set :relatable_objids
         base.class_hashkey :owners
@@ -82,7 +79,8 @@ module V2
 
         def owned?
           # We can only have an owner if we are relatable ourselves.
-          return false unless self.is_a?(RelatableObject)
+          return false unless is_a?(RelatableObject)
+
           # If our object identifier is present, we have an owner
           self.class.owners.key?(objid)
         end

data/lib/familia/features/safe_dump.rb

@@ -1,6 +1,5 @@
 # lib/familia/features/safe_dump.rb
 
-
 module Familia::Features
   # SafeDump is a mixin that allows models to define a list of fields that are
   # safe to dump. This is useful for serializing objects to JSON or other
@@ -54,6 +53,20 @@ module Familia::Features
     @safe_dump_fields = []
     @safe_dump_field_map = {}
 
+    def self.included(base)
+      Familia.ld "[#{self}] Enabled in #{base}"
+      base.extend ClassMethods
+
+      # Optionally define safe_dump_fields in the class to make
+      # sure we always have an array to work with.
+      base.instance_variable_set(:@safe_dump_fields, []) unless base.instance_variable_defined?(:@safe_dump_fields)
+
+      # Ditto for the field map
+      return if base.instance_variable_defined?(:@safe_dump_field_map)
+
+      base.instance_variable_set(:@safe_dump_field_map, {})
+    end
+
     module ClassMethods
       def set_safe_dump_fields(*fields)
         @safe_dump_fields = fields
@@ -100,22 +113,6 @@ module Familia::Features
       end
     end
 
-    def self.included base
-      Familia.ld "[#{self}] Enabled in #{base}"
-      base.extend ClassMethods
-
-      # Optionally define safe_dump_fields in the class to make
-      # sure we always have an array to work with.
-      unless base.instance_variable_defined?(:@safe_dump_fields)
-        base.instance_variable_set(:@safe_dump_fields, [])
-      end
-
-      # Ditto for the field map
-      unless base.instance_variable_defined?(:@safe_dump_field_map)
-        base.instance_variable_set(:@safe_dump_field_map, {})
-      end
-    end
-
     # Returns a hash of safe fields and their values. This method
     # calls the callables defined in the safe_dump_field_map with
     # the instance object as an argument.

data/lib/familia/features/transient_fields/redacted_string.rb

@@ -0,0 +1,159 @@
+# lib/familia/features/transient_fields/redacted_string.rb
+
+# RedactedString
+#
+# A secure wrapper for sensitive string values (e.g., API keys, passwords,
+# encryption keys).
+# Designed to:
+#   - Prevent accidental logging/inspection
+#   - Enable secure memory wiping
+#   - Encourage safe usage patterns
+#
+# ⚠️ IMPORTANT: This is *best-effort* protection. Ruby does not guarantee
+#              memory zeroing. GC, string sharing, and internal optimizations
+#              may leave copies in memory.
+#
+# ⚠️ INPUT SECURITY: The constructor calls .dup on the input, creating a copy,
+#                   but the original input value remains in memory uncontrolled.
+#                   The caller is responsible for securely clearing the original.
+#
+# Security Model:
+#   - The secret is *contained* from the moment it's wrapped.
+#   - Access is available via `.expose { }` for controlled use, or `.value` for direct access.
+#   - Manual `.clear!` is required when done with the value (unlike SingleUseRedactedString).
+#   - `.to_s` and `.inspect` return '[REDACTED]' to prevent leaks in logs,
+#     errors, or debugging.
+#
+# Critical Gotchas:
+#
+# 1. Ruby 3.4+ String Internals — Memory Safety Reality
+#    - Ruby uses "compact strings" and copy-on-write semantics.
+#    - Short strings (< 24 bytes on 64-bit) are *embedded* in the object
+#      (RSTRING_EMBED_LEN).
+#    - Long strings use heap-allocated buffers, but may be shared or
+#      duplicated silently.
+#    - There is *no guarantee* that GC will not copy the string before
+#      finalization.
+#
+# 2. Every .dup, .to_s, +, interpolation, or method call may create hidden
+#    copies:
+#      s = "secret"
+#      t = s.dup        # New object, same content — now two copies
+#      u = s + "123"    # New string — third copy
+#      "#{t}"           # Interpolation — fourth copy
+#    These copies are *not* controlled by RedactedString and may persist.
+#
+# 3. String Freezing & Immutability
+#    - `.freeze` prevents mutation but does *not* prevent copying.
+#    - `.replace` on a frozen string raises FrozenError — so wiping fails.
+#
+# 4. RbNaCl::Util.zero Limitations
+#    - Only works on mutable byte buffers.
+#    - May not zero embedded strings if Ruby's internal representation is
+#      immutable.
+#    - Does *not* protect against memory dumps or GC-compacted heaps.
+#
+# 5. Finalizers Are Not Guaranteed
+#    - Ruby does not promise when (or if) `ObjectSpace.define_finalizer`
+#      runs.
+#    - Never rely on finalizers for security-critical wiping.
+#
+# Best Practices:
+#   - Wrap secrets *immediately* on input (e.g., from ENV, params, DB).
+#   - Clear original input after wrapping: `secret.clear!` or `secret = nil`
+#   - Use `.expose { }` for short-lived operations — never store plaintext.
+#   - Avoid passing RedactedString to logging, serialization, or debugging
+#     tools.
+#   - Prefer `.expose { }` over any "getter" method.
+#   - Do *not* subclass String — it leaks the underlying value in regex,
+#     case, etc.
+#
+# Example:
+#   password_input = params[:password]     # Original value in memory
+#   password = RedactedString.new(password_input)
+#   password_input.clear! if password_input.respond_to?(:clear!)
+#   # or: params[:password] = nil          # Clear reference (not guaranteed)
+#
+class RedactedString
+  # Wrap a sensitive value. The input is *not* wiped — ensure it's not reused.
+  def initialize(original_value)
+    # WARNING: .dup only creates a shallow copy; the original may still exist
+    # elsewhere in memory.
+    @value = original_value.to_s.dup
+    @cleared = false
+    # Do NOT freeze — we need to mutate it in `#clear!`
+    ObjectSpace.define_finalizer(self, self.class.finalizer_proc)
+  end
+
+  # Primary API: expose the value in a block.
+  # The value remains accessible for multiple reads until manually cleared.
+  # Call clear! explicitly when done with the value.
+  #
+  # ⚠️ Security Warning: Avoid .dup, string interpolation, or other operations
+  #    that create uncontrolled copies of the sensitive value.
+  #
+  # Example:
+  #   token.expose do |plain|
+  #     # Good: use directly without copying
+  #     HTTP.post('/api', headers: { 'X-Token' => plain })
+  #     # Avoid: plain.dup, "prefix#{plain}", plain[0..-1], etc.
+  #   end
+  #   # Value is still accessible after block
+  #   token.clear! # Explicitly clear when done
+  #
+  def expose
+    raise ArgumentError, 'Block required' unless block_given?
+    raise SecurityError, 'Value already cleared' if cleared?
+
+    yield @value
+  end
+
+  # Clear the internal buffer. Safe to call multiple times.
+  #
+  # REALITY CHECK: This doesn't actually provide security in Ruby.
+  # - Ruby may have already copied the string elsewhere in memory
+  # - Garbage collection behavior is unpredictable
+  # - The original input value is still in memory somewhere
+  # - This is primarily for API consistency and preventing reuse
+  def clear!
+    return if @value.nil? || @value.frozen? || @cleared
+
+    # Simple clear - no security theater
+    @value.clear if @value.respond_to?(:clear)
+    @value = nil
+    @cleared = true
+    freeze # one and done
+  end
+
+  # Get the actual value (for convenience in less sensitive contexts)
+  # Returns the wrapped value or nil if cleared
+  #
+  # ⚠️ Security Warning: Direct access bypasses the controlled exposure pattern.
+  #    Prefer .expose { } for better security practices.
+  def value
+    raise SecurityError, 'Value already cleared' if cleared?
+
+    @value
+  end
+
+  # Always redact in logs, debugging, or string conversion
+  def to_s = '[REDACTED]'
+  def inspect = to_s
+  def cleared? = @cleared
+
+  # Returns true when it's literally the same object, otherwsie false.
+  # This prevents timing attacks where an attacker could potentially
+  # infer information about the secret value through comparison timing
+  def ==(other)
+    object_id.equal?(other.object_id) # same object
+  end
+  alias eql? ==
+
+  # All RedactedString instances have the same hash to prevent
+  # hash-based timing attacks or information leakage
+  def hash
+    RedactedString.hash
+  end
+
+  def self.finalizer_proc = proc { |id| }
+end

data/lib/familia/features/transient_fields/single_use_redacted_string.rb

@@ -0,0 +1,62 @@
+# lib/familia/features/transient_fields/single_use_redacted_string.rb
+
+require_relative 'redacted_string'
+
+# SingleUseRedactedString
+#
+# A high-security variant of RedactedString that automatically clears
+# its value after a single use via the expose method. Unlike RedactedString,
+# this provides automatic cleanup and enforces single-use semantics.
+#
+# ⚠️ IMPORTANT: Inherits all security limitations from RedactedString regarding
+#              Ruby's memory management and copy-on-write semantics.
+#
+# ⚠️ INPUT SECURITY: Like RedactedString, the constructor calls .dup on input,
+#                   creating a copy, but the original input remains in memory.
+#                   The caller is responsible for securely clearing the original.
+#
+# Key Differences from RedactedString:
+#   - Automatically clears after expose() (no manual clear! needed)
+#   - Blocks direct value() access (prevents accidental multi-use)
+#   - Raises SecurityError on second expose() attempt
+#
+# Use this for extremely sensitive values that should only be accessed
+# once, such as:
+#   - One-time passwords (OTPs)
+#   - Temporary authentication tokens
+#   - Encryption keys that should be immediately discarded
+#
+# Example:
+#   otp_input = params[:otp]               # Original value in memory
+#   otp = SingleUseRedactedString.new(otp_input)
+#   params[:otp] = nil                     # Clear reference (not guaranteed)
+#   otp.expose do |code|
+#     verify_otp(code)                     # Use directly without copying
+#   end
+#   # Value is automatically cleared after block
+#   otp.cleared? #=> true
+#
+class SingleUseRedactedString < RedactedString
+  # Override expose to automatically clear after use
+  #
+  # This ensures the value can only be accessed once via expose,
+  # providing maximum security for single-use secrets.
+  #
+  def expose
+    raise ArgumentError, 'Block required' unless block_given?
+    raise SecurityError, 'Value already cleared' if cleared?
+
+    yield @value
+  ensure
+    clear! # Automatically clear after single use
+  end
+
+  # Override value accessor to prevent direct access
+  #
+  # For single-use secrets, we don't want to allow direct value access
+  # to maintain the single-use guarantee.
+  #
+  def value
+    raise SecurityError, 'Direct value access not allowed for single-use secrets. Use #expose with a block.'
+  end
+end

data/lib/familia/features/transient_fields/transient_field_type.rb

@@ -0,0 +1,139 @@
+# lib/familia/features/transient_fields/transient_field_type.rb
+
+require 'familia/field_type'
+
+require_relative 'redacted_string'
+
+module Familia
+  # TransientFieldType - Fields that are not persisted to database
+  #
+  # Transient fields automatically wrap values in RedactedString for security
+  # and are excluded from serialization operations. They are ideal for storing
+  # sensitive data like API keys, passwords, and tokens that should not be
+  # persisted to the database.
+  #
+  # @example Using transient fields
+  #   class SecretService < Familia::Horreum
+  #     field :name                    # Regular field
+  #     transient_field :api_key       # Wrapped in RedactedString
+  #     transient_field :password      # Not persisted to database
+  #   end
+  #
+  #   service = SecretService.new
+  #   service.api_key = "sk-1234567890"
+  #   service.api_key.class           #=> RedactedString
+  #   service.to_h                    #=> {:name => nil} (no api_key)
+  #
+  class TransientFieldType < FieldType
+    # Override setter to wrap values in RedactedString
+    #
+    # Values are automatically wrapped in RedactedString objects for security.
+    # Nil values and existing RedactedString objects are handled appropriately.
+    #
+    # @param klass [Class] The class to define the method on
+    #
+    def define_setter(klass)
+      field_name = @name
+      method_name = @method_name
+
+      handle_method_conflict(klass, :"#{method_name}=") do
+        klass.define_method :"#{method_name}=" do |value|
+          wrapped = if value.nil?
+                      nil
+                    elsif value.is_a?(RedactedString)
+                      value
+                    else
+                      RedactedString.new(value)
+                    end
+          instance_variable_set(:"@#{field_name}", wrapped)
+        end
+      end
+    end
+
+    # Override getter to unwrap RedactedString values
+    #
+    # Returns the actual value from the RedactedString wrapper for
+    # convenient access, or nil if the value is nil or cleared.
+    #
+    # @param klass [Class] The class to define the method on
+    #
+    def define_getter(klass)
+      field_name = @name
+      method_name = @method_name
+
+      handle_method_conflict(klass, method_name) do
+        klass.define_method method_name do
+          wrapped = instance_variable_get(:"@#{field_name}")
+          return nil if wrapped.nil? || wrapped.cleared?
+
+          wrapped
+        end
+      end
+    end
+
+    # Override fast writer to disable it for transient fields
+    #
+    # Transient fields should not have fast writers since they're not
+    # persisted to the database.
+    #
+    # @param klass [Class] The class to define the method on
+    #
+    def define_fast_writer(_klass)
+      # No fast writer for transient fields since they're not persisted
+      Familia.ld "[TransientFieldType] Skipping fast writer for transient field: #{@name}"
+      nil
+    end
+
+    # Transient fields are not persisted to database
+    #
+    # @return [Boolean] false - transient fields are never persisted
+    #
+    def persistent?
+      false
+    end
+
+    # A convenience method that wraps `persistent?`
+    #
+    def transient?
+      !persistent?
+    end
+
+    # Category for transient fields
+    #
+    # @return [Symbol] :transient
+    #
+    def category
+      :transient
+    end
+
+    # Transient fields are not serialized to database
+    #
+    # This method should not be called since transient fields are not
+    # persisted, but we provide it for completeness.
+    #
+    # @param value [Object] The value to serialize
+    # @param record [Object] The record instance
+    # @return [nil] Always nil since transient fields are not serialized
+    #
+    def serialize(_value, _record = nil)
+      # Transient fields should never be serialized
+      Familia.ld "[TransientFieldType] WARNING: serialize called on transient field #{@name}"
+      nil
+    end
+
+    # Transient fields are not deserialized from database
+    #
+    # This method should not be called since transient fields are not
+    # persisted, but we provide it for completeness.
+    #
+    # @param value [Object] The value to deserialize
+    # @param record [Object] The record instance
+    # @return [nil] Always nil since transient fields are not stored
+    #
+    def deserialize(_value, _record = nil)
+      # Transient fields should never be deserialized
+      Familia.ld "[TransientFieldType] WARNING: deserialize called on transient field #{@name}"
+      nil
+    end
+  end
+end

data/lib/familia/features/transient_fields.rb

@@ -0,0 +1,47 @@
+# lib/familia/features/transient_fields.rb
+
+require_relative 'transient_fields/redacted_string'
+
+module Familia
+  module Features
+    # Familia::Features::TransientFields
+    #
+    # Provides secure transient fields that wrap sensitive values in RedactedString
+    # objects. These fields are excluded from serialization operations and provide
+    # automatic memory wiping for security.
+    #
+    module TransientFields
+      def self.included(base)
+        Familia.ld "[#{base}] Loaded #{self}"
+        base.extend ClassMethods
+      end
+
+      # ClassMethods
+      #
+      module ClassMethods
+        # Define a transient field that automatically wraps values in RedactedString
+        #
+        # @param name [Symbol] The field name
+        # @param as [Symbol] The method name (defaults to field name)
+        # @param kwargs [Hash] Additional field options
+        #
+        # @example Define a transient API key field
+        #   class Service < Familia::Horreum
+        #     feature :transient_fields
+        #     transient_field :api_key
+        #   end
+        #
+        def transient_field(name, as: name, **kwargs)
+          # Use the field type system - much cleaner than alias_method approach!
+          # We can now remove the transient_field method from this feature entirely
+          # since it's built into DefinitionMethods using TransientFieldType
+          require_relative 'transient_fields/transient_field_type'
+          field_type = TransientFieldType.new(name, as: as, **kwargs.merge(fast_method: false))
+          register_field_type(field_type)
+        end
+      end
+
+      Familia::Base.add_feature self, :transient_fields, depends_on: nil
+    end
+  end
+end

data/lib/familia/features.rb

@@ -2,45 +2,61 @@
 
 module Familia
 
+  FeatureDefinition = Data.define(:name, :depends_on)
+
+  # Familia::Features
+  #
   module Features
 
     @features_enabled = nil
     attr_reader :features_enabled
 
-    def feature(val = nil)
+    def feature(feature_name = nil)
       @features_enabled ||= []
 
-      # If there's a value provied check that it's a valid feature
-      if val
-        val = val.to_sym
-        raise Familia::Problem, "Unsupported feature: #{val}" unless Familia::Base.features.key?(val)
+      return features_enabled if feature_name.nil?
 
-        # If the feature is already enabled, do nothing but log about it
-        if @features_enabled.member?(val)
-          Familia.warn "[Familia::Settings] feature already enabled: #{val}"
-          return
-        end
+      # If there's a value provied check that it's a valid feature
+      feature_name = feature_name.to_sym
+      unless Familia::Base.features_available.key?(feature_name)
+        raise Familia::Problem, "Unsupported feature: #{feature_name}"
+      end
 
-        Familia.trace :FEATURE, nil, "#{self} includes #{val.inspect}", caller(1..1) if Familia.debug?
+      # If the feature is already available, do nothing but log about it
+      if features_enabled.member?(feature_name)
+        Familia.warn "[#{self.class}] feature already available: #{feature_name}"
+        return
+      end
 
-        klass = Familia::Base.features[val]
+      if Familia.debug?
+        Familia.trace :FEATURE, nil, "#{self} includes #{feature_name.inspect}", caller(1..1)
+      end
 
-        # Extend the Familia::Base subclass (e.g. Customer) with the feature module
-        include klass
+      # Add it to the list available features_enabled for Familia::Base classes.
+      features_enabled << feature_name
 
-        # NOTE: We may also want to extend Familia::DataType here so that we can
-        # call safe_dump on relations fields (e.g. list, set, zset, hashkey). Or
-        # maybe that only makes sense for hashk/object relations.
-        #
-        # We'd need to avoid it getting included multiple times (i.e. once for each
-        # Familia::Horreum subclass that includes the feature).
+      klass = Familia::Base.features_available[feature_name]
 
-        # Now that the feature is loaded successfully, add it to the list
-        # enabled features for Familia::Base classes.
-        @features_enabled << val
+      # Validate dependencies
+      feature_def = Familia::Base.feature_definitions[feature_name]
+      if feature_def&.depends_on&.any?
+        missing = feature_def.depends_on - features_enabled
+        raise Familia::Problem, "#{feature_name} requires: #{missing.join(', ')}" if missing.any?
       end
 
-      features_enabled
+      # Extend the Familia::Base subclass (e.g. Customer) with the feature module
+      include klass
+
+      # NOTE: Do we want to extend Familia::DataType here? That would make it
+      # possible to call safe_dump on relations fields (e.g. list, zset, hashkey).
+      #
+      # The challenge is that DataType classes (List, Set, etc.) are shared across
+      # all Horreum models. If Customer extends DataType with safe_dump, then
+      # Session's lists would also have it. Not ideal. If that's all we wanted
+      # then we can do that by looping through every DataType class here.
+      #
+      # We'd need to extend the DataType instances for each Horreum subclass. That
+      # avoids it getting included multiple times per DataType
     end
 
   end