native-update 1.0.8 → 1.1.0

package/docs/examples/android-manifest-example.xml

@@ -0,0 +1,77 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- 
+    EXAMPLE: Complete Android Manifest for apps using native-update plugin
+    Location: android/app/src/main/AndroidManifest.xml (in YOUR app, not the plugin)
+    
+    This example shows the correct placement of all required elements for the
+    native-update plugin with background update support.
+-->
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    xmlns:tools="http://schemas.android.com/tools"
+    package="com.yourcompany.yourapp">
+
+    <!-- Permissions are added automatically by the plugin, but listed here for reference -->
+    <!-- These permissions allow the plugin to function properly -->
+    <uses-permission android:name="android.permission.INTERNET" />
+    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
+
+    <application
+        android:allowBackup="true"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/AppTheme">
+
+        <!-- Your main activity and other components -->
+        <activity
+            android:name=".MainActivity"
+            android:label="@string/app_name"
+            android:theme="@style/AppTheme.NoActionBar"
+            android:launchMode="singleTask"
+            android:exported="true">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+
+        <!-- ============================================= -->
+        <!-- REQUIRED FOR NATIVE-UPDATE BACKGROUND UPDATES -->
+        <!-- ============================================= -->
+        
+        <!-- WorkManager Foreground Service -->
+        <!-- This service is REQUIRED for background downloads to work -->
+        <!-- Without it: Downloads will fail with ServiceNotFoundException -->
+        <!-- Purpose: Keeps downloads running when app is in background -->
+        <service
+            android:name="androidx.work.impl.foreground.SystemForegroundService"
+            android:foregroundServiceType="dataSync"
+            tools:node="merge" />
+
+        <!-- Notification Action Receiver -->
+        <!-- This receiver is REQUIRED for notification buttons to work -->
+        <!-- Without it: Update notifications will show but buttons won't work -->
+        <!-- Purpose: Handles "Update Now", "Update Later", and "Dismiss" actions -->
+        <receiver
+            android:name="com.aoneahsan.nativeupdate.NotificationActionReceiver"
+            android:exported="false">
+            <intent-filter>
+                <!-- Action triggered when user taps "Update Now" -->
+                <action android:name="com.aoneahsan.nativeupdate.UPDATE_NOW" />
+                <!-- Action triggered when user taps "Update Later" -->
+                <action android:name="com.aoneahsan.nativeupdate.UPDATE_LATER" />
+                <!-- Action triggered when user dismisses the notification -->
+                <action android:name="com.aoneahsan.nativeupdate.DISMISS" />
+            </intent-filter>
+        </receiver>
+
+        <!-- Other app components like providers, services, etc. -->
+        
+    </application>
+
+</manifest>

package/docs/getting-started/configuration.md

@@ -66,8 +66,9 @@ liveUpdate: {
   serverUrl: 'https://updates.yourserver.com',
   channel: 'production',
 
-  // Security
-  publicKey: 'YOUR_RSA_PUBLIC_KEY',
+  // Security (see Key Management Guide for generating keys)
+  // Generate keys: npx native-update keys generate --type rsa --size 4096
+  publicKey: 'YOUR_RSA_PUBLIC_KEY', // Base64 encoded public key
   requireSignature: true,
   checksumAlgorithm: 'SHA-256', // or 'SHA-512'
 

package/docs/getting-started/installation.md

@@ -98,8 +98,73 @@ This command will:
    ```
 
 3. The plugin automatically adds required permissions to the manifest:
-   - `INTERNET` - For downloading updates
-   - `ACCESS_NETWORK_STATE` - For checking network availability
+   - **`INTERNET`** - Required for downloading update bundles from your server
+   - **`ACCESS_NETWORK_STATE`** - Required to check network availability before downloading
+   - **`WAKE_LOCK`** - Required to keep the device awake during background downloads
+   - **`FOREGROUND_SERVICE`** - Required for showing download progress notifications
+   - **`POST_NOTIFICATIONS`** - Required for update notifications on Android 13+ ([API 33](https://developer.android.com/develop/ui/views/notifications/notification-permission))
+   - **`RECEIVE_BOOT_COMPLETED`** - Required to resume interrupted downloads after device restart
+
+4. **CRITICAL: Android Manifest Configuration for Background Updates**
+
+   If you're using background updates, you **MUST** add these elements to your app's `AndroidManifest.xml` inside the `<application>` tag. Without these, background updates will fail silently:
+
+   ```xml
+   <application>
+       <!-- Your existing application configuration -->
+       
+       <!-- WorkManager Foreground Service (REQUIRED for background downloads) -->
+       <!-- Without this: Background downloads will be killed by the system after ~10 minutes -->
+       <!-- Documentation: https://developer.android.com/topic/libraries/architecture/workmanager/advanced/long-running -->
+       <service
+           android:name="androidx.work.impl.foreground.SystemForegroundService"
+           android:foregroundServiceType="dataSync"
+           tools:node="merge" />
+
+       <!-- Notification Action Receiver (REQUIRED for update notifications) -->
+       <!-- Without this: "Update Now" and "Dismiss" buttons in notifications won't work -->
+       <!-- The receiver handles user actions from update notifications -->
+       <receiver
+           android:name="com.aoneahsan.nativeupdate.NotificationActionReceiver"
+           android:exported="false">
+           <intent-filter>
+               <action android:name="com.aoneahsan.nativeupdate.UPDATE_NOW" />
+               <action android:name="com.aoneahsan.nativeupdate.UPDATE_LATER" />
+               <action android:name="com.aoneahsan.nativeupdate.DISMISS" />
+           </intent-filter>
+       </receiver>
+   </application>
+   ```
+
+   **What happens if you skip this step:**
+   - ❌ Background downloads will be terminated by Android after ~10 minutes
+   - ❌ Update notifications won't display progress
+   - ❌ Notification action buttons won't respond to taps
+   - ❌ Downloads won't resume after app restart
+   - ❌ Users will experience failed or incomplete updates
+
+   **Detailed Explanation of Each Component:**
+
+   - **SystemForegroundService**: Android's WorkManager service that handles long-running background tasks
+     - **Purpose**: Keeps downloads alive when app is backgrounded or device is locked
+     - **`foregroundServiceType="dataSync"`**: Tells Android this service downloads/syncs data
+     - **What breaks without it**: Background downloads crash with `ServiceNotFoundException`
+     - **Reference**: [WorkManager Long-running Workers](https://developer.android.com/topic/libraries/architecture/workmanager/advanced/long-running)
+
+   - **NotificationActionReceiver**: Handles user interactions with update notifications
+     - **`UPDATE_NOW`**: Triggered when user taps "Update Now" - starts immediate installation
+     - **`UPDATE_LATER`**: Triggered when user taps "Update Later" - schedules for later
+     - **`DISMISS`**: Triggered when user dismisses notification - cancels pending update
+     - **What breaks without it**: Buttons appear in notifications but don't do anything when tapped
+     - **Reference**: [Notification Actions](https://developer.android.com/develop/ui/views/notifications/notification-actions)
+
+   - **Security Attributes Explained**:
+     - **`android:exported="false"`**: Prevents other apps from sending intents to your receiver (security best practice)
+     - **`tools:node="merge"`**: Handles conflicts if multiple libraries define the same service
+
+   **Note:** If you're only using immediate (foreground) updates, these additions are optional.
+
+   📋 **[View Complete Android Manifest Example](../examples/android-manifest-example.xml)** - Shows the correct placement of all elements
 
 #### Web Setup
 
@@ -165,6 +230,40 @@ import type {
 
 ## Troubleshooting Installation
 
+### Android Manifest Errors
+
+1. **"AAPT: error: unexpected element <service> found in <manifest>"**
+   - **Cause**: Service/receiver elements placed outside `<application>` tag or in wrong manifest
+   - **Fix**: Add to your **app's** manifest at `android/app/src/main/AndroidManifest.xml`, NOT the plugin's manifest
+   - **Example of CORRECT placement**:
+     ```xml
+     <manifest>
+         <uses-permission ... />
+         <application>
+             <!-- HERE is where service and receiver go -->
+             <service ... />
+             <receiver ... />
+         </application>
+     </manifest>
+     ```
+
+2. **"ServiceNotFoundException" when downloading updates**
+   - **Cause**: Missing WorkManager service declaration
+   - **Symptoms**: App crashes when starting background download
+   - **Fix**: Add the SystemForegroundService to your app's manifest as shown above
+   - **Log message**: `java.lang.IllegalArgumentException: Service not registered: androidx.work.impl.foreground.SystemForegroundService`
+
+3. **Notification buttons don't work**
+   - **Cause**: Missing NotificationActionReceiver declaration
+   - **Symptoms**: Update notification appears but buttons don't respond
+   - **Fix**: Add the receiver with all three action filters to your app's manifest
+   - **Test**: Send a test notification and verify buttons trigger actions
+
+4. **"Permission denied" errors on Android 13+**
+   - **Cause**: Missing runtime permission request for notifications
+   - **Fix**: Request `POST_NOTIFICATIONS` permission at runtime
+   - **Reference**: [Android 13 Notification Permission](https://developer.android.com/develop/ui/views/notifications/notification-permission)
+
 ### Common Issues
 
 1. **"Module not found" error**

package/docs/getting-started/quick-start.md

@@ -345,14 +345,66 @@ async function safeUpdateCheck() {
    });
    ```
 
+## Setting Up Backend & Creating Updates
+
+### Quick Backend Setup
+
+Use our CLI to quickly set up a backend:
+
+```bash
+# Create an Express.js backend with admin dashboard
+npx native-update backend create express --with-admin
+
+# Or create a Firebase Functions backend
+npx native-update backend create firebase --with-monitoring
+
+# Start the development server
+cd native-update-backend
+npm install
+npm run dev
+```
+
+### Creating and Deploying Updates
+
+1. **Generate signing keys** (see [Key Management Guide](../guides/key-management.md) for details):
+   ```bash
+   npx native-update keys generate --type rsa --size 4096
+   ```
+   This creates a private key (keep secret) and public key (add to app config)
+
+2. **Build and create update bundle**:
+   ```bash
+   npm run build
+   npx native-update bundle create ./www --version 1.0.1
+   ```
+
+3. **Sign the bundle**:
+   ```bash
+   npx native-update bundle sign ./update-bundles/bundle-*.zip --key ./keys/private-*.pem
+   ```
+
+4. **Upload via admin dashboard or API**
+
+### Development Server
+
+For local testing:
+```bash
+# Start a local update server
+npx native-update server start --port 3000
+
+# Monitor updates in real-time
+npx native-update monitor --server http://localhost:3000
+```
+
 ## Next Steps
 
 Now that you have the basics working:
 
-1. Set up your update server (see backend-template folder)
+1. Deploy your backend to production
 2. Implement [Security Best Practices](../guides/security-best-practices.md)
 3. Configure [Advanced Options](./configuration.md)
 4. Explore [API Reference](../api/live-update-api.md) for all available methods
+5. See [CLI Reference](../cli-reference.md) for all available commands
 
 ## Quick Reference
 

package/docs/guides/deployment-guide.md

@@ -90,11 +90,13 @@ pm2 startup
 
 ### 1. Production Keys
 
-```typescript
-// Generate RSA keys for production
-const keys = await generateKeyPair();
-// Store private key securely on server
-// Embed public key in app
+```bash
+# Generate RSA keys for production
+npx native-update keys generate --type rsa --size 4096
+
+# This creates:
+# - private-[timestamp].pem (keep secure on CI/CD server)
+# - public-[timestamp].pem (embed in app)
 ```
 
 ### 2. Configure Plugin
@@ -181,10 +183,10 @@ ServerDown:
 npm run build
 
 # Create bundle
-node tools/bundle-creator.js create ./www
+npx native-update bundle create ./www
 
 # Sign bundle
-node tools/bundle-signer.js sign bundle.zip private-key.pem
+npx native-update bundle sign bundle.zip --key private-key.pem
 ```
 
 ### 2. Upload to Server

package/docs/guides/key-management.md

@@ -0,0 +1,284 @@
+# Key Management Guide
+
+This guide explains how to generate, manage, and use cryptographic keys for bundle signing in the Native Update plugin.
+
+## Overview
+
+The Native Update plugin uses public key cryptography to ensure the security and integrity of update bundles. This system prevents tampering and ensures updates come from trusted sources.
+
+### Why Use Cryptographic Signing?
+
+1. **Integrity**: Ensures bundles haven't been modified during transmission
+2. **Authenticity**: Verifies bundles come from your trusted server
+3. **Non-repudiation**: Proves the origin of updates
+4. **Security**: Prevents man-in-the-middle attacks and bundle injection
+
+## Key Generation
+
+### Using the CLI Tool (Recommended)
+
+The easiest way to generate keys is using our CLI tool:
+
+```bash
+# Generate RSA 4096-bit keys (recommended for production)
+npx native-update keys generate --type rsa --size 4096
+
+# Generate RSA 2048-bit keys (faster, still secure)
+npx native-update keys generate --type rsa --size 2048
+
+# Generate EC keys (smaller signatures, modern)
+npx native-update keys generate --type ec --size 256
+
+# Specify output directory
+npx native-update keys generate --output ./my-keys
+```
+
+This will create:
+- `private-{timestamp}.pem` - Keep this SECRET on your server
+- `public-{timestamp}.pem` - Include this in your app
+
+### Manual Key Generation
+
+If you prefer to generate keys manually, you can use OpenSSL:
+
+#### RSA Keys
+
+```bash
+# Generate 4096-bit RSA private key
+openssl genrsa -out private.pem 4096
+
+# Extract public key from private key
+openssl rsa -in private.pem -pubout -out public.pem
+```
+
+#### Elliptic Curve Keys
+
+```bash
+# Generate EC private key (P-256 curve)
+openssl ecparam -genkey -name prime256v1 -out private-ec.pem
+
+# Extract public key
+openssl ec -in private-ec.pem -pubout -out public-ec.pem
+```
+
+## Key Usage
+
+### 1. Store Private Key Securely
+
+The private key must be kept secure on your server:
+
+```bash
+# Set restrictive permissions
+chmod 600 private-*.pem
+
+# Store in secure location
+sudo mv private-*.pem /secure/keys/
+```
+
+**Security Tips:**
+- Never commit private keys to version control
+- Use environment variables or key management services
+- Rotate keys periodically
+- Keep backup copies in secure storage
+
+### 2. Configure Public Key in App
+
+Add the public key to your Capacitor configuration:
+
+```typescript
+// capacitor.config.ts
+import { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  plugins: {
+    NativeUpdate: {
+      publicKey: 'YOUR_BASE64_PUBLIC_KEY_HERE',
+      // ... other config
+    }
+  }
+};
+
+export default config;
+```
+
+To get the base64 version of your public key:
+
+```bash
+# Convert public key to base64
+cat public-*.pem | base64 -w 0 > public-key.b64
+
+# On macOS
+cat public-*.pem | base64 > public-key.b64
+```
+
+### 3. Sign Bundles
+
+Use the private key to sign update bundles:
+
+```bash
+# Sign a bundle
+npx native-update bundle sign ./bundle.zip --key /secure/keys/private.pem
+
+# This creates a signature file alongside the bundle
+```
+
+### 4. Verify Signatures
+
+The plugin automatically verifies signatures using the configured public key. You can manually verify:
+
+```bash
+# Verify a signed bundle
+npx native-update bundle verify ./bundle.zip --key ./public.pem
+```
+
+## Security Best Practices
+
+### Key Storage
+
+1. **Server Side (Private Key)**:
+   - Store in hardware security module (HSM) if possible
+   - Use encrypted storage
+   - Implement access controls
+   - Never expose via API or logs
+
+2. **Client Side (Public Key)**:
+   - Embed in app configuration
+   - Can be safely distributed
+   - Consider certificate pinning for extra security
+
+### Key Rotation
+
+Implement a key rotation strategy:
+
+1. Generate new key pair
+2. Start signing new bundles with new key
+3. Update app with both old and new public keys
+4. Phase out old key after all users update
+5. Remove old public key in future release
+
+### Environment-Specific Keys
+
+Use different keys for different environments:
+
+```typescript
+const config: CapacitorConfig = {
+  plugins: {
+    NativeUpdate: {
+      publicKey: process.env.NODE_ENV === 'production' 
+        ? 'PRODUCTION_PUBLIC_KEY_BASE64'
+        : 'STAGING_PUBLIC_KEY_BASE64',
+    }
+  }
+};
+```
+
+## Implementation Details
+
+### How Signing Works
+
+1. **Bundle Creation**: Your web assets are packaged into a ZIP file
+2. **Hash Generation**: SHA-256 hash of the bundle is calculated
+3. **Signing**: Hash is signed with your private key using RSA-SHA256
+4. **Distribution**: Bundle + signature are uploaded to your server
+
+### How Verification Works
+
+1. **Download**: App downloads bundle and signature
+2. **Hash Calculation**: App calculates SHA-256 hash of downloaded bundle
+3. **Signature Verification**: App uses public key to verify signature matches hash
+4. **Installation**: Bundle is only installed if verification succeeds
+
+### Signature Format
+
+Signatures are base64-encoded for transport:
+
+```json
+{
+  "bundle": "bundle-1.0.1.zip",
+  "signature": "MEUCIQDp3...base64...==",
+  "algorithm": "RSA-SHA256",
+  "timestamp": "2024-01-20T10:30:00Z"
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Signature verification failed"**
+   - Ensure public key in app matches private key used for signing
+   - Check bundle hasn't been modified after signing
+   - Verify base64 encoding is correct
+
+2. **"Invalid key format"**
+   - Keys must be in PEM format
+   - Check for proper headers/footers in key files
+   - Ensure no extra whitespace or characters
+
+3. **"Permission denied" when accessing keys**
+   - Set proper file permissions: `chmod 600 private-*.pem`
+   - Store in accessible location for your server process
+
+### Testing Key Pairs
+
+Test your keys are properly paired:
+
+```bash
+# Create test message
+echo "test message" > test.txt
+
+# Sign with private key
+openssl dgst -sha256 -sign private.pem -out test.sig test.txt
+
+# Verify with public key
+openssl dgst -sha256 -verify public.pem -signature test.sig test.txt
+# Should output: "Verified OK"
+```
+
+## Advanced Topics
+
+### Hardware Security Modules (HSM)
+
+For maximum security, use HSM for key storage:
+
+```javascript
+// Example using AWS KMS
+const AWS = require('aws-sdk');
+const kms = new AWS.KMS();
+
+async function signWithHSM(data) {
+  const params = {
+    KeyId: 'arn:aws:kms:...',
+    Message: data,
+    SigningAlgorithm: 'RSASSA_PKCS1_V1_5_SHA_256'
+  };
+  
+  const result = await kms.sign(params).promise();
+  return result.Signature;
+}
+```
+
+### Certificate Chains
+
+For enterprise deployments, use certificate chains:
+
+```bash
+# Create certificate chain
+cat intermediate.crt root.crt > chain.pem
+
+# Configure in app
+{
+  "certificateChain": "base64_encoded_chain",
+  "publicKey": "base64_encoded_public_key"
+}
+```
+
+## Next Steps
+
+- Review [Security Best Practices](./security-best-practices.md)
+- Implement [Bundle Signing](../BUNDLE_SIGNING.md)
+- Set up [CI/CD Integration](../ci-cd-integration.md)
+
+---
+
+Made with ❤️ by Ahsan Mahmood

package/docs/guides/migration-from-codepush.md

@@ -23,10 +23,14 @@ This guide helps you migrate from Microsoft CodePush to Capacitor Native Update.
 First, you need to set up your own update server:
 
 ```bash
-# Use our backend template
-cd backend-template
+# Create a backend using our templates
+npx native-update backend create express --with-admin
+# or for Firebase
+npx native-update backend create firebase --with-monitoring
+
+cd native-update-backend
 npm install
-npm start
+npm run dev
 ```
 
 ### 2. Update Your App Code
@@ -88,8 +92,8 @@ Replace release process:
 code-push release-react MyApp ios -d Production
 
 # New (Capacitor Native Update)
-node tools/bundle-creator.js create ./www
-node tools/bundle-signer.js sign bundle.zip private-key.pem
+npx native-update bundle create ./www
+npx native-update bundle sign bundle.zip --key private-key.pem
 # Upload to your server
 ```
 

package/docs/guides/testing-guide.md

@@ -120,7 +120,7 @@ try {
 #### Signature Verification
 ```bash
 # Create signed bundle
-node tools/bundle-signer.js sign test-bundle.zip private-key.pem
+npx native-update bundle sign test-bundle.zip --key private-key.pem
 
 # Verify in app
 const isValid = await NativeUpdate.validateUpdate({
@@ -153,10 +153,10 @@ NativeUpdate.addListener('downloadProgress', (progress) => {
 1. **Prepare Test Bundle**
    ```bash
    # Create bundle
-   node tools/bundle-creator.js create ./www
+   npx native-update bundle create ./www
    
    # Sign bundle
-   node tools/bundle-signer.js sign bundle.zip private-key.pem
+   npx native-update bundle sign bundle.zip --key private-key.pem
    
    # Upload to server
    curl -X POST http://localhost:3000/api/updates/upload/update-id \
@@ -299,7 +299,7 @@ jobs:
 ### Bundle Testing
 ```bash
 # Create test bundle
-node tools/bundle-creator.js create ./test-www
+npx native-update bundle create ./test-www
 
 # Verify bundle
 unzip -t test-bundle.zip