Merge pull request #6 from mauriciozanettisalomao/feat/lfxv2-587-user-metadata-read-auth0

[LFXV2-587] User metadata READ - Auth0

Author: mauriciozanettisalomao

README.md

@@ -92,6 +92,117 @@ nats request lfx.auth-service.email_to_username zephyr.stormwind@mythicaltech.io
 
 ---
 
+### User Metadata Retrieval
+
+To retrieve user metadata, send a NATS request to the following subject:
+
+**Subject:** `lfx.auth-service.user_metadata.read`  
+**Pattern:** Request/Reply
+
+The service supports two lookup strategies based on the input format, providing both authoritative identification and convenient username-based searches.
+
+##### Input Format and Strategy Selection
+
+The service automatically determines the lookup strategy based on the input format:
+
+- **Canonical Lookup** (contains `|`): `<connection>|<provider_user_id>` - Subject identifier
+- **Search Lookup** (no `|`): `<username>` - Convenience lookup
+
+##### Canonical Lookup Strategy (Recommended)
+
+**Format:** `<connection>|<provider_user_id>`
+
+The canonical lookup is the **authoritative, standard way to identify a user**, regardless of which provider they come from.
+
+**Examples:** `auth0|123456789`, `google-oauth2|987654321`, `samlp|my-connection|user123`
+
+##### Search Lookup Strategy (Convenience)
+
+**Format:** `<username>`
+
+Username lookups are **convenience only** and help avoid connection collisions within the Username-Password-Authentication connection.
+
+**Examples:** `john.doe`, `jane.smith`, `developer123`
+
+##### Request Payload
+
+The request payload should be a plain text identifier (no JSON wrapping required):
+
+**Canonical Lookup:**
+```
+auth0|123456789
+```
+
+**Search Lookup:**
+```
+john.doe
+```
+
+##### Reply
+
+The service returns a structured reply with user metadata:
+
+**Success Reply:**
+```json
+{
+  "success": true,
+  "data": {
+    "name": "John Doe",
+    "given_name": "John",
+    "family_name": "Doe",
+    "job_title": "Software Engineer",
+    "organization": "Example Corp",
+    "country": "United States",
+    "state_province": "California",
+    "city": "San Francisco",
+    "address": "123 Main Street",
+    "postal_code": "94102",
+    "phone_number": "+1-555-0123",
+    "t_shirt_size": "L",
+    "picture": "https://example.com/avatar.jpg",
+    "zoneinfo": "America/Los_Angeles"
+  }
+}
+```
+
+**Error Reply (User Not Found):**
+```json
+{
+  "success": false,
+  "error": "user not found"
+}
+```
+
+**Error Reply (Invalid Input):**
+```json
+{
+  "success": false,
+  "error": "input is required"
+}
+```
+
+##### Examples using NATS CLI
+
+```bash
+# Canonical lookup (subject identifier)
+# Note: Use quotes to escape the pipe character in shell commands
+nats request lfx.auth-service.user_metadata.read "auth0|123456789"
+
+# Search lookup (convenience username lookup)
+nats request lfx.auth-service.user_metadata.read john.doe
+
+```
+
+**Important Notes:**
+- **Canonical lookups** are the preferred method for system-to-system communication
+- **Search lookups** are provided for convenience and user-facing interfaces
+- The pipe character (`|`) in canonical identifiers must be escaped with quotes in shell commands
+- Both strategies return the same metadata format on success
+- When using mock or authelia mode, the service simulates Auth0 behavior for development and testing
+- For detailed Auth0-specific behavior and limitations, see the [Auth0 Integration Documentation](internal/infrastructure/auth0/README.md)
+
+---
+
 ### User Update Operation
 
 To update a user profile, send a NATS request to the following subject:

charts/lfx-v2-auth-service/Chart.yaml

@@ -5,5 +5,5 @@ apiVersion: v2
 name: lfx-v2-auth-service
 description: LFX Platform V2 Auth Service chart
 type: application
-version: 0.2.0
+version: 0.2.1
 appVersion: "latest"

cmd/server/service/message_handler.go

@@ -28,6 +28,7 @@ func (mhs *MessageHandlerService) HandleMessage(ctx context.Context, msg port.Tr
 	handlers := map[string]func(ctx context.Context, msg port.TransportMessenger) ([]byte, error){
 		constants.UserMetadataUpdateSubject: mhs.messageHandler.UpdateUser,
 		constants.UserEmailToUserSubject:    mhs.messageHandler.EmailToUsername,
+		constants.UserMetadataReadSubject:   mhs.messageHandler.GetUserMetadata,
 	}
 
 	handler, ok := handlers[subject]

cmd/server/service/providers.go

@@ -160,6 +160,7 @@ func QueueSubscriptions(ctx context.Context) error {
 	subjects := map[string]func(context.Context, port.TransportMessenger){
 		constants.UserMetadataUpdateSubject: messageHandlerService.HandleMessage,
 		constants.UserEmailToUserSubject:    messageHandlerService.HandleMessage,
+		constants.UserMetadataReadSubject:   messageHandlerService.HandleMessage,
 		// Add more subjects here as needed
 	}
 

internal/domain/model/auth0.go

@@ -23,25 +23,46 @@ type Auth0Identity struct {
 	IsSocial   bool   `json:"isSocial"`
 }
 
-// Auth0UserMetadata represents the metadata of a user in Auth0
+// Auth0UserMetadata represents the metadata of a user in Auth0.
+//
+// It's the same as the domain User.UserMetadata, but it might be useful
+// to have it separated for Auth0 to handle it separately if needed.
 type Auth0UserMetadata struct {
-	Name       *string `json:"name"`
-	FamilyName *string `json:"family_name"`
-	GivenName  *string `json:"given_name"`
-	Picture    *string `json:"picture"`
-	JobTitle   *string `json:"job_title"`
+	Name          *string `json:"name"`
+	FamilyName    *string `json:"family_name"`
+	GivenName     *string `json:"given_name"`
+	Picture       *string `json:"picture"`
+	JobTitle      *string `json:"job_title"`
+	Organization  *string `json:"organization"`
+	Country       *string `json:"country"`
+	StateProvince *string `json:"state_province"`
+	City          *string `json:"city"`
+	Address       *string `json:"address"`
+	PostalCode    *string `json:"postal_code"`
+	PhoneNumber   *string `json:"phone_number"`
+	TShirtSize    *string `json:"t_shirt_size"`
+	Zoneinfo      *string `json:"zoneinfo"`
 }
 
 // ToUser converts an Auth0User to a User
 func (u *Auth0User) ToUser() *User {
 	var meta *UserMetadata
 	if u.UserMetadata != nil {
 		meta = &UserMetadata{
-			Name:       u.UserMetadata.Name,
-			FamilyName: u.UserMetadata.FamilyName,
-			GivenName:  u.UserMetadata.GivenName,
-			Picture:    u.UserMetadata.Picture,
-			JobTitle:   u.UserMetadata.JobTitle,
+			Name:          u.UserMetadata.Name,
+			FamilyName:    u.UserMetadata.FamilyName,
+			GivenName:     u.UserMetadata.GivenName,
+			Picture:       u.UserMetadata.Picture,
+			JobTitle:      u.UserMetadata.JobTitle,
+			Organization:  u.UserMetadata.Organization,
+			Country:       u.UserMetadata.Country,
+			StateProvince: u.UserMetadata.StateProvince,
+			City:          u.UserMetadata.City,
+			Address:       u.UserMetadata.Address,
+			PostalCode:    u.UserMetadata.PostalCode,
+			PhoneNumber:   u.UserMetadata.PhoneNumber,
+			TShirtSize:    u.UserMetadata.TShirtSize,
+			Zoneinfo:      u.UserMetadata.Zoneinfo,
 		}
 	}
 	return &User{

internal/domain/model/user.go

@@ -14,6 +14,7 @@ import (
 type User struct {
 	Token        string        `json:"token" yaml:"token"`
 	UserID       string        `json:"user_id" yaml:"user_id"`
+	Sub          string        `json:"sub,omitempty" yaml:"sub,omitempty"`
 	Username     string        `json:"username" yaml:"username"`
 	PrimaryEmail string        `json:"primary_email" yaml:"primary_email"`
 	UserMetadata *UserMetadata `json:"user_metadata,omitempty" yaml:"user_metadata,omitempty"`
@@ -60,6 +61,7 @@ func (u *User) UserSanitize() {
 	// Sanitize basic user fields
 	u.Token = strings.TrimSpace(u.Token)
 	u.UserID = strings.TrimSpace(u.UserID)
+	u.Sub = strings.TrimSpace(u.Sub)
 	u.Username = strings.TrimSpace(u.Username)
 	u.PrimaryEmail = strings.TrimSpace(u.PrimaryEmail)
 
@@ -116,3 +118,22 @@ func (um *UserMetadata) userMetadataSanitize() {
 		*um.Zoneinfo = strings.TrimSpace(*um.Zoneinfo)
 	}
 }
+
+// PrepareForMetadataLookup prepares the user for metadata lookup based on the input
+// Returns true if should use canonical lookup, false if should use search
+func (u *User) PrepareForMetadataLookup(input string) bool {
+	input = strings.TrimSpace(input)
+
+	if strings.Contains(input, "|") {
+		// Input contains "|", use as sub for canonical lookup
+		u.Sub = input
+		u.UserID = input // Auth0 uses user_id for the canonical lookup
+		u.Username = ""  // Clear username field
+		return true
+	}
+	// Input doesn't contain "|", use for search query
+	u.Sub = ""    // Clear sub field
+	u.UserID = "" // Clear user_id field
+	u.Username = input
+	return false
+}