Better support for custom party hints for non-operator users (#3367)

Signed-off-by: Pasindu Tennage <pasindu.tennage@digitalasset.com>

[ci]

Author: pasindutennage-da

apps/app/src/main/scala/org/lfdecentralizedtrust/splice/console/ValidatorAppReference.scala

@@ -105,10 +105,14 @@ abstract class ValidatorAppReference(
   @Help.Description(
     """Onboard individual canton-amulet user with a fresh or existing party-id. Return the user's partyId."""
   )
-  def onboardUser(user: String, existingPartyId: Option[PartyId] = None): PartyId = {
+  def onboardUser(
+      user: String,
+      existingPartyId: Option[PartyId] = None,
+      createIfMissing: Option[Boolean] = None,
+  ): PartyId = {
     consoleEnvironment.run {
       httpCommand(
-        HttpValidatorAdminAppClient.OnboardUser(user, existingPartyId)
+        HttpValidatorAdminAppClient.OnboardUser(user, existingPartyId, createIfMissing)
       )
     }
   }

apps/app/src/test/scala/org/lfdecentralizedtrust/splice/integration/tests/ValidatorIntegrationTest.scala

@@ -578,4 +578,82 @@ class ValidatorIntegrationTest extends IntegrationTest with WalletTestUtil {
     getUser.primaryParty.value.uid.identifier shouldBe validatorPartyHint
   }
 
+  "onboard user with custom party hint and check assignment/creation modes" in { implicit env =>
+    initDso()
+    aliceValidatorBackend.startSync()
+
+    val aliceValidatorParty = aliceValidatorBackend.getValidatorPartyId()
+    val testUser1 = s"test-1-${Random.nextInt(10000)}"
+    val testUser2 = s"test-2-${Random.nextInt(10000)}"
+    val testUser3 = s"test-3-${Random.nextInt(10000)}"
+    val testUser4 = s"test-4-${Random.nextInt(10000)}"
+    val customPartyHint = s"CustomHint${Random.nextInt(10000)}"
+
+    def onboard(
+        name: String,
+        partyId: Option[PartyId] = None,
+        createIfMissing: Option[Boolean] = None,
+    ): PartyId = {
+      aliceValidatorBackend.onboardUser(name, partyId, createIfMissing)
+    }
+
+    clue(
+      "Assign new user to existing Validator Party"
+    ) {
+      aliceValidatorBackend.listUsers() should not contain testUser1
+      val assignedPartyId = onboard(
+        name = testUser1,
+        partyId = Some(aliceValidatorParty),
+      )
+      assignedPartyId shouldBe aliceValidatorParty
+      aliceValidatorBackend.listUsers() should contain(testUser1)
+    }
+
+    clue("Use 'name' as hint") {
+      aliceValidatorBackend.listUsers() should not contain testUser2
+
+      val defaultPartyId = onboard(
+        name = testUser2,
+        createIfMissing = Some(true),
+      )
+
+      val expectedHint = BaseLedgerConnection.sanitizeUserIdToPartyString(testUser2)
+      defaultPartyId.toString.split("::").head shouldBe expectedHint
+      aliceValidatorBackend.listUsers() should contain(testUser2)
+    }
+
+    clue("Use partyId as hint") {
+      val desiredPartyId = PartyId.tryCreate(customPartyHint, aliceValidatorParty.uid.namespace)
+      aliceValidatorBackend.listUsers() should not contain testUser3
+      val customPartyId = onboard(
+        name = testUser3,
+        partyId = Some(desiredPartyId),
+        createIfMissing = Some(true),
+      )
+
+      customPartyId.toString.split("::").head shouldBe customPartyHint
+      customPartyId shouldBe desiredPartyId
+      aliceValidatorBackend.listUsers() should contain(testUser3)
+    }
+
+    clue("Fail when creation is disallowed but no party is provided to assign to") {
+      loggerFactory.assertEventuallyLogsSeq(SuppressionRule.LevelAndAbove(Level.DEBUG))(
+        intercept[com.digitalasset.canton.console.CommandFailure] {
+          onboard(
+            name = testUser4,
+            createIfMissing = Some(false),
+          )
+        },
+        entries => {
+          forAtLeast(1, entries)(
+            _.message should include(
+              s"party_id must be provided when createPartyIfMissing is false and no existing"
+            )
+          )
+        },
+      )
+      aliceValidatorBackend.listUsers() should not contain testUser4
+    }
+  }
+
 }

apps/validator/src/main/openapi/validator-internal.yaml

@@ -551,11 +551,19 @@ components:
       properties:
         name:
           type: string
+          description: The name of the user to onboard.
         party_id:
           type: string
           description: |
-            The party id of the user to onboard. This is optional and if not provided
-            a fresh party id will be generated by the backend.
+            The party id of the user to onboard.
+            If no party_id is provided then a fresh party will be generated, using the 'name' as the Party Hint.
+            If party_id is provided and createPartyIfMissing is false, then the party must already exist on the ledger. The existing party will be assigned to the user.
+            If party_id is provided and createPartyIfMissing is true, then: if a party with the provided party_id exists, the user will be associated with it. Otherwise, a new party will be created using the provided party_id, and the user will be associated with that new party.
+        createPartyIfMissing:
+          type: boolean
+          description: |
+            If true, create the party if it does not already exist on the ledger.
+            Default is 'false'.
 
     OnboardUserResponse:
       type: object

apps/validator/src/main/scala/org/lfdecentralizedtrust/splice/validator/ValidatorApp.scala

@@ -525,6 +525,7 @@ class ValidatorApp(
         .onboard(
           instance.walletUser.getOrElse(instance.serviceUser),
           Some(party),
+          Some(false),
           storeWithIngestion,
           validatorUserName = config.ledgerApiUser,
           // we're initializing so AmuletRules is guaranteed to be on synchronizerId
@@ -973,6 +974,7 @@ class ValidatorApp(
           ValidatorUtil.onboard(
             endUserName = user,
             knownParty = Some(validatorParty),
+            Some(false),
             automation,
             validatorUserName = config.ledgerApiUser,
             // we're initializing so AmuletRules is guaranteed to be on synchronizerId

apps/validator/src/main/scala/org/lfdecentralizedtrust/splice/validator/admin/api/client/commands/HttpValidatorAdminAppClient.scala

@@ -98,15 +98,19 @@ object HttpValidatorAdminAppClient {
     }
   }
 
-  case class OnboardUser(name: String, existingPartyId: Option[PartyId])
-      extends BaseCommand[http.OnboardUserResponse, PartyId] {
+  case class OnboardUser(
+      name: String,
+      existingPartyId: Option[PartyId],
+      createIfMissing: Option[Boolean] = None,
+  ) extends BaseCommand[http.OnboardUserResponse, PartyId] {
 
     def submitRequest(
         client: Client,
         headers: List[HttpHeader],
     ): EitherT[Future, Either[Throwable, HttpResponse], http.OnboardUserResponse] =
       client.onboardUser(
-        definitions.OnboardUserRequest(name, existingPartyId.map(_.toProtoPrimitive)),
+        definitions
+          .OnboardUserRequest(name, existingPartyId.map(_.toProtoPrimitive), createIfMissing),
         headers,
       )
 

apps/validator/src/main/scala/org/lfdecentralizedtrust/splice/validator/admin/http/HttpValidatorAdminHandler.scala

@@ -114,8 +114,8 @@ class HttpValidatorAdminHandler(
     withSpan(s"$workflowId.onboardUser") { _ => span =>
       val name = body.name
       span.setAttribute("name", name)
-      onboard(name, body.partyId.map(PartyId.tryFromProtoPrimitive)).map(p =>
-        definitions.OnboardUserResponse(p)
+      onboard(name, body.partyId.map(PartyId.tryFromProtoPrimitive), body.createPartyIfMissing).map(
+        p => definitions.OnboardUserResponse(p)
       )
     }
   }
@@ -235,13 +235,18 @@ class HttpValidatorAdminHandler(
     }
   }
 
-  private def onboard(name: String, partyId: Option[PartyId])(implicit
+  private def onboard(
+      name: String,
+      partyId: Option[PartyId],
+      createPartyIfMissing: Option[Boolean],
+  )(implicit
       traceContext: TraceContext
   ): Future[String] = {
     ValidatorUtil
       .onboard(
         name,
         partyId,
+        createPartyIfMissing,
         storeWithIngestion,
         validatorUserName,
         getAmuletRulesDomain,

apps/validator/src/main/scala/org/lfdecentralizedtrust/splice/validator/admin/http/HttpValidatorHandler.scala

@@ -50,6 +50,7 @@ class HttpValidatorHandler(
       .onboard(
         name,
         None,
+        None,
         storeWithIngestion,
         validatorUserName,
         getAmuletRulesDomain,

apps/validator/src/main/scala/org/lfdecentralizedtrust/splice/validator/util/ValidatorUtil.scala

@@ -25,7 +25,7 @@ import com.digitalasset.canton.topology.transaction.*
 import com.digitalasset.canton.topology.{PartyId, SynchronizerId}
 import com.digitalasset.canton.tracing.TraceContext
 import com.digitalasset.canton.util.HexString
-import io.grpc.Status
+import io.grpc.{Status, StatusRuntimeException}
 import org.lfdecentralizedtrust.splice.store.AppStoreWithIngestion.SpliceLedgerConnectionPriority
 
 import java.util.Base64
@@ -96,6 +96,7 @@ private[validator] object ValidatorUtil {
   def onboard(
       endUserName: String,
       knownParty: Option[PartyId],
+      createPartyIfMissing: Option[Boolean],
       storeWithIngestion: AppStoreWithIngestion[ValidatorStore],
       validatorUserName: String,
       getAmuletRulesDomain: ScanConnection.GetAmuletRulesDomain,
@@ -110,17 +111,77 @@ private[validator] object ValidatorUtil {
     for {
       userPartyId <- knownParty match {
         case Some(party) =>
-          connection.createUserWithPrimaryParty(
-            endUserName,
-            party,
-            Seq(),
-          )
+          if (createPartyIfMissing.getOrElse(false)) {
+            for {
+              newlyAllocatedPartyId <- connection.getOrAllocateParty(
+                party.uid.identifier.unwrap,
+                Seq(),
+                participantAdminConnection,
+              )
+              allocatedPartyId <- connection.createUserWithPrimaryParty(
+                endUserName,
+                newlyAllocatedPartyId,
+                Seq(),
+              )
+            } yield {
+              logger.debug(
+                s"Creation allowed. Allocated new party ID $allocatedPartyId for user $endUserName"
+              )
+              allocatedPartyId
+            }
+          } else {
+            connection
+              .createUserWithPrimaryParty(
+                endUserName,
+                party,
+                Seq(),
+              )
+              .map(newParty => {
+                logger.debug(
+                  s"Creation disallowed. Associating user $endUserName with existing party $newParty"
+                )
+                newParty
+              })
+          }
         case None =>
-          connection.getOrAllocateParty(
-            endUserName,
-            Seq(),
-            participantAdminConnection,
-          )
+          if (createPartyIfMissing.getOrElse(true)) {
+            connection
+              .getOrAllocateParty(
+                endUserName,
+                Seq(),
+                participantAdminConnection,
+              )
+              .map(allocatedParty => {
+                logger.debug(
+                  s"No party ID provided and creation allowed. Allocated $allocatedParty for user $endUserName"
+                )
+                allocatedParty
+              })
+          } else {
+            logger.debug(
+              s"No party ID provided and creation disallowed. Checking for existing party."
+            )
+            connection
+              .getOptionalPrimaryParty(endUserName)
+              .recover {
+                case e: StatusRuntimeException if e.getStatus.getCode == Status.Code.NOT_FOUND =>
+                  None
+              }
+              .map {
+                case Some(existingParty) =>
+                  logger.debug(
+                    s"No party ID provided, creation disallowed, but user $endUserName has existing party $existingParty."
+                  )
+                  existingParty
+
+                case None =>
+                  throw Status.INVALID_ARGUMENT
+                    .withDescription(
+                      s"party_id must be provided when createPartyIfMissing is false and no existing party for user $endUserName is found."
+                    )
+                    .asRuntimeException()
+              }
+          }
       }
       _ <- retryProvider.ensureThatB(
         RetryFor.ClientCalls,

docs/src/release_notes.rst

@@ -7,6 +7,9 @@
 
 .. release-notes:: upcoming
 
+  - Validator
+    - Added support for picking a custom name for new parties created when onboarding users via the `/v0/admin/users` API. See :ref:`docs <validator-users>`.
+
   - API security
 
     - Tightened authorization checks for all non-public API endpoints.

docs/src/validator_operator/validator_users.rst

@@ -19,7 +19,12 @@ with the newly allocated party. As part of validator initialization, a party is
 Validator Operator. The user provided during installation as the `validatorWalletUser` will be
 associated with this party as its primary party.
 
-More users can be configured such that their primary party is that of the validator operator.
+In addition to above approach, the validator API endpoint `/v0/admin/users` supports two additional modes for creating user and party associations:
+
+1. Association with Existing Party: Linking a user to an existing party.
+2. Custom Party Hint: Allocating a new party using a human-readable party hint and associating the user to this newly created party.
+
+Association with Existing Party: Users can be configured such that their primary party is that of the validator operator (or any other existing party).
 In effect, when such users login to the wallet UI, they will be accessing the wallet of the validator
 operator. Note that this will be the same wallet accessed by different users, with currently
 no support for finer grained permissions per user.
@@ -49,6 +54,18 @@ In order to associate a user with the party of the validator operator, the follo
    onboarded through the API call above. If you do see the button, it means that something has gone wrong
    in the process above (do not click the button!).
 
+Custom Party Hint: This mode allows providing a human-readable Party hint when creating a new party for a user.
+This is used to create parties with descriptive hints (e.g., treasury_dept::...) instead of OAuth IDs.
+
+1. Follow steps 1-3 from Mode ``Association with Existing Party`` to obtain the USER and TOKEN.
+2. Determine the desired, full PartyID ``(Hint::Namespace)``, e.g., ``alice::f3d917....``. Use the namespace of an existing party (like the validator operator's) for the namespace part. Save the full ID in a ``PARTY_ID`` environment variable: ``export PARTY_ID=alice::f3d917...``.
+3. Run the following command to create the new party and associate the user:
+
+.. code-block:: bash
+
+    curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    --data-raw "{\"party_id\":\"$PARTY_ID\",\"name\":\"$USER\",\"createPartyIfMissing\":true}" \
+    https://<URL of your wallet>/api/validator/v0/admin/users
 
 Disable wallet and wallet automation
 -----------------------------------------------