Initial commit — Alta Proxy Tool (APT)

Electron desktop app for Avigilon Alta Video camera proxy management. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-09 20:28:32 -05:00
commit e813607f63
11 changed files with 9117 additions and 0 deletions
@@ -0,0 +1,187 @@
+# Alta Video Camera Proxy
+
+An Electron desktop application for managing Alta Video camera proxy connections with API integration. This application allows you to authenticate with your Alta deployment, browse available cameras, and launch camera proxy connections through an external executable.
+
+## Features
+
+- **Encrypted Profile Management**: Store multiple connection profiles with AES-encrypted passwords
+- **API Integration**: Secure authentication and device discovery via Alta Video API
+- **Camera Proxy Management**: Launch and manage up to 2 simultaneous 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
+- **Modern Dark UI**: Professional dark-mode interface with responsive design
+- **Cookie-Based Proxy**: Alternative cookie-based authentication method (requires aware-cam-proxy.exe)
+
+## Prerequisites
+
+- **Node.js** (version 14 or higher)
+- **npm** (comes with Node.js)
+- **Valid Alta Video API credentials**
+- **Windows OS** (required for camera proxy executable)
+- **aware-cam-proxy-win.exe** (camera proxy executable) - must be placed in the application directory
+
+## Installation
+
+1. Clone or download this project
+2. Open a terminal in the project directory
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+## Usage
+
+### Starting the Application
+
+```bash
+npm start
+```
+
+Or for development mode with DevTools:
+```bash
+npm run dev
+```
+
+### Creating a Connection Profile
+
+1. Click "Add User" to create a new profile
+2. Enter:
+   - **Profile Name**: A friendly name for this profile
+   - **Deployment URL**: Your Alta deployment URL (e.g., `https://your-deployment.eu1.aware.avasecurity.com`)
+   - **Username**: Your Alta username
+   - **Password**: Your Alta password (stored encrypted)
+3. Click "Save Profile"
+
+### Connecting to Alta API
+
+1. Select a profile from the dropdown
+2. Click "Connect to API"
+3. Devices will automatically load and display in the left sidebar
+
+### Launching Camera Proxy
+
+1. **Connect to API** first
+2. **Select a device** from the left sidebar (click on a device name)
+3. Click "Start Camera Proxy"
+4. A command prompt window will open
+5. **Password is copied to clipboard** - press Ctrl+V when prompted
+6. The proxy will establish connection to the camera
+
+**Note**: You can run up to 2 simultaneous camera proxy connections. Active connections are indicated with a green "PROXY ACTIVE" badge on the device.
+
+## API Endpoints Used
+
+- **Authentication**: `POST /api/v1/dologin` - User login
+- **Device List**: `GET /api/v1/devices` - Retrieve all devices
+- **Auth Info**: `GET /api/v1/auth` - Verify authentication status
+
+## Camera Proxy Methods
+
+### Username/Password Method
+Uses `aware-cam-proxy-win.exe` with credentials:
+```bash
+aware-cam-proxy-win.exe -a <domain> -u <username> -d <device-uuid>
+```
+
+### Cookie Method (Alternative)
+Uses `aware-cam-proxy.exe` with cookie authentication:
+```bash
+aware-cam-proxy.exe -a <domain> -d <device-uuid> -k <cookie-key>
+```
+
+## Security Features
+
+- **Context Isolation**: Renderer process is isolated from Node.js APIs
+- **Preload Script**: Secure IPC communication between main and renderer processes
+- **Encrypted Storage**: Passwords are encrypted using AES encryption before storage
+- **No Hardcoded Credentials**: All credentials are entered and managed by the user
+- **Profile-Based Authentication**: Secure profile management with encrypted credential storage
+
+⚠️ **Security Note**: Encryption key is derived from machine identifiers (hostname, homedir, username) via SHA-256. Profiles are not portable between machines.
+
+## File Structure
+
+```
+├── main.js              # Main Electron process (IPC handlers, API, proxy spawning, encryption)
+├── renderer.js          # Renderer process (UI logic, state management, event handlers)
+├── preload.js           # Secure IPC bridge (contextBridge)
+├── index.html           # Static HTML shell (CSP enforced)
+├── styles.css           # Dark theme styling (CSS custom properties)
+├── package.json         # Project dependencies and build config
+├── assets/
+│   └── icon.png         # Application icon
+├── CLAUDE.md            # Claude Code project instructions
+└── README.md            # This file
+```
+
+**External executables** (not included in repo — must be placed in app directory):
+- `aware-cam-proxy-win.exe` — username/password auth proxy (required)
+- `aware-cam-proxy.exe` — cookie-based auth proxy (optional)
+
+### Profile Storage
+
+Profiles are stored in: `~/.alta-api-profiles.json` (user home directory)
+
+## Troubleshooting
+
+### Connection Issues
+- Verify your deployment URL is correct and accessible
+- Check your username and password
+- Ensure your network allows HTTPS connections to the deployment
+- Check if your account requires 2FA (not currently supported)
+
+### Camera Proxy Issues
+- **Executable not found**: Ensure `aware-cam-proxy-win.exe` is in the application directory
+- **Proxy won't start**: Check that you're connected to the API and have selected a device
+- **Maximum connections**: You can only run 2 simultaneous connections - stop an existing one first
+- **Command window closes immediately**: Check credentials and network connectivity
+
+### Device List Issues
+- Ensure you're connected to the API first
+- Check that your user account has permissions to view devices
+- **No devices shown**: You may only have cloud cameras (localStorage=true) which are filtered out
+- Use the search box to find specific devices
+
+## API Documentation
+
+This application is built according to the Avigilon Alta Video API documentation. For more advanced features or custom integrations, refer to the official API documentation.
+
+## Limitations
+
+- **Windows Only**: Camera proxy executables are Windows-specific (.exe files)
+- **2FA Not Supported**: Two-factor authentication is not currently supported
+- **Connection Limit**: Maximum of 2 simultaneous camera proxy connections
+- **Local Cameras Only**: Automatically filters out cloud-based cameras (localStorage=true)
+- **No Session Refresh**: Sessions may expire and require reconnection
+- **Executable Required**: `aware-cam-proxy-win.exe` must be obtained separately
+
+## Building for Distribution
+
+```bash
+# Build portable Windows executable
+npm run build
+
+# Output will be in: dist/AltaCameraProxy-1.0.0-portable.exe
+```
+
+**Important**: Copy `aware-cam-proxy-win.exe` to the same directory as the built executable before distribution.
+
+## Development
+
+To modify or extend this application:
+
+1. **Main Process** ([main.js](main.js)): Electron app lifecycle, API requests, and process management
+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. **Styling** ([styles.css](styles.css)): Dark mode theme and responsive design
+
+### Adding New API Endpoints
+
+1. Add IPC 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.