feat: Add Parse Server option allowPublicExplain to allow Parse.Query.explain without master key

DEPRECATIONS.md

@@ -15,6 +15,7 @@ The following is a list of deprecations, according to the [Deprecation Policy](h
 | DEPPS9 | Rename LiveQuery `fields` option to `keys` | [#8389](https://github.com/parse-community/parse-server/issues/8389)   | 6.0.0 (2023)                    | 7.0.0 (2024)                    | removed            | -     |
 | DEPPS10 | Encode `Parse.Object` in Cloud Function and remove option `encodeParseObjectInCloudFunction` | [#8634](https://github.com/parse-community/parse-server/issues/8634)   | 6.2.0 (2023)                    | 9.0.0 (2026)                    | deprecated            | -     |
 | DEPPS11 | Replace `PublicAPIRouter` with `PagesRouter` | [#7625](https://github.com/parse-community/parse-server/issues/7625)   | 8.0.0 (2025)                    | 9.0.0 (2026)                    | deprecated            | -     |
+| DEPPS12 | Restrict `explain` query parameter to master key | [#7519](https://github.com/parse-community/parse-server/issues/7519) | 8.3.0 (2025)                    | 9.0.0 (2027)                    | deprecated            | -     |
 
 [i_deprecation]: ## "The version and date of the deprecation."
 [i_removal]: ## "The version and date of the planned removal."

changelogs/CHANGELOG_alpha.md

@@ -1,3 +1,9 @@
+# [8.3.0-alpha.13](https://github.com/parse-community/parse-server/compare/8.3.0-alpha.12...8.3.0-alpha.13) (2025-10-25)
+
+### Features
+
+- Deprecation DEPPS12: `explain` query parameter without master key ([#7519](https://github.com/parse-community/parse-server/issues/7519)) ([DEPPS12](https://github.com/parse-community/parse-server/blob/alpha/DEPRECATIONS.md#depps12))
+
 # [8.3.0-alpha.12](https://github.com/parse-community/parse-server/compare/8.3.0-alpha.11...8.3.0-alpha.12) (2025-10-25)
 
 

spec/ParseQuery.spec.js

@@ -8,6 +8,7 @@ const Parse = require('parse/node');
 const request = require('../lib/request');
 const ParseServerRESTController = require('../lib/ParseServerRESTController').ParseServerRESTController;
 const ParseServer = require('../lib/ParseServer').default;
+const Deprecator = require('../lib/Deprecator/Deprecator');
 
 const masterKeyHeaders = {
   'X-Parse-Application-Id': 'test',
@@ -5384,4 +5385,40 @@ describe('Parse.Query testing', () => {
       expect(query1.length).toEqual(1);
     });
   });
+
+  it_id('DEPPS12')(it_only_db('mongo'))(
+    'throws error when using explain without master key',
+    async () => {
+      const obj = new TestObject({ foo: 'bar' });
+      await obj.save();
+
+      const spyLogRuntimeDeprecation = spyOn(Deprecator, 'logRuntimeDeprecation');
+
+      // Test that explain without master key throws an error
+      const query = new Parse.Query(TestObject);
+      query.explain();
+
+      try {
+        await query.find();
+
+        expect(spyLogRuntimeDeprecation).toHaveBeenCalledTimes(1);
+        expect(spyLogRuntimeDeprecation).toHaveBeenCalledWith({
+          usage: 'Using the explain query parameter without the master key',
+        });
+        // fail('Should have thrown an error');
+      } catch (error) {
+        // Uncomment this after the Deprecation DEPPS12
+        // expect(error.code).toEqual(Parse.Error.INVALID_QUERY);
+        // expect(error.message).toEqual('Using the explain query parameter without the master key');
+      }
+
+      // Test that explain with master key works fine
+      const queryWithMasterKey = new Parse.Query(TestObject);
+      queryWithMasterKey.explain();
+      const result = await queryWithMasterKey.find({ useMasterKey: true });
+
+      // Should return explain result (not throw error)
+      expect(result).toBeDefined();
+    }
+  );
 });

src/rest.js

@@ -13,6 +13,7 @@ var RestQuery = require('./RestQuery');
 var RestWrite = require('./RestWrite');
 var triggers = require('./triggers');
 const { enforceRoleSecurity } = require('./SharedRest');
+const Deprecator = require('./Deprecator/Deprecator');
 
 function checkTriggers(className, config, types) {
   return types.some(triggerType => {
@@ -35,6 +36,19 @@ async function runFindTriggers(
 ) {
   const { isGet } = options;
 
+  if (restOptions && restOptions.explain && !auth.isMaster) {
+    // After the Deprecation DEPPS12 uncomment this to throw an error
+    // throw new Parse.Error(
+    //   Parse.Error.INVALID_QUERY,
+    //   'Using the explain query parameter without the master key'
+    // );
+
+    // Deprecation DEPPS12
+    Deprecator.logRuntimeDeprecation({
+      usage: 'Using the explain query parameter without the master key',
+    });
+  }
+
   // Run beforeFind trigger - may modify query or return objects directly
   const result = await triggers.maybeRunQueryTrigger(
     triggers.Types.beforeFind,