peji/Alta-Proxy-Tool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Update CLAUDE.md and README.md for cookie-only architecture

Browse Source 
Rewrite both docs to reflect the current state: Chrome extension
cookie auth, no profiles/passwords, simplified IPC channels and
file structure, updated troubleshooting and security sections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Zac
2026-02-09 21:30:11 -05:00
parent 0f12915b47
commit f57183448f
2 changed files with 100 additions and 126 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+80 -91
View File
@@ -1,34 +1,42 @@
# 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.
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
- **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
- **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
- **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**
- **Google Chrome** (for the authentication extension)
- **Windows OS** (required for camera proxy executable)
- **aware-cam-proxy-win.exe** (camera proxy executable) - must be placed in the application directory
- **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. Open a terminal in the project directory
3. Install dependencies:
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
@@ -43,145 +51,126 @@ Or for development mode with DevTools:
npm run dev
```
### Creating a Connection Profile
### Connecting to Alta
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
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 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.
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
## 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
- **Device List**: `GET /api/v1/devices` — Retrieve all devices
- **Auth Info**: `GET /api/v1/auth` — Verify authentication status
## Camera Proxy Methods
## How It Works
### Username/Password Method
Uses `aware-cam-proxy-win.exe` with credentials:
```bash
aware-cam-proxy-win.exe -a <domain> -u <username> -d <device-uuid>
```
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
```
### Cookie Method (Alternative)
Uses `aware-cam-proxy.exe` with cookie authentication:
```bash
aware-cam-proxy.exe -a <domain> -d <device-uuid> -k <cookie-key>
```
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 Features
## Security
- **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.
- **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 Electron process (IPC handlers, API, proxy spawning, encryption)
├── renderer.js # Renderer process (UI logic, state management, event handlers)
├── 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 (CSS custom properties)
├── package.json # Project dependencies and build config
├── 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 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)
**External executable** (not included in repo):
- `aware-cam-proxy.exe` — cookie-based auth proxy (required, place in app root)
## 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)
- 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-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
- **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 to the API first
- 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 (localStorage=true) which are filtered out
- **No devices shown**: You may only have cloud cameras 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
# Output: dist/AltaCameraProxy-1.0.0-portable.exe
```
**Important**: Copy `aware-cam-proxy-win.exe` to the same directory as the built executable before distribution.
**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
## Development
To modify or extend this application:
1. **Main Process** ([main.js](main.js)): Electron app lifecycle, API requests, and process management
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. **Styling** ([styles.css](styles.css)): Dark mode theme and responsive design
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 API Endpoints
### Adding New IPC Endpoints
1. Add IPC handler in [main.js](main.js) using `ipcMain.handle()`
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.
MIT License - Feel free to modify and distribute as needed.