permission_forge 0.14.1

data/lib/permission_forge/invalidation_batch.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # What the permission records committed by one transaction have already
+  # invalidated, so the next record of that commit does not repeat it: a
+  # "Review and save" that writes 20 records in a Permission Set assigned to
+  # 50 people invalidates 50 hashes, not 1,000.
+  #
+  # A batch never holds work that only it knows about. Each record still
+  # invalidates in its own after_commit (Concerns::InvalidatesInBatch); the
+  # batch remembers what was done after the commit — which users (#once) and
+  # which affected-user lookups (#fetch) — and keeps a second copy of what
+  # records noted for the commit (#note). Mistrusting or losing a batch
+  # therefore costs repeated invalidations, never one a record would have
+  # made on its own.
+  #
+  # Lifecycle:
+  #   1. A record joins the batch still open on its thread and connection when
+  #      it is written (.join). An open batch has been used by no commit, so
+  #      it remembers nothing — joining one cannot bring anything stale along.
+  #   2. The first after_commit of a record that joined claims it (#claim):
+  #      from then on nothing can join, and the batch notes where the claim
+  #      happened — the transaction depth of its connection and the ambient
+  #      tenant.
+  #   3. Later records of that commit claim it from the same place and reuse
+  #      what it remembers. A claim from anywhere else is refused, and that
+  #      record invalidates on its own.
+  #
+  # Why the depth: a batch must only be reused by records whose transaction had
+  # committed before the batch remembered anything. While a record's
+  # transaction is open it sits on the connection's transaction stack; its
+  # after_commit runs once it has been popped. So everything remembered at the
+  # depth a record sees in its own after_commit was remembered after that
+  # record's transaction left the stack — after its commit. Without the check,
+  # a transaction nested in a non-joinable one (it runs its commit callbacks
+  # while the outer transaction is still open) would cover for the outer
+  # transaction's records, whose rows are not visible to anyone else yet.
+  #
+  # Why the tenant: lookups and cache keys follow the ambient tenant, so what
+  # was remembered under one tenant says nothing about another.
+  #
+  # What it remembers is forgotten as soon as another permission record is
+  # written (.note_write): the commit's after_commit callbacks are not the only
+  # code that runs between two of them. A callback in between may write a
+  # record whose own invalidation comes too early to count — in a transaction
+  # nested in a non-joinable one it runs at the savepoint release, before the
+  # COMMIT anyone else can see. The records still waiting then invalidate
+  # again, after that write, as they did before there were batches. The count
+  # of writes is kept for the whole process: such a write may be made in
+  # another fiber or thread than the one the commit runs on.
+  # (Notes — #note — are kept: they say what has to be done, not what was.)
+  #
+  # @api private
+  class InvalidationBatch
+    # The ExecutionState slot of the batch still open on this thread (fiber
+    # under Rails' fiber isolation).
+    THREAD_KEY = :pf_open_invalidation_batch
+
+    # Guards @writes increments; reads are lock-free.
+    WRITES_MUTEX = Mutex.new
+
+    class << self
+      # The batch a record being written on `connection` joins: the one still
+      # open on this thread for that connection, else a new one.
+      #
+      # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+      # @return [InvalidationBatch]
+      def join(connection)
+        note_write
+        current = ExecutionState[THREAD_KEY]
+        return current if current&.open_on?(connection)
+
+        ExecutionState[THREAD_KEY] = new(connection)
+      end
+
+      # A permission record is being written somewhere in this process: every
+      # batch forgets what it remembers before it is reused (see #claim).
+      #
+      # @return [void]
+      def note_write
+        WRITES_MUTEX.synchronize { @writes = writes + 1 }
+      end
+
+      # @return [Integer] permission-record writes this process has made
+      def writes
+        @writes || 0
+      end
+    end
+
+    # Without a connection the batch stands alone: it can be used at once and
+    # never joined or claimed (an invalidation outside any commit).
+    def initialize(connection = nil)
+      @connection = connection
+      @claimed_at = nil
+      @writes_seen = nil
+      @lookups = {}
+      @done = Set.new
+      @noted = {}
+    end
+
+    # @return [Boolean] whether a record written on `connection` may still join
+    def open_on?(connection)
+      !@claimed_at && @connection.equal?(connection)
+    end
+
+    # Called from a record's after_commit, before it uses the batch.
+    #
+    # @return [InvalidationBatch, nil] the batch when the commit being reported
+    #   may reuse it; nil when it was claimed from somewhere else
+    def claim
+      return unless @connection
+
+      place = [@connection.open_transactions, PermissionForge.ambient_tenant_id]
+      unless @claimed_at
+        @claimed_at = place
+        release_thread
+      end
+      return unless @claimed_at == place
+
+      forget_if_written_since
+      self
+    end
+
+    # A lookup shared by the records of the commit.
+    #
+    # @param key [Object] what is looked up (e.g. [:assignments, permission_set_id])
+    # @return [Object] the block's value, from the first call for this key
+    def fetch(key)
+      return @lookups[key] if @lookups.key?(key)
+
+      @lookups[key] = yield
+    end
+
+    # Runs an invalidation unless the commit has already run it. The key is
+    # only remembered once the block has returned: an invalidation that raised
+    # was not done.
+    #
+    # @param key [Object] what is invalidated (e.g. [:user, user_id, tenant_id])
+    # @return [void]
+    def once(key)
+      return if @done.include?(key)
+
+      yield
+      @done << key
+    end
+
+    # Remembers an invalidation the commit has made without #once (many
+    # users in one call, Cache::HolderInvalidation) — after it was made.
+    #
+    # @param key [Object] what was invalidated (e.g. [:user, user_id, tenant_id])
+    # @return [void]
+    def done!(key)
+      @done << key
+    end
+
+    # @return [Boolean] whether #once (or #done!) has already run for this key
+    def done?(key)
+      @done.include?(key)
+    end
+
+    # Says that something has to be invalidated when the transaction commits.
+    # This never replaces the note a record keeps for itself — a record does
+    # its own invalidation in its own after_commit, whatever becomes of the
+    # batch. It is for the case that after_commit never runs: of two instances
+    # of one row written in a transaction, Rails runs the callbacks of one,
+    # and that one can find here what the other noted.
+    #
+    # @param kind [Symbol] which cache (e.g. :managed_actions)
+    # @param value [Object] what of it (e.g. the tenant id)
+    # @return [void]
+    def note(kind, value)
+      (@noted[kind] ||= Set.new) << value
+    end
+
+    # @param kind [Symbol]
+    # @return [Array] what the records that joined have noted for this cache
+    def noted(kind)
+      @noted.fetch(kind, []).to_a
+    end
+
+    # A record can be marshalled (cached) while it still references the batch
+    # it joined. Nothing of a batch is worth keeping, and its connection cannot
+    # be dumped: the copy stands alone.
+    def marshal_dump = nil
+
+    def marshal_load(_state)
+      initialize
+    end
+
+    private
+
+    def forget_if_written_since
+      writes = self.class.writes
+      return if @writes_seen == writes
+
+      @writes_seen = writes
+      @lookups.clear
+      @done.clear
+    end
+
+    # So the thread keeps nothing of a claimed batch (it is never joined again).
+    def release_thread
+      ExecutionState[THREAD_KEY] = nil if ExecutionState[THREAD_KEY].equal?(self)
+    end
+  end
+end

data/lib/permission_forge/masked_models.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # Auto-applied masking: mixes MaskedAttributes into the models
+  # config.auto_apply_masked_attributes selects and wraps the virtual readers
+  # of the models config.mask_virtual_attributes selects. Each setting takes
+  # its models from the Resource rows (:auto / true) or from a list. Called
+  # by MaskingSync (at boot, after a Resource row names a model, and when
+  # another process named one).
+  #
+  # @api private
+  module MaskedModels
+    # Setting values that switch a step off.
+    OFF = [false, nil].freeze
+
+    class << self
+      # @return [Boolean] whether either setting is on (MaskingSync does
+      #   nothing otherwise)
+      def enabled?(config = PermissionForge.configuration)
+        settings(config).any? { |setting| !OFF.include?(setting) }
+      end
+
+      # Whether a setting that is on takes its models from the Resource rows:
+      # a row committed in another process can then name a model this process
+      # has not masked. False when every setting that is on is a list — the
+      # models are fixed by the configuration.
+      #
+      # @return [Boolean]
+      def row_driven?(config = PermissionForge.configuration)
+        settings(config).any? { |setting| !OFF.include?(setting) && !setting.is_a?(Array) }
+      end
+
+      # Includes the concern on every selected model, then wraps the virtual
+      # readers of every selected model that has it (applied here, or
+      # included by the model itself). Idempotent. A model that cannot be
+      # masked (its table is missing, its database is down) is logged and
+      # skipped: the others are still masked.
+      #
+      # @param only [String, nil] one model, as long as the settings select it
+      # @return [Boolean] true when every selected model is masked; false when
+      #   the Resource rows could not be read (no table yet, no database), a
+      #   model could not be masked, or a listed name is no model here
+      #   (MaskingSync then tries again)
+      def apply(only: nil)
+        config = PermissionForge.configuration
+        return true unless enabled?(config)
+        return false unless PermissionForge::Resource.table_exists?
+
+        apply_selected(config, only).all? & unknown_listed_names(config, only).empty?
+      rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
+        # Tables may not exist yet during early boot or pre-migration.
+        false
+      end
+
+      # @return [Boolean, nil] false when the model is left unmasked
+      def apply_concern(model_name)
+        klass = model_class(model_name)
+        return if klass.nil? || klass.abstract_class?
+        return if masked_class?(klass)
+
+        # Including the concern runs its `included` block after the module is
+        # in the ancestors: a block that failed there (the table could not be
+        # read) leaves a class every later include skips. Never start one
+        # that cannot finish.
+        why = unmaskable_reason(klass)
+        if why
+          warn_unmaskable(klass, why)
+          return false
+        end
+
+        klass.include(PermissionForge::Concerns::MaskedAttributes)
+        unmaskable_warned.delete(klass.name)
+      end
+
+      # Wraps the virtual readers of a model that has MaskedAttributes. The
+      # wrappers re-check config.mask_virtual_attributes on every call. A
+      # model whose extra_fields_method raises keeps its declared readers
+      # unwrapped, and pf_mask_virtual_readers logs a SECURITY warning.
+      #
+      # @return [Array<String>, nil] the names wrapped
+      def mask_virtual_readers(model_name)
+        klass = model_class(model_name)
+        return unless klass.respond_to?(:pf_mask_virtual_readers)
+        return unless PermissionForge.configuration.mask_virtual_attributes_for?(klass.name)
+
+        klass.pf_mask_virtual_readers
+      end
+
+      # Whether the model `model_name` names has the concern in this process
+      # (applied, or included by the model or a class it inherits from);
+      # false for a name that resolves to no model here.
+      #
+      # @param model_name [String]
+      # @return [Boolean]
+      def masked?(model_name)
+        klass = model_class(model_name)
+        klass ? masked_class?(klass) : false
+      end
+
+      # Warns again about a model that still cannot be masked (MaskingSync.reset!).
+      def reset_warnings!
+        unmaskable_warned.clear
+      end
+
+      private
+
+      def settings(config)
+        [config.auto_apply_masked_attributes, config.mask_virtual_attributes]
+      end
+
+      # The concern on every selected model, then the virtual readers (the
+      # names of both read first).
+      #
+      # @return [Array<Boolean>] whether each step left its model masked
+      def apply_selected(config, only)
+        concern = model_names(config.auto_apply_masked_attributes, only: only)
+        virtual = model_names(config.mask_virtual_attributes, only: only)
+        concern.map { |name| guarded(name) { apply_concern(name) } } +
+          virtual.map { |name| guarded(name) { mask_virtual_readers(name) } }
+      end
+
+      # One model's failure is logged and the loop goes on; a
+      # ConfigurationError (the setup is wrong, not the model) still stops the
+      # boot, as everywhere in BootChecks.
+      def guarded(name)
+        yield != false
+      rescue PermissionForge::ConfigurationError
+        raise
+      rescue StandardError => e
+        warn_unmaskable(model_class(name) || name, "#{e.class}: #{e.message}")
+        false
+      end
+
+      # The models a setting selects: none when it is off, its list, or the
+      # names of the Resource rows — narrowed to `only`.
+      def model_names(setting, only: nil)
+        return [] if OFF.include?(setting)
+        return listed_names(setting, only) if setting.is_a?(Array)
+
+        only ? Array(only).map(&:to_s) : resource_names
+      end
+
+      def listed_names(list, only)
+        list = list.map(&:to_s)
+        only ? Array(only).map(&:to_s) & list : list
+      end
+
+      # The names a list setting gives that resolve to no model here (a typo,
+      # a class not loaded yet), each logged once. A name a Resource row
+      # gives (:auto) may name a controller-only resource: not reported.
+      #
+      # @return [Array<String>]
+      def unknown_listed_names(config, only)
+        { 'auto_apply_masked_attributes' => config.auto_apply_masked_attributes,
+          'mask_virtual_attributes' => config.mask_virtual_attributes }.flat_map do |setting, value|
+          next [] unless value.is_a?(Array)
+
+          listed_names(value, only).reject { |name| model_class(name) }.each { |name| warn_unknown(setting, name) }
+        end
+      end
+
+      def warn_unknown(setting, name)
+        return if unmaskable_warned.put_if_absent("#{setting}=#{name}", true)
+
+        Rails.logger&.warn("[PermissionForge] SECURITY warning: '#{name}' is listed in config.#{setting} but is no " \
+                           'model in this process: nothing is masked for it. It is tried again at the next request or job.')
+      end
+
+      # Every tenant's rows: a model is masked for the whole process.
+      def resource_names
+        if PermissionForge.configuration.tenant_enabled? && defined?(ActsAsTenant)
+          ActsAsTenant.without_tenant { PermissionForge::Resource.distinct.pluck(:name) }
+        else
+          PermissionForge::Resource.distinct.pluck(:name)
+        end
+      end
+
+      # The class, or a class it inherits from, has the concern applied. A
+      # subclass is masked through its parent (the concern is never included
+      # into a subclass) and may have a Resource row of its own (STI).
+      def masked_class?(klass)
+        PermissionForge::Concerns::MaskedAttributes.applied_in_chain?(klass)
+      end
+
+      # Only reached when no class in the chain has the concern applied: the
+      # module in the ancestors then means an include that failed halfway.
+      #
+      # @return [String, nil] why the concern cannot be included now
+      def unmaskable_reason(klass)
+        return 'its table cannot be read' unless readable_table?(klass)
+
+        'an earlier attempt failed halfway; restart the process' if klass.include?(PermissionForge::Concerns::MaskedAttributes)
+      end
+
+      # The table exists and can be read. A table found missing is looked up
+      # again next time (the cached answer is dropped): a migration may run.
+      def readable_table?(klass)
+        return true if klass.table_exists?
+
+        klass.reset_column_information
+        false
+      rescue ActiveRecord::StatementInvalid, ActiveRecord::ConnectionNotEstablished
+        false
+      end
+
+      # Logs once per model and process (MaskingSync retries every request).
+      def warn_unmaskable(klass, why)
+        name = klass.to_s
+        return if unmaskable_warned.put_if_absent(name, true)
+
+        Rails.logger&.warn("[PermissionForge] SECURITY warning: #{name} has a Resource row but #{why}: its columns " \
+                           'are NOT masked in this process. It is tried again at the next request or job.')
+      end
+
+      # The models (and unknown listed names) whose warning this process has logged.
+      def unmaskable_warned
+        @unmaskable_warned ||= Concurrent::Map.new
+      end
+
+      def model_class(model_name)
+        klass = model_name.to_s.safe_constantize
+        klass if klass.is_a?(Class) && klass < ActiveRecord::Base
+      end
+    end
+  end
+end

data/lib/permission_forge/masking_sync.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module PermissionForge
+  # Carries auto-applied masking (MaskedModels) to every process. The
+  # concern is mixed into a model class in the process that loads it: at
+  # boot, and in the process that commits the first Resource row for a new
+  # model. Every other process would serve that model unmasked until it
+  # restarts — unless it hears of it (docs/masked-attributes.md).
+  #
+  # When a setting takes its models from the Resource rows
+  # (MaskedModels.row_driven?):
+  #   - Writer: the process that commits a row naming a model for the first
+  #     time (no other row in any tenant has the name, or this process had
+  #     not masked it: two rows committed together) applies the concern and
+  #     writes a new random token under KEY in the shared store, no expiry.
+  #   - Reader: each executor run (request or job) reads KEY once (check!);
+  #     a token it has not synced with makes it apply to every named model.
+  #   - A process that reads no token (evicted, flushed) writes one and
+  #     syncs; every other process then syncs once too. Losing the token
+  #     costs one `pluck` per process, never a model left unmasked.
+  #   - A store that does not answer is left alone for RETRY_PAUSE seconds,
+  #     then one request or job per process probes it; logged once per
+  #     outage. An announcement the store did not take is owed and written
+  #     once it answers.
+  # When every setting that is on is a list, the models are fixed by the
+  # configuration: no token is read or written, and a process that has
+  # synced does nothing per request. When both are off, check! returns
+  # before reading anything (the hook stays: a setting may be switched on
+  # after the boot step).
+  #
+  # 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).
+  #
+  # @api private
+  module MaskingSync
+    KEY = 'masked_models_version'
+
+    # The token of a process that has not synced yet (no token can equal it).
+    UNSYNCED = Object.new.freeze
+
+    # Seconds the store is left alone after it did not answer.
+    RETRY_PAUSE = 30
+
+    # One sync (or apply) at a time; one probe of a failing store at a time.
+    SYNC_LOCK = Mutex.new
+    PROBE_LOCK = Mutex.new
+
+    # The token this process synced with (UNSYNCED, or nil for "synced
+    # without one"), whether it owes the store an announcement, and until
+    # when (monotonic seconds) which store is left alone. A failure while
+    # @failing_until is set belongs to the outage already logged.
+    @token = UNSYNCED
+    @announcement_owed = false
+    @failing_until = nil
+    @failing_store = 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.
+      def check!
+        return unless MaskedModels.enabled?
+
+        token = MaskedModels.row_driven? ? 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}")
+      end
+
+      # After a Resource row naming `name` has been created or renamed and
+      # committed: tells the other processes (a new token) when the name is
+      # new to them — no other row has it — or when this process had not
+      # masked the model before: rows committed together each see the
+      # others, and the first to get here announces. Otherwise, and when
+      # the settings are lists, applies the concern here only.
+      #
+      # @param name [String] the model the row names
+      # @yieldreturn [Boolean] whether another Resource row has the name
+      #   (asked only when it decides something)
+      def named!(name)
+        return unless MaskedModels.enabled?
+        return apply!(name) unless MaskedModels.row_driven?
+
+        masked_here?(name) && yield ? apply!(name) : announce!(name)
+      end
+
+      # The boot step: applies to every selected model and syncs with the
+      # current token (read first, so a name committed meanwhile is seen
+      # again by the next check). When a model could not be masked (or the
+      # rows could not be read) the process stays unsynced and the next
+      # request or job tries again.
+      #
+      # @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
+      end
+
+      # `to_prepare`: after a code reload in development the model classes
+      # are new and unmasked. At boot it runs before the boot step: nothing
+      # to re-apply yet.
+      def reloaded!
+        return unless Rails.application&.initialized?
+
+        reset!
+        check!
+      end
+
+      # Forgets the token (the next check applies whatever the token says)
+      # and that the store failed. Also what a boot that could not reach the
+      # database leaves (BootChecks).
+      def reset!
+        SYNC_LOCK.synchronize { @token = UNSYNCED }
+        @announcement_owed = false
+        @failing_until = nil
+        MaskedModels.reset_warnings!
+      end
+
+      # @return [Boolean] whether this process has synced once
+      def synced?
+        !@token.equal?(UNSYNCED)
+      end
+
+      # @return [Boolean] whether the store recently did not answer (the
+      #   store in use: one that replaced it has not failed yet)
+      def store_failing?
+        until_time = @failing_until
+        !until_time.nil? && now < until_time && PermissionForge.cache.equal?(@failing_store)
+      end
+
+      private
+
+      # Applies the concern to one model in this process.
+      def apply!(name)
+        SYNC_LOCK.synchronize { MaskedModels.apply(only: name) }
+      end
+
+      # Applies the concern here, then tells the other processes. The token
+      # it writes is not taken as this process's own: another process may
+      # have written one since this one last checked, so the next check
+      # syncs once more.
+      #
+      # A token the store does not take (it is down, or raises) is owed:
+      # this process writes a new one at its first request or job after the
+      # store answers again (after RETRY_PAUSE). Never raises for the store.
+      def announce!(name)
+        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.")
+      end
+
+      # The token to check against — nil while the store is failing. A
+      # token this process owes the store (an announcement it did not take)
+      # is written first, once the store answers.
+      #
+      # @return [String, nil]
+      def answered_token
+        return if store_failing?
+        return owed_or_current_token unless @failing_until
+
+        probe_store
+      end
+
+      # The pause after a failure is over: one thread asks the store again;
+      # the others keep the pause (nil) instead of each waiting for a store
+      # that may still be gone.
+      def probe_store
+        return unless PROBE_LOCK.try_lock
+
+        begin
+          owed_or_current_token
+        ensure
+          PROBE_LOCK.unlock
+        end
+      end
+
+      def owed_or_current_token
+        token = current_token
+        token && @announcement_owed ? (publish_token || token) : token
+      end
+
+      # Writes a new token (no expiry). Remembers it as owed when the store
+      # does not take it, and starts the back-off.
+      #
+      # @return [String, nil] the token written
+      def publish_token
+        token = SecureRandom.uuid
+        written = PermissionForge.cache.write_permanent(KEY, token)
+        store_failed! unless written
+        @announcement_owed = !written
+        token if written
+      rescue StandardError => e
+        @announcement_owed = true
+        store_failed!(e)
+        nil
+      end
+
+      # The token in the store — or, when there is none, a new one written
+      # (with no expiry) and read back: whatever token is there then, also
+      # one another process wrote meanwhile. nil when the store did not
+      # answer: it is left alone for RETRY_PAUSE. A read that raised is not
+      # followed by a write.
+      #
+      # @return [String, nil]
+      def current_token
+        cache = PermissionForge.cache
+        token = cache.read_fresh(KEY) || (cache.read_fresh(KEY) if cache.write_permanent(KEY, SecureRandom.uuid))
+        token ? store_answered! : store_failed!
+        token
+      rescue StandardError => e
+        store_failed!(e)
+        nil
+      end
+
+      def store_answered!
+        @failing_until = nil
+      end
+
+      # Logged once per outage: the first failure after the store answered.
+      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.")
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # Whether `token` is one this process has not synced with. An unknown
+      # one (nil: the store did not answer) only for a process that never
+      # synced.
+      def changed?(token)
+        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
+
+          applied = MaskedModels.apply
+          @token = token if applied
+          applied
+        end
+      end
+    end
+  end
+end