familia 2.0.0.pre4 → 2.0.0.pre6

data/lib/familia/features/expiration.rb

@@ -1,100 +1,130 @@
 # lib/familia/features/expiration.rb
 
+module Familia
+  module Features
+    # Famnilia::Features::Expiration
+    #
+    module Expiration
+      @default_expiration = nil
 
-module Familia::Features
+      def self.included(base)
+        Familia.trace :LOADED!, nil, self, caller(1..1) if Familia.debug?
+        base.extend ClassMethods
 
-  module Expiration
-    @default_expiration = nil
+        # Optionally define default_expiration in the class to make
+        # sure we always have an array to work with.
+        return if base.instance_variable_defined?(:@default_expiration)
 
-    module ClassMethods
+        base.instance_variable_set(:@default_expiration, @default_expiration) # set above
+      end
 
-      attr_writer :default_expiration
+      # ClassMethods
+      #
+      module ClassMethods
+        attr_writer :default_expiration
 
-      def default_expiration(v = nil)
-        @default_expiration = v.to_f unless v.nil?
-        @default_expiration || parent&.default_expiration || Familia.default_expiration
+        def default_expiration(num = nil)
+          @default_expiration = num.to_f unless num.nil?
+          @default_expiration || parent&.default_expiration || Familia.default_expiration
+        end
       end
 
-    end
-
-    def self.included base
-      Familia.ld "[#{base}] Loaded #{self}"
-      base.extend ClassMethods
+      def default_expiration=(num)
+        @default_expiration = num.to_f
+      end
 
-      # Optionally define default_expiration in the class to make
-      # sure we always have an array to work with.
-      unless base.instance_variable_defined?(:@default_expiration)
-        base.instance_variable_set(:@default_expiration, @default_expiration) # set above
+      def default_expiration
+        @default_expiration || self.class.default_expiration
       end
-    end
 
-    def default_expiration=(v)
-      @default_expiration = v.to_f
-    end
+      # Sets an expiration time for the Database data associated with this object.
+      #
+      # This method allows setting a Time To Live (TTL) for the data in Redis,
+      # after which it will be automatically removed.
+      #
+      # @param default_expiration [Integer, nil] The Time To Live in seconds. If nil, the default
+      #   TTL will be used.
+      #
+      # @return [Boolean] Returns true if the expiration was set successfully,
+      #   false otherwise.
+      #
+      # @example Setting an expiration of one day
+      #   object.update_expiration(default_expiration: 86400)
+      #
+      # @note If Default expiration is set to zero, the expiration will be removed, making the
+      #   data persist indefinitely.
+      #
+      # @raise [Familia::Problem] Raises an error if the default expiration is not a non-negative
+      #   integer.
+      #
+      def update_expiration(default_expiration: nil)
+        default_expiration ||= self.default_expiration
+
+        if self.class.has_relations?
+          Familia.ld "[update_expiration] #{self.class} has relations: #{self.class.related_fields.keys}"
+          self.class.related_fields.each do |name, definition|
+            next if definition.opts[:default_expiration].nil?
+
+            obj = send(name)
+            Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{default_expiration}"
+            obj.update_expiration(default_expiration: default_expiration)
+          end
+        end
+
+        # It's important to raise exceptions here and not just log warnings. We
+        # don't want to silently fail at setting expirations and cause data
+        # retention issues (e.g. not removed in a timely fashion).
+        #
+        # For the same reason, we don't want to default to 0 bc there's not a
+        # good reason for the default_expiration to not be set in the first place. If the
+        # class doesn't have a default_expiration, the default comes from
+        # Familia.default_expiration (which is 0, aka no-op/skip/do nothing).
+        unless default_expiration.is_a?(Numeric)
+          raise Familia::Problem, "Default expiration must be a number (#{default_expiration.class} in #{self.class})"
+        end
 
-    def default_expiration
-      @default_expiration || self.class.default_expiration
+        # If zero, simply skips setting an expiry for this key. If we were to set
+        # 0 the database would drop the key immediately.
+        return Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})" if default_expiration.zero?
+
+        Familia.ld "[update_expiration] Expires #{dbkey} in #{default_expiration} seconds"
+
+        # Redis' EXPIRE command returns 1 if the timeout was set, 0 if key does
+        # not exist or the timeout could not be set. Via redis-rb here, it's
+        # a bool.
+        expire(default_expiration)
+      end
+
+      Familia::Base.add_feature self, :expiration
     end
+  end
+end
 
-    # Sets an expiration time for the Database data associated with this object.
-    #
-    # This method allows setting a Time To Live (TTL) for the data in Redis,
-    # after which it will be automatically removed.
-    #
-    # @param default_expiration [Integer, nil] The Time To Live in seconds. If nil, the default
-    #   TTL will be used.
+module Familia
+  # Add a default update_expiration method for all classes that include
+  # Familia::Base. Since expiration is a core feature, we can confidently
+  # call `horreum_instance.update_expiration` without defensive programming
+  # even when expiration is not enabled for the horreum_instance class.
+  module Base
+    # Base implementation of update_expiration that maintains API compatibility
+    # with the :expiration feature's implementation.
     #
-    # @return [Boolean] Returns true if the expiration was set successfully,
-    #   false otherwise.
+    # This is a no-op implementation that gets overridden by features like
+    # :expiration. It accepts an optional default_expiration parameter to maintain interface
+    # compatibility with the overriding implementations.
     #
-    # @example Setting an expiration of one day
-    #   object.update_expiration(default_expiration: 86400)
+    # @param default_expiration [Integer, nil] Time To Live in seconds
+    # @return [nil] Always returns nil
     #
-    # @note If Default expiration is set to zero, the expiration will be removed, making the
-    #   data persist indefinitely.
-    #
-    # @raise [Familia::Problem] Raises an error if the default expiration is not a non-negative
-    #   integer.
+    # @note This is a no-op implementation. Classes that need expiration
+    #       functionality should include the :expiration feature.
     #
     def update_expiration(default_expiration: nil)
-      default_expiration ||= self.default_expiration
-
-      if self.class.has_relations?
-        Familia.ld "[update_expiration] #{self.class} has relations: #{self.class.related_fields.keys}"
-        self.class.related_fields.each do |name, definition|
-          next if definition.opts[:default_expiration].nil?
-          obj = send(name)
-          Familia.ld "[update_expiration] Updating expiration for #{name} (#{obj.dbkey}) to #{default_expiration}"
-          obj.update_expiration(default_expiration: default_expiration)
-        end
-      end
-
-      # It's important to raise exceptions here and not just log warnings. We
-      # don't want to silently fail at setting expirations and cause data
-      # retention issues (e.g. not removed in a timely fashion).
-      #
-      # For the same reason, we don't want to default to 0 bc there's not a
-      # good reason for the default_expiration to not be set in the first place. If the
-      # class doesn't have a default_expiration, the default comes from Familia.default_expiration (which
-      # is 0).
-      unless default_expiration.is_a?(Numeric)
-        raise Familia::Problem, "Default expiration must be a number (#{default_expiration.class} in #{self.class})"
-      end
-
-      if default_expiration.zero?
-        return Familia.ld "[update_expiration] No expiration for #{self.class} (#{dbkey})"
-      end
-
-      Familia.ld "[update_expiration] Expires #{dbkey} in #{default_expiration} seconds"
-
-      # Redis' EXPIRE command returns 1 if the timeout was set, 0 if key does
-      # not exist or the timeout could not be set. Via redis-rb here, it's
-      # a bool.
-      expire(default_expiration)
+      Familia.ld <<~LOG
+        [update_expiration] Feature not enabled for #{self.class}.
+        Key: #{dbkey} Arg: #{default_expiration} (caller: #{caller(1..1)})
+      LOG
+      nil
     end
-    extend ClassMethods
-
-    Familia::Base.add_feature self, :expiration
   end
-
 end

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.trace :included, base, self, caller(1..1) if Familia.debug?
+      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.trace :LOADED, self, base, caller(1..1) if Familia.debug?
+      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, otherwise 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