From f9d3743bddf0832e0bc10cc7dc0f95bb308899f0 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 09:34:44 +0000 Subject: [PATCH 01/19] Bump the version to 1.1.3 and open its changelog entry Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 19 +++++++++++++++++++ meson.build | 2 +- packaging/freebsd/+MANIFEST | 2 +- packaging/netbsd/Makefile | 2 +- packaging/opensuse/merovingian.spec | 5 ++++- packaging/rhel/merovingian.spec | 5 ++++- packaging/rpm/merovingian.spec | 5 ++++- scripts/build-deb.sh | 4 ++-- scripts/build-freebsd-pkg.sh | 4 ++-- scripts/build-netbsd-pkg.sh | 4 ++-- scripts/build-openbsd-pkg.sh | 4 ++-- scripts/build-opensuse-rpm.sh | 4 ++-- scripts/build-rhel-rpm.sh | 4 ++-- scripts/build-rpm.sh | 4 ++-- scripts/build-static-linux.sh | 2 +- src/db_migrate.cpp | 2 +- src/main.cpp | 2 +- 17 files changed, 51 insertions(+), 23 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 57f9ea3ed..7af347655 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,25 @@ Changes from 1.0.0, the first production release, onwards; the format is set out Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md), which is no longer added to ([ADR-0740](docs/adr/0740-the-changelog-starts-at-1-0-0-and-the-pre-release-entries-are-a-frozen-record.md)). +# Version 1.1.3 + +## Features + +* None. + +## Security Fixes + +* None. + +## Bug fixes + +* None. + +## Release notes + +Version 1.1.3 is in progress: a LiveKit token service built into the server for MatrixRTC calls, and an exact +`state_after` on `/sync`. + # Version 1.1.2 ## Features diff --git a/meson.build b/meson.build index 813a15102..887a3f69f 100644 --- a/meson.build +++ b/meson.build @@ -2,7 +2,7 @@ project( 'merovingian', 'cpp', 'c', - version: '1.1.2', + version: '1.1.3', license: 'GPL-3.0-or-later', meson_version: '>=1.1.0', default_options: [ diff --git a/packaging/freebsd/+MANIFEST b/packaging/freebsd/+MANIFEST index 8ec24b40a..77d305136 100644 --- a/packaging/freebsd/+MANIFEST +++ b/packaging/freebsd/+MANIFEST @@ -1,5 +1,5 @@ name: "merovingian" -version: "1.1.2" +version: "1.1.3" origin: net/merovingian comment: Secure Matrix Protocol homeserver desc: "Merovingian is a Matrix Protocol homeserver." diff --git a/packaging/netbsd/Makefile b/packaging/netbsd/Makefile index ee3d41614..172afbb90 100644 --- a/packaging/netbsd/Makefile +++ b/packaging/netbsd/Makefile @@ -1,4 +1,4 @@ -DISTNAME= merovingian-1.1.2 +DISTNAME= merovingian-1.1.3 CATEGORIES= net MASTER_SITES= ${MASTER_SITE_GITHUB:=OMG-Software/} GITHUB_PROJECT= Merovingian diff --git a/packaging/opensuse/merovingian.spec b/packaging/opensuse/merovingian.spec index 4c5cc7c95..ad696ac3b 100644 --- a/packaging/opensuse/merovingian.spec +++ b/packaging/opensuse/merovingian.spec @@ -1,5 +1,5 @@ Name: merovingian -Version: 1.1.2 +Version: 1.1.3 Release: 1%{?dist} Summary: Secure Matrix Protocol homeserver @@ -115,6 +115,9 @@ fi %{_sysconfdir}/merovingian/merovingian.conf.example %changelog +* Tue Nov 17 2026 James Chapman - 1.1.3-1 +- Merovingian 1.1.3 + * Tue Nov 17 2026 James Chapman - 1.1.2-1 - Merovingian 1.1.2 diff --git a/packaging/rhel/merovingian.spec b/packaging/rhel/merovingian.spec index 218c2842d..c1833789f 100644 --- a/packaging/rhel/merovingian.spec +++ b/packaging/rhel/merovingian.spec @@ -1,5 +1,5 @@ Name: merovingian -Version: 1.1.2 +Version: 1.1.3 Release: 1%{?dist} Summary: Secure Matrix Protocol homeserver @@ -100,6 +100,9 @@ fi %{_sysconfdir}/merovingian/merovingian.conf.example %changelog +* Tue Nov 17 2026 James Chapman - 1.1.3-1 +- Merovingian 1.1.3 + * Tue Nov 17 2026 James Chapman - 1.1.2-1 - Merovingian 1.1.2 diff --git a/packaging/rpm/merovingian.spec b/packaging/rpm/merovingian.spec index d6dacd37c..2291e8410 100644 --- a/packaging/rpm/merovingian.spec +++ b/packaging/rpm/merovingian.spec @@ -1,5 +1,5 @@ Name: merovingian -Version: 1.1.2 +Version: 1.1.3 Release: 1%{?dist} Summary: Secure Matrix Protocol homeserver @@ -104,6 +104,9 @@ fi %{_sysconfdir}/merovingian/merovingian.conf.example %changelog +* Tue Nov 17 2026 James Chapman - 1.1.3-1 +- Merovingian 1.1.3 + * Tue Nov 17 2026 James Chapman - 1.1.2-1 - Merovingian 1.1.2 diff --git a/scripts/build-deb.sh b/scripts/build-deb.sh index 810712faf..40460537a 100755 --- a/scripts/build-deb.sh +++ b/scripts/build-deb.sh @@ -1,9 +1,9 @@ #!/bin/sh # SPDX-License-Identifier: GPL-3.0-or-later -# Build for merovingian 1.1.2. +# Build for merovingian 1.1.3. set -e -VERSION="1.1.2" +VERSION="1.1.3" PKG_NAME="merovingian" STAGING="staging-deb" diff --git a/scripts/build-freebsd-pkg.sh b/scripts/build-freebsd-pkg.sh index 999397b0e..67bb69112 100755 --- a/scripts/build-freebsd-pkg.sh +++ b/scripts/build-freebsd-pkg.sh @@ -1,9 +1,9 @@ #!/bin/sh # SPDX-License-Identifier: GPL-3.0-or-later -# Build for merovingian 1.1.2. +# Build for merovingian 1.1.3. set -e -VERSION="1.1.2" +VERSION="1.1.3" STAGING="staging-fbsd" # Clean any state (staged files, build dir) from cached FreeBSD VM runs. diff --git a/scripts/build-netbsd-pkg.sh b/scripts/build-netbsd-pkg.sh index 5d3651758..5022a7975 100644 --- a/scripts/build-netbsd-pkg.sh +++ b/scripts/build-netbsd-pkg.sh @@ -1,6 +1,6 @@ #!/bin/sh # SPDX-License-Identifier: GPL-3.0-or-later -# Build for merovingian 1.1.2. +# Build for merovingian 1.1.3. # # The checked-in packaging/netbsd/Makefile is the pkgsrc recipe kept for # downstream porters. This script generates a framework-free package so CI @@ -11,7 +11,7 @@ # a staged tree using tar, which produces a package that pkg_add can install. set -e -VERSION="1.1.2" +VERSION="1.1.3" STAGE="staging-netbsd" PREFIX=/usr/pkg diff --git a/scripts/build-openbsd-pkg.sh b/scripts/build-openbsd-pkg.sh index a05d22805..f0b043f10 100644 --- a/scripts/build-openbsd-pkg.sh +++ b/scripts/build-openbsd-pkg.sh @@ -1,6 +1,6 @@ #!/bin/sh # SPDX-License-Identifier: GPL-3.0-or-later -# Build for merovingian 1.1.2. +# Build for merovingian 1.1.3. # # Standalone pkg_create(1), no ports tree. The checked-in packaging/openbsd/PLIST # is the ports-framework packing list kept for downstream porters; this script @@ -8,7 +8,7 @@ # produce and validate an installable package on every run. set -e -VERSION="1.1.2" +VERSION="1.1.3" STAGE="staging-openbsd" PREFIX=/usr/local diff --git a/scripts/build-opensuse-rpm.sh b/scripts/build-opensuse-rpm.sh index cd3cd82d3..e2e5e79cb 100644 --- a/scripts/build-opensuse-rpm.sh +++ b/scripts/build-opensuse-rpm.sh @@ -1,6 +1,6 @@ #!/bin/sh # SPDX-License-Identifier: GPL-3.0-or-later -# Build an RPM package for merovingian 1.1.2 on OpenSUSE Tumbleweed or Leap. +# Build an RPM package for merovingian 1.1.3 on OpenSUSE Tumbleweed or Leap. # # Uses packaging/opensuse/merovingian.spec which adapts BuildRequires to # OpenSUSE package names (libopenssl-devel, postgresql-devel, libpng16-devel, @@ -12,7 +12,7 @@ # (.leap16, ADR-0650). set -e -VERSION="1.1.2" +VERSION="1.1.3" DIST="${MEROVINGIAN_RPM_DIST:-.tumbleweed}" case "${DIST}" in .[a-z]*) ;; diff --git a/scripts/build-rhel-rpm.sh b/scripts/build-rhel-rpm.sh index a6b668a76..ab43f76bb 100644 --- a/scripts/build-rhel-rpm.sh +++ b/scripts/build-rhel-rpm.sh @@ -1,13 +1,13 @@ #!/bin/sh # SPDX-License-Identifier: GPL-3.0-or-later -# Build an RPM package for merovingian 1.1.2 targeting RHEL 10 / AlmaLinux 10. +# Build an RPM package for merovingian 1.1.3 targeting RHEL 10 / AlmaLinux 10. # # Differs from build-rpm.sh only in the spec file used: packaging/rhel/merovingian.spec # omits catch-devel from BuildRequires (Catch2 is not reliably available in EPEL 10 # and is not needed when -Dbuild_tests=false). set -e -VERSION="1.1.2" +VERSION="1.1.3" mkdir -p "${HOME}/rpmbuild/BUILD" mkdir -p "${HOME}/rpmbuild/BUILDROOT" diff --git a/scripts/build-rpm.sh b/scripts/build-rpm.sh index ac4f9b3f7..91a7ebacf 100755 --- a/scripts/build-rpm.sh +++ b/scripts/build-rpm.sh @@ -1,9 +1,9 @@ #!/bin/sh # SPDX-License-Identifier: GPL-3.0-or-later -# Build an RPM package for merovingian 1.1.2 using rpmbuild. +# Build an RPM package for merovingian 1.1.3 using rpmbuild. set -e -VERSION="1.1.2" +VERSION="1.1.3" # 1. Create rpmbuild directory tree mkdir -p "${HOME}/rpmbuild/BUILD" diff --git a/scripts/build-static-linux.sh b/scripts/build-static-linux.sh index a83d86c1e..455810c6a 100755 --- a/scripts/build-static-linux.sh +++ b/scripts/build-static-linux.sh @@ -3,7 +3,7 @@ # Build a portable Linux fallback tarball with musl-linked static PIE binaries. set -eu -VERSION="${MEROVINGIAN_VERSION:-1.1.2}" +VERSION="${MEROVINGIAN_VERSION:-1.1.3}" BUILD_DIR="${BUILD_DIR:-build-static-linux}" STAGING="staging-static-linux" PACKAGE_ROOT="merovingian-${VERSION}-linux-static-x86_64" diff --git a/src/db_migrate.cpp b/src/db_migrate.cpp index 1e38bb17f..8ed212e6a 100644 --- a/src/db_migrate.cpp +++ b/src/db_migrate.cpp @@ -23,7 +23,7 @@ namespace { -constexpr auto version = std::string_view{"1.1.2"}; +constexpr auto version = std::string_view{"1.1.3"}; auto print_help() -> void { diff --git a/src/main.cpp b/src/main.cpp index fffef2e22..9b97e009f 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -82,7 +82,7 @@ namespace { -constexpr auto version = std::string_view{"1.1.2"}; +constexpr auto version = std::string_view{"1.1.3"}; struct BootstrapConfigResult final { From 93d4219b1d735b131d6d39acad2ec5be7d7212da Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 10:10:02 +0000 Subject: [PATCH 02/19] Measure state_after deltas from an in-memory log of resolved state changes A state_after delta was measured from the state recorded for the newest event at since. On a room forked at since, that is one branch's state, not the resolved state the client was told, so a key that resolution later moved back was never sent (review of PR 595). A backfilled event ordered at or below since did the same, and the left-room delta had the same baseline. Every change to a room's current state in the main process now goes into PersistentStore::state_change_log. A change is filed at the causing event's stream ordering, raised above every position a sync has answered, so the state told as of a served position never changes. resolved_state_at and resolved_state_changes rebuild the state told and the exact delta from that one record. A window of messages costs no state row. A since from before start-up gets the room's whole state once. No migration (ADR-0827, superseding part of ADR-0819). Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 6 +- ...ate-after-delta-compares-the-two-states.md | 2 +- ...in-memory-log-of-resolved-state-changes.md | 133 ++++++++ docs/adr/index.md | 1 + docs/database-persistence.md | 6 + docs/matrix-v1.19-client-server-api.md | 2 +- docs/todos/capability-gaps.md | 2 +- .../merovingian/database/PersistentStore.hpp | 22 +- .../merovingian/database/StateChangeLog.hpp | 112 +++++++ include/merovingian/sync/ResolvedState.hpp | 41 +++ include/merovingian/sync/StateGroupLookup.hpp | 11 - src/database/AGENTS.md | 11 + src/database/PersistentStore.cpp | 28 +- src/database/StateChangeLog.cpp | 142 +++++++++ src/database/meson.build | 1 + src/homeserver/ClientServerRuntime.cpp | 124 ++++---- src/homeserver/HomeserverRuntime.cpp | 4 + src/homeserver/StateBookkeeping.cpp | 8 +- src/sync/AGENTS.md | 25 +- src/sync/ResolvedState.cpp | 127 ++++++++ src/sync/StateGroupLookup.cpp | 31 -- src/sync/meson.build | 1 + .../test_sync_state_after_conformance.cpp | 12 +- tests/integration/test_sync_handler_flow.cpp | 88 +---- .../test_sync_state_after_flow.cpp | 219 +++++++++++++ tests/meson.build | 2 + tests/support/AGENTS.md | 1 + tests/support/StatePduSupport.hpp | 92 ++++++ tests/unit/test_resolved_state.cpp | 240 ++++++++++++++ tests/unit/test_state_change_log.cpp | 300 ++++++++++++++++++ 30 files changed, 1584 insertions(+), 210 deletions(-) create mode 100644 docs/adr/0827-a-state-after-delta-is-measured-from-an-in-memory-log-of-resolved-state-changes.md create mode 100644 include/merovingian/database/StateChangeLog.hpp create mode 100644 include/merovingian/sync/ResolvedState.hpp create mode 100644 src/database/StateChangeLog.cpp create mode 100644 src/sync/ResolvedState.cpp create mode 100644 tests/support/StatePduSupport.hpp create mode 100644 tests/unit/test_resolved_state.cpp create mode 100644 tests/unit/test_state_change_log.cpp diff --git a/CHANGELOG.md b/CHANGELOG.md index 7af347655..8c7975ad3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,12 +15,14 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Bug fixes -* None. +* `use_state_after`: a room forked at `since` now gets exactly what changed since what the client was told, read from an + in-memory log of state changes, and so does a left room (ADR-0827). ## Release notes Version 1.1.3 is in progress: a LiveKit token service built into the server for MatrixRTC calls, and an exact -`state_after` on `/sync`. +`state_after` on `/sync`. After a restart, the first `state_after` sync of each room with news carries its whole state +once. # Version 1.1.2 diff --git a/docs/adr/0819-a-state-after-delta-compares-the-two-states.md b/docs/adr/0819-a-state-after-delta-compares-the-two-states.md index 663bfac96..e95eced11 100644 --- a/docs/adr/0819-a-state-after-delta-compares-the-two-states.md +++ b/docs/adr/0819-a-state-after-delta-compares-the-two-states.md @@ -1,6 +1,6 @@ # A `state_after` delta compares the two states, and every change it finds is sent under lazy-loading -* Status: accepted +* Status: accepted (the baseline at `since` and the chain walk are superseded by [ADR-0827](0827-a-state-after-delta-is-measured-from-an-in-memory-log-of-resolved-state-changes.md); the lazy-loading rules stand) * Date: 2026-11-16 ## Context and Problem Statement diff --git a/docs/adr/0827-a-state-after-delta-is-measured-from-an-in-memory-log-of-resolved-state-changes.md b/docs/adr/0827-a-state-after-delta-is-measured-from-an-in-memory-log-of-resolved-state-changes.md new file mode 100644 index 000000000..cf57b83ca --- /dev/null +++ b/docs/adr/0827-a-state-after-delta-is-measured-from-an-in-memory-log-of-resolved-state-changes.md @@ -0,0 +1,133 @@ +# A `state_after` delta is measured from an in-memory log of resolved state changes + +* Status: accepted +* Date: 2026-11-17 + +Technical Story: review of 1.1.1, https://github.com/OMG-Software/Merovingian/pull/595#discussion_r4593957508 + +## Context and Problem Statement + +[ADR-0819](0819-a-state-after-delta-compares-the-two-states.md) +measured an incremental `state_after` from the state recorded for the newest event at or below `since`. A client is +told the room's *resolved* state, which on a forked room is not that event's recorded state. Take a fork at `since` +whose resolution picks branch A while the newest event records branch B: + +1. The client is told A. +2. Resolution later moves the key to B. +3. The delta compares B with B and sends nothing. + +The client keeps A for ever, and `state_after` exists so that a client can stop reading state from the timeline. + +A backfilled event ordered at or below `since` can stand in for the anchor in the same way. The left-room delta had the +same baseline. + +How can a delta be exact against what the client was told, at the cost rules of `src/sync/AGENTS.md`? + +- A room with no news costs nothing. +- There is no whole-state read on the common path. +- There is no per-request scan of a room's rows under `runtime.mutex`. + +## Decision Drivers + +* The delta must equal the difference between the state told at `since` and the state told now, for every graph shape. +* A window of messages must read no state. +* Every writer of current state already runs under `runtime.mutex` in the main process, as does every sync. + +## Considered Options + +* Store each response's state per token (refused in ADR-0819 for its cost) +* Send the whole state whenever the room is forked +* A persisted table of state changes (migration 004) +* An in-memory log of resolved state changes, keyed by the sync position from which a client sees each one + +## Decision Outcome + +Chosen option: the in-memory log, `database::StateChangeLog` (`PersistentStore::state_change_log`), read through +`sync::resolved_state_at`, `sync::resolved_state_changes` and `sync::resolved_state_event_at`. + +* **What is recorded.** Every change to a room's current state in the main process is recorded: room, key, previous + event and new event. + - Every such change goes through one of four store functions, and each records: `apply_store_event_with_state`, + `apply_current_state`, `store_state` and `remove_current_state_rows`. + - `apply_room_snapshot` forgets the room instead (a reload replaces the room's state wholesale). + - The federation worker never starts the log, so it records nothing. +* **Where a change is filed.** A change is filed at the stream ordering of the event whose storing made it, raised to + one above the highest position a sync has answered at (`note_served`, called where `sync_json` fixes + `sync_position`). + - So no change is ever filed at or below a position a client was already told about. + - The state as of a served position is therefore fixed once served: the current state, with each key changed above + the position put back to the value its first such change replaced. + - A backfilled event ordered below `since` is filed above it. +* **Why the delta is exact.** The state told at `since` and the state told now are both read from this one record, so + their difference is exact. Specifically: + - A key that state resolution moved back is found. + - A key that changed and changed back is not sent. + - A key removed from the state is not sent, since `state_after` cannot express a removal. + - The whole-state answers (an initial sync, `full_state=true`, a join in the window) are the same rebuilt state, so + a later delta starts from what was really said. + - A lazy-loaded sender's member as of the position is looked up the same way. +* **Left rooms.** A left room's delta is the state readable as of the leave (`room_read_access_for`, unchanged) minus the + state told at `since`. +* **News check.** `select_sync_rooms` counts a logged change above `since` as news for a `state_after` client, because + a change with no event of its own in the room is still a change. +* **Cost.** + - A delta reads the room's changes above `since`, counted in the log's `rows_examined`, plus one lookup by key per + key they name: nothing for a window of messages. + - `has_change_after` is one map lookup. + - Rebuilding a whole state reads the room's state rows once, which is what the whole-state answers already did. +* **What is not covered.** The log covers a position only above the position the process started at, and only at or + above a room's horizon. A position outside that falls back as follows: + - A `since` at or below the start was answered by an earlier process, or comes from a database restored or upgraded + from one, so it is never trusted for a delta. The room's whole resolved state is sent once (an update the client + already holds is harmless), and the next sync is a delta again. Upgraded databases need nothing more. + - When the log does not cover the position itself, the state ADR-0247 reads is sent. A delta from that position is + then never taken, so the two cannot disagree. +* **Bounds.** + - At most 1,024 changes per room and 65,536 in all. Past either bound the oldest change is dropped. + - Dropping a room's change raises that room's horizon: a `since` below it is not covered, and the room's whole + state is sent once. + +This supersedes the part of ADR-0819 that chose the baseline and the chain walk (`state_changes_along_chain`, now +removed). ADR-0819's lazy-loading rules stand. + +### Positive Consequences + +* The delta is exact against what each response said, for forks, resolutions that move a key back, and backfill. +* A window of messages costs nothing. No migration, and no write to any transaction. + +### Negative Consequences + +* After a restart, the first `state_after` sync of each room with news sends that room's whole state once. +* A change made with no event that raises the stream (for example a state group recorded later for an old event) is + filed above the last served position, and reaches clients when the stream next moves. As before, this happens as soon + as any event is stored anywhere on the server. If the process stops first, the change waits for the room's next + event, which is then sent with the room's whole state. +* The log uses memory: at most 65,536 changes of a few event IDs each. + +## Pros and Cons of the Options + +### Store each response's state per token + +* Bad, because it costs a room's whole state per response, per device. + +### Send the whole state whenever the room is forked + +* Bad, because a room that stays forked (common over federation) would send its whole state on every sync. + +### A persisted table of state changes (migration 004) + +* Good, because a restart would not cost one whole state per room. +* Bad, because it needs a migration on both backends, a row in every writer's transaction (including state + resolution's corrections), its own bound and pruning, worker classification and an upgrade answer. The answer for an + upgraded database would still be "send the whole state once", so the gain is only the first sync after each restart. + +### An in-memory log + +* Good, because it is exact, costs nothing for a window of messages, and touches no schema. +* Bad, because it starts empty at every start-up (see Negative Consequences). + +## Links + +* Supersedes the baseline and the chain walk of [ADR-0819](0819-a-state-after-delta-compares-the-two-states.md) +* Keeps the access rule of [ADR-0820](0820-a-left-rooms-state-after-stops-at-what-the-user-may-read.md) +* Relates to [ADR-0247](0247-no-sync-position-passes-a-stream-ordering-still-being-committed.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index d1afd2355..7395dc176 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -705,3 +705,4 @@ * [0824 - A delayed event is a stored row that is kept after it is finalised, bounded per user, and deleted with the account](0824-a-delayed-event-is-a-stored-row-kept-after-it-is-finalised-bounded-per-user-and-deleted-with-the-account.md) * [0825 - A due delayed event is sent by one job through the ordinary send path, never early and at least once](0825-a-due-delayed-event-is-sent-by-one-job-through-the-ordinary-send-path-never-early-and-at-least-once.md) * [0826 - Delayed events are on by default, with a maximum delay, per-user caps and per-user rate limits](0826-delayed-events-are-on-by-default-with-a-maximum-delay-per-user-caps-and-per-user-rate-limits.md) +* [0827 - A state_after delta is measured from an in-memory log of resolved state changes](0827-a-state-after-delta-is-measured-from-an-in-memory-log-of-resolved-state-changes.md) diff --git a/docs/database-persistence.md b/docs/database-persistence.md index 0194eaaf3..189907fbc 100644 --- a/docs/database-persistence.md +++ b/docs/database-persistence.md @@ -699,6 +699,12 @@ value. Test fixtures that do not exercise persistence select it through memory only: at most 1024 entries, the oldest dropped first, each naming the group that holds the state before an event for a room, a resolution context and sorted distinct prev groups. The same three writers forget the room. + `PersistentStore::state_change_log` is a `StateChangeLog` (ADR-0827), in memory + only and started by the main process after hydration: every change to a room's + current state, filed at the sync position from which a client sees it, at most + 1024 per room and 65536 in all, the oldest dropped first. The four writers of + `current_state` record into it and `apply_room_snapshot` forgets the room; + `/sync`'s `state_after` reads it. No table backs it, so nothing is migrated. **In-memory indexes (F-07, F-15, ADR-0325).** The three tables are mirrored in memory by `StateGroupTable`, `StateGroupEntryTable` and `EventStateGroupTable` diff --git a/docs/matrix-v1.19-client-server-api.md b/docs/matrix-v1.19-client-server-api.md index a3291849f..8c4d977a3 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -514,7 +514,7 @@ In each case below the spec leaves the choice to the server; the owner decided t - **An identifier over 255 bytes is refused (ADR-0613).** `GET /profile/{userId}` and `GET /directory/room/{roomAlias}` answer `400 M_INVALID_PARAM` before any lookup. The spec limits a user ID and a room alias to 255 bytes. - **Unset profile fields are absent.** `GET /profile/{userId}`, the user directory and `/search` `profile_info` leave out a `displayname` or `avatar_url` that is not set, instead of sending an empty string. - **`GET /rooms/{roomId}/messages` with `lazy_load_members`.** `state` holds only the `m.room.member` events of the senders of the returned `chunk` (no other state). Redundant membership events are not tracked across calls, so a sender's membership is sent on every page (the spec's `include_redundant_members` default permits it). -- **`use_state_after` on `/sync` (1.1.1, ADR-0818 to ADR-0820).** With `use_state_after=true`, joined and left rooms answer `state_after`, present even when empty, and omit `state`; with `false` or absent, the reverse. It is the state as of the response's position: all of it with no `since`, `full_state=true` or a join in the window, otherwise what differs from the state at `since`, including what the timeline carries, what the timeline filter hid and a key state resolution moved back, also on a `limited` sync. A left room's stops at the user's leave and always holds their own membership; `full_state` does not make it whole, but a room the user joined and left inside one window (or rejoined and left again) gets its whole readable state as of the leave, as the client held none of it. Invited and knocked rooms have no `state_after` in the spec and get none. With `lazy_load_members`, every member change is sent and each timeline sender's member is as of the end of the timeline. Sliding sync is unchanged. +- **`use_state_after` on `/sync` (1.1.1, ADR-0818 to ADR-0820).** With `use_state_after=true`, joined and left rooms answer `state_after`, present even when empty, and omit `state`; with `false` or absent, the reverse. It is the state as of the response's position: all of it with no `since`, `full_state=true` or a join in the window, otherwise what differs from the state the client was told at `since`, including what the timeline carries, what the timeline filter hid and a key state resolution moved back, also on a `limited` sync and on a room forked at `since` (1.1.3, ADR-0827: measured from an in-memory log of resolved state changes; a `since` from before a restart gets the room's whole state once). A left room's stops at the user's leave and always holds their own membership; `full_state` does not make it whole, but a room the user joined and left inside one window (or rejoined and left again) gets its whole readable state as of the leave, as the client held none of it. Invited and knocked rooms have no `state_after` in the spec and get none. With `lazy_load_members`, every member change is sent and each timeline sender's member is as of the end of the timeline. Sliding sync is unchanged. - **Lazy-loading on `/context` and `/sync` (0.12.73).** `GET /context` with `lazy_load_members` returns as `state` only the member events of the senders of `events_before`, `event` and `events_after` (stateless, redundancy allowed). `GET /sync` with `room.state.lazy_load_members` (the `timeline` flag does nothing) sends, besides the non-member state the room would carry without lazy-loading (the state filter still applies, and an incremental sync is a delta), the member events of the delivered timeline's senders, every member change in the gap of a limited sync, and the user's own membership on joining or `full_state=true`. A member the client acknowledged through its `since` is skipped (best effort, in memory, per user, device and `filter`); `include_redundant_members=true` and `full_state=true` skip nothing. `full_state=true` is now honoured for joined rooms. `use_state_after` is implemented (1.1.0, below). - **Initial `/sync` carries `m.push_rules`.** An initial `/sync` (no usable `since`) always holds a global `m.push_rules` account-data event with the user's effective ruleset (the server defaults plus their changes), if the filter's `account_data` admits it. An incremental `/sync` carries it only after a change. - **A hole in the event graph makes a joined room's `/sync` timeline `limited` (ADR-0289).** The spec defines `limited` by the filter `limit` and leaves events the server never received over federation unspecified; an event in the window whose `prev_events` are not all held (no row, or an outlier with no state group; rejected, soft-failed and backfilled events count as held, ADR-0290) starts a limited timeline at that event, with `prev_batch` for `/messages` to reach what lies before. A limited incremental sync carries the state at the start of the timeline. Sliding sync is unchanged. diff --git a/docs/todos/capability-gaps.md b/docs/todos/capability-gaps.md index 586abd72d..ebe247caf 100644 --- a/docs/todos/capability-gaps.md +++ b/docs/todos/capability-gaps.md @@ -69,7 +69,7 @@ When adding a capability, record what is *missing* as explicitly as what works. | `POST /_matrix/client/v3/rooms/{roomId}/receipt/{receiptType}/{eventId}` | `spec-covered` | 0.12.30: accepts `m.read`, `m.read.private`, and `m.fully_read`; rejects unknown types with 400 `M_INVALID_PARAM`, non-members with 403 `M_FORBIDDEN`, and malformed bodies with 400 `M_BAD_JSON`. `m.read` and `m.read.private` are durable receipt rows (ADR-0169), keyed by `(room, type, user, thread_id)`, so restarts preserve read positions. `thread_id` is optional for `m.read`/`m.read.private`, must be a non-empty string naming `main` or a thread root in this room, and is carried by `/sync` `m.receipt` events and federated `m.read` EDUs. `m.read` is public and federated; `m.read.private` is visible only to its sender and is not federated. `m.fully_read` is accepted without `thread_id`, rejected if `thread_id` is supplied, and stored as the owner's `m.fully_read` room account data rather than a receipt; it never appears in `m.receipt` or a federation EDU. Invalid `thread_id` values (including a non-root room event ID) return 400 `M_INVALID_PARAM`. 0.12.60: `/sync` delivers one `m.receipt` event per thread categorisation (unthreaded, `main`, each thread root), so a user's unthreaded and threaded `m.read` for one event both arrive; sliding sync's receipts extension still holds one event per room and keeps the latest receipt on such a clash. **Gap:** the optional 400 for "The event_id is not related to the thread_id" is not checked; the root's existence and main-timeline classification are checked, but the acknowledged event's relationship to it is not. | | `POST /_matrix/client/v3/user_directory/search` | `spec-covered` | 0.12.60: searches only the users visible to the requester (a shared joined room, or joined to a `public` or `world_readable` room), as Complement expects; the spec allows searching more. Remote users are still not queried (the spec says SHOULD). | | `POST /_matrix/client/v3/delete_devices` | `spec-covered` | | -| `GET /_matrix/client/v3/sync` | `spec-covered` | Unread-notification counts are relative to the user's read receipts, partitioned by thread (an unthreaded receipt covers every earlier event, a threaded one only its thread; 0.12.30), and bound to the response snapshot. 0.12.30: the `unread_thread_notifications` filter flag (on `room.timeline`) returns per-thread counts and limits `unread_notifications` to the main timeline, and a non-state event the user sends reads its own thread up to itself (ADR-0170). The `summary` object (`m.joined_member_count`, `m.invited_member_count`, `m.heroes`) is now emitted for every joined room and covered by conformance tests. `filter_id` parameter now wired and conformance-covered; sync-only stream tokens now bound to the response snapshot for to-device delivery so room keys queued during response construction remain pending for the next sync. 0.12.59: a joined room's `state` on an initial sync (or a newly joined room) is the state up to the start of the timeline, not current state. An incremental sync with a limited timeline sends the whole state up to the start of the timeline as `state`, which covers the gap between `since` and the timeline's start (not as a delta), and `state_after` holds what changed in the gap. 0.12.60: `rooms.leave` lists rooms the user left **or was banned from**; each holds the filtered timeline (types, senders, `contains_url` now apply to a `/sync` timeline, and a `limit` of 0 means none) up to the leave or ban, as the user may see it, and an initial sync's `state` as of the start of that timeline (as of the leave when it is empty). An incremental sync reports a leave once, after `since`; `include_leave` lists left rooms on an initial sync only. A forgotten room is never listed (the spec says so, although Complement `TestRoomForget` expects its leave in the next incremental sync). Timeline events carry `unsigned.membership` (the requesting user's membership at the event, `leave` before they had one) and, for the device that sent them, `unsigned.transaction_id`; the same two on `GET /rooms/{roomId}/event/{eventId}`. 0.12.71: sliding sync's timeline and `required_state` events carry the same two fields, and no read path serves a stored event's `unsigned` (a received PDU is stored without it; ADR-0402). **Not done:** both fields are absent from `/messages`, `/context`, `/relations` and `/search`, and transaction-ID idempotency is still scoped to the user, not the device (the spec scopes it to a device). 0.12.60: an initial `/sync` always carries a global `m.push_rules` event with the effective ruleset (defaults plus changes), as Complement expects; an incremental one only after a change. **Lazy-loading of room members (0.12.73, ADR-0450 to ADR-0454).** With `room.state.lazy_load_members`, `state` holds the non-member state as before and only these member events: the senders of the delivered timeline (as of its start, skipped when the client has acknowledged that very event through its `since`), every member change in the gap of a limited sync, and the user's own on joining or `full_state`. Redundancy is tracked in memory per (user, device, filter, room) and lost on restart; `include_redundant_members` and `full_state=true` bypass it. The same flag on `room.timeline` does nothing, and the state filter's `types`/`senders` apply to the members. `full_state=true` is now honoured for joined rooms. Not done: sliding sync. 1.1.1: `use_state_after` answers `state_after` and omits `state` for joined and left rooms, on initial and incremental sync, with `full_state` and with `lazy_load_members` (ADR-0818 to ADR-0820); invited and knocked rooms have no such field. **Not done (accepted limit, ADR-0819):** after a state fork at `since`, a key that state resolution later flips back to the value recorded at `since` is not sent in `state_after`, because the delta compares against the state recorded for the event at `since`, not the state the client was told; `full_state=true` repairs the client. Storing each response's state per token would close it and was refused for its cost. | +| `GET /_matrix/client/v3/sync` | `spec-covered` | Unread-notification counts are relative to the user's read receipts, partitioned by thread (an unthreaded receipt covers every earlier event, a threaded one only its thread; 0.12.30), and bound to the response snapshot. 0.12.30: the `unread_thread_notifications` filter flag (on `room.timeline`) returns per-thread counts and limits `unread_notifications` to the main timeline, and a non-state event the user sends reads its own thread up to itself (ADR-0170). The `summary` object (`m.joined_member_count`, `m.invited_member_count`, `m.heroes`) is now emitted for every joined room and covered by conformance tests. `filter_id` parameter now wired and conformance-covered; sync-only stream tokens now bound to the response snapshot for to-device delivery so room keys queued during response construction remain pending for the next sync. 0.12.59: a joined room's `state` on an initial sync (or a newly joined room) is the state up to the start of the timeline, not current state. An incremental sync with a limited timeline sends the whole state up to the start of the timeline as `state`, which covers the gap between `since` and the timeline's start (not as a delta), and `state_after` holds what changed in the gap. 0.12.60: `rooms.leave` lists rooms the user left **or was banned from**; each holds the filtered timeline (types, senders, `contains_url` now apply to a `/sync` timeline, and a `limit` of 0 means none) up to the leave or ban, as the user may see it, and an initial sync's `state` as of the start of that timeline (as of the leave when it is empty). An incremental sync reports a leave once, after `since`; `include_leave` lists left rooms on an initial sync only. A forgotten room is never listed (the spec says so, although Complement `TestRoomForget` expects its leave in the next incremental sync). Timeline events carry `unsigned.membership` (the requesting user's membership at the event, `leave` before they had one) and, for the device that sent them, `unsigned.transaction_id`; the same two on `GET /rooms/{roomId}/event/{eventId}`. 0.12.71: sliding sync's timeline and `required_state` events carry the same two fields, and no read path serves a stored event's `unsigned` (a received PDU is stored without it; ADR-0402). **Not done:** both fields are absent from `/messages`, `/context`, `/relations` and `/search`, and transaction-ID idempotency is still scoped to the user, not the device (the spec scopes it to a device). 0.12.60: an initial `/sync` always carries a global `m.push_rules` event with the effective ruleset (defaults plus changes), as Complement expects; an incremental one only after a change. **Lazy-loading of room members (0.12.73, ADR-0450 to ADR-0454).** With `room.state.lazy_load_members`, `state` holds the non-member state as before and only these member events: the senders of the delivered timeline (as of its start, skipped when the client has acknowledged that very event through its `since`), every member change in the gap of a limited sync, and the user's own on joining or `full_state`. Redundancy is tracked in memory per (user, device, filter, room) and lost on restart; `include_redundant_members` and `full_state=true` bypass it. The same flag on `room.timeline` does nothing, and the state filter's `types`/`senders` apply to the members. `full_state=true` is now honoured for joined rooms. Not done: sliding sync. 1.1.1: `use_state_after` answers `state_after` and omits `state` for joined and left rooms, on initial and incremental sync, with `full_state` and with `lazy_load_members` (ADR-0818 to ADR-0820); invited and knocked rooms have no such field. 1.1.3: the delta is measured from the resolved state the client was told at `since`, read from an in-memory log of state changes, so a fork at `since`, a key resolution moves back and a backfilled event are all sent exactly; a `since` from before a restart gets the room's whole state once (ADR-0827). | | `GET /_matrix/client/v3/keys/changes` | `spec-covered` | Requires and validates `from` and `to` sync tokens, decodes them to `sync_stream_id` boundaries, and filters `changed`/`left` device-list changes to that half-open range. Conformance coverage includes missing/invalid parameters and an upper-bound test proving `to` excludes later changes. | | Remote device-list cache | `spec-covered` | Server-Server API v1.19 "Device Management". 0.12.81 (G14, ADR-0560, ADR-0561): the list of a remote user who shares a joined room with a local user is filled from `GET /user/devices/{userId}` (its `stream_id` places later updates) and kept in memory, bounded per user and in all. `m.device_list_update` EDUs apply in `stream_id` order; a `prev_id` above the snapshot that was never applied, or an empty one, marks the list stale and the next `/keys/query` fetches it again; `m.signing_key_update` does the same. An update that changes nothing is no longer reported in `device_lists.changed`. Not persisted: a restart refills on demand. Complement `TestDeviceListsUpdateOverFederation` (three subtests) stays skip-listed until it is run against this change. | | `POST /_matrix/client/v4/sync` and `POST /_matrix/client/unstable/org.matrix.msc4186/sync` (MSC4186 Simplified Sliding Sync) | `spec-covered` | Advertised via `unstable_features["org.matrix.msc4186"] = true` and the compatibility alias `unstable_features["org.matrix.simplified_msc3575"] = true`; the stable `v4` endpoint is now also routed and accepts the same request shape. Implements named lists with windowed `ranges` or singular `range`, SYNC/INVALIDATE/INSERT/DELETE/UPDATE ops, per-room state/timeline, room subscriptions, and all five extensions (to_device, e2ee, account_data, receipts, typing). Long-poll parks in the notifier's registry and holds no sync-pool thread while it waits (ADR-0569); `pos` and `timeout` may be supplied in query parameters or in the JSON body. List + `room_subscriptions` merge: when a room is in both a list window and a `room_subscriptions` entry, `required_state` is the superset (dedup + wildcard-aware), `timeline_limit` is the max, and `include_heroes` is OR'd (previously the subscription overrode the list wholesale) — landed 0.11.9. Multi-list combination: a room in MORE THAN ONE list window now has ALL matching list windows combined (left-fold over `combine_room_configs`, associative+commutative) with each other and the `room_subscriptions` entry, not just the first matching list — landed 0.11.10. Access control (CSAZ-1): a `room_subscriptions` entry is served only for a room the caller has joined; an invited room yields `invite_state` only (no timeline or `required_state`); any other membership omits the room, and the receipts/typing extensions drop rooms the caller has not joined. `timeline_limit` is clamped to 100, and more than 256 subscriptions or 256 `required_state` pairs is a 400 `M_INVALID_PARAM` (`sync::room_access_for`, `sliding_sync_request_limit_violation`). Truncated timelines (0.12.45): a room carries `limited` when its timeline holds fewer events than it could, `prev_batch` (a `/messages` `from`) on every non-empty timeline, `num_live`, and on a grown `timeline_limit` resends its latest events with `expanded_timeline`, answering without long-polling once per request `pos` (ADR-0221). Remaining: broader MSC4186 conformance fixtures, subscription timeline pruning, and `bump_stamp`, which is never sent (Element X orders its room list by it). | diff --git a/include/merovingian/database/PersistentStore.hpp b/include/merovingian/database/PersistentStore.hpp index 743b5eddb..f43e7be0b 100644 --- a/include/merovingian/database/PersistentStore.hpp +++ b/include/merovingian/database/PersistentStore.hpp @@ -88,6 +88,7 @@ #include "merovingian/database/RowKeyIndex.hpp" #include "merovingian/database/SchemaState.hpp" #include "merovingian/database/StateBeforeMemo.hpp" +#include "merovingian/database/StateChangeLog.hpp" #include "merovingian/database/StateGroupEntryTable.hpp" #include "merovingian/database/StateGroupTable.hpp" #include "merovingian/database/TableLoadProfile.hpp" @@ -613,6 +614,12 @@ struct PersistentStore final // How many times each room's current state, or the status or JSON of one of its events, has changed // (`room_state_revision`, ADR-0624). In memory only. std::unordered_map room_state_revisions{}; + // Every change to a room's current state since start-up, by the sync position from which a client sees it, for + // `/sync`'s `state_after` (ADR-0827). In memory only, and inactive until the main process starts it. The four + // writers of current state (`apply_store_event_with_state`, `apply_current_state`, `store_state` and + // `remove_current_state_rows`) record into it, and `apply_room_snapshot` forgets the room. A new writer of `state` + // records too. + StateChangeLog state_change_log{}; // Stored events parsed for state resolution, for tests that prove cost. ExaminedRows state_events_parsed{}; // Test-only capture of committed statements (AUTH-11). Empty and disabled @@ -961,7 +968,10 @@ auto rebuild_invite_indexes(PersistentStore& store) -> void; [[nodiscard]] auto store_room_with_membership(PersistentStore& store, PersistentRoom room, PersistentMembership membership) -> bool; [[nodiscard]] auto store_event(PersistentStore& store, PersistentEvent event) -> bool; -[[nodiscard]] auto store_state(PersistentStore& store, PersistentStateEvent state) -> bool; +// `causing_stream_ordering` is the stream ordering of the event whose storing made this change, 0 for none; the state +// change log files the change there or above (ADR-0827). +[[nodiscard]] auto store_state(PersistentStore& store, PersistentStateEvent state, + std::uint64_t causing_stream_ordering = 0U) -> bool; // The statements that make `state` current, replacing `previous_event_id` // (empty for a key with no current_state row yet), and record the transition. @@ -970,8 +980,10 @@ auto rebuild_invite_indexes(PersistentStore& store) -> void; [[nodiscard]] auto prepare_current_state(PersistentStateEvent state, std::string previous_event_id) -> PreparedCurrentState; // Mirrors a committed prepare_current_state into current_state and the -// state_transitions index. -auto apply_current_state(PersistentStore& store, PreparedCurrentState const& prepared) -> void; +// state_transitions index, and records the change in the state change log as made by the event at +// `causing_stream_ordering` (0 for none, ADR-0827). +auto apply_current_state(PersistentStore& store, PreparedCurrentState const& prepared, + std::uint64_t causing_stream_ordering = 0U) -> void; // True when `state` names a stored event of that type and state key in that room. [[nodiscard]] auto state_matches_stored_event(PersistentStore const& store, PersistentStateEvent const& state) -> bool; // With `membership`, also writes that membership row and invite change in the same @@ -989,9 +1001,11 @@ auto apply_current_state(PersistentStore& store, PreparedCurrentState const& pre MembershipProjection projection) -> bool; // Removes `keys` (event type, state key) from `room_id`'s current state and writes `memberships`, in one transaction, // then mirrors both, keeping the state indexes in step (ADR-0615). Costs the rows of the rooms that lose or move a row. +// Each key removed is recorded in the state change log as made by the event at `causing_stream_ordering` (ADR-0827). [[nodiscard]] auto remove_current_state_rows(PersistentStore& store, std::string_view room_id, std::vector> const& keys, - std::vector const& memberships) -> bool; + std::vector const& memberships, + std::uint64_t causing_stream_ordering = 0U) -> bool; // DB-4: makes each `membership` row agree with its room's current m.room.member // state event, which is the user's membership (Matrix v1.19 "m.room.member"). // A row is rewritten to the event's membership when the row is missing, when it diff --git a/include/merovingian/database/StateChangeLog.hpp b/include/merovingian/database/StateChangeLog.hpp new file mode 100644 index 000000000..38cd9c013 --- /dev/null +++ b/include/merovingian/database/StateChangeLog.hpp @@ -0,0 +1,112 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/ExaminedRows.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::database +{ + +// Every change to a room's resolved current state since the process started, keyed by the sync position from which a +// client sees it (ADR-0827). `/sync`'s `state_after` reads it to tell a client exactly what changed between two +// positions, whatever the shape of the event graph: the state at a position is the current state with each key changed +// above that position put back to the value its first such change replaced. +// +// The key of a change is the stream ordering of the event whose storing made it, raised above every position a sync +// has already answered (`note_served`), so a change is never filed at or below a position a client was told about +// before it happened. A key is therefore final once the position is served, and the state as of a served position never +// changes. +// +// In memory only, and inactive until `start`: the federation worker, which serves no sync, records nothing. It is +// bounded per room and in all; dropping a room's oldest change raises that room's horizon, and a position below the +// horizon is no longer covered, so the caller sends the whole state there (an update the client already holds is +// harmless). Not thread-safe: every call is made with `runtime.mutex` held, as every writer of current state and every +// sync holds it. +class StateChangeLog final +{ +public: + // One change of one key. An empty `previous_event_id` is a key that had no value; an empty `event_id` a key + // removed. + struct Change final + { + std::string event_type{}; + std::string state_key{}; + std::string previous_event_id{}; + std::string event_id{}; + std::uint64_t position{0U}; + }; + + // At most this many changes are held for one room, and in all. Past either the oldest go first. + static constexpr auto max_changes_per_room = std::size_t{1024U}; + static constexpr auto max_changes = std::size_t{65536U}; + + // Starts recording. Every position at or below `floor` predates the log, so it is covered for no room, and the + // first change is filed above it. Clears anything recorded before. + auto start(std::uint64_t floor) -> void; + [[nodiscard]] auto active() const noexcept -> bool; + + // Records that a sync answered as of `position`: a change recorded afterwards is filed above it. + auto note_served(std::uint64_t position) noexcept -> void; + + // Records that `room_id`'s value for (`event_type`, `state_key`) went from `previous_event_id` to `event_id`, made + // by storing the event at stream ordering `causing_position` (0 when no event caused it). Nothing when inactive or + // when the value did not change. + auto record(std::string_view room_id, std::string_view event_type, std::string_view state_key, + std::string_view previous_event_id, std::string_view event_id, std::uint64_t causing_position) -> void; + + // Forgets `room_id`'s changes, for a writer that replaced its current state wholesale (a room reload): no position + // served so far is covered for it any more, and the state as of any later one is rebuilt from the new rows. + auto forget_room(std::string_view room_id) -> void; + + // Whether every change of `room_id` above `position` is held, so the state as of `position` can be rebuilt, and + // `position` is above the floor, so a state a client was told as of it was told by this process from this log. + [[nodiscard]] auto covers(std::string_view room_id, std::uint64_t position) const -> bool; + + // Whether `room_id` has a change above `position`. One lookup. + [[nodiscard]] auto has_change_after(std::string_view room_id, std::uint64_t position) const -> bool; + + // The changes of `room_id` above `position`, by position and, at one position, in the order they were made. Each + // one returned is counted in `rows_examined`. The pointers stay valid until the next call that records or starts. + [[nodiscard]] auto changes_after(std::string_view room_id, std::uint64_t position) const + -> std::vector; + + // The number of changes held, for every room. + [[nodiscard]] auto size() const noexcept -> std::size_t; + + // The changes `changes_after` returned, so a test proves a reader's cost by count, not by time. + [[nodiscard]] auto rows_examined() const noexcept -> ExaminedRows const&; + +private: + // A room's changes keyed by (position, sequence), and the position at or below which its changes are no longer all + // held. + struct RoomChanges final + { + std::map, Change> changes{}; + std::uint64_t horizon{0U}; + }; + + // The lowest position no sync has been answered at. + [[nodiscard]] auto above_served() const noexcept -> std::uint64_t; + auto drop_oldest_of_room(RoomChanges& room) -> void; + auto drop_oldest() -> void; + + bool m_active{false}; + std::uint64_t m_floor{0U}; + std::uint64_t m_served{0U}; + std::uint64_t m_next_sequence{0U}; + std::unordered_map m_rooms{}; + // Every held change by sequence, oldest first: its room and position, so the oldest can be dropped in O(log n). + std::map> m_order{}; + ExaminedRows m_rows_examined{}; +}; + +} // namespace merovingian::database diff --git a/include/merovingian/sync/ResolvedState.hpp b/include/merovingian/sync/ResolvedState.hpp new file mode 100644 index 000000000..296edeb8c --- /dev/null +++ b/include/merovingian/sync/ResolvedState.hpp @@ -0,0 +1,41 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/PersistentStore.hpp" + +#include +#include +#include +#include +#include + +namespace merovingian::sync +{ + +// A room's resolved state as of a sync position, rebuilt from its current state and the store's state change log +// (ADR-0827): each key the log shows changed above `position` takes the value its first such change replaced, a key +// with no value then is left out. nullopt when the log does not cover `position` for the room (before this process +// started, or past what it still holds). Reads the room's state rows once, plus its changes above `position`. +[[nodiscard]] auto resolved_state_at(database::PersistentStore const& store, std::string_view room_id, + std::uint64_t position) -> std::optional>; + +// The event (`event_type`, `state_key`) of the room held as of `position`, empty when it held none: the value its first +// change above `position` replaced, else its current one. nullopt when the log does not cover `position`. Costs the +// room's changes above `position`, none when `position` is the newest, and one lookup by key. +[[nodiscard]] auto resolved_state_event_at(database::PersistentStore const& store, std::string_view room_id, + std::string_view event_type, std::string_view state_key, + std::uint64_t position) -> std::optional; + +// The events that make the room's resolved state at `position` differ from its resolved state at `since`, one per key +// whose value differs and has one at `position` (`state_after`, ADR-0827). Exact for every pair of positions the log +// covers, whatever the event graph: both states are read from the same record, so a key resolution moved back is found +// and a key that changed and changed back is not sent. nullopt when the log does not cover `since`. +// +// Cost: the room's changes above `since`, counted in the log's `rows_examined`, and one state lookup by key for each +// key they name. Nothing for a window with no state change, never a read of the room's whole state. +[[nodiscard]] auto resolved_state_changes(database::PersistentStore const& store, std::string_view room_id, + std::uint64_t since, std::uint64_t position) + -> std::optional>; + +} // namespace merovingian::sync diff --git a/include/merovingian/sync/StateGroupLookup.hpp b/include/merovingian/sync/StateGroupLookup.hpp index b1f925706..2de037fce 100644 --- a/include/merovingian/sync/StateGroupLookup.hpp +++ b/include/merovingian/sync/StateGroupLookup.hpp @@ -5,10 +5,7 @@ #include "merovingian/database/PersistentStore.hpp" #include "merovingian/sync/GroupLookupResult.hpp" -#include -#include #include -#include namespace merovingian::sync { @@ -20,12 +17,4 @@ namespace merovingian::sync [[nodiscard]] auto lookup_state_in_group(database::PersistentStore const& store, std::string_view group_id, std::string_view event_type, std::string_view state_key) -> GroupLookupResult; -// The event IDs of the state `group_id` holds that differs from what its ancestor `ancestor_id` holds: the newest row -// of each key on the delta chain from `group_id` down to, not including, `ancestor_id`. Empty when the two are one -// group. Nullopt when `ancestor_id` is not on the chain (a snapshot, a missing group or a cycle comes first), and the -// caller compares the two states. It costs the rows of the groups between the two, not the room's state: a snapshot's -// rows are never read. A key that changed and changed back is reported, with the value it holds. -[[nodiscard]] auto state_changes_along_chain(database::PersistentStore const& store, std::string_view ancestor_id, - std::string_view group_id) -> std::optional>; - } // namespace merovingian::sync diff --git a/src/database/AGENTS.md b/src/database/AGENTS.md index 728be821d..d9dd084fa 100644 --- a/src/database/AGENTS.md +++ b/src/database/AGENTS.md @@ -31,6 +31,7 @@ Manages schema migrations and provides a dual-backend (SQLite / PostgreSQL) pers | `RoomAliasTable.cpp` | `RoomAliasTable`, the in-memory mirror of `room_aliases` with indexes by alias, room and creator (ADR-0581) | | `ForwardExtremityTable.cpp` | `ForwardExtremityTable`, a room's tips with a count per server of their sender (ADR-0602) | | `ResolvedStateMemo.cpp` | `ResolvedStateMemo`, each room's last resolved state, bounded and in memory only (ADR-0600) | +| `StateChangeLog.cpp` | `StateChangeLog`, every change to a room's resolved current state since start-up, filed at the sync position from which a client sees it and never at or below one already served; bounded per room (1,024) and in all (65,536), in memory only, started by the main process alone (ADR-0827) | | `StateBeforeMemo.cpp` | `StateBeforeMemo`, the group holding the state before an event by its distinct prev groups, bounded and in memory only (ADR-0694) | | `StateGroupTable.cpp`, `StateGroupEntryTable.cpp`, `EventStateGroupTable.cpp` | The state-group tables with their hash indexes (ADR-0325); their shared rules are in `StateGroupTableSupport.hpp` | | `RuntimeDatabaseConfig.cpp` | Exposes the live store to the rest of the server | @@ -136,6 +137,16 @@ calls `note_state_row_appended` or `rebuild_state_index` (the two writers in `Pe and both hydration paths) or, for a deletion, goes through `remove_current_state_rows` (ADR-0615); a new one must too. Do not scan `state` for one key or one room in a handler. Both readers add the rows they look at to `state_rows_examined`; tests prove a handler's state reads with it. +## The state change log (ADR-0827) + +`PersistentStore::state_change_log` is what `/sync`'s `state_after` reads (see `src/sync/AGENTS.md`). Every in-memory change +of `state` in the main process records into it: `apply_store_event_with_state` (at the event's stream ordering), +`apply_current_state`, `store_state` and `remove_current_state_rows` (each with the causing event's ordering, which state +resolution passes through, 0 when none), and `apply_room_snapshot` calls `forget_room`. A new writer of `state` records too, +with the value the mirror held before (not the one a statement was prepared against), or a client is told a delta that is +wrong. The log is started after hydration and repair, so start-up writes are not changes; the federation worker never starts +it. It is not thread-safe: every caller holds `runtime.mutex`. + ## Per-user and per-ID indexes (ADR-0440, ADR-0441) `account_data_user_index`, `notification_user_index` and `federation_transaction_index` follow the state index's rule: diff --git a/src/database/PersistentStore.cpp b/src/database/PersistentStore.cpp index 86987c7a7..49599829e 100644 --- a/src/database/PersistentStore.cpp +++ b/src/database/PersistentStore.cpp @@ -3024,6 +3024,7 @@ auto apply_room_snapshot(PersistentStore& store, RoomReloadSnapshot snapshot) -> auto const& room_id = snapshot.room_id; store.resolved_state_memo.forget_room(room_id); store.state_before_memo.forget_room(room_id); + store.state_change_log.forget_room(room_id); ++store.room_state_revisions[room_id]; // Replace this room's slice of the store: drop every existing row keyed @@ -4188,7 +4189,8 @@ namespace // Takes `keys` out of `state`, filling each gap from the end, and leaves the indexes in step (ADR-0615). Only the // rooms that lost or moved a row have their position lists rewritten. auto remove_state_rows_from_mirror(PersistentStore& store, std::string_view room_id, - std::vector> const& keys) -> void + std::vector> const& keys, + std::uint64_t causing_stream_ordering) -> void { if (store.state_indexed_rows != store.state.size()) { @@ -4200,6 +4202,8 @@ namespace auto const entry = store.state_position_index.find(state_position_key(room_id, event_type, state_key)); if (entry != store.state_position_index.end()) { + store.state_change_log.record(room_id, event_type, state_key, store.state[entry->second].event_id, {}, + causing_stream_ordering); removed.insert(entry->second); store.state_position_index.erase(entry); } @@ -4259,7 +4263,8 @@ namespace auto remove_current_state_rows(PersistentStore& store, std::string_view room_id, std::vector> const& keys, - std::vector const& memberships) -> bool + std::vector const& memberships, + std::uint64_t causing_stream_ordering) -> bool { auto statements = std::vector{}; if (room_id.empty()) @@ -4285,7 +4290,7 @@ auto remove_current_state_rows(PersistentStore& store, std::string_view room_id, { return false; } - remove_state_rows_from_mirror(store, room_id, keys); + remove_state_rows_from_mirror(store, room_id, keys, causing_stream_ordering); if (!keys.empty()) { note_room_state_changed(store, std::string{room_id}); @@ -4586,7 +4591,8 @@ namespace return true; } -[[nodiscard]] auto store_state(PersistentStore& store, PersistentStateEvent state) -> bool +[[nodiscard]] auto store_state(PersistentStore& store, PersistentStateEvent state, + std::uint64_t causing_stream_ordering) -> bool { if (!state_matches_persisted_event(store, state)) { @@ -4608,7 +4614,7 @@ namespace { return false; } - apply_current_state(store, prepared); + apply_current_state(store, prepared, causing_stream_ordering); return true; } @@ -4668,7 +4674,8 @@ namespace return {std::move(state), std::move(previous_event_id), std::move(statements)}; } -auto apply_current_state(PersistentStore& store, PreparedCurrentState const& prepared) -> void +auto apply_current_state(PersistentStore& store, PreparedCurrentState const& prepared, + std::uint64_t causing_stream_ordering) -> void { auto const& state = prepared.state; note_room_state_changed(store, state.room_id); @@ -4677,6 +4684,11 @@ auto apply_current_state(PersistentStore& store, PreparedCurrentState const& pre return current.room_id == state.room_id && current.event_type == state.event_type && current.state_key == state.state_key; }); + // The value the mirror held, not the one the statement was prepared against: the log chains what clients saw. + store.state_change_log.record(state.room_id, state.event_type, state.state_key, + existing != store.state.end() ? std::string_view{existing->event_id} + : std::string_view{}, + state.event_id, causing_stream_ordering); if (existing != store.state.end()) { existing->event_id = state.event_id; @@ -4856,6 +4868,10 @@ auto apply_store_event_with_state(PersistentStore& store, PreparedStateUpdate co return current.room_id == update.state->room_id && current.event_type == update.state->event_type && current.state_key == update.state->state_key; }); + store.state_change_log.record(update.state->room_id, update.state->event_type, update.state->state_key, + existing != store.state.end() ? std::string_view{existing->event_id} + : std::string_view{}, + update.state->event_id, update.event.stream_ordering); if (existing != store.state.end()) { existing->event_id = update.state->event_id; diff --git a/src/database/StateChangeLog.cpp b/src/database/StateChangeLog.cpp new file mode 100644 index 000000000..04aa43d53 --- /dev/null +++ b/src/database/StateChangeLog.cpp @@ -0,0 +1,142 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/database/StateChangeLog.hpp" + +#include +#include + +namespace merovingian::database +{ + +auto StateChangeLog::start(std::uint64_t floor) -> void +{ + m_active = true; + m_floor = floor; + m_served = floor; + m_rooms.clear(); + m_order.clear(); +} + +auto StateChangeLog::active() const noexcept -> bool +{ + return m_active; +} + +auto StateChangeLog::note_served(std::uint64_t position) noexcept -> void +{ + m_served = std::max(m_served, position); +} + +auto StateChangeLog::forget_room(std::string_view room_id) -> void +{ + if (!m_active) + { + return; + } + auto& room = m_rooms[std::string{room_id}]; + for (auto const& entry : room.changes) + { + m_order.erase(entry.first.second); + } + room.changes.clear(); + room.horizon = std::max(room.horizon, above_served()); +} + +auto StateChangeLog::record(std::string_view room_id, std::string_view event_type, std::string_view state_key, + std::string_view previous_event_id, std::string_view event_id, + std::uint64_t causing_position) -> void +{ + if (!m_active || previous_event_id == event_id) + { + return; + } + // Above every position a client has been answered at, so no answer already given is changed by this one; a + // position past the last one representable is never served, and the change is filed there. + auto const position = std::max(causing_position, above_served()); + auto const sequence = m_next_sequence++; + auto const room = m_rooms.try_emplace(std::string{room_id}).first; + room->second.changes.emplace(std::pair{position, sequence}, + Change{std::string{event_type}, std::string{state_key}, std::string{previous_event_id}, + std::string{event_id}, position}); + m_order.emplace(sequence, std::pair{room->first, position}); + if (room->second.changes.size() > max_changes_per_room) + { + drop_oldest_of_room(room->second); + } + while (m_order.size() > max_changes) + { + drop_oldest(); + } +} + +auto StateChangeLog::covers(std::string_view room_id, std::uint64_t position) const -> bool +{ + if (!m_active || position <= m_floor) + { + return false; + } + auto const room = m_rooms.find(std::string{room_id}); + return room == m_rooms.end() || position >= room->second.horizon; +} + +auto StateChangeLog::has_change_after(std::string_view room_id, std::uint64_t position) const -> bool +{ + auto const room = m_rooms.find(std::string{room_id}); + return room != m_rooms.end() && !room->second.changes.empty() && + room->second.changes.rbegin()->first.first > position; +} + +auto StateChangeLog::changes_after(std::string_view room_id, std::uint64_t position) const -> std::vector +{ + auto found = std::vector{}; + auto const room = m_rooms.find(std::string{room_id}); + if (room == m_rooms.end() || position == std::numeric_limits::max()) + { + return found; + } + auto const& changes = room->second.changes; + for (auto it = changes.lower_bound(std::pair{position + 1U, std::uint64_t{0U}}); it != changes.end(); ++it) + { + found.push_back(&it->second); + } + m_rows_examined.add(found.size()); + return found; +} + +auto StateChangeLog::size() const noexcept -> std::size_t +{ + return m_order.size(); +} + +auto StateChangeLog::rows_examined() const noexcept -> ExaminedRows const& +{ + return m_rows_examined; +} + +auto StateChangeLog::above_served() const noexcept -> std::uint64_t +{ + // A position past the last one representable is never served, and a change is filed there. + return m_served == std::numeric_limits::max() ? m_served : m_served + 1U; +} + +auto StateChangeLog::drop_oldest_of_room(RoomChanges& room) -> void +{ + auto const oldest = room.changes.begin(); + room.horizon = std::max(room.horizon, oldest->first.first); + m_order.erase(oldest->first.second); + room.changes.erase(oldest); +} + +auto StateChangeLog::drop_oldest() -> void +{ + auto const oldest = m_order.begin(); + auto const& [room_id, position] = oldest->second; + if (auto const room = m_rooms.find(room_id); room != m_rooms.end()) + { + room->second.horizon = std::max(room->second.horizon, position); + room->second.changes.erase(std::pair{position, oldest->first}); + } + m_order.erase(oldest); +} + +} // namespace merovingian::database diff --git a/src/database/meson.build b/src/database/meson.build index 538b14505..e7ca77857 100644 --- a/src/database/meson.build +++ b/src/database/meson.build @@ -20,6 +20,7 @@ database_sources = files( 'PostgresqlResultDeleter.cpp', 'ResolvedStateMemo.cpp', 'StateBeforeMemo.cpp', + 'StateChangeLog.cpp', 'RoomAliasTable.cpp', 'RedactionView.cpp', 'PostgresqlStore.cpp', diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index 9f519a9fd..e248d2ce6 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -180,6 +180,7 @@ #include "merovingian/sync/PreparedRoomEventFilter.hpp" #include "merovingian/sync/ReceiptContentBuilder.hpp" #include "merovingian/sync/ReceiptVisibility.hpp" +#include "merovingian/sync/ResolvedState.hpp" #include "merovingian/sync/RoomAccess.hpp" #include "merovingian/sync/RoomFilter.hpp" #include "merovingian/sync/RoomListResult.hpp" @@ -5918,60 +5919,46 @@ namespace }); } - // ADR-0819: the IDs of the state events that make a joined room's state at `position` differ from its state at - // `since_ordering`, for `state_after`. A key can change with no event of the window about it (state resolution can - // move it back), so this compares the two states; it does not list the window's state events. + // ADR-0827: a joined room's resolved state as of `position`, which is what a `state_after` client is told and what + // a later delta is measured from. Rebuilt from the current state and the state change log; where the log does not + // reach `position` (at or before start-up, or past what it holds for the room) it is the state ADR-0247 reads, and + // a delta from such a position is never taken, so the two cannot disagree. + [[nodiscard]] auto resolved_state_event_ids_at_position(database::PersistentStore const& store, + std::string_view room_id, std::uint64_t position) + -> std::vector + { + if (auto ids = sync::resolved_state_at(store, room_id, position); ids.has_value()) + { + return std::move(*ids); + } + return state_event_ids_at_position(store, room_id, position); + } + + // ADR-0827: the IDs of the state events that make a joined room's resolved state at `position` differ from its + // resolved state at `since_ordering`, the state the response carrying that token told the client. Both are read + // from the one record of changes, so the delta is exact whatever the event graph: a fork at `since`, a key state + // resolution moved back, and a backfilled event ordered at or below `since` (its change is filed above every + // position already answered) are all found, and a key that changed and changed back is not sent. // - // Cost: nothing for a room with no event since `since` (one look at the newest row). Otherwise the anchor at - // `since` is a binary search of the room's index plus the withheld rows stepped over below it, however many rows - // the window holds (`state_anchor_rows_examined`). With an unforked graph, then the state group rows between the - // two points, none for a window of messages. Otherwise (a fork, a snapshot between the points, an unreadable chain) - // it reads the room's state twice, its own rows only. + // Cost: the room's changes above `since` and one lookup by key for each key they name; nothing for a window of + // messages. Only a `since` the log does not cover (answered before start-up, or older than what the log holds for + // the room) reads the room's whole state, once: an update the client already holds is harmless. [[nodiscard]] auto joined_state_changes(database::PersistentStore const& store, std::string_view room_id, std::uint64_t since_ordering, std::uint64_t position) -> std::vector { - auto newest_first = store.events.room_in_stream_order(room_id) | std::views::reverse; - if (std::ranges::empty(newest_first) || (*newest_first.begin()).stream_ordering <= since_ordering) + if (auto changes = sync::resolved_state_changes(store, room_id, since_ordering, position); changes.has_value()) { - return {}; - } - auto const access = sync::RoomReadAccess{sync::RoomReadKind::current, {}, 0U}; - auto const* const since_anchor = sync::state_anchor_event(store, room_id, access, since_ordering); - auto const since_group = since_anchor == nullptr - ? std::optional{} - : database::find_event_state_group(store, since_anchor->event_id); - if (since_group.has_value()) - { - // With one extremity the current state is that event's recorded state (ADR-0064). The forward extremity - // index answers for one room: it costs that room's tips. - auto const tips = store.forward_extremities.tips_of_room(room_id); - if (tips.size() == 1U) - { - auto const tip = store.events.find(tips.front()); - auto const tip_group = tip != store.events.end() && tip->stream_ordering <= position - ? database::find_event_state_group(store, tip->event_id) - : std::optional{}; - if (tip_group.has_value()) - { - if (auto changes = sync::state_changes_along_chain(store, *since_group, *tip_group); - changes.has_value()) - { - return std::move(*changes); - } - } - } + return std::move(*changes); } - auto changes = state_event_ids_at_position(store, room_id, position); - // A `since` older than anything recorded here gets all of it: an update the client already holds is harmless. - if (since_anchor != nullptr) + auto newest_first = store.events.room_in_stream_order(room_id) | std::views::reverse; + if ((std::ranges::empty(newest_first) || (*newest_first.begin()).stream_ordering <= since_ordering) && + !store.state_change_log.has_change_after(room_id, since_ordering)) { - if (auto const held = sync::state_event_ids_after(store, *since_anchor); held.has_value()) - { - remove_state_held(changes, *held); - } + // Nothing happened in the room since `since`, in this process or as far as its events show. + return {}; } - return changes; + return resolved_state_event_ids_at_position(store, room_id, position); } // Whether a timeline carries the join of `user_id`: the join then tells the client everything the spec's "own @@ -6049,6 +6036,15 @@ namespace std::string_view sender, UnreadableMember unreadable) -> std::optional { + // ADR-0827: a joined room's member as of `position` is the resolved one, as its `state_after` delta reads it. + if (access.kind == sync::RoomReadKind::current) + { + if (auto const resolved = sync::resolved_state_event_at(store, room_id, "m.room.member", sender, position); + resolved.has_value()) + { + return resolved->empty() ? std::optional{} : std::optional{*resolved}; + } + } auto const current = database::find_current_state_event_id(store, room_id, "m.room.member", sender); if (current.has_value()) { @@ -6403,8 +6399,9 @@ namespace // news was dropped (ADR-0658). [[nodiscard]] auto select_sync_rooms(ClientServerRuntime const& rt, database::PersistentStore const& store, std::string_view user, sync::SyncFilter const& filter, bool incremental, - std::uint64_t since_ordering, std::uint64_t since_sync_stream_id, - AccountDataByRoom const& user_account_data) -> std::vector + bool use_state_after, std::uint64_t since_ordering, + std::uint64_t since_sync_stream_id, AccountDataByRoom const& user_account_data) + -> std::vector { struct Candidate final { @@ -6439,6 +6436,12 @@ namespace { return false; } + // ADR-0827: state resolution can change a room's state with no event above `since` (a backfilled + // event's change is filed above every position answered); `state_after` reports it. One lookup. + if (use_state_after && store.state_change_log.has_change_after(room_id, since_ordering)) + { + return false; + } if (auto const rows = user_account_data.find(room_id); rows != user_account_data.end() && std::ranges::any_of(rows->second, [&](database::PersistentAccountData const* row) { @@ -6665,14 +6668,13 @@ namespace { ids->clear(); } - else if (auto const* const since_anchor = - sync::state_anchor_event(store, request.room_id, request.access, *delta_since); - since_anchor != nullptr) + else if (auto const held = sync::resolved_state_at(store, request.room_id, *delta_since); + held.has_value()) { - if (auto const held = sync::state_event_ids_after(store, *since_anchor); held.has_value()) - { - remove_state_held(*ids, *held); - } + // ADR-0827: the user was joined at `since`, so the client holds the resolved state it was told + // then. A `since` the log does not cover gets the whole readable state: an update it already + // holds is harmless. + remove_state_held(*ids, *held); } } auto selector = std::optional{}; @@ -7037,6 +7039,9 @@ namespace // holds nothing above it, or the next sync, starting from it, would // deliver that event again. auto const sync_position = visible_stream_position(rt.homeserver.database); + // ADR-0827: a state change recorded after this is filed above `sync_position`, so the state a `state_after` + // client is told as of it never changes afterwards. + store.state_change_log.note_served(sync_position); auto max_observed_sync_stream_id = since_sync_stream_id; auto join_members = canonicaljson::Object{}; auto join_count = std::size_t{0U}; @@ -7081,8 +7086,9 @@ namespace // rows, not by walking every room on the server; an incremental sync leaves out a room that cannot have news // without charging it to max_sync_rooms; and when more rooms remain than the cap the most recently active are // served. - auto const served_rooms = select_sync_rooms(rt, store, user, filter, since_token.has_value() && !full_state, - since_ordering, since_sync_stream_id, user_account_data); + auto const served_rooms = + select_sync_rooms(rt, store, user, filter, since_token.has_value() && !full_state, use_state_after, + since_ordering, since_sync_stream_id, user_account_data); for (auto const* const served_room : served_rooms) { @@ -7200,8 +7206,10 @@ namespace // filter hides lies before `next_batch`, and no later sync would report it. if (state_path) { - state_events = - build_state_events_at_position(store, filter.room.state, room.room_id, sync_position, lazy_ref); + // ADR-0827: the resolved state as of the position, the baseline of the next delta. + state_events = build_state_events_array_for_ids( + store, filter.room.state, + resolved_state_event_ids_at_position(store, room.room_id, sync_position), lazy_ref); } else { diff --git a/src/homeserver/HomeserverRuntime.cpp b/src/homeserver/HomeserverRuntime.cpp index 7bc27f38c..bb0a0bad8 100644 --- a/src/homeserver/HomeserverRuntime.cpp +++ b/src/homeserver/HomeserverRuntime.cpp @@ -920,6 +920,10 @@ auto bootstrap_local_database(config::Config const& config, database::SchemaStat { database.opened = false; } + // ADR-0827: `state_after` deltas are measured from the change log, which covers only what this process saw. + // A `since` at or below the position reached at start-up was answered by an earlier process (or a database + // restored or upgraded from one) and gets a room's whole state once. + database.persistent_store.state_change_log.start(visible_stream_position(database)); } return database; } diff --git a/src/homeserver/StateBookkeeping.cpp b/src/homeserver/StateBookkeeping.cpp index 0589eb89f..18e05495a 100644 --- a/src/homeserver/StateBookkeeping.cpp +++ b/src/homeserver/StateBookkeeping.cpp @@ -823,8 +823,8 @@ auto recompute_current_state(database::PersistentStore& store, std::string_view auto const held = current.find(key); if (held == current.end() || held->second != entry.event_id) { - if (!database::store_state(store, - {std::string{room_id}, entry.event_type, entry.state_key, entry.event_id})) + if (!database::store_state(store, {std::string{room_id}, entry.event_type, entry.state_key, entry.event_id}, + causing_stream_ordering)) { return {CurrentStateRecomputeStatus::write_failed, {}, {}}; } @@ -847,7 +847,7 @@ auto recompute_current_state(database::PersistentStore& store, std::string_view removed_keys.emplace_back(std::move(row.event_type), std::move(row.state_key)); } if ((!removed_keys.empty() || !corrections.empty()) && - !database::remove_current_state_rows(store, room_id, removed_keys, corrections)) + !database::remove_current_state_rows(store, room_id, removed_keys, corrections, causing_stream_ordering)) { return {CurrentStateRecomputeStatus::write_failed, {}, {}}; } @@ -1195,7 +1195,7 @@ auto store_event_with_bookkeeping(database::PersistentStore& store, rooms::RoomV database::apply_forward_extremities_update(store, room_id, event_id, bookkeeping.replaced_extremities); for (auto const& change : current_state_changes) { - database::apply_current_state(store, change); + database::apply_current_state(store, change, prepared_event->event.stream_ordering); } if (resolution.refusal.has_value()) { diff --git a/src/sync/AGENTS.md b/src/sync/AGENTS.md index 546cc3a66..1e5d9faa0 100644 --- a/src/sync/AGENTS.md +++ b/src/sync/AGENTS.md @@ -30,6 +30,7 @@ Spec authority: | `ViewerEventUnsigned.cpp` | `ViewerEventUnsigned`: adds the requesting user's `unsigned.membership` and, for the sending device, `unsigned.transaction_id` to a client event | | `ReadMarkers.cpp` | `ReadMarkers`, `read_markers_for()`, `event_thread_id()`: where a user has read up to, unthreaded and per thread; `event_relates_to()`: whether an event's relation chain reaches an event within 3 hops (ADR-0746) | | `HistoryVisibility.cpp` | `HistoryVisibility`: the one per-request filter deciding which room events a user may see (Room History Visibility rules, state at the event, fail closed) | +| `ResolvedState.cpp` | `resolved_state_at`, `resolved_state_changes`, `resolved_state_event_at`: a room's resolved state as of a sync position, the exact delta between two, and one key's value, rebuilt from the current state and `PersistentStore::state_change_log` (ADR-0827) | | `RoomReadAccess.cpp` | `room_read_access_for()` / `room_state_event_ids()`: the one predicate deciding which room state a user may read (current, as of departure, or none) | | `SlidingSync.hpp` (header-only) | Core sliding-sync connection-state, request and response types shared by the files above | | `DeviceListDelta.cpp` | Device-list `changed` / `left` deltas for `/sync` and the e2ee extension | @@ -359,17 +360,23 @@ room and, when the user is local, for them. The membership acceptor (`send_join` `device_lists.left` for remote users. A user who joins over federation is also `changed` for themselves (spec: a server may add a user to `changed` when they share a new room). -## `use_state_after` on `/sync` (ADR-0818 to ADR-0820) +## `use_state_after` on `/sync` (ADR-0818 to ADR-0820, ADR-0827) `state_after` is as of `sync_position`, not the last delivered event, or a state event the timeline filter hides is lost. -A delta is `joined_state_changes`: it compares the state at `since` with the state at the position. Do not replace it with a -list of the window's state events (a key state resolution moved back has none), and do not read both whole states when the -graph is unforked (`state_changes_along_chain` costs the rows between them, none for a window of messages). Read the room's -single forward extremity with `ForwardExtremityTable::tips_of_room`, never a walk of every room's. `state_anchor_event` seeks -the first row at or below its position through `EventTable::room_in_stream_order_up_to` (binary search) and steps only over -withheld rows (`state_anchor_rows_examined`); never walk the rows above the position. A left room's delta is taken against -`since` only when the user was joined then (`RoomReadAccess::join_ordering` at or below `since`); a join in the window gets the -whole readable state (ADR-0820). A left room goes through +What a client is told is the room's **resolved** state as of a position, rebuilt from the current state and the store's +`state_change_log` (`ResolvedState.hpp`, ADR-0827); a delta (`joined_state_changes`) is `resolved_state_changes` between +`since` and the position, and a whole state (initial, `full_state`, a join in the window) is +`resolved_state_event_ids_at_position`. Never measure a delta from the state recorded for an event at `since`: on a forked +room that is one branch's, not what the client was told (the 1.1.1 defect). Never list the window's state events either (a +key state resolution moved back has none). `sync_json` calls `note_served(sync_position)` before it builds anything, so a +change recorded afterwards is filed above the position and the state told as of it never changes; a new path that serves +`state_after` does the same. A `since` the log does not cover (at or below the process's start, or below the room's +horizon) gets the whole resolved state, once. A window of messages costs no change and no state row; a test proves it with +`state_rows_examined` and the log's `rows_examined`. `select_sync_rooms` counts a logged change above `since` as news for a +`state_after` client. A sender's member as of the position in a joined room is `resolved_state_event_at` too. +A left room's delta is taken against `since` only when the user was joined then (`RoomReadAccess::join_ordering` at or +below `since`), and is the readable state minus the resolved state at `since`; a join in the window gets the whole readable +state (ADR-0820). A left room goes through `build_left_room_state_after`, which reads only as far as `room_read_access_for` allows: never a joined room's delta, which would tell a departed user what came after their leave. With lazy-loading the delta's member events are always kept (`Plan::changed_event_ids`), and the senders' come by key from `member_event_at_position`. A timeline event is not state diff --git a/src/sync/ResolvedState.cpp b/src/sync/ResolvedState.cpp new file mode 100644 index 000000000..c84ec720f --- /dev/null +++ b/src/sync/ResolvedState.cpp @@ -0,0 +1,127 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/sync/ResolvedState.hpp" + +#include "merovingian/database/PersistentStateEvent.hpp" +#include "merovingian/database/StateChangeLog.hpp" + +#include +#include + +namespace merovingian::sync +{ + +namespace +{ + + using StateKey = std::pair; + + // What one key held at `since` and, when it changed again after `position`, at `position`. + struct KeyValues final + { + std::string at_since{}; + std::optional at_position{}; + }; + +} // namespace + +auto resolved_state_at(database::PersistentStore const& store, std::string_view room_id, std::uint64_t position) + -> std::optional> +{ + auto const& log = store.state_change_log; + if (!log.covers(room_id, position)) + { + return std::nullopt; + } + // The value each key changed above `position` held then: the one its first such change replaced. + auto restored = std::map{}; + for (auto const* change : log.changes_after(room_id, position)) + { + restored.try_emplace(StateKey{change->event_type, change->state_key}, change->previous_event_id); + } + auto ids = std::vector{}; + database::for_each_room_state_row(store, room_id, [&](database::PersistentStateEvent const& row) { + auto const found = restored.find(StateKey{row.event_type, row.state_key}); + if (found == restored.end()) + { + ids.push_back(row.event_id); + return; + } + if (!found->second.empty()) + { + ids.push_back(found->second); + } + restored.erase(found); + }); + // Keys removed from the current state since, which held a value at `position`. + for (auto& [key, event_id] : restored) + { + if (!event_id.empty()) + { + ids.push_back(std::move(event_id)); + } + } + return ids; +} + +auto resolved_state_event_at(database::PersistentStore const& store, std::string_view room_id, + std::string_view event_type, std::string_view state_key, std::uint64_t position) + -> std::optional +{ + auto const& log = store.state_change_log; + if (!log.covers(room_id, position)) + { + return std::nullopt; + } + for (auto const* change : log.changes_after(room_id, position)) + { + if (change->event_type == event_type && change->state_key == state_key) + { + return change->previous_event_id; + } + } + return database::find_current_state_event_id(store, room_id, event_type, state_key).value_or(std::string{}); +} + +auto resolved_state_changes(database::PersistentStore const& store, std::string_view room_id, std::uint64_t since, + std::uint64_t position) -> std::optional> +{ + auto const& log = store.state_change_log; + if (!log.covers(room_id, since)) + { + return std::nullopt; + } + auto ids = std::vector{}; + if (position <= since) + { + return ids; + } + auto keys = std::map{}; + for (auto const* change : log.changes_after(room_id, since)) + { + auto const [entry, first] = keys.try_emplace(StateKey{change->event_type, change->state_key}); + if (first) + { + entry->second.at_since = change->previous_event_id; + } + if (change->position > position && !entry->second.at_position.has_value()) + { + entry->second.at_position = change->previous_event_id; + } + } + for (auto const& [key, values] : keys) + { + auto const at_position = + values.at_position.has_value() + ? *values.at_position + : database::find_current_state_event_id(store, room_id, key.first, key.second).value_or(std::string{}); + // A key with no value at `position` cannot be sent: `state_after` has no way to remove one. + if (!at_position.empty() && at_position != values.at_since) + { + ids.push_back(at_position); + } + } + return ids; +} + +} // namespace merovingian::sync diff --git a/src/sync/StateGroupLookup.cpp b/src/sync/StateGroupLookup.cpp index 1d08a9935..496dea725 100644 --- a/src/sync/StateGroupLookup.cpp +++ b/src/sync/StateGroupLookup.cpp @@ -6,9 +6,7 @@ #include "merovingian/sync/GroupLookup.hpp" #include "merovingian/sync/GroupLookupResult.hpp" -#include #include -#include namespace merovingian::sync { @@ -44,33 +42,4 @@ auto lookup_state_in_group(database::PersistentStore const& store, std::string_v } } -auto state_changes_along_chain(database::PersistentStore const& store, std::string_view ancestor_id, - std::string_view group_id) -> std::optional> -{ - auto changes = std::vector{}; - auto seen = std::set>{}; - auto current = group_id; - for (auto hops = std::size_t{0U}; hops <= events::max_state_group_delta_depth; ++hops) - { - if (current == ancestor_id) - { - return changes; - } - auto const group = store.state_groups.find(current); - if (group == store.state_groups.end() || !group->parent_state_group_id.has_value()) - { - return std::nullopt; - } - for (auto const& entry : store.state_group_state.entries_of(current)) - { - if (seen.emplace(entry.event_type, entry.state_key).second) - { - changes.push_back(entry.event_id); - } - } - current = *group->parent_state_group_id; - } - return std::nullopt; -} - } // namespace merovingian::sync diff --git a/src/sync/meson.build b/src/sync/meson.build index b59ffeac4..b64589afc 100644 --- a/src/sync/meson.build +++ b/src/sync/meson.build @@ -8,6 +8,7 @@ sync_sources = files( 'ReadMarkers.cpp', 'ReceiptContentBuilder.cpp', 'ReceiptVisibility.cpp', + 'ResolvedState.cpp', 'RoomAccess.cpp', 'RoomReadAccess.cpp', 'StateGroupLookup.cpp', diff --git a/tests/conformance/test_sync_state_after_conformance.cpp b/tests/conformance/test_sync_state_after_conformance.cpp index 41e5d9af9..c674f5419 100644 --- a/tests/conformance/test_sync_state_after_conformance.cpp +++ b/tests/conformance/test_sync_state_after_conformance.cpp @@ -14,6 +14,8 @@ // (client-server-api.md, GET /sync, "Joined Room", "Left Room"; ADR-0818 to ADR-0820). #include "../support/JsonTestSupport.hpp" #include "../support/SyncStateAfterSupport.hpp" +#include "merovingian/database/PersistentStateEvent.hpp" +#include "merovingian/database/PersistentStore.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" @@ -257,14 +259,8 @@ SCENARIO("state_after reports a key that state resolution moved back to an older auto& store = rt.homeserver.database.persistent_store; std::ignore = store.forward_extremities.insert({room, old_topic}, user_id("alice")); - for (auto& row : store.state) - { - if (row.room_id == room && row.event_type == "m.room.topic") - { - row.event_id = old_topic; - } - } - merovingian::database::rebuild_state_index(store); + // What a resolution that picked the older topic writes, through the writer it uses. + REQUIRE(merovingian::database::store_state(store, {room, "m.room.topic", "", old_topic})); WHEN("alice syncs with use_state_after=true") { diff --git a/tests/integration/test_sync_handler_flow.cpp b/tests/integration/test_sync_handler_flow.cpp index 2c6378cd7..43b351a77 100644 --- a/tests/integration/test_sync_handler_flow.cpp +++ b/tests/integration/test_sync_handler_flow.cpp @@ -26,12 +26,13 @@ #include "../support/MasterKey.hpp" #include "../support/RegistrationToken.hpp" #include "../support/RoomHistoryFixture.hpp" +#include "../support/StatePduSupport.hpp" #include "merovingian/canonicaljson/CanonicalJsonError.hpp" #include "merovingian/canonicaljson/ObjectMember.hpp" #include "merovingian/canonicaljson/ParseError.hpp" -#include "merovingian/canonicaljson/Value.hpp" #include "merovingian/canonicaljson/Parser.hpp" #include "merovingian/canonicaljson/Serializer.hpp" +#include "merovingian/canonicaljson/Value.hpp" #include "merovingian/config/ClientRateLimitsConfig.hpp" #include "merovingian/config/Config.hpp" #include "merovingian/config/ListenersConfig.hpp" @@ -43,17 +44,17 @@ #include "merovingian/database/PersistentStore.hpp" #include "merovingian/database/PersistentToDeviceMessage.hpp" #include "merovingian/events/EventId.hpp" +#include "merovingian/federation/InboundIngestion.hpp" #include "merovingian/federation/InboundPduEnvelope.hpp" #include "merovingian/federation/PduIngestionStatus.hpp" -#include "merovingian/federation/InboundIngestion.hpp" #include "merovingian/homeserver/ClientDevice.hpp" #include "merovingian/homeserver/ClientServerClock.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" #include "merovingian/homeserver/DispatchResult.hpp" -#include "merovingian/homeserver/WorkerPool.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" #include "merovingian/homeserver/RoomService.hpp" +#include "merovingian/homeserver/WorkerPool.hpp" #include "merovingian/sync/StreamToken.hpp" #include @@ -139,8 +140,8 @@ namespace return body.substr(value_start, value_end - value_start); } -[[nodiscard]] auto json_member(merovingian::canonicaljson::Object const& object, - std::string_view key) -> merovingian::canonicaljson::Value const* +[[nodiscard]] auto json_member(merovingian::canonicaljson::Object const& object, std::string_view key) + -> merovingian::canonicaljson::Value const* { for (auto const& member : object) { @@ -184,8 +185,8 @@ namespace // Returns the most-recently-added device for `user`. Registration now creates // a device first; callers want the login device which is always added last. -[[nodiscard]] auto first_device_id_for(merovingian::homeserver::ClientServerRuntime const& rt, - std::string_view user) -> std::string +[[nodiscard]] auto first_device_id_for(merovingian::homeserver::ClientServerRuntime const& rt, std::string_view user) + -> std::string { // Track the last matching device with a portable loop: std::ranges::find_last_if // is C++23 and is not yet provided by every Tier 1 platform's standard library. @@ -1110,67 +1111,6 @@ SCENARIO("Federation-joined room state events are visible to incremental sync", } } -namespace -{ - -[[nodiscard]] auto make_topic_fork_pdu(std::string const& room_id, std::string const& event_id, - std::string const& sender, std::string const& topic, - std::vector const& prev_event_ids, - std::vector const& auth_event_ids, - std::int64_t ts) -> merovingian::federation::InboundPduEnvelope -{ - using namespace merovingian; - - auto content = canonicaljson::Object{}; - content.push_back(canonicaljson::make_member("topic", canonicaljson::Value{topic})); - - auto obj = canonicaljson::Object{}; - obj.push_back(canonicaljson::make_member("type", canonicaljson::Value{std::string{"m.room.topic"}})); - obj.push_back(canonicaljson::make_member("state_key", canonicaljson::Value{std::string{}})); - obj.push_back(canonicaljson::make_member("room_id", canonicaljson::Value{room_id})); - obj.push_back(canonicaljson::make_member("sender", canonicaljson::Value{sender})); - obj.push_back(canonicaljson::make_member("content", canonicaljson::Value{std::move(content)})); - obj.push_back(canonicaljson::make_member("origin_server_ts", canonicaljson::Value{ts})); - obj.push_back(canonicaljson::make_member("depth", canonicaljson::Value{std::int64_t{10}})); - auto prev_arr = canonicaljson::Array{}; - for (auto const& id : prev_event_ids) - { - prev_arr.push_back(canonicaljson::Value{id}); - } - obj.push_back(canonicaljson::make_member("prev_events", canonicaljson::Value{std::move(prev_arr)})); - auto auth_arr = canonicaljson::Array{}; - for (auto const& id : auth_event_ids) - { - auth_arr.push_back(canonicaljson::Value{id}); - } - obj.push_back(canonicaljson::make_member("auth_events", canonicaljson::Value{std::move(auth_arr)})); - - auto const hash = events::make_content_hash(canonicaljson::Value{obj}); - REQUIRE(hash.error.empty()); - auto hashes = canonicaljson::Object{}; - hashes.push_back(canonicaljson::make_member("sha256", canonicaljson::Value{hash.sha256})); - obj.push_back(canonicaljson::make_member("hashes", canonicaljson::Value{std::move(hashes)})); - - auto const serialized = canonicaljson::serialize_canonical(canonicaljson::Value{std::move(obj)}); - REQUIRE(serialized.error == canonicaljson::CanonicalJsonError::none); - - auto env = federation::InboundPduEnvelope{}; - env.event_id = event_id; - env.room_id = room_id; - env.room_version = "12"; - env.sender = sender; - env.event_type = "m.room.topic"; - env.state_key = std::string{}; - env.origin_server_ts = ts; - env.depth = 10U; - env.prev_event_ids = prev_event_ids; - env.auth_event_ids = auth_event_ids; - env.json = serialized.output; - return env; -} - -} // namespace - // ADR-0064 phase B1, test (e) from the completion brief: a resolution that // REVERTS a key to an OLDER event must be delivered to sync as an ordinary // state change, through the same state_transitions/current_state path every @@ -1248,14 +1188,14 @@ SCENARIO("Sync sees a state-resolution-driven current_state change, including a // A is created and superseded by B FIRST, before C exists, and // still wins the later fork against C — an older-in-the-DAG event // becoming current for a second time. - auto const event_a = - make_topic_fork_pdu(room_id, "$topic_a:example.org", alice_id, "topic-A", {tip0}, auth_ids, 9000); + auto const event_a = merovingian::tests::state_pdu_support::make_topic_pdu( + room_id, "$topic_a:example.org", alice_id, "topic-A", {tip0}, auth_ids, 9000); REQUIRE(merovingian::homeserver::ingest_pdu_event(hs, event_a).status == merovingian::federation::PduIngestionStatus::accepted); // Event B: a plain linear successor, supersedes A. - auto const event_b = make_topic_fork_pdu(room_id, "$topic_b:example.org", alice_id, "topic-B", - {"$topic_a:example.org"}, auth_ids, 2000); + auto const event_b = merovingian::tests::state_pdu_support::make_topic_pdu( + room_id, "$topic_b:example.org", alice_id, "topic-B", {"$topic_a:example.org"}, auth_ids, 2000); REQUIRE(merovingian::homeserver::ingest_pdu_event(hs, event_b).status == merovingian::federation::PduIngestionStatus::accepted); REQUIRE(std::ranges::any_of(hs.database.persistent_store.state, [&](auto const& s) { @@ -1335,8 +1275,8 @@ SCENARIO("Sync sees a state-resolution-driven current_state change, including a witness_w.auth_event_ids = auth_ids; witness_w.json = witness_serialized.output; - auto const fork_c = make_topic_fork_pdu(room_id, "$topic_c:example.org", alice_id, "topic-C", - {"$topic_b:example.org"}, auth_ids, 3500); + auto const fork_c = merovingian::tests::state_pdu_support::make_topic_pdu( + room_id, "$topic_c:example.org", alice_id, "topic-C", {"$topic_b:example.org"}, auth_ids, 3500); REQUIRE(merovingian::homeserver::ingest_pdu_event(hs, witness_w).status == merovingian::federation::PduIngestionStatus::accepted); diff --git a/tests/integration/test_sync_state_after_flow.cpp b/tests/integration/test_sync_state_after_flow.cpp index b229d100c..d3b180026 100644 --- a/tests/integration/test_sync_state_after_flow.cpp +++ b/tests/integration/test_sync_state_after_flow.cpp @@ -5,9 +5,18 @@ // client-server stack (ADR-0818 to ADR-0820). What the spec states is in // tests/conformance/test_sync_state_after_conformance.cpp. #include "../support/JsonTestSupport.hpp" +#include "../support/StatePduSupport.hpp" #include "../support/SyncStateAfterSupport.hpp" +#include "merovingian/canonicaljson/ObjectMember.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/database/PersistentStateEvent.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/federation/InboundPduEnvelope.hpp" +#include "merovingian/federation/PduIngestionStatus.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRouter.hpp" #include @@ -24,6 +33,48 @@ using namespace merovingian::tests::state_after_support; constexpr auto k_full_state_after = std::string_view{"&full_state=true&use_state_after=true"}; +constexpr auto k_topic_a = std::string_view{"$topic_a:example.org"}; +constexpr auto k_topic_b = std::string_view{"$topic_b:example.org"}; + +// The event ID of the room's current `m.room.topic`, or "" when it has none. +[[nodiscard]] auto current_topic(ClientServerRuntime const& rt, std::string const& room) -> std::string +{ + return merovingian::database::find_current_state_event_id(rt.homeserver.database.persistent_store, room, + "m.room.topic", "") + .value_or(std::string{}); +} + +// Forks alice's room through the ingestion path, so that the room's resolved state and the state recorded for its +// newest event disagree: topic A on the room's tip, then a name change after A and a topic B after A, each on its own +// branch. State resolution v2 orders the two topics, both at the same mainline position, by `origin_server_ts`, and A +// (9000) wins over B (2000): the room's topic is A, while B, the newest event, records topic B. +auto fork_between_two_topics(ClientServerRuntime& rt, std::string const& room) -> void +{ + namespace pdus = merovingian::tests::state_pdu_support; + auto& hs = rt.homeserver; + auto const& store = hs.database.persistent_store; + auto const alice_id = user_id("alice"); + auto const auth_ids = std::vector{ + merovingian::database::find_current_state_event_id(store, room, "m.room.power_levels", "").value_or(""), + merovingian::database::find_current_state_event_id(store, room, "m.room.member", alice_id).value_or("")}; + auto const tips = store.forward_extremities.tips_of_room(room); + REQUIRE(tips.size() == 1U); + auto const accepted = [&](merovingian::federation::InboundPduEnvelope const& pdu) { + REQUIRE(merovingian::homeserver::ingest_pdu_event(hs, pdu).status == + merovingian::federation::PduIngestionStatus::accepted); + }; + accepted(pdus::make_topic_pdu(room, std::string{k_topic_a}, alice_id, "topic-A", {tips.front()}, auth_ids, 9000)); + auto name = Object{}; + name.push_back( + merovingian::canonicaljson::make_member("name", merovingian::canonicaljson::Value{std::string{"witness"}})); + accepted(pdus::make_state_pdu(room, "$witness:example.org", alice_id, "m.room.name", std::move(name), + {std::string{k_topic_a}}, auth_ids, 2500)); + accepted(pdus::make_topic_pdu(room, std::string{k_topic_b}, alice_id, "topic-B", {std::string{k_topic_a}}, auth_ids, + 2000)); + REQUIRE(store.forward_extremities.tips_of_room(room).size() == 2U); + REQUIRE(current_topic(rt, room) == k_topic_a); +} + } // namespace // ADR-0818: a sync that finds nothing new in a joined room does not report it. @@ -447,3 +498,171 @@ SCENARIO("A lazy-loaded member whose response was lost is sent again in state_af } } } + +// The review of 1.1.1's `state_after` (ADR-0827): the client is told the room's resolved state. With the room forked at +// `since`, the state recorded for the newest event at or below `since` is one branch's, so a delta measured from it +// lost a key that resolution later moved back to that branch's value: neither the chain walk nor the fallback saw a +// difference, and a `state_after` client, which takes no state from the timeline, kept the old value. +SCENARIO("A state_after delta is exact when the room was forked at since", + "[integration][sync][state-after][flow][state-change-log]") +{ + GIVEN("a forked room whose resolved topic is not the newest event's recorded topic, synced by alice") + { + auto started = merovingian::homeserver::start_client_server(state_after_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + auto const alice = register_user(rt, "alice"); + auto const room = create_room(rt, alice, "public_chat"); + fork_between_two_topics(rt, room); + auto const initial = sync(rt, alice, k_no_filter, {}, k_state_after); + REQUIRE(topics_in(events_of(required_room(initial, "join", room), "state_after")) == + std::vector{"topic-A"}); + + WHEN("a message arrives, resolution moves the topic back to B, and alice syncs with use_state_after=true") + { + say(rt, alice, room, "after the fork"); + // recompute_current_state writes a resolution's outcome through this writer. + REQUIRE(merovingian::database::store_state( + rt.homeserver.database.persistent_store, + merovingian::database::PersistentStateEvent{room, "m.room.topic", "", std::string{k_topic_b}})); + REQUIRE(current_topic(rt, room) == k_topic_b); + auto const synced = sync(rt, alice, k_no_filter, initial.next_batch, k_state_after); + + THEN("state_after holds topic B, which the room now has and alice was never told") + { + auto const after = events_of(required_room(synced, "join", room), "state_after"); + REQUIRE(topics_in(after) == std::vector{"topic-B"}); + } + } + WHEN("only a message arrives and alice syncs with use_state_after=true") + { + say(rt, alice, room, "after the fork"); + REQUIRE(current_topic(rt, room) == k_topic_a); + auto const synced = sync(rt, alice, k_no_filter, initial.next_batch, k_state_after); + + THEN("state_after holds no topic: alice already has the room's topic") + { + auto const after = events_of(required_room(synced, "join", room), "state_after"); + REQUIRE(topics_in(after).empty()); + } + } + } +} + +// ADR-0827: a delta reads the room's changes since `since` from the state change log, so a message in a forked room +// costs no read of the room's state, where the fallback this replaced read the whole of it twice. +SCENARIO("A state_after delta of a forked room with only a message reads none of the room's state", + "[integration][sync][state-after][flow][state-change-log][state-index]") +{ + GIVEN("a forked room with sixty more state events, synced by alice") + { + auto started = merovingian::homeserver::start_client_server(state_after_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + auto const alice = register_user(rt, "alice"); + auto const room = create_room(rt, alice, "public_chat"); + for (auto index = 0; index < 60; ++index) + { + auto const sent = + call(rt, "PUT", "/_matrix/client/v3/rooms/" + room + "/state/org.example.key/k" + std::to_string(index), + alice, R"({"value":"v"})"); + REQUIRE(sent.status == 200U); + } + fork_between_two_topics(rt, room); + auto const initial = sync(rt, alice, k_no_filter, {}, k_state_after); + auto const& store = rt.homeserver.database.persistent_store; + + WHEN("a message arrives and alice syncs with use_state_after=true") + { + say(rt, alice, room, "hello"); + auto const before = store.state_rows_examined.value(); + auto const synced = sync(rt, alice, k_no_filter, initial.next_batch, k_state_after); + auto const examined = store.state_rows_examined.value() - before; + + THEN("state_after is empty, and far fewer than sixty state rows were read") + { + REQUIRE(events_of(required_room(synced, "join", room), "state_after").empty()); + REQUIRE(examined < 30U); + } + } + } +} + +// ADR-0827: a left room's `state_after` is measured from the state the client was told at `since`, the resolved state, +// not the state recorded for the newest event at `since`, which on a forked room is one branch's. +SCENARIO("A left room's state_after is measured from what the client was told when the room was forked", + "[integration][sync][state-after][flow][state-change-log]") +{ + GIVEN("a forked room bob was told the resolved topic of, and then left") + { + auto started = merovingian::homeserver::start_client_server(state_after_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + auto const alice = register_user(rt, "alice"); + auto const bob = register_user(rt, "bob"); + auto const room = create_room(rt, alice, "public_chat"); + room_post(rt, bob, room, "join"); + fork_between_two_topics(rt, room); + auto const initial = sync(rt, bob, k_no_filter, {}, k_state_after); + REQUIRE(topics_in(events_of(required_room(initial, "join", room), "state_after")) == + std::vector{"topic-A"}); + room_post(rt, bob, room, "leave"); + REQUIRE(current_topic(rt, room) == k_topic_a); + + WHEN("bob syncs with use_state_after=true") + { + auto const synced = sync(rt, bob, k_no_filter, initial.next_batch, k_state_after); + auto const& left = required_room(synced, "leave", room); + + THEN("state_after holds no topic, which bob already has, and his leave is reported") + { + auto const after = events_of(left, "state_after"); + REQUIRE(topics_in(after).empty()); + auto const timeline = events_of(left, "timeline"); + REQUIRE(member_keys(timeline).contains(user_id("bob"))); + } + } + } +} + +// ADR-0827: a `since` answered before the change log started (an earlier process, or a database restored or upgraded +// from one) is not trusted for a delta: the room's whole state is sent once, and the next sync is a delta again. +SCENARIO("A state_after since from before the change log started gets the room's whole state once", + "[integration][sync][state-after][flow][state-change-log]") +{ + GIVEN("a room alice synced before the server's change log started again, as at a restart") + { + auto started = merovingian::homeserver::start_client_server(state_after_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + auto const alice = register_user(rt, "alice"); + auto const room = create_room(rt, alice, "public_chat"); + auto const initial = sync(rt, alice, k_no_filter, {}, k_state_after); + auto& store = rt.homeserver.database.persistent_store; + store.state_change_log.start(merovingian::homeserver::visible_stream_position(rt.homeserver.database)); + + WHEN("the topic changes and alice syncs from her old token") + { + set_topic(rt, alice, room, "after the restart"); + auto const synced = sync(rt, alice, k_no_filter, initial.next_batch, k_state_after); + + THEN("state_after is the room's whole state") + { + auto const after = events_of(required_room(synced, "join", room), "state_after"); + REQUIRE(event_types(after).contains("m.room.create")); + REQUIRE(topics_in(after) == std::vector{"after the restart"}); + } + + AND_WHEN("only a message arrives and she syncs from the new token") + { + say(rt, alice, room, "hello"); + auto const next = sync(rt, alice, k_no_filter, synced.next_batch, k_state_after); + + THEN("state_after is a delta again, and empty") + { + REQUIRE(events_of(required_room(next, "join", room), "state_after").empty()); + } + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index 8143d3982..797a78ba6 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -366,6 +366,8 @@ shell = find_program('sh') 'unit/test_join_batch_persistence.cpp', 'unit/test_room_position_index.cpp', 'unit/test_state_index.cpp', + 'unit/test_state_change_log.cpp', + 'unit/test_resolved_state.cpp', 'unit/test_state_groups.cpp', 'unit/test_state_group_tables.cpp', 'unit/test_reload_room_state_groups.cpp', diff --git a/tests/support/AGENTS.md b/tests/support/AGENTS.md index 9ff3cd6fb..43684a265 100644 --- a/tests/support/AGENTS.md +++ b/tests/support/AGENTS.md @@ -20,6 +20,7 @@ Shared test utilities used across unit, conformance, and integration tests. | `IngestedStateFixture.hpp` | `record_ingested_state()` / `record_ingested_state_for_room()`: for a fixture that writes events straight into a `PersistentStore` and then asks for the state AT an event (federation `/state`, `/state_ids`, client `/context`), records the state group ingestion would have recorded for each event (state before = resolution of the prev_events' states, state after = that plus the event, unchanged for a rejected one). Those reads answer from the recorded state, never from a walk of the event graph (ADR-0363). Call it parents first | | `CrossSigningFixture.hpp` | `make_cross_signing_set()`: a master, self-signing and user-signing key with real Ed25519 keys and real signatures (the self-signing and user-signing keys signed by the master key), plus `sign_cross_signing_key_json()`, `cross_signing_upload_body()` and `fresh_cross_signing_upload_body()`. `POST /keys/device_signing/upload` verifies those signatures (ADR-0421), so a test that uploads cross-signing keys uses this, never invented key or signature text | | `ForgedUnsigned.hpp` | `with_forged_unsigned()` / `forged_unsigned_json`: a signed PDU with the `unsigned` a hostile relaying server would write (`m.relations`, `redacted_because`, `prev_content`, `age`, `transaction_id`, `membership`). The signatures and event ID still hold, so it ingests like the genuine PDU (ADR-0402) | +| `StatePduSupport.hpp` | `state_pdu_support`: `make_state_pdu` and `make_topic_pdu`, a room-version-12 state PDU with a correct content hash, given prev and auth events and an `origin_server_ts`, for scenarios that fork a room's graph through `ingest_pdu_event` | | `SyncStateAfterSupport.hpp` | `state_after_support`: the config, request, `/sync` and response-reading helpers the `use_state_after` conformance and integration scenarios share (`state_after_config`, `call`, `register_user`, `create_room`, `sync`, `required_room`, `events_of`, `event_types`, `member_keys`, ...). Drives the runtime the caller started | | `RegistrationToken.hpp` | Generates registration tokens for test users without going through the full UIAA flow | | `FakeClamdServer.hpp` | `FakeClamdServer`: a clamd stand-in on a temporary AF_UNIX socket. Reads INSTREAM exchanges, records the streamed bytes and answers with a fixed reply (or stays silent for the timeout case). Another I/O exception, shared by the unit and integration suites (G15, ADR-0565); assert on its recorded data from the test thread only | diff --git a/tests/support/StatePduSupport.hpp b/tests/support/StatePduSupport.hpp new file mode 100644 index 000000000..49ecf94a2 --- /dev/null +++ b/tests/support/StatePduSupport.hpp @@ -0,0 +1,92 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +// Builds an inbound state PDU of a version 12 room for `homeserver::ingest_pdu_event`, with its content hash and no +// signatures, so a scenario can lay out an event graph (a fork, a resolution that moves a key back) through the real +// ingestion path. The caller chooses the event ID, the `prev_events`, the `auth_events` and the timestamp, which is the +// tie-break state resolution v2 applies between two non-power events at the same mainline position. + +#include "merovingian/canonicaljson/CanonicalJsonError.hpp" +#include "merovingian/canonicaljson/ObjectMember.hpp" +#include "merovingian/canonicaljson/Serializer.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/events/EventId.hpp" +#include "merovingian/federation/InboundPduEnvelope.hpp" + +#include + +#include +#include +#include +#include + +namespace merovingian::tests::state_pdu_support +{ + +// A state event of `type` with `state_key` "" and `content`, at depth 10. +[[nodiscard]] inline auto make_state_pdu(std::string const& room_id, std::string const& event_id, + std::string const& sender, std::string const& type, + canonicaljson::Object content, std::vector const& prev_event_ids, + std::vector const& auth_event_ids, std::int64_t ts) + -> federation::InboundPduEnvelope +{ + auto obj = canonicaljson::Object{}; + obj.push_back(canonicaljson::make_member("type", canonicaljson::Value{type})); + obj.push_back(canonicaljson::make_member("state_key", canonicaljson::Value{std::string{}})); + obj.push_back(canonicaljson::make_member("room_id", canonicaljson::Value{room_id})); + obj.push_back(canonicaljson::make_member("sender", canonicaljson::Value{sender})); + obj.push_back(canonicaljson::make_member("content", canonicaljson::Value{std::move(content)})); + obj.push_back(canonicaljson::make_member("origin_server_ts", canonicaljson::Value{ts})); + obj.push_back(canonicaljson::make_member("depth", canonicaljson::Value{std::int64_t{10}})); + auto prev_arr = canonicaljson::Array{}; + for (auto const& id : prev_event_ids) + { + prev_arr.push_back(canonicaljson::Value{id}); + } + obj.push_back(canonicaljson::make_member("prev_events", canonicaljson::Value{std::move(prev_arr)})); + auto auth_arr = canonicaljson::Array{}; + for (auto const& id : auth_event_ids) + { + auth_arr.push_back(canonicaljson::Value{id}); + } + obj.push_back(canonicaljson::make_member("auth_events", canonicaljson::Value{std::move(auth_arr)})); + + auto const hash = events::make_content_hash(canonicaljson::Value{obj}); + REQUIRE(hash.error.empty()); + auto hashes = canonicaljson::Object{}; + hashes.push_back(canonicaljson::make_member("sha256", canonicaljson::Value{hash.sha256})); + obj.push_back(canonicaljson::make_member("hashes", canonicaljson::Value{std::move(hashes)})); + + auto const serialized = canonicaljson::serialize_canonical(canonicaljson::Value{std::move(obj)}); + REQUIRE(serialized.error == canonicaljson::CanonicalJsonError::none); + + auto env = federation::InboundPduEnvelope{}; + env.event_id = event_id; + env.room_id = room_id; + env.room_version = "12"; + env.sender = sender; + env.event_type = type; + env.state_key = std::string{}; + env.origin_server_ts = ts; + env.depth = 10U; + env.prev_event_ids = prev_event_ids; + env.auth_event_ids = auth_event_ids; + env.json = serialized.output; + return env; +} + +// An `m.room.topic` event whose topic is `topic`. +[[nodiscard]] inline auto make_topic_pdu(std::string const& room_id, std::string const& event_id, + std::string const& sender, std::string const& topic, + std::vector const& prev_event_ids, + std::vector const& auth_event_ids, std::int64_t ts) + -> federation::InboundPduEnvelope +{ + auto content = canonicaljson::Object{}; + content.push_back(canonicaljson::make_member("topic", canonicaljson::Value{topic})); + return make_state_pdu(room_id, event_id, sender, "m.room.topic", std::move(content), prev_event_ids, auth_event_ids, + ts); +} + +} // namespace merovingian::tests::state_pdu_support diff --git a/tests/unit/test_resolved_state.cpp b/tests/unit/test_resolved_state.cpp new file mode 100644 index 000000000..a1ed53c17 --- /dev/null +++ b/tests/unit/test_resolved_state.cpp @@ -0,0 +1,240 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// A room's resolved state as of a sync position, rebuilt from its current state and the state change log (ADR-0827): +// the state a `state_after` client is told, and the exact delta between two such positions, whatever made the state +// change and in whatever order. + +#include "merovingian/database/PersistentEvent.hpp" +#include "merovingian/database/PersistentStateEvent.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/sync/ResolvedState.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +namespace db = merovingian::database; +namespace sync = merovingian::sync; + +constexpr auto room_id = std::string_view{"!room:example.org"}; + +// Stores a state event of `type` and `state_key` at `ordering`, so that store_state accepts a row naming it. +auto store_state_event(db::PersistentStore& store, std::string_view type, std::string_view state_key, + std::string const& event_id, std::uint64_t ordering) -> void +{ + auto event = db::PersistentEvent{}; + event.event_id = event_id; + event.room_id = std::string{room_id}; + event.sender_user_id = "@alice:example.org"; + event.depth = ordering; + event.stream_ordering = ordering; + event.json = std::string{R"({"type":")"} + std::string{type} + R"(","state_key":")" + std::string{state_key} + + R"(","room_id":")" + std::string{room_id} + R"(","sender":"@alice:example.org","content":{}})"; + REQUIRE(db::store_event(store, std::move(event))); +} + +// Makes `event_id` the room's current value of (`type`, `state_key`), as made by the event at `causing`. +auto set_current(db::PersistentStore& store, std::string_view type, std::string_view state_key, + std::string const& event_id, std::uint64_t causing) -> void +{ + REQUIRE( + db::store_state(store, {std::string{room_id}, std::string{type}, std::string{state_key}, event_id}, causing)); +} + +[[nodiscard]] auto sorted(std::vector ids) -> std::vector +{ + std::ranges::sort(ids); + return ids; +} + +} // namespace + +SCENARIO("Nothing is rebuilt while the state change log is inactive", "[sync][state-change-log]") +{ + GIVEN("a store whose log was never started, as in the federation worker") + { + auto store = db::PersistentStore{}; + store_state_event(store, "m.room.topic", "", "$a", 1U); + set_current(store, "m.room.topic", "", "$a", 1U); + + THEN("no position is covered") + { + REQUIRE_FALSE(sync::resolved_state_at(store, room_id, 5U).has_value()); + REQUIRE_FALSE(sync::resolved_state_changes(store, room_id, 5U, 6U).has_value()); + REQUIRE_FALSE(sync::resolved_state_event_at(store, room_id, "m.room.topic", "", 5U).has_value()); + REQUIRE(store.state_change_log.size() == 0U); + } + } +} + +SCENARIO("A key resolution moves back after a sync is sent to the client that was told the other value", + "[sync][state-change-log]") +{ + GIVEN("a room whose topic is A when a sync answers at 20") + { + auto store = db::PersistentStore{}; + store_state_event(store, "m.room.topic", "", "$a", 5U); + store_state_event(store, "m.room.topic", "", "$b", 6U); + set_current(store, "m.room.topic", "", "$a", 5U); + store.state_change_log.start(10U); + store.state_change_log.note_served(20U); + + WHEN("resolution moves the topic to B, a sync answers at 30, and resolution moves it back to A") + { + set_current(store, "m.room.topic", "", "$b", 0U); + store.state_change_log.note_served(30U); + set_current(store, "m.room.topic", "", "$a", 0U); + + THEN("each sync's state is the value it was told, and each delta is exact") + { + REQUIRE(sync::resolved_state_at(store, room_id, 20U) == std::vector{"$a"}); + REQUIRE(sync::resolved_state_at(store, room_id, 30U) == std::vector{"$b"}); + REQUIRE(sync::resolved_state_at(store, room_id, 31U) == std::vector{"$a"}); + REQUIRE(sync::resolved_state_changes(store, room_id, 20U, 30U) == std::vector{"$b"}); + REQUIRE(sync::resolved_state_changes(store, room_id, 30U, 31U) == std::vector{"$a"}); + } + + THEN("a client that slept through both is sent nothing: it already has A") + { + REQUIRE(sync::resolved_state_changes(store, room_id, 20U, 31U) == std::vector{}); + } + + THEN("the topic as of each position is looked up by key") + { + REQUIRE(sync::resolved_state_event_at(store, room_id, "m.room.topic", "", 30U) == "$b"); + REQUIRE(sync::resolved_state_event_at(store, room_id, "m.room.topic", "", 31U) == "$a"); + REQUIRE(sync::resolved_state_event_at(store, room_id, "m.room.name", "", 31U) == ""); + } + } + } +} + +SCENARIO("A change caused by an event ordered at or below a served position is seen after it", + "[sync][state-change-log]") +{ + GIVEN("a room whose topic is A when a sync answers at 30") + { + auto store = db::PersistentStore{}; + store_state_event(store, "m.room.topic", "", "$a", 5U); + store_state_event(store, "m.room.topic", "", "$backfilled", 25U); + set_current(store, "m.room.topic", "", "$a", 5U); + store.state_change_log.start(10U); + store.state_change_log.note_served(30U); + + WHEN("a backfilled event at 25 becomes the topic") + { + set_current(store, "m.room.topic", "", "$backfilled", 25U); + + THEN("the state as of 30 still says A, and the next delta carries the change") + { + REQUIRE(sync::resolved_state_at(store, room_id, 30U) == std::vector{"$a"}); + REQUIRE(sync::resolved_state_changes(store, room_id, 30U, 31U) == + std::vector{"$backfilled"}); + REQUIRE(store.state_change_log.has_change_after(room_id, 30U)); + } + } + } +} + +SCENARIO("A key removed from the current state is put back as of an earlier position", "[sync][state-change-log]") +{ + GIVEN("a room with a topic and a name when a sync answers at 20") + { + auto store = db::PersistentStore{}; + store_state_event(store, "m.room.topic", "", "$topic", 5U); + store_state_event(store, "m.room.name", "", "$name", 6U); + set_current(store, "m.room.topic", "", "$topic", 5U); + set_current(store, "m.room.name", "", "$name", 6U); + store.state_change_log.start(10U); + store.state_change_log.note_served(20U); + + WHEN("resolution drops the name") + { + REQUIRE(db::remove_current_state_rows(store, room_id, + { + {"m.room.name", ""} + }, + {}, 0U)); + + THEN("the state as of 20 still holds the name, and the delta sends nothing it cannot express") + { + REQUIRE(sorted(*sync::resolved_state_at(store, room_id, 20U)) == + std::vector{"$name", "$topic"}); + REQUIRE(sync::resolved_state_at(store, room_id, 21U) == std::vector{"$topic"}); + REQUIRE(sync::resolved_state_changes(store, room_id, 20U, 21U) == std::vector{}); + } + } + } +} + +SCENARIO("A position the log does not cover is not rebuilt", "[sync][state-change-log]") +{ + GIVEN("a store whose log started at 10") + { + auto store = db::PersistentStore{}; + store_state_event(store, "m.room.topic", "", "$a", 5U); + set_current(store, "m.room.topic", "", "$a", 5U); + store.state_change_log.start(10U); + + THEN("a since at or below the start, which an earlier process answered, gives no delta") + { + REQUIRE_FALSE(sync::resolved_state_changes(store, room_id, 10U, 12U).has_value()); + REQUIRE_FALSE(sync::resolved_state_at(store, room_id, 10U).has_value()); + REQUIRE(sync::resolved_state_at(store, room_id, 11U) == std::vector{"$a"}); + } + } +} + +SCENARIO("A delta over a window with no state change reads none of the room's state", "[sync][state-change-log]") +{ + GIVEN("a room with many state rows, synced at 20") + { + auto store = db::PersistentStore{}; + for (auto index = 0U; index < 50U; ++index) + { + auto const event_id = "$k" + std::to_string(index); + store_state_event(store, "org.example.key", std::to_string(index), event_id, 1U + index); + set_current(store, "org.example.key", std::to_string(index), event_id, 1U + index); + } + store.state_change_log.start(10U); + store.state_change_log.note_served(20U); + + WHEN("the delta from 20 to 40 is taken") + { + auto const rows_before = store.state_rows_examined.value(); + auto const log_before = store.state_change_log.rows_examined().value(); + auto const changes = sync::resolved_state_changes(store, room_id, 20U, 40U); + + THEN("it is empty and reads no state row and no change") + { + REQUIRE(changes == std::vector{}); + REQUIRE(store.state_rows_examined.value() == rows_before); + REQUIRE(store.state_change_log.rows_examined().value() == log_before); + } + } + + WHEN("one key changes and the delta is taken") + { + store_state_event(store, "org.example.key", "7", "$k7b", 60U); + set_current(store, "org.example.key", "7", "$k7b", 60U); + auto const rows_before = store.state_rows_examined.value(); + auto const changes = sync::resolved_state_changes(store, room_id, 20U, 60U); + + THEN("it names that key and reads one state row") + { + REQUIRE(changes == std::vector{"$k7b"}); + REQUIRE(store.state_rows_examined.value() - rows_before <= 1U); + } + } + } +} diff --git a/tests/unit/test_state_change_log.cpp b/tests/unit/test_state_change_log.cpp new file mode 100644 index 000000000..5de95eb77 --- /dev/null +++ b/tests/unit/test_state_change_log.cpp @@ -0,0 +1,300 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The state change log (ADR-0827): what `/sync`'s `state_after` reads to tell a client exactly what changed between two +// positions. A change is filed above every position already served, a position before the log started or past what it +// still holds is not covered, and both bounds hold. + +#include "merovingian/database/StateChangeLog.hpp" + +#include + +#include +#include +#include +#include +#include +#include + +namespace +{ + +namespace db = merovingian::database; + +constexpr auto room_id = std::string_view{"!room:example.org"}; +constexpr auto other_room_id = std::string_view{"!other:example.org"}; + +// The event IDs of the changes `log` holds for `room` above `position`, in its order. +[[nodiscard]] auto event_ids_after(db::StateChangeLog const& log, std::string_view room, std::uint64_t position) + -> std::vector +{ + auto ids = std::vector{}; + for (auto const* change : log.changes_after(room, position)) + { + ids.push_back(change->event_id); + } + return ids; +} + +// The position `log` filed the one change of `room` above `position` at. +[[nodiscard]] auto only_position_after(db::StateChangeLog const& log, std::string_view room, std::uint64_t position) + -> std::uint64_t +{ + auto const changes = log.changes_after(room, position); + REQUIRE(changes.size() == 1U); + return changes.front()->position; +} + +} // namespace + +SCENARIO("The state change log records nothing until it starts", "[database][state-change-log]") +{ + GIVEN("a log that has not been started, as in the federation worker") + { + auto log = db::StateChangeLog{}; + + WHEN("a change is recorded") + { + log.record(room_id, "m.room.topic", "", "$a", "$b", 5U); + + THEN("nothing is held and no position is covered") + { + REQUIRE_FALSE(log.active()); + REQUIRE(log.size() == 0U); + REQUIRE_FALSE(log.covers(room_id, 5U)); + REQUIRE_FALSE(log.has_change_after(room_id, 0U)); + } + } + } +} + +SCENARIO("A started log covers positions from its floor and files changes above it", "[database][state-change-log]") +{ + GIVEN("a log started at position 10") + { + auto log = db::StateChangeLog{}; + log.start(10U); + + THEN("a position at or below the floor is not covered and one above it is") + { + REQUIRE(log.active()); + REQUIRE_FALSE(log.covers(room_id, 9U)); + REQUIRE_FALSE(log.covers(room_id, 10U)); + REQUIRE(log.covers(room_id, 11U)); + } + + WHEN("a change caused by an event ordered at or below the floor is recorded") + { + log.record(room_id, "m.room.topic", "", "$a", "$b", 3U); + + THEN("it is filed above the floor, so the state at the floor is unchanged") + { + REQUIRE(only_position_after(log, room_id, 10U) == 11U); + REQUIRE(log.has_change_after(room_id, 10U)); + REQUIRE_FALSE(log.has_change_after(room_id, 11U)); + } + } + + WHEN("a change caused by an event ordered above the floor is recorded") + { + log.record(room_id, "m.room.topic", "", "$a", "$b", 25U); + + THEN("it is filed at that event's ordering") + { + REQUIRE(only_position_after(log, room_id, 10U) == 25U); + } + } + + WHEN("a change caused by no event is recorded") + { + log.record(room_id, "m.room.topic", "", "$a", "$b", 0U); + + THEN("it is filed just above the floor") + { + REQUIRE(only_position_after(log, room_id, 10U) == 11U); + } + } + + WHEN("a write that leaves the value unchanged is recorded") + { + log.record(room_id, "m.room.topic", "", "$a", "$a", 20U); + + THEN("nothing is held") + { + REQUIRE(log.size() == 0U); + } + } + } +} + +SCENARIO("A change is never filed at or below a position a sync has answered at", "[database][state-change-log]") +{ + GIVEN("a log started at 10 that has answered a sync at 40") + { + auto log = db::StateChangeLog{}; + log.start(10U); + log.note_served(40U); + + WHEN("an event ordered at 30, a backfilled one, changes the state") + { + log.record(room_id, "m.room.topic", "", "$a", "$b", 30U); + + THEN("the change is filed at 41, so the state the client was told at 40 still holds at 40") + { + REQUIRE(only_position_after(log, room_id, 10U) == 41U); + REQUIRE(event_ids_after(log, room_id, 40U) == std::vector{"$b"}); + } + } + + WHEN("a sync at a lower position is noted afterwards") + { + log.note_served(20U); + log.record(room_id, "m.room.topic", "", "$a", "$b", 0U); + + THEN("the highest position served still holds") + { + REQUIRE(only_position_after(log, room_id, 10U) == 41U); + } + } + + WHEN("the last representable position has been served") + { + log.note_served(std::numeric_limits::max()); + log.record(room_id, "m.room.topic", "", "$a", "$b", 0U); + + THEN("the change is filed there, without wrapping, and changes_after the maximum is empty") + { + REQUIRE(only_position_after(log, room_id, 10U) == std::numeric_limits::max()); + REQUIRE(log.changes_after(room_id, std::numeric_limits::max()).empty()); + } + } + } +} + +SCENARIO("Changes come back by position and, at one position, in the order they were made", + "[database][state-change-log]") +{ + GIVEN("a started log with changes in two rooms") + { + auto log = db::StateChangeLog{}; + log.start(0U); + log.record(room_id, "m.room.topic", "", "$a", "$c", 20U); + log.record(room_id, "m.room.topic", "", "", "$a", 10U); + log.record(other_room_id, "m.room.topic", "", "", "$other", 15U); + log.record(room_id, "m.room.name", "", "", "$n1", 20U); + log.record(room_id, "m.room.name", "", "$n1", "$n2", 20U); + + WHEN("the room's changes above 0 are read") + { + auto const before = log.rows_examined().value(); + auto const ids = event_ids_after(log, room_id, 0U); + + THEN("they are ordered by position, then by the order recorded, and only that room's") + { + REQUIRE(ids == std::vector{"$a", "$c", "$n1", "$n2"}); + REQUIRE(log.rows_examined().value() - before == 4U); + } + } + + WHEN("the room's changes above 10 are read") + { + auto const before = log.rows_examined().value(); + auto const ids = event_ids_after(log, room_id, 10U); + + THEN("only the changes above 10 are examined") + { + REQUIRE(ids == std::vector{"$c", "$n1", "$n2"}); + REQUIRE(log.rows_examined().value() - before == 3U); + } + } + + WHEN("a room with no changes is read") + { + THEN("nothing is returned and the room is covered") + { + REQUIRE(log.changes_after("!quiet:example.org", 0U).empty()); + REQUIRE(log.covers("!quiet:example.org", 1U)); + } + } + } +} + +SCENARIO("Dropping a room's oldest change raises its horizon", "[database][state-change-log]") +{ + GIVEN("a started log holding as many changes of one room as it allows") + { + auto log = db::StateChangeLog{}; + log.start(0U); + for (auto index = std::size_t{0U}; index < db::StateChangeLog::max_changes_per_room; ++index) + { + log.record(room_id, "org.example.key", std::to_string(index), "", "$e" + std::to_string(index), + 100U + index); + } + REQUIRE(log.size() == db::StateChangeLog::max_changes_per_room); + REQUIRE(log.covers(room_id, 1U)); + + WHEN("one more change is recorded") + { + log.record(room_id, "org.example.key", "late", "", "$late", 5000U); + + THEN("the oldest is dropped and positions at or below it are no longer covered") + { + REQUIRE(log.size() == db::StateChangeLog::max_changes_per_room); + REQUIRE_FALSE(log.covers(room_id, 1U)); + REQUIRE_FALSE(log.covers(room_id, 99U)); + REQUIRE(log.covers(room_id, 100U)); + REQUIRE(log.covers(other_room_id, 1U)); + } + } + } +} + +SCENARIO("The log holds at most max_changes changes in all", "[database][state-change-log]") +{ + GIVEN("a started log filled with one change in each of max_changes rooms") + { + auto log = db::StateChangeLog{}; + log.start(0U); + for (auto index = std::size_t{0U}; index < db::StateChangeLog::max_changes; ++index) + { + log.record("!r" + std::to_string(index) + ":example.org", "m.room.topic", "", "", "$t", 1U + index); + } + REQUIRE(log.size() == db::StateChangeLog::max_changes); + + WHEN("one more change is recorded in another room") + { + log.record(room_id, "m.room.topic", "", "", "$t", 1000000U); + + THEN("the oldest change of all is dropped and its room is no longer covered below it") + { + REQUIRE(log.size() == db::StateChangeLog::max_changes); + REQUIRE_FALSE(log.covers("!r0:example.org", 0U)); + REQUIRE(log.covers("!r0:example.org", 1U)); + REQUIRE(log.covers("!r1:example.org", 1U)); + REQUIRE(log.covers(room_id, 1U)); + } + } + } +} + +SCENARIO("Starting the log again forgets what it held", "[database][state-change-log]") +{ + GIVEN("a log holding a change") + { + auto log = db::StateChangeLog{}; + log.start(0U); + log.record(room_id, "m.room.topic", "", "", "$t", 5U); + + WHEN("it is started again at 50") + { + log.start(50U); + + THEN("nothing is held and only positions above 50 are covered") + { + REQUIRE(log.size() == 0U); + REQUIRE_FALSE(log.covers(room_id, 50U)); + REQUIRE(log.covers(room_id, 51U)); + } + } + } +} From 543e99ffe88573c5941d205cf08517214c94ef7d Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 11:27:34 +0000 Subject: [PATCH 03/19] Sign and verify LiveKit HS256 tokens through typed functions in the crypto boundary Add crypto/LiveKitToken: a participant-token signer whose grant type cannot express roomCreate, roomAdmin or hidden, a room-creation signer with roomCreate alone, and an HS256 verifier that never reads the header's alg. libsodium's HMAC-SHA256 stays internal. Pinned vectors from Python's hmac and RFC 7515 A.1 (ADR-0828). Co-Authored-By: Claude Opus 5.5 --- ...-hs256-functions-in-the-crypto-boundary.md | 87 ++++++ docs/adr/index.md | 1 + .../crypto/LiveKitParticipantGrant.hpp | 27 ++ include/merovingian/crypto/LiveKitToken.hpp | 57 ++++ .../merovingian/crypto/VerifiedHs256Token.hpp | 18 ++ src/crypto/AGENTS.md | 1 + src/crypto/LiveKitToken.cpp | 215 +++++++++++++ src/crypto/meson.build | 1 + tests/meson.build | 1 + tests/unit/test_crypto_livekit_token.cpp | 286 ++++++++++++++++++ 10 files changed, 694 insertions(+) create mode 100644 docs/adr/0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md create mode 100644 include/merovingian/crypto/LiveKitParticipantGrant.hpp create mode 100644 include/merovingian/crypto/LiveKitToken.hpp create mode 100644 include/merovingian/crypto/VerifiedHs256Token.hpp create mode 100644 src/crypto/LiveKitToken.cpp create mode 100644 tests/unit/test_crypto_livekit_token.cpp diff --git a/docs/adr/0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md b/docs/adr/0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md new file mode 100644 index 000000000..48d184785 --- /dev/null +++ b/docs/adr/0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md @@ -0,0 +1,87 @@ +# LiveKit tokens are signed and verified only through typed HS256 functions in the crypto boundary + +* Status: accepted +* Date: 2026-11-17 + +## Context and Problem Statement + +The built-in MatrixRTC token service (MSC4195) hands clients LiveKit access tokens and calls LiveKit's room service, +and LiveKit signs the webhooks it sends. All three are JSON Web Tokens signed with HS256 (HMAC-SHA256) under the +LiveKit API secret. The project has HMAC-SHA1 for coturn only (ADR-0480) and no HMAC-SHA256, and a general +"sign these bytes" function would let any later code mint tokens with any rights, under the one secret that controls +the SFU. + +## Decision Drivers + +* A token never grants `roomCreate` to a participant, `roomAdmin`, `hidden`, or any right this server did not decide on. +* No new dependency, and no hand-written primitive. +* A webhook is accepted only under a MAC check that cannot be steered by the token itself. + +## Considered Options + +* A general `hmac_sha256(key, message)` and a JWT builder outside the crypto boundary. +* OpenSSL's `HMAC` with `EVP_sha256()`, as `hmac_sha1` uses. +* Typed signers and one verifier in `src/crypto/LiveKitToken.cpp`, over libsodium's `crypto_auth_hmacsha256`. + +## Decision Outcome + +Chosen option: typed signers and one verifier over libsodium, because no caller can widen what a token says, and +libsodium's HMAC-SHA256 is already in the build. + +* `crypto/LiveKitToken.hpp` declares exactly three operations: + * `sign_livekit_participant_token(api_key, api_secret, LiveKitParticipantGrant)`. The grant type holds the MSC4195 + identity and room name, one `can_publish` flag (which sets `canPublish` and `canPublishData` together), and + `nbf`/`exp`. It has no field for `roomCreate`, `roomAdmin`, `roomList`, `roomRecord`, `ingressAdmin`, `hidden`, + `canUpdateOwnMetadata`, a name, metadata or attributes, so no participant token can carry them. `roomJoin` and + `canSubscribe` are always true. + * `sign_livekit_room_create_token(api_key, api_secret, nbf, exp)`: `video` is `{"roomCreate":true}` and nothing else, + with no `sub` and no `room`. It is used for `CreateRoom` only. + * `verify_hs256_token(token, secret)`, for LiveKit's webhook requests. It bounds the token at 4,096 bytes, requires + exactly three non-empty unpadded URL-safe base64 segments, computes HMAC-SHA256 over the first two segments as + received, and compares it with the third in constant time (`constant_time_equal`, 32 bytes). It decodes the header + and payload only after the MAC matches, returns them undecided, and never reads the header's `alg`: an + `alg: none` or any other algorithm claim cannot change what is checked. The caller judges every claim. +* The HMAC is libsodium's `crypto_auth_hmacsha256_init`/`update`/`final`, which takes a key of any length, as RFC 7518 + section 3.2 requires. It stays in an anonymous namespace; the state is wiped after use. It is not exported. +* Every value placed in a token is checked before it is written, so the JSON needs no escaping: + * the API key is 1 to 128 ASCII letters, digits, `_`, `-` and `.`; + * the identity and room are 43 characters of the standard base64 alphabet; + * `nbf` is not negative and `exp` is after it. +* The payload's keys are in lexical order. Its characters cannot form a base64 group of 62 or 63, so the encoded + payload has no `-` or `_`. Element Call reads it with `atob`, which knows only the standard alphabet, so the signer + refuses (rather than emits) a payload that would contain either. +* The secret must be at least 32 bytes, for signing and verifying alike. The caller reads it per use from its file into + a `core::SecretBuffer`. This file holds no secret. +* HMAC-SHA1 stays for coturn alone (ADR-0480). Nothing here uses it. + +### Positive Consequences + +* A participant token's rights are fixed by a type, and the tests pin the exact bytes of every token kind against + vectors computed apart from this code (Python's `hmac`). The verifier is checked against RFC 7515 Appendix A.1. +* A future LiveKit call that needs a different grant must add a typed signer here, under review, and record the + call in an ADR. + +### Negative Consequences + +* A new LiveKit grant (for example a participant lookup with `roomAdmin`) cannot be added from the homeserver module + alone. That is the point. + +## Pros and Cons of the Options + +### A general HMAC-SHA256 and a JWT builder outside the boundary + +* Good, because it is flexible. +* Bad, because any caller could sign a token with `roomAdmin` or `hidden` under the SFU's secret. + +### OpenSSL `HMAC` with SHA-256 + +* Good, because it matches `hmac_sha1`. +* Bad, because libsodium already offers HMAC-SHA256 with an arbitrary-length key, and the boundary prefers libsodium + where it has the primitive (ADR-0014); OpenSSL was admitted for SHA-1 only because libsodium has none. + +## Links + +* Refines [ADR-0480](0480-turn-credentials-come-from-a-coturn-shared-secret-file-through-an-openssl-hmac-sha1.md) and [ADR-0014](0014-confine-cryptographic-primitives-behind-providers.md) +* [MSC4195](https://github.com/matrix-org/matrix-spec-proposals/blob/6d49798949e1b31023565d4ff1c7fe10f4cacf83/proposals/4195-matrixrtc-livekit.md) +* [RFC 7515 Appendix A.1](https://www.rfc-editor.org/rfc/rfc7515#appendix-A.1), + [RFC 7518 section 3.2](https://www.rfc-editor.org/rfc/rfc7518#section-3.2) diff --git a/docs/adr/index.md b/docs/adr/index.md index 7395dc176..e16796bae 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -706,3 +706,4 @@ * [0825 - A due delayed event is sent by one job through the ordinary send path, never early and at least once](0825-a-due-delayed-event-is-sent-by-one-job-through-the-ordinary-send-path-never-early-and-at-least-once.md) * [0826 - Delayed events are on by default, with a maximum delay, per-user caps and per-user rate limits](0826-delayed-events-are-on-by-default-with-a-maximum-delay-per-user-caps-and-per-user-rate-limits.md) * [0827 - A state_after delta is measured from an in-memory log of resolved state changes](0827-a-state-after-delta-is-measured-from-an-in-memory-log-of-resolved-state-changes.md) +* [0828 - LiveKit tokens are signed and verified only through typed HS256 functions in the crypto boundary](0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md) diff --git a/include/merovingian/crypto/LiveKitParticipantGrant.hpp b/include/merovingian/crypto/LiveKitParticipantGrant.hpp new file mode 100644 index 000000000..68bf86349 --- /dev/null +++ b/include/merovingian/crypto/LiveKitParticipantGrant.hpp @@ -0,0 +1,27 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::crypto +{ + +// What a LiveKit participant token says (ADR-0828). The token always grants `roomJoin` and `canSubscribe` in `room` +// and nothing else but what is here: there is no field for `roomCreate`, `roomAdmin`, `roomList`, `roomRecord`, +// `ingressAdmin`, `hidden`, `canUpdateOwnMetadata`, a name, metadata or attributes, so no token built from this type can +// carry them. +struct LiveKitParticipantGrant final +{ + // The MSC4195 participant identity and room name: unpadded standard base64 of a SHA-256, 43 characters each. + std::string identity{}; + std::string room{}; + // `canPublish` and `canPublishData` together. + bool can_publish{false}; + // Seconds since the Unix epoch. `expires` is after `not_before`. + std::int64_t not_before{0}; + std::int64_t expires{0}; +}; + +} // namespace merovingian::crypto diff --git a/include/merovingian/crypto/LiveKitToken.hpp b/include/merovingian/crypto/LiveKitToken.hpp new file mode 100644 index 000000000..9a00f8894 --- /dev/null +++ b/include/merovingian/crypto/LiveKitToken.hpp @@ -0,0 +1,57 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/crypto/LiveKitParticipantGrant.hpp" +#include "merovingian/crypto/VerifiedHs256Token.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::crypto +{ + +// LiveKit's tokens are JWTs signed with HMAC-SHA256 under the API secret (ADR-0828). The MAC is libsodium's +// `crypto_auth_hmacsha256` and is not exposed: this file signs exactly two kinds of token, each built here from typed +// claims, and verifies one. There is no function that signs bytes a caller chose. + +// The shortest API secret accepted. LiveKit refuses shorter secrets itself. +inline constexpr auto livekit_api_secret_min_bytes = std::size_t{32U}; +// The longest API key and token accepted. +inline constexpr auto livekit_api_key_max_bytes = std::size_t{128U}; +inline constexpr auto hs256_token_max_bytes = std::size_t{4096U}; + +// Whether `api_key` can be a LiveKit API key here: 1 to `livekit_api_key_max_bytes` of ASCII letters, digits, `_`, `-` +// and `.`. The key is a token's `iss`; this alphabet needs no JSON escaping. +[[nodiscard]] auto livekit_api_key_is_valid(std::string_view api_key) noexcept -> bool; + +// Whether `value` is an MSC4195 identity or room name: 43 characters of the standard base64 alphabet, no padding. +[[nodiscard]] auto livekit_name_is_valid(std::string_view value) noexcept -> bool; + +// The participant token for `grant`, signed with `api_secret`: +// `{"alg":"HS256","typ":"JWT"}` and the claims `exp`, `iss` (`api_key`), `nbf`, `sub` (the identity) and `video` +// (`room`, `roomJoin` true, `canSubscribe` true, `canPublish` and `canPublishData` from the grant). nullopt when the +// key, a name, the times (`expires` not after `not_before`, or negative) or the secret (shorter than +// `livekit_api_secret_min_bytes`) is not valid, or libsodium fails. Every character of its payload segment comes from +// the standard and URL-safe base64 alphabets alike (no `-` or `_`), which Element Call's decoder needs. +[[nodiscard]] auto sign_livekit_participant_token(std::string_view api_key, std::span api_secret, + LiveKitParticipantGrant const& grant) -> std::optional; + +// The service token for one call of LiveKit's room service: `video` holds `roomCreate` true and nothing else, `sub` and +// `room` are absent. For `CreateRoom` only. nullopt on the same refusals as above. +[[nodiscard]] auto sign_livekit_room_create_token(std::string_view api_key, std::span api_secret, + std::int64_t not_before, std::int64_t expires) + -> std::optional; + +// Verifies that `token` is three unpadded URL-safe base64 segments whose third is the HMAC-SHA256 under `secret` of the +// first two joined by `.`, compared in constant time, and returns the decoded header and payload. The header's `alg` +// is never consulted: only HMAC-SHA256 is ever checked. nullopt for a token longer than `hs256_token_max_bytes`, a +// malformed segment, a short secret or a MAC that does not match. +[[nodiscard]] auto verify_hs256_token(std::string_view token, std::span secret) + -> std::optional; + +} // namespace merovingian::crypto diff --git a/include/merovingian/crypto/VerifiedHs256Token.hpp b/include/merovingian/crypto/VerifiedHs256Token.hpp new file mode 100644 index 000000000..e6fa56a04 --- /dev/null +++ b/include/merovingian/crypto/VerifiedHs256Token.hpp @@ -0,0 +1,18 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::crypto +{ + +// The decoded parts of an HS256 token whose MAC `verify_hs256_token` checked. Nothing in them has been judged: the +// caller parses both and checks every claim it relies on. +struct VerifiedHs256Token final +{ + std::string header_json{}; + std::string payload_json{}; +}; + +} // namespace merovingian::crypto diff --git a/src/crypto/AGENTS.md b/src/crypto/AGENTS.md index 8c009565f..f030519e3 100644 --- a/src/crypto/AGENTS.md +++ b/src/crypto/AGENTS.md @@ -15,6 +15,7 @@ or `src/core/SecretBuffer.cpp`.** `scripts/reject-unsafe.sh` enforces this for b | `RefusingEd25519Provider.cpp` | `RefusingEd25519Provider` — the federation worker's provider: refuses every `sign` and `verify` (ADR-0078) | | `SigningService.cpp` | Server signing-key selection and delegation to the Ed25519 provider | | `HmacSha1.cpp` | `hmac_sha1`: OpenSSL's `HMAC` with SHA-1, for the coturn REST API's TURN password only (ADR-0480). Not for any new use of SHA-1 | +| `LiveKitToken.cpp` | LiveKit HS256 tokens (ADR-0828): `sign_livekit_participant_token` (grant type cannot express create, admin or hidden), `sign_livekit_room_create_token` (`roomCreate` only) and `verify_hs256_token` (webhooks; never reads `alg`). libsodium HMAC-SHA256 stays internal: there is no general HMAC-SHA256 or "sign these bytes" function | | `ConstantTime.cpp` | Constant-time byte comparison (wraps `sodium_memcmp`) | | `Random.cpp` | Bounded random byte generation (wraps `randombytes_buf`) | | `GenericHash.cpp` | Domain-separated BLAKE2b hashing helpers | diff --git a/src/crypto/LiveKitToken.cpp b/src/crypto/LiveKitToken.cpp new file mode 100644 index 000000000..942ba6ccd --- /dev/null +++ b/src/crypto/LiveKitToken.cpp @@ -0,0 +1,215 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/crypto/LiveKitToken.hpp" + +#include "merovingian/crypto/ConstantTime.hpp" +#include "merovingian/crypto/Encoding.hpp" + +#include +#include +#include +#include +#include +#include + +#include + +namespace merovingian::crypto +{ +namespace +{ + +constexpr auto mac_bytes = std::size_t{crypto_auth_hmacsha256_BYTES}; +constexpr auto livekit_name_bytes = std::size_t{43U}; +// The header every token signed here carries. It is never read back from a token: `verify_hs256_token` returns the +// header it received for the caller to judge, and checks HMAC-SHA256 whatever the header says. +constexpr auto hs256_header_json = std::string_view{R"({"alg":"HS256","typ":"JWT"})"}; + +[[nodiscard]] auto is_ascii_alnum(char const character) noexcept -> bool +{ + return (character >= 'a' && character <= 'z') || (character >= 'A' && character <= 'Z') || + (character >= '0' && character <= '9'); +} + +// HMAC-SHA256 of `message` under `key`. The init/update/final form takes a key of any length, as JWT HS256 requires +// (RFC 7518 3.2); `crypto_auth_hmacsha256` alone takes exactly 32 bytes. +[[nodiscard]] auto hmac_sha256(std::span key, std::string_view message) + -> std::optional> +{ + if (sodium_init() < 0) + { + return std::nullopt; + } + auto state = crypto_auth_hmacsha256_state{}; + auto mac = std::array{}; + auto const ok = crypto_auth_hmacsha256_init(&state, key.data(), key.size()) == 0 && + crypto_auth_hmacsha256_update(&state, reinterpret_cast(message.data()), + message.size()) == 0 && + crypto_auth_hmacsha256_final(&state, mac.data()) == 0; + // The state holds the key's inner and outer pads. + sodium_memzero(&state, sizeof(state)); + if (!ok) + { + sodium_memzero(mac.data(), mac.size()); + return std::nullopt; + } + return mac; +} + +[[nodiscard]] auto as_string_view(std::array const& mac) noexcept -> std::string_view +{ + return {reinterpret_cast(mac.data()), mac.size()}; +} + +// `header.payload.signature` for `payload_json`, whose every value the caller validated so that it needs no escaping. +[[nodiscard]] auto sign_payload(std::span api_secret, std::string_view payload_json) + -> std::optional +{ + if (api_secret.size() < livekit_api_secret_min_bytes) + { + return std::nullopt; + } + auto header = base64_urlsafe_encode(hs256_header_json); + auto payload = base64_urlsafe_encode(payload_json); + if (!header || !payload) + { + return std::nullopt; + } + // Element Call reads the payload with `atob`, which knows only the standard alphabet. The claims hold only ASCII + // letters, digits and `{}":,+/._-`, none of which can put a 62 or 63 in a base64 group, so this never fires; it is + // the guarantee stated where it is relied on. + if (payload->find_first_of("-_") != std::string::npos) + { + return std::nullopt; + } + auto signing_input = std::move(*header); + signing_input += '.'; + signing_input += *payload; + auto const mac = hmac_sha256(api_secret, signing_input); + if (!mac) + { + return std::nullopt; + } + auto signature = base64_urlsafe_encode(as_string_view(*mac)); + if (!signature) + { + return std::nullopt; + } + signing_input += '.'; + signing_input += *signature; + return signing_input; +} + +[[nodiscard]] auto times_are_valid(std::int64_t const not_before, std::int64_t const expires) noexcept -> bool +{ + return not_before >= 0 && expires > not_before; +} + +} // namespace + +auto livekit_api_key_is_valid(std::string_view const api_key) noexcept -> bool +{ + return !api_key.empty() && api_key.size() <= livekit_api_key_max_bytes && + std::ranges::all_of(api_key, [](char const character) { + return is_ascii_alnum(character) || character == '_' || character == '-' || character == '.'; + }); +} + +auto livekit_name_is_valid(std::string_view const value) noexcept -> bool +{ + return value.size() == livekit_name_bytes && std::ranges::all_of(value, [](char const character) { + return is_ascii_alnum(character) || character == '+' || character == '/'; + }); +} + +auto sign_livekit_participant_token(std::string_view const api_key, std::span const api_secret, + LiveKitParticipantGrant const& grant) -> std::optional +{ + if (!livekit_api_key_is_valid(api_key) || !livekit_name_is_valid(grant.identity) || + !livekit_name_is_valid(grant.room) || !times_are_valid(grant.not_before, grant.expires)) + { + return std::nullopt; + } + auto const publish = std::string_view{grant.can_publish ? "true" : "false"}; + // Keys in lexical order, as canonical JSON would put them; LiveKit does not care, a reader of a token might. + auto payload = std::string{R"({"exp":)"}; + payload += std::to_string(grant.expires); + payload += R"(,"iss":")"; + payload += api_key; + payload += R"(","nbf":)"; + payload += std::to_string(grant.not_before); + payload += R"(,"sub":")"; + payload += grant.identity; + payload += R"(","video":{"canPublish":)"; + payload += publish; + payload += R"(,"canPublishData":)"; + payload += publish; + payload += R"(,"canSubscribe":true,"room":")"; + payload += grant.room; + payload += R"(","roomJoin":true}})"; + return sign_payload(api_secret, payload); +} + +auto sign_livekit_room_create_token(std::string_view const api_key, std::span const api_secret, + std::int64_t const not_before, std::int64_t const expires) + -> std::optional +{ + if (!livekit_api_key_is_valid(api_key) || !times_are_valid(not_before, expires)) + { + return std::nullopt; + } + auto payload = std::string{R"({"exp":)"}; + payload += std::to_string(expires); + payload += R"(,"iss":")"; + payload += api_key; + payload += R"(","nbf":)"; + payload += std::to_string(not_before); + payload += R"(,"video":{"roomCreate":true}})"; + return sign_payload(api_secret, payload); +} + +auto verify_hs256_token(std::string_view const token, std::span const secret) + -> std::optional +{ + if (secret.size() < livekit_api_secret_min_bytes || token.size() > hs256_token_max_bytes) + { + return std::nullopt; + } + auto const first_dot = token.find('.'); + if (first_dot == std::string_view::npos) + { + return std::nullopt; + } + auto const second_dot = token.find('.', first_dot + 1U); + if (second_dot == std::string_view::npos || token.find('.', second_dot + 1U) != std::string_view::npos) + { + return std::nullopt; + } + auto const header_segment = token.substr(0U, first_dot); + auto const payload_segment = token.substr(first_dot + 1U, second_dot - first_dot - 1U); + auto const signature_segment = token.substr(second_dot + 1U); + if (header_segment.empty() || payload_segment.empty() || signature_segment.empty()) + { + return std::nullopt; + } + auto const signature = base64_urlsafe_decode(signature_segment); + if (!signature || signature->size() != mac_bytes) + { + return std::nullopt; + } + // The MAC covers the segments as received, so nothing is decoded before it is checked. + auto const mac = hmac_sha256(secret, token.substr(0U, second_dot)); + if (!mac || !constant_time_equal(as_string_view(*mac), *signature)) + { + return std::nullopt; + } + auto header = base64_urlsafe_decode(header_segment); + auto payload = base64_urlsafe_decode(payload_segment); + if (!header || !payload) + { + return std::nullopt; + } + return VerifiedHs256Token{.header_json = std::move(*header), .payload_json = std::move(*payload)}; +} + +} // namespace merovingian::crypto diff --git a/src/crypto/meson.build b/src/crypto/meson.build index fed88f0c8..098a0b016 100644 --- a/src/crypto/meson.build +++ b/src/crypto/meson.build @@ -4,6 +4,7 @@ crypto_sources = files( 'Encoding.cpp', 'GenericHash.cpp', 'HmacSha1.cpp', + 'LiveKitToken.cpp', 'IpcAuthKey.cpp', 'IpcStreamCipher.cpp', 'LibraryVersions.cpp', diff --git a/tests/meson.build b/tests/meson.build index 797a78ba6..74aa7cec4 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -343,6 +343,7 @@ shell = find_program('sh') 'unit/test_config_reload_plan.cpp', 'unit/test_config_reload_policy.cpp', 'unit/test_crypto.cpp', + 'unit/test_crypto_livekit_token.cpp', 'unit/test_crypto_oauth_client_id.cpp', 'unit/test_crypto_token_key_cache.cpp', 'unit/test_database_backend_config.cpp', diff --git a/tests/unit/test_crypto_livekit_token.cpp b/tests/unit/test_crypto_livekit_token.cpp new file mode 100644 index 000000000..21d472f06 --- /dev/null +++ b/tests/unit/test_crypto_livekit_token.cpp @@ -0,0 +1,286 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// LiveKit's HS256 tokens (ADR-0828): the two typed signers and the verifier. The signed vectors were computed apart from +// this code with Python's `hmac` and `hashlib`; the verifier's vector is RFC 7515 Appendix A.1. + +#include "merovingian/crypto/LiveKitToken.hpp" + +#include + +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::crypto::LiveKitParticipantGrant; + +// The MSC4195 vectors: the identity of `["@alice:example.com","memberABC"]` and the room of +// `["!roomid:example.com","slot1234"]`. +constexpr auto alice_identity = "M3VnsLXrkbxIDINXO64u8PZzFyD9ZYFiQULR2dshWYs"; +constexpr auto slot_room = "O8437W3+jmzMVjoIP3tNwbm+XxHQk2iKpOA7aqw3qSc"; +constexpr auto api_key = "APIkey_1.x-"; + +[[nodiscard]] auto counting_secret() -> std::vector +{ + auto secret = std::vector(32U); + for (auto index = std::size_t{0U}; index < secret.size(); ++index) + { + secret[index] = static_cast(index); + } + return secret; +} + +[[nodiscard]] auto alice_grant(bool can_publish) -> LiveKitParticipantGrant +{ + return LiveKitParticipantGrant{.identity = alice_identity, + .room = slot_room, + .can_publish = can_publish, + .not_before = 1'700'000'000, + .expires = 1'700'003'600}; +} + +// RFC 7515 A.1's key and token. +constexpr auto rfc7515_key = std::array{ + 0x03U, 0x23U, 0x35U, 0x4bU, 0x2bU, 0x0fU, 0xa5U, 0xbcU, 0x83U, 0x7eU, 0x06U, 0x65U, 0x77U, 0x7bU, 0xa6U, 0x8fU, + 0x5aU, 0xb3U, 0x28U, 0xe6U, 0xf0U, 0x54U, 0xc9U, 0x28U, 0xa9U, 0x0fU, 0x84U, 0xb2U, 0xd2U, 0x50U, 0x2eU, 0xbfU, + 0xd3U, 0xfbU, 0x5aU, 0x92U, 0xd2U, 0x06U, 0x47U, 0xefU, 0x96U, 0x8aU, 0xb4U, 0xc3U, 0x77U, 0x62U, 0x3dU, 0x22U, + 0x3dU, 0x2eU, 0x21U, 0x72U, 0x05U, 0x2eU, 0x4fU, 0x08U, 0xc0U, 0xcdU, 0x9aU, 0xf5U, 0x67U, 0xd0U, 0x80U, 0xa3U}; +constexpr auto rfc7515_token = + "eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9p" + "c19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"; + +[[nodiscard]] auto payload_segment(std::string const& token) -> std::string +{ + auto const first = token.find('.'); + auto const second = token.find('.', first + 1U); + return token.substr(first + 1U, second - first - 1U); +} + +} // namespace + +SCENARIO("A participant token is the pinned HS256 JWT for its grant", "[crypto][livekit][rtc]") +{ + GIVEN("a 32-byte secret, an API key and Alice's MSC4195 identity and room") + { + auto const secret = counting_secret(); + + WHEN("a publishing token and a subscribe-only token are signed") + { + auto const publisher = + merovingian::crypto::sign_livekit_participant_token(api_key, secret, alice_grant(true)); + auto const subscriber = + merovingian::crypto::sign_livekit_participant_token(api_key, secret, alice_grant(false)); + + THEN("each is byte for byte the token computed independently") + { + REQUIRE(publisher.has_value()); + REQUIRE(subscriber.has_value()); + CHECK(*publisher == + "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9." + "eyJleHAiOjE3MDAwMDM2MDAsImlzcyI6IkFQSWtleV8xLngtIiwibmJmIjoxNzAwMDAwMDAwLCJzdWIiOiJNM1Zuc0xYcmti" + "eElESU5YTzY0dThQWnpGeUQ5WllGaVFVTFIyZHNoV1lzIiwidmlkZW8iOnsiY2FuUHVibGlzaCI6dHJ1ZSwiY2FuUHVibGlz" + "aERhdGEiOnRydWUsImNhblN1YnNjcmliZSI6dHJ1ZSwicm9vbSI6Ik84NDM3VzMram16TVZqb0lQM3ROd2JtK1h4SFFrMmlL" + "cE9BN2FxdzNxU2MiLCJyb29tSm9pbiI6dHJ1ZX19.SG0vHhzqCslGsLDX5LZYqggMxPneFx5FQvIqAYQUiH0"); + CHECK(*subscriber == + "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9." + "eyJleHAiOjE3MDAwMDM2MDAsImlzcyI6IkFQSWtleV8xLngtIiwibmJmIjoxNzAwMDAwMDAwLCJzdWIiOiJNM1Zuc0xYcmti" + "eElESU5YTzY0dThQWnpGeUQ5WllGaVFVTFIyZHNoV1lzIiwidmlkZW8iOnsiY2FuUHVibGlzaCI6ZmFsc2UsImNhblB1Ymxp" + "c2hEYXRhIjpmYWxzZSwiY2FuU3Vic2NyaWJlIjp0cnVlLCJyb29tIjoiTzg0MzdXMytqbXpNVmpvSVAzdE53Ym0rWHhIUWsy" + "aUtwT0E3YXF3M3FTYyIsInJvb21Kb2luIjp0cnVlfX0.AfihjyEiSMPDtr4DhJZ0U4ouv2fsWs2BoKe0fvJGdNE"); + } + + THEN("the payload segments are readable with the standard base64 alphabet") + { + REQUIRE(publisher.has_value()); + REQUIRE(subscriber.has_value()); + CHECK(payload_segment(*publisher).find_first_of("-_") == std::string::npos); + CHECK(payload_segment(*subscriber).find_first_of("-_") == std::string::npos); + } + } + } +} + +SCENARIO("A signed participant token verifies and says nothing beyond its grant", "[crypto][livekit][rtc]") +{ + GIVEN("a participant token signed for Alice") + { + auto const secret = counting_secret(); + auto const token = merovingian::crypto::sign_livekit_participant_token(api_key, secret, alice_grant(true)); + REQUIRE(token.has_value()); + + WHEN("it is verified with the same secret") + { + auto const verified = merovingian::crypto::verify_hs256_token(*token, secret); + + THEN("the header and the claims are the ones signed, with no create, admin or hidden right") + { + REQUIRE(verified.has_value()); + CHECK(verified->header_json == R"({"alg":"HS256","typ":"JWT"})"); + CHECK(verified->payload_json == + R"({"exp":1700003600,"iss":"APIkey_1.x-","nbf":1700000000,"sub":")" + std::string{alice_identity} + + R"(","video":{"canPublish":true,"canPublishData":true,"canSubscribe":true,"room":")" + + std::string{slot_room} + R"(","roomJoin":true}})"); + CHECK(verified->payload_json.find("roomCreate") == std::string::npos); + CHECK(verified->payload_json.find("roomAdmin") == std::string::npos); + CHECK(verified->payload_json.find("hidden") == std::string::npos); + } + } + } +} + +SCENARIO("A room-creation token grants roomCreate and nothing else", "[crypto][livekit][rtc]") +{ + GIVEN("a 32-byte secret and an API key") + { + auto const secret = counting_secret(); + + WHEN("a room-creation token is signed for one minute") + { + auto const token = + merovingian::crypto::sign_livekit_room_create_token(api_key, secret, 1'700'000'000, 1'700'000'060); + + THEN("it is byte for byte the token computed independently") + { + REQUIRE(token.has_value()); + CHECK(*token == "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9." + "eyJleHAiOjE3MDAwMDAwNjAsImlzcyI6IkFQSWtleV8xLngtIiwibmJmIjoxNzAwMDAwMDAwLCJ2aWRlbyI6eyJy" + "b29tQ3JlYXRlIjp0cnVlfX0.H8s0R8qoKX-6VA99JYKgYg0WktDfwQ-zfAuzjRi8j6M"); + } + } + } +} + +SCENARIO("The signers refuse a claim or secret they cannot sign safely", "[crypto][livekit][rtc][negative]") +{ + GIVEN("a valid grant, key and secret") + { + auto const secret = counting_secret(); + + WHEN("one of them is changed to something out of bounds") + { + auto const short_secret = std::vector(31U, 0x01U); + auto with_identity = [](std::string identity) { + auto grant = alice_grant(true); + grant.identity = std::move(identity); + return grant; + }; + auto with_room = [](std::string room) { + auto grant = alice_grant(true); + grant.room = std::move(room); + return grant; + }; + auto with_times = [](std::int64_t not_before, std::int64_t expires) { + auto grant = alice_grant(true); + grant.not_before = not_before; + grant.expires = expires; + return grant; + }; + auto const sign = [&secret](std::string const& key, LiveKitParticipantGrant const& grant) { + return merovingian::crypto::sign_livekit_participant_token(key, secret, grant); + }; + + THEN("no token is signed") + { + CHECK_FALSE( + merovingian::crypto::sign_livekit_participant_token(api_key, short_secret, alice_grant(true))); + CHECK_FALSE(sign("", alice_grant(true))); + CHECK_FALSE(sign("key with space", alice_grant(true))); + CHECK_FALSE(sign(R"(key")", alice_grant(true))); + CHECK_FALSE(sign(std::string(129U, 'k'), alice_grant(true))); + CHECK(sign(std::string(128U, 'k'), alice_grant(true))); + CHECK_FALSE(sign(api_key, with_identity("@alice:example.com"))); + CHECK_FALSE(sign(api_key, with_identity(std::string(42U, 'A')))); + CHECK_FALSE(sign(api_key, with_identity(std::string(42U, 'A') + "="))); + CHECK_FALSE(sign(api_key, with_identity(std::string(42U, 'A') + "-"))); + CHECK_FALSE(sign(api_key, with_room(std::string(44U, 'A')))); + CHECK_FALSE(sign(api_key, with_room(std::string(42U, 'A') + "\""))); + CHECK_FALSE(sign(api_key, with_times(1'700'000'000, 1'700'000'000))); + CHECK_FALSE(sign(api_key, with_times(1'700'000'001, 1'700'000'000))); + CHECK_FALSE(sign(api_key, with_times(-1, 1'700'000'000))); + CHECK_FALSE(merovingian::crypto::sign_livekit_room_create_token(api_key, short_secret, 0, 60)); + CHECK_FALSE(merovingian::crypto::sign_livekit_room_create_token("bad key", secret, 0, 60)); + CHECK_FALSE(merovingian::crypto::sign_livekit_room_create_token(api_key, secret, 60, 60)); + } + } + } +} + +SCENARIO("The verifier accepts RFC 7515's HS256 example", "[crypto][livekit][rtc]") +{ + GIVEN("the key and token of RFC 7515 Appendix A.1") + { + WHEN("the token is verified") + { + auto const verified = merovingian::crypto::verify_hs256_token(rfc7515_token, rfc7515_key); + + THEN("it verifies and its header and payload are the RFC's, line breaks included") + { + REQUIRE(verified.has_value()); + CHECK(verified->header_json == "{\"typ\":\"JWT\",\r\n \"alg\":\"HS256\"}"); + CHECK(verified->payload_json == + "{\"iss\":\"joe\",\r\n \"exp\":1300819380,\r\n \"http://example.com/is_root\":true}"); + } + } + } +} + +SCENARIO("The verifier refuses a token that is altered, malformed or under another key", + "[crypto][livekit][rtc][negative]") +{ + GIVEN("a participant token signed with one secret") + { + auto const secret = counting_secret(); + auto const token = merovingian::crypto::sign_livekit_participant_token(api_key, secret, alice_grant(false)); + REQUIRE(token.has_value()); + auto const first_dot = token->find('.'); + auto const second_dot = token->find('.', first_dot + 1U); + + WHEN("it is altered or checked under the wrong key") + { + auto other_secret = secret; + other_secret[0] ^= 0x01U; + auto flipped_payload = *token; + flipped_payload[first_dot + 5U] = flipped_payload[first_dot + 5U] == 'A' ? 'B' : 'A'; + auto flipped_signature = *token; + flipped_signature.back() = flipped_signature.back() == 'A' ? 'B' : 'A'; + auto const header = token->substr(0U, first_dot); + auto const payload = token->substr(first_dot + 1U, second_dot - first_dot - 1U); + auto const signature = token->substr(second_dot + 1U); + // `{"alg":"none"}`: an unsigned token is refused whatever its header claims. + auto const alg_none = std::string{"eyJhbGciOiJub25lIn0."} + payload + "."; + + THEN("none of them verifies") + { + CHECK_FALSE(merovingian::crypto::verify_hs256_token(*token, other_secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(*token, std::span{secret}.first(31U))); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(flipped_payload, secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(flipped_signature, secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(alg_none, secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(header + "." + payload, secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(*token + ".", secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(*token + "." + signature, secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(header + ".." + signature, secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(header + "." + payload + "." + signature + "=", + secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token(header + "." + payload + "." + signature.substr(1U), + secret)); + CHECK_FALSE(merovingian::crypto::verify_hs256_token("", secret)); + } + } + + WHEN("a token is longer than the bound") + { + auto const long_token = std::string(4097U, 'A'); + + THEN("it is refused before any decoding") + { + CHECK_FALSE(merovingian::crypto::verify_hs256_token(long_token, secret)); + } + } + } +} From 055855a3cb4a74bbb8f71d0ebc13f418ea4f5441 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 12:28:18 +0000 Subject: [PATCH 04/19] Add a one-room roomAdmin LiveKit token signer for GetParticipant sign_livekit_room_admin_token signs {"room":,"roomAdmin":true} for one MSC4195 room name and nothing else, with a vector computed apart from this code. ADR-0828 and the crypto boundary doc now list four operations. Co-Authored-By: Claude Opus 5.5 --- ...-hs256-functions-in-the-crypto-boundary.md | 10 +- docs/crypto-boundary.md | 9 + .../crypto/LiveKitParticipantGrant.hpp | 4 +- include/merovingian/crypto/LiveKitToken.hpp | 10 +- src/crypto/AGENTS.md | 2 +- src/crypto/LiveKitToken.cpp | 195 ++++++++++-------- tests/unit/test_crypto_livekit_token.cpp | 77 ++++++- 7 files changed, 204 insertions(+), 103 deletions(-) diff --git a/docs/adr/0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md b/docs/adr/0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md index 48d184785..4a6c2f8d9 100644 --- a/docs/adr/0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md +++ b/docs/adr/0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md @@ -28,7 +28,7 @@ the SFU. Chosen option: typed signers and one verifier over libsodium, because no caller can widen what a token says, and libsodium's HMAC-SHA256 is already in the build. -* `crypto/LiveKitToken.hpp` declares exactly three operations: +* `crypto/LiveKitToken.hpp` declares exactly four operations: * `sign_livekit_participant_token(api_key, api_secret, LiveKitParticipantGrant)`. The grant type holds the MSC4195 identity and room name, one `can_publish` flag (which sets `canPublish` and `canPublishData` together), and `nbf`/`exp`. It has no field for `roomCreate`, `roomAdmin`, `roomList`, `roomRecord`, `ingressAdmin`, `hidden`, @@ -36,6 +36,10 @@ libsodium's HMAC-SHA256 is already in the build. `canSubscribe` are always true. * `sign_livekit_room_create_token(api_key, api_secret, nbf, exp)`: `video` is `{"roomCreate":true}` and nothing else, with no `sub` and no `room`. It is used for `CreateRoom` only. + * `sign_livekit_room_admin_token(api_key, api_secret, room_name, nbf, exp)`: `video` is `{"room":, + "roomAdmin":true}` and nothing else, with no `sub`. LiveKit limits `roomAdmin` to the room named, and the room name + must be an MSC4195 name (43 standard base64 characters). It is used for `GetParticipant` only, by MSC4195's + delegated delayed leave. * `verify_hs256_token(token, secret)`, for LiveKit's webhook requests. It bounds the token at 4,096 bytes, requires exactly three non-empty unpadded URL-safe base64 segments, computes HMAC-SHA256 over the first two segments as received, and compares it with the third in constant time (`constant_time_equal`, 32 bytes). It decodes the header @@ -63,8 +67,8 @@ libsodium's HMAC-SHA256 is already in the build. ### Negative Consequences -* A new LiveKit grant (for example a participant lookup with `roomAdmin`) cannot be added from the homeserver module - alone. That is the point. +* A new LiveKit grant cannot be added from the homeserver module alone. That is the point: the one-room `roomAdmin` + token for `GetParticipant` was added here, with its own vector, when the delegated delayed leave needed it. ## Pros and Cons of the Options diff --git a/docs/crypto-boundary.md b/docs/crypto-boundary.md index 00665b830..0c2d1b0e3 100644 --- a/docs/crypto-boundary.md +++ b/docs/crypto-boundary.md @@ -20,6 +20,15 @@ implementing custom cryptographic primitives. the coturn REST API defines a TURN password as the base64 of HMAC-SHA1 over the username (ADR-0480). libsodium has no SHA-1; OpenSSL is already a required dependency, so no new dependency enters the build, but `merovingian-crypto` now links it. No other code may use SHA-1 for a new purpose. +- LiveKit tokens (`LiveKitToken.cpp`, ADR-0828): HS256 JWTs, signed with libsodium's `crypto_auth_hmacsha256`, which + stays inside the file. There is no general "sign this payload" function: `sign_livekit_participant_token` takes a + `LiveKitParticipantGrant`, which cannot express `roomCreate`, `roomAdmin` or `hidden` and always writes + `canPublish`, `canPublishData` and `canSubscribe` (LiveKit reads an absent `canPublish` as true), and + `sign_livekit_room_create_token` grants `roomCreate` alone, and `sign_livekit_room_admin_token` grants `roomAdmin` + over one named MSC4195 room alone (for `GetParticipant`). `verify_hs256_token` checks the signature in constant + time and never trusts the header's `alg`. The API secret is a `core::SecretBuffer` the caller reads from its file + for each signature; the boundary refuses one shorter than 32 bytes. Pinned vectors are in + `tests/unit/test_crypto_livekit_token.cpp`. - Variable-length comparison uses domain-separated hashing so it does not leak input length through a premature length check. - Runtime signing secret material uses `core::SecretBuffer`, backed by diff --git a/include/merovingian/crypto/LiveKitParticipantGrant.hpp b/include/merovingian/crypto/LiveKitParticipantGrant.hpp index 68bf86349..7d54b3299 100644 --- a/include/merovingian/crypto/LiveKitParticipantGrant.hpp +++ b/include/merovingian/crypto/LiveKitParticipantGrant.hpp @@ -10,8 +10,8 @@ namespace merovingian::crypto // What a LiveKit participant token says (ADR-0828). The token always grants `roomJoin` and `canSubscribe` in `room` // and nothing else but what is here: there is no field for `roomCreate`, `roomAdmin`, `roomList`, `roomRecord`, -// `ingressAdmin`, `hidden`, `canUpdateOwnMetadata`, a name, metadata or attributes, so no token built from this type can -// carry them. +// `ingressAdmin`, `hidden`, `canUpdateOwnMetadata`, a name, metadata or attributes, so no token built from this type +// can carry them. struct LiveKitParticipantGrant final { // The MSC4195 participant identity and room name: unpadded standard base64 of a SHA-256, 43 characters each. diff --git a/include/merovingian/crypto/LiveKitToken.hpp b/include/merovingian/crypto/LiveKitToken.hpp index 9a00f8894..895e24d3e 100644 --- a/include/merovingian/crypto/LiveKitToken.hpp +++ b/include/merovingian/crypto/LiveKitToken.hpp @@ -16,7 +16,7 @@ namespace merovingian::crypto { // LiveKit's tokens are JWTs signed with HMAC-SHA256 under the API secret (ADR-0828). The MAC is libsodium's -// `crypto_auth_hmacsha256` and is not exposed: this file signs exactly two kinds of token, each built here from typed +// `crypto_auth_hmacsha256` and is not exposed: this file signs exactly three kinds of token, each built here from typed // claims, and verifies one. There is no function that signs bytes a caller chose. // The shortest API secret accepted. LiveKit refuses shorter secrets itself. @@ -47,6 +47,14 @@ inline constexpr auto hs256_token_max_bytes = std::size_t{4096U}; std::int64_t not_before, std::int64_t expires) -> std::optional; +// The service token for reading one participant of one room (`GetParticipant`, ADR-0830): `video` holds `room` +// (`room_name`) and `roomAdmin` true and nothing else; `sub` is absent. LiveKit's `roomAdmin` covers only the room +// named, so this token cannot act on any other room or create one. nullopt on the refusals above, or when +// `room_name` is not an MSC4195 room name. +[[nodiscard]] auto sign_livekit_room_admin_token(std::string_view api_key, std::span api_secret, + std::string_view room_name, std::int64_t not_before, + std::int64_t expires) -> std::optional; + // Verifies that `token` is three unpadded URL-safe base64 segments whose third is the HMAC-SHA256 under `secret` of the // first two joined by `.`, compared in constant time, and returns the decoded header and payload. The header's `alg` // is never consulted: only HMAC-SHA256 is ever checked. nullopt for a token longer than `hs256_token_max_bytes`, a diff --git a/src/crypto/AGENTS.md b/src/crypto/AGENTS.md index f030519e3..17b3bc6bd 100644 --- a/src/crypto/AGENTS.md +++ b/src/crypto/AGENTS.md @@ -15,7 +15,7 @@ or `src/core/SecretBuffer.cpp`.** `scripts/reject-unsafe.sh` enforces this for b | `RefusingEd25519Provider.cpp` | `RefusingEd25519Provider` — the federation worker's provider: refuses every `sign` and `verify` (ADR-0078) | | `SigningService.cpp` | Server signing-key selection and delegation to the Ed25519 provider | | `HmacSha1.cpp` | `hmac_sha1`: OpenSSL's `HMAC` with SHA-1, for the coturn REST API's TURN password only (ADR-0480). Not for any new use of SHA-1 | -| `LiveKitToken.cpp` | LiveKit HS256 tokens (ADR-0828): `sign_livekit_participant_token` (grant type cannot express create, admin or hidden), `sign_livekit_room_create_token` (`roomCreate` only) and `verify_hs256_token` (webhooks; never reads `alg`). libsodium HMAC-SHA256 stays internal: there is no general HMAC-SHA256 or "sign these bytes" function | +| `LiveKitToken.cpp` | LiveKit HS256 tokens (ADR-0828): `sign_livekit_participant_token` (grant type cannot express create, admin or hidden), `sign_livekit_room_create_token` (`roomCreate` only), `sign_livekit_room_admin_token` (`roomAdmin` for one named room, for `GetParticipant`) and `verify_hs256_token` (webhooks; never reads `alg`). libsodium HMAC-SHA256 stays internal: there is no general HMAC-SHA256 or "sign these bytes" function | | `ConstantTime.cpp` | Constant-time byte comparison (wraps `sodium_memcmp`) | | `Random.cpp` | Bounded random byte generation (wraps `randombytes_buf`) | | `GenericHash.cpp` | Domain-separated BLAKE2b hashing helpers | diff --git a/src/crypto/LiveKitToken.cpp b/src/crypto/LiveKitToken.cpp index 942ba6ccd..fba436f69 100644 --- a/src/crypto/LiveKitToken.cpp +++ b/src/crypto/LiveKitToken.cpp @@ -5,6 +5,8 @@ #include "merovingian/crypto/ConstantTime.hpp" #include "merovingian/crypto/Encoding.hpp" +#include + #include #include #include @@ -12,98 +14,97 @@ #include #include -#include - namespace merovingian::crypto { namespace { -constexpr auto mac_bytes = std::size_t{crypto_auth_hmacsha256_BYTES}; -constexpr auto livekit_name_bytes = std::size_t{43U}; -// The header every token signed here carries. It is never read back from a token: `verify_hs256_token` returns the -// header it received for the caller to judge, and checks HMAC-SHA256 whatever the header says. -constexpr auto hs256_header_json = std::string_view{R"({"alg":"HS256","typ":"JWT"})"}; - -[[nodiscard]] auto is_ascii_alnum(char const character) noexcept -> bool -{ - return (character >= 'a' && character <= 'z') || (character >= 'A' && character <= 'Z') || - (character >= '0' && character <= '9'); -} - -// HMAC-SHA256 of `message` under `key`. The init/update/final form takes a key of any length, as JWT HS256 requires -// (RFC 7518 3.2); `crypto_auth_hmacsha256` alone takes exactly 32 bytes. -[[nodiscard]] auto hmac_sha256(std::span key, std::string_view message) - -> std::optional> -{ - if (sodium_init() < 0) - { - return std::nullopt; - } - auto state = crypto_auth_hmacsha256_state{}; - auto mac = std::array{}; - auto const ok = crypto_auth_hmacsha256_init(&state, key.data(), key.size()) == 0 && - crypto_auth_hmacsha256_update(&state, reinterpret_cast(message.data()), - message.size()) == 0 && - crypto_auth_hmacsha256_final(&state, mac.data()) == 0; - // The state holds the key's inner and outer pads. - sodium_memzero(&state, sizeof(state)); - if (!ok) - { - sodium_memzero(mac.data(), mac.size()); - return std::nullopt; - } - return mac; -} - -[[nodiscard]] auto as_string_view(std::array const& mac) noexcept -> std::string_view -{ - return {reinterpret_cast(mac.data()), mac.size()}; -} - -// `header.payload.signature` for `payload_json`, whose every value the caller validated so that it needs no escaping. -[[nodiscard]] auto sign_payload(std::span api_secret, std::string_view payload_json) - -> std::optional -{ - if (api_secret.size() < livekit_api_secret_min_bytes) - { - return std::nullopt; - } - auto header = base64_urlsafe_encode(hs256_header_json); - auto payload = base64_urlsafe_encode(payload_json); - if (!header || !payload) - { - return std::nullopt; - } - // Element Call reads the payload with `atob`, which knows only the standard alphabet. The claims hold only ASCII - // letters, digits and `{}":,+/._-`, none of which can put a 62 or 63 in a base64 group, so this never fires; it is - // the guarantee stated where it is relied on. - if (payload->find_first_of("-_") != std::string::npos) - { - return std::nullopt; - } - auto signing_input = std::move(*header); - signing_input += '.'; - signing_input += *payload; - auto const mac = hmac_sha256(api_secret, signing_input); - if (!mac) - { - return std::nullopt; + constexpr auto mac_bytes = std::size_t{crypto_auth_hmacsha256_BYTES}; + constexpr auto livekit_name_bytes = std::size_t{43U}; + // The header every token signed here carries. It is never read back from a token: `verify_hs256_token` returns the + // header it received for the caller to judge, and checks HMAC-SHA256 whatever the header says. + constexpr auto hs256_header_json = std::string_view{R"({"alg":"HS256","typ":"JWT"})"}; + + [[nodiscard]] auto is_ascii_alnum(char const character) noexcept -> bool + { + return (character >= 'a' && character <= 'z') || (character >= 'A' && character <= 'Z') || + (character >= '0' && character <= '9'); + } + + // HMAC-SHA256 of `message` under `key`. The init/update/final form takes a key of any length, as JWT HS256 requires + // (RFC 7518 3.2); `crypto_auth_hmacsha256` alone takes exactly 32 bytes. + [[nodiscard]] auto hmac_sha256(std::span key, std::string_view message) + -> std::optional> + { + if (sodium_init() < 0) + { + return std::nullopt; + } + auto state = crypto_auth_hmacsha256_state{}; + auto mac = std::array{}; + auto const ok = crypto_auth_hmacsha256_init(&state, key.data(), key.size()) == 0 && + crypto_auth_hmacsha256_update(&state, reinterpret_cast(message.data()), + message.size()) == 0 && + crypto_auth_hmacsha256_final(&state, mac.data()) == 0; + // The state holds the key's inner and outer pads. + sodium_memzero(&state, sizeof(state)); + if (!ok) + { + sodium_memzero(mac.data(), mac.size()); + return std::nullopt; + } + return mac; + } + + [[nodiscard]] auto as_string_view(std::array const& mac) noexcept -> std::string_view + { + return {reinterpret_cast(mac.data()), mac.size()}; + } + + // `header.payload.signature` for `payload_json`, whose every value the caller validated so that it needs no + // escaping. + [[nodiscard]] auto sign_payload(std::span api_secret, std::string_view payload_json) + -> std::optional + { + if (api_secret.size() < livekit_api_secret_min_bytes) + { + return std::nullopt; + } + auto header = base64_urlsafe_encode(hs256_header_json); + auto payload = base64_urlsafe_encode(payload_json); + if (!header || !payload) + { + return std::nullopt; + } + // Element Call reads the payload with `atob`, which knows only the standard alphabet. The claims hold only + // ASCII letters, digits and `{}":,+/._-`, none of which can put a 62 or 63 in a base64 group, so this never + // fires; it is the guarantee stated where it is relied on. + if (payload->find_first_of("-_") != std::string::npos) + { + return std::nullopt; + } + auto signing_input = std::move(*header); + signing_input += '.'; + signing_input += *payload; + auto const mac = hmac_sha256(api_secret, signing_input); + if (!mac) + { + return std::nullopt; + } + auto signature = base64_urlsafe_encode(as_string_view(*mac)); + if (!signature) + { + return std::nullopt; + } + signing_input += '.'; + signing_input += *signature; + return signing_input; + } + + [[nodiscard]] auto times_are_valid(std::int64_t const not_before, std::int64_t const expires) noexcept -> bool + { + return not_before >= 0 && expires > not_before; } - auto signature = base64_urlsafe_encode(as_string_view(*mac)); - if (!signature) - { - return std::nullopt; - } - signing_input += '.'; - signing_input += *signature; - return signing_input; -} - -[[nodiscard]] auto times_are_valid(std::int64_t const not_before, std::int64_t const expires) noexcept -> bool -{ - return not_before >= 0 && expires > not_before; -} } // namespace @@ -168,6 +169,28 @@ auto sign_livekit_room_create_token(std::string_view const api_key, std::span const api_secret, + std::string_view const room_name, std::int64_t const not_before, + std::int64_t const expires) -> std::optional +{ + if (!livekit_api_key_is_valid(api_key) || !livekit_name_is_valid(room_name) || + !times_are_valid(not_before, expires)) + { + return std::nullopt; + } + // The key and the room name are of alphabets that need no JSON escaping, checked above. + auto payload = std::string{R"({"exp":)"}; + payload += std::to_string(expires); + payload += R"(,"iss":")"; + payload += api_key; + payload += R"(","nbf":)"; + payload += std::to_string(not_before); + payload += R"(,"video":{"room":")"; + payload += room_name; + payload += R"(","roomAdmin":true}})"; + return sign_payload(api_secret, payload); +} + auto verify_hs256_token(std::string_view const token, std::span const secret) -> std::optional { diff --git a/tests/unit/test_crypto_livekit_token.cpp b/tests/unit/test_crypto_livekit_token.cpp index 21d472f06..60051808f 100644 --- a/tests/unit/test_crypto_livekit_token.cpp +++ b/tests/unit/test_crypto_livekit_token.cpp @@ -1,8 +1,8 @@ // SPDX-FileCopyrightText: 2026 James Chapman // SPDX-License-Identifier: GPL-3.0-or-later -// LiveKit's HS256 tokens (ADR-0828): the two typed signers and the verifier. The signed vectors were computed apart from -// this code with Python's `hmac` and `hashlib`; the verifier's vector is RFC 7515 Appendix A.1. +// LiveKit's HS256 tokens (ADR-0828): the three typed signers and the verifier. The signed vectors were computed apart +// from this code with Python's `hmac` and `hashlib`; the verifier's vector is RFC 7515 Appendix A.1. #include "merovingian/crypto/LiveKitToken.hpp" @@ -12,6 +12,7 @@ #include #include #include +#include #include namespace @@ -50,9 +51,9 @@ constexpr auto rfc7515_key = std::array{ 0x5aU, 0xb3U, 0x28U, 0xe6U, 0xf0U, 0x54U, 0xc9U, 0x28U, 0xa9U, 0x0fU, 0x84U, 0xb2U, 0xd2U, 0x50U, 0x2eU, 0xbfU, 0xd3U, 0xfbU, 0x5aU, 0x92U, 0xd2U, 0x06U, 0x47U, 0xefU, 0x96U, 0x8aU, 0xb4U, 0xc3U, 0x77U, 0x62U, 0x3dU, 0x22U, 0x3dU, 0x2eU, 0x21U, 0x72U, 0x05U, 0x2eU, 0x4fU, 0x08U, 0xc0U, 0xcdU, 0x9aU, 0xf5U, 0x67U, 0xd0U, 0x80U, 0xa3U}; -constexpr auto rfc7515_token = - "eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9p" - "c19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"; +constexpr auto rfc7515_token = "eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9." + "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9p" + "c19yb290Ijp0cnVlfQ.dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"; [[nodiscard]] auto payload_segment(std::string const& token) -> std::string { @@ -122,7 +123,8 @@ SCENARIO("A signed participant token verifies and says nothing beyond its grant" REQUIRE(verified.has_value()); CHECK(verified->header_json == R"({"alg":"HS256","typ":"JWT"})"); CHECK(verified->payload_json == - R"({"exp":1700003600,"iss":"APIkey_1.x-","nbf":1700000000,"sub":")" + std::string{alice_identity} + + R"({"exp":1700003600,"iss":"APIkey_1.x-","nbf":1700000000,"sub":")" + + std::string{alice_identity} + R"(","video":{"canPublish":true,"canPublishData":true,"canSubscribe":true,"room":")" + std::string{slot_room} + R"(","roomJoin":true}})"); CHECK(verified->payload_json.find("roomCreate") == std::string::npos); @@ -144,12 +146,67 @@ SCENARIO("A room-creation token grants roomCreate and nothing else", "[crypto][l auto const token = merovingian::crypto::sign_livekit_room_create_token(api_key, secret, 1'700'000'000, 1'700'000'060); + THEN("it is byte for byte the token computed independently") + { + REQUIRE(token.has_value()); + CHECK(*token == + "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9." + "eyJleHAiOjE3MDAwMDAwNjAsImlzcyI6IkFQSWtleV8xLngtIiwibmJmIjoxNzAwMDAwMDAwLCJ2aWRlbyI6eyJy" + "b29tQ3JlYXRlIjp0cnVlfX0.H8s0R8qoKX-6VA99JYKgYg0WktDfwQ-zfAuzjRi8j6M"); + } + } + } +} + +SCENARIO("A room-administration token names one room and grants roomAdmin and nothing else", "[crypto][livekit][rtc]") +{ + GIVEN("a 32-byte secret, an API key and an MSC4195 room name") + { + auto const secret = counting_secret(); + + WHEN("a room-administration token is signed for one minute") + { + auto const token = merovingian::crypto::sign_livekit_room_admin_token(api_key, secret, slot_room, + 1'700'000'000, 1'700'000'060); + THEN("it is byte for byte the token computed independently") { REQUIRE(token.has_value()); CHECK(*token == "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9." - "eyJleHAiOjE3MDAwMDAwNjAsImlzcyI6IkFQSWtleV8xLngtIiwibmJmIjoxNzAwMDAwMDAwLCJ2aWRlbyI6eyJy" - "b29tQ3JlYXRlIjp0cnVlfX0.H8s0R8qoKX-6VA99JYKgYg0WktDfwQ-zfAuzjRi8j6M"); + "eyJleHAiOjE3MDAwMDAwNjAsImlzcyI6IkFQSWtleV8xLngtIiwibmJmIjoxNzAwMDAwMDAwLCJ2aWRlbyI6" + "eyJyb29tIjoiTzg0MzdXMytqbXpNVmpvSVAzdE53Ym0rWHhIUWsyaUtwT0E3YXF3M3FTYyIsInJvb21BZG1p" + "biI6dHJ1ZX19.ucjJr3_4DS-WSGjVhhyp9FFvSRBVw5sOduvkke9yApo"); + } + + THEN("its payload holds the room, roomAdmin, iss and the times, and no sub") + { + REQUIRE(token.has_value()); + auto const verified = merovingian::crypto::verify_hs256_token(*token, secret); + REQUIRE(verified.has_value()); + CHECK(verified->payload_json == + R"({"exp":1700000060,"iss":"APIkey_1.x-","nbf":1700000000,"video":{"room":")" + + std::string{slot_room} + R"(","roomAdmin":true}})"); + } + } + + WHEN("the room is not an MSC4195 name, or the key, secret or times are refused") + { + auto const short_secret = std::vector(31U, 0x01U); + auto const sign = [&secret](std::string_view const room) { + return merovingian::crypto::sign_livekit_room_admin_token(api_key, secret, room, 0, 60); + }; + + THEN("no token is signed") + { + CHECK_FALSE(sign("")); + CHECK_FALSE(sign("!roomid:example.com")); + CHECK_FALSE(sign(std::string(42U, 'A') + "\"")); + CHECK_FALSE(sign(std::string(44U, 'A'))); + CHECK(sign(slot_room)); + CHECK_FALSE( + merovingian::crypto::sign_livekit_room_admin_token(api_key, short_secret, slot_room, 0, 60)); + CHECK_FALSE(merovingian::crypto::sign_livekit_room_admin_token("bad key", secret, slot_room, 0, 60)); + CHECK_FALSE(merovingian::crypto::sign_livekit_room_admin_token(api_key, secret, slot_room, 60, 60)); } } } @@ -265,8 +322,8 @@ SCENARIO("The verifier refuses a token that is altered, malformed or under anoth CHECK_FALSE(merovingian::crypto::verify_hs256_token(*token + ".", secret)); CHECK_FALSE(merovingian::crypto::verify_hs256_token(*token + "." + signature, secret)); CHECK_FALSE(merovingian::crypto::verify_hs256_token(header + ".." + signature, secret)); - CHECK_FALSE(merovingian::crypto::verify_hs256_token(header + "." + payload + "." + signature + "=", - secret)); + CHECK_FALSE( + merovingian::crypto::verify_hs256_token(header + "." + payload + "." + signature + "=", secret)); CHECK_FALSE(merovingian::crypto::verify_hs256_token(header + "." + payload + "." + signature.substr(1U), secret)); CHECK_FALSE(merovingian::crypto::verify_hs256_token("", secret)); From 8815e25b2d0af3e9c6cac33f115d04504cdf5689 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 12:28:31 +0000 Subject: [PATCH 05/19] Serve MSC4195 LiveKit tokens from a built-in token service Adds server.rtc.livekit.{url,api_url,api_key,api_secret_file,token_lifetime} (exclusive with the external service_url) and serves get_token on the unstable io.element.msc4195 and stable v1 client paths: a token only for a caller this server finds joined, with MSC4195's room name and identity, no create, admin or hidden rights, after CreateRoom at the configured API address under an outbound slot with the lock released (ADR-0829, ADR-0830). A request for another server's SFU is relayed over signed federation when that server has a joined member here; its 403 M_FORBIDDEN and 400 M_INVALID_PARAM are passed on in this server's words, so the outbound call now carries those two errcodes as well as M_INVITE_BLOCKED. A federated request is judged from this server's state and answered subscribe-only (ADR-0831). /versions and the transports list match what is served. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 6 +- config/merovingian.conf.bsd.example | 18 +- config/merovingian.conf.example | 18 +- ...s-type-livekit-with-livekit-service-url.md | 3 + ...-only-to-users-this-server-finds-joined.md | 151 +++ ...figured-address-with-a-token-of-its-own.md | 64 + ...ged-by-main-and-answered-subscribe-only.md | 128 ++ docs/adr/index.md | 3 + docs/log-filtering.md | 1 + docs/matrix-v1.19-client-server-api.md | 3 +- docs/threat-model.md | 44 + docs/todos/capability-gaps.md | 3 +- docs/user-manual.md | 68 +- include/merovingian/config/Config.hpp | 4 + .../config/LiveKitTokenServiceConfig.hpp | 34 + include/merovingian/config/RtcConfig.hpp | 9 +- .../homeserver/HomeserverRuntime.hpp | 4 + .../merovingian/homeserver/LiveKitNames.hpp | 30 + .../homeserver/LiveKitRoomService.hpp | 58 + .../homeserver/LiveKitTokenRequest.hpp | 25 + .../homeserver/LiveKitTokenService.hpp | 60 + .../homeserver/OutboundCallResult.hpp | 5 +- .../merovingian/homeserver/RoomService.hpp | 4 + src/config/Config.cpp | 81 ++ src/config/ConfigParser.cpp | 29 + src/config/ReloadPlan.cpp | 23 + src/config/ReloadPolicy.cpp | 8 + src/homeserver/AGENTS.md | 5 +- src/homeserver/ClientServerRuntime.cpp | 51 +- src/homeserver/LiveKitNames.cpp | 63 + src/homeserver/LiveKitRoomService.cpp | 116 ++ src/homeserver/LiveKitTokenService.cpp | 552 ++++++++ src/homeserver/RoomService.cpp | 47 +- src/homeserver/meson.build | 3 + src/http/RateLimit.cpp | 4 + src/main.cpp | 11 + tests/complement/merovingian.conf.template | 2 + tests/conformance/AGENTS.md | 1 + .../test_livekit_token_conformance.cpp | 332 +++++ .../test_route_query_conformance.cpp | 4 +- tests/integration/test_livekit_token_flow.cpp | 1124 +++++++++++++++++ tests/meson.build | 3 + tests/unit/test_config_rtc.cpp | 232 ++++ tests/unit/test_livekit_names.cpp | 94 ++ 44 files changed, 3482 insertions(+), 46 deletions(-) create mode 100644 docs/adr/0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md create mode 100644 docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md create mode 100644 docs/adr/0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md create mode 100644 include/merovingian/config/LiveKitTokenServiceConfig.hpp create mode 100644 include/merovingian/homeserver/LiveKitNames.hpp create mode 100644 include/merovingian/homeserver/LiveKitRoomService.hpp create mode 100644 include/merovingian/homeserver/LiveKitTokenRequest.hpp create mode 100644 include/merovingian/homeserver/LiveKitTokenService.hpp create mode 100644 src/homeserver/LiveKitNames.cpp create mode 100644 src/homeserver/LiveKitRoomService.cpp create mode 100644 src/homeserver/LiveKitTokenService.cpp create mode 100644 tests/conformance/test_livekit_token_conformance.cpp create mode 100644 tests/integration/test_livekit_token_flow.cpp create mode 100644 tests/unit/test_livekit_names.cpp diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c7975ad3..9ebf96533 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,13 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Features -* None. +* MatrixRTC calls on LiveKit need no `lk-jwt-service`: `POST .../rtc/livekit/get_token` (MSC4195) issues tokens to + joined users, and `server.rtc.livekit.url`, `api_url`, `api_key` and `api_secret_file` turn it on (ADR-0829, ADR-0830). ## Security Fixes -* None. +* LiveKit tokens are HS256, signed only by typed functions that cannot grant room creation, administration or hidden + participants; the API secret is read per token and never logged (ADR-0828). ## Bug fixes diff --git a/config/merovingian.conf.bsd.example b/config/merovingian.conf.bsd.example index c98f366e2..43d0a9f0f 100644 --- a/config/merovingian.conf.bsd.example +++ b/config/merovingian.conf.bsd.example @@ -147,8 +147,22 @@ server.http.ipv6_client_prefix_length=64 # server.turn.shared_secret_file=@SYSCONFDIR@/merovingian/turn-secret # server.turn.ttl_seconds=86400 -# MatrixRTC group calls (optional) -# The HTTPS URL of an lk-jwt-service (Element's LiveKit authorisation service) that you run beside a LiveKit SFU. +# MatrixRTC group calls (optional). Choose one of the two ways below; setting both is refused. +# +# 1. The built-in token service (MSC4195; restart required). This server hands each caller joined to a room a +# LiveKit token for your LiveKit SFU, so you run LiveKit only. Set all four of url, api_url, api_key and +# api_secret_file, or none; a partial set is refused. +# The SFU address clients connect to: wss, a host, no query or fragment, no trailing slash. +# server.rtc.livekit.url=wss://livekit.example.org +# Where this server calls LiveKit's room service: https, or http only to 127.0.0.1 or [::1]. +# server.rtc.livekit.api_url=https://livekit.example.org +# server.rtc.livekit.api_key=APIexamplekey +# An owner-only (0400) file holding the API secret, at least 32 bytes, read for each token and never kept. +# server.rtc.livekit.api_secret_file=@SYSCONFDIR@/merovingian/livekit-secret +# How long a token can be used to join: 60s to 3600s. +# server.rtc.livekit.token_lifetime=3600s +# +# 2. An external lk-jwt-service (Element's LiveKit authorisation service) that you run beside a LiveKit SFU. # This server never contacts it: it only tells authenticated clients, and the /.well-known/matrix/client # document, where it is. Empty means no group-call transport is advertised. Reloadable. # Clients append /sfu/get or /get_token to it, so write it with no trailing slash and no query: a URL ending in / diff --git a/config/merovingian.conf.example b/config/merovingian.conf.example index f8016723d..caa5fbaed 100644 --- a/config/merovingian.conf.example +++ b/config/merovingian.conf.example @@ -120,8 +120,22 @@ server.http.ipv6_client_prefix_length=64 # server.turn.shared_secret_file=/etc/merovingian/turn-secret # server.turn.ttl_seconds=86400 -# MatrixRTC group calls (optional) -# The HTTPS URL of an lk-jwt-service (Element's LiveKit authorisation service) that you run beside a LiveKit SFU. +# MatrixRTC group calls (optional). Choose one of the two ways below; setting both is refused. +# +# 1. The built-in token service (MSC4195; restart required). This server hands each caller joined to a room a +# LiveKit token for your LiveKit SFU, so you run LiveKit only. Set all four of url, api_url, api_key and +# api_secret_file, or none; a partial set is refused. +# The SFU address clients connect to: wss, a host, no query or fragment, no trailing slash. +# server.rtc.livekit.url=wss://livekit.example.org +# Where this server calls LiveKit's room service: https, or http only to 127.0.0.1 or [::1]. +# server.rtc.livekit.api_url=https://livekit.example.org +# server.rtc.livekit.api_key=APIexamplekey +# An owner-only (0400) file holding the API secret, at least 32 bytes, read for each token and never kept. +# server.rtc.livekit.api_secret_file=/etc/merovingian/livekit-secret +# How long a token can be used to join: 60s to 3600s. +# server.rtc.livekit.token_lifetime=3600s +# +# 2. An external lk-jwt-service (Element's LiveKit authorisation service) that you run beside a LiveKit SFU. # This server never contacts it: it only tells authenticated clients, and the /.well-known/matrix/client # document, where it is. Empty means no group-call transport is advertised. Reloadable. # Clients append /sfu/get or /get_token to it, so write it with no trailing slash and no query: a URL ending in / diff --git a/docs/adr/0822-the-rtc-transport-is-advertised-as-type-livekit-with-livekit-service-url.md b/docs/adr/0822-the-rtc-transport-is-advertised-as-type-livekit-with-livekit-service-url.md index dd7a1bfb2..96f915fd7 100644 --- a/docs/adr/0822-the-rtc-transport-is-advertised-as-type-livekit-with-livekit-service-url.md +++ b/docs/adr/0822-the-rtc-transport-is-advertised-as-type-livekit-with-livekit-service-url.md @@ -33,6 +33,9 @@ Element Call understand only that type. A future reader must not "fix" the type to the MSC's stable name `m.livekit` without also adding the token endpoints. +*Superseded in part by [ADR-0829](0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md): +the token endpoints exist for the built-in service. With it configured, the transport is `{"type":"livekit","url":...}`, +and the stable answer also lists `m.livekit`. The external service is still advertised as this record says.* ## Pros and Cons of the Options diff --git a/docs/adr/0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md b/docs/adr/0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md new file mode 100644 index 000000000..682b3a798 --- /dev/null +++ b/docs/adr/0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md @@ -0,0 +1,151 @@ +# The built-in LiveKit token service issues tokens only to users this server finds joined + +* Status: accepted +* Date: 2026-11-17 + +Technical Story: MatrixRTC slice 4. The owner chose the homeserver flow only, the external service kept but mutually +exclusive, users of other servers relayed out and admitted subscribe-only, and delegated delayed leave implemented. + +## Context and Problem Statement + +ADR-0822 lets the operator name an external MatrixRTC authorisation service (Element's `lk-jwt-service`). MSC4195 also +lets the homeserver issue LiveKit tokens itself (`POST .../rtc/livekit/get_token`), so no second service, OpenID +round trip or application service is needed. Issuing them means: + +* holding the LiveKit API secret, the one secret that controls the SFU; +* deciding who may join which LiveKit room; +* calling LiveKit. + +Released Element Call (0.28.2) uses this "homeserver flow" for a transport that has a `url` and no +`livekit_service_url`. It sends `POST /_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token` with +`{url, room_id, slot_id, member_id, server_name}` and connects to the transport's `url` with the `jwt` it gets back. + +## Decision Drivers + +* A token goes only to a caller this server authenticated and finds joined to the room, by its own current state, never + by anything the request claims. +* The SFU never sees a Matrix ID or room ID. +* The secret is never held for the life of the process, logged, or put in a response. +* Nothing a request carries decides where this server connects. + +## Considered Options + +* Keep only the external service (ADR-0822). +* The built-in service, alongside the external one, both allowed at once. +* The built-in service, or the external one, never both. + +## Decision Outcome + +Chosen option: "the built-in service, or the external one, never both". Two ways to authorise calls would leave it +unclear which one a client is sent to, so a configuration with both is refused at start-up. + +### Configuration + +The keys below are all restart-required, read at start-up, and refused, never repaired, by `validate()`: + +| Key | Rule | +|---|---| +| `server.rtc.livekit.url` | The SFU's `wss` URL | +| `server.rtc.livekit.api_url` | `https`, or `http` only to a loopback IP literal | +| `server.rtc.livekit.api_key` | 1 to 128 of `A-Za-z0-9_-.` | +| `server.rtc.livekit.api_secret_file` | An owner-only file; the start-up check is `validate_existing_secret_file_metadata`, as for every secret file | +| `server.rtc.livekit.token_lifetime` | 60 s to 1 h, default 1 h | + +* The four keys `url`, `api_url`, `api_key` and `api_secret_file` go together. +* With `server.rtc.livekit.service_url` they are refused. +* The secret is read for each token with `platform::read_secure_secret_line` into a `core::SecretBuffer`, used to sign, + and wiped before the response. The `crypto/LiveKitToken` signers refuse a secret shorter than 32 bytes (ADR-0828), so + a short one is a 500 and an error log naming no secret. + +### Advertisement + +* `GET .../rtc/transports` lists `{"type":"livekit","url":}`. The stable path also lists + `{"type":"m.livekit","url":...}` after it; MSC4195 names that type, and released clients read only `livekit`. +* `org.matrix.msc4143.rtc_foci` in the well-known document stays for the external service only. The clients that read + it know only the OpenID flow. +* `/versions` gains `org.matrix.msc4195` and `org.matrix.msc4195.stable`. Each is true exactly when the routes are + served. + +### Routes + +* `POST /_matrix/client/v1/rtc/livekit/get_token` and its unstable `io.element.msc4195` path, authenticated. + * A locked account gets the gate's 401. + * A suspended account gets the gate's 403 `M_USER_SUSPENDED`: joining a call is participation. + * Without the built-in service the route answers 404 `M_UNRECOGNIZED`. +* The body is a JSON object with string members `url` (at most 2048 bytes), `room_id`, `slot_id` and `member_id` (each + 1 to 255 bytes, valid for JSON, `room_id` starting `!`), and an optional `server_name`. + * A missing member is 400 `M_MISSING_PARAM`. + * Anything else wrong is 400 `M_INVALID_PARAM`. + * A body that is not an object is 400 `M_BAD_JSON`. +* `server_name` absent or equal to this server's name asks for this server's SFU. + * `url` must then equal `server.rtc.livekit.url` byte for byte, else 400 `M_INVALID_PARAM` (MSC4195). It is never + fetched. + * Another server's name is relayed to that server over federation, as ADR-0831 describes; its `url` is that + server's to judge. + +### Authorisation + +* The caller's `memberships` row for `room_id` must say `join`. + * That row is this server's projection of the room's current `m.room.member` state, written in the same transaction + as the event (ADR-0126). + * An unknown room and a room the caller is not joined to are the same 403 `M_FORBIDDEN`. + * No field of the request is consulted. +* The caller's own token always has `canPublish` and `canPublishData` true. +* Rate limit: 60 a minute per user on each path (built in, `client_rate_limits.per_user.` overrides). The global + bound is the ADR-0079 outbound budget each token's LiveKit call takes. + +### Names + +* The LiveKit room is `base64nopad(SHA-256(canonical JSON [room_id, slot_id]))`. +* The identity is the same over `[user_id, member_id]`, as MSC4195 specifies and its vectors test. +* The one exception is the slot `m.call#ROOM`, which is hashed as `m.call#room`. Released Element Call sends the first + on the unstable path, MSC4195 names the second, and lk-jwt-service folds them so old and new clients meet in one + LiveKit room. No other value is folded. + +### Calling LiveKit + +* Before a publishing token is issued, the room is created with `CreateRoom` (MSC4195), as ADR-0830 describes. +* The call takes an ADR-0079 slot first (none is 429 `M_LIMIT_EXCEEDED` with `retry_after_ms`) and runs under one + 10-second deadline, clamped by `remote_timeout`. +* `runtime.mutex` is released for the call only. +* Any failure (unreachable, timeout, a non-200 answer, an answer over 16 KiB) is 502 `M_UNKNOWN`, and no token is + issued. + +### Answer and logging + +* The answer is `{"jwt": }`. +* The `livekit` logger records `livekit.token.issued`, `livekit.token.refused`, `livekit.create_room_failed` and + `livekit.secret_unavailable`. Each carries `user_id` and `room_id`, and a reason where there is one. It never + records the token, the secret, the slot or the member ID (which carries a device ID). + +### Positive Consequences + +* A deployment needs only LiveKit: no `lk-jwt-service`, no application service registration, no OpenID exchange, and + no second copy of the secret. +* Who may join is decided by the server that holds the room state. + +### Negative Consequences + +* This server now holds the LiveKit API secret, and the threat model records it. +* The OpenID flow (`/sfu/get`) is not served. A client that knows only that flow needs the external service. + +## Pros and Cons of the Options + +### Keep only the external service + +* Good, because the secret stays out of this process. +* Bad, because the external service decides membership by asking the homeserver over OpenID and a well-known lookup. + It runs as an application service to do delegated leave, and its identity for `/sfu/get` is the raw Matrix ID. + +### Both at once + +* Bad, because a client is told about one of two, and the operator cannot tell which. + +## Links + +* Supersedes in part [ADR-0822](0822-the-rtc-transport-is-advertised-as-type-livekit-with-livekit-service-url.md), + which said there is no `/rtc/livekit/*` route; its external service keeps working unchanged. +* Refined by [ADR-0830](0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md) and + [ADR-0831](0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md) +* [ADR-0828](0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md) +* [MSC4195](https://github.com/matrix-org/matrix-spec-proposals/blob/6d49798949e1b31023565d4ff1c7fe10f4cacf83/proposals/4195-matrixrtc-livekit.md) diff --git a/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md new file mode 100644 index 000000000..03e95ce1a --- /dev/null +++ b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md @@ -0,0 +1,64 @@ +# Every call to LiveKit goes to the configured address with a token of its own + +* Status: accepted +* Date: 2026-11-17 + +## Context and Problem Statement + +The built-in token service (ADR-0829) calls LiveKit's room service. Each call is signed with the API secret, so a call +to the wrong address would hand that address a token valid on the SFU. A call is also an outbound request made on a +client's behalf, with what that costs the request pool. This record lists every call and the rules each follows; a new +call is added here. + +## Decision Outcome + +### Where a call goes + +* A call goes only to `server.rtc.livekit.api_url`, never to an address a request names. +* `livekit_create_room_request` parses the URL again with `http::parse_outbound_url` and holds it to the + configuration's rule (`https`, or `http` to a loopback IP literal). It rebuilds the URL from the parsed parts with an + explicit port and appends `/twirp/livekit.RoomService/`. +* `perform_livekit_request` resolves the host with `discovery.upstream().lookup_addresses`, the operator-trusted lookup + the application service client uses (ADR-0515). The connection is pinned to the addresses found. + * The SSRF-filtered lookup is not used: the operator chose the address, and LiveKit commonly runs on the same host or + LAN. +* TLS verification is always on and redirects are refused (`http::OutboundClient`). + +### How a call is made + +* Every call is made from a client request with an ADR-0079 slot held, under one deadline, and with `runtime.mutex` + released around the call only (`src/homeserver/AGENTS.md`). +* At most 16 KiB of answer is read (`livekit_response_max_bytes`). Nothing in an answer is trusted or returned to the + client: only the HTTP status is read. + +### What each call may do + +* Each call carries its own Twirp bearer token. The token is signed by a typed function in `crypto/LiveKitToken` + (ADR-0828), is valid for 60 seconds, and grants only what that call needs. + +| Call | Method | Grant | When | +|---|---|---|---| +| Create the room | `POST /twirp/livekit.RoomService/CreateRoom`, body `{"name", "empty_timeout": 300, "departure_timeout": 20}` | `video.roomCreate` only | Before a publishing token is issued (MSC4195 MUST) | + +No call removes a participant, ends a room, changes permissions or reads metadata. Adding one is a change to this +record and a new typed signer, and a call that acts against a participant (for example `RemoveParticipant`) needs the +owner's decision first. + +### Tests + +* `HomeserverRuntime::test_livekit_perform` stands in for LiveKit. It is handed the finished request, token included, + and returns LiveKit's answer, so tests check the address, the method, the grant and the body without a network. + +### Positive Consequences + +* A leaked call token can create a room for one minute and nothing else. + +### Negative Consequences + +* Each publishing token costs one round trip to LiveKit while a request thread waits. The slot and the deadline bound + it. + +## Links + +* Refines [ADR-0829](0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md) +* [ADR-0079](0079-cap-client-triggered-outbound-proxying.md) diff --git a/docs/adr/0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md b/docs/adr/0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md new file mode 100644 index 000000000..8cf2da363 --- /dev/null +++ b/docs/adr/0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md @@ -0,0 +1,128 @@ +# A federated LiveKit token request is judged by main and answered subscribe-only + +* Status: accepted +* Date: 2026-11-17 + +Technical Story: MatrixRTC slice 4. The owner chose "relay out, subscribe-only in". + +## Context and Problem Statement + +In MSC4195 a client asks its own server for a token for another server's SFU. Its server relays the request to that +server's `POST /_matrix/federation/v1/rtc/livekit/get_token`, adding `user_id`. The receiving server must refuse: + +* when it is not joined to the room (403 `M_FORBIDDEN`); +* when `user_id` is not of the origin (403 `M_FORBIDDEN`); +* when the user is not joined (403 `M_FORBIDDEN`); +* when `url` is not its SFU (400 `M_INVALID_PARAM`). + +The relaying server passes 403 `M_FORBIDDEN` and 400 `M_INVALID_PARAM` back to the client, and turns anything else +into 502 `M_UNKNOWN`. + +On this server, inbound federation is parsed by the federation worker. The worker holds no secret and signs nothing +(ADR-0078). The LiveKit API secret is main's (ADR-0829). + +## Decision Drivers + +* The worker never sees the API secret and never signs a token. +* A token goes only to a user this server's own state shows joined, for an origin main verified. Nothing the worker + says is believed. +* A request from another server does not make this server call anything. +* What this server relays out goes only to a server its state shows in the room, under the client-outbound bounds. + +## Decision Outcome + +### Inbound: `POST /_matrix/federation/{v1,unstable/io.element.msc4195}/rtc/livekit/get_token` + +1. Main verifies the X-Matrix signature in `FederationProxy::handle` and gives the forwarded request one relay permit + (ADR-0595). The permit is `WorkerRelayKind::livekit_token` over the request body. +2. The worker routes the request and relays it to main in a `livekit_token_ingest` frame carrying the body and the + origin. +3. Main admits the frame only when the origin matches the pending request's verified origin + (`IpcChannel::matches_pending_origin`) and the body's digest consumes the permit (`consume_pending_relay`). A worker + cannot change the origin or the body, or replay a frame. +4. Main judges the request with `issue_federation_livekit_token`, holding `runtime.mutex`, by its own state: + * this server is in the room (`room_state_is_current`: the create event is held and a local user is joined); + * `user_id`'s server is the origin; + * the user's current `m.room.member` state is `join`; + * `url` is `server.rtc.livekit.url`, byte for byte. + + The first three are one 403 `M_FORBIDDEN`, "No token can be issued for this user in this room.", so a server learns + nothing about a room it has no member in. The last is 400 `M_INVALID_PARAM`. A body naming a `server_name` other + than this server's is 400 too. +5. The token is signed in main and returned to the worker, which answers it. The worker answers a refused frame + 403 `M_FORBIDDEN`. + +### A user of another server subscribes only + +* Its token has `canPublish` and `canPublishData` false: MSC4195 lets a server restrict publishing for users of other + servers, and this one's SFU carries only its own users' media. +* No `CreateRoom` call is made for it. MSC4195 says the receiving server "creates the room (if needed)". This server + does not, so that a request from another server never makes it call LiveKit. +* Nothing is lost by skipping the call. A subscriber has nothing to receive until a local user publishes, and that + user's own request creates the room. LiveKit's `auto_create` (on by default) covers the order where the subscriber + connects first. + +### Outbound: a client names another server + +When `server_name` is not this server's, `issue_client_livekit_token`: + +1. Requires the caller joined here (the same 403 as for this server's SFU). +2. Requires the named server to have a member joined by this server's roster (`RoomMembers::has_member_of_server`), + else 403 `M_FORBIDDEN` (MSC4195). +3. Takes an ADR-0079 slot (429 without one) and one deadline of 10 seconds, clamped by `remote_timeout`. +4. Sends `{member_id, room_id, slot_id, url, user_id}` over signed federation (`perform_outbound_call`, + `OutboundAnswerTrust::unverified`, at most 8 KiB of answer) to the stable path only, with `runtime.mutex` released + for the call. +5. Relays a 403 `M_FORBIDDEN` and a 400 `M_INVALID_PARAM` with this server's own text, never the other server's + (MSC4195: upstream answers are not shown to clients). Anything else is 502 `M_UNKNOWN`. +6. Passes on only a `jwt` string that is three non-empty base64url segments of at most 4096 bytes. Its claims are the + other server's to vouch for; this server does not read them. + +The `url` is the other server's to judge and is never fetched here. + +### Bounds and logging + +* The inbound route is limited per verified origin by `security.federation.per_origin_request_rate`, as every + federation endpoint but `/send` is. +* It costs one secret read and one signature, with no network call. +* The outbound relay is the client route's own per-user limit (ADR-0829) and the ADR-0079 budget. +* The `livekit` logger records: + * `livekit.federation.issued` (`origin`, `user_id`, `room_id`); + * `livekit.federation.refused` (with `reason`); + * `livekit.relay.issued` (with `server_name`); + * `livekit.relay.refused`; + * `livekit.relay.failed`. + + It never records the token or the member ID. + +### Positive Consequences + +* A federated call works with the secret and the signing in main only, and every judgement is made by the server + holding the room state. + +### Negative Consequences + +* A remote user cannot publish on this server's SFU. A deployment where users of several servers share one SFU + needs each server to run its own. +* No server is known to serve the federation route yet, so the outbound relay has been tested only against this + server. + +## Pros and Cons of the Options + +### Answer the inbound route in main without the worker (`federation_request_should_bypass_worker`) + +* Good, because no frame or permit is needed. +* Bad, because the owner asked for the ADR-0595 relay. Inbound federation is routed by the worker, and main admits + only what a permit binds. + +### Issue remote users publishing tokens and create the room for them + +* Good, because it follows MSC4195's default (SHOULD). +* Bad, because another server could then make this server call LiveKit and put media on its SFU. + +## Links + +* Refines [ADR-0829](0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md) +* [ADR-0595](0595-bind-worker-key-claim-and-query-relays-to-the-verified-request-by-digest.md) +* [ADR-0078](0078-the-federation-worker-never-signs.md) +* [ADR-0079](0079-client-triggered-outbound-proxying-runs-under-a-bounded-in-flight-budget.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index e16796bae..50884d947 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -707,3 +707,6 @@ * [0826 - Delayed events are on by default, with a maximum delay, per-user caps and per-user rate limits](0826-delayed-events-are-on-by-default-with-a-maximum-delay-per-user-caps-and-per-user-rate-limits.md) * [0827 - A state_after delta is measured from an in-memory log of resolved state changes](0827-a-state-after-delta-is-measured-from-an-in-memory-log-of-resolved-state-changes.md) * [0828 - LiveKit tokens are signed and verified only through typed HS256 functions in the crypto boundary](0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md) +* [0829 - The built-in LiveKit token service issues tokens only to users this server finds joined](0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md) +* [0830 - Every call to LiveKit goes to the configured address with a token of its own](0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md) +* [0831 - A federated LiveKit token request is judged by main and answered subscribe-only](0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md) diff --git a/docs/log-filtering.md b/docs/log-filtering.md index 15d4a6345..bc58ce9d9 100644 --- a/docs/log-filtering.md +++ b/docs/log-filtering.md @@ -134,6 +134,7 @@ used as the first argument to `observability::log_diagnostic` and `log_diagnosti | `tls` | TLS context set-up and handshake accept or reject | | `oauth` | OAuth 2.0 client registration, eviction at the cap, and stored metadata that no longer validates | | `delayed_events` | Delayed events: scheduled, restarted, cancelled, sent, failed, a failed outcome write and a failed prune; never event content or a state key. The count of rows skipped at load is a start-up warning from the process entry point, not this module | +| `livekit` | The built-in LiveKit token service: a token issued or refused, to a local user, to another server's user, or relayed from another server; a failed `CreateRoom` call and an unreadable API secret. Each names the user and room (and the server, for federation); never the token, the API secret, the device or member ID, or the slot | Unrecognised module names are accepted and the level is recorded — there is no error. Restart the server to apply. diff --git a/docs/matrix-v1.19-client-server-api.md b/docs/matrix-v1.19-client-server-api.md index 8c4d977a3..15ef16d7f 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -539,7 +539,8 @@ In each case below the spec leaves the choice to the server; the owner decided t - **`POST /users/{userId}/report` (v1.14, ADR-0482).** Needs an access token and is rate-limited. The body is a JSON object whose `reason`, when present, is a string (`400 M_BAD_JSON` otherwise). A local user ID no account holds is `404 M_NOT_FOUND` and stores nothing; a user of another server is accepted without a lookup. It is stored as an audit row `trust_safety.account.accept_report` (reporter, reported user), one per pair, listed by `GET /admin/safety/reports`; a repeat answers `200` without a second row. The reporter need share no room with the reported user. - **Password reset by email (ADR-0481).** `POST /account/password/email/requestToken` (no token) answers `200` with `sid` and `submit_url` for every well-formed request, whether or not an account holds the address, and emails an 8-character code only to an active account's address; it never answers `M_THREEPID_NOT_FOUND` or `M_THREEPID_IN_USE`. A repeat with the same or a lower `send_attempt` returns the same `sid` and sends nothing. With no relay (`server.email.smtp_url`) it is `400 M_THREEPID_MEDIUM_NOT_SUPPORTED`. The client posts `{sid, client_secret, token}` to `submit_url` (`/_matrix/client/unstable/org.merovingian/account/password/email/submitToken`, this server's own path, the Identity Service `submitToken` shape): `{"success":true}`, or `400 M_TOKEN_INCORRECT`, `M_INVALID_PARAM` or `M_SESSION_EXPIRED` (five wrong codes end the session; sessions last 15 minutes). `POST /account/password` with no access token and `auth: {type: "m.login.email.identity", threepid_creds: {sid, client_secret}}` then sets the password of the account that holds the address (`401` with the flows for a missing or unvalidated stage, `400 M_WEAK_PASSWORD` for a weak password and the session is kept for a retry) and, with `logout_devices` (the default), revokes every token of the account. `POST /account/password/msisdn/requestToken` is `400 M_THREEPID_MEDIUM_NOT_SUPPORTED` (no SMS). -- **MatrixRTC transport discovery (MSC4143, not in v1.19; ADR-0822).** `GET /_matrix/client/v1/rtc/transports` answers `{"transports":[{"type":"livekit","livekit_service_url":""}]}` and `GET /_matrix/client/unstable/org.matrix.msc4143/rtc/transports` answers `{"rtc_transports":[...]}`, both needing an access token; with `server.rtc.livekit.service_url` empty they answer `{"transports":[]}` and `{}`. `/versions` always lists `org.matrix.msc4143` and `org.matrix.msc4143.stable`, and the well-known document gains `org.matrix.msc4143.rtc_foci` when a URL is set. There is no `m.livekit` transport and no `/rtc/livekit/*` route. +- **MatrixRTC transport discovery (MSC4143, not in v1.19; ADR-0822).** `GET /_matrix/client/v1/rtc/transports` answers `{"transports":[{"type":"livekit","livekit_service_url":""}]}` and `GET /_matrix/client/unstable/org.matrix.msc4143/rtc/transports` answers `{"rtc_transports":[...]}`, both needing an access token; with `server.rtc.livekit.service_url` empty they answer `{"transports":[]}` and `{}`. `/versions` always lists `org.matrix.msc4143` and `org.matrix.msc4143.stable`, and the well-known document gains `org.matrix.msc4143.rtc_foci` when a URL is set. With the built-in token service on (`server.rtc.livekit.url`, ADR-0829) the transports are instead `livekit` with `url`, and, on the stable route only, `m.livekit` with the same `url`; the well-known document gains no member for it. +- **LiveKit token service (MSC4195, not in v1.19; ADR-0829 to ADR-0831).** `POST /_matrix/client/v1/rtc/livekit/get_token` and `POST /_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token`, access token and the standard account gate, body `{room_id, slot_id, member_id, url, server_name?}` (every member a string; `room_id`, `slot_id`, `member_id` at most 255 bytes, `url` at most 2048; anything else `400 M_BAD_JSON` or `M_INVALID_PARAM`). Answers `{"jwt":...}`. A caller whose current membership is not `join` gets `403 M_FORBIDDEN`, alike for a room that does not exist. For this server (`server_name` absent or this server's name), a `url` that is not `server.rtc.livekit.url` byte for byte is `400 M_INVALID_PARAM`, and the LiveKit room is created before answering: an unreachable or failing LiveKit is `502 M_UNKNOWN`. For another server named in `server_name`, the request is relayed over federation only when that server has a member joined (`403 M_FORBIDDEN` otherwise); its `403 M_FORBIDDEN` and `400 M_INVALID_PARAM` are passed on in this server's words and anything else is `502 M_UNKNOWN`. Without an outbound slot the answer is `429 M_LIMIT_EXCEEDED`; per-user limit 60/60s. With the service off both routes are `404 M_UNRECOGNIZED`. `/versions` lists `org.matrix.msc4195` and `org.matrix.msc4195.stable`, true when the service is on. The federation route `POST /_matrix/federation/v1/rtc/livekit/get_token` (and its `io.element.msc4195` unstable form) issues a subscribe-only token for a joined user of the requesting server. - **Delayed events (MSC4140; in the v1.20 spec text, not in v1.19; ADR-0823 to ADR-0826).** All nine routes need an access token and the standard account gate; `?user_id=` masquerade works as on other routes. Schedule: `PUT /v3/rooms/{roomId}/delayed_event/{eventType}/{txnId}` and `PUT /unstable/org.matrix.msc4140/rooms/{roomId}/delayed_event/{eventType}/{txnId}`; a request to `PUT /v3/rooms/{roomId}/send/{eventType}/{txnId}` or `PUT /v3/rooms/{roomId}/state/{eventType}/{stateKey}` (also the no-state-key and empty-state-key forms) that carries `?org.matrix.msc4140.delay=` is always scheduled, never sent at once, and answers `403 M_FORBIDDEN` when the feature is disabled (the other body-sending routes, `POST .../send` and `PUT .../redact/...`, answer `400 M_INVALID_PARAM` when the parameter is present, and the application-service `?ts=` is ignored on a delayed request); a delay that is not a decimal integer of at least 1, or is repeated, is `400 M_INVALID_PARAM`, and one over `server.delayed_events.max_delay_ms` is `400` (`M_DELAY_TOO_LARGE` on the v3 dedicated path, `ORG.MATRIX.MSC4140_DELAY_TOO_LARGE` on the others); a user at `max_scheduled_per_user` gets `429 M_LIMIT_EXCEEDED`; content over 65,536 bytes is `413 M_TOO_LARGE`. Manage: `POST /v1/delayed_events/{delayId}/{send|cancel|restart}` and `POST /unstable/org.matrix.msc4140/delayed_events/{delayId}/{send|cancel|restart}`, and, under the unstable prefix only, `POST /unstable/org.matrix.msc4140/delayed_events/{delayId}` with `{"action":"send"|"cancel"|"restart"}` (there is no `POST /v1/delayed_events/{delayId}`; any other last segment is `404 M_UNRECOGNIZED`). Look up: `GET /v1/delayed_events/{delayId}` and `GET /unstable/org.matrix.msc4140/delayed_events/{delayId}`. A delay ID that is unknown and one that belongs to another user both answer `404 M_NOT_FOUND` with `Delayed event not found.`; a repeated action on a finalised event answers `200` or `409 M_UNKNOWN`, and one on an event being sent answers `409`. `/versions` lists `org.matrix.msc4140` and `org.matrix.msc4140.stable` (each true when the feature is enabled), and `/capabilities` lists `m.delayed_events` and `org.matrix.msc4140.delayed_events` (`max_delay_ms`, `max_scheduled`; zeros when disabled). The event a delayed event became carries `unsigned.delay_id` for the user who scheduled it. The listing endpoint (MSC4486) is not routed (`404 M_UNRECOGNIZED`); sticky events (MSC4354) are not supported. - **`GET /voip/turnServer` with `server.turn.uris` (ADR-0821)** answers one `uris` entry per configured URI, in the configured order; `server.turn.server` still gives one. - **`GET /voip/turnServer` with `server.turn.shared_secret_file` (ADR-0480)** answers per-user credentials in the coturn REST API format: `username` `:`, `password` the base64 HMAC-SHA1 of it under the secret, `ttl` `server.turn.ttl_seconds`. diff --git a/docs/threat-model.md b/docs/threat-model.md index 045eb40fe..1210b7794 100644 --- a/docs/threat-model.md +++ b/docs/threat-model.md @@ -36,6 +36,8 @@ SSRF-filtered; namespace matching; masquerading) - Identity Service client (outbound `store-invite`/`bind`/`unbind`/`requestToken`) - Push gateway delivery (outbound, client-supplied URL, no operator allowlist) +- The built-in LiveKit token service (1.1.3): the LiveKit API secret, tokens handed to clients, the `CreateRoom` call to + the operator's LiveKit, and the federation `rtc/livekit/get_token` route in both directions (see below) - Email pushers (outbound SMTP to an operator-configured relay; a client-supplied recipient address) - Federation worker IPC channel (local process boundary) - MSC4186 sliding-sync connection state (client-chosen `conn_id`) @@ -3363,3 +3365,45 @@ ever logged; (j) the federation worker: it never reads the table and sends nothi after a crash in the window between the send and its record, or when a `send` request throws after the event was stored (it has no catch, the event stays scheduled and can be sent again later); a wall clock stepped forwards brings deadlines forward by the step; a suspended account's delayed events fail rather than send, so the server does not end a suspended participant's call membership; the feature is on by default. + +### The built-in LiveKit token service (1.1.3, ADR-0828 to ADR-0831) + +New surface: a long-lived secret, `server.rtc.livekit.api_secret_file`, whose holder can mint any token for the +operator's LiveKit, including administrative ones; two client routes that hand out tokens; an outbound call to +LiveKit's room service; and a federation route, served for other servers and called on other servers. Threats and +mitigations: + +(a) The secret leaking. It is a path to an owner-only (`0400`) file, checked at start-up, read into a +`core::SecretBuffer` for each signature and wiped after, never held for the life of the process, never logged and +never in a response. Signing is in `src/crypto/` through typed functions only (ADR-0828): the participant grant cannot +express `roomCreate`, `roomAdmin` or `hidden`, and the one other signer grants `roomCreate` alone. The federation +worker never reads the configuration or the secret. + +(b) A token for someone who should not have one. A token goes only to a caller this server authenticated (access token, +account gate) and finds joined by its own current room state, never by the request: a user not joined, and a room that +does not exist, get the same 403. A federated request is judged by main, for the origin main verified, and needs the +user to be of that origin and joined by this server's state; the three refusals are one 403, so a server learns nothing +about a room it has no member in (ADR-0831). + +(c) More rights than a call needs. A local user's token joins one room and may publish and subscribe; another +server's user's token may only subscribe. Lifetime is 60 to 3600 seconds. The room name and identity are MSC4195's +hashes, so the SFU does not learn Matrix IDs. + +(d) SSRF and outbound abuse. The `url` in a request is only compared, byte for byte, with the configured SFU and never +fetched. `CreateRoom` goes only to `server.rtc.livekit.api_url`, which is `https` or loopback `http`, with a token of +its own lasting 60 seconds, one ADR-0079 outbound slot, one deadline of at most 10 seconds, a 16 KiB answer cap and the +runtime lock released for the call only (ADR-0830). A relay to another server goes only to one this server's roster +shows in the room, signed, under the same slot and deadline, with an 8 KiB answer cap; only a well-formed `jwt` is +passed on, and that server's error text never is. + +(e) Cost and flooding. The client routes are limited to 60 a minute per user and share the client outbound budget. +The federation route is limited per origin by `security.federation.per_origin_request_rate` and costs a secret read and +a signature, with no network call: a request from another server never makes this server call LiveKit. + +(f) The worker forging a request. The inbound route reaches main only through the ADR-0595 relay: a permit over the +body, bound to the request main authenticated, used once, with the origin checked against the pending request's. + +Residual risk: a token stays usable for its lifetime after the user leaves the room, and a participant already +connected stays in the call until LiveKit removes them (this server does not call `RemoveParticipant`); anyone who can +read the secret file can mint any LiveKit token; the relay and the inbound route have been tested only against this +server, never another implementation or a real LiveKit. diff --git a/docs/todos/capability-gaps.md b/docs/todos/capability-gaps.md index ebe247caf..0334db18c 100644 --- a/docs/todos/capability-gaps.md +++ b/docs/todos/capability-gaps.md @@ -48,7 +48,8 @@ When adding a capability, record what is *missing* as explicitly as what works. | Endpoint | Status | Needs | | --- | --- | --- | | `GET /_matrix/client/v1/auth_metadata` and the MSC2965 unstable path | `spec-covered` | The OAuth 2.0 server metadata, served while `server.oauth.enabled` is true (ADR-0773); `404 M_UNRECOGNIZED` while it is off. Registration, the authorisation pages, the token endpoint (code and refresh grants), revocation, the account pages at `/_merovingian/account` (all six account management actions), the `m.oauth` UIA stage, the `legacy_api_enabled=false` switch and the hand-off for OAuth 2.0 aware clients (`m.login.sso` with `oauth_aware_preferred`) are served (ADR-0779 to ADR-0802), and so is the device authorization grant with `server.oauth.device_grant_enabled=true` (ADR-0804 to ADR-0806). An OAuth session still cannot add an email address or mint a login token (no page; `403 M_FORBIDDEN`). Element X's QR-code login needs the MSC4108 rendezvous API, which is not in spec v1.19 and not part of 1.1.0 (owner decision), so it stays unavailable although the device authorization grant is served. Nothing here has yet been tried with Element X or in a real browser; see the open items in `docs/todos/oauth-2-0-api.md`. | -| `GET /_matrix/client/v1/rtc/transports` and the MSC4143 unstable path | `runtime-wired` | MatrixRTC transport discovery (MSC4143, not in the v1.19 spec): advertises the operator's `lk-jwt-service` (`server.rtc.livekit.service_url`) as type `livekit` (ADR-0822). Gap: no built-in token service (`m.livekit`, `/rtc/livekit/*`). | +| `GET /_matrix/client/v1/rtc/transports` and the MSC4143 unstable path | `runtime-wired` | MatrixRTC transport discovery (MSC4143, not in the v1.19 spec): advertises the operator's `lk-jwt-service` (`server.rtc.livekit.service_url`) as type `livekit` (ADR-0822). With the built-in token service on, advertises `livekit` and `m.livekit` with the SFU `url` instead (ADR-0829). | +| `POST /_matrix/client/v1/rtc/livekit/get_token`, the `io.element.msc4195` path, and the federation `rtc/livekit/get_token` | `runtime-wired` | MSC4195, not in the v1.19 spec: the built-in LiveKit token service issues tokens to users this server finds joined, creates the LiveKit room first, relays a request for another server's SFU over federation and answers other servers' joined users with subscribe-only tokens (ADR-0829 to ADR-0831). Gap: no real client, LiveKit SFU or other homeserver has been run against it; the OpenID `/sfu/get` flow is not served. | | Delayed events: `PUT .../delayed_event/{eventType}/{txnId}`, `?org.matrix.msc4140.delay=` on `/send` and `/state`, `POST` and `GET .../delayed_events/{delayId}` (stable, `org.matrix.msc4140` and query forms) | `runtime-wired` | MSC4140, in the v1.20 spec text and not in v1.19: schedule, restart, cancel, send and look up a delayed event, kept in the `delayed_events` table (migration 003) and sent by the `delayed-events` job through the ordinary send path (ADR-0823 to ADR-0826). Not implemented: the listing endpoint (MSC4486, `404 M_UNRECOGNIZED`) and sticky events (MSC4354). No real client (Element X, Element Web, Element Call, lk-jwt-service) has been run against it yet. | | `GET /_matrix/client/v3/voip/turnServer` | `spec-covered` | Static TURN credentials from `server.turn.*` configuration, or per-user time-limited coturn shared-secret credentials when `server.turn.shared_secret_file` is set (`src/homeserver/TurnCredentials.cpp`, ADR-0480). `server.turn.uris` advertises several URIs (ADR-0821). | | Unrouted v1.19 operations | `not-started` | These answer `404 M_UNRECOGNIZED` (most are asserted as `(implementation gap)` scenarios in `tests/conformance/test_client_server_conformance.cpp`): legacy `GET /v3/events`, `GET /v3/events/{eventId}`, `GET /v3/initialSync`; `GET /.well-known/matrix/policy_server` and `GET /.well-known/matrix/support`. `POST /v1/login/get_token` (off unless `security.login_token.enabled`; UIA password every call; single-use in-memory tokens, ADR-0548) and `GET /v3/admin/whois/{userId}` (devices only: the server records no IP, user agent or last-seen time, so `connections` is always empty) are implemented (CS8). The two `/account/password/*/requestToken` routes are routed (email: ADR-0481; msisdn answers `400 M_THREEPID_MEDIUM_NOT_SUPPORTED`). User reporting, redaction, the appservice ping and the appservice network directory have their own rows. | diff --git a/docs/user-manual.md b/docs/user-manual.md index f6ac9c013..d7981e5dc 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -825,17 +825,64 @@ support. #### Voice and video calls — `server.rtc.*` and `server.turn.*` -Merovingian does not carry call media. A call needs a service you run beside it: +Merovingian does not carry call media. A call needs a media service you run beside it: - **1:1 calls** need a TURN server such as coturn. Configure it with `server.turn.*` (above). -- **Group calls (MatrixRTC)** need a LiveKit SFU plus Element's `lk-jwt-service`, the authorisation service that - hands a caller a LiveKit token. `lk-jwt-service` checks who is calling through this server's existing OpenID - endpoints (`/_matrix/client/v3/user/{userId}/openid/request_token` and the federation `openid/userinfo`), so it must - be able to reach this server over HTTPS. Merovingian only tells clients where it is. +- **Group calls (MatrixRTC)** need a LiveKit SFU, and something that hands each caller a LiveKit token. Choose one: + - **The built-in token service** (`server.rtc.livekit.url` and the keys beside it). This server issues the tokens + itself (MSC4195), to users it finds joined to the room. You run LiveKit only. + - **An external `lk-jwt-service`** (`server.rtc.livekit.service_url`). Element's service issues the tokens and + checks who is calling through this server's OpenID endpoints + (`/_matrix/client/v3/user/{userId}/openid/request_token` and the federation `openid/userinfo`), so it must be able + to reach this server over HTTPS. Merovingian only tells clients where it is. + + The two cannot be combined: setting `service_url` together with any built-in key refuses the configuration. + +##### The built-in token service — `server.rtc.livekit.*` + +Set all four of `url`, `api_url`, `api_key` and `api_secret_file`, or none. A partial set refuses the configuration +(ADR-0829). Every key below requires a restart. + +| Key | Default | When to change | +|---|---|---| +| `server.rtc.livekit.url` | (empty) | The SFU's WebSocket address that clients connect to, for example `wss://livekit.example.org`. It must be an absolute `wss` URL with a host, no user name or password, no query or `#fragment`, a path that does not end in `/`, and at most 2048 bytes. Clients are told this address, and a token request naming any other `url` for this server is refused. | +| `server.rtc.livekit.api_url` | (empty) | Where this server calls LiveKit's room service, for example `https://livekit.example.org`. `https`, or `http` only to `127.0.0.1` or `[::1]` when LiveKit runs on the same host; otherwise the same rules as `url`. Only this address is ever called (ADR-0830). | +| `server.rtc.livekit.api_key` | (empty) | The LiveKit API key, 1 to 128 ASCII letters, digits, `_`, `-` and `.`. | +| `server.rtc.livekit.api_secret_file` | (empty) | Path to an owner-read-only file (mode `0400`, as every secret file) holding the matching API secret, at least 32 bytes, on its first line. The file is read each time a token is signed and never kept in memory; the server refuses to start if its owner or mode is wrong. | +| `server.rtc.livekit.token_lifetime` | `3600s` | How long an issued token can be used to join, `60s` to `3600s` (or `1m` to `60m`). A participant already in the call stays in it after the token expires. | + +What the service does: + +- A client asks `POST /_matrix/client/v1/rtc/livekit/get_token` (or the unstable + `/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token`) for a room. The caller must be joined to the + room by this server's own current state; anyone else gets 403 `M_FORBIDDEN`, the same answer whether or not the room + exists. +- Before answering, the server asks LiveKit to create the call's room (`CreateRoom`, at most 10 seconds, with a token + of its own allowed only to create rooms). If LiveKit cannot be reached, the client gets 502 and no token. +- The token lets its holder join that one LiveKit room, publish and subscribe. It never grants room creation, + administration or hidden participation. The LiveKit room name and participant identity are hashes (MSC4195), so the + SFU does not learn Matrix user, device or room IDs. +- A user of another server joined to the room can get a token from this server for its SFU, through that user's + server over federation (`POST /_matrix/federation/v1/rtc/livekit/get_token`). That token may subscribe but not + publish, and no LiveKit call is made for it (ADR-0831). +- When a local user asks for a token for another server's SFU, this server relays the request to that server over + federation, but only to a server it finds in the room. +- Token requests are rate limited per user (60 a minute by default; override with `client_rate_limits.per_user.` for each path) + and share the outbound-request budget of other client-triggered calls. Federated requests are limited per server by + `security.federation.per_origin_request_rate`. +- The `livekit` logger records each issued or refused token with the user and room, never the token, the secret or + the device. + +With the service on, `GET /_matrix/client/v1/rtc/transports` lists `{"type":"livekit","url":""}` +and, on the stable path only, the same with type `m.livekit`. `/_matrix/client/versions` adds `org.matrix.msc4195` +and `org.matrix.msc4195.stable`. The `.well-known` `org.matrix.msc4143.rtc_foci` member is not served by the built-in +service, because the older clients that read it expect `lk-jwt-service`'s OpenID flow. + +##### An external `lk-jwt-service` — `server.rtc.livekit.service_url` | Key | Default | When to change | |---|---|---| -| `server.rtc.livekit.service_url` | (empty) | The HTTPS URL of your `lk-jwt-service`, for example `https://livekit-jwt.example.org/lk-jwt-service`. Empty means no group-call transport is advertised. Clients build `/sfu/get` and `/get_token` by appending to it, so give the address without a trailing `/` and without a query: `https://host`, `https://host:8443` and `https://host/jwt` are accepted, `https://host/` and `https://host/jwt?x=1` are refused. It must be an absolute `https` URL with a host, no user name or password, no `#fragment`, no whitespace and at most 2048 bytes; anything else refuses the configuration. The server never contacts this URL. | +| `server.rtc.livekit.service_url` | (empty) | The HTTPS URL of your `lk-jwt-service`, for example `https://livekit-jwt.example.org/lk-jwt-service`. Empty means no external service is advertised. Clients build `/sfu/get` and `/get_token` by appending to it, so give the address without a trailing `/` and without a query: `https://host`, `https://host:8443` and `https://host/jwt` are accepted, `https://host/` and `https://host/jwt?x=1` are refused. It must be an absolute `https` URL with a host, no user name or password, no `#fragment`, no whitespace and at most 2048 bytes; anything else refuses the configuration. The server never contacts this URL. This key is reloadable. | With the key set, an authenticated client reading `GET /_matrix/client/v1/rtc/transports` (or the older `GET /_matrix/client/unstable/org.matrix.msc4143/rtc/transports`) learns a transport of type `livekit` with that @@ -856,11 +903,6 @@ start-up; anything outside the range, or not a boolean or unsigned integer, refu | `server.delayed_events.max_scheduled_per_user` | `100` | `1` to `1000` | Scheduled events one user may hold. | | `server.delayed_events.max_finalised_per_user` | `100` | `1` to `1000` | Finalised events kept per user (and for at most 7 days). | -Not implemented yet: - -- **A built-in token service.** There is no `/_matrix/client/v1/rtc/livekit/*` endpoint and the transport type - `m.livekit` is not advertised; you must run `lk-jwt-service` yourself. - ##### Delayed events and call membership A call member who loses connection should stop being listed. With delayed events (MSC4140) the client schedules the @@ -1929,6 +1971,7 @@ Default route-aware policies applied when no override is configured: | URL previews (`/_matrix/client/v1/media/preview_url`, `/_matrix/media/v3/preview_url`) | 30/60s per user | | Asynchronous upload reservations (`/_matrix/media/v1/create`) | 30/60s per user | | Delayed-event scheduling paths (`.../rooms/{roomId}/delayed_event/{eventType}/{txnId}`, both prefixes) | 60/60s per user | +| LiveKit token requests (`/_matrix/client/v1/rtc/livekit/get_token`, `/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token`) | 60/60s per user | | Generic client APIs | 600/60s per IP fallback | Example overrides: @@ -2017,7 +2060,8 @@ take effect. | `presence.*` | Restart required | | `database.pool_size` | Restart required | | `server.turn.*` | Reloadable | -| `server.rtc.*` | Reloadable | +| `server.rtc.livekit.service_url` | Reloadable | +| `server.rtc.livekit.*` (the built-in token service) | Restart required | | `server.delayed_events.*` | Restart required | | `security.trust_safety.*` | Reloadable | | `security.access_token_lifetime_ms` / `security.refresh_token_lifetime_ms` / `security.audit_log_retention_days` | Reloadable | diff --git a/include/merovingian/config/Config.hpp b/include/merovingian/config/Config.hpp index 8e64a21fb..2cfb4a608 100644 --- a/include/merovingian/config/Config.hpp +++ b/include/merovingian/config/Config.hpp @@ -37,6 +37,10 @@ inline constexpr std::uint64_t min_delayed_event_delay_ms = 1'000U; inline constexpr std::uint64_t max_delayed_event_delay_ms = 2'678'400'000U; // 31 days inline constexpr std::uint32_t max_delayed_events_per_user = 1'000U; +// server.rtc.livekit.token_lifetime range (ADR-0829). +inline constexpr std::uint32_t min_livekit_token_lifetime_seconds = 60U; +inline constexpr std::uint32_t max_livekit_token_lifetime_seconds = 3'600U; + class Config final { public: diff --git a/include/merovingian/config/LiveKitTokenServiceConfig.hpp b/include/merovingian/config/LiveKitTokenServiceConfig.hpp new file mode 100644 index 000000000..69714f6c2 --- /dev/null +++ b/include/merovingian/config/LiveKitTokenServiceConfig.hpp @@ -0,0 +1,34 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::config +{ + +// The built-in MatrixRTC token service (MSC4195; ADR-0829): this server issues LiveKit tokens for the operator's +// LiveKit SFU itself. Off unless all of `url`, `api_url`, `api_key` and `api_secret_file` are set; validate() refuses +// a partial set, and refuses it together with `server.rtc.livekit.service_url`, so a validated config with `url` set +// has the service on. Every key is read at start-up, so a change needs a restart. +struct LiveKitTokenServiceConfig final +{ + // `server.rtc.livekit.url`: the SFU's WebSocket URL, sent to clients as the transport's `url` and the only `url` a + // token request may name. An absolute `wss` URL with a host, no userinfo, query or fragment, a path that does not + // end in `/`, at most 2048 bytes. + std::string url{}; + // `server.rtc.livekit.api_url`: where this server calls LiveKit's room service. `https`, or `http` to a loopback IP + // literal (`127.0.0.1`, `[::1]`) when LiveKit runs on the same host; otherwise the same rules as `url`. + std::string api_url{}; + // `server.rtc.livekit.api_key`: the API key, written as each token's `iss`. 1 to 128 ASCII letters, digits, `_`, + // `-` and `.`. + std::string api_key{}; + // `server.rtc.livekit.api_secret_file`: an owner-only (0400) file holding the API secret, at least 32 bytes on its + // first line. Read for each use into a `core::SecretBuffer` and never kept. + std::string api_secret_file{}; + // `server.rtc.livekit.token_lifetime`: how long an issued token can be used to join. 60 to 3600 seconds. + std::uint32_t token_lifetime_seconds{3600U}; +}; + +} // namespace merovingian::config diff --git a/include/merovingian/config/RtcConfig.hpp b/include/merovingian/config/RtcConfig.hpp index 20acf4567..eb2816b85 100644 --- a/include/merovingian/config/RtcConfig.hpp +++ b/include/merovingian/config/RtcConfig.hpp @@ -2,13 +2,16 @@ // SPDX-License-Identifier: GPL-3.0-or-later #pragma once +#include "merovingian/config/LiveKitTokenServiceConfig.hpp" + #include namespace merovingian::config { -// MatrixRTC transport discovery (MSC4143, MSC4195; ADR-0822). This server never fetches or proxies anything here: it -// only tells authenticated clients where the operator's own MatrixRTC authorisation service is. +// MatrixRTC (MSC4143, MSC4195). Either this server tells clients where the operator's own external authorisation +// service is (`livekit_service_url`, ADR-0822), or it issues LiveKit tokens itself (`token_service`, ADR-0829); never +// both. struct RtcConfig final { // The HTTPS URL of an external MatrixRTC authorisation service (Element's `lk-jwt-service`) that the operator @@ -18,6 +21,8 @@ struct RtcConfig final // control character and at most 2048 bytes, or whose path ends in `/`. A URL with no path (`https://host`, // `https://host:8443`) is accepted. std::string livekit_service_url{}; + // The built-in token service. + LiveKitTokenServiceConfig token_service{}; }; } // namespace merovingian::config diff --git a/include/merovingian/homeserver/HomeserverRuntime.hpp b/include/merovingian/homeserver/HomeserverRuntime.hpp index 1e20bb612..3c2159705 100644 --- a/include/merovingian/homeserver/HomeserverRuntime.hpp +++ b/include/merovingian/homeserver/HomeserverRuntime.hpp @@ -343,6 +343,10 @@ struct HomeserverRuntime final // play a compromised worker, and count the calls that reach one, without a worker process. An // unverified call never reaches it. Always empty in production. std::function test_worker_outbound_route{}; + // Test-only (ADR-0830): stands in for the operator's LiveKit server. When set, every call to LiveKit's room service + // (perform_livekit_request) hands it the finished request, token and body included, in place of resolving the + // API host and connecting, and uses what it returns as LiveKit's answer. Always empty in production. + std::function test_livekit_perform{}; // Owned implementation of the runtime signing provider: the production // multi-key provider in main, or the refusing provider in the federation // worker (RuntimeStartOptions::signing_disabled, ADR-0078). diff --git a/include/merovingian/homeserver/LiveKitNames.hpp b/include/merovingian/homeserver/LiveKitNames.hpp new file mode 100644 index 000000000..ec0e6b4d2 --- /dev/null +++ b/include/merovingian/homeserver/LiveKitNames.hpp @@ -0,0 +1,30 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include +#include + +namespace merovingian::homeserver +{ + +// The LiveKit names MSC4195 derives, so the SFU never sees a Matrix ID or room ID (ADR-0829). Each is the unpadded +// standard base64 of the SHA-256 of the canonical JSON array of two strings: 43 characters of `A-Za-z0-9+/`. + +// The slot ID released Element Call versions send on the unstable path, and the one MSC4195 names. lk-jwt-service +// hashes the first as the second, so a call between old and new clients lands in one LiveKit room; this server does +// the same, for that one value only. +inline constexpr auto legacy_call_slot_id = std::string_view{"m.call#ROOM"}; +inline constexpr auto call_slot_id = std::string_view{"m.call#room"}; + +// The LiveKit room for `slot_id` in `room_id`: hash of `[room_id, slot_id]`, with `legacy_call_slot_id` read as +// `call_slot_id`. nullopt when either string is not valid for JSON or hashing fails. +[[nodiscard]] auto livekit_room_name(std::string_view room_id, std::string_view slot_id) -> std::optional; + +// The LiveKit participant identity of member `member_id` of `user_id`: hash of `[user_id, member_id]`. nullopt as +// above. +[[nodiscard]] auto livekit_participant_identity(std::string_view user_id, std::string_view member_id) + -> std::optional; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/LiveKitRoomService.hpp b/include/merovingian/homeserver/LiveKitRoomService.hpp new file mode 100644 index 000000000..34f73038d --- /dev/null +++ b/include/merovingian/homeserver/LiveKitRoomService.hpp @@ -0,0 +1,58 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/http/OutboundRequest.hpp" +#include "merovingian/http/OutboundResult.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::federation +{ +class CachedServerDiscovery; +} // namespace merovingian::federation + +namespace merovingian::http +{ +class OutboundClient; +} // namespace merovingian::http + +namespace merovingian::homeserver +{ + +// Calls to LiveKit's room service (Twirp, JSON) at `server.rtc.livekit.api_url` (ADR-0830). Each call carries a token +// of its own with only the grant that call needs, minted for one minute; the address is the operator's, never one a +// request names. + +// The largest answer read from LiveKit. A `Room` or `ParticipantInfo` is far smaller. +inline constexpr auto livekit_response_max_bytes = std::size_t{16U * 1024U}; +// How long the service token of one call is valid. +inline constexpr auto livekit_service_token_seconds = std::int64_t{60}; +// What `CreateRoom` asks for, as lk-jwt-service does: a room with nobody in it closes after 300 s, and one everybody +// left after 20 s. +inline constexpr auto livekit_room_empty_timeout_seconds = std::uint32_t{300U}; +inline constexpr auto livekit_room_departure_timeout_seconds = std::uint32_t{20U}; + +// The `CreateRoom` request for `room_name` (an MSC4195 room name), signed with a `roomCreate`-only token. nullopt +// when `api_url` is not an `https` URL, or an `http` URL to a loopback IP literal, or the token cannot be signed. +// `pinned_addresses` and the timeouts are left for `perform_livekit_request`. +[[nodiscard]] auto livekit_create_room_request(std::string_view api_url, std::string_view api_key, + std::span api_secret, std::string_view room_name, + std::int64_t now_seconds) -> std::optional; + +// Stands in for LiveKit in tests: it is handed the finished request in place of resolving and connecting. +using LiveKitTestPerform = std::function; + +// Sends `request` with `timeout_seconds` for the whole exchange. The host is resolved with the operator-trusted lookup +// (`discovery.upstream()`, no private-range filter: the operator chose the address, and LiveKit often runs beside +// this server) and the connection is pinned to it. Never call with `runtime.mutex` held. +[[nodiscard]] auto perform_livekit_request(http::OutboundRequest request, http::OutboundClient& client, + federation::CachedServerDiscovery& discovery, std::uint32_t timeout_seconds, + LiveKitTestPerform const& test_perform) -> http::OutboundResult; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/LiveKitTokenRequest.hpp b/include/merovingian/homeserver/LiveKitTokenRequest.hpp new file mode 100644 index 000000000..af6a45292 --- /dev/null +++ b/include/merovingian/homeserver/LiveKitTokenRequest.hpp @@ -0,0 +1,25 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::homeserver +{ + +// An MSC4195 `get_token` request body, read and bounded (ADR-0829). Nothing in it is trusted: the caller judges every +// field against this server's own configuration and room state. +struct LiveKitTokenRequest final +{ + // The SFU the client means; only ever compared with `server.rtc.livekit.url` (or passed on unread when relayed). + std::string url{}; + std::string room_id{}; + std::string slot_id{}; + std::string member_id{}; + // Client form only: the server whose SFU the token is for. Empty when the body did not name one. + std::string server_name{}; + // Federation form only: the user the requesting server asks for. + std::string user_id{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/LiveKitTokenService.hpp b/include/merovingian/homeserver/LiveKitTokenService.hpp new file mode 100644 index 000000000..396654558 --- /dev/null +++ b/include/merovingian/homeserver/LiveKitTokenService.hpp @@ -0,0 +1,60 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/LiveKitTokenRequest.hpp" +#include "merovingian/homeserver/OperationResult.hpp" +#include "merovingian/homeserver/RuntimeMutex.hpp" + +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +struct ClientServerRuntime; +struct HomeserverRuntime; +struct LocalHttpRequest; + +// The built-in MatrixRTC token service (MSC4195; ADR-0829). + +// Bounds on the identifiers a request names. A slot or member ID is the `slot_id` or `member.id` of an +// `m.rtc.member` state event, whose state key is itself at most 255 bytes. +inline constexpr auto max_livekit_slot_id_bytes = std::size_t{255U}; +inline constexpr auto max_livekit_member_id_bytes = std::size_t{255U}; +inline constexpr auto max_livekit_room_id_bytes = std::size_t{255U}; +inline constexpr auto max_livekit_url_bytes = std::size_t{2048U}; +// A user ID is at most 255 bytes (the identifier grammar). +inline constexpr auto max_livekit_user_id_bytes = std::size_t{255U}; + +// The federation route this server asks another server's token service on (ADR-0831), and the largest answer read: +// a `jwt` is at most `crypto::hs256_token_max_bytes`. +inline constexpr auto federation_livekit_token_path = std::string_view{"/_matrix/federation/v1/rtc/livekit/get_token"}; +inline constexpr auto livekit_relay_response_max_bytes = std::uint64_t{8U * 1024U}; + +// What a client body reads as, or the 400 to answer. Not std::expected, which this project's toolchain does not +// build. +using LiveKitTokenRequestResult = std::variant; + +// The client body `{url, room_id, slot_id, member_id[, server_name]}`. A failure is the 400 to answer: +// `M_BAD_JSON` for a body that is not a JSON object, `M_MISSING_PARAM` for a missing member, `M_INVALID_PARAM` for one +// of the wrong type or out of bounds. +[[nodiscard]] auto parse_client_livekit_token_request(std::string_view body) -> LiveKitTokenRequestResult; + +// `POST /_matrix/client/{v1,unstable/io.element.msc4195}/rtc/livekit/get_token` for `user_id`, whom the dispatcher +// authenticated. A `server_name` naming another server is relayed to it over federation (ADR-0831). `guard` holds +// `runtime.mutex`; it is released only around the call to LiveKit or to the other server. The answer's `value` is the +// response body on success; on failure `status`, `errcode` and `reason` say what to answer. +[[nodiscard]] auto issue_client_livekit_token(ClientServerRuntime& rt, LocalHttpRequest const& req, + std::string const& user_id, RuntimeLock& guard) -> OperationResult; + +// `POST /_matrix/federation/{v1,unstable/io.element.msc4195}/rtc/livekit/get_token` from `origin`, the server main +// verified the X-Matrix signature of, with the request's `body` (ADR-0831). The caller holds `runtime.mutex`; nothing +// here blocks. A token for a user of another server can subscribe only. +[[nodiscard]] auto issue_federation_livekit_token(HomeserverRuntime& runtime, std::string_view origin, + std::string_view body) -> OperationResult; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/OutboundCallResult.hpp b/include/merovingian/homeserver/OutboundCallResult.hpp index 9d9d461e0..ce9fbd8a2 100644 --- a/include/merovingian/homeserver/OutboundCallResult.hpp +++ b/include/merovingian/homeserver/OutboundCallResult.hpp @@ -17,8 +17,9 @@ struct OutboundCallResult final bool ok{false}; std::string body{}; std::uint16_t remote_status{0U}; - // The `errcode` of a non-2xx answer's Matrix error body when it is `M_INVITE_BLOCKED` (SS7), else empty. A remote - // body is untrusted, so only this one fixed value is carried, never the remote's text. + // The `errcode` of a non-2xx answer's Matrix error body when it is `M_INVITE_BLOCKED` (SS7), `M_FORBIDDEN` or + // `M_INVALID_PARAM` (a LiveKit token relay, ADR-0831), else empty. A remote body is untrusted, so only these fixed + // values are carried, never the remote's text. std::string remote_errcode{}; // ADR-0761: true when the destination itself gave no answer: discovery found no server, or the request got no // connection, no verified TLS session or no response in time. False on success, on any HTTP answer (including a diff --git a/include/merovingian/homeserver/RoomService.hpp b/include/merovingian/homeserver/RoomService.hpp index a730d1c51..696768100 100644 --- a/include/merovingian/homeserver/RoomService.hpp +++ b/include/merovingian/homeserver/RoomService.hpp @@ -373,6 +373,10 @@ auto claim_membership_event_template(canonicaljson::Object& event, std::string_v // `send_event_as_resolved_user` itself asks. [[nodiscard]] auto room_send_refusal(HomeserverRuntime& runtime, std::string const& user_id, std::string_view room_id) -> std::optional; +// `user_id`'s membership in `room_id`'s current state (`join`, `leave`, ...), read from its current +// `m.room.member` event by the state index, or empty when the state holds none. For a user of any server. +[[nodiscard]] auto current_state_membership(database::PersistentStore const& store, std::string_view room_id, + std::string_view user_id) -> std::string; // 403 "event authorization or signing failed": what an event the room's auth rules refuse is answered, shared with // the delayed events' schedule-time power check. [[nodiscard]] auto event_authorization_refusal() -> OperationResult; diff --git a/src/config/Config.cpp b/src/config/Config.cpp index d6a10eb63..b941aa5f9 100644 --- a/src/config/Config.cpp +++ b/src/config/Config.cpp @@ -23,10 +23,12 @@ #include "merovingian/config/SizeLimitParseResult.hpp" #include "merovingian/config/SpecialUseIpRanges.hpp" #include "merovingian/core/Error.hpp" +#include "merovingian/crypto/LiveKitToken.hpp" #include "merovingian/email/MailboxAddress.hpp" #include "merovingian/email/SmtpEndpoint.hpp" #include "merovingian/http/KeepAlive.hpp" #include "merovingian/http/RateLimit.hpp" +#include "merovingian/net/LoopbackLiteral.hpp" #include "merovingian/oauth/HandOffAllowlist.hpp" #include "merovingian/oauth/OAuthBaseUrl.hpp" #include "merovingian/oauth/ParsedUri.hpp" @@ -78,6 +80,35 @@ namespace } } + // Which LiveKit address a URL names: the SFU clients connect to, or the room service this server calls. + enum class livekit_url_kind : std::uint8_t + { + sfu, + api, + }; + + // A LiveKit URL as server.rtc.livekit.url or api_url must be (ADR-0829): read with oauth::ParsedUri (printable + // ASCII, no userinfo, no fragment, at most 2048 bytes), with a host, no query and a path that does not end in `/`. + // The SFU URL is `wss`. The API URL is `https`, or `http` only to a loopback IP literal + // (net::is_loopback_ip_literal, shared with the appservice and SMTP checks), so a cleartext request signed under + // the API secret never leaves the host. + [[nodiscard]] auto livekit_url_is_valid(std::string const& url, livekit_url_kind const kind) -> bool + { + auto const uri = oauth::ParsedUri::read(url); + auto const* parsed = std::get_if(&uri); + if (parsed == nullptr || !parsed->has_authority() || parsed->host().empty() || parsed->has_query() || + parsed->path().ends_with('/')) + { + return false; + } + if (kind == livekit_url_kind::sfu) + { + return parsed->scheme() == "wss"; + } + return parsed->scheme() == "https" || + (parsed->scheme() == "http" && net::is_loopback_ip_literal(parsed->host())); + } + } // namespace Config::Config(ServerConfig server, ListenersConfig listeners, DatabaseConfig database, SecurityConfig security, @@ -1350,6 +1381,56 @@ auto validate(Config const& config) -> std::vector } } + // The built-in MatrixRTC token service (ADR-0829). Its four keys go together, and with the external service URL as + // well it would be unclear which one clients are sent to, so both are refused. Nothing is repaired. + auto const& token_service = config.server().rtc.token_service; + auto const token_service_any_set = !token_service.url.empty() || !token_service.api_url.empty() || + !token_service.api_key.empty() || !token_service.api_secret_file.empty(); + if (token_service_any_set) + { + if (!config.server().rtc.livekit_service_url.empty()) + { + findings.push_back({"server.rtc.livekit.service_url", + "set either service_url or the built-in token service (server.rtc.livekit.url, " + "api_url, api_key and api_secret_file), not both"}); + } + auto const require = [&findings](std::string const& value, std::string_view key) { + if (value.empty()) + { + findings.push_back({std::string{key}, "the built-in token service needs server.rtc.livekit.url, " + "api_url, api_key and api_secret_file together"}); + } + }; + require(token_service.url, "server.rtc.livekit.url"); + require(token_service.api_url, "server.rtc.livekit.api_url"); + require(token_service.api_key, "server.rtc.livekit.api_key"); + require(token_service.api_secret_file, "server.rtc.livekit.api_secret_file"); + if (!token_service.url.empty() && !livekit_url_is_valid(token_service.url, livekit_url_kind::sfu)) + { + findings.push_back({"server.rtc.livekit.url", + "must be a wss URL with a host, no userinfo, query or fragment, a path that does not " + "end in /, no whitespace and at most 2048 bytes"}); + } + if (!token_service.api_url.empty() && !livekit_url_is_valid(token_service.api_url, livekit_url_kind::api)) + { + findings.push_back( + {"server.rtc.livekit.api_url", + "must be an https URL, or an http URL to a loopback IP literal, with no userinfo, query " + "or fragment, a path that does not end in /, no whitespace and at most 2048 bytes"}); + } + if (!token_service.api_key.empty() && !crypto::livekit_api_key_is_valid(token_service.api_key)) + { + findings.push_back({"server.rtc.livekit.api_key", "must be 1 to 128 ASCII letters, digits, _, - and ."}); + } + } + if (token_service.token_lifetime_seconds < min_livekit_token_lifetime_seconds || + token_service.token_lifetime_seconds > max_livekit_token_lifetime_seconds) + { + findings.push_back({"server.rtc.livekit.token_lifetime", + "must be between " + std::to_string(min_livekit_token_lifetime_seconds) + "s and " + + std::to_string(max_livekit_token_lifetime_seconds) + "s"}); + } + // The built-in OAuth 2.0 API (ADR-0812, ADR-0816). Every OAuth address is derived from public_baseurl, so with the // API on it must be a base URL the OAuth reader accepts (ADR-0773). The other server.oauth.* keys mean nothing // with the API off, and are refused rather than silently ignored. diff --git a/src/config/ConfigParser.cpp b/src/config/ConfigParser.cpp index d23e64a07..7c0580bc4 100644 --- a/src/config/ConfigParser.cpp +++ b/src/config/ConfigParser.cpp @@ -993,6 +993,35 @@ namespace { server.rtc.livekit_service_url = std::string{value}; } + // The built-in MatrixRTC token service (ADR-0829). validate() judges every value and the combination. + else if (key == "server.rtc.livekit.url") + { + server.rtc.token_service.url = std::string{value}; + } + else if (key == "server.rtc.livekit.api_url") + { + server.rtc.token_service.api_url = std::string{value}; + } + else if (key == "server.rtc.livekit.api_key") + { + server.rtc.token_service.api_key = std::string{value}; + } + else if (key == "server.rtc.livekit.api_secret_file") + { + server.rtc.token_service.api_secret_file = std::string{value}; + } + else if (key == "server.rtc.livekit.token_lifetime") + { + auto const lifetime = parse_duration_seconds(value); + if (!lifetime.valid) + { + add_parse_finding(findings, std::string{key}, "expected a duration such as 600s or 60m"); + } + else + { + server.rtc.token_service.token_lifetime_seconds = lifetime.seconds; + } + } // Delayed events (ADR-0826). validate() judges the ranges. else if (key == "server.delayed_events.enabled") { diff --git a/src/config/ReloadPlan.cpp b/src/config/ReloadPlan.cpp index 9ebcad7cd..28480c643 100644 --- a/src/config/ReloadPlan.cpp +++ b/src/config/ReloadPlan.cpp @@ -586,6 +586,29 @@ auto build_reload_plan(Config const& current, Config const& next) -> ReloadPlan { add_change(plan, "server.rtc.livekit.service_url"); } + // The built-in token service: every field is diffed, and every change is restart_required (see ReloadPolicy.cpp). + auto const& current_token_service = current.server().rtc.token_service; + auto const& next_token_service = next.server().rtc.token_service; + if (current_token_service.url != next_token_service.url) + { + add_change(plan, "server.rtc.livekit.url"); + } + if (current_token_service.api_url != next_token_service.api_url) + { + add_change(plan, "server.rtc.livekit.api_url"); + } + if (current_token_service.api_key != next_token_service.api_key) + { + add_change(plan, "server.rtc.livekit.api_key"); + } + if (current_token_service.api_secret_file != next_token_service.api_secret_file) + { + add_change(plan, "server.rtc.livekit.api_secret_file"); + } + if (current_token_service.token_lifetime_seconds != next_token_service.token_lifetime_seconds) + { + add_change(plan, "server.rtc.livekit.token_lifetime"); + } // Delayed events: every field is diffed, and every change is restart_required (see ReloadPolicy.cpp). if (current.server().delayed_events.enabled != next.server().delayed_events.enabled) diff --git a/src/config/ReloadPolicy.cpp b/src/config/ReloadPolicy.cpp index 6e159cac1..c5e6ce595 100644 --- a/src/config/ReloadPolicy.cpp +++ b/src/config/ReloadPolicy.cpp @@ -24,6 +24,14 @@ auto reload_policy_for_key(std::string_view key) noexcept -> ReloadPolicy return ReloadPolicy::restart_required; } + // The built-in MatrixRTC token service (ADR-0829) is read once at start-up: the start-up check of the secret file's + // owner and mode, the advertised transport and the webhook all depend on it. Only the external service URL + // (ADR-0822) stays reloadable. + if (starts_with(key, "server.rtc.livekit.") && key != "server.rtc.livekit.service_url") + { + return ReloadPolicy::restart_required; + } + // ADR-0236: a weaker password policy is logged at CRITICAL when the server // starts. Taking it only on restart keeps that warning from being skipped. if (starts_with(key, "security.password_policy.")) diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index eb70aa7c7..42d03e0e5 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -74,7 +74,10 @@ This is the largest and most complex module — read this file carefully before | `PresenceService.cpp` | Presence (CS API "Presence", SS API `m.presence`): `read_presence` (GET), `apply_sync_presence` (the `/sync` `set_presence` parameter), `build_sync_presence_events` (`presence.events`), `accept_inbound_presence` (the EDU sink's presence case) and `record_presence`, the one place a presence row is stored. `expire_idle_presence` (the idle sweep, ADR-0492). `presence.enabled=false` turns every entry point into a no-op. Sending the EDU stays in `ClientServerRuntime.cpp` (`broadcast_presence_edu`), beside the other outbound EDUs | | `PushRetry.cpp` | `attempt_push_delivery` (every push attempt: circuit breaker, rejected pushkeys, scheduling retries) and `PushRetryJob`, the one thread that sends retries (R14, ADR-0206); a run is bounded by a time budget, takes retries one recipient at a time in turn and sends with a shorter timeout (ADR-0410), and a slow answer counts against the gateway's circuit (ADR-0409) | | `PasswordReset.cpp` | Password reset by email (ADR-0481): `make_password_reset_token` (8 characters, 40 bits), `normalize_password_reset_token`, `send_password_reset_email` (a background task parked in `orphan_futures_`, at most 8 in flight, no lock held while it sends). The endpoints are in `ClientServerRuntime.cpp` before the auth gate; `reset_local_user_password` is in `AuthService.cpp` | -| `ClientServerRuntime.cpp` (MatrixRTC) | `GET /_matrix/client/v1/rtc/transports` and `GET /_matrix/client/unstable/org.matrix.msc4143/rtc/transports` advertise `server.rtc.livekit.service_url` as `{"type":"livekit","livekit_service_url":...}` (`livekit_transport_json`): `transports` and `[]` when none on the stable path, `rtc_transports` and `{}` on the unstable one; both flags `org.matrix.msc4143` and `org.matrix.msc4143.stable` are always in `/versions`, and the well-known document gains `org.matrix.msc4143.rtc_foci` only with a URL (ADR-0822). The type is never `m.livekit` and there is no `/rtc/livekit/*` route. `voip/turnServer` returns `server.turn.server` or, when that is empty, each `server.turn.uris` entry in order (ADR-0821) | +| `ClientServerRuntime.cpp` (MatrixRTC) | `GET /_matrix/client/v1/rtc/transports` and `GET /_matrix/client/unstable/org.matrix.msc4143/rtc/transports` advertise `server.rtc.livekit.service_url` as `{"type":"livekit","livekit_service_url":...}` (`livekit_transport_json`): `transports` and `[]` when none on the stable path, `rtc_transports` and `{}` on the unstable one; both flags `org.matrix.msc4143` and `org.matrix.msc4143.stable` are always in `/versions`, and the well-known document gains `org.matrix.msc4143.rtc_foci` only with a URL (ADR-0822). With the built-in token service instead (`server.rtc.livekit.url`, ADR-0829) they list `{"type":"livekit","url":...}` (`livekit_sfu_transport_json`), the stable path `m.livekit` after it, and `org.matrix.msc4195` and `.stable` are true; `rtc_foci` stays for the external service only. `voip/turnServer` returns `server.turn.server` or, when that is empty, each `server.turn.uris` entry in order (ADR-0821) | +| `LiveKitTokenService.cpp` | `POST /_matrix/client/{v1,unstable/io.element.msc4195}/rtc/livekit/get_token` (`issue_client_livekit_token`, ADR-0829): reads the body strictly, compares `url` with `server.rtc.livekit.url` byte for byte, requires the caller's `memberships` row to say `join` (an unknown room is the same 403), reads the API secret per request, signs through `crypto/LiveKitToken` only, and creates the LiveKit room first under an ADR-0079 slot, one deadline and `RuntimeLockRelease{guard}`. Logs under `livekit` with `user_id` and `room_id` only: never the token, the secret, the slot or the member ID | +| `LiveKitRoomService.cpp` | Every call to LiveKit's room service (ADR-0830): `livekit_create_room_request` builds the Twirp request to `server.rtc.livekit.api_url` only, with its own 60-second `roomCreate`-only token; `perform_livekit_request` resolves with the operator-trusted lookup, pins, and reads at most 16 KiB. `HomeserverRuntime::test_livekit_perform` replaces the network in tests. A new call is a row in ADR-0830 and a typed signer | +| `LiveKitNames.cpp` | `livekit_room_name` and `livekit_participant_identity`: MSC4195's `base64nopad(SHA-256(canonical JSON [a, b]))`, with the legacy slot `m.call#ROOM` hashed as `m.call#room` (ADR-0829). Never send a Matrix ID or room ID to LiveKit any other way | | `TurnCredentials.cpp` | `make_turn_credentials`: the coturn REST API username and password for `GET /voip/turnServer` (ADR-0480) | | `EmailPush.cpp` | Kind `"email"` pushers (ADR-0219, ADR-0220): `owned_email_pusher_address` (the pushkey must be the account's own email 3PID), `remove_email_pushers_for_address`, and `EmailPushJob`, the one thread that sends due digests through `send_due_email_notifications`. It re-reads the pusher, the 3PID, the account and the badge count under `runtime.mutex` (one hold, one `PushBadgeBudget`: rows and glob steps bounded together, ADR-0722), then sends with the mutex released | | `RuntimeSigningKeyStore.cpp` | Production `SigningKeyStore` over the persisted server signing-key rows | diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index e248d2ce6..a7ec9ef28 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -98,6 +98,7 @@ #include "merovingian/homeserver/InvitePermission.hpp" #include "merovingian/homeserver/KeyServerCache.hpp" #include "merovingian/homeserver/LegacyAuthPolicy.hpp" +#include "merovingian/homeserver/LiveKitTokenService.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/LocalHttpResponse.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" @@ -871,6 +872,18 @@ namespace }; } + // The MatrixRTC transport entry for this server's own SFU (MSC4195; ADR-0829): `type` and `url`, nothing else. + [[nodiscard]] auto livekit_sfu_transport_json(std::string const& type, std::string const& sfu_url) + -> canonicaljson::Value + { + return canonicaljson::Value{ + canonicaljson::Object{ + canonicaljson::make_member("type", canonicaljson::Value{type}), + canonicaljson::make_member("url", canonicaljson::Value{sfu_url}), + } + }; + } + [[nodiscard]] auto json_serialize(canonicaljson::Value const& value) -> std::string { auto const result = canonicaljson::serialize_canonical(value); @@ -4188,6 +4201,8 @@ namespace "/_matrix/client/v3/voip/turnServer", "/_matrix/client/v1/rtc/transports", "/_matrix/client/unstable/org.matrix.msc4143/rtc/transports", + "/_matrix/client/v1/rtc/livekit/get_token", + "/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token", "/_matrix/client/v3/room_keys/version", "/_matrix/client/v3/room_keys/keys", "/_matrix/client/v3/devices", @@ -4293,6 +4308,8 @@ namespace {"/_matrix/client/v3/voip/turnServer", "GET" }, {"/_matrix/client/v1/rtc/transports", "GET" }, {"/_matrix/client/unstable/org.matrix.msc4143/rtc/transports", "GET" }, + {"/_matrix/client/v1/rtc/livekit/get_token", "POST" }, + {"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token", "POST" }, {"/_matrix/client/v3/room_keys/version", "GET, POST" }, {"/_matrix/client/v3/room_keys/keys", "DELETE, GET, PUT"}, {"/_matrix/client/v3/devices", "GET" }, @@ -15855,6 +15872,11 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp json_member("org.matrix.msc4186", json_bool(true)), json_member("org.matrix.msc4143", json_bool(true)), json_member("org.matrix.msc4143.stable", json_bool(true)), + // MSC4195 (ADR-0829): the token routes are served only with the built-in service. + json_member("org.matrix.msc4195", + json_bool(!rt.homeserver.config.server().rtc.token_service.url.empty())), + json_member("org.matrix.msc4195.stable", + json_bool(!rt.homeserver.config.server().rtc.token_service.url.empty())), // MSC4140 (ADR-0823): both flags say whether scheduling is on. json_member("org.matrix.msc4140", json_bool(rt.limits.delayed_events_enabled)), json_member("org.matrix.msc4140.stable", json_bool(rt.limits.delayed_events_enabled)), @@ -20156,18 +20178,30 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } // GET /_matrix/client/v1/rtc/transports and its unstable MSC4143 path: where the operator's MatrixRTC - // authorisation service is (ADR-0822). The two differ in the property name and in what they answer when no - // service is configured, as the reference server's do. + // authorisation service is (ADR-0822), or the SFU this server issues tokens for itself (ADR-0829). The two differ + // in the property name and in what they answer when nothing is configured, as the reference server's do. if (req.method == "GET" && (request_path == "/_matrix/client/v1/rtc/transports" || request_path == "/_matrix/client/unstable/org.matrix.msc4143/rtc/transports")) { auto const& service_url = rt.homeserver.config.server().rtc.livekit_service_url; + auto const& sfu_url = rt.homeserver.config.server().rtc.token_service.url; auto const stable = request_path == "/_matrix/client/v1/rtc/transports"; auto transports = canonicaljson::Array{}; if (!service_url.empty()) { transports.push_back(livekit_transport_json(service_url)); } + else if (!sfu_url.empty()) + { + // A `url` and no `livekit_service_url`: released Element Call then asks this server's get_token route. + // MSC4195's stable type `m.livekit` is listed beside it on the stable path only; released clients read + // only `livekit`. + transports.push_back(livekit_sfu_transport_json("livekit", sfu_url)); + if (stable) + { + transports.push_back(livekit_sfu_transport_json("m.livekit", sfu_url)); + } + } if (!stable && transports.empty()) { return dispatch_resp(req, rt, 200U, "{}"); @@ -20178,6 +20212,19 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp }))); } + // POST /_matrix/client/{v1,unstable/io.element.msc4195}/rtc/livekit/get_token: a LiveKit token for this server's + // SFU (MSC4195; ADR-0829). LiveKitTokenService.cpp judges the request; this only answers. + if (req.method == "POST" && (request_path == "/_matrix/client/v1/rtc/livekit/get_token" || + request_path == "/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token")) + { + auto answer = issue_client_livekit_token(rt, req, *user, guard); + if (!answer.ok) + { + return dispatch_err(req, rt, answer.status, answer.errcode, answer.reason, answer.retry_after_ms); + } + return dispatch_resp(req, rt, 200U, std::move(answer.value)); + } + // Delayed events (MSC4140, ADR-0823): S1 and S2 schedule, M1 to M3 manage and G1 and G2 look up. The listing // `GET .../delayed_events` is MSC4486 and no route (`normalized_target` leaves it unmatched). Placed before the // room routes, whose `/send/` and `/state/` markers must never be offered S1's path. A method a path does not diff --git a/src/homeserver/LiveKitNames.cpp b/src/homeserver/LiveKitNames.cpp new file mode 100644 index 000000000..da95f18ce --- /dev/null +++ b/src/homeserver/LiveKitNames.cpp @@ -0,0 +1,63 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/LiveKitNames.hpp" + +#include "merovingian/canonicaljson/CanonicalJsonError.hpp" +#include "merovingian/canonicaljson/Serializer.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/crypto/Encoding.hpp" +#include "merovingian/crypto/Sha256.hpp" + +#include + +namespace merovingian::homeserver +{ +namespace +{ + + [[nodiscard]] auto hash_pair(std::string_view first, std::string_view second) -> std::optional + { + if (!canonicaljson::string_is_valid_for_json(first) || !canonicaljson::string_is_valid_for_json(second)) + { + return std::nullopt; + } + auto const pair = canonicaljson::Value{ + canonicaljson::Array{canonicaljson::Value{std::string{first}}, canonicaljson::Value{std::string{second}}} + }; + auto const serialized = canonicaljson::serialize_canonical_strict(pair); + if (serialized.error != canonicaljson::CanonicalJsonError::none) + { + return std::nullopt; + } + auto const digest = crypto::sha256(serialized.output); + if (!digest) + { + return std::nullopt; + } + auto encoded = crypto::base64_original_encode(*digest); + if (!encoded) + { + return std::nullopt; + } + // 32 bytes encode to 44 characters, the last of them one `=`; MSC4195 drops the padding. + while (!encoded->empty() && encoded->back() == '=') + { + encoded->pop_back(); + } + return encoded; + } + +} // namespace + +auto livekit_room_name(std::string_view const room_id, std::string_view const slot_id) -> std::optional +{ + return hash_pair(room_id, slot_id == legacy_call_slot_id ? call_slot_id : slot_id); +} + +auto livekit_participant_identity(std::string_view const user_id, std::string_view const member_id) + -> std::optional +{ + return hash_pair(user_id, member_id); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/LiveKitRoomService.cpp b/src/homeserver/LiveKitRoomService.cpp new file mode 100644 index 000000000..389cb61e2 --- /dev/null +++ b/src/homeserver/LiveKitRoomService.cpp @@ -0,0 +1,116 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/LiveKitRoomService.hpp" + +#include "merovingian/crypto/LiveKitToken.hpp" +#include "merovingian/federation/CachedServerDiscovery.hpp" +#include "merovingian/federation/ServerDiscoveryNetwork.hpp" +#include "merovingian/http/OutboundClient.hpp" +#include "merovingian/http/OutboundError.hpp" +#include "merovingian/http/OutboundHeader.hpp" +#include "merovingian/http/ParsedOutboundUrl.hpp" +#include "merovingian/net/LoopbackLiteral.hpp" + +#include +#include +#include + +namespace merovingian::homeserver +{ +namespace +{ + + // `api_url` parsed and held to the rule validate() applies (ADR-0829), again here so a value that reached this code + // any other way still cannot send a signed request in cleartext off the host. + [[nodiscard]] auto parsed_api_url(std::string_view const api_url) -> std::optional + { + auto parsed = http::parse_outbound_url(api_url, true); + if (!parsed.has_value() || !parsed->query.empty() || + (parsed->scheme != "https" && !(parsed->scheme == "http" && net::is_loopback_ip_literal(parsed->host)))) + { + return std::nullopt; + } + return parsed; + } + + // `://:`, rebuilt from the parsed parts with the port always written. + [[nodiscard]] auto twirp_url(http::ParsedOutboundUrl const& base, std::string_view const method) -> std::string + { + auto path = std::string_view{base.path}; + if (!path.empty() && path.back() == '/') + { + path.remove_suffix(1U); + } + return base.scheme + "://" + (base.ipv6_literal ? "[" + base.host + "]" : base.host) + ":" + + std::to_string(base.port) + std::string{path} + "/twirp/livekit.RoomService/" + std::string{method}; + } + + [[nodiscard]] auto failed(http::OutboundError const error, std::string detail) -> http::OutboundResult + { + auto result = http::OutboundResult{}; + result.ok = false; + result.error = error; + result.error_detail = std::move(detail); + return result; + } + +} // namespace + +auto livekit_create_room_request(std::string_view const api_url, std::string_view const api_key, + std::span const api_secret, std::string_view const room_name, + std::int64_t const now_seconds) -> std::optional +{ + auto const base = parsed_api_url(api_url); + if (!base.has_value() || !crypto::livekit_name_is_valid(room_name)) + { + return std::nullopt; + } + auto token = crypto::sign_livekit_room_create_token(api_key, api_secret, now_seconds, + now_seconds + livekit_service_token_seconds); + if (!token.has_value()) + { + return std::nullopt; + } + auto request = http::OutboundRequest{}; + request.method = "POST"; + request.url = twirp_url(*base, "CreateRoom"); + request.headers.push_back(http::OutboundHeader{"Content-Type", "application/json"}); + request.headers.push_back(http::OutboundHeader{"Authorization", "Bearer " + std::move(*token)}); + // The room name is 43 base64 characters (checked above), so it needs no JSON escaping. + request.body = R"({"name":")" + std::string{room_name} + R"(","empty_timeout":)" + + std::to_string(livekit_room_empty_timeout_seconds) + R"(,"departure_timeout":)" + + std::to_string(livekit_room_departure_timeout_seconds) + "}"; + request.allow_cleartext_http = base->scheme == "http"; + request.max_response_body_bytes = livekit_response_max_bytes; + return request; +} + +auto perform_livekit_request(http::OutboundRequest request, http::OutboundClient& client, + federation::CachedServerDiscovery& discovery, std::uint32_t const timeout_seconds, + LiveKitTestPerform const& test_perform) -> http::OutboundResult +{ + if (timeout_seconds == 0U) + { + return failed(http::OutboundError::timeout, "deadline exceeded"); + } + request.total_timeout_seconds = timeout_seconds; + request.connect_timeout_seconds = std::min(timeout_seconds, std::uint32_t{10U}); + if (test_perform) + { + return test_perform(request); + } + auto const parsed = http::parse_outbound_url(request.url, request.allow_cleartext_http); + if (!parsed.has_value()) + { + return failed(http::OutboundError::invalid_url, "invalid LiveKit API URL"); + } + auto const resolved = discovery.upstream().lookup_addresses(parsed->host, parsed->port); + if (!resolved.ok || resolved.addresses.empty()) + { + return failed(http::OutboundError::unresolved_host, "failed to resolve the LiveKit API host"); + } + request.pinned_addresses = resolved.addresses; + return client.perform(request); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/LiveKitTokenService.cpp b/src/homeserver/LiveKitTokenService.cpp new file mode 100644 index 000000000..c8499bc48 --- /dev/null +++ b/src/homeserver/LiveKitTokenService.cpp @@ -0,0 +1,552 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/LiveKitTokenService.hpp" + +#include "merovingian/auth/Identity.hpp" +#include "merovingian/canonicaljson/CanonicalJsonError.hpp" +#include "merovingian/canonicaljson/ParseError.hpp" +#include "merovingian/canonicaljson/Parser.hpp" +#include "merovingian/canonicaljson/Serializer.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/config/LiveKitTokenServiceConfig.hpp" +#include "merovingian/core/SecretBuffer.hpp" +#include "merovingian/crypto/LiveKitParticipantGrant.hpp" +#include "merovingian/crypto/LiveKitToken.hpp" +#include "merovingian/database/PersistentMembership.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/federation/OutboundTransactionSupport.hpp" +#include "merovingian/homeserver/BoundedOutboundLimits.hpp" +#include "merovingian/homeserver/ClientOutboundProxy.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LiveKitNames.hpp" +#include "merovingian/homeserver/LiveKitRoomService.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpRouter.hpp" +#include "merovingian/homeserver/OutboundAnswerTrust.hpp" +#include "merovingian/homeserver/OutboundCallResult.hpp" +#include "merovingian/homeserver/OutboundDeadline.hpp" +#include "merovingian/homeserver/RoomResidency.hpp" +#include "merovingian/homeserver/RoomService.hpp" +#include "merovingian/homeserver/RuntimeLockRelease.hpp" +#include "merovingian/http/OutboundError.hpp" +#include "merovingian/http/OutboundResult.hpp" +#include "merovingian/observability/LogEventSeverity.hpp" +#include "merovingian/observability/SingleLog.hpp" +#include "merovingian/observability/StructuredLogField.hpp" +#include "merovingian/platform/FileMetadataSupport.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ +namespace +{ + + constexpr auto log_module = std::string_view{"livekit"}; + // The API secret's file is read up to this size, first line only (`platform::read_secure_secret_line`). + constexpr auto max_livekit_secret_file_bytes = std::size_t{4096U}; + // The budget for the one call to LiveKit a token costs, before the operator's `remote_timeout` clamps it. + constexpr auto livekit_call_deadline_seconds = std::uint32_t{10U}; + + [[nodiscard]] auto refusal(std::uint16_t const status, std::string errcode, std::string reason) -> OperationResult + { + auto result = OperationResult{}; + result.ok = false; + result.status = status; + result.errcode = std::move(errcode); + result.reason = std::move(reason); + return result; + } + + [[nodiscard]] auto member_of(canonicaljson::Object const& object, std::string_view const key) + -> canonicaljson::Value const* + { + for (auto const& member : object) + { + if (member.key == key && member.value != nullptr) + { + return member.value.get(); + } + } + return nullptr; + } + + // A required string member of at most `max_bytes` bytes, at least one, valid for JSON, copied into `out`. A missing + // member is `M_MISSING_PARAM`, anything else wrong `M_INVALID_PARAM`; neither echoes the value. + [[nodiscard]] auto read_required_string(canonicaljson::Object const& object, std::string_view const key, + std::size_t const max_bytes, std::string& out) + -> std::optional + { + auto const* value = member_of(object, key); + if (value == nullptr) + { + return refusal(400U, "M_MISSING_PARAM", std::string{key} + " is required"); + } + auto const* text = std::get_if(&value->storage()); + if (text == nullptr || text->empty() || text->size() > max_bytes || + !canonicaljson::string_is_valid_for_json(*text)) + { + return refusal(400U, "M_INVALID_PARAM", std::string{key} + " is not valid"); + } + out = *text; + return std::nullopt; + } + + // The required members. `room_id` is held to the shape of a room ID; it is only ever looked up exactly. + [[nodiscard]] auto read_required_members(canonicaljson::Object const& object, LiveKitTokenRequest& request) + -> std::optional + { + if (auto refused = read_required_string(object, "url", max_livekit_url_bytes, request.url)) + { + return refused; + } + if (auto refused = read_required_string(object, "room_id", max_livekit_room_id_bytes, request.room_id)) + { + return refused; + } + if (!request.room_id.starts_with('!')) + { + return refusal(400U, "M_INVALID_PARAM", "room_id is not valid"); + } + if (auto refused = read_required_string(object, "slot_id", max_livekit_slot_id_bytes, request.slot_id)) + { + return refused; + } + return read_required_string(object, "member_id", max_livekit_member_id_bytes, request.member_id); + } + + [[nodiscard]] auto now_seconds() -> std::int64_t + { + return std::chrono::duration_cast(std::chrono::system_clock::now().time_since_epoch()) + .count(); + } + + auto log_refusal(std::string_view const event, std::string_view const user_id, std::string_view const room_id, + std::string_view const reason, + observability::LogEventSeverity const severity = observability::LogEventSeverity::info) -> void + { + // Never the token, the secret, the slot or the member ID (which carries a device ID). + observability::log_diagnostic(log_module, event, + { + {"user_id", std::string{user_id}, false}, + {"room_id", std::string{room_id}, false}, + {"reason", std::string{reason}, false}, + }, + severity); + } + +} // namespace + +auto parse_client_livekit_token_request(std::string_view const body) -> LiveKitTokenRequestResult +{ + auto const parsed = canonicaljson::parse_json(body); + auto const* object = std::get_if(&parsed.value.storage()); + if (parsed.error != canonicaljson::ParseError::none || object == nullptr) + { + return refusal(400U, "M_BAD_JSON", "the body must be a JSON object"); + } + auto request = LiveKitTokenRequest{}; + if (auto refused = read_required_members(*object, request)) + { + return std::move(*refused); + } + if (auto const* server_name = member_of(*object, "server_name"); server_name != nullptr) + { + auto const* text = std::get_if(&server_name->storage()); + if (text == nullptr || !auth::server_name_is_valid(*text)) + { + return refusal(400U, "M_INVALID_PARAM", "server_name is not valid"); + } + request.server_name = *text; + } + return request; +} + +namespace +{ + + [[nodiscard]] auto jwt_answer(std::string token) -> OperationResult + { + auto result = OperationResult{}; + result.ok = true; + result.status = 200U; + result.value = + canonicaljson::serialize_canonical(canonicaljson::Value{canonicaljson::Object{canonicaljson::make_member( + "jwt", canonicaljson::Value{std::move(token)})}}) + .output; + return result; + } + + // A participant token for `identity` in `room_name`, signed with the API secret read for this one token. When the + // caller publishes, also the `CreateRoom` request, signed with the same read of the secret. nullopt (and an error + // log naming no secret) when the file cannot be read, the secret is too short, or the API URL is unusable. + struct SignedToken final + { + std::string token; + std::optional create_room; + }; + + [[nodiscard]] auto sign_for(config::LiveKitTokenServiceConfig const& service, std::string const& identity, + std::string const& room_name, bool const can_publish, std::string_view const user_id, + std::string_view const room_id) -> std::optional + { + // The secret is read for this token into locked memory that wipes itself, and is gone before the response. + auto const secret = platform::read_secure_secret_line(service.api_secret_file, max_livekit_secret_file_bytes); + auto const now = now_seconds(); + auto signed_token = std::optional{}; + if (secret.has_value()) + { + auto token = crypto::sign_livekit_participant_token( + service.api_key, secret->bytes(), + crypto::LiveKitParticipantGrant{.identity = identity, + .room = room_name, + .can_publish = can_publish, + .not_before = now, + .expires = + now + static_cast(service.token_lifetime_seconds)}); + auto create_room = can_publish ? livekit_create_room_request(service.api_url, service.api_key, + secret->bytes(), room_name, now) + : std::nullopt; + if (token.has_value() && (!can_publish || create_room.has_value())) + { + signed_token = SignedToken{std::move(*token), std::move(create_room)}; + } + } + if (!signed_token.has_value()) + { + log_refusal("livekit.secret_unavailable", user_id, room_id, + "the API secret file is unreadable, too short, or the API URL is unusable", + observability::LogEventSeverity::error); + } + return signed_token; + } + + [[nodiscard]] auto client_outbound_refusal(ClientServerRuntime& rt) -> OperationResult + { + auto limited = refusal(429U, "M_LIMIT_EXCEEDED", "too many concurrent outbound requests, retry shortly"); + limited.retry_after_ms = rt.homeserver.client_outbound_proxy_policy.retry_after_ms; + return limited; + } + + // A `jwt` another server returned: what LiveKit accepts and nothing more, three non-empty base64url segments of + // at most `hs256_token_max_bytes` in all. Its contents are the other server's to vouch for; this server neither + // reads nor trusts them, and passes only this string on. + [[nodiscard]] auto relayed_jwt_is_well_formed(std::string_view const jwt) -> bool + { + if (jwt.empty() || jwt.size() > crypto::hs256_token_max_bytes) + { + return false; + } + auto segments = 1U; + auto segment_length = std::size_t{0U}; + for (auto const c : jwt) + { + if (c == '.') + { + if (segment_length == 0U) + { + return false; + } + ++segments; + segment_length = 0U; + continue; + } + auto const is_base64url = + (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '-' || c == '_'; + if (!is_base64url) + { + return false; + } + ++segment_length; + } + return segments == 3U && segment_length != 0U; + } + + // MSC4195: a client asks for a token for another server's SFU (`server_name` is not ours). The caller is joined + // here (checked before), and the named server must have a member joined by this server's state; then the request + // goes to that server over signed federation, under an ADR-0079 slot and one deadline, with runtime.mutex released + // for the call only (ADR-0831). Its 403 `M_FORBIDDEN` and 400 `M_INVALID_PARAM` are relayed, with this server's own + // text; anything else is 502 `M_UNKNOWN`. Only a well-formed `jwt` string is taken from the answer. + [[nodiscard]] auto relay_client_livekit_token(ClientServerRuntime& rt, LocalHttpRequest const& req, + std::string const& user_id, LiveKitTokenRequest const& request, + RuntimeLock& guard) -> OperationResult + { + auto const* room = find_local_room(rt.homeserver.database, request.room_id); + if (room == nullptr || !room->members.has_member_of_server(request.server_name)) + { + log_refusal("livekit.relay.refused", user_id, request.room_id, "server not in room"); + return refusal(403U, "M_FORBIDDEN", "That server is not in this room."); + } + if (rt.homeserver.outbound_client == nullptr || rt.homeserver.cached_discovery == nullptr) + { + return refusal(502U, "M_UNKNOWN", "this server cannot make outbound requests"); + } + auto const slot = + admit_client_outbound_proxy(rt.homeserver, rate_limit_client_key(req, rt.homeserver.config.server())); + if (!slot.has_value()) + { + return client_outbound_refusal(rt); + } + auto const deadline = effective_client_outbound_deadline(rt.homeserver, livekit_call_deadline_seconds); + wire_federation_callbacks(rt.homeserver); + auto const signing_key = ensure_runtime_server_signing_key(rt.homeserver); + if (!signing_key.has_value()) + { + return refusal(500U, "M_UNKNOWN", "this server cannot sign federation requests"); + } + // The MSC4195 federation body: the client's, with `server_name` dropped and the requesting user added. + auto members = canonicaljson::Object{}; + members.push_back(canonicaljson::make_member("member_id", canonicaljson::Value{request.member_id})); + members.push_back(canonicaljson::make_member("room_id", canonicaljson::Value{request.room_id})); + members.push_back(canonicaljson::make_member("slot_id", canonicaljson::Value{request.slot_id})); + members.push_back(canonicaljson::make_member("url", canonicaljson::Value{request.url})); + members.push_back(canonicaljson::make_member("user_id", canonicaljson::Value{user_id})); + auto const body = canonicaljson::serialize_canonical(canonicaljson::Value{std::move(members)}); + if (body.error != canonicaljson::CanonicalJsonError::none) + { + return refusal(500U, "M_UNKNOWN", "the request to the other server cannot be written"); + } + auto const transaction = + federation::make_outbound_transaction(request.server_name, "POST", federation_livekit_token_path, + rt.homeserver.config.server().server_name, body.output); + auto secret = core::SecretBuffer{rt.homeserver.database.signing_secret_key.bytes()}; + auto const limits = std::optional{ + BoundedOutboundLimits{ + OutboundDeadline{deadline}, + std::chrono::seconds{rt.homeserver.client_outbound_proxy_policy.worker_margin_seconds}} + }; + auto const answer = [&] { + auto const released = RuntimeLockRelease{guard}; + return perform_outbound_call(rt.homeserver, OutboundAnswerTrust::unverified, {}, transaction, + signing_key->key_id, std::move(secret), "livekit.relay", deadline, + livekit_relay_response_max_bytes, limits); + }(); + if (!answer.ok) + { + if (answer.remote_status == 403U && answer.remote_errcode == "M_FORBIDDEN") + { + log_refusal("livekit.relay.refused", user_id, request.room_id, "the other server refused"); + return refusal(403U, "M_FORBIDDEN", "The other server refused to issue a token."); + } + if (answer.remote_status == 400U && answer.remote_errcode == "M_INVALID_PARAM") + { + log_refusal("livekit.relay.refused", user_id, request.room_id, "the other server found it invalid"); + return refusal(400U, "M_INVALID_PARAM", "The other server found the request invalid."); + } + log_refusal("livekit.relay.failed", user_id, request.room_id, + answer.remote_answered ? "status " + std::to_string(answer.remote_status) : "unreachable", + observability::LogEventSeverity::warning); + return refusal(502U, "M_UNKNOWN", "The other server could not issue a token."); + } + auto const parsed = canonicaljson::parse_json(answer.body); + auto const* object = std::get_if(&parsed.value.storage()); + auto const* jwt_value = object == nullptr ? nullptr : member_of(*object, "jwt"); + auto const* jwt = jwt_value == nullptr ? nullptr : std::get_if(&jwt_value->storage()); + if (parsed.error != canonicaljson::ParseError::none || jwt == nullptr || !relayed_jwt_is_well_formed(*jwt)) + { + log_refusal("livekit.relay.failed", user_id, request.room_id, "malformed answer", + observability::LogEventSeverity::warning); + return refusal(502U, "M_UNKNOWN", "The other server could not issue a token."); + } + observability::log_diagnostic(log_module, "livekit.relay.issued", + { + {"user_id", user_id, false}, + {"room_id", request.room_id, false}, + {"server_name", request.server_name, false}, + }, + observability::LogEventSeverity::info); + return jwt_answer(*jwt); + } + + // The federation body: the client form's members without `server_name`, plus `user_id`. + [[nodiscard]] auto parse_federation_request(std::string_view const body, std::string_view const our_server) + -> LiveKitTokenRequestResult + { + auto const parsed = canonicaljson::parse_json(body); + auto const* object = std::get_if(&parsed.value.storage()); + if (parsed.error != canonicaljson::ParseError::none || object == nullptr) + { + return refusal(400U, "M_BAD_JSON", "the body must be a JSON object"); + } + auto request = LiveKitTokenRequest{}; + if (auto refused = read_required_members(*object, request)) + { + return std::move(*refused); + } + if (auto refused = read_required_string(*object, "user_id", max_livekit_user_id_bytes, request.user_id)) + { + return std::move(*refused); + } + if (!auth::user_id_is_valid_federated(request.user_id)) + { + return refusal(400U, "M_INVALID_PARAM", "user_id is not valid"); + } + // MSC4195 omits `server_name` here, since it is the receiving server's own. One that names another is refused. + if (auto const* server_name = member_of(*object, "server_name"); server_name != nullptr) + { + auto const* text = std::get_if(&server_name->storage()); + if (text == nullptr || *text != our_server) + { + return refusal(400U, "M_INVALID_PARAM", "server_name is not this server"); + } + } + return request; + } + +} // namespace + +auto issue_client_livekit_token(ClientServerRuntime& rt, LocalHttpRequest const& req, std::string const& user_id, + RuntimeLock& guard) -> OperationResult +{ + auto const& service = rt.homeserver.config.server().rtc.token_service; + if (service.url.empty()) + { + return refusal(404U, "M_UNRECOGNIZED", "no LiveKit token service is configured"); + } + auto parsed = parse_client_livekit_token_request(req.body); + if (auto* refused = std::get_if(&parsed); refused != nullptr) + { + return std::move(*refused); + } + auto request = std::get(std::move(parsed)); + auto const& our_server = rt.homeserver.config.server().server_name; + auto const remote = !request.server_name.empty() && request.server_name != our_server; + // MSC4195: for this server's own SFU, a `url` that is not it is 400 M_INVALID_PARAM. It is compared byte for byte + // and never fetched. Another server's `url` is that server's to judge. + if (!remote && request.url != service.url) + { + return refusal(400U, "M_INVALID_PARAM", "url is not this server's SFU"); + } + // Joined by this server's own current state: the membership row moves with every accepted member event, in the + // same transaction. An unknown room and a room the user is not joined to are the same answer. + auto const* membership = + database::find_membership_row(rt.homeserver.database.persistent_store, request.room_id, user_id); + if (membership == nullptr || membership->membership != "join") + { + log_refusal("livekit.token.refused", user_id, request.room_id, "not joined"); + return refusal(403U, "M_FORBIDDEN", "You are not joined to this room."); + } + if (remote) + { + return relay_client_livekit_token(rt, req, user_id, request, guard); + } + auto const room_name = livekit_room_name(request.room_id, request.slot_id); + auto const identity = livekit_participant_identity(user_id, request.member_id); + if (!room_name.has_value() || !identity.has_value()) + { + return refusal(400U, "M_INVALID_PARAM", "the room or member cannot be named"); + } + auto signed_token = sign_for(service, *identity, *room_name, true, user_id, request.room_id); + if (!signed_token.has_value()) + { + return refusal(500U, "M_UNKNOWN", "LiveKit tokens are unavailable"); + } + + // MSC4195: the room is created before a publishing token is issued, so an SFU that does not create rooms on + // join still admits the caller. This is a call to another server: an ADR-0079 slot first, one deadline, and + // runtime.mutex released around the call only. + if (rt.homeserver.outbound_client == nullptr || rt.homeserver.cached_discovery == nullptr) + { + return refusal(502U, "M_UNKNOWN", "this server cannot make outbound requests"); + } + auto const slot = + admit_client_outbound_proxy(rt.homeserver, rate_limit_client_key(req, rt.homeserver.config.server())); + if (!slot.has_value()) + { + return client_outbound_refusal(rt); + } + auto const deadline = effective_client_outbound_deadline(rt.homeserver, livekit_call_deadline_seconds); + auto& client = *rt.homeserver.outbound_client; + auto& discovery = *rt.homeserver.cached_discovery; + auto const test_perform = rt.homeserver.test_livekit_perform; + auto const created = [&] { + auto const released = RuntimeLockRelease{guard}; + return perform_livekit_request(std::move(*signed_token->create_room), client, discovery, deadline, + test_perform); + }(); + if (!created.ok || created.response.status != 200U) + { + log_refusal("livekit.create_room_failed", user_id, request.room_id, + created.ok ? "status " + std::to_string(created.response.status) + : std::string{http::outbound_error_name(created.error)}, + observability::LogEventSeverity::warning); + return refusal(502U, "M_UNKNOWN", "the SFU could not be reached"); + } + observability::log_diagnostic(log_module, "livekit.token.issued", + { + {"user_id", user_id, false}, + {"room_id", request.room_id, false}, + }, + observability::LogEventSeverity::info); + return jwt_answer(std::move(signed_token->token)); +} + +auto issue_federation_livekit_token(HomeserverRuntime& runtime, std::string_view const origin, + std::string_view const body) -> OperationResult +{ + auto const& service = runtime.config.server().rtc.token_service; + if (service.url.empty()) + { + return refusal(404U, "M_UNRECOGNIZED", "no LiveKit token service is configured"); + } + auto const& our_server = runtime.config.server().server_name; + auto parsed = parse_federation_request(body, our_server); + if (auto* refused = std::get_if(&parsed); refused != nullptr) + { + return std::move(*refused); + } + auto const& request = std::get(parsed); + auto const& store = runtime.database.persistent_store; + // MSC4195, in its order: this server joined to the room, the user of the origin, the user joined; each 403 + // M_FORBIDDEN with one text, so the answer tells a server nothing about a room it has no member in. All judged by + // this server's own current state (ADR-0831). + auto const forbidden = [&](std::string_view const reason) { + log_refusal("livekit.federation.refused", request.user_id, request.room_id, reason); + return refusal(403U, "M_FORBIDDEN", "No token can be issued for this user in this room."); + }; + if (!room_state_is_current(store, request.room_id, our_server)) + { + return forbidden("this server is not in the room"); + } + if (auth::user_id_server_name(request.user_id) != origin) + { + return forbidden("user_id is not of the origin"); + } + if (current_state_membership(store, request.room_id, request.user_id) != "join") + { + return forbidden("not joined"); + } + if (request.url != service.url) + { + return refusal(400U, "M_INVALID_PARAM", "url is not this server's SFU"); + } + auto const room_name = livekit_room_name(request.room_id, request.slot_id); + auto const identity = livekit_participant_identity(request.user_id, request.member_id); + if (!room_name.has_value() || !identity.has_value()) + { + return refusal(400U, "M_INVALID_PARAM", "the room or member cannot be named"); + } + // A user of another server subscribes only (MSC4195 lets a server restrict publishing for them; ADR-0831): no + // `canPublish`, `canPublishData`, and no CreateRoom call made on another server's behalf. + auto signed_token = sign_for(service, *identity, *room_name, false, request.user_id, request.room_id); + if (!signed_token.has_value()) + { + return refusal(500U, "M_UNKNOWN", "LiveKit tokens are unavailable"); + } + observability::log_diagnostic(log_module, "livekit.federation.issued", + { + {"origin", std::string{origin}, false}, + {"user_id", request.user_id, false}, + {"room_id", request.room_id, false}, + }, + observability::LogEventSeverity::info); + return jwt_answer(std::move(signed_token->token)); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/RoomService.cpp b/src/homeserver/RoomService.cpp index 6557a1bd0..ba1729d56 100644 --- a/src/homeserver/RoomService.cpp +++ b/src/homeserver/RoomService.cpp @@ -1840,15 +1840,6 @@ namespace return authorising == nullptr ? std::string{} : *authorising; } - // `user_id`'s membership in the room's current state, or empty. - [[nodiscard]] auto current_membership_of(database::PersistentStore const& store, std::string_view room_id, - std::string_view user_id) -> std::string - { - auto const event_id = database::find_current_state_event_id(store, room_id, "m.room.member", user_id); - return event_id.has_value() ? std::string{events::extract_content_membership(find_event_json(store, *event_id))} - : std::string{}; - } - [[nodiscard]] auto build_auth_event_map(database::PersistentStore const& store, std::string_view room_id, std::string_view sender, std::string_view target_state_key, std::string_view event_type, canonicaljson::Value const& event) @@ -2007,7 +1998,7 @@ namespace // 4.3.5.1), so a copied field is dropped rather than honoured or refused. auto const drop_join_authoriser = event_type == "m.room.member" && membership == "join" && event_state_key == sender && - current_membership_of(runtime.database.persistent_store, room_id, sender) == "join"; + current_state_membership(runtime.database.persistent_store, room_id, sender) == "join"; if (event_type == "m.room.member") { // A restricted join names its authorising user's m.room.member @@ -2736,17 +2727,29 @@ auto apply_membership_to_roster(HomeserverRuntime& runtime, std::string_view roo namespace { - // "M_INVITE_BLOCKED" when a remote error body's `errcode` is exactly that, else empty (SS7). The body is a - // remote server's, so nothing else of it is kept. - [[nodiscard]] auto remote_invite_blocked_errcode(std::string_view body) -> std::string + // A remote error body's `errcode` when it is exactly one a caller acts on, else empty: `M_INVITE_BLOCKED` (SS7), + // and the `M_FORBIDDEN` and `M_INVALID_PARAM` a LiveKit token relay passes on in its own words (ADR-0831). The + // body is a remote server's, so nothing else of it is kept, and only these fixed values are returned. + [[nodiscard]] auto remote_known_errcode(std::string_view body) -> std::string { auto const parsed = canonicaljson::parse_lossless(body); auto const* root = parsed.error == canonicaljson::ParseError::none ? std::get_if(&parsed.value.storage()) : nullptr; auto const* errcode = root == nullptr ? nullptr : string_member(*root, "errcode"); - return errcode != nullptr && *errcode == invite_blocked_errcode ? std::string{invite_blocked_errcode} - : std::string{}; + if (errcode == nullptr) + { + return {}; + } + for (auto const known : {invite_blocked_errcode, std::string_view{"M_FORBIDDEN"}, + std::string_view{"M_INVALID_PARAM"}}) + { + if (*errcode == known) + { + return std::string{known}; + } + } + return {}; } // A make_join, make_leave or make_knock answer is one event plus `room_version`, so four times the 64 KiB event @@ -3050,7 +3053,7 @@ namespace outcome.error_detail.empty() ? "remote server returned " + std::to_string(outcome.response.status) : outcome.error_detail, outcome.ok ? outcome.response.status : std::uint16_t{0U}, - outcome.ok ? remote_invite_blocked_errcode(outcome.response.body) : std::string{}, + outcome.ok ? remote_known_errcode(outcome.response.body) : std::string{}, !outcome.ok && destination_gave_no_answer(outcome.error), outcome.ok || destination_sent_a_response(outcome.error)}; } @@ -4636,7 +4639,7 @@ namespace { auto held = database::find_current_state_event_id(store, room_id, "m.room.member", user_id); auto const agrees = held.has_value() && *held == claimed_event_id; - auto const holds_a_row = held.has_value() || !current_membership_of(store, room_id, user_id).empty(); + auto const holds_a_row = held.has_value() || !current_state_membership(store, room_id, user_id).empty(); return {agrees || !holds_a_row, std::move(held)}; } } // namespace @@ -7940,7 +7943,7 @@ auto exchange_third_party_invite(HomeserverRuntime& runtime, federation::ThirdPa } // The auth rules let a third-party invite stand in for the usual membership checks, so a member who is already // in the room, or banned, would be moved to `invite` by a replayed `signed` object (ADR-0485). - auto const membership = current_membership_of(store, exchange.room_id, exchange.target_user_id); + auto const membership = current_state_membership(store, exchange.room_id, exchange.target_user_id); if (membership == "join" || membership == "ban") { return make_operation_result(false, {}, "the invited user is already in the room or banned from it", 403U); @@ -10966,4 +10969,12 @@ auto validate_make_leave_response(std::string_view requested_room_id, std::strin return validate_make_leave_event(requested_room_id, requested_user_id, *response_object); } +auto current_state_membership(database::PersistentStore const& store, std::string_view const room_id, + std::string_view const user_id) -> std::string +{ + auto const event_id = database::find_current_state_event_id(store, room_id, "m.room.member", user_id); + return event_id.has_value() ? std::string{events::extract_content_membership(find_event_json(store, *event_id))} + : std::string{}; +} + } // namespace merovingian::homeserver diff --git a/src/homeserver/meson.build b/src/homeserver/meson.build index 46bddf1fd..b3b42ab36 100644 --- a/src/homeserver/meson.build +++ b/src/homeserver/meson.build @@ -94,6 +94,9 @@ homeserver_sources = files( 'TlsServerContextResult.cpp', 'TlsConnection.cpp', 'TlsConnectionResult.cpp', + 'LiveKitNames.cpp', + 'LiveKitRoomService.cpp', + 'LiveKitTokenService.cpp', 'TurnCredentials.cpp', 'MinimalWorkerEnv.cpp', 'WorkerIpcLimits.cpp', diff --git a/src/http/RateLimit.cpp b/src/http/RateLimit.cpp index 46836ea3a..881786670 100644 --- a/src/http/RateLimit.cpp +++ b/src/http/RateLimit.cpp @@ -226,6 +226,10 @@ auto default_client_rate_limit_config() noexcept -> RateLimitConfig {"/_matrix/client/unstable/org.matrix.msc4140/delayed_events/", {120U, 60U}}, {"/_matrix/client/v3/rooms/{roomId}/delayed_event/", {60U, 60U}}, {"/_matrix/client/unstable/org.matrix.msc4140/rooms/{roomId}/delayed_event/", {60U, 60U}}, + // ADR-0829: a call join asks one token per server in the call, and a reconnect asks + // again; each token for this server's SFU may cost a call to LiveKit. + {"/_matrix/client/v1/rtc/livekit/get_token", {60U, 60U}}, + {"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token", {60U, 60U}}, }, .default_per_ip = {600U, 60U}, }; diff --git a/src/main.cpp b/src/main.cpp index 9b97e009f..0c36d3fc8 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -265,6 +265,17 @@ struct BootstrapConfigResult final } } + // server.rtc.livekit.api_secret_file holds the LiveKit API secret (ADR-0829): owner-only like every other secret. + if (!config.server().rtc.token_service.api_secret_file.empty()) + { + auto livekit_secret_validation = validate_existing_secret_file_metadata( + config.server().rtc.token_service.api_secret_file, "server.rtc.livekit.api_secret_file", false); + if (!livekit_secret_validation.parsed.findings.empty()) + { + return livekit_secret_validation; + } + } + auto database_validation = validate_existing_secret_file_metadata(config.database().uri_file, "database.uri_file", true); if (!database_validation.parsed.findings.empty()) diff --git a/tests/complement/merovingian.conf.template b/tests/complement/merovingian.conf.template index 7e73b9ea5..a18753577 100644 --- a/tests/complement/merovingian.conf.template +++ b/tests/complement/merovingian.conf.template @@ -88,6 +88,8 @@ client_rate_limits.per_user./_matrix/client/v1/delayed_events/=1000000000/1s client_rate_limits.per_user./_matrix/client/unstable/org.matrix.msc4140/delayed_events/=1000000000/1s client_rate_limits.per_user./_matrix/client/v3/rooms/{roomId}/delayed_event/=1000000000/1s client_rate_limits.per_user./_matrix/client/unstable/org.matrix.msc4140/rooms/{roomId}/delayed_event/=1000000000/1s +client_rate_limits.per_user./_matrix/client/v1/rtc/livekit/get_token=1000000000/1s +client_rate_limits.per_user./_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token=1000000000/1s # Complement logs in and registers from many parallel subtests; four concurrent # Argon2id hashes answered some of them 429 (ADR-0246). Each takes 64 MiB, so 32 # bounds a homeserver container at 2 GiB of hashing. diff --git a/tests/conformance/AGENTS.md b/tests/conformance/AGENTS.md index 84e14581e..ca67c88e7 100644 --- a/tests/conformance/AGENTS.md +++ b/tests/conformance/AGENTS.md @@ -59,6 +59,7 @@ Every test in this directory directly encodes a **MUST** or **SHOULD** from the | `test_key_backup_conformance.cpp` | [CS API § Server-side key backups](../../docs/matrix-v1.19-spec/client-server-api.md#server-side-key-backups) (an upload for a session the backup holds keeps the better key: `is_verified`, then lower `first_message_index`, then lower `forwarded_count`; deleting a version deletes its keys and a new backup starts empty; updating a missing version is 404, a mismatched `version` or `algorithm` 400) | | `test_key_upload_validation_conformance.cpp` | [CS API `POST /keys/device_signing/upload`](../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3keysdevice_signingupload) (keys judged before any write: `user_id`, `usage`, one `keys` property, master key available; written in one transaction) · [`PUT /room_keys/keys`](../../docs/matrix-v1.19-spec/client-server-api.md#put_matrixclientv3room_keyskeys) (a malformed batch is 400, a failed write is 500, never a 200 with an etag) | | `test_key_publication_conformance.cpp` | [SS API § Key publication](../../docs/matrix-v1.19-spec/server-server-api.md#publishing-keys) | +| `test_livekit_token_conformance.cpp` | [MSC4195 — MatrixRTC transport using LiveKit backend](https://github.com/matrix-org/matrix-spec-proposals/blob/6d49798949e1b31023565d4ff1c7fe10f4cacf83/proposals/4195-matrixrtc-livekit.md) (unstable; not part of v1.19): `POST /_matrix/client/v1/rtc/livekit/get_token` refuses a user not joined to the room with 403 `M_FORBIDDEN` alike for a room that does not exist, a `url` that is not this server's SFU with 400 `M_INVALID_PARAM`, and creates the LiveKit room before answering a `jwt` with the MSC's claims | | `test_membership_projection_conformance.cpp` | [CS API § m.room.member](../../docs/matrix-v1.19-spec/client-server-api.md#mroommember) (a ban, kick or invite sent through `PUT /state/m.room.member/{userId}` takes effect as through the membership APIs; a banned user still reads pre-ban history and nothing after) | | `test_notifications_conformance.cpp` | [CS API § Push Notifications](../../docs/matrix-v1.19-spec/client-server-api.md#push-notifications) | | `test_outbound_delivery_conformance.cpp` | [SS API § Transactions](../../docs/matrix-v1.19-spec/server-server-api.md#transactions) · [§ EDUs](../../docs/matrix-v1.19-spec/server-server-api.md#edus) | diff --git a/tests/conformance/test_livekit_token_conformance.cpp b/tests/conformance/test_livekit_token_conformance.cpp new file mode 100644 index 000000000..f7e037a5f --- /dev/null +++ b/tests/conformance/test_livekit_token_conformance.cpp @@ -0,0 +1,332 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// MSC4195 (MatrixRTC transport using LiveKit backend; unstable, not part of v1.19), the client get_token endpoint, at +// the revision this server implements: +// https://github.com/matrix-org/matrix-spec-proposals/blob/6d49798949e1b31023565d4ff1c7fe10f4cacf83/proposals/4195-matrixrtc-livekit.md +// LiveKit is HomeserverRuntime::test_livekit_perform; what this server decides beyond the MSC is in +// tests/integration/test_livekit_token_flow.cpp. + +#include "../support/InMemoryDatabaseConfig.hpp" +#include "../support/JsonTestSupport.hpp" +#include "../support/MasterKey.hpp" +#include "../support/RegistrationToken.hpp" +#include "../support/TempDirectory.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/config/ClientRateLimitsConfig.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/config/ListenersConfig.hpp" +#include "merovingian/config/LogModulesConfig.hpp" +#include "merovingian/config/SecurityConfig.hpp" +#include "merovingian/config/ServerConfig.hpp" +#include "merovingian/crypto/LiveKitToken.hpp" +#include "merovingian/crypto/VerifiedHs256Token.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/LiveKitNames.hpp" +#include "merovingian/http/OutboundRequest.hpp" +#include "merovingian/http/OutboundResult.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +namespace hs = merovingian::homeserver; +using namespace merovingian::tests; + +constexpr auto sfu_url = std::string_view{"wss://livekit.example.org"}; +constexpr auto secret = std::string_view{"conformance-secret-of-32-bytes!!"}; +constexpr auto path = std::string_view{"/_matrix/client/v1/rtc/livekit/get_token"}; + +class SecretDirectory final +{ +public: + SecretDirectory() + : m_directory{temporary_directory() / ("merovingian-msc4195-" + std::to_string(std::random_device{}()))} + { + std::filesystem::create_directories(m_directory); + std::filesystem::permissions(m_directory, std::filesystem::perms::owner_all); + auto stream = std::ofstream{file(), std::ios::binary}; + stream << secret; + stream.close(); + std::filesystem::permissions(file(), std::filesystem::perms::owner_read); + } + ~SecretDirectory() + { + auto ignored = std::error_code{}; + std::filesystem::remove_all(m_directory, ignored); + } + SecretDirectory(SecretDirectory const&) = delete; + auto operator=(SecretDirectory const&) -> SecretDirectory& = delete; + SecretDirectory(SecretDirectory&&) = delete; + auto operator=(SecretDirectory&&) -> SecretDirectory& = delete; + + [[nodiscard]] auto file() const -> std::filesystem::path + { + return m_directory / "livekit_secret"; + } + +private: + std::filesystem::path m_directory; +}; + +struct Reply final +{ + std::uint16_t status{}; + std::string body{}; +}; + +[[nodiscard]] auto call(hs::ClientServerRuntime& runtime, std::string method, std::string target, std::string token, + std::string body) -> Reply +{ + auto const result = hs::handle_client_server_request( + runtime, {std::move(method), std::move(target), std::move(token), std::move(body)}); + return {result.response.status, result.response.body}; +} + +[[nodiscard]] auto errcode_of(Reply const& reply) -> std::string +{ + auto const body = parse_object(reply.body); + auto const* errcode = string_member(body, "errcode"); + return errcode == nullptr ? std::string{} : *errcode; +} + +[[nodiscard]] auto login(hs::ClientServerRuntime& runtime, std::string const& localpart) -> std::string +{ + REQUIRE(call(runtime, "POST", "/_matrix/client/v3/register", {}, registration_json(localpart, "CorrectHorse7!")) + .status == 200U); + auto const reply = call(runtime, "POST", "/_matrix/client/v3/login", {}, + R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":"@)" + localpart + + R"(:example.org"},"password":"CorrectHorse7!","device_id":"D1"})"); + REQUIRE(reply.status == 200U); + auto const body = parse_object(reply.body); + auto const* token = string_member(body, "access_token"); + REQUIRE(token != nullptr); + return *token; +} + +[[nodiscard]] auto request_body(std::string const& room_id, std::string_view const url = sfu_url) -> std::string +{ + return R"({"server_name":"example.org","url":")" + std::string{url} + R"(","room_id":")" + room_id + + R"(","slot_id":"m.call#room","member_id":"xyzABCDEF10123"})"; +} + +[[nodiscard]] auto now_seconds() -> std::int64_t +{ + return std::chrono::duration_cast(std::chrono::system_clock::now().time_since_epoch()) + .count(); +} + +// A server issuing tokens for its own SFU, alice in a public room and bob in none. +class Msc4195Server final +{ +public: + Msc4195Server() + : m_started{hs::start_client_server(config())} + , m_calls{std::make_shared>()} + { + REQUIRE(m_started.started); + auto calls = m_calls; + runtime().homeserver.test_livekit_perform = [calls](merovingian::http::OutboundRequest const& outbound) { + calls->push_back(outbound); + auto result = merovingian::http::OutboundResult{}; + result.ok = true; + result.response.status = 200U; + result.response.body = "{}"; + return result; + }; + alice = login(runtime(), "alice"); + bob = login(runtime(), "bob"); + auto const created = + call(runtime(), "POST", "/_matrix/client/v3/createRoom", alice, R"({"preset":"public_chat"})"); + REQUIRE(created.status == 200U); + auto const body = parse_object(created.body); + auto const* id = string_member(body, "room_id"); + REQUIRE(id != nullptr); + room_id = *id; + } + + [[nodiscard]] auto runtime() -> hs::ClientServerRuntime& + { + return m_started.runtime; + } + + [[nodiscard]] auto livekit_calls() const -> std::vector const& + { + return *m_calls; + } + + std::string alice{}; + std::string bob{}; + std::string room_id{}; + +private: + [[nodiscard]] auto config() const -> merovingian::config::Config + { + auto security = merovingian::config::SecurityConfig{}; + security.secrets.master_key_file = shared_master_key_file(); + enable_token_registration(security); + auto server = merovingian::config::ServerConfig{}; + server.rtc.token_service.url = std::string{sfu_url}; + server.rtc.token_service.api_url = "https://livekit-api.example.org"; + server.rtc.token_service.api_key = "APIconformance"; + server.rtc.token_service.api_secret_file = m_secret.file().string(); + return { + std::move(server), merovingian::config::ListenersConfig{}, in_memory_database_config(), + std::move(security), merovingian::config::ClientRateLimitsConfig{}, merovingian::config::LogModulesConfig{}, + }; + } + + SecretDirectory m_secret{}; + hs::ClientServerStartResult m_started; + std::shared_ptr> m_calls; +}; + +} // namespace + +// Spec: MSC4195 (unstable; not part of v1.19) +// Endpoint / Section: POST /_matrix/client/v1/rtc/livekit/get_token +// URL: proposals/4195-matrixrtc-livekit.md, "The receiving server MUST reject the request in all of the following +// cases", and "Validation or authorisation failures MUST NOT reveal information about whether a particular Matrix +// user, device, or room exists." +// +// A user not joined to `room_id` is refused with 403 M_FORBIDDEN, and a room that does not exist is answered alike. +SCENARIO("get_token refuses a user not joined to the room, revealing nothing", "[conformance][client-server][livekit]") +{ + GIVEN("alice's room, and bob in none") + { + auto server = Msc4195Server{}; + + WHEN("bob asks for a token for alice's room, and for a room that does not exist") + { + auto const existing = + call(server.runtime(), "POST", std::string{path}, server.bob, request_body(server.room_id)); + auto const missing = call(server.runtime(), "POST", std::string{path}, server.bob, + request_body("!doesnotexist:example.org")); + + THEN("both are 403 M_FORBIDDEN with the same body") + { + // Spec MUST: a requesting user not joined to the room is rejected with HTTP 403 / M_FORBIDDEN. + REQUIRE(existing.status == 403U); + REQUIRE(errcode_of(existing) == "M_FORBIDDEN"); + // Spec MUST NOT: reveal whether a particular room exists. + REQUIRE(missing.status == existing.status); + REQUIRE(missing.body == existing.body); + } + } + } +} + +// Spec: MSC4195 (unstable; not part of v1.19) +// Endpoint / Section: POST /_matrix/client/v1/rtc/livekit/get_token +// URL: proposals/4195-matrixrtc-livekit.md, "If `server_name` is the server's own name and `url` does not match one of +// the server's own SFUs, reject the request with HTTP 400 / `M_INVALID_PARAM`." +SCENARIO("get_token refuses a url that is not one of this server's SFUs", "[conformance][client-server][livekit]") +{ + GIVEN("alice, joined to her room") + { + auto server = Msc4195Server{}; + + WHEN("she names this server and another SFU") + { + auto const reply = call(server.runtime(), "POST", std::string{path}, server.alice, + request_body(server.room_id, "wss://other-sfu.example.net")); + + THEN("the answer is 400 M_INVALID_PARAM") + { + // Spec MUST: `url` not one of the server's own SFUs is HTTP 400 / M_INVALID_PARAM. + REQUIRE(reply.status == 400U); + REQUIRE(errcode_of(reply) == "M_INVALID_PARAM"); + REQUIRE(server.livekit_calls().empty()); + } + } + } +} + +// Spec: MSC4195 (unstable; not part of v1.19) +// Endpoint / Section: POST /_matrix/client/v1/rtc/livekit/get_token; "Access token properties"; "LiveKit room name +// and participant identity" +// URL: proposals/4195-matrixrtc-livekit.md +// +// For its own server the server "ensures that the room exists, creating it if needed" (REQUIRED), then answers 200 +// with a single required property `jwt`. The token's `sub` MUST be the participant identity, `nbf` MUST be the current +// time, `video.room` MUST be the room name, `roomCreate` and `hidden` MUST be false, and `roomJoin`, `canPublish` (a +// local user) and `canSubscribe` MUST be true. +SCENARIO("get_token creates the LiveKit room and answers a token with the MSC4195 claims", + "[conformance][client-server][livekit]") +{ + GIVEN("alice, joined to her room") + { + auto server = Msc4195Server{}; + + WHEN("she asks for a token for this server's SFU") + { + auto const before = now_seconds(); + auto const reply = + call(server.runtime(), "POST", std::string{path}, server.alice, request_body(server.room_id)); + auto const after = now_seconds(); + + THEN("the room was created first and the token carries exactly what the MSC requires") + { + REQUIRE(reply.status == 200U); + auto const body = parse_object(reply.body); + auto const* jwt = string_member(body, "jwt"); + // Spec: a JSON object with a single required property `jwt`. + REQUIRE(jwt != nullptr); + auto const room_name = hs::livekit_room_name(server.room_id, "m.call#room"); + auto const identity = hs::livekit_participant_identity("@alice:example.org", "xyzABCDEF10123"); + REQUIRE((room_name.has_value() && identity.has_value())); + // Spec REQUIRED: the server ensures the room exists before answering. + REQUIRE(server.livekit_calls().size() == 1U); + REQUIRE(server.livekit_calls().front().url.ends_with("/twirp/livekit.RoomService/CreateRoom")); + REQUIRE(server.livekit_calls().front().body.find(*room_name) != std::string::npos); + + auto const key = std::vector{secret.begin(), secret.end()}; + auto const verified = merovingian::crypto::verify_hs256_token(*jwt, std::span{key}); + REQUIRE(verified.has_value()); + auto const payload = parse_object(verified->payload_json); + auto const* sub = string_member(payload, "sub"); + // Spec MUST: `sub` is the LiveKit participant identity. + REQUIRE(sub != nullptr); + REQUIRE(*sub == *identity); + auto const* nbf = int_member(payload, "nbf"); + // Spec MUST: `nbf` is the current time. + REQUIRE(nbf != nullptr); + REQUIRE(*nbf >= before); + REQUIRE(*nbf <= after); + auto const* video = object_member_as_object(payload, "video"); + REQUIRE(video != nullptr); + auto const* room = string_member(*video, "room"); + // Spec MUST: `video.room` is the LiveKit room name. + REQUIRE(room != nullptr); + REQUIRE(*room == *room_name); + // Spec MUST: `video.roomCreate` and `video.hidden` are false (LiveKit reads an absent grant as false). + auto const* create = bool_member(*video, "roomCreate"); + auto const* hidden = bool_member(*video, "hidden"); + REQUIRE((create == nullptr || !*create)); + REQUIRE((hidden == nullptr || !*hidden)); + REQUIRE(object_member(*video, "roomAdmin") == nullptr); + // Spec MUST: `roomJoin`, `canPublish` for a local user and `canSubscribe` are true. Written explicitly: + // LiveKit reads an absent `canPublish` or `canSubscribe` as true too, but the claim says so itself. + auto const* join = bool_member(*video, "roomJoin"); + auto const* publish = bool_member(*video, "canPublish"); + auto const* subscribe = bool_member(*video, "canSubscribe"); + REQUIRE((join != nullptr && publish != nullptr && subscribe != nullptr)); + REQUIRE((*join && *publish && *subscribe)); + } + } + } +} diff --git a/tests/conformance/test_route_query_conformance.cpp b/tests/conformance/test_route_query_conformance.cpp index a8f589c65..b4963a16d 100644 --- a/tests/conformance/test_route_query_conformance.cpp +++ b/tests/conformance/test_route_query_conformance.cpp @@ -111,7 +111,7 @@ SCENARIO("every client route that matched its whole target answers a request wit // Every route that was compared with `req.target == "..."`. A handler may answer anything // (a UIA challenge, a 400 for the empty body); what it may not do is answer as though the // route does not exist. /logout is last: it ends the session. - constexpr auto routes = std::array{ + constexpr auto routes = std::array{ { {"GET", "/.well-known/matrix/client", ""}, {"GET", "/_matrix/client/versions", ""}, @@ -152,6 +152,8 @@ SCENARIO("every client route that matched its whole target answers a request wit {"GET", "/_matrix/client/v3/voip/turnServer", ""}, {"GET", "/_matrix/client/v1/rtc/transports", ""}, {"GET", "/_matrix/client/unstable/org.matrix.msc4143/rtc/transports", ""}, + {"POST", "/_matrix/client/v1/rtc/livekit/get_token", "{}"}, + {"POST", "/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token", "{}"}, {"GET", "/_matrix/client/v3/devices", ""}, {"POST", "/_matrix/client/v3/delete_devices", "{}"}, {"GET", "/_matrix/client/v3/joined_rooms", ""}, diff --git a/tests/integration/test_livekit_token_flow.cpp b/tests/integration/test_livekit_token_flow.cpp new file mode 100644 index 000000000..c0b70c731 --- /dev/null +++ b/tests/integration/test_livekit_token_flow.cpp @@ -0,0 +1,1124 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The built-in MatrixRTC token service (MSC4195; ADR-0829, ADR-0830): POST .../rtc/livekit/get_token driven through +// handle_client_server_request, with HomeserverRuntime::test_livekit_perform standing in for LiveKit. No network. + +#include "../support/ConsoleLogCapture.hpp" +#include "../support/InMemoryDatabaseConfig.hpp" +#include "../support/JsonTestSupport.hpp" +#include "../support/MasterKey.hpp" +#include "../support/RegistrationToken.hpp" +#include "../support/TempDirectory.hpp" +#include "../support/TlsMockServer.hpp" +#include "../support/TlsTestCertificate.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/config/ClientRateLimitsConfig.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/config/ListenersConfig.hpp" +#include "merovingian/config/LogModulesConfig.hpp" +#include "merovingian/config/SecurityConfig.hpp" +#include "merovingian/config/ServerConfig.hpp" +#include "merovingian/core/SocketHandle.hpp" +#include "merovingian/crypto/LiveKitToken.hpp" +#include "merovingian/crypto/VerifiedHs256Token.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientOutboundProxy.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LiveKitNames.hpp" +#include "merovingian/homeserver/LiveKitTokenService.hpp" +#include "merovingian/homeserver/LocalRoom.hpp" +#include "merovingian/homeserver/OperationResult.hpp" +#include "merovingian/homeserver/RuntimeMutex.hpp" +#include "merovingian/homeserver/TestOnlyForcedOutboundResolution.hpp" +#include "merovingian/homeserver/Tls.hpp" +#include "merovingian/homeserver/TlsServerContextResult.hpp" +#include "merovingian/http/OutboundRequest.hpp" +#include "merovingian/http/OutboundResult.hpp" +#include "merovingian/net/TcpAcceptor.hpp" + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +namespace hs = merovingian::homeserver; +using namespace merovingian::tests; + +constexpr auto sfu_url = std::string_view{"wss://sfu.example.org"}; +constexpr auto api_url = std::string_view{"https://sfu-api.example.org"}; +constexpr auto api_key = std::string_view{"APIkey_test"}; +// 32 bytes, the minimum the signers accept. +constexpr auto api_secret = std::string_view{"0123456789abcdef0123456789abcdef"}; +constexpr auto stable_path = std::string_view{"/_matrix/client/v1/rtc/livekit/get_token"}; +constexpr auto unstable_path = std::string_view{"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token"}; +constexpr auto password = std::string_view{"CorrectHorse7!"}; + +[[nodiscard]] auto secret_bytes(std::string_view const text) -> std::vector +{ + return {text.begin(), text.end()}; +} + +class SecretFile final +{ +public: + explicit SecretFile(std::string_view const contents) + : m_directory{temporary_directory() / ("merovingian-livekit-" + std::to_string(std::random_device{}()))} + { + std::filesystem::create_directories(m_directory); + std::filesystem::permissions(m_directory, std::filesystem::perms::owner_all); + m_path = m_directory / "livekit_secret"; + auto stream = std::ofstream{m_path, std::ios::binary}; + stream << contents; + stream.close(); + std::filesystem::permissions(m_path, std::filesystem::perms::owner_read); + } + ~SecretFile() + { + auto ignored = std::error_code{}; + std::filesystem::remove_all(m_directory, ignored); + } + SecretFile(SecretFile const&) = delete; + auto operator=(SecretFile const&) -> SecretFile& = delete; + SecretFile(SecretFile&&) = delete; + auto operator=(SecretFile&&) -> SecretFile& = delete; + + [[nodiscard]] auto path() const -> std::string + { + return m_path.string(); + } + +private: + std::filesystem::path m_directory; + std::filesystem::path m_path; +}; + +// The configuration with the built-in service on when `secret_path` is set, off when it is empty. +[[nodiscard]] auto livekit_config(std::string const& secret_path) -> merovingian::config::Config +{ + auto security = merovingian::config::SecurityConfig{}; + security.secrets.master_key_file = shared_master_key_file(); + enable_token_registration(security); + auto server = merovingian::config::ServerConfig{}; + if (!secret_path.empty()) + { + server.rtc.token_service.url = std::string{sfu_url}; + server.rtc.token_service.api_url = std::string{api_url}; + server.rtc.token_service.api_key = std::string{api_key}; + server.rtc.token_service.api_secret_file = secret_path; + server.rtc.token_service.token_lifetime_seconds = 600U; + } + return { + std::move(server), merovingian::config::ListenersConfig{}, in_memory_database_config(), + std::move(security), merovingian::config::ClientRateLimitsConfig{}, merovingian::config::LogModulesConfig{}, + }; +} + +struct Answer final +{ + std::uint16_t status{}; + std::string body{}; +}; + +[[nodiscard]] auto request(hs::ClientServerRuntime& runtime, std::string method, std::string target, std::string token, + std::string body) -> Answer +{ + auto const result = hs::handle_client_server_request( + runtime, {std::move(method), std::move(target), std::move(token), std::move(body)}); + return {result.response.status, result.response.body}; +} + +[[nodiscard]] auto errcode_of(Answer const& answer) -> std::string +{ + auto const body = parse_object(answer.body); + auto const* errcode = string_member(body, "errcode"); + return errcode == nullptr ? std::string{} : *errcode; +} + +[[nodiscard]] auto login(hs::ClientServerRuntime& runtime, std::string const& localpart) -> std::string +{ + REQUIRE( + request(runtime, "POST", "/_matrix/client/v3/register", {}, registration_json(localpart, std::string{password})) + .status == 200U); + auto const response = + request(runtime, "POST", "/_matrix/client/v3/login", {}, + R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":"@)" + localpart + + R"(:example.org"},"password":")" + std::string{password} + R"(","device_id":"D1"})"); + REQUIRE(response.status == 200U); + auto const body = parse_object(response.body); + auto const* token = string_member(body, "access_token"); + REQUIRE(token != nullptr); + return *token; +} + +[[nodiscard]] auto token_body(std::string_view const room_id, std::string_view const url = sfu_url, + std::string_view const member_id = "DEVICEID_member") -> std::string +{ + return R"({"url":")" + std::string{url} + R"(","room_id":")" + std::string{room_id} + + R"(","slot_id":"m.call#room","member_id":")" + std::string{member_id} + R"(","server_name":"example.org"})"; +} + +// LiveKit, as far as the room service goes: records each request and answers with `status`, or fails the call. +struct MockLiveKit final +{ + std::vector requests{}; + std::uint16_t status{200U}; + bool reachable{true}; +}; + +auto install_mock(hs::ClientServerRuntime& runtime, std::shared_ptr const& mock) -> void +{ + runtime.homeserver.test_livekit_perform = [mock](merovingian::http::OutboundRequest const& outbound) { + mock->requests.push_back(outbound); + auto result = merovingian::http::OutboundResult{}; + result.ok = mock->reachable; + if (mock->reachable) + { + result.response.status = mock->status; + result.response.body = "{}"; + } + else + { + result.error = merovingian::http::OutboundError::network_error; + result.error_detail = "connection refused"; + } + return result; + }; +} + +[[nodiscard]] auto header_value(merovingian::http::OutboundRequest const& outbound, std::string_view const name) + -> std::optional +{ + for (auto const& header : outbound.headers) + { + if (header.name == name) + { + return header.value; + } + } + return std::nullopt; +} + +[[nodiscard]] auto verified_payload(std::string_view const token) -> merovingian::canonicaljson::Object +{ + auto const secret = secret_bytes(api_secret); + auto const verified = merovingian::crypto::verify_hs256_token(token, std::span{secret}); + REQUIRE(verified.has_value()); + CHECK(verified->header_json == R"({"alg":"HS256","typ":"JWT"})"); + return parse_object(verified->payload_json); +} + +// A server with the service on, alice in a public room and bob registered but not in it. +class LiveKitFixture final +{ +public: + explicit LiveKitFixture(std::string const& secret_path = {}) + : m_secret{api_secret} + , m_started{hs::start_client_server(livekit_config(secret_path.empty() ? m_secret.path() : secret_path))} + , m_mock{std::make_shared()} + { + REQUIRE(m_started.started); + install_mock(runtime(), m_mock); + alice_token = login(runtime(), "alice"); + bob_token = login(runtime(), "bob"); + auto const created = + request(runtime(), "POST", "/_matrix/client/v3/createRoom", alice_token, R"({"preset":"public_chat"})"); + REQUIRE(created.status == 200U); + auto const body = parse_object(created.body); + auto const* id = string_member(body, "room_id"); + REQUIRE(id != nullptr); + room_id = *id; + } + + [[nodiscard]] auto runtime() -> hs::ClientServerRuntime& + { + return m_started.runtime; + } + + [[nodiscard]] auto mock() const -> MockLiveKit& + { + return *m_mock; + } + + std::string alice_token{}; + std::string bob_token{}; + std::string room_id{}; + +private: + SecretFile m_secret; + hs::ClientServerStartResult m_started; + std::shared_ptr m_mock; +}; + +constexpr auto remote_server = std::string_view{"remote.example.org"}; +constexpr auto carol = std::string_view{"@carol:remote.example.org"}; + +// Puts `user_id` joined in the room's current state, as an accepted federated join would. +auto seed_remote_join(hs::ClientServerRuntime& runtime, std::string const& room_id, std::string_view const user_id) + -> void +{ + auto& store = runtime.homeserver.database.persistent_store; + auto const event_id = "$join-of-" + std::string{user_id}; + auto const json = R"({"content":{"membership":"join"},"event_id":")" + event_id + R"(","room_id":")" + room_id + + R"(","sender":")" + std::string{user_id} + R"(","state_key":")" + std::string{user_id} + + R"(","type":"m.room.member"})"; + store.events.push_back({event_id, room_id, std::string{user_id}, json, 9U, 0U, {}, {}, {}}); + store.state.push_back({room_id, "m.room.member", std::string{user_id}, event_id}); + store.memberships.push_back({room_id, std::string{user_id}, "join", 0U}); + auto* room = hs::find_local_room(runtime.homeserver.database, room_id); + REQUIRE(room != nullptr); + std::ignore = room->members.add(std::string{user_id}); +} + +// MSC4195's federation body, as `origin` would send it. +[[nodiscard]] auto federation_body(std::string_view const room_id, std::string_view const user_id, + std::string_view const url = sfu_url) -> std::string +{ + return R"({"url":")" + std::string{url} + R"(","room_id":")" + std::string{room_id} + + R"(","slot_id":"m.call#room","member_id":"DEVICEID_member","user_id":")" + std::string{user_id} + R"("})"; +} + +// What main answers a federated request it has admitted, judged under the runtime lock as the relay calls it. +[[nodiscard]] auto federated(hs::ClientServerRuntime& runtime, std::string_view const origin, std::string const& body) + -> hs::OperationResult +{ + auto const guard = hs::RuntimeLock{runtime.homeserver.mutex}; + return hs::issue_federation_livekit_token(runtime.homeserver, origin, body); +} + +// Another server answering the relayed get_token once with `response`; the request it saw is kept. +class RemoteTokenServer final +{ +public: + RemoteTokenServer(hs::ClientServerRuntime& runtime, std::string response) + : m_response{std::move(response)} + , m_certificate{tls_mock::write_test_tls_certificate()} + , m_tls{hs::make_tls_server_context(m_certificate.certificate_file, m_certificate.private_key_file)} + { + REQUIRE(m_tls.ok()); + REQUIRE(m_acceptor.bind("127.0.0.1", 0U).ok); + runtime.homeserver.test_forced_outbound_resolution[std::string{remote_server}] = + hs::TestOnlyForcedOutboundResolution{ + "localhost", m_acceptor.bound_port(), {"127.0.0.1"}, m_certificate.certificate_pem}; + m_thread = std::thread{[this]() { + serve(); + }}; + } + + ~RemoteTokenServer() + { + std::ignore = finish(); + } + + RemoteTokenServer(RemoteTokenServer const&) = delete; + auto operator=(RemoteTokenServer const&) -> RemoteTokenServer& = delete; + RemoteTokenServer(RemoteTokenServer&&) = delete; + auto operator=(RemoteTokenServer&&) -> RemoteTokenServer& = delete; + + // Joins the serving thread; the request it saw is readable afterwards. + [[nodiscard]] auto finish() -> std::string const& + { + if (m_thread.joinable()) + { + m_thread.join(); + } + return m_captured; + } + +private: + // One connection: the whole request, headers and Content-Length body, then the response. + auto serve() noexcept -> void + { + auto const client_fd = tls_mock::accept_loopback(m_acceptor, 5000); + if (client_fd < 0) + { + return; + } + auto const owned = merovingian::core::SocketHandle{client_fd}; + auto tls = hs::accept_tls_connection(*m_tls.context, client_fd, 5000); + if (!tls.connection.has_value()) + { + return; + } + auto buffer = std::array{}; + auto expected = std::string::npos; + while (expected == std::string::npos || m_captured.size() < expected) + { + auto const bytes_read = tls.connection->read(buffer.data(), buffer.size()); + if (bytes_read <= 0) + { + break; + } + m_captured.append(buffer.data(), static_cast(bytes_read)); + auto const headers_end = m_captured.find("\r\n\r\n"); + if (expected == std::string::npos && headers_end != std::string::npos) + { + auto headers = m_captured.substr(0U, headers_end); + std::ranges::transform(headers, headers.begin(), [](unsigned char const c) { + return static_cast(std::tolower(c)); + }); + auto const length_at = headers.find("\r\ncontent-length:"); + auto const length = + length_at == std::string::npos + ? std::size_t{0U} + : static_cast(std::strtoul(headers.c_str() + length_at + 17U, nullptr, 10)); + expected = headers_end + 4U + length; + } + } + std::ignore = tls.connection->write(m_response); + } + + std::string m_response; + tls_mock::TlsTestCertificate m_certificate; + hs::TlsServerContextResult m_tls; + merovingian::net::TcpAcceptor m_acceptor{}; + std::string m_captured{}; + std::thread m_thread{}; +}; + +// alice's body asking for a token for the remote server's SFU. +[[nodiscard]] auto relay_body(std::string_view const room_id) -> std::string +{ + return R"({"url":"wss://sfu.remote.example.org","room_id":")" + std::string{room_id} + + R"(","slot_id":"m.call#room","member_id":"DEVICEID_member","server_name":")" + std::string{remote_server} + + R"("})"; +} + +} // namespace + +SCENARIO("A joined user gets a LiveKit token for this server's SFU, and the room is created first", + "[homeserver][livekit][rtc][client-server]") +{ + GIVEN("alice, joined to a room, and the built-in token service") + { + auto fixture = LiveKitFixture{}; + auto const path = std::string{GENERATE(stable_path, unstable_path)}; + + WHEN("alice asks for a token on " + path) + { + auto const answer = + request(fixture.runtime(), "POST", path, fixture.alice_token, token_body(fixture.room_id)); + + THEN("the answer is one jwt, signed with the API secret, for the MSC4195 names and no more") + { + REQUIRE(answer.status == 200U); + auto const body = parse_object(answer.body); + REQUIRE(body.size() == 1U); + auto const* jwt = string_member(body, "jwt"); + REQUIRE(jwt != nullptr); + auto const payload = verified_payload(*jwt); + auto const room_name = hs::livekit_room_name(fixture.room_id, "m.call#room"); + auto const identity = hs::livekit_participant_identity("@alice:example.org", "DEVICEID_member"); + REQUIRE((room_name.has_value() && identity.has_value())); + auto const* iss = string_member(payload, "iss"); + auto const* sub = string_member(payload, "sub"); + REQUIRE((iss != nullptr && sub != nullptr)); + CHECK(*iss == api_key); + CHECK(*sub == *identity); + auto const* nbf = int_member(payload, "nbf"); + auto const* exp = int_member(payload, "exp"); + REQUIRE((nbf != nullptr && exp != nullptr)); + CHECK(*exp - *nbf == 600); + auto const* video = object_member_as_object(payload, "video"); + REQUIRE(video != nullptr); + auto const* room = string_member(*video, "room"); + REQUIRE(room != nullptr); + CHECK(*room == *room_name); + auto const* join = bool_member(*video, "roomJoin"); + auto const* publish = bool_member(*video, "canPublish"); + auto const* publish_data = bool_member(*video, "canPublishData"); + auto const* subscribe = bool_member(*video, "canSubscribe"); + REQUIRE((join != nullptr && publish != nullptr && publish_data != nullptr && subscribe != nullptr)); + CHECK((*join && *publish && *publish_data && *subscribe)); + // Exactly those five grants: never roomCreate, roomAdmin, hidden, or anything else. + CHECK(video->size() == 5U); + // Nothing the SFU sees names the Matrix user, device or room. + CHECK(jwt->find("alice") == std::string::npos); + auto const secret = secret_bytes(api_secret); + auto const decoded = + merovingian::crypto::verify_hs256_token(*jwt, std::span{secret}); + REQUIRE(decoded.has_value()); + CHECK(decoded->payload_json.find("alice") == std::string::npos); + CHECK(decoded->payload_json.find("DEVICEID") == std::string::npos); + CHECK(decoded->payload_json.find(fixture.room_id) == std::string::npos); + } + + THEN("CreateRoom went to the configured API address, with a roomCreate-only token of its own") + { + REQUIRE(answer.status == 200U); + REQUIRE(fixture.mock().requests.size() == 1U); + auto const& call = fixture.mock().requests.front(); + CHECK(call.method == "POST"); + CHECK(call.url == "https://sfu-api.example.org:443/twirp/livekit.RoomService/CreateRoom"); + CHECK_FALSE(call.allow_cleartext_http); + CHECK(call.max_response_body_bytes == 16U * 1024U); + CHECK(call.total_timeout_seconds > 0U); + CHECK(call.total_timeout_seconds <= 10U); + auto const room_name = hs::livekit_room_name(fixture.room_id, "m.call#room"); + REQUIRE(room_name.has_value()); + CHECK(call.body == R"({"name":")" + *room_name + R"(","empty_timeout":300,"departure_timeout":20})"); + CHECK(header_value(call, "Content-Type") == std::optional{"application/json"}); + auto const authorization = header_value(call, "Authorization"); + REQUIRE(authorization.has_value()); + REQUIRE(authorization->starts_with("Bearer ")); + auto const payload = verified_payload(std::string_view{*authorization}.substr(7U)); + CHECK(string_member(payload, "sub") == nullptr); + auto const* video = object_member_as_object(payload, "video"); + REQUIRE(video != nullptr); + CHECK(video->size() == 1U); + auto const* create = bool_member(*video, "roomCreate"); + REQUIRE(create != nullptr); + CHECK(*create); + auto const* nbf = int_member(payload, "nbf"); + auto const* exp = int_member(payload, "exp"); + REQUIRE((nbf != nullptr && exp != nullptr)); + CHECK(*exp - *nbf == 60); + } + } + } +} + +SCENARIO("A token goes only to a user this server finds joined to the room", "[homeserver][livekit][rtc][negative]") +{ + GIVEN("alice in a room, and bob registered") + { + auto fixture = LiveKitFixture{}; + + WHEN("bob, never in the room, asks for a token for it") + { + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.bob_token, + token_body(fixture.room_id)); + auto const unknown = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.bob_token, + token_body("!nosuchroom:example.org")); + + THEN("both are the same 403, and LiveKit is never called") + { + CHECK(answer.status == 403U); + CHECK(errcode_of(answer) == "M_FORBIDDEN"); + CHECK(unknown.status == 403U); + CHECK(unknown.body == answer.body); + CHECK(answer.body.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("bob joins, then leaves, and asks") + { + auto const room_path = "/_matrix/client/v3/rooms/" + fixture.room_id; + REQUIRE(request(fixture.runtime(), "POST", "/_matrix/client/v3/join/" + fixture.room_id, fixture.bob_token, + "{}") + .status == 200U); + auto const joined = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.bob_token, + token_body(fixture.room_id)); + REQUIRE(request(fixture.runtime(), "POST", room_path + "/leave", fixture.bob_token, "{}").status == 200U); + auto const left = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.bob_token, + token_body(fixture.room_id)); + + THEN("he had a token while joined and none after") + { + CHECK(joined.status == 200U); + CHECK(left.status == 403U); + CHECK(errcode_of(left) == "M_FORBIDDEN"); + CHECK(fixture.mock().requests.size() == 1U); + } + } + + WHEN("alice names a url that is not this server's SFU") + { + auto const other_url = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + token_body(fixture.room_id, "wss://evil.example.net")); + auto const prefix_url = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + token_body(fixture.room_id, "wss://sfu.example.org/")); + + THEN("each is 400 M_INVALID_PARAM, and nothing is fetched or called") + { + for (auto const* answer : {&other_url, &prefix_url}) + { + CHECK(answer->status == 400U); + CHECK(errcode_of(*answer) == "M_INVALID_PARAM"); + } + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("alice names another server, which has no member in the room") + { + auto const other_server = + request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + R"({"url":"wss://sfu.other.example.net","room_id":")" + fixture.room_id + + R"(","slot_id":"m.call#room","member_id":"m","server_name":"other.example.net"})"); + + THEN("it is 403 M_FORBIDDEN, nothing is relayed, and LiveKit is not called") + { + CHECK(other_server.status == 403U); + CHECK(errcode_of(other_server) == "M_FORBIDDEN"); + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("bob, not joined, names another server") + { + auto const answer = + request(fixture.runtime(), "POST", std::string{stable_path}, fixture.bob_token, + R"({"url":"wss://sfu.other.example.net","room_id":")" + fixture.room_id + + R"(","slot_id":"m.call#room","member_id":"m","server_name":"other.example.net"})"); + + THEN("he gets the not-joined 403 before any relay is considered") + { + auto const local = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.bob_token, + token_body(fixture.room_id)); + CHECK(answer.status == 403U); + CHECK(answer.body == local.body); + } + } + } +} + +SCENARIO("A get_token body is read strictly", "[homeserver][livekit][rtc][negative]") +{ + GIVEN("alice in a room") + { + auto fixture = LiveKitFixture{}; + auto const room = fixture.room_id; + struct Case final + { + std::string body; + std::string errcode; + }; + auto const long_slot = std::string(256U, 's'); + auto const cases = std::vector{ + {"[]", "M_BAD_JSON" }, + {"\"text\"", "M_BAD_JSON" }, + {R"({"room_id":")" + room + R"(","slot_id":"s","member_id":"m"})", "M_MISSING_PARAM"}, + {R"({"url":"wss://sfu.example.org","slot_id":"s","member_id":"m"})", "M_MISSING_PARAM"}, + {R"({"url":"wss://sfu.example.org","room_id":")" + room + R"(","member_id":"m"})", "M_MISSING_PARAM"}, + {R"({"url":"wss://sfu.example.org","room_id":")" + room + R"(","slot_id":"s"})", "M_MISSING_PARAM"}, + {R"({"url":7,"room_id":")" + room + R"(","slot_id":"s","member_id":"m"})", "M_INVALID_PARAM"}, + {R"({"url":"wss://sfu.example.org","room_id":")" + room + R"(","slot_id":"","member_id":"m"})", + "M_INVALID_PARAM" }, + {R"({"url":"wss://sfu.example.org","room_id":")" + room + R"(","slot_id":")" + long_slot + + R"(","member_id":"m"})", "M_INVALID_PARAM"}, + {R"({"url":"wss://sfu.example.org","room_id":"#alias:example.org","slot_id":"s","member_id":"m"})", + "M_INVALID_PARAM" }, + {R"({"url":"wss://sfu.example.org","room_id":")" + room + R"(","slot_id":"s","member_id":["m"]})", + "M_INVALID_PARAM" }, + {R"({"url":"wss://sfu.example.org","room_id":")" + room + + R"(","slot_id":"s","member_id":"m","server_name":"not a name"})", "M_INVALID_PARAM"}, + {R"({"url":"wss://sfu.example.org","room_id":")" + room + + R"(","slot_id":"s","member_id":"m","server_name":5})", "M_INVALID_PARAM"}, + }; + + WHEN("each malformed body is sent") + { + THEN("each is a 400 with its errcode, and LiveKit is never called") + { + for (auto const& item : cases) + { + INFO(item.body); + auto const answer = + request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, item.body); + CHECK(answer.status == 400U); + CHECK(errcode_of(answer) == item.errcode); + } + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("server_name is absent, which asks for this server's SFU") + { + auto const answer = request(fixture.runtime(), "POST", std::string{unstable_path}, fixture.alice_token, + R"({"url":"wss://sfu.example.org","room_id":")" + room + + R"(","slot_id":"m.call#ROOM","member_id":"m"})"); + + THEN("a token is issued for the room the legacy slot shares with m.call#room") + { + REQUIRE(answer.status == 200U); + REQUIRE(fixture.mock().requests.size() == 1U); + auto const room_name = hs::livekit_room_name(room, "m.call#room"); + REQUIRE(room_name.has_value()); + CHECK(fixture.mock().requests.front().body.find(*room_name) != std::string::npos); + } + } + } +} + +SCENARIO("No token is issued when LiveKit, the secret or the outbound budget fails", + "[homeserver][livekit][rtc][negative]") +{ + GIVEN("alice in a room") + { + WHEN("LiveKit cannot be reached, or refuses CreateRoom") + { + auto fixture = LiveKitFixture{}; + auto const reachable = GENERATE(false, true); + fixture.mock().reachable = reachable; + fixture.mock().status = 401U; + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + token_body(fixture.room_id)); + + THEN("the answer is 502 with no token") + { + CHECK(answer.status == 502U); + CHECK(errcode_of(answer) == "M_UNKNOWN"); + CHECK(answer.body.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.size() == 1U); + } + } + + WHEN("every client outbound slot is taken") + { + auto fixture = LiveKitFixture{}; + fixture.runtime().homeserver.client_outbound_proxy_policy.global_cap = 1U; + auto const held = hs::admit_client_outbound_proxy(fixture.runtime().homeserver, "another-client"); + REQUIRE(held.has_value()); + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + token_body(fixture.room_id)); + + THEN("the answer is 429 with retry_after_ms, before LiveKit is called") + { + CHECK(answer.status == 429U); + CHECK(errcode_of(answer) == "M_LIMIT_EXCEEDED"); + auto const body = parse_object(answer.body); + CHECK(int_member(body, "retry_after_ms") != nullptr); + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("the API secret file is missing, or holds a secret shorter than 32 bytes") + { + auto const short_secret = SecretFile{"0123456789abcdef0123456789abcde"}; + auto const missing = GENERATE(false, true); + auto fixture = + LiveKitFixture{missing ? std::string{"/nonexistent/merovingian-livekit-secret"} : short_secret.path()}; + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + token_body(fixture.room_id)); + + THEN("the answer is 500 with no token, and LiveKit is never called") + { + CHECK(answer.status == 500U); + CHECK(errcode_of(answer) == "M_UNKNOWN"); + CHECK(answer.body.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + } + } + } +} + +SCENARIO("get_token is for active accounts with an access token", "[homeserver][livekit][rtc][negative]") +{ + GIVEN("alice in a room") + { + auto fixture = LiveKitFixture{}; + + WHEN("the request has no access token") + { + auto const answer = + request(fixture.runtime(), "POST", std::string{stable_path}, {}, token_body(fixture.room_id)); + + THEN("it is 401 M_MISSING_TOKEN") + { + CHECK(answer.status == 401U); + CHECK(errcode_of(answer) == "M_MISSING_TOKEN"); + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("alice is suspended, or locked") + { + auto const locked = GENERATE(false, true); + auto& homeserver = fixture.runtime().homeserver; + REQUIRE(hs::bootstrap_admin_user(homeserver, "admin", std::string{password}).ok); + REQUIRE(hs::set_local_user_moderation(homeserver, "@admin:example.org", "@alice:example.org", !locked, + locked, "t", "t") + .ok); + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + token_body(fixture.room_id)); + + THEN("the moderation gate refuses it and no token is issued") + { + CHECK(answer.status == (locked ? 401U : 403U)); + CHECK(errcode_of(answer) == (locked ? "M_USER_LOCKED" : "M_USER_SUSPENDED")); + CHECK(fixture.mock().requests.empty()); + } + } + } +} + +SCENARIO("The routes, /versions and the transports say the same thing", "[homeserver][livekit][rtc][client-server]") +{ + GIVEN("a server with the built-in service") + { + auto fixture = LiveKitFixture{}; + + WHEN("a client reads /versions and both transport routes") + { + auto const versions = request(fixture.runtime(), "GET", "/_matrix/client/versions", {}, {}); + auto const stable = + request(fixture.runtime(), "GET", "/_matrix/client/v1/rtc/transports", fixture.alice_token, {}); + auto const unstable = + request(fixture.runtime(), "GET", "/_matrix/client/unstable/org.matrix.msc4143/rtc/transports", + fixture.alice_token, {}); + + THEN("both MSC4195 flags are true and the SFU is advertised by its url") + { + REQUIRE(versions.status == 200U); + auto const body = parse_object(versions.body); + auto const* features = object_member_as_object(body, "unstable_features"); + REQUIRE(features != nullptr); + auto const* flag = bool_member(*features, "org.matrix.msc4195"); + auto const* stable_flag = bool_member(*features, "org.matrix.msc4195.stable"); + REQUIRE((flag != nullptr && stable_flag != nullptr)); + CHECK((*flag && *stable_flag)); + CHECK(stable.status == 200U); + CHECK(stable.body == R"({"transports":[{"type":"livekit","url":"wss://sfu.example.org"},)" + R"({"type":"m.livekit","url":"wss://sfu.example.org"}]})"); + CHECK(unstable.status == 200U); + CHECK(unstable.body == R"({"rtc_transports":[{"type":"livekit","url":"wss://sfu.example.org"}]})"); + } + } + } + + GIVEN("a server without it") + { + auto started = hs::start_client_server(livekit_config({})); + REQUIRE(started.started); + auto const mock = std::make_shared(); + install_mock(started.runtime, mock); + auto const token = login(started.runtime, "alice"); + + WHEN("a client asks for a token on either path, and reads /versions") + { + auto const versions = request(started.runtime, "GET", "/_matrix/client/versions", {}, {}); + + THEN("each path is 404 M_UNRECOGNIZED and both flags are false") + { + for (auto const path : {stable_path, unstable_path}) + { + auto const answer = + request(started.runtime, "POST", std::string{path}, token, token_body("!room:example.org")); + CHECK(answer.status == 404U); + CHECK(errcode_of(answer) == "M_UNRECOGNIZED"); + } + REQUIRE(versions.status == 200U); + auto const body = parse_object(versions.body); + auto const* features = object_member_as_object(body, "unstable_features"); + REQUIRE(features != nullptr); + auto const* flag = bool_member(*features, "org.matrix.msc4195"); + auto const* stable_flag = bool_member(*features, "org.matrix.msc4195.stable"); + REQUIRE((flag != nullptr && stable_flag != nullptr)); + CHECK_FALSE(*flag); + CHECK_FALSE(*stable_flag); + CHECK(mock->requests.empty()); + } + } + } +} + +SCENARIO("The livekit log names the user and room and never the token, the secret or the member", + "[homeserver][livekit][rtc][logging]") +{ + GIVEN("alice in a room") + { + auto fixture = LiveKitFixture{}; + + WHEN("a token is issued and one refused, with the log captured") + { + auto const capture = ConsoleLogCapture{}; + auto const issued = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + token_body(fixture.room_id, sfu_url, "SECRETDEVICE_member")); + auto const refused = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.bob_token, + token_body(fixture.room_id, sfu_url, "SECRETDEVICE_member")); + auto const text = capture.text(); + + THEN("the events are there, with no jwt, secret or member ID") + { + REQUIRE(issued.status == 200U); + REQUIRE(refused.status == 403U); + auto const body = parse_object(issued.body); + auto const* jwt = string_member(body, "jwt"); + REQUIRE(jwt != nullptr); + CHECK(text.find("livekit.token.issued") != std::string::npos); + CHECK(text.find("livekit.token.refused") != std::string::npos); + CHECK(text.find(*jwt) == std::string::npos); + CHECK(text.find(api_secret) == std::string::npos); + CHECK(text.find("SECRETDEVICE") == std::string::npos); + CHECK(text.find("m.call#room") == std::string::npos); + } + } + } +} + +SCENARIO("A federated request gets a subscribe-only token for a user of the origin joined here", + "[homeserver][livekit][rtc][federation]") +{ + GIVEN("alice's room, which carol of remote.example.org has joined") + { + auto fixture = LiveKitFixture{}; + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + + WHEN("remote.example.org asks for a token for carol") + { + auto const answer = federated(fixture.runtime(), remote_server, federation_body(fixture.room_id, carol)); + + THEN("the token is carol's, for the MSC4195 names, and may subscribe but not publish") + { + REQUIRE(answer.ok); + REQUIRE(answer.status == 200U); + auto const body = parse_object(answer.value); + REQUIRE(body.size() == 1U); + auto const* jwt = string_member(body, "jwt"); + REQUIRE(jwt != nullptr); + auto const payload = verified_payload(*jwt); + auto const identity = hs::livekit_participant_identity(carol, "DEVICEID_member"); + auto const room_name = hs::livekit_room_name(fixture.room_id, "m.call#room"); + REQUIRE((identity.has_value() && room_name.has_value())); + auto const* sub = string_member(payload, "sub"); + REQUIRE(sub != nullptr); + CHECK(*sub == *identity); + auto const* video = object_member_as_object(payload, "video"); + REQUIRE(video != nullptr); + auto const* room = string_member(*video, "room"); + REQUIRE(room != nullptr); + CHECK(*room == *room_name); + auto const* join = bool_member(*video, "roomJoin"); + auto const* publish = bool_member(*video, "canPublish"); + auto const* publish_data = bool_member(*video, "canPublishData"); + auto const* subscribe = bool_member(*video, "canSubscribe"); + REQUIRE((join != nullptr && publish != nullptr && publish_data != nullptr && subscribe != nullptr)); + CHECK(*join); + CHECK(*subscribe); + // Written as false, never left out: LiveKit reads an absent canPublish as true (ADR-0828). + CHECK_FALSE(*publish); + CHECK_FALSE(*publish_data); + CHECK(video->size() == 5U); + CHECK(answer.value.find("carol") == std::string::npos); + } + + THEN("LiveKit is not called on another server's behalf") + { + CHECK(fixture.mock().requests.empty()); + } + } + } +} + +SCENARIO("A federated request is refused unless this server's own state shows the user of the origin joined", + "[homeserver][livekit][rtc][federation][negative]") +{ + GIVEN("alice's room, which carol of remote.example.org has joined") + { + auto fixture = LiveKitFixture{}; + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + auto const joined = federated(fixture.runtime(), remote_server, federation_body(fixture.room_id, carol)); + REQUIRE(joined.status == 200U); + + WHEN("the user is not of the origin, is not joined, or the room is not one this server is in") + { + auto const other_origin = + federated(fixture.runtime(), "other.example.net", federation_body(fixture.room_id, carol)); + auto const not_joined = federated(fixture.runtime(), remote_server, + federation_body(fixture.room_id, "@dave:remote.example.org")); + auto const no_room = + federated(fixture.runtime(), remote_server, federation_body("!nosuchroom:example.org", carol)); + + THEN("each is one and the same 403 M_FORBIDDEN, and nothing is signed or called") + { + for (auto const* refused : {&other_origin, ¬_joined, &no_room}) + { + CHECK_FALSE(refused->ok); + CHECK(refused->status == 403U); + CHECK(refused->errcode == "M_FORBIDDEN"); + CHECK(refused->reason == other_origin.reason); + CHECK(refused->value.find("jwt") == std::string::npos); + } + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("carol leaves") + { + auto& store = fixture.runtime().homeserver.database.persistent_store; + auto const leave_id = std::string{"$leave-of-carol"}; + store.events.push_back({leave_id, + fixture.room_id, + std::string{carol}, + R"({"content":{"membership":"leave"},"type":"m.room.member"})", + 10U, + 0U, + {}, + {}, + {}}); + for (auto& row : store.state) + { + if (row.room_id == fixture.room_id && row.event_type == "m.room.member" && row.state_key == carol) + { + row.event_id = leave_id; + } + } + auto const left = federated(fixture.runtime(), remote_server, federation_body(fixture.room_id, carol)); + + THEN("she is refused like a user never joined") + { + CHECK(left.status == 403U); + CHECK(left.errcode == "M_FORBIDDEN"); + } + } + + WHEN("the url is not this server's SFU, or the body is malformed") + { + auto const wrong_url = federated(fixture.runtime(), remote_server, + federation_body(fixture.room_id, carol, "wss://sfu.remote.example.org")); + auto const other_server_name = federated( + fixture.runtime(), remote_server, + R"({"url":"wss://sfu.example.org","room_id":")" + fixture.room_id + + R"(","slot_id":"m.call#room","member_id":"m","user_id":"@carol:remote.example.org","server_name":"remote.example.org"})"); + auto const no_user = federated(fixture.runtime(), remote_server, + R"({"url":"wss://sfu.example.org","room_id":")" + fixture.room_id + + R"(","slot_id":"m.call#room","member_id":"m"})"); + auto const bad_user = + federated(fixture.runtime(), remote_server, federation_body(fixture.room_id, "carol")); + auto const not_json = federated(fixture.runtime(), remote_server, "[]"); + + THEN("each is a 400, and no token is issued") + { + CHECK(wrong_url.status == 400U); + CHECK(wrong_url.errcode == "M_INVALID_PARAM"); + for (auto const* refused : {&other_server_name, &no_user, &bad_user, ¬_json}) + { + CHECK(refused->status == 400U); + CHECK(refused->value.find("jwt") == std::string::npos); + } + CHECK(fixture.mock().requests.empty()); + } + } + } + + GIVEN("a server with no token service") + { + auto started = hs::start_client_server(livekit_config({})); + REQUIRE(started.started); + + WHEN("a federated request arrives") + { + auto const answer = federated(started.runtime, remote_server, federation_body("!room:example.org", carol)); + + THEN("it is 404 M_UNRECOGNIZED") + { + CHECK(answer.status == 404U); + CHECK(answer.errcode == "M_UNRECOGNIZED"); + } + } + } +} + +SCENARIO("A token for another server's SFU is relayed to that server, and only its jwt is passed on", + "[homeserver][livekit][rtc][federation][relay]") +{ + GIVEN("alice's room, which carol of remote.example.org has joined, and remote.example.org issuing a token") + { + auto fixture = LiveKitFixture{}; + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + auto remote = RemoteTokenServer{fixture.runtime(), + tls_mock::json_http_response("200 OK", R"({"jwt":"aGVhZA.Ym9keQ.c2ln"})")}; + + WHEN("alice asks for a token for remote.example.org's SFU") + { + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + relay_body(fixture.room_id)); + auto const& seen = remote.finish(); + + THEN("she gets the other server's jwt and nothing else") + { + REQUIRE(answer.status == 200U); + auto const body = parse_object(answer.body); + REQUIRE(body.size() == 1U); + auto const* jwt = string_member(body, "jwt"); + REQUIRE(jwt != nullptr); + CHECK(*jwt == "aGVhZA.Ym9keQ.c2ln"); + } + + THEN("the request went signed to the stable federation path, naming alice and no server_name") + { + CHECK(seen.starts_with("POST /_matrix/federation/v1/rtc/livekit/get_token HTTP/1.1\r\n")); + CHECK(seen.find("X-Matrix origin=\"example.org\"") != std::string::npos); + auto const body_start = seen.find("\r\n\r\n"); + REQUIRE(body_start != std::string::npos); + CHECK( + seen.substr(body_start + 4U) == + R"({"member_id":"DEVICEID_member","room_id":")" + fixture.room_id + + R"(","slot_id":"m.call#room","url":"wss://sfu.remote.example.org","user_id":"@alice:example.org"})"); + CHECK(fixture.mock().requests.empty()); + } + } + } + + GIVEN("remote.example.org answering get_token with a refusal, an error or a malformed jwt") + { + struct Case final + { + std::string response; + std::uint16_t status; + std::string errcode; + }; + auto const scenario = GENERATE( + Case{tls_mock::json_http_response("403 Forbidden", + R"({"errcode":"M_FORBIDDEN","error":"room secret-detail"})"), + 403U, "M_FORBIDDEN"}, + Case{tls_mock::json_http_response("400 Bad Request", + R"({"errcode":"M_INVALID_PARAM","error":"url secret-detail"})"), + 400U, "M_INVALID_PARAM"}, + Case{tls_mock::json_http_response("403 Forbidden", R"({"errcode":"M_LIMIT_EXCEEDED","error":"x"})"), 502U, + "M_UNKNOWN"}, + Case{tls_mock::json_http_response("404 Not Found", R"({"errcode":"M_UNRECOGNIZED","error":"x"})"), 502U, + "M_UNKNOWN"}, + Case{tls_mock::json_http_response("500 Internal Server Error", R"({"errcode":"M_UNKNOWN","error":"x"})"), + 502U, "M_UNKNOWN"}, + Case{tls_mock::json_http_response("200 OK", R"({"jwt":"not a token"})"), 502U, "M_UNKNOWN"}, + Case{tls_mock::json_http_response("200 OK", R"({"jwt":"a..c"})"), 502U, "M_UNKNOWN"}, + Case{tls_mock::json_http_response("200 OK", R"({"token":"aGVhZA.Ym9keQ.c2ln"})"), 502U, "M_UNKNOWN"}); + auto fixture = LiveKitFixture{}; + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + auto remote = RemoteTokenServer{fixture.runtime(), scenario.response}; + + WHEN("alice asks for a token for its SFU") + { + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + relay_body(fixture.room_id)); + std::ignore = remote.finish(); + + THEN("403 and 400 are passed on in this server's words, and anything else is 502 M_UNKNOWN") + { + CHECK(answer.status == scenario.status); + CHECK(errcode_of(answer) == scenario.errcode); + CHECK(answer.body.find("secret-detail") == std::string::npos); + CHECK(answer.body.find("jwt") == std::string::npos); + CHECK(fixture.runtime().homeserver.client_outbound_budget->active() == 0U); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index 74aa7cec4..6f0129064 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -416,6 +416,7 @@ shell = find_program('sh') 'unit/test_file_descriptor.cpp', 'unit/test_file_metadata.cpp', 'unit/test_secure_secret_loading.cpp', + 'unit/test_livekit_names.cpp', 'unit/test_turn_shared_secret.cpp', 'unit/test_elf_probe.cpp', 'unit/test_email.cpp', @@ -727,6 +728,7 @@ shell = find_program('sh') 'conformance/test_profile_unset_fields_conformance.cpp', 'conformance/test_route_query_conformance.cpp', 'conformance/test_key_publication_conformance.cpp', + 'conformance/test_livekit_token_conformance.cpp', 'conformance/test_membership_projection_conformance.cpp', 'conformance/test_pdu_format_conformance.cpp', 'conformance/test_pdu_ingestion_conformance.cpp', @@ -1010,6 +1012,7 @@ shell = find_program('sh') 'integration/test_stored_invite_caps_flow.cpp', 'integration/test_delayed_events_flow.cpp', 'integration/test_delayed_events_routes_flow.cpp', + 'integration/test_livekit_token_flow.cpp', 'integration/test_security_issues_460_463_flow.cpp', 'integration/test_server_signing_key_lifecycle_flow.cpp', 'integration/test_sync_dag_gap_flow.cpp', diff --git a/tests/unit/test_config_rtc.cpp b/tests/unit/test_config_rtc.cpp index dccb8374f..0c91ae8d0 100644 --- a/tests/unit/test_config_rtc.cpp +++ b/tests/unit/test_config_rtc.cpp @@ -179,3 +179,235 @@ SCENARIO("server.rtc.livekit.service_url is reloadable and diffed by the reload } } } + +namespace +{ + +constexpr auto token_service_keys = std::string_view{"server.rtc.livekit.url=wss://sfu.example.org\n" + "server.rtc.livekit.api_url=https://sfu.example.org\n" + "server.rtc.livekit.api_key=APIkey_1\n" + "server.rtc.livekit.api_secret_file=/etc/merovingian/livekit\n"}; + +[[nodiscard]] auto parse_token_service(std::string const& extra) -> merovingian::config::ConfigParseResult +{ + return merovingian::config::parse_key_value_config(std::string{token_service_keys} + extra); +} + +[[nodiscard]] auto with_value(std::string_view key, std::string const& value) -> merovingian::config::ConfigParseResult +{ + auto text = std::string{token_service_keys}; + auto const start = text.find(std::string{key} + "="); + REQUIRE(start != std::string::npos); + auto const end = text.find('\n', start); + text.replace(start, end - start, std::string{key} + "=" + value); + return merovingian::config::parse_key_value_config(text); +} + +[[nodiscard]] auto plan_names(merovingian::config::ReloadPlan const& plan, std::string const& key) -> bool +{ + for (auto const& change : plan.changes()) + { + if (change.key == key) + { + return true; + } + } + return false; +} + +} // namespace + +SCENARIO("The built-in LiveKit token service is configured by four keys together", "[config][rtc][livekit]") +{ + GIVEN("the four keys with valid values and no lifetime") + { + WHEN("they are parsed and validated") + { + auto const parsed = parse_token_service(""); + auto const findings = merovingian::config::validate(parsed.config); + auto const& service = parsed.config.server().rtc.token_service; + + THEN("they are kept as written, the lifetime is one hour, and nothing is reported") + { + CHECK(parsed.findings.empty()); + CHECK(findings.empty()); + CHECK(service.url == "wss://sfu.example.org"); + CHECK(service.api_url == "https://sfu.example.org"); + CHECK(service.api_key == "APIkey_1"); + CHECK(service.api_secret_file == "/etc/merovingian/livekit"); + CHECK(service.token_lifetime_seconds == 3600U); + } + } + } + + GIVEN("a configuration that does not mention them") + { + WHEN("it is validated") + { + auto const parsed = merovingian::config::parse_key_value_config(""); + + THEN("the service is off and nothing is reported") + { + CHECK(parsed.config.server().rtc.token_service.url.empty()); + CHECK(merovingian::config::is_valid(parsed.config)); + } + } + } + + GIVEN("each key alone") + { + auto const keys = std::vector{ + "server.rtc.livekit.url=wss://sfu.example.org", "server.rtc.livekit.api_url=https://sfu.example.org", + "server.rtc.livekit.api_key=APIkey_1", "server.rtc.livekit.api_secret_file=/etc/merovingian/livekit"}; + + WHEN("each is validated without the other three") + { + THEN("each is refused, with a finding on every missing key") + { + for (auto const& line : keys) + { + INFO(line); + auto const parsed = merovingian::config::parse_key_value_config(line + "\n"); + auto const findings = merovingian::config::validate(parsed.config); + CHECK_FALSE(merovingian::config::is_valid(parsed.config)); + auto missing = std::size_t{0U}; + for (auto const& finding : findings) + { + missing += finding.message.find("together") != std::string::npos ? 1U : 0U; + } + CHECK(missing == 3U); + } + } + } + } + + GIVEN("the four keys and the external service URL") + { + WHEN("they are validated") + { + auto const parsed = parse_token_service("server.rtc.livekit.service_url=https://jwt.example.org\n"); + auto const findings = merovingian::config::validate(parsed.config); + + THEN("the combination is refused on the service URL") + { + CHECK(has_finding(findings, "server.rtc.livekit.service_url")); + CHECK_FALSE(merovingian::config::is_valid(parsed.config)); + } + } + } +} + +SCENARIO("The built-in token service refuses a value it cannot use, and never repairs it", + "[config][rtc][livekit][negative]") +{ + GIVEN("acceptable and unacceptable values for each key") + { + struct Case + { + std::string_view key; + std::string value; + bool accepted; + }; + auto const cases = std::vector{ + {"server.rtc.livekit.url", "wss://sfu.example.org:7880", true}, + {"server.rtc.livekit.url", "wss://sfu.example.org/livekit", true}, + {"server.rtc.livekit.url", "ws://sfu.example.org", false}, + {"server.rtc.livekit.url", "https://sfu.example.org", false}, + {"server.rtc.livekit.url", "wss://sfu.example.org/", false}, + {"server.rtc.livekit.url", "wss://sfu.example.org?a=1", false}, + {"server.rtc.livekit.url", "wss://user@sfu.example.org", false}, + {"server.rtc.livekit.url", "wss://sfu.example.org/#x", false}, + {"server.rtc.livekit.url", "wss://", false}, + {"server.rtc.livekit.url", "wss://sfu.example.org/" + std::string(2100U, 'a'), false}, + {"server.rtc.livekit.api_url", "https://sfu.example.org:7880", true}, + {"server.rtc.livekit.api_url", "http://127.0.0.1:7880", true}, + {"server.rtc.livekit.api_url", "http://[::1]:7880", true}, + {"server.rtc.livekit.api_url", "http://sfu.example.org:7880", false}, + {"server.rtc.livekit.api_url", "http://10.0.0.5:7880", false}, + {"server.rtc.livekit.api_url", "http://localhost:7880", false}, + {"server.rtc.livekit.api_url", "wss://sfu.example.org", false}, + {"server.rtc.livekit.api_url", "https://sfu.example.org/", false}, + {"server.rtc.livekit.api_url", "https://sfu.example.org/?x", false}, + {"server.rtc.livekit.api_key", "API.key-1_x", true}, + {"server.rtc.livekit.api_key", std::string(128U, 'k'), true}, + {"server.rtc.livekit.api_key", std::string(129U, 'k'), false}, + {"server.rtc.livekit.api_key", "key with space", false}, + {"server.rtc.livekit.api_key", "key\"quote", false}, + {"server.rtc.livekit.api_key", "k\xC3\xA9y", false}, + }; + + WHEN("each is put in an otherwise valid configuration") + { + THEN("only the acceptable ones pass, and a refusal names the key") + { + for (auto const& entry : cases) + { + INFO(std::string{entry.key} + "=" + entry.value.substr(0U, 60U)); + auto const parsed = with_value(entry.key, entry.value); + auto const findings = merovingian::config::validate(parsed.config); + CHECK((has_finding(findings, entry.key) || has_finding(parsed.findings, entry.key)) == + !entry.accepted); + CHECK(merovingian::config::is_valid(parsed.config) == entry.accepted); + } + } + } + } + + GIVEN("token lifetimes at and beyond the bounds") + { + WHEN("each is parsed and validated") + { + auto const at_low = parse_token_service("server.rtc.livekit.token_lifetime=60s\n"); + auto const at_high = parse_token_service("server.rtc.livekit.token_lifetime=60m\n"); + auto const below = parse_token_service("server.rtc.livekit.token_lifetime=59s\n"); + auto const above = parse_token_service("server.rtc.livekit.token_lifetime=3601s\n"); + auto const zero = parse_token_service("server.rtc.livekit.token_lifetime=0s\n"); + auto const garbage = parse_token_service("server.rtc.livekit.token_lifetime=1h\n"); + + THEN("60s and 60m pass and everything else is refused") + { + CHECK(merovingian::config::is_valid(at_low.config)); + CHECK(at_low.config.server().rtc.token_service.token_lifetime_seconds == 60U); + CHECK(merovingian::config::is_valid(at_high.config)); + CHECK(at_high.config.server().rtc.token_service.token_lifetime_seconds == 3600U); + CHECK(has_finding(merovingian::config::validate(below.config), "server.rtc.livekit.token_lifetime")); + CHECK(has_finding(merovingian::config::validate(above.config), "server.rtc.livekit.token_lifetime")); + CHECK(has_finding(zero.findings, "server.rtc.livekit.token_lifetime")); + CHECK(has_finding(garbage.findings, "server.rtc.livekit.token_lifetime")); + } + } + } +} + +SCENARIO("Every built-in token service key needs a restart", "[config][rtc][livekit]") +{ + GIVEN("two configurations that differ in every token service key") + { + auto const before = parse_token_service(""); + auto const after = + merovingian::config::parse_key_value_config("server.rtc.livekit.url=wss://sfu2.example.org\n" + "server.rtc.livekit.api_url=https://sfu2.example.org\n" + "server.rtc.livekit.api_key=APIkey_2\n" + "server.rtc.livekit.api_secret_file=/etc/merovingian/livekit2\n" + "server.rtc.livekit.token_lifetime=10m\n"); + + WHEN("a reload is planned") + { + auto const plan = merovingian::config::build_reload_plan(before.config, after.config); + + THEN("each key is named and each needs a restart") + { + auto const keys = std::vector{ + "server.rtc.livekit.url", "server.rtc.livekit.api_url", "server.rtc.livekit.api_key", + "server.rtc.livekit.api_secret_file", "server.rtc.livekit.token_lifetime"}; + for (auto const& key : keys) + { + INFO(key); + CHECK(plan_names(plan, key)); + CHECK(merovingian::config::reload_policy_for_key(key) == + merovingian::config::ReloadPolicy::restart_required); + } + } + } + } +} diff --git a/tests/unit/test_livekit_names.cpp b/tests/unit/test_livekit_names.cpp new file mode 100644 index 000000000..bf85b8601 --- /dev/null +++ b/tests/unit/test_livekit_names.cpp @@ -0,0 +1,94 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// The LiveKit room name and participant identity MSC4195 derives (ADR-0829). The first two vectors are the MSC's own; +// the rest were computed apart from this code with Python's `json` and `hashlib`. + +#include "merovingian/crypto/LiveKitToken.hpp" +#include "merovingian/homeserver/LiveKitNames.hpp" + +#include + +#include + +SCENARIO("The LiveKit names match MSC4195's vectors", "[homeserver][livekit][rtc]") +{ + GIVEN("the MSC's room and slot, and its user and member") + { + WHEN("the room name and identity are derived") + { + auto const room = merovingian::homeserver::livekit_room_name("!roomid:example.com", "slot1234"); + auto const identity = + merovingian::homeserver::livekit_participant_identity("@alice:example.com", "memberABC"); + + THEN("they are the MSC's values, and a valid LiveKit name each") + { + REQUIRE(room.has_value()); + REQUIRE(identity.has_value()); + CHECK(*room == "O8437W3+jmzMVjoIP3tNwbm+XxHQk2iKpOA7aqw3qSc"); + CHECK(*identity == "M3VnsLXrkbxIDINXO64u8PZzFyD9ZYFiQULR2dshWYs"); + CHECK(merovingian::crypto::livekit_name_is_valid(*room)); + CHECK(merovingian::crypto::livekit_name_is_valid(*identity)); + } + } + } +} + +SCENARIO("The legacy call slot names the same LiveKit room as the stable one", "[homeserver][livekit][rtc]") +{ + GIVEN("one room and the two spellings of the call slot") + { + WHEN("both room names are derived") + { + auto const stable = merovingian::homeserver::livekit_room_name("!roomid:example.com", "m.call#room"); + auto const legacy = merovingian::homeserver::livekit_room_name("!roomid:example.com", "m.call#ROOM"); + auto const other = merovingian::homeserver::livekit_room_name("!roomid:example.com", "m.call#Room"); + + THEN("both are the hash of the stable slot, and no other spelling is folded") + { + REQUIRE(stable.has_value()); + REQUIRE(legacy.has_value()); + REQUIRE(other.has_value()); + CHECK(*stable == "2EPGhjulIGe4Sqyrrzv9fQuklBFly+CBIEYlCRUmJ5E"); + CHECK(*legacy == *stable); + CHECK(*other != *stable); + } + } + } +} + +SCENARIO("The LiveKit names hash canonical JSON, escapes and non-ASCII included", "[homeserver][livekit][rtc]") +{ + GIVEN("member IDs with non-ASCII and with characters JSON escapes") + { + WHEN("the identities are derived") + { + auto const accented = + merovingian::homeserver::livekit_participant_identity("@alice:example.com", "caf\xC3\xA9\xE2\x98\x83"); + auto const escaped = + merovingian::homeserver::livekit_participant_identity("@alice:example.com", "a\"b\\c\nd"); + + THEN("each is the independently computed hash") + { + REQUIRE(accented.has_value()); + REQUIRE(escaped.has_value()); + CHECK(*accented == "TMP0XlNvSwylAPHKC8kFbPdxQaz1HyqWuO6pX7ilfhI"); + CHECK(*escaped == "FXIBqDUROwH93ach69WuL2jLRKoQq47pNLYhXP16hMs"); + } + } + } + + GIVEN("a member ID that is not valid UTF-8") + { + WHEN("an identity is derived") + { + auto const identity = + merovingian::homeserver::livekit_participant_identity("@alice:example.com", std::string{"\xC3"}); + + THEN("there is none") + { + CHECK_FALSE(identity.has_value()); + } + } + } +} From eef0fa6fd0cf3cde0496808c593b99ac40a041f6 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 12:56:09 +0000 Subject: [PATCH 06/19] Classify the LiveKit token relay in the outbound answer trust table The relay of get_token to another server is a perform_outbound_call caller, so ADR-0349's table and test_outbound_answer_trust.py name it: unverified, over main's own client. Also wrap a changelog bullet line that ran to 121 characters. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 +- ...swer-main-does-not-verify-comes-over-mains-own-connection.md | 1 + tests/tooling/test_outbound_answer_trust.py | 1 + 3 files changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ebf96533..df917e127 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,7 +8,7 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Features * MatrixRTC calls on LiveKit need no `lk-jwt-service`: `POST .../rtc/livekit/get_token` (MSC4195) issues tokens to - joined users, and `server.rtc.livekit.url`, `api_url`, `api_key` and `api_secret_file` turn it on (ADR-0829, ADR-0830). + joined users; `server.rtc.livekit.url`, `api_url`, `api_key` and `api_secret_file` turn it on (ADR-0829, ADR-0830). ## Security Fixes diff --git a/docs/adr/0349-an-outbound-answer-main-does-not-verify-comes-over-mains-own-connection.md b/docs/adr/0349-an-outbound-answer-main-does-not-verify-comes-over-mains-own-connection.md index 5b9dc82aa..d161b0391 100644 --- a/docs/adr/0349-an-outbound-answer-main-does-not-verify-comes-over-mains-own-connection.md +++ b/docs/adr/0349-an-outbound-answer-main-does-not-verify-comes-over-mains-own-connection.md @@ -65,6 +65,7 @@ signed material. | `federation.backfill.state_ids_failed` | the IDs name the state a later event is judged against | no (the PDUs they lead to are verified, the choice of IDs is not) | direct | | `timestamp_to_event.ask` | the event ID and timestamp decide which event is offered | no (the event is verified, the choice is not) | direct | | `space_hierarchy.fetch` | room summaries shown to the client | no | direct | +| `livekit.relay` | relays a LiveKit token and SFU URL from the server the client named; a 403/400 is relayed | no | direct | | `room.join.remote.make_join_failed` | keeps the template's `prev_events`, `auth_events`, `depth`, content | no | direct | | `room.join.remote.send_join_failed` | state and auth chain, and the status | per event only | direct | | `room.leave.remote.make_leave_failed` | template; a 403/404 ends an invite locally | no | direct | diff --git a/tests/tooling/test_outbound_answer_trust.py b/tests/tooling/test_outbound_answer_trust.py index b3ea88f1c..d7dfb2d25 100644 --- a/tests/tooling/test_outbound_answer_trust.py +++ b/tests/tooling/test_outbound_answer_trust.py @@ -51,6 +51,7 @@ "federation.backfill.state_ids_failed", "timestamp_to_event.ask", "space_hierarchy.fetch", + "livekit.relay", "room.join.remote.make_join_failed", "room.join.remote.send_join_failed", "room.leave.remote.make_leave_failed", From dcd9d66900f9e9060d8da09467e29f5780f1032b Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 13:45:34 +0000 Subject: [PATCH 07/19] Relay the inbound federation LiveKit token route through the worker relay (ADR-0831, ADR-0595) Co-Authored-By: Claude Sonnet 5.5 --- .../federation/FederationEndpoint.hpp | 1 + .../federation/FederationRuntimeState.hpp | 3 + .../federation/InboundRequestProviders.hpp | 7 + .../merovingian/federation/Transactions.hpp | 2 +- .../federation/WorkerRelayKind.hpp | 4 + .../federation_worker/WorkerRelayFrame.hpp | 21 +-- include/merovingian/homeserver/WorkerPool.hpp | 9 ++ src/federation/InboundRequest.cpp | 13 ++ src/federation/Transactions.cpp | 7 + src/federation/WorkerRelayBinding.cpp | 5 + src/federation_worker/WorkerEventLoop.cpp | 29 +++++ src/federation_worker/WorkerRelayFrame.cpp | 21 ++- src/homeserver/LocalHttpRouter.cpp | 17 +++ src/homeserver/WorkerPool.cpp | 58 +++++++++ .../test_federation_worker_flow.cpp | 121 ++++++++++++++++++ tests/support/EduRelayContext.hpp | 11 ++ .../unit/test_federation_inbound_request.cpp | 56 ++++++++ tests/unit/test_federation_transactions.cpp | 2 + tests/unit/test_worker_relay_binding.cpp | 38 ++++++ tests/unit/test_worker_relay_frame.cpp | 43 +++++++ 20 files changed, 455 insertions(+), 13 deletions(-) diff --git a/include/merovingian/federation/FederationEndpoint.hpp b/include/merovingian/federation/FederationEndpoint.hpp index 1d3b04090..90b57b8d7 100644 --- a/include/merovingian/federation/FederationEndpoint.hpp +++ b/include/merovingian/federation/FederationEndpoint.hpp @@ -33,6 +33,7 @@ enum class FederationEndpoint media_download, media_thumbnail, exchange_third_party_invite, + livekit_token, }; } // namespace merovingian::federation diff --git a/include/merovingian/federation/FederationRuntimeState.hpp b/include/merovingian/federation/FederationRuntimeState.hpp index 6333f78fe..8c3388212 100644 --- a/include/merovingian/federation/FederationRuntimeState.hpp +++ b/include/merovingian/federation/FederationRuntimeState.hpp @@ -111,6 +111,9 @@ struct FederationRuntimeState final DeviceKeysQueryProvider device_keys_query_provider{}; OneTimeKeysClaimProvider one_time_keys_claim_provider{}; UserDevicesProvider user_devices_provider{}; + // Mints a MatrixRTC LiveKit token for a verified origin (ADR-0831). Unset: the route answers 501. A worker's is + // a relay to main, which holds the LiveKit secret; a worker never reads that configuration. + LiveKitTokenProvider livekit_token_provider{}; // Optional resolvers for inbound event-graph queries. Each unset hook // makes its route respond 501 Not Implemented. EventQueryProvider event_query_provider{}; diff --git a/include/merovingian/federation/InboundRequestProviders.hpp b/include/merovingian/federation/InboundRequestProviders.hpp index 5b759a0ec..a14ea0609 100644 --- a/include/merovingian/federation/InboundRequestProviders.hpp +++ b/include/merovingian/federation/InboundRequestProviders.hpp @@ -6,6 +6,7 @@ #include "merovingian/federation/FederationDirectory.hpp" #include "merovingian/federation/FederationProfile.hpp" #include "merovingian/federation/FederationRemoteRuntime.hpp" +#include "merovingian/federation/FederationResponse.hpp" #include "merovingian/federation/FederationThumbnailQuery.hpp" #include "merovingian/federation/PublicRoomsRequest.hpp" #include "merovingian/federation/RoomReadResult.hpp" @@ -64,6 +65,12 @@ using DeviceKeysQueryProvider = std::function; using UserDevicesProvider = std::function; +// `POST /_matrix/federation/{v1,unstable/io.element.msc4195}/rtc/livekit/get_token` (ADR-0831). Takes the verified +// `origin` and the request body and returns the HTTP status and body to answer, a refusal included: the token +// service judges the request, the federation layer only carries it. Optional: an unset hook makes the route respond +// 501 Not Implemented. +using LiveKitTokenProvider = std::function; + // Inbound event-graph query hooks. Each takes the parsed path component (and // for `get_missing_events`, the request body) plus the X-Matrix-authenticated // `origin` of the requesting server, and returns a `RoomReadResult`: the diff --git a/include/merovingian/federation/Transactions.hpp b/include/merovingian/federation/Transactions.hpp index 5d0b52497..448fde999 100644 --- a/include/merovingian/federation/Transactions.hpp +++ b/include/merovingian/federation/Transactions.hpp @@ -24,7 +24,7 @@ inline constexpr auto max_federation_transaction_edus = std::uint32_t{100U}; // synchronous IPC round-trip back to main — pdu_sink/edu_sink (transaction), // membership_acceptor (send_join/send_leave/send_knock), invite_handler // (invite), or one of the query-provider relays (query_profile, query_directory, -// public_rooms, query_keys, claim_keys, query_user_devices, query_event). False for endpoints a worker +// public_rooms, query_keys, claim_keys, query_user_devices, query_event, livekit_token). False for endpoints a worker // answers entirely from its own local, room-scoped snapshot with no relay. // Used to route worker requests to a differently-sized thread pool so a // burst of slow relay calls cannot starve fast local ones of a thread to run diff --git a/include/merovingian/federation/WorkerRelayKind.hpp b/include/merovingian/federation/WorkerRelayKind.hpp index af100f851..9508ac9de 100644 --- a/include/merovingian/federation/WorkerRelayKind.hpp +++ b/include/merovingian/federation/WorkerRelayKind.hpp @@ -20,6 +20,10 @@ enum class WorkerRelayKind : std::uint8_t user_devices, // GET /query/profile. Argument: the percent-decoded `user_id` query parameter. profile_query, + // POST /rtc/livekit/get_token (ADR-0831): main mints a token with the LiveKit secret, which no worker holds. + // Argument: the request body. The relay frame also names the verified origin, which main checks against the + // pending request's. + livekit_token, }; } // namespace merovingian::federation diff --git a/include/merovingian/federation_worker/WorkerRelayFrame.hpp b/include/merovingian/federation_worker/WorkerRelayFrame.hpp index 3b88a7d12..a8d7758b7 100644 --- a/include/merovingian/federation_worker/WorkerRelayFrame.hpp +++ b/include/merovingian/federation_worker/WorkerRelayFrame.hpp @@ -24,16 +24,21 @@ namespace merovingian::federation_worker { // The frame asking main for a relay of `kind`: its type (`otk_claim_ingest`, `device_keys_query_ingest`, -// `user_devices_ingest`, `profile_query_ingest`), `parent_request_id`, and `argument` as `request_body` (claim and -// keys query) or `user_id` (device list and profile). nullopt when `parent_request_id` is 0: a worker serving no -// request main forwarded relays nothing, since main would refuse it. +// `user_devices_ingest`, `profile_query_ingest`, `livekit_token_ingest`), `parent_request_id`, and `argument` as +// `request_body` (claim, keys query and LiveKit token) or `user_id` (device list and profile). The LiveKit token frame +// also carries `origin`, the verified origin of the request main forwarded, which main compares with the pending +// request's; `origin` is ignored for every other kind. nullopt when `parent_request_id` is 0: a worker serving no +// request main forwarded relays nothing, since main would refuse it. nullopt too for a LiveKit token frame with an +// empty `origin`. [[nodiscard]] auto worker_relay_frame(federation::WorkerRelayKind kind, std::string_view argument, - std::uint64_t parent_request_id) -> std::optional; + std::uint64_t parent_request_id, std::string_view origin = {}) + -> std::optional; -// Sends worker_relay_frame(kind, argument, parent_request_id) to main over `channel` and returns main's reply frame. -// nullopt, with nothing sent, when there is no parent request; nullopt when main does not answer within `timeout`. +// Sends worker_relay_frame(kind, argument, parent_request_id, origin) to main over `channel` and returns main's reply +// frame. nullopt, with nothing sent, when there is no parent request; nullopt when main does not answer within +// `timeout`. [[nodiscard]] auto relay_to_main(ipc::IpcChannel& channel, federation::WorkerRelayKind kind, std::string_view argument, - std::uint64_t parent_request_id, std::chrono::seconds timeout) - -> std::optional; + std::uint64_t parent_request_id, std::chrono::seconds timeout, + std::string_view origin = {}) -> std::optional; } // namespace merovingian::federation_worker diff --git a/include/merovingian/homeserver/WorkerPool.hpp b/include/merovingian/homeserver/WorkerPool.hpp index 3f05e069f..2a3c1c4de 100644 --- a/include/merovingian/homeserver/WorkerPool.hpp +++ b/include/merovingian/homeserver/WorkerPool.hpp @@ -133,6 +133,15 @@ struct HomeserverRuntime; [[nodiscard]] auto handle_device_keys_query_ingest_request(HomeserverRuntime& runtime, std::string_view request_json, ipc::IpcChannel& receiving_channel) -> std::string; +// Handles a "livekit_token_ingest" IPC request (a worker relaying an inbound +// POST /_matrix/federation/v1/rtc/livekit/get_token, ADR-0831). The frame names the `origin` the worker's request +// was verified as; it is answered only when that origin is the pending request's AND the request's one permit over +// this body is unused (ADR-0595). Otherwise the reply carries status 403 and a standard `M_FORBIDDEN` body, and the +// token service is not reached. Reply: `{"type":"livekit_token_ingest_result","status":N,"response_body":"..."}`, +// a standard Matrix error body for a failure. +[[nodiscard]] auto handle_livekit_token_ingest_request(HomeserverRuntime& runtime, std::string_view request_json, + ipc::IpcChannel& receiving_channel) -> std::string; + // Handles a "profile_query_ingest" IPC request (a worker relaying an inbound // GET /_matrix/federation/v1/query/profile), for the same reason and against // the same stale-snapshot failure mode as handle_user_devices_ingest_request diff --git a/src/federation/InboundRequest.cpp b/src/federation/InboundRequest.cpp index aec293f54..b25118138 100644 --- a/src/federation/InboundRequest.cpp +++ b/src/federation/InboundRequest.cpp @@ -1879,6 +1879,17 @@ namespace return {200U, std::move(body)}; } + // The provider judges the request and answers its own refusals; this only carries the verified origin and body. + [[nodiscard]] auto handle_livekit_token(FederationRuntimeState& runtime, SignedFederationRequest const& request) + -> FederationResponse + { + if (!runtime.livekit_token_provider) + { + return {501U, "livekit_token not implemented"}; + } + return runtime.livekit_token_provider(request.origin, request.body); + } + [[nodiscard]] auto handle_user_devices(FederationRuntimeState& runtime, SignedFederationRequest const& request) -> FederationResponse { @@ -2353,6 +2364,8 @@ namespace return handle_claim_keys(runtime, request); case FederationEndpoint::query_user_devices: return handle_user_devices(runtime, request); + case FederationEndpoint::livekit_token: + return handle_livekit_token(runtime, request); case FederationEndpoint::query_event: return handle_query_event(runtime, request); case FederationEndpoint::query_state: diff --git a/src/federation/Transactions.cpp b/src/federation/Transactions.cpp index fcf194e34..845538beb 100644 --- a/src/federation/Transactions.cpp +++ b/src/federation/Transactions.cpp @@ -125,6 +125,8 @@ auto federation_endpoint_name(FederationEndpoint endpoint) noexcept -> char cons return "media_thumbnail"; case FederationEndpoint::exchange_third_party_invite: return "exchange_third_party_invite"; + case FederationEndpoint::livekit_token: + return "livekit_token"; } return "unknown"; @@ -153,6 +155,8 @@ auto federation_endpoint_requires_main_relay(FederationEndpoint endpoint) noexce case FederationEndpoint::claim_keys: case FederationEndpoint::query_user_devices: case FederationEndpoint::query_event: + // Mints a token with the LiveKit secret, which only main holds (ADR-0831). + case FederationEndpoint::livekit_token: return true; case FederationEndpoint::make_leave: case FederationEndpoint::make_knock: @@ -210,6 +214,9 @@ auto federation_routes() -> std::vector route("GET", "/_matrix/federation/v1/media/thumbnail/{mediaId}", FederationEndpoint::media_thumbnail), route("PUT", "/_matrix/federation/v1/exchange_third_party_invite/{roomId}", FederationEndpoint::exchange_third_party_invite), + route("POST", "/_matrix/federation/v1/rtc/livekit/get_token", FederationEndpoint::livekit_token), + route("POST", "/_matrix/federation/unstable/io.element.msc4195/rtc/livekit/get_token", + FederationEndpoint::livekit_token), }; } diff --git a/src/federation/WorkerRelayBinding.cpp b/src/federation/WorkerRelayBinding.cpp index 83c4e35de..2fd23b7ff 100644 --- a/src/federation/WorkerRelayBinding.cpp +++ b/src/federation/WorkerRelayBinding.cpp @@ -35,6 +35,8 @@ namespace return "user_devices"; case WorkerRelayKind::profile_query: return "profile_query"; + case WorkerRelayKind::livekit_token: + return "livekit_token"; } return "unknown"; } @@ -103,6 +105,9 @@ auto verified_request_relay_digests(std::string_view method, std::string_view ta std::ignore = append_digest(digests, WorkerRelayKind::profile_query, user_id); } break; + case FederationEndpoint::livekit_token: + std::ignore = append_digest(digests, WorkerRelayKind::livekit_token, body); + break; default: break; } diff --git a/src/federation_worker/WorkerEventLoop.cpp b/src/federation_worker/WorkerEventLoop.cpp index 83fc34e85..f33a849cb 100644 --- a/src/federation_worker/WorkerEventLoop.cpp +++ b/src/federation_worker/WorkerEventLoop.cpp @@ -498,6 +498,20 @@ namespace return ipc::ipc_json_get_str(json, "response_body"); } + // Deserialize a `livekit_token_ingest_result` JSON frame from main into the status and body to answer. A reply + // with no usable status or no body is a 502 `M_UNKNOWN`: main did not answer, and the worker never invents a + // token or a refusal of its own (ADR-0831). + auto deserialize_livekit_token_ingest_result(std::string_view json) -> federation::FederationResponse + { + auto const status = ipc::ipc_json_get_u64(json, "status"); + auto body = ipc::ipc_json_get_str(json, "response_body"); + if (status < 100U || status > 599U || body.empty()) + { + return {502U, R"({"errcode":"M_UNKNOWN","error":"the token service did not answer"})"}; + } + return {static_cast(status), std::move(body)}; + } + // Deserialize a `profile_query_ingest_result` JSON frame from main. Uses // the same full-JSON-parse approach as deserialize_membership_ingest_result // above rather than ipc::ipc_json_get_str, since "found" is a raw bool @@ -1090,6 +1104,21 @@ auto WorkerEventLoop::run() -> void return deserialize_device_keys_query_ingest_result(*reply); }; + // POST /rtc/livekit/get_token: the token is signed with the LiveKit secret, which only main holds, so the worker + // forwards the verified origin and body and answers what main answers (ADR-0831). Bound to the verified request + // like the relays above. + runtime.federation.livekit_token_provider = + [channel_ptr](std::string_view origin, std::string_view request_body) -> federation::FederationResponse { + auto const reply = + federation_worker::relay_to_main(*channel_ptr, federation::WorkerRelayKind::livekit_token, request_body, + current_fed_parent_request_id, std::chrono::seconds{60}, origin); + if (!reply.has_value()) + { + return deserialize_livekit_token_ingest_result({}); + } + return deserialize_livekit_token_ingest_result(*reply); + }; + runtime.federation.profile_query_provider = [channel_ptr](std::string_view user_id) -> federation::FederationProfile { // GHSA-3p5v-vrg8-f545 (ADR-0595): main admits the relay only for the verified request it forwarded. diff --git a/src/federation_worker/WorkerRelayFrame.cpp b/src/federation_worker/WorkerRelayFrame.cpp index 96ca730c5..8d1db7778 100644 --- a/src/federation_worker/WorkerRelayFrame.cpp +++ b/src/federation_worker/WorkerRelayFrame.cpp @@ -36,6 +36,8 @@ namespace return {"device_keys_query_ingest", "request_body"}; case federation::WorkerRelayKind::user_devices: return {"user_devices_ingest", "user_id"}; + case federation::WorkerRelayKind::livekit_token: + return {"livekit_token_ingest", "request_body"}; case federation::WorkerRelayKind::profile_query: break; } @@ -44,13 +46,18 @@ namespace } // namespace -auto worker_relay_frame(federation::WorkerRelayKind kind, std::string_view argument, std::uint64_t parent_request_id) - -> std::optional +auto worker_relay_frame(federation::WorkerRelayKind kind, std::string_view argument, std::uint64_t parent_request_id, + std::string_view origin) -> std::optional { if (parent_request_id == 0U) { return std::nullopt; } + auto const names_origin = kind == federation::WorkerRelayKind::livekit_token; + if (names_origin && origin.empty()) + { + return std::nullopt; + } auto const shape = relay_frame_shape(kind); auto frame = std::string{R"({"type":)"}; frame.reserve(96U + argument.size()); @@ -61,14 +68,20 @@ auto worker_relay_frame(federation::WorkerRelayKind kind, std::string_view argum frame += ipc::ipc_json_str(shape.argument_field); frame += ":"; frame += ipc::ipc_json_str(argument); + if (names_origin) + { + frame += R"(,"origin":)"; + frame += ipc::ipc_json_str(origin); + } frame += '}'; return frame; } auto relay_to_main(ipc::IpcChannel& channel, federation::WorkerRelayKind kind, std::string_view argument, - std::uint64_t parent_request_id, std::chrono::seconds timeout) -> std::optional + std::uint64_t parent_request_id, std::chrono::seconds timeout, std::string_view origin) + -> std::optional { - auto const frame = worker_relay_frame(kind, argument, parent_request_id); + auto const frame = worker_relay_frame(kind, argument, parent_request_id, origin); if (!frame.has_value()) { return std::nullopt; diff --git a/src/homeserver/LocalHttpRouter.cpp b/src/homeserver/LocalHttpRouter.cpp index 30ce90d0e..7f2a169f4 100644 --- a/src/homeserver/LocalHttpRouter.cpp +++ b/src/homeserver/LocalHttpRouter.cpp @@ -74,6 +74,7 @@ #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/InvitePermission.hpp" #include "merovingian/homeserver/KeyServerCache.hpp" +#include "merovingian/homeserver/LiveKitTokenService.hpp" #include "merovingian/homeserver/LocalDatabase.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/LocalHttpResponse.hpp" @@ -3367,6 +3368,22 @@ namespace return user_exists ? federation::FederationProfile{true, {}, {}} : federation::FederationProfile{}; }; + // ADR-0831: main serves a federation request itself on some paths, and a worker's relay lands here too. + runtime.federation.livekit_token_provider = [rt](std::string_view origin, + std::string_view body) -> federation::FederationResponse { + auto const guard = RuntimeLock{rt->mutex}; + auto const result = issue_federation_livekit_token(*rt, origin, body); + if (result.ok) + { + return {result.status, result.value}; + } + auto const errcode = + result.errcode.empty() ? std::string_view{"M_UNKNOWN"} : std::string_view{result.errcode}; + return {result.status, result.retry_after_ms > 0U + ? matrix_error(errcode, result.reason, result.retry_after_ms) + : matrix_error(errcode, result.reason)}; + }; + runtime.federation.device_keys_query_provider = [rt](std::string_view body) -> std::string { return federation::build_device_keys_query_response(rt->database.persistent_store, body, rt->config.server().server_name); diff --git a/src/homeserver/WorkerPool.cpp b/src/homeserver/WorkerPool.cpp index 9ef8bc84d..5b72dc0a8 100644 --- a/src/homeserver/WorkerPool.cpp +++ b/src/homeserver/WorkerPool.cpp @@ -32,7 +32,9 @@ #include "merovingian/federation/Transactions.hpp" #include "merovingian/federation/WorkerRelayBinding.hpp" #include "merovingian/federation/WorkerRelayKind.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LiveKitTokenService.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/LocalHttpResponse.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" @@ -455,6 +457,10 @@ namespace { return R"({"type":"membership_template_ingest_result","found":true,"reason":"{\"errcode\":\"M_UNKNOWN\",\"error\":\"main at per-channel in-flight cap\"}","error_status":503})"; } + if (type == "livekit_token_ingest") + { + return R"({"type":"livekit_token_ingest_result","status":503,"response_body":"{\"errcode\":\"M_UNKNOWN\",\"error\":\"main at per-channel in-flight cap\"}"})"; + } return R"({"type":"error","status":503,"reason":"main at per-channel in-flight cap"})"; } @@ -620,6 +626,17 @@ namespace return body; } + // `status` and `response_body` are the HTTP answer the worker gives the requesting server as it stands. + auto serialize_livekit_token_ingest_result(std::uint16_t status, std::string_view response_body) -> std::string + { + auto body = std::string{R"({"type":"livekit_token_ingest_result","status":)"}; + body += std::to_string(status); + body += R"(,"response_body":)"; + body += json_str(response_body); + body += '}'; + return body; + } + auto serialize_profile_query_ingest_result(federation::FederationProfile const& profile) -> std::string { auto body = std::string{R"({"type":"profile_query_ingest_result","found":)"}; @@ -1304,6 +1321,37 @@ auto handle_device_keys_query_ingest_request(HomeserverRuntime& runtime, std::st return serialize_device_keys_query_ingest_result(response_body); } +auto handle_livekit_token_ingest_request(HomeserverRuntime& runtime, std::string_view request_json, + ipc::IpcChannel& receiving_channel) -> std::string +{ + // The token is signed with the LiveKit secret, which no worker holds, so the worker relays the verified request + // and main decides it (ADR-0831). Admitted only for the origin main verified AND the one permit main gave the + // request (GHSA-3p5v-vrg8-f545, ADR-0595); main judges nothing the frame says beyond that. + auto const request_body = json_get_str(request_json, "request_body"); + auto const origin = json_get_str(request_json, "origin"); + auto const parent_request_id = ipc::ipc_json_get_u64(request_json, "parent_request_id"); + auto const digest = federation::worker_relay_digest(federation::WorkerRelayKind::livekit_token, request_body); + auto result = OperationResult{}; + { + auto guard = RuntimeLock{runtime.mutex}; + if (origin.empty() || !receiving_channel.matches_pending_origin(parent_request_id, origin) || + !worker_relay_admitted(receiving_channel, request_json, digest, "livekit_token_ingest")) + { + return serialize_livekit_token_ingest_result( + 403U, matrix_error("M_FORBIDDEN", "the token request is not one this server forwarded")); + } + result = issue_federation_livekit_token(runtime, origin, request_body); + } + if (result.ok) + { + return serialize_livekit_token_ingest_result(result.status, result.value); + } + auto const errcode = result.errcode.empty() ? std::string_view{"M_UNKNOWN"} : std::string_view{result.errcode}; + return serialize_livekit_token_ingest_result( + result.status, result.retry_after_ms > 0U ? matrix_error(errcode, result.reason, result.retry_after_ms) + : matrix_error(errcode, result.reason)); +} + auto handle_profile_query_ingest_request(HomeserverRuntime& runtime, std::string_view request_json, ipc::IpcChannel& receiving_channel) -> std::string { @@ -1625,6 +1673,16 @@ WorkerPool::WorkerPool(config::FederationWorkerConfig const& cfg, HomeserverRunt ch->send_response(id, overload_response_for(type)); } } + else if (type == "livekit_token_ingest") + { + if (!submit_limited(handler_pool_, ch, [this, ch, id, json = std::move(json)]() mutable { + auto const guard = InFlightGuard{*ch}; + ch->send_response(id, handle_livekit_token_ingest_request(runtime_, json, *ch)); + })) + { + ch->send_response(id, overload_response_for(type)); + } + } else if (type == "profile_query_ingest") { if (!submit_limited(handler_pool_, ch, [this, ch, id, json = std::move(json)]() mutable { diff --git a/tests/integration/test_federation_worker_flow.cpp b/tests/integration/test_federation_worker_flow.cpp index ce0353f34..4d53fba2d 100644 --- a/tests/integration/test_federation_worker_flow.cpp +++ b/tests/integration/test_federation_worker_flow.cpp @@ -3149,6 +3149,127 @@ SCENARIO("main admits a worker's key and profile query only as the verified quer } } +SCENARIO("main admits a worker's LiveKit token relay only as the verified request it forwarded", + "[integration][federation-worker][query-relay][ghsa-3p5v][livekit]") +{ + // ADR-0831: the LiveKit secret is main's alone, so a worker relays the request. The service is off here, so a + // call that reaches issue_federation_livekit_token answers 404 M_UNRECOGNIZED; a refusal never reaches it. + GIVEN("a runtime with no LiveKit token service and a verified request from remote.example carrying a body") + { + REQUIRE(sodium_init() >= 0); + + auto const tmp_dir = unique_temp_dir("merovingian-fed-worker-livekit-binding"); + auto config = make_federation_worker_config(tmp_dir); + config.database().sqlite_path = (tmp_dir / "livekit-binding-test.sqlite3").string(); + + auto started = start_runtime(config); + REQUIRE(started.started); + auto& runtime = started.runtime; + merovingian::homeserver::wire_federation_callbacks(runtime); + REQUIRE(runtime.federation.livekit_token_provider); + + auto const body = std::string{R"({"room_id":"!r:remote.example","slot_id":"s","member":{"id":"m"}})"}; + auto const permit = + merovingian::federation::worker_relay_digest(merovingian::federation::WorkerRelayKind::livekit_token, body); + REQUIRE(permit.has_value()); + auto const status_of = [](std::string const& reply) { + return merovingian::ipc::ipc_json_get_u64(reply, "status"); + }; + auto const body_of = [](std::string const& reply) { + return merovingian::ipc::ipc_json_get_str(reply, "response_body"); + }; + + auto channels = merovingian::tests::make_edu_relay_channels(); + auto context = merovingian::tests::EduRelayContext{*channels.main, *channels.worker}; + + WHEN("the worker relays the body under the verified origin, with the permit") + { + REQUIRE(context.establish("remote.example", {}, {*permit})); + auto const reply = merovingian::homeserver::handle_livekit_token_ingest_request( + runtime, context.frame(merovingian::federation::WorkerRelayKind::livekit_token, body, "remote.example"), + *channels.main); + REQUIRE(context.finish()); + + THEN("the token service is reached: it answers 404 M_UNRECOGNIZED because it is off") + { + INFO("reply: " << reply); + CHECK(merovingian::ipc::ipc_json_get_str(reply, "type") == "livekit_token_ingest_result"); + CHECK(status_of(reply) == 404U); + CHECK(body_of(reply).find("M_UNRECOGNIZED") != std::string::npos); + } + } + WHEN("the worker names an origin other than the one main verified") + { + REQUIRE(context.establish("remote.example", {}, {*permit})); + auto const reply = merovingian::homeserver::handle_livekit_token_ingest_request( + runtime, context.frame(merovingian::federation::WorkerRelayKind::livekit_token, body, "other.example"), + *channels.main); + REQUIRE(context.finish()); + + THEN("it is 403 M_FORBIDDEN and the token service is not reached") + { + INFO("reply: " << reply); + CHECK(status_of(reply) == 403U); + CHECK(body_of(reply).find("M_FORBIDDEN") != std::string::npos); + CHECK(body_of(reply).find("M_UNRECOGNIZED") == std::string::npos); + } + } + WHEN("the verified request holds no permit for the relay") + { + REQUIRE(context.establish("remote.example")); + auto const reply = merovingian::homeserver::handle_livekit_token_ingest_request( + runtime, context.frame(merovingian::federation::WorkerRelayKind::livekit_token, body, "remote.example"), + *channels.main); + REQUIRE(context.finish()); + + THEN("it is 403 M_FORBIDDEN and the token service is not reached") + { + INFO("reply: " << reply); + CHECK(status_of(reply) == 403U); + CHECK(body_of(reply).find("M_FORBIDDEN") != std::string::npos); + CHECK(body_of(reply).find("M_UNRECOGNIZED") == std::string::npos); + } + } + WHEN("the permit is spent a second time") + { + REQUIRE(context.establish("remote.example", {}, {*permit})); + auto const frame = + context.frame(merovingian::federation::WorkerRelayKind::livekit_token, body, "remote.example"); + auto const first = + merovingian::homeserver::handle_livekit_token_ingest_request(runtime, frame, *channels.main); + auto const second = + merovingian::homeserver::handle_livekit_token_ingest_request(runtime, frame, *channels.main); + REQUIRE(context.finish()); + + THEN("the first reaches the token service and the second is 403 M_FORBIDDEN") + { + INFO("first: " << first << "\nsecond: " << second); + CHECK(status_of(first) == 404U); + CHECK(status_of(second) == 403U); + CHECK(body_of(second).find("M_FORBIDDEN") != std::string::npos); + CHECK(body_of(second).find("M_UNRECOGNIZED") == std::string::npos); + } + } + WHEN("the permit was made for another body") + { + auto const other_permit = merovingian::federation::worker_relay_digest( + merovingian::federation::WorkerRelayKind::livekit_token, R"({"room_id":"!other:remote.example"})"); + REQUIRE(other_permit.has_value()); + REQUIRE(context.establish("remote.example", {}, {*other_permit})); + auto const reply = merovingian::homeserver::handle_livekit_token_ingest_request( + runtime, context.frame(merovingian::federation::WorkerRelayKind::livekit_token, body, "remote.example"), + *channels.main); + REQUIRE(context.finish()); + + THEN("it is 403 M_FORBIDDEN") + { + INFO("reply: " << reply); + CHECK(status_of(reply) == 403U); + } + } + } +} + SCENARIO("handle_directory_query_ingest_request reads a room alias from main's own store", "[integration][federation-worker][query-relay][fed-endpoints]") { diff --git a/tests/support/EduRelayContext.hpp b/tests/support/EduRelayContext.hpp index 22a825886..ef2b5424c 100644 --- a/tests/support/EduRelayContext.hpp +++ b/tests/support/EduRelayContext.hpp @@ -182,6 +182,17 @@ class EduRelayContext final return std::move(*built); } + // As frame(), for a relay that also names the verified `origin` the worker serves (the LiveKit token relay). + [[nodiscard]] auto frame(federation::WorkerRelayKind kind, std::string_view argument, std::string_view origin) const + -> std::string + { + auto guard = std::lock_guard{mutex_}; + REQUIRE(parent_id_ != 0U); + auto built = federation_worker::worker_relay_frame(kind, argument, parent_id_, origin); + REQUIRE(built.has_value()); + return std::move(*built); + } + [[nodiscard]] auto finish() noexcept -> bool { if (finished_) diff --git a/tests/unit/test_federation_inbound_request.cpp b/tests/unit/test_federation_inbound_request.cpp index 3c0156910..2cd6fd4b4 100644 --- a/tests/unit/test_federation_inbound_request.cpp +++ b/tests/unit/test_federation_inbound_request.cpp @@ -938,6 +938,62 @@ SCENARIO("Inbound federation hands a valid exchange_third_party_invite to the ex } } +SCENARIO("Inbound federation hands a LiveKit token request to the provider with the verified origin and body", + "[federation][inbound][livekit]") +{ + GIVEN("a runtime with a verified peer matrix.example.org") + { + auto runtime = merovingian::federation::make_federation_runtime_state(runtime_config()); + auto const origin = std::string{"matrix.example.org"}; + auto const key_id = std::string{"ed25519:auto"}; + auto const token = std::string{"verify-token"}; + merovingian::federation::upsert_remote(runtime, remote_for(origin, key_id, token)); + auto const body = std::string{R"({"room_id":"!r:matrix.example.org","slot_id":"s"})"}; + auto const send = [&](std::string const& path) { + auto request = signed_request(origin, key_id, token, body); + request.method = "POST"; + request.target = path; + request.signature = merovingian::federation::make_federation_signature( + origin, request.destination, request.method, request.target, request.body, + merovingian::federation::test::keypair_from_seed(token).secret_key); + return merovingian::federation::handle_inbound_federation_request(runtime, request); + }; + + WHEN("a provider is set and each path is requested") + { + auto origins = std::vector{}; + auto bodies = std::vector{}; + runtime.livekit_token_provider = [&](std::string_view from, std::string_view request_body) { + origins.emplace_back(from); + bodies.emplace_back(request_body); + return merovingian::federation::FederationResponse{418U, R"({"jwt":"x"})"}; + }; + auto const stable = send("/_matrix/federation/v1/rtc/livekit/get_token"); + auto const unstable = send("/_matrix/federation/unstable/io.element.msc4195/rtc/livekit/get_token"); + + THEN("the provider gets the verified origin and the body, and its status and body are the answer") + { + REQUIRE(stable.status == 418U); + REQUIRE(stable.body == R"({"jwt":"x"})"); + REQUIRE(unstable.status == 418U); + REQUIRE(origins == std::vector{origin, origin}); + REQUIRE(bodies == std::vector{body, body}); + } + } + + WHEN("there is no provider") + { + runtime.livekit_token_provider = {}; + auto const response = send("/_matrix/federation/v1/rtc/livekit/get_token"); + + THEN("the endpoint is not implemented") + { + REQUIRE(response.status == 501U); + } + } + } +} + SCENARIO("Inbound federation rejects malformed send targets and unsigned PDUs", "[federation][inbound][security]") { GIVEN("a runtime with malformed transaction requests") diff --git a/tests/unit/test_federation_transactions.cpp b/tests/unit/test_federation_transactions.cpp index e8d46ebcc..3134a6fc8 100644 --- a/tests/unit/test_federation_transactions.cpp +++ b/tests/unit/test_federation_transactions.cpp @@ -116,6 +116,8 @@ SCENARIO("federation_endpoint_requires_main_relay classifies every registered en merovingian::federation::FederationEndpoint::claim_keys, merovingian::federation::FederationEndpoint::query_user_devices, merovingian::federation::FederationEndpoint::query_event, + // livekit_token is signed with a secret only main holds (ADR-0831). + merovingian::federation::FederationEndpoint::livekit_token, }; WHEN("each registered route's endpoint is classified") diff --git a/tests/unit/test_worker_relay_binding.cpp b/tests/unit/test_worker_relay_binding.cpp index 665e232b4..75ff6f1d2 100644 --- a/tests/unit/test_worker_relay_binding.cpp +++ b/tests/unit/test_worker_relay_binding.cpp @@ -83,6 +83,44 @@ SCENARIO("a verified request yields the one relay permit its route can cause", " } } +SCENARIO("a verified LiveKit token request yields one permit over its body, on either POST path", + "[unit][ghsa-3p5v][relay-binding][livekit]") +{ + REQUIRE(sodium_init() >= 0); + + GIVEN("a token request body") + { + auto const body = std::string{R"({"room_id":"!r:hs.example","slot_id":"s","member":{"id":"m"}})"}; + + WHEN("the permits are computed for the stable and the unstable path, and for routes that are not one") + { + auto const stable = + verified_request_relay_digests("POST", "/_matrix/federation/v1/rtc/livekit/get_token", body); + auto const unstable = verified_request_relay_digests( + "POST", "/_matrix/federation/unstable/io.element.msc4195/rtc/livekit/get_token", body); + auto const get = + verified_request_relay_digests("GET", "/_matrix/federation/v1/rtc/livekit/get_token", body); + auto const other = verified_request_relay_digests("POST", "/_matrix/federation/v1/rtc/livekit/other", body); + + THEN("each POST path has one livekit_token permit over the body, and a GET or another path has none") + { + auto const expected = std::vector{digest_of(WorkerRelayKind::livekit_token, body)}; + CHECK(stable == expected); + CHECK(unstable == expected); + CHECK(get.empty()); + CHECK(other.empty()); + } + + THEN("the permit is not one of another kind over the same body") + { + REQUIRE(stable.size() == 1U); + CHECK(stable.front() != digest_of(WorkerRelayKind::device_keys_query, body)); + CHECK(stable.front() != digest_of(WorkerRelayKind::otk_claim, body)); + } + } + } +} + SCENARIO("a relay digest depends on the relay's kind and its whole argument", "[unit][ghsa-3p5v][relay-binding]") { REQUIRE(sodium_init() >= 0); diff --git a/tests/unit/test_worker_relay_frame.cpp b/tests/unit/test_worker_relay_frame.cpp index 7a4f83f2f..47b171090 100644 --- a/tests/unit/test_worker_relay_frame.cpp +++ b/tests/unit/test_worker_relay_frame.cpp @@ -98,6 +98,49 @@ SCENARIO("a worker's bound relay frame names its kind, its parent request and it } } +SCENARIO("a worker's LiveKit token relay frame also names the verified origin", + "[unit][ghsa-3p5v][relay-frame][livekit]") +{ + GIVEN("a request body and a verified origin holding characters JSON must escape") + { + auto const body = std::string{R"({"room_id":"!r:hs","member":{"id":"a\"b"}})"}; + auto const origin = std::string{"remote.example:8448"}; + + WHEN("the frame is built under parent request 42") + { + auto const frame = worker_relay_frame(WorkerRelayKind::livekit_token, body, 42U, origin); + + THEN("main reads back the type, the parent, the body and the origin unchanged") + { + REQUIRE(frame.has_value()); + INFO("frame: " << *frame); + CHECK(merovingian::ipc::ipc_json_get_str(*frame, "type") == "livekit_token_ingest"); + CHECK(merovingian::ipc::ipc_json_get_u64(*frame, "parent_request_id") == 42U); + CHECK(merovingian::ipc::ipc_json_get_str(*frame, "request_body") == body); + CHECK(merovingian::ipc::ipc_json_get_str(*frame, "origin") == origin); + } + } + WHEN("the frame is built with no parent request, or with no origin") + { + THEN("there is no frame") + { + CHECK_FALSE(worker_relay_frame(WorkerRelayKind::livekit_token, body, 0U, origin).has_value()); + CHECK_FALSE(worker_relay_frame(WorkerRelayKind::livekit_token, body, 42U, "").has_value()); + } + } + WHEN("another kind's frame is built with an origin") + { + auto const frame = worker_relay_frame(WorkerRelayKind::device_keys_query, body, 42U, origin); + + THEN("the origin is not put in it") + { + REQUIRE(frame.has_value()); + CHECK(merovingian::ipc::ipc_json_get_str(*frame, "origin").empty()); + } + } + } +} + SCENARIO("a worker sends a bound relay to main only under a parent request", "[unit][ghsa-3p5v][relay-frame]") { GIVEN("a worker channel whose main end records the frame it receives and answers it") From 15cb35d05133cfc0352b8c186418aa6c9641fa4d Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 13:17:13 +0000 Subject: [PATCH 08/19] Add migration 004 and the LiveKit delegations table, store functions and hydration (ADR-0832) Migration 004 creates livekit_delegations on SQLite and PostgreSQL, with LiveKitDelegationTable holding the rows in memory and LiveKitDelegationStore.hpp writing them in one transaction each. A new delegation replaces the row holding its key and the row holding its delay ID; account deactivation deletes a user's rows beside the delayed events. Co-Authored-By: Claude Sonnet 5.5 --- docs/database-persistence.md | 49 +- .../database/LiveKitDelegationRowText.hpp | 25 + .../database/LiveKitDelegationStore.hpp | 34 + .../database/LiveKitDelegationTable.hpp | 86 +++ include/merovingian/database/Migration.hpp | 3 + .../database/PersistentLiveKitDelegation.hpp | 26 + .../merovingian/database/PersistentStore.hpp | 9 + include/merovingian/database/Schema.hpp | 3 +- migrations/004_livekit_delegations.sql | 5 + migrations/AGENTS.md | 12 +- src/database/LiveKitDelegationRowText.cpp | 63 ++ src/database/LiveKitDelegationStore.cpp | 82 +++ src/database/LiveKitDelegationTable.cpp | 150 ++++ src/database/Migration.cpp | 25 +- src/database/PostgresqlStore.cpp | 27 + src/database/Schema.cpp | 32 +- src/database/SqliteStore.cpp | 39 ++ src/database/meson.build | 3 + src/homeserver/AuthService.cpp | 11 + src/main.cpp | 7 + .../test_database_upgrade_flow.cpp | 39 +- .../test_persistent_homeserver_flow.cpp | 3 +- .../test_postgresql_store_behaviour_flow.cpp | 68 ++ tests/meson.build | 2 + tests/smoke/meson.build | 22 + tests/unit/test_database_persistence.cpp | 132 +++- tests/unit/test_livekit_delegation_store.cpp | 661 ++++++++++++++++++ tests/unit/test_livekit_delegation_table.cpp | 310 ++++++++ tests/unit/test_worker_table_load_profile.cpp | 4 + 29 files changed, 1873 insertions(+), 59 deletions(-) create mode 100644 include/merovingian/database/LiveKitDelegationRowText.hpp create mode 100644 include/merovingian/database/LiveKitDelegationStore.hpp create mode 100644 include/merovingian/database/LiveKitDelegationTable.hpp create mode 100644 include/merovingian/database/PersistentLiveKitDelegation.hpp create mode 100644 migrations/004_livekit_delegations.sql create mode 100644 src/database/LiveKitDelegationRowText.cpp create mode 100644 src/database/LiveKitDelegationStore.cpp create mode 100644 src/database/LiveKitDelegationTable.cpp create mode 100644 tests/unit/test_livekit_delegation_store.cpp create mode 100644 tests/unit/test_livekit_delegation_table.cpp diff --git a/docs/database-persistence.md b/docs/database-persistence.md index 189907fbc..a2ec03e18 100644 --- a/docs/database-persistence.md +++ b/docs/database-persistence.md @@ -25,8 +25,9 @@ value. Test fixtures that do not exercise persistence select it through migration statements (`INSERT`/`UPDATE`/`DELETE`) are accepted as no-op schema-state transitions, enabling backfill and corrective migrations should a later migration need one. -- The schema has three steps. `schema::current_schema_version()` is `3`, and - `migrations/` holds `001_initial_schema.sql`, `002_oauth_tables.sql` and `003_delayed_events.sql`. +- The schema has four steps. `schema::current_schema_version()` is `4`, and + `migrations/` holds `001_initial_schema.sql`, `002_oauth_tables.sql`, `003_delayed_events.sql` and + `004_livekit_delegations.sql`. - Version `1` (`initial_schema`) is the frozen v1 schema. Every pre-1.0 migration (versions 2 to 26 as of 0.12.46) was collapsed into it in 0.12.47 ([ADR-0224](adr/0224-pre-1-0-migrations-collapse-into-one-frozen-v1-schema.md)), @@ -42,12 +43,14 @@ value. Test fixtures that do not exercise persistence select it through `stream_ordering` is deliberately unindexed) Nothing is seeded or backfilled: the old state-transition backfill and state-group seeding only ever mattered for upgrading existing databases and no longer exist. The compiled catalog in - `src/database/Migration.cpp` has three upgrade steps (version `1`, - `initial_schema`; version `2`, `oauth_tables`; version `3`, `delayed_events`) and three downgrade steps, newest - first (`drop_delayed_events` to version `2`, `drop_oauth_tables` to version `1`, then `drop_initial_schema` to - version `0`, which drops every v1 table). + `src/database/Migration.cpp` has four upgrade steps (version `1`, + `initial_schema`; version `2`, `oauth_tables`; version `3`, `delayed_events`; version `4`, `livekit_delegations`) + and four downgrade steps, newest first (`drop_livekit_delegations` to version `3`, `drop_delayed_events` to + version `2`, `drop_oauth_tables` to version `1`, then `drop_initial_schema` to version `0`, which drops every v1 + table). `migrations/001_initial_schema.sql` is the frozen record of v1, - `002_oauth_tables.sql` of version 2 and `003_delayed_events.sql` of version 3; a unit test requires each file to + `002_oauth_tables.sql` of version 2, `003_delayed_events.sql` of version 3 and `004_livekit_delegations.sql` of + version 4; a unit test requires each file to match the build's step statement for statement. - Version `2` (`oauth_tables`, 1.1.0) adds the OAuth 2.0 tables ([ADR-0776](adr/0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md)), @@ -111,6 +114,29 @@ value. Test fixtures that do not exercise persistence select it through memory is finalised even when the finalising commit fails (the function says so), and the database row still reads `scheduled`, so the next start-up sends it again (at least once, ADR-0825). Every other function changes memory only after the commit. +- Version `4` (`livekit_delegations`, ADR-0832) adds one table for delayed leave events the LiveKit token service + keeps alive for a user (MSC4195 `delegate_delayed_leave`), and changes no existing table: + - `livekit_delegations` (`delay_id TEXT PRIMARY KEY`, then `user_id`, `room_id`, `slot_id`, `member_id` and + `created_ms`, all `TEXT NOT NULL`: `created_ms` is wall-clock milliseconds since the epoch as decimal text), with + `idx_livekit_delegations_user_id` on `user_id`, which serves the delete at deactivation. `delay_id` is the + `delayed_events.delay_id` of the delayed event; there is no foreign key, the store keeps its rules in code. One row + per (user, room, slot, member): MSC4195 allows one delegation per key. + - Caps, enforced by `store_livekit_delegation` and again when hydrating (`LiveKitDelegationStore.hpp`, + `LiveKitDelegationTable.hpp`): `delay_id` 1 to 64 bytes, and 1 to 255 bytes for `user_id`, `room_id`, `slot_id` + and `member_id`, none holding a NUL byte. A row outside them is refused, never truncated. + - Writes: `store_livekit_delegation` deletes the row holding the same key, deletes the row holding the same delay ID + and inserts the new row in one transaction, so a new delay ID for a key replaces the old delegation; + `delete_livekit_delegation` deletes one row (success also when there was none); and + `delete_livekit_delegations_of_user` deletes all of a user's rows, always running the `DELETE` so a row hydration + skipped does not outlive the account, and runs beside `delete_delayed_events_of_user` at account deactivation. Every + write is bound parameters only, and memory changes only after the commit returns true. + - In memory: `PersistentStore::livekit_delegations` (`LiveKitDelegationTable`), hydrated on both backends (neither + loads it for the federation worker profile), with no lock of its own (`runtime.mutex` serialises it). It indexes the + rows by delay ID and by (user, room, slot, member) and counts them per user; `rows()` lists them in insertion + order. A row the loader cannot read is skipped, never repaired and never guessed: an empty or over-long field, a + `created_ms` that is not decimal digits fitting 64 bits, or a duplicate delay ID or key (the first by delay ID + wins). The count skipped is `PersistentStore::livekit_delegation_rows_skipped_at_load`, logged once at start-up as + `livekit_delegations.rows_skipped_at_load`. - The schema registry is split by version ([ADR-0778](adr/0778-the-schema-is-built-from-per-version-tables-and-each-migration-step-from-what-its-version-adds.md)): `initial_schema_definitions()` is what v1 created, and the SQLite and @@ -956,9 +982,9 @@ value. Test fixtures that do not exercise persistence select it through (`[fixture]`, one per backend) open it, run `migrate_*_schema_to`, start the runtime on it and read back the users, access tokens, rooms, events, media, account data, pusher and device keys the manifest lists, then send a new event signed with the old release's key. Opening the 1.0.3 database applies migration 002 (the OAuth 2.0 tables), so - the scenarios first assert the v1 to v3 steps ran: the schema version is `current_schema_version()`, the ledger gained the - `oauth_tables` and `delayed_events` rows, and `oauth_clients`, `oauth_sessions` and `delayed_events` exist and take a row (the fixture - held none of them before). They then assert everything the manifest lists is still served. + the scenarios first assert the v1 to v4 steps ran: the schema version is `current_schema_version()`, the ledger gained the + `oauth_tables`, `delayed_events` and `livekit_delegations` rows, and `oauth_clients`, `oauth_sessions`, `delayed_events` + and `livekit_delegations` exist and take a row (the fixture held none of them before). They then assert everything the manifest lists is still served. The PostgreSQL scenario needs `MEROVINGIAN_TEST_POSTGRESQL_URI` and reports itself skipped without it. - Both stores read the migration ledger in numeric order (`ORDER BY CAST(version AS INTEGER)`): `schema_migrations.version` is `TEXT`, and @@ -1272,7 +1298,8 @@ migration's table cannot go unclassified: `login_tokens`, `appservice_txn_cursor`, `appservice_outbox`, `deferred_pdus`, `receipts`, `appservice_directory`, `media_pending_uploads`, `oauth_clients` and `oauth_sessions` (migration 002; every OAuth 2.0 endpoint runs in main), `delayed_events` (migration 003; the federation worker sends no events - and holds no signing key, so it never reads a scheduled event), plus six tables `Schema.cpp` + and holds no signing key, so it never reads a scheduled event), `livekit_delegations` (migration 004; the token + service runs in main and the worker keeps no delayed event alive), plus six tables `Schema.cpp` declares but that no runtime code path (main's or the worker's) ever populates or queries — `event_json`, `key_backups`, `push_rules`, `rate_limits`, `room_versions`, `state_group_edges` — vestigial from diff --git a/include/merovingian/database/LiveKitDelegationRowText.hpp b/include/merovingian/database/LiveKitDelegationRowText.hpp new file mode 100644 index 000000000..8a622d8ce --- /dev/null +++ b/include/merovingian/database/LiveKitDelegationRowText.hpp @@ -0,0 +1,25 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/PersistentLiveKitDelegation.hpp" + +#include +#include +#include +#include + +namespace merovingian::database +{ + +// The number of columns of a `livekit_delegations` row, in the order the loaders select them: `delay_id`, `user_id`, +// `room_id`, `slot_id`, `member_id`, `created_ms`. +inline constexpr auto livekit_delegation_row_columns = std::size_t{6U}; + +// The strict reading of one stored `livekit_delegations` row, shared by both backends' loaders. Nullopt (the row is +// skipped, never repaired or guessed) unless there are at least `livekit_delegation_row_columns` columns, each text +// column is storable (`livekit_delegation_is_storable`) and `created_ms` is one or more ASCII digits that fit 64 bits. +[[nodiscard]] auto parse_livekit_delegation_row(std::span columns) + -> std::optional; + +} // namespace merovingian::database diff --git a/include/merovingian/database/LiveKitDelegationStore.hpp b/include/merovingian/database/LiveKitDelegationStore.hpp new file mode 100644 index 000000000..fd7ff422d --- /dev/null +++ b/include/merovingian/database/LiveKitDelegationStore.hpp @@ -0,0 +1,34 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/PersistentLiveKitDelegation.hpp" + +#include + +namespace merovingian::database +{ + +struct PersistentStore; + +// The LiveKit delegations of migration 004 (ADR-0832). Every function here reads or writes +// `PersistentStore::livekit_delegations` and, for a write, the database in one transaction with bound parameters +// only. Memory changes only after the commit returns true. None takes a lock; in main the caller holds +// `runtime.mutex`. The caps are in LiveKitDelegationTable.hpp. + +// Stores `row` as the one delegation of its (user, room, slot, member): in one transaction the row holding the same +// key, if any, and the row holding the same delay ID, if any, are deleted and `row` is inserted (MSC4195: one +// delegation per key, and a new delay ID replaces the old). False, writing nothing, when a field is empty, over its +// cap or holds a NUL byte, or the commit fails. +[[nodiscard]] auto store_livekit_delegation(PersistentStore& store, PersistentLiveKitDelegation row) -> bool; + +// Deletes the delegation of `delay_id`. True when the row is gone, also when there was none; false only when the +// commit fails, with memory unchanged. +[[nodiscard]] auto delete_livekit_delegation(PersistentStore& store, std::string_view delay_id) -> bool; + +// Deletes every delegation of `user_id`. Always runs the DELETE, even when memory holds no row for the user: a row that +// hydration skipped is in the database and must not survive a deactivation. False only when the commit fails, with +// memory unchanged. +[[nodiscard]] auto delete_livekit_delegations_of_user(PersistentStore& store, std::string_view user_id) -> bool; + +} // namespace merovingian::database diff --git a/include/merovingian/database/LiveKitDelegationTable.hpp b/include/merovingian/database/LiveKitDelegationTable.hpp new file mode 100644 index 000000000..0437495ff --- /dev/null +++ b/include/merovingian/database/LiveKitDelegationTable.hpp @@ -0,0 +1,86 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/PersistentLiveKitDelegation.hpp" +#include "merovingian/database/StateGroupKeyHash.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::database +{ + +// Caps on what one row holds, enforced where the row is stored and where it is read back: an oversized row is +// refused, never truncated. +inline constexpr auto max_livekit_delegation_delay_id_bytes = std::size_t{64U}; +// The user, room, slot and member IDs. +inline constexpr auto max_livekit_delegation_field_bytes = std::size_t{255U}; + +// Whether `row` may be stored: every text field non-empty, within its cap and free of NUL (PostgreSQL TEXT cannot hold +// one and the table's key joins its parts with one). +[[nodiscard]] auto livekit_delegation_is_storable(PersistentLiveKitDelegation const& row) noexcept -> bool; + +// The in-memory copy of `livekit_delegations` (migration 004, ADR-0832). The class owns the rows and shows them +// read-only, so a writer that bypasses it does not compile and its indexes cannot drift from the rows. Indexes: by +// delay ID, by (user, room, slot, member) and a row count per user; the rows themselves are kept in insertion order. +// An erase renumbers the positions the two lookups hold, which costs the table's size; delegations are few and end +// rarely. The table has no lock: a reader needs exclusion from writers (in main, `runtime.mutex`). A pointer it +// returns is valid until the next write. Copy and move are defaulted: the indexes hold positions into the vector, so +// they stay valid in the copy. +class LiveKitDelegationTable final +{ +public: + // The row for `delay_id`, or nullptr. + [[nodiscard]] auto find(std::string_view delay_id) const -> PersistentLiveKitDelegation const*; + // The row of (`user_id`, `room_id`, `slot_id`, `member_id`), or nullptr. + [[nodiscard]] auto find_by_key(std::string_view user_id, std::string_view room_id, std::string_view slot_id, + std::string_view member_id) const -> PersistentLiveKitDelegation const*; + // How many rows `user_id` holds. + [[nodiscard]] auto count_of_user(std::string_view user_id) const -> std::size_t; + [[nodiscard]] auto size() const noexcept -> std::size_t + { + return m_rows.size(); + } + // Every row, in insertion order. + [[nodiscard]] auto rows() const noexcept -> std::vector const& + { + return m_rows; + } + + // The remaining members are for the store functions (LiveKitDelegationStore.hpp) and hydration only. + + // Adds `row`. False, and nothing changes, when it is not storable (`livekit_delegation_is_storable`), its delay ID + // is held or another row holds the same key. + auto insert(PersistentLiveKitDelegation row) -> bool; + // Removes the row for `delay_id`. False when absent. + auto erase(std::string_view delay_id) -> bool; + // Removes the row holding the key. False when absent. + auto erase_key(std::string_view user_id, std::string_view room_id, std::string_view slot_id, + std::string_view member_id) -> bool; + // Removes every row of `user_id`, returning how many. + auto erase_user(std::string_view user_id) -> std::size_t; + // Removes every row, for hydration. + auto clear() noexcept -> void; + +private: + template + using KeyedBy = std::unordered_map>; + + auto erase_at(std::size_t position) -> void; + // Rebuilds both position indexes from the rows. + auto reindex() -> void; + + std::vector m_rows{}; + // Delay ID -> position in `m_rows`. + KeyedBy m_by_delay_id{}; + // (user NUL room NUL slot NUL member) -> position in `m_rows`. + KeyedBy m_by_key{}; + KeyedBy m_user_counts{}; +}; + +} // namespace merovingian::database diff --git a/include/merovingian/database/Migration.hpp b/include/merovingian/database/Migration.hpp index 19c5ec693..524de73e1 100644 --- a/include/merovingian/database/Migration.hpp +++ b/include/merovingian/database/Migration.hpp @@ -29,6 +29,9 @@ namespace merovingian::database // Migration 003 (1.1.2): the delayed-events table (ADR-0824). [[nodiscard]] auto delayed_events_migration() -> MigrationStep; [[nodiscard]] auto downgrade_delayed_events_migration() -> MigrationStep; +// Migration 004: the LiveKit delegations table (ADR-0832). +[[nodiscard]] auto livekit_delegations_migration() -> MigrationStep; +[[nodiscard]] auto downgrade_livekit_delegations_migration() -> MigrationStep; [[nodiscard]] auto upgrade_migration_catalog() -> std::vector; [[nodiscard]] auto downgrade_migration_catalog() -> std::vector; [[nodiscard]] auto migration_plan_for(SchemaState const& state) -> MigrationPlan; diff --git a/include/merovingian/database/PersistentLiveKitDelegation.hpp b/include/merovingian/database/PersistentLiveKitDelegation.hpp new file mode 100644 index 000000000..12ad7091f --- /dev/null +++ b/include/merovingian/database/PersistentLiveKitDelegation.hpp @@ -0,0 +1,26 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::database +{ + +// Migration 004 (ADR-0832): one delegation (`livekit_delegations`) of a delayed `m.rtc.member` leave event to the +// LiveKit token service (MSC4195 `delegate_delayed_leave`). While the user's LiveKit participant is connected the +// server keeps the delayed event (`delay_id`, a `delayed_events.delay_id`) alive. One row per (user, room, slot, +// member). `created_ms` is wall-clock milliseconds since the Unix epoch. A row never changes except through +// `LiveKitDelegationTable`. +struct PersistentLiveKitDelegation final +{ + std::string delay_id{}; + std::string user_id{}; + std::string room_id{}; + std::string slot_id{}; + std::string member_id{}; + std::uint64_t created_ms{0U}; +}; + +} // namespace merovingian::database diff --git a/include/merovingian/database/PersistentStore.hpp b/include/merovingian/database/PersistentStore.hpp index f43e7be0b..7c4a77fa5 100644 --- a/include/merovingian/database/PersistentStore.hpp +++ b/include/merovingian/database/PersistentStore.hpp @@ -13,6 +13,7 @@ #include "merovingian/database/ExaminedRows.hpp" #include "merovingian/database/ForwardExtremityTable.hpp" #include "merovingian/database/KeyBackupDigest.hpp" +#include "merovingian/database/LiveKitDelegationTable.hpp" #include "merovingian/database/MediaBlobRead.hpp" #include "merovingian/database/MembershipProjection.hpp" #include "merovingian/database/MembershipStoreResult.hpp" @@ -584,6 +585,14 @@ struct PersistentStore final // not digits or is out of range, a boolean that is not "true" or "false", an unknown status, a duplicate key). The // rows stay in the database. The homeserver warns once at start-up when this is not zero. std::size_t delayed_event_rows_skipped_at_load{0U}; + // Migration 004 (ADR-0832): `livekit_delegations`, MSC4195 delayed leaves delegated to the LiveKit token service. + // Read and write through LiveKitDelegationStore.hpp; it has no lock of its own, so in main `runtime.mutex` + // serialises it. The federation worker never holds it. + LiveKitDelegationTable livekit_delegations{}; + // How many `livekit_delegations` rows the last hydration skipped because they were not read exactly (an empty or + // over-long field, a `created_ms` that is not digits, a duplicate delay ID or key). The rows stay in the database. + // The homeserver warns once at start-up when this is not zero. + std::size_t livekit_delegation_rows_skipped_at_load{0U}; std::vector appservice_txn_cursors{}; // Events queued for appservices, kept sorted by (appservice_id, stream_ordering). See // PersistentAppserviceOutboxEntry. diff --git a/include/merovingian/database/Schema.hpp b/include/merovingian/database/Schema.hpp index 1b08d11d9..5cd309b8d 100644 --- a/include/merovingian/database/Schema.hpp +++ b/include/merovingian/database/Schema.hpp @@ -16,7 +16,8 @@ namespace merovingian::database [[nodiscard]] auto current_schema_version() noexcept -> std::uint32_t; // The schema split (ADR-0778). The tables and indexes migration `version` creates: version 1 is the frozen v1 -// schema, version 2 the OAuth 2.0 tables, version 3 the delayed-events table; any other version adds none. A migration step is built from these. +// schema, version 2 the OAuth 2.0 tables, version 3 the delayed-events table, version 4 the LiveKit delegations table; +// any other version adds none. A migration step is built from these. [[nodiscard]] auto schema_definitions_added_by(std::uint32_t version) -> std::vector; [[nodiscard]] auto schema_indexes_added_by(std::uint32_t version) -> std::vector; // Exactly what v1 created, which the SQLite and PostgreSQL bootstraps build before any later step runs. diff --git a/migrations/004_livekit_delegations.sql b/migrations/004_livekit_delegations.sql new file mode 100644 index 000000000..4c3757c9e --- /dev/null +++ b/migrations/004_livekit_delegations.sql @@ -0,0 +1,5 @@ +-- merovingian-migration version=4 name=livekit_delegations direction=upgrade +-- statement create_livekit_delegations +CREATE TABLE "livekit_delegations" (delay_id TEXT PRIMARY KEY, user_id TEXT NOT NULL, room_id TEXT NOT NULL, slot_id TEXT NOT NULL, member_id TEXT NOT NULL, created_ms TEXT NOT NULL) +-- statement create_idx_livekit_delegations_user_id +CREATE INDEX idx_livekit_delegations_user_id ON livekit_delegations (user_id) diff --git a/migrations/AGENTS.md b/migrations/AGENTS.md index 50c7383b2..06c30db48 100644 --- a/migrations/AGENTS.md +++ b/migrations/AGENTS.md @@ -54,6 +54,16 @@ with `schema_step_creating` and its downgrade with `schema_step_dropping`, a fil (`drop_delayed_events`, to version 2) at the front of the downgrade catalog, and the file equal to the step. The table is classified in the worker's never-reads set (the worker sends no events), not in the allowlist. +## Migration 004: LiveKit delegations (ADR-0832) + +`004_livekit_delegations.sql` creates `livekit_delegations` (six `TEXT` columns, `delay_id` the primary key) and +`idx_livekit_delegations_user_id` on `(user_id)`. It follows migration 003's pattern exactly: its own arrays +`livekit_delegation_tables` and `livekit_delegation_indexes` in `Schema.cpp`, a case in both `*_added_by` functions and +in `schema_table_definition`, the step `livekit_delegations_migration()` built with `schema_step_creating` and its +downgrade `downgrade_livekit_delegations_migration()` (`drop_livekit_delegations`, to version 3) at the front of the +downgrade catalog, and the file equal to the step. The table is classified in the worker's never-reads set (the token +service runs in main), not in the allowlist. + ## File naming ``` @@ -62,7 +72,7 @@ NNN_snake_case_description.sql `NNN` is a zero-padded three-digit integer: `001`, `002`, ..., `010`, `011`, ... The next migration number is always `max(existing) + 1`. -Current highest: `003`. +Current highest: `004`. ## File format diff --git a/src/database/LiveKitDelegationRowText.cpp b/src/database/LiveKitDelegationRowText.cpp new file mode 100644 index 000000000..ed38a0116 --- /dev/null +++ b/src/database/LiveKitDelegationRowText.cpp @@ -0,0 +1,63 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/database/LiveKitDelegationRowText.hpp" + +#include "merovingian/database/LiveKitDelegationTable.hpp" + +#include +#include +#include + +namespace merovingian::database +{ +namespace +{ + + // One or more ASCII digits whose value fits 64 bits; nullopt for anything else (empty, a sign, a space, a letter, + // 21 digits). + [[nodiscard]] auto strict_u64(std::string_view text) noexcept -> std::optional + { + if (text.empty()) + { + return std::nullopt; + } + auto value = std::uint64_t{0U}; + for (auto const character : text) + { + if (character < '0' || character > '9') + { + return std::nullopt; + } + auto const digit = static_cast(character - '0'); + if (value > (std::numeric_limits::max() - digit) / 10U) + { + return std::nullopt; + } + value = (value * 10U) + digit; + } + return value; + } + +} // namespace + +auto parse_livekit_delegation_row(std::span columns) -> std::optional +{ + if (columns.size() < livekit_delegation_row_columns) + { + return std::nullopt; + } + auto const created_ms = strict_u64(columns[5]); + if (!created_ms.has_value()) + { + return std::nullopt; + } + auto row = PersistentLiveKitDelegation{columns[0], columns[1], columns[2], columns[3], columns[4], *created_ms}; + if (!livekit_delegation_is_storable(row)) + { + return std::nullopt; + } + return row; +} + +} // namespace merovingian::database diff --git a/src/database/LiveKitDelegationStore.cpp b/src/database/LiveKitDelegationStore.cpp new file mode 100644 index 000000000..9b8f6fa48 --- /dev/null +++ b/src/database/LiveKitDelegationStore.cpp @@ -0,0 +1,82 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/database/LiveKitDelegationStore.hpp" + +#include "merovingian/database/BoundValue.hpp" +#include "merovingian/database/LiveKitDelegationTable.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/database/PreparedStatement.hpp" + +#include +#include +#include + +namespace merovingian::database +{ +namespace +{ + + [[nodiscard]] auto text(std::string_view value) -> BoundValue + { + return {std::string{value}, false}; + } + +} // namespace + +auto store_livekit_delegation(PersistentStore& store, PersistentLiveKitDelegation row) -> bool +{ + if (!livekit_delegation_is_storable(row)) + { + return false; + } + auto const same_key = PreparedStatement{ + "delete_livekit_delegation_by_key", + "DELETE FROM livekit_delegations WHERE user_id = $1 AND room_id = $2 AND slot_id = $3 AND member_id = $4", + {text(row.user_id), text(row.room_id), text(row.slot_id), text(row.member_id)} + }; + auto const same_delay_id = PreparedStatement{"delete_livekit_delegation_by_delay_id", + "DELETE FROM livekit_delegations WHERE delay_id = $1", + {text(row.delay_id)}}; + auto const insert = PreparedStatement{ + "insert_livekit_delegation", + "INSERT INTO livekit_delegations (delay_id, user_id, room_id, slot_id, member_id, created_ms) VALUES ($1, $2, " + "$3, $4, $5, $6)", + {text(row.delay_id), text(row.user_id), text(row.room_id), text(row.slot_id), text(row.member_id), + text(std::to_string(row.created_ms))} + }; + if (!commit_persistent_transaction(store, {same_key, same_delay_id, insert})) + { + return false; + } + std::ignore = store.livekit_delegations.erase_key(row.user_id, row.room_id, row.slot_id, row.member_id); + std::ignore = store.livekit_delegations.erase(row.delay_id); + return store.livekit_delegations.insert(std::move(row)); +} + +auto delete_livekit_delegation(PersistentStore& store, std::string_view delay_id) -> bool +{ + // Always the DELETE: a row that hydration skipped is in the database and is removed with the rest. + auto const statement = PreparedStatement{ + "delete_livekit_delegation", "DELETE FROM livekit_delegations WHERE delay_id = $1", {text(delay_id)}}; + if (!commit_persistent_transaction(store, {statement})) + { + return false; + } + std::ignore = store.livekit_delegations.erase(delay_id); + return true; +} + +auto delete_livekit_delegations_of_user(PersistentStore& store, std::string_view user_id) -> bool +{ + auto const statement = PreparedStatement{ + "delete_livekit_delegations_of_user", "DELETE FROM livekit_delegations WHERE user_id = $1", {text(user_id)}}; + if (!commit_persistent_transaction(store, {statement})) + { + return false; + } + std::ignore = store.livekit_delegations.erase_user(user_id); + return true; +} + +} // namespace merovingian::database diff --git a/src/database/LiveKitDelegationTable.cpp b/src/database/LiveKitDelegationTable.cpp new file mode 100644 index 000000000..576550a57 --- /dev/null +++ b/src/database/LiveKitDelegationTable.cpp @@ -0,0 +1,150 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/database/LiveKitDelegationTable.hpp" + +#include +#include + +namespace merovingian::database +{ +namespace +{ + + // A key made of the parts separated by NUL, which a storable row never holds, so two different tuples never make + // the same key. + [[nodiscard]] auto delegation_key(std::string_view user_id, std::string_view room_id, std::string_view slot_id, + std::string_view member_id) -> std::string + { + auto key = std::string{user_id}; + for (auto const part : {room_id, slot_id, member_id}) + { + key.push_back('\0'); + key.append(part); + } + return key; + } + + [[nodiscard]] auto has_nul(std::string_view value) noexcept -> bool + { + return value.find('\0') != std::string_view::npos; + } + + [[nodiscard]] auto field_is_storable(std::string_view value, std::size_t cap) noexcept -> bool + { + return !value.empty() && value.size() <= cap && !has_nul(value); + } + +} // namespace + +auto livekit_delegation_is_storable(PersistentLiveKitDelegation const& row) noexcept -> bool +{ + return field_is_storable(row.delay_id, max_livekit_delegation_delay_id_bytes) && + field_is_storable(row.user_id, max_livekit_delegation_field_bytes) && + field_is_storable(row.room_id, max_livekit_delegation_field_bytes) && + field_is_storable(row.slot_id, max_livekit_delegation_field_bytes) && + field_is_storable(row.member_id, max_livekit_delegation_field_bytes); +} + +auto LiveKitDelegationTable::find(std::string_view delay_id) const -> PersistentLiveKitDelegation const* +{ + auto const found = m_by_delay_id.find(delay_id); + return found == m_by_delay_id.end() ? nullptr : &m_rows[found->second]; +} + +auto LiveKitDelegationTable::find_by_key(std::string_view user_id, std::string_view room_id, std::string_view slot_id, + std::string_view member_id) const -> PersistentLiveKitDelegation const* +{ + auto const found = m_by_key.find(delegation_key(user_id, room_id, slot_id, member_id)); + return found == m_by_key.end() ? nullptr : &m_rows[found->second]; +} + +auto LiveKitDelegationTable::count_of_user(std::string_view user_id) const -> std::size_t +{ + auto const found = m_user_counts.find(user_id); + return found == m_user_counts.end() ? 0U : found->second; +} + +auto LiveKitDelegationTable::insert(PersistentLiveKitDelegation row) -> bool +{ + if (!livekit_delegation_is_storable(row) || m_by_delay_id.contains(row.delay_id)) + { + return false; + } + auto key = delegation_key(row.user_id, row.room_id, row.slot_id, row.member_id); + if (m_by_key.contains(key)) + { + return false; + } + auto const position = m_rows.size(); + m_by_delay_id.emplace(row.delay_id, position); + m_by_key.emplace(std::move(key), position); + ++m_user_counts[row.user_id]; + m_rows.push_back(std::move(row)); + return true; +} + +auto LiveKitDelegationTable::erase(std::string_view delay_id) -> bool +{ + auto const found = m_by_delay_id.find(delay_id); + if (found == m_by_delay_id.end()) + { + return false; + } + erase_at(found->second); + return true; +} + +auto LiveKitDelegationTable::erase_key(std::string_view user_id, std::string_view room_id, std::string_view slot_id, + std::string_view member_id) -> bool +{ + auto const found = m_by_key.find(delegation_key(user_id, room_id, slot_id, member_id)); + if (found == m_by_key.end()) + { + return false; + } + erase_at(found->second); + return true; +} + +auto LiveKitDelegationTable::erase_user(std::string_view user_id) -> std::size_t +{ + auto const removed = std::erase_if(m_rows, [user_id](PersistentLiveKitDelegation const& row) { + return row.user_id == user_id; + }); + if (removed != 0U) + { + reindex(); + } + return removed; +} + +auto LiveKitDelegationTable::clear() noexcept -> void +{ + m_rows.clear(); + m_by_delay_id.clear(); + m_by_key.clear(); + m_user_counts.clear(); +} + +auto LiveKitDelegationTable::erase_at(std::size_t position) -> void +{ + m_rows.erase(m_rows.begin() + static_cast::difference_type>(position)); + reindex(); +} + +auto LiveKitDelegationTable::reindex() -> void +{ + m_by_delay_id.clear(); + m_by_key.clear(); + m_user_counts.clear(); + for (auto position = std::size_t{0U}; position < m_rows.size(); ++position) + { + auto const& row = m_rows[position]; + m_by_delay_id.emplace(row.delay_id, position); + m_by_key.emplace(delegation_key(row.user_id, row.room_id, row.slot_id, row.member_id), position); + ++m_user_counts[row.user_id]; + } +} + +} // namespace merovingian::database diff --git a/src/database/Migration.cpp b/src/database/Migration.cpp index b79af4514..8f3c606c1 100644 --- a/src/database/Migration.cpp +++ b/src/database/Migration.cpp @@ -42,6 +42,10 @@ namespace constexpr auto delayed_events_version = std::uint32_t{3U}; constexpr auto delayed_events_name = std::string_view{"delayed_events"}; + // Migration 004 (ADR-0832): migrations/004_livekit_delegations.sql records it. + constexpr auto livekit_delegations_version = std::uint32_t{4U}; + constexpr auto livekit_delegations_name = std::string_view{"livekit_delegations"}; + [[nodiscard]] auto make_create_table_statement(SchemaTableDefinition const& table) -> std::optional { @@ -346,18 +350,29 @@ auto downgrade_delayed_events_migration() -> MigrationStep return schema_step_dropping(delayed_events_version, "drop_delayed_events"); } -// The next migration is v4: add its upgrade step at the end here, its downgrade -// (to v3) at the front of the downgrade catalog, and its tables to +auto livekit_delegations_migration() -> MigrationStep +{ + return schema_step_creating(livekit_delegations_version, livekit_delegations_name); +} + +auto downgrade_livekit_delegations_migration() -> MigrationStep +{ + return schema_step_dropping(livekit_delegations_version, "drop_livekit_delegations"); +} + +// The next migration is v5: add its upgrade step at the end here, its downgrade +// (to v4) at the front of the downgrade catalog, and its tables to // schema_definitions_added_by. Never change an earlier step. auto upgrade_migration_catalog() -> std::vector { - return {initial_schema_migration(), oauth_tables_migration(), delayed_events_migration()}; + return {initial_schema_migration(), oauth_tables_migration(), delayed_events_migration(), + livekit_delegations_migration()}; } auto downgrade_migration_catalog() -> std::vector { - return {downgrade_delayed_events_migration(), downgrade_oauth_tables_migration(), - downgrade_initial_schema_migration()}; + return {downgrade_livekit_delegations_migration(), downgrade_delayed_events_migration(), + downgrade_oauth_tables_migration(), downgrade_initial_schema_migration()}; } auto migration_plan_between(std::uint32_t current_version, std::uint32_t target_version) -> MigrationPlan diff --git a/src/database/PostgresqlStore.cpp b/src/database/PostgresqlStore.cpp index 9268d0dbd..75287c36b 100644 --- a/src/database/PostgresqlStore.cpp +++ b/src/database/PostgresqlStore.cpp @@ -9,6 +9,7 @@ #include "merovingian/canonicaljson/Serializer.hpp" #include "merovingian/database/ConnectionPool.hpp" #include "merovingian/database/DelayedEventRowText.hpp" +#include "merovingian/database/LiveKitDelegationRowText.hpp" #include "merovingian/database/Migration.hpp" #include "merovingian/database/PostgresqlConnection.hpp" #include "merovingian/database/PostgresqlConnectionDeleter.hpp" @@ -1450,6 +1451,32 @@ namespace } } + // Migration 004 (ADR-0832): LiveKit delegations, main only. A row with an empty or over-long field, a + // created_ms that is not digits, or a duplicate delay ID or key is skipped and counted, never repaired. + if (table_load_profile_includes("livekit_delegations", profile)) + { + auto delegations = query_rows(connection, "postgresql_load_livekit_delegations", + "SELECT delay_id, user_id, room_id, slot_id, member_id, created_ms FROM " + "livekit_delegations ORDER BY delay_id"); + if (!delegations.ok) + { + return false; + } + for (auto const& row : delegations.rows) + { + auto parsed = parse_livekit_delegation_row(row); + if (!parsed.has_value()) + { + ++store.livekit_delegation_rows_skipped_at_load; + continue; + } + if (!store.livekit_delegations.insert(std::move(*parsed))) + { + ++store.livekit_delegation_rows_skipped_at_load; + } + } + } + if (table_load_profile_includes("appservice_txn_cursor", profile)) { auto appservice_txn_cursor_result = diff --git a/src/database/Schema.cpp b/src/database/Schema.cpp index 4256772ae..24491f64f 100644 --- a/src/database/Schema.cpp +++ b/src/database/Schema.cpp @@ -22,7 +22,7 @@ namespace // never an edit to core_tables that changes what v1 creates. Each later // version's tables and indexes are an array of their own, below core_indexes // (ADR-0778). - constexpr auto schema_version = std::uint32_t{3U}; + constexpr auto schema_version = std::uint32_t{4U}; constexpr auto core_tables = std::array{ SchemaTableDefinition{"schema_migrations", @@ -293,6 +293,20 @@ namespace SchemaIndexDefinition{"idx_delayed_events_user_id", "delayed_events", "user_id"}, }; + // Migration 004 (ADR-0832): MSC4195 delegated delayed leaves, one row per delegation. Every column is TEXT like the + // rest of the schema: `created_ms` is decimal text. No foreign key: the store keeps its rules in code. + constexpr auto livekit_delegation_tables = std::array{ + SchemaTableDefinition{"livekit_delegations", + "delay_id TEXT PRIMARY KEY, user_id TEXT NOT NULL, room_id TEXT NOT NULL, " + "slot_id TEXT NOT NULL, member_id TEXT NOT NULL, created_ms TEXT NOT NULL"}, + }; + + // The delete at account deactivation reads a user's rows by user ID; the store answers every other lookup from + // memory. + constexpr auto livekit_delegation_indexes = std::array{ + SchemaIndexDefinition{"idx_livekit_delegations_user_id", "livekit_delegations", "user_id"}, + }; + template auto append_all(std::vector& into, std::array const& from) -> void { @@ -305,7 +319,8 @@ namespace return known.name == index.name && known.table == index.table && known.columns_sql == index.columns_sql; }; return std::ranges::any_of(core_indexes, same) || std::ranges::any_of(oauth_indexes, same) || - std::ranges::any_of(delayed_event_indexes, same); + std::ranges::any_of(delayed_event_indexes, same) || + std::ranges::any_of(livekit_delegation_indexes, same); } [[nodiscard]] auto index_sql(SchemaIndexDefinition const& index, std::string_view prefix) @@ -351,6 +366,10 @@ auto schema_definitions_added_by(std::uint32_t version) -> std::vector std::vector std::optio { return *delayed; } + if (auto const delegation = std::ranges::find_if(livekit_delegation_tables, named); + delegation != livekit_delegation_tables.end()) + { + return *delegation; + } return std::nullopt; } diff --git a/src/database/SqliteStore.cpp b/src/database/SqliteStore.cpp index 031b3eceb..66e92f90a 100644 --- a/src/database/SqliteStore.cpp +++ b/src/database/SqliteStore.cpp @@ -9,6 +9,7 @@ #include "merovingian/database/ConnectionPool.hpp" #include "merovingian/database/DelayedEventRowText.hpp" #include "merovingian/database/ExaminedRows.hpp" +#include "merovingian/database/LiveKitDelegationRowText.hpp" #include "merovingian/database/Migration.hpp" #include "merovingian/database/MigrationStep.hpp" #include "merovingian/database/PersistentAccountData.hpp" @@ -792,6 +793,38 @@ namespace }); } + // Migration 004 (ADR-0832): LiveKit delegations. A row with an empty or over-long field, a created_ms that is not + // digits, or a duplicate delay ID or key is skipped and counted, never repaired. Skipped for a profile that does + // not include the table, as PostgreSQL does. + [[nodiscard]] auto load_livekit_delegation_rows(sqlite3& connection, PersistentStore& store, + TableLoadProfile profile) -> bool + { + if (!table_load_profile_includes("livekit_delegations", profile)) + { + return true; + } + return load_rows(connection, + "SELECT delay_id, user_id, room_id, slot_id, member_id, created_ms FROM livekit_delegations " + "ORDER BY delay_id", + [&store](sqlite3_stmt& row) { + auto columns = std::array{}; + for (auto index = std::size_t{0U}; index < columns.size(); ++index) + { + columns[index] = column_text(row, static_cast(index)); + } + auto parsed = parse_livekit_delegation_row(columns); + if (!parsed.has_value()) + { + ++store.livekit_delegation_rows_skipped_at_load; + return; + } + if (!store.livekit_delegations.insert(std::move(*parsed))) + { + ++store.livekit_delegation_rows_skipped_at_load; + } + }); + } + // Events go to `hydrated_events` rather than `store.events`, for the caller to index in one pass // (ADR-0215): the SELECT has no ORDER BY, so adding them one at a time could shift the // stream-order index for every row. @@ -805,6 +838,12 @@ namespace { return false; } + // Migration 004 (ADR-0832): LiveKit delegations, loaded the same way and for the same reason: the table depends + // on no other table and none depends on it. + if (!load_livekit_delegation_rows(connection, store, profile)) + { + return false; + } // Tables load in dependency order and the chain short-circuits: the first failed SELECT // fails the whole load, so a partially read store is never served. return load_rows(connection, "SELECT user_id, password_hash, locked, suspended, admin, deactivated FROM users", diff --git a/src/database/meson.build b/src/database/meson.build index e7ca77857..eb89f6ea0 100644 --- a/src/database/meson.build +++ b/src/database/meson.build @@ -4,6 +4,9 @@ database_sources = files( 'DelayedEventStatusText.cpp', 'DelayedEventStore.cpp', 'DelayedEventTable.cpp', + 'LiveKitDelegationRowText.cpp', + 'LiveKitDelegationStore.cpp', + 'LiveKitDelegationTable.cpp', 'EventTable.cpp', 'EventStateGroupTable.cpp', 'ForwardExtremityTable.cpp', diff --git a/src/homeserver/AuthService.cpp b/src/homeserver/AuthService.cpp index 412d003fc..9309eaac7 100644 --- a/src/homeserver/AuthService.cpp +++ b/src/homeserver/AuthService.cpp @@ -27,6 +27,7 @@ #include "merovingian/crypto/TokenHmacKeys.hpp" #include "merovingian/crypto/TokenKey.hpp" #include "merovingian/database/DelayedEventStore.hpp" +#include "merovingian/database/LiveKitDelegationStore.hpp" #include "merovingian/database/OAuthStore.hpp" #include "merovingian/federation/KeySignatures.hpp" #include "merovingian/homeserver/AccountSummary.hpp" @@ -2597,6 +2598,16 @@ auto deactivate_user_account(HomeserverRuntime& runtime, std::string_view user_i }, observability::LogEventSeverity::warning); } + // Every LiveKit delegation of the account goes too (MSC4195, ADR-0832): a deactivated account keeps no delayed + // leave alive. A failure is logged and deactivation goes on. + if (!database::delete_livekit_delegations_of_user(runtime.database.persistent_store, user_id)) + { + log_diagnostic("account.deactivated.livekit_delegations_removal_failed", + { + {"user_id", std::string{user_id}, false} + }, + observability::LogEventSeverity::warning); + } // The password hash is replaced with a value no password can produce, so a // credential leak predating deactivation cannot be replayed even if a future // change were to soften the login gate. diff --git a/src/main.cpp b/src/main.cpp index 0c36d3fc8..b23e6d833 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -1275,6 +1275,13 @@ struct ListenerBinding final LOG_WARNING("delayed_events.rows_skipped_at_load: " + std::to_string(skipped) + " delayed event rows were not read and stay in the database"); } + // Likewise for LiveKit delegation rows (ADR-0832): the count only, never a row's columns. + if (auto const skipped = runtime.homeserver.database.persistent_store.livekit_delegation_rows_skipped_at_load; + skipped != 0U) + { + LOG_WARNING("livekit_delegations.rows_skipped_at_load: " + std::to_string(skipped) + + " LiveKit delegation rows were not read and stay in the database"); + } // Wire federation callbacks and start the outbound dispatch worker now that // the runtime is in its final stable location (no further moves). Doing this // eagerly means thread-creation failure surfaces at startup with a clear log diff --git a/tests/integration/test_database_upgrade_flow.cpp b/tests/integration/test_database_upgrade_flow.cpp index 6ea453e73..0f4858f65 100644 --- a/tests/integration/test_database_upgrade_flow.cpp +++ b/tests/integration/test_database_upgrade_flow.cpp @@ -827,6 +827,7 @@ SCENARIO("A SQLite schema is built at v1 and stops there", "[database][upgrade][ REQUIRE_FALSE(has_table(migrated.state, "oauth_clients")); REQUIRE_FALSE(has_table(migrated.state, "oauth_sessions")); REQUIRE_FALSE(has_table(migrated.state, "delayed_events")); + REQUIRE_FALSE(has_table(migrated.state, "livekit_delegations")); REQUIRE(sqlite_count(path, "SELECT count(*) FROM sqlite_master WHERE name LIKE 'oauth%'") == 0); } } @@ -992,10 +993,12 @@ SCENARIO("A SQLite database migrated from v1 holds exactly the schema a fresh on REQUIRE(migrated.ok); REQUIRE(fresh.ok); REQUIRE(migrated.store.schema.version == merovingian::database::current_schema_version()); - REQUIRE(migrated.store.schema.applied_migrations.back().name == "delayed_events"); - REQUIRE(sqlite_count(migrated_path, "SELECT count(*) FROM schema_migrations") == 3); + REQUIRE(migrated.store.schema.applied_migrations.back().name == "livekit_delegations"); + REQUIRE(sqlite_count(migrated_path, "SELECT count(*) FROM schema_migrations") == 4); REQUIRE(sqlite_count(migrated_path, "SELECT count(*) FROM delayed_events") == 0); REQUIRE(migrated.store.delayed_events.size() == 0U); + REQUIRE(sqlite_count(migrated_path, "SELECT count(*) FROM livekit_delegations") == 0); + REQUIRE(migrated.store.livekit_delegations.size() == 0U); REQUIRE(sqlite_count(migrated_path, "SELECT count(*) FROM oauth_clients") == 0); REQUIRE(sqlite_count(migrated_path, "SELECT count(*) FROM oauth_sessions") == 0); REQUIRE(migrated.store.oauth.client_count() == 0U); @@ -1110,6 +1113,7 @@ SCENARIO("A PostgreSQL schema is built at v1 and stops there", "[database][upgra REQUIRE_FALSE(has_table(migrated.state, "oauth_clients")); REQUIRE_FALSE(has_table(migrated.state, "oauth_sessions")); REQUIRE_FALSE(has_table(migrated.state, "delayed_events")); + REQUIRE_FALSE(has_table(migrated.state, "livekit_delegations")); REQUIRE(pg_count(scratch.conninfo(), "SELECT count(*) FROM information_schema.tables WHERE " "table_schema = 'public' AND table_name LIKE 'oauth%'") == 0); } @@ -1244,8 +1248,9 @@ SCENARIO("A PostgreSQL database migrated from v1 holds exactly the schema a fres REQUIRE(migrated.ok); REQUIRE(fresh.ok); REQUIRE(migrated.store.schema.version == merovingian::database::current_schema_version()); - REQUIRE(pg_count(migrated_scratch.conninfo(), "SELECT count(*) FROM schema_migrations") == 3); + REQUIRE(pg_count(migrated_scratch.conninfo(), "SELECT count(*) FROM schema_migrations") == 4); REQUIRE(pg_count(migrated_scratch.conninfo(), "SELECT count(*) FROM delayed_events") == 0); + REQUIRE(pg_count(migrated_scratch.conninfo(), "SELECT count(*) FROM livekit_delegations") == 0); REQUIRE(pg_count(migrated_scratch.conninfo(), "SELECT count(*) FROM oauth_clients") == 0); REQUIRE(pg_count(migrated_scratch.conninfo(), "SELECT count(*) FROM oauth_sessions") == 0); auto const migrated_shape = pg_schema_shape(migrated_scratch.conninfo()); @@ -1359,6 +1364,8 @@ SCENARIO("The 1.0.3 release's own SQLite database is migrated and served by this sqlite_count(path, "SELECT count(*) FROM sqlite_master WHERE name LIKE 'oauth%'"); auto const delayed_objects_before = sqlite_count(path, "SELECT count(*) FROM sqlite_master WHERE name LIKE '%delayed_events%'"); + auto const delegation_objects_before = + sqlite_count(path, "SELECT count(*) FROM sqlite_master WHERE name LIKE '%livekit_delegations%'"); WHEN("the migration path runs on it and the current runtime starts on the result") { @@ -1377,6 +1384,12 @@ SCENARIO("The 1.0.3 release's own SQLite database is migrated and served by this "'scheduled', '0', '', '')") && sqlite_count(path, "SELECT count(*) FROM delayed_events WHERE delay_id = 'upgrade-probe'") == 1 && sqlite_execute(path, "DELETE FROM delayed_events WHERE delay_id = 'upgrade-probe'"); + // Version 4's table takes a row and gives it back the same way. + auto const livekit_delegations_usable = + sqlite_execute(path, "INSERT INTO livekit_delegations VALUES ('upgrade-probe', '@u:x', '!r:x', " + "'slot', 'member', '1000')") && + sqlite_count(path, "SELECT count(*) FROM livekit_delegations WHERE delay_id = 'upgrade-probe'") == 1 && + sqlite_execute(path, "DELETE FROM livekit_delegations WHERE delay_id = 'upgrade-probe'"); auto started = merovingian::homeserver::start_client_server( sqlite_fixture_config(path, master_key, expected.server_name)); REQUIRE(started.started); @@ -1390,10 +1403,11 @@ SCENARIO("The 1.0.3 release's own SQLite database is migrated and served by this REQUIRE(ledger_rows_before == 1); REQUIRE(oauth_objects_before == 0); REQUIRE(delayed_objects_before == 0); + REQUIRE(delegation_objects_before == 0); REQUIRE(migrated.state.version == merovingian::database::current_schema_version()); REQUIRE(static_cast(migrated.state.version) > expected.schema_version); REQUIRE(static_cast(migrated.state.applied_migrations.size()) > ledger_rows_before); - REQUIRE(migrated.state.applied_migrations.back().name == "delayed_events"); + REQUIRE(migrated.state.applied_migrations.back().name == "livekit_delegations"); REQUIRE(sqlite_count(path, "SELECT count(*) FROM schema_migrations") == static_cast(migrated.state.applied_migrations.size())); REQUIRE(sqlite_count(path, "SELECT count(*) FROM oauth_clients") == 0); @@ -1402,6 +1416,10 @@ SCENARIO("The 1.0.3 release's own SQLite database is migrated and served by this "name = 'idx_oauth_sessions_client_id'") == 1); REQUIRE(oauth_tables_usable); REQUIRE(delayed_events_usable); + REQUIRE(livekit_delegations_usable); + REQUIRE(sqlite_count(path, "SELECT count(*) FROM livekit_delegations") == 0); + REQUIRE(sqlite_count(path, "SELECT count(*) FROM sqlite_master WHERE type = 'index' AND " + "name = 'idx_livekit_delegations_user_id'") == 1); REQUIRE(sqlite_count(path, "SELECT count(*) FROM delayed_events") == 0); REQUIRE(sqlite_count(path, "SELECT count(*) FROM sqlite_master WHERE type = 'index' AND " "name = 'idx_delayed_events_user_id'") == 1); @@ -1442,6 +1460,9 @@ SCENARIO("The 1.0.3 release's own PostgreSQL database is migrated and served by auto const delayed_tables_before = pg_count(scratch.conninfo(), "SELECT count(*) FROM information_schema.tables WHERE " "table_schema = 'public' AND table_name = 'delayed_events'"); + auto const delegation_tables_before = + pg_count(scratch.conninfo(), "SELECT count(*) FROM information_schema.tables WHERE " + "table_schema = 'public' AND table_name = 'livekit_delegations'"); WHEN("the migration path runs on it and the current runtime starts on the result") { @@ -1460,6 +1481,12 @@ SCENARIO("The 1.0.3 release's own PostgreSQL database is migrated and served by pg_count(scratch.conninfo(), "SELECT count(*) FROM delayed_events WHERE delay_id = 'upgrade-probe'") == 1 && pg_execute(scratch.conninfo(), "DELETE FROM delayed_events WHERE delay_id = 'upgrade-probe'"); + auto const livekit_delegations_usable = + pg_execute(scratch.conninfo(), "INSERT INTO livekit_delegations VALUES ('upgrade-probe', '@u:x', " + "'!r:x', 'slot', 'member', '1000')") && + pg_count(scratch.conninfo(), + "SELECT count(*) FROM livekit_delegations WHERE delay_id = 'upgrade-probe'") == 1 && + pg_execute(scratch.conninfo(), "DELETE FROM livekit_delegations WHERE delay_id = 'upgrade-probe'"); auto started = merovingian::homeserver::start_client_server( postgresql_fixture_config(uri_file, master_key, expected.server_name)); REQUIRE(started.started); @@ -1473,14 +1500,16 @@ SCENARIO("The 1.0.3 release's own PostgreSQL database is migrated and served by REQUIRE(ledger_rows_before == 1); REQUIRE(oauth_tables_before == 0); REQUIRE(delayed_tables_before == 0); + REQUIRE(delegation_tables_before == 0); REQUIRE(migrated.state.version == merovingian::database::current_schema_version()); REQUIRE(static_cast(migrated.state.version) > expected.schema_version); REQUIRE(static_cast(migrated.state.applied_migrations.size()) > ledger_rows_before); - REQUIRE(migrated.state.applied_migrations.back().name == "delayed_events"); + REQUIRE(migrated.state.applied_migrations.back().name == "livekit_delegations"); REQUIRE(pg_count(scratch.conninfo(), "SELECT count(*) FROM schema_migrations") == static_cast(migrated.state.applied_migrations.size())); REQUIRE(oauth_tables_usable); REQUIRE(delayed_events_usable); + REQUIRE(livekit_delegations_usable); REQUIRE(started.runtime.homeserver.database.schema_version == merovingian::database::current_schema_version()); require_fixture_served(view, expected); diff --git a/tests/integration/test_persistent_homeserver_flow.cpp b/tests/integration/test_persistent_homeserver_flow.cpp index e77a99ddf..b30b6241b 100644 --- a/tests/integration/test_persistent_homeserver_flow.cpp +++ b/tests/integration/test_persistent_homeserver_flow.cpp @@ -788,9 +788,10 @@ SCENARIO("Persistent homeserver runtime bootstraps a fresh migrated schema", "[d REQUIRE(applied.size() == merovingian::database::current_schema_version()); REQUIRE(applied.front().direction == merovingian::database::MigrationDirection::upgrade); REQUIRE(applied.front().name == "initial_schema"); - REQUIRE(applied.back().name == "delayed_events"); + REQUIRE(applied.back().name == "livekit_delegations"); REQUIRE(merovingian::homeserver::database_has_table(started.runtime.database, "oauth_clients")); REQUIRE(merovingian::homeserver::database_has_table(started.runtime.database, "delayed_events")); + REQUIRE(merovingian::homeserver::database_has_table(started.runtime.database, "livekit_delegations")); REQUIRE(merovingian::homeserver::database_has_table(started.runtime.database, "oauth_sessions")); } } diff --git a/tests/integration/test_postgresql_store_behaviour_flow.cpp b/tests/integration/test_postgresql_store_behaviour_flow.cpp index 46dab422a..643499fe0 100644 --- a/tests/integration/test_postgresql_store_behaviour_flow.cpp +++ b/tests/integration/test_postgresql_store_behaviour_flow.cpp @@ -11,6 +11,7 @@ #include #include #include +#include #include #include #include @@ -1937,3 +1938,70 @@ SCENARIO("PostgreSQL hydration skips delayed event rows that are not read exactl } } } + +SCENARIO("PostgreSQL LiveKit delegations survive a reopen, replace by key and by delay ID, and leave with the account", + "[database][postgresql][integration][pg-behaviour][livekit-delegations]") +{ + GIVEN("three delegations of two users, one of them replaced by a new delay ID for the same key") + { + auto const uri = postgresql_uri(); + if (uri.empty()) + { + SUCCEED("skipped: MEROVINGIAN_TEST_POSTGRESQL_URI is not set"); + return; + } + auto opened = reopen(uri); + auto const suffix = unique_suffix(); + auto const alice = "@delegation-a-" + suffix + ":example.org"; + auto const bob = "@delegation-b-" + suffix + ":example.org"; + auto const room_id = "!delegation-" + suffix + ":example.org"; + auto const make = [&](std::string id, std::string const& user, std::string member) { + return db::PersistentLiveKitDelegation{"dl-" + id + "-" + suffix, user, room_id, "slot-" + suffix, + std::move(member), 123'456'789U}; + }; + REQUIRE(db::store_livekit_delegation(opened.store, make("old", alice, "member-1"))); + REQUIRE(db::store_livekit_delegation(opened.store, make("two", alice, "member-2"))); + REQUIRE(db::store_livekit_delegation(opened.store, make("bob", bob, "member-1"))); + REQUIRE(db::store_livekit_delegation(opened.store, make("new", alice, "member-1"))); + REQUIRE(db::store_livekit_delegation(opened.store, make("two", alice, "member-3"))); + REQUIRE(db::store_livekit_delegation(opened.store, make("gone", bob, "member-9"))); + REQUIRE(db::delete_livekit_delegation(opened.store, "dl-gone-" + suffix)); + + WHEN("the store is reopened") + { + opened = {}; + auto reopened = reopen(uri); + auto const& table = reopened.store.livekit_delegations; + + THEN("exactly the surviving rows are back with every column, and the lookups answer") + { + REQUIRE(table.find("dl-old-" + suffix) == nullptr); + REQUIRE(table.find("dl-gone-" + suffix) == nullptr); + REQUIRE(table.find("dl-new-" + suffix) != nullptr); + REQUIRE(table.find("dl-new-" + suffix)->user_id == alice); + REQUIRE(table.find("dl-new-" + suffix)->room_id == room_id); + REQUIRE(table.find("dl-new-" + suffix)->slot_id == "slot-" + suffix); + REQUIRE(table.find("dl-new-" + suffix)->member_id == "member-1"); + REQUIRE(table.find("dl-new-" + suffix)->created_ms == 123'456'789U); + REQUIRE(table.find("dl-two-" + suffix)->member_id == "member-3"); + REQUIRE(table.find_by_key(alice, room_id, "slot-" + suffix, "member-2") == nullptr); + REQUIRE(table.find_by_key(alice, room_id, "slot-" + suffix, "member-1") == + table.find("dl-new-" + suffix)); + REQUIRE(table.find_by_key(bob, room_id, "slot-" + suffix, "member-1") == + table.find("dl-bob-" + suffix)); + REQUIRE(table.count_of_user(alice) == 2U); + REQUIRE(table.count_of_user(bob) == 1U); + } + + AND_THEN("deleting both users' rows removes them from the database as well") + { + REQUIRE(db::delete_livekit_delegations_of_user(reopened.store, alice)); + REQUIRE(db::delete_livekit_delegations_of_user(reopened.store, bob)); + auto again = reopen(uri); + REQUIRE(again.store.livekit_delegations.find("dl-new-" + suffix) == nullptr); + REQUIRE(again.store.livekit_delegations.find("dl-bob-" + suffix) == nullptr); + REQUIRE(again.store.livekit_delegations.count_of_user(alice) == 0U); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index 6f0129064..0a25cfa97 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -357,6 +357,8 @@ shell = find_program('sh') 'unit/test_database_oauth_store.cpp', 'unit/test_delayed_event_store.cpp', 'unit/test_delayed_event_table.cpp', + 'unit/test_livekit_delegation_store.cpp', + 'unit/test_livekit_delegation_table.cpp', 'unit/test_media_reservation_sweep.cpp', 'unit/test_credential_tables.cpp', 'unit/test_bundled_aggregations.cpp', diff --git a/tests/smoke/meson.build b/tests/smoke/meson.build index 1271c6330..bb40c5367 100644 --- a/tests/smoke/meson.build +++ b/tests/smoke/meson.build @@ -622,3 +622,25 @@ test( + '" | grep -q "current_version=0 target_version=3 steps=3"', ], ) + +# Migration 004: a plan from v3 takes the checked-in 004 file alone, and a plan from an empty database takes all four +# (ADR-0778). +test( + 'db-migrate-plans-v3-to-v4-from-files-smoke-test', + smoke_test, + args: [ + '-c', + db_migrate_executable + ' --plan 3 4 --migrations "' + migrations_directory + + '" | grep -q "current_version=3 target_version=4 steps=1"', + ], +) + +test( + 'db-migrate-plans-empty-to-v4-from-files-smoke-test', + smoke_test, + args: [ + '-c', + db_migrate_executable + ' --plan 0 4 --migrations "' + migrations_directory + + '" | grep -q "current_version=0 target_version=4 steps=4"', + ], +) diff --git a/tests/unit/test_database_persistence.cpp b/tests/unit/test_database_persistence.cpp index 05d542d66..432248d9f 100644 --- a/tests/unit/test_database_persistence.cpp +++ b/tests/unit/test_database_persistence.cpp @@ -1332,7 +1332,7 @@ SCENARIO("Database migration plans are contiguous and direction-aware", "[databa } } -SCENARIO("Database migration runner applies the v1, v2 and v3 schema steps and their explicit downgrades", +SCENARIO("Database migration runner applies the v1 to v4 schema steps and their explicit downgrades", "[database][migration]") { GIVEN("an empty schema state") @@ -1348,34 +1348,38 @@ SCENARIO("Database migration runner applies the v1, v2 and v3 schema steps and t auto const downgrade_plan = merovingian::database::migration_plan_between(upgraded.state.version, 0U); auto const downgraded = merovingian::database::apply_migration_plan(upgraded.state, downgrade_plan); - THEN("v1, v2 then v3 build the whole current schema, and three steps take it away newest first") + THEN("v1 to v4 build the whole current schema, and four steps take it away newest first") { - REQUIRE(merovingian::database::current_schema_version() == 3U); + REQUIRE(merovingian::database::current_schema_version() == 4U); REQUIRE(upgrade_plan.direction == merovingian::database::MigrationDirection::upgrade); REQUIRE(upgrade_plan.current_version == 0U); - REQUIRE(upgrade_plan.target_version == 3U); - REQUIRE(upgrade_plan.steps.size() == 3U); + REQUIRE(upgrade_plan.target_version == 4U); + REQUIRE(upgrade_plan.steps.size() == 4U); REQUIRE(upgrade_plan.steps[0].version == 1U); REQUIRE(upgrade_plan.steps[0].name == "initial_schema"); REQUIRE(upgrade_plan.steps[1].version == 2U); REQUIRE(upgrade_plan.steps[1].name == "oauth_tables"); REQUIRE(upgrade_plan.steps[2].version == 3U); REQUIRE(upgrade_plan.steps[2].name == "delayed_events"); + REQUIRE(upgrade_plan.steps[3].version == 4U); + REQUIRE(upgrade_plan.steps[3].name == "livekit_delegations"); REQUIRE(upgraded.ok); - REQUIRE(upgraded.state.version == 3U); - REQUIRE(upgraded.state.applied_migrations.size() == 3U); + REQUIRE(upgraded.state.version == 4U); + REQUIRE(upgraded.state.applied_migrations.size() == 4U); REQUIRE(upgraded.state.applied_migrations.front().name == "initial_schema"); - REQUIRE(upgraded.state.applied_migrations.back().name == "delayed_events"); + REQUIRE(upgraded.state.applied_migrations.back().name == "livekit_delegations"); REQUIRE(upgraded.state.tables.size() == merovingian::database::current_schema_tables().size()); REQUIRE(compatible.valid); REQUIRE(second_plan.steps.empty()); REQUIRE(downgrade_plan.direction == merovingian::database::MigrationDirection::downgrade); - REQUIRE(downgrade_plan.steps.size() == 3U); - REQUIRE(downgrade_plan.steps[0].name == "drop_delayed_events"); - REQUIRE(downgrade_plan.steps[0].version == 2U); - REQUIRE(downgrade_plan.steps[1].name == "drop_oauth_tables"); - REQUIRE(downgrade_plan.steps[1].version == 1U); - REQUIRE(downgrade_plan.steps[2].name == "drop_initial_schema"); + REQUIRE(downgrade_plan.steps.size() == 4U); + REQUIRE(downgrade_plan.steps[0].name == "drop_livekit_delegations"); + REQUIRE(downgrade_plan.steps[0].version == 3U); + REQUIRE(downgrade_plan.steps[1].name == "drop_delayed_events"); + REQUIRE(downgrade_plan.steps[1].version == 2U); + REQUIRE(downgrade_plan.steps[2].name == "drop_oauth_tables"); + REQUIRE(downgrade_plan.steps[2].version == 1U); + REQUIRE(downgrade_plan.steps[3].name == "drop_initial_schema"); REQUIRE(downgraded.ok); REQUIRE(downgraded.state.version == 0U); REQUIRE(downgraded.state.tables.empty()); @@ -1402,8 +1406,8 @@ SCENARIO("The v1 schema step creates every table in its final shape and every in THEN("each v1 table is created whole, by exactly the DDL the registry describes") { - REQUIRE(merovingian::database::upgrade_migration_catalog().size() == 3U); - REQUIRE(merovingian::database::downgrade_migration_catalog().size() == 3U); + REQUIRE(merovingian::database::upgrade_migration_catalog().size() == 4U); + REQUIRE(merovingian::database::downgrade_migration_catalog().size() == 4U); for (auto const& table : tables) { INFO("table " << table.name); @@ -1416,6 +1420,8 @@ SCENARIO("The v1 schema step creates every table in its final shape and every in REQUIRE(statement_sql("create_oauth_sessions").empty()); REQUIRE(statement_sql("create_delayed_events").empty()); REQUIRE(statement_sql("create_idx_delayed_events_user_id").empty()); + REQUIRE(statement_sql("create_livekit_delegations").empty()); + REQUIRE(statement_sql("create_idx_livekit_delegations_user_id").empty()); } AND_THEN("every column the pre-1.0 chain ALTERed on is part of its table's CREATE") @@ -1514,8 +1520,8 @@ SCENARIO("The v2 schema step adds only the OAuth 2.0 tables and their index", "[ "device_id))"); REQUIRE(step.statements[2].sql == "CREATE INDEX idx_oauth_sessions_client_id ON oauth_sessions (client_id)"); - // Version 2 adds two tables; version 3 adds one more. - REQUIRE(current.size() == initial.size() + 3U); + // Version 2 adds two tables; versions 3 and 4 add one each. + REQUIRE(current.size() == initial.size() + 4U); REQUIRE(std::ranges::find(initial, std::string_view{"oauth_clients"}) == initial.end()); REQUIRE(std::ranges::find(current, std::string_view{"oauth_clients"}) != current.end()); REQUIRE(std::ranges::find(current, std::string_view{"oauth_sessions"}) != current.end()); @@ -1570,7 +1576,7 @@ SCENARIO("The v3 schema step adds only the delayed-events table and its user ind "TEXT NOT NULL)"); REQUIRE(step.statements[1].sql == "CREATE INDEX idx_delayed_events_user_id ON delayed_events (user_id)"); - REQUIRE(current.size() == initial.size() + 3U); + REQUIRE(current.size() == initial.size() + 4U); REQUIRE(std::ranges::find(initial, std::string_view{"delayed_events"}) == initial.end()); REQUIRE(std::ranges::find(current, std::string_view{"delayed_events"}) != current.end()); REQUIRE(merovingian::database::schema_definitions_added_by(2U).size() == 2U); @@ -1588,6 +1594,59 @@ SCENARIO("The v3 schema step adds only the delayed-events table and its user ind } } +SCENARIO("The v4 schema step adds only the LiveKit delegations table and its user index", + "[database][migration][livekit-delegations]") +{ + GIVEN("the v4 schema step, its downgrade and the current table inventory") + { + auto const step = merovingian::database::livekit_delegations_migration(); + auto const downgrade = merovingian::database::downgrade_livekit_delegations_migration(); + auto const initial = merovingian::database::initial_schema_tables(); + auto const current = merovingian::database::current_schema_tables(); + + WHEN("its statements are inspected") + { + auto const names = [&step]() { + auto collected = std::vector{}; + for (auto const& statement : step.statements) + { + collected.push_back(statement.name); + } + return collected; + }(); + + THEN("it creates livekit_delegations with six TEXT columns and the user index, and nothing else") + { + REQUIRE(step.version == 4U); + REQUIRE(step.name == "livekit_delegations"); + REQUIRE(step.direction == merovingian::database::MigrationDirection::upgrade); + REQUIRE(names == std::vector{"create_livekit_delegations", + "create_idx_livekit_delegations_user_id"}); + REQUIRE(step.statements[0].sql == + "CREATE TABLE \"livekit_delegations\" (delay_id TEXT PRIMARY KEY, user_id TEXT NOT NULL, " + "room_id TEXT NOT NULL, slot_id TEXT NOT NULL, member_id TEXT NOT NULL, created_ms TEXT NOT " + "NULL)"); + REQUIRE(step.statements[1].sql == + "CREATE INDEX idx_livekit_delegations_user_id ON livekit_delegations (user_id)"); + REQUIRE(std::ranges::find(initial, std::string_view{"livekit_delegations"}) == initial.end()); + REQUIRE(std::ranges::find(current, std::string_view{"livekit_delegations"}) != current.end()); + REQUIRE(merovingian::database::schema_definitions_added_by(3U).size() == 1U); + REQUIRE(merovingian::database::schema_definitions_added_by(4U).size() == 1U); + REQUIRE(merovingian::database::schema_indexes_added_by(4U).size() == 1U); + REQUIRE(merovingian::database::schema_table_definition("livekit_delegations").has_value()); + } + + AND_THEN("its downgrade drops only that table, back to version 3") + { + REQUIRE(downgrade.version == 3U); + REQUIRE(downgrade.name == "drop_livekit_delegations"); + REQUIRE(downgrade.statements.size() == 1U); + REQUIRE(downgrade.statements[0].sql.find("livekit_delegations") != std::string::npos); + } + } + } +} + SCENARIO("A schema ledger naming a migration this build does not have is refused", "[database][migration][collapse][security]") { @@ -2482,7 +2541,7 @@ SCENARIO("Checked-in migrations hold exactly the steps this build runs", "[datab } SCENARIO("An offline plan takes only the migration files between its two versions", - "[database][migration][files][oauth][delayed-events]") + "[database][migration][files][oauth][delayed-events][livekit-delegations]") { GIVEN("the repository migration directory and the migration role") { @@ -2493,28 +2552,34 @@ SCENARIO("An offline plan takes only the migration files between its two version auto migration_config = merovingian::config::DatabaseConfig{}; migration_config.role = merovingian::config::DatabaseRole::migration; - WHEN("plans from v1, from v2 and from nothing to v3 are built from the files") + WHEN("plans from v1, from v2, from v3 and from nothing to v4 are built from the files") { auto const from_v1 = - merovingian::database::build_offline_migration_plan(migration_config, 1U, 3U, loaded.steps); + merovingian::database::build_offline_migration_plan(migration_config, 1U, 4U, loaded.steps); auto const from_v2 = - merovingian::database::build_offline_migration_plan(migration_config, 2U, 3U, loaded.steps); + merovingian::database::build_offline_migration_plan(migration_config, 2U, 4U, loaded.steps); + auto const from_v3 = + merovingian::database::build_offline_migration_plan(migration_config, 3U, 4U, loaded.steps); auto const from_empty = - merovingian::database::build_offline_migration_plan(migration_config, 0U, 3U, loaded.steps); + merovingian::database::build_offline_migration_plan(migration_config, 0U, 4U, loaded.steps); auto const no_op = - merovingian::database::build_offline_migration_plan(migration_config, 3U, 3U, loaded.steps); + merovingian::database::build_offline_migration_plan(migration_config, 4U, 4U, loaded.steps); - THEN("a v1 database gets 002 then 003, a v2 one 003 alone, an empty one all three, a v3 one nothing") + THEN("a v1 database gets 002 to 004, a v2 one 003 and 004, a v3 one 004 alone, an empty one all four, a v4 " + "one nothing") { REQUIRE(from_v1.ok); - REQUIRE(from_v1.plan.steps.size() == 2U); + REQUIRE(from_v1.plan.steps.size() == 3U); REQUIRE(from_v1.plan.steps.front().name == "oauth_tables"); - REQUIRE(from_v1.plan.steps.back().name == "delayed_events"); + REQUIRE(from_v1.plan.steps.back().name == "livekit_delegations"); REQUIRE(from_v2.ok); - REQUIRE(from_v2.plan.steps.size() == 1U); + REQUIRE(from_v2.plan.steps.size() == 2U); REQUIRE(from_v2.plan.steps.front().name == "delayed_events"); + REQUIRE(from_v3.ok); + REQUIRE(from_v3.plan.steps.size() == 1U); + REQUIRE(from_v3.plan.steps.front().name == "livekit_delegations"); REQUIRE(from_empty.ok); - REQUIRE(from_empty.plan.steps.size() == 3U); + REQUIRE(from_empty.plan.steps.size() == 4U); REQUIRE(from_empty.plan.steps.front().name == "initial_schema"); REQUIRE(no_op.ok); REQUIRE(no_op.plan.steps.empty()); @@ -2570,10 +2635,11 @@ SCENARIO("Database schema inventory covers the core Matrix tables", "[database][ THEN("required Matrix storage areas have table-specific definitions") { // The pre-1.0 migration chain collapsed into v1's 64 tables; migration 002 (1.1.0) adds the two - // OAuth 2.0 tables and migration 003 (1.1.2) the delayed-events table. + // OAuth 2.0 tables, migration 003 (1.1.2) the delayed-events table and migration 004 the LiveKit + // delegations table. REQUIRE(tables.size() == 64U); - REQUIRE(merovingian::database::current_schema_version() == 3U); - REQUIRE(merovingian::database::current_schema_tables().size() == 67U); + REQUIRE(merovingian::database::current_schema_version() == 4U); + REQUIRE(merovingian::database::current_schema_tables().size() == 68U); REQUIRE(users_definition.has_value()); REQUIRE(current_state_definition.has_value()); REQUIRE(room_aliases_definition.has_value()); diff --git a/tests/unit/test_livekit_delegation_store.cpp b/tests/unit/test_livekit_delegation_store.cpp new file mode 100644 index 000000000..883573d60 --- /dev/null +++ b/tests/unit/test_livekit_delegation_store.cpp @@ -0,0 +1,661 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The LiveKit delegation store functions (migration 004, ADR-0832): what each refuses, that a write is one +// transaction with bound parameters only, that memory changes only after a commit, replacement by key and by delay ID, +// the delete at deactivation, and a round trip through a SQLite file with strict hydration. +#include "../support/TempDirectory.hpp" +#include "merovingian/database/BoundValue.hpp" +#include "merovingian/database/LiveKitDelegationRowText.hpp" +#include "merovingian/database/LiveKitDelegationStore.hpp" +#include "merovingian/database/LiveKitDelegationTable.hpp" +#include "merovingian/database/PersistentLiveKitDelegation.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/database/PersistentStoreOpenResult.hpp" +#include "merovingian/database/PreparedStatement.hpp" +#include "merovingian/database/TableLoadProfile.hpp" + +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +namespace db = merovingian::database; +using db::PersistentLiveKitDelegation; + +constexpr auto alice = std::string_view{"@alice:example.org"}; +constexpr auto bob = std::string_view{"@bob:example.org"}; + +[[nodiscard]] auto delegation(std::string delay_id, std::string_view user = alice, std::string_view member = "member-1") + -> PersistentLiveKitDelegation +{ + return {std::move(delay_id), std::string{user}, "!room:example.org", "slot-1", std::string{member}, 1'000U}; +} + +[[nodiscard]] auto opened_store() -> db::PersistentStoreOpenResult +{ + auto opened = db::open_persistent_store(); + REQUIRE(opened.ok); + return opened; +} + +struct SqliteClose final +{ + auto operator()(sqlite3* connection) const noexcept -> void + { + sqlite3_close(connection); + } +}; + +// Runs one query on its own connection to the file and returns the text of its first column of its first row. +[[nodiscard]] auto sqlite_first_text(std::filesystem::path const& path, char const* sql) -> std::string +{ + auto* raw = static_cast(nullptr); + auto const opened = sqlite3_open_v2(path.string().c_str(), &raw, SQLITE_OPEN_READONLY, nullptr); + auto const connection = std::unique_ptr{raw}; + auto text = std::string{}; + if (opened != SQLITE_OK) + { + return text; + } + auto* statement = static_cast(nullptr); + if (sqlite3_prepare_v2(connection.get(), sql, -1, &statement, nullptr) == SQLITE_OK && + sqlite3_step(statement) == SQLITE_ROW) + { + auto const* value = sqlite3_column_text(statement, 0); + if (value != nullptr) + { + // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast) + text = reinterpret_cast(value); + } + } + sqlite3_finalize(statement); + return text; +} + +using RawRow = std::array; + +// The six columns of a valid row, as the text the store writes, for a test to change one of. +[[nodiscard]] auto raw_row(std::string delay_id) -> RawRow +{ + return {std::move(delay_id), std::string{alice}, "!room:example.org", "slot-9", "member-9", "1000"}; +} + +// Writes `values` to the store's database as one row of `livekit_delegations`, without touching memory (a +// bound-parameter insert, so any text goes in), the way a damaged or foreign file would hold it. +[[nodiscard]] auto insert_raw_row(db::PersistentStore& store, RawRow const& values) -> bool +{ + auto statement = db::PreparedStatement{ + "insert_raw_livekit_delegation", + "INSERT INTO livekit_delegations (delay_id, user_id, room_id, slot_id, member_id, created_ms) VALUES ($1, $2, " + "$3, $4, $5, $6)", + {}}; + for (auto const& value : values) + { + statement.parameters.push_back(db::BoundValue{value, false}); + } + return db::commit_persistent_transaction(store, {statement}); +} + +[[nodiscard]] auto temporary_database(std::string_view stem) -> std::filesystem::path +{ + return merovingian::tests::temporary_directory() / + (std::string{stem} + std::to_string(std::chrono::steady_clock::now().time_since_epoch().count()) + + ".sqlite3"); +} + +struct RawRowCase final +{ + std::string_view name{}; + std::size_t column{0U}; + std::string_view value{}; +}; + +} // namespace + +SCENARIO("A LiveKit delegation is stored, and a field outside its rules is refused", + "[database][livekit-delegations][delegation-store]") +{ + GIVEN("an in-memory store") + { + auto opened = opened_store(); + auto& store = opened.store; + + WHEN("a valid row is stored") + { + auto const stored = db::store_livekit_delegation(store, delegation("d-1")); + + THEN("memory holds it under both lookups") + { + REQUIRE(stored); + REQUIRE(store.livekit_delegations.size() == 1U); + REQUIRE(store.livekit_delegations.find("d-1") != nullptr); + REQUIRE(store.livekit_delegations.find("d-1")->created_ms == 1'000U); + REQUIRE(store.livekit_delegations.find_by_key(alice, "!room:example.org", "slot-1", "member-1") == + store.livekit_delegations.find("d-1")); + REQUIRE(store.livekit_delegations.count_of_user(alice) == 1U); + } + } + + WHEN("a row breaking one rule is stored") + { + auto const broken = GENERATE( + std::pair{"an empty delay ID", delegation("")}, + std::pair{ + "a 65-byte delay ID", delegation(std::string(db::max_livekit_delegation_delay_id_bytes + 1U, 'd'))}, + std::pair{"an empty user", delegation("d-1", "")}, + std::pair{ + "a 256-byte user", + delegation("d-1", std::string(db::max_livekit_delegation_field_bytes + 1U, 'u'))}, + std::pair{"an empty room", + [] { + auto made = delegation("d-1"); + made.room_id.clear(); + return made; + }()}, + std::pair{ + "a 256-byte room", + [] { + auto made = delegation("d-1"); + made.room_id = std::string(db::max_livekit_delegation_field_bytes + 1U, 'r'); + return made; + }()}, + std::pair{"an empty slot", + [] { + auto made = delegation("d-1"); + made.slot_id.clear(); + return made; + }()}, + std::pair{ + "a 256-byte slot", + [] { + auto made = delegation("d-1"); + made.slot_id = std::string(db::max_livekit_delegation_field_bytes + 1U, 's'); + return made; + }()}, + std::pair{"an empty member", + delegation("d-1", alice, "")}, + std::pair{ + "a 256-byte member", + delegation("d-1", alice, std::string(db::max_livekit_delegation_field_bytes + 1U, 'm'))}, + std::pair{"a NUL byte in the delay ID", + delegation(std::string{"d\0x", 3U})}); + INFO(broken.first); + db::enable_statement_capture(store, 16U); + auto const before = db::committed_transaction_count(store); + auto const stored = db::store_livekit_delegation(store, broken.second); + + THEN("it is refused, nothing is written and memory is unchanged") + { + REQUIRE_FALSE(stored); + REQUIRE(db::committed_transaction_count(store) == before); + REQUIRE(store.captured_statements.empty()); + REQUIRE(store.livekit_delegations.size() == 0U); + } + } + + WHEN("rows exactly at the caps are stored") + { + auto at_cap = delegation(std::string(db::max_livekit_delegation_delay_id_bytes, 'd')); + at_cap.user_id = std::string(db::max_livekit_delegation_field_bytes, 'u'); + at_cap.room_id = std::string(db::max_livekit_delegation_field_bytes, 'r'); + at_cap.slot_id = std::string(db::max_livekit_delegation_field_bytes, 's'); + at_cap.member_id = std::string(db::max_livekit_delegation_field_bytes, 'm'); + + THEN("the row is stored") + { + REQUIRE(db::store_livekit_delegation(store, at_cap)); + REQUIRE(store.livekit_delegations.size() == 1U); + } + } + } +} + +SCENARIO("A new delegation replaces the one holding its key or its delay ID in one transaction", + "[database][livekit-delegations][delegation-store]") +{ + GIVEN("a store holding two delegations of one user") + { + auto opened = opened_store(); + auto& store = opened.store; + REQUIRE(db::store_livekit_delegation(store, delegation("d-1", alice, "member-1"))); + REQUIRE(db::store_livekit_delegation(store, delegation("d-2", alice, "member-2"))); + REQUIRE(db::store_livekit_delegation(store, delegation("d-3", bob, "member-1"))); + + WHEN("a delegation for the same key but a new delay ID is stored") + { + auto replacement = delegation("d-new", alice, "member-1"); + replacement.created_ms = 5'000U; + auto const before = db::committed_transaction_count(store); + auto const stored = db::store_livekit_delegation(store, replacement); + + THEN("the old delay ID is gone, the key answers the new row, and it was one transaction") + { + REQUIRE(stored); + REQUIRE(db::committed_transaction_count(store) - before == 1U); + REQUIRE(store.livekit_delegations.size() == 3U); + REQUIRE(store.livekit_delegations.find("d-1") == nullptr); + REQUIRE(store.livekit_delegations.find("d-new") != nullptr); + REQUIRE(store.livekit_delegations.find("d-new")->created_ms == 5'000U); + REQUIRE(store.livekit_delegations.find_by_key(alice, "!room:example.org", "slot-1", "member-1") == + store.livekit_delegations.find("d-new")); + REQUIRE(store.livekit_delegations.count_of_user(alice) == 2U); + } + } + + WHEN("a delegation for a new key but a delay ID already held is stored") + { + auto const before = db::committed_transaction_count(store); + auto const stored = db::store_livekit_delegation(store, delegation("d-2", alice, "member-3")); + + THEN("the old row under that delay ID is gone, the new key answers it, and it was one transaction") + { + REQUIRE(stored); + REQUIRE(db::committed_transaction_count(store) - before == 1U); + REQUIRE(store.livekit_delegations.size() == 3U); + REQUIRE(store.livekit_delegations.find("d-2")->member_id == "member-3"); + REQUIRE(store.livekit_delegations.find_by_key(alice, "!room:example.org", "slot-1", "member-2") == + nullptr); + REQUIRE(store.livekit_delegations.find_by_key(alice, "!room:example.org", "slot-1", "member-3") == + store.livekit_delegations.find("d-2")); + } + } + + WHEN("a delegation holding the key of one row and the delay ID of another is stored") + { + auto const stored = db::store_livekit_delegation(store, delegation("d-2", alice, "member-1")); + + THEN("both old rows are replaced by the one new row") + { + REQUIRE(stored); + REQUIRE(store.livekit_delegations.size() == 2U); + REQUIRE(store.livekit_delegations.find("d-1") == nullptr); + REQUIRE(store.livekit_delegations.find("d-2")->member_id == "member-1"); + REQUIRE(store.livekit_delegations.find("d-3") != nullptr); + REQUIRE(store.livekit_delegations.count_of_user(alice) == 1U); + } + } + + WHEN("the same delegation is stored again") + { + auto const stored = db::store_livekit_delegation(store, delegation("d-1", alice, "member-1")); + + THEN("it is accepted and there is still one row for it") + { + REQUIRE(stored); + REQUIRE(store.livekit_delegations.size() == 3U); + REQUIRE(store.livekit_delegations.find("d-1") != nullptr); + } + } + + WHEN("the commit of a replacement fails") + { + db::force_next_persist_failures(store, 1U); + auto const stored = db::store_livekit_delegation(store, delegation("d-new", alice, "member-1")); + + THEN("it reports the failure and memory still holds the old row") + { + REQUIRE_FALSE(stored); + REQUIRE(store.livekit_delegations.size() == 3U); + REQUIRE(store.livekit_delegations.find("d-1") != nullptr); + REQUIRE(store.livekit_delegations.find("d-new") == nullptr); + REQUIRE(store.livekit_delegations.find_by_key(alice, "!room:example.org", "slot-1", "member-1") == + store.livekit_delegations.find("d-1")); + } + } + } +} + +SCENARIO("A LiveKit delegation is written with bound parameters only", + "[database][livekit-delegations][delegation-store]") +{ + GIVEN("a memory store capturing statements") + { + auto opened = opened_store(); + auto& store = opened.store; + db::enable_statement_capture(store, 16U); + + WHEN("a delegation is stored, replaced and deleted, and a user's rows are deleted") + { + REQUIRE(db::store_livekit_delegation(store, delegation("d-1"))); + REQUIRE(db::delete_livekit_delegation(store, "d-1")); + REQUIRE(db::delete_livekit_delegations_of_user(store, alice)); + auto const& captured = store.captured_statements; + + THEN("every statement uses $n placeholders and none carries a value") + { + REQUIRE(captured.size() == 5U); + for (auto const& statement : captured) + { + INFO("statement " << statement.name); + REQUIRE(statement.sql.find('$') != std::string::npos); + REQUIRE(statement.sql.find("d-1") == std::string::npos); + REQUIRE(statement.sql.find(std::string{alice}) == std::string::npos); + REQUIRE(statement.sql.find("member-1") == std::string::npos); + } + REQUIRE(captured[0].name == "delete_livekit_delegation_by_key"); + REQUIRE(captured[0].parameters.size() == 4U); + REQUIRE(captured[1].name == "delete_livekit_delegation_by_delay_id"); + REQUIRE(captured[2].name == "insert_livekit_delegation"); + REQUIRE(captured[2].parameters.size() == 6U); + REQUIRE(captured[2].sql.find("$6") != std::string::npos); + REQUIRE(captured[2].parameters[0].value == "d-1"); + REQUIRE(captured[2].parameters[5].value == "1000"); + REQUIRE(captured[3].sql == "DELETE FROM livekit_delegations WHERE delay_id = $1"); + REQUIRE(captured[4].sql == "DELETE FROM livekit_delegations WHERE user_id = $1"); + REQUIRE(captured[4].parameters[0].value == std::string{alice}); + } + } + } +} + +SCENARIO("A delegation is deleted by delay ID, and a failed commit leaves it in memory", + "[database][livekit-delegations][delegation-store]") +{ + GIVEN("a store holding two delegations") + { + auto opened = opened_store(); + auto& store = opened.store; + REQUIRE(db::store_livekit_delegation(store, delegation("d-1", alice, "member-1"))); + REQUIRE(db::store_livekit_delegation(store, delegation("d-2", alice, "member-2"))); + + WHEN("one is deleted, and then a delay ID that is not held") + { + auto const deleted = db::delete_livekit_delegation(store, "d-1"); + auto const absent = db::delete_livekit_delegation(store, "d-none"); + + THEN("both report success and only the first row is gone") + { + REQUIRE(deleted); + REQUIRE(absent); + REQUIRE(store.livekit_delegations.size() == 1U); + REQUIRE(store.livekit_delegations.find("d-1") == nullptr); + REQUIRE(store.livekit_delegations.find_by_key(alice, "!room:example.org", "slot-1", "member-1") == + nullptr); + REQUIRE(store.livekit_delegations.find("d-2") != nullptr); + REQUIRE(store.livekit_delegations.count_of_user(alice) == 1U); + } + } + + WHEN("the commit of a delete fails") + { + db::force_next_persist_failures(store, 1U); + auto const deleted = db::delete_livekit_delegation(store, "d-1"); + + THEN("it reports the failure and memory is exactly as it was") + { + REQUIRE_FALSE(deleted); + REQUIRE(store.livekit_delegations.size() == 2U); + REQUIRE(store.livekit_delegations.find("d-1") != nullptr); + } + } + } +} + +SCENARIO("All of a user's LiveKit delegations are deleted in one statement", + "[database][livekit-delegations][delegation-store]") +{ + GIVEN("a store holding delegations of two users") + { + auto opened = opened_store(); + auto& store = opened.store; + REQUIRE(db::store_livekit_delegation(store, delegation("d-1", alice, "member-1"))); + REQUIRE(db::store_livekit_delegation(store, delegation("d-2", alice, "member-2"))); + REQUIRE(db::store_livekit_delegation(store, delegation("d-3", bob, "member-1"))); + + WHEN("one user's delegations are deleted") + { + auto const before = db::committed_transaction_count(store); + auto const deleted = db::delete_livekit_delegations_of_user(store, alice); + + THEN("they go in one transaction and the other user's stay") + { + REQUIRE(deleted); + REQUIRE(db::committed_transaction_count(store) - before == 1U); + REQUIRE(store.livekit_delegations.size() == 1U); + REQUIRE(store.livekit_delegations.count_of_user(alice) == 0U); + REQUIRE(store.livekit_delegations.find("d-3") != nullptr); + } + } + + WHEN("the commit of that delete fails") + { + db::force_next_persist_failures(store, 1U); + auto const deleted = db::delete_livekit_delegations_of_user(store, alice); + + THEN("it reports the failure and memory is exactly as it was") + { + REQUIRE_FALSE(deleted); + REQUIRE(store.livekit_delegations.size() == 3U); + REQUIRE(store.livekit_delegations.count_of_user(alice) == 2U); + } + } + + WHEN("a user with no delegations is deleted") + { + auto const before = db::committed_transaction_count(store); + auto const deleted = db::delete_livekit_delegations_of_user(store, "@nobody:example.org"); + + THEN("the DELETE still runs, so a row hydration skipped does not outlive the account") + { + REQUIRE(deleted); + REQUIRE(db::committed_transaction_count(store) - before == 1U); + REQUIRE(store.livekit_delegations.size() == 3U); + } + } + } +} + +SCENARIO("Deactivation deletes a LiveKit delegation that exists only in the database", + "[database][livekit-delegations][delegation-store][sqlite]") +{ + GIVEN("a SQLite file holding a delegation memory never loaded") + { + auto const path = temporary_database("merovingian-livekit-delegations-skipped-"); + { + auto opened = db::open_sqlite_persistent_store(path.string()); + REQUIRE(opened.ok); + REQUIRE(insert_raw_row(opened.store, raw_row("z-hidden"))); + REQUIRE(opened.store.livekit_delegations.size() == 0U); + + WHEN("the user's delegations are deleted") + { + REQUIRE(db::delete_livekit_delegations_of_user(opened.store, alice)); + + THEN("the row is gone from the file") + { + REQUIRE(sqlite_first_text(path, "SELECT count(*) FROM livekit_delegations") == "0"); + } + } + } + std::filesystem::remove(path); + } +} + +SCENARIO("LiveKit delegations survive a reopen of a SQLite store with every column and index", + "[database][livekit-delegations][delegation-store][sqlite]") +{ + GIVEN("a SQLite store holding three delegations of two users, one replaced and one deleted") + { + auto const path = temporary_database("merovingian-livekit-delegations-"); + { + auto opened = db::open_sqlite_persistent_store(path.string()); + REQUIRE(opened.ok); + auto first = delegation("d-1", alice, "member-1"); + first.created_ms = 123'456'789U; + REQUIRE(db::store_livekit_delegation(opened.store, first)); + REQUIRE(db::store_livekit_delegation(opened.store, delegation("d-2", alice, "member-2"))); + REQUIRE(db::store_livekit_delegation(opened.store, delegation("d-3", bob, "member-1"))); + REQUIRE(db::store_livekit_delegation(opened.store, delegation("d-4", bob, "member-1"))); + REQUIRE(db::store_livekit_delegation(opened.store, delegation("d-5", bob, "member-9"))); + REQUIRE(db::delete_livekit_delegation(opened.store, "d-5")); + } + + WHEN("the store is opened again") + { + auto reopened = db::open_sqlite_persistent_store(path.string()); + REQUIRE(reopened.ok); + auto const& table = reopened.store.livekit_delegations; + + THEN("exactly the surviving rows are back with every column, and the lookups answer") + { + REQUIRE(table.size() == 3U); + REQUIRE(table.find("d-1") != nullptr); + REQUIRE(table.find("d-1")->user_id == std::string{alice}); + REQUIRE(table.find("d-1")->room_id == "!room:example.org"); + REQUIRE(table.find("d-1")->slot_id == "slot-1"); + REQUIRE(table.find("d-1")->member_id == "member-1"); + REQUIRE(table.find("d-1")->created_ms == 123'456'789U); + REQUIRE(table.find("d-3") == nullptr); + REQUIRE(table.find("d-4") != nullptr); + REQUIRE(table.find("d-5") == nullptr); + REQUIRE(table.find_by_key(bob, "!room:example.org", "slot-1", "member-1") == table.find("d-4")); + REQUIRE(table.count_of_user(alice) == 2U); + REQUIRE(table.count_of_user(bob) == 1U); + REQUIRE(reopened.store.livekit_delegation_rows_skipped_at_load == 0U); + } + } + + WHEN("a user's delegations are deleted and the store is opened again") + { + { + auto opened = db::open_sqlite_persistent_store(path.string()); + REQUIRE(opened.ok); + REQUIRE(db::delete_livekit_delegations_of_user(opened.store, alice)); + } + auto reopened = db::open_sqlite_persistent_store(path.string()); + + THEN("the file agrees with memory") + { + REQUIRE(reopened.ok); + REQUIRE(reopened.store.livekit_delegations.size() == 1U); + REQUIRE(reopened.store.livekit_delegations.find("d-4") != nullptr); + REQUIRE(sqlite_first_text(path, "SELECT count(*) FROM livekit_delegations") == "1"); + } + } + std::filesystem::remove(path); + } +} + +SCENARIO("Hydration reads a LiveKit delegation row strictly and counts the rows it skips", + "[database][livekit-delegations][delegation-store][sqlite]") +{ + GIVEN("a SQLite file holding a valid row and one row that is not read exactly") + { + auto const bad = + GENERATE(RawRowCase{"a created_ms that is not a number", 5U, "abc"}, + RawRowCase{"an empty created_ms", 5U, ""}, RawRowCase{"a negative created_ms", 5U, "-5"}, + RawRowCase{"a created_ms of 21 digits", 5U, "123456789012345678901"}, + RawRowCase{"an empty user", 1U, ""}, RawRowCase{"an empty room", 2U, ""}, + RawRowCase{"an empty slot", 3U, ""}, RawRowCase{"an empty member", 4U, ""}); + INFO(bad.name); + auto const path = temporary_database("merovingian-livekit-delegations-strict-"); + { + auto opened = db::open_sqlite_persistent_store(path.string()); + REQUIRE(opened.ok); + REQUIRE(db::store_livekit_delegation(opened.store, delegation("m-good"))); + auto damaged = raw_row("z-bad"); + damaged[bad.column] = std::string{bad.value}; + REQUIRE(insert_raw_row(opened.store, damaged)); + } + + WHEN("the store is opened") + { + auto reopened = db::open_sqlite_persistent_store(path.string()); + + THEN("the row is not loaded, stays in the file and is counted, and the valid row loads") + { + REQUIRE(reopened.ok); + REQUIRE(reopened.store.livekit_delegations.size() == 1U); + REQUIRE(reopened.store.livekit_delegations.find("z-bad") == nullptr); + REQUIRE(reopened.store.livekit_delegations.find("m-good") != nullptr); + REQUIRE(reopened.store.livekit_delegation_rows_skipped_at_load == 1U); + REQUIRE(sqlite_first_text(path, "SELECT count(*) FROM livekit_delegations WHERE delay_id = 'z-bad'") == + "1"); + } + } + std::filesystem::remove(path); + } +} + +SCENARIO("Hydration skips a row that duplicates a key or an over-long field and counts it", + "[database][livekit-delegations][delegation-store][sqlite]") +{ + GIVEN("a SQLite file holding a row, a second row with its key, and a row with an over-long delay ID") + { + auto const path = temporary_database("merovingian-livekit-delegations-dup-"); + { + auto opened = db::open_sqlite_persistent_store(path.string()); + REQUIRE(opened.ok); + REQUIRE(db::store_livekit_delegation(opened.store, delegation("a-first", alice, "member-1"))); + auto same_key = raw_row("z-second"); + same_key[3] = "slot-1"; + same_key[4] = "member-1"; + REQUIRE(insert_raw_row(opened.store, same_key)); + REQUIRE(insert_raw_row(opened.store, + raw_row(std::string(db::max_livekit_delegation_delay_id_bytes + 1U, 'x')))); + } + + WHEN("the store is opened") + { + auto reopened = db::open_sqlite_persistent_store(path.string()); + + THEN("the first row keeps the key, the other two are skipped and counted, and all stay in the file") + { + REQUIRE(reopened.ok); + REQUIRE(reopened.store.livekit_delegations.size() == 1U); + REQUIRE(reopened.store.livekit_delegations.find("a-first") != nullptr); + REQUIRE(reopened.store.livekit_delegations.find("z-second") == nullptr); + REQUIRE(reopened.store.livekit_delegation_rows_skipped_at_load == 2U); + REQUIRE(sqlite_first_text(path, "SELECT count(*) FROM livekit_delegations") == "3"); + } + } + std::filesystem::remove(path); + } +} + +SCENARIO("A store opened with the federation worker profile does not load LiveKit delegations and leaves them in the " + "file", + "[database][livekit-delegations][delegation-store][sqlite]") +{ + GIVEN("a SQLite store holding two delegations") + { + auto const path = temporary_database("merovingian-livekit-delegations-profile-"); + { + auto opened = db::open_sqlite_persistent_store(path.string()); + REQUIRE(opened.ok); + REQUIRE(db::store_livekit_delegation(opened.store, delegation("d-one"))); + REQUIRE(db::store_livekit_delegation(opened.store, delegation("d-two", bob))); + } + + WHEN("it is opened with the full profile and with the federation worker profile") + { + auto const full = db::open_sqlite_persistent_store(path.string(), db::TableLoadProfile::full); + auto const worker = + db::open_sqlite_persistent_store(path.string(), db::TableLoadProfile::federation_worker); + + THEN("the full profile loads both, the worker profile loads none and counts no skipped row") + { + REQUIRE(full.ok); + REQUIRE(full.store.livekit_delegations.size() == 2U); + REQUIRE(worker.ok); + REQUIRE(worker.store.livekit_delegations.size() == 0U); + REQUIRE(worker.store.livekit_delegation_rows_skipped_at_load == 0U); + REQUIRE(sqlite_first_text(path, "SELECT count(*) FROM livekit_delegations") == "2"); + } + } + std::filesystem::remove(path); + } +} diff --git a/tests/unit/test_livekit_delegation_table.cpp b/tests/unit/test_livekit_delegation_table.cpp new file mode 100644 index 000000000..6e193df50 --- /dev/null +++ b/tests/unit/test_livekit_delegation_table.cpp @@ -0,0 +1,310 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The in-memory LiveKit delegations table (migration 004, ADR-0832): what it refuses, the lookups by delay ID and by +// key, the per-user count, insertion order, and that every erase keeps the indexes right. +#include "merovingian/database/LiveKitDelegationRowText.hpp" +#include "merovingian/database/LiveKitDelegationTable.hpp" +#include "merovingian/database/PersistentLiveKitDelegation.hpp" + +#include +#include + +#include +#include +#include +#include +#include +#include + +namespace +{ + +namespace db = merovingian::database; +using db::PersistentLiveKitDelegation; + +constexpr auto alice = std::string_view{"@alice:example.org"}; +constexpr auto bob = std::string_view{"@bob:example.org"}; + +[[nodiscard]] auto delegation(std::string delay_id, std::string_view user = alice, std::string_view member = "member-1") + -> PersistentLiveKitDelegation +{ + return {std::move(delay_id), std::string{user}, "!room:example.org", "slot-1", std::string{member}, 1'000U}; +} + +} // namespace + +SCENARIO("The delegations table finds a row by delay ID and by key", + "[database][livekit-delegations][delegation-table]") +{ + GIVEN("a table holding two rows of one user and one of another") + { + auto table = db::LiveKitDelegationTable{}; + REQUIRE(table.insert(delegation("d-1", alice, "member-1"))); + REQUIRE(table.insert(delegation("d-2", alice, "member-2"))); + REQUIRE(table.insert(delegation("d-3", bob, "member-1"))); + + WHEN("the rows are looked up") + { + THEN("each lookup answers the row, the count is per user and the rows keep insertion order") + { + REQUIRE(table.size() == 3U); + REQUIRE(table.find("d-2") != nullptr); + REQUIRE(table.find("d-2")->member_id == "member-2"); + REQUIRE(table.find("d-2")->created_ms == 1'000U); + REQUIRE(table.find("d-none") == nullptr); + REQUIRE(table.find_by_key(alice, "!room:example.org", "slot-1", "member-2") == table.find("d-2")); + REQUIRE(table.find_by_key(bob, "!room:example.org", "slot-1", "member-1") == table.find("d-3")); + REQUIRE(table.find_by_key(bob, "!room:example.org", "slot-1", "member-2") == nullptr); + REQUIRE(table.find_by_key(alice, "!other:example.org", "slot-1", "member-1") == nullptr); + REQUIRE(table.find_by_key(alice, "!room:example.org", "slot-2", "member-1") == nullptr); + REQUIRE(table.count_of_user(alice) == 2U); + REQUIRE(table.count_of_user(bob) == 1U); + REQUIRE(table.count_of_user("@nobody:example.org") == 0U); + REQUIRE(table.rows().size() == 3U); + REQUIRE(table.rows()[0].delay_id == "d-1"); + REQUIRE(table.rows()[1].delay_id == "d-2"); + REQUIRE(table.rows()[2].delay_id == "d-3"); + } + } + + WHEN("the key parts are shifted between fields so the joined text would be the same") + { + THEN("a key that differs in one part finds nothing") + { + REQUIRE(table.find_by_key("@alice:example.org!room:example.org", "slot-1", "member-1", "") == nullptr); + REQUIRE(table.find_by_key(alice, "!room:example.orgslot-1", "member-1", "") == nullptr); + } + } + } +} + +SCENARIO("The delegations table refuses a row that is not storable or that duplicates a delay ID or a key", + "[database][livekit-delegations][delegation-table]") +{ + GIVEN("a table holding one row") + { + auto table = db::LiveKitDelegationTable{}; + REQUIRE(table.insert(delegation("d-1"))); + + WHEN("rows are inserted that break a rule") + { + auto const same_delay_id = table.insert(delegation("d-1", bob)); + auto const same_key = table.insert(delegation("d-other")); + auto empty_delay_id = delegation(""); + auto empty_user = delegation("d-2"); + empty_user.user_id.clear(); + auto empty_room = delegation("d-3"); + empty_room.room_id.clear(); + auto empty_slot = delegation("d-4"); + empty_slot.slot_id.clear(); + auto empty_member = delegation("d-5"); + empty_member.member_id.clear(); + auto long_delay_id = delegation(std::string(db::max_livekit_delegation_delay_id_bytes + 1U, 'd')); + auto long_user = delegation("d-6"); + long_user.user_id = std::string(db::max_livekit_delegation_field_bytes + 1U, 'u'); + auto long_room = delegation("d-7"); + long_room.room_id = std::string(db::max_livekit_delegation_field_bytes + 1U, 'r'); + auto long_slot = delegation("d-8"); + long_slot.slot_id = std::string(db::max_livekit_delegation_field_bytes + 1U, 's'); + auto long_member = delegation("d-9"); + long_member.member_id = std::string(db::max_livekit_delegation_field_bytes + 1U, 'm'); + auto nul_slot = delegation("d-10"); + nul_slot.slot_id = std::string{"a\0b", 3U}; + + THEN("each is refused and the table is unchanged") + { + REQUIRE_FALSE(same_delay_id); + REQUIRE_FALSE(same_key); + REQUIRE_FALSE(table.insert(empty_delay_id)); + REQUIRE_FALSE(table.insert(empty_user)); + REQUIRE_FALSE(table.insert(empty_room)); + REQUIRE_FALSE(table.insert(empty_slot)); + REQUIRE_FALSE(table.insert(empty_member)); + REQUIRE_FALSE(table.insert(long_delay_id)); + REQUIRE_FALSE(table.insert(long_user)); + REQUIRE_FALSE(table.insert(long_room)); + REQUIRE_FALSE(table.insert(long_slot)); + REQUIRE_FALSE(table.insert(long_member)); + REQUIRE_FALSE(table.insert(nul_slot)); + REQUIRE(table.size() == 1U); + REQUIRE(table.count_of_user(alice) == 1U); + REQUIRE(table.count_of_user(bob) == 0U); + } + } + + WHEN("rows exactly at the caps are inserted") + { + auto at_cap = delegation(std::string(db::max_livekit_delegation_delay_id_bytes, 'd')); + at_cap.user_id = std::string(db::max_livekit_delegation_field_bytes, 'u'); + at_cap.room_id = std::string(db::max_livekit_delegation_field_bytes, 'r'); + at_cap.slot_id = std::string(db::max_livekit_delegation_field_bytes, 's'); + at_cap.member_id = std::string(db::max_livekit_delegation_field_bytes, 'm'); + + THEN("the row is stored") + { + REQUIRE(table.insert(at_cap)); + REQUIRE(table.size() == 2U); + } + } + } +} + +SCENARIO("Erasing from the delegations table keeps every index right", + "[database][livekit-delegations][delegation-table]") +{ + GIVEN("a table holding four rows of two users") + { + auto table = db::LiveKitDelegationTable{}; + REQUIRE(table.insert(delegation("d-1", alice, "member-1"))); + REQUIRE(table.insert(delegation("d-2", bob, "member-1"))); + REQUIRE(table.insert(delegation("d-3", alice, "member-2"))); + REQUIRE(table.insert(delegation("d-4", bob, "member-2"))); + + WHEN("a row is erased by delay ID") + { + auto const erased = table.erase("d-2"); + auto const again = table.erase("d-2"); + + THEN("the later rows are still found by both lookups, in order, and the count dropped") + { + REQUIRE(erased); + REQUIRE_FALSE(again); + REQUIRE(table.size() == 3U); + REQUIRE(table.find("d-2") == nullptr); + REQUIRE(table.find("d-3")->member_id == "member-2"); + REQUIRE(table.find_by_key(bob, "!room:example.org", "slot-1", "member-2") == table.find("d-4")); + REQUIRE(table.find_by_key(bob, "!room:example.org", "slot-1", "member-1") == nullptr); + REQUIRE(table.count_of_user(bob) == 1U); + REQUIRE(table.count_of_user(alice) == 2U); + REQUIRE(table.rows()[1].delay_id == "d-3"); + } + + AND_THEN("the erased key and delay ID can be inserted again") + { + REQUIRE(table.insert(delegation("d-2", bob, "member-1"))); + REQUIRE(table.rows().back().delay_id == "d-2"); + } + } + + WHEN("a row is erased by key") + { + auto const erased = table.erase_key(alice, "!room:example.org", "slot-1", "member-1"); + auto const again = table.erase_key(alice, "!room:example.org", "slot-1", "member-1"); + + THEN("it is gone by delay ID too, and the rest are unchanged") + { + REQUIRE(erased); + REQUIRE_FALSE(again); + REQUIRE(table.find("d-1") == nullptr); + REQUIRE(table.size() == 3U); + REQUIRE(table.count_of_user(alice) == 1U); + REQUIRE(table.find("d-4") != nullptr); + } + } + + WHEN("every row of one user is erased") + { + auto const removed = table.erase_user(alice); + auto const none = table.erase_user("@nobody:example.org"); + + THEN("the other user's rows remain and the count is returned") + { + REQUIRE(removed == 2U); + REQUIRE(none == 0U); + REQUIRE(table.size() == 2U); + REQUIRE(table.count_of_user(alice) == 0U); + REQUIRE(table.find("d-1") == nullptr); + REQUIRE(table.find("d-3") == nullptr); + REQUIRE(table.find("d-4")->user_id == std::string{bob}); + } + } + + WHEN("the table is cleared and a copy is taken before") + { + auto const copy = table; + table.clear(); + + THEN("the table is empty and the copy still answers every lookup") + { + REQUIRE(table.size() == 0U); + REQUIRE(table.find("d-1") == nullptr); + REQUIRE(table.count_of_user(alice) == 0U); + REQUIRE(copy.size() == 4U); + REQUIRE(copy.find_by_key(alice, "!room:example.org", "slot-1", "member-2") == copy.find("d-3")); + } + } + } +} + +SCENARIO("A stored delegation row is read strictly", "[database][livekit-delegations][delegation-table]") +{ + GIVEN("the six columns of a valid row") + { + auto const valid = std::array{ + "d-1", std::string{alice}, "!room:example.org", "slot-1", "member-1", "123456789"}; + + WHEN("it is read") + { + auto const parsed = db::parse_livekit_delegation_row(valid); + + THEN("every field is carried over") + { + REQUIRE(parsed.has_value()); + REQUIRE(parsed->delay_id == "d-1"); + REQUIRE(parsed->user_id == std::string{alice}); + REQUIRE(parsed->room_id == "!room:example.org"); + REQUIRE(parsed->slot_id == "slot-1"); + REQUIRE(parsed->member_id == "member-1"); + REQUIRE(parsed->created_ms == 123'456'789U); + } + } + + WHEN("one column is damaged") + { + auto const column = GENERATE(std::size_t{0U}, std::size_t{1U}, std::size_t{2U}, std::size_t{3U}, + std::size_t{4U}, std::size_t{5U}); + auto damaged = valid; + damaged[column] = ""; + + THEN("an empty column is not read") + { + REQUIRE_FALSE(db::parse_livekit_delegation_row(damaged).has_value()); + } + } + + WHEN("created_ms is not exactly decimal digits that fit 64 bits") + { + auto const bad = + GENERATE(std::string{"abc"}, std::string{"-5"}, std::string{" 5"}, std::string{"5 "}, + std::string{"1.5"}, std::string{"123456789012345678901"}, std::string{"18446744073709551616"}); + auto damaged = valid; + damaged[5] = bad; + + THEN("the row is not read") + { + INFO(bad); + REQUIRE_FALSE(db::parse_livekit_delegation_row(damaged).has_value()); + } + } + + WHEN("created_ms is the largest 64-bit value, or a field is over its cap, or there are too few columns") + { + auto largest = valid; + largest[5] = "18446744073709551615"; + auto over_long = valid; + over_long[3] = std::string(db::max_livekit_delegation_field_bytes + 1U, 's'); + auto over_long_id = valid; + over_long_id[0] = std::string(db::max_livekit_delegation_delay_id_bytes + 1U, 'd'); + auto const few = std::array{"d-1", std::string{alice}, "!room:example.org"}; + + THEN("the largest value is read and the others are not") + { + REQUIRE(db::parse_livekit_delegation_row(largest).has_value()); + REQUIRE_FALSE(db::parse_livekit_delegation_row(over_long).has_value()); + REQUIRE_FALSE(db::parse_livekit_delegation_row(over_long_id).has_value()); + REQUIRE_FALSE(db::parse_livekit_delegation_row(few).has_value()); + } + } + } +} diff --git a/tests/unit/test_worker_table_load_profile.cpp b/tests/unit/test_worker_table_load_profile.cpp index df4fdfd89..64cfd874e 100644 --- a/tests/unit/test_worker_table_load_profile.cpp +++ b/tests/unit/test_worker_table_load_profile.cpp @@ -205,6 +205,9 @@ namespace // ADR-0824: delayed events (migration 003). Main only: the federation worker sends no events and holds no // signing key, so it never reads a scheduled event. "delayed_events", + // ADR-0832: LiveKit delegations (migration 004). Main only: the token service runs in main and the worker + // keeps no delayed event alive. + "livekit_delegations", // Vestigial: declared in src/database/Schema.cpp's DDL but never // populated or queried by any runtime code path, main's or the // worker's (confirmed by grep finding no reference outside @@ -278,6 +281,7 @@ SCENARIO("The federation_worker load profile excludes every table outside the al REQUIRE_FALSE(merovingian::database::table_load_profile_includes("oauth_clients", profile)); REQUIRE_FALSE(merovingian::database::table_load_profile_includes("oauth_sessions", profile)); REQUIRE_FALSE(merovingian::database::table_load_profile_includes("delayed_events", profile)); + REQUIRE_FALSE(merovingian::database::table_load_profile_includes("livekit_delegations", profile)); } AND_THEN("an arbitrary non-allowlisted table is excluded, proving this is a fail-closed allowlist " "rather than a denylist") From d9af2116a004ae6a1f1bb683652bad389acfc17a Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 14:01:03 +0000 Subject: [PATCH 09/19] Delegate delayed MatrixRTC leaves to the token service and accept the LiveKit webhook MSC4195 delegate_delayed_leave: a joined caller hands the server one delay ID per (room, slot, member). The livekit-delegations job asks LiveKit's GetParticipant (a one-room roomAdmin token, the configured address only, the lock released) and restarts the delayed leave while the participant is connected, or sends it once LiveKit no longer shows them (ADR-0832). Delegations live in migration 004 and go with a cancel, a send, a leave or a deactivation. POST /_merovingian/livekit/webhook is served on the client listener: an HS256 token from the configured key, a body SHA-256 match, a bounded body, staleness and replay checks. It only brings a matching delegation's next check forward; it never changes state itself (ADR-0833). The MSC4195 request readers move to LiveKitRequestFields and the LiveKit test fixture to tests/support/LiveKitTestSupport.hpp, shared by the token and delegation flows. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 12 +- ...figured-address-with-a-token-of-its-own.md | 24 +- ...e-participant-and-sent-once-it-does-not.md | 125 +++ ...ener-and-trusted-only-to-prompt-a-check.md | 94 +++ docs/adr/index.md | 2 + docs/architecture.md | 6 + docs/http-transport.md | 8 +- docs/log-filtering.md | 2 +- docs/matrix-v1.19-client-server-api.md | 1 + docs/threat-model.md | 47 +- docs/todos/capability-gaps.md | 1 + docs/user-manual.md | 22 +- .../homeserver/HomeserverRuntime.hpp | 12 + .../homeserver/LiveKitDelegationProgress.hpp | 26 + .../homeserver/LiveKitDelegations.hpp | 68 ++ .../homeserver/LiveKitRequestFields.hpp | 39 + .../homeserver/LiveKitRoomService.hpp | 9 + src/database/AGENTS.md | 9 + src/homeserver/AGENTS.md | 4 +- src/homeserver/ClientServerRuntime.cpp | 194 +++-- src/homeserver/LiveKitDelegations.cpp | 622 +++++++++++++++ src/homeserver/LiveKitRequestFields.cpp | 76 ++ src/homeserver/LiveKitRoomService.cpp | 28 + src/homeserver/LiveKitTokenService.cpp | 133 +--- src/homeserver/meson.build | 2 + src/http/RateLimit.cpp | 4 + src/main.cpp | 49 +- tests/complement/merovingian.conf.template | 2 + .../test_route_query_conformance.cpp | 4 +- .../test_livekit_delegation_flow.cpp | 715 ++++++++++++++++++ tests/integration/test_livekit_token_flow.cpp | 211 +----- tests/meson.build | 1 + tests/support/AGENTS.md | 1 + tests/support/LiveKitTestSupport.hpp | 258 +++++++ 34 files changed, 2391 insertions(+), 420 deletions(-) create mode 100644 docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md create mode 100644 docs/adr/0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md create mode 100644 include/merovingian/homeserver/LiveKitDelegationProgress.hpp create mode 100644 include/merovingian/homeserver/LiveKitDelegations.hpp create mode 100644 include/merovingian/homeserver/LiveKitRequestFields.hpp create mode 100644 src/homeserver/LiveKitDelegations.cpp create mode 100644 src/homeserver/LiveKitRequestFields.cpp create mode 100644 tests/integration/test_livekit_delegation_flow.cpp create mode 100644 tests/support/LiveKitTestSupport.hpp diff --git a/CHANGELOG.md b/CHANGELOG.md index df917e127..5deb55d84 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,11 +9,17 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * MatrixRTC calls on LiveKit need no `lk-jwt-service`: `POST .../rtc/livekit/get_token` (MSC4195) issues tokens to joined users; `server.rtc.livekit.url`, `api_url`, `api_key` and `api_secret_file` turn it on (ADR-0829, ADR-0830). +* A token for another server's SFU is relayed to it over federation, and other servers' joined users get subscribe-only + tokens for this server's SFU, judged by the main process (ADR-0831). +* `delegate_delayed_leave` (MSC4195): this server sends a caller's delayed leave once LiveKit no longer shows them, + checked every 30 s and sooner on LiveKit's signed webhook, kept across restarts (ADR-0832, ADR-0833). ## Security Fixes * LiveKit tokens are HS256, signed only by typed functions that cannot grant room creation, administration or hidden participants; the API secret is read per token and never logged (ADR-0828). +* LiveKit's webhook is believed only when signed with the API secret for its exact body and recent, and even then only + brings a check forward: it never sends or restarts an event (ADR-0833). ## Bug fixes @@ -22,9 +28,9 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Release notes -Version 1.1.3 is in progress: a LiveKit token service built into the server for MatrixRTC calls, and an exact -`state_after` on `/sync`. After a restart, the first `state_after` sync of each room with news carries its whole state -once. +Version 1.1.3 is in progress: a LiveKit token service built into the server for MatrixRTC calls, with delegated leaves, +and an exact `state_after` on `/sync`. It adds migration 004 (`livekit_delegations`). After a restart, the first +`state_after` sync of each room with news carries its whole state once. # Version 1.1.2 diff --git a/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md index 03e95ce1a..14c074991 100644 --- a/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md +++ b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md @@ -15,8 +15,8 @@ call is added here. ### Where a call goes * A call goes only to `server.rtc.livekit.api_url`, never to an address a request names. -* `livekit_create_room_request` parses the URL again with `http::parse_outbound_url` and holds it to the - configuration's rule (`https`, or `http` to a loopback IP literal). It rebuilds the URL from the parsed parts with an +* Each request builder (`livekit_create_room_request`, `livekit_get_participant_request`) parses the URL again with + `http::parse_outbound_url` and holds it to the configuration's rule (`https`, or `http` to a loopback IP literal). It rebuilds the URL from the parsed parts with an explicit port and appends `/twirp/livekit.RoomService/`. * `perform_livekit_request` resolves the host with `discovery.upstream().lookup_addresses`, the operator-trusted lookup the application service client uses (ADR-0515). The connection is pinned to the addresses found. @@ -26,10 +26,14 @@ call is added here. ### How a call is made -* Every call is made from a client request with an ADR-0079 slot held, under one deadline, and with `runtime.mutex` +* `CreateRoom` is made from a client request with an ADR-0079 slot held, under one deadline, and with `runtime.mutex` released around the call only (`src/homeserver/AGENTS.md`). -* At most 16 KiB of answer is read (`livekit_response_max_bytes`). Nothing in an answer is trusted or returned to the - client: only the HTTP status is read. +* `GetParticipant` is made by the "livekit-delegations" job (ADR-0832), on its own thread, never from a client request: + it holds no request thread and so takes no ADR-0079 slot. The job takes `runtime.mutex` before and after its calls, + never during one; each call has 10 seconds, and one run makes at most 16 (`livekit_delegation_checks_per_run`). +* At most 16 KiB of answer is read (`livekit_response_max_bytes`). Nothing in an answer is returned to a client. Of + `CreateRoom`'s answer only the HTTP status is read; of `GetParticipant`'s only the status, the Twirp error `code` + and the participant's `state`, which decide whether a delayed event is restarted, sent or left alone. ### What each call may do @@ -39,8 +43,12 @@ call is added here. | Call | Method | Grant | When | |---|---|---|---| | Create the room | `POST /twirp/livekit.RoomService/CreateRoom`, body `{"name", "empty_timeout": 300, "departure_timeout": 20}` | `video.roomCreate` only | Before a publishing token is issued (MSC4195 MUST) | +| Look up one participant | `POST /twirp/livekit.RoomService/GetParticipant`, body `{"room", "identity"}` (MSC4195 names) | `video.room` (that room) and `video.roomAdmin` | Each check of a delegated delayed leave (ADR-0832) | -No call removes a participant, ends a room, changes permissions or reads metadata. Adding one is a change to this +LiveKit has no grant narrower than `roomAdmin` for `GetParticipant`, so that token could also act on participants of +its one room for its one minute. It is accepted because it names one room, is sent only to the configured address over +verified TLS (or to a loopback address), and is never stored or logged; this server sends it with `GetParticipant` +alone. No call removes a participant, ends a room, changes permissions or reads metadata. Adding one is a change to this record and a new typed signer, and a call that acts against a participant (for example `RemoveParticipant`) needs the owner's decision first. @@ -51,7 +59,8 @@ owner's decision first. ### Positive Consequences -* A leaked call token can create a room for one minute and nothing else. +* A leaked `CreateRoom` token can create a room for one minute and nothing else; a leaked `GetParticipant` token acts + on one room for one minute. ### Negative Consequences @@ -60,5 +69,6 @@ owner's decision first. ## Links +* Refined by [ADR-0832](0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md) * Refines [ADR-0829](0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md) * [ADR-0079](0079-cap-client-triggered-outbound-proxying.md) diff --git a/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md b/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md new file mode 100644 index 000000000..389cb8cf3 --- /dev/null +++ b/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md @@ -0,0 +1,125 @@ +# A delegated delayed leave is restarted while LiveKit shows the participant, and sent once it does not + +* Status: accepted +* Date: 2026-11-17 + +Technical Story: MatrixRTC slice 4. The owner chose to implement MSC4195's optional delegated delayed leave. + +## Context and Problem Statement + +A MatrixRTC client schedules a delayed `m.rtc.member` leave (MSC4140, ADR-0823) and restarts it while it is in the +call, so its membership ends if it vanishes. MSC4195 lets the client hand that work to its homeserver: +`POST /_matrix/client/v1/rtc/livekit/delegate_delayed_leave` with `{url, room_id, slot_id, member_id, delay_id}`. The +server then restarts the event while the LiveKit participant is connected and sends it once the participant has +disconnected. The client, believing the server has the event, stops restarting it and uses a long delay (Element Call +uses one hour). + +What the server does with a delegation decides whether a user's call membership is ended at the right time. Two +failures matter: ending a membership while the user is still in the call, and keeping one alive after they have left. + +## Decision Drivers + +* A delegation acts only on a delayed event the delegating user owns, in the room they named, while they are joined. +* No input the server cannot verify ends or prolongs a membership by itself. +* When the server cannot tell, the event falls back to its own timer, which is where the client left it. +* A restart of this server does not drop delegations, so a connected participant is not ended an hour later. + +## Decision Outcome + +### The request + +`POST /_matrix/client/v1/rtc/livekit/delegate_delayed_leave` and the unstable +`/_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave`, with an access token and the account +gate. In order: + +1. The built-in token service off: 404 `M_UNRECOGNIZED`. +2. A body that is not the five strings, within the get_token bounds (`delay_id` at most 64 bytes): 400. +3. `url` not `server.rtc.livekit.url` byte for byte: 400 `M_INVALID_PARAM` (MSC4195 MUST). +4. The caller's current membership not `join`: 403 `M_FORBIDDEN`, as get_token answers. +5. The delayed event not the caller's, not in `room_id`, or not scheduled: 400 `M_INVALID_PARAM`, one answer for all + three (MSC4195 MUST), so a delay ID of another user's is not confirmed. +6. Its delay under 5 minutes: 400 `M_INVALID_PARAM` (MSC4195 MAY). A shorter delay would need a restart more often than + LiveKit is polled. +7. The user holding 20 delegations already, none of them for this key: 429 `M_LIMIT_EXCEEDED`, nothing evicted. + +Then the delegation is stored, replacing any of the same (user, room, slot, member) and any of the same delay ID +(MSC4195 MUST: one per key), and the answer is `{}`. The route is limited per user (30 a minute). + +### Stored, so a restart keeps it + +Delegations are rows of `livekit_delegations` (migration 004): the delay ID, user, room, slot, member and creation time. +Nothing else about a delegation needs to survive a restart: after one, every delegation is checked again from the +start. + +### LiveKit decides, by polling + +A job in the main process, `livekit-delegations`, checks each delegation about every 30 seconds with LiveKit's +`GetParticipant` for the delegation's room name and identity (MSC4195 names, ADR-0829), at most 16 calls a run, with +`runtime.mutex` released for the calls (ADR-0830). Under the lock, before any call, a delegation is dropped (its row +deleted, the event left as it is) when: + +* its delayed event is no longer scheduled (sent, cancelled or failed); +* the user is no longer joined to the room; +* the token service is no longer configured. + +After a call: + +* **Connected** (an answer for the participant in a state other than `DISCONNECTED`): recorded. If less than half the + delay remains, the event is restarted through `manage_delayed_event`. +* **Gone** (Twirp `not_found`, or the participant `DISCONNECTED`): if the participant was seen connected, or the + delegation is more than 2 minutes old, the event is sent through `manage_delayed_event` and the delegation dropped. + A delegation younger than that is left to wait, for a client still connecting. +* **Unknown** (LiveKit unreachable, a timeout, any other answer): nothing changes. + +The event is restarted only on a "connected" answer to the call just made, never on one remembered from an earlier +run. When LiveKit cannot be asked, the restarts stop and the event is sent by its own timer: a lost LiveKit ends +memberships late, never early. + +Both actions go through `manage_delayed_event`, as the user's own `restart` and `send` would, so a send is authorised +against the room when it happens (ADR-0825) and an account refusal applies. + +### Webhooks only prompt a check + +LiveKit's `participant_joined`, `participant_left` and `participant_connection_aborted` webhooks (ADR-0833) mark the +matching delegation to be checked at the next run and wake the job. A webhook never restarts or sends an event itself, +so a webhook that is replayed, reordered or lost changes when a check happens, never its outcome. + +### Positive Consequences + +* A participant who drops off the SFU leaves the call within about 30 seconds, or at once when the webhook arrives, + instead of after the client's delay. +* A delegation that can no longer be acted on safely falls back to the behaviour the client chose. + +### Negative Consequences + +* While the server is down, or LiveKit cannot be asked, a vanished participant stays listed until the event's own delay + runs out (an hour for Element Call). +* One `GetParticipant` call per delegation every 30 seconds. +* Delegation works only for this server's SFU, as MSC4195 says. + +## Pros and Cons of the Options + +### Act on the webhook alone + +* Good, because it is immediate and makes no calls. +* Bad, because LiveKit's webhooks are delivered at most a few times with no guarantee; a lost `participant_left` keeps a + membership alive for as long as the server goes on restarting it. + +### Keep delegations in memory only + +* Good, because it needs no migration. +* Bad, because after a restart nothing restarts the delegated events, and every participant still connected is ended + when the client's hour runs out. + +### Send the leave whenever LiveKit cannot be asked + +* Good, because a vanished participant never lingers. +* Bad, because a LiveKit outage or a slow answer would end every call membership on the server. + +## Links + +* Refines [ADR-0829](0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md) +* [ADR-0825](0825-a-due-delayed-event-is-sent-by-one-job-through-the-ordinary-send-path-never-early-and-at-least-once.md) +* [ADR-0823](0823-delayed-events-are-served-on-the-stable-unstable-and-query-parameter-forms-that-released-clients-send.md) +* [ADR-0830](0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md) +* [ADR-0833](0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md) diff --git a/docs/adr/0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md b/docs/adr/0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md new file mode 100644 index 000000000..bc9ae05b7 --- /dev/null +++ b/docs/adr/0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md @@ -0,0 +1,94 @@ +# The LiveKit webhook is served on the client listener and trusted only to prompt a check + +* Status: accepted +* Date: 2026-11-17 + +Technical Story: MatrixRTC slice 4, the delegated delayed leave (ADR-0832). + +## Context and Problem Statement + +LiveKit tells a configured URL about participants joining and leaving by webhook. MSC4195 recommends combining +webhooks with polling for a delegated leave, since webhooks have no delivery guarantee. A webhook is an unauthenticated +HTTP request as far as Matrix is concerned: anyone who can reach the URL can send one. What it may change, and how it +proves it came from the operator's LiveKit, has to be decided. + +LiveKit signs each webhook: the `Authorization` header holds an HS256 JWT signed with the API secret, whose `iss` is the +API key, valid for 5 minutes, and whose `sha256` claim is the standard base64 of the SHA-256 of the body. The body is a +`WebhookEvent` in protobuf JSON: `event`, `room.name`, `participant.identity`, `id` and `createdAt` (seconds). + +## Decision Drivers + +* No state changes on a webhook alone (ADR-0832). +* The check is the one LiveKit's own SDKs make, with nothing weaker. +* A webhook that is replayed, stale or not for a delegation this server recorded does nothing. +* A flood of webhooks, forged or real, costs little. + +## Decision Outcome + +### Where + +`POST /_merovingian/livekit/webhook`, a fixed path on the client listener(s). The operator points LiveKit's +`webhook.urls` at it. The client listener is chosen because the operator's LiveKit already reaches this server's +client API, and the federation listener is for other servers. With the built-in token service off the path is +404 `M_UNRECOGNIZED`, as any unknown route. + +### Authentication + +In order, each failure answering 401 `M_UNAUTHORIZED` with one text and logging `livekit.webhook.refused` with the +reason: + +1. The body is at most 64 KiB (413 above that, before anything is read). +2. `Authorization` is present: a JWT, with or without a `Bearer ` prefix, at most 4096 bytes. +3. The JWT verifies with `crypto::verify_hs256_token` under the API secret, read from its file for this request into a + `core::SecretBuffer`. The header's `alg` is never read (ADR-0828). +4. `iss` equals `server.rtc.livekit.api_key`. +5. `nbf` is not after now plus 60 seconds and `exp` is after now minus 60 seconds: the token is current, with a + minute's allowance for clock difference. +6. `sha256` equals the base64 of the body's SHA-256, compared in constant time, so the body is the one LiveKit signed. + +### What an authenticated event may do + +* Only `participant_joined`, `participant_left` and `participant_connection_aborted` are read. Others are answered + 200 and ignored, so LiveKit does not retry them. +* `createdAt` within 5 minutes of now, and an `id` (at most 128 bytes) not among the last 1024 seen, else ignored. A + replay within the token's own 5 minutes is caught by the `id`; one after is caught by the token's `exp`. +* The event must name, by `room.name` and `participant.identity`, a delegation this server recorded, created no later + than `createdAt`, else ignored. Nothing in the body is used otherwise: no Matrix ID is derived from it. +* A match marks that delegation to be checked at the next run of `livekit-delegations` and wakes the job. That is all. + +Every authenticated event is answered 200 `{}`. + +### Bounds + +* The path has the client rate limiter's default per-address limit (600 a minute) and no tighter one: LiveKit sends + every room and track event of every call from one address, and a webhook refused for its rate only loses a prompt, + since the job's own checks decide. +* A request costs a secret read, an HMAC and a SHA-256, under `runtime.mutex` only for the delegation lookup. + +### Positive Consequences + +* Forged, replayed or stale webhooks change nothing, and real ones only bring a check forward. + +### Negative Consequences + +* LiveKit must be able to reach the client listener's address. +* A webhook signed with the secret but for an event LiveKit never sent (someone holding the secret) can still only + prompt a check. + +## Pros and Cons of the Options + +### Serve the webhook on a listener of its own + +* Good, because it could be bound to loopback only. +* Bad, because it is a new listener for one route, with its own TLS and configuration, and the signature already + restricts who can use the route. + +### Act on `participant_left` at once + +* Good, because the leave is sent sooner by up to one polling interval. +* Bad, because a forged-but-signed or reordered webhook would end a membership that LiveKit still shows connected. + +## Links + +* Refines [ADR-0832](0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md) +* [ADR-0828](0828-livekit-tokens-are-signed-and-verified-only-through-typed-hs256-functions-in-the-crypto-boundary.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 50884d947..a045c32a5 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -710,3 +710,5 @@ * [0829 - The built-in LiveKit token service issues tokens only to users this server finds joined](0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md) * [0830 - Every call to LiveKit goes to the configured address with a token of its own](0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md) * [0831 - A federated LiveKit token request is judged by main and answered subscribe-only](0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md) +* [0832 - A delegated delayed leave is restarted while LiveKit shows the participant, and sent once it does not](0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md) +* [0833 - The LiveKit webhook is served on the client listener and trusted only to prompt a check](0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md) diff --git a/docs/architecture.md b/docs/architecture.md index 7bb20b73b..48e108ce9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -594,6 +594,11 @@ it answers with the published room directory, which any server may request, and listing reads appservice registration files the worker does not load (ADR-0296, ADR-0461), not because its database role is denied the data. +The federation LiveKit token route (`rtc/livekit/get_token`, MSC4195) is bound the same way, as +`WorkerRelayKind::livekit_token` with a permit over the request body (ADR-0831). Main judges it: the origin main +verified must be the user's server, and the user must be joined by main's own state. The worker never reads the LiveKit +configuration or the API secret, and signs nothing. + ### IPC reader/dispatch split `ipc::IpcChannel` runs two threads per channel end. The reader thread only routes frames: a `reply_to` frame wakes its pending `send_request` waiter, and request frames are queued for the dispatch thread, which invokes the registered request handler one frame at a time in arrival order. The reader must never run handler code: a handler that blocks on a lock held by a thread that is itself waiting inside `send_request` on the same channel would otherwise wedge frame routing until the `send_request` timeout. That exact cycle previously occurred on every relayed PDU: the worker's relay thread held the worker `runtime.mutex` across its `pdu_ingest` round trip to main, main's `pdu_ingest` handler sent a `room_sync` notification (whose handler needs that same worker mutex) immediately before the `pdu_ingest` response, and the worker's reader thread blocked on the notification before it could route the response — a 60-second stall per PDU that remote origins turned into retry-with-backoff drip feed. The mirror case existed on main: a client-server handler holding main's `runtime.mutex` across a proxied outbound call (e.g. remote `/keys/query`) starved main's reader from routing the worker's `outbound_http_response` whenever a `pdu_ingest` arrived first and blocked inline on the same mutex. For the same reason, the worker handles `room_sync` on `local_pool` rather than on the dispatch thread: `reload_room` needs `runtime.mutex`, and blocking the dispatch thread on it would delay every later queued request frame. On the main side, `WorkerPool` runs every worker-to-main request handler (`pdu_ingest`, `membership_ingest`, `edu_ingest`, `invite_ingest`, query-provider relays) on a dedicated handler pool sized from `federation.worker.relay_threads`; the per-channel IPC dispatch thread only classifies the frame and enqueues the work. This means a slow `pdu_ingest` — which reserves a sync-surface ID, acquires its room stripe, reserves its stream ordering once the event is ready to store (pending until applied, so no sync position passes it, ADR-0247), prepares the update, releases the global runtime lock for the backend commit, and re-acquires it only to apply the result and update membership — no longer serializes all later request frames on that channel behind it, eliminating the single-dispatch-thread throughput bottleneck that made high-rate inbound federation back up and drip-feed. `WorkerPool::stop()` drains `handler_pool_` before stopping the supervisors so no handler thread races the closing channel. Because the handler pool can still be running a `pdu_ingest` when `WorkerSupervisor` needs to stop or restart, the supervisor takes ownership of the `IpcChannel` under `channel_mu_` and releases the lock before calling `IpcChannel::stop()`; otherwise `stop()`'s join of the dispatch thread would deadlock against the same handler calling back into `channel_snapshot()` via `notify_room_changed()`. `WorkerSupervisor::stop()` also bounds its final `waitpid` with `WNOHANG` and escalates through `SIGTERM` to `SIGKILL`, so a TSan-slow or stuck worker child cannot block process shutdown or test teardown. @@ -642,6 +647,7 @@ Implemented endpoints are grouped below. Matrix v1.19 behaviour is described in - **Admin**: `GET /admin/safety/reports`, quarantine/release/remove media - **Push notifications**: `GET /pushers`, `POST /pushers/set`, the Push Rules API (`GET`/`PUT`/`DELETE /pushrules/...`; a user's rules are their `m.push_rules` account data applied over the server defaults by `push::UserPushRules`, ADR-0204), `GET /notifications`. Unread counts are decided by the same rules (`homeserver::PushRuleUnreadClassifier`, ADR-0205), and a failed notification is retried with backoff by the `push-retry` job thread from a bounded in-memory queue (`push::PushRetryQueue`, ADR-0206). Gateway delivery is gated on `server.push.enabled` (default `false`); when enabled, `RoomService.cpp`'s `send_event()` evaluates each local joined recipient's push rules and dispatches Push Gateway API notifications asynchronously — see "Fire-and-forget background work" above and `push` in the module diagram. `GET /notifications` history recording (`database::store_notification`, a synchronous local write, not gateway I/O) happens in that same rule-evaluation step regardless of `push.enabled` or whether the recipient has a pusher — a user with push turned off still needs to see their notifications. Kind `"email"` pushers have their own switch, `server.email.smtp_url` (ADR-0219, ADR-0220): the same step notes a notification in `push::EmailDigestQueue` (no network), and the `email-push` job thread (`homeserver/EmailPush.cpp`) sends each due digest, re-reading the pusher, the account's email 3PID and the badge count under `runtime.mutex` and sending through `email::send_smtp_message` with the mutex released. Only the main process sends email; the federation worker clears `server.email` in its config copy. - **Search**: `POST /search` — in-memory full-text search (`content.body`/`content.name`/`content.topic`) over `PersistentStore::events`, scoped to the caller's currently-joined, unencrypted rooms; bounded by `ClientApiLimits::max_search_events_scanned` rather than a SQL full-text index (SQLite FTS5/PostgreSQL `tsvector`), to avoid a second, divergent search backend in an architecture that does not otherwise read events from SQL at request time. See `docs/todos/capability-gaps.md` for the deliberately-left-out spec corners. +- **Calls (MatrixRTC)**: `GET /rtc/transports`; with the built-in LiveKit token service, `POST /rtc/livekit/get_token` and `POST /rtc/livekit/delegate_delayed_leave` (MSC4195), and LiveKit's signed webhook at `POST /_merovingian/livekit/webhook`, answered before the access-token gate (`homeserver/LiveKitTokenService.cpp`, `homeserver/LiveKitDelegations.cpp`). A token goes only to a user main finds joined; a request for another server's SFU is relayed to that server over signed federation; each call to LiveKit (`CreateRoom` on a token request, `GetParticipant` from the `livekit-delegations` job) goes only to `server.rtc.livekit.api_url` with a token of its own signed in `crypto/LiveKitToken.cpp`, with `runtime.mutex` released (ADR-0828 to ADR-0833). The job restarts a delegated delayed leave while LiveKit shows the participant and sends it once LiveKit does not, through `manage_delayed_event`; a webhook only brings a check forward. Delegations are kept in the `livekit_delegations` table (migration 004). - **Other**: `GET /capabilities`, `GET /voip/turnServer`, OAuth 2.0 server metadata (`auth_metadata`, ADR-0773) ## Sync subsystem diff --git a/docs/http-transport.md b/docs/http-transport.md index 9c4e3f238..73ad60977 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -823,7 +823,10 @@ Built-in per-endpoint refinements inside a tier: device and key APIs at 120/60s, search at 20/60s, thumbnails at 240/60s, and the delayed-event management and lookup paths (both prefixes, ADR-0826) at 3000/60s. Search requests do real work (a bounded in-memory scan, see `ClientApiLimits::max_search_events_scanned`) rather than a cheap -lookup. The built-in per-user caps are 5/60s on `/login`, 4/60s on `/login/get_token` (ADR-0548), 30/60s on the two `preview_url` routes (ADR-0213) and 30/60s on `/_matrix/media/v1/create` (ADR-0212). The delayed-event management and lookup paths (`/_matrix/client/v1/delayed_events/` and `/_matrix/client/unstable/org.matrix.msc4140/delayed_events/`) are 120/60s per user, and the dedicated scheduling paths (`.../rooms/{roomId}/delayed_event/...`, both prefixes) 60/60s per user (ADR-0826); each path template is its own bucket. +lookup. The built-in per-user caps are 5/60s on `/login`, 4/60s on `/login/get_token` (ADR-0548), 30/60s on the two `preview_url` routes (ADR-0213) and 30/60s on `/_matrix/media/v1/create` (ADR-0212). The delayed-event management and lookup paths (`/_matrix/client/v1/delayed_events/` and `/_matrix/client/unstable/org.matrix.msc4140/delayed_events/`) are 120/60s per user, and the dedicated scheduling paths (`.../rooms/{roomId}/delayed_event/...`, both prefixes) 60/60s per user (ADR-0826). The two LiveKit `get_token` paths are 60/60s per user (ADR-0829) and the two +`delegate_delayed_leave` paths 30/60s per user (ADR-0832); LiveKit's webhook, `/_merovingian/livekit/webhook`, has only +the default per-IP limit, because LiveKit sends every event from one address (ADR-0833). Each path template is its own +bucket. The per-user tier keys on the *authenticated* user, which before a login succeeds is nobody — so a `/login` guessing spree against one account spread @@ -849,7 +852,8 @@ Per-IP policy resolution is most-specific-first: `client_rate_limits.default_per_ip`. Per-user resolution: `client_rate_limits.per_user.` first, then -the built-in per-user caps (`/login`, `/login/get_token`, `preview_url`, media `create`, the delayed-event paths); routes with neither have no per-user cap (the +the built-in per-user caps (`/login`, `/login/get_token`, `preview_url`, media `create`, the delayed-event paths, the +LiveKit `get_token` and `delegate_delayed_leave` paths); routes with neither have no per-user cap (the per-IP cap still applies). Tier names are `auth_sensitive`, `media`, `sync`, `federation`, `admin`, `generic`; an unknown name is a parse-time finding, not a silently ignored key. All `client_rate_limits.*` changes require a server diff --git a/docs/log-filtering.md b/docs/log-filtering.md index bc58ce9d9..9249a455a 100644 --- a/docs/log-filtering.md +++ b/docs/log-filtering.md @@ -134,7 +134,7 @@ used as the first argument to `observability::log_diagnostic` and `log_diagnosti | `tls` | TLS context set-up and handshake accept or reject | | `oauth` | OAuth 2.0 client registration, eviction at the cap, and stored metadata that no longer validates | | `delayed_events` | Delayed events: scheduled, restarted, cancelled, sent, failed, a failed outcome write and a failed prune; never event content or a state key. The count of rows skipped at load is a start-up warning from the process entry point, not this module | -| `livekit` | The built-in LiveKit token service: a token issued or refused, to a local user, to another server's user, or relayed from another server; a failed `CreateRoom` call and an unreadable API secret. Each names the user and room (and the server, for federation); never the token, the API secret, the device or member ID, or the slot | +| `livekit` | The built-in LiveKit token service: a token issued or refused, to a local user, to another server's user, or relayed from another server; a failed `CreateRoom` call and an unreadable API secret; a delegated delayed leave stored, refused, dropped, sent or failing to restart or send (`livekit.delegation.*`); a refused webhook (`livekit.webhook.refused`, warning, with the reason only) and one that prompted a check (`livekit.webhook.prompted`). Each names the user and room (and the server, for federation); never the token, the API secret, the device or member ID, the slot or the delay ID | Unrecognised module names are accepted and the level is recorded — there is no error. Restart the server to apply. diff --git a/docs/matrix-v1.19-client-server-api.md b/docs/matrix-v1.19-client-server-api.md index 15ef16d7f..0b1a83c86 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -541,6 +541,7 @@ In each case below the spec leaves the choice to the server; the owner decided t - **Password reset by email (ADR-0481).** `POST /account/password/email/requestToken` (no token) answers `200` with `sid` and `submit_url` for every well-formed request, whether or not an account holds the address, and emails an 8-character code only to an active account's address; it never answers `M_THREEPID_NOT_FOUND` or `M_THREEPID_IN_USE`. A repeat with the same or a lower `send_attempt` returns the same `sid` and sends nothing. With no relay (`server.email.smtp_url`) it is `400 M_THREEPID_MEDIUM_NOT_SUPPORTED`. The client posts `{sid, client_secret, token}` to `submit_url` (`/_matrix/client/unstable/org.merovingian/account/password/email/submitToken`, this server's own path, the Identity Service `submitToken` shape): `{"success":true}`, or `400 M_TOKEN_INCORRECT`, `M_INVALID_PARAM` or `M_SESSION_EXPIRED` (five wrong codes end the session; sessions last 15 minutes). `POST /account/password` with no access token and `auth: {type: "m.login.email.identity", threepid_creds: {sid, client_secret}}` then sets the password of the account that holds the address (`401` with the flows for a missing or unvalidated stage, `400 M_WEAK_PASSWORD` for a weak password and the session is kept for a retry) and, with `logout_devices` (the default), revokes every token of the account. `POST /account/password/msisdn/requestToken` is `400 M_THREEPID_MEDIUM_NOT_SUPPORTED` (no SMS). - **MatrixRTC transport discovery (MSC4143, not in v1.19; ADR-0822).** `GET /_matrix/client/v1/rtc/transports` answers `{"transports":[{"type":"livekit","livekit_service_url":""}]}` and `GET /_matrix/client/unstable/org.matrix.msc4143/rtc/transports` answers `{"rtc_transports":[...]}`, both needing an access token; with `server.rtc.livekit.service_url` empty they answer `{"transports":[]}` and `{}`. `/versions` always lists `org.matrix.msc4143` and `org.matrix.msc4143.stable`, and the well-known document gains `org.matrix.msc4143.rtc_foci` when a URL is set. With the built-in token service on (`server.rtc.livekit.url`, ADR-0829) the transports are instead `livekit` with `url`, and, on the stable route only, `m.livekit` with the same `url`; the well-known document gains no member for it. - **LiveKit token service (MSC4195, not in v1.19; ADR-0829 to ADR-0831).** `POST /_matrix/client/v1/rtc/livekit/get_token` and `POST /_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token`, access token and the standard account gate, body `{room_id, slot_id, member_id, url, server_name?}` (every member a string; `room_id`, `slot_id`, `member_id` at most 255 bytes, `url` at most 2048; anything else `400 M_BAD_JSON` or `M_INVALID_PARAM`). Answers `{"jwt":...}`. A caller whose current membership is not `join` gets `403 M_FORBIDDEN`, alike for a room that does not exist. For this server (`server_name` absent or this server's name), a `url` that is not `server.rtc.livekit.url` byte for byte is `400 M_INVALID_PARAM`, and the LiveKit room is created before answering: an unreachable or failing LiveKit is `502 M_UNKNOWN`. For another server named in `server_name`, the request is relayed over federation only when that server has a member joined (`403 M_FORBIDDEN` otherwise); its `403 M_FORBIDDEN` and `400 M_INVALID_PARAM` are passed on in this server's words and anything else is `502 M_UNKNOWN`. Without an outbound slot the answer is `429 M_LIMIT_EXCEEDED`; per-user limit 60/60s. With the service off both routes are `404 M_UNRECOGNIZED`. `/versions` lists `org.matrix.msc4195` and `org.matrix.msc4195.stable`, true when the service is on. The federation route `POST /_matrix/federation/v1/rtc/livekit/get_token` (and its `io.element.msc4195` unstable form) issues a subscribe-only token for a joined user of the requesting server. +- **Delegated delayed leave (MSC4195, not in v1.19; ADR-0832, ADR-0833).** `POST /_matrix/client/v1/rtc/livekit/delegate_delayed_leave` and `POST /_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave`, access token and the account gate, body `{url, room_id, slot_id, member_id, delay_id}` (strings; `delay_id` at most 64 bytes). In order: `404 M_UNRECOGNIZED` with the built-in service off; `400 M_BAD_JSON`, `M_MISSING_PARAM` or `M_INVALID_PARAM` for the body; `400 M_INVALID_PARAM` for a `url` that is not `server.rtc.livekit.url`; `403 M_FORBIDDEN` when the caller is not joined; one `400 M_INVALID_PARAM` for a delayed event that is unknown, another user's, in another room or no longer scheduled, and one for a delay under 5 minutes; `429 M_LIMIT_EXCEEDED` at 20 delegations per user. Answers `200 {}`; a new `delay_id` for the same room, slot and member replaces the old delegation. Without an access token the answer is `401`, never `404`, so Element Call's empty probe finds the route. Per-user limit 30/60s. `POST /_merovingian/livekit/webhook` (not a Matrix route) takes LiveKit's signed webhooks on the client listener, without an access token: `404 M_UNRECOGNIZED` with the service off, `413` over 64 KiB, `401 M_UNAUTHORIZED` unless signed by the configured LiveKit key for that body, else `200 {}`. - **Delayed events (MSC4140; in the v1.20 spec text, not in v1.19; ADR-0823 to ADR-0826).** All nine routes need an access token and the standard account gate; `?user_id=` masquerade works as on other routes. Schedule: `PUT /v3/rooms/{roomId}/delayed_event/{eventType}/{txnId}` and `PUT /unstable/org.matrix.msc4140/rooms/{roomId}/delayed_event/{eventType}/{txnId}`; a request to `PUT /v3/rooms/{roomId}/send/{eventType}/{txnId}` or `PUT /v3/rooms/{roomId}/state/{eventType}/{stateKey}` (also the no-state-key and empty-state-key forms) that carries `?org.matrix.msc4140.delay=` is always scheduled, never sent at once, and answers `403 M_FORBIDDEN` when the feature is disabled (the other body-sending routes, `POST .../send` and `PUT .../redact/...`, answer `400 M_INVALID_PARAM` when the parameter is present, and the application-service `?ts=` is ignored on a delayed request); a delay that is not a decimal integer of at least 1, or is repeated, is `400 M_INVALID_PARAM`, and one over `server.delayed_events.max_delay_ms` is `400` (`M_DELAY_TOO_LARGE` on the v3 dedicated path, `ORG.MATRIX.MSC4140_DELAY_TOO_LARGE` on the others); a user at `max_scheduled_per_user` gets `429 M_LIMIT_EXCEEDED`; content over 65,536 bytes is `413 M_TOO_LARGE`. Manage: `POST /v1/delayed_events/{delayId}/{send|cancel|restart}` and `POST /unstable/org.matrix.msc4140/delayed_events/{delayId}/{send|cancel|restart}`, and, under the unstable prefix only, `POST /unstable/org.matrix.msc4140/delayed_events/{delayId}` with `{"action":"send"|"cancel"|"restart"}` (there is no `POST /v1/delayed_events/{delayId}`; any other last segment is `404 M_UNRECOGNIZED`). Look up: `GET /v1/delayed_events/{delayId}` and `GET /unstable/org.matrix.msc4140/delayed_events/{delayId}`. A delay ID that is unknown and one that belongs to another user both answer `404 M_NOT_FOUND` with `Delayed event not found.`; a repeated action on a finalised event answers `200` or `409 M_UNKNOWN`, and one on an event being sent answers `409`. `/versions` lists `org.matrix.msc4140` and `org.matrix.msc4140.stable` (each true when the feature is enabled), and `/capabilities` lists `m.delayed_events` and `org.matrix.msc4140.delayed_events` (`max_delay_ms`, `max_scheduled`; zeros when disabled). The event a delayed event became carries `unsigned.delay_id` for the user who scheduled it. The listing endpoint (MSC4486) is not routed (`404 M_UNRECOGNIZED`); sticky events (MSC4354) are not supported. - **`GET /voip/turnServer` with `server.turn.uris` (ADR-0821)** answers one `uris` entry per configured URI, in the configured order; `server.turn.server` still gives one. - **`GET /voip/turnServer` with `server.turn.shared_secret_file` (ADR-0480)** answers per-user credentials in the coturn REST API format: `username` `:`, `password` the base64 HMAC-SHA1 of it under the secret, `ttl` `server.turn.ttl_seconds`. diff --git a/docs/threat-model.md b/docs/threat-model.md index 1210b7794..12a0da372 100644 --- a/docs/threat-model.md +++ b/docs/threat-model.md @@ -36,8 +36,9 @@ SSRF-filtered; namespace matching; masquerading) - Identity Service client (outbound `store-invite`/`bind`/`unbind`/`requestToken`) - Push gateway delivery (outbound, client-supplied URL, no operator allowlist) -- The built-in LiveKit token service (1.1.3): the LiveKit API secret, tokens handed to clients, the `CreateRoom` call to - the operator's LiveKit, and the federation `rtc/livekit/get_token` route in both directions (see below) +- The built-in LiveKit token service (1.1.3): the LiveKit API secret, tokens handed to clients, the `CreateRoom` and + `GetParticipant` calls to the operator's LiveKit, the federation `rtc/livekit/get_token` route in both directions, the + delegated delayed leave and the LiveKit webhook (see below) - Email pushers (outbound SMTP to an operator-configured relay; a client-supplied recipient address) - Federation worker IPC channel (local process boundary) - MSC4186 sliding-sync connection state (client-chosen `conn_id`) @@ -3366,17 +3367,19 @@ after a crash in the window between the send and its record, or when a `send` re the step; a suspended account's delayed events fail rather than send, so the server does not end a suspended participant's call membership; the feature is on by default. -### The built-in LiveKit token service (1.1.3, ADR-0828 to ADR-0831) +### The built-in LiveKit token service (1.1.3, ADR-0828 to ADR-0833) New surface: a long-lived secret, `server.rtc.livekit.api_secret_file`, whose holder can mint any token for the operator's LiveKit, including administrative ones; two client routes that hand out tokens; an outbound call to -LiveKit's room service; and a federation route, served for other servers and called on other servers. Threats and -mitigations: +LiveKit's room service; a federation route, served for other servers and called on other servers; a client route that +hands this server a user's delayed leave and a job that restarts or sends it on what LiveKit says; and an +unauthenticated webhook route for LiveKit. Threats and mitigations: (a) The secret leaking. It is a path to an owner-only (`0400`) file, checked at start-up, read into a `core::SecretBuffer` for each signature and wiped after, never held for the life of the process, never logged and never in a response. Signing is in `src/crypto/` through typed functions only (ADR-0828): the participant grant cannot -express `roomCreate`, `roomAdmin` or `hidden`, and the one other signer grants `roomCreate` alone. The federation +express `roomCreate`, `roomAdmin` or `hidden`; one other signer grants `roomCreate` alone, and the last `roomAdmin` over +one named room alone, for `GetParticipant`. The federation worker never reads the configuration or the secret. (b) A token for someone who should not have one. A token goes only to a caller this server authenticated (access token, @@ -3403,7 +3406,35 @@ a signature, with no network call: a request from another server never makes thi (f) The worker forging a request. The inbound route reaches main only through the ADR-0595 relay: a permit over the body, bound to the request main authenticated, used once, with the origin checked against the pending request's. +(g) A delegation acting on someone else's event. The delayed event must be the caller's own (looked up by owner, so +another user's ID is the same 400 as an unknown one), scheduled, in the named room, and the caller joined to it by this +server's state; it is bound to that delay ID, room, slot and member and is dropped when the event stops being +scheduled, the user leaves or the service is turned off. The job acts only through `manage_delayed_event`, so a send is +authorised against the room when it happens, as the user's own send would be. At most 20 per user, 30 requests a +minute, and a delay of at least 5 minutes (ADR-0832). + +(h) LiveKit's answers ending a membership early. Only a `not_found` or `DISCONNECTED` answer for a participant seen +connected, or never seen after 2 minutes, sends the leave; anything else (no answer, a timeout, another error) changes +nothing and leaves the event to its own timer, and a restart needs a "connected" answer to the call just made. A +LiveKit that is down or lies about a participant being present can only delay a leave by as long as it keeps saying so +(the client's own leave and the user's own actions still work); one that lies about a participant being gone ends +that membership early, which the operator's own SFU could do anyway. `GetParticipant` goes only to `api_url`, from +the job's thread, at most 16 per run, 10 seconds each, with the runtime lock released, and its token can act on one +room for one minute: LiveKit has no narrower grant for it (ADR-0830). + +(i) A forged or replayed webhook. `POST /_merovingian/livekit/webhook` takes no access token, so it is authenticated as +LiveKit authenticates it: one `Authorization` header, an HS256 JWT checked in constant time under the API secret with +the issuer equal to the API key (constant time), `nbf` and `exp` current within 60 seconds, and a `sha256` claim equal +to the body's hash, so the body is the one LiveKit signed; the body is at most 64 KiB, and the route is 404 with the +service off (ADR-0833). Even an authentic webhook is only a prompt: it is read only for a recorded delegation created +before the event, only if `createdAt` is within 5 minutes and its `id` is not one of the last 1024 seen, and then it +only brings that delegation's next check forward. It never sends or restarts an event, so a forged or replayed webhook +can at most cost one `GetParticipant` call. Each unauthenticated request costs a secret file read and an HMAC, limited +by the default per-address rate. + Residual risk: a token stays usable for its lifetime after the user leaves the room, and a participant already connected stays in the call until LiveKit removes them (this server does not call `RemoveParticipant`); anyone who can -read the secret file can mint any LiveKit token; the relay and the inbound route have been tested only against this -server, never another implementation or a real LiveKit. +read the secret file can mint any LiveKit token, and could forge webhooks (which only prompt checks); a delegated leave +depends on LiveKit's view of the call, so a LiveKit that keeps reporting a vanished participant keeps their membership +alive; the relay, the inbound route, the delegation job and the webhook have been tested only against this server and +a local stand-in for LiveKit, never another implementation or a real LiveKit. diff --git a/docs/todos/capability-gaps.md b/docs/todos/capability-gaps.md index 0334db18c..dc83f0730 100644 --- a/docs/todos/capability-gaps.md +++ b/docs/todos/capability-gaps.md @@ -50,6 +50,7 @@ When adding a capability, record what is *missing* as explicitly as what works. | `GET /_matrix/client/v1/auth_metadata` and the MSC2965 unstable path | `spec-covered` | The OAuth 2.0 server metadata, served while `server.oauth.enabled` is true (ADR-0773); `404 M_UNRECOGNIZED` while it is off. Registration, the authorisation pages, the token endpoint (code and refresh grants), revocation, the account pages at `/_merovingian/account` (all six account management actions), the `m.oauth` UIA stage, the `legacy_api_enabled=false` switch and the hand-off for OAuth 2.0 aware clients (`m.login.sso` with `oauth_aware_preferred`) are served (ADR-0779 to ADR-0802), and so is the device authorization grant with `server.oauth.device_grant_enabled=true` (ADR-0804 to ADR-0806). An OAuth session still cannot add an email address or mint a login token (no page; `403 M_FORBIDDEN`). Element X's QR-code login needs the MSC4108 rendezvous API, which is not in spec v1.19 and not part of 1.1.0 (owner decision), so it stays unavailable although the device authorization grant is served. Nothing here has yet been tried with Element X or in a real browser; see the open items in `docs/todos/oauth-2-0-api.md`. | | `GET /_matrix/client/v1/rtc/transports` and the MSC4143 unstable path | `runtime-wired` | MatrixRTC transport discovery (MSC4143, not in the v1.19 spec): advertises the operator's `lk-jwt-service` (`server.rtc.livekit.service_url`) as type `livekit` (ADR-0822). With the built-in token service on, advertises `livekit` and `m.livekit` with the SFU `url` instead (ADR-0829). | | `POST /_matrix/client/v1/rtc/livekit/get_token`, the `io.element.msc4195` path, and the federation `rtc/livekit/get_token` | `runtime-wired` | MSC4195, not in the v1.19 spec: the built-in LiveKit token service issues tokens to users this server finds joined, creates the LiveKit room first, relays a request for another server's SFU over federation and answers other servers' joined users with subscribe-only tokens (ADR-0829 to ADR-0831). Gap: no real client, LiveKit SFU or other homeserver has been run against it; the OpenID `/sfu/get` flow is not served. | +| `POST /_matrix/client/v1/rtc/livekit/delegate_delayed_leave`, the `io.element.msc4195` path, and `POST /_merovingian/livekit/webhook` | `runtime-wired` | MSC4195's delegated delayed leave: stored per user, room, slot and member (migration 004), checked every 30 s with LiveKit's `GetParticipant` by the `livekit-delegations` job, which restarts the event while the participant is in the call and sends it once LiveKit no longer shows them; LiveKit's signed webhooks bring a check forward (ADR-0832, ADR-0833). Gap: tested only against a local stand-in for LiveKit, never a real SFU or Element Call; a participant who vanishes is noticed within 30 s without webhooks. | | Delayed events: `PUT .../delayed_event/{eventType}/{txnId}`, `?org.matrix.msc4140.delay=` on `/send` and `/state`, `POST` and `GET .../delayed_events/{delayId}` (stable, `org.matrix.msc4140` and query forms) | `runtime-wired` | MSC4140, in the v1.20 spec text and not in v1.19: schedule, restart, cancel, send and look up a delayed event, kept in the `delayed_events` table (migration 003) and sent by the `delayed-events` job through the ordinary send path (ADR-0823 to ADR-0826). Not implemented: the listing endpoint (MSC4486, `404 M_UNRECOGNIZED`) and sticky events (MSC4354). No real client (Element X, Element Web, Element Call, lk-jwt-service) has been run against it yet. | | `GET /_matrix/client/v3/voip/turnServer` | `spec-covered` | Static TURN credentials from `server.turn.*` configuration, or per-user time-limited coturn shared-secret credentials when `server.turn.shared_secret_file` is set (`src/homeserver/TurnCredentials.cpp`, ADR-0480). `server.turn.uris` advertises several URIs (ADR-0821). | | Unrouted v1.19 operations | `not-started` | These answer `404 M_UNRECOGNIZED` (most are asserted as `(implementation gap)` scenarios in `tests/conformance/test_client_server_conformance.cpp`): legacy `GET /v3/events`, `GET /v3/events/{eventId}`, `GET /v3/initialSync`; `GET /.well-known/matrix/policy_server` and `GET /.well-known/matrix/support`. `POST /v1/login/get_token` (off unless `security.login_token.enabled`; UIA password every call; single-use in-memory tokens, ADR-0548) and `GET /v3/admin/whois/{userId}` (devices only: the server records no IP, user agent or last-seen time, so `connections` is always empty) are implemented (CS8). The two `/account/password/*/requestToken` routes are routed (email: ADR-0481; msisdn answers `400 M_THREEPID_MEDIUM_NOT_SUPPORTED`). User reporting, redaction, the appservice ping and the appservice network directory have their own rows. | diff --git a/docs/user-manual.md b/docs/user-manual.md index d7981e5dc..f671a47bb 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -872,6 +872,22 @@ What the service does: `security.federation.per_origin_request_rate`. - The `livekit` logger records each issued or refused token with the user and room, never the token, the secret or the device. +- A client may hand this server its call membership's delayed leave + (`POST /_matrix/client/v1/rtc/livekit/delegate_delayed_leave`, or the `io.element.msc4195` unstable path), so the + leave is sent when it drops out of the call even if it vanishes without a word (ADR-0832). The delayed event must be + the caller's own, scheduled, in a room the caller is joined to, with a delay of at least 5 minutes; a user holds at + most 20 delegations, and asking is limited to 30 a minute per user. The `livekit-delegations` job asks LiveKit about + each delegation every 30 seconds (`GetParticipant`, with a token of its own valid for that one room): while the + participant is in the call it restarts the event once less than half the delay is left, and once LiveKit no longer + shows the participant it sends the event at once. A participant never seen in the call is given 2 minutes to + connect. If LiveKit cannot be reached nothing is restarted, so the event is sent by its own timer: a lost LiveKit + ends memberships late, never early. Delegations survive a restart. +- To end memberships within seconds rather than within 30 seconds, point LiveKit's webhooks at this server: + `webhook.urls: ["https:///_merovingian/livekit/webhook"]` and `webhook.api_key: ` in + LiveKit's configuration (ADR-0833). The path is served on the client listener only while the built-in service is on. + A webhook is accepted only when signed by LiveKit with this API key and secret, for its exact body, and recent; it + then only makes the job check that participant at once. A webhook never sends or restarts an event by itself, so a + forged or replayed one can at most cause an early check. Without webhooks everything still works, 30 seconds slower. With the service on, `GET /_matrix/client/v1/rtc/transports` lists `{"type":"livekit","url":""}` and, on the stable path only, the same with type `m.livekit`. `/_matrix/client/versions` adds `org.matrix.msc4195` @@ -918,8 +934,10 @@ joins without a delayed leave. The endpoints are listed in The wire shapes were taken from the source of Element Web 1.12.35, Element X 26.11.0, Element Call 0.28.2 and `lk-jwt-service` 0.10.0 at those releases (ADR-0823). No real client has been run against this server yet. -`lk-jwt-service` 0.10.0 manages a delegated leave as an application service acting for the user, so an operator who -wants that registers it as an application service whose user namespace covers the local users; see the +With the built-in token service, a delegated leave is handled by this server itself (see +[the built-in token service](#the-built-in-token-service-serverrtclivekit) above). With an external `lk-jwt-service`, +0.10.0 manages a delegated leave as an application service acting for the user, so an operator who wants that +registers it as an application service whose user namespace covers the local users; see the [application service section](#application-service-api-appservice). What you will notice in operation (ADR-0824, ADR-0825): diff --git a/include/merovingian/homeserver/HomeserverRuntime.hpp b/include/merovingian/homeserver/HomeserverRuntime.hpp index 3c2159705..65a358db6 100644 --- a/include/merovingian/homeserver/HomeserverRuntime.hpp +++ b/include/merovingian/homeserver/HomeserverRuntime.hpp @@ -28,6 +28,7 @@ #include "merovingian/homeserver/CrossSigningResetApprovals.hpp" #include "merovingian/homeserver/DeviceAuthorisationStore.hpp" #include "merovingian/homeserver/InboundTypingUser.hpp" +#include "merovingian/homeserver/LiveKitDelegationProgress.hpp" #include "merovingian/homeserver/LocalDatabase.hpp" #include "merovingian/homeserver/LocalRoom.hpp" #include "merovingian/homeserver/MediaUploadNotifier.hpp" @@ -292,6 +293,17 @@ struct HomeserverRuntime final // runtime.mutex on another thread (PeriodicJob::wake does neither). Cleared under runtime.mutex at shutdown // before the thread is stopped. std::function delayed_events_wake{}; + // Wakes the "livekit-delegations" job (ADR-0832) when a delegation is stored or a webhook brings a check forward. + // Set by the process entry point once that thread exists; null in tests, which call run_livekit_delegations + // directly. Called with runtime.mutex held, so it must not block or wait for runtime.mutex on another thread + // (PeriodicJob::wake does neither). Cleared under runtime.mutex at shutdown before the thread is stopped. + std::function livekit_delegations_wake{}; + // What the "livekit-delegations" job knows of each stored delegation, by delay ID (ADR-0832). In memory only: after + // a restart each starts again as never seen and due now. Guarded by `mutex`. + std::map> livekit_delegation_progress{}; + // The `id`s of the last `livekit_webhook_seen_ids` authenticated LiveKit webhook events, oldest first, so a replay + // inside a token's lifetime prompts nothing (ADR-0833). In memory only. Guarded by `mutex`. + std::deque livekit_webhook_seen_ids{}; // Users whose profile change has rooms left to reach, with the index in database.rooms to // resume from (F-11, ADR-0353). No token and no event body: the job sends as the user and reads // the profile when it sends. In memory only: a restart leaves those rooms for the next profile diff --git a/include/merovingian/homeserver/LiveKitDelegationProgress.hpp b/include/merovingian/homeserver/LiveKitDelegationProgress.hpp new file mode 100644 index 000000000..8038d5d86 --- /dev/null +++ b/include/merovingian/homeserver/LiveKitDelegationProgress.hpp @@ -0,0 +1,26 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::homeserver +{ + +// What the "livekit-delegations" job knows of one stored delegation (ADR-0832), keyed by its delay ID in +// `HomeserverRuntime::livekit_delegation_progress`. In memory only: after a restart every delegation starts again as +// never seen and due for a check. Guarded by `runtime.mutex`. +struct LiveKitDelegationProgress final +{ + // The delegation's MSC4195 LiveKit room name and participant identity, derived once from the stored row, so a + // webhook is matched without hashing every delegation. + std::string room_name{}; + std::string identity{}; + // When LiveKit last answered that the participant is connected (wall-clock ms); 0 = never. + std::uint64_t last_seen_connected_ms{0U}; + // When the next GetParticipant check is due (wall-clock ms); 0 = at the next run. + std::uint64_t next_check_ms{0U}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/LiveKitDelegations.hpp b/include/merovingian/homeserver/LiveKitDelegations.hpp new file mode 100644 index 000000000..80a7c59f6 --- /dev/null +++ b/include/merovingian/homeserver/LiveKitDelegations.hpp @@ -0,0 +1,68 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/OperationResult.hpp" + +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +struct ClientServerRuntime; +struct LocalHttpRequest; +class StopFlag; + +// MSC4195's delegated delayed leave (ADR-0832) and the LiveKit webhook that prompts its checks (ADR-0833). + +// A delegated event's delay must be at least this long (MSC4195 lets a server refuse a short one): a restart is due +// when half the delay remains, and LiveKit is asked only every `livekit_delegation_check_interval`. +inline constexpr auto livekit_delegation_min_delay_ms = std::uint64_t{300'000U}; +// Delegations one user may hold. One more is refused (429), nothing is evicted. +inline constexpr auto livekit_delegations_per_user = std::size_t{20U}; +// How often each delegation is checked with GetParticipant, unless a webhook brings the check forward. +inline constexpr auto livekit_delegation_check_interval = std::chrono::milliseconds{30'000}; +// A delegation whose participant has never been seen is given this long to connect before a "gone" answer sends it. +inline constexpr auto livekit_delegation_connect_grace_ms = std::uint64_t{120'000U}; +// GetParticipant calls made by one run of the job, so one run's lock-free stretch stays bounded. +inline constexpr auto livekit_delegation_checks_per_run = std::size_t{16U}; +// The webhook body and the event `id` LiveKit sends, at most. +inline constexpr auto livekit_webhook_max_body_bytes = std::size_t{64U * 1024U}; +inline constexpr auto livekit_webhook_max_event_id_bytes = std::size_t{128U}; +// Webhook event IDs remembered, to ignore a replay inside the token's own lifetime. +inline constexpr auto livekit_webhook_seen_ids = std::size_t{1024U}; +// How far a webhook's `createdAt` may be from now, and the allowance on its token's `nbf` and `exp`. +inline constexpr auto livekit_webhook_max_age_seconds = std::int64_t{300}; +inline constexpr auto livekit_webhook_clock_leeway_seconds = std::int64_t{60}; +inline constexpr auto livekit_webhook_path = std::string_view{"/_merovingian/livekit/webhook"}; + +// POST .../rtc/livekit/delegate_delayed_leave for `user_id`, whose access token the caller checked. Caller holds +// `runtime.homeserver.mutex`. Answers per ADR-0832: 404 M_UNRECOGNIZED with the service off; 400 for a malformed body; +// 400 M_INVALID_PARAM for a `url` that is not the SFU; 403 M_FORBIDDEN when the user is not joined; 400 +// M_INVALID_PARAM, one answer, for a delayed event that is not the user's, not in the room or not scheduled, or whose +// delay is under `livekit_delegation_min_delay_ms`; 429 M_LIMIT_EXCEEDED at `livekit_delegations_per_user`; 500 when +// the row cannot be stored. On success stores the delegation (replacing any for the same user, room, slot and member, +// or the same delay ID), marks it for a check now, wakes the job, and answers 200 `{}`. Makes no network call. +[[nodiscard]] auto delegate_livekit_delayed_leave(ClientServerRuntime& runtime, std::string_view body, + std::string const& user_id) -> OperationResult; + +// The "livekit-delegations" job's body (main.cpp; tests call it directly with their own `now_ms`). Takes +// `runtime.homeserver.mutex` itself. Drops the delegations that can no longer be acted on, then checks at most +// `livekit_delegation_checks_per_run` due ones with GetParticipant with the lock released, then applies each answer +// under the lock through `manage_delayed_event`. Returns how long to wait before the next run: the time to the next +// due check, at most `livekit_delegation_check_interval`, at least 1 s; 1 s also when more checks are already due. +[[nodiscard]] auto run_livekit_delegations(ClientServerRuntime& runtime, std::uint64_t now_ms, StopFlag const& stop) + -> std::chrono::milliseconds; + +// POST /_merovingian/livekit/webhook (ADR-0833). Caller holds `runtime.homeserver.mutex` and has checked nothing: +// this is called before any access-token handling. 404 M_UNRECOGNIZED with the service off; 413 for a body over +// `livekit_webhook_max_body_bytes`; 401 M_UNAUTHORIZED for any authentication failure; otherwise 200 `{}`. At most +// marks one recorded delegation to be checked at the next run and wakes the job; never restarts or sends an event. +[[nodiscard]] auto receive_livekit_webhook(ClientServerRuntime& runtime, LocalHttpRequest const& request, + std::int64_t now_seconds) -> OperationResult; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/LiveKitRequestFields.hpp b/include/merovingian/homeserver/LiveKitRequestFields.hpp new file mode 100644 index 000000000..9cd823958 --- /dev/null +++ b/include/merovingian/homeserver/LiveKitRequestFields.hpp @@ -0,0 +1,39 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/homeserver/OperationResult.hpp" + +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +struct LiveKitTokenRequest; + +// Module-internal helpers shared by the MSC4195 request handlers (`LiveKitTokenService.cpp`, `LiveKitDelegations.cpp`). +// Not a public API. + +// A failed OperationResult with `status`, `errcode` and `reason`. +[[nodiscard]] auto livekit_refusal(std::uint16_t status, std::string errcode, std::string reason) -> OperationResult; + +// The value of `object`'s member `key`, or nullptr. +[[nodiscard]] auto livekit_member_of(canonicaljson::Object const& object, std::string_view key) + -> canonicaljson::Value const*; + +// A required string member of at most `max_bytes` bytes, at least one, valid for JSON, copied into `out`. A missing +// member is 400 `M_MISSING_PARAM`, anything else wrong 400 `M_INVALID_PARAM`; neither echoes the value. +[[nodiscard]] auto read_livekit_string(canonicaljson::Object const& object, std::string_view key, std::size_t max_bytes, + std::string& out) -> std::optional; + +// The members every MSC4195 call request carries: `url`, `room_id` (held to the shape of a room ID; it is only ever +// looked up exactly), `slot_id` and `member_id`, each within its `max_livekit_*_bytes`. The first refusal, or nullopt. +[[nodiscard]] auto read_livekit_call_members(canonicaljson::Object const& object, LiveKitTokenRequest& request) + -> std::optional; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/LiveKitRoomService.hpp b/include/merovingian/homeserver/LiveKitRoomService.hpp index 34f73038d..5f07df2fe 100644 --- a/include/merovingian/homeserver/LiveKitRoomService.hpp +++ b/include/merovingian/homeserver/LiveKitRoomService.hpp @@ -45,6 +45,15 @@ inline constexpr auto livekit_room_departure_timeout_seconds = std::uint32_t{20U std::span api_secret, std::string_view room_name, std::int64_t now_seconds) -> std::optional; +// The `GetParticipant` request for `identity` in `room_name` (both MSC4195 names), signed with a token granting +// `roomAdmin` over that one room only (`crypto::sign_livekit_room_admin_token`). Used only by the delegated delayed +// leave's checks (ADR-0832). nullopt on the same refusals as `livekit_create_room_request`, or a name that is not an +// MSC4195 name. +[[nodiscard]] auto livekit_get_participant_request(std::string_view api_url, std::string_view api_key, + std::span api_secret, std::string_view room_name, + std::string_view identity, std::int64_t now_seconds) + -> std::optional; + // Stands in for LiveKit in tests: it is handed the finished request in place of resolving and connecting. using LiveKitTestPerform = std::function; diff --git a/src/database/AGENTS.md b/src/database/AGENTS.md index d9dd084fa..5d935b3eb 100644 --- a/src/database/AGENTS.md +++ b/src/database/AGENTS.md @@ -19,6 +19,9 @@ Manages schema migrations and provides a dual-backend (SQLite / PostgreSQL) pers | `DelayedEventStore.cpp` | The delayed-event store functions and their caps (`max_delayed_event_id_bytes` 64, `max_delayed_event_content_bytes` 65,536, `max_delayed_event_error_bytes` 1,024, `max_delayed_event_field_bytes` 255, `max_delayed_event_delay_ms` 31 days): store, restart, cancel, record the outcome of a send, delete a user's rows, prune by age. Finalising evicts the user's oldest finalised rows in the same transaction (ADR-0824, ADR-0825) | | `DelayedEventStatusText.cpp` | The `status` column's text for `DelayedEventStatus` and its strict parse (an unknown text makes hydration skip the row) | | `DelayedEventRowText.cpp` | `parse_delayed_event_row`, the one strict reading of a stored row both loaders use: the three numeric columns are 1+ ASCII digits that fit 64 bits, both booleans are exactly `true` or `false`, a scheduled row's `delay_ms` is 1 to `max_delayed_event_delay_ms`, a finalised row has a non-zero `finalised_at_ms`. Anything else is skipped, never repaired or guessed | +| `LiveKitDelegationTable.cpp` | `LiveKitDelegationTable`, the in-memory copy of `livekit_delegations` (migration 004, ADR-0832): by delay ID, by (user, room, slot, member) and a count per user; the caps (`max_livekit_delegation_delay_id_bytes` 64, `max_livekit_delegation_field_bytes` 255) and `livekit_delegation_is_storable` | +| `LiveKitDelegationStore.cpp` | `store_livekit_delegation` (one transaction replaces the row of the same key and of the same delay ID), `delete_livekit_delegation`, `delete_livekit_delegations_of_user` (always runs the DELETE, so a row hydration skipped goes too) | +| `LiveKitDelegationRowText.cpp` | `parse_livekit_delegation_row`, the strict reading of a stored row both loaders use; a bad row is skipped and counted (`livekit_delegation_rows_skipped_at_load`), never repaired | | `OAuthStore.cpp` | The OAuth 2.0 store functions and their caps (`max_oauth_client_metadata_bytes` 16 KiB, `max_oauth_scope_bytes` 2048, `max_oauth_client_id_bytes` 128): insert-or-keep clients, the once-a-day touch, delete a set of clients, sessionless clients oldest first, and the session row's prepare/remember pair | | `EventTable.cpp` | `EventTable`, the in-memory mirror of the `events` table with its indexes by event ID, stream order, room and stream order, room and time, and relation target (ADR-0215, ADR-0300, ADR-0430, ADR-0435) | | `RedactionView.cpp` | Client-facing redaction presentation: adds `redacts` to `m.room.redaction` events and `redacted_because` under `unsigned` of redacted events (CSAZ-11) | @@ -230,6 +233,12 @@ single-table revokes. The grant's `oauth.session.granted` audit row is in the same transaction (ADR-0629's pattern: `audit_insert_statement`, then `remember_audit_event` after the commit). Neither table is read by the federation worker. +## LiveKit delegations (migration 004, ADR-0832) + +`PersistentStore::livekit_delegations` is a `LiveKitDelegationTable`: write it only through `LiveKitDelegationStore.hpp` +(hydration uses `insert`), and ask it by `find`, `find_by_key` and `count_of_user`. The store functions change memory +only after `commit_persistent_transaction` returns true. The federation worker's load profile never reads the table. + ## Delayed events (migration 003, ADR-0824) `PersistentStore::delayed_events` is a `DelayedEventTable`: write it only through `DelayedEventStore.hpp` (hydration diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 42d03e0e5..77808a582 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -76,7 +76,9 @@ This is the largest and most complex module — read this file carefully before | `PasswordReset.cpp` | Password reset by email (ADR-0481): `make_password_reset_token` (8 characters, 40 bits), `normalize_password_reset_token`, `send_password_reset_email` (a background task parked in `orphan_futures_`, at most 8 in flight, no lock held while it sends). The endpoints are in `ClientServerRuntime.cpp` before the auth gate; `reset_local_user_password` is in `AuthService.cpp` | | `ClientServerRuntime.cpp` (MatrixRTC) | `GET /_matrix/client/v1/rtc/transports` and `GET /_matrix/client/unstable/org.matrix.msc4143/rtc/transports` advertise `server.rtc.livekit.service_url` as `{"type":"livekit","livekit_service_url":...}` (`livekit_transport_json`): `transports` and `[]` when none on the stable path, `rtc_transports` and `{}` on the unstable one; both flags `org.matrix.msc4143` and `org.matrix.msc4143.stable` are always in `/versions`, and the well-known document gains `org.matrix.msc4143.rtc_foci` only with a URL (ADR-0822). With the built-in token service instead (`server.rtc.livekit.url`, ADR-0829) they list `{"type":"livekit","url":...}` (`livekit_sfu_transport_json`), the stable path `m.livekit` after it, and `org.matrix.msc4195` and `.stable` are true; `rtc_foci` stays for the external service only. `voip/turnServer` returns `server.turn.server` or, when that is empty, each `server.turn.uris` entry in order (ADR-0821) | | `LiveKitTokenService.cpp` | `POST /_matrix/client/{v1,unstable/io.element.msc4195}/rtc/livekit/get_token` (`issue_client_livekit_token`, ADR-0829): reads the body strictly, compares `url` with `server.rtc.livekit.url` byte for byte, requires the caller's `memberships` row to say `join` (an unknown room is the same 403), reads the API secret per request, signs through `crypto/LiveKitToken` only, and creates the LiveKit room first under an ADR-0079 slot, one deadline and `RuntimeLockRelease{guard}`. Logs under `livekit` with `user_id` and `room_id` only: never the token, the secret, the slot or the member ID | -| `LiveKitRoomService.cpp` | Every call to LiveKit's room service (ADR-0830): `livekit_create_room_request` builds the Twirp request to `server.rtc.livekit.api_url` only, with its own 60-second `roomCreate`-only token; `perform_livekit_request` resolves with the operator-trusted lookup, pins, and reads at most 16 KiB. `HomeserverRuntime::test_livekit_perform` replaces the network in tests. A new call is a row in ADR-0830 and a typed signer | +| `LiveKitRoomService.cpp` | Every call to LiveKit's room service (ADR-0830): `livekit_create_room_request` and `livekit_get_participant_request` build the Twirp request to `server.rtc.livekit.api_url` only, each with its own 60-second token (`roomCreate` only; `roomAdmin` over the one room); `perform_livekit_request` resolves with the operator-trusted lookup, pins, and reads at most 16 KiB. `HomeserverRuntime::test_livekit_perform` replaces the network in tests. A new call is a row in ADR-0830 and a typed signer | +| `LiveKitDelegations.cpp` | MSC4195's delegated delayed leave and LiveKit's webhook: `delegate_livekit_delayed_leave` (`POST .../rtc/livekit/delegate_delayed_leave`, ADR-0832: the caller's own scheduled event in a room they are joined to, delay at least 5 min, 20 per user; stores the row, makes no network call), `run_livekit_delegations` (the `livekit-delegations` `PeriodicJob`: drops rows that can no longer be acted on, asks `GetParticipant` about at most 16 due ones with `runtime.mutex` free, then restarts or sends through `manage_delayed_event` only; an unknown answer changes nothing) and `receive_livekit_webhook` (`POST /_merovingian/livekit/webhook`, ADR-0833, before the access-token gate: authenticated as LiveKit signs it, and an authentic event only sets a recorded delegation's next check to now). Never let a webhook restart or send an event. Progress (`livekit_delegation_progress`) and seen webhook IDs are in memory, guarded by `runtime.mutex` | +| `LiveKitRequestFields.cpp` | Module-internal: the request-body readers and refusal shared by `LiveKitTokenService.cpp` and `LiveKitDelegations.cpp` (`read_livekit_call_members`, `read_livekit_string`, `livekit_member_of`, `livekit_refusal`). Not public API | | `LiveKitNames.cpp` | `livekit_room_name` and `livekit_participant_identity`: MSC4195's `base64nopad(SHA-256(canonical JSON [a, b]))`, with the legacy slot `m.call#ROOM` hashed as `m.call#room` (ADR-0829). Never send a Matrix ID or room ID to LiveKit any other way | | `TurnCredentials.cpp` | `make_turn_credentials`: the coturn REST API username and password for `GET /voip/turnServer` (ADR-0480) | | `EmailPush.cpp` | Kind `"email"` pushers (ADR-0219, ADR-0220): `owned_email_pusher_address` (the pushkey must be the account's own email 3PID), `remove_email_pushers_for_address`, and `EmailPushJob`, the one thread that sends due digests through `send_due_email_notifications`. It re-reads the pusher, the 3PID, the account and the badge count under `runtime.mutex` (one hold, one `PushBadgeBudget`: rows and glob steps bounded together, ADR-0722), then sends with the mutex released | diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index a7ec9ef28..ea93a181e 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -98,6 +98,7 @@ #include "merovingian/homeserver/InvitePermission.hpp" #include "merovingian/homeserver/KeyServerCache.hpp" #include "merovingian/homeserver/LegacyAuthPolicy.hpp" +#include "merovingian/homeserver/LiveKitDelegations.hpp" #include "merovingian/homeserver/LiveKitTokenService.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/LocalHttpResponse.hpp" @@ -4203,6 +4204,9 @@ namespace "/_matrix/client/unstable/org.matrix.msc4143/rtc/transports", "/_matrix/client/v1/rtc/livekit/get_token", "/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token", + "/_matrix/client/v1/rtc/livekit/delegate_delayed_leave", + "/_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave", + "/_merovingian/livekit/webhook", "/_matrix/client/v3/room_keys/version", "/_matrix/client/v3/room_keys/keys", "/_matrix/client/v3/devices", @@ -4243,82 +4247,85 @@ namespace std::string_view allow; }; static constexpr auto routes = std::to_array({ - {"/_matrix/client/v3/admin/safety/reports", "GET, POST" }, - {"/_matrix/client/v3/admin/safety/policy_rules", "GET, POST, PUT" }, - {"/_matrix/client/v3/pushrules/", "GET" }, - {"/_matrix/client/v3/pushrules/global/", "GET" }, - {"/_matrix/client/v3/sync", "GET" }, - {"/_matrix/client/v4/sync", "GET, POST" }, - {"/_matrix/client/unstable/org.matrix.msc4186/sync", "GET, POST" }, - {"/_matrix/client/unstable/org.matrix.simplified_msc3575/sync", "GET, POST" }, - {"/_matrix/client/v3/publicRooms", "GET, POST" }, - {"/_matrix/client/v3/register/available", "GET" }, - {"/_matrix/client/v1/register/m.login.registration_token/validity", "GET" }, - {"/_matrix/client/v3/register/email/requestToken", "POST" }, - {"/_matrix/client/v3/register/msisdn/requestToken", "POST" }, - {"/_matrix/client/v3/register", "POST" }, - {"/_matrix/client/v3/login", "GET, POST" }, - {"/_matrix/client/v3/login/sso/redirect", "GET" }, - {"/_matrix/client/v1/login/get_token", "POST" }, - {"/_matrix/client/v3/refresh", "POST" }, - {"/_matrix/client/v3/logout", "POST" }, - {"/_matrix/client/v3/logout/all", "POST" }, - {"/_matrix/client/v1/auth_metadata", "GET" }, - {"/_matrix/client/unstable/org.matrix.msc2965/auth_metadata", "GET" }, - {"/_merovingian/oauth2/register", "POST" }, - {"/_merovingian/oauth2/authorize", "GET, POST" }, - {"/_merovingian/oauth2/token", "POST" }, - {"/_merovingian/oauth2/revoke", "POST" }, - {"/_merovingian/oauth2/device", "POST" }, - {"/_merovingian/oauth2/link", "GET, POST" }, - {"/_merovingian/account", "GET, POST" }, - {"/_matrix/client/v3/account/3pid/email/requestToken", "POST" }, - {"/_matrix/client/v3/account/3pid/msisdn/requestToken", "POST" }, - {"/_matrix/client/v3/account/password/email/requestToken", "POST" }, - {"/_matrix/client/v3/account/password/msisdn/requestToken", "POST" }, - {"/_matrix/client/unstable/org.merovingian/account/password/email/submitToken", "POST" }, - {"/_matrix/client/v3/account/whoami", "GET" }, - {"/_matrix/client/v3/account/password", "POST" }, - {"/_matrix/client/v3/account/deactivate", "POST" }, - {"/_matrix/client/v3/account/3pid", "GET, POST" }, - {"/_matrix/client/v3/account/3pid/add", "POST" }, - {"/_matrix/client/v3/account/3pid/bind", "POST" }, - {"/_matrix/client/v3/account/3pid/unbind", "POST" }, - {"/_matrix/client/v3/account/3pid/delete", "POST" }, - {"/_matrix/client/v3/pushers", "GET" }, - {"/_matrix/client/v3/pushers/set", "POST" }, - {"/_matrix/client/v3/notifications", "GET" }, - {"/_matrix/client/v3/capabilities", "GET" }, - {"/_matrix/client/v3/keys/changes", "GET" }, - {"/_matrix/client/v3/keys/claim", "POST" }, - {"/_matrix/client/v3/keys/device_signing/upload", "POST" }, - {"/_matrix/client/v3/keys/query", "POST" }, - {"/_matrix/client/v3/keys/signatures/upload", "POST" }, - {"/_matrix/client/v3/keys/upload", "POST" }, - {"/_matrix/client/v3/thirdparty/protocols", "GET" }, - {"/_matrix/client/v3/thirdparty/location", "GET" }, - {"/_matrix/client/v3/thirdparty/user", "GET" }, - {"/_matrix/media/v3/config", "GET" }, - {"/_matrix/media/v3/upload", "POST" }, - {"/_matrix/media/v1/create", "POST" }, - {"/_matrix/media/v3/preview_url", "GET" }, - {"/_matrix/client/v1/media/config", "GET" }, - {"/_matrix/client/v1/media/upload", "POST" }, - {"/_matrix/client/v1/media/preview_url", "GET" }, - {"/_matrix/client/v3/voip/turnServer", "GET" }, - {"/_matrix/client/v1/rtc/transports", "GET" }, - {"/_matrix/client/unstable/org.matrix.msc4143/rtc/transports", "GET" }, - {"/_matrix/client/v1/rtc/livekit/get_token", "POST" }, - {"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token", "POST" }, - {"/_matrix/client/v3/room_keys/version", "GET, POST" }, - {"/_matrix/client/v3/room_keys/keys", "DELETE, GET, PUT"}, - {"/_matrix/client/v3/devices", "GET" }, - {"/_matrix/client/v3/delete_devices", "POST" }, - {"/_matrix/client/v3/createRoom", "POST" }, - {"/_matrix/client/v3/joined_rooms", "GET" }, - {"/_matrix/client/v1/mutual_rooms", "GET" }, - {"/_matrix/client/v3/user_directory/search", "POST" }, - {"/_matrix/client/v3/search", "POST" }, + {"/_matrix/client/v3/admin/safety/reports", "GET, POST" }, + {"/_matrix/client/v3/admin/safety/policy_rules", "GET, POST, PUT" }, + {"/_matrix/client/v3/pushrules/", "GET" }, + {"/_matrix/client/v3/pushrules/global/", "GET" }, + {"/_matrix/client/v3/sync", "GET" }, + {"/_matrix/client/v4/sync", "GET, POST" }, + {"/_matrix/client/unstable/org.matrix.msc4186/sync", "GET, POST" }, + {"/_matrix/client/unstable/org.matrix.simplified_msc3575/sync", "GET, POST" }, + {"/_matrix/client/v3/publicRooms", "GET, POST" }, + {"/_matrix/client/v3/register/available", "GET" }, + {"/_matrix/client/v1/register/m.login.registration_token/validity", "GET" }, + {"/_matrix/client/v3/register/email/requestToken", "POST" }, + {"/_matrix/client/v3/register/msisdn/requestToken", "POST" }, + {"/_matrix/client/v3/register", "POST" }, + {"/_matrix/client/v3/login", "GET, POST" }, + {"/_matrix/client/v3/login/sso/redirect", "GET" }, + {"/_matrix/client/v1/login/get_token", "POST" }, + {"/_matrix/client/v3/refresh", "POST" }, + {"/_matrix/client/v3/logout", "POST" }, + {"/_matrix/client/v3/logout/all", "POST" }, + {"/_matrix/client/v1/auth_metadata", "GET" }, + {"/_matrix/client/unstable/org.matrix.msc2965/auth_metadata", "GET" }, + {"/_merovingian/oauth2/register", "POST" }, + {"/_merovingian/oauth2/authorize", "GET, POST" }, + {"/_merovingian/oauth2/token", "POST" }, + {"/_merovingian/oauth2/revoke", "POST" }, + {"/_merovingian/oauth2/device", "POST" }, + {"/_merovingian/oauth2/link", "GET, POST" }, + {"/_merovingian/account", "GET, POST" }, + {"/_matrix/client/v3/account/3pid/email/requestToken", "POST" }, + {"/_matrix/client/v3/account/3pid/msisdn/requestToken", "POST" }, + {"/_matrix/client/v3/account/password/email/requestToken", "POST" }, + {"/_matrix/client/v3/account/password/msisdn/requestToken", "POST" }, + {"/_matrix/client/unstable/org.merovingian/account/password/email/submitToken", "POST" }, + {"/_matrix/client/v3/account/whoami", "GET" }, + {"/_matrix/client/v3/account/password", "POST" }, + {"/_matrix/client/v3/account/deactivate", "POST" }, + {"/_matrix/client/v3/account/3pid", "GET, POST" }, + {"/_matrix/client/v3/account/3pid/add", "POST" }, + {"/_matrix/client/v3/account/3pid/bind", "POST" }, + {"/_matrix/client/v3/account/3pid/unbind", "POST" }, + {"/_matrix/client/v3/account/3pid/delete", "POST" }, + {"/_matrix/client/v3/pushers", "GET" }, + {"/_matrix/client/v3/pushers/set", "POST" }, + {"/_matrix/client/v3/notifications", "GET" }, + {"/_matrix/client/v3/capabilities", "GET" }, + {"/_matrix/client/v3/keys/changes", "GET" }, + {"/_matrix/client/v3/keys/claim", "POST" }, + {"/_matrix/client/v3/keys/device_signing/upload", "POST" }, + {"/_matrix/client/v3/keys/query", "POST" }, + {"/_matrix/client/v3/keys/signatures/upload", "POST" }, + {"/_matrix/client/v3/keys/upload", "POST" }, + {"/_matrix/client/v3/thirdparty/protocols", "GET" }, + {"/_matrix/client/v3/thirdparty/location", "GET" }, + {"/_matrix/client/v3/thirdparty/user", "GET" }, + {"/_matrix/media/v3/config", "GET" }, + {"/_matrix/media/v3/upload", "POST" }, + {"/_matrix/media/v1/create", "POST" }, + {"/_matrix/media/v3/preview_url", "GET" }, + {"/_matrix/client/v1/media/config", "GET" }, + {"/_matrix/client/v1/media/upload", "POST" }, + {"/_matrix/client/v1/media/preview_url", "GET" }, + {"/_matrix/client/v3/voip/turnServer", "GET" }, + {"/_matrix/client/v1/rtc/transports", "GET" }, + {"/_matrix/client/unstable/org.matrix.msc4143/rtc/transports", "GET" }, + {"/_matrix/client/v1/rtc/livekit/get_token", "POST" }, + {"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token", "POST" }, + {"/_matrix/client/v1/rtc/livekit/delegate_delayed_leave", "POST" }, + {"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave", "POST" }, + {"/_merovingian/livekit/webhook", "POST" }, + {"/_matrix/client/v3/room_keys/version", "GET, POST" }, + {"/_matrix/client/v3/room_keys/keys", "DELETE, GET, PUT"}, + {"/_matrix/client/v3/devices", "GET" }, + {"/_matrix/client/v3/delete_devices", "POST" }, + {"/_matrix/client/v3/createRoom", "POST" }, + {"/_matrix/client/v3/joined_rooms", "GET" }, + {"/_matrix/client/v1/mutual_rooms", "GET" }, + {"/_matrix/client/v3/user_directory/search", "POST" }, + {"/_matrix/client/v3/search", "POST" }, }); auto const row = std::ranges::find(routes, path, &StaticRouteMethods::path); return row == routes.end() ? std::string_view{} : row->allow; @@ -17426,6 +17433,27 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return DispatchResult{DispatchResult::Status::complete, handle_oauth_revoke(rt, req), {}}; } } + // POST /_merovingian/livekit/webhook: LiveKit's signed webhook (ADR-0833). LiveKit holds no access token, so it is + // answered before the access-token gate; with the built-in token service off the path is not served, so it is 404 + // whatever the method. Another method falls through to the 405 gate. LiveKitDelegations.cpp authenticates it; an + // authenticated event at most brings a delegation's check forward. + if (request_path == livekit_webhook_path) + { + if (rt.homeserver.config.server().rtc.token_service.url.empty()) + { + return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); + } + if (req.method == "POST") + { + auto const now_seconds = static_cast(delayed_event_now_ms(rt.homeserver) / 1000U); + auto answer = receive_livekit_webhook(rt, req, now_seconds); + if (!answer.ok) + { + return dispatch_err(req, rt, answer.status, answer.errcode, answer.reason, answer.retry_after_ms); + } + return dispatch_resp(req, rt, 200U, std::move(answer.value)); + } + } // POST /_merovingian/oauth2/device (spec "Device authorization grant", RFC 8628 section 3.1) and GET and POST // /_merovingian/oauth2/link (its verification page): answered before the access-token gate, and 404 unless both // the OAuth 2.0 API and the device grant are on (ADR-0804). Another method falls through to the 405 gate. The @@ -20224,6 +20252,20 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } return dispatch_resp(req, rt, 200U, std::move(answer.value)); } + // POST /_matrix/client/{v1,unstable/io.element.msc4195}/rtc/livekit/delegate_delayed_leave: hand this server the + // caller's delayed leave, to be restarted while LiveKit shows them and sent once it does not (MSC4195; ADR-0832). + // LiveKitDelegations.cpp judges the request and makes no network call; this only answers. + if (req.method == "POST" && + (request_path == "/_matrix/client/v1/rtc/livekit/delegate_delayed_leave" || + request_path == "/_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave")) + { + auto answer = delegate_livekit_delayed_leave(rt, req.body, *user); + if (!answer.ok) + { + return dispatch_err(req, rt, answer.status, answer.errcode, answer.reason, answer.retry_after_ms); + } + return dispatch_resp(req, rt, 200U, std::move(answer.value)); + } // Delayed events (MSC4140, ADR-0823): S1 and S2 schedule, M1 to M3 manage and G1 and G2 look up. The listing // `GET .../delayed_events` is MSC4486 and no route (`normalized_target` leaves it unmatched). Placed before the diff --git a/src/homeserver/LiveKitDelegations.cpp b/src/homeserver/LiveKitDelegations.cpp new file mode 100644 index 000000000..2ee98dbf7 --- /dev/null +++ b/src/homeserver/LiveKitDelegations.cpp @@ -0,0 +1,622 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/LiveKitDelegations.hpp" + +#include "merovingian/canonicaljson/ParseError.hpp" +#include "merovingian/canonicaljson/Parser.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/config/LiveKitTokenServiceConfig.hpp" +#include "merovingian/crypto/ConstantTime.hpp" +#include "merovingian/crypto/Encoding.hpp" +#include "merovingian/crypto/LiveKitToken.hpp" +#include "merovingian/crypto/Sha256.hpp" +#include "merovingian/database/DelayedEventStatus.hpp" +#include "merovingian/database/LiveKitDelegationStore.hpp" +#include "merovingian/database/LiveKitDelegationTable.hpp" +#include "merovingian/database/PersistentLiveKitDelegation.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/DelayedEventAction.hpp" +#include "merovingian/homeserver/DelayedEvents.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LiveKitDelegationProgress.hpp" +#include "merovingian/homeserver/LiveKitNames.hpp" +#include "merovingian/homeserver/LiveKitRequestFields.hpp" +#include "merovingian/homeserver/LiveKitRoomService.hpp" +#include "merovingian/homeserver/LiveKitTokenRequest.hpp" +#include "merovingian/homeserver/LiveKitTokenService.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/RequestHeaders.hpp" +#include "merovingian/homeserver/RoomService.hpp" +#include "merovingian/homeserver/RuntimeMutex.hpp" +#include "merovingian/homeserver/StopFlag.hpp" +#include "merovingian/http/OutboundResult.hpp" +#include "merovingian/observability/LogEventSeverity.hpp" +#include "merovingian/observability/SingleLog.hpp" +#include "merovingian/observability/StructuredLogField.hpp" +#include "merovingian/platform/FileMetadataSupport.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ +namespace +{ + + constexpr auto log_module = std::string_view{"livekit"}; + constexpr auto max_delay_id_bytes = std::size_t{64U}; + constexpr auto max_secret_file_bytes = std::size_t{4096U}; + // One GetParticipant call's budget. + constexpr auto get_participant_timeout_seconds = std::uint32_t{10U}; + constexpr auto shortest_wait = std::chrono::milliseconds{1000}; + + [[nodiscard]] auto ok_empty() -> OperationResult + { + auto result = OperationResult{}; + result.ok = true; + result.status = 200U; + result.value = "{}"; + return result; + } + + auto log_delegation(std::string_view const event, std::string_view const user_id, std::string_view const room_id, + std::string_view const detail, + observability::LogEventSeverity const severity = observability::LogEventSeverity::info) -> void + { + // Never the delay ID, the slot or the member ID. + observability::log_diagnostic(log_module, event, + { + {"user_id", std::string{user_id}, false}, + {"room_id", std::string{room_id}, false}, + {"detail", std::string{detail}, false}, + }, + severity); + } + + // The progress entry of a stored delegation, created (due now, never seen) with its names when missing. nullopt + // when the names cannot be derived, which a validated row never gives. + [[nodiscard]] auto progress_of(HomeserverRuntime& runtime, database::PersistentLiveKitDelegation const& row) + -> LiveKitDelegationProgress* + { + auto found = runtime.livekit_delegation_progress.find(row.delay_id); + if (found != runtime.livekit_delegation_progress.end()) + { + return &found->second; + } + auto room_name = livekit_room_name(row.room_id, row.slot_id); + auto identity = livekit_participant_identity(row.user_id, row.member_id); + if (!room_name.has_value() || !identity.has_value()) + { + return nullptr; + } + auto progress = LiveKitDelegationProgress{}; + progress.room_name = std::move(*room_name); + progress.identity = std::move(*identity); + return &runtime.livekit_delegation_progress.emplace(row.delay_id, std::move(progress)).first->second; + } + + auto wake(HomeserverRuntime& runtime) -> void + { + if (runtime.livekit_delegations_wake) + { + runtime.livekit_delegations_wake(); + } + } + + // Deletes the row and its progress. False when the delete did not commit; the row then stays and is dropped at a + // later run. + auto drop(HomeserverRuntime& runtime, std::string const& delay_id) -> bool + { + if (!database::delete_livekit_delegation(runtime.database.persistent_store, delay_id)) + { + return false; + } + runtime.livekit_delegation_progress.erase(delay_id); + return true; + } + + // Why a stored delegation can no longer be acted on, or empty when it can. + [[nodiscard]] auto drop_reason(HomeserverRuntime const& runtime, database::PersistentLiveKitDelegation const& row) + -> std::string_view + { + auto const& store = runtime.database.persistent_store; + if (runtime.config.server().rtc.token_service.url.empty()) + { + return "the token service is off"; + } + auto const* event = store.delayed_events.find_owned(row.user_id, row.delay_id); + if (event == nullptr || event->status != database::DelayedEventStatus::scheduled) + { + return "the delayed event is no longer scheduled"; + } + if (current_state_membership(store, row.room_id, row.user_id) != "join") + { + return "the user is no longer joined"; + } + return {}; + } + + enum class Observation + { + connected, + gone, + unknown, + }; + + [[nodiscard]] auto string_member(canonicaljson::Object const& object, std::string_view const key) + -> std::string const* + { + auto const* value = livekit_member_of(object, key); + return value == nullptr ? nullptr : std::get_if(&value->storage()); + } + + // GetParticipant's answer (ADR-0832): a ParticipantInfo whose `state` is not DISCONNECTED (an absent `state` is the + // protobuf default, JOINING) is connected; Twirp's `not_found`, or DISCONNECTED, is gone; anything else is unknown. + [[nodiscard]] auto observe(http::OutboundResult const& result) -> Observation + { + if (!result.ok) + { + return Observation::unknown; + } + auto const parsed = canonicaljson::parse_json(result.response.body); + auto const* object = std::get_if(&parsed.value.storage()); + if (parsed.error != canonicaljson::ParseError::none || object == nullptr) + { + return Observation::unknown; + } + if (result.response.status == 200U) + { + auto const* state = string_member(*object, "state"); + return state != nullptr && *state == "DISCONNECTED" ? Observation::gone : Observation::connected; + } + if (result.response.status == 404U) + { + auto const* code = string_member(*object, "code"); + return code != nullptr && *code == "not_found" ? Observation::gone : Observation::unknown; + } + return Observation::unknown; + } + + struct Check final + { + std::string delay_id; + std::string user_id; + std::string room_id; + std::string room_name; + std::string identity; + Observation observation{Observation::unknown}; + }; + + [[nodiscard]] auto wait_until(std::uint64_t const now_ms, std::uint64_t const next_ms) -> std::chrono::milliseconds + { + auto const wait = next_ms > now_ms ? std::chrono::milliseconds{next_ms - now_ms} : shortest_wait; + return std::clamp(wait, shortest_wait, livekit_delegation_check_interval); + } + + // Applies one check's answer, under the lock, to the delegation it was made for, if it is still that delegation. + auto apply(ClientServerRuntime& rt, Check const& check, std::uint64_t const now_ms) -> void + { + auto& runtime = rt.homeserver; + auto const& store = runtime.database.persistent_store; + auto const* row = store.livekit_delegations.find(check.delay_id); + if (row == nullptr || row->user_id != check.user_id || row->room_id != check.room_id) + { + return; // dropped or replaced while the lock was free + } + auto* progress = progress_of(runtime, *row); + auto const* event = store.delayed_events.find_owned(row->user_id, row->delay_id); + if (progress == nullptr || event == nullptr || event->status != database::DelayedEventStatus::scheduled) + { + return; // the next run drops it + } + progress->next_check_ms = now_ms + static_cast(livekit_delegation_check_interval.count()); + switch (check.observation) + { + case Observation::connected: { + progress->last_seen_connected_ms = now_ms; + auto const due_ms = database::delayed_event_due_ms(*event); + auto const remaining = due_ms > now_ms ? due_ms - now_ms : 0U; + if (remaining < event->delay_ms / 2U) + { + auto const restarted = + manage_delayed_event(rt, row->user_id, row->delay_id, DelayedEventAction::restart); + if (!restarted.ok) + { + log_delegation("livekit.delegation.restart_failed", row->user_id, row->room_id, restarted.reason, + observability::LogEventSeverity::warning); + } + } + return; + } + case Observation::gone: { + auto const seen = progress->last_seen_connected_ms != 0U; + if (!seen && now_ms < row->created_ms + livekit_delegation_connect_grace_ms) + { + return; // a client still connecting + } + // Copies: `row` is erased by drop(). + auto const user_id = row->user_id; + auto const room_id = row->room_id; + auto const delay_id = row->delay_id; + auto const sent = manage_delayed_event(rt, user_id, delay_id, DelayedEventAction::send); + log_delegation(sent.ok ? "livekit.delegation.sent" : "livekit.delegation.send_failed", user_id, room_id, + seen ? "the participant left" : "the participant never connected", + sent.ok ? observability::LogEventSeverity::info : observability::LogEventSeverity::warning); + // Sent or not, the delegation ends: a send that failed leaves the event to its own timer. + std::ignore = drop(runtime, delay_id); + return; + } + case Observation::unknown: + return; // no restart: without an answer the event falls back to its own timer + } + } + +} // namespace + +auto delegate_livekit_delayed_leave(ClientServerRuntime& rt, std::string_view const body, std::string const& user_id) + -> OperationResult +{ + auto& runtime = rt.homeserver; + auto const& service = runtime.config.server().rtc.token_service; + if (service.url.empty()) + { + return livekit_refusal(404U, "M_UNRECOGNIZED", "no LiveKit token service is configured"); + } + auto const parsed = canonicaljson::parse_json(body); + auto const* object = std::get_if(&parsed.value.storage()); + if (parsed.error != canonicaljson::ParseError::none || object == nullptr) + { + return livekit_refusal(400U, "M_BAD_JSON", "the body must be a JSON object"); + } + auto request = LiveKitTokenRequest{}; + if (auto refused = read_livekit_call_members(*object, request)) + { + return std::move(*refused); + } + auto delay_id = std::string{}; + if (auto refused = read_livekit_string(*object, "delay_id", max_delay_id_bytes, delay_id)) + { + return std::move(*refused); + } + if (request.url != service.url) + { + return livekit_refusal(400U, "M_INVALID_PARAM", "url is not this server's SFU"); + } + auto& store = runtime.database.persistent_store; + if (current_state_membership(store, request.room_id, user_id) != "join") + { + log_delegation("livekit.delegation.refused", user_id, request.room_id, "not joined"); + return livekit_refusal(403U, "M_FORBIDDEN", "You are not joined to this room."); + } + // MSC4195: an event that cannot be found, or is another room's or user's, is one 400; a delay ID of another user's + // is looked up as the caller's and so is never confirmed. + auto const* event = store.delayed_events.find_owned(user_id, delay_id); + if (event == nullptr || event->room_id != request.room_id || + event->status != database::DelayedEventStatus::scheduled || store.delayed_events.is_being_sent(delay_id)) + { + return livekit_refusal(400U, "M_INVALID_PARAM", "No delayed event of yours in this room can be delegated."); + } + if (event->delay_ms < livekit_delegation_min_delay_ms) + { + return livekit_refusal(400U, "M_INVALID_PARAM", "The delayed event's delay is too short to delegate."); + } + if (!livekit_room_name(request.room_id, request.slot_id).has_value() || + !livekit_participant_identity(user_id, request.member_id).has_value()) + { + return livekit_refusal(400U, "M_INVALID_PARAM", "the room or member cannot be named"); + } + auto const* same_key = + store.livekit_delegations.find_by_key(user_id, request.room_id, request.slot_id, request.member_id); + auto const* same_delay = store.livekit_delegations.find(delay_id); + if (same_key == nullptr && same_delay == nullptr && + store.livekit_delegations.count_of_user(user_id) >= livekit_delegations_per_user) + { + return livekit_refusal(429U, "M_LIMIT_EXCEEDED", "Too many delegated delayed events."); + } + // The delegations this one replaces lose their progress with their rows. + auto replaced = std::vector{}; + if (same_key != nullptr) + { + replaced.push_back(same_key->delay_id); + } + auto row = database::PersistentLiveKitDelegation{}; + row.delay_id = delay_id; + row.user_id = user_id; + row.room_id = request.room_id; + row.slot_id = request.slot_id; + row.member_id = request.member_id; + row.created_ms = delayed_event_now_ms(runtime); + if (!database::store_livekit_delegation(store, std::move(row))) + { + return livekit_refusal(500U, "M_UNKNOWN", "the delegation could not be stored"); + } + for (auto const& old : replaced) + { + runtime.livekit_delegation_progress.erase(old); + } + runtime.livekit_delegation_progress.erase(delay_id); + if (auto const* stored = store.livekit_delegations.find(delay_id); stored != nullptr) + { + std::ignore = progress_of(runtime, *stored); + } + log_delegation("livekit.delegation.stored", user_id, request.room_id, {}); + wake(runtime); + return ok_empty(); +} + +auto run_livekit_delegations(ClientServerRuntime& rt, std::uint64_t const now_ms, StopFlag const& stop) + -> std::chrono::milliseconds +{ + auto& runtime = rt.homeserver; + auto checks = std::vector{}; + auto next_ms = now_ms + static_cast(livekit_delegation_check_interval.count()); + auto service = config::LiveKitTokenServiceConfig{}; + { + auto const guard = RuntimeLock{runtime.mutex}; + service = runtime.config.server().rtc.token_service; + // A copy: drop() changes the table. + auto const rows = runtime.database.persistent_store.livekit_delegations.rows(); + for (auto const& row : rows) + { + if (auto const reason = drop_reason(runtime, row); !reason.empty()) + { + if (drop(runtime, row.delay_id)) + { + log_delegation("livekit.delegation.dropped", row.user_id, row.room_id, reason); + } + continue; + } + auto* progress = progress_of(runtime, row); + if (progress == nullptr) + { + std::ignore = drop(runtime, row.delay_id); + continue; + } + if (progress->next_check_ms <= now_ms && checks.size() < livekit_delegation_checks_per_run) + { + checks.push_back(Check{row.delay_id, row.user_id, row.room_id, progress->room_name, progress->identity, + Observation::unknown}); + } + else + { + next_ms = std::min(next_ms, std::max(progress->next_check_ms, now_ms)); + } + } + // Progress for a row no longer stored (deleted by deactivation, for one) goes too. + std::erase_if(runtime.livekit_delegation_progress, [&](auto const& entry) { + return runtime.database.persistent_store.livekit_delegations.find(entry.first) == nullptr; + }); + } + if (checks.empty()) + { + return wait_until(now_ms, next_ms); + } + + // The calls, with the lock free. One read of the secret serves this run's tokens. + if (runtime.outbound_client != nullptr && runtime.cached_discovery != nullptr) + { + auto const secret = platform::read_secure_secret_line(service.api_secret_file, max_secret_file_bytes); + auto const now_seconds = static_cast(now_ms / 1000U); + for (auto& check : checks) + { + if (stop.stop_requested() || !secret.has_value()) + { + break; + } + auto request = livekit_get_participant_request(service.api_url, service.api_key, secret->bytes(), + check.room_name, check.identity, now_seconds); + if (!request.has_value()) + { + continue; + } + check.observation = observe( + perform_livekit_request(std::move(*request), *runtime.outbound_client, *runtime.cached_discovery, + get_participant_timeout_seconds, runtime.test_livekit_perform)); + } + if (!secret.has_value()) + { + log_delegation("livekit.secret_unavailable", {}, {}, "the API secret file is unreadable or too short", + observability::LogEventSeverity::error); + } + } + + auto const guard = RuntimeLock{runtime.mutex}; + for (auto const& check : checks) + { + apply(rt, check, now_ms); + } + // Checks still due (more than one run's worth) run again soon. + auto more_due = false; + for (auto const& [delay_id, progress] : runtime.livekit_delegation_progress) + { + more_due = more_due || progress.next_check_ms <= now_ms; + next_ms = std::min(next_ms, std::max(progress.next_check_ms, now_ms)); + } + return more_due ? shortest_wait : wait_until(now_ms, next_ms); +} + +namespace +{ + + [[nodiscard]] auto unauthorised(std::string_view const reason) -> OperationResult + { + log_delegation("livekit.webhook.refused", {}, {}, reason, observability::LogEventSeverity::warning); + return livekit_refusal(401U, "M_UNAUTHORIZED", "The webhook is not signed by this server's LiveKit."); + } + + [[nodiscard]] auto int_member(canonicaljson::Object const& object, std::string_view const key) + -> std::optional + { + auto const* value = livekit_member_of(object, key); + auto const* number = value == nullptr ? nullptr : std::get_if(&value->storage()); + return number == nullptr ? std::nullopt : std::optional{*number}; + } + + // `createdAt` as protobuf JSON writes an int64: a decimal string; a bare integer is taken too. + [[nodiscard]] auto created_at_of(canonicaljson::Object const& object) -> std::optional + { + if (auto const number = int_member(object, "createdAt")) + { + return number; + } + auto const* text = string_member(object, "createdAt"); + if (text == nullptr || text->empty() || text->size() > 18U) + { + return std::nullopt; + } + auto value = std::int64_t{0}; + for (auto const c : *text) + { + if (c < '0' || c > '9') + { + return std::nullopt; + } + value = value * 10 + (c - '0'); + } + return value; + } + + [[nodiscard]] auto nested_string(canonicaljson::Object const& object, std::string_view const outer, + std::string_view const inner) -> std::string const* + { + auto const* value = livekit_member_of(object, outer); + auto const* nested = value == nullptr ? nullptr : std::get_if(&value->storage()); + return nested == nullptr ? nullptr : string_member(*nested, inner); + } + +} // namespace + +auto receive_livekit_webhook(ClientServerRuntime& rt, LocalHttpRequest const& request, std::int64_t const now_seconds) + -> OperationResult +{ + auto& runtime = rt.homeserver; + auto const& service = runtime.config.server().rtc.token_service; + if (service.url.empty()) + { + return livekit_refusal(404U, "M_UNRECOGNIZED", "Unrecognized request"); + } + if (request.body.size() > livekit_webhook_max_body_bytes) + { + return livekit_refusal(413U, "M_TOO_LARGE", "The webhook body is too large."); + } + // ADR-0833: exactly one Authorization header holding LiveKit's JWT, with or without "Bearer ". + auto const authorizations = request_header_values(request, "Authorization"); + if (authorizations.size() != 1U) + { + return unauthorised("no single Authorization header"); + } + auto token = authorizations.front(); + if (token.starts_with("Bearer ")) + { + token.remove_prefix(7U); + } + if (token.empty() || token.size() > crypto::hs256_token_max_bytes) + { + return unauthorised("malformed token"); + } + auto const secret = platform::read_secure_secret_line(service.api_secret_file, max_secret_file_bytes); + if (!secret.has_value()) + { + log_delegation("livekit.secret_unavailable", {}, {}, "the API secret file is unreadable or too short", + observability::LogEventSeverity::error); + return livekit_refusal(500U, "M_UNKNOWN", "The webhook cannot be checked."); + } + auto const verified = crypto::verify_hs256_token(token, secret->bytes()); + if (!verified.has_value()) + { + return unauthorised("bad signature"); + } + auto const claims_parsed = canonicaljson::parse_json(verified->payload_json); + auto const* claims = std::get_if(&claims_parsed.value.storage()); + if (claims_parsed.error != canonicaljson::ParseError::none || claims == nullptr) + { + return unauthorised("unreadable claims"); + } + auto const* issuer = string_member(*claims, "iss"); + if (issuer == nullptr || !crypto::constant_time_equal_variable_length(*issuer, service.api_key)) + { + return unauthorised("wrong issuer"); + } + auto const not_before = int_member(*claims, "nbf"); + auto const expires = int_member(*claims, "exp"); + if (!expires.has_value() || *expires <= now_seconds - livekit_webhook_clock_leeway_seconds || + (not_before.has_value() && *not_before > now_seconds + livekit_webhook_clock_leeway_seconds)) + { + return unauthorised("token not current"); + } + auto const* body_hash = string_member(*claims, "sha256"); + auto const digest = crypto::sha256(request.body); + auto const expected = digest.has_value() ? crypto::base64_original_encode(*digest) : std::nullopt; + if (body_hash == nullptr || !expected.has_value() || + !crypto::constant_time_equal_variable_length(*body_hash, *expected)) + { + return unauthorised("body does not match its signature"); + } + + // Authenticated. From here every answer is 200, so LiveKit does not retry, and an event only prompts a check. + auto const parsed = canonicaljson::parse_json(request.body); + auto const* event = std::get_if(&parsed.value.storage()); + if (parsed.error != canonicaljson::ParseError::none || event == nullptr) + { + return ok_empty(); + } + auto const* kind = string_member(*event, "event"); + if (kind == nullptr || + (*kind != "participant_joined" && *kind != "participant_left" && *kind != "participant_connection_aborted")) + { + return ok_empty(); + } + auto const* id = string_member(*event, "id"); + auto const created_at = created_at_of(*event); + if (id == nullptr || id->empty() || id->size() > livekit_webhook_max_event_id_bytes || !created_at.has_value() || + *created_at < now_seconds - livekit_webhook_max_age_seconds || + *created_at > now_seconds + livekit_webhook_clock_leeway_seconds) + { + return ok_empty(); + } + auto& seen = runtime.livekit_webhook_seen_ids; + if (std::ranges::find(seen, *id) != seen.end()) + { + return ok_empty(); + } + seen.push_back(*id); + if (seen.size() > livekit_webhook_seen_ids) + { + seen.pop_front(); + } + auto const* room_name = nested_string(*event, "room", "name"); + auto const* identity = nested_string(*event, "participant", "identity"); + if (room_name == nullptr || identity == nullptr) + { + return ok_empty(); + } + auto const& delegations = runtime.database.persistent_store.livekit_delegations; + for (auto& [delay_id, progress] : runtime.livekit_delegation_progress) + { + if (progress.room_name != *room_name || progress.identity != *identity) + { + continue; + } + auto const* row = delegations.find(delay_id); + if (row == nullptr || static_cast(row->created_ms / 1000U) > *created_at) + { + continue; // an event from before this delegation existed + } + progress.next_check_ms = 0U; + log_delegation("livekit.webhook.prompted", row->user_id, row->room_id, *kind); + wake(runtime); + } + return ok_empty(); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/LiveKitRequestFields.cpp b/src/homeserver/LiveKitRequestFields.cpp new file mode 100644 index 000000000..73d8c511f --- /dev/null +++ b/src/homeserver/LiveKitRequestFields.cpp @@ -0,0 +1,76 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/LiveKitRequestFields.hpp" + +#include "merovingian/canonicaljson/Serializer.hpp" +#include "merovingian/homeserver/LiveKitTokenRequest.hpp" +#include "merovingian/homeserver/LiveKitTokenService.hpp" + +#include +#include + +namespace merovingian::homeserver +{ + +auto livekit_refusal(std::uint16_t const status, std::string errcode, std::string reason) -> OperationResult +{ + auto result = OperationResult{}; + result.ok = false; + result.status = status; + result.errcode = std::move(errcode); + result.reason = std::move(reason); + return result; +} + +auto livekit_member_of(canonicaljson::Object const& object, std::string_view const key) -> canonicaljson::Value const* +{ + for (auto const& member : object) + { + if (member.key == key && member.value != nullptr) + { + return member.value.get(); + } + } + return nullptr; +} + +auto read_livekit_string(canonicaljson::Object const& object, std::string_view const key, std::size_t const max_bytes, + std::string& out) -> std::optional +{ + auto const* value = livekit_member_of(object, key); + if (value == nullptr) + { + return livekit_refusal(400U, "M_MISSING_PARAM", std::string{key} + " is required"); + } + auto const* text = std::get_if(&value->storage()); + if (text == nullptr || text->empty() || text->size() > max_bytes || !canonicaljson::string_is_valid_for_json(*text)) + { + return livekit_refusal(400U, "M_INVALID_PARAM", std::string{key} + " is not valid"); + } + out = *text; + return std::nullopt; +} + +auto read_livekit_call_members(canonicaljson::Object const& object, LiveKitTokenRequest& request) + -> std::optional +{ + if (auto refused = read_livekit_string(object, "url", max_livekit_url_bytes, request.url)) + { + return refused; + } + if (auto refused = read_livekit_string(object, "room_id", max_livekit_room_id_bytes, request.room_id)) + { + return refused; + } + if (!request.room_id.starts_with('!')) + { + return livekit_refusal(400U, "M_INVALID_PARAM", "room_id is not valid"); + } + if (auto refused = read_livekit_string(object, "slot_id", max_livekit_slot_id_bytes, request.slot_id)) + { + return refused; + } + return read_livekit_string(object, "member_id", max_livekit_member_id_bytes, request.member_id); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/LiveKitRoomService.cpp b/src/homeserver/LiveKitRoomService.cpp index 389cb61e2..af818f5a6 100644 --- a/src/homeserver/LiveKitRoomService.cpp +++ b/src/homeserver/LiveKitRoomService.cpp @@ -85,6 +85,34 @@ auto livekit_create_room_request(std::string_view const api_url, std::string_vie return request; } +auto livekit_get_participant_request(std::string_view const api_url, std::string_view const api_key, + std::span const api_secret, std::string_view const room_name, + std::string_view const identity, std::int64_t const now_seconds) + -> std::optional +{ + auto const base = parsed_api_url(api_url); + if (!base.has_value() || !crypto::livekit_name_is_valid(room_name) || !crypto::livekit_name_is_valid(identity)) + { + return std::nullopt; + } + auto token = crypto::sign_livekit_room_admin_token(api_key, api_secret, room_name, now_seconds, + now_seconds + livekit_service_token_seconds); + if (!token.has_value()) + { + return std::nullopt; + } + auto request = http::OutboundRequest{}; + request.method = "POST"; + request.url = twirp_url(*base, "GetParticipant"); + request.headers.push_back(http::OutboundHeader{"Content-Type", "application/json"}); + request.headers.push_back(http::OutboundHeader{"Authorization", "Bearer " + std::move(*token)}); + // Both names are 43 base64 characters (checked above), so they need no JSON escaping. + request.body = R"({"room":")" + std::string{room_name} + R"(","identity":")" + std::string{identity} + R"("})"; + request.allow_cleartext_http = base->scheme == "http"; + request.max_response_body_bytes = livekit_response_max_bytes; + return request; +} + auto perform_livekit_request(http::OutboundRequest request, http::OutboundClient& client, federation::CachedServerDiscovery& discovery, std::uint32_t const timeout_seconds, LiveKitTestPerform const& test_perform) -> http::OutboundResult diff --git a/src/homeserver/LiveKitTokenService.cpp b/src/homeserver/LiveKitTokenService.cpp index c8499bc48..769f3ac88 100644 --- a/src/homeserver/LiveKitTokenService.cpp +++ b/src/homeserver/LiveKitTokenService.cpp @@ -20,6 +20,7 @@ #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/LiveKitNames.hpp" +#include "merovingian/homeserver/LiveKitRequestFields.hpp" #include "merovingian/homeserver/LiveKitRoomService.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" @@ -54,73 +55,6 @@ namespace // The budget for the one call to LiveKit a token costs, before the operator's `remote_timeout` clamps it. constexpr auto livekit_call_deadline_seconds = std::uint32_t{10U}; - [[nodiscard]] auto refusal(std::uint16_t const status, std::string errcode, std::string reason) -> OperationResult - { - auto result = OperationResult{}; - result.ok = false; - result.status = status; - result.errcode = std::move(errcode); - result.reason = std::move(reason); - return result; - } - - [[nodiscard]] auto member_of(canonicaljson::Object const& object, std::string_view const key) - -> canonicaljson::Value const* - { - for (auto const& member : object) - { - if (member.key == key && member.value != nullptr) - { - return member.value.get(); - } - } - return nullptr; - } - - // A required string member of at most `max_bytes` bytes, at least one, valid for JSON, copied into `out`. A missing - // member is `M_MISSING_PARAM`, anything else wrong `M_INVALID_PARAM`; neither echoes the value. - [[nodiscard]] auto read_required_string(canonicaljson::Object const& object, std::string_view const key, - std::size_t const max_bytes, std::string& out) - -> std::optional - { - auto const* value = member_of(object, key); - if (value == nullptr) - { - return refusal(400U, "M_MISSING_PARAM", std::string{key} + " is required"); - } - auto const* text = std::get_if(&value->storage()); - if (text == nullptr || text->empty() || text->size() > max_bytes || - !canonicaljson::string_is_valid_for_json(*text)) - { - return refusal(400U, "M_INVALID_PARAM", std::string{key} + " is not valid"); - } - out = *text; - return std::nullopt; - } - - // The required members. `room_id` is held to the shape of a room ID; it is only ever looked up exactly. - [[nodiscard]] auto read_required_members(canonicaljson::Object const& object, LiveKitTokenRequest& request) - -> std::optional - { - if (auto refused = read_required_string(object, "url", max_livekit_url_bytes, request.url)) - { - return refused; - } - if (auto refused = read_required_string(object, "room_id", max_livekit_room_id_bytes, request.room_id)) - { - return refused; - } - if (!request.room_id.starts_with('!')) - { - return refusal(400U, "M_INVALID_PARAM", "room_id is not valid"); - } - if (auto refused = read_required_string(object, "slot_id", max_livekit_slot_id_bytes, request.slot_id)) - { - return refused; - } - return read_required_string(object, "member_id", max_livekit_member_id_bytes, request.member_id); - } - [[nodiscard]] auto now_seconds() -> std::int64_t { return std::chrono::duration_cast(std::chrono::system_clock::now().time_since_epoch()) @@ -149,19 +83,19 @@ auto parse_client_livekit_token_request(std::string_view const body) -> LiveKitT auto const* object = std::get_if(&parsed.value.storage()); if (parsed.error != canonicaljson::ParseError::none || object == nullptr) { - return refusal(400U, "M_BAD_JSON", "the body must be a JSON object"); + return livekit_refusal(400U, "M_BAD_JSON", "the body must be a JSON object"); } auto request = LiveKitTokenRequest{}; - if (auto refused = read_required_members(*object, request)) + if (auto refused = read_livekit_call_members(*object, request)) { return std::move(*refused); } - if (auto const* server_name = member_of(*object, "server_name"); server_name != nullptr) + if (auto const* server_name = livekit_member_of(*object, "server_name"); server_name != nullptr) { auto const* text = std::get_if(&server_name->storage()); if (text == nullptr || !auth::server_name_is_valid(*text)) { - return refusal(400U, "M_INVALID_PARAM", "server_name is not valid"); + return livekit_refusal(400U, "M_INVALID_PARAM", "server_name is not valid"); } request.server_name = *text; } @@ -229,7 +163,8 @@ namespace [[nodiscard]] auto client_outbound_refusal(ClientServerRuntime& rt) -> OperationResult { - auto limited = refusal(429U, "M_LIMIT_EXCEEDED", "too many concurrent outbound requests, retry shortly"); + auto limited = + livekit_refusal(429U, "M_LIMIT_EXCEEDED", "too many concurrent outbound requests, retry shortly"); limited.retry_after_ms = rt.homeserver.client_outbound_proxy_policy.retry_after_ms; return limited; } @@ -281,11 +216,11 @@ namespace if (room == nullptr || !room->members.has_member_of_server(request.server_name)) { log_refusal("livekit.relay.refused", user_id, request.room_id, "server not in room"); - return refusal(403U, "M_FORBIDDEN", "That server is not in this room."); + return livekit_refusal(403U, "M_FORBIDDEN", "That server is not in this room."); } if (rt.homeserver.outbound_client == nullptr || rt.homeserver.cached_discovery == nullptr) { - return refusal(502U, "M_UNKNOWN", "this server cannot make outbound requests"); + return livekit_refusal(502U, "M_UNKNOWN", "this server cannot make outbound requests"); } auto const slot = admit_client_outbound_proxy(rt.homeserver, rate_limit_client_key(req, rt.homeserver.config.server())); @@ -298,7 +233,7 @@ namespace auto const signing_key = ensure_runtime_server_signing_key(rt.homeserver); if (!signing_key.has_value()) { - return refusal(500U, "M_UNKNOWN", "this server cannot sign federation requests"); + return livekit_refusal(500U, "M_UNKNOWN", "this server cannot sign federation requests"); } // The MSC4195 federation body: the client's, with `server_name` dropped and the requesting user added. auto members = canonicaljson::Object{}; @@ -310,7 +245,7 @@ namespace auto const body = canonicaljson::serialize_canonical(canonicaljson::Value{std::move(members)}); if (body.error != canonicaljson::CanonicalJsonError::none) { - return refusal(500U, "M_UNKNOWN", "the request to the other server cannot be written"); + return livekit_refusal(500U, "M_UNKNOWN", "the request to the other server cannot be written"); } auto const transaction = federation::make_outbound_transaction(request.server_name, "POST", federation_livekit_token_path, @@ -332,27 +267,27 @@ namespace if (answer.remote_status == 403U && answer.remote_errcode == "M_FORBIDDEN") { log_refusal("livekit.relay.refused", user_id, request.room_id, "the other server refused"); - return refusal(403U, "M_FORBIDDEN", "The other server refused to issue a token."); + return livekit_refusal(403U, "M_FORBIDDEN", "The other server refused to issue a token."); } if (answer.remote_status == 400U && answer.remote_errcode == "M_INVALID_PARAM") { log_refusal("livekit.relay.refused", user_id, request.room_id, "the other server found it invalid"); - return refusal(400U, "M_INVALID_PARAM", "The other server found the request invalid."); + return livekit_refusal(400U, "M_INVALID_PARAM", "The other server found the request invalid."); } log_refusal("livekit.relay.failed", user_id, request.room_id, answer.remote_answered ? "status " + std::to_string(answer.remote_status) : "unreachable", observability::LogEventSeverity::warning); - return refusal(502U, "M_UNKNOWN", "The other server could not issue a token."); + return livekit_refusal(502U, "M_UNKNOWN", "The other server could not issue a token."); } auto const parsed = canonicaljson::parse_json(answer.body); auto const* object = std::get_if(&parsed.value.storage()); - auto const* jwt_value = object == nullptr ? nullptr : member_of(*object, "jwt"); + auto const* jwt_value = object == nullptr ? nullptr : livekit_member_of(*object, "jwt"); auto const* jwt = jwt_value == nullptr ? nullptr : std::get_if(&jwt_value->storage()); if (parsed.error != canonicaljson::ParseError::none || jwt == nullptr || !relayed_jwt_is_well_formed(*jwt)) { log_refusal("livekit.relay.failed", user_id, request.room_id, "malformed answer", observability::LogEventSeverity::warning); - return refusal(502U, "M_UNKNOWN", "The other server could not issue a token."); + return livekit_refusal(502U, "M_UNKNOWN", "The other server could not issue a token."); } observability::log_diagnostic(log_module, "livekit.relay.issued", { @@ -372,28 +307,28 @@ namespace auto const* object = std::get_if(&parsed.value.storage()); if (parsed.error != canonicaljson::ParseError::none || object == nullptr) { - return refusal(400U, "M_BAD_JSON", "the body must be a JSON object"); + return livekit_refusal(400U, "M_BAD_JSON", "the body must be a JSON object"); } auto request = LiveKitTokenRequest{}; - if (auto refused = read_required_members(*object, request)) + if (auto refused = read_livekit_call_members(*object, request)) { return std::move(*refused); } - if (auto refused = read_required_string(*object, "user_id", max_livekit_user_id_bytes, request.user_id)) + if (auto refused = read_livekit_string(*object, "user_id", max_livekit_user_id_bytes, request.user_id)) { return std::move(*refused); } if (!auth::user_id_is_valid_federated(request.user_id)) { - return refusal(400U, "M_INVALID_PARAM", "user_id is not valid"); + return livekit_refusal(400U, "M_INVALID_PARAM", "user_id is not valid"); } // MSC4195 omits `server_name` here, since it is the receiving server's own. One that names another is refused. - if (auto const* server_name = member_of(*object, "server_name"); server_name != nullptr) + if (auto const* server_name = livekit_member_of(*object, "server_name"); server_name != nullptr) { auto const* text = std::get_if(&server_name->storage()); if (text == nullptr || *text != our_server) { - return refusal(400U, "M_INVALID_PARAM", "server_name is not this server"); + return livekit_refusal(400U, "M_INVALID_PARAM", "server_name is not this server"); } } return request; @@ -407,7 +342,7 @@ auto issue_client_livekit_token(ClientServerRuntime& rt, LocalHttpRequest const& auto const& service = rt.homeserver.config.server().rtc.token_service; if (service.url.empty()) { - return refusal(404U, "M_UNRECOGNIZED", "no LiveKit token service is configured"); + return livekit_refusal(404U, "M_UNRECOGNIZED", "no LiveKit token service is configured"); } auto parsed = parse_client_livekit_token_request(req.body); if (auto* refused = std::get_if(&parsed); refused != nullptr) @@ -421,7 +356,7 @@ auto issue_client_livekit_token(ClientServerRuntime& rt, LocalHttpRequest const& // and never fetched. Another server's `url` is that server's to judge. if (!remote && request.url != service.url) { - return refusal(400U, "M_INVALID_PARAM", "url is not this server's SFU"); + return livekit_refusal(400U, "M_INVALID_PARAM", "url is not this server's SFU"); } // Joined by this server's own current state: the membership row moves with every accepted member event, in the // same transaction. An unknown room and a room the user is not joined to are the same answer. @@ -430,7 +365,7 @@ auto issue_client_livekit_token(ClientServerRuntime& rt, LocalHttpRequest const& if (membership == nullptr || membership->membership != "join") { log_refusal("livekit.token.refused", user_id, request.room_id, "not joined"); - return refusal(403U, "M_FORBIDDEN", "You are not joined to this room."); + return livekit_refusal(403U, "M_FORBIDDEN", "You are not joined to this room."); } if (remote) { @@ -440,12 +375,12 @@ auto issue_client_livekit_token(ClientServerRuntime& rt, LocalHttpRequest const& auto const identity = livekit_participant_identity(user_id, request.member_id); if (!room_name.has_value() || !identity.has_value()) { - return refusal(400U, "M_INVALID_PARAM", "the room or member cannot be named"); + return livekit_refusal(400U, "M_INVALID_PARAM", "the room or member cannot be named"); } auto signed_token = sign_for(service, *identity, *room_name, true, user_id, request.room_id); if (!signed_token.has_value()) { - return refusal(500U, "M_UNKNOWN", "LiveKit tokens are unavailable"); + return livekit_refusal(500U, "M_UNKNOWN", "LiveKit tokens are unavailable"); } // MSC4195: the room is created before a publishing token is issued, so an SFU that does not create rooms on @@ -453,7 +388,7 @@ auto issue_client_livekit_token(ClientServerRuntime& rt, LocalHttpRequest const& // runtime.mutex released around the call only. if (rt.homeserver.outbound_client == nullptr || rt.homeserver.cached_discovery == nullptr) { - return refusal(502U, "M_UNKNOWN", "this server cannot make outbound requests"); + return livekit_refusal(502U, "M_UNKNOWN", "this server cannot make outbound requests"); } auto const slot = admit_client_outbound_proxy(rt.homeserver, rate_limit_client_key(req, rt.homeserver.config.server())); @@ -476,7 +411,7 @@ auto issue_client_livekit_token(ClientServerRuntime& rt, LocalHttpRequest const& created.ok ? "status " + std::to_string(created.response.status) : std::string{http::outbound_error_name(created.error)}, observability::LogEventSeverity::warning); - return refusal(502U, "M_UNKNOWN", "the SFU could not be reached"); + return livekit_refusal(502U, "M_UNKNOWN", "the SFU could not be reached"); } observability::log_diagnostic(log_module, "livekit.token.issued", { @@ -493,7 +428,7 @@ auto issue_federation_livekit_token(HomeserverRuntime& runtime, std::string_view auto const& service = runtime.config.server().rtc.token_service; if (service.url.empty()) { - return refusal(404U, "M_UNRECOGNIZED", "no LiveKit token service is configured"); + return livekit_refusal(404U, "M_UNRECOGNIZED", "no LiveKit token service is configured"); } auto const& our_server = runtime.config.server().server_name; auto parsed = parse_federation_request(body, our_server); @@ -508,7 +443,7 @@ auto issue_federation_livekit_token(HomeserverRuntime& runtime, std::string_view // this server's own current state (ADR-0831). auto const forbidden = [&](std::string_view const reason) { log_refusal("livekit.federation.refused", request.user_id, request.room_id, reason); - return refusal(403U, "M_FORBIDDEN", "No token can be issued for this user in this room."); + return livekit_refusal(403U, "M_FORBIDDEN", "No token can be issued for this user in this room."); }; if (!room_state_is_current(store, request.room_id, our_server)) { @@ -524,20 +459,20 @@ auto issue_federation_livekit_token(HomeserverRuntime& runtime, std::string_view } if (request.url != service.url) { - return refusal(400U, "M_INVALID_PARAM", "url is not this server's SFU"); + return livekit_refusal(400U, "M_INVALID_PARAM", "url is not this server's SFU"); } auto const room_name = livekit_room_name(request.room_id, request.slot_id); auto const identity = livekit_participant_identity(request.user_id, request.member_id); if (!room_name.has_value() || !identity.has_value()) { - return refusal(400U, "M_INVALID_PARAM", "the room or member cannot be named"); + return livekit_refusal(400U, "M_INVALID_PARAM", "the room or member cannot be named"); } // A user of another server subscribes only (MSC4195 lets a server restrict publishing for them; ADR-0831): no // `canPublish`, `canPublishData`, and no CreateRoom call made on another server's behalf. auto signed_token = sign_for(service, *identity, *room_name, false, request.user_id, request.room_id); if (!signed_token.has_value()) { - return refusal(500U, "M_UNKNOWN", "LiveKit tokens are unavailable"); + return livekit_refusal(500U, "M_UNKNOWN", "LiveKit tokens are unavailable"); } observability::log_diagnostic(log_module, "livekit.federation.issued", { diff --git a/src/homeserver/meson.build b/src/homeserver/meson.build index b3b42ab36..146c3cfba 100644 --- a/src/homeserver/meson.build +++ b/src/homeserver/meson.build @@ -94,7 +94,9 @@ homeserver_sources = files( 'TlsServerContextResult.cpp', 'TlsConnection.cpp', 'TlsConnectionResult.cpp', + 'LiveKitDelegations.cpp', 'LiveKitNames.cpp', + 'LiveKitRequestFields.cpp', 'LiveKitRoomService.cpp', 'LiveKitTokenService.cpp', 'TurnCredentials.cpp', diff --git a/src/http/RateLimit.cpp b/src/http/RateLimit.cpp index 881786670..39dea4d0d 100644 --- a/src/http/RateLimit.cpp +++ b/src/http/RateLimit.cpp @@ -230,6 +230,10 @@ auto default_client_rate_limit_config() noexcept -> RateLimitConfig // again; each token for this server's SFU may cost a call to LiveKit. {"/_matrix/client/v1/rtc/livekit/get_token", {60U, 60U}}, {"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token", {60U, 60U}}, + // ADR-0832: a client delegates its leave once per call join and again when it + // replaces the delayed event; each stored delegation costs the job a call to LiveKit every 30 s. + {"/_matrix/client/v1/rtc/livekit/delegate_delayed_leave", {30U, 60U}}, + {"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave", {30U, 60U}}, }, .default_per_ip = {600U, 60U}, }; diff --git a/src/main.cpp b/src/main.cpp index b23e6d833..cd01db309 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -4,19 +4,22 @@ #include "merovingian/bootstrap/ExitCode.hpp" #include "merovingian/config/Config.hpp" #include "merovingian/config/ConfigParseResult.hpp" +#include "merovingian/config/ConfigParser.hpp" #include "merovingian/config/FederationWorkerConfig.hpp" #include "merovingian/config/ListenerConfig.hpp" #include "merovingian/config/ReloadPlan.hpp" #include "merovingian/config/ReloadPolicy.hpp" -#include "merovingian/config/ConfigParser.hpp" #include "merovingian/core/LibraryVersion.hpp" #include "merovingian/database/RuntimeDatabaseConfig.hpp" -#include "merovingian/email/SmtpEndpoint.hpp" #include "merovingian/email/SmtpClient.hpp" +#include "merovingian/email/SmtpEndpoint.hpp" #include "merovingian/federation/RuntimeFederationConfig.hpp" +#include "merovingian/homeserver/AppserviceDelivery.hpp" +#include "merovingian/homeserver/AuthService.hpp" #include "merovingian/homeserver/ClientServerClock.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/ClientTxnPrune.hpp" #include "merovingian/homeserver/DeferredPduRetryJob.hpp" #include "merovingian/homeserver/DelayedEvents.hpp" #include "merovingian/homeserver/EmailPushJob.hpp" @@ -24,24 +27,22 @@ #include "merovingian/homeserver/HttpConnectionDispatcher.hpp" #include "merovingian/homeserver/HttpServeStats.hpp" #include "merovingian/homeserver/HttpServeTuning.hpp" -#include "merovingian/homeserver/LocalDatabaseScope.hpp" -#include "merovingian/homeserver/PeriodicJob.hpp" -#include "merovingian/homeserver/PushRetryJob.hpp" -#include "merovingian/homeserver/TlsServerContext.hpp" -#include "merovingian/homeserver/AppserviceDelivery.hpp" -#include "merovingian/homeserver/AuthService.hpp" -#include "merovingian/homeserver/ClientTxnPrune.hpp" #include "merovingian/homeserver/HttpServer.hpp" #include "merovingian/homeserver/LibraryVersions.hpp" +#include "merovingian/homeserver/LiveKitDelegations.hpp" +#include "merovingian/homeserver/LocalDatabaseScope.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" +#include "merovingian/homeserver/PeriodicJob.hpp" +#include "merovingian/homeserver/PushRetryJob.hpp" #include "merovingian/homeserver/RetentionSweep.hpp" #include "merovingian/homeserver/RoomService.hpp" #include "merovingian/homeserver/StreamTokenEpoch.hpp" #include "merovingian/homeserver/Tls.hpp" +#include "merovingian/homeserver/TlsServerContext.hpp" #include "merovingian/media/ClamdScanner.hpp" #include "merovingian/media/RuntimeMediaConfig.hpp" -#include "merovingian/media/ThumbnailerConfig.hpp" #include "merovingian/media/Thumbnailer.hpp" +#include "merovingian/media/ThumbnailerConfig.hpp" #include "merovingian/net/ListenerRole.hpp" #include "merovingian/net/RuntimeListeners.hpp" #include "merovingian/net/ShutdownSignal.hpp" @@ -49,9 +50,9 @@ #include "merovingian/observability/LogLevel.hpp" #include "merovingian/observability/SingleLog.hpp" #include "merovingian/platform/FileKind.hpp" +#include "merovingian/platform/FileMetadataSupport.hpp" #include "merovingian/platform/HardeningSelfCheck.hpp" #include "merovingian/platform/HardeningStatus.hpp" -#include "merovingian/platform/FileMetadataSupport.hpp" #include "merovingian/platform/RuntimeHardening.hpp" #include "merovingian/platform/SeccompHardening.hpp" #include "merovingian/platform/SignalHardening.hpp" @@ -962,6 +963,25 @@ struct ListenerBinding final sync_pool.request_stop(); return std::nullopt; } + // Checks the MSC4195 delegated delayed leaves (ADR-0832): drops those that can no longer be acted on, asks LiveKit + // with GetParticipant about at most `livekit_delegation_checks_per_run` due ones with the runtime lock free, and + // restarts or sends their events. It sleeps at most 30 s and is woken when a delegation is stored or a webhook + // brings a check forward. Stopping waits for at most the one LiveKit call in progress (10 s). Declared after the + // pools so it is stopped and joined before them. + auto livekit_delegations_job = merovingian::homeserver::PeriodicJob{ + "livekit-delegations", [&runtime](merovingian::homeserver::StopFlag const& stop) { + return merovingian::homeserver::run_livekit_delegations( + runtime, merovingian::homeserver::delayed_event_now_ms(runtime.homeserver), stop); + }}; + if (!livekit_delegations_job.start()) + { + LOG_CRITICAL("LiveKit delegations thread failed to start; refusing to serve"); + dispatcher.request_stop(); + pool.request_stop(); + media_fetch_pool.request_stop(); + sync_pool.request_stop(); + return std::nullopt; + } // Sends a profile change to the rooms its request left (F-11, ADR-0353), taking the runtime lock // per room. It only ever touches `runtime`, which outlives this function. Declared after the // pools so it is stopped and joined before them. @@ -1071,6 +1091,9 @@ struct ListenerBinding final runtime.homeserver.delayed_events_wake = [&delayed_events_job]() { delayed_events_job.wake(); }; + runtime.homeserver.livekit_delegations_wake = [&livekit_delegations_job]() { + livekit_delegations_job.wake(); + }; } auto threads = std::vector{}; threads.reserve(bindings.size()); @@ -1144,11 +1167,15 @@ struct ListenerBinding final runtime.homeserver.typing_expiry_wake = nullptr; runtime.homeserver.profile_propagation_wake = nullptr; runtime.homeserver.delayed_events_wake = nullptr; + runtime.homeserver.livekit_delegations_wake = nullptr; } typing_expiry_job.stop(); // The wake hook is cleared above; a send in progress ends first (it makes no network call). Events still // scheduled stay in the database and are sent by the next start (ADR-0825). delayed_events_job.stop(); + // The wake hook is cleared above; a LiveKit call in progress ends first, under its own 10 s deadline. Delegations + // are stored and checked again by the next start (ADR-0832). + livekit_delegations_job.stop(); // Rooms still queued are left for the user's next profile change (ADR-0353). One room's send ends // first; it makes no network call. profile_propagation_job.stop(); diff --git a/tests/complement/merovingian.conf.template b/tests/complement/merovingian.conf.template index a18753577..f938b36af 100644 --- a/tests/complement/merovingian.conf.template +++ b/tests/complement/merovingian.conf.template @@ -90,6 +90,8 @@ client_rate_limits.per_user./_matrix/client/v3/rooms/{roomId}/delayed_event/=100 client_rate_limits.per_user./_matrix/client/unstable/org.matrix.msc4140/rooms/{roomId}/delayed_event/=1000000000/1s client_rate_limits.per_user./_matrix/client/v1/rtc/livekit/get_token=1000000000/1s client_rate_limits.per_user./_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token=1000000000/1s +client_rate_limits.per_user./_matrix/client/v1/rtc/livekit/delegate_delayed_leave=1000000000/1s +client_rate_limits.per_user./_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave=1000000000/1s # Complement logs in and registers from many parallel subtests; four concurrent # Argon2id hashes answered some of them 429 (ADR-0246). Each takes 64 MiB, so 32 # bounds a homeserver container at 2 GiB of hashing. diff --git a/tests/conformance/test_route_query_conformance.cpp b/tests/conformance/test_route_query_conformance.cpp index b4963a16d..1bd9a081a 100644 --- a/tests/conformance/test_route_query_conformance.cpp +++ b/tests/conformance/test_route_query_conformance.cpp @@ -111,7 +111,7 @@ SCENARIO("every client route that matched its whole target answers a request wit // Every route that was compared with `req.target == "..."`. A handler may answer anything // (a UIA challenge, a 400 for the empty body); what it may not do is answer as though the // route does not exist. /logout is last: it ends the session. - constexpr auto routes = std::array{ + constexpr auto routes = std::array{ { {"GET", "/.well-known/matrix/client", ""}, {"GET", "/_matrix/client/versions", ""}, @@ -154,6 +154,8 @@ SCENARIO("every client route that matched its whole target answers a request wit {"GET", "/_matrix/client/unstable/org.matrix.msc4143/rtc/transports", ""}, {"POST", "/_matrix/client/v1/rtc/livekit/get_token", "{}"}, {"POST", "/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token", "{}"}, + {"POST", "/_matrix/client/v1/rtc/livekit/delegate_delayed_leave", "{}"}, + {"POST", "/_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave", "{}"}, {"GET", "/_matrix/client/v3/devices", ""}, {"POST", "/_matrix/client/v3/delete_devices", "{}"}, {"GET", "/_matrix/client/v3/joined_rooms", ""}, diff --git a/tests/integration/test_livekit_delegation_flow.cpp b/tests/integration/test_livekit_delegation_flow.cpp new file mode 100644 index 000000000..d12853bc6 --- /dev/null +++ b/tests/integration/test_livekit_delegation_flow.cpp @@ -0,0 +1,715 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// MSC4195's delegated delayed leave (ADR-0832) and the LiveKit webhook (ADR-0833): the request, the job's decisions on +// GetParticipant's answers, and the webhook's authentication. LiveKit is a mock (`test_livekit_perform`); time is the +// delayed events' test clock and the job's `now_ms`; nothing sleeps. + +#include "../support/JsonTestSupport.hpp" +#include "../support/LiveKitTestSupport.hpp" +#include "merovingian/database/DelayedEventStatus.hpp" +#include "merovingian/database/LiveKitDelegationTable.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LiveKitDelegations.hpp" +#include "merovingian/homeserver/LiveKitNames.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/OperationResult.hpp" +#include "merovingian/homeserver/RuntimeMutex.hpp" +#include "merovingian/homeserver/StopFlag.hpp" +#include "merovingian/http/Header.hpp" +#include "merovingian/http/OutboundRequest.hpp" + +#include +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +namespace hs = merovingian::homeserver; +using namespace merovingian::tests; +using namespace merovingian::tests::livekit; + +constexpr auto t0_ms = std::uint64_t{1'800'000'000'000U}; +constexpr auto hour_ms = std::uint64_t{3'600'000U}; +constexpr auto delegate_path = std::string_view{"/_matrix/client/v1/rtc/livekit/delegate_delayed_leave"}; +constexpr auto delegate_unstable_path = + std::string_view{"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/delegate_delayed_leave"}; + +// Schedules a delayed event of the token's user in the fixture's room (their call's leave, as far as this server can +// tell: the server holds any delayed event of the user's own) and returns its delay ID. A message, so a member without +// power to send state can schedule one too. +[[nodiscard]] auto schedule_leave(LiveKitFixture& fixture, std::string const& token, std::uint64_t const delay_ms, + std::string_view const txn = "alice-call") -> std::string +{ + auto const answer = request(fixture.runtime(), "PUT", + "/_matrix/client/v3/rooms/" + fixture.room_id + "/send/m.test.leave/" + + std::string{txn} + "?org.matrix.msc4140.delay=" + std::to_string(delay_ms), + token, "{}"); + REQUIRE(answer.status == 200U); + auto const body = parse_object(answer.body); + auto const* id = string_member(body, "delay_id"); + REQUIRE(id != nullptr); + return *id; +} + +[[nodiscard]] auto delegation_body(std::string_view const room_id, std::string_view const delay_id, + std::string_view const url = sfu_url, std::string_view const slot = "m.call#room", + std::string_view const member = "DEVICEID_member") -> std::string +{ + return R"({"url":")" + std::string{url} + R"(","room_id":")" + std::string{room_id} + R"(","slot_id":")" + + std::string{slot} + R"(","member_id":")" + std::string{member} + R"(","delay_id":")" + + std::string{delay_id} + R"("})"; +} + +[[nodiscard]] auto delegate(LiveKitFixture& fixture, std::string const& token, std::string body) -> Answer +{ + return request(fixture.runtime(), "POST", std::string{delegate_path}, token, std::move(body)); +} + +[[nodiscard]] auto run_job(LiveKitFixture& fixture, std::uint64_t const now_ms) -> std::chrono::milliseconds +{ + fixture.runtime().homeserver.test_delayed_event_clock_ms = now_ms; + auto const stop = hs::StopFlag{}; + return hs::run_livekit_delegations(fixture.runtime(), now_ms, stop); +} + +[[nodiscard]] auto delayed_row(LiveKitFixture& fixture, std::string_view const delay_id) + -> merovingian::database::PersistentDelayedEvent const* +{ + return fixture.runtime().homeserver.database.persistent_store.delayed_events.find(delay_id); +} + +[[nodiscard]] auto delegations(LiveKitFixture& fixture) -> merovingian::database::LiveKitDelegationTable const& +{ + return fixture.runtime().homeserver.database.persistent_store.livekit_delegations; +} + +[[nodiscard]] auto get_participant_calls(LiveKitFixture& fixture) -> std::size_t +{ + auto count = std::size_t{0U}; + for (auto const& call : fixture.mock().requests) + { + count += call.url.ends_with("/twirp/livekit.RoomService/GetParticipant") ? 1U : 0U; + } + return count; +} + +// alice in her room, with the clock at t0, one delayed leave of an hour, delegated. +struct Delegated final +{ + LiveKitFixture fixture{}; + std::string delay_id{}; + + Delegated() + { + fixture.runtime().homeserver.test_delayed_event_clock_ms = t0_ms; + delay_id = schedule_leave(fixture, fixture.alice_token, hour_ms); + auto const answer = delegate(fixture, fixture.alice_token, delegation_body(fixture.room_id, delay_id)); + REQUIRE(answer.status == 200U); + REQUIRE(answer.body == "{}"); + } +}; + +// --- LiveKit's webhook, signed as LiveKit signs it, independently of the code under test --- + +[[nodiscard]] auto base64url(std::string_view const bytes) -> std::string +{ + auto out = std::string(sodium_base64_encoded_len(bytes.size(), sodium_base64_VARIANT_URLSAFE_NO_PADDING), '\0'); + sodium_bin2base64(out.data(), out.size(), reinterpret_cast(bytes.data()), bytes.size(), + sodium_base64_VARIANT_URLSAFE_NO_PADDING); + out.resize(out.find('\0')); + return out; +} + +[[nodiscard]] auto body_hash(std::string_view const body) -> std::string +{ + auto digest = std::array{}; + crypto_hash_sha256(digest.data(), reinterpret_cast(body.data()), body.size()); + auto out = std::string(sodium_base64_encoded_len(digest.size(), sodium_base64_VARIANT_ORIGINAL), '\0'); + sodium_bin2base64(out.data(), out.size(), digest.data(), digest.size(), sodium_base64_VARIANT_ORIGINAL); + out.resize(out.find('\0')); + return out; +} + +[[nodiscard]] auto hs256(std::string_view const payload_json, std::string_view const secret) -> std::string +{ + auto const signing_input = base64url(R"({"alg":"HS256","typ":"JWT"})") + "." + base64url(payload_json); + auto mac = std::array{}; + auto state = crypto_auth_hmacsha256_state{}; + crypto_auth_hmacsha256_init(&state, reinterpret_cast(secret.data()), secret.size()); + crypto_auth_hmacsha256_update(&state, reinterpret_cast(signing_input.data()), + signing_input.size()); + crypto_auth_hmacsha256_final(&state, mac.data()); + return signing_input + "." + base64url(std::string_view{reinterpret_cast(mac.data()), mac.size()}); +} + +struct Webhook final +{ + std::string body; + std::string authorization; +}; + +[[nodiscard]] auto webhook_event(std::string_view const event, std::string_view const room_name, + std::string_view const identity, std::string_view const id, + std::int64_t const created_at) -> std::string +{ + return R"({"event":")" + std::string{event} + R"(","room":{"name":")" + std::string{room_name} + + R"("},"participant":{"identity":")" + std::string{identity} + R"(","state":"DISCONNECTED"},"id":")" + + std::string{id} + R"(","createdAt":")" + std::to_string(created_at) + R"("})"; +} + +[[nodiscard]] auto signed_webhook(std::string body, std::int64_t const now_seconds, + std::string_view const issuer = api_key, std::string_view const secret = api_secret, + std::string const& hash_override = {}) -> Webhook +{ + auto const claims = R"({"exp":)" + std::to_string(now_seconds + 300) + R"(,"iss":")" + std::string{issuer} + + R"(","nbf":)" + std::to_string(now_seconds) + R"(,"sha256":")" + + (hash_override.empty() ? body_hash(body) : hash_override) + R"("})"; + return {std::move(body), hs256(claims, secret)}; +} + +[[nodiscard]] auto post_webhook(LiveKitFixture& fixture, Webhook const& webhook, std::int64_t const now_seconds, + std::vector headers = {}) -> hs::OperationResult +{ + auto request = hs::LocalHttpRequest{}; + request.method = "POST"; + request.target = std::string{hs::livekit_webhook_path}; + request.body = webhook.body; + if (headers.empty() && !webhook.authorization.empty()) + { + headers.push_back({"Authorization", webhook.authorization}); + } + request.headers = std::move(headers); + auto const guard = hs::RuntimeLock{fixture.runtime().homeserver.mutex}; + return hs::receive_livekit_webhook(fixture.runtime(), request, now_seconds); +} + +} // namespace + +SCENARIO("A delegation is accepted only for the caller's own scheduled event, in the room, for this server's SFU", + "[homeserver][livekit][rtc][delegation][negative]") +{ + GIVEN("alice and bob in alice's room, each with a delayed event, and the clock at t0") + { + auto fixture = LiveKitFixture{}; + fixture.runtime().homeserver.test_delayed_event_clock_ms = t0_ms; + REQUIRE( + request(fixture.runtime(), "POST", "/_matrix/client/v3/join/" + fixture.room_id, fixture.bob_token, "{}") + .status == 200U); + auto const alice_delay = schedule_leave(fixture, fixture.alice_token, hour_ms); + auto const bob_delay = schedule_leave(fixture, fixture.bob_token, hour_ms, "bob-call"); + auto const short_delay = schedule_leave(fixture, fixture.alice_token, 299'999U, "alice-short"); + + WHEN("alice delegates bob's event, an unknown one, one too short, or names another SFU") + { + auto const foreign = delegate(fixture, fixture.alice_token, delegation_body(fixture.room_id, bob_delay)); + auto const unknown = delegate(fixture, fixture.alice_token, delegation_body(fixture.room_id, "nosuch")); + auto const other_room = + delegate(fixture, fixture.alice_token, delegation_body("!other:example.org", alice_delay)); + auto const too_short = + delegate(fixture, fixture.alice_token, delegation_body(fixture.room_id, short_delay)); + auto const wrong_url = delegate(fixture, fixture.alice_token, + delegation_body(fixture.room_id, alice_delay, "wss://sfu.example.org/")); + + THEN("each is 400 M_INVALID_PARAM, bob's and an unknown one alike, and nothing is stored") + { + for (auto const* answer : {&foreign, &unknown, &too_short, &wrong_url}) + { + CHECK(answer->status == 400U); + CHECK(errcode_of(*answer) == "M_INVALID_PARAM"); + } + CHECK(foreign.body == unknown.body); + CHECK(other_room.status == 403U); // not joined to that room + CHECK(delegations(fixture).size() == 0U); + } + } + + WHEN("a body is malformed") + { + auto const body = GENERATE(std::string{"[]"}, std::string{"{}"}, + std::string{R"({"url":"wss://sfu.example.org","room_id":"!r:example.org"})"}, + std::string{R"({"url":"wss://sfu.example.org","room_id":"!r:example.org",)" + R"("slot_id":"s","member_id":"m","delay_id":5})"}, + std::string{R"({"url":"wss://sfu.example.org","room_id":"!r:example.org",)" + R"("slot_id":"s","member_id":"m","delay_id":")"} + + std::string(65U, 'd') + R"("})"); + auto const answer = delegate(fixture, fixture.alice_token, body); + + THEN("it is a 400 and nothing is stored") + { + CHECK(answer.status == 400U); + CHECK(delegations(fixture).size() == 0U); + } + } + + WHEN("alice delegates her own event on either path") + { + auto const path = std::string{GENERATE(delegate_path, delegate_unstable_path)}; + auto const answer = request(fixture.runtime(), "POST", path, fixture.alice_token, + delegation_body(fixture.room_id, alice_delay)); + + THEN("it is 200 {} and one delegation is stored, with nothing called yet") + { + CHECK(answer.status == 200U); + CHECK(answer.body == "{}"); + REQUIRE(delegations(fixture).size() == 1U); + CHECK(delegations(fixture).find(alice_delay) != nullptr); + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("there is no access token") + { + auto const answer = request(fixture.runtime(), "POST", std::string{delegate_unstable_path}, {}, {}); + + THEN("it is 401, never 404, so Element Call's probe finds the route") + { + CHECK(answer.status == 401U); + } + } + } + + GIVEN("a server with no token service") + { + auto started = hs::start_client_server(livekit_config({})); + REQUIRE(started.started); + auto const token = login(started.runtime, "alice"); + + WHEN("a delegation is asked for") + { + auto const answer = request(started.runtime, "POST", std::string{delegate_path}, token, + delegation_body("!r:example.org", "d")); + + THEN("it is 404 M_UNRECOGNIZED") + { + CHECK(answer.status == 404U); + CHECK(errcode_of(answer) == "M_UNRECOGNIZED"); + } + } + } +} + +SCENARIO("One delegation per room, slot and member; a new delay ID replaces the old; at most 20 per user", + "[homeserver][livekit][rtc][delegation]") +{ + GIVEN("alice's delegated leave") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + + WHEN("she delegates a second event for the same slot and member") + { + auto const second = schedule_leave(fixture, fixture.alice_token, hour_ms, "alice-call-2"); + auto const answer = delegate(fixture, fixture.alice_token, delegation_body(fixture.room_id, second)); + + THEN("it replaces the first") + { + CHECK(answer.status == 200U); + CHECK(delegations(fixture).size() == 1U); + CHECK(delegations(fixture).find(second) != nullptr); + CHECK(delegations(fixture).find(delegated.delay_id) == nullptr); + } + } + + WHEN("she holds 20 delegations and asks for a 21st with a new member") + { + for (auto index = 1; index < 20; ++index) + { + auto const id = schedule_leave(fixture, fixture.alice_token, hour_ms, "k" + std::to_string(index)); + REQUIRE(delegate(fixture, fixture.alice_token, + delegation_body(fixture.room_id, id, sfu_url, "m.call#room", + "member" + std::to_string(index))) + .status == 200U); + } + auto const extra = schedule_leave(fixture, fixture.alice_token, hour_ms, "k-extra"); + auto const refused = delegate(fixture, fixture.alice_token, + delegation_body(fixture.room_id, extra, sfu_url, "m.call#room", "member-x")); + + THEN("it is 429 M_LIMIT_EXCEEDED and nothing is evicted") + { + CHECK(refused.status == 429U); + CHECK(errcode_of(refused) == "M_LIMIT_EXCEEDED"); + CHECK(delegations(fixture).size() == 20U); + } + } + } +} + +SCENARIO("The job restarts a delegated leave while LiveKit shows the participant, with a GetParticipant-only token", + "[homeserver][livekit][rtc][delegation]") +{ + GIVEN("alice's delegated one-hour leave, and LiveKit answering that she is connected") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = R"({"identity":"x","state":"ACTIVE"})"; + + WHEN("the job runs at t0, then 31 minutes later") + { + std::ignore = run_job(fixture, t0_ms); + auto const since_first = delayed_row(fixture, delegated.delay_id)->delayed_since_ms; + std::ignore = run_job(fixture, t0_ms + 31U * 60'000U); + auto const* row = delayed_row(fixture, delegated.delay_id); + + THEN("the first run leaves the timer, and the second, with under half the delay left, restarts it") + { + CHECK(since_first == t0_ms); + REQUIRE(row != nullptr); + CHECK(row->status == merovingian::database::DelayedEventStatus::scheduled); + CHECK(row->delayed_since_ms == t0_ms + 31U * 60'000U); + } + + THEN("each call asked LiveKit's API address for the participant's MSC4195 room and identity only") + { + REQUIRE(get_participant_calls(fixture) == 2U); + auto const& call = fixture.mock().requests.back(); + CHECK(call.url == "https://sfu-api.example.org:443/twirp/livekit.RoomService/GetParticipant"); + auto const room_name = hs::livekit_room_name(fixture.room_id, "m.call#room"); + auto const identity = hs::livekit_participant_identity("@alice:example.org", "DEVICEID_member"); + REQUIRE((room_name.has_value() && identity.has_value())); + CHECK(call.body == R"({"room":")" + *room_name + R"(","identity":")" + *identity + R"("})"); + auto const authorization = header_value(call, "Authorization"); + REQUIRE(authorization.has_value()); + REQUIRE(authorization->starts_with("Bearer ")); + auto const payload = verified_payload(std::string_view{*authorization}.substr(7U)); + CHECK(string_member(payload, "sub") == nullptr); + auto const* video = object_member_as_object(payload, "video"); + REQUIRE(video != nullptr); + CHECK(video->size() == 2U); + auto const* admin = bool_member(*video, "roomAdmin"); + auto const* room = string_member(*video, "room"); + REQUIRE((admin != nullptr && room != nullptr)); + CHECK(*admin); + CHECK(*room == *room_name); + } + } + + WHEN("the job runs 10 seconds after t0, before the check interval has passed") + { + std::ignore = run_job(fixture, t0_ms); + std::ignore = run_job(fixture, t0_ms + 10'000U); + + THEN("LiveKit was asked once") + { + CHECK(get_participant_calls(fixture) == 1U); + } + } + } +} + +SCENARIO("The job sends a delegated leave once LiveKit no longer shows a participant it saw", + "[homeserver][livekit][rtc][delegation]") +{ + GIVEN("alice's delegated leave, seen connected at t0") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = R"({"state":"ACTIVE"})"; + std::ignore = run_job(fixture, t0_ms); + + WHEN("LiveKit then answers not_found, or the participant DISCONNECTED") + { + auto const gone = GENERATE(std::pair{404U, R"({"code":"not_found","msg":"x"})"}, + std::pair{200U, R"({"state":"DISCONNECTED"})"}); + fixture.mock().get_participant_status = gone.first; + fixture.mock().get_participant_body = gone.second; + std::ignore = run_job(fixture, t0_ms + 31'000U); + auto const* row = delayed_row(fixture, delegated.delay_id); + + THEN("the leave is sent at once and the delegation ends") + { + REQUIRE(row != nullptr); + CHECK(row->status == merovingian::database::DelayedEventStatus::sent); + CHECK(delegations(fixture).size() == 0U); + } + } + + WHEN("LiveKit cannot be reached, or answers something else") + { + auto const unknown = GENERATE(0, 1, 2); + if (unknown == 0) + { + fixture.mock().reachable = false; + } + else + { + fixture.mock().get_participant_status = unknown == 1 ? 500U : 404U; + fixture.mock().get_participant_body = unknown == 1 ? "{}" : R"({"code":"permission_denied"})"; + } + std::ignore = run_job(fixture, t0_ms + 31U * 60'000U); + auto const* row = delayed_row(fixture, delegated.delay_id); + + THEN("nothing is sent and nothing is restarted: the event keeps its own timer") + { + REQUIRE(row != nullptr); + CHECK(row->status == merovingian::database::DelayedEventStatus::scheduled); + CHECK(row->delayed_since_ms == t0_ms); + CHECK(delegations(fixture).size() == 1U); + } + } + } + + GIVEN("alice's delegated leave, never seen connected") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 404U; + fixture.mock().get_participant_body = R"({"code":"not_found"})"; + + WHEN("LiveKit answers not_found within the 2-minute grace, then after it") + { + std::ignore = run_job(fixture, t0_ms + 60'000U); + auto const status_in_grace = delayed_row(fixture, delegated.delay_id)->status; + std::ignore = run_job(fixture, t0_ms + 120'000U); + auto const* row = delayed_row(fixture, delegated.delay_id); + + THEN("it waits for a client still connecting, then sends the leave") + { + CHECK(status_in_grace == merovingian::database::DelayedEventStatus::scheduled); + REQUIRE(row != nullptr); + CHECK(row->status == merovingian::database::DelayedEventStatus::sent); + } + } + } +} + +SCENARIO("A delegation ends without a call when its event is no longer scheduled or its user leaves", + "[homeserver][livekit][rtc][delegation]") +{ + GIVEN("alice's delegated leave") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + + WHEN("she cancels the event, then the job runs") + { + REQUIRE(request(fixture.runtime(), "POST", + "/_matrix/client/v1/delayed_events/" + delegated.delay_id + "/cancel", fixture.alice_token, + "{}") + .status == 200U); + std::ignore = run_job(fixture, t0_ms); + + THEN("the delegation is dropped and LiveKit is not asked") + { + CHECK(delegations(fixture).size() == 0U); + CHECK(get_participant_calls(fixture) == 0U); + } + } + } + + GIVEN("bob's delegated leave in alice's room") + { + auto fixture = LiveKitFixture{}; + fixture.runtime().homeserver.test_delayed_event_clock_ms = t0_ms; + REQUIRE( + request(fixture.runtime(), "POST", "/_matrix/client/v3/join/" + fixture.room_id, fixture.bob_token, "{}") + .status == 200U); + auto const delay_id = schedule_leave(fixture, fixture.bob_token, hour_ms, "bob-call"); + REQUIRE(delegate(fixture, fixture.bob_token, delegation_body(fixture.room_id, delay_id)).status == 200U); + + WHEN("bob leaves the room, then the job runs") + { + REQUIRE(request(fixture.runtime(), "POST", "/_matrix/client/v3/rooms/" + fixture.room_id + "/leave", + fixture.bob_token, "{}") + .status == 200U); + std::ignore = run_job(fixture, t0_ms); + + THEN("the delegation is dropped and the event is left to its own timer") + { + CHECK(delegations(fixture).size() == 0U); + CHECK(get_participant_calls(fixture) == 0U); + auto const* row = delayed_row(fixture, delay_id); + REQUIRE(row != nullptr); + CHECK(row->status == merovingian::database::DelayedEventStatus::scheduled); + } + } + } +} + +SCENARIO("A LiveKit webhook is believed only when LiveKit signed it, and then only prompts a check", + "[homeserver][livekit][rtc][delegation][webhook]") +{ + GIVEN("alice's delegated leave, checked at t0 and seen connected") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = R"({"state":"ACTIVE"})"; + std::ignore = run_job(fixture, t0_ms); + REQUIRE(get_participant_calls(fixture) == 1U); + auto const now_s = static_cast((t0_ms + 5'000U) / 1000U); + auto const room_name = *hs::livekit_room_name(fixture.room_id, "m.call#room"); + auto const identity = *hs::livekit_participant_identity("@alice:example.org", "DEVICEID_member"); + auto const left = webhook_event("participant_left", room_name, identity, "EV_1", now_s); + + WHEN("a webhook is unsigned, signed with another secret, by another key, stale, or for another body") + { + auto const unsigned_hook = post_webhook(fixture, Webhook{left, {}}, now_s); + auto const other_secret = + post_webhook(fixture, signed_webhook(left, now_s, api_key, "fedcba9876543210fedcba9876543210"), now_s); + auto const other_key = post_webhook(fixture, signed_webhook(left, now_s, "APIother"), now_s); + auto const expired = post_webhook(fixture, signed_webhook(left, now_s - 400), now_s); + auto const other_body = + post_webhook(fixture, signed_webhook(left, now_s, api_key, api_secret, body_hash("{}")), now_s); + auto const twice = post_webhook(fixture, signed_webhook(left, now_s), now_s, + { + {"Authorization", signed_webhook(left, now_s).authorization}, + {"Authorization", signed_webhook(left, now_s).authorization} + }); + std::ignore = run_job(fixture, t0_ms + 6'000U); + + THEN("each is 401 M_UNAUTHORIZED and no check is brought forward") + { + for (auto const* answer : {&unsigned_hook, &other_secret, &other_key, &expired, &other_body, &twice}) + { + CHECK(answer->status == 401U); + CHECK(answer->errcode == "M_UNAUTHORIZED"); + } + CHECK(get_participant_calls(fixture) == 1U); + } + } + + WHEN("LiveKit's signed participant_left arrives, with or without a Bearer prefix") + { + auto webhook = signed_webhook(left, now_s); + if (GENERATE(false, true)) + { + webhook.authorization = "Bearer " + webhook.authorization; + } + fixture.mock().get_participant_status = 404U; + fixture.mock().get_participant_body = R"({"code":"not_found"})"; + auto const answer = post_webhook(fixture, webhook, now_s); + auto const status_after_webhook = delayed_row(fixture, delegated.delay_id)->status; + std::ignore = run_job(fixture, t0_ms + 6'000U); + + THEN("it is 200, changes nothing by itself, and the next run checks at once and sends the leave") + { + CHECK(answer.status == 200U); + CHECK(status_after_webhook == merovingian::database::DelayedEventStatus::scheduled); + CHECK(get_participant_calls(fixture) == 2U); + CHECK(delayed_row(fixture, delegated.delay_id)->status == + merovingian::database::DelayedEventStatus::sent); + } + } + + WHEN("a signed webhook is replayed, stale, of another kind, or for no recorded delegation") + { + auto const first = post_webhook(fixture, signed_webhook(left, now_s), now_s); + std::ignore = run_job(fixture, t0_ms + 6'000U); + auto const calls_after_first = get_participant_calls(fixture); + auto const replay = post_webhook(fixture, signed_webhook(left, now_s), now_s); + auto const stale = post_webhook( + fixture, + signed_webhook(webhook_event("participant_left", room_name, identity, "EV_2", now_s - 400), now_s), + now_s); + auto const other_kind = post_webhook( + fixture, signed_webhook(webhook_event("track_published", room_name, identity, "EV_3", now_s), now_s), + now_s); + auto const stranger = post_webhook( + fixture, + signed_webhook(webhook_event("participant_left", room_name, std::string(43U, 'A'), "EV_4", now_s), + now_s), + now_s); + std::ignore = run_job(fixture, t0_ms + 7'000U); + + THEN("each is 200 and none brings a check forward") + { + CHECK(first.status == 200U); + for (auto const* answer : {&replay, &stale, &other_kind, &stranger}) + { + CHECK(answer->status == 200U); + } + CHECK(get_participant_calls(fixture) == calls_after_first); + } + } + + WHEN("a webhook is larger than 64 KiB") + { + auto const answer = post_webhook(fixture, signed_webhook(std::string(64U * 1024U + 1U, ' '), now_s), now_s); + + THEN("it is 413") + { + CHECK(answer.status == 413U); + } + } + } +} + +SCENARIO("The webhook route is answered before the access-token gate, and only with the token service on", + "[homeserver][livekit][rtc][delegation][webhook][client-server]") +{ + GIVEN("a server with the token service on and LiveKit's signed webhook for an unknown room") + { + auto fixture = LiveKitFixture{}; + auto const now_ms = std::uint64_t{t0_ms}; + fixture.runtime().homeserver.test_delayed_event_clock_ms = now_ms; + auto const now_s = static_cast(now_ms / 1000U); + auto const webhook = signed_webhook( + webhook_event("participant_left", std::string(43U, 'B'), std::string(43U, 'C'), "EV_route", now_s), now_s); + auto const dispatch = [&fixture](std::string method, std::vector headers, + std::string body) { + auto request = hs::LocalHttpRequest{}; + request.method = std::move(method); + request.target = std::string{hs::livekit_webhook_path} + "?unused=1"; + request.body = std::move(body); + request.headers = std::move(headers); + return hs::handle_client_server_request(fixture.runtime(), std::move(request)).response; + }; + + WHEN("it is posted with no access token, signed and unsigned, and fetched with GET") + { + auto const signed_reply = dispatch("POST", + { + {"Authorization", webhook.authorization} + }, + webhook.body); + auto const unsigned_reply = dispatch("POST", {}, webhook.body); + auto const get_reply = dispatch("GET", {}, {}); + + THEN("the signed one is 200 {}, the unsigned one the webhook's 401, and GET 405") + { + CHECK(signed_reply.status == 200U); + CHECK(signed_reply.body == "{}"); + CHECK(unsigned_reply.status == 401U); + CHECK(unsigned_reply.body.find("M_UNAUTHORIZED") != std::string::npos); + CHECK(unsigned_reply.body.find("M_MISSING_TOKEN") == std::string::npos); + CHECK(get_reply.status == 405U); + } + } + } + + GIVEN("a server with no token service") + { + auto started = hs::start_client_server(livekit_config({})); + REQUIRE(started.started); + + WHEN("the webhook path is posted to") + { + auto request = hs::LocalHttpRequest{}; + request.method = "POST"; + request.target = std::string{hs::livekit_webhook_path}; + request.body = "{}"; + auto const reply = hs::handle_client_server_request(started.runtime, std::move(request)).response; + + THEN("it is 404, as a path this server does not serve") + { + CHECK(reply.status == 404U); + CHECK(reply.body.find("M_UNRECOGNIZED") != std::string::npos); + } + } + } +} diff --git a/tests/integration/test_livekit_token_flow.cpp b/tests/integration/test_livekit_token_flow.cpp index c0b70c731..c9ee886af 100644 --- a/tests/integration/test_livekit_token_flow.cpp +++ b/tests/integration/test_livekit_token_flow.cpp @@ -7,6 +7,7 @@ #include "../support/ConsoleLogCapture.hpp" #include "../support/InMemoryDatabaseConfig.hpp" #include "../support/JsonTestSupport.hpp" +#include "../support/LiveKitTestSupport.hpp" #include "../support/MasterKey.hpp" #include "../support/RegistrationToken.hpp" #include "../support/TempDirectory.hpp" @@ -49,15 +50,11 @@ #include #include #include -#include -#include #include #include -#include #include #include #include -#include #include #include #include @@ -69,211 +66,7 @@ namespace namespace hs = merovingian::homeserver; using namespace merovingian::tests; - -constexpr auto sfu_url = std::string_view{"wss://sfu.example.org"}; -constexpr auto api_url = std::string_view{"https://sfu-api.example.org"}; -constexpr auto api_key = std::string_view{"APIkey_test"}; -// 32 bytes, the minimum the signers accept. -constexpr auto api_secret = std::string_view{"0123456789abcdef0123456789abcdef"}; -constexpr auto stable_path = std::string_view{"/_matrix/client/v1/rtc/livekit/get_token"}; -constexpr auto unstable_path = std::string_view{"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token"}; -constexpr auto password = std::string_view{"CorrectHorse7!"}; - -[[nodiscard]] auto secret_bytes(std::string_view const text) -> std::vector -{ - return {text.begin(), text.end()}; -} - -class SecretFile final -{ -public: - explicit SecretFile(std::string_view const contents) - : m_directory{temporary_directory() / ("merovingian-livekit-" + std::to_string(std::random_device{}()))} - { - std::filesystem::create_directories(m_directory); - std::filesystem::permissions(m_directory, std::filesystem::perms::owner_all); - m_path = m_directory / "livekit_secret"; - auto stream = std::ofstream{m_path, std::ios::binary}; - stream << contents; - stream.close(); - std::filesystem::permissions(m_path, std::filesystem::perms::owner_read); - } - ~SecretFile() - { - auto ignored = std::error_code{}; - std::filesystem::remove_all(m_directory, ignored); - } - SecretFile(SecretFile const&) = delete; - auto operator=(SecretFile const&) -> SecretFile& = delete; - SecretFile(SecretFile&&) = delete; - auto operator=(SecretFile&&) -> SecretFile& = delete; - - [[nodiscard]] auto path() const -> std::string - { - return m_path.string(); - } - -private: - std::filesystem::path m_directory; - std::filesystem::path m_path; -}; - -// The configuration with the built-in service on when `secret_path` is set, off when it is empty. -[[nodiscard]] auto livekit_config(std::string const& secret_path) -> merovingian::config::Config -{ - auto security = merovingian::config::SecurityConfig{}; - security.secrets.master_key_file = shared_master_key_file(); - enable_token_registration(security); - auto server = merovingian::config::ServerConfig{}; - if (!secret_path.empty()) - { - server.rtc.token_service.url = std::string{sfu_url}; - server.rtc.token_service.api_url = std::string{api_url}; - server.rtc.token_service.api_key = std::string{api_key}; - server.rtc.token_service.api_secret_file = secret_path; - server.rtc.token_service.token_lifetime_seconds = 600U; - } - return { - std::move(server), merovingian::config::ListenersConfig{}, in_memory_database_config(), - std::move(security), merovingian::config::ClientRateLimitsConfig{}, merovingian::config::LogModulesConfig{}, - }; -} - -struct Answer final -{ - std::uint16_t status{}; - std::string body{}; -}; - -[[nodiscard]] auto request(hs::ClientServerRuntime& runtime, std::string method, std::string target, std::string token, - std::string body) -> Answer -{ - auto const result = hs::handle_client_server_request( - runtime, {std::move(method), std::move(target), std::move(token), std::move(body)}); - return {result.response.status, result.response.body}; -} - -[[nodiscard]] auto errcode_of(Answer const& answer) -> std::string -{ - auto const body = parse_object(answer.body); - auto const* errcode = string_member(body, "errcode"); - return errcode == nullptr ? std::string{} : *errcode; -} - -[[nodiscard]] auto login(hs::ClientServerRuntime& runtime, std::string const& localpart) -> std::string -{ - REQUIRE( - request(runtime, "POST", "/_matrix/client/v3/register", {}, registration_json(localpart, std::string{password})) - .status == 200U); - auto const response = - request(runtime, "POST", "/_matrix/client/v3/login", {}, - R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":"@)" + localpart + - R"(:example.org"},"password":")" + std::string{password} + R"(","device_id":"D1"})"); - REQUIRE(response.status == 200U); - auto const body = parse_object(response.body); - auto const* token = string_member(body, "access_token"); - REQUIRE(token != nullptr); - return *token; -} - -[[nodiscard]] auto token_body(std::string_view const room_id, std::string_view const url = sfu_url, - std::string_view const member_id = "DEVICEID_member") -> std::string -{ - return R"({"url":")" + std::string{url} + R"(","room_id":")" + std::string{room_id} + - R"(","slot_id":"m.call#room","member_id":")" + std::string{member_id} + R"(","server_name":"example.org"})"; -} - -// LiveKit, as far as the room service goes: records each request and answers with `status`, or fails the call. -struct MockLiveKit final -{ - std::vector requests{}; - std::uint16_t status{200U}; - bool reachable{true}; -}; - -auto install_mock(hs::ClientServerRuntime& runtime, std::shared_ptr const& mock) -> void -{ - runtime.homeserver.test_livekit_perform = [mock](merovingian::http::OutboundRequest const& outbound) { - mock->requests.push_back(outbound); - auto result = merovingian::http::OutboundResult{}; - result.ok = mock->reachable; - if (mock->reachable) - { - result.response.status = mock->status; - result.response.body = "{}"; - } - else - { - result.error = merovingian::http::OutboundError::network_error; - result.error_detail = "connection refused"; - } - return result; - }; -} - -[[nodiscard]] auto header_value(merovingian::http::OutboundRequest const& outbound, std::string_view const name) - -> std::optional -{ - for (auto const& header : outbound.headers) - { - if (header.name == name) - { - return header.value; - } - } - return std::nullopt; -} - -[[nodiscard]] auto verified_payload(std::string_view const token) -> merovingian::canonicaljson::Object -{ - auto const secret = secret_bytes(api_secret); - auto const verified = merovingian::crypto::verify_hs256_token(token, std::span{secret}); - REQUIRE(verified.has_value()); - CHECK(verified->header_json == R"({"alg":"HS256","typ":"JWT"})"); - return parse_object(verified->payload_json); -} - -// A server with the service on, alice in a public room and bob registered but not in it. -class LiveKitFixture final -{ -public: - explicit LiveKitFixture(std::string const& secret_path = {}) - : m_secret{api_secret} - , m_started{hs::start_client_server(livekit_config(secret_path.empty() ? m_secret.path() : secret_path))} - , m_mock{std::make_shared()} - { - REQUIRE(m_started.started); - install_mock(runtime(), m_mock); - alice_token = login(runtime(), "alice"); - bob_token = login(runtime(), "bob"); - auto const created = - request(runtime(), "POST", "/_matrix/client/v3/createRoom", alice_token, R"({"preset":"public_chat"})"); - REQUIRE(created.status == 200U); - auto const body = parse_object(created.body); - auto const* id = string_member(body, "room_id"); - REQUIRE(id != nullptr); - room_id = *id; - } - - [[nodiscard]] auto runtime() -> hs::ClientServerRuntime& - { - return m_started.runtime; - } - - [[nodiscard]] auto mock() const -> MockLiveKit& - { - return *m_mock; - } - - std::string alice_token{}; - std::string bob_token{}; - std::string room_id{}; - -private: - SecretFile m_secret; - hs::ClientServerStartResult m_started; - std::shared_ptr m_mock; -}; +using namespace merovingian::tests::livekit; constexpr auto remote_server = std::string_view{"remote.example.org"}; constexpr auto carol = std::string_view{"@carol:remote.example.org"}; diff --git a/tests/meson.build b/tests/meson.build index 0a25cfa97..36ac35d9d 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -1015,6 +1015,7 @@ shell = find_program('sh') 'integration/test_delayed_events_flow.cpp', 'integration/test_delayed_events_routes_flow.cpp', 'integration/test_livekit_token_flow.cpp', + 'integration/test_livekit_delegation_flow.cpp', 'integration/test_security_issues_460_463_flow.cpp', 'integration/test_server_signing_key_lifecycle_flow.cpp', 'integration/test_sync_dag_gap_flow.cpp', diff --git a/tests/support/AGENTS.md b/tests/support/AGENTS.md index 43684a265..17cd62b0b 100644 --- a/tests/support/AGENTS.md +++ b/tests/support/AGENTS.md @@ -22,6 +22,7 @@ Shared test utilities used across unit, conformance, and integration tests. | `ForgedUnsigned.hpp` | `with_forged_unsigned()` / `forged_unsigned_json`: a signed PDU with the `unsigned` a hostile relaying server would write (`m.relations`, `redacted_because`, `prev_content`, `age`, `transaction_id`, `membership`). The signatures and event ID still hold, so it ingests like the genuine PDU (ADR-0402) | | `StatePduSupport.hpp` | `state_pdu_support`: `make_state_pdu` and `make_topic_pdu`, a room-version-12 state PDU with a correct content hash, given prev and auth events and an `origin_server_ts`, for scenarios that fork a room's graph through `ingest_pdu_event` | | `SyncStateAfterSupport.hpp` | `state_after_support`: the config, request, `/sync` and response-reading helpers the `use_state_after` conformance and integration scenarios share (`state_after_config`, `call`, `register_user`, `create_room`, `sync`, `required_room`, `events_of`, `event_types`, `member_keys`, ...). Drives the runtime the caller started | +| `LiveKitTestSupport.hpp` | `livekit`: a server with the built-in LiveKit token service on (`LiveKitFixture`, `livekit_config()`; alice in a public room, bob registered), its API secret in a mode-0400 file (`SecretFile`), `MockLiveKit` installed as `test_livekit_perform` (records each request; answers `GetParticipant` and other calls separately, or fails them), and the request, login and token-verifying helpers the LiveKit flow tests share. LiveKit is never reached over the network | | `RegistrationToken.hpp` | Generates registration tokens for test users without going through the full UIAA flow | | `FakeClamdServer.hpp` | `FakeClamdServer`: a clamd stand-in on a temporary AF_UNIX socket. Reads INSTREAM exchanges, records the streamed bytes and answers with a fixed reply (or stays silent for the timeout case). Another I/O exception, shared by the unit and integration suites (G15, ADR-0565); assert on its recorded data from the test thread only | | `TempDirectory.hpp` | `temporary_directory()`: the fallback-aware temporary directory for test scratch files; `unique_temporary_path(stem, extension)`: a name under it unique to the process and call (pid, counter, random), not created. Every scratch file or directory a test creates is named with it, never a fixed name (ADR-0753) | diff --git a/tests/support/LiveKitTestSupport.hpp b/tests/support/LiveKitTestSupport.hpp new file mode 100644 index 000000000..60beee557 --- /dev/null +++ b/tests/support/LiveKitTestSupport.hpp @@ -0,0 +1,258 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +// A server with the built-in LiveKit token service on (ADR-0829), a stand-in for LiveKit's room service, and the +// request helpers the LiveKit flow tests share. LiveKit is never reached over the network. + +#include "InMemoryDatabaseConfig.hpp" +#include "JsonTestSupport.hpp" +#include "MasterKey.hpp" +#include "RegistrationToken.hpp" +#include "TempDirectory.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/config/ClientRateLimitsConfig.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/config/ListenersConfig.hpp" +#include "merovingian/config/LogModulesConfig.hpp" +#include "merovingian/config/SecurityConfig.hpp" +#include "merovingian/config/ServerConfig.hpp" +#include "merovingian/crypto/LiveKitToken.hpp" +#include "merovingian/crypto/VerifiedHs256Token.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/http/OutboundError.hpp" +#include "merovingian/http/OutboundRequest.hpp" +#include "merovingian/http/OutboundResult.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::tests::livekit +{ + +inline constexpr auto sfu_url = std::string_view{"wss://sfu.example.org"}; +inline constexpr auto api_url = std::string_view{"https://sfu-api.example.org"}; +inline constexpr auto api_key = std::string_view{"APIkey_test"}; +// 32 bytes, the minimum the signers accept. +inline constexpr auto api_secret = std::string_view{"0123456789abcdef0123456789abcdef"}; +inline constexpr auto stable_path = std::string_view{"/_matrix/client/v1/rtc/livekit/get_token"}; +inline constexpr auto unstable_path = + std::string_view{"/_matrix/client/unstable/io.element.msc4195/rtc/livekit/get_token"}; +inline constexpr auto password = std::string_view{"CorrectHorse7!"}; + +[[nodiscard]] inline auto secret_bytes(std::string_view const text) -> std::vector +{ + return {text.begin(), text.end()}; +} + +class SecretFile final +{ +public: + explicit SecretFile(std::string_view const contents) + : m_directory{temporary_directory() / ("merovingian-livekit-" + std::to_string(std::random_device{}()))} + { + std::filesystem::create_directories(m_directory); + std::filesystem::permissions(m_directory, std::filesystem::perms::owner_all); + m_path = m_directory / "livekit_secret"; + auto stream = std::ofstream{m_path, std::ios::binary}; + stream << contents; + stream.close(); + std::filesystem::permissions(m_path, std::filesystem::perms::owner_read); + } + ~SecretFile() + { + auto ignored = std::error_code{}; + std::filesystem::remove_all(m_directory, ignored); + } + SecretFile(SecretFile const&) = delete; + auto operator=(SecretFile const&) -> SecretFile& = delete; + SecretFile(SecretFile&&) = delete; + auto operator=(SecretFile&&) -> SecretFile& = delete; + + [[nodiscard]] auto path() const -> std::string + { + return m_path.string(); + } + +private: + std::filesystem::path m_directory; + std::filesystem::path m_path; +}; + +// The configuration with the built-in service on when `secret_path` is set, off when it is empty. +[[nodiscard]] inline auto livekit_config(std::string const& secret_path) -> merovingian::config::Config +{ + auto security = merovingian::config::SecurityConfig{}; + security.secrets.master_key_file = shared_master_key_file(); + enable_token_registration(security); + auto server = merovingian::config::ServerConfig{}; + if (!secret_path.empty()) + { + server.rtc.token_service.url = std::string{sfu_url}; + server.rtc.token_service.api_url = std::string{api_url}; + server.rtc.token_service.api_key = std::string{api_key}; + server.rtc.token_service.api_secret_file = secret_path; + server.rtc.token_service.token_lifetime_seconds = 600U; + } + return { + std::move(server), merovingian::config::ListenersConfig{}, in_memory_database_config(), + std::move(security), merovingian::config::ClientRateLimitsConfig{}, merovingian::config::LogModulesConfig{}, + }; +} + +struct Answer final +{ + std::uint16_t status{}; + std::string body{}; +}; + +[[nodiscard]] inline auto request(homeserver::ClientServerRuntime& runtime, std::string method, std::string target, + std::string token, std::string body) -> Answer +{ + auto const result = homeserver::handle_client_server_request( + runtime, {std::move(method), std::move(target), std::move(token), std::move(body)}); + return {result.response.status, result.response.body}; +} + +[[nodiscard]] inline auto errcode_of(Answer const& answer) -> std::string +{ + auto const body = parse_object(answer.body); + auto const* errcode = string_member(body, "errcode"); + return errcode == nullptr ? std::string{} : *errcode; +} + +[[nodiscard]] inline auto login(homeserver::ClientServerRuntime& runtime, std::string const& localpart) -> std::string +{ + REQUIRE( + request(runtime, "POST", "/_matrix/client/v3/register", {}, registration_json(localpart, std::string{password})) + .status == 200U); + auto const response = + request(runtime, "POST", "/_matrix/client/v3/login", {}, + R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":"@)" + localpart + + R"(:example.org"},"password":")" + std::string{password} + R"(","device_id":"D1"})"); + REQUIRE(response.status == 200U); + auto const body = parse_object(response.body); + auto const* token = string_member(body, "access_token"); + REQUIRE(token != nullptr); + return *token; +} + +[[nodiscard]] inline auto token_body(std::string_view const room_id, std::string_view const url = sfu_url, + std::string_view const member_id = "DEVICEID_member") -> std::string +{ + return R"({"url":")" + std::string{url} + R"(","room_id":")" + std::string{room_id} + + R"(","slot_id":"m.call#room","member_id":")" + std::string{member_id} + R"(","server_name":"example.org"})"; +} + +// LiveKit, as far as the room service goes: records each request and answers `GetParticipant` with +// `get_participant_status` and `get_participant_body`, any other call with `status` and `{}`, or fails the call. +struct MockLiveKit final +{ + std::vector requests{}; + std::uint16_t status{200U}; + std::uint16_t get_participant_status{500U}; + std::string get_participant_body{"{}"}; + bool reachable{true}; +}; + +inline auto install_mock(homeserver::ClientServerRuntime& runtime, std::shared_ptr const& mock) -> void +{ + runtime.homeserver.test_livekit_perform = [mock](merovingian::http::OutboundRequest const& outbound) { + mock->requests.push_back(outbound); + auto result = merovingian::http::OutboundResult{}; + result.ok = mock->reachable; + if (mock->reachable) + { + auto const get_participant = outbound.url.ends_with("/twirp/livekit.RoomService/GetParticipant"); + result.response.status = get_participant ? mock->get_participant_status : mock->status; + result.response.body = get_participant ? mock->get_participant_body : std::string{"{}"}; + } + else + { + result.error = merovingian::http::OutboundError::network_error; + result.error_detail = "connection refused"; + } + return result; + }; +} + +[[nodiscard]] inline auto header_value(merovingian::http::OutboundRequest const& outbound, std::string_view const name) + -> std::optional +{ + for (auto const& header : outbound.headers) + { + if (header.name == name) + { + return header.value; + } + } + return std::nullopt; +} + +[[nodiscard]] inline auto verified_payload(std::string_view const token) -> merovingian::canonicaljson::Object +{ + auto const secret = secret_bytes(api_secret); + auto const verified = merovingian::crypto::verify_hs256_token(token, std::span{secret}); + REQUIRE(verified.has_value()); + CHECK(verified->header_json == R"({"alg":"HS256","typ":"JWT"})"); + return parse_object(verified->payload_json); +} + +// A server with the service on, alice in a public room and bob registered but not in it. +class LiveKitFixture final +{ +public: + explicit LiveKitFixture(std::string const& secret_path = {}) + : m_secret{api_secret} + , m_started{homeserver::start_client_server( + livekit_config(secret_path.empty() ? m_secret.path() : secret_path))} + , m_mock{std::make_shared()} + { + REQUIRE(m_started.started); + install_mock(runtime(), m_mock); + alice_token = login(runtime(), "alice"); + bob_token = login(runtime(), "bob"); + auto const created = + request(runtime(), "POST", "/_matrix/client/v3/createRoom", alice_token, R"({"preset":"public_chat"})"); + REQUIRE(created.status == 200U); + auto const body = parse_object(created.body); + auto const* id = string_member(body, "room_id"); + REQUIRE(id != nullptr); + room_id = *id; + } + + [[nodiscard]] auto runtime() -> homeserver::ClientServerRuntime& + { + return m_started.runtime; + } + + [[nodiscard]] auto mock() const -> MockLiveKit& + { + return *m_mock; + } + + std::string alice_token{}; + std::string bob_token{}; + std::string room_id{}; + +private: + SecretFile m_secret; + homeserver::ClientServerStartResult m_started; + std::shared_ptr m_mock; +}; + +} // namespace merovingian::tests::livekit From 10528a7b55be154bdf7d41c2c8f4f37c2a236d73 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 14:33:06 +0000 Subject: [PATCH 10/19] Check the room's server ACL for LiveKit tokens and bind each check to its delegation The federated get_token names its room in the body, so the route-level server ACL check never saw it, and an ACL leaves a denied server's users joined: a denied server could get a subscribe-only token for the call. Main now refuses a denied origin with the same 403, and a client's token request is not relayed to a server the room denies (ADR-0831). A GetParticipant answer is applied only to the delegation it was asked for (slot, member, creation time, LiveKit names), so a delegation stored again while the lock was free is not taken as seen. One run drops at most 64 delegations, keeping one lock hold bounded (ADR-0832). Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 +- ...ged-by-main-and-answered-subscribe-only.md | 7 +- ...e-participant-and-sent-once-it-does-not.md | 8 +- docs/threat-model.md | 6 +- .../homeserver/LiveKitDelegations.hpp | 2 + src/homeserver/LiveKitDelegations.cpp | 26 ++++- src/homeserver/LiveKitTokenService.cpp | 13 ++- .../test_livekit_delegation_flow.cpp | 95 +++++++++++++++++++ tests/integration/test_livekit_token_flow.cpp | 50 ++++++++++ 9 files changed, 197 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5deb55d84..9ad43f720 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * MatrixRTC calls on LiveKit need no `lk-jwt-service`: `POST .../rtc/livekit/get_token` (MSC4195) issues tokens to joined users; `server.rtc.livekit.url`, `api_url`, `api_key` and `api_secret_file` turn it on (ADR-0829, ADR-0830). * A token for another server's SFU is relayed to it over federation, and other servers' joined users get subscribe-only - tokens for this server's SFU, judged by the main process (ADR-0831). + tokens for this server's SFU, judged by the main process and refused to a server the room's ACL denies (ADR-0831). * `delegate_delayed_leave` (MSC4195): this server sends a caller's delayed leave once LiveKit no longer shows them, checked every 30 s and sooner on LiveKit's signed webhook, kept across restarts (ADR-0832, ADR-0833). diff --git a/docs/adr/0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md b/docs/adr/0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md index 8cf2da363..18ed3ebc4 100644 --- a/docs/adr/0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md +++ b/docs/adr/0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md @@ -42,11 +42,14 @@ On this server, inbound federation is parsed by the federation worker. The worke cannot change the origin or the body, or replay a frame. 4. Main judges the request with `issue_federation_livekit_token`, holding `runtime.mutex`, by its own state: * this server is in the room (`room_state_is_current`: the create event is held and a local user is joined); + * the room's current `m.room.server_acl` allows the origin (`room_server_acl_allows`). The room is named in the + body, not the path, so the route-level ACL check in `InboundRequest.cpp` never sees it, and an ACL does not change + a membership: without this check a denied server whose user is still joined would get a token for the call; * `user_id`'s server is the origin; * the user's current `m.room.member` state is `join`; * `url` is `server.rtc.livekit.url`, byte for byte. - The first three are one 403 `M_FORBIDDEN`, "No token can be issued for this user in this room.", so a server learns + The first four are one 403 `M_FORBIDDEN`, "No token can be issued for this user in this room.", so a server learns nothing about a room it has no member in. The last is 400 `M_INVALID_PARAM`. A body naming a `server_name` other than this server's is 400 too. 5. The token is signed in main and returned to the worker, which answers it. The worker answers a refused frame @@ -68,7 +71,7 @@ When `server_name` is not this server's, `issue_client_livekit_token`: 1. Requires the caller joined here (the same 403 as for this server's SFU). 2. Requires the named server to have a member joined by this server's roster (`RoomMembers::has_member_of_server`), - else 403 `M_FORBIDDEN` (MSC4195). + and the room's server ACL to allow it, else 403 `M_FORBIDDEN` (MSC4195). A server the room denies is not asked. 3. Takes an ADR-0079 slot (429 without one) and one deadline of 10 seconds, clamped by `remote_timeout`. 4. Sends `{member_id, room_id, slot_id, url, user_id}` over signed federation (`perform_outbound_call`, `OutboundAnswerTrust::unverified`, at most 8 KiB of answer) to the stable path only, with `runtime.mutex` released diff --git a/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md b/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md index 389cb8cf3..9e1c6e2fe 100644 --- a/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md +++ b/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md @@ -56,12 +56,18 @@ start. A job in the main process, `livekit-delegations`, checks each delegation about every 30 seconds with LiveKit's `GetParticipant` for the delegation's room name and identity (MSC4195 names, ADR-0829), at most 16 calls a run, with `runtime.mutex` released for the calls (ADR-0830). Under the lock, before any call, a delegation is dropped (its row -deleted, the event left as it is) when: +deleted, the event left as it is), at most 64 a run so that one lock hold stays bounded (each drop is a commit, and +erasing from the in-memory table costs its size; the rest go on the next run, soon after), when: * its delayed event is no longer scheduled (sent, cancelled or failed); * the user is no longer joined to the room; * the token service is no longer configured. +After a call, under the lock again, an answer is applied only to the delegation it was asked for: the same delay ID, +user, room, slot, member and creation time, with the same LiveKit room name and identity. A delegation stored again +while the lock was free (another member for the same delay ID, say) is a different participant, and the answer is +dropped rather than recorded as seeing it. + After a call: * **Connected** (an answer for the participant in a state other than `DISCONNECTED`): recorded. If less than half the diff --git a/docs/threat-model.md b/docs/threat-model.md index 12a0da372..0cc236762 100644 --- a/docs/threat-model.md +++ b/docs/threat-model.md @@ -3385,8 +3385,10 @@ worker never reads the configuration or the secret. (b) A token for someone who should not have one. A token goes only to a caller this server authenticated (access token, account gate) and finds joined by its own current room state, never by the request: a user not joined, and a room that does not exist, get the same 403. A federated request is judged by main, for the origin main verified, and needs the -user to be of that origin and joined by this server's state; the three refusals are one 403, so a server learns nothing -about a room it has no member in (ADR-0831). +user to be of that origin and joined by this server's state, and the room's server ACL to allow the origin (the room is +named in the body, so the route-level ACL check does not cover it, and an ACL leaves a denied server's users joined); the +four refusals are one 403, so a server learns nothing about a room it has no member in (ADR-0831). A relay goes only to a +server the room's ACL allows. (c) More rights than a call needs. A local user's token joins one room and may publish and subscribe; another server's user's token may only subscribe. Lifetime is 60 to 3600 seconds. The room name and identity are MSC4195's diff --git a/include/merovingian/homeserver/LiveKitDelegations.hpp b/include/merovingian/homeserver/LiveKitDelegations.hpp index 80a7c59f6..96bdf1473 100644 --- a/include/merovingian/homeserver/LiveKitDelegations.hpp +++ b/include/merovingian/homeserver/LiveKitDelegations.hpp @@ -30,6 +30,8 @@ inline constexpr auto livekit_delegation_check_interval = std::chrono::milliseco inline constexpr auto livekit_delegation_connect_grace_ms = std::uint64_t{120'000U}; // GetParticipant calls made by one run of the job, so one run's lock-free stretch stays bounded. inline constexpr auto livekit_delegation_checks_per_run = std::size_t{16U}; +// At most this many delegations are dropped in one run, each a commit under the lock; the rest wait for the next run. +inline constexpr auto livekit_delegation_drops_per_run = std::size_t{64U}; // The webhook body and the event `id` LiveKit sends, at most. inline constexpr auto livekit_webhook_max_body_bytes = std::size_t{64U * 1024U}; inline constexpr auto livekit_webhook_max_event_id_bytes = std::size_t{128U}; diff --git a/src/homeserver/LiveKitDelegations.cpp b/src/homeserver/LiveKitDelegations.cpp index 2ee98dbf7..37b34b5fa 100644 --- a/src/homeserver/LiveKitDelegations.cpp +++ b/src/homeserver/LiveKitDelegations.cpp @@ -192,6 +192,9 @@ namespace std::string delay_id; std::string user_id; std::string room_id; + std::string slot_id; + std::string member_id; + std::uint64_t created_ms{0U}; std::string room_name; std::string identity; Observation observation{Observation::unknown}; @@ -208,12 +211,19 @@ namespace { auto& runtime = rt.homeserver; auto const& store = runtime.database.persistent_store; + // The whole delegation, not only its delay ID: one stored again while the lock was free (another slot or + // member, or the same anew) is not the participant this answer is about. auto const* row = store.livekit_delegations.find(check.delay_id); - if (row == nullptr || row->user_id != check.user_id || row->room_id != check.room_id) + if (row == nullptr || row->user_id != check.user_id || row->room_id != check.room_id || + row->slot_id != check.slot_id || row->member_id != check.member_id || row->created_ms != check.created_ms) { return; // dropped or replaced while the lock was free } auto* progress = progress_of(runtime, *row); + if (progress != nullptr && (progress->room_name != check.room_name || progress->identity != check.identity)) + { + return; + } auto const* event = store.delayed_events.find_owned(row->user_id, row->delay_id); if (progress == nullptr || event == nullptr || event->status != database::DelayedEventStatus::scheduled) { @@ -364,12 +374,20 @@ auto run_livekit_delegations(ClientServerRuntime& rt, std::uint64_t const now_ms { auto const guard = RuntimeLock{runtime.mutex}; service = runtime.config.server().rtc.token_service; - // A copy: drop() changes the table. + // A copy: drop() changes the table. Each drop is a commit and costs the table's size (an erase renumbers its + // indexes), so one run drops at most `livekit_delegation_drops_per_run`; the rest go on the next, soon after. auto const rows = runtime.database.persistent_store.livekit_delegations.rows(); + auto drops = std::size_t{0U}; for (auto const& row : rows) { if (auto const reason = drop_reason(runtime, row); !reason.empty()) { + if (drops == livekit_delegation_drops_per_run) + { + next_ms = now_ms; + continue; + } + ++drops; if (drop(runtime, row.delay_id)) { log_delegation("livekit.delegation.dropped", row.user_id, row.room_id, reason); @@ -384,8 +402,8 @@ auto run_livekit_delegations(ClientServerRuntime& rt, std::uint64_t const now_ms } if (progress->next_check_ms <= now_ms && checks.size() < livekit_delegation_checks_per_run) { - checks.push_back(Check{row.delay_id, row.user_id, row.room_id, progress->room_name, progress->identity, - Observation::unknown}); + checks.push_back(Check{row.delay_id, row.user_id, row.room_id, row.slot_id, row.member_id, + row.created_ms, progress->room_name, progress->identity, Observation::unknown}); } else { diff --git a/src/homeserver/LiveKitTokenService.cpp b/src/homeserver/LiveKitTokenService.cpp index 769f3ac88..8e452d511 100644 --- a/src/homeserver/LiveKitTokenService.cpp +++ b/src/homeserver/LiveKitTokenService.cpp @@ -15,6 +15,7 @@ #include "merovingian/database/PersistentMembership.hpp" #include "merovingian/database/PersistentStore.hpp" #include "merovingian/federation/OutboundTransactionSupport.hpp" +#include "merovingian/federation/ServerAcl.hpp" #include "merovingian/homeserver/BoundedOutboundLimits.hpp" #include "merovingian/homeserver/ClientOutboundProxy.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" @@ -213,7 +214,10 @@ namespace RuntimeLock& guard) -> OperationResult { auto const* room = find_local_room(rt.homeserver.database, request.room_id); - if (room == nullptr || !room->members.has_member_of_server(request.server_name)) + // A server the room's ACL denies is not one this server deals with in the room, joined members or not. + if (room == nullptr || !room->members.has_member_of_server(request.server_name) || + !federation::room_server_acl_allows(rt.homeserver.database.persistent_store, request.room_id, + request.server_name)) { log_refusal("livekit.relay.refused", user_id, request.room_id, "server not in room"); return livekit_refusal(403U, "M_FORBIDDEN", "That server is not in this room."); @@ -440,7 +444,8 @@ auto issue_federation_livekit_token(HomeserverRuntime& runtime, std::string_view auto const& store = runtime.database.persistent_store; // MSC4195, in its order: this server joined to the room, the user of the origin, the user joined; each 403 // M_FORBIDDEN with one text, so the answer tells a server nothing about a room it has no member in. All judged by - // this server's own current state (ADR-0831). + // this server's own current state (ADR-0831). The room is named in the body, not the path, so the route-level + // server ACL check never sees it: the room's ACL is checked here, and a denied origin is refused like any other. auto const forbidden = [&](std::string_view const reason) { log_refusal("livekit.federation.refused", request.user_id, request.room_id, reason); return livekit_refusal(403U, "M_FORBIDDEN", "No token can be issued for this user in this room."); @@ -449,6 +454,10 @@ auto issue_federation_livekit_token(HomeserverRuntime& runtime, std::string_view { return forbidden("this server is not in the room"); } + if (!federation::room_server_acl_allows(store, request.room_id, origin)) + { + return forbidden("the room's server ACL denies the origin"); + } if (auth::user_id_server_name(request.user_id) != origin) { return forbidden("user_id is not of the origin"); diff --git a/tests/integration/test_livekit_delegation_flow.cpp b/tests/integration/test_livekit_delegation_flow.cpp index d12853bc6..1ebb86660 100644 --- a/tests/integration/test_livekit_delegation_flow.cpp +++ b/tests/integration/test_livekit_delegation_flow.cpp @@ -8,7 +8,9 @@ #include "../support/JsonTestSupport.hpp" #include "../support/LiveKitTestSupport.hpp" #include "merovingian/database/DelayedEventStatus.hpp" +#include "merovingian/database/LiveKitDelegationStore.hpp" #include "merovingian/database/LiveKitDelegationTable.hpp" +#include "merovingian/database/PersistentLiveKitDelegation.hpp" #include "merovingian/database/PersistentStore.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" @@ -487,6 +489,99 @@ SCENARIO("The job sends a delegated leave once LiveKit no longer shows a partici } } +SCENARIO("A delegation stored again while a check was in flight is not given that check's answer", + "[homeserver][livekit][rtc][delegation]") +{ + GIVEN("alice's delegated leave, and LiveKit answering that she is connected") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = R"({"identity":"x","state":"ACTIVE"})"; + + WHEN("while LiveKit is asked, with the lock free, she delegates the same delay ID for another member") + { + auto const answer_connected = fixture.runtime().homeserver.test_livekit_perform; + auto redelegated = Answer{}; + fixture.runtime().homeserver.test_livekit_perform = + [&](merovingian::http::OutboundRequest const& outbound) { + redelegated = delegate( + fixture, fixture.alice_token, + delegation_body(fixture.room_id, delegated.delay_id, sfu_url, "m.call#room", "OTHER_member")); + return answer_connected(outbound); + }; + std::ignore = run_job(fixture, t0_ms); + fixture.runtime().homeserver.test_livekit_perform = answer_connected; + auto const& progress = fixture.runtime().homeserver.livekit_delegation_progress; + auto const entry = progress.find(delegated.delay_id); + + THEN("the new delegation is stored, and the old member's answer does not count as seeing the new one") + { + CHECK(redelegated.status == 200U); + auto const* row = delegations(fixture).find(delegated.delay_id); + REQUIRE(row != nullptr); + CHECK(row->member_id == "OTHER_member"); + REQUIRE(entry != progress.end()); + CHECK(entry->second.last_seen_connected_ms == 0U); + } + + AND_WHEN("a minute later LiveKit does not know the new member") + { + fixture.mock().get_participant_status = 404U; + fixture.mock().get_participant_body = R"({"code":"not_found","msg":"participant not found"})"; + std::ignore = run_job(fixture, t0_ms + 60'000U); + + THEN("the leave is not sent: the new member is still inside its time to connect") + { + auto const* event = delayed_row(fixture, delegated.delay_id); + REQUIRE(event != nullptr); + CHECK(event->status == merovingian::database::DelayedEventStatus::scheduled); + CHECK(delegations(fixture).size() == 1U); + } + } + } + } +} + +SCENARIO("One run drops a bounded number of delegations, and the rest soon after", + "[homeserver][livekit][rtc][delegation]") +{ + GIVEN("alice's delegated leave, and 70 stored delegations whose events are not scheduled") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + auto& store = fixture.runtime().homeserver.database.persistent_store; + constexpr auto stale = std::size_t{70U}; + for (auto index = std::size_t{0U}; index < stale; ++index) + { + auto row = merovingian::database::PersistentLiveKitDelegation{}; + row.delay_id = "stale-" + std::to_string(index); + row.user_id = "@stale" + std::to_string(index / 20U) + ":example.org"; + row.room_id = fixture.room_id; + row.slot_id = "m.call#room"; + row.member_id = "member-" + std::to_string(index); + row.created_ms = t0_ms; + REQUIRE(merovingian::database::store_livekit_delegation(store, std::move(row))); + } + REQUIRE(delegations(fixture).size() == stale + 1U); + + WHEN("the job runs once, then again") + { + auto const first_wait = run_job(fixture, t0_ms); + auto const after_first = delegations(fixture).size(); + std::ignore = run_job(fixture, t0_ms + 1'000U); + + THEN("the first run drops 64 and asks to run again soon; the second drops the rest and keeps alice's") + { + CHECK(after_first == stale + 1U - hs::livekit_delegation_drops_per_run); + CHECK(first_wait < hs::livekit_delegation_check_interval); + CHECK(delegations(fixture).size() == 1U); + CHECK(delegations(fixture).find(delegated.delay_id) != nullptr); + } + } + } +} + SCENARIO("A delegation ends without a call when its event is no longer scheduled or its user leaves", "[homeserver][livekit][rtc][delegation]") { diff --git a/tests/integration/test_livekit_token_flow.cpp b/tests/integration/test_livekit_token_flow.cpp index c9ee886af..b7f364afd 100644 --- a/tests/integration/test_livekit_token_flow.cpp +++ b/tests/integration/test_livekit_token_flow.cpp @@ -88,6 +88,19 @@ auto seed_remote_join(hs::ClientServerRuntime& runtime, std::string const& room_ std::ignore = room->members.add(std::string{user_id}); } +// Makes the room's current `m.room.server_acl` allow every server but `denied`. +auto seed_server_acl(hs::ClientServerRuntime& runtime, std::string const& room_id, std::string_view const denied) + -> void +{ + auto& store = runtime.homeserver.database.persistent_store; + auto const event_id = std::string{"$server-acl"}; + auto const json = R"({"content":{"allow":["*"],"allow_ip_literals":false,"deny":[")" + std::string{denied} + + R"("]},"event_id":")" + event_id + R"(","room_id":")" + room_id + + R"(","sender":"@alice:example.org","state_key":"","type":"m.room.server_acl"})"; + store.events.push_back({event_id, room_id, "@alice:example.org", json, 11U, 0U, {}, {}, {}}); + store.state.push_back({room_id, "m.room.server_acl", "", event_id}); +} + // MSC4195's federation body, as `origin` would send it. [[nodiscard]] auto federation_body(std::string_view const room_id, std::string_view const user_id, std::string_view const url = sfu_url) -> std::string @@ -753,6 +766,23 @@ SCENARIO("A federated request is refused unless this server's own state shows th } } + WHEN("the room's server ACL denies remote.example.org, though carol is still joined") + { + seed_server_acl(fixture.runtime(), fixture.room_id, remote_server); + auto const denied = federated(fixture.runtime(), remote_server, federation_body(fixture.room_id, carol)); + auto const unknown_origin = + federated(fixture.runtime(), "other.example.net", federation_body(fixture.room_id, carol)); + + THEN("it is the same 403 M_FORBIDDEN, and nothing is signed or called") + { + CHECK(denied.status == 403U); + CHECK(denied.errcode == "M_FORBIDDEN"); + CHECK(denied.reason == unknown_origin.reason); + CHECK(denied.value.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + } + } + WHEN("carol leaves") { auto& store = fixture.runtime().homeserver.database.persistent_store; @@ -870,6 +900,26 @@ SCENARIO("A token for another server's SFU is relayed to that server, and only i } } + GIVEN("alice's room, which carol of remote.example.org has joined, and a server ACL denying remote.example.org") + { + auto fixture = LiveKitFixture{}; + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + seed_server_acl(fixture.runtime(), fixture.room_id, remote_server); + + WHEN("alice asks for a token for remote.example.org's SFU") + { + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + relay_body(fixture.room_id)); + + THEN("it is 403 M_FORBIDDEN without a request to that server, as for a server not in the room") + { + CHECK(answer.status == 403U); + CHECK(errcode_of(answer) == "M_FORBIDDEN"); + CHECK(fixture.mock().requests.empty()); + } + } + } + GIVEN("remote.example.org answering get_token with a refusal, an error or a malformed jwt") { struct Case final From 35b27f452067113f139a5557a59240fbbbfda421 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 15:10:28 +0000 Subject: [PATCH 11/19] Link ADR-0830 to ADR-0079 by its real file name The documentation site build (mkdocs --strict) refused the link to a 0079 file name that does not exist. Co-Authored-By: Claude Opus 5.5 --- ...it-goes-to-the-configured-address-with-a-token-of-its-own.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md index 14c074991..47f13c149 100644 --- a/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md +++ b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md @@ -71,4 +71,4 @@ owner's decision first. * Refined by [ADR-0832](0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md) * Refines [ADR-0829](0829-the-built-in-livekit-token-service-issues-tokens-only-to-users-this-server-finds-joined.md) -* [ADR-0079](0079-cap-client-triggered-outbound-proxying.md) +* [ADR-0079](0079-client-triggered-outbound-proxying-runs-under-a-bounded-in-flight-budget.md) From e74cc04d18e6d9b2501ca3892dd073537d994132 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 17:22:50 +0000 Subject: [PATCH 12/19] Pass the unsafe source gate: reword a comment and mark the reviewed shared_ptrs scripts/reject-unsafe.sh read "free (" in a comment as a call to free(), and the LiveKit test helpers' shared_ptr lines had no review marker. Each one shares a call log or mock with the std::function hook installed on the runtime, which must be copyable. Co-Authored-By: Claude Opus 5.5 --- src/homeserver/LiveKitDelegations.cpp | 4 ++-- tests/conformance/test_livekit_token_conformance.cpp | 3 ++- tests/support/LiveKitTestSupport.hpp | 6 ++++-- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/src/homeserver/LiveKitDelegations.cpp b/src/homeserver/LiveKitDelegations.cpp index 37b34b5fa..15aae3f8b 100644 --- a/src/homeserver/LiveKitDelegations.cpp +++ b/src/homeserver/LiveKitDelegations.cpp @@ -211,8 +211,8 @@ namespace { auto& runtime = rt.homeserver; auto const& store = runtime.database.persistent_store; - // The whole delegation, not only its delay ID: one stored again while the lock was free (another slot or - // member, or the same anew) is not the participant this answer is about. + // The whole delegation, not only its delay ID: one stored again while the lock was released, for another slot + // or member or the same one anew, is not the participant this answer is about. auto const* row = store.livekit_delegations.find(check.delay_id); if (row == nullptr || row->user_id != check.user_id || row->room_id != check.room_id || row->slot_id != check.slot_id || row->member_id != check.member_id || row->created_ms != check.created_ms) diff --git a/tests/conformance/test_livekit_token_conformance.cpp b/tests/conformance/test_livekit_token_conformance.cpp index f7e037a5f..674fc1fab 100644 --- a/tests/conformance/test_livekit_token_conformance.cpp +++ b/tests/conformance/test_livekit_token_conformance.cpp @@ -192,7 +192,8 @@ class Msc4195Server final SecretDirectory m_secret{}; hs::ClientServerStartResult m_started; - std::shared_ptr> m_calls; + using CallLog = std::vector; + std::shared_ptr m_calls; // SHARED_PTR: reviewed — the call log is shared with the installed hook }; } // namespace diff --git a/tests/support/LiveKitTestSupport.hpp b/tests/support/LiveKitTestSupport.hpp index 60beee557..61cdc2003 100644 --- a/tests/support/LiveKitTestSupport.hpp +++ b/tests/support/LiveKitTestSupport.hpp @@ -169,7 +169,9 @@ struct MockLiveKit final bool reachable{true}; }; -inline auto install_mock(homeserver::ClientServerRuntime& runtime, std::shared_ptr const& mock) -> void +inline auto install_mock(homeserver::ClientServerRuntime& runtime, + std::shared_ptr const& mock) // SHARED_PTR: reviewed — mock shared with its hook + -> void { runtime.homeserver.test_livekit_perform = [mock](merovingian::http::OutboundRequest const& outbound) { mock->requests.push_back(outbound); @@ -252,7 +254,7 @@ class LiveKitFixture final private: SecretFile m_secret; homeserver::ClientServerStartResult m_started; - std::shared_ptr m_mock; + std::shared_ptr m_mock; // SHARED_PTR: reviewed — fixture shares the mock with the installed hook }; } // namespace merovingian::tests::livekit From f589be87e68f624491b1406655255182ae8862d7 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 19:37:45 +0000 Subject: [PATCH 13/19] Guard the LiveKit secret from the worker, schedule checks fairly, index webhooks, bound DNS Four findings from review of PR 598: - The federation worker's Landlock secret-path guard now lists server.rtc.livekit.api_secret_file, so a worker-readable placement of the LiveKit API secret (beneath /etc/ssl/certs, say) refuses to start the worker, as for every other secret (ADR-0062). - run_livekit_delegations asks the due delegations most overdue first, stamps each GetParticipant token when its call is made, and schedules the next check from when the calls ended, so a slow LiveKit cannot make the job ask the same 16 again while others wait (ADR-0832). - The webhook finds matching delegations through an index by LiveKit room name and identity (livekit_delegation_participants, kept in step with the progress map), and checks each match against its progress, instead of scanning every delegation (ADR-0833). - perform_livekit_request charges the host lookup and the exchange to one OutboundDeadline: the exchange gets what the lookup left, and none is started once it is spent (ADR-0830). Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 + ...files-secrets-arrive-over-inherited-fds.md | 5 +- ...figured-address-with-a-token-of-its-own.md | 3 + ...e-participant-and-sent-once-it-does-not.md | 6 + ...ener-and-trusted-only-to-prompt-a-check.md | 3 + docs/threat-model.md | 3 +- .../homeserver/HomeserverRuntime.hpp | 4 + .../homeserver/LiveKitRoomService.hpp | 4 +- .../platform/LandlockHardening.hpp | 4 +- src/homeserver/LiveKitDelegations.cpp | 129 ++++++++++--- src/homeserver/LiveKitRoomService.cpp | 17 +- src/platform/LandlockHardening.cpp | 2 +- .../test_livekit_delegation_flow.cpp | 177 ++++++++++++++++++ tests/meson.build | 1 + tests/unit/test_livekit_room_service.cpp | 122 ++++++++++++ tests/unit/test_worker_landlock.cpp | 43 +++++ 16 files changed, 496 insertions(+), 30 deletions(-) create mode 100644 tests/unit/test_livekit_room_service.cpp diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ad43f720..8438b6c05 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,9 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) participants; the API secret is read per token and never logged (ADR-0828). * LiveKit's webhook is believed only when signed with the API secret for its exact body and recent, and even then only brings a check forward: it never sends or restarts an event (ADR-0833). +* The federation worker refuses to start if a Landlock rule would let it read the LiveKit API secret file (ADR-0062). +* A LiveKit call's host lookup counts against the call's deadline, so a slow resolver cannot hold a request thread + past it (ADR-0830). ## Bug fixes diff --git a/docs/adr/0062-federation-worker-holds-no-secret-files-secrets-arrive-over-inherited-fds.md b/docs/adr/0062-federation-worker-holds-no-secret-files-secrets-arrive-over-inherited-fds.md index 5b181b41a..db69a2f23 100644 --- a/docs/adr/0062-federation-worker-holds-no-secret-files-secrets-arrive-over-inherited-fds.md +++ b/docs/adr/0062-federation-worker-holds-no-secret-files-secrets-arrive-over-inherited-fds.md @@ -621,8 +621,9 @@ in the rule set" is not enough: the required read-write grant on the SQLite database's *directory* would silently expose a master key an operator placed beside the database. At startup, before applying the ruleset, the worker checks every rule against `platform::worker_landlock_secret_paths()` (the -master key, both TLS private keys, both database URI files, and the -registration token file) with `platform::find_landlock_rule_covering_secret`, +master key, both TLS private keys, both database URI files, the +registration token file, the SMTP password file, the TURN shared secret, the LiveKit API secret +file (ADR-0830) and the appservice registration files) with `platform::find_landlock_rule_covering_secret`, and refuses to start if any rule equals or is an ancestor of one. Paths are compared by component after `std::filesystem::weakly_canonical`, matching how the kernel resolves the rule's path, so a symlink cannot hide an overlap diff --git a/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md index 47f13c149..29b4a728c 100644 --- a/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md +++ b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md @@ -20,6 +20,9 @@ call is added here. explicit port and appends `/twirp/livekit.RoomService/`. * `perform_livekit_request` resolves the host with `discovery.upstream().lookup_addresses`, the operator-trusted lookup the application service client uses (ADR-0515). The connection is pinned to the addresses found. + * The lookup and the exchange draw from one `OutboundDeadline` of the call's `timeout_seconds`: the exchange gets + only what the lookup left, and none is started once it is spent (a timeout). A slow resolver therefore cannot hold + the request thread, the ADR-0079 slot or the job past the call's bound. * The SSRF-filtered lookup is not used: the operator chose the address, and LiveKit commonly runs on the same host or LAN. * TLS verification is always on and redirects are refused (`http::OutboundClient`). diff --git a/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md b/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md index 9e1c6e2fe..4d94aeb2d 100644 --- a/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md +++ b/docs/adr/0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md @@ -68,6 +68,12 @@ user, room, slot, member and creation time, with the same LiveKit room name and while the lock was free (another member for the same delay ID, say) is a different participant, and the answer is dropped rather than recorded as seeing it. +A run asks the due delegations most overdue first, so with more than 16 due none waits behind the others for ever. +Each call's token is stamped with the clock when that call is made, not when the run began, so a run made slow by +LiveKit never sends a token that is about to expire. A checked delegation's next check is 30 seconds after the run's +calls ended, not after it began: a run that took as long as the interval would otherwise find the same 16 due again, +and ask them again, while the rest waited. + After a call: * **Connected** (an answer for the participant in a state other than `DISCONNECTED`): recorded. If less than half the diff --git a/docs/adr/0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md b/docs/adr/0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md index bc9ae05b7..975897296 100644 --- a/docs/adr/0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md +++ b/docs/adr/0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md @@ -54,6 +54,9 @@ reason: replay within the token's own 5 minutes is caught by the `id`; one after is caught by the token's `exp`. * The event must name, by `room.name` and `participant.identity`, a delegation this server recorded, created no later than `createdAt`, else ignored. Nothing in the body is used otherwise: no Matrix ID is derived from it. + * The match is found through an index by room name and identity (`livekit_delegation_participants`, kept in step + with the delegations' progress under `runtime.mutex`), so each signed event costs its matches, never a scan of + every user's delegations. Each match is checked again against the progress it names. * A match marks that delegation to be checked at the next run of `livekit-delegations` and wakes the job. That is all. Every authenticated event is answered 200 `{}`. diff --git a/docs/threat-model.md b/docs/threat-model.md index 0cc236762..116f59019 100644 --- a/docs/threat-model.md +++ b/docs/threat-model.md @@ -3380,7 +3380,8 @@ unauthenticated webhook route for LiveKit. Threats and mitigations: never in a response. Signing is in `src/crypto/` through typed functions only (ADR-0828): the participant grant cannot express `roomCreate`, `roomAdmin` or `hidden`; one other signer grants `roomCreate` alone, and the last `roomAdmin` over one named room alone, for `GetParticipant`. The federation -worker never reads the configuration or the secret. +worker never reads the configuration or the secret, and its Landlock secret-path guard (`worker_landlock_secret_paths`) +refuses to start the worker if a rule, such as the SQLite database directory grant, would cover the secret file. (b) A token for someone who should not have one. A token goes only to a caller this server authenticated (access token, account gate) and finds joined by its own current room state, never by the request: a user not joined, and a room that diff --git a/include/merovingian/homeserver/HomeserverRuntime.hpp b/include/merovingian/homeserver/HomeserverRuntime.hpp index 65a358db6..a212bf414 100644 --- a/include/merovingian/homeserver/HomeserverRuntime.hpp +++ b/include/merovingian/homeserver/HomeserverRuntime.hpp @@ -301,6 +301,10 @@ struct HomeserverRuntime final // What the "livekit-delegations" job knows of each stored delegation, by delay ID (ADR-0832). In memory only: after // a restart each starts again as never seen and due now. Guarded by `mutex`. std::map> livekit_delegation_progress{}; + // The delay IDs in `livekit_delegation_progress` by LiveKit participant (room name, NUL, identity), so a webhook + // finds its delegations without scanning everyone's. Kept in step with that map by LiveKitDelegations.cpp, its only + // writer. Guarded by `mutex`. + std::multimap> livekit_delegation_participants{}; // The `id`s of the last `livekit_webhook_seen_ids` authenticated LiveKit webhook events, oldest first, so a replay // inside a token's lifetime prompts nothing (ADR-0833). In memory only. Guarded by `mutex`. std::deque livekit_webhook_seen_ids{}; diff --git a/include/merovingian/homeserver/LiveKitRoomService.hpp b/include/merovingian/homeserver/LiveKitRoomService.hpp index 5f07df2fe..0c5fb135a 100644 --- a/include/merovingian/homeserver/LiveKitRoomService.hpp +++ b/include/merovingian/homeserver/LiveKitRoomService.hpp @@ -57,7 +57,9 @@ inline constexpr auto livekit_room_departure_timeout_seconds = std::uint32_t{20U // Stands in for LiveKit in tests: it is handed the finished request in place of resolving and connecting. using LiveKitTestPerform = std::function; -// Sends `request` with `timeout_seconds` for the whole exchange. The host is resolved with the operator-trusted lookup +// Sends `request` with `timeout_seconds` for the lookup and the exchange together (one `OutboundDeadline`: the +// exchange gets what the lookup leaves, and none is started once it is spent). The host is resolved with the +// operator-trusted lookup // (`discovery.upstream()`, no private-range filter: the operator chose the address, and LiveKit often runs beside // this server) and the connection is pinned to it. Never call with `runtime.mutex` held. [[nodiscard]] auto perform_livekit_request(http::OutboundRequest request, http::OutboundClient& client, diff --git a/include/merovingian/platform/LandlockHardening.hpp b/include/merovingian/platform/LandlockHardening.hpp index 6c8119954..283cfdada 100644 --- a/include/merovingian/platform/LandlockHardening.hpp +++ b/include/merovingian/platform/LandlockHardening.hpp @@ -65,7 +65,9 @@ inline constexpr int k_landlock_max_known_abi = 6; // Every non-empty secret file path in `config` the worker must never be able // to open: the master key, both TLS private keys, main's database URI file, // the worker's own database URI file (delivered over an fd, never opened), -// the registration token file, and the SMTP password file (ADR-0220). +// the registration token file, the SMTP password file (ADR-0220), the TURN +// shared secret file, the LiveKit API secret file (ADR-0830: only main signs +// LiveKit tokens) and every appservice registration file. [[nodiscard]] auto worker_landlock_secret_paths(config::Config const& config) -> std::vector; // Returns the first rule whose path is, or is an ancestor directory of, one diff --git a/src/homeserver/LiveKitDelegations.cpp b/src/homeserver/LiveKitDelegations.cpp index 15aae3f8b..848e1f464 100644 --- a/src/homeserver/LiveKitDelegations.cpp +++ b/src/homeserver/LiveKitDelegations.cpp @@ -41,6 +41,7 @@ #include #include #include +#include #include #include #include @@ -83,6 +84,37 @@ namespace severity); } + // The key of `livekit_delegation_participants`. MSC4195 names are base64, so they hold no NUL and two keys are + // equal only when both names are. + [[nodiscard]] auto participant_key(std::string_view const room_name, std::string_view const identity) -> std::string + { + auto key = std::string{room_name}; + key += '\0'; + key += identity; + return key; + } + + // Removes a delegation's progress and its participant index entry together; the only way either is removed. + auto forget_progress(HomeserverRuntime& runtime, std::string_view const delay_id) -> void + { + auto const found = runtime.livekit_delegation_progress.find(delay_id); + if (found == runtime.livekit_delegation_progress.end()) + { + return; + } + auto& participants = runtime.livekit_delegation_participants; + auto [first, last] = participants.equal_range(participant_key(found->second.room_name, found->second.identity)); + for (auto entry = first; entry != last; ++entry) + { + if (entry->second == delay_id) + { + participants.erase(entry); + break; + } + } + runtime.livekit_delegation_progress.erase(found); + } + // The progress entry of a stored delegation, created (due now, never seen) with its names when missing. nullopt // when the names cannot be derived, which a validated row never gives. [[nodiscard]] auto progress_of(HomeserverRuntime& runtime, database::PersistentLiveKitDelegation const& row) @@ -102,6 +134,8 @@ namespace auto progress = LiveKitDelegationProgress{}; progress.room_name = std::move(*room_name); progress.identity = std::move(*identity); + runtime.livekit_delegation_participants.emplace(participant_key(progress.room_name, progress.identity), + row.delay_id); return &runtime.livekit_delegation_progress.emplace(row.delay_id, std::move(progress)).first->second; } @@ -121,7 +155,7 @@ namespace { return false; } - runtime.livekit_delegation_progress.erase(delay_id); + forget_progress(runtime, delay_id); return true; } @@ -352,9 +386,9 @@ auto delegate_livekit_delayed_leave(ClientServerRuntime& rt, std::string_view co } for (auto const& old : replaced) { - runtime.livekit_delegation_progress.erase(old); + forget_progress(runtime, old); } - runtime.livekit_delegation_progress.erase(delay_id); + forget_progress(runtime, delay_id); if (auto const* stored = store.livekit_delegations.find(delay_id); stored != nullptr) { std::ignore = progress_of(runtime, *stored); @@ -378,8 +412,12 @@ auto run_livekit_delegations(ClientServerRuntime& rt, std::uint64_t const now_ms // indexes), so one run drops at most `livekit_delegation_drops_per_run`; the rest go on the next, soon after. auto const rows = runtime.database.persistent_store.livekit_delegations.rows(); auto drops = std::size_t{0U}; - for (auto const& row : rows) + // Due checks as (next check time, row): the most overdue are asked first, so a run never starves the rows + // further down the table. + auto due = std::vector>{}; + for (auto position = std::size_t{0U}; position < rows.size(); ++position) { + auto const& row = rows[position]; if (auto const reason = drop_reason(runtime, row); !reason.empty()) { if (drops == livekit_delegation_drops_per_run) @@ -400,39 +438,70 @@ auto run_livekit_delegations(ClientServerRuntime& rt, std::uint64_t const now_ms std::ignore = drop(runtime, row.delay_id); continue; } - if (progress->next_check_ms <= now_ms && checks.size() < livekit_delegation_checks_per_run) + if (progress->next_check_ms <= now_ms) { - checks.push_back(Check{row.delay_id, row.user_id, row.room_id, row.slot_id, row.member_id, - row.created_ms, progress->room_name, progress->identity, Observation::unknown}); + due.emplace_back(progress->next_check_ms, position); } else { - next_ms = std::min(next_ms, std::max(progress->next_check_ms, now_ms)); + next_ms = std::min(next_ms, progress->next_check_ms); + } + } + auto const asked = std::min(due.size(), livekit_delegation_checks_per_run); + std::ranges::partial_sort(due, due.begin() + static_cast(asked)); + if (due.size() > asked) + { + next_ms = now_ms; // more are due than one run asks + } + for (auto const& [next_check_ms, position] : std::span{due}.first(asked)) + { + auto const& row = rows[position]; + auto const* progress = progress_of(runtime, row); + if (progress != nullptr) + { + checks.push_back(Check{row.delay_id, row.user_id, row.room_id, row.slot_id, row.member_id, + row.created_ms, progress->room_name, progress->identity, Observation::unknown}); } } // Progress for a row no longer stored (deleted by deactivation, for one) goes too. - std::erase_if(runtime.livekit_delegation_progress, [&](auto const& entry) { - return runtime.database.persistent_store.livekit_delegations.find(entry.first) == nullptr; - }); + auto stale = std::vector{}; + for (auto const& [delay_id, progress] : runtime.livekit_delegation_progress) + { + if (runtime.database.persistent_store.livekit_delegations.find(delay_id) == nullptr) + { + stale.push_back(delay_id); + } + } + for (auto const& delay_id : stale) + { + forget_progress(runtime, delay_id); + } } if (checks.empty()) { return wait_until(now_ms, next_ms); } - // The calls, with the lock free. One read of the secret serves this run's tokens. + // A run can take a while (each call has its own timeout), so every token and every schedule is stamped with the + // time it is made, not the time the run began. + // The same clock as the job's `now_ms` (`delayed_event_now_ms`, read without the lock as main.cpp reads it). + auto const clock_ms = [&] { + return std::max(now_ms, delayed_event_now_ms(runtime)); + }; + + // The calls, with the lock released. One read of the secret serves this run's tokens. if (runtime.outbound_client != nullptr && runtime.cached_discovery != nullptr) { auto const secret = platform::read_secure_secret_line(service.api_secret_file, max_secret_file_bytes); - auto const now_seconds = static_cast(now_ms / 1000U); for (auto& check : checks) { if (stop.stop_requested() || !secret.has_value()) { break; } - auto request = livekit_get_participant_request(service.api_url, service.api_key, secret->bytes(), - check.room_name, check.identity, now_seconds); + auto request = + livekit_get_participant_request(service.api_url, service.api_key, secret->bytes(), check.room_name, + check.identity, static_cast(clock_ms() / 1000U)); if (!request.has_value()) { continue; @@ -449,18 +518,25 @@ auto run_livekit_delegations(ClientServerRuntime& rt, std::uint64_t const now_ms } auto const guard = RuntimeLock{runtime.mutex}; + // Each answer is applied, and its next check scheduled, from when the calls ended: scheduled from the start of a + // long run, the rows just asked would be due again at once and be asked again before the rest. + auto const done_ms = clock_ms(); for (auto const& check : checks) { - apply(rt, check, now_ms); + apply(rt, check, done_ms); + } + if (next_ms <= now_ms) + { + return shortest_wait; // more were due than one run asks, or drops are left } - // Checks still due (more than one run's worth) run again soon. + // Checks that fell due while the calls were made run again soon. auto more_due = false; for (auto const& [delay_id, progress] : runtime.livekit_delegation_progress) { - more_due = more_due || progress.next_check_ms <= now_ms; - next_ms = std::min(next_ms, std::max(progress.next_check_ms, now_ms)); + more_due = more_due || progress.next_check_ms <= done_ms; + next_ms = std::min(next_ms, std::max(progress.next_check_ms, done_ms)); } - return more_due ? shortest_wait : wait_until(now_ms, next_ms); + return more_due ? shortest_wait : wait_until(done_ms, next_ms); } namespace @@ -618,13 +694,22 @@ auto receive_livekit_webhook(ClientServerRuntime& rt, LocalHttpRequest const& re { return ok_empty(); } + // Only this participant's delegations, through the index: the cost is the matches, not every user's delegations. auto const& delegations = runtime.database.persistent_store.livekit_delegations; - for (auto& [delay_id, progress] : runtime.livekit_delegation_progress) + auto [first, last] = runtime.livekit_delegation_participants.equal_range(participant_key(*room_name, *identity)); + for (auto entry = first; entry != last; ++entry) { - if (progress.room_name != *room_name || progress.identity != *identity) + auto const& delay_id = entry->second; + auto const found = runtime.livekit_delegation_progress.find(delay_id); + if (found == runtime.livekit_delegation_progress.end()) { continue; } + auto& progress = found->second; + if (progress.room_name != *room_name || progress.identity != *identity) + { + continue; // the index is kept in step with progress; this only refuses to trust it alone + } auto const* row = delegations.find(delay_id); if (row == nullptr || static_cast(row->created_ms / 1000U) > *created_at) { diff --git a/src/homeserver/LiveKitRoomService.cpp b/src/homeserver/LiveKitRoomService.cpp index af818f5a6..0b7877067 100644 --- a/src/homeserver/LiveKitRoomService.cpp +++ b/src/homeserver/LiveKitRoomService.cpp @@ -5,6 +5,7 @@ #include "merovingian/crypto/LiveKitToken.hpp" #include "merovingian/federation/CachedServerDiscovery.hpp" #include "merovingian/federation/ServerDiscoveryNetwork.hpp" +#include "merovingian/homeserver/OutboundDeadline.hpp" #include "merovingian/http/OutboundClient.hpp" #include "merovingian/http/OutboundError.hpp" #include "merovingian/http/OutboundHeader.hpp" @@ -121,8 +122,14 @@ auto perform_livekit_request(http::OutboundRequest request, http::OutboundClient { return failed(http::OutboundError::timeout, "deadline exceeded"); } - request.total_timeout_seconds = timeout_seconds; - request.connect_timeout_seconds = std::min(timeout_seconds, std::uint32_t{10U}); + // One deadline for the lookup and the exchange: a slow lookup shortens the exchange rather than adding to it, so + // the call never holds its thread or its outbound slot past `timeout_seconds`. + auto const deadline = OutboundDeadline{timeout_seconds}; + auto const limit_to = [&request](std::uint32_t const seconds) { + request.total_timeout_seconds = seconds; + request.connect_timeout_seconds = std::min(seconds, std::uint32_t{10U}); + }; + limit_to(timeout_seconds); if (test_perform) { return test_perform(request); @@ -137,6 +144,12 @@ auto perform_livekit_request(http::OutboundRequest request, http::OutboundClient { return failed(http::OutboundError::unresolved_host, "failed to resolve the LiveKit API host"); } + auto const remaining = deadline.remaining_seconds(); + if (remaining == 0U) + { + return failed(http::OutboundError::timeout, "deadline exceeded while resolving the LiveKit API host"); + } + limit_to(remaining); request.pinned_addresses = resolved.addresses; return client.perform(request); } diff --git a/src/platform/LandlockHardening.cpp b/src/platform/LandlockHardening.cpp index bda106515..69b62ec5c 100644 --- a/src/platform/LandlockHardening.cpp +++ b/src/platform/LandlockHardening.cpp @@ -188,7 +188,7 @@ auto worker_landlock_secret_paths(config::Config const& config) -> std::vectorempty()) { diff --git a/tests/integration/test_livekit_delegation_flow.cpp b/tests/integration/test_livekit_delegation_flow.cpp index 1ebb86660..25d85d670 100644 --- a/tests/integration/test_livekit_delegation_flow.cpp +++ b/tests/integration/test_livekit_delegation_flow.cpp @@ -27,6 +27,7 @@ #include #include +#include #include #include #include @@ -808,3 +809,179 @@ SCENARIO("The webhook route is answered before the access-token gate, and only w } } } + +namespace +{ + +// The identity GetParticipant asked about in `call`. +[[nodiscard]] auto asked_identity(merovingian::http::OutboundRequest const& call) -> std::string +{ + auto const body = parse_object(call.body); + auto const* identity = string_member(body, "identity"); + REQUIRE(identity != nullptr); + return *identity; +} + +// The `exp` of the GetParticipant token in `call`. +[[nodiscard]] auto token_expiry(merovingian::http::OutboundRequest const& call) -> std::int64_t +{ + auto const authorization = header_value(call, "Authorization"); + REQUIRE(authorization.has_value()); + REQUIRE(authorization->starts_with("Bearer ")); + auto const payload = verified_payload(std::string_view{*authorization}.substr(7U)); + auto const* expiry = int_member(payload, "exp"); + REQUIRE(expiry != nullptr); + return *expiry; +} + +// Delegates one more of alice's one-hour leaves, for member `member`, and returns its delay ID. +[[nodiscard]] auto delegate_another(LiveKitFixture& fixture, std::string const& member) -> std::string +{ + auto const delay_id = schedule_leave(fixture, fixture.alice_token, hour_ms, "call-" + member); + auto const answer = delegate(fixture, fixture.alice_token, + delegation_body(fixture.room_id, delay_id, sfu_url, "m.call#room", member)); + REQUIRE(answer.status == 200U); + return delay_id; +} + +// alice's MSC4195 participant identity for `member`. +[[nodiscard]] auto identity_of(std::string_view const member) -> std::string +{ + auto identity = hs::livekit_participant_identity("@alice:example.org", member); + REQUIRE(identity.has_value()); + return *identity; +} + +} // namespace + +SCENARIO("A slow LiveKit does not make the job ask the same delegations again while another waits", + "[homeserver][livekit][rtc][delegation]") +{ + GIVEN("17 delegations of alice, LiveKit answering that each is connected, and each answer taking 2 seconds") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = R"({"state":"ACTIVE"})"; + auto identities = std::vector{identity_of("DEVICEID_member")}; + for (auto index = 0; index < 16; ++index) + { + auto const member = "member-" + std::to_string(index); + std::ignore = delegate_another(fixture, member); + identities.push_back(identity_of(member)); + } + REQUIRE(delegations(fixture).size() == 17U); + auto const answer = fixture.runtime().homeserver.test_livekit_perform; + fixture.runtime().homeserver.test_livekit_perform = + [&fixture, answer](merovingian::http::OutboundRequest const& outbound) { + auto& clock = fixture.runtime().homeserver.test_delayed_event_clock_ms; + clock = clock.value_or(0U) + 2'000U; + return answer(outbound); + }; + + WHEN("the job runs at t0, and again just after the 30-second interval measured from t0") + { + auto const first_wait = run_job(fixture, t0_ms); + auto const first_calls = fixture.mock().requests; + std::ignore = run_job(fixture, t0_ms + 33'000U); + auto const& calls = fixture.mock().requests; + + THEN("the first run asks 16, each with a token stamped when it was sent, and asks to run again soon") + { + REQUIRE(first_calls.size() == hs::livekit_delegation_checks_per_run); + CHECK(first_wait < hs::livekit_delegation_check_interval); + CHECK(token_expiry(first_calls.back()) - token_expiry(first_calls.front()) == 30); + } + + THEN("the second asks only the one left waiting: the 16 are next due 30 seconds after their answers") + { + REQUIRE(calls.size() == hs::livekit_delegation_checks_per_run + 1U); + auto asked_first = std::vector{}; + for (auto const& call : first_calls) + { + asked_first.push_back(asked_identity(call)); + } + auto const last = asked_identity(calls.back()); + CHECK(std::ranges::find(asked_first, last) == asked_first.end()); + CHECK(std::ranges::find(identities, last) != identities.end()); + } + } + } +} + +SCENARIO("A webhook prompts only the delegation of the participant it names, as delegations come and go", + "[homeserver][livekit][rtc][delegation][webhook]") +{ + GIVEN("two delegations of alice, for members A and B, both checked at t0 and seen connected") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = R"({"state":"ACTIVE"})"; + auto const delay_b = delegate_another(fixture, "member-B"); + std::ignore = run_job(fixture, t0_ms); + REQUIRE(get_participant_calls(fixture) == 2U); + auto const now_s = static_cast((t0_ms + 5'000U) / 1000U); + auto const room_name = *hs::livekit_room_name(fixture.room_id, "m.call#room"); + auto const left = [&](std::string_view const member, std::string_view const id) { + return signed_webhook(webhook_event("participant_left", room_name, identity_of(member), id, now_s), now_s); + }; + + WHEN("LiveKit says B left") + { + auto const answer = post_webhook(fixture, left("member-B", "EV_B"), now_s); + std::ignore = run_job(fixture, t0_ms + 6'000U); + + THEN("the next run asks about B alone") + { + CHECK(answer.status == 200U); + REQUIRE(get_participant_calls(fixture) == 3U); + CHECK(asked_identity(fixture.mock().requests.back()) == identity_of("member-B")); + } + } + + WHEN("A's delay ID is delegated again for member C and C is checked, then LiveKit says A left, then C") + { + REQUIRE(delegate(fixture, fixture.alice_token, + delegation_body(fixture.room_id, delegated.delay_id, sfu_url, "m.call#room", "member-C")) + .status == 200U); + std::ignore = run_job(fixture, t0_ms + 6'000U); + auto const after_c_checked = get_participant_calls(fixture); + auto const last_checked = asked_identity(fixture.mock().requests.back()); + auto const for_a = post_webhook(fixture, left("DEVICEID_member", "EV_A"), now_s); + std::ignore = run_job(fixture, t0_ms + 7'000U); + auto const after_a = get_participant_calls(fixture); + auto const for_c = post_webhook(fixture, left("member-C", "EV_C"), now_s); + std::ignore = run_job(fixture, t0_ms + 8'000U); + + THEN("the new delegation is checked as C; A's webhook prompts nothing; C's prompts C's check alone") + { + CHECK(after_c_checked == 3U); + CHECK(last_checked == identity_of("member-C")); + CHECK(for_a.status == 200U); + CHECK(after_a == after_c_checked); + CHECK(for_c.status == 200U); + REQUIRE(get_participant_calls(fixture) == after_a + 1U); + CHECK(asked_identity(fixture.mock().requests.back()) == identity_of("member-C")); + } + } + + WHEN("B's leave is cancelled, its delegation is dropped, and LiveKit then says B left") + { + REQUIRE(request(fixture.runtime(), "POST", "/_matrix/client/v1/delayed_events/" + delay_b + "/cancel", + fixture.alice_token, "{}") + .status == 200U); + std::ignore = run_job(fixture, t0_ms + 6'000U); + REQUIRE(delegations(fixture).find(delay_b) == nullptr); + auto const calls_before = get_participant_calls(fixture); + auto const answer = post_webhook(fixture, left("member-B", "EV_B2"), now_s); + std::ignore = run_job(fixture, t0_ms + 7'000U); + + THEN("the webhook is accepted and prompts no check") + { + CHECK(answer.status == 200U); + CHECK(get_participant_calls(fixture) == calls_before); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index 36ac35d9d..d7fbacbc9 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -419,6 +419,7 @@ shell = find_program('sh') 'unit/test_file_metadata.cpp', 'unit/test_secure_secret_loading.cpp', 'unit/test_livekit_names.cpp', + 'unit/test_livekit_room_service.cpp', 'unit/test_turn_shared_secret.cpp', 'unit/test_elf_probe.cpp', 'unit/test_email.cpp', diff --git a/tests/unit/test_livekit_room_service.cpp b/tests/unit/test_livekit_room_service.cpp new file mode 100644 index 000000000..5c79600e2 --- /dev/null +++ b/tests/unit/test_livekit_room_service.cpp @@ -0,0 +1,122 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// `perform_livekit_request` (ADR-0830): the host lookup and the exchange draw from one deadline, so a slow lookup +// cannot add a whole second budget to a LiveKit call. + +#include "merovingian/federation/CachedServerDiscovery.hpp" +#include "merovingian/federation/ServerDiscoveryNetwork.hpp" +#include "merovingian/homeserver/LiveKitRoomService.hpp" +#include "merovingian/http/OutboundClient.hpp" +#include "merovingian/http/OutboundError.hpp" +#include "merovingian/http/OutboundRequest.hpp" + +#include + +#include +#include +#include +#include +#include +#include + +namespace +{ + +// Answers every address lookup with a loopback address, after `delay`. +class SlowDiscoveryNetwork final : public merovingian::federation::ServerDiscoveryNetwork +{ +public: + explicit SlowDiscoveryNetwork(std::chrono::milliseconds const delay) + : delay_{delay} + { + } + + [[nodiscard]] auto fetch_well_known(std::string_view, std::uint32_t) + -> merovingian::federation::WellKnownServerResult override + { + return {}; + } + + [[nodiscard]] auto lookup_srv(std::string_view) -> std::vector override + { + return {}; + } + + [[nodiscard]] auto lookup_addresses(std::string_view, std::uint16_t) + -> merovingian::federation::ResolvedAddressSet override + { + ++lookups_; + std::this_thread::sleep_for(delay_); + return {true, {"127.0.0.1"}, {}}; + } + + [[nodiscard]] auto lookups() const noexcept -> int + { + return lookups_; + } + +private: + std::chrono::milliseconds delay_; + int lookups_{0}; +}; + +[[nodiscard]] auto livekit_request() -> merovingian::http::OutboundRequest +{ + auto request = merovingian::http::OutboundRequest{}; + request.method = "POST"; + request.url = "http://livekit.test:7880/twirp/livekit.RoomService/CreateRoom"; + request.allow_cleartext_http = true; + return request; +} + +} // namespace + +SCENARIO("A LiveKit call's host lookup draws from the call's one deadline", "[homeserver][livekit][deadline]") +{ + auto client = merovingian::http::OutboundClient{}; + auto const no_test_perform = merovingian::homeserver::LiveKitTestPerform{}; + + GIVEN("a lookup that takes longer than the whole one-second budget") + { + auto network = SlowDiscoveryNetwork{std::chrono::milliseconds{1100}}; + auto discovery = merovingian::federation::CachedServerDiscovery{network, 60000U, []() -> std::uint64_t { + return 0U; + }}; + + WHEN("the request is performed") + { + auto const result = merovingian::homeserver::perform_livekit_request(livekit_request(), client, discovery, + 1U, no_test_perform); + + THEN("it ends as a timeout after the lookup, and no exchange is started") + { + CHECK(network.lookups() == 1); + CHECK_FALSE(result.ok); + CHECK(result.error == merovingian::http::OutboundError::timeout); + CHECK(result.error_detail == "deadline exceeded while resolving the LiveKit API host"); + } + } + } + + GIVEN("a budget already spent") + { + auto network = SlowDiscoveryNetwork{std::chrono::milliseconds{0}}; + auto discovery = merovingian::federation::CachedServerDiscovery{network, 60000U, []() -> std::uint64_t { + return 0U; + }}; + + WHEN("the request is performed with no seconds left") + { + auto const result = merovingian::homeserver::perform_livekit_request(livekit_request(), client, discovery, + 0U, no_test_perform); + + THEN("it is a timeout and the host is not even looked up") + { + CHECK(network.lookups() == 0); + CHECK_FALSE(result.ok); + CHECK(result.error == merovingian::http::OutboundError::timeout); + } + } + } +} diff --git a/tests/unit/test_worker_landlock.cpp b/tests/unit/test_worker_landlock.cpp index 5ca5a396e..e18efd94e 100644 --- a/tests/unit/test_worker_landlock.cpp +++ b/tests/unit/test_worker_landlock.cpp @@ -955,6 +955,49 @@ SCENARIO("A Landlock rule on a directory holding the SMTP password file is detec } } +SCENARIO("A LiveKit API secret file the worker could read is detected", + "[platform][security][worker_landlock][livekit]") +{ + GIVEN("the LiveKit API secret placed under /etc/ssl/certs, which the worker reads for CA trust") + { + auto config = merovingian::config::Config{}; + config.server().rtc.token_service.api_secret_file = "/etc/ssl/certs/livekit-secret"; + + WHEN("the worker's rules are checked against its secret paths") + { + auto const rules = merovingian::platform::build_worker_landlock_rules(config); + auto const secrets = merovingian::platform::worker_landlock_secret_paths(config); + auto const exposure = merovingian::platform::find_landlock_rule_covering_secret(rules, secrets); + + THEN("the file is a secret and the exposure names it, so the worker refuses to start") + { + REQUIRE(std::ranges::count(secrets, "/etc/ssl/certs/livekit-secret") == 1); + REQUIRE(exposure.has_value()); + REQUIRE(exposure->rule_path == "/etc/ssl/certs"); + REQUIRE(exposure->secret_path == "/etc/ssl/certs/livekit-secret"); + } + } + } + + GIVEN("the LiveKit API secret in the shipped layout") + { + auto config = merovingian::config::Config{}; + config.server().rtc.token_service.api_secret_file = "/etc/merovingian/livekit-api-secret"; + + WHEN("the worker's rules are checked against its secret paths") + { + auto const rules = merovingian::platform::build_worker_landlock_rules(config); + auto const secrets = merovingian::platform::worker_landlock_secret_paths(config); + + THEN("the file is listed and no rule covers it") + { + REQUIRE(std::ranges::count(secrets, "/etc/merovingian/livekit-api-secret") == 1); + REQUIRE_FALSE(merovingian::platform::find_landlock_rule_covering_secret(rules, secrets).has_value()); + } + } + } +} + SCENARIO("The shipped secret layout is not covered by any worker Landlock rule", "[platform][security][worker_landlock]") { From b48c7f4d37c704f14879339d74d97fd8d15a2d28 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 19:41:56 +0000 Subject: [PATCH 14/19] Cover the LiveKit token, request builder and perform refusal paths Co-Authored-By: Claude Opus 5.5 --- tests/unit/test_crypto_livekit_token.cpp | 88 ++++++++++++++++ tests/unit/test_livekit_room_service.cpp | 122 ++++++++++++++++++++++- 2 files changed, 208 insertions(+), 2 deletions(-) diff --git a/tests/unit/test_crypto_livekit_token.cpp b/tests/unit/test_crypto_livekit_token.cpp index 60051808f..9a8655dc3 100644 --- a/tests/unit/test_crypto_livekit_token.cpp +++ b/tests/unit/test_crypto_livekit_token.cpp @@ -4,9 +4,11 @@ // LiveKit's HS256 tokens (ADR-0828): the three typed signers and the verifier. The signed vectors were computed apart // from this code with Python's `hmac` and `hashlib`; the verifier's vector is RFC 7515 Appendix A.1. +#include "merovingian/crypto/Encoding.hpp" #include "merovingian/crypto/LiveKitToken.hpp" #include +#include #include #include @@ -341,3 +343,89 @@ SCENARIO("The verifier refuses a token that is altered, malformed or under anoth } } } + +namespace +{ + +// `signing_input` signed with HMAC-SHA256 under `secret` and appended as the third segment, so the token's MAC is +// genuine whatever its first two segments hold. +[[nodiscard]] auto with_genuine_mac(std::string const& signing_input, std::vector const& secret) + -> std::string +{ + REQUIRE(sodium_init() >= 0); + auto state = crypto_auth_hmacsha256_state{}; + auto mac = std::array{}; + crypto_auth_hmacsha256_init(&state, secret.data(), secret.size()); + crypto_auth_hmacsha256_update(&state, reinterpret_cast(signing_input.data()), + signing_input.size()); + crypto_auth_hmacsha256_final(&state, mac.data()); + auto const encoded = merovingian::crypto::base64_urlsafe_encode( + std::string_view{reinterpret_cast(mac.data()), mac.size()}); + REQUIRE(encoded.has_value()); + return signing_input + "." + *encoded; +} + +} // namespace + +SCENARIO("The verifier refuses a correctly signed token whose header or payload is not base64", + "[crypto][livekit][rtc][negative]") +{ + GIVEN("tokens whose MAC is genuine but whose first or second segment is not unpadded URL-safe base64") + { + auto const secret = counting_secret(); + // A valid segment, `{}`. + auto const good = std::string{"e30"}; + auto const bad_header = with_genuine_mac("!!!!." + good, secret); + auto const bad_payload = with_genuine_mac(good + ".!!!!", secret); + auto const control = with_genuine_mac(good + "." + good, secret); + + WHEN("they are verified under the secret that signed them") + { + auto const header_result = merovingian::crypto::verify_hs256_token(bad_header, secret); + auto const payload_result = merovingian::crypto::verify_hs256_token(bad_payload, secret); + auto const control_result = merovingian::crypto::verify_hs256_token(control, secret); + + THEN("the control verifies and neither malformed one returns any part of its content") + { + REQUIRE(control_result.has_value()); + CHECK(control_result->header_json == "{}"); + CHECK(control_result->payload_json == "{}"); + CHECK_FALSE(header_result.has_value()); + CHECK_FALSE(payload_result.has_value()); + } + } + } +} + +SCENARIO("The room-administration signer refuses a bad room name, key, time or secret", + "[crypto][livekit][rtc][negative]") +{ + GIVEN("a valid key, secret and room name") + { + auto const secret = counting_secret(); + auto const short_secret = std::vector(31U, 0x01U); + + WHEN("one input at a time is made invalid") + { + auto const sign = [&secret](std::string_view key, std::string_view room, std::int64_t not_before, + std::int64_t expires) { + return merovingian::crypto::sign_livekit_room_admin_token(key, secret, room, not_before, expires); + }; + + THEN("no token is signed, and the valid call does sign") + { + CHECK(sign(api_key, slot_room, 0, 60)); + CHECK_FALSE(sign(api_key, "", 0, 60)); + CHECK_FALSE(sign(api_key, std::string(42U, 'A'), 0, 60)); + CHECK_FALSE(sign(api_key, std::string(42U, 'A') + "\"", 0, 60)); + CHECK_FALSE(sign("bad key", slot_room, 0, 60)); + CHECK_FALSE(sign(api_key, slot_room, 60, 60)); + CHECK_FALSE(sign(api_key, slot_room, -1, 60)); + CHECK_FALSE( + merovingian::crypto::sign_livekit_room_admin_token(api_key, short_secret, slot_room, 0, 60)); + CHECK_FALSE(merovingian::crypto::sign_livekit_room_admin_token(api_key, std::span{}, + slot_room, 0, 60)); + } + } + } +} diff --git a/tests/unit/test_livekit_room_service.cpp b/tests/unit/test_livekit_room_service.cpp index 5c79600e2..747366c95 100644 --- a/tests/unit/test_livekit_room_service.cpp +++ b/tests/unit/test_livekit_room_service.cpp @@ -15,9 +15,11 @@ #include #include +#include #include #include #include +#include #include namespace @@ -27,8 +29,11 @@ namespace class SlowDiscoveryNetwork final : public merovingian::federation::ServerDiscoveryNetwork { public: - explicit SlowDiscoveryNetwork(std::chrono::milliseconds const delay) + explicit SlowDiscoveryNetwork(std::chrono::milliseconds const delay, bool const answer_ok = true, + std::vector addresses = {"127.0.0.1"}) : delay_{delay} + , answer_ok_{answer_ok} + , addresses_{std::move(addresses)} { } @@ -48,7 +53,7 @@ class SlowDiscoveryNetwork final : public merovingian::federation::ServerDiscove { ++lookups_; std::this_thread::sleep_for(delay_); - return {true, {"127.0.0.1"}, {}}; + return {answer_ok_, addresses_, {}}; } [[nodiscard]] auto lookups() const noexcept -> int @@ -58,6 +63,8 @@ class SlowDiscoveryNetwork final : public merovingian::federation::ServerDiscove private: std::chrono::milliseconds delay_; + bool answer_ok_; + std::vector addresses_; int lookups_{0}; }; @@ -120,3 +127,114 @@ SCENARIO("A LiveKit call's host lookup draws from the call's one deadline", "[ho } } } + +SCENARIO("The LiveKit request builders refuse an address, key, secret or name they cannot sign for", + "[homeserver][livekit][negative]") +{ + GIVEN("a valid https API URL, key, 32-byte secret and MSC4195 names") + { + auto const secret = std::vector(32U, 0x07U); + auto const short_secret = std::vector(31U, 0x07U); + auto const room = std::string{"O8437W3+jmzMVjoIP3tNwbm+XxHQk2iKpOA7aqw3qSc"}; + auto const identity = std::string{"M3VnsLXrkbxIDINXO64u8PZzFyD9ZYFiQULR2dshWYs"}; + auto const url = std::string{"https://livekit.example:7880"}; + + WHEN("the control call and each invalid variation are built") + { + using merovingian::homeserver::livekit_create_room_request; + using merovingian::homeserver::livekit_get_participant_request; + + auto const control_create = livekit_create_room_request(url, "key", secret, room, 1'700'000'000); + auto const control_get = livekit_get_participant_request(url, "key", secret, room, identity, 1'700'000'000); + + THEN("the controls build, and every variation is refused with no request") + { + CHECK(control_create.has_value()); + CHECK(control_get.has_value()); + + for (auto const* bad_url : {"http://livekit.example:7880", "http://10.0.0.1:7880", "ftp://127.0.0.1", + "not a url", "", "https://livekit.example:7880/?x=1"}) + { + CAPTURE(bad_url); + CHECK_FALSE(livekit_create_room_request(bad_url, "key", secret, room, 1'700'000'000)); + CHECK_FALSE(livekit_get_participant_request(bad_url, "key", secret, room, identity, 1'700'000'000)); + } + CHECK_FALSE(livekit_create_room_request(url, "key", short_secret, room, 1'700'000'000)); + CHECK_FALSE( + livekit_create_room_request(url, "key", std::span{}, room, 1'700'000'000)); + CHECK_FALSE(livekit_create_room_request(url, "", secret, room, 1'700'000'000)); + CHECK_FALSE(livekit_create_room_request(url, "key", secret, "short", 1'700'000'000)); + CHECK_FALSE(livekit_create_room_request(url, "key", secret, room, -1)); + CHECK_FALSE(livekit_get_participant_request(url, "key", short_secret, room, identity, 1'700'000'000)); + CHECK_FALSE(livekit_get_participant_request(url, "", secret, room, identity, 1'700'000'000)); + CHECK_FALSE(livekit_get_participant_request(url, "key", secret, "short", identity, 1'700'000'000)); + CHECK_FALSE( + livekit_get_participant_request(url, "key", secret, room, "@alice:example.com", 1'700'000'000)); + CHECK_FALSE(livekit_get_participant_request(url, "key", secret, room, identity, -1)); + } + } + } +} + +SCENARIO("A LiveKit call whose URL does not parse or whose host does not resolve fails before any exchange", + "[homeserver][livekit][negative]") +{ + auto client = merovingian::http::OutboundClient{}; + auto const no_test_perform = merovingian::homeserver::LiveKitTestPerform{}; + + GIVEN("a request whose URL is not a URL") + { + auto network = SlowDiscoveryNetwork{std::chrono::milliseconds{0}}; + auto discovery = merovingian::federation::CachedServerDiscovery{network, 60000U, []() -> std::uint64_t { + return 0U; + }}; + auto request = livekit_request(); + request.url = "not a url"; + + WHEN("it is performed") + { + auto const result = + merovingian::homeserver::perform_livekit_request(request, client, discovery, 5U, no_test_perform); + + THEN("it is an invalid_url failure and the host is never looked up") + { + CHECK_FALSE(result.ok); + CHECK(result.error == merovingian::http::OutboundError::invalid_url); + CHECK(result.error_detail == "invalid LiveKit API URL"); + CHECK(network.lookups() == 0); + } + } + } + + GIVEN("a lookup that fails, and one that succeeds with no address") + { + auto failing = SlowDiscoveryNetwork{std::chrono::milliseconds{0}, false, {}}; + auto empty = SlowDiscoveryNetwork{std::chrono::milliseconds{0}, true, {}}; + auto failing_discovery = merovingian::federation::CachedServerDiscovery{failing, 60000U, []() -> std::uint64_t { + return 0U; + }}; + auto empty_discovery = merovingian::federation::CachedServerDiscovery{empty, 60000U, []() -> std::uint64_t { + return 0U; + }}; + + WHEN("the request is performed against each") + { + auto const failed = merovingian::homeserver::perform_livekit_request( + livekit_request(), client, failing_discovery, 5U, no_test_perform); + auto const none = merovingian::homeserver::perform_livekit_request(livekit_request(), client, + empty_discovery, 5U, no_test_perform); + + THEN("each is an unresolved_host failure after one lookup, with no exchange") + { + CHECK(failing.lookups() == 1); + CHECK(empty.lookups() == 1); + CHECK_FALSE(failed.ok); + CHECK(failed.error == merovingian::http::OutboundError::unresolved_host); + CHECK(failed.error_detail == "failed to resolve the LiveKit API host"); + CHECK_FALSE(none.ok); + CHECK(none.error == merovingian::http::OutboundError::unresolved_host); + CHECK(none.error_detail == "failed to resolve the LiveKit API host"); + } + } + } +} From 654c68e7811ac89f4ffc0b7d3710bf4a06e68cda Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 19:42:21 +0000 Subject: [PATCH 15/19] Cover the wired LiveKit token provider, the relay refusals and the worker relay success path Co-Authored-By: Claude Opus 5.5 --- .../test_federation_worker_flow.cpp | 77 ++++++++ tests/integration/test_livekit_token_flow.cpp | 171 ++++++++++++++++++ 2 files changed, 248 insertions(+) diff --git a/tests/integration/test_federation_worker_flow.cpp b/tests/integration/test_federation_worker_flow.cpp index 4d53fba2d..bf9467e36 100644 --- a/tests/integration/test_federation_worker_flow.cpp +++ b/tests/integration/test_federation_worker_flow.cpp @@ -12,6 +12,7 @@ #include "../support/EduRelayContext.hpp" #include "../support/IngestedStateFixture.hpp" #include "../support/JoiningThreads.hpp" +#include "../support/LiveKitTestSupport.hpp" #include "../support/MasterKey.hpp" #include "../support/MembershipFixtureSupport.hpp" #include "../support/RemoteRoomFixture.hpp" @@ -3270,6 +3271,82 @@ SCENARIO("main admits a worker's LiveKit token relay only as the verified reques } } +SCENARIO("main issues a token for a worker's verified LiveKit relay when the token service is on and the user joined", + "[integration][federation-worker][query-relay][ghsa-3p5v][livekit]") +{ + // The token service is configured here (LiveKit is a mock and never called), so a relay admitted by its permit + // reaches a real decision: a subscribe-only token for a user main finds joined, a refusal for one it does not. + GIVEN("alice's room, the token service on, and a verified request from remote.example.org with its permit") + { + auto fixture = merovingian::tests::livekit::LiveKitFixture{}; + auto& homeserver = fixture.runtime().homeserver; + constexpr auto origin = std::string_view{"remote.example.org"}; + auto const user_id = std::string{"@carol:remote.example.org"}; + auto const body = std::string{R"({"url":")"} + std::string{merovingian::tests::livekit::sfu_url} + + R"(","room_id":")" + fixture.room_id + + R"(","slot_id":"m.call#room","member_id":"DEVICEID_member","user_id":")" + user_id + R"("})"; + auto const permit = + merovingian::federation::worker_relay_digest(merovingian::federation::WorkerRelayKind::livekit_token, body); + REQUIRE(permit.has_value()); + + auto channels = merovingian::tests::make_edu_relay_channels(); + auto context = merovingian::tests::EduRelayContext{*channels.main, *channels.worker}; + + WHEN("carol of that server has joined the room") + { + auto& store = homeserver.database.persistent_store; + auto const event_id = std::string{"$join-of-carol"}; + auto const join_json = R"({"content":{"membership":"join"},"event_id":")" + event_id + R"(","room_id":")" + + fixture.room_id + R"(","sender":")" + user_id + R"(","state_key":")" + user_id + + R"(","type":"m.room.member"})"; + store.events.push_back({event_id, fixture.room_id, user_id, join_json, 9U, 0U, {}, {}, {}}); + store.state.push_back({fixture.room_id, "m.room.member", user_id, event_id}); + store.memberships.push_back({fixture.room_id, user_id, "join", 0U}); + auto* room = merovingian::homeserver::find_local_room(homeserver.database, fixture.room_id); + REQUIRE(room != nullptr); + std::ignore = room->members.add(user_id); + + REQUIRE(context.establish(std::string{origin}, {}, {*permit})); + auto const reply = merovingian::homeserver::handle_livekit_token_ingest_request( + homeserver, + context.frame(merovingian::federation::WorkerRelayKind::livekit_token, body, std::string{origin}), + *channels.main); + REQUIRE(context.finish()); + + THEN("main answers 200 with a token, and LiveKit is not called") + { + INFO("reply: " << reply); + CHECK(merovingian::ipc::ipc_json_get_str(reply, "type") == "livekit_token_ingest_result"); + CHECK(merovingian::ipc::ipc_json_get_u64(reply, "status") == 200U); + auto const response_body = merovingian::ipc::ipc_json_get_str(reply, "response_body"); + CHECK(response_body.starts_with(R"({"jwt":")")); + CHECK(response_body.find("carol") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("carol has not joined the room") + { + REQUIRE(context.establish(std::string{origin}, {}, {*permit})); + auto const reply = merovingian::homeserver::handle_livekit_token_ingest_request( + homeserver, + context.frame(merovingian::federation::WorkerRelayKind::livekit_token, body, std::string{origin}), + *channels.main); + REQUIRE(context.finish()); + + THEN("main refuses with 403 M_FORBIDDEN and no token") + { + INFO("reply: " << reply); + CHECK(merovingian::ipc::ipc_json_get_u64(reply, "status") == 403U); + auto const response_body = merovingian::ipc::ipc_json_get_str(reply, "response_body"); + CHECK(response_body.find("M_FORBIDDEN") != std::string::npos); + CHECK(response_body.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + } + } + } +} + SCENARIO("handle_directory_query_ingest_request reads a room alias from main's own store", "[integration][federation-worker][query-relay][fed-endpoints]") { diff --git a/tests/integration/test_livekit_token_flow.cpp b/tests/integration/test_livekit_token_flow.cpp index b7f364afd..95654b2ba 100644 --- a/tests/integration/test_livekit_token_flow.cpp +++ b/tests/integration/test_livekit_token_flow.cpp @@ -23,6 +23,7 @@ #include "merovingian/core/SocketHandle.hpp" #include "merovingian/crypto/LiveKitToken.hpp" #include "merovingian/crypto/VerifiedHs256Token.hpp" +#include "merovingian/database/PersistentServerSigningKey.hpp" #include "merovingian/database/PersistentStore.hpp" #include "merovingian/homeserver/AuthService.hpp" #include "merovingian/homeserver/ClientOutboundProxy.hpp" @@ -31,6 +32,7 @@ #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/LiveKitNames.hpp" #include "merovingian/homeserver/LiveKitTokenService.hpp" +#include "merovingian/homeserver/LocalHttpRouter.hpp" #include "merovingian/homeserver/LocalRoom.hpp" #include "merovingian/homeserver/OperationResult.hpp" #include "merovingian/homeserver/RuntimeMutex.hpp" @@ -965,3 +967,172 @@ SCENARIO("A token for another server's SFU is relayed to that server, and only i } } } + +SCENARIO("The federation token provider main wires answers as the federation response", + "[homeserver][livekit][rtc][federation]") +{ + GIVEN("alice's room and the callbacks main wires for inbound federation") + { + auto fixture = LiveKitFixture{}; + hs::wire_federation_callbacks(fixture.runtime().homeserver); + auto const& provider = fixture.runtime().homeserver.federation.livekit_token_provider; + REQUIRE(provider); + + WHEN("the provider is asked for a user of the origin who has joined the room") + { + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + auto const response = provider(remote_server, federation_body(fixture.room_id, carol)); + + THEN("it is 200 with the token as the body") + { + REQUIRE(response.status == 200U); + auto const body = parse_object(response.body); + REQUIRE(body.size() == 1U); + auto const* jwt = string_member(body, "jwt"); + REQUIRE(jwt != nullptr); + std::ignore = verified_payload(*jwt); + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("the provider is asked for a user who has not joined the room") + { + auto const response = provider(remote_server, federation_body(fixture.room_id, carol)); + + THEN("the status and errcode of the refusal pass through, with no token") + { + CHECK(response.status == 403U); + auto const body = parse_object(response.body); + auto const* errcode = string_member(body, "errcode"); + REQUIRE(errcode != nullptr); + CHECK(*errcode == "M_FORBIDDEN"); + CHECK(response.body.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("the provider is given a body that is not JSON") + { + auto const response = provider(remote_server, "not json"); + + THEN("it is the 400 M_BAD_JSON the service refused with") + { + CHECK(response.status == 400U); + auto const body = parse_object(response.body); + auto const* errcode = string_member(body, "errcode"); + REQUIRE(errcode != nullptr); + CHECK(*errcode == "M_BAD_JSON"); + } + } + } +} + +SCENARIO("A token request this server cannot carry out is refused before LiveKit or another server is called", + "[homeserver][livekit][rtc][negative]") +{ + GIVEN("alice in a room, with this server unable to make outbound requests") + { + auto fixture = LiveKitFixture{}; + fixture.runtime().homeserver.cached_discovery.reset(); + + WHEN("alice asks for a token for this server's SFU") + { + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + token_body(fixture.room_id)); + + THEN("it is 502 M_UNKNOWN with no token, and LiveKit is not called") + { + CHECK(answer.status == 502U); + CHECK(errcode_of(answer) == "M_UNKNOWN"); + CHECK(answer.body.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + } + } + + WHEN("alice asks for a token for a server that has a member in the room") + { + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + relay_body(fixture.room_id)); + + THEN("it is 502 M_UNKNOWN with no token, and LiveKit is not called") + { + CHECK(answer.status == 502U); + CHECK(errcode_of(answer) == "M_UNKNOWN"); + CHECK(answer.body.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + } + } + } + + GIVEN("alice in a room that carol of remote.example.org has joined, and every client outbound slot taken") + { + auto fixture = LiveKitFixture{}; + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + fixture.runtime().homeserver.client_outbound_proxy_policy.global_cap = 1U; + auto const held = hs::admit_client_outbound_proxy(fixture.runtime().homeserver, "another-client"); + REQUIRE(held.has_value()); + + WHEN("alice asks for a token for remote.example.org's SFU") + { + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + relay_body(fixture.room_id)); + + THEN("it is 429 M_LIMIT_EXCEEDED with retry_after_ms, and nothing is relayed or called") + { + CHECK(answer.status == 429U); + CHECK(errcode_of(answer) == "M_LIMIT_EXCEEDED"); + auto const body = parse_object(answer.body); + CHECK(int_member(body, "retry_after_ms") != nullptr); + CHECK(fixture.mock().requests.empty()); + } + } + } + + GIVEN("alice in a room that carol of remote.example.org has joined, and a signing key this server cannot use") + { + auto fixture = LiveKitFixture{}; + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + auto& homeserver = fixture.runtime().homeserver; + // The newest key holding a secret is the one chosen; its secret is not 32 bytes, so no key can be loaded. + REQUIRE(merovingian::database::store_server_signing_key( + homeserver.database.persistent_store, + {homeserver.config.server().server_name, "ed25519:unusable", "AAAA", 4102444800000U, "AAAA"})); + + WHEN("alice asks for a token for remote.example.org's SFU") + { + auto const answer = request(fixture.runtime(), "POST", std::string{stable_path}, fixture.alice_token, + relay_body(fixture.room_id)); + + THEN("it is 500 M_UNKNOWN with no token, and nothing is sent or called") + { + CHECK(answer.status == 500U); + CHECK(errcode_of(answer) == "M_UNKNOWN"); + CHECK(answer.body.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + CHECK(homeserver.client_outbound_budget->active() == 0U); + } + } + } + + GIVEN("carol of remote.example.org joined to alice's room, and an API secret this server cannot read") + { + auto fixture = LiveKitFixture{"/nonexistent/merovingian-livekit-secret"}; + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + + WHEN("remote.example.org asks for a token for carol") + { + auto const answer = federated(fixture.runtime(), remote_server, federation_body(fixture.room_id, carol)); + + THEN("it is 500 M_UNKNOWN with no token, and LiveKit is not called") + { + CHECK_FALSE(answer.ok); + CHECK(answer.status == 500U); + CHECK(answer.errcode == "M_UNKNOWN"); + CHECK(answer.reason == "LiveKit tokens are unavailable"); + CHECK(answer.value.find("jwt") == std::string::npos); + CHECK(fixture.mock().requests.empty()); + } + } + } +} From 9e5387150df4e3056405cd0eef551d7ce1819468 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 19:43:05 +0000 Subject: [PATCH 16/19] Cover the delegation job's and webhook's refusal and ignore paths Scenarios for the paths CI's coverage report showed unexecuted in LiveKitDelegations.cpp: a malformed or over-long webhook token and claims that are not an object (401); authentic events with no object body, no participant, an unreadable createdAt, or a time before the delegation (ignored); createdAt as a bare integer; the bounded memory of event IDs; the API secret missing (no call, webhook 500); the token service switched off (delegations dropped, webhook 404); a stored delegation whose names cannot be derived (dropped); and an unreadable GetParticipant answer (nothing changes). Co-Authored-By: Claude Opus 5.5 --- .../test_livekit_delegation_flow.cpp | 296 ++++++++++++++++++ 1 file changed, 296 insertions(+) diff --git a/tests/integration/test_livekit_delegation_flow.cpp b/tests/integration/test_livekit_delegation_flow.cpp index 25d85d670..e00e5c8a1 100644 --- a/tests/integration/test_livekit_delegation_flow.cpp +++ b/tests/integration/test_livekit_delegation_flow.cpp @@ -7,6 +7,7 @@ #include "../support/JsonTestSupport.hpp" #include "../support/LiveKitTestSupport.hpp" +#include "merovingian/crypto/LiveKitToken.hpp" #include "merovingian/database/DelayedEventStatus.hpp" #include "merovingian/database/LiveKitDelegationStore.hpp" #include "merovingian/database/LiveKitDelegationTable.hpp" @@ -31,6 +32,7 @@ #include #include #include +#include #include #include #include @@ -985,3 +987,297 @@ SCENARIO("A webhook prompts only the delegation of the participant it names, as } } } + +namespace +{ + +// alice's leave, delegated and checked at t0 with LiveKit answering that she is connected; the clock at t0 + 5 s. +struct CheckedDelegation final +{ + Delegated delegated{}; + std::int64_t now_s{static_cast((t0_ms + 5'000U) / 1000U)}; + std::string room_name{}; + std::string identity{}; + + CheckedDelegation() + { + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = R"({"state":"ACTIVE"})"; + std::ignore = run_job(fixture, t0_ms); + REQUIRE(get_participant_calls(fixture) == 1U); + room_name = *hs::livekit_room_name(fixture.room_id, "m.call#room"); + identity = *hs::livekit_participant_identity("@alice:example.org", "DEVICEID_member"); + } + + // A participant_left of alice's delegation, with `created_at_json` written into the body as it is. + [[nodiscard]] auto left_with_created_at(std::string_view const id, std::string_view const created_at_json) const + -> std::string + { + return R"({"event":"participant_left","room":{"name":")" + room_name + R"("},"participant":{"identity":")" + + identity + R"("},"id":")" + std::string{id} + R"(","createdAt":)" + std::string{created_at_json} + "}"; + } +}; + +} // namespace + +SCENARIO("A webhook with a malformed token or unreadable claims is refused, and one that names nothing is ignored", + "[homeserver][livekit][rtc][delegation][webhook][negative]") +{ + GIVEN("alice's delegation, checked at t0") + { + auto checked = CheckedDelegation{}; + auto& fixture = checked.delegated.fixture; + auto const now_s = checked.now_s; + auto const left = webhook_event("participant_left", checked.room_name, checked.identity, "EV_shape", now_s); + + WHEN("the Authorization header is a bare Bearer prefix, or a token longer than any HS256 token") + { + auto const bare = post_webhook(fixture, Webhook{left, "Bearer "}, now_s); + auto const long_token = post_webhook( + fixture, Webhook{left, std::string(merovingian::crypto::hs256_token_max_bytes + 1U, 'a')}, now_s); + + THEN("each is 401 M_UNAUTHORIZED") + { + CHECK(bare.status == 401U); + CHECK(bare.errcode == "M_UNAUTHORIZED"); + CHECK(long_token.status == 401U); + CHECK(long_token.errcode == "M_UNAUTHORIZED"); + } + } + + WHEN("the token is signed with the API secret but its claims are not a JSON object") + { + auto const answer = post_webhook(fixture, Webhook{left, hs256("[1]", api_secret)}, now_s); + + THEN("it is 401 M_UNAUTHORIZED") + { + CHECK(answer.status == 401U); + CHECK(answer.errcode == "M_UNAUTHORIZED"); + } + } + + WHEN("authentic webhooks carry a body that is not an object, no participant, an unreadable createdAt, or an " + "event from before the delegation existed") + { + auto const not_object = post_webhook(fixture, signed_webhook("[]", now_s), now_s); + auto const no_participant = + post_webhook(fixture, + signed_webhook(R"({"event":"participant_left","room":{"name":")" + checked.room_name + + R"("},"id":"EV_np","createdAt":")" + std::to_string(now_s) + R"("})", + now_s), + now_s); + auto const empty_created = + post_webhook(fixture, signed_webhook(checked.left_with_created_at("EV_e", R"("")"), now_s), now_s); + auto const letters_created = + post_webhook(fixture, signed_webhook(checked.left_with_created_at("EV_l", R"("12a")"), now_s), now_s); + auto const before_delegation = + post_webhook(fixture, + signed_webhook(webhook_event("participant_left", checked.room_name, checked.identity, + "EV_old", static_cast(t0_ms / 1000U) - 10), + now_s), + now_s); + std::ignore = run_job(fixture, t0_ms + 6'000U); + + THEN("each is 200 and none brings the check forward") + { + for (auto const* answer : + {¬_object, &no_participant, &empty_created, &letters_created, &before_delegation}) + { + CHECK(answer->status == 200U); + } + CHECK(get_participant_calls(fixture) == 1U); + } + } + + WHEN("an authentic webhook writes createdAt as a bare integer") + { + auto const answer = post_webhook( + fixture, signed_webhook(checked.left_with_created_at("EV_int", std::to_string(now_s)), now_s), now_s); + std::ignore = run_job(fixture, t0_ms + 6'000U); + + THEN("it is read as the time it names, and the check is brought forward") + { + CHECK(answer.status == 200U); + CHECK(get_participant_calls(fixture) == 2U); + } + } + } +} + +SCENARIO("The webhook remembers a bounded number of event IDs, the oldest forgotten first", + "[homeserver][livekit][rtc][delegation][webhook]") +{ + GIVEN("alice's delegation, checked at t0, and LiveKit's participant_left for her as event EV_first") + { + auto checked = CheckedDelegation{}; + auto& fixture = checked.delegated.fixture; + auto const now_s = checked.now_s; + auto const first = signed_webhook( + webhook_event("participant_left", checked.room_name, checked.identity, "EV_first", now_s), now_s); + REQUIRE(post_webhook(fixture, first, now_s).status == 200U); + std::ignore = run_job(fixture, t0_ms + 6'000U); + REQUIRE(get_participant_calls(fixture) == 2U); + + WHEN("as many other events as the webhook remembers follow, for a stranger, and EV_first comes again") + { + for (auto index = std::size_t{0U}; index < hs::livekit_webhook_seen_ids; ++index) + { + auto const other = + signed_webhook(webhook_event("participant_left", checked.room_name, std::string(43U, 'S'), + "EV_other_" + std::to_string(index), now_s), + now_s); + REQUIRE(post_webhook(fixture, other, now_s).status == 200U); + } + REQUIRE(fixture.runtime().homeserver.livekit_webhook_seen_ids.size() == hs::livekit_webhook_seen_ids); + auto const again = post_webhook(fixture, first, now_s); + std::ignore = run_job(fixture, t0_ms + 7'000U); + + THEN("EV_first has been forgotten, so it is taken as new and brings the check forward once more") + { + CHECK(again.status == 200U); + CHECK(get_participant_calls(fixture) == 3U); + } + } + + WHEN("EV_first comes again straight away") + { + auto const again = post_webhook(fixture, first, now_s); + std::ignore = run_job(fixture, t0_ms + 7'000U); + + THEN("it is remembered, answered 200, and brings nothing forward") + { + CHECK(again.status == 200U); + CHECK(get_participant_calls(fixture) == 2U); + } + } + } +} + +SCENARIO("Without the API secret the job asks LiveKit nothing and the webhook cannot be checked", + "[homeserver][livekit][rtc][delegation][webhook][negative]") +{ + GIVEN("alice's delegated leave, and the API secret file gone") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.runtime().homeserver.config.server().rtc.token_service.api_secret_file = + (std::filesystem::temp_directory_path() / "merovingian-livekit-no-such-secret").string(); + auto const now_s = static_cast(t0_ms / 1000U); + auto const room_name = *hs::livekit_room_name(fixture.room_id, "m.call#room"); + auto const identity = *hs::livekit_participant_identity("@alice:example.org", "DEVICEID_member"); + + WHEN("the job runs, and LiveKit's signed webhook arrives") + { + std::ignore = run_job(fixture, t0_ms); + auto const answer = post_webhook( + fixture, signed_webhook(webhook_event("participant_left", room_name, identity, "EV_s", now_s), now_s), + now_s); + + THEN("LiveKit is not asked, the delegation and its event stay, and the webhook is 500 M_UNKNOWN") + { + CHECK(get_participant_calls(fixture) == 0U); + CHECK(delegations(fixture).find(delegated.delay_id) != nullptr); + CHECK(delayed_row(fixture, delegated.delay_id)->status == + merovingian::database::DelayedEventStatus::scheduled); + CHECK(answer.status == 500U); + CHECK(answer.errcode == "M_UNKNOWN"); + } + } + } +} + +SCENARIO("With the token service switched off, the job drops every delegation and the webhook is no route", + "[homeserver][livekit][rtc][delegation][webhook]") +{ + GIVEN("alice's delegated leave, and the token service's URL then removed from the configuration") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.runtime().homeserver.config.server().rtc.token_service.url.clear(); + auto const now_s = static_cast(t0_ms / 1000U); + + WHEN("the job runs, and a signed webhook arrives") + { + std::ignore = run_job(fixture, t0_ms); + auto const answer = post_webhook(fixture, + signed_webhook(webhook_event("participant_left", std::string(43U, 'B'), + std::string(43U, 'C'), "EV_off", now_s), + now_s), + now_s); + + THEN("the delegation is gone without a call, its leave stays scheduled, and the webhook is 404") + { + CHECK(get_participant_calls(fixture) == 0U); + CHECK(delegations(fixture).size() == 0U); + CHECK(delayed_row(fixture, delegated.delay_id)->status == + merovingian::database::DelayedEventStatus::scheduled); + CHECK(answer.status == 404U); + CHECK(answer.errcode == "M_UNRECOGNIZED"); + } + } + } +} + +SCENARIO("A stored delegation whose LiveKit names cannot be derived is dropped, and others are kept", + "[homeserver][livekit][rtc][delegation]") +{ + GIVEN("alice's delegation, and a second scheduled leave of hers stored with a member ID that is not UTF-8") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = R"({"state":"ACTIVE"})"; + auto const other_delay = schedule_leave(fixture, fixture.alice_token, hour_ms, "alice-unnameable"); + auto row = merovingian::database::PersistentLiveKitDelegation{}; + row.delay_id = other_delay; + row.user_id = "@alice:example.org"; + row.room_id = fixture.room_id; + row.slot_id = "m.call#room"; + row.member_id = "\xFF"; + row.created_ms = t0_ms; + REQUIRE(merovingian::database::store_livekit_delegation(fixture.runtime().homeserver.database.persistent_store, + std::move(row))); + + WHEN("the job runs") + { + std::ignore = run_job(fixture, t0_ms); + + THEN("the unnameable delegation is dropped without a call, and alice's own is asked about") + { + CHECK(delegations(fixture).find(other_delay) == nullptr); + CHECK(delegations(fixture).find(delegated.delay_id) != nullptr); + CHECK(get_participant_calls(fixture) == 1U); + CHECK(delayed_row(fixture, other_delay)->status == + merovingian::database::DelayedEventStatus::scheduled); + } + } + } +} + +SCENARIO("An answer from LiveKit that cannot be read changes nothing", "[homeserver][livekit][rtc][delegation]") +{ + GIVEN("alice's delegated one-hour leave, and LiveKit answering 200 with a body that is not JSON") + { + auto delegated = Delegated{}; + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = "not json"; + + WHEN("the job runs at t0 and again 31 minutes later, when a connected participant's leave would be restarted") + { + std::ignore = run_job(fixture, t0_ms); + std::ignore = run_job(fixture, t0_ms + 31U * 60'000U); + auto const* event = delayed_row(fixture, delegated.delay_id); + + THEN("LiveKit was asked both times, and the leave was neither restarted nor sent") + { + CHECK(get_participant_calls(fixture) == 2U); + REQUIRE(event != nullptr); + CHECK(event->status == merovingian::database::DelayedEventStatus::scheduled); + CHECK(event->delayed_since_ms == t0_ms); + CHECK(delegations(fixture).find(delegated.delay_id) != nullptr); + } + } + } +} From d8f9543019d48f17523676a5877e3decc0530cb1 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 20:13:18 +0000 Subject: [PATCH 17/19] Say what the LiveKit call deadline bounds and what it cannot The deadline stops a slow lookup from adding a whole exchange, and stops an exchange from starting once it is spent. The lookup is a blocking getaddrinfo the deadline cannot interrupt, so the comment, ADR-0830 and the CHANGELOG no longer claim the call never outlasts its budget. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 ++-- ...oes-to-the-configured-address-with-a-token-of-its-own.md | 6 ++++-- src/homeserver/LiveKitRoomService.cpp | 4 ++-- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8438b6c05..c685c194d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,8 +21,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * LiveKit's webhook is believed only when signed with the API secret for its exact body and recent, and even then only brings a check forward: it never sends or restarts an event (ADR-0833). * The federation worker refuses to start if a Landlock rule would let it read the LiveKit API secret file (ADR-0062). -* A LiveKit call's host lookup counts against the call's deadline, so a slow resolver cannot hold a request thread - past it (ADR-0830). +* A LiveKit call's host lookup counts against the call's deadline: the exchange gets only the time the lookup left, + and none starts once the deadline has passed (ADR-0830). ## Bug fixes diff --git a/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md index 29b4a728c..cd31b21b4 100644 --- a/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md +++ b/docs/adr/0830-every-call-to-livekit-goes-to-the-configured-address-with-a-token-of-its-own.md @@ -21,8 +21,10 @@ call is added here. * `perform_livekit_request` resolves the host with `discovery.upstream().lookup_addresses`, the operator-trusted lookup the application service client uses (ADR-0515). The connection is pinned to the addresses found. * The lookup and the exchange draw from one `OutboundDeadline` of the call's `timeout_seconds`: the exchange gets - only what the lookup left, and none is started once it is spent (a timeout). A slow resolver therefore cannot hold - the request thread, the ADR-0079 slot or the job past the call's bound. + only what the lookup left, and none is started once it is spent (a timeout). A slow lookup therefore never adds a + whole exchange to the call. The lookup itself is a blocking `getaddrinfo` that the deadline cannot interrupt: a + resolver slower than the whole budget still holds the thread, the ADR-0079 slot or the job until it answers, as + it does for every other caller of `lookup_addresses`. * The SSRF-filtered lookup is not used: the operator chose the address, and LiveKit commonly runs on the same host or LAN. * TLS verification is always on and redirects are refused (`http::OutboundClient`). diff --git a/src/homeserver/LiveKitRoomService.cpp b/src/homeserver/LiveKitRoomService.cpp index 0b7877067..6a91afa2b 100644 --- a/src/homeserver/LiveKitRoomService.cpp +++ b/src/homeserver/LiveKitRoomService.cpp @@ -122,8 +122,8 @@ auto perform_livekit_request(http::OutboundRequest request, http::OutboundClient { return failed(http::OutboundError::timeout, "deadline exceeded"); } - // One deadline for the lookup and the exchange: a slow lookup shortens the exchange rather than adding to it, so - // the call never holds its thread or its outbound slot past `timeout_seconds`. + // One deadline for the lookup and the exchange: a slow lookup shortens the exchange rather than adding to it, and + // no exchange starts once it is spent. The lookup itself is a blocking call this cannot interrupt. auto const deadline = OutboundDeadline{timeout_seconds}; auto const limit_to = [&request](std::uint32_t const seconds) { request.total_timeout_seconds = seconds; From 955350c1bdddfcadbc9f88034cf34d14dffa389a Mon Sep 17 00:00:00 2001 From: James Chapman Date: Tue, 17 Nov 2026 23:31:48 +0000 Subject: [PATCH 18/19] Split the LiveKit flow scenarios CodeQL found over 100 lines CodeQL's poorly-documented-function rule failed on five Catch2 scenarios of 106 to 125 lines. Each is split where its cases already divide, so every scenario is under 95 lines and no case is lost or changed: - the worker relay: the admitted relay and the spent permit, apart from the refusals for another origin, no permit and another body's permit; - the webhook: replayed, stale, other-kind and unknown signed webhooks apart from the signature, prompt and size cases, both on CheckedDelegation, now declared before its first user; - the federated request: the 400s and the no-service 404 apart from the 403s; - the relay: the other server's refusals and errors apart from the success and the ACL; - the refusals before any call: no outbound client apart from the budget, the signing key and the API secret. Co-Authored-By: Claude Opus 5.5 --- .../test_federation_worker_flow.cpp | 78 ++++++++---- .../test_livekit_delegation_flow.cpp | 115 ++++++++++-------- tests/integration/test_livekit_token_flow.cpp | 20 +++ 3 files changed, 138 insertions(+), 75 deletions(-) diff --git a/tests/integration/test_federation_worker_flow.cpp b/tests/integration/test_federation_worker_flow.cpp index bf9467e36..a8aac00e9 100644 --- a/tests/integration/test_federation_worker_flow.cpp +++ b/tests/integration/test_federation_worker_flow.cpp @@ -3150,7 +3150,7 @@ SCENARIO("main admits a worker's key and profile query only as the verified quer } } -SCENARIO("main admits a worker's LiveKit token relay only as the verified request it forwarded", +SCENARIO("main admits a worker's LiveKit token relay under the origin it verified, with its permit, once", "[integration][federation-worker][query-relay][ghsa-3p5v][livekit]") { // ADR-0831: the LiveKit secret is main's alone, so a worker relays the request. The service is off here, so a @@ -3199,6 +3199,62 @@ SCENARIO("main admits a worker's LiveKit token relay only as the verified reques CHECK(body_of(reply).find("M_UNRECOGNIZED") != std::string::npos); } } + WHEN("the permit is spent a second time") + { + REQUIRE(context.establish("remote.example", {}, {*permit})); + auto const frame = + context.frame(merovingian::federation::WorkerRelayKind::livekit_token, body, "remote.example"); + auto const first = + merovingian::homeserver::handle_livekit_token_ingest_request(runtime, frame, *channels.main); + auto const second = + merovingian::homeserver::handle_livekit_token_ingest_request(runtime, frame, *channels.main); + REQUIRE(context.finish()); + + THEN("the first reaches the token service and the second is 403 M_FORBIDDEN") + { + INFO("first: " << first << "\nsecond: " << second); + CHECK(status_of(first) == 404U); + CHECK(status_of(second) == 403U); + CHECK(body_of(second).find("M_FORBIDDEN") != std::string::npos); + CHECK(body_of(second).find("M_UNRECOGNIZED") == std::string::npos); + } + } + } +} + +SCENARIO("main refuses a worker's LiveKit token relay for another origin, or without this body's permit", + "[integration][federation-worker][query-relay][ghsa-3p5v][livekit][negative]") +{ + // ADR-0831: each relay here is refused by main before the token service. The service is off, so a relay that + // got through would answer 404 M_UNRECOGNIZED; every refusal must be 403 M_FORBIDDEN instead. + GIVEN("a runtime with no LiveKit token service and a verified request from remote.example carrying a body") + { + REQUIRE(sodium_init() >= 0); + + auto const tmp_dir = unique_temp_dir("merovingian-fed-worker-livekit-binding"); + auto config = make_federation_worker_config(tmp_dir); + config.database().sqlite_path = (tmp_dir / "livekit-binding-test.sqlite3").string(); + + auto started = start_runtime(config); + REQUIRE(started.started); + auto& runtime = started.runtime; + merovingian::homeserver::wire_federation_callbacks(runtime); + REQUIRE(runtime.federation.livekit_token_provider); + + auto const body = std::string{R"({"room_id":"!r:remote.example","slot_id":"s","member":{"id":"m"}})"}; + auto const permit = + merovingian::federation::worker_relay_digest(merovingian::federation::WorkerRelayKind::livekit_token, body); + REQUIRE(permit.has_value()); + auto const status_of = [](std::string const& reply) { + return merovingian::ipc::ipc_json_get_u64(reply, "status"); + }; + auto const body_of = [](std::string const& reply) { + return merovingian::ipc::ipc_json_get_str(reply, "response_body"); + }; + + auto channels = merovingian::tests::make_edu_relay_channels(); + auto context = merovingian::tests::EduRelayContext{*channels.main, *channels.worker}; + WHEN("the worker names an origin other than the one main verified") { REQUIRE(context.establish("remote.example", {}, {*permit})); @@ -3231,26 +3287,6 @@ SCENARIO("main admits a worker's LiveKit token relay only as the verified reques CHECK(body_of(reply).find("M_UNRECOGNIZED") == std::string::npos); } } - WHEN("the permit is spent a second time") - { - REQUIRE(context.establish("remote.example", {}, {*permit})); - auto const frame = - context.frame(merovingian::federation::WorkerRelayKind::livekit_token, body, "remote.example"); - auto const first = - merovingian::homeserver::handle_livekit_token_ingest_request(runtime, frame, *channels.main); - auto const second = - merovingian::homeserver::handle_livekit_token_ingest_request(runtime, frame, *channels.main); - REQUIRE(context.finish()); - - THEN("the first reaches the token service and the second is 403 M_FORBIDDEN") - { - INFO("first: " << first << "\nsecond: " << second); - CHECK(status_of(first) == 404U); - CHECK(status_of(second) == 403U); - CHECK(body_of(second).find("M_FORBIDDEN") != std::string::npos); - CHECK(body_of(second).find("M_UNRECOGNIZED") == std::string::npos); - } - } WHEN("the permit was made for another body") { auto const other_permit = merovingian::federation::worker_relay_digest( diff --git a/tests/integration/test_livekit_delegation_flow.cpp b/tests/integration/test_livekit_delegation_flow.cpp index e00e5c8a1..21e641c47 100644 --- a/tests/integration/test_livekit_delegation_flow.cpp +++ b/tests/integration/test_livekit_delegation_flow.cpp @@ -201,6 +201,34 @@ struct Webhook final return hs::receive_livekit_webhook(fixture.runtime(), request, now_seconds); } +// alice's leave, delegated and checked at t0 with LiveKit answering that she is connected; the clock at t0 + 5 s. +struct CheckedDelegation final +{ + Delegated delegated{}; + std::int64_t now_s{static_cast((t0_ms + 5'000U) / 1000U)}; + std::string room_name{}; + std::string identity{}; + + CheckedDelegation() + { + auto& fixture = delegated.fixture; + fixture.mock().get_participant_status = 200U; + fixture.mock().get_participant_body = R"({"state":"ACTIVE"})"; + std::ignore = run_job(fixture, t0_ms); + REQUIRE(get_participant_calls(fixture) == 1U); + room_name = *hs::livekit_room_name(fixture.room_id, "m.call#room"); + identity = *hs::livekit_participant_identity("@alice:example.org", "DEVICEID_member"); + } + + // A participant_left of alice's delegation, with `created_at_json` written into the body as it is. + [[nodiscard]] auto left_with_created_at(std::string_view const id, std::string_view const created_at_json) const + -> std::string + { + return R"({"event":"participant_left","room":{"name":")" + room_name + R"("},"participant":{"identity":")" + + identity + R"("},"id":")" + std::string{id} + R"(","createdAt":)" + std::string{created_at_json} + "}"; + } +}; + } // namespace SCENARIO("A delegation is accepted only for the caller's own scheduled event, in the room, for this server's SFU", @@ -643,15 +671,11 @@ SCENARIO("A LiveKit webhook is believed only when LiveKit signed it, and then on { GIVEN("alice's delegated leave, checked at t0 and seen connected") { - auto delegated = Delegated{}; - auto& fixture = delegated.fixture; - fixture.mock().get_participant_status = 200U; - fixture.mock().get_participant_body = R"({"state":"ACTIVE"})"; - std::ignore = run_job(fixture, t0_ms); - REQUIRE(get_participant_calls(fixture) == 1U); - auto const now_s = static_cast((t0_ms + 5'000U) / 1000U); - auto const room_name = *hs::livekit_room_name(fixture.room_id, "m.call#room"); - auto const identity = *hs::livekit_participant_identity("@alice:example.org", "DEVICEID_member"); + auto checked = CheckedDelegation{}; + auto& fixture = checked.delegated.fixture; + auto const now_s = checked.now_s; + auto const& room_name = checked.room_name; + auto const& identity = checked.identity; auto const left = webhook_event("participant_left", room_name, identity, "EV_1", now_s); WHEN("a webhook is unsigned, signed with another secret, by another key, stale, or for another body") @@ -691,7 +715,7 @@ SCENARIO("A LiveKit webhook is believed only when LiveKit signed it, and then on fixture.mock().get_participant_status = 404U; fixture.mock().get_participant_body = R"({"code":"not_found"})"; auto const answer = post_webhook(fixture, webhook, now_s); - auto const status_after_webhook = delayed_row(fixture, delegated.delay_id)->status; + auto const status_after_webhook = delayed_row(fixture, checked.delegated.delay_id)->status; std::ignore = run_job(fixture, t0_ms + 6'000U); THEN("it is 200, changes nothing by itself, and the next run checks at once and sends the leave") @@ -699,11 +723,37 @@ SCENARIO("A LiveKit webhook is believed only when LiveKit signed it, and then on CHECK(answer.status == 200U); CHECK(status_after_webhook == merovingian::database::DelayedEventStatus::scheduled); CHECK(get_participant_calls(fixture) == 2U); - CHECK(delayed_row(fixture, delegated.delay_id)->status == + CHECK(delayed_row(fixture, checked.delegated.delay_id)->status == merovingian::database::DelayedEventStatus::sent); } } + WHEN("a webhook is larger than 64 KiB") + { + auto const answer = post_webhook(fixture, signed_webhook(std::string(64U * 1024U + 1U, ' '), now_s), now_s); + + THEN("it is 413") + { + CHECK(answer.status == 413U); + } + } + } +} + +SCENARIO("A signed webhook that is replayed, stale, of another kind or for no delegation prompts no check", + "[homeserver][livekit][rtc][delegation][webhook]") +{ + // Only a participant_left LiveKit signed, seen once and recent, for a recorded delegation brings its check + // forward; anything else is still answered 200, so LiveKit does not retry it. + GIVEN("alice's delegated leave, checked at t0 and seen connected") + { + auto checked = CheckedDelegation{}; + auto& fixture = checked.delegated.fixture; + auto const now_s = checked.now_s; + auto const& room_name = checked.room_name; + auto const& identity = checked.identity; + auto const left = webhook_event("participant_left", room_name, identity, "EV_1", now_s); + WHEN("a signed webhook is replayed, stale, of another kind, or for no recorded delegation") { auto const first = post_webhook(fixture, signed_webhook(left, now_s), now_s); @@ -734,16 +784,6 @@ SCENARIO("A LiveKit webhook is believed only when LiveKit signed it, and then on CHECK(get_participant_calls(fixture) == calls_after_first); } } - - WHEN("a webhook is larger than 64 KiB") - { - auto const answer = post_webhook(fixture, signed_webhook(std::string(64U * 1024U + 1U, ' '), now_s), now_s); - - THEN("it is 413") - { - CHECK(answer.status == 413U); - } - } } } @@ -988,39 +1028,6 @@ SCENARIO("A webhook prompts only the delegation of the participant it names, as } } -namespace -{ - -// alice's leave, delegated and checked at t0 with LiveKit answering that she is connected; the clock at t0 + 5 s. -struct CheckedDelegation final -{ - Delegated delegated{}; - std::int64_t now_s{static_cast((t0_ms + 5'000U) / 1000U)}; - std::string room_name{}; - std::string identity{}; - - CheckedDelegation() - { - auto& fixture = delegated.fixture; - fixture.mock().get_participant_status = 200U; - fixture.mock().get_participant_body = R"({"state":"ACTIVE"})"; - std::ignore = run_job(fixture, t0_ms); - REQUIRE(get_participant_calls(fixture) == 1U); - room_name = *hs::livekit_room_name(fixture.room_id, "m.call#room"); - identity = *hs::livekit_participant_identity("@alice:example.org", "DEVICEID_member"); - } - - // A participant_left of alice's delegation, with `created_at_json` written into the body as it is. - [[nodiscard]] auto left_with_created_at(std::string_view const id, std::string_view const created_at_json) const - -> std::string - { - return R"({"event":"participant_left","room":{"name":")" + room_name + R"("},"participant":{"identity":")" + - identity + R"("},"id":")" + std::string{id} + R"(","createdAt":)" + std::string{created_at_json} + "}"; - } -}; - -} // namespace - SCENARIO("A webhook with a malformed token or unreadable claims is refused, and one that names nothing is ignored", "[homeserver][livekit][rtc][delegation][webhook][negative]") { diff --git a/tests/integration/test_livekit_token_flow.cpp b/tests/integration/test_livekit_token_flow.cpp index 95654b2ba..df5b6d777 100644 --- a/tests/integration/test_livekit_token_flow.cpp +++ b/tests/integration/test_livekit_token_flow.cpp @@ -813,6 +813,18 @@ SCENARIO("A federated request is refused unless this server's own state shows th CHECK(left.errcode == "M_FORBIDDEN"); } } + } +} + +SCENARIO("A federated request for another SFU or with a malformed body is 400, and with no token service 404", + "[homeserver][livekit][rtc][federation][negative]") +{ + GIVEN("alice's room, which carol of remote.example.org has joined") + { + auto fixture = LiveKitFixture{}; + seed_remote_join(fixture.runtime(), fixture.room_id, carol); + auto const joined = federated(fixture.runtime(), remote_server, federation_body(fixture.room_id, carol)); + REQUIRE(joined.status == 200U); WHEN("the url is not this server's SFU, or the body is malformed") { @@ -921,7 +933,11 @@ SCENARIO("A token for another server's SFU is relayed to that server, and only i } } } +} +SCENARIO("A relayed request's refusal or error is passed on only in this server's words", + "[homeserver][livekit][rtc][federation][relay][negative]") +{ GIVEN("remote.example.org answering get_token with a refusal, an error or a malformed jwt") { struct Case final @@ -1064,7 +1080,11 @@ SCENARIO("A token request this server cannot carry out is refused before LiveKit } } } +} +SCENARIO("A token request is refused before any call when the outbound budget, signing key or API secret fails", + "[homeserver][livekit][rtc][negative]") +{ GIVEN("alice in a room that carol of remote.example.org has joined, and every client outbound slot taken") { auto fixture = LiveKitFixture{}; From a20f5da67dd29294305e5dbdafd4d1797a3ecb6f Mon Sep 17 00:00:00 2001 From: James Chapman Date: Wed, 18 Nov 2026 01:20:49 +0000 Subject: [PATCH 19/19] Give SQLite writes one pooled connection, and change the version only when the owner asks (#599) * Give SQLite writes one pooled connection so a write never waits in SQLite's busy handler for another (1.1.4) The DB-7 scenario lost three of 64 writes under load: three pooled SQLite connections being opened polled SQLite's busy handler for the first one's lock, lost to its back-to-back commits (every journal and database sync runs under EXCLUSIVE) and were refused after 5 s with SQLITE_BUSY. SQLite runs one write at a time, so the SQLite write pool now holds one connection whatever database.pool_size says, and writers wait in the pool instead (ADR-0834). database.pool_size applies to PostgreSQL only. A new scenario holds SQLite's write lock on a leased pool slot for 7 s while a second write runs; on the old code that write was refused at BEGIN IMMEDIATE after the busy timeout. Co-Authored-By: Claude Opus 5.5 * Name the one SQLite write connection in the review skill's database invariants Co-Authored-By: Claude Opus 5.5 * Change the version only when the owner asks, and keep this branch at 1.1.3 The owner's rule from 2026-11-18: no branch increments the version on its own; it changes only when the owner asks, and every change adds its CHANGELOG bullets to the newest version's entry (ADR-0835, superseding ADR-0464 and the per-branch increment of ADR-0647). docs/versioning.md, the root AGENTS.md, docs/coding-rules.md, docs/AGENTS.md and the review skill now say so. Under the new rule this branch drops its 1.1.4 bump: every version location is back to its base's 1.1.3, and the SQLite fix's bullet and release-notes sentence move into the 1.1.3 entry. Co-Authored-By: Claude Opus 5.5 --------- Co-authored-by: Claude Opus 5.5 --- .agent/skills/merovingian-review/SKILL.md | 10 +- .../references/module-invariants.md | 2 + .../references/obligations.md | 14 ++- AGENTS.md | 4 +- CHANGELOG.md | 7 +- docs/AGENTS.md | 4 +- .../0154-pool-database-write-connections.md | 5 + ...y-changes-do-not-require-a-version-bump.md | 6 +- ...rsions-from-1-0-0-are-major-minor-build.md | 3 +- ...lite-writes-share-one-pooled-connection.md | 86 +++++++++++++++++ ...ersion-changes-only-when-the-owner-asks.md | 66 +++++++++++++ docs/adr/index.md | 6 +- docs/coding-rules.md | 7 +- docs/database-persistence.md | 6 +- docs/user-manual.md | 2 +- docs/versioning.md | 63 ++++++------ .../merovingian/database/PersistentStore.hpp | 20 ++-- .../merovingian/database/SqliteWritePool.hpp | 11 ++- src/database/AGENTS.md | 4 +- src/database/PersistentStore.cpp | 5 +- src/database/SqliteStore.cpp | 13 +-- .../test_security_audit_write_pool_flow.cpp | 95 ++++++++++++++++++- 22 files changed, 355 insertions(+), 84 deletions(-) create mode 100644 docs/adr/0834-sqlite-writes-share-one-pooled-connection.md create mode 100644 docs/adr/0835-the-version-changes-only-when-the-owner-asks.md diff --git a/.agent/skills/merovingian-review/SKILL.md b/.agent/skills/merovingian-review/SKILL.md index 2165f5383..1257f194b 100644 --- a/.agent/skills/merovingian-review/SKILL.md +++ b/.agent/skills/merovingian-review/SKILL.md @@ -1,6 +1,6 @@ --- name: merovingian-review -description: "Review a Merovingian pull request, branch or local diff against this project's binding rules: docs/coding-rules.md, the security coding rules, the per-module AGENTS.md invariants, the Matrix v1.19 spec, and the change obligations (CHANGELOG, docs, ADR, version bump, PR headings). It targets the defect classes this project has actually shipped. Use when asked to review a PR, branch, diff or commit in this repository, to check a change before merge, to verify a subagent's or another session's work, or to post review comments on a Merovingian PR." +description: "Review a Merovingian pull request, branch or local diff against this project's binding rules: docs/coding-rules.md, the security coding rules, the per-module AGENTS.md invariants, the Matrix v1.19 spec, and the change obligations (CHANGELOG, docs, ADR, version and PR headings). It targets the defect classes this project has actually shipped. Use when asked to review a PR, branch, diff or commit in this repository, to check a change before merge, to verify a subagent's or another session's work, or to post review comments on a Merovingian PR." --- # Merovingian review @@ -22,7 +22,7 @@ against this skill. | [references/rule-checks.md](references/rule-checks.md) | Grep-able rule checks and judgement checks from the coding and security rules | | [references/recurring-defects.md](references/recurring-defects.md) | Defect classes this project has shipped and fixed, as questions to ask of a diff | | [references/tests.md](references/tests.md) | Where a test belongs, required structure, what the gates catch and miss, how to run and read tests | -| [references/obligations.md](references/obligations.md) | CHANGELOG, docs, ADR, version bump, PR description: rules and commands | +| [references/obligations.md](references/obligations.md) | CHANGELOG, docs, ADR, version, PR description: rules and commands | ## Modes @@ -192,7 +192,7 @@ under Verification as not reviewed. | Tag | Meaning in this project | Blocks merge | |---|---|---| | **[Blocker]** | Wrong result, auth or signature bypass, a worker-trust violation, data loss, a crash, a deadlock or timeout, an unbounded cost reachable by an unprivileged client or remote, a weakened conformance assertion, a broken build or test | Yes | -| **[Major]** | Real defect on a plausible path; incomplete fix; behaviour without a test that fails if reverted; missing CHANGELOG, docs, ADR or version bump the project rules require | Yes, unless the author shows it is wrong | +| **[Major]** | Real defect on a plausible path; incomplete fix; behaviour without a test that fails if reverted; missing CHANGELOG, docs or ADR the project rules require, or a version change the owner did not ask for | Yes, unless the author shows it is wrong | | **[Minor]** | Correct but fragile, unclear or wasteful; a missing negative-path test on non-security code; doc drift | No | | **[Nit]** | Wording, naming, or style no tool owns | Never; collapse them | @@ -260,10 +260,10 @@ One or two sentences: what the change does, and whether the diff supports what i ## Obligations | Item | State | Evidence | -| CHANGELOG bullet in current version, right section | | | +| CHANGELOG bullet in the newest version's entry, right section | | | | Docs per docs/AGENTS.md table | | | | ADR (needed? numbered above all branches? index line?) | | | -| Version bump (or docs-only exemption) and all places agree | | | +| Version unchanged from the base unless the owner asked (ADR-0835), and all places agree | | | | PR description headings | | | ## Evidence log diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index 32e82193c..923ed6f25 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -103,6 +103,8 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that tests. `src/database/AGENTS.md#Security rules — non-negotiable` - Every BLOB write sets `BoundValue::binary`. - One transaction is one pooled lease. Never take a second lease while holding one: that deadlocks (ADR-0154). + SQLite has exactly one write connection; a change that lets it open more brings back writes refused after + SQLite's 5 s busy timeout (ADR-0834). - A read that combines several tables into one picture of a room runs in one read transaction (ADR-0161). Federated join writes are single transactions (ADR-0714). - Reads go by index, never scan. `PersistentStore` mutexes follow ADR-0517. A member added to `PersistentStore` diff --git a/.agent/skills/merovingian-review/references/obligations.md b/.agent/skills/merovingian-review/references/obligations.md index cb52df884..c66861ec3 100644 --- a/.agent/skills/merovingian-review/references/obligations.md +++ b/.agent/skills/merovingian-review/references/obligations.md @@ -13,24 +13,22 @@ ADR-0000/0001/0543/0740/0741. Only the formats are checked by tooling (`test_cha upgrading. - The bullet says what changed for the operator or client, not how, and ends with its ADR or finding ID. - `CHANGELOG-pre-release.md` is frozen (ADR-0740). Any diff to it is a finding. -- A docs-only branch adds its bullets to the **current** version's entry and does not bump. +- Every branch adds its bullets to the **newest** version's entry; it opens a new entry only when the owner asked + for a new version (ADR-0835). ## Version -- One bump per branch, BUILD + 1, except documentation-only changes (ADR-0464). `AGENTS.md` and coding-guidance - edits count as documentation. Any code, build, packaging or test change means the bump applies. +- The version changes only when the owner asks (ADR-0835). A branch whose version differs from its base's, with no + request from the owner in its PR or linked discussion, is a finding, whatever the branch changes. - Every place agrees with `meson.build`. The list is in `docs/versioning.md`: `src/main.cpp`, `src/db_migrate.cpp`, the FreeBSD manifest, the NetBSD Makefile, three RPM specs (each also with a new dated - `%changelog` entry), the `scripts/build-*.sh` scripts, and the CHANGELOG heading. -- The number must not be taken by another open branch. Check before approving. + `%changelog` entry when the version changes), the `scripts/build-*.sh` scripts, and the CHANGELOG heading. ```bash -git show origin/main:meson.build | grep -m1 "version:"; grep -m1 "version:" meson.build +git show :meson.build | grep -m1 "version:"; grep -m1 "version:" meson.build grep -n 'version = std::string_view' src/main.cpp src/db_migrate.cpp grep -n '^Version:' packaging/{rpm,rhel,opensuse}/merovingian.spec grep -nE '^VERSION=' scripts/build-*.sh -for r in $(git for-each-ref --format='%(refname)' refs/remotes/origin); do - git show "$r:meson.build" 2>/dev/null | grep -m1 -o "version: '[^']*'" | sed "s|^|$r |"; done | sort -k3 | tail ``` ## Docs diff --git a/AGENTS.md b/AGENTS.md index d4aae725e..a553e603b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,7 +27,9 @@ report any unresolved conflict or unmet requirement. See - Flag potential bugs or edge cases after the code explanation if relevant. - With every change, update the relevant docs. See [docs/AGENTS.md](docs/AGENTS.md) for the update table. - Before creating a new branch from main, pull from origin so that main is up to date. -- Bump the version number on creating a new branch, except for documentation-only changes. See versioning doc for all the places where the version number needs updating. +- Never change the version number unless the owner asks for it; a new branch keeps its base's version, and its + CHANGELOG bullets go in the newest version's entry. See the [bump policy](docs/versioning.md#bump-policy) and + [ADR-0835](docs/adr/0835-the-version-changes-only-when-the-owner-asks.md). - Update the docs when code change invalidates something. - Record a decision in the ADR register (`docs/adr/`) whenever you make one. A decision qualifies when a future reader would otherwise be likely to undo it diff --git a/CHANGELOG.md b/CHANGELOG.md index c685c194d..1cde09836 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) tokens for this server's SFU, judged by the main process and refused to a server the room's ACL denies (ADR-0831). * `delegate_delayed_leave` (MSC4195): this server sends a caller's delayed leave once LiveKit no longer shows them, checked every 30 s and sooner on LiveKit's signed webhook, kept across restarts (ADR-0832, ADR-0833). +* A branch no longer bumps the version: it changes only when the owner asks, and a change adds its bullets to the + newest version's entry here (ADR-0835). ## Security Fixes @@ -28,12 +30,15 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * `use_state_after`: a room forked at `since` now gets exactly what changed since what the client was told, read from an in-memory log of state changes, and so does a left room (ADR-0827). +* SQLite writes share one connection, whatever `database.pool_size` says: a second write connection waited for the + first's lock by polling, lost to its back-to-back commits and was refused after 5 s, failing the write (ADR-0834). ## Release notes Version 1.1.3 is in progress: a LiveKit token service built into the server for MatrixRTC calls, with delegated leaves, and an exact `state_after` on `/sync`. It adds migration 004 (`livekit_delegations`). After a restart, the first -`state_after` sync of each room with news carries its whole state once. +`state_after` sync of each room with news carries its whole state once. A SQLite server no longer refuses writes under +sustained write load, and `database.pool_size` now applies to PostgreSQL only. # Version 1.1.2 diff --git a/docs/AGENTS.md b/docs/AGENTS.md index dc1bb6946..caf3f462c 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -8,7 +8,7 @@ new documents. | Document | What to add/update | |---|---| -| `../CHANGELOG.md` (repo root) | Describe what changed. Add a new `# Version X.Y.Z` entry when the version changes, with exactly the headings `## Features`, `## Security Fixes`, `## Bug fixes` and `## Release notes`: bullets of two lines at most, and one short release-notes paragraph ([changelog format](versioning.md#changelog-format), [ADR-0741](adr/0741-each-changelog-version-has-features-security-fixes-bug-fixes-and-release-notes.md)). Documentation-only changes add bullets to the current version's entry without a bump. Never add to `../CHANGELOG-pre-release.md`, the frozen record of the 0.x series ([ADR-0740](adr/0740-the-changelog-starts-at-1-0-0-and-the-pre-release-entries-are-a-frozen-record.md)). | +| `../CHANGELOG.md` (repo root) | Describe what changed. Add a new `# Version X.Y.Z` entry only when the owner asks for a new version, with exactly the headings `## Features`, `## Security Fixes`, `## Bug fixes` and `## Release notes`: bullets of two lines at most, and one short release-notes paragraph ([changelog format](versioning.md#changelog-format), [ADR-0741](adr/0741-each-changelog-version-has-features-security-fixes-bug-fixes-and-release-notes.md)). Every other change, documentation-only or not, adds bullets to the newest version's entry and never changes the version ([ADR-0835](adr/0835-the-version-changes-only-when-the-owner-asks.md)). Never add to `../CHANGELOG-pre-release.md`, the frozen record of the 0.x series ([ADR-0740](adr/0740-the-changelog-starts-at-1-0-0-and-the-pre-release-entries-are-a-frozen-record.md)). | ## Update when the matching domain changes @@ -17,7 +17,7 @@ new documents. | `coding-rules.md` | A project-wide coding rule is added, changed, or removed. Maintain the rule here; the root `AGENTS.md` requires this document rather than copying its rules. | | `security-coding-rules.md` | A security-relevant rule is added, changed, or removed in any module `AGENTS.md` file | | `testing-standards.md` | A new testing convention is adopted | -| `versioning.md` | Version scheme changes; see also the version bump table | +| `versioning.md` | Version scheme or bump policy changes; see also its table of version locations | | `auth-identity.md` | Auth, session token, or identity changes | | `crypto-boundary.md` | Crypto interface, key management, or signing changes | | `database-persistence.md` | Schema changes (migrations), store interface changes | diff --git a/docs/adr/0154-pool-database-write-connections.md b/docs/adr/0154-pool-database-write-connections.md index 9723e3485..14c3bff0f 100644 --- a/docs/adr/0154-pool-database-write-connections.md +++ b/docs/adr/0154-pool-database-write-connections.md @@ -48,3 +48,8 @@ copies of it; `bootstrap_local_database` applies `database.pool_size` through a fresh connection dying mid-transaction always did. * A replaced SQLite file is not reopened by pooled handles until restart (they keep the file they opened, which is also what the DB-10 no-follow checks protected). + +## Links + +* Refined by [ADR-0834](0834-sqlite-writes-share-one-pooled-connection.md): SQLite writes use one pooled connection, + because the busy timeout does not absorb contention between this process's own connections. diff --git a/docs/adr/0464-documentation-only-changes-do-not-require-a-version-bump.md b/docs/adr/0464-documentation-only-changes-do-not-require-a-version-bump.md index 1f4401053..e5f3ce37b 100644 --- a/docs/adr/0464-documentation-only-changes-do-not-require-a-version-bump.md +++ b/docs/adr/0464-documentation-only-changes-do-not-require-a-version-bump.md @@ -1,6 +1,6 @@ # Documentation-only changes do not require a version bump -* Status: accepted +* Status: superseded by [ADR-0835](0835-the-version-changes-only-when-the-owner-asks.md) * Date: 2026-11-05 ## Context and Problem Statement @@ -32,3 +32,7 @@ The maintained policy is in [versioning](../versioning.md#bump-policy). ### Negative Consequences * Authors must check whether later changes make a branch more than documentation-only. + +## Links + +* Superseded by [ADR-0835](0835-the-version-changes-only-when-the-owner-asks.md) diff --git a/docs/adr/0647-versions-from-1-0-0-are-major-minor-build.md b/docs/adr/0647-versions-from-1-0-0-are-major-minor-build.md index 370816fd5..b1b0d6dea 100644 --- a/docs/adr/0647-versions-from-1-0-0-are-major-minor-build.md +++ b/docs/adr/0647-versions-from-1-0-0-are-major-minor-build.md @@ -1,6 +1,6 @@ # Versions from 1.0.0 are MAJOR.MINOR.BUILD -* Status: accepted +* Status: accepted; its per-branch `BUILD` increment is superseded by [ADR-0835](0835-the-version-changes-only-when-the-owner-asks.md) * Date: 2026-11-11 ## Context and Problem Statement @@ -43,4 +43,5 @@ Chosen option: "`MAJOR.MINOR.BUILD`". ## Links * Supersedes [ADR-0047](0047-keep-project-phase-out-of-the-version-string.md) +* Partly superseded by [ADR-0835](0835-the-version-changes-only-when-the-owner-asks.md): the per-branch `BUILD` increment * [docs/versioning.md](../versioning.md) diff --git a/docs/adr/0834-sqlite-writes-share-one-pooled-connection.md b/docs/adr/0834-sqlite-writes-share-one-pooled-connection.md new file mode 100644 index 000000000..a8de083e7 --- /dev/null +++ b/docs/adr/0834-sqlite-writes-share-one-pooled-connection.md @@ -0,0 +1,86 @@ +# SQLite writes share one pooled connection, whatever database.pool_size says + +* Status: accepted +* Date: 2026-11-18 + +Technical Story: the DB-7 scenario "concurrent writes to SQLite reuse at most database.pool_size connections" lost +three of its 64 writes in a full test run on a loaded VM: three writers logged `connection.rejected sqlite_code=5` +and `transaction.failed stage=open` together, 5.3 s after the store opened. Refines +[ADR-0154](0154-pool-database-write-connections.md), which assumed that SQLite's 5-second busy timeout absorbs +contention for its single writer lock. + +## Context and Problem Statement + +SQLite in rollback-journal mode (`journal_mode = DELETE`, pinned by every connection) has one writer at a time, +and a connection that wants a lock another connection holds does not queue for it. Its busy handler polls: it +sleeps 1, 2, 5 ... ms, then every 100 ms, and gives up after 5 s of sleeps (`sqliteDefaultBusyCallback`). A +committing connection holds PENDING or EXCLUSIVE for the whole commit, journal syncs, database write and database +sync included (`syncJournal` takes EXCLUSIVE before its first sync), and PENDING refuses every new SHARED lock. A +pooled connection that commits back to back therefore holds the lock nearly all the time. Its next lease takes the +lock again within microseconds, while another connection of the same process, polling every 100 ms by then, +rarely arrives in the gap. + +With `database.pool_size` connections allowed, the pool opened a second, third and fourth SQLite connection while +the first was committing. Each needs a SHARED lock to read the schema when it pins its pragmas, and each of +them polled against the first for 5 s and was refused: a write the client is told failed, because another write of +the same process was busy. The same refusal follows for a write that waits behind one slow write for longer than +5 s. + +Should SQLite writes keep up to `database.pool_size` connections? + +## Considered Options + +* **One SQLite write connection: the SQLite write pool's limit is always 1 (chosen).** +* Keep `database.pool_size` connections and lengthen the busy timeout, or retry a refused open. +* Keep `database.pool_size` connections and serialise their transactions with a mutex. +* Write-ahead logging (`journal_mode = WAL`). + +## Decision Outcome + +Chosen option: one connection, because SQLite runs one write transaction at a time anyway, so a second connection +adds no parallelism and only a second place to wait, and that place is SQLite's polling, unfair, time-limited +busy handler. With one connection, every write of this process waits in the pool, on a condition variable that +wakes the next writer when a lease ends and never times out, which is how ADR-0154 already waits for a PostgreSQL +connection. + +* `SqliteWritePool` holds a `ConnectionPool` of limit 1, and `set_write_connection_limit` (that is, + `database.pool_size`) changes only the PostgreSQL pool. `write_connections_opened` reports 1 for SQLite unless a + connection could not be opened. +* SQLite's busy timeout still governs this process's reads against its writer, and every lock another process + takes (`merovingian-db-migrate`, an operator's `sqlite3` shell). A read can still be refused after 5 s of + back-to-back commits; that is not changed here. + +### Positive Consequences + +* No write is refused because another write of this process holds SQLite's lock, however long it holds it. +* A waiting writer is woken when the lease ends rather than at its next poll, and does no busy polling. + +### Negative Consequences + +* A write that never ends blocks every later write instead of failing them after 5 s each. A write is one + transaction of statements built before the lease is taken, so nothing in it waits on anything but SQLite. + +## Pros and Cons of the Options + +### Lengthen the busy timeout, or retry a refused open + +* Good, because it is a one-line change. +* Bad, because the wait stays unfair: a longer budget lowers the odds of a refusal under load but keeps it, and + every waiter polls. It raises the tolerance instead of removing the contention. + +### Several connections, serialised by a mutex + +* Bad, because the connections would never be used at once; the extra handles are idle weight, and + `database.pool_size` would claim a parallelism that does not exist. + +### Write-ahead logging + +* Good, because readers would no longer block a writer or be blocked by one. +* Bad, because the read-only connections refuse WAL on purpose + ([ADR-0157](0157-never-open-a-sqlite-database-file-outside-sqlite.md): a read-only connection can still write + the WAL index), and the pinned journal mode is a durability decision (#447). Changing them is a decision of its + own. + +## Links + +* Refines [ADR-0154](0154-pool-database-write-connections.md) diff --git a/docs/adr/0835-the-version-changes-only-when-the-owner-asks.md b/docs/adr/0835-the-version-changes-only-when-the-owner-asks.md new file mode 100644 index 000000000..77f5f8c78 --- /dev/null +++ b/docs/adr/0835-the-version-changes-only-when-the-owner-asks.md @@ -0,0 +1,66 @@ +# The version changes only when the owner asks + +* Status: accepted +* Date: 2026-11-18 + +Technical Story: the project owner's instruction of 2026-11-18, while a SQLite fix was being stacked on four open +pull requests (1.1.0 to 1.1.3): "No more auto incrementing versions. We'll only do that when I ask for it." + +## Context and Problem Statement + +Every branch with a code, build, packaging or test change incremented `BUILD` when it was created +([ADR-0647](0647-versions-from-1-0-0-are-major-minor-build.md)); documentation-only branches did not +([ADR-0464](0464-documentation-only-changes-do-not-require-a-version-bump.md)). With several branches open at once, +each took the next free number, and every rebase of a stacked branch conflicted in the sixteen places that hold the +version and in the CHANGELOG, whose entries git interleaved. The numbers then said how many branches had been made, +not what a release contains. When does the version change? + +## Considered Options + +* **Only when the owner asks; every change adds its CHANGELOG bullets to the newest version's entry (chosen).** +* Keep one `BUILD` increment per branch. +* Increment once per merge to `main` instead of per branch. + +## Decision Outcome + +Chosen option: the owner decides, because the owner asked for it, and a version is then a release decision rather than +a by-product of branching. + +* No branch changes the version on its own, whatever it changes. A branch keeps the version of the branch it is based + on, in every location `docs/versioning.md` lists. +* Every change, documentation-only or not, adds its bullets to the newest `# Version` entry of `CHANGELOG.md` under the + existing headings, and updates that entry's release-notes paragraph when an operator needs to know about it. The + format rules ([ADR-0741](0741-each-changelog-version-has-features-security-fixes-bug-fixes-and-release-notes.md)) and + the check that the newest entry is the version `meson.build` declares are unchanged. +* When the owner asks for a version, that change sets the version the owner names in every location together, adds its + `%changelog` entries to the three RPM specs, and opens a new CHANGELOG entry above the previous one. +* This supersedes ADR-0464, whose exemption no longer has a rule to except, and the per-branch increment of ADR-0647. + ADR-0647's scheme stands: versions are `MAJOR.MINOR.BUILD`, and `MINOR` and `MAJOR` change when the owner decides. + +### Positive Consequences + +* Parallel and stacked branches no longer conflict over the version, and the CHANGELOG has one entry to add to. + +### Negative Consequences + +* Two builds from different commits can report the same version until the owner asks for a new one. The commit, not + the version string, identifies an unreleased build. + +## Pros and Cons of the Options + +### One increment per branch + +* Good, because every branch's build reports a different version. +* Bad, because of the conflicts and meaningless numbers above, and because the owner no longer wants it. + +### One increment per merge to main + +* Good, because only merged work moves the number. +* Bad, because a merge still picks a number nobody chose for a release, and someone has to make the change at merge + time, which the project has no step for. + +## Links + +* Supersedes [ADR-0464](0464-documentation-only-changes-do-not-require-a-version-bump.md) +* Partly supersedes [ADR-0647](0647-versions-from-1-0-0-are-major-minor-build.md): the per-branch `BUILD` increment +* [docs/versioning.md](../versioning.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index a045c32a5..a1c0a73e0 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -457,7 +457,7 @@ * [0510 - The test binaries hash passwords at minimum cost](0510-the-test-binaries-hash-passwords-at-minimum-cost.md) * [0462 - Use std::invoke for callable dispatch and immediate lambdas](0462-use-std-invoke-for-callable-dispatch-and-immediate-lambdas.md) * [0463 - Confine unavoidable C API pointers to RAII wrappers](0463-confine-unavoidable-c-api-pointers-to-raii-wrappers.md) -* [0464 - Documentation-only changes do not require a version bump](0464-documentation-only-changes-do-not-require-a-version-bump.md) +* [0464 - Documentation-only changes do not require a version bump](0464-documentation-only-changes-do-not-require-a-version-bump.md) — Superseded by ADR-0835: no branch bumps the version, so there is nothing to exempt * [0465 - Root agent guidance requires the coding rules without copying them](0465-root-agent-guidance-requires-the-coding-rules-without-copying-them.md) * [0466 - Define one class or struct per file](0466-define-one-class-or-struct-per-file.md) * [0467 - Type filenames match the type name exactly](0467-type-filenames-match-the-type-name-exactly.md) @@ -559,7 +559,7 @@ * [0634 - A share of the push delivery budget is kept for gateways that answer, and one host carries an eighth of it](0634-a-share-of-the-push-delivery-budget-is-kept-for-gateways-that-answer-and-a-host-carries-an-eighth.md) * [0635 - An inbound federation origin is asked about once at a time, and its decision is kept for a short time](0635-an-inbound-federation-origin-is-asked-about-once-at-a-time-and-its-decision-is-kept-for-a-short-time.md) * [0636 - A blob row is deleted with its last reference, and a removed record holds no reference](0636-a-blob-row-is-deleted-with-its-last-reference-and-a-removed-record-holds-none.md) -* [0647 - Versions from 1.0.0 are MAJOR.MINOR.BUILD](0647-versions-from-1-0-0-are-major-minor-build.md) +* [0647 - Versions from 1.0.0 are MAJOR.MINOR.BUILD](0647-versions-from-1-0-0-are-major-minor-build.md) — Partly superseded by ADR-0835: the version changes only when the owner asks, not once per branch * [0648 - The Complement blocker is waived for 1.0.0 only](0648-the-complement-blocker-is-waived-for-1-0-0-only.md) — Extended by ADR-0744: 1.0.1 is waived too * [0731 - A spawned worker gets no terminal, and no sandbox profile allows TIOCSTI or TIOCLINUX](0731-a-spawned-worker-gets-no-terminal-and-no-sandbox-profile-allows-tiocsti.md) * [0732 - Every published attestation check pins the signing workflow and the ref](0732-every-published-attestation-check-pins-the-signing-workflow-and-the-ref.md) — Partly superseded by ADR-0742: every published file is attested by packages.yml @@ -712,3 +712,5 @@ * [0831 - A federated LiveKit token request is judged by main and answered subscribe-only](0831-a-federated-livekit-token-request-is-judged-by-main-and-answered-subscribe-only.md) * [0832 - A delegated delayed leave is restarted while LiveKit shows the participant, and sent once it does not](0832-a-delegated-delayed-leave-is-restarted-while-livekit-shows-the-participant-and-sent-once-it-does-not.md) * [0833 - The LiveKit webhook is served on the client listener and trusted only to prompt a check](0833-the-livekit-webhook-is-served-on-the-client-listener-and-trusted-only-to-prompt-a-check.md) +* [0834 - SQLite writes share one pooled connection, whatever database.pool_size says](0834-sqlite-writes-share-one-pooled-connection.md) +* [0835 - The version changes only when the owner asks](0835-the-version-changes-only-when-the-owner-asks.md) diff --git a/docs/coding-rules.md b/docs/coding-rules.md index e3f442e90..425e68f8c 100644 --- a/docs/coding-rules.md +++ b/docs/coding-rules.md @@ -239,9 +239,10 @@ defects on executed paths; a clean run does not prove that all paths are safe. bug fix, or experiment. Never make development changes on `main`. Follow the branch prefix required by the project or tool instructions, and submit changes through a pull request. -- Documentation-only changes do not require a version bump. For other changes, - increment the version once when creating the branch. Update all locations in - [versioning](versioning.md) together. +- Do not change the version unless the owner asks for it; a branch keeps the + version of its base. When the owner asks, update all locations in + [versioning](versioning.md) together. See + [ADR-0835](adr/0835-the-version-changes-only-when-the-owner-asks.md). - Update `CHANGELOG.md` for every change, in the [changelog format](versioning.md#changelog-format). Use the [documentation update table](AGENTS.md) to find the other required updates. diff --git a/docs/database-persistence.md b/docs/database-persistence.md index a2ec03e18..137aee4b3 100644 --- a/docs/database-persistence.md +++ b/docs/database-persistence.md @@ -1353,7 +1353,11 @@ membership is `invite` or `knock`, or deletes it; a new reader must check the me ### Write connection pool (DB-7, 0.12.26) Persisted writes reuse connections from a per-store `ConnectionPool` instead of opening one per -transaction: at most `database.pool_size` (16) are in use at once, and a write waits for a free one. +transaction, and a write waits for a free one. On PostgreSQL at most `database.pool_size` (16) are in use at +once. On SQLite there is always exactly one write connection, whatever `database.pool_size` says (ADR-0834): +SQLite runs one write transaction at a time, and a second connection of this process waiting for the first's +lock would poll SQLite's busy handler, lose to the first connection's back-to-back commits and be refused after +5 s. Writers wait in the pool instead, without a time limit, and are woken in turn. PostgreSQL connections assume the runtime role once when opened; a pooled one is reused only while idle (`PQTRANS_IDLE`) with nothing to read on its socket, so one the server has closed is replaced. SQLite connections keep their pragmas and `foreign_keys=ON`. Reads, migrations and the worker's read-only store diff --git a/docs/user-manual.md b/docs/user-manual.md index f671a47bb..262b4ac65 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -1296,7 +1296,7 @@ federation port `8448`. | `database.role` | `runtime` | Use `migration` only with `merovingian-db-migrate`. | | `database.migration_role` | (empty) | PostgreSQL role assumed for the DDL/migration phase only. Must be set together with `database.runtime_role`. | | `database.runtime_role` | (empty) | PostgreSQL role assumed to serve requests, dropping DDL rights. Both empty issues no `SET ROLE`, leaving an existing single-role deployment unchanged. | -| `database.pool_size` | `16` | Database connections persisted writes keep and use at once; a write waits for a free one rather than opening another (DB-7, ADR-0154). Requires restart. | +| `database.pool_size` | `16` | PostgreSQL connections persisted writes keep and use at once; a write waits for a free one rather than opening another (DB-7, ADR-0154). SQLite writes always share one connection, since SQLite runs one write at a time (ADR-0834). Requires restart. | | `database.sqlite_path` | `/var/lib/merovingian/merovingian.sqlite3` | Path for SQLite single-file store. Commented out in the shipped example, which defaults to PostgreSQL. The file itself must not be a symlink and is created `0600`; missing directories are created `0700`. Directories that already exist may be symlinks (for example `/var/lib/merovingian` pointing at a data volume). | #### PostgreSQL TLS admission diff --git a/docs/versioning.md b/docs/versioning.md index d1627a937..9ce94d12c 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -5,13 +5,10 @@ From 1.0.0 Merovingian uses **`MAJOR.MINOR.BUILD`** ([ADR-0647](adr/0647-versions-from-1-0-0-are-major-minor-build.md)). -`BUILD` is the working counter: feature, fix, and packaging branches increment -it by one, exactly as `PATCH` did before 1.0.0. The bump policy below is -unchanged. Documentation-only changes do not require a version bump -([ADR-0464](adr/0464-documentation-only-changes-do-not-require-a-version-bump.md)). - -`MINOR` and `MAJOR` change only when the owner decides. The decision states the -version that follows. +No part of the version changes on its own: `BUILD`, `MINOR` and `MAJOR` all +change only when the owner asks, and the request states the version that follows +([ADR-0835](adr/0835-the-version-changes-only-when-the-owner-asks.md)). See the +bump policy below. **Project phase is declared in `README.md` and `CHANGELOG.md`, never encoded in the version number** ([ADR-0647](adr/0647-versions-from-1-0-0-are-major-minor-build.md), which restates the rule @@ -28,26 +25,34 @@ long, and a new series did not restart at `.0` (`0.9.25` to `0.10.1`, `0.10.63` to `0.11.4`). `1.0.0` was cut when the project reached production. Beta was declared at `v0.10.59`. These rules no longer apply. -## Bump policy +From 1.0.0 until 2026-11-18, every branch with a code, build, packaging or test +change incremented `BUILD` once when it was created, and documentation-only +branches did not ([ADR-0647](adr/0647-versions-from-1-0-0-are-major-minor-build.md), +[ADR-0464](adr/0464-documentation-only-changes-do-not-require-a-version-bump.md)). +That is why 1.0.x and 1.1.x moved one number per branch. It no longer applies. -**One bump per branch, when the branch is created, except for documentation-only changes.** Update `CHANGELOG.md` -and every version location below together before the branch's first commit. -Do not increment again on intermediate commits. Before raising the PR, verify -that the version remains consistent with the base branch; if another branch -has used that version in the meantime, update all locations together to the -next available build number. There is no separate merge-time bump. +## Bump policy -The one exception is the `release.yml` fix that let 1.0.0 publish: the owner -kept it at 1.0.0 and moved the unpublished `v1.0.0` tag to it +**The version changes only when the owner asks for it** +([ADR-0835](adr/0835-the-version-changes-only-when-the-owner-asks.md)). No branch +changes it on its own, whatever the branch changes: code, build, packaging, +tests or documentation. A branch keeps the version of the branch it is based on, +in every location below. + +Every change adds its notes as bullets to the newest `# Version` entry of +`CHANGELOG.md`, in the [changelog format](#changelog-format): new behaviour or +guidance under `Features`, a vulnerability under `Security Fixes`, any other +correction under `Bug fixes`. Update that entry's release-notes paragraph when an +operator needs to know about the change. + +When the owner asks for a version, that change sets the version the owner names +in every location below in one commit, adds the dated `%changelog` entry to each +RPM spec, and opens a new `# Version` entry at the top of `CHANGELOG.md` for the +changes that follow. + +The `release.yml` fix that let 1.0.0 publish kept 1.0.0 and moved the +unpublished `v1.0.0` tag to it ([ADR-0651](adr/0651-the-v1-0-0-tag-moves-to-the-release-workflow-fix-without-a-version-bump.md)). -It is not a precedent. - -For a documentation-only branch, keep the current version and add the change -notes as bullets in its `CHANGELOG.md` entry: new guidance under `Features`, a -correction under `Bug fixes`. Changes to coding -guidance and `AGENTS.md` files are documentation changes. If the branch later -includes code, build, or packaging changes, apply the bump policy before -committing those changes. ## Changelog format @@ -136,19 +141,19 @@ than the others. a new dated entry for every version — the `Version:` field alone is not sufficient for `rpmbuild` to accept the spec. - Historical version strings in `CHANGELOG.md`, `CHANGELOG-pre-release.md` and every spec - `%changelog` are records, not live values; do not edit them when bumping. + `%changelog` are records, not live values; do not edit them when the version changes. - `CHANGELOG.md` starts at 1.0.0. The 0.x entries are in `CHANGELOG-pre-release.md`, a frozen record that nothing is added to ([ADR-0740](adr/0740-the-changelog-starts-at-1-0-0-and-the-pre-release-entries-are-a-frozen-record.md)). - `tests/tooling/test_packages_workflow.py` enforces that every file in the table above carries the current `meson.build` version. Run it (or `python build.py - vm`) after a bump to catch any location that was missed. + vm`) after a version change to catch any location that was missed. ## Release process 1. Update `main` from `origin`, then create a feature or fix branch from it. -2. Unless the changes are documentation-only, increment the build number in every location above and add its changelog section. -3. Make the changes and keep that version for intermediate commits. -4. Before raising the PR, check version consistency and conflicts with the base branch. +2. Make the changes without touching the version, and add their bullets to the newest `CHANGELOG.md` entry. +3. Only when the owner asks for a version: set it in every location above and open its changelog entry. +4. Before raising the PR, check that the version and the CHANGELOG agree with the base branch and do not conflict. 5. Raise a PR. CI builds the configured platform artifacts and runs the test suite; see [platform-support.md](platform-support.md) for the artifact matrix. 6. Merge to `main`. The `publish-latest` CI job replaces the rolling GitHub diff --git a/include/merovingian/database/PersistentStore.hpp b/include/merovingian/database/PersistentStore.hpp index 7c4a77fa5..5a30fc22e 100644 --- a/include/merovingian/database/PersistentStore.hpp +++ b/include/merovingian/database/PersistentStore.hpp @@ -259,10 +259,10 @@ struct PersistentStoreOpenResult; namespace detail { // DB-7, ADR-0154: each backend's pool of write connections, defined in its - // own source file. Shared, not copied, by copies of a store. + // own source file. Shared, not copied, by copies of a store. Only the + // PostgreSQL pool's limit can be set: SQLite's is one (ADR-0834). struct SqliteWritePool; struct PostgresqlWritePool; - auto set_write_pool_limit(SqliteWritePool& pool, std::uint32_t limit) -> void; auto set_write_pool_limit(PostgresqlWritePool& pool, std::uint32_t limit) -> void; [[nodiscard]] auto write_pool_opened(SqliteWritePool const& pool) -> std::uint64_t; [[nodiscard]] auto write_pool_opened(PostgresqlWritePool const& pool) -> std::uint64_t; @@ -659,10 +659,11 @@ struct PersistentStore final // stripe locks because capture access is independent of any room. Held by // value (ADR-0517) so PersistentStore stays copyable and moveable; a copy gets its own mutex. core::CopyableMutex statement_capture_mutex{}; - // DB-7, ADR-0154: persisted writes reuse at most this many connections - // (database.pool_size, applied by set_write_connection_limit), instead of - // opening one per transaction. The pool of the store's backend is created - // when the store is opened; copies share it. + // DB-7, ADR-0154: persisted writes to PostgreSQL reuse at most this many + // connections (database.pool_size, applied by set_write_connection_limit), + // instead of opening one per transaction; SQLite writes reuse one + // (ADR-0834). The pool of the store's backend is created when the store is + // opened; copies share it. std::uint32_t write_connection_limit{16U}; std::shared_ptr sqlite_write_pool{}; // SHARED_PTR: reviewed - shared by store copies. std::shared_ptr // SHARED_PTR: reviewed - shared by store copies. @@ -744,9 +745,10 @@ static_assert(std::is_nothrow_move_constructible_v && [[nodiscard]] auto validate_persistent_store(PersistentStore const& store) -> MigrationValidationResult; [[nodiscard]] auto commit_persistent_transaction(PersistentStore& store, std::vector const& statements) -> bool; -// DB-7, ADR-0154: caps the connections persisted writes keep and use at once -// (database.pool_size). A write waits for a free connection rather than opening -// another. Takes effect for the next write. +// DB-7, ADR-0154: caps the PostgreSQL connections persisted writes keep and use +// at once (database.pool_size). A write waits for a free connection rather than +// opening another. Takes effect for the next write. SQLite writes always share +// one connection and ignore it (ADR-0834). auto set_write_connection_limit(PersistentStore& store, std::uint32_t limit) -> void; // Connections ever opened for persisted writes (both backends' pools). [[nodiscard]] auto write_connections_opened(PersistentStore const& store) -> std::uint64_t; diff --git a/include/merovingian/database/SqliteWritePool.hpp b/include/merovingian/database/SqliteWritePool.hpp index 045c9072c..3a6b6ab7c 100644 --- a/include/merovingian/database/SqliteWritePool.hpp +++ b/include/merovingian/database/SqliteWritePool.hpp @@ -10,10 +10,17 @@ namespace merovingian::database::detail { +// ADR-0834: one SQLite write connection, whatever database.pool_size says. +// SQLite runs one write transaction at a time; a second connection of this +// process would wait for the first's lock in SQLite's polling busy handler, +// lose to its back-to-back commits and be refused after 5 s. Writers wait in +// the pool instead, without a time limit. struct SqliteWritePool final { - explicit SqliteWritePool(std::uint32_t limit) - : pool{limit} + static constexpr auto connection_limit = std::uint32_t{1U}; + + SqliteWritePool() + : pool{connection_limit} { } ConnectionPool pool; diff --git a/src/database/AGENTS.md b/src/database/AGENTS.md index 5d935b3eb..76e143364 100644 --- a/src/database/AGENTS.md +++ b/src/database/AGENTS.md @@ -61,7 +61,9 @@ Manages schema migrations and provides a dual-backend (SQLite / PostgreSQL) pers `actor`, `target` and `reason` to 255 bytes on a UTF-8 boundary (`observability::bounded_utf8`). 7. **Persisted writes lease a pooled connection; nothing else opens one per write.** `commit_persistent_transaction` - goes through the store's `ConnectionPool` (at most `database.pool_size` in use, ADR-0154). Hold a lease for exactly + goes through the store's `ConnectionPool` (at most `database.pool_size` in use on PostgreSQL, ADR-0154; exactly one + on SQLite, ADR-0834: never give SQLite a second write connection, whose wait for the first's lock is SQLite's + polling busy handler, which loses to back-to-back commits and refuses the write after 5 s). Hold a lease for exactly one transaction and never take another lease while holding one, or writers can deadlock waiting for each other. A PostgreSQL connection is reused only while idle with nothing to read on its socket. Main's reads for a federation worker (room list, room snapshots) lease a reader from `SnapshotReaderPool`, opened diff --git a/src/database/PersistentStore.cpp b/src/database/PersistentStore.cpp index 49599829e..2b75aa14d 100644 --- a/src/database/PersistentStore.cpp +++ b/src/database/PersistentStore.cpp @@ -536,10 +536,7 @@ namespace auto set_write_connection_limit(PersistentStore& store, std::uint32_t limit) -> void { store.write_connection_limit = std::max(limit, std::uint32_t{1U}); - if (store.sqlite_write_pool != nullptr) - { - detail::set_write_pool_limit(*store.sqlite_write_pool, store.write_connection_limit); - } + // The SQLite write pool keeps its one connection (ADR-0834). if (store.postgresql_write_pool != nullptr) { detail::set_write_pool_limit(*store.postgresql_write_pool, store.write_connection_limit); diff --git a/src/database/SqliteStore.cpp b/src/database/SqliteStore.cpp index 66e92f90a..53dd1de07 100644 --- a/src/database/SqliteStore.cpp +++ b/src/database/SqliteStore.cpp @@ -1670,11 +1670,6 @@ namespace namespace detail { - auto set_write_pool_limit(SqliteWritePool& pool, std::uint32_t limit) -> void - { - pool.pool.set_limit(limit); - } - auto write_pool_opened(SqliteWritePool const& pool) -> std::uint64_t { return pool.pool.opened_total(); @@ -1768,7 +1763,7 @@ auto open_sqlite_persistent_store(std::string const& path, TableLoadProfile prof store.sqlite_read_only = read_only; if (!read_only) { - store.sqlite_write_pool = std::make_shared(store.write_connection_limit); + store.sqlite_write_pool = std::make_shared(); } store.schema = load_schema_state(sqlite); log_diagnostic("store.schema_loaded", @@ -1923,8 +1918,10 @@ namespace detail auto connection = open_writer(); return connection.has_value() && execute_transaction(**connection, statements); } - // DB-7, ADR-0154: reuse a pooled connection; a SQLite handle stays usable - // after a failed transaction (execute_transaction rolls back). + // DB-7, ADR-0154: reuse the pooled connection; a SQLite handle stays usable + // after a failed transaction (execute_transaction rolls back). There is one + // (ADR-0834), so a writer waits here for the one before it, never in + // SQLite's busy handler against another connection of this process. auto lease = store.sqlite_write_pool->pool.acquire(open_writer, [](SqliteConnection const&) { return true; }); diff --git a/tests/integration/test_security_audit_write_pool_flow.cpp b/tests/integration/test_security_audit_write_pool_flow.cpp index 05637d98f..f592ee446 100644 --- a/tests/integration/test_security_audit_write_pool_flow.cpp +++ b/tests/integration/test_security_audit_write_pool_flow.cpp @@ -3,16 +3,20 @@ // DB-7 (29 Sep 2026 audit): every persisted write opened a fresh database // connection (SQLite open with its path checks, or a PostgreSQL connect and // SET ROLE) while the runtime mutex was usually held. Writes now reuse at most -// database.pool_size connections (ADR-0154). +// database.pool_size connections on PostgreSQL (ADR-0154) and one on SQLite +// (ADR-0834). #include "../support/TempDirectory.hpp" #include "merovingian/database/ExaminedRows.hpp" #include "merovingian/database/PersistentStore.hpp" #include "merovingian/database/PreparedStatement.hpp" #include "merovingian/database/PostgresqlStore.hpp" +#include "merovingian/database/SqliteConnectionDeleter.hpp" +#include "merovingian/database/SqliteWritePool.hpp" #include #include +#include #include #include @@ -22,6 +26,7 @@ #include #include #include +#include #include #include #include @@ -34,6 +39,28 @@ namespace constexpr auto writers = 64U; constexpr auto limit = std::uint32_t{4U}; +// SQLite's busy handler gives up after 5 s (busy_timeout_ms in SqliteStore.cpp); +// a write held this long would outlast it by 2 s. +constexpr auto longer_than_sqlite_busy_timeout = std::chrono::milliseconds{7000}; + +// A plain read-write connection to the store's file, for a test that holds +// SQLite's write lock itself. Opened by SQLite, as ADR-0157 requires. +[[nodiscard]] auto open_raw_writer(std::filesystem::path const& path) + -> std::optional +{ + auto* raw = static_cast(nullptr); + if (sqlite3_open_v2(path.string().c_str(), &raw, SQLITE_OPEN_READWRITE, nullptr) != SQLITE_OK) + { + sqlite3_close(raw); + return std::nullopt; + } + return merovingian::database::SqliteConnection{raw}; +} + +[[nodiscard]] auto run_sql(merovingian::database::SqliteConnection const& connection, char const* sql) -> bool +{ + return sqlite3_exec(connection.get(), sql, nullptr, nullptr, nullptr) == SQLITE_OK; +} [[nodiscard]] auto insert_room(std::string const& room_id) -> merovingian::database::PreparedStatement { @@ -150,10 +177,12 @@ auto terminate_other_backends(std::string const& uri) -> bool } // namespace -SCENARIO("DB-7 concurrent writes to SQLite reuse at most database.pool_size connections", +// SQLite runs one write at a time, so its writes share one connection whatever +// database.pool_size allows (ADR-0834). +SCENARIO("DB-7 concurrent writes to SQLite share one connection, whatever database.pool_size allows", "[db7][integration][database]") { - GIVEN("a real SQLite store whose write connections are limited to four") + GIVEN("a real SQLite store whose write connections database.pool_size would limit to four") { auto const directory = TemporaryDirectory{}; auto const path = directory.path() / "db7.sqlite3"; @@ -166,10 +195,10 @@ SCENARIO("DB-7 concurrent writes to SQLite reuse at most database.pool_size conn { auto const committed = commit_concurrently(store, "!db7-sqlite-"); - THEN("every write is durable and no more than four connections were ever opened for them") + THEN("every write is durable and one connection was opened for all of them") { CHECK(committed == writers); - CHECK(merovingian::database::write_connections_opened(store) <= limit); + CHECK(merovingian::database::write_connections_opened(store) == 1U); auto const reopened = merovingian::database::open_sqlite_persistent_store(path.string()); REQUIRE(reopened.ok); CHECK(reopened.store.rooms.size() == writers); @@ -178,6 +207,62 @@ SCENARIO("DB-7 concurrent writes to SQLite reuse at most database.pool_size conn } } +// SQLite's lock wait is a busy handler that polls, backing off to every 100 ms, +// and gives up after 5 s. A second write connection of this process waiting for +// the first one's lock polls against it, and is refused if the first holds the +// lock for longer: a single slow write, or one connection committing back to back +// (every journal and database sync runs under EXCLUSIVE), which is how the DB-7 +// scenario above lost three writes under load on 2026-11-17 (ADR-0834). +SCENARIO("A SQLite write waits for another write of this process for longer than SQLite's busy timeout", + "[db7][integration][database]") +{ + GIVEN("a real SQLite store allowed four write connections, one of whose writes holds SQLite's write lock") + { + auto const directory = TemporaryDirectory{}; + auto const path = directory.path() / "db7-held.sqlite3"; + auto opened = merovingian::database::open_sqlite_persistent_store(path.string()); + REQUIRE(opened.ok); + auto& store = opened.store; + merovingian::database::set_write_connection_limit(store, limit); + REQUIRE(store.sqlite_write_pool != nullptr); + // The held write leases a slot of the store's own pool, as a write of the + // store does, but on a connection this test drives. + auto held = store.sqlite_write_pool->pool.acquire( + [&path] { + return open_raw_writer(path); + }, + [](merovingian::database::SqliteConnection const&) { + return true; + }); + REQUIRE(held.has_value()); + held->discard(); + REQUIRE(run_sql(held->get(), "BEGIN IMMEDIATE")); + REQUIRE(run_sql(held->get(), "INSERT INTO rooms (room_id, creator_user_id, directory_public) VALUES " + "('!db7-held:example.org', '@db7:example.org', 'false')")); + + WHEN("a second write starts and the first commits only after SQLite's busy timeout has passed") + { + auto second = std::async(std::launch::async, [&store] { + return merovingian::database::commit_persistent_transaction(store, + {insert_room("!db7-waiting:example.org")}); + }); + std::this_thread::sleep_for(longer_than_sqlite_busy_timeout); + auto const first_committed = run_sql(held->get(), "COMMIT"); + held.reset(); + auto const second_committed = second.get(); + + THEN("the second write waited for the first instead of being refused, and both are durable") + { + CHECK(first_committed); + CHECK(second_committed); + auto const reopened = merovingian::database::open_sqlite_persistent_store(path.string()); + REQUIRE(reopened.ok); + CHECK(reopened.store.rooms.size() == 2U); + } + } + } +} + SCENARIO("DB-7 concurrent writes to PostgreSQL reuse at most database.pool_size connections, and replace dead ones", "[db7][integration][database][postgresql]") {