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:
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
+ )
+}