native-update 1.4.8 → 2.0.0

package/docs/features/laravel-nova-backend/progress-tracker.json

@@ -0,0 +1,184 @@
+{
+  "feature": "Laravel + Nova Backend for Native Update",
+  "created": "2026-03-28",
+  "lastUpdated": "2026-03-28",
+  "status": "in_progress",
+  "estimatedWeeks": 5,
+  "currentPhase": 3,
+  "phases": [
+    {
+      "id": 1,
+      "name": "Laravel Project Setup",
+      "status": "completed",
+      "completedAt": "2026-03-28",
+      "estimatedDays": 5,
+      "tasks": [
+        { "task": "Create Laravel 11 project", "status": "completed" },
+        { "task": "Install and configure Nova 5", "status": "completed" },
+        { "task": "Configure MySQL database", "status": "completed", "note": "Using SQLite for dev, MySQL for production" },
+        { "task": "Set up Firebase token validation middleware", "status": "completed" },
+        { "task": "Configure S3/Cloudflare R2 storage", "status": "partial", "note": "Config added, needs keys" },
+        { "task": "Set up development environment (.env)", "status": "completed" }
+      ]
+    },
+    {
+      "id": 2,
+      "name": "Database Schema & Models",
+      "status": "completed",
+      "completedAt": "2026-03-28",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Create users migration and model", "status": "completed" },
+        { "task": "Create apps migration and model", "status": "completed" },
+        { "task": "Create builds migration and model", "status": "completed" },
+        { "task": "Create api_keys migration and model", "status": "completed" },
+        { "task": "Create subscriptions migration and model", "status": "completed" },
+        { "task": "Create device_activities migration and model", "status": "completed" },
+        { "task": "Create signing_keys migration and model", "status": "completed" },
+        { "task": "Set up model relationships", "status": "completed" }
+      ]
+    },
+    {
+      "id": 3,
+      "name": "API Endpoints",
+      "status": "in_progress",
+      "estimatedDays": 5,
+      "tasks": [
+        { "task": "Create ValidateApiKey middleware", "status": "completed" },
+        { "task": "Create ValidateFirebaseToken middleware", "status": "completed" },
+        { "task": "Create UpdateController (check for updates)", "status": "completed" },
+        { "task": "Create BundleController (upload, download)", "status": "completed" },
+        { "task": "Create AnalyticsController (MAU ping)", "status": "completed" },
+        { "task": "Create AppController (dashboard CRUD)", "status": "pending" },
+        { "task": "Create ApiKeyController (key management)", "status": "pending" },
+        { "task": "Create SubscriptionController (billing)", "status": "pending" },
+        { "task": "Set up API routes", "status": "completed" },
+        { "task": "Add rate limiting", "status": "pending" }
+      ]
+    },
+    {
+      "id": 4,
+      "name": "Stripe Integration",
+      "status": "partial",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Install Laravel Cashier", "status": "completed" },
+        { "task": "Configure Stripe API keys", "status": "pending", "note": "Config added, needs keys" },
+        { "task": "Create pricing plans in Stripe", "status": "pending" },
+        { "task": "Implement checkout session creation", "status": "pending" },
+        { "task": "Implement customer portal redirect", "status": "pending" },
+        { "task": "Create webhook handler", "status": "pending" },
+        { "task": "Handle subscription lifecycle events", "status": "pending" },
+        { "task": "Implement MAU overage billing", "status": "pending" }
+      ]
+    },
+    {
+      "id": 5,
+      "name": "Bundle Signing & Security",
+      "status": "completed",
+      "completedAt": "2026-03-28",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Create BundleSigningService", "status": "completed", "note": "In SigningKey model" },
+        { "task": "Implement RSA key pair generation", "status": "completed" },
+        { "task": "Implement RSA-PSS signing", "status": "completed" },
+        { "task": "Create SignedUrlService", "status": "completed", "note": "Using Laravel's built-in signed URLs" },
+        { "task": "Implement time-limited download URLs", "status": "completed" },
+        { "task": "Add device binding to URLs", "status": "completed" },
+        { "task": "Implement one-time download tokens", "status": "pending" },
+        { "task": "Add request signature validation (replay protection)", "status": "pending" }
+      ]
+    },
+    {
+      "id": 6,
+      "name": "Nova Admin Panel",
+      "status": "pending",
+      "estimatedDays": 4,
+      "tasks": [
+        { "task": "Create User Nova resource", "status": "completed", "note": "Auto-generated by Nova install" },
+        { "task": "Create App Nova resource", "status": "pending" },
+        { "task": "Create Build Nova resource", "status": "pending" },
+        { "task": "Create Subscription Nova resource", "status": "pending" },
+        { "task": "Create ApiKey Nova resource", "status": "pending" },
+        { "task": "Create Main dashboard (revenue, usage)", "status": "pending" },
+        { "task": "Add admin actions (suspend, adjust plan)", "status": "pending" },
+        { "task": "Add metrics cards and charts", "status": "pending" }
+      ]
+    },
+    {
+      "id": 7,
+      "name": "Plugin Updates",
+      "status": "pending",
+      "estimatedDays": 3,
+      "tasks": [
+        { "task": "Add apiKey to PluginInitConfig in definitions.ts", "status": "pending" },
+        { "task": "Add X-API-Key header to HTTP requests in plugin.ts", "status": "pending" },
+        { "task": "Add MAU ping endpoint call", "status": "pending" },
+        { "task": "Update iOS SecureStorage for API key", "status": "pending" },
+        { "task": "Update Android SecureStorage for API key", "status": "pending" },
+        { "task": "Update documentation", "status": "pending" }
+      ]
+    },
+    {
+      "id": 8,
+      "name": "Migration & Testing",
+      "status": "pending",
+      "estimatedDays": 5,
+      "tasks": [
+        { "task": "Write unit tests for API key validation", "status": "pending" },
+        { "task": "Write unit tests for bundle signing", "status": "pending" },
+        { "task": "Write unit tests for MAU calculation", "status": "pending" },
+        { "task": "Write integration tests for upload flow", "status": "pending" },
+        { "task": "Write integration tests for download flow", "status": "pending" },
+        { "task": "Write integration tests for Stripe flow", "status": "pending" },
+        { "task": "Create Firebase user sync script", "status": "pending" },
+        { "task": "Deploy to staging environment", "status": "pending" },
+        { "task": "Perform end-to-end testing", "status": "pending" },
+        { "task": "Deploy to production", "status": "pending" },
+        { "task": "Monitor and fix issues", "status": "pending" }
+      ]
+    }
+  ],
+  "decisions": {
+    "keepFirebaseAuth": true,
+    "keepGoogleDrive": "optional-free-tier",
+    "primaryStorage": "s3-or-r2",
+    "adminPanel": "laravel-nova",
+    "paymentProcessor": "stripe",
+    "mauTracking": "device-hash-monthly"
+  },
+  "pricingTiers": [
+    { "name": "Free", "price": 0, "mauLimit": 1000, "appsLimit": 1 },
+    { "name": "Pro", "price": 29, "mauLimit": 10000, "appsLimit": 5 },
+    { "name": "Enterprise", "price": 199, "mauLimit": 100000, "appsLimit": -1 }
+  ],
+  "securityFeatures": [
+    "api-key-authentication",
+    "firebase-token-validation",
+    "rsa-pss-bundle-signing",
+    "signed-download-urls",
+    "device-binding",
+    "rate-limiting",
+    "replay-attack-prevention"
+  ],
+  "completedToday": [
+    "Laravel 11 + Nova 5 project created in /backend",
+    "All database migrations created and run",
+    "All models with relationships created",
+    "API key validation middleware created",
+    "Firebase token validation middleware created",
+    "Update check API endpoint created",
+    "Bundle download API with signed URLs created",
+    "Analytics/MAU tracking API created",
+    "RSA key generation and signing in SigningKey model",
+    "Laravel Cashier, Firebase SDK, AWS SDK installed"
+  ],
+  "blockers": [],
+  "notes": [
+    "Nova license configured globally",
+    "Stripe API keys needed",
+    "Firebase service account JSON needed",
+    "S3/R2 bucket and keys needed",
+    "Current plugin already supports HTTP backend - minimal changes needed"
+  ]
+}

package/docs/guides/no-cost-backend-implementation-plan.md

@@ -0,0 +1,77 @@
+# No-Cost Backend Implementation Plan
+
+This document is the concrete production plan for the `website` sub-project using a no-cost backend built from browser code, Firestore, and Google Drive.
+
+## Architecture
+
+- Dashboard: `website`
+- Metadata backend: Firestore
+- Bundle storage: user-owned Google Drive
+- App manifest read path: `apiKeys/{apiKey}/manifests/{channel}`
+- Compatibility read path: `manifests/{appId}_{channel}`
+- Human discovery endpoints: `/sitemap`, `/feed`
+- Machine discovery endpoints: `/sitemap.xml`, `/feed.xml`
+
+## Publish Flow
+
+1. User signs into the website dashboard.
+2. User connects Google Drive.
+3. User uploads a ZIP bundle from the dashboard.
+4. The website computes bundle checksum and manifest metadata in-browser.
+5. The website uploads the ZIP and generated manifest JSON to Google Drive.
+6. The website writes build history to Firestore.
+7. The website updates both manifest documents:
+   - `apiKeys/{apiKey}/manifests/{channel}`
+   - `manifests/{appId}_{channel}`
+8. Apps configured with `backendType: 'firestore'` read the latest manifest and download the published ZIP from Google Drive.
+
+## Firestore Collections
+
+- `apps/{appId}`
+  - dashboard-owned app registry and channel settings
+- `builds/{buildId}`
+  - uploaded build history, Drive URLs, release notes, checksums
+- `apiKeys/{apiKey}`
+  - secret lookup key metadata for manifest access
+- `apiKeys/{apiKey}/manifests/{channel}`
+  - primary manifest document for app update checks
+- `manifests/{appId}_{channel}`
+  - compatibility manifest document for existing readers
+
+## Security Model
+
+- Firestore rules allow public read only for manifest documents that apps need.
+- App, build, and API key documents stay owner-restricted.
+- Browser code does not hold server secrets.
+- Google Drive is used because the asset owner controls storage without paid compute.
+
+## Website Responsibilities
+
+- Keep dashboard configuration examples aligned with Firestore backend usage.
+- Keep upload flow routed through `uploadBundle()`.
+- Keep footer links to `/sitemap` and `/feed`.
+- Keep `scripts/generate-sitemap.mjs` current whenever routes or public content change.
+
+## Package Responsibilities
+
+- Support Firestore manifest reads through `backendType: 'firestore'`.
+- Accept `firestore.projectId` and optional `firestore.apiKey` in public config types.
+- Preserve HTTP backend support for users who self-host.
+
+## When A Separate Backend Is Justified
+
+Only add Laravel or another backend if one of these becomes mandatory:
+
+- server-held private signing keys
+- private asset proxy/download authorization
+- scheduled rollout jobs or cleanup tasks
+- heavy processing such as delta generation outside the browser
+
+## Production Checklist
+
+- Dashboard can connect Google Drive
+- ZIP publish updates Firestore manifest documents
+- App config snippets use `backendType: 'firestore'`
+- `/sitemap`, `/sitemap.xml`, `/feed`, and `/feed.xml` build successfully
+- Firestore rules are deployed
+- Google OAuth and Firebase environment variables are configured

package/docs/guides/no-cost-firestore-google-drive-backend.md

@@ -0,0 +1,60 @@
+# No-Cost Backend Architecture
+
+This project's recommended zero-cost backend uses:
+
+- `website/` as the dashboard and publishing UI
+- Firestore for manifest metadata and rollout state
+- Google Drive for bundle and manifest file storage
+- direct browser uploads instead of server-side processing
+
+## Why this architecture
+
+- avoids Firebase Functions and other paid compute
+- keeps bundle ownership in each user's own Google Drive
+- uses Firestore's free tier for lightweight manifest reads
+- supports staged rollout metadata without custom backend code
+
+## Publish flow
+
+1. User signs in to the website.
+2. User connects Google Drive.
+3. User uploads a ZIP bundle.
+4. Website calculates SHA-256 and generates a file manifest in-browser.
+5. Website uploads the bundle and generated manifest JSON to Google Drive.
+6. Website writes the published version into Firestore.
+7. Apps read Firestore manifests and download the bundle from Google Drive.
+
+## Firestore documents
+
+Recommended secure path:
+
+- `/apiKeys/{apiKey}/manifests/{channel}`
+
+Backward-compatible path:
+
+- `/manifests/{appId}_{channel}`
+
+The dashboard publishes both today. New integrations should prefer the API key path.
+
+## Operational limits
+
+- bundle files must be reachable by the app, so Google Drive files are published with direct-download access
+- there is no trusted server for private signing keys, cron jobs, or private bundle proxying
+- if you later need private downloads, server-side signing, scheduled jobs, or delta generation, add a real backend
+
+## Required dashboard capabilities
+
+- app creation with generated API keys
+- Google Drive connect/disconnect
+- ZIP bundle upload and publish
+- rollout editing in Firestore
+- copy-paste integration config for apps
+
+## Production checklist
+
+- connect Google Drive before first publish
+- publish ZIP bundles only
+- keep API keys out of public repos
+- sign bundles client-side or via CLI if you need signature verification
+- verify Firestore rules before launch
+- test download/install flow on real devices

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

@@ -0,0 +1,218 @@
+# Native Update System Overview
+
+## Metadata
+
+- **Reference Date:** 2026-03-16
+- **Last Updated:** 2026-03-16
+
+## Project Identity
+
+- **Name:** Native Update
+- **Package:** `native-update`
+- **Type:** Open-source Capacitor plugin plus update management platform
+- **Primary Creator:** Ahsan Mahmood
+- **Primary Contact:** aoneahsan@gmail.com
+- **License:** MIT
+
+## Core Mission
+
+Native Update exists to reduce the operational complexity of shipping updates in Capacitor apps. It unifies OTA updates, native app update flows, in-app reviews, release manifests, rollout controls, and management tooling into one ecosystem.
+
+## Core Product Layers
+
+### 1. Plugin Layer
+
+The plugin provides the runtime capabilities inside a Capacitor app:
+
+- OTA/live update checks and bundle handling
+- app update checks and prompts
+- in-app review requests
+- background update scheduling
+- security validation logic
+- Firestore-backed manifest reading support
+
+### 2. Dashboard Layer
+
+The website provides a management surface for:
+
+- user auth
+- app creation and app management
+- build uploads
+- rollout visibility and control
+- analytics review
+- Google Drive connection and storage management
+- configuration generation
+- admin-only oversight pages
+
+### 3. Docs Layer
+
+The docs explain:
+
+- installation and setup
+- features and APIs
+- examples and advanced scenarios
+- security, deployment, testing, and troubleshooting
+- migration from other approaches
+- planning, tracking, roadmap, audit, and report history
+
+### 4. Tooling Layer
+
+The project includes:
+
+- CLI commands
+- bundle creation/signing/verification utilities
+- backend templates and examples
+- local development scripts
+
+## What The Product Solves
+
+Capacitor teams often need several disconnected systems to handle:
+
+- web asset updates
+- store version upgrades
+- review prompts
+- release rollout control
+- security verification
+- app/build administration
+
+Native Update consolidates those concerns into one project with a common mental model.
+
+## Main Feature Areas
+
+### Live / OTA Updates
+
+- Deliver JavaScript, HTML, and CSS changes without app store review
+- Support update channels
+- Manage version checks and bundle downloads
+- Support checksum and signature validation
+- Enable rollback-aware update flows
+- Support delta patch concepts and file manifests
+
+### Native App Updates
+
+- Check for newer native binary versions
+- Support immediate and flexible update strategies
+- Integrate with Android and iOS update behavior
+
+### In-App Reviews
+
+- Request native reviews
+- respect timing/rate limiting logic
+- support user-experience-aware prompting
+
+### Background Updates
+
+- Schedule checks while app is not active
+- support native notification behavior
+- provide background configuration hooks
+
+### Security
+
+- signing
+- checksum verification
+- HTTPS-first posture
+- certificate pinning support
+- validation helpers
+
+### Release Operations
+
+- upload build ZIPs
+- generate file manifests
+- publish app-facing manifests
+- configure rollout percentages
+- manage app/channel/build metadata
+
+## Current Product Surfaces
+
+### Public Website
+
+- `/`
+- `/features`
+- `/pricing`
+- `/docs`
+- `/docs/*`
+- `/about`
+- `/contact`
+- `/privacy`
+- `/terms`
+- `/data-deletion`
+- `/cookies`
+- `/security`
+- `/sitemap`
+- `/feed`
+
+### Auth Pages
+
+- `/login`
+- `/signup`
+
+### Protected Dashboard
+
+- `/dashboard`
+- `/dashboard/apps`
+- `/dashboard/apps/:appId`
+- `/dashboard/builds`
+- `/dashboard/builds/:buildId`
+- `/dashboard/upload`
+- `/dashboard/drive`
+- `/dashboard/config`
+- `/dashboard/settings`
+- `/dashboard/rollouts`
+- `/dashboard/analytics`
+
+### Admin Area
+
+- `/admin`
+- `/admin/users`
+- `/admin/apps`
+- `/admin/builds`
+
+## User Types
+
+### Public Visitor
+
+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.
+
+### Admin User
+
+An authenticated user whose Firestore user document has `isAdmin: true`. Admins can access `/admin` pages for broader oversight.
+
+### Mobile App Client
+
+Not a dashboard user, but an app-side runtime consumer of manifests, update metadata, and plugin APIs.
+
+### Developer / Maintainer
+
+Works in the codebase, docs, CLI, native code, example apps, and release infrastructure.
+
+## 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`.
+
+## 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.
+
+## 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 dashboard as owner/operator tooling, not end-user mobile UI.
+- Treat security, rollout control, and documentation quality as important project values.
+
+## Important Known Context
+
+- 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.