📷 CAMERA SYSTEM — canonical reference (don't re-discover this)

Last verified: 2026-06-25 (camera/infra session). LIVING doc. Evidence discipline: ✅ = verified this session; 🟡 = per Brain/prior, spot-check recommended; ⚠️ = unverified/flag.
One-line truth (UPDATED 2026-07-01): cameras = Hikvision NVR → ops-api nvrFetch() DIRECT (digest auth, PC-FREE) → /camera/snapshot → portal. Rewired to the NVR-direct path (deployed a405e728; all 4 cams verified HTTP 200 + JPEG straight from the NVR — no PC). go2rtc-on-PC is now only a FALLBACK and can be stopped. ⚠️ NVR ports 8500/8501 are internet-exposed — Step 2 = cloudflared tunnel to the NVR from an always-on box, then close the eero forwards (raw Hikvision ports are actively exploited). Step-2 runbook → docs/CAMERA_STEP2_TUNNEL_RUNBOOK.md (host = a ~$50 always-on LAN box, NOT the PC; exact steps; written 2026-07-01).

CAMERA MAP ✅ (verified by on-screen OSD labels + cameras.html + Brain)

ARCHITECTURE (A) — FALLBACK ONLY (as of 2026-07-01): go2rtc RTSP bridge (PC-tied)

Chain: cameras.html <img> → ops-api /camera/snapshot?cam=N (referer-gated) → Worker fetches https://cam.hookstreetservices.com/api/frame.jpeg?src=camN with headers CF-Access-Client-Id: <CAM_CF_ID> + CF-Access-Client-Secret: <CAM_CF_SECRET> (names only, never values) → cloudflared tunnel treitel-cameras → go2rtc on Sam's PC (localhost:1984) → NVR RTSP rtsp://admin:<NVR_PW>@192.168.4.47:54607/Streaming/Channels/N02 → JPEG (ffmpeg-transcoded). Code: ops-api/src/index.ts ~L630-668.
Why this exists: the NVR's direct HTTP/ISAPI web service stopped responding (see Architecture B / the security hardening), so we go around it via RTSP.

go2rtc setup on the PC (everything, exact)

• Install dir: C:\Users\ztrei\go2rtc\ — go2rtc.exe (v1.9.14) + ffmpeg.exe (~143MB, needed for H.265→JPEG) + go2rtc.yaml.
• Config C:\Users\ztrei\go2rtc\go2rtc.yaml (creds redacted):
  yaml streams: cam1: rtsp://admin:<NVR_PW>@192.168.4.47:54607/Streaming/Channels/102 cam2..cam8: ...Channels/202 .. 802 # cam=N -> channel N02 (sub-stream, lighter/H.264) api: listen: ":1984" username: "hsops" # basic auth; but go2rtc TRUSTS localhost so the tunnel password: "<GO2RTC_PW>" # (which connects from localhost) is NOT gated by this. ffmpeg: bin: "C:/Users/ztrei/go2rtc/ffmpeg.exe" # absolute -> cwd-independent
• Ports: go2rtc API/web :1984, RTSP :8554, WebRTC :8555 (all local).
• Start manually: cd C:\Users\ztrei\go2rtc && go2rtc.exe -config go2rtc.yaml
• Auto-start (INSTALLED 2026-06-25 ✅): C:\Users\ztrei\go2rtc\start-go2rtc.bat (does cd /d C:\Users\ztrei\go2rtc && start "" /min go2rtc.exe -config C:\Users\ztrei\go2rtc\go2rtc.yaml), copied into the Startup folder C:\Users\ztrei\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\start-go2rtc.bat → relaunches go2rtc on every login. (A schtasks ... /sc onlogon task needs admin; the Startup-folder copy does NOT — that's why we used it.)
• Restart: taskkill //F //IM go2rtc.exe then run the bat (or it relaunches at next login).
• Verify locally: curl http://localhost:1984/api/frame.jpeg?src=cam1 → ffd8... JPEG = healthy. http://localhost:1984/api/streams = producer states.

Cloudflare side

• Tunnel treitel-cameras (id 16a75a7b-5ee7-4715-8bf5-b6ae746eb8da), DNS cam.hookstreetservices.com CNAME→tunnel (proxied). Ingress → http://localhost:1984 (go2rtc). Editable via CF API /accounts/<acct>/cfd_tunnel/<id>/configurations. The cloudflared Windows service runs the connector (dials out; no inbound port).
• CF Access app "Treitel Cameras" (id ab415497-863c-465c-ad68-16ada31d3d22) gates cam.hookstreetservices.com to Sam's login + a non-identity service-token policy for the ops-api Worker.
• Service token "ops-api-camera-proxy" → CAM_CF_ID (...access) + CAM_CF_SECRET (Worker secrets, names only). Rotate: create a new service token via CF API → add to the cam app's policy → set the two Worker secrets (CF-API way, see secret rules) → delete the old token.

ARCHITECTURE (B) — ⭐ CURRENT / LIVE (rewired 2026-07-01): NVR-direct, PC-FREE

Was: Worker nvrFetch() → http://d6468120.eero.online:8500/ISAPI/Streaming/channels/<ch>/picture (eero DDNS + eero port-forward → NVR, MD5 digest auth, NVR_HOST/NVR_USER/NVR_PASS). Verified working June 2 (commit 88c1454, "cam1 returns 34KB JPEG"). PC-FREE — the NVR served snapshots itself; nothing ran on the PC.
⚠️ CORRECTED 2026-07-01 (verified live from Sam's eero app — supersedes the old "closed June 1" claim below): the eero port-forwards are STILL OPEN + ENABLED — the NVR 192.168.4.47 has 8500 AND 8501 forwarded to the internet (Reservations & port forwards → "Hangzhou Hikvision Digital"). DDNS d6468120.eero.online → 74.101.240.91 is live (Dynamic DNS ON). So the NVR is currently internet-reachable — nvrFetch() (Architecture B, PC-FREE) works RIGHT NOW; a live GET to :8500 returned 200. The NVR is the ONLY forwarded device (iPod/laptop/iPads are LAN-only reservations). This is a real security exposure (internet-facing Hikvision = actively exploited) → the plan is: (1) rewire ops-api to nvrFetch() for PC-free cameras now, (2) stand up a cloudflared tunnel to the NVR from an always-on HOME box, (3) Sam disables the 8500/8501 eero forwards to close the hole. NEVER leave raw ports open long-term.

~~OLD (WRONG) note, kept for history:~~ "Why it broke: Sam's 2026-06-01 hardening moved the NVR port off 8500 + closed the eero 8500 forward → 8500 empty / 443 refused." — the eero shows the forward was never actually removed; 8500 is open. (The FABRICATED "firmware update killed it" citation in ops-api/src/index.ts ~L642 is also false — flag for correction.)
Restore (a SECURITY decision, Sam + camera/infra own it): the nvrFetch() helper is STILL in ops-api/src/index.ts (only the call site was rewired). To go PC-free: revert /camera/snapshot to nvrFetch() + make the NVR HTTP reachable again. Secure form = a cloudflared tunnel → the NVR's HTTPS on an always-on box (NOT reopening raw 8500 to the internet). Reopening 8500 = the exposure the audit flagged. Deploy alone does NOT light cameras — the secret/route half ships, but the architecture choice is the actual restore.

SECRET / VERSION ARCHITECTURE + SAFE-RESTORE RULES (🔴 critical)

• ops-api secrets (30) are VERSION-EMBEDDED, not script-level. wrangler secret list shows 0 even when all 30 are present — DO NOT trust it; the reliable check is a live secret-backed endpoint (e.g. /camera/snapshot or /plaid/balances).
• NEVER wrangler secret put or a bare wrangler deploy on ops-api → strands all 30 secrets (happened twice 6/24-25; cameras + Plaid + comms all died).
• Safe restore = CF-API rollback/roll-forward to the max-secret version (e.g. live = ad740523, 30 secrets incl CAM_CF; earlier good = bbaba3ee). The Brain/#042 session owns this.
• The master→ops-api build-clobber (every push rebuilt the wrong root wrangler.toml onto ops-api → stranded secrets) is FIXED 2026-06-25 (build path-scoped: root_directory:ops-api, path_includes:ops-api/*). Committing docs/skills/portal to master is now safe; only ops-api/* code edits are sensitive.

DIAGNOSTIC DECISION TREE (502 / "no signal")

1. ALL cams 502 + a secret-backed endpoint also fails → secrets stranded (clobber/bad deploy). Fix: Brain rolls ops-api to the max-secret version.
2. ALL cams 502 + other endpoints WORK → wrong/regressed ops-api version (route missing). Fix: roll forward to the full version (ad740523).
3. SOME cams work, one is 502 / "no signal" → THAT camera's source feed (go2rtc/RTSP/physical), NOT ops-api. Check: curl localhost:1984/api/frame.jpeg?src=camN. If local works but portal 502s = tunnel/ops-api; if local also fails = the physical camera/NVR channel (power-cycle/reseat when home). cam4 is permanently dead (empty connection).
4. Brief "no signal" that self-recovers → transient RTSP drop; go2rtc auto-reconnects. Refresh. Only worry if a camera flaps persistently (then physical).

5-POINT ACCEPTANCE TEST (not "done" until all pass)

1. PC awake. 2. go2rtc + cloudflared running (tasklist). 3. ops-api has CAM_CF (live /camera/snapshot test, NOT secret list). 4. Worker → tunnel returns JPEGs (7/8; cam4 dead). 5. Feed loads on Sam's phone off Wi-Fi (cellular).

DURABILITY ROADMAP

• ✅ go2rtc auto-start (Startup folder) — survives reboot while PC is on.
• ⬜ Always-on home box (~$150 mini-PC/Pi) running go2rtc + cloudflared → cameras survive the PC being OFF (a cloud VM can't — it can't reach the home LAN). THIS is the durable end state.
• ⬜ Optional: revert to the PC-free Architecture B (security tradeoff) to drop go2rtc entirely.

CURRENT STATE (2026-06-25)

Cameras LIVE via go2rtc (7/8; cam4 dead). ops-api live ad740523 (CAM_CF present). go2rtc + cloudflared running + auto-start installed. cam1/Backyard occasionally shows a transient "no signal" that self-recovers (6/6 good on last test). Portal labels correct. Off-Wi-Fi confirmed by Sam.