native-update 1.4.8 → 2.0.0

package/docs/features/laravel-nova-backend/IMPLEMENTATION-PLAN.md

@@ -0,0 +1,504 @@
+# Native Update - Laravel + Nova Backend Implementation Plan
+
+**Created:** 2026-03-28
+**Status:** Planning Complete
+**Goal:** Transform native-update from a free Firebase-based system to a paid SaaS with Laravel + Nova backend
+
+---
+
+## Context
+
+### Why This Change Is Needed
+
+The native-update project is currently a fully functional OTA update system for Capacitor apps using a "no-cost" architecture (Firebase Auth + Firestore + Google Drive). However, to become a **paid commercial service** like Ionic AppFlow, we need:
+
+1. **Licensing & API Keys** - Secure server-side key validation
+2. **Stripe Payments** - Subscription management, usage-based billing (MAU)
+3. **Secure Downloads** - API key-authenticated bundle downloads
+4. **Server-Side Signing** - Private RSA keys held server-side
+5. **Admin Dashboard** - Nova-powered backend for management
+
+### Current State Assessment
+
+| Component | Status | Production Ready |
+|-----------|--------|------------------|
+| TypeScript Plugin Core | Excellent | YES |
+| Android Native | Good (minor fixes) | YES |
+| iOS Native | Good (minor fixes) | YES |
+| Firestore Schema | Complete | YES |
+| Website (React) | Complete | YES |
+| Security (Crypto) | Excellent | YES |
+
+**The plugin itself is production-ready.** This plan focuses on the backend infrastructure for commercialization.
+
+---
+
+## Architecture Decision
+
+### Keep vs Migrate
+
+| Component | Decision | Rationale |
+|-----------|----------|-----------|
+| **Frontend (React + Radix)** | KEEP | Working well, no migration needed |
+| **Firebase Auth** | KEEP | Google OAuth working, validate tokens in Laravel |
+| **Firestore** | MIGRATE to MySQL | Laravel needs relational data for billing |
+| **Google Drive Storage** | OPTIONAL | Keep for free tier, add S3/R2 for paid |
+| **Bundle Distribution** | MIGRATE | Laravel signed URLs for secure downloads |
+
+### Final Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         FINAL ARCHITECTURE                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│  ┌─────────────┐     ┌─────────────────────┐     ┌──────────────┐  │
+│  │ React       │────▶│ Laravel API         │────▶│ MySQL        │  │
+│  │ Dashboard   │     │ (API + Nova Admin)  │     │ Database     │  │
+│  │ (existing)  │     │                     │     │              │  │
+│  └─────────────┘     │ - Stripe webhooks   │     └──────────────┘  │
+│        │             │ - Bundle signing    │            │          │
+│        │             │ - API key auth      │            │          │
+│        ▼             │ - MAU tracking      │            ▼          │
+│  ┌─────────────┐     └─────────────────────┘     ┌──────────────┐  │
+│  │ Firebase    │              │                  │ S3/R2        │  │
+│  │ Auth        │              │                  │ (bundles)    │  │
+│  │ (keep)      │              ▼                  │              │  │
+│  └─────────────┘     ┌─────────────────────┐     └──────────────┘  │
+│                      │ Mobile Apps         │                       │
+│                      │ - API key auth      │                       │
+│                      │ - Signed URL DL     │                       │
+│                      └─────────────────────┘                       │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Laravel Project Setup (Week 1)
+
+**Tasks:**
+1. Create Laravel 11 project with Nova 5
+2. Configure MySQL database
+3. Set up authentication (Firebase token validation middleware)
+4. Configure S3/Cloudflare R2 for bundle storage
+5. Set up development environment
+
+**Files to Create:**
+```
+backend/
+├── app/
+│   ├── Http/
+│   │   ├── Middleware/
+│   │   │   ├── ValidateFirebaseToken.php
+│   │   │   ├── ValidateApiKey.php
+│   │   │   └── ValidateRequestSignature.php
+│   │   └── Controllers/
+│   │       └── Api/
+│   │           ├── UpdateController.php
+│   │           ├── BundleController.php
+│   │           └── AnalyticsController.php
+│   ├── Models/
+│   │   ├── User.php
+│   │   ├── App.php
+│   │   ├── Build.php
+│   │   ├── ApiKey.php
+│   │   ├── Subscription.php
+│   │   └── DeviceActivity.php
+│   ├── Services/
+│   │   ├── BundleSigningService.php
+│   │   ├── SignedUrlService.php
+│   │   └── MAUService.php
+│   └── Nova/
+│       ├── User.php
+│       ├── App.php
+│       ├── Build.php
+│       ├── Subscription.php
+│       └── Dashboards/
+│           └── Main.php
+├── config/
+│   ├── firebase.php
+│   └── stripe.php
+├── database/
+│   └── migrations/
+│       ├── create_users_table.php
+│       ├── create_apps_table.php
+│       ├── create_builds_table.php
+│       ├── create_api_keys_table.php
+│       ├── create_subscriptions_table.php
+│       └── create_device_activities_table.php
+└── routes/
+    ├── api.php
+    └── web.php
+```
+
+### Phase 2: Database Schema & Models (Week 1-2)
+
+**Core Tables:**
+
+```sql
+-- users (synced from Firebase)
+CREATE TABLE users (
+    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
+    firebase_uid VARCHAR(128) UNIQUE NOT NULL,
+    email VARCHAR(255) UNIQUE NOT NULL,
+    name VARCHAR(255),
+    avatar_url TEXT,
+    plan ENUM('free', 'pro', 'enterprise') DEFAULT 'free',
+    stripe_customer_id VARCHAR(255),
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP
+);
+
+-- apps
+CREATE TABLE apps (
+    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
+    user_id BIGINT UNSIGNED NOT NULL,
+    app_id VARCHAR(255) NOT NULL,  -- com.example.app
+    name VARCHAR(255) NOT NULL,
+    platforms JSON,  -- ['ios', 'android']
+    channels JSON,   -- {production: {}, staging: {}}
+    public_key TEXT, -- RSA public key (auto-generated)
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id),
+    UNIQUE KEY (user_id, app_id)
+);
+
+-- api_keys
+CREATE TABLE api_keys (
+    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
+    app_id BIGINT UNSIGNED NOT NULL,
+    key_hash VARCHAR(64) NOT NULL,  -- SHA-256 of full key
+    key_prefix VARCHAR(20) NOT NULL, -- nu_app_abc123... (for display)
+    name VARCHAR(255),
+    type ENUM('app', 'admin') DEFAULT 'app',
+    status ENUM('active', 'deprecated', 'revoked') DEFAULT 'active',
+    permissions JSON,
+    rate_limit INT DEFAULT 60,
+    last_used_at TIMESTAMP,
+    expires_at TIMESTAMP,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    FOREIGN KEY (app_id) REFERENCES apps(id),
+    INDEX (key_hash),
+    INDEX (status)
+);
+
+-- builds
+CREATE TABLE builds (
+    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
+    app_id BIGINT UNSIGNED NOT NULL,
+    bundle_id VARCHAR(255) NOT NULL,
+    version VARCHAR(50) NOT NULL,
+    build_number INT,
+    channel ENUM('production', 'staging', 'development') DEFAULT 'production',
+    platform ENUM('ios', 'android', 'web', 'all') DEFAULT 'all',
+    storage_path TEXT NOT NULL,
+    storage_provider ENUM('s3', 'r2', 'drive') DEFAULT 's3',
+    file_size BIGINT UNSIGNED,
+    checksum VARCHAR(64) NOT NULL,  -- SHA-256
+    signature TEXT,  -- RSA-PSS signature
+    release_notes TEXT,
+    mandatory BOOLEAN DEFAULT FALSE,
+    min_native_version VARCHAR(50),
+    rollout_percentage INT DEFAULT 100,
+    status ENUM('uploading', 'processing', 'active', 'archived', 'failed') DEFAULT 'uploading',
+    download_count INT DEFAULT 0,
+    install_count INT DEFAULT 0,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    FOREIGN KEY (app_id) REFERENCES apps(id),
+    INDEX (channel, status),
+    INDEX (version)
+);
+
+-- subscriptions
+CREATE TABLE subscriptions (
+    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
+    user_id BIGINT UNSIGNED NOT NULL,
+    stripe_subscription_id VARCHAR(255),
+    stripe_price_id VARCHAR(255),
+    plan ENUM('free', 'pro', 'enterprise') NOT NULL,
+    status ENUM('active', 'canceled', 'past_due', 'trialing') DEFAULT 'active',
+    mau_limit INT NOT NULL,  -- Monthly active users limit
+    apps_limit INT NOT NULL,
+    current_period_start TIMESTAMP,
+    current_period_end TIMESTAMP,
+    canceled_at TIMESTAMP,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    FOREIGN KEY (user_id) REFERENCES users(id)
+);
+
+-- device_activities (for MAU tracking)
+CREATE TABLE device_activities (
+    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
+    app_id BIGINT UNSIGNED NOT NULL,
+    device_hash VARCHAR(64) NOT NULL,  -- SHA-256 of device ID
+    platform ENUM('ios', 'android', 'web'),
+    app_version VARCHAR(50),
+    bundle_version VARCHAR(50),
+    month_key VARCHAR(7) NOT NULL,  -- '2026-03'
+    last_seen_at TIMESTAMP,
+    created_at TIMESTAMP,
+    FOREIGN KEY (app_id) REFERENCES apps(id),
+    UNIQUE KEY (app_id, device_hash, month_key),
+    INDEX (month_key)
+);
+
+-- signing_keys (RSA key pairs per app)
+CREATE TABLE signing_keys (
+    id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT,
+    app_id BIGINT UNSIGNED NOT NULL,
+    key_id VARCHAR(64) NOT NULL,  -- fingerprint
+    private_key_encrypted TEXT NOT NULL,  -- AES-256 encrypted
+    public_key TEXT NOT NULL,
+    status ENUM('active', 'rotated', 'revoked') DEFAULT 'active',
+    created_at TIMESTAMP,
+    rotated_at TIMESTAMP,
+    FOREIGN KEY (app_id) REFERENCES apps(id),
+    UNIQUE KEY (app_id, key_id)
+);
+```
+
+### Phase 3: API Endpoints (Week 2)
+
+**Mobile App API (API Key Auth):**
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/v1/updates/check` | Check for available updates |
+| GET | `/api/v1/bundles/{id}/download` | Download bundle (signed URL redirect) |
+| POST | `/api/v1/analytics/mau` | Report device activity |
+
+**Dashboard API (Firebase Token Auth):**
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/dashboard/apps` | List user's apps |
+| POST | `/api/dashboard/apps` | Create new app |
+| GET | `/api/dashboard/apps/{id}/builds` | List builds |
+| POST | `/api/dashboard/apps/{id}/builds` | Upload new build |
+| GET | `/api/dashboard/apps/{id}/keys` | List API keys |
+| POST | `/api/dashboard/apps/{id}/keys` | Generate API key |
+| GET | `/api/dashboard/subscription` | Get subscription status |
+| POST | `/api/dashboard/subscription/checkout` | Create Stripe checkout |
+
+**Webhook Endpoints:**
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/webhooks/stripe` | Stripe payment events |
+
+### Phase 4: Stripe Integration (Week 2-3)
+
+**Pricing Tiers:**
+
+| Plan | Price | MAU Limit | Apps | Features |
+|------|-------|-----------|------|----------|
+| Free | $0 | 1,000 | 1 | Basic updates, community support |
+| Pro | $29/mo | 10,000 | 5 | Rollouts, analytics, email support |
+| Enterprise | $199/mo | 100,000 | Unlimited | Delta updates, SLA, priority support |
+
+**MAU Overage:** $0.005 per MAU above limit
+
+**Implementation:**
+- Laravel Cashier for subscription management
+- Stripe Checkout for self-serve signup
+- Stripe Customer Portal for self-serve management
+- Webhook handling for subscription lifecycle
+
+### Phase 5: Bundle Signing & Security (Week 3)
+
+**Server-Side Signing Flow:**
+
+1. User uploads bundle via dashboard
+2. Laravel receives file, stores in S3/R2
+3. Calculate SHA-256 checksum
+4. Sign with app's private RSA key (RSA-PSS, SHA-256)
+5. Store signature in builds table
+6. Return signed metadata to mobile apps
+
+**Download Security:**
+
+1. Mobile app requests update check with API key
+2. Server validates API key + device eligibility
+3. Generate time-limited signed URL (5 minutes)
+4. URL bound to device ID hash
+5. One-time download token
+6. Mobile app downloads and verifies checksum + signature
+
+### Phase 6: Nova Admin Panel (Week 3-4)
+
+**Nova Resources:**
+- Users - View all users, subscriptions, apps
+- Apps - All apps across users
+- Builds - All builds, status management
+- Subscriptions - Revenue, plan management
+- ApiKeys - Key management, revocation
+- DeviceActivities - MAU reports
+
+**Nova Dashboards:**
+- Revenue Overview (MRR, churn, growth)
+- Usage Metrics (MAU, downloads, installs)
+- Build Analytics (success rate, rollback rate)
+
+**Nova Actions:**
+- Suspend User
+- Adjust Plan
+- Revoke API Key
+- Archive Build
+- Force Rollback
+
+### Phase 7: Plugin Updates (Week 4)
+
+**Changes to TypeScript Plugin:**
+
+1. Add `apiKey` to `PluginInitConfig`
+2. Add API key header to HTTP requests
+3. Add request signing (optional, for replay protection)
+4. Add MAU ping endpoint call
+
+**Files to Modify:**
+- `src/definitions.ts` - Add config interfaces
+- `src/plugin.ts` - Add headers to fetch requests
+- `src/core/config.ts` - API key validation
+
+**Native Changes (minimal):**
+- Store API key in secure storage (already supported)
+- No other changes needed
+
+### Phase 8: Migration & Testing (Week 4-5)
+
+**Migration Strategy:**
+
+1. Deploy Laravel backend alongside existing Firestore
+2. Sync Firebase users to MySQL
+3. Add HTTP backend support to plugin (already exists)
+4. Migrate apps one-by-one
+5. Deprecate Firestore (keep as fallback for 90 days)
+6. Full cutover
+
+**Testing Checklist:**
+- [ ] API key generation and validation
+- [ ] Bundle upload and signing
+- [ ] Secure download URLs
+- [ ] MAU tracking accuracy
+- [ ] Stripe subscription flow
+- [ ] Stripe webhook handling
+- [ ] Nova admin operations
+- [ ] Rate limiting
+- [ ] Error handling
+
+---
+
+## Security Architecture
+
+### API Key Format
+
+```
+nu_{type}_{random}_{checksum}
+
+Example: nu_app_a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890_f7d8
+```
+
+- `nu_` - Namespace prefix
+- `app_` or `adm_` - Key type
+- 64 hex chars - Cryptographically secure random
+- 4 hex chars - CRC-32 checksum
+
+### Request Authentication
+
+**Mobile Apps:**
+```http
+GET /api/v1/updates/check HTTP/1.1
+Host: api.nativeupdate.dev
+X-API-Key: nu_app_...
+X-Device-ID: device_hash
+X-Current-Version: 1.2.3
+X-Platform: ios
+```
+
+**Dashboard:**
+```http
+GET /api/dashboard/apps HTTP/1.1
+Host: api.nativeupdate.dev
+Authorization: Bearer {firebase_id_token}
+```
+
+### Bundle Signature Flow
+
+```
+1. Upload: bundle.zip
+2. Server: checksum = SHA-256(bundle.zip)
+3. Server: signature = RSA-PSS(checksum, private_key)
+4. Store: {checksum, signature, key_id}
+5. Mobile: verify RSA-PSS(checksum, signature, public_key)
+```
+
+---
+
+## File References
+
+### Critical Plugin Files
+- `/src/definitions.ts` - Add apiKey config
+- `/src/plugin.ts` - Add auth headers (lines 362-368)
+- `/src/core/security.ts` - Signature verification (existing)
+- `/ios/Plugin/Security/SecurityManager.swift` - iOS secure storage
+- `/android/.../SecurityManager.kt` - Android secure storage
+
+### Website Files to Update
+- `/website/src/services/bundle-upload-service.ts` - Change to Laravel API
+- `/website/src/services/auth-service.ts` - Keep Firebase, add token forwarding
+- `/website/src/stores/appsStore.ts` - Update API calls
+
+---
+
+## Verification Plan
+
+### Unit Tests
+- API key validation middleware
+- Bundle signing service
+- MAU calculation
+- Subscription tier enforcement
+
+### Integration Tests
+- Full upload → download flow
+- Stripe checkout → subscription active
+- MAU tracking → billing calculation
+- API key rotation
+
+### End-to-End Tests
+- Mobile app update check
+- Mobile app bundle download
+- Dashboard app creation
+- Dashboard build upload
+
+---
+
+## Timeline Summary
+
+| Week | Phase | Deliverables |
+|------|-------|--------------|
+| 1 | Setup + Schema | Laravel project, database, models |
+| 2 | APIs | Mobile + Dashboard API endpoints |
+| 2-3 | Stripe | Billing, subscriptions, webhooks |
+| 3 | Security | Signing, secure downloads |
+| 3-4 | Nova | Admin panel, dashboards |
+| 4 | Plugin | TypeScript + native updates |
+| 4-5 | Migration | Testing, gradual rollout |
+
+**Total: 5 weeks to production**
+
+---
+
+## Questions Resolved
+
+1. **Keep Google Drive?** - Optional for free tier, S3/R2 for paid
+2. **Keep Firebase Auth?** - YES, validate tokens in Laravel
+3. **Mobile auth?** - API keys with signed URLs for downloads
+4. **MAU tracking?** - Device hash + monthly aggregation
+5. **Admin panel?** - Nova with full resource management

package/docs/features/laravel-nova-backend/credentials.ignore.md

@@ -0,0 +1,34 @@
+# Laravel Nova Credentials (GITIGNORED)
+
+**File Pattern:** `*.ignore.*` - This file is excluded from git
+
+---
+
+## Nova License
+
+| Field | Value |
+|-------|-------|
+| Email | Sajawal.developer@gmail.com |
+| Key | koFe33Gb0rhbseLFlcUj4IGM0gKlLeWKGvQ64BxU4biZh4H4P6 |
+
+---
+
+## Usage
+
+When setting up Laravel project:
+
+```bash
+# Add to composer.json
+composer config http-basic.nova.laravel.com Sajawal.developer@gmail.com koFe33Gb0rhbseLFlcUj4IGM0gKlLeWKGvQ64BxU4biZh4H4P6
+
+# Or set environment variables
+export NOVA_LICENSE_EMAIL="Sajawal.developer@gmail.com"
+export NOVA_LICENSE_KEY="koFe33Gb0rhbseLFlcUj4IGM0gKlLeWKGvQ64BxU4biZh4H4P6"
+
+# Then install Nova
+composer require laravel/nova
+```
+
+---
+
+**Saved:** 2026-03-28