@umutcansu/react-native-pinvault 0.0.0-stage → 2.3.2

package/ios/Core/JSEnvironmentGuard.swift

@@ -0,0 +1,129 @@
+// `environmentGuard` answered by a JS callback. Fail closed: no answer in time,
+// an unknown request id — every one of them is a refusal.
+//
+// PinVault's `EnvironmentGuard.allows(_:)` is synchronous and runs on the
+// calling task, i.e. on a thread of Swift's shared cooperative pool. Waiting
+// there for JS would hold that thread for up to the timeout (30 s at most). So
+// the bridge asks JS *before* it calls the library (`withVerdicts`): the wait
+// is a suspended continuation, no thread is held, and the library's
+// synchronous check answers at once from that verdict. Only an operation the
+// library starts on its own (a background refresh picking up a pending
+// enrollment, a periodic vault sync) finds no verdict and waits on its own
+// thread, bounded by the timeout.
+import Foundation
+import PinVault
+
+public final class JSEnvironmentGuard: EnvironmentGuard, @unchecked Sendable {
+    public static let defaultTimeoutMs: Int64 = 5000
+    public static let minTimeoutMs: Int64 = 100
+    public static let maxTimeoutMs: Int64 = 30_000
+
+    /// One question to JS; answered exactly once (by JS, or `false` at the deadline).
+    private final class Pending: @unchecked Sendable {
+        private let lock = NSLock()
+        private var done = false
+        private let deliver: (Bool) -> Void
+
+        init(_ deliver: @escaping (Bool) -> Void) { self.deliver = deliver }
+
+        func finish(_ allowed: Bool) {
+            lock.lock()
+            let first = !done
+            done = true
+            lock.unlock()
+            if first { deliver(allowed) }
+        }
+    }
+
+    private let timeoutMs: Int64
+    private let ask: (_ requestId: String, _ operation: String) -> Void
+    private let lock = NSLock()
+    private var pending: [String: Pending] = [:]
+    /// Verdicts asked before a bridge call, per operation, while that call runs.
+    private var verdicts: [GuardedOperation: [(UUID, Bool)]] = [:]
+
+    public init(timeoutMs: Int64, ask: @escaping (_ requestId: String, _ operation: String) -> Void) {
+        self.timeoutMs = timeoutMs
+        self.ask = ask
+    }
+
+    private func send(_ operation: GuardedOperation, _ deliver: @escaping (Bool) -> Void) {
+        let id = UUID().uuidString
+        let request = Pending { [weak self] allowed in
+            self?.lock.lock()
+            self?.pending.removeValue(forKey: id)
+            self?.lock.unlock()
+            deliver(allowed)
+        }
+        lock.lock(); pending[id] = request; lock.unlock()
+        DispatchQueue.global().asyncAfter(deadline: .now() + .milliseconds(Int(timeoutMs))) { request.finish(false) }
+        ask(id, operation.rawValue)
+    }
+
+    /// JS's verdict on `operation`, waited for without holding a thread.
+    public func verdict(_ operation: GuardedOperation) async -> Bool {
+        await withCheckedContinuation { (continuation: CheckedContinuation<Bool, Never>) in
+            send(operation) { continuation.resume(returning: $0) }
+        }
+    }
+
+    /// Runs `body` (a library call) with JS's verdicts on `operations` asked
+    /// beforehand: the library's synchronous ``allows(_:)`` reads them.
+    public func withVerdicts<T>(_ operations: [GuardedOperation], _ body: () async throws -> T) async rethrows -> T {
+        var asked: [(GuardedOperation, Bool)] = []
+        for operation in operations { asked.append((operation, await verdict(operation))) }
+        let token = UUID()
+        hold(asked, token)
+        defer { release(asked.map(\.0), token) }
+        return try await body()
+    }
+
+    private func hold(_ asked: [(GuardedOperation, Bool)], _ token: UUID) {
+        lock.lock(); defer { lock.unlock() }
+        for (operation, allowed) in asked { verdicts[operation, default: []].append((token, allowed)) }
+    }
+
+    private func release(_ operations: [GuardedOperation], _ token: UUID) {
+        lock.lock(); defer { lock.unlock() }
+        for operation in operations { verdicts[operation]?.removeAll { $0.0 == token } }
+    }
+
+    public func allows(_ operation: GuardedOperation) throws -> Bool {
+        lock.lock()
+        let held = verdicts[operation] ?? []
+        lock.unlock()
+        // Asked before the bridge call that runs now: no waiting. A refusal wins.
+        if !held.isEmpty { return held.allSatisfy { $0.1 } }
+        // The library asks on its own: wait here, bounded by the timeout.
+        let semaphore = DispatchSemaphore(value: 0)
+        let result = Locked(false)
+        send(operation) { allowed in
+            result.set(allowed)
+            semaphore.signal()
+        }
+        guard semaphore.wait(timeout: .now() + .milliseconds(Int(timeoutMs) + 50)) == .success else { return false }
+        return result.get()
+    }
+
+    /// JS's verdict; ignored when the request is unknown or already timed out.
+    public func answer(_ requestId: String, allowed: Bool) {
+        lock.lock()
+        let request = pending[requestId]
+        lock.unlock()
+        request?.finish(allowed)
+    }
+
+    public var pendingCount: Int {
+        lock.lock(); defer { lock.unlock() }
+        return pending.count
+    }
+
+    /// A value behind a lock (the answer crosses threads).
+    private final class Locked<V>: @unchecked Sendable {
+        private let lock = NSLock()
+        private var value: V
+        init(_ value: V) { self.value = value }
+        func set(_ v: V) { lock.lock(); value = v; lock.unlock() }
+        func get() -> V { lock.lock(); defer { lock.unlock() }; return value }
+    }
+}

package/ios/Core/NativeSecurity.swift

@@ -0,0 +1,197 @@
+// The app's native security file (the Swift twin of NativeSecurity.kt): the
+// trust anchors and relaxations of `start(config)` declared outside the JS
+// bundle, which an OTA update (CodePush, Expo Updates) or an edited bundle can
+// change. The file is a resource of the app bundle (`pinvault_security.json`),
+// which the code signature seals. Same JSON shape as a JS config subset:
+//
+//   { "configApis": [{ "id", "bootstrapPins", "signaturePublicKeys", "requiredSignatures",
+//                      "recoveryPublicKeys", "requiredRecoverySignatures", "serverScope",
+//                      "clientCaPins", "allowUnsigned", "allowUnpinnedConfigApi",
+//                      "allowServerGeneratedKey" }],
+//     "staticPins": { "pins": [...], "version": 1 } }
+//
+// When the file is there: every JS Config API (and JS `staticPins`) must be
+// declared in it; a declared field is the value (JS may omit or repeat it, a
+// different value is refused); the three relaxations need the file's consent.
+// Without it, release builds refuse the three relaxations from JS.
+import Foundation
+import PinVault
+
+public struct NativeSecurity {
+    public static let resourceName = "pinvault_security"
+    static let maxFileChars = 256 * 1024
+
+    public struct Block {
+        let bootstrapPins: [HostPin]?
+        let signaturePublicKeys: [String]?
+        let requiredSignatures: Int?
+        let recoveryPublicKeys: [String]?
+        let requiredRecoverySignatures: Int?
+        let serverScope: String?
+        let clientCaPins: [String]?
+        let allowUnsigned: Bool
+        let allowUnpinnedConfigApi: Bool
+        let allowServerGeneratedKey: Bool
+    }
+
+    /// Where the file came from, for messages.
+    public let source: String
+    let blocks: [String: Block]
+    let staticPins: CertificateConfig?
+
+    /// The file from `bundle`; nil when the app ships none. A broken file throws `BridgeInputError`.
+    public static func load(from bundle: Bundle = .main) throws -> NativeSecurity? {
+        guard let url = bundle.url(forResource: resourceName, withExtension: "json") else { return nil }
+        let source = "\(resourceName).json (app bundle)"
+        guard let data = try? Data(contentsOf: url) else {
+            throw BridgeInputError("native security file \(source): cannot be read")
+        }
+        guard let text = String(data: data, encoding: .utf8) else {
+            throw BridgeInputError("native security file \(source): not UTF-8")
+        }
+        return try parse(text, source: source)
+    }
+
+    public static func parse(_ text: String, source: String) throws -> NativeSecurity {
+        do {
+            let root = try StrictJSON.parseObject(text, path: source, maxChars: maxFileChars)
+            var blocks: [String: Block] = [:]
+            for b in try root.objectList("configApis", maxItems: ConfigParser.maxConfigApis) ?? [] {
+                let id = try b.requireString("id", maxLength: 128)
+                if blocks[id] != nil { throw BridgeInputError("\(b.path).id: '\(id)' is declared twice") }
+                blocks[id] = Block(
+                    bootstrapPins: try b.objectList("bootstrapPins", maxItems: ConfigParser.maxPins)?.map(ConfigParser.hostPin),
+                    signaturePublicKeys: try b.stringList("signaturePublicKeys", maxItems: 16, maxLength: ConfigParser.keyLength, multiline: true),
+                    requiredSignatures: try b.int("requiredSignatures", min: 1, max: 16),
+                    recoveryPublicKeys: try b.stringList("recoveryPublicKeys", maxItems: 16, maxLength: ConfigParser.keyLength, multiline: true),
+                    requiredRecoverySignatures: try b.int("requiredRecoverySignatures", min: 1, max: 16),
+                    serverScope: try b.string("serverScope", maxLength: 128),
+                    clientCaPins: try b.stringList("clientCaPins", maxItems: 16, maxLength: 128),
+                    allowUnsigned: try b.bool("allowUnsigned") == true,
+                    allowUnpinnedConfigApi: try b.bool("allowUnpinnedConfigApi") == true,
+                    allowServerGeneratedKey: try b.bool("allowServerGeneratedKey") == true
+                )
+                try b.finish()
+            }
+            let staticPins = try root.object("staticPins").map(ConfigParser.staticPins)
+            try root.finish()
+            if blocks.isEmpty && staticPins == nil {
+                throw BridgeInputError("\(source): declares neither configApis nor staticPins")
+            }
+            return NativeSecurity(source: source, blocks: blocks, staticPins: staticPins)
+        } catch let e as BridgeInputError {
+            throw e.message.hasPrefix("native security file") ? e : BridgeInputError("native security file \(e.message)")
+        } catch {
+            throw BridgeInputError("native security file \(source): \((error as? PinVaultError)?.message ?? "\(error)")")
+        }
+    }
+
+    // MARK: comparison (the order of lists does not matter)
+
+    static func sameKeys(_ a: [String], _ b: [String]) -> Bool {
+        Set(a.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }) == Set(b.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) })
+    }
+
+    private static func pinKey(_ p: HostPin) -> String {
+        [p.hostname.lowercased(), p.sha256.sorted().joined(separator: ","), "\(p.version)", "\(p.forceUpdate)", "\(p.mtls)",
+         p.clientCertVersion.map { "\($0)" } ?? "nil"].joined(separator: "|")
+    }
+
+    static func samePins(_ a: [HostPin], _ b: [HostPin]) -> Bool {
+        a.map(pinKey).sorted() == b.map(pinKey).sorted()
+    }
+
+    static func sameStaticPins(_ a: CertificateConfig, _ b: CertificateConfig) -> Bool {
+        a.version == b.version && a.forceUpdate == b.forceUpdate && samePins(a.pins, b.pins)
+    }
+}
+
+/// What JS asked for in one `configApis[i]` entry, before the native policy.
+struct SecurityFields {
+    var bootstrapPins: [HostPin]?
+    var oneKey: String?
+    var keys: [String]?
+    var requiredSignatures: Int?
+    var recoveryKeys: [String]?
+    var requiredRecovery: Int?
+    var serverScope: String?
+    var clientCaPins: [String]?
+    var allowUnsigned: Bool
+    var allowUnpinned: Bool
+    var allowServerKey: Bool
+}
+
+enum SecurityPolicy {
+    static let relaxationsHint =
+        "a release build takes it only from the app's native security file (\(NativeSecurity.resourceName).json, README \"Native security file\")"
+
+    static func apply(path: String, id: String, js: SecurityFields, native: NativeSecurity?, release: Bool) throws -> SecurityFields {
+        guard let native else {
+            if release {
+                if js.allowUnsigned { throw BridgeInputError("\(path).allowUnsigned: refused from JS; \(relaxationsHint)") }
+                if js.allowUnpinned { throw BridgeInputError("\(path).allowUnpinnedConfigApi: refused from JS; \(relaxationsHint)") }
+                if js.allowServerKey { throw BridgeInputError("\(path).allowServerGeneratedKey: refused from JS; \(relaxationsHint)") }
+            }
+            return js
+        }
+        guard let block = native.blocks[id] else {
+            throw BridgeInputError("\(path): Config API '\(id)' is not declared in the app's native security file (\(native.source))")
+        }
+        func fixed(_ key: String) -> BridgeInputError {
+            BridgeInputError("\(path).\(key): differs from the app's native security file (\(native.source)); the native value is fixed")
+        }
+        func relaxation(_ key: String, _ asked: Bool, _ allowed: Bool) throws {
+            if asked && !allowed {
+                throw BridgeInputError("\(path).\(key): refused; the app's native security file (\(native.source)) does not allow it")
+            }
+        }
+        try relaxation("allowUnsigned", js.allowUnsigned, block.allowUnsigned)
+        try relaxation("allowUnpinnedConfigApi", js.allowUnpinned, block.allowUnpinnedConfigApi)
+        try relaxation("allowServerGeneratedKey", js.allowServerKey, block.allowServerGeneratedKey)
+
+        var out = js
+        if let n = block.bootstrapPins {
+            if let j = js.bootstrapPins, !NativeSecurity.samePins(j, n) { throw fixed("bootstrapPins") }
+            out.bootstrapPins = n
+        }
+        if let n = block.signaturePublicKeys {
+            if let j = js.oneKey.map({ [$0] }) ?? js.keys {
+                if !NativeSecurity.sameKeys(j, n) { throw fixed(js.oneKey != nil ? "signaturePublicKey" : "signaturePublicKeys") }
+            } else {
+                out.keys = n
+            }
+        }
+        func one<T: Equatable>(_ key: String, _ n: T?, _ j: T?) throws -> T? {
+            guard let n else { return j }
+            if let j, j != n { throw fixed(key) }
+            return n
+        }
+        func list(_ key: String, _ n: [String]?, _ j: [String]?) throws -> [String]? {
+            guard let n else { return j }
+            if let j, !NativeSecurity.sameKeys(j, n) { throw fixed(key) }
+            return n
+        }
+        out.requiredSignatures = try one("requiredSignatures", block.requiredSignatures, js.requiredSignatures)
+        out.recoveryKeys = try list("recoveryPublicKeys", block.recoveryPublicKeys, js.recoveryKeys)
+        out.requiredRecovery = try one("requiredRecoverySignatures", block.requiredRecoverySignatures, js.requiredRecovery)
+        out.serverScope = try one("serverScope", block.serverScope, js.serverScope)
+        out.clientCaPins = try list("clientCaPins", block.clientCaPins, js.clientCaPins)
+        // The file is the source of truth for the relaxations too.
+        out.allowUnsigned = block.allowUnsigned
+        out.allowUnpinned = block.allowUnpinnedConfigApi
+        out.allowServerKey = block.allowServerGeneratedKey
+        return out
+    }
+
+    static func staticPins(path: String, js: CertificateConfig?, native: NativeSecurity?) throws -> CertificateConfig? {
+        guard let native else { return js }
+        guard let n = native.staticPins else {
+            if js != nil { throw BridgeInputError("\(path): not declared in the app's native security file (\(native.source))") }
+            return nil
+        }
+        if let js, !NativeSecurity.sameStaticPins(js, n) {
+            throw BridgeInputError("\(path): differs from the app's native security file (\(native.source)); the native value is fixed")
+        }
+        return n
+    }
+}

package/ios/Core/PinnedFetch.swift

@@ -0,0 +1,119 @@
+// The plugin's own `fetch` (the Swift twin of PinnedFetch.kt): parsed strictly,
+// sent through the pinned session the library hands out
+// (`PinVault.shared.session()` or `session(settings:)`), HTTPS only, bounded.
+// PinVault's sessions never follow a redirect from https into plain http.
+import Foundation
+import PinVault
+
+public struct FetchRequest {
+    public let url: URL
+    public let method: String
+    public let headers: [(String, String)]
+    public let body: Data?
+    public let responseEncoding: String
+    public let timeoutMs: Int64?
+    public let maxResponseBytes: Int64
+    public let settings: HttpConnectionSettings?
+}
+
+public struct ResponseTooLargeError: Error, CustomStringConvertible {
+    public let limit: Int64
+    public var description: String { "Response larger than \(limit) bytes" }
+}
+
+public enum PinnedFetch {
+    public static let maxRequestBytes: Int64 = 10 * 1024 * 1024
+    public static let defaultMaxResponseBytes: Int64 = 10 * 1024 * 1024
+    public static let maxResponseBytesLimit: Int64 = 50 * 1024 * 1024
+    static let methods: Set<String> = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+    static let tokenChars = CharacterSet(charactersIn: "!#$%&'*+.^_`|~0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-")
+
+    public static func parse(_ json: String) throws -> FetchRequest {
+        let f = try StrictJSON.parseObject(json, path: "request", maxChars: Int(maxRequestBytes * 4 / 3) + 64 * 1024)
+        let urlText = try f.requireString("url", maxLength: 8192)
+        guard let url = URL(string: urlText), url.host != nil else { throw BridgeInputError("request.url: not a valid URL") }
+        guard url.scheme?.lowercased() == "https" else {
+            throw BridgeInputError("request.url: only https:// URLs go through the pinned client")
+        }
+        let method = (try f.string("method", maxLength: 16) ?? "GET").uppercased()
+        guard methods.contains(method) else { throw BridgeInputError("request.method: '\(method)' is not supported") }
+        var headers: [(String, String)] = []
+        for (name, value) in (try f.stringMap("headers", maxItems: 128, maxKeyLength: 256, maxValueLength: 8192) ?? [:]).sorted(by: { $0.key < $1.key }) {
+            guard name.unicodeScalars.allSatisfy({ tokenChars.contains($0) }) else {
+                throw BridgeInputError("request.headers: '\(name.prefix(40))' is not a header name")
+            }
+            if value.unicodeScalars.contains(where: { $0 == "\r" || $0 == "\n" || $0.value == 0 }) {
+                throw BridgeInputError("request.headers.\(name): line breaks are not allowed")
+            }
+            headers.append((name, value))
+        }
+        let bodyText = try f.text("body", maxLength: Int(maxRequestBytes * 4 / 3) + 4)
+        let bodyEncoding = try ResultMapper.checkEncoding(try f.string("bodyEncoding", maxLength: 16) ?? ResultMapper.utf8)
+        var body: Data?
+        if let bodyText {
+            if bodyEncoding == ResultMapper.base64 {
+                guard let d = Data(base64Encoded: bodyText) else { throw BridgeInputError("request.body: not valid Base64") }
+                body = d
+            } else {
+                body = Data(bodyText.utf8)
+            }
+        }
+        if let body, Int64(body.count) > maxRequestBytes { throw BridgeInputError("request.body: larger than \(maxRequestBytes) bytes") }
+        if body != nil && (method == "GET" || method == "HEAD") { throw BridgeInputError("request.body: \(method) has no body") }
+        let responseEncoding = try ResultMapper.checkEncoding(try f.string("responseEncoding", maxLength: 16) ?? ResultMapper.utf8)
+        let timeoutMs = try f.int64("timeoutMs", min: 1, max: 10 * 60 * 1000)
+        let maxResponse = try f.int64("maxResponseBytes", min: 1, max: maxResponseBytesLimit) ?? defaultMaxResponseBytes
+        var settings: HttpConnectionSettings?
+        if let s = try f.object("settings") {
+            let d = HttpConnectionSettings()
+            settings = HttpConnectionSettings(
+                connectTimeout: try s.int64("connectTimeout", min: 0, max: 600) ?? d.connectTimeout,
+                readTimeout: try s.int64("readTimeout", min: 0, max: 600) ?? d.readTimeout,
+                writeTimeout: try s.int64("writeTimeout", min: 0, max: 600) ?? d.writeTimeout,
+                callTimeout: try s.int64("callTimeout", min: 0, max: 600) ?? d.callTimeout
+            )
+            try s.finish()
+        }
+        try f.finish()
+        return FetchRequest(
+            url: url, method: method, headers: headers, body: body, responseEncoding: responseEncoding,
+            timeoutMs: timeoutMs, maxResponseBytes: maxResponse, settings: settings
+        )
+    }
+
+    public static func urlRequest(_ r: FetchRequest) -> URLRequest {
+        var request = URLRequest(url: r.url)
+        request.httpMethod = r.method
+        for (name, value) in r.headers { request.addValue(value, forHTTPHeaderField: name) }
+        request.httpBody = r.body
+        if let t = r.timeoutMs { request.timeoutInterval = Double(t) / 1000 }
+        return request
+    }
+
+    /// Runs `request` on `session` (a pinned session from the library). The
+    /// library stops reading once the body passes `maxResponseBytes` (a
+    /// declared `Content-Length` over it is refused before the body is read).
+    public static func execute(_ session: PinnedSession, _ r: FetchRequest) async throws -> [String: Any] {
+        let (data, response) = try await session.data(for: urlRequest(r), maxResponseBytes: r.maxResponseBytes)
+        guard let http = response as? HTTPURLResponse else { throw BridgeInputError("not an HTTP response") }
+        return try map(http, data, r)
+    }
+
+    public static func map(_ http: HTTPURLResponse, _ data: Data, _ r: FetchRequest) throws -> [String: Any] {
+        // The transport enforced the bound while reading; this is a second look.
+        if Int64(data.count) > r.maxResponseBytes { throw ResponseTooLargeError(limit: r.maxResponseBytes) }
+        var headers: [String: String] = [:]
+        for (k, v) in http.allHeaderFields {
+            guard let name = (k as? String)?.lowercased() else { continue }
+            let value = "\(v)"
+            headers[name] = headers[name].map { "\($0), \(value)" } ?? value
+        }
+        return [
+            "status": http.statusCode,
+            "url": http.url?.absoluteString ?? r.url.absoluteString,
+            "headers": headers,
+            "body": ResultMapper.encode(data, r.responseEncoding),
+            "bodyEncoding": r.responseEncoding,
+        ]
+    }
+}

package/ios/Core/ReactNetworking.swift

@@ -0,0 +1,172 @@
+// React Native's own https traffic (fetch, XMLHttpRequest, <Image>) through
+// PinVault's pinned session — the engine behind RNPinVaultURLRequestHandler,
+// the RCTURLRequestHandler that RCTNetworking prefers over its
+// RCTHTTPRequestHandler for https. Foundation only, so it is tested on the Mac.
+//
+// The rules are the Android hook's:
+// - before `start()` (and after a start that failed: the library's session
+//   then refuses every request) every https request fails — fail closed;
+// - pinning, `PinVault-Token`, pin-mismatch recovery: the library's session;
+//   a redirect from https into plain http is not followed (the library's
+//   sessions never follow one; the 3xx is the answer);
+// - no cookies and no cache (the library's sessions are ephemeral, without a
+//   cookie store or URL cache);
+// - the answer is bounded (`maxResponseBytes`, default 50 MiB): the library
+//   stops reading past it.
+//
+// The library hands out whole answers (`PinnedSession.data(for:)`), so RN
+// gets the response, then the body in chunks, then the completion — after the
+// body has been read; progress events arrive at the end.
+import Foundation
+
+public enum ReactNetworking {
+    public static let defaultMaxResponseBytes: Int64 = 50 * 1024 * 1024
+    public static let maxResponseBytesLimit: Int64 = 256 * 1024 * 1024
+    /// Body pieces handed to RN's delegate.
+    public static let chunkSize = 64 * 1024
+    public static let errorDomain = "PinVault"
+
+    /// What a request needs: `send` = the pinned session's bounded `data(for:maxResponseBytes:)`,
+    /// nil before `start()`.
+    public typealias Send = @Sendable (URLRequest, Int64) async throws -> (Data, URLResponse)
+
+    /// RN's `RCTURLRequestDelegate`, as blocks (Core does not link React).
+    public struct Callbacks: @unchecked Sendable {
+        public let didSendData: (Int64) -> Void
+        public let didReceiveResponse: (URLResponse) -> Void
+        public let didReceiveData: (Data) -> Void
+        public let didComplete: ((any Error)?) -> Void
+
+        public init(
+            didSendData: @escaping (Int64) -> Void,
+            didReceiveResponse: @escaping (URLResponse) -> Void,
+            didReceiveData: @escaping (Data) -> Void,
+            didComplete: @escaping ((any Error)?) -> Void
+        ) {
+            self.didSendData = didSendData
+            self.didReceiveResponse = didReceiveResponse
+            self.didReceiveData = didReceiveData
+            self.didComplete = didComplete
+        }
+    }
+
+    /// Only https: plain http stays with RN's own handler (ATS refuses it unless the app allows it).
+    public static func handles(_ request: URLRequest) -> Bool {
+        request.url?.scheme?.lowercased() == "https"
+    }
+
+    /// The error RN hands to JS (`fetch` rejects with "Network request failed").
+    public static func error(_ name: String, _ message: String) -> NSError {
+        NSError(domain: errorDomain, code: 1, userInfo: [
+            NSLocalizedDescriptionKey: "\(name): \(message)",
+            "exceptionName": name,
+        ])
+    }
+
+    /// ``prepare(_:send:maxResponseBytes:describe:callbacks:)`` + `resume()`.
+    @discardableResult
+    public static func start(
+        _ request: URLRequest,
+        send: Send?,
+        maxResponseBytes: Int64,
+        describe: @escaping @Sendable (any Error) -> (String, String),
+        callbacks: Callbacks
+    ) -> ReactNetworkingTask {
+        let task = prepare(request, send: send, maxResponseBytes: maxResponseBytes, describe: describe, callbacks: callbacks)
+        task.resume()
+        return task
+    }
+
+    /// The request, not started yet: the task is the request token RN keeps,
+    /// and nothing reaches the delegate before `resume()` (RN's rule: the
+    /// token first, then the callbacks).
+    /// - Parameter describe: an error → (exception name, message) for JS.
+    public static func prepare(
+        _ request: URLRequest,
+        send: Send?,
+        maxResponseBytes: Int64,
+        describe: @escaping @Sendable (any Error) -> (String, String),
+        callbacks: Callbacks
+    ) -> ReactNetworkingTask {
+        let task = ReactNetworkingTask(callbacks)
+        let sent = Int64(request.httpBody?.count ?? 0)
+        task.body = {
+            guard let send else {
+                throw ReactNetworking.error(
+                    "IllegalStateException", "PinVault has not started: https requests are refused until start() returns"
+                )
+            }
+            do {
+                let (data, response) = try await send(request, maxResponseBytes)
+                return (data, response, sent)
+            } catch {
+                let (name, message) = describe(error)
+                throw ReactNetworking.error(name, message)
+            }
+        }
+        return task
+    }
+}
+
+/// One React Native request: its token, and its cancellation.
+@objc(RNPinVaultReactNetworkingTask)
+public final class ReactNetworkingTask: NSObject, @unchecked Sendable {
+    private let callbacks: ReactNetworking.Callbacks
+    private let lock = NSLock()
+    private var work: _Concurrency.Task<Void, Never>?
+    private var cancelled = false
+    /// Set by `prepare`, run by `resume`.
+    var body: (@Sendable () async throws -> (Data, URLResponse, Int64))?
+
+    init(_ callbacks: ReactNetworking.Callbacks) {
+        self.callbacks = callbacks
+    }
+
+    public var isCancelled: Bool {
+        lock.lock(); defer { lock.unlock() }
+        return cancelled
+    }
+
+    /// RN cancelled (`cancelRequest:`): the request stops, the delegate hears nothing more.
+    @objc public func cancel() {
+        lock.lock()
+        cancelled = true
+        let w = work
+        lock.unlock()
+        w?.cancel()
+    }
+
+    /// Sends the request (once).
+    @objc public func resume() {
+        lock.lock()
+        let body = self.body
+        self.body = nil
+        lock.unlock()
+        guard let body else { return }
+        let callbacks = self.callbacks
+        let w = _Concurrency.Task.detached { [self] in
+            do {
+                let (data, response, sent) = try await body()
+                if isCancelled { return }
+                if sent > 0 { callbacks.didSendData(sent) }
+                callbacks.didReceiveResponse(response)
+                var offset = 0
+                while offset < data.count {
+                    if isCancelled { return }
+                    let end = min(offset + ReactNetworking.chunkSize, data.count)
+                    callbacks.didReceiveData(data.subdata(in: offset..<end))
+                    offset = end
+                }
+                callbacks.didComplete(nil)
+            } catch {
+                if isCancelled { return }
+                callbacks.didComplete(error)
+            }
+        }
+        lock.lock()
+        work = w
+        let alreadyCancelled = cancelled
+        lock.unlock()
+        if alreadyCancelled { w.cancel() }
+    }
+}