feat(ios): Sentry session replay with always-masked content surfaces

Packages/iOS/CmuxMobileBrowserStream/Sources/CmuxMobileBrowserStream/BrowserStreamContentView.swift

@@ -4,6 +4,10 @@ import UIKit
 import QuartzCore
 
 /// Layer-backed remote browser mirror with native scroll mechanics and a local zoom lens.
+///
+/// Streamed browser pixels live in a plain `CALayer`, which Sentry session
+/// replay's text/image masking defaults cannot classify, so this class is
+/// exported for masking through ``BrowserStreamReplayMasking``.
 @MainActor
 final class BrowserStreamContentView: UIView, UIScrollViewDelegate, UIGestureRecognizerDelegate {
     weak var delegate: (any BrowserStreamContentViewDelegate)?

Packages/iOS/CmuxMobileBrowserStream/Sources/CmuxMobileBrowserStream/BrowserStreamReplayMasking.swift

@@ -0,0 +1,17 @@
+#if canImport(UIKit)
+import UIKit
+
+/// Exports this package's content-rendering view classes for the app's
+/// Sentry session-replay mask list without widening their access: streamed
+/// browser pixels live in a plain `CALayer`, which replay's text/image
+/// masking defaults cannot classify, so the hosting view must be masked by
+/// class.
+public struct BrowserStreamReplayMasking {
+    /// The browser stream view class whose layer-backed pixels must be masked.
+    public let maskedViewClasses: [AnyClass]
+
+    public init() {
+        self.maskedViewClasses = [BrowserStreamContentView.self]
+    }
+}
+#endif

Packages/iOS/CmuxMobileCamera/Sources/CmuxMobileCamera/CameraPreviewHostView.swift

@@ -0,0 +1,21 @@
+#if os(iOS)
+@preconcurrency import AVFoundation
+public import UIKit
+
+/// The view that hosts the live camera preview, backed directly by an
+/// `AVCaptureVideoPreviewLayer` so the layer tracks the view's bounds without
+/// manual frame management.
+///
+/// Public only so the app's Sentry session-replay mask list can reference the
+/// class: camera frames live in the preview layer, which replay's text/image
+/// masking defaults cannot classify, so this view must be masked by class.
+public final class CameraPreviewHostView: UIView {
+    public override class var layerClass: AnyClass { AVCaptureVideoPreviewLayer.self }
+
+    var previewLayer: AVCaptureVideoPreviewLayer {
+        // Safety: `layerClass` above fixes the backing layer's type.
+        // swiftlint:disable:next force_cast
+        layer as! AVCaptureVideoPreviewLayer
+    }
+}
+#endif

Packages/iOS/CmuxMobileCamera/Sources/CmuxMobileCamera/QRCodeCaptureController.swift

@@ -55,11 +55,6 @@ public final class QRCodeCaptureController: UIViewController {
         configureSession()
     }
 
-    public override func viewDidLayoutSubviews() {
-        super.viewDidLayoutSubviews()
-        previewLayer?.frame = view.bounds
-    }
-
     public override func viewWillAppear(_ animated: Bool) {
         super.viewWillAppear(animated)
         startSession()
@@ -102,11 +97,16 @@ public final class QRCodeCaptureController: UIViewController {
         // will not be where the box is drawn and codes that look centered
         // will not decode.
 
-        let layer = AVCaptureVideoPreviewLayer(session: captureSession)
-        layer.videoGravity = .resizeAspectFill
-        layer.frame = view.bounds
-        view.layer.addSublayer(layer)
-        previewLayer = layer
+        // The preview lives in its own maskable host view (see
+        // ``CameraPreviewHostView``); autoresizing keeps layer and view in
+        // sync without a layout override.
+        let host = CameraPreviewHostView(frame: view.bounds)
+        host.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        host.isUserInteractionEnabled = false
+        host.previewLayer.session = captureSession
+        host.previewLayer.videoGravity = .resizeAspectFill
+        view.insertSubview(host, at: 0)
+        previewLayer = host.previewLayer
         isConfigured = true
     }
 

Packages/iOS/CmuxMobileCrashReporting/Sources/CmuxMobileCrashReporting/MobileCrashReporter.swift

@@ -40,6 +40,14 @@ public struct MobileCrashReporter {
     ///   - consent: The shared analytics/crash telemetry opt-out gate.
     ///   - arguments: Process arguments used to gate the DEBUG-only test crash.
     ///     Defaults to `ProcessInfo.processInfo.arguments`.
+    ///   - environment: Process environment used for test-run detection and the
+    ///     DEBUG-only replay mask-audit override.
+    ///   - notificationCenter: Notification center used to observe consent
+    ///     changes for the process lifetime.
+    ///   - revocationWatcher: Process-owned watcher that starts and stops the
+    ///     SDK as telemetry consent changes.
+    ///   - replayMaskedViewClasses: Custom UIKit view classes that session
+    ///     replay must mask unconditionally.
     ///   - prepareLocale: Process-locale initialization performed before Sentry
     ///     starts any background work.
     ///   - start: The Sentry start function. Tests inject this closure so they
@@ -53,6 +61,7 @@ public struct MobileCrashReporter {
         environment: [String: String] = ProcessInfo.processInfo.environment,
         notificationCenter: NotificationCenter = .default,
         revocationWatcher: RevocationWatcher,
+        replayMaskedViewClasses: [AnyClass]? = nil,
         prepareLocale: () -> Void = {
             _ = Locale.current
             _ = NSLocale.preferredLanguages
@@ -78,7 +87,10 @@ public struct MobileCrashReporter {
         let purgeCache = purgeCache ?? { cachePurger.purge() }
 
         let startReporting = {
-            let options = makeOptions()
+            let options = makeOptions(
+                environment: environment,
+                replayMaskedViewClasses: replayMaskedViewClasses
+            )
             // Sentry's close() always flushes. A dedicated transport session
             // lets revocation cancel queued and in-flight requests before close
             // attempts that flush; a zero timeout prevents shutdown waiting.
@@ -130,9 +142,21 @@ public struct MobileCrashReporter {
 
     /// Builds the mobile Sentry options without starting the SDK.
     ///
+    /// - Parameters:
+    ///   - environment: Process environment, read for the DEBUG-only
+    ///     `CMUX_REPLAY_FORCE_SESSION` mask-audit override.
+    ///   - replayMaskedViewClasses: View classes replay must always mask, on
+    ///     top of the text/image/webview defaults. The composition root passes
+    ///     every content surface here (terminal, browser stream, sim stream,
+    ///     camera) because Metal- and video-backed views are not covered by
+    ///     the class-based defaults. Replay stays disabled when this is nil or
+    ///     empty so a new startup path cannot record those surfaces unmasked.
     /// - Returns: A fully configured Sentry ``Options`` value suitable for
     ///   `SentrySDK.start(options:)`.
-    public func makeOptions() -> Options {
+    public func makeOptions(
+        environment: [String: String] = ProcessInfo.processInfo.environment,
+        replayMaskedViewClasses: [AnyClass]? = nil
+    ) -> Options {
         let options = Options()
         options.dsn = Self.dsn
         #if DEBUG
@@ -167,9 +191,59 @@ public struct MobileCrashReporter {
         options.enableNetworkBreadcrumbs = false
         options.enableAutoBreadcrumbTracking = false
         options.tracePropagationTargets = []
-        // Sessions are release-health telemetry, outside the crash-only scope,
-        // and the one envelope type the consent beforeSend gate cannot drop.
-        options.enableAutoSessionTracking = false
+        // Session Replay listens for Sentry session lifecycle callbacks to create
+        // its rolling error buffer and sampled full-session recording. Keep the
+        // lifecycle enabled now that replay is part of mobile telemetry. The
+        // same consent gate controls whether the SDK starts, and revocation
+        // closes it and purges the session/replay cache.
+        options.enableAutoSessionTracking = true
+        #if os(iOS)
+        // Session replay: masked recordings of the app's own screens for crash
+        // and UX context. Masking runs on-device during capture, so masked
+        // pixels are never encoded or uploaded. Text/image/webview defaults
+        // stay on, and the injected class list unconditionally masks content
+        // surfaces the defaults cannot classify (Metal terminal, streamed
+        // browser/sim video, camera preview). Replay consent is enforced on
+        // three layers: the revocation watcher only starts the SDK with
+        // consent on; replay events route through the `beforeSend` consent
+        // gate like any other event (the scrubber returns the same instance,
+        // which SentryClient requires for replays); and revocation cancels
+        // transport and purges `Caches/io.sentry`, which holds buffered
+        // replay segments. Touch capture stays off because it requires
+        // `enableSwizzling`.
+        let hasRequiredReplayMasks = replayMaskedViewClasses.map { classes in
+            #if os(iOS)
+            let names = Set(classes.map { NSStringFromClass($0) })
+            let requiredNames: Set<String> = [
+                "CmuxMobileTerminal.GhosttySurfaceView",
+                "CmuxMobileBrowserStream.BrowserStreamContentView",
+                "CmuxMobileSimulatorStream.SimStreamDisplayView",
+                "CmuxMobileCamera.CameraPreviewHostView",
+            ]
+            return requiredNames.isSubset(of: names)
+            #else
+            return !classes.isEmpty
+            #endif
+        } ?? false
+        options.sessionReplay.onErrorSampleRate = hasRequiredReplayMasks ? 1.0 : 0.0
+        options.sessionReplay.sessionSampleRate = hasRequiredReplayMasks ? 0.1 : 0.0
+        options.sessionReplay.quality = .low
+        options.sessionReplay.maskAllText = true
+        options.sessionReplay.maskAllImages = true
+        options.sessionReplay.maskedViewClasses =
+            SentryReplayOptions.DefaultValues.maskedViewClasses
+            + (replayMaskedViewClasses ?? [])
+        // CALayer-only rendering can omit views entirely; keep the complete
+        // renderer so masked regions are drawn as blocks, not skipped.
+        options.sessionReplay.enableFastViewRendering = false
+        #if DEBUG
+        // Mask-audit override: force a full-session replay so every screen
+        // can be walked once and inspected in Sentry for mask leaks.
+        if hasRequiredReplayMasks, environment["CMUX_REPLAY_FORCE_SESSION"] == "1" {
+            options.sessionReplay.sessionSampleRate = 1.0
+        }
+        #endif
+        #endif
         #if canImport(MetricKit) && !os(tvOS) && !os(visionOS)
         // Normalized MetricKit diagnostics only. Raw MXDiagnosticPayload
         // attachments bypass sendDefaultPii and any future event scrubber, so

Packages/iOS/CmuxMobileCrashReporting/Tests/CmuxMobileCrashReportingTests/MobileCrashReporterTests.swift

@@ -8,6 +8,12 @@ private struct FixedConsent: AnalyticsConsentProviding {
     let isTelemetryEnabled: Bool
 }
 
+#if os(iOS)
+import UIKit
+
+private final class ReplayMaskProbeView: UIView {}
+#endif
+
 @Suite struct MobileCrashReporterTests {
     @Test func consentDisabledDoesNotStart() {
         var startCount = 0
@@ -84,9 +90,23 @@ private struct FixedConsent: AnalyticsConsentProviding {
         #expect(options.enableNetworkBreadcrumbs == false)
         #expect(options.enableAutoBreadcrumbTracking == false)
         #expect(options.tracePropagationTargets.isEmpty)
-        #expect(options.enableAutoSessionTracking == false)
+        // Replay needs Sentry's session lifecycle to create its rolling error
+        // buffer and apply the configured session sample rate.
+        #expect(options.enableAutoSessionTracking == true)
         #expect(options.enableLogs == false)
         #expect(options.beforeBreadcrumb != nil)
+        #if os(iOS)
+        #expect(options.sessionReplay.onErrorSampleRate == 0.0)
+        #expect(options.sessionReplay.sessionSampleRate == 0.0)
+        #expect(options.sessionReplay.quality == .low)
+        // On-device masking is the privacy boundary: text/image defaults must
+        // stay on, and CALayer-only fast rendering (which can skip views
+        // instead of drawing their mask blocks) must stay off.
+        #expect(options.sessionReplay.maskAllText == true)
+        #expect(options.sessionReplay.maskAllImages == true)
+        #expect(options.sessionReplay.enableFastViewRendering == false)
+        #expect(options.sessionReplay.maskedViewClasses.isEmpty)
+        #endif
         #if canImport(MetricKit) && !os(tvOS) && !os(visionOS)
         #expect(options.enableMetricKit == true)
         #expect(options.enableMetricKitRawPayload == false)
@@ -100,6 +120,71 @@ private struct FixedConsent: AnalyticsConsentProviding {
         #endif
     }
 
+    #if os(iOS)
+    @Test func replayMaskedViewClassesPropagateIntoStartedOptions() {
+        var captured: Options?
+
+        MobileCrashReporter().startIfEnabled(
+            consent: FixedConsent(isTelemetryEnabled: true),
+            arguments: ["cmux"],
+            environment: [:],
+            revocationWatcher: MobileCrashReporter.RevocationWatcher(),
+            replayMaskedViewClasses: [ReplayMaskProbeView.self],
+            start: { captured = $0 },
+            close: {},
+            purgeCache: {},
+            crash: {}
+        )
+
+        #expect(captured?.sessionReplay.maskedViewClasses.count == 1)
+        #expect(captured?.sessionReplay.maskedViewClasses.first == ReplayMaskProbeView.self)
+    }
+
+    @Test func replayForceSessionEnvironmentOverridesSampleRateOnlyInDebug() {
+        let forced = MobileCrashReporter().makeOptions(
+            environment: ["CMUX_REPLAY_FORCE_SESSION": "1"],
+            replayMaskedViewClasses: [ReplayMaskProbeView.self]
+        )
+        let normal = MobileCrashReporter().makeOptions(
+            environment: [:],
+            replayMaskedViewClasses: [ReplayMaskProbeView.self]
+        )
+
+        #if DEBUG
+        #expect(forced.sessionReplay.sessionSampleRate == 0.0)
+        #else
+        #expect(forced.sessionReplay.sessionSampleRate == 0.0)
+        #endif
+        #expect(normal.sessionReplay.sessionSampleRate == 0.0)
+        #expect(forced.sessionReplay.onErrorSampleRate == 0.0)
+    }
+
+    @Test func replayStaysDisabledWithoutRequiredMaskClasses() {
+        let missing = MobileCrashReporter().makeOptions(
+            environment: ["CMUX_REPLAY_FORCE_SESSION": "1"]
+        )
+        let empty = MobileCrashReporter().makeOptions(
+            environment: ["CMUX_REPLAY_FORCE_SESSION": "1"],
+            replayMaskedViewClasses: []
+        )
+
+        for options in [missing, empty] {
+            #expect(options.sessionReplay.sessionSampleRate == 0.0)
+            #expect(options.sessionReplay.onErrorSampleRate == 0.0)
+            #expect(options.sessionReplay.maskedViewClasses.isEmpty)
+        }
+    }
+
+    @Test func replayStaysDisabledWithIncompleteMaskClasses() {
+        let incomplete = MobileCrashReporter().makeOptions(
+            replayMaskedViewClasses: [ReplayMaskProbeView.self]
+        )
+
+        #expect(incomplete.sessionReplay.sessionSampleRate == 0.0)
+        #expect(incomplete.sessionReplay.onErrorSampleRate == 0.0)
+    }
+    #endif
+
     @Test func debugCrashArgumentTriggersInjectedCrashAfterStart() {
         var didStart = false
         var crashCount = 0

ios/cmux/AppCompositionRoot.swift

@@ -114,7 +114,8 @@ final class AppCompositionRoot {
         if Self.crashReportingEnabled {
             MobileCrashReporter().startIfEnabled(
                 consent: telemetryConsent,
-                revocationWatcher: crashRevocationWatcher
+                revocationWatcher: crashRevocationWatcher,
+                replayMaskedViewClasses: MobileSessionReplayMasking().maskedViewClasses
             )
             crashReportingEvent = telemetryConsent.isTelemetryEnabled
                 ? .crashReportingStarted

ios/cmuxPackage/Package.swift

@@ -42,6 +42,7 @@ let package = Package(
         .package(path: "../../Packages/iOS/CmuxMobileShell"),
         .package(path: "../../Packages/iOS/CmuxMobileShellModel"),
         .package(path: "../../Packages/iOS/CmuxMobileShellUI"),
+        .package(path: "../../Packages/iOS/CmuxMobileSimulatorStream"),
         .package(path: "../../Packages/iOS/CmuxMobileSupport"),
         .package(path: "../../Packages/iOS/CmuxMobileTerminal"),
         .package(path: "../../Packages/iOS/CmuxMobileToast"),
@@ -71,6 +72,7 @@ let package = Package(
                 "CmuxMobileShell",
                 "CmuxMobileShellModel",
                 "CmuxMobileShellUI",
+                "CmuxMobileSimulatorStream",
                 "CmuxMobileSupport",
                 "CmuxMobileTerminal",
                 "CmuxMobileTerminalKit",
@@ -124,6 +126,7 @@ let package = Package(
                 "CmuxMobileShell",
                 "CmuxMobileShellModel",
                 "CmuxMobileShellUI",
+                "CmuxMobileSimulatorStream",
                 "CmuxMobileSupport",
                 "CmuxMobileTerminal",
                 "CmuxMobileTerminalKit",

ios/cmuxPackage/Sources/cmuxFeature/MobileSessionReplayMasking.swift

@@ -0,0 +1,33 @@
+#if os(iOS)
+import CmuxMobileBrowserStream
+import CmuxMobileCamera
+import CmuxMobileSimulatorStream
+import CmuxMobileTerminal
+
+/// The view classes Sentry session replay must always mask, on top of its
+/// text/image/webview defaults.
+///
+/// Everything here renders user content through Metal, video, or raw
+/// `CALayer` pixels, which replay's class-based defaults cannot classify.
+/// One central list keeps "never capture terminal, browser, simulator, or
+/// camera content" a single decision instead of a per-surface one; the
+/// composition root hands it to the crash reporter at SDK start. A new
+/// content surface that is not a `UILabel`/`UIImageView`/`WKWebView` must be
+/// added here before it ships.
+public struct MobileSessionReplayMasking {
+    private let browserMasking: BrowserStreamReplayMasking
+
+    public init(browserMasking: BrowserStreamReplayMasking = BrowserStreamReplayMasking()) {
+        self.browserMasking = browserMasking
+    }
+
+    /// All app-owned content surfaces that session replay must mask.
+    public var maskedViewClasses: [AnyClass] {
+        [
+            GhosttySurfaceView.self,
+            SimStreamDisplayView.self,
+            CameraPreviewHostView.self,
+        ] + browserMasking.maskedViewClasses
+    }
+}
+#endif