@scalebun/react-native 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalebun/react-native",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Production-grade React Native SDK for ScaleBun",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",
@@ -104,7 +104,8 @@
   "dependencies": {
     "@babel/runtime": "^7.25.0",
     "@jridgewell/sourcemap-codec": "1.5.5",
-    "@jridgewell/trace-mapping": "0.3.31"
+    "@jridgewell/trace-mapping": "0.3.31",
+    "@scalebun/cli": "^1.6.0"
   },
   "codegenConfig": {
     "name": "ScaleBunSpec",

package/src/analytics/EventTracker.ts

@@ -317,7 +317,27 @@ export class EventTracker {
         const effectiveBatch = clampBatchSize(this.cfg.batchSize, DEFAULT_BATCH);
         const batch = this.queue.slice(0, effectiveBatch);
         try {
-            // Sign the exact bytes we send so the backend can tamper-detect the payload.
+            // WHAT THIS SIGNATURE IS, AND WHAT IT IS NOT.
+            //
+            // This used to be described as letting "the backend tamper-detect
+            // the payload", which overstates it to the point of being wrong.
+            // The HMAC key is `clientKey` — the same value sent beside it in
+            // `x-scalebun-client-key`, and a value that ships inside every
+            // installed app, extractable by anyone who unzips an APK. A MAC
+            // whose key travels with the message and is public by construction
+            // proves nothing about who sent it: anyone can compute a valid one.
+            //
+            // What it DOES buy is integrity in transit against non-adversarial
+            // corruption, and a cheap filter for junk traffic. Treat `clientKey`
+            // as a publishable identifier (like a Stripe publishable key), never
+            // as a trust boundary. Authenticity that actually holds has to come
+            // from something the client cannot forge — server-side rate limits
+            // and anomaly detection per key, short-lived device tokens, or
+            // platform attestation (Play Integrity / App Attest).
+            //
+            // Contrast with OTA bundle signing (features/ota/signature.ts),
+            // which is asymmetric: the private half never leaves the publisher,
+            // so a valid signature there IS proof of origin.
             const payload = JSON.stringify({ events: batch });
             // Wave 2 (§2F.2): a stable idempotency key over the batch's event ids so a
             // retry after a timeout/disconnect replays the first response instead of

package/src/core/constants/version.ts

@@ -3,4 +3,4 @@
  * can attribute telemetry to the SDK build that produced it.
  * Keep in sync with package.json "version".
  */
-export const SDK_VERSION = '1.4.0';
+export const SDK_VERSION = '1.6.0';

package/src/core/id/installationId.ts

@@ -0,0 +1,52 @@
+import { createStorageBackend } from '../../storage/StorageBackend';
+import { K_INSTALLATION_ID } from '../../analytics/EventTracker';
+
+/**
+ * The SDK's canonical per-install id.
+ *
+ * ONE install, ONE id, every lane. This is deliberately NOT `getDeviceId()` —
+ * that is a separate value under a separate storage key, and the backend schema
+ * annotates the two as different ("stable per-install id from the SDK (≠
+ * deviceId)").
+ *
+ * It matters because the backend joins a bundle's OTA installs to that device's
+ * sessions through this value. OTA events have always been keyed by it; the
+ * session lane did not send it at all, so on the server the two could only be
+ * connected for devices that happened to have registered for push. Release
+ * health then reported "no data" for bundles that were running perfectly well —
+ * or crashing badly.
+ *
+ * Lives here rather than inside one feature so the OTA orchestrator and the
+ * session adapter cannot drift to two different ids.
+ */
+export function resolveInstallationId(): string {
+    try {
+        const storage = createStorageBackend();
+        const existing = storage.get(K_INSTALLATION_ID);
+        if (existing) return existing;
+        const id = `inst-${randomSegment()}${randomSegment()}`;
+        storage.set(K_INSTALLATION_ID, id);
+        return id;
+    } catch {
+        // Storage unavailable (tests, exotic hosts): a per-process id keeps the
+        // lanes functional; it stabilizes on the first run where storage works.
+        return `inst-ephemeral-${randomSegment()}`;
+    }
+}
+
+/** 8 chars of base36 entropy, crypto-backed when the runtime offers it. */
+function randomSegment(): string {
+    try {
+        const g = globalThis as { crypto?: { getRandomValues?: (a: Uint8Array) => Uint8Array } };
+        if (g.crypto?.getRandomValues) {
+            const bytes = g.crypto.getRandomValues(new Uint8Array(6));
+            return Array.from(bytes)
+                .map((b) => b.toString(36).padStart(2, '0'))
+                .join('')
+                .slice(0, 8);
+        }
+    } catch {
+        // fall through to Math.random
+    }
+    return Math.random().toString(36).slice(2, 10).padEnd(8, '0');
+}

package/src/debug/bootstrap.ts

@@ -67,6 +67,24 @@ export interface DebugConfig {
     /** @internal */
     _performanceDisabled?: boolean;
     enableProfiler?: boolean;
+    /**
+     * Permit the debug channel in a RELEASE build. Default false, and you
+     * almost certainly want it that way.
+     *
+     * The transport is an unencrypted `ws://` socket that carries captured
+     * console output, network traffic and the shared `secret` itself in
+     * cleartext, readable by anyone on the same Wi-Fi. That is an acceptable
+     * trade for a developer on their own machine and not acceptable in an app
+     * on a user's phone.
+     *
+     * Until now the only thing standing between those two cases was that the
+     * desktop tooling is excluded from bundles by default — a BUILD-time
+     * opt-out, not a release check. Anyone who set `devTools: true` to debug
+     * locally and shipped without reverting it published an app that opens
+     * that socket in production. This flag makes that a deliberate act rather
+     * than an oversight.
+     */
+    allowInRelease?: boolean;
 }
 
 // ─── Singleton State ────────────────────────────────────────────────────────
@@ -115,6 +133,24 @@ export function enableDebug(config: DebugConfig): void {
             return;
         }
 
+        // Refuse in release builds. See `allowInRelease` on DebugConfig: this
+        // channel is plaintext ws:// carrying console output, network traffic
+        // and the shared secret, and the only previous guard was that the
+        // tooling is excluded from bundles by default — which a developer
+        // disables to debug locally and then forgets. Warn rather than fail
+        // silently, because a debug connection that does nothing with no
+        // explanation is its own long afternoon.
+        if (!__DEV__ && !config.allowInRelease) {
+            logger.warn(
+                '[ScaleBun] Debug connection refused in a release build. The debug ' +
+                    'transport is unencrypted (ws://) and carries captured traffic and the ' +
+                    'shared secret in cleartext, so it is development-only by default. If ' +
+                    'you genuinely need it in a release build, set ' +
+                    '`allowInRelease: true` — and do not ship that to users.',
+            );
+            return;
+        }
+
         // The desktop-debugger tooling can be excluded from a build via
         // `withScaleBun(config, { features: { devTools: false } })`, which resolves these modules
         // to an empty stub. Detect that explicitly: without this check the first `new

package/src/features/ota/OtaOrchestrator.ts

@@ -13,7 +13,7 @@ import type { OtaCheckRequest, OtaCheckResponse, OtaBundlePayload } from './OtaT
 import { otaEventEmitter } from './OtaEventEmitter';
 import { getDeviceCountry, prefetchDeviceCountry } from './geoCountry';
 import { deviceTargetingAttributes } from './deviceAttributes';
-import { K_INSTALLATION_ID } from '../../analytics/EventTracker';
+import { resolveInstallationId } from '../../core/id/installationId';
 import { verifyBundleSignature, type SignatureConfig } from './signature';
 import { detectOtaEnvironment, type OtaEnvironment } from './environment';
 import { retryWithBackoff, isRetryableNetworkError, HttpStatusError } from './retry';
@@ -71,35 +71,6 @@ function subscribeNativeProgress(
 /** POST at most once per this interval; first and terminal ticks always go. */
 const PROGRESS_POST_INTERVAL_MS = 1_000;
 
-/**
- * P8 — the SDK's canonical per-install id, shared with the analytics lane.
- *
- * OTA used to REQUIRE a caller-supplied `installationId`, and the documented
- * example passed `deviceId` — so OTA telemetry lived in its own identity
- * namespace, disconnected from the id every other lane reports. Every join
- * from OTA data to CDP data (blast radius, MRR-at-risk, churn bands) was a
- * cross-namespace join that matched by luck.
- *
- * Reads (or mints, for OTA-only apps that never initialize analytics) the same
- * persisted value `EventTracker` uses, via the same storage backend and the
- * same exported key — one install, one id, every lane.
- */
-function resolveInstallationId(): string {
-  try {
-    const storage = createStorageBackend();
-    const existing = storage.get(K_INSTALLATION_ID);
-    if (existing) return existing;
-    const id = `inst-${Math.random().toString(36).slice(2, 10)}${Math.random()
-      .toString(36)
-      .slice(2, 10)}`;
-    storage.set(K_INSTALLATION_ID, id);
-    return id;
-  } catch {
-    // Storage unavailable (tests, exotic hosts): a per-process id keeps sync
-    // functional; it will stabilize on the first run where storage works.
-    return `inst-ephemeral-${Math.random().toString(36).slice(2, 10)}`;
-  }
-}
 
 /**
  * Deliver queued OTA lifecycle events to the backend's batch endpoint.

package/src/features/session/BackendSessionAdapter.ts

@@ -26,6 +26,7 @@
 import { logger } from '../../core/logger/internalLogger';
 import { base64ToBytes } from '../../core/encoding/base64';
 import { ENDPOINTS } from '../../transport/http/endpoints';
+import { resolveInstallationId } from '../../core/id/installationId';
 import { SDK_VERSION } from '../../core/constants/version';
 import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
 import { getReplaySdkNative } from '../replay/bridge/nativeModule';
@@ -262,6 +263,13 @@ export class BackendSessionAdapter implements SessionTransport {
                 const payload = {
                     sessionId: session.sessionId,
                     deviceId: session.deviceId,
+                    // The canonical per-install id — the SAME value OTA events are
+                    // reported under, and a DIFFERENT value from deviceId. The
+                    // backend stores it on the Device so release health can join a
+                    // bundle's installs to that device's sessions. Without it, crash
+                    // impact for a release resolves to "no data" for every device
+                    // that never registered for push.
+                    installationId: resolveInstallationId(),
                     startedAt: session.startedAt,
                     // Link the recording row to the always-on analytics row so the
                     // dashboard can join them. track() events land on the analytics