native-update 1.3.2 → 1.3.4

package/docs/TESTING_REQUIREMENTS.md

@@ -0,0 +1,312 @@
+# Testing Requirements
+
+This document outlines the testing requirements for the native-update plugin.
+
+## Current Testing Status
+
+- **Plugin testing**: Handled in actual/live applications using the plugin
+- **Example apps**: Demonstrate functionality for manual testing
+- **Unit tests (TypeScript)**: ✅ Implemented in `/src/__tests__/`
+- **iOS Native Tests (XCTest)**: ✅ Implemented in `/ios/Tests/NativeUpdateTests/`
+- **Android Native Tests (JUnit/Kotlin)**: ✅ Implemented in `/android/src/test/`
+- **E2E Tests (Detox)**: ✅ Implemented in `/e2e/`
+
+---
+
+## iOS Native Tests (XCTest)
+
+### Test File Structure
+```
+ios/
+└── Tests/
+    └── NativeUpdateTests/
+        ├── LiveUpdateTests.swift
+        ├── AppUpdateTests.swift
+        ├── AppReviewTests.swift
+        ├── BundleManagerTests.swift
+        └── SecurityTests.swift
+```
+
+### Test Categories
+
+#### LiveUpdateTests.swift
+- `testCheckForUpdate()` - Verify update check returns correct response
+- `testDownloadBundle()` - Verify bundle download with progress
+- `testApplyUpdate()` - Verify bundle extraction and application
+- `testRollback()` - Verify rollback to previous version
+- `testChecksumVerification()` - Verify SHA-256 checksum validation
+- `testSignatureVerification()` - Verify RSA/ECDSA signature validation
+- `testChannelManagement()` - Verify channel switching (production/staging/dev)
+
+#### AppUpdateTests.swift
+- `testCheckAppStoreVersion()` - Verify app store version check
+- `testVersionComparison()` - Verify semantic version comparison
+- `testUpdateAvailability()` - Verify update availability detection
+- `testOpenAppStore()` - Verify App Store navigation
+
+#### AppReviewTests.swift
+- `testRequestReview()` - Verify StoreKit review request
+- `testRateLimiting()` - Verify review request rate limiting
+
+#### BundleManagerTests.swift
+- `testBundleStorage()` - Verify bundle storage in app sandbox
+- `testBundleCleanup()` - Verify old bundle cleanup
+- `testActiveBundlePath()` - Verify active bundle path resolution
+
+#### SecurityTests.swift
+- `testInputValidation()` - Verify URL/input sanitization
+- `testHTTPSEnforcement()` - Verify HTTPS-only connections
+- `testDowngradeProtection()` - Verify version downgrade prevention
+- `testKeychain Storage()` - Verify sensitive data in Keychain
+
+### Running iOS Tests
+```bash
+cd ios
+xcodebuild test -scheme NativeUpdate -destination 'platform=iOS Simulator,name=iPhone 15'
+```
+
+### Current Test Files (✅ Implemented)
+
+| File | Tests | Status |
+|------|-------|--------|
+| `SecurityManagerTests.swift` | 6 tests | ✅ |
+| `LiveUpdateTests.swift` | 10 tests | ✅ |
+| `AppUpdateTests.swift` | 5 tests | ✅ |
+| `AppReviewTests.swift` | 5 tests | ✅ |
+| `BackgroundUpdateTests.swift` | 6 tests | ✅ |
+| **Total** | **32 tests** | ✅ |
+
+---
+
+## Android Native Tests (JUnit)
+
+### Test File Structure
+```
+android/
+└── src/
+    └── test/
+        └── java/
+            └── com/
+                └── aoneahsan/
+                    └── nativeupdate/
+                        ├── LiveUpdateTest.kt
+                        ├── AppUpdateTest.kt
+                        ├── AppReviewTest.kt
+                        ├── BundleManagerTest.kt
+                        └── SecurityTest.kt
+```
+
+### Test Categories
+
+#### LiveUpdateTest.kt
+- `testCheckForUpdate()` - Verify update check HTTP request
+- `testDownloadBundle()` - Verify bundle download with OkHttp
+- `testApplyUpdate()` - Verify bundle extraction to internal storage
+- `testRollback()` - Verify rollback mechanism
+- `testChecksumVerification()` - Verify SHA-256 validation
+- `testSignatureVerification()` - Verify signature with Android Keystore
+- `testChannelManagement()` - Verify channel configuration
+
+#### AppUpdateTest.kt
+- `testCheckPlayStoreVersion()` - Verify Play Core version check
+- `testImmediateUpdate()` - Verify blocking update flow
+- `testFlexibleUpdate()` - Verify background update flow
+- `testUpdatePriority()` - Verify update priority handling
+
+#### AppReviewTest.kt
+- `testRequestReview()` - Verify Play Core review API
+- `testReviewManagerInitialization()` - Verify ReviewManager setup
+- `testRateLimiting()` - Verify request limiting
+
+#### BundleManagerTest.kt
+- `testBundleStorage()` - Verify internal storage operations
+- `testBundleCleanup()` - Verify old bundle deletion
+- `testActiveBundlePath()` - Verify bundle path resolution
+- `testStoragePermissions()` - Verify no external storage access
+
+#### SecurityTest.kt
+- `testInputValidation()` - Verify input sanitization
+- `testHTTPSEnforcement()` - Verify HTTPS-only policy
+- `testDowngradeProtection()` - Verify version validation
+- `testKeystore()` - Verify Android Keystore usage
+
+### Running Android Tests
+```bash
+cd android
+./gradlew test
+./gradlew connectedAndroidTest  # For instrumented tests
+```
+
+### Current Test Files (✅ Implemented)
+
+| File | Tests | Status |
+|------|-------|--------|
+| `SecurityManagerTest.kt` | 10 tests | ✅ |
+| `LiveUpdatePluginTest.kt` | 10 tests | ✅ |
+| `AppUpdatePluginTest.kt` | 5 tests | ✅ |
+| `AppReviewPluginTest.kt` | 5 tests | ✅ |
+| `BackgroundUpdateWorkerTest.kt` | 5 tests | ✅ |
+| `BackgroundNotificationManagerTest.kt` | 5 tests | ✅ |
+| **Total** | **40 tests** | ✅ |
+
+### Test Dependencies (Added to build.gradle)
+
+```gradle
+testImplementation 'junit:junit:4.13.2'
+testImplementation 'org.mockito:mockito-core:5.8.0'
+testImplementation 'org.mockito.kotlin:mockito-kotlin:5.2.1'
+testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3'
+testImplementation 'com.google.truth:truth:1.1.5'
+testImplementation 'org.robolectric:robolectric:4.11.1'
+```
+
+---
+
+## End-to-End Tests (Detox) ✅ IMPLEMENTED
+
+The E2E tests are implemented in `/e2e/` using Detox framework.
+
+### Framework
+- **Detox** for React Native + Capacitor apps
+
+### Test Coverage
+
+| Spec File | Tests | Status |
+|-----------|-------|--------|
+| `ota-update.e2e.spec.js` | 5 tests | ✅ |
+| `download-progress.e2e.spec.js` | 5 tests | ✅ |
+| `channel-switching.e2e.spec.js` | 5 tests | ✅ |
+| `error-handling.e2e.spec.js` | 4 tests | ✅ |
+| **Total** | **19 tests** | ✅ |
+
+### Running E2E Tests
+
+```bash
+cd e2e
+yarn install
+yarn build:android  # or yarn build:ios
+yarn test:android   # or yarn test:ios
+```
+
+### Mock Server
+
+Start the mock update server for E2E tests:
+```bash
+yarn start-mock-server
+```
+
+### Test Scenarios
+
+#### OTA Update Flow
+```
+1. App starts with version 1.0.0
+2. Server has version 1.1.0 available
+3. App checks for update → receives update info
+4. App downloads bundle → shows progress
+5. App applies update → restarts
+6. App shows version 1.1.0
+```
+
+#### Rollback Flow
+```
+1. App has version 1.1.0 applied
+2. New update 1.2.0 has critical bug
+3. App applies 1.2.0 → crashes on start
+4. App automatically rolls back to 1.1.0
+5. App reports rollback to server
+```
+
+#### Native Update Flow
+```
+1. App version 1.0.0 installed from store
+2. Store has version 2.0.0 (native update required)
+3. App detects native update available
+4. User shown update prompt
+5. User redirected to app store
+```
+
+#### Channel Switching
+```
+1. App configured for 'production' channel
+2. Developer switches to 'staging' channel
+3. App receives staging bundle
+4. App applies staging updates
+```
+
+### E2E Test File Structure
+```
+e2e/
+├── specs/
+│   ├── ota-update.spec.js
+│   ├── rollback.spec.js
+│   ├── native-update.spec.js
+│   └── channel-switching.spec.js
+├── helpers/
+│   └── server-mock.js
+└── setup.js
+```
+
+---
+
+## Test Server for E2E
+
+A mock update server should provide:
+
+```javascript
+// Mock endpoints
+GET /api/updates/check?appId=xxx&version=1.0.0&channel=production
+POST /api/updates/download/:bundleId
+POST /api/updates/report
+```
+
+The CLI already provides `npx native-update server start` for local testing.
+
+---
+
+## Security Testing Checklist
+
+- [ ] Test with malformed bundle files (corrupted ZIP)
+- [ ] Test with invalid checksums
+- [ ] Test with expired/invalid signatures
+- [ ] Test with HTTP URLs (should be rejected)
+- [ ] Test downgrade attempts (should be blocked)
+- [ ] Test oversized bundles (should respect limits)
+- [ ] Test with network interruptions
+- [ ] Test permission denial scenarios
+
+---
+
+## Test Implementation Status
+
+All test categories have been implemented as of 2026-01-16:
+
+| Category | Location | Tests | Status |
+|----------|----------|-------|--------|
+| TypeScript Unit Tests | `/src/__tests__/` | 9 test files | ✅ Complete |
+| iOS Native Tests | `/ios/Tests/NativeUpdateTests/` | 5 test files, 32 tests | ✅ Complete |
+| Android Native Tests | `/android/src/test/.../nativeupdate/` | 6 test files, 40 tests | ✅ Complete |
+| E2E Tests | `/e2e/specs/` | 4 spec files, 19 tests | ✅ Complete |
+| **Total** | | **~100 tests** | ✅ Complete |
+
+## Running All Tests
+
+```bash
+# TypeScript Unit Tests
+yarn test
+
+# iOS Native Tests
+cd ios && xcodebuild test -scheme NativeUpdate -destination 'platform=iOS Simulator,name=iPhone 15'
+
+# Android Native Tests
+cd android && ./gradlew test
+
+# E2E Tests
+cd e2e && yarn install && yarn test:android  # or yarn test:ios
+```
+
+## Additional Testing
+
+Manual testing is also supported through:
+- Example apps for end-user testing
+- CLI command verification
+- Integration testing in production apps

package/docs/guides/BACKEND_TEMPLATES_GUIDE.md

@@ -0,0 +1,183 @@
+# Backend Templates Guide
+
+This guide explains the backend templates provided by the native-update CLI and how to customize them for your production environment.
+
+## Overview
+
+The `npx native-update backend create <type>` command generates backend templates for managing OTA updates. These templates are **starting points** that require customization for your specific infrastructure.
+
+## Available Templates
+
+| Template | Command | Use Case |
+|----------|---------|----------|
+| Express.js | `npx native-update backend create express` | Self-hosted Node.js server |
+| Firebase | `npx native-update backend create firebase` | Serverless with Firebase Functions |
+| Vercel | `npx native-update backend create vercel` | Serverless with Vercel Edge Functions |
+
+## Template Structure
+
+Each template includes:
+
+```
+native-update-backend/
+├── src/
+│   ├── routes/
+│   │   ├── updates.js      # Update check/download endpoints
+│   │   └── admin.js        # Admin dashboard routes (if --with-admin)
+│   ├── services/
+│   │   ├── storage.js      # Bundle storage service (CUSTOMIZE THIS)
+│   │   └── database.js     # Metadata storage (CUSTOMIZE THIS)
+│   └── index.js            # Entry point
+├── package.json
+└── README.md
+```
+
+## Understanding Placeholder Code
+
+The generated templates contain placeholder implementations marked with comments explaining what you need to implement. These are **intentional customization points**, not incomplete code.
+
+### Example: Storage Service
+
+```javascript
+// storage.js - CUSTOMIZE FOR YOUR INFRASTRUCTURE
+export async function storeBundle(bundleId, file) {
+  // Implement your storage logic here
+  // Options:
+  // - AWS S3: Use @aws-sdk/client-s3
+  // - Google Cloud Storage: Use @google-cloud/storage
+  // - Azure Blob: Use @azure/storage-blob
+  // - Local filesystem: Use fs/promises
+  throw new Error('Storage not configured - implement storeBundle()');
+}
+
+export async function getBundle(bundleId) {
+  // Implement your retrieval logic here
+  throw new Error('Storage not configured - implement getBundle()');
+}
+```
+
+### Example: Database Service
+
+```javascript
+// database.js - CUSTOMIZE FOR YOUR INFRASTRUCTURE
+export async function saveBundleMetadata(metadata) {
+  // Implement your database logic here
+  // Options:
+  // - PostgreSQL: Use pg or prisma
+  // - MongoDB: Use mongoose
+  // - Firebase Firestore: Use firebase-admin
+  // - MySQL: Use mysql2
+  throw new Error('Database not configured - implement saveBundleMetadata()');
+}
+```
+
+## Customization Guide
+
+### Step 1: Choose Your Storage
+
+| Storage Option | Package | Best For |
+|----------------|---------|----------|
+| AWS S3 | `@aws-sdk/client-s3` | Production, scalable |
+| Google Cloud Storage | `@google-cloud/storage` | GCP infrastructure |
+| Azure Blob | `@azure/storage-blob` | Azure infrastructure |
+| Local Filesystem | `fs/promises` | Development only |
+| Cloudflare R2 | `@aws-sdk/client-s3` | Cost-effective |
+
+### Step 2: Choose Your Database
+
+| Database Option | Package | Best For |
+|----------------|---------|----------|
+| PostgreSQL | `pg`, `prisma` | Production, relational |
+| MongoDB | `mongoose` | Document-based |
+| Firebase Firestore | `firebase-admin` | Serverless |
+| SQLite | `better-sqlite3` | Small deployments |
+| Redis | `ioredis` | Caching, fast reads |
+
+### Step 3: Implement the Services
+
+Replace the placeholder functions with your actual implementations:
+
+```javascript
+// Example: AWS S3 implementation
+import { S3Client, PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';
+
+const s3 = new S3Client({ region: process.env.AWS_REGION });
+
+export async function storeBundle(bundleId, file) {
+  await s3.send(new PutObjectCommand({
+    Bucket: process.env.S3_BUCKET,
+    Key: `bundles/${bundleId}.zip`,
+    Body: file,
+  }));
+  return `bundles/${bundleId}.zip`;
+}
+
+export async function getBundle(bundleId) {
+  const response = await s3.send(new GetObjectCommand({
+    Bucket: process.env.S3_BUCKET,
+    Key: `bundles/${bundleId}.zip`,
+  }));
+  return response.Body;
+}
+```
+
+## Template Options
+
+### --with-admin
+
+Adds an admin dashboard for:
+- Viewing deployed bundles
+- Monitoring update adoption
+- Managing channels
+- Viewing device statistics
+
+### --with-monitoring
+
+Adds monitoring endpoints for:
+- Health checks
+- Prometheus metrics
+- Update success/failure rates
+- Download statistics
+
+## Production Checklist
+
+Before deploying to production:
+
+- [ ] Implement storage service for your cloud provider
+- [ ] Implement database service for metadata
+- [ ] Configure environment variables
+- [ ] Set up authentication for admin endpoints
+- [ ] Configure HTTPS/TLS
+- [ ] Set up rate limiting
+- [ ] Configure logging (Winston, Pino, etc.)
+- [ ] Set up error tracking (Sentry, etc.)
+- [ ] Configure backup strategy for bundles
+
+## Environment Variables
+
+Templates expect these environment variables:
+
+```env
+# Server
+PORT=3000
+NODE_ENV=production
+
+# Storage (example for S3)
+AWS_REGION=us-east-1
+S3_BUCKET=my-update-bundles
+AWS_ACCESS_KEY_ID=xxx
+AWS_SECRET_ACCESS_KEY=xxx
+
+# Database (example for PostgreSQL)
+DATABASE_URL=postgres://user:pass@host:5432/dbname
+
+# Security
+API_KEY=your-admin-api-key
+SIGNING_PUBLIC_KEY_PATH=./keys/public.pem
+```
+
+## Related Documentation
+
+- [Deployment Guide](./deployment-guide.md) - Full deployment instructions
+- [Security Best Practices](./security-best-practices.md) - Security recommendations
+- [Key Management](./key-management.md) - Managing signing keys

package/docs/reports/COMPLETE_VERIFICATION.md

@@ -17,7 +17,7 @@
 2. **Development Tools** ✅
    - Bundle creation utility (`tools/bundle-creator.js`)
    - Bundle signing tool (`tools/bundle-signer.js`)
-   - CLI tool (`cli/cap-update.js`)
+   - CLI tool (`cli/index.js`)
    - Testing framework with Vitest
    - Unit and integration tests
 

package/docs/reports/PRODUCTION_STATUS.md

@@ -20,7 +20,7 @@ This document summarizes the current production readiness status of the capacito
 - Bundle creation utility (`tools/bundle-creator.js`)
 - Bundle signing tool (`tools/bundle-signer.js`)
 - Minimal backend server template (`backend-template/`)
-- CLI tool for easier usage (`cli/cap-update.js`)
+- CLI tool for easier usage (`cli/index.js`)
 
 ### Core Features ✅
 - Client-side signature verification using Web Crypto API

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "native-update",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "Foundation package for building a comprehensive update system for Capacitor apps. Provides architecture and interfaces but requires backend implementation.",
   "type": "module",
   "main": "dist/plugin.cjs.js",
@@ -89,20 +89,20 @@
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^0.4.4",
-    "@types/node": "^25.0.8",
+    "@types/node": "^25.0.9",
     "@typescript-eslint/eslint-plugin": "^8.53.0",
     "@typescript-eslint/parser": "^8.53.0",
     "@vitest/ui": "^4.0.17",
     "eslint": "^9.39.2",
-    "happy-dom": "^20.1.0",
-    "prettier": "^3.7.4",
+    "happy-dom": "^20.3.1",
+    "prettier": "^3.8.0",
     "rimraf": "^6.1.2",
     "rollup": "^4.55.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
   },
   "peerDependencies": {
-    "@capacitor/core": "^8.0.0"
+    "@capacitor/core": "^8.0.1"
   },
   "capacitor": {
     "ios": {

package/cli/cap-update.js

@@ -1,45 +0,0 @@
-#!/usr/bin/env node
-
-import { Command } from 'commander';
-import { readFileSync } from 'fs';
-import { resolve } from 'path';
-
-const program = new Command();
-const packageJson = JSON.parse(
-  readFileSync(resolve(process.cwd(), 'package.json'), 'utf8')
-);
-
-program
-  .name('cap-update')
-  .description('CLI for Capacitor Native Update')
-  .version('1.0.0');
-
-program
-  .command('init')
-  .description('Initialize update configuration')
-  .option('-s, --server <url>', 'Update server URL')
-  .action((options) => {
-    console.log('Initializing Capacitor Native Update...');
-    console.log('Server:', options.server || 'Not specified');
-    // TODO: Create config file
-  });
-
-program
-  .command('bundle')
-  .description('Create update bundle')
-  .argument('<path>', 'Path to dist directory')
-  .action((path) => {
-    console.log(`Creating bundle from: ${path}`);
-    // TODO: Call bundle creator
-  });
-
-program
-  .command('sign')
-  .description('Sign update bundle')
-  .argument('<bundle>', 'Bundle file path')
-  .action((bundle) => {
-    console.log(`Signing bundle: ${bundle}`);
-    // TODO: Call bundle signer
-  });
-
-program.parse();