Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 65 additions & 0 deletions docs/tcp-proxy-ip-address.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# TCP Connection IP Address Handling

## Current State

Device IP addresses shown in telemetry often display as `::1` (localhost IPv6) because traffic arrives via a local reverse proxy or tunnel before reaching SmartLayerProxy.

## HTTP API Routes: X-Forwarded-For Support

For HTTP routes, the proxy can now honor standard forwarding headers when configured:

- Set environment variable `TRUST_PROXY=true` (or `trust.proxy=true` in application.properties)
- SmartLayerProxy will extract the real client IP from:
- `X-Forwarded-For` header (takes first IP from comma-separated list)
- `CF-Connecting-IP` header (Cloudflare)

**Example:**
```bash
export TRUST_PROXY=true
```

This applies to all HTTP-based device API routes:
- `GET /api/getEthAddress`
- `GET /api/:Address/:method`
- `GET /api/async/:Address/:method`
- `GET /api/bridge/:Address/:data`
- `GET /api/bridge/login`

## TCP Socket Connections: PROXY Protocol

For raw TCP connections (port 8082), the current implementation cannot read IP forwarding information because:

1. TCP sockets don't have HTTP headers
2. The socket's `remoteAddress` reflects the immediate peer (the reverse proxy/tunnel)

### Potential Solution: PROXY Protocol

The **PROXY protocol** (v1 or v2) prepends connection metadata (real client IP, port) to the TCP stream before application data. This is supported by:

- HAProxy
- nginx (with `proxy_protocol` directive)
- AWS ELB/NLB
- Cloudflare Spectrum

**Implementation would require:**

1. Detecting and parsing PROXY protocol header on new TCP connections
2. Extracting the real client IP before processing authentication opcodes
3. Stripping the PROXY header from the data stream

**Example PROXY v1 header:**
```
PROXY TCP4 192.168.1.100 10.0.0.1 50123 8082\r\n
```

This feature is **not implemented** in the current release. TCP connections will continue to show the tunnel/proxy IP address until PROXY protocol support is added.

### Workarounds

- For development/testing: disable the tunnel and connect directly
- For production: accept that TCP telemetry shows proxy IPs, or implement PROXY protocol support

## References

- [PROXY protocol specification](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)
- [nginx proxy_protocol](https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol/)
93 changes: 93 additions & 0 deletions docs/unknown-opcode-behavior.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Unknown Opcode Handling in ASyncTCPService

## Current Master Behavior (Pre-PR)

The current deployed `master` branch's `ASyncTCPService.parseClientMessage()` uses a `switch` statement **without a default case**:

```typescript
switch (opcode) {
case 0x01: // login
case 0x02: // challenge
case 0x03: // auth with personal sign
case 0x07: // auth without personal sign
case 0x04: // return values
case 0x05: // API response
case 0x08: // HTTP bridge response
// ... handlers ...
}
// No default case - falls through silently
```

### Impact on Unknown Opcodes

When master receives an **unknown opcode** (e.g., 0x09 or 0x0A from new firmware):

1. ✅ **Connection stays open** - No termination
2. ✅ **Stream framing intact** - TCP buffer read as single message (see below)
3. ✅ **Silent ignore** - Message logged but not processed
4. ✅ **Device can continue** - Subsequent known opcodes work normally

### TCP Framing Robustness

The `TCPClient` implementation in master is **robust to partial and combined frames**:

```typescript
socket.on('data', (data: Buffer) => {
buffer = Buffer.concat([buffer, data]);
// ... length checks ...
this.serverCallback.receivedMessage(this.clientIndex, buffer);
buffer = Buffer.alloc(0); // Reset after processing
});
```

**Key characteristics:**
- Each TCP `data` event accumulates into a buffer
- The entire buffer (up to `MAX_TCP_PACKET = 4096` bytes) is passed as one message
- Buffer resets after `receivedMessage()` completes
- **No length-based framing** - each TCP read is one opcode message

### Backward Compatibility Conclusion

✅ **New firmware (0x09, 0x0A) is safe with old master servers:**

- 0x09 auth with version: Ignored, but firmware should fall back to 0x07
- 0x0A diagnostics: Silently ignored, connection remains open

**However:** Since master doesn't implement 0x09, **firmware MUST send 0x07 as fallback** if the server doesn't respond to 0x09, or use 0x07 exclusively until this PR is deployed.

## This PR's Changes

### Opcode 0x09 - Auth with Firmware Version
- **Format:** `[addr20][sig65][versionLen1 (0-32)][ASCII version]`
- **Signature over:** `keccak256(challenge || versionLen || version)`
- **Behavior:** Validates and stores firmware version; falls back gracefully if malformed

### Opcode 0x0A - WiFi Diagnostics
- **Format:** 14 bytes, big-endian:
- `[0]` = 0x0A
- `[1]` = resetReason (esp_reset_reason_t)
- `[2-3]` = bootCount uint16
- `[4-5]` = wifiAttempts uint16
- `[6-9]` = connectTimeMs uint32
- `[10]` = networkIndex
- `[11]` = lastFailureStage (0-6)
- `[12]` = lastDisconnectReason (wifi_err_reason_t)
- `[13]` = reserved
- **Behavior:**
- Only accepted from authenticated devices
- Decodes ESP reset reasons and WiFi error codes to names
- Stores in `device_diagnostics` table for analysis
- Silently ignores if unauthenticated or malformed

### Unknown Opcode Handling
- **No default case added** - maintains backward compatibility
- Unknown opcodes still fall through silently
- Future opcodes can be added without breaking old clients

## Deployment Strategy

1. **Deploy this PR first** (proxy supports 0x09, 0x0A)
2. **Then deploy Web3E firmware** (sends 0x09, 0x0A)
3. **Fallback safe:** New firmware + old proxy = firmware uses 0x07, no diagnostics

**Migration window:** Once this PR deploys, new firmware can start sending 0x09/0x0A immediately. Old firmware continues working indefinitely with 0x07.
Loading
Loading