apple_kit

Apple-native services for Radroots iOS and macOS apps
git clone https://radroots.dev/git/apple_kit.git
Log | Files | Refs | README | LICENSE

commit c27dae18746654ff77d5fc37059f7e5ba0664e3a
parent 69c1b1eb114bc603fc19e61386f5a27a2e3b2180
Author: triesap <tyson@radroots.org>
Date:   Wed, 14 Oct 2026 06:30:21 +0000

transfer: Validate original request field controls and lengths

- Refuse controls and oversized original fields hidden by trimming.
- Preserve accepted raw whitespace, Unicode and character-count limits.
- Retain thirteen actual constructor cases without network effects.
- Verify formatting, all 326 tests, exact public API and supply chain.

Diffstat:
MREADME | 7+++++++
MSources/RadrootsKit/RadrootsBackgroundTransferValidation.swift | 67++++++++++++++++++++++++++++++++++++++++---------------------------
ATests/RadrootsKitTests/RadrootsTransferOriginalFieldTests.swift | 75+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 122 insertions(+), 27 deletions(-)

diff --git a/README b/README @@ -47,6 +47,13 @@ identifier containing one Apple filesystem component. Slash, NUL and complete `.` or `..` components fail with `invalidRequest` before filesystem access. Valid Unicode, spaces, dots within names and literal backslashes are preserved. +## Transfer request fields + +Control-character and length checks apply to the original header and metadata +fields. Header names allow 80 characters and values 8,192; metadata keys allow +80 characters and values 500. Accepted values retain their original whitespace +and Unicode form. Blank fields remain invalid. + ## Copyright Except as otherwise noted, all files in the `apple_kit` distribution are diff --git a/Sources/RadrootsKit/RadrootsBackgroundTransferValidation.swift b/Sources/RadrootsKit/RadrootsBackgroundTransferValidation.swift @@ -10,8 +10,9 @@ public enum RadrootsBackgroundTransferValidation { throw RadrootsBackgroundTransferError.invalidRequest } guard - trimmed.range(of: "^[a-z0-9][a-z0-9._-]*[a-z0-9]$|^[a-z0-9]$", options: .regularExpression) - != nil + trimmed.range( + of: "^[a-z0-9][a-z0-9._-]*[a-z0-9]$|^[a-z0-9]$", options: .regularExpression) + != nil else { throw RadrootsBackgroundTransferError.invalidRequest } @@ -33,7 +34,7 @@ public enum RadrootsBackgroundTransferValidation { try validate(headers: headers) try validate(metadata: metadata) guard maximumTransferBytes > 0, - maximumTransferBytes <= RadrootsBackgroundTransferRequest.absoluteMaximumTransferBytes + maximumTransferBytes <= RadrootsBackgroundTransferRequest.absoluteMaximumTransferBytes else { throw RadrootsBackgroundTransferError.invalidRequest } @@ -42,13 +43,14 @@ public enum RadrootsBackgroundTransferValidation { } if let expectedSourceSHA256 { guard case .upload = operation, - expectedSourceSHA256.range(of: "^[0-9a-f]{64}$", options: .regularExpression) != nil + expectedSourceSHA256.range(of: "^[0-9a-f]{64}$", options: .regularExpression) != nil else { throw RadrootsBackgroundTransferError.invalidRequest } } - if case let .upload(.stagedBlob(blob)) = operation, - UInt64(blob.sizeBytes) > maximumTransferBytes { + if case .upload(.stagedBlob(let blob)) = operation, + UInt64(blob.sizeBytes) > maximumTransferBytes + { throw RadrootsBackgroundTransferError.invalidRequest } } @@ -63,7 +65,7 @@ public enum RadrootsBackgroundTransferValidation { method: RadrootsBackgroundTransferMethod, operation: RadrootsBackgroundTransferOperation ) throws { switch operation { - case let .download(destination): + case .download(let destination): guard method == .get else { throw RadrootsBackgroundTransferError.invalidRequest } @@ -71,7 +73,7 @@ public enum RadrootsBackgroundTransferValidation { throw RadrootsBackgroundTransferError.invalidRequest } try validateLocalFile(destination) - case let .upload(source): + case .upload(let source): guard method == .post || method == .put else { throw RadrootsBackgroundTransferError.invalidRequest } @@ -81,14 +83,16 @@ public enum RadrootsBackgroundTransferValidation { static func validateLocalFile(_ localFile: RadrootsBackgroundTransferLocalFile) throws { switch localFile { - case let .file(reference): + case .file(let reference): let path = reference.relativePath.trimmingCharacters(in: .whitespacesAndNewlines) guard !path.isEmpty, !NSString(string: path).isAbsolutePath, - !path.split(separator: "/", omittingEmptySubsequences: false).contains(where: { $0 == ".." }) + !path.split(separator: "/", omittingEmptySubsequences: false).contains(where: { + $0 == ".." + }) else { throw RadrootsBackgroundTransferError.invalidRequest } - case let .stagedBlob(blob): + case .stagedBlob(let blob): guard (try? RadrootsStagedBlobReference( blobID: blob.blobID, sizeBytes: blob.sizeBytes, mediaType: blob.mediaType, @@ -106,12 +110,15 @@ public enum RadrootsBackgroundTransferValidation { } for (key, value) in headers { try validateSafeText(key, field: "background transfer header name", maximumLength: 80) - guard key.range(of: "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$", options: .regularExpression) != nil, - !["connection", "content-length", "host", "transfer-encoding"].contains(key.lowercased()) + guard + key.range(of: "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$", options: .regularExpression) != nil, + !["connection", "content-length", "host", "transfer-encoding"].contains( + key.lowercased()) else { throw RadrootsBackgroundTransferError.invalidRequest } - try validateSafeText(value, field: "background transfer header value", maximumLength: 8192) + try validateSafeText( + value, field: "background transfer header value", maximumLength: 8192) } } @@ -121,12 +128,14 @@ public enum RadrootsBackgroundTransferValidation { } for (key, value) in metadata { try validateSafeText(key, field: "background transfer metadata key", maximumLength: 80) - try validateSafeText(value, field: "background transfer metadata value", maximumLength: 500) + try validateSafeText( + value, field: "background transfer metadata value", maximumLength: 500) let unsafeKey = key.lowercased() guard - !["auth", "token", "secret", "credential", "cookie", "header", "path", "url"].contains( - where: { unsafeKey.contains($0) } - ) + !["auth", "token", "secret", "credential", "cookie", "header", "path", "url"] + .contains( + where: { unsafeKey.contains($0) } + ) else { throw RadrootsBackgroundTransferError.invalidRequest } @@ -139,8 +148,9 @@ public enum RadrootsBackgroundTransferValidation { in: .whitespacesAndNewlines ).lowercased() ?? "" guard - normalized.range(of: "^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+$", options: .regularExpression) - != nil, + normalized.range( + of: "^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+$", options: .regularExpression) + != nil, normalized.utf8.count <= 127 else { throw RadrootsBackgroundTransferError.invalidRequest @@ -149,9 +159,10 @@ public enum RadrootsBackgroundTransferValidation { } static func validate( - response: RadrootsBackgroundTransferResponse, policy: RadrootsBackgroundTransferResponsePolicy + response: RadrootsBackgroundTransferResponse, + policy: RadrootsBackgroundTransferResponsePolicy ) throws { - guard (200 ... 299).contains(response.statusCode) else { + guard (200...299).contains(response.statusCode) else { throw RadrootsBackgroundTransferError.invalidRequest } if policy.maximumBodyBytes == 0 { @@ -161,8 +172,8 @@ public enum RadrootsBackgroundTransferValidation { return } guard let body = response.body, body.count <= policy.maximumBodyBytes, - let mediaType = response.mediaType, - policy.acceptedMediaTypes.contains(mediaType) + let mediaType = response.mediaType, + policy.acceptedMediaTypes.contains(mediaType) else { throw RadrootsBackgroundTransferError.invalidRequest } @@ -173,15 +184,17 @@ public enum RadrootsBackgroundTransferValidation { } } - private static func validateSafeText(_ value: String, field _: String, maximumLength: Int) throws { + private static func validateSafeText(_ value: String, field _: String, maximumLength: Int) + throws + { let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines) guard !trimmed.isEmpty else { throw RadrootsBackgroundTransferError.invalidRequest } - guard trimmed.count <= maximumLength else { + guard value.count <= maximumLength else { throw RadrootsBackgroundTransferError.invalidRequest } - guard doesNotContainControlCharacters(trimmed) else { + guard doesNotContainControlCharacters(value) else { throw RadrootsBackgroundTransferError.invalidRequest } } diff --git a/Tests/RadrootsKitTests/RadrootsTransferOriginalFieldTests.swift b/Tests/RadrootsKitTests/RadrootsTransferOriginalFieldTests.swift @@ -0,0 +1,75 @@ +import Foundation +import Testing + +@testable import RadrootsKit + +@Test(arguments: [ + "header_leading_lf", "header_trailing_cr", "header_leading_tab", + "metadata_key_lf", "metadata_value_cr", "metadata_value_tab", +]) +func transferOriginalFieldsRefuseControlCharacters(_ name: String) throws { + var headers: [String: String] = [:] + var metadata: [String: String] = [:] + switch name { + case "header_leading_lf": headers = ["X-Test": "\nowned-value"] + case "header_trailing_cr": headers = ["X-Test": "owned-value\r"] + case "header_leading_tab": headers = ["X-Test": "\towned-value"] + case "metadata_key_lf": metadata = ["\nlabel": "owned-value"] + case "metadata_value_cr": metadata = ["label": "\rowned-value"] + case "metadata_value_tab": metadata = ["label": "owned-value\t"] + default: throw TransferOriginalFieldFixtureError.unknownCase + } + #expect(throws: RadrootsBackgroundTransferError.invalidRequest) { + _ = try originalFieldRequest(headers: headers, metadata: metadata) + } +} + +@Test(arguments: ["header_value", "metadata_key", "metadata_value"]) +func transferOriginalFieldsRefuseTrimHiddenLength(_ name: String) throws { + var headers: [String: String] = [:] + var metadata: [String: String] = [:] + switch name { + case "header_value": headers = ["X-Test": String(repeating: " ", count: 8192) + "v"] + case "metadata_key": metadata = [String(repeating: " ", count: 80) + "label": "v"] + case "metadata_value": metadata = ["label": "v" + String(repeating: " ", count: 500)] + default: throw TransferOriginalFieldFixtureError.unknownCase + } + #expect(throws: RadrootsBackgroundTransferError.invalidRequest) { + _ = try originalFieldRequest(headers: headers, metadata: metadata) + } +} + +@Test(arguments: ["value", " value ", "récolte"]) +func transferOriginalFieldsPreserveValidRawValues(_ value: String) throws { + let request = try originalFieldRequest(headers: ["X-Test": value], metadata: ["label": value]) + #expect(request.headers == ["X-Test": value]) + #expect(request.metadata == ["label": value]) +} + +@Test func transferOriginalFieldsAdmitExactCharacterBoundaries() throws { + let header = String(repeating: "a", count: 8192) + let metadata = String(repeating: "é", count: 500) + let request = try originalFieldRequest( + headers: ["X-Test": header], metadata: ["label": metadata]) + #expect(request.headers["X-Test"] == header) + #expect(request.metadata["label"] == metadata) +} + +private enum TransferOriginalFieldFixtureError: Error { case unknownCase } + +private func originalFieldRequest( + headers: [String: String], metadata: [String: String] +) throws -> RadrootsBackgroundTransferRequest { + #expect(headers.count <= 1 && metadata.count <= 1) + let bytes = [headers, metadata].reduce(0) { sum, fields in + sum + fields.reduce(0) { $0 + $1.key.utf8.count + $1.value.utf8.count } + } + #expect(bytes <= 32768) + return try RadrootsBackgroundTransferRequest( + identifier: RadrootsBackgroundTransferIdentifier("owned.original.fields"), + remoteURL: #require(URL(string: "https://example.org/owned-input-fixture")), method: .put, + operation: .upload( + source: .file(RadrootsFileReference(scope: .cache, relativePath: "owned/body"))), + headers: headers, metadata: metadata + ) +}