cloudfire-auth 0.1.0

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

@@ -0,0 +1,207 @@
+/**
+ * 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 async function deleteUserHandler(uid, oauth2AccessToken) {
+    // Validate input parameters
+    if (typeof uid !== "string" || uid.length === 0) {
+        throw new Error("uid must be a non-empty string");
+    }
+    if (typeof oauth2AccessToken !== "string" || oauth2AccessToken.length === 0) {
+        throw new Error("oauth2AccessToken must be a non-empty string");
+    }
+    // Make the API call to delete the user
+    const response = await fetch("https://identitytoolkit.googleapis.com/v1/accounts:delete", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${oauth2AccessToken}`,
+        },
+        body: JSON.stringify({
+            localId: uid,
+        }),
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        let errorMessage;
+        try {
+            const errorData = JSON.parse(errorText);
+            const formattedErrorText = JSON.stringify(errorData, null, 2);
+            errorMessage = `Failed to delete user: ${response.status} ${response.statusText}\n${formattedErrorText}`;
+        }
+        catch {
+            errorMessage = `Failed to delete user: ${response.status} ${response.statusText} - ${errorText}`;
+        }
+        throw new Error(errorMessage);
+    }
+}

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

@@ -0,0 +1,2 @@
+import type { DeleteUsersResult } from "../types.js";
+export declare function deleteUsersHandler(uids: string[]): Promise<DeleteUsersResult>;

package/dist/rest-api/delete-users.js

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

package/dist/rest-api/get-user-by-email.d.ts

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

package/dist/rest-api/get-user-by-email.js

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

package/dist/rest-api/get-user-by-phone-number.d.ts

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

package/dist/rest-api/get-user-by-phone-number.js

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

package/dist/rest-api/get-user-by-provider-uid.d.ts

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

package/dist/rest-api/get-user-by-provider-uid.js

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

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

@@ -0,0 +1,99 @@
+import type { UserRecord } from "../types.js";
+/**
+ * Retrieves a Firebase Auth user by their unique identifier (UID).
+ *
+ * This function provides comprehensive user data retrieval by making a direct call
+ * to the Firebase Admin API's accounts:lookup endpoint. It transforms the Firebase
+ * response into a standardized UserRecord format that matches the Firebase Admin SDK.
+ *
+ * **Retrieved User Information:**
+ * - **Basic Profile**: uid, email, emailVerified, displayName, photoURL, phoneNumber
+ * - **Account Status**: disabled status, creation and last sign-in timestamps
+ * - **Provider Data**: All linked authentication providers with their details
+ * - **Custom Claims**: Parsed from customAttributes if present
+ * - **Metadata**: Creation time, last sign-in time, last refresh time
+ *
+ * **Firebase API Integration:**
+ * - Uses Firebase Admin API's `accounts:lookup` endpoint
+ * - Requires valid OAuth2 access token with admin privileges
+ * - Handles Firebase response format `{ users: [GetAccountInfoUserResponse] }`
+ * - Safely processes optional fields with proper null handling
+ * - Transforms provider information to match Admin SDK format
+ *
+ * @param uid - The Firebase Auth user ID (localId) to retrieve.
+ *              Must be a valid, existing Firebase user identifier.
+ * @param oauth2AccessToken - Valid OAuth2 access token with Firebase Admin API privileges.
+ *                           Obtained via service account authentication.
+ *
+ * @returns Promise that resolves to the UserRecord containing complete user information.
+ *
+ * @throws {Error} When user lookup fails or user doesn't exist:
+ *   - "Failed to get user: {status} {statusText}, {details}" - Firebase API errors with HTTP details
+ *   - "User not found: {uid}" - No user exists with the specified UID
+ *   - Network errors during Firebase API communication
+ *   - JSON parsing errors from malformed Firebase responses
+ *
+ * @example
+ * ```typescript
+ * // Basic user retrieval
+ * const user = await getUserHandler('user123', oauth2Token);
+ * console.log(`User: ${user.displayName} (${user.email})`);
+ * console.log(`Created: ${user.metadata.creationTime}`);
+ * console.log(`Verified: ${user.emailVerified}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check user status and providers
+ * const user = await getUserHandler('user456', oauth2Token);
+ *
+ * if (user.disabled) {
+ *   console.log('Account is disabled');
+ * }
+ *
+ * // List all authentication providers
+ * user.providerData.forEach(provider => {
+ *   console.log(`Provider: ${provider.providerId} - ${provider.email}`);
+ * });
+ *
+ * // Access custom claims if available
+ * const customClaims = user.customClaims;
+ * if (customClaims?.role) {
+ *   console.log(`User role: ${customClaims.role}`);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error handling with detailed information
+ * try {
+ *   const user = await getUserHandler(userId, oauth2Token);
+ *   console.log('User retrieved successfully:', user.uid);
+ * } catch (error) {
+ *   if (error.message.includes('User not found')) {
+ *     console.error('User does not exist:', userId);
+ *   } else if (error.message.includes('Failed to get user')) {
+ *     console.error('Firebase API error:', error.message);
+ *   } else {
+ *     console.error('Unexpected error:', error);
+ *   }
+ * }
+ * ```
+ *
+ * **Important Notes:**
+ * - Returns complete user profile including sensitive information (use appropriate access controls)
+ * - Custom claims are automatically parsed from Firebase's customAttributes field
+ * - Provider data includes all linked authentication methods (Google, Facebook, etc.)
+ * - Metadata timestamps are in ISO 8601 format or empty strings if not available
+ * - Phone numbers are returned in the format stored in Firebase (may not be E.164)
+ * - Disabled users can still be retrieved but cannot authenticate
+ * - This function requires Firebase Admin privileges - ensure proper token scoping
+ *
+ * @see {@link https://firebase.google.com/docs/auth/admin/manage-users Firebase User Management}
+ * @see {@link https://firebase.google.com/docs/reference/rest/auth#section-get-account-info Firebase REST API}
+ * @see {@link UserRecord} For complete UserRecord interface documentation
+ *
+ * @package
+ * @since 1.0.0
+ */
+export declare function getUserHandler(uid: string, oauth2AccessToken: string): Promise<UserRecord>;

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

@@ -0,0 +1,177 @@
+/**
+ * Retrieves a Firebase Auth user by their unique identifier (UID).
+ *
+ * This function provides comprehensive user data retrieval by making a direct call
+ * to the Firebase Admin API's accounts:lookup endpoint. It transforms the Firebase
+ * response into a standardized UserRecord format that matches the Firebase Admin SDK.
+ *
+ * **Retrieved User Information:**
+ * - **Basic Profile**: uid, email, emailVerified, displayName, photoURL, phoneNumber
+ * - **Account Status**: disabled status, creation and last sign-in timestamps
+ * - **Provider Data**: All linked authentication providers with their details
+ * - **Custom Claims**: Parsed from customAttributes if present
+ * - **Metadata**: Creation time, last sign-in time, last refresh time
+ *
+ * **Firebase API Integration:**
+ * - Uses Firebase Admin API's `accounts:lookup` endpoint
+ * - Requires valid OAuth2 access token with admin privileges
+ * - Handles Firebase response format `{ users: [GetAccountInfoUserResponse] }`
+ * - Safely processes optional fields with proper null handling
+ * - Transforms provider information to match Admin SDK format
+ *
+ * @param uid - The Firebase Auth user ID (localId) to retrieve.
+ *              Must be a valid, existing Firebase user identifier.
+ * @param oauth2AccessToken - Valid OAuth2 access token with Firebase Admin API privileges.
+ *                           Obtained via service account authentication.
+ *
+ * @returns Promise that resolves to the UserRecord containing complete user information.
+ *
+ * @throws {Error} When user lookup fails or user doesn't exist:
+ *   - "Failed to get user: {status} {statusText}, {details}" - Firebase API errors with HTTP details
+ *   - "User not found: {uid}" - No user exists with the specified UID
+ *   - Network errors during Firebase API communication
+ *   - JSON parsing errors from malformed Firebase responses
+ *
+ * @example
+ * ```typescript
+ * // Basic user retrieval
+ * const user = await getUserHandler('user123', oauth2Token);
+ * console.log(`User: ${user.displayName} (${user.email})`);
+ * console.log(`Created: ${user.metadata.creationTime}`);
+ * console.log(`Verified: ${user.emailVerified}`);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Check user status and providers
+ * const user = await getUserHandler('user456', oauth2Token);
+ *
+ * if (user.disabled) {
+ *   console.log('Account is disabled');
+ * }
+ *
+ * // List all authentication providers
+ * user.providerData.forEach(provider => {
+ *   console.log(`Provider: ${provider.providerId} - ${provider.email}`);
+ * });
+ *
+ * // Access custom claims if available
+ * const customClaims = user.customClaims;
+ * if (customClaims?.role) {
+ *   console.log(`User role: ${customClaims.role}`);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Error handling with detailed information
+ * try {
+ *   const user = await getUserHandler(userId, oauth2Token);
+ *   console.log('User retrieved successfully:', user.uid);
+ * } catch (error) {
+ *   if (error.message.includes('User not found')) {
+ *     console.error('User does not exist:', userId);
+ *   } else if (error.message.includes('Failed to get user')) {
+ *     console.error('Firebase API error:', error.message);
+ *   } else {
+ *     console.error('Unexpected error:', error);
+ *   }
+ * }
+ * ```
+ *
+ * **Important Notes:**
+ * - Returns complete user profile including sensitive information (use appropriate access controls)
+ * - Custom claims are automatically parsed from Firebase's customAttributes field
+ * - Provider data includes all linked authentication methods (Google, Facebook, etc.)
+ * - Metadata timestamps are in ISO 8601 format or empty strings if not available
+ * - Phone numbers are returned in the format stored in Firebase (may not be E.164)
+ * - Disabled users can still be retrieved but cannot authenticate
+ * - This function requires Firebase Admin privileges - ensure proper token scoping
+ *
+ * @see {@link https://firebase.google.com/docs/auth/admin/manage-users Firebase User Management}
+ * @see {@link https://firebase.google.com/docs/reference/rest/auth#section-get-account-info Firebase REST API}
+ * @see {@link UserRecord} For complete UserRecord interface documentation
+ *
+ * @package
+ * @since 1.0.0
+ */
+export async function getUserHandler(uid, oauth2AccessToken) {
+    const response = await fetch("https://identitytoolkit.googleapis.com/v1/accounts:lookup", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${oauth2AccessToken}`,
+        },
+        body: JSON.stringify({
+            localId: [uid],
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to get user: ${response.status} ${response.statusText}, ${await response.text()}`);
+    }
+    const data = (await response.json());
+    let userData;
+    try {
+        userData = data.users[0];
+    }
+    catch (error) {
+        console.error("Error parsing user data:", error);
+        throw new Error(`User not found: ${uid}`);
+    }
+    if (!userData) {
+        throw new Error(`User not found: ${uid}`);
+    }
+    const userRecord = convertToUserRecord(userData);
+    return userRecord;
+}
+/**
+ * Converts Firebase's GetAccountInfoUserResponse to a UserRecord to match
+ * the Firebase Admin SDK format.
+ *
+ * This function safely handles optional fields and transforms the Firebase API
+ * response structure into a standardized UserRecord. It includes proper null
+ * handling, custom claims parsing, and provider data transformation.
+ *
+ * @param userData - The raw user data from Firebase Admin API.
+ * @returns The converted UserRecord with all available user information.
+ * @internal
+ */
+function convertToUserRecord(userData) {
+    // Safely map provider user info, handling optional fields properly
+    const userInfo = userData.providerUserInfo?.map((providerUserInfo) => ({
+        uid: providerUserInfo.rawId || providerUserInfo.federatedId || "",
+        displayName: providerUserInfo.displayName || null,
+        email: providerUserInfo.email || null,
+        photoURL: providerUserInfo.photoUrl || null,
+        providerId: providerUserInfo.providerId,
+        phoneNumber: providerUserInfo.phoneNumber || null,
+    })) || [];
+    // Parse custom claims from customAttributes JSON string
+    let customClaims = null;
+    if (userData.customAttributes) {
+        try {
+            customClaims = JSON.parse(userData.customAttributes);
+        }
+        catch (error) {
+            // Invalid JSON in customAttributes, leave as null
+            console.warn("Failed to parse custom attributes as JSON:", error);
+        }
+    }
+    const userRecord = {
+        uid: userData.localId,
+        email: userData.email || null,
+        emailVerified: userData.emailVerified || false,
+        displayName: userData.displayName || null,
+        photoURL: userData.photoUrl || null,
+        phoneNumber: userData.phoneNumber || null,
+        disabled: userData.disabled || false,
+        providerData: userInfo,
+        customClaims: customClaims,
+        metadata: {
+            creationTime: userData.createdAt || "",
+            lastSignInTime: userData.lastLoginAt || "",
+            lastRefreshTime: userData.lastRefreshAt || null,
+        },
+    };
+    return userRecord;
+}

package/dist/rest-api/get-users.d.ts

@@ -0,0 +1,2 @@
+import type { UserIdentifier, GetUsersResult } from "../types.js";
+export declare function getUsersHandler(identifiers: UserIdentifier[]): Promise<GetUsersResult>;

package/dist/rest-api/get-users.js

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

package/dist/rest-api/list-users.d.ts

@@ -0,0 +1,2 @@
+import type { ListUsersResult } from "../types.js";
+export declare function listUsersHandler(maxResults?: number, pageToken?: string): Promise<ListUsersResult>;

package/dist/rest-api/list-users.js

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

package/dist/rest-api/revoke-refresh-tokens.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Revokes all refresh tokens for an existing Firebase Auth user.
+ *
+ * This function updates the user's `tokensValidAfterTime` to the current UTC timestamp,
+ * effectively invalidating all existing refresh tokens and sessions for the specified user.
+ * After calling this function, the user will need to re-authenticate to obtain new tokens.
+ *
+ * **Important Implementation Details:**
+ * - Updates the user's `tokensValidAfterTime` to the current UTC timestamp (in seconds)
+ * - All existing refresh tokens become invalid immediately
+ * - Existing ID tokens remain valid until their natural expiration (1 hour) unless verified with `checkRevoked=true`
+ * - Requires accurate server time synchronization for proper functionality
+ * - Uses Firebase Admin API's `accounts:update` endpoint with `validSince` parameter
+ *
+ * **Security Considerations:**
+ * - Forces user re-authentication on all devices and sessions
+ * - Useful for compromised accounts or mandatory sign-out scenarios
+ * - Should be combined with ID token verification using `checkRevoked=true` for immediate effect
+ * - Does not affect the user's account data or profile information
+ *
+ * **Use Cases:**
+ * - Security incident response (compromised accounts)
+ * - Forced logout from all devices
+ * - Administrative account suspension workflows
+ * - Password change security measures
+ * - Device management and session control
+ *
+ * @param uid - The Firebase Auth user ID (localId) whose refresh tokens should be revoked.
+ *              Must be a valid, existing Firebase user identifier.
+ * @param oauth2AccessToken - Valid OAuth2 access token with Firebase Admin API privileges.
+ *                           Obtained via service account authentication.
+ *
+ * @returns Promise that resolves when the revocation is complete.
+ *          No return value - success is indicated by promise resolution.
+ *
+ * @throws {Error} When revocation fails:
+ *   - **Validation Errors**:
+ *     - "uid must be a non-empty string" - Invalid or missing uid parameter
+ *   - **Firebase API Errors**:
+ *     - "Failed to revoke refresh tokens: {status} {statusText} - {details}" - API errors with detailed information
+ *     - "USER_NOT_FOUND" - Specified user does not exist
+ *     - "INVALID_ID_TOKEN" - OAuth2 token is invalid or expired
+ *   - **Network Errors**: Various network-related failures during API communication
+ *
+ * @example
+ * ```typescript
+ * // Revoke all refresh tokens for a user (security incident)
+ * try {
+ *   await revokeRefreshTokensHandler('user123', oauth2Token);
+ *   console.log('All refresh tokens revoked successfully');
+ *
+ *   // Verify that existing ID tokens are now invalid
+ *   await verifyIdTokenHandler(existingIdToken, projectId, oauth2Token, kvNamespace, true);
+ * } catch (error) {
+ *   if (error.message.includes('id-token-revoked')) {
+ *     console.log('Tokens successfully revoked - existing ID token is invalid');
+ *   } else {
+ *     console.error('Failed to revoke tokens:', error);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Force logout from all devices after password change
+ * try {
+ *   // First update the password
+ *   await updateUserHandler('user456', { password: 'newSecurePassword' }, oauth2Token);
+ *
+ *   // Then revoke all existing sessions for security
+ *   await revokeRefreshTokensHandler('user456', oauth2Token);
+ *
+ *   console.log('Password updated and all sessions revoked');
+ * } catch (error) {
+ *   console.error('Security update failed:', error);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Administrative account suspension workflow
+ * try {
+ *   // Disable the account
+ *   await updateUserHandler('suspendedUser', { disabled: true }, oauth2Token);
+ *
+ *   // Revoke all active sessions
+ *   await revokeRefreshTokensHandler('suspendedUser', oauth2Token);
+ *
+ *   console.log('Account suspended and all sessions terminated');
+ * } catch (error) {
+ *   console.error('Account suspension failed:', error);
+ * }
+ * ```
+ *
+ * **Technical Implementation:**
+ * - Makes POST request to `https://identitytoolkit.googleapis.com/v1/accounts:update`
+ * - Sets `validSince` to current timestamp: `Math.floor(Date.now() / 1000)`
+ * - Uses `localId` parameter to identify the target user
+ * - Handles Firebase API error responses with detailed error information
+ * - Validates input parameters before making API calls
+ *
+ * **Testing Considerations:**
+ * - Can be verified by attempting to verify existing ID tokens with `checkRevoked=true`
+ * - Integration tests should create tokens, revoke them, then verify revocation
+ * - Unit tests should mock the fetch call and verify request format
+ * - Error scenarios should test various Firebase API error responses
+ *
+ * @see {@link verifyIdTokenHandler} For verifying ID tokens with revocation checking
+ * @see {@link updateUserHandler} For other user management operations
+ * @see {@link https://firebase.google.com/docs/auth/admin/manage-sessions#revoke_refresh_tokens Firebase Session Management}
+ * @see {@link https://firebase.google.com/docs/reference/rest/auth#section-update-account Firebase REST API}
+ *
+ * @package
+ * @since 1.0.0
+ */
+export declare function revokeRefreshTokensHandler(uid: string, oauth2AccessToken: string): Promise<void>;