IRC-kosmi-relay/cmd/monitor-auth/README.md

# 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