feat(flipcash): wire usernames through profile and resolver (#1316)

Refresh the flipcash protos, which introduce a public `Username` handle:

- common/v1 gains a `Username` message (lowercase `^[a-z0-9_]{2,15}$`)
- `UserProfile` carries `user_id` and `username`
- `GetProfileRequest.user_id` becomes a `oneof identifier` of user ID or username
- the resolver `Identifier` oneof gains `username`

Wire all of it through the service layer:

- `UserProfile` gains `userId`/`username`, mapped in `UserProfileMapper` and in
  the chat-member profile path, which decodes the same proto message. Both are
  trailing and default to null so the positional constructor and previously
  persisted profile JSON keep decoding.
- New `ProfileIdentifier` sealed interface mirrors the `GetProfileRequest` oneof
  and is threaded through `ProfileApi` -> `ProfileService` -> `ProfileRepository`.
  `ProfileController.getProfileForUser` is unchanged for callers; lookup by handle
  is `getProfileForUsername`.
- `ResolveIdentifier.Username` plus `ResolverController.resolve(username)`.

`ProfileApi.getProfile` now validates its request like every other method in the
class, so a malformed handle fails locally instead of round-tripping: the oneof
carries `validate.required` and the username its character-set pattern.

The opencode protos were already up to date.

Author: bmc08gt

definitions/flipcash/protos/src/main/proto/common/v1/common.proto

@@ -61,6 +61,13 @@ message UserId {
     }];
 }
 
+// Username is a user's unique handle on Flipcash. It uses the same character
+// set as X — letters, digits and underscores — with the exception that it must
+// be lowercase.
+message Username {
+    string value = 1 [(validate.rules).string.pattern = "^[a-z0-9_]{2,15}$"];
+}
+
 message ChatId {
     // value has the following structure:
     //  - 32 byte hash for DMs

definitions/flipcash/protos/src/main/proto/profile/v1/model.proto

@@ -12,12 +12,20 @@ import "google/protobuf/timestamp.proto";
 import "validate/validate.proto";
 
 message UserProfile {
+	// The ID of the user this profile belongs to. Always set, so a caller that
+	// looked the profile up by username learns the user's ID from the response.
+	common.v1.UserId user_id = 9 [(validate.rules).message.required = true];
+
 	// Display name is the display name of the user (if found).
 	string display_name = 1 [(validate.rules).string = {
 		min_len: 0
 		max_len: 64
 	}];
 
+	// The user's username on Flipcash. Public, so it is returned for any user,
+	// not just the caller. Unset when the user hasn't claimed one yet.
+	common.v1.Username username = 8;
+
 	// Social profiles are links to external social accounts
 	repeated SocialProfile social_profiles = 2 [(validate.rules).repeated = {
         min_items: 0

definitions/flipcash/protos/src/main/proto/profile/v1/profile_service.proto

@@ -38,7 +38,14 @@ service Profile {
 }
 
 message GetProfileRequest {
-	common.v1.UserId user_id = 1 [(validate.rules).message.required = true];
+	// The user whose profile is being fetched, identified either by their user
+	// ID or by their username. Exactly one must be set.
+	oneof identifier {
+		option (validate.required) = true;
+
+		common.v1.UserId   user_id  = 1;
+		common.v1.Username username = 3;
+	}
 
 	// Optional auth to retrieve private profile information for self
 	common.v1.Auth auth = 2;

definitions/flipcash/protos/src/main/proto/resolver/v1/model.proto

@@ -15,8 +15,9 @@ message Identifier {
     oneof kind {
         option (validate.required) = true;
 
-        common.v1.PhoneNumber phone   = 1;
-        common.v1.UserId      user_id = 2;
+        common.v1.PhoneNumber phone    = 1;
+        common.v1.UserId      user_id  = 2;
+        common.v1.Username    username = 3;
     }
 }
 

services/flipcash/src/main/kotlin/com/flipcash/services/controllers/ProfileController.kt

@@ -2,6 +2,7 @@ package com.flipcash.services.controllers
 
 import com.flipcash.services.models.GetUserProfileError
 import com.flipcash.services.models.LinkingToken
+import com.flipcash.services.models.ProfileIdentifier
 import com.flipcash.services.models.SocialAccount
 import com.flipcash.services.models.SocialAccountLinkRequest
 import com.flipcash.services.models.SocialAccountUnlinkRequest
@@ -68,11 +69,21 @@ class ProfileController @Inject constructor(
 
     suspend fun getProfileForUser(
         userId: ID,
-    ): Result<UserProfile> {
+    ): Result<UserProfile> = getProfile(ProfileIdentifier.UserId(userId))
+
+    /**
+     * Fetches a profile by its owner's public Flipcash handle. The response carries
+     * the user's ID, so a caller that only had the username learns it from here.
+     */
+    suspend fun getProfileForUsername(
+        username: String,
+    ): Result<UserProfile> = getProfile(ProfileIdentifier.Username(username))
+
+    private suspend fun getProfile(identifier: ProfileIdentifier): Result<UserProfile> {
         val owner = userManager.accountCluster?.authority?.keyPair
             ?: return Result.failure(Throwable("No account cluster in UserManager"))
 
-        return repository.getProfile(userId, owner)
+        return repository.getProfile(identifier, owner)
     }
 
     suspend fun setDisplayName(

services/flipcash/src/main/kotlin/com/flipcash/services/controllers/ResolverController.kt

@@ -22,6 +22,10 @@ class ResolverController @Inject constructor(
     suspend fun resolve(userId: ID): Result<PublicKey> =
         resolve(ResolveIdentifier.UserId(userId))
 
+    /** Resolves a username to its owner's on-chain address. */
+    suspend fun resolve(username: String): Result<PublicKey> =
+        resolve(ResolveIdentifier.Username(username))
+
     private suspend fun resolve(identifier: ResolveIdentifier): Result<PublicKey> {
         val owner = userManager.accountCluster?.authority?.keyPair
             ?: return Result.failure(Throwable("No account cluster in UserManager"))

services/flipcash/src/main/kotlin/com/flipcash/services/internal/domain/UserProfileMapper.kt

@@ -3,6 +3,8 @@ package com.flipcash.services.internal.domain
 import com.codeinc.flipcash.gen.profile.v1.Model
 import com.codeinc.flipcash.gen.profile.v1.emailAddressOrNull
 import com.codeinc.flipcash.gen.profile.v1.phoneNumberOrNull
+import com.codeinc.flipcash.gen.profile.v1.usernameOrNull
+import com.flipcash.services.internal.network.extensions.toId
 import com.flipcash.services.internal.network.extensions.toMediaItem
 import com.flipcash.services.models.UserProfile
 import com.flipcash.services.models.VerifiableContactMethod
@@ -25,6 +27,9 @@ class UserProfileMapper @Inject constructor(
                 Instant.fromEpochSeconds(from.joinTs.seconds, from.joinTs.nanos)
             } else null,
             tipCardColor = if (from.hasTipCardCustomization()) from.tipCardCustomization.color.hex else null,
+            userId = if (from.hasUserId()) from.userId.toId() else null,
+            // Public, so it is returned for any user — absent only when unclaimed.
+            username = from.usernameOrNull?.value,
         )
     }
 }

services/flipcash/src/main/kotlin/com/flipcash/services/internal/network/api/ProfileApi.kt

@@ -5,14 +5,15 @@ import com.codeinc.flipcash.gen.profile.v1.ProfileGrpcKt
 import com.codeinc.flipcash.gen.profile.v1.ProfileService
 import com.flipcash.services.internal.annotations.FlipcashManagedChannel
 import com.flipcash.services.internal.network.extensions.asUserId
+import com.flipcash.services.internal.network.extensions.asUsername
 import com.flipcash.services.internal.network.extensions.authenticate
 import com.flipcash.services.internal.network.extensions.linkingToken
+import com.flipcash.services.models.ProfileIdentifier
 import com.flipcash.services.models.SocialAccountLinkRequest
 import com.flipcash.services.models.SocialAccountUnlinkRequest
 import com.flipcash.services.models.chat.BlobId
 import com.getcode.ed25519.Ed25519
 import com.getcode.opencode.internal.network.core.GrpcApi
-import com.getcode.opencode.model.core.ID
 import com.getcode.utils.toByteString
 import com.codeinc.flipcash.gen.profile.v1.validate
 import dev.bmcreations.protovalidate.orThrow
@@ -32,14 +33,24 @@ internal class ProfileApi @Inject constructor(
         .withWaitForReady()
 
     /**
-     * Gets the profile for a user
+     * Gets the profile for a user, keyed by either their user ID or their username.
      */
-    suspend fun getProfile(userId: ID, owner: Ed25519.KeyPair): ProfileService.GetProfileResponse {
+    suspend fun getProfile(
+        identifier: ProfileIdentifier,
+        owner: Ed25519.KeyPair,
+    ): ProfileService.GetProfileResponse {
         val request = ProfileService.GetProfileRequest.newBuilder()
-            .setUserId(userId.asUserId())
+            .apply {
+                when (identifier) {
+                    is ProfileIdentifier.UserId -> setUserId(identifier.userId.asUserId())
+                    is ProfileIdentifier.Username -> setUsername(identifier.username.asUsername())
+                }
+            }
             .apply { setAuth(authenticate(owner)) }
             .build()
 
+        request.validate().orThrow()
+
         return withContext(Dispatchers.IO) {
             api.getProfile(request)
         }

services/flipcash/src/main/kotlin/com/flipcash/services/internal/network/api/ResolverApi.kt

@@ -7,6 +7,7 @@ import com.flipcash.services.models.ResolveIdentifier
 import com.flipcash.services.internal.annotations.FlipcashManagedChannel
 import com.flipcash.services.internal.network.extensions.asUserId
 import com.flipcash.services.internal.network.extensions.authenticate
+import com.flipcash.services.internal.network.extensions.asUsername
 import com.getcode.ed25519.Ed25519.KeyPair
 import com.getcode.opencode.internal.network.core.GrpcApi
 import dev.bmcreations.protovalidate.orThrow
@@ -50,6 +51,8 @@ internal class ResolverApi @Inject constructor(
                 builder.setPhone(Common.PhoneNumber.newBuilder().setValue(phone.phoneNumber))
             is ResolveIdentifier.UserId ->
                 builder.setUserId(userId.asUserId())
+            is ResolveIdentifier.Username ->
+                builder.setUsername(username.asUsername())
         }.build()
     }
 }

services/flipcash/src/main/kotlin/com/flipcash/services/internal/network/extensions/LocalToProtobuf.kt

@@ -45,6 +45,10 @@ internal fun ID.asUserId(): Common.UserId {
     return Common.UserId.newBuilder().setValue(toByteString()).build()
 }
 
+internal fun String.asUsername(): Common.Username {
+    return Common.Username.newBuilder().setValue(this).build()
+}
+
 internal fun Instant.asTimestamp(): Timestamp {
     return Timestamp.newBuilder().setSeconds(this.epochSeconds).build()
 }