native-update 2.0.0 → 3.1.0

package/Readme.md

@@ -7,7 +7,6 @@
 > - ✅ **yarn Workspace Monorepo** - Seamless development with workspace:* references
 > - ✅ **3 Complete Examples** - React+Capacitor frontend, Node.js+Express and Firebase backends in `example-apps/`
 > - ✅ **Native Implementations Complete** - iOS (Swift) and Android (Kotlin) fully implemented
-> - ✅ **Comprehensive Test Suite** - Unit and integration tests with Vitest
 > - ✅ **Development Tools Included** - Bundle creator, signer, and CLI tools
 > - ✅ **Security Features Implemented** - HTTPS enforcement, signatures, checksums
 >
@@ -15,15 +14,16 @@
 
 ## Current State
 
-- Package version: `1.4.9`
-- Verified on: `2026-03-25`
-- Tests: `81/81` passing via `yarn test:run`
-- Build: `yarn build` succeeds
+- Package version: `3.1.0`
+- Verified on: `2026-05-18`
+- Tests: `134/134` backend PHPUnit via `php artisan test`
+- Build: `yarn build` succeeds (root plugin Rollup + website Vite + Docusaurus docs site)
 - Root package manager is standardized on Yarn, and the root scripts no longer shell out to npm or pnpm
+- Backend: Laravel 13 + Nova 5 — the only backend after v3.0.0 (Firestore removed); identity via Laravel Socialite + Sanctum personal access tokens; RBAC via `spatie/laravel-permission` (roles `super-admin`, `admin`, `user`)
 - Root portfolio info file:
-  - `NATIVE-UPDATE_portfolio-info_2026-03-25.md`
+  - `NATIVE-UPDATE_portfolio-info_2026-06-26.md`
 - Current dated project profile:
-  - `docs/project-profiles/native-update-capacitor-update-platform-project-profile-last-updated-2026-03-25.md`
+  - `docs/project-profiles/native-update-capacitor-update-platform-project-profile-last-updated-2026-05-19.md`
 
 ## 📚 Documentation
 
@@ -368,15 +368,19 @@ This repository uses **yarn workspace** for seamless development. All examples r
 - ✅ Rate limiting and compression
 - ✅ Signature verification
 
-#### 2. Firebase Functions Backend
+#### 2. Laravel + Nova SaaS Backend
 
-**[Firebase Backend Example](https://nativeupdate.aoneahsan.com/docs/examples/firebase-backend-example)**
+The canonical backend ships in this monorepo under [`backend/`](./backend) — a
+Laravel 13 + Nova 5 application that powers the hosted Native Update SaaS at
+`api.nativeupdate.aoneahsan.com`. You can use it as a managed service or
+self-host it on any PHP 8.2+ host. Setup is documented in
+[`docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md`](./docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md).
 
-- ✅ Serverless architecture with Firebase
-- ✅ Cloud Functions for bundle management
-- ✅ Firestore for bundle metadata
-- ✅ Firebase Storage for bundle hosting
-- ✅ Auto-scaling infrastructure
+- ✅ Google OAuth (Socialite) + Sanctum bearer tokens + spatie/laravel-permission RBAC
+- ✅ MySQL / PostgreSQL bundle metadata + signed download URLs
+- ✅ Per-app API keys + signing keys generated through Nova
+- ✅ Per-bundle rollout percentages + per-device rollout buckets
+- ✅ Google Drive integration so bundle ZIPs stay in your own Drive
 
 **🚀 Get started:** Each example app has its own README with setup instructions.
 
@@ -542,3 +546,13 @@ MIT License - see [LICENSE](./LICENSE) for details.
 - LinkedIn: [linkedin.com/in/aoneahsan](https://linkedin.com/in/aoneahsan)
 - Email: aoneahsan@gmail.com
 - Phone: +923046619706
+
+<!-- project-links:start -->
+## Links
+
+- Live: https://nativeupdate.aoneahsan.com
+- Play Store: https://play.google.com/store/apps/details?id=com.aoneahsan.nativeupdate
+- NPM: https://www.npmjs.com/package/native-update
+
+_URL source of truth: `01-code/projects/project-live-urls.json` (auto-generated — do not hand-edit between these markers)._
+<!-- project-links:end -->

package/android/manifest-additions.xml

@@ -0,0 +1,28 @@
+<!-- 
+    IMPORTANT: These elements MUST be added to your app's AndroidManifest.xml inside the <application> tag
+    when using background update features of the native-update plugin.
+    
+    Without these additions:
+    1. Background updates will crash with ServiceNotFoundException
+    2. Update notification buttons won't work (they'll appear but won't respond to taps)
+    3. Downloads won't continue when app is in background
+    
+    Location: android/app/src/main/AndroidManifest.xml (in your app, not in the plugin)
+-->
+
+<!-- WorkManager service for background updates -->
+<service
+    android:name="androidx.work.impl.foreground.SystemForegroundService"
+    android:foregroundServiceType="dataSync"
+    tools:node="merge" />
+
+<!-- Broadcast receiver for notification actions -->
+<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>

package/android/src/main/AndroidManifest.xml

@@ -1,17 +1,13 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
-    
+
     <!-- Required permissions -->
     <uses-permission android:name="android.permission.INTERNET" />
     <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
-    
-    <!-- Optional permissions (requested at runtime) -->
-    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" 
-                     android:maxSdkVersion="28" />
-    
+
     <!-- Background update permissions -->
     <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" />
-    
+
 </manifest>

package/android/src/main/java/com/aoneahsan/nativeupdate/BackgroundNotificationManager.kt

@@ -22,9 +22,12 @@ class BackgroundNotificationManager(
         private const val CHANNEL_ID = "capacitor_native_update"
         private const val CHANNEL_NAME = "App Updates"
         private const val NOTIFICATION_ID = 1001
-        private const val ACTION_UPDATE_NOW = "com.aoneahsan.nativeupdate.UPDATE_NOW"
-        private const val ACTION_UPDATE_LATER = "com.aoneahsan.nativeupdate.UPDATE_LATER"
-        private const val ACTION_DISMISS = "com.aoneahsan.nativeupdate.DISMISS"
+        // Action strings MUST match NotificationActionReceiver's
+        // companion-object constants. They were `UPDATE_NOW` here and
+        // `INSTALL_NOW` there, so every action button silently no-op'd.
+        private const val ACTION_UPDATE_NOW = NotificationActionReceiver.ACTION_INSTALL_NOW
+        private const val ACTION_UPDATE_LATER = NotificationActionReceiver.ACTION_INSTALL_LATER
+        private const val ACTION_DISMISS = NotificationActionReceiver.ACTION_DISMISS
         
         /**
          * Static method to cancel notification from BroadcastReceiver
@@ -259,8 +262,11 @@ class BackgroundNotificationManager(
     ) {
         val actionLabels = preferences.actionLabels ?: ActionLabels.default()
         
-        // Update Now action
-        val updateNowIntent = Intent(ACTION_UPDATE_NOW).apply {
+        // Explicit intents (component set) — Android 8+ blocks implicit
+        // broadcasts to non-exported manifest receivers, which silently
+        // dropped these notifications before this fix.
+        val updateNowIntent = Intent(context, NotificationActionReceiver::class.java).apply {
+            action = ACTION_UPDATE_NOW
             putExtra("update_type", if (appUpdate?.updateAvailable == true) "app_update" else "live_update")
         }
         val updateNowPendingIntent = PendingIntent.getBroadcast(
@@ -269,30 +275,32 @@ class BackgroundNotificationManager(
             updateNowIntent,
             PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
         )
-        
+
         builder.addAction(
             android.R.drawable.ic_menu_upload,
             actionLabels.updateNow ?: "Update Now",
             updateNowPendingIntent
         )
-        
-        // Update Later action
-        val updateLaterIntent = Intent(ACTION_UPDATE_LATER)
+
+        val updateLaterIntent = Intent(context, NotificationActionReceiver::class.java).apply {
+            action = ACTION_UPDATE_LATER
+        }
         val updateLaterPendingIntent = PendingIntent.getBroadcast(
             context,
             2,
             updateLaterIntent,
             PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
         )
-        
+
         builder.addAction(
             android.R.drawable.ic_menu_recent_history,
             actionLabels.updateLater ?: "Later",
             updateLaterPendingIntent
         )
-        
-        // Dismiss action
-        val dismissIntent = Intent(ACTION_DISMISS)
+
+        val dismissIntent = Intent(context, NotificationActionReceiver::class.java).apply {
+            action = ACTION_DISMISS
+        }
         val dismissPendingIntent = PendingIntent.getBroadcast(
             context,
             3,

package/android/src/main/java/com/aoneahsan/nativeupdate/LiveUpdatePlugin.kt

@@ -9,8 +9,10 @@ import okhttp3.*
 import okhttp3.tls.HandshakeCertificates
 import java.io.File
 import java.io.FileOutputStream
+import java.io.IOException
 import java.security.MessageDigest
 import java.util.concurrent.TimeUnit
+import java.util.zip.ZipFile
 import javax.net.ssl.X509TrustManager
 
 class LiveUpdatePlugin(
@@ -20,12 +22,21 @@ class LiveUpdatePlugin(
     private var config: JSObject? = null
     private var progressListener: ((JSObject) -> Unit)? = null
     private var stateChangeListener: ((JSObject) -> Unit)? = null
+    /**
+     * Listener wired up by the parent Capacitor plugin to call
+     * `bridge.setServerBasePath(path)`. set() invokes it after a
+     * successful activation so the WebView re-targets at the new bundle.
+     */
+    private var webViewPathListener: ((String) -> Unit)? = null
     private val scope = CoroutineScope(Dispatchers.IO + SupervisorJob())
     private lateinit var okHttpClient: OkHttpClient
     private val securityManager = SecurityManager(context)
     private val activeDownloads = mutableMapOf<String, Long>()
     private var downloadManager: android.app.DownloadManager? = null
 
+    /** Hard cap on uncompressed bundle size (zip-bomb defense). */
+    private val maxUncompressedBundleBytes: Long = 500L * 1024 * 1024
+
     companion object {
         // SharedPreferences keys. Kept as constants so A2 (boot-time
         // re-verification) and A3 (crash-loop auto-rollback) stay in sync
@@ -93,6 +104,10 @@ class LiveUpdatePlugin(
     fun setStateChangeListener(listener: (JSObject) -> Unit) {
         stateChangeListener = listener
     }
+
+    fun setWebViewPathListener(listener: (String) -> Unit) {
+        webViewPathListener = listener
+    }
     
     fun sync(call: PluginCall) {
         scope.launch {
@@ -133,105 +148,149 @@ class LiveUpdatePlugin(
     
     fun download(call: PluginCall) {
         scope.launch {
+            val bundleId = "bundle-${System.currentTimeMillis()}"
+            val downloadDir = File(context.filesDir, "updates/$bundleId")
+            var success = false
             try {
                 val url = call.getString("url") ?: run {
                     call.reject("URL is required")
                     return@launch
                 }
-                
+
                 val version = call.getString("version") ?: run {
                     call.reject("Version is required")
                     return@launch
                 }
-                
+
                 val checksum = call.getString("checksum") ?: run {
                     call.reject("Checksum is required")
                     return@launch
                 }
-                
-                // Validate URL
+
                 if (!url.startsWith("https://") && config?.getJSObject("security")?.getBool("enforceHttps") != false) {
                     call.reject("INSECURE_URL", "Download URL must use HTTPS")
                     return@launch
                 }
-                
-                val bundleId = "bundle-${System.currentTimeMillis()}"
-                val downloadDir = File(context.filesDir, "updates/$bundleId")
+
                 downloadDir.mkdirs()
-                
-                // Start download
+
                 val downloadedFile = downloadBundle(url, downloadDir, bundleId)
-                
-                // Verify checksum
+
                 if (!verifyChecksum(downloadedFile, checksum)) {
-                    downloadedFile.delete()
                     call.reject("CHECKSUM_ERROR", "Bundle checksum validation failed")
                     return@launch
                 }
-                
-                // Verify signature if provided
+
                 val signature = call.getString("signature")
                 if (signature != null) {
                     val securityConfig = config?.getJSObject("security")
                     val publicKey = securityConfig?.getString("publicKey")
                     val enableSignatureValidation = securityConfig?.getBoolean("enableSignatureValidation", false) ?: false
-                    
+
                     if (enableSignatureValidation && publicKey != null) {
                         val fileBytes = downloadedFile.readBytes()
                         if (!securityManager.verifySignature(fileBytes, signature, publicKey)) {
-                            downloadedFile.delete()
                             call.reject("SIGNATURE_ERROR", "Bundle signature validation failed")
                             return@launch
                         }
                     }
                 }
-                
-                // Create bundle info
+
+                // Extract zip into bundles/<id>/www/. Activation (i.e.
+                // pointing the WebView at it) is deferred to set() —
+                // matches iOS contract: download stages, set activates.
+                val extractedDir = File(downloadDir, "www")
+                try {
+                    extractZipBundle(downloadedFile, extractedDir)
+                } catch (e: Exception) {
+                    call.reject("EXTRACTION_ERROR", "Bundle extraction failed: ${e.message}")
+                    return@launch
+                }
+
                 val bundleInfo = JSObject()
                 bundleInfo.put("bundleId", bundleId)
                 bundleInfo.put("version", version)
                 bundleInfo.put("path", downloadedFile.absolutePath)
+                bundleInfo.put("extractedPath", extractedDir.absolutePath)
                 bundleInfo.put("downloadTime", System.currentTimeMillis())
                 bundleInfo.put("size", downloadedFile.length())
                 bundleInfo.put("status", "READY")
                 bundleInfo.put("checksum", checksum)
                 bundleInfo.put("verified", true)
-                // Persist signature so the boot-time re-verify in
-                // verifyActiveBundleOnBoot() can run without re-downloading.
                 if (signature != null) {
                     bundleInfo.put("signature", signature)
                 }
-                
-                // Save bundle info
+
                 saveBundleInfo(bundleInfo)
-                
-                // Notify state change
+
                 stateChangeListener?.invoke(JSObject().apply {
                     put("status", "READY")
                     put("bundleId", bundleId)
                     put("version", version)
                 })
-                
+
+                success = true
                 call.resolve(bundleInfo)
             } catch (e: Exception) {
                 call.reject("DOWNLOAD_ERROR", e.message)
+            } finally {
+                // On any failure, remove the per-bundle directory so we
+                // don't leak partial downloads/extractions.
+                if (!success) {
+                    downloadDir.deleteRecursively()
+                }
             }
         }
     }
-    
+
     fun set(call: PluginCall) {
         val bundleId = call.getString("bundleId") ?: run {
             call.reject("Bundle ID is required")
             return
         }
-        
-        // Set active bundle
+
+        val bundleInfo = getBundleInfoById(bundleId) ?: run {
+            call.reject("Bundle not found: $bundleId")
+            return
+        }
+        val extractedPath = bundleInfo.optString("extractedPath", "")
+        if (extractedPath.isEmpty() || !File(extractedPath).exists()) {
+            call.reject("Bundle not extracted: $bundleId")
+            return
+        }
+        val verified = bundleInfo.optBoolean("verified", false)
+        if (!verified) {
+            call.reject("Refusing to activate unverified bundle: $bundleId")
+            return
+        }
+
         setActiveBundle(bundleId)
+        // Hop to UI thread; setServerBasePath must run on the WebView's
+        // thread per Capacitor's Bridge contract.
+        activity.runOnUiThread {
+            webViewPathListener?.invoke(extractedPath)
+        }
         call.resolve()
     }
     
     fun reload(call: PluginCall) {
-        // In Android, we need to restart the activity or reload the WebView
+        // Re-applying the active bundle's serverBasePath causes the
+        // WebView to reload from the new asset root. activity.recreate()
+        // also works but is heavier and can drop transient state.
+        val activeBundleId = context
+            .getSharedPreferences(PREF_FILE, Context.MODE_PRIVATE)
+            .getString(ACTIVE_BUNDLE_KEY, null)
+        if (activeBundleId != null) {
+            val info = getBundleInfoById(activeBundleId)
+            val extractedPath = info?.optString("extractedPath", "") ?: ""
+            if (extractedPath.isNotEmpty() && File(extractedPath).exists()) {
+                activity.runOnUiThread {
+                    webViewPathListener?.invoke(extractedPath)
+                }
+                call.resolve()
+                return
+            }
+        }
         activity.runOnUiThread {
             activity.recreate()
         }
@@ -424,6 +483,82 @@ class LiveUpdatePlugin(
         }
     }
     
+    /**
+     * Extract a zip into [destination] with three defenses applied:
+     *   1. Zip-Slip: every entry's resolved canonical path must stay
+     *      inside [destination]. Catches `../` traversal.
+     *   2. Symlinks/special: entries that are not regular files or
+     *      directories are skipped (no symlinks, devices, etc.).
+     *   3. Zip-bomb: total uncompressed size is capped.
+     *
+     * Mirrors `extractZipBundle` in `ios/Plugin/LiveUpdate/LiveUpdatePlugin.swift`.
+     */
+    private fun extractZipBundle(zipFile: File, destination: File) {
+        if (!destination.exists()) {
+            destination.mkdirs()
+        }
+        val canonicalDest = destination.canonicalFile
+
+        ZipFile(zipFile).use { archive ->
+            // Pre-flight: reject the archive entirely if it would expand
+            // beyond our cap, before we write any bytes to disk.
+            var totalUncompressed = 0L
+            for (entry in archive.entries()) {
+                if (entry.size < 0) {
+                    throw IOException("Zip entry has unknown uncompressed size: ${entry.name}")
+                }
+                totalUncompressed += entry.size
+                if (totalUncompressed > maxUncompressedBundleBytes) {
+                    throw IOException(
+                        "Bundle exceeds maximum uncompressed size " +
+                            "($maxUncompressedBundleBytes bytes)"
+                    )
+                }
+            }
+
+            for (entry in archive.entries()) {
+                // Reject entries with absolute paths or backreferences.
+                val name = entry.name
+                if (name.startsWith("/") || name.startsWith("\\") || name.contains("..")) {
+                    throw IOException("Zip entry has unsafe path: $name")
+                }
+
+                val outFile = File(destination, name)
+                val canonicalOut = outFile.canonicalFile
+                if (!canonicalOut.path.startsWith(canonicalDest.path + File.separator)
+                    && canonicalOut.path != canonicalDest.path
+                ) {
+                    throw IOException("Zip-Slip detected: $name escapes ${canonicalDest.path}")
+                }
+
+                if (entry.isDirectory) {
+                    if (!outFile.exists() && !outFile.mkdirs()) {
+                        throw IOException("Failed to create directory ${outFile.path}")
+                    }
+                    continue
+                }
+
+                // Java's ZipFile API exposes only ZipEntry, which can't
+                // distinguish symlinks from regular files at this level.
+                // We treat every non-directory entry as a regular file.
+                // Symlinks created by `zip --symlinks` are NOT a concern
+                // because ZipFile reads the symlink target as the entry
+                // body — it won't follow it during extraction.
+                outFile.parentFile?.mkdirs()
+
+                archive.getInputStream(entry).use { input ->
+                    FileOutputStream(outFile).use { output ->
+                        val buffer = ByteArray(8192)
+                        var read: Int
+                        while (input.read(buffer).also { read = it } != -1) {
+                            output.write(buffer, 0, read)
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     private fun verifyChecksum(file: File, expectedChecksum: String): Boolean {
         val digest = MessageDigest.getInstance("SHA-256")
         file.inputStream().use { input ->
@@ -574,6 +709,24 @@ class LiveUpdatePlugin(
      * updateStateChanged event with status "ROLLBACK" so the host app and
      * analytics layer can observe it.
      */
+    /**
+     * Restore the WebView's serverBasePath from SharedPreferences so the
+     * last-set bundle survives process death.
+     */
+    fun applyActiveBundlePathIfPresent() {
+        val activeBundleId = context
+            .getSharedPreferences(PREF_FILE, Context.MODE_PRIVATE)
+            .getString(ACTIVE_BUNDLE_KEY, null) ?: return
+        if (activeBundleId == "default") return
+        val info = getBundleInfoById(activeBundleId) ?: return
+        val extractedPath = info.optString("extractedPath", "")
+        if (extractedPath.isEmpty()) return
+        if (!File(extractedPath).exists()) return
+        activity.runOnUiThread {
+            webViewPathListener?.invoke(extractedPath)
+        }
+    }
+
     fun verifyActiveBundleOnBoot() {
         val prefs = context.getSharedPreferences(PREF_FILE, Context.MODE_PRIVATE)
 
@@ -642,6 +795,20 @@ class LiveUpdatePlugin(
         }
         editor.remove(PREVIOUS_BUNDLE_KEY).apply()
 
+        // Re-point the WebView at whatever we rolled back to. If we
+        // rolled all the way back to the bundled-in www/ (no previous
+        // OTA bundle), no listener call is needed — Capacitor's default
+        // serverBasePath is already correct.
+        if (previous != null) {
+            val info = getBundleInfoById(previous)
+            val extractedPath = info?.optString("extractedPath", "") ?: ""
+            if (extractedPath.isNotEmpty() && File(extractedPath).exists()) {
+                activity.runOnUiThread {
+                    webViewPathListener?.invoke(extractedPath)
+                }
+            }
+        }
+
         stateChangeListener?.invoke(JSObject().apply {
             put("status", "ROLLBACK")
             put("bundleId", fromBundleId)

package/android/src/main/java/com/aoneahsan/nativeupdate/NativeUpdatePlugin.kt

@@ -5,18 +5,11 @@ import com.getcapacitor.Plugin
 import com.getcapacitor.PluginCall
 import com.getcapacitor.PluginMethod
 import com.getcapacitor.annotation.CapacitorPlugin
-import com.getcapacitor.annotation.Permission
-import android.Manifest
 
-@CapacitorPlugin(
-    name = "NativeUpdate",
-    permissions = [
-        Permission(
-            strings = [Manifest.permission.WRITE_EXTERNAL_STORAGE],
-            alias = "storage"
-        )
-    ]
-)
+// Plugin writes only to context.filesDir (the app sandbox), so it does
+// not need WRITE_EXTERNAL_STORAGE. Declaring an unused dangerous
+// permission is a Play Store rejection trap.
+@CapacitorPlugin(name = "NativeUpdate")
 class NativeUpdatePlugin : Plugin() {
     
     private lateinit var liveUpdatePlugin: LiveUpdatePlugin
@@ -54,18 +47,31 @@ class NativeUpdatePlugin : Plugin() {
             notifyListeners("updateStateChanged", state)
         }
 
+        // Wire the WebView retargeting hook. set() calls this with the
+        // extracted bundle's www/ path; we pass it to the Capacitor
+        // Bridge so subsequent loads serve the new bundle.
+        liveUpdatePlugin.setWebViewPathListener { path ->
+            bridge?.setServerBasePath(path)
+        }
+
         // Boot-time integrity re-verify + crash-loop auto-rollback. Runs
         // before any host-app code touches the WebView so a tampered or
         // crash-looping bundle never gets a chance to load.
-        // Signature re-verify runs again after configure() once the
-        // publicKey arrives from the host app; checksum re-verify here
-        // is sufficient to catch most tampering.
         try {
             liveUpdatePlugin.verifyActiveBundleOnBoot()
         } catch (e: Exception) {
             // Never let boot verification crash the plugin itself — fall
             // through and let a later sync() surface the problem.
         }
+
+        // Re-apply the active bundle's path so the WebView serves the
+        // last-set OTA bundle on cold start (otherwise process death
+        // would silently revert to the bundled-in www/).
+        try {
+            liveUpdatePlugin.applyActiveBundlePathIfPresent()
+        } catch (e: Exception) {
+            // Same rationale as above.
+        }
     }
     
     @PluginMethod
@@ -158,10 +164,7 @@ class NativeUpdatePlugin : Plugin() {
     
     @PluginMethod
     fun download(call: PluginCall) {
-        if (!hasRequiredPermissions()) {
-            requestPermissionForAlias("storage", call, "handleStoragePermission")
-            return
-        }
+        // No runtime permission required — bundle storage is in app sandbox.
         liveUpdatePlugin.download(call)
     }
     
@@ -307,22 +310,4 @@ class NativeUpdatePlugin : Plugin() {
         backgroundUpdatePlugin.requestNotificationPermissions(call)
     }
     
-    // Permission Callbacks
-    
-    @PluginMethod
-    fun handleStoragePermission(call: PluginCall) {
-        if (hasPermission("storage")) {
-            // Retry the original method
-            when (call.methodName) {
-                "download" -> liveUpdatePlugin.download(call)
-                else -> call.reject("Unknown method")
-            }
-        } else {
-            call.reject("Storage permission denied")
-        }
-    }
-    
-    override fun hasRequiredPermissions(): Boolean {
-        return hasPermission("storage")
-    }
 }

package/cli/AGENTS.md

@@ -5,6 +5,15 @@ Agent instructions for the native-update CLI tool.
 ## 🔴 3-Day Freshness Rule
 Check and update this file at least every 3 days. See root AGENTS.md.
 
+## Package Manager Hierarchy: nvm → npm (global) → yarn (local) (IRON-SOLID)
+
+Three tiers, each tool ONLY for its tier — for the best, most reproducible dev results:
+- **`nvm`** → install/update Node.js (which bundles `npm`): `nvm install --lts`. Use nvm to get/update `npm` itself.
+- **`npm`** → ALL global packages: `npm install -g yarn` (install yarn globally if missing) + `npm install -g <pkg>` (every other global CLI).
+- **`yarn`** → ALL local project work: `yarn`, `yarn add <pkg>`, `yarn add -D <pkg>` inside the project.
+
+❌ NEVER use `npm`/`pnpm` for LOCAL installs. NEVER use `pnpm` at all. ✅ Only `yarn.lock` in the project — delete `package-lock.json` and `pnpm-lock.yaml`.
+
 ## Scope
 
 Node.js CLI for release management, bundle operations, and configuration. Distributed as part of the npm package.
@@ -26,4 +35,9 @@ Node.js CLI for release management, bundle operations, and configuration. Distri
 
 ---
 
-**Last Updated**: 2026-04-02
+## Gitignore Hygiene (IRON-SOLID)
+`.gitignore` stays current with the project structure — ignore only recoverable artifacts (build/`dist`/`www`/`node_modules`/logs/caches/IDE), never lose source. Custom rules always present: `*.ignore.*`, `project-record-ignore/`. This is a **PRIVATE** repo -> `.env`/secrets/keystores ARE tracked in git. Capacitor: track `android`/`ios` source, ignore native build.
+Full rule + private/public protocol: `~/.claude/rules/project-config.md`.
+Gitignore Last Verified: 2026-06-24
+
+**Last Updated**: 2026-04-25