Files
VCCPlusOSS/platforms/macos/App/SoftwareLibraryInstaller.swift
T

390 lines
24 KiB
Swift

// SPDX-License-Identifier: GPL-3.0-or-later
import Foundation
import CryptoKit
import Darwin
/// All filesystem/verification work runs on this actor, away from the native UI.
/// A receipt is committed only after a complete staged tree has been renamed.
actor SoftwareLibraryInstaller {
static let maximumPackageBytes: Int64 = 1_073_741_824
static let maximumExpandedBytes: UInt64 = 8 * 1024 * 1024 * 1024
static let maximumEntries: UInt = 20_000
let root: URL
private let session: URLSession
private var active: Set<String> = []
private(set) var recoveryWarnings: [String] = []
private let manager = FileManager.default
init(root: URL, session: URLSession? = nil) {
self.root = root.standardizedFileURL
if let session { self.session = session }
else {
let configuration = URLSessionConfiguration.ephemeral
configuration.urlCache = nil
configuration.timeoutIntervalForRequest = 60
configuration.timeoutIntervalForResource = 1800
self.session = URLSession(configuration: configuration)
}
}
enum Failure: LocalizedError {
case invalidMetadata, unsafeLocation, invalidReceipt, busy, existingDifferentPackage
case response, size, fingerprint, unsupported, insufficientSpace
var errorDescription: String? {
switch self {
case .invalidMetadata: return "This catalog entry has invalid download details. Its files have not been installed."
case .unsafeLocation: return "The Software Library location contains an unexpected file or symbolic link. Existing files have been preserved."
case .invalidReceipt: return "An installation record is damaged or unsupported. Its media has been preserved."
case .busy: return "This title is already being installed."
case .existingDifferentPackage: return "Another version is already installed. Remove its Library entry first; its working files will be preserved."
case .response: return "The software server did not return the expected download. Please try again."
case .size: return "The download size does not match the catalog. The incomplete download was discarded."
case .fingerprint: return "The download fingerprint does not match the catalog. The changed download was discarded."
case .unsupported: return "This package format is not supported for installation yet."
case .insufficientSpace: return "There is not enough free space to prepare this software. Free space and try again."
}
}
}
static func acceptsDownloadURL(_ url: URL) -> Bool {
guard url.scheme?.lowercased() == "https", url.host?.lowercased() == "vccplus.brianholman.com",
url.user == nil, url.password == nil, url.port == nil || url.port == 443,
url.query == nil, url.fragment == nil, url.path.hasPrefix("/dl/software/CoCoLibrary/") else { return false }
return !url.pathComponents.contains(where: { $0 == ".." || $0 == "." })
&& !url.path.contains("\\") && !url.path.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains)
}
static func releaseKey(_ id: String) -> String {
SHA256.hash(data: Data(id.utf8)).map { String(format: "%02x", $0) }.joined()
}
private static func validSHA(_ value: String) -> Bool { value.count == 64 && value.allSatisfy { "0123456789abcdef".contains($0) } }
private static func validID(_ value: String) -> Bool {
!value.isEmpty && value.utf8.count <= 256 && !value.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains)
}
private static func validRelative(_ value: String) -> Bool {
!value.isEmpty && !value.hasPrefix("/") && !value.contains("\\") && !value.contains(":")
&& !value.unicodeScalars.contains(where: CharacterSet.controlCharacters.contains)
&& value.split(separator: "/", omittingEmptySubsequences: false).allSatisfy { !$0.isEmpty && $0 != "." && $0 != ".." }
}
private func directory(_ path: URL, create: Bool) throws {
guard path.isFileURL else { throw Failure.unsafeLocation }
if manager.fileExists(atPath: path.path) || (try? path.resourceValues(forKeys: [.isSymbolicLinkKey]).isSymbolicLink) == true {
let values = try path.resourceValues(forKeys: [.isDirectoryKey, .isSymbolicLinkKey])
guard values.isDirectory == true, values.isSymbolicLink != true else { throw Failure.unsafeLocation }
} else if create { try manager.createDirectory(at: path, withIntermediateDirectories: true) }
else { throw Failure.invalidReceipt }
}
private func prepareRoot() throws {
try directory(root, create: true)
for name in ["Installations", "Packages", ".Staging", ".Locks"] { try directory(root.appendingPathComponent(name), create: true) }
}
private func regularFile(_ url: URL) throws -> Int64 {
let attributes = try manager.attributesOfItem(atPath: url.path)
guard attributes[.type] as? FileAttributeType == .typeRegular,
let size = attributes[.size] as? NSNumber else { throw Failure.unsafeLocation }
return size.int64Value
}
private func acquireLock(_ key: String) throws -> Int32 {
let path = root.appendingPathComponent(".Locks").appendingPathComponent(key).path
let fd = open(path, O_CREAT | O_RDWR | O_NOFOLLOW, S_IRUSR | S_IWUSR)
guard fd >= 0 else { throw Failure.unsafeLocation }
guard flock(fd, LOCK_EX | LOCK_NB) == 0 else { close(fd); throw Failure.busy }
return fd
}
func install(_ release: SoftwareLibraryRelease,
progress: @escaping @Sendable (SoftwareLibraryInstallProgress) -> Void = { _ in }) async throws -> SoftwareLibraryInstallationReceipt {
try release.validatePresentationMetadata()
guard Self.validID(release.id), Self.validSHA(release.packageSHA256),
release.byteSize > 0, release.byteSize <= Self.maximumPackageBytes else { throw Failure.invalidMetadata }
// Project provenance may be a repository/page; delivery has its own identity.
let format = (release.ownedGame?.package.url ?? release.sourceURL).pathExtension.lowercased()
guard ["zip", "ccc", "dsk", "os9"].contains(format) else { throw Failure.unsupported }
let downloadURL: URL
if let owned = release.ownedGame {
guard release.downloadURLs.contains(owned.package.url), Self.acceptsDownloadURL(owned.package.url) else { throw Failure.invalidMetadata }
downloadURL = owned.package.url
} else {
guard let accepted = release.downloadURLs.first(where: Self.acceptsDownloadURL) else { throw Failure.invalidMetadata }
downloadURL = accepted
}
try prepareRoot()
guard active.insert(release.id).inserted else { throw Failure.busy }
defer { active.remove(release.id) }
let key = Self.releaseKey(release.id), lock = try acquireLock(Self.releaseKey(release.id))
defer { flock(lock, LOCK_UN); close(lock) }
if let previous = try records(releaseID: release.id).first {
guard previous.1.packageSHA256 == release.packageSHA256 else { throw Failure.existingDifferentPackage }
return previous.1.publicReceipt(in: previous.0) // Never replace a user's modified working copy.
}
try Task.checkCancellation()
if let free = freeBytes(), free < release.byteSize * 3 + 64 * 1024 * 1024 { throw Failure.insufficientSpace }
let stageID = UUID().uuidString
let stageLock = try acquireLock("stage-" + stageID)
defer { flock(stageLock, LOCK_UN); close(stageLock) }
let stage = root.appendingPathComponent(".Staging").appendingPathComponent(stageID)
try manager.createDirectory(at: stage, withIntermediateDirectories: false)
defer { try? manager.removeItem(at: stage) }
let cached = root.appendingPathComponent("Packages").appendingPathComponent(release.packageSHA256 + ".package")
var validCache = false
if manager.fileExists(atPath: cached.path) {
do { try verify(cached, size: release.byteSize, sha: release.packageSHA256); validCache = true }
catch is CancellationError { throw CancellationError() }
catch {
_ = try regularFile(cached) // Refuse to unlink unexpected links or directories.
try manager.removeItem(at: cached)
}
}
if !validCache {
progress(.init(stage: .downloading, receivedBytes: 0, totalBytes: release.byteSize))
var request = URLRequest(url: downloadURL)
request.setValue("VCCPlus/SoftwareLibrary", forHTTPHeaderField: "User-Agent")
request.setValue("identity", forHTTPHeaderField: "Accept-Encoding")
let observer = LibraryDownloadObserver(expected: release.byteSize, progress: progress)
let temporary: URL, response: URLResponse
do { (temporary, response) = try await session.download(for: request, delegate: observer) }
catch {
if Task.isCancelled { throw CancellationError() }
if let failure = observer.failure { throw failure }
throw error
}
defer { try? manager.removeItem(at: temporary) }
guard let http = response as? HTTPURLResponse, http.statusCode == 200,
let finalURL = response.url, Self.acceptsDownloadURL(finalURL) else { throw Failure.response }
if let failure = observer.failure { throw failure }
if response.expectedContentLength >= 0 && response.expectedContentLength != release.byteSize { throw Failure.size }
progress(.init(stage: .verifying, receivedBytes: release.byteSize, totalBytes: release.byteSize))
try verify(temporary, size: release.byteSize, sha: release.packageSHA256)
let stagedPackage = stage.appendingPathComponent("verified.package")
try copyFile(temporary, stagedPackage)
try manager.setAttributes([.posixPermissions: 0o444], ofItemAtPath: stagedPackage.path)
// A second title with the same package may have filled the cache.
if manager.fileExists(atPath: cached.path) {
try verify(cached, size: release.byteSize, sha: release.packageSHA256)
try manager.removeItem(at: stagedPackage)
}
else { try manager.moveItem(at: stagedPackage, to: cached) }
}
try Task.checkCancellation()
let original = stage.appendingPathComponent("Original")
try manager.createDirectory(at: original, withIntermediateDirectories: false)
let originalPackage = original.appendingPathComponent("package." + format)
try copyFile(cached, originalPackage)
try manager.setAttributes([.posixPermissions: 0o444], ofItemAtPath: originalPackage.path)
let originalFiles = original.appendingPathComponent("Files")
let relativeFiles: [String]
progress(.init(stage: .extracting, receivedBytes: 0, totalBytes: 0))
let expandedAllowance: UInt64
if let free = freeBytes() {
guard free > 64 * 1024 * 1024 else { throw Failure.insufficientSpace }
// Reserve space for both originals and writable copies. The native
// extractor enforces this budget before accepting each entry.
expandedAllowance = min(Self.maximumExpandedBytes, UInt64((free - 64 * 1024 * 1024) / 2))
} else { expandedAllowance = Self.maximumExpandedBytes }
if format == "zip" {
do {
relativeFiles = try VCCLibraryArchive.extractZIP(at: originalPackage, toNewDirectory: originalFiles,
maximumExpandedBytes: expandedAllowance, maximumEntries: Self.maximumEntries,
shouldCancel: { Task.isCancelled })
} catch {
if Task.isCancelled { throw CancellationError() }
throw error
}
} else {
guard UInt64(release.byteSize) <= expandedAllowance else { throw Failure.insufficientSpace }
try manager.createDirectory(at: originalFiles, withIntermediateDirectories: false)
let candidate = release.sourceURL.lastPathComponent
let name = Self.validRelative(candidate) && !candidate.contains("/") ? candidate : "Media." + format
try copyFile(cached, originalFiles.appendingPathComponent(name))
relativeFiles = [name]
}
guard !relativeFiles.isEmpty, relativeFiles.count <= Self.maximumEntries,
relativeFiles.allSatisfy(Self.validRelative) else { throw Failure.invalidReceipt }
if let owned = release.ownedGame {
guard relativeFiles.contains(owned.diskPath) else { throw Failure.invalidMetadata }
try verify(originalFiles.appendingPathComponent(owned.diskPath), size: owned.diskByteSize, sha: owned.diskSHA256)
}
let sizes = try relativeFiles.map { try regularFile(originalFiles.appendingPathComponent($0)) }
let total = sizes.reduce(Int64(0), +)
guard UInt64(total) <= Self.maximumExpandedBytes else { throw Failure.size }
if let available = (try? manager.attributesOfFileSystem(forPath: root.path)[.systemFreeSize]) as? NSNumber,
available.int64Value < total + 16 * 1024 * 1024 { throw Failure.insufficientSpace }
let working = stage.appendingPathComponent("Working")
try manager.createDirectory(at: working, withIntermediateDirectories: false)
progress(.init(stage: .preparing, receivedBytes: 0, totalBytes: total))
var copied: Int64 = 0
var lastPreparationProgress = DispatchTime.now().uptimeNanoseconds
for (index, name) in relativeFiles.enumerated() {
try Task.checkCancellation()
let source = originalFiles.appendingPathComponent(name), target = working.appendingPathComponent(name)
try manager.createDirectory(at: target.deletingLastPathComponent(), withIntermediateDirectories: true)
try copyFile(source, target)
try manager.setAttributes([.posixPermissions: 0o444], ofItemAtPath: source.path)
copied += sizes[index]
let now = DispatchTime.now().uptimeNanoseconds
if index == relativeFiles.count - 1 || now &- lastPreparationProgress >= 100_000_000 {
progress(.init(stage: .preparing, receivedBytes: copied, totalBytes: total))
lastPreparationProgress = now
}
}
let record = StoredReceipt(version: 1, releaseID: release.id, packageSHA256: release.packageSHA256,
installedAt: Date(), relativeFiles: relativeFiles, format: format)
let encoder = JSONEncoder(); encoder.outputFormatting = [.sortedKeys]
try encoder.encode(record).write(to: stage.appendingPathComponent("receipt.json"), options: .atomic)
try Task.checkCancellation()
let group = root.appendingPathComponent("Installations").appendingPathComponent(key)
try directory(group, create: true)
let final = group.appendingPathComponent(UUID().uuidString)
try manager.moveItem(at: stage, to: final)
progress(.init(stage: .complete, receivedBytes: total, totalBytes: total))
return record.publicReceipt(in: final)
}
private func freeBytes() -> Int64? {
((try? manager.attributesOfFileSystem(forPath: root.path)[.systemFreeSize]) as? NSNumber)?.int64Value
}
private func cleanupAbandonedStages() throws {
let staging = root.appendingPathComponent(".Staging")
for stage in try manager.contentsOfDirectory(at: staging, includingPropertiesForKeys: nil) {
guard UUID(uuidString: stage.lastPathComponent) != nil else { continue }
try directory(stage, create: false)
let lockPath = root.appendingPathComponent(".Locks/stage-" + stage.lastPathComponent)
guard manager.fileExists(atPath: lockPath.path) else { continue }
let fd = open(lockPath.path, O_RDWR | O_NOFOLLOW)
guard fd >= 0 else { continue }
defer { close(fd) }
if flock(fd, LOCK_EX | LOCK_NB) == 0 {
defer { flock(fd, LOCK_UN) }
try manager.removeItem(at: stage)
}
}
}
private func verify(_ path: URL, size: Int64, sha: String) throws {
guard try regularFile(path) == size else { throw Failure.size }
let file = try FileHandle(forReadingFrom: path)
defer { try? file.close() }
var hasher = SHA256()
while let bytes = try file.read(upToCount: 1024 * 1024), !bytes.isEmpty {
try Task.checkCancellation(); hasher.update(data: bytes)
}
guard hasher.finalize().map({ String(format: "%02x", $0) }).joined() == sha else { throw Failure.fingerprint }
}
private func copyFile(_ source: URL, _ destination: URL) throws {
_ = try regularFile(source)
guard !manager.fileExists(atPath: destination.path), manager.createFile(atPath: destination.path, contents: nil,
attributes: [.posixPermissions: 0o644]) else { throw Failure.unsafeLocation }
let input = try FileHandle(forReadingFrom: source), output = try FileHandle(forWritingTo: destination)
defer { try? input.close(); try? output.close() }
while let bytes = try input.read(upToCount: 1024 * 1024), !bytes.isEmpty {
try Task.checkCancellation(); try output.write(contentsOf: bytes)
}
}
private struct StoredReceipt: Codable {
let version: Int
let releaseID: String
let packageSHA256: String
let installedAt: Date
let relativeFiles: [String]
let format: String
func publicReceipt(in directory: URL) -> SoftwareLibraryInstallationReceipt {
.init(releaseID: releaseID, packageSHA256: packageSHA256, installedAt: installedAt,
workingDirectory: directory.appendingPathComponent("Working"), relativeFiles: relativeFiles)
}
}
private func records(releaseID: String? = nil) throws -> [(URL, StoredReceipt)] {
if releaseID == nil { recoveryWarnings = [] }
try prepareRoot()
try cleanupAbandonedStages()
var result: [(URL, StoredReceipt)] = []
let groups = try manager.contentsOfDirectory(at: root.appendingPathComponent("Installations"), includingPropertiesForKeys: nil)
for group in groups {
guard Self.validSHA(group.lastPathComponent), releaseID == nil || group.lastPathComponent == Self.releaseKey(releaseID!) else { continue }
do { result.append(contentsOf: try groupRecords(group)) }
catch {
// A damaged unrelated title cannot hide valid installations or
// block a new title. Its bytes remain available for recovery.
if releaseID != nil { throw error }
recoveryWarnings.append("An installation record could not be read. Its files were preserved at \(group.path). \(error.localizedDescription)")
}
}
return result
}
private func groupRecords(_ group: URL) throws -> [(URL, StoredReceipt)] {
try directory(group, create: false)
var result: [(URL, StoredReceipt)] = []
for installation in try manager.contentsOfDirectory(at: group, includingPropertiesForKeys: nil) {
guard UUID(uuidString: installation.lastPathComponent) != nil else { continue }
try directory(installation, create: false)
let path = installation.appendingPathComponent("receipt.json")
guard manager.fileExists(atPath: path.path) else { continue }
guard try regularFile(path) <= 16 * 1024 * 1024 else { throw Failure.invalidReceipt }
let record: StoredReceipt
do { record = try JSONDecoder().decode(StoredReceipt.self, from: Data(contentsOf: path)) }
catch { throw Failure.invalidReceipt }
guard record.version == 1, Self.validID(record.releaseID), Self.releaseKey(record.releaseID) == group.lastPathComponent,
Self.validSHA(record.packageSHA256), !record.relativeFiles.isEmpty,
record.relativeFiles.count <= Self.maximumEntries, record.relativeFiles.allSatisfy(Self.validRelative),
Set(record.relativeFiles).count == record.relativeFiles.count,
["zip", "ccc", "dsk", "os9"].contains(record.format) else { throw Failure.invalidReceipt }
try directory(installation.appendingPathComponent("Working"), create: false)
try directory(installation.appendingPathComponent("Original"), create: false)
_ = try regularFile(installation.appendingPathComponent("Original/package." + record.format))
guard result.isEmpty else { throw Failure.invalidReceipt }
result.append((installation, record))
}
return result
}
func recoverInstallations() throws -> [SoftwareLibraryInstallationReceipt] {
try records().map { $0.1.publicReceipt(in: $0.0) }.sorted { $0.installedAt < $1.installedAt }
}
/// Unregisters only. Original packages and all working files remain in place,
/// including media currently mounted in the emulator or modified by the user.
func forgetInstallation(releaseID: String) throws -> URL? {
guard Self.validID(releaseID), !active.contains(releaseID) else { throw Failure.busy }
try prepareRoot()
let lock = try acquireLock(Self.releaseKey(releaseID))
defer { flock(lock, LOCK_UN); close(lock) }
guard let (directory, record) = try records(releaseID: releaseID).first else { return nil }
try manager.removeItem(at: directory.appendingPathComponent("receipt.json"))
return record.publicReceipt(in: directory).workingDirectory
}
}
private final class LibraryDownloadObserver: NSObject, URLSessionDownloadDelegate, @unchecked Sendable {
private let expected: Int64
private let progress: @Sendable (SoftwareLibraryInstallProgress) -> Void
private let lock = NSLock()
private var storedFailure: SoftwareLibraryInstaller.Failure?
private var lastProgressTime: UInt64?
private var reportedDownloadCompletion = false
var failure: SoftwareLibraryInstaller.Failure? { lock.lock(); defer { lock.unlock() }; return storedFailure }
init(expected: Int64, progress: @escaping @Sendable (SoftwareLibraryInstallProgress) -> Void) {
self.expected = expected; self.progress = progress
}
private func fail(_ failure: SoftwareLibraryInstaller.Failure, task: URLSessionTask) {
lock.lock(); storedFailure = failure; lock.unlock(); task.cancel()
}
func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didWriteData bytesWritten: Int64,
totalBytesWritten: Int64, totalBytesExpectedToWrite: Int64) {
guard totalBytesWritten <= expected, totalBytesExpectedToWrite <= expected else { fail(.size, task: downloadTask); return }
let now = DispatchTime.now().uptimeNanoseconds
lock.lock()
let isFinal = totalBytesWritten == expected && !reportedDownloadCompletion
let shouldReport = storedFailure == nil && (lastProgressTime == nil || isFinal
|| now &- (lastProgressTime ?? now) >= 100_000_000)
if shouldReport {
lastProgressTime = now
if isFinal { reportedDownloadCompletion = true }
}
lock.unlock()
if shouldReport { progress(.init(stage: .downloading, receivedBytes: totalBytesWritten, totalBytes: expected)) }
}
func urlSession(_ session: URLSession, task: URLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse,
newRequest request: URLRequest, completionHandler: @escaping (URLRequest?) -> Void) {
guard request.url.map(SoftwareLibraryInstaller.acceptsDownloadURL) == true else {
fail(.response, task: task); completionHandler(nil); return
}
completionHandler(request)
}
func urlSession(_ session: URLSession, downloadTask: URLSessionDownloadTask, didFinishDownloadingTo location: URL) { }
}