lcp 0.1.0

data/lib/lcp_ruby/authentication/user_resolver.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module LcpRuby
+  module Authentication
+    # Bridges OmniAuth's auth_hash into an LCP user record. Called from the
+    # OIDC callback controller. Side-effects: may create a new LcpRuby::User,
+    # update fields on an existing one, and persist mapped roles.
+    class UserResolver
+      # Columns that update_on_login must never overwrite, regardless of what an
+      # `auth.yml` author lists. Devise-managed credentials, role/authorization
+      # state, the OIDC linkage keys, and audit columns are all out of bounds.
+      # The whitelist applied at runtime is `User.column_names - PROTECTED_FIELDS`.
+      PROTECTED_FIELDS = %w[
+        id provider external_id lcp_role active
+        encrypted_password reset_password_token reset_password_sent_at
+        remember_created_at sign_in_count current_sign_in_at last_sign_in_at
+        current_sign_in_ip last_sign_in_ip failed_attempts unlock_token locked_at
+        confirmation_token confirmed_at confirmation_sent_at unconfirmed_email
+        created_at updated_at
+      ].freeze
+
+      def self.call(auth:, provider:)
+        new(auth: auth, provider: provider).call
+      end
+
+      # Build a resolver from already-extracted claims (e.g. from a verified
+      # JWT) without an OmniAuth `auth_hash`. Reuses the provisioning, role
+      # mapping, and synchronizer pipeline. `auth` is nil for bearer flows;
+      # the `claims_synchronizer` hook receives nil as its 4th arg, so hosts
+      # that need the OmniAuth hash must guard.
+      def self.from_claims(claims:, provider:)
+        new(auth: nil, provider: provider, claims: claims).call
+      end
+
+      # When `claims:` is non-nil, bypasses OmniAuth `auth_hash` extraction
+      # and uses the hash verbatim (after deep-stringification of keys).
+      # When nil, extracts claims from the OmniAuth hash (web-login path).
+      def initialize(auth:, provider:, claims: nil)
+        @auth     = auth
+        @provider = provider
+        @claims   = claims.nil? ? extract_claims(auth) : claims.deep_stringify_keys
+      end
+
+      def call
+        validate_claims!
+        external_id = @claims[@provider.claim_mappings[:external_id].to_s]
+
+        user = LcpRuby::User.find_by(provider: @provider.name, external_id: external_id)
+        user ||= provision!(external_id)
+
+        apply_updates!(user)
+        user.lcp_role = RoleMapper.call(@claims, @provider)
+        apply_claims_synchronizer!(user)
+        user.active = true if user.respond_to?(:active=)
+        user.save! if user.new_record? || user.changed? || attachment_changes?(user)
+        user
+      end
+
+      private
+
+      # Pulls the raw IdP claims out of the OmniAuth auth hash and normalises
+      # them to a deeply string-keyed hash. RoleMapper#dig_path walks nested
+      # claims like `realm_access.roles` and relies on this normalisation.
+      def extract_claims(auth)
+        info = auth.respond_to?(:extra) ? auth.extra&.raw_info : nil
+        return {} unless info
+
+        hash = info.respond_to?(:to_h) ? info.to_h : info
+        hash.deep_stringify_keys
+      end
+
+      def validate_claims!
+        ext_key = @provider.claim_mappings[:external_id].to_s
+        if ext_key.empty? || @claims[ext_key].to_s.empty?
+          raise InvalidClaims, "missing external_id claim '#{ext_key}'"
+        end
+      end
+
+      def provision!(external_id)
+        if @provider.provisioning[:reject_if_host_missing]
+          provisioner = LcpRuby.configuration.user_provisioner
+          host_user = provisioner&.call(@claims, @provider.name)
+          raise HostRejected, "user_provisioner rejected sign-in" if host_user.nil?
+
+          host_user.provider     ||= @provider.name
+          host_user.external_id  ||= external_id
+          host_user
+        elsif @provider.provisioning[:auto_create]
+          LcpRuby::User.new(
+            provider:    @provider.name,
+            external_id: external_id,
+            email:       @claims[@provider.claim_mappings[:email].to_s] || derived_email(external_id),
+            name:        @claims[@provider.claim_mappings[:name].to_s] || external_id
+          )
+        else
+          raise HostRejected, "auto_create disabled and no host provisioner ran"
+        end
+      end
+
+      # Optional host hook for syncing arbitrary claims into the user record:
+      # custom columns (department, title), profile_data JSON, Active Storage
+      # attachments fetched via Microsoft Graph / similar, host-side
+      # associations, …. Runs AFTER role mapping so the host can inspect
+      # `user.lcp_role` and override.
+      #
+      # Exceptions: in development/test, propagate so the bug is visible. In
+      # production, log and continue — a flaky external dependency (e.g. an
+      # MS Graph fetch for the user's photo) shouldn't lock people out.
+      def apply_claims_synchronizer!(user)
+        hook = LcpRuby.configuration.claims_synchronizer
+        return unless hook
+
+        hook.call(user, @claims, @provider.name, @auth)
+      rescue StandardError => e
+        raise unless defined?(Rails) && Rails.env.production?
+        # Avoid logging external_id (a stable IdP identifier — mild PII).
+        # The user.id is enough to correlate with the audit trail.
+        Rails.logger.warn(
+          "[lcp_ruby] OIDC claims_synchronizer failed for provider='#{@provider.name}' " \
+          "user_id=#{user.id || 'new'} #{e.class}: #{e.message}"
+        )
+      end
+
+      # True when the user has Active Storage attachment writes pending. Used
+      # alongside `user.changed?` to decide whether to issue a save: column-only
+      # idempotent runs skip the UPDATE, but a fresh `attach(...)` from the
+      # synchronizer must reach disk via the user's after_save callback.
+      def attachment_changes?(user)
+        user.respond_to?(:attachment_changes) && user.attachment_changes.any?
+      end
+
+      def apply_updates!(user)
+        Array(@provider.provisioning[:update_on_login]).each do |field|
+          field_name = field.to_s
+          unless updatable_field?(user, field_name)
+            Rails.logger.warn(
+              "[lcp_ruby] OIDC update_on_login skipped field='#{field_name}' " \
+              "provider='#{@provider.name}' (not a writable, non-protected column)"
+            )
+            next
+          end
+
+          claim_key = @provider.claim_mappings[field_name.to_sym]
+          next unless claim_key
+
+          value = @claims[claim_key.to_s]
+          user.public_send("#{field_name}=", value) if value
+        end
+      end
+
+      # `update_on_login` runs reflective `public_send` against the user record;
+      # restrict it to actual columns minus PROTECTED_FIELDS so a malicious or
+      # careless auth.yml can't write to credentials, role state, or the OIDC
+      # linkage keys.
+      def updatable_field?(user, field)
+        return false unless user.class.column_names.include?(field)
+        return false if PROTECTED_FIELDS.include?(field)
+        user.respond_to?("#{field}=")
+      end
+
+      # Synthesise a stable but harmless email when the IdP didn't return one.
+      # Avoids the `null: false, default: ""` collision under the unique index
+      # on lcp_ruby_users.email when multiple OIDC users sign in without email.
+      def derived_email(external_id)
+        "#{@provider.name}-#{external_id}@oidc.local"
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authentication.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "authentication/errors"
+require_relative "authentication/provider"
+require_relative "authentication/role_mapper"
+require_relative "authentication/provider_registry"
+require_relative "authentication/devise_setup"
+require_relative "authentication/audit_subscriber"
+require_relative "authentication/user_resolver"
+require_relative "authentication/omniauth_builder"
+require_relative "authentication/oidc_bearer_resolver"
+
+module LcpRuby
+  module Authentication
+    class << self
+      def built_in?
+        LcpRuby.configuration.authentication == :built_in
+      end
+
+      def none?
+        LcpRuby.configuration.authentication == :none
+      end
+
+      def external?
+        LcpRuby.configuration.authentication == :external
+      end
+
+      def oidc?
+        LcpRuby.configuration.authentication == :oidc
+      end
+
+      # True when authentication uses Warden/Devise — i.e. when the engine
+      # should wire up Devise routes and a sign_in/sign_out flow. OIDC also
+      # requires Warden because session creation goes through it.
+      def session_based?
+        %i[built_in oidc].include?(LcpRuby.configuration.authentication)
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authorization/association_lookup.rb

@@ -0,0 +1,56 @@
+module LcpRuby
+  module Authorization
+    # Reverse-resolves a parent model name to the `belongs_to` reflection on
+    # a child AR class. Used by `inherits_from` consumers (ScopeBuilder for
+    # the FK column, PermissionEvaluator for the association name, the
+    # InheritedParentValidator for both). Centralised so the polymorphic
+    # rejection rule and the multi-candidate ambiguity policy live in one
+    # place.
+    module AssociationLookup
+      class MissingAssociation < ScopeBuilder::ScopeError; end
+      class AmbiguousAssociation < ScopeBuilder::ScopeError; end
+
+      module_function
+
+      # Returns the matching belongs_to reflection or `nil` when no
+      # non-polymorphic belongs_to on `model_class` points at `parent_name`.
+      # Raises AmbiguousAssociation when more than one belongs_to qualifies
+      # (configurator must declare `via:` explicitly in that case).
+      def belongs_to_for(model_class, parent_name)
+        candidates = model_class
+                     .reflect_on_all_associations(:belongs_to)
+                     .reject { |r| r.options[:polymorphic] }
+                     .select { |r| r.class_name.demodulize.underscore == parent_name.to_s }
+
+        case candidates.size
+        when 0 then nil
+        when 1 then candidates.first
+        else
+          raise AmbiguousAssociation,
+                "inherits_from #{parent_name}: multiple belongs_to point to " \
+                "#{parent_name} on #{model_class.name} — declare `via:` explicitly"
+        end
+      end
+
+      # Same as `belongs_to_for` but raises MissingAssociation when no
+      # association qualifies. For consumers that require a definite answer.
+      def belongs_to_for!(model_class, parent_name)
+        belongs_to_for(model_class, parent_name) ||
+          raise(MissingAssociation,
+                "inherits_from #{parent_name}: no belongs_to on " \
+                "#{model_class.name} points to #{parent_name}")
+      end
+
+      # Returns the association name as a symbol, or `nil` if no match.
+      def belongs_to_name_for(model_class, parent_name)
+        belongs_to_for(model_class, parent_name)&.name
+      end
+
+      # Returns the foreign-key column name as a string. Raises
+      # MissingAssociation when no belongs_to qualifies.
+      def foreign_key_for(model_class, parent_name)
+        belongs_to_for!(model_class, parent_name).foreign_key
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authorization/authorization_error.rb

@@ -0,0 +1,12 @@
+module LcpRuby
+  module Authorization
+    # Abstract parent for authorization-subsystem errors that are
+    # *configuration* signals (not access-denial signals).
+    #
+    # Descends from StandardError so a host's
+    # `rescue_from Pundit::NotAuthorizedError` does NOT also catch
+    # configuration errors. See docs/design/authorization_hardening.md
+    # § "Error class hierarchy and inheritance".
+    class AuthorizationError < StandardError; end
+  end
+end

data/lib/lcp_ruby/authorization/cache.rb

@@ -0,0 +1,89 @@
+module LcpRuby
+  module Authorization
+    # Per-request memoization for parent policy classes and resolved parent
+    # scopes used by `inherits_from`. Storage lives on `LcpRuby::Current`,
+    # which Rails resets automatically at request boundaries via
+    # ActionDispatch::Executor and at the start of each ActiveJob perform.
+    # No manual around_action wiring required.
+    #
+    # Pattern: explicit user threading. The cache **does not read**
+    # `LcpRuby::Current.user`; the user that defines what gets cached is
+    # the one passed explicitly to `parent_policy_scope(parent_name, user)`.
+    # Cache keys include `user&.id` so impersonated and real views never
+    # collide.
+    module Cache
+      RESOLVING = :__resolving__
+
+      class ScopeError < StandardError; end
+
+      # Per-request memoization of PolicyFactory.policy_for.
+      #
+      # NB: PolicyFactory itself has a class-level cache, so this is
+      # technically a double cache. The Current-backed layer is kept
+      # deliberately for test isolation: `Cache.clear!` resets both
+      # `authz_scopes` AND `authz_policies` to nil, so test setups that
+      # want a clean policy-class slate per example get it via one call
+      # instead of also having to remember `PolicyFactory.clear!`.
+      # The runtime cost is one hash lookup per request, dwarfed by AR
+      # query overhead in any save path.
+      def self.policy_for(model_name)
+        store = (LcpRuby::Current.authz_policies ||= {})
+        store[model_name.to_s] ||= PolicyFactory.policy_for(model_name)
+      end
+
+      # Resolves the parent's policy scope and memoizes per (parent, user).
+      # Uses a re-entry sentinel: if a code path triggers re-entry on the
+      # same key during its own resolution (cycle escaped validation, DSL
+      # flow, dynamic edits) we raise rather than recurse infinitely.
+      #
+      # If the underlying resolver raises, the sentinel is cleared so the
+      # SAME error surfaces on subsequent calls instead of a misleading
+      # "recursion detected" message about the leftover sentinel.
+      def self.parent_policy_scope(parent_name, user)
+        store = (LcpRuby::Current.authz_scopes ||= {})
+        key = [ parent_name.to_s, user&.id ]
+
+        existing = store[key]
+        if existing == RESOLVING
+          raise ScopeError,
+                "inheritance recursion detected for parent " \
+                "#{parent_name.inspect} (user_id=#{user&.id}); " \
+                "inherits_from cycle escaped validation"
+        end
+        return existing if store.key?(key) && existing != RESOLVING
+
+        store[key] = RESOLVING
+        begin
+          store[key] = resolve_parent_scope(parent_name, user)
+        rescue
+          # Roll back the sentinel so a retry surfaces the original error
+          # rather than a "recursion detected" red herring.
+          store.delete(key)
+          raise
+        end
+      end
+
+      # Test/console helper. Production code should rely on Rails' automatic
+      # CurrentAttributes reset at request boundaries.
+      def self.clear!
+        LcpRuby::Current.authz_scopes = nil
+        LcpRuby::Current.authz_policies = nil
+      end
+
+      class << self
+        private
+
+        def resolve_parent_scope(parent_name, user)
+          unless LcpRuby.registry.registered?(parent_name)
+            raise ScopeError,
+                  "no AR class registered for parent '#{parent_name}'"
+          end
+
+          parent_class = LcpRuby.registry.model_for(parent_name)
+          policy_class = policy_for(parent_name)
+          policy_class::Scope.new(user, parent_class).resolve
+        end
+      end
+    end
+  end
+end

data/lib/lcp_ruby/authorization/codes.rb

@@ -0,0 +1,17 @@
+module LcpRuby
+  module Authorization
+    # Single source of truth for runtime authorization codes emitted via
+    # `LcpRuby.record_error`. Boot-time validator codes (AUTH-001..009)
+    # live in `InvariantCheck::Configuration::DEFAULT_SEVERITIES`; these
+    # runtime codes are NOT severity-configurable.
+    #
+    # See docs/reference/invariant_check.md § "Runtime-only codes" for
+    # the contract.
+    module Codes
+      AUTH_002_RUNTIME = "AUTH-002-runtime".freeze # standalone page reached with no gate
+      AUTH_003          = "AUTH-003".freeze         # malformed visible_when shape
+      AUTH_010          = "AUTH-010".freeze         # visible_when evaluator raised
+      AUTH_011          = "AUTH-011".freeze         # PageAuthorization wiring sentinel
+    end
+  end
+end

data/lib/lcp_ruby/authorization/impersonated_user.rb

@@ -0,0 +1,29 @@
+require "delegate"
+
+module LcpRuby
+  class ImpersonatedUser < SimpleDelegator
+    def initialize(real_user, impersonated_role)
+      super(real_user)
+      @impersonated_role = impersonated_role
+    end
+
+    # Override role method to return impersonated role.
+    # Override group method to return [] — impersonation suppresses group-derived roles.
+    # Handles both the default methods and any custom role_method/group_method.
+    def method_missing(method_name, *args, &block)
+      if method_name == LcpRuby.configuration.role_method
+        [ @impersonated_role ]
+      elsif method_name == LcpRuby.configuration.group_method
+        []
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      method_name == LcpRuby.configuration.role_method ||
+        method_name == LcpRuby.configuration.group_method ||
+        super
+    end
+  end
+end

data/lib/lcp_ruby/authorization/includes_hint.rb

@@ -0,0 +1,110 @@
+module LcpRuby
+  module Authorization
+    # Builds an `ActiveRecord::Relation#includes` argument that preloads the
+    # parent associations along an `inherits_from` cascade. Composes
+    # recursively so a 3-tier chain `grade → student → school_class`
+    # yields `{ student: { school_class: {} } }` — preloading just the
+    # immediate parent is not enough when the parent's own scope traverses
+    # further.
+    #
+    # The hint is purely additive: AR's `.includes` is associative and
+    # idempotent, so callers may chain their own `.includes(...)` on top
+    # (e.g. presenter-driven `IncludesResolver`) and the result is one
+    # consolidated preload graph.
+    #
+    # See `docs/design/hierarchical_record_permissions.md` § 6.7
+    # (Increment 3 of hierarchical record permissions).
+    module IncludesHint
+      module_function
+
+      # Returns one of:
+      #   nil          — scope has no inheritance to preload
+      #   Hash         — `{ assoc: <child> }` per parent (always a Hash for
+      #                  the `inherits` branch)
+      #   Array        — top-level `union` of multiple branches; AR accepts
+      #                  mixed `[:a, { b: :c }]`.
+      #
+      # `model_class` is the AR class the scope spec applies to (needed to
+      # resolve the `belongs_to` reflection name from the parent model name
+      # — handles `via:` overrides via `AssociationLookup`).
+      #
+      # `roles` is the list already computed by the caller
+      # (`PermissionEvaluator#roles`) — passed through so we don't re-walk
+      # the role resolver per parent and so the unit specs can drive the
+      # helper without a real `User`.
+      #
+      # Bounded by `max_inheritance_depth` (also enforced by
+      # `ConfigurationValidator#detect_inheritance_cycle` at boot) so a
+      # malformed cycle here cannot loop forever.
+      def build(scope_spec, model_class, roles, depth = 0)
+        return nil unless scope_spec.is_a?(Hash)
+        return nil if depth > LcpRuby.configuration.max_inheritance_depth
+
+        case scope_spec["type"]
+        when "inherits"
+          build_inherits(scope_spec, model_class, roles, depth)
+        when "union"
+          build_union(scope_spec, model_class, roles, depth)
+        end
+      end
+
+      def build_inherits(scope_spec, model_class, roles, depth)
+        parents = Array(scope_spec["parent"])
+        explicit_via = scope_spec["via"]&.to_sym
+
+        result = parents.each_with_object({}) do |parent_name, acc|
+          assoc_name = explicit_via ||
+                       AssociationLookup.belongs_to_name_for(model_class, parent_name)
+          next unless assoc_name
+
+          parent_class = parent_class_for(parent_name)
+          child = nil
+          if parent_class
+            parent_spec = parent_scope_spec_for(parent_name, roles)
+            child = build(parent_spec, parent_class, roles, depth + 1)
+          end
+          acc[assoc_name] = normalize_child(child)
+        end
+        result.empty? ? nil : result
+      end
+
+      def build_union(scope_spec, model_class, roles, depth)
+        branches = Array(scope_spec["scopes"])
+                   .map { |s| build(s, model_class, roles, depth + 1) }
+                   .compact
+        branches.empty? ? nil : branches
+      end
+
+      def parent_class_for(parent_name)
+        return nil unless LcpRuby.registry.registered?(parent_name)
+        LcpRuby.registry.model_for(parent_name)
+      end
+
+      def parent_scope_spec_for(parent_name, roles)
+        # Use the source-aware resolver, not the YAML-only loader API:
+        # hosts running with `permission_source: :model` keep parent
+        # permissions in the DB, and the YAML-only path would silently
+        # break recursion at every DB-resolved hop (the immediate parent
+        # would still preload, but its own parent wouldn't).
+        perm_def = LcpRuby.loader.permission_definition(parent_name)
+        return nil unless perm_def
+        perm_def.merged_effective_scope_for(roles)
+      end
+
+      # `nil` collapses to `{}` — "preload this association, no further
+      # nesting". Hashes pass through. Anything else (Array from a nested
+      # union) wraps so AR sees the full mixed-shape argument it expects.
+      def normalize_child(child)
+        case child
+        when nil then {}
+        when Hash then child
+        else Array.wrap(child)
+        end
+      end
+
+      private_class_method :build_inherits, :build_union,
+                           :parent_class_for, :parent_scope_spec_for,
+                           :normalize_child
+    end
+  end
+end

data/lib/lcp_ruby/authorization/inherited_parent_validator.rb

@@ -0,0 +1,142 @@
+module LcpRuby
+  module Authorization
+    # Auto-applied to every dynamic AR model. Closes the design's "create
+    # attack vector" (§4.2 / §6.10): without this, a user with `crud:
+    # [create]` on a child model could submit `<fk>: <id>` pointing at a
+    # parent record they cannot see, because `inherited_record_check` skips
+    # the cascade for `:create` (the child does not yet exist, so no parent
+    # association traversal).
+    #
+    # Wiring on dynamic models — always-wire:
+    #   `ModelFactory::Builder#apply_inherited_parent_validator` calls
+    #   `validates_with(InheritedParentValidator)` unconditionally on every
+    #   dynamic AR model. The validator itself early-returns at runtime
+    #   when the model's currently-resolved permission has no
+    #   `inherits_from`. Always-wiring covers DB-backed `inherits_from`
+    #   declarations (`permission_source: :model`) that are not visible at
+    #   boot time but appear at the registry level — the runtime lookup
+    #   resolves through `Permissions::SourceResolver`.
+    #
+    # Wiring on `bind_to:` host AR models — smart-auto + opt-in:
+    #   Hosts opt INTO this validator (rather than receiving it
+    #   unconditionally) to keep host-managed AR classes' `validators`
+    #   arrays free of no-op LCP entries. The applicator
+    #   (`ModelFactory::InheritedParentValidatorApplicator`) is registered
+    #   in `BIND_TO_APPLICATOR_MAP`. `Engine.apply_bind_to_features`
+    #   smart-auto-includes it when the YAML permission for the bound
+    #   model declares `inherits_from`. Configurators with DB-backed perms
+    #   on bind_to models opt in explicitly via
+    #   `bind_to_apply: [inherited_parent_validator]`.
+    #
+    # The check itself uses the same per-request `Authorization::Cache`
+    # as the read-time cascade, so it imposes no extra cost on indexes
+    # or shows.
+    #
+    # Skip semantics:
+    #   * Permission has no `inherits_from` — most models. Validator
+    #     no-ops at runtime; the per-save overhead is one hash lookup.
+    #   * No `LcpRuby::Current.user` — seeds, console, raw model API, and
+    #     ExecutorJob without handler-specific setup all hit this path.
+    #     Validation no-ops silently to match the platform-wide convention
+    #     that authorization checks pass in system contexts.
+    #   * FK is nil — delegate to the configurator's `belongs_to ...,
+    #     required: true` declaration. "FK must be present" and "FK must
+    #     point at a visible record" are distinct concerns.
+    #
+    # Bypass paths (not enforced; documented as gaps):
+    #   * `update_columns` / `update_all` / `insert_all` / `upsert_all` skip
+    #     ActiveRecord validations per Rails design.
+    class InheritedParentValidator < ActiveModel::Validator
+      def validate(record)
+        inherits = inherits_from_for(record)
+        return unless inherits
+
+        user = LcpRuby::Current.user
+        return unless user
+
+        results = inherits[:parents].map do |parent_name|
+          assoc_name = inherits[:via] || AssociationLookup.belongs_to_name_for(record.class, parent_name)
+          next [ :skip, nil ] if assoc_name.nil?
+
+          fk_value = fk_value_for(record, assoc_name)
+          next [ :skip, nil ] if fk_value.nil?  # AR presence validation handles required FKs
+
+          parent_scope = Cache.parent_policy_scope(parent_name, user)
+          if parent_scope.exists?(id: fk_value)
+            [ :pass, assoc_name ]
+          else
+            [ :fail, assoc_name ]
+          end
+        end
+
+        # Mode handling here is intentionally NOT shared with
+        # `PermissionEvaluator#inherited_record_check` (which performs the
+        # read-time cascade). The two call sites have genuinely different
+        # output shapes:
+        #   - Read-time: returns boolean (visible / not visible) via
+        #     `parents_pass.all?` / `.any?` — :skip is collapsed into
+        #     "no visibility" because read-time has no notion of
+        #     "let AR presence handle it".
+        #   - Create-time (here): adds errors to a record per failed
+        #     association, with `:skip` (FK nil) deliberately neutral
+        #     so AR's own presence validation handles required-FK errors.
+        # A unified helper would either be too generic (re-deriving
+        # behavior at each call site) or fragmented (one helper per
+        # shape). Keeping them separate is the cleaner choice.
+        case inherits[:mode]
+        when "union"
+          # Reject only when no parent passes. Single error on first failed
+          # association (which one is arbitrary; users only need ANY parent
+          # visible). All-skip results in no error — AR presence handles
+          # the required-FK case for the user.
+          if results.none? { |r, _| r == :pass } && (failed = results.find { |r, _| r == :fail })
+            record.errors.add(failed[1], :inaccessible_parent, message: i18n_message)
+          end
+        else  # intersection (default)
+          # Reject every failed association so the user sees which FKs are problems.
+          # :skip results contribute nothing — AR presence handles them.
+          results.each do |result, assoc|
+            record.errors.add(assoc, :inaccessible_parent, message: i18n_message) if result == :fail
+          end
+        end
+      end
+
+      private
+
+      # Resolve the permission definition by deriving the model name from the
+      # AR class. Dynamic models live under LcpRuby::Dynamic::, so demodulize
+      # + underscore yields the registry key.
+      #
+      # Uses `permission_definition` (not `yaml_permission_definition`) so
+      # the lookup goes through `Permissions::SourceResolver` and picks up
+      # DB-backed inherits_from declarations at runtime. STI fallback is
+      # preserved through that resolver chain.
+      def inherits_from_for(record)
+        model_name = record.class.name.demodulize.underscore
+        perm_def = LcpRuby.loader.permission_definition(model_name)
+        perm_def&.inherits_from
+      end
+
+      # Read the FK either via `<assoc>_id` directly, or by traversing the
+      # association object. The traversal path covers nested-attributes saves
+      # where the parent is assigned as an object (no FK column write yet),
+      # so we fall through when `<assoc>_id` is present-but-nil.
+      #
+      # Uses `unless fk.nil?` (not `if fk`) so a falsy-but-non-nil FK value
+      # (e.g. integer 0, which can occur with custom keyspaces) is treated
+      # as a real FK to validate, not as "absent → fall through".
+      def fk_value_for(record, assoc_name)
+        fk_method = "#{assoc_name}_id"
+        fk = record.public_send(fk_method) if record.respond_to?(fk_method)
+        return fk unless fk.nil?
+
+        record.public_send(assoc_name)&.id if record.respond_to?(assoc_name)
+      end
+
+      def i18n_message
+        I18n.t("lcp_ruby.errors.inherited_parent.inaccessible",
+               default: "is not accessible to the current user")
+      end
+    end
+  end
+end