forest_admin_agent 1.39.1 → 1.39.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 428e77bbb38c12b3b742940d6389b10953d719dbbb01ee121130dd01f9eb8868
-  data.tar.gz: 1b87f61a2aceb41b7ecd1e1c65339374a3f50c9faccaaf48331cebbff73a8760
+  metadata.gz: 5002fa757fc6f7be665d7b966a47e8d7f69c600b0061092fc4ae0d9cd25ff2c7
+  data.tar.gz: efd52bb2fcc984e3cf589b3933cc5876c8f93071daad61084435fa71f50f276b
 SHA512:
-  metadata.gz: 0d1408d54a4650b3850fd62647704eaca320f376603639328d3e2356b0064adc1a2cbd05920040eafd0314fce89cba22fb09456b8244a9d6e238c21bc7c54b50
-  data.tar.gz: a30686d3e81a9febf50189dc66249922c288ab33c9868f51c6d91ff40c2ace58c512bd185e2dd2230c35bbf78e2823485db9ea5685f745bf4183c17a44c9bf64
+  metadata.gz: f02eff4908523d3f0d0e38bd1b673ecbdfc7c6aee8613c6c55fb0ef526a23eb22fe4a033f7a61d77f6a96176f7df7cde4d69a50460a7adf06a934bbf8a854d19
+  data.tar.gz: c9c02167321c811f1318edc433ef8f93b12f5e2bd74115c13983dcbcb8f9a3918c56ed1b34ba066a947c8115934e167203572d6558313cae3d3668ea171e9103

data/lib/forest_admin_agent/routes/abstract_authenticated_route.rb

@@ -12,6 +12,26 @@ module ForestAdminAgent
         context
       end
 
+      # Never refused: a write must not 403 because the row it just wrote carries a relation the
+      # caller cannot read.
+      def redacted_full_projection(context)
+        all = ForestAdminDatasourceToolkit::Components::Query::ProjectionFactory.all(context.collection)
+
+        context.permissions.redact_projection(context.collection, all, named_by_caller: false)
+      end
+
+      # +with_pks+ runs after the redaction on purpose. It only re-adds keys for relations the
+      # redaction kept a path through, and the serializer needs those keys to emit the readable
+      # column behind them — dropping them would take the permitted path down with them. A relation
+      # the redaction emptied contributes no path, so nothing is re-added for it.
+      def redacted_projection_with_pks(context, collection, args)
+        requested = Utils::QueryStringParser.parse_requested_projection(collection, args)
+
+        context.permissions.redact_projection(
+          collection, requested[:projection], named_by_caller: requested[:named_by_caller]
+        ).with_pks(collection)
+      end
+
       def format_attributes(args, collection)
         record = args[:params][:data][:attributes] || {}
 

data/lib/forest_admin_agent/routes/charts/charts.rb

@@ -28,15 +28,14 @@ module ForestAdminAgent
         def handle_request(args = {})
           context = build(args)
           context.permissions.can_chart?(args[:params])
+          condition_tree = ForestAdminAgent::Utils::QueryStringParser.parse_condition_tree(
+            context.collection, args
+          )
+          context.permissions.assert_can_read_query_fields(context.collection, condition_tree: condition_tree)
           type = validate_and_get_type(args[:params][:type])
           filter = Filter.new(
             condition_tree: ConditionTreeFactory.intersect(
-              [
-                context.permissions.get_scope(context.collection),
-                ForestAdminAgent::Utils::QueryStringParser.parse_condition_tree(
-                  context.collection, args
-                )
-              ]
+              [context.permissions.get_scope(context.collection), condition_tree]
             )
           )
 
@@ -47,6 +46,15 @@ module ForestAdminAgent
 
         private
 
+        # An empty `aggregateFieldName` is a count, and `can_chart?` cannot tell it from an absent
+        # one — `sanitize_chart_parameters` drops both before hashing. Normalising here keeps the
+        # aggregation and the guards that read it from disagreeing on what a count is.
+        def aggregate_field_name(args)
+          field = args[:params][:aggregateFieldName]
+
+          field.nil? || field.to_s.empty? ? nil : field
+        end
+
         def validate_and_get_type(type)
           chart_types = %w[Value Objective Pie Line Leaderboard]
           unless chart_types.include?(type)
@@ -89,9 +97,13 @@ module ForestAdminAgent
 
         def make_pie(context, filter, args)
           group_field = args[:params][:groupByFieldName]
+          assert_can_read_aggregated_fields(
+            context, context.collection,
+            [['group a chart by', group_field], ['aggregate a chart on', aggregate_field_name(args)]]
+          )
           aggregation = Aggregation.new(
             operation: args[:params][:aggregator],
-            field: args[:params][:aggregateFieldName],
+            field: aggregate_field_name(args),
             groups: group_field ? [{ field: group_field }] : []
           )
 
@@ -102,6 +114,11 @@ module ForestAdminAgent
 
         def make_line(context, filter, args)
           group_by_field_name = args[:params][:groupByFieldName]
+          assert_can_read_aggregated_fields(
+            context, context.collection,
+            [['group a chart by', group_by_field_name],
+             ['aggregate a chart on', aggregate_field_name(args)]]
+          )
           time_range = args[:params][:timeRange]
           filter_only_with_values = filter.override(
             condition_tree: ConditionTree::ConditionTreeFactory.intersect(
@@ -116,7 +133,7 @@ module ForestAdminAgent
             filter_only_with_values,
             Aggregation.new(
               operation: args[:params][:aggregator],
-              field: args[:params][:aggregateFieldName],
+              field: aggregate_field_name(args),
               groups: [{ field: group_by_field_name, operation: time_range }]
             )
           )
@@ -151,7 +168,7 @@ module ForestAdminAgent
               leaderboard_filter = filter.nest(inverse)
               aggregation = Aggregation.new(
                 operation: args[:params][:aggregator],
-                field: args[:params][:aggregateFieldName],
+                field: aggregate_field_name(args),
                 groups: [{ field: "#{inverse}:#{args[:params][:labelFieldName]}" }]
               )
             end
@@ -171,13 +188,25 @@ module ForestAdminAgent
               leaderboard_filter = filter.nest(origin)
               aggregation = Aggregation.new(
                 operation: args[:params][:aggregator],
-                field: args[:params][:aggregateFieldName] ? "#{target}:#{args[:params][:aggregateFieldName]}" : nil,
+                field: aggregate_field_name(args) ? "#{target}:#{aggregate_field_name(args)}" : nil,
                 groups: [{ field: "#{origin}:#{args[:params][:labelFieldName]}" }]
               )
             end
           end
 
           if collection && leaderboard_filter && aggregation
+            assert_can_read_aggregated_fields(
+              context, context.datasource.get_collection(collection),
+              [['group a leaderboard by', aggregation.groups[0][:field]],
+               ['aggregate a leaderboard on', aggregation.field]]
+            )
+
+            # A count exposes the cardinality of the relation, which `/relationships/<name>/count`
+            # puts behind `browse`. No path names it, so nothing above sees it.
+            if aggregation.field.nil?
+              context.permissions.can?(:browse, context.datasource.get_collection(field.foreign_collection))
+            end
+
             rows = context.datasource.get_collection(collection).aggregate(
               context.caller,
               leaderboard_filter,
@@ -200,12 +229,33 @@ module ForestAdminAgent
         end
 
         def compute_value(context, filter, args)
+          assert_can_read_aggregated_fields(
+            context, context.collection,
+            [['aggregate a chart on', aggregate_field_name(args)]]
+          )
           aggregation = Aggregation.new(operation: args[:params][:aggregator],
-                                        field: args[:params][:aggregateFieldName])
+                                        field: aggregate_field_name(args))
           result = context.collection.aggregate(context.caller, filter, aggregation)
 
           result[0]['value'] || 0
         end
+
+        # The permission root stays the chart's own collection, which the leaderboard call site does
+        # not share with the collection its paths resolve against.
+        def assert_can_read_aggregated_fields(context, path_collection, fields)
+          usages = fields.reject { |_action, path| path.nil? || path.to_s.empty? }
+                         .map do |action, path|
+            {
+              action: action,
+              path: path,
+              collections: ForestAdminDatasourceToolkit::Utils::FieldPath.leaf_collection_names(
+                path_collection, path
+              )
+            }
+          end
+
+          context.permissions.assert_can_read_usages(context.collection.name, usages)
+        end
       end
     end
   end

data/lib/forest_admin_agent/routes/resources/count.rb

@@ -19,16 +19,26 @@ module ForestAdminAgent
           context.permissions.can?(:browse, context.collection)
 
           if context.collection.is_countable?
+            condition_tree = ForestAdminAgent::Utils::QueryStringParser.parse_condition_tree(
+              context.collection, args
+            )
+            search = QueryStringParser.parse_search(context.collection, args)
+            search_extended = QueryStringParser.parse_search_extended(args)
+            context.permissions.assert_can_read_query_fields(
+              context.collection,
+              condition_tree: condition_tree, search: search, search_extended: search_extended
+            )
+
             filter = ForestAdminDatasourceToolkit::Components::Query::Filter.new(
               condition_tree: ConditionTreeFactory.intersect(
                 [
                   context.permissions.get_scope(context.collection),
                   parse_query_segment(context.collection, args, context.permissions, context.caller),
-                  ForestAdminAgent::Utils::QueryStringParser.parse_condition_tree(context.collection, args)
+                  condition_tree
                 ]
               ),
-              search: QueryStringParser.parse_search(context.collection, args),
-              search_extended: QueryStringParser.parse_search_extended(args),
+              search: search,
+              search_extended: search_extended,
               segment: QueryStringParser.parse_segment(context.collection, args)
             )
             aggregation = ForestAdminDatasourceToolkit::Components::Query::Aggregation.new(operation: 'Count')

data/lib/forest_admin_agent/routes/resources/csv.rb

@@ -22,25 +22,38 @@ module ForestAdminAgent
           context = build(args)
           context.permissions.can?(:browse, context.collection)
           context.permissions.can?(:export, context.collection)
+
+          condition_tree = QueryStringParser.parse_condition_tree(context.collection, args)
+          search = QueryStringParser.parse_search(context.collection, args)
+          search_extended = QueryStringParser.parse_search_extended(args)
+          sort = QueryStringParser.parse_sort(context.collection, args)
+          context.permissions.assert_can_read_query_fields(
+            context.collection,
+            condition_tree: condition_tree, sort: sort, search: search, search_extended: search_extended
+          )
+
           filter = ForestAdminDatasourceToolkit::Components::Query::Filter.new(
             condition_tree: ConditionTreeFactory.intersect(
               [
                 context.permissions.get_scope(context.collection),
                 parse_query_segment(context.collection, args, context.permissions, context.caller),
-                QueryStringParser.parse_condition_tree(
-                  context.collection, args
-                )
+                condition_tree
               ]
             ),
-            search: QueryStringParser.parse_search(context.collection, args),
-            search_extended: QueryStringParser.parse_search_extended(args),
-            sort: QueryStringParser.parse_sort(context.collection, args),
+            search: search,
+            search_extended: search_extended,
+            sort: sort,
             segment: QueryStringParser.parse_segment(context.collection, args)
           )
-          projection = QueryStringParser.parse_projection_from_request(context.collection, args)
+          requested = QueryStringParser.parse_requested_projection(context.collection, args)
+          projection = context.permissions.redact_projection(
+            context.collection,
+            requested[:projection],
+            named_by_caller: requested[:named_by_caller]
+          )
           filename = args[:params][:filename] || args[:params]['collection_name']
           filename += '.csv' unless /\.csv$/i.match?(filename)
-          header = args[:params][:header]
+          header = Utils::CsvGenerator.filter_header(args[:params][:header], requested[:projection], projection)
 
           # Generate timestamp for filename
           now = Time.now.strftime('%Y%m%d_%H%M%S')

data/lib/forest_admin_agent/routes/resources/list.rb

@@ -18,22 +18,31 @@ module ForestAdminAgent
           context = build(args)
           context.permissions.can?(:browse, context.collection)
 
+          condition_tree = QueryStringParser.parse_condition_tree(context.collection, args)
+          search = QueryStringParser.parse_search(context.collection, args)
+          search_extended = QueryStringParser.parse_search_extended(args)
+          sort = QueryStringParser.parse_sort(context.collection, args)
+          context.permissions.assert_can_read_query_fields(
+            context.collection,
+            condition_tree: condition_tree, sort: sort, search: search, search_extended: search_extended
+          )
+
           filter = ForestAdminDatasourceToolkit::Components::Query::Filter.new(
             condition_tree: ConditionTreeFactory.intersect(
               [
                 context.permissions.get_scope(context.collection),
-                QueryStringParser.parse_condition_tree(context.collection, args),
+                condition_tree,
                 parse_query_segment(context.collection, args, context.permissions, context.caller)
               ]
             ),
             page: QueryStringParser.parse_pagination(args),
-            search: QueryStringParser.parse_search(context.collection, args),
-            search_extended: QueryStringParser.parse_search_extended(args),
-            sort: QueryStringParser.parse_sort(context.collection, args),
+            search: search,
+            search_extended: search_extended,
+            sort: sort,
             segment: QueryStringParser.parse_segment(context.collection, args)
           )
 
-          projection = QueryStringParser.parse_projection_with_pks(context.collection, args)
+          projection = redacted_projection_with_pks(context, context.collection, args)
           records = context.collection.list(context.caller, filter, projection)
 
           {

data/lib/forest_admin_agent/routes/resources/related/csv_related.rb

@@ -23,18 +23,26 @@ module ForestAdminAgent
             context = build(args)
             context.permissions.can?(:browse, context.child_collection)
             context.permissions.can?(:export, context.child_collection)
+            condition_tree = ForestAdminAgent::Utils::QueryStringParser.parse_condition_tree(
+              context.child_collection, args
+            )
+            context.permissions.assert_can_read_query_fields(
+              context.child_collection, condition_tree: condition_tree
+            )
 
             filter = ForestAdminDatasourceToolkit::Components::Query::Filter.new(
               condition_tree: ConditionTreeFactory.intersect(
-                [
-                  context.permissions.get_scope(context.child_collection),
-                  ForestAdminAgent::Utils::QueryStringParser.parse_condition_tree(context.child_collection, args)
-                ]
+                [context.permissions.get_scope(context.child_collection), condition_tree]
               )
             )
-            projection = ForestAdminAgent::Utils::QueryStringParser.parse_projection_from_request(
+            requested = ForestAdminAgent::Utils::QueryStringParser.parse_requested_projection(
               context.child_collection, args
             )
+            projection = context.permissions.redact_projection(
+              context.child_collection,
+              requested[:projection],
+              named_by_caller: requested[:named_by_caller]
+            )
 
             # Get the parent record primary keys
             primary_key_values = Utils::Id.unpack_id(context.collection, args[:params]['id'], with_key: true)
@@ -43,7 +51,9 @@ module ForestAdminAgent
             # Generate timestamp for filename
             now = Time.now.strftime('%Y%m%d_%H%M%S')
             collection_name = args.dig(:params, 'collection_name')
-            header = args.dig(:params, 'header')
+            header = ForestAdminAgent::Utils::CsvGenerator.filter_header(
+              args.dig(:params, 'header'), requested[:projection], projection
+            )
             filename_with_timestamp = "#{collection_name}_#{relation_name}_export_#{now}.csv"
 
             # Create a callable to fetch related records

data/lib/forest_admin_agent/routes/resources/related/list_related.rb

@@ -23,19 +23,22 @@ module ForestAdminAgent
           def handle_request(args = {})
             context = build(args)
             context.permissions.can?(:browse, context.child_collection)
+            condition_tree = ForestAdminAgent::Utils::QueryStringParser.parse_condition_tree(
+              context.child_collection, args
+            )
+            sort = ForestAdminAgent::Utils::QueryStringParser.parse_sort(context.child_collection, args)
+            context.permissions.assert_can_read_query_fields(
+              context.child_collection, condition_tree: condition_tree, sort: sort
+            )
 
             filter = ForestAdminDatasourceToolkit::Components::Query::Filter.new(
               condition_tree: ConditionTreeFactory.intersect(
-                [
-                  context.permissions.get_scope(context.child_collection),
-                  ForestAdminAgent::Utils::QueryStringParser.parse_condition_tree(context.child_collection, args)
-                ]
+                [context.permissions.get_scope(context.child_collection), condition_tree]
               ),
               page: ForestAdminAgent::Utils::QueryStringParser.parse_pagination(args),
-              sort: ForestAdminAgent::Utils::QueryStringParser.parse_sort(context.child_collection, args)
+              sort: sort
             )
-            projection = ForestAdminAgent::Utils::QueryStringParser.parse_projection_with_pks(context.child_collection,
-                                                                                              args)
+            projection = redacted_projection_with_pks(context, context.child_collection, args)
             primary_key_values = Utils::Id.unpack_id(context.collection, args[:params]['id'], with_key: true)
             records = Collection.list_relation(
               context.collection,

data/lib/forest_admin_agent/routes/resources/show.rb

@@ -25,7 +25,7 @@ module ForestAdminAgent
             condition_tree: ConditionTree::ConditionTreeFactory.intersect([condition_tree, scope])
           )
 
-          projection = QueryStringParser.parse_projection_with_pks(context.collection, args)
+          projection = redacted_projection_with_pks(context, context.collection, args)
 
           records = context.collection.list(context.caller, filter, projection)
 

data/lib/forest_admin_agent/routes/resources/store.rb

@@ -25,7 +25,8 @@ module ForestAdminAgent
           filter = ForestAdminDatasourceToolkit::Components::Query::Filter.new(
             condition_tree: ConditionTree::ConditionTreeFactory.match_ids(context.collection, [id])
           )
-          records = context.collection.list(context.caller, filter, ProjectionFactory.all(context.collection))
+          projection = redacted_full_projection(context)
+          records = context.collection.list(context.caller, filter, projection)
 
           {
             name: args[:params]['collection_name'],

data/lib/forest_admin_agent/routes/resources/update.rb

@@ -26,7 +26,8 @@ module ForestAdminAgent
           drop_relationships!(args)
           data = format_attributes(args, context.collection)
           context.collection.update(context.caller, filter, data)
-          records = context.collection.list(context.caller, filter, ProjectionFactory.all(context.collection))
+          projection = redacted_full_projection(context)
+          records = context.collection.list(context.caller, filter, projection)
 
           {
             name: args[:params]['collection_name'],

data/lib/forest_admin_agent/routes/resources/update_field.rb

@@ -51,7 +51,8 @@ module ForestAdminAgent
           )
           context.collection.update(context.caller, filter, { field_name => updated_array })
 
-          records = context.collection.list(context.caller, filter, ProjectionFactory.all(context.collection))
+          projection = redacted_full_projection(context)
+          records = context.collection.list(context.caller, filter, projection)
 
           {
             name: args[:params]['collection_name'],
@@ -93,7 +94,8 @@ module ForestAdminAgent
           filter = ForestAdminDatasourceToolkit::Components::Query::Filter.new(
             condition_tree: ConditionTree::ConditionTreeFactory.intersect([condition_tree, scope])
           )
-          records = context.collection.list(context.caller, filter, ProjectionFactory.all(context.collection))
+          projection = redacted_full_projection(context)
+          records = context.collection.list(context.caller, filter, projection)
 
           raise Http::Exceptions::NotFoundError, 'Record not found' unless records&.any?
 

data/lib/forest_admin_agent/services/permissions.rb

@@ -53,6 +53,83 @@ module ForestAdminAgent
         is_allowed
       end
 
+      # +root_collection_name+ is pinned to readable and never looked up: +browse+ already gates a
+      # listing, +read+ a get, and the signed hash a chart.
+      #
+      # Answered once per collection for the whole request: +redact_projection+ and
+      # +assert_can_read_query_fields+ both ask on a listing, and a chart asks three times.
+      def read_permissions(root_collection_name, collection_names)
+        to_check = collection_names.uniq.reject { |name| name == root_collection_name }
+        allowed = { root_collection_name => true }
+
+        return allowed if to_check.empty?
+
+        # An absent permission system is not a denial: `can?` allows everything there, and answering
+        # anything else would redact every relation on a deployment that granted nothing to check.
+        return allowed.merge(to_check.to_h { |name| [name, true] }) unless permission_system?
+
+        @read_permissions ||= {}
+        missing = to_check - @read_permissions.keys
+        @read_permissions.merge!(fetch_read_permissions(missing)) unless missing.empty?
+
+        allowed.merge(@read_permissions.slice(*to_check))
+      end
+
+      # An unnamed field is dropped rather than refused: the default expansion covers every column
+      # of every to-one relation, so refusing would turn an ordinary listing into a 403 for a caller
+      # that asked for nothing.
+      def redact_projection(collection, projection, named_by_caller:)
+        owners = projection.to_h do |path|
+          [path, ForestAdminDatasourceToolkit::Utils::FieldPath.leaf_collection_names(collection, path)]
+        end
+        allowed = read_permissions(collection.name, owners.values.flatten)
+        readable = ->(path) { readable_leaves?(owners[path], allowed) }
+
+        if named_by_caller
+          denied = projection.reject { |path| readable.call(path) }
+
+          unless denied.empty?
+            fields = denied.map { |path| "'#{path}' from #{leaf_label(owners[path])}" }
+            raise ForbiddenError, "You are not allowed to read #{fields.join(", ")}."
+          end
+        end
+
+        ForestAdminDatasourceToolkit::Components::Query::Projection.new(projection.select { |path| readable.call(path) })
+      end
+
+      # Refused rather than redacted: dropping a condition widens the result set and dropping a sort
+      # clause silently reorders it, while both leak the value they touch anyway — a `starts_with`
+      # filter answers one guess per request without returning a column of its own.
+      #
+      # The route passes the components it will actually apply, already parsed. A component it drops
+      # is simply one it does not pass — a count carries no sort, a chart neither sort nor search — so
+      # nothing has to be declared alongside the query and then kept in step with it. What is
+      # authorised here is what the filter carries, not a second parse of the same parameters.
+      def assert_can_read_query_fields(collection, condition_tree: nil, sort: nil, search: nil,
+                                       search_extended: false)
+        usages = []
+
+        # `projection` collects the leaf fields without touching the tree. The route applies this very
+        # instance next, so a traversal that rebuilt a branch — as `for_each_leaf` does — would leave
+        # the guard deciding what runs.
+        condition_tree&.projection&.each { |path| usages << usage('filter on', collection, path) }
+        sort&.each { |clause| usages << usage('sort on', collection, clause[:field]) }
+        collect_search_usages(collection, search, search_extended, usages)
+
+        assert_can_read_usages(collection.name, usages)
+      end
+
+      def assert_can_read_usages(root_collection_name, usages)
+        allowed = read_permissions(root_collection_name, usages.flat_map { |usage| usage[:collections] })
+        denied = usages.find { |usage| !readable_leaves?(usage[:collections], allowed) }
+
+        return unless denied
+
+        raise ForbiddenError,
+              "You cannot #{denied[:action]} '#{denied[:path]}': you are not allowed to read " \
+              "#{leaf_label(denied[:collections])}."
+      end
+
       def can_chart?(parameters)
         attributes = sanitize_chart_parameters(parameters.deep_symbolize_keys)
         hash_request = "#{attributes[:type]}:#{array_hash(attributes)}"
@@ -188,6 +265,103 @@ module ForestAdminAgent
 
       private
 
+      # An empty list of leaves resolves to no collection at all — a polymorphic relation declaring
+      # no `foreign_collections`. `[].all?` would allow it unconditionally, which is the one answer
+      # this guard must never give by default, so it counts as denied.
+      def readable_leaves?(names, allowed)
+        names.any? && names.all? { |name| allowed[name] }
+      end
+
+      def leaf_label(names)
+        names.empty? ? 'an unresolved polymorphic relation' : "the '#{names.join("' or '")}' collection"
+      end
+
+      def fetch_read_permissions(names)
+        user_data = get_user_data(caller.id)
+        collections_data = get_collections_permissions_data
+        results = names.to_h { |name| [name, read_allowed?(collections_data, name, user_data)] }
+
+        return results if results.values.all? || !refetch_denied_reads?(names, collections_data)
+
+        @read_permissions_refetched = true
+        refetched = get_collections_permissions_data(force_fetch: true)
+
+        names.to_h { |name| [name, read_allowed?(refetched, name, user_data)] }
+      end
+
+      # `can?` refetches the whole environment on every denial. Denial is the steady state of this
+      # check rather than the exception, so paying that per denial would cost a permission fetch, and
+      # a cache eviction every other in-flight request reads through, on each page load.
+      #
+      # Two things make a denial worth one fetch. Without `instant_cache_refresh` nothing else keeps
+      # the cache fresh — this is the gate node puts its own refetch behind — so a role granted `read`
+      # would otherwise stay redacted until the cache expires. With the channel up, `refresh-roles`
+      # evicts on a role change, and the only denial staleness still explains is a collection the
+      # payload has never heard of.
+      def refetch_denied_reads?(names, collections_data)
+        return false if @read_permissions_refetched
+
+        !instant_cache_refresh? || names.any? { |name| !collections_data.key?(name.to_sym) }
+      end
+
+      def instant_cache_refresh?
+        Facades::Container.config_from_cache[:instant_cache_refresh] == true
+      end
+
+      def read_allowed?(collections_data, collection_name, user_data)
+        return false unless user_data_valid?(user_data)
+
+        collection_key = collection_name.to_sym
+        return false unless collection_exists?(collections_data, collection_key, collection_name, user_data)
+
+        role_ids = get_role_ids_for_action(collections_data, collection_key, :read, collection_name, user_data)
+        return false unless role_ids
+
+        check_user_permission(role_ids, user_data, :read, collection_name)
+      end
+
+      def usage(action, collection, path)
+        {
+          action: action,
+          path: path,
+          collections: ForestAdminDatasourceToolkit::Utils::FieldPath.leaf_collection_names(collection, path)
+        }
+      end
+
+      def collect_search_usages(collection, search, search_extended, usages)
+        return if search.nil? || !collection.respond_to?(:searched_fields)
+
+        searched = collection.searched_fields(search, search_extended)
+
+        return if searched.nil?
+
+        published = collection.datasource.collections
+
+        searched.each do |field|
+          assert_search_target_exposed(field, published)
+          usages << { action: 'search on', path: field[:path], collections: field[:collections] }
+        end
+      end
+
+      # `searched_fields` answers below the publication layer — deliberately, so a field hidden by
+      # renaming above it is still checked — so it can name a collection `remove_collection` took out
+      # of the API. An extended search does reach through to it: the condition is built below
+      # publication, which has already passed the filter down and cannot strip it.
+      #
+      # That collection is absent from the permission payload too, so asking `read_allowed?` answers
+      # "denied" for every role, admins included, and no grant can lift it. So it is refused as what
+      # it is — a column the agent does not expose — which points at `disable_search` or publishing
+      # the collection again rather than at a permission to grant.
+      def assert_search_target_exposed(field, published)
+        unexposed = field[:collections].reject { |name| published.key?(name) }
+
+        return if unexposed.empty?
+
+        raise ForbiddenError,
+              "You cannot search on '#{field[:path]}': the '#{unexposed.join("' or '")}' collection " \
+              'is not exposed by this agent.'
+      end
+
       def permission_allowed?(collections_data, collection, action, user_data)
         return false unless user_data_valid?(user_data)
 

data/lib/forest_admin_agent/utils/csv_generator.rb

@@ -3,6 +3,46 @@ require 'csv'
 module ForestAdminAgent
   module Utils
     class CsvGenerator
+      # Labels are positionally aligned with the requested projection, so dropping a field without
+      # dropping its label shifts every later value under the wrong heading.
+      # The header carries one label per exported column, so a label survives exactly when the
+      # projection path at its index did.
+      #
+      # A count that does not match the requested projection cannot be mapped onto columns — a to-one
+      # relation expanded into several paths, or a polymorphic type field appended — and there is then
+      # no header to hand back. Returning the original would leave `CsvGeneratorStream.parse_header`
+      # to check it against the *kept* count instead, so labels that happen to match the redacted
+      # column count would be accepted, printing each surviving column under the label of whatever
+      # preceded it. `nil` is what makes the stream fall back to the field paths.
+      #
+      # Handing it back untouched is only safe on the branch above, where nothing was redacted: there
+      # the two counts are the same number, so the stream's own check cannot reach a different answer.
+      def self.filter_header(header, requested, kept)
+        return header if header.nil? || kept.size == requested.size
+
+        labels = parse_header_labels(header)
+
+        return nil unless labels&.size == requested.size
+
+        labels.each_with_index
+              .select { |_label, index| kept.include?(requested[index]) }
+              .map(&:first)
+      end
+
+      # The front joins the labels with commas; a JSON array comes from older callers.
+      def self.parse_header_labels(header)
+        return header if header.is_a?(Array)
+        return nil unless header.is_a?(String)
+
+        parsed = begin
+          JSON.parse(header)
+        rescue JSON::ParserError
+          nil
+        end
+
+        parsed.is_a?(Array) ? parsed : header.split(',', -1)
+      end
+
       def self.generate(records, projection)
         data = {}
         projection.each do |schema_field|

data/lib/forest_admin_agent/utils/csv_generator_stream.rb

@@ -16,8 +16,9 @@ module ForestAdminAgent
       def self.stream(header, filter, projection, list_records, limit_export_size = nil)
         Enumerator.new do |yielder|
           # Yield header row first (client receives immediately)
-          header_array = parse_header(header, projection)
-          yielder << "#{header_array.join(",")}\n"
+          # Escaped like any other row: the labels are the caller's, and one carrying a comma or a
+          # quote would otherwise emit a header row wider than the data under it.
+          yielder << CSV.generate_line(parse_header(header, projection))
 
           offset = 0
 
@@ -58,23 +59,14 @@ module ForestAdminAgent
       end
 
       # Parse header parameter into an array
-      # @param header [String, Array, nil] Header as JSON string, array, or nil
-      # @param projection [Projection] Field projection (fallback if header is invalid)
-      # @return [Array<String>] Header fields
+      # @param header [String, Array, nil] Header as a comma-joined string, JSON array, array or nil
+      # @param projection [Projection] Field projection
+      # @return [Array<String>] The labels when there is exactly one per exported column, the field
+      #   paths otherwise — a header that cannot be mapped onto the columns would mislabel them
       def self.parse_header(header, projection)
-        case header
-        when Array
-          header
-        when String
-          return projection.to_a if header.empty?
+        labels = CsvGenerator.parse_header_labels(header)
 
-          JSON.parse(header)
-        else
-          projection.to_a
-        end
-      rescue JSON::ParserError
-        # Fallback to projection if JSON parsing fails
-        projection.to_a
+        labels&.size == projection.size ? labels : projection.to_a
       end
 
       # Generate CSV row from record data

data/lib/forest_admin_agent/utils/query_string_parser.rb

@@ -66,6 +66,22 @@ module ForestAdminAgent
         parse_projection_from_header(collection, args) || parse_projection(collection, args)
       end
 
+      # Both halves read the same `fields` param the same way on purpose: an empty
+      # `fields[<collection>]=` means "every column", so it is not named and must take the redaction
+      # path rather than a 403.
+      def self.parse_requested_projection(collection, args)
+        from_header = parse_projection_from_header(collection, args)
+
+        return { projection: from_header, named_by_caller: true } if from_header
+
+        fields = args.dig(:params, :fields, collection.name)
+
+        {
+          projection: parse_projection(collection, args),
+          named_by_caller: !(fields.nil? || fields == '')
+        }
+      end
+
       def self.add_polymorphic_type_fields(collection, requested_field_names)
         polymorphic_relations = collection.schema[:fields].select { |_, field| field.type == 'PolymorphicManyToOne' }
 

data/lib/forest_admin_agent/utils/schema/schema_emitter.rb

@@ -6,7 +6,7 @@ module ForestAdminAgent
     module Schema
       class SchemaEmitter
         LIANA_NAME = "agent-ruby"
-        LIANA_VERSION = "1.39.1"
+        LIANA_VERSION = "1.39.2"
 
         def self.generate(datasource)
           datasource.collections

data/lib/forest_admin_agent/version.rb

@@ -1,3 +1,3 @@
 module ForestAdminAgent
-  VERSION = "1.39.1"
+  VERSION = "1.39.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forest_admin_agent
 version: !ruby/object:Gem::Version
-  version: 1.39.1
+  version: 1.39.2
 platform: ruby
 authors:
 - Matthieu
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-20 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport