native-update 1.4.9 → 2.0.0

package/docs/AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md - Documentation
+
+Agent instructions for maintaining native-update documentation.
+
+## 🔴 3-Day Freshness Rule
+Check and update this file at least every 3 days. See root AGENTS.md.
+
+## Scope
+
+All markdown documentation, guides, API reference, project profiles, knowledge base, and tracker files.
+
+## Key Rules
+
+1. **Documentation-first**: Update docs BEFORE or WITH code changes, never after
+2. **Knowledge base**: Update `/docs/project-knowledge-base/` every 2 weeks minimum
+3. **Project profile**: Update `/docs/project-profiles/` weekly when project is active
+4. **Inventory sync**: When docs are added/removed, update `05-docs-corpus-inventory.md`
+5. **No stale docs**: Every doc must reflect current reality, not historical plans
+
+## When API Changes
+1. Update relevant guides in `docs/features/` or `docs/guides/`
+2. Update `docs/api/` reference
+3. Update `AI-INTEGRATION-GUIDE.md`
+4. Update `CHANGELOG.md`
+5. If breaking: update `MIGRATION.md`
+
+## When Adding New Docs
+1. Place in appropriate subfolder by topic
+2. Update `docs/project-knowledge-base/05-docs-corpus-inventory.md`
+3. Link from relevant parent docs
+4. Include `Last Updated` date at bottom
+
+## Tracker Files
+Located in `docs/tracking/`. Update relevant trackers when completing cross-project work.
+
+---
+
+**Last Updated**: 2026-04-02

package/docs/CHANGELOG.md

@@ -5,6 +5,157 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.0] - 2026-04-18
+
+### Native (Android + iOS)
+- **Boot-time bundle re-verification.** On every cold start the plugin
+  re-hashes the active OTA bundle and compares against the checksum
+  stored at install time. If the host app configured a public key and the
+  bundle carries a signature, the signature is re-verified too. Mismatch
+  triggers an immediate rollback to the previous known-good bundle and
+  emits `updateStateChanged` with `status: 'ROLLBACK'`. Closes an
+  on-disk-tampering gap on rooted/jailbroken devices.
+- **Automatic rollback on crash loop.** Activating a bundle marks it as
+  pending-verify. Each cold start before `notifyAppReady()` fires
+  increments a counter; after 2 failed boots the plugin rolls back to
+  the previous bundle automatically. Catches a bundle that crashes the
+  app before it can tell the plugin it booted cleanly.
+- Bundle metadata now persists the signature alongside checksum so the
+  boot re-verify can run without needing the manifest or a re-download.
+- **iOS zip-slip + zip-bomb protection.** Bundle extraction now inspects
+  every archive entry before writing to disk: rejects symlinks, absolute
+  paths, and any path that resolves outside the destination directory,
+  and caps total uncompressed size at 500 MB. A malicious bundle can no
+  longer overwrite files outside the sandbox or exhaust device storage.
+  (Android does not currently extract bundles in-plugin; when that is
+  added, the same validation must be applied.)
+- **Secure storage is now always on.** Android persists secrets only
+  through `EncryptedSharedPreferences` (Keystore-backed); iOS persists
+  only through the Keychain. The `secureStorage: false` opt-out is
+  removed — passing it is ignored. On web, `initialize()` config is
+  sanitised before write-through to `localStorage`: `apiKey`, top-level
+  and `liveUpdate.publicKey`, and `security.publicKey` are stripped, so
+  a compromised script or stale cache cannot surface the credential.
+  Host apps must pass the apiKey/publicKey on every `initialize()`.
+- **Android background retries are bounded + backoff-aware.** All three
+  enqueue sites (periodic, one-shot, notification-action) now pass
+  `setBackoffCriteria(EXPONENTIAL, 30s)`. The worker itself caps at
+  5 retry attempts per run, so a persistently-failing server can no
+  longer burn battery in a tight retry loop — total wall-clock budget
+  for a failing run is ~15 minutes before falling through to the next
+  scheduled tick.
+- **iOS background-task diagnostics.** `BGTaskScheduler.submit` errors
+  are now classified (`.notPermitted`, `.tooManyPendingTaskRequests`,
+  `.unavailable`) and logged with actionable messages. `.notPermitted`
+  almost always means the host app's `Info.plist` is missing the
+  scheduler identifier — previously a silent failure. We also cancel
+  any prior pending request before resubmitting to dodge the
+  "already-scheduled" edge case observed on a few iOS versions. Host
+  apps must declare `BGTaskSchedulerPermittedIdentifiers` with
+  `com.aoneahsan.nativeupdate.background` in their own Info.plist —
+  the framework's plist does not propagate to the app bundle.
+
+### Security (BREAKING)
+- **Signature verification fails closed.** If the host app configures
+  `publicKey`, `requireSignature`, or `enableSignatureValidation`, a missing
+  signature now throws instead of silently passing. Previously, a manifest
+  with the signature field stripped out would bypass all integrity checks.
+- **Checksum verification fails closed.** `verifyChecksum(data, '')` now
+  throws. Every OTA bundle manifest must ship a SHA-256 checksum; a missing
+  one is treated as tampering.
+- **Monotonic version enforcement persists across reinstalls.** The plugin
+  now records the highest version ever applied per channel in Preferences
+  and refuses to apply any older bundle — even if the active-bundle state
+  was wiped. Closes a downgrade-attack path.
+- **`setUpdateUrl()` is deprecated and ignored at runtime.** The update
+  server URL is fixed at `initialize()` time. Runtime mutation was an XSS
+  attack path (compromised WebView could repoint updates to a hostile
+  host). Re-call `initialize()` to switch servers.
+- **Removed `allowDowngrade` from `UpdateOptions`.** Downgrades are a
+  debug/recovery operation and do not belong in a production option flag.
+- **Removed `enableEncryption`, `encryptionKey`, `encryptionSalt` from
+  the public API.** Bundle encryption was only wired on the web path and
+  never implemented on Android or iOS — the option shipped a false
+  guarantee. Sign bundles (RSA-PSS/ECDSA) and serve them over HTTPS; the
+  plugin's existing verification is the correct integrity primitive.
+
+### Backend (native-update/backend)
+- API key checksum comparison uses `hash_equals` (timing-safe) — closes a
+  byte-by-byte response-time leak on brute-force against short suffixes.
+- Bundle download asserts `build->app_id === authenticated app->id` as
+  defense-in-depth beyond the signed URL.
+- Device identifiers are HMAC-SHA256 hashed (keyed by `APP_KEY`) via an
+  Eloquent mutator before landing in `analytics_events` and
+  `device_activities`. Casual DB access can no longer correlate a row back
+  to a specific device.
+- Build upload rejects versions ≤ current channel head unless an explicit
+  rollback flow is used. Prevents accidental and malicious downgrades on
+  live channels.
+- `GET /api/health` unauth'd endpoint added for Hostinger uptime pings.
+- `/api/v1/*` now carries a route-level `throttle:600,15` as
+  defense-in-depth on top of per-key rate limiting in middleware.
+- `.env.example` tightened for production defaults: `APP_ENV=production`,
+  `APP_DEBUG=false`, `LOG_LEVEL=warning`, `LOG_CHANNEL=daily`,
+  `DB_CONNECTION=mysql`.
+- **Signed bundle URLs include checksum + app_id in their signed payload**
+  and `BundleController::download` re-asserts both against the `Build`
+  row before streaming. A replayed URL whose Build was flipped to
+  archived now returns 403 instead of serving the old bundle.
+- **Signed URL TTL moved from 5 minutes → 30 minutes and made
+  configurable** via `NATIVE_UPDATE_DOWNLOAD_TTL_MIN`. Five minutes
+  frequently expired mid-download on a slow mobile link.
+- **Bundle downloads stream through Laravel**, never redirect to the
+  underlying storage URL — comment enforces the invariant. Keeps auth,
+  rate-limit, and audit in one chokepoint.
+- **Signing-key decryption is now per-request memoised** in
+  `SigningKey::getPrivateKey()`. `rotate()` and `revoke()` clear the
+  cache so stale keys can't leak across a long-running worker.
+
+### Optimization
+- **Resume-download correctness.** `resumeDownload()` now records whether
+  the server actually returned HTTP 206 (Partial Content) and decides
+  whether to concatenate the partial prefix or discard it accordingly.
+  Previously a server that fell back to HTTP 200 (full response)
+  silently produced a corrupted bundle by double-writing the prefix —
+  a latent corruption bug on CDNs that don't honour Range.
+- **Jittered exponential backoff on download retry.** `downloadWithRetry`
+  now adds ±25% random jitter to each retry interval. Avoids the
+  thundering-herd scenario where many clients retry in lockstep after a
+  common failure (CDN blip, server restart) and hammer a recovering
+  server simultaneously.
+- **Auto-cleanup is now the default.** After a successful bundle apply
+  the plugin keeps the last 3 bundles (active + 2 recent) and deletes
+  the rest. Host apps that want the old every-bundle-forever behavior
+  can pass `cleanupOldBundles: false` explicitly.
+
+### Payments (BREAKING)
+- **Stripe + Cashier removed; PayPal (`srmklive/paypal`) takes over.**
+  New `SubscriptionController` exposes `subscribe → activate → cancel /
+  resume / changePlan` with PayPal's approval-URL flow. Webhook endpoint
+  moved from `/api/webhooks/stripe` → `/api/webhooks/paypal`, with a new
+  `PayPalWebhookController` that verifies transmissions via PayPal's
+  own `verifyWebHook` API.
+- New migration `2026_04_18_000001_add_paypal_provider_to_subscriptions`
+  introduces provider-agnostic columns (`provider`,
+  `provider_subscription_id`, `provider_status`, `provider_plan_id`) on
+  `subscriptions`, `subscription_items`, and `users`. Legacy `stripe_*`
+  columns are kept nullable for one release to ease rollback.
+- `.env.example` replaces `STRIPE_*` with `PAYPAL_MODE`,
+  `PAYPAL_LIVE_CLIENT_ID / SECRET / APP_ID`, `PAYPAL_PLAN_PRO`,
+  `PAYPAL_PLAN_ENTERPRISE`, `PAYPAL_WEBHOOK_ID`.
+- `User` model drops the Cashier `Billable` trait and grows an
+  `activeSubscription()` helper against the new schema.
+
+### Migration
+- Apps relying on `allowDowngrade: true` in `UpdateOptions` will fail to
+  apply older bundles. Remove the flag and treat rollback as a separate
+  flow.
+- Apps passing `enableEncryption`, `encryptionKey`, or `encryptionSalt`
+  to `initialize()` or `configure()` will see them silently dropped.
+  Rely on signature + checksum verification for integrity.
+- Apps calling `setUpdateUrl()` at runtime will receive a deprecation
+  warning and the call is a no-op. Pass `serverUrl` to `initialize()`.
+
 ## [1.4.9] - 2026-03-11
 
 ### Added

package/docs/CLAUDE.md

@@ -0,0 +1,101 @@
+# Native Update - Documentation
+
+Comprehensive documentation for the native-update Capacitor plugin and platform.
+
+## 🔴 3-Day Freshness Rule
+Check and update this file at least every 3 days. See root CLAUDE.md.
+
+## Structure
+
+| Folder | Purpose |
+|--------|---------|
+| `api/` | API reference documentation |
+| `architecture/` | System architecture docs |
+| `examples/` | Code examples |
+| `features/` | Feature documentation |
+| `getting-started/` | Quick start guides |
+| `guides/` | How-to guides |
+| `plans/` | Development plans and roadmap |
+| `project-knowledge-base/` | AI-readable domain knowledge |
+| `project-profiles/` | Project profile for portfolio/resume |
+| `reports/` | Status and analysis reports |
+| `security/` | Security documentation |
+| `tracking/` | Progress tracker JSON files |
+
+## Key Reference Files
+
+| File | Purpose |
+|------|---------|
+| `QUICK_START.md` | Getting started guide |
+| `CHANGELOG.md` | Version history |
+| `ROADMAP.md` | Future plans |
+| `MIGRATION.md` | v1 to v2 migration guide |
+| `SECURITY.md` | Security overview |
+| `KNOWN_LIMITATIONS.md` | Current limitations |
+| `TESTING_REQUIREMENTS.md` | Test guidelines |
+| `SERVER_REQUIREMENTS.md` | Backend requirements |
+| `CLI_REFERENCE.md` | CLI command reference |
+
+## Feature Guides
+
+| File | Topic |
+|------|-------|
+| `APP_REVIEW_GUIDE.md` | App review integration |
+| `LIVE_UPDATES_GUIDE.md` | OTA live updates |
+| `NATIVE_UPDATES_GUIDE.md` | App store updates |
+| `BUNDLE_SIGNING.md` | Bundle security signing |
+| `BACKGROUND_UPDATES.md` | Background update processing |
+
+## Project Profile Maintenance Rule
+
+**CRITICAL: Keep the dated project profile file current**
+
+- Canonical location: `/docs/project-profiles/`
+- Filename pattern: `native-update-capacitor-update-platform-project-profile-last-updated-YYYY-MM-DD.md`
+- Update weekly when project is active, or whenever major features, positioning, roadmap, SEO metadata, resume bullets, or portfolio messaging changes
+- Always update inside: `Reference Date`, `Last Updated`, `Update History`
+- Keep only the most recent 10 update-history records
+- All sub-projects with their own `CLAUDE.md` must follow this same rule
+
+## Root Portfolio File Maintenance Rule
+
+- Maintain exactly one root portfolio info file: `NATIVE-UPDATE_portfolio-info_YYYY-MM-DD.md`
+- Refresh only after 7+ days unless a major release or material change happens sooner
+- Keep at most 10 update-history records
+- When portfolio file changes, also update: `README.md`, root `CLAUDE.md`, and the dated project-profile file
+
+## AI Knowledge Base Maintenance Rule
+
+**CRITICAL: Keep `/docs/project-knowledge-base/` current**
+
+- Update every 2 weeks while project is active
+- Also update when: routes, forms, user roles, docs, legal pages, modules, tech stack, integrations, or backend assumptions change
+
+### Required Files (minimum)
+1. `README.md` — Knowledge base index
+2. `01-system-overview.md` — System overview
+3. `02-routes-pages-forms-users.md` — Routes, pages, forms, user roles
+4. `03-tech-stack-modules-services.md` — Tech stack, modules, services
+5. `04-data-models-integrations.md` — Data models, integrations
+6. `05-docs-corpus-inventory.md` — Documentation inventory
+7. `06-operations-testing-legal-content.md` — Operations, testing, legal
+
+### Sync Triggers
+- When `/docs` gains or loses files → update `05-docs-corpus-inventory.md`
+- When website routes/pages/forms change → update `02-routes-pages-forms-users.md`
+- When modules/services/schema/integrations change → update `03-tech-stack-modules-services.md` and `04-data-models-integrations.md`
+- Every file must keep `Reference Date` and `Last Updated` current
+
+## Package Update History
+
+| Date | Updated By | Notes |
+|------|------------|-------|
+| 2026-03-24 | Codex | Refreshed docs, verified package state |
+| 2026-02-02 | Claude | Full update to latest versions |
+
+## FilesHub Rule (inherited)
+All file storage uses FilesHub API. See root CLAUDE.md.
+
+---
+
+**Last Updated**: 2026-04-02

package/docs/MIGRATION.md

@@ -1,5 +1,92 @@
 # Migration Guide
 
+## Upgrading v1 → v2.0.0
+
+v2 is a security-focused hardening release with a handful of breaking
+changes. Every change is either (a) a credential-hardening tightening
+that removes a silent-pass path, or (b) a feature removal for an option
+that was documented but never actually implemented. Typical integrations
+need only 2–3 config edits.
+
+### Required action
+
+#### 1. Re-pass `apiKey` / `publicKey` on every `initialize()`
+
+v1 persisted config (including `apiKey` and `publicKey`) to
+`localStorage` / `SharedPreferences` / `UserDefaults`. v2 strips these
+fields before persistence on every platform. Your app must provide them
+on every `initialize()` call instead of relying on the cached copy.
+
+```ts
+await NativeUpdate.initialize({
+  serverUrl: import.meta.env.VITE_NATIVE_UPDATE_API_URL,
+  apiKey:    import.meta.env.VITE_NATIVE_UPDATE_API_KEY,
+  publicKey: import.meta.env.VITE_NATIVE_UPDATE_PUBLIC_KEY,
+  appId:     'com.your.app',
+  channel:   'production',
+});
+```
+
+If you relied on a "call initialize once, then continue" pattern without
+re-passing the key, sync + download calls will fail with
+"API key not configured" after the first cold start.
+
+#### 2. Remove `enableEncryption`, `encryptionKey`, `encryptionSalt`
+
+These options claimed AES-256-GCM bundle encryption but were only wired
+on the web platform and never on Android/iOS — they shipped a false
+guarantee. v2 removes them from the public API.
+
+#### 3. Remove `allowDowngrade` from `UpdateOptions`
+
+Downgrades are a debug / recovery operation, not a production flag.
+v2 removes the option and always blocks downgrades against the
+persisted high-water mark per channel.
+
+#### 4. Stop calling `setUpdateUrl()` at runtime
+
+`setUpdateUrl()` is deprecated and now a no-op. Server URL is fixed at
+`initialize()` to close an XSS-repoint attack path. Re-call
+`initialize()` with the new config if you legitimately need to switch
+servers.
+
+#### 5. iOS host-app Info.plist for background updates
+
+If you use `enableBackgroundUpdates` on iOS, add to your app's own
+`Info.plist`:
+
+```xml
+<key>UIBackgroundModes</key>
+<array><string>background-app-refresh</string></array>
+<key>BGTaskSchedulerPermittedIdentifiers</key>
+<array><string>com.aoneahsan.nativeupdate.background</string></array>
+```
+
+Without these, iOS silently refuses to register the background task.
+v2 surfaces an actionable error in `backgroundUpdateStatus.lastError`.
+
+### Behaviour that changed (no action needed)
+
+- Signature verification fails closed when a `publicKey` is configured.
+- Active bundle is re-hashed + re-signature-verified on every cold start.
+- 2 failed cold starts without `notifyAppReady()` trigger auto-rollback.
+- 3 most recent bundles kept by default (pass `cleanupOldBundles: false`
+  to opt out).
+- Jittered exponential backoff on retries.
+- Android WorkManager background jobs cap at 5 retries.
+
+### Backend changes (if self-hosting)
+
+- Stripe → PayPal swap via `srmklive/paypal`. Run `composer update`,
+  apply the new migration, set `PAYPAL_*` env vars. See
+  `/docs/deployment/HOSTINGER_DEPLOY.md`.
+- Signed URL TTL moved 5min → 30min, configurable via
+  `NATIVE_UPDATE_DOWNLOAD_TTL_MIN`.
+- Device IDs HMAC-SHA256 hashed at DB write. New rows only — existing
+  rows are not backfilled.
+
+---
+
 ## Migrating from Other Update Solutions
 
 ### From Capacitor Live Updates (Official)

package/docs/README.md

@@ -2,6 +2,17 @@
 
 Welcome to the comprehensive documentation for **Capacitor Native Update**, a complete update lifecycle management solution for Capacitor applications.
 
+## Verified Status
+
+- Last reviewed: `2026-03-25`
+- Current package version: `1.4.9`
+- Test status: `yarn test:run` passed with 81 tests
+- Build status: `yarn build` passed
+- Root package manager: `yarn@4.10.3`
+- Root package workflow is Yarn-only and no longer shells out to npm or pnpm
+- Root portfolio info file: `../NATIVE-UPDATE_portfolio-info_2026-03-25.md`
+- Current dated project profile: `./project-profiles/native-update-capacitor-update-platform-project-profile-last-updated-2026-03-25.md`
+
 > **Dashboard & Management Platform**: [nativeupdate.aoneahsan.com](https://nativeupdate.aoneahsan.com)
 >
 > The platform provides a complete SaaS solution for managing your updates including:
@@ -97,7 +108,7 @@ Consistent API across iOS, Android, and Web platforms with platform-specific opt
 - Capacitor 7.0.0 or higher
 - iOS 13.0+ for iOS apps
 - Android 5.0+ (API level 21) for Android apps
-- Node.js 18+ for development
+- Node.js `>=24.13.0` for development
 
 ## 🤝 Contributing
 
@@ -117,4 +128,4 @@ This project is licensed under the MIT License. See the [LICENSE](../LICENSE) fi
 
 ---
 
-Made with ❤️ by Ahsan Mahmood for the developer community
+Created by Ahsan Mahmood for the developer community.