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
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/`.