cdp-lite-sdk 0.1.7 → 0.1.8

package/README.md

@@ -218,7 +218,7 @@ const cdp = new CdpLiteSdk({
 });
 ```
 
-**📖 See [SECURITY.md](./SECURITY.md) for complete security documentation.**
+**📖 See [SECURITY.md](https://gitlab.ovp.vn/dlc/vc-cdp-sdk/blob/master/sdk-js/SECURITY.md) for complete security documentation.**
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-lite-sdk",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "CDP Lite SDK for tracking events and users - Customer Data Platform",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -16,7 +16,6 @@
   "files": [
     "dist",
     "README.md",
-    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {

package/SECURITY.md

@@ -1,513 +0,0 @@
-# 🔒 CDP Lite SDK - Security Documentation
-
-Comprehensive security features for protecting user data and API communications.
-
----
-
-## 🎯 Security Features
-
-### 1. **Request Signatures (HMAC-SHA256)**
-Mọi request đều được ký bằng HMAC để đảm bảo tính toàn vẹn và xác thực.
-
-### 2. **Traits Encryption (AES-256-CBC)**
-Thông tin nhạy cảm của user được mã hóa trước khi gửi.
-
-### 3. **Dynamic Keys**
-Keys được generate động dựa trên timestamp để tăng bảo mật.
-
----
-
-## 🔐 How It Works
-
-### Request Signing
-
-```
-X-Signatures = Base64(HMAC-SHA256(X-Source + "|" + X-Timestamp + "|" + Payload))
-HMAC Key = Secret Key
-```
-
-**Example:**
-```javascript
-const source = "Fiza";
-const timestamp = "1767583520";
-const payload = '{"event":"view_home","properties":{...}}';
-const message = source + "|" + timestamp + "|" + payload;
-const signature = Base64(HMAC-SHA256(message, secretKey));
-```
-
-### Traits Encryption
-
-```
-AES Key = SHA256(SecretKey + X-Timestamp)
-Encrypted Traits = Base64(AES-256-CBC(Traits, AES Key))
-```
-
-**Sensitive Fields:**
-- `full_name`, `first_name`, `last_name`
-- `idcard`, `old_idcard`
-- `phone`, `email`
-- `gender`, `dob`
-- `address`, `religion`
-
-**Example:**
-```javascript
-const timestamp = "1767583520";
-const aesKey = SHA256(secretKey + timestamp);
-const traits = {
-  full_name: "Nguyen Van A",
-  email: "user@example.com",
-  phone: "0901234567"
-};
-const encryptedTraits = Base64(AES-256-CBC(JSON.stringify(traits), aesKey));
-```
-
----
-
-## 🚀 Quick Start
-
-### Initialization with Security
-
-```javascript
-import CdpLiteSdk from 'cdp-lite-sdk';
-
-const cdp = new CdpLiteSdk({
-  apiKey: 'your-api-key',
-  secretKey: 'your-secret-key',  // Required for security features
-  source: 'YourApp',
-  serviceName: 'YourService',
-  enableEncryption: true,  // Enable encryption (default: true)
-  debug: true
-});
-```
-
-### Identify User with Auto-Encryption
-
-```javascript
-// SDK automatically encrypts sensitive fields
-cdp.identify('user_123', {
-  // Sensitive fields (will be encrypted)
-  full_name: 'Nguyen Van A',
-  first_name: 'A',
-  last_name: 'Nguyen Van',
-  email: 'user@example.com',
-  phone: '0901234567',
-  idcard: '001234567890',
-  dob: '1990-01-01',
-  gender: 'male',
-  address: '123 ABC Street, Hanoi',
-  religion: 'Buddhism',
-  
-  // Non-sensitive fields (won't be encrypted)
-  age: 30,
-  city: 'Hanoi',
-  subscription: 'premium'
-});
-```
-
-### Track Event with Signature
-
-```javascript
-// Request automatically signed with HMAC
-cdp.track('purchase_completed', {
-  order_id: 'ORDER123',
-  amount: 99.99,
-  currency: 'VND'
-});
-```
-
----
-
-## 📋 Configuration Options
-
-### Security Configuration
-
-```javascript
-const cdp = new CdpLiteSdk({
-  // Required for security
-  apiKey: 'string',           // API Key
-  secretKey: 'string',        // Secret Key for HMAC & encryption
-  
-  // Optional
-  enableEncryption: boolean,  // Enable traits encryption (default: true)
-  source: 'string',           // Source identifier
-  serviceName: 'string',      // Service name
-  debug: boolean              // Show encryption logs
-});
-```
-
-### Environment Variables (Recommended)
-
-```bash
-# .env
-CDP_API_KEY=your-api-key
-CDP_SECRET_KEY=your-secret-key
-CDP_SOURCE=YourApp
-CDP_SERVICE_NAME=YourService
-```
-
-```javascript
-const cdp = new CdpLiteSdk({
-  apiKey: process.env.CDP_API_KEY,
-  secretKey: process.env.CDP_SECRET_KEY,
-  source: process.env.CDP_SOURCE,
-  serviceName: process.env.CDP_SERVICE_NAME
-});
-```
-
----
-
-## 🔧 Advanced Usage
-
-### Manual Encryption Control
-
-```javascript
-// Disable auto-encryption
-const cdp = new CdpLiteSdk({
-  apiKey: 'your-api-key',
-  secretKey: 'your-secret-key',
-  enableEncryption: false  // Disable encryption
-});
-
-// Traits won't be encrypted
-cdp.identify('user_123', {
-  email: 'user@example.com'  // Sent as plain text
-});
-```
-
-### Partial Sensitive Data
-
-```javascript
-// Only fields in sensitive list will be encrypted
-cdp.identify('user_123', {
-  // These WILL be encrypted
-  email: 'user@example.com',
-  phone: '0901234567',
-  
-  // These WON'T be encrypted
-  username: 'user123',
-  city: 'Hanoi',
-  age: 30
-});
-```
-
-### Verify Encryption
-
-```javascript
-const cdp = new CdpLiteSdk({
-  apiKey: 'your-api-key',
-  secretKey: 'your-secret-key',
-  debug: true  // See encryption logs
-});
-
-// Check console for encryption status
-cdp.identify('user_123', {
-  email: 'test@example.com'
-});
-// Console: [CDP Lite SDK] User identified { userId: 'user_123', traitsEncrypted: true }
-```
-
----
-
-## 🛡️ Security Best Practices
-
-### 1. **Protect Secret Keys**
-
-```javascript
-// ❌ BAD - Hardcoded keys
-const cdp = new CdpLiteSdk({
-  apiKey: 'abc123',
-  secretKey: 'my-secret-key'
-});
-
-// ✅ GOOD - Use environment variables
-const cdp = new CdpLiteSdk({
-  apiKey: process.env.CDP_API_KEY,
-  secretKey: process.env.CDP_SECRET_KEY
-});
-```
-
-### 2. **Never Commit Keys**
-
-```bash
-# .gitignore
-.env
-.env.local
-.env.*.local
-config/secrets.js
-```
-
-### 3. **Use Different Keys per Environment**
-
-```javascript
-// Development
-const cdp = new CdpLiteSdk({
-  apiKey: process.env.DEV_CDP_API_KEY,
-  secretKey: process.env.DEV_CDP_SECRET_KEY,
-  baseUrl: 'https://stg-ingestlog.vietcredit.com.vn',
-  isTest: true
-});
-
-// Production
-const cdp = new CdpLiteSdk({
-  apiKey: process.env.PROD_CDP_API_KEY,
-  secretKey: process.env.PROD_CDP_SECRET_KEY,
-  baseUrl: 'https://vconnect.vietcredit.com.vn',
-  isTest: false
-});
-```
-
-### 4. **Rotate Keys Regularly**
-
-Update your secret keys periodically and deploy new versions.
-
-### 5. **Validate on Server Side**
-
-Server should validate:
-- X-Signatures match
-- X-Timestamp is recent (prevent replay attacks)
-- Decrypt traits and validate format
-
----
-
-## 🔍 How to Test Security
-
-### Test Signature Generation
-
-```javascript
-const cdp = new CdpLiteSdk({
-  apiKey: 'test-key',
-  secretKey: 'test-secret',
-  debug: true  // See signatures in console
-});
-
-cdp.track('test_event', { test: true });
-// Check Network tab > Headers > X-Signatures
-```
-
-### Test Traits Encryption
-
-```javascript
-const cdp = new CdpLiteSdk({
-  apiKey: 'test-key',
-  secretKey: 'test-secret',
-  debug: true
-});
-
-cdp.identify('user_123', {
-  email: 'test@example.com',
-  phone: '0901234567'
-});
-// Check Network tab > Payload > traits (should be Base64 string)
-```
-
-### Verify in Browser DevTools
-
-1. Open DevTools > Network tab
-2. Trigger an identify or track call
-3. Check request:
-   - Headers: `X-Signatures` should have Base64 value
-   - Payload: `traits` should be encrypted Base64 string
-
----
-
-## 🧪 Example: Complete Secure Flow
-
-```javascript
-import CdpLiteSdk from 'cdp-lite-sdk';
-
-// 1. Initialize with security
-const cdp = new CdpLiteSdk({
-  apiKey: process.env.CDP_API_KEY,
-  secretKey: process.env.CDP_SECRET_KEY,
-  source: 'MySecureApp',
-  serviceName: 'UserService',
-  enableEncryption: true,
-  debug: process.env.NODE_ENV === 'development'
-});
-
-// 2. User registration - sensitive data encrypted
-async function handleUserRegistration(userData) {
-  try {
-    // Identify with encrypted traits
-    await cdp.identify(userData.id, {
-      // Encrypted fields
-      full_name: userData.fullName,
-      email: userData.email,
-      phone: userData.phone,
-      idcard: userData.idCard,
-      dob: userData.dateOfBirth,
-      address: userData.address,
-      
-      // Non-encrypted metadata
-      signup_source: 'web',
-      referrer: document.referrer
-    });
-
-    // Track registration event (signed)
-    cdp.track('user_registered', {
-      method: 'email',
-      timestamp: new Date().toISOString()
-    });
-
-    console.log('User registered securely');
-  } catch (error) {
-    console.error('Registration failed:', error);
-  }
-}
-
-// 3. Sensitive action with loan info
-async function handleLoanApplication(loanData) {
-  const loanCode = 'LOAN_' + Date.now();
-  
-  // Update user with income info (encrypted)
-  await cdp.setUserAttributes({
-    income: loanData.monthlyIncome,
-    employment: loanData.employmentType
-  });
-
-  // Track application (signed)
-  cdp.track('loan_application_submitted', {
-    amount: loanData.amount,
-    term: loanData.term,
-    purpose: loanData.purpose
-  }, {
-    loanCode: loanCode
-  });
-}
-
-// 4. Logout - clear data
-function handleLogout() {
-  cdp.track('user_logged_out');
-  cdp.flush();  // Send remaining events
-  cdp.reset();  // Clear user data
-}
-```
-
----
-
-## 🔐 Encryption Algorithm Details
-
-### AES-256-CBC
-
-- **Algorithm:** AES (Advanced Encryption Standard)
-- **Mode:** CBC (Cipher Block Chaining)
-- **Key Length:** 256 bits
-- **IV:** 128 bits (randomly generated per encryption)
-- **Key Derivation:** SHA-256 hash of (SecretKey + Timestamp)
-
-### HMAC-SHA256
-
-- **Algorithm:** HMAC (Hash-based Message Authentication Code)
-- **Hash Function:** SHA-256
-- **Input:** X-Source + "|" + X-Timestamp + "|" + Payload
-- **Output:** Base64-encoded signature
-
----
-
-## 📊 Performance Impact
-
-### Encryption Overhead
-
-- **Traits Encryption:** ~1-5ms per identify call
-- **Request Signing:** ~1-2ms per request
-- **Impact:** Minimal for typical use cases
-- **Optimization:** Batching reduces overhead
-
-### Browser Support
-
-- ✅ Chrome 37+
-- ✅ Firefox 34+
-- ✅ Safari 11+
-- ✅ Edge 79+
-- ✅ Node.js 12+
-
-Uses Web Crypto API (browser) and crypto module (Node.js).
-
----
-
-## 🐛 Troubleshooting
-
-### Issue: Signature Mismatch
-
-**Error:** Server rejects request with signature error
-
-**Solution:**
-1. Verify secret key is correct
-2. Check timestamp synchronization
-3. Ensure payload format matches server expectations
-
-```javascript
-// Enable debug to see signature
-const cdp = new CdpLiteSdk({
-  secretKey: 'your-secret',
-  debug: true
-});
-```
-
-### Issue: Encryption Fails
-
-**Error:** Traits not encrypted
-
-**Solution:**
-1. Check secret key is provided
-2. Verify browser supports Web Crypto API
-3. Enable debug mode to see errors
-
-```javascript
-const cdp = new CdpLiteSdk({
-  secretKey: 'your-secret',
-  enableEncryption: true,
-  debug: true  // See encryption errors
-});
-```
-
-### Issue: Empty Traits
-
-**Error:** Traits field is empty string
-
-**Cause:** No sensitive fields provided
-
-**Solution:** Include at least one sensitive field:
-
-```javascript
-// This won't encrypt (no sensitive fields)
-cdp.identify('user_123', {
-  age: 30,
-  city: 'Hanoi'
-});
-
-// This will encrypt
-cdp.identify('user_123', {
-  email: 'user@example.com',  // Sensitive field
-  age: 30,
-  city: 'Hanoi'
-});
-```
-
----
-
-## 🔒 Security Checklist
-
-- [ ] Secret key stored in environment variables
-- [ ] Different keys for dev/staging/production
-- [ ] Keys not committed to version control
-- [ ] HTTPS used for all requests
-- [ ] Encryption enabled in production
-- [ ] Debug mode disabled in production
-- [ ] Keys rotated periodically
-- [ ] Server validates signatures
-- [ ] Server decrypts and validates traits
-- [ ] Timestamp checked for replay attacks
-
----
-
-## 📞 Need Help?
-
-- 📖 [Main Documentation](README.md)
-- 🐛 [Report Security Issues](mailto:vinv@vega.com.vn)
-
-**⚠️ Security Disclosure:** If you find a security vulnerability, please email vinv@vega.com.vn instead of creating a public issue.
-
----
-
-Made with 🔒 by Your Team