Fix frozen headers and precompute parse_reference

Make MCPRackApp return per-response header hashes (json_headers / sse_headers) instead of the frozen JSON_CONTENT_TYPE / SSE_HEADERS constants to avoid FrozenError when Rack middleware decorates response headers; add helpers and tests for header mutability. Harden parse_reference precompute: suppress autofetch during the before_create precompute callback to avoid ObjectNotFound, and gate client-generated objectId forwarding so precompute only runs with master-key authority (skip when a per-save session token is present or client.master_key is absent). Add YARD notes documenting Auth0 correlation_id normalization and server requirements/threat model for precompute, enable allowCustomObjectId in test docker/config/scripts to cover the precompute path, add tests for precompute behaviors, and bump version to 4.1.2 (Gemfile.lock, version file, changelog updated).

Author: AdrianCurtin

CHANGELOG.md

@@ -1,5 +1,26 @@
 ## Parse-Stack Changelog
 
+### 4.1.2
+
+#### Bug Fixes
+
+- **FIXED**: `Parse::Agent::MCPRackApp` no longer returns the frozen `JSON_CONTENT_TYPE` / `SSE_HEADERS` module-level constants as the response headers hash. Every response now receives a fresh `.dup` of the template via new private `json_headers` / `sse_headers` helpers, so downstream Rack middleware that decorates response headers — Sinatra's `xss_header`, `json_csrf`, and `common_logger`, as well as `rack-deflater` and similar — can mutate the hash without raising `FrozenError`, and cross-request mutation cannot leak through the shared singleton. The constants remain as frozen templates and are still publicly readable; existing callers that read them directly are unaffected. (`lib/parse/agent/mcp_rack_app.rb`)
+- **FIXED**: The built-in `export_data` tool definition's `columns:` parameter declared `type: "array"` without an `items` schema, which caused OpenAI's function-calling endpoint to reject every request that included the agent's tool list with `invalid_function_parameters`: "array schema missing items." Because OpenAI validates the entire tool list at request time, the broken schema fired even when the LLM never invoked `export_data`, effectively disabling the agent. The `columns:` items schema is now declared as a `oneOf` between a plain string (used as both field path and header) and a single-entry `{field => header}` object (used to rename a column), matching what `normalize_export_columns` already accepts at runtime. A new regression test (`test/lib/parse/agent/tools_schema_validity_test.rb`) walks every `TOOL_DEFINITIONS` entry and asserts that every array property at every nesting depth carries an `items` schema, so this bug class cannot recur silently in another tool's definition. (`lib/parse/agent/tools.rb`)
+- **FIXED**: `parse_reference precompute: true` no longer aborts the create POST with `Parse::Error::ObjectNotFound` (code 101). The `before_create _precompute_<field>!` callback used to call `public_send(field_name)` to compare the current value against the canonical target; that read went through the property accessor, which observed `value.nil?` and `pointer?` (objectId just client-assigned, timestamps still blank) and fired an autofetch GET against an id Parse Server had not seen yet. The callback now suppresses autofetch for the duration of the write by toggling `disable_autofetch!` / `enable_autofetch!` around the comparison and assignment, restoring the prior autofetch state on exit. The eventual create POST is unaffected — it still includes both `objectId` and the canonical `parseReference` in a single round-trip. (`lib/parse/model/core/parse_reference.rb`)
+
+#### Hardening
+
+- **FIXED**: `parse_reference precompute: true` now refuses to forward a client-supplied `objectId` unless the save runs with master-key authority. The `_precompute_<field>!` callback short-circuits when an explicit per-save session token is set (`with_session` / `set_session_token`) or when no `master_key` is configured on `Parse::Client`; in those cases the legacy after-create `_assign_<field>!` flow takes over, costing one extra round-trip but staying within the requesting session's permissions and yielding a reference derived from the server-assigned id. Previously the callback would client-generate an objectId regardless of auth context, which on a server with `allowCustomObjectId: true` allowed objectId-squatting from any session whose ACL permitted creates on the class. The SDK gate protects parse-stack callers; for cross-SDK enforcement, the inline documentation on `parse_reference precompute:` shows a `beforeSave` cloud-code hook that rejects client-supplied objectIds from non-master sessions. (`lib/parse/model/core/parse_reference.rb`)
+
+#### Testing Infrastructure
+
+- The Dockerized test Parse Server now starts with `allowCustomObjectId: true` (`PARSE_SERVER_ALLOW_CUSTOM_OBJECT_ID=true`), enabling integration coverage for the `parse_reference precompute: true` path. The flag is scoped to the test rig — `config/parse-config.json` for the docker-compose mount and `scripts/start-parse.sh` for the standalone helper — and does not affect any consumer's production configuration. (`config/parse-config.json`, `scripts/docker/docker-compose.test.yml`, `scripts/start-parse.sh`, `test/lib/parse/parse_reference_integration_test.rb`, `test/lib/parse/parse_reference_test.rb`)
+
+#### Documentation
+
+- Added a `@note` on `Parse::Agent#correlation_id` clarifying that the safe-character regex (`[A-Za-z0-9._-]`) intentionally rejects the `|` character used in Auth0 `sub` values (e.g. `auth0|abc123`) as log-injection hardening. Integrators threading an Auth0 sub through as the correlation id should normalize it before assignment with `sub.gsub(/[^A-Za-z0-9._-]/, "_")`, which handles every disallowed character in one pass (necessary for federated provider subs that can also contain `:` or `/`). The note also calls out that many-to-one normalization can collide distinct subs onto the same correlation id, which is acceptable for log threading — the only intended use — but means the value must not be reused as a cache key, rate-limit bucket, or identity token. (`lib/parse/agent.rb`)
+- Expanded the YARD doc-block on `parse_reference precompute:` with a new "Server requirements and threat model" section describing the `allowCustomObjectId` server flag, the SDK-side master-key gate, the cross-SDK objectId-squatting risk that remains when `allowCustomObjectId` is on, and the recommended `beforeSave` cloud-code hook for non-master enforcement across all client SDKs. (`lib/parse/model/core/parse_reference.rb`)
+
 ### 4.1.1
 
 #### Bug Fixes

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack (4.1.1)
+    parse-stack (4.1.2)
       activemodel (>= 6.1, < 9)
       activesupport (>= 6.1, < 9)
       faraday (~> 2.0)

config/parse-config.json

@@ -7,5 +7,6 @@
   "mountPath": "/parse",
   "cloud": "/parse-server/cloud/main.js",
   "logLevel": "info",
-  "allowClientClassCreation": true
+  "allowClientClassCreation": true,
+  "allowCustomObjectId": true
 }

lib/parse/agent.rb

@@ -359,6 +359,21 @@ def raw_schema_enabled?
     #   payload as `:correlation_id` when present. Sanitized to a max of
     #   128 characters from the set `[A-Za-z0-9._-]` to prevent log
     #   injection — anything else is rejected.
+    #
+    # @note Auth0 `sub` values use the form `provider|subject` (e.g.
+    #   `auth0|abc123`). The `|` character is rejected by the safe-char
+    #   regex by design (log-injection hardening). Integrators threading
+    #   an Auth0 sub through as the correlation id must normalize it
+    #   first — e.g.:
+    #     agent.correlation_id = sub.gsub(/[^A-Za-z0-9._-]/, "_")
+    #   `gsub` (rather than `tr("|", "_")`) handles every disallowed
+    #   character in one pass, which is necessary for federated provider
+    #   subs that can contain `|`, `:`, `/`, and other separators. Note
+    #   that a many-to-one normalization can collide two distinct subs
+    #   onto the same correlation id (`auth0|abc` and `auth0_abc` both
+    #   collapse to `auth0_abc`). This is acceptable for log threading,
+    #   the only intended use of `correlation_id`. Do not reuse the
+    #   value as a cache key, rate-limit bucket, or identity token.
     attr_reader :correlation_id
 
     # Setter for correlation_id with input sanitization. Silently rejects

lib/parse/agent/mcp_rack_app.rb

@@ -70,10 +70,14 @@ class MCPRackApp
       # Default heartbeat interval in seconds when streaming is enabled.
       DEFAULT_HEARTBEAT_INTERVAL = 2
 
-      # Standard Content-Type for all JSON responses.
+      # Standard Content-Type for all JSON responses. Frozen template — call
+      # {#json_headers} to obtain a per-response mutable copy that composes
+      # with Rack middleware that decorates response headers (e.g. Sinatra's
+      # xss_header / json_csrf / common_logger).
       JSON_CONTENT_TYPE = { "Content-Type" => "application/json" }.freeze
 
       # SSE response headers. X-Accel-Buffering disables Nginx proxy buffering.
+      # Frozen template — call {#sse_headers} to obtain a per-response copy.
       SSE_HEADERS = {
         "Content-Type"      => "text/event-stream",
         "Cache-Control"     => "no-cache",
@@ -197,28 +201,28 @@ def call(env)
         # 1. Method check — only POST is accepted.
         unless env["REQUEST_METHOD"] == "POST"
           return [405,
-                  JSON_CONTENT_TYPE.merge("Allow" => "POST"),
+                  json_headers.merge("Allow" => "POST"),
                   [json_rpc_error(-32_700, "method_not_allowed")]]
         end
 
         # 2. Content-type check — must be application/json (charset ignored).
         content_type = env["CONTENT_TYPE"].to_s.split(";").first.to_s.strip.downcase
         unless content_type == "application/json"
-          return [415, JSON_CONTENT_TYPE, [json_rpc_error(-32_700, "Unsupported Media Type: Content-Type must be application/json")]]
+          return [415, json_headers, [json_rpc_error(-32_700, "Unsupported Media Type: Content-Type must be application/json")]]
         end
 
         # 3. Body size limit — read one byte beyond limit to detect oversized bodies
         #    without buffering the full stream.
         raw_body = env["rack.input"].read(@max_body_size + 1)
         if raw_body.bytesize > @max_body_size
-          return [413, JSON_CONTENT_TYPE, [json_rpc_error(-32_700, "Payload Too Large: body exceeds #{@max_body_size} bytes")]]
+          return [413, json_headers, [json_rpc_error(-32_700, "Payload Too Large: body exceeds #{@max_body_size} bytes")]]
         end
 
         # 4. JSON parse.
         begin
           body = JSON.parse(raw_body.empty? ? "{}" : raw_body, max_nesting: MAX_JSON_NESTING)
         rescue JSON::ParserError, JSON::NestingError
-          return [400, JSON_CONTENT_TYPE, [json_rpc_error(-32_700, "Parse error: invalid JSON")]]
+          return [400, json_headers, [json_rpc_error(-32_700, "Parse error: invalid JSON")]]
         end
 
         # 5. Agent factory — auth gate. Rescue Unauthorized first, then catch-all
@@ -227,13 +231,13 @@ def call(env)
           agent = @agent_factory.call(env)
         rescue Parse::Agent::Unauthorized => e
           @logger.warn("[Parse::Agent::MCPRackApp] Unauthorized: #{e.class.name}") if @logger
-          return [401, JSON_CONTENT_TYPE, [unauthorized_body]]
+          return [401, json_headers, [unauthorized_body]]
         rescue StandardError => e
           if @logger
             @logger.warn("[Parse::Agent::MCPRackApp] Factory error: #{e.class.name}")
             @logger.warn(e.backtrace.join("\n")) if e.backtrace
           end
-          return [500, JSON_CONTENT_TYPE, [json_rpc_error(-32_603, "Internal error")]]
+          return [500, json_headers, [json_rpc_error(-32_603, "Internal error")]]
         end
 
         # 5b. Thread the conversation correlation id through. Source:
@@ -271,7 +275,7 @@ def call(env)
       # @return [Array] Rack triple with Array<String> body.
       def serve_json(body, agent)
         result = Parse::Agent::MCPDispatcher.call(body: body, agent: agent, logger: @logger)
-        [result[:status], JSON_CONTENT_TYPE, [JSON.generate(result[:body])]]
+        [result[:status], json_headers, [JSON.generate(result[:body])]]
       end
 
       # Return a streaming Rack response that emits SSE progress events while
@@ -303,7 +307,7 @@ def serve_sse(body, agent)
         # model.
         if @max_concurrent_dispatchers &&
            MCPRackApp.active_dispatcher_count >= @max_concurrent_dispatchers
-          return [503, JSON_CONTENT_TYPE,
+          return [503, json_headers,
                   [json_rpc_error(-32_000, "server busy", id: body["id"])]]
         end
 
@@ -316,7 +320,7 @@ def serve_sse(body, agent)
           Parse::Agent::MCPDispatcher.call(body: body, agent: agent, logger: logger)
         end
 
-        [200, SSE_HEADERS, sse_body]
+        [200, sse_headers, sse_body]
       end
 
       # ---------------------------------------------------------------------------
@@ -493,6 +497,24 @@ def build_error_envelope(error)
         end
       end
 
+      # ---------------------------------------------------------------------------
+      # Response-header helpers
+      # ---------------------------------------------------------------------------
+
+      # Return a per-response copy of the JSON content-type header hash. Always
+      # returns a fresh, unfrozen hash so Rack middleware that decorates
+      # response headers (Sinatra's xss_header, json_csrf, common_logger,
+      # rack-deflater, etc.) can mutate the result without FrozenError, and
+      # so that cross-request mutation cannot leak through a shared singleton.
+      def json_headers
+        JSON_CONTENT_TYPE.dup
+      end
+
+      # Return a per-response copy of the SSE header hash. See {#json_headers}.
+      def sse_headers
+        SSE_HEADERS.dup
+      end
+
       # ---------------------------------------------------------------------------
       # JSON-RPC envelope helpers
       # ---------------------------------------------------------------------------

lib/parse/agent/tools.rb

@@ -265,6 +265,16 @@ module Tools
               # output control
               columns:  {
                 type: "array",
+                # Each entry is either a string (used as both path and header) or a
+                # single-entry { "<field>" => "<Header>" } object for renaming.
+                # OpenAI rejects array properties without an `items` schema
+                # (`invalid_function_parameters`: "array schema missing items.").
+                items: {
+                  oneOf: [
+                    { type: "string" },
+                    { type: "object", additionalProperties: { type: "string" } },
+                  ],
+                },
                 description: "Column spec. Each entry is either a string (field name, used as header) " \
                              "or an object {field => header} to rename. Dotted paths supported.",
               },

lib/parse/model/core/parse_reference.rb

@@ -54,6 +54,54 @@ module Core
     #   {ClassMethods#populate_parse_references!} batch helper or call
     #   `obj._assign_<field>!` manually after the transaction commits.
     #
+    # == `precompute: true` — server requirements and threat model
+    #
+    # The `precompute: true` option client-generates the objectId in a
+    # `before_create` callback and embeds both `objectId` and the canonical
+    # reference in the initial POST body, eliminating the follow-up
+    # `update!` that the default after_create flow issues. Two requirements
+    # must hold for this to work end-to-end:
+    #
+    # 1. Parse Server must be started with `allowCustomObjectId: true`
+    #    (`PARSE_SERVER_ALLOW_CUSTOM_OBJECT_ID=true`). Without that flag,
+    #    Parse Server rejects any create whose body contains `objectId`
+    #    with `error: objectId is an invalid field name` (HTTP 400, code
+    #    105) before any cloud-code hooks run.
+    # 2. The save must run with master-key authority. The DSL enforces
+    #    this SDK-side: `_precompute_<field>!` is a no-op when the
+    #    instance has a per-save session token set (`with_session` /
+    #    `set_session_token`) or when no `master_key` is configured on
+    #    `Parse::Client`. In either case the legacy after_create
+    #    `_assign_<field>!` flow takes over, costing one extra round-trip
+    #    but staying within the session's permissions. The local @id
+    #    falls back to the server-assigned id (no client id is generated
+    #    or forwarded), so the resulting `parseReference` is correct.
+    #
+    # The SDK gate protects parse-stack callers, but `allowCustomObjectId`
+    # is a server-global flag — it also lets the JS SDK, iOS SDK, raw
+    # REST callers, and any other client using the same Parse Server pick
+    # their own `objectId` on create. That permits objectId-squatting
+    # ("admin", "root", colliding with another tenant's id), id-spoofing
+    # on classes whose ACL allows public create, and a few subtle CLP
+    # bypass shapes when a class's class-level permissions key off
+    # `objectId` patterns. To enforce master-only client objectIds across
+    # ALL SDKs, register a Cloud Code `beforeSave` hook that rejects
+    # client-supplied ids from non-master sessions, e.g.:
+    #
+    #   Parse.Cloud.beforeSave("MyClass", req => {
+    #     if (req.original === undefined && req.object.id && !req.master) {
+    #       throw "Client-supplied objectId not allowed";
+    #     }
+    #   });
+    #
+    # `req.original === undefined` narrows to creates (no prior state);
+    # `req.object.id` is the client-supplied id; `!req.master` excludes
+    # legitimate master-key creates including this gem's precompute path.
+    # Apply per-class for the classes that declare
+    # `parse_reference precompute: true`, or globally on every class via
+    # `Parse.Cloud.beforeSave(Parse.Object, ...)` if the application has
+    # no legitimate non-master custom-id use case.
+    #
     # @example default field name
     #   class Post < Parse::Object
     #     parse_reference   # local :parse_reference -> remote "parseReference"
@@ -241,12 +289,43 @@ def parse_reference(field_name = :parse_reference, field: nil, precompute: false
           if precompute
             precompute_method = :"_precompute_#{field_name}!"
             define_method(precompute_method) do
+              # Precompute is master-key-only. Parse Server rejects a
+              # client-supplied `objectId` in the create body unless its
+              # `allowCustomObjectId` option is enabled, and even with that
+              # global flag on, accepting client-set objectIds from
+              # non-master sessions is an objectId-squatting risk
+              # (attacker picks "admin", "root", or collides with another
+              # tenant's id). Skip precompute when this save won't run as
+              # master: an explicit per-save session token is present
+              # (`with_session` / `set_session_token`), or no master key is
+              # configured on the client at all. In those cases the legacy
+              # after_create `_assign_<field>!` flow takes over, costing
+              # one extra round-trip but staying within whatever
+              # permissions the requesting session has.
+              return if _session_token.present?
+              return unless client.respond_to?(:master_key) && client.master_key.present?
+
               if id.blank?
                 @id = Parse::Core::ParseReference.generate_object_id
               end
-                target = Parse::Core::ParseReference.format(self.class.parse_class, id)
+              target = Parse::Core::ParseReference.format(self.class.parse_class, id)
+              # We just client-assigned @id, so the instance now satisfies
+              # `pointer?` (objectId present, timestamps blank). The property
+              # accessor's autofetch heuristic — and the setter's
+              # prepare_for_dirty_tracking! pre-fetch — would both fire a GET
+              # against an id Parse Server has not seen yet, producing a 101
+              # Object not found and aborting the create. Suppress autofetch
+              # for the duration of this callback's writes; the actual create
+              # POST that follows includes both objectId and parse_reference,
+              # so server state is unaffected.
+              was_disabled = autofetch_disabled?
+              disable_autofetch!
+              begin
                 return if public_send(field_name) == target
                 public_send("#{field_name}=", target)
+              ensure
+                enable_autofetch! unless was_disabled
+              end
             end
 
             already_precomputing = _create_callbacks.any? do |cb|

lib/parse/stack/version.rb

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