// 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 = [] 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) { } }