Extended App-Receipt Validation (#4)

* Introduced (optional) verification of the app instance based on its “identity” (`AppIdentity`)—bundle ID and version
* Extended `AppReceiptValidatorTests`
* Updated visibility of `SoftwareVersion.string`
* Configured module exports
* This change is backward-compatible

Author: yakovmanshin

AppReceiptValidation/src/YMAppReceiptValidation.swift

@@ -6,7 +6,15 @@
 //  Copyright © 2025 Yakov Manshin. See the LICENSE file for license info.
 //
 
+@_exported import YMUtilities
+
 /// Initializes and returns an opaque-type app-receipt validator.
-public func makeAppReceiptValidator() -> some AppReceiptValidatorProtocol {
-    AppReceiptValidator(proxy: AppReceiptValidatorProxy())
+///
+/// - Parameter appIdentity: *Optional.* The object which describes the checked app’s identity.
+/// If no value is provided, app-identity verification will be skipped.
+public func makeAppReceiptValidator(appIdentity: AppIdentity? = nil) -> some AppReceiptValidatorProtocol {
+    AppReceiptValidator(
+        proxy: AppReceiptValidatorProxy(),
+        appIdentity: appIdentity,
+    )
 }

AppReceiptValidation/src/impl/AppReceiptValidator.swift

@@ -13,9 +13,11 @@ import CryptoKit
 final actor AppReceiptValidator<Proxy: AppReceiptValidatorProxyProtocol> {
 
     private let proxy: Proxy
+    private let appIdentity: AppIdentity?
 
-    init(proxy: Proxy) {
+    init(proxy: Proxy, appIdentity: AppIdentity?) {
         self.proxy = proxy
+        self.appIdentity = appIdentity
     }
 
 }
@@ -45,6 +47,12 @@ extension AppReceiptValidator: AppReceiptValidatorProtocol {
             return .init(result: .failure(error), transaction: verifiedTransaction)
         }
 
+        do {
+            try verifyAppIdentity(for: verifiedTransaction)
+        } catch {
+            return .init(result: .failure(error), transaction: verifiedTransaction)
+        }
+        
         return .init(result: .success(()), transaction: verifiedTransaction)
     }
 
@@ -106,4 +114,20 @@ extension AppReceiptValidator: AppReceiptValidatorProtocol {
         byteSequence.map({ String(format: "%02x", $0) }).joined()
     }
 
+    func verifyAppIdentity(for transaction: AppTransactionProxy) throws(AppReceiptValidatorError) {
+        guard let appIdentity else { return }
+        
+        if appIdentity.bundleIdentifier != transaction.bundleID {
+            // TODO: This will constitute a breaking change:
+//            throw .appIdentityMismatch
+            throw .other
+        }
+        
+        if appIdentity.version.string != transaction.appVersion {
+            // TODO: This will constitute a breaking change:
+//            throw .appIdentityMismatch
+            throw .other
+        }
+    }
+    
 }

AppReceiptValidation/src/public/AppIdentity.swift

@@ -0,0 +1,27 @@
+//
+//  AppIdentity.swift
+//  YMAppReceiptValidation
+//
+//  Created by Yakov Manshin on 6/13/25.
+//  Copyright © 2025 Yakov Manshin. See the LICENSE file for license info.
+//
+
+/// The object that fixes the identity of the app in place.
+public struct AppIdentity: Sendable {
+    
+    let bundleIdentifier: String
+    let version: SoftwareVersion
+    
+    /// Initializes a new `AppIdentity`.
+    ///
+    /// + This object is supposed to be initialized using string literals. Don’t use `Bundle` as it retrieves values from `Info.plist` at runtime.
+    ///
+    /// - Parameters:
+    ///   - bundleIdentifier: *Required.* The main bundle’s identifier.
+    ///   - version: *Required.* The main bundle’s current version.
+    public init(bundleIdentifier: String, version: SoftwareVersion) {
+        self.bundleIdentifier = bundleIdentifier
+        self.version = version
+    }
+    
+}

AppReceiptValidation/src/public/AppReceiptValidatorError.swift

@@ -29,9 +29,14 @@ public enum AppReceiptValidatorError: Error {
     /// Device-verification tags don’t match.
     case deviceVerificationMismatch(expected: String, actual: String)
 
-    /// Other (unexpected) error.
+    // TODO: This will constitute a breaking change:
+//    /// Failed to verify app identity.
+//    case appIdentityMismatch
+    
+    /// Other error.
     ///
-    /// + This error is never expected to be thrown.
+    /// + Generally, this error is not expected to be thrown.
+    /// + The exception is newly-introduced errors, thrown as `other` to preserve backward compatibility.
     case other
 
 }
@@ -52,6 +57,9 @@ extension AppReceiptValidatorError: CustomStringConvertible, LocalizedError {
             "Invalid device-verification string: \(string)"
         case .deviceVerificationMismatch(let expected, let actual):
             "Device-verification data mismatched: expected (\(expected.prefix(16))…) / computed (\(actual.prefix(16))…)"
+        // TODO: This will constitute a breaking change:
+//        case .appIdentityMismatch:
+//            "The app identity does not match the receipt"
         case .other:
             "An unknown error occurred"
         }

AppReceiptValidation/test/suites/AppReceiptValidatorTests.swift

@@ -10,6 +10,7 @@
 
 import Foundation
 import Testing
+import YMUtilities
 
 // MARK: - Tests
 
@@ -19,7 +20,7 @@ struct AppReceiptValidatorTests {
     let proxy = AppReceiptValidatorProxyStub()
 
     init() {
-        validator = AppReceiptValidator(proxy: proxy)
+        validator = AppReceiptValidator(proxy: proxy, appIdentity: .sample)
     }
 
     @Test func validateAppReceipt_allowUI_success_shared() async {
@@ -323,6 +324,56 @@ struct AppReceiptValidatorTests {
         #expect(actual == "7d30e01f8fd318434b2f5ac0a49936d14eac344505ef789fa89a8a57b5e181a0f23827d610107e0f4defe5214f9f6130")
     }
 
+    @Test func verifyAppIdentity_success() async throws {
+        try await validator.verifyAppIdentity(for: .sample)
+    }
+    
+    @Test func verifyAppIdentity_success_skipped() async throws {
+        let validator = AppReceiptValidator(proxy: proxy, appIdentity: nil)
+        
+        try await validator.verifyAppIdentity(for: .sample)
+    }
+    
+    @Test func verifyAppIdentity_failure_bundleID() async throws {
+        let transaction = AppTransactionProxy(
+            bundleID: "TEST_AnotherBundleID",
+            environment: .production,
+            appVersion: "1.23.45",
+            originalAppVersion: "",
+            purchaseDate: Date(),
+            deviceVerificationNonce: .allZero,
+            deviceVerification: Data()
+        )
+        
+        let error = try await #require(throws: AppReceiptValidatorError.self) {
+            try await validator.verifyAppIdentity(for: transaction)
+        }
+        guard case .other = error else {
+            Issue.record()
+            return
+        }
+    }
+    
+    @Test func verifyAppIdentity_failure_appVersion() async throws {
+        let transaction = AppTransactionProxy(
+            bundleID: "TEST_BundleID",
+            environment: .sandbox,
+            appVersion: "10.0.0",
+            originalAppVersion: "",
+            purchaseDate: Date(),
+            deviceVerificationNonce: .allZero,
+            deviceVerification: Data()
+        )
+        
+        let error = try await #require(throws: AppReceiptValidatorError.self) {
+            try await validator.verifyAppIdentity(for: transaction)
+        }
+        guard case .other = error else {
+            Issue.record()
+            return
+        }
+    }
+    
 }
 
 // MARK: - Utilities
@@ -332,7 +383,7 @@ fileprivate extension AppTransactionProxy {
     static let sample = AppTransactionProxy(
         bundleID: "TEST_BundleID",
         environment: .other("TEST_Environment"),
-        appVersion: "TEST_AppVersion",
+        appVersion: "1.23.45",
         originalAppVersion: "TEST_OriginalAppVersion",
         purchaseDate: Date(timeIntervalSince1970: 1521288000),
         deviceVerificationNonce: .allZero,
@@ -378,3 +429,7 @@ fileprivate extension UUID {
     static let allZero = UUID(uuidString: "00000000-0000-0000-0000-000000000000")!
     static let nonZero = UUID(uuidString: "01234567-89AB-CDEF-0123-456789ABCDEF")!
 }
+
+fileprivate extension AppIdentity {
+    static let sample = AppIdentity(bundleIdentifier: "TEST_BundleID", version: SoftwareVersion("1.23.45")!)
+}

AppValidation/src/YMAppValidation.swift

@@ -6,9 +6,13 @@
 //  Copyright © 2025 Yakov Manshin. See the LICENSE file for license info.
 //
 
-import YMAppReceiptValidation
+@_exported import YMAppReceiptValidation
+@_exported import YMUtilities
 
 /// Initializes and returns an opaque-type app validator.
-public func makeAppValidator() -> some AppValidatorProtocol {
-    AppValidator(appReceiptValidator: makeAppReceiptValidator())
+///
+/// - Parameter appIdentity: *Optional.* The object which describes the checked app’s identity.
+/// If no value is provided, app-identity verification will be skipped.
+public func makeAppValidator(appIdentity: AppIdentity? = nil) -> some AppValidatorProtocol {
+    AppValidator(appReceiptValidator: makeAppReceiptValidator(appIdentity: appIdentity))
 }

Package.swift

@@ -47,6 +47,7 @@ private func darwinTargets() -> [Target] {
     [
         .target(
             name: "YMAppReceiptValidation",
+            dependencies: ["YMUtilities"],
             path: "AppReceiptValidation/src",
         ),
         .testTarget(

Utilities/src/SoftwareVersion.swift

@@ -28,7 +28,7 @@ public struct SoftwareVersion: Sendable {
 
 extension SoftwareVersion {
 
-    var string: String {
+    public var string: String {
         "\(major).\(minor).\(patch)"
     }