[FEAT] Restrict Firestore Doc/QuerySnapshot toJSON on client.

packages/firestore/src/api/snapshot.ts

@@ -43,13 +43,12 @@ import { DocumentKey } from '../model/document_key';
 import { DocumentSet } from '../model/document_set';
 import { ResourcePath } from '../model/path';
 import { newSerializer } from '../platform/serializer';
+import {
+  buildQuerySnapshotJsonBundle,
+  buildDocumentSnapshotJsonBundle
+} from '../platform/snapshot_to_json';
 import { fromDocument } from '../remote/serializer';
 import { debugAssert, fail } from '../util/assert';
-import {
-  BundleBuilder,
-  DocumentSnapshotBundleData,
-  QuerySnapshotBundleData
-} from '../util/bundle_builder_impl';
 import { Code, FirestoreError } from '../util/error';
 // API extractor fails importing 'property' unless we also explicitly import 'Property'.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports-ts
@@ -529,6 +528,13 @@ export class DocumentSnapshot<
    * @returns a JSON representation of this object.
    */
   toJSON(): object {
+    if (this.metadata.hasPendingWrites) {
+      throw new FirestoreError(
+        Code.FAILED_PRECONDITION,
+        'DocumentSnapshot.toJSON() attempted to serialize a document with pending writes. ' +
+          'Await waitForPendingWrites() before invoking toJSON().'
+      );
+    }
     const document = this._document;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const result: any = {};
@@ -544,29 +550,16 @@ export class DocumentSnapshot<
     ) {
       return result;
     }
-    const builder: BundleBuilder = new BundleBuilder(
-      this._firestore,
-      AutoId.newId()
-    );
     const documentData = this._userDataWriter.convertObjectMap(
       document.data.value.mapValue.fields,
       'previous'
     );
-    if (this.metadata.hasPendingWrites) {
-      throw new FirestoreError(
-        Code.FAILED_PRECONDITION,
-        'DocumentSnapshot.toJSON() attempted to serialize a document with pending writes. ' +
-          'Await waitForPendingWrites() before invoking toJSON().'
-      );
-    }
-    builder.addBundleDocument(
-      documentToDocumentSnapshotBundleData(
-        this.ref.path,
-        documentData,
-        document
-      )
+    result['bundle'] = buildDocumentSnapshotJsonBundle(
+      this._firestore,
+      document,
+      documentData,
+      this.ref.path
     );
-    result['bundle'] = builder.build();
     return result;
   }
 }
@@ -611,6 +604,12 @@ export function documentSnapshotFromJSON<
   converter?: FirestoreDataConverter<AppModelType, DbModelType>
 ): DocumentSnapshot<AppModelType, DbModelType> {
   if (validateJSON(json, DocumentSnapshot._jsonSchema)) {
+    if (json.bundle === 'NOT SUPPORTED') {
+      throw new FirestoreError(
+        Code.INVALID_ARGUMENT,
+        'The provided JSON object was created in a client environment, which is not supported.'
+      );
+    }
     // Parse the bundle data.
     const serializer = newSerializer(db._databaseId);
     const bundleReader = createBundleReaderSync(json.bundle, serializer);
@@ -825,52 +824,48 @@ export class QuerySnapshot<
    * @returns a JSON representation of this object.
    */
   toJSON(): object {
+    if (this.metadata.hasPendingWrites) {
+      throw new FirestoreError(
+        Code.FAILED_PRECONDITION,
+        'QuerySnapshot.toJSON() attempted to serialize a document with pending writes. ' +
+          'Await waitForPendingWrites() before invoking toJSON().'
+      );
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const result: any = {};
     result['type'] = QuerySnapshot._jsonSchemaVersion;
     result['bundleSource'] = 'QuerySnapshot';
     result['bundleName'] = AutoId.newId();
 
-    const builder: BundleBuilder = new BundleBuilder(
-      this._firestore,
-      result['bundleName']
-    );
     const databaseId = this._firestore._databaseId.database;
     const projectId = this._firestore._databaseId.projectId;
     const parent = `projects/${projectId}/databases/${databaseId}/documents`;
-    const docBundleDataArray: DocumentSnapshotBundleData[] = [];
-    const docArray = this.docs;
-    docArray.forEach(doc => {
+    const documents: Document[] = [];
+    const documentData: DocumentData[] = [];
+    const paths: string[] = [];
+
+    this.docs.forEach(doc => {
       if (doc._document === null) {
         return;
       }
-      const documentData = this._userDataWriter.convertObjectMap(
-        doc._document.data.value.mapValue.fields,
-        'previous'
-      );
-      if (this.metadata.hasPendingWrites) {
-        throw new FirestoreError(
-          Code.FAILED_PRECONDITION,
-          'QuerySnapshot.toJSON() attempted to serialize a document with pending writes. ' +
-            'Await waitForPendingWrites() before invoking toJSON().'
-        );
-      }
-      docBundleDataArray.push(
-        documentToDocumentSnapshotBundleData(
-          doc.ref.path,
-          documentData,
-          doc._document
+      documents.push(doc._document);
+      documentData.push(
+        this._userDataWriter.convertObjectMap(
+          doc._document.data.value.mapValue.fields,
+          'previous'
         )
       );
+      paths.push(doc.ref.path);
     });
-    const bundleData: QuerySnapshotBundleData = {
-      name: result['bundleName'],
-      query: this.query._query,
+    result['bundle'] = buildQuerySnapshotJsonBundle(
+      this._firestore,
+      this.query._query,
+      result['bundleName'],
       parent,
-      docBundleDataArray
-    };
-    builder.addBundleQuery(bundleData);
-    result['bundle'] = builder.build();
+      paths,
+      documents,
+      documentData
+    );
     return result;
   }
 }
@@ -915,6 +910,12 @@ export function querySnapshotFromJSON<
   converter?: FirestoreDataConverter<AppModelType, DbModelType>
 ): QuerySnapshot<AppModelType, DbModelType> {
   if (validateJSON(json, QuerySnapshot._jsonSchema)) {
+    if (json.bundle === 'NOT SUPPORTED') {
+      throw new FirestoreError(
+        Code.INVALID_ARGUMENT,
+        'The provided JSON object was created in a client environment, which is not supported.'
+      );
+    }
     // Parse the bundle data.
     const serializer = newSerializer(db._databaseId);
     const bundleReader = createBundleReaderSync(json.bundle, serializer);
@@ -1111,20 +1112,3 @@ export function snapshotEqual<AppModelType, DbModelType extends DocumentData>(
 
   return false;
 }
-
-// Formats Document data for bundling a DocumentSnapshot.
-function documentToDocumentSnapshotBundleData(
-  path: string,
-  documentData: DocumentData,
-  document: Document
-): DocumentSnapshotBundleData {
-  return {
-    documentData,
-    documentKey: document.mutableCopy().key,
-    documentPath: path,
-    documentExists: true,
-    createdTime: document.createTime.toTimestamp(),
-    readTime: document.readTime.toTimestamp(),
-    versionTime: document.version.toTimestamp()
-  };
-}

packages/firestore/src/platform/browser/snapshot_to_json.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** Return the Platform-specific build JSON bundle implementations. */
+import { Firestore } from '../../api/database';
+import { Query } from '../../core/query';
+import { DocumentData } from '../../lite-api/reference';
+import { Document } from '../../model/document';
+
+export function buildDocumentSnapshotJsonBundle(
+  db: Firestore,
+  document: Document,
+  docData: DocumentData,
+  path: string
+): string {
+  return 'NOT SUPPORTED';
+}
+
+export function buildQuerySnapshotJsonBundle(
+  db: Firestore,
+  query: Query,
+  bundleName: string,
+  parent: string,
+  paths: string[],
+  docs: Document[],
+  documentData: DocumentData[]
+): string {
+  return 'NOT SUPPORTED';
+}

packages/firestore/src/platform/browser_lite/snapshot_to_json.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from '../browser/snapshot_to_json';

packages/firestore/src/platform/node/snapshot_to_json.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** Return the Platform-specific build JSON bundle implementations. */
+import { Firestore } from '../../api/database';
+import { Query } from '../../core/query';
+import { DocumentData } from '../../lite-api/reference';
+import { Document } from '../../model/document';
+import {
+  BundleBuilder,
+  DocumentSnapshotBundleData,
+  QuerySnapshotBundleData
+} from '../../util/bundle_builder_impl';
+import { AutoId } from '../../util/misc';
+
+export function buildDocumentSnapshotJsonBundle(
+  db: Firestore,
+  document: Document,
+  docData: DocumentData,
+  path: string
+): string {
+  const builder: BundleBuilder = new BundleBuilder(db, AutoId.newId());
+  builder.addBundleDocument(
+    documentToDocumentSnapshotBundleData(path, docData, document)
+  );
+  return builder.build();
+}
+
+export function buildQuerySnapshotJsonBundle(
+  db: Firestore,
+  query: Query,
+  bundleName: string,
+  parent: string,
+  paths: string[],
+  docs: Document[],
+  documentData: DocumentData[]
+): string {
+  const docBundleDataArray: DocumentSnapshotBundleData[] = [];
+  for (let i = 0; i < docs.length; i++) {
+    docBundleDataArray.push(
+      documentToDocumentSnapshotBundleData(paths[i], documentData[i], docs[i])
+    );
+  }
+  const bundleData: QuerySnapshotBundleData = {
+    name: bundleName,
+    query,
+    parent,
+    docBundleDataArray
+  };
+  const builder: BundleBuilder = new BundleBuilder(db, bundleName);
+  builder.addBundleQuery(bundleData);
+  return builder.build();
+}
+
+// Formats Document data for bundling a DocumentSnapshot.
+function documentToDocumentSnapshotBundleData(
+  path: string,
+  documentData: DocumentData,
+  document: Document
+): DocumentSnapshotBundleData {
+  return {
+    documentData,
+    documentKey: document.mutableCopy().key,
+    documentPath: path,
+    documentExists: true,
+    createdTime: document.createTime.toTimestamp(),
+    readTime: document.readTime.toTimestamp(),
+    versionTime: document.version.toTimestamp()
+  };
+}

packages/firestore/src/platform/node_lite/snapshot_to_json.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from '../node/snapshot_to_json';

packages/firestore/src/platform/rn/snapshot_to_json.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {
+  buildDocumentSnapshotJsonBundle,
+  buildQuerySnapshotJsonBundle
+} from '../browser/snapshot_to_json';