sync

cmd/monitor-auth/README.md

@@ -0,0 +1,244 @@
+# Kosmi Auth & Reconnection Monitor
+
+A comprehensive WebSocket monitoring tool for reverse engineering Kosmi's authentication and reconnection behavior.
+
+## Features
+
+- 📡 Captures all WebSocket traffic (send/receive)
+- 🔐 Monitors authentication flows (login, token acquisition)
+- 🔄 Tests reconnection behavior
+- 💾 Captures localStorage, sessionStorage, and cookies
+- 📝 Logs to both console and file
+- 🌐 Monitors HTTP requests/responses
+
+## Building
+
+```bash
+cd /Users/erikfredericks/dev-ai/HSO/irc-kosmi-relay
+go build -o bin/monitor-auth ./cmd/monitor-auth
+```
+
+## Usage
+
+### 1. Monitor Anonymous Connection (Default)
+
+Captures the anonymous token acquisition and WebSocket connection:
+
+```bash
+./bin/monitor-auth -room "https://app.kosmi.io/room/@hyperspaceout"
+```
+
+**What it captures:**
+- Anonymous token request/response
+- WebSocket connection handshake
+- Message subscription
+- Room join
+- Incoming messages
+
+### 2. Monitor Login Flow
+
+Captures the full authentication flow when logging in:
+
+```bash
+./bin/monitor-auth -login
+```
+
+**What to do:**
+1. Script opens browser to Kosmi
+2. Manually log in with your credentials
+3. Navigate to a room
+4. Script captures all auth traffic
+
+**What it captures:**
+- Login form submission
+- Token response
+- Token storage (localStorage/cookies)
+- Authenticated WebSocket connection
+- User information
+
+### 3. Test Reconnection Behavior
+
+Simulates network disconnection and observes reconnection:
+
+```bash
+./bin/monitor-auth -reconnect
+```
+
+**What it does:**
+1. Connects to Kosmi
+2. Simulates network offline for 10 seconds
+3. Restores network
+4. Observes reconnection behavior
+
+**What it captures:**
+- Disconnection events
+- Reconnection attempts
+- Token refresh (if any)
+- Re-subscription
+
+## Output
+
+All captured data is written to:
+- **Console**: Real-time output with emojis for easy reading
+- **File**: `auth-monitor.log` in current directory
+
+### Log Format
+
+```
+HH:MM:SS.mmm [TYPE] Message
+```
+
+Examples:
+```
+11:45:23.123 🌐 [HTTP REQUEST] POST https://engine.kosmi.io/
+11:45:23.456 📨 [HTTP RESPONSE] 200 https://engine.kosmi.io/
+11:45:23.789 🔌 [WS MONITOR] WebSocket created: wss://engine.kosmi.io/gql-ws
+11:45:24.012 📤 [WS MONITOR] SEND #1: {"type":"connection_init",...}
+11:45:24.234 📥 [WS MONITOR] RECEIVE #1: {"type":"connection_ack"}
+```
+
+## Analyzing Captured Data
+
+### Finding Authentication API
+
+Look for POST requests to `https://engine.kosmi.io/`:
+
+```bash
+grep "POST.*engine.kosmi.io" auth-monitor.log
+grep "Response Body" auth-monitor.log | grep -A 10 "login"
+```
+
+### Finding Token Storage
+
+Look for localStorage/sessionStorage writes:
+
+```bash
+grep "localStorage" auth-monitor.log
+grep "token" auth-monitor.log
+```
+
+### Finding Reconnection Logic
+
+Look for WebSocket CLOSED/OPENED events:
+
+```bash
+grep "WebSocket CLOSED" auth-monitor.log
+grep "WebSocket OPENED" auth-monitor.log
+```
+
+## Common Patterns to Look For
+
+### 1. Login Mutation
+
+```graphql
+mutation Login($email: String!, $password: String!) {
+  login(email: $email, password: $password) {
+    token
+    refreshToken
+    expiresIn
+    user {
+      id
+      displayName
+      username
+    }
+  }
+}
+```
+
+### 2. Token Refresh Mutation
+
+```graphql
+mutation RefreshToken($refreshToken: String!) {
+  refreshToken(refreshToken: $refreshToken) {
+    token
+    refreshToken
+    expiresIn
+  }
+}
+```
+
+### 3. Typing Indicators
+
+```graphql
+mutation SetTyping($roomId: String!, $isTyping: Boolean!) {
+  setTyping(roomId: $roomId, isTyping: $isTyping) {
+    ok
+  }
+}
+
+subscription OnUserTyping($roomId: String!) {
+  userTyping(roomId: $roomId) {
+    user {
+      id
+      displayName
+    }
+    isTyping
+  }
+}
+```
+
+## Troubleshooting
+
+### Script won't stop with Ctrl+C
+
+**Fixed in latest version**. Rebuild if you have an old version:
+```bash
+go build -o bin/monitor-auth ./cmd/monitor-auth
+```
+
+If still stuck, you can force quit:
+```bash
+# In another terminal
+pkill -f monitor-auth
+```
+
+### Browser doesn't open
+
+Make sure Playwright is installed:
+```bash
+go run github.com/playwright-community/playwright-go/cmd/playwright@latest install
+```
+
+### No WebSocket traffic captured
+
+The monitoring script injects BEFORE page load. If you see "WebSocket hook active" in the console, it's working. If not, try:
+1. Refresh the page
+2. Check browser console for errors
+3. Ensure you're on a Kosmi room page
+
+### Log file is empty
+
+Check that you have write permissions in the current directory:
+```bash
+touch auth-monitor.log
+ls -l auth-monitor.log
+```
+
+## Tips
+
+1. **Use with real credentials**: The monitoring script is safe - it runs locally and doesn't send data anywhere. Use real credentials to capture actual auth flows.
+
+2. **Compare anonymous vs authenticated**: Run twice - once without `-login` and once with - to see the differences.
+
+3. **Watch the browser**: Keep an eye on the browser window to see what triggers each WebSocket message.
+
+4. **Search the log file**: Use `grep`, `jq`, or text editor to analyze the captured data.
+
+5. **Test edge cases**: Try invalid credentials, expired tokens, network failures, etc.
+
+## Next Steps
+
+After capturing auth data:
+
+1. Review `auth-monitor.log`
+2. Identify actual GraphQL mutation formats
+3. Update `bridge/kosmi/auth.go` if needed
+4. Test with real credentials in production
+5. Verify token refresh works correctly
+
+## See Also
+
+- `TYPING_INDICATORS.md` - Guide for implementing typing indicators
+- `IMPLEMENTATION_SUMMARY.md` - Overall project documentation
+- `chat-summaries/2025-11-01_*_reconnection-and-auth-implementation.md` - Implementation details
+