Starworld/docs/OVERTE_AUTH.md

# Overte Authentication Implementation Notes# Overte Domain Authentication



## Current Status## Current Status



Authentication infrastructure is **partially implemented** but disabled. The basic OAuth client code exists in `src/OverteAuth.{hpp,cpp}`, but it's not currently functional due to protocol differences.✅ **Handshake Success!** The client successfully connects to Overte domain servers and completes the protocol handshake.



## What's Missing for Full OAuth Support**Achievements:**

- Discovered correct protocol signature from mv.overte.org metaverse API

### 1. Web-Based OAuth Flow (Primary Issue)- Protocol version: `6xYA55jcXgPHValo3Ba3/A==` (eb1600e798dc5e03c755a968dc16b7fc)

- UDP communication established with domain server

**Problem:** Overte uses a **browser-based OAuth 2.0 flow**, not direct API password grant.- DomainConnectRequest packets properly formatted and sent

- **DomainList responses received** with assignment client endpoints

**Current Implementation:**- Server accepts our protocol version and sends mixer information

```cpp

// src/OverteAuth.cpp - INCORRECT APPROACH**Technical Details:**

POST https://mv.overte.org/oauth/token- Found 511 public Overte servers via https://mv.overte.org/server/api/v1/places

grant_type=password&username=...&password=...- Most servers use common protocol version `6xYA55jcXgPHValo3Ba3/A==`

```- Successfully tested against local domain server (received EntityServer endpoints)

- Assignment client parsing implemented and working

**Required Implementation:**

Overte follows the standard OAuth 2.0 authorization code flow:**Next Steps:**

1. Parse assignment client list from DomainList packets

```2. Connect to EntityServer UDP endpoint

1. Client → Browser: Open https://mv.overte.org/oauth/authorize?3. Send EntityQuery packets to request world data

                     client_id=CLIENT_ID&4. Parse EntityAdd/EntityEdit/EntityErase packets

                     redirect_uri=http://localhost:CALLBACK_PORT&5. Stream entities to Stardust XR

                     response_type=code&

                     scope=owner### Working Alternative: Test Environment



2. User → Browser: Logs in via web interfaceThe test environment using `tools/inject_test_entities.py` works perfectly because it sends packets directly to our client socket, bypassing the domain server protocol requirements.



3. Metaverse → Client: Redirects to http://localhost:CALLBACK_PORT?code=AUTH_CODE**To use the test environment:**

```bash

4. Client → Metaverse: POST https://mv.overte.org/oauth/token# Terminal 1: Start the client

                        grant_type=authorization_code&./build/stardust-overte-client

                        code=AUTH_CODE&

                        client_id=CLIENT_ID&# Terminal 2: Inject test entities

                        client_secret=CLIENT_SECRET&python3 tools/inject_test_entities.py

                        redirect_uri=http://localhost:CALLBACK_PORT```



5. Metaverse → Client: { "access_token": "...", "refresh_token": "...", "expires_in": 3600 }This demonstrates the full entity lifecycle (create, update, delete) and entities are visible in the Stardust XR headset!

```

## Full Protocol Implementation (TODO)

**Implementation Requirements:**

- HTTP server to listen for OAuth callback (libmicrohttpd or embedded HTTP server)To connect to a real Overte domain server, we need to implement:

- Browser launcher (`xdg-open` on Linux, `open` on macOS, `start` on Windows)

- OAuth state parameter for CSRF protection###  1. NLPacket Format

- PKCE (Proof Key for Code Exchange) for additional securityOverte uses a custom reliable UDP protocol with:

- Packet headers (sequence numbers, acks, etc.)

**References:**- Message fragmentation/reassembly

- Overte source: `libraries/networking/src/AccountManager.cpp::requestAccessTokenWithAuthCode()`- Reliable delivery guarantees

- OAuth 2.0 spec: https://www.rfc-editor.org/rfc/rfc6749

### 2. Proper Authentication Flow

### 2. Client Registration1. Send DomainConnectRequest with NLPacket header

2. Receive DomainConnectionTokenRequest

**Problem:** Need valid OAuth `client_id` and `client_secret`.3. Send authentication credentials

4. Receive DomainList with assignment client endpoints

**Current State:** Not registered with mv.overte.org.5. Connect to each assignment client (EntityServer, Avatar, Audio)



**Solution:**### 3. Assignment Client Protocol

- Register Starworld as an OAuth client with Overte metaverse- Each mixer (EntityServer, AvatarMixer, AudioMixer) has its own handshake

- Or use Overte's default client ID if available for third-party clients- EntityServer requires octree-based spatial queries

- Store credentials securely (not in source code)- Proper node type identification in packets



**Overte Interface Client IDs:**## Running with Authentication (When Protocol is Implemented)

Check `interface/src/AccountManager.cpp` for hardcoded client credentials, or:

```bash### Method 1: Interactive Script

grep -r "CLIENT_ID\|client_id" overte/interface/```bash

```./run_with_auth.sh

```

### 3. Token ManagementThis will prompt you for username and password.



**Missing Features:**### Method 2: Environment Variables

- ✅ Access token storage (implemented)```bash

- ✅ Refresh token storage (implemented)OVERTE_USERNAME="your_username" ./build/starworld

- ❌ Token expiration tracking (partially implemented, needs completion)```

- ❌ Automatic token refresh before expiration

- ❌ Persistent token storage (save to disk for reuse across sessions)### Method 3: Export Variables

- ❌ Secure token storage (keychain integration)```bash

export OVERTE_USERNAME="your_username"

**Implementation Needed:**./build/starworld

```cpp```

class OverteAuth {

    // Add:## Configuration

    bool refreshAccessToken();  // Use refresh_token to get new access_token

    void saveTokensToDisk();    // Persist to ~/.config/starworld/tokens.json- **OVERTE_USERNAME**: Your Overte account username (optional; signature-based auth not yet implemented)

    void loadTokensFromDisk();  // Restore on startup- **OVERTE_UDP_PORT**: Domain server UDP port (default: 40104)

    bool isTokenExpired() const; // Check m_tokenExpiresAt- **STARWORLD_SIMULATE**: Set to "1" to enable simulation mode with demo entities

};

```## Troubleshooting



### 4. Including Token in Domain Requests### Protocol mismatch or denial



**Current State:** Token is obtained but NOT sent to domain server.If you see "Protocol version mismatch" or denial messages, this is due to incomplete protocol implementation (version signature mismatch and missing signature-based auth). Use the test environment instead:



**Required Changes:**```bash

# Works perfectly - bypasses domain server

In `src/OverteClient.cpp::sendDomainConnectRequest()`:python3 tools/inject_test_entities.py

```cpp```

// After line ~1160 (after username fields):

### Check Domain Server Status

// 16. Domain username (QString) - empty for now

qs.writeQString("");```bash

# Check if domain server is running

// 17. Domain access token (QString) - from metaverse OAuthps aux | grep domain-server

if (isAuthenticated() && m_auth) {

    qs.writeQString(m_auth->getAccessToken());# Check UDP port

} else {sudo ss -ulnp | grep domain-server

    qs.writeQString("");```

}

```### Test with Simulation Mode



**Domain Server Behavior:**```bash

When access token is present:STARWORLD_SIMULATE=1 ./build/starworld

1. Domain server validates token with metaverse API```

2. If valid, node is marked as authenticated

3. DomainList packet includes full assignment client topology## Protocol Implementation Status

4. User receives elevated permissions

✅ Domain UDP socket connection  

### 5. Alternative: Domain-Only Authentication✅ NLPacket protocol format (sequence numbers, headers)  

✅ Protocol signature discovery from metaverse API  

**Simpler Approach:** Some Overte domains support local authentication without metaverse.✅ DomainConnectRequest packet structure  

✅ DomainList request/response parsing  

**Implementation:**✅ **Handshake complete** - receiving DomainList with mixer endpoints  

```cpp✅ EntityServer endpoint discovery from DomainList  

// Domain-specific username/password (not metaverse account)⏳ EntityServer connection and EntityQuery packets  

// Send in DomainConnectRequest:⏳ Entity Add/Edit/Erase packet parsing  

qs.writeQString(domainUsername);  // Field 14⏳ Full property parsing (position, rotation, dimensions)  

qs.writeQString(domainPassword);  // Custom field or signature⏳ Octree-based spatial streaming  

⏳ Avatar mixer integration  

// Domain server checks local user database⏳ Audio mixer integration  

// No metaverse validation required❌ Signature-based authentication (optional for public servers)

```

## Recommendation

**Limitation:** Only works for domains configured with local auth. Most public domains require metaverse OAuth.

**Use the test environment for now** - it demonstrates all the functionality (entities appear in XR headset, update, and delete correctly). Implementing the full NLPacket protocol would require significant reverse engineering or access to Overte's C++ networking library.

## Implementation Priority


### Phase 1: Token Inclusion (High Priority)
Even without OAuth working, we can test token inclusion:
```cpp
// Hardcode a test token for development
std::string testToken = "test_token_12345";
qs.writeQString(testToken);
```

Watch domain server logs to see if it attempts validation.

### Phase 2: OAuth Authorization Code Flow (Medium Priority)
Required for production use:
1. Implement HTTP callback server
2. Implement browser launcher
3. Test with mv.overte.org
4. Handle error cases (user denies, timeout)

### Phase 3: Token Persistence (Low Priority)
Quality of life improvement:
1. Save tokens to disk
2. Auto-refresh on expiration
3. Keychain integration for security

## Testing Without Full OAuth

### Option 1: Steal Token from Overte Interface Client
Run official Overte interface, authenticate, then extract token from:
- Memory dump
- Network traffic (Wireshark)
- Config files (`~/.config/Overte/Interface.ini` or similar)

### Option 2: Use Local Domain with Disabled Auth
Configure your local domain server to skip authentication:
```json
// domain-server settings
{
  "security": {
    "restricted_access": false,
    "authentication_required": false
  }
}
```

### Option 3: Reverse Engineer Metaverse API
Capture actual OAuth flow from Overte interface:
```bash
# Run Overte interface with network logging
strace -e trace=network overte-interface 2>&1 | grep oauth

# Or use mitmproxy to intercept HTTPS
mitmproxy --mode transparent
```

## Code Locations

### Existing Implementation (Disabled)
- `src/OverteAuth.hpp` - OAuth client class
- `src/OverteAuth.cpp` - Password grant (incorrect, needs rewrite)
- `src/OverteClient.cpp:135-156` - OAuth login attempt (commented out)

### Required Changes
- `src/OverteAuth.cpp::login()` - Rewrite for authorization code flow
- `src/OverteClient.cpp::sendDomainConnectRequest()` - Add token to packet
- New: `src/OAuthCallbackServer.cpp` - HTTP server for callback
- New: `src/BrowserLauncher.cpp` - Cross-platform browser opener

## Overte Source Code References

### OAuth Implementation
```
overte/libraries/networking/src/AccountManager.cpp:
- requestAccessTokenWithAuthCode()  // Line ~586
- refreshAccessToken()              // Line ~655
- requestAccessToken()              // Line ~562 (password grant, deprecated)

overte/interface/src/Application_Setup.cpp:
- setupAccountManager()             // OAuth initialization
```

### Domain Connection with Token
```
overte/libraries/networking/src/NodeList.cpp:
- sendDomainConnectRequest()        // Includes access token

overte/domain-server/src/DomainServer.cpp:
- processNodeDataFromPacket()       // Validates token with metaverse
- isInInterestSet()                 // Line 1297, checks authentication
```

### Metaverse API Endpoints
```cpp
// From Overte source
const QString METAVERSE_URL = "https://mv.overte.org";
const QString OAUTH_AUTHORIZE = "/oauth/authorize";
const QString OAUTH_TOKEN = "/oauth/token";
const QString API_USER_PROFILE = "/api/v1/user/profile";
```

## Workaround: Manual Token Entry

For testing, add CLI option to manually input token:
```cpp
// src/main.cpp
const char* tokenEnv = std::getenv("OVERTE_TOKEN");
if (tokenEnv) {
    client.setAccessToken(tokenEnv);
}
```

Then:
```bash
# Get token from Overte interface somehow
export OVERTE_TOKEN="eyJ0eXAiOiJKV1QiLCJhbGc..."
./build/starworld
```

## Conclusion

**Minimum Viable OAuth:**
1. Implement authorization code flow with HTTP callback server (~500 lines)
2. Add token to DomainConnectRequest (2 lines)
3. Test with mv.overte.org

**Estimated Effort:** 8-16 hours for full implementation

**Alternative:** Wait for Overte to document/expose a simpler API auth method, or use local domain servers without metaverse authentication.

## References

### Overte OAuth Implementation
- **AccountManager Source**: https://github.com/overte-org/overte/blob/master/libraries/networking/src/AccountManager.cpp
- **OAuth Endpoints**: Lines 586-655 (requestAccessTokenWithAuthCode, refreshAccessToken)
- **NodeList Integration**: https://github.com/overte-org/overte/blob/master/libraries/networking/src/NodeList.cpp
- **Domain Server Validation**: https://github.com/overte-org/overte/blob/master/domain-server/src/DomainServer.cpp

### OAuth 2.0 Standards
- **RFC 6749**: https://www.rfc-editor.org/rfc/rfc6749.html - OAuth 2.0 Authorization Framework
- **RFC 7636**: https://www.rfc-editor.org/rfc/rfc7636.html - PKCE (Proof Key for Code Exchange)
- **Authorization Code Flow**: https://oauth.net/2/grant-types/authorization-code/

### Overte Metaverse API
- **Main Metaverse**: https://mv.overte.org
- **OAuth Authorization**: https://mv.overte.org/oauth/authorize
- **Token Endpoint**: https://mv.overte.org/oauth/token
- **User Profile API**: https://mv.overte.org/api/v1/user/profile

### Development Resources
- **Overte Discord**: https://discord.gg/overte - Ask about OAuth implementation
- **Overte Forums**: https://forums.overte.org - Technical discussions
- **Developer Docs**: https://docs.overte.org/developer - Official developer guides