@firebase-function-kits/delete-user-data 0.0.1 → 0.0.2-rc.1

package/package.json

@@ -1,12 +1,45 @@
 {
   "name": "@firebase-function-kits/delete-user-data",
-  "version": "0.0.1",
+  "version": "0.0.2-rc.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/firebase/extensions.git",
+    "directory": "kits/delete-user-data"
+  },
   "description": "Delete user data across Firestore, RTDB, and Storage on account deletion",
   "license": "Apache-2.0",
-  "main": "index.js",
-  "private": false,
-  "repository": "firebase/extensions",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./lib": {
+      "types": "./lib/lib.d.ts",
+      "default": "./lib/lib.js"
+    }
+  },
   "engines": {
     "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run",
+    "deploy": "pnpm build && firebase deploy --only functions",
+    "serve": "firebase emulators:start --only functions"
+  },
+  "dependencies": {
+    "@google-cloud/pubsub": "^4.3.3",
+    "firebase-admin": "^13.2.0",
+    "firebase-functions": "7.3.2",
+    "lodash.chunk": "^4.2.0",
+    "node-fetch": "^2.6.2"
+  },
+  "devDependencies": {
+    "@types/lodash.chunk": "^4.2.7",
+    "@types/node-fetch": "^2.6.2",
+    "vitest": "^4.1.10"
   }
 }

package/src/config.ts

@@ -0,0 +1,188 @@
+/**
+ * Copyright 2026 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
+ *
+ *    https://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.
+ */
+
+import {
+  defineBoolean,
+  defineInt,
+  defineString,
+  expr,
+  projectID,
+  select,
+  storageBucket,
+} from "firebase-functions/params";
+import type { DeleteUserDataConfig } from "./export-config";
+
+const instanceId = defineString("INSTANCE_ID");
+
+const params = {
+  instanceId,
+  firestorePaths: defineString("FIRESTORE_PATHS", {
+    label: "Cloud Firestore paths",
+    description:
+      "Which paths in your Cloud Firestore instance contain data keyed on a user ID? Leave empty if you don't use Cloud Firestore.\nEnter the full paths, separated by commas. Use `{UID}` as a placeholder for the user's UID.\nFor example, if you have the collections `users` and `admins`, and each collection has documents with User ID as document IDs, then enter `users/{UID},admins/{UID}`.",
+    default: "",
+    input: { text: { example: "users/{UID},admins/{UID}" } },
+  }),
+  firestoreDatabaseId: defineString("FIRESTORE_DATABASE_ID", {
+    label: "Firestore Database ID",
+    description:
+      'The ID of the Firestore database to use. Use "(default)" for the default database. You can view your available Firestore databases at https://console.cloud.google.com/firestore/databases.',
+
+    default: "(default)",
+  }),
+  firestoreDeleteMode: defineString("FIRESTORE_DELETE_MODE", {
+    label: "Cloud Firestore delete mode",
+    description:
+      "(Only applicable if you use the `Cloud Firestore paths` parameter.) How do you want to delete Cloud Firestore documents? To also delete documents in subcollections, set this parameter to `recursive`.",
+
+    default: "shallow",
+    input: select({ Recursive: "recursive", Shallow: "shallow" }),
+  }),
+  rtdbInstance: defineString("SELECTED_DATABASE_INSTANCE", {
+    label: "Realtime Database instance",
+    description:
+      "What is the ID of the Realtime Database instance from which you want to delete user data (keyed on user ID)?",
+
+    default: "",
+    input: {
+      text: {
+        example: "my-instance",
+
+        // Extension regex, with an empty branch added: the param is optional.
+        validationRegex: /^(?:[^\.\$\#\]\[\/\x00-\x1F\x7F]+|)$/,
+        validationErrorMessage:
+          "Invalid database instance. Make sure that you have entered just the instance ID, and not the entire database URL.",
+      },
+    },
+  }),
+  rtdbLocation: defineString("SELECTED_DATABASE_LOCATION", {
+    label: "Realtime Database location",
+    description:
+      "(Only applicable if you provided the `Realtime Database instance` parameter.) From which Realtime Database location do you want to delete data keyed on a user ID?",
+
+    default: "us-central1",
+    input: select({
+      "United States": "us-central1",
+      Belgium: "europe-west1",
+      Singapore: "asia-southeast1",
+    }),
+  }),
+  rtdbPaths: defineString("RTDB_PATHS", {
+    label: "Realtime Database paths",
+    description:
+      "Which paths in your Realtime Database instance contain data keyed on a user ID? Leave empty if you don't use Realtime Database.\nEnter the full paths, separated by commas. Use `{UID}` as a placeholder for the user's UID.\nFor example: `users/{UID},admins/{UID}`.",
+    default: "",
+    input: { text: { example: "users/{UID},admins/{UID}" } },
+  }),
+  storageBucket: defineString("CLOUD_STORAGE_BUCKET", {
+    label: "Cloud Storage bucket",
+    description:
+      "Which Google Cloud Storage bucket do you want to delete files from?",
+
+    default: storageBucket,
+    input: {
+      text: {
+        example: "my-project-12345.appspot.com",
+
+        validationRegex: /^([0-9a-z_.-]*)$/,
+        validationErrorMessage: "Invalid storage bucket",
+      },
+    },
+  }),
+  storagePaths: defineString("STORAGE_PATHS", {
+    label: "Cloud Storage paths",
+    description:
+      "Where in Google Cloud Storage do you store data keyed on a user ID? Leave empty if you don't use Cloud Storage.\nEnter the full paths to files or directories in your Storage buckets, separated by commas. Use `{UID}` to represent the User ID of the deleted user, and use `{DEFAULT}` to represent your default Storage bucket.\nHere's a series of examples. To delete all the files in your default bucket with the file naming scheme `{UID}-pic.png`, enter `{DEFAULT}/{UID}-pic.png`. To also delete all the files in another bucket called my-app-logs with the file naming scheme `{UID}-logs.txt`, enter `{DEFAULT}/{UID}-pic.png,my-app-logs/{UID}-logs.txt`. To *also* delete a User ID-labeled directory and all its files (like `media/{UID}`), enter `{DEFAULT}/{UID}-pic.png,my-app-logs/{UID}-logs.txt,{DEFAULT}/media/{UID}`.",
+    default: "",
+    input: {
+      text: {
+        example: "{DEFAULT}/{UID}-pic.png,my-awesome-app-logs/{UID}-logs.txt",
+      },
+    },
+  }),
+  enableAutoDiscovery: defineBoolean("ENABLE_AUTO_DISCOVERY", {
+    label: "Enable auto discovery",
+    description:
+      "Enable the extension to automatically discover Firestore collections and documents to delete.",
+
+    default: false,
+  }),
+  searchDepth: defineInt("AUTO_DISCOVERY_SEARCH_DEPTH", {
+    label: "Auto discovery search depth",
+    description:
+      "If auto discovery is enabled, how deep should auto discovery find collections and documents. For example, setting to `1` would only discover root collections and documents, whereas setting to `9` would search sub-collections 9 levels deep. Defaults to `3`.",
+    default: 3,
+  }),
+  searchFields: defineString("AUTO_DISCOVERY_SEARCH_FIELDS", {
+    label: "Auto discovery search fields",
+    description:
+      "If auto discovery is enabled, specify what document fields are used to associate the UID with the document. The extension will delete documents where the value for one or more of these fields matches the deleting user’s UID. If left empty, document fields will not be used in auto discovery.",
+
+    default: "id,uid,userId",
+  }),
+  searchFunction: defineString("SEARCH_FUNCTION", {
+    label: "Search function URL",
+    description:
+      "Specify a URL to call that will return a list of document paths to delete. The extension will send a `POST` request to the specified `URL`, with the `uid` of the deleted user will be provided in the body of the request. The endpoint specified should return an array of firestore paths to delete.",
+    default: "",
+    input: {
+      text: {
+        example:
+          "https://us-west1-my-project-id.cloudfunctions.net/myTransformFunction",
+      },
+    },
+  }),
+  // Non-empty defaults so Pub/Sub trigger bindings resolve during deploy
+  // discovery without freezing an empty topic name into the manifest.
+  discoveryTopicName: defineString("DISCOVERY_TOPIC_NAME", {
+    default: expr`kit-${instanceId}-discovery`,
+  }),
+  deletionTopicName: defineString("DELETION_TOPIC_NAME", {
+    default: expr`kit-${instanceId}-deletion`,
+  }),
+};
+
+export const CONFIG_EXPRESSIONS = {
+  discoveryTopicName: params.discoveryTopicName,
+  deletionTopicName: params.deletionTopicName,
+} as const;
+
+function optional(value: string): string | undefined {
+  return value.length > 0 ? value : undefined;
+}
+
+export function configFromEnv(): DeleteUserDataConfig {
+  return {
+    firestorePaths: optional(params.firestorePaths.value()),
+    firestoreDatabaseId: params.firestoreDatabaseId.value(),
+    firestoreDeleteMode:
+      params.firestoreDeleteMode.value() as DeleteUserDataConfig["firestoreDeleteMode"],
+    rtdbInstance: optional(params.rtdbInstance.value()),
+    rtdbLocation: optional(params.rtdbLocation.value()),
+    rtdbPaths: optional(params.rtdbPaths.value()),
+    storageBucket:
+      optional(params.storageBucket.value()) ?? process.env.STORAGE_BUCKET,
+    storagePaths: optional(params.storagePaths.value()),
+    enableAutoDiscovery: params.enableAutoDiscovery.value(),
+    searchDepth: params.searchDepth.value(),
+    searchFields: params.searchFields.value(),
+    searchFunction: optional(params.searchFunction.value()),
+    instanceId: params.instanceId.value(),
+    discoveryTopicName: optional(params.discoveryTopicName.value()),
+    deletionTopicName: optional(params.deletionTopicName.value()),
+    projectId: projectID.value(),
+  };
+}

package/src/events.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright 2026 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
+ *
+ *    https://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.
+ */
+
+import * as eventArc from "firebase-admin/eventarc";
+
+let eventChannel: eventArc.Channel | undefined;
+
+export const setupEventChannel = (): void => {
+  eventChannel = process.env.EVENTARC_CHANNEL
+    ? eventArc.getEventarc().channel(process.env.EVENTARC_CHANNEL, {
+        allowedEventTypes: process.env.EXT_SELECTED_EVENTS,
+      })
+    : undefined;
+};
+
+export async function publishDeletionEvent(
+  target: "firestore" | "database" | "storage",
+  data: object
+): Promise<unknown> {
+  if (!eventChannel) return Promise.resolve();
+  return eventChannel.publish({
+    type: `firebase.extensions.delete-user-data.v1.${target}`,
+    data,
+  });
+}

package/src/export-config.ts

@@ -0,0 +1,112 @@
+/**
+ * Copyright 2026 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
+ *
+ *    https://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 type FirestoreDeleteMode = "recursive" | "shallow";
+
+export interface DeleteUserDataConfig {
+  firestorePaths?: string;
+  firestoreDatabaseId?: string;
+  firestoreDeleteMode?: FirestoreDeleteMode;
+  rtdbInstance?: string;
+  rtdbLocation?: string;
+  rtdbPaths?: string;
+  storageBucket?: string;
+  storagePaths?: string;
+  enableAutoDiscovery?: boolean;
+  searchDepth?: number;
+  searchFields?: string;
+  searchFunction?: string;
+  instanceId: string;
+  discoveryTopicName?: string;
+  deletionTopicName?: string;
+  projectId?: string;
+}
+
+export interface ResolvedDeleteUserDataConfig {
+  firestorePaths?: string;
+  firestoreDatabaseId: string;
+  firestoreDeleteMode: FirestoreDeleteMode;
+  rtdbInstance?: string;
+  rtdbLocation?: string;
+  rtdbPaths?: string;
+  storageBucket?: string;
+  storagePaths?: string;
+  enableAutoDiscovery: boolean;
+  searchDepth: number;
+  searchFields: string;
+  searchFunction?: string;
+  instanceId: string;
+  discoveryTopicName: string;
+  deletionTopicName: string;
+  projectId?: string;
+}
+
+const DEFAULT_FIRESTORE_DATABASE_ID = "(default)";
+const DEFAULT_FIRESTORE_DELETE_MODE: FirestoreDeleteMode = "shallow";
+const DEFAULT_SEARCH_DEPTH = 3;
+const DEFAULT_SEARCH_FIELDS = "id,uid,userId";
+function topicName(
+  name: string | undefined,
+  instanceId: string,
+  suffix: string
+): string {
+  return name ?? `kit-${instanceId}-${suffix}`;
+}
+
+export function resolveDeleteUserDataConfig(
+  config: DeleteUserDataConfig
+): ResolvedDeleteUserDataConfig {
+  const instanceId = config.instanceId;
+  return {
+    firestorePaths: config.firestorePaths,
+    firestoreDatabaseId:
+      config.firestoreDatabaseId ?? DEFAULT_FIRESTORE_DATABASE_ID,
+    firestoreDeleteMode:
+      config.firestoreDeleteMode ?? DEFAULT_FIRESTORE_DELETE_MODE,
+    rtdbInstance: config.rtdbInstance,
+    rtdbLocation: config.rtdbLocation,
+    rtdbPaths: config.rtdbPaths,
+    storageBucket: config.storageBucket,
+    storagePaths: config.storagePaths,
+    enableAutoDiscovery: config.enableAutoDiscovery ?? false,
+    searchDepth: config.searchDepth ?? DEFAULT_SEARCH_DEPTH,
+    searchFields: config.searchFields ?? DEFAULT_SEARCH_FIELDS,
+    searchFunction: config.searchFunction,
+    instanceId,
+    discoveryTopicName: topicName(
+      config.discoveryTopicName,
+      instanceId,
+      "discovery"
+    ),
+    deletionTopicName: topicName(
+      config.deletionTopicName,
+      instanceId,
+      "deletion"
+    ),
+    projectId: config.projectId,
+  };
+}
+
+export function getDatabaseUrl(
+  selectedDatabaseInstance: string | undefined,
+  selectedDatabaseLocation: string | undefined
+): string | null {
+  if (!selectedDatabaseLocation || !selectedDatabaseInstance) return null;
+  if (selectedDatabaseLocation === "us-central1") {
+    return `https://${selectedDatabaseInstance}.firebaseio.com`;
+  }
+  return `https://${selectedDatabaseInstance}.${selectedDatabaseLocation}.firebasedatabase.app`;
+}

package/src/handlers.ts

@@ -0,0 +1,271 @@
+/**
+ * Copyright 2026 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
+ *
+ *    https://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.
+ */
+
+import type * as admin from "firebase-admin";
+import type { DocumentReference } from "firebase-admin/firestore";
+import { FieldPath } from "firebase-admin/firestore";
+import chunk from "lodash.chunk";
+import * as events from "./events";
+import { extractUserPaths, hasValidUserPath } from "./helpers";
+import * as logs from "./logs";
+import { recursiveDelete } from "./recursiveDelete";
+import {
+  type PublisherContext,
+  runBatchPubSubDeletions,
+} from "./runBatchPubSubDeletions";
+import { runCustomSearchFunction } from "./runCustomSearchFunction";
+import { search } from "./search";
+
+export interface HandlerContext extends PublisherContext {
+  firestore: admin.firestore.Firestore;
+  storage: admin.storage.Storage;
+  database: admin.database.Database;
+}
+
+export interface DeleteMessageData {
+  paths: string[];
+  uid: string;
+}
+
+export interface SearchMessageData {
+  path: string;
+  depth: number;
+  uid: string;
+}
+
+export async function handleDeletion(
+  data: DeleteMessageData,
+  ctx: HandlerContext
+): Promise<void> {
+  const { paths, uid } = data;
+  const batchArray: admin.firestore.WriteBatch[] = [];
+  const invalidPaths: string[] = [];
+
+  for (const chunkedPaths of chunk<string>(paths, 450)) {
+    const batch = ctx.firestore.batch();
+    for (const path of chunkedPaths) {
+      const docRef = ctx.firestore.doc(path);
+      const isValidPath = await hasValidUserPath(
+        docRef,
+        path,
+        uid,
+        ctx.config.searchFields
+      );
+
+      if (!isValidPath) {
+        invalidPaths.push(path);
+        continue;
+      }
+      if (ctx.config.firestoreDeleteMode === "recursive") {
+        await recursiveDelete(path, ctx.firestore);
+      } else {
+        batch.delete(docRef);
+      }
+    }
+    batchArray.push(batch);
+  }
+
+  await Promise.all(batchArray.map((batch) => batch.commit()));
+
+  if (invalidPaths.length > 0) {
+    logs.warnInvalidPaths(invalidPaths.length, uid);
+  }
+
+  await events.publishDeletionEvent("firestore", {
+    uid,
+    documentPaths: paths,
+    invalidPaths,
+  });
+}
+
+export async function handleSearch(
+  data: SearchMessageData,
+  ctx: HandlerContext
+): Promise<void> {
+  const { path, depth, uid } = data;
+  const nextDepth = depth + 1;
+  const collection = ctx.firestore.collection(path);
+
+  if (depth > ctx.config.searchDepth) return;
+
+  if (collection.id === uid) {
+    await recursiveDelete(path, ctx.firestore);
+    await events.publishDeletionEvent("firestore", {
+      uid,
+      collectionPath: collection.path,
+    });
+    return;
+  }
+
+  const documentReferences = await collection.listDocuments();
+  const documentReferencesToSearch: DocumentReference[] = [];
+  const pathsToDelete: string[] = [];
+
+  await Promise.all(
+    documentReferences.map(async (reference) => {
+      if (nextDepth <= ctx.config.searchDepth) {
+        await search(uid, nextDepth, ctx.firestore, ctx, reference);
+      }
+
+      if (reference.id === uid) {
+        pathsToDelete.push(reference.path);
+      } else if (ctx.config.searchFields) {
+        documentReferencesToSearch.push(reference);
+      }
+    })
+  );
+
+  if (documentReferencesToSearch.length > 0) {
+    const snapshots = await ctx.firestore.getAll(...documentReferencesToSearch);
+    for (const snapshot of snapshots) {
+      if (snapshot.exists) {
+        for (const field of ctx.config.searchFields.split(",")) {
+          if (snapshot.get(new FieldPath(field)) === uid) {
+            pathsToDelete.push(snapshot.ref.path);
+          }
+        }
+      }
+    }
+  }
+
+  await runBatchPubSubDeletions({ firestorePaths: pathsToDelete }, uid, ctx);
+}
+
+export async function handleClear(
+  uid: string,
+  ctx: HandlerContext
+): Promise<void> {
+  logs.start(ctx.config);
+
+  const promises: Promise<void>[] = [];
+  if (ctx.config.firestorePaths) {
+    promises.push(clearFirestoreData(ctx.config.firestorePaths, uid, ctx));
+  } else {
+    logs.firestoreNotConfigured();
+  }
+  if (ctx.config.rtdbPaths) {
+    promises.push(clearDatabaseData(ctx.config.rtdbPaths, uid, ctx));
+  } else {
+    logs.rtdbNotConfigured();
+  }
+  if (ctx.config.storagePaths) {
+    promises.push(clearStorageData(ctx.config.storagePaths, uid, ctx));
+  } else {
+    logs.storageNotConfigured();
+  }
+
+  await Promise.all(promises);
+
+  if (ctx.config.enableAutoDiscovery) {
+    await search(uid, 1, ctx.firestore, ctx);
+  }
+
+  if (ctx.config.searchFunction) {
+    await runCustomSearchFunction(uid, ctx);
+  }
+
+  logs.complete(uid);
+}
+
+async function clearDatabaseData(
+  databasePaths: string,
+  uid: string,
+  ctx: HandlerContext
+): Promise<void> {
+  logs.rtdbDeleting();
+  const paths = extractUserPaths(databasePaths, uid);
+  await Promise.all(
+    paths.map(async (path) => {
+      try {
+        logs.rtdbPathDeleting(path);
+        await ctx.database.ref(path).remove();
+        logs.rtdbPathDeleted(path);
+      } catch (err) {
+        logs.rtdbPathError(path, err as Error);
+      }
+    })
+  );
+  await events.publishDeletionEvent("database", { uid, paths });
+  logs.rtdbDeleted();
+}
+
+async function clearStorageData(
+  storagePaths: string,
+  uid: string,
+  ctx: HandlerContext
+): Promise<void> {
+  logs.storageDeleting();
+  const paths = extractUserPaths(storagePaths, uid);
+  await Promise.all(
+    paths.map(async (path) => {
+      const parts = path.split("/");
+      const bucketName = parts[0];
+      const bucket =
+        bucketName === "{DEFAULT}"
+          ? ctx.storage.bucket(ctx.config.storageBucket)
+          : ctx.storage.bucket(bucketName);
+      const prefix = parts.slice(1).join("/");
+      try {
+        logs.storagePathDeleting(prefix);
+        await bucket.deleteFiles({ prefix });
+        logs.storagePathDeleted(prefix);
+      } catch (err) {
+        if ((err as { code?: number }).code === 404) {
+          logs.storagePath404(prefix);
+        } else {
+          logs.storagePathError(prefix, err as Error);
+        }
+      }
+    })
+  );
+  await events.publishDeletionEvent("storage", { uid, paths });
+  logs.storageDeleted();
+}
+
+async function clearFirestoreData(
+  firestorePaths: string,
+  uid: string,
+  ctx: HandlerContext
+): Promise<void> {
+  logs.firestoreDeleting();
+  const paths = extractUserPaths(firestorePaths, uid);
+  await Promise.all(
+    paths.map(async (path) => {
+      try {
+        const isRecursive = ctx.config.firestoreDeleteMode === "recursive";
+        if (!isRecursive) {
+          logs.firestorePathDeleting(path, false);
+          await ctx.firestore.runTransaction((transaction) => {
+            transaction.delete(ctx.firestore.doc(path));
+            return Promise.resolve();
+          });
+          logs.firestorePathDeleted(path, false);
+        } else {
+          logs.firestorePathDeleting(path, true);
+          await recursiveDelete(path, ctx.firestore);
+          logs.firestorePathDeleted(path, true);
+        }
+      } catch (err) {
+        logs.firestorePathError(path, err as Error);
+      }
+    })
+  );
+  await events.publishDeletionEvent("firestore", {
+    uid,
+    documentPaths: paths,
+  });
+  logs.firestoreDeleted();
+}

package/src/helpers.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2026 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
+ *
+ *    https://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.
+ */
+
+import { type DocumentReference, FieldPath } from "firebase-admin/firestore";
+
+export const hasValidUserPath = async (
+  ref: DocumentReference,
+  path: string,
+  uid: string,
+  searchFields: string
+): Promise<boolean> => {
+  if (path.includes(uid)) return true;
+  if (searchFields.length === 0) return false;
+
+  const snapshot = await ref.get();
+  if (snapshot.exists) {
+    for (const field of searchFields.split(",").filter(Boolean)) {
+      const fieldValue = snapshot.get(new FieldPath(field));
+      if (typeof fieldValue === "string" && fieldValue.includes(uid)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+};
+
+export const extractUserPaths = (paths: string, uid: string): string[] =>
+  paths.split(",").map((path) => path.replace(/{UID}/g, uid));