Repository Public
1// =============================================================================2// SP BOUCHER | SOFTWARE & RESEARCH3// ARTIFICIAL INTELLIGENCE • FINANCE • ENGINEERING4// =============================================================================5//6// PROJECT METADATA7// -----------------------------------------------------------------------------8// Project : SP Wallet for macOS9// File : Features/NFTs/NFTMedia.swift10// Description : The only door through which NFT media enters the app.11// Bytes come exclusively from the backend's media proxy (an12// opaque id, never a URL); images are decoded with ImageIO13// into downsampled bitmaps under strict type, dimension and14// pixel limits (decompression bombs are refused before any15// pixel is decoded); HTML, SVG and 3D models are never16// rendered. Thumbnails live in a memory cache bounded by17// cost, and the small grid thumbnails are re-encoded by this18// app and kept beside the offline snapshots so the last19// inventory stays viewable without a connection.20// Module : Features21// Repository : https://git.spboucher.ai/sp-wallet-macos22// Created : 2026-11-1823// Last Modified : 2026-11-1824//25// =============================================================================26// AUTHOR & PROFESSIONAL AFFILIATION27// =============================================================================28//29// Author : Simon-Pierre Boucher30// Position : Professor of Finance31// Institution : Université du Québec en Outaouais (UQO)32// Department : Département des sciences administratives33// Organization : SP Boucher34//35// Website : https://spboucher.ai36// Git : https://git.spboucher.ai37//38// =============================================================================39// OFFICIAL CONTACT DIRECTORY40// =============================================================================41//42// General : info@spboucher.ai43// Professional : contact@spboucher.ai44// Direct : simon@spboucher.ai45// Research : research@spboucher.ai46// Development : dev@spboucher.ai47// Support : support@spboucher.ai48// Security/Admin : admin@spboucher.ai49// Notifications : notifications@spboucher.ai50//51// Preferred Contact: support@spboucher.ai52//53// =============================================================================54// COPYRIGHT & INTELLECTUAL PROPERTY55// =============================================================================56//57// Copyright (c) 202658// Simon-Pierre Boucher59//60// All rights reserved where applicable.61//62// This file is governed by the applicable project license,63// copyright notices, institutional agreements and relevant law.64//65// Unless expressly authorized by the applicable license or66// rights holder, copying, redistribution, sublicensing,67// publication and commercial exploitation are not permitted.68//69// Existing third-party rights and notices remain unaffected.70//71// =============================================================================72// CONFIDENTIALITY & SECURITY73// =============================================================================74//75// Classification : Public76// Distribution : Public repository; use is governed by the project license77// Security Contact : admin@spboucher.ai78//79// Access to this source does not independently grant permission80// to redistribute or disclose confidential materials.81//82// Do not embed credentials, private keys, access tokens,83// certificates or confidential personal information.84//85// =============================================================================86// LICENSE & MAINTENANCE87// =============================================================================88//89// License : None specified (no license file in this repository)90// Maintainer : Simon-Pierre Boucher91// Technical Contact: dev@spboucher.ai92//93// =============================================================================94// END OF SP BOUCHER SOURCE HEADER95// =============================================================================9697import Foundation98import ImageIO99import CoreGraphics100import UniformTypeIdentifiers101import SPWalletCore102103/// What a media tile can show. Never the raw bytes: either a bitmap this app decoded, or the reason there is none.104enum NFTThumbnail: Sendable {105 case image(CGImage)106 /// The file exists but this app will not render it (active content, unsupported type, refused by the decoder).107 case notDisplayable(String)108 /// The file could not be obtained (proxy refusal, host unreachable, offline).109 case unavailable(String)110}111112enum NFTImageDecoder {113 /// Hard limits on what is handed to the decoder. A 36-megapixel image is at most ~144 MB transiently while it is downsampled.114 static let maxPixels = 36_000_000115 static let maxDimension = 16_384116 /// Container types ImageIO may open for NFT media: exactly the raster types the proxy serves. SVG is not among them.117 static let allowedTypes: Set<String> = ["public.png", "public.jpeg", "com.compuserve.gif", "org.webmproject.webp", "public.avif"]118119 enum Failure: Error { case notAnImage, typeNotAllowed(String), tooLarge(width: Int, height: Int), undecodable }120121 /// Reads the header first (type, pixel size), refuses anything outside the limits, then asks ImageIO for a thumbnail of at most `maxPixelSize` on its long side. The full-size bitmap is never kept.122 static func downsample(_ data: Data, maxPixelSize: Int) -> Result<CGImage, Failure> {123 let lazy = [kCGImageSourceShouldCache: false] as CFDictionary124 guard let source = CGImageSourceCreateWithData(data as CFData, lazy), CGImageSourceGetCount(source) > 0 else { return .failure(.notAnImage) }125 guard let type = CGImageSourceGetType(source) as String? else { return .failure(.notAnImage) }126 guard allowedTypes.contains(type) else { return .failure(.typeNotAllowed(type)) }127 guard let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, lazy) as? [CFString: Any],128 let width = (properties[kCGImagePropertyPixelWidth] as? NSNumber)?.intValue,129 let height = (properties[kCGImagePropertyPixelHeight] as? NSNumber)?.intValue, width > 0, height > 0 else { return .failure(.undecodable) }130 guard width <= maxDimension, height <= maxDimension, width.multipliedReportingOverflow(by: height).overflow == false, width * height <= maxPixels131 else { return .failure(.tooLarge(width: width, height: height)) }132 let options = [133 kCGImageSourceCreateThumbnailFromImageAlways: true, kCGImageSourceCreateThumbnailWithTransform: true,134 kCGImageSourceThumbnailMaxPixelSize: max(16, maxPixelSize), kCGImageSourceShouldCacheImmediately: true,135 ] as CFDictionary136 guard let image = CGImageSourceCreateThumbnailAtIndex(source, 0, options) else { return .failure(.undecodable) }137 return .success(image)138 }139140 /// PNG bytes of a bitmap this app produced (what is written to the offline thumbnail cache — never the creator's file).141 static func png(_ image: CGImage) -> Data? {142 let out = NSMutableData()143 guard let destination = CGImageDestinationCreateWithData(out, UTType.png.identifier as CFString, 1, nil) else { return nil }144 CGImageDestinationAddImage(destination, image, nil)145 return CGImageDestinationFinalize(destination) ? out as Data : nil146 }147148 static func text(_ f: Failure) -> String {149 switch f {150 case .notAnImage: "Média non affichable : ces octets ne sont pas une image reconnue."151 case .typeNotAllowed(let t): "Média non affichable : type d’image non accepté (\(t))."152 case .tooLarge(let w, let h): "Média non affichable : image de \(w) × \(h) pixels, au-delà de la limite de sécurité de cette app."153 case .undecodable: "Média non affichable : l’image n’a pas pu être décodée."154 }155 }156}157158/// One decode at a time: a downsample can transiently need over a hundred megabytes, so decodes are never run in parallel.159private actor NFTDecodeQueue {160 func downsample(_ data: Data, maxPixelSize: Int) -> Result<CGImage, NFTImageDecoder.Failure> { NFTImageDecoder.downsample(data, maxPixelSize: maxPixelSize) }161}162163/// A media file this app can hand to AVFoundation, written to a private temporary file.164struct NFTPlayableFile: Sendable, Equatable {165 let url: URL166 let mime: String167 var isAudio: Bool { mime.hasPrefix("audio/") }168}169170actor NFTMediaStore {171 static let shared = NFTMediaStore()172173 /// Long side, in pixels, of a grid thumbnail (kept on disk for offline reading) and of the item page's image (memory only).174 static let gridPixels = 360175 static let detailPixels = 1800176 /// Types AVFoundation plays natively among those the proxy serves. WebM and Ogg are not, and are said so.177 static let playableTypes: [String: String] = ["video/mp4": "mp4", "audio/mp4": "m4a", "audio/mpeg": "mp3", "audio/wav": "wav"]178 /// Local ceiling on one media download, whatever the server's own limit is.179 static let maxDownloadBytes = 64 * 1024 * 1024180181 private final class Box { let image: CGImage; init(_ image: CGImage) { self.image = image } }182 private let memory: NSCache<NSString, Box> = {183 let c = NSCache<NSString, Box>(); c.totalCostLimit = 160 * 1024 * 1024; c.countLimit = 600184 return c185 }()186 private var failures: [String: NFTThumbnail] = [:]187 private var inflight: [String: Task<NFTThumbnail, Never>] = [:]188 private var running = 0189 private var waiters: [CheckedContinuation<Void, Never>] = []190 private let decoder = NFTDecodeQueue()191 private let thumbDirectory = AppEnvironment.supportDirectory.appendingPathComponent("snapshots", isDirectory: true).appendingPathComponent("nft-thumbs", isDirectory: true)192 private let playDirectory = FileManager.default.temporaryDirectory.appendingPathComponent("spw-nft-media", isDirectory: true)193 private var pruned = false194195 private init() { try? FileManager.default.removeItem(at: playDirectory) }196197 static func limit(_ serverMax: Int?) -> Int { min(serverMax ?? 25 * 1024 * 1024, maxDownloadBytes) }198199 /// The thumbnail of one proxy media id. `api == nil` means offline: only what is already in memory or on disk is answered.200 func thumbnail(id: String, pixels: Int, api: NFTAPI?, maxBytes: Int) async -> NFTThumbnail {201 guard id.range(of: "^m[0-9a-f]{40}$", options: .regularExpression) != nil else { return .unavailable("Identifiant de média invalide.") }202 let key = "\(id)-\(pixels)"203 if let box = memory.object(forKey: key as NSString) { return .image(box.image) }204 if let failed = failures[key] { return failed }205 if let task = inflight[key] { return await task.value }206 let persist = pixels == Self.gridPixels207 let file = thumbDirectory.appendingPathComponent("\(key).png")208 let directory = thumbDirectory, decoder = decoder209 let task = Task<NFTThumbnail, Never> {210 if persist, let cached = try? Data(contentsOf: file), case .success(let image) = await decoder.downsample(cached, maxPixelSize: pixels) { return .image(image) }211 guard let api else { return .unavailable("Hors connexion : cette miniature n’avait pas été téléchargée.") }212 await self.acquire()213 let content: NFTMediaContent214 do { content = try await api.media(id: id, maxBytes: maxBytes) } catch { self.release(); return .unavailable(Self.text(error)) }215 self.release()216 guard content.kind == "image" else { return .notDisplayable("Média non affichable ici : type \(content.mime).") }217 guard !content.isActiveContent else { return .notDisplayable("Média non affichable : document SVG (peut contenir du script ; le serveur ne le convertit pas en image).") }218 switch await decoder.downsample(content.data, maxPixelSize: pixels) {219 case .failure(let f): return .notDisplayable(NFTImageDecoder.text(f))220 case .success(let image):221 if persist, let png = NFTImageDecoder.png(image) {222 try? FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)223 try? png.write(to: file, options: [.atomic, .completeFileProtection])224 }225 return .image(image)226 }227 }228 inflight[key] = task229 let result = await task.value230 inflight[key] = nil231 switch result {232 case .image(let image): memory.setObject(Box(image), forKey: key as NSString, cost: image.bytesPerRow * image.height)233 case .notDisplayable: remember(result, for: key)234 case .unavailable: if api != nil { remember(result, for: key) }235 }236 if persist, !pruned { pruned = true; prune() }237 return result238 }239240 /// Download a playable file (types of `playableTypes` only) to a private temporary file for AVFoundation.241 func playable(id: String, api: NFTAPI, maxBytes: Int) async throws -> NFTPlayableFile {242 let content = try await api.media(id: id, maxBytes: maxBytes)243 guard let ext = Self.playableTypes[content.mime] else { throw APIError(status: 0, code: "media_not_playable", message: content.mime) }244 try FileManager.default.createDirectory(at: playDirectory, withIntermediateDirectories: true)245 let url = playDirectory.appendingPathComponent("\(UUID().uuidString).\(ext)")246 try content.data.write(to: url, options: [.atomic])247 return NFTPlayableFile(url: url, mime: content.mime)248 }249250 func discard(_ file: NFTPlayableFile) { try? FileManager.default.removeItem(at: file.url) }251252 /// A manual refresh gives every refused or failed media another chance.253 func forgetFailures() { failures.removeAll() }254255 private func remember(_ t: NFTThumbnail, for key: String) {256 if failures.count >= 2_000 { failures.removeAll() }257 failures[key] = t258 }259260 // at most four proxy downloads at once (the route allows 240 a minute)261 private func acquire() async {262 if running < 4 { running += 1; return }263 await withCheckedContinuation { waiters.append($0) }264 }265 private func release() {266 if waiters.isEmpty { running -= 1 } else { waiters.removeFirst().resume() }267 }268269 /// Keeps the offline thumbnail folder bounded: beyond 3 000 files the oldest are removed.270 private func prune() {271 let fm = FileManager.default272 guard let files = try? fm.contentsOfDirectory(at: thumbDirectory, includingPropertiesForKeys: [.contentModificationDateKey]), files.count > 3_000 else { return }273 let dated = files.map { ($0, (try? $0.resourceValues(forKeys: [.contentModificationDateKey]).contentModificationDate) ?? .distantPast) }.sorted { $0.1 < $1.1 }274 for (url, _) in dated.prefix(files.count - 3_000) { try? fm.removeItem(at: url) }275 }276277 /// French reason of a proxy refusal. The server's codes are kept: a refusal is information, not noise.278 static func text(_ error: Error) -> String {279 guard let e = error as? APIError else { return "Média indisponible : \(error.localizedDescription)" }280 let detail = e.data?["code"]?.stringValue.map { " (\($0))" } ?? ""281 switch e.code {282 case "offline": return "Média indisponible : portefeuille injoignable."283 case "media_blocked": return e.status == 413 ? "Média refusé par le serveur : fichier trop volumineux\(detail)." : "Média bloqué par le serveur\(detail)."284 case "media_unreachable": return "Média indisponible : l’hôte du créateur ne répond pas\(detail)."285 case "not_found": return "Média introuvable sur le serveur."286 case "media_too_large": return "Média refusé par cette app : fichier au-delà de la limite locale."287 case "media_unexpected_type": return "Média refusé : le serveur a répondu un type hors de sa liste autorisée."288 case "media_not_playable": return "Média non lisible nativement (type \(e.message))."289 case "rate_limited": return "Trop de requêtes de médias ; réessayez dans un instant."290 default: return "Média indisponible : \(e.message.isEmpty ? e.code : e.message) [\(e.code)]"291 }292 }293}294