Starworld/docs/OAUTH_TESTING.md

OAuth Authentication Testing Guide

Overview

Starworld now includes full OAuth 2.0 browser-based authentication for connecting to Overte servers with your user account.

Quick Test

Test 1: Browser OAuth Flow

cd /home/mayatheshy/stardust/Starworld
./build/starworld --auth --overte=127.0.0.1:40102

Expected Behavior:

1. Application starts callback server on port 8765
2. Browser opens to Overte login page
3. You log in with your Overte credentials
4. Browser redirects to localhost callback
5. Application receives authorization code
6. Token is exchanged and saved
7. Connection to domain server proceeds with authentication

Success Indicators:

• [Auth] Starting browser-based authentication...
• [OverteAuth] Callback server listening on port 8765
• [OverteAuth] Opening browser to: https://...
• [OverteAuth] Received authorization code: ...
• [OverteAuth] Successfully exchanged authorization code for token
• [OverteAuth] Token saved to ~/.config/starworld/overte_token.txt

Test 2: Saved Token Reuse

After Test 1 succeeds, run again:

./build/starworld --auth --overte=127.0.0.1:40102

Expected Behavior:

• No browser opens
• Token loaded from file
• If token is still valid, no re-authentication needed
• If token expired but refresh token valid, automatic refresh

Success Indicators:

• [Auth] Using saved token for <username>
• [OverteAuth] Loaded saved token for <username>
• No browser window opens

Test 3: Token Refresh

To test automatic token refresh, manually edit the token file to make it expire soon:

# Edit expiration timestamp
nano ~/.config/starworld/overte_token.txt
# Change last line (timestamp) to current time + 500 seconds

Then run:

./build/starworld --auth --overte=127.0.0.1:40102

Expected Behavior:

• Token detected as expiring soon
• Automatic refresh attempt
• New token saved

Success Indicators:

• [OverteAuth] Token expiring soon, refreshing...
• [OverteAuth] Successfully refreshed access token

Test 4: Entity Data with Authentication

With authentication enabled, you should receive full assignment client topology:

./build/starworld --auth --overte=127.0.0.1:40102

Look for:

• [OverteClient] Parsed X assignment clients (X > 0)
• [OverteClient] Assignment client: EntityServer at ...
• [OverteClient] Entity server found at ...
• Entity data packets received

Compare with anonymous connection:

./build/starworld --overte=127.0.0.1:40102  # No --auth

You should see:

• [OverteClient] Parsed 0 assignment clients
• [OverteClient] Warning: No EntityServer found in assignment client list

Troubleshooting

Browser Doesn't Open

Symptom: [OverteAuth] Failed to open browser

Solution:

1. Manually copy the URL from console
2. Paste into browser
3. Complete authentication
4. Application will receive callback automatically

Port 8765 Already in Use

Symptom: [OverteAuth] Failed to bind socket

Solution: The callback server will automatically try a different port (OS-assigned). Check console for actual port number.

CSRF State Mismatch

Symptom: [OverteAuth] State mismatch - possible CSRF attack!

Cause: Browser navigated to old/cached authorization URL

Solution:

1. Clear browser cache
2. Restart authentication flow
3. Use the freshly generated URL

Token File Permissions

Symptom: Cannot save/load token

Solution:

# Ensure config directory exists
mkdir -p ~/.config/starworld
chmod 700 ~/.config/starworld

# Fix token file permissions
chmod 600 ~/.config/starworld/overte_token.txt

Testing Against Different Metaverse Servers

# Use custom metaverse server
OVERTE_METAVERSE=https://my-custom-server.org ./build/starworld --auth

# Or for self-hosted domain servers
./build/starworld --auth --overte=my-domain.local:40102

File Locations

• Token Storage: ~/.config/starworld/overte_token.txt
• Token Format:

  <metaverse_url>
  <username>
  <access_token>
  <refresh_token>
  <expiration_timestamp>
  

Security Notes

1. Token File: Contains sensitive authentication tokens. File permissions are automatically set to 0600 (user read/write only).

2. Callback Server: Binds to localhost only, preventing external access.

3. CSRF Protection: Uses random state parameter to prevent cross-site request forgery.

4. HTTPS: OAuth endpoints use HTTPS for secure token exchange.

5. Token Lifetime: Tokens automatically refresh before expiration (1 hour threshold).

Comparison: Anonymous vs Authenticated

Feature	Anonymous	Authenticated
Public domains	✅	✅
Private domains	❌	✅
Assignment client list	❌ (empty)	✅ (full topology)
Direct EntityServer	❌	✅
Entity editing	❌	✅ (future)
Voice chat	❌	✅ (future)
Performance	Slower (domain server fallback)	Faster (direct connections)

Next Steps

Once OAuth authentication works, the next phase is to:

1. Use access token in EntityQuery packets
2. Establish direct connections to EntityServer
3. Parse full entity data with authentication
4. Test with your local Overte server's entities

Example Session

$ ./build/starworld --auth --overte=127.0.0.1:40102

[Auth] ===================================
[Auth] Overte OAuth Authentication
[Auth] Metaverse: https://mv.overte.org
[Auth] ===================================
[Auth] Starting browser-based authentication...
[OverteAuth] Callback server listening on port 8765
[OverteAuth] ===================================
[OverteAuth] Opening browser for authentication
[OverteAuth] If browser doesn't open automatically, navigate to:
[OverteAuth] https://mv.overte.org/oauth/authorize?response_type=code&client_id=starworld&redirect_uri=http%3A%2F%2Flocalhost%3A8765%2Fcallback&scope=owner&state=a1b2c3d4...
[OverteAuth] ===================================
[OverteAuth] Opening browser to: https://mv.overte.org/oauth/...
[OverteAuth] Waiting for authentication callback...

(User logs in via browser...)

[OverteAuth] Callback server thread started
[OverteAuth] Received authorization code: Xy7zQ9...
[OverteAuth] Exchanging authorization code for access token...
[OverteAuth] Token received, expires in 7200 seconds
[OverteAuth] Access token: eyJhbGciOiJSUzI1...
[OverteAuth] Token saved to /home/user/.config/starworld/overte_token.txt
[OverteAuth] Successfully exchanged authorization code for token
[OverteAuth] Callback server thread stopped
[Auth] ✓ Successfully authenticated!
[Auth] Username: your_username

[StardustBridge] Loaded Rust bridge: ./bridge/target/debug/libstardust_bridge.so
[StardustBridge] Connected via Rust bridge (C-ABI).
[main] Connecting to Overte domain: 127.0.0.1:40102
[OverteClient] Session UUID: a1b2c3d4-...
[OverteClient] Connecting to domain at 127.0.0.1 (HTTP:40100, UDP:40102)
...
[OverteClient] Parsed 6 assignment clients
[OverteClient] Assignment client: EntityServer at 192.168.1.100:33237
[OverteClient] Entity server found at 192.168.1.100:33237
[OverteClient] Domain connected! Sending entity query to entity-server...