Enhance file encryption with stream metadata (#206)

feat(crypto-module): return stream metadata when encrypting a file
feat(crypto-module): add a convenience `decryptStream(from: to:)` method in `CryptoModule` for file decryption

Author: jguz-pubnub

.pubnub.yml

@@ -1,9 +1,16 @@
 ---
 name: swift
 scm: github.com/pubnub/swift
-version: "9.0.1"
+version: "9.1.0"
 schema: 1
 changelog:
+  - date: 2025-05-13
+    version: 9.1.0
+    changes:
+      - type: feature
+        text: "The `encrypt(stream:contentLength:)` method in `CryptoModule` now returns an `EncryptedStreamResult` containing both the encrypted stream and its total content length."
+      - type: feature
+        text: "The new `decryptStream(from:to:)` method in CryptoModule simplifies file decryption by automatically handling low-level details, in contrast to `decrypt(stream:contentLength:to:)`. Instead of manually creating an InputStream and specifying the content length, you now only need to provide the source and destination URLs."
   - date: 2025-03-20
     version: 9.0.1
     changes:
@@ -100,7 +107,7 @@ changelog:
       - type: feature
         text: "Replace module name with `PubNubSDK` due to compiler error when a public type shares the same name as the module."
       - type: feature
-        text: " add new `subscriptionChanged(channels, groups)` connection status and remove previously deprecated `connecting` and `reconnecting` cases."
+        text: "Add new `subscriptionChanged(channels, groups)` connection status and remove previously deprecated `connecting` and `reconnecting` cases."
       - type: feature
         text: "Remove previously deprecated `.legacyExponential(base, scale, maxDelay)` reconnection policy."
       - type: feature
@@ -676,7 +683,7 @@ sdks:
           - distribution-type: source
             distribution-repository: GitHub release
             package-name: PubNub
-            location: https://github.com/pubnub/swift/archive/refs/tags/9.0.1.zip
+            location: https://github.com/pubnub/swift/archive/refs/tags/9.1.0.zip
             supported-platforms:
               supported-operating-systems:
                 macOS:

PubNub.xcodeproj/project.pbxproj

@@ -2238,12 +2238,12 @@
 			path = Strategy;
 			sourceTree = "<group>";
 		};
-		3D6265D22ABC8E6900FDD5E6 /* CryptorModule */ = {
+		3D6265D22ABC8E6900FDD5E6 /* CryptoModule */ = {
 			isa = PBXGroup;
 			children = (
 				3DBB2C202ABD8053008A100E /* PubNubCryptoModuleContractTestSteps.swift */,
 			);
-			path = CryptorModule;
+			path = CryptoModule;
 			sourceTree = "<group>";
 		};
 		3D7411A12C171F20002267B8 /* Helpers */ = {
@@ -2463,7 +2463,7 @@
 			isa = PBXGroup;
 			children = (
 				3D38A0192B35AFBE006928E7 /* EventEngine */,
-				3D6265D22ABC8E6900FDD5E6 /* CryptorModule */,
+				3D6265D22ABC8E6900FDD5E6 /* CryptoModule */,
 				A5F88ECF2906A9DE00F49D5C /* Objects */,
 				79407BC2271D4CFA0032076C /* Access */,
 				79407BC4271D4CFA0032076C /* Message Actions */,
@@ -4011,7 +4011,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.0.1;
+				MARKETING_VERSION = 9.1.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
@@ -4062,7 +4062,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.0.1;
+				MARKETING_VERSION = 9.1.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
@@ -4170,7 +4170,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.0.1;
+				MARKETING_VERSION = 9.1.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
@@ -4223,7 +4223,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.0.1;
+				MARKETING_VERSION = 9.1.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
@@ -4344,7 +4344,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.0.1;
+				MARKETING_VERSION = 9.1.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
@@ -4396,7 +4396,7 @@
 					"@loader_path/Frameworks",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.0.1;
+				MARKETING_VERSION = 9.1.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu11 gnu++17";
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
@@ -4876,7 +4876,7 @@
 					"$(TOOLCHAIN_DIR)/usr/lib/swift/macosx",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.0.1;
+				MARKETING_VERSION = 9.1.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu17 gnu++14";
 				OTHER_CFLAGS = "$(inherited)";
 				OTHER_LDFLAGS = "$(inherited)";
@@ -4919,7 +4919,7 @@
 					"$(TOOLCHAIN_DIR)/usr/lib/swift/macosx",
 				);
 				MACOSX_DEPLOYMENT_TARGET = 10.15;
-				MARKETING_VERSION = 9.0.1;
+				MARKETING_VERSION = 9.1.0;
 				MODULE_VERIFIER_SUPPORTED_LANGUAGE_STANDARDS = "gnu17 gnu++14";
 				OTHER_CFLAGS = "$(inherited)";
 				OTHER_LDFLAGS = "$(inherited)";

PubNubSwift.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name     = 'PubNubSwift'
-  s.version  = '9.0.1'
+  s.version  = '9.1.0'
   s.homepage = 'https://github.com/pubnub/swift'
   s.documentation_url = 'https://www.pubnub.com/docs/swift-native/pubnub-swift-sdk'
   s.authors = { 'PubNub, Inc.' => '[email protected]' }

Sources/PubNub/Errors/ErrorDescription.swift

@@ -263,7 +263,9 @@ extension PubNubError.Reason: CustomStringConvertible, LocalizedError {
     case .outputStreamFailure:
       return "An `OutputStream` failed due to the contained underlying error"
     case .fileMissingAtPath:
-      return "A File did not exist at the specified path.  Ensure the URL is not nil, and it paths to a file"
+      return "A File did not exist at the specified path. Ensure the URL is not nil, and it paths to a file"
+    case .fileExistsAtPath:
+      return "A File exists at the specified path"
     case .backgroundUpdatesDisabled:
       return "System canceled the background task because background tasks are disabled."
     case .backgroundInsufficientResources:

Sources/PubNub/Errors/PubNubError.swift

@@ -149,6 +149,7 @@ public struct PubNubError: Error {
 
     // File Management
     case fileMissingAtPath
+    case fileExistsAtPath
     case fileTooLarge
     case fileAccessDenied
     case fileContentLength
@@ -215,7 +216,7 @@ public struct PubNubError: Error {
         return .uncategorized
       case .streamCouldNotBeInitialized, .inputStreamFailure, .outputStreamFailure:
         return .streamFailure
-      case .fileTooLarge, .fileMissingAtPath, .fileAccessDenied, .fileContentLength:
+      case .fileTooLarge, .fileMissingAtPath, .fileExistsAtPath, .fileAccessDenied, .fileContentLength:
         return .fileManagement
       case .encryptionFailure, .decryptionFailure, .unknownCryptorFailure:
         return .crypto

Sources/PubNub/Extensions/InputStream+PubNub.swift

@@ -13,7 +13,7 @@ import Foundation
 extension InputStream {
   public func writeEncodedData(to fileURL: URL) throws {
     if FileManager.default.fileExists(atPath: fileURL.path) {
-      throw PubNubError(.fileMissingAtPath, additional: [fileURL.path])
+      throw PubNubError(.fileExistsAtPath, additional: [fileURL.path])
     }
 
     guard let outputStream = OutputStream(url: fileURL, append: false) else {

Sources/PubNub/Extensions/URLRequest+PubNub.swift

@@ -59,8 +59,8 @@ public extension URLRequest {
     if let cryptoModule = cryptoModule {
       switch cryptoModule.encrypt(stream: contentStream, contentLength: content.contentLength) {
       case .success(let encryptingResult):
-        finalStream = encryptingResult
-        contentLength = prefixData.count + ((encryptingResult as? MultipartInputStream)?.length ?? 0) + postfixData.count
+        finalStream = encryptingResult.stream
+        contentLength = prefixData.count + encryptingResult.contentLength + postfixData.count
       case .failure(let encryptionError):
         throw encryptionError
       }

Sources/PubNub/Helpers/Constants.swift

@@ -57,7 +57,7 @@ public enum Constant {
 
   static let pubnubSwiftSDKName: String = "PubNubSwift"
 
-  static let pubnubSwiftSDKVersion: String = "9.0.1"
+  static let pubnubSwiftSDKVersion: String = "9.1.0"
 
   static let appBundleId: String = {
     if let info = Bundle.main.infoDictionary,

Sources/PubNub/Helpers/Crypto/CryptoModule.swift

@@ -10,17 +10,6 @@
 
 import Foundation
 
-@available(*, unavailable, renamed: "CryptoModule")
-public class CryptorModule {
-  public static func aesCbcCryptoModule(with key: String, withRandomIV: Bool = true) -> CryptoModule {
-    preconditionFailure("This method is no longer available")
-  }
-
-  public static func legacyCryptoModule(with key: String, withRandomIV: Bool = true) -> CryptoModule {
-    preconditionFailure("This method is no longer available")
-  }
-}
-
 /// Object capable of encryption/decryption
 public struct CryptoModule {
   private let defaultCryptor: any Cryptor
@@ -29,6 +18,14 @@ public struct CryptoModule {
 
   typealias Base64EncodedString = String
 
+  /// Represents an encrypted stream with its total content length
+  public struct EncryptedStreamResult {
+    /// The encrypted input stream
+    public let stream: InputStream
+    /// Total length of the encrypted content
+    public let contentLength: Int
+  }
+
   /// Initializes `CryptoModule` with custom ``Cryptor`` objects capable of encryption and decryption
   ///
   /// Use this constructor if you would like to provide **custom** objects for decryption and encryption
@@ -176,15 +173,15 @@ public struct CryptoModule {
     }
   }
 
-  /// Encrypts the given `InputStream` object
+  /// Creates an encrypted stream from the given stream
   ///
   /// - Parameters:
   ///   - stream: Stream to encrypt
-  ///   - contentLength: Content length of encoded stream
+  ///   - contentLength: Content length of the stream to encrypt
   /// - Returns:
-  ///   - **Success**: An `InputStream` value
+  ///   - **Success**: An `EncryptedStreamResult` containing the encrypted input stream and its total content length
   ///   - **Failure**: `PubNubError` describing the reason of failure
-  public func encrypt(stream: InputStream, contentLength: Int) -> Result<InputStream, PubNubError> {
+  public func encrypt(stream: InputStream, contentLength: Int) -> Result<EncryptedStreamResult, PubNubError> {
     PubNub.log.debug(
       "Encrypting file",
       category: .crypto
@@ -202,10 +199,15 @@ public struct CryptoModule {
       PubNub.log.debug("Encryption of file failed due to \(error)")
     }
 
-    return streamEncryptionResult
+    return streamEncryptionResult.map { multipartStream in
+      EncryptedStreamResult(
+        stream: multipartStream,
+        contentLength: multipartStream.length
+      )
+    }
   }
 
-  private func performStreamEncryption(stream: InputStream, contentLength: Int) -> Result<InputStream, PubNubError> {
+  private func performStreamEncryption(stream: InputStream, contentLength: Int) -> Result<MultipartInputStream, PubNubError> {
     guard contentLength > 0 else {
       return .failure(PubNubError(
         .encryptionFailure,
@@ -242,7 +244,7 @@ public struct CryptoModule {
   ///
   /// - Parameters:
   ///   - stream: Stream to decrypt
-  ///   - contentLength: Content length of encrypted stream
+  ///   - contentLength: Content length of the encrypted stream
   ///   - to: URL where the stream should be decrypted to
   /// - Returns:
   ///  - **Success**: A decrypted `InputStream` object
@@ -273,6 +275,48 @@ public struct CryptoModule {
     return streamDecryptionResult
   }
 
+  /// Decrypts the stream from the given URL and writes it to the output path
+  ///
+  /// - Parameters:
+  ///   - url: URL of the encrypted stream
+  ///   - outputPath: Path to write the decrypted stream
+  /// - Returns:
+  ///  - **Success**: A decrypted `InputStream` object
+  ///  - **Failure**: `PubNubError` describing the reason of failure
+  @discardableResult
+  public func decryptStream(from url: URL, to outputPath: URL) -> Result<InputStream, PubNubError> {
+    PubNub.log.debug(
+      "Decrypting file",
+      category: .crypto
+    )
+
+    guard let inputStream = InputStream(url: url) else {
+      PubNub.log.debug(
+        "Cannot create InputStream from \(url). Ensure that the file exists at the specified path",
+        category: .crypto
+      )
+      return .failure(PubNubError(
+        .decryptionFailure,
+        additional: ["File doesn't exist at \(url) path"]
+      ))
+    }
+
+    let streamDecryptionResult = performStreamDecryption(
+      stream: inputStream,
+      contentLength: url.sizeOf,
+      to: outputPath
+    )
+
+    switch streamDecryptionResult {
+    case .success:
+      PubNub.log.debug("File decrypted successfully", category: .crypto)
+    case let .failure(error):
+      PubNub.log.debug("Decryption of file failed due to \(error)", category: .crypto)
+    }
+
+    return streamDecryptionResult
+  }
+
   @discardableResult
   public func performStreamDecryption(
     stream: InputStream,

Sources/PubNub/KMP/Wrappers/KMPFileChangeEvent.swift

@@ -87,7 +87,7 @@ public class KMPFile: NSObject {
   }
 
   init(from: PubNubFile, url: URL?) {
-    self.id = from.channel
+    self.id = from.fileId
     self.name = from.filename
     self.size = from.size
     self.contentType = from.contentType

Tests/PubNubContractTest/Steps/CryptorModule/PubNubCryptoModuleContractTestSteps.swift renamed to Tests/PubNubContractTest/Steps/CryptoModule/PubNubCryptoModuleContractTestSteps.swift

@@ -24,7 +24,7 @@ public class PubNubCryptoModuleContractTestSteps: PubNubContractTestCase {
 
   var encryptDataRes: Result<Data, PubNubError>!
   var decryptDataRes: Result<Data, PubNubError>!
-  var encryptStreamRes: Result<InputStream, PubNubError>!
+  var encryptStreamRes: Result<CryptoModule.EncryptedStreamResult, PubNubError>!
   var decryptStreamRes: Result<InputStream, PubNubError>!
 
   var givenFileUrl: URL!
@@ -150,9 +150,9 @@ public class PubNubCryptoModuleContractTestSteps: PubNubContractTestCase {
         let decryptedData = try! self.cryptoModule.decrypt(data: encryptedData).get()
         XCTAssertEqual(expectedData, decryptedData)
       } else {
-        let encryptedStream = try! self.encryptStreamRes.get()
-        let length = (encryptedStream as! MultipartInputStream).length
-        self.cryptoModule.decrypt(stream: encryptedStream, contentLength: length, to: self.outputPath)
+        let encryptedStreamMetadata = try! self.encryptStreamRes.get()
+        let length = encryptedStreamMetadata.contentLength
+        self.cryptoModule.decrypt(stream: encryptedStreamMetadata.stream, contentLength: length, to: self.outputPath)
         let decryptedData = try! Data(contentsOf: self.outputPath)
         XCTAssertEqual(expectedData, decryptedData)
       }