Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
11.6 KB
Raw Blame
import Foundation
import Testing
@testable import VPhoneCoreKit

/// The acceptance criterion for this port is byte equivalence with
/// `tools/apfs_snap_rename.py`, because what it edits is a filesystem the
/// guest kernel then has to mount. A "close enough" rename is a VM that does
/// not boot.
///
/// The fixtures here are synthetic APFS-shaped blocks rather than a real
/// `Disk.img`: a real image is tens of gigabytes and is not in the repo, and
/// the two properties that matter — the fletcher64 and which hits get rewritten
/// — are exercised just as well by a handful of 4 KiB blocks. The end-to-end
/// byte gate against a real image is a separate, manual step.
@Suite("APFS snapshot rename")
struct APFSSnapshotTests {
    // MARK: - Helpers

    /// A 4 KiB block carrying `payload` at `offset`, with a correct checksum.
    static func makeValidBlock(payload: [UInt8], at offset: Int, filler: UInt8 = 0x41) -> [UInt8] {
        var block = [UInt8](repeating: filler, count: VPhoneAPFSSnapshot.blockSize)
        for k in 0 ..< 8 {
            block[k] = 0
        }
        for (k, byte) in payload.enumerated() {
            block[offset + k] = byte
        }

        let sum = block.withUnsafeBytes { VPhoneAPFSSnapshot.checksum($0) }
        withUnsafeBytes(of: sum.littleEndian) { bytes in
            for (k, byte) in bytes.enumerated() {
                block[k] = byte
            }
        }
        return block
    }

    static func snapshotName(hash: String) -> [UInt8] {
        VPhoneAPFSSnapshot.oldPrefix + Array(hash.utf8)
    }

    static let validHash = String(repeating: "ab12cd34", count: 8) // 64 hex chars

    static func write(_ bytes: [UInt8]) throws -> URL {
        let url = FileManager.default.temporaryDirectory
            .appendingPathComponent("vphone-apfs-\(UUID().uuidString).img")
        try Data(bytes).write(to: url)
        return url
    }

    // MARK: - Checksum

    @Test
    func `fletcher64 round-trips: a block we stamp verifies`() {
        let block = Self.makeValidBlock(payload: Self.snapshotName(hash: Self.validHash), at: 100)
        let stored = block.withUnsafeBytes { $0.loadUnaligned(as: UInt64.self) }
        let computed = block.withUnsafeBytes { VPhoneAPFSSnapshot.checksum($0) }
        #expect(stored == computed)
    }

    @Test
    func `fletcher64 uses modulus 0xFFFFFFFF, not 2^32`() {
        // A block of all-0xFF words is the case where the two moduli diverge:
        // with 2^32 the sums wrap to 0, with 0xFFFFFFFF they do not. Getting
        // this "right" in the arithmetic sense would make every checksum wrong.
        var block = [UInt8](repeating: 0xFF, count: VPhoneAPFSSnapshot.blockSize)
        for k in 0 ..< 8 {
            block[k] = 0
        }
        let sum = block.withUnsafeBytes { VPhoneAPFSSnapshot.checksum($0) }
        #expect(sum != 0)
    }

    // MARK: - Scan

    @Test
    func `finds a snapshot record in a valid block`() {
        let block = Self.makeValidBlock(payload: Self.snapshotName(hash: Self.validHash), at: 100)
        let report = block.withUnsafeBytes { VPhoneAPFSSnapshot.scan($0) }

        #expect(report.recordCount == 1)
        #expect(report.blocks.count == 1)
        #expect(report.blocks[0].blockOffset == 0)
        #expect(report.blocks[0].offsetsInBlock == [100])
        #expect(report.snapshotName == "com.apple.os.update-" + Self.validHash)
    }

    @Test
    func `ignores a hit in a block that does not checksum`() {
        // This is the case that matters: the same string is baked into binaries
        // sitting on the volume. Those are file data, so the block they live in
        // is not an APFS object and must never be rewritten.
        var block = Self.makeValidBlock(payload: Self.snapshotName(hash: Self.validHash), at: 100)
        block[9] ^= 0xFF // corrupt a byte the checksum covers

        let report = block.withUnsafeBytes { VPhoneAPFSSnapshot.scan($0) }
        #expect(report.isEmpty)
    }

    @Test
    func `ignores a prefix not followed by 64 hex characters`() {
        let notAHash = String(repeating: "zz", count: 32) // 64 chars, not hex
        let block = Self.makeValidBlock(payload: Self.snapshotName(hash: notAHash), at: 100)
        let report = block.withUnsafeBytes { VPhoneAPFSSnapshot.scan($0) }
        #expect(report.isEmpty)
    }

    @Test
    func `finds both records when they share one block`() {
        // The real layout: snap_metadata value and snap_name key, normally in
        // the same leaf node.
        var block = [UInt8](repeating: 0x41, count: VPhoneAPFSSnapshot.blockSize)
        for k in 0 ..< 8 {
            block[k] = 0
        }
        let name = Self.snapshotName(hash: Self.validHash)
        for (k, byte) in name.enumerated() {
            block[200 + k] = byte
        }
        for (k, byte) in name.enumerated() {
            block[1200 + k] = byte
        }
        let sum = block.withUnsafeBytes { VPhoneAPFSSnapshot.checksum($0) }
        withUnsafeBytes(of: sum.littleEndian) { bytes in
            for (k, byte) in bytes.enumerated() {
                block[k] = byte
            }
        }

        let report = block.withUnsafeBytes { VPhoneAPFSSnapshot.scan($0) }
        #expect(report.recordCount == 2)
        #expect(report.blocks.count == 1)
        #expect(report.blocks[0].offsetsInBlock == [200, 1200])
    }

    @Test
    func `reports blocks in ascending order`() {
        let name = Self.snapshotName(hash: Self.validHash)
        let first = Self.makeValidBlock(payload: name, at: 100)
        let second = Self.makeValidBlock(payload: name, at: 300, filler: 0x42)
        let report = (first + second).withUnsafeBytes { VPhoneAPFSSnapshot.scan($0) }

        #expect(report.blocks.map(\.blockOffset) == [0, VPhoneAPFSSnapshot.blockSize])
    }

    // MARK: - Rename

    @Test
    func `renames every record and leaves the block verifying`() throws {
        let name = Self.snapshotName(hash: Self.validHash)
        let url = try Self.write(Self.makeValidBlock(payload: name, at: 100))
        defer { try? FileManager.default.removeItem(at: url) }

        try VPhoneAPFSSnapshot.rename(imageAt: url, log: { _ in })

        let after = try [UInt8](Data(contentsOf: url))
        let renamed = String(decoding: after[100 ..< 120], as: UTF8.self)
        #expect(renamed == VPhoneAPFSSnapshot.defaultNewPrefix)

        // The point of fixing the checksum: the block still reads as an APFS
        // object afterwards, or the volume is corrupt.
        let stored = after.withUnsafeBytes { $0.loadUnaligned(as: UInt64.self) }
        let computed = after.withUnsafeBytes { VPhoneAPFSSnapshot.checksum($0) }
        #expect(stored == computed)
    }

    @Test
    func `finds a record past a hole in a 128 GB sparse image`() throws {
        // Mid-window, so skipping the holes must still land on the window
        // boundary before it. Scanning every hole would take minutes.
        let recordOffset = 100 * 1024 * 1024 * 1024 + 3 * 64 * 1024 * 1024 + 8 * VPhoneAPFSSnapshot.blockSize
        let block = Self.makeValidBlock(payload: Self.snapshotName(hash: Self.validHash), at: 100)
        let url = try Self.write([])
        defer { try? FileManager.default.removeItem(at: url) }
        let handle = try FileHandle(forWritingTo: url)
        try handle.seek(toOffset: UInt64(recordOffset))
        try handle.write(contentsOf: Data(block))
        try handle.truncate(atOffset: 128 * 1_000_000_000)
        try handle.close()

        let report = try VPhoneAPFSSnapshot.rename(imageAt: url, dryRun: true, log: { _ in })
        #expect(report.blocks.map(\.blockOffset) == [recordOffset])
    }

    @Test
    func `renames snapshot records on both sides of a 64 MiB scan window`() throws {
        let name = Self.snapshotName(hash: Self.validHash)
        let first = Self.makeValidBlock(payload: name, at: 100)
        let second = Self.makeValidBlock(payload: name, at: 200)
        let url = try Self.write(first)
        defer { try? FileManager.default.removeItem(at: url) }
        let handle = try FileHandle(forWritingTo: url)
        try handle.seek(toOffset: 64 * 1024 * 1024)
        try handle.write(contentsOf: Data(second))
        try handle.close()

        let report = try VPhoneAPFSSnapshot.rename(imageAt: url, log: { _ in })
        #expect(report.blocks.map(\.blockOffset) == [0, 64 * 1024 * 1024])
        let check = try FileHandle(forReadingFrom: url)
        defer { try? check.close() }
        let firstAfter = try #require(try check.read(upToCount: VPhoneAPFSSnapshot.blockSize))
        try check.seek(toOffset: 64 * 1024 * 1024)
        let secondAfter = try #require(try check.read(upToCount: VPhoneAPFSSnapshot.blockSize))
        for (block, offset) in [(firstAfter, 100), (secondAfter, 200)] {
            #expect(String(decoding: block[offset ..< offset + 20], as: UTF8.self)
                == VPhoneAPFSSnapshot.defaultNewPrefix)
            #expect(block.withUnsafeBytes { VPhoneAPFSSnapshot.checksum($0) }
                == block.withUnsafeBytes { $0.loadUnaligned(as: UInt64.self) })
        }
    }

    @Test
    func `rename is idempotent: a second pass finds nothing`() throws {
        let name = Self.snapshotName(hash: Self.validHash)
        let url = try Self.write(Self.makeValidBlock(payload: name, at: 100))
        defer { try? FileManager.default.removeItem(at: url) }

        try VPhoneAPFSSnapshot.rename(imageAt: url, log: { _ in })
        let second = try VPhoneAPFSSnapshot.rename(imageAt: url, log: { _ in })
        #expect(second.isEmpty)
    }

    @Test
    func `dry run changes nothing`() throws {
        let name = Self.snapshotName(hash: Self.validHash)
        let original = Self.makeValidBlock(payload: name, at: 100)
        let url = try Self.write(original)
        defer { try? FileManager.default.removeItem(at: url) }

        let report = try VPhoneAPFSSnapshot.rename(imageAt: url, dryRun: true, log: { _ in })
        #expect(report.recordCount == 1)
        #expect(try [UInt8](Data(contentsOf: url)) == original)
    }

    @Test
    func `a differently sized prefix is refused`() throws {
        let name = Self.snapshotName(hash: Self.validHash)
        let url = try Self.write(Self.makeValidBlock(payload: name, at: 100))
        defer { try? FileManager.default.removeItem(at: url) }

        // Same length is load-bearing, not cosmetic: a different length would
        // move every following byte in the b-tree node and invalidate name_len.
        #expect(throws: VPhoneAPFSSnapshotError.self) {
            try VPhoneAPFSSnapshot.rename(imageAt: url, newPrefix: "too-short-", log: { _ in })
        }
    }

    @Test
    func `log lines match the Python the port replaces`() throws {
        let name = Self.snapshotName(hash: Self.validHash)
        let url = try Self.write(Self.makeValidBlock(payload: name, at: 100))
        defer { try? FileManager.default.removeItem(at: url) }

        var lines: [String] = []
        try VPhoneAPFSSnapshot.rename(imageAt: url, dryRun: true, log: { lines.append($0) })

        #expect(lines == [
            "Detected snapshot: com.apple.os.update-\(Self.validHash)",
            "Records: 1 in 1 block(s): ['0x0']",
            "Dry run: the prefix would be renamed to orig-fs.disabled.rn-.",
        ])
    }

    @Test
    func `says so when there is nothing to rename`() throws {
        let url = try Self.write([UInt8](repeating: 0x41, count: VPhoneAPFSSnapshot.blockSize))
        defer { try? FileManager.default.removeItem(at: url) }

        var lines: [String] = []
        let report = try VPhoneAPFSSnapshot.rename(imageAt: url, log: { lines.append($0) })
        #expect(report.isEmpty)
        #expect(lines == [
            "No com.apple.os.update-* root snapshot found. The snapshot may already be renamed.",
        ])
    }
}