feat: Phase 2 - Add DeviceRegistrationClientApplication, DeviceState, DiscoveryEndpoint

- Create DeviceRegistrationClientApplication in common (public API for OneAuth)
  - All methods take mandatory correlationId: UUID for IPC tracing
  - correlationId passed to V0 protocol parameters via constructor
  - Two constructors: simple (Context) and full (Context, components, discoveryClient, provider)
- Add DeviceState enum in common4j (DEVICE_VALID, DEVICE_NOT_FOUND, DEVICE_DISABLED, UNKNOWN)
- Add DiscoveryEndpoint enum in common4j (PROD, PPE, INT)
- Update AbstractDeviceRegistrationProtocolParameters: remove no-arg constructor,
  add (UUID correlationId) constructor. Remove @AllArgsConstructor from V0 params,
  add explicit constructors with correlationId as first param.
- Add DeviceRegistrationClientApplicationTest (7 tests)
- Update serializer and packer tests for new constructor signatures

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

Author: mohitc1

changelog.txt

@@ -1,5 +1,6 @@
 vNext
 ----------
+- [MINOR] Add DeviceRegistrationClientApplication as public API for OneAuth device registration with mandatory correlationId, DeviceState and DiscoveryEndpoint enums (#3073)
 - [MINOR] Move device registration protocol types, domain types, controller, and packer from broker to common to enable OneAuth device registration support (#3066)
 - [MINOR] Upgrade compileSdkVersion to 36 and buildToolsVersion to 36.0.0 (#3065)
 - [PATCH] Rename SovSG to GovSG for the Singapore sovereign cloud identifiers (#3068)

common/src/main/java/com/microsoft/identity/deviceregistration/DeviceRegistrationClientApplication.kt

@@ -101,7 +101,7 @@ class AndroidDeviceRegistrationClientControllerTest {
     private val testRecordWithAccount = DeviceRegistrationRecordWithAccount("account", "tenant", "upn", "deviceId", false, false)
 
     private fun testParams() = TestHappyPathV0Parameters(
-        "hello ", "world", true, false, 1.4f, 3.7f, testRecord, testRecordWithAccount
+        UUID.randomUUID(), "hello ", "world", true, false, 1.4f, 3.7f, testRecord, testRecordWithAccount
     )
 
     private fun testResponse() = TestHappyPathV0Response(

common/src/test/java/com/microsoft/identity/deviceregistration/AndroidDeviceRegistrationClientControllerTest.kt

@@ -22,33 +22,31 @@
 // THE SOFTWARE.
 package com.microsoft.identity.deviceregistration;
 
-import static com.microsoft.identity.deviceregistration.java.exception.DeviceRegistrationException.INTERNAL_ERROR_CODE;
-import static com.microsoft.identity.deviceregistration.java.exception.DeviceRegistrationException.INVALID_PACKAGE_ERROR_CODE;
 import static com.microsoft.identity.deviceregistration.AndroidDeviceRegistrationProtocolPacker.CORRELATION_ID;
 import static com.microsoft.identity.deviceregistration.AndroidDeviceRegistrationProtocolPacker.PROTOCOL_DATA;
 import static com.microsoft.identity.deviceregistration.AndroidDeviceRegistrationProtocolPacker.PROTOCOL_EXCEPTION_ERROR_CAUSE_MESSAGE;
 import static com.microsoft.identity.deviceregistration.AndroidDeviceRegistrationProtocolPacker.PROTOCOL_EXCEPTION_ERROR_CODE;
 import static com.microsoft.identity.deviceregistration.AndroidDeviceRegistrationProtocolPacker.PROTOCOL_EXCEPTION_ERROR_MESSAGE;
 import static com.microsoft.identity.deviceregistration.AndroidDeviceRegistrationProtocolPacker.PROTOCOL_EXCEPTION_STACK_TRACE_STRING;
 import static com.microsoft.identity.deviceregistration.AndroidDeviceRegistrationProtocolPacker.PROTOCOL_NAME;
-
+import static com.microsoft.identity.deviceregistration.java.exception.DeviceRegistrationException.INTERNAL_ERROR_CODE;
+import static com.microsoft.identity.deviceregistration.java.exception.DeviceRegistrationException.INVALID_PACKAGE_ERROR_CODE;
 
 import android.os.Bundle;
 
-import com.microsoft.identity.deviceregistration.testprotocols.TestHappyPathV0Parameters;
+import com.microsoft.identity.common.java.exception.BaseException;
+import com.microsoft.identity.common.java.exception.ClientException;
 import com.microsoft.identity.deviceregistration.java.api.DeviceRegistrationRecord;
 import com.microsoft.identity.deviceregistration.java.api.DeviceRegistrationRecordWithAccount;
 import com.microsoft.identity.deviceregistration.java.exception.DeviceRegistrationException;
 import com.microsoft.identity.deviceregistration.java.exception.DrsErrorResponseException;
-import com.microsoft.identity.common.java.exception.BaseException;
-import com.microsoft.identity.common.java.exception.ClientException;
+import com.microsoft.identity.deviceregistration.testprotocols.TestHappyPathV0Parameters;
 
 import org.junit.Assert;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.robolectric.RobolectricTestRunner;
 
-
 import java.util.UUID;
 
 import lombok.SneakyThrows;
@@ -72,6 +70,7 @@ public class AndroidDeviceRegistrationProtocolPackerTest {
 
 
     private static final TestHappyPathV0Parameters TEST_PROTOCOL = new TestHappyPathV0Parameters(
+            UUID.randomUUID(),
             TEST_DATA,
             TEST_DATA,
             true,

common/src/test/java/com/microsoft/identity/deviceregistration/AndroidDeviceRegistrationProtocolPackerTest.java

@@ -0,0 +1,215 @@
+// Copyright (c) Microsoft Corporation.
+// All rights reserved.
+//
+// This code is licensed under the MIT License.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files(the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions :
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+package com.microsoft.identity.deviceregistration
+
+import android.content.Context
+import android.os.Bundle
+import androidx.test.core.app.ApplicationProvider
+import com.microsoft.identity.common.internal.activebrokerdiscovery.IBrokerDiscoveryClient
+import com.microsoft.identity.common.internal.broker.BrokerData
+import com.microsoft.identity.common.internal.broker.ipc.IIpcStrategy
+import com.microsoft.identity.common.java.interfaces.IPlatformComponents
+import com.microsoft.identity.deviceregistration.java.DeviceState
+import com.microsoft.identity.deviceregistration.java.api.DeviceRegistrationRecord
+import com.microsoft.identity.deviceregistration.java.api.IDeviceRegistrationRecord
+import com.microsoft.identity.deviceregistration.java.protocol.response.GetDeviceRegistrationRecordV0Response
+import com.microsoft.identity.deviceregistration.java.protocol.response.GetDeviceRegistrationRecordsV0Response
+import com.microsoft.identity.deviceregistration.java.protocol.response.GetRegistrationStateV0Response
+import com.microsoft.identity.deviceregistration.java.protocol.response.PreProvisionedBlobV0Response
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Before
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.mockito.kotlin.any
+import org.mockito.kotlin.mock
+import org.mockito.kotlin.whenever
+import org.robolectric.RobolectricTestRunner
+import java.util.UUID
+import java.util.concurrent.Executors
+import java.util.concurrent.TimeUnit
+
+/**
+ * Unit tests for [DeviceRegistrationClientApplication].
+ * Uses mock IPC strategy to verify DRCA methods call the controller
+ * with correct V0 params and return correctly parsed responses.
+ */
+@RunWith(RobolectricTestRunner::class)
+class DeviceRegistrationClientApplicationTest {
+
+    private lateinit var context: Context
+    private val backgroundExecutor = Executors.newSingleThreadExecutor()
+    private val packer = AndroidDeviceRegistrationProtocolPacker()
+    private val testBrokerPkg = "com.microsoft.test.broker"
+
+    @Before
+    fun setup() {
+        context = ApplicationProvider.getApplicationContext()
+    }
+
+    private fun createDrca(strategy: IIpcStrategy): DeviceRegistrationClientApplication {
+        val storageSupplier: com.microsoft.identity.common.java.interfaces.IStorageSupplier = mock(defaultAnswer = org.mockito.Mockito.RETURNS_DEEP_STUBS)
+        val components: IPlatformComponents = mock {
+            whenever(it.storageSupplier).thenReturn(storageSupplier)
+        }
+        val discoveryClient: IBrokerDiscoveryClient = mock {
+            whenever(it.getActiveBroker(false)).thenReturn(BrokerData(testBrokerPkg, "sig"))
+        }
+        val provider = object : DeviceRegistrationIpcStrategiesProvider() {
+            override fun getStrategies(
+                context: Context,
+                components: IPlatformComponents,
+                activeBrokerPackageName: String
+            ): MutableList<IIpcStrategy> = mutableListOf(strategy)
+        }
+        return DeviceRegistrationClientApplication(context, components, discoveryClient, provider)
+    }
+
+    private fun successStrategy(responseBundle: Bundle): IIpcStrategy {
+        val strategy: IIpcStrategy = mock()
+        whenever(strategy.getType()).thenReturn(IIpcStrategy.Type.CONTENT_PROVIDER)
+        whenever(strategy.communicateToBroker(any())).thenReturn(responseBundle)
+        return strategy
+    }
+
+    private fun <T> runOnBackground(op: () -> T): T {
+        val future = backgroundExecutor.submit(op)
+        try {
+            return future.get(5, TimeUnit.SECONDS)
+        } catch (e: java.util.concurrent.ExecutionException) {
+            throw e.cause ?: e
+        }
+    }
+
+    @Test
+    fun getPreProvisionedBlob_returnsJws() {
+        val expectedJws = "test.jws.blob"
+        val response = PreProvisionedBlobV0Response(UUID.randomUUID(), expectedJws)
+        val drca = createDrca(successStrategy(packer.pack(response)))
+
+        val result = runOnBackground {
+            drca.getPreProvisionedBlob("test-tenant", UUID.randomUUID())
+        }
+
+        assertEquals(expectedJws, result)
+    }
+
+    @Test
+    fun getRegistrationState_returnsDeviceState() {
+        val response = GetRegistrationStateV0Response(UUID.randomUUID(), "DEVICE_VALID")
+        val drca = createDrca(successStrategy(packer.pack(response)))
+
+        val result = runOnBackground {
+            drca.getRegistrationState(
+                DeviceRegistrationRecord("tenant", "upn", "device", false, false),
+                UUID.randomUUID()
+            )
+        }
+
+        assertEquals(DeviceState.DEVICE_VALID, result)
+    }
+
+    @Test
+    fun getRegistrationState_unknownState_returnsUnknown() {
+        val response = GetRegistrationStateV0Response(UUID.randomUUID(), "SOME_NEW_STATE")
+        val drca = createDrca(successStrategy(packer.pack(response)))
+
+        val result = runOnBackground {
+            drca.getRegistrationState(
+                DeviceRegistrationRecord("tenant", "upn", "device", false, false),
+                UUID.randomUUID()
+            )
+        }
+
+        assertEquals(DeviceState.UNKNOWN, result)
+    }
+
+    @Test
+    fun getDeviceRegistrationRecord_returnsRecord() {
+        val record = DeviceRegistrationRecord("test-tenant", "user@test.com", "device-123", false, true)
+        val response = GetDeviceRegistrationRecordV0Response(UUID.randomUUID(), record)
+        val drca = createDrca(successStrategy(packer.pack(response)))
+
+        val result = runOnBackground {
+            drca.getDeviceRegistrationRecord("test-tenant", UUID.randomUUID())
+        }
+
+        assertNotNull(result)
+        assertEquals("test-tenant", result!!.tenantId)
+        assertEquals("user@test.com", result.upn)
+        assertEquals("device-123", result.deviceId)
+    }
+
+    @Test
+    fun getDeviceRegistrationRecord_notFound_returnsNull() {
+        val response = GetDeviceRegistrationRecordV0Response(UUID.randomUUID(), null)
+        val drca = createDrca(successStrategy(packer.pack(response)))
+
+        val result = runOnBackground {
+            drca.getDeviceRegistrationRecord("unknown-tenant", UUID.randomUUID())
+        }
+
+        assertNull(result)
+    }
+
+    @Test
+    fun getAllEntries_returnsList() {
+        val records = listOf<IDeviceRegistrationRecord>(
+            DeviceRegistrationRecord("tenant1", "upn1", "dev1", false, false),
+            DeviceRegistrationRecord("tenant2", "upn2", "dev2", true, false)
+        )
+        val response = GetDeviceRegistrationRecordsV0Response(UUID.randomUUID(), records)
+        val drca = createDrca(successStrategy(packer.pack(response)))
+
+        val result = runOnBackground {
+            drca.getAllEntries(UUID.randomUUID())
+        }
+
+        assertEquals(2, result.size)
+        assertEquals("tenant1", result[0].tenantId)
+        assertEquals("tenant2", result[1].tenantId)
+    }
+
+    @Test
+    fun correlationId_isPassedToParameters() {
+        val correlationId = UUID.randomUUID()
+        val response = PreProvisionedBlobV0Response(UUID.randomUUID(), "jws")
+        val strategy: IIpcStrategy = mock()
+        whenever(strategy.getType()).thenReturn(IIpcStrategy.Type.CONTENT_PROVIDER)
+        whenever(strategy.communicateToBroker(any())).thenAnswer { invocation ->
+            val bundle = (invocation.arguments[0] as com.microsoft.identity.common.internal.broker.ipc.BrokerOperationBundle).bundle
+            val protocolData = bundle?.getByteArray("protocol.data")
+            assertNotNull(protocolData)
+            // Return the packed response
+            packer.pack(response)
+        }
+
+        val drca = createDrca(strategy)
+
+        runOnBackground {
+            drca.getPreProvisionedBlob("test-tenant", correlationId)
+        }
+        // If we get here without exception, the correlationId was accepted and the flow completed
+    }
+}

common/src/test/java/com/microsoft/identity/deviceregistration/DeviceRegistrationClientApplicationTest.kt

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft Corporation.
+// All rights reserved.
+//
+// This code is licensed under the MIT License.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files(the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions :
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+package com.microsoft.identity.deviceregistration.java
+
+/**
+ * Represents the WPJ device state as queried from ADRS.
+ */
+enum class DeviceState {
+    /** Device is found and valid. */
+    DEVICE_VALID,
+    /** Device was not found. */
+    DEVICE_NOT_FOUND,
+    /** Device was disabled (e.g. by the admin). */
+    DEVICE_DISABLED,
+    /** Unexpected state. */
+    UNKNOWN;
+
+    companion object {
+        /**
+         * Converts a raw state string (from V0 protocol response) to a [DeviceState].
+         * Returns [UNKNOWN] if the string doesn't match any known state.
+         */
+        @JvmStatic
+        fun fromString(state: String): DeviceState {
+            return try {
+                valueOf(state)
+            } catch (e: IllegalArgumentException) {
+                UNKNOWN
+            }
+        }
+    }
+}

common4j/src/main/com/microsoft/identity/deviceregistration/java/DeviceState.kt

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft Corporation.
+// All rights reserved.
+//
+// This code is licensed under the MIT License.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files(the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions :
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+package com.microsoft.identity.deviceregistration.java
+
+/**
+ * Discovery endpoint flags to indicate the instance for device registration.
+ */
+enum class DrsDiscoveryEndpoint {
+    /** Production instance. */
+    PROD,
+    /** PPE instance. */
+    PPE,
+    /** Int instance. */
+    INT;
+
+    companion object {
+        /**
+         * Converts a string into [DrsDiscoveryEndpoint].
+         * Returns [PROD] by default if not recognizable.
+         */
+        @JvmStatic
+        fun fromString(value: String?): DrsDiscoveryEndpoint {
+            if (value.isNullOrEmpty()) return PROD
+            return try {
+                valueOf(value)
+            } catch (e: IllegalArgumentException) {
+                PROD
+            }
+        }
+    }
+}

common4j/src/main/com/microsoft/identity/deviceregistration/java/DrsDiscoveryEndpoint.kt

@@ -36,5 +36,9 @@ public abstract class AbstractDeviceRegistrationProtocolParameters implements ID
 
     @Getter
     @NonNull
-    protected final UUID mCorrelationId = UUID.randomUUID();
+    protected final UUID mCorrelationId;
+
+    protected AbstractDeviceRegistrationProtocolParameters(@NonNull final UUID correlationId) {
+        mCorrelationId = correlationId;
+    }
 }