refactor: Separate raw and state-based output modules with security fixes

- Fix port collision: Change AVR default port from 30003 to 30001
- Introduce OutputModuleBase, RawOutputModule, and StateOutputModule traits
- Separate broadcast pipelines for raw packets vs aircraft state
- BREAKING: WebSocket now streams SBS-1 CSV format instead of BEAST binary
- Replace unsafe unwrap() calls with expect() and if-let patterns in tracker
- Update documentation with WebSocket format change and security model
- Document WebSocket as local-only with no authentication/encryption

This refactoring enables clean separation between pass-through protocols
(BEAST, Raw, AVR) and stateful protocols (SBS-1, WebSocket) that require
accumulated aircraft data.

Author: ccustine

CLAUDE.md

@@ -160,14 +160,14 @@ AirJedi supports multiple output formats for compatibility with various ADS-B to
 - **Protocol**: `*{hexdata};\n` format
 - **Compatibility**: dump1090 port 30002, simple monitoring tools
 
-### AVR Format (Port 30003)
+### AVR Format (Port 30001)
 - **Default**: Disabled by default
 - **Description**: Text format with timestamps and signal levels
 - **Usage**: `--avr`, `--avr-port <PORT>`
 - **Protocol**: `@{timestamp}\n*{hexdata};\n` format
 - **Compatibility**: dump1090 AVR format, debugging tools
 
-### SBS-1/BaseStation Format (Port 30004)
+### SBS-1/BaseStation Format (Port 30003)
 - **Default**: Disabled by default
 - **Description**: CSV format compatible with BaseStation and SBS-1 receivers
 - **Usage**: `--sbs1`, `--sbs1-port <PORT>`
@@ -179,12 +179,13 @@ AirJedi supports multiple output formats for compatibility with various ADS-B to
 
 ### WebSocket Format (Port 8080)
 - **Default**: Disabled by default
-- **Description**: Real-time WebSocket streaming with BEAST format messages
+- **Description**: Real-time WebSocket streaming with SBS-1 CSV format messages
 - **Usage**: `--websocket`, `--websocket-port <PORT>`
-- **Protocol**: Binary WebSocket messages containing BEAST-encoded ADS-B data
+- **Protocol**: Text WebSocket messages containing SBS-1/BaseStation CSV data
 - **Compatibility**: Web browsers, JavaScript applications, real-time web dashboards
-- **Message Format**: Each WebSocket message contains a complete BEAST-format packet
+- **Message Format**: Each WebSocket message contains SBS-1 CSV formatted aircraft data (MSG,1/2/3/4)
 - **Use Cases**: Real-time web applications, live flight tracking interfaces, custom dashboards
+- **Note**: WebSocket broadcasts state-based updates (identification, position, velocity) rather than raw packets
 
 ## Example Usage
 
@@ -196,7 +197,7 @@ cargo run
 cargo run -- --avr --sbs1 --websocket
 
 # Custom ports to avoid conflicts
-cargo run -- --beast-port 40005 --raw-port 40002 --sbs1-port 40004 --websocket-port 9090
+cargo run -- --beast-port 40005 --raw-port 40002 --sbs1-port 40003 --websocket-port 9090
 
 # Enable only WebSocket output for web applications
 cargo run -- --no-beast --no-raw --websocket
@@ -213,23 +214,41 @@ For web applications connecting to the WebSocket output:
 // Connect to AirJedi WebSocket server
 const ws = new WebSocket('ws://localhost:8080');
 
-// Handle binary BEAST messages
+// Handle SBS-1 CSV text messages
 ws.onmessage = function(event) {
-    // event.data is an ArrayBuffer containing BEAST format data
-    const data = new Uint8Array(event.data);
-    
-    // BEAST format: [0x1A, type, timestamp(6), signal, payload...]
-    if (data[0] === 0x1A) {  // BEAST escape character
-        const messageType = data[1];  // 0x31=short, 0x32=long
-        const timestamp = data.slice(2, 8);  // 6 bytes
-        const signal = data[8];  // Signal strength
-        const payload = data.slice(9);  // ADS-B message
-        
-        console.log('ADS-B Message:', {
-            type: messageType === 0x31 ? 'short' : 'long',
-            signal: signal,
-            data: Array.from(payload).map(b => b.toString(16).padStart(2, '0')).join('')
-        });
+    // event.data is a string containing SBS-1 CSV format data
+    const csvData = event.data;
+    const fields = csvData.split(',');
+
+    // SBS-1 format: MSG,type,session,aircraft,icao,flight,date_gen,time_gen,date_log,time_log,...
+    if (fields[0] === 'MSG') {
+        const messageType = parseInt(fields[1]);
+        const icao = fields[4];
+
+        switch (messageType) {
+            case 1:  // Identification (callsign)
+                console.log('Aircraft Identification:', {
+                    icao: icao,
+                    callsign: fields[10]
+                });
+                break;
+            case 3:  // Airborne Position
+                console.log('Aircraft Position:', {
+                    icao: icao,
+                    altitude: fields[11],
+                    latitude: fields[14],
+                    longitude: fields[15]
+                });
+                break;
+            case 4:  // Airborne Velocity
+                console.log('Aircraft Velocity:', {
+                    icao: icao,
+                    groundSpeed: fields[12],
+                    track: fields[13],
+                    verticalRate: fields[16]
+                });
+                break;
+        }
     }
 };
 
@@ -240,4 +259,38 @@ ws.onopen = function() {
 ws.onerror = function(error) {
     console.error('WebSocket error:', error);
 };
-```
+```
+
+## WebSocket Security Model
+
+**IMPORTANT**: The WebSocket server is designed for **local-only use** and has minimal security controls:
+
+### Security Characteristics
+
+- **No Authentication**: Any client that can reach the port can connect and receive data
+- **No Authorization**: All connected clients receive all aircraft data
+- **No Origin Validation**: No CORS checks - any website can connect via JavaScript
+- **No TLS/Encryption**: Plain TCP WebSocket (ws://) without encryption (wss:// not supported)
+- **No Rate Limiting**: Clients can connect and consume data without throttling
+- **Public Data**: ADS-B data is inherently public information broadcast by aircraft
+
+### Recommended Deployment
+
+1. **Bind to localhost only** (default: 127.0.0.1:8080) - prevents external access
+2. **Use firewall rules** to restrict access if binding to non-localhost interfaces
+3. **Deploy behind reverse proxy** if internet access is needed (add authentication/TLS there)
+4. **Monitor connections** via client_count metrics to detect unexpected clients
+
+### Acceptable Use Cases
+
+- ✅ Local development and testing
+- ✅ Single-user desktop applications
+- ✅ Trusted local network deployments
+- ✅ Behind authenticated reverse proxy (nginx, Apache with auth)
+
+### Unsuitable Use Cases
+
+- ❌ Direct internet exposure without additional security layers
+- ❌ Multi-tenant environments without isolation
+- ❌ Scenarios requiring data access auditing
+- ❌ Compliance-regulated environments without additional controls

Cargo.toml

@@ -13,7 +13,7 @@ authors = ["ccustine"]
 
 [[bin]]
 name = "airjedi"
-path = "src/bin/listen_adsb.rs"
+path = "src/bin/airjedi.rs"
 
 [features]
 default = ["soapy"]

src/avr_output.rs

@@ -5,6 +5,7 @@
 //! output with timestamps and signal levels for debugging and integration.
 
 use crate::decoder::DecoderMetaData;
+use crate::output_module::{OutputModuleBase, RawOutputModule};
 use anyhow::Result;
 use std::time::UNIX_EPOCH;
 use tokio::io::AsyncWriteExt;
@@ -191,24 +192,20 @@ impl AvrOutput {
     }
 }
 
-#[async_trait::async_trait]
-impl crate::output_module::OutputModule for AvrOutput {
+// Implement the base trait for common functionality
+impl crate::output_module::OutputModuleBase for AvrOutput {
     fn name(&self) -> &str {
         &self.name
     }
 
     fn description(&self) -> &str {
-        "AVR text format with timestamps for dump1090 compatibility (port 30003)"
+        "AVR text format with timestamps for dump1090 compatibility (port 30001)"
     }
 
     fn port(&self) -> u16 {
         self.port
     }
 
-    fn broadcast_packet(&self, data: &[u8], metadata: &DecoderMetaData) -> Result<()> {
-        self.broadcaster.broadcast_packet(data, metadata)
-    }
-
     fn client_count(&self) -> usize {
         self.broadcaster.client_count()
     }
@@ -223,6 +220,46 @@ impl crate::output_module::OutputModule for AvrOutput {
     }
 }
 
+// Implement the raw output trait for broadcasting raw packets
+#[async_trait::async_trait]
+impl crate::output_module::RawOutputModule for AvrOutput {
+    fn broadcast_raw_packet(&self, data: &[u8], metadata: &DecoderMetaData) -> Result<()> {
+        self.broadcaster.broadcast_packet(data, metadata)
+    }
+}
+
+// Keep legacy trait implementation for backward compatibility during migration
+#[async_trait::async_trait]
+impl crate::output_module::OutputModule for AvrOutput {
+    fn name(&self) -> &str {
+        OutputModuleBase::name(self)
+    }
+
+    fn description(&self) -> &str {
+        OutputModuleBase::description(self)
+    }
+
+    fn port(&self) -> u16 {
+        OutputModuleBase::port(self)
+    }
+
+    fn broadcast_packet(&self, data: &[u8], metadata: &DecoderMetaData) -> Result<()> {
+        self.broadcast_raw_packet(data, metadata)
+    }
+
+    fn client_count(&self) -> usize {
+        OutputModuleBase::client_count(self)
+    }
+
+    fn is_running(&self) -> bool {
+        OutputModuleBase::is_running(self)
+    }
+
+    fn stop(&mut self) -> Result<()> {
+        OutputModuleBase::stop(self)
+    }
+}
+
 // Builder implementation removed - using direct instantiation in main
 
 #[cfg(test)]

src/beast_output.rs

@@ -5,6 +5,7 @@
 //! existing ADS-B tools like tar1090, FlightAware feeders, and other aggregators.
 
 use crate::decoder::DecoderMetaData;
+use crate::output_module::{OutputModuleBase, RawOutputModule};
 use anyhow::Result;
 use std::time::UNIX_EPOCH;
 use tokio::io::AsyncWriteExt;
@@ -229,8 +230,8 @@ impl BeastOutput {
     }
 }
 
-#[async_trait::async_trait]
-impl crate::output_module::OutputModule for BeastOutput {
+// Implement the base trait for common functionality
+impl crate::output_module::OutputModuleBase for BeastOutput {
     fn name(&self) -> &str {
         &self.name
     }
@@ -243,10 +244,6 @@ impl crate::output_module::OutputModule for BeastOutput {
         self.port
     }
 
-    fn broadcast_packet(&self, data: &[u8], metadata: &DecoderMetaData) -> Result<()> {
-        self.broadcaster.broadcast_packet(data, metadata)
-    }
-
     fn client_count(&self) -> usize {
         self.broadcaster.client_count()
     }
@@ -261,6 +258,46 @@ impl crate::output_module::OutputModule for BeastOutput {
     }
 }
 
+// Implement the raw output trait for broadcasting raw packets
+#[async_trait::async_trait]
+impl crate::output_module::RawOutputModule for BeastOutput {
+    fn broadcast_raw_packet(&self, data: &[u8], metadata: &DecoderMetaData) -> Result<()> {
+        self.broadcaster.broadcast_packet(data, metadata)
+    }
+}
+
+// Keep legacy trait implementation for backward compatibility during migration
+#[async_trait::async_trait]
+impl crate::output_module::OutputModule for BeastOutput {
+    fn name(&self) -> &str {
+        OutputModuleBase::name(self)
+    }
+
+    fn description(&self) -> &str {
+        OutputModuleBase::description(self)
+    }
+
+    fn port(&self) -> u16 {
+        OutputModuleBase::port(self)
+    }
+
+    fn broadcast_packet(&self, data: &[u8], metadata: &DecoderMetaData) -> Result<()> {
+        self.broadcast_raw_packet(data, metadata)
+    }
+
+    fn client_count(&self) -> usize {
+        OutputModuleBase::client_count(self)
+    }
+
+    fn is_running(&self) -> bool {
+        OutputModuleBase::is_running(self)
+    }
+
+    fn stop(&mut self) -> Result<()> {
+        OutputModuleBase::stop(self)
+    }
+}
+
 // Builder implementation removed - using direct instantiation in main
 
 #[cfg(test)]