Investigation: add durable private bookmarks

db/migrations/0064_add_investigation_bookmarks.sql

@@ -0,0 +1,45 @@
+-- Durable, owner-private investigation review bookmarks. A bookmark captures
+-- navigation state only; it does not protect or hold recording media.
+
+-- migrate:up
+
+CREATE TABLE investigation_bookmarks (
+    uuid TEXT PRIMARY KEY,
+    owner_user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,
+    title TEXT NOT NULL,
+    note TEXT NOT NULL DEFAULT '',
+    start_time INTEGER NOT NULL,
+    end_time INTEGER NOT NULL,
+    cursor_time INTEGER NOT NULL,
+    primary_camera_uuid TEXT NOT NULL,
+    filters_json TEXT NOT NULL DEFAULT '{}',
+    representative_result_json TEXT,
+    revision INTEGER NOT NULL DEFAULT 1,
+    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+    updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+    CHECK (end_time > start_time),
+    CHECK (cursor_time >= start_time AND cursor_time <= end_time)
+);
+
+CREATE INDEX idx_investigation_bookmarks_owner_updated
+ON investigation_bookmarks(owner_user_id, updated_at DESC, uuid);
+
+CREATE TABLE investigation_bookmark_cameras (
+    bookmark_uuid TEXT NOT NULL
+        REFERENCES investigation_bookmarks(uuid) ON DELETE CASCADE,
+    camera_uuid TEXT NOT NULL,
+    sort_order INTEGER NOT NULL,
+    PRIMARY KEY (bookmark_uuid, camera_uuid),
+    UNIQUE (bookmark_uuid, sort_order)
+);
+
+CREATE INDEX idx_investigation_bookmark_cameras_camera
+ON investigation_bookmark_cameras(camera_uuid, bookmark_uuid);
+
+-- migrate:down
+
+DROP INDEX IF EXISTS idx_investigation_bookmark_cameras_camera;
+DROP TABLE IF EXISTS investigation_bookmark_cameras;
+DROP INDEX IF EXISTS idx_investigation_bookmarks_owner_updated;
+DROP TABLE IF EXISTS investigation_bookmarks;
+SELECT 1;

docs/API.md

@@ -1045,6 +1045,59 @@ queue bound concurrent generation; a busy server returns `503` with
 `Retry-After: 2`. Deleting a recording also removes its arbitrary-offset cache
 entries.
 
+#### Durable investigation bookmarks
+
+```
+GET    /api/investigation-bookmarks
+POST   /api/investigation-bookmarks
+GET    /api/investigation-bookmarks/{bookmark_uuid}
+PUT    /api/investigation-bookmarks/{bookmark_uuid}
+DELETE /api/investigation-bookmarks/{bookmark_uuid}
+```
+
+Bookmarks are private to the authenticated user and restore an investigation's
+camera order, UTC window, shared cursor, primary camera, filters, region, and an
+optional representative result. They are navigation aids only:
+`holds_recordings` is always `false`, so saving a bookmark does not protect
+media from retention or deletion. Use the recording protection endpoints when
+media must be retained.
+
+Create accepts one through 16 camera UUIDs and a window of at most 31 days:
+
+```json
+{
+  "title": "Loading bay handoff",
+  "note": "Review before the morning shift",
+  "camera_uuids": ["0192a7f0-4f43-4a1d-9e1c-d6947677f145"],
+  "start_time": 1787529600,
+  "end_time": 1787533200,
+  "cursor_time": 1787531400,
+  "primary_camera_uuid": "0192a7f0-4f43-4a1d-9e1c-d6947677f145",
+  "filters": {
+    "event_type": "detection",
+    "label": "person",
+    "min_confidence": 0.75
+  },
+  "representative_result": {
+    "result_id": "detection:482",
+    "camera_uuid": "0192a7f0-4f43-4a1d-9e1c-d6947677f145",
+    "start_time": 1787531400
+  }
+}
+```
+
+The service stores only a bounded whitelist of investigation fields; request
+credentials, media URLs, and arbitrary result data are not retained. Every
+list, read, update, delete, and reopen re-evaluates `recordings.replay` for all
+saved cameras using current policy. List responses omit bookmarks that are no
+longer fully visible. Direct access returns `403` for a current policy denial
+or `404` if a saved camera no longer exists.
+
+`PUT` changes only `title` and `note` and requires the last observed positive
+`revision`. `DELETE` accepts a JSON body containing the same `revision`.
+Stale changes return `409`. Create, update, and delete outcomes are written to
+the audit history. Demo mode returns an empty list and rejects mutations.
+
 ### Fleet Query and Selectors
 
 #### Query Cameras

include/database/db_embedded_migrations.h

@@ -1279,6 +1279,36 @@ static const char migration_0063_up[] =
 static const char migration_0063_down[] =
     "SELECT 1;";
 
+static const char migration_0064_up[] =
+    "CREATE TABLE investigation_bookmarks ("
+    "uuid TEXT PRIMARY KEY,"
+    "owner_user_id INTEGER REFERENCES users(id) ON DELETE CASCADE,"
+    "title TEXT NOT NULL,note TEXT NOT NULL DEFAULT '',"
+    "start_time INTEGER NOT NULL,end_time INTEGER NOT NULL,"
+    "cursor_time INTEGER NOT NULL,primary_camera_uuid TEXT NOT NULL,"
+    "filters_json TEXT NOT NULL DEFAULT '{}',"
+    "representative_result_json TEXT,revision INTEGER NOT NULL DEFAULT 1,"
+    "created_at INTEGER NOT NULL DEFAULT (strftime('%s','now')) ,"
+    "updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now')) ,"
+    "CHECK (end_time > start_time),"
+    "CHECK (cursor_time >= start_time AND cursor_time <= end_time));"
+    "CREATE INDEX idx_investigation_bookmarks_owner_updated "
+    "ON investigation_bookmarks(owner_user_id,updated_at DESC,uuid);"
+    "CREATE TABLE investigation_bookmark_cameras ("
+    "bookmark_uuid TEXT NOT NULL REFERENCES investigation_bookmarks(uuid) "
+    "ON DELETE CASCADE,camera_uuid TEXT NOT NULL,sort_order INTEGER NOT NULL,"
+    "PRIMARY KEY (bookmark_uuid,camera_uuid),"
+    "UNIQUE (bookmark_uuid,sort_order));"
+    "CREATE INDEX idx_investigation_bookmark_cameras_camera "
+    "ON investigation_bookmark_cameras(camera_uuid,bookmark_uuid);";
+
+static const char migration_0064_down[] =
+    "DROP INDEX IF EXISTS idx_investigation_bookmark_cameras_camera;"
+    "DROP TABLE IF EXISTS investigation_bookmark_cameras;"
+    "DROP INDEX IF EXISTS idx_investigation_bookmarks_owner_updated;"
+    "DROP TABLE IF EXISTS investigation_bookmarks;"
+    "SELECT 1;";
+
 static const migration_t embedded_migrations_data[] = {
     {
         .version = "0001",
@@ -1721,8 +1751,15 @@ static const migration_t embedded_migrations_data[] = {
         .sql_down = migration_0063_down,
         .is_embedded = true
     },
+    {
+        .version = "0064",
+        .description = "add_investigation_bookmarks",
+        .sql_up = migration_0064_up,
+        .sql_down = migration_0064_down,
+        .is_embedded = true
+    },
 };
 
-#define EMBEDDED_MIGRATIONS_COUNT 63
+#define EMBEDDED_MIGRATIONS_COUNT 64
 
 #endif /* DB_EMBEDDED_MIGRATIONS_H */

include/database/db_investigation_bookmarks.h

@@ -0,0 +1,59 @@
+#ifndef LIGHTNVR_DB_INVESTIGATION_BOOKMARKS_H
+#define LIGHTNVR_DB_INVESTIGATION_BOOKMARKS_H
+
+#include <stdint.h>
+
+#include "core/config.h"
+
+#define INVESTIGATION_BOOKMARK_TITLE_MAX 128
+#define INVESTIGATION_BOOKMARK_NOTE_MAX 2048
+#define INVESTIGATION_BOOKMARK_FILTERS_MAX 4096
+#define INVESTIGATION_BOOKMARK_RESULT_MAX 2048
+#define INVESTIGATION_BOOKMARK_MAX_CAMERAS 16
+#define INVESTIGATION_BOOKMARK_MAX_PER_OWNER 256
+
+typedef struct {
+    char uuid[CAMERA_UUID_STRING_SIZE];
+    int64_t owner_user_id;
+    char title[INVESTIGATION_BOOKMARK_TITLE_MAX];
+    char note[INVESTIGATION_BOOKMARK_NOTE_MAX];
+    int64_t start_time;
+    int64_t end_time;
+    int64_t cursor_time;
+    char primary_camera_uuid[CAMERA_UUID_STRING_SIZE];
+    char filters_json[INVESTIGATION_BOOKMARK_FILTERS_MAX];
+    char representative_result_json[INVESTIGATION_BOOKMARK_RESULT_MAX];
+    int camera_count;
+    int64_t revision;
+    int64_t created_at;
+    int64_t updated_at;
+} investigation_bookmark_t;
+
+typedef enum {
+    DB_INVESTIGATION_BOOKMARK_OK = 0,
+    DB_INVESTIGATION_BOOKMARK_NOT_FOUND = -1,
+    DB_INVESTIGATION_BOOKMARK_INVALID = -2,
+    DB_INVESTIGATION_BOOKMARK_STALE = -3,
+    DB_INVESTIGATION_BOOKMARK_LIMIT = -4,
+    DB_INVESTIGATION_BOOKMARK_ERROR = -5
+} db_investigation_bookmark_result_t;
+
+int db_investigation_bookmark_count(int64_t owner_user_id);
+int db_investigation_bookmark_list(
+    int64_t owner_user_id, investigation_bookmark_t *bookmarks,
+    int max_count);
+db_investigation_bookmark_result_t db_investigation_bookmark_get(
+    int64_t owner_user_id, const char *uuid,
+    investigation_bookmark_t *bookmark);
+int db_investigation_bookmark_list_cameras(
+    const char *bookmark_uuid,
+    char camera_uuids[][CAMERA_UUID_STRING_SIZE], int max_count);
+db_investigation_bookmark_result_t db_investigation_bookmark_create(
+    investigation_bookmark_t *bookmark,
+    const char camera_uuids[][CAMERA_UUID_STRING_SIZE], int camera_count);
+db_investigation_bookmark_result_t db_investigation_bookmark_update_metadata(
+    investigation_bookmark_t *bookmark, int64_t expected_revision);
+db_investigation_bookmark_result_t db_investigation_bookmark_delete(
+    int64_t owner_user_id, const char *uuid, int64_t expected_revision);
+
+#endif /* LIGHTNVR_DB_INVESTIGATION_BOOKMARKS_H */

include/web/api_handlers_investigation_bookmarks.h

@@ -0,0 +1,17 @@
+#ifndef LIGHTNVR_API_HANDLERS_INVESTIGATION_BOOKMARKS_H
+#define LIGHTNVR_API_HANDLERS_INVESTIGATION_BOOKMARKS_H
+
+#include "web/request_response.h"
+
+void handle_get_investigation_bookmarks(const http_request_t *req,
+                                        http_response_t *res);
+void handle_post_investigation_bookmark(const http_request_t *req,
+                                        http_response_t *res);
+void handle_get_investigation_bookmark(const http_request_t *req,
+                                       http_response_t *res);
+void handle_put_investigation_bookmark(const http_request_t *req,
+                                       http_response_t *res);
+void handle_delete_investigation_bookmark(const http_request_t *req,
+                                          http_response_t *res);
+
+#endif /* LIGHTNVR_API_HANDLERS_INVESTIGATION_BOOKMARKS_H */