Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
f9d3743
Bump the version to 1.1.3 and open its changelog entry
James-Chapman Nov 17, 2026
93d4219
Measure state_after deltas from an in-memory log of resolved state ch…
James-Chapman Nov 17, 2026
543e99f
Sign and verify LiveKit HS256 tokens through typed functions in the c…
James-Chapman Nov 17, 2026
055855a
Add a one-room roomAdmin LiveKit token signer for GetParticipant
James-Chapman Nov 17, 2026
8815e25
Serve MSC4195 LiveKit tokens from a built-in token service
James-Chapman Nov 17, 2026
eef0fa6
Classify the LiveKit token relay in the outbound answer trust table
James-Chapman Nov 17, 2026
dcd9d66
Relay the inbound federation LiveKit token route through the worker r…
James-Chapman Nov 17, 2026
15cb35d
Add migration 004 and the LiveKit delegations table, store functions …
James-Chapman Nov 17, 2026
d9af211
Delegate delayed MatrixRTC leaves to the token service and accept the…
James-Chapman Nov 17, 2026
10528a7
Check the room's server ACL for LiveKit tokens and bind each check to…
James-Chapman Nov 17, 2026
35b27f4
Link ADR-0830 to ADR-0079 by its real file name
James-Chapman Nov 17, 2026
e74cc04
Pass the unsafe source gate: reword a comment and mark the reviewed s…
James-Chapman Nov 17, 2026
f589be8
Guard the LiveKit secret from the worker, schedule checks fairly, ind…
James-Chapman Nov 17, 2026
b48c7f4
Cover the LiveKit token, request builder and perform refusal paths
James-Chapman Nov 17, 2026
654c68e
Cover the wired LiveKit token provider, the relay refusals and the wo…
James-Chapman Nov 17, 2026
9e53871
Cover the delegation job's and webhook's refusal and ignore paths
James-Chapman Nov 17, 2026
d8f9543
Say what the LiveKit call deadline bounds and what it cannot
James-Chapman Nov 17, 2026
955350c
Split the LiveKit flow scenarios CodeQL found over 100 lines
James-Chapman Nov 17, 2026
a20f5da
Give SQLite writes one pooled connection, and change the version only…
James-Chapman Nov 18, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .agent/skills/merovingian-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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 |

Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
14 changes: 6 additions & 8 deletions .agent/skills/merovingian-review/references/obligations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <base>: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
Expand Down
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
37 changes: 37 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,43 @@ 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

* 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 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

* 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).
* 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: the exchange gets only the time the lookup left,
and none starts once the deadline has passed (ADR-0830).

## Bug fixes

* `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. A SQLite server no longer refuses writes under
sustained write load, and `database.pool_size` now applies to PostgreSQL only.

# Version 1.1.2

## Features
Expand Down
18 changes: 16 additions & 2 deletions config/merovingian.conf.bsd.example
Original file line number Diff line number Diff line change
Expand Up @@ -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 /
Expand Down
18 changes: 16 additions & 2 deletions config/merovingian.conf.example
Original file line number Diff line number Diff line change
Expand Up @@ -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 /
Expand Down
4 changes: 2 additions & 2 deletions docs/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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 |
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
5 changes: 5 additions & 0 deletions docs/adr/0154-pool-database-write-connections.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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)
3 changes: 2 additions & 1 deletion docs/adr/0647-versions-from-1-0-0-are-major-minor-build.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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)
Original file line number Diff line number Diff line change
@@ -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
Expand Down
Loading
Loading