Surface integrity-check failure when parsing a bad manual pairing code

A Manual Pairing Code with a wrong Verhoeff check digit causes
ManualSetupPayloadParser::populatePayload to return
CHIP_ERROR_INTEGRITY_CHECK_FAILED, but the MTR layer was discarding the
specific code: -[MTRSetupPayload initWithManualPairingCode:] dropped it on
the floor (no error out-param), and downstream call sites
(+setupPayloadWithOnboardingPayload:error:,
-[MTRManualSetupPayloadParser populatePayload:],
-[MTRDeviceController pairDevice:onboardingPayload:error:]) all flattened
parse failures to MTRErrorCodeInvalidArgument. Callers had no way to tell
"the user typed a bad setup code" apart from any other parse error.

Add an NSError**-bearing -initWithManualPairingCode:error: variant that
maps the underlying CHIP_ERROR via [MTRError errorForCHIPErrorCode:],
and route the three downstream call sites through it. The existing
no-error initWithManualPairingCode: is preserved as a thin wrapper.

The CHIP_ERROR_INTEGRITY_CHECK_FAILED -> MTRErrorCodeIntegrityCheckFailed
mapping already exists in MTRError.mm; no new error code is needed.

Adds two focused regression tests to MTRSetupPayloadTests.m:
  1. last-digit corruption of a known-good manual pairing code surfaces
     MTRErrorCodeIntegrityCheckFailed (and the canonical form still parses).
  2. bad-Verhoeff code surfaces MTRErrorCodeIntegrityCheckFailed (and not
     MTRErrorCodeInvalidArgument) on all three public parse entry points.
The existing C++ regression guard (TestManualCode.TestPayloadParser_InvalidEntry)
is left intact.

Author: woody-apple

src/darwin/Framework/CHIP/MTRDeviceController_Concrete.mm

@@ -2383,11 +2383,8 @@ - (BOOL)pairDevice:(uint64_t)deviceID
 
 - (BOOL)pairDevice:(uint64_t)deviceID onboardingPayload:(NSString *)onboardingPayload error:(NSError * __autoreleasing *)error
 {
-    auto * setupPayload = [[MTRSetupPayload alloc] initWithPayload:onboardingPayload];
+    auto * setupPayload = [MTRSetupPayload setupPayloadWithOnboardingPayload:onboardingPayload error:error];
     if (!setupPayload) {
-        if (error) {
-            *error = [MTRError errorForCHIPErrorCode:CHIP_ERROR_INVALID_ARGUMENT];
-        }
         return NO;
     }
 

src/darwin/Framework/CHIP/MTRManualSetupPayloadParser.mm

@@ -33,11 +33,7 @@ - (id)initWithDecimalStringRepresentation:(NSString *)decimalStringRepresentatio
 
 - (MTRSetupPayload *)populatePayload:(NSError * __autoreleasing *)error
 {
-    MTRSetupPayload * payload = [[MTRSetupPayload alloc] initWithManualPairingCode:_decimalStringRepresentation];
-    if (!payload && error) {
-        *error = [MTRError errorWithCode:MTRErrorCodeInvalidArgument];
-    }
-    return payload;
+    return [[MTRSetupPayload alloc] initWithManualPairingCode:_decimalStringRepresentation error:error];
 }
 
 @end

src/darwin/Framework/CHIP/MTRSetupPayload.h

@@ -121,6 +121,18 @@ MTR_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
  */
 - (nullable instancetype)initWithPayload:(NSString *)payload MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6));
 
+/**
+ * Initializes the payload object from the provided Manual Pairing Code string.
+ *
+ * Returns nil and populates `error` (if non-nil) if the string is not a valid
+ * Manual Pairing Code. The returned error is in MTRErrorDomain; in particular,
+ * a Manual Pairing Code with an incorrect Verhoeff check digit will report
+ * `MTRErrorCodeIntegrityCheckFailed`, allowing callers to distinguish a
+ * mistyped setup code from other parse failures.
+ */
+- (nullable instancetype)initWithManualPairingCode:(NSString *)manualCode
+                                             error:(NSError * __autoreleasing *)error MTR_PROVISIONALLY_AVAILABLE;
+
 /**
  * Whether this object represents a concatenated QR Code payload consisting
  * of two or more underlying payloads. If YES, then:

src/darwin/Framework/CHIP/MTRSetupPayload.mm

@@ -280,6 +280,12 @@ - (nullable instancetype)initWithQRCode:(NSString *)qrCodePayload
 }
 
 - (nullable instancetype)initWithManualPairingCode:(NSString *)manualCode
+{
+    return [self initWithManualPairingCode:manualCode error:nil];
+}
+
+- (nullable instancetype)initWithManualPairingCode:(NSString *)manualCode
+                                             error:(NSError * __autoreleasing *)error
 {
     self = [super init];
 
@@ -288,10 +294,16 @@ - (nullable instancetype)initWithManualPairingCode:(NSString *)manualCode
     CHIP_ERROR err = parser.populatePayload(_payload);
     if (err != CHIP_NO_ERROR) {
         MTR_LOG_ERROR("Failed to parse Manual Pairing Code: %" CHIP_ERROR_FORMAT, err.Format());
+        if (error) {
+            *error = [MTRError errorForCHIPErrorCode:err];
+        }
         return nil;
     }
     if (!_payload.isValidManualCode(chip::PayloadContents::ValidationMode::kConsume)) {
         MTR_LOG_ERROR("Invalid Manual Pairing Code");
+        if (error) {
+            *error = [MTRError errorForCHIPErrorCode:CHIP_ERROR_INVALID_ARGUMENT];
+        }
         return nil;
     }
 
@@ -781,6 +793,13 @@ + (instancetype)new
 + (MTRSetupPayload * _Nullable)setupPayloadWithOnboardingPayload:(NSString *)onboardingPayload
                                                            error:(NSError * __autoreleasing *)error
 {
+    // For Manual Pairing Codes use the error-bearing init so we can surface
+    // the underlying CHIP_ERROR (e.g. CHIP_ERROR_INTEGRITY_CHECK_FAILED for a
+    // bad Verhoeff check digit) rather than flattening to InvalidArgument.
+    if (![onboardingPayload hasPrefix:@"MT:"]) {
+        return [[MTRSetupPayload alloc] initWithManualPairingCode:onboardingPayload error:error];
+    }
+
     MTRSetupPayload * payload = [[MTRSetupPayload alloc] initWithPayload:onboardingPayload];
     if (!payload && error) {
         *error = [MTRError errorWithCode:MTRErrorCodeInvalidArgument];

src/darwin/Framework/CHIPTests/MTRSetupPayloadTests.m

@@ -562,4 +562,71 @@ - (void)testValidSetupPasscode
     XCTAssertTrue([MTRSetupPayload isValidSetupPasscode:[MTRSetupPayload generateRandomSetupPasscode]]);
 }
 
+- (void)testManualPairingCode_LastDigitCorruption_ReturnsIntegrityCheckFailed
+{
+    // Regression pin (1/2): malformed setup code with last-digit corruption.
+    // Take a known-good 21-digit manual pairing code, flip ONLY its last digit
+    // (the Verhoeff check digit), and confirm the parser rejects the corrupted
+    // form with MTRErrorCodeIntegrityCheckFailed while still accepting the
+    // canonical form. Pins the bug where typo-on-the-last-digit was silently
+    // flattened to MTRErrorCodeInvalidArgument and indistinguishable from any
+    // other parse failure.
+    NSString * const validCode = @"641286075300001000016";
+    NSString * const corruptedCode = @"641286075300001000017"; // last digit 6 -> 7
+
+    NSError * validError;
+    MTRSetupPayload * validPayload = [[MTRSetupPayload alloc] initWithManualPairingCode:validCode error:&validError];
+    XCTAssertNotNil(validPayload);
+    XCTAssertNil(validError);
+
+    NSError * corruptedError;
+    MTRSetupPayload * corruptedPayload = [[MTRSetupPayload alloc] initWithManualPairingCode:corruptedCode error:&corruptedError];
+    XCTAssertNil(corruptedPayload);
+    XCTAssertNotNil(corruptedError);
+    XCTAssertEqualObjects(corruptedError.domain, MTRErrorDomain);
+    XCTAssertEqual(corruptedError.code, MTRErrorCodeIntegrityCheckFailed);
+}
+
+- (void)testManualPairingCode_BadCheckDigit_SurfacesIntegrityCheckFailedAcrossAPIs
+{
+    // Regression pin (2/2): integrity-check error surfaces correct MTRError.
+    // A manual pairing code with a wrong Verhoeff check digit must surface as
+    // MTRErrorCodeIntegrityCheckFailed (NOT MTRErrorCodeInvalidArgument) on
+    // every public entry point that parses one. Covers the three surfaces the
+    // pre-fix code flattened: -initWithManualPairingCode:error:,
+    // +setupPayloadWithOnboardingPayload:error:, and -[MTRManualSetupPayloadParser
+    // populatePayload:].
+    NSString * const badCode = @"02684354589";
+
+    {
+        NSError * error;
+        MTRSetupPayload * payload = [[MTRSetupPayload alloc] initWithManualPairingCode:badCode error:&error];
+        XCTAssertNil(payload);
+        XCTAssertNotNil(error);
+        XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+        XCTAssertEqual(error.code, MTRErrorCodeIntegrityCheckFailed);
+        XCTAssertNotEqual(error.code, MTRErrorCodeInvalidArgument);
+    }
+    {
+        NSError * error;
+        MTRSetupPayload * payload = [MTRSetupPayload setupPayloadWithOnboardingPayload:badCode error:&error];
+        XCTAssertNil(payload);
+        XCTAssertNotNil(error);
+        XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+        XCTAssertEqual(error.code, MTRErrorCodeIntegrityCheckFailed);
+        XCTAssertNotEqual(error.code, MTRErrorCodeInvalidArgument);
+    }
+    {
+        MTRManualSetupPayloadParser * parser =
+            [[MTRManualSetupPayloadParser alloc] initWithDecimalStringRepresentation:badCode];
+        NSError * error;
+        MTRSetupPayload * payload = [parser populatePayload:&error];
+        XCTAssertNil(payload);
+        XCTAssertNotNil(error);
+        XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+        XCTAssertEqual(error.code, MTRErrorCodeIntegrityCheckFailed);
+        XCTAssertNotEqual(error.code, MTRErrorCodeInvalidArgument);
+    }
+}
+
 @end