@hasna/recordings 0.2.10 → 0.2.13

package/src/native/Recordings/Updater/Broker/PeerIdentity.swift

@@ -0,0 +1,274 @@
+import Darwin
+import Foundation
+import RecordingsUpdateProtocol
+import Security
+
+struct BrokerPolicy: Codable, Sendable {
+    let schemaVersion: Int
+    let signingTeamIdentifier: String
+    let allowedClientIdentifiers: [String]
+    let applicationIdentifier: String
+    let initialKeyEpoch: UInt64
+    let allowedKeyEpochs: [UInt64]
+    let lifecycle: String
+    let rootMaintenanceSupported: Bool
+    let keyRotationSupported: Bool
+
+    enum CodingKeys: String, CodingKey {
+        case schemaVersion = "schema_version"
+        case signingTeamIdentifier = "signing_team_identifier"
+        case allowedClientIdentifiers = "allowed_client_identifiers"
+        case applicationIdentifier = "application_identifier"
+        case initialKeyEpoch = "initial_key_epoch"
+        case allowedKeyEpochs = "allowed_key_epochs"
+        case lifecycle
+        case rootMaintenanceSupported = "root_maintenance_supported"
+        case keyRotationSupported = "key_rotation_supported"
+    }
+
+    func validate() throws {
+        guard schemaVersion == RecordingsUpdateConstants.protocolVersion else {
+            throw BrokerSecurityError.invalidPolicy("unsupported schema")
+        }
+        guard signingTeamIdentifier.range(of: #"^[A-Z0-9]{10}$"#, options: .regularExpression) != nil else {
+            throw BrokerSecurityError.invalidPolicy("invalid team identifier")
+        }
+        guard !allowedClientIdentifiers.isEmpty, allowedClientIdentifiers.count <= 16 else {
+            throw BrokerSecurityError.invalidPolicy("invalid client identifier list")
+        }
+        guard initialKeyEpoch > 0, allowedKeyEpochs == [initialKeyEpoch]
+        else {
+            throw BrokerSecurityError.invalidPolicy("invalid key-epoch authorization")
+        }
+        guard lifecycle == RecordingsUpdateConstants.lifecycle,
+              rootMaintenanceSupported == RecordingsUpdateConstants.rootMaintenanceSupported,
+              keyRotationSupported == RecordingsUpdateConstants.keyRotationSupported
+        else {
+            throw BrokerSecurityError.invalidPolicy("unsupported updater lifecycle")
+        }
+        for identifier in allowedClientIdentifiers + [applicationIdentifier] {
+            guard identifier.range(of: #"^[A-Za-z0-9][A-Za-z0-9.-]{1,254}$"#, options: .regularExpression) != nil else {
+                throw BrokerSecurityError.invalidPolicy("invalid bundle identifier")
+            }
+        }
+    }
+}
+
+struct AuthenticatedPeer: Sendable {
+    let effectiveUserID: uid_t
+    let processIdentifier: pid_t
+    let signingIdentifier: String
+    let signingTeamIdentifier: String
+}
+
+enum RootTrustStore {
+    static func readPolicy() throws -> BrokerPolicy {
+        let data = try readRootOwnedRegularFile(
+            at: RecordingsUpdateConstants.policyPath,
+            maximumBytes: 64 * 1024,
+            expectedModeMask: 0o022
+        )
+        let policy: BrokerPolicy
+        do {
+            let decoder = JSONDecoder()
+            decoder.keyDecodingStrategy = .useDefaultKeys
+            policy = try decoder.decode(BrokerPolicy.self, from: data)
+        } catch {
+            throw BrokerSecurityError.invalidPolicy("malformed JSON")
+        }
+        try policy.validate()
+        return policy
+    }
+
+    static func readEnvelopePublicKey(epoch: UInt64) throws -> Data {
+        guard epoch > 0 else { throw BrokerSecurityError.invalidTrustFile }
+        let data = try readRootOwnedRegularFile(
+            at: RecordingsUpdateConstants.envelopePublicKeyDirectory + "/\(epoch).raw",
+            maximumBytes: 32,
+            expectedModeMask: 0o022
+        )
+        guard data.count == 32 else { throw BrokerSecurityError.invalidTrustFile }
+        return data
+    }
+
+    static func readBootstrapMarker() throws -> Data {
+        try readRootOwnedRegularFile(
+            at: RecordingsUpdateConstants.bootstrapMarkerPath,
+            maximumBytes: 1024 * 1024,
+            expectedModeMask: 0o022
+        )
+    }
+
+    private static func readRootOwnedRegularFile(
+        at path: String,
+        maximumBytes: Int,
+        expectedModeMask: mode_t
+    ) throws -> Data {
+        let parentDirectory = URL(fileURLWithPath: path).deletingLastPathComponent().path
+        guard DarwinACLValidator.rootOwnedDirectoryAncestryHasNoExtendedACL(
+            to: parentDirectory
+        ) else {
+            throw BrokerSecurityError.invalidTrustFile
+        }
+        let descriptor = Darwin.open(path, O_RDONLY | O_CLOEXEC | O_NOFOLLOW)
+        guard descriptor >= 0 else { throw BrokerSecurityError.invalidTrustFile }
+        defer { Darwin.close(descriptor) }
+
+        var metadata = stat()
+        guard fstat(descriptor, &metadata) == 0,
+              (metadata.st_mode & S_IFMT) == S_IFREG,
+              metadata.st_uid == 0,
+              (metadata.st_mode & expectedModeMask) == 0,
+              DarwinACLValidator.descriptorHasNoExtendedACL(descriptor),
+              metadata.st_size > 0,
+              metadata.st_size <= maximumBytes
+        else {
+            throw BrokerSecurityError.invalidTrustFile
+        }
+
+        var result = Data()
+        result.reserveCapacity(Int(metadata.st_size))
+        var offset: off_t = 0
+        var buffer = [UInt8](repeating: 0, count: min(16 * 1024, maximumBytes + 1))
+        while offset < metadata.st_size {
+            let requested = min(buffer.count, Int(metadata.st_size - offset))
+            let count = buffer.withUnsafeMutableBytes {
+                pread(descriptor, $0.baseAddress, requested, offset)
+            }
+            guard count > 0 else { throw BrokerSecurityError.invalidTrustFile }
+            result.append(contentsOf: buffer.prefix(count))
+            offset += off_t(count)
+        }
+        var trailingByte: UInt8 = 0
+        guard pread(descriptor, &trailingByte, 1, offset) == 0,
+              DarwinACLValidator.descriptorHasNoExtendedACL(descriptor)
+        else {
+            throw BrokerSecurityError.invalidTrustFile
+        }
+        return result
+    }
+}
+
+struct PeerIdentityPolicy {
+    let policy: BrokerPolicy
+
+    func authenticate(_ connection: NSXPCConnection) throws -> AuthenticatedPeer {
+        var token = connection.auditToken
+        let tokenData = withUnsafeBytes(of: &token) { Data($0) }
+        let attributes = [kSecGuestAttributeAudit as String: tokenData] as CFDictionary
+        var guest: SecCode?
+        let guestStatus = SecCodeCopyGuestWithAttributes(nil, attributes, [], &guest)
+        guard guestStatus == errSecSuccess, let guest else {
+            throw BrokerSecurityError.peerCodeUnavailable(guestStatus)
+        }
+
+        let identifiers = policy.allowedClientIdentifiers
+            .map { "identifier \(Self.requirementQuoted($0))" }
+            .joined(separator: " or ")
+        let requirementText = """
+        anchor apple generic and
+        certificate leaf[field.1.2.840.113635.100.6.1.13] exists and
+        certificate 1[field.1.2.840.113635.100.6.2.6] exists and
+        certificate leaf[subject.OU] = \(Self.requirementQuoted(policy.signingTeamIdentifier)) and
+        (\(identifiers))
+        """
+        var requirement: SecRequirement?
+        let requirementStatus = SecRequirementCreateWithString(
+            requirementText as CFString,
+            [],
+            &requirement
+        )
+        guard requirementStatus == errSecSuccess, let requirement else {
+            throw BrokerSecurityError.invalidPolicy("could not compile peer requirement")
+        }
+        let validationStatus = SecCodeCheckValidity(
+            guest,
+            SecCSFlags(rawValue: kSecCSStrictValidate | kSecCSCheckNestedCode),
+            requirement
+        )
+        guard validationStatus == errSecSuccess else {
+            throw BrokerSecurityError.peerRejected(validationStatus)
+        }
+
+        var signingInformation: CFDictionary?
+        let informationStatus = SecCodeCopySigningInformation(
+            guest,
+            SecCSFlags(rawValue: kSecCSSigningInformation | kSecCSRequirementInformation),
+            &signingInformation
+        )
+        guard informationStatus == errSecSuccess,
+              let information = signingInformation as? [String: Any],
+              let identifier = information[kSecCodeInfoIdentifier as String] as? String,
+              let team = information[kSecCodeInfoTeamIdentifier as String] as? String,
+              identifiersContain(identifier),
+              team == policy.signingTeamIdentifier,
+              Self.hasHardenedRuntime(information),
+              Self.hasNoDangerousDebugOrLoaderEntitlements(information)
+        else {
+            throw BrokerSecurityError.peerMetadataRejected
+        }
+
+        return AuthenticatedPeer(
+            effectiveUserID: audit_token_to_euid(token),
+            processIdentifier: audit_token_to_pid(token),
+            signingIdentifier: identifier,
+            signingTeamIdentifier: team
+        )
+    }
+
+    private func identifiersContain(_ identifier: String) -> Bool {
+        policy.allowedClientIdentifiers.contains(identifier)
+    }
+
+    private static func requirementQuoted(_ value: String) -> String {
+        "\"" + value.replacingOccurrences(of: "\\", with: "\\\\")
+            .replacingOccurrences(of: "\"", with: "\\\"") + "\""
+    }
+
+    private static func hasHardenedRuntime(_ information: [String: Any]) -> Bool {
+        guard let flags = information[kSecCodeInfoFlags as String] as? NSNumber else {
+            return false
+        }
+        return flags.uint32Value & UInt32(kSecCodeSignatureRuntime) != 0
+    }
+
+    private static func hasNoDangerousDebugOrLoaderEntitlements(
+        _ information: [String: Any]
+    ) -> Bool {
+        let entitlements: [String: Any]
+        if let values = information[kSecCodeInfoEntitlementsDict as String] as? [String: Any] {
+            entitlements = values
+        } else if information[kSecCodeInfoEntitlementsDict as String] == nil,
+                  information[kSecCodeInfoEntitlements as String] == nil {
+            entitlements = [:]
+        } else {
+            // A present but non-dictionary entitlement blob is not safely
+            // inspectable here, so dynamic-peer admission fails closed.
+            return false
+        }
+        let forbidden = [
+            "com.apple.security.get-task-allow",
+            "com.apple.security.cs.disable-library-validation",
+            "com.apple.security.cs.allow-dyld-environment-variables",
+        ]
+        return forbidden.allSatisfy { entitlements[$0] == nil }
+    }
+}
+
+enum BrokerSecurityError: Error, CustomStringConvertible {
+    case invalidPolicy(String)
+    case invalidTrustFile
+    case peerCodeUnavailable(OSStatus)
+    case peerRejected(OSStatus)
+    case peerMetadataRejected
+
+    var description: String {
+        switch self {
+        case let .invalidPolicy(reason): "Invalid root-owned broker policy: \(reason)"
+        case .invalidTrustFile: "A root-owned broker trust file is missing or unsafe"
+        case let .peerCodeUnavailable(status): "Could not resolve the XPC peer code identity (\(status))"
+        case let .peerRejected(status): "The XPC peer code identity was rejected (\(status))"
+        case .peerMetadataRejected: "The XPC peer signing metadata was rejected"
+        }
+    }
+}

package/src/native/Recordings/Updater/Broker/VerifierRunner.swift

@@ -0,0 +1,81 @@
+import Darwin
+import Foundation
+import RecordingsUpdateProtocol
+import RecordingsVerifierLauncher
+
+struct ArtifactVerifierRunner {
+    func materialize(stagedUpdate: StagedUpdate) throws -> String {
+        var verifierUserID: uid_t = 0
+        var verifierGroupID: gid_t = 0
+        let lookupStatus = RecordingsUpdateConstants.artifactVerifierAccount.withCString {
+            recordings_lookup_verifier_account($0, &verifierUserID, &verifierGroupID)
+        }
+        guard lookupStatus == 0, verifierUserID != 0, verifierGroupID != 0 else {
+            throw VerifierRunnerError.invalidVerifierAccount
+        }
+        let outputPath = stagedUpdate.directory + "/verifier-output"
+        guard mkdir(outputPath, 0o700) == 0,
+              chown(outputPath, verifierUserID, verifierGroupID) == 0
+        else {
+            throw VerifierRunnerError.couldNotCreateOutput
+        }
+        let archive = Darwin.open(stagedUpdate.archive.path, O_RDONLY | O_CLOEXEC | O_NOFOLLOW)
+        guard archive >= 0,
+              DarwinACLValidator.descriptorHasNoExtendedACL(archive)
+        else {
+            if archive >= 0 { Darwin.close(archive) }
+            throw VerifierRunnerError.invalidStagedArchive
+        }
+        defer { Darwin.close(archive) }
+        let output = Darwin.open(outputPath, O_RDONLY | O_DIRECTORY | O_CLOEXEC | O_NOFOLLOW)
+        guard output >= 0,
+              DarwinACLValidator.descriptorHasNoExtendedACL(output)
+        else {
+            if output >= 0 { Darwin.close(output) }
+            throw VerifierRunnerError.couldNotCreateOutput
+        }
+        defer { Darwin.close(output) }
+
+        let status = stagedUpdate.archive.sha256.withCString {
+            recordings_run_artifact_verifier(
+                archive,
+                output,
+                verifierUserID,
+                verifierGroupID,
+                $0
+            )
+        }
+        guard status == 0 else { throw VerifierRunnerError.verifierFailed(status) }
+        var outputMetadata = stat()
+        guard fchown(output, 0, 0) == 0,
+              fchmod(output, 0o700) == 0,
+              fstat(output, &outputMetadata) == 0,
+              (outputMetadata.st_mode & S_IFMT) == S_IFDIR,
+              outputMetadata.st_uid == 0,
+              (outputMetadata.st_mode & 0o077) == 0,
+              DarwinACLValidator.descriptorHasNoExtendedACL(output),
+              fsync(output) == 0
+        else {
+            throw VerifierRunnerError.couldNotSealOutput
+        }
+        return outputPath
+    }
+}
+
+enum VerifierRunnerError: Error, CustomStringConvertible {
+    case invalidVerifierAccount
+    case couldNotCreateOutput
+    case invalidStagedArchive
+    case verifierFailed(Int32)
+    case couldNotSealOutput
+
+    var description: String {
+        switch self {
+        case .invalidVerifierAccount: "The no-login artifact-verifier account is missing or unsafe"
+        case .couldNotCreateOutput: "Could not create protected verifier output"
+        case .invalidStagedArchive: "The protected staged package is unavailable"
+        case let .verifierFailed(status): "The sandboxed artifact verifier failed (\(status))"
+        case .couldNotSealOutput: "Could not seal verifier output for root-side validation"
+        }
+    }
+}

package/src/native/Recordings/Updater/BrokerTests/ActivationRecoveryPolicyTests.swift

@@ -0,0 +1,259 @@
+import Foundation
+import Testing
+@testable import RecordingsUpdateBroker
+
+struct ActivationRecoveryPolicyTests {
+    private let old = String(repeating: "a", count: 64)
+    private let candidate = String(repeating: "b", count: 64)
+
+    @Test("swap recovery spans rename, fsync, and phase-journal failure boundaries")
+    func swapFailureInjectionBoundaries() {
+        let beforeRename = snapshot(live: old, candidate: candidate)
+        #expect(commit(beforeRename) == .exchangeCandidateAndLive)
+
+        // renameatx_np(RENAME_SWAP) succeeded, but either directory fsync failed.
+        let afterRenameBeforeFsync = snapshot(live: candidate, candidate: old)
+        #expect(commit(afterRenameBeforeFsync) == .retainPrevious)
+
+        // Both directory fsyncs succeeded, but writing `swapped` failed. The exact
+        // namespace shape is the same and recovery retains the old tree once.
+        let afterFsyncBeforeSwappedJournal = snapshot(live: candidate, candidate: old)
+        #expect(commit(afterFsyncBeforeSwappedJournal) == .retainPrevious)
+
+        // Retaining the old app succeeded, but its fsync or `previous-retained`
+        // journal write failed. Recovery recognizes the durable terminal shape.
+        let afterRetainBeforeJournal = snapshot(live: candidate, previous: old)
+        #expect(commit(afterRetainBeforeJournal) == .ready)
+    }
+
+    @Test("rollback recovery restores the exact old digest at every swap boundary")
+    func rollbackFailureInjectionBoundaries() {
+        #expect(rollback(snapshot(live: candidate, candidate: old)) == .exchangeCandidateAndLive)
+        #expect(rollback(snapshot(live: candidate, previous: old)) == .exchangePreviousAndLive)
+
+        // The rollback exchange succeeded, but fsync failed before the candidate
+        // could be moved from the previous slot to its failed-candidate slot.
+        #expect(rollback(snapshot(live: old, previous: candidate)) == .retainFailedFromPrevious)
+
+        // Either rollback path is terminal only when the exact old digest is live
+        // and the exact candidate survives in exactly one protected slot.
+        #expect(rollback(snapshot(live: old, candidate: candidate)) == .ready)
+        #expect(rollback(snapshot(live: old, failed: candidate)) == .ready)
+        #expect(
+            rollback(snapshot(live: old, candidate: candidate, failed: candidate)) == .invalid
+        )
+        #expect(
+            rollback(snapshot(live: old, candidate: candidate, failed: old)) == .invalid
+        )
+    }
+
+    @Test("first install is exclusive and crash recoverable")
+    func firstInstallFailureInjectionBoundaries() {
+        #expect(
+            ActivationRecoveryPolicy.commitAction(
+                snapshot: snapshot(candidate: candidate),
+                previousDigest: nil,
+                candidateDigest: candidate
+            ) == .installCandidateExclusively
+        )
+        #expect(
+            ActivationRecoveryPolicy.commitAction(
+                snapshot: snapshot(live: candidate),
+                previousDigest: nil,
+                candidateDigest: candidate
+            ) == .ready
+        )
+        #expect(
+            ActivationRecoveryPolicy.commitAction(
+                snapshot: snapshot(live: old, candidate: candidate),
+                previousDigest: nil,
+                candidateDigest: candidate
+            ) == .invalid
+        )
+    }
+
+    @Test("prepared newer transaction is discarded over an older aborted barrier")
+    func preparedOverOlderAbortedBarrier() {
+        #expect(
+            ActivationRecoveryPolicy.preparedBarrierAction(
+                currentPhase: .aborted,
+                currentSequence: 7,
+                journalSequence: 8,
+                exactBinding: false,
+                sameCohort: true
+            ) == .discard
+        )
+        #expect(
+            ActivationRecoveryPolicy.preparedBarrierAction(
+                currentPhase: .aborted,
+                currentSequence: 7,
+                journalSequence: 8,
+                exactBinding: false,
+                sameCohort: false
+            ) == .invalid
+        )
+    }
+
+    @Test("rollback-started plus seen closes abort before prune across a second crash")
+    func rolledBackSeenBarrierSecondCrash() {
+        let afterRolledBackJournalBeforeAbort =
+            ActivationRecoveryPolicy.rolledBackBarrierAction(
+                currentPhase: .seen,
+                currentSequence: 8,
+                journalSequence: 8,
+                exactBinding: true,
+                sameCohort: true
+            )
+        #expect(afterRolledBackJournalBeforeAbort == .finalizeAbortThenPrune)
+
+        // If the broker crashes after persisting `rolled-back` but before the abort
+        // state write, startup obtains the same action and preserves the journal.
+        let secondStartup = ActivationRecoveryPolicy.rolledBackBarrierAction(
+            currentPhase: .seen,
+            currentSequence: 8,
+            journalSequence: 8,
+            exactBinding: true,
+            sameCohort: true
+        )
+        #expect(secondStartup == .finalizeAbortThenPrune)
+
+        let afterAbort = ActivationRecoveryPolicy.rolledBackBarrierAction(
+            currentPhase: .aborted,
+            currentSequence: 8,
+            journalSequence: 8,
+            exactBinding: true,
+            sameCohort: true
+        )
+        #expect(afterAbort == .prune)
+    }
+
+    @Test("bootstrap journal fsync before seen is safely discardable without state mutation")
+    func bootstrapAfterJournalFsyncBeforeSeen() {
+        #expect(
+            bootstrap(phase: .prepared, current: nil, exact: false, candidateMatches: false)
+                == .discardBeforeSeen
+        )
+        #expect(
+            bootstrap(phase: .aborted, current: nil, exact: false, candidateMatches: false)
+                == .prune
+        )
+    }
+
+    @Test("bootstrap seen state commits from its exact durable journal")
+    func bootstrapAfterSeenFsyncBeforeCommit() {
+        #expect(bootstrap(phase: .prepared, current: .seen) == .finalizeCommit)
+    }
+
+    @Test("a visible seen rename remains recoverable when its directory fsync failed")
+    func bootstrapStateRenameBeforeDirectoryFsync() {
+        #expect(bootstrap(phase: .prepared, current: .seen) == .finalizeCommit)
+        // If the rename is lost rather than visible after restart, no monotonic state
+        // exists and the pre-seen journal can be closed without committing anything.
+        #expect(
+            bootstrap(phase: .prepared, current: nil, exact: false, candidateMatches: false)
+                == .discardBeforeSeen
+        )
+    }
+
+    @Test("bootstrap recovery is idempotent across a second crash")
+    func bootstrapSecondCrashDuringRecovery() {
+        #expect(bootstrap(phase: .commitPending, current: .seen) == .finalizeCommit)
+        #expect(bootstrap(phase: .commitPending, current: .committed) == .validateCommitted)
+        #expect(bootstrap(phase: .committed, current: .committed) == .prune)
+    }
+
+    @Test("bootstrap recovery does not depend on replaying an expired envelope")
+    func bootstrapExpiredEnvelopeAfterCrash() {
+        // Recovery uses the root-owned journal, exact highest-seen binding, and live
+        // candidate digest; envelope wall-clock validity is intentionally not an input.
+        #expect(bootstrap(phase: .prepared, current: .seen) == .finalizeCommit)
+    }
+
+    @Test("bootstrap recovery rejects mismatched or non-absent prior state")
+    func bootstrapMismatchedJournal() {
+        #expect(bootstrap(phase: .prepared, current: .seen, exact: false) == .invalid)
+        #expect(
+            bootstrap(phase: .prepared, current: .seen, priorWasAbsent: false) == .invalid
+        )
+        #expect(
+            bootstrap(phase: .prepared, current: .seen, candidateMatches: false) == .invalid
+        )
+    }
+
+    @Test("schema-v1 activation journals without a discriminator remain activation-only")
+    func legacyActivationJournalSchemaMigration() throws {
+        let legacyJSON = Data(#"""
+        {
+          "schema_version": 1,
+          "transaction_id": "00000000-0000-0000-0000-000000000001",
+          "phase": "prepared",
+          "release_id": "00000000-0000-0000-0000-000000000002",
+          "release_sequence": 2,
+          "key_epoch": 1,
+          "envelope_payload_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+          "artifact_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+          "manifest_sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
+          "cohort_package_sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+          "candidate_tree_sha256": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+          "candidate_application_mode": 493,
+          "candidate_executable_modes": {
+            "Contents/MacOS/Recordings": 493,
+            "Contents/Helpers/recordings": 493,
+            "Contents/Helpers/recordings-update-client": 493
+          },
+          "candidate_application_path": "/Library/Application Support/Hasna/Recordings/Updates/transaction-00000000-0000-0000-0000-000000000001/candidate/Recordings.app",
+          "application_path": "/Applications/Recordings.app"
+        }
+        """#.utf8)
+        let journal = try JSONDecoder().decode(BrokerInstallJournal.self, from: legacyJSON)
+        #expect(journal.operation == nil)
+        #expect(journal.resolvedOperation == .applicationActivation)
+        #expect(journal.expectedPurpose == "update")
+    }
+
+    private func commit(_ value: ApplicationNamespaceSnapshot) -> CommitRecoveryAction {
+        ActivationRecoveryPolicy.commitAction(
+            snapshot: value,
+            previousDigest: old,
+            candidateDigest: candidate
+        )
+    }
+
+    private func rollback(_ value: ApplicationNamespaceSnapshot) -> RollbackRecoveryAction {
+        ActivationRecoveryPolicy.rollbackAction(
+            snapshot: value,
+            previousDigest: old,
+            candidateDigest: candidate
+        )
+    }
+
+    private func bootstrap(
+        phase: BootstrapJournalPhase,
+        current: MonotonicBarrierPhase?,
+        exact: Bool = true,
+        priorWasAbsent: Bool = true,
+        candidateMatches: Bool = true
+    ) -> BootstrapRecoveryAction {
+        BootstrapRecoveryPolicy.action(
+            journalPhase: phase,
+            currentPhase: current,
+            exactBinding: exact,
+            priorMonotonicStateWasAbsent: priorWasAbsent,
+            candidateMatches: candidateMatches
+        )
+    }
+
+    private func snapshot(
+        live: String? = nil,
+        candidate: String? = nil,
+        previous: String? = nil,
+        failed: String? = nil
+    ) -> ApplicationNamespaceSnapshot {
+        ApplicationNamespaceSnapshot(
+            live: live,
+            candidateSlot: candidate,
+            previousSlot: previous,
+            failedSlot: failed
+        )
+    }
+}

package/src/native/Recordings/Updater/BrokerTests/CanonicalReleaseOrderTests.swift

@@ -0,0 +1,21 @@
+import Testing
+@testable import RecordingsUpdateBroker
+
+struct CanonicalReleaseOrderTests {
+    @Test("canonical material uses unsigned UTF-8 byte ordering")
+    func unsignedUTF8Ordering() {
+        let astral = "\u{10000}"
+        let privateUse = "\u{e000}"
+        let decomposed = "e\u{301}"
+        let precomposed = "\u{e9}"
+        let values = [astral, precomposed, privateUse, "z", decomposed, "a"]
+        let expected = ["a", decomposed, "z", precomposed, privateUse, astral]
+
+        #expect(CanonicalReleaseOrder.sorted(values) == expected)
+        // Swift String equality is normalization-aware. Canonical release
+        // ordering intentionally compares the preserved UTF-8 bytes instead.
+        #expect(decomposed == precomposed)
+        #expect(CanonicalReleaseOrder.unsignedUTF8Precedes(decomposed, precomposed))
+        #expect(!CanonicalReleaseOrder.unsignedUTF8Precedes(precomposed, decomposed))
+    }
+}