Surface integrity-check failure when parsing a bad setup payload

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.

Adversarial audit found the QR Code parse path had the same shape:
-[MTRSetupPayload initWithQRCode:] has no error out-param,
-[MTRQRCodeSetupPayloadParser populatePayload:] discards the specific
CHIP_ERROR and rewrites it to MTRErrorCodeInvalidArgument, and the QR
branch of +setupPayloadWithOnboardingPayload:error: does the same.
A scanner glitch or a typed-in QR string with a bad Base38 character
or invalid chunk length was indistinguishable from any other parse
failure, so callers stalled the same way.

Add NSError**-bearing -initWithManualPairingCode:error: and
-initWithQRCode:error: variants that map the underlying CHIP_ERROR
via [MTRError errorForCHIPErrorCode:], and route the downstream call
sites through them:
- -[MTRManualSetupPayloadParser populatePayload:]
- -[MTRQRCodeSetupPayloadParser populatePayload:]
- +[MTRSetupPayload setupPayloadWithOnboardingPayload:error:] (both
  the QR and manual branches collapse to a single dispatch)
- -[MTRDeviceController pairDevice:onboardingPayload:error:]

The existing no-error inits are preserved as thin wrappers for
source compatibility. The CHIP_ERROR -> MTRError mappings already
exist in MTRError.mm (CHIP_ERROR_INTEGRITY_CHECK_FAILED ->
MTRErrorCodeIntegrityCheckFailed, CHIP_ERROR_INVALID_INTEGER_VALUE
-> MTRErrorCodeInvalidIntegerValue, CHIP_ERROR_INVALID_STRING_LENGTH
-> MTRErrorCodeInvalidStringLength); no new error codes are needed.

Adds XCTests against MTRSetupPayloadTests.m pinning the new error
shape across both parse paths:
- bad Verhoeff check digit -> MTRErrorCodeIntegrityCheckFailed
- bad Base38 character -> MTRErrorCodeInvalidIntegerValue
- invalid Base38 chunk length -> MTRErrorCodeInvalidStringLength
and a MTRPairingBackwardsCompatTests integration pin on the
pairDevice:onboardingPayload:error: surface. The existing C++
regression guard (TestManualCode.TestPayloadParser_InvalidEntry)
is left intact.

NFC commissioning shares the QR parse path (the NFC tag carries a
Matter-encoded URL whose payload portion is the same Base38 QR string),
so this fix covers NFC payload failures too.

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/MTRQRCodeSetupPayloadParser.mm

@@ -33,11 +33,7 @@ - (id)initWithBase38Representation:(NSString *)base38Representation
 
 - (MTRSetupPayload *)populatePayload:(NSError * __autoreleasing *)error
 {
-    MTRSetupPayload * payload = [[MTRSetupPayload alloc] initWithQRCode:_base38Representation];
-    if (!payload && error) {
-        *error = [MTRError errorWithCode:MTRErrorCodeInvalidArgument];
-    }
-    return payload;
+    return [[MTRSetupPayload alloc] initWithQRCode:_base38Representation 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

@@ -269,17 +269,32 @@ - (CHIP_ERROR)initializeFromQRCode:(NSString *)qrCode validate:(BOOL)validate
 }
 
 - (nullable instancetype)initWithQRCode:(NSString *)qrCodePayload
+{
+    return [self initWithQRCode:qrCodePayload error:nil];
+}
+
+- (nullable instancetype)initWithQRCode:(NSString *)qrCodePayload
+                                  error:(NSError * __autoreleasing *)error
 {
     self = [super init];
     CHIP_ERROR err = [self initializeFromQRCode:qrCodePayload validate:YES];
     if (err != CHIP_NO_ERROR) {
+        if (error) {
+            *error = [MTRError errorForCHIPErrorCode:err];
+        }
         return nil;
     }
 
     return self;
 }
 
 - (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 +303,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,11 +802,15 @@ + (instancetype)new
 + (MTRSetupPayload * _Nullable)setupPayloadWithOnboardingPayload:(NSString *)onboardingPayload
                                                            error:(NSError * __autoreleasing *)error
 {
-    MTRSetupPayload * payload = [[MTRSetupPayload alloc] initWithPayload:onboardingPayload];
-    if (!payload && error) {
-        *error = [MTRError errorWithCode:MTRErrorCodeInvalidArgument];
+    // Use the error-bearing inits so we can surface the specific underlying
+    // CHIP_ERROR (e.g. CHIP_ERROR_INTEGRITY_CHECK_FAILED for a bad Verhoeff
+    // check digit on a Manual Pairing Code, or CHIP_ERROR_INVALID_STRING_LENGTH /
+    // CHIP_ERROR_INVALID_INTEGER_VALUE for a malformed QR Code) rather than
+    // flattening every parse failure to MTRErrorCodeInvalidArgument.
+    if ([onboardingPayload hasPrefix:@"MT:"]) {
+        return [[MTRSetupPayload alloc] initWithQRCode:onboardingPayload error:error];
     }
-    return payload;
+    return [[MTRSetupPayload alloc] initWithManualPairingCode:onboardingPayload error:error];
 }
 
 - (nullable NSNumber *)rendezvousInformation

src/darwin/Framework/CHIP/MTRSetupPayload_Internal.h

@@ -28,6 +28,7 @@ MTR_DIRECT_MEMBERS
 
 - (instancetype)initWithSetupPayload:(const chip::SetupPayload &)setupPayload;
 - (nullable instancetype)initWithQRCode:(NSString *)qrCodePayload;
+- (nullable instancetype)initWithQRCode:(NSString *)qrCodePayload error:(NSError * __autoreleasing *)error;
 - (nullable instancetype)initWithManualPairingCode:(NSString *)manualCode;
 
 @end

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

@@ -562,4 +562,126 @@ - (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);
+    }
+}
+
+- (void)testQRCode_MalformedBase38_SurfacesSpecificErrorAcrossAPIs
+{
+    // Regression pin: the QR-code parse path used to flatten every failure to
+    // MTRErrorCodeInvalidArgument the same way the manual-code path did, which
+    // meant a typo or scanner glitch in a QR Code was indistinguishable from a
+    // structural rejection. A bad Base38 character (here, the '?' which is not
+    // in the Base38 alphabet) returns CHIP_ERROR_INVALID_INTEGER_VALUE from
+    // base38Decode and must surface as MTRErrorCodeInvalidIntegerValue (NOT
+    // MTRErrorCodeInvalidArgument) on every entry point that parses a QR Code:
+    // -initWithQRCode:error: (internal), +setupPayloadWithOnboardingPayload:error:,
+    // and -[MTRQRCodeSetupPayloadParser populatePayload:].
+    NSString * const malformedQRCode = @"MT:M5L90MP500K64J0000?";
+
+    {
+        NSError * error;
+        MTRSetupPayload * payload = [MTRSetupPayload setupPayloadWithOnboardingPayload:malformedQRCode error:&error];
+        XCTAssertNil(payload);
+        XCTAssertNotNil(error);
+        XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+        XCTAssertEqual(error.code, MTRErrorCodeInvalidIntegerValue);
+        XCTAssertNotEqual(error.code, MTRErrorCodeInvalidArgument);
+    }
+    {
+        // Strip the "MT:" prefix for the Base38-only parser surface.
+        MTRQRCodeSetupPayloadParser * parser =
+            [[MTRQRCodeSetupPayloadParser alloc] initWithBase38Representation:[malformedQRCode substringFromIndex:3]];
+        NSError * error;
+        MTRSetupPayload * payload = [parser populatePayload:&error];
+        XCTAssertNil(payload);
+        XCTAssertNotNil(error);
+        XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+        XCTAssertEqual(error.code, MTRErrorCodeInvalidIntegerValue);
+        XCTAssertNotEqual(error.code, MTRErrorCodeInvalidArgument);
+    }
+}
+
+- (void)testQRCode_TruncatedBase38_SurfacesInvalidStringLength
+{
+    // Companion to the malformed-Base38 case: a Base38 payload whose total
+    // length is not decomposable into the allowed chunk sizes (2, 4, 5) returns
+    // CHIP_ERROR_INVALID_STRING_LENGTH from base38Decode. The valid 19-character
+    // payload below would parse, but appending two extra characters leaves the
+    // length at 21 = 5+5+5+5+1, with a single trailing character that cannot
+    // form any allowed chunk. That must surface as MTRErrorCodeInvalidStringLength,
+    // not the pre-fix MTRErrorCodeInvalidArgument.
+    NSError * error;
+    MTRSetupPayload * payload =
+        [MTRSetupPayload setupPayloadWithOnboardingPayload:@"MT:M5L90MP500K64J00000AB" error:&error];
+    XCTAssertNil(payload);
+    XCTAssertNotNil(error);
+    XCTAssertEqualObjects(error.domain, MTRErrorDomain);
+    XCTAssertEqual(error.code, MTRErrorCodeInvalidStringLength);
+    XCTAssertNotEqual(error.code, MTRErrorCodeInvalidArgument);
+}
+
 @end