Alta-Proxy-Tool/README.md

Alta Video Camera Proxy

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.

Security boundary

• 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, detached spawn of the fixed helper with shell: false. Its exact arguments are deployment host, non-secret Alta username/email, and selected device UUID; no session bearer, password, or 2FA value reaches the command line. 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.

Requirements

• Windows (current supported runtime scope)
• Node.js 22.12 or newer 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

Setup and pairing

npm install
npm start

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, enter your Alta username/email, and choose Start Proxy.
6. Complete the password and 2FA prompts in the helper's visible Windows console. APT does not collect or pass those secrets.

Use Generate / Rotate if a pairing may have been exposed, then update the extension. Use Revoke to immediately disable bridge authentication.

Camera hierarchy and large deployments

The sidebar presents collapsed Alta sites, then device groups, then cameras, including explicit fallback nodes for ungrouped, orphaned, unknown, or conflicting metadata. Search opens only matching ancestors and supports full tree keyboard navigation. A fixed-height virtual window keeps the mounted DOM bounded even when thousands of cameras are visible; selection and active-proxy state survive expansion, search, and scrolling. If site or group metadata cannot be loaded, every valid camera remains selectable in the fallback hierarchy and APT shows a warning.

Development and verification

npm test          # Node test suite, including synthetic runtime contracts
npm run check     # Syntax checks plus tests
npm run audit:prod
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
• device-tree.js, sidebar-controller.js, sidebar-view.js — pure hierarchy, interaction state, and bounded DOM adapter
• renderer.js, index.html, styles.css — non-secret UI integration and Alta styling
• chrome-extension/ — stable-ID paired cookie sender
• test/ — pure and end-to-end contract tests

Building

npm run build

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.

CI produces an unpacked Windows build only for verification. It does not publish, release, push, deploy, or sign artifacts. Windows code signing and verification with the approved certificate remain mandatory manual release gates; a successful build must not be represented as signed.