# 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

```bash
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

```bash
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

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