native-update 2.0.0 → 3.1.0

package/docs/project-knowledge-base/04-data-models-integrations.md

@@ -2,142 +2,141 @@
 
 ## Metadata
 
-- **Reference Date:** 2026-03-16
-- **Last Updated:** 2026-03-16
+- **Reference Date:** 2026-05-18
+- **Last Updated:** 2026-05-18
 
 ## Main Integration Surfaces
 
-- Firebase Authentication
-- Firestore
-- Google Identity Services
-- Google Drive API
+- Google OAuth via Laravel Socialite (auth provider)
+- Laravel Sanctum (token plane for the SPA)
+- `spatie/laravel-permission` (RBAC inside MySQL)
+- Google Drive API (server-side OAuth; bundle storage)
+- FilesHub (`https://fileshub.zaions.com`) for miscellaneous user-uploaded assets
+- PayPal (webhook for subscription events)
 - Capacitor runtime APIs
-- Android native APIs / Play-related update capabilities
-- iOS native APIs / StoreKit-related review and update capabilities
+- Android native APIs (Play Core update, Play Review, WorkManager)
+- iOS native APIs (StoreKit SKStoreReviewController, BGTaskScheduler)
 
 ## Authentication Model
 
 ### Sign-In Method
 
-- Primary auth flow is Google sign-in via Firebase popup
-- user records are created on first login
-- admin privilege is stored in Firestore and seeded from owner email logic
-
-### User Document (`users/{uid}`)
-
-Key fields visible in types and auth flow:
-
-- `uid`
-- `email`
-- `displayName`
-- `photoURL`
-- `provider`
-- `emailVerified`
-- `createdAt`
-- `lastLogin`
-- `driveConnected`
-- `driveEmail`
-- `driveConnectedAt`
-- `plan`
-- `planStartDate`
-- `planEndDate`
-- `appsCount`
-- `buildsCount`
-- `storageUsed`
-- `preferences`
-- `isAdmin`
-- `updatedAt`
-
-### User Preferences
-
-- `emailNotifications`
-- `updateNotifications`
-- `theme`
-- `language`
-
-## App Model
-
-### App Document (`apps/{appId}`)
-
-- `userId`
-- `name`
-- `packageId`
-- `icon`
-- `description`
-- `platforms`
-- `channels`
-- `apiKey`
-- `totalBuilds`
-- `activeUsers`
-- `lastBuildDate`
-- `createdAt`
-- `updatedAt`
+- Only auth flow is Google OAuth via Laravel Socialite
+- SPA navigates to `${VITE_API_URL}/auth/google/redirect`
+- Laravel's `OAuthController` redirects to Google, receives the callback, exchanges the code, and creates/updates the `users` row keyed by `google_id`
+- On success, Laravel issues a Sanctum personal access token and redirects to `${FRONTEND_URL}/auth/callback?token=…`
+- SPA's `CallbackPage` stores the plain-text token (shown once) via `setAuthToken()` and navigates to `/dashboard`
 
-### Channel Config
+### Role Assignment
 
-Per channel:
+- First sign-in → assigns the `user` role (default)
+- Emails in `ADMIN_EMAILS` env → auto-assigned `super-admin`
+- Manual: `php artisan native-update:role-assign <email> <role>` (revokes existing tokens to force re-login with new role)
+- Seeder: `php artisan db:seed --class=RolesPermissionsSeeder` (idempotent)
 
-- `enabled`
-- `autoUpdate`
-- `updateStrategy`
-- `requireUserConsent`
-- `minVersion`
+### Token Lifecycle
 
-Default observed behavior:
+- Default TTL: 7 days (configurable via `SANCTUM_TOKEN_EXPIRATION`)
+- Stored as `Bearer` header on every `/api/dashboard/*` and `/api/admin/*` request
+- 401 from any endpoint → axios interceptor clears the token, broadcasts a logout event, redirects to `/login`
+- Logout: `DELETE /api/dashboard/me/token` revokes the current token; on multi-device logout, all of the user's tokens are revoked
 
-- production enabled
-- staging enabled
-- development enabled and auto-update true
+## MySQL Schema (Laravel migrations)
 
-## API Key Model
+Migrations live in `backend/database/migrations/`. The following tables exist:
 
-### API Key Document (`apiKeys/{apiKey}`)
+### `users`
 
-Used so mobile apps can query manifests using an API key rather than dashboard auth. Observed fields include:
+- Standard Laravel fields plus:
+- `google_id` (unique; primary identity key)
+- `name`, `email`, `avatar_url`
+- `google_drive_access_token`, `google_drive_refresh_token`, `google_drive_token_expires_at` (encrypted via Laravel encrypter)
+- `google_drive_email`, `google_drive_connected_at`
+- `preferences` (JSON: email notifications, update notifications, theme, language, accent color, etc.)
+- admin-control flags (block, suspend, notes)
+- `apps_count`, `builds_count`, `storage_used` (denormalized counters)
+- standard timestamps + soft-delete
 
-- `appId`
-- `packageId`
-- `userId`
-- `createdAt`
+### `apps`
 
-There is also an app-facing manifests subcollection under this API key path.
+- `user_id` (foreign key to `users`)
+- `name`, `package_id` (unique per user), `description`, `icon_url`
+- `platforms` (JSON array: android/ios/web)
+- `channels` (JSON config)
+- `total_builds`, `active_users`, `last_build_at`
+- standard timestamps + soft-delete
 
-## Build Model
+### `api_keys`
 
-### Build Document (`builds/{buildId}`)
+- `app_id` (foreign key)
+- `key` (random token; used for mobile `/api/v1/*` plane)
+- `name`, `is_active`, `last_used_at`
+- standard timestamps
 
-Observed/typed fields include:
+### `signing_keys`
 
-- `id`
-- `userId`
-- `appId`
-- `version`
-- `buildNumber`
-- `channel`
-- `platform`
-- `fileName`
-- `fileSize`
-- `mimeType`
-- `checksum`
-- `signature`
-- `driveFileId`
-- `driveFileUrl`
-- `driveFolderId`
-- `fileManifest`
-- `manifestDriveId`
-- `releaseNotes`
-- `releaseType`
-- `isPreRelease`
-- `minNativeVersion`
-- `uploadedAt`
-- `uploadedBy`
-- `uploadDuration`
-- `status`
-- `processingSteps`
-- `analytics`
-- `updatedAt`
+- `app_id` (foreign key)
+- `name`
+- `algorithm` (RSA-2048 / RSA-4096 / EC P-256 / EC P-384)
+- `public_key` (PEM)
+- `private_key` (encrypted; backend-side only — never sent to the SPA)
+- `is_active`, `rotated_at`
+- standard timestamps
+
+### `builds`
 
-### Build Status Values
+- `id`
+- `user_id`, `app_id`
+- `version`, `build_number`
+- `channel`, `platform`
+- `file_name`, `file_size`, `mime_type`
+- `checksum` (SHA-256)
+- `signature` (RSA-SHA256 base64)
+- `drive_file_id`, `drive_file_url`, `drive_folder_id`
+- `fileshub_object_id` (when FilesHub used instead of Drive)
+- `file_manifest` (JSON: per-entry checksums for delta hints)
+- `release_notes`, `release_type`, `is_pre_release`
+- `min_native_version`
+- `uploaded_at`, `uploaded_by`, `upload_duration`
+- `status` (uploading / processing / active / archived / failed)
+- `processing_steps` (JSON; multi-step state)
+- `analytics` (JSON snapshot)
+- rollout config inline:
+  - `rollout_enabled`
+  - `rollout_percentage`
+  - `rollout_start_time`, `rollout_end_time`
+  - `target_segments` (JSON; optional)
+- standard timestamps + soft-delete
+
+### `subscriptions` + `subscription_items`
+
+- billing model (Stripe-style + PayPal provider added 2026-04-18)
+- `provider` (stripe / paypal), `provider_id`
+- `status`, `current_period_start`, `current_period_end`
+- per-item quantities + plan refs
+
+### `device_activities`
+
+- mobile-side telemetry (one row per active device)
+- last-seen, version installed, channel, platform metadata
+
+### `analytics_events`
+
+- per-event analytics (update checks, downloads, installs, rollbacks, errors)
+- `app_id`, `channel`, `platform`, `event_type`, `payload` (JSON)
+- aggregated by `AnalyticsDashboardController` for the dashboard
+
+### `personal_access_tokens` (Sanctum)
+
+- Sanctum's default token table
+- `tokenable_type`, `tokenable_id`, `name`, `token` (hashed), `abilities`, `last_used_at`, `expires_at`
+
+### Spatie permission tables
+
+- `roles`, `permissions`, `model_has_roles`, `model_has_permissions`, `role_has_permissions`
+- guard name: `sanctum`
+
+## Build Status Values
 
 - `uploading`
 - `processing`
@@ -145,163 +144,101 @@ Observed/typed fields include:
 - `archived`
 - `failed`
 
-## Manifest Model
-
-### Manifest Document (`manifests/{appId}_{channel}`)
-
-This is the primary document used for update checks.
-
-Fields:
-
-- `appId`
-- `channel`
-- `current`
-- `deltas`
-- `rollout`
-- `previousVersions`
-- `updatedAt`
-- `updatedBy`
-
-### Current Version Block
-
-- `version`
-- `bundleId`
-- `bundleUrl`
-- `manifestUrl`
-- `checksum`
-- `signature`
-- `size`
-- `releaseNotes`
-- `releaseDate`
-- `mandatory`
-- `minNativeVersion`
-
-### Rollout Config
-
-- `enabled`
-- `percentage`
-- `startTime`
-- `endTime`
-- optional `targetSegments`
-- optional `schedule`
-
-### Rollout Schedule
-
-- `immediate`
-- `gradual`
-- `scheduled`
-
-## Delta Model
-
-### Delta Document
-
-Used for pre-computed patch information:
+## Manifest Shape (returned by `/api/v1/updates/check`)
+
+Returned for each `appId + channel` combination, derived from the active Build row:
+
+```jsonc
+{
+  "appId": "com.example.myapp",
+  "channel": "production",
+  "current": {
+    "version": "1.2.0",
+    "bundleId": "<build uuid>",
+    "bundleUrl": "https://<signed-drive-or-fileshub-url>",
+    "manifestUrl": "<self-link>",
+    "checksum": "sha256-…",
+    "signature": "<base64 RSA-SHA256>",
+    "size": 1234567,
+    "releaseNotes": "…",
+    "releaseDate": "ISO-8601",
+    "mandatory": false,
+    "minNativeVersion": "1.0.0"
+  },
+  "deltas": [],
+  "rollout": {
+    "enabled": true,
+    "percentage": 25,
+    "startTime": "ISO-8601",
+    "endTime": null,
+    "targetSegments": null
+  },
+  "previousVersions": [],
+  "updatedAt": "ISO-8601",
+  "updatedBy": "<user id>"
+}
+```
+
+## Rollout Config
+
+- `enabled` (boolean)
+- `percentage` (0–100)
+- `startTime` / `endTime` (ISO-8601; optional bounds)
+- `targetSegments` (optional JSON; reserved for future segmentation)
+- `schedule` strategy (immediate / gradual / scheduled)
+
+## Delta Shape
+
+Used when the plugin asks for an incremental patch between two known versions:
 
 - `appId`
-- `fromVersion`
-- `toVersion`
+- `fromVersion`, `toVersion`
 - `channel`
-- `patchDriveId`
-- `patchUrl`
-- `patchSize`
-- `patchChecksum`
-- `sourceChecksum`
-- `targetChecksum`
-- `generatedAt`
-- `generationDuration`
-- `algorithm`
-- `compressionRatio`
+- `patchUrl`, `patchSize`, `patchChecksum`
+- `sourceChecksum`, `targetChecksum`
+- `algorithm`, `compressionRatio`
 - `status`
 
-## Analytics Model
-
-### Analytics Batch Document (`analytics_batch/{batchId}`)
-
-- `appId`
-- `channel`
-- `windowStart`
-- `windowEnd`
-- `events`
-- `versionStats`
-- `platformStats`
-- `errorSamples`
-- `createdAt`
-
-### Events Aggregated
-
-- update checks
-- downloads
-- installs
-- rollbacks
-- errors
-
-## Drive Token Model
-
-### Drive Token Document (`drive_tokens/{userId}`)
-
-Observed fields include:
-
-- `userId`
-- `accessToken`
-- `refreshToken`
-- `tokenType`
-- `scope`
-- `expiresAt`
-- Google account metadata such as email/name/picture/id/locale
-- `encryptionMethod`
-- `iv`
-- `authTag`
-- `createdAt`
-- `updatedAt`
-
-## Google Drive Integration Flow
+## Google Drive Integration Flow (server-side)
 
 ### Connect Flow
 
-1. Load Google Identity Services script
-2. Request Drive and profile scopes
-3. Exchange response into usable access token
-4. Fetch Google user profile info
-5. Store token metadata in Firestore
-6. Update `users/{uid}` Drive connection fields
-
-### Upload Flow
-
-1. User selects ZIP
-2. Validate file
-3. Calculate SHA-256 checksum
-4. Generate file manifest from ZIP contents
-5. Upload ZIP to Drive
-6. Upload manifest JSON to Drive
-7. Make Drive files publicly retrievable as needed
-8. Write build record in Firestore
-9. Update channel manifest document
-
-## No-Cost Backend Operating Model
-
-The intended website publishing model is:
+1. User clicks "Connect Google Drive" on `/dashboard/drive`
+2. SPA calls `GET /api/dashboard/google-drive/auth-url` → backend returns Google OAuth URL with Drive scope
+3. Browser does full-window redirect to Google
+4. Google redirects to `${FRONTEND_URL}/oauth/google-drive/callback?code=…`
+5. SPA `DriveCallbackPage` POSTs the code to `POST /api/dashboard/google-drive/callback`
+6. Backend exchanges the code, encrypts access + refresh tokens, persists on the `users` row
+7. Backend writes `google_drive_email` + `google_drive_connected_at` for UI display
 
-- browser-based uploads
-- Google Drive for bundle storage
-- Firestore for metadata and app-facing manifests
-- no paid compute required for core publish/check/download flow
+### Upload Flow (Laravel-driven)
 
-This is a central strategic assumption in the repo’s website guidance.
+1. User selects ZIP on `/dashboard/upload`
+2. SPA multipart-POSTs to `POST /api/dashboard/apps/{app}/builds`
+3. `UpdateBuildRequest` FormRequest validates app ownership, version, build_number, file presence, file size, Drive-connected precondition
+4. Laravel computes SHA-256 of the uploaded ZIP
+5. Laravel signs the checksum with the app's active signing key (RSA-SHA256)
+6. Laravel uploads the ZIP to the user's Drive folder via encrypted tokens
+7. Laravel inserts the Build row in MySQL with `status='active'`
+8. Laravel returns the Build resource to the SPA
+9. TanStack Query invalidates the relevant cache keys → UploadPage navigates to app detail
 
-## App-Facing Manifest Paths Mentioned In CLAUDE Guidance
+## App-Facing Manifest Paths
 
-- `/apiKeys/{apiKey}/manifests/{channel}`
-- `/manifests/{appId}_{channel}`
+- `GET /api/v1/updates/check?appId=…&channel=…&apiKey=…` → returns the active manifest
+- `GET /api/v1/bundles/{build}/download` → returns a short-lived signed URL to the bundle (default 30 min)
 
 ## Security-Relevant Data Points
 
-- checksums are stored and used for validation
-- signature support exists
-- manifest and build docs carry release metadata
-- bundle file manifests support file-level integrity and delta logic
+- SHA-256 checksums are stored on every Build and verified on every download
+- RSA-SHA256 signatures are stored alongside checksums; plugin verifies against the configured public key (or array of public keys during a key rotation window)
+- Signing-key private keys never leave the Laravel host
+- Drive OAuth tokens are encrypted at rest using Laravel's encrypter (per-row, not per-app)
+- Sanctum token strings are hashed in the DB; the plain-text token is shown to the SPA exactly once at issuance
 
 ## Data Ownership Notes
 
-- The website messaging emphasizes that user build files are stored in the user’s Google Drive
-- user account data and release metadata live in Firebase/Firestore
-- deletion/account settings pages document data handling expectations for legal/compliance messaging
+- The website messaging emphasizes that user build files are stored in the user's Google Drive
+- All other data (account, app metadata, builds, analytics, signing keys, subscriptions) lives in the Laravel MySQL database
+- Account deletion soft-deletes the User row, revokes all Sanctum tokens, clears encrypted Drive tokens, cascades to apps/builds, and surfaces a confirmation page documenting what was removed
+- Privacy policy + data-deletion page reflect this exact architecture