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

package/ios/Core/NativeSecurity.swift

@@ -0,0 +1,303 @@
+// 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", "url", "attestation", "tokenHosts", "proofOfPossession",
+//                      "clientCertHosts",
+//                      "enrollmentUrl", "renewalUrl" }],
+//     "staticPins": { "pins": [...], "version": 1 },
+//     "require": { "requireUnlockedDevice", "requireHardwareBackedKeys", "managedTrustRoots",
+//                  "wipeVaultFilesOnRevocation", "requireCaTrust", "expectedBundleIds",
+//                  "expectedTeamIds", "userAuthStrength", "expiredConfigGraceSeconds",
+//                  "vaultFileMaxOfflineAgeSeconds", "expectedSignerSha256" (Android's, read for the shape) },
+//     "vaultFiles": [{ "key", "signaturePublicKey", "encryption", "userAuth", "maxOfflineAgeSeconds" }] }
+//
+// 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;
+// `attestation: true` and `proofOfPossession: true` cannot be switched off; `require` only tightens (its
+// protections stay on, its `requireCaTrust` hosts are added to JS's, its
+// expected ids are fixed, its grace is the most JS may ask for); `vaultFiles`
+// fixes those files' signature key, encryption and lock, and a JS vault file
+// it does not name is refused.
+//
+// Without it, a release build refuses a config with Config APIs or static
+// pins — the trust anchors would come from JS alone — unless the app's
+// Info.plist says `PinVaultAllowNoNativeSecurityFile` = YES; the three
+// relaxations stay refused from JS then. A release build caps
+// `expiredConfigGrace` at 7 days whatever the file says.
+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
+        var url: String? = nil
+        var attestation = false
+        var tokenHosts: [String]? = nil
+        var proofOfPossession = false
+        var clientCertHosts: [String]? = nil
+        var enrollmentUrl: String? = nil
+        var renewalUrl: String? = nil
+    }
+
+    /// The `require` section: protections JS cannot switch off.
+    public struct Require {
+        var requireUnlockedDevice = false
+        var requireHardwareBackedKeys = false
+        var managedTrustRoots = false
+        var wipeVaultFilesOnRevocation = false
+        var requireCaTrust: [String]? = nil
+        var expectedBundleIds: [String]? = nil
+        var expectedTeamIds: [String]? = nil
+        /// The most `expiredConfigGrace` JS may set; nil = only the release cap.
+        var expiredConfigGraceMs: Int64? = nil
+        /// The most `vaultFileMaxOfflineAge` JS may set (and the value when JS sets none).
+        var vaultFileMaxOfflineAgeMs: Int64? = nil
+        /// `ios.userAuthStrength`, fixed.
+        var userAuthStrength: UserAuthStrength? = nil
+    }
+
+    /// One `vaultFiles` entry: what JS cannot change about that file.
+    struct VaultFilePolicy {
+        let signaturePublicKey: String?
+        let encryption: VaultFileEncryption?
+        let userAuth: UserAuth?
+        /// The most `maxOfflineAge` JS may give this file (and the value when JS gives none).
+        var maxOfflineAgeMs: Int64? = nil
+    }
+
+    /// The Info.plist key with which an app accepts a release start without the file.
+    public static let noFileInfoKey = "PinVaultAllowNoNativeSecurityFile"
+    /// The longest `expiredConfigGrace` a release build takes.
+    public static let maxReleaseGraceMs: Int64 = 7 * 24 * 3600 * 1000
+    static let maxOfflineAgeS: Int64 = 10 * 365 * 24 * 3600
+
+    /// Where the file came from, for messages.
+    public let source: String
+    let blocks: [String: Block]
+    let staticPins: CertificateConfig?
+    var require = Require()
+    /// Nil when the file has no `vaultFiles` section.
+    var vaultFiles: [String: VaultFilePolicy]? = nil
+
+    /// True when the app's Info.plist accepts a release start without the file.
+    public static func noFileAllowed(_ bundle: Bundle = .main) -> Bool {
+        (bundle.object(forInfoDictionaryKey: noFileInfoKey) as? Bool) == true
+    }
+
+    /// 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,
+                    url: try ConfigParser.httpsUrl(b, "url"),
+                    attestation: try b.bool("attestation") == true,
+                    tokenHosts: try b.stringList("tokenHosts", maxItems: 64, maxLength: 255),
+                    proofOfPossession: try b.bool("proofOfPossession") == true,
+                    clientCertHosts: try b.stringList("clientCertHosts", maxItems: 64, maxLength: 2048),
+                    enrollmentUrl: try ConfigParser.httpsUrl(b, "enrollmentUrl"),
+                    renewalUrl: try ConfigParser.httpsUrl(b, "renewalUrl")
+                )
+                try b.finish()
+            }
+            let staticPins = try root.object("staticPins").map(ConfigParser.staticPins)
+            var require = Require()
+            if let r = try root.object("require") {
+                require.requireUnlockedDevice = try r.bool("requireUnlockedDevice") == true
+                require.requireHardwareBackedKeys = try r.bool("requireHardwareBackedKeys") == true
+                require.managedTrustRoots = try r.bool("managedTrustRoots") == true
+                require.wipeVaultFilesOnRevocation = try r.bool("wipeVaultFilesOnRevocation") == true
+                require.requireCaTrust = try r.stringList("requireCaTrust", maxItems: 64, maxLength: 255)
+                require.expectedBundleIds = try r.stringList("expectedBundleIds", maxItems: 16, maxLength: 255)
+                require.expectedTeamIds = try r.stringList("expectedTeamIds", maxItems: 16, maxLength: 32)
+                require.expiredConfigGraceMs = try r.int64("expiredConfigGraceSeconds", min: 0, max: maxReleaseGraceMs / 1000).map { $0 * 1000 }
+                require.vaultFileMaxOfflineAgeMs = try r.int64("vaultFileMaxOfflineAgeSeconds", min: 1, max: maxOfflineAgeS).map { $0 * 1000 }
+                require.userAuthStrength = try r.enumValue("userAuthStrength", UserAuthStrength.self)
+                // Android-only (signer digests): read for the shape, used by the Android side.
+                _ = try r.stringList("expectedSignerSha256", maxItems: 16, maxLength: 128)
+                try r.finish()
+            }
+            var vaultFiles: [String: VaultFilePolicy]?
+            if let list = try root.objectList("vaultFiles", maxItems: ConfigParser.maxVaultFiles) {
+                var map: [String: VaultFilePolicy] = [:]
+                for f in list {
+                    let key = try f.requireString("key", maxLength: 128)
+                    if map[key] != nil { throw BridgeInputError("\(f.path).key: '\(key)' is declared twice") }
+                    map[key] = VaultFilePolicy(
+                        signaturePublicKey: try f.string("signaturePublicKey", maxLength: ConfigParser.keyLength, multiline: true),
+                        encryption: try f.enumValue("encryption", VaultFileEncryption.self),
+                        userAuth: try f.enumValue("userAuth", UserAuth.self),
+                        maxOfflineAgeMs: try f.int64("maxOfflineAgeSeconds", min: 1, max: maxOfflineAgeS).map { $0 * 1000 }
+                    )
+                    try f.finish()
+                }
+                vaultFiles = map
+            }
+            try root.finish()
+            if blocks.isEmpty && staticPins == nil {
+                throw BridgeInputError("\(source): declares neither configApis nor staticPins")
+            }
+            var native = NativeSecurity(source: source, blocks: blocks, staticPins: staticPins)
+            native.require = require
+            native.vaultFiles = vaultFiles
+            return native
+        } 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() }
+    }
+}