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 three XCTests against MTRSetupPayloadTests.m pinning the new error
shape on both APIs plus the happy path. 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/MTRPairingBackwardsCompatTests.m

@@ -118,4 +118,25 @@ - (void)test002_PairDeviceWithString
     [self waitForExpectations:@[ expectation ] timeout:kPairingTimeoutInSeconds];
 }
 
+- (void)test003_PairDeviceWithBadManualPairingCode_SurfacesIntegrityCheckFailed
+{
+    // Integration regression pin: pairing through MTRDeviceController with a
+    // manual pairing code whose Verhoeff check digit is wrong must surface
+    // MTRErrorCodeIntegrityCheckFailed end-to-end, not the pre-fix generic
+    // MTRErrorCodeInvalidArgument. No server app is needed -- this fails at
+    // parse time before any PASE work is attempted.
+    __auto_type * controller = [self createControllerOnTestFabric];
+    XCTAssertNotNil(controller);
+
+    NSError * error;
+    BOOL ok = [controller pairDevice:sDeviceId
+                   onboardingPayload:@"02684354589"
+                               error:&error];
+    XCTAssertFalse(ok);
+    XCTAssertNotNil(error);
+    XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+    XCTAssertEqual(error.code, MTRErrorCodeIntegrityCheckFailed);
+    XCTAssertNotEqual(error.code, MTRErrorCodeInvalidArgument);
+}
+
 @end

src/darwin/Framework/CHIPTests/MTRSetupPayloadTests.m

@@ -18,6 +18,8 @@
 #import <Matter/Matter.h>
 #import <XCTest/XCTest.h>
 
+#import "MTRSetupPayload_Internal.h"
+
 @interface MTRSetupPayloadTests : XCTestCase
 
 @end
@@ -562,4 +564,124 @@ - (void)testValidSetupPasscode
     XCTAssertTrue([MTRSetupPayload isValidSetupPasscode:[MTRSetupPayload generateRandomSetupPasscode]]);
 }
 
+- (void)testManualParser_BadCheckDigit_ReturnsIntegrityCheckFailed
+{
+    // "02684354589" is a manual pairing code with a wrong Verhoeff check digit.
+    // It must surface as MTRErrorCodeIntegrityCheckFailed, not be flattened to
+    // MTRErrorCodeInvalidArgument (which loses the user-actionable distinction
+    // between "you typed a bad code" and other parse failures).
+    NSError * error;
+    MTRSetupPayload * payload = [MTRSetupPayload setupPayloadWithOnboardingPayload:@"02684354589" error:&error];
+
+    XCTAssertNil(payload);
+    XCTAssertNotNil(error);
+    XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+    XCTAssertEqual(error.code, MTRErrorCodeIntegrityCheckFailed);
+}
+
+- (void)testManualParser_InitWithManualPairingCodeError_BadCheckDigit
+{
+    NSError * error;
+    MTRSetupPayload * payload = [[MTRSetupPayload alloc] initWithManualPairingCode:@"02684354589" error:&error];
+
+    XCTAssertNil(payload);
+    XCTAssertNotNil(error);
+    XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+    XCTAssertEqual(error.code, MTRErrorCodeIntegrityCheckFailed);
+}
+
+- (void)testManualParser_InitWithManualPairingCodeError_Valid
+{
+    NSError * error;
+    MTRSetupPayload * payload = [[MTRSetupPayload alloc] initWithManualPairingCode:@"641286075300001000016" error:&error];
+
+    XCTAssertNotNil(payload);
+    XCTAssertNil(error);
+    XCTAssertTrue(payload.hasShortDiscriminator);
+    XCTAssertEqual(payload.discriminator.unsignedIntegerValue, 10);
+    XCTAssertEqual(payload.setupPasscode.unsignedIntegerValue, 12345670);
+}
+
+- (void)testManualParser_PopulatePayload_BadCheckDigit_ReturnsIntegrityCheckFailed
+{
+    // Cover the MTRManualSetupPayloadParser entry point too, so a regression
+    // that bypasses MTRSetupPayload's new init still gets caught.
+    MTRManualSetupPayloadParser * parser =
+        [[MTRManualSetupPayloadParser alloc] initWithDecimalStringRepresentation:@"02684354589"];
+    NSError * error;
+    MTRSetupPayload * payload = [parser populatePayload:&error];
+
+    XCTAssertNil(payload);
+    XCTAssertNotNil(error);
+    XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+    XCTAssertEqual(error.code, MTRErrorCodeIntegrityCheckFailed);
+}
+
+- (void)testOnboardingPayloadParser_Manual_BadCheckDigit_DistinguishesFromInvalidArgument
+{
+    // Regression pin: +setupPayloadWithOnboardingPayload:error: must surface
+    // MTRErrorCodeIntegrityCheckFailed for a bad-Verhoeff manual pairing code,
+    // and explicitly NOT flatten to MTRErrorCodeInvalidArgument (the pre-fix
+    // behavior). Guards against re-introduction of the flattening in any
+    // downstream call site routed through this factory.
+    NSError * error;
+    MTRSetupPayload * payload = [MTRSetupPayload setupPayloadWithOnboardingPayload:@"02684354589" error:&error];
+
+    XCTAssertNil(payload);
+    XCTAssertNotNil(error);
+    XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+    XCTAssertEqual(error.code, MTRErrorCodeIntegrityCheckFailed);
+    XCTAssertNotEqual(error.code, MTRErrorCodeInvalidArgument);
+}
+
+- (void)testManualParser_BadCheckDigit_LegacyInitStillReturnsNil_AndNewInitNotFlattenedToInvalidArgument
+{
+    // Regression pin for both shapes of the API on a bad-Verhoeff code:
+    //   - Legacy -initWithManualPairingCode: must still return nil
+    //     (source-compat for callers that relied on nil-on-failure).
+    //   - New -initWithManualPairingCode:error: must surface
+    //     MTRErrorCodeIntegrityCheckFailed and explicitly NOT
+    //     MTRErrorCodeInvalidArgument (pre-fix flattening).
+    NSString * badCode = @"02684354589";
+
+    MTRSetupPayload * legacyPayload = [[MTRSetupPayload alloc] initWithManualPairingCode:badCode];
+    XCTAssertNil(legacyPayload);
+
+    NSError * error;
+    MTRSetupPayload * newPayload = [[MTRSetupPayload alloc] initWithManualPairingCode:badCode error:&error];
+    XCTAssertNil(newPayload);
+    XCTAssertNotNil(error);
+    XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+    XCTAssertEqual(error.code, MTRErrorCodeIntegrityCheckFailed);
+    XCTAssertNotEqual(error.code, MTRErrorCodeInvalidArgument);
+}
+
+- (void)testManualParser_InitWithManualPairingCodeError_BoundaryInputs
+{
+    // Boundary-input pin for -initWithManualPairingCode:error:. None of these
+    // should crash, all should yield a nil payload, and any reported error
+    // must be in MTRErrorDomain. Both &error and NULL out-param shapes are
+    // exercised so a regression that null-derefs the out-param is caught.
+    NSArray<NSString *> * badInputs = @[
+        @"", // zero-length
+        @"0", // sub-minimum
+        @"1234567890", // exact-length-but-invalid (10 digits, not a valid manual code)
+        @"abcdefghijk", // non-numeric
+        @"   02684354589   ", // whitespace-padded
+        @"026843545890268435458902684354589026843545890", // oversized
+    ];
+
+    for (NSString * input in badInputs) {
+        NSError * error;
+        MTRSetupPayload * payload = [[MTRSetupPayload alloc] initWithManualPairingCode:input error:&error];
+        XCTAssertNil(payload, @"input=%@ unexpectedly produced a payload", input);
+        XCTAssertNotNil(error, @"input=%@ produced nil payload but no error", input);
+        XCTAssertEqualObjects(error.domain, MTRErrorDomain, @"input=%@ wrong error domain", input);
+
+        // NULL error out-param must not crash.
+        MTRSetupPayload * payloadNoError = [[MTRSetupPayload alloc] initWithManualPairingCode:input error:NULL];
+        XCTAssertNil(payloadNoError, @"input=%@ unexpectedly produced a payload (NULL error)", input);
+    }
+}
+
 @end