Verify Downloaded AI Models on iOS Before Activation

Quick Answer

Download large model assets to files, validate them against trusted release metadata, and activate only a complete compatible candidate. Use CryptoKit to hash the file incrementally instead of loading the entire model into memory. Keep a known working version until the replacement has passed your runtime checks. Transfer completion, integrity verification, and activation are separate states.

Requirements

Use Xcode 15 or later, Swift 5.9 or later, and an iOS 17 or later app target. The validation example uses Foundation and CryptoKit. Tests use XCTest. The example is a local validation boundary, not a complete background download manager, model loader, or signed-manifest implementation.

Use This Pattern When

• Your app downloads its own large model rather than relying on a system-managed model.
• A failed update must leave the current model usable.
• You need to distinguish corrupt bytes from an incompatible model format.
• Your release process can supply trusted file length and SHA-256 metadata.

A small bundled asset may not need a separate downloader. Do not use this example to manage Apple's system model installation.

Implementation

1. Define an immutable release identity

Keep a versioned URL, byte count, checksum, format, and minimum supported runtime in the release metadata. Publish the file and metadata as a coordinated release. Avoid changing bytes behind a released URL.

The expected checksum must come from a trusted source. A digest obtained beside a compromised file does not authenticate that file. Your application must separately validate the manifest's origin and any signature scheme your threat model requires.

2. Keep the transfer separate from validation

Use URLSession download tasks for file transfers. Apple's background download documentation covers recreating a session with its stable identifier and preserving the temporary downloaded file. Move that temporary result into an app-owned staging location during the download callback, before returning.

Reject an unexpected HTTP response before considering the candidate installable. A successful HTTP status can still contain an HTML error page, so status alone is insufficient. Treat resumability as a recovery aid rather than a guarantee; see Apple's pause and resume guidance.

3. Validate in bounded chunks

This synchronous helper reads at most one chunk at a time. Call it from a dedicated non-main execution context. Wrapping synchronous work in an actor-inheriting Task from a SwiftUI view does not itself move that work off the main actor.

import Foundation
import CryptoKit

enum ModelFileError: Error {
    case invalidExpectedSize
    case sizeMismatch
    case digestMismatch
}

func verifyModelFile(
    at url: URL,
    expectedBytes: Int64,
    expectedSHA256: String
) throws {
    guard expectedBytes > 0 else {
        throw ModelFileError.invalidExpectedSize
    }
    let handle = try FileHandle(forReadingFrom: url)
    defer { try? handle.close() }

    var hasher = SHA256()
    var bytesRead: Int64 = 0
    while true {
        try Task.checkCancellation()
        let chunk = try handle.read(upToCount: 1_048_576) ?? Data()
        if chunk.isEmpty { break }
        bytesRead += Int64(chunk.count)
        guard bytesRead <= expectedBytes else {
            throw ModelFileError.sizeMismatch
        }
        hasher.update(data: chunk)
    }
    guard bytesRead == expectedBytes else {
        throw ModelFileError.sizeMismatch
    }
    let actual = hasher.finalize()
        .map { String(format: "%02x", $0) }
        .joined()
    guard actual == expectedSHA256.lowercased() else {
        throw ModelFileError.digestMismatch
    }
}

This bounds the hashing buffer, not the memory your model runtime will later allocate. Validate manifest syntax separately, including the digest's length and allowed characters. Keep the staged file under the installer's exclusive control while validating and activating it, so another operation cannot replace it between those steps.

4. Commit only a verified installation

Write the candidate into a version-specific directory. Run the relevant format and runtime compatibility checks after the byte check. A checksum match cannot prove that the runtime can load the model.

Persist a small active-version record only after the candidate is ready. Make that record replacement atomic and serialize installation changes. On launch, reconcile the record with actual files; recover if either is missing. Keep the previous version according to a defined rollback policy, then clean abandoned candidates without deleting the active one.

A cancelled transfer should not change the active-version record. Neither should failed verification. These are installation invariants worth testing independently of the network.

Testing

Place this test beside the helper in a test target, or import your app module to access the helper. The small fixture deliberately corrupts bytes without changing their length, proving that a length-only check would miss the failure.

import Foundation
import XCTest

final class ModelFileValidationTests: XCTestCase {
    func testAcceptsKnownBytesAndRejectsSameSizeCorruption() throws {
        let url = FileManager.default.temporaryDirectory
            .appendingPathComponent(UUID().uuidString)
        defer { try? FileManager.default.removeItem(at: url) }
        let digest = "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"

        try Data("abc".utf8).write(to: url)
        XCTAssertNoThrow(try verifyModelFile(
            at: url, expectedBytes: 3, expectedSHA256: digest
        ))
        try Data("abd".utf8).write(to: url)
        XCTAssertThrowsError(try verifyModelFile(
            at: url, expectedBytes: 3, expectedSHA256: digest
        )) { error in
            guard case ModelFileError.digestMismatch = error else {
                return XCTFail("Expected a digest mismatch, got \(error)")
            }
        }
    }
}

Extend coverage with a truncated file, an oversized file, missing file access, cancellation, and an app restart between staging and activation. In installer tests, assert that the active version stays unchanged after each failed candidate. Test real transfers on devices; the helper test makes no claim about background execution or network recovery.

Common Mistakes

• Loading a multi-gigabyte model into a single Data value to compute its hash.
• Treating a finished progress bar as a usable model.
• Deleting the previous version before the replacement passes checks.
• Assuming a checksum authenticates an untrusted manifest.
• Updating the active pointer before persisting the candidate. This crash window is easy to miss in a successful-install demo.

Production Checklist

• Use immutable release URLs and trusted compatibility metadata.
• Preserve the temporary download before its callback returns.
• Check the HTTP response and file contents independently.
• Budget space for staging and any retained previous version.
• Keep hashing and loading off the main actor.
• Expose distinct downloading, verifying, ready, and retry states accessibly.
• Keep prompts and documents out of transfer diagnostics.
• Verify offline launch after a successful installation and after a failed update.

Related

• Model delivery decisions before launch
• Background tasks in production
• Integrating Core ML into an existing app
• ECHO, a 3NSOFTS product using downloadable on-device model assets; this guide is an illustrative implementation, not its source code.

References

• Apple: Downloading files in the background
• Apple: Pausing and resuming downloads
• Apple: CryptoKit SHA256