Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
17.7 KB
Raw Blame
// DyldSharedCacheLSDEmbeddedRegTests.swift — parity for the lsd embedded-registration gate.
//
// The patch is one instruction in a 6.7 GB cache, and a wrong one is a boot
// panic rather than a failing assertion, so the reference these tests grade
// against is the Python that shipped before this port: `cfw.py
// patch-lsd-embedded-reg`. That Python has since been deleted, so its result
// is frozen here instead of re-run: `FrozenReference` below records the site
// it found, the bytes it wrote and the SHA-256 of every chunk it changed, and
// the Swift patcher is graded against those numbers. Each constant names the
// command that produced it.
//
// The cache is required. Point `VPHONE_DSC_PRISTINE` at a directory of
// `dyld_shared_cache_arm64e*` chunks, or leave the default
// `ipsws/ref_extract/dsc_pristine` in place. Without it these tests FAIL — the
// suite never opens with a bare `return`, which Swift Testing reports as a
// pass, so a green run cannot mean the cache was absent. A machine that
// genuinely cannot carry the fixture sets `VPHONE_DSC_FIXTURE_OPTIONAL=1`,
// which turns the failure into a visible skip.
//
// Nothing here writes to the pristine tree. Clones are made with `clonefile`
// (instant and near-free on APFS) under the system temporary directory, or
// under `VPHONE_DSC_SCRATCH` when the caller names one.

import CryptoKit
@testable import FirmwarePatcher
import Foundation
import Testing
import VPhonePatchKit

// MARK: - The frozen reference

/// What the reference Python wrote on the real 24A435 arm64e shared cache.
///
/// Every value below was read off one live run, recorded at commit 78cbeea:
///
///     .venv/bin/python3 scripts/patchers/cfw.py \
///         patch-lsd-embedded-reg <clone of ipsws/ref_extract/dsc_pristine>
///
/// The Swift patcher has to land on the same site, write the same bytes and
/// leave the same chunk files with the same digests.
private enum FrozenReference {
    /// Python: `[.] -[_LSDModifyClient clientIsEntitled…] @ 0x186EE9FAC`.
    static let methodVMA: UInt64 = 0x1_86EE_9FAC

    /// Python: `[.] gate: cbz w0, #0x186eea048 @ 0x186EEA024`.
    static let gateVMA: UInt64 = 0x1_86EE_A024

    /// Python: the gate it decoded at `0x186EEA024` was a `cbz`.
    static let gateMnemonic = "cbz"

    /// Python: `(fall-through sets w20=1)` — the register carrying the YES.
    static let gateResultRegister = "w20"

    /// Python: `NOP'd gate cbz -> nop … (bytes 20010034 -> 1f2003d5)`.
    static let originalBytes = Data([0x20, 0x01, 0x00, 0x34])

    /// Python: the same line's replacement half, `1f2003d5`, i.e. `ARM64.nop`.
    static let patchedBytes = Data([0x1F, 0x20, 0x03, 0xD5])

    /// Python: one `NOP'd gate` line, so one site written.
    static let sitesWritten = 1

    /// `cmp -s` of the Python's output against the pristine tree, chunk by
    /// chunk: exactly one file moved, with this SHA-256 afterwards, from
    /// `shasum -a 256 <python output>/dyld_shared_cache_arm64e.01`.
    ///
    /// The digest covers the re-attestation as well as the NOP — the Python
    /// logged `re-attest: wrote slot 6842 of dyld_shared_cache_arm64e.01`
    /// (`ee91dcbd.. -> 4ba06a66..`), `updated 1 slot hash(es) across 1
    /// chunk(s)`, and a Swift run that skipped or mis-computed that slot hash
    /// would land on a different digest here.
    ///
    /// Two further runs of the same Python pinned the edges: re-run over its
    /// own output printed `already NOP at 0x186EEA024`, no `NOP'd gate` line,
    /// `updated 0 slot hash(es)`, and left this digest standing; `--dry-run`
    /// on a fresh clone printed `would NOP gate cbz -> nop at 0x186EEA024` and
    /// changed no byte of any chunk.
    static let changedChunks: [String: String] = [
        "dyld_shared_cache_arm64e.01":
            "e0c33aa967c0de2d2f46ee6becf40eab5acf20c12a8e1d99bf5b14da6da12a7c",
    ]
}

// MARK: - Fixture discovery

private enum LSDRegFixture {
    static let repoRoot = URL(fileURLWithPath: #filePath)
        .deletingLastPathComponent()
        .deletingLastPathComponent()
        .deletingLastPathComponent()
        .deletingLastPathComponent()
        .deletingLastPathComponent()

    /// The read-only reference cache.
    static var pristine: URL? {
        let url = ProcessInfo.processInfo.environment["VPHONE_DSC_PRISTINE"]
            .map { URL(fileURLWithPath: $0) }
            ?? repoRoot.appendingPathComponent("ipsws/ref_extract/dsc_pristine")
        let main = url.appendingPathComponent("dyld_shared_cache_arm64e")
        return FileManager.default.fileExists(atPath: main.path) ? url : nil
    }

    /// Opt-out for a machine that cannot carry the 6.7 GB fixture.
    static var isOptional: Bool {
        ProcessInfo.processInfo.environment["VPHONE_DSC_FIXTURE_OPTIONAL"] == "1"
    }

    /// The suite runs unless the cache is absent *and* the caller opted out.
    static var runs: Bool {
        pristine != nil || !isOptional
    }

    static let missing: Comment = """
    the real 24A435 arm64e shared cache is required — put it at \
    ipsws/ref_extract/dsc_pristine, point VPHONE_DSC_PRISTINE at it, or set \
    VPHONE_DSC_FIXTURE_OPTIONAL=1 to skip these tests instead of failing
    """

    /// Where clones go. Deliberately *not* inside `ipsws/ref_extract`: that
    /// tree is the pristine reference every DSC test compares against, and a
    /// scratch directory next to it is one `rm -rf` typo away from destroying
    /// a 6.7 GB extraction nobody can regenerate quickly.
    static var scratchRoot: URL {
        // Per-suite leaf on BOTH branches: the override is a base shared with
        // the other DSC suites, and they reuse the same clone names.
        let base = ProcessInfo.processInfo.environment["VPHONE_DSC_SCRATCH"]
            .map { URL(fileURLWithPath: $0) }
            ?? URL(fileURLWithPath: NSTemporaryDirectory())
        return base.appendingPathComponent("vphone-dsc-lsd-embedded-reg")
    }

    /// Clone the pristine cache into a fresh directory the caller may write to.
    ///
    /// `cp -c` asks for a `clonefile`, which costs no space and no time when
    /// the scratch root is on the same APFS volume as the fixture. When it is
    /// not — a caller who pointed `VPHONE_DSC_SCRATCH` at another disk — the
    /// clone is refused, and the fallback is an ordinary copy rather than a
    /// failed test.
    static func cloneCache(named name: String) throws -> URL {
        let pristine = try #require(self.pristine, missing)
        let destination = scratchRoot.appendingPathComponent(name)
        try? FileManager.default.removeItem(at: destination)
        try FileManager.default.createDirectory(
            at: destination,
            withIntermediateDirectories: true,
        )
        let entries = try FileManager.default
            .contentsOfDirectory(atPath: pristine.path)
            .sorted()
            .map { pristine.appendingPathComponent($0).path }

        for flags in [["-c", "-R"], ["-R"]] {
            let result = try Shell.run(
                executable: URL(fileURLWithPath: "/bin/cp"),
                arguments: flags + entries + [destination.path],
            )
            if result.status == 0 {
                return destination
            }
        }
        Issue.record("could not clone the pristine cache into \(destination.path)")
        throw CocoaError(.fileWriteUnknown)
    }

    /// Discard clones, and the scratch root with them once the last one is
    /// gone, so a test run leaves the filesystem as it found it.
    static func discard(_ clones: URL...) {
        for clone in clones {
            try? FileManager.default.removeItem(at: clone)
        }
        let remaining = (try? FileManager.default
            .contentsOfDirectory(atPath: scratchRoot.path)) ?? []
        if remaining.isEmpty {
            try? FileManager.default.removeItem(at: scratchRoot)
        }
    }
}

// MARK: - Subprocess helper

private enum Shell {
    struct Result {
        let status: Int32
        let stdout: String
        let stderr: String
    }

    @discardableResult
    static func run(
        executable: URL,
        arguments: [String],
        currentDirectory: URL? = nil,
    ) throws -> Result {
        let process = Process()
        process.executableURL = executable
        process.arguments = arguments
        if let currentDirectory {
            process.currentDirectoryURL = currentDirectory
        }
        let out = Pipe()
        let err = Pipe()
        process.standardOutput = out
        process.standardError = err
        try process.run()
        let outData = out.fileHandleForReading.readDataToEndOfFile()
        let errData = err.fileHandleForReading.readDataToEndOfFile()
        process.waitUntilExit()
        return Result(
            status: process.terminationStatus,
            stdout: String(decoding: outData, as: UTF8.self),
            stderr: String(decoding: errData, as: UTF8.self),
        )
    }
}

// MARK: - Digests

/// SHA-256 of a cache chunk, streamed so a 131 MB file never lands in memory
/// whole. The hex spelling matches `shasum -a 256`, which is what produced the
/// frozen digests.
private enum Digest {
    static func sha256(of url: URL) throws -> String {
        let handle = try FileHandle(forReadingFrom: url)
        defer { try? handle.close() }
        var hasher = SHA256()
        while let block = try handle.read(upToCount: 4 << 20), !block.isEmpty {
            hasher.update(data: block)
        }
        return hasher.finalize().map { String(format: "%02x", $0) }.joined()
    }
}

// MARK: - Byte-for-byte cache comparison

private enum CacheComparison {
    /// Every file name that differs between two cache directories.
    ///
    /// `cmp -s` rather than loading 6.7 GB into memory twice; file names are
    /// compared first so a missing or extra chunk is reported as such.
    static func differences(between lhs: URL, and rhs: URL) throws -> [String] {
        let manager = FileManager.default
        let left = try Set(manager.contentsOfDirectory(atPath: lhs.path))
        let right = try Set(manager.contentsOfDirectory(atPath: rhs.path))
        var differing = Array(left.symmetricDifference(right)).sorted()

        for name in left.intersection(right).sorted() {
            let result = try Shell.run(
                executable: URL(fileURLWithPath: "/usr/bin/cmp"),
                arguments: [
                    "-s",
                    lhs.appendingPathComponent(name).path,
                    rhs.appendingPathComponent(name).path,
                ],
            )
            if result.status != 0 {
                differing.append(name)
            }
        }
        return differing.sorted()
    }

    /// How many chunk files differ from the pristine tree.
    static func changedFiles(in directory: URL) throws -> [String] {
        let pristine = try #require(LSDRegFixture.pristine, LSDRegFixture.missing)
        return try differences(between: pristine, and: directory)
    }
}

// MARK: - Gate discovery

@Suite(
    "DSC lsd embedded-registration gate",
    .enabled(if: LSDRegFixture.runs, LSDRegFixture.missing),
    .serialized,
)
struct DyldSharedCacheLSDEmbeddedRegGateTests {
    @Test
    func `the gate is a cbz/cbnz on w0 whose fall-through sets a w register to 1`() throws {
        let pristine = try #require(LSDRegFixture.pristine, LSDRegFixture.missing)
        let chunks = try DyldSharedCacheChunkSet(directory: pristine)
        let located = try #require(
            try DyldSharedCacheLSDEmbeddedRegPatcher.locateGate(in: chunks),
            "the iOS 27 fixture must carry \(DyldSharedCacheLSDEmbeddedRegPatcher.method)",
        )

        #expect(["cbz", "cbnz"].contains(located.gate.mnemonic))
        #expect(!located.gate.wasAlreadyNOP)
        #expect(located.gate.resultRegister.hasPrefix("w"))
        #expect(located.gate.vma > located.functionVMA)
        // The gate is inside the disassembly window, by construction.
        #expect(
            located.gate.vma
                < located.functionVMA + UInt64(DyldSharedCacheLSDEmbeddedRegPatcher.maxInstructions * 4),
        )

        // …and it is the exact site the reference Python reported.
        #expect(located.functionVMA == FrozenReference.methodVMA)
        #expect(located.gate.vma == FrozenReference.gateVMA)
        #expect(located.gate.mnemonic == FrozenReference.gateMnemonic)
        #expect(located.gate.resultRegister == FrozenReference.gateResultRegister)
    }

    @Test
    func `the symbol resolves through the cache's own local symbol table`() throws {
        let pristine = try #require(LSDRegFixture.pristine, LSDRegFixture.missing)
        let chunks = try DyldSharedCacheChunkSet(directory: pristine)
        let address = try #require(
            try chunks.resolveLocalSymbol(DyldSharedCacheLSDEmbeddedRegPatcher.method),
            "\(DyldSharedCacheLSDEmbeddedRegPatcher.method) must be in the .symbols table",
        )
        #expect(address == FrozenReference.methodVMA)
        // It has to live in an executable mapping, or it is not the method.
        let mapping = try #require(chunks.mapping(forVMA: address))
        #expect(mapping.isExecutable)
    }
}

// MARK: - Parity against the frozen reference

@Suite(
    "DSC lsd embedded-registration parity",
    .enabled(if: LSDRegFixture.runs, LSDRegFixture.missing),
    .serialized,
)
struct DyldSharedCacheLSDEmbeddedRegParityTests {
    @Test
    func `Swift reproduces the reference cache byte for byte, one site`() throws {
        let swiftClone = try LSDRegFixture.cloneCache(named: "swift")
        defer { LSDRegFixture.discard(swiftClone) }

        let report = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(
            chunksDirectory: swiftClone,
            log: nil,
        )
        #expect(report.outcome == .patched)
        #expect(report.sitesWritten == FrozenReference.sitesWritten)
        #expect(report.methodIsPresent)
        #expect(report.gate?.vma == FrozenReference.gateVMA)

        // Exactly the chunk the Python moved, and to exactly the same bytes.
        let changed = try CacheComparison.changedFiles(in: swiftClone)
        #expect(changed == FrozenReference.changedChunks.keys.sorted())
        for name in changed {
            let digest = try Digest.sha256(of: swiftClone.appendingPathComponent(name))
            let frozen = FrozenReference.changedChunks[name] ?? "(not a chunk the Python moved)"
            #expect(digest == frozen, "\(name): Swift \(digest), reference \(frozen)")
        }
    }

    @Test
    func `the recorded write names the chunk, its offset and the gate address`() throws {
        let clone = try LSDRegFixture.cloneCache(named: "record")
        defer { LSDRegFixture.discard(clone) }

        let report = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(chunksDirectory: clone, log: nil)
        let record = try #require(report.record)
        let gate = try #require(report.gate)

        #expect(record.patchID == DyldSharedCacheLSDEmbeddedRegPatcher.patchID)
        #expect(record.component.hasPrefix("dyld_shared_cache_arm64e"))
        #expect(record.virtualAddress == gate.vma)
        #expect(record.patchedBytes == ARM64.nop)
        #expect(record.originalBytes != ARM64.nop)
        #expect(record.originalBytes.count == 4)
        #expect(record.afterDisasm == "nop")
        #expect(record.beforeDisasm.hasPrefix(gate.mnemonic))

        // The bytes on both sides are the pair the Python printed.
        #expect(record.originalBytes == FrozenReference.originalBytes)
        #expect(record.patchedBytes == FrozenReference.patchedBytes)
        #expect(record.virtualAddress == FrozenReference.gateVMA)

        // The offset has to name the byte that changed, in the file it names.
        let handle = try FileHandle(
            forReadingFrom: clone.appendingPathComponent(record.component),
        )
        defer { try? handle.close() }
        try handle.seek(toOffset: UInt64(record.fileOffset))
        #expect(try handle.read(upToCount: 4) == ARM64.nop)
    }
}

// MARK: - Re-runs and dry runs

@Suite(
    "DSC lsd embedded-registration re-runs",
    .enabled(if: LSDRegFixture.runs, LSDRegFixture.missing),
    .serialized,
)
struct DyldSharedCacheLSDEmbeddedRegRerunTests {
    @Test
    func `a second Swift run is idempotent and leaves the bytes alone`() throws {
        let clone = try LSDRegFixture.cloneCache(named: "idempotent")
        defer { LSDRegFixture.discard(clone) }

        let first = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(chunksDirectory: clone, log: nil)
        #expect(first.outcome == .patched)
        let afterFirst = try CacheComparison.changedFiles(in: clone)

        let second = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(chunksDirectory: clone, log: nil)
        #expect(second.outcome == .alreadyPatched)
        #expect(second.sitesWritten == 0)
        #expect(second.gate?.wasAlreadyNOP == true)
        #expect(second.gate?.vma == first.gate?.vma)

        #expect(try CacheComparison.changedFiles(in: clone) == afterFirst)
        // The reference was idempotent across runs too, so a second Swift pass
        // has to leave the frozen digests standing.
        for name in afterFirst {
            #expect(
                try Digest.sha256(of: clone.appendingPathComponent(name))
                    == FrozenReference.changedChunks[name],
            )
        }
    }

    @Test
    func `a dry run locates the gate and writes nothing`() throws {
        let clone = try LSDRegFixture.cloneCache(named: "dryrun")
        defer { LSDRegFixture.discard(clone) }

        let report = try DyldSharedCacheLSDEmbeddedRegPatcher.patch(
            chunksDirectory: clone,
            dryRun: true,
            log: nil,
        )
        #expect(report.outcome == .wouldPatch)
        #expect(report.sitesWritten == 0)
        #expect(report.gate?.vma == FrozenReference.gateVMA)
        // The reference dry run wrote nothing either.
        #expect(try CacheComparison.changedFiles(in: clone).isEmpty)
    }
}