Address PR review comments: improve warn message, document overwrite behavior, add tests

- NativeAuthCIAMAuthority: Improve misleading WARN log message to clearly
  explain that custom headers will not be applied when interceptor type
  does not match
- RequestInterceptorHeaderUtils: Add detailed KDoc explaining case-insensitive
  merge semantics matching iOS behavior and why reserved SDK headers cannot
  be overwritten
- JITInteractorRequestInterceptorTest: Use 3 base headers (was 2) so null
  interceptor size assertion is more meaningful
- SignUpInteractorRequestInterceptorTest: Add test for reserved header
  overwrite protection and case-insensitive header merge

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: spetrescu84

common4j/src/main/com/microsoft/identity/common/java/nativeauth/authorities/NativeAuthCIAMAuthority.kt

@@ -126,7 +126,7 @@ class NativeAuthCIAMAuthority (
     @Throws(ClientException::class)
     override fun createOAuth2Strategy(parameters: OAuth2StrategyParameters): NativeAuthOAuth2Strategy {
         if (parameters.mRequestInterceptor != null && parameters.mRequestInterceptor !is NativeAuthRequestInterceptor) {
-            Logger.warn(TAG, "Ignoring non-native OAuth2RequestInterceptor for NativeAuthCIAMAuthority.")
+            Logger.warn(TAG, "Request interceptor is not a NativeAuthRequestInterceptor instance; custom headers will not be applied to native auth requests.")
         }
 
         val config = createNativeAuthOAuth2Configuration(

common4j/src/main/com/microsoft/identity/common/java/nativeauth/providers/interactors/RequestInterceptorHeaderUtils.kt

@@ -29,13 +29,17 @@ import java.net.URL
 /**
  * Applies additional interceptor headers to the base request headers for native auth interactors.
  *
- * Uses case-insensitive merge semantics: interceptor headers replace matching base headers.
- * Interceptor headers are validated and normalized to lowercase by [NativeAuthHeaderValidator].
+ * Uses case-insensitive merge semantics matching iOS behavior: interceptor headers replace
+ * matching base headers regardless of casing. Interceptor headers are first validated and
+ * normalized to lowercase by [NativeAuthHeaderValidator], which filters out any non-`x-` prefixed
+ * headers and reserved prefixes (`x-ms-`, `x-client-`, `x-broker-`, `x-app-`). This ensures that
+ * mandatory SDK headers (e.g., `Content-Type`, `x-client-SKU`) cannot be overwritten by the
+ * interceptor, since they either lack the `x-` prefix or use a reserved prefix.
  *
  * @param requestUrl The outbound request URL.
  * @param headers The base request headers.
  * @param requestInterceptor Optional interceptor providing additional headers.
- * @return The merged headers map with interceptor values taking precedence.
+ * @return The merged headers map with interceptor values taking precedence for valid custom headers.
  */
 internal fun applyInterceptorHeaders(
     requestUrl: URL,
@@ -48,6 +52,8 @@ internal fun applyInterceptorHeaders(
     val validHeaders = NativeAuthHeaderValidator.filterValidHeaders(additionalHeaders)
     if (validHeaders.isEmpty()) return headers
 
+    // Case-insensitive merge: matches iOS's [NSMutableURLRequest setValue:forHTTPHeaderField:]
+    // which replaces existing headers case-insensitively.
     val mergedHeaders = headers.toMutableMap()
     for ((field, value) in validHeaders) {
         val existingHeader = mergedHeaders.keys.firstOrNull { it.equals(field, ignoreCase = true) }

common4j/src/test/com/microsoft/identity/common/java/nativeauth/providers/interactors/JITInteractorRequestInterceptorTest.kt

@@ -57,7 +57,8 @@ class JITInteractorRequestInterceptorTest {
 
     private val baseHeaders = mapOf<String, String?>(
         "Content-Type" to "application/x-www-form-urlencoded",
-        "x-client-SKU" to "MSAL.Android"
+        "x-client-SKU" to "MSAL.Android",
+        "Accept" to "application/json"
     )
 
     private val testInterceptor = object : NativeAuthRequestInterceptor {
@@ -153,7 +154,7 @@ class JITInteractorRequestInterceptorTest {
         interactor.performIntrospect(createJITIntrospectParams())
 
         assertTrue(capturedHeaders.isCaptured)
-        assertEquals(2, capturedHeaders.captured.size)
+        assertEquals(3, capturedHeaders.captured.size)
         assertFalse(capturedHeaders.captured.containsKey("x-akamai-sensor"))
     }
     // endregion

common4j/src/test/com/microsoft/identity/common/java/nativeauth/providers/interactors/SignUpInteractorRequestInterceptorTest.kt

@@ -271,4 +271,83 @@ class SignUpInteractorRequestInterceptorTest {
         assertEquals(testUrl, capturedUrls[0])
     }
     // endregion
+
+    // region reserved header overwrite protection
+    @Test
+    fun testInterceptorCannotOverwriteReservedBaseHeaders() {
+        val overwriteInterceptor = object : NativeAuthRequestInterceptor {
+            override fun additionalHeaders(requestUrl: URL): Map<String, String>? {
+                return mapOf(
+                    "x-client-SKU" to "Evil.SDK",
+                    "x-ms-request-id" to "fake-id",
+                    "x-akamai-sensor" to "valid-data"
+                )
+            }
+        }
+
+        val mockRequest = mockk<SignUpStartRequest>(relaxed = true)
+        every { mockRequest.requestUrl } returns testUrl
+        every { mockRequest.headers } returns baseHeaders
+        every { mockRequestProvider.createSignUpStartRequest(any()) } returns mockRequest
+        every { mockResponseHandler.getSignUpStartResultFromHttpResponse(any(), any()) } returns mockk(relaxed = true)
+
+        val capturedHeaders = setupHttpClientCapture()
+        val interactor = createInteractor(interceptor = overwriteInterceptor)
+
+        interactor.performSignUpStart(mockk<SignUpStartCommandParameters>(relaxed = true))
+
+        assertTrue(capturedHeaders.isCaptured)
+        val headers = capturedHeaders.captured
+        // Reserved prefix headers from interceptor should be filtered, preserving base values
+        assertEquals("MSAL.Android", headers["x-client-SKU"])
+        assertFalse("x-ms- prefix should be filtered", headers.containsKey("x-ms-request-id"))
+        // Valid custom header should be merged
+        assertEquals("valid-data", headers["x-akamai-sensor"])
+    }
+    // endregion
+
+    // region case-insensitive header merge
+    @Test
+    fun testCaseInsensitiveHeaderMerge() {
+        val baseHeadersWithCustom = mapOf<String, String?>(
+            "Content-Type" to "application/x-www-form-urlencoded",
+            "x-client-SKU" to "MSAL.Android",
+            "x-existing-custom" to "old-value"
+        )
+
+        val caseInterceptor = object : NativeAuthRequestInterceptor {
+            override fun additionalHeaders(requestUrl: URL): Map<String, String>? {
+                return mapOf(
+                    "X-Existing-Custom" to "new-value",
+                    "x-new-header" to "new-data"
+                )
+            }
+        }
+
+        val mockRequest = mockk<SignUpStartRequest>(relaxed = true)
+        every { mockRequest.requestUrl } returns testUrl
+        every { mockRequest.headers } returns baseHeadersWithCustom
+        every { mockRequestProvider.createSignUpStartRequest(any()) } returns mockRequest
+        every { mockResponseHandler.getSignUpStartResultFromHttpResponse(any(), any()) } returns mockk(relaxed = true)
+
+        val capturedHeaders = setupHttpClientCapture()
+        val interactor = createInteractor(interceptor = caseInterceptor)
+
+        interactor.performSignUpStart(mockk<SignUpStartCommandParameters>(relaxed = true))
+
+        assertTrue(capturedHeaders.isCaptured)
+        val headers = capturedHeaders.captured
+        // The original casing key should be replaced by the normalized (lowercase) key from validator
+        assertFalse(
+            "Original casing key should be removed",
+            headers.containsKey("x-existing-custom") && headers.containsKey("x-Existing-Custom")
+        )
+        // The value should be the interceptor's new value (validator normalizes to lowercase)
+        assertEquals("new-value", headers["x-existing-custom"])
+        // New header should be added
+        assertEquals("new-data", headers["x-new-header"])
+        // Base reserved headers should be preserved
+        assertEquals("MSAL.Android", headers["x-client-SKU"])
+    }
+    // endregion
 }