native-update 2.0.0 → 3.1.0

package/docs/ROADMAP.md

@@ -1,15 +1,15 @@
-# Capacitor Native Update - Development Roadmap
+# Capacitor Native Update — Development Roadmap
 
-**Last Updated:** 2026-01-16
-**Status:** ✅ PRODUCTION READY (Core Features Complete)
+**Last Updated:** 2026-05-18
+**Status:** ✅ Production Ready — Play-Store-publishable end-to-end (finalization audit closed 2026-05-16; cooldown until 2026-05-23)
 
-This document outlines the development phases and their completion status.
+This document outlines the development phases and their completion status. For the authoritative timeline of who-shipped-what-when, see the root `CLAUDE.md` Audit Record + `docs/CHANGELOG.md`.
 
 ---
 
 ## ✅ Current Status: Production Ready
 
-The plugin provides complete OTA update functionality with native implementations for iOS and Android, comprehensive documentation, example applications, and developer tools.
+The plugin provides complete OTA update functionality with native implementations for iOS and Android, a Laravel 13 + Nova 5 SaaS backend with Sanctum-token auth + Spatie RBAC, comprehensive documentation (including a public Docusaurus docs site with 58 pages), example applications, CLI release-management tooling, and a Capacitor-wrapped React dashboard that is Play-Store-publishable end-to-end.
 
 ---
 
@@ -18,157 +18,233 @@ The plugin provides complete OTA update functionality with native implementation
 ### 1. Backend Infrastructure ✅ COMPLETE
 
 #### Update Server
-- [x] REST API endpoints for update management (Firebase Functions)
+
+- [x] Laravel 13 + Nova 5 SaaS backend (`backend/` — the only backend after v3.0.0)
+- [x] REST API endpoints for update management (`/api/dashboard/*` for the dashboard, `/api/v1/*` for the mobile plane)
 - [x] Version management system
-- [x] Bundle storage and retrieval (Google Drive integration)
+- [x] Bundle storage and retrieval (Google Drive via server-side OAuth)
 - [x] Update manifest generation
 - [x] Channel management (production, staging, development)
 - [x] Analytics endpoints
+- [x] Rollout config (percentage + pause/resume + targetSegments JSON) on the `builds` table
+- [x] FormRequest validators on every mutating endpoint
+- [x] env-driven CORS allowlist
+- [x] PayPal webhook + Stripe subscription model
+
+#### Auth + Identity
+
+- [x] Laravel Socialite (Google OAuth) — only sign-in method
+- [x] Sanctum personal access tokens (default 7-day TTL; configurable via `SANCTUM_TOKEN_EXPIRATION`)
+- [x] `spatie/laravel-permission` RBAC with `super-admin`, `admin`, `user` roles
+- [x] Per-route `can:<permission>` middleware on every dashboard/admin endpoint
+- [x] `Gate::before` super-admin bypass
+- [x] `php artisan native-update:role-assign <email> <role>` command for ops-driven role changes
+- [x] Per-app `ValidateApiKey` middleware for the mobile `/api/v1/*` plane (separate from Sanctum)
 
 #### Security Infrastructure
+
 - [x] Bundle signing service (CLI tools)
-- [x] Public/private key generation
+- [x] Public/private key generation (RSA-2048 / RSA-4096 / EC P-256 / EC P-384)
 - [x] Checksum generation (SHA-256)
-- [x] Signature verification
+- [x] Signature verification (RSA-SHA256 / ECDSA)
+- [x] Encrypted Drive OAuth token storage (Laravel encrypter)
+- [x] Hashed-at-rest Sanctum tokens
 
 #### Example Backends
+
 - [x] Node.js + Express example (`example-apps/node-express/`)
-- [x] Firebase Cloud Functions example (`example-apps/firebase-backend/`)
 - [x] Google Drive integration for storage
 
+(Note: `example-apps/firebase-backend/` was removed in v3.0.0; the project no longer carries a Firebase backend example.)
+
 ### 2. Native Platform Implementation ✅ COMPLETE
 
 #### iOS (Swift)
-- [x] NativeUpdatePlugin.swift - Main plugin
-- [x] LiveUpdatePlugin.swift - OTA updates
-- [x] BundleManager.swift - Bundle management
-- [x] AppUpdatePlugin.swift - App store updates
-- [x] AppReviewPlugin.swift - In-app reviews
-- [x] BackgroundUpdatePlugin.swift - Background updates
-- [x] SecurityManager.swift - Security utilities
+
+- [x] NativeUpdatePlugin.swift — Main plugin
+- [x] LiveUpdatePlugin.swift — OTA updates
+- [x] BundleManager (bundle handling)
+- [x] AppUpdatePlugin.swift — App store updates
+- [x] AppReviewPlugin.swift — In-app reviews (`SKStoreReviewController`)
+- [x] BackgroundUpdatePlugin.swift — Background updates (BGTaskScheduler)
+- [x] SecurityManager.swift — Security utilities
 
 #### Android (Kotlin)
-- [x] NativeUpdatePlugin.kt - Main plugin
-- [x] LiveUpdatePlugin.kt - OTA updates
-- [x] BundleManager.kt - Bundle management
-- [x] AppUpdatePlugin.kt - Play Store updates (Play Core Library)
-- [x] AppReviewPlugin.kt - In-app reviews
-- [x] BackgroundUpdatePlugin.kt - Background updates
-- [x] SecurityManager.kt - Security utilities
+
+- [x] NativeUpdatePlugin.kt — Main plugin
+- [x] LiveUpdatePlugin.kt — OTA updates
+- [x] BundleManager (bundle handling)
+- [x] AppUpdatePlugin.kt — Play Store updates (Play Core Library)
+- [x] AppReviewPlugin.kt — In-app reviews (Play Review)
+- [x] BackgroundUpdatePlugin.kt — Background updates (WorkManager)
+- [x] SecurityManager.kt — Security utilities
 
 ### 3. TypeScript Implementation ✅ COMPLETE
 
 - [x] Plugin definitions and interfaces
 - [x] Web implementation
-- [x] Live update module (7 files)
-- [x] App update module (7 files)
-- [x] App review module (6 files)
-- [x] Background update module (3 files)
-- [x] Core infrastructure (9 files)
-- [x] Security module (2 files)
-- [x] Firestore integration (4 files)
+- [x] Live update module
+- [x] App update module
+- [x] App review module
+- [x] Background update module
+- [x] Core infrastructure (analytics, cache, config, errors, event-emitter, logger, performance, plugin-manager, security)
+- [x] Security module (crypto, validator)
+
+(Note: `src/firestore/` was removed in v3.0.0. The plugin no longer carries any Firestore code; manifest reads happen over plain HTTPS against any user-controlled endpoint.)
 
 ### 4. Testing Suite ✅ COMPLETE
 
-#### TypeScript Unit Tests
-- [x] Bundle manager tests
-- [x] Config tests
-- [x] Delta processor tests
-- [x] Firestore schema tests
-- [x] Manifest reader tests
-- [x] Rollout checker tests
-- [x] Security tests
-- [x] Version manager tests
-- [x] Integration tests
-
-#### iOS Native Tests (XCTest) ✅ IMPLEMENTED
-- [x] SecurityManagerTests.swift (6 tests)
-- [x] LiveUpdateTests.swift (10 tests)
-- [x] AppUpdateTests.swift (5 tests)
-- [x] AppReviewTests.swift (5 tests)
-- [x] BackgroundUpdateTests.swift (6 tests)
-
-#### Android Native Tests (JUnit/Kotlin) ✅ IMPLEMENTED
-- [x] SecurityManagerTest.kt (10 tests)
-- [x] LiveUpdatePluginTest.kt (10 tests)
-- [x] AppUpdatePluginTest.kt (5 tests)
-- [x] AppReviewPluginTest.kt (5 tests)
-- [x] BackgroundUpdateWorkerTest.kt (5 tests)
-- [x] BackgroundNotificationManagerTest.kt (5 tests)
-
-#### E2E Tests (Detox) ✅ IMPLEMENTED
-- [x] Complete update lifecycle (ota-update.e2e.spec.js)
-- [x] Download progress tracking (download-progress.e2e.spec.js)
-- [x] Channel switching (channel-switching.e2e.spec.js)
-- [x] Error handling (error-handling.e2e.spec.js)
+#### Backend Tests (Laravel)
+
+- [x] OAuth + Socialite flow
+- [x] Sanctum token issuance + middleware
+- [x] Spatie permission seeder + role assignment
+- [x] UpdateBuildRequest FormRequest validation
+- [x] PayPal webhook (4 cases)
+- [x] BundleUploadTest (7 cases)
+- [x] UserLicenseTest (5 cases)
+- **Total: 136/136 passing** (Pest/PHPUnit)
+
+#### iOS Native Tests (XCTest) ✅
+
+- [x] SecurityManagerTests.swift
+- [x] LiveUpdateTests.swift
+- [x] AppUpdateTests.swift
+- [x] AppReviewTests.swift
+- [x] BackgroundUpdateTests.swift
+
+#### Android Native Tests (JUnit/Kotlin) ✅
+
+- [x] SecurityManagerTest.kt
+- [x] LiveUpdatePluginTest.kt
+- [x] AppUpdatePluginTest.kt
+- [x] AppReviewPluginTest.kt
+- [x] BackgroundUpdateWorkerTest.kt
+- [x] BackgroundNotificationManagerTest.kt
 
 ### 5. Tooling and Utilities ✅ COMPLETE
 
 #### CLI Package (8 Commands)
-- [x] `init` - Initialize a new project
-- [x] `bundle-create` - Create update bundles
-- [x] `bundle-sign` - Sign bundles cryptographically
-- [x] `bundle-verify` - Verify bundle signatures
-- [x] `keys-generate` - Generate RSA/ECDSA keys
-- [x] `backend-create` - Scaffold backend server
-- [x] `server-start` - Run local update server
-- [x] `monitor` - Monitor update deployments
+
+- [x] `init` — Initialize a new project
+- [x] `bundle-create` — Create update bundles
+- [x] `bundle-sign` — Sign bundles cryptographically
+- [x] `bundle-verify` — Verify bundle signatures
+- [x] `keys-generate` — Generate RSA / ECDSA keypairs
+- [x] `backend-create` — Scaffold backend server (with `TODO[SCAFFOLD-IMPLEMENT-BEFORE-DEPLOY]` markers)
+- [x] `server-start` — Run local update server
+- [x] `monitor` — Monitor update deployments (interval+spinner cleanup, signal handlers, failure bail)
 
 #### Developer Tools
+
 - [x] Local testing server
 - [x] Bundle creator utility
 - [x] Bundle signer utility
 
 ### 6. Documentation ✅ COMPLETE
 
-- [x] API documentation (7 files in `/docs/api/`)
-- [x] Feature guides (3 files in `/docs/features/`)
-- [x] Getting started guides (3 files)
-- [x] Developer guides (5 files)
-- [x] Examples (2 files)
-- [x] Security documentation
-- [x] Migration guide
+- [x] API documentation (`docs/api/`)
+- [x] Feature guides (`docs/features/`)
+- [x] Getting started guides (`docs/getting-started/`)
+- [x] Developer guides (`docs/guides/`)
+- [x] Examples (`docs/examples/`)
+- [x] Security documentation + PRE-LAUNCH-PENTEST-CHECKLIST
+- [x] Migration guide (v2 → v3.0.0 + 2026-05-11 auth-swap notes)
 - [x] Changelog
 - [x] Known limitations
-
-### 7. Marketing Website ✅ COMPLETE
-
-- [x] 24 pages (marketing + dashboard)
-- [x] User authentication (Firebase + Google)
-- [x] Dashboard with app management
-- [x] Build upload and management
-- [x] Google Drive integration
-- [x] Analytics visualization
+- [x] **Public Docusaurus docs site** (sibling repo `native-update-docs`, Firebase Hosting, 58 Diátaxis-organized pages, ~76k words, 30+ AI-bot allowlist + llms.txt + JSON-LD)
+
+### 7. Marketing Website + Dashboard ✅ COMPLETE
+
+- [x] React 19 + Vite 7 + Tailwind v4 + TanStack Query + Radix primitives
+- [x] Public marketing pages (Home, Features 1956 words, Pricing 1897 words, About 1913 words, Docs, Examples, Contact)
+- [x] Authenticated dashboard (Apps, Builds, Upload, Drive, Config, Settings, Rollouts, Analytics)
+- [x] Admin pages (Overview, Users, Apps, Builds) with Spatie permission gates
+- [x] User authentication via Laravel Socialite + Sanctum (Firebase Auth removed 2026-05-11)
+- [x] Build upload and management (multipart → Laravel → Drive)
+- [x] Google Drive connect/disconnect (server-side OAuth)
+- [x] Analytics visualization (D3-based; pulls aggregates from `/api/dashboard/analytics`)
 - [x] Configuration generator
-- [x] All legal pages (Privacy, Terms, Security, Cookies, Data Deletion)
+- [x] All legal pages (Privacy, Terms, Security, Cookies, Data Deletion) rewritten for the Sanctum stack
+- [x] SEO/AEO discovery files: robots.txt with 30+ AI bots, sitemap.xml, sitemap-index.json, feed.xml, llms.txt, llms-full.txt, ai.txt, humans.txt, security.txt, machine-readable pricing.md
+- [x] Per-route static HTML prerender + per-route JSON-LD
+- [x] Capacitor-wrapped for Play Store distribution (Android release readiness closed 2026-05-16)
 
 ### 8. Example Applications ✅ COMPLETE
 
-- [x] React + Capacitor frontend (`example-apps/react-capacitor/`)
-- [x] Node.js + Express backend (`example-apps/node-express/`)
-- [x] Firebase Cloud Functions (`example-apps/firebase-backend/`)
+- [x] React + Capacitor frontend (`example-apps/react-capacitor/`) — with capability cards for app-update / app-review / background-update; React 18 (stable downstream target)
+- [x] Node.js + Express backend (`example-apps/node-express/`) — minimal manifest-endpoint reference
+
+### 9. CI/CD ✅ COMPLETE
+
+- [x] `.github/workflows/ci.yml` — yarn-based CI on PRs (corepack + node 20 + yarn 4)
+- [x] `.github/workflows/release.yml` — tag-driven npm publish (with provenance) + GitHub Release
+- [x] `.github/workflows/example-bundle.yml` — release+manual+weekly-cron build of the example app, signed, attached to GitHub Release (ephemeral-key fallback when secret absent)
+
+### 10. Android Release Readiness ✅ COMPLETE (2026-05-16)
+
+- [x] `signingConfigs.release` wired from env vars
+- [x] ProGuard / R8 enabled with Capacitor-aware rules
+- [x] `network_security_config.xml` (HTTPS-only outside debug; localhost cleartext exception for dev)
+- [x] Branded launcher icons (15 PNGs across all densities + adaptive icons)
+- [x] Branded splash assets (11 PNGs)
+- [x] 3 Play Store graphics (feature graphic, promo graphic, TV banner) rendered from SVG via rsvg-convert
+- [x] 10-section `docs/deployment/BUILD_FOR_PLAY_STORE.md` runbook
+- [x] `screenshots/CAPTURE-GUIDE.md`
+- [x] Play Store `full-description.md` + `data-safety.md` rewritten for the Sanctum stack
+- [x] Unverifiable SOC / ISO / SLA claims removed from SecurityPage
 
 ---
 
 ## 🎯 Future Enhancement Phases
 
-### ~~Phase 1: Advanced Testing~~ ✅ COMPLETE (2026-01-16)
-- [x] iOS XCTest implementation - 5 files, 32 tests
-- [x] Android JUnit tests - 6 files, 40 tests
-- [x] E2E test suite with Detox - 4 specs, 19 tests
+### ~~Phase 1: Advanced Testing~~ ✅ COMPLETE (2026-01-16 → 2026-05-11)
+
+- [x] iOS XCTest implementation
+- [x] Android JUnit tests
+- [x] E2E test suite with Detox
+- [x] Backend Pest/PHPUnit test suite (added 2026-05-08 → 2026-05-11)
+- [x] Microbenchmark scaffold for security hot paths (added 2026-05-11)
+
+### ~~Phase 2: CI/CD~~ ✅ COMPLETE (2026-05-08 → 2026-05-11)
+
+- [x] GitHub Actions CI (`.github/workflows/ci.yml`)
+- [x] GitHub Actions release pipeline (`.github/workflows/release.yml`)
+- [x] GitHub Actions example-bundle pipeline (`.github/workflows/example-bundle.yml`)
+
+### ~~Phase 3: Public Docs Site~~ ✅ COMPLETE (2026-05-11)
 
-### Phase 2: Enterprise Features (Optional)
-- [ ] Delta updates WASM optimization
-- [ ] Multi-tenant SaaS platform
-- [ ] Enterprise SSO integration
-- [ ] Advanced rollout strategies
+- [x] Docusaurus public docs site at sibling repo `native-update-docs`
+- [x] 58 Diátaxis-organized pages, ~76k words
+- [x] Firebase Hosting deployed (custom domain ready)
+- [x] 7 discovery files (robots / llms / llms-full / humans / security / sitemap-index / sitemap)
+- [x] 3 JSON-LD blocks per page
+
+### ~~Phase 4: Android Play Store Readiness~~ ✅ COMPLETE (2026-05-16)
+
+(See "Android Release Readiness" section above.)
+
+### Phase 5: Enterprise Features (Optional, future)
+
+- [ ] Delta updates WASM optimization (placeholder exists)
 - [ ] A/B testing support
+- [ ] Multi-tenant SaaS hardening (sub-team / org accounts / shared ownership)
+- [ ] Enterprise SSO integration (SAML / OIDC beyond Google)
+- [ ] Custom branding for white-label SaaS
+- [ ] SLA monitoring + uptime page
+- [ ] Audit-logging UI surfaces on top of existing `analytics_events` data
+
+### Phase 6: Community / Ecosystem (Optional, future)
 
-### Phase 3: Community Features (Optional)
 - [ ] Video tutorials
-- [ ] Additional framework examples (Vue, Angular)
-- [ ] CI/CD integration templates
-- [ ] Community plugins
+- [ ] Wikipedia / Reddit / Product Hunt / AlternativeTo / G2 / Capterra presence (AI-citation reach)
+- [ ] Additional framework examples (Vue, Angular, Svelte)
+- [ ] Additional backend examples (Python, Java)
+- [ ] Community plugins directory
+
+### Phase 7: Internal Refactors (Optional, future)
+
+- [ ] `website/src/pages/DocsPage.tsx` — 1,406-line file (workspace 500-line max). Multi-session refactor into per-feature sub-components.
 
 ---
 
@@ -176,40 +252,44 @@ The plugin provides complete OTA update functionality with native implementation
 
 | Category | Status | Progress |
 |----------|--------|----------|
-| Backend Infrastructure | ✅ Complete | 100% |
+| Backend Infrastructure (Laravel + Nova + Sanctum + Spatie) | ✅ Complete | 100% |
 | iOS Native Implementation | ✅ Complete | 100% |
 | Android Native Implementation | ✅ Complete | 100% |
 | TypeScript Implementation | ✅ Complete | 100% |
 | CLI Tools | ✅ Complete | 100% |
-| Documentation | ✅ Complete | 100% |
-| Marketing Website | ✅ Complete | 100% |
+| Documentation (repo + public Docusaurus) | ✅ Complete | 100% |
+| Marketing Website + Dashboard | ✅ Complete | 100% |
 | Example Applications | ✅ Complete | 100% |
-| TypeScript Unit Tests | ✅ Complete | 100% |
+| Backend Pest Tests | ✅ Complete | 100% (136/136) |
 | iOS Native Tests (XCTest) | ✅ Complete | 100% |
 | Android Native Tests (JUnit) | ✅ Complete | 100% |
-| E2E Tests (Detox) | ✅ Complete | 100% |
+| CI/CD | ✅ Complete | 100% |
+| Android Release Readiness | ✅ Complete | 100% |
+| Enterprise Features (Phase 5) | ⏳ Optional | 0% |
+| Community / Ecosystem (Phase 6) | ⏳ Optional | 0% |
 
-**Overall Status:** Production Ready with Comprehensive Test Coverage
+**Overall Status:** Production Ready, Play-Store-publishable end-to-end, with backend Pest + iOS XCTest + Android JUnit test layers passing.
 
 ---
 
 ## 📝 Notes
 
-- Core plugin functionality is complete and tested
-- Native tests are fully implemented (iOS XCTest, Android JUnit)
-- E2E tests are implemented with Detox framework
-- All builds pass with zero errors
-- All lint checks pass with zero warnings
-- Comprehensive test coverage with ~121 tests across all categories
+- v3.0.0 (2026-05-04) removed Firestore from the plugin SDK + website; Laravel HTTP is the only backend.
+- 2026-05-11 swapped Firebase Auth for Laravel Socialite + Sanctum + Spatie RBAC.
+- 2026-05-16 closed the finalization audit (10 batches) making the Capacitor-wrapped dashboard Play-Store-publishable end-to-end.
+- All builds pass with zero errors (`yarn build` root + website + Docusaurus).
+- All lint checks pass with zero warnings.
+- Audit cooldown until 2026-05-23 (7-day cooldown after finalization audit closure).
 
 ---
 
 ## 🤝 Contributing
 
-We welcome contributions! Focus areas:
-- Additional backend examples
-- Framework-specific adapters
-- Enterprise feature development
-- Delta updates optimization
+Contributions welcome. Focus areas:
+
+- Delta updates WASM optimization (Phase 5)
+- Additional backend examples in other languages (Phase 6)
+- Framework-specific adapters (Vue / Angular / Svelte — Phase 6)
+- AI-citation reach: Wikipedia mention, Reddit / Product Hunt presence (Phase 6)
 
 See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.

package/docs/SECURITY-IF-REPO-PUBLIC.md

@@ -0,0 +1,232 @@
+# If This Repo Ever Becomes Public — Security Runbook
+
+**Status:** Preventive. As of 2026-05-08 the repository is **PRIVATE** by intent.
+The root `.gitignore` explicitly opts to keep `.env` files in git so the team can
+share secrets. If that policy ever changes — open-sourcing the SaaS, splitting
+the dashboard into a separate public repo, accidental leak via a public mirror,
+contractor audit, etc. — work through this runbook in order. Do **not** rely on
+"I'll just delete the file" — git history keeps it forever unless you scrub.
+
+> **Trigger phrases that mean "run this runbook":** "make this repo public",
+> "open-source this", "we're forking the dashboard public", "the repo got
+> mirrored", "GitHub flagged a leaked secret", "we leaked X".
+
+---
+
+## Step 0 — Stop and assess (before pushing anything)
+
+1. Is the repo currently public on GitHub or anywhere else? Check
+   `gh repo view aoneahsan/native-update --json visibility` and search GitHub
+   + GitLab + public mirrors for `aoneahsan/native-update`.
+2. What is the diff between "what's checked in today" and "what should be
+   public"? Run `git ls-files | xargs grep -lE 'AIza|sk_live_|AKIA|-----BEGIN'`
+   to list files containing literal secret patterns.
+3. List every `.env*` file currently tracked:
+   ```bash
+   git ls-files | grep -E '\.env(\..+)?$|\.pem$|keystores/|keystore\.properties$|\.jks$|\.keystore$'
+   ```
+4. **Decide:** rotate-all-then-publish (safe) or scrub-history-then-publish (faster
+   but irreversible). Default: rotate-all. Pick the second only if rotation is
+   blocked (live PayPal subscriptions in flight, Google OAuth client in use by
+   real users, etc.) — and even then, rotate within the next 30 days.
+
+---
+
+## Step 1 — Rotate every committed secret
+
+Treat every secret that has EVER touched git as compromised. Rotate, don't
+re-use. Order: highest-blast-radius first.
+
+| Secret | Where it lives | How to rotate |
+|---|---|---|
+| Google OAuth Client Secret | `backend/.env` `GOOGLE_CLIENT_SECRET` | Google Cloud Console → APIs & Services → Credentials → reset client secret. Update on server. Existing Sanctum bearer tokens issued by previous sign-ins keep working until they expire (`SANCTUM_TOKEN_EXPIRATION` minutes); to revoke them all now run `php artisan tinker` then `\App\Models\PersonalAccessToken::truncate()`. |
+| Sanctum personal access tokens | `personal_access_tokens` table | Tokens themselves aren't a config secret, but if you suspect they leaked, mass-revoke: `php artisan tinker` then `\Laravel\Sanctum\PersonalAccessToken::truncate()`. Every user has to sign in again. |
+| Laravel `APP_KEY` | `backend/.env` | `php artisan key:generate --show` → paste into the server's real `.env`. **Important:** changing APP_KEY invalidates all encrypted-cookie sessions and all `encrypted:array` columns (Google Drive OAuth tokens stored on User rows). After rotation, every connected user must reconnect Google Drive. Do this in a maintenance window. |
+| PayPal Live Client Secret | `backend/.env` `PAYPAL_LIVE_CLIENT_SECRET` | developer.paypal.com → My Apps & Credentials → Live → app → Show/regenerate secret. Existing subscriptions keep running on the new credentials. |
+| PayPal Webhook ID | `backend/.env` `PAYPAL_WEBHOOK_ID` | developer.paypal.com → Webhooks → delete the old endpoint, create a new one pointing at the same URL, paste the new `WH-...` id. |
+| FilesHub API key | `backend/.env` `FILESHUB_API_KEY` | fileshub.zaions.com → Account → API keys → revoke + regenerate. Old uploads are still accessible (public URLs) but new uploads will fail until you update the server. |
+| Database password | `backend/.env` `DB_PASSWORD` | Hostinger hPanel (or your DB host) → reset password → update on server. |
+| Mail credentials | `backend/.env` `MAIL_*` | If real credentials are committed, rotate at the mail provider. |
+| Android keystore + key passwords | `keystores/` or `website/android/keystore.properties` | If a keystore is committed, **the app signing identity is compromised**. You cannot rotate this without uploading a new app via Google Play's "Reset upload key" flow, which requires Play Console approval. Avoid committing keystores at all costs — `website/android/keystore.properties` is gitignored by the Batch 8 changes. |
+| Sentry DSN, Amplitude key, Clarity ID, Google Client ID | `website/.env` | These are public-by-design (intended to ship in client JS). No rotation needed. |
+
+**Verification after rotation:** every server still works against the new
+secrets BEFORE you scrub history. Don't break prod chasing a clean history.
+
+---
+
+## Step 2 — Add patterns to `.gitignore` (BEFORE step 3)
+
+If you scrub history without updating `.gitignore`, the next dev's `.env` will
+get re-committed. Update `.gitignore` first:
+
+```gitignore
+# --- Secrets (added when repo went public on YYYY-MM-DD) -------------------
+.env
+.env.*
+!.env.example
+!.env.test.example
+
+backend/.env
+backend/.env.*
+!backend/.env.example
+
+website/.env
+website/.env.*
+!website/.env.example
+
+backend/storage/oauth-private-key.pem
+backend/storage/app.key
+
+# Android signing material
+android/key.properties
+android/app/keystore/
+keystores/
+*.jks
+*.keystore
+
+# iOS signing material
+ios/Plugin/PrivateKey.p8
+*.p12
+
+# RSA / ECDSA private keys for plugin bundle signing
+*-private.pem
+*.p8
+```
+
+Then **remove the explicit "we keep .env in git" note** from the top of
+`.gitignore`.
+
+Commit this change in a single, isolated commit so the history shows the policy
+shift cleanly:
+```bash
+git add .gitignore
+git commit -m "chore(security): exclude .env files in preparation for public repo"
+```
+
+---
+
+## Step 3 — Scrub git history
+
+Pick **one** tool. Do this on a fresh local clone, push to a new repo or
+force-push to the same one once verified.
+
+### Option A — `git filter-repo` (recommended)
+
+```bash
+# Install: https://github.com/newren/git-filter-repo
+pip install git-filter-repo
+
+# Fresh clone — destructive, do not work on your daily clone
+git clone --mirror git@github.com:aoneahsan/native-update.git native-update-scrub.git
+cd native-update-scrub.git
+
+# Remove tracked secret files from all history
+git filter-repo \
+  --invert-paths \
+  --path .env \
+  --path backend/.env \
+  --path website/.env \
+  --path website/android/keystore.properties
+
+# If specific strings (a leaked AKIA key, a hardcoded Sanctum token, an
+# OAuth client secret literal) need to be redacted:
+echo 'sk_live_0123456789012345678901==>REDACTED' > /tmp/replace.txt
+git filter-repo --replace-text /tmp/replace.txt
+
+# Verify locally before pushing
+git log --all --full-history -- .env
+
+# Force-push the rewritten history
+git push --force --all
+git push --force --tags
+```
+
+### Option B — `bfg-repo-cleaner`
+
+```bash
+brew install bfg
+git clone --mirror git@github.com:aoneahsan/native-update.git native-update-scrub.git
+cd native-update-scrub.git
+bfg --delete-files '.env'
+bfg --delete-files 'keystore.properties'
+bfg --replace-text /tmp/replace.txt
+git reflog expire --expire=now --all && git gc --prune=now --aggressive
+git push --force
+```
+
+**After force-push:**
+- Tell every collaborator to re-clone. Their old local clones still contain the
+  secrets.
+- GitHub caches forks + refs for ~30 days. Open a support ticket asking for a
+  cache purge if the leaked secret has not been rotated yet (it shouldn't —
+  step 1 ran first).
+
+---
+
+## Step 4 — Verify the public-facing tree
+
+Before flipping repo visibility (`gh repo edit --visibility public --accept-visibility-change-consequences`):
+
+- [ ] `git ls-files | grep -iE '\.env(\..+)?$' | grep -v example` returns
+      **empty**.
+- [ ] `git log --all --diff-filter=A --pretty=format: --name-only | sort -u | grep -iE '\.env(\..+)?$|keystore\.properties$|\.jks$|\.keystore$|\.pem$' | grep -v example`
+      returns **empty** (after history scrub).
+- [ ] `git ls-files | xargs grep -lE 'AIza[0-9A-Za-z_-]{35}|AKIA[0-9A-Z]{16}|sk_live_[0-9a-zA-Z]{20,}|-----BEGIN ((RSA |EC )?PRIVATE KEY|OPENSSH PRIVATE KEY)-----'`
+      returns **empty or only fake/demo strings**.
+- [ ] `gh secret-scanning alerts list` (after pushing) shows no critical alerts.
+- [ ] All `[REQUIRED]` secrets in `.env.example` are blank in the example file.
+- [ ] `LICENSE` exists and matches the project license everyone expects.
+- [ ] `SECURITY.md` exists with a security-contact email and a vulnerability
+      disclosure policy. Add one if missing.
+- [ ] Backend `config/cors.php` `allowed_origins` is locked to production
+      domains; CORS fallback in dev does not expose anything sensitive.
+- [ ] Backend route gates are correct: every `/api/dashboard/*` route has
+      `auth:sanctum` middleware AND a `can:<permission>` gate (see
+      `backend/routes/api.php`). `/api/admin/*` additionally has the
+      `RequireAdmin` middleware. `/api/v1/*` (device endpoints) uses
+      `ValidateApiKey`, not Sanctum.
+- [ ] Sample data in seeders / fixtures contains no real user PII.
+- [ ] Internal-only docs (work-history with personal context, vendor-private
+      notes) moved to a private folder NOT shipped with the public repo, OR
+      sanitized.
+
+---
+
+## Step 5 — Flip visibility + monitor
+
+```bash
+gh repo edit aoneahsan/native-update --visibility public --accept-visibility-change-consequences
+```
+
+Then:
+
+- Enable **Push protection** for secrets: GitHub repo → Settings → Code
+  security → Secret scanning → Push protection → Enable.
+- Enable **Dependency review** in PRs.
+- Enable **Dependabot** alerts + security updates.
+- Subscribe a security inbox to the `gh secret-scanning alerts` webhook.
+- Watch for the next 30 days: search GitHub for the names of the rotated
+  secrets to confirm no copy is sitting in someone's fork or gist.
+
+---
+
+## What this runbook does NOT cover
+
+- **License changes.** Going public may require relicensing (especially for
+  any vendored code that was MIT-OK in private but needs explicit attribution
+  in public). Run `npx license-checker --production` and audit before
+  publishing.
+- **Trademark + branding.** "Native Update", logos, and visual assets — confirm
+  you can publish them under MIT.
+- **GDPR / contractual obligations.** If user emails or any analytics data sit
+  in fixtures or test snapshots, scrub or anonymize before publishing.
+- **PR access policy.** Decide upfront: do you accept public PRs? CONTRIBUTING.md
+  needs a review-ladder section.
+
+---
+
+**Last updated:** 2026-05-08
+**Owner:** Ahsan Mahmood (`aoneahsan@gmail.com`)
+**Companion:** root `.gitignore`, `backend/.env.example`, `website/.env.example`,
+`docs/deployment/PRODUCTION-DEPLOY-CHECKLIST.md`.