Camera pictures without an object-storage bucket

Head office shows a camera's latest frame rather than live video, for a
reason that has not changed: the engine serves MJPEG on 127.0.0.1 on a PC
behind a shop's router with no inbound route, and relaying it needs
WebRTC/TURN. Pointing a browser straight at the shop PC is not the escape
either - the engine's API is Basic-authenticated with a credential it
generates locally and never sends anywhere, and shipping that to the
cloud so a web page could use it would put the key to the biometric API
and the live face feed in the server's database.

But that picture only worked if you had an S3 bucket. Without one,
attachSnapshots reported "This system is not storing images" for every
camera forever - on the two screens whose whole job is to show the
camera. Making them picture-led turned a missing feature into a wall of
empty tiles, on every local install and any self-hosted customer who does
not want a bucket.

migrations/009 adds camera_snapshots and the agent falls back to
PUT /api/agent/cameras/{camera}/snapshot when the presigned route answers
images_disabled - chosen by sentinel, never by matching the message, since
it picks between two routes. One row per camera is what makes this safe in
the database when face images are not: the key IS the camera, so storage
is (cameras x ~100 KB) and does not grow with footfall.

The read is session-authenticated rather than a signed link, which an
<img> cannot use - hence Shot.jsx and useAuthedImage, keyed on the URL
string rather than the snapshot object so a poll does not re-fetch 90 KB
per camera every few seconds, and revoking the object URL on cleanup.

Verified against the real office camera with no bucket configured: 90,587
bytes stored in Postgres, served as image/jpeg to a signed-in user, 401
without a session, rendered on both the Cameras and Shops cards.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HViLj9gYNRtSr7YVZmW5sn

CLAUDE.md

@@ -2171,3 +2171,89 @@ Two bugs, both found by running it after a reboot rather than by reading it.
   longer discarded, and the broker is waited for and reported on if it will not
   stay up. A failure there means the server cannot authenticate to its own
   broker, which is exactly what this script exists to surface early.
+
+## Where the live feed is, and why head office gets a picture instead
+
+Live video exists and always has — on the shop PC, where the camera is:
+
+- `GET /api/cameras/{id}/stream.mjpeg` on the engine's loopback API. Measured
+  on the office camera: 1280×720, ~850 KB/s.
+- The desktop app's Live screen and the engine's own dashboard both render it.
+
+**Head office does not, and cannot cheaply.** The engine serves that stream on
+`127.0.0.1` on a PC behind a shop's router with no inbound route. Putting live
+video on `platform.loyaly.ai` needs a relay — WebRTC with TURN, or the agent
+pushing a continuous stream up — which is infrastructure and bandwidth this does
+not have. Nor can the browser be pointed straight at the shop PC even on one
+LAN: the engine's API is Basic-authenticated with a credential it generates
+locally and never sends anywhere, and shipping that credential to the cloud so a
+web page could use it would put the key to the biometric API and the live face
+feed in the server's database. That is a far worse trade than not having live
+video at head office.
+
+So head office shows the camera's **latest frame**, refreshed every 60 s. The
+agent already holds it in memory for its own stream, so it costs a memory copy
+rather than a camera round trip.
+
+### The picture only worked if you had an S3 bucket
+
+Which meant that on any deployment without object storage — every local install,
+and any self-hosted customer who does not want a bucket — `attachSnapshots`
+returned *"This system is not storing images"* for every camera, **forever**, on
+the two screens whose entire job is to show the camera. Making those screens
+picture-led is what turned a missing feature into a wall of empty tiles.
+
+`migrations/009` adds `camera_snapshots`, and the agent falls back to
+`PUT /api/agent/cameras/{camera}/snapshot` when the presigned route answers
+`images_disabled`. What makes this safe in the database when face images are
+not:
+
+- **One row per camera.** The primary key *is* the camera, so a snapshot
+  replaces its predecessor. Storage is (cameras × ~100 KB) and does not grow
+  with time or footfall. Face images grow with every visitor who ever walks in,
+  which is exactly why they stay in a bucket.
+- It is a picture of a shop floor, not a face crop bound to an identity, and it
+  carries no template.
+- `ON DELETE CASCADE` from the camera, so removing a camera removes its picture
+  with no second place to remember.
+
+Details that are not incidental:
+
+- **The bucket stays primary where one exists.** Both routes exist because they
+  are right for different deployments, not because one supersedes the other —
+  a presigned PUT never passes the bytes through the API at all, which is what
+  makes it the right route at estate scale.
+- **The fallback is chosen by a sentinel (`bridge.ErrImagesOff`), never by
+  matching the message.** It decides which of two routes to take; getting it
+  wrong from prose somebody later rewords would silently stop every camera
+  picture in the estate.
+- **The camera is resolved by (site_id, camera_id) inside the INSERT**, so an
+  agent cannot store a picture against another site's camera. The tenant and
+  site come from the agent's credential, never the request.
+- **`snapshot_at` is written in the same transaction as the bytes.** It is what
+  tells the camera list a picture exists; set apart, a camera could advertise
+  one that is not there, which renders as a broken image on the one screen
+  meant to show it.
+- **JPEG is verified from the magic bytes, not the Content-Type header**, and
+  the body is bounded by `MaxBytesReader` at 2 MB. This endpoint stores what it
+  is handed and serves it back to a browser, so the one thing it must not become
+  is a way to park arbitrary content under a URL this server will serve.
+- **The read is session-authenticated, not a signed link.** There is no third
+  party to delegate to — the bytes are in our own database — and minting an
+  unauthenticated URL so that `<img src>` could use it would add a way to reach
+  a photograph of somebody's shop floor with no session at all.
+
+That last decision has a front-end consequence, and it is why `Shot.jsx` exists:
+**an `<img>` cannot send an Authorization header.** A presigned bucket URL is
+absolute and carries its own signature, so a plain `src` loads it; a relative
+URL served by this server has to be fetched with the session and handed over as
+an object URL. `useAuthedImage` keys on the URL string rather than the
+`snapshot` object — which is a fresh object on every poll, so an effect
+depending on it would re-fetch ~90 KB per camera every few seconds — and revokes
+the object URL on cleanup, or a screen left open all afternoon holds hundreds of
+copies of the same photograph.
+
+Verified against the real office camera with no object storage configured: a
+90,587-byte frame stored in Postgres, served as `image/jpeg` to a signed-in
+user, **401 without a session**, and rendered on both the Cameras and Shops
+cards.