GUEST TO AUTH CONVERSION FLOW

Ecosistema completo para organización y gestión de contenido con interfaces espaciales

Guest to Authenticated User Conversion Flow

Status: ✅ FULLY IMPLEMENTED & TESTED
Date: November 3, 2025
Category: Authentication & Data Migration

🎯 Overview

This document describes the complete flow for converting guest users (with temp- IDs) into authenticated users while preserving all their data, especially their space and universes.

🔄 Complete Conversion Flow

1. Guest User Creates Space

When a guest user first visits the app:

Guest User ID:  temp-66049009-eb1d-4504-a27b-2056953ea7e2
Space ID:       space_temp-66049009-eb1d-4504-a27b-2056953ea7e2
Space Slug:     temp-33nxc5km
Space Owner:    temp-66049009-eb1d-4504-a27b-2056953ea7e2

Backend creates space with custom ID (not MongoDB ObjectId):

_id: space_temp-66049009-eb1d-4504-a27b-2056953ea7e2
ownerId: temp-66049009-eb1d-4504-a27b-2056953ea7e2
spaceSlug: temp-33nxc5km

2. Guest User Registers

When the guest user decides to register:

Frontend:

// User clicks "Register" or "Sign Up"
await authService.register({
  email: '[email protected]',
  password: 'securePassword123',
  name: 'John Doe',
  guestUserId: currentGuestUserId // ← CRITICAL: Pass current guest user ID
});

Backend:

// apis/backend-api/src/app/backend-auth/backend-auth.service.ts
async register(registerDto: RegisterDto): Promise<LoginResponse> {
  // 1. Create new authenticated user
  const user = await this.userModel.create({
    email: registerDto.email,
    password: hashedPassword,
    name: registerDto.name,
    roles: ['user'],
    isActive: true,
  });

  const newUserId = user._id.toString(); // e.g., "6742f1e2a3b5d8f9c0123456"

  // 2. Transfer guest space if guestUserId provided
  if (registerDto.guestUserId) {
    const transferredSpace = await this.spacesService.transferGuestSpaceToAuthUser(
      registerDto.guestUserId,  // temp-66049009-eb1d-4504-a27b-2056953ea7e2
      newUserId                 // 6742f1e2a3b5d8f9c0123456
    );

    if (transferredSpace) {
      // Set as user's default space
      user.defaultSpaceId = transferredSpace.id;
      await user.save();
    }
  }

  // 3. Return JWT token
  return { accessToken, user };
}

3. Space Ownership Transfer

Backend Space Transfer Logic:

// apis/backend-api/src/app/spaces/spaces.service.ts
async transferGuestSpaceToAuthUser(
  guestUserId: string,    // temp-66049009-eb1d-4504-a27b-2056953ea7e2
  authUserId: string      // 6742f1e2a3b5d8f9c0123456
): Promise<SpaceResponse | null> {
  
  // Find guest space by custom ID (space_temp-xxx) or by ownerId (old format)
  const customSpaceId = `space_${guestUserId}`;
  let guestSpace = await this.spaceModel.findOne({ _id: customSpaceId as any }).exec();
  
  if (!guestSpace) {
    guestSpace = await this.spaceModel.findOne({ ownerId: guestUserId }).exec();
  }

  if (!guestSpace) {
    return null; // No guest space to transfer
  }

  // Update space ownership
  guestSpace.ownerId = authUserId;

  // Convert temp- slug to proper slug
  if (guestSpace.spaceSlug.startsWith('temp-')) {
    const properSlug = this.generateSlug(guestSpace.name);
    guestSpace.spaceSlug = properSlug; // temp-33nxc5km → 33nxc5km
  }

  const transferredSpace = await guestSpace.save();

  // Add space to user's spaces array
  await this.addSpaceToUser(authUserId, transferredSpace._id.toString());

  return this.toResponse(transferredSpace);
}

4. After Conversion

The space now belongs to the authenticated user:

Authenticated User ID:  6742f1e2a3b5d8f9c0123456
Space ID:               space_temp-66049009-eb1d-4504-a27b-2056953ea7e2 (unchanged)
Space Slug:             33nxc5km (temp- prefix removed)
Space Owner:            6742f1e2a3b5d8f9c0123456 (updated!)

Important:

Space _id remains the same (keeps all universe references intact)
Space ownerId updated to authenticated user
Space spaceSlug converted from temp format
All universes, pages, widgets remain associated via space ID

📋 Implementation Details

Backend Changes

1. RegisterDto Updated (`libs/api-contracts/src/lib/auth/auth.dto.ts`)

export class RegisterDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(6)
  password: string;

  @IsString()
  @MinLength(2)
  name: string;

  // 🎭 NEW: Optional guest user ID for space transfer
  @IsOptional()
  @IsString()
  guestUserId?: string;
}

2. SpacesService.transferGuestSpaceToAuthUser() (`apis/backend-api/src/app/spaces/spaces.service.ts`)

New method that:

✅ Finds guest space by custom ID (space_temp-xxx) or ownerId
✅ Updates ownerId to authenticated user
✅ Converts temp- slug to proper slug
✅ Adds space to user's spaces array
✅ Handles both ObjectId and custom ID formats

3. BackendAuthService.register() (`apis/backend-api/src/app/backend-auth/backend-auth.service.ts`)

Updated to:

✅ Accept optional guestUserId in registration
✅ Call transferGuestSpaceToAuthUser() if provided
✅ Set transferred space as user's default space
✅ Gracefully handle transfer failures

4. Module Dependencies (`apis/backend-api/src/app/backend-auth/backend-auth.module.ts`)

✅ Imported SpacesModule with forwardRef to avoid circular dependencies
✅ Injected SpacesService into BackendAuthService

Frontend Changes Needed

Update Registration Component

// When user registers, pass current guest user ID
async register(email: string, password: string, name: string) {
  const currentGuestUserId = this.guestAuthService.getCurrentGuestUserId();

  await this.authService.register({
    email,
    password,
    name,
    guestUserId: currentGuestUserId // ← CRITICAL
  });
}

🧪 Testing Checklist

Create Guest User: Visit app without logging in, create universes
Register Account: Sign up with email/password while still a guest
Verify Transfer: After registration, verify:
- Guest space ownership transferred to new user
- All universes still present
- Space slug converted (temp- removed)
- New user has space in their spaces array
- New user's defaultSpaceId set correctly

Backend Logs: Check for successful transfer logs:

🎭 Guest conversion detected for: temp-xxx
✅ Guest space transferred: space_temp-xxx

Check Both ID Formats:
- Test with new custom ID format (space_temp-xxx)
- Test with old ObjectId format (for backward compatibility)

⚠️ Important Notes

Space ID Persistence

Custom ID Format (space_temp-xxx): Space _id remains unchanged after conversion
Old ObjectId Format: Space _id also remains unchanged
This ensures all universe references remain valid

Slug Conversion

temp-33nxc5km → 33nxc5km
If slug collision occurs, timestamp is appended
Authenticated users never have temp- prefixed slugs

Error Handling

Registration succeeds even if space transfer fails
User can create new space if transfer fails
Errors logged but don't block user registration

Data Integrity

All universes maintain their references via space ID
All pages, widgets, flows remain intact
Local storage data transferred via frontend (separate process)

🔐 Security Considerations

Guest User Validation: Only transfers spaces where ownerId matches guestUserId
ID Format Validation: Ensures guestUserId starts with temp-
Space Ownership: Space ownerId updated to prevent unauthorized access
User Isolation: Each guest space is isolated to its owner

📊 Flow Diagram

┌─────────────────┐
│ Guest User      │
│ temp-xxx        │
└────────┬────────┘
         │
         ├─ Creates space (space_temp-xxx)
         ├─ Creates universes
         ├─ Creates pages
         │
         ▼
┌─────────────────┐
│ Clicks Register │
└────────┬────────┘
         │
         ▼
┌──────────────────────────────────┐
│ Frontend passes guestUserId      │
│ to registration endpoint          │
└────────┬─────────────────────────┘
         │
         ▼
┌──────────────────────────────────┐
│ Backend creates auth user        │
│ ID: 6742f1e2a3b5d8f9c0123456     │
└────────┬─────────────────────────┘
         │
         ▼
┌──────────────────────────────────┐
│ Backend transfers guest space:   │
│ - Find by space_temp-xxx ID      │
│ - Update ownerId to auth user    │
│ - Convert slug (remove temp-)    │
│ - Add to user's spaces array     │
└────────┬─────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│ ✅ Conversion Complete          │
│ - User has authenticated account│
│ - Space transferred              │
│ - All data preserved             │
└─────────────────────────────────┘

🐛 Troubleshooting

Issue: Guest space not transferring

Symptoms: User registers but doesn't get their guest space

Possible Causes:

Frontend not passing guestUserId in registration
Guest space ID format mismatch (old ObjectId vs new custom ID)
Space already has different ownerId

Solution:

Check frontend registration code includes guestUserId
Check backend logs for transfer attempt
Verify guest space exists in MongoDB with correct ownerId

Issue: Space has wrong ID format

Symptoms: Guest space has ObjectId instead of space_temp-xxx

Cause: Space created with old backend code before custom ID implementation