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

fix: integrate hardened APT security boundary

Browse Source
This commit is contained in:
PageZ948
2026-08-19 21:36:24 +00:00
parent b6df6f1a66
commit 2f492b662d
14 changed files with 1113 additions and 1730 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+47 -168
View File
@@ -1,186 +1,65 @@
# Alta Video Camera Proxy
# Alta Video Camera Proxy
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.
APT is a Windows Electron desktop app that imports an existing Alta Video session through its paired Chrome extension, discovers local cameras, and launches `aware-cam-proxy.exe` without exposing Alta credentials to the renderer.
## Features
## Security boundary
- **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
- **Auto-Update**: Checks for updates on startup via GitHub Releases, with one-click in-place update
- **Modern Dark UI**: Professional dark-mode interface with responsive design
- `main.js` owns the in-memory `SessionStore`, `AltaClient`, `ProxyProcessManager`, bridge pairing envelope, and update checker.
- The renderer receives only connection origin/state, device/site/auth responses, and owned proxy metadata. It never receives or supplies the Alta session value.
- The bridge listens only on `127.0.0.1:18247`, accepts only the committed extension origin, requires the `X-APT-Pairing` secret, limits concurrent/body/deadline work, and validates an exact canonical Alta HTTPS origin.
- The pairing envelope is a scrypt hash stored atomically under Electron `userData` with restrictive permissions. The plaintext secret is shown once on first run or rotation. Revoke invalidates it.
- Proxy launch is a direct `spawn` of the fixed helper with `shell: false`; stop actions can target only children owned by this app.
- Updates are **check-only**. APT checks the exact GitPeji release API and can open only `https://git.pejicorp.com/peji/Alta-Proxy-Tool/releases` in the system browser. It never downloads, replaces, or executes an update.
## Prerequisites
## Requirements
- **Node.js** (version 14 or higher)
- **npm** (comes with Node.js)
- **Google Chrome** (for the authentication extension)
- **Windows OS** (required for camera proxy executable)
- **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)
- Windows (current supported runtime scope)
- Node.js and npm for development
- Chrome with the bundled extension loaded unpacked
- `aware-cam-proxy.exe` beside the development app or packaged portable executable
- An active Alta Video login in Chrome
## Installation
1. Clone or download this project
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
### Starting the Application
## Setup and pairing
```bash
npm install
npm start
```
Or for development mode with DevTools:
```bash
npm run dev
```
1. Open `chrome://extensions`, enable Developer mode, and load `chrome-extension/` unpacked.
2. Start APT. Under **Bridge Pairing**, copy the one-time secret.
3. Open the extension pairing settings, paste the secret, and save it.
4. Visit your Alta deployment in Chrome and use **Send to APT**.
5. Select a local camera and choose **Start Proxy**.
### Connecting to Alta
Use **Generate / Rotate** if a pairing may have been exposed, then update the extension. Use **Revoke** to immediately disable bridge authentication.
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 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
### Updating
The app checks for updates automatically 2 seconds after launch. If a newer version is available on GitHub Releases, the "Check for Updates" button in the header will show a green badge.
- **Manual check**: Click "Check for Updates" in the top-right corner
- **Install**: The update modal shows release notes — click "Install Update" to download and replace the current executable
- The app will quit, swap the `.exe`, and relaunch automatically
## API Endpoints Used
- **Device List**: `GET /api/v1/devices` — Retrieve all devices
- **Auth Info**: `GET /api/v1/auth` — Verify authentication status
## How It Works
```
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
```
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
- **Context Isolation**: Renderer process is isolated from Node.js APIs
- **Preload Script**: Secure IPC communication between main and renderer processes
- **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 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
├── 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 executable** (not included in repo):
- `aware-cam-proxy.exe` — cookie-based auth proxy (required, place in app root)
## Troubleshooting
### Connection Issues
- 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.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 via the Chrome extension first
- Check that your user account has permissions to view devices
- **No devices shown**: You may only have cloud cameras which are filtered out
- Use the search box to find specific devices
## Building for Distribution
## Development and verification
```bash
npm test # Node test suite, including synthetic runtime contracts
npm run check # Syntax checks plus tests
npm run build-test
```
Tests use synthetic sessions/transports/processes only. Never add a real Alta tenant URL or session value to fixtures, logs, screenshots, or commits.
Core files:
- `main.js` — Electron lifecycle, trusted-sender IPC, fixed loopback server
- `src/electron-runtime.js` — pairing persistence, bridge handler, narrow runtime orchestration
- `src/session-store.js`, `src/alta-client.js` — main-only Alta session and requests
- `src/proxy-launch.js` — fixed shell-free helper process management
- `src/update-policy.js` — exact GitPeji check-only release policy
- `preload.js` — narrow context bridge
- `renderer.js`, `index.html`, `styles.css` — non-secret UI
- `chrome-extension/` — stable-ID paired cookie sender
- `test/` — pure and end-to-end contract tests
## Building
```bash
# Build portable Windows executable
npm run build
# Output: dist/AltaCameraProxy-1.0.0-portable.exe
```
**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
- **Update Requires Write Access**: Self-update needs write permission to the directory containing the `.exe`
## Development
To modify or extend this application:
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. **Chrome Extension** ([chrome-extension/](chrome-extension/)): Cookie import from browser
5. **Styling** ([styles.css](styles.css)): Dark mode theme and responsive design
### Adding New IPC Endpoints
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.
The output remains Windows-only because the external camera helper is Windows-specific. Copy `aware-cam-proxy.exe` beside the portable APT executable before use. Dependencies are intentionally unchanged in this hardening release.