permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/masking_sync.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'securerandom'
+require_relative 'database_reach'
 
 module PermissionForge
   # Carries auto-applied masking (MaskedModels) to every process. The
@@ -33,7 +34,17 @@ module PermissionForge
   # Either way a process that has not synced (its boot could not reach the
   # database, a model could not be masked) applies at its next executor
   # run, and a development code reload applies again (`to_prepare`).
-  # The store must be shared (not :memory or :null).
+  #
+  # The token needs a shared store. One that keeps nothing (:null, a
+  # :null_store) is never asked for it: the token would read as lost on
+  # every check. One that lives in each process (:memory, a :memory_store)
+  # reaches no other process. In development, where Rails' default store is
+  # one of these, each executor run re-reads the Resource names from the
+  # database instead, at most every DATABASE_RECHECK seconds (database
+  # recheck): a model named from a console, `bin/rails runner` or a rake task
+  # is masked in the server at its next request. Other environments get no
+  # such query (CacheWarnings warns at boot): a process then masks a model
+  # first named in another one only after a restart.
   #
   # @api private
   module MaskingSync
@@ -45,6 +56,21 @@ module PermissionForge
     # Seconds the store is left alone after it did not answer.
     RETRY_PAUSE = 30
 
+    # Development with a store that cannot carry the token: seconds between
+    # two reads of the Resource names (one query each).
+    DATABASE_RECHECK = 2
+
+    # The cause named by the token warning when the store raised nothing: a
+    # read of the token, and a read right after writing one, came back empty.
+    SILENT_STORE = ' (it did not answer, or a read right after a write came back empty: the store is down, full, ' \
+                   'or evicts the key at once)'
+
+    # check!'s warning when a sync raised: a SECURITY one, the process fails open until the next sync.
+    SYNC_FAILED = 'Auto-applied masking could not be synced: a model named in another process may stay unmasked here until the next sync'
+    # The boot step's warning when a model could not be masked (boot!).
+    INCOMPLETE_AT_BOOT = 'Auto-applied masking is not complete at boot (see the warnings above, or the Resource ' \
+                         'table cannot be read): it is tried again at each request or job.'
+
     # One sync (or apply) at a time; one probe of a failing store at a time.
     SYNC_LOCK = Mutex.new
     PROBE_LOCK = Mutex.new
@@ -57,20 +83,34 @@ module PermissionForge
     @announcement_owed = false
     @failing_until = nil
     @failing_store = nil
+    @recheck_after = nil
 
     class << self
       # Executor `to_run`. Row-driven: one store read; applies when another
       # process named a model since this one last synced. The store is not
-      # read while it is failing (RETRY_PAUSE), nor at all for lists: the
-      # token is then unknown (nil), and only a process that has not synced
-      # applies (from the database). Never raises.
+      # read while it is failing (RETRY_PAUSE), nor at all for lists or a
+      # store that keeps nothing: the token is then unknown (nil), and only
+      # a process that has not synced applies (from the database). In
+      # development with a store that cannot carry the token, the Resource
+      # names instead (database_recheck?). Never raises.
+      #
+      # A process that has not synced (its boot could not use the database)
+      # asks the database first (database_unavailable?: one table check per
+      # run until it syncs, none after): while it cannot
+      # read the Resource table, nothing can be masked from it, and the store
+      # is not read — its own database may be the one that is not there
+      # (Solid Cache in a `rails new` app whose production database is not
+      # configured raised the same ArgumentError, logged as a SECURITY store
+      # failure on every runner).
       def check!
         return unless MaskedModels.enabled?
+        return recheck_database if database_recheck?
+        return if database_unavailable?
 
-        token = MaskedModels.row_driven? ? answered_token : nil
+        token = token_in_store? ? answered_token : nil
         sync(token) if changed?(token)
       rescue StandardError => e
-        Rails.logger&.error("[PermissionForge] auto-applied masking could not be synced — #{e.class}: #{e.message}")
+        Warnings.emit(:masking_sync_failed, "#{SYNC_FAILED} (#{e.class}: #{e.message}).", severity: :security)
       end
 
       # After a Resource row naming `name` has been created or renamed and
@@ -85,9 +125,9 @@ module PermissionForge
       #   (asked only when it decides something)
       def named!(name)
         return unless MaskedModels.enabled?
-        return apply!(name) unless MaskedModels.row_driven?
+        return apply!(name) unless token_in_store?
 
-        masked_here?(name) && yield ? apply!(name) : announce!(name)
+        MaskedModels.masked?(name) && yield ? apply!(name) : announce!(name)
       end
 
       # The boot step: applies to every selected model and syncs with the
@@ -98,11 +138,8 @@ module PermissionForge
       #
       # @return [Boolean] whether every selected model is masked
       def boot!
-        done = sync(MaskedModels.row_driven? ? current_token : nil, always: true)
-        unless done
-          Rails.logger&.warn('[PermissionForge] Auto-applied masking is not complete at boot (see the warnings ' \
-                             'above, or the Resource table cannot be read): it is tried again at each request or job.')
-        end
+        done = sync(token_in_store? ? current_token : nil, always: true)
+        Warnings.emit(:masking_sync_incomplete_at_boot, INCOMPLETE_AT_BOOT, severity: :security) unless done
         done
       end
 
@@ -123,6 +160,7 @@ module PermissionForge
         SYNC_LOCK.synchronize { @token = UNSYNCED }
         @announcement_owed = false
         @failing_until = nil
+        @recheck_after = nil
         MaskedModels.reset_warnings!
       end
 
@@ -138,8 +176,43 @@ module PermissionForge
         !until_time.nil? && now < until_time && PermissionForge.cache.equal?(@failing_store)
       end
 
+      # Whether this process learns of a model named in another one from the
+      # Resource rows (development, a row-driven setting, a store that cannot
+      # carry the token: it keeps nothing or lives in each process). Asks
+      # nothing outside development.
+      #
+      # @return [Boolean]
+      def database_recheck?
+        return false unless Rails.env.development? && MaskedModels.row_driven?
+
+        cache = PermissionForge.cache
+        cache.process_local? || !cache.keeps_entries?
+      end
+
       private
 
+      # A process that has not synced, whose Resource table cannot be read
+      # (DatabaseReach: unreachable, not configured, not migrated).
+      def database_unavailable? = !synced? && !DatabaseReach.table_exists?(PermissionForge::Resource)
+
+      # Whether the token is read and written: a row-driven setting and a
+      # store that keeps entries, outside a database recheck.
+      #
+      # @return [Boolean]
+      def token_in_store?
+        MaskedModels.row_driven? && PermissionForge.cache.keeps_entries? && !database_recheck?
+      end
+
+      # The database recheck: every model the Resource rows name, at most
+      # every DATABASE_RECHECK seconds — and at each run until it succeeded
+      # once (a process that has not synced).
+      def recheck_database
+        return if synced? && @recheck_after && now < @recheck_after
+
+        @recheck_after = now + DATABASE_RECHECK
+        sync(nil, always: true)
+      end
+
       # Applies the concern to one model in this process.
       def apply!(name)
         SYNC_LOCK.synchronize { MaskedModels.apply(only: name) }
@@ -157,8 +230,9 @@ module PermissionForge
         apply!(name)
         return if publish_token
 
-        Rails.logger&.warn('[PermissionForge] The cache store did not take the masking token: other processes ' \
-                           "mask #{name} once the store answers again and this process has written it.")
+        Warnings.emit("masking_sync.token_not_taken.#{name}",
+                      "The cache store did not take the masking token: other processes mask #{name} once the " \
+                      'store answers again and this process has written it.', severity: :security)
       end
 
       # The token to check against — nil while the store is failing. A
@@ -228,16 +302,23 @@ module PermissionForge
         @failing_until = nil
       end
 
-      # Logged once per outage: the first failure after the store answered.
+      # Warned once per outage: the first failure after the store answered.
+      # The warning names the cause (the error, or what a silent store did)
+      # and the remedy.
       def store_failed!(error = nil)
         first = @failing_until.nil?
         @failing_until = now + RETRY_PAUSE
         @failing_store = PermissionForge.cache
         return unless first
 
-        why = error ? " (#{error.class}: #{error.message})" : ''
-        Rails.logger&.warn("[PermissionForge] The cache store did not give or keep the masking token#{why}: auto-applied " \
-                           "masking is not synced with other processes for the next #{RETRY_PAUSE} seconds.")
+        Warnings.emit(:masking_sync_store_failed,
+                      'The cache store did not give or keep the masking token' \
+                      "#{error ? " (#{error.class}: #{error.message})" : SILENT_STORE}: auto-applied " \
+                      "masking is not synced with other processes for the next #{RETRY_PAUSE} seconds — a model " \
+                      'a Resource row names in another process is masked here once the store answers. A store ' \
+                      'that is up but loses the token at once cannot sync masking: use a shared store that keeps ' \
+                      'entries, or include PermissionForge::Concerns::MaskedAttributes in the models ' \
+                      '(docs/masked-attributes.md).', severity: :security)
       end
 
       def now
@@ -251,12 +332,6 @@ module PermissionForge
         token.nil? ? !synced? : token != @token
       end
 
-      # Whether this process has the concern on the model (false for a name
-      # that resolves to no model here: not known to be masked).
-      def masked_here?(name)
-        MaskedModels.masked?(name)
-      end
-
       def sync(token, always: false)
         SYNC_LOCK.synchronize do
           return true if !always && synced? && token == @token

data/lib/permission_forge/model_bindings.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'warnings'
+
 module PermissionForge
   # What a model took from the configuration as it loaded — the user class of
   # an assignment (PermissionSetUser#user, PermissionSetGroupUser#user), the
@@ -8,16 +10,21 @@ module PermissionForge
   # changed after the class loaded (a PermissionForge.configure or a setter
   # in after_initialize, a console) changes nothing in the class: a
   # development reload picks it up, an eager-loaded production process never
-  # does. The engine logs each difference once the host's after_initialize
-  # blocks have run, and PermissionForge.configure logs it too. Nothing here
-  # loads a model. (table_name_prefix is not compared: table_name is a
-  # method that reads it on every call.)
+  # does. The engine warns about each difference (Warnings.emit) once the
+  # host's after_initialize blocks have run, and PermissionForge.configure
+  # does too. Nothing here loads a model. (table_name_prefix is not
+  # compared: table_name is a method that reads it on every call.)
   #
   # @api private
   module ModelBindings
     # The settings a model declares as it loads, each with the association
     # that carries it (the tenant is read from HasTenantScoping).
     ASSOCIATIONS = { user_class: :user, audit_user_class: :created_by }.freeze
+    # The severity of a mismatch, by setting (Warnings): a model loaded with
+    # another tenant model (or none) is not isolated as configured, access
+    # across tenants; another user class only points an association
+    # elsewhere.
+    SEVERITY = { tenant_model: :security }.freeze
 
     class << self
       # One sentence per setting that loaded models declared differently.
@@ -25,22 +32,18 @@ module PermissionForge
       # @param config [Configuration]
       # @return [Array<String>]
       def mismatches(config = PermissionForge.configuration)
-        found = Hash.new { |hash, key| hash[key] = [] }
-        loaded_models.each do |model|
-          declared_otherwise(model, config).each do |setting, declared|
-            found[[setting, config.public_send(setting), declared]] << model.name
-          end
-        end
-        found.map { |difference, models| sentence(difference, models) }
+        differences(config).map { |difference, models| sentence(difference, models) }
       end
 
-      # Logs every mismatch.
+      # Warns about every mismatch, one key per setting.
       #
       # @param config [Configuration]
-      # @param logger [Logger, nil]
       # @return [void]
-      def warn!(config = PermissionForge.configuration, logger: default_logger)
-        mismatches(config).each { |sentence| logger&.warn("[PermissionForge] #{sentence}") }
+      def warn!(config = PermissionForge.configuration)
+        differences(config).each do |difference, models|
+          setting = difference.first
+          Warnings.emit("model_bindings.#{setting}", sentence(difference, models), severity: SEVERITY.fetch(setting, :config))
+        end
       end
 
       # The model classes already loaded, without loading one.
@@ -53,6 +56,18 @@ module PermissionForge
 
       private
 
+      # { [setting, what the configuration says, what the models declared] =>
+      # the model names } for every difference.
+      def differences(config)
+        found = Hash.new { |hash, key| hash[key] = [] }
+        loaded_models.each do |model|
+          declared_otherwise(model, config).each do |setting, declared|
+            found[[setting, config.public_send(setting), declared]] << model.name
+          end
+        end
+        found
+      end
+
       # [setting, what the model declared] for each setting the model
       # declared and the configuration now says differently. A model without
       # the association (a PermissionSet has no :user) declares nothing.
@@ -81,10 +96,6 @@ module PermissionForge
           'development; never in an eager-loaded production process). Configure PermissionForge in ' \
           'config/initializers.'
       end
-
-      def default_logger
-        Rails.logger if defined?(Rails) && Rails.respond_to?(:logger)
-      end
     end
   end
 end

data/lib/permission_forge/model_lookup.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # "This name is a model with a table" has one definition: the class a
+  # Resource name or a rule's Resource stands for, when it is an ActiveRecord
+  # model that is not abstract and whose table exists. Anything else — a
+  # module (`Kernel`), a class that is no model (`String`), an abstract
+  # model, a model whose table is not there yet, a name that is no constant,
+  # a constant whose file raises while it loads — is no model: the callers
+  # describe or skip, they never fail on it (a Resource named `Kernel` made
+  # the field generator raise NoMethodError and the API answer 500). A table
+  # found missing is asked of the database again once (SchemaRead.table?).
+  # The one place a Resource name is constantized (a G4 needle).
+  #
+  # @example
+  #   ModelLookup.model_for('Customer')  # => Customer
+  #   ModelLookup.model_for('Kernel')    # => nil
+  #
+  # @api private
+  module ModelLookup
+    # What is rescued while a name is resolved: anything raised as the
+    # constant loads, a model file's SyntaxError or LoadError included.
+    UNTELLABLE = [StandardError, ScriptError].freeze
+
+    module_function
+
+    # @param name [String, Symbol, nil] a constant path
+    # @return [Class, nil] the model, or nil when the name is no model with a table
+    def model_for(name)
+      klass = name.to_s.safe_constantize
+      klass if klass.is_a?(Class) && klass < ActiveRecord::Base && !klass.abstract_class? && SchemaRead.table?(klass, klass.table_name)
+    rescue *UNTELLABLE
+      nil
+    end
+
+    # @param name [String, Symbol, nil]
+    # @return [Boolean] whether the name is a model with a table
+    def model?(name)
+      !model_for(name).nil?
+    end
+  end
+end

data/lib/permission_forge/operators/encrypted_alias.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Operators
+    # The model whose encrypted column a rule names through a name its
+    # query gives a table that is on no model along the rule's path: an
+    # alias (`twins_notes.body` on a self-join), a `has_many :through`'s
+    # join table, a table a default scope or a host's join brings in
+    # (RuleSources). RuleColumn leaves such a name to the database
+    # (UNKNOWN) — except a column that holds ciphertext, which no built-in
+    # operator can compare (RuleColumn#encrypted?): failing to see one would
+    # compare the ciphertext, and `not_equal` would show the rows it should
+    # hide.
+    #
+    # - The name is resolved to the table it stands for, and every loaded
+    #   model on that table (PermissionForge::EncryptedAttributes.models_on,
+    #   single-table inheritance included) says whether it encrypts the
+    #   column: one that does makes it encrypted.
+    # - A name whose table cannot be told, or that no loaded model is on (a
+    #   subquery, a table without a model), is judged by every model along
+    #   the path, the rule's own included: a column of that name that any of
+    #   them encrypts counts as encrypted (fail closed).
+    #
+    # Names are compared as the database compares them (RuleColumn.same_name?).
+    #
+    # @api private
+    class EncryptedAlias
+      # @param models [Array<Class>] the rule's model, then the model of each
+      #   association on its path
+      # @param joined [Hash{String => String, nil}, Array<String>, nil] the
+      #   names the rule's query gives its tables (RuleSources.tables; a list
+      #   of names: their tables not known)
+      def initialize(models, joined)
+        @models = models
+        @joined = joined || {}
+        @exact = RuleColumn.exact_names?(models.last)
+      end
+
+      # The model whose encrypted column `name` is, when `table` is a name
+      # the query gives a table: one on that table, or one along the path;
+      # nil otherwise.
+      #
+      # @param table [String] the field name's qualifier
+      # @param name [String] the column as written
+      # @return [Class, nil]
+      def model(table, name)
+        source = @joined.find { |alias_name, _table| RuleColumn.same_name?(alias_name, table, @exact) } or return
+
+        (on_table(source).presence || @models).find { |model| encrypts?(model, name) }
+      end
+
+      private
+
+      # The loaded models on the table the name stands for.
+      def on_table(source)
+        _alias_name, table = source
+        return [] unless table
+
+        PermissionForge::EncryptedAttributes.models_on(table, exact: @exact)
+      end
+
+      def encrypts?(model, name)
+        PermissionForge::EncryptedAttributes.names(model).any? { |attribute| RuleColumn.same_name?(attribute.to_s, name, @exact) }
+      end
+    end
+  end
+end

data/lib/permission_forge/operators/registry.rb

@@ -18,6 +18,12 @@ module PermissionForge
     #
     # @api public
     module Registry
+      # The operators whose strategy adds the NULL rows under a rule's
+      # `include_nulls` ("…, or empty"); the others ignore the flag. The one
+      # list: the RLS policy (Services::RlsOperatorSql), the rule builder and
+      # the rule's sentence read it (a test compares it with the strategies).
+      NULL_INCLUDING = [Constants::EQUAL, Constants::NOT_EQUAL, Constants::IN, Constants::NOT_IN].freeze
+
       module_function
 
       # @param name [String] operator constant from PermissionSetRule (e.g., 'equal')