@hasna/recordings 0.2.11 → 0.2.13

package/src/native/Recordings/Updater/Protocol/ReleaseEnvelope.swift

@@ -0,0 +1,229 @@
+import CryptoKit
+import Foundation
+
+public struct ReleaseEnvelopePayload: Codable, Equatable, Sendable {
+    public let schemaVersion: Int
+    public let purpose: String
+    public let keyEpoch: UInt64
+    public let releaseSequence: UInt64
+    public let releaseID: String
+    public let version: String
+    public let build: String
+    public let sourceCommit: String
+    public let artifactSHA256: String
+    public let artifactByteCount: UInt64
+    public let manifestSHA256: String
+    public let manifestByteCount: UInt64
+    public let candidateTreeSHA256: String
+    public let packageSHA256: String
+    public let updateClientSHA256: String
+    public let updateBrokerSHA256: String
+    public let artifactVerifierSHA256: String
+    public let bootstrapMarkerSHA256: String
+    public let architectures: [String]
+    public let minimumOSVersion: String
+    public let minimumBrokerVersion: String
+    public let signingTeamIdentifier: String
+    public let applicationDesignatedRequirement: String
+    public let updateClientDesignatedRequirement: String
+    public let updateBrokerDesignatedRequirement: String
+    public let artifactVerifierDesignatedRequirement: String
+    public let installerCertificateSHA256: String
+    public let issuedAtUTC: String
+    public let expiresAtUTC: String
+
+    enum CodingKeys: String, CodingKey {
+        case schemaVersion = "schema_version"
+        case purpose
+        case keyEpoch = "key_epoch"
+        case releaseSequence = "release_sequence"
+        case releaseID = "release_id"
+        case version
+        case build
+        case sourceCommit = "source_commit"
+        case artifactSHA256 = "artifact_sha256"
+        case artifactByteCount = "artifact_byte_count"
+        case manifestSHA256 = "manifest_sha256"
+        case manifestByteCount = "manifest_byte_count"
+        case candidateTreeSHA256 = "candidate_tree_sha256"
+        case packageSHA256 = "package_sha256"
+        case updateClientSHA256 = "update_client_sha256"
+        case updateBrokerSHA256 = "update_broker_sha256"
+        case artifactVerifierSHA256 = "artifact_verifier_sha256"
+        case bootstrapMarkerSHA256 = "bootstrap_marker_sha256"
+        case architectures
+        case minimumOSVersion = "minimum_os_version"
+        case minimumBrokerVersion = "minimum_broker_version"
+        case signingTeamIdentifier = "signing_team_identifier"
+        case applicationDesignatedRequirement = "application_designated_requirement"
+        case updateClientDesignatedRequirement = "update_client_designated_requirement"
+        case updateBrokerDesignatedRequirement = "update_broker_designated_requirement"
+        case artifactVerifierDesignatedRequirement = "artifact_verifier_designated_requirement"
+        case installerCertificateSHA256 = "installer_certificate_sha256"
+        case issuedAtUTC = "issued_at_utc"
+        case expiresAtUTC = "expires_at_utc"
+    }
+
+    public func canonicalData() throws -> Data {
+        let encoder = JSONEncoder()
+        encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+        return try encoder.encode(self)
+    }
+
+    public func validate(now: Date = Date(), brokerVersion: String = RecordingsUpdateConstants.brokerVersion) throws {
+        guard schemaVersion == RecordingsUpdateConstants.protocolVersion else {
+            throw ReleaseEnvelopeValidationError.unsupportedSchema
+        }
+        guard purpose == "bootstrap" || purpose == "update" else {
+            throw ReleaseEnvelopeValidationError.invalidField("purpose")
+        }
+        guard keyEpoch > 0, releaseSequence > 0 else {
+            throw ReleaseEnvelopeValidationError.invalidField("release_epoch_or_sequence")
+        }
+        guard UUID(uuidString: releaseID) != nil else {
+            throw ReleaseEnvelopeValidationError.invalidField("release_id")
+        }
+        guard Self.isVersion(version), Self.isBuild(build), Self.isVersion(minimumBrokerVersion) else {
+            throw ReleaseEnvelopeValidationError.invalidField("version")
+        }
+        guard Self.isLowerHex(sourceCommit, count: 40) else {
+            throw ReleaseEnvelopeValidationError.invalidField("source_commit")
+        }
+        for (name, value) in [
+            ("artifact_sha256", artifactSHA256),
+            ("manifest_sha256", manifestSHA256),
+            ("candidate_tree_sha256", candidateTreeSHA256),
+            ("package_sha256", packageSHA256),
+            ("update_client_sha256", updateClientSHA256),
+            ("update_broker_sha256", updateBrokerSHA256),
+            ("artifact_verifier_sha256", artifactVerifierSHA256),
+            ("bootstrap_marker_sha256", bootstrapMarkerSHA256),
+            ("installer_certificate_sha256", installerCertificateSHA256),
+        ] where !Self.isLowerHex(value, count: 64) {
+            throw ReleaseEnvelopeValidationError.invalidField(name)
+        }
+        guard purpose != "bootstrap" || artifactSHA256 == packageSHA256 else {
+            throw ReleaseEnvelopeValidationError.invalidField("package_sha256")
+        }
+        guard artifactByteCount > 0,
+              artifactByteCount <= 2 * 1024 * 1024 * 1024,
+              manifestByteCount > 0,
+              manifestByteCount <= 16 * 1024 * 1024
+        else {
+            throw ReleaseEnvelopeValidationError.invalidField("release_input_size")
+        }
+        guard architectures == ["arm64", "x86_64"] else {
+            throw ReleaseEnvelopeValidationError.invalidField("architectures")
+        }
+        guard HostOSVersionPolicy.isValidNumericVersion(minimumOSVersion) else {
+            throw ReleaseEnvelopeValidationError.invalidField("minimum_os_version")
+        }
+        guard signingTeamIdentifier.range(of: #"^[A-Z0-9]{10}$"#, options: .regularExpression) != nil else {
+            throw ReleaseEnvelopeValidationError.invalidField("signing_team_identifier")
+        }
+        for (name, value) in [
+            ("application_designated_requirement", applicationDesignatedRequirement),
+            ("update_client_designated_requirement", updateClientDesignatedRequirement),
+            ("update_broker_designated_requirement", updateBrokerDesignatedRequirement),
+            ("artifact_verifier_designated_requirement", artifactVerifierDesignatedRequirement),
+        ] where value.isEmpty || value.utf8.count > 8_192 {
+            throw ReleaseEnvelopeValidationError.invalidField(name)
+        }
+        guard Self.compareVersions(brokerVersion, minimumBrokerVersion) >= 0 else {
+            throw ReleaseEnvelopeValidationError.brokerTooOld
+        }
+        guard let issued = Self.parseTimestamp(issuedAtUTC), let expires = Self.parseTimestamp(expiresAtUTC) else {
+            throw ReleaseEnvelopeValidationError.invalidField("release_timestamp")
+        }
+        guard issued <= expires, now >= issued.addingTimeInterval(-300), now <= expires else {
+            throw ReleaseEnvelopeValidationError.expiredOrNotYetValid
+        }
+        guard expires.timeIntervalSince(issued) <= 31 * 24 * 60 * 60 else {
+            throw ReleaseEnvelopeValidationError.invalidField("release_validity_window")
+        }
+    }
+
+    private static func isLowerHex(_ value: String, count: Int) -> Bool {
+        value.utf8.count == count && value.range(of: "^[a-f0-9]{\(count)}$", options: .regularExpression) != nil
+    }
+
+    private static func isVersion(_ value: String) -> Bool {
+        value.range(of: #"^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z.-]+)?$"#, options: .regularExpression) != nil
+    }
+
+    private static func isBuild(_ value: String) -> Bool {
+        guard !value.isEmpty, value.utf8.count <= 32 else { return false }
+        return value.range(
+            of: #"^[0-9]+(?:\.[0-9]+){0,2}$"#,
+            options: .regularExpression
+        ) != nil
+    }
+
+    private static func compareVersions(_ lhs: String, _ rhs: String) -> Int {
+        let left = lhs.split(separator: "-", maxSplits: 1)[0].split(separator: ".").compactMap { Int($0) }
+        let right = rhs.split(separator: "-", maxSplits: 1)[0].split(separator: ".").compactMap { Int($0) }
+        guard left.count == 3, right.count == 3 else { return -1 }
+        for index in 0..<3 where left[index] != right[index] {
+            return left[index] < right[index] ? -1 : 1
+        }
+        return 0
+    }
+
+    private static func parseTimestamp(_ value: String) -> Date? {
+        let formatter = ISO8601DateFormatter()
+        formatter.formatOptions = [.withInternetDateTime, .withFractionalSeconds]
+        return formatter.date(from: value)
+    }
+}
+
+public struct SignedReleaseEnvelope: Codable, Sendable {
+    public let payload: ReleaseEnvelopePayload
+    public let signature: String
+
+    public init(payload: ReleaseEnvelopePayload, signature: String) {
+        self.payload = payload
+        self.signature = signature
+    }
+
+    public func verify(publicKeyData: Data, now: Date = Date()) throws -> ReleaseEnvelopePayload {
+        try payload.validate(now: now)
+        guard publicKeyData.count == 32 else {
+            throw ReleaseEnvelopeValidationError.invalidPublicKey
+        }
+        guard let signatureData = Data(base64Encoded: signature), signatureData.count == 64 else {
+            throw ReleaseEnvelopeValidationError.invalidSignatureEncoding
+        }
+        let publicKey: Curve25519.Signing.PublicKey
+        do {
+            publicKey = try Curve25519.Signing.PublicKey(rawRepresentation: publicKeyData)
+        } catch {
+            throw ReleaseEnvelopeValidationError.invalidPublicKey
+        }
+        guard publicKey.isValidSignature(signatureData, for: try payload.canonicalData()) else {
+            throw ReleaseEnvelopeValidationError.invalidSignature
+        }
+        return payload
+    }
+}
+
+public enum ReleaseEnvelopeValidationError: Error, CustomStringConvertible {
+    case unsupportedSchema
+    case invalidField(String)
+    case brokerTooOld
+    case expiredOrNotYetValid
+    case invalidPublicKey
+    case invalidSignatureEncoding
+    case invalidSignature
+
+    public var description: String {
+        switch self {
+        case .unsupportedSchema: "Unsupported release-envelope schema"
+        case let .invalidField(name): "Invalid release-envelope field: \(name)"
+        case .brokerTooOld: "The installed update broker is too old for this release"
+        case .expiredOrNotYetValid: "The release envelope is expired or not yet valid"
+        case .invalidPublicKey: "The pinned release-envelope public key is invalid"
+        case .invalidSignatureEncoding: "The release-envelope signature encoding is invalid"
+        case .invalidSignature: "The release-envelope signature is invalid"
+        }
+    }
+}

package/src/native/Recordings/Updater/Protocol/UpdateProtocol.swift

@@ -0,0 +1,119 @@
+import Foundation
+
+public enum RecordingsUpdateConstants {
+    public static let protocolVersion = 1
+    public static let brokerVersion = "1.0.0"
+    public static let lifecycle = "bootstrap-v1-app-updates-only"
+    public static let rootMaintenanceSupported = false
+    public static let keyRotationSupported = false
+    public static let machServiceName = "com.hasna.recordings.updater"
+    public static let applicationPath = "/Applications/Recordings.app"
+    public static let brokerExecutablePath = "/Library/PrivilegedHelperTools/com.hasna.recordings.updater"
+    public static let stateRoot = "/Library/Application Support/Hasna/Recordings/Updates"
+    public static let trustRoot = "/Library/Application Support/Hasna/Recordings/Trust"
+    public static let policyPath = trustRoot + "/broker-policy.json"
+    public static let envelopePublicKeyDirectory = trustRoot + "/envelope-keys"
+    public static let monotonicStateDirectory = "/private/var/db/com.hasna.recordings.updater"
+    public static let monotonicStatePath = monotonicStateDirectory + "/release-state.json"
+    public static let artifactVerifierPath = "/Library/PrivilegedHelperTools/com.hasna.recordings.artifact-verifier"
+    public static let artifactVerifierSandboxProfilePath = trustRoot + "/artifact-verifier.sb"
+    public static let bootstrapMarkerPath = trustRoot + "/bootstrap-marker.json"
+    public static let artifactVerifierAccount = "_recordingsverify"
+    public static let updateClientRelativePath = "Contents/Helpers/recordings-update-client"
+}
+
+public enum RecordingsUpdateErrorCode: String, Codable, Sendable {
+    case invalidRequest = "invalid_request"
+    case unauthorizedPeer = "unauthorized_peer"
+    case brokerUnavailable = "broker_unavailable"
+    case brokerNotPrivileged = "broker_not_privileged"
+    case invalidDescriptor = "invalid_descriptor"
+    case artifactTooLarge = "artifact_too_large"
+    case invalidEnvelope = "invalid_envelope"
+    case signatureRejected = "signature_rejected"
+    case artifactMismatch = "artifact_mismatch"
+    case rollbackRejected = "rollback_rejected"
+    case unsupportedLifecycle = "unsupported_lifecycle"
+    case codeIdentityRejected = "code_identity_rejected"
+    case candidateRejected = "candidate_rejected"
+    case activationFailed = "activation_failed"
+    case internalFailure = "internal_failure"
+}
+
+public enum RecordingsUpdateReplyKey {
+    public static let success = "success"
+    public static let code = "code"
+    public static let message = "message"
+    public static let transactionID = "transaction_id"
+    public static let releaseID = "release_id"
+    public static let installedVersion = "installed_version"
+    public static let lifecycle = "lifecycle"
+    public static let rootMaintenanceSupported = "root_maintenance_supported"
+    public static let keyRotationSupported = "key_rotation_supported"
+    public static let keyEpoch = "key_epoch"
+}
+
+public func updateSuccessReply(
+    transactionID: String? = nil,
+    releaseID: String? = nil,
+    installedVersion: String? = nil
+) -> NSDictionary {
+    let reply = NSMutableDictionary()
+    reply[RecordingsUpdateReplyKey.success] = true
+    reply[RecordingsUpdateReplyKey.code] = "ok"
+    reply[RecordingsUpdateReplyKey.message] = "Update completed"
+    reply[RecordingsUpdateReplyKey.lifecycle] = RecordingsUpdateConstants.lifecycle
+    reply[RecordingsUpdateReplyKey.rootMaintenanceSupported] =
+        RecordingsUpdateConstants.rootMaintenanceSupported
+    reply[RecordingsUpdateReplyKey.keyRotationSupported] =
+        RecordingsUpdateConstants.keyRotationSupported
+    if let transactionID { reply[RecordingsUpdateReplyKey.transactionID] = transactionID }
+    if let releaseID { reply[RecordingsUpdateReplyKey.releaseID] = releaseID }
+    if let installedVersion { reply[RecordingsUpdateReplyKey.installedVersion] = installedVersion }
+    return reply
+}
+
+public func updateFailureReply(_ code: RecordingsUpdateErrorCode, message: String) -> NSDictionary {
+    let reply = NSMutableDictionary()
+    reply[RecordingsUpdateReplyKey.success] = false
+    reply[RecordingsUpdateReplyKey.code] = code.rawValue
+    reply[RecordingsUpdateReplyKey.message] = message
+    reply[RecordingsUpdateReplyKey.lifecycle] = RecordingsUpdateConstants.lifecycle
+    reply[RecordingsUpdateReplyKey.rootMaintenanceSupported] =
+        RecordingsUpdateConstants.rootMaintenanceSupported
+    reply[RecordingsUpdateReplyKey.keyRotationSupported] =
+        RecordingsUpdateConstants.keyRotationSupported
+    return reply
+}
+
+@objc(RecordingsUpdateXPCProtocol)
+public protocol RecordingsUpdateXPCProtocol {
+    /// File descriptors, not paths, cross the trust boundary. The broker copies every
+    /// descriptor into root-owned storage before parsing or executing any content.
+    @objc(installWithArchive:manifest:envelope:reply:)
+    func install(
+        archive: FileHandle,
+        manifest: FileHandle,
+        envelope: FileHandle,
+        withReply reply: @escaping (NSDictionary) -> Void
+    )
+
+    @objc(queryStatusWithReply:)
+    func queryStatus(withReply reply: @escaping (NSDictionary) -> Void)
+}
+
+/// XPC decoding is intentionally limited to retained file handles on request and
+/// scalar dictionaries on reply. No path-bearing or arbitrary option object is accepted.
+public func makeRecordingsUpdateXPCInterface() -> NSXPCInterface {
+    let interface = NSXPCInterface(with: RecordingsUpdateXPCProtocol.self)
+    let installSelector = NSSelectorFromString("installWithArchive:manifest:envelope:reply:")
+    let statusSelector = NSSelectorFromString("queryStatusWithReply:")
+    let fileHandleClasses: Set<AnyHashable> = [FileHandle.self]
+    for index in 0..<3 {
+        interface.setClasses(fileHandleClasses, for: installSelector, argumentIndex: index, ofReply: false)
+    }
+    let replyClasses: Set<AnyHashable> = [NSDictionary.self, NSString.self, NSNumber.self]
+    interface.setClasses(replyClasses, for: installSelector, argumentIndex: 0, ofReply: true)
+    interface.setClasses(replyClasses, for: statusSelector, argumentIndex: 0, ofReply: true)
+    return interface
+}

package/src/native/Recordings/Updater/ProtocolTests/BoundedProcessRunnerTests.swift

@@ -0,0 +1,60 @@
+import Foundation
+import Testing
+@testable import RecordingsUpdateProtocol
+
+struct BoundedProcessRunnerTests {
+    @Test("captures small successful output exactly")
+    func capturesSmallOutput() throws {
+        let result = try BoundedProcessRunner.run(
+            executablePath: "/bin/sh",
+            arguments: ["-c", "printf '26.0.1\\n'"],
+            environment: [:],
+            maximumOutputBytes: 64,
+            timeout: 1
+        )
+        #expect(result.exitedNormally)
+        #expect(result.terminationStatus == 0)
+        #expect(result.standardOutput == Data("26.0.1\n".utf8))
+    }
+
+    @Test("rejects output at the first byte beyond the configured limit")
+    func rejectsOversizedOutput() {
+        #expect(throws: BoundedProcessError.outputTooLarge) {
+            _ = try BoundedProcessRunner.run(
+                executablePath: "/bin/sh",
+                arguments: ["-c", "printf '12345'"],
+                environment: [:],
+                maximumOutputBytes: 4,
+                timeout: 1
+            )
+        }
+    }
+
+    @Test("kills a subprocess that exceeds its deadline")
+    func rejectsTimedOutProcess() {
+        #expect(throws: BoundedProcessError.timedOut) {
+            _ = try BoundedProcessRunner.run(
+                executablePath: "/bin/sh",
+                arguments: ["-c", "exec /bin/sleep 5"],
+                environment: [:],
+                maximumOutputBytes: 64,
+                timeout: 0.05
+            )
+        }
+    }
+
+    @Test("deadline is not extended by a descendant retaining stdout")
+    func rejectsInheritedPipeDescendant() {
+        let startedAt = Date()
+        #expect(throws: BoundedProcessError.timedOut) {
+            _ = try BoundedProcessRunner.run(
+                executablePath: "/bin/sh",
+                arguments: ["-c", "(/bin/sleep 2; printf inherited) & exit 0"],
+                environment: [:],
+                maximumOutputBytes: 64,
+                timeout: 0.05
+            )
+        }
+        #expect(Date().timeIntervalSince(startedAt) < 1)
+    }
+}

package/src/native/Recordings/Updater/ProtocolTests/CandidateMetadataPolicyTests.swift

@@ -0,0 +1,168 @@
+import Testing
+@testable import RecordingsUpdateProtocol
+
+struct CandidateMetadataPolicyTests {
+    @Test("exact release application and provenance metadata are admitted")
+    func exactMetadataIsAdmitted() throws {
+        try validate()
+    }
+
+    @Test("bundle identifier and executable mismatches are rejected")
+    func applicationIdentityMismatchIsRejected() {
+        #expect(throws: CandidateMetadataPolicyError.applicationIdentifierMismatch) {
+            try validate(applicationIdentifier: "com.example.other")
+        }
+        #expect(throws: CandidateMetadataPolicyError.applicationExecutableMismatch) {
+            try validate(executable: "Other")
+        }
+    }
+
+    @Test("application and provenance version mismatches are rejected")
+    func versionMismatchIsRejected() {
+        #expect(throws: CandidateMetadataPolicyError.applicationVersionMismatch) {
+            try validate(applicationVersion: "0.2.12")
+        }
+        #expect(throws: CandidateMetadataPolicyError.provenanceVersionMismatch) {
+            try validate(provenanceVersion: "0.2.12")
+        }
+    }
+
+    @Test("application and provenance build mismatches are rejected")
+    func buildMismatchIsRejected() {
+        #expect(throws: CandidateMetadataPolicyError.applicationBuildMismatch) {
+            try validate(applicationBuild: "0.2.12")
+        }
+        #expect(throws: CandidateMetadataPolicyError.provenanceBuildMismatch) {
+            try validate(provenanceBuild: "0.2.12")
+        }
+    }
+
+    @Test("provenance source and Team ID mismatches are rejected")
+    func provenanceIdentityMismatchIsRejected() {
+        #expect(throws: CandidateMetadataPolicyError.provenanceSourceMismatch) {
+            try validate(sourceCommit: String(repeating: "b", count: 40))
+        }
+        #expect(throws: CandidateMetadataPolicyError.provenanceTeamMismatch) {
+            try validate(teamIdentifier: "OTHERTE123")
+        }
+    }
+
+    @Test("application and provenance minimum OS mismatches are rejected")
+    func minimumOSMismatchIsRejected() {
+        #expect(throws: CandidateMetadataPolicyError.applicationMinimumOSMismatch) {
+            try validate(applicationMinimumOS: "25.0")
+        }
+        #expect(throws: CandidateMetadataPolicyError.provenanceMinimumOSMismatch) {
+            try validate(provenanceMinimumOS: "25.0")
+        }
+    }
+
+    @Test("actual, provenance, and companion architecture mismatches are rejected")
+    func architectureMismatchIsRejected() {
+        #expect(throws: CandidateMetadataPolicyError.applicationArchitectureMismatch) {
+            try validate(applicationArchitectures: ["arm64"])
+        }
+        #expect(throws: CandidateMetadataPolicyError.provenanceArchitectureMismatch) {
+            try validate(provenanceArchitectures: ["arm64"])
+        }
+        #expect(throws: CandidateMetadataPolicyError.provenanceArchitectureMismatch) {
+            try validate(companionArchitectures: ["arm64"])
+        }
+        #expect(throws: CandidateMetadataPolicyError.companionArchitectureMismatch) {
+            try validate(actualCompanionArchitectures: ["arm64"])
+        }
+    }
+
+    @Test("update client must contain exactly the signed universal architectures")
+    func updateClientArchitectureMismatchIsRejected() {
+        for architectures in [
+            ["arm64"],
+            ["x86_64"],
+            [],
+            ["arm64", "x86_64", "i386"],
+        ] {
+            #expect(throws: CandidateMetadataPolicyError.updateClientArchitectureMismatch) {
+                try validate(actualUpdateClientArchitectures: architectures)
+            }
+        }
+    }
+
+    @Test("measured companion digest and signed companion release version are bound")
+    func companionIdentityMismatchIsRejected() {
+        #expect(throws: CandidateMetadataPolicyError.companionDigestMismatch) {
+            try validate(actualCompanionSHA256: String(repeating: "c", count: 64))
+        }
+        #expect(throws: CandidateMetadataPolicyError.provenanceCompanionVersionMismatch) {
+            try validate(companionVersion: "0.2.12")
+        }
+    }
+
+    @Test("local-only provenance fields are rejected from release candidates")
+    func localOnlyFieldsAreRejected() {
+        #expect(throws: CandidateMetadataPolicyError.localOnlyProvenanceRejected) {
+            try validate(containsLocalOnlyFields: true)
+        }
+    }
+
+    private func validate(
+        applicationIdentifier: String = "com.hasna.recordings",
+        applicationVersion: String = "0.2.13",
+        applicationBuild: String = "0.2.13",
+        executable: String = "Recordings",
+        applicationMinimumOS: String = "26.0",
+        applicationArchitectures: [String] = ["arm64", "x86_64"],
+        actualUpdateClientArchitectures: [String] = ["arm64", "x86_64"],
+        provenanceVersion: String = "0.2.13",
+        provenanceBuild: String = "0.2.13",
+        sourceCommit: String = String(repeating: "a", count: 40),
+        teamIdentifier: String = "EXAMPLE123",
+        provenanceMinimumOS: String = "26.0",
+        provenanceArchitectures: [String] = ["arm64", "x86_64"],
+        actualCompanionSHA256: String = String(repeating: "d", count: 64),
+        actualCompanionArchitectures: [String] = ["arm64", "x86_64"],
+        companionVersion: String = "0.2.13",
+        companionSHA256: String = String(repeating: "d", count: 64),
+        companionArchitectures: [String] = ["arm64", "x86_64"],
+        containsLocalOnlyFields: Bool = false
+    ) throws {
+        try CandidateMetadataPolicy.validate(
+            application: CandidateApplicationMetadata(
+                bundleIdentifier: applicationIdentifier,
+                shortVersion: applicationVersion,
+                buildVersion: applicationBuild,
+                executable: executable,
+                minimumOSVersion: applicationMinimumOS,
+                architectures: applicationArchitectures
+            ),
+            updateClientArchitectures: actualUpdateClientArchitectures,
+            companion: CandidateCompanionMetadata(
+                sha256: actualCompanionSHA256,
+                architectures: actualCompanionArchitectures
+            ),
+            provenance: CandidateBuildProvenanceMetadata(
+                schemaVersion: 4,
+                containsLocalOnlyFields: containsLocalOnlyFields,
+                bundleIdentifier: "com.hasna.recordings",
+                bundleVersion: provenanceVersion,
+                bundleBuildVersion: provenanceBuild,
+                sourceCommit: sourceCommit,
+                teamIdentifier: teamIdentifier,
+                minimumMacOS: provenanceMinimumOS,
+                architectures: provenanceArchitectures,
+                companionVersion: companionVersion,
+                companionSHA256: companionSHA256,
+                companionArchitectures: companionArchitectures
+            ),
+            expected: CandidateReleaseMetadataExpectation(
+                applicationIdentifier: "com.hasna.recordings",
+                applicationExecutable: "Recordings",
+                version: "0.2.13",
+                build: "0.2.13",
+                sourceCommit: String(repeating: "a", count: 40),
+                signingTeamIdentifier: "EXAMPLE123",
+                minimumOSVersion: "26.0",
+                architectures: ["arm64", "x86_64"]
+            )
+        )
+    }
+}

package/src/native/Recordings/Updater/ProtocolTests/HostOSVersionPolicyTests.swift

@@ -0,0 +1,62 @@
+import Testing
+@testable import RecordingsUpdateProtocol
+
+struct HostOSVersionPolicyTests {
+    @Test("equal minimum and host versions are admitted")
+    func equalVersionIsAdmitted() throws {
+        try HostOSVersionPolicy.validate(
+            candidateMinimumOSVersion: "26.0",
+            hostProductVersion: "26.0.0"
+        )
+    }
+
+    @Test("an older minimum OS is admitted on a newer host using numeric semantics")
+    func olderMinimumIsAdmitted() throws {
+        try HostOSVersionPolicy.validate(
+            candidateMinimumOSVersion: "15.9.12",
+            hostProductVersion: "15.10"
+        )
+    }
+
+    @Test("a newer minimum OS is rejected")
+    func newerMinimumIsRejected() {
+        #expect(throws: HostOSVersionPolicyError.candidateRequiresNewerOS) {
+            try HostOSVersionPolicy.validate(
+                candidateMinimumOSVersion: "26.1",
+                hostProductVersion: "26.0.9"
+            )
+        }
+    }
+
+    @Test("malformed host ProductVersion evidence is rejected")
+    func malformedHostEvidenceIsRejected() {
+        for value in ["", "26", "26.beta", "26.0.0.1", "026.0", "26..1"] {
+            #expect(throws: HostOSVersionPolicyError.malformedHostProductVersion) {
+                try HostOSVersionPolicy.validate(
+                    candidateMinimumOSVersion: "26.0",
+                    hostProductVersion: value
+                )
+            }
+        }
+    }
+
+    @Test("malformed signed minimum OS evidence is rejected")
+    func malformedCandidateEvidenceIsRejected() {
+        #expect(throws: HostOSVersionPolicyError.malformedCandidateMinimumOSVersion) {
+            try HostOSVersionPolicy.validate(
+                candidateMinimumOSVersion: "26.beta",
+                hostProductVersion: "26.0"
+            )
+        }
+    }
+
+    @Test("unavailable host ProductVersion evidence is rejected")
+    func unavailableHostEvidenceIsRejected() {
+        #expect(throws: HostOSVersionPolicyError.hostProductVersionUnavailable) {
+            try HostOSVersionPolicy.validate(
+                candidateMinimumOSVersion: "26.0",
+                hostProductVersion: nil
+            )
+        }
+    }
+}