@scalebun/react-native 1.10.6 → 1.10.7

package/src/features/ota/signature.ts

@@ -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:
  *
@@ -44,15 +53,26 @@ export type SignatureVerifier = (input: {
 }) => boolean | Promise<boolean>;
 
 export interface SignatureConfig {
-  /** ed25519 public key shipped in the app binary. Absent = signing not adopted. */
-  publicKey?: string;
+  /**
+   * ed25519 public key(s) shipped in the app binary. Absent = signing not
+   * adopted. An ARRAY pins several keys at once and a bundle is accepted when
+   * ANY of them verifies — this is what makes key rotation possible without an
+   * app-store release: ship a build pinning [old, new], start signing with new,
+   * drop old from the next build. With a single pinnable key, losing the
+   * private key meant no OTA capability until a new binary cleared review —
+   * the exact emergency OTA exists to solve.
+   */
+  publicKey?: string | 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' };
+  | {
+      ok: false;
+      reason: 'no_verifier' | 'invalid_signature' | 'missing_signature' | 'verifier_threw' | 'no_keys';
+    };
 
 let warnedNotConfigured = false;
 
@@ -69,10 +89,18 @@ export async function verifyBundleSignature(
   signature: string | undefined,
   config: SignatureConfig | undefined,
 ): Promise<SignatureOutcome> {
-  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): k is string => 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(
@@ -83,6 +111,20 @@ export async function verifyBundleSignature(
     return { ok: true, reason: 'not_configured' };
   }
 
+  // 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(
@@ -91,30 +133,71 @@ export async function verifyBundleSignature(
     return { ok: false, reason: 'missing_signature' };
   }
 
-  if (typeof config?.verifier !== 'function') {
+  // 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. Provide `ota.verifySignature` so signatures can be checked.',
+        '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: any) {
+      // 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: any) {
-    // 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/src/metro/serializerCompose.ts

@@ -106,6 +106,9 @@ export function discoverArtifacts(packageRoot: string): ArtifactMapping[] {
     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.
  */
@@ -122,10 +125,43 @@ export function createComposingSerializer(
             const hostResult = await hostSerializer(entryPoint, preModules, graph, options);
             if (typeof hostResult === 'string') {
                 code = hostResult;
+            } else if (hostResult && typeof (hostResult as any).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 as never;
             } else {
-                code = hostResult.code;
+                code = (hostResult as { code: string; map: string }).code;
                 try {
-                    mapObj = JSON.parse(hostResult.map);
+                    mapObj = JSON.parse((hostResult as { code: string; map: string }).map);
                 } catch {
                     // Host emitted an unparsable map; fall through and rebuild from the graph so
                     // the build still succeeds with a correct map rather than failing here.

package/src/public/ScaleBunFacade.ts

@@ -275,12 +275,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.
      */
     private _maybeStartOta(rawConfig: any): void {
         const ota = rawConfig?.ota;
@@ -290,16 +295,49 @@ class ScaleBunFacade {
             // module (or touch the native spec) at import time.
             // eslint-disable-next-line @typescript-eslint/no-var-requires
             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: unknown): k is string => 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 ? { signature: { publicKey, verifier } } : {}),
+                ...(signingRequested
+                    ? {
+                          signature: {
+                              // Single key stays a plain string — the shape every
+                              // existing consumer and test already handles.
+                              publicKey: publicKeys.length === 1 ? publicKeys[0] : publicKeys,
+                              verifier,
+                          },
+                      }
+                    : {}),
                 ...(typeof ota.healthyTimeoutMs === 'number'
                     ? { healthyTimeoutMs: ota.healthyTimeoutMs }
                     : {}),
@@ -526,6 +564,42 @@ 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.
+     */
+    public setUiState(name: string, value: string): void {
+        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.
+     */
+    public clearUiState(name?: string): void {
+        try {
+            const { clearUiState } = require('../features/journey/uiState');
+            clearUiState(name);
+        } catch { /* no-throw */ }
+    }
+
     public trackPurchase(input: { revenue: number; currency: string; transactionId: string; [k: string]: any }): void {
         noThrow(() => this._eventTracker?.trackPurchase(input));
     }

package/src/specs/NativeScaleBunOta.ts

@@ -85,6 +85,30 @@ export interface Spec extends TurboModule {
    * `recreateReactContextInBackground()` (bridge). iOS: RCTReloadCommand.
    */
   restartApp(): void;
+
+  /**
+   * Verify a detached ed25519 signature in NATIVE code.
+   *
+   * Exists because the JS verifier runs inside the very bundle it protects —
+   * an attacker who lands one malicious bundle can neuter a JS check for every
+   * update after it. Platform crypto is outside the bundle's reach, and it also
+   * removes the runtime dependency on the optional @noble peers wherever the OS
+   * provides ed25519 (iOS 13+ CryptoKit everywhere; Android API 33+).
+   *
+   * All three arguments are lowercase hex, pre-validated by the JS caller:
+   * the 32-byte bundle SHA-256 (the signature is over its RAW BYTES, matching
+   * the CLI's signing contract), the 64-byte signature, the 32-byte public key.
+   *
+   * Resolves a verdict STRING, not a boolean, because "the signature is wrong"
+   * and "this OS cannot check" must never collapse into one value:
+   *   'valid'       — signature verifies under the key
+   *   'invalid'     — it does not; the caller must refuse the bundle
+   *   'unavailable' — this OS level has no ed25519 (Android < 33); the caller
+   *                   falls back to the JS verifier
+   * A rejected promise is machinery failure and the caller treats it as
+   * 'unavailable' — never as 'valid'.
+   */
+  verifyEd25519(messageHex: string, signatureHex: string, publicKeyHex: string): Promise<string>;
 }
 
 /**