indraq_cli 2.8.0 → 2.13.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/README.md +185 -2
  2. package/cloud-api/.env.example +9 -0
  3. package/cloud-api/README.md +34 -1
  4. package/cloud-api/dist/index.js +1396 -68
  5. package/cloud-api/dist/index.js.map +1 -1
  6. package/cloud-api/dist/ota-device-enrollment.js +41 -0
  7. package/cloud-api/dist/ota-device-enrollment.js.map +1 -0
  8. package/cloud-api/dist/ota-enrollment-pages.js +67 -0
  9. package/cloud-api/dist/ota-enrollment-pages.js.map +1 -0
  10. package/cloud-api/dist/ota-recovery-content.js +36 -0
  11. package/cloud-api/dist/ota-recovery-content.js.map +1 -0
  12. package/cloud-api/dist/ota-recovery-protocol.js +16 -0
  13. package/cloud-api/dist/ota-release-policy.js +25 -0
  14. package/cloud-api/dist/ota-release-policy.js.map +1 -0
  15. package/cloud-api/package.json +1 -1
  16. package/cloud-api/public/indraq-logo.png +0 -0
  17. package/cloud-api/sql/015_ota_device_registry_and_withdrawal.sql +23 -0
  18. package/cloud-api/sql/016_ota_verified_tester_devices.sql +19 -0
  19. package/cloud-api/sql/017_ota_device_app_access_grants.sql +18 -0
  20. package/cloud-api/sql/018_ota_android_tester_agent.sql +24 -0
  21. package/cloud-api/sql/019_ota_android_scoped_testers.sql +9 -0
  22. package/cloud-api/sql/020_ota_recovery_and_retention.sql +21 -0
  23. package/cloud-api/sql/021_ota_device_profile_consolidation.sql +14 -0
  24. package/cloud-api/src/index.ts +1078 -82
  25. package/cloud-api/src/index.ts.backup-before-extra-params-2026-11-20T19-41-35-684Z +3189 -0
  26. package/cloud-api/src/ota-device-enrollment.ts +30 -0
  27. package/cloud-api/src/ota-enrollment-pages.ts +71 -0
  28. package/cloud-api/src/ota-recovery-content.ts +45 -0
  29. package/cloud-api/src/ota-recovery-protocol.ts +16 -0
  30. package/cloud-api/src/ota-release-policy.ts +28 -0
  31. package/dist/cli/help-content.d.ts.map +1 -1
  32. package/dist/cli/help-content.js +34 -10
  33. package/dist/cli/help-content.js.map +1 -1
  34. package/dist/index.js +1 -1
  35. package/dist/index.js.map +1 -1
  36. package/dist/modules/mobile/commands/build-mobile.command.d.ts +3 -1
  37. package/dist/modules/mobile/commands/build-mobile.command.d.ts.map +1 -1
  38. package/dist/modules/mobile/commands/build-mobile.command.js +216 -41
  39. package/dist/modules/mobile/commands/build-mobile.command.js.map +1 -1
  40. package/dist/modules/mobile/commands/mobile-build-wizard.command.d.ts +3 -1
  41. package/dist/modules/mobile/commands/mobile-build-wizard.command.d.ts.map +1 -1
  42. package/dist/modules/mobile/commands/mobile-build-wizard.command.js +23 -16
  43. package/dist/modules/mobile/commands/mobile-build-wizard.command.js.map +1 -1
  44. package/dist/modules/mobile/commands/mobile-prebuild.command.d.ts +2 -0
  45. package/dist/modules/mobile/commands/mobile-prebuild.command.d.ts.map +1 -1
  46. package/dist/modules/mobile/commands/mobile-prebuild.command.js +61 -2
  47. package/dist/modules/mobile/commands/mobile-prebuild.command.js.map +1 -1
  48. package/dist/modules/mobile/commands/ota.command.d.ts +9 -0
  49. package/dist/modules/mobile/commands/ota.command.d.ts.map +1 -1
  50. package/dist/modules/mobile/commands/ota.command.js +271 -103
  51. package/dist/modules/mobile/commands/ota.command.js.map +1 -1
  52. package/dist/modules/mobile/commands/testers.command.d.ts +11 -0
  53. package/dist/modules/mobile/commands/testers.command.d.ts.map +1 -1
  54. package/dist/modules/mobile/commands/testers.command.js +236 -5
  55. package/dist/modules/mobile/commands/testers.command.js.map +1 -1
  56. package/dist/modules/mobile/config/mobile-config.d.ts +3 -0
  57. package/dist/modules/mobile/config/mobile-config.d.ts.map +1 -1
  58. package/dist/modules/mobile/config/mobile-config.js.map +1 -1
  59. package/dist/modules/mobile/index.d.ts.map +1 -1
  60. package/dist/modules/mobile/index.js +49 -6
  61. package/dist/modules/mobile/index.js.map +1 -1
  62. package/dist/modules/mobile/services/mobile-cloud.service.d.ts +85 -1
  63. package/dist/modules/mobile/services/mobile-cloud.service.d.ts.map +1 -1
  64. package/dist/modules/mobile/services/mobile-cloud.service.js +27 -1
  65. package/dist/modules/mobile/services/mobile-cloud.service.js.map +1 -1
  66. package/dist/modules/mobile/services/mobile-native-integration.service.d.ts +12 -0
  67. package/dist/modules/mobile/services/mobile-native-integration.service.d.ts.map +1 -0
  68. package/dist/modules/mobile/services/mobile-native-integration.service.js +394 -0
  69. package/dist/modules/mobile/services/mobile-native-integration.service.js.map +1 -0
  70. package/dist/modules/mobile/services/ota-apk-validator.service.d.ts +22 -0
  71. package/dist/modules/mobile/services/ota-apk-validator.service.d.ts.map +1 -0
  72. package/dist/modules/mobile/services/ota-apk-validator.service.js +227 -0
  73. package/dist/modules/mobile/services/ota-apk-validator.service.js.map +1 -0
  74. package/dist/modules/mobile/services/ota-native-compatibility.service.d.ts +18 -0
  75. package/dist/modules/mobile/services/ota-native-compatibility.service.d.ts.map +1 -0
  76. package/dist/modules/mobile/services/ota-native-compatibility.service.js +21 -0
  77. package/dist/modules/mobile/services/ota-native-compatibility.service.js.map +1 -0
  78. package/dist/modules/mobile/services/ota-setup.service.d.ts +4 -0
  79. package/dist/modules/mobile/services/ota-setup.service.d.ts.map +1 -1
  80. package/dist/modules/mobile/services/ota-setup.service.js +240 -48
  81. package/dist/modules/mobile/services/ota-setup.service.js.map +1 -1
  82. package/dist/modules/mobile/services/tester-reconnect-policy.d.ts +9 -0
  83. package/dist/modules/mobile/services/tester-reconnect-policy.d.ts.map +1 -0
  84. package/dist/modules/mobile/services/tester-reconnect-policy.js +12 -0
  85. package/dist/modules/mobile/services/tester-reconnect-policy.js.map +1 -0
  86. package/dist/modules/mobile/services/tester-reconnect-probe.service.d.ts +5 -0
  87. package/dist/modules/mobile/services/tester-reconnect-probe.service.d.ts.map +1 -0
  88. package/dist/modules/mobile/services/tester-reconnect-probe.service.js +41 -0
  89. package/dist/modules/mobile/services/tester-reconnect-probe.service.js.map +1 -0
  90. package/dist/modules/scaffold/commands/init.command.d.ts.map +1 -1
  91. package/dist/modules/scaffold/commands/init.command.js +8 -2
  92. package/dist/modules/scaffold/commands/init.command.js.map +1 -1
  93. package/package.json +61 -4
  94. package/src/modules/mobile/services/android-agent-bridge/IIndraQTesterAgent.aidl +2 -0
  95. package/src/modules/mobile/services/android-agent-bridge/IndraQTesterModule.java +67 -0
  96. package/src/modules/mobile/services/android-agent-bridge/IndraQTesterPackage.java +15 -0
  97. package/src/modules/mobile/services/android-identity-bridge/IndraQDeviceIdentityModule.java +31 -0
  98. package/src/modules/mobile/services/android-identity-bridge/IndraQDeviceIdentityPackage.java +16 -0
  99. package/src/modules/mobile/services/expo-android-identity-plugin.cjs +44 -0
package/README.md CHANGED
@@ -1,4 +1,148 @@
1
- # IndraQ CLI — developer guide (v2.8.0)
1
+ # IndraQ CLI — developer guide (v2.13.0)
2
+
3
+ **Cloud API v1.7.0.** OTA tester/withdrawal incident fixes built on v2.12.0; **no new SQL migration is required** beyond migration 020. Back up PostgreSQL and MinIO, deploy Cloud API first, then CLI, then a **new Expo Release APK** to install the CNG native module. Do not overwrite currently released or testing OTA records.
4
+
5
+ ## v2.13.0 — fixes from real OnePlus 7 testing
6
+
7
+ - **Named tester selection:** `indraq mobile send update` now lists **each globally verified, app-approved device once** (rather than each previous installation). Select a device once for all chosen compatible runtimes. The explicit **Selected app installations** option remains for one-installation debugging.
8
+ - **Repeated install/reinstall delivery:** Test OTA audience stores stable `deviceIds` and IndraQ Cloud resolves the device's **current authorized installation** on each manifest request, checking approved device, app grant, enrollment, runtime and platform. A fresh installation must enroll before a test OTA is served. Repeated delivery is not once-per-device. Previously published installation-ID-scoped test releases remain unchanged and may still require republishing to use this fix.
9
+ - **Withdraw to an older OTA or embedded APK:** The Cloud API now locks and evaluates the **actual latest overlapping active release**, reporting the blocking release ID and timestamp rather than an opaque conflict. Disjoint verified-device audiences need not conflict. Optional pinning, withdrawal, and creation of a new scoped recovery release are **one database transaction**—a rejected withdrawal makes no pin/status changes. Production rollback is still separate and unchanged.
10
+ - **Expo managed Android:** For internal testing builds, CLI installs a **local Expo CNG config plugin** (`indraq-ota/with-indraq-android-identity.cjs`) plus native Java sources. Jenkins runs the plugin during `expo prebuild`, registering `IndraQDeviceIdentity` just as bare React Native does. No Agent APK, no AIDL, no manual `android/` folder. Requires a **fresh signed native Expo APK**, a previously approved device, and the trusted internal Cloud opt-in `OTA_ANDROID_SCOPED_TESTER_RESTORE=true`; existing Expo APKs without the module cannot gain it through an OTA.
11
+ - **Storage cleanup:** If no uploads are eligible, `indraq mobile storage cleanup` prints `Nothing to clean up` and exits before asking for global deletion. The safety contract still protects all published immutable assets. Orphan-upload deletion with actual test objects requires a separate isolated staging check.
12
+ - **Metrics:** Embedded-recovery directives count as manifest deliveries for their own recovery release rather than appearing as zero served. Historical Expo automatic-rollback or emergency-launch counts remain historical until separately investigated.
13
+ - **Native compatibility:** Still fail-closed for missing or mismatched native fingerprints, with independent exports per selected runtime. For safety, the wizard preselects **only the newest compatible runtime**; older versions must be explicitly selected.
14
+
15
+ ### Testing / rollback commands
16
+
17
+ ```powershell
18
+ indraq --version
19
+ indraq mobile doctor
20
+ indraq mobile testers installations
21
+ indraq mobile send update
22
+ indraq mobile updates list
23
+ indraq mobile withdraw
24
+ indraq mobile rollback
25
+ indraq mobile storage
26
+ indraq mobile storage cleanup
27
+ indraq mobile metrics
28
+ ```
29
+
30
+ **Risk boundary:** Android's signing-key-scoped ID is a low-assurance identification hint for trusted internal testing, **not cryptographic device authentication**. The verified-browser fallback and per-project revocation remain in force. Do not enable scoped-ID recognition for security-critical or general-public distribution. Devices offline during recovery can continue to run downloaded code until their next successful online check. No command can remotely erase a cached JS bundle while the phone is offline.
31
+
32
+ See [CHANGELOG_v2.13.0.md](CHANGELOG_v2.13.0.md), [UPGRADE_v2.13.0.md](UPGRADE_v2.13.0.md), and [TEST_RESULTS_v2.13.0.md](TEST_RESULTS_v2.13.0.md) for the checklist and unverified live tests.
33
+
34
+ ---
35
+
36
+ # IndraQ CLI — developer guide (v2.12.0)
37
+
38
+ **Cloud API v1.6.0, migration 020.** Production rollout is a separate, gated operation; deploy Cloud first and validate its native/OTA routes before upgrading the CLI.
39
+
40
+ ## OTA publishing, recovery, and storage — v2.12.0
41
+
42
+ - **`indraq mobile send update`** now compares the current project native fingerprint with every successful Jenkins Android native build in the selected environment. Incompatible builds are **blocked**, not silently updated. You may select **multiple compatible runtimes**; each runtime receives its own Expo export, signed manifest, audience and immutable release, grouped by deployment ID. An Expo-managed Android project and a bare React Native Android project both use the Expo Updates protocol. iOS cannot use an Android-only build record, and is blocked until a separately verified iOS binary is supported.
43
+ - **`indraq mobile withdraw`** is for never-promoted **testing** updates. It prompts for the bad update and recovery target: an older compatible OTA (including previously tested candidates), **the original embedded native app**, or stop delivery only. Recovery is a **new release**, scoped to the source runtime, platform and original test audience. A bad cached OTA is not removed by deleting it from Cloud; the phone must check online and process the signed recovery. The app bootstrap handles `isRollBackToEmbedded` before activating pending cached code.
44
+ - **`indraq mobile rollback`** is for **released Production** OTA only: choose a previously released compatible OTA or the default native binary embedded update. Native binary versions on other runtimes remain untouched.
45
+ - **`indraq mobile updates list`**, **`indraq mobile updates pin`**, **`indraq mobile storage`**, **`indraq mobile storage cleanup`** show history/controls. Pinning marks a recovery preference; **published Expo asset URLs must remain immutable and retrievable** even after withdrawal. Normal GC therefore removes only **unreferenced uploads older than 7 days**, and never a file used by a historical or current published manifest. Global GC requires an admin and explicit confirmation. `OTA_ORPHAN_GC_ENABLED=true` enables opt-in six-hour scheduled orphan GC on Cloud.
46
+ - **Known-good versus recoverable:** all older compatible, retained releases are *recovery candidates*. Only user-validated or promoted production versions qualify as *approved*; age alone does not prove stability. The embedded native baseline is registered when Jenkins records a successful native build, without duplicating its embedded JavaScript in MinIO.
47
+ - **Safety limitations:** Native fingerprints catch native dependency/configuration mismatches but cannot prove every dynamic JS call is safe. Recovery relies on a compatible Expo Updates client, a reachable Cloud API and an installed build with embedded JS. Offline clients may retain cached updates. Old published assets cannot safely be permanently deleted under the Expo protocol; if reclaiming historical published storage becomes necessary, design an explicit compatibility/end-of-support policy first.
48
+
49
+ **Typical commands:**
50
+
51
+ ```powershell
52
+ indraq mobile send update
53
+ indraq mobile updates list
54
+ indraq mobile withdraw
55
+ indraq mobile rollback
56
+ indraq mobile storage
57
+ indraq mobile storage cleanup
58
+ indraq mobile metrics
59
+ indraq help mobile
60
+ ```
61
+
62
+ Read [UPGRADE_v2.12.0.md](UPGRADE_v2.12.0.md), [CHANGELOG_v2.12.0.md](CHANGELOG_v2.12.0.md), and [TEST_RESULTS_v2.12.0.md](TEST_RESULTS_v2.12.0.md) before deployment.
63
+
64
+ ---
65
+
66
+ # IndraQ CLI — developer guide (v2.11.0)
67
+
68
+ **New in v2.11.0:** Android in-app background tester recognition plus an IndraQ-branded responsive verified-browser fallback, without a mandatory Tester Agent. Requires Cloud API v1.5.0. Automatic Android ID matching is **opt-in** and lower assurance than browser verification: `OTA_ANDROID_SCOPED_TESTER_RESTORE=true` must be explicitly set on the Cloud API for trusted internal-only programs. iOS/managed Expo are not included. Read [UPGRADE_v2.11.0.md](UPGRADE_v2.11.0.md) before use.
69
+
70
+ ---
71
+
72
+ # IndraQ CLI — developer guide (v2.10.0)
73
+
74
+ **New in v2.10.0:** Android silent tester enrollment for bare React Native CLI via separately installed IndraQ Tester Agent. Cloud API v1.4.0 and matching Android app signing are mandatory. Read [UPGRADE_v2.10.0.md](UPGRADE_v2.10.0.md), [CHANGELOG_v2.10.0.md](CHANGELOG_v2.10.0.md), and [TEST_RESULTS_v2.10.0.md](TEST_RESULTS_v2.10.0.md) before deployment. Browser reconnect remains an explicit recovery option; existing APKs require a new native build for the bridge. iOS and managed Expo are not covered by the silent agent implementation.
75
+
76
+ ---
77
+
78
+ # IndraQ CLI — developer guide (v2.9.9)
79
+
80
+ ## v2.9.9 — Fix silent enrollment-link parsing failure on React Native/Hermes
81
+
82
+ - Parse native pairing links without `URL.hostname`/`URL.searchParams` (not implemented in some React Native/Hermes versions).
83
+ - Record `enrollment_link_received`, `enrollment_link_rejected` and `enrollment_failed` OTA events without logging pairing tokens.
84
+ - The global device grant and verified-browser security rules remain unchanged. Browserless reuse across separately installed apps still requires a separate trusted device credential.
85
+ - Refer to `CHANGELOG_v2.9.9.md` and `UPGRADE_v2.9.9.md`. Cloud API remains v1.3.12.
86
+
87
+ ## v2.9.8 — Persistent tester grant selection + reliable reconnect diagnostics
88
+
89
+ - During every internal release build, choose **continue with saved devices**, **use all verified devices**, or **select individual devices**. Revocation of deselected app grants is applied after a successful Jenkins build. The global device approval remains intact.
90
+ - **Before Jenkins builds** an internal tester APK, the CLI checks the *deployed* Cloud API's `/ota/v1/enrollment/status` route, rather than trusting source or package version numbers. If the route is missing or does not match the app, the build stops with an actionable error.
91
+ - A failed/interrupted browser reconnection is no longer permanently marked as tried. It can retry (up to three times per 24 hours with five-minute spacing), and successful enrollment clears its retry state. Public builds still never open a tester browser.
92
+ - **APK 0.8 built with v2.9.7** cannot gain this revised auto-retry code without a new native build, but it can be reconnected now without a new QR: on the original approved phone browser visit `https://cli.indraq.com/ota/device/apps`, tap **Connect** for the app, and tap **Open App**. If the original browser credential is missing, reverify the global device.
93
+ - See `CHANGELOG_v2.9.8.md` and `UPGRADE_v2.9.8.md`. Cloud API stays v1.3.12.
94
+
95
+ ## v2.9.7 — Metro-only Development; release OTA and reusable testers in the build wizard
96
+
97
+ **Run `indraq mobile build`.** Choose **Development** for Expo Development Client / React Native Debug APK (JavaScript from Metro, no IndraQ OTA registration or OTA baseline). Choose **Staging/Preview** or **Production** for release builds that can receive signed IndraQ OTA updates.
98
+
99
+ For a staging/production release build, the wizard asks **Internal testers** or **Public users**. For internal testing it lists the phones globally verified by the one-time `indraq mobile devices register` QR. Select devices once for each new app; existing app grants persist across future APK versions. The builder automatically enables previously verified-browser reinstall reconnect for internal tester builds and disables it for public releases. **No `--mode dev`, `--tester-reconnect`, or long prebuild command is required.** If release OTA setup is missing, the wizard invokes it automatically.
100
+
101
+ A new/reinstalled application may need its verified phone browser to open an app link; this cannot be made zero-interaction on every mobile OS. Native versions must remain OTA runtime-compatible. Developers can explicitly choose automation flags `--audience testers --reuse-devices all`; unattended `--yes` alone grants no devices and produces a public build. See `CHANGELOG_v2.9.7.md` and `UPGRADE_v2.9.7.md`.
102
+
103
+ ---
104
+
105
+ ## Historical versions (the workflow below reflects earlier releases)
106
+
107
+ ## v2.9.5: Reuse verified tester phones and reconnect fresh test installations
108
+
109
+ * **Register once:** `indraq mobile devices register` verifies a reusable account-level phone in the original HTTPS browser. The approved device stays registered independently of app deletion, native versions, and OTA channels.
110
+ * **Choose once for each new project:** `indraq mobile prebuild --mode dev` offers all previously verified phones. Selected devices receive per-app grants in IndraQ Cloud. Use `--reuse-devices all|none|<id1,id2>` when running noninteractively; no permission is granted implicitly.
111
+ * **Reconnect fresh tester builds:** When a new/reinstalled development/staging installation first launches and that app has authorized tester devices, it can open the phone's original verified browser for a short-lived app pairing link. No new registration QR is issued. Android/iOS may ask to **Open App**; automatic handoff depends on OS/browser policies.
112
+ * **Production safety:** Public production builds do not force browser opening. Internal tester-only production builds can opt in with `indraq mobile prebuild --mode prod --tester-reconnect`.
113
+ * **Security:** A grant is not device proof. Existing cookie verification, project permissions, app grants, one-use tokens, and revocation all remain enforced. The app never authorizes OTA based on spoofable Android ID, iOS IDFV, or a self-asserted device name.
114
+ * **Upgrade Cloud API first:** API **1.3.12**, then CLI **2.9.5**. Native app rebuilds are required to gain the reconnect feature; previously distributed APKs cannot gain it retroactively. See `UPGRADE_v2.9.5.md`, `CHANGELOG_v2.9.5.md`, and `TEST_RESULTS_v2.9.5.md`.
115
+
116
+
117
+
118
+ ## v2.9.3: Select authorized phones when registering a device or building an app
119
+
120
+ * **Before the registration QR**, `indraq mobile devices register` asks which existing mobile apps this phone may test. The phone's secure one-time QR approval confirms its reusable tester identity and displays the selected app names. The Cloud API stores **app permissions separately from the APK/runtime**.
121
+ * During `indraq mobile build`, the CLI offers currently verified devices not yet authorized for that app. The selected grants are saved **only after Jenkins successfully builds and the native OTA baseline is recorded**. An unsuccessful build grants no access; `--yes` remains noninteractive and skips access selection.
122
+ * Use `indraq mobile devices allow` to grant a previously registered phone access to an app, `devices access` to inspect authorization and installation pairing, and `devices deny` to remove access to one app. `devices remove` still revokes the entire device, including its linked testing access.
123
+ * Granting app access **is not automatically pairing a new app sandbox** with a physical phone. Already linked installations become eligible again when access is granted. New app installations must prove possession once, using the verified phone's browser link; no new global QR registration is necessary. A build shared among devices cannot securely reveal which phone installed it.
124
+ * Cloud API **1.3.11**, migration `017_ota_device_app_access_grants.sql`, and CLI **2.9.3** must be deployed in that order. See `UPGRADE_v2.9.3.md`. The device portal shows **only explicitly granted apps**, and app-level redemption rejects revoked grants.
125
+
126
+ ## v2.9.2: Live QR approval, reusable browser app portal, device removal
127
+
128
+ * `indraq mobile devices register` creates a pending QR and **waits** for phone confirmation via an authenticated Cloud API status endpoint; `devices verify` does the same for an existing profile. Press Ctrl+C to stop waiting without approving.
129
+ * Phone pages are responsive and fully self-contained, with IndraQ styling, escaped names, no third-party assets and clear success/error states. A verified phone browser can visit **`https://cli.indraq.com/ota/device/apps`**, choose an authorized app and tap **Connect → Open app** without scanning another QR. The app still has to redeem a one-use token to prove installation ownership. No app can silently read another app's browser credentials.
130
+ * `indraq mobile devices remove` (alias `revoke`) immediately revokes browser and linked tester authorization; `devices list` hides removed profiles by default, and `devices list --all` shows them for audit.
131
+ * Requires **Cloud API 1.3.10** first (migrations 015 and 016 already apply). Read `UPGRADE_v2.9.2.md` before deployment. Full CLI TypeScript typecheck and live phone test still required.
132
+
133
+ ## v2.9.1: Verified QR devices, OTA release controls, and one-step mobile setup
134
+
135
+ **Upgrade order:** back up the Cloud PostgreSQL database and MinIO OTA bucket; deploy **Cloud API 1.3.9** (runs migrations `015_ota_device_registry_and_withdrawal.sql` and `016_ota_verified_tester_devices.sql` in order), then install **IndraQ CLI 2.9.1**. From each mobile project run `indraq mobile prebuild` (or `indraq init` for a new project), then produce and verify a fresh native build if the QR deep link/native setup changed. The CLI does **not** alter the shared Jenkins pipeline. See `UPGRADE_v2.9.1.md` for staging and device acceptance steps.
136
+
137
+ * **Expo:** prebuild owns Expo configuration and signed OTA bootstrap; standard Expo native generation from config remains in the build workflow.
138
+ * **React Native CLI:** prebuild verifies/aligns `app.json` and native component registration, validates Android JS entry and Expo CLI paths, and installs QR deep-link integration for supported Android/iOS templates; no edits in `node_modules`.
139
+ * **Verified global tester profiles:** `indraq mobile devices register|verify|list|revoke`. Registration first creates a **PENDING** profile and a 15-minute QR. The real phone browser must approve the QR; IndraQ stores a hashed browser credential, not a hardware identifier. Linked app invitations require approval from the **same verified browser** before opening an app deep link. Different apps still securely pair their isolated installations; in-place APK upgrades keep their app identity.
140
+ * **Immutable rollback:** `indraq mobile rollback` chooses an older released, compatible update and deploys a new signed update identifier referencing **already stored** JS/assets—no source edits or bundle export.
141
+ * **Server-enforced lifecycle:** draft-only finalize; only testing/never-promoted paused releases can be promoted, withdrawn or deleted; a normal released OTA can only be rolled back or paused. Release status transitions use compare-and-set to reject stale actions.
142
+ * **Testing withdrawal:** `indraq mobile withdraw` stops distributing an unreleased testing update. Where an earlier compatible released update exists, IndraQ generates a tester-scoped recovery from stored artifacts; otherwise it warns that cached/offline installs may need remediation. It does **not** forcibly erase files from offline devices.
143
+ * **Verification:** run `indraq mobile doctor`, inspect a built APK using `indraq mobile verify-apk <path>`, and perform an actual installed-device launch and OTA test before production promotion. Builds/devices cannot be verified from source code alone.
144
+
145
+ ---
2
146
 
3
147
  > **Mobile Jenkins safety policy:** IndraQ CLI **never creates, edits, replaces, repairs, or deletes** the shared mobile Jenkins Pipeline. Both `indraq mobile prebuild` and `indraq mobile build` check the existing manually managed `Mobile app Cli build` job **read-only**. If the job is missing, disabled, or has incorrect/missing parameters, the command stops; an administrator fixes Jenkins manually. Only an actual build request sends `POST /buildWithParameters` with the expected inputs.
4
148
 
@@ -99,7 +243,7 @@ During **Send update**, pick **Tester groups**, **Named testers**, **Selected in
99
243
 
100
244
  **Security:** The invitation is a one-time token (hashed at rest), expires in 5–60 minutes, and does not grant a Cloud user account or permission to publish. QR generation happens on the local computer using a bundled QR encoder—no outside QR service receives the invitation. Treat the SVG/link as confidential until redeemed. A tester device must already have registered its IndraQ-enabled app installation. Installation IDs are **device delivery identifiers**, not strong user authentication or verified proof of account identity.
101
245
 
102
- **Platform scope:** Automated deep-link enrollment setup is currently implemented for **Expo** (including Expo Router). Existing React Native CLI projects can still receive installation-based and general OTA releases, but native QR deep links need a separate explicit Android/iOS link integration before enrollment will work. Live QR scanning, update application, and device testing must be verified before production rollout.
246
+ **Platform scope (updated in v2.9.0+):** Expo and supported React Native CLI templates both receive native deep-link setup during IndraQ prebuild. Native changes require a new installed build. Live Android/iOS enrollment and OTA startup tests remain required before production rollout.
103
247
 
104
248
  ---
105
249
 
@@ -1545,3 +1689,42 @@ Before using IndraQ mobile prebuild/build, an administrator must configure an ex
1545
1689
  The CLI reads the job type, enabled/buildable status, parameters, file types and choices. If invalid, it prints what needs manual repair **before uploading any source**. If valid, the build uses only Jenkins' `buildWithParameters` endpoint, streams the output, and leaves job configuration untouched. A real build naturally creates build history/artifacts, not Jenkins job configuration changes.
1546
1690
 
1547
1691
  **Older CLI versions:** Cloud API v1.3.7 retains the Jenkins read-only protections introduced in v1.3.5. It rejects the legacy create/repair mobile operations with HTTP 409, so older CLI clients cannot modify the shared mobile job through IndraQ Cloud either.
1692
+
1693
+ ## Preserve OTA tester pairing when upgrading a test APK (CLI v2.9.4)
1694
+
1695
+ Once a physical tester approved its QR and its installed app was securely linked, **do not uninstall the APK** for the next native build. A compatible Android upgrade preserves the app's AsyncStorage Installation ID and its tester enrollment:
1696
+
1697
+ ```powershell
1698
+ indraq mobile install "C:\\Downloads\\YourApp_NewRelease.apk" --device <ADB_SERIAL>
1699
+ indraq mobile testers installations
1700
+ ```
1701
+
1702
+ The command runs `adb install -r`. Add `--smoke-test` for an additional native Expo Updates startup check. If the APK's package name or signature is incompatible, fix that rather than erasing app data. After a successful in-place upgrade the same app installation should report the new native runtime and remain enrolled. For a brand-new app sandbox (first install, uninstall/clear-data), separate secure app pairing is still necessary; merely authorizing a global phone during build cannot prove an anonymous new installation belongs to it.
1703
+
1704
+ ### v2.9.6 — Internal Production tester reconnect fix (superseded by v2.9.7)
1705
+
1706
+ For an internal Production Release APK that must reuse globally verified tester phones after uninstall/reinstall, run `indraq mobile prebuild --mode prod --tester-reconnect --reuse-devices all` **before** the next Production mobile build. `--reuse-devices all` grants all verified devices accessible to the developer; for selective grants use `indraq mobile devices allow`. The build now retains the explicit reconnect setting when regenerating the native OTA bootstrap. Regular public Production builds do not automatically reconnect. See `HOTFIX_v2.9.6.md`.
1707
+
1708
+
1709
+ ### Duplicate approved tester registrations — CLI 2.13.1 / Cloud API 1.7.2
1710
+
1711
+ `indraq mobile devices consolidate` provides an **explicit owner-confirmed** way to combine two registrations known to belong to the *same physical phone*, across **all** mobile projects. A matching label, model, IP, or Android identifier is **never** automatically treated as proof of shared identity. Never combine two separate phones.
1712
+
1713
+ - Choose the **surviving** verified registration (prefer the one with more linked installs / stable Android identity).
1714
+ - Choose the **duplicate** verified registration to retire. Type `SAME PHYSICAL PHONE`, supply an audit reason, and approve an additional default-No confirmation.
1715
+ - Cloud transactionally preserves app grants, historical installation links, and scoped Android identity hashes; retires the duplicate browser credential; and records a permanent audited alias so past immutable OTA audiences continue to work.
1716
+ - Conflicting explicit app revocations or different cryptographic agent keys **block** consolidation until manually investigated.
1717
+ - The build, prebuild device registry, device access list, and named OTA tester choices now inherit the single surviving active registration; historical `indraq mobile testers installations` stays a per-installation audit list and is intentionally not deduplicated.
1718
+ - New device registration checks the already-verified browser session and warns instead of verifying a second profile for that same browser; alternate browser profiles and reset phones cannot be automatically proven to be the same hardware.
1719
+
1720
+ The Cloud API applies `021_ota_device_profile_consolidation.sql` at startup. Back up PostgreSQL first and deploy the Cloud API before upgrading CLI. Existing OTA assets are not modified. Use `indraq mobile devices list` before and after; confirm in Barakah and IndraQOtaNativeTest that each physical phone appears once. Android scoped matching is a convenience for trusted internal testers, not cryptographic proof of device possession.
1721
+
1722
+ ### OTA recovery chain safeguards — CLI 2.13.2 / Cloud API 1.7.3
1723
+
1724
+ The `mobile withdraw` wizard labels recovery sources, hides previously recovered
1725
+ payloads from the candidate list, and preserves immutable history. The Cloud API
1726
+ checks the actual published per-platform asset fingerprints and stable manifest
1727
+ configuration before changing release status or pinning. A recovery to the same
1728
+ already-served JavaScript is rejected as a no-op without creating a new release;
1729
+ legitimate older/embedded recoveries and `Stop delivery only` remain available.
1730
+ Production rollback has the same no-op guard. No SQL migration is needed.
@@ -22,3 +22,12 @@ MINIO_SECRET_KEY=change-me
22
22
  MINIO_BUCKET=indraq-ota
23
23
  # Public Cloud API URL embedded into mobile builds. Keep this on the same cli.indraq.com backend.
24
24
  PUBLIC_API_URL=https://cli.indraq.com
25
+
26
+ # Lower-assurance internal Android tester restore; disabled by default.
27
+ # Do NOT enable for public apps or sensitive tester distribution.
28
+ OTA_ANDROID_SCOPED_TESTER_RESTORE=false
29
+
30
+ # Safe maintenance: disabled by default. Deletes only unreferenced uploads
31
+ # older than seven days; never deletes files referenced by a published OTA.
32
+ OTA_ORPHAN_GC_ENABLED=false
33
+ OTA_ANDROID_SCOPED_TESTER_RESTORE=true
@@ -1,6 +1,35 @@
1
+ # IndraQ Cloud API v1.6.0 — OTA recovery, compatibility and retention
2
+
3
+ **New migration:** `020_ota_recovery_and_retention.sql`. Keep existing PostgreSQL, MinIO, signing certificates, Android tester registry and scoped ID secrets unchanged.
4
+
5
+ - Native build records are platform-scoped (existing Jenkins builds become Android). An Android build cannot authorize iOS OTA manifests.
6
+ - Native fingerprint/runtime checks remain mandatory for creating a release; deployment groups track multiple independently compatible Android runtimes.
7
+ - Test withdraw accepts `targetReleaseId`: older compatible OTA UUID, `embedded`, or `none`; legacy omitted target chooses previously released compatible OTA or embedded.
8
+ - Production rollback accepts an older released OTA UUID or `embedded`. Recovery produces a new release, reusing stored artifacts or serving a signed multipart Expo Updates v1 rollback directive.
9
+ - `GET /mobile/apps/:appId/storage` reports unique assets and unreferenced uploads. `POST /mobile/apps/:appId/storage/cleanup` requires admin and removes at most 50 unreferenced uploads older than 7 days. `OTA_ORPHAN_GC_ENABLED=true` opts into scheduled cleanup every six hours. **Referenced published assets are never deleted.**
10
+ - `POST /mobile/releases/:releaseId/pin` controls recovery-history pinning only. It cannot override the immutable published asset retention contract.
11
+
12
+ **Order:** Postgres+MinIO backup → deploy Cloud v1.6.0 → apply migration 020 on startup → verify recovery/storage endpoints → install CLI v2.12.0 → test on disposable Android testers → widen rollout. See top-level `UPGRADE_v2.12.0.md`.
13
+
14
+ ---
15
+
16
+ # IndraQ Cloud API v1.5.0
17
+
18
+ **New:** migration 019, first-party brand logo, acknowledged installation announce route, opt-in Android scoped-ID internal tester matching, verified-browser binding and responsive recovery page. Silent matching requires Cloud-only `OTA_ANDROID_SCOPED_TESTER_RESTORE=true` and uses a spoofable device identifier, NOT strong device authentication. Default browser-only remains secure. See root `UPGRADE_v2.11.0.md`.
19
+
20
+ ---
21
+
22
+ # IndraQ Cloud API v1.4.0
23
+
24
+ New in v1.4.0: registered Android Tester Agent public keys, browser-approved one-time agent activation, short-lived signed challenges, per-app access and revocation enforcement, and migration 018. Deploy Cloud API v1.4.0 **before** CLI v2.10.0 internal Android builds. See root `UPGRADE_v2.10.0.md`. Existing browser pairing APIs remain available for explicit recovery.
25
+
1
26
  # IndraQ Cloud API
2
27
 
3
- Control plane for IndraQ CLI v2.6.0 / Cloud API v1.2.0. The public CLI and OTA endpoint is `https://cli.indraq.com`.
28
+ Control plane for IndraQ CLI v2.9.5 / Cloud API v1.3.12. The public CLI and OTA endpoint is `https://cli.indraq.com`.
29
+
30
+ ## Global tester browser reconnect (1.3.12)
31
+
32
+ Cloud API 1.3.12 reuses the existing registered-device and per-app-grant tables (migrations 015–017). `GET /ota/v1/enrollment/status/:updatePath?installationId=...` reports whether a tester install is currently enrolled and whether this app has verified tester grants. `GET /ota/device/reconnect/:appId?state=...` requires the existing verified phone-browser cookie, current project membership, an active app grant, and a valid native URL scheme; it issues a five-minute single-use pairing invitation. A fresh app installation uses its native deep link to redeem the token, never an unverified device ID. Keep HTTPS and the browser Secure cookie enabled. Existing unauthenticated clients and public OTA manifest behavior remain compatible.
4
33
 
5
34
  ## Responsibilities
6
35
 
@@ -75,6 +104,10 @@ Numbered migrations in `sql/` are applied automatically at startup. Current scop
75
104
  010_persistent_auth_sessions.sql
76
105
  011_environment_internal_ipv4.sql
77
106
  012_mobile_ota.sql
107
+ 013_ota_tester_enrollment.sql
108
+ 014_mobile_native_build_history.sql
109
+ 015_ota_device_registry_and_withdrawal.sql
110
+ 016_ota_verified_tester_devices.sql
78
111
  ```
79
112
 
80
113
  v2.3 deployment topology does not require a new table: it is stored inside the existing `projects.config` JSONB document and validated through `PUT /projects/:id/deployment-topology`. Each target stores environment, primary/secondary/replica role, and Jenkins stage (`dev`/`prod`).