parse-stack-next 5.7.5 → 5.7.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d06f0d8932e328bae92fde22a568b9669614a02e75a5deed1a220884213d43e
-  data.tar.gz: edaaf3bb456a5396fdc08706188ca07d66aba66b17c7fce95220f130041644d8
+  metadata.gz: e52d26b7117b0f69c691813a88cde7be0429024b7e95624a0b4fc54e883c799f
+  data.tar.gz: e97f5cc5e069020a1580a1175e7ce04810790222ccd03e981f502982532112f5
 SHA512:
-  metadata.gz: 202606fe6edad9aafda2d48a216addfca376d24b01f1a8a39febce4fa511fcf5253f736632bf7aeff64645fe398d015fccb694ddf622688f3a78a6431b570ed2
-  data.tar.gz: a09f557be7a37d9f12937e0c70da314c617bd8ec18993cef2952336b7b55b6d1d9bbe3e0381933b70a4f3bdc3b2dcf3a71125edf83c460f5d15d4b0c58d3b3c8
+  metadata.gz: 87157a0beba280ad3c62d854989687edad86d994ed2e61b574c1394241d3151cb8f158b318d424eab95eb441a18ee48b15fc02a3debd5736d98e7c397971b3b9
+  data.tar.gz: 64d779b52738ee8c276fcbf8f6e6e6d848817b90b3841b2deceb2514ffc32c1e59c1ba8a6061d8b59c58c40e62d3085aa187dc6e5b32048ce8ac8250f7429758

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## parse-stack-next Changelog
 
+### 5.7.6
+
+#### `semantic_search` no longer returns hidden fields as chunk content
+
+A focused security fix for the `semantic_search` agent tool. When a class
+embedded a field that its `agent_fields` allowlist hides from agents (for
+example, searching on `body` while exposing only `title`), the tool returned
+that field's text as `chunks[].content`, even though the `documents` map
+correctly omitted it. The chunk text is now restricted to fields the agent may
+read.
+
+- **FIXED**: `semantic_search` built chunk content from the raw value of the
+  embedded text source before the per-record `agent_fields` projection ran,
+  and its `text_field` check compared against the class's embed sources but
+  not its `agent_fields` allowlist. A text source is now usable only when it
+  is both an embed source and inside `agent_fields`. An explicit `text_field`
+  naming an embedded-but-hidden field is refused with `AccessDenied`
+  (`kind: :field_denied`) before any search runs. When `text_field` is
+  omitted, the tool infers the sole readable source, refuses with
+  `:field_denied` when no embedded source is readable, and asks for an
+  explicit `text_field` when several are. Reranker input is built from the
+  same text source, so it is covered by the same check. Classes without an
+  `agent_fields` allowlist behave as before, and direct
+  `Parse::Retrieval.retrieve` callers, which are application code rather than
+  agents, are unaffected.
+
 ### 5.7.5
 
 #### MongoDB 9.0 support

data/README.md

@@ -6,6 +6,7 @@ A full-featured Ruby client SDK for [Parse Server](http://parseplatform.org/). [
 
 ## What's new in 5.7
 
+- **5.7.6: `semantic_search` respects `agent_fields` for chunk content.** A class that embedded a field hidden by its `agent_fields` allowlist returned that field's text as chunk content. Chunk text now comes only from embedded fields the agent may read; a hidden text source is refused with `:field_denied` before the search runs. See [CHANGELOG.md](./CHANGELOG.md)
 - **5.7.5: MongoDB 9.0 support.** The test stack runs MongoDB 9 by default (`MONGO_VERSION=8` selects the previous major), and use the `mongo` driver 2.26 or newer for 9.0's overload handling. MongoDB 9.0 changes how `null` comparisons treat dotted paths through arrays; see the behavior notes in [CHANGELOG.md](./CHANGELOG.md)
 - **5.7.5: `voyage-code-4` and contextualized chunk embeddings.** The Voyage provider accepts `voyage-code-4`, `voyage-context-4`, and `voyage-context-3`. `Voyage#embed_chunks` embeds whole chunked documents so each chunk's vector carries its document's context. See [CHANGELOG.md](./CHANGELOG.md)
 - **5.7.5: Voyage reranker and MCP 2025-11-25.** `Parse::Retrieval::Reranker::Voyage` adds `rerank-3` and `rerank-3-lite` reranking, including through the Atlas endpoint. The MCP server negotiates protocol `2025-11-25` and adds `completion/complete` (class and field names scoped to the agent) and `logging/setLevel`. Mongo-direct reads re-run queries MongoDB 9.0 kills mid-flight. See [CHANGELOG.md](./CHANGELOG.md)

data/docs/atlas_vector_search_guide.md

@@ -715,7 +715,15 @@ Because this model embeds **two** text sources (`:title` and `:body`),
 `semantic_search` cannot guess which one to chunk and return as the
 result `content`. Pass `text_field:` to choose (it must name one of the
 embedded sources); a single-source model infers it automatically and the
-parameter is optional:
+parameter is optional.
+
+Through the agent tool, the chosen source must also be inside the class's
+`agent_fields` allowlist, because chunk `content` is that field's text. A
+class may embed a field it hides from agents (search the `body`, expose only
+the `title`), but `semantic_search` then refuses that source with
+`:field_denied` instead of returning it, and infers only among the readable
+sources. Direct `Parse::Retrieval.retrieve` calls are application code and
+are not subject to `agent_fields`:
 
 ```ruby
 # via the agent tool (LLM-facing parameter)

data/docs/mcp_guide.md

@@ -912,6 +912,7 @@ front avoids discovering each only on impact:
 | Reserved underscore key | A `filter:` / `vector_filter:` / `where:` contains an underscore-prefixed key (`_rperm`, `_p_*`, …) at any depth | `ArgumentError` / `ValidationError` (recursive refusal) |
 | Filter-field allowlist | A `filter:` / `vector_filter:` names a field not in the class's `agent_searchable filter_fields:` | `ValidationError` naming the offending field(s) |
 | `text_field` not embedded | `semantic_search` `text_field:` names a field that isn't a declared `embed` source | `ValidationError` listing the allowed sources |
+| `text_field` hidden | The `semantic_search` text source (explicit or inferred) is an `embed` source outside the class's `agent_fields` allowlist | `Parse::Agent::AccessDenied` (`kind: :field_denied`), before any search runs |
 | Tool filtered | A tool/method removed by a per-instance `tools:` / `methods:` filter is invoked | `error_code: :tool_filtered` |
 | Approval denied/unavailable | A gated write/admin op is rejected or the approver is unreachable | `error_code: :approval_denied` |
 

data/lib/parse/retrieval/agent_tool.rb

@@ -59,10 +59,12 @@ module Parse
 
       # @param agent [Parse::Agent]
       # @param text_field [String, Symbol, nil] which embedded text source to
-      #   chunk and return as `content`. Required only for models with more
-      #   than one `embed` text source (otherwise inferred). Must name one of
-      #   the class's declared embed sources — an arbitrary field is refused so
-      #   the chunk `content` can't disclose a non-embedded field.
+      #   chunk and return as `content`. Must name one of the class's declared
+      #   embed sources that is also inside its `agent_fields` allowlist: an
+      #   arbitrary field is refused so chunk `content` can't disclose a
+      #   non-embedded field, and an embedded-but-hidden field is refused with
+      #   `:field_denied` so it can't disclose a field the agent may not read.
+      #   When omitted, it is inferred from the readable embed sources.
       # @param max_chunks_per_document [Integer, nil] cap on chunks emitted per
       #   matched document (forwarded to the chunker).
       # @param max_total_tokens [Integer, nil] ceiling on total returned
@@ -329,22 +331,76 @@ module Parse
              .flat_map(&:sources).map(&:to_s).uniq
       end
 
+      # @!visibility private
+      # The embed text sources the agent may also READ: those whose wire
+      # column is inside the class's `agent_fields` allowlist. Chunk
+      # `content` (and any reranker input) is built from the chosen source's
+      # raw value BEFORE the per-record projection strips disallowed fields,
+      # so the source itself must be readable. With no allowlist every
+      # source is readable, as before.
+      #
+      # @return [Array<String>, nil] readable sources, or nil when the class
+      #   declares no `agent_fields` allowlist.
+      def readable_text_fields(klass)
+        allowlist = Parse::Agent::MetadataRegistry.field_allowlist(klass.parse_class)
+        return nil if allowlist.nil? || allowlist.empty?
+        permitted = allowlist.map(&:to_s)
+        searchable_text_fields(klass).select do |source|
+          permitted.include?(Parse::Retrieval.send(:wire_name, klass, source))
+        end
+      end
+
       # @!visibility private
       # Validate a caller-supplied text_field against the embedded-source
-      # allowlist. nil/blank → nil (retrieve infers; works for single-source
-      # models, raises AmbiguousTextField for multi-source so the agent knows
-      # to pass one).
+      # list and the `agent_fields` allowlist, or infer one.
+      #
+      # * Explicit field that is not an embed source: ValidationError.
+      # * Explicit embed source outside `agent_fields`: AccessDenied
+      #   (`:field_denied`), raised before any search runs.
+      # * Omitted, class has no `agent_fields`: nil, so retrieve infers as
+      #   before (single source) or raises AmbiguousTextField (several).
+      # * Omitted, class has `agent_fields`: the sole readable source; a
+      #   `:field_denied` refusal when none is readable; a ValidationError
+      #   asking for `text_field` when several are.
       def normalize_text_field!(text_field, klass)
-        return nil if text_field.nil? || text_field.to_s.strip.empty?
+        readable = readable_text_fields(klass)
+
+        if text_field.nil? || text_field.to_s.strip.empty?
+          return nil if readable.nil?
+          return readable.first.to_sym if readable.length == 1
+          if readable.empty?
+            raise text_field_denied(klass, searchable_text_fields(klass).first)
+          end
+          raise Parse::Agent::ValidationError,
+                "semantic_search: this class embeds several readable text sources; pass " \
+                "text_field (allowed: #{readable.inspect})."
+        end
+
         allowed = searchable_text_fields(klass)
         unless allowed.include?(text_field.to_s)
           raise Parse::Agent::ValidationError,
                 "semantic_search: text_field #{text_field.to_s.inspect} is not an embedded " \
-                "text source for this class (allowed: #{allowed.inspect})."
+                "text source for this class (allowed: #{(readable || allowed).inspect})."
+        end
+        if readable && !readable.include?(text_field.to_s)
+          raise text_field_denied(klass, text_field.to_s)
         end
         text_field.to_sym
       end
 
+      # @!visibility private
+      def text_field_denied(klass, source)
+        allowlist = Parse::Agent::MetadataRegistry.field_allowlist(klass.parse_class)
+        Parse::Agent::AccessDenied.new(
+          klass.parse_class,
+          "semantic_search: text source #{source.to_s.inspect} is outside the agent_fields " \
+          "allowlist for class '#{klass.parse_class}', so it cannot be returned as chunk content.",
+          kind: :field_denied,
+          denied_field: source.to_s,
+          allowed_fields: allowlist&.map(&:to_s),
+        )
+      end
+
       # @!visibility private
       # Refuse any top-level filter key not in the class's declared
       # `filter_fields` allowlist (compound operators included — the

data/lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.7.5"
+    VERSION = "5.7.6"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parse-stack-next
 version: !ruby/object:Gem::Version
-  version: 5.7.5
+  version: 5.7.6
 platform: ruby
 authors:
 - Adrian Curtin