forest_admin_agent 1.44.0 → 1.44.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 765a7dfcd6479eadd50782c2d72e2fa6d14e2f0cd5858cd56b53279fb319f52d
-  data.tar.gz: 869b66b6a89dcbaf78887428fc8b9d5dd823629204c1c25cc6e7a3bf6645c0be
+  metadata.gz: eb144d36d50f4763b0b8f2e61e701ee5fbfb7a97b66b4a9a6f67aaff26b8ac5d
+  data.tar.gz: c6f7817f4a8507b703c604b8c4c643884eb57b8d0902cd90437e6ffe1b201238
 SHA512:
-  metadata.gz: ef2ffa8474a150773b31add6d108ea351d4be7aac9f176e14967576f0718998d7a025d82d894d53c82736115165f92dd50f655e43afc1cb579b41b2cdd054f2f
-  data.tar.gz: f34499524fc80e0194f2341e14c0e5b373beca8a95fa1d4ae46a912bea35747d34d21819170acfee83f082b67703656bee4a7d152c08f2b834b5fb4916fecb5a
+  metadata.gz: c76840f3a4d7823a6395b6926e5ba60cb018f8acc30f6166773334ce6e966292b410001ad262a26cf0ca36580bf08dfcd0c0451821f52552919c37ec242083a7
+  data.tar.gz: fd08b9086757654dd821a909376648fa0f1a7274b18118cf734573bfc99f1818fabc063f085c72d1bccd7d94a8852f299aa0cd23703a3588d55f81a33a12f03b

data/AUDIT_TRAIL.md

@@ -190,6 +190,43 @@ A record that no longer exists keeps its history: only a record that still exist
 caller's permission scope is refused (404). Inspecting what was deleted is much of the point of an
 audit trail, and the delete event itself is the last thing recorded.
 
+Those rows still carry the column values captured while the record existed, and a scope that can no
+longer be evaluated against the record is evaluated against the values instead: a `delete` row keeps
+its `previousValues` only if they match the scope, a `create` row its `newValues`, and an `update`
+row — whose two sides are a partial diff — is tested side by side, so each is kept only if its own
+values match. Action rows hold a submitted form and a result summary, not column values, so they are
+untouched. The row itself is always returned: what happened, by whom and when stays visible either way.
+
+A snapshot only answers for the writable columns it captured, so a scope reaching for anything else — a
+read-only column, a relation, a value stored redacted — is not evaluated against it at all and the values
+are withheld: `nil` there is a missing answer, not a passing one, and a redacted value answers no better.
+Primary keys are the exception: the packed id fills in whatever the snapshot cannot answer — a read-only key
+it never captured, or a writable one the trail redacts — so a scope on the id still matches the record it
+belongs to. It fills in only what is missing: where a side captured the key itself, that value is the one
+that was true there. Each side of an update is read against the id it was filed under, the row's own id and,
+for the previous side of an update that moved the key, the id it moved from. A `pending` row is filed under
+the id the record had *before* the write, which may not have landed, so its new side is given no id to fill
+from and answers with what it captured or not at all.
+
+Neither failure this can meet is fatal, and each costs only what it actually broke. An id that stopped
+decoding when the primary key changed shape costs the keys it would have filled and nothing more, so a scope
+that never asks about the id is still answered from the columns the row captured. A column captured as `nil`
+that an ordered operator cannot compare withholds that row. Uncaught, either would have failed the whole
+page, and only for the callers a scope applies to, since an unscoped caller never reaches this test. Both
+are logged, and the row keeps its operation, author and timestamp. This is also
+what makes an update's partial diff safe to test: a diff that never carried the scoped column answers for
+neither side, so both are withheld.
+
+The record is read twice: once before the rows are fetched, to refuse a record that exists outside the
+caller's scope without touching the audit database, and once after, so the answer that decides the
+withholding is never older than the rows it applies to — a record deleted in between would otherwise have
+answered "present and in scope" for rows that already carry its delete. The second read is skipped when no
+scope is in effect.
+
+**This covers the history route only.** `/state` reconstructs a gone record from the same rows and serves
+it unfiltered, and the correlation routes check the record but not the values, so a caller the withholding
+above protects against can still read those values one request away. Closing that is tracked separately.
+
 ### State route
 
 `GET /forest/_audit-trail/{collection}/{recordId}/state?timestamp=…` returns the record as it stood at

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

@@ -39,7 +39,7 @@ module ForestAdminAgent
         def handle_request(args = {})
           context = build(args)
           context.permissions.can?(:read, context.collection)
-          assert_record_in_scope(context, context.collection, args[:params]['id'])
+          withholding_scope = assert_record_in_scope(context, context.collection, args[:params]['id'])
 
           skip, limit = parse_pagination(args)
           filters = {
@@ -54,9 +54,14 @@ module ForestAdminAgent
           # `count` reflects the active filters (not the absolute total) and is independent of the page.
           count = store.count_by_record(**filters)
 
+          # Asked again now: the check above ran before these rows were read, so a record deleted in between
+          # answered "present and in scope" for rows that already carry its delete.
+          withholding_scope ||= scope_if_gone_since(context, args)
+          data = withhold_out_of_scope_values(history, withholding_scope, context)
+
           {
             name: args[:params]['collection_name'],
-            content: { data: history.map { |record| serialize_record(record) }, meta: meta(args, filters, count) }
+            content: { data: data.map { |record| serialize_record(record) }, meta: meta(args, filters, count) }
           }
         end
 
@@ -85,6 +90,108 @@ module ForestAdminAgent
 
         private
 
+        # Second read of the record, once the rows are in hand, so the answer that decides the withholding is
+        # never older than what it decides on. Skipped without a scope in effect — there is nothing to withhold
+        # then, and nothing to ask. A record moved out of scope rather than deleted raises the 404 it would
+        # raise for a request starting a moment later.
+        def scope_if_gone_since(context, args)
+          return nil if context.permissions.get_scope(context.collection).nil?
+
+          assert_record_in_scope(context, context.collection, args[:params]['id'])
+        end
+
+        # A record that is gone for good bypasses the scope check — there is nothing left to check it against
+        # — but its rows still carry the column values captured while it existed. When those values would
+        # themselves have failed the caller's scope, withhold them; the row itself stays visible either way,
+        # so that it happened, by whom and when still reads.
+        def withhold_out_of_scope_values(entries, scope, context)
+          return entries if scope.nil?
+
+          entries.map { |entry| withhold(entry, scope, context) }
+        end
+
+        def withhold(entry, scope, context)
+          case entry.operation
+          # `delete`'s previous_values and `create`'s new_values both capture every writable column.
+          when 'delete'
+            in_scope?(entry.previous_values, entry.record_id, scope, context) ? entry : blank(entry, :previous_values)
+          when 'create'
+            in_scope?(entry.new_values, entry.record_id, scope, context) ? entry : blank(entry, :new_values)
+          when 'update'
+            withhold_each_side(entry, scope, context)
+          # `action`/`action_failed` rows hold a submitted form and a result summary, not column values, so
+          # the scope doesn't apply to them.
+          else
+            entry
+          end
+        end
+
+        # An update's two sides are a partial diff, so each is tested against its own values: a diff that never
+        # carried the scoped column answers for neither and is withheld by `in_scope?` anyway. Gating the sides
+        # separately releases the ones that can be proven in scope — "it used to be X" can't escape through a
+        # row whose new value is out of scope, since that side is tested on its own.
+        def withhold_each_side(entry, scope, context)
+          # An update that moved a writable primary key files its row under the id the record ended up with,
+          # and keeps the one it had on `previous_record_id`. Each side is tested against the id it was true
+          # of, or the new state's id would decide whether the old state is in scope.
+          before = entry.previous_record_id || entry.record_id
+          kept = in_scope?(entry.previous_values, before, scope, context) ? entry : blank(entry, :previous_values)
+
+          in_scope?(kept.new_values, after_id(kept), scope, context) ? kept : blank(kept, :new_values)
+        end
+
+        # A pending row is filed under the id the record had *before* the write, since the write may not have
+        # landed: it says nothing about the state the update was moving to, so the new side gets no id to fill
+        # from and falls back on what it captured itself.
+        def after_id(entry)
+          entry.status == ::ForestAdminAgent::AuditTrail::Recording::PENDING ? nil : entry.record_id
+        end
+
+        # Only a snapshot that answers every field the scope asks about, with what was really stored, is worth
+        # matching. The capture keeps the writable columns, so a scope on anything else — a read-only column, a
+        # relation — reads as nil there and would answer for a value the row never held: `status != 'private'`
+        # would match, and an ordered operator would raise on the nil. A redacted value answers no better.
+        def in_scope?(values, packed_id, scope, context)
+          snapshot = answerable_snapshot(values, packed_id, context.collection)
+          return false unless scope.projection.all? { |field| snapshot.key?(field) }
+
+          scope.match(snapshot, context.collection, context.caller.timezone)
+        rescue StandardError => e
+          # Key presence is not answerability: a column captured as nil has its key, and an ordered operator
+          # raises on it. Uncaught that would fail the whole page, and only for the callers a scope applies
+          # to. One withheld row is the smaller loss, and the same answer the field would have got had it
+          # been missing outright.
+          Facades::Container.logger&.log('Warn', "[ForestAdmin] Audit row not scope-checkable: #{e.message}")
+
+          false
+        end
+
+        # What this side of the row can answer about. A redacted value answers nothing, so it is dropped rather
+        # than matched against the placeholder — leaving the field unanswered, which withholds. The packed id
+        # then fills in the primary keys: a read-only one never lands in the snapshot at all, and a writable one
+        # the trail redacts was just dropped, while the id the row was filed under proves what the key was.
+        # It only fills what the snapshot cannot answer: on the side of a row that captured the key itself,
+        # that value is the one that was true there.
+        def answerable_snapshot(values, packed_id, collection)
+          answered = (values || {}).reject { |_, value| value == ::ForestAdminAgent::AuditTrail::Recording::REDACTED }
+          return answered if packed_id.nil?
+
+          begin
+            Utils::Id.unpack_id(collection, packed_id, with_key: true).merge(answered)
+          rescue StandardError => e
+            # An id written under a primary key of another shape costs the keys it would have filled, and
+            # nothing else: the snapshot still answers for the columns it captured, so a scope that never
+            # asks about the id is unaffected.
+            Facades::Container.logger&.log('Warn', "[ForestAdmin] Audit row id not decodable: #{e.message}")
+
+            answered
+          end
+        end
+
+        def blank(entry, *fields)
+          entry.dup.tap { |copy| fields.each { |field| copy[field] = {} } }
+        end
+
         # `availableUsers` rides along on the first fetch only — the front keeps the list it saw — and lists the
         # distinct authors of the entries the current filters match, whatever page was asked for. The identity
         # comes from the rows, so someone since renamed or removed still reads as they were when they acted.

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

@@ -9,10 +9,16 @@ module ForestAdminAgent
       module AuditTrailRoute
         include ForestAdminDatasourceToolkit::Components::Query
 
+        # The caller's scope when the record is gone for good, nil otherwise — no scope in effect, or a record
+        # still there and in scope. A scope can't be evaluated against a record that no longer exists, so its
+        # history is served, but the values its rows captured while it existed still have to be tested against
+        # that scope before being handed back.
         def assert_record_in_scope(context, collection, packed_id)
-          scoped_record(context, collection, packed_id)
+          return nil if scoped_record(context, collection, packed_id)
 
-          nil
+          # Nothing there: gone for good, since an out-of-scope record raised above. Without a scope in
+          # effect this reads nil, which is the same answer.
+          context.permissions.get_scope(collection)
         end
 
         # The record as it stands, read through the caller's permission scope. nil when it no longer exists

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.44.0"
+        LIANA_VERSION = "1.44.2"
 
         def self.generate(datasource)
           datasource.collections

data/lib/forest_admin_agent/version.rb

@@ -1,3 +1,3 @@
 module ForestAdminAgent
-  VERSION = "1.44.0"
+  VERSION = "1.44.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: forest_admin_agent
 version: !ruby/object:Gem::Version
-  version: 1.44.0
+  version: 1.44.2
 platform: ruby
 authors:
 - Matthieu
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-15 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport