From 4606da62d23f20c5c1513f7fa7ad6485ded08fb0 Mon Sep 17 00:00:00 2001 From: Daniel Eggert Date: Wed, 4 Nov 2026 18:41:52 +0100 Subject: [PATCH] Validate response text, command tags and namespace delimiters (#866) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Reject invalid response text when writing `.no(.init(text: "No mailbox x\r\n* BYE pwned"))` was written verbatim, injecting an untagged response; likewise tagged, BYE, PREAUTH and continuation responses. RFC 9051: `text = 1*(TEXT-CHAR / UTF8-2 / UTF8-3 / UTF8-4)`. `writeText` now asserts no NUL, CR or LF. Empty stays valid. The parser now accepts UTF-8 text. * Add Command.Tag for command and response tags `TaggedCommand(tag: "A1 NOOP\r\nA2 DELETE INBOX\r\nA3", command: .noop)` was written verbatim, injecting a command; likewise `APPEND` start. `TaggedResponse(tag: "* BYE x\r\nA1", …)` injected a response. RFC 3501: `tag = 1*`. New `Command.Tag` replaces the `String` in `TaggedCommand`, `TaggedResponse`, `Response`, `CommandStreamPart`, `AppendCommand`, `BadCommand` and NIOIMAP's state machine errors; `init?(_:)` validates, literals trap. The parser already enforces the production. IMAPCommands converts its numeric tags. * Validate and escape namespace delimiters `NamespaceDescription(string: "x", char: "\r\n", …)` wrote a raw CRLF inside `"…"`, injecting a response. `"\""` encoded as `"""`, and `"\\"` as `"\"` (unterminated); non-ASCII was accepted. RFC 2342: `DQUOTE QUOTED-CHAR DQUOTE / nil`. `init(string:delimiter: responseExtensions:)` (was `char:`) throws `InvalidDelimiterError` for non-ASCII, CR, LF, NUL; the delimiter is stored as a byte, read-only. Quoted-specials are escaped on write and parsed when escaped. * Gate a capturing exit test on Swift 6.3 --- .../Operations/TestConnection.swift | 2 +- .../Operations/TestServer.swift | 6 +- .../CommandTester.swift | 2 +- Sources/IMAPCommands/AppendWriter.swift | 2 +- Sources/IMAPCommands/IMAPConnection.swift | 10 +- Sources/IMAPCommands/Tag.swift | 18 +++ .../NIOIMAP/Client/AppendStateMachine.swift | 2 +- Sources/NIOIMAP/Client/IdleStateMachine.swift | 4 +- .../NIOIMAP/Coders/ClientStateMachine.swift | 8 +- .../Grammar/Command/CommandStreamPart.swift | 10 +- .../Grammar/Command/CommandTag.swift | 105 +++++++++++++ .../Grammar/Command/TaggedCommand.swift | 11 +- .../Namespace/NamespaceDescription.swift | 60 +++++++- .../Grammar/Response/Response.swift | 6 +- .../Grammar/Response/ResponseText.swift | 20 ++- .../Grammar/Response/TaggedResponse.swift | 9 +- .../Grammar/GrammarParser+Response.swift | 2 +- .../Parser/Grammar/GrammarParser.swift | 32 ++-- .../NIOIMAPCore/Parser/ParserLibrary.swift | 2 +- .../Parser/UInt8+ParseTypeMembership.swift | 11 ++ Tests/IMAPCommandsTests/TagTests.swift | 34 +++++ .../CommandType/CommandStream+Tests.swift | 8 +- .../CommandType/CommandTag+Tests.swift | 143 ++++++++++++++++++ .../Grammar/Namespace/Namespace+Tests.swift | 6 +- .../NamespaceDescription+Tests.swift | 88 +++++++++-- .../Namespace/NamespaceResponse+Tests.swift | 8 +- .../Grammar/Response/Response+Tests.swift | 4 +- .../Grammar/Response/ResponseText+Tests.swift | 66 ++++++++ .../Response/ResponseTextCodeTests.swift | 4 +- .../GrammarParser+Primitives+Tests.swift | 31 ---- .../Parser/RoundtripTests.swift | 2 +- .../Parser/UInt8+ParseTypeMembership.swift | 16 ++ 32 files changed, 614 insertions(+), 118 deletions(-) create mode 100644 Sources/NIOIMAPCore/Grammar/Command/CommandTag.swift create mode 100644 Tests/IMAPCommandsTests/TagTests.swift create mode 100644 Tests/NIOIMAPCoreTests/Grammar/CommandType/CommandTag+Tests.swift diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestConnection.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestConnection.swift index db5df493..0caed795 100644 --- a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestConnection.swift +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestConnection.swift @@ -139,7 +139,7 @@ final actor TestConnection: ConnectionProtocol { continuation.yield( .tagged( TaggedResponse( - tag: "\(tag)", + tag: Command.Tag(String(tag))!, state: state ) ) diff --git a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestServer.swift b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestServer.swift index 3f6cf960..0af33db3 100644 --- a/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestServer.swift +++ b/Examples/IMAPTool/Tests/IMAPToolLibTests/Operations/TestServer.swift @@ -129,7 +129,7 @@ final actor TestServer: Sendable { let greeting: UntaggedStatus let expectedOrdering: Ordering private var expectedCommands: [ExpectedCommand] - private var previousTag: String? + private var previousTag: Command.Tag? private var runningAppend: RunningAppend? private init( @@ -296,7 +296,7 @@ extension TestServer { previousTag == nil else { struct ReceivedCommandWhileWaitingForContinuation: Swift.Error { - var previousTag: String + var previousTag: Command.Tag var command: TaggedCommand } throw ReceivedCommandWhileWaitingForContinuation( @@ -446,7 +446,7 @@ extension TestServer { private func didReceive( appendInto mailbox: MailboxName, - tag: String, + tag: Command.Tag, expectation: RunningAppend ) throws { guard diff --git a/Examples/PerformanceTester/Sources/NIOIMAPPerformanceTester/CommandTester.swift b/Examples/PerformanceTester/Sources/NIOIMAPPerformanceTester/CommandTester.swift index 4c37eb9b..f3c7743f 100644 --- a/Examples/PerformanceTester/Sources/NIOIMAPPerformanceTester/CommandTester.swift +++ b/Examples/PerformanceTester/Sources/NIOIMAPPerformanceTester/CommandTester.swift @@ -32,7 +32,7 @@ class CommandTester: Benchmark { @discardableResult func run() throws -> Int { for i in 1...self.iterations { var commandBuffer = CommandEncodeBuffer(buffer: ByteBuffer(), options: .init(), loggingMode: false) - commandBuffer.writeCommand(.init(tag: "\(i)", command: self.command)) + commandBuffer.writeCommand(.init(tag: Command.Tag("\(i)")!, command: self.command)) var buffer = ByteBuffer() var chunk = commandBuffer.buffer.nextChunk() diff --git a/Sources/IMAPCommands/AppendWriter.swift b/Sources/IMAPCommands/AppendWriter.swift index 6b9ce938..2e695486 100644 --- a/Sources/IMAPCommands/AppendWriter.swift +++ b/Sources/IMAPCommands/AppendWriter.swift @@ -50,7 +50,7 @@ extension IMAPConnection { } static func withAppendWriter( - tag: String, + tag: Command.Tag, appendingTo mailbox: MailboxName, underlying: consuming OutboundQueue.AppendQueueWriter, didCompleteCommand: inout Bool, diff --git a/Sources/IMAPCommands/IMAPConnection.swift b/Sources/IMAPCommands/IMAPConnection.swift index f8a90ce8..afbbc71f 100644 --- a/Sources/IMAPCommands/IMAPConnection.swift +++ b/Sources/IMAPCommands/IMAPConnection.swift @@ -200,7 +200,7 @@ public final class IMAPConnection: Sendable { try await outboundWriter.write( TaggedCommand( - tag: "\(tag)", + tag: Command.Tag(tag), command: command ) ) @@ -236,7 +236,7 @@ public final class IMAPConnection: Sendable { try await outboundWriter.write( TaggedCommand( - tag: "\(tag)", + tag: Command.Tag(tag), command: .idleStart ) ) @@ -282,7 +282,7 @@ public final class IMAPConnection: Sendable { try await outboundWriter.write( TaggedCommand( - tag: "\(tag)", + tag: Command.Tag(tag), command: .authenticate( mechanism: mechanism, initialResponse: initialResponse @@ -394,7 +394,7 @@ public final class IMAPConnection: Sendable { try await outboundWriter.withAppendWriter { (writer: consuming OutboundQueue.AppendQueueWriter) in try await AppendWriter.withAppendWriter( - tag: "\(tag)", + tag: Command.Tag(tag), appendingTo: mailbox, underlying: writer, didCompleteCommand: &didCompleteCommand @@ -836,7 +836,7 @@ extension IMAPConnection.PerCommandResponseStream { guard let tag = IMAPConnection.Tag(response.tag), let continuation = continuations.removeValue(forKey: tag) - else { return .unknownTag(response.tag) } + else { return .unknownTag(String(response.tag)) } self = .streams(nextTag, continuations) return .finishContinuation(continuation, response) case .connectionClosed: diff --git a/Sources/IMAPCommands/Tag.swift b/Sources/IMAPCommands/Tag.swift index 8d1a8f72..ffd1bb83 100644 --- a/Sources/IMAPCommands/Tag.swift +++ b/Sources/IMAPCommands/Tag.swift @@ -13,6 +13,7 @@ //===----------------------------------------------------------------------===// import Logging +import NIOIMAP extension IMAPConnection { /// A command tag that uniquely identifies an in-flight IMAP command. @@ -77,3 +78,20 @@ extension IMAPConnection.Tag { self.init(rawValue: value) } } + +extension Command.Tag { + /// Creates the wire tag for a connection tag, for example `A1`. + init(_ tag: IMAPConnection.Tag) { + guard let tag = Command.Tag(String(tag)) else { + preconditionFailure("Invalid command tag: \(String(reflecting: String(tag)))") + } + self = tag + } +} + +extension IMAPConnection.Tag { + /// Creates a connection tag from a wire tag; `nil` if this connection didn't generate it. + init?(_ tag: Command.Tag) { + self.init(String(tag)) + } +} diff --git a/Sources/NIOIMAP/Client/AppendStateMachine.swift b/Sources/NIOIMAP/Client/AppendStateMachine.swift index c3a6d493..de4c9828 100644 --- a/Sources/NIOIMAP/Client/AppendStateMachine.swift +++ b/Sources/NIOIMAP/Client/AppendStateMachine.swift @@ -54,7 +54,7 @@ extension ClientStateMachine { } // The tag of the APPEND command - var tag: String + var tag: Command.Tag var state: State = .started(canFinish: false) var isWaitingForContinuationRequest: Bool { diff --git a/Sources/NIOIMAP/Client/IdleStateMachine.swift b/Sources/NIOIMAP/Client/IdleStateMachine.swift index e315a865..3f44f2f6 100644 --- a/Sources/NIOIMAP/Client/IdleStateMachine.swift +++ b/Sources/NIOIMAP/Client/IdleStateMachine.swift @@ -37,10 +37,10 @@ extension ClientStateMachine { } /// The tag of the IDLE command. - let tag: String + let tag: Command.Tag private(set) var state: State = .waitingForConfirmation - init(tag: String) { + init(tag: Command.Tag) { self.tag = tag } diff --git a/Sources/NIOIMAP/Coders/ClientStateMachine.swift b/Sources/NIOIMAP/Coders/ClientStateMachine.swift index 88031503..92080632 100644 --- a/Sources/NIOIMAP/Coders/ClientStateMachine.swift +++ b/Sources/NIOIMAP/Coders/ClientStateMachine.swift @@ -37,7 +37,7 @@ public struct UnexpectedResponse: Error { /// Used to give more context about where the unexpected response was encountered. public enum Kind: Equatable, Sendable { - case commandCompletionWithUnknownTag(tag: String) + case commandCompletionWithUnknownTag(tag: Command.Tag) case appendNotWaitingForTaggedResponse case appendWaitingForTaggedResponse case appendWithPendingContinuation @@ -78,9 +78,9 @@ public struct UnexpectedContinuationRequest: Error { } public struct DuplicateCommandTag: Error { - public var tag: String + public var tag: Command.Tag - public init(tag: String) { + public init(tag: Command.Tag) { self.tag = tag } } @@ -224,7 +224,7 @@ struct ClientStateMachine { var encodingOptions: ClientEncodingOptions var state: State = .expectingNormalResponse - private var activeCommandTags: Set = [] + private var activeCommandTags: Set = [] private var allocator: ByteBufferAllocator! // We mark where we should write up to at the next opportunity diff --git a/Sources/NIOIMAPCore/Grammar/Command/CommandStreamPart.swift b/Sources/NIOIMAPCore/Grammar/Command/CommandStreamPart.swift index 84c18a2a..615667c6 100644 --- a/Sources/NIOIMAPCore/Grammar/Command/CommandStreamPart.swift +++ b/Sources/NIOIMAPCore/Grammar/Command/CommandStreamPart.swift @@ -61,7 +61,7 @@ public enum AppendCommand: Hashable, Sendable { /// /// - parameter tag: An identifier for the command, typically alphanumeric characters /// - parameter appendingTo: The destination mailbox name - case start(tag: String, appendingTo: MailboxName) + case start(tag: Command.Tag, appendingTo: MailboxName) /// Metadata for a message to be appended to the mailbox. /// @@ -122,7 +122,7 @@ public enum AppendCommand: Hashable, Sendable { /// `\r\n` to complete the command. case finish - public var tag: String? { + public var tag: Command.Tag? { switch self { case .start(let tag, _): return tag @@ -265,8 +265,8 @@ public enum CommandStreamPart: Hashable, Sendable { /// command tag to correlate client requests with server responses. Returns `nil` for /// ``idleDone`` and ``continuationResponse(_:)`` cases, which are not tagged commands. /// - /// - Returns: The tag string for tagged commands, or `nil` for untagged operations. - public var tag: String? { + /// - Returns: The tag for tagged commands, or `nil` for untagged operations. + public var tag: Command.Tag? { switch self { case .idleDone, .continuationResponse: return nil @@ -325,7 +325,7 @@ extension CommandEncodeBuffer { switch command { case .start(tag: let tag, appendingTo: let mailbox): return - self.buffer.writeString("\(tag) APPEND ") + self.buffer.writeMailbox(mailbox) + self.buffer.writeTag(tag) + self.buffer.writeString(" APPEND ") + self.buffer.writeMailbox(mailbox) case .beginMessage(message: let message): return self.buffer.writeAppendMessage(message) case .messageBytes(var bytes): diff --git a/Sources/NIOIMAPCore/Grammar/Command/CommandTag.swift b/Sources/NIOIMAPCore/Grammar/Command/CommandTag.swift new file mode 100644 index 00000000..8958094f --- /dev/null +++ b/Sources/NIOIMAPCore/Grammar/Command/CommandTag.swift @@ -0,0 +1,105 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftNIO project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// + +extension Command { + /// The identifier a client prefixes a command with, and the server echoes in the command's + /// tagged response. + /// + /// ### Example + /// + /// ``` + /// C: A001 NOOP + /// S: A001 OK NOOP completed + /// ``` + /// + /// `A001` is the tag. + /// + /// ## Validity + /// + /// A tag is written to the wire verbatim, so anything that isn't a `tag` is rejected: + /// + /// - ``init(_:)`` returns `nil`. Use it for a tag derived from input. + /// - ``init(stringLiteral:)`` traps. A literal is written by the programmer, so an invalid one + /// is a bug to be caught on first run rather than handled. + /// + /// - SeeAlso: [RFC 3501 Section 2.2.1](https://datatracker.ietf.org/doc/html/rfc3501#section-2.2.1) + public struct Tag: Hashable, Sendable { + let stringValue: String + + /// Creates a tag from a string, if the string is a valid `tag`. + /// + /// A string literal resolves to ``init(stringLiteral:)`` instead, which traps rather than + /// returning `nil`. + /// + /// - parameter stringValue: The tag, for example `A001`. + /// - returns: A new tag, or `nil` if `stringValue` is not a valid `tag`. + public init?(_ stringValue: String) { + guard Self.isValidTag(stringValue) else { return nil } + self.stringValue = stringValue + } + + init(unchecked stringValue: String) { + assert(Self.isValidTag(stringValue)) + self.stringValue = stringValue + } + + /// Whether the given string is a `tag` + /// ([RFC 3501 Section 9](https://datatracker.ietf.org/doc/html/rfc3501#section-9)): + /// ``` + /// tag = 1* + /// ``` + static func isValidTag(_ string: String) -> Bool { + !string.isEmpty && string.utf8.allSatisfy(\.isTagChar) + } + } +} + +extension String { + /// Creates a `String` from a ``Command/Tag``. + /// + /// - parameter other: The tag to convert. + public init(_ other: Command.Tag) { + self = other.stringValue + } +} + +extension Command.Tag: ExpressibleByStringLiteral { + /// Creates a tag from a string literal. + /// + /// A literal is written by the programmer, so an invalid one is a bug to be caught on first + /// run rather than handled. Use ``init(_:)`` for anything else. + /// + /// - parameter value: The string literal. + /// - Precondition: `value` is a valid `tag`; this traps if it isn't. + public init(stringLiteral value: String) { + precondition(Self.isValidTag(value), "Invalid command tag: \(String(reflecting: value))") + self.init(unchecked: value) + } +} + +extension Command.Tag: CustomStringConvertible { + /// The tag, for example `A001`. + public var description: String { + self.stringValue + } +} + +// MARK: - Encoding + +extension EncodeBuffer { + @discardableResult mutating func writeTag(_ tag: Command.Tag) -> Int { + assert(Command.Tag.isValidTag(tag.stringValue)) + return self.writeString(tag.stringValue) + } +} diff --git a/Sources/NIOIMAPCore/Grammar/Command/TaggedCommand.swift b/Sources/NIOIMAPCore/Grammar/Command/TaggedCommand.swift index 7cb2b701..372f772c 100644 --- a/Sources/NIOIMAPCore/Grammar/Command/TaggedCommand.swift +++ b/Sources/NIOIMAPCore/Grammar/Command/TaggedCommand.swift @@ -35,12 +35,12 @@ import struct NIO.ByteBuffer /// - SeeAlso: [RFC 3501 Section 2.2.1](https://datatracker.ietf.org/doc/html/rfc3501#section-2.2.1) (Command Syntax) /// - SeeAlso: ``Command``, ``CommandStreamPart/tagged(_:)`` public struct TaggedCommand: Hashable, Sendable { - /// The tag string used to correlate this command with its response. + /// The tag used to correlate this command with its response. /// /// Tags are typically alphanumeric identifiers assigned by the client. The server /// will include this tag in its response to allow the client to match responses to /// requests, especially when using pipelined commands. - public var tag: String + public var tag: Command.Tag /// The command to send with this tag. /// @@ -49,9 +49,9 @@ public struct TaggedCommand: Hashable, Sendable { /// Creates a new tagged command. /// - /// - parameter tag: The tag string, typically a mixture of alphanumeric characters + /// - parameter tag: The tag, typically a mixture of alphanumeric characters /// - parameter command: The command to associate with the tag - public init(tag: String, command: Command) { + public init(tag: Command.Tag, command: Command) { self.tag = tag self.command = command } @@ -71,7 +71,8 @@ extension CommandEncodeBuffer { /// - returns: The number of bytes written. @discardableResult public mutating func writeCommand(_ command: TaggedCommand) -> Int { var size = 0 - size += self.buffer.writeString("\(command.tag) ") + size += self.buffer.writeTag(command.tag) + size += self.buffer.writeSpace() size += self.writeCommand(command.command) size += self.buffer.writeString("\r\n") return size diff --git a/Sources/NIOIMAPCore/Grammar/Namespace/NamespaceDescription.swift b/Sources/NIOIMAPCore/Grammar/Namespace/NamespaceDescription.swift index 8419c782..ad208de5 100644 --- a/Sources/NIOIMAPCore/Grammar/Namespace/NamespaceDescription.swift +++ b/Sources/NIOIMAPCore/Grammar/Namespace/NamespaceDescription.swift @@ -48,7 +48,12 @@ public struct NamespaceDescription: Hashable, Sendable { /// The delimiter separates components of a mailbox name in this namespace. Common delimiters /// include `/` and `.`. If `nil`, the namespace does not use a hierarchy delimiter, /// meaning mailbox names are not hierarchical within this namespace. - public var delimiter: Character? + public var delimiter: Character? { + self.delimiterByte.map { Character(Unicode.Scalar($0)) } + } + + /// A `QUOTED-CHAR` (unescaped), or `nil`. + let delimiterByte: UInt8? /// Response extensions for this namespace, supporting future protocol enhancements. /// @@ -62,17 +67,54 @@ public struct NamespaceDescription: Hashable, Sendable { /// /// - Parameters: /// - string: The namespace prefix string. - /// - char: The hierarchy delimiter for this namespace, or `nil` if not used. + /// - delimiter: The hierarchy delimiter for this namespace, or `nil` if not used. /// - responseExtensions: Response extensions for this namespace. + /// - Throws: ``InvalidDelimiterError`` if `delimiter` is not an ASCII character, or is CR, LF, or + /// NUL (which can't be written as a `QUOTED-CHAR`). public init( string: ByteBuffer, - char: Character? = nil, + delimiter: Character? = nil, + responseExtensions: OrderedDictionary + ) throws { + var delimiterByte: UInt8? + if let delimiter { + // `Character("\r\n").asciiValue` is LF, so CRLF is rejected too. + guard let byte = delimiter.asciiValue, Self.isValidDelimiter(byte) else { + throw InvalidDelimiterError(delimiter: delimiter) + } + delimiterByte = byte + } + self.init(string: string, delimiterByte: delimiterByte, responseExtensions: responseExtensions) + } + + init( + string: ByteBuffer, + delimiterByte: UInt8?, responseExtensions: OrderedDictionary ) { + assert(delimiterByte.map(Self.isValidDelimiter) ?? true) self.string = string - self.delimiter = char + self.delimiterByte = delimiterByte self.responseExtensions = responseExtensions } + + /// Whether the given byte can be written as a `QUOTED-CHAR` + /// ([RFC 2342 Section 6](https://datatracker.ietf.org/doc/html/rfc2342#section-6)), escaping + /// quoted-specials: + /// ``` + /// QUOTED-CHAR = / "\" quoted-specials + /// ``` + static func isValidDelimiter(_ byte: UInt8) -> Bool { + byte.isTextChar + } +} + +extension NamespaceDescription { + /// The error thrown when a namespace delimiter can't be written as a `QUOTED-CHAR`. + public struct InvalidDelimiterError: Error, Hashable { + /// The rejected delimiter. + public var delimiter: Character + } } // MARK: - Encoding @@ -84,8 +126,14 @@ extension EncodeBuffer { size += self.writeIMAPString(description.string) size += self.writeSpace() - if let char = description.delimiter { - size += self.writeString("\"\(char)\"") + if let byte = description.delimiterByte { + // DQUOTE QUOTED-CHAR DQUOTE, QUOTED-CHAR = ... / "\" quoted-specials + size += self.writeString("\"") + if byte.isQuotedSpecial { + size += self.writeString("\\") + } + size += self.writeString(String(UnicodeScalar(byte))) + size += self.writeString("\"") } else { size += self.writeNil() } diff --git a/Sources/NIOIMAPCore/Grammar/Response/Response.swift b/Sources/NIOIMAPCore/Grammar/Response/Response.swift index cb87ee43..a61e17de 100644 --- a/Sources/NIOIMAPCore/Grammar/Response/Response.swift +++ b/Sources/NIOIMAPCore/Grammar/Response/Response.swift @@ -171,12 +171,12 @@ public enum Response: Hashable, Sendable { /// The command tag associated with this response, if any. /// - /// Returns the tag string for ``tagged(_:)`` responses, which matches the original command tag + /// Returns the tag for ``tagged(_:)`` responses, which matches the original command tag /// to correlate the response with its request. Returns `nil` for untagged responses, fatal responses, /// continuation requests, and other response types that are not associated with a specific command. /// - /// - Returns: The tag string for tagged responses, or `nil` otherwise. - public var tag: String? { + /// - Returns: The tag for tagged responses, or `nil` otherwise. + public var tag: Command.Tag? { switch self { case .untagged, .fetch, .fatal, .authenticationChallenge, .idleStarted: return nil diff --git a/Sources/NIOIMAPCore/Grammar/Response/ResponseText.swift b/Sources/NIOIMAPCore/Grammar/Response/ResponseText.swift index 4e424f60..acb72511 100644 --- a/Sources/NIOIMAPCore/Grammar/Response/ResponseText.swift +++ b/Sources/NIOIMAPCore/Grammar/Response/ResponseText.swift @@ -47,8 +47,14 @@ public struct ResponseText: Hashable, Sendable { /// A human-readable description from the server. /// /// The text provides context-specific information about the response, such as error messages or - /// successful completion notifications. It is always present but may be a single space for some - /// protocol-compliant responses. + /// successful completion notifications. It may be empty. + /// + /// - Warning: The text is written to the wire verbatim and must not contain NUL, CR, or LF: + /// `No mailbox x\r\n* BYE pwned` would inject a whole response. Writing such text traps in + /// debug builds. + /// - Note: The parser skips spaces before the text, so leading spaces are not read back. + /// - Warning: With a `nil` ``code``, a text that starts with `[` may be read back as a code: + /// text `[ALERT] hi` is sent as `* OK [ALERT] hi`. Don't start it with untrusted input. public var text: String /// Creates a new `ResponseText`. @@ -68,14 +74,14 @@ extension EncodeBuffer { self.writeString("[") + self.writeResponseTextCode(code) + self.writeString("] ") } - // If the text is empty, write an additional space - // to enforce standard compliance. Oddly, this is - // perfectly legal IMAP. - + self.writeText(text.text.count > 0 ? text.text : " ") + // `text` is `1*…`, so empty text is written as a single space, which parses back as + // empty. + + self.writeText(text.text.isEmpty ? " " : text.text) } @discardableResult mutating func writeText(_ text: String) -> Int { - self.writeString(text) + assert(text.utf8.allSatisfy(\.isUTF8TextByte), "Invalid text: \(String(reflecting: text))") + return self.writeString(text) } } diff --git a/Sources/NIOIMAPCore/Grammar/Response/TaggedResponse.swift b/Sources/NIOIMAPCore/Grammar/Response/TaggedResponse.swift index bc58b939..d63924d6 100644 --- a/Sources/NIOIMAPCore/Grammar/Response/TaggedResponse.swift +++ b/Sources/NIOIMAPCore/Grammar/Response/TaggedResponse.swift @@ -55,7 +55,7 @@ public struct TaggedResponse: Hashable, Sendable { /// The same tag that appeared in the original client command, allowing the client /// to correlate the response with its request. The tag uniquely identifies the command within /// the connection session. - public var tag: String + public var tag: Command.Tag /// The outcome status of the command execution. /// @@ -67,7 +67,7 @@ public struct TaggedResponse: Hashable, Sendable { /// Creates a new `TaggedResponse`. /// - parameter tag: The tag of the command that led to this response. /// - parameter state: Signals if the command was successfully executed. - public init(tag: String, state: State) { + public init(tag: Command.Tag, state: State) { self.tag = tag self.state = state } @@ -77,6 +77,9 @@ public struct TaggedResponse: Hashable, Sendable { extension EncodeBuffer { @discardableResult mutating func writeTaggedResponse(_ response: TaggedResponse) -> Int { - self.writeString("\(response.tag) ") + self.writeTaggedResponseState(response.state) + self.writeString("\r\n") + self.writeTag(response.tag) + + self.writeSpace() + + self.writeTaggedResponseState(response.state) + + self.writeString("\r\n") } } diff --git a/Sources/NIOIMAPCore/Parser/Grammar/GrammarParser+Response.swift b/Sources/NIOIMAPCore/Parser/Grammar/GrammarParser+Response.swift index e45024c1..fa4dc9da 100644 --- a/Sources/NIOIMAPCore/Parser/Grammar/GrammarParser+Response.swift +++ b/Sources/NIOIMAPCore/Parser/Grammar/GrammarParser+Response.swift @@ -226,7 +226,7 @@ extension GrammarParser { // text requires minimum 1 char, but we want to be lenient here // and allow 0 characters to represent empty text let parsed = try PL.parseZeroOrMoreCharacters(buffer: &buffer, tracker: tracker) { (char) -> Bool in - char.isTextChar + char.isUTF8TextByte } let text = try ParserLibrary.parseBufferAsUTF8(parsed) diff --git a/Sources/NIOIMAPCore/Parser/Grammar/GrammarParser.swift b/Sources/NIOIMAPCore/Parser/Grammar/GrammarParser.swift index 5b90f48b..89923991 100644 --- a/Sources/NIOIMAPCore/Parser/Grammar/GrammarParser.swift +++ b/Sources/NIOIMAPCore/Parser/Grammar/GrammarParser.swift @@ -1852,17 +1852,25 @@ extension GrammarParser { // (DQUOTE QUOTED-CHAR DQUOTE / nil) // [Namespace-Response-Extensions] ")" func parseNamespaceDescription(buffer: inout ParseBuffer, tracker: StackTracker) throws -> NamespaceDescription { - func parseNamespaceDescr_quotedChar(buffer: inout ParseBuffer, tracker: StackTracker) throws -> Character? { + func parseNamespaceDescr_quotedChar(buffer: inout ParseBuffer, tracker: StackTracker) throws -> UInt8? { try PL.parseFixedString("\"", buffer: &buffer, tracker: tracker) - let char = try PL.parseByte(buffer: &buffer, tracker: tracker) - guard char.isQuotedChar else { - throw ParserError(hint: "Invalid character") + // QUOTED-CHAR = / "\" quoted-specials + var byte = try PL.parseByte(buffer: &buffer, tracker: tracker) + if byte == UInt8(ascii: "\\") { + byte = try PL.parseByte(buffer: &buffer, tracker: tracker) + guard byte.isQuotedSpecial else { + throw ParserError(hint: "Expected quoted special") + } + } else { + guard byte.isQuotedChar else { + throw ParserError(hint: "Invalid character") + } } try PL.parseFixedString("\"", buffer: &buffer, tracker: tracker) - return Character(.init(char)) + return byte } - func parseNamespaceDescr_nil(buffer: inout ParseBuffer, tracker: StackTracker) throws -> Character? { + func parseNamespaceDescr_nil(buffer: inout ParseBuffer, tracker: StackTracker) throws -> UInt8? { try self.parseNil(buffer: &buffer, tracker: tracker) return nil } @@ -1871,7 +1879,7 @@ extension GrammarParser { try PL.parseFixedString("(", buffer: &buffer, tracker: tracker) let string = try self.parseString(buffer: &buffer, tracker: tracker) try PL.parseSpaces(buffer: &buffer, tracker: tracker) - let char = try PL.parseOneOf( + let delimiter = try PL.parseOneOf( parseNamespaceDescr_quotedChar, parseNamespaceDescr_nil, buffer: &buffer, @@ -1879,7 +1887,7 @@ extension GrammarParser { ) let extensions = try self.parseNamespaceResponseExtensions(buffer: &buffer, tracker: tracker) try PL.parseFixedString(")", buffer: &buffer, tracker: tracker) - return .init(string: string, char: char, responseExtensions: extensions) + return .init(string: string, delimiterByte: delimiter, responseExtensions: extensions) } } @@ -2647,11 +2655,9 @@ extension GrammarParser { } // tag = 1* - func parseTag(buffer: inout ParseBuffer, tracker: StackTracker) throws -> String { - let parsed = try PL.parseOneOrMoreCharacters(buffer: &buffer, tracker: tracker) { char -> Bool in - char.isAStringChar && char != UInt8(ascii: "+") - } - return try ParserLibrary.parseBufferAsUTF8(parsed) + func parseTag(buffer: inout ParseBuffer, tracker: StackTracker) throws -> Command.Tag { + let parsed = try PL.parseOneOrMoreCharacters(buffer: &buffer, tracker: tracker) { $0.isTagChar } + return Command.Tag(unchecked: try ParserLibrary.parseBufferAsUTF8(parsed)) } // tagged-ext = tagged-ext-label SP tagged-ext-val diff --git a/Sources/NIOIMAPCore/Parser/ParserLibrary.swift b/Sources/NIOIMAPCore/Parser/ParserLibrary.swift index b17d603d..9bb179c0 100644 --- a/Sources/NIOIMAPCore/Parser/ParserLibrary.swift +++ b/Sources/NIOIMAPCore/Parser/ParserLibrary.swift @@ -77,7 +77,7 @@ public struct BadCommand: Error { /// /// Allows the server to send a properly-tagged error response to the client, /// maintaining IMAP's request/response correlation even when the command is malformed. - public var commandTag: String + public var commandTag: Command.Tag /// Why parsing failed. /// diff --git a/Sources/NIOIMAPCore/Parser/UInt8+ParseTypeMembership.swift b/Sources/NIOIMAPCore/Parser/UInt8+ParseTypeMembership.swift index dbf63548..0d3a0688 100644 --- a/Sources/NIOIMAPCore/Parser/UInt8+ParseTypeMembership.swift +++ b/Sources/NIOIMAPCore/Parser/UInt8+ParseTypeMembership.swift @@ -71,6 +71,12 @@ extension UInt8 { } } + /// `TEXT-CHAR`, or a byte of a UTF8-2/3/4 sequence: RFC 9051 `text`. Callers check that the + /// bytes are well-formed UTF-8. + var isUTF8TextByte: Bool { + self.isTextChar || self > 0x7F + } + var isAStringChar: Bool { switch self { case _ where self.isResponseSpecial, _ where isAtomChar: @@ -80,6 +86,11 @@ extension UInt8 { } } + /// tag = 1* + var isTagChar: Bool { + self.isAStringChar && self != UInt8(ascii: "+") + } + /// ATOM-CHAR = /// CHAR = %x01-7F ; RFC 5234 var isAtomChar: Bool { diff --git a/Tests/IMAPCommandsTests/TagTests.swift b/Tests/IMAPCommandsTests/TagTests.swift new file mode 100644 index 00000000..5854e411 --- /dev/null +++ b/Tests/IMAPCommandsTests/TagTests.swift @@ -0,0 +1,34 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftNIO project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// + +@testable import IMAPCommands +import NIOIMAP +import Testing + +/// Tagged responses are routed to their command by converting the wire tag back. +@Suite("IMAPConnection.Tag") +struct TagTests { + @Test("connection tags round-trip through wire tags") + func roundTrip() { + let tag = IMAPConnection.Tag.first.makeNext() + #expect(Command.Tag(tag) == "A2") + #expect(IMAPConnection.Tag(Command.Tag(tag)) == tag) + } + + @Test("wire tags this connection didn't generate are not connection tags") + func foreignTag() { + let wireTag: Command.Tag = "B1" + #expect(IMAPConnection.Tag(wireTag) == nil) + } +} diff --git a/Tests/NIOIMAPCoreTests/Grammar/CommandType/CommandStream+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/CommandType/CommandStream+Tests.swift index 4ddfd0e9..45e344f7 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/CommandType/CommandStream+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/CommandType/CommandStream+Tests.swift @@ -300,9 +300,9 @@ private struct CommandStreamTests { (AppendCommand.catenateData(.end), nil), (AppendCommand.endCatenate, nil), (AppendCommand.finish, nil), - ] as [(AppendCommand, String?)] + ] as [(AppendCommand, Command.Tag?)] ) - func appendCommandTag(_ fixture: (AppendCommand, String?)) { + func appendCommandTag(_ fixture: (AppendCommand, Command.Tag?)) { #expect(fixture.0.tag == fixture.1) } @@ -314,9 +314,9 @@ private struct CommandStreamTests { (CommandStreamPart.append(.start(tag: "C3", appendingTo: .inbox)), "C3"), (CommandStreamPart.append(.finish), nil), (CommandStreamPart.continuationResponse("data"), nil), - ] as [(CommandStreamPart, String?)] + ] as [(CommandStreamPart, Command.Tag?)] ) - func commandStreamPartTag(_ fixture: (CommandStreamPart, String?)) { + func commandStreamPartTag(_ fixture: (CommandStreamPart, Command.Tag?)) { #expect(fixture.0.tag == fixture.1) } diff --git a/Tests/NIOIMAPCoreTests/Grammar/CommandType/CommandTag+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/CommandType/CommandTag+Tests.swift new file mode 100644 index 00000000..d732d49e --- /dev/null +++ b/Tests/NIOIMAPCoreTests/Grammar/CommandType/CommandTag+Tests.swift @@ -0,0 +1,143 @@ +//===----------------------------------------------------------------------===// +// +// This source file is part of the SwiftNIO open source project +// +// Copyright (c) 2026 Apple Inc. and the SwiftNIO project authors +// Licensed under Apache License v2.0 +// +// See LICENSE.txt for license information +// See CONTRIBUTORS.txt for the list of SwiftNIO project authors +// +// SPDX-License-Identifier: Apache-2.0 +// +//===----------------------------------------------------------------------===// + +import NIO +@_spi(NIOIMAPInternal) @testable import NIOIMAPCore +import Testing + +@Suite("Command.Tag") +struct CommandTagTests { + /// A tag is written to the wire verbatim, so ``Command/Tag/init(_:)`` is the only thing + /// between a caller that builds tags from untrusted input and an injected command. + @Test( + "invalid tags are rejected", + arguments: [ + "", + "+", + "A+1", // ASTRING-CHAR, but not a tag char. + "A 1", + "A(1", + "A{1", + "A*1", + "A%1", + #"A"1"#, + #"A\1"#, + "Ä1", + "A\u{7F}1", + "A1 NOOP\r\nA2 DELETE INBOX\r\nA3", // Would inject a whole command. + "* BYE x\r\nA1", // Would inject an untagged response. + ] + ) + func invalidTags(_ string: String) { + #expect(Command.Tag(string) == nil) + } + + @Test("valid tags", arguments: validTagStrings) + func validTags(_ string: String) { + #expect(Command.Tag(string).map { String($0) } == string) + } + + /// Written verbatim, so every tag we accept has to parse back unchanged, in a command and in a + /// response. + @Test("valid tags round-trip in a command", arguments: validTagStrings) + func commandRoundTrip(_ string: String) throws { + let tag = try #require(Command.Tag(string)) + var encodeBuffer = CommandEncodeBuffer(buffer: ByteBuffer(), options: .rfc3501, loggingMode: false) + encodeBuffer.writeCommand(TaggedCommand(tag: tag, command: .noop)) + var buffer = ParseBuffer(encodeBuffer.buffer.nextChunk().bytes) + let parsed = try GrammarParser().parseTaggedCommand(buffer: &buffer, tracker: .testTracker) + #expect(parsed == TaggedCommand(tag: tag, command: .noop)) + } + + @Test("valid tags round-trip in an APPEND", arguments: validTagStrings) + func appendRoundTrip(_ string: String) throws { + let tag = try #require(Command.Tag(string)) + var encodeBuffer = CommandEncodeBuffer(buffer: ByteBuffer(), options: .rfc3501, loggingMode: false) + encodeBuffer.writeCommandStream(.append(.start(tag: tag, appendingTo: .inbox))) + var bytes = encodeBuffer.buffer.nextChunk().bytes + bytes.writeString(" ") + var buffer = ParseBuffer(bytes) + let parsed = try GrammarParser().parseAppend(buffer: &buffer, tracker: .testTracker) + #expect(parsed == .append(.start(tag: tag, appendingTo: .inbox))) + } + + @Test("valid tags round-trip in a tagged response", arguments: validTagStrings) + func responseRoundTrip(_ string: String) throws { + TestUtilities.expectRoundTrip( + TaggedResponse(tag: try #require(Command.Tag(string)), state: .ok(.init(text: "done"))), + terminator: "", + encoder: { $0.writeTaggedResponse($1) }, + parser: GrammarParser().parseTaggedResponse + ) + } + + @Test(arguments: [ + ParseFixture.tag("abc", "\r", expected: .success("abc")), + ParseFixture.tag("abc", "+", expected: .success("abc")), + ParseFixture.tag("+", "", expected: .failure), + ParseFixture.tag("", "", expected: .incompleteMessage), + // RFC 3501: tag = 1*; ASTRING-CHAR + // inherits the CTL exclusion via ATOM-CHAR, and RFC 5234 has + // CTL = %x00-1F / %x7F, so a tag stops at DEL and cannot start with it. + ParseFixture.tag("ab", "\u{7F}c\r", expected: .success("ab")), + ParseFixture.tag("\u{7F}", "", expected: .failure), + // Stops at non-ASCII: parsed tags go through `init(unchecked:)`. + ParseFixture.tag("ab", "ü\r", expected: .success("ab")), + ]) + func parse(_ fixture: ParseFixture) { + fixture.checkParsing() + } + + #if !os(iOS) && !os(watchOS) && !os(tvOS) && !os(visionOS) && !os(Android) + @Test("an invalid string literal traps") func stringLiteralPreconditionFailure() async { + let result = await #expect( + processExitsWith: ExitTest.Condition.failure, + observing: [\.standardErrorContent], + performing: { + let tag: Command.Tag = "A 1" + _ = tag + } + ) + TestUtilities.expectTrapMessage(result, "Invalid command tag") + } + #endif +} + +// MARK: - + +private let validTagStrings = [ + "A", + "1", + "A001", + "a.b-c_d", + "]", + "A]1", + "!#$&'", + "~|`^=", +] + +extension ParseFixture { + fileprivate static func tag( + _ input: String, + _ terminator: String, + expected: Expected + ) -> Self { + ParseFixture( + input: input, + terminator: terminator, + expected: expected, + parser: GrammarParser().parseTag + ) + } +} diff --git a/Tests/NIOIMAPCoreTests/Grammar/Namespace/Namespace+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/Namespace/Namespace+Tests.swift index a96782dc..cebf74f4 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/Namespace/Namespace+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/Namespace/Namespace+Tests.swift @@ -22,13 +22,13 @@ struct NamespaceTests { @Test(arguments: [ EncodeFixture.namespace([], "NIL"), EncodeFixture.namespace( - [.init(string: "str1", char: nil, responseExtensions: [:])], + [try! .init(string: "str1", delimiter: nil, responseExtensions: [:])], "((\"str1\" NIL))" ), EncodeFixture.namespace( [ - .init(string: "str1", char: nil, responseExtensions: [:]), - .init(string: "str2", char: nil, responseExtensions: [:]), + try! .init(string: "str1", delimiter: nil, responseExtensions: [:]), + try! .init(string: "str2", delimiter: nil, responseExtensions: [:]), ], "((\"str1\" NIL)(\"str2\" NIL))" ), diff --git a/Tests/NIOIMAPCoreTests/Grammar/Namespace/NamespaceDescription+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/Namespace/NamespaceDescription+Tests.swift index f1cdc4f4..dbf46842 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/Namespace/NamespaceDescription+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/Namespace/NamespaceDescription+Tests.swift @@ -21,15 +21,15 @@ import Testing struct NamespaceDescriptionTests { @Test(arguments: [ EncodeFixture.namespaceDescription( - .init(string: "string", char: nil, responseExtensions: [:]), + try! .init(string: "string", delimiter: nil, responseExtensions: [:]), "(\"string\" NIL)" ), EncodeFixture.namespaceDescription( - .init(string: "string", char: "a", responseExtensions: [:]), + try! .init(string: "string", delimiter: "a", responseExtensions: [:]), "(\"string\" \"a\")" ), EncodeFixture.namespaceDescription( - .init(string: "string", char: nil, responseExtensions: ["str2": ["str3"]]), + try! .init(string: "string", delimiter: nil, responseExtensions: ["str2": ["str3"]]), "(\"string\" NIL \"str2\" (\"str3\"))" ), ]) @@ -37,29 +37,97 @@ struct NamespaceDescriptionTests { fixture.checkEncoding() } + @Test( + "encode escapes quoted-specials", + arguments: [ + ("\\", #"("x" "\\")"#), + ("\"", #"("x" "\"")"#), + ] as [(Character, String)] + ) + func encodeQuotedSpecial(_ delimiter: Character, _ expected: String) throws { + EncodeFixture( + input: try NamespaceDescription(string: "x", delimiter: delimiter, responseExtensions: [:]), + bufferKind: .defaultServer, + expectedString: expected, + encoder: { $0.writeNamespaceDescription($1) } + ).checkEncoding() + } + + /// The delimiter isn't PII, so logging shows it. + @Test("logging mode shows the delimiter") + func loggingMode() throws { + var buffer = EncodeBuffer.serverEncodeBuffer( + buffer: ByteBuffer(), + options: ResponseEncodingOptions(), + loggingMode: true + ) + buffer.writeNamespaceDescription( + try NamespaceDescription(string: "x", delimiter: "/", responseExtensions: [:]) + ) + #expect(String(buffer: buffer.nextChunk().bytes).hasSuffix(#" "/")"#)) + } + + /// `DQUOTE QUOTED-CHAR DQUOTE`: CR, LF, NUL, and non-ASCII can't be written. + @Test( + "invalid delimiter throws", + arguments: ["\r", "\n", "\r\n", "\0", "ü", "🇨🇭"] as [Character] + ) + func invalidDelimiter(_ delimiter: Character) { + #expect(throws: NamespaceDescription.InvalidDelimiterError(delimiter: delimiter)) { + try NamespaceDescription(string: "x", delimiter: delimiter, responseExtensions: [:]) + } + } + + /// Every delimiter we accept has to parse back unchanged. + @Test( + "delimiter round-trips", + arguments: [nil, "/", ".", "\\", "\"", "~", "\t", " ", "\u{7F}"] as [Character?] + ) + func delimiterRoundTrip(_ delimiter: Character?) throws { + let description = try NamespaceDescription(string: "x", delimiter: delimiter, responseExtensions: [:]) + #expect(description.delimiter == delimiter) + TestUtilities.expectRoundTrip( + description, + encoder: { $0.writeNamespaceDescription($1) }, + parser: GrammarParser().parseNamespaceDescription + ) + } + @Test(arguments: [ ParseFixture.namespaceDescription( "(\"str1\" NIL)", " ", - expected: .success(.init(string: "str1", char: nil, responseExtensions: [:])) + expected: .success(try! .init(string: "str1", delimiter: nil, responseExtensions: [:])) ), ParseFixture.namespaceDescription( "(\"str\" \"a\")", " ", - expected: .success(.init(string: "str", char: "a", responseExtensions: [:])) + expected: .success(try! .init(string: "str", delimiter: "a", responseExtensions: [:])) ), ParseFixture.namespaceDescription( "(\"str\" \"\r\")", " ", expected: .failureIgnoringBufferModifications ), + // Escaped quoted-specials: `"\\"` is a backslash, `"\""` a double quote. + ParseFixture.namespaceDescription( + #"("str" "\\")"#, + " ", + expected: .success(try! .init(string: "str", delimiter: "\\", responseExtensions: [:])) + ), + ParseFixture.namespaceDescription( + #"("str" "\"")"#, + " ", + expected: .success(try! .init(string: "str", delimiter: "\"", responseExtensions: [:])) + ), + ParseFixture.namespaceDescription(#"("str" "\a")"#, " ", expected: .failureIgnoringBufferModifications), ParseFixture.namespaceDescription( "(\"str\" NIL \"ext-key\" (\"val1\" \"val2\"))", " ", expected: .success( - .init( + try! .init( string: "str", - char: nil, + delimiter: nil, responseExtensions: ["ext-key": ["val1", "val2"]] ) ) @@ -78,13 +146,13 @@ struct NamespaceDescriptionTests { ), ParseFixture.namespace( "((\"#mh/\" \"/\"))", - expected: .success([.init(string: "#mh/", char: "/", responseExtensions: [:])]) + expected: .success([try! .init(string: "#mh/", delimiter: "/", responseExtensions: [:])]) ), ParseFixture.namespace( "((\"\" \"/\")(\"#mh/\" \"/\"))", expected: .success([ - .init(string: "", char: "/", responseExtensions: [:]), - .init(string: "#mh/", char: "/", responseExtensions: [:]), + try! .init(string: "", delimiter: "/", responseExtensions: [:]), + try! .init(string: "#mh/", delimiter: "/", responseExtensions: [:]), ]) ), ParseFixture.namespace("", "", expected: .incompleteMessage), diff --git a/Tests/NIOIMAPCoreTests/Grammar/Namespace/NamespaceResponse+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/Namespace/NamespaceResponse+Tests.swift index 7982e8c0..7364b8fa 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/Namespace/NamespaceResponse+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/Namespace/NamespaceResponse+Tests.swift @@ -26,9 +26,11 @@ struct NamespaceResponseTests { ), EncodeFixture.namespaceResponse( .init( - userNamespace: [NamespaceDescription(string: "", responseExtensions: [:])], - otherUserNamespace: [NamespaceDescription(string: "#shared/", char: "/", responseExtensions: [:])], - sharedNamespace: [NamespaceDescription(string: "Public Folders/", responseExtensions: [:])] + userNamespace: [try! NamespaceDescription(string: "", responseExtensions: [:])], + otherUserNamespace: [ + try! NamespaceDescription(string: "#shared/", delimiter: "/", responseExtensions: [:]) + ], + sharedNamespace: [try! NamespaceDescription(string: "Public Folders/", responseExtensions: [:])] ), "NAMESPACE ((\"\" NIL)) ((\"#shared/\" \"/\")) ((\"Public Folders/\" NIL))" ), diff --git a/Tests/NIOIMAPCoreTests/Grammar/Response/Response+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/Response/Response+Tests.swift index be15f935..4bd64151 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/Response/Response+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/Response/Response+Tests.swift @@ -299,9 +299,9 @@ private struct PIIFixture: Sendable, CustomTestStringConvertible { private struct ResponseTagFixture: Sendable, CustomTestStringConvertible { let response: Response - let expectedTag: String? + let expectedTag: Command.Tag? - var testDescription: String { expectedTag ?? "(nil)" } + var testDescription: String { expectedTag.map { String($0) } ?? "(nil)" } } private struct StreamingKindSectionSpecifierFixture: Sendable, CustomTestStringConvertible { diff --git a/Tests/NIOIMAPCoreTests/Grammar/Response/ResponseText+Tests.swift b/Tests/NIOIMAPCoreTests/Grammar/Response/ResponseText+Tests.swift index 4752b396..8e7ecb9d 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/Response/ResponseText+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/Response/ResponseText+Tests.swift @@ -18,6 +18,49 @@ import Testing @Suite("ResponseText") struct ResponseTextTests { + /// Written verbatim, so all text we accept has to parse back unchanged, with and without a code. + @Test("valid text round-trips", arguments: validTextStrings) + func validTextRoundTrips(_ string: String) { + for code in [nil, ResponseTextCode.alert] { + TestUtilities.expectRoundTrip( + ResponseText(code: code, text: string), + terminator: "\r\n", + encoder: { $0.writeResponseText($1) }, + parser: GrammarParser().parseResponseText + ) + } + } + + // Exit tests can only capture values (the `[string = …]` list below) with Swift 6.3 and later. + #if compiler(>=6.3) && DEBUG && !os(iOS) && !os(watchOS) && !os(tvOS) && !os(visionOS) && !os(Android) + /// Text is written to the wire verbatim, so a server that echoes untrusted input could inject a + /// whole response. + @Test( + "writing invalid text traps", + arguments: [ + "a\rb", + "a\nb", + "a\u{0}b", + "No mailbox x\r\n* BYE pwned", + ] + ) + func invalidTextTraps(_ string: String) async { + let result = await #expect( + processExitsWith: ExitTest.Condition.failure, + observing: [\.standardErrorContent], + performing: { [string = string as String] in + var buffer = EncodeBuffer.serverEncodeBuffer( + buffer: ByteBuffer(), + options: ResponseEncodingOptions(), + loggingMode: false + ) + buffer.writeResponseText(ResponseText(text: string)) + } + ) + TestUtilities.expectTrapMessage(result, "Invalid text") + } + #endif + @Test(arguments: [ EncodeFixture.responseText(.init(code: nil, text: "buffer"), "buffer"), EncodeFixture.responseText(.init(code: .alert, text: "buffer"), "[ALERT] buffer"), @@ -44,11 +87,21 @@ struct ResponseTextTests { expected: .success(.init(code: .uidValidity(1_561_789_793), text: "")) ), ParseFixture.responseText("[UIDNEXT 171]", expected: .success(.init(code: .uidNext(171), text: ""))), + ParseFixture.responseText("Grüezi 🇨🇭", expected: .success(.init(code: nil, text: "Grüezi 🇨🇭"))), ]) func parse(_ fixture: ParseFixture) { fixture.checkParsing() } + @Test("non-UTF-8 text fails to parse") + func parseLatin1() { + // Latin-1 `ü`. + var buffer = ParseBuffer(ByteBuffer(bytes: [UInt8(ascii: "a"), 0xFC, UInt8(ascii: "\r")])) + #expect(throws: ParserError.self) { + try GrammarParser().parseResponseText(buffer: &buffer, tracker: .testTracker) + } + } + @Test( "custom debug string convertible", arguments: [ @@ -63,6 +116,19 @@ struct ResponseTextTests { // MARK: - +private let validTextStrings = [ + "", + "a", + "CAPABILITY completed", + "a b ", + "a\tb", + "[a", + "a]", + "Grüezi", + "日本語", + "🇨🇭", +] + extension EncodeFixture { fileprivate static func responseText( _ input: ResponseText, diff --git a/Tests/NIOIMAPCoreTests/Grammar/Response/ResponseTextCodeTests.swift b/Tests/NIOIMAPCoreTests/Grammar/Response/ResponseTextCodeTests.swift index bfb2fdf3..4d02798d 100644 --- a/Tests/NIOIMAPCoreTests/Grammar/Response/ResponseTextCodeTests.swift +++ b/Tests/NIOIMAPCoreTests/Grammar/Response/ResponseTextCodeTests.swift @@ -187,9 +187,9 @@ struct ResponseTextCodeTests { expected: .success( .namespace( .init( - userNamespace: [.init(string: "Foo", responseExtensions: [:])], + userNamespace: [try! .init(string: "Foo", responseExtensions: [:])], otherUserNamespace: [], - sharedNamespace: [.init(string: "Bar", char: nil, responseExtensions: [:])] + sharedNamespace: [try! .init(string: "Bar", delimiter: nil, responseExtensions: [:])] ) ) ) diff --git a/Tests/NIOIMAPCoreTests/Parser/Grammar/GrammarParser+Primitives+Tests.swift b/Tests/NIOIMAPCoreTests/Parser/Grammar/GrammarParser+Primitives+Tests.swift index 74fe891a..10b2f012 100644 --- a/Tests/NIOIMAPCoreTests/Parser/Grammar/GrammarParser+Primitives+Tests.swift +++ b/Tests/NIOIMAPCoreTests/Parser/Grammar/GrammarParser+Primitives+Tests.swift @@ -294,24 +294,6 @@ private struct GrammarParserPrimitivesTests { fixture.checkParsing() } - @Test( - "parse tag", - arguments: [ - ParseFixture.tag("abc", "\r", expected: .success("abc")), - ParseFixture.tag("abc", "+", expected: .success("abc")), - ParseFixture.tag("+", "", expected: .failure), - ParseFixture.tag("", "", expected: .incompleteMessage), - // RFC 3501: tag = 1*; ASTRING-CHAR - // inherits the CTL exclusion via ATOM-CHAR, and RFC 5234 has - // CTL = %x00-1F / %x7F, so a tag stops at DEL and cannot start with it. - ParseFixture.tag("ab", "\u{7F}c\r", expected: .success("ab")), - ParseFixture.tag("\u{7F}", "", expected: .failure), - ] - ) - func parseTag(_ fixture: ParseFixture) { - fixture.checkParsing() - } - @Test( "parse vendor-token", arguments: [ @@ -415,19 +397,6 @@ extension ParseFixture { ) } - fileprivate static func tag( - _ input: String, - _ terminator: String, - expected: Expected - ) -> Self { - ParseFixture( - input: input, - terminator: terminator, - expected: expected, - parser: GrammarParser().parseTag - ) - } - fileprivate static func vendorToken( _ input: String, _ terminator: String, diff --git a/Tests/NIOIMAPCoreTests/Parser/RoundtripTests.swift b/Tests/NIOIMAPCoreTests/Parser/RoundtripTests.swift index 7ba8d9ac..ff359299 100644 --- a/Tests/NIOIMAPCoreTests/Parser/RoundtripTests.swift +++ b/Tests/NIOIMAPCoreTests/Parser/RoundtripTests.swift @@ -186,7 +186,7 @@ private enum RoundtripTests { ) static func commandRoundtrip(_ fixture: RoundtripFixture) throws { var encodeBuffer = CommandEncodeBuffer(buffer: ByteBuffer(), options: .init(), loggingMode: false) - let tag = "1" + let tag: Command.Tag = "1" let taggedCommand = TaggedCommand(tag: tag, command: fixture.command) encodeBuffer.writeCommand(taggedCommand) // required for commands that might terminate with a literal (e.g. append) diff --git a/Tests/NIOIMAPCoreTests/Parser/UInt8+ParseTypeMembership.swift b/Tests/NIOIMAPCoreTests/Parser/UInt8+ParseTypeMembership.swift index 93657c99..9f9e6d21 100644 --- a/Tests/NIOIMAPCoreTests/Parser/UInt8+ParseTypeMembership.swift +++ b/Tests/NIOIMAPCoreTests/Parser/UInt8+ParseTypeMembership.swift @@ -115,6 +115,14 @@ struct UInt8ParseTypeMembershipTests { #expect(invalid.allSatisfy { !$0.isAStringChar }) } + @Test("tag char") + func tagChar() { + let valid = atomChars.union([UInt8(ascii: "]")]).subtracting([UInt8(ascii: "+")]) + let invalid = allChars.subtracting(valid) + #expect(valid.allSatisfy { $0.isTagChar }) + #expect(invalid.allSatisfy { !$0.isTagChar }) + } + /// `list-char = ATOM-CHAR / list-wildcards / resp-specials` @Test("list char") func listChar() { @@ -152,6 +160,14 @@ struct UInt8ParseTypeMembershipTests { #expect(invalid.allSatisfy { !$0.isTextChar }) } + @Test("UTF-8 text byte") + func utf8TextByte() { + let invalid: Set = [UInt8(ascii: "\r"), .init(ascii: "\n"), 0] + let valid = allChars.subtracting(invalid) + #expect(valid.allSatisfy { $0.isUTF8TextByte }) + #expect(invalid.allSatisfy { !$0.isUTF8TextByte }) + } + @Test("hex character") func hexCharacter() { var valid = Set()