http-request-manager 18.15.33 → 18.15.34

package/src/docs/ENCRYPTION_README.md

@@ -0,0 +1,403 @@
+# Encryption Utilities
+
+The HTTP Request Manager library provides comprehensive encryption utilities for securing sensitive data, including both symmetric (AES) and asymmetric (RSA) encryption.
+
+## Overview
+
+**Features:**
+- 🔐 **AES Symmetric Encryption** - Fast encryption for data at rest
+- 🔑 **RSA Asymmetric Encryption** - Secure key exchange and digital signatures
+- 🎲 **Random Generation** - Cryptographically secure random values
+- 📝 **Key Pair Generation** - Generate RSA key pairs
+- 🔒 **Secure Storage** - Integration with LocalStorage for encrypted persistence
+
+## Installation
+
+Encryption utilities are automatically available when you import `HttpRequestManagerModule`.
+
+```typescript
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [HttpRequestManagerModule.forRoot({
+    LocalStorageOptions: {
+      storageName: 'my-app-data',
+      options: {
+        encrypted: true  // Enable encryption
+      }
+    }
+  })]
+})
+export class AppModule { }
+```
+
+### Provide APP_ID
+
+For encryption to work, you must provide a unique APP_ID:
+
+```typescript
+import { APP_ID } from '@angular/core';
+
+@NgModule({
+  providers: [
+    { provide: APP_ID, useValue: "my-unique-app-guid-12345" }
+  ]
+})
+export class AppModule { }
+```
+
+## AES Symmetric Encryption
+
+### SymmetricalEncryptionService
+
+Fast encryption for data storage using AES algorithm.
+
+**Usage:**
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { SymmetricalEncryptionService } from 'http-request-manager';
+
+@Component({
+  selector: 'app-secure-data',
+  template: `
+    <button (click)="encryptData()">Encrypt Data</button>
+    <button (click)="decryptData()">Decrypt Data</button>
+    <div>Encrypted: {{ encryptedData }}</div>
+    <div>Decrypted: {{ decryptedData }}</div>
+  `
+})
+export class SecureDataComponent {
+  private encryption = inject(SymmetricalEncryptionService);
+  
+  encryptedData: string = '';
+  decryptedData: string = '';
+  originalData: any = { secret: 'sensitive-info', userId: 123 };
+
+  encryptData() {
+    this.encryptedData = this.encryption.encrypt(
+      JSON.stringify(this.originalData)
+    );
+    console.log('Encrypted:', this.encryptedData);
+  }
+
+  decryptData() {
+    const decrypted = this.encryption.decrypt(this.encryptedData);
+    this.decryptedData = JSON.parse(decrypted);
+    console.log('Decrypted:', this.decryptedData);
+  }
+}
+```
+
+**Methods:**
+
+```typescript
+encrypt(data: string): string
+decrypt(encryptedData: string): string
+generateKey(): string
+```
+
+## RSA Asymmetric Encryption
+
+### AsymmetricalEncryptionService
+
+Secure encryption using public/private key pairs for enhanced security.
+
+**Usage:**
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { AsymmetricalEncryptionService } from 'http-request-manager';
+
+@Component({
+  selector: 'app-rsa-encryption',
+  template: `
+    <button (click)="generateKeys()">Generate Key Pair</button>
+    <button (click)="encryptWithPublicKey()">Encrypt</button>
+    <button (click)="decryptWithPrivateKey()">Decrypt</button>
+    
+    <div *ngIf="publicKey">
+      <h3>Public Key</h3>
+      <pre>{{ publicKey }}</pre>
+    </div>
+    
+    <div *ngIf="privateKey">
+      <h3>Private Key</h3>
+      <pre>{{ privateKey }}</pre>
+    </div>
+  `
+})
+export class RsaEncryptionComponent {
+  private encryption = inject(AsymmetricalEncryptionService);
+  
+  publicKey: string = '';
+  privateKey: string = '';
+  encryptedData: string = '';
+  decryptedData: string = '';
+
+  generateKeys() {
+    const keyPair = this.encryption.generateKeyPair();
+    this.publicKey = keyPair.publicKey;
+    this.privateKey = keyPair.privateKey;
+  }
+
+  encryptWithPublicKey() {
+    const data = 'Sensitive information';
+    this.encryptedData = this.encryption.encryptWithPublicKey(
+      data,
+      this.publicKey
+    );
+  }
+
+  decryptWithPrivateKey() {
+    this.decryptedData = this.encryption.decryptWithPrivateKey(
+      this.encryptedData,
+      this.privateKey
+    );
+  }
+}
+```
+
+**Methods:**
+
+```typescript
+generateKeyPair(): { publicKey: string, privateKey: string }
+encryptWithPublicKey(data: string, publicKey: string): string
+decryptWithPrivateKey(encryptedData: string, privateKey: string): string
+sign(data: string, privateKey: string): string
+verify(signature: string, data: string, publicKey: string): boolean
+```
+
+## Key Pair Generation
+
+### Generate RSA Keys on Mac
+
+Use the built-in openssl command-line tool:
+
+#### Step 1: Generate Private Key
+
+```bash
+openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048
+```
+
+#### Step 2: Extract Public Key
+
+```bash
+openssl rsa -pubout -in private_key.pem -out public_key.pem
+```
+
+#### Step 3: View Keys
+
+```bash
+# View private key
+cat private_key.pem
+
+# View public key
+cat public_key.pem
+```
+
+### Example Key Pair
+
+```
+-----BEGIN PRIVATE KEY-----
+MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQC2mvvEWn/aMikX
+A8+/Po2R4+PHwC9wxa10fr75sR9Wbuq8NY/yY174JHR4rRmyV8EnKEfyoTzfsvTO
+858lPD4DuUKESh+NDKiLNUdY4isrR060rxzJn+30OzKkZIHWhIZY3jqEw7C+glMV
+Fmphtci4WQqPYwi1rX3YswE0MJhF/a+HCZ5erDmET/PFZJtTSsx47zbeck2Mnfta
+KpF/wS9jYtpUFrf/vSuTo4Q0libauiFwPgCeYTGEBGGbKVnbAbM71qqmjOxT0ItW
+TbsrGWG54G6vTxg/mnzxpJfMNlVOogv9u2YcG0lEQ/xo9P88WBWPdE0TK5V37GOq
+3twvUruHAgMBAAECggEAThZZqr6OpQbFRofFO8GqtaQQAJghUWbfRY176ngBcCtP
+azu2ek9fSdsBCafwcLERMscJeWrVBs5W3PcWa8xmsp3zIXI3KtCqdJlMkOhq0H+W
+WzL1Kw2eqs3z2pP2Z/9VGkSyHps2hklh8QccZ/teQeMl3mpZy6NMyTHHRoOvYmIg
+TBhDPL+WWJXPVlgKle3RRDVeD1JVo5XmsOW4I8FRyp5f7BZE1IwPTNDUATAtwC8u
+dHHo1rTkWIk2gxVPRcH61w8ceij4VPv7Sk7iFobcLkscTwbTzondU3YssSYEmayW
+5+qhIbHXWnn4FVMPVrDUORVAW8naCrVVBCYGWFDnQQKBgQDcsQ07EaYWDnRQ0xcq
+5hTQUnd137CKNQcLXJ8T+ghuj5v0ZhPpu3YZDjm+rX52mrFN4+kEMKkCjFJAeKaI
+omqKb/i57t7tcQKsbGdtUyRt7PirnHed7dlEo0ElwBWr58hTcUuTnoIiQM3sgmpn
+VrlntlWpVWr0hoJMxRS6Pb6xQQKBgQDT0gVdNm0+ZrBKDWWKkeaQHHyxdva8Dt6C
+NEjP+uU16hF6CsPGCvDuNA9PMIqGHR914aeEwYWtma6/zI1T74jhlUiyAHkpW373
++xNWmruq8k3UlVBK8JIjH/LOXNV5Gw85yLJwokhl6A8m4DSMkDJZTLVXfYQ24su1
+TMDz0yhyxwKBgA/jNx6fgKNp2vnOmIZgFfOBXFRCDEWG18D7pAAeKek7sXCAwMI8
+2p2nJoURnF8Rd94xoB7LGf+y9mDpzqNbfewFb5SDG81gK18aVr/KEn9PZf+Evh/C
+dbe5QQFkuKqtfwBy0YwJBzlMDQcPxHU4CxTqTXRpT8/Wtx6ruXhG5amBAoGANXmC
+8ypHYAaKoNdK+DWnMGCQtjijR4y1bceHTkI31WmXKelHzVp7wpcP+lz1y6/Ufm0O
+XnyAo/f1XuRkFXmWY+TNKmrmK6O2pSIUmruLfzeWoIFleNXM/uMU6DYVinJjYKIj
+Mj416swv7w+RFJ9epp6v9Ttxwm11IfsThzqarocCgYAPbtk6kqJwxq5I49NoC3Nm
+WozUs31UywHJLS4JeudityA7ZTD8kULyhCig+Mrupiu3qLAmFtJzYFFIoP4msIOC
+xMQ2qHvUyX9BwpONDwZ6fjwQYa8/kt22MelVICKqDpyYlOipV/YRKMNXsaQJd6xB
+pkaCFGUW4xoRwTR/So/RnQ==
+-----END PRIVATE KEY-----
+```
+
+## Random Generation
+
+### Random Utility
+
+Generate cryptographically secure random values.
+
+```typescript
+import { Random } from 'http-request-manager';
+
+// Generate random string
+const randomString = Random.generate(16); // 16 characters
+
+// Generate random number
+const randomNumber = Random.number(1, 100); // Between 1 and 100
+
+// Generate random color
+const randomColor = Random.color(); // '#a3f129'
+```
+
+**Methods:**
+
+```typescript
+generate(length: number): string
+number(min: number, max: number): number
+color(): string
+```
+
+## Integration with LocalStorage
+
+When encryption is enabled in LocalStorageManagerService:
+
+```typescript
+import { LocalStorageManagerService } from 'http-request-manager';
+
+@Injectable({ providedIn: 'root' })
+export class SecureStorageService {
+  private storage = inject(LocalStorageManagerService);
+
+  constructor() {
+    this.storage.init({
+      store: 'secure-data',
+      options: {
+        encrypted: true,  // All data is encrypted with AES
+        storage: StorageType.GLOBAL
+      }
+    });
+  }
+
+  saveSecretData(data: any) {
+    this.storage.setItem('sensitive', data);
+    // Data is automatically encrypted before storage
+  }
+
+  getSecretData() {
+    return this.storage.getItem('sensitive');
+    // Data is automatically decrypted on retrieval
+  }
+}
+```
+
+## Security Best Practices
+
+### 1. Protect Private Keys
+
+```typescript
+// ❌ NEVER store private keys in code
+const privateKey = '-----BEGIN PRIVATE KEY-----...';
+
+// ✅ Store in secure environment variables or secure vault
+const privateKey = process.env.PRIVATE_KEY;
+```
+
+### 2. Use APP_ID Uniquely
+
+```typescript
+// ❌ Don't use generic APP_ID
+{ provide: APP_ID, useValue: 'my-app' }
+
+// ✅ Use unique GUID
+{ provide: APP_ID, useValue: '550e8400-e29b-41d4-a716-446655440000' }
+```
+
+### 3. Encrypt Sensitive Data
+
+```typescript
+// ❌ Don't store sensitive data in plain text
+localStorage.setItem('token', 'secret-jwt-token');
+
+// ✅ Use encrypted storage
+storage.setItem('token', 'secret-jwt-token'); // Auto-encrypted
+```
+
+### 4. Rotate Keys Periodically
+
+```typescript
+// Generate new key pairs periodically
+const newKeyPair = encryption.generateKeyPair();
+// Update stored public key
+// Securely distribute new public key
+```
+
+## Use Cases
+
+### 1. Secure User Preferences
+
+```typescript
+interface SecurePreferences {
+  apiKeys: string[];
+  passwords: { [service: string]: string };
+  tokens: string[];
+}
+
+// Store with encryption
+storage.setItem('preferences', preferences);
+```
+
+### 2. Protect API Keys
+
+```typescript
+const apiKey = 'sk-1234567890';
+const encrypted = encryption.encrypt(apiKey);
+localStorage.setItem('encryptedApiKey', encrypted);
+```
+
+### 3. Secure Communication
+
+```typescript
+// Encrypt message with recipient's public key
+const encryptedMessage = encryption.encryptWithPublicKey(
+  message,
+  recipientPublicKey
+);
+
+// Recipient decrypts with private key
+const decrypted = encryption.decryptWithPrivateKey(
+  encryptedMessage,
+  recipientPrivateKey
+);
+```
+
+### 4. Digital Signatures
+
+```typescript
+// Sign data
+const signature = encryption.sign(data, privateKey);
+
+// Verify signature
+const isValid = encryption.verify(signature, data, publicKey);
+```
+
+## Related Documentation
+
+- [`LocalStorage Manager`](LOCAL_STORAGE_README.md) - Encrypted storage integration
+- [`Utils Service`](UTILS_README.md) - All utility functions
+- [`Models Guide`](MODELS_README.md) - Configuration models
+- [`Complete API Reference`](COMPLETE_API_REFERENCE.md) - Full API documentation
+
+## Security Considerations
+
+⚠️ **Important:**
+
+1. **Key Management** - Private keys must be kept secure
+2. **APP_ID** - Must be unique per application
+3. **Encryption Overhead** - Encryption adds processing time
+4. **Browser Security** - Client-side encryption is not a substitute for server-side security
+5. **Key Rotation** - Implement key rotation for long-term security
+
+For production use, consider:
+- Server-side key management
+- Hardware Security Modules (HSM)
+- Key derivation functions (PBKDF2, bcrypt)
+- Regular security audits