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

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}`
+  );
+}

package/src/recursiveDelete.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 * as admin from "firebase-admin";
+
+const MAX_RETRY_ATTEMPTS = 3;
+
+export const recursiveDelete = async (
+  path: string,
+  db: admin.firestore.Firestore
+) => {
+  // Recursively delete a reference and log the references of failures.
+  const bulkWriter = db.bulkWriter();
+
+  bulkWriter.onWriteError((error) => {
+    if (error.failedAttempts < MAX_RETRY_ATTEMPTS) {
+      return true;
+    } else {
+      console.warn("Failed to delete document: ", error.documentRef.path);
+      return false;
+    }
+  });
+
+  const isDocument = path.split("/").length % 2 === 0;
+
+  const reference = isDocument ? db.doc(path) : db.collection(path);
+
+  await db.recursiveDelete(reference, bulkWriter);
+};

package/src/runBatchPubSubDeletions.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 { PubSub } from "@google-cloud/pubsub";
+import chunk from "lodash.chunk";
+import type { ResolvedDeleteUserDataConfig } from "./export-config";
+
+export interface DeletionPaths {
+  firestorePaths: string[];
+}
+
+export interface PublisherContext {
+  pubsub: PubSub;
+  config: ResolvedDeleteUserDataConfig;
+}
+
+function topicPath(
+  config: ResolvedDeleteUserDataConfig,
+  topicName: string
+): string {
+  const projectId =
+    config.projectId ??
+    process.env.GOOGLE_CLOUD_PROJECT ??
+    process.env.PROJECT_ID;
+  return projectId ? `projects/${projectId}/topics/${topicName}` : topicName;
+}
+
+export async function publishSearch(
+  uid: string,
+  depth: number,
+  path: string,
+  ctx: PublisherContext
+): Promise<void> {
+  await ctx.pubsub
+    .topic(topicPath(ctx.config, ctx.config.discoveryTopicName))
+    .publishMessage({ json: { path, uid, depth } });
+}
+
+export async function runBatchPubSubDeletions(
+  paths: DeletionPaths,
+  uid: string,
+  ctx: PublisherContext
+): Promise<void> {
+  const { firestorePaths } = paths;
+  if (!firestorePaths || !Array.isArray(firestorePaths)) return;
+  if (firestorePaths.length === 0) return;
+
+  for (const chunkedPaths of chunk<string>(firestorePaths, 450)) {
+    await ctx.pubsub
+      .topic(topicPath(ctx.config, ctx.config.deletionTopicName))
+      .publishMessage({ json: { paths: chunkedPaths, uid } });
+  }
+}

package/src/runCustomSearchFunction.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 fetch from "node-fetch";
+import * as logs from "./logs";
+import type { PublisherContext } from "./runBatchPubSubDeletions";
+import { runBatchPubSubDeletions } from "./runBatchPubSubDeletions";
+
+export const runCustomSearchFunction = async (
+  uid: string,
+  ctx: PublisherContext
+): Promise<void> => {
+  if (!ctx.config.searchFunction) return;
+
+  const response = await fetch(ctx.config.searchFunction, {
+    method: "POST",
+    body: JSON.stringify({ uid }),
+    headers: { "Content-Type": "application/json" },
+  });
+
+  if (!response.ok) {
+    const body = await response.text();
+    logs.customFunctionError(new Error(body));
+    return;
+  }
+
+  const json = await response.json();
+  if (Array.isArray(json)) {
+    return runBatchPubSubDeletions({ firestorePaths: json }, uid, ctx);
+  }
+
+  return runBatchPubSubDeletions(
+    json as { firestorePaths: string[] },
+    uid,
+    ctx
+  );
+};

package/src/search.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 PublisherContext,
+  publishSearch,
+} from "./runBatchPubSubDeletions";
+
+export const search = async (
+  uid: string,
+  depth: number,
+  db: admin.firestore.Firestore,
+  ctx: PublisherContext,
+  document?: admin.firestore.DocumentReference<admin.firestore.DocumentData>
+): Promise<void> => {
+  const collections = !document
+    ? await db.listCollections()
+    : await document.listCollections();
+
+  for (const collection of collections) {
+    await publishSearch(uid, depth, collection.path, ctx);
+  }
+};

package/tests/config.test.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 { afterEach, describe, expect, test, vi } from "vitest";
+
+class FakeExpression<_T = string> {
+  constructor(private readonly cel: string) {}
+
+  toCEL(): string {
+    return this.cel;
+  }
+}
+
+class FakeStringParam extends FakeExpression<string> {
+  constructor(
+    private readonly name: string,
+    private readonly defaultValue?: string | FakeExpression
+  ) {
+    super(`{{ params.${name} }}`);
+  }
+
+  value(): string {
+    if (this.defaultValue instanceof FakeStringParam) {
+      return this.defaultValue.value();
+    }
+    if (this.defaultValue instanceof FakeExpression) {
+      return this.defaultValue.toCEL();
+    }
+    return this.defaultValue ?? `${this.name.toLowerCase()}-value`;
+  }
+}
+
+const defineString = vi.fn(
+  (name: string, opts?: { default?: string | FakeExpression }) =>
+    new FakeStringParam(name, opts?.default)
+);
+
+const defineInt = vi.fn((_name: string, opts?: { default?: number }) => ({
+  value: () => opts?.default ?? 0,
+}));
+
+const defineBoolean = vi.fn((_name: string, opts?: { default?: boolean }) => ({
+  value: () => opts?.default ?? false,
+}));
+
+const expr = vi.fn(
+  (strings: TemplateStringsArray, ...values: unknown[]) =>
+    new FakeExpression(
+      strings.reduce(
+        (result, part, index) =>
+          result + part + (index < values.length ? cel(values[index]) : ""),
+        ""
+      )
+    )
+);
+
+function cel(value: unknown): string {
+  return value instanceof FakeExpression ? value.toCEL() : String(value);
+}
+
+vi.mock("firebase-functions/params", () => ({
+  Expression: FakeExpression,
+  defineBoolean,
+  defineInt,
+  defineString,
+  expr,
+  projectID: { value: () => "demo-test" },
+  select: vi.fn((options: string[]) => ({ options })),
+  storageBucket: new FakeStringParam("STORAGE_BUCKET", "demo-test.appspot.com"),
+}));
+
+async function importConfig() {
+  vi.resetModules();
+  defineString.mockClear();
+  defineInt.mockClear();
+  defineBoolean.mockClear();
+  expr.mockClear();
+
+  return import("../src/config");
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("configFromEnv", () => {
+  test("reads the extension.yaml defaults", async () => {
+    const { configFromEnv } = await importConfig();
+
+    expect(configFromEnv()).toMatchObject({
+      firestoreDatabaseId: "(default)",
+      firestoreDeleteMode: "shallow",
+      rtdbLocation: "us-central1",
+      enableAutoDiscovery: false,
+      searchDepth: 3,
+      searchFields: "id,uid,userId",
+      projectId: "demo-test",
+    });
+  });
+
+  test("maps empty params to undefined", async () => {
+    const { configFromEnv } = await importConfig();
+    const config = configFromEnv();
+
+    expect(config.firestorePaths).toBeUndefined();
+    expect(config.rtdbPaths).toBeUndefined();
+    expect(config.storagePaths).toBeUndefined();
+    expect(config.searchFunction).toBeUndefined();
+    expect(config.rtdbInstance).toBeUndefined();
+  });
+
+  test("declares the params the extension exposes", async () => {
+    await importConfig();
+
+    const declared = defineString.mock.calls.map(([name]) => name);
+    expect(declared).toEqual(
+      expect.arrayContaining([
+        "INSTANCE_ID",
+        "FIRESTORE_PATHS",
+        "FIRESTORE_DATABASE_ID",
+        "FIRESTORE_DELETE_MODE",
+        "SELECTED_DATABASE_INSTANCE",
+        "SELECTED_DATABASE_LOCATION",
+        "RTDB_PATHS",
+        "CLOUD_STORAGE_BUCKET",
+        "STORAGE_PATHS",
+        "AUTO_DISCOVERY_SEARCH_FIELDS",
+        "SEARCH_FUNCTION",
+        "DISCOVERY_TOPIC_NAME",
+        "DELETION_TOPIC_NAME",
+      ])
+    );
+    expect(defineInt.mock.calls).toContainEqual([
+      "AUTO_DISCOVERY_SEARCH_DEPTH",
+      expect.objectContaining({ default: 3 }),
+    ]);
+    expect(defineBoolean.mock.calls).toContainEqual([
+      "ENABLE_AUTO_DISCOVERY",
+      expect.objectContaining({ default: false }),
+    ]);
+  });
+
+  test("defaults the topic names to kit-{instanceId}-* expressions", async () => {
+    const { CONFIG_EXPRESSIONS } = await importConfig();
+
+    expect(cel(CONFIG_EXPRESSIONS.discoveryTopicName)).toBe(
+      "{{ params.DISCOVERY_TOPIC_NAME }}"
+    );
+    expect(cel(CONFIG_EXPRESSIONS.deletionTopicName)).toBe(
+      "{{ params.DELETION_TOPIC_NAME }}"
+    );
+    expect(expr.mock.results.map((result) => cel(result.value))).toEqual([
+      "kit-{{ params.INSTANCE_ID }}-discovery",
+      "kit-{{ params.INSTANCE_ID }}-deletion",
+    ]);
+    expect(defineString.mock.calls).toContainEqual([
+      "DISCOVERY_TOPIC_NAME",
+      { default: expect.anything() },
+    ]);
+  });
+
+  test("defaults the storage bucket to the project bucket param", async () => {
+    const { configFromEnv } = await importConfig();
+
+    expect(configFromEnv().storageBucket).toBe("demo-test.appspot.com");
+  });
+});