Implementation of MSC4195: MatrixRTC Transport using LiveKit Backend by fkwp · Pull Request #128 · element-hq/lk-jwt-service

fkwp · 2025-11-04T14:33:02Z

As part of Matrix 2.0 Spec the MatrixRTC Authorization Service implements MSC4195: MatrixRTC Transport using LiveKit Backend

According the MSC4195 the JWT request endpoint is now /get_token. For smooth transition we still listen for a transition period to the old endpoint /get/sfu
Refactoring of /sfu/get POST request handling to allow different request types
- Actual processing is carried out by processLegacySFURequest and processSFURequest function and createLivekKitRoom helper function
- POST request is validated and mapped into LegacySFURequest or SFURequest by mapSFURequest
Add new endpoint /get_token using processSFURequest
Added tests
- TestMapSFURequest
- TestMapSFURequestMemoryLeak
- TestProcessLegacySFURequest
- TestProcessSFURequest
- TestLegacyHandlePost

…est types: - split out into two functions - processSFURequest: main request handling - createLiveKitRoom: utility function which will be used by all different request types - applying previously added writeMatrixError func

…s for data validation

- cache body request for later processing - add mapSFURequest function to map the request into LegacySFURequest or Matrix2 SFURequest. Including request field validation

…riables for better testability

Half-Shot

Go code looks competent ✨ . My concern is mostly in that we've got and endpoint that takes two different schemas of values, and that puts the overhead on the server to figure out the correct route.

I think we should probably just have a second endpoint, maybe under /v2/ or something that handles the new RTC endpoints. There is a marginal speedup to be had, and we will have an easier time in the client debugging if it's not supported.

fkwp · 2025-11-06T15:55:49Z

Go code looks competent ✨ . My concern is mostly in that we've got and endpoint that takes two different schemas of values, and that puts the overhead on the server to figure out the correct route.

I think we should probably just have a second endpoint, maybe under /v2/ or something that handles the new RTC endpoints. There is a marginal speedup to be had, and we will have an easier time in the client debugging if it's not supported.

My rational was that we will just remove the LegacyRTCRequest at a soon point in time. Otherwise we could also find a better endpoint name for /sfu/get ... what about /sfu/get_token

Half-Shot · 2025-11-06T15:56:42Z

/sfu/get_token is better, at least it tells me what it does :)

…h transition: - Allow for a transition period the old endpoint `/get/sfu` - This old endpoint does auto map according to request type (LegacySFURequest, SFURequest) - Define related function to 'legacy` and add TODO to remove them in future - implement the new endpoint `/get_token`

Co-authored-by: Will Hunt <2072976+Half-Shot@users.noreply.github.com>

…rocessSFURequest and adapt test case.

Co-authored-by: Will Hunt <2072976+Half-Shot@users.noreply.github.com>

…Post

Half-Shot

Overall looks good, a few nitpicks here and there.

Half-Shot

Looks beautiful ✔️

…0 → 0.4.4) (#485) This PR contains the following updates: | Package | Update | Change | |---|---|---| | [ghcr.io/element-hq/lk-jwt-service](https://github.com/element-hq/lk-jwt-service) | minor | `0.3.0` → `0.4.4` | --- ### Release Notes <details> <summary>element-hq/lk-jwt-service (ghcr.io/element-hq/lk-jwt-service)</summary> ### [`v0.4.4`](https://github.com/element-hq/lk-jwt-service/releases/tag/v0.4.4) [Compare Source](element-hq/lk-jwt-service@v0.4.3...v0.4.4) ##### Towards Delegation of Delayed Events This release updates the service to accept the JSON signature required for the delegation of MatrixRTC membership leave events, as specified in [MSC4195](matrix-org/matrix-spec-proposals#4195). Note: This update specifically addresses the JSON signature for JWT request. Comprehensive parsing and handling of the additional delegation data are currently in development (PR [#171](element-hq/lk-jwt-service#171)). ##### Docker image The service is available as a Docker image from the [GitHub Container Registry](https://github.com/element-hq/lk-jwt-service/pkgs/container/lk-jwt-service). ``` docker pull ghcr.io/element-hq/lk-jwt-service:0.4.4 ``` ##### Precompiled binaries The service is available as static precompiled binaries for amd64 and arm64 on linux attached to this release below. ##### What's Changed - Update Docker image version in installation steps by [@her001](https://github.com/her001) in [#175](element-hq/lk-jwt-service#175) - Adapted the lastest JSON signature from MSC4195 for SFURequest by [@fkwp](https://github.com/fkwp) in [#176](element-hq/lk-jwt-service#176) ##### New Contributors - [@her001](https://github.com/her001) made their first contribution in [#175](element-hq/lk-jwt-service#175) **Full Changelog**: <element-hq/lk-jwt-service@v0.4.3...v0.4.4> ### [`v0.4.3`](https://github.com/element-hq/lk-jwt-service/releases/tag/v0.4.3) [Compare Source](element-hq/lk-jwt-service@v0.4.2...v0.4.3) ##### Security Update and MSC4195 Identity Alignment This release introduces important security updates and aligns the LiveKit identity calculation with the latest MSC4195 specification. ##### ⚠️ Breaking Change The update to the LiveKit Identity hash calculation ([#172](element-hq/lk-jwt-service#172)) impacts two experimental modes in Element Call: **Compatibility: state events & multi SFU** and **Matrix 2.0**. Note that by default, these modes are not activated and Element Call will remain working with this release. For these experimental features to function correctly, the versions of Element Call and the JWT Service must be aligned: - Compatible: Element Call v0.19.2 or higher AND lk-jwt-service v0.4.3 or higher - Incompatible: - Element Call v0.19.1 or lower AND lk-jwt-service v0.4.3 or higher - Element Call v0.19.2 or higher AND lk-jwt-service v0.4.2 or lower ##### Docker image The service is available as a Docker image from the [GitHub Container Registry](https://github.com/element-hq/lk-jwt-service/pkgs/container/lk-jwt-service). ``` docker pull ghcr.io/element-hq/lk-jwt-service:0.4.3 ``` ##### Precompiled binaries The service is available as static precompiled binaries for amd64 and arm64 on linux attached to this release below. ##### What's Changed - Pin element-hq/setup-ess-cluster-action action to [`aac02ff`](element-hq/lk-jwt-service@aac02ff) by [@renovate](https://github.com/renovate)\[bot] in [#169](element-hq/lk-jwt-service#169) - Update module github.com/go-jose/go-jose/v3 to v3.0.5 \[SECURITY] by [@renovate](https://github.com/renovate)\[bot] in [#170](element-hq/lk-jwt-service#170) - Update all non-major dependencies by [@renovate](https://github.com/renovate)\[bot] in [#173](element-hq/lk-jwt-service#173) - Update softprops/action-gh-release action to v3 by [@renovate](https://github.com/renovate)\[bot] in [#174](element-hq/lk-jwt-service#174) - Adapt LiveKit Identity hash calculation to latest MSC4195 update by [@fkwp](https://github.com/fkwp) in [#172](element-hq/lk-jwt-service#172) **Full Changelog**: <element-hq/lk-jwt-service@v0.4.2...v0.4.3> ### [`v0.4.2`](https://github.com/element-hq/lk-jwt-service/releases/tag/v0.4.2) [Compare Source](element-hq/lk-jwt-service@v0.4.1...v0.4.2) ##### Healthcheck Improvement & Security Updates This is a minor release focused on maintenance and small improvements. Highlights: Added support for the HEAD method on the healthcheck endpoint, improving compatibility with monitoring tools. Included multiple security-related dependency updates to ensure the service remains up to date and secure. No breaking changes are introduced in this release. ##### Docker image The service is available as a Docker image from the [GitHub Container Registry](https://github.com/element-hq/lk-jwt-service/pkgs/container/lk-jwt-service). ``` docker pull ghcr.io/element-hq/lk-jwt-service:0.4.2 ``` ##### Precompiled binaries The service is available as static precompiled binaries for amd64 and arm64 on linux attached to this release below. ##### What's Changed - Consolidate non-major dependency updates into larger batches by [@robintown](https://github.com/robintown) in [#160](element-hq/lk-jwt-service#160) - Update module github.com/pion/dtls/v3 to v3.0.11 \[SECURITY] by [@renovate](https://github.com/renovate)\[bot] in [#154](element-hq/lk-jwt-service#154) - Update module google.golang.org/grpc to v1.79.3 \[SECURITY] by [@renovate](https://github.com/renovate)\[bot] in [#162](element-hq/lk-jwt-service#162) - Add tests against ESS by [@gaelgatelement](https://github.com/gaelgatelement) in [#164](element-hq/lk-jwt-service#164) - Update all non-major dependencies by [@renovate](https://github.com/renovate)\[bot] in [#165](element-hq/lk-jwt-service#165) - Update github.com/matrix-org/gomatrixserverlib digest to [`20c9de3`](element-hq/lk-jwt-service@20c9de3) by [@renovate](https://github.com/renovate)\[bot] in [#134](element-hq/lk-jwt-service#134) - Allow HEAD method on healthcheck by [@VlaDexa](https://github.com/VlaDexa) in [#151](element-hq/lk-jwt-service#151) - Push docker images also to oci.element.io by [@fkwp](https://github.com/fkwp) in [#166](element-hq/lk-jwt-service#166) - Update all non-major dependencies by [@renovate](https://github.com/renovate)\[bot] in [#167](element-hq/lk-jwt-service#167) - Update GitHub Actions (major) by [@renovate](https://github.com/renovate)\[bot] in [#168](element-hq/lk-jwt-service#168) ##### New Contributors - [@VlaDexa](https://github.com/VlaDexa) made their first contribution in [#151](element-hq/lk-jwt-service#151) **Full Changelog**: <element-hq/lk-jwt-service@v0.4.1...v0.4.2> ### [`v0.4.1`](https://github.com/element-hq/lk-jwt-service/releases/tag/v0.4.1) [Compare Source](element-hq/lk-jwt-service@v0.4.0...v0.4.1) ##### 🚀 Cont. Towards Matrix 2.0 – MatrixRTC-Authorisation Service This release is a minor update from 0.4.0 reflecting the lastest changes in **MSC4195: MatrixRTC Transport** which adds unpadded base64 encoding to hashes for room alias and participant ID. Furthermore, this release ensures compatibility between clients using the old `/sfu/get` endpoint and the new `/get_token` endpoint (details are [here](https://github.com/element-hq/lk-jwt-service/blob/fa226031ac7a9252996f8d038c45fc086d9d960b/main.go#L230)). ##### Docker image The service is available as a Docker image from the [GitHub Container Registry](https://github.com/element-hq/lk-jwt-service/pkgs/container/lk-jwt-service). ``` docker pull ghcr.io/element-hq/lk-jwt-service:0.4.1 ``` ##### Precompiled binaries The service is available as static precompiled binaries for amd64 and arm64 on linux attached to this release below. ##### What's Changed - README: Use LIVEKIT\_FULL\_ACCESS\_HOMESERVERS consistently by [@csett86](https://github.com/csett86) in [#140](element-hq/lk-jwt-service#140) - README: Describe the static binaries by [@csett86](https://github.com/csett86) in [#141](element-hq/lk-jwt-service#141) - refactor build.yaml into reusable chunks by [@fkwp](https://github.com/fkwp) in [#142](element-hq/lk-jwt-service#142) - fix build.yaml date determination by [@fkwp](https://github.com/fkwp) in [#143](element-hq/lk-jwt-service#143) - Use base64 encoded hashes for room alias and participant ID (minimize identifying metadata sent to SFU) by [@robintown](https://github.com/robintown) in [#144](element-hq/lk-jwt-service#144) - Add 'synchronize' and 'opened' types to PR trigger by [@fkwp](https://github.com/fkwp) in [#146](element-hq/lk-jwt-service#146) - Update room alias handling in token generation for LegacySfuRequest by [@fkwp](https://github.com/fkwp) in [#147](element-hq/lk-jwt-service#147) ##### New Contributors - [@robintown](https://github.com/robintown) made their first contribution in [#144](element-hq/lk-jwt-service#144) **Full Changelog**: <element-hq/lk-jwt-service@v0.4.0...v0.4.1> ### [`v0.4.0`](https://github.com/element-hq/lk-jwt-service/releases/tag/v0.4.0) [Compare Source](element-hq/lk-jwt-service@v0.3.0...v0.4.0) ##### 🚀 Towards Matrix 2.0 – MatrixRTC-Authorisation Service This release brings major foundational work towards **MSC4195: MatrixRTC Transport**, introduces the new `/get_token` endpoint, improves validation and error-handling, and enhances deployment flexibility with improved bind controls. ##### ✨ What's New ##### **Implementation of MSC4195: MatrixRTC Transport using LiveKit Backend** This release introduces the new MSC4195-compliant request flow and `/get_token` endpoint, while keeping `/get/sfu` available for a transition period. Key changes: - Added unified error handling via `writeMatrixError`. - Introduced new Matrix 2.0 `SFURequest` type, alongside `LegacySFURequest`. - Refactored internal functions for better testability and structure. - Added extensive new tests across request mapping, processing, and JSON handling. - Updated logging, error codes, and user-identity checks. ##### **🔌 Allow Binding of Arbitrary Addresses** This release improves deployment flexibility by allowing the service to bind to any or a specific address. ##### Features & Fixes - **feat:** Introduced support for binding to arbitrary addresses.\ *Contributed by [@matdup](https://github.com/matdup)* - **fix:** Documentation updated for environment variable changes. - **feat:** Reintroduced `LIVEKIT_JWT_PORT` for backward compatibility. - Now mutually exclusive with `LIVEKIT_JWT_BIND`. - Emits a warning when used. - **feat:** Enforced mutual exclusivity between `LIVEKIT_JWT_BIND` and `LIVEKIT_JWT_PORT`. ##### ⚙️ Configuration ##### Environment Variables | Variable | Description | | ------------------ | ------------------------------------------------------------------------------------- | | `LIVEKIT_JWT_BIND` | Binds the service to a specific host:port (new preferred method). Defaults to `:8080` | | `LIVEKIT_JWT_PORT` | Deprecated but still supported. Mutually exclusive with `LIVEKIT_JWT_BIND`. | ##### Endpoint Changes | Endpoint | Status | Notes | | ------------ | ------------------------- | ------------------------------------------------------------- | | `/get_token` | **New (Primary)** | Conforms to MSC4195. | | `/get/sfu` | **Legacy (Transitional)** | Auto-maps request types; will be removed in a future release. | ##### 🤝 Client Compatibility - Legacy MatrixRTC clients continue functioning via `/sfu/get`. - MSC4195-aware clients should migrate to **`/get_token`**. - Both request formats remain supported during the transition. - Stricter validation may require client-side updates: - Correct request field shapes - Accurate user identity claims (`claimed_user_id` vs OpenID `sub`) ##### Docker image The service is available as a Docker image from the [GitHub Container Registry](https://github.com/element-hq/lk-jwt-service/pkgs/container/lk-jwt-service). ``` docker pull ghcr.io/element-hq/lk-jwt-service:0.4.0 ``` ##### Precompiled binaries The service is available as static precompiled binaries for amd64 and arm64 on linux attached to this release below. ##### What's Changed - ci: add static go releases for linux arm64 and amd64 by [@csett86](https://github.com/csett86) in [#111](element-hq/lk-jwt-service#111) - fix(deps): update github.com/matrix-org/gomatrixserverlib digest to [`a234d6d`](element-hq/lk-jwt-service@a234d6d) by [@renovate](https://github.com/renovate)\[bot] in [#113](element-hq/lk-jwt-service#113) - chore(deps): update dependency go to v1.24.5 by [@renovate](https://github.com/renovate)\[bot] in [#114](element-hq/lk-jwt-service#114) - refactor README.md by [@fkwp](https://github.com/fkwp) in [#115](element-hq/lk-jwt-service#115) - feat: allow binding of arbitrary addresses by [@MatthieuCoder](https://github.com/MatthieuCoder) in [#118](element-hq/lk-jwt-service#118) - fix(deps): update github.com/matrix-org/gomatrixserverlib digest to [`6697d93`](element-hq/lk-jwt-service@6697d93) by [@renovate](https://github.com/renovate)\[bot] in [#120](element-hq/lk-jwt-service#120) - chore(deps): update dependency go to v1.25.3 by [@renovate](https://github.com/renovate)\[bot] in [#121](element-hq/lk-jwt-service#121) - Refactor config parsing by [@fkwp](https://github.com/fkwp) in [#125](element-hq/lk-jwt-service#125) - fix(deps): update module github.com/golang-jwt/jwt/v5 to v5.3.0 by [@renovate](https://github.com/renovate)\[bot] in [#127](element-hq/lk-jwt-service#127) - chore(deps): update github actions by [@renovate](https://github.com/renovate)\[bot] in [#126](element-hq/lk-jwt-service#126) - Implementation of MSC4195: MatrixRTC Transport using LiveKit Backend by [@fkwp](https://github.com/fkwp) in [#128](element-hq/lk-jwt-service#128) - fix: add `expires_in` field to `OpenIDTokenType` by [@fkwp](https://github.com/fkwp) in [#130](element-hq/lk-jwt-service#130) ##### New Contributors - [@csett86](https://github.com/csett86) made their first contribution in [#111](element-hq/lk-jwt-service#111) - [@MatthieuCoder](https://github.com/MatthieuCoder) made their first contribution in [#118](element-hq/lk-jwt-service#118) **Full Changelog**: <element-hq/lk-jwt-service@v0.3.0...v0.4.0> </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about these updates again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Reviewed-on: https://git.erwanleboucher.dev/eleboucher/homelab/pulls/485

fkwp added 12 commits October 31, 2025 19:52

Add writeMatrixError function to unify error handling

6502d92

rename SFURequest into LegacySFURequest

b6a6497

add Matrix2 SFURequest type

1c3c7df

Add interface as well as implementation of it to SFURequest data type…

531b65d

…s for data validation

linting

046f9a8

Add process function for Matrix2 SFURequest type

d96a452

refactor /sfu/get "POST" handling:

f1cc9f9

- cache body request for later processing - add mapSFURequest function to map the request into LegacySFURequest or Matrix2 SFURequest. Including request field validation

comment about request validation validation

5f963fa

add test for MapSFURequest

824dd7c

license header upddate

97fd56f

add test to check json parsing and processing wrt. memory leaks

9a356f9

fkwp force-pushed the fkwp/matrix2 branch from 4ec6d59 to 9a356f9 Compare November 4, 2025 15:24

fkwp marked this pull request as ready for review November 6, 2025 11:28

fkwp requested a review from a team as a code owner November 6, 2025 11:28

fkwp requested review from AndrewFerr and BillCarsonFr November 6, 2025 11:28

fkwp added 4 commits November 6, 2025 13:04

convert exchangeOpenIdUserInfo and createLiveKitRoom into function va…

679a256

…riables for better testability

reorder tests in main_test.go

7004aa8

Add test for ProcessSFURequest

d1a33aa

Add test for ProcessLegacySFURequest

83665ee

fkwp force-pushed the fkwp/matrix2 branch from 2dfe1ea to 83665ee Compare November 6, 2025 12:04

Half-Shot requested review from Half-Shot and removed request for BillCarsonFr November 6, 2025 15:27

Half-Shot suggested changes Nov 6, 2025

View reviewed changes

fkwp and others added 3 commits November 7, 2025 12:10

Update main.go

7c9fe51

Co-authored-by: Will Hunt <2072976+Half-Shot@users.noreply.github.com>

Update main.go

7734402

Co-authored-by: Will Hunt <2072976+Half-Shot@users.noreply.github.com>

fkwp and others added 6 commits November 7, 2025 12:14

Update main.go

f7cdeee

Co-authored-by: Will Hunt <2072976+Half-Shot@users.noreply.github.com>

add type to errCode

2efed9b

add logline in case of error while getJoinToken

f2be4d0

Check if validated userInfo.Sub matches req.Member.ClaimedUserID in p…

1806681

…rocessSFURequest and adapt test case.

Update main.go

e7c9438

Co-authored-by: Will Hunt <2072976+Half-Shot@users.noreply.github.com>

Use correct err code M_INVALID_PARAM -> M_BAD_JSON

4926f65

fkwp requested a review from Half-Shot November 7, 2025 11:58

renamed TestHandlePost -> TestLegacyHandlePost and readded TestHandle…

9541e02

…Post

Half-Shot previously approved these changes Nov 10, 2025

View reviewed changes

Comment thread main.go

Comment thread main.go

Comment thread main.go Outdated

review comments

6fdbe7c

fkwp dismissed Half-Shot’s stale review via 6fdbe7c November 10, 2025 13:43

fkwp requested a review from Half-Shot November 10, 2025 13:46

Half-Shot approved these changes Nov 10, 2025

View reviewed changes

fkwp merged commit 6573de0 into main Nov 10, 2025
4 checks passed

fkwp deleted the fkwp/matrix2 branch November 10, 2025 13:50

fkwp mentioned this pull request Dec 5, 2025

MSC4195: LiveKit transport for MatrixRTC matrix-org/matrix-spec-proposals#4195

Open

Navigation Menu

Uh oh!

Implementation of MSC4195: MatrixRTC Transport using LiveKit Backend - #128

Implementation of MSC4195: MatrixRTC Transport using LiveKit Backend#128
fkwp merged 27 commits into
mainfrom
fkwp/matrix2

fkwp commented Nov 4, 2025 •

edited

Loading

Uh oh!

Half-Shot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fkwp commented Nov 6, 2025

Uh oh!

Half-Shot commented Nov 6, 2025

Uh oh!

Half-Shot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Half-Shot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

fkwp commented Nov 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Half-Shot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

fkwp commented Nov 6, 2025

Uh oh!

Half-Shot commented Nov 6, 2025

Uh oh!

Half-Shot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Half-Shot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

fkwp commented Nov 4, 2025 •

edited

Loading