Alta-Proxy-Tool/README.md

# Alta Video Camera Proxy

An Electron desktop application for managing Alta Video camera proxy connections. Authenticates via a companion Chrome extension that imports your existing Alta session cookie, discovers cameras, and launches proxy connections.

## Features

- **Chrome Extension Authentication**: Import your Alta session cookie from Chrome with one click — no manual login
- **API Integration**: Device discovery via Alta Video API using cookie auth
- **Camera Proxy Management**: Launch and manage camera proxy connections
- **Device Filtering**: Automatically filters to show only local (non-cloud) cameras
- **Device Search**: Quick search functionality to find cameras by name, ID, IP, or model
- **Real-time Status**: Live connection status and device online/offline indicators
- **Auto-Update**: Checks for updates on startup via GitHub Releases, with one-click in-place update
- **Modern Dark UI**: Professional dark-mode interface with responsive design

## Prerequisites

- **Node.js** (version 14 or higher)
- **npm** (comes with Node.js)
- **Google Chrome** (for the authentication extension)
- **Windows OS** (required for camera proxy executable)
- **aware-cam-proxy.exe** (camera proxy executable) — must be placed in the application directory
- **An active Alta Video session** in Chrome (logged in to your deployment)

## Installation

1. Clone or download this project
2. Install dependencies:
   ```bash
   npm install
   ```
3. Place `aware-cam-proxy.exe` in the project root directory

### Chrome Extension Setup

1. Open Chrome and navigate to `chrome://extensions/`
2. Enable **Developer mode** (toggle in top-right)
3. Click **Load unpacked**
4. Select the `chrome-extension/` folder from this project
5. The extension icon will appear in the Chrome toolbar

## Usage

### Starting the Application

```bash
npm start
```

Or for development mode with DevTools:
```bash
npm run dev
```

### Connecting to Alta

1. **Log into your Alta deployment** in Chrome (e.g., `https://your-site.eu1.aware.avasecurity.com`)
2. **Click the extension icon** in Chrome — it will detect the Alta tab
3. **Click "Send Cookie to APT"** — the app will connect and load devices automatically

### Launching Camera Proxy

1. **Connect via Chrome extension** (above)
2. **Select a device** from the left sidebar
3. **Click "Start Camera Proxy"**
4. A command prompt window will open with the proxy connection

### Updating

The app checks for updates automatically 2 seconds after launch. If a newer version is available on GitHub Releases, the "Check for Updates" button in the header will show a green badge.

- **Manual check**: Click "Check for Updates" in the top-right corner
- **Install**: The update modal shows release notes — click "Install Update" to download and replace the current executable
- The app will quit, swap the `.exe`, and relaunch automatically

## API Endpoints Used

- **Device List**: `GET /api/v1/devices` — Retrieve all devices
- **Auth Info**: `GET /api/v1/auth` — Verify authentication status

## How It Works

```
Chrome Extension (popup click)
  → POST http://127.0.0.1:18247/cookie
  → Electron app HTTP server receives cookie
  → Sets session state, fetches devices
  → User selects device → launches aware-cam-proxy.exe
```

The Electron app runs a local HTTP server on port 18247 that only accepts requests from Chrome extensions with a shared token. The Chrome extension reads the `va` session cookie from the active Alta tab and sends it to the app.

## Security

- **Context Isolation**: Renderer process is isolated from Node.js APIs
- **Preload Script**: Secure IPC communication between main and renderer processes
- **CSP Enforced**: `script-src 'self'` — no inline scripts allowed
- **Localhost Only**: Cookie server binds to `127.0.0.1`, not accessible from network
- **CORS Restricted**: Only `chrome-extension://` origins accepted
- **Domain Validation**: Only `*.avasecurity.com` and `*.avigilon.com` URLs accepted
- **Input Sanitization**: Batch file inputs sanitized to prevent command injection
- **Size Limits**: 64KB body limit on cookie server, type/length validation on all inputs

## File Structure

```
├── main.js              # Main process (IPC, API calls, proxy spawning, cookie server)
├── renderer.js          # Renderer process (UI logic, state management)
├── preload.js           # Secure IPC bridge (contextBridge)
├── index.html           # Static HTML shell (CSP enforced)
├── styles.css           # Dark theme styling
├── package.json         # Dependencies and build config
├── chrome-extension/    # Chrome extension for cookie import
│   ├── manifest.json    # Manifest V3
│   ├── popup.html       # Extension popup UI
│   ├── popup.css        # Dark theme styling
│   ├── popup.js         # Tab detection, cookie retrieval
│   └── icon*.png        # Extension icons
├── assets/
│   └── icon.png         # Application icon
├── CLAUDE.md            # Claude Code project instructions
└── README.md            # This file
```

**External executable** (not included in repo):
- `aware-cam-proxy.exe` — cookie-based auth proxy (required, place in app root)

## Troubleshooting

### Connection Issues
- Ensure you are **logged into Alta in Chrome** before clicking the extension
- Verify the extension shows "Detected: [hostname]" in green
- If extension shows "Alta Proxy Tool is not running" — start the Electron app first
- If "Session cookie has expired" — log into Alta again in Chrome
- Check that the app console shows "Cookie server listening on http://127.0.0.1:18247"

### Camera Proxy Issues
- **Executable not found**: Ensure `aware-cam-proxy.exe` is in the application directory
- **Proxy won't start**: Check that you're connected and have selected a device
- **Command window closes immediately**: Check network connectivity to the deployment

### Device List Issues
- Ensure you're connected via the Chrome extension first
- Check that your user account has permissions to view devices
- **No devices shown**: You may only have cloud cameras which are filtered out
- Use the search box to find specific devices

## Building for Distribution

```bash
# Build portable Windows executable
npm run build

# Output: dist/AltaCameraProxy-1.0.0-portable.exe
```

**Important**: Copy `aware-cam-proxy.exe` to the same directory as the built executable before distribution.

## Limitations

- **Windows Only**: Camera proxy executable is Windows-specific
- **Chrome Required**: Authentication requires the Chrome extension
- **Local Cameras Only**: Automatically filters out cloud-based cameras
- **No Session Refresh**: Sessions may expire and require re-import from Chrome
- **Executable Required**: `aware-cam-proxy.exe` must be obtained separately
- **Update Requires Write Access**: Self-update needs write permission to the directory containing the `.exe`

## Development

To modify or extend this application:

1. **Main Process** ([main.js](main.js)): App lifecycle, API requests, proxy spawning, cookie server
2. **Renderer Process** ([renderer.js](renderer.js)): UI interactions and state management
3. **Preload Script** ([preload.js](preload.js)): Secure IPC bridge with context isolation
4. **Chrome Extension** ([chrome-extension/](chrome-extension/)): Cookie import from browser
5. **Styling** ([styles.css](styles.css)): Dark mode theme and responsive design

### Adding New IPC Endpoints

1. Add handler in [main.js](main.js) using `ipcMain.handle()`
2. Expose method in [preload.js](preload.js) via `contextBridge.exposeInMainWorld()`
3. Call from [renderer.js](renderer.js) using `window.electronAPI.yourMethod()`

## License

MIT License - Feel free to modify and distribute as needed.