Files
QFT/ios/QFT/Core/PairingProtocol.swift
T
zhy200308 4d77ba6c91 feat: 新增 iPhone 客户端,含隔空投送式点对点互传
三条链路:
- 电脑 → iPhone:扫 QFTSEND2 码下载,流式落盘 + 增量 SHA-256,
  支持 Range 断点续传
- iPhone → 电脑:扫 QFTPAIR2 码后 init/chunk/finish 并行分块上传
- iPhone ↔ iPhone:QFTP2P1 扫码握手,Network.framework 开启
  includePeerToPeer(AirDrop 同款 BLE 发现 + AWDL 点对点 Wi-Fi),
  两台设备不需要连同一个 Wi-Fi,也不需要路由器

P2P 用 TLS-PSK 握手:32 字节预共享密钥由发送端随机生成并写进二维码,
扫码这个动作本身完成带外密钥交换与双向认证,无需证书体系与配对弹窗。
未扫到码的第三方连上来过不了握手。

核心层刻意不 import UIKit,可直接以 macOS 为目标编译测试,
不需要 Xcode 也不需要模拟器,已接入主自检套件,72 项全部通过:
- 端点白名单 11 种拒绝用例(域名、公网、172.32 边界、
  非规范八位组、IPv6、带凭据/路径/query)
- CoreTests/MockPCServer.py 严格复刻 receiver.rs / sender.rs 的线上语义
  (路径、header 名、JSON 字段、Range 行为、chunk 长度校验),
  构成 Swift 与 Rust 两端的线格式契约测试,任一端改协议即会失败
- 真实 TLS-PSK 握手下的 P2P 端到端传输,含错误密钥必须被拒

iOS 平台限制(已在 ios/README.md 说明):
NEHotspotConfiguration 需要付费账号 entitlement,故不实现 Direct AP
流程,与电脑互传要求同一局域网;AWDL 是苹果私有链路,Windows 无法参与。
上传块固定 4 MiB 而非 Android 的 4/8/16 MiB,因为 iOS 上
worker 数 × 块大小即内存峰值。

未验证部分:本机只有 Command Line Tools,无 Xcode 与 iOS SDK,
UI 层(SwiftUI/UIKit/AVFoundation)未经编译;.xcodeproj 已通过
plutil 解析与引用完整性校验(42 个对象无悬空引用),
但未在 Xcode 中实际打开过。
2026-08-11 09:08:37 +08:00

189 lines
7.5 KiB
Swift
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
import Foundation
enum TransferDirection: String {
case uploadToPC = "u" // QFTPAIR2:手机把文件传给电脑
case downloadToPhone = "d" // QFTSEND2:电脑已选好文件,手机扫码后下载
}
struct WifiCredentials: Equatable {
let ssid: String
let passphrase: String
}
struct PairingPayload: Equatable {
let version: Int
let session: String
let pcName: String
let port: Int
let endpoints: [String]
let wifi: WifiCredentials?
let direction: TransferDirection
let fileName: String?
let fileSize: UInt64?
let sha256: String?
}
/// QFTPAIR2 / QFTSEND2 配对二维码解析。
///
/// 二维码是**不可信输入**:它决定了 App 接下来去连哪个地址。因此这里只接受
/// 字面量私有 IPv4 + 二维码自称的端口,任何域名、公网地址、带 query/fragment
/// 的 URL 一律拒绝——与 Windows/Android 两端的校验保持一致。
enum PairingProtocol {
static let prefixUpload = "QFTPAIR2:"
static let prefixDownload = "QFTSEND2:"
static func isPairingText(_ text: String) -> Bool {
text.hasPrefix(prefixUpload) || text.hasPrefix(prefixDownload)
}
static func parse(_ text: String) -> PairingPayload? {
guard text.count <= 4096 else { return nil }
if text.hasPrefix(prefixUpload) {
return parseV2(String(text.dropFirst(prefixUpload.count)), expected: .uploadToPC)
}
if text.hasPrefix(prefixDownload) {
return parseV2(String(text.dropFirst(prefixDownload.count)), expected: .downloadToPhone)
}
return nil
}
private static func parseV2(_ encoded: String, expected: TransferDirection) -> PairingPayload? {
guard let data = Base64URL.decode(encoded), data.count <= 2048 else { return nil }
guard let root = try? JSONSerialization.jsonObject(with: data),
let object = root as? [String: Any] else { return nil }
guard (object["v"] as? Int) == 2 else { return nil }
// 缺省为 "u",与 Windows 端「上传 QR 不写 d 字段」的编码方式对应
let rawDirection = (object["d"] as? String) ?? "u"
guard let direction = TransferDirection(rawValue: rawDirection),
direction == expected else { return nil }
guard let session = object["s"] as? String, isValidSession(session) else { return nil }
guard let port = object["p"] as? Int, (1...65535).contains(port) else { return nil }
var wifi: WifiCredentials?
if let array = object["w"] as? [Any], array.count >= 2,
let ssid = array[0] as? String, let passphrase = array[1] as? String {
guard isValidWifi(ssid: ssid, passphrase: passphrase) else { return nil }
wifi = WifiCredentials(ssid: ssid, passphrase: passphrase)
}
var endpoints: [String] = []
if let array = object["e"] as? [Any] {
for item in array {
guard let raw = item as? String else { continue }
var value = raw.trimmingCharacters(in: .whitespaces)
while value.hasSuffix("/") { value.removeLast() }
if isAllowedLocalHTTPEndpoint(value, expectedPort: port), !endpoints.contains(value) {
endpoints.append(value)
}
}
}
// iOS 无法用代码加入指定 Wi-Fi(NEHotspotConfiguration 需要付费账号的
// entitlement),所以 Direct-AP 二维码在本端必须自带可用 endpoint。
if endpoints.isEmpty { return nil }
var fileName: String?
var fileSize: UInt64?
var sha256: String?
if direction == .downloadToPhone {
guard let name = (object["f"] as? String)?.trimmingCharacters(in: .whitespaces),
isValidFileName(name) else { return nil }
guard let size = object["z"] as? NSNumber, size.int64Value >= 0 else { return nil }
guard let hash = (object["h"] as? String)?.lowercased(), isValidSHA256(hash) else { return nil }
fileName = name
fileSize = UInt64(size.int64Value)
sha256 = hash
}
let pcName = String(((object["n"] as? String) ?? "Windows-PC").prefix(80))
return PairingPayload(
version: 2,
session: session,
pcName: pcName,
port: port,
endpoints: endpoints,
wifi: wifi,
direction: direction,
fileName: fileName,
fileSize: fileSize,
sha256: sha256
)
}
// MARK: - 校验
static func isValidSession(_ value: String) -> Bool {
guard (20...64).contains(value.count) else { return false }
for scalar in value.unicodeScalars {
switch scalar {
case "A"..."Z", "a"..."z", "0"..."9", "-", "_": continue
default: return false
}
}
return true
}
static func isValidWifi(ssid: String, passphrase: String) -> Bool {
!ssid.trimmingCharacters(in: .whitespaces).isEmpty
&& Data(ssid.utf8).count <= 32
&& (8...63).contains(passphrase.count)
}
static func isValidFileName(_ value: String) -> Bool {
guard !value.isEmpty, value.count <= 180 else { return false }
let forbidden: Set<Unicode.Scalar> = ["\\", "/", ":", "*", "?", "\"", "<", ">", "|"]
for scalar in value.unicodeScalars {
if scalar.value <= 31 || scalar.value == 127 { return false }
if forbidden.contains(scalar) { return false }
}
return true
}
static func isValidSHA256(_ value: String) -> Bool {
guard value.count == 64 else { return false }
for scalar in value.unicodeScalars {
switch scalar {
case "0"..."9", "a"..."f": continue
default: return false
}
}
return true
}
/// 只允许 `http://<私有 IPv4 字面量>:<期望端口>`。
/// 故意不使用 URL/URLComponents 的宽松解析:它会接受域名、IPv6、
/// 带凭据的 URL 等本协议不该出现的形态。
static func isAllowedLocalHTTPEndpoint(_ value: String, expectedPort: Int) -> Bool {
guard value.hasPrefix("http://") else { return false }
let rest = String(value.dropFirst("http://".count))
guard !rest.contains("@"), !rest.contains("?"), !rest.contains("#"),
!rest.contains("/") else { return false }
let parts = rest.split(separator: ":", omittingEmptySubsequences: false)
guard parts.count == 2, let port = Int(parts[1]), port == expectedPort else { return false }
return isPrivateIPv4(String(parts[0]))
}
static func isPrivateIPv4(_ host: String) -> Bool {
let octets = host.split(separator: ".", omittingEmptySubsequences: false)
guard octets.count == 4 else { return false }
var values: [Int] = []
for octet in octets {
// 拒绝 "01"、"+1"、空段这类非规范写法
guard !octet.isEmpty, octet.count <= 3, octet.allSatisfy({ $0.isASCII && $0.isNumber }),
let value = Int(octet), (0...255).contains(value),
octet.count == 1 || !octet.hasPrefix("0") else { return false }
values.append(value)
}
switch (values[0], values[1]) {
case (10, _): return true
case (127, _): return true
case (169, 254): return true
case (172, 16...31): return true
case (192, 168): return true
default: return false
}
}
}