fix(video): isolate drill-down cache by principal

changelog.d/features/11369-video-bridge-drilldown-isolation.md

@@ -0,0 +1 @@
+- **feat(video bridge):** harden the optional drill-down cache substrate with exact-path broker policy, canonical principal/session/media isolation, independent retained-byte quotas, cancellation-safe commits, rejection of excess or non-canonical Base64 padding and non-JPEG/truncated media, warning-sensitive full JPEG canonicalization that strips trailing polyglot bytes, server-derived dimensions, and auditable derivation metadata; production tenant binding and multi-resolution selection remain follow-up work ([#11369](https://github.com/diegosouzapw/OmniRoute/pull/11369))

docs/openapi.yaml

@@ -5719,17 +5719,28 @@ paths:
       x-loopback-only: true
       tags: [System]
       summary: Read a bounded Video Bridge drill-down slice
-      description: Internal loopback/token-authenticated lookup into a short-lived per-session frame cache. It never downloads media or starts a subprocess; start/end and frame count only select already materialized frames.
+      description: Internal loopback/token-authenticated lookup into a short-lived cache isolated by an opaque principal, session, and media reference. It never downloads media or starts a subprocess; start/end and frame count only select already materialized, canonicalized JPEG frames whose dimensions were derived from their bytes. This cache substrate is not yet wired to the transparent Video Bridge request path and does not yet expose multi-resolution selection.
       security: []
       parameters:
+        - in: header
+          name: x-omniroute-video-bridge-principal
+          required: true
+          description: Canonical visible-ASCII, opaque non-secret principal ID; production tenant derivation is required before enabling a caller
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 256
+            pattern: "^[!-~]{1,256}$"
         - in: query
           name: sessionId
           required: true
-          schema: { type: string, maxLength: 128 }
+          description: Canonical opaque ID without surrounding whitespace
+          schema: { type: string, minLength: 1, maxLength: 128 }
         - in: query
           name: videoRef
           required: true
-          schema: { type: string, maxLength: 4096 }
+          description: Canonical opaque reference without surrounding whitespace
+          schema: { type: string, minLength: 1, maxLength: 4096 }
         - in: query
           name: start
           required: false
@@ -5743,53 +5754,102 @@ paths:
           required: false
           schema: { type: integer, minimum: 1, maximum: 16 }
       responses:
-        "200": { description: Bounded cached frame slice }
-        "403": { description: Trusted loopback/token identity required }
+        "200": { description: Bounded cached frame slice with derivation audit metadata }
+        "403": { description: Trusted loopback/token identity and principal required }
         "404": { description: Drill-down session or media key was not found }
     post:
       x-loopback-only: true
       tags: [System]
       summary: Store a bounded Video Bridge drill-down result
-      description: Internal lifecycle operation for explicitly authorized callers. The short-lived session cache is isolated by session and media reference and does not alter the primary request cost.
+      description: Internal lifecycle operation for explicitly authorized callers. The short-lived cache is isolated by principal, session, and media reference; enforces independent per-principal and global retained-byte quotas; accepts canonical Base64 only after a warning-sensitive bounded full JPEG decode/re-encode; strips trailing polyglot bytes; retains and charges only the canonical JPEG output; derives resolution from decoded bytes; and does not alter the primary request cost. The JSON wire budget includes Base64 overhead for the 32 MiB decoded-input ceiling.
       security: []
+      parameters:
+        - in: header
+          name: x-omniroute-video-bridge-principal
+          required: true
+          description: Canonical visible-ASCII, opaque non-secret principal ID; production tenant derivation is required before enabling a caller
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 256
+            pattern: "^[!-~]{1,256}$"
       requestBody:
         required: true
         content:
           application/json:
             schema:
               type: object
-              required: [sessionId, videoRef, durationSeconds, frames]
+              additionalProperties: false
+              required: [sessionId, videoRef, derivation, durationSeconds, frames]
               properties:
-                sessionId: { type: string, maxLength: 128 }
-                videoRef: { type: string, maxLength: 4096 }
+                sessionId:
+                  type: string
+                  minLength: 1
+                  maxLength: 128
+                  description: Canonical opaque ID without surrounding whitespace
+                videoRef:
+                  type: string
+                  minLength: 1
+                  maxLength: 4096
+                  description: Canonical opaque reference without surrounding whitespace
+                derivation:
+                  type: object
+                  additionalProperties: false
+                  required: [parentContentHash, policy, version]
+                  properties:
+                    parentContentHash:
+                      type: string
+                      pattern: "^sha256:[a-f0-9]{64}$"
+                    policy:
+                      type: string
+                      pattern: "^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}$"
+                    version:
+                      type: string
+                      pattern: "^[A-Za-z0-9][A-Za-z0-9._/-]{0,63}$"
                 durationSeconds: { type: number, exclusiveMinimum: 0, maximum: 600 }
                 frames:
                   type: array
                   minItems: 1
                   maxItems: 16
                   items:
                     type: object
+                    additionalProperties: false
                     required: [timestampSeconds, dataUri]
                     properties:
                       timestampSeconds: { type: number, minimum: 0 }
-                      dataUri: { type: string, pattern: "^data:image/jpeg;base64," }
+                      dataUri:
+                        type: string
+                        minLength: 27
+                        maxLength: 5592431
+                        description: Canonical Base64 data URI whose decoded bytes pass a warning-sensitive bounded full JPEG decode/re-encode; trailing bytes are discarded and width and height are derived server-side
       responses:
         "201": { description: Drill-down result stored }
-        "403": { description: Trusted loopback/token identity required }
+        "403": { description: Trusted loopback/token identity and principal required }
         "413": { description: Payload exceeds the bounded session budget }
+        "499": { description: Caller cancelled before the derivation was committed }
     delete:
       x-loopback-only: true
       tags: [System]
       summary: Delete a Video Bridge drill-down session
       security: []
       parameters:
+        - in: header
+          name: x-omniroute-video-bridge-principal
+          required: true
+          description: Canonical visible-ASCII, opaque non-secret principal ID; production tenant derivation is required before enabling a caller
+          schema:
+            type: string
+            minLength: 1
+            maxLength: 256
+            pattern: "^[!-~]{1,256}$"
         - in: query
           name: sessionId
           required: true
-          schema: { type: string, maxLength: 128 }
+          description: Canonical opaque ID without surrounding whitespace
+          schema: { type: string, minLength: 1, maxLength: 128 }
       responses:
         "200": { description: Session entries removed }
-        "403": { description: Trusted loopback/token identity required }
+        "403": { description: Trusted loopback/token identity and principal required }
 
   /api/cache/stats:
     get:

docs/security/GUARDRAILS.md

@@ -378,14 +378,39 @@ or download a second media copy; without that explicit track, it remains
 video-only.
 
 The internal `/api/modality-bridge/video/drilldown` lifecycle is a separate,
-loopback/token-authenticated cache. It stores at most 16 JPEG frames per entry,
-keeps entries isolated by session and video reference, expires them after ten
-minutes, and supports bounded `start`/`end` reads or explicit session deletion.
-Besides the per-entry limits, the cache enforces a global 256 MiB decoded-byte
-budget: least-recently-used entries are evicted until new content fits, and an
-entry larger than the whole budget is rejected outright.
-It only slices materialized frames and cannot increase the cost of the primary
-video request.
+loopback/token-authenticated cache substrate. Every operation also requires a
+canonical opaque principal ID. Before a production caller is enabled, it must
+derive that ID from the authenticated tenant and must never forward a
+client-selected value. Cache keys bind that principal to canonical session and
+video-reference IDs, store only their SHA-256-derived keys, and scope both reads
+and deletion to the same principal. The cache stores at most 16 derived JPEG
+frames per entry, expires them after ten minutes, and supports bounded
+`start`/`end` reads or explicit session deletion.
+
+Each principal is limited to 16 entries and 64 MiB of canonical JPEG data. Those
+limits are independent from the global 64-entry/256 MiB ceiling: principal quota
+pressure evicts only that principal's least-recently-used entries before global
+LRU eviction is considered. Expired entries are swept from both principal and
+global accounting on cache activity, while cancellation and validation failure do
+not commit a partial replacement.
+
+The cache rejects non-canonical Base64, excess padding, non-JPEG media, malformed or
+truncated JPEGs, and JPEGs that produce a warning during a bounded full-image `sharp`
+decode. It re-encodes each accepted image as a canonical JPEG, derives width and height
+from the decoded bytes instead of trusting caller fields, and discards any trailing
+polyglot bytes rather than retaining them. Only the bounded canonical compressed buffer
+is charged to both quotas. The JSON wire limit includes Base64 overhead for the 32 MiB
+decoded-input ceiling. Every
+stored derivation records its validated JPEG format/resolution, sampling policy,
+derivation version, creation time, server-computed content hash, and hashed parent
+reference plus the trusted caller's parent-content hash. Cancellation is checked
+between asynchronous decode/hash phases before the atomic cache commit.
+
+This tranche does not yet connect a production producer to the route and does not
+provide multi-resolution variant selection. The transparent Video Bridge request
+path therefore incurs no added work, while tenant-bound principal derivation and
+the full FU-08 multi-resolution lifecycle remain explicit follow-up work rather
+than documented as complete behavior.
 
 Frames are captioned sequentially with the configured Video model. An empty
 Video override inherits the Vision setting; if both are empty, the Vision