Merge branch 'feature-protected-recordings'

Author: defnull

bbblb/migrations/versions/faacfea3b608_protected_recordings.py

@@ -0,0 +1,48 @@
+"""Protected recordings
+
+Revision ID: faacfea3b608
+Revises: 988e3ce2a20e
+Create Date: 2026-04-10 14:55:08.788193
+
+"""
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = "faacfea3b608"
+down_revision: Union[str, Sequence[str], None] = "988e3ce2a20e"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.create_table(
+        "view_tickets",
+        sa.Column("uuid", sa.Uuid(), nullable=False),
+        sa.Column("recording_fk", sa.Integer(), nullable=False),
+        sa.Column("expire", sa.DateTime(), nullable=False),
+        sa.Column("consumed", sa.Boolean(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["recording_fk"],
+            ["recordings.id"],
+            name=op.f("fk_view_tickets_recording_fk_recordings"),
+            ondelete="CASCADE",
+        ),
+        sa.PrimaryKeyConstraint("uuid", name=op.f("pk_view_tickets")),
+    )
+    op.add_column("recordings", sa.Column("protected", sa.Boolean(), server_default=sa.sql.expression.false()))
+    with op.batch_alter_table("recordings") as batch_op:
+        batch_op.alter_column("protected", server_default=None)
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    with op.batch_alter_table("recordings") as batch_op:
+        batch_op.drop_column("protected")
+
+    op.drop_table("view_tickets")

bbblb/model.py

@@ -4,6 +4,7 @@
 import enum
 import logging
 import typing
+import uuid
 from uuid import UUID
 
 import datetime
@@ -536,6 +537,7 @@ class Recording(Base):
     started: Mapped[datetime.datetime] = mapped_column(TZDateTime(), nullable=False)
     ended: Mapped[datetime.datetime] = mapped_column(TZDateTime(), nullable=False)
     participants: Mapped[int] = mapped_column(nullable=False, default=0)
+    protected: Mapped[bool] = mapped_column(nullable=False, default=False)
 
     @validates("meta")
     def validate_meta(self, key, meta):
@@ -569,6 +571,57 @@ class PlaybackFormat(Base):
     xml: Mapped[str] = mapped_column(nullable=False)
 
 
+class ViewTicket(Base):
+    __tablename__ = "view_tickets"
+
+    uuid: Mapped[UUID] = mapped_column(primary_key=True)
+    recording_fk: Mapped[int] = mapped_column(
+        ForeignKey("recordings.id", ondelete="CASCADE"), nullable=False
+    )
+    recording: Mapped[Recording] = relationship(lazy=False)
+    expire: Mapped[datetime.datetime] = mapped_column(TZDateTime(), nullable=False)
+    consumed: Mapped[bool] = mapped_column(nullable=False, default=False)
+
+    def is_expired(self):
+        return utcnow() > self.expire
+
+    @classmethod
+    def create(cls, recording: Recording, lifetime: datetime.timedelta) -> "ViewTicket":
+        return cls(
+            uuid=uuid.uuid4(),
+            recording=recording,
+            expire=utcnow() + lifetime,
+        )
+
+    @classmethod
+    def delete_expired(cls):
+        return cls.delete(cls.expire < utcnow())
+
+    async def consume(self, session: AsyncSession, commit=False) -> bool:
+        """Atomically mark a valid ticket as consumed.
+
+        Returns True if the ticket existed, was not expired and not already consumed.
+        """
+        result = await session.execute(
+            update(ViewTicket)
+            .where(ViewTicket.uuid == self.uuid)
+            .where(ViewTicket.expire > utcnow())
+            .where(ViewTicket.consumed.is_(False))
+            .values(consumed=True)
+            .returning(ViewTicket.uuid)
+        )
+        row = result.fetchone()
+        if row is None:
+            return False
+        if commit:
+            await session.commit()
+        self.consumed = True
+        return True
+
+    def __str__(self):
+        return f"ViewTicket(rec={self.recording.record_id} ticket={self.uuid})"
+
+
 # class Task(Base):
 #     __tablename__ = "tasks"
 #     id: Mapped[int] = mapped_column(primary_key=True)

bbblb/services/recording.py

@@ -34,18 +34,16 @@
 P = typing.ParamSpec("P")
 R = typing.TypeVar("R")
 
-URLPATTERNS = {
-    "presentation",
-    "{BASEURL}/playback/presentation/player/{RECORD_ID}/*",
-    "{BASEURL}/playback/{FORMAT}/{RECORD_ID}/",
-}
-
 
 class RecordingImportError(RuntimeError):
     pass
 
 
-def playback_to_xml(config: BBBLBConfig, playback: model.PlaybackFormat) -> Element:
+def playback_to_xml(
+    config: BBBLBConfig,
+    playback: model.PlaybackFormat,
+    ticket_prefix: str | None = None,
+) -> Element:
     orig = lxml.etree.fromstring(playback.xml)
     playback_domain = config.PLAYBACK_DOMAIN.format(
         DOMAIN=config.DOMAIN, REALM=playback.recording.tenant.realm
@@ -80,6 +78,8 @@ def playback_to_xml(config: BBBLBConfig, playback: model.PlaybackFormat) -> Elem
         url = url._replace(scheme="https", netloc=playback_domain)
         if url.path.startswith(f"/{playback.format}"):
             url = url._replace(path=f"/playback{url.path}")
+        if ticket_prefix and url.path.startswith("/playback/"):
+            url = url._replace(path=ticket_prefix + url.path)
         node.text = url.geturl()
 
     return result
@@ -259,7 +259,12 @@ async def import_waiting(self):
 
     async def cleanup(self):
         # TODO: Cleanup *.failed and *.canceled work directories.
-        pass
+
+        # Cleanup expored ViewTicket entries for protected recordings.
+        async with self.db.connect() as conn:
+            result = await conn.execute(model.ViewTicket.delete_expired())
+            if result.rowcount:
+                LOG.debug(f"Removed {result.rowcount} expired ViewTickets")
 
     async def close(self):
         for task in list(self.tasks.values()):

bbblb/settings.py

@@ -210,11 +210,37 @@ class BBBLBConfig(BaseConfig):
     then BBBLB will import new recordings as 'unpublished' regardless of
     their original state. """
 
+    PROTECTED_RECORDINGS: bool = False
+    """ If enabled, BBBLB will support *protected recordings* similar to
+    the experimental and unofficial API extention implemented by
+    Scalelite and Greenlight.
+
+    For protected recordings, the getRecordings API will replace
+    recording links with a one-time ticket that allow a single user to
+    watch the protected recording for a limited amount of time.
+
+    Warning: This feature needs additional configuration if recordings
+    are not served through BBBLB, and does not prevent downloads. Read
+    the documentation to understand requirements and limitations of this
+    feature."""
+
+    PROTECTED_RECORDINGS_TIMEOUT: int = 360
+    """ Number of minutes a protected recording can be watched wth a
+    ticket after it has been issued. """
+
     PLAYBACK_DOMAIN: str = "{DOMAIN}"
     """ Domain where recordings are hostet. The wildcards {DOMAIN} or {REALM}
     can be used to refer to the global DOMAIN config, or the realm of the
     current tenant. """
 
+    PLAYBACK_PLAYER_ROOT: Path | None = None
+    """ Absolute path to a copy of the bbb-playback presentation player.
+    You can leave this blank if you serve the bbb-playback assets via
+    a front-end webserver or CDN.
+
+    Defaults to `{PATH_DATA}/htdocs/playback/presentation/2.3/`
+    """
+
     POLL_INTERVAL: int = 30
     """ Poll interval in seconds for the background server health and meeting
     checker. This also defines the timeout for each individual poll, and

bbblb/utils.py

@@ -1,6 +1,8 @@
 # Copyright (C) 2025, 2026  Marcel Hellkamp
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
+import hashlib
+import hmac
 import typing
 import re
 
@@ -12,7 +14,7 @@
 # Common regular expressions
 RE_MEETING_ID = re.compile("^[a-zA-Z0-9-_]{2,%d}$" % MAX_MEETING_ID_LEN)
 RE_FORMAT_NAME = re.compile("^[a-zA-Z0-9]{1,64}$")
-RE_RECORD_ID = re.compile("^[0-9a-fA-F]+-\\d+$")
+RE_RECORD_ID = re.compile("^[0-9a-f]{40}-\\d{12,}$")
 RE_TENANT_NAME = re.compile("^[a-zA-Z0-9]{1,%d}$" % MAX_TENANT_NAME_LEN)
 
 
@@ -64,3 +66,21 @@ def checked_cast(type_: type[T], value: typing.Any) -> T:
     if isinstance(value, type_):
         return value
     raise TypeError(f"Expected {type_} but got {type(value)}")
+
+
+def hmac_sign(payload: str, secret: str) -> str:
+    sig = hmac.digest(secret.encode("UTF8"), payload.encode("UTF8"), hashlib.sha256)
+    return f"{sig.hex()}:{payload}"
+
+
+def hmac_verify(untrtusted: str, secret: str) -> str | None:
+    sig, sep, payload = untrtusted.partition(":")
+    if sig and sep:
+        check = hmac.digest(
+            secret.encode("UTF8"), payload.encode("UTF8"), hashlib.sha256
+        )
+        try:
+            if hmac.compare_digest(check, bytes.fromhex(sig)):
+                return payload
+        except ValueError:
+            pass

bbblb/web/__init__.py

@@ -2,7 +2,6 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 from contextlib import asynccontextmanager
-from functools import partial
 from starlette.applications import Starlette
 from starlette.routing import Mount, Route
 from starlette.staticfiles import StaticFiles
@@ -61,53 +60,37 @@ def session(self):
         return self.db.session()
 
 
-# Playback formats for which we know that they sometimes expect their files
-# in /{format}/* instead of the default /playback/{format}/* path.
-PLAYBACK_FROM_ROOT_FORMATS = ("presentation", "video")
-
-
-async def format_redirect_app(format, scope, receive, send):
-    assert scope["type"] == "http"
-    path = scope["path"].lstrip("/")
-    response = RedirectResponse(url=f"/playback/{format}/{path}")
-    await response(scope, receive, send)
-
-
 def redirect(src, dst):
     async def handler(request):
         return RedirectResponse(url=dst)
 
     return Route(src, endpoint=handler)
 
 
-def make_routes(config: BBBLBConfig):
-    from bbblb.web import bbbapi, bbblbapi
+async def collect_routes(sr: ServiceRegistry):
+    from bbblb.web import bbbapi, bbblbapi, playback
 
-    playback_dir = config.PATH_DATA / "recordings" / "public"
-    playback_dir.mkdir(parents=True, exist_ok=True)
+    config = await sr.use(BBBLBConfig)
     static_dir = config.PATH_DATA / "htdocs"
     static_dir.mkdir(parents=True, exist_ok=True)
 
     return [
         Mount("/bigbluebutton/api", routes=bbbapi.api_routes),
         Mount("/bbblb/api", routes=bbblbapi.api_routes),
-        # Serve /playback/* files in case the reverse proxy in front if BBBLB does not.
+        Mount(
+            "/playback/presentation/2.3/{record_id}",
+            app=playback.PlaybackPlayerApp(config),
+            name="bbb:playback:player",
+        ),
         Mount(
             "/playback",
-            app=StaticFiles(
-                directory=playback_dir,
-                check_dir=False,
-                follow_symlink=True,
-            ),
-            name="bbb:playback",
+            app=playback.PlaybackMediaApp(config, await sr.use(DBContext)),
+            name="bbb:playback:media",
         ),
         # Redirect misguided playback file requests to the real path. We send
         # redirects instead of real files in case a reverse proxy in front if BBBLB
-        # serves /playback/* for us more efficiently.
-        *[
-            Mount(f"/{format}", app=partial(format_redirect_app, format))
-            for format in PLAYBACK_FROM_ROOT_FORMATS
-        ],
+        # serves /playback/* for us.
+        *playback.PLAYBACK_FORMAT_REDIRECTS,
         # Redirect non-slash requests to prefix mounts, because automatic slash handling
         # breaks if there are other routes matching the non-slash request :/
         redirect("/bigbluebutton/api", "/bigbluebutton/api/"),
@@ -139,8 +122,9 @@ async def lifespan(app: Starlette):
         async with services:
             if autostart:
                 await services.start_all()
-            app.state.config = config
+            app.router.routes.extend(await collect_routes(services))
             app.state.services = services
+
             yield
 
-    return Starlette(debug=config.DEBUG, routes=make_routes(config), lifespan=lifespan)
+    return Starlette(debug=config.DEBUG, lifespan=lifespan)