`
})
export class AppComponent {
token$ = this.storage.getItem('accessToken');
constructor(private storage: SecureStorageService) {}
saveToken(token: string) {
this.storage.setItem('accessToken', token).subscribe();
}
}
```
## Angular Integration
```typescript
import { SecureStorageService } from '@bantis/local-cipher';
@Component({...})
export class AppComponent {
token$ = this.storage.getItem('token');
constructor(private storage: SecureStorageService) {
this.storage.events$.subscribe(event => {
console.log('Storage event:', event);
});
}
}
```
## Configuration
```typescript
const storage = SecureStorage.getInstance({
encryption: {
iterations: 150000, // PBKDF2 iterations
keyLength: 256, // 128, 192, or 256 bits
saltLength: 16, // Salt size in bytes
ivLength: 12, // IV size in bytes
},
storage: {
compression: true, // Enable gzip compression
compressionThreshold: 1024, // Compress if > 1KB
autoCleanup: true, // Auto-delete expired items
cleanupInterval: 60000 // Cleanup every 60s
},
debug: {
enabled: false, // Enable debug logging
logLevel: 'info' // silent, error, warn, info, debug, verbose
}
});
```
## Security
### What This Protects Against
✅ **XSS attacks** - Encrypted data is useless without the browser-specific key
✅ **Local file access** - Malware reading browser files gets encrypted data
✅ **Casual inspection** - DevTools shows encrypted values
✅ **Data tampering** - Integrity checks detect modifications
### What This Does NOT Protect Against
❌ **Server-side attacks** - Encryption is client-side only
❌ **Man-in-the-Middle** - Use HTTPS for data in transit
❌ **Memory dumps** - Keys exist in memory during runtime
❌ **Compromised browser** - If the browser is compromised, all bets are off
❌ **Physical access during active session** - Data is decrypted when accessed
### Best Practices
1. **Use HTTPS** - Always transmit data over secure connections
2. **Short TTLs** - Set expiration on sensitive data
3. **Clear on logout** - Call `storage.clear()` when user logs out
4. **Monitor events** - Track suspicious activity via event listeners
5. **Rotate keys** - Periodically call `storage.rotateKeys()`
6. **Don't store passwords** - Never store plaintext passwords, even encrypted
## Browser Support
Requires [Web Crypto API](https://caniuse.com/cryptography):
- Chrome 37+
- Firefox 34+
- Safari 11+
- Edge 12+
- Opera 24+
**Fallback:** Gracefully degrades to unencrypted localStorage in unsupported browsers.
## API Reference
### Core Methods
```typescript
setItem(key: string, value: string): Promise
getItem(key: string): Promise
removeItem(key: string): Promise
hasItem(key: string): Promise
clear(): void
```
### Expiration
```typescript
setItemWithExpiry(key: string, value: string, options: {
expiresIn?: number; // milliseconds from now
expiresAt?: Date; // absolute date
}): Promise
cleanExpired(): Promise // Returns count of deleted items
```
### Events
```typescript
on(event: StorageEventType, listener: EventListener): void
off(event: StorageEventType, listener: EventListener): void
once(event: StorageEventType, listener: EventListener): void
// Event types: 'encrypted', 'decrypted', 'deleted', 'cleared',
// 'expired', 'error', 'keyRotated', 'compressed'
```
### Namespaces
```typescript
namespace(name: string): NamespacedStorage
const userStorage = storage.namespace('user');
await userStorage.setItem('profile', data);
await userStorage.clearNamespace();
```
### Key Rotation
```typescript
rotateKeys(): Promise
exportEncryptedData(): Promise
importEncryptedData(backup: EncryptedBackup): Promise
```
## FAQ
**Q: Is this secure enough for passwords?**
A: No. Never store passwords in localStorage, even encrypted. Use secure, httpOnly cookies or sessionStorage with server-side session management.
**Q: Can data be decrypted on another device?**
A: No. Keys are derived from browser fingerprinting. Data encrypted on Chrome/Windows cannot be decrypted on Firefox/Mac.
**Q: What happens if Web Crypto API is unavailable?**
A: The library falls back to unencrypted localStorage with a console warning. Check `EncryptionHelper.isSupported()` to detect support.
**Q: Does this protect against XSS?**
A: Partially. It makes stolen data harder to use, but XSS can still intercept data when it's decrypted in memory. Use CSP headers and sanitize inputs.
**Q: How is this different from sessionStorage?**
A: sessionStorage is cleared on tab close. This provides persistent, encrypted storage across sessions.
**Q: Can I use this in Node.js?**
A: No. This library requires browser APIs (Web Crypto, localStorage). For Node.js, use native `crypto` module.
**Q: What's the performance impact?**
A: Encryption adds ~2-5ms per operation. Compression adds ~5-10ms for large values. Negligible for most use cases.
## Migration from v1
v1 data is automatically migrated to v2 format on first read. No action required.
```typescript
// v1 and v2 are API-compatible
const storage = SecureStorage.getInstance(); // Works with both
```
## Migration from v2.0.x to v2.1.0
> [!WARNING]
> **Breaking Change:** Framework-specific imports required
### For React Users
**Before (v2.0.x):**
```typescript
import { useSecureStorage } from '@bantis/local-cipher';
```
**After (v2.1.0):**
```typescript
import { useSecureStorage } from '@bantis/local-cipher/react';
```
### For Angular Users
**Before (v2.0.x):**
```typescript
import { SecureStorageService } from '@bantis/local-cipher';
```
**After (v2.1.0):**
```typescript
import { SecureStorageService } from '@bantis/local-cipher/angular';
```
### For Core/Vanilla JS Users
**No changes required:**
```typescript
import { SecureStorage } from '@bantis/local-cipher'; // Still works
```
### Why This Change?
v2.0.x bundled all framework code together, causing dependency conflicts:
- React projects needed Angular dependencies (`@angular/core`, `rxjs`)
- Vanilla JS projects loaded unused React/Angular code
- 40% larger bundle size for non-framework users
v2.1.0 separates frameworks into independent bundles:
- ✅ Core: 42KB (no framework dependencies)
- ✅ React: 49KB (core + hooks)
- ✅ Angular: 55KB (core + service)
## FAQ
