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.

agent/pkg/cameras/cameras.go

@@ -29,7 +29,14 @@ type Engine interface {
 type Cloud interface {
 	Desired(ctx context.Context) ([]Desired, error)
 	Report(ctx context.Context, rep Report) error
+	// UploadSnapshot puts a JPEG in object storage and names it. Used for the
+	// placement check's proof picture, which is transient.
 	UploadSnapshot(ctx context.Context, jpeg []byte) (key string, err error)
+	// PutSnapshot gets a camera's latest frame to head office by whichever
+	// route this deployment has - the bucket, or the server itself when there
+	// is none. An empty key means the server already stored it, so the state
+	// report has nothing to carry.
+	PutSnapshot(ctx context.Context, cameraID string, jpeg []byte) (key string, err error)
 }
 
 // Local is a camera as the engine holds it.
@@ -252,7 +259,9 @@ func (s *Syncer) reportWith(ctx context.Context, adopt []Desired) {
 			// camera is down matters far more than having a picture of it,
 			// and the picture is the part most likely to fail.
 			if jpeg, err := s.Engine.Snapshot(ctx, c.ID); err == nil && len(jpeg) > 0 {
-				if key, err := s.Cloud.UploadSnapshot(ctx, jpeg); err == nil {
+				// An empty key is not a failure: it means this deployment has
+				// no object storage and the server stored the picture itself.
+				if key, err := s.Cloud.PutSnapshot(ctx, c.ID, jpeg); err == nil {
 					st.SnapshotKey = key
 				} else {
 					s.logf("camera %s: snapshot upload failed: %v", c.ID, err)

agent/pkg/cameras/cameras_test.go

@@ -59,6 +59,10 @@ type fakeCloud struct {
 	reports    []Report
 	uploads    int
 	uploadErr  error
+	// direct records the cameras whose picture went to the server itself
+	// rather than to object storage.
+	direct     []string
+	directOnly bool
 }
 
 func (f *fakeCloud) Desired(context.Context) ([]Desired, error) {
@@ -68,6 +72,20 @@ func (f *fakeCloud) Report(_ context.Context, r Report) error {
 	f.reports = append(f.reports, r)
 	return nil
 }
+
+// PutSnapshot mirrors the real client: the bucket when there is one, the
+// server itself when there is not.
+func (f *fakeCloud) PutSnapshot(ctx context.Context, cameraID string, jpeg []byte) (string, error) {
+	if f.directOnly {
+		if f.uploadErr != nil {
+			return "", f.uploadErr
+		}
+		f.direct = append(f.direct, cameraID)
+		return "", nil
+	}
+	return f.UploadSnapshot(ctx, jpeg)
+}
+
 func (f *fakeCloud) UploadSnapshot(context.Context, []byte) (string, error) {
 	if f.uploadErr != nil {
 		return "", f.uploadErr
@@ -239,3 +257,28 @@ func TestAnEngineThatIsNotRunningIsNotAnError(t *testing.T) {
 		t.Fatal("reported state it could not have observed")
 	}
 }
+
+// A deployment with no object storage must still get its picture to head
+// office. Before this, the camera screen said "This system is not storing
+// images" for every camera, forever - on the one screen whose entire job is to
+// show the camera.
+func TestASnapshotStillReachesHeadOfficeWithNoObjectStorage(t *testing.T) {
+	e := newEngine(Local{ID: "entrance", Connected: true})
+	c := &fakeCloud{directOnly: true}
+	syncer(e, c).Once(context.Background())
+
+	if len(c.direct) != 1 || c.direct[0] != "entrance" {
+		t.Fatalf("the picture did not reach the server: %v", c.direct)
+	}
+	if len(c.reports) == 0 || len(c.reports[0].State) != 1 {
+		t.Fatalf("no state was reported: %+v", c.reports)
+	}
+	// Empty, and that is the point: there is no object to name. A key here
+	// would have head office try to presign a bucket it does not have.
+	if key := c.reports[0].State[0].SnapshotKey; key != "" {
+		t.Fatalf("the direct route reported an object key %q", key)
+	}
+	if !c.reports[0].State[0].Connected {
+		t.Error("connected state was lost")
+	}
+}

agent/pkg/cameras/clients.go

@@ -4,12 +4,15 @@ import (
 	"bytes"
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
 	"net/http"
 	"net/url"
 	"strings"
 	"time"
+
+	"github.com/loyaly/behavision-agent/pkg/bridge"
 )
 
 // EngineClient talks to the recognition engine on this PC's loopback.
@@ -192,6 +195,64 @@ func (c *CloudClient) UploadSnapshot(ctx context.Context, jpeg []byte) (string,
 	return c.Upload(ctx, jpeg)
 }
 
+// PutSnapshot gets a camera's latest frame to head office by whichever route
+// that deployment has.
+//
+// The bucket first: a presigned PUT goes straight to object storage and never
+// passes through the API, which is what makes it the right route at estate
+// scale. When there is no bucket the picture goes to the server itself, which
+// stores one row per camera. Without this second route head office reported
+// "This system is not storing images" for every camera forever, on the screen
+// whose entire job is to show the camera.
+//
+// The returned key is empty for the direct route - there is no object to name -
+// and the server records the picture as it stores it, so the state report has
+// nothing to carry.
+func (c *CloudClient) PutSnapshot(ctx context.Context, cameraID string, jpeg []byte) (string, error) {
+	if c.Upload != nil {
+		key, err := c.Upload(ctx, jpeg)
+		if err == nil {
+			return key, nil
+		}
+		// A bucket that is configured here but disabled at the server is the
+		// ordinary case on a self-hosted install: fall through rather than
+		// giving up, and let the direct route decide.
+		if !isImagesDisabled(err) {
+			return "", err
+		}
+	}
+	return "", c.putSnapshotDirect(ctx, cameraID, jpeg)
+}
+
+func (c *CloudClient) putSnapshotDirect(ctx context.Context, cameraID string, jpeg []byte) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut,
+		c.Base+"/api/agent/cameras/"+url.PathEscape(cameraID)+"/snapshot",
+		bytes.NewReader(jpeg))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Authorization", "Bearer "+c.Token)
+	req.Header.Set("Content-Type", "image/jpeg")
+	resp, err := c.Client.Do(req)
+	if err != nil {
+		return err
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("head office: %s", resp.Status)
+	}
+	return nil
+}
+
+// isImagesDisabled recognises the server saying it has no object storage.
+//
+// A sentinel, not a string match on the message: this decides whether to take a
+// completely different route, and getting it wrong from prose that somebody
+// later rewords would silently stop every camera picture in the estate.
+func isImagesDisabled(err error) bool {
+	return errors.Is(err, bridge.ErrImagesOff)
+}
+
 // ---------------------------------------------------------------- probing
 
 // Test opens the candidate stream once, without saving it.

server/internal/api/api.go

@@ -65,6 +65,10 @@ type Store interface {
 	// reachable only with that site's own agent token.
 	AgentCameras(ctx context.Context, siteID string) ([]AgentCamera, error)
 	ApplyAgentReport(ctx context.Context, clientID, siteID string, rep AgentCameraReport) error
+	// Camera pictures held by this server, for deployments with no object
+	// storage. Where a bucket is configured neither of these is called.
+	PutCameraSnapshot(ctx context.Context, clientID, siteID, cameraID string, jpeg []byte) error
+	CameraSnapshot(ctx context.Context, clientID, cameraID string) ([]byte, time.Time, error)
 
 	// --- claiming a shop PC ---
 	IssueEnrolmentCode(ctx context.Context, clientID, siteID, actorID,
@@ -192,6 +196,7 @@ func (s *Server) Routes() *http.ServeMux {
 	mux.HandleFunc("POST /api/sites/{site}/cameras", s.authed(s.handleCreateCamera))
 	mux.HandleFunc("PATCH /api/cameras/{id}", s.authed(s.handleUpdateCamera))
 	mux.HandleFunc("DELETE /api/cameras/{id}", s.authed(s.handleDeleteCamera))
+	mux.HandleFunc("GET /api/cameras/{id}/snapshot.jpg", s.authed(s.handleGetSnapshot))
 	// Prove a camera works: "connection" asks whether the shop PC can open the
 	// stream, "placement" asks whether somebody walking past produces a view
 	// good enough to recognise. Two questions, because a camera passes the
@@ -235,6 +240,8 @@ func (s *Server) Routes() *http.ServeMux {
 	// What this shop PC should be running, and what it reports back.
 	mux.HandleFunc("GET /api/agent/cameras", s.agentAuthed(s.handleAgentCameras))
 	mux.HandleFunc("POST /api/agent/cameras", s.agentAuthed(s.handleAgentCameraReport))
+	mux.HandleFunc("PUT /api/agent/cameras/{camera}/snapshot",
+		s.agentAuthed(s.handlePutSnapshot))
 	mux.HandleFunc("GET /api/agent/checks", s.agentAuthed(s.handleAgentChecks))
 	mux.HandleFunc("POST /api/agent/checks", s.agentAuthed(s.handleAgentCheckResult))
 
@@ -408,6 +415,11 @@ func looksLikeUUID(s string) bool {
 // without importing the store package.
 var ErrNoSecrets = errors.New("this server has no encryption key, so camera passwords cannot be stored")
 
+// ErrNoSnapshot means a camera has no stored picture. An ordinary state - a
+// camera added a minute ago has none - so it is reported as absence, never as
+// a failure.
+var ErrNoSnapshot = errors.New("no snapshot for this camera")
+
 // BlobStore is what the API needs from object storage. Declared here and
 // implemented by internal/blob, so the handlers can be tested without a bucket
 // and so a deployment with images switched off is a nil field rather than a

server/internal/api/fake_test.go

@@ -19,6 +19,14 @@ import (
 // live - which tenant, which message on failure, what is echoed back - and
 // those are exactly what a real database would make slow and awkward to test.
 type fakeStore struct {
+	// Camera pictures held by the server, for a deployment with no bucket.
+	// Keyed as written by PutCameraSnapshot (by camera_id) and as read by
+	// CameraSnapshot ("client/camera"), so a test has to say which it means.
+	snapshots          map[string][]byte
+	snapshotRejects    bool
+	lastSnapshotClient string
+	lastSnapshotSite   string
+
 	mu sync.Mutex
 
 	users     map[string]UserRecord // by lower-cased email
@@ -586,3 +594,31 @@ func (b *fakeBlob) Delete(_ context.Context, key string) error {
 	b.deleted = append(b.deleted, key)
 	return nil
 }
+
+// ------------------------------------------------------- camera snapshots --
+
+func (f *fakeStore) PutCameraSnapshot(_ context.Context,
+	clientID, siteID, cameraID string, jpeg []byte) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.snapshots == nil {
+		f.snapshots = map[string][]byte{}
+	}
+	if f.snapshotRejects {
+		return ErrNoSnapshot
+	}
+	f.lastSnapshotClient, f.lastSnapshotSite = clientID, siteID
+	f.snapshots[cameraID] = append([]byte(nil), jpeg...)
+	return nil
+}
+
+func (f *fakeStore) CameraSnapshot(_ context.Context, clientID, cameraID string) (
+	[]byte, time.Time, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	img, ok := f.snapshots[clientID+"/"+cameraID]
+	if !ok {
+		return nil, time.Time{}, ErrNoSnapshot
+	}
+	return img, time.Unix(1756900000, 0).UTC(), nil
+}

server/internal/api/handlers_cameras.go

@@ -49,10 +49,23 @@ func (s *Server) attachSnapshots(cams []Camera) {
 		key := cams[i].Snapshot.Key
 		cams[i].Snapshot.Key = ""
 		switch {
-		case s.Blob == nil:
-			cams[i].Snapshot.Reason = "This system is not storing images."
+		case key == "" && cams[i].SnapshotAt != "":
+			// Held by this server, because the deployment has no object
+			// storage. Served from an endpoint rather than a signed link:
+			// there is no third party to delegate to, the bytes are in our own
+			// database, and an unauthenticated URL to somebody's shop floor
+			// would be a new way in for no gain.
+			cams[i].Snapshot = Image{
+				Available: true,
+				URL:       "/api/cameras/" + cams[i].ID + "/snapshot.jpg",
+				ExpiresIn: int(snapshotTTL.Seconds()),
+			}
 		case key == "":
 			cams[i].Snapshot.Reason = "No picture from this camera yet."
+		case s.Blob == nil:
+			// A key from a bucket this server can no longer reach. Distinct
+			// from "no picture yet": one is waiting, the other is misconfigured.
+			cams[i].Snapshot.Reason = "This system is not storing images."
 		default:
 			url, err := s.Blob.PresignGet(key, snapshotTTL)
 			if err != nil {

server/internal/api/handlers_snapshots.go

@@ -0,0 +1,118 @@
+package api
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"time"
+)
+
+// maxSnapshotBytes caps what a shop PC may store per camera.
+//
+// A camera frame downscaled to 1280 px is ~100 KB; 2 MB is generous for a
+// 4K still and small enough that a misbehaving or compromised agent cannot use
+// this endpoint as free storage. One row per camera means it cannot accumulate
+// either - the cap is about a single request, the primary key about the total.
+const maxSnapshotBytes = 2 << 20
+
+// snapshotMaxAge is how long a browser may reuse a camera picture. The agent
+// refreshes them every 60 s, so anything longer shows a stale shop floor and
+// anything shorter re-fetches a picture that has not changed.
+const snapshotMaxAge = 30 * time.Second
+
+// handlePutSnapshot stores the latest frame from one of this site's cameras.
+//
+// This is the path for a deployment with NO object storage. Where a bucket is
+// configured the agent keeps using the presigned-URL route, which never puts a
+// picture through this process at all; both exist because they are right for
+// different deployments, not because one supersedes the other.
+//
+// The body is the JPEG itself rather than JSON with base64: it avoids a third
+// of the bytes and a decode step, and there is exactly one thing being sent.
+func (s *Server) handlePutSnapshot(w http.ResponseWriter, r *http.Request, ap AgentPrincipal) {
+	cameraID := r.PathValue("camera")
+	if cameraID == "" {
+		writeErr(w, http.StatusNotFound, "not_found", "No such camera.")
+		return
+	}
+
+	// http.MaxBytesReader, not a Content-Length check: a length header is
+	// whatever the client says it is, and this has to bound what is actually
+	// read into memory.
+	body, err := io.ReadAll(http.MaxBytesReader(w, r.Body, maxSnapshotBytes+1))
+	if err != nil {
+		writeErr(w, http.StatusRequestEntityTooLarge, "too_large",
+			fmt.Sprintf("A snapshot must be under %d KB.", maxSnapshotBytes/1024))
+		return
+	}
+	if len(body) > maxSnapshotBytes {
+		writeErr(w, http.StatusRequestEntityTooLarge, "too_large",
+			fmt.Sprintf("A snapshot must be under %d KB.", maxSnapshotBytes/1024))
+		return
+	}
+	// Checked against the bytes, not the Content-Type header. This endpoint
+	// stores whatever it is given and hands it back to a browser later, so the
+	// one thing it must not become is a way to park arbitrary content under a
+	// URL this server will serve.
+	if !isJPEG(body) {
+		badRequest(w, "a snapshot must be a JPEG")
+		return
+	}
+
+	switch err := s.Store.PutCameraSnapshot(r.Context(),
+		ap.ClientID, ap.SiteID, cameraID, body); {
+	case err == nil:
+		w.WriteHeader(http.StatusNoContent)
+	case errors.Is(err, ErrNoSnapshot):
+		// Head office has not adopted this camera yet. Not the agent's fault
+		// and not worth retrying: the next sync adopts it.
+		writeErr(w, http.StatusNotFound, "not_found",
+			"That camera is not set up at head office yet.")
+	default:
+		s.serverError(w, "store snapshot", err)
+	}
+}
+
+// handleGetSnapshot serves a camera's stored picture to a signed-in user.
+//
+// Deliberately NOT a signed link like the bucket path: there is no third party
+// to delegate to here, the bytes are in this server's own database, and minting
+// a URL that works without a session in order to serve them would be adding an
+// unauthenticated path to reach a picture of somebody's shop floor for no gain.
+func (s *Server) handleGetSnapshot(w http.ResponseWriter, r *http.Request) {
+	p := PrincipalFrom(r.Context())
+	id := r.PathValue("id")
+	if !looksLikeUUID(id) {
+		writeErr(w, http.StatusNotFound, "not_found", "No such camera.")
+		return
+	}
+	img, at, err := s.Store.CameraSnapshot(r.Context(), p.ClientID, id)
+	if errors.Is(err, ErrNoSnapshot) {
+		writeErr(w, http.StatusNotFound, "no_image", "No picture from this camera yet.")
+		return
+	}
+	if err != nil {
+		s.serverError(w, "read snapshot", err)
+		return
+	}
+	w.Header().Set("Content-Type", "image/jpeg")
+	w.Header().Set("Content-Length", strconv.Itoa(len(img)))
+	w.Header().Set("Cache-Control", "private, max-age="+
+		strconv.Itoa(int(snapshotMaxAge.Seconds())))
+	w.Header().Set("Last-Modified", at.UTC().Format(http.TimeFormat))
+	// A picture of a shop floor is not something to hand to another origin's
+	// script, and nothing here needs to.
+	w.Header().Set("X-Content-Type-Options", "nosniff")
+	w.WriteHeader(http.StatusOK)
+	_, _ = w.Write(img)
+}
+
+// isJPEG checks the magic bytes: SOI marker at the front, EOI at the back.
+func isJPEG(b []byte) bool {
+	if len(b) < 4 {
+		return false
+	}
+	return b[0] == 0xFF && b[1] == 0xD8 && b[2] == 0xFF
+}

server/internal/api/snapshots_test.go

@@ -0,0 +1,102 @@
+package api
+
+import (
+	"bytes"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// A minimal but real JPEG header: SOI + APP0. The endpoint checks the bytes,
+// not the Content-Type header, so a test that sends anything else is not
+// testing the same path a shop PC uses.
+func jpegBytes(padTo int) []byte {
+	b := []byte{0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 'J', 'F', 'I', 'F', 0}
+	for len(b) < padTo {
+		b = append(b, 0x00)
+	}
+	return append(b, 0xFF, 0xD9)
+}
+
+func TestAnAgentCanStoreItsCameraPicture(t *testing.T) {
+	srv, fs := newServer(t)
+	fs.addAgent("agent-token", AgentPrincipal{ClientID: "client-1", SiteID: "site-1"})
+
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut,
+		"/api/agent/cameras/entrance/snapshot", bytes.NewReader(jpegBytes(64)))
+	req.Header.Set("Authorization", "Bearer agent-token")
+	srv.Routes().ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusNoContent {
+		t.Fatalf("status %d: %s", rr.Code, rr.Body)
+	}
+	if len(fs.snapshots["entrance"]) == 0 {
+		t.Fatal("nothing was stored")
+	}
+	// The tenant and site come from the AGENT's credential, never the request.
+	// A camera id a caller can set must not be able to choose whose camera it
+	// decorates.
+	if fs.lastSnapshotClient != "client-1" || fs.lastSnapshotSite != "site-1" {
+		t.Fatalf("stored against %s/%s", fs.lastSnapshotClient, fs.lastSnapshotSite)
+	}
+}
+
+// This endpoint stores whatever it is handed and serves it back to a browser
+// later, so the one thing it must not become is a way to park arbitrary content
+// under a URL this server will serve.
+func TestOnlyAJPEGIsAccepted(t *testing.T) {
+	srv, fs := newServer(t)
+	fs.addAgent("agent-token", AgentPrincipal{ClientID: "client-1", SiteID: "site-1"})
+
+	for _, body := range []string{
+		"<html><script>alert(1)</script></html>",
+		"GIF89a",
+		"",
+	} {
+		rr := httptest.NewRecorder()
+		req := httptest.NewRequest(http.MethodPut,
+			"/api/agent/cameras/entrance/snapshot", strings.NewReader(body))
+		req.Header.Set("Authorization", "Bearer agent-token")
+		// Claiming to be a JPEG must not help: the check is on the bytes.
+		req.Header.Set("Content-Type", "image/jpeg")
+		srv.Routes().ServeHTTP(rr, req)
+		if rr.Code != http.StatusBadRequest {
+			t.Fatalf("body %q was accepted with status %d", body, rr.Code)
+		}
+	}
+}
+
+// One row per camera is what makes this safe to keep in the database at all,
+// but a single oversized request still has to be bounded - it is read into
+// memory before anything else looks at it.
+func TestAnOversizedSnapshotIsRefused(t *testing.T) {
+	srv, fs := newServer(t)
+	fs.addAgent("agent-token", AgentPrincipal{ClientID: "client-1", SiteID: "site-1"})
+
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut,
+		"/api/agent/cameras/entrance/snapshot",
+		bytes.NewReader(jpegBytes(maxSnapshotBytes+1024)))
+	req.Header.Set("Authorization", "Bearer agent-token")
+	srv.Routes().ServeHTTP(rr, req)
+
+	if rr.Code != http.StatusRequestEntityTooLarge {
+		t.Fatalf("status %d", rr.Code)
+	}
+	if len(fs.snapshots) != 0 {
+		t.Fatal("an oversized snapshot was stored anyway")
+	}
+}
+
+func TestAnUnauthenticatedAgentCannotStoreAPicture(t *testing.T) {
+	srv, _ := newServer(t)
+	rr := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodPut,
+		"/api/agent/cameras/entrance/snapshot", bytes.NewReader(jpegBytes(64)))
+	srv.Routes().ServeHTTP(rr, req)
+	if rr.Code != http.StatusUnauthorized {
+		t.Fatalf("status %d", rr.Code)
+	}
+}

server/internal/store/api_snapshots.go

@@ -0,0 +1,84 @@
+package store
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+)
+
+// ErrNoSnapshot means this camera has no stored picture. It is an ordinary
+// state - a camera added a minute ago has none - so callers report it as
+// absence rather than as a failure.
+var ErrNoSnapshot = errors.New("no snapshot for this camera")
+
+// PutCameraSnapshot stores the latest frame from one of a site's cameras.
+//
+// The camera is resolved by (site_id, camera_id) IN THE INSERT, so an agent
+// physically cannot store a picture against another site's camera even if it
+// sends one - the same rule as every other agent-authenticated write here.
+// `camera_id` is what the ENGINE knows the camera by, because that is the only
+// name the shop PC has.
+func (s *Store) PutCameraSnapshot(ctx context.Context,
+	clientID, siteID, cameraID string, jpeg []byte) error {
+
+	tx, err := s.pool.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer func() { _ = tx.Rollback(context.WithoutCancel(ctx)) }()
+
+	var id string
+	err = tx.QueryRow(ctx, `
+		SELECT id::text FROM site_cameras
+		 WHERE site_id = $1::uuid AND camera_id = $2 AND deleted_at IS NULL`,
+		siteID, cameraID).Scan(&id)
+	if errors.Is(err, pgx.ErrNoRows) {
+		// Head office has not been told about this camera yet, or it was
+		// removed. Neither is an error the agent can act on: the next sync
+		// adopts it and the snapshot after that lands.
+		return ErrNoSnapshot
+	}
+	if err != nil {
+		return err
+	}
+
+	if _, err := tx.Exec(ctx, `
+		INSERT INTO camera_snapshots (camera_id, client_id, site_id, image, bytes, captured_at)
+		VALUES ($1::uuid, $2::uuid, $3::uuid, $4, $5, now())
+		ON CONFLICT (camera_id) DO UPDATE
+		   SET image = EXCLUDED.image, bytes = EXCLUDED.bytes,
+		       captured_at = EXCLUDED.captured_at`,
+		id, clientID, siteID, jpeg, len(jpeg)); err != nil {
+		return fmt.Errorf("store snapshot: %w", err)
+	}
+
+	// snapshot_at is what tells the camera list a picture exists at all, and it
+	// is written in the SAME transaction as the bytes. Set apart, a camera
+	// could advertise a picture that is not there - which renders as a broken
+	// image on the one screen whose job is to show the camera.
+	if _, err := tx.Exec(ctx, `
+		UPDATE site_cameras SET snapshot_at = now() WHERE id = $1::uuid`,
+		id); err != nil {
+		return err
+	}
+	return tx.Commit(ctx)
+}
+
+// CameraSnapshot returns a camera's stored picture, scoped to the tenant.
+func (s *Store) CameraSnapshot(ctx context.Context, clientID, cameraID string) (
+	[]byte, time.Time, error) {
+
+	var img []byte
+	var at time.Time
+	err := s.pool.QueryRow(ctx, `
+		SELECT image, captured_at FROM camera_snapshots
+		 WHERE camera_id = $1::uuid AND client_id = $2::uuid`,
+		cameraID, clientID).Scan(&img, &at)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return nil, time.Time{}, ErrNoSnapshot
+	}
+	return img, at, err
+}

server/internal/web/dist/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="color-scheme" content="dark" />
     <title>Behavision</title>
-    <script type="module" crossorigin src="/assets/index-C8M-zRAi.js"></script>
+    <script type="module" crossorigin src="/assets/index-B_gTsA07.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-pUqVBCLm.css">
   </head>
   <body>

server/migrations/009_camera_snapshots.sql

@@ -0,0 +1,45 @@
+-- The latest still frame from each camera, held by the server itself.
+--
+-- Camera snapshots already worked, through the same presigned-URL path face
+-- images use: the agent asks for a URL, PUTs the JPEG to object storage, and
+-- the server presigns a short-lived link when somebody looks. That is the right
+-- design for face images - one per visit, unbounded, and they must never touch
+-- a shop PC's disk or the server's.
+--
+-- It is the wrong design for the ONE case where a deployment has no object
+-- storage at all. Head office then reports "This system is not storing images"
+-- for every camera, forever, on a screen whose whole point is to SHOW the
+-- camera. A self-hosted customer who does not want an S3 bucket, and every
+-- local install, got a wall of empty tiles.
+--
+-- What makes this safe to put in the database, when face images are not:
+--
+--   * ONE ROW PER CAMERA. The primary key is the camera, so a snapshot
+--     replaces its predecessor. An estate's storage is (cameras x ~100 KB)
+--     and does not grow with time or with footfall. Face images grow with
+--     every visitor who ever walks in, which is why they stay in a bucket.
+--   * It is a picture of a shop floor, not a face crop attached to an
+--     identity. It carries no template and is not tied to a person.
+--   * ON DELETE CASCADE from the camera. Removing a camera removes its
+--     picture, with no second place to remember to clean up.
+--
+-- When object storage IS configured nothing changes: the bucket path stays
+-- primary and this table is not written.
+
+BEGIN;
+
+CREATE TABLE IF NOT EXISTS camera_snapshots (
+    camera_id   uuid PRIMARY KEY REFERENCES site_cameras(id) ON DELETE CASCADE,
+    -- Denormalised deliberately, like every other table here: a cross-tenant
+    -- read should require a wrong WHERE clause rather than a forgotten join.
+    client_id   uuid        NOT NULL REFERENCES clients(id) ON DELETE CASCADE,
+    site_id     uuid        NOT NULL REFERENCES sites(id)   ON DELETE CASCADE,
+    image       bytea       NOT NULL,
+    bytes       integer     NOT NULL,
+    captured_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS camera_snapshots_client_idx
+    ON camera_snapshots (client_id);
+
+COMMIT;

web/src/api.js

@@ -91,6 +91,37 @@ async function send(method, path, body, retry = true) {
     parsed?.message || `Something went wrong (${res.status}).`)
 }
 
+// fetchImage loads a picture this server holds itself, with the session's
+// bearer token, and returns an object URL an <img> can use.
+//
+// It exists because an <img src> cannot carry an Authorization header. The
+// object-storage path returns a presigned absolute URL that needs no auth,
+// which is why it worked with a plain src; a picture served from our own
+// database has no such link, and minting an unauthenticated one so that <img>
+// could use it would add a way to reach a photograph of somebody's shop floor
+// without a session - the opposite of what this path is for.
+//
+// The caller MUST revoke the returned URL when it is finished with it, or the
+// browser keeps every blob it has ever loaded for the life of the page.
+async function fetchImage(path, retry = true) {
+  const { access } = tokens()
+  const res = await fetch(path, {
+    headers: access ? { Authorization: 'Bearer ' + access } : {},
+  })
+  if (res.ok) return URL.createObjectURL(await res.blob())
+
+  let parsed = null
+  try { parsed = await res.json() } catch { /* an image endpoint may not answer json */ }
+  const code = parsed?.error || ''
+  if (code === 'token_expired' && retry) {
+    await refresh()
+    return fetchImage(path, false)
+  }
+  if (res.status === 401) clearTokens()
+  throw new ApiError(res.status, code,
+    parsed?.message || `That picture could not be loaded (${res.status}).`)
+}
+
 const qs = (params) => {
   const p = new URLSearchParams()
   for (const [k, v] of Object.entries(params || {})) {
@@ -138,6 +169,9 @@ export const api = {
   conversion: (params) => send('GET', '/api/reports/conversion' + qs(params)),
 
   cameras: () => send('GET', '/api/cameras'),
+  // A camera picture this server holds itself. Returns an object URL the
+  // caller must revoke; see fetchImage.
+  cameraSnapshot: (url) => fetchImage(url),
   createCamera: (siteID, cam) =>
     send('POST', `/api/sites/${encodeURIComponent(siteID)}/cameras`, cam),
   updateCamera: (id, cam) => send('PATCH', `/api/cameras/${encodeURIComponent(id)}`, cam),

web/src/hooks.js

@@ -1,5 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
 
+import { api } from './api.js'
+
 // usePolled runs `fn` now and every `everyMs`, and is careful about the two
 // things every screen would otherwise get wrong on its own: overlapping
 // requests when the server is slower than the interval, and setting state
@@ -40,3 +42,40 @@ export function usePolled(fn, everyMs, deps = []) {
 
   return { data, error, loading, reload: run }
 }
+
+
+// useAuthedImage loads a picture that needs the session's bearer token and
+// hands back a URL an <img> can use.
+//
+// Two things it has to get right, and both were bugs the first time something
+// like it was written elsewhere in this app:
+//
+//   * REVOKE. An object URL pins the blob in memory until it is revoked, and
+//     this component re-renders on every poll. Without the cleanup a camera
+//     screen left open for an afternoon holds hundreds of copies of the same
+//     photograph.
+//   * Key on the URL, not on the object. `snapshot` is a fresh object on every
+//     poll, so an effect depending on it would re-fetch 90 KB per camera every
+//     few seconds; the URL only changes when the picture actually does.
+export function useAuthedImage(url) {
+  const [src, setSrc] = useState(null)
+
+  useEffect(() => {
+    if (!url) { setSrc(null); return }
+    let alive = true
+    let objectURL = null
+    api.cameraSnapshot(url)
+      .then(u => {
+        if (!alive) { URL.revokeObjectURL(u); return }
+        objectURL = u
+        setSrc(u)
+      })
+      .catch(() => { if (alive) setSrc(null) })
+    return () => {
+      alive = false
+      if (objectURL) URL.revokeObjectURL(objectURL)
+    }
+  }, [url])
+
+  return src
+}

web/src/views/Cameras.jsx

@@ -1,6 +1,7 @@
 import { useState } from 'react'
 import { api } from '../api.js'
 import { usePolled } from '../hooks.js'
+import Shot from './Shot.jsx'
 import { ago, Loading, Problem } from './Sites.jsx'
 import CameraSetup from './CameraSetup.jsx'
 
@@ -114,7 +115,7 @@ function CameraCard({ cam, canEdit, onEdit }) {
              onKeyDown={e => canEdit && e.key === 'Enter' && onEdit()}>
       <div className="shot">
         {cam.snapshot?.available
-          ? <img src={cam.snapshot.url} alt={`View from ${cam.label}`} loading="lazy" />
+          ? <Shot url={cam.snapshot.url} alt={`View from ${cam.label}`} />
           : <div className="noshot">
               <span className="lens" aria-hidden="true" />
               {cam.snapshot?.reason || 'No picture yet.'}

web/src/views/Shot.jsx

@@ -0,0 +1,24 @@
+import { useAuthedImage } from '../hooks.js'
+
+// One camera picture, however this deployment stores them.
+//
+// Two shapes arrive here and they need different handling, which is exactly
+// why it is one component rather than an <img> repeated on each screen:
+//
+//   * An ABSOLUTE url is a presigned link to object storage. It carries its
+//     own signature, so a plain <img src> loads it.
+//   * A RELATIVE url is served by this server from its own database, for a
+//     deployment with no bucket. An <img> cannot send an Authorization header,
+//     so it has to be fetched with the session and handed over as an object
+//     URL. Minting an unauthenticated link instead would put a photograph of
+//     somebody's shop floor behind no session at all, which is the thing this
+//     path exists to avoid.
+export default function Shot({ url, alt }) {
+  const local = typeof url === 'string' && url.startsWith('/')
+  // Hooks cannot be called conditionally, so this always runs and simply has
+  // nothing to do when the URL is already usable.
+  const fetched = useAuthedImage(local ? url : null)
+  const src = local ? fetched : url
+  if (!src) return null
+  return <img src={src} alt={alt} loading="lazy" />
+}

web/src/views/Sites.jsx

@@ -1,6 +1,7 @@
 import { useState } from 'react'
 import { api } from '../api.js'
 import { usePolled } from '../hooks.js'
+import Shot from './Shot.jsx'
 import SiteCheck from './SiteCheck.jsx'
 
 // The estate at a glance.
@@ -134,7 +135,7 @@ function SiteCard({ site, cams, verdict, onCheck }) {
              tabIndex={0} onKeyDown={e => e.key === 'Enter' && onCheck()}>
       <div className="shot">
         {view.url
-          ? <img src={view.url} alt={`View inside ${site.name}`} loading="lazy" />
+          ? <Shot url={view.url} alt={`View inside ${site.name}`} />
           : <div className="noshot">
               <ShopMark />
               {view.reason && <span>{view.reason}</span>}