@onekeyfe/react-native-range-downloader 3.0.81-alpha.1 → 3.0.81-alpha.11

package/ios/FirmwareArtifactStore.swift

@@ -1,13 +1,32 @@
 import CryptoKit
 import Foundation
-import SniConnect
-
-enum FirmwareArtifactStoreError: Error {
-  case invalidInput(String)
-  case downloadFailed(String)
-  case integrityMismatch(String)
-  case readerInvalid(String)
-  case archiveInvalid(String)
+import ReactNativeNativeLogger
+
+func isFirmwareArtifactTLSError(_ error: Error) -> Bool {
+  var current: NSError? = error as NSError
+  var visited = Set<ObjectIdentifier>()
+  while let candidate = current {
+    let identifier = ObjectIdentifier(candidate)
+    guard visited.insert(identifier).inserted else {
+      break
+    }
+    if candidate.domain == NSURLErrorDomain,
+      [
+        NSURLErrorSecureConnectionFailed,
+        NSURLErrorServerCertificateHasBadDate,
+        NSURLErrorServerCertificateUntrusted,
+        NSURLErrorServerCertificateHasUnknownRoot,
+        NSURLErrorServerCertificateNotYetValid,
+        NSURLErrorClientCertificateRejected,
+        NSURLErrorClientCertificateRequired,
+        NSURLErrorAppTransportSecurityRequiresSecureConnection,
+      ].contains(candidate.code)
+    {
+      return true
+    }
+    current = candidate.userInfo[NSUnderlyingErrorKey] as? NSError
+  }
+  return false
 }
 
 struct StoredFirmwareArtifact: Sendable {
@@ -29,7 +48,106 @@ private struct StagedFirmwareArchiveEntry {
   let stagingURL: URL
 }
 
-private final class FirmwareArtifactRedirectDelegate: NSObject, URLSessionTaskDelegate {
+private struct FirmwareArchiveRequirement {
+  let entryName: String
+  let expectedSize: Int64
+  let expectedSha256: String?
+}
+
+private final class FirmwareArtifactStreamDelegate: NSObject, URLSessionDataDelegate {
+  private let partialURL: URL
+  private let hostname: String
+  private let resumeOffset: Int64
+  private let expectedSize: Int64?
+  private let maxBytes: Int64
+  private let isCancelled: () -> Bool
+  private let stateLock = NSLock()
+  private var continuation: CheckedContinuation<Void, Error>?
+  private var dataTask: URLSessionDataTask?
+  private var cancellationRequested = false
+  private var completed = false
+  private var responseAccepted = false
+  private var handle: FileHandle?
+  private var written: Int64 = 0
+
+  init(
+    partialURL: URL,
+    hostname: String,
+    resumeOffset: Int64,
+    expectedSize: Int64?,
+    maxBytes: Int64,
+    isCancelled: @escaping () -> Bool
+  ) {
+    self.partialURL = partialURL
+    self.hostname = hostname
+    self.resumeOffset = resumeOffset
+    self.expectedSize = expectedSize
+    self.maxBytes = maxBytes
+    self.isCancelled = isCancelled
+  }
+
+  func run(session: URLSession, request: URLRequest) async throws {
+    try await withTaskCancellationHandler {
+      try await withCheckedThrowingContinuation {
+        (continuation: CheckedContinuation<Void, Error>) in
+        let task = session.dataTask(with: request)
+        stateLock.lock()
+        if cancellationRequested || completed {
+          stateLock.unlock()
+          task.cancel()
+          continuation.resume(throwing: CancellationError())
+          return
+        }
+        self.continuation = continuation
+        dataTask = task
+        stateLock.unlock()
+        task.resume()
+      }
+    } onCancel: {
+      self.cancel()
+    }
+  }
+
+  private func cancel() {
+    stateLock.lock()
+    cancellationRequested = true
+    let task = dataTask
+    stateLock.unlock()
+    task?.cancel()
+  }
+
+  private func finish(_ result: Result<Void, Error>) {
+    stateLock.lock()
+    guard !completed else {
+      stateLock.unlock()
+      return
+    }
+    completed = true
+    let continuation = continuation
+    self.continuation = nil
+    dataTask = nil
+    let handle = handle
+    self.handle = nil
+    stateLock.unlock()
+
+    try? handle?.close()
+    continuation?.resume(with: result)
+  }
+
+  private func reject(
+    _ dataTask: URLSessionDataTask,
+    completionHandler: @escaping (URLSession.ResponseDisposition) -> Void,
+    message: String
+  ) {
+    completionHandler(.cancel)
+    fail(dataTask, message: message)
+  }
+
+  private func fail(_ task: URLSessionTask, message: String) {
+    task.cancel()
+    finish(.failure(FirmwareArtifactStoreError.downloadFailed(message)))
+  }
+
   func urlSession(
     _ session: URLSession,
     task: URLSessionTask,
@@ -38,6 +156,193 @@ private final class FirmwareArtifactRedirectDelegate: NSObject, URLSessionTaskDe
     completionHandler: @escaping (URLRequest?) -> Void
   ) {
     completionHandler(nil)
+    fail(
+      task,
+      message:
+        "ARTIFACT_REDIRECT_REJECTED: firmware response changed canonical identity"
+    )
+  }
+
+  func urlSession(
+    _ session: URLSession,
+    dataTask: URLSessionDataTask,
+    didReceive response: URLResponse,
+    completionHandler: @escaping (URLSession.ResponseDisposition) -> Void
+  ) {
+    guard !isCancelled() else {
+      reject(
+        dataTask,
+        completionHandler: completionHandler,
+        message: "ARTIFACT_CANCELLED: firmware artifact download was cancelled"
+      )
+      return
+    }
+    guard let httpResponse = response as? HTTPURLResponse else {
+      reject(
+        dataTask,
+        completionHandler: completionHandler,
+        message: "Firmware response is not HTTP"
+      )
+      return
+    }
+    guard
+      let responseURL = httpResponse.url,
+      responseURL.scheme?.lowercased() == "https",
+      responseURL.host?.lowercased() == hostname.lowercased(),
+      responseURL.port == nil || responseURL.port == 443
+    else {
+      reject(
+        dataTask,
+        completionHandler: completionHandler,
+        message:
+          "ARTIFACT_REDIRECT_REJECTED: firmware response changed canonical identity"
+      )
+      return
+    }
+    guard httpResponse.statusCode == 200 || httpResponse.statusCode == 206 else {
+      reject(
+        dataTask,
+        completionHandler: completionHandler,
+        message:
+          "ARTIFACT_HTTP_\(httpResponse.statusCode): firmware request failed"
+      )
+      return
+    }
+
+    let append = resumeOffset > 0 && httpResponse.statusCode == 206
+    if httpResponse.statusCode == 206 {
+      guard
+        let contentRange = httpResponse.value(
+          forHTTPHeaderField: "Content-Range"
+        ),
+        firmwareArtifactContentRangeIsValid(
+          contentRange,
+          expectedStart: append ? resumeOffset : 0,
+          expectedTotal: expectedSize,
+          maxBytes: maxBytes
+        )
+      else {
+        reject(
+          dataTask,
+          completionHandler: completionHandler,
+          message:
+            "ARTIFACT_PROTOCOL_INVALID: firmware resume Content-Range is invalid"
+        )
+        return
+      }
+    }
+
+    let baseOffset = append ? resumeOffset : 0
+    guard
+      firmwareArtifactResponseFits(
+        expectedContentLength: httpResponse.expectedContentLength,
+        baseOffset: baseOffset,
+        maxBytes: maxBytes
+      )
+    else {
+      reject(
+        dataTask,
+        completionHandler: completionHandler,
+        message:
+          "ARTIFACT_PROTOCOL_INVALID: firmware artifact exceeds maxBytes"
+      )
+      return
+    }
+
+    do {
+      let handle = try FileHandle(forWritingTo: partialURL)
+      if append {
+        try handle.seekToEnd()
+      } else {
+        try handle.truncate(atOffset: 0)
+      }
+      self.handle = handle
+      written = baseOffset
+      responseAccepted = true
+      completionHandler(.allow)
+    } catch {
+      reject(
+        dataTask,
+        completionHandler: completionHandler,
+        message:
+          "ARTIFACT_NETWORK_FAILED: firmware partial file could not be opened"
+      )
+    }
+  }
+
+  func urlSession(
+    _ session: URLSession,
+    dataTask: URLSessionDataTask,
+    didReceive data: Data
+  ) {
+    guard responseAccepted, let handle else {
+      fail(
+        dataTask,
+        message:
+          "ARTIFACT_PROTOCOL_INVALID: firmware response stream was not accepted"
+      )
+      return
+    }
+    guard !isCancelled() else {
+      fail(
+        dataTask,
+        message: "ARTIFACT_CANCELLED: firmware artifact download was cancelled"
+      )
+      return
+    }
+    guard
+      firmwareArtifactResponseFits(
+        expectedContentLength: Int64(data.count),
+        baseOffset: written,
+        maxBytes: maxBytes
+      )
+    else {
+      fail(
+        dataTask,
+        message:
+          "ARTIFACT_PROTOCOL_INVALID: firmware artifact exceeds maxBytes"
+      )
+      return
+    }
+    do {
+      try handle.write(contentsOf: data)
+      written += Int64(data.count)
+    } catch {
+      fail(
+        dataTask,
+        message:
+          "ARTIFACT_NETWORK_FAILED: firmware response stream could not be persisted"
+      )
+    }
+  }
+
+  func urlSession(
+    _ session: URLSession,
+    task: URLSessionTask,
+    didCompleteWithError error: Error?
+  ) {
+    if let error {
+      finish(.failure(error))
+      return
+    }
+    guard responseAccepted, let handle else {
+      finish(
+        .failure(FirmwareArtifactStoreError.downloadFailed(
+          "ARTIFACT_PROTOCOL_INVALID: firmware response stream was not accepted"
+        ))
+      )
+      return
+    }
+    do {
+      try handle.synchronize()
+      finish(.success(()))
+    } catch {
+      finish(
+        .failure(FirmwareArtifactStoreError.downloadFailed(
+          "ARTIFACT_NETWORK_FAILED: firmware partial file could not be synchronized"
+        ))
+      )
+    }
   }
 }
 
@@ -78,11 +383,10 @@ private actor FirmwareArtifactDownloadCoordinator {
 
 final class FirmwareArtifactStore {
   static let shared = FirmwareArtifactStore()
-  static let maxReadBytes = 256 * 1024
-  private static let maxLeaseMetadataBytes: Int64 = 1024 * 1024
-  private static let maxTotalLeaseRefs = 8192
-  private static let finalArtifactGrace: TimeInterval = 24 * 60 * 60
-  private static let partialArtifactGrace: TimeInterval = 7 * 24 * 60 * 60
+  static let maxReadBytes = Int(firmwareArtifactMaxReadBytes)
+  static let maxArtifactBytes = firmwareArtifactMaxBytes
+  private static let defaultDownloadDeadline: TimeInterval = 180
+  private static let maxDownloadDeadline: TimeInterval = 24 * 60 * 60
 
   private struct OpenReader {
     let handle: FileHandle
@@ -90,16 +394,11 @@ final class FirmwareArtifactStore {
     let size: Int64
   }
 
-  private struct LeaseState: Codable {
+  private struct LeaseState {
     let transactionId: String
     var artifactRefs: Set<String>
   }
 
-  private struct LeaseEnvelope: Codable {
-    let schemaVersion: Int
-    var leases: [String: LeaseState]
-  }
-
   private let fileManager = FileManager.default
   private let downloadCoordinator = FirmwareArtifactDownloadCoordinator()
   private let leaseLock = NSLock()
@@ -109,6 +408,7 @@ final class FirmwareArtifactStore {
   private var cancelledTransactions: Set<String> = []
   private let readerLock = NSLock()
   private var readers: [String: OpenReader] = [:]
+  private var leases: [String: LeaseState] = [:]
 
   private lazy var rootURL: URL = {
     let base = fileManager.urls(
@@ -122,7 +422,16 @@ final class FirmwareArtifactStore {
 
   private init() {}
 
-  static func validateDownloadParams(_ params: FirmwareArtifactDownloadParams) throws {
+  private struct ValidatedDownload {
+    let expectedSize: Int64?
+    let expectedSha256: String?
+    let maxBytes: Int64
+    let downloadToken: String
+  }
+
+  private static func validateDownloadParams(
+    _ params: FirmwareArtifactDownloadParams
+  ) throws -> ValidatedDownload {
     guard
       !params.taskId.isEmpty,
       params.taskId.count <= 100,
@@ -150,47 +459,92 @@ final class FirmwareArtifactStore {
     else {
       throw FirmwareArtifactStoreError.invalidInput("Firmware URL must use HTTPS port 443")
     }
-    guard
-      params.expectedSize.isFinite,
-      params.expectedSize > 0,
-      params.expectedSize <= Double(Int64.max),
-      params.expectedSize.rounded() == params.expectedSize,
-      params.maxBytes.isFinite,
-      params.maxBytes == params.expectedSize,
-      params.maxBytes <= Double(512 * 1024 * 1024)
-    else {
+    let expectedSize: Int64?
+    if let value = params.expectedSize {
+      guard let converted = firmwareArtifactExactInt64(
+        value,
+        minimum: 1,
+        maximum: Self.maxArtifactBytes
+      ) else {
+        throw FirmwareArtifactStoreError.invalidInput(
+          "Invalid firmware artifact expected size"
+        )
+      }
+      expectedSize = converted
+    } else {
+      expectedSize = nil
+    }
+    guard let maxBytes = firmwareArtifactExactInt64(
+      params.maxBytes,
+      minimum: 1,
+      maximum: Self.maxArtifactBytes
+    ) else {
       throw FirmwareArtifactStoreError.invalidInput("Invalid firmware artifact size")
     }
-    guard params.expectedSha256.range(
-      of: "^[a-fA-F0-9]{64}$",
-      options: .regularExpression
-    ) != nil else {
-      throw FirmwareArtifactStoreError.invalidInput("Invalid firmware artifact SHA-256")
+    guard expectedSize.map({ $0 <= maxBytes }) ?? true else {
+      throw FirmwareArtifactStoreError.invalidInput(
+        "Firmware artifact expected size exceeds maxBytes"
+      )
+    }
+    let expectedSha256 = params.expectedSha256?.lowercased()
+    if let expectedSha256 {
+      guard expectedSha256.range(
+        of: "^[a-f0-9]{64}$",
+        options: .regularExpression
+      ) != nil else {
+        throw FirmwareArtifactStoreError.invalidInput(
+          "Invalid firmware artifact SHA-256"
+        )
+      }
     }
-    guard params.routeType == "domain" || params.routeType == "pinnedIp" else {
+    guard params.routeType == "domain" else {
       throw FirmwareArtifactStoreError.invalidInput("Invalid firmware route type")
     }
-    if params.routeType == "pinnedIp" {
-      guard let resolvedIp = params.resolvedIp, !resolvedIp.isEmpty else {
-        throw FirmwareArtifactStoreError.invalidInput("Pinned route requires resolvedIp")
-      }
-    } else if params.resolvedIp != nil {
+    let deadline = params.overallDeadlineSeconds ?? defaultDownloadDeadline
+    guard
+      deadline.isFinite,
+      deadline > 0,
+      deadline <= maxDownloadDeadline
+    else {
+      throw FirmwareArtifactStoreError.invalidInput("Invalid firmware download deadline")
+    }
+    if params.resolvedIp != nil {
       throw FirmwareArtifactStoreError.invalidInput("Domain route must not include resolvedIp")
     }
+    return ValidatedDownload(
+      expectedSize: expectedSize,
+      expectedSha256: expectedSha256,
+      maxBytes: maxBytes,
+      downloadToken: firmwareArtifactDownloadToken(
+        expectedSha256: expectedSha256,
+        url: params.url
+      )
+    )
   }
 
   func download(_ params: FirmwareArtifactDownloadParams) async throws -> StoredFirmwareArtifact {
-    try Self.validateDownloadParams(params)
+    let validated = try Self.validateDownloadParams(params)
     try rejectIfCancelled(transactionId: params.transactionId)
-    let expectedSha256 = params.expectedSha256.lowercased()
-    try retainExpectedArtifact(
-      leaseRef: params.leaseRef,
+    if let expectedSha256 = validated.expectedSha256 {
+      try retainExpectedArtifact(
+        leaseRef: params.leaseRef,
+        transactionId: params.transactionId,
+        artifactRef: "fw:\(expectedSha256)"
+      )
+    } else {
+      try requireLeaseTransaction(
+        leaseRef: params.leaseRef,
+        transactionId: params.transactionId
+      )
+    }
+    let key = firmwareArtifactDownloadKey(
       transactionId: params.transactionId,
-      artifactRef: "fw:\(expectedSha256)"
+      taskId: params.taskId,
+      expectedSize: validated.expectedSize,
+      expectedSha256: validated.expectedSha256,
+      downloadToken: validated.downloadToken
     )
-    let key =
-      "\(params.transactionId):\(expectedSha256):\(Int64(params.expectedSize))"
-    markDownloadActive(expectedSha256, delta: 1)
+    markDownloadActive(validated.downloadToken, delta: 1)
     do {
       let artifact = try await downloadCoordinator.run(
         key: key,
@@ -199,13 +553,23 @@ final class FirmwareArtifactStore {
         try rejectIfCancelled(transactionId: params.transactionId)
         return try await downloadLocked(
           params,
-          expectedSha256: expectedSha256
+          validated: validated
         )
       }
-      markDownloadActive(expectedSha256, delta: -1)
+      try rejectIfCancelled(transactionId: params.transactionId)
+      try retainExpectedArtifact(
+        leaseRef: params.leaseRef,
+        transactionId: params.transactionId,
+        artifactRef: artifact.artifactRef
+      )
+      markDownloadActive(validated.downloadToken, delta: -1)
       return artifact
     } catch {
-      markDownloadActive(expectedSha256, delta: -1)
+      markDownloadActive(validated.downloadToken, delta: -1)
+      OneKeyLog.error(
+        "FirmwareArtifact",
+        "event=download_failed transactionId=\(params.transactionId) artifactId=\(params.artifactId) route=\(params.routeType) errorType=\(String(describing: type(of: error)))"
+      )
       if error is CancellationError ||
         isTransactionCancelled(params.transactionId) {
         throw FirmwareArtifactStoreError.downloadFailed(
@@ -216,6 +580,32 @@ final class FirmwareArtifactStore {
     }
   }
 
+  func cachedArtifact(
+    _ params: FirmwareArtifactDownloadParams
+  ) throws -> StoredFirmwareArtifact? {
+    let validated = try Self.validateDownloadParams(params)
+    try rejectIfCancelled(transactionId: params.transactionId)
+    guard let expectedSha256 = validated.expectedSha256 else {
+      return nil
+    }
+    let finalURL = artifactURL(sha256: expectedSha256)
+    guard let artifact = try? validateDownloadedArtifact(
+      fileURL: finalURL,
+      expectedSize: validated.expectedSize,
+      expectedSha256: expectedSha256,
+      maxBytes: validated.maxBytes
+    ) else {
+      return nil
+    }
+    try retainExpectedArtifact(
+      leaseRef: params.leaseRef,
+      transactionId: params.transactionId,
+      artifactRef: artifact.artifactRef
+    )
+    try rejectIfCancelled(transactionId: params.transactionId)
+    return artifact
+  }
+
   func cancelDownloads(transactionId: String) async throws {
     guard Self.isSafeIdentifier(transactionId) else {
       throw FirmwareArtifactStoreError.invalidInput(
@@ -226,49 +616,55 @@ final class FirmwareArtifactStore {
       cancelledTransactions.insert(transactionId)
     }
     await downloadCoordinator.cancel(transactionId: transactionId)
-    try await RangeDownloader.shared.cancelFirmwareArtifactDownloads(
-      transactionId: transactionId
-    )
   }
 
   private func downloadLocked(
     _ params: FirmwareArtifactDownloadParams,
-    expectedSha256: String
+    validated: ValidatedDownload
   ) async throws -> StoredFirmwareArtifact {
-    let finalURL = artifactURL(sha256: expectedSha256)
-    if let existing = try? validateStoredArtifact(
-      fileURL: finalURL,
-      expectedSize: Int64(params.expectedSize),
-      expectedSha256: expectedSha256
-    ) {
-      return existing
-    }
-
-    if params.routeType == "domain" {
-      return try await RangeDownloader.shared.downloadFirmwareArtifact(
-        params: params
-      )
+    if let expectedSha256 = validated.expectedSha256 {
+      let finalURL = artifactURL(sha256: expectedSha256)
+      if let existing = try? validateDownloadedArtifact(
+        fileURL: finalURL,
+        expectedSize: validated.expectedSize,
+        expectedSha256: expectedSha256,
+        maxBytes: validated.maxBytes
+      ) {
+        return existing
+      }
     }
 
+    // Firmware preflight is foreground-bound, so both routes use the same
+    // cancellable stream instead of waiting on process-owned background tasks.
     let partialURL = rootURL.appendingPathComponent(
-      "\(expectedSha256).\(params.taskId).partial",
+      firmwareArtifactPartialFileName(
+        transactionId: params.transactionId,
+        taskId: params.taskId,
+        downloadToken: validated.downloadToken
+      ),
       isDirectory: false
     )
     if !fileManager.fileExists(atPath: partialURL.path) {
       fileManager.createFile(atPath: partialURL.path, contents: nil)
     }
     var currentSize = try fileSize(partialURL)
-    if currentSize > Int64(params.expectedSize) {
+    if validated.expectedSha256 == nil && currentSize > 0 {
+      try fileManager.removeItem(at: partialURL)
+      fileManager.createFile(atPath: partialURL.path, contents: nil)
+      currentSize = 0
+    } else if currentSize > validated.maxBytes {
       try fileManager.removeItem(at: partialURL)
       fileManager.createFile(atPath: partialURL.path, contents: nil)
       currentSize = 0
     }
-    if currentSize == Int64(params.expectedSize) {
-      if let completed = try? validateStoredArtifact(
+    if let expectedSize = validated.expectedSize, currentSize == expectedSize {
+      if let completed = try? validateDownloadedArtifact(
         fileURL: partialURL,
-        expectedSize: Int64(params.expectedSize),
-        expectedSha256: expectedSha256
+        expectedSize: expectedSize,
+        expectedSha256: validated.expectedSha256,
+        maxBytes: validated.maxBytes
       ) {
+        let finalURL = artifactURL(sha256: completed.sha256)
         try promote(source: partialURL, destination: finalURL)
         return StoredFirmwareArtifact(
           artifactRef: completed.artifactRef,
@@ -282,22 +678,33 @@ final class FirmwareArtifactStore {
       currentSize = 0
     }
 
+    OneKeyLog.info(
+      "FirmwareArtifact",
+      "event=stream_start transactionId=\(params.transactionId) artifactId=\(params.artifactId) route=\(params.routeType) expectedBytes=\(validated.expectedSize ?? -1) resumeBytes=\(currentSize)"
+    )
     try await streamDownload(
       params,
       partialURL: partialURL,
-      resumeOffset: min(currentSize, Int64(params.expectedSize))
+      resumeOffset: min(currentSize, validated.maxBytes),
+      validated: validated
+    )
+    OneKeyLog.info(
+      "FirmwareArtifact",
+      "event=stream_complete transactionId=\(params.transactionId) artifactId=\(params.artifactId) route=\(params.routeType) expectedBytes=\(validated.expectedSize ?? -1)"
     )
     let artifact: StoredFirmwareArtifact
     do {
-      artifact = try validateStoredArtifact(
+      artifact = try validateDownloadedArtifact(
         fileURL: partialURL,
-        expectedSize: Int64(params.expectedSize),
-        expectedSha256: expectedSha256
+        expectedSize: validated.expectedSize,
+        expectedSha256: validated.expectedSha256,
+        maxBytes: validated.maxBytes
       )
     } catch {
       try? fileManager.removeItem(at: partialURL)
       throw error
     }
+    let finalURL = artifactURL(sha256: artifact.sha256)
     try promote(source: partialURL, destination: finalURL)
     return StoredFirmwareArtifact(
       artifactRef: artifact.artifactRef,
@@ -307,67 +714,11 @@ final class FirmwareArtifactStore {
     )
   }
 
-  func acceptBackgroundDownload(
-    temporaryURL: URL,
-    leaseRef: String,
-    transactionId: String,
-    expectedSize: Int64,
-    expectedSha256: String
-  ) throws -> StoredFirmwareArtifact {
-    let normalizedExpectedSha256 = expectedSha256.lowercased()
-    try retainExpectedArtifact(
-      leaseRef: leaseRef,
-      transactionId: transactionId,
-      artifactRef: "fw:\(normalizedExpectedSha256)"
-    )
-    let finalURL = artifactURL(sha256: normalizedExpectedSha256)
-    if let existing = try? validateStoredArtifact(
-      fileURL: finalURL,
-      expectedSize: expectedSize,
-      expectedSha256: normalizedExpectedSha256
-    ) {
-      return existing
-    }
-    let artifact = try validateStoredArtifact(
-      fileURL: temporaryURL,
-      expectedSize: expectedSize,
-      expectedSha256: normalizedExpectedSha256
-    )
-    try promote(source: temporaryURL, destination: finalURL)
-    return StoredFirmwareArtifact(
-      artifactRef: artifact.artifactRef,
-      size: artifact.size,
-      sha256: artifact.sha256,
-      fileURL: finalURL
-    )
-  }
-
-  func storedArtifact(
-    expectedSize: Int64,
-    expectedSha256: String
-  ) throws -> StoredFirmwareArtifact? {
-    let finalURL = artifactURL(sha256: expectedSha256)
-    guard fileManager.fileExists(atPath: finalURL.path) else {
-      return nil
-    }
-    return try validateStoredArtifact(
-      fileURL: finalURL,
-      expectedSize: expectedSize,
-      expectedSha256: expectedSha256
-    )
-  }
-
   func discard(artifactRef: String) throws {
     let fileURL = try resolveArtifactURL(artifactRef)
     leaseLock.lock()
-    let isRetained: Bool
-    do {
-      isRetained = try loadLeasesLocked().leases.values.contains {
-        $0.artifactRefs.contains(artifactRef)
-      }
-    } catch {
-      leaseLock.unlock()
-      throw error
+    let isRetained = leases.values.contains {
+      $0.artifactRefs.contains(artifactRef)
     }
     leaseLock.unlock()
     guard !isRetained else {
@@ -447,7 +798,7 @@ final class FirmwareArtifactStore {
   func materializeArchive(
     leaseRef: String,
     artifactRef: String,
-    expectedEntries: [FirmwareArchiveExpectedEntry]
+    expectedEntries: [FirmwareArchiveExpectedEntry]?
   ) throws -> [StoredFirmwareArchiveEntry] {
     try requireLease(leaseRef)
     let archiveURL = try resolveArtifactURL(artifactRef)
@@ -458,10 +809,13 @@ final class FirmwareArtifactStore {
     try fileManager.createDirectory(at: scratchURL, withIntermediateDirectories: true)
     defer { try? fileManager.removeItem(at: scratchURL) }
 
-    let requirements = try validateArchiveRequirements(expectedEntries)
     let archiveEntries = try FirmwareArchiveMinizipBridge.scanArchive(
       atPath: archiveURL.path
     )
+    let requirements = try resolveArchiveRequirements(
+      expectedEntries,
+      archiveEntries: archiveEntries
+    )
     try validateArchiveEntries(
       archiveEntries,
       requirements: requirements
@@ -488,7 +842,7 @@ final class FirmwareArtifactStore {
           }
           do {
             actualSize += Int64(chunk.count)
-            guard actualSize <= Int64(requirement.expectedSize) else {
+            guard actualSize <= requirement.expectedSize else {
               throw FirmwareArtifactStoreError.archiveInvalid(
                 "Firmware archive entry exceeds its expected size"
               )
@@ -514,8 +868,8 @@ final class FirmwareArtifactStore {
         String(format: "%02x", $0)
       }.joined()
       guard
-        actualSize == Int64(requirement.expectedSize),
-        sha256 == requirement.expectedSha256.lowercased()
+        actualSize == requirement.expectedSize,
+        requirement.expectedSha256.map({ sha256 == $0 }) ?? true
       else {
         throw FirmwareArtifactStoreError.archiveInvalid(
           "Firmware archive entry integrity mismatch"
@@ -566,18 +920,16 @@ final class FirmwareArtifactStore {
     }
     leaseLock.lock()
     defer { leaseLock.unlock() }
-    var envelope = try loadLeasesLocked()
-    guard envelope.leases.count < 32 else {
+    guard leases.count < 32 else {
       throw FirmwareArtifactStoreError.invalidInput(
         "Too many firmware artifact leases"
       )
     }
     let leaseRef = "fwlease:\(UUID().uuidString.lowercased())"
-    envelope.leases[leaseRef] = LeaseState(
+    leases[leaseRef] = LeaseState(
       transactionId: transactionId,
       artifactRefs: []
     )
-    try saveLeasesLocked(envelope)
     return leaseRef
   }
 
@@ -603,9 +955,8 @@ final class FirmwareArtifactStore {
     let transactionId: String = try {
       leaseLock.lock()
       defer { leaseLock.unlock() }
-      var envelope = try loadLeasesLocked()
       guard
-        let lease = envelope.leases.removeValue(
+        let lease = leases.removeValue(
           forKey: try validateLeaseRef(leaseRef)
         )
       else {
@@ -613,7 +964,6 @@ final class FirmwareArtifactStore {
           "Firmware artifact lease is unavailable"
         )
       }
-      try saveLeasesLocked(envelope)
       return lease.transactionId
     }()
     cancellationLock.withFirmwareArtifactLock {
@@ -621,43 +971,13 @@ final class FirmwareArtifactStore {
     }
   }
 
-  func reconcileLeases(activeLeaseRefs: [String]) throws {
-    guard activeLeaseRefs.count <= 32 else {
-      throw FirmwareArtifactStoreError.invalidInput(
-        "Too many active firmware artifact leases"
-      )
-    }
-    let active = try Set(activeLeaseRefs.map(validateLeaseRef))
-    guard active.count == activeLeaseRefs.count else {
-      throw FirmwareArtifactStoreError.invalidInput(
-        "Duplicate active firmware artifact lease"
-      )
-    }
-    leaseLock.lock()
-    defer { leaseLock.unlock() }
-    var envelope = try loadLeasesLocked()
-    guard active.allSatisfy({ envelope.leases[$0] != nil }) else {
-      throw FirmwareArtifactStoreError.invalidInput(
-        "Firmware artifact lease reconciliation is incomplete"
-      )
-    }
-    envelope.leases = envelope.leases.filter { active.contains($0.key) }
-    try saveLeasesLocked(envelope)
-  }
-
   func sweepOrphans() throws -> (deletedFiles: Int, deletedBytes: Int64) {
     leaseLock.lock()
-    let retained: Set<String>
-    do {
-      retained = Set(
-        try loadLeasesLocked().leases.values
-          .flatMap(\.artifactRefs)
-          .map { String($0.dropFirst(3)) }
-      )
-    } catch {
-      leaseLock.unlock()
-      throw error
-    }
+    let retained = Set(
+      leases.values
+        .flatMap(\.artifactRefs)
+        .map { String($0.dropFirst(3)) }
+    )
     leaseLock.unlock()
     activeDownloadLock.lock()
     let active = Set(activeDownloadCounts.filter { $0.value > 0 }.keys)
@@ -666,61 +986,41 @@ final class FirmwareArtifactStore {
     let openPaths = Set(readers.values.map(\.fileURL.path))
     readerLock.unlock()
 
-    let now = Date()
-    var deletedFiles = 0
-    var deletedBytes: Int64 = 0
-    let files = try fileManager.contentsOfDirectory(
-      at: rootURL,
-      includingPropertiesForKeys: [.contentModificationDateKey, .fileSizeKey],
-      options: [.skipsHiddenFiles]
+    return try sweepFirmwareArtifactOrphansAtRoot(
+      rootURL,
+      retainedSha256: retained,
+      activeSha256: active,
+      openPaths: openPaths,
+      fileManager: fileManager
     )
-    for fileURL in files {
-      let name = fileURL.lastPathComponent
-      guard name != "leases.json", name.count >= 64 else { continue }
-      let sha256 = String(name.prefix(64))
-      guard
-        sha256.range(of: "^[a-f0-9]{64}$", options: .regularExpression) != nil,
-        !retained.contains(sha256),
-        !active.contains(sha256),
-        !openPaths.contains(fileURL.path)
-      else {
-        continue
-      }
-      let grace: TimeInterval
-      if name.hasSuffix(".bin") {
-        grace = Self.finalArtifactGrace
-      } else if name.hasSuffix(".partial") {
-        grace = Self.partialArtifactGrace
-      } else {
-        continue
-      }
-      let values = try fileURL.resourceValues(
-        forKeys: [.contentModificationDateKey, .fileSizeKey]
-      )
-      guard
-        let modifiedAt = values.contentModificationDate,
-        now.timeIntervalSince(modifiedAt) >= grace
-      else {
-        continue
-      }
-      let size = Int64(values.fileSize ?? 0)
-      try fileManager.removeItem(at: fileURL)
-      deletedFiles += 1
-      deletedBytes += size
-    }
-    return (deletedFiles, deletedBytes)
   }
 
   private func requireLease(_ leaseRef: String) throws {
     leaseLock.lock()
     defer { leaseLock.unlock() }
-    guard try loadLeasesLocked().leases[validateLeaseRef(leaseRef)] != nil else {
+    guard leases[try validateLeaseRef(leaseRef)] != nil else {
       throw FirmwareArtifactStoreError.invalidInput(
         "Firmware artifact lease is unavailable"
       )
     }
   }
 
+  private func requireLeaseTransaction(
+    leaseRef: String,
+    transactionId: String
+  ) throws {
+    leaseLock.lock()
+    defer { leaseLock.unlock() }
+    guard
+      let lease = leases[try validateLeaseRef(leaseRef)],
+      lease.transactionId == transactionId
+    else {
+      throw FirmwareArtifactStoreError.invalidInput(
+        "Firmware artifact lease transaction mismatch"
+      )
+    }
+  }
+
   private func retainExpectedArtifact(
     leaseRef: String,
     transactionId: String?,
@@ -736,9 +1036,8 @@ final class FirmwareArtifactStore {
     }
     leaseLock.lock()
     defer { leaseLock.unlock() }
-    var envelope = try loadLeasesLocked()
     let validatedLeaseRef = try validateLeaseRef(leaseRef)
-    guard var lease = envelope.leases[validatedLeaseRef] else {
+    guard var lease = leases[validatedLeaseRef] else {
       throw FirmwareArtifactStoreError.invalidInput(
         "Firmware artifact lease is unavailable"
       )
@@ -749,8 +1048,7 @@ final class FirmwareArtifactStore {
       )
     }
     if lease.artifactRefs.insert(artifactRef).inserted {
-      envelope.leases[validatedLeaseRef] = lease
-      try saveLeasesLocked(envelope)
+      leases[validatedLeaseRef] = lease
     }
   }
 
@@ -770,84 +1068,8 @@ final class FirmwareArtifactStore {
     ) != nil
   }
 
-  private static func isSafeIdentifier(_ value: String) -> Bool {
-    value.range(
-      of: "^[A-Za-z0-9._:-]{1,160}$",
-      options: .regularExpression
-    ) != nil
-  }
-
-  private func loadLeasesLocked() throws -> LeaseEnvelope {
-    let url = rootURL.appendingPathComponent("leases.json", isDirectory: false)
-    guard fileManager.fileExists(atPath: url.path) else {
-      return LeaseEnvelope(schemaVersion: 1, leases: [:])
-    }
-    let fileSize = try url.resourceValues(forKeys: [.fileSizeKey]).fileSize ?? 0
-    guard fileSize > 0, Int64(fileSize) <= Self.maxLeaseMetadataBytes else {
-      throw FirmwareArtifactStoreError.invalidInput(
-        "Firmware lease metadata is too large"
-      )
-    }
-    let envelope = try JSONDecoder().decode(
-      LeaseEnvelope.self,
-      from: Data(contentsOf: url)
-    )
-    guard envelope.schemaVersion == 1, envelope.leases.count <= 32 else {
-      throw FirmwareArtifactStoreError.invalidInput(
-        "Unsupported firmware lease schema"
-      )
-    }
-    guard
-      envelope.leases.values.reduce(0, { $0 + $1.artifactRefs.count })
-        <= Self.maxTotalLeaseRefs
-    else {
-      throw FirmwareArtifactStoreError.invalidInput(
-        "Firmware lease metadata is too large"
-      )
-    }
-    for (leaseRef, lease) in envelope.leases {
-      guard
-        Self.isValidLeaseRef(leaseRef),
-        Self.isSafeIdentifier(lease.transactionId),
-        lease.artifactRefs.count <= 4096,
-        lease.artifactRefs.allSatisfy({
-          $0.range(
-            of: "^fw:[a-f0-9]{64}$",
-            options: .regularExpression
-          ) != nil
-        })
-      else {
-        throw FirmwareArtifactStoreError.invalidInput(
-          "Invalid persisted firmware lease"
-        )
-      }
-    }
-    return envelope
-  }
-
-  private func saveLeasesLocked(_ envelope: LeaseEnvelope) throws {
-    guard
-      envelope.schemaVersion == 1,
-      envelope.leases.count <= 32,
-      envelope.leases.values.allSatisfy({
-        $0.artifactRefs.count <= 4096
-      }),
-      envelope.leases.values.reduce(0, {
-        $0 + $1.artifactRefs.count
-      }) <= Self.maxTotalLeaseRefs
-    else {
-      throw FirmwareArtifactStoreError.invalidInput(
-        "Firmware lease metadata is too large"
-      )
-    }
-    let data = try JSONEncoder().encode(envelope)
-    guard Int64(data.count) <= Self.maxLeaseMetadataBytes else {
-      throw FirmwareArtifactStoreError.invalidInput(
-        "Firmware lease metadata is too large"
-      )
-    }
-    let url = rootURL.appendingPathComponent("leases.json", isDirectory: false)
-    try data.write(to: url, options: [.atomic])
+  static func isSafeIdentifier(_ value: String) -> Bool {
+    firmwareArtifactIdentifierIsSafe(value)
   }
 
   private func markDownloadActive(_ sha256: String, delta: Int) {
@@ -863,7 +1085,7 @@ final class FirmwareArtifactStore {
 
   private func validateArchiveRequirements(
     _ expectedEntries: [FirmwareArchiveExpectedEntry]
-  ) throws -> [FirmwareArchiveExpectedEntry] {
+  ) throws -> [FirmwareArchiveRequirement] {
     guard !expectedEntries.isEmpty, expectedEntries.count <= 4096 else {
       throw FirmwareArtifactStoreError.archiveInvalid(
         "Firmware archive expected entry count is invalid"
@@ -904,12 +1126,48 @@ final class FirmwareArtifactStore {
         )
       }
     }
-    return expectedEntries
+    return expectedEntries.map {
+      FirmwareArchiveRequirement(
+        entryName: $0.entryName,
+        expectedSize: Int64($0.expectedSize),
+        expectedSha256: $0.expectedSha256.lowercased()
+      )
+    }
+  }
+
+  private func resolveArchiveRequirements(
+    _ expectedEntries: [FirmwareArchiveExpectedEntry]?,
+    archiveEntries: [FirmwareArchiveEntryInfo]
+  ) throws -> [FirmwareArchiveRequirement] {
+    if let expectedEntries {
+      return try validateArchiveRequirements(expectedEntries)
+    }
+    if let issue = firmwareArchiveDiscoveredEntriesIssue(
+      archiveEntries.map(\.name)
+    ) {
+      switch issue {
+      case .empty:
+        throw FirmwareArtifactStoreError.archiveInvalid(
+          "Firmware archive must contain at least one entry"
+        )
+      case .duplicateName:
+        throw FirmwareArtifactStoreError.archiveInvalid(
+          "Firmware archive contains duplicate entry names"
+        )
+      }
+    }
+    return archiveEntries.map {
+      FirmwareArchiveRequirement(
+        entryName: $0.name,
+        expectedSize: $0.uncompressedSize,
+        expectedSha256: nil
+      )
+    }
   }
 
   private func validateArchiveEntries(
     _ entries: [FirmwareArchiveEntryInfo],
-    requirements: [FirmwareArchiveExpectedEntry]
+    requirements: [FirmwareArchiveRequirement]
   ) throws {
     guard entries.count == requirements.count else {
       throw FirmwareArtifactStoreError.archiveInvalid(
@@ -921,16 +1179,32 @@ final class FirmwareArtifactStore {
     )
     var names = Set<String>()
     var canonicalNames = Set<String>()
+    var totalSize: Int64 = 0
     for entry in entries {
+      guard let requirement = requirementsByName[entry.name] else {
+        throw FirmwareArtifactStoreError.archiveInvalid(
+          "Firmware archive contains an unexpected entry"
+        )
+      }
+      let (nextTotalSize, overflowed) = totalSize.addingReportingOverflow(
+        entry.uncompressedSize
+      )
+      guard !overflowed else {
+        throw FirmwareArtifactStoreError.archiveInvalid(
+          "Firmware archive expanded size is invalid"
+        )
+      }
+      totalSize = nextTotalSize
       guard
         names.insert(entry.name).inserted,
         isPortableArchiveEntryName(
           entry.name,
           canonicalNames: &canonicalNames
         ),
-        let requirement = requirementsByName[entry.name],
-        entry.uncompressedSize == Int64(requirement.expectedSize),
+        entry.uncompressedSize == requirement.expectedSize,
         entry.uncompressedSize > 0,
+        entry.uncompressedSize <= 128 * 1024 * 1024,
+        totalSize <= 512 * 1024 * 1024,
         entry.compressedSize >= 0,
         entry.compressedSize <= 512 * 1024 * 1024,
         entry.uncompressedSize <= max(entry.compressedSize, 1) * 1000,
@@ -1001,107 +1275,68 @@ final class FirmwareArtifactStore {
   private func streamDownload(
     _ params: FirmwareArtifactDownloadParams,
     partialURL: URL,
-    resumeOffset: Int64
+    resumeOffset: Int64,
+    validated: ValidatedDownload
+  ) async throws {
+    do {
+      try await FirmwareArtifactWallClockDeadline.run(
+        timeoutSeconds:
+          params.overallDeadlineSeconds ?? Self.defaultDownloadDeadline
+      ) { [self] in
+        try await streamDownloadWithinDeadline(
+          params,
+          partialURL: partialURL,
+          resumeOffset: resumeOffset,
+          validated: validated
+        )
+      }
+    } catch FirmwareArtifactDeadlineError.exceeded {
+      throw FirmwareArtifactStoreError.downloadFailed(
+        "ARTIFACT_DEADLINE_EXCEEDED: firmware download exceeded its deadline"
+      )
+    }
+  }
+
+  private func streamDownloadWithinDeadline(
+    _ params: FirmwareArtifactDownloadParams,
+    partialURL: URL,
+    resumeOffset: Int64,
+    validated: ValidatedDownload
   ) async throws {
     guard let url = URL(string: params.url), let hostname = url.host else {
       throw FirmwareArtifactStoreError.invalidInput("Invalid firmware URL")
     }
     var request = URLRequest(url: url)
     request.cachePolicy = .reloadIgnoringLocalCacheData
-    request.timeoutInterval = params.overallDeadlineSeconds ?? 180
+    request.timeoutInterval =
+      params.overallDeadlineSeconds ?? Self.defaultDownloadDeadline
     request.setValue("identity", forHTTPHeaderField: "Accept-Encoding")
     if resumeOffset > 0 {
       request.setValue("bytes=\(resumeOffset)-", forHTTPHeaderField: "Range")
     }
 
-    let pinnedSession: SniConnectPinnedSession?
-    if params.routeType == "pinnedIp" {
-      pinnedSession = try SniConnectPinnedTransport.makeSession(
-          hostname: hostname,
-          ip: params.resolvedIp!
-        )
-    } else {
-      pinnedSession = nil
-    }
-    let domainDelegate = FirmwareArtifactRedirectDelegate()
-    let session = pinnedSession?.session ?? URLSession(
+    let streamDelegate = FirmwareArtifactStreamDelegate(
+      partialURL: partialURL,
+      hostname: hostname,
+      resumeOffset: resumeOffset,
+      expectedSize: validated.expectedSize,
+      maxBytes: validated.maxBytes,
+      isCancelled: { [weak self] in
+        Task.isCancelled ||
+          self?.isTransactionCancelled(params.transactionId) == true
+      }
+    )
+    let session = URLSession(
       configuration: .ephemeral,
-      delegate: domainDelegate,
+      delegate: streamDelegate,
       delegateQueue: nil
     )
     defer {
-      if let pinnedSession {
-        pinnedSession.close()
-      } else {
-        session.finishTasksAndInvalidate()
-      }
-    }
-
-    let bytes: URLSession.AsyncBytes
-    let response: URLResponse
-    do {
-      (bytes, response) = try await session.bytes(for: request)
-    } catch {
-      if isCancellationError(
-        error,
-        transactionId: params.transactionId
-      ) {
-        throw FirmwareArtifactStoreError.downloadFailed(
-          "ARTIFACT_CANCELLED: firmware artifact download was cancelled"
-        )
-      }
-      throw FirmwareArtifactStoreError.downloadFailed(
-        "ARTIFACT_NETWORK_FAILED: firmware request failed"
-      )
-    }
-    guard let httpResponse = response as? HTTPURLResponse else {
-      throw FirmwareArtifactStoreError.downloadFailed("Firmware response is not HTTP")
-    }
-    guard httpResponse.statusCode == 200 || httpResponse.statusCode == 206 else {
-      throw FirmwareArtifactStoreError.downloadFailed(
-        "ARTIFACT_HTTP_\(httpResponse.statusCode): firmware request failed"
-      )
-    }
-    let append = resumeOffset > 0 && httpResponse.statusCode == 206
-    if httpResponse.statusCode == 206 {
-      guard
-        let contentRange = httpResponse.value(forHTTPHeaderField: "Content-Range"),
-        validateContentRange(
-          contentRange,
-          expectedStart: append ? resumeOffset : 0,
-          expectedTotal: Int64(params.expectedSize)
-        )
-      else {
-        throw FirmwareArtifactStoreError.downloadFailed(
-          "ARTIFACT_PROTOCOL_INVALID: firmware resume Content-Range is invalid"
-        )
-      }
-    }
-    let handle = try FileHandle(forWritingTo: partialURL)
-    defer { try? handle.close() }
-    if append {
-      try handle.seekToEnd()
-    } else {
-      try handle.truncate(atOffset: 0)
+      session.finishTasksAndInvalidate()
     }
 
-    var written = append ? resumeOffset : 0
-    var buffer = Data()
-    buffer.reserveCapacity(64 * 1024)
     do {
-      for try await byte in bytes {
-        buffer.append(byte)
-        if buffer.count >= 64 * 1024 {
-          written += Int64(buffer.count)
-          guard written <= Int64(params.maxBytes) else {
-            throw FirmwareArtifactStoreError.downloadFailed(
-              "ARTIFACT_PROTOCOL_INVALID: firmware artifact exceeds maxBytes"
-            )
-          }
-          try handle.write(contentsOf: buffer)
-          buffer.removeAll(keepingCapacity: true)
-        }
-      }
+      try await streamDelegate.run(session: session, request: request)
     } catch let error as FirmwareArtifactStoreError {
       throw error
     } catch {
@@ -1113,20 +1348,15 @@ final class FirmwareArtifactStore {
           "ARTIFACT_CANCELLED: firmware artifact download was cancelled"
         )
       }
-      throw FirmwareArtifactStoreError.downloadFailed(
-        "ARTIFACT_NETWORK_FAILED: firmware response stream failed"
-      )
-    }
-    if !buffer.isEmpty {
-      written += Int64(buffer.count)
-      guard written <= Int64(params.maxBytes) else {
+      if isFirmwareArtifactTLSError(error) {
         throw FirmwareArtifactStoreError.downloadFailed(
-          "ARTIFACT_PROTOCOL_INVALID: firmware artifact exceeds maxBytes"
+          "ARTIFACT_TLS_FAILED: firmware TLS validation failed"
         )
       }
-      try handle.write(contentsOf: buffer)
+      throw FirmwareArtifactStoreError.downloadFailed(
+        "ARTIFACT_NETWORK_FAILED: firmware request failed"
+      )
     }
-    try handle.synchronize()
     try rejectIfCancelled(transactionId: params.transactionId)
   }
 
@@ -1157,34 +1387,6 @@ final class FirmwareArtifactStore {
       nsError.code == NSURLErrorCancelled
   }
 
-  private func validateContentRange(
-    _ value: String,
-    expectedStart: Int64,
-    expectedTotal: Int64
-  ) -> Bool {
-    let pattern = #"^bytes ([0-9]+)-([0-9]+)/([0-9]+)$"#
-    guard
-      let expression = try? NSRegularExpression(pattern: pattern),
-      let match = expression.firstMatch(
-        in: value.lowercased(),
-        range: NSRange(value.startIndex..., in: value)
-      ),
-      match.range.location != NSNotFound,
-      let startRange = Range(match.range(at: 1), in: value),
-      let endRange = Range(match.range(at: 2), in: value),
-      let totalRange = Range(match.range(at: 3), in: value),
-      let start = Int64(value[startRange]),
-      let end = Int64(value[endRange]),
-      let total = Int64(value[totalRange])
-    else {
-      return false
-    }
-    return start == expectedStart &&
-      end >= start &&
-      end < total &&
-      total == expectedTotal
-  }
-
   private func validateStoredArtifact(
     fileURL: URL,
     expectedSize: Int64,
@@ -1210,6 +1412,36 @@ final class FirmwareArtifactStore {
     )
   }
 
+  private func validateDownloadedArtifact(
+    fileURL: URL,
+    expectedSize: Int64?,
+    expectedSha256: String?,
+    maxBytes: Int64
+  ) throws -> StoredFirmwareArtifact {
+    let size = try fileSize(fileURL)
+    guard
+      size > 0,
+      size <= maxBytes,
+      expectedSize.map({ size == $0 }) ?? true
+    else {
+      throw FirmwareArtifactStoreError.integrityMismatch(
+        "ARTIFACT_INTEGRITY_FAILED: firmware artifact size mismatch"
+      )
+    }
+    let sha256 = try hashFile(fileURL)
+    guard expectedSha256.map({ sha256 == $0 }) ?? true else {
+      throw FirmwareArtifactStoreError.integrityMismatch(
+        "ARTIFACT_INTEGRITY_FAILED: firmware artifact SHA-256 mismatch"
+      )
+    }
+    return StoredFirmwareArtifact(
+      artifactRef: "fw:\(sha256)",
+      size: size,
+      sha256: sha256,
+      fileURL: fileURL
+    )
+  }
+
   private func resolveArtifactURL(_ artifactRef: String) throws -> URL {
     guard artifactRef.hasPrefix("fw:") else {
       throw FirmwareArtifactStoreError.invalidInput("Invalid firmware artifactRef")