@agentsdock/server 1.0.7-beta.5

package/server/shared_chat_video_stream.py

@@ -0,0 +1,262 @@
+"""Bounded HTTP video streaming from an already authorized, pinned descriptor.
+
+This module does not resolve paths, read a share ledger, or open server state.
+The caller securely opens and validates a regular file and transfers exclusive
+ownership of its descriptor to SharedVideoResponse, including on init failure.
+"""
+from __future__ import annotations
+
+import os
+import re
+import stat
+import threading
+import time
+from urllib.parse import quote
+
+from starlette.concurrency import run_in_threadpool
+from starlette.responses import Response, StreamingResponse
+
+
+VIDEO_CONTENT_TYPES = frozenset({"video/mp4", "video/webm", "video/quicktime", "video/ogg"})
+VIDEO_CHUNK_BYTES = 64 * 1024
+REAUTHORIZE_INTERVAL_SECONDS = 1.0
+_RANGE = re.compile(r"bytes=([0-9]*)-([0-9]*)", re.IGNORECASE)
+_SECURITY_HEADERS = {
+    "cache-control": "no-store",
+    "referrer-policy": "no-referrer",
+    "x-content-type-options": "nosniff",
+    "x-robots-tag": "noindex, nofollow, noarchive",
+    "cross-origin-resource-policy": "same-origin",
+}
+
+
+class SharedVideoUnavailable(RuntimeError):
+    """Abort an already started response without exposing internal details."""
+
+
+class VideoStreamAdmission:
+    """A bounded, nonwaiting lease shared by both video route families."""
+
+    def __init__(self, limit=8):
+        if type(limit) is not int or limit < 1:
+            raise ValueError("Invalid video stream limit")
+        self.limit = limit
+        self._active = 0
+        self._lock = threading.Lock()
+
+    def acquire(self):
+        with self._lock:
+            if self._active >= self.limit:
+                return False
+            self._active += 1
+            return True
+
+    def release(self):
+        with self._lock:
+            self._active -= 1
+
+
+_ADMISSION = VideoStreamAdmission()
+
+
+def _byte_range(request, byte_size):
+    """Return (status, start, length), including strict single-range rejection."""
+    values = request.headers.getlist("range")
+    if not values:
+        return 200, 0, byte_size
+    if len(values) != 1 or len(values[0]) > 256:
+        return 416, 0, 0
+    match = _RANGE.fullmatch(values[0].strip())
+    if match is None or not any(match.groups()) or byte_size == 0:
+        return 416, 0, 0
+    first, last = match.groups()
+    if first:
+        start = int(first)
+        end = min(int(last), byte_size - 1) if last else byte_size - 1
+        if start >= byte_size or end < start:
+            return 416, 0, 0
+    else:
+        suffix = int(last)
+        if suffix == 0:
+            return 416, 0, 0
+        start, end = max(0, byte_size - suffix), byte_size - 1
+    return 206, start, end - start + 1
+
+
+def _file_revision(info):
+    return (info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns,
+            info.st_ctime_ns, info.st_uid, info.st_mode, info.st_nlink)
+
+
+class SharedVideoResponse(StreamingResponse):
+    """GET/HEAD response owning a descriptor for its complete ASGI lifecycle.
+
+    ``request`` is a Starlette Request. ``reauthorize`` is an optional async
+    zero-argument callback: None/True grants access, False or an exception denies
+    it. It runs immediately before headers and, on demand while consuming the
+    response, at most once per second. Denial before headers produces an empty
+    404; denial after headers aborts the stream with SharedVideoUnavailable.
+
+    Admission is acquired only when ASGI invokes the response and released on
+    every exit, including header disconnects. ``close()`` explicitly disposes a
+    response that will never be invoked; finalization is an additional fallback.
+    Neither the caller nor any other object may close/reuse the transferred fd.
+    ``file_revision`` may pin the resolver's fstat result as the tuple
+    (dev, ino, size, mtime_ns, ctime_ns, uid, mode, nlink). The revision is checked
+    at construction, before headers, and before/after every bounded read.
+    """
+
+    def __init__(self, fd, *, byte_size, content_type, filename, request,
+                 reauthorize=None, extra_headers=None, admission=None, file_revision=None):
+        self._fd = fd
+        self._fd_lock = threading.Lock()
+        self._called = False
+        try:
+            if (type(fd) is not int or fd < 0 or type(byte_size) is not int
+                    or byte_size < 0 or content_type not in VIDEO_CONTENT_TYPES):
+                raise ValueError("Invalid shared video")
+            info = os.fstat(fd)
+            if not stat.S_ISREG(info.st_mode) or info.st_size != byte_size:
+                raise ValueError("Invalid shared video")
+            self._file_revision = _file_revision(info)
+            if file_revision is not None and file_revision != self._file_revision:
+                raise ValueError("Invalid shared video")
+            # The caller supplies a display filename, never a path. Fail closed
+            # on path/control characters even if that contract was violated.
+            if (not isinstance(filename, str) or not filename or len(filename) > 255
+                    or filename in {".", ".."}
+                    or re.search(r"[\x00-\x1f\x7f/\\]", filename)):
+                raise ValueError("Invalid shared video")
+            self._method = request.method.upper()
+            self._reauthorize = reauthorize
+            self._last_authorized = None
+            self._admission = admission if admission is not None else _ADMISSION
+            self._base_headers = {str(key).lower(): value for key, value in (extra_headers or {}).items()}
+            # Route CSP is retained; callers cannot replace the mandatory
+            # privacy headers or representation/framing headers below.
+            for key in ("content-type", "content-length", "content-range", "content-disposition",
+                        "accept-ranges", "transfer-encoding", "etag", "last-modified"):
+                self._base_headers.pop(key, None)
+            self._base_headers.update(_SECURITY_HEADERS)
+            headers = dict(self._base_headers)
+            status, self._start, self._length = _byte_range(request, byte_size)
+            if self._method not in {"GET", "HEAD"}:
+                status, self._length = 405, 0
+                headers["allow"] = "GET, HEAD"
+            else:
+                headers["accept-ranges"] = "bytes"
+                if status == 416:
+                    headers["content-range"] = f"bytes */{byte_size}"
+                else:
+                    headers["content-type"] = content_type
+                    headers["content-disposition"] = "inline; filename*=UTF-8''" + quote(filename, safe="")
+                    if status == 206:
+                        headers["content-range"] = f"bytes {self._start}-{self._start + self._length - 1}/{byte_size}"
+            headers["content-length"] = str(self._length)
+            # stream_response owns the body; no generator owns the descriptor.
+            super().__init__(iter(()), status_code=status, headers=headers)
+        except BaseException:
+            self.close()
+            raise
+
+    def close(self):
+        """Idempotently close the owned descriptor, including unused responses."""
+        with self._fd_lock:
+            fd, self._fd = self._fd, None
+        if type(fd) is int and fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+
+    def __del__(self):
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def _read(self, size, offset):
+        # Cancellation may end an await while its worker still runs. Dup under
+        # the close lock so a delayed worker can never read a reused descriptor.
+        # The worker owns that duplicate until its one bounded read finishes.
+        with self._fd_lock:
+            if self._fd is None:
+                raise SharedVideoUnavailable("Shared video unavailable")
+            fd = os.dup(self._fd)
+        try:
+            if _file_revision(os.fstat(fd)) != self._file_revision:
+                raise SharedVideoUnavailable("Shared video unavailable")
+            chunk = os.pread(fd, size, offset)
+            if _file_revision(os.fstat(fd)) != self._file_revision:
+                raise SharedVideoUnavailable("Shared video unavailable")
+            return chunk
+        finally:
+            os.close(fd)
+
+    def _unchanged(self):
+        with self._fd_lock:
+            try:
+                return self._fd is not None and _file_revision(os.fstat(self._fd)) == self._file_revision
+            except OSError:
+                return False
+
+    async def _authorized(self, *, force=False):
+        if self._reauthorize is None:
+            return True
+        if (not force and self._last_authorized is not None
+                and time.monotonic() - self._last_authorized < REAUTHORIZE_INTERVAL_SECONDS):
+            return True
+        try:
+            granted = await self._reauthorize()
+        except Exception:
+            return False
+        self._last_authorized = time.monotonic()
+        return granted is None or granted is True
+
+    async def stream_response(self, send):
+        if not await self._authorized(force=True):
+            await self._empty_response(send, 404)
+            return
+        if not self._unchanged():
+            await self._empty_response(send, 404)
+            return
+        await send({"type": "http.response.start", "status": self.status_code, "headers": self.raw_headers})
+        if self._method != "HEAD" and self.status_code in {200, 206}:
+            offset, remaining = self._start, self._length
+            while remaining:
+                if not await self._authorized():
+                    raise SharedVideoUnavailable("Shared video unavailable")
+                try:
+                    chunk = await run_in_threadpool(self._read, min(VIDEO_CHUNK_BYTES, remaining), offset)
+                except OSError:
+                    raise SharedVideoUnavailable("Shared video unavailable") from None
+                if not chunk:
+                    raise SharedVideoUnavailable("Shared video unavailable")
+                # A slow disk read can cross the authorization interval.
+                if not await self._authorized():
+                    raise SharedVideoUnavailable("Shared video unavailable")
+                await send({"type": "http.response.body", "body": chunk, "more_body": True})
+                offset += len(chunk)
+                remaining -= len(chunk)
+        await send({"type": "http.response.body", "body": b"", "more_body": False})
+
+    async def _empty_response(self, send, status):
+        response = Response(status_code=status, headers=self._base_headers)
+        await send({"type": "http.response.start", "status": status, "headers": response.raw_headers})
+        await send({"type": "http.response.body", "body": b"", "more_body": False})
+
+    async def __call__(self, scope, receive, send):
+        admitted = False
+        try:
+            if self._called or self._fd is None:
+                raise SharedVideoUnavailable("Shared video unavailable")
+            self._called = True
+            admitted = self._admission.acquire()
+            if not admitted:
+                await self._empty_response(send, 503)
+                return
+            await super().__call__(scope, receive, send)
+        finally:
+            self.close()
+            if admitted:
+                self._admission.release()

package/server/shared_chat_videos.py

@@ -0,0 +1,155 @@
+"""Read-only, signed references to videos already published in one chat.
+
+No workspace paths, file discovery, registry writes, or video copies. Capabilities
+pin the registered copy's metadata and inode revision; changed files fail closed.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+from pathlib import Path
+import re
+import stat
+
+VIDEO_TYPES = frozenset({"video/mp4", "video/webm", "video/quicktime", "video/ogg"})
+VIDEO_ID = re.compile(r"video_[A-Za-z0-9_-]+\.[a-f0-9]{64}\Z")
+FILE_ID = re.compile(r"(?:file|art)_[a-f0-9]{16,32}\Z")
+SESSION_ID = re.compile(r"[A-Za-z0-9_-]{1,128}\Z")
+EXTENSIONS = {".mp4": "video/mp4", ".m4v": "video/mp4", ".webm": "video/webm",
+              ".mov": "video/quicktime", ".ogv": "video/ogg", ".ogg": "video/ogg"}
+
+
+class SharedVideoUnavailable(ValueError):
+    def __init__(self):
+        super().__init__("Shared video is unavailable")
+
+
+def normalize_shared_chat_videos(value):
+    if not isinstance(value, list) or len(value) > 32:
+        raise ValueError("Invalid shared videos")
+    output, seen = [], set()
+    for item in value:
+        if not isinstance(item, dict) or set(item) != {"id", "filename", "content_type", "size"}:
+            raise ValueError("Invalid shared video")
+        identity, name = item["id"], item["filename"]
+        if (not isinstance(identity, str) or len(identity) > 1024 or VIDEO_ID.fullmatch(identity) is None
+                or identity in seen or not isinstance(name, str) or not 1 <= len(name) <= 255
+                or name in {".", ".."} or any(ord(c) < 32 or ord(c) == 127 or c in "/\\" for c in name)
+                or len(name.encode("utf-8")) > 1024 or not isinstance(item["content_type"], str) or item["content_type"] not in VIDEO_TYPES
+                or type(item["size"]) is not int or not 0 < item["size"] <= (1 << 53) - 1):
+            raise ValueError("Invalid shared video")
+        output.append(dict(item)); seen.add(identity)
+    return output
+
+
+def _key(secret):
+    if not isinstance(secret, str) or not secret:
+        raise SharedVideoUnavailable()
+    return hmac.new(secret.encode("utf-8"), b"agentsdock-chat-video-v1", hashlib.sha256).digest()
+
+
+def _regular(info, owner):
+    if not stat.S_ISREG(info.st_mode) or info.st_nlink != 1 or info.st_uid != owner:
+        raise SharedVideoUnavailable()
+
+
+def _open_registered(root, session_id, file_id, *, legacy_owner=False):
+    """Open through pinned directories; return an owned FD, never reopen a path."""
+    if (not isinstance(session_id, str) or SESSION_ID.fullmatch(session_id) is None
+            or not isinstance(file_id, str) or FILE_ID.fullmatch(file_id) is None):
+        raise SharedVideoUnavailable()
+    root = Path(root)
+    if not root.is_absolute() or not hasattr(os, "O_NOFOLLOW") or not hasattr(os, "O_DIRECTORY"):
+        raise SharedVideoUnavailable()
+    directory_flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+    root_fd = directory_fd = meta_fd = video_fd = None
+    try:
+        root_fd = os.open(root, directory_flags)
+        owner = os.fstat(root_fd).st_uid
+        directory_fd = os.open(file_id, directory_flags, dir_fd=root_fd)
+        if os.fstat(directory_fd).st_uid != owner:
+            raise SharedVideoUnavailable()
+        meta_fd = os.open("meta.json", os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory_fd)
+        before = os.fstat(meta_fd)
+        _regular(before, owner)
+        if not 0 < before.st_size <= 64 * 1024:
+            raise SharedVideoUnavailable()
+        raw = os.read(meta_fd, 64 * 1024 + 1)
+        after = os.fstat(meta_fd)
+        if len(raw) != before.st_size or (before.st_mtime_ns, before.st_ctime_ns) != (after.st_mtime_ns, after.st_ctime_ns):
+            raise SharedVideoUnavailable()
+        meta = json.loads(raw)
+        if not isinstance(meta, dict) or meta.get("id") != file_id:
+            raise SharedVideoUnavailable()
+        if meta.get("session_id") != session_id and not (legacy_owner and meta.get("session_id") in (None, "")):
+            raise SharedVideoUnavailable()
+        name = meta.get("filename")
+        if (not isinstance(name, str) or not 1 <= len(name) <= 255 or name in {".", "..", "meta.json"}
+                or any(ord(c) < 32 or ord(c) == 127 or c in "/\\" for c in name)
+                or len(name.encode("utf-8")) > 1024 or meta.get("path") != str(root / file_id / name)):
+            raise SharedVideoUnavailable()
+        guessed = EXTENSIONS.get(Path(name).suffix.lower())
+        mime = str(meta.get("content_type") or "").split(";", 1)[0].strip().lower()
+        if mime in {"", "application/octet-stream", "binary/octet-stream"}:
+            mime = guessed
+        if mime not in VIDEO_TYPES or mime != guessed:
+            raise SharedVideoUnavailable()
+        video_fd = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=directory_fd)
+        info = os.fstat(video_fd)
+        _regular(info, owner)
+        if type(meta.get("size")) is not int or meta["size"] != info.st_size or not 0 < info.st_size <= (1 << 53) - 1:
+            raise SharedVideoUnavailable()
+        revision = hashlib.sha256(json.dumps([name, mime, meta.get("session_id"), info.st_dev, info.st_ino,
+            info.st_size, info.st_mtime_ns, info.st_ctime_ns, info.st_uid, info.st_mode],
+            ensure_ascii=True, separators=(",", ":")).encode("ascii")).hexdigest()
+        result = {"file_fd": video_fd, "filename": name, "content_type": mime, "size": info.st_size, "revision": revision,
+                  "file_revision": (info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns,
+                                    info.st_uid, info.st_mode, info.st_nlink)}
+        video_fd = None
+        return result
+    except (OSError, ValueError, TypeError, KeyError, UnicodeError, RecursionError):
+        raise SharedVideoUnavailable() from None
+    finally:
+        for fd in (video_fd, meta_fd, directory_fd, root_fd):
+            if fd is not None:
+                os.close(fd)
+
+
+def shared_chat_video_descriptor(root, secret, session_id, file_id, *, legacy_owner=False):
+    key = _key(secret)
+    opened = _open_registered(root, session_id, file_id, legacy_owner=legacy_owner)
+    try:
+        payload = json.dumps([1, session_id, file_id, opened["revision"]], separators=(",", ":")).encode("ascii")
+        encoded = base64.urlsafe_b64encode(payload).rstrip(b"=").decode("ascii")
+        identity = "video_" + encoded + "." + hmac.new(key, encoded.encode("ascii"), hashlib.sha256).hexdigest()
+        return normalize_shared_chat_videos([{key: opened[key] for key in ("filename", "content_type", "size")} | {"id": identity}])[0]
+    finally:
+        os.close(opened["file_fd"])
+
+
+def open_shared_chat_video(root, secret, session_id, identity):
+    opened = None
+    try:
+        if not isinstance(identity, str) or len(identity) > 1024 or VIDEO_ID.fullmatch(identity) is None:
+            raise SharedVideoUnavailable()
+        encoded, signature = identity[len("video_"):].split(".")
+        expected = hmac.new(_key(secret), encoded.encode("ascii"), hashlib.sha256).hexdigest()
+        if not hmac.compare_digest(signature, expected):
+            raise SharedVideoUnavailable()
+        payload = json.loads(base64.b64decode(encoded + "=" * (-len(encoded) % 4), altchars=b"-_", validate=True))
+        if (not isinstance(payload, list) or len(payload) != 4 or type(payload[0]) is not int or payload[0] != 1
+                or payload[1] != session_id or not isinstance(payload[3], str)):
+            raise SharedVideoUnavailable()
+        opened = _open_registered(root, session_id, payload[2], legacy_owner=True)
+        if not hmac.compare_digest(opened.pop("revision"), payload[3]):
+            raise SharedVideoUnavailable()
+        result, opened = opened, None
+        return result
+    except (ValueError, TypeError, KeyError, UnicodeError, RecursionError):
+        raise SharedVideoUnavailable() from None
+    finally:
+        if opened is not None:
+            os.close(opened["file_fd"])