IRC-kosmi-relay/AUTHENTICATION_STATUS.md

Kosmi Authentication Status

Current Status: ✅ Fully Automated

Authentication for the Kosmi bridge is fully automated using browser-based email/password login with automatic token refresh.

Quick Start

Option 1: Email/Password (Recommended - Fully Automated)

1. Configure credentials in matterbridge.toml:

   [kosmi.hyperspaceout]
   RoomURL="https://app.kosmi.io/room/@hyperspaceout"
   Email="your-email@example.com"
   Password="your-password"
   

2. Run the bot: ./irc-kosmi-relay -conf matterbridge.toml

The bot will automatically:

• Launch headless Chrome
• Log in to Kosmi
• Extract and use the JWT token
• Refresh the token automatically (checked daily)

See BROWSER_AUTH_GUIDE.md for detailed instructions.

Option 2: Manual Token (Alternative)

If you prefer not to provide credentials:

1. Log in to Kosmi in your browser
2. Extract your token:
   • Open DevTools (F12) → Console tab
   • Run: localStorage.getItem('token')
   • Copy the token (without quotes)
3. Add to config:

   [kosmi.hyperspaceout]
   RoomURL="https://app.kosmi.io/room/@hyperspaceout"
   Token="your-token-here"
   

4. Run the bot: ./irc-kosmi-relay -conf matterbridge.toml

See QUICK_START_TOKEN.md for detailed instructions.

Authentication Methods

✅ Email/Password (RECOMMENDED)

• Status: Working - Fully Automated
• Setup: Provide email and password in config
• Pros: Fully automated, auto-refresh, no manual intervention
• Cons: Requires Chrome/Chromium, credentials in config file
• Use Case: Production use
• Details: See BROWSER_AUTH_GUIDE.md

✅ Manual Token (Alternative)

• Status: Working
• Setup: Extract token from browser localStorage
• Pros: Simple, no browser required, no credentials in config
• Cons: Manual process, token expires after ~1 year
• Use Case: When Chrome is not available or preferred
• Details: See QUICK_START_TOKEN.md

✅ Anonymous Login

• Status: Working
• Setup: Leave both Email and Token fields empty
• Pros: No configuration needed
• Cons: Limited permissions, can't access private rooms
• Use Case: Testing, public rooms

Technical Details

How It Works

1. User provides JWT token in configuration
2. Bot uses token directly for WebSocket authentication
3. Token is sent in connection_init payload
4. Kosmi validates token and establishes authenticated session

Token Format

• Algorithm: HS512
• Expiry: ~1 year from issue
• Storage: Browser localStorage with key "token"
• Format: Standard JWT (header.payload.signature)

Token Payload Example

{
  "aud": "kosmi",
  "exp": 1793465205,
  "iat": 1762015605,
  "iss": "kosmi",
  "jti": "1c7f9db8-9a65-4909-92c0-1c646103bdee",
  "nbf": 1762015604,
  "sub": "4ec0b428-712b-49d6-8551-224295 45d29b",
  "typ": "access"
}

Troubleshooting

Bot connects anonymously instead of using token

• Check token is correctly copied (no quotes, no extra spaces)
• Verify Token="" line is not commented out
• Check logs for "Using provided authentication token"

Connection fails with token

• Token may be expired - extract a new one
• Verify you're logged in to correct Kosmi account
• Check token format is valid JWT

How to check token expiry

# Decode token at https://jwt.io
# Or use command line:
echo "your-token" | cut -d'.' -f2 | base64 -d | jq .exp | xargs -I {} date -r {}

Implementation Files

Core Implementation

• bridge/kosmi/graphql_ws_client.go - WebSocket client with token support
• bridge/kosmi/kosmi.go - Bridge integration and config handling
• bridge/kosmi/auth.go - Auth manager (for future email/password support)

Configuration

• matterbridge.toml - Main config with Token field
• test-token-config.toml - Example test configuration

Documentation

• QUICK_START_TOKEN.md - User guide for manual token setup
• AUTH_DISCOVERY.md - Technical investigation details
• chat-summaries/auth-discovery-2025-11-01-16-48.md - Session summary

Testing Tools

• cmd/test-introspection/main.go - GraphQL schema introspection
• cmd/test-login/main.go - Test login mutations
• cmd/monitor-auth/main.go - Browser automation for traffic capture

Future Enhancements

Possible Improvements

1. Automatic Token Extraction: Browser automation to extract token
2. Token Refresh: Implement if refresh mechanism is discovered
3. Email/Password: Deep reverse engineering of Kosmi's auth
4. Token Expiry Warning: Alert user when token is about to expire

Priority

• Low: Current solution works well for most use cases
• Revisit: If Kosmi adds official bot API or auth documentation

Security Considerations

Token Storage

• Tokens are stored in plain text in matterbridge.toml
• Ensure config file has appropriate permissions (chmod 600)
• Do not commit config with real tokens to version control

Token Sharing

• Each token is tied to a specific user account
• Do not share tokens between users
• Revoke token by logging out in browser if compromised

Best Practices

1. Use dedicated bot account for token
2. Limit bot account permissions in Kosmi
3. Rotate tokens periodically (even though they last 1 year)
4. Monitor bot activity for unusual behavior

Support

Getting Help

1. Check QUICK_START_TOKEN.md for setup instructions
2. Review AUTH_DISCOVERY.md for technical details
3. Check logs for error messages
4. Verify token is valid and not expired

Reporting Issues

If you encounter problems:

1. Check token expiry
2. Verify configuration format
3. Review bot logs for errors
4. Try extracting a fresh token

Conclusion

Manual token provision provides a reliable and simple authentication method for the Kosmi bridge. While not as automated as email/password would be, it:

• Works immediately
• Requires minimal maintenance (tokens last ~1 year)
• Has no external dependencies
• Is easy to troubleshoot

For most users, this is the recommended authentication method.