feat(cctv): seven camera packs, semantic labels, terrain-clear monitor planes (#433)

Seven contributed CCTV camera packs (Ontario 511, Fintraffic Finland, DriveBC, TxDOT Texas, Estonia Tallinn + Tarktee, Warendorf, Live Traffic NSW) on a fair per-pack catalog cap; semantic camera labels; monitor planes lifted clear of the terrain from a precomputed, bundled ground-height dataset. Default catalog 800 → 3,446 cameras. Full context in PR #433.

Co-authored-by: sendmebits <[email protected]>
Co-authored-by: avocadoAgent <[email protected]>
Co-authored-by: Alex Harvey <[email protected]>
Co-authored-by: Jason Meredith <[email protected]>
Co-authored-by: Daniel Smith <[email protected]>
Co-authored-by: Vladimir Sobolev <[email protected]>
Co-authored-by: Matthias Schneider <[email protected]>
Co-authored-by: Cyber Knight <[email protected]>
Co-authored-by: NovaSoft Australia <[email protected]>

server/providers/cctv/media.js

@@ -5,6 +5,8 @@ import {
   CCTV_FRAME_MAX_BODY_BYTES,
   CCTV_MEDIA_FETCH_TIMEOUT_MS,
   CCTV_MEDIA_MAX_BODY_BYTES,
+  NSW_IMAGE_ORIGIN,
+  NSW_IMAGE_USER_AGENT,
 } from './constants.js';
 /**
  * Generate a synthetic SVG billboard image for a CCTV camera placeholder.
@@ -238,6 +240,163 @@ export async function fetchCctvMediaUpstream(
   }
 }
 
+/**
+ * Fetch and decode a TxDOT ITS / TransGuide snapshot.
+ *
+ * TxDOT returns JSON with a base64-encoded JPEG in `snippet`, rather than
+ * returning image/jpeg directly.
+ */
+export async function fetchTxdotSnapshot(
+  url,
+  {
+    fetchImpl = fetch,
+    timeoutMs = CCTV_FRAME_FETCH_TIMEOUT_MS,
+    maxBytes = CCTV_FRAME_MAX_BODY_BYTES,
+  } = {},
+) {
+  if (!url) return null;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (
+    parsed.origin !== 'https://its.txdot.gov' ||
+    parsed.pathname !== '/its/DistrictIts/GetCctvSnapshotByIcdId'
+  ) {
+    return null;
+  }
+  // Base64 inflates by 4/3; the JSON envelope adds a few bytes of framing.
+  const maxEnvelopeBytes = Math.ceil((maxBytes * 4) / 3) + 4096;
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    // The snapshot endpoint answers directly; a redirect is not followed, so
+    // the origin/path pin above holds for the request that is actually made.
+    const upstream = await fetchImpl(parsed.toString(), {
+      headers: {
+        Accept: 'application/json',
+        'User-Agent': 'gods-eye-view-cctv-proxy/1.0',
+      },
+      signal: controller.signal,
+      redirect: 'manual',
+    });
+    if (!upstream.ok) return null;
+    const envelope = await readCappedResponseBytes(upstream, maxEnvelopeBytes);
+    if (!envelope) return null;
+    let payload;
+    try {
+      payload = JSON.parse(envelope.toString('utf8'));
+    } catch {
+      return null;
+    }
+    let snippet =
+      typeof payload?.snippet === 'string' ? payload.snippet.trim() : '';
+    if (!snippet) return null;
+    snippet = snippet.replace(/^data:image\/jpeg;base64,/i, '');
+    // Canonical base64 only (4-char groups, padding only at the end):
+    // Buffer.from() silently skips junk, which would let a non-image body
+    // decode into "something".
+    if (
+      snippet.length > maxEnvelopeBytes ||
+      !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+        snippet,
+      )
+    ) {
+      return null;
+    }
+    const body = Buffer.from(snippet, 'base64');
+    if (body.length < 4 || body.length > maxBytes) return null;
+    if (body[0] !== 0xff || body[1] !== 0xd8 || body[2] !== 0xff) return null;
+    return { ok: true, body, contentType: 'image/jpeg' };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeoutId);
+    controller.abort();
+  }
+}
+
+/** Redirect hops the frame path will follow, and only within the same host. */
+const MAX_SAME_HOST_REDIRECTS = 2;
+
+/**
+ * Fetch a registered frame URL following redirects ONLY within the original
+ * origin (scheme, host and port; at most MAX_SAME_HOST_REDIRECTS hops).
+ * Default redirect-following would let an upstream steer a host-pinned
+ * request, and its host-specific headers, to any origin, another port, or a
+ * plaintext downgrade.
+ *
+ * @param {string} url
+ * @param {object} init - fetch init (headers, signal).
+ * @param {typeof fetch} fetchImpl
+ * @returns {Promise<Response|null>} Final response, or null on an off-host or
+ *   over-long redirect chain.
+ */
+export async function fetchWithinHost(url, init, fetchImpl = fetch) {
+  let current;
+  try {
+    current = new URL(url);
+  } catch {
+    return null;
+  }
+  const origin = current.origin;
+  for (let hop = 0; hop <= MAX_SAME_HOST_REDIRECTS; hop++) {
+    const upstream = await fetchImpl(current.toString(), {
+      ...init,
+      redirect: 'manual',
+    });
+    // Anything that is not a 3xx (including a test double with no status) is
+    // the final answer.
+    const status = Number(upstream?.status);
+    if (!(status >= 300 && status < 400)) return upstream;
+    const location = upstream.headers.get('location');
+    try {
+      await upstream.body?.cancel();
+    } catch {
+      /* no-op */
+    }
+    if (!location || hop === MAX_SAME_HOST_REDIRECTS) return null;
+    let next;
+    try {
+      next = new URL(location, current);
+    } catch {
+      return null;
+    }
+    if (next.origin !== origin) return null;
+    current = next;
+  }
+  return null;
+}
+
+/**
+ * Image hosts that only serve frames to browser-identified clients, keyed by
+ * exact hostname. Every other upstream sees the proxy's own identifying
+ * User-Agent. Keyed on host, not on a URL substring, so a look-alike host or a
+ * path that merely mentions the host never inherits the header.
+ */
+const CCTV_IMAGE_USER_AGENT_BY_HOST = Object.freeze({
+  [new URL(NSW_IMAGE_ORIGIN).hostname]: NSW_IMAGE_USER_AGENT,
+});
+
+/**
+ * User-Agent for one upstream frame request.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function cctvUpstreamUserAgent(url) {
+  try {
+    return (
+      CCTV_IMAGE_USER_AGENT_BY_HOST[new URL(url).hostname] ||
+      'gods-eye-view-cctv-proxy/1.0'
+    );
+  } catch {
+    return 'gods-eye-view-cctv-proxy/1.0';
+  }
+}
+
 /**
  * Fetch one upstream CCTV image within the frame-refresh budget.
  *
@@ -268,10 +427,15 @@ export async function fetchCctvImageFromUpstream(
     );
   }, timeoutMs);
   try {
-    const upstream = await fetchImpl(url, {
-      headers: { 'User-Agent': 'gods-eye-view-cctv-proxy/1.0' },
-      signal: controller.signal,
-    });
+    const upstream = await fetchWithinHost(
+      url,
+      {
+        headers: { 'User-Agent': cctvUpstreamUserAgent(url) },
+        signal: controller.signal,
+      },
+      fetchImpl,
+    );
+    if (!upstream) return null;
     const contentType = upstream.headers.get('content-type') || '';
     if (!upstream.ok || !contentType.startsWith('image/')) {
       controller.abort();