pulse-updates 1.3.8 → 1.3.10

package/README.md

@@ -138,7 +138,11 @@ On a recent iOS first open, the host may call `links.matchFirstOpen` with its na
 bundle id and locale. It may also provide bounded ephemeral release/model dimensions (app/OS
 version, hardware model code, device type, distribution, timezone offset and emulator flag). Pulse
 validates and omits malformed values. The request intentionally contains no unique device id,
-IDFV/IDFA, account, clipboard value or client-observed IP. Ambiguous matches produce no action.
+IDFV/IDFA, clipboard value or client-observed IP. It carries the signed-in address only when the
+integrator sets `sendAccountEmailOnFirstOpen` and the host passes one: an install that names its
+account is bound to the message sent there instead of being inferred, which is the only
+deterministic signal left where no store referrer survives. The switch is off by default, so
+reading your own auth state never starts forwarding addresses by itself. Ambiguous matches produce no action.
 Sensitive actions are rejected for every probabilistic result even if a malformed server response
 claims otherwise. A random install-attempt nonce may accompany later deterministic resolver
 outcomes so the server can calibrate its earlier probabilistic decision against deterministic

package/android/src/main/java/app/pulse/updates/PulseController.kt

@@ -157,6 +157,29 @@ class PulseController private constructor() {
             }
         }
 
+    /**
+     * Which binary this is — the versionCode, as a string.
+     *
+     * The runtime version is versionName, and several versionCodes ship under one. Where bundles
+     * are wrapped for integrity that means several keys behind one runtime version, and a bundle
+     * wrapped for another build cannot be opened: the app does not degrade, it stops starting. This
+     * is what lets the server keep those bundles apart. Null when the package cannot be read, in
+     * which case the header is omitted and the server serves as it always did.
+     */
+    internal val nativeBuildNumber: String?
+        get() = try {
+            val ctx = context
+            if (ctx == null) null else {
+                val info = ctx.packageManager.getPackageInfo(ctx.packageName, 0)
+                @Suppress("DEPRECATION")
+                val code = if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.P)
+                    info.longVersionCode else info.versionCode.toLong()
+                code.toString()
+            }
+        } catch (e: Exception) {
+            null
+        }
+
     /**
      * Load config from AndroidManifest.xml metadata (like expo-updates)
      */
@@ -1339,6 +1362,12 @@ object PulseRemoteLoader {
             // Stable device id so the server can bucket this device into staged rollouts (without it,
             // a device is held back from any partial rollout until it reaches 100%).
             connection.setRequestProperty("Pulse-Device-Id", PulseController.getInstance().deviceId)
+            // WHICH binary is asking. The runtime version is versionName, and several versionCodes
+            // can ship under one — so where bundles are wrapped for integrity, one runtime version
+            // can mean several keys, and a bundle wrapped for another build cannot be opened at all.
+            // versionCode is the number that always moves, so the server can keep a bundle prepared
+            // for one build away from the others. Servers that do not know the header ignore it.
+            PulseController.getInstance().nativeBuildNumber?.let { connection.setRequestProperty("Pulse-Native-Build", it) }
 
             pulseLog(TAG, "checkForUpdate: url=${config.updateUrl}")
             pulseLog(TAG, "checkForUpdate: runtimeVersion=${config.runtimeVersion}")

package/ios/PulseUpdates/PulseController.swift

@@ -1364,6 +1364,16 @@ final class PulseRemoteLoader {
         // Stable device id so the server can bucket this device into staged rollouts (without it,
         // a device is held back from any partial rollout until it reaches 100%).
         request.setValue(PulseController.shared.deviceId, forHTTPHeaderField: "Pulse-Device-Id")
+        // WHICH binary is asking. The runtime version does not answer that on iOS: it is
+        // MARKETING_VERSION, which stays put across re-submissions, so one runtime version can be
+        // several builds. Where bundles are wrapped for integrity each build holds its own key, and
+        // a bundle wrapped for another one cannot be opened — the app does not degrade, it stops
+        // starting. CFBundleVersion is the number that does move, so the server can keep a bundle
+        // prepared for one build away from the others. A server that does not know the header
+        // ignores it, and a release not tied to a build is still served to everyone.
+        if let build = Bundle.main.infoDictionary?["CFBundleVersion"] as? String, !build.isEmpty {
+            request.setValue(build, forHTTPHeaderField: "Pulse-Native-Build")
+        }
 
         if let channel = config.channel {
             request.setValue(channel, forHTTPHeaderField: "X-Pulse-Channel-Name")

package/lib/commonjs/links.js

@@ -7,6 +7,7 @@ exports.createDeferredLinkClient = void 0;
 exports.createPulseLinkClient = createPulseLinkClient;
 exports.extractDeferredHandoffToken = extractDeferredHandoffToken;
 exports.isOpaqueDeferredLinkToken = isOpaqueDeferredLinkToken;
+exports.normalizeAccountEmail = normalizeAccountEmail;
 exports.normalizeAndroidInstallReferrerResult = normalizeAndroidInstallReferrerResult;
 exports.normalizeDeferredHandoffToken = normalizeDeferredHandoffToken;
 /**
@@ -195,6 +196,11 @@ function createPulseLinkClient(options) {
   let accountRetryAt = 0;
   let accountAttempts = 0;
   let deterministicEpoch = 0;
+  // Invalidates every host callback that crossed an await when this client is reset/disposed.
+  // This is deliberately separate from deterministicEpoch: captures during a committed callback
+  // have intentional last-touch semantics, whereas a lifecycle boundary must forbid every stale
+  // state write, retry and outcome from the old instance.
+  let lifecycleGeneration = 0;
   // Host navigation is irreversible once any routing callback has started: it may perform its
   // side effect synchronously before returning a Promise. Serialize captures against that commit
   // boundary and keep the newer accepted token durable for the next client lifecycle instead of
@@ -413,6 +419,9 @@ function createPulseLinkClient(options) {
     return acknowledgeTerminalDelivery(tombstone);
   };
   const completeFirstOpen = (status, outcome) => {
+    const completionLifecycleGeneration = lifecycleGeneration;
+    const completionDeterministicEpoch = deterministicEpoch;
+    const completionIsCurrent = () => !disposed && lifecycleGeneration === completionLifecycleGeneration && deterministicEpoch === completionDeterministicEpoch;
     let shouldQueue = Boolean(options.onFirstOpenResult);
     if (shouldQueue && options.shouldQueueFirstOpenResult) {
       try {
@@ -421,6 +430,9 @@ function createPulseLinkClient(options) {
         shouldQueue = false;
         reportError(error);
       }
+      // Privacy/diagnostic hooks are host code and may synchronously reset, dispose, or capture a
+      // deterministic destination. Never resurrect the terminal first-open state they invalidated.
+      if (!completionIsCurrent()) return;
     }
     if (!shouldQueue) {
       state = {
@@ -464,8 +476,10 @@ function createPulseLinkClient(options) {
     void flushTerminalDelivery();
   };
   const blockFirstOpenForDeterministic = () => {
+    const blockingLifecycleGeneration = lifecycleGeneration;
     deterministicEpoch += 1;
-    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return;
+    const blockingDeterministicEpoch = deterministicEpoch;
+    if (state.firstOpen.completed && state.firstOpen.nextRetryAt === 0) return true;
     state = {
       ...state,
       firstOpen: {
@@ -475,14 +489,23 @@ function createPulseLinkClient(options) {
       }
     };
     persistAndNotify();
+    return !disposed && lifecycleGeneration === blockingLifecycleGeneration && deterministicEpoch === blockingDeterministicEpoch;
   };
-  const isAccountReady = () => {
+  const readAccountReadiness = () => {
+    const readinessLifecycleGeneration = lifecycleGeneration;
+    const readinessDeterministicEpoch = deterministicEpoch;
+    let ready = false;
     try {
-      return options.isAccountReady?.() ?? false;
+      ready = options.isAccountReady?.() ?? false;
     } catch (error) {
       reportError(error);
-      return false;
     }
+    return {
+      ready,
+      // Readiness is host code, not a pure getter. A reset/dispose/capture inside it invalidates
+      // the caller's snapshot and must be observed before any waiting/retry/application write.
+      current: !disposed && lifecycleGeneration === readinessLifecycleGeneration && deterministicEpoch === readinessDeterministicEpoch
+    };
   };
   const schedulePendingRetry = () => {
     const pending = state.pending;
@@ -690,7 +713,9 @@ function createPulseLinkClient(options) {
         if (!sourceToken || state.pending?.token === sourceToken) clearPendingAsTerminal();
         return false;
       }
-      if (!isAccountReady()) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) return false;
+      if (!accountReadiness.ready) {
         patchState({
           status: 'waiting_for_account'
         });
@@ -712,13 +737,23 @@ function createPulseLinkClient(options) {
     let applicationFailed = false;
     let applicationError;
     const applicationEpoch = deterministicEpoch;
+    const applicationLifecycleGeneration = lifecycleGeneration;
+    const lifecycleIsCurrent = () => !disposed && lifecycleGeneration === applicationLifecycleGeneration;
     const hasNewerPendingIntent = () => deterministicEpoch !== applicationEpoch && state.pending !== null
     // A provenance upgrade or rejected lower-priority capture for the token already being
     // applied does not represent another destination and must not leave that token pending.
     && (sourceToken === null || state.pending.token !== sourceToken);
     routingApplicationInFlight = true;
     emitOutcome(link, 'app_open_confirmed');
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
     emitOutcome(link, 'deferred_link_resolved');
+    if (!lifecycleIsCurrent()) {
+      routingApplicationInFlight = false;
+      return false;
+    }
     // `emitOutcome` invokes host diagnostics synchronously. If those hooks re-enter capture with
     // a newer accepted destination, it still arrived before the routing callback and must win.
     if (hasNewerPendingIntent()) {
@@ -741,10 +776,19 @@ function createPulseLinkClient(options) {
     } finally {
       routingApplicationInFlight = false;
     }
+
+    // The callback may resolve after reset/dispose and after another client has already committed
+    // a newer journey into the same storage. The old instance must not schedule a retry, rewrite
+    // state, or emit action_applied regardless of whether the callback returned true/false/threw.
+    if (!lifecycleIsCurrent()) return false;
     const newerIntentArrivedDuringApplication = hasNewerPendingIntent();
     if (applicationFailed) {
       reportError(applicationError);
-      if (newerIntentArrivedDuringApplication) {
+      if (!lifecycleIsCurrent()) return false;
+      // onError is host code too: it may capture a newer deterministic destination while reporting
+      // this failure. Re-evaluate after the callback instead of arming a stale retry from the value
+      // observed before diagnostics ran.
+      if (hasNewerPendingIntent()) {
         // The current action did not commit. Resume the newer accepted intent that was captured
         // while its callback was suspended, without scheduling a retry for the superseded one.
         void process();
@@ -779,11 +823,13 @@ function createPulseLinkClient(options) {
       appliedIds
     };
     persistAndNotify();
+    if (!lifecycleIsCurrent()) return false;
     if (link.matchBasis === 'account_bound') {
       accountAttempts = 0;
       accountRetryAt = 0;
     }
     emitOutcome(link, 'action_applied');
+    if (!lifecycleIsCurrent()) return false;
     if (stillPending && state.pending?.token !== deterministicTokenDeferredAfterCommittedJourney) {
       void process();
     }
@@ -836,11 +882,13 @@ function createPulseLinkClient(options) {
         return;
       }
       const token = pending.token;
+      const pendingLifecycleGeneration = lifecycleGeneration;
       patchState({
         status: 'resolving'
       });
+      if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
       const publicResult = await resolvePublic(token, pending.matchBasis);
-      if (disposed || state.pending?.token !== token) return;
+      if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
       if (publicResult.kind === 'resolved') {
         await applyResolved(publicResult.link, token);
         return;
@@ -849,7 +897,15 @@ function createPulseLinkClient(options) {
         schedulePendingRetry();
         return;
       }
-      if (!options.accountBridge || !isAccountReady()) {
+      if (!options.accountBridge) {
+        patchState({
+          status: 'waiting_for_account'
+        });
+        return;
+      }
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current || disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
+      if (!accountReadiness.ready) {
         patchState({
           status: 'waiting_for_account'
         });
@@ -857,7 +913,7 @@ function createPulseLinkClient(options) {
       }
       try {
         const raw = await withPromiseTimeout(() => options.accountBridge.claim(token), requestTimeoutMs, 'account claim');
-        if (disposed || state.pending?.token !== token) return;
+        if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
         const normalizedClaim = normalizeResolved(raw, token, 'account_bound', allowedActions, now());
         const claimed = normalizedClaim ? {
           ...normalizedClaim,
@@ -866,23 +922,28 @@ function createPulseLinkClient(options) {
           confidence: 1
         } : null;
         if (claimed) {
-          blockFirstOpenForDeterministic();
+          if (!blockFirstOpenForDeterministic()) return;
           await applyResolved(claimed, token);
         } else clearPendingAsTerminal();
       } catch (error) {
+        if (disposed || lifecycleGeneration !== pendingLifecycleGeneration || state.pending?.token !== token) return;
         reportError(error);
-        if (state.pending?.token === token) schedulePendingRetry();
+        if (!disposed && lifecycleGeneration === pendingLifecycleGeneration && state.pending?.token === token) schedulePendingRetry();
       }
       return;
     }
-    if (!options.accountBridge || !isAccountReady() || accountRetryAt > now()) return;
+    if (!options.accountBridge) return;
+    const accountReadiness = readAccountReadiness();
+    if (!accountReadiness.current || state.pending) return;
+    if (!accountReadiness.ready || accountRetryAt > now()) return;
     const accountPendingEpoch = deterministicEpoch;
+    const accountPendingLifecycleGeneration = lifecycleGeneration;
     try {
       const raw = await withPromiseTimeout(() => options.accountBridge.pending(), requestTimeoutMs, 'account pending');
       // A URL/paste/referrer captured while the account lookup was in flight is newer explicit
       // user intent. Ignore the stale bridge response and let the requested drain resolve the
       // captured token; otherwise both deterministic destinations could be applied.
-      if (disposed || deterministicEpoch !== accountPendingEpoch || state.pending) return;
+      if (disposed || lifecycleGeneration !== accountPendingLifecycleGeneration || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       if (!raw) {
         accountAttempts = 0;
         accountRetryAt = 0;
@@ -905,7 +966,7 @@ function createPulseLinkClient(options) {
         // Reserve the first-open journey for deterministic recovery before invoking any host
         // callback. This also covers an already-applied account item restored from older SDK
         // state, which must still prevent a second probabilistic destination.
-        blockFirstOpenForDeterministic();
+        if (!blockFirstOpenForDeterministic()) return;
         if (!state.appliedIds.includes(pendingLink.id)) {
           await applyResolved(pendingLink, null);
         } else if (state.status !== 'applied') {
@@ -915,8 +976,9 @@ function createPulseLinkClient(options) {
         }
       }
     } catch (error) {
-      if (disposed || deterministicEpoch !== accountPendingEpoch || state.pending) return;
+      if (disposed || lifecycleGeneration !== accountPendingLifecycleGeneration || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       reportError(error);
+      if (disposed || lifecycleGeneration !== accountPendingLifecycleGeneration || deterministicEpoch !== accountPendingEpoch || state.pending) return;
       // No token was consumed; the authenticated server outbox remains authoritative.
       scheduleAccountRetry();
     }
@@ -1019,7 +1081,14 @@ function createPulseLinkClient(options) {
     lastFirstOpenContext = context;
     if (state.pending) return 'deterministic_pending';
     if (state.firstOpen.completed) return 'already_completed';
-    if (state.firstOpen.nextRetryAt > now()) return 'backoff';
+    if (state.firstOpen.nextRetryAt > now()) {
+      // On a fresh client lifecycle scheduleWake() ran before the host supplied this ephemeral
+      // context, so the persisted first-open deadline could not be part of its candidates. Re-arm
+      // now that retrying is possible; otherwise a 503 followed by process death remains asleep
+      // until some unrelated foreground/manual call invokes matchFirstOpen again.
+      scheduleWake();
+      return 'backoff';
+    }
     if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
 
     // The client starts account recovery at construction. Join that deterministic rail before
@@ -1028,13 +1097,20 @@ function createPulseLinkClient(options) {
     await process();
     if (disposed) return 'ineligible';
     if (state.pending || state.firstOpen.completed) return 'deterministic_pending';
-    if (options.accountBridge && isAccountReady() && accountRetryAt > now()) {
-      if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
-      return 'retry_scheduled';
+    if (options.accountBridge) {
+      const accountReadiness = readAccountReadiness();
+      if (!accountReadiness.current) {
+        return disposed ? 'ineligible' : 'deterministic_pending';
+      }
+      if (accountReadiness.ready && accountRetryAt > now()) {
+        if (state.firstOpen.nextRetryAt === 0) scheduleFirstOpenRetry();
+        return 'retry_scheduled';
+      }
     }
     if (!isEligibleFirstOpen(context, now(), recentInstallMaxAgeMs)) return 'ineligible';
     const installAttemptId = state.firstOpen.installAttemptId ?? makeInstallAttemptId(options.randomUUID);
     const startingDeterministicEpoch = deterministicEpoch;
+    const startingLifecycleGeneration = lifecycleGeneration;
     state = {
       ...state,
       status: 'resolving',
@@ -1044,14 +1120,44 @@ function createPulseLinkClient(options) {
         attemptedAt: now()
       }
     };
-    persistAndNotify();
+    const firstOpenReservationPersisted = persistAndNotify();
+    // Persistence notifies host state hooks synchronously. They may reset/dispose this client or
+    // capture a deterministic destination. In all three cases the reserved id no longer belongs to
+    // the current lifecycle and must never cross the network boundary.
+    if (disposed) return 'ineligible';
+    if (lifecycleGeneration !== startingLifecycleGeneration || deterministicEpoch !== startingDeterministicEpoch || state.pending || state.firstOpen.completed) return 'deterministic_pending';
+    if (options.storage && !firstOpenReservationPersisted) {
+      // An unpersisted id must never leave the process: after a crash the retry would mint a new
+      // id and the server could count/route the same install twice. Keep the exact nonce in memory,
+      // arm a persistence retry without incrementing matcher attempts, and send nothing until a
+      // synchronous durable write succeeds. Memory-only clients have no restart contract and may
+      // continue normally.
+      state = {
+        ...state,
+        status: 'retryable_error',
+        firstOpen: {
+          ...state.firstOpen,
+          nextRetryAt: now() + retryBaseMs
+        }
+      };
+      reportError(new Error('Pulse Links: first-open install attempt id was not durably persisted'));
+      notifyState();
+      return 'retry_scheduled';
+    }
+    const accountEmail = options.sendAccountEmailOnFirstOpen === true ? normalizeAccountEmail(context.accountEmail) : null;
     const body = {
       appBundleId: context.appBundleId.trim(),
       platform: 'ios',
       locale: normalizeLocale(context.locale),
       firstOpen: true,
       installAttemptId,
-      ...normalizeAnonymousFirstOpenSignals(context)
+      ...normalizeAnonymousFirstOpenSignals(context),
+      // Sent only when the app already knows it. The resolver treats an address that matches
+      // exactly one recent message as proof of origin; anything else falls back to the
+      // probabilistic path, so a shared or unknown address costs nothing.
+      ...(accountEmail ? {
+        accountEmail
+      } : {})
     };
     try {
       const response = await withTimeout(fetcher, matchUrlOf(resolverBaseUrl), {
@@ -1177,6 +1283,8 @@ function createPulseLinkClient(options) {
     return owned;
   };
   const captureAndroidInstallReferrer = async bridge => {
+    const referrerLifecycleGeneration = lifecycleGeneration;
+    const referrerDeterministicEpoch = deterministicEpoch;
     let raw;
     try {
       raw = await bridge.getDeferredHandoff();
@@ -1189,6 +1297,7 @@ function createPulseLinkClient(options) {
       };
     }
     const result = normalizeAndroidInstallReferrerResult(raw);
+    if (disposed || lifecycleGeneration !== referrerLifecycleGeneration || deterministicEpoch !== referrerDeterministicEpoch) return result;
     if (result.status === 'OK' && result.token) {
       capture(result.token, 'android_install_referrer');
     }
@@ -1245,6 +1354,7 @@ function createPulseLinkClient(options) {
     dispose: () => {
       if (disposed) return;
       disposed = true;
+      lifecycleGeneration += 1;
       deterministicEpoch += 1;
       terminalDeliveryGeneration += 1;
       if (retryTimer) clearTimeout(retryTimer);
@@ -1256,6 +1366,7 @@ function createPulseLinkClient(options) {
     reset: () => {
       accountRetryAt = 0;
       accountAttempts = 0;
+      lifecycleGeneration += 1;
       deterministicEpoch += 1;
       terminalDeliveryGeneration += 1;
       terminalDeliverySending = null;
@@ -1456,6 +1567,20 @@ function resolverOutcomeRetryDelay(eventId, attempts, retryBaseMs, retryMaxMs) {
   const jitter = 0.5 + hash / 0xffffffff * 0.5;
   return Math.max(1, Math.floor(ceiling * jitter));
 }
+
+/**
+ * An address is only useful to the resolver if it is the same shape the send was recorded with.
+ * Anything that is not plausibly an address is dropped rather than sent: a malformed value can
+ * only ever fail to match, and not sending it keeps the payload free of stray user input.
+ */
+function normalizeAccountEmail(raw) {
+  const value = (raw ?? '').trim().toLowerCase();
+  if (value.length < 3 || value.length > 255) return null;
+  const at = value.indexOf('@');
+  if (at <= 0 || at !== value.lastIndexOf('@') || at === value.length - 1) return null;
+  if (/\s/.test(value)) return null;
+  return value;
+}
 async function withTimeout(fetcher, input, init, timeoutMs) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);