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
CLAUDE.md
+20 -35
View File
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Project Overview ## Project Overview
Alta Proxy Tool (APT) — an Electron desktop app that authenticates with Avigilon Alta Video deployments, discovers cameras, and launches external proxy executables (`aware-cam-proxy-win.exe`, `aware-cam-proxy.exe`) to establish camera connections. Windows-only due to the proxy executables. Alta Proxy Tool (APT) — an Electron desktop app that authenticates with Avigilon Alta Video deployments via a companion Chrome extension, discovers cameras, and launches `aware-cam-proxy.exe` to establish camera connections. Authentication uses cookie import from Chrome — no username/password login flow. Windows-only due to the proxy executable.
## Repository ## Repository
@@ -28,10 +28,9 @@ No test framework is configured. No linter is configured.
This is a vanilla Electron app (no React/Vue/framework). Core files: This is a vanilla Electron app (no React/Vue/framework). Core files:
``` ```
main.js → Electron main process: IPC handlers, API calls (axios), profile CRUD, main.js → Electron main process: IPC handlers, API calls (axios),
camera proxy process spawning, password encryption (CryptoJS + machine-derived key), cookie proxy process spawning, local HTTP cookie server
local HTTP cookie server for Chrome extension bridge preload.js → contextBridge exposing window.electronAPI with IPC wrappers
preload.js → contextBridge exposing window.electronAPI with typed IPC invoke wrappers
renderer.js → All UI logic: DOM manipulation, state management, event handlers renderer.js → All UI logic: DOM manipulation, state management, event handlers
index.html → Static HTML shell, no inline scripts (CSP enforced) index.html → Static HTML shell, no inline scripts (CSP enforced)
styles.css → Dark theme using CSS custom properties styles.css → Dark theme using CSS custom properties
@@ -48,6 +47,18 @@ chrome-extension/
icon*.png → Placeholder icons icon*.png → Placeholder icons
``` ```
### Authentication Flow
There is no login form or profile system. Authentication works exclusively through the Chrome extension cookie bridge:
1. User logs into Alta deployment in Chrome
2. Clicks the Chrome extension popup → "Send Cookie to APT"
3. Extension POSTs `{deploymentUrl, cookieValue}` to `http://127.0.0.1:18247/cookie` with `X-APT-Token` header
4. `main.js` HTTP server validates and forwards via IPC push to renderer
5. `renderer.js` `handleExtensionCookie()` sets session state, auto-populates cookie key, fetches devices
The extension is loaded unpacked via `chrome://extensions/` → Developer mode → Load unpacked → select `chrome-extension/`.
### IPC Communication Pattern ### IPC Communication Pattern
Most cross-process communication follows the request/response pattern: Most cross-process communication follows the request/response pattern:
@@ -66,51 +77,26 @@ There is one **push-pattern** channel for the Chrome extension cookie bridge:
| Channel | Purpose | | Channel | Purpose |
|---------|---------| |---------|---------|
| `api-login` | POST /api/v1/dologin, returns cookies |
| `api-get-devices` | GET /api/v1/devices with cookie auth | | `api-get-devices` | GET /api/v1/devices with cookie auth |
| `api-get-auth-info` | GET /api/v1/auth to verify session | | `api-get-auth-info` | GET /api/v1/auth to verify session |
| `profiles-load/save/get/delete/update` | CRUD for `~/.alta-api-profiles.json` |
| `camera-proxy-launch` | Spawns aware-cam-proxy-win.exe (user/pass method) |
| `camera-proxy-cookie-launch` | Spawns aware-cam-proxy.exe (cookie method) | | `camera-proxy-cookie-launch` | Spawns aware-cam-proxy.exe (cookie method) |
| `camera-proxy-stop` | Kills all proxy processes via taskkill/powershell | | `camera-proxy-stop` | Kills all proxy processes via taskkill/powershell |
| `camera-proxy-check` | Checks if proxy executable exists |
| `camera-proxy-version` | Runs proxy with -v flag |
| `extension-cookie-received` | Push channel: cookie data from Chrome extension → renderer | | `extension-cookie-received` | Push channel: cookie data from Chrome extension → renderer |
### State Management (renderer.js) ### State Management (renderer.js)
All connection state lives in the `sessionData` object (deploymentUrl, cookies, isConnected). There is no separate `isConnected` flag — always use `sessionData.isConnected`. All connection state lives in the `sessionData` object (deploymentUrl, cookies, isConnected). There is no separate `isConnected` flag — always use `sessionData.isConnected`.
Active proxy processes are tracked in two Maps: `activeProxyConnections` and `activeCookieProxyConnections`, keyed by device GUID. Max 2 simultaneous connections (`MAX_PROXY_CONNECTIONS`). Active cookie proxy processes are tracked in `activeCookieProxyConnections` Map, keyed by device GUID.
### Security Model ### Security Model
- Context isolation enabled, nodeIntegration disabled - Context isolation enabled, nodeIntegration disabled
- CSP meta tag: `script-src 'self'` — no inline scripts or onclick handlers allowed - CSP meta tag: `script-src 'self'` — no inline scripts or onclick handlers allowed
- Batch file inputs are sanitized via `sanitizeBatchInput()` to prevent command injection - Batch file inputs are sanitized via `sanitizeBatchInput()` to prevent command injection
- Encryption key derived from machine identifiers (hostname, homedir, username) via SHA-256
- Legacy profiles auto-migrate from old static key on first load
- Clipboard is cleared 30 seconds after password copy
- Passwords never written to DOM; kept only in JS variables (`selectedProfile`)
- Local HTTP cookie server (port 18247) bound to `127.0.0.1` only - Local HTTP cookie server (port 18247) bound to `127.0.0.1` only
- Cookie server validates: shared token header, CORS restricted to `chrome-extension://` origins, deployment URL must be `*.avasecurity.com` or `*.avigilon.com` over HTTPS, type/length limits on all inputs, 64KB body size limit - Cookie server validates: shared token header, CORS restricted to `chrome-extension://` origins, deployment URL must be `*.avasecurity.com` or `*.avigilon.com` over HTTPS, type/length limits on all inputs, 64KB body size limit
### Profile Storage
Profiles stored at `~/.alta-api-profiles.json`. Passwords encrypted with CryptoJS AES using a machine-derived key. The `profiles-load` handler strips passwords before sending to renderer; `profiles-get` decrypts for a specific profile when needed.
### Chrome Extension Cookie Bridge
Users already logged into Alta in Chrome can send their `va` session cookie to the running Electron app. The flow:
1. Chrome extension popup detects Alta tab (`*.avasecurity.com` / `*.avigilon.com`)
2. User clicks "Send Cookie to APT"
3. Extension POSTs `{deploymentUrl, cookieValue}` to `http://127.0.0.1:18247/cookie` with `X-APT-Token` header
4. `main.js` HTTP server validates and forwards via IPC push to renderer
5. `renderer.js` `handleExtensionCookie()` sets session state, populates cookie key, expands cookie proxy section, fetches devices
The extension is loaded unpacked via `chrome://extensions/` → Developer mode → Load unpacked → select `chrome-extension/`.
## Key Conventions ## Key Conventions
- No inline event handlers in HTML — all use `addEventListener` in renderer.js - No inline event handlers in HTML — all use `addEventListener` in renderer.js
@@ -119,9 +105,8 @@ The extension is loaded unpacked via `chrome://extensions/` → Developer mode
- Device list filters out cloud cameras (`capabilities.localStorage === false` only) - Device list filters out cloud cameras (`capabilities.localStorage === false` only)
- `clearDeviceList()` must NOT clear proxy connection Maps (proxies may still be running) - `clearDeviceList()` must NOT clear proxy connection Maps (proxies may still be running)
## External Executables ## External Executable
- `aware-cam-proxy-win.exe` — username/password auth proxy (required) - `aware-cam-proxy.exe` — cookie-based auth proxy (required)
- `aware-cam-proxy.exe` — cookie-based auth proxy (optional)
These are not bundled via npm. They must be in the app root directory. They are gitignored along with `*.pdf`, `node_modules/`, and `dist/`. Not bundled via npm. Must be in the app root directory. Gitignored along with `*.pdf`, `node_modules/`, and `dist/`.
README.md
+79 -90
View File
@@ -1,34 +1,42 @@
# Alta Video Camera Proxy # 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 ## Features
- **Encrypted Profile Management**: Store multiple connection profiles with AES-encrypted passwords - **Chrome Extension Authentication**: Import your Alta session cookie from Chrome with one click — no manual login
- **API Integration**: Secure authentication and device discovery via Alta Video API - **API Integration**: Device discovery via Alta Video API using cookie auth
- **Camera Proxy Management**: Launch and manage up to 2 simultaneous camera proxy connections - **Camera Proxy Management**: Launch and manage camera proxy connections
- **Device Filtering**: Automatically filters to show only local (non-cloud) cameras - **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 - **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 - **Real-time Status**: Live connection status and device online/offline indicators
- **Modern Dark UI**: Professional dark-mode interface with responsive design - **Modern Dark UI**: Professional dark-mode interface with responsive design
- **Cookie-Based Proxy**: Alternative cookie-based authentication method (requires aware-cam-proxy.exe)
## Prerequisites ## Prerequisites
- **Node.js** (version 14 or higher) - **Node.js** (version 14 or higher)
- **npm** (comes with Node.js) - **npm** (comes with Node.js)
- **Valid Alta Video API credentials** - **Google Chrome** (for the authentication extension)
- **Windows OS** (required for camera proxy executable) - **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 ## Installation
1. Clone or download this project 1. Clone or download this project
2. Open a terminal in the project directory 2. Install dependencies:
3. Install dependencies:
```bash ```bash
npm install 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 ## Usage
@@ -43,142 +51,123 @@ Or for development mode with DevTools:
npm run dev npm run dev
``` ```
### Creating a Connection Profile ### Connecting to Alta
1. Click "Add User" to create a new profile 1. **Log into your Alta deployment** in Chrome (e.g., `https://your-site.eu1.aware.avasecurity.com`)
2. Enter: 2. **Click the extension icon** in Chrome — it will detect the Alta tab
- **Profile Name**: A friendly name for this profile 3. **Click "Send Cookie to APT"** — the app will connect and load devices automatically
- **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 ### Launching Camera Proxy
1. **Connect to API** first 1. **Connect via Chrome extension** (above)
2. **Select a device** from the left sidebar (click on a device name) 2. **Select a device** from the left sidebar
3. Click "Start Camera Proxy" 3. **Click "Start Camera Proxy"**
4. A command prompt window will open 4. A command prompt window will open with the proxy connection
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 ## API Endpoints Used
- **Authentication**: `POST /api/v1/dologin` - User login - **Device List**: `GET /api/v1/devices` — Retrieve all devices
- **Device List**: `GET /api/v1/devices` - Retrieve all devices - **Auth Info**: `GET /api/v1/auth` — Verify authentication status
- **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: Chrome Extension (popup click)
```bash → POST http://127.0.0.1:18247/cookie
aware-cam-proxy-win.exe -a <domain> -u <username> -d <device-uuid> → Electron app HTTP server receives cookie
→ Sets session state, fetches devices
→ User selects device → launches aware-cam-proxy.exe
``` ```
### Cookie Method (Alternative) 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.
Uses `aware-cam-proxy.exe` with cookie authentication:
```bash
aware-cam-proxy.exe -a <domain> -d <device-uuid> -k <cookie-key>
```
## Security Features ## Security
- **Context Isolation**: Renderer process is isolated from Node.js APIs - **Context Isolation**: Renderer process is isolated from Node.js APIs
- **Preload Script**: Secure IPC communication between main and renderer processes - **Preload Script**: Secure IPC communication between main and renderer processes
- **Encrypted Storage**: Passwords are encrypted using AES encryption before storage - **CSP Enforced**: `script-src 'self'` — no inline scripts allowed
- **No Hardcoded Credentials**: All credentials are entered and managed by the user - **Localhost Only**: Cookie server binds to `127.0.0.1`, not accessible from network
- **Profile-Based Authentication**: Secure profile management with encrypted credential storage - **CORS Restricted**: Only `chrome-extension://` origins accepted
- **Domain Validation**: Only `*.avasecurity.com` and `*.avigilon.com` URLs accepted
⚠️ **Security Note**: Encryption key is derived from machine identifiers (hostname, homedir, username) via SHA-256. Profiles are not portable between machines. - **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 ## File Structure
``` ```
├── main.js # Main Electron process (IPC handlers, API, proxy spawning, encryption) ├── main.js # Main process (IPC, API calls, proxy spawning, cookie server)
├── renderer.js # Renderer process (UI logic, state management, event handlers) ├── renderer.js # Renderer process (UI logic, state management)
├── preload.js # Secure IPC bridge (contextBridge) ├── preload.js # Secure IPC bridge (contextBridge)
├── index.html # Static HTML shell (CSP enforced) ├── index.html # Static HTML shell (CSP enforced)
├── styles.css # Dark theme styling (CSS custom properties) ├── styles.css # Dark theme styling
├── package.json # Project dependencies and build config ├── 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/ ├── assets/
│ └── icon.png # Application icon │ └── icon.png # Application icon
├── CLAUDE.md # Claude Code project instructions ├── CLAUDE.md # Claude Code project instructions
└── README.md # This file └── README.md # This file
``` ```
**External executables** (not included in repo — must be placed in app directory): **External executable** (not included in repo):
- `aware-cam-proxy-win.exe` — username/password auth proxy (required) - `aware-cam-proxy.exe` — cookie-based auth proxy (required, place in app root)
- `aware-cam-proxy.exe` — cookie-based auth proxy (optional)
### Profile Storage
Profiles are stored in: `~/.alta-api-profiles.json` (user home directory)
## Troubleshooting ## Troubleshooting
### Connection Issues ### Connection Issues
- Verify your deployment URL is correct and accessible - Ensure you are **logged into Alta in Chrome** before clicking the extension
- Check your username and password - Verify the extension shows "Detected: [hostname]" in green
- Ensure your network allows HTTPS connections to the deployment - If extension shows "Alta Proxy Tool is not running" — start the Electron app first
- Check if your account requires 2FA (not currently supported) - 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 ### Camera Proxy Issues
- **Executable not found**: Ensure `aware-cam-proxy-win.exe` is in the application directory - **Executable not found**: Ensure `aware-cam-proxy.exe` is in the application directory
- **Proxy won't start**: Check that you're connected to the API and have selected a device - **Proxy won't start**: Check that you're connected and have selected a device
- **Maximum connections**: You can only run 2 simultaneous connections - stop an existing one first - **Command window closes immediately**: Check network connectivity to the deployment
- **Command window closes immediately**: Check credentials and network connectivity
### Device List Issues ### 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 - 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 - 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 ## Building for Distribution
```bash ```bash
# Build portable Windows executable # Build portable Windows executable
npm run build 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 ## Development
To modify or extend this application: 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 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 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()` 2. Expose method in [preload.js](preload.js) via `contextBridge.exposeInMainWorld()`
3. Call from [renderer.js](renderer.js) using `window.electronAPI.yourMethod()` 3. Call from [renderer.js](renderer.js) using `window.electronAPI.yourMethod()`