Add flatUsername attribute to UserAttributes builder Fixes AB#3607103 (#2513)

## Summary
Adds a new `flatusername` built-in attribute to the
`UserAttributes.Builder` class, following the existing pattern for other
attributes (city, country, surname, etc.).

## Changes
- **UserAttributes.kt**: Added `FLAT_USERNAME` constant and
`flatUsername()` builder method with KDoc.
- **SignUpEmailPasswordAttributesTest.kt**: Updated to exercise the new
`flatUsername` attribute alongside existing attributes.


[AB#3607103](https://identitydivision.visualstudio.com/Engineering/_workitems/edit/3607103)

---------

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

Author: spetrescu84

msal/src/main/java/com/microsoft/identity/nativeauth/UserAttributes.kt

@@ -40,6 +40,7 @@ class UserAttributes(internal val userAttributes: Map<String, String>) {
             private const val STATE = "state"
             private const val STREET_ADDRESS = "streetAddress"
             private const val SURNAME = "surname"
+            private const val FLAT_USERNAME = "flatusername"
         }
 
         private val userAttributes = mutableMapOf<String, String>()
@@ -125,6 +126,15 @@ class UserAttributes(internal val userAttributes: Map<String, String>) {
             return this
         }
 
+        /**
+         * Sets the flat username for the user
+         * @param flatUsername: Flat username for the user
+         */
+        fun flatUsername(flatUsername: String): Builder {
+            userAttributes[FLAT_USERNAME] = flatUsername
+            return this
+        }
+
         /**
          * Sets any custom attribute for the use
          * @param key: Name of the attribute

msal/src/test/java/com/microsoft/identity/client/e2e/tests/network/nativeauth/SignUpEmailPasswordAttributesTest.kt

@@ -68,7 +68,7 @@ class SignUpEmailPasswordAttributesTest : NativeAuthPublicClientApplicationAbstr
         retryOperation {
             runBlocking {
                 val user = tempEmailApi.generateRandomEmailAddressLocally()
-                val attributes = UserAttributes.Builder().country("Ireland").city("Dublin").build()
+                val attributes = UserAttributes.Builder().country("Ireland").city("Dublin").flatUsername("flatusername").build()
 
                 val param = NativeAuthSignUpParameters(username = user)
                 param.password = getSafePassword().toCharArray()

msal/src/test/java/com/microsoft/identity/nativeauth/NativeAuthPublicClientApplicationJavaTest.java

@@ -3192,6 +3192,8 @@ public void testSignUpInvalidEmailReturnsError() throws ExecutionException, Inte
         assertTrue(signUpResult instanceof SignUpError);
         assertTrue(((SignUpError) signUpResult).isInvalidUsername());
     }
+
+
 }
 
 abstract class TestCallback<T> {

msal/src/test/java/com/microsoft/identity/nativeauth/NativeAuthPublicClientApplicationKotlinTest.kt

@@ -3042,4 +3042,24 @@ class NativeAuthPublicClientApplicationKotlinTest(private val allowPII: Boolean)
         val submitChallengeResult = nextState4.submitChallenge(code)
         assertResult<SignInResult.Complete>(submitChallengeResult)
     }
+
+    @Test
+    fun testUserAttributesFlatUsernameBuilder() {
+        val attrs = UserAttributes.Builder()
+            .flatUsername("testuser")
+            .build()
+        assertEquals("testuser", attrs.userAttributes["flatusername"])
+    }
+
+    @Test
+    fun testUserAttributesFlatUsernameWithOtherAttributes() {
+        val attrs = UserAttributes.Builder()
+            .flatUsername("testuser")
+            .displayName("Test User")
+            .city("Seattle")
+            .build()
+        assertEquals("testuser", attrs.userAttributes["flatusername"])
+        assertEquals("Test User", attrs.userAttributes["displayName"])
+        assertEquals("Seattle", attrs.userAttributes["city"])
+    }
 }