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

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));

package/src/index.ts

@@ -0,0 +1,100 @@
+/*
+ * Copyright 2019 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 { PubSub } from "@google-cloud/pubsub";
+import * as admin from "firebase-admin";
+import { getFirestore } from "firebase-admin/firestore";
+import * as functionsV1 from "firebase-functions/v1";
+import type { Role } from "firebase-functions/v2";
+import { requiresRole } from "firebase-functions/v2";
+import { onMessagePublished } from "firebase-functions/v2/pubsub";
+import { CONFIG_EXPRESSIONS, configFromEnv } from "./config";
+import * as events from "./events";
+import { getDatabaseUrl, resolveDeleteUserDataConfig } from "./export-config";
+import {
+  type HandlerContext,
+  handleClear,
+  handleDeletion as runDeletion,
+  handleSearch as runSearch,
+} from "./handlers";
+import * as logs from "./logs";
+
+export * from "./lib";
+
+const REQUIRED_ROLES: ReadonlyArray<Role> = [
+  "roles/datastore.owner",
+  "roles/firebasedatabase.admin",
+  "roles/storage.admin",
+  "roles/pubsub.admin",
+  // Gen2 event triggers need Eventarc receive and run.invoker on the function SA.
+  "roles/eventarc.eventReceiver",
+  "roles/run.invoker",
+];
+
+for (const role of REQUIRED_ROLES) {
+  requiresRole(role);
+}
+
+let ctx: HandlerContext | undefined;
+
+function getContext(): HandlerContext {
+  if (ctx) {
+    return ctx;
+  }
+
+  const resolved = resolveDeleteUserDataConfig(configFromEnv());
+  const databaseURL = getDatabaseUrl(
+    resolved.rtdbInstance,
+    resolved.rtdbLocation
+  );
+
+  if (admin.apps.length === 0) {
+    admin.initializeApp({
+      credential: admin.credential.applicationDefault(),
+      ...(databaseURL ? { databaseURL } : {}),
+    });
+  }
+
+  events.setupEventChannel();
+  logs.init(resolved);
+
+  ctx = {
+    firestore: getFirestore(resolved.firestoreDatabaseId),
+    storage: admin.storage(),
+    database: admin.database(),
+    pubsub: new PubSub({ projectId: resolved.projectId }),
+    config: resolved,
+  };
+  return ctx;
+}
+
+export const clearData = functionsV1.auth.user().onDelete((user) => {
+  return handleClear(user.uid, getContext());
+});
+
+export const handleSearch = onMessagePublished(
+  {
+    topic: CONFIG_EXPRESSIONS.discoveryTopicName,
+  },
+  (event) => runSearch(event.data.message.json, getContext())
+);
+
+export const handleDeletion = onMessagePublished(
+  {
+    topic: CONFIG_EXPRESSIONS.deletionTopicName,
+  },
+  (event) => runDeletion(event.data.message.json, getContext())
+);

package/src/lib.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 DeleteUserDataConfig,
+  type FirestoreDeleteMode,
+  getDatabaseUrl,
+  type ResolvedDeleteUserDataConfig,
+  resolveDeleteUserDataConfig,
+} from "./export-config";
+export {
+  type DeleteMessageData,
+  type HandlerContext,
+  handleClear,
+  handleDeletion,
+  handleSearch,
+  type SearchMessageData,
+} from "./handlers";
+export { extractUserPaths, hasValidUserPath } from "./helpers";
+export { recursiveDelete } from "./recursiveDelete";
+export {
+  type DeletionPaths,
+  type PublisherContext,
+  publishSearch,
+  runBatchPubSubDeletions,
+} from "./runBatchPubSubDeletions";
+export { runCustomSearchFunction } from "./runCustomSearchFunction";
+export { search } from "./search";

package/src/logs.ts

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2019 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 { logger } from "firebase-functions";
+import type { ResolvedDeleteUserDataConfig } from "./export-config";
+
+export const complete = (uid: string) => {
+  logger.log(`Successfully removed data for user: ${uid}`);
+};
+
+export const firestoreDeleted = () => {
+  logger.log("Finished deleting user data from Cloud Firestore");
+};
+
+export const firestoreDeleting = () => {
+  logger.log("Deleting user data from Cloud Firestore");
+};
+
+export const firestoreNotConfigured = () => {
+  logger.log("Cloud Firestore paths are not configured, skipping");
+};
+
+export const firestorePathDeleted = (path: string, recursive: boolean) => {
+  logger.log(
+    `Deleted: '${path}' from Cloud Firestore ${
+      recursive ? "with recursive delete" : ""
+    }`
+  );
+};
+
+export const firestorePathDeleting = (path: string, recursive: boolean) => {
+  logger.log(
+    `Deleting: '${path}' from Cloud Firestore ${
+      recursive ? "with recursive delete" : ""
+    }`
+  );
+};
+
+export const firestorePathError = (path: string, err: Error) => {
+  logger.error(`Error when deleting: '${path}' from Cloud Firestore`, err);
+};
+
+export const init = (config: ResolvedDeleteUserDataConfig) => {
+  logger.log("Initializing extension with configuration", config);
+};
+
+export const rtdbDeleted = () => {
+  logger.log("Finished deleting user data from the Realtime Database");
+};
+
+export const rtdbDeleting = () => {
+  logger.log("Deleting user data from the Realtime Database");
+};
+
+export const rtdbPathDeleted = (path: string) => {
+  logger.log(`Deleted: '${path}' from the Realtime Database`);
+};
+
+export const rtdbNotConfigured = () => {
+  logger.log("Realtime Database paths are not configured, skipping");
+};
+
+export const rtdbPathDeleting = (path: string) => {
+  logger.log(`Deleting: '${path}' from the Realtime Database`);
+};
+
+export const rtdbPathError = (path: string, err: Error) => {
+  logger.error(
+    `Error when deleting: '${path}' from the Realtime Database`,
+    err
+  );
+};
+
+export const start = (config: ResolvedDeleteUserDataConfig) => {
+  logger.log("Started extension execution with configuration", config);
+};
+
+export const storageDeleted = () => {
+  logger.log("Finished deleting user data from Cloud Storage");
+};
+
+export const storageDeleting = () => {
+  logger.log("Deleting user data from Cloud Storage");
+};
+
+export const storageNotConfigured = () => {
+  logger.log("Cloud Storage paths are not configured, skipping");
+};
+
+export const storagePathDeleted = (path: string) => {
+  logger.log(`Deleted: '${path}' from Cloud Storage`);
+};
+
+export const storagePathDeleting = (path: string) => {
+  logger.log(`Deleting: '${path}' from Cloud Storage`);
+};
+
+export const storagePath404 = (path: string) => {
+  logger.log(`File: '${path}' does not exist in Cloud Storage, skipping`);
+};
+
+export const storagePathError = (path: string, err: Error) => {
+  logger.error(`Error deleting: '${path}' from Cloud Storage`, err);
+};
+
+export const customFunctionError = (err: Error) => {
+  logger.error(`Call to custom hook function threw an error`, err);
+};
+
+export function warnInvalidPaths(invalidPathCount: number, uid: string) {
+  logger.warn(
+    `Attempted to delete ${invalidPathCount} invalid paths for deleted user ${uid}`
+  );
+}