@scalebun/react-native 1.0.2 → 1.0.3

package/src/features/ota/OtaTypes.ts

@@ -1,62 +1,118 @@
-/**
- * OTA contract types — SDK-side mirror of the backend's ota.contracts.ts.
- *
- * These types are hand-maintained here AND mirrored in the backend.
- * Golden JSON fixtures in packages/protocol/fixtures/ota/ are the SINGLE source
- * of truth; conformance tests in both repos assert against them to prevent drift.
- */
-
-// ── SDK → backend (POST /sdk/ota/check) ──────────────────────────────────────
-export interface OtaCheckRequest {
-  appVersion: string;
-  platform: 'android' | 'ios';
-  arch?: string;
-  installationId: string;
-  currentBundleId?: string;
-  currentBundleHash?: string;
-}
-
-// ── backend → SDK ────────────────────────────────────────────────────────────
-export interface OtaCheckResponse {
-  action: 'NONE' | 'DOWNLOAD' | 'ROLLBACK';
-  bundle?: OtaBundlePayload;
-}
-
-export interface OtaBundlePayload {
-  id: string;
-  version: number;
-  url: string;         // presigned GET — short-TTL
-  size: number;
-  sha256: string;
-  signature?: string;  // ed25519 detached signature (hex)
-  isMandatory: boolean;
-  releaseNote?: string;
-  patch?: OtaPatchPayload;
-}
-
-export interface OtaPatchPayload {
-  url: string;
-  size: number;
-  sha256: string;
-  baseBundleId: string;
-}
-
-// ── Adoption telemetry (rides the unified batch envelope as kind:'ota_event') ──
-export type OtaEventType =
-  | 'CHECK'
-  | 'DOWNLOAD_STARTED'
-  | 'DOWNLOAD_COMPLETE'
-  | 'INSTALLED'
-  | 'APPLY_FAILED'
-  | 'AUTO_ROLLBACK'
-  | 'MANUAL_ROLLBACK';
-
-export interface OtaEventItem {
-  kind: 'ota_event';
-  bundleId: string;
-  releaseId?: string;
-  type: OtaEventType;
-  durationMs?: number;
-  errorCode?: string;
-  patchUsed?: boolean;
-}
+/**
+ * OTA contract types — SDK-side mirror of the backend's ota.contracts.ts.
+ *
+ * These types are hand-maintained here AND mirrored in the backend.
+ * Golden JSON fixtures in packages/protocol/fixtures/ota/ are the SINGLE source
+ * of truth; conformance tests in both repos assert against them to prevent drift.
+ */
+
+// ── SDK → backend (POST /sdk/ota/check) ──────────────────────────────────────
+export interface OtaCheckRequest {
+  appVersion: string;
+  platform: 'android' | 'ios';
+  arch?: string;
+  installationId: string;
+  currentBundleId?: string;
+  currentBundleHash?: string;
+
+  // ── C1: channel + targeting context ────────────────────────────────────────
+  // The backend DTO has accepted all of these since Sprint 9. The SDK declared
+  // none of them and `checkForUpdate` sent none, so every device in the field
+  // resolved to the `default` channel with an empty targeting context: beta
+  // channels were unreachable and the entire targeting-rule engine — country,
+  // segment, lifecycle, attributes — could never match. Sending them is what
+  // turns that already-built subsystem on.
+  /** Channel to pull from. Omitted means `default`. */
+  channelName?: string;
+  /** ISO 3166-1 alpha-2. The server fills this from the edge when absent. */
+  country?: string;
+  /** Free-form device attributes evaluated by ATTRIBUTE rules. */
+  attributes?: Record<string, string | number>;
+  /** CDP segment ids this installation belongs to. */
+  segmentIds?: string[];
+  /** Lifecycle stage (e.g. 'onboarding', 'activated', 'churned'). */
+  lifecycleStage?: string;
+
+  // ── Runtime compatibility context ──────────────────────────────────────────
+  // `appVersion` is a marketing string; these are the actual runtime contract.
+  // Serving a bundle built for a different runtime is the most common way an
+  // OTA product bricks an app, and without these fields the backend cannot
+  // even detect the mismatch, let alone refuse to serve it.
+  /** React Native version of the host binary, e.g. `"0.81.5"`. */
+  rnVersion?: string;
+  /** True when the JS engine is Hermes. */
+  hermes?: boolean;
+  /**
+   * Hermes bytecode (HBC) format version of the running engine. Independent of
+   * the RN release number. A mismatch either fails to load outright ("Wrong
+   * bytecode version. Expected 96 but got 98") or — worse — loads and crashes
+   * later on a path the older runtime does not expose.
+   */
+  hermesBytecodeVersion?: number;
+  /** True when running the New Architecture's bridgeless runtime. */
+  bridgeless?: boolean;
+}
+
+// ── backend → SDK ────────────────────────────────────────────────────────────
+export interface OtaCheckResponse {
+  action: 'NONE' | 'DOWNLOAD' | 'ROLLBACK';
+  bundle?: OtaBundlePayload;
+}
+
+export interface OtaBundlePayload {
+  id: string;
+  version: number;
+  url: string;         // presigned GET — short-TTL
+  size: number;
+  sha256: string;
+  signature?: string;  // ed25519 detached signature (hex)
+  isMandatory: boolean;
+  /**
+   * How to activate the bundle after install:
+   *   ON_NEXT_RESTART — nothing to do now; next cold start loads it (default)
+   *   ON_NEXT_RESUME  — restart the JS runtime when the app next returns to
+   *                     the foreground after a background stay
+   *   IMMEDIATE       — restart the JS runtime right after install
+   * Absent means ON_NEXT_RESTART, which is what every pre-installMode release
+   * actually did.
+   */
+  installMode?: 'ON_NEXT_RESTART' | 'ON_NEXT_RESUME' | 'IMMEDIATE';
+  releaseNote?: string;
+  patch?: OtaPatchPayload;
+  /**
+   * Identity marker compiled into this bundle at publish time.
+   *
+   * Recorded at install; compared after restart against the marker the RUNNING
+   * bundle carries. Its PRESENCE is the important part — knowing a bundle
+   * definitely has a marker is what turns "no marker after restart" from
+   * ambiguous into proof that the install never took effect.
+   */
+  identityToken?: string;
+}
+
+export interface OtaPatchPayload {
+  url: string;
+  size: number;
+  sha256: string;
+  baseBundleId: string;
+}
+
+// ── Adoption telemetry (rides the unified batch envelope as kind:'ota_event') ──
+export type OtaEventType =
+  | 'CHECK'
+  | 'DOWNLOAD_STARTED'
+  | 'DOWNLOAD_COMPLETE'
+  | 'INSTALLED'
+  | 'APPLY_FAILED'
+  | 'AUTO_ROLLBACK'
+  | 'MANUAL_ROLLBACK';
+
+export interface OtaEventItem {
+  kind: 'ota_event';
+  bundleId: string;
+  releaseId?: string;
+  type: OtaEventType;
+  durationMs?: number;
+  errorCode?: string;
+  patchUsed?: boolean;
+}

package/src/features/ota/environment.ts

@@ -0,0 +1,199 @@
+import { Platform } from 'react-native';
+
+/**
+ * OTA runtime environment detection.
+ *
+ * ── Why this file exists ────────────────────────────────────────────────────
+ *
+ * Our Android OTA resolves the active bundle through
+ * `MainApplication.getJSBundleFile()`. That is a *bridge-mode* API.
+ *
+ * Under the New Architecture (bridgeless), the app is built by
+ * `DefaultReactHost` instead — and until React Native 0.76.1,
+ * `DefaultReactNativeHost.toReactHost()` never forwarded `jsBundleFile`:
+ *
+ *     // RN 0.74.1 — DefaultReactNativeHost.kt
+ *     public fun toReactHost(context: Context): ReactHost =
+ *         DefaultReactHost.getDefaultReactHost(
+ *             context, packages, jsMainModuleName,
+ *             bundleAssetName ?: "index",   // <- jsBundleFile is NEVER passed
+ *             isHermesEnabled ?: true)
+ *
+ *     // RN 0.74.1 — DefaultReactHost.kt
+ *     val jsBundleLoader =
+ *         JSBundleLoader.createAssetLoader(context, "assets://$jsBundleAssetPath", true)
+ *
+ * The loader is hardcoded to the APK asset. `getJSBundleFile()` is never
+ * consulted, so an update stages, applies, reports INSTALLED, restarts — and
+ * the app loads the bundle baked into the APK. Every signal says success and
+ * nothing happened. This is the same failure that killed CodePush on modern RN.
+ *
+ * Fixed upstream in 0.76.1 (`jsBundleFile` is threaded through). Verified
+ * present in 0.81.5.
+ *
+ * We refuse to run rather than pretend to work. A loud failure at startup is
+ * recoverable; a silent no-op that reports success is not — it corrupts the
+ * adoption metrics, the guard thresholds, and every rollout decision made
+ * from them.
+ */
+
+/** First React Native version where bridgeless honours `getJSBundleFile()`. */
+export const MIN_BRIDGELESS_RN = { major: 0, minor: 76, patch: 1 } as const;
+
+/**
+ * React Native 0.82 REMOVED `ReactNativeHost`. The New Architecture became
+ * mandatory and `newArchEnabled=false` was withdrawn, so the legacy
+ * `override fun getJSBundleFile()` integration does not merely stop working —
+ * it does not compile. From 0.82 the only correct integration is passing
+ * `jsBundleFilePath` straight to `getDefaultReactHost(...)`.
+ *
+ * We cannot see which integration a host app used, so this is not a block. It
+ * drives a startup hint, and the post-restart identity check is what actually
+ * catches a host that got it wrong.
+ */
+export const REACT_HOST_ONLY_RN = { major: 0, minor: 82, patch: 0 } as const;
+
+export interface RnVersion {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+export interface OtaEnvironment {
+  /** Parsed React Native version, or null when it could not be determined. */
+  rnVersion: RnVersion | null;
+  /** `"0.76.1"`, or null. Sent to the backend for compatibility gating. */
+  rnVersionString: string | null;
+  /** True when running on the New Architecture's bridgeless runtime. */
+  bridgeless: boolean;
+  /** True when the JS engine is Hermes. */
+  hermes: boolean;
+  /**
+   * Hermes bytecode (HBC) format version of the *running* engine. This is the
+   * file-format compatibility number, NOT a React Native release number — the
+   * two move independently. A bundle compiled by a different hermesc can be
+   * rejected outright ("Wrong bytecode version. Expected 96 but got 98") or,
+   * worse, load fine and crash later on a path the older runtime lacks.
+   */
+  hermesBytecodeVersion: number | null;
+  /** False when OTA cannot work on this runtime and must not be enabled. */
+  supported: boolean;
+  /** Human-readable explanation when `supported` is false. */
+  blockReason: string | null;
+  /**
+   * True on RN >= 0.82, where `ReactNativeHost` no longer exists and the only
+   * valid integration is `getDefaultReactHost(..., jsBundleFilePath = …)`.
+   * Used to make the startup diagnostic name the right fix.
+   */
+  requiresReactHostIntegration: boolean;
+}
+
+function compare(a: RnVersion, b: { major: number; minor: number; patch: number }): number {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  return a.patch - b.patch;
+}
+
+function readRnVersion(): RnVersion | null {
+  // `Platform.constants.reactNativeVersion` is public API and present on both
+  // platforms since 0.62. Preferred over the deep `Libraries/Core/...` import,
+  // which is private and has moved between releases.
+  try {
+    const v = (Platform as unknown as { constants?: { reactNativeVersion?: RnVersion } })
+      .constants?.reactNativeVersion;
+    if (v && typeof v.major === 'number' && typeof v.minor === 'number') {
+      return { major: v.major, minor: v.minor, patch: v.patch ?? 0 };
+    }
+  } catch {
+    // fall through
+  }
+  return null;
+}
+
+function readBridgeless(): boolean {
+  // Set by the runtime itself when the bridgeless host is in use. Absent on
+  // the old architecture, so `=== true` is the correct test.
+  try {
+    return (globalThis as unknown as { RN$Bridgeless?: boolean }).RN$Bridgeless === true;
+  } catch {
+    return false;
+  }
+}
+
+interface HermesInternalShape {
+  getRuntimeProperties?: () => Record<string, unknown>;
+}
+
+function readHermes(): { hermes: boolean; bytecodeVersion: number | null } {
+  try {
+    const h = (globalThis as unknown as { HermesInternal?: HermesInternalShape }).HermesInternal;
+    if (!h) return { hermes: false, bytecodeVersion: null };
+
+    let bytecodeVersion: number | null = null;
+    const props = h.getRuntimeProperties?.();
+    if (props) {
+      // Hermes reports this as "Bytecode Version"; the value has been both a
+      // number and a numeric string across releases, so coerce and validate.
+      const raw = props['Bytecode Version'];
+      const n = typeof raw === 'string' ? Number(raw) : raw;
+      if (typeof n === 'number' && Number.isFinite(n)) bytecodeVersion = n;
+    }
+    return { hermes: true, bytecodeVersion };
+  } catch {
+    return { hermes: false, bytecodeVersion: null };
+  }
+}
+
+let cached: OtaEnvironment | null = null;
+
+/**
+ * Detect the runtime environment and decide whether OTA can function at all.
+ * Result is cached — none of these values change during a process lifetime.
+ */
+export function detectOtaEnvironment(): OtaEnvironment {
+  if (cached) return cached;
+
+  const rnVersion = readRnVersion();
+  const bridgeless = readBridgeless();
+  const { hermes, bytecodeVersion } = readHermes();
+
+  let supported = true;
+  let blockReason: string | null = null;
+
+  if (bridgeless && rnVersion) {
+    if (compare(rnVersion, MIN_BRIDGELESS_RN) < 0) {
+      supported = false;
+      blockReason =
+        `React Native ${rnVersion.major}.${rnVersion.minor}.${rnVersion.patch} is running ` +
+        `bridgeless (New Architecture), but jsBundleFile was not threaded through ` +
+        `DefaultReactHost until RN 0.76.1. getJSBundleFile() is ignored on this runtime, ` +
+        `so an OTA bundle would install successfully and never actually load. ` +
+        `Upgrade to React Native >= 0.76.1, or disable the New Architecture.`;
+    }
+  } else if (bridgeless && !rnVersion) {
+    // Can't prove it's broken, and blocking every app whose version we failed
+    // to read would be worse than the bug. Warn instead of blocking.
+    blockReason = null;
+  }
+
+  cached = {
+    rnVersion,
+    rnVersionString: rnVersion
+      ? `${rnVersion.major}.${rnVersion.minor}.${rnVersion.patch}`
+      : null,
+    bridgeless,
+    hermes,
+    hermesBytecodeVersion: bytecodeVersion,
+    supported,
+    blockReason,
+    requiresReactHostIntegration: rnVersion
+      ? compare(rnVersion, REACT_HOST_ONLY_RN) >= 0
+      : false,
+  };
+  return cached;
+}
+
+/** Test seam — the detection result is process-lifetime cached. */
+export function _resetOtaEnvironmentCache(): void {
+  cached = null;
+}

package/src/features/ota/retry.ts

@@ -0,0 +1,123 @@
+import { logger } from '../../core/logger/internalLogger';
+
+/**
+ * Retry with exponential backoff and full jitter.
+ *
+ * ── Why ─────────────────────────────────────────────────────────────────────
+ *
+ * The OTA path had no retry at all. A download that failed on a flaky mobile
+ * connection returned an error and the device then waited for the next cold
+ * start to try again — which on a phone is often hours, and on a device that
+ * is never fully restarted, effectively never. On mobile networks a single
+ * transient failure is the common case, not the exception.
+ *
+ * Full jitter (`random(0, backoff)` rather than `backoff`) matters more here
+ * than in most clients: every device on a release checks in against the same
+ * schedule, so a fixed backoff would retry the whole fleet in lockstep and
+ * turn one origin blip into a synchronised thundering herd.
+ */
+
+export interface RetryOptions {
+  /** Total attempts including the first. Default 3. */
+  attempts?: number;
+  /** Base delay in ms for the first backoff. Default 1000. */
+  baseDelayMs?: number;
+  /** Upper bound on any single delay. Default 30_000. */
+  maxDelayMs?: number;
+  /** Label used in log lines. */
+  label?: string;
+  /**
+   * Decides whether a given failure is worth retrying. Default: retry
+   * everything. Callers should pass a predicate that returns false for
+   * failures that will never succeed on a retry (4xx, hash mismatch), so a
+   * device does not burn battery re-requesting something already rejected.
+   */
+  isRetryable?: (err: unknown) => boolean;
+}
+
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_BASE_DELAY_MS = 1_000;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** Exposed for tests; `Math.random` is the only nondeterminism in the schedule. */
+export function backoffDelay(
+  attemptIndex: number,
+  baseDelayMs: number,
+  maxDelayMs: number,
+  random: () => number = Math.random,
+): number {
+  const exponential = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attemptIndex));
+  return Math.floor(random() * exponential);
+}
+
+/**
+ * Run `fn`, retrying on failure with exponential backoff.
+ * Rethrows the last error once attempts are exhausted.
+ */
+export async function retryWithBackoff<T>(
+  fn: (attempt: number) => Promise<T>,
+  options: RetryOptions = {},
+): Promise<T> {
+  const attempts = options.attempts ?? DEFAULT_ATTEMPTS;
+  const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS;
+  const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
+  const label = options.label ?? 'operation';
+  const isRetryable = options.isRetryable ?? (() => true);
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      return await fn(attempt);
+    } catch (err) {
+      lastError = err;
+
+      if (!isRetryable(err)) {
+        logger.debug(`[OTA] ${label} failed with a non-retryable error — not retrying`);
+        throw err;
+      }
+
+      const isLast = attempt === attempts - 1;
+      if (isLast) break;
+
+      const delay = backoffDelay(attempt, baseDelayMs, maxDelayMs);
+      logger.debug(
+        `[OTA] ${label} failed (attempt ${attempt + 1}/${attempts}) — retrying in ${delay}ms`,
+      );
+      await sleep(delay);
+    }
+  }
+
+  throw lastError;
+}
+
+/**
+ * True for failures that a later attempt could plausibly survive.
+ *
+ * Network errors and 5xx/429 are retryable. A 4xx other than 429 is the server
+ * telling us the request itself is wrong — retrying it just wastes battery.
+ */
+export function isRetryableNetworkError(err: unknown): boolean {
+  const status = (err as { status?: number } | undefined)?.status;
+  if (typeof status === 'number') {
+    if (status === 429) return true;
+    if (status >= 500) return true;
+    if (status >= 400) return false;
+  }
+  // fetch() rejects with a TypeError on DNS failure, connection refused, and
+  // airplane mode — all of which are exactly what we want to retry.
+  return true;
+}
+
+/** Error carrying an HTTP status so `isRetryableNetworkError` can classify it. */
+export class HttpStatusError extends Error {
+  constructor(
+    message: string,
+    public readonly status: number,
+  ) {
+    super(message);
+    this.name = 'HttpStatusError';
+  }
+}

package/src/features/ota/signature.ts

@@ -0,0 +1,123 @@
+import { logger } from '../../core/logger/internalLogger';
+
+/**
+ * Bundle signature verification (OTA-03).
+ *
+ * WHAT WAS WRONG. `ota-signing-key.service.ts` documents the intended model
+ * exactly: the CLI generates an ed25519 keypair locally, uploads only the public
+ * half, and "the device verifies every bundle's signature before install and
+ * rejects forgeries." Two of those three steps did not exist. The CLI had no
+ * signing code, and this SDK received `bundle.signature` in the check response
+ * and never read it. The only client-side check was SHA-256 against a hash
+ * delivered in the same response as the URL — which defends against a corrupted
+ * download and nothing else. On a platform whose entire purpose is remote code
+ * delivery, that is the control that matters most.
+ *
+ * WHY IT IS SHAPED LIKE THIS. The SDK ships zero third-party runtime
+ * dependencies, and React Native has no built-in ed25519. So verification is
+ * delegated to a host-provided verifier when one is installed, and the SDK's job
+ * is to decide — unambiguously — what happens when there is not one.
+ *
+ * THE POLICY, which is the important part:
+ *
+ *   - A bundle carrying a signature, with a configured public key and a
+ *     verifier: verified. Failure REJECTS the install. This is the goal state.
+ *   - A bundle carrying a signature, with a public key configured, but no
+ *     verifier available: REJECT. The app asked for signature enforcement by
+ *     configuring a key; silently installing unverified code because a helper is
+ *     missing would turn a security feature into a placebo.
+ *   - No public key configured: skip, and say so once. Signing is opt-in per app,
+ *     and an app that has not adopted it must keep working.
+ *
+ * The failure mode is the whole design: an app that opts in cannot be
+ * accidentally downgraded to unverified installs.
+ */
+
+/** Verifies a detached ed25519 signature. Supplied by the host app. */
+export type SignatureVerifier = (input: {
+  /** Hex-encoded SHA-256 of the bundle — what the signature is over. */
+  messageHex: string;
+  /** Hex or base64 detached signature from the check response. */
+  signature: string;
+  /** The app's configured ed25519 public key. */
+  publicKey: string;
+}) => boolean | Promise<boolean>;
+
+export interface SignatureConfig {
+  /** ed25519 public key shipped in the app binary. Absent = signing not adopted. */
+  publicKey?: string;
+  /** Host-provided ed25519 verification function. */
+  verifier?: SignatureVerifier;
+}
+
+export type SignatureOutcome =
+  | { ok: true; reason: 'verified' | 'not_configured' }
+  | { ok: false; reason: 'no_verifier' | 'invalid_signature' | 'missing_signature' | 'verifier_threw' };
+
+let warnedNotConfigured = false;
+
+/**
+ * Decide whether a bundle may be staged.
+ *
+ * Returns a structured outcome rather than a boolean so the caller can emit a
+ * precise telemetry reason — "we shipped unverified code because no key was
+ * configured" and "we refused because the signature was forged" are very
+ * different operational events and must not collapse into one.
+ */
+export async function verifyBundleSignature(
+  bundleSha256: string,
+  signature: string | undefined,
+  config: SignatureConfig | undefined,
+): Promise<SignatureOutcome> {
+  const publicKey = config?.publicKey;
+
+  // Signing not adopted by this app — nothing to enforce.
+  if (!publicKey) {
+    if (!warnedNotConfigured) {
+      warnedNotConfigured = true;
+      logger.warn(
+        '[OTA] No signing public key configured — bundles are accepted on SHA-256 ' +
+          'integrity alone. Configure `ota.publicSigningKey` to enforce authenticity.',
+      );
+    }
+    return { ok: true, reason: 'not_configured' };
+  }
+
+  // The app opted in, so a bundle without a signature is a refusal, not a pass.
+  if (!signature) {
+    logger.error(
+      '[OTA] Bundle has no signature but a signing key is configured — refusing to stage.',
+    );
+    return { ok: false, reason: 'missing_signature' };
+  }
+
+  if (typeof config?.verifier !== 'function') {
+    logger.error(
+      '[OTA] A signing key is configured but no signature verifier is available — ' +
+        'refusing to stage. Provide `ota.verifySignature` so signatures can be checked.',
+    );
+    return { ok: false, reason: 'no_verifier' };
+  }
+
+  try {
+    const valid = await config.verifier({
+      messageHex: bundleSha256,
+      signature,
+      publicKey,
+    });
+    if (!valid) {
+      logger.error('[OTA] Bundle signature is INVALID — refusing to stage.');
+      return { ok: false, reason: 'invalid_signature' };
+    }
+    return { ok: true, reason: 'verified' };
+  } catch (err: any) {
+    // A throwing verifier is treated as a failed verification, never as a pass.
+    logger.error(`[OTA] Signature verifier threw: ${err?.message ?? err}`);
+    return { ok: false, reason: 'verifier_threw' };
+  }
+}
+
+/** Test seam — resets the once-per-process "not configured" warning. */
+export function _resetSignatureWarnings(): void {
+  warnedNotConfigured = false;
+}