@scalebun/react-native 1.10.5 → 1.10.7

package/lib/module/features/ota/signature.js

@@ -1,4 +1,6 @@
 import { logger } from '../../core/logger/internalLogger';
+import { getBuiltinVerifier } from './crypto/builtinVerifier';
+import { getNativeVerifier } from './crypto/nativeVerifier';
 
 /**
  * Bundle signature verification (OTA-03).
@@ -13,10 +15,17 @@ import { logger } from '../../core/logger/internalLogger';
  * 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.
+ * WHY IT IS SHAPED LIKE THIS. React Native has no built-in ed25519, so the
+ * verification primitive has to come from somewhere. It is resolved in order:
+ * a host-supplied verifier, else the built-in one assembled from the OPTIONAL
+ * `@noble/ed25519` + `@noble/hashes` peers, else nothing — and the SDK's job is
+ * to decide, unambiguously, what happens in that last case.
+ *
+ * The built-in path exists because requiring every adopter to hand-write a
+ * verifier put the most security-critical operation in the product in code the
+ * SDK could neither test nor audit, and made a routine dependency bump able to
+ * silently stop all updates. See `crypto/builtinVerifier.ts`. Signing stays
+ * opt-in, and apps that never adopt it carry no curve arithmetic.
  *
  * THE POLICY, which is the important part:
  *
@@ -46,10 +55,16 @@ let warnedNotConfigured = false;
  * different operational events and must not collapse into one.
  */
 export async function verifyBundleSignature(bundleSha256, signature, config) {
-  const publicKey = config?.publicKey;
+  const rawKey = config?.publicKey;
+
+  // Normalize to a list. A single non-empty string is the pre-rotation config
+  // shape and behaves exactly as before; an array pins several keys at once.
+  const keys = (Array.isArray(rawKey) ? rawKey : rawKey ? [rawKey] : []).filter(k => typeof k === 'string' && k.trim().length > 0);
 
-  // Signing not adopted by this app — nothing to enforce.
-  if (!publicKey) {
+  // Signing not adopted by this app — nothing to enforce. Parity note: a
+  // falsy single value (undefined, '') has always meant "not configured" and
+  // still does.
+  if (rawKey === undefined || rawKey === '' || rawKey === null) {
     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.');
@@ -60,6 +75,19 @@ export async function verifyBundleSignature(bundleSha256, signature, config) {
     };
   }
 
+  // The host PROVIDED a key config that resolves to zero usable keys — an
+  // empty array, or an array of blank strings. That is a broken attempt to
+  // enable signing, not an absence of one, and the two must not collapse:
+  // treating `publicSigningKeys: []` as "not configured" would let a config
+  // mistake silently downgrade an app to unverified installs. Fail closed.
+  if (keys.length === 0) {
+    logger.error('[OTA] Signing key config resolves to zero usable keys (empty array or blank ' + 'strings) — refusing to stage. Remove the config to disable signing, or pin ' + 'at least one real key.');
+    return {
+      ok: false,
+      reason: 'no_keys'
+    };
+  }
+
   // 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.');
@@ -68,38 +96,70 @@ export async function verifyBundleSignature(bundleSha256, signature, config) {
       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.');
+
+  // Resolution order, and the order matters:
+  //   1. A host-supplied verifier ALWAYS wins. A team with its own crypto
+  //      policy must be able to override whatever the SDK would otherwise pick.
+  //   2. Otherwise the NATIVE verifier (CryptoKit / Android 13+ platform
+  //      ed25519). Preferred over the JS one because it runs outside the
+  //      bundle it protects and needs no optional peers; on OS levels without
+  //      ed25519 it delegates to the builtin internally.
+  //   3. Otherwise the built-in @noble verifier, if the optional peers are
+  //      installed. This is the path that removes ~100 lines of hand-written
+  //      crypto plumbing from every app that adopts signing.
+  //   4. Otherwise reject, because a configured key is a request for
+  //      enforcement and quietly installing unverified code would turn a
+  //      security feature into a placebo.
+  const verifier = typeof config?.verifier === 'function' ? config.verifier : getNativeVerifier() ?? getBuiltinVerifier();
+  if (!verifier) {
+    logger.error('[OTA] A signing key is configured but no signature verifier is available — ' + 'refusing to stage. Either install the optional peers ' + '`@noble/ed25519` and `@noble/hashes` (the SDK then verifies with no ' + 'further code), or provide your own `ota.verifySignature`.');
     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'
+
+  // Try every pinned key; any single match accepts. The verifier contract is
+  // unchanged (one key per call) so host-supplied verifiers keep working.
+  //
+  // Outcome labelling when nothing matched, and why it matters: if at least
+  // one verifier call RAN TO COMPLETION and said no, the bundle failed
+  // verification — 'invalid_signature'. Only when EVERY call threw is the
+  // machinery itself suspect — 'verifier_threw'. Collapsing those (e.g. by
+  // letting the last key's throw win) would point an investigation at the
+  // host's verifier when the actual event was a forged bundle, or vice versa.
+  let sawThrow = false;
+  let sawCompletion = false;
+  for (const key of keys) {
+    try {
+      const valid = await verifier({
+        messageHex: bundleSha256,
+        signature,
+        publicKey: key
+      });
+      sawCompletion = true;
+      if (valid) return {
+        ok: true,
+        reason: 'verified'
       };
+    } catch (err) {
+      // A throwing verifier is treated as a failed verification for this key,
+      // never as a pass — but the remaining keys still get their chance.
+      sawThrow = true;
+      logger.error(`[OTA] Signature verifier threw: ${err?.message ?? err}`);
     }
-    return {
-      ok: true,
-      reason: 'verified'
-    };
-  } catch (err) {
-    // A throwing verifier is treated as a failed verification, never as a pass.
-    logger.error(`[OTA] Signature verifier threw: ${err?.message ?? err}`);
+  }
+  if (sawThrow && !sawCompletion) {
     return {
       ok: false,
       reason: 'verifier_threw'
     };
   }
+  logger.error(keys.length > 1 ? `[OTA] Bundle signature is INVALID under all ${keys.length} pinned keys — refusing to stage.` : '[OTA] Bundle signature is INVALID — refusing to stage.');
+  return {
+    ok: false,
+    reason: 'invalid_signature'
+  };
 }
 
 /** Test seam — resets the once-per-process "not configured" warning. */

package/lib/module/metro/serializerCompose.js

@@ -74,6 +74,9 @@ export function discoverArtifacts(packageRoot) {
   return out;
 }
 
+/** One-shot guard so an Expo build does not print the pass-through notice per bundle. */
+let warnedUnknownShape = false;
+
 /**
  * Build the composing serializer. `hostSerializer` is the app's own customSerializer, if any.
  */
@@ -85,6 +88,35 @@ export function createComposingSerializer(artifacts, internals, hostSerializer)
       const hostResult = await hostSerializer(entryPoint, preModules, graph, options);
       if (typeof hostResult === 'string') {
         code = hostResult;
+      } else if (hostResult && typeof hostResult.code !== 'string') {
+        /**
+         * A shape this wrapper does not understand — pass it back UNTOUCHED.
+         *
+         * Expo is the case that matters. `expo/metro-config` installs a
+         * serializer returning `{ artifacts: [...] }`, a multi-artifact
+         * shape with no top-level `code`. Reading `.code` off it yielded
+         * undefined, and returning `{ code: undefined, map }` made every
+         * `expo export:embed` die with:
+         *
+         *   Serializer did not return expected format. The project copy
+         *   of `expo/metro-config` may be out of date.
+         *
+         * — a message that sends you to upgrade Expo, which is not the
+         * problem. The result: `withScaleBun` broke PRODUCTION BUNDLING
+         * FOR EVERY EXPO APP, and the SDK's own marketing test app could
+         * not build. Found by bundling it.
+         *
+         * Passing it through costs ScaleBun's source-map composition on
+         * Expo (OTA stack traces stay mapped to the bundle rather than to
+         * original sources). That is a real loss and strictly better than
+         * a build that cannot run at all. Composing INTO an artifact
+         * array is the follow-up; it must not be guessed at here.
+         */
+        if (!warnedUnknownShape) {
+          warnedUnknownShape = true;
+          console.warn('[ScaleBun/metro] The host serializer returned a shape this SDK does not ' + 'compose (Expo returns { artifacts }). Passing it through unchanged — ' + 'the build is correct, but ScaleBun source-map composition is skipped.');
+        }
+        return hostResult;
       } else {
         code = hostResult.code;
         try {

package/lib/module/public/ScaleBunFacade.js

@@ -18,13 +18,14 @@ import { BugReportFeature } from '../features/bugreport/BugReportFeature';
 import { PersistentQueue } from '../pipeline/queue/persistentQueue';
 import { MemoryBackend, createStorageBackend } from '../storage/StorageBackend';
 import { getDeviceId } from '../core/id/deviceId';
-import { mergeDeviceContext, resolveEventPlatform } from '../core/context/device';
+import { mergeDeviceContext, nativeDeviceContext, resolveEventPlatform } from '../core/context/device';
 import { coreContainer } from '../core/di/container';
 import { flushQueue } from '../pipeline/queue/flushQueue';
 import { enableDebug as _enableDebug, disableDebug as _disableDebug, isDebugEnabled, addBreadcrumb as _addBreadcrumb, ping as _ping, _getStream, _setFlushFn, getPerformanceFeature as _getPerformanceFeature, requestExport as _requestExport, buildDebugConfigFromInitConfig, applyFeatureGatesToDebugConfig, sendDebugMetric } from '../debug';
 import { ReplaySdk } from '../features/replay/public/api';
 import { SDKBootstrapper } from '../bootstrap/SDKBootstrapper';
 import { EventTracker } from '../analytics/EventTracker';
+import { bridgeAdapter } from '../features/replay/bridge/adapters/bridgeAdapter';
 import { emitAutomaticEvent } from '../analytics/automaticEvents';
 import { resolveEventLane, isUploadedSessionEvent } from '../analytics/eventLane';
 import { ConfigManager } from '../config/ConfigManager';
@@ -208,12 +209,17 @@ class ScaleBunFacade {
   /**
    * Boot the OTA orchestrator when the init config asks for it.
    *
-   * `publicSigningKey` is honoured here so signature enforcement is reachable
-   * from configuration alone. The SDK ships no ed25519 implementation, so a
-   * host that pins a key must also supply `ota.verifySignature`; pinning a key
-   * without a verifier is fail-CLOSED by design (signature.ts) — an update
-   * that cannot be verified is not installed. We say that out loud rather than
-   * letting the app discover it as a silent no-update condition.
+   * `publicSigningKey` / `publicSigningKeys` are honoured here so signature
+   * enforcement is reachable from configuration alone. The list form exists
+   * for key ROTATION: a build pinning [old, new] keeps verifying while the
+   * server moves to the new key, so replacing a key never needs an emergency
+   * store release. Both fields merge (deduplicated) into one pinned set.
+   *
+   * Verification comes from `ota.verifySignature` when supplied, else the
+   * built-in @noble-based verifier (optional peers). Pinning keys with
+   * NEITHER available is fail-CLOSED by design (signature.ts) — an update
+   * that cannot be verified is not installed. We say that out loud rather
+   * than letting the app discover it as a silent no-update condition.
    */
   _maybeStartOta(rawConfig) {
     const ota = rawConfig?.ota;
@@ -225,15 +231,34 @@ class ScaleBunFacade {
       const {
         otaOrchestrator
       } = require('../features/ota/OtaOrchestrator');
-      const publicKey = ota.publicSigningKey;
+      const rawSingle = ota.publicSigningKey;
+      const rawList = ota.publicSigningKeys;
+      const publicKeys = Array.from(new Set([...(typeof rawSingle === 'string' && rawSingle ? [rawSingle] : []), ...(Array.isArray(rawList) ? rawList : [])].filter(k => typeof k === 'string' && k.trim().length > 0)));
+      // Signing was REQUESTED if a usable key exists, or the host passed a
+      // keys array at all — an empty one included. `publicSigningKeys: []`
+      // is a broken attempt to enable signing, and it must flow through to
+      // signature.ts's fail-closed handling, not silently disable signing.
+      const signingRequested = publicKeys.length > 0 || Array.isArray(rawList);
       const verifier = ota.verifySignature;
-      if (publicKey && typeof verifier !== 'function') {
-        logger.warn('[ScaleBun] ota.publicSigningKey is set but ota.verifySignature is not a function. ' + 'Signature checking is fail-closed: updates will be REJECTED until a verifier is supplied.');
+      if (signingRequested && typeof verifier !== 'function') {
+        // A host verifier is optional since the built-in one landed — the
+        // old unconditional warning here told every correctly-configured
+        // app that its updates would be rejected. Warn only when neither
+        // verifier can actually be resolved.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const {
+          getBuiltinVerifier
+        } = require('../features/ota/crypto/builtinVerifier');
+        if (!getBuiltinVerifier()) {
+          logger.warn('[ScaleBun] A signing key is pinned but no signature verifier is available. ' + 'Signature checking is fail-closed: updates will be REJECTED until one exists. ' + 'Install the optional peers `@noble/ed25519` + `@noble/hashes` (no further ' + 'code needed), or supply `ota.verifySignature`.');
+        }
       }
       otaOrchestrator.init({
-        ...(publicKey ? {
+        ...(signingRequested ? {
           signature: {
-            publicKey,
+            // Single key stays a plain string — the shape every
+            // existing consumer and test already handles.
+            publicKey: publicKeys.length === 1 ? publicKeys[0] : publicKeys,
             verifier
           }
         } : {}),
@@ -307,6 +332,8 @@ class ScaleBunFacade {
          * the whole time. The SDK knows the device; the integrator is guessing at it.
          * Everything outside the detected keys is still theirs.
          */
+        // Everything Platform.constants knows. On iOS that is neither the model nor the
+        // manufacturer, so the bridge completes it below once it answers.
         context: mergeDeviceContext(rawConfig?.context),
         // Use the same foreground id as replay/journey capture. The
         // callback is resolved per event because the session subsystem
@@ -321,6 +348,19 @@ class ScaleBunFacade {
       this._eventTracker.start();
       __DEV__ && logger.info('[ScaleBun] Envelope event tracking started → /v1/batch.');
 
+      // Complete the device context from the native bridge.
+      //
+      // `Platform.constants` answers Android synchronously — model and manufacturer ride the
+      // first event. It answers NEITHER on iOS, so without this every iOS installation
+      // reported no device model at all: `nativeDeviceContext` existed for exactly this and
+      // had no caller, and the bridge's own answer was `UIDevice.current.model` — the string
+      // "iPhone", identical on every iPhone ever made.
+      //
+      // Fire-and-forget on purpose. The bridge is async and absent entirely on Expo Go or an
+      // older native binary; waiting on it would delay the first event, and failing on it
+      // would take analytics down over a nice-to-have field.
+      this._applyNativeDeviceContext(this._eventTracker);
+
       // Android: capture the Play Install Referrer once per install → feeds the
       // deterministic click_id path + a one-off install_referrer event (UTM/gclid).
       // Fire-and-forget; no-op off Android.
@@ -345,6 +385,24 @@ class ScaleBunFacade {
     }
   }
 
+  /**
+   * Fold the native bridge's device facts into the analytics context once it answers.
+   *
+   * Detected values never overwrite a populated one with an empty one — `nativeDeviceContext`
+   * drops absent keys and `applyDetectedContext` ignores an empty patch — so a bridge that
+   * cannot answer leaves whatever `Platform.constants` already found.
+   */
+  _applyNativeDeviceContext(tracker) {
+    Promise.resolve().then(() => bridgeAdapter.getDeviceInfo()).then(info => {
+      if (!info) return;
+      tracker.applyDetectedContext(nativeDeviceContext({
+        osVersion: info.osVersion,
+        deviceModel: info.deviceModel
+        // iOS ships no manufacturer over the bridge; it is a constant there and the
+        // static path already set it. Android's arrives via Platform.constants.
+      }));
+    }).catch(() => {/* bridge unavailable — the static context stands */});
+  }
   /**
    * Android-only: read the Play Install Referrer once per install and route it into
    * attribution. `scalebun_click_id` → the deterministic click path; the full
@@ -437,6 +495,45 @@ class ScaleBunFacade {
   }
 
   /** Convenience: emit a Phase 1 purchase event (revenue + currency + transaction_id). */
+  /**
+   * Declare which UI state the user is looking at, so taps are attributed to the surface they
+   * happened on rather than averaged across every variant of the screen.
+   *
+   *     ScaleBun.setUiState('filter-sheet', 'open');
+   *     ScaleBun.setUiState('checkout-step', 'payment');
+   *
+   * Call it when the state CHANGES — the value is read at tap time, so it only has to be right by
+   * the time the next tap lands. On React Native this is the ONLY source of UI state: unlike the web,
+   * there is no queryable accessibility tree that says a sheet is up, and guessing would produce a
+   * state key that is right on some apps and silently wrong on others.
+   *
+   * Names and values are identifiers, not content: they become query keys in the dashboard, so a
+   * person's name or a cart total does not belong in one. `;`, `:` and `|` are stripped and both
+   * halves are capped at 32 characters.
+   */
+  setUiState(name, value) {
+    try {
+      const {
+        setUiState
+      } = require('../features/journey/uiState');
+      setUiState(name, value);
+    } catch {/* no-throw: a state declaration must never break the host */}
+  }
+
+  /**
+   * Stop reporting a UI state dimension — or, with no argument, all of them.
+   *
+   * Clear on screen unmount. A declaration left behind follows the user onto a surface where it means
+   * nothing, and every tap there is filed under a state that was not on screen.
+   */
+  clearUiState(name) {
+    try {
+      const {
+        clearUiState
+      } = require('../features/journey/uiState');
+      clearUiState(name);
+    } catch {/* no-throw */}
+  }
   trackPurchase(input) {
     noThrow(() => this._eventTracker?.trackPurchase(input));
   }

package/lib/typescript/analytics/EventTracker.d.ts

@@ -134,6 +134,21 @@ export declare class EventTracker {
     }): void;
     flush(): Promise<void>;
     stop(): void;
+    /**
+     * Fold in device facts that were not knowable at init.
+     *
+     * `Platform.constants` answers Android synchronously, so its model and manufacturer ride the
+     * very first event. iOS exposes neither there — only the native bridge knows, and the bridge is
+     * async and may not be installed at all. Without this the iOS half of every install reported no
+     * model whatsoever.
+     *
+     * `buildEnvelope` reads `cfg.context` per event, so applying it here reaches every event from
+     * the next one onward. Detected keys WIN over whatever the integrator configured, for the same
+     * reason `mergeDeviceContext` inverts the usual precedence: a measurement must not be
+     * overridable by a guess. Empty patches are ignored so a bridge that answered with nothing
+     * cannot blank a value the static path already found.
+     */
+    applyDetectedContext(patch: Record<string, string>): void;
     private buildEnvelope;
     private enqueue;
     private scheduleFlush;

package/lib/typescript/core/config/schema.d.ts

@@ -93,6 +93,8 @@ export interface ScaleBunConfig {
         checkOnForeground: boolean;
         channelOverride?: string;
         publicSigningKey?: string;
+        /** Additional pinned keys for rotation; unioned with publicSigningKey. */
+        publicSigningKeys?: string[];
         mandatoryBlocksUi: boolean;
     };
 }

package/lib/typescript/core/constants/version.d.ts

@@ -3,5 +3,5 @@
  * can attribute telemetry to the SDK build that produced it.
  * Keep in sync with package.json "version".
  */
-export declare const SDK_VERSION = "1.10.5";
+export declare const SDK_VERSION = "1.10.7";
 //# sourceMappingURL=version.d.ts.map

package/lib/typescript/core/context/device.d.ts

@@ -34,6 +34,7 @@ export declare function nativeDeviceContext(info: {
     platform?: string;
     osVersion?: string;
     deviceModel?: string;
+    manufacturer?: string;
 } | null): Record<string, string>;
 /**
  * Merge the integrator's context with what we detected — DETECTED WINS on the keys above.

package/lib/typescript/features/journey/uiState.d.ts

@@ -0,0 +1,53 @@
+/**
+ * UI STATE AT INTERACTION TIME — React Native.
+ *
+ * A screen is not just `Cart`. It is `Cart` with the filter sheet down, or up; with the address form
+ * expanded, or collapsed. Those are different interaction surfaces and a tap on one must never be
+ * counted on another — heat from the open sheet painted over the closed layout is a picture of
+ * something that never existed.
+ *
+ * HOW THIS DIFFERS FROM THE WEB, and the difference is not an omission:
+ *
+ *   The web SDK ALSO detects state automatically, by reading `aria-expanded` and open `<dialog>`
+ *   elements out of the live DOM. Those are platform-defined, so reading them is a measurement.
+ *
+ *   React Native has no equivalent. There is no queryable tree of accessibility state that says a
+ *   bottom sheet is up; a sheet is a component with a boolean in someone's store, and the only place
+ *   that boolean exists is the host's own code. Guessing at it — from a modal's presence in the tree, or
+ *   from a component name — would produce a state key that is right on some apps and silently wrong on
+ *   others, and a wrong state key partitions taps into buckets corresponding to nothing.
+ *
+ * So on RN, state is DECLARED and never inferred. `ScaleBun.setUiState('filter-sheet', 'open')` is the
+ * whole mechanism, and its absence means "not captured" rather than "nothing was open". That
+ * distinction is carried all the way to the dashboard: a tap with no declared state is NULL, not '',
+ * and cannot be selected as a state or counted as one. Reporting it as "nothing was open" would be
+ * asserting a measurement nobody took.
+ *
+ * PAIRED WITH: whatzbug-web-sdk/packages/web/src/features/journey/uiState.ts — same wire format
+ * (`name:value` pairs, sorted, `;`-joined, <= 96 chars), same separator stripping, same explicit-wins
+ * precedence, so one dashboard control queries both platforms.
+ */
+/**
+ * Declare the state of one UI dimension.
+ *
+ * Call it when the state CHANGES, not on every render: the value is read at interaction time, so it
+ * only has to be correct by the time the next tap lands.
+ */
+export declare function setUiState(name: string, value: string): void;
+/**
+ * Stop reporting a dimension — or, with no name, all of them.
+ *
+ * Later taps carry no value for it, which is not the same as carrying a value. Clearing all is what a
+ * screen unmount wants: declarations from the previous screen would otherwise follow the user onto a
+ * surface where they mean nothing, and every tap there would be filed under a state that was not on
+ * screen.
+ */
+export declare function clearUiState(name?: string): void;
+/**
+ * The signature for the interaction happening RIGHT NOW, or undefined when nothing is declared.
+ *
+ * undefined rather than '' deliberately — see the header. '' is the web's "we looked and nothing was
+ * open"; on RN there is nothing to look at, so the honest answer is silence.
+ */
+export declare function uiStateSignature(): string | undefined;
+//# sourceMappingURL=uiState.d.ts.map

package/lib/typescript/features/ota/OtaTypes.d.ts

@@ -5,6 +5,49 @@
  * 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.
  */
+/**
+ * ═══════════════════════════════════════════════════════════════════════════
+ * OTA-TELEMETRY-SPEC — remaining telemetry fixes (from the 2026-08 audit)
+ * ═══════════════════════════════════════════════════════════════════════════
+ * These close the SDK half of spec §84-86. All are ADDITIVE + backward-compatible
+ * (new optional fields, new enum members, new no-throw emit calls); old installed
+ * clients omit them and the backend ingests nullable/unknown fields. Each ALTERS
+ * DEVICE RUNTIME BEHAVIOR, so land them behind a real RN build + device/kill-test
+ * (Metro cannot exercise the boot-guard) — this file only carries the contract
+ * types + this spec, not the runtime wiring.
+ *
+ * 1. releaseId end-to-end  (CRITICAL — root of the dashboard funnel mismatch)
+ *    Backend already serves it: OtaBundlePayload.releaseId (done, this file +
+ *    ota-check.service.ts). SDK TODO:
+ *      - store payload.releaseId on the downloaded/installed bundle state, and
+ *      - set `releaseId: bundle.releaseId` in the delivery mapper
+ *        OtaOrchestrator.ts deliverOtaEvents (~:105) — currently only bundleId.
+ *      Then ota_events carry releaseId and the funnel keys by release.
+ *
+ * 2. Emit CHECK + OFFERED  (funnel top is currently unmeasurable)
+ *    - CHECK: emit at the start of checkForUpdate (OtaOrchestrator.ts ~:480),
+ *      before the fetch. ('CHECK' type already exists — no emit site today.)
+ *    - OFFERED: add 'OFFERED' to OtaEventType, emit when checkRes.action ===
+ *      'DOWNLOAD' (~:619) before download begins.
+ *
+ * 3. Emit BOOT_SUCCESS  (honest activation signal)
+ *    Add 'BOOT_SUCCESS' to OtaEventType and emit it from the boot-guard
+ *    markHealthy path (OtaOrchestrator.ts ~:863). INSTALLED (~:794) is emitted
+ *    optimistically BEFORE the bundle boots; keep it (it means "staged+swapped")
+ *    but let the dashboard measure real activation on BOOT_SUCCESS. Optionally
+ *    add 'VERIFIED' after signature check (~:635).
+ *
+ * 4. Stamp the running OTA bundle onto session/crash telemetry
+ *    SessionMetadata.bundleId is the NATIVE app package id, not the OTA bundle.
+ *    Add optional otaBundleId?/otaBundleVersion? (distinct fields — do NOT
+ *    overload bundleId) sourced from otaOrchestrator.getCurrentBundle() at
+ *    session start (SessionManager.ts ~:451), so crashes attribute to the
+ *    running bundle/version (release-health crash impact).
+ *
+ * Do NOT repurpose errorCode (it already collapses failure-error vs rollback-
+ * reason); add a new optional field if the two must be distinguished.
+ * ═══════════════════════════════════════════════════════════════════════════
+ */
 export interface OtaCheckRequest {
     appVersion: string;
     platform: 'android' | 'ios';
@@ -43,6 +86,13 @@ export interface OtaCheckResponse {
 export interface OtaBundlePayload {
     id: string;
     version: number;
+    /**
+     * The release this bundle is served AS (the backend now includes it — see
+     * ota.contracts.ts / ota-check.service.ts). Optional, for backward-compat with
+     * older backends. Carry it onto the emitted OtaEventItem.releaseId so telemetry
+     * is attributable by RELEASE, not just bundle. See OTA-TELEMETRY-SPEC below.
+     */
+    releaseId?: string;
     url: string;
     size: number;
     sha256: string;

package/lib/typescript/features/ota/crypto/builtinVerifier.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Built-in ed25519 verifier, assembled from OPTIONAL peer dependencies.
+ *
+ * WHAT THIS REPLACES. Pinning `ota.publicSigningKey` used to require the host
+ * app to write its own `verifySignature` — roughly a hundred lines of hex and
+ * base64 decoding wrapped around a crypto library. That put the single most
+ * security-critical operation in the product, the one deciding whether remote
+ * code is authentic before it executes, in code the SDK could neither test nor
+ * audit. Three failure modes all landed on the app author:
+ *
+ *   - A verifier that always returns `true` silently disables the feature, and
+ *     nothing can detect it.
+ *   - @noble's hash-provider property moved between major versions, so a
+ *     routine dependency bump made every update fail closed with no signal
+ *     pointing at the cause.
+ *   - Hand-written base64 decoders tend to omit base64url, so a signature
+ *     containing `-` or `_` is rejected as a forgery.
+ *
+ * All three are now the SDK's problem, which is where they belong. A host that
+ * installs `@noble/ed25519` and `@noble/hashes` gets verification by pinning a
+ * key and writing no code at all.
+ *
+ * WHY OPTIONAL AND NOT A HARD DEPENDENCY. Most apps never adopt bundle
+ * signing, and they should not carry curve arithmetic they will not run. The
+ * `verifySignature` hook remains supported and still WINS over this, for teams
+ * with their own crypto policy or a native implementation to delegate to.
+ *
+ * WHAT THIS DOES NOT FIX. Verification still happens in JS, inside the very
+ * bundle it protects. An attacker who lands one malicious bundle by other means
+ * can neuter the check for every update after it. Closing that needs native
+ * verification — CryptoKit on iOS (13.4+, already the deployment target) and
+ * `Signature.getInstance("Ed25519")` on Android API 33+, with a fallback below.
+ */
+import type { SignatureVerifier } from '../signature';
+/**
+ * Decode a detached signature that may arrive hex- or base64-encoded.
+ *
+ * Tries the unambiguous case first: 128 hex characters is exactly 64 bytes and
+ * cannot be anything else. Otherwise base64, then hex as a last resort. Only a
+ * result of exactly 64 bytes is accepted, so a string that decodes under the
+ * wrong scheme is rejected rather than fed to the curve code as garbage.
+ */
+export declare function decodeSignature(sig: string): Uint8Array | null;
+/**
+ * The built-in verifier, or null when the optional deps are not installed.
+ * Resolution is cached, including the negative result — a missing dependency
+ * does not become present at runtime, and retrying the require on every update
+ * check would be pure overhead.
+ */
+export declare function getBuiltinVerifier(): SignatureVerifier | null;
+/** Test seam — clears the cached resolution. */
+export declare function _resetBuiltinVerifier(): void;
+//# sourceMappingURL=builtinVerifier.d.ts.map

package/lib/typescript/features/ota/crypto/loadEd25519.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Isolated lazy loader for the OPTIONAL `@noble/ed25519` dep.
+ *
+ * WHY ITS OWN FILE: Metro's dependency collector emits a dependency map one
+ * entry short for a module containing TWO OR MORE different-string inline
+ * `require()` calls, so the require indices desync and `_dependencyMap[N]`
+ * reads `undefined` ("Requiring unknown module 'undefined'"). Exactly ONE
+ * inline require per module avoids the miscount. `loadSha512` is a sibling file
+ * for the same reason — see `push/adapters/loadNotifee.ts`, which hit this first.
+ *
+ * The string must still be STATICALLY resolvable at bundle time; hosts that do
+ * not install it stub it via `withScaleBun`.
+ */
+/** The subset of the @noble/ed25519 surface this SDK uses. */
+export interface NobleEd25519 {
+    verifyAsync?: (sig: Uint8Array, msg: Uint8Array, pub: Uint8Array) => Promise<boolean>;
+    verify?: (sig: Uint8Array, msg: Uint8Array, pub: Uint8Array) => boolean;
+    /** v3 shape: `ed.hashes.sha512` */
+    hashes?: {
+        sha512?: unknown;
+        sha512Async?: unknown;
+    };
+    /** v2 shape: `ed.etc.sha512Sync` */
+    etc?: {
+        sha512Sync?: unknown;
+        sha512Async?: unknown;
+    };
+}
+export declare function loadEd25519(): NobleEd25519 | null;
+//# sourceMappingURL=loadEd25519.d.ts.map