native-update 1.4.9 → 3.1.0

package/docs/CHANGELOG.md

@@ -5,6 +5,281 @@ 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).
 
+## [3.1.0] - 2026-07-02
+
+### Added
+- **`exports` map in package.json.** Modern conditional exports
+  (`types`/`import`/`require`) with `./dist/*` and `./cli/*` wildcard
+  passthrough so existing deep imports keep resolving. Legacy
+  `main`/`module`/`types`/`unpkg` fields retained.
+- **`website/.env.production`.** Production builds now always bake the
+  production backend URL; the dev `.env` can safely point at localhost.
+- **Composite index `builds(app_id, channel, status, created_at)`.**
+  Covers the update-check lookup's sort; removes a filesort from the
+  hottest query.
+
+### Changed
+- **Update-check hot path (backend).** The two per-request DB writes
+  (device activity + analytics event) now run after the response is
+  sent (`dispatch(...)->afterResponse()`), and the latest-build lookup
+  is cached for 45s with model-event invalidation. Rollout bucketing
+  stays per-device and uncached.
+- **`analytics:cleanup` now also prunes `analytics_events`** in 5000-row
+  chunks (previously only device-activity rows; the events table grew
+  unboundedly).
+- **Web validateUpdate() reuses downloaded bundle bytes.** Validating a
+  bundle right after `download()` no longer re-downloads it to hash.
+- **Landing page animation engine loads lazily** (LazyMotion): ~44 KB
+  of framer-motion moves off the first-paint critical path.
+- **Firebase Hosting config consolidated** to the repo root with
+  long-lived immutable caching for hashed assets and revalidation for
+  HTML.
+- CORS `supports_credentials` disabled (bearer-token auth needs no
+  credentialed CORS).
+
+### Removed
+- 9 dead env keys from `website/.env` (Firebase-era), 10 commented-out
+  debug lines in `src/web.ts`, 2 framework scaffold test files.
+
+### Fixed
+- Doc drift: backend is Laravel 13 (not 11); the test suite is PHPUnit
+  (not Pest); canonical backend host is `nativeupdatebe.aoneahsan.com`.
+
+## [3.0.1] - 2026-05-11
+
+### Added
+- **Documentation site.** A new public Docusaurus documentation site
+  ships alongside the marketing site. 58 pages total: SDK reference
+  (23), CLI reference (9), Backend setup (5), Platform guides (3),
+  Tutorials (2), How-to guides (6), Concepts (6), Getting Started (2),
+  About + intro pages. Full Diátaxis coverage. Lives in the sibling
+  `native-update-docs/` repository; deployed to Firebase Hosting at
+  `docs.nativeupdate.aoneahsan.com`. Discovery files (`robots.txt`
+  with 30+ AI-bot allowlist, `llms.txt`, `llms-full.txt`, `humans.txt`,
+  `.well-known/security.txt`, `sitemap-index.json`, `sitemap.xml`)
+  and 3 JSON-LD blocks per page (WebSite, SoftwareApplication,
+  Organization) for AI-search citability.
+- **`docs/security/PRE-LAUNCH-PENTEST-CHECKLIST.md`.** 10-section
+  DIY security checklist covering dep hygiene, authentication,
+  authorization, CORS/CSRF, bundle integrity, file safety, data
+  handling, operational safety, mobile platform integration,
+  9 specific attack paths, and a final sanity sweep.
+- **`docs/PERFORMANCE.md` + `tools/bench/`.** Vitest microbench
+  scaffold for the SHA-256 checksum and RSA-SHA256 signature hot
+  paths, with calibration targets and a regression-investigation
+  workflow.
+- **CI: example-bundle workflow.** `.github/workflows/example-bundle.yml`
+  builds, signs, and attaches an OTA bundle from `example-apps/react-capacitor`
+  to each GitHub Release. Also runs weekly as a drift-detection canary.
+- **Example-app capability cards.** `example-apps/react-capacitor/src/App.tsx`
+  now demonstrates App Update (`getAppUpdateInfo` + `openAppStore`),
+  App Review (`canRequestReview` + `requestReview`), and Background
+  Update (toggle with `allowMeteredConnection` + `nextCheckTime`)
+  alongside the existing Live Update flow. One section per feature
+  area.
+
+### Fixed
+- **`website/src/pages/ExamplesPage.tsx`.** Removed the stale third
+  example card advertising the `example-apps/firebase-backend`
+  directory, which was deleted in v3.0.0. The GitHub source link
+  404'd and the description ("Firestore manifests") contradicted the
+  website's own v3 architecture rule.
+
+### Documentation
+- **`docs/project-audit/MARKETING-WEBSITE-FINDINGS-2026-05-11.md`**
+  produced by the production-readiness audit Batch 9 sweep. Documents
+  3 deferred follow-ups (stale MDX docs mirror, HomePage missing
+  Screenshots/Demo section, DocsPage size violation) and 7 surfaces
+  confirmed healthy.
+- **`docs/MARKETING_WEBSITE_TRACKER.md`** annotated as SUPERSEDED with
+  a redirect block to the new findings doc.
+- **`example-apps/react-capacitor/README.md`** documents the React 18
+  vs 19 version-choice reasoning (the plugin is React-version-agnostic;
+  the example pins React 18 to maximise readable audience).
+
+### Closed
+- **Production-readiness audit (10 batches)** initiated 2026-05-08 is
+  complete as of 2026-05-11. Authoritative tracker:
+  `docs/tracking/production-readiness-audit-tracker.json`. The flow
+  enters a 7-day cooldown; next allowed re-run 2026-05-18.
+
+## [3.0.0] - 2026-05-04
+
+### Removed (BREAKING)
+- **Firestore backend.** `backendType: 'firestore'` and the
+  `firestore: { … }` config field are gone. The plugin now speaks HTTP
+  to a single backend (the hosted Native Update SaaS / Laravel
+  reference implementation in `backend/`). Apps using the Firestore
+  branch must switch to `serverUrl` + `apiKey` — see
+  [MIGRATION.md](./MIGRATION.md#upgrading-v2--v300).
+- **`src/firestore/` module.** `FirestoreClient`, `ManifestReader`,
+  `firestore.rules`, `firestore.indexes.json`, the schema types, and
+  the `FirestoreConfig` public export are removed.
+- **`example-apps/firebase-backend/`.** The standalone Firebase Cloud
+  Functions example is removed; `example-apps/node-express/` is the
+  reference HTTP implementation of the `/v1/updates/check` contract.
+
+### Changed
+- Rollout / device-info / update-check types moved to
+  `src/types/rollout.ts` and are re-exported from the package root.
+  `FirestoreTimestamp` is replaced by `RolloutTimestamp` (`number |
+  string | Date`) with a `toEpochMs()` helper.
+- Website auth-service drops the Firestore user-profile mirror. The
+  Laravel `ValidateFirebaseToken` middleware already upserts the user
+  record from verified token claims on every authenticated request, so
+  the client mirror was redundant.
+
+## [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-25

package/docs/MANUAL-TASKS.md

@@ -0,0 +1,17 @@
+# Manual / User-Only Tasks — Native Update
+> The ONE place for everything only you (the human) can do. Fixed path: docs/MANUAL-TASKS.md.
+> Global spec: ~/.claude/rules/manual-tasks.md.   Last updated: 2026-07-02
+
+## ⏳ Pending manual tasks
+
+| # | Task | Why only you | Detail | Status |
+|---|------|--------------|--------|--------|
+| 1 | 🔴 **URGENT — production backend is DOWN.** Every route on `https://nativeupdatebe.aoneahsan.com` returns HTTP 500 (verified 2026-07-02: root, `/api/v1/updates/check`, `/api/auth/google/redirect`). Dashboard sign-in and mobile update checks are broken in production right now. | Needs Hostinger SSH + server logs | 1) SSH in, read `storage/logs/laravel-*.log` to find the fatal (likely PHP version — **Laravel 13 requires PHP ≥ 8.3**; or a missing `.env` key / uncached config). 2) Deploy the fresh zip from `production-deploy/` per `docs/deployment/HOSTINGER_DEPLOY.md` §6 + §9: unzip → `composer install --no-dev --optimize-autoloader` → `php artisan migrate --force` (applies the new covering index) → `php artisan config:cache && route:cache && view:cache` → `nova:publish`. 3) Confirm the `schedule:run` cron (§5) exists. 4) Smoke: `curl https://nativeupdatebe.aoneahsan.com/api/health`. | ☐ Not started |
+| 2 | Verify the backend **Laravel 11→13 + spatie-permission 6→8** upgrade against the real production DB | Needs the configured MySQL (agent runs tests only on sqlite `:memory:`) | Agent already runs the full suite locally: **134 PHPUnit tests pass** (`cd backend && php artisan test`, sqlite in-memory — all migrations incl. the new `builds_channel_lookup_idx` apply cleanly). Remaining for you: `php artisan migrate --force` against production MySQL (review spatie v8 changes: `php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"` if prompted), then smoke-test sign-in + RBAC + a build upload. | ☐ Not started |
+| 3 | Ensure production server runs **PHP ≥ 8.3** and **Node ≥ 24.16.0** | Server/host change | Laravel 13 requires PHP 8.3+ (hPanel → PHP Configuration). `engines.node` is ≥24.16.0 across all units (the published `native-update@3.1.0` declares this floor too). The current 500 is very likely a PHP-version mismatch — check this first. | ☐ Not started |
+| 4 | Deploy the Docusaurus docs site (`native-update-docs/`) | Needs Firebase Hosting auth | `cd native-update-docs && yarn build` → `yarn firebase:deploy`. Runbook: `native-update-docs/DEPLOY.md`. (This repo's marketing site + dashboard were deployed by the agent — see Completed.) | ☐ Not started |
+| 5 | On-device OTA verification (Android + iOS) | Device-only; agent cannot run emulators/`cap run` | Per `docs/CLAUDE.md` Bundle/OTA Release Safety: test bundles on both platforms, verify checksum validation + rollback + background-update behavior before any live release. | ☐ Not started |
+
+## ✅ Completed manual tasks
+
+(none yet — npm publish + website deploy pending this session's Step F)

package/docs/MARKETING_WEBSITE_TRACKER.md

@@ -1,8 +1,24 @@
 # Marketing Website - Progress Tracker
 
 **Created:** 2025-12-27
-**Last Updated:** 2025-12-27
-**Status:** 🔴 Not Started
+**Last Updated:** 2025-12-27 (stale — see note below)
+**Status:** 📦 SUPERSEDED
+
+---
+
+## ⚠️ Stale tracker — superseded as of 2026-05-11
+
+This file is a **pre-launch planning artifact** from December 2025. It was never updated as features actually shipped. The 236 unchecked `[ ]` items below do NOT reflect the current state of the live website — most of them correspond to features that are already in production at https://nativeupdate.aoneahsan.com and in the `website/` directory of this repo.
+
+**Where to look instead:**
+
+- For genuine rendered-on-live-pages gaps as of 2026-05-11, see [docs/project-audit/MARKETING-WEBSITE-FINDINGS-2026-05-11.md](./project-audit/MARKETING-WEBSITE-FINDINGS-2026-05-11.md). That file is the production-readiness audit Batch 9 deliverable.
+- For the per-route SEO + indexing tracker, see [website/docs/tracking/seo-url-coverage.json](../website/docs/tracking/seo-url-coverage.json).
+- For the website's run-history of SEO/AEO/AIO passes (3-day + commit-delta gated), see the `SEO / AEO / AIO Run History` table in [website/CLAUDE.md](../website/CLAUDE.md).
+
+**Why this file is kept (not deleted):**
+
+History reference only. Reading the items below is a useful "what did we plan vs what shipped" archaeology, especially when onboarding a contributor who wants to understand the project's early scope decisions. If you are chasing what is broken or missing TODAY, do not start here.
 
 ---
 

package/docs/MIGRATION.md

@@ -1,5 +1,175 @@
 # Migration Guide
 
+## Upgrading v2 → v3.0.0
+
+v3 narrows the plugin to a single, well-supported backend contract: the
+hosted Native Update SaaS at `https://nativeupdate.aoneahsan.com`
+(reference implementation: Laravel 11 + Nova 5 in `backend/`). The
+direct-Firestore branch — `backendType: 'firestore'` plus the
+`firestore: { … }` config — is removed, along with the
+`src/firestore/` schema/client/manifest-reader/rules/indexes and the
+`example-apps/firebase-backend/` example.
+
+### Why
+
+The Firestore branch existed so apps could run without any server. In
+practice it pushed a lot of operational work (security rules, indexes,
+billing, Drive token storage) onto every consumer. The SaaS handles all
+of it server-side, so the SDK only needs to know how to call one
+backend.
+
+### Required action
+
+#### 1. Drop `backendType` and `firestore` from your config
+
+```diff
+ await NativeUpdate.initialize({
+-  backendType: 'firestore',
+-  firestore: { projectId: '…', appId: 'com.your.app', channel: 'production' },
++  serverUrl: 'https://api.nativeupdate.aoneahsan.com',
++  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 were running your own Firestore project for manifests, register
+your app in the Native Update dashboard, generate an API key, and
+switch to the HTTP config above. The dashboard mirrors every field
+that previously lived in your Firestore manifest.
+
+#### 2. Delete any direct Firestore reads from your app code
+
+```diff
+- import { FirestoreConfig } from 'native-update';
+```
+
+The plugin no longer exposes `FirestoreConfig`, `firestore-client`, or
+`manifest-reader`. Update checks happen via
+`NativeUpdate.checkForUpdate()` / `NativeUpdate.sync()`, which now
+always speak HTTP to your configured `serverUrl`.
+
+#### 3. Replace `firestore/schema` type imports
+
+If you were importing rollout / device / update-check types, switch to
+the new backend-neutral exports:
+
+```diff
+- import type {
+-   RolloutConfig,
+-   RolloutTargetSegments,
+-   DeviceInfo,
+-   UpdateCheckResponse,
+- } from 'native-update/firestore';
++ import type {
++   RolloutConfig,
++   RolloutTargetSegments,
++   DeviceInfo,
++   UpdateCheckResponse,
++ } from 'native-update';
+```
+
+`FirestoreTimestamp` is replaced by `RolloutTimestamp` (`number |
+string | Date`); a `toEpochMs()` helper handles all three forms.
+
+### Not affected
+
+- Bundle download, verification, install, rollback, boot-time
+  re-verify, and crash-loop auto-rollback are unchanged.
+- Native Android / iOS plugin code is unchanged.
+- App store update checks (`AppUpdate`) and in-app review prompts
+  (`AppReview`) are unchanged.
+
+---
+
+## 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)