feat(rotation): add key rotation functionality with automatic re-encryption and event handling

Author: mCodex

README.md

@@ -31,6 +31,7 @@ Modern secure storage for React Native, powered by Nitro Modules. Version 6 ship
 - [⚡️ Quick start](#-quick-start)
 - [📚 API reference](#-api-reference)
 - [🔐 Access control & metadata](#-access-control--metadata)
+- [🔑 Key rotation](#-key-rotation)
 - [❗ Error handling](#-error-handling)
 - [🧪 Simulators and emulators](#-simulators-and-emulators)
 - [📈 Performance benchmarks](#-performance-benchmarks)
@@ -333,7 +334,164 @@ See `src/sensitive-info.nitro.ts` for full TypeScript definitions.
 Use `getSupportedSecurityLevels()` to tailor UX before prompting users. For example, disable Secure Enclave options on simulators.
 
 > [!TIP]
-> Need to demo biometrics on a simulator? Use Xcode’s “Features → Face ID” and Android Studio’s “Fingerprints” toggles to simulate successful scans.
+> Need to demo biometrics on a simulator? Use Xcode's "Features → Face ID" and Android Studio's "Fingerprints" toggles to simulate successful scans.
+
+## 🔑 Key rotation
+
+Automatically rotate encryption keys to maintain security over time, with zero-downtime re-encryption of stored secrets. This feature implements envelope encryption with key versioning, ensuring forward secrecy and compliance with security best practices.
+
+### 🛡️ Security benefits
+
+- **Forward secrecy**: Old keys become useless even if compromised, protecting historical data
+- **Compliance**: Meets security standards requiring regular key rotation (NIST, PCI DSS, etc.)
+- **Post-compromise security**: Limits damage from key exposure by automatically cycling keys
+- **Hardware-backed**: Uses Secure Enclave (iOS) and Keystore/StrongBox (Android) for key protection
+
+### ⚡ Advantages
+
+- **Zero downtime**: Re-encryption happens automatically in the background
+- **Event-driven**: Real-time notifications for rotation lifecycle events
+- **Configurable**: Customize rotation intervals, triggers, and behavior
+- **Cross-platform**: Consistent API across iOS and Android
+- **Performance optimized**: Batched operations with progress tracking
+
+### 🚀 Quick setup
+
+```tsx
+import {
+  initializeKeyRotation,
+  rotateKeys,
+  getRotationStatus,
+  onRotationEvent
+} from 'react-native-sensitive-info'
+
+// Initialize automatic rotation (30 days, biometric triggers)
+await initializeKeyRotation({
+  enabled: true,
+  rotationIntervalMs: 30 * 24 * 60 * 60 * 1000, // 30 days
+  rotateOnBiometricChange: true,
+  backgroundReEncryption: true
+})
+
+// Listen for rotation events
+const unsubscribe = onRotationEvent((event) => {
+  console.log(`${event.type}: ${event.reason}`)
+  if (event.type === 'rotation:completed') {
+    console.log(`Re-encrypted ${event.itemsReEncrypted} items`)
+  }
+})
+
+// Manual rotation
+const result = await rotateKeys({
+  reason: 'User requested rotation'
+})
+console.log(`Rotated to key: ${result.newKeyVersion.id}`)
+
+// Check status
+const status = await getRotationStatus()
+console.log(`Current key: ${status.currentKeyVersion?.id}`)
+```
+
+### 📋 API reference
+
+| Method | Description |
+| --- | --- |
+| `initializeKeyRotation(options)` | Configure automatic key rotation settings |
+| `rotateKeys(options)` | Manually trigger key rotation |
+| `getRotationStatus()` | Get current rotation state and key information |
+| `onRotationEvent(callback)` | Subscribe to rotation lifecycle events |
+| `reEncryptAllItems(options)` | Re-encrypt all items with current key |
+
+### ⚙️ Configuration options
+
+```tsx
+interface InitializeKeyRotationRequest {
+  enabled?: boolean                    // Enable/disable automatic rotation
+  rotationIntervalMs?: number          // Time between rotations (default: 30 days)
+  rotateOnBiometricChange?: boolean    // Trigger on biometric enrollment changes
+  rotateOnCredentialChange?: boolean   // Trigger on device credential changes
+  manualRotationEnabled?: boolean      // Allow manual rotation triggers
+  maxKeyVersions?: number              // Maximum key versions to keep
+  backgroundReEncryption?: boolean     // Re-encrypt during rotation
+}
+```
+
+### 🎯 Event types
+
+Subscribe to rotation events for real-time feedback:
+
+```tsx
+onRotationEvent((event) => {
+  switch (event.type) {
+    case 'rotation:started':
+      console.log(`🔄 Rotation started: ${event.reason}`)
+      break
+    case 'rotation:completed':
+      console.log(`✅ Completed: ${event.itemsReEncrypted} items in ${event.duration}ms`)
+      break
+    case 'rotation:failed':
+      console.log(`❌ Failed: ${event.reason}`)
+      break
+  }
+})
+```
+
+### 🔧 Advanced usage
+
+> [!TIP]
+> Use the example app's Key Rotation panel to explore all features interactively.
+
+#### Custom rotation intervals
+
+```tsx
+// Rotate every 7 days
+await initializeKeyRotation({
+  rotationIntervalMs: 7 * 24 * 60 * 60 * 1000,
+  enabled: true
+})
+```
+
+#### Biometric change detection
+
+```tsx
+// Auto-rotate when fingerprints/face change
+await initializeKeyRotation({
+  rotateOnBiometricChange: true,
+  rotateOnCredentialChange: true
+})
+```
+
+#### Manual bulk re-encryption
+
+```tsx
+// Re-encrypt all items without rotating keys
+const result = await reEncryptAllItems({
+  service: 'myapp',
+  batchSize: 50
+})
+console.log(`Re-encrypted ${result.itemsReEncrypted} items`)
+```
+
+### ⚠️ Important considerations
+
+> [!WARNING]
+> Key rotation is irreversible. Ensure you have backups before enabling automatic rotation in production.
+
+> [!IMPORTANT]
+> Background re-encryption may consume battery and data. Monitor performance on resource-constrained devices.
+
+> [!NOTE]
+> Rotation events are delivered asynchronously. UI updates should be handled in event callbacks.
+
+### 🔍 Troubleshooting
+
+- **Rotation not triggering**: Check that `enabled: true` and verify device time settings
+- **Re-encryption failures**: Some items may fail if keys are invalidated; check error details
+- **Performance issues**: Reduce `rotationIntervalMs` or disable `backgroundReEncryption` on low-end devices
+- **Event not firing**: Ensure the event listener is set up before rotation starts
+
+> [!TIP]
+> The example app includes comprehensive logging and error handling for all rotation operations.
 
 ## 🧪 Simulators and emulators