native-update 2.0.0 → 3.1.0

package/docs/rules-tracker.md

@@ -0,0 +1,102 @@
+# Rules Tracker — Native Update
+
+This file tracks the application of the Generic Project Rules master prompt (R-001 through R-039) against this monorepo. It is the source of truth for "when was rule X last applied" and is used to skip recently-applied rules on re-runs.
+
+**Tracker last updated:** 2026-05-18
+**Run by:** Claude Code (Opus 4.7)
+**Run scope:** R-033 reclassified to N/A after v3.0.0 Firestore removal (full audit cooldown still in effect until 2026-05-23)
+
+---
+
+## Project context (locked answers)
+
+| # | Question | Answer |
+|---|---|---|
+| 1 | Private or public git repo? | **Public** — `github.com/aoneahsan/native-update`, MIT license |
+| 2 | Project + brand name? | Project: `native-update` (npm) · Brand: **Native Update** |
+| 3 | App identifier / bundle ID | Plugin (npm) has none. Website Capacitor app: `com.zaions.nativeupdate` (per `website/capacitor.config.ts`); example app: per its own config |
+| 4 | Developer contact | Ahsan Mahmood · aoneahsan@gmail.com · +923046619706 · linkedin.com/in/aoneahsan · aoneahsan.com |
+| 5 | Domain / social / support | Domain: `nativeupdate.aoneahsan.com` (live). Socials: GitHub `aoneahsan`, NPM `aoneahsan`, LinkedIn `aoneahsan`, Twitter `aoneahsan`. Support email: `aoneahsan@gmail.com`. Privacy URL: `https://nativeupdate.aoneahsan.com/privacy` |
+| 6 | Radix UI / ShadCN used? | **Yes (Radix UI)** — Radix primitives across `website/`. Tailwind v4 + Radix is the stack. ShadCN is not used |
+| 7 | Capacitor used? | Root IS a Capacitor **plugin** (not an app). The `website/` is a Capacitor app for hybrid mobile distribution of the dashboard. `example-apps/react-capacitor/` is a Capacitor demo. Root plugin rules differ from app-level Capacitor rules |
+
+---
+
+## Sub-project map and applicable rule set
+
+| Sub-project | Path | Type | Frontend rules (R-007/R-008/R-012/R-013/R-018/R-021–R-024/R-026/R-031/R-032/R-034) | Capacitor rules (R-019/R-027/R-028/R-035/R-036) | Notes |
+|---|---|---|---|---|---|
+| Root plugin | `/` | npm + Capacitor plugin | N/A (no UI) | N/A (the plugin is consumed; not itself an app) | Apply structural, build, docs rules only |
+| Website + dashboard | `website/` | React + Vite + Capacitor app | YES | YES | Primary UI target |
+| Example app | `example-apps/react-capacitor/` | Capacitor demo | Light (demo only) | Light (demo only) | Demos plugin usage; not a published product |
+| Example backend | `example-apps/node-express/` | Node demo | N/A | N/A | Reference server for plugin docs (the `firebase-backend/` example was removed in v3.0.0) |
+| Backend | `backend/` | Laravel 11 + Nova SaaS | N/A (server-rendered, separate flow) | N/A | Canonical backend — the only backend after v3.0.0 |
+| CLI | `cli/` | Node CLI | N/A | N/A | Plugin user CLI — structural rules only |
+
+---
+
+## Rules table
+
+Rules marked **N/A** include a justification in the Notes column. **Done** means the rule was applied in this run (or a prior run, and verified still in place). **Pending** means it's a follow-up.
+
+| Rule ID | Cadence | Status | Last Applied | Next Review | Notes |
+|---|---|---|---|---|---|
+| R-001-CLAUDE-AGENTS-FILES | Every 3 days | Done | 2026-04-25 | 2026-04-28 | Root + sub-project CLAUDE.md/AGENTS.md verified. AGENTS.md re-synced from CLAUDE.md at root. |
+| R-002-CONTEXT-MANAGEMENT | Behavioral | Done | 2026-04-25 | — | Already enshrined in root + global CLAUDE.md (`/compact` at <20%, progress logs). |
+| R-003-PACKAGE-MANAGER | One-time | Done | 2026-04-25 | — | yarn-only confirmed across root, website, cli, example-apps. No `package-lock.json` or `pnpm-lock.yaml` at any level (one stray `package-lock.json` exists at `backend/` for npm-published Tailwind/PostCSS — left because `backend/` is Laravel + intentionally uses npm for Vite plugins; documented in tracker). |
+| R-004-DOCS-SCRIPTS-FOLDERS | Recurring | Done | 2026-04-25 | 2026-05-09 | Docs in `docs/` (41 entries). Scripts intentionally absent at root per R-006. `website/scripts/` retained — only `generate-sitemap.mjs` (necessary for SEO build pipeline). |
+| R-005-NO-USELESS-FILES | Recurring | Done | 2026-04-25 | 2026-05-09 | Reviewed root + website docs; no useless record/summary files added. Older "_TRACKER.md" / "_PLAN.md" files left in place because they're in active use. |
+| R-006-NO-SCRIPTS | One-time | Done | 2026-04-25 | — | No `.sh` files anywhere. Root has no `scripts/`. `website/scripts/generate-sitemap.mjs` is the only script — required by SEO build, documented at top of file. |
+| R-007-NO-NATIVE-HTML | One-time + recurring | Partial | 2026-04-25 | 2026-05-09 | Website uses Radix primitives extensively, but some `<button>` / `<input>` usage remains in legacy components. Documented for incremental migration; no regressions allowed in new code. See R-007 audit notes below. |
+| R-008-SITEMAP-FEED-BLOG | ≥3 days, ≤7 days | Done (sitemap+feed) / N/A (blog) | 2026-04-24 | 2026-05-01 | Sitemap + feed fully implemented per `website/CLAUDE.md` SEO record. Blog is **not** required for this project (technical plugin docs site, not a content site) — recorded as deliberate N/A. |
+| R-009-GITIGNORE | Recurring | Done | 2026-04-25 | 2026-05-09 | Root + website + example-apps `.gitignore` re-audited. `website/.firebase/hosting.*` cache was leaking into git — already fixed in commit `c687dd5`. No further changes needed. |
+| R-010-CLEAN-PACKAGE-JSON | Recurring | Done | 2026-04-25 | 2026-05-09 | Audited root + website + cli `package.json`. All listed deps are imported. Notes recorded in `docs/package-audit.md`. |
+| R-011-APP-VERSION-FOOTER | One-time | Done | 2026-04-25 | — | Website footer now displays plugin version + build year. Sourced from `package.json` via Vite `define`. |
+| R-012-404-ERROR-PAGES | One-time + recurring | Done | 2026-04-25 | 2026-05-09 | `NotFoundPage.tsx` exists. Verified it matches current branding. 401/403/500 fall back to NotFoundPage with appropriate copy via router. |
+| R-013-SCROLL-TO-TOP | One-time | Done | 2026-04-25 | — | `<ScrollToTop>` component added to `MarketingLayout` and `DashboardLayout`. Honours hash for deep links. |
+| R-014-README-SYNC | Every 14 days | Done | 2026-04-25 | 2026-05-09 | Root `Readme.md` + `website/README.md` last updated; rules-tracker date noted. |
+| R-015-DEV-SERVER-PORT | One-time, confirm | Done | 2026-04-25 | — | Website: 5942 (registered). Example-apps/react-capacitor: 5944 (registered). Both unique, NOT defaults. Path in registry updated to current `projects/native-update/...` location. |
+| R-016-AI-KNOWLEDGE-BASE | Every 14 days | Done | 2026-04-25 | 2026-05-09 | `docs/ai-knowledge-base/` populated with project profile, features, routes, tech-stack, modules. Existing `AI-INTEGRATION-GUIDE.md` referenced. |
+| R-017-ENV-EXAMPLE | Recurring | Done | 2026-04-25 | 2026-05-09 | Root `env-example` and `env.sentry-example` unchanged (no new env vars). Website `.env.example` unchanged (still 4 keys). Required-env error wiring verified. |
+| R-018-PROJECT-META-INFO | Recurring | Done | 2026-04-25 | 2026-05-09 | All info pages exist and were verified: privacy, terms, security, cookies, data-deletion, about, contact, permissions. Links from footer confirmed. |
+| R-019-PUBLISH-ASSETS | One-time + refresh | Done (website) | 2026-04-25 | — | `website/app-publish-assets/` already exists. Refreshed `Last Updated` date. |
+| R-020-UPDATE-CLAUDE-MD | Every 14 days | Done | 2026-04-25 | 2026-05-09 | Root + website + cli + example-apps + backend CLAUDE.md/AGENTS.md updated with `Last Updated: 2026-04-25`. Version drift fixed. |
+| R-021-THEME-COLOR-CONTROLS | One-time, confirm | N/A (deliberate) | 2026-04-25 | — | Per `~/.claude/rules/radix-theme.md`: rule applies if Radix is used **app-wide**. Native Update website uses some Radix primitives but the visual system is Tailwind-driven, not `@radix-ui/themes`. Recorded as "Radix not used app-wide" → no theme customizer required. Re-verify on adoption of `@radix-ui/themes`. |
+| R-022-GO-BACK-BUTTON | One-time + recurring | Done | 2026-04-25 | 2026-05-09 | Dashboard pages have absolute back routes. Marketing pages don't need back (root + footer nav). DocsMarkdownPage uses absolute back to `/docs`. |
+| R-023-ERROR-HANDLING | One-time + audit | Partial | 2026-05-18 | 2026-05-25 | `errorTracker` service at `website/src/lib/errorTracking.ts`. Firebase Analytics path removed during the auth swap (2026-05-11). Sentry / Clarity / Amplitude shims silently skip when their env keys are missing. `docs/error-handling-tracking.md` registry kept up to date. |
+| R-024-ANALYTICS | One-time + audit | Partial | 2026-05-18 | 2026-05-25 | `website/src/lib/analytics.ts` no longer routes to Firebase Analytics — that path was removed when the app moved off Firebase Auth. Clarity + Amplitude shims silently skip when env keys missing; analytics-event registry kept at `docs/analytics-tracking.md`. |
+| R-025-FILES-STORAGE | One-time + audit | Done | 2026-04-25 | 2026-05-09 | Project intentionally uses **Google Drive only** (no FilesHub) — see `website/CLAUDE.md` "No-Cost Backend Rule". Documented as deliberate choice. FilesHub admin path is not needed because admins also use their Drive. |
+| R-026-D3-CHARTS | One-time + audit | Done | 2026-04-25 | 2026-05-09 | `d3@^7.9.0` and `@types/d3` confirmed in website deps. No competing chart libs (`Recharts`/`Chart.js`) in `package.json`. |
+| R-027-TRAPEZE-CONFIGURE | One-time | Done | 2026-04-25 | — | Root has `apps-config.yaml`. Website has `apps-config.yaml` with `sync:apps-config` script. Confirmed. |
+| R-028-CAPACITOR-ASSETS | One-time | Done | 2026-04-25 | — | Website has `assets/` source directory. `@capacitor/assets` is invoked via `cap:sync`. Verified. |
+| R-029-VITE-LOGGER | One-time | Done | 2026-04-25 | — | `website/src/lib/logger.ts` created — wraps `console.warn`/`console.error` with a single toggle for verbose mode. Existing `console.log` calls left in dev paths but documented for incremental migration. |
+| R-030-GOOGLE-AUTH-ONLY | One-time | Done | 2026-05-18 | — | Website uses Google sign-in only — implemented as a full-page redirect to the Laravel Socialite endpoint (`${VITE_API_URL}/auth/google/redirect`); the backend issues a Sanctum personal access token on callback. No Firebase, no popups, no client-side credentials. Confirmed in `website/src/services/auth-service.ts`. |
+| R-031-FORM-MANAGEMENT | One-time + audit | Done | 2026-04-25 | 2026-05-09 | `react-hook-form@^7.72`, `zod@^4.3.6`, `@hookform/resolvers@^5.2.2` — all confirmed. Used in UploadPage, SettingsPage, AppsPage. New forms in this run will reuse the pattern. |
+| R-032-UI-STATE-IN-URL | One-time + audit | Partial | 2026-04-25 | 2026-05-09 | Some pages already use search params (`?tab=...`, `?view=...`). `useUrlState` hook added at `website/src/lib/hooks/useUrlState.ts`. Audit notes record outstanding pages for incremental migration. |
+| R-033-FIRESTORE-RULES-INDEXES | Every 3 days | N/A (permanent) | 2026-05-18 | — | Firestore was removed from the plugin SDK + website in v3.0.0 (2026-05-04). The project's only persistence layer is now MySQL behind Laravel. `firestore.rules` / `firestore.indexes.json` / `docs/firestore-queries.json` were all deleted in commit `336f647` (post-closure cleanup). This rule is permanently N/A for this project; do not re-introduce Firestore. |
+| R-034-ADMIN-PANEL | One-time + audit | Done | 2026-04-25 | 2026-05-09 | Admin layout exists at `website/src/components/admin/` and pages at `website/src/pages/admin/` (Overview, Users, Apps, Builds). Super admin email: `aoneahsan@gmail.com` per `VITE_ADMIN_EMAILS`. |
+| R-035-CAPACITOR-OFFICIAL-PLUGINS | One-time | Done | 2026-04-25 | — | Website has `@capacitor/{android,ios,core,cli,motion,preferences,privacy-screen}` installed. Other plugins are deliberately not installed because the website doesn't need them (no camera, geolocation, etc.). Plugin status registry created at `docs/capacitor-official-plugins.md`. |
+| R-036-CAPAWESOME-PLUGINS | One-time | Done | 2026-04-25 | — | Website has `@capawesome/capacitor-app-shortcuts`. Other Capawesome plugins (app-update, app-review, edge-to-edge, badge) documented as "to add when website ships to Play Store" — registry at `docs/capawesome-plugins.md`. |
+| R-037-PROJECT-AS-PRODUCT | One-time, confirm | Done | 2026-04-25 | — | Footer copyright updated to `© Native Update team. Built with care.`. Footer credit to "Ahsan Mahmood" replaced with neutral attribution. Contact info on info pages still uses dev contact. |
+| R-038-REFERENCE-PROJECTS | One-time | Done | 2026-04-25 | — | Reference projects `ZTools`, `ClearHire`, `Video Controls Plus` exist at `~/Documents/01-code/projects/`. Patterns from those projects already informed prior native-update SEO/AEO work; no new patterns to copy in this pass. |
+| R-039-PROJECT-COMPLIANCE-AUDIT | Every run | Done | 2026-04-25 | next run | Final-step audit completed: build status confirmed, tracker entries finalized, version drift resolved. |
+
+---
+
+## Pending follow-ups (incremental work)
+
+These items are documented but not rolled into this run because they would require multi-day refactors and the user wants this run shipped. Each is dated; a future re-run picks them up.
+
+1. **R-007 — Native HTML migration to Radix:** `<button>` and `<input>` still appear in some marketing/legacy components. New code MUST use Radix or `@/components/ui/*` wrappers. Existing usage to be migrated component-by-component.
+2. **R-023 / R-024 — Sentry / Clarity / Amplitude env wiring:** services exist and silently skip when keys are absent. Add real env keys when those tools are provisioned.
+3. **R-032 — URL state migration:** `useUrlState` hook is now available at `src/lib/hooks/useUrlState.ts`. Migrate the remaining pages incrementally as they're touched.
+4. **R-036 — Capawesome plugins:** `app-update`, `app-review`, `edge-to-edge`, `badge` to be added before any Play Store / App Store submission of the website-as-app.
+
+---
+
+## Run history
+
+| Date | Scope | Outcome | Operator |
+|---|---|---|---|
+| 2026-04-25 | Full pass R-001 → R-039 | All rules either Done, Done-Partial (with documented follow-up), or N/A-with-justification | Claude Code Opus 4.7 |
+| 2026-05-18 | R-033 reclassification only — marked permanently N/A after v3.0.0 Firestore removal | Targeted update; full audit cooldown still in effect until 2026-05-23 | Claude Code Opus 4.7 |

package/docs/security/PRE-LAUNCH-PENTEST-CHECKLIST.md

@@ -0,0 +1,116 @@
+# Pre-Launch Pentest Checklist
+
+A focused, do-it-yourself security checklist for self-hosted `native-update` deployments before going to production. Walk through every section. Each item is a yes/no gate; if you can't say yes, fix it before launch.
+
+This is not a substitute for a professional penetration test. It is the floor — the issues a serious external test would catch in the first hour. Apps that fail this checklist are not ready for production traffic regardless of how nice the dashboard looks.
+
+The checklist assumes you have a self-hosted Laravel + Nova backend (the reference implementation). Adapt to your own backend if you wrote one. Hosted SaaS users skip everything in the backend sections — those defenses are operated by the SaaS provider — and focus on the device-side and operational sections.
+
+Maintained by Ahsan Mahmood. Last review: 2026-05-11.
+
+## 1 — Dependency hygiene (root + backend + website + example-app)
+
+The single highest-yield pre-launch security activity. Most production incidents trace back to an unpatched transitive dep, not a clever bug in your own code.
+
+- [ ] **Root plugin**: `yarn npm audit --severity high --recursive` exits 0 from `/` (the project root). If it reports a high or critical, evaluate each — false positives are common in the npm advisory feed, but a real one blocks launch.
+- [ ] **Backend (Laravel)**: `cd backend && composer audit` exits 0. If a CVE shows up, bump the package or pin the patched version explicitly.
+- [ ] **Website (React dashboard)**: `cd website && yarn npm audit --severity high --recursive` exits 0.
+- [ ] **Example app**: `cd example-apps/react-capacitor && yarn npm audit` clean (advisory severity HIGH or above only — the example app has a shallower attack surface).
+- [ ] **Direct dependency review**: scan `package.json` files for any deps that haven't been updated in >12 months. Stale deps are not a vulnerability by themselves but correlate strongly with abandoned maintenance.
+- [ ] **Yarn / Composer lockfile is committed**: `yarn.lock` (root, website, example-app) and `composer.lock` (backend) all in git. Without locked versions, every CI run can install different transitive versions and your audit is meaningless.
+- [ ] **No deprecated crypto libraries**: grep for `crypto-js`, `node-forge`, `jsrsasign`. None should appear in production paths — use Node's built-in `crypto` (server side) or `SubtleCrypto` (browser side).
+
+## 2 — Authentication and authorization
+
+- [ ] **API keys are hashed at rest.** The Laravel reference stores `key_hash` (bcrypt) plus `key_prefix` (first 12 chars, for lookup). The full key is shown ONCE at creation. Confirm with `mysql -e "SELECT key_prefix, LENGTH(key_hash), key_hash LIKE '%\$2y\$%' FROM native_update_dev.api_keys LIMIT 5"` — `key_hash` should look like a bcrypt string.
+- [ ] **API keys are scoped to one app.** The `ValidateApiKey` middleware joins `api_keys` to `apps` by `app_id`. Try authenticating a request with App A's key against App B's bundle download URL — it should 403, not 200.
+- [ ] **API keys have a rate limit.** Default is 600 req / 15 min per key. Verify: send 700 requests in 5 minutes and confirm requests 601+ return 429 with `Retry-After`.
+- [ ] **Revoked keys are immediately rejected.** Flip a key's `revoked_at`, then make a request with it. Should 401 within 1 second (no caching that extends past revocation).
+- [ ] **Firebase ID tokens are verified server-side.** The dashboard `/api/dashboard/*` endpoints use `ValidateFirebaseToken`. Send an unsigned / expired / wrong-audience token; backend should reject with 401. Watch `storage/logs/laravel.log` for the verification trace.
+- [ ] **Admin claims are checked.** `/api/admin/*` requires both a Firebase token AND the user being on the `ADMIN_EMAILS` allowlist. Authenticate as a non-admin and call `/api/admin/users` — should 403.
+- [ ] **Nova policies fail closed.** Verify by logging into Nova as a non-admin tenant and trying to view another tenant's app via direct URL (`/admin/resources/apps/<other-tenant-app-id>`). Should redirect or 404, not show the resource.
+- [ ] **Suspended-user flow works.** Flip `is_suspended=true` on a test user via Nova. Their API keys should immediately return 403; their dashboard logins should redirect to the suspension screen.
+
+## 3 — Cross-origin and CSRF
+
+- [ ] **CORS allowlist is finite.** Open `backend/config/cors.php` (or your equivalent). `allowed_origins` must be a comma-separated list of full origins (`https://...`), NOT `*`. The default `CORS_ALLOWED_ORIGINS` env var should be set.
+- [ ] **Wildcard origin only allowed for the public SDK endpoints.** `/api/v1/*` may permit `*` because it's API-key-gated; `/api/dashboard/*` must NOT.
+- [ ] **`supports_credentials=true` is paired with explicit origin allowlist.** Browsers reject `Access-Control-Allow-Origin: *` when credentials are sent.
+- [ ] **CSRF protection on dashboard endpoints.** Laravel's `web` middleware group includes `VerifyCsrfToken`. The dashboard's React client must send the CSRF token in the `X-CSRF-Token` header on mutating requests.
+- [ ] **PayPal webhook is CSRF-exempt but signature-verified.** `/api/webhooks/paypal` skips Laravel's CSRF check (it has no session) but runs PayPal's signature verification. Confirm with a request lacking the signature header — should 401.
+
+## 4 — Bundle integrity and signing
+
+- [ ] **HTTPS enforced for the bundle download.** `npm run dev`-style HTTP allowlists must not appear in `app.production.env`. Confirm: `curl http://your-backend/api/v1/updates/check` should redirect to HTTPS or refuse.
+- [ ] **Signed download URLs expire.** Default TTL is 30 minutes (`NATIVE_UPDATE_DOWNLOAD_URL_TTL_MINUTES`). Get a signed URL, wait 31 minutes, try it — should 403.
+- [ ] **Bundle ZIP hash is verified server-side at upload.** When uploading a build via the dashboard or `/api/v1/bundles/upload`, the backend should re-compute SHA-256 over the bytes and reject if mismatched against the client-supplied checksum. Confirm by uploading with a deliberately wrong checksum — should 400.
+- [ ] **Signature is verified server-side at upload.** Backend should also re-verify the RSA-SHA256 signature against the app's registered public key. Confirm by uploading a bundle signed with the wrong key — should 400.
+- [ ] **Device-side signature verify is unconditional.** Edit `native-update.config.js` to point at the backend, deliberately corrupt the bundle bytes mid-transit (e.g. via a proxy), and confirm the SDK refuses to apply with `SIGNATURE_VERIFICATION_FAILED`. There must be no debug flag to bypass.
+- [ ] **Private signing keys are never persisted to logs.** Grep `storage/logs/laravel.log` for `BEGIN PRIVATE KEY`, `pkcs8`, `RSA PRIVATE`. Zero hits required.
+
+## 5 — Bundle file safety
+
+- [ ] **No reverse-engineered or unsafe ZIP extraction.** The plugin uses platform-standard libraries (`java.util.zip.ZipFile` on Android, `Foundation`'s `NSFileManager` on iOS). Zip-slip is mitigated by validating entry names don't contain `..` or absolute paths. Verify with a crafted bundle whose entry name is `../../etc/passwd` — install should fail with `INVALID_BUNDLE`.
+- [ ] **Bundle size limits enforced.** Set `NATIVE_UPDATE_MAX_BUNDLE_SIZE_MB=50` (or your real limit). Upload a 60 MB bundle — should 413.
+- [ ] **No symlinks in extracted bundles.** Bundle extraction refuses symlink entries. Verify with a ZIP containing a symlink entry — install should fail.
+- [ ] **Temp files are scoped to the app sandbox.** The SDK extracts to `<sandbox>/native-update/bundles/<version>/`. Verify by inspecting filesystem after a download — no files outside the sandbox.
+
+## 6 — Data handling and privacy
+
+- [ ] **Device hashes are not raw identifiers.** Confirm the SDK sends `X-Device-ID: <sha256_hex>`, never the raw IMEI / ADID / IDFA. Inspect `src/web.ts` for the hashing call.
+- [ ] **MAU + analytics writes do not include PII.** Inspect the analytics_events table — should contain `device_hash` (opaque), platform, app_version, bundle_version, event_type. Should NOT contain email, name, exact location, or full IP.
+- [ ] **Account deletion is honored.** The `/api/dashboard/me` DELETE endpoint cascades to apps + builds + signing_keys + api_keys + analytics_events for that user. Verify by creating a test user, uploading data, calling DELETE /api/dashboard/me, then confirming all related rows are gone.
+- [ ] **PII fields in user table are listed.** `users.name`, `users.email`, `users.firebase_uid` — known. Document any others. GDPR DSAR responses depend on knowing what to dump.
+- [ ] **Privacy policy URL is publicly accessible AND covers OTA.** Open the URL in an incognito tab. Body must mention bundle downloads, device IDs, and the retention policy for analytics events.
+
+## 7 — Operational safety
+
+- [ ] **`.env` is in `.gitignore`.** Verify: `git check-ignore backend/.env` exits 0.
+- [ ] **`firebase-credentials.json` is in `.gitignore`.** Same check for `backend/storage/firebase-credentials.json`.
+- [ ] **`auth.json` (Nova license) is in `.gitignore`.** Same check.
+- [ ] **No secrets in committed history.** Run `git log --all -p -G "BEGIN RSA PRIVATE\|password\s*=\|api[_-]key\s*=" -- backend/ | head -50`. Should return nothing meaningful. If something appears, rotate the secret AND filter the history with `git filter-repo`.
+- [ ] **Production database backups exist.** Run a backup, restore it to a test instance, verify the restore is bit-for-bit identical via `mysqldump | sha256sum` comparison.
+- [ ] **Queue worker is supervised.** systemctl status native-update-queue should show "active (running)" with auto-restart on failure.
+- [ ] **Logs do not contain API keys, JWTs, or signed URLs in plaintext.** Grep `storage/logs/laravel.log` for `Bearer eyJ`, `X-API-Key:`, `signature=`. Zero hits required.
+- [ ] **Web server hides version info.** `curl -sI https://your-backend/api/health | grep -i server` should NOT show `Server: nginx/1.18.0 (Ubuntu)`. Set `server_tokens off;` in nginx config.
+
+## 8 — Mobile platform integration
+
+- [ ] **Android merged manifest has no unexpected permissions.** Inspect `android/app/build/intermediates/merged_manifests/release/AndroidManifest.xml`. Sensitive permissions (CAMERA, RECORD_AUDIO, ACCESS_FINE_LOCATION, ACCESS_BACKGROUND_LOCATION, READ_CONTACTS, READ_SMS, READ_CALL_LOG, BODY_SENSORS, ACTIVITY_RECOGNITION) must each map to a privacy-policy disclosure + Data Safety entry + runtime-prompt UX.
+- [ ] **iOS Privacy Manifest is complete.** Open `ios/App/App/PrivacyInfo.xcprivacy`. Required-reason API entries must cover all the APIs your app uses (the plugin's two: NSPrivacyAccessedAPICategoryUserDefaults CA92.1, NSPrivacyAccessedAPICategoryFileTimestamp C617.1).
+- [ ] **ATS exceptions removed from production builds.** Inspect `ios/App/App/Info.plist`. `NSAllowsArbitraryLoads`, `NSAllowsLocalNetworking`, and per-domain exception entries should all be false / absent in the production xcconfig.
+- [ ] **Network security config restricts cleartext to dev IPs only.** `android/app/src/main/res/xml/network_security_config.xml` should permit cleartext only for `10.0.2.2` / `192.168.x.x` LAN ranges, not `*`.
+- [ ] **Production AAB is signed with Play App Signing.** Confirm in Play Console → Setup → App integrity. Without this, the In-App Update API does not work.
+
+## 9 — Specific attack paths to try
+
+Run each of these against staging. Document the result.
+
+- [ ] **Login-as-other-user via Firebase token swap.** Mint a Firebase ID token for user A, call `/api/dashboard/me` with it. Mint one for user B, call `/api/dashboard/me`. Confirm the response identifies the correct user in each case. Try sending user A's token with `Authorization: Bearer <token>` AND a header `X-User-Id: <user-b-id>` — should ignore the header and identify user A.
+- [ ] **Cross-tenant bundle download.** As tenant A, upload bundle. Grab the signed download URL from the check response. As tenant B (different API key), try to download from that URL. Should 403 even though the URL is signed — the BundleController re-asserts `app_id` ownership.
+- [ ] **Signed-URL tampering.** Take a valid signed URL, change one byte of the `signature=` parameter, request. Should 403.
+- [ ] **Replay of expired signed URL.** Take a signed URL, wait past its TTL, request. Should 403.
+- [ ] **Bundle ID confusion.** Generate two builds with overlapping `bundle_id` values (force via DB if needed). Check that bundle_id is unique-constrained — INSERT should fail at DB level.
+- [ ] **API key prefix collision.** API keys are looked up by 12-char prefix. Brute-force the prefix space — at 16^12 you're not at meaningful collision risk, but verify with `EXPLAIN SELECT * FROM api_keys WHERE key_prefix = '<prefix>'` that the prefix column has an index (you don't want a full-table scan on every request).
+- [ ] **Subscription cancellation race.** Create a subscription, cancel via dashboard, immediately try to upload a build. Should the subscription state propagate fast enough to block the upload? Define the policy and test it.
+- [ ] **License-key bypass.** A user with no license tries to access a license-gated feature. Should 403. A user with an expired license_expires_at tries the same. Should 403.
+- [ ] **MAU limit bypass.** A user on the free tier (100 MAU) tries to exceed it. Define the policy (soft limit with warning? hard limit?) and test it.
+
+## 10 — Final pre-launch sanity sweep
+
+- [ ] **Run the test suite.** `php artisan test` (backend) — all pass.
+- [ ] **Run lint.** `yarn lint` (root + website) — exit 0.
+- [ ] **Run typecheck.** `yarn typecheck` (website) — exit 0.
+- [ ] **Run build.** `yarn build` (root + website) — exit 0.
+- [ ] **Smoke-test the full happy path.** Sign up → create app → upload bundle → device fetches → device verifies → device applies → notifyAppReady → bundle marked verified. End-to-end, on a real device, not just an emulator.
+- [ ] **External healthcheck.** Use UptimeRobot / Pingdom / a similar service to monitor `/api/health` from outside your network for ~24 hours before launch. Should be 100% green.
+
+## What this checklist does NOT replace
+
+A professional pentest. A SOC 2 audit. A formal threat model. Bug-bounty engagement. Independent code review of the plugin native layer (Kotlin + Swift) by someone fluent in those languages. Quarterly review and update of this checklist itself.
+
+This is the first 80% — the fast-cheap-routine part. The remaining 20% (sophisticated attacker classes, supply-chain via deps, side-channel attacks, advanced persistent threats) needs specialist attention.
+
+## Authored by
+
+[Ahsan Mahmood](https://aoneahsan.com) — author and maintainer of `native-update`.

package/docs/social-media-marketing/README.md

@@ -0,0 +1,81 @@
+# Native Update — Social Media Marketing
+
+Long-form posts, WhatsApp messages, and WhatsApp status copy for promoting the **Native Update** Capacitor plugin (`native-update` on NPM) and the surrounding ecosystem (Laravel + Nova SaaS backend, CLI, native Android/iOS, React marketing/dashboard site, 3 example apps).
+
+All content is **truthful** — only features that ship today are mentioned. No fabricated stats, no "best-in-class" puffery, no keyword stuffing. Every piece has a clear CTA.
+
+---
+
+## How this folder works
+
+| File pattern | Purpose | Items per file | Size per item |
+|---|---|---|---|
+| `posts-batch-NN.md` | Posts for LinkedIn / Facebook (LinkedIn caps at 3,000 chars) | 10 | **2700–2900 chars (~490–510 words)** |
+| `whatsapp-messages-batch-NN.md` | WhatsApp group / DM messages | 30 | **400–600 chars (~60–80 words)** |
+| `whatsapp-status-batch-NN.md` | WhatsApp status messages | 30 | **240–400 chars (~40–60 words)** |
+
+**Char limits are HARD limits.** LinkedIn rejects > 3,000-char posts. WhatsApp messages over ~600 chars get scrolled-past in groups. Status over ~400 chars gets visually cramped. Stay inside the windows.
+
+### "USED" marker convention
+
+Once a post / message / status has been shared, **prepend `USED — ` to its heading**. Example:
+
+```
+## Post 03 — OTA in 60 seconds   →   ## USED — Post 03 — OTA in 60 seconds
+```
+
+This lets the next session see at a glance which content has been consumed and avoid duplicates.
+
+### When to generate the next batch
+
+The next session of this prompt should:
+
+1. Read this README first
+2. Scan `posts-batch-*.md`, `whatsapp-messages-batch-*.md`, `whatsapp-status-batch-*.md`
+3. **Only generate a new posts file** if every post in the latest posts batch is marked `USED`
+4. **Only generate a new WhatsApp messages file** if every message in the latest messages batch is marked `USED`
+5. Same rule for status files
+6. Per session: max 5 new posts files + max 2 new WhatsApp message files + max 2 new status files. Ask the user before each new file.
+
+### Hashtag policy
+
+- Max 7 hashtags per post; **5 (2 generic + 3 specific) is the SEO sweet spot** — that's the default
+- Generic pool (always available): `#Aoneahsan` `#AhsanMahmood` `#Zaions` `#BestOpenSourceCommunityProject` `#TopFree` `#SaaSApp`
+- Per-post, pick 2 generic + 3 post-specific hashtags
+- Never keyword-stuff. Princeton GEO study (KDD 2024) shows it actively reduces AI-citation share by ~10%.
+
+### Honesty rules (IRON-SOLID — do not break)
+
+- Only describe features that exist in the live codebase as of the file's date
+- Native Update v3.0.0 backend = **Laravel HTTP only** (Firestore was removed in v3 — never claim Firestore support)
+- License is **MIT** — say so plainly
+- The plugin works on **iOS + Android via Capacitor**, NOT React Native
+- "OTA updates" mean **non-native JS/HTML/CSS bundle replacements** — they do not push native code changes
+- App Store / Play Store policies still apply — say so when relevant
+- No fabricated stars, downloads, or testimonials
+
+---
+
+## Run history
+
+| Date | Files generated | Notes |
+|---|---|---|
+| 2026-05-06 | `posts-batch-01.md` | First run. 10 long-form posts covering: problem framing → plugin intro → OTA deep-dive → store-update checks → in-app review → Laravel/Nova backend → CLI → example apps → v3.0.0 BREAKING story → getting-started CTA. Source of truth: `NATIVE-UPDATE_portfolio-info_2026-05-06.md`. |
+| 2026-05-06 | `whatsapp-messages-batch-01.md` | Same session. 30 short messages (~250–350 words each): feature pitches, comparisons, architecture explainers, build-in-public notes, honest-limit framing, integration walkthroughs. |
+| 2026-05-07 | `whatsapp-status-batch-01.md` | 30 status messages, originally ~120–180 words each. |
+| 2026-05-07 | All 3 files **rewritten** to NEW char limits: posts 2700–2900, messages 400–600, statuses 240–400. README + CLAUDE.md + AGENTS.md rule updated to reflect HARD char limits. Verified all 70 items in-spec. |
+| 2026-05-07 | `posts-batch-02.md` | 10 fresh long-form posts on different angles from batch 01: founder note, Capgo/Live-Updates comparison, security model, common OTA mistakes, multi-app setup, Nova admin tour, v3 migration retrospective, performance, telemetry, roadmap. Series tag: `#NativeUpdateInside`. All 10 verified at 2700–2900 chars. |
+
+---
+
+## Source of truth for facts
+
+Always cross-check claims against:
+
+- `/home/ahsan/Documents/01-code/projects/native-update/NATIVE-UPDATE_portfolio-info_2026-05-06.md` — current portfolio file
+- `/home/ahsan/Documents/01-code/projects/native-update/CLAUDE.md` — features + status + version
+- `/home/ahsan/Documents/01-code/projects/native-update/Readme.md` — public README
+- Live NPM page: https://www.npmjs.com/package/native-update
+- Live homepage: https://nativeupdate.aoneahsan.com
+
+If a fact is not in any of those, **do not write it**.