From f57183448fea2137ba80c02aafe3e8e645e2b3e1 Mon Sep 17 00:00:00 2001 From: Zac Date: Mon, 9 Feb 2026 21:30:11 -0500 Subject: [PATCH] Update CLAUDE.md and README.md for cookie-only architecture 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 --- CLAUDE.md | 55 +++++++----------- README.md | 171 +++++++++++++++++++++++++----------------------------- 2 files changed, 100 insertions(+), 126 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index f5751b2..2b2a0cb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## 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 @@ -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: ``` -main.js → Electron main process: IPC handlers, API calls (axios), profile CRUD, - camera proxy process spawning, password encryption (CryptoJS + machine-derived key), - local HTTP cookie server for Chrome extension bridge -preload.js → contextBridge exposing window.electronAPI with typed IPC invoke wrappers +main.js → Electron main process: IPC handlers, API calls (axios), + cookie proxy process spawning, local HTTP cookie server +preload.js → contextBridge exposing window.electronAPI with IPC wrappers renderer.js → All UI logic: DOM manipulation, state management, event handlers index.html → Static HTML shell, no inline scripts (CSP enforced) styles.css → Dark theme using CSS custom properties @@ -48,6 +47,18 @@ chrome-extension/ 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 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 | |---------|---------| -| `api-login` | POST /api/v1/dologin, returns cookies | | `api-get-devices` | GET /api/v1/devices with cookie auth | | `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-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 | ### 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`. -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 - Context isolation enabled, nodeIntegration disabled - CSP meta tag: `script-src 'self'` — no inline scripts or onclick handlers allowed - 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 - 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 - 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) - `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 (optional) +- `aware-cam-proxy.exe` — cookie-based auth proxy (required) -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/`. diff --git a/README.md b/README.md index b1e83a0..f7d8bc5 100644 --- a/README.md +++ b/README.md @@ -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 -u -d +``` +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 -d -k -``` +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. \ No newline at end of file +MIT License - Feel free to modify and distribute as needed.