native-update 2.0.0 → 3.1.0

package/docs/project-knowledge-base/01-system-overview.md

@@ -2,14 +2,14 @@
 
 ## Metadata
 
-- **Reference Date:** 2026-03-16
-- **Last Updated:** 2026-03-16
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
 
 ## Project Identity
 
 - **Name:** Native Update
 - **Package:** `native-update`
-- **Type:** Open-source Capacitor plugin plus update management platform
+- **Type:** Open-source Capacitor plugin plus self-hostable update management platform
 - **Primary Creator:** Ahsan Mahmood
 - **Primary Contact:** aoneahsan@gmail.com
 - **License:** MIT
@@ -28,21 +28,21 @@ The plugin provides the runtime capabilities inside a Capacitor app:
 - app update checks and prompts
 - in-app review requests
 - background update scheduling
-- security validation logic
-- Firestore-backed manifest reading support
+- security validation logic (SHA-256 checksums + RSA-SHA256 signatures)
+- HTTP-based manifest reading from any user-controlled backend
 
 ### 2. Dashboard Layer
 
 The website provides a management surface for:
 
-- user auth
+- user auth (Google OAuth via Laravel Socialite + Sanctum bearer tokens)
 - app creation and app management
-- build uploads
+- build uploads (browser → Laravel → Google Drive)
 - rollout visibility and control
 - analytics review
 - Google Drive connection and storage management
 - configuration generation
-- admin-only oversight pages
+- admin-only oversight pages (Spatie permission-gated)
 
 ### 3. Docs Layer
 
@@ -52,17 +52,19 @@ The docs explain:
 - features and APIs
 - examples and advanced scenarios
 - security, deployment, testing, and troubleshooting
-- migration from other approaches
+- migration from other approaches (CodePush, Capacitor Live Updates)
 - planning, tracking, roadmap, audit, and report history
 
+In addition to the in-repo `/docs` folder, a public Docusaurus site lives at the sibling repo `native-update-docs` and is deployed to Firebase Hosting (hosting-only — no Firebase backend).
+
 ### 4. Tooling Layer
 
 The project includes:
 
-- CLI commands
+- CLI commands (`init`, `bundle-create`, `bundle-sign`, `bundle-verify`, `keys-generate`, `backend-create`, `server-start`, `monitor`)
 - bundle creation/signing/verification utilities
-- backend templates and examples
-- local development scripts
+- backend scaffolding templates
+- local development server
 
 ## What The Product Solves
 
@@ -82,7 +84,7 @@ Native Update consolidates those concerns into one project with a common mental
 ### Live / OTA Updates
 
 - Deliver JavaScript, HTML, and CSS changes without app store review
-- Support update channels
+- Support update channels (production / staging / development)
 - Manage version checks and bundle downloads
 - Support checksum and signature validation
 - Enable rollback-aware update flows
@@ -92,35 +94,36 @@ Native Update consolidates those concerns into one project with a common mental
 
 - Check for newer native binary versions
 - Support immediate and flexible update strategies
-- Integrate with Android and iOS update behavior
+- Integrate with Android Play Core update + iOS App Store update behavior
 
 ### In-App Reviews
 
-- Request native reviews
+- Request native reviews via Play Review API + StoreKit `SKStoreReviewController`
 - respect timing/rate limiting logic
 - support user-experience-aware prompting
 
 ### Background Updates
 
-- Schedule checks while app is not active
+- Schedule checks while app is not active (Android WorkManager, iOS BGTaskScheduler)
 - support native notification behavior
 - provide background configuration hooks
 
 ### Security
 
-- signing
-- checksum verification
+- RSA-SHA256 signing of bundles
+- SHA-256 checksum verification
 - HTTPS-first posture
 - certificate pinning support
 - validation helpers
+- fail-closed on integrity violations
 
 ### Release Operations
 
-- upload build ZIPs
+- upload build ZIPs through the dashboard
 - generate file manifests
 - publish app-facing manifests
 - configure rollout percentages
-- manage app/channel/build metadata
+- manage app/channel/build metadata via Nova admin or REST API
 
 ## Current Product Surfaces
 
@@ -131,6 +134,7 @@ Native Update consolidates those concerns into one project with a common mental
 - `/pricing`
 - `/docs`
 - `/docs/*`
+- `/examples`
 - `/about`
 - `/contact`
 - `/privacy`
@@ -143,8 +147,9 @@ Native Update consolidates those concerns into one project with a common mental
 
 ### Auth Pages
 
-- `/login`
-- `/signup`
+- `/login` (Google sign-in via Laravel Socialite redirect)
+- `/signup` (same flow as `/login`; account is created on first callback)
+- `/auth/callback` (SPA receives the Sanctum token from the Laravel OAuth callback)
 
 ### Protected Dashboard
 
@@ -166,6 +171,7 @@ Native Update consolidates those concerns into one project with a common mental
 - `/admin/users`
 - `/admin/apps`
 - `/admin/builds`
+- Laravel Nova admin lives at `/nova` on the backend host (separate UI; same MySQL store)
 
 ## User Types
 
@@ -175,15 +181,15 @@ Can browse marketing, docs, legal, contact, sitemap, and feed pages.
 
 ### Authenticated User
 
-Can access dashboard pages and manage their own apps, builds, Drive connection, settings, and release operations.
+Holds a Sanctum personal access token, has a row in the MySQL `users` table keyed by `google_id`, and the `user` role from `spatie/laravel-permission`. Can manage their own apps, builds, Drive connection, settings, and release operations.
 
 ### Admin User
 
-An authenticated user whose Firestore user document has `isAdmin: true`. Admins can access `/admin` pages for broader oversight.
+A signed-in user assigned the `admin` or `super-admin` role in MySQL via `spatie/laravel-permission`. Super-admins bypass all `can:` middleware checks via a `Gate::before` hook. Admin assignment happens via `php artisan native-update:role-assign <email> <role>` or automatically when the email is in the `ADMIN_EMAILS` env list.
 
 ### Mobile App Client
 
-Not a dashboard user, but an app-side runtime consumer of manifests, update metadata, and plugin APIs.
+Not a dashboard user, but an app-side runtime consumer of manifests, update metadata, and plugin APIs. Authenticates with the mobile API plane via a per-app API key (separate from Sanctum).
 
 ### Developer / Maintainer
 
@@ -192,22 +198,24 @@ Works in the codebase, docs, CLI, native code, example apps, and release infrast
 ## Access Model
 
 - Public routes are open.
-- Dashboard routes are wrapped by `ProtectedRoute`.
-- Admin routes are wrapped by `AdminRoute`.
-- Google sign-in is the primary auth flow.
-- Admin is currently determined by email/user doc logic, including `aoneahsan@gmail.com`.
+- Dashboard routes are wrapped by `ProtectedRoute` on the SPA AND protected by `auth:sanctum` middleware on every Laravel `/api/dashboard/*` route.
+- Admin routes are wrapped by `AdminRoute` on the SPA AND protected by `can:<permission>` middleware on every Laravel `/api/admin/*` route.
+- Google sign-in (via Laravel Socialite) is the only auth flow.
+- Admin privilege comes from Spatie role assignment, not a `users.is_admin` boolean.
 
 ## Product Positioning Notes
 
 - The repo positions Native Update as more than a plugin; it is a platform direction.
 - The website presents a complete update solution with dashboard and docs.
 - The repo also contains older historical docs from pre-production phases. These should be treated as timeline artifacts, not always the newest truth.
+- All mentions of "Firebase Auth", "Firestore", or "Firebase backend" in older docs are historical — the architecture switched to Laravel + Sanctum on 2026-05-11.
 
 ## Recommended Decision Assumptions For AI Tools
 
 - Treat the project as a cross-platform mobile infrastructure product.
 - Treat the website as both a marketing site and operations dashboard.
-- Treat Google Drive + Firestore as the preferred no-cost production backend path for the website flow.
+- Treat the Laravel backend at `backend/` as the canonical persistence + auth layer for the dashboard.
+- Treat Google Drive as the canonical storage destination for uploaded bundle ZIPs; tokens are encrypted server-side by Laravel.
 - Treat the dashboard as owner/operator tooling, not end-user mobile UI.
 - Treat security, rollout control, and documentation quality as important project values.
 
@@ -216,3 +224,4 @@ Works in the codebase, docs, CLI, native code, example apps, and release infrast
 - The project contains current docs plus historical reports and planning files.
 - Some documents disagree on production readiness because they were written at different times.
 - For technical state, prefer current source code, route definitions, type definitions, package files, and newer roadmap/report files.
+- The "no-cost Firestore + Google Drive backend" architecture was deliberately abandoned in v3.0.0 (2026-05-04). Any document still describing it is historical-only.

package/docs/project-knowledge-base/02-routes-pages-forms-users.md

@@ -2,8 +2,8 @@
 
 ## Metadata
 
-- **Reference Date:** 2026-03-16
-- **Last Updated:** 2026-03-16
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
 
 ## Route Inventory
 
@@ -16,6 +16,7 @@
 | `/pricing` | PricingPage | Public | Pricing/beta/commercial positioning page |
 | `/docs` | DocsPage | Public | Docs hub and guided docs entry |
 | `/docs/*` | DocsMarkdownPage | Public | Render markdown docs pages from public docs set |
+| `/examples` | ExamplesPage | Public | Code snippets + sample-app links |
 | `/about` | AboutPage | Public | Mission, project story, differentiators, creator profile |
 | `/contact` | ContactPage | Public | Contact methods, support info, FAQ |
 | `/privacy` | PrivacyPage | Public | Privacy policy |
@@ -30,8 +31,10 @@
 
 | Route | Page | Access | Purpose |
 |------|------|--------|---------|
-| `/login` | LoginPage | Public | Sign in with Google |
-| `/signup` | SignupPage | Public | Sign up with Google / beta onboarding |
+| `/login` | LoginPage | Public | Sign in with Google (redirects to Laravel Socialite) |
+| `/signup` | SignupPage | Public | Same OAuth flow as `/login`; account auto-created on first callback |
+| `/auth/callback` | CallbackPage | Public | Receives the Sanctum token from Laravel's OAuth callback and persists it |
+| `/oauth/google-drive/callback` | DriveCallbackPage | Public | Receives Drive OAuth code and posts it to the Laravel backend |
 
 ### Protected Dashboard Routes
 
@@ -42,37 +45,45 @@
 | `/dashboard/apps/:appId` | AppDetailPage | Authenticated user | Per-app details, builds, channels, and rollout state |
 | `/dashboard/builds` | BuildsPage | Authenticated user | Browse/filter builds |
 | `/dashboard/builds/:buildId` | BuildDetailPage | Authenticated user | Detailed build record view |
-| `/dashboard/upload` | UploadPage | Authenticated user | Publish ZIP bundle and update manifests |
+| `/dashboard/upload` | UploadPage | Authenticated user | Publish ZIP bundle, write manifest |
 | `/dashboard/drive` | GoogleDrivePage | Authenticated user | Connect/disconnect Drive and review storage footprint |
 | `/dashboard/config` | ConfigPage | Authenticated user | Show recommended backend/config integration guidance |
-| `/dashboard/settings` | SettingsPage | Authenticated user | Account preferences, password flow, account deletion |
+| `/dashboard/settings` | SettingsPage | Authenticated user | Account preferences, account deletion |
 | `/dashboard/rollouts` | RolloutsPage | Authenticated user | Manage rollout percentages and pause/resume rollouts |
 | `/dashboard/analytics` | AnalyticsPage | Authenticated user | View aggregated update analytics |
 
-### Admin Routes
+### Admin Routes (SPA)
 
 | Route | Page | Access | Purpose |
 |------|------|--------|---------|
-| `/admin` | AdminOverview | Admin only | Admin overview metrics |
-| `/admin/users` | AdminUsersPage | Admin only | Search/browse user accounts |
-| `/admin/apps` | AdminAppsPage | Admin only | Search/browse all apps |
-| `/admin/builds` | AdminBuildsPage | Admin only | Search/filter all builds |
+| `/admin` | AdminOverview | `admin` or `super-admin` role | Admin overview metrics |
+| `/admin/users` | AdminUsersPage | `admin` or `super-admin` role | Search/browse user accounts |
+| `/admin/apps` | AdminAppsPage | `admin` or `super-admin` role | Search/browse all apps |
+| `/admin/builds` | AdminBuildsPage | `admin` or `super-admin` role | Search/filter all builds |
+
+### Admin Routes (Nova)
+
+Laravel Nova 5 lives at `/nova` on the backend host. Same MySQL store, separate UI. Resources include User, App, ApiKey, SigningKey, Build, Subscription, AnalyticsEvent. Custom Nova actions exist for rotating signing keys, promoting builds, etc.
 
 ## Access and Guard Behavior
 
-### ProtectedRoute
+### ProtectedRoute (SPA)
+
+- Requires a Sanctum token stored in `@capacitor/preferences` (native) or `localStorage` (web)
+- The 401-handling axios interceptor clears the token and event-broadcasts a logout, redirecting to `/login`
+- Token is sent as a `Bearer` header on every `/api/dashboard/*` and `/api/admin/*` request
 
-- Requires authenticated user
-- Computes email verification from Firebase auth state or Google provider context
-- Redirects unauthenticated users to `/login`
-- If email verification is required and not satisfied, redirects to `/verify-email`
+### AdminRoute (SPA)
 
-### AdminRoute
+- Requires a Sanctum token AND the SPA-side cached `me.roles` to include `admin` or `super-admin`
+- Backend enforcement: every Laravel admin route also carries `auth:sanctum` + `can:<permission>` middleware; an unauthorized request returns 403 regardless of SPA state
 
-- Requires authenticated user
-- loads the Firestore user document
-- allows access only when `isAdmin === true`
-- redirects non-admin users to `/dashboard`
+### Backend gate model
+
+- `auth:sanctum` middleware on `/api/dashboard/*` and `/api/admin/*`
+- `can:<permission>` middleware on every dashboard/admin route (per-permission, not per-role)
+- `Gate::before` returns `true` for any user with the `super-admin` role (full bypass)
+- First sign-in assigns the `user` role; emails in `ADMIN_EMAILS` env auto-assign `super-admin`
 
 ## User Types and Permissions
 
@@ -83,19 +94,23 @@
 
 ### Signed-In Product User
 
-- Signs in via Google popup
-- has a Firestore `users/{uid}` document
+- Signs in via Google (Laravel Socialite redirect)
+- has a MySQL `users` row keyed by `google_id`
+- holds a Sanctum personal access token (default 7-day TTL, configurable via `SANCTUM_TOKEN_EXPIRATION`)
+- carries the `user` role by default
 - can manage their own apps/builds/settings
-- can connect Google Drive
+- can connect Google Drive (server-side OAuth — tokens encrypted at rest on the User row)
 
 ### Admin User
 
-- Same as signed-in user plus `isAdmin: true`
-- can access admin metrics and cross-user inventories
+- Same as signed-in user plus `admin` or `super-admin` role
+- can access SPA admin pages and Nova admin
+- super-admin bypasses every `can:` gate
 
 ### App Runtime Consumer
 
 - Uses plugin APIs and manifest endpoints
+- authenticates with a per-app API key (separate `ValidateApiKey` middleware on `/api/v1/*`)
 - not a website operator account
 
 ## Page-Level Notes
@@ -129,10 +144,15 @@
 - DocsPage acts as a rich docs landing surface
 - DocsMarkdownPage renders markdown docs pages from the public docs payload
 
+### ExamplesPage
+
+- Hero + quick-start code snippets (OTA basic, React hook, background, app-store, self-hosted backend pattern)
+- Two canonical example-app cards (React + Capacitor, Node.js + Express)
+
 ### SitemapPage and FeedPage
 
 - Search/filter style discovery experiences
-- use `Input` fields for route/content lookup
+- use Input fields for route/content lookup
 - intended as human-friendly content navigation surfaces
 
 ### DashboardOverview
@@ -143,8 +163,8 @@
 ### AppsPage
 
 - Central app management page
-- create/edit/delete dialog workflows
-- stores package id, description, platforms, and generates API key on creation
+- create/edit/delete dialog workflows (URL-state driven: `?formMode`, `?editId`, `?deleteId`)
+- stores package id, description, platforms, and generates an API key on creation
 
 ### AppDetailPage
 
@@ -161,27 +181,26 @@
 ### UploadPage
 
 - Core publish UI
-- requires Google Drive connection
-- uploads ZIP bundle and file manifest
-- publishes Firestore manifest data
+- requires Google Drive connection (server-side OAuth must be completed)
+- multipart-POST ZIP to Laravel `/api/dashboard/apps/{app}/builds`
+- Laravel computes SHA-256, signs with the app's signing key, stages in user's Drive, persists Build row in MySQL
 
 ### GoogleDrivePage
 
-- connects/disconnects Drive
+- starts the Drive OAuth flow (`/api/dashboard/google-drive/auth-url` → full-window Google redirect → `/oauth/google-drive/callback` → POST code to backend)
 - shows Drive connection status, connected email, folder list, file count, and total size
 
 ### ConfigPage
 
 - instructional/configuration surface
-- presents recommended production path: browser upload to Google Drive + Firestore metadata publishing + app-side reads
+- presents the recommended path: dashboard publishes through the Laravel backend; plugin polls the Laravel manifest endpoint
 
 ### SettingsPage
 
 - account profile details
-- preferences
-- appearance
-- password change for email/password providers
-- account deletion confirmation flow
+- preferences (`users.preferences` JSON column via `/api/dashboard/preferences`)
+- appearance/theme controls
+- account deletion confirmation flow (Sanctum tokens revoked, MySQL row soft-deleted, encrypted Drive tokens cleared)
 
 ### RolloutsPage
 
@@ -193,7 +212,7 @@
 ### AnalyticsPage
 
 - filters by app and channel
-- aggregates analytics batch data across time range
+- aggregates analytics data across time range from `analytics_events` table
 - intended for download/install/error/rollback analysis
 
 ### Admin Pages
@@ -202,18 +221,19 @@
 - AdminUsersPage supports user search/filtering
 - AdminAppsPage supports app search/filtering
 - AdminBuildsPage supports build search/filtering by multiple fields
+- Full admin tooling (resource editors, custom actions) lives in Nova at `/nova`
 
 ## Form and Input Inventory
 
 ### LoginPage
 
-- **Action:** Google sign-in button
+- **Action:** Google sign-in button → SPA navigates to `${VITE_API_URL}/auth/google/redirect`
 - **Inputs:** No text input fields
-- **Errors handled:** popup closed, popup blocked, generic auth failure
+- **Errors handled:** popup blocked (unlikely with full-window redirect), generic OAuth failure displayed on `/auth/callback`
 
 ### SignupPage
 
-- **Action:** Google sign-up button
+- **Action:** Same Google flow as LoginPage; backend auto-provisions the User row + assigns `user` role
 - **Inputs:** No text input fields
 - **Purpose:** fast account creation for beta onboarding
 
@@ -228,16 +248,15 @@
   - app name required, minimum length
   - package ID required and regex-validated
   - at least one platform required
-- **Side effects on create:**
-  - creates app doc
-  - generates API key
-  - creates `apiKeys/{apiKey}` doc
-  - increments user `appsCount`
+- **Backend side effects on create (Laravel `AppController` + `UpdateBuildRequest`):**
+  - inserts row in `apps` table (RBAC-gated by `can:apps.create`)
+  - generates an API key, inserts row in `api_keys` table
+  - increments user `apps_count`
 
 ### AppsPage Delete Dialog
 
 - **Purpose:** destructive app deletion
-- **Effects:** deletes manifests under app API key, deletes API key doc, deletes app doc, decrements user `appsCount`
+- **Backend side effects:** soft-deletes app row, revokes related API keys, decrements user `apps_count`, optionally archives builds
 
 ### UploadPage Publish Form
 
@@ -249,21 +268,18 @@
   - version input
   - build number input
   - release notes textarea
-- **Validation:**
-  - app required
-  - version required
-  - build number required
-  - ZIP file required
-  - Drive connection required
+- **Validation (server-side `UpdateBuildRequest` FormRequest):**
+  - app_id required + ownership-checked
+  - version required + semver-validated
+  - build_number required + numeric
+  - ZIP file required + max-size enforced
+  - Drive connection required (backend rejects otherwise)
 - **Flow:**
-  - validate file
-  - calculate SHA-256
-  - generate file manifest
-  - upload ZIP to Drive
-  - upload manifest JSON to Drive
-  - write build doc
-  - update Firestore manifest docs
-  - navigate to app detail
+  - browser multipart POST → Laravel `/api/dashboard/apps/{app}/builds`
+  - Laravel validates, computes SHA-256, signs with RSA-SHA256 using the app's signing key
+  - Laravel uploads the ZIP to the user's Drive folder (server-side OAuth tokens)
+  - Laravel writes the Build row, updates the App's active manifest pointer
+  - SPA navigates to app detail
 
 ### SettingsPage Preferences
 
@@ -272,31 +288,19 @@
   - update notifications toggle
   - theme select
   - language select
-- **Action:** save preferences to user doc
-
-### SettingsPage Change Password
-
-- **Fields:**
-  - current password
-  - new password
-  - confirm new password
-- **Validation:**
-  - required fields
-  - minimum new password length
-  - confirmation match
-- **Special note:** only shown for email/password provider, not Google-only users
+- **Action:** PATCH `/api/dashboard/preferences` → updates `users.preferences` JSON column
 
 ### SettingsPage Delete Account
 
 - **Field:** confirmation input requiring exact `DELETE`
-- **Action:** delete Firestore user doc and Firebase auth user
+- **Action:** DELETE `/api/dashboard/me` → revokes Sanctum tokens, soft-deletes user row, clears encrypted Drive tokens, cascades to apps/builds
 
 ### RolloutsPage Edit Modal
 
 - **Fields:**
   - rollout percentage numeric input
   - rollout percentage range slider
-- **Action:** update `rollout.percentage`
+- **Action:** PATCH `/api/dashboard/builds/{build}/rollout` → updates rollout config on the Build row
 
 ### BuildsPage Filters
 
@@ -305,12 +309,13 @@
 - channel filter
 - platform filter
 - status filter
+- URL-state driven (`?q=`, `?app=`, `?channel=`, `?platform=`, `?status=`, `?page=`)
 
 ### AdminBuildsPage Filters
 
 - search input
 - app filter
-- user filter or owner-related filtering
+- user filter
 - channel/status/platform filters
 
 ### AdminUsersPage Filters
@@ -339,8 +344,9 @@
 ## Important UX and Product Notes
 
 - Dashboard is clearly owner/operator tooling, not consumer UI
-- Google sign-in is primary auth path
-- Google Drive is central to the no-cost publishing workflow
+- Google sign-in is the only auth path
+- Google Drive is central to the publishing workflow (server-side OAuth, not browser SDK)
 - App creation is a prerequisite for upload
 - Drive connection is a prerequisite for upload
-- Rollouts are edited from manifest data, not from a separate dedicated rollout service
+- Rollouts are edited on the Build row, not from a separate dedicated rollout service
+- All user-visible state that should survive refresh (modal open, edit/delete dialogs, filters, tabs) is encoded in URL search params via the shared `useUrlState` hooks