native-update 1.2.0 → 1.3.0

package/docs/ROADMAP.md

@@ -0,0 +1,143 @@
+# Capacitor Native Update - Development Roadmap
+
+This document outlines what needs to be built to make this package production-ready.
+
+## 🚨 Current Status: Foundation Only
+
+This package provides architecture and interfaces but requires significant development before production use.
+
+## 📋 Required Components for Production
+
+### 1. Backend Infrastructure (Critical)
+
+#### Update Server
+- [ ] REST API endpoints for update management
+- [ ] Version management system
+- [ ] Bundle storage and retrieval
+- [ ] Update manifest generation
+- [ ] Channel management (production, staging, dev)
+- [ ] Analytics and monitoring endpoints
+
+#### Security Infrastructure
+- [ ] Bundle signing service
+- [ ] Public/private key management
+- [ ] Encryption implementation
+- [ ] Certificate management
+- [ ] Checksum generation
+
+#### CDN Integration
+- [ ] Bundle distribution setup
+- [ ] Geographic distribution
+- [ ] Caching strategies
+- [ ] Bandwidth optimization
+
+### 2. Native Platform Implementation
+
+#### iOS (Swift)
+- [ ] Verify existing Swift implementation
+- [ ] Complete missing functionality
+- [ ] Test all plugin methods
+- [ ] Handle edge cases
+- [ ] Memory management optimization
+- [ ] Background task handling
+
+#### Android (Kotlin)
+- [ ] Verify existing Kotlin implementation
+- [ ] Complete missing functionality
+- [ ] Test all plugin methods
+- [ ] Handle Android lifecycle
+- [ ] Permission management
+- [ ] Background service implementation
+
+### 3. Testing Suite
+
+#### Unit Tests
+- [ ] TypeScript plugin tests
+- [ ] iOS native tests
+- [ ] Android native tests
+- [ ] Web implementation tests
+
+#### Integration Tests
+- [ ] Cross-platform compatibility
+- [ ] Update flow testing
+- [ ] Rollback scenarios
+- [ ] Network failure handling
+
+#### E2E Tests
+- [ ] Complete update lifecycle
+- [ ] Multi-version updates
+- [ ] Security validation
+- [ ] Performance benchmarks
+
+### 4. Tooling and Utilities
+
+#### Bundle Management
+- [ ] Bundle creation CLI tool
+- [ ] Bundle signing utility
+- [ ] Version management tool
+- [ ] Deployment scripts
+
+#### Developer Tools
+- [ ] Local testing server
+- [ ] Debug utilities
+- [ ] Migration tools
+- [ ] Documentation generator
+
+### 5. Production Features
+
+#### Monitoring
+- [ ] Update success metrics
+- [ ] Error tracking
+- [ ] Performance monitoring
+- [ ] User analytics
+
+#### Advanced Features
+- [ ] Delta update implementation
+- [ ] Partial rollouts
+- [ ] A/B testing support
+- [ ] Multi-app management
+
+## 🎯 Implementation Priority
+
+### Phase 1: Core Infrastructure (Required)
+1. Basic update server
+2. Native platform verification
+3. Security implementation
+4. Basic testing
+
+### Phase 2: Production Readiness
+1. CDN integration
+2. Monitoring and analytics
+3. Advanced tooling
+4. Performance optimization
+
+### Phase 3: Enterprise Features
+1. Delta updates
+2. Advanced rollout strategies
+3. Multi-tenant support
+4. Enterprise security
+
+## 📝 Getting Started
+
+If you want to use this package, you should:
+
+1. **Build the update server first** - Without this, nothing will work
+2. **Test native implementations** - Ensure they work on real devices
+3. **Create basic tooling** - At minimum, bundle creation and signing
+4. **Add monitoring** - Know when updates succeed or fail
+
+## ⏱️ Estimated Development Time
+
+- **Minimum Viable Implementation**: 2-3 months
+- **Production-Ready Solution**: 4-6 months
+- **Enterprise-Grade System**: 6-12 months
+
+## 🤝 Contributing
+
+We welcome contributions! Focus areas:
+- Backend server examples
+- Native platform testing
+- Security implementations
+- Testing frameworks
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

package/docs/SECURITY.md

@@ -0,0 +1,356 @@
+# Security Guidelines for Capacitor Native Update Plugin
+
+This document outlines the security measures and best practices implemented in the Capacitor Native Update plugin, following the official [Capacitor Security Guidelines](https://capacitorjs.com/docs/guides/security).
+
+## Table of Contents
+
+- [Security Principles](#security-principles)
+- [Secure Update Process](#secure-update-process)
+- [Platform-Specific Security](#platform-specific-security)
+- [Data Protection](#data-protection)
+- [Network Security](#network-security)
+- [Input Validation](#input-validation)
+- [Permission Management](#permission-management)
+- [Security Configuration](#security-configuration)
+- [Security Checklist](#security-checklist)
+
+## Security Principles
+
+### 1. No Embedded Secrets
+
+- **Never** embed API keys, encryption keys, or certificates in the plugin code
+- All sensitive configuration must be provided at runtime by the host application
+- Use environment-specific configuration files that are not committed to version control
+
+### 2. Defense in Depth
+
+- Multiple layers of security validation
+- Fail securely - deny by default
+- Comprehensive error handling without exposing sensitive information
+
+### 3. Principle of Least Privilege
+
+- Request only necessary permissions
+- Minimize access to system resources
+- Isolate update processes from main application
+
+## Secure Update Process
+
+### Bundle Verification
+
+```typescript
+// Example of secure update verification
+const verifyUpdate = async (bundle: UpdateBundle): Promise<boolean> => {
+  // 1. Verify HTTPS URL
+  if (!bundle.url.startsWith('https://')) {
+    throw new SecurityError('INSECURE_URL', 'Updates must use HTTPS');
+  }
+
+  // 2. Verify checksum
+  const calculatedChecksum = await calculateSHA256(bundle.data);
+  if (calculatedChecksum !== bundle.expectedChecksum) {
+    throw new SecurityError(
+      'INVALID_CHECKSUM',
+      'Bundle integrity check failed'
+    );
+  }
+
+  // 3. Verify signature (if configured)
+  if (config.requireSignature) {
+    const isValidSignature = await verifySignature(
+      bundle.data,
+      bundle.signature,
+      publicKey
+    );
+    if (!isValidSignature) {
+      throw new SecurityError(
+        'INVALID_SIGNATURE',
+        'Bundle signature verification failed'
+      );
+    }
+  }
+
+  return true;
+};
+```
+
+### Version Validation
+
+- Prevent downgrade attacks by default
+- Semantic version comparison
+- Minimum native version requirements
+
+## Platform-Specific Security
+
+### iOS Security
+
+#### Keychain Usage
+
+```swift
+// Store sensitive data in Keychain, not UserDefaults
+let keychain = KeychainWrapper()
+keychain.set(updateKey, forKey: "UpdateEncryptionKey")
+```
+
+#### File System Security
+
+```swift
+// Validate file operations stay within app sandbox
+guard let documentsPath = FileManager.default.urls(for: .documentDirectory,
+                                                   in: .userDomainMask).first else {
+    throw UpdateError.invalidPath
+}
+
+let updatePath = documentsPath.appendingPathComponent("updates")
+// Ensure path doesn't escape sandbox
+guard updatePath.path.hasPrefix(documentsPath.path) else {
+    throw UpdateError.pathTraversal
+}
+```
+
+### Android Security
+
+#### Android Keystore
+
+```kotlin
+// Use Android Keystore for sensitive data
+val keyAlias = "UpdateKeyAlias"
+val keyStore = KeyStore.getInstance("AndroidKeyStore")
+keyStore.load(null)
+
+// Generate or retrieve key
+if (!keyStore.containsAlias(keyAlias)) {
+    val keyGenerator = KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore")
+    val keyGenParameterSpec = KeyGenParameterSpec.Builder(
+        keyAlias,
+        KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+    ).build()
+    keyGenerator.init(keyGenParameterSpec)
+    keyGenerator.generateKey()
+}
+```
+
+#### Permission Handling
+
+```java
+@Permission(strings = {
+    Manifest.permission.INTERNET,
+    Manifest.permission.ACCESS_NETWORK_STATE
+}, alias = "network")
+@Permission(strings = {
+    Manifest.permission.WRITE_EXTERNAL_STORAGE
+}, alias = "storage")
+public class NativeUpdatePlugin extends Plugin {
+    @PluginMethod
+    public void downloadUpdate(PluginCall call) {
+        if (!hasPermission("network")) {
+            requestPermissionForAlias("network", call, "handleNetworkPermission");
+            return;
+        }
+        // Proceed with download
+    }
+}
+```
+
+## Data Protection
+
+### Secure Storage
+
+1. **Sensitive Data**: Store in platform-specific secure storage (Keychain/Keystore)
+2. **Update Metadata**: Store in app-specific directories with restricted permissions
+3. **Temporary Files**: Use system temp directories and clean up immediately
+
+### Encryption
+
+```typescript
+// Example encryption configuration
+export interface EncryptionConfig {
+  algorithm: 'AES-256-GCM';
+  keyDerivation: 'PBKDF2';
+  iterations: 100000;
+  saltLength: 32;
+}
+```
+
+## Network Security
+
+### HTTPS Enforcement
+
+```typescript
+// Validate URLs before making requests
+const validateUpdateUrl = (url: string): void => {
+  const parsedUrl = new URL(url);
+
+  if (parsedUrl.protocol !== 'https:') {
+    throw new SecurityError('INSECURE_PROTOCOL', 'Only HTTPS URLs are allowed');
+  }
+
+  // Optional: Validate against whitelist
+  if (config.allowedHosts && !config.allowedHosts.includes(parsedUrl.host)) {
+    throw new SecurityError(
+      'UNAUTHORIZED_HOST',
+      'Update host not in whitelist'
+    );
+  }
+};
+```
+
+### Certificate Pinning
+
+```typescript
+// Certificate pinning configuration
+export interface CertificatePinning {
+  enabled: boolean;
+  certificates: string[]; // Base64 encoded certificates
+  includeSubdomains: boolean;
+  maxAge: number; // Seconds
+}
+```
+
+## Input Validation
+
+### JavaScript to Native Bridge
+
+```typescript
+// Validate all inputs from JavaScript
+const validateUpdateOptions = (options: any): UpdateOptions => {
+  // Type validation
+  if (typeof options !== 'object' || options === null) {
+    throw new ValidationError('Invalid options object');
+  }
+
+  // URL validation
+  if (typeof options.url !== 'string' || !options.url) {
+    throw new ValidationError('URL must be a non-empty string');
+  }
+
+  // Version validation
+  if (options.version && !isValidSemver(options.version)) {
+    throw new ValidationError('Invalid version format');
+  }
+
+  // File size validation
+  if (
+    options.maxSize &&
+    (typeof options.maxSize !== 'number' || options.maxSize <= 0)
+  ) {
+    throw new ValidationError('maxSize must be a positive number');
+  }
+
+  return options as UpdateOptions;
+};
+```
+
+### Path Validation
+
+```typescript
+// Prevent directory traversal attacks
+const sanitizePath = (path: string): string => {
+  // Remove any path traversal attempts
+  const cleaned = path.replace(/\.\./g, '').replace(/\/\//g, '/');
+
+  // Ensure path is within allowed directory
+  if (!cleaned.startsWith(ALLOWED_UPDATE_PATH)) {
+    throw new SecurityError('PATH_TRAVERSAL', 'Invalid update path');
+  }
+
+  return cleaned;
+};
+```
+
+## Permission Management
+
+### Android Permissions
+
+```xml
+<!-- AndroidManifest.xml -->
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+<!-- Request at runtime for Android 6.0+ -->
+<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
+                 android:maxSdkVersion="28" />
+```
+
+### iOS Permissions
+
+```xml
+<!-- Info.plist -->
+<key>NSAppTransportSecurity</key>
+<dict>
+    <!-- Only allow HTTPS connections -->
+    <key>NSAllowsArbitraryLoads</key>
+    <false/>
+</dict>
+```
+
+## Security Configuration
+
+### Recommended Configuration
+
+```typescript
+const secureConfig: UpdateSecurityConfig = {
+  // Network Security
+  enforceHttps: true,
+  certificatePinning: {
+    enabled: true,
+    certificates: ['sha256/...'],
+    maxAge: 60 * 60 * 24 * 30, // 30 days
+  },
+
+  // Update Security
+  requireSignature: true,
+  allowDowngrade: false,
+  checksumAlgorithm: 'SHA-256',
+
+  // Storage Security
+  encryptStorage: true,
+  secureStorageKeys: ['updateKey', 'serverConfig'],
+
+  // Validation
+  maxBundleSize: 50 * 1024 * 1024, // 50MB
+  allowedHosts: ['updates.yourdomain.com'],
+
+  // Error Handling
+  exposeDetailedErrors: false,
+  logSecurityEvents: true,
+};
+```
+
+## Security Checklist
+
+### Development Phase
+
+- [ ] No hardcoded secrets or keys in code
+- [ ] All network requests use HTTPS
+- [ ] Input validation on all public methods
+- [ ] Proper error handling without exposing internals
+- [ ] Secure storage for sensitive data
+- [ ] Permission requests are minimal and justified
+
+### Before Release
+
+- [ ] Security audit of all native code
+- [ ] Penetration testing of update mechanism
+- [ ] Certificate pinning configured for production
+- [ ] All debug logs removed from production builds
+- [ ] Documentation of security features complete
+- [ ] Security configuration examples provided
+
+### Ongoing Maintenance
+
+- [ ] Regular dependency updates
+- [ ] Security patch monitoring
+- [ ] Incident response plan
+- [ ] Regular security audits
+- [ ] User security guidance updates
+
+## Reporting Security Issues
+
+If you discover a security vulnerability, please email aoneahsan@gmail.com with:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Potential impact
+- Suggested fix (if any)
+
+Please do **not** file public issues for security vulnerabilities.