cloudfire-auth 0.1.0

package/dist/CloudFireAuth.js

@@ -0,0 +1,346 @@
+/*! firebase-admin v13.4.0 */
+/*!
+ * Copyright 2021 Google Inc.
+ *
+ * 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.
+ */
+// Rest API
+import { verifyIdTokenHandler } from "./rest-api/verify-id-token.js";
+import { getUserHandler } from "./rest-api/get-user.js";
+import { getUserByEmailHandler } from "./rest-api/get-user-by-email.js";
+import { getUserByPhoneNumberHandler } from "./rest-api/get-user-by-phone-number.js";
+import { getUserByProviderUidHandler } from "./rest-api/get-user-by-provider-uid.js";
+import { getUsersHandler } from "./rest-api/get-users.js";
+import { listUsersHandler } from "./rest-api/list-users.js";
+import { createUserHandler } from "./rest-api/create-user.js";
+import { deleteUserHandler } from "./rest-api/delete-user.js";
+import { deleteUsersHandler } from "./rest-api/delete-users.js";
+import { updateUserHandler } from "./rest-api/update-user.js";
+import { setCustomUserClaimsHandler } from "./rest-api/set-custom-user-claims.js";
+import { revokeRefreshTokensHandler } from "./rest-api/revoke-refresh-tokens.js";
+import { verifySessionCookieHandler } from "./rest-api/verify-session-cookie.js";
+// Google Auth
+import { getOauth2AccessTokenHandler } from "./google-auth/get-oauth-2-token.js";
+export class CloudFireAuth {
+    projectId;
+    serviceAccountKey;
+    oauth2Token;
+    kvNamespace;
+    constructor(serviceAccountKey, kvNamespace) {
+        this.projectId = serviceAccountKey.project_id;
+        this.serviceAccountKey = serviceAccountKey;
+        this.kvNamespace = kvNamespace;
+    }
+    /**
+     * Verifies a Firebase ID token (JWT). If the token is valid, the promise is
+     * fulfilled with the token's decoded claims; otherwise, the promise is
+     * rejected.
+     *
+     * If `checkRevoked` is set to true, first verifies whether the corresponding
+     * user is disabled. If yes, an `auth/user-disabled` error is thrown. If no,
+     * verifies if the session corresponding to the ID token was revoked. If the
+     * corresponding user's session was invalidated, an `auth/id-token-revoked`
+     * error is thrown. If not specified the check is not applied.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/verify-id-tokens | Verify ID Tokens}
+     * for code samples and detailed documentation.
+     *
+     * @param idToken - The ID token to verify.
+     * @param checkRevoked - Whether to check if the ID token was revoked.
+     *   This requires an extra request to the Firebase Auth backend to check
+     *   the `tokensValidAfterTime` time for the corresponding user.
+     *   When not specified, this additional check is not applied.
+     *
+     * @returns A promise fulfilled with the
+     *   token's decoded claims if the ID token is valid; otherwise, a rejected
+     *   promise.
+     */
+    async verifyIdToken(idToken, checkRevoked) {
+        const oauth2Token = await this.getOauth2AccessToken();
+        return await verifyIdTokenHandler(idToken, this.projectId, oauth2Token, this.kvNamespace, checkRevoked);
+    }
+    /**
+     * Gets the user data for the user corresponding to a given `uid`.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data}
+     * for code samples and detailed documentation.
+     *
+     * @param uid - The `uid` corresponding to the user whose data to fetch.
+     *
+     * @returns A promise fulfilled with the user
+     *   data corresponding to the provided `uid`.
+     */
+    async getUser(uid) {
+        const oauth2Token = await this.getOauth2AccessToken();
+        return await getUserHandler(uid, oauth2Token);
+    }
+    /**
+     * Gets the user data for the user corresponding to a given email.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data}
+     * for code samples and detailed documentation.
+     *
+     * @param email - The email corresponding to the user whose data to
+     *   fetch.
+     *
+     * @returns A promise fulfilled with the user
+     *   data corresponding to the provided email.
+     */
+    async getUserByEmail(email) {
+        return await getUserByEmailHandler(email);
+    }
+    /**
+     * Gets the user data for the user corresponding to a given phone number. The
+     * phone number has to conform to the E.164 specification.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data}
+     * for code samples and detailed documentation.
+     *
+     * @param phoneNumber - The phone number corresponding to the user whose
+     *   data to fetch.
+     *
+     * @returns A promise fulfilled with the user
+     *   data corresponding to the provided phone number.
+     */
+    async getUserByPhoneNumber(phoneNumber) {
+        return await getUserByPhoneNumberHandler(phoneNumber);
+    }
+    /**
+     * Gets the user data for the user corresponding to a given provider id.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#retrieve_user_data | Retrieve user data}
+     * for code samples and detailed documentation.
+     *
+     * @param providerId - The provider ID, for example, "google.com" for the
+     *   Google provider.
+     * @param uid - The user identifier for the given provider.
+     *
+     * @returns A promise fulfilled with the user data corresponding to the
+     *   given provider id.
+     */
+    async getUserByProviderUid(providerId, uid) {
+        return await getUserByProviderUidHandler(providerId, uid);
+    }
+    /**
+     * Gets the user data corresponding to the specified identifiers.
+     *
+     * There are no ordering guarantees; in particular, the nth entry in the result list is not
+     * guaranteed to correspond to the nth entry in the input parameters list.
+     *
+     * Only a maximum of 100 identifiers may be supplied. If more than 100 identifiers are supplied,
+     * this method throws a FirebaseAuthError.
+     *
+     * @param identifiers - The identifiers used to indicate which user records should be returned.
+     *     Must not have more than 100 entries.
+     * @returns A promise that resolves to the corresponding user records.
+     * @throws FirebaseAuthError If any of the identifiers are invalid or if more than 100
+     *     identifiers are specified.
+     */
+    async getUsers(identifiers) {
+        return await getUsersHandler(identifiers);
+    }
+    /**
+     * Retrieves a list of users (single batch only) with a size of `maxResults`
+     * starting from the offset as specified by `pageToken`. This is used to
+     * retrieve all the users of a specified project in batches.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#list_all_users | List all users}
+     * for code samples and detailed documentation.
+     *
+     * @param maxResults - The page size, 1000 if undefined. This is also
+     *   the maximum allowed limit.
+     * @param pageToken - The next page token. If not specified, returns
+     *   users starting without any offset.
+     * @returns A promise that resolves with
+     *   the current batch of downloaded users and the next page token.
+     */
+    async listUsers(maxResults, pageToken) {
+        return await listUsersHandler(maxResults, pageToken);
+    }
+    /**
+     * Creates a new user.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#create_a_user | Create a user}
+     * for code samples and detailed documentation.
+     *
+     * @param properties - The properties to set on the
+     *   new user record to be created.
+     *
+     * @returns A promise fulfilled with the user
+     *   data corresponding to the newly created user.
+     */
+    async createUser(properties) {
+        return await createUserHandler(properties);
+    }
+    /**
+     * Deletes an existing user.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#delete_a_user | Delete a user}
+     * for code samples and detailed documentation.
+     *
+     * @param uid - The `uid` corresponding to the user to delete.
+     *
+     * @returns An empty promise fulfilled once the user has been
+     *   deleted.
+     */
+    async deleteUser(uid) {
+        const oauth2Token = await this.getOauth2AccessToken();
+        await deleteUserHandler(uid, oauth2Token);
+    }
+    /**
+     * Deletes the users specified by the given uids.
+     *
+     * Deleting a non-existing user won't generate an error (i.e. this method
+     * is idempotent.) Non-existing users are considered to be successfully
+     * deleted, and are therefore counted in the
+     * `DeleteUsersResult.successCount` value.
+     *
+     * Only a maximum of 1000 identifiers may be supplied. If more than 1000
+     * identifiers are supplied, this method throws a FirebaseAuthError.
+     *
+     * This API is currently rate limited at the server to 1 QPS. If you exceed
+     * this, you may get a quota exceeded error. Therefore, if you want to
+     * delete more than 1000 users, you may need to add a delay to ensure you
+     * don't go over this limit.
+     *
+     * @param uids - The `uids` corresponding to the users to delete.
+     *
+     * @returns A Promise that resolves to the total number of successful/failed
+     *     deletions, as well as the array of errors that corresponds to the
+     *     failed deletions.
+     */
+    async deleteUsers(uids) {
+        return await deleteUsersHandler(uids);
+    }
+    /**
+     * Updates an existing user.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-users#update_a_user | Update a user}
+     * for code samples and detailed documentation.
+     *
+     * @param uid - The `uid` corresponding to the user to update.
+     * @param properties - The properties to update on
+     *   the provided user.
+     *
+     * @returns A promise fulfilled with the
+     *   updated user data.
+     */
+    async updateUser(uid, properties) {
+        const oauth2Token = await this.getOauth2AccessToken();
+        return await updateUserHandler(uid, properties, oauth2Token);
+    }
+    /**
+     * Sets additional developer claims on an existing user identified by the
+     * provided `uid`, typically used to define user roles and levels of
+     * access. These claims should propagate to all devices where the user is
+     * already signed in (after token expiration or when token refresh is forced)
+     * and the next time the user signs in. If a reserved OIDC claim name
+     * is used (sub, iat, iss, etc), an error is thrown. They are set on the
+     * authenticated user's ID token JWT.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/custom-claims |
+     * Defining user roles and access levels}
+     * for code samples and detailed documentation.
+     *
+     * @param uid - The `uid` of the user to edit.
+     * @param customUserClaims - The developer claims to set. If null is
+     *   passed, existing custom claims are deleted. Passing a custom claims payload
+     *   larger than 1000 bytes will throw an error. Custom claims are added to the
+     *   user's ID token which is transmitted on every authenticated request.
+     *   For profile non-access related user attributes, use database or other
+     *   separate storage systems.
+     * @returns A promise that resolves when the operation completes
+     *   successfully.
+     */
+    async setCustomUserClaims(uid, customUserClaims) {
+        const oauth2Token = await this.getOauth2AccessToken();
+        await setCustomUserClaimsHandler(uid, customUserClaims, oauth2Token);
+    }
+    /**
+     * Revokes all refresh tokens for an existing user.
+     *
+     * This API will update the user's {@link UserRecord.tokensValidAfterTime} to
+     * the current UTC. It is important that the server on which this is called has
+     * its clock set correctly and synchronized.
+     *
+     * While this will revoke all sessions for a specified user and disable any
+     * new ID tokens for existing sessions from getting minted, existing ID tokens
+     * may remain active until their natural expiration (one hour). To verify that
+     * ID tokens are revoked, use {@link BaseAuth.verifyIdToken}
+     * where `checkRevoked` is set to true.
+     *
+     * @param uid - The `uid` corresponding to the user whose refresh tokens
+     *   are to be revoked.
+     *
+     * @returns An empty promise fulfilled once the user's refresh
+     *   tokens have been revoked.
+     */
+    async revokeRefreshTokens(uid) {
+        const oauth2Token = await this.getOauth2AccessToken();
+        return await revokeRefreshTokensHandler(uid, oauth2Token);
+    }
+    /**
+     * Verifies a Firebase session cookie. Returns a Promise with the cookie claims.
+     * Rejects the promise if the cookie could not be verified.
+     *
+     * If `checkRevoked` is set to true, first verifies whether the corresponding
+     * user is disabled: If yes, an `auth/user-disabled` error is thrown. If no,
+     * verifies if the session corresponding to the session cookie was revoked.
+     * If the corresponding user's session was invalidated, an
+     * `auth/session-cookie-revoked` error is thrown. If not specified the check
+     * is not performed.
+     *
+     * See {@link https://firebase.google.com/docs/auth/admin/manage-cookies#verify_session_cookie_and_check_permissions |
+     * Verify Session Cookies}
+     * for code samples and detailed documentation
+     *
+     * @param sessionCookie - The session cookie to verify.
+     * @param checkForRevocation -  Whether to check if the session cookie was
+     *   revoked. This requires an extra request to the Firebase Auth backend to
+     *   check the `tokensValidAfterTime` time for the corresponding user.
+     *   When not specified, this additional check is not performed.
+     *
+     * @returns A promise fulfilled with the
+     *   session cookie's decoded claims if the session cookie is valid; otherwise,
+     *   a rejected promise.
+     */
+    async verifySessionCookie(sessionCookie, checkRevoked) {
+        return await verifySessionCookieHandler(sessionCookie, checkRevoked);
+    }
+    /**
+     * Gets an OAuth2 access token from Google's OAuth2 server. This token is
+     * required for accessing the Firebase Auth REST API via fetch requests.
+     *
+     * Checks if a token already exists in the KV namespace. If not, it gets a new
+     * token from Google's OAuth2 server, and sets it on the KV namespace.¨
+     *
+     * This code is under the MIT Licence.
+     *
+     * @returns The OAuth2 access token
+     */
+    async getOauth2AccessToken() {
+        if (this.oauth2Token) {
+            return this.oauth2Token;
+        }
+        let token = null;
+        if (this.kvNamespace) {
+            token = await this.kvNamespace?.get("oauth2Token");
+        }
+        if (!token) {
+            // Sets the token on the KV namespace
+            token = await getOauth2AccessTokenHandler(this.serviceAccountKey, 3000, this.kvNamespace);
+        }
+        this.oauth2Token = token;
+        return token;
+    }
+}

package/dist/google-auth/get-oauth-2-token.d.ts

@@ -0,0 +1,15 @@
+import type { ServiceAccountKey } from "../types.js";
+/**
+ * Gets an OAuth2 access token from Google's OAuth2 server. This token is
+ * required for accessing the Firebase Auth REST API via fetch requests.
+ *
+ * The token is stored in the KV namespace for the amount of time which is
+ * shorter:
+ *
+ * - The provided expiration time
+ * - The expiration time returned from Google's OAuth2 server
+ *
+ * @returns The OAuth2 access token
+ */
+export declare function getOauth2AccessTokenHandler(serviceAccountKey: ServiceAccountKey, expiration?: number, // 50 minutes
+kvNamespace?: KVNamespace): Promise<string>;

package/dist/google-auth/get-oauth-2-token.js

@@ -0,0 +1,66 @@
+import { importPKCS8, SignJWT } from "jose";
+/**
+ * Gets an OAuth2 access token from Google's OAuth2 server. This token is
+ * required for accessing the Firebase Auth REST API via fetch requests.
+ *
+ * The token is stored in the KV namespace for the amount of time which is
+ * shorter:
+ *
+ * - The provided expiration time
+ * - The expiration time returned from Google's OAuth2 server
+ *
+ * @returns The OAuth2 access token
+ */
+export async function getOauth2AccessTokenHandler(serviceAccountKey, expiration = 3000, // 50 minutes
+kvNamespace) {
+    const signedJwt = await createSignedJwt(serviceAccountKey, expiration);
+    const response = await fetch("https://oauth2.googleapis.com/token", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: new URLSearchParams({
+            grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+            assertion: signedJwt,
+        }),
+    });
+    const oauth2TokenResponse = (await response.json());
+    const shortestExpiration = Math.min(expiration, oauth2TokenResponse.expires_in);
+    if (kvNamespace) {
+        await kvNamespace.put("oauth2Token", oauth2TokenResponse.access_token, {
+            expirationTtl: shortestExpiration,
+        });
+    }
+    return oauth2TokenResponse.access_token;
+}
+/**
+ * Creates a signed JWT using information from a service account key. The JWT
+ * is sent to Google's OAuth2 server to produce an OAuth2 access token.
+ *
+ * The scope we're using is:
+ * - https://www.googleapis.com/auth/identitytoolkit
+ *
+ * This scope is required for the Firebase Auth REST API.
+ *
+ * The JWT is valid for 50 minutes.
+ *
+ * @returns The signed JWT
+ */
+async function createSignedJwt(serviceAccountKey, expiration) {
+    const header = {
+        alg: "RS256",
+        typ: "JWT",
+        kid: serviceAccountKey.private_key_id,
+    };
+    const now = Math.floor(Date.now() / 1000);
+    const claims = {
+        iss: serviceAccountKey.client_email,
+        scope: "https://www.googleapis.com/auth/identitytoolkit", // The scope we need for the Firebase Auth REST API
+        aud: "https://oauth2.googleapis.com/token",
+        exp: now + expiration,
+        iat: now,
+    };
+    const signingKey = await importPKCS8(serviceAccountKey.private_key, "RS256");
+    const jwt = new SignJWT(claims).setProtectedHeader(header).sign(signingKey);
+    return jwt;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { CloudFireAuth } from "./CloudFireAuth.js";
+export * from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { CloudFireAuth } from "./CloudFireAuth.js";
+export * from "./types.js";

package/dist/rest-api/create-user.d.ts

@@ -0,0 +1,2 @@
+import type { CreateRequest, UserRecord } from "../types.js";
+export declare function createUserHandler(properties: CreateRequest): Promise<UserRecord>;

package/dist/rest-api/create-user.js

@@ -0,0 +1,3 @@
+export async function createUserHandler(properties) {
+    throw new Error("Not implemented");
+}

package/dist/rest-api/delete-user.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Deletes an existing Firebase Auth user permanently from the system.
+ *
+ * This function completely removes a user account and all associated data from Firebase Auth.
+ * Once deleted, the user cannot be recovered and will need to create a new account if they
+ * wish to access the system again. This operation is permanent and irreversible.
+ *
+ * **Important Implementation Details:**
+ * - Permanently deletes the user account from Firebase Auth
+ * - All user data including profile information, custom claims, and metadata is removed
+ * - Linked provider accounts are unlinked and removed
+ * - Multi-factor authentication settings are deleted
+ * - The operation is idempotent - deleting a non-existent user succeeds silently
+ * - Uses Firebase Admin API's `accounts:delete` endpoint
+ *
+ * **Security Considerations:**
+ * - This operation cannot be undone - user data is permanently lost
+ * - Should be used with extreme caution in production environments
+ * - Consider disabling users instead of deleting for audit and recovery purposes
+ * - Requires proper authorization and access control in production systems
+ * - May affect user sessions and active tokens immediately
+ *
+ * **Use Cases:**
+ * - User account closure requests (GDPR compliance)
+ * - Administrative account management
+ * - Cleanup of test or demo accounts
+ * - System maintenance and data purging
+ * - User request for account deletion
+ *
+ * **Behavioral Notes:**
+ * - **Idempotent Operation**: Deleting a non-existent user does not throw an error
+ * - **Immediate Effect**: User cannot authenticate immediately after deletion
+ * - **Related Data**: Only Firebase Auth data is deleted - external data must be handled separately
+ * - **Audit Trail**: Consider logging deletion events for compliance and debugging
+ * - **Batch Operations**: For bulk deletions, consider using deleteUsersHandler instead
+ *
+ * @param uid - The Firebase Auth user ID (localId) of the user to delete.
+ *              Must be a valid Firebase user identifier string.
+ * @param oauth2AccessToken - Valid OAuth2 access token with Firebase Admin API privileges.
+ *                           Obtained via service account authentication.
+ *
+ * @returns Promise that resolves when the deletion is complete.
+ *          No return value - success is indicated by promise resolution.
+ *          The promise resolves successfully even if the user doesn't exist.
+ *
+ * @throws {Error} When deletion fails due to system errors:
+ *   - **Validation Errors**:
+ *     - "uid must be a non-empty string" - Invalid or missing uid parameter
+ *     - "oauth2AccessToken must be a non-empty string" - Invalid or missing token parameter
+ *   - **Firebase API Errors**:
+ *     - "Failed to delete user: {status} {statusText} - {details}" - API errors with detailed information
+ *     - "INVALID_ID_TOKEN" - OAuth2 token is invalid or expired
+ *     - "PERMISSION_DENIED" - Insufficient permissions to delete users
+ *   - **Network Errors**: Various network-related failures during API communication
+ *
+ * @example
+ * ```typescript
+ * // Delete a user account (basic usage)
+ * try {
+ *   await deleteUserHandler('user123', oauth2Token);
+ *   console.log('User account deleted successfully');
+ * } catch (error) {
+ *   console.error('Failed to delete user:', error.message);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // User-initiated account deletion with confirmation
+ * async function handleAccountDeletion(userId: string) {
+ *   try {
+ *     // 1. Verify user identity and intent
+ *     const user = await getUserHandler(userId, oauth2Token);
+ *     console.log(`Deleting account for: ${user.email}`);
+ *
+ *     // 2. Perform additional cleanup (external data, files, etc.)
+ *     await cleanupUserData(userId);
+ *
+ *     // 3. Delete the Firebase Auth account
+ *     await deleteUserHandler(userId, oauth2Token);
+ *
+ *     console.log('Account deletion completed');
+ *   } catch (error) {
+ *     console.error('Account deletion failed:', error.message);
+ *     throw error;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Administrative cleanup with error handling
+ * async function adminDeleteInactiveUsers(userIds: string[]) {
+ *   const results = [];
+ *
+ *   for (const userId of userIds) {
+ *     try {
+ *       await deleteUserHandler(userId, oauth2Token);
+ *       results.push({ userId, status: 'deleted', error: null });
+ *     } catch (error) {
+ *       results.push({ userId, status: 'failed', error: error.message });
+ *     }
+ *   }
+ *
+ *   return results;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // GDPR compliance workflow
+ * async function processGDPRDeletionRequest(userEmail: string) {
+ *   try {
+ *     // 1. Find the user by email
+ *     const user = await getUserByEmailHandler(userEmail, oauth2Token);
+ *
+ *     // 2. Export user data for compliance (if required)
+ *     const userData = await exportUserData(user.uid);
+ *     await saveDataExport(userData, `${userEmail}-export.json`);
+ *
+ *     // 3. Delete associated external data
+ *     await deleteUserFromDatabase(user.uid);
+ *     await deleteUserFiles(user.uid);
+ *
+ *     // 4. Delete the Firebase Auth account
+ *     await deleteUserHandler(user.uid, oauth2Token);
+ *
+ *     // 5. Log the deletion for audit purposes
+ *     await logGDPRDeletion({
+ *       userEmail,
+ *       userId: user.uid,
+ *       deletedAt: new Date(),
+ *       reason: 'GDPR_REQUEST'
+ *     });
+ *
+ *     console.log(`GDPR deletion completed for ${userEmail}`);
+ *   } catch (error) {
+ *     console.error(`GDPR deletion failed for ${userEmail}:`, error);
+ *     throw error;
+ *   }
+ * }
+ * ```
+ *
+ * **Technical Implementation:**
+ * - Makes POST request to `https://identitytoolkit.googleapis.com/v1/accounts:delete`
+ * - Sends `localId` parameter to identify the target user
+ * - Handles Firebase API error responses with detailed error information
+ * - Validates input parameters before making API calls
+ * - Operates idempotently - no error for non-existent users
+ *
+ * **Testing Considerations:**
+ * - Create test users specifically for deletion tests
+ * - Verify user is actually deleted by attempting to retrieve them
+ * - Test idempotent behavior by deleting non-existent users
+ * - Unit tests should mock the fetch call and verify request format
+ * - Integration tests should verify actual deletion from Firebase
+ *
+ * **Production Considerations:**
+ * - **Logging**: Log all deletion operations for audit trails
+ * - **Confirmation**: Implement confirmation flows for critical deletions
+ * - **Backup**: Consider backing up user data before deletion
+ * - **Related Data**: Ensure external data is properly cleaned up
+ * - **Rate Limits**: Be aware of Firebase API rate limits for bulk operations
+ * - **Alternative**: Consider using `disabled: true` instead of deletion for recoverable scenarios
+ *
+ * @see {@link getUserHandler} For retrieving user data before deletion
+ * @see {@link updateUserHandler} For disabling users instead of deletion
+ * @see {@link deleteUsersHandler} For bulk deletion operations
+ * @see {@link https://firebase.google.com/docs/auth/admin/manage-users#delete_a_user Firebase User Deletion}
+ * @see {@link https://firebase.google.com/docs/reference/rest/auth#section-delete-account Firebase REST API}
+ *
+ * @package
+ * @since 1.0.0
+ */
+export declare function deleteUserHandler(uid: string, oauth2AccessToken: string): Promise<void>;