From dd2e6baacab22ff0422b17b5b3d922561f4fbd7c Mon Sep 17 00:00:00 2001 From: James Chapman Date: Sun, 15 Nov 2026 20:40:27 +0000 Subject: [PATCH 01/42] Plan the built-in OAuth 2.0 API and start 1.1.0 (ADR-0760 to ADR-0764) Element X creates accounts only through the Matrix OAuth 2.0 API, and Merovingian answers its discovery request with 404, so account creation from Element X fails. - Bump every version location to 1.1.0, the first build of the 1.1 series. - Add docs/todos/oauth-2-0-api.md: the design, twelve phases, and the proposals that still need the owner's confirmation before their phase. - Record the owner's decisions: the API is built into the homeserver (ADR-0760), the legacy API stays on by default with a key to turn it off (ADR-0761), the registration page applies security.registration.* (ADR-0762), the pages are compiled in without JavaScript (ADR-0763), and server.oauth.* replaces server.oidc.* (ADR-0764). - Link the plan from the docs navigation and the capability-gaps row. No server behaviour changes in this commit. Co-Authored-By: Claude Fable 5.2 --- CHANGELOG.md | 21 ++ ...th-2-0-api-is-built-into-the-homeserver.md | 70 +++++ ...y-default-and-a-config-key-turns-it-off.md | 51 +++ ...pplies-the-legacy-registration-settings.md | 49 +++ ...uilt-into-the-binary-without-javascript.md | 54 ++++ ...erver-oidc-and-the-old-keys-are-refused.md | 48 +++ docs/adr/index.md | 5 + docs/todos/capability-gaps.md | 2 +- docs/todos/oauth-2-0-api.md | 297 ++++++++++++++++++ meson.build | 2 +- mkdocs.yml | 1 + 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 +- 26 files changed, 629 insertions(+), 24 deletions(-) create mode 100644 docs/adr/0760-the-oauth-2-0-api-is-built-into-the-homeserver.md create mode 100644 docs/adr/0761-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md create mode 100644 docs/adr/0762-the-registration-page-applies-the-legacy-registration-settings.md create mode 100644 docs/adr/0763-the-authentication-pages-are-built-into-the-binary-without-javascript.md create mode 100644 docs/adr/0764-server-oauth-replaces-server-oidc-and-the-old-keys-are-refused.md create mode 100644 docs/todos/oauth-2-0-api.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b7732b7db..2d653c607 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,27 @@ 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.0 + +## Features + +* The plan for a built-in OAuth 2.0 API, which Element X needs to create accounts, is in + `docs/todos/oauth-2-0-api.md`. Nothing the server does has changed yet (ADR-0760 to ADR-0764). + +## Security Fixes + +* None. + +## Bug fixes + +* None. + +## Release notes + +1.1.0 is in development and so far holds only the plan for the OAuth 2.0 API and the decisions behind it. When the +feature lands, a configuration that sets any `server.oidc.*` key will be refused at start-up: remove those keys and +set `server.oauth.enabled` instead. + # Version 1.0.2 ## Features diff --git a/docs/adr/0760-the-oauth-2-0-api-is-built-into-the-homeserver.md b/docs/adr/0760-the-oauth-2-0-api-is-built-into-the-homeserver.md new file mode 100644 index 000000000..7c49bb0af --- /dev/null +++ b/docs/adr/0760-the-oauth-2-0-api-is-built-into-the-homeserver.md @@ -0,0 +1,70 @@ +# The OAuth 2.0 API is built into the homeserver + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-15 + +Technical Story: Element X cannot create an account on Merovingian. It reports that the account provider "needs to +be upgraded to support Matrix Authentication Service and account creation". + +## Context and Problem Statement + +Element X creates accounts only through the Matrix OAuth 2.0 API, which the spec added in v1.15 beside the legacy +login and registration API. Merovingian answered the discovery request, `GET /_matrix/client/v1/auth_metadata`, with +`404 M_UNRECOGNIZED` unless `server.oidc.*` was set, and those keys only published the addresses of an authorisation +server run by someone else. Merovingian could not accept a token such a server issued. + +Who is the authorisation server for a Merovingian deployment? + +## Decision Drivers + +* An operator should get a working Element X from one package and one configuration file. +* The authorisation server decides who may hold a session. That is the most security-sensitive decision the + homeserver makes, and the project's rules for tokens, passwords and throttling already govern it. +* The spec defines the OAuth 2.0 API as something a homeserver offers. It defines no protocol between a homeserver + and a separate authorisation server. + +## Considered Options + +* Build the OAuth 2.0 API into the homeserver. +* Delegate to Matrix Authentication Service. +* Keep publishing an operator-supplied authorisation server's metadata. + +## Decision Outcome + +Chosen option: "Build the OAuth 2.0 API into the homeserver". The homeserver serves the metadata, client +registration, the authorisation, token and revocation endpoints and the pages the user sees. A session it issues is +an ordinary session in the existing session and token tables. + +### Positive Consequences + +* One process holds accounts, sessions and tokens. Revocation, deactivation, locking and the device cap apply to an + OAuth session exactly as they apply to a legacy one. +* No second service to package, configure, secure and upgrade. + +### Negative Consequences + +* The homeserver now serves HTML pages to a browser. That is new attack surface, which + [ADR-0763](0763-the-authentication-pages-are-built-into-the-binary-without-javascript.md) bounds. +* Upstream identity providers (signing in with an account held elsewhere) are not part of this decision and are not + provided. + +## Pros and Cons of the Options + +### Delegate to Matrix Authentication Service + +* Good, because the pages, the flows and the upstream-provider support already exist. +* Bad, because the homeserver side is not in the spec: it is a private interface (token introspection and an + account-provisioning API) that Matrix Authentication Service defines for Synapse. +* Bad, because every deployment would need a second service and a second database. + +### Keep publishing an operator-supplied authorisation server's metadata + +* Bad, because it cannot work: a client that follows the metadata receives a token Merovingian does not recognise. + +## Links + +* Refined by [ADR-0761](0761-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md), + [ADR-0762](0762-the-registration-page-applies-the-legacy-registration-settings.md), + [ADR-0763](0763-the-authentication-pages-are-built-into-the-binary-without-javascript.md) and + [ADR-0764](0764-server-oauth-replaces-server-oidc-and-the-old-keys-are-refused.md) diff --git a/docs/adr/0761-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md b/docs/adr/0761-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md new file mode 100644 index 000000000..eee75b355 --- /dev/null +++ b/docs/adr/0761-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md @@ -0,0 +1,51 @@ +# The legacy authentication API stays on by default, and a config key turns it off + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-15 + +## Context and Problem Statement + +The spec lets a homeserver offer the legacy authentication API, the OAuth 2.0 API, or both. Once Merovingian offers +the OAuth 2.0 API ([ADR-0760](0760-the-oauth-2-0-api-is-built-into-the-homeserver.md)), what happens to +`POST /login` and `POST /register`? + +## Decision Drivers + +* Most clients other than Element X still log in through the legacy API. +* An operator who wants every login to pass through the server's own pages should be able to have that. +* Enabling a feature must not sign existing users out. + +## Considered Options + +* Both APIs on, always. +* Both on by default, with a key that turns the legacy API off. +* The legacy API off whenever the OAuth 2.0 API is on. + +## Decision Outcome + +Chosen option: "Both on by default, with a key that turns the legacy API off". `server.oauth.legacy_api_enabled` +defaults to `true`. With `false`, the legacy endpoints stop issuing sessions to users, and the server answers as the +spec says a server without the legacy API answers: `GET /login` is `404 M_UNRECOGNIZED`, and `POST /register` serves +only application services, which must set `inhibit_login`. The key is refused at start-up unless +`server.oauth.enabled` is `true`, so a configuration can never leave users with no way to log in. + +### Positive Consequences + +* Turning the OAuth 2.0 API on changes nothing for a client that does not use it. + +### Negative Consequences + +* With both on, the server has two ways to obtain a session, and every rule about sessions has to hold for both. + A check added to one login path must be added to the other. + +## Pros and Cons of the Options + +### Both APIs on, always + +* Bad, because an operator cannot require that passwords are typed only into the server's own pages. + +### The legacy API off whenever the OAuth 2.0 API is on + +* Good, because there is one login path. +* Bad, because enabling the feature would lock out every client that has not adopted the OAuth 2.0 API. diff --git a/docs/adr/0762-the-registration-page-applies-the-legacy-registration-settings.md b/docs/adr/0762-the-registration-page-applies-the-legacy-registration-settings.md new file mode 100644 index 000000000..7159bf90a --- /dev/null +++ b/docs/adr/0762-the-registration-page-applies-the-legacy-registration-settings.md @@ -0,0 +1,49 @@ +# The registration page applies the legacy registration settings + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-15 + +## Context and Problem Statement + +Under the OAuth 2.0 API an account is created on a page the homeserver serves, and the spec gives the homeserver +"complete control over the requirements to create a new account". `POST /register` is governed by +`security.registration.enabled`, `require_token`, `allow_open_registration` and `token_file`. What governs the page? + +## Considered Options + +* The page applies `security.registration.*`, and nothing else. +* The page has settings of its own. +* The page always requires a registration token. +* The page also requires a verified email address. + +## Decision Outcome + +Chosen option: "The page applies `security.registration.*`, and nothing else". The page calls the function +`POST /register` calls, so the enabled flag, the registration token, the username rules, the reserved localparts, +the password rules, the registration policy rule and the Argon2id admission budget all apply. The page offers +account creation, and the metadata lists `create` in `prompt_values_supported`, only while +`security.registration.enabled` is `true`. + +### Positive Consequences + +* An operator reasons about one registration policy. A server that is closed to registration is closed on both + paths, and a registration token cannot be bypassed by choosing the other path. + +### Negative Consequences + +* An operator cannot open registration for Element X while keeping it closed for legacy clients, or the reverse. + [ADR-0761](0761-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md) gives the + nearest equivalent: turn the legacy API off. + +## Pros and Cons of the Options + +### The page has settings of its own + +* Bad, because two policies for one act is how one of them ends up open by mistake. + +### The page also requires a verified email address + +* Good, because it raises the cost of mass registration. +* Bad, because it needs SMTP configured and adds a verification flow to the page. It can be added later without + changing this decision. diff --git a/docs/adr/0763-the-authentication-pages-are-built-into-the-binary-without-javascript.md b/docs/adr/0763-the-authentication-pages-are-built-into-the-binary-without-javascript.md new file mode 100644 index 000000000..cd5d86ae6 --- /dev/null +++ b/docs/adr/0763-the-authentication-pages-are-built-into-the-binary-without-javascript.md @@ -0,0 +1,54 @@ +# The authentication pages are built into the binary, without JavaScript + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-15 + +## Context and Problem Statement + +The OAuth 2.0 API ([ADR-0760](0760-the-oauth-2-0-api-is-built-into-the-homeserver.md)) makes the homeserver serve +pages to a browser: login, registration, consent and account management. The user types the account password into +them. Until now the server returned no HTML at all. Where do the pages come from? + +## Decision Drivers + +* A page that takes a password is the most valuable target on the server. Script injection there is account + takeover. +* The main process is sandboxed after start-up. On FreeBSD it cannot open a file after `cap_enter`. +* The pages show text an unauthenticated party chose: the client's name and addresses from its registration. + +## Considered Options + +* Fixed HTML compiled into the binary, with no JavaScript. +* Template files on disk that an operator may edit. + +## Decision Outcome + +Chosen option: "Fixed HTML compiled into the binary, with no JavaScript". One renderer builds every page and +accepts only fragments that have been escaped. Every page is sent with a `Content-Security-Policy` that allows no +script and no remote resource. Branding is the server name and links from the configuration. A client's logo is +never fetched or shown. + +Rules for future code: + +* A page never contains a `&"}; +constexpr auto hostile_escaped = std::string_view{""><script>alert('x')</script>&amp;"}; + +[[nodiscard]] auto escaped(std::string_view text) -> HtmlText +{ + auto html = HtmlText::escape(text); + REQUIRE(html.has_value()); + return std::move(*html); +} + +[[nodiscard]] auto count(std::string_view haystack, std::string_view needle) -> std::size_t +{ + auto found = std::size_t{0U}; + for (auto at = haystack.find(needle); at != std::string_view::npos; at = haystack.find(needle, at + 1U)) + { + ++found; + } + return found; +} + +[[nodiscard]] auto header(std::vector> const& headers, std::string_view name) + -> std::string +{ + auto const it = std::ranges::find_if(headers, [name](auto const& entry) { + return entry.first == name; + }); + REQUIRE(it != headers.end()); + return it->second; +} + +[[nodiscard]] auto read(std::string_view text) -> ParsedUri +{ + auto parsed = ParsedUri::read(text); + REQUIRE(std::holds_alternative(parsed)); + return std::get(std::move(parsed)); +} + +constexpr auto fixed_policy = std::string_view{"default-src 'none'; style-src 'sha256-"}; + +} // namespace + +SCENARIO("HtmlText escapes the five markup characters and refuses unsafe text", "[oauth][page][security]") +{ + GIVEN("the hostile payload, and text with a NUL, invalid UTF-8, a right-to-left override and a control byte") + { + auto with_nul = std::string{"a"}; + with_nul.push_back('\0'); + + WHEN("each is escaped") + { + auto const markup = HtmlText::escape(hostile); + + THEN("the payload is escaped and every unsafe text is refused, never repaired") + { + REQUIRE(markup.has_value()); + REQUIRE(markup->html() == hostile_escaped); + REQUIRE_FALSE(HtmlText::escape(with_nul).has_value()); + REQUIRE_FALSE(HtmlText::escape("a\xff").has_value()); + REQUIRE_FALSE(HtmlText::escape("a\xc0\xaf").has_value()); + REQUIRE_FALSE(HtmlText::escape("pay\xe2\x80\xaelapyap").has_value()); + REQUIRE_FALSE(HtmlText::escape("a\x1b[31m").has_value()); + REQUIRE_FALSE(HtmlText::escape("").has_value()); + } + } + } +} + +SCENARIO("HtmlText is capped at 4096 bytes before escaping", "[oauth][page][boundary]") +{ + GIVEN("texts of 4096 and 4097 bytes") + { + auto const at_cap = std::string(HtmlText::max_text_bytes, '<'); + auto const over_cap = at_cap + "<"; + + WHEN("each is escaped") + { + auto const accepted = HtmlText::escape(at_cap); + + THEN("4096 bytes are escaped whole and 4097 are refused") + { + REQUIRE(accepted.has_value()); + REQUIRE(accepted->html().size() == HtmlText::max_text_bytes * 4U); + REQUIRE_FALSE(HtmlText::escape(over_cap).has_value()); + } + } + } +} + +SCENARIO("Hostile text in every slot of a page stays text", "[oauth][page][security]") +{ + GIVEN("a page with the hostile payload as title, paragraph, notice, error, details, link label and form parts") + { + auto page = Page{escaped(hostile)}; + page.paragraph(escaped(hostile)); + page.notice(escaped(hostile)); + page.error(escaped(hostile)); + auto const details = std::array{ + PageDetail{escaped(hostile), escaped(hostile)}, + PageDetail{HtmlText{"Device ID"}, escaped(std::string(255U, 'D'))}, + }; + page.details(details); + REQUIRE(page.link(escaped(hostile), "https://example.com/tos?a=1&b='2'")); + + auto form = PageForm{"/_merovingian/oauth2/authorize"}; + form.hidden("pending", escaped(hostile)); + REQUIRE(form.input(TextInput{"username", escaped(hostile), "username", false, escaped(hostile)})); + REQUIRE(form.input(TextInput{"password", escaped(hostile), "current-password", true})); + REQUIRE(form.button(SubmitButton{"decision", "approve", escaped(hostile)})); + REQUIRE(page.form(form)); + + WHEN("it is rendered") + { + auto const html = page.render(); + + THEN("the payload appears only escaped, and the page has no script, handler or inline style") + { + REQUIRE(html.find("<") == std::string::npos); + REQUIRE(html.find("javascript:") == std::string::npos); + REQUIRE(html.find("style=") == std::string::npos); + REQUIRE(html.find(" on") == std::string::npos); + // Title, heading, paragraph, notice, error, detail label and value, link label, hidden value, two + // input labels, the input value and the button label. + REQUIRE(count(html, hostile_escaped) == 13U); + REQUIRE(count(html, "") != + std::string::npos); + REQUIRE(header(headers, "Content-Security-Policy") == + std::string{fixed_policy} + *encoded + + "'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'"); + REQUIRE(header(headers, "Content-Type") == "text/html; charset=utf-8"); + REQUIRE(header(headers, "X-Frame-Options") == "DENY"); + REQUIRE(header(headers, "Referrer-Policy") == "no-referrer"); + REQUIRE(header(headers, "Cache-Control") == "no-store"); + REQUIRE(headers.size() == 5U); + } + } + } +} + +SCENARIO("A redirect target adds only its own origin to form-action", "[oauth][page][security]") +{ + GIVEN("redirect targets whose paths and queries try to inject directives and sources") + { + auto const web = read("https://app.example.com:8443/cb;script-src%20*?x=1;default-src%20*,'unsafe-inline'"); + auto const loopback = read("http://127.0.0.1:5000/cb?a=;b"); + auto const native = read("com.example.app:/cb;script-src"); + + WHEN("headers are built for each") + { + auto const web_policy = header(merovingian::oauth::page_headers(web), "Content-Security-Policy"); + auto const loopback_policy = header(merovingian::oauth::page_headers(loopback), "Content-Security-Policy"); + auto const native_policy = header(merovingian::oauth::page_headers(native), "Content-Security-Policy"); + + THEN("each policy has the same five directives and ends with the target's origin or scheme") + { + for (auto const& policy : {web_policy, loopback_policy, native_policy}) + { + REQUIRE(count(policy, ";") == 4U); + REQUIRE(policy.find("script-src") == std::string::npos); + REQUIRE(policy.find("unsafe") == std::string::npos); + } + REQUIRE(web_policy.ends_with("; form-action 'self' https://app.example.com:8443")); + REQUIRE(loopback_policy.ends_with("; form-action 'self' http://127.0.0.1:5000")); + REQUIRE(native_policy.ends_with("; form-action 'self' com.example.app:")); + } + } + } +} + +SCENARIO("A target that is no valid redirect adds no form-action source", "[oauth][page][security]") +{ + GIVEN("URIs a caller should never pass: a bare scheme with no dot, javascript:, data: and ftp://") + { + auto const targets = std::array{read("https:example.com"), read("javascript:alert(1)"), + read("data:text/html,x"), read("ftp://example.com/")}; + + WHEN("headers are built for each") + { + THEN("form-action stays 'self' alone") + { + for (auto const& target : targets) + { + INFO(target.text()); + REQUIRE(header(merovingian::oauth::page_headers(target), "Content-Security-Policy") + .ends_with("; form-action 'self'")); + } + } + } + } +} From 84038b9f6ecdc7b4f21f5fca385c4c4d71232897 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 00:28:58 +0000 Subject: [PATCH 07/42] Link observability and platform into the OAuth fuzz targets auth's objects reach observability::SingleLog, so fuzz-oauth-scope failed to link with -Dbuild_fuzz=true. With the two libraries added, all three OAuth fuzz targets build and each ran 60 seconds on the Linux VM without a finding. Co-Authored-By: Claude Fable 5.2 --- tests/fuzz/meson.build | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tests/fuzz/meson.build b/tests/fuzz/meson.build index 0e1c196f1..d09460be2 100644 --- a/tests/fuzz/meson.build +++ b/tests/fuzz/meson.build @@ -82,7 +82,7 @@ fuzz_targets = [ cpp_args: fuzz_sanitizer_args, link_args: fuzz_sanitizer_args, dependencies: [libsodium_dep, openssl_dep], - link_with: [oauth_lib, auth_lib, canonicaljson_lib, core_lib, crypto_lib], + link_with: [oauth_lib, auth_lib, canonicaljson_lib, core_lib, crypto_lib, observability_lib, platform_lib], ), executable( 'fuzz-oauth-scope', @@ -91,7 +91,7 @@ fuzz_targets = [ cpp_args: fuzz_sanitizer_args, link_args: fuzz_sanitizer_args, dependencies: [libsodium_dep, openssl_dep], - link_with: [oauth_lib, auth_lib, canonicaljson_lib, core_lib, crypto_lib], + link_with: [oauth_lib, auth_lib, canonicaljson_lib, core_lib, crypto_lib, observability_lib, platform_lib], ), executable( 'fuzz-oauth-client-metadata', @@ -100,7 +100,7 @@ fuzz_targets = [ cpp_args: fuzz_sanitizer_args, link_args: fuzz_sanitizer_args, dependencies: [libsodium_dep, openssl_dep], - link_with: [oauth_lib, auth_lib, canonicaljson_lib, core_lib, crypto_lib], + link_with: [oauth_lib, auth_lib, canonicaljson_lib, core_lib, crypto_lib, observability_lib, platform_lib], ), executable( 'fuzz-srv-record', From 2e1d6e9e2c8b856a90981cd0f0787903a0013995 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 01:15:21 +0000 Subject: [PATCH 08/42] Serve the OAuth 2.0 server metadata behind server.oauth.*, and refuse server.oidc.* (ADR-0773 to ADR-0775) Phase 2 of the OAuth 2.0 API plan: configuration and metadata. - server.oauth.enabled, legacy_api_enabled, device_grant_enabled and hand_off_redirect_allowlist are parsed, validated and restart-required. - server.oidc.* is refused at start-up with a message naming server.oauth.enabled; OidcConfig and auth/OidcDiscovery are removed. - With OAuth on, public_baseurl must be an https URL the strict reader accepts, and server.sso.authorization_url is refused. - oauth::OAuthBaseUrl builds every OAuth address; oauth::server_metadata builds the auth_metadata document, served on the v1 and MSC2965 paths. - auth_metadata stays in the generic rate-limit tier (ADR-0775). Co-Authored-By: Claude Fable 5.2 --- .../references/module-invariants.md | 2 + AGENTS.md | 4 +- CHANGELOG.md | 12 +- config/merovingian.conf.bsd.example | 35 +- config/merovingian.conf.example | 35 +- ...l-and-the-routes-live-under-merovingian.md | 44 ++ ...-bare-private-use-scheme-never-a-prefix.md | 37 ++ ...ta-stays-in-the-generic-rate-limit-tier.md | 35 ++ docs/adr/index.md | 3 + docs/architecture.md | 2 +- docs/auth-identity.md | 2 +- docs/matrix-v1.19-client-server-api.md | 2 +- docs/todos/capability-gaps.md | 2 +- docs/todos/oauth-2-0-api.md | 6 +- docs/user-manual.md | 58 ++- include/merovingian/auth/AuthMetadata.hpp | 19 - include/merovingian/auth/OidcDiscovery.hpp | 17 - include/merovingian/config/Config.hpp | 1 - include/merovingian/config/OAuthConfig.hpp | 28 ++ include/merovingian/config/OidcConfig.hpp | 28 -- include/merovingian/config/PushConfig.hpp | 2 +- include/merovingian/config/ServerConfig.hpp | 7 +- include/merovingian/config/SsoConfig.hpp | 2 +- .../merovingian/oauth/HandOffAllowlist.hpp | 36 ++ include/merovingian/oauth/OAuthBaseUrl.hpp | 46 ++ include/merovingian/oauth/OAuthPaths.hpp | 29 ++ include/merovingian/oauth/ServerMetadata.hpp | 23 + .../oauth/ServerMetadataOptions.hpp | 26 ++ src/auth/AGENTS.md | 1 - src/auth/OidcDiscovery.cpp | 92 ---- src/auth/meson.build | 1 - src/config/AGENTS.md | 2 +- src/config/Config.cpp | 86 ++-- src/config/ConfigParser.cpp | 48 +- src/config/ReloadPlan.cpp | 21 +- src/config/ReloadPolicy.cpp | 8 + src/config/meson.build | 3 +- src/federation_worker/meson.build | 4 +- src/homeserver/AGENTS.md | 8 + src/homeserver/ClientServerRuntime.cpp | 46 +- src/meson.build | 6 +- src/oauth/AGENTS.md | 17 +- src/oauth/HandOffAllowlist.cpp | 105 +++++ src/oauth/OAuthBaseUrl.cpp | 71 +++ src/oauth/ServerMetadata.cpp | 79 ++++ src/oauth/meson.build | 3 + .../test_client_server_conformance.cpp | 38 +- .../test_oauth_metadata_conformance.cpp | 301 ++++++++++++ .../test_route_query_conformance.cpp | 4 +- tests/fuzz/meson.build | 4 +- .../test_client_server_endpoints_flow.cpp | 60 +-- .../integration/test_oauth_metadata_flow.cpp | 255 ++++++++++ tests/meson.build | 15 +- tests/tooling/test_example_config.py | 27 ++ tests/unit/test_auth_oidc_discovery.cpp | 183 -------- tests/unit/test_config_oauth.cpp | 435 ++++++++++++++++++ tests/unit/test_config_oidc_validation.cpp | 250 ---------- tests/unit/test_config_sso.cpp | 27 +- tests/unit/test_http_rate_limit_tiers.cpp | 5 +- tests/unit/test_oauth_hand_off_allowlist.cpp | 131 ++++++ tests/unit/test_oauth_server_metadata.cpp | 279 +++++++++++ 61 files changed, 2309 insertions(+), 849 deletions(-) create mode 100644 docs/adr/0773-the-oauth-issuer-is-public-baseurl-and-the-routes-live-under-merovingian.md create mode 100644 docs/adr/0774-a-hand-off-allowlist-entry-is-an-https-origin-or-a-bare-private-use-scheme-never-a-prefix.md create mode 100644 docs/adr/0775-auth-metadata-stays-in-the-generic-rate-limit-tier.md delete mode 100644 include/merovingian/auth/AuthMetadata.hpp delete mode 100644 include/merovingian/auth/OidcDiscovery.hpp create mode 100644 include/merovingian/config/OAuthConfig.hpp delete mode 100644 include/merovingian/config/OidcConfig.hpp create mode 100644 include/merovingian/oauth/HandOffAllowlist.hpp create mode 100644 include/merovingian/oauth/OAuthBaseUrl.hpp create mode 100644 include/merovingian/oauth/OAuthPaths.hpp create mode 100644 include/merovingian/oauth/ServerMetadata.hpp create mode 100644 include/merovingian/oauth/ServerMetadataOptions.hpp delete mode 100644 src/auth/OidcDiscovery.cpp create mode 100644 src/oauth/HandOffAllowlist.cpp create mode 100644 src/oauth/OAuthBaseUrl.cpp create mode 100644 src/oauth/ServerMetadata.cpp create mode 100644 tests/conformance/test_oauth_metadata_conformance.cpp create mode 100644 tests/integration/test_oauth_metadata_flow.cpp delete mode 100644 tests/unit/test_auth_oidc_discovery.cpp create mode 100644 tests/unit/test_config_oauth.cpp delete mode 100644 tests/unit/test_config_oidc_validation.cpp create mode 100644 tests/unit/test_oauth_hand_off_allowlist.cpp create mode 100644 tests/unit/test_oauth_server_metadata.cpp diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index ff9f301a8..4616cde39 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -246,6 +246,8 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that (ADR-0770). No redirect before the client and its redirect URI are validated. - HTML only through `Page` with `HtmlText` or compile-time parts; every page sends `page_headers()`; only a matched redirect URI adds a `form-action` source (ADR-0772). PKCE `S256` only, constant-time. +- Every absolute OAuth address comes from `OAuthBaseUrl` with a path from `OAuthPaths.hpp` (ADR-0773). A hand-off + allowlist entry is an https origin or a bare private-use scheme, never a prefix (ADR-0774). ## src/observability diff --git a/AGENTS.md b/AGENTS.md index bb298332d..f0e9aed61 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -191,7 +191,7 @@ the same name in `include/`: `src/appservice/RegistrationYaml.cpp`, `src/databas ``` ├── include/merovingian/ # Public headers (same module dirs as src/) │ ├── appservice/ # Application Service registration, namespaces, outbound client -│ ├── auth/ # Password hashing, session tokens, identity, key API, OIDC discovery +│ ├── auth/ # Password hashing, session tokens, identity, key API │ ├── bootstrap/ # Process exit codes (header-only) │ ├── canonicaljson/ # Canonical JSON (value, parser, serializer, signable) │ ├── config/ # Config model, parser, runtime config, reload plan/policy @@ -208,7 +208,7 @@ the same name in `include/`: `src/appservice/RegistrationYaml.cpp`, `src/databas │ ├── ipc/ # Authenticated, encrypted AF_UNIX channel between main process and federation worker │ ├── media/ # Media repository, MIME/quarantine security, sandboxed thumbnailer │ ├── net/ # Listener, TCP acceptor, thread pool, shutdown signal -│ ├── oauth/ # OAuth 2.0 API: PKCE, scope, URI reader, redirect URI and client metadata rules, page renderer +│ ├── oauth/ # OAuth 2.0 API: PKCE, scope, URI reader, redirect URI and client metadata rules, page renderer, base URL, server metadata, hand-off allowlist │ ├── observability/ # Logger, observability │ ├── platform/ # Runtime hardening, seccomp, ELF probe, file metadata, self-check │ ├── push/ # Push rules evaluation, push gateway client diff --git a/CHANGELOG.md b/CHANGELOG.md index 6d4a42637..2fa78d260 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,12 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) canonical form (ADR-0770, ADR-0771). * The one HTML page renderer, which accepts only escaped text, and the headers every page carries (ADR-0772). * `crypto::sha256` for protocols that name SHA-256. +* `server.oauth.enabled` serves the OAuth 2.0 server metadata at `auth_metadata` and its MSC2965 path; off, both + answer 404. The issuer is `server.public_baseurl`, endpoints sit under `/_merovingian/oauth2/` (ADR-0773, ADR-0775). +* `server.oauth.legacy_api_enabled`, `server.oauth.device_grant_enabled` and `server.oauth.hand_off_redirect_allowlist` + (https origins or bare private-use schemes, never prefixes) are parsed and checked; all need a restart (ADR-0774). +* With OAuth on, `server.public_baseurl` must be an https URL with a host and no query, and + `server.sso.authorization_url` is refused. ## Security Fixes @@ -30,9 +36,9 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Release notes -1.1.0 is in development and so far holds only the plan for the OAuth 2.0 API and the decisions behind it. When the -feature lands, a configuration that sets any `server.oidc.*` key will be refused at start-up: remove those keys and -set `server.oauth.enabled` instead. +1.1.0 is in development. A configuration that sets any `server.oidc.*` key is now refused at start-up: remove those +keys and set `server.oauth.enabled` instead (ADR-0764). The metadata names the authorisation, token, registration and +revocation endpoints, which later 1.1.0 changes serve; leave `server.oauth.enabled` off until then. # Version 1.0.2 diff --git a/config/merovingian.conf.bsd.example b/config/merovingian.conf.bsd.example index 03150b5a5..ea428618c 100644 --- a/config/merovingian.conf.bsd.example +++ b/config/merovingian.conf.bsd.example @@ -629,24 +629,23 @@ security.media.decode_in_sandbox=true # server.sso.identity_providers.com.example.idp.github.brand=github # server.sso.identity_providers.com.example.idp.github.icon=mxc://example.org/githubicon -# OIDC authorisation server metadata (MSC2965 discovery) -# Advertisement only: enabling this makes GET /_matrix/client/v1/auth_metadata -# return RFC 8414 metadata built from these fields. No OAuth flow is -# implemented here -- the endpoints named below belong to your authorisation -# server, and this block only tells clients where to find them. With -# enabled=false the endpoint returns 404 M_UNRECOGNIZED. -# account_management_uri and the supported-actions list are what an OAuth-aware -# client is told to send users to instead of calling POST /account/deactivate -# directly (spec: OAuth 2.0 aware clients). -# server.oidc.enabled=true -# server.oidc.issuer=https://auth.example.org/ -# server.oidc.authorization_endpoint=https://auth.example.org/authorize -# server.oidc.token_endpoint=https://auth.example.org/token -# server.oidc.registration_endpoint=https://auth.example.org/register -# server.oidc.revocation_endpoint=https://auth.example.org/revoke -# server.oidc.device_authorization_endpoint=https://auth.example.org/device -# server.oidc.account_management_uri=https://auth.example.org/account -# server.oidc.account_management_actions_supported=org.matrix.profile,org.matrix.sessions_list,org.matrix.account_deactivate +# OAuth 2.0 API (Matrix v1.19 "OAuth 2.0 API"), off by default. +# With enabled=true, GET /_matrix/client/v1/auth_metadata (and its MSC2965 +# unstable path) returns the server metadata, and server.public_baseurl must be +# an https URL with no query: the issuer is that URL and every OAuth endpoint +# sits under it at /_merovingian/oauth2/. Cannot be combined with +# server.sso.authorization_url. Every key here needs a restart. +# legacy_api_enabled=false (only with enabled=true) turns off the legacy +# /login and /register API. device_grant_enabled=true (only with enabled=true) +# advertises the device authorization grant. +# hand_off_redirect_allowlist (only with enabled=true, at most 32 entries) lists +# https origins (https://app.example.org) and bare private-use schemes +# (io.element.app:) a hand-off may return to; never a URL prefix. +# The former server.oidc.* keys are refused at start-up. +# server.oauth.enabled=false +# server.oauth.legacy_api_enabled=true +# server.oauth.device_grant_enabled=false +# server.oauth.hand_off_redirect_allowlist= # Application Services (Matrix v1.19 Application Service API) # Each path is a registration document describing one appservice: its as_token, diff --git a/config/merovingian.conf.example b/config/merovingian.conf.example index e7849d50b..0ed52eebf 100644 --- a/config/merovingian.conf.example +++ b/config/merovingian.conf.example @@ -602,24 +602,23 @@ security.media.decode_in_sandbox=true # server.sso.identity_providers.com.example.idp.github.brand=github # server.sso.identity_providers.com.example.idp.github.icon=mxc://example.org/githubicon -# OIDC authorisation server metadata (MSC2965 discovery) -# Advertisement only: enabling this makes GET /_matrix/client/v1/auth_metadata -# return RFC 8414 metadata built from these fields. No OAuth flow is -# implemented here -- the endpoints named below belong to your authorisation -# server, and this block only tells clients where to find them. With -# enabled=false the endpoint returns 404 M_UNRECOGNIZED. -# account_management_uri and the supported-actions list are what an OAuth-aware -# client is told to send users to instead of calling POST /account/deactivate -# directly (spec: OAuth 2.0 aware clients). -# server.oidc.enabled=true -# server.oidc.issuer=https://auth.example.org/ -# server.oidc.authorization_endpoint=https://auth.example.org/authorize -# server.oidc.token_endpoint=https://auth.example.org/token -# server.oidc.registration_endpoint=https://auth.example.org/register -# server.oidc.revocation_endpoint=https://auth.example.org/revoke -# server.oidc.device_authorization_endpoint=https://auth.example.org/device -# server.oidc.account_management_uri=https://auth.example.org/account -# server.oidc.account_management_actions_supported=org.matrix.profile,org.matrix.sessions_list,org.matrix.account_deactivate +# OAuth 2.0 API (Matrix v1.19 "OAuth 2.0 API"), off by default. +# With enabled=true, GET /_matrix/client/v1/auth_metadata (and its MSC2965 +# unstable path) returns the server metadata, and server.public_baseurl must be +# an https URL with no query: the issuer is that URL and every OAuth endpoint +# sits under it at /_merovingian/oauth2/. Cannot be combined with +# server.sso.authorization_url. Every key here needs a restart. +# legacy_api_enabled=false (only with enabled=true) turns off the legacy +# /login and /register API. device_grant_enabled=true (only with enabled=true) +# advertises the device authorization grant. +# hand_off_redirect_allowlist (only with enabled=true, at most 32 entries) lists +# https origins (https://app.example.org) and bare private-use schemes +# (io.element.app:) a hand-off may return to; never a URL prefix. +# The former server.oidc.* keys are refused at start-up. +# server.oauth.enabled=false +# server.oauth.legacy_api_enabled=true +# server.oauth.device_grant_enabled=false +# server.oauth.hand_off_redirect_allowlist= # Application Services (Matrix v1.19 Application Service API) # Each path is a registration document describing one appservice: its as_token, diff --git a/docs/adr/0773-the-oauth-issuer-is-public-baseurl-and-the-routes-live-under-merovingian.md b/docs/adr/0773-the-oauth-issuer-is-public-baseurl-and-the-routes-live-under-merovingian.md new file mode 100644 index 000000000..eb94ab3ee --- /dev/null +++ b/docs/adr/0773-the-oauth-issuer-is-public-baseurl-and-the-routes-live-under-merovingian.md @@ -0,0 +1,44 @@ +# The OAuth issuer is `server.public_baseurl`, and the routes live under `/_merovingian/` + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: proposal P1 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +The spec fixes only the discovery paths (`/_matrix/client/v1/auth_metadata` and its MSC2965 unstable path). The issuer +and every other OAuth address are whatever the metadata advertises. Where do they come from, and where do the +endpoints and pages live? + +## Considered Options + +* The issuer is `server.public_baseurl`; endpoints and pages live under `/_merovingian/oauth2/` and the account page at + `/_merovingian/account`. +* A separately configured issuer and endpoint addresses. +* Endpoints at the root (`/authorize`, `/token`), as many standalone authorisation servers do. + +## Decision Outcome + +Chosen option: the first. `oauth::OAuthBaseUrl` reads `server.public_baseurl` (an `https` URL with a host and no +query; a path is allowed, and the scheme must be lowercase). `issuer()` is that URL with exactly one trailing slash, +and `url(path)` is that URL with its trailing slashes removed plus a constant from `oauth/OAuthPaths.hpp`. No other +code builds an OAuth address. With `server.oauth.enabled=true`, a `public_baseurl` the reader refuses fails +validation at start-up, naming both keys. + +### Positive Consequences + +* The metadata cannot name an address the server does not serve: one builder and one table of paths. +* A namespace this server owns cannot collide with `/_matrix/` or with a site the operator serves at `/`. +* A reverse proxy that already forwards `/_matrix/` needs one more prefix, `/_merovingian/`. + +### Negative Consequences + +* An operator who hosts Merovingian under a path must forward `//_merovingian/` too. +* Moving a route later changes an address clients may have cached; the paths are fixed in one header so a change is + deliberate. + +## Links + +* Refines [ADR-0764](0764-server-oauth-replaces-server-oidc-and-the-old-keys-are-refused.md) diff --git a/docs/adr/0774-a-hand-off-allowlist-entry-is-an-https-origin-or-a-bare-private-use-scheme-never-a-prefix.md b/docs/adr/0774-a-hand-off-allowlist-entry-is-an-https-origin-or-a-bare-private-use-scheme-never-a-prefix.md new file mode 100644 index 000000000..264db2673 --- /dev/null +++ b/docs/adr/0774-a-hand-off-allowlist-entry-is-an-https-origin-or-a-bare-private-use-scheme-never-a-prefix.md @@ -0,0 +1,37 @@ +# A hand-off allowlist entry is an https origin or a bare private-use scheme, never a prefix + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: `server.oauth.hand_off_redirect_allowlist`, [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +A hand-off returns the user to an application the operator trusts. The allowlist names those applications. What +shape may an entry take, and how is a target compared with it? + +## Considered Options + +* An https origin (`https://app.example.org`, an optional non-default port) or a bare private-use scheme with its + colon (`io.element.app:`), compared by origin or by scheme. +* A URL prefix, compared with `starts_with`. +* Any URL, compared byte for byte. + +## Decision Outcome + +Chosen option: the first. `oauth::hand_off_allowlist_entry_error` reads an entry with `ParsedUri::read` and refuses +anything else: a path (even `/`), a query, a fragment, userinfo, an explicit `:443`, an upper-case letter, a scheme +other than `https` with an authority, and a bare scheme with more than its colon or without a `.` (RFC 8252 section +7.1; this also refuses `http:`, `https:`, `javascript:` and `data:`). The list holds at most 32 entries, each once, +and is refused unless `server.oauth.enabled=true`. Entries are refused, never repaired. + +### Positive Consequences + +* A prefix match of `https://app.example.com` accepts `https://app.example.com.evil.example` and + `https://app.example.com@evil.example`; an origin comparison cannot. +* One spelling per entry, so a duplicate or a case variant cannot hide in the list. + +### Negative Consequences + +* An operator cannot limit a hand-off to one path of an origin; the whole origin is trusted. diff --git a/docs/adr/0775-auth-metadata-stays-in-the-generic-rate-limit-tier.md b/docs/adr/0775-auth-metadata-stays-in-the-generic-rate-limit-tier.md new file mode 100644 index 000000000..5edeba7dc --- /dev/null +++ b/docs/adr/0775-auth-metadata-stays-in-the-generic-rate-limit-tier.md @@ -0,0 +1,35 @@ +# `auth_metadata` stays in the generic rate-limit tier + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 2 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), which put every OAuth route in the +`auth_sensitive` tier + +## Context and Problem Statement + +The plan put every new OAuth route in the `auth_sensitive` rate-limit tier (20 requests a minute per client). One of +them, `GET /_matrix/client/v1/auth_metadata` and its MSC2965 path, is read-only, unauthenticated, holds nothing +secret, and the spec marks it "Rate-limited: No". Element X reads it on every server probe, often from many devices +behind one address. Which tier does it take? + +## Considered Options + +* The generic tier, like the other unauthenticated discovery endpoints (`/versions`, `/login` flows). +* The `auth_sensitive` tier, as the plan said. +* No rate limit at all. + +## Decision Outcome + +Chosen option: the generic tier. `http::rate_limit_tier_for` has no entry for the two paths, so they fall to the +generic tier; the registration, token, revocation and device endpoints still take `auth_sensitive` when they land. + +### Positive Consequences + +* A household or office behind one NAT address cannot lock itself out of login discovery. +* The connection and request limits that protect every route still apply. + +### Negative Consequences + +* Unlike the spec's "No", requests are still counted; a client far above 600 a minute gets 429. diff --git a/docs/adr/index.md b/docs/adr/index.md index 37b9a892b..3f4ef45d5 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -654,3 +654,6 @@ * [0770 - OAuth addresses are read by a strict reader of our own and matched byte for byte](0770-oauth-addresses-are-read-by-a-strict-reader-of-our-own-and-matched-byte-for-byte.md) * [0771 - OAuth client metadata rules, and its canonical form](0771-oauth-client-metadata-rules-and-its-canonical-form.md) * [0772 - Page text is escaped by type, and the page policy names only a validated redirect origin](0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md) +* [0773 - The OAuth issuer is `server.public_baseurl`, and the routes live under `/_merovingian/`](0773-the-oauth-issuer-is-public-baseurl-and-the-routes-live-under-merovingian.md) +* [0774 - A hand-off allowlist entry is an https origin or a bare private-use scheme, never a prefix](0774-a-hand-off-allowlist-entry-is-an-https-origin-or-a-bare-private-use-scheme-never-a-prefix.md) +* [0775 - `auth_metadata` stays in the generic rate-limit tier](0775-auth-metadata-stays-in-the-generic-rate-limit-tier.md) diff --git a/docs/architecture.md b/docs/architecture.md index 00201a41b..7bb20b73b 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -642,7 +642,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. -- **Other**: `GET /capabilities`, `GET /voip/turnServer`, MSC2965 OIDC discovery +- **Other**: `GET /capabilities`, `GET /voip/turnServer`, OAuth 2.0 server metadata (`auth_metadata`, ADR-0773) ## Sync subsystem diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 93d955d62..abbfea89b 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -156,7 +156,7 @@ production-gated. (issue #437), had no caller and was removed. - Client-server auth/device/key actions append durable audit rows without logging plaintext credentials, bearer tokens, or key payloads. -- `GET /_matrix/client/v1/auth_metadata` (MSC2965 OIDC discovery) returns RFC 8414 / Matrix v1.19 authorisation server metadata when `server.oidc.*` is configured; returns `404 M_UNRECOGNIZED` when OIDC is not configured. No OAuth 2.0 authorization-code / token / revocation flow is implemented yet. +- `GET /_matrix/client/v1/auth_metadata` (and its MSC2965 unstable path) returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. `oauth::server_metadata` builds the document and every address in it comes from `oauth::OAuthBaseUrl`: the issuer is `server.public_baseurl` with one trailing slash and the endpoints sit under `/_merovingian/oauth2/` (ADR-0773). The endpoint is unauthenticated, carries CORS headers and stays in the generic rate-limit tier (ADR-0775). The authorization, token, registration and revocation endpoints it names are not served yet; they land in later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). The former `server.oidc.*` keys are refused at start-up. - **Application Service API identity (Matrix v1.19, `merovingian::appservice`).** Registration files (`appservice.registration_files`, parsed as JSON) build an in-memory `AppserviceRegistry` at startup in the main process only (the federation worker diff --git a/docs/matrix-v1.19-client-server-api.md b/docs/matrix-v1.19-client-server-api.md index bd2a185b9..2e1a5ec46 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -393,7 +393,7 @@ lists have no server maximum (ADR-0332). | --- | --- | --- | --- | --- | --- | | `GET` | `/_matrix/client/v1/auth_metadata` | `getAuthMetadata` | none | - | 200, 404 | -Implemented: returns RFC 8414 metadata when `server.oidc.*` is configured; `404 M_UNRECOGNIZED` otherwise. +Implemented: returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. The MSC2965 path `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answers the same. The endpoints the document names are served from later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). | `POST` | `/_matrix/client/v1/login/get_token` | `generateLoginToken` | access token | required application/json | 200, 400, 401, 429 | | `GET` | `/_matrix/client/v3/account/whoami` | `getTokenOwner` | access token | - | 200, 401, 403, 429 | | `GET` | `/_matrix/client/v3/login` | `getLoginFlows` | none | - | 200, 404, 429 | diff --git a/docs/todos/capability-gaps.md b/docs/todos/capability-gaps.md index 301b101b2..50e410a29 100644 --- a/docs/todos/capability-gaps.md +++ b/docs/todos/capability-gaps.md @@ -47,7 +47,7 @@ When adding a capability, record what is *missing* as explicitly as what works. | Endpoint | Status | Needs | | --- | --- | --- | -| `GET /_matrix/client/v1/auth_metadata`, MSC2965 OIDC | `spec-covered` | Discovery metadata implemented. The full OAuth 2.0 flow is planned for 1.1.0: see the [OAuth 2.0 API plan](oauth-2-0-api.md). | +| `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. The endpoints it names are later phases of the [OAuth 2.0 API plan](oauth-2-0-api.md). | | `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). | | 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. | | Room summary over federation | `runtime-wired` | `GET /v1/room_summary/{roomIdOrAlias}?via=` asks up to 3 `via` servers over federation `GET /hierarchy/{roomId}` (the `room` chunk; v1.19 defines no federation summary route) for a room this server holds no state for (ADR-0556): one ADR-0079 slot (429 at once without one, also without a token), one deadline, unverified answer, shown only by its own `join_rule` / `world_readable` / `allowed_room_ids`. Local state always wins; a malformed `via` is `400 M_INVALID_PARAM`. Not implemented: resolving an alias that lives on another server (404 / 401), and `membership` for a room not held locally. | diff --git a/docs/todos/oauth-2-0-api.md b/docs/todos/oauth-2-0-api.md index e554703b9..181434ae7 100644 --- a/docs/todos/oauth-2-0-api.md +++ b/docs/todos/oauth-2-0-api.md @@ -136,7 +136,7 @@ lifetime of a code, rate limits, and what a revocation does to the device. | Route | Method | Purpose | |---|---|---| -| `/_matrix/client/v1/auth_metadata` | GET | Metadata. Also served at `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata`, which today is a fixed 404. | +| `/_matrix/client/v1/auth_metadata` | GET | Metadata. Also served at `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata`, with the same document. | | `/_merovingian/oauth2/register` | POST | Client registration, JSON. | | `/_merovingian/oauth2/authorize` | GET, POST | The authorisation request, then the login, registration and consent forms. | | `/_merovingian/oauth2/token` | POST | Code, refresh and device-code grants, form-encoded. | @@ -148,13 +148,13 @@ lifetime of a code, rate limits, and what a revocation does to the device. Every route needs what `src/homeserver/AGENTS.md` lists under "Adding a new client-server endpoint": a handler ahead of the 405 and 404 gates, a `static_routes` entry, a `client_static_route_allow` row naming every method, a row in `tests/conformance/test_route_query_conformance.cpp`, and a rate-limit tier. All of them take the `auth_sensitive` -tier. `auth_metadata`, the registration, token, revocation and device endpoints carry the CORS headers; the pages +tier except `auth_metadata`, which the spec marks not rate-limited and stays in the generic tier (ADR-0775). `auth_metadata`, the registration, token, revocation and device endpoints carry the CORS headers; the pages carry none. ### Module layout - **`src/oauth/` and `include/merovingian/oauth/`**: a new module of pure functions with no runtime state. It holds - the metadata builder (replacing `auth/OidcDiscovery`), client metadata and redirect URI validation, the scope + the metadata builder (`ServerMetadata`, which replaced `auth/OidcDiscovery`), client metadata and redirect URI validation, the scope parser, PKCE verification and the page renderer. It gets an `AGENTS.md`, a `CLAUDE.md` and rows in the root `AGENTS.md`. - **`src/core/`**: a strict `application/x-www-form-urlencoded` parser (a malformed escape or a repeated parameter diff --git a/docs/user-manual.md b/docs/user-manual.md index dd6d0ea8f..975230024 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -493,7 +493,7 @@ change them. | Key | Default | When to change | |---|---|---| | `server.name` | `example.org` | **Required.** The Matrix server name used in user IDs and federation. Must match the host part served by your reverse proxy. The shipped `config/merovingian.conf.example` sets `matrix.example.org`. | -| `server.public_baseurl` | `https://matrix.example.org` | **Required.** The HTTPS URL clients use. Must be HTTPS. | +| `server.public_baseurl` | `https://matrix.example.org` | **Required.** The HTTPS URL clients use. Must be HTTPS. With `server.oauth.enabled=true` it is also the OAuth issuer, and must have a host and no query, fragment or userinfo. | | `server.trusted_proxies` | (empty) | **Required behind a reverse proxy.** Comma-separated list of proxy IPs whose `X-Forwarded-For` header is trusted for rate limiting. Without this, every client shares one per-IP bucket. The client is the rightmost `X-Forwarded-For` entry that is not itself a trusted proxy (ADR-0073), so a proxy may append to the header or overwrite it; list every proxy hop you control. The shipped example sets `127.0.0.1`. | #### CORS policy — `server.cors.*` @@ -822,24 +822,44 @@ support. > Set the same value as coturn's `static-auth-secret`, and keep > `server.turn.ttl_seconds` at or below coturn's own limits. -#### OIDC discovery — `server.oidc.*` - -`GET /_matrix/client/v1/auth_metadata` (MSC2965) returns 404 `M_UNRECOGNIZED` -until `server.oidc.enabled=true`. Merovingian does not implement an OAuth 2.0 -authorization server itself — these keys only describe an external one for -clients to discover. +#### OAuth 2.0 API — `server.oauth.*` + +Merovingian has a built-in OAuth 2.0 API (Matrix v1.19 "OAuth 2.0 API"), which +clients such as Element X use to create accounts and log in through pages the +homeserver serves. It is **off by default**: `GET /_matrix/client/v1/auth_metadata` +and its unstable form `GET /_matrix/client/unstable/org.matrix.msc2965/auth_metadata` +answer `404 M_UNRECOGNIZED`, as the spec asks of a server without the API. With +`server.oauth.enabled=true` both answer the server metadata. In 1.1.0 the API +is being built in phases; this release serves the metadata, and the endpoints it +names follow. Until they do, a client that follows the metadata cannot log in, +so leave the API off. + +No address is configured. The issuer is `server.public_baseurl` with one +trailing slash, and every endpoint is under it: `/_merovingian/oauth2/register`, +`/_merovingian/oauth2/authorize`, `/_merovingian/oauth2/token`, +`/_merovingian/oauth2/revoke`, `/_merovingian/oauth2/device` and +`/_merovingian/account` (ADR-0773). A reverse proxy in front of the server must +pass `/_merovingian/oauth2/` and `/_merovingian/account` through, as it does +`/_matrix/`. | Key | Default | When to change | |---|---|---| -| `server.oidc.enabled` | `false` | Set `true` once the endpoints below point at a real OIDC provider. | -| `server.oidc.issuer` | (empty) | **Required when enabled.** Must be a valid HTTPS URL with no query or fragment. | -| `server.oidc.authorization_endpoint` | (empty) | The provider's authorization endpoint. | -| `server.oidc.token_endpoint` | (empty) | The provider's token endpoint. | -| `server.oidc.registration_endpoint` | (empty) | The provider's dynamic client registration endpoint, if supported. | -| `server.oidc.revocation_endpoint` | (empty) | The provider's token revocation endpoint, if supported. | -| `server.oidc.device_authorization_endpoint` | (empty) | The provider's device authorization endpoint, if supported. | -| `server.oidc.account_management_uri` | (empty) | A user-facing account management page, if the provider offers one. | -| `server.oidc.account_management_actions_supported` | (empty) | Comma-separated list of account-management actions the URI above supports. | +| `server.oauth.enabled` | `false` | Set `true` to serve the OAuth 2.0 API. `server.public_baseurl` must then be an `https` URL with a host and no query, fragment or userinfo (a path is allowed), and `server.sso.authorization_url` must be empty. | +| `server.oauth.legacy_api_enabled` | `true` | Set `false` to stop the legacy login and registration API issuing new sessions to users (ADR-0761). Refused unless `server.oauth.enabled=true`, so users always have a way to log in. Checked now, acted on once the OAuth login pages land. | +| `server.oauth.device_grant_enabled` | `false` | Set `true` to offer the device authorization grant (RFC 8628): the metadata then lists the device code grant type and `device_authorization_endpoint`. Refused unless `server.oauth.enabled=true`. | +| `server.oauth.hand_off_redirect_allowlist` | (empty) | Comma-separated places the hand-off from the legacy SSO redirect may send the browser: `https` origins (`https://app.example.com`, `https://app.example.com:8443`, nothing after the host or port) and bare private-use schemes (`io.element.app:`), in lower case. Never a URL prefix (ADR-0774). At most 32 entries, none twice. Refused unless `server.oauth.enabled=true`. Checked now, used once the hand-off lands. | + +The metadata offers `prompt=create` (`prompt_values_supported`) only while +`security.registration.enabled=true`: account creation through the pages +follows the legacy registration settings (ADR-0762). + +Every `server.oauth.*` key needs a restart. + +**`server.oidc.*` is refused.** Before 1.1.0 these keys made `auth_metadata` +advertise an external authorisation server that Merovingian could not log +anyone in through. A configuration that still sets any `server.oidc.*` key does +not start; the message names `server.oauth.enabled`. Delete those lines, and set +`server.oauth.enabled=true` if you want the built-in API (ADR-0764). #### Identity Service API — `server.identity_server.*` @@ -868,8 +888,8 @@ is not possible. 3PIDs are not used for login or password reset. Push Gateway API delivery (Matrix v1.19 push-gateway-api / CS API push-notifications module) is **disabled by default** — pushers can still be registered via `POST /pushers/set`, but no notification is ever sent to a -gateway until `server.push.enabled=true`. This mirrors `server.oidc.enabled`'s -pattern so merging this capability cannot start sending traffic to +gateway until `server.push.enabled=true`. Like the other opt-in features, this +means merging this capability cannot start sending traffic to client-supplied gateway URLs on upgrade. | Key | Default | When to change | @@ -1831,7 +1851,7 @@ take effect. | `security.password_policy.*` | Restart required | | `security.password_hashing.max_concurrent` | Restart required | | `security.logging.*` | Reloadable | -| `server.oidc.*` | Reloadable | +| `server.oauth.*` | Restart required | | `server.sso.*` | Reloadable | `--plan-config-reload ` compares two validated configs and diff --git a/include/merovingian/auth/AuthMetadata.hpp b/include/merovingian/auth/AuthMetadata.hpp deleted file mode 100644 index fa81fe280..000000000 --- a/include/merovingian/auth/AuthMetadata.hpp +++ /dev/null @@ -1,19 +0,0 @@ -// SPDX-FileCopyrightText: 2026 James Chapman -// SPDX-License-Identifier: GPL-3.0-or-later -#pragma once - -#include "merovingian/canonicaljson/Value.hpp" - -namespace merovingian::auth -{ - -// Holds the OIDC authorisation server metadata as a canonical JSON object. -// When `configured` is false the caller should return 404 M_UNRECOGNIZED; -// when true the caller should return the fields object with status 200. -struct AuthMetadata final -{ - bool configured{false}; - canonicaljson::Object fields{}; -}; - -} // namespace merovingian::auth diff --git a/include/merovingian/auth/OidcDiscovery.hpp b/include/merovingian/auth/OidcDiscovery.hpp deleted file mode 100644 index d9e043474..000000000 --- a/include/merovingian/auth/OidcDiscovery.hpp +++ /dev/null @@ -1,17 +0,0 @@ -// SPDX-FileCopyrightText: 2026 James Chapman -// SPDX-License-Identifier: GPL-3.0-or-later - -#pragma once - -#include "merovingian/auth/AuthMetadata.hpp" -#include "merovingian/config/OidcConfig.hpp" - -namespace merovingian::auth -{ - -// Builds the Matrix v1.19 / RFC 8414 authorisation server metadata response -// from the server's OIDC configuration. All required fields are populated when -// `config.enabled` is true; optional fields are emitted only when non-empty. -[[nodiscard]] auto make_auth_metadata(config::OidcConfig const& config) -> AuthMetadata; - -} // namespace merovingian::auth diff --git a/include/merovingian/config/Config.hpp b/include/merovingian/config/Config.hpp index bebeafa72..640dcf230 100644 --- a/include/merovingian/config/Config.hpp +++ b/include/merovingian/config/Config.hpp @@ -88,7 +88,6 @@ class Config final [[nodiscard]] auto is_safe_cleartext_listener(ListenerConfig const& listener) noexcept -> bool; [[nodiscard]] auto is_valid_public_baseurl(std::string_view public_baseurl) noexcept -> bool; [[nodiscard]] auto is_valid_https_url(std::string_view url) noexcept -> bool; -[[nodiscard]] auto is_valid_https_origin_url(std::string_view url) noexcept -> bool; [[nodiscard]] auto is_valid_federation_policy(std::string_view policy) noexcept -> bool; [[nodiscard]] auto is_valid_media_acceptance_policy(std::string_view policy) noexcept -> bool; [[nodiscard]] auto is_valid_federation_server_name(std::string_view server_name) noexcept -> bool; diff --git a/include/merovingian/config/OAuthConfig.hpp b/include/merovingian/config/OAuthConfig.hpp new file mode 100644 index 000000000..c00e51abc --- /dev/null +++ b/include/merovingian/config/OAuthConfig.hpp @@ -0,0 +1,28 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::config +{ + +// `server.oauth.*`: the built-in OAuth 2.0 API (ADR-0760, ADR-0764). Off by default. Its addresses are not configured: +// every one is derived from `server.public_baseurl` (ADR-0773). validate() refuses each non-default value of the last +// three fields unless `enabled` is true, so a configuration cannot half-enable the API. +struct OAuthConfig final +{ + // Serves the OAuth 2.0 API: the metadata at `auth_metadata` and, in later phases, its endpoints and pages. + bool enabled{false}; + // With false the legacy login and registration API refuses new user sessions (ADR-0761). + bool legacy_api_enabled{true}; + // Serves the device authorization grant (RFC 8628), off by default because it lets an attacker start a login + // and send the victim the link. + bool device_grant_enabled{false}; + // Where the hand-off from the legacy SSO redirect may send the browser: `https` origins and bare private-use + // schemes, never URL prefixes (ADR-0774). Empty: any target, after the confirmation page. + std::vector hand_off_redirect_allowlist{}; +}; + +} // namespace merovingian::config diff --git a/include/merovingian/config/OidcConfig.hpp b/include/merovingian/config/OidcConfig.hpp deleted file mode 100644 index d4fa0ef0a..000000000 --- a/include/merovingian/config/OidcConfig.hpp +++ /dev/null @@ -1,28 +0,0 @@ -// SPDX-FileCopyrightText: 2026 James Chapman -// SPDX-License-Identifier: GPL-3.0-or-later -#pragma once - -#include -#include - -namespace merovingian::config -{ - -// OIDC authorisation server metadata configuration for MSC2965 discovery. -// When `enabled` is false, GET /_matrix/client/v1/auth_metadata returns -// 404 M_UNRECOGNIZED. When enabled, the endpoint returns RFC 8414 metadata -// built from these fields; no actual OAuth flow is implemented here. -struct OidcConfig final -{ - bool enabled{false}; - std::string issuer{}; - std::string authorization_endpoint{}; - std::string token_endpoint{}; - std::string registration_endpoint{}; - std::string revocation_endpoint{}; - std::string device_authorization_endpoint{}; - std::string account_management_uri{}; - std::vector account_management_actions_supported{}; -}; - -} // namespace merovingian::config diff --git a/include/merovingian/config/PushConfig.hpp b/include/merovingian/config/PushConfig.hpp index e0b8f858f..234f6c832 100644 --- a/include/merovingian/config/PushConfig.hpp +++ b/include/merovingian/config/PushConfig.hpp @@ -9,7 +9,7 @@ namespace merovingian::config // Push Gateway API delivery configuration (Matrix v1.19 push-gateway-api / // CS API push-notifications module). `enabled` gates the entire outbound -// delivery path and defaults to false, mirroring OidcConfig's pattern, so +// delivery path and defaults to false, like the other opt-in server features, so // merging this capability cannot cause an existing deployment to start // sending traffic to gateways on upgrade — an operator must explicitly opt // in. Timeouts mirror IdentityServerConfig's operator-tunable connect/total diff --git a/include/merovingian/config/ServerConfig.hpp b/include/merovingian/config/ServerConfig.hpp index a8fc0b137..38f6b1176 100644 --- a/include/merovingian/config/ServerConfig.hpp +++ b/include/merovingian/config/ServerConfig.hpp @@ -7,7 +7,7 @@ #include "merovingian/config/EmailConfig.hpp" #include "merovingian/config/HttpTransportConfig.hpp" #include "merovingian/config/IdentityServerConfig.hpp" -#include "merovingian/config/OidcConfig.hpp" +#include "merovingian/config/OAuthConfig.hpp" #include "merovingian/config/PushConfig.hpp" #include "merovingian/config/SsoConfig.hpp" #include "merovingian/config/TurnServerConfig.hpp" @@ -37,9 +37,8 @@ struct ServerConfig final // TURN relay configuration for GET /_matrix/client/v3/voip/turnServer. // Empty by default; when populated the endpoint returns real credentials. TurnServerConfig turn{}; - // OIDC discovery metadata. Empty by default; when populated the - // auth_metadata endpoint advertises the configured OAuth 2.0 server. - OidcConfig oidc{}; + // The built-in OAuth 2.0 API. Off by default (see OAuthConfig). + OAuthConfig oauth{}; // Identity Service API client config for 3PID invites/bind/unbind/ // requestToken. Empty by default; with no trusted servers the homeserver // refuses 3PID operations that need an IS rather than minting locally. diff --git a/include/merovingian/config/SsoConfig.hpp b/include/merovingian/config/SsoConfig.hpp index 7c923c922..2b6a889d7 100644 --- a/include/merovingian/config/SsoConfig.hpp +++ b/include/merovingian/config/SsoConfig.hpp @@ -11,7 +11,7 @@ namespace merovingian::config { // SSO login configuration (Matrix v1.19 CS API §"Client login via SSO"). -// Disabled by default, mirroring OidcConfig's opt-in pattern. `enabled` +// Disabled by default, like the other opt-in server features. `enabled` // gates both advertising `m.login.sso` from `GET /login` and routing // `GET /login/sso/redirect[/{idpId}]` — a misconfigured or disabled SSO // setup fails closed (flow not advertised, redirect endpoints 404) rather diff --git a/include/merovingian/oauth/HandOffAllowlist.hpp b/include/merovingian/oauth/HandOffAllowlist.hpp new file mode 100644 index 000000000..8fd07735a --- /dev/null +++ b/include/merovingian/oauth/HandOffAllowlist.hpp @@ -0,0 +1,36 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/core/Error.hpp" + +#include +#include +#include +#include +#include + +namespace merovingian::oauth +{ + +// The most entries `server.oauth.hand_off_redirect_allowlist` may hold. The hand-off compares a redirect target with +// every entry; a short fixed list keeps that bounded and keeps the list something an operator reviews by eye. +inline constexpr std::size_t max_hand_off_allowlist_entries = 32U; + +// Why `entry` cannot be an entry of the hand-off redirect allowlist, or nothing when it can (ADR-0774). An entry is +// one of two shapes, each read with ParsedUri::read and written in lower case so a later match can be byte for byte: +// +// - an `https` origin: `https://host` or `https://host:port`, with nothing after the authority (no path, not even +// `/`, no query) and no explicit `:443`, which would be a second spelling of the same origin; +// - a bare private-use scheme followed by its colon (`io.element.app:`): no authority, path or query. The scheme +// holds a `.`, as RFC 8252 asks of a private-use scheme, which also refuses `http:`, `https:`, `javascript:` and +// every other scheme with a general meaning. +// +// Never a URL prefix: a prefix match accepts `https://app.example.com.evil.example`. The message is fixed text. +[[nodiscard]] auto hand_off_allowlist_entry_error(std::string_view entry) -> std::optional; + +// Why `entries` cannot be the hand-off redirect allowlist, or nothing when it can: each entry as above, no entry +// twice, at most max_hand_off_allowlist_entries. An empty list is valid. +[[nodiscard]] auto hand_off_allowlist_error(std::span entries) -> std::optional; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/OAuthBaseUrl.hpp b/include/merovingian/oauth/OAuthBaseUrl.hpp new file mode 100644 index 000000000..86044341c --- /dev/null +++ b/include/merovingian/oauth/OAuthBaseUrl.hpp @@ -0,0 +1,46 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/core/Error.hpp" +#include "merovingian/oauth/PagePath.hpp" +#include "merovingian/oauth/ParsedUri.hpp" + +#include +#include +#include + +namespace merovingian::oauth +{ + +// `server.public_baseurl` read as the base of every absolute address the OAuth 2.0 API publishes (ADR-0773). It +// exists only through read(), so it always satisfies these rules: a ParsedUri (so no userinfo, no fragment, printable +// ASCII only) with the scheme `https` in lower case, an authority, and no query. A port and a path are allowed. +// +// Every absolute URL the API publishes is built here, by url(), and the issuer by issuer(). Nothing else joins a +// path to the base URL. +class OAuthBaseUrl final +{ +public: + // `text` as the base URL, or why not, as fixed text that never quotes the input. + // ErrorCode::parse_failure: a rule above is broken. ErrorCode::invalid_argument: ParsedUri's length cap. + [[nodiscard]] static auto read(std::string_view text) -> std::variant; + + // The issuer identifier: the base URL with exactly one trailing slash (`https://h` and `https://h/` both give + // `https://h/`; `https://h/m` gives `https://h/m/`). RFC 8414 requires `https` and no query or fragment. + [[nodiscard]] auto issuer() const -> std::string; + // The absolute URL of `path` on this server: the base URL with its trailing slashes removed, then `path` + // (`https://h/m/` and `/_merovingian/oauth2/token` give `https://h/m/_merovingian/oauth2/token`). + [[nodiscard]] auto url(PagePath path) const -> std::string; + // The base URL as read. + [[nodiscard]] auto uri() const noexcept -> ParsedUri const&; + +private: + explicit OAuthBaseUrl(ParsedUri uri); + + ParsedUri m_uri; + // The text without trailing slashes, the common prefix of issuer() and url(). + std::string m_prefix{}; +}; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/OAuthPaths.hpp b/include/merovingian/oauth/OAuthPaths.hpp new file mode 100644 index 000000000..2d199381c --- /dev/null +++ b/include/merovingian/oauth/OAuthPaths.hpp @@ -0,0 +1,29 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/oauth/PagePath.hpp" + +#include + +namespace merovingian::oauth +{ + +// The paths of the OAuth 2.0 API this server serves under its own namespace (ADR-0773). The metadata advertises +// each as `OAuthBaseUrl::url(path)`, and the dispatcher routes on the same constants, so what is advertised and what +// is served cannot drift apart. Every one is a PagePath: fixed at compile time, `/`-rooted, no query. +inline constexpr auto register_path = PagePath{"/_merovingian/oauth2/register"}; +inline constexpr auto authorize_path = PagePath{"/_merovingian/oauth2/authorize"}; +inline constexpr auto token_path = PagePath{"/_merovingian/oauth2/token"}; +inline constexpr auto revoke_path = PagePath{"/_merovingian/oauth2/revoke"}; +inline constexpr auto device_path = PagePath{"/_merovingian/oauth2/device"}; +inline constexpr auto link_path = PagePath{"/_merovingian/oauth2/link"}; +inline constexpr auto account_path = PagePath{"/_merovingian/account"}; + +// The metadata document's own paths, fixed by the spec (`GET /_matrix/client/v1/auth_metadata`) and by MSC2965 for +// the unstable form. They are routed as they stand and never joined to the base URL. +inline constexpr auto auth_metadata_path = std::string_view{"/_matrix/client/v1/auth_metadata"}; +inline constexpr auto auth_metadata_unstable_path = + std::string_view{"/_matrix/client/unstable/org.matrix.msc2965/auth_metadata"}; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/ServerMetadata.hpp b/include/merovingian/oauth/ServerMetadata.hpp new file mode 100644 index 000000000..35a3b29bb --- /dev/null +++ b/include/merovingian/oauth/ServerMetadata.hpp @@ -0,0 +1,23 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/oauth/OAuthBaseUrl.hpp" +#include "merovingian/oauth/ServerMetadataOptions.hpp" + +namespace merovingian::oauth +{ + +// The OAuth 2.0 authorisation server metadata (RFC 8414) this server answers `GET /_matrix/client/v1/auth_metadata` +// with (spec "Server metadata discovery"), as a JSON object. Every address comes from `base` (issuer() and url() over +// the paths in OAuthPaths.hpp), so the document cannot name an endpoint the server does not route. +// +// Always present: `issuer`, `authorization_endpoint`, `token_endpoint`, `registration_endpoint`, +// `revocation_endpoint`, `response_types_supported` (`code`), `response_modes_supported` (`query`, `fragment`), +// `grant_types_supported` (`authorization_code`, `refresh_token`) and `code_challenge_methods_supported` (`S256`). +// The rest follows `options`. +[[nodiscard]] auto server_metadata(OAuthBaseUrl const& base, ServerMetadataOptions const& options) + -> canonicaljson::Value; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/ServerMetadataOptions.hpp b/include/merovingian/oauth/ServerMetadataOptions.hpp new file mode 100644 index 000000000..bb50c0040 --- /dev/null +++ b/include/merovingian/oauth/ServerMetadataOptions.hpp @@ -0,0 +1,26 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::oauth +{ + +// What the OAuth 2.0 server metadata advertises beyond its fixed part. The caller fills it from the configuration; +// every field defaults to "not offered". +struct ServerMetadataOptions final +{ + // `server.oauth.device_grant_enabled`: adds the device code grant type and `device_authorization_endpoint`. + bool device_grant_enabled{false}; + // `security.registration.enabled`: adds `prompt_values_supported: ["create"]`. The field is left out otherwise, + // so a client never offers account creation the registration page would refuse (ADR-0762). + bool registration_enabled{false}; + // The account management actions the account page implements, in the order to advertise. Empty leaves out both + // `account_management_uri` and `account_management_actions_supported`; the account pages arrive in phase 8, and + // until then nothing passes an action. + std::vector account_management_actions{}; +}; + +} // namespace merovingian::oauth diff --git a/src/auth/AGENTS.md b/src/auth/AGENTS.md index 382760d19..6b4495e1f 100644 --- a/src/auth/AGENTS.md +++ b/src/auth/AGENTS.md @@ -11,7 +11,6 @@ Spec authority: ../../docs/matrix-v1.19-spec/client-server-api.md | `Token.cpp` | Token hashing (`hash_access_token_v2/v3/v4`), constant-time comparison | | `Identity.cpp` | Validation of user IDs, localparts, device IDs and server names; login policy | | `Password.cpp` | Argon2id hashing and verification of passwords and registration tokens | -| `OidcDiscovery.cpp` | OIDC / RFC 8414 authorisation-server metadata built from `config::OidcConfig` | | `FailureWindowTable.cpp` | `FailureWindowTable`: the bounded, time-ordered failure counters behind the failed-login throttle (100 000 entries, fixed-size BLAKE2b-256 keys via `make_failure_key`, O(1) expiry from the front, oldest evicted when full). Not thread-safe: the runtime mutex serialises it. Used for (account, source), per-account and (account, device) UIA counters | | `KeyApi.cpp` | `/_matrix/client/v3/keys/upload`, `/query`, `/claim` — E2EE key management | diff --git a/src/auth/OidcDiscovery.cpp b/src/auth/OidcDiscovery.cpp deleted file mode 100644 index 16ef93b13..000000000 --- a/src/auth/OidcDiscovery.cpp +++ /dev/null @@ -1,92 +0,0 @@ -// SPDX-FileCopyrightText: 2026 James Chapman -// SPDX-License-Identifier: GPL-3.0-or-later - -#include "merovingian/auth/OidcDiscovery.hpp" - -#include "merovingian/auth/AuthMetadata.hpp" -#include "merovingian/canonicaljson/ObjectMember.hpp" -#include "merovingian/canonicaljson/Value.hpp" - -#include -#include -#include -#include - -namespace merovingian::auth -{ -namespace -{ - - [[nodiscard]] auto json_str(std::string_view value) -> canonicaljson::Value - { - return canonicaljson::Value{std::string{value}}; - } - - [[nodiscard]] auto json_arr(std::vector items) -> canonicaljson::Value - { - auto array = canonicaljson::Array{}; - array.reserve(items.size()); - for (auto const item : items) - { - array.emplace_back(json_str(item)); - } - return canonicaljson::Value{std::move(array)}; - } - - [[nodiscard]] auto json_member(std::string key, canonicaljson::Value value) -> canonicaljson::ObjectMember - { - return canonicaljson::make_member(std::move(key), std::move(value)); - } - -} // namespace - -auto make_auth_metadata(config::OidcConfig const& config) -> AuthMetadata -{ - if (!config.enabled) - { - return {}; - } - - auto fields = canonicaljson::Object{}; - - // Required by RFC 8414 / Matrix v1.19. - fields.emplace_back(json_member("issuer", json_str(config.issuer))); - fields.emplace_back(json_member("authorization_endpoint", json_str(config.authorization_endpoint))); - fields.emplace_back(json_member("token_endpoint", json_str(config.token_endpoint))); - fields.emplace_back(json_member("registration_endpoint", json_str(config.registration_endpoint))); - fields.emplace_back(json_member("revocation_endpoint", json_str(config.revocation_endpoint))); - - fields.emplace_back(json_member("response_types_supported", json_arr({"code"}))); - fields.emplace_back(json_member("response_modes_supported", json_arr({"query", "fragment"}))); - fields.emplace_back(json_member("code_challenge_methods_supported", json_arr({"S256"}))); - fields.emplace_back(json_member("grant_types_supported", json_arr({"authorization_code", "refresh_token"}))); - - // Optional device-authorization grant endpoint (RFC 8628). - if (!config.device_authorization_endpoint.empty()) - { - fields.emplace_back( - json_member("device_authorization_endpoint", json_str(config.device_authorization_endpoint))); - } - - // Optional account management URI and supported actions (Matrix v1.19 extension). - if (!config.account_management_uri.empty()) - { - fields.emplace_back(json_member("account_management_uri", json_str(config.account_management_uri))); - - if (!config.account_management_actions_supported.empty()) - { - auto actions = canonicaljson::Array{}; - actions.reserve(config.account_management_actions_supported.size()); - for (auto const& action : config.account_management_actions_supported) - { - actions.emplace_back(json_str(action)); - } - fields.emplace_back( - json_member("account_management_actions_supported", canonicaljson::Value{std::move(actions)})); - } - } - - return {true, std::move(fields)}; -} - -} // namespace merovingian::auth diff --git a/src/auth/meson.build b/src/auth/meson.build index 1eafe0365..a1ea90e24 100644 --- a/src/auth/meson.build +++ b/src/auth/meson.build @@ -4,7 +4,6 @@ auth_sources = files( 'FailureWindowTable.cpp', 'Identity.cpp', 'KeyApi.cpp', - 'OidcDiscovery.cpp', 'Password.cpp', 'Session.cpp', 'Token.cpp', diff --git a/src/config/AGENTS.md b/src/config/AGENTS.md index 45d14bf6a..3f6eb3f18 100644 --- a/src/config/AGENTS.md +++ b/src/config/AGENTS.md @@ -10,7 +10,7 @@ Parses and validates the server configuration and plans (but does not yet apply) | `ConfigParser.cpp` | Parses the key-value `.conf` file into `Config`; validates ranges and required fields | | `RuntimeConfigSnapshot.cpp` | `RuntimeConfigSnapshot`: holds a `Config` and can swap it for a reload-only candidate. Only the unit tests construct it today; the server does not | | `ReloadPlan.cpp` | Diffs old vs new config and classifies each change; used by `--plan-config-reload`. No live reload path (SIGHUP/admin socket) exists yet | -| `ReloadPolicy.cpp` | `reload_policy_for_key()`: which keys need a restart. Keys are reloadable by default. Restart is required for `server.name`, the `database.*` URI and role keys, listener TLS certificate/key and `reverse_proxy` keys, `security.registration.token_file`, `database.pool_size`, `security.media.thumbnail_cache_size`, `security.media.thumbnail_max_concurrent_per_user`, `security.secrets.master_key_file`, `security.federation.key_resolution_*`, `security.federation.join_response_max_size`, `client_rate_limits.*`, `log_modules.*`, `federation.worker.*`, `server.cors.*`, `server.http.*`, `server.identity_server.*`, `server.push.*`, `appservice.*` and `presence.*`. The rate-limit engine and per-module log map are built once at start-up, so they are not hot-reloadable. | +| `ReloadPolicy.cpp` | `reload_policy_for_key()`: which keys need a restart. Keys are reloadable by default. Restart is required for `server.name`, the `database.*` URI and role keys, listener TLS certificate/key and `reverse_proxy` keys, `security.registration.token_file`, `database.pool_size`, `security.media.thumbnail_cache_size`, `security.media.thumbnail_max_concurrent_per_user`, `security.secrets.master_key_file`, `security.federation.key_resolution_*`, `security.federation.join_response_max_size`, `client_rate_limits.*`, `log_modules.*`, `federation.worker.*`, `server.cors.*`, `server.http.*`, `server.identity_server.*`, `server.push.*`, `server.oauth.*`, `appservice.*` and `presence.*`. The rate-limit engine and per-module log map are built once at start-up, so they are not hot-reloadable. | ## Rules diff --git a/src/config/Config.cpp b/src/config/Config.cpp index 6cef0a91b..18c0db075 100644 --- a/src/config/Config.cpp +++ b/src/config/Config.cpp @@ -22,10 +22,13 @@ #include "merovingian/config/ServerConfig.hpp" #include "merovingian/config/SizeLimitParseResult.hpp" #include "merovingian/config/SpecialUseIpRanges.hpp" +#include "merovingian/core/Error.hpp" #include "merovingian/email/MailboxAddress.hpp" #include "merovingian/email/SmtpEndpoint.hpp" #include "merovingian/http/KeepAlive.hpp" #include "merovingian/http/RateLimit.hpp" +#include "merovingian/oauth/HandOffAllowlist.hpp" +#include "merovingian/oauth/OAuthBaseUrl.hpp" #include #include @@ -43,6 +46,7 @@ #include #include #include +#include #include namespace merovingian::config @@ -335,24 +339,6 @@ auto is_valid_https_url(std::string_view url) noexcept -> bool return !remainder.empty() && remainder.find(' ') == std::string_view::npos; } -auto is_valid_https_origin_url(std::string_view url) noexcept -> bool -{ - constexpr auto https_scheme = std::string_view{"https://"}; - if (!starts_with(url, https_scheme)) - { - return false; - } - - auto const remainder = url.substr(https_scheme.size()); - if (remainder.empty() || remainder.find(' ') != std::string_view::npos) - { - return false; - } - - // RFC 8414: issuer URL has no query or fragment components. - return remainder.find('?') == std::string_view::npos && remainder.find('#') == std::string_view::npos; -} - auto is_valid_federation_policy(std::string_view policy) noexcept -> bool { return policy == "allow" || policy == "deny"; @@ -1188,38 +1174,48 @@ auto validate(Config const& config) -> std::vector findings.push_back({"server.turn.server", "TURN credentials supplied but no server URI is configured"}); } - // OIDC discovery metadata. When enabled, all required Matrix v1.19 / RFC 8414 - // fields must be present and use HTTPS. Partial configuration is rejected. - auto const& oidc = config.server().oidc; - if (oidc.enabled) + // The built-in OAuth 2.0 API (ADR-0760, ADR-0764). 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. + auto const& oauth_config = config.server().oauth; + if (oauth_config.enabled) { - if (oidc.issuer.empty()) + if (std::holds_alternative(oauth::OAuthBaseUrl::read(config.server().public_baseurl))) { - findings.push_back({"server.oidc.issuer", "OIDC enabled but issuer is missing"}); + findings.push_back({"server.public_baseurl", + "with server.oauth.enabled=true, server.public_baseurl must be an https URL with a " + "host and no query, fragment or userinfo"}); } - else if (!is_valid_https_origin_url(oidc.issuer)) + // The built-in pages answer the SSO redirect (plan phase 9); an external SSO page beside them would give one + // redirect endpoint two owners. + if (!config.server().sso.authorization_url.empty()) { - findings.push_back( - {"server.oidc.issuer", "OIDC issuer must be a valid HTTPS URL with no query or fragment"}); + findings.push_back({"server.sso.authorization_url", + "server.sso.authorization_url cannot be set while server.oauth.enabled=true"}); } - - auto const validate_oidc_endpoint = [&findings](std::string_view field, std::string_view url, bool required) { - if (required && url.empty()) - { - findings.push_back({std::string{field}, "OIDC enabled but required endpoint is missing"}); - } - if (!url.empty() && !is_valid_https_url(url)) - { - findings.push_back({std::string{field}, "OIDC endpoint must use HTTPS"}); - } - }; - - validate_oidc_endpoint("server.oidc.authorization_endpoint", oidc.authorization_endpoint, true); - validate_oidc_endpoint("server.oidc.token_endpoint", oidc.token_endpoint, true); - validate_oidc_endpoint("server.oidc.registration_endpoint", oidc.registration_endpoint, true); - validate_oidc_endpoint("server.oidc.revocation_endpoint", oidc.revocation_endpoint, true); - validate_oidc_endpoint("server.oidc.device_authorization_endpoint", oidc.device_authorization_endpoint, false); - validate_oidc_endpoint("server.oidc.account_management_uri", oidc.account_management_uri, false); + } + else + { + // ADR-0761: with neither API on no user could log in. + if (!oauth_config.legacy_api_enabled) + { + findings.push_back({"server.oauth.legacy_api_enabled", + "server.oauth.legacy_api_enabled=false requires server.oauth.enabled=true"}); + } + if (oauth_config.device_grant_enabled) + { + findings.push_back({"server.oauth.device_grant_enabled", + "server.oauth.device_grant_enabled=true requires server.oauth.enabled=true"}); + } + if (!oauth_config.hand_off_redirect_allowlist.empty()) + { + findings.push_back({"server.oauth.hand_off_redirect_allowlist", + "server.oauth.hand_off_redirect_allowlist requires server.oauth.enabled=true"}); + } + } + if (auto const error = oauth::hand_off_allowlist_error(oauth_config.hand_off_redirect_allowlist); error.has_value()) + { + findings.push_back({"server.oauth.hand_off_redirect_allowlist", error->message()}); } // Identity Service API: every trusted server must be an HTTPS URL. An empty trusted list is valid — it means 3PID diff --git a/src/config/ConfigParser.cpp b/src/config/ConfigParser.cpp index f5daedf14..02a384116 100644 --- a/src/config/ConfigParser.cpp +++ b/src/config/ConfigParser.cpp @@ -1015,45 +1015,39 @@ namespace add_parse_finding(findings, std::string{key}, "expected positive integer"); } } - // OIDC delegation: discovery endpoints advertised to clients when an external issuer is used. - else if (key == "server.oidc.enabled") + // The built-in OAuth 2.0 API (ADR-0760). validate() judges how the keys combine. + else if (key == "server.oauth.enabled") { - if (!parse_bool_value(value, server.oidc.enabled)) + if (!parse_bool_value(value, server.oauth.enabled)) { add_parse_finding(findings, std::string{key}, "expected boolean value"); } } - else if (key == "server.oidc.issuer") + else if (key == "server.oauth.legacy_api_enabled") { - server.oidc.issuer = std::string{value}; - } - else if (key == "server.oidc.authorization_endpoint") - { - server.oidc.authorization_endpoint = std::string{value}; - } - else if (key == "server.oidc.token_endpoint") - { - server.oidc.token_endpoint = std::string{value}; - } - else if (key == "server.oidc.registration_endpoint") - { - server.oidc.registration_endpoint = std::string{value}; - } - else if (key == "server.oidc.revocation_endpoint") - { - server.oidc.revocation_endpoint = std::string{value}; + if (!parse_bool_value(value, server.oauth.legacy_api_enabled)) + { + add_parse_finding(findings, std::string{key}, "expected boolean value"); + } } - else if (key == "server.oidc.device_authorization_endpoint") + else if (key == "server.oauth.device_grant_enabled") { - server.oidc.device_authorization_endpoint = std::string{value}; + if (!parse_bool_value(value, server.oauth.device_grant_enabled)) + { + add_parse_finding(findings, std::string{key}, "expected boolean value"); + } } - else if (key == "server.oidc.account_management_uri") + else if (key == "server.oauth.hand_off_redirect_allowlist") { - server.oidc.account_management_uri = std::string{value}; + server.oauth.hand_off_redirect_allowlist = parse_string_list(value); } - else if (key == "server.oidc.account_management_actions_supported") + // ADR-0764: server.oidc.* only advertised an external server that could not log anyone in. It is refused, not + // ignored, so an operator who set it learns that the server now answers auth_metadata itself. + else if (starts_with(key, "server.oidc.")) { - server.oidc.account_management_actions_supported = parse_string_list(value); + add_parse_finding(findings, std::string{key}, + "removed in 1.1.0: delete every server.oidc.* line; the OAuth 2.0 API is built in and " + "is turned on with server.oauth.enabled=true (ADR-0764)"); } // Identity server client: allowlists and timeouts for outbound 3PID calls. else if (key == "server.identity_server.trusted_servers") diff --git a/src/config/ReloadPlan.cpp b/src/config/ReloadPlan.cpp index d6c4a18cf..aa97be467 100644 --- a/src/config/ReloadPlan.cpp +++ b/src/config/ReloadPlan.cpp @@ -577,8 +577,25 @@ auto build_reload_plan(Config const& current, Config const& next) -> ReloadPlan add_change(plan, "server.turn.ttl_seconds"); } - // Identity Service API. Unlike the OIDC block (which has no reload diff — - // issue #421), every identity_server field is diffed so a hot-reload that + // The OAuth 2.0 API: every field is diffed, and every change is restart_required (see ReloadPolicy.cpp). + if (current.server().oauth.enabled != next.server().oauth.enabled) + { + add_change(plan, "server.oauth.enabled"); + } + if (current.server().oauth.legacy_api_enabled != next.server().oauth.legacy_api_enabled) + { + add_change(plan, "server.oauth.legacy_api_enabled"); + } + if (current.server().oauth.device_grant_enabled != next.server().oauth.device_grant_enabled) + { + add_change(plan, "server.oauth.device_grant_enabled"); + } + if (current.server().oauth.hand_off_redirect_allowlist != next.server().oauth.hand_off_redirect_allowlist) + { + add_change(plan, "server.oauth.hand_off_redirect_allowlist"); + } + + // Identity Service API. Every identity_server field is diffed so a hot-reload that // changes the trusted-IS allowlist or timeouts is detected. All changes // are restart_required (see ReloadPolicy.cpp): the outbound IS client and // cached resolver are built at startup. diff --git a/src/config/ReloadPolicy.cpp b/src/config/ReloadPolicy.cpp index d4fe12785..5d63c05ae 100644 --- a/src/config/ReloadPolicy.cpp +++ b/src/config/ReloadPolicy.cpp @@ -92,6 +92,14 @@ auto reload_policy_for_key(std::string_view key) noexcept -> ReloadPolicy return ReloadPolicy::restart_required; } + // The OAuth 2.0 API: turning it on or off changes which login API answers, what auth_metadata advertises and, + // from later phases, which in-memory stores (pending authorisations, codes, device codes) exist. Clients cache the + // metadata, and a half-switched server would advertise endpoints it does not yet serve, so every key restarts. + if (starts_with(key, "server.oauth.")) + { + return ReloadPolicy::restart_required; + } + // Outbound email for email pushers: the SMTP relay, credentials file and timeouts are read // at startup. SIGHUP does not rebuild them. if (starts_with(key, "server.email.")) diff --git a/src/config/meson.build b/src/config/meson.build index 9a23a0e1b..2fe86e364 100644 --- a/src/config/meson.build +++ b/src/config/meson.build @@ -10,5 +10,6 @@ config_lib = static_library( 'merovingian-config', config_sources, include_directories: inc, - link_with: [auth_lib, email_lib], + # oauth_lib: validation reads server.public_baseurl and the hand-off allowlist with the OAuth readers. + link_with: [auth_lib, email_lib, oauth_lib], ) diff --git a/src/federation_worker/meson.build b/src/federation_worker/meson.build index ef8c3c007..cd63d86a1 100644 --- a/src/federation_worker/meson.build +++ b/src/federation_worker/meson.build @@ -14,7 +14,7 @@ federation_worker_lib = static_library( link_with: [ appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, homeserver_lib, http_lib, - identity_lib, ipc_lib, media_lib, net_lib, observability_lib, platform_lib, + identity_lib, ipc_lib, media_lib, net_lib, oauth_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib, ], ) @@ -29,7 +29,7 @@ federation_worker_exe = executable( link_with: [ appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, homeserver_lib, http_lib, - identity_lib, ipc_lib, media_lib, net_lib, observability_lib, platform_lib, + identity_lib, ipc_lib, media_lib, net_lib, oauth_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib, federation_worker_lib, ], install: true, diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index e1c7c7d84..651500408 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -100,6 +100,14 @@ is `declared_mime|sniffed_mime|scanner_clean|bytes` — the pipe-delimited wrapp `404 M_UNRECOGNIZED` before authentication (`client_route_is_known`, ADR-0230), so a route missing there is unreachable for every caller +## OAuth 2.0 API (ADR-0760, ADR-0773) + +`GET /_matrix/client/v1/auth_metadata` and its MSC2965 unstable path are answered in `ClientServerRuntime.cpp` before +authentication: `404 M_UNRECOGNIZED` while `server.oauth.enabled` is false, otherwise `oauth::server_metadata`. Every +absolute OAuth address a handler writes comes from `oauth::OAuthBaseUrl` read from `server.public_baseurl`, with a path +constant from `oauth/OAuthPaths.hpp`; never join the base URL and a path here. The two paths stay in the generic +rate-limit tier (ADR-0775); the other OAuth endpoints take `auth_sensitive`. + ## Password reset by email (ADR-0481) `POST /account/password/email/requestToken`, the submit step and `POST /account/password` with `m.login.email.identity` diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index ed5be622f..6fbd7ddf0 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -23,7 +23,6 @@ #include "merovingian/auth/KeyApi.hpp" #include "merovingian/auth/KeyApiEndpoint.hpp" #include "merovingian/auth/KeyApiRoute.hpp" -#include "merovingian/auth/OidcDiscovery.hpp" #include "merovingian/auth/Password.hpp" #include "merovingian/canonicaljson/CanonicalJsonError.hpp" #include "merovingian/canonicaljson/ObjectMember.hpp" @@ -139,6 +138,10 @@ #include "merovingian/http/RequestErrorCode.hpp" #include "merovingian/identity/IdentityServerClient.hpp" #include "merovingian/media/Security.hpp" +#include "merovingian/oauth/OAuthBaseUrl.hpp" +#include "merovingian/oauth/OAuthPaths.hpp" +#include "merovingian/oauth/ServerMetadata.hpp" +#include "merovingian/oauth/ServerMetadataOptions.hpp" #include "merovingian/observability/AuditCategory.hpp" #include "merovingian/observability/BoundedText.hpp" #include "merovingian/observability/LogEventSeverity.hpp" @@ -4060,6 +4063,7 @@ namespace "/_matrix/client/v3/logout", "/_matrix/client/v3/logout/all", "/_matrix/client/v1/auth_metadata", + "/_matrix/client/unstable/org.matrix.msc2965/auth_metadata", "/_matrix/client/v3/account/3pid/email/requestToken", "/_matrix/client/v3/account/3pid/msisdn/requestToken", "/_matrix/client/v3/account/password/email/requestToken", @@ -4155,6 +4159,7 @@ namespace {"/_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" }, {"/_matrix/client/v3/account/3pid/email/requestToken", "POST" }, {"/_matrix/client/v3/account/3pid/msisdn/requestToken", "POST" }, {"/_matrix/client/v3/account/password/email/requestToken", "POST" }, @@ -15989,23 +15994,36 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp : dispatch_err(req, rt, r.status, r.status == 401U ? unauthenticated_errcode : "M_UNKNOWN", r.body); } - // MSC2965 OIDC discovery: Cinny and Element probe auth_metadata and - // auth_issuer before login to detect OIDC support. We do not implement - // OIDC, so return 404 for the whole msc2965 namespace before the - // access-token gate, otherwise the probes produce a misleading 401. - if (req.method == "GET" && starts_with(req.target, "/_matrix/client/unstable/org.matrix.msc2965/")) - { - return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "OIDC not supported"); - } - if (req.method == "GET" && request_path == "/_matrix/client/v1/auth_metadata") + // GET /auth_metadata (spec "Server metadata discovery"), also at its MSC2965 unstable path, which clients still + // probe. Unauthenticated, so it is answered before the access-token gate; CORS is added at the boundary like + // every other answer. With the OAuth 2.0 API off both paths are 404 M_UNRECOGNIZED, the spec's answer of a server + // without it ("Authentication API discovery"). + if (req.method == "GET" && + (request_path == oauth::auth_metadata_path || request_path == oauth::auth_metadata_unstable_path)) { - auto const metadata = auth::make_auth_metadata(rt.homeserver.config.server().oidc); - if (!metadata.configured) + auto const& server_config = rt.homeserver.config.server(); + if (!server_config.oauth.enabled) + { + return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "The OAuth 2.0 API is not enabled on this server."); + } + // validate() refused a base URL this cannot read when the API is on; a runtime built without validation + // answers 500 rather than advertise an address the reader refused. + auto base = oauth::OAuthBaseUrl::read(server_config.public_baseurl); + if (std::holds_alternative(base)) { - return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "OIDC not supported"); + return dispatch_err(req, rt, 500U, "M_UNKNOWN", "The OAuth 2.0 base URL is not configured correctly."); } + auto options = oauth::ServerMetadataOptions{}; + options.device_grant_enabled = server_config.oauth.device_grant_enabled; + options.registration_enabled = rt.homeserver.config.security().registration.enabled; return dispatch_resp(req, rt, 200U, - json_serialize(canonicaljson::Value{canonicaljson::Object{metadata.fields}})); + json_serialize(oauth::server_metadata(std::get(base), options))); + } + // The rest of the MSC2965 namespace (`auth_issuer`, from an earlier draft of the MSC) is not served. It is + // answered 404 before the access-token gate, so a probe does not read a 401 as partial support. + if (req.method == "GET" && starts_with(req.target, "/_matrix/client/unstable/org.matrix.msc2965/")) + { + return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); } auto constexpr media_download_prefix = std::string_view{"/_matrix/media/v3/download/"}; diff --git a/src/meson.build b/src/meson.build index c808e4430..3efc060d1 100644 --- a/src/meson.build +++ b/src/meson.build @@ -1,7 +1,7 @@ # core first: it links nothing of the project's, and canonicaljson links it (core::utf8_is_valid). subdir('core') subdir('crypto') -# canonicaljson before auth: auth links it (Identity.cpp, OidcDiscovery.cpp). +# canonicaljson before auth: auth links it (Identity.cpp). subdir('canonicaljson') subdir('auth') # oauth after auth: it links auth (device_id_is_valid), canonicaljson and crypto. @@ -35,7 +35,7 @@ server_exe = executable( sources: files('main.cpp'), include_directories: inc, dependencies: [thread_dep, libsodium_dep, openssl_dep, libpq_dep, sqlite_dep, libcurl_dep, resolv_dep], - link_with: [appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], + link_with: [appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, oauth_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], install: true, ) @@ -44,7 +44,7 @@ executable( sources: files('db_migrate.cpp'), include_directories: inc, dependencies: [thread_dep, libpq_dep, sqlite_dep], - link_with: [config_lib, canonicaljson_lib, database_lib, observability_lib, platform_lib], + link_with: [config_lib, canonicaljson_lib, database_lib, oauth_lib, observability_lib, platform_lib], install: true, ) diff --git a/src/oauth/AGENTS.md b/src/oauth/AGENTS.md index b3c98e33a..b4ec57146 100644 --- a/src/oauth/AGENTS.md +++ b/src/oauth/AGENTS.md @@ -19,6 +19,10 @@ Pure functions and value types for the built-in OAuth 2.0 API | `HtmlText.cpp`, `HtmlLiteral.hpp`, `HtmlName.hpp`, `PagePath.hpp` | Page text: escaped at run time, or fixed and checked at compile time (ADR-0772) | | `Page.cpp`, `PageForm.cpp`, `PageDetail.hpp`, `TextInput.hpp`, `SubmitButton.hpp` | The one page renderer and its parts | | `PageHeaders.cpp` | `page_style`, `page_headers`: the fixed style block and the headers every page carries, with the `form-action` source of a validated redirect target | +| `OAuthPaths.hpp` | Every OAuth route path: the `PagePath` constants under `/_merovingian/oauth2/` and `/_merovingian/account`, and the two `auth_metadata` paths (ADR-0773) | +| `OAuthBaseUrl.cpp` | `OAuthBaseUrl::read`: `server.public_baseurl` as an `https` URL with a host and no query; `issuer()` (one trailing slash) and `url(PagePath)` (ADR-0773) | +| `ServerMetadata.cpp`, `ServerMetadataOptions.hpp` | `server_metadata`: the `auth_metadata` document, device grant, `prompt=create` and account management fields only when their option is on | +| `HandOffAllowlist.cpp` | `hand_off_allowlist_entry_error`, `hand_off_allowlist_error`: an https origin or a bare private-use scheme, at most 32, each once (ADR-0774) | | `DisplayText.cpp`, `AsciiCase.cpp` | Module-internal: `display_text_is_safe` (no control or bidirectional formatting character) and `ascii_lower` | ## Rules @@ -44,12 +48,17 @@ Pure functions and value types for the built-in OAuth 2.0 API computed from it, and `test_oauth_page.cpp` proves the policy names it. 8. **PKCE is `S256` only and compared in constant time** (`crypto::constant_time_equal`). SHA-256 and base64 come from `crypto`; this module never calls libsodium. -9. **Client metadata is validated once, by `ClientMetadata::validate`,** also when a stored registration is read back. - The client ID is a keyed hash of `canonical_bytes()` (phase 4); do not hash anything else for it. +9. **Every absolute OAuth address comes from `OAuthBaseUrl`.** The issuer is `issuer()` and every endpoint is + `url(path)` with a constant from `OAuthPaths.hpp`; never join `public_baseurl` and a path by hand (ADR-0773). +10. **A hand-off allowlist entry is an origin or a bare scheme, never a prefix** (ADR-0774). +11. **Client metadata is validated once, by `ClientMetadata::validate`,** also when a stored registration is read back. + The client ID is a keyed hash of `canonical_bytes()` (phase 4); do not hash anything else for it. ## Tests `tests/unit/test_oauth_pkce.cpp` (`[oauth][pkce]`), `test_oauth_scope.cpp` (`[oauth][scope]`), `test_oauth_redirect_uri.cpp` (`[oauth][uri]`, `[oauth][redirect]`), `test_oauth_client_metadata.cpp` -(`[oauth][metadata]`), `test_oauth_page.cpp` (`[oauth][page]`). Fuzz targets: `fuzz_oauth_redirect_uri.cpp`, -`fuzz_oauth_scope.cpp`, `fuzz_oauth_client_metadata.cpp`. +(`[oauth][metadata]`), `test_oauth_page.cpp` (`[oauth][page]`), `test_oauth_server_metadata.cpp` (`[oauth][urls]`, +`[oauth][server_metadata]`), `test_oauth_hand_off_allowlist.cpp` (`[oauth][allowlist]`). The served document: +`tests/conformance/test_oauth_metadata_conformance.cpp` and `tests/integration/test_oauth_metadata_flow.cpp` +(`[oauth]`). Fuzz targets: `fuzz_oauth_redirect_uri.cpp`, `fuzz_oauth_scope.cpp`, `fuzz_oauth_client_metadata.cpp`. diff --git a/src/oauth/HandOffAllowlist.cpp b/src/oauth/HandOffAllowlist.cpp new file mode 100644 index 000000000..8825d9769 --- /dev/null +++ b/src/oauth/HandOffAllowlist.cpp @@ -0,0 +1,105 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/oauth/HandOffAllowlist.hpp" + +#include "merovingian/core/ErrorCode.hpp" +#include "merovingian/oauth/ParsedUri.hpp" + +#include +#include +#include +#include +#include + +namespace merovingian::oauth +{ +namespace +{ + + [[nodiscard]] auto refuse(char const* message) -> core::Error + { + return core::Error{core::ErrorCode::parse_failure, message}; + } + + [[nodiscard]] auto has_upper_case(std::string_view text) noexcept -> bool + { + return std::ranges::any_of(text, [](char value) noexcept { + return value >= 'A' && value <= 'Z'; + }); + } + + [[nodiscard]] auto origin_error(ParsedUri const& uri) -> std::optional + { + if (!uri.path().empty() || uri.has_query()) + { + return refuse("A hand-off origin must end after the host or port, with no path, not even /."); + } + if (uri.port() == std::optional{443U}) + { + return refuse("A hand-off origin must not write the default port 443."); + } + return std::nullopt; + } + + [[nodiscard]] auto scheme_error(ParsedUri const& uri, std::string_view entry) -> std::optional + { + // `scheme:` and nothing else: the reader's text is the scheme and its colon. + if (!uri.path().empty() || uri.has_query() || entry.size() != uri.scheme().size() + 1U) + { + return refuse("A hand-off scheme must be a bare scheme and its colon, such as io.element.app:."); + } + if (uri.scheme().find('.') == std::string::npos) + { + return refuse("A hand-off scheme must be a private-use scheme with a dot, such as io.element.app:."); + } + return std::nullopt; + } + +} // namespace + +auto hand_off_allowlist_entry_error(std::string_view entry) -> std::optional +{ + auto parsed = ParsedUri::read(entry); + if (auto const* error = std::get_if(&parsed)) + { + return core::Error{error->code(), "A hand-off allowlist entry is not a valid URI."}; + } + auto const& uri = std::get(parsed); + if (has_upper_case(entry)) + { + return refuse("A hand-off allowlist entry must be written in lower case."); + } + if (uri.has_authority()) + { + if (uri.scheme() != "https") + { + return refuse("A hand-off origin must use the https scheme."); + } + return origin_error(uri); + } + return scheme_error(uri, entry); +} + +auto hand_off_allowlist_error(std::span entries) -> std::optional +{ + if (entries.size() > max_hand_off_allowlist_entries) + { + return core::Error{core::ErrorCode::invalid_argument, "The hand-off allowlist holds more than 32 entries."}; + } + for (auto index = std::size_t{0U}; index < entries.size(); ++index) + { + if (auto error = hand_off_allowlist_entry_error(entries[index]); error.has_value()) + { + return error; + } + if (std::find(entries.begin(), entries.begin() + static_cast(index), entries[index]) != + entries.begin() + static_cast(index)) + { + return refuse("The hand-off allowlist names an entry twice."); + } + } + return std::nullopt; +} + +} // namespace merovingian::oauth diff --git a/src/oauth/OAuthBaseUrl.cpp b/src/oauth/OAuthBaseUrl.cpp new file mode 100644 index 000000000..5069ca665 --- /dev/null +++ b/src/oauth/OAuthBaseUrl.cpp @@ -0,0 +1,71 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/oauth/OAuthBaseUrl.hpp" + +#include "merovingian/core/ErrorCode.hpp" + +#include + +namespace merovingian::oauth +{ +namespace +{ + + [[nodiscard]] auto without_trailing_slashes(std::string_view text) -> std::string + { + while (text.ends_with('/')) + { + text.remove_suffix(1U); + } + return std::string{text}; + } + +} // namespace + +OAuthBaseUrl::OAuthBaseUrl(ParsedUri uri) + : m_uri{std::move(uri)} + , m_prefix{without_trailing_slashes(m_uri.text())} +{ +} + +auto OAuthBaseUrl::read(std::string_view text) -> std::variant +{ + auto parsed = ParsedUri::read(text); + if (auto const* error = std::get_if(&parsed)) + { + return core::Error{error->code(), "The base URL is not a valid URI."}; + } + auto& uri = std::get(parsed); + // The scheme is compared as written: the reader keeps its case, and a base URL is refused, never repaired. + if (uri.scheme() != "https") + { + return core::Error{core::ErrorCode::parse_failure, "The base URL must use the https scheme."}; + } + if (!uri.has_authority()) + { + return core::Error{core::ErrorCode::parse_failure, "The base URL must name a host."}; + } + if (uri.has_query()) + { + return core::Error{core::ErrorCode::parse_failure, "The base URL must not have a query."}; + } + return OAuthBaseUrl{std::move(uri)}; +} + +auto OAuthBaseUrl::issuer() const -> std::string +{ + return m_prefix + "/"; +} + +auto OAuthBaseUrl::url(PagePath path) const -> std::string +{ + return m_prefix + std::string{path.view()}; +} + +auto OAuthBaseUrl::uri() const noexcept -> ParsedUri const& +{ + return m_uri; +} + +} // namespace merovingian::oauth diff --git a/src/oauth/ServerMetadata.cpp b/src/oauth/ServerMetadata.cpp new file mode 100644 index 000000000..efb85bcf5 --- /dev/null +++ b/src/oauth/ServerMetadata.cpp @@ -0,0 +1,79 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/oauth/ServerMetadata.hpp" + +#include "merovingian/canonicaljson/ObjectMember.hpp" +#include "merovingian/oauth/OAuthPaths.hpp" + +#include +#include +#include +#include + +namespace merovingian::oauth +{ +namespace +{ + + // RFC 8628's grant type URN for the device authorization grant. + constexpr auto device_code_grant_type = std::string_view{"urn:ietf:params:oauth:grant-type:device_code"}; + + [[nodiscard]] auto string_list(std::initializer_list items) -> canonicaljson::Value + { + auto array = canonicaljson::Array{}; + array.reserve(items.size()); + for (auto const item : items) + { + array.emplace_back(std::string{item}); + } + return canonicaljson::Value{std::move(array)}; + } + + void add(canonicaljson::Object& object, std::string key, canonicaljson::Value value) + { + object.push_back(canonicaljson::make_member(std::move(key), std::move(value))); + } + +} // namespace + +auto server_metadata(OAuthBaseUrl const& base, ServerMetadataOptions const& options) -> canonicaljson::Value +{ + auto object = canonicaljson::Object{}; + add(object, "issuer", canonicaljson::Value{base.issuer()}); + add(object, "authorization_endpoint", canonicaljson::Value{base.url(authorize_path)}); + add(object, "token_endpoint", canonicaljson::Value{base.url(token_path)}); + add(object, "registration_endpoint", canonicaljson::Value{base.url(register_path)}); + add(object, "revocation_endpoint", canonicaljson::Value{base.url(revoke_path)}); + add(object, "response_types_supported", string_list({"code"})); + add(object, "response_modes_supported", string_list({"query", "fragment"})); + add(object, "code_challenge_methods_supported", string_list({"S256"})); + if (options.device_grant_enabled) + { + add(object, "grant_types_supported", + string_list({"authorization_code", "refresh_token", device_code_grant_type})); + add(object, "device_authorization_endpoint", canonicaljson::Value{base.url(device_path)}); + } + else + { + add(object, "grant_types_supported", string_list({"authorization_code", "refresh_token"})); + } + if (options.registration_enabled) + { + add(object, "prompt_values_supported", string_list({"create"})); + } + if (!options.account_management_actions.empty()) + { + add(object, "account_management_uri", canonicaljson::Value{base.url(account_path)}); + auto actions = canonicaljson::Array{}; + actions.reserve(options.account_management_actions.size()); + for (auto const& action : options.account_management_actions) + { + actions.emplace_back(action); + } + add(object, "account_management_actions_supported", canonicaljson::Value{std::move(actions)}); + } + return canonicaljson::Value{std::move(object)}; +} + +} // namespace merovingian::oauth diff --git a/src/oauth/meson.build b/src/oauth/meson.build index 86fc045ec..43e655a1d 100644 --- a/src/oauth/meson.build +++ b/src/oauth/meson.build @@ -3,7 +3,9 @@ oauth_sources = files( 'ClientMetadata.cpp', 'ClientUri.cpp', 'DisplayText.cpp', + 'HandOffAllowlist.cpp', 'HtmlText.cpp', + 'OAuthBaseUrl.cpp', 'Page.cpp', 'PageForm.cpp', 'PageHeaders.cpp', @@ -11,6 +13,7 @@ oauth_sources = files( 'Pkce.cpp', 'RedirectUriRules.cpp', 'ScopeParser.cpp', + 'ServerMetadata.cpp', ) # Pure functions only: no runtime state, no I/O, no logging (src/oauth/AGENTS.md). diff --git a/tests/conformance/test_client_server_conformance.cpp b/tests/conformance/test_client_server_conformance.cpp index 22c166952..98d8bdb85 100644 --- a/tests/conformance/test_client_server_conformance.cpp +++ b/tests/conformance/test_client_server_conformance.cpp @@ -28,9 +28,9 @@ // +-------------------------------------------------------------------------+ #include "../FederationSigningTestSupport.hpp" -#include "../support/MockIdentityServer.hpp" #include "../support/JsonTestSupport.hpp" #include "../support/MasterKey.hpp" +#include "../support/MockIdentityServer.hpp" #include "../support/RegistrationToken.hpp" #include "../support/TlsMockServer.hpp" #include "merovingian/canonicaljson/CanonicalJsonError.hpp" @@ -45,9 +45,9 @@ #include "merovingian/federation/FederationRemoteRuntime.hpp" #include "merovingian/federation/InboundRequest.hpp" #include "merovingian/federation/OutboundTransactionSupport.hpp" +#include "merovingian/homeserver/AuthService.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" -#include "merovingian/homeserver/AuthService.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" #include @@ -4004,10 +4004,10 @@ SCENARIO("POST /logout/all returns 200 with empty JSON object", "[conformance][c // --- GET /_matrix/client/v1/auth_metadata ------------------------------------ // Spec: ../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv1auth_metadata -// OIDC discovery is optional; unsupported servers should answer this -// unauthenticated probe cleanly so clients do not mistake lack of OIDC for an -// authentication failure. -SCENARIO("GET /v1/auth_metadata returns an unauthenticated 404 M_UNRECOGNIZED when OIDC is unsupported", +// The OAuth 2.0 API is optional; a server without it answers this +// unauthenticated probe 404 M_UNRECOGNIZED so clients do not mistake its +// absence for an authentication failure. +SCENARIO("GET /v1/auth_metadata returns an unauthenticated 404 M_UNRECOGNIZED when the OAuth 2.0 API is off", "[conformance][client-server][session]") { GIVEN("a running client-server") @@ -17695,21 +17695,21 @@ SCENARIO("POST /user_directory/search result entries each contain a non-empty us } // ============================================================================= -// OIDC DISCOVERY (MSC2965) +// OAUTH 2.0 API DISCOVERY // ============================================================================= -// Spec: Matrix Client-Server API v1.19 — GET /auth_metadata (MSC2965) -// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#openid-connect-discovery +// Spec: Matrix Client-Server API v1.19 — Authentication API discovery +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#authentication-api-discovery // -// Servers that do not support OIDC MUST return 404 M_UNRECOGNIZED so that -// clients (Element, Cindy, etc.) can detect the absence of OIDC support and -// fall back to password-based login. The server MUST NOT return 401 for this -// unauthenticated discovery endpoint — returning 401 would mislead clients -// into thinking OIDC is partially supported. -SCENARIO("GET /v1/auth_metadata returns 404 M_UNRECOGNIZED for non-OIDC servers", - "[conformance][client-server][oidc][auth]") +// A server without the OAuth 2.0 API SHOULD return 404 M_UNRECOGNIZED so that +// clients (Element, Cinny, etc.) can detect its absence and fall back to the +// legacy API. This unauthenticated discovery endpoint is never answered 401: +// that would mislead clients into thinking the API is partially supported. +// test_oauth_metadata_conformance.cpp covers the API switched on. +SCENARIO("GET /v1/auth_metadata returns 404 M_UNRECOGNIZED while the OAuth 2.0 API is off", + "[conformance][client-server][oauth][auth]") { - GIVEN("a running homeserver that does not implement OIDC") + GIVEN("a running homeserver with the OAuth 2.0 API left off") { auto started = merovingian::homeserver::start_client_server(conformance_config()); REQUIRE(started.started); @@ -17721,8 +17721,8 @@ SCENARIO("GET /v1/auth_metadata returns 404 M_UNRECOGNIZED for non-OIDC servers" THEN("the server returns 404 M_UNRECOGNIZED") { - // Spec: non-OIDC servers MUST return 404 M_UNRECOGNIZED so clients - // detect the absence of OIDC before attempting OIDC login. + // Spec SHOULD: a server without the OAuth 2.0 API returns 404 M_UNRECOGNIZED + // so clients detect its absence before attempting an OAuth login. REQUIRE(response.response.status == 404U); auto const body = parse_object(response.response.body); auto const* errcode = string_member(body, "errcode"); diff --git a/tests/conformance/test_oauth_metadata_conformance.cpp b/tests/conformance/test_oauth_metadata_conformance.cpp new file mode 100644 index 000000000..f68e281e1 --- /dev/null +++ b/tests/conformance/test_oauth_metadata_conformance.cpp @@ -0,0 +1,301 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// +-------------------------------------------------------------------------+ +// | OAUTH 2.0 SERVER METADATA CONFORMANCE TESTS | +// | | +// | Spec: Matrix Client-Server API v1.19 — "Server metadata discovery" | +// | and "Authentication API discovery" | +// | URL: ../../docs/matrix-v1.19-spec/client-server-api.md | +// +-------------------------------------------------------------------------+ +// +// `GET /_matrix/client/v1/auth_metadata`, and the same document at the MSC2965 unstable path, with the built-in +// OAuth 2.0 API on and off. + +#include "../support/InMemoryDatabaseConfig.hpp" +#include "../support/JsonTestSupport.hpp" +#include "../support/MasterKey.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/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; + +constexpr auto stable_path = std::string_view{"/_matrix/client/v1/auth_metadata"}; +constexpr auto unstable_path = std::string_view{"/_matrix/client/unstable/org.matrix.msc2965/auth_metadata"}; + +[[nodiscard]] auto metadata_config(bool oauth_enabled) -> merovingian::config::Config +{ + auto security = merovingian::config::SecurityConfig{}; + security.secrets.master_key_file = merovingian::tests::shared_master_key_file(); + auto server = merovingian::config::ServerConfig{}; + server.public_baseurl = "https://matrix.example.org"; + server.oauth.enabled = oauth_enabled; + return { + std::move(server), + merovingian::config::ListenersConfig{}, + merovingian::tests::in_memory_database_config(), + std::move(security), + merovingian::config::ClientRateLimitsConfig{}, + merovingian::config::LogModulesConfig{}, + }; +} + +[[nodiscard]] auto get(merovingian::homeserver::ClientServerRuntime& runtime, std::string_view path) + -> merovingian::homeserver::LocalHttpResponse +{ + return merovingian::homeserver::handle_client_server_request(runtime, {"GET", std::string{path}, {}, {}}).response; +} + +// The strings of the array member `key`, or nothing when it is absent or not an array of strings. +[[nodiscard]] auto string_list(merovingian::canonicaljson::Object const& object, std::string_view key) + -> std::optional> +{ + auto const* array = object_member_as_array(object, key); + if (array == nullptr) + { + return std::nullopt; + } + auto out = std::vector{}; + for (auto const& item : *array) + { + auto const* text = std::get_if(&item.storage()); + if (text == nullptr) + { + return std::nullopt; + } + out.push_back(*text); + } + return out; +} + +[[nodiscard]] auto holds(std::optional> const& list, std::string_view value) -> bool +{ + if (!list.has_value()) + { + return false; + } + for (auto const& item : *list) + { + if (item == value) + { + return true; + } + } + return false; +} + +[[nodiscard]] auto header(merovingian::homeserver::LocalHttpResponse const& response, std::string_view name) + -> std::optional +{ + for (auto const& [key, value] : response.headers) + { + if (key == name) + { + return value; + } + } + return std::nullopt; +} + +} // namespace + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: GET /_matrix/client/v1/auth_metadata; Authentication API discovery +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv1auth_metadata +// ../../docs/matrix-v1.19-spec/client-server-api.md#authentication-api-discovery +// +// "404 With M_UNRECOGNIZED: the homeserver does not support the OAuth 2.0 API." Discovery: "the server SHOULD respond +// with 404 and an M_UNRECOGNIZED error code if the corresponding API is not supported." The endpoint "Requires +// authentication: No", so the probe is never answered 401. +SCENARIO("auth_metadata is 404 M_UNRECOGNIZED on both paths while the OAuth 2.0 API is off", + "[conformance][client-server][oauth][auth_metadata]") +{ + GIVEN("a running homeserver with server.oauth.enabled left false") + { + auto started = merovingian::homeserver::start_client_server(metadata_config(false)); + REQUIRE(started.started); + + for (auto const path : std::array{stable_path, unstable_path}) + { + WHEN("GET " + std::string{path} + " is called without a token") + { + auto const response = get(started.runtime, path); + + THEN("it is 404 M_UNRECOGNIZED, not 401") + { + // Spec SHOULD: 404 when the OAuth 2.0 API is not supported. + REQUIRE(response.status == 404U); + auto const body = parse_object(response.body); + auto const* errcode = string_member(body, "errcode"); + REQUIRE(errcode != nullptr); + // Spec SHOULD: the error code is M_UNRECOGNIZED. + REQUIRE(*errcode == "M_UNRECOGNIZED"); + } + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: GET /_matrix/client/v1/auth_metadata, 200 response +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv1auth_metadata +// +// Required: issuer (an https URL with no query or fragment), authorization_endpoint, token_endpoint, +// registration_endpoint, revocation_endpoint, response_types_supported (MUST contain `code`), +// response_modes_supported (MUST contain `query` and `fragment`), grant_types_supported (MUST contain +// `authorization_code` and `refresh_token`), code_challenge_methods_supported (MUST contain `S256`). +SCENARIO("auth_metadata answers the required metadata on both paths while the OAuth 2.0 API is on", + "[conformance][client-server][oauth][auth_metadata]") +{ + GIVEN("a running homeserver with server.oauth.enabled=true and public_baseurl https://matrix.example.org") + { + auto started = merovingian::homeserver::start_client_server(metadata_config(true)); + REQUIRE(started.started); + + for (auto const path : std::array{stable_path, unstable_path}) + { + WHEN("GET " + std::string{path} + " is called without a token") + { + auto const response = get(started.runtime, path); + + THEN("it is 200 with every required field") + { + // Spec: "Requires authentication: No"; 200 is the metadata. + REQUIRE(response.status == 200U); + auto const body = parse_object(response.body); + + auto const* issuer = string_member(body, "issuer"); + REQUIRE(issuer != nullptr); + // Spec MUST (issuer): "a URL that uses the https scheme and has no query or fragment components". + REQUIRE(issuer->starts_with("https://")); + REQUIRE(issuer->find('?') == std::string::npos); + REQUIRE(issuer->find('#') == std::string::npos); + + for (auto const* key : + {"authorization_endpoint", "token_endpoint", "registration_endpoint", "revocation_endpoint"}) + { + INFO(key); + // Spec: each endpoint is Required. + REQUIRE(string_member(body, key) != nullptr); + } + + // Spec MUST: response_types_supported contains `code`. + REQUIRE(holds(string_list(body, "response_types_supported"), "code")); + // Spec MUST: response_modes_supported contains `query` and `fragment`. + REQUIRE(holds(string_list(body, "response_modes_supported"), "query")); + REQUIRE(holds(string_list(body, "response_modes_supported"), "fragment")); + // Spec MUST: grant_types_supported contains `authorization_code` and `refresh_token`. + REQUIRE(holds(string_list(body, "grant_types_supported"), "authorization_code")); + REQUIRE(holds(string_list(body, "grant_types_supported"), "refresh_token")); + // Spec MUST: code_challenge_methods_supported contains `S256`. + REQUIRE(holds(string_list(body, "code_challenge_methods_supported"), "S256")); + } + } + } + + WHEN("both paths are requested") + { + auto const stable = get(started.runtime, stable_path); + auto const unstable = get(started.runtime, unstable_path); + + THEN("they answer the same document") + { + REQUIRE(stable.status == 200U); + // MSC2965's unstable path names the endpoint the spec stabilised as /v1/auth_metadata. + REQUIRE(unstable.body == stable.body); + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Web Browser Clients; GET /_matrix/client/v1/auth_metadata +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#web-browser-clients +// +// "Servers MUST expose the following CORS headers on all /_matrix/ resources ... Access-Control-Allow-Origin: *". +// A browser client reads the metadata cross-origin before it can log in. +SCENARIO("auth_metadata carries the CORS headers on both paths", "[conformance][client-server][oauth][cors]") +{ + GIVEN("a running homeserver with the OAuth 2.0 API on and the default CORS policy") + { + auto started = merovingian::homeserver::start_client_server(metadata_config(true)); + REQUIRE(started.started); + + for (auto const path : std::array{stable_path, unstable_path}) + { + WHEN("a browser sends GET " + std::string{path} + " with an Origin header") + { + auto const response = + merovingian::homeserver::handle_client_server_request( + started.runtime, {"GET", std::string{path}, {}, {}, {{"Origin", "https://app.element.io"}}}) + .response; + + THEN("the answer carries Access-Control-Allow-Origin") + { + REQUIRE(response.status == 200U); + // Spec MUST: Access-Control-Allow-Origin on all /_matrix/ resources. + auto const allow_origin = header(response, "Access-Control-Allow-Origin"); + REQUIRE(allow_origin.has_value()); + REQUIRE(!allow_origin->empty()); + } + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Standard error response (M_UNRECOGNIZED) +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#api-standards +// +// M_UNRECOGNIZED: "a 405 HTTP status code if the endpoint is implemented, but the incorrect HTTP method is used". +SCENARIO("auth_metadata answers another method 405 M_UNRECOGNIZED on both paths", + "[conformance][client-server][oauth][auth_metadata]") +{ + GIVEN("a running homeserver with the OAuth 2.0 API on") + { + auto started = merovingian::homeserver::start_client_server(metadata_config(true)); + REQUIRE(started.started); + + for (auto const path : std::array{stable_path, unstable_path}) + { + WHEN("POST " + std::string{path} + " is called") + { + auto const response = merovingian::homeserver::handle_client_server_request( + started.runtime, {"POST", std::string{path}, {}, "{}"}) + .response; + + THEN("it is 405 M_UNRECOGNIZED") + { + // Spec MUST: 405 for an implemented endpoint used with the wrong method. + REQUIRE(response.status == 405U); + auto const body = parse_object(response.body); + auto const* errcode = string_member(body, "errcode"); + REQUIRE(errcode != nullptr); + REQUIRE(*errcode == "M_UNRECOGNIZED"); + } + } + } + } +} diff --git a/tests/conformance/test_route_query_conformance.cpp b/tests/conformance/test_route_query_conformance.cpp index 4945300af..d57f46e28 100644 --- a/tests/conformance/test_route_query_conformance.cpp +++ b/tests/conformance/test_route_query_conformance.cpp @@ -105,10 +105,12 @@ 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", ""}, + {"GET", "/_matrix/client/v1/auth_metadata", ""}, + {"GET", "/_matrix/client/unstable/org.matrix.msc2965/auth_metadata", ""}, {"POST", "/_matrix/client/v3/register/email/requestToken", "{}"}, {"POST", "/_matrix/client/v3/register/msisdn/requestToken", "{}"}, {"POST", "/_matrix/client/v3/register", "{}"}, diff --git a/tests/fuzz/meson.build b/tests/fuzz/meson.build index d09460be2..d70652857 100644 --- a/tests/fuzz/meson.build +++ b/tests/fuzz/meson.build @@ -41,7 +41,7 @@ fuzz_targets = [ include_directories: inc, cpp_args: fuzz_sanitizer_args, link_args: fuzz_sanitizer_args, - link_with: [config_lib, http_lib, observability_lib, core_lib, platform_lib], + link_with: [config_lib, http_lib, oauth_lib, observability_lib, core_lib, platform_lib], ), executable( 'fuzz-stream-token', @@ -118,7 +118,7 @@ fuzz_targets = [ fuzz_server_libs = [ appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, - observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib, + oauth_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib, ] fuzz_server_deps = [thread_dep, libsodium_dep, openssl_dep, libpq_dep, sqlite_dep, libcurl_dep, resolv_dep] diff --git a/tests/integration/test_client_server_endpoints_flow.cpp b/tests/integration/test_client_server_endpoints_flow.cpp index 0f3e72f49..5d2186a75 100644 --- a/tests/integration/test_client_server_endpoints_flow.cpp +++ b/tests/integration/test_client_server_endpoints_flow.cpp @@ -23,9 +23,9 @@ // +-------------------------------------------------------------------------+ #include "../FederationSigningTestSupport.hpp" -#include "../support/MockIdentityServer.hpp" #include "../support/JsonTestSupport.hpp" #include "../support/MasterKey.hpp" +#include "../support/MockIdentityServer.hpp" #include "../support/RegistrationToken.hpp" #include "../support/TlsMockServer.hpp" #include "merovingian/config/ClientRateLimitsConfig.hpp" @@ -40,9 +40,9 @@ #include "merovingian/database/PersistentStore.hpp" #include "merovingian/database/PersistentStoreBackend.hpp" #include "merovingian/events/EventSigner.hpp" +#include "merovingian/homeserver/AuthService.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" -#include "merovingian/homeserver/AuthService.hpp" #include "merovingian/http/Header.hpp" #include "merovingian/observability/LogLevel.hpp" #include "merovingian/observability/SingleLog.hpp" @@ -116,30 +116,6 @@ struct ModuleLogLevelGuard final }; } -[[nodiscard]] auto oidc_enabled_config() -> merovingian::config::Config -{ - auto security = merovingian::config::SecurityConfig{}; - // A runtime refuses to mint a signing secret it cannot encrypt at rest - // (0.12.5 audit, finding 1), so every fixture needs a master key. - security.secrets.master_key_file = merovingian::tests::shared_master_key_file(); - merovingian::tests::enable_token_registration(security); - auto server = merovingian::config::ServerConfig{}; - server.oidc.enabled = true; - server.oidc.issuer = "https://account.example.com/"; - server.oidc.authorization_endpoint = "https://account.example.com/oauth2/auth"; - server.oidc.token_endpoint = "https://account.example.com/oauth2/token"; - server.oidc.registration_endpoint = "https://account.example.com/oauth2/clients/register"; - server.oidc.revocation_endpoint = "https://account.example.com/oauth2/revoke"; - return { - std::move(server), - merovingian::config::ListenersConfig{}, - merovingian::tests::in_memory_database_config(), - std::move(security), - merovingian::config::ClientRateLimitsConfig{}, - merovingian::config::LogModulesConfig{}, - }; -} - [[nodiscard]] auto sso_enabled_config() -> merovingian::config::Config { auto security = merovingian::config::SecurityConfig{}; @@ -5265,7 +5241,8 @@ SCENARIO("Keys upload accepts bodies larger than 4 KiB", "[homeserver][client-se } } -SCENARIO("OIDC discovery endpoints return 404 without authentication", "[homeserver][client-server]") +SCENARIO("OAuth 2.0 discovery endpoints return 404 without authentication while the API is off", + "[homeserver][client-server]") { GIVEN("a started runtime") { @@ -5280,7 +5257,7 @@ SCENARIO("OIDC discovery endpoints return 404 without authentication", "[homeser THEN("the response is 404, not 401") { - // We do not implement OIDC; the endpoint must be absent (404) rather + // The OAuth 2.0 API is off by default; the endpoint must be absent (404) rather // than access-denied (401) so clients can probe and fall back gracefully. REQUIRE(response.response.status == 404U); } @@ -5310,33 +5287,6 @@ SCENARIO("OIDC discovery endpoints return 404 without authentication", "[homeser } } -SCENARIO("GET /_matrix/client/v1/auth_metadata returns OIDC metadata when configured", - "[homeserver][client-server][oidc]") -{ - GIVEN("a started runtime with OIDC discovery configured") - { - auto started = merovingian::homeserver::start_client_server(oidc_enabled_config()); - REQUIRE(started.started); - auto& runtime = started.runtime; - - WHEN("the endpoint is called without a token") - { - auto const response = merovingian::homeserver::handle_client_server_request( - runtime, {"GET", "/_matrix/client/v1/auth_metadata", {}, {}}); - - THEN("the response is 200 and contains the configured issuer") - { - REQUIRE(response.response.status == 200U); - REQUIRE(response.response.body.find("\"issuer\":\"https://account.example.com/\"") != - std::string::npos); - REQUIRE(response.response.body.find( - "\"authorization_endpoint\":\"https://account.example.com/oauth2/auth\"") != - std::string::npos); - } - } - } -} - // Matrix v1.19 CS API §"Client login via SSO" SCENARIO("GET /login does not advertise m.login.sso when SSO is not configured", "[homeserver][client-server][sso]") { diff --git a/tests/integration/test_oauth_metadata_flow.cpp b/tests/integration/test_oauth_metadata_flow.cpp new file mode 100644 index 000000000..58ce697b1 --- /dev/null +++ b/tests/integration/test_oauth_metadata_flow.cpp @@ -0,0 +1,255 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The OAuth 2.0 server metadata as a client reads it from a running homeserver: the checks Element X (through +// matrix-rust-sdk) makes before it offers an OAuth login (docs/todos/oauth-2-0-api.md, "What Element X needs"), and +// the fields the configuration turns on and off. + +#include "../support/InMemoryDatabaseConfig.hpp" +#include "../support/JsonTestSupport.hpp" +#include "../support/MasterKey.hpp" +#include "../support/RegistrationToken.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/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; + +struct MetadataSettings final +{ + std::string public_baseurl{"https://matrix.example.org"}; + bool registration_enabled{false}; + bool device_grant_enabled{false}; +}; + +[[nodiscard]] auto oauth_config(MetadataSettings const& settings) -> merovingian::config::Config +{ + auto security = merovingian::config::SecurityConfig{}; + security.secrets.master_key_file = merovingian::tests::shared_master_key_file(); + if (settings.registration_enabled) + { + merovingian::tests::enable_token_registration(security); + } + auto server = merovingian::config::ServerConfig{}; + server.public_baseurl = settings.public_baseurl; + server.oauth.enabled = true; + server.oauth.device_grant_enabled = settings.device_grant_enabled; + return { + std::move(server), + merovingian::config::ListenersConfig{}, + merovingian::tests::in_memory_database_config(), + std::move(security), + merovingian::config::ClientRateLimitsConfig{}, + merovingian::config::LogModulesConfig{}, + }; +} + +[[nodiscard]] auto fetch_metadata(MetadataSettings const& settings) -> merovingian::canonicaljson::Object +{ + auto started = merovingian::homeserver::start_client_server(oauth_config(settings)); + REQUIRE(started.started); + auto const response = merovingian::homeserver::handle_client_server_request( + started.runtime, {"GET", "/_matrix/client/v1/auth_metadata", {}, {}}); + REQUIRE(response.response.status == 200U); + return parse_object(response.response.body); +} + +[[nodiscard]] auto string_list(merovingian::canonicaljson::Object const& object, std::string_view key) + -> std::optional> +{ + auto const* array = object_member_as_array(object, key); + if (array == nullptr) + { + return std::nullopt; + } + auto out = std::vector{}; + for (auto const& item : *array) + { + auto const* text = std::get_if(&item.storage()); + if (text == nullptr) + { + return std::nullopt; + } + out.push_back(*text); + } + return out; +} + +[[nodiscard]] auto holds(std::optional> const& list, std::string_view value) -> bool +{ + if (!list.has_value()) + { + return false; + } + for (auto const& item : *list) + { + if (item == value) + { + return true; + } + } + return false; +} + +// Every member whose value is a URL: its name ends in `_endpoint` or `_uri`, or it is the issuer. +[[nodiscard]] auto url_members(merovingian::canonicaljson::Object const& object) + -> std::vector> +{ + auto out = std::vector>{}; + for (auto const& member : object) + { + auto const is_url = member.key == "issuer" || member.key.ends_with("_endpoint") || member.key.ends_with("_uri"); + auto const* text = member.value == nullptr ? nullptr : std::get_if(&member.value->storage()); + if (is_url && text != nullptr) + { + out.emplace_back(member.key, *text); + } + } + return out; +} + +} // namespace + +SCENARIO("auth_metadata passes every check Element X makes before an OAuth login", "[homeserver][oauth][element-x]") +{ + GIVEN("a running homeserver with the OAuth 2.0 API on") + { + WHEN("auth_metadata is read") + { + auto const body = fetch_metadata({}); + + THEN("every URL uses https") + { + auto const urls = url_members(body); + // issuer and the four required endpoints at least. + REQUIRE(urls.size() >= 5U); + for (auto const& [key, url] : urls) + { + INFO(key << " = " << url); + CHECK(url.starts_with("https://")); + } + } + + THEN("the issuer has no query or fragment") + { + auto const* issuer = string_member(body, "issuer"); + REQUIRE(issuer != nullptr); + CHECK(issuer->find('?') == std::string::npos); + CHECK(issuer->find('#') == std::string::npos); + } + + THEN("the four supported lists hold the values the SDK requires") + { + CHECK(holds(string_list(body, "response_types_supported"), "code")); + CHECK(holds(string_list(body, "response_modes_supported"), "query")); + CHECK(holds(string_list(body, "response_modes_supported"), "fragment")); + CHECK(holds(string_list(body, "grant_types_supported"), "authorization_code")); + CHECK(holds(string_list(body, "grant_types_supported"), "refresh_token")); + CHECK(holds(string_list(body, "code_challenge_methods_supported"), "S256")); + } + + THEN("a revocation endpoint and a registration endpoint are advertised") + { + auto const* revocation = string_member(body, "revocation_endpoint"); + REQUIRE(revocation != nullptr); + CHECK(*revocation == "https://matrix.example.org/_merovingian/oauth2/revoke"); + auto const* registration = string_member(body, "registration_endpoint"); + REQUIRE(registration != nullptr); + CHECK(*registration == "https://matrix.example.org/_merovingian/oauth2/register"); + } + + THEN("the account management fields are not advertised before the account pages exist") + { + CHECK(object_member(body, "account_management_uri") == nullptr); + CHECK(object_member(body, "account_management_actions_supported") == nullptr); + } + } + } +} + +SCENARIO("auth_metadata derives every address from a public_baseurl with a path", "[homeserver][oauth]") +{ + GIVEN("a homeserver whose public_baseurl is https://example.org/matrix/") + { + WHEN("auth_metadata is read") + { + auto const body = fetch_metadata({.public_baseurl = "https://example.org/matrix/"}); + + THEN("the issuer keeps one trailing slash and every endpoint sits under the path") + { + auto const* issuer = string_member(body, "issuer"); + REQUIRE(issuer != nullptr); + CHECK(*issuer == "https://example.org/matrix/"); + auto const* token = string_member(body, "token_endpoint"); + REQUIRE(token != nullptr); + CHECK(*token == "https://example.org/matrix/_merovingian/oauth2/token"); + auto const* authorize = string_member(body, "authorization_endpoint"); + REQUIRE(authorize != nullptr); + CHECK(*authorize == "https://example.org/matrix/_merovingian/oauth2/authorize"); + } + } + } +} + +SCENARIO("auth_metadata offers prompt=create only while registration is enabled", "[homeserver][oauth]") +{ + GIVEN("one homeserver with registration enabled and one without") + { + WHEN("auth_metadata is read from each") + { + auto const open = fetch_metadata({.registration_enabled = true}); + auto const closed = fetch_metadata({.registration_enabled = false}); + + THEN("prompt_values_supported is [create] with registration on and absent with it off") + { + auto const prompts = string_list(open, "prompt_values_supported"); + REQUIRE(prompts.has_value()); + CHECK(*prompts == std::vector{"create"}); + CHECK(object_member(closed, "prompt_values_supported") == nullptr); + } + } + } +} + +SCENARIO("auth_metadata advertises the device grant only while server.oauth.device_grant_enabled is true", + "[homeserver][oauth]") +{ + GIVEN("one homeserver with the device grant on and one with it off") + { + WHEN("auth_metadata is read from each") + { + auto const on = fetch_metadata({.device_grant_enabled = true}); + auto const off = fetch_metadata({.device_grant_enabled = false}); + + THEN("the device code grant type and device_authorization_endpoint appear only with it on") + { + constexpr auto device_code = std::string_view{"urn:ietf:params:oauth:grant-type:device_code"}; + CHECK(holds(string_list(on, "grant_types_supported"), device_code)); + auto const* endpoint = string_member(on, "device_authorization_endpoint"); + REQUIRE(endpoint != nullptr); + CHECK(*endpoint == "https://matrix.example.org/_merovingian/oauth2/device"); + CHECK_FALSE(holds(string_list(off, "grant_types_supported"), device_code)); + CHECK(object_member(off, "device_authorization_endpoint") == nullptr); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index 64266bb3a..99eb13dd4 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -293,7 +293,6 @@ shell = find_program('sh') 'unit/test_appservice_registration.cpp', 'unit/test_member_join_sender.cpp', 'unit/test_auth.cpp', - 'unit/test_auth_oidc_discovery.cpp', 'unit/test_auth_session.cpp', 'unit/test_audit_filter.cpp', 'unit/test_audit_rate_gate.cpp', @@ -327,7 +326,7 @@ shell = find_program('sh') 'unit/test_sync_stream_ceiling.cpp', 'unit/test_config_client_rate_limits.cpp', 'unit/test_config_log_modules.cpp', - 'unit/test_config_oidc_validation.cpp', + 'unit/test_config_oauth.cpp', 'unit/test_config_sso.cpp', 'unit/test_config_identity_server.cpp', 'unit/test_identity_bind_domains.cpp', @@ -435,10 +434,12 @@ shell = find_program('sh') 'unit/test_core_host_cookie.cpp', 'unit/test_core_request_cookies.cpp', 'unit/test_oauth_client_metadata.cpp', + 'unit/test_oauth_hand_off_allowlist.cpp', 'unit/test_oauth_page.cpp', 'unit/test_oauth_pkce.cpp', 'unit/test_oauth_redirect_uri.cpp', 'unit/test_oauth_scope.cpp', + 'unit/test_oauth_server_metadata.cpp', 'unit/test_http_request_limits.cpp', 'unit/test_inbound_ingestion.cpp', 'unit/test_join_routing.cpp', @@ -639,6 +640,7 @@ shell = find_program('sh') 'conformance/test_canonicaljson_parser.cpp', 'conformance/test_canonicaljson_serializer.cpp', 'conformance/test_client_server_conformance.cpp', + 'conformance/test_oauth_metadata_conformance.cpp', 'conformance/test_open_registration_conformance.cpp', 'conformance/test_account_lifecycle_conformance.cpp', 'conformance/test_device_lifecycle_conformance.cpp', @@ -725,7 +727,7 @@ shell = find_program('sh') include_directories: inc, link_args: password_hash_cost_link_args, dependencies: [catch2_dep, thread_dep, libsodium_dep, openssl_dep, libpq_dep, sqlite_dep, libcurl_dep, resolv_dep], - link_with: [appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], + link_with: [appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, oauth_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], ) # Most scenarios start a server and log a user in, so this binary grows with every scenario. It reached @@ -847,6 +849,7 @@ shell = find_program('sh') 'integration/test_media_thumbnail_flow.cpp', 'integration/test_media_thumbnail_revalidation_flow.cpp', 'integration/test_security_audit_remote_media.cpp', + 'integration/test_oauth_metadata_flow.cpp', 'integration/test_observability_flow.cpp', 'integration/test_operator_admin_flow.cpp', 'integration/test_admin_masquerade_refusal_flow.cpp', @@ -964,7 +967,7 @@ shell = find_program('sh') include_directories: inc, link_args: password_hash_cost_link_args, dependencies: [catch2_dep, thread_dep, libsodium_dep, openssl_dep, libpq_dep, sqlite_dep, libcurl_dep, resolv_dep], - link_with: [appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, federation_worker_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], + link_with: [appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, federation_worker_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, oauth_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], cpp_args: [thumbnail_test_args, thumbnail_gate_test_args, federation_worker_test_args, server_test_args, '-DMEROVINGIAN_TEST_SOURCE_ROOT="' + meson.project_source_root() + '"'], ) @@ -985,7 +988,7 @@ shell = find_program('sh') ), include_directories: inc, dependencies: [catch2_dep, thread_dep, libsodium_dep, openssl_dep, libpq_dep, sqlite_dep, libcurl_dep, resolv_dep], - link_with: [appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], + link_with: [appservice_lib, auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, oauth_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], ) test('live-integration-tests', live_integration_tests) @@ -1000,7 +1003,7 @@ shell = find_program('sh') ), include_directories: inc, dependencies: [catch2_dep, thread_dep, libsodium_dep, openssl_dep, libpq_dep, sqlite_dep, libcurl_dep, resolv_dep], - link_with: [auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, federation_worker_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], + link_with: [auth_lib, canonicaljson_lib, core_lib, config_lib, crypto_lib, database_lib, email_lib, events_lib, federation_lib, federation_worker_lib, homeserver_lib, http_lib, identity_lib, ipc_lib, media_lib, net_lib, oauth_lib, observability_lib, platform_lib, push_lib, rooms_lib, sync_lib, trust_safety_lib], ) #The harness's own default duration is short (2 s, MEROVINGIAN_LOCK_SOAK_SECONDS diff --git a/tests/tooling/test_example_config.py b/tests/tooling/test_example_config.py index c6a272285..141caad58 100644 --- a/tests/tooling/test_example_config.py +++ b/tests/tooling/test_example_config.py @@ -48,6 +48,33 @@ def test_example_config_enables_remote_media_fetching(self) -> None: self.assertEqual(active.get("security.media.remote_fetch_enabled"), "true") self.assertEqual(active.get("security.media.remote_fetch_media_policy"), "allow") + def test_example_config_documents_the_oauth_keys_commented_and_off(self) -> None: + # GIVEN the example configs an operator starts from + for path in (EXAMPLE_CONFIG, BSD_EXAMPLE_CONFIG): + with self.subTest(path=path.name): + lines = [line.strip() for line in path.read_text(encoding="utf-8").splitlines()] + + # WHEN their server.oauth and server.oidc lines are read + oauth = { + line.lstrip("#").strip().split("=", 1)[0]: line + for line in lines + if line.lstrip("#").strip().startswith("server.oauth.") + } + oidc = [line for line in lines if "server.oidc." in line and "=" in line] + + # THEN each server.oauth key is documented, commented out, with its default (off), + # and no server.oidc key is left: the server refuses those at start-up (ADR-0764) + self.assertEqual( + oauth, + { + "server.oauth.enabled": "# server.oauth.enabled=false", + "server.oauth.legacy_api_enabled": "# server.oauth.legacy_api_enabled=true", + "server.oauth.device_grant_enabled": "# server.oauth.device_grant_enabled=false", + "server.oauth.hand_off_redirect_allowlist": "# server.oauth.hand_off_redirect_allowlist=", + }, + ) + self.assertEqual(oidc, []) + # The BSD example is the Linux example with a header of its own and the BSD paths # (ADR-0738): the configuration directory is a placeholder each package fills in, diff --git a/tests/unit/test_auth_oidc_discovery.cpp b/tests/unit/test_auth_oidc_discovery.cpp deleted file mode 100644 index 197a24afa..000000000 --- a/tests/unit/test_auth_oidc_discovery.cpp +++ /dev/null @@ -1,183 +0,0 @@ -// SPDX-License-Identifier: GPL-3.0-or-later -// -// +-------------------------------------------------------------------------+ -// | OIDC DISCOVERY METADATA UNIT TESTS | -// | | -// | Spec: Matrix Client-Server API v1.19 — GET /_matrix/client/v1/auth_metadata | -// | URL: ../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv1auth_metadata | -// +-------------------------------------------------------------------------+ - -#include "merovingian/auth/OidcDiscovery.hpp" -#include "merovingian/config/OidcConfig.hpp" - -#include - -#include -#include - -namespace cjson = merovingian::canonicaljson; - -namespace -{ - -[[nodiscard]] auto field(cjson::Object const& object, std::string_view key) -> cjson::Value const* -{ - for (auto const& member : object) - { - if (member.key == key) - { - return member.value.get(); - } - } - return nullptr; -} - -[[nodiscard]] auto string_value(cjson::Value const* value) -> std::string -{ - if (value == nullptr) - { - return {}; - } - auto const* text = std::get_if(&value->storage()); - return text == nullptr ? std::string{} : *text; -} - -[[nodiscard]] auto has_string_member(cjson::Object const& object, std::string_view key, std::string_view expected) - -> bool -{ - return string_value(field(object, key)) == expected; -} - -} // namespace - -SCENARIO("OIDC metadata is absent when OIDC is not enabled", "[auth][oidc]") -{ - GIVEN("an empty OIDC configuration") - { - auto const config = merovingian::config::OidcConfig{}; - - WHEN("auth metadata is built") - { - auto const metadata = merovingian::auth::make_auth_metadata(config); - - THEN("the result reports not configured") - { - REQUIRE_FALSE(metadata.configured); - REQUIRE(metadata.fields.empty()); - } - } - } -} - -SCENARIO("OIDC metadata contains all required v1.19 fields", "[auth][oidc]") -{ - GIVEN("a fully populated OIDC configuration") - { - auto config = merovingian::config::OidcConfig{}; - config.enabled = true; - config.issuer = "https://account.example.com/"; - config.authorization_endpoint = "https://account.example.com/oauth2/auth"; - config.token_endpoint = "https://account.example.com/oauth2/token"; - config.registration_endpoint = "https://account.example.com/oauth2/clients/register"; - config.revocation_endpoint = "https://account.example.com/oauth2/revoke"; - config.device_authorization_endpoint = "https://account.example.com/oauth2/device"; - config.account_management_uri = "https://account.example.com/manage"; - config.account_management_actions_supported = {"org.matrix.profile", "org.matrix.devices_list", - "org.matrix.account_deactivate"}; - - WHEN("auth metadata is built") - { - auto const metadata = merovingian::auth::make_auth_metadata(config); - - THEN("the result reports configured and contains every required field") - { - REQUIRE(metadata.configured); - REQUIRE(has_string_member(metadata.fields, "issuer", config.issuer)); - REQUIRE(has_string_member(metadata.fields, "authorization_endpoint", config.authorization_endpoint)); - REQUIRE(has_string_member(metadata.fields, "token_endpoint", config.token_endpoint)); - REQUIRE(has_string_member(metadata.fields, "registration_endpoint", config.registration_endpoint)); - REQUIRE(has_string_member(metadata.fields, "revocation_endpoint", config.revocation_endpoint)); - REQUIRE(has_string_member(metadata.fields, "device_authorization_endpoint", - config.device_authorization_endpoint)); - REQUIRE(has_string_member(metadata.fields, "account_management_uri", config.account_management_uri)); - } - } - } -} - -SCENARIO("OIDC metadata omits optional fields when they are empty", "[auth][oidc]") -{ - GIVEN("an OIDC configuration without optional endpoints") - { - auto config = merovingian::config::OidcConfig{}; - config.enabled = true; - config.issuer = "https://auth.example.com/"; - config.authorization_endpoint = "https://auth.example.com/auth"; - config.token_endpoint = "https://auth.example.com/token"; - config.registration_endpoint = "https://auth.example.com/register"; - config.revocation_endpoint = "https://auth.example.com/revoke"; - - WHEN("auth metadata is built") - { - auto const metadata = merovingian::auth::make_auth_metadata(config); - - THEN("device_authorization_endpoint and account_management_uri are absent") - { - REQUIRE(metadata.configured); - REQUIRE(field(metadata.fields, "device_authorization_endpoint") == nullptr); - REQUIRE(field(metadata.fields, "account_management_uri") == nullptr); - REQUIRE(field(metadata.fields, "account_management_actions_supported") == nullptr); - } - } - } -} - -SCENARIO("OIDC metadata advertises the required grant and response types", "[auth][oidc]") -{ - GIVEN("a minimal enabled OIDC configuration") - { - auto config = merovingian::config::OidcConfig{}; - config.enabled = true; - config.issuer = "https://auth.example.com/"; - config.authorization_endpoint = "https://auth.example.com/auth"; - config.token_endpoint = "https://auth.example.com/token"; - config.registration_endpoint = "https://auth.example.com/register"; - config.revocation_endpoint = "https://auth.example.com/revoke"; - - WHEN("auth metadata is built") - { - auto const metadata = merovingian::auth::make_auth_metadata(config); - - THEN("the response_types_supported array contains exactly 'code'") - { - auto const* response_types = field(metadata.fields, "response_types_supported"); - REQUIRE(response_types != nullptr); - auto const* array = std::get_if(&response_types->storage()); - REQUIRE(array != nullptr); - REQUIRE(array->size() == 1U); - REQUIRE(string_value(&array->front()) == "code"); - } - - THEN("the code_challenge_methods_supported array contains exactly 'S256'") - { - auto const* methods = field(metadata.fields, "code_challenge_methods_supported"); - REQUIRE(methods != nullptr); - auto const* array = std::get_if(&methods->storage()); - REQUIRE(array != nullptr); - REQUIRE(array->size() == 1U); - REQUIRE(string_value(&array->front()) == "S256"); - } - - THEN("the grant_types_supported array contains 'authorization_code' and 'refresh_token'") - { - auto const* grants = field(metadata.fields, "grant_types_supported"); - REQUIRE(grants != nullptr); - auto const* array = std::get_if(&grants->storage()); - REQUIRE(array != nullptr); - REQUIRE(array->size() == 2U); - REQUIRE(string_value(&array->at(0)) == "authorization_code"); - REQUIRE(string_value(&array->at(1)) == "refresh_token"); - } - } - } -} diff --git a/tests/unit/test_config_oauth.cpp b/tests/unit/test_config_oauth.cpp new file mode 100644 index 000000000..7166fdc51 --- /dev/null +++ b/tests/unit/test_config_oauth.cpp @@ -0,0 +1,435 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// +-------------------------------------------------------------------------+ +// | server.oauth.* PARSING, VALIDATION AND RELOAD TESTS | +// | | +// | Plan: docs/todos/oauth-2-0-api.md, "Configuration" | +// | ADR-0761 (legacy API switch), ADR-0764 (server.oidc.* refused), | +// | ADR-0773 (issuer from public_baseurl), ADR-0774 (hand-off allowlist) | +// +-------------------------------------------------------------------------+ + +#include "merovingian/config/Config.hpp" +#include "merovingian/config/ConfigParser.hpp" +#include "merovingian/config/ConfigValidationFinding.hpp" +#include "merovingian/config/ReloadPlan.hpp" +#include "merovingian/config/ReloadPolicy.hpp" + +#include +#include + +#include +#include +#include +#include + +namespace +{ + +using merovingian::config::ConfigValidationFinding; + +[[nodiscard]] auto finding_for(std::vector const& findings, std::string_view field) + -> ConfigValidationFinding const* +{ + for (auto const& finding : findings) + { + if (finding.field == field) + { + return &finding; + } + } + return nullptr; +} + +[[nodiscard]] auto contains_finding(std::vector const& findings, std::string_view field) + -> bool +{ + return finding_for(findings, field) != nullptr; +} + +[[nodiscard]] auto parse(std::string const& input) -> std::vector +{ + return merovingian::config::parse_key_value_config(input).findings; +} + +} // namespace + +SCENARIO("server.oauth.* defaults leave the OAuth 2.0 API off and the legacy API on", "[config][oauth]") +{ + GIVEN("a configuration that sets no server.oauth key") + { + WHEN("it is parsed") + { + auto const result = merovingian::config::parse_key_value_config(""); + auto const& oauth = result.config.server().oauth; + + THEN("each key has its documented default and nothing is refused") + { + REQUIRE(result.findings.empty()); + CHECK_FALSE(oauth.enabled); + CHECK(oauth.legacy_api_enabled); + CHECK_FALSE(oauth.device_grant_enabled); + CHECK(oauth.hand_off_redirect_allowlist.empty()); + } + } + } +} + +SCENARIO("server.oauth.* keys are parsed into the configuration", "[config][oauth][parser]") +{ + GIVEN("a configuration that sets all four keys") + { + auto const input = std::string{"server.oauth.enabled=true\n" + "server.oauth.legacy_api_enabled=false\n" + "server.oauth.device_grant_enabled=true\n" + "server.oauth.hand_off_redirect_allowlist=https://app.example.com, " + "io.element.app:\n"}; + + WHEN("it is parsed") + { + auto const result = merovingian::config::parse_key_value_config(input); + auto const& oauth = result.config.server().oauth; + + THEN("every value is stored and the combination is accepted") + { + REQUIRE(result.findings.empty()); + CHECK(oauth.enabled); + CHECK_FALSE(oauth.legacy_api_enabled); + CHECK(oauth.device_grant_enabled); + CHECK(oauth.hand_off_redirect_allowlist == + std::vector{"https://app.example.com", "io.element.app:"}); + } + } + } +} + +SCENARIO("server.oauth.* boolean keys refuse a value that is not a boolean", "[config][oauth][parser]") +{ + GIVEN("each boolean key set to maybe") + { + auto const key = GENERATE(as{}, "server.oauth.enabled", "server.oauth.legacy_api_enabled", + "server.oauth.device_grant_enabled"); + + WHEN("it is parsed") + { + auto const findings = parse(key + "=maybe\n"); + + THEN("the key is refused") + { + INFO(key); + REQUIRE(contains_finding(findings, key)); + } + } + } +} + +SCENARIO("every server.oidc.* key is refused with a message naming server.oauth.enabled", "[config][oauth][oidc]") +{ + GIVEN("a configuration that still sets a server.oidc.* key") + { + auto const key = GENERATE(as{}, "server.oidc.enabled", "server.oidc.issuer", + "server.oidc.authorization_endpoint", "server.oidc.account_management_uri", + "server.oidc.no_such_key"); + auto const value = std::string{key == "server.oidc.enabled" ? "false" : "https://auth.example.org/"}; + + WHEN("it is parsed") + { + auto const findings = parse(key + "=" + value + "\n"); + + THEN("start-up is refused, and the message points at server.oauth.enabled") + { + INFO(key); + auto const* finding = finding_for(findings, key); + REQUIRE(finding != nullptr); + CHECK(finding->message.find("server.oauth.enabled") != std::string::npos); + CHECK(finding->message.find("unknown configuration key") == std::string::npos); + } + } + } +} + +SCENARIO("server.oauth.legacy_api_enabled=false needs server.oauth.enabled=true", "[config][oauth]") +{ + GIVEN("the legacy API switched off") + { + WHEN("the OAuth 2.0 API is off") + { + auto const findings = parse("server.oauth.legacy_api_enabled=false\n"); + + THEN("the configuration is refused: no user could log in") + { + REQUIRE(contains_finding(findings, "server.oauth.legacy_api_enabled")); + } + } + + WHEN("the OAuth 2.0 API is on") + { + auto const findings = parse("server.oauth.enabled=true\nserver.oauth.legacy_api_enabled=false\n"); + + THEN("it is accepted") + { + REQUIRE(findings.empty()); + } + } + } +} + +SCENARIO("server.oauth.device_grant_enabled=true needs server.oauth.enabled=true", "[config][oauth]") +{ + GIVEN("the device grant switched on") + { + WHEN("the OAuth 2.0 API is off") + { + auto const findings = parse("server.oauth.device_grant_enabled=true\n"); + + THEN("the configuration is refused") + { + REQUIRE(contains_finding(findings, "server.oauth.device_grant_enabled")); + } + } + + WHEN("the OAuth 2.0 API is on") + { + auto const findings = parse("server.oauth.enabled=true\nserver.oauth.device_grant_enabled=true\n"); + + THEN("it is accepted") + { + REQUIRE(findings.empty()); + } + } + } +} + +SCENARIO("server.oauth.hand_off_redirect_allowlist needs server.oauth.enabled=true and valid entries", + "[config][oauth][allowlist]") +{ + GIVEN("a hand-off allowlist") + { + WHEN("it is set while the OAuth 2.0 API is off") + { + auto const findings = parse("server.oauth.hand_off_redirect_allowlist=https://app.example.com\n"); + + THEN("the configuration is refused") + { + REQUIRE(contains_finding(findings, "server.oauth.hand_off_redirect_allowlist")); + } + } + + WHEN("it names an entry twice while the OAuth 2.0 API is on") + { + auto const findings = parse("server.oauth.enabled=true\n" + "server.oauth.hand_off_redirect_allowlist=io.element.app:,io.element.app:\n"); + + THEN("the configuration is refused") + { + REQUIRE(contains_finding(findings, "server.oauth.hand_off_redirect_allowlist")); + } + } + + WHEN("it holds 33 entries while the OAuth 2.0 API is on") + { + auto list = std::string{}; + for (auto index = 0; index < 33; ++index) + { + list += (index == 0 ? "" : ",") + std::string{"https://h"} + std::to_string(index) + ".example.com"; + } + auto const findings = + parse("server.oauth.enabled=true\nserver.oauth.hand_off_redirect_allowlist=" + list + "\n"); + + THEN("the configuration is refused") + { + REQUIRE(contains_finding(findings, "server.oauth.hand_off_redirect_allowlist")); + } + } + } +} + +SCENARIO("a hand-off allowlist entry of neither shape is refused", "[config][oauth][allowlist]") +{ + GIVEN("an entry that is neither an https origin nor a bare private-use scheme") + { + auto const entry = GENERATE(as{}, "https://app.example.com/", "https://app.example.com/cb", + "http://app.example.com", "app.example.com", + "https:", "javascript:", "io.element.app:/callback", "https://App.example.com"); + + WHEN("it is configured while the OAuth 2.0 API is on") + { + auto const findings = + parse("server.oauth.enabled=true\nserver.oauth.hand_off_redirect_allowlist=" + entry + "\n"); + + THEN("the configuration is refused") + { + INFO(entry); + REQUIRE(contains_finding(findings, "server.oauth.hand_off_redirect_allowlist")); + } + } + } +} + +SCENARIO("an https server.public_baseurl, with or without a path, is accepted while OAuth is on", + "[config][oauth][public_baseurl]") +{ + GIVEN("a plain https base URL, with or without a path and a trailing slash") + { + auto const base = GENERATE(as{}, "https://matrix.example.org", "https://matrix.example.org/", + "https://example.org/matrix", "https://example.org:8448/matrix/"); + + WHEN("it is configured with server.oauth.enabled=true") + { + auto const findings = parse("server.oauth.enabled=true\nserver.public_baseurl=" + base + "\n"); + + THEN("it is accepted") + { + INFO(base); + REQUIRE(findings.empty()); + } + } + } +} + +SCENARIO("a server.public_baseurl that breaks a rule is refused while OAuth is on, naming both keys", + "[config][oauth][public_baseurl]") +{ + GIVEN("a base URL that is not https, has a query, fragment or userinfo, no host, or a space") + { + auto const base = GENERATE(as{}, "http://matrix.example.org", "https://matrix.example.org/?a=b", + "https://matrix.example.org/#top", "https://user@matrix.example.org", "https://", + "https://matrix example.org", "https://matrix.example.org/a b"); + + WHEN("it is configured with server.oauth.enabled=true") + { + auto const findings = parse("server.oauth.enabled=true\nserver.public_baseurl=" + base + "\n"); + + THEN("start-up is refused with a message that names both keys") + { + INFO(base); + // The generic public_baseurl check may report as well; one finding must name both keys. + auto named = false; + for (auto const& candidate : findings) + { + named = named || (candidate.field == "server.public_baseurl" && + candidate.message.find("server.oauth.enabled") != std::string::npos && + candidate.message.find("server.public_baseurl") != std::string::npos); + } + REQUIRE(named); + } + } + } +} + +SCENARIO("server.public_baseurl with an upper-case scheme, or a query while OAuth is off", + "[config][oauth][public_baseurl]") +{ + GIVEN("the OAuth 2.0 API switched on") + { + WHEN("server.public_baseurl is written with an upper-case scheme") + { + auto const findings = + parse("server.oauth.enabled=true\nserver.public_baseurl=HTTPS://matrix.example.org\n"); + + THEN("it is refused, not repaired") + { + REQUIRE(contains_finding(findings, "server.public_baseurl")); + } + } + } + + GIVEN("the OAuth 2.0 API left off") + { + WHEN("server.public_baseurl has a query, which only the OAuth rule refuses") + { + auto const findings = parse("server.public_baseurl=https://matrix.example.org/?a=b\n"); + + THEN("the validation that applied before is unchanged and accepts it") + { + REQUIRE_FALSE(contains_finding(findings, "server.public_baseurl")); + } + } + } +} + +SCENARIO("server.sso.authorization_url cannot be set while the OAuth 2.0 API is on", "[config][oauth][sso]") +{ + GIVEN("an external SSO authorization URL") + { + WHEN("the OAuth 2.0 API is on") + { + auto const findings = parse("server.oauth.enabled=true\n" + "server.sso.authorization_url=https://sso.example.org/login\n"); + + THEN("start-up is refused") + { + auto const* finding = finding_for(findings, "server.sso.authorization_url"); + REQUIRE(finding != nullptr); + CHECK(finding->message.find("server.oauth.enabled") != std::string::npos); + } + } + + WHEN("the OAuth 2.0 API is off") + { + auto const findings = parse("server.sso.authorization_url=https://sso.example.org/login\n"); + + THEN("the URL alone is not refused") + { + REQUIRE_FALSE(contains_finding(findings, "server.sso.authorization_url")); + } + } + } +} + +SCENARIO("every server.oauth.* key needs a restart", "[config][oauth][reload]") +{ + GIVEN("the four keys") + { + auto const key = GENERATE(as{}, "server.oauth.enabled", "server.oauth.legacy_api_enabled", + "server.oauth.device_grant_enabled", "server.oauth.hand_off_redirect_allowlist"); + + WHEN("their reload policy is read") + { + auto const policy = merovingian::config::reload_policy_for_key(key); + + THEN("it is restart_required") + { + INFO(key); + REQUIRE(policy == merovingian::config::ReloadPolicy::restart_required); + } + } + } +} + +SCENARIO("the reload plan reports a change of each server.oauth.* key", "[config][oauth][reload]") +{ + GIVEN("a current configuration with OAuth off and a next one with every key changed") + { + auto const current = merovingian::config::parse_key_value_config("").config; + auto const next = + merovingian::config::parse_key_value_config("server.oauth.enabled=true\n" + "server.oauth.legacy_api_enabled=false\n" + "server.oauth.device_grant_enabled=true\n" + "server.oauth.hand_off_redirect_allowlist=io.element.app:\n") + .config; + + WHEN("a reload plan is built") + { + auto const plan = merovingian::config::build_reload_plan(current, next); + + THEN("it lists all four keys as restart_required changes") + { + REQUIRE(plan.restart_required_change_count() == 4U); + for (auto const* key : + {"server.oauth.enabled", "server.oauth.legacy_api_enabled", "server.oauth.device_grant_enabled", + "server.oauth.hand_off_redirect_allowlist"}) + { + INFO(key); + auto found = false; + for (auto const& change : plan.changes()) + { + found = found || (change.key == key && + change.policy == merovingian::config::ReloadPolicy::restart_required); + } + CHECK(found); + } + } + } + } +} diff --git a/tests/unit/test_config_oidc_validation.cpp b/tests/unit/test_config_oidc_validation.cpp deleted file mode 100644 index 75f1f4c13..000000000 --- a/tests/unit/test_config_oidc_validation.cpp +++ /dev/null @@ -1,250 +0,0 @@ -// SPDX-License-Identifier: GPL-3.0-or-later -// -// +-------------------------------------------------------------------------+ -// | OIDC CONFIGURATION PARSING AND VALIDATION TESTS | -// | | -// | Spec: Matrix Client-Server API v1.19 — MSC2965 discovery metadata | -// | URL: ../../docs/matrix-v1.19-spec/client-server-api.md | -// +-------------------------------------------------------------------------+ - -#include "merovingian/config/Config.hpp" -#include "merovingian/config/ConfigValidationFinding.hpp" -#include "merovingian/config/ConfigParser.hpp" - -#include - -#include -#include -#include - -namespace -{ - -[[nodiscard]] auto contains_finding(std::vector const& findings, - std::string_view field) -> bool -{ - for (auto const& finding : findings) - { - if (finding.field == field) - { - return true; - } - } - return false; -} - -} // namespace - -SCENARIO("OIDC is disabled by default and requires no endpoints", "[config][oidc]") -{ - GIVEN("a default server configuration") - { - auto config = merovingian::config::Config{}; - - WHEN("validated") - { - auto const findings = merovingian::config::validate(config); - - THEN("no OIDC findings are reported") - { - REQUIRE(merovingian::config::is_valid(config)); - REQUIRE_FALSE(contains_finding(findings, "server.oidc.enabled")); - REQUIRE_FALSE(contains_finding(findings, "server.oidc.issuer")); - } - } - } -} - -SCENARIO("OIDC configuration with all required HTTPS endpoints is valid", "[config][oidc]") -{ - GIVEN("a config string enabling OIDC with valid endpoints") - { - auto const input = std::string{ - "server.oidc.enabled=true\n" - "server.oidc.issuer=https://account.example.com/\n" - "server.oidc.authorization_endpoint=https://account.example.com/oauth2/auth\n" - "server.oidc.token_endpoint=https://account.example.com/oauth2/token\n" - "server.oidc.registration_endpoint=https://account.example.com/oauth2/clients/register\n" - "server.oidc.revocation_endpoint=https://account.example.com/oauth2/revoke\n" - "server.oidc.device_authorization_endpoint=https://account.example.com/oauth2/device\n" - "server.oidc.account_management_uri=https://account.example.com/manage\n" - "server.oidc.account_management_actions_supported=org.matrix.profile,org.matrix.devices_list\n"}; - - WHEN("parsed and validated") - { - auto const result = merovingian::config::parse_key_value_config(input); - - THEN("the configuration is accepted") - { - REQUIRE(merovingian::config::is_valid(result.config)); - REQUIRE(result.findings.empty()); - REQUIRE(result.config.server().oidc.enabled); - REQUIRE(result.config.server().oidc.issuer == "https://account.example.com/"); - REQUIRE(result.config.server().oidc.account_management_actions_supported.size() == 2U); - } - } - } -} - -SCENARIO("OIDC enabled without required fields is rejected", "[config][oidc]") -{ - GIVEN("a config string enabling OIDC but omitting endpoints") - { - auto const input = std::string{"server.oidc.enabled=true\n"}; - - WHEN("parsed and validated") - { - auto const result = merovingian::config::parse_key_value_config(input); - - THEN("missing required fields are reported") - { - REQUIRE_FALSE(merovingian::config::is_valid(result.config)); - REQUIRE(contains_finding(result.findings, "server.oidc.issuer")); - REQUIRE(contains_finding(result.findings, "server.oidc.authorization_endpoint")); - REQUIRE(contains_finding(result.findings, "server.oidc.token_endpoint")); - REQUIRE(contains_finding(result.findings, "server.oidc.registration_endpoint")); - REQUIRE(contains_finding(result.findings, "server.oidc.revocation_endpoint")); - } - } - } -} - -SCENARIO("OIDC issuer must be an HTTPS origin URL with no query or fragment", "[config][oidc]") -{ - GIVEN("config inputs with invalid issuers") - { - auto const missing = std::string{"server.oidc.enabled=true\n" - "server.oidc.authorization_endpoint=https://example.com/auth\n" - "server.oidc.token_endpoint=https://example.com/token\n" - "server.oidc.registration_endpoint=https://example.com/register\n" - "server.oidc.revocation_endpoint=https://example.com/revoke\n"}; - - auto const http = missing + "server.oidc.issuer=http://example.com/\n"; - auto const with_query = missing + "server.oidc.issuer=https://example.com/?foo=bar\n"; - auto const with_fragment = missing + "server.oidc.issuer=https://example.com/#section\n"; - - WHEN("validated") - { - auto const missing_result = merovingian::config::parse_key_value_config(missing); - auto const http_result = merovingian::config::parse_key_value_config(http); - auto const query_result = merovingian::config::parse_key_value_config(with_query); - auto const fragment_result = merovingian::config::parse_key_value_config(with_fragment); - - THEN("each invalid issuer is rejected") - { - REQUIRE(contains_finding(missing_result.findings, "server.oidc.issuer")); - REQUIRE(contains_finding(http_result.findings, "server.oidc.issuer")); - REQUIRE(contains_finding(query_result.findings, "server.oidc.issuer")); - REQUIRE(contains_finding(fragment_result.findings, "server.oidc.issuer")); - } - } - } -} - -SCENARIO("OIDC endpoints must use HTTPS when present", "[config][oidc]") -{ - GIVEN("a config with a non-HTTPS endpoint") - { - auto const input = std::string{"server.oidc.enabled=true\n" - "server.oidc.issuer=https://example.com/\n" - "server.oidc.authorization_endpoint=http://example.com/auth\n" - "server.oidc.token_endpoint=https://example.com/token\n" - "server.oidc.registration_endpoint=https://example.com/register\n" - "server.oidc.revocation_endpoint=https://example.com/revoke\n"}; - - WHEN("parsed and validated") - { - auto const result = merovingian::config::parse_key_value_config(input); - - THEN("the cleartext endpoint is rejected") - { - REQUIRE(contains_finding(result.findings, "server.oidc.authorization_endpoint")); - } - } - } - - GIVEN("a config with an optional non-HTTPS endpoint") - { - auto const input = std::string{"server.oidc.enabled=true\n" - "server.oidc.issuer=https://example.com/\n" - "server.oidc.authorization_endpoint=https://example.com/auth\n" - "server.oidc.token_endpoint=https://example.com/token\n" - "server.oidc.registration_endpoint=https://example.com/register\n" - "server.oidc.revocation_endpoint=https://example.com/revoke\n" - "server.oidc.account_management_uri=http://example.com/manage\n"}; - - WHEN("parsed and validated") - { - auto const result = merovingian::config::parse_key_value_config(input); - - THEN("the optional cleartext URI is rejected") - { - REQUIRE(contains_finding(result.findings, "server.oidc.account_management_uri")); - } - } - } -} - -SCENARIO("is_valid_https_url requires an HTTPS scheme and non-empty authority", "[config][oidc][helpers]") -{ - GIVEN("a set of URLs to validate") - { - WHEN("checked") - { - THEN("HTTPS URLs are accepted") - { - REQUIRE(merovingian::config::is_valid_https_url("https://example.com/")); - REQUIRE(merovingian::config::is_valid_https_url("https://example.com/path?query=1")); - } - - THEN("non-HTTPS, empty, and malformed URLs are rejected") - { - REQUIRE_FALSE(merovingian::config::is_valid_https_url("http://example.com/")); - REQUIRE_FALSE(merovingian::config::is_valid_https_url("https://")); - REQUIRE_FALSE(merovingian::config::is_valid_https_url("")); - REQUIRE_FALSE(merovingian::config::is_valid_https_url("https://exam ple.com/")); - } - } - } -} - -SCENARIO("is_valid_https_origin_url forbids query and fragment components", "[config][oidc][helpers]") -{ - GIVEN("a set of origin URLs to validate") - { - WHEN("checked") - { - THEN("plain HTTPS origins are accepted") - { - REQUIRE(merovingian::config::is_valid_https_origin_url("https://example.com/")); - REQUIRE(merovingian::config::is_valid_https_origin_url("https://example.com")); - } - - THEN("non-HTTPS, query, fragment, and malformed origins are rejected") - { - REQUIRE_FALSE(merovingian::config::is_valid_https_origin_url("http://example.com/")); - REQUIRE_FALSE(merovingian::config::is_valid_https_origin_url("https://example.com/?q=1")); - REQUIRE_FALSE(merovingian::config::is_valid_https_origin_url("https://example.com/#frag")); - REQUIRE_FALSE(merovingian::config::is_valid_https_origin_url("https://")); - } - } - } -} - -SCENARIO("server.oidc.enabled rejects non-boolean values", "[config][oidc][parser]") -{ - GIVEN("a config string with a malformed boolean") - { - auto const input = std::string{"server.oidc.enabled=maybe\n"}; - - WHEN("parsed") - { - auto const result = merovingian::config::parse_key_value_config(input); - - THEN("a parse finding is reported") - { - REQUIRE(contains_finding(result.findings, "server.oidc.enabled")); - } - } - } -} diff --git a/tests/unit/test_config_sso.cpp b/tests/unit/test_config_sso.cpp index c842aeee8..2d4b8adfa 100644 --- a/tests/unit/test_config_sso.cpp +++ b/tests/unit/test_config_sso.cpp @@ -8,8 +8,8 @@ // +-------------------------------------------------------------------------+ #include "merovingian/config/Config.hpp" -#include "merovingian/config/ConfigValidationFinding.hpp" #include "merovingian/config/ConfigParser.hpp" +#include "merovingian/config/ConfigValidationFinding.hpp" #include @@ -273,3 +273,28 @@ SCENARIO("a malformed identity_providers key without a field segment is rejected } } } + +// Moved from the retired server.oidc.* tests: SSO, the identity server allowlist and the SSO redirect allowlist +// still validate their URLs with this helper. +SCENARIO("is_valid_https_url requires an HTTPS scheme and non-empty authority", "[config][sso][helpers]") +{ + GIVEN("a set of URLs to validate") + { + WHEN("checked") + { + THEN("HTTPS URLs are accepted") + { + REQUIRE(merovingian::config::is_valid_https_url("https://example.com/")); + REQUIRE(merovingian::config::is_valid_https_url("https://example.com/path?query=1")); + } + + THEN("non-HTTPS, empty, and malformed URLs are rejected") + { + REQUIRE_FALSE(merovingian::config::is_valid_https_url("http://example.com/")); + REQUIRE_FALSE(merovingian::config::is_valid_https_url("https://")); + REQUIRE_FALSE(merovingian::config::is_valid_https_url("")); + REQUIRE_FALSE(merovingian::config::is_valid_https_url("https://exam ple.com/")); + } + } + } +} diff --git a/tests/unit/test_http_rate_limit_tiers.cpp b/tests/unit/test_http_rate_limit_tiers.cpp index ed2703f8c..c115d7881 100644 --- a/tests/unit/test_http_rate_limit_tiers.cpp +++ b/tests/unit/test_http_rate_limit_tiers.cpp @@ -1,10 +1,10 @@ // SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/http/RateLimit.hpp" #include "merovingian/http/RateLimitConfig.hpp" #include "merovingian/http/RateLimitEngine.hpp" #include "merovingian/http/RateLimitPolicy.hpp" #include "merovingian/http/RateLimitTier.hpp" -#include "merovingian/http/RateLimit.hpp" #include @@ -85,6 +85,9 @@ SCENARIO("Rate-limit tiers classify client-server routes explicitly", "[http][ra // generic: everything else. REQUIRE(tier_of("/_matrix/client/v3/account/whoami") == RateLimitTier::generic); REQUIRE(tier_of("/_matrix/client/v3/rooms/!room/send/m.room.message") == RateLimitTier::generic); + // OAuth server metadata: the spec marks it not rate-limited, so it is not auth_sensitive (ADR-0775). + REQUIRE(tier_of("/_matrix/client/v1/auth_metadata") == RateLimitTier::generic); + REQUIRE(tier_of("/_matrix/client/unstable/org.matrix.msc2965/auth_metadata") == RateLimitTier::generic); } } } diff --git a/tests/unit/test_oauth_hand_off_allowlist.cpp b/tests/unit/test_oauth_hand_off_allowlist.cpp new file mode 100644 index 000000000..be998122a --- /dev/null +++ b/tests/unit/test_oauth_hand_off_allowlist.cpp @@ -0,0 +1,131 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The shape of a hand-off redirect allowlist entry: an https origin or a bare private-use scheme, never a URL prefix +// (ADR-0774). + +#include "merovingian/core/Error.hpp" +#include "merovingian/oauth/HandOffAllowlist.hpp" + +#include +#include + +#include +#include + +SCENARIO("an https origin or a bare private-use scheme is a valid hand-off allowlist entry", "[oauth][allowlist]") +{ + GIVEN("an entry of one of the two shapes") + { + auto const entry = + GENERATE(as{}, "https://app.example.com", "https://app.example.com:8443", "https://localhost", + "https://[::1]:8443", "io.element.app:", "com.example.app-x+y:"); + + WHEN("it is checked") + { + auto const error = merovingian::oauth::hand_off_allowlist_entry_error(entry); + + THEN("it is accepted") + { + INFO(entry); + REQUIRE_FALSE(error.has_value()); + } + } + } +} + +SCENARIO("a hand-off allowlist entry that is a prefix, a path or another shape is refused", "[oauth][allowlist]") +{ + GIVEN("an entry that is not an https origin or a bare private-use scheme") + { + auto const entry = + GENERATE(as{}, + // A URL prefix: a prefix match would accept https://app.example.com.evil.example. + "https://app.example.com/", "https://app.example.com/callback", "https://app.example.com?x=1", + // Not https, or no scheme at all. + "http://app.example.com", "app.example.com", "//app.example.com", + // Default port written out, upper case, userinfo, fragment. + "https://app.example.com:443", "https://App.example.com", + "IO.element.app:", "https://user@app.example.com", "https://app.example.com#x", + // A scheme with a general meaning, or a scheme with more than its colon. + "https:", "http:", "javascript:", "data:", "io.element.app:/callback", "io.element.app:x", + "io.element.app://host", + // Not a URI. + "", " https://app.example.com", "https://app example.com"); + + WHEN("it is checked") + { + auto const error = merovingian::oauth::hand_off_allowlist_entry_error(entry); + + THEN("it is refused with fixed text that does not quote the entry") + { + INFO(entry); + REQUIRE(error.has_value()); + CHECK(error->message().find("example.com") == std::string::npos); + } + } + } +} + +SCENARIO("a hand-off allowlist is bounded and holds each entry once", "[oauth][allowlist]") +{ + GIVEN("allowlists of various sizes") + { + auto list_of = [](int count) { + auto out = std::vector{}; + for (auto index = 0; index < count; ++index) + { + out.push_back("https://h" + std::to_string(index) + ".example.com"); + } + return out; + }; + + WHEN("an empty list is checked") + { + THEN("it is accepted") + { + REQUIRE_FALSE(merovingian::oauth::hand_off_allowlist_error(std::vector{}).has_value()); + } + } + + WHEN("a list of exactly 32 entries is checked") + { + auto const list = list_of(32); + + THEN("it is accepted") + { + REQUIRE_FALSE(merovingian::oauth::hand_off_allowlist_error(list).has_value()); + } + } + + WHEN("a list of 33 entries is checked") + { + auto const list = list_of(33); + + THEN("it is refused") + { + REQUIRE(merovingian::oauth::hand_off_allowlist_error(list).has_value()); + } + } + + WHEN("a list names the same entry twice") + { + auto const list = std::vector{"io.element.app:", "https://a.example.com", "io.element.app:"}; + + THEN("it is refused") + { + REQUIRE(merovingian::oauth::hand_off_allowlist_error(list).has_value()); + } + } + + WHEN("a list holds one invalid entry among valid ones") + { + auto const list = std::vector{"https://a.example.com", "https://b.example.com/"}; + + THEN("it is refused") + { + REQUIRE(merovingian::oauth::hand_off_allowlist_error(list).has_value()); + } + } + } +} diff --git a/tests/unit/test_oauth_server_metadata.cpp b/tests/unit/test_oauth_server_metadata.cpp new file mode 100644 index 000000000..bd05f2c1a --- /dev/null +++ b/tests/unit/test_oauth_server_metadata.cpp @@ -0,0 +1,279 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// OAuthBaseUrl, the one builder of every absolute OAuth address, and server_metadata, the auth_metadata document +// (ADR-0773; spec "Server metadata discovery"). + +#include "merovingian/canonicaljson/ObjectMember.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/core/Error.hpp" +#include "merovingian/core/ErrorCode.hpp" +#include "merovingian/oauth/OAuthBaseUrl.hpp" +#include "merovingian/oauth/OAuthPaths.hpp" +#include "merovingian/oauth/ServerMetadata.hpp" +#include "merovingian/oauth/ServerMetadataOptions.hpp" + +#include +#include + +#include +#include +#include +#include + +namespace +{ + +using merovingian::canonicaljson::Object; +using merovingian::canonicaljson::Value; +using merovingian::oauth::OAuthBaseUrl; + +[[nodiscard]] auto read_base(std::string_view text) -> OAuthBaseUrl +{ + auto result = OAuthBaseUrl::read(text); + REQUIRE(std::holds_alternative(result)); + return std::get(std::move(result)); +} + +[[nodiscard]] auto as_object(Value const& value) -> Object const& +{ + auto const* object = std::get_if(&value.storage()); + REQUIRE(object != nullptr); + return *object; +} + +[[nodiscard]] auto member(Object const& object, std::string_view key) -> Value const* +{ + for (auto const& entry : object) + { + if (entry.key == key) + { + return entry.value.get(); + } + } + return nullptr; +} + +[[nodiscard]] auto text(Object const& object, std::string_view key) -> std::string +{ + auto const* value = member(object, key); + REQUIRE(value != nullptr); + auto const* string = std::get_if(&value->storage()); + REQUIRE(string != nullptr); + return *string; +} + +[[nodiscard]] auto texts(Object const& object, std::string_view key) -> std::vector +{ + auto const* value = member(object, key); + REQUIRE(value != nullptr); + auto const* array = std::get_if(&value->storage()); + REQUIRE(array != nullptr); + auto out = std::vector{}; + for (auto const& item : *array) + { + auto const* string = std::get_if(&item.storage()); + REQUIRE(string != nullptr); + out.push_back(*string); + } + return out; +} + +} // namespace + +SCENARIO("the OAuth paths are the documented constants", "[oauth][urls]") +{ + GIVEN("the path constants") + { + WHEN("they are read") + { + THEN("each names its route under /_merovingian/") + { + CHECK(merovingian::oauth::register_path.view() == "/_merovingian/oauth2/register"); + CHECK(merovingian::oauth::authorize_path.view() == "/_merovingian/oauth2/authorize"); + CHECK(merovingian::oauth::token_path.view() == "/_merovingian/oauth2/token"); + CHECK(merovingian::oauth::revoke_path.view() == "/_merovingian/oauth2/revoke"); + CHECK(merovingian::oauth::device_path.view() == "/_merovingian/oauth2/device"); + CHECK(merovingian::oauth::link_path.view() == "/_merovingian/oauth2/link"); + CHECK(merovingian::oauth::account_path.view() == "/_merovingian/account"); + CHECK(merovingian::oauth::auth_metadata_path == "/_matrix/client/v1/auth_metadata"); + CHECK(merovingian::oauth::auth_metadata_unstable_path == + "/_matrix/client/unstable/org.matrix.msc2965/auth_metadata"); + } + } + } +} + +SCENARIO("the issuer is the base URL with exactly one trailing slash", "[oauth][urls]") +{ + GIVEN("base URLs with and without a path and trailing slashes") + { + struct Case final + { + std::string_view base; + std::string_view issuer; + std::string_view token; + }; + auto const sample = GENERATE(Case{"https://matrix.example.org", "https://matrix.example.org/", + "https://matrix.example.org/_merovingian/oauth2/token"}, + Case{"https://matrix.example.org/", "https://matrix.example.org/", + "https://matrix.example.org/_merovingian/oauth2/token"}, + Case{"https://matrix.example.org//", "https://matrix.example.org/", + "https://matrix.example.org/_merovingian/oauth2/token"}, + Case{"https://example.org/matrix", "https://example.org/matrix/", + "https://example.org/matrix/_merovingian/oauth2/token"}, + Case{"https://example.org/matrix/", "https://example.org/matrix/", + "https://example.org/matrix/_merovingian/oauth2/token"}, + Case{"https://example.org:8448/a/b/", "https://example.org:8448/a/b/", + "https://example.org:8448/a/b/_merovingian/oauth2/token"}); + + WHEN("the base URL is read and its addresses are built") + { + auto const base = read_base(sample.base); + + THEN("the issuer ends in one slash and each endpoint is the base without its slashes plus the path") + { + INFO(sample.base); + CHECK(base.issuer() == sample.issuer); + CHECK(base.url(merovingian::oauth::token_path) == sample.token); + CHECK(base.uri().text() == sample.base); + } + } + } +} + +SCENARIO("a base URL that is not an https URL with a host and no query is refused", "[oauth][urls]") +{ + GIVEN("a base URL that breaks a rule") + { + auto const text = GENERATE(as{}, "", "http://matrix.example.org", "HTTPS://matrix.example.org", + "https:matrix.example.org", "https://", "https://matrix.example.org/?a=b", + "https://matrix.example.org?", "https://matrix.example.org/#top", + "https://user@matrix.example.org", "https://matrix example.org", + "https://matrix.example.org/a\tb"); + + WHEN("it is read") + { + auto const result = OAuthBaseUrl::read(text); + + THEN("it is refused with fixed text that does not quote the input") + { + INFO(text); + auto const* error = std::get_if(&result); + REQUIRE(error != nullptr); + CHECK(error->code() != merovingian::core::ErrorCode::none); + CHECK(error->message().find("matrix") == std::string::npos); + } + } + } + + GIVEN("a base URL longer than the reader's 2048-byte cap") + { + auto const text = "https://matrix.example.org/" + std::string(2048U, 'a'); + + WHEN("it is read") + { + auto const result = OAuthBaseUrl::read(text); + + THEN("it is refused as too long") + { + auto const* error = std::get_if(&result); + REQUIRE(error != nullptr); + CHECK(error->code() == merovingian::core::ErrorCode::invalid_argument); + } + } + } +} + +SCENARIO("the server metadata holds the required fields, every address built from the base URL", + "[oauth][server_metadata]") +{ + GIVEN("a base URL with a path and the default options") + { + auto const base = read_base("https://example.org/matrix/"); + + WHEN("the metadata is built") + { + auto const value = merovingian::oauth::server_metadata(base, {}); + auto const& object = as_object(value); + + THEN("each required field is present with the address or list the spec asks for") + { + CHECK(text(object, "issuer") == "https://example.org/matrix/"); + CHECK(text(object, "authorization_endpoint") == + "https://example.org/matrix/_merovingian/oauth2/authorize"); + CHECK(text(object, "token_endpoint") == "https://example.org/matrix/_merovingian/oauth2/token"); + CHECK(text(object, "registration_endpoint") == + "https://example.org/matrix/_merovingian/oauth2/register"); + CHECK(text(object, "revocation_endpoint") == "https://example.org/matrix/_merovingian/oauth2/revoke"); + CHECK(texts(object, "response_types_supported") == std::vector{"code"}); + CHECK(texts(object, "response_modes_supported") == std::vector{"query", "fragment"}); + CHECK(texts(object, "grant_types_supported") == + std::vector{"authorization_code", "refresh_token"}); + CHECK(texts(object, "code_challenge_methods_supported") == std::vector{"S256"}); + } + + THEN("nothing optional is advertised") + { + CHECK(member(object, "device_authorization_endpoint") == nullptr); + CHECK(member(object, "prompt_values_supported") == nullptr); + CHECK(member(object, "account_management_uri") == nullptr); + CHECK(member(object, "account_management_actions_supported") == nullptr); + CHECK(object.size() == 9U); + } + } + } +} + +SCENARIO("the server metadata follows its options", "[oauth][server_metadata]") +{ + GIVEN("a base URL without a path") + { + auto const base = read_base("https://matrix.example.org"); + + WHEN("the device grant is enabled") + { + auto options = merovingian::oauth::ServerMetadataOptions{}; + options.device_grant_enabled = true; + auto const value = merovingian::oauth::server_metadata(base, options); + auto const& object = as_object(value); + + THEN("the device code grant type and the device authorization endpoint are advertised") + { + CHECK(texts(object, "grant_types_supported") == + std::vector{"authorization_code", "refresh_token", + "urn:ietf:params:oauth:grant-type:device_code"}); + CHECK(text(object, "device_authorization_endpoint") == + "https://matrix.example.org/_merovingian/oauth2/device"); + } + } + + WHEN("registration is enabled") + { + auto options = merovingian::oauth::ServerMetadataOptions{}; + options.registration_enabled = true; + auto const value = merovingian::oauth::server_metadata(base, options); + auto const& object = as_object(value); + + THEN("prompt_values_supported holds create alone") + { + CHECK(texts(object, "prompt_values_supported") == std::vector{"create"}); + } + } + + WHEN("account management actions are given") + { + auto options = merovingian::oauth::ServerMetadataOptions{}; + options.account_management_actions = {"org.matrix.profile", "org.matrix.devices_list"}; + auto const value = merovingian::oauth::server_metadata(base, options); + auto const& object = as_object(value); + + THEN("the account page and the actions are advertised in order") + { + CHECK(text(object, "account_management_uri") == "https://matrix.example.org/_merovingian/account"); + CHECK(texts(object, "account_management_actions_supported") == + std::vector{"org.matrix.profile", "org.matrix.devices_list"}); + } + } + } +} From a8d55c5933870fbcdf65be53c6908e80578ecad9 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 01:33:01 +0000 Subject: [PATCH 09/42] Run the form, cookie and OAuth fuzz targets from the fuzz runner The five targets added in phase 1 were registered in tests/fuzz/meson.build but missing from scripts/run-fuzz-targets.sh, so the fuzz job never ran them and tests/tooling/test_fuzz_targets.py failed. Co-Authored-By: Claude Fable 5.2 --- scripts/run-fuzz-targets.sh | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/scripts/run-fuzz-targets.sh b/scripts/run-fuzz-targets.sh index 231804b83..8c6a6da89 100644 --- a/scripts/run-fuzz-targets.sh +++ b/scripts/run-fuzz-targets.sh @@ -156,5 +156,10 @@ run_target fuzz-inbound-pdu "$builddir/tests/fuzz/fuzz-inbound-pdu" run_target fuzz-ipc-frame "$builddir/tests/fuzz/fuzz-ipc-frame" run_target fuzz-appservice-yaml "$builddir/tests/fuzz/fuzz-appservice-yaml" run_target fuzz-push-glob "$builddir/tests/fuzz/fuzz-push-glob" +run_target fuzz-form-fields "$builddir/tests/fuzz/fuzz-form-fields" +run_target fuzz-request-cookies "$builddir/tests/fuzz/fuzz-request-cookies" +run_target fuzz-oauth-scope "$builddir/tests/fuzz/fuzz-oauth-scope" +run_target fuzz-oauth-redirect-uri "$builddir/tests/fuzz/fuzz-oauth-redirect-uri" +run_target fuzz-oauth-client-metadata "$builddir/tests/fuzz/fuzz-oauth-client-metadata" printf 'All fuzz targets completed cleanly.\n' From d27963fb7cff1c34040fce237ec97fbff6b5dc59 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 02:40:37 +0000 Subject: [PATCH 10/42] Add migration 002 with the OAuth 2.0 client and session tables (ADR-0776 to ADR-0778) Phase 3 of the OAuth 2.0 API: oauth_clients and oauth_sessions on SQLite and PostgreSQL, hydrated at start-up, with the schema registry split by version so a fresh and a migrated 1.0.x database reach the same schema by the same path. delete_device removes a device's session row in its own transaction, the retention sweep deletes sessionless clients unused for 30 days, and merovingian-db-migrate --migrations plans only the files between its versions. Co-Authored-By: Claude Opus 5.5 --- .../references/module-invariants.md | 4 + CHANGELOG.md | 10 +- ...vice-and-the-token-tables-do-not-change.md | 71 +++ ...-last-use-is-written-at-most-once-a-day.md | 65 +++ ...gration-step-from-what-its-version-adds.md | 72 +++ docs/adr/index.md | 3 + docs/auth-identity.md | 15 + docs/database-persistence.md | 58 +- docs/release-process.md | 5 +- docs/security-coding-rules.md | 8 + docs/user-manual.md | 16 +- include/merovingian/database/Migration.hpp | 3 + .../database/OAuthClientStoreResult.hpp | 17 + include/merovingian/database/OAuthStore.hpp | 92 +++ include/merovingian/database/OAuthTables.hpp | 102 ++++ .../database/PersistentOAuthClient.hpp | 23 + .../database/PersistentOAuthSession.hpp | 23 + .../merovingian/database/PersistentStore.hpp | 15 +- include/merovingian/database/Schema.hpp | 11 +- .../merovingian/homeserver/RetentionSweep.hpp | 14 +- migrations/002_oauth_tables.sql | 7 + migrations/AGENTS.md | 28 +- src/database/AGENTS.md | 20 +- src/database/Migration.cpp | 96 ++-- src/database/MigrationFiles.cpp | 20 +- src/database/OAuthStore.cpp | 221 ++++++++ src/database/OAuthTables.cpp | 204 +++++++ src/database/PersistentStore.cpp | 24 +- src/database/PostgresqlStore.cpp | 38 ++ src/database/Schema.cpp | 232 +++++--- src/database/SqliteStore.cpp | 14 + src/database/meson.build | 2 + src/homeserver/AGENTS.md | 2 +- src/homeserver/RetentionSweep.cpp | 58 +- .../test_database_upgrade_flow.cpp | 168 +++++- .../test_persistent_homeserver_flow.cpp | 17 +- .../test_postgresql_store_behaviour_flow.cpp | 67 +++ .../integration/test_retention_sweep_flow.cpp | 172 +++++- tests/meson.build | 1 + tests/smoke/meson.build | 23 + tests/unit/test_database_oauth_store.cpp | 530 ++++++++++++++++++ tests/unit/test_database_persistence.cpp | 194 +++++-- tests/unit/test_worker_table_load_profile.cpp | 6 + 43 files changed, 2534 insertions(+), 237 deletions(-) create mode 100644 docs/adr/0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md create mode 100644 docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md create mode 100644 docs/adr/0778-the-schema-is-built-from-per-version-tables-and-each-migration-step-from-what-its-version-adds.md create mode 100644 include/merovingian/database/OAuthClientStoreResult.hpp create mode 100644 include/merovingian/database/OAuthStore.hpp create mode 100644 include/merovingian/database/OAuthTables.hpp create mode 100644 include/merovingian/database/PersistentOAuthClient.hpp create mode 100644 include/merovingian/database/PersistentOAuthSession.hpp create mode 100644 migrations/002_oauth_tables.sql create mode 100644 src/database/OAuthStore.cpp create mode 100644 src/database/OAuthTables.cpp create mode 100644 tests/unit/test_database_oauth_store.cpp diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index 4616cde39..a472753b8 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -105,6 +105,8 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that - Reads go by index, never scan. `PersistentStore` mutexes follow ADR-0517. A member added to `PersistentStore` is added to every hand-written copy, move and serialise path too. - Schema changes go only through `migrations/` (ADR-0224). Nothing but SQLite opens an SQLite file (ADR-0157). +- A path that deletes a `devices` row deletes its `oauth_sessions` row in the same transaction, and no path deletes + an OAuth client that has a session (ADR-0776, ADR-0777). `src/database/AGENTS.md#OAuth 2.0 tables (migration 002, ADR-0776, ADR-0777)` ## src/email @@ -307,6 +309,8 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that - Never edit an applied migration. `001_initial_schema.sql` is frozen (ADR-0224). A change is a new numbered file, plus its step in `upgrade_migration_catalog()` and its downgrade. `migrations/AGENTS.md#Safety rules` +- A migration's tables go in their own per-version arrays in `Schema.cpp`, never into an earlier version's; the file + equals the generated step (ADR-0778). `migrations/AGENTS.md#Migration 002: the OAuth 2.0 tables (1.1.0, ADR-0776, ADR-0778)` - Next number is the maximum plus one, contiguous. Check that parallel branches have not taken it. Format and header follow `#File format`. - Every new table is classified for the federation worker. `#Federation worker classification` diff --git a/CHANGELOG.md b/CHANGELOG.md index 2fa78d260..58782b726 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,10 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) (https origins or bare private-use schemes, never prefixes) are parsed and checked; all need a restart (ADR-0774). * With OAuth on, `server.public_baseurl` must be an https URL with a host and no query, and `server.sso.authorization_url` is refused. +* Migration 002 adds the `oauth_clients` and `oauth_sessions` tables, hydrated on both backends; deleting a device + deletes its OAuth session in the same transaction (ADR-0776, ADR-0778). +* The retention sweep deletes OAuth clients with no session unused for 30 days, never one with a session, and a + client's last use is written at most once a day (ADR-0777). ## Security Fixes @@ -33,12 +37,16 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * A handler's `Content-Type` spelled in another letter case no longer adds a second `Content-Type` to the response, and 302, 303, 409, 504 and other statuses now carry their reason phrase instead of `OK`. +* `merovingian-db-migrate --plan 1 2 --migrations` now plans only the files between the two versions, instead of + every file in the directory. ## Release notes 1.1.0 is in development. A configuration that sets any `server.oidc.*` key is now refused at start-up: remove those keys and set `server.oauth.enabled` instead (ADR-0764). The metadata names the authorisation, token, registration and -revocation endpoints, which later 1.1.0 changes serve; leave `server.oauth.enabled` off until then. +revocation endpoints, which later 1.1.0 changes serve; leave `server.oauth.enabled` off until then. 1.1.0 migrates +the database: on first start it applies migration 002, which adds two empty tables and changes no existing one. A +1.0.x server refuses the migrated database, so back it up before upgrading if you may need to go back. # Version 1.0.2 diff --git a/docs/adr/0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md b/docs/adr/0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md new file mode 100644 index 000000000..7e39dcb4a --- /dev/null +++ b/docs/adr/0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md @@ -0,0 +1,71 @@ +# An OAuth session is a row keyed by user and device, and the token tables do not change + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 3 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), proposal P3 + +## Context and Problem Statement + +The OAuth 2.0 API needs to know which devices were created by an OAuth grant, with which client and which scope, so +that the token endpoint can refuse a legacy refresh token for an OAuth device (and the reverse), the revocation +endpoint can end the session, and retention can tell a client with a session from one without. Where is that fact +stored? + +## Decision Drivers + +* The v1 tables are frozen since 1.0.0 (ADR-0224): a schema change is a new migration, and an `ALTER TABLE` on a + frozen table changes the shape 1.0.x wrote. +* Some inserts into `access_tokens` and `refresh_tokens` are positional (`INSERT INTO access_tokens VALUES (...)`), so a + new column on those tables would change every one of them. +* A device is an OAuth device or it is not. Every token of the device shares that fact, so it belongs to the device, + not to each token. +* The spec forbids deleting a client registration that has an active session, so the store must answer "does this + client have a session" without scanning tokens. + +## Considered Options + +* A new `oauth_sessions` table keyed by (`user_id`, `device_id`), with `client_id`, `scope` and `created_at_ms`. +* A `client_id` (and scope) column on `access_tokens` and `refresh_tokens`. +* A column on `devices`. + +## Decision Outcome + +Chosen option: the `oauth_sessions` table, created by migration 002 together with `oauth_clients` and an index on +`oauth_sessions (client_id)`. The token tables are not changed. The row is written by the caller's own transaction +(`prepare_oauth_session_insert`, then `commit_persistent_transaction` with the device and token inserts, then +`remember_oauth_session`), and `delete_device` deletes it in the transaction that deletes the device, so the two +cannot disagree. Neither table has a foreign key: no table of the v1 schema declares one, and `delete_device` +already removes every dependent row explicitly in one transaction. + +### Positive Consequences + +* No frozen table changes shape; a 1.0.x database gains two empty tables and nothing else. +* "Is this an OAuth device" and "does this client have a session" are one hash lookup each in memory. +* Every path that deletes a device removes the session row with it, because every one goes through `delete_device`. + +### Negative Consequences + +* A new path that deletes a `devices` row without `delete_device` would leave a session row behind. The rule is + written in `src/database/AGENTS.md`. + +## Pros and Cons of the Options + +### A column on the token tables + +* Good, because a token lookup would carry the client at once. +* Bad, because it is an `ALTER TABLE` on frozen v1 tables and changes every positional insert. +* Bad, because a device's tokens would each repeat the same fact, and a refresh rotation could split them. +* Bad, because "does the client have a session" would scan tokens. + +### A column on `devices` + +* Good, because the fact sits on the device. +* Bad, because it is still an `ALTER TABLE` on a frozen table, and `insert_device` is positional. + +## Links + +* Builds on [ADR-0224](0224-pre-1-0-migrations-collapse-into-one-frozen-v1-schema.md) +* Related to [ADR-0777](0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md) and + [ADR-0778](0778-the-schema-is-built-from-per-version-tables-and-each-migration-step-from-what-its-version-adds.md) diff --git a/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md b/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md new file mode 100644 index 000000000..0557ab77a --- /dev/null +++ b/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md @@ -0,0 +1,65 @@ +# An OAuth client's last use is written at most once a day + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 3 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), the `oauth_clients` retention rule + +## Context and Problem Statement + +The retention sweep deletes a client registration that has no session and has not been used for 30 days, and +phase 4 caps the number of registrations by evicting the least recently used client without a session. Both need +`last_used_at_ms`. A client is "used" on every authorisation request and every token request, so writing the +timestamp each time would add a database transaction to every refresh of every OAuth device. How precise must the +stored value be, and how are the eligible clients found? + +## Decision Drivers + +* Retention works in days; an error of up to a day in a 30-day window changes nothing that matters. +* A refresh must not cost a write it does not need. +* The sweep and the cap run under `runtime.mutex`, so finding the eligible clients must cost the clients it returns, + not every client or every session. + +## Considered Options + +* Write `last_used_at_ms` only when the stored value is more than 24 hours old (`touch_oauth_client`). +* Write it on every use. +* Keep it in memory only and write it at shutdown. + +## Decision Outcome + +Chosen option: write at most once a day. `touch_oauth_client` writes nothing when `now` is at or before the stored +value (a clock that stepped back) or within `oauth_client_touch_interval_ms` (24 hours) of it, and otherwise one +`UPDATE` of that row. The in-memory `OAuthTables` keeps the clients that have no session in an ordered set of +(`last_used_at_ms`, `client_id`), maintained by every insert, touch, delete and session change, so +`oauth_clients_without_sessions` walks only the oldest sessionless clients and never reads the session table. A +client with a session is never in that set, and `delete_oauth_clients` refuses one, so neither the sweep nor the cap +can delete it (the spec: "The server MUST NOT delete client registrations that have an active session"). The sweep +asks `oauth_client_has_pending_authorisation` too; it is false until phase 5 keeps pending authorisations. + +### Positive Consequences + +* A busy client costs at most one write a day, whatever its number of refreshes. +* The sweep's cost under the lock is the rows it deletes, counted by `OAuthTables::rows_examined()`. + +### Negative Consequences + +* A client used once, then idle, is deleted up to a day later than an exact clock would say. Accepted. + +## Pros and Cons of the Options + +### Write on every use + +* Good, because the stored value is exact. +* Bad, because every token request becomes a write, under `runtime.mutex`, for a precision retention does not use. + +### Memory only, written at shutdown + +* Good, because no request writes. +* Bad, because a crash loses every use since start, and a client in use could then be deleted as idle. + +## Links + +* Related to [ADR-0776](0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md) +* Follows the batch discipline of [ADR-0488](0488-sessions-are-found-through-a-digest-index-and-unusable-credentials-are-deleted.md) diff --git a/docs/adr/0778-the-schema-is-built-from-per-version-tables-and-each-migration-step-from-what-its-version-adds.md b/docs/adr/0778-the-schema-is-built-from-per-version-tables-and-each-migration-step-from-what-its-version-adds.md new file mode 100644 index 000000000..3f2d56722 --- /dev/null +++ b/docs/adr/0778-the-schema-is-built-from-per-version-tables-and-each-migration-step-from-what-its-version-adds.md @@ -0,0 +1,72 @@ +# The schema is built from per-version tables, and each migration step from what its version adds + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 3 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), migration 002, the first after the +frozen v1 schema + +## Context and Problem Statement + +Until 1.1.0 the whole schema was one step, so `Schema.cpp` held one list of tables and indexes and the v1 step, the +bootstraps and the compatibility check all read it. Migration 002 adds two tables. The bootstraps must keep building +exactly what 1.0.x built, so that a fresh database and a 1.0.x database reach the current version by the same path, +while the compatibility check and the DDL allowlist must know every current table. How are "what v1 has" and "what +the current schema has" kept apart without copying table definitions? + +## Decision Drivers + +* v1 must never change (ADR-0224); `migrations/001_initial_schema.sql` is compared to the build's v1 step. +* A fresh database must end with exactly the schema a migrated one does. +* A table's DDL must be written once. + +## Considered Options + +* Per-version arrays in `Schema.cpp` (`core_tables`/`core_indexes` for v1, `oauth_tables`/`oauth_indexes` for v2), + `schema_definitions_added_by(version)` and `schema_indexes_added_by(version)`, with the initial lists being version + 1 and the current lists the concatenation of versions 1 to `current_schema_version()`. +* Have the bootstraps build the current schema and record every ledger row at once. +* Write migration 002's DDL by hand in `Migration.cpp`. + +## Decision Outcome + +Chosen option: per-version arrays. A migration step is generated from what its version adds +(`schema_step_creating`: CREATE TABLE for each table, then CREATE INDEX for each index; `schema_step_dropping`: DROP +TABLE in reverse order, to the version before). The bootstraps build only version 1 and write ledger row 1, and +`apply_pending_migrations` then runs 002 on a fresh and a migrated database alike. Every table of every version is +allowlisted for DDL (`schema_table_is_core`, `index_is_registered`). `merovingian-db-migrate --migrations` now plans +only the files between its two versions, so `--plan 1 2` takes 002 alone. + +A later migration adds its own arrays and a case in `schema_definitions_added_by` / `schema_indexes_added_by`, a +`migrations/00N_*.sql` file equal to its generated step, and raises `schema_version`. It never edits an earlier +version's array. + +### Positive Consequences + +* A fresh database and a 1.0.x one take the same path to the current schema; the upgrade tests compare the two. +* Each table's DDL is in one place and the migration file is checked against it statement for statement. + +### Negative Consequences + +* A migration that changes an existing table (rather than adding one) cannot be expressed as "what its version adds" + and needs hand-written statements in its step; none exists yet. + +## Pros and Cons of the Options + +### Bootstrap the current schema directly + +* Good, because a fresh database needs no migration run. +* Bad, because a fresh database and an upgraded one then take different paths, and a difference between them would + go unnoticed. + +### Hand-written DDL for 002 + +* Good, because it is explicit. +* Bad, because each table's DDL would live twice, and the DDL allowlist would not know the new tables. + +## Links + +* Builds on [ADR-0224](0224-pre-1-0-migrations-collapse-into-one-frozen-v1-schema.md) and + [ADR-0216](0216-upgrade-path-is-tested-from-a-forward-only-seam-and-a-real-previous-release-fixture.md) +* Related to [ADR-0776](0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 3f4ef45d5..01031ad36 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -657,3 +657,6 @@ * [0773 - The OAuth issuer is `server.public_baseurl`, and the routes live under `/_merovingian/`](0773-the-oauth-issuer-is-public-baseurl-and-the-routes-live-under-merovingian.md) * [0774 - A hand-off allowlist entry is an https origin or a bare private-use scheme, never a prefix](0774-a-hand-off-allowlist-entry-is-an-https-origin-or-a-bare-private-use-scheme-never-a-prefix.md) * [0775 - `auth_metadata` stays in the generic rate-limit tier](0775-auth-metadata-stays-in-the-generic-rate-limit-tier.md) +* [0776 - An OAuth session is a row keyed by user and device, and the token tables do not change](0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md) +* [0777 - An OAuth client's last use is written at most once a day](0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md) +* [0778 - The schema is built from per-version tables, and each migration step from what its version adds](0778-the-schema-is-built-from-per-version-tables-and-each-migration-step-from-what-its-version-adds.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index abbfea89b..7879e134c 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -1062,6 +1062,21 @@ The built-in OAuth 2.0 API ([ADR-0760](adr/0760-the-oauth-2-0-api-is-built-into- headers every page carries ([ADR-0772](adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md)). +## OAuth 2.0 storage (migration 002) + +1.1.0 adds two tables (ADR-0776, ADR-0777, ADR-0778); nothing serves them yet, and the token tables are unchanged. + +- `oauth_clients`: one row per registered client, its canonical metadata (at most 16 KiB), when it was registered + and when it was last used. A client row is kept as first written; `last_used_at_ms` is written at most once a day. + The hourly `retention-sweep` deletes a client with no session that has not been used for 30 days, at most 500 per + transaction. A client with a session is never deleted. +- `oauth_sessions`: one row per OAuth device, keyed by (user ID, device ID), naming its client and granted scope (at + most 2048 bytes). A device is an OAuth device exactly when it has a row. The row is written in the transaction that + writes the device and its tokens (phase 6), and deleted in the transaction that deletes the device, which covers + `POST /logout`, `POST /logout/all`, `DELETE /devices/{deviceId}` and `POST /delete_devices`. + +Neither table is read by the federation worker. + ## Next starting points 1. Preserve the reviewed libsodium boundary for random token generation and password hashing as auth flows expand. diff --git a/docs/database-persistence.md b/docs/database-persistence.md index 18bcdf8ae..b8bc79bbd 100644 --- a/docs/database-persistence.md +++ b/docs/database-persistence.md @@ -25,9 +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 is a single step, version `1` (`initial_schema`): - `schema::current_schema_version()` is `1`, and `migrations/` holds only - `001_initial_schema.sql`. Every pre-1.0 migration (versions 2 to 26 as of +- The schema has two steps. `schema::current_schema_version()` is `2`, and + `migrations/` holds `001_initial_schema.sql` and `002_oauth_tables.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)), so v1 creates all 64 tables in their final shape, every column that an @@ -42,11 +42,42 @@ 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 exactly one upgrade step (version `1`, - `initial_schema`) and one downgrade step (to version `0`, - `drop_initial_schema`, which drops every table). - `migrations/001_initial_schema.sql` is the frozen record of v1; a unit test - requires it to match the build's v1 step statement for statement. + `src/database/Migration.cpp` has two upgrade steps (version `1`, + `initial_schema`; version `2`, `oauth_tables`) and two downgrade steps, newest + first (`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 and + `002_oauth_tables.sql` of version 2; 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)), + and changes no existing table: + - `oauth_clients` (`client_id TEXT PRIMARY KEY`, `metadata_json`, + `created_at_ms`, `last_used_at_ms`, all `TEXT NOT NULL`, the integers + written as decimal text like every other `*_ms` column). A row is kept as + first written (`store_oauth_client` answers `existing`); only + `last_used_at_ms` changes, at most once a day (`touch_oauth_client`, + [ADR-0777](adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md)). + The metadata is refused over 16 KiB and the ID over 128 bytes. + - `oauth_sessions` (`user_id`, `device_id`, `client_id`, `scope`, + `created_at_ms`, primary key `(user_id, device_id)`), with + `idx_oauth_sessions_client_id`. The scope is refused over 2048 bytes. A + session row is written in the caller's transaction + (`prepare_oauth_session_insert`, then `remember_oauth_session` after the + commit) and deleted by `delete_device` in the transaction that deletes the + device. No foreign keys: no v1 table declares one, and the deleting + transaction removes dependent rows explicitly. + - In memory: `PersistentStore::oauth` (`OAuthTables`), hydrated on both + backends, with sessions by (user, device), a per-user index, a session + count per client and the sessionless clients ordered by last use, which the + retention sweep reads (30 days, never a client with a session). +- 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 + PostgreSQL bootstraps build exactly that and write ledger row 1; every later + step then runs through `apply_pending_migrations`, so a fresh database and an + upgraded 1.0.x database reach the same schema by the same path. + `current_schema_definitions()` is every version up to the current one. - Schema change policy. Before `v1.0.0` there was nothing to upgrade from: a database whose `schema_migrations` ledger holds an upgrade row this build does not have (for example the rows 2 to 26 written by every build up to 0.12.46) @@ -199,8 +230,10 @@ value. Test fixtures that do not exercise persistence select it through - `delete_federation_transactions` removes a list of queued transactions in one database transaction; the dispatch worker uses it to drop what a failing destination holds past its share or its age (ADR-0621). - Physical migration-file loading for SQL files with explicit metadata and - statement names; the checked-in `migrations/` directory contains only - `001_initial_schema.sql`, the frozen record of the v1 schema. + statement names; the checked-in `migrations/` directory contains + `001_initial_schema.sql`, the frozen record of the v1 schema, and + `002_oauth_tables.sql`. `merovingian-db-migrate --plan A B --migrations DIR` + takes only the files whose version is between A (exclusive) and B. - `sync_stream_watermark` table stores the highest allocated `sync_stream_id` and is updated by `database::allocate_sync_stream_id()` before the ID is used for ephemeral events such as typing notifications and read receipts. This @@ -1173,7 +1206,7 @@ migration's table cannot go unclassified: `event_state_groups`, `forward_extremities` (the last four added in 0.12.13 by ADR-0064 phase A — `state_groups` was vestigial before this and is now moved out of the never-reads list below). -- **Worker never reads** (50 tables): `users`, `devices`, `access_tokens`, +- **Worker never reads** (52 tables): `users`, `devices`, `access_tokens`, `refresh_tokens`, `federation_destinations`, `federation_transactions`, `invites`, `state_transitions`, `sync_stream_watermark`, `event_stream_watermark`, `stream_token_epoch`, `device_keys`, `one_time_keys`, `fallback_keys`, @@ -1184,7 +1217,8 @@ migration's table cannot go unclassified: `presence_state`, `filters`, `profiles`, `account_threepids`, `client_txn_ids`, `pushers`, `notifications`, `openid_tokens`, `login_tokens`, `appservice_txn_cursor`, `appservice_outbox`, `deferred_pdus`, - `receipts`, `appservice_directory`, `media_pending_uploads`, plus six tables `Schema.cpp` + `receipts`, `appservice_directory`, `media_pending_uploads`, `oauth_clients` and `oauth_sessions` (migration + 002; every OAuth 2.0 endpoint runs in main), 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/docs/release-process.md b/docs/release-process.md index ab9befeba..c0c09366c 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -132,8 +132,9 @@ fixture until the 1.1 series starts. Since 1.0.0, the v1 migration (the `initial_schema` step in `src/database/Migration.cpp`) and `migrations/001_initial_schema.sql` never change. A schema change is a new numbered -migration (v2 onwards) that keeps deployed databases compatible. A unit test requires the -SQL file to match the build's v1 step statement for statement. +migration (v2 onwards) that keeps deployed databases compatible; the first is +`002_oauth_tables.sql` in 1.1.0 (ADR-0778). A unit test requires each SQL file to match the +build's step statement for statement. ## Verifying release signatures diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index ce73f8709..caabc3a5e 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -637,6 +637,14 @@ quickly finding everything a given `AGENTS.md` file contributed. Why: a limit one server can fill would let its forks keep out another server's ban or demotion (ADR-0374, ADR-0602). Source: `src/homeserver/AGENTS.md`. +- **A device's OAuth session row is deleted in the transaction that deletes the device, and an OAuth client that has + a session is never deleted.** Every device-deleting path goes through `database::delete_device`; the retention sweep + and any cap choose candidates with `oauth_clients_without_sessions`, and `delete_oauth_clients` refuses a set that + names a client with a session. + Why: a session row that outlives its device would mark a later device of the same ID as an OAuth device, and the + spec forbids deleting a client registration that has an active session (ADR-0776, ADR-0777). + Source: `src/database/AGENTS.md`, `src/homeserver/AGENTS.md`. + - **A change to a stored event's JSON or status forgets the room in `ResolvedStateMemo`, and a memo hit is still applied through the normal write path.** Why: a resolution reads both, and `current_state` has other writers, so a stale or skipped result leaves state a diff --git a/docs/user-manual.md b/docs/user-manual.md index 975230024..ba2fe206e 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -1997,15 +1997,17 @@ and cannot be selected in the config file. `merovingian-db-migrate` plans schema migrations without starting the runtime: ```sh -merovingian-db-migrate --plan 0 1 --migrations migrations/ +merovingian-db-migrate --plan 1 2 --migrations migrations/ ``` -The schema is at version 1 and `migrations/` holds only `001_initial_schema.sql`, -so `--plan 0 1` is the plan that matches it. With `--migrations`, the steps come -from the files, and the plan is rejected (exit 78) unless their versions run -contiguously from ` + 1` to ``; without -`--migrations`, the plan is built from the steps this build carries. A plan to a -version this build does not have, such as `--plan 1 2`, is rejected. +The schema is at version 2 and `migrations/` holds `001_initial_schema.sql` and +`002_oauth_tables.sql` (1.1.0), so `--plan 1 2` is the plan that takes a 1.0.x +database to this release: migration 002 alone. With `--migrations`, the steps come +from the files whose version lies between `` (exclusive) and +``, and the plan is rejected (exit 78) unless they run +contiguously; without `--migrations`, the plan is built from the steps this build +carries. A plan to a version this build does not have, such as `--plan 2 3`, is +rejected. The tool only prints a plan. It takes no database URI or config file, never opens a database, and never changes one: it sets the migration role diff --git a/include/merovingian/database/Migration.hpp b/include/merovingian/database/Migration.hpp index e3ac2b266..7ee8dd851 100644 --- a/include/merovingian/database/Migration.hpp +++ b/include/merovingian/database/Migration.hpp @@ -23,6 +23,9 @@ namespace merovingian::database [[nodiscard]] auto migration_plan_summary(MigrationPlan const& plan) -> std::string; [[nodiscard]] auto initial_schema_migration() -> MigrationStep; [[nodiscard]] auto downgrade_initial_schema_migration() -> MigrationStep; +// Migration 002 (1.1.0): the OAuth 2.0 client and session tables (ADR-0776, ADR-0778). +[[nodiscard]] auto oauth_tables_migration() -> MigrationStep; +[[nodiscard]] auto downgrade_oauth_tables_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/OAuthClientStoreResult.hpp b/include/merovingian/database/OAuthClientStoreResult.hpp new file mode 100644 index 000000000..e77650138 --- /dev/null +++ b/include/merovingian/database/OAuthClientStoreResult.hpp @@ -0,0 +1,17 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +namespace merovingian::database +{ + +// What `store_oauth_client` did. `existing` wrote nothing: the row already held keeps its metadata and its +// `created_at_ms`. `refused` wrote nothing either: the row broke a cap or the transaction did not commit. +enum class OAuthClientStoreResult +{ + inserted, + existing, + refused, +}; + +} // namespace merovingian::database diff --git a/include/merovingian/database/OAuthStore.hpp b/include/merovingian/database/OAuthStore.hpp new file mode 100644 index 000000000..c5400a8b8 --- /dev/null +++ b/include/merovingian/database/OAuthStore.hpp @@ -0,0 +1,92 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/OAuthClientStoreResult.hpp" +#include "merovingian/database/PersistentOAuthClient.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" +#include "merovingian/database/PreparedStatement.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::database +{ + +struct PersistentStore; + +// The OAuth 2.0 tables of migration 002 (ADR-0776, ADR-0777). Every function here reads or writes +// `PersistentStore::oauth` and, for a write, the database in one transaction, changing memory only after the commit: +// a failed commit changes nothing. None takes a lock; in main the caller holds `runtime.mutex`. + +// Caps on what one row holds. A remote client chooses the metadata and the scope, so each is bounded where it is +// stored as well as where it is parsed: an oversized row is refused here, never truncated. +// The canonical client metadata; the registration endpoint's body cap is the same size. +inline constexpr auto max_oauth_client_metadata_bytes = std::size_t{16U} * 1024U; +// A granted scope: the Matrix API scope, one device scope and room for a few more tokens. +inline constexpr auto max_oauth_scope_bytes = std::size_t{2048U}; +// A client ID: this server issues them as a keyed hash in text, far shorter than this (plan P2). +inline constexpr auto max_oauth_client_id_bytes = std::size_t{128U}; +// `last_used_at_ms` is written only when the stored value is more than this old (ADR-0777): clients register again +// before every login, and a write per registration would make every login cost a commit. +inline constexpr auto oauth_client_touch_interval_ms = std::uint64_t{24U} * 60U * 60U * 1000U; + +// Stores a new client. `existing` when its ID is already held, which writes nothing: an existing row's metadata and +// `created_at_ms` never change. `refused` when the ID is empty or longer than `max_oauth_client_id_bytes`, the metadata +// is empty or longer than `max_oauth_client_metadata_bytes`, or the write fails. +[[nodiscard]] auto store_oauth_client(PersistentStore& store, PersistentOAuthClient client) -> OAuthClientStoreResult; +// The client `client_id`, or nullptr. One hash lookup; valid until the next write to the OAuth tables. +[[nodiscard]] auto find_oauth_client(PersistentStore const& store, std::string_view client_id) + -> PersistentOAuthClient const*; +[[nodiscard]] auto oauth_client_count(PersistentStore const& store) -> std::size_t; +// Records that `client_id` was used at `now_ms`, writing only when its stored `last_used_at_ms` is more than +// `oauth_client_touch_interval_ms` older than `now_ms`. True when the client is held and its row is now fresh enough +// (written or not); false when it is not held or the write failed, leaving the row as it was. +[[nodiscard]] auto touch_oauth_client(PersistentStore& store, std::string_view client_id, std::uint64_t now_ms) -> bool; +// Deletes the clients `client_ids` names, all in one transaction. False, deleting nothing, when an ID is not held, +// is repeated, or names a client with a session (never deleted: spec "Client registration"), or the write fails. +[[nodiscard]] auto delete_oauth_clients(PersistentStore& store, std::span client_ids) -> bool; +// The clients with no session, least recently used first, at most `max`, and only those last used before +// `used_before_ms` (pass UINT64_MAX for all). A client `excluded` answers true for (phase 5: a pending authorisation +// names it) is skipped and does not count against `max`. Costs the clients walked, not the session table. +[[nodiscard]] auto oauth_clients_without_sessions(PersistentStore const& store, std::size_t max, + std::uint64_t used_before_ms, + std::function const& excluded = {}) + -> std::vector; + +// The session of (`user_id`, `device_id`), or nullptr. One hash lookup; valid until the next write. +[[nodiscard]] auto find_oauth_session(PersistentStore const& store, std::string_view user_id, + std::string_view device_id) -> PersistentOAuthSession const*; +// Every session of `user_id`, through the per-user index. +[[nodiscard]] auto oauth_sessions_of_user(PersistentStore const& store, std::string_view user_id) + -> std::vector; +[[nodiscard]] auto oauth_client_has_session(PersistentStore const& store, std::string_view client_id) -> bool; + +// The `oauth_sessions` INSERT for a transaction that also writes the device and its tokens (phase 6): append it to +// that transaction's statements, commit, and only then call `remember_oauth_session` with the same row. nullopt when +// the row is refused: an empty user, device or client, a client ID or scope over its cap, a client that is not +// held, or a (user, device) that already holds a session. Reads the store; changes nothing. +[[nodiscard]] auto prepare_oauth_session_insert(PersistentStore const& store, PersistentOAuthSession const& session) + -> std::optional; +// The memory half of `prepare_oauth_session_insert`, after its transaction committed. False when memory already +// holds a session for the device, which cannot happen if nothing wrote between the prepare and the commit. +[[nodiscard]] auto remember_oauth_session(PersistentStore& store, PersistentOAuthSession session) -> bool; +// `prepare_oauth_session_insert`, a transaction of that one statement, then `remember_oauth_session`. +[[nodiscard]] auto store_oauth_session(PersistentStore& store, PersistentOAuthSession session) -> bool; +// Deletes the session of (`user_id`, `device_id`). False when there is none or the write fails. The device stays: +// a device deletion removes its session itself (`delete_device`). +[[nodiscard]] auto delete_oauth_session(PersistentStore& store, std::string_view user_id, std::string_view device_id) + -> bool; + +// The `oauth_sessions` DELETE for one device, which `delete_device` adds to the transaction that deletes the device +// row, so the two never disagree after a commit or a failed one. +[[nodiscard]] auto delete_oauth_session_of_device_statement(std::string_view user_id, std::string_view device_id) + -> PreparedStatement; + +} // namespace merovingian::database diff --git a/include/merovingian/database/OAuthTables.hpp b/include/merovingian/database/OAuthTables.hpp new file mode 100644 index 000000000..109c775ff --- /dev/null +++ b/include/merovingian/database/OAuthTables.hpp @@ -0,0 +1,102 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/ExaminedRows.hpp" +#include "merovingian/database/PersistentOAuthClient.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" +#include "merovingian/database/StateGroupKeyHash.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::database +{ + +// The in-memory copy of `oauth_clients` and `oauth_sessions` (migration 002, ADR-0776, ADR-0777). 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. A client is found by ID and a session by (user, device) with one hash lookup; a user's sessions through a +// per-user index; and the clients that hold no session are kept in an ordered set by `last_used_at_ms`, so "the +// least recently used clients without a session" never walks the session table. 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. The +// defaulted copy and move keep every index valid: the indexes hold keys, never positions or pointers. +class OAuthTables final +{ +public: + // The row for `client_id`, or nullptr. + [[nodiscard]] auto find_client(std::string_view client_id) const -> PersistentOAuthClient const*; + [[nodiscard]] auto client_count() const noexcept -> std::size_t + { + return clients_.size(); + } + // How many sessions name `client_id`, whether or not the client row is held. + [[nodiscard]] auto sessions_of_client(std::string_view client_id) const -> std::size_t; + + // Adds `client`. False, and nothing changes, when its ID is already held. + auto insert_client(PersistentOAuthClient client) -> bool; + // Sets a held client's `last_used_at_ms`. False when `client_id` is not held. + auto set_client_last_used(std::string_view client_id, std::uint64_t last_used_at_ms) -> bool; + // Removes a client. False, and nothing changes, when it is not held or a session names it: a client with a + // session is never deleted (spec, "Client registration": the server "MUST NOT delete client registrations that have + // an active session"). + auto erase_client(std::string_view client_id) -> bool; + + // The held clients no session names, least recently used first (ties by ID), stopping at `max` IDs or at the + // first client used at or after `used_before_ms`. A client `excluded` answers true for is skipped. Costs the + // clients walked, counted in `rows_examined`, never the session table. + [[nodiscard]] auto idle_clients(std::size_t max, std::uint64_t used_before_ms, + std::function const& excluded) const + -> std::vector; + + // The session of (`user_id`, `device_id`), or nullptr. + [[nodiscard]] auto find_session(std::string_view user_id, std::string_view device_id) const + -> PersistentOAuthSession const*; + [[nodiscard]] auto session_count() const noexcept -> std::size_t + { + return sessions_.size(); + } + // Every session of `user_id`, in no particular order. Costs the user's own sessions, counted in + // `rows_examined`. + [[nodiscard]] auto sessions_of_user(std::string_view user_id) const -> std::vector; + + // Adds `session`. False, and nothing changes, when (user, device) already holds one. The client need not be + // held (hydration may load the sessions first); a held client named by it stops being idle. + auto insert_session(PersistentOAuthSession session) -> bool; + // Removes the session of (`user_id`, `device_id`). False when there is none. + auto erase_session(std::string_view user_id, std::string_view device_id) -> bool; + + auto clear() noexcept -> void; + + // Rows every reader above looked at over the table's life, for tests that prove cost. + [[nodiscard]] auto rows_examined() const noexcept -> std::uint64_t + { + return rows_examined_.value(); + } + +private: + template + using KeyedBy = std::unordered_map>; + + // A client is idle while no session names it; `idle_` then holds (last_used_at_ms, client_id). + auto mark_idle(PersistentOAuthClient const& client) -> void; + auto unmark_idle(PersistentOAuthClient const& client) -> void; + + KeyedBy clients_{}; + // (user_id NUL device_id) -> the session. + KeyedBy sessions_{}; + // user_id -> that user's device IDs that hold a session. + KeyedBy>> devices_by_user_{}; + // client_id -> how many sessions name it; absent means none. + KeyedBy sessions_by_client_{}; + std::set> idle_{}; + ExaminedRows rows_examined_{}; +}; + +} // namespace merovingian::database diff --git a/include/merovingian/database/PersistentOAuthClient.hpp b/include/merovingian/database/PersistentOAuthClient.hpp new file mode 100644 index 000000000..5d55252d4 --- /dev/null +++ b/include/merovingian/database/PersistentOAuthClient.hpp @@ -0,0 +1,23 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::database +{ + +// Migration 002: a registered OAuth 2.0 client (`oauth_clients`). `metadata_json` is the accepted client metadata as +// `oauth::ClientMetadata::canonical_bytes` gives it; the row is written once and never changed, except +// `last_used_at_ms`, which `touch_oauth_client` moves at most once a day (ADR-0777). Times are milliseconds since +// the Unix epoch. +struct PersistentOAuthClient final +{ + std::string client_id{}; + std::string metadata_json{}; + std::uint64_t created_at_ms{0U}; + std::uint64_t last_used_at_ms{0U}; +}; + +} // namespace merovingian::database diff --git a/include/merovingian/database/PersistentOAuthSession.hpp b/include/merovingian/database/PersistentOAuthSession.hpp new file mode 100644 index 000000000..f3ffe4c65 --- /dev/null +++ b/include/merovingian/database/PersistentOAuthSession.hpp @@ -0,0 +1,23 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::database +{ + +// Migration 002 (ADR-0776): the device (`user_id`, `device_id`) is an OAuth 2.0 session of `client_id`, granted +// `scope` (`oauth_sessions`). The device's tokens are ordinary `access_tokens` and `refresh_tokens` rows; this row +// is what makes it an OAuth device. It is deleted with the device, in the same transaction. +struct PersistentOAuthSession final +{ + std::string user_id{}; + std::string device_id{}; + std::string client_id{}; + std::string scope{}; + std::uint64_t created_at_ms{0U}; +}; + +} // namespace merovingian::database diff --git a/include/merovingian/database/PersistentStore.hpp b/include/merovingian/database/PersistentStore.hpp index 0f2d35151..532fb244b 100644 --- a/include/merovingian/database/PersistentStore.hpp +++ b/include/merovingian/database/PersistentStore.hpp @@ -6,18 +6,19 @@ #include "merovingian/database/CappedAccountDataStore.hpp" #include "merovingian/database/CredentialTable.hpp" #include "merovingian/database/DeferredPduAwaits.hpp" -#include "merovingian/database/KeyBackupDigest.hpp" #include "merovingian/database/DeferredPduUpsert.hpp" #include "merovingian/database/EventStateGroupTable.hpp" #include "merovingian/database/EventTable.hpp" #include "merovingian/database/ExaminedRows.hpp" #include "merovingian/database/ForwardExtremityTable.hpp" +#include "merovingian/database/KeyBackupDigest.hpp" #include "merovingian/database/MediaBlobRead.hpp" #include "merovingian/database/MembershipProjection.hpp" #include "merovingian/database/MembershipStoreResult.hpp" #include "merovingian/database/MigrationApplyResult.hpp" #include "merovingian/database/MigrationValidationResult.hpp" #include "merovingian/database/MissingEventReferences.hpp" +#include "merovingian/database/OAuthTables.hpp" #include "merovingian/database/PersistentAccessToken.hpp" #include "merovingian/database/PersistentAccountData.hpp" #include "merovingian/database/PersistentAdminAction.hpp" @@ -442,9 +443,9 @@ struct PersistentStore final // Key backup indexes (ADR-0606): a session by (user, version, room, session), the sessions of each (user, // version) and the versions of each user. Same trust rule as above. A deleted session or version erases by // moving the last row into the gap, so `key_backup_sessions` has no meaningful order. - // The digest of each (user, version) backup (run-3 C22, ADR-0673), kept by every writer of `key_backup_sessions` and - // rebuilt after hydration. Trusted only while its count equals the version's session count; a reader that finds it - // stale recomputes from the rows without storing the result. + // The digest of each (user, version) backup (run-3 C22, ADR-0673), kept by every writer of `key_backup_sessions` + // and rebuilt after hydration. Trusted only while its count equals the version's session count; a reader that finds + // it stale recomputes from the rows without storing the result. std::unordered_map key_backup_digests{}; RowKeyIndex key_backup_session_index{}; RowGroupIndex key_backup_version_session_index{}; @@ -565,6 +566,9 @@ struct PersistentStore final // audit log (C26). ExaminedRows audit_type_queries{}; std::vector login_tokens{}; + // Migration 002 (ADR-0776, ADR-0777): `oauth_clients` and `oauth_sessions`, with their indexes. Read and write + // through OAuthStore.hpp; `delete_device` removes a device's session in the transaction that deletes the device. + OAuthTables oauth{}; std::vector appservice_txn_cursors{}; // Events queued for appservices, kept sorted by (appservice_id, stream_ordering). See // PersistentAppserviceOutboxEntry. @@ -1262,8 +1266,7 @@ auto for_each_key_backup_session(PersistentStore const& store, std::string_view // Stores every signature in one transaction (one commit, whatever the count): all are written or, when the write // fails, none is. A row with an empty target key or an empty payload is refused and the rest are still written; the // result is false when any row was refused. An empty list succeeds and writes nothing. Run-3 C14 (ADR-0672). -[[nodiscard]] auto store_key_signatures(PersistentStore& store, std::vector signatures) - -> bool; +[[nodiscard]] auto store_key_signatures(PersistentStore& store, std::vector signatures) -> bool; // Calls `visit` with the (target user, target key) of each signature `signer_user_id` holds; stops when it returns // false. Reads the signer's rows only, counted in `key_rows_examined`. auto for_each_signer_key_signature(PersistentStore const& store, std::string_view signer_user_id, diff --git a/include/merovingian/database/Schema.hpp b/include/merovingian/database/Schema.hpp index 94828e249..d88cc7b86 100644 --- a/include/merovingian/database/Schema.hpp +++ b/include/merovingian/database/Schema.hpp @@ -15,17 +15,26 @@ 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; 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. [[nodiscard]] auto initial_schema_definitions() -> std::vector; +// Every version up to current_schema_version(), in order: what a migrated database holds. [[nodiscard]] auto current_schema_definitions() -> std::vector; [[nodiscard]] auto initial_schema_indexes() -> std::vector; +[[nodiscard]] auto current_schema_indexes() -> std::vector; [[nodiscard]] auto initial_schema_tables() -> std::vector; [[nodiscard]] auto current_schema_tables() -> std::vector; +// A table of the current schema (any version), by name; nullopt for any other name. [[nodiscard]] auto schema_table_definition(std::string_view table_name) noexcept -> std::optional; +// True for a table of the current schema, of whichever version. Only these may appear in generated DDL. [[nodiscard]] auto schema_table_is_core(std::string_view table_name) noexcept -> bool; [[nodiscard]] auto quote_sqlite_identifier(std::string_view identifier) noexcept -> std::optional; [[nodiscard]] auto create_table_sql(SchemaTableDefinition const& table) -> std::optional; -// Refuse (nullopt) any index that is not one of initial_schema_indexes(). +// Refuse (nullopt) any index that is not one of current_schema_indexes(). [[nodiscard]] auto create_index_sql(SchemaIndexDefinition const& index) -> std::optional; [[nodiscard]] auto create_index_if_missing_sql(SchemaIndexDefinition const& index) -> std::optional; diff --git a/include/merovingian/homeserver/RetentionSweep.hpp b/include/merovingian/homeserver/RetentionSweep.hpp index 06e148e9a..c9bcd9b46 100644 --- a/include/merovingian/homeserver/RetentionSweep.hpp +++ b/include/merovingian/homeserver/RetentionSweep.hpp @@ -6,6 +6,7 @@ #include #include +#include namespace merovingian::homeserver { @@ -24,12 +25,23 @@ inline constexpr auto retention_max_batches = std::size_t{20U}; // An access token stays on record this long after it expired, so a request that presents it is still answered // "token expired" in the audit log rather than "session not found". A revoked one goes at once. inline constexpr auto expired_access_token_grace = std::chrono::hours{24 * 7}; +// An OAuth 2.0 client registration with no session is deleted once it has gone unused this long (ADR-0777). A client +// with a session is never deleted: "The server MUST NOT delete client registrations that have an active session." +inline constexpr auto oauth_client_retention = std::chrono::hours{24 * 30}; + +// Whether an authorisation request still pending names `client_id`, so its client must not be deleted under it. +// Phase 5 of the OAuth 2.0 work keeps pending authorisations; until then none exist and this is always false. +// Called with HomeserverRuntime::mutex held. +[[nodiscard]] auto oauth_client_has_pending_authorisation(HomeserverRuntime const& runtime, std::string_view client_id) + -> bool; // One sweep at `now`: // - deletes the sessions and tokens that can no longer authenticate (revoked or long-expired access tokens, // expired refresh tokens), from the database in batches of `retention_batch_rows`, then once from memory; // - when `security.audit_log_retention_days` is not 0, deletes the audit rows older than that, in batches, -// and writes one `audit.retention.purged` audit row saying up to when and in how many batches. +// and writes one `audit.retention.purged` audit row saying up to when and in how many batches; +// - deletes the OAuth 2.0 clients with no session and none pending, last used over `oauth_client_retention` +// ago, least recently used first, in batches of `retention_batch_rows` (database and memory together). // Locks: HomeserverRuntime::mutex is taken for one scan of the in-memory tokens, once per batch (one // transaction of at most `retention_batch_rows` rows) and once for the final in-memory erase; it is released // between batches. The audit existence probe reads on a connection of its own with no lock held. A failed diff --git a/migrations/002_oauth_tables.sql b/migrations/002_oauth_tables.sql new file mode 100644 index 000000000..acdcd6868 --- /dev/null +++ b/migrations/002_oauth_tables.sql @@ -0,0 +1,7 @@ +-- merovingian-migration version=2 name=oauth_tables direction=upgrade +-- statement create_oauth_clients +CREATE TABLE "oauth_clients" (client_id TEXT PRIMARY KEY, metadata_json TEXT NOT NULL, created_at_ms TEXT NOT NULL, last_used_at_ms TEXT NOT NULL) +-- statement create_oauth_sessions +CREATE TABLE "oauth_sessions" (user_id TEXT NOT NULL, device_id TEXT NOT NULL, client_id TEXT NOT NULL, scope TEXT NOT NULL, created_at_ms TEXT NOT NULL, PRIMARY KEY (user_id, device_id)) +-- statement create_idx_oauth_sessions_client_id +CREATE INDEX idx_oauth_sessions_client_id ON oauth_sessions (client_id) diff --git a/migrations/AGENTS.md b/migrations/AGENTS.md index 636db1155..62f6931ca 100644 --- a/migrations/AGENTS.md +++ b/migrations/AGENTS.md @@ -24,10 +24,24 @@ to match statement for statement. - **v1 is frozen (1.0.0 is cut).** The pre-1.0 rule, that a schema change edited `core_tables`/`core_indexes` and this file together, no longer applies. Never edit `001_initial_schema.sql`, and never change `core_tables`/`core_indexes` in a way that changes what v1 creates. A schema change is - a new migration: `002_.sql`, plus its upgrade step in `upgrade_migration_catalog()` - and its downgrade at the front of `downgrade_migration_catalog()`. The first one must - also make `initial_schema_definitions()` keep returning the v1 shape while - `current_schema_definitions()` gains the change (today both return the same registry). + a new migration: `00N_.sql`, plus its upgrade step in `upgrade_migration_catalog()` + and its downgrade at the front of `downgrade_migration_catalog()`. + +## Migration 002: the OAuth 2.0 tables (1.1.0, ADR-0776, ADR-0778) + +`002_oauth_tables.sql` creates `oauth_clients`, `oauth_sessions` and `idx_oauth_sessions_client_id`. It is the +first migration after v1, so it also split the schema registry by version (ADR-0778): `Schema.cpp` keeps one pair of +arrays per version (`core_tables`/`core_indexes` for v1, `oauth_tables`/`oauth_indexes` for v2), and +`schema_definitions_added_by(version)` / `schema_indexes_added_by(version)` return what a version adds. +`initial_schema_definitions()` is version 1 only and `current_schema_definitions()` every version up to +`current_schema_version()`. Each step is generated from what its version adds (`oauth_tables_migration()`), and the +bootstraps build version 1 only, so a fresh database runs 002 exactly as an upgraded 1.0.x one does. The unit test +"Checked-in migrations hold exactly the steps this build runs" compares every file to its catalog step. + +A later migration that adds tables does the same: new arrays, a case in both `*_added_by` functions, a step built +with `schema_step_creating` and its downgrade with `schema_step_dropping`, a file equal to the step, a higher +`schema_version`, and the new tables classified for the worker. It never edits an earlier version's arrays. +`merovingian-db-migrate --plan A B --migrations DIR` takes only the files with a version in (A, B]. - Never rename a step or reuse a version number: the ledger check identifies a step by both. @@ -39,7 +53,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: `001`. +Current highest: `002`. ## File format @@ -55,8 +69,8 @@ NEXT SQL STATEMENT - Each statement preceded by `-- statement ` on its own line - Statement names must be unique within the file and descriptive (`events_add_stream_ordering`, not `stmt1`) - No trailing semicolons — the migration runner adds them -- The v1 file names each table statement `create_` and each index statement - `create_`, and quotes table names in `CREATE TABLE`, exactly as the build's +- The v1 and 002 files name each table statement `create_
` and each index statement + `create_`, and quote table names in `CREATE TABLE`, exactly as the build's generated DDL does ## Federation worker classification diff --git a/src/database/AGENTS.md b/src/database/AGENTS.md index e1f28e921..4994c855e 100644 --- a/src/database/AGENTS.md +++ b/src/database/AGENTS.md @@ -13,7 +13,9 @@ Manages schema migrations and provides a dual-backend (SQLite / PostgreSQL) pers | `MigrationFiles.cpp` | Parses `migrations/*.sql` for `merovingian-db-migrate --migrations` and the tests; the server runs the C++ catalog | | `Connection.cpp` | Connection lifecycle and pool management | | `PreparedStatement.cpp` | Prepared statement wrapper; parameters are always bound, never interpolated | -| `Schema.cpp` | The frozen v1 schema: `core_tables` and `core_indexes`, the `SchemaTableDefinition`/`SchemaIndexDefinition` lists built from them, the `CREATE TABLE`/`CREATE INDEX` SQL, and `current_schema_version()` (ADR-0224: a schema change is a new numbered migration, never an edit to v1) | +| `Schema.cpp` | The schema by version: the frozen v1 arrays `core_tables` and `core_indexes` (ADR-0224: a schema change is a new numbered migration, never an edit to v1), the v2 arrays `oauth_tables` and `oauth_indexes`, `schema_definitions_added_by`/`schema_indexes_added_by`, the initial (v1) and current lists built from them, the `CREATE TABLE`/`CREATE INDEX` SQL, and `current_schema_version()` (ADR-0778) | +| `OAuthTables.cpp` | `OAuthTables`, the in-memory copy of `oauth_clients` and `oauth_sessions`: clients by ID, sessions by (user, device), a per-user index, a session count per client and the sessionless clients ordered by last use (ADR-0776, ADR-0777) | +| `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) | | `PersistentServerSigningKey.cpp` | A stored server signing-key row; wipes the secret on destruction and on overwrite | @@ -190,6 +192,19 @@ hash of the version and that digest. A new writer of `key_backup_sessions` goes bypasses them does not compile. Status and room are not in the key: the reader judges them. Never scan the table to find the children of an event. +## OAuth 2.0 tables (migration 002, ADR-0776, ADR-0777) + +`PersistentStore::oauth` is an `OAuthTables`: write it only through `OAuthStore.hpp` (hydration uses `insert_client` and +`insert_session`). A client row is never changed after insert except `last_used_at_ms`, which `touch_oauth_client` writes +at most once a day. `delete_oauth_clients` refuses a set holding a client with a session, so no caller can delete one +(spec: "The server MUST NOT delete client registrations that have an active session"); find candidates with +`oauth_clients_without_sessions`, which walks the sessionless clients oldest first and never the session table. +A session row is written in the caller's transaction: `prepare_oauth_session_insert` gives the statement, the caller +commits it with the device and tokens, and only then calls `remember_oauth_session`. **Every path that deletes a +`devices` row deletes its `oauth_sessions` row in the same transaction**: today that is `delete_device`, which appends +`delete_oauth_session_of_device_statement` and erases the memory row after the commit. A new device-deleting path does +the same. Neither table is read by the federation worker. + ## Backend selection The backend is chosen at startup from config (`database.backend = sqlite | postgresql`). @@ -199,7 +214,8 @@ All higher-level modules receive a `PersistentStore&` — they must not downcast See `migrations/AGENTS.md` for the migration file format. Migrations run automatically at startup via `Migration.hpp`; the runner is idempotent. The whole schema is one -v1 step (ADR-0224), frozen since 1.0.0: a schema change is a new numbered migration. Both stores refuse a ledger that names a migration this build does not have +v1 step (ADR-0224), frozen since 1.0.0: a schema change is a new numbered migration, the first of which is 002 +(the OAuth 2.0 tables, ADR-0778). Both stores refuse a ledger that names a migration this build does not have (`schema_ledger_is_known`) before migrating or hydrating anything, and the PostgreSQL bootstrap, like every migration, runs as `database.migration_role` when one is configured. diff --git a/src/database/Migration.cpp b/src/database/Migration.cpp index 8fdbf655f..67dd06f39 100644 --- a/src/database/Migration.cpp +++ b/src/database/Migration.cpp @@ -9,10 +9,10 @@ #include "merovingian/database/MigrationRecord.hpp" #include "merovingian/database/MigrationStep.hpp" #include "merovingian/database/MigrationValidationResult.hpp" +#include "merovingian/database/Schema.hpp" #include "merovingian/database/SchemaIndexDefinition.hpp" #include "merovingian/database/SchemaState.hpp" #include "merovingian/database/SchemaTableDefinition.hpp" -#include "merovingian/database/Schema.hpp" #include "merovingian/observability/LogEventSeverity.hpp" #include "merovingian/observability/SingleLog.hpp" #include "merovingian/observability/StructuredLogField.hpp" @@ -35,6 +35,9 @@ namespace constexpr auto initial_schema_version = std::uint32_t{1U}; constexpr auto initial_schema_name = std::string_view{"initial_schema"}; + // Migration 002 (ADR-0776): migrations/002_oauth_tables.sql records it. + constexpr auto oauth_tables_version = std::uint32_t{2U}; + constexpr auto oauth_tables_name = std::string_view{"oauth_tables"}; [[nodiscard]] auto make_create_table_statement(SchemaTableDefinition const& table) -> std::optional @@ -186,6 +189,40 @@ namespace return is_data_only_statement(statement.sql); } + // The upgrade to `version`: CREATE TABLE for each table that version adds, then CREATE INDEX for each of its + // indexes, named create_
and create_ as the migration files name them (ADR-0778). + [[nodiscard]] auto schema_step_creating(std::uint32_t version, std::string_view name) -> MigrationStep + { + auto statements = std::vector{}; + for (auto const& table : schema_definitions_added_by(version)) + { + // Table definitions are allowlisted at compile time, so the + // generated CREATE TABLE SQL is always valid. + statements.push_back(make_create_table_statement(table).value()); + } + for (auto const& index : schema_indexes_added_by(version)) + { + // Likewise for the registered indexes. + statements.push_back(make_create_index_statement(index).value()); + } + return {version, std::string{name}, std::move(statements), MigrationDirection::upgrade}; + } + + // The downgrade from `version` to the one before: DROP TABLE for each table `version` added, in reverse + // order so a dependent table comes down before the one it references. Each table's indexes go with it. + [[nodiscard]] auto schema_step_dropping(std::uint32_t version, std::string_view name) -> MigrationStep + { + auto statements = std::vector{}; + auto definitions = schema_definitions_added_by(version); + for (auto iterator = definitions.rbegin(); iterator != definitions.rend(); ++iterator) + { + // Table names are allowlisted at compile time, so the generated + // DROP TABLE SQL is always valid. + statements.push_back(make_drop_table_statement(iterator->name).value()); + } + return {version - 1U, std::string{name}, std::move(statements), MigrationDirection::downgrade}; + } + } // namespace auto migration_direction_name(MigrationDirection direction) noexcept -> std::string_view @@ -275,50 +312,38 @@ auto migration_plan_summary(MigrationPlan const& plan) -> std::string auto initial_schema_migration() -> MigrationStep { - // The whole schema, tables then indexes. Every pre-1.0 migration was folded - // into this one step (ADR-0224); migrations/001_initial_schema.sql records it - // statement for statement, and from 1.0.0 neither may change. - auto statements = std::vector{}; - for (auto const& table : initial_schema_definitions()) - { - // Core table definitions are allowlisted at compile time, so the - // generated CREATE TABLE SQL is always valid. - statements.push_back(make_create_table_statement(table).value()); - } - for (auto const& index : initial_schema_indexes()) - { - // Likewise for the registered indexes. - statements.push_back(make_create_index_statement(index).value()); - } - return {initial_schema_version, std::string{initial_schema_name}, std::move(statements), - MigrationDirection::upgrade}; + // The whole v1 schema, tables then indexes. Every pre-1.0 migration was + // folded into this one step (ADR-0224); migrations/001_initial_schema.sql + // records it statement for statement, and from 1.0.0 neither may change. + return schema_step_creating(initial_schema_version, initial_schema_name); } auto downgrade_initial_schema_migration() -> MigrationStep { - auto statements = std::vector{}; - auto definitions = initial_schema_definitions(); - // Drop in reverse declaration order so dependent tables come down - // before the ones they reference. Each table's indexes go with it. - for (auto iterator = definitions.rbegin(); iterator != definitions.rend(); ++iterator) - { - // Core table names are allowlisted at compile time, so the generated - // DROP TABLE SQL is always valid. - statements.push_back(make_drop_table_statement(iterator->name).value()); - } - return {0U, "drop_initial_schema", std::move(statements), MigrationDirection::downgrade}; + return schema_step_dropping(initial_schema_version, "drop_initial_schema"); +} + +auto oauth_tables_migration() -> MigrationStep +{ + return schema_step_creating(oauth_tables_version, oauth_tables_name); +} + +auto downgrade_oauth_tables_migration() -> MigrationStep +{ + return schema_step_dropping(oauth_tables_version, "drop_oauth_tables"); } -// The next migration is v2: add its upgrade step here and its downgrade (to v1) -// at the front of the downgrade catalog, and leave v1 exactly as it is. +// The next migration is v3: add its upgrade step at the end here, its downgrade +// (to v2) 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()}; + return {initial_schema_migration(), oauth_tables_migration()}; } auto downgrade_migration_catalog() -> std::vector { - return {downgrade_initial_schema_migration()}; + return {downgrade_oauth_tables_migration(), downgrade_initial_schema_migration()}; } auto migration_plan_between(std::uint32_t current_version, std::uint32_t target_version) -> MigrationPlan @@ -489,8 +514,9 @@ auto schema_state_is_compatible(SchemaState const& state) -> MigrationValidation auto migration_rollback_policy() noexcept -> std::string_view { - return "schema deploys at v1 in its final shape; the only downgrade drops it, exists for completeness, " - "and remains operator-controlled, paired with backup/restore validation"; + return "schema deploys at v1 and migrates forward one numbered step at a time; each step's downgrade drops " + "what that step created, exists for completeness, and remains operator-controlled, paired with " + "backup/restore validation"; } } // namespace merovingian::database diff --git a/src/database/MigrationFiles.cpp b/src/database/MigrationFiles.cpp index b76e4b786..be419b2ef 100644 --- a/src/database/MigrationFiles.cpp +++ b/src/database/MigrationFiles.cpp @@ -3,6 +3,8 @@ // SPDX-FileCopyrightText: 2026 James Chapman // SPDX-License-Identifier: GPL-3.0-or-later +#include + #include #include #include @@ -12,8 +14,6 @@ #include #include -#include - namespace merovingian::database { namespace @@ -177,7 +177,21 @@ auto build_offline_migration_plan(config::DatabaseConfig const& database_config, auto plan = migration_plan_between(current_version, target_version); if (!file_steps.empty()) { - plan.steps = file_steps; + // The directory holds every migration ever written; the plan takes only the steps between its two versions, + // so `--plan 1 2` runs 002 alone rather than replaying 001 over a v1 database. + auto const upgrade = plan.direction == MigrationDirection::upgrade; + auto const lowest = upgrade ? current_version : target_version; + auto const highest = upgrade ? target_version : current_version; + plan.steps.clear(); + for (auto const& step : file_steps) + { + auto const in_range = upgrade ? step.version > lowest && step.version <= highest + : step.version >= lowest && step.version < highest; + if (step.direction == plan.direction && in_range) + { + plan.steps.push_back(step); + } + } } auto const validation = migration_plan_is_valid(plan); if (!validation.valid) diff --git a/src/database/OAuthStore.cpp b/src/database/OAuthStore.cpp new file mode 100644 index 000000000..2073697fe --- /dev/null +++ b/src/database/OAuthStore.cpp @@ -0,0 +1,221 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/database/OAuthStore.hpp" + +#include "merovingian/database/BoundValue.hpp" +#include "merovingian/database/OAuthTables.hpp" +#include "merovingian/database/PersistentStore.hpp" + +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::database +{ +namespace +{ + + // A prepared statement takes at most 128 parameters, so a longer list of IDs is several DELETEs in the one + // transaction, never one statement per row. + constexpr auto delete_ids_per_statement = std::size_t{128U}; + + [[nodiscard]] auto text(std::string_view value) -> BoundValue + { + return {std::string{value}, false}; + } + + [[nodiscard]] auto client_id_is_storable(std::string_view client_id) noexcept -> bool + { + return !client_id.empty() && client_id.size() <= max_oauth_client_id_bytes; + } + + [[nodiscard]] auto delete_clients_statement(std::span client_ids) -> PreparedStatement + { + auto sql = std::string{"DELETE FROM oauth_clients WHERE client_id IN ("}; + auto parameters = std::vector{}; + parameters.reserve(client_ids.size()); + for (auto const& client_id : client_ids) + { + sql += parameters.empty() ? "$" : ", $"; + sql += std::to_string(parameters.size() + 1U); + parameters.push_back(text(client_id)); + } + sql += ")"; + return {"delete_oauth_clients", std::move(sql), std::move(parameters)}; + } + +} // namespace + +auto store_oauth_client(PersistentStore& store, PersistentOAuthClient client) -> OAuthClientStoreResult +{ + if (!client_id_is_storable(client.client_id) || client.metadata_json.empty() || + client.metadata_json.size() > max_oauth_client_metadata_bytes) + { + return OAuthClientStoreResult::refused; + } + if (store.oauth.find_client(client.client_id) != nullptr) + { + return OAuthClientStoreResult::existing; + } + auto const statement = PreparedStatement{ + "insert_oauth_client", + "INSERT INTO oauth_clients (client_id, metadata_json, created_at_ms, last_used_at_ms) VALUES ($1, $2, $3, $4)", + {text(client.client_id), text(client.metadata_json), text(std::to_string(client.created_at_ms)), + text(std::to_string(client.last_used_at_ms))} + }; + if (!commit_persistent_transaction(store, {statement})) + { + return OAuthClientStoreResult::refused; + } + std::ignore = store.oauth.insert_client(std::move(client)); + return OAuthClientStoreResult::inserted; +} + +auto find_oauth_client(PersistentStore const& store, std::string_view client_id) -> PersistentOAuthClient const* +{ + return store.oauth.find_client(client_id); +} + +auto oauth_client_count(PersistentStore const& store) -> std::size_t +{ + return store.oauth.client_count(); +} + +auto touch_oauth_client(PersistentStore& store, std::string_view client_id, std::uint64_t now_ms) -> bool +{ + auto const* client = store.oauth.find_client(client_id); + if (client == nullptr) + { + return false; + } + // A stored value from the future, or one inside the interval, is fresh enough: no write. + if (now_ms <= client->last_used_at_ms || now_ms - client->last_used_at_ms <= oauth_client_touch_interval_ms) + { + return true; + } + auto const statement = PreparedStatement{ + "touch_oauth_client", + "UPDATE oauth_clients SET last_used_at_ms = $1 WHERE client_id = $2", + {text(std::to_string(now_ms)), text(client_id)} + }; + if (!commit_persistent_transaction(store, {statement})) + { + return false; + } + std::ignore = store.oauth.set_client_last_used(client_id, now_ms); + return true; +} + +auto delete_oauth_clients(PersistentStore& store, std::span client_ids) -> bool +{ + if (client_ids.empty()) + { + return true; + } + auto seen = std::unordered_set{}; + for (auto const& client_id : client_ids) + { + if (!seen.insert(client_id).second || store.oauth.find_client(client_id) == nullptr || + store.oauth.sessions_of_client(client_id) != 0U) + { + return false; + } + } + auto statements = std::vector{}; + statements.reserve((client_ids.size() / delete_ids_per_statement) + 1U); + for (auto first = std::size_t{0U}; first < client_ids.size(); first += delete_ids_per_statement) + { + auto const count = std::min(delete_ids_per_statement, client_ids.size() - first); + statements.push_back(delete_clients_statement(client_ids.subspan(first, count))); + } + if (!commit_persistent_transaction(store, statements)) + { + return false; + } + for (auto const& client_id : client_ids) + { + std::ignore = store.oauth.erase_client(client_id); + } + return true; +} + +auto oauth_clients_without_sessions(PersistentStore const& store, std::size_t max, std::uint64_t used_before_ms, + std::function const& excluded) -> std::vector +{ + return store.oauth.idle_clients(max, used_before_ms, excluded); +} + +auto find_oauth_session(PersistentStore const& store, std::string_view user_id, std::string_view device_id) + -> PersistentOAuthSession const* +{ + return store.oauth.find_session(user_id, device_id); +} + +auto oauth_sessions_of_user(PersistentStore const& store, std::string_view user_id) + -> std::vector +{ + return store.oauth.sessions_of_user(user_id); +} + +auto oauth_client_has_session(PersistentStore const& store, std::string_view client_id) -> bool +{ + return store.oauth.sessions_of_client(client_id) != 0U; +} + +auto prepare_oauth_session_insert(PersistentStore const& store, PersistentOAuthSession const& session) + -> std::optional +{ + if (session.user_id.empty() || session.device_id.empty() || !client_id_is_storable(session.client_id) || + session.scope.size() > max_oauth_scope_bytes || store.oauth.find_client(session.client_id) == nullptr || + store.oauth.find_session(session.user_id, session.device_id) != nullptr) + { + return std::nullopt; + } + return PreparedStatement{ + "insert_oauth_session", + "INSERT INTO oauth_sessions (user_id, device_id, client_id, scope, created_at_ms) VALUES ($1, $2, $3, $4, $5)", + {text(session.user_id), text(session.device_id), text(session.client_id), text(session.scope), + text(std::to_string(session.created_at_ms))} + }; +} + +auto remember_oauth_session(PersistentStore& store, PersistentOAuthSession session) -> bool +{ + return store.oauth.insert_session(std::move(session)); +} + +auto store_oauth_session(PersistentStore& store, PersistentOAuthSession session) -> bool +{ + auto statement = prepare_oauth_session_insert(store, session); + if (!statement.has_value() || !commit_persistent_transaction(store, {std::move(*statement)})) + { + return false; + } + return remember_oauth_session(store, std::move(session)); +} + +auto delete_oauth_session(PersistentStore& store, std::string_view user_id, std::string_view device_id) -> bool +{ + if (store.oauth.find_session(user_id, device_id) == nullptr || + !commit_persistent_transaction(store, {delete_oauth_session_of_device_statement(user_id, device_id)})) + { + return false; + } + return store.oauth.erase_session(user_id, device_id); +} + +auto delete_oauth_session_of_device_statement(std::string_view user_id, std::string_view device_id) -> PreparedStatement +{ + return { + "delete_oauth_session_of_device", + "DELETE FROM oauth_sessions WHERE user_id = $1 AND device_id = $2", + {text(user_id), text(device_id)} + }; +} + +} // namespace merovingian::database diff --git a/src/database/OAuthTables.cpp b/src/database/OAuthTables.cpp new file mode 100644 index 000000000..4b1010a31 --- /dev/null +++ b/src/database/OAuthTables.cpp @@ -0,0 +1,204 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/database/OAuthTables.hpp" + +#include + +namespace merovingian::database +{ +namespace +{ + + // A key made of the user and the device, separated by NUL, which no Matrix identifier may hold. + [[nodiscard]] auto session_key(std::string_view user_id, std::string_view device_id) -> std::string + { + auto key = std::string{user_id}; + key.push_back('\0'); + key.append(device_id); + return key; + } + +} // namespace + +auto OAuthTables::find_client(std::string_view client_id) const -> PersistentOAuthClient const* +{ + auto const found = clients_.find(client_id); + return found == clients_.end() ? nullptr : &found->second; +} + +auto OAuthTables::sessions_of_client(std::string_view client_id) const -> std::size_t +{ + auto const found = sessions_by_client_.find(client_id); + return found == sessions_by_client_.end() ? 0U : found->second; +} + +auto OAuthTables::mark_idle(PersistentOAuthClient const& client) -> void +{ + idle_.emplace(client.last_used_at_ms, client.client_id); +} + +auto OAuthTables::unmark_idle(PersistentOAuthClient const& client) -> void +{ + idle_.erase({client.last_used_at_ms, client.client_id}); +} + +auto OAuthTables::insert_client(PersistentOAuthClient client) -> bool +{ + if (clients_.contains(client.client_id)) + { + return false; + } + auto const idle = sessions_of_client(client.client_id) == 0U; + auto key = client.client_id; + auto const [position, inserted] = clients_.emplace(std::move(key), std::move(client)); + if (inserted && idle) + { + mark_idle(position->second); + } + return inserted; +} + +auto OAuthTables::set_client_last_used(std::string_view client_id, std::uint64_t last_used_at_ms) -> bool +{ + auto const found = clients_.find(client_id); + if (found == clients_.end()) + { + return false; + } + auto const idle = sessions_of_client(client_id) == 0U; + if (idle) + { + unmark_idle(found->second); + } + found->second.last_used_at_ms = last_used_at_ms; + if (idle) + { + mark_idle(found->second); + } + return true; +} + +auto OAuthTables::erase_client(std::string_view client_id) -> bool +{ + auto const found = clients_.find(client_id); + if (found == clients_.end() || sessions_of_client(client_id) != 0U) + { + return false; + } + unmark_idle(found->second); + clients_.erase(found); + return true; +} + +auto OAuthTables::idle_clients(std::size_t max, std::uint64_t used_before_ms, + std::function const& excluded) const -> std::vector +{ + auto chosen = std::vector{}; + auto walked = std::uint64_t{0U}; + for (auto const& [last_used_at_ms, client_id] : idle_) + { + if (chosen.size() >= max || last_used_at_ms >= used_before_ms) + { + break; + } + ++walked; + if (excluded && excluded(client_id)) + { + continue; + } + chosen.push_back(client_id); + } + rows_examined_.add(walked); + return chosen; +} + +auto OAuthTables::find_session(std::string_view user_id, std::string_view device_id) const + -> PersistentOAuthSession const* +{ + auto const found = sessions_.find(session_key(user_id, device_id)); + return found == sessions_.end() ? nullptr : &found->second; +} + +auto OAuthTables::sessions_of_user(std::string_view user_id) const -> std::vector +{ + auto rows = std::vector{}; + auto const devices = devices_by_user_.find(user_id); + if (devices == devices_by_user_.end()) + { + return rows; + } + rows.reserve(devices->second.size()); + for (auto const& device_id : devices->second) + { + if (auto const* session = find_session(user_id, device_id); session != nullptr) + { + rows.push_back(*session); + } + } + rows_examined_.add(devices->second.size()); + return rows; +} + +auto OAuthTables::insert_session(PersistentOAuthSession session) -> bool +{ + auto key = session_key(session.user_id, session.device_id); + if (sessions_.contains(key)) + { + return false; + } + auto& count = sessions_by_client_[session.client_id]; + if (count == 0U) + { + if (auto const* client = find_client(session.client_id); client != nullptr) + { + unmark_idle(*client); + } + } + ++count; + devices_by_user_[session.user_id].insert(session.device_id); + sessions_.emplace(std::move(key), std::move(session)); + return true; +} + +auto OAuthTables::erase_session(std::string_view user_id, std::string_view device_id) -> bool +{ + auto const found = sessions_.find(session_key(user_id, device_id)); + if (found == sessions_.end()) + { + return false; + } + auto const client_id = found->second.client_id; + if (auto const devices = devices_by_user_.find(user_id); devices != devices_by_user_.end()) + { + devices->second.erase(std::string{device_id}); + if (devices->second.empty()) + { + devices_by_user_.erase(devices); + } + } + sessions_.erase(found); + if (auto const count = sessions_by_client_.find(client_id); count != sessions_by_client_.end()) + { + if (--count->second == 0U) + { + sessions_by_client_.erase(count); + if (auto const* client = find_client(client_id); client != nullptr) + { + mark_idle(*client); + } + } + } + return true; +} + +auto OAuthTables::clear() noexcept -> void +{ + clients_.clear(); + sessions_.clear(); + devices_by_user_.clear(); + sessions_by_client_.clear(); + idle_.clear(); +} + +} // namespace merovingian::database diff --git a/src/database/PersistentStore.cpp b/src/database/PersistentStore.cpp index 552e58f9d..7150b4cdf 100644 --- a/src/database/PersistentStore.cpp +++ b/src/database/PersistentStore.cpp @@ -15,6 +15,7 @@ #include "merovingian/database/MembershipProjection.hpp" #include "merovingian/database/Migration.hpp" #include "merovingian/database/MissingEventReferences.hpp" +#include "merovingian/database/OAuthStore.hpp" #include "merovingian/database/PersistentAccessToken.hpp" #include "merovingian/database/PersistentAccountData.hpp" #include "merovingian/database/PersistentAdminAction.hpp" @@ -2344,11 +2345,14 @@ namespace record_statement("delete_to_device_messages_of_device", "DELETE FROM to_device_messages WHERE target_user_id = $1 AND target_device_id = $2", parameters), + // An OAuth device's session row goes with the device (ADR-0776), so the two never disagree. + delete_oauth_session_of_device_statement(user_id, device_id), }; if (!commit_persistent_transaction(store, statements)) { return false; } + std::ignore = store.oauth.erase_session(user_id, device_id); // The erase keeps the vector's order, so it shifts the rows after it once, for a device that exists. store.devices.erase(std::ranges::find_if(store.devices, [user_id, device_id](PersistentDevice const& device) { return device.user_id == user_id && device.device_id == device_id; @@ -5615,12 +5619,12 @@ auto rebuild_key_signature_index(PersistentStore& store) -> void statements.reserve(signatures.size()); for (auto const& signature : signatures) { - statements.push_back(record_statement( - "upsert_key_signature", - "INSERT INTO key_signatures VALUES ($1, $2, $3, $4) ON CONFLICT (signer_user_id, " - "target_user_id, target_device_id) DO UPDATE SET json = $4", - {public_value(signature.signer_user_id), public_value(signature.target_user_id), - public_value(signature.target_device_id), sensitive_value(signature.json)})); + statements.push_back( + record_statement("upsert_key_signature", + "INSERT INTO key_signatures VALUES ($1, $2, $3, $4) ON CONFLICT (signer_user_id, " + "target_user_id, target_device_id) DO UPDATE SET json = $4", + {public_value(signature.signer_user_id), public_value(signature.target_user_id), + public_value(signature.target_device_id), sensitive_value(signature.json)})); } if (!commit_persistent_transaction(store, statements)) { @@ -5649,7 +5653,7 @@ auto rebuild_key_signature_index(PersistentStore& store) -> void store.key_signature_key_index.note_appended(store.key_signatures.size(), key_signature_key_of(added)); store.key_signature_signer_index.note_appended(store.key_signatures.size(), added.signer_user_id); store.key_signature_target_key_index.note_appended(store.key_signatures.size(), - key_signature_target_key_of(added)); + key_signature_target_key_of(added)); } return all_accepted; } @@ -5657,9 +5661,9 @@ auto rebuild_key_signature_index(PersistentStore& store) -> void auto for_each_signer_key_signature(PersistentStore const& store, std::string_view signer_user_id, std::function const& visit) -> void { - for (auto const position : positions_in_group(store.key_signature_signer_index, store.key_signatures, - std::string{signer_user_id}, key_signature_signer_of, - store.key_rows_examined)) + for (auto const position : + positions_in_group(store.key_signature_signer_index, store.key_signatures, std::string{signer_user_id}, + key_signature_signer_of, store.key_rows_examined)) { if (!visit(store.key_signatures[position])) { diff --git a/src/database/PostgresqlStore.cpp b/src/database/PostgresqlStore.cpp index b8483e62d..292db041f 100644 --- a/src/database/PostgresqlStore.cpp +++ b/src/database/PostgresqlStore.cpp @@ -1382,6 +1382,44 @@ namespace } } + // Migration 002 (ADR-0776): OAuth 2.0 clients and the devices that are their sessions. Neither is on the + // federation worker's allowlist. + if (table_load_profile_includes("oauth_clients", profile)) + { + auto clients = query_rows(connection, "postgresql_load_oauth_clients", + "SELECT client_id, metadata_json, created_at_ms, last_used_at_ms FROM " + "oauth_clients ORDER BY client_id"); + if (!clients.ok) + { + return false; + } + for (auto const& row : clients.rows) + { + if (row.size() >= 4U) + { + std::ignore = store.oauth.insert_client({row[0], row[1], parse_u64(row[2]), parse_u64(row[3])}); + } + } + } + + if (table_load_profile_includes("oauth_sessions", profile)) + { + auto sessions = query_rows(connection, "postgresql_load_oauth_sessions", + "SELECT user_id, device_id, client_id, scope, created_at_ms FROM " + "oauth_sessions ORDER BY user_id, device_id"); + if (!sessions.ok) + { + return false; + } + for (auto const& row : sessions.rows) + { + if (row.size() >= 5U) + { + std::ignore = store.oauth.insert_session({row[0], row[1], row[2], row[3], parse_u64(row[4])}); + } + } + } + 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 c9dc8e45e..48d5789f8 100644 --- a/src/database/Schema.cpp +++ b/src/database/Schema.cpp @@ -8,6 +8,9 @@ #include #include +#include +#include +#include namespace merovingian::database { @@ -16,42 +19,44 @@ namespace // Every pre-1.0 migration was collapsed into v1 in 0.12.47 (ADR-0224). From // 1.0.0 the v1 step is frozen: a schema change is a new numbered migration, - // never an edit to core_tables that changes what v1 creates. - constexpr auto schema_version = std::uint32_t{1U}; + // 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{2U}; constexpr auto core_tables = std::array{ SchemaTableDefinition{"schema_migrations", "version TEXT PRIMARY KEY, name TEXT NOT NULL, direction TEXT NOT NULL" }, SchemaTableDefinition{ - "users", "user_id TEXT PRIMARY KEY, password_hash TEXT NOT NULL, locked TEXT NOT NULL, " + "users", "user_id TEXT PRIMARY KEY, password_hash TEXT NOT NULL, locked TEXT NOT NULL, " "suspended TEXT NOT NULL, admin TEXT NOT NULL, deactivated TEXT NOT NULL DEFAULT 'false'" }, - SchemaTableDefinition{"devices", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, display_name TEXT NOT NULL, " + SchemaTableDefinition{"devices", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, display_name TEXT NOT NULL, " "PRIMARY KEY (user_id, device_id)" }, SchemaTableDefinition{ - "access_tokens", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, token_hash TEXT PRIMARY KEY, revoked TEXT NOT NULL, " + "access_tokens", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, token_hash TEXT PRIMARY KEY, revoked TEXT NOT NULL, " "expires_at TEXT NOT NULL DEFAULT '', predecessor_refresh_hash TEXT NOT NULL DEFAULT ''" }, SchemaTableDefinition{ - "refresh_tokens", "token_hash TEXT PRIMARY KEY, user_id TEXT NOT NULL, device_id TEXT NOT NULL, revoked TEXT NOT NULL, " + "refresh_tokens", "token_hash TEXT PRIMARY KEY, user_id TEXT NOT NULL, device_id TEXT NOT NULL, revoked TEXT NOT NULL, " "expires_at TEXT NOT NULL DEFAULT '', predecessor_hash TEXT NOT NULL DEFAULT '', " "issued_at_ms TEXT NOT NULL DEFAULT '0'" }, SchemaTableDefinition{"server_signing_keys", "server_name TEXT NOT NULL, key_id TEXT NOT NULL, public_key TEXT NOT NULL, " "valid_until_ts TEXT NOT NULL, secret_key BLOB NOT NULL DEFAULT '', " - "expired_ts TEXT NOT NULL DEFAULT '', PRIMARY KEY (server_name, key_id)" }, + "expired_ts TEXT NOT NULL DEFAULT '', PRIMARY KEY (server_name, key_id)" }, SchemaTableDefinition{ - "rooms", "room_id TEXT PRIMARY KEY, creator_user_id TEXT NOT NULL, directory_public TEXT NOT NULL DEFAULT 'false'" }, + "rooms", "room_id TEXT PRIMARY KEY, creator_user_id TEXT NOT NULL, directory_public TEXT NOT NULL DEFAULT 'false'" }, SchemaTableDefinition{ - "room_aliases", "room_alias TEXT PRIMARY KEY, room_id TEXT NOT NULL, creator_user_id TEXT NOT NULL DEFAULT ''" }, - SchemaTableDefinition{"room_versions", "room_id TEXT PRIMARY KEY, version TEXT NOT NULL" }, + "room_aliases", "room_alias TEXT PRIMARY KEY, room_id TEXT NOT NULL, creator_user_id TEXT NOT NULL DEFAULT ''" }, + SchemaTableDefinition{"room_versions", "room_id TEXT PRIMARY KEY, version TEXT NOT NULL" }, SchemaTableDefinition{ - "events", "event_id TEXT PRIMARY KEY, room_id TEXT NOT NULL, sender_user_id TEXT NOT NULL, json TEXT " + "events", "event_id TEXT PRIMARY KEY, room_id TEXT NOT NULL, sender_user_id TEXT NOT NULL, json TEXT " "NOT NULL, depth TEXT NOT NULL, stream_ordering TEXT NOT NULL DEFAULT '0', status TEXT NOT NULL DEFAULT " "'accepted'" }, - SchemaTableDefinition{"event_json", "event_id TEXT PRIMARY KEY, json TEXT NOT NULL" }, + SchemaTableDefinition{"event_json", "event_id TEXT PRIMARY KEY, json TEXT NOT NULL" }, SchemaTableDefinition{ - "event_edges", "event_id TEXT NOT NULL, prev_event_id TEXT NOT NULL, PRIMARY KEY (event_id, prev_event_id)" }, + "event_edges", "event_id TEXT NOT NULL, prev_event_id TEXT NOT NULL, PRIMARY KEY (event_id, prev_event_id)" }, SchemaTableDefinition{ - "event_auth", "event_id TEXT NOT NULL, auth_event_id TEXT NOT NULL, PRIMARY KEY (event_id, auth_event_id)" }, + "event_auth", "event_id TEXT NOT NULL, auth_event_id TEXT NOT NULL, PRIMARY KEY (event_id, auth_event_id)" }, SchemaTableDefinition{"event_signatures", "event_id TEXT NOT NULL, server_name TEXT NOT NULL, key_id TEXT NOT NULL, signature TEXT " "NOT NULL, PRIMARY KEY (event_id, server_name, key_id)" }, @@ -59,7 +64,7 @@ namespace "room_id TEXT NOT NULL, event_type TEXT NOT NULL, state_key TEXT NOT NULL, event_id TEXT " "NOT NULL, PRIMARY KEY (room_id, event_type, state_key)" }, SchemaTableDefinition{ - "state_transitions", "room_id TEXT NOT NULL, event_type TEXT NOT NULL, state_key TEXT NOT NULL, event_id TEXT NOT " + "state_transitions", "room_id TEXT NOT NULL, event_type TEXT NOT NULL, state_key TEXT NOT NULL, event_id TEXT NOT " "NULL, previous_event_id TEXT NOT NULL DEFAULT '', PRIMARY KEY (room_id, event_type, state_key, event_id)"}, SchemaTableDefinition{"account_threepids", "user_id TEXT NOT NULL, medium TEXT NOT NULL, address TEXT NOT NULL, " @@ -68,9 +73,9 @@ namespace "bound TEXT NOT NULL DEFAULT '0', client_secret TEXT NOT NULL DEFAULT '', " "sid TEXT NOT NULL DEFAULT '', PRIMARY KEY (user_id, medium, address)" }, SchemaTableDefinition{ - "state_groups", "state_group_id TEXT PRIMARY KEY, room_id TEXT NOT NULL, parent_state_group_id TEXT NOT NULL DEFAULT '', " + "state_groups", "state_group_id TEXT PRIMARY KEY, room_id TEXT NOT NULL, parent_state_group_id TEXT NOT NULL DEFAULT '', " "delta_depth TEXT NOT NULL DEFAULT '0'" }, - SchemaTableDefinition{"state_group_edges", "state_group_id TEXT NOT NULL, prev_state_group_id TEXT NOT NULL, " + SchemaTableDefinition{"state_group_edges", "state_group_id TEXT NOT NULL, prev_state_group_id TEXT NOT NULL, " "PRIMARY KEY (state_group_id, prev_state_group_id)" }, SchemaTableDefinition{"membership", "room_id TEXT NOT NULL, user_id TEXT NOT NULL, membership TEXT NOT NULL DEFAULT 'join', " @@ -88,33 +93,31 @@ namespace "user_id TEXT NOT NULL, room_id TEXT NOT NULL, event_type TEXT NOT NULL, stream_id TEXT " "NOT NULL DEFAULT '0', json TEXT NOT NULL, PRIMARY KEY (user_id, room_id, event_type)" }, SchemaTableDefinition{ - "push_rules", "user_id TEXT NOT NULL, rule_id TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, rule_id)" }, + "push_rules", "user_id TEXT NOT NULL, rule_id TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, rule_id)" }, SchemaTableDefinition{ - "filters", "user_id TEXT NOT NULL, filter_id TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, filter_id)" }, - SchemaTableDefinition{"device_keys", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, json TEXT NOT NULL, " + "filters", "user_id TEXT NOT NULL, filter_id TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, filter_id)" }, + SchemaTableDefinition{"device_keys", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, json TEXT NOT NULL, " "PRIMARY KEY (user_id, device_id)" }, - SchemaTableDefinition{"one_time_keys", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, key_id TEXT NOT NULL, " + SchemaTableDefinition{"one_time_keys", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, key_id TEXT NOT NULL, " "json TEXT NOT NULL, PRIMARY KEY (user_id, device_id, key_id)" }, - SchemaTableDefinition{"fallback_keys", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, key_id TEXT NOT NULL, " + SchemaTableDefinition{"fallback_keys", "user_id TEXT NOT NULL, device_id TEXT NOT NULL, key_id TEXT NOT NULL, " "json TEXT NOT NULL, PRIMARY KEY (user_id, device_id, key_id)" }, SchemaTableDefinition{ - "cross_signing_keys", "user_id TEXT NOT NULL, key_type TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, key_type)" }, + "cross_signing_keys", "user_id TEXT NOT NULL, key_type TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, key_type)" }, SchemaTableDefinition{ - "key_signatures", "signer_user_id TEXT NOT NULL, target_user_id TEXT NOT NULL, target_device_id TEXT NOT NULL, " + "key_signatures", "signer_user_id TEXT NOT NULL, target_user_id TEXT NOT NULL, target_device_id TEXT NOT NULL, " "json TEXT NOT NULL, PRIMARY KEY (signer_user_id, target_user_id, target_device_id)" }, SchemaTableDefinition{ - "key_backups", "user_id TEXT NOT NULL, version TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, version)" }, + "key_backups", "user_id TEXT NOT NULL, version TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, version)" }, SchemaTableDefinition{ - "key_backup_versions", "user_id TEXT NOT NULL, version TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, version)" }, + "key_backup_versions", "user_id TEXT NOT NULL, version TEXT NOT NULL, json TEXT NOT NULL, PRIMARY KEY (user_id, version)" }, + SchemaTableDefinition{"key_backup_version_counters", "user_id TEXT PRIMARY KEY, last_version TEXT NOT NULL" }, SchemaTableDefinition{ - "key_backup_version_counters", - "user_id TEXT PRIMARY KEY, last_version TEXT NOT NULL" }, - SchemaTableDefinition{ - "key_backup_sessions", "user_id TEXT NOT NULL, version TEXT NOT NULL, room_id TEXT NOT NULL, session_id TEXT NOT NULL, " + "key_backup_sessions", "user_id TEXT NOT NULL, version TEXT NOT NULL, room_id TEXT NOT NULL, session_id TEXT NOT NULL, " "json TEXT NOT NULL, PRIMARY KEY (user_id, version, room_id, session_id), " "FOREIGN KEY (user_id, version) REFERENCES key_backup_versions (user_id, version) ON DELETE CASCADE" }, SchemaTableDefinition{ - "media", "media_id TEXT PRIMARY KEY, owner_user_id TEXT NOT NULL, content_type TEXT NOT " + "media", "media_id TEXT PRIMARY KEY, owner_user_id TEXT NOT NULL, content_type TEXT NOT " "NULL, size_bytes TEXT NOT NULL, hash_algorithm TEXT NOT NULL, digest TEXT NOT " "NULL, quarantined TEXT NOT NULL, removed TEXT NOT NULL, legacy_endpoint_visible TEXT NOT NULL " "DEFAULT 'true', upload_name TEXT NOT NULL DEFAULT ''" }, @@ -122,7 +125,7 @@ namespace "storage_id TEXT PRIMARY KEY, hash_algorithm TEXT NOT NULL, digest TEXT NOT NULL, " "size_bytes TEXT NOT NULL, bytes BLOB NOT NULL, ref_count TEXT NOT NULL" }, SchemaTableDefinition{ - "remote_media", "server_name TEXT NOT NULL, media_id TEXT NOT NULL, content_type TEXT NOT NULL, size_bytes " + "remote_media", "server_name TEXT NOT NULL, media_id TEXT NOT NULL, content_type TEXT NOT NULL, size_bytes " "TEXT NOT NULL, quarantined TEXT NOT NULL, local_media_id TEXT NOT NULL DEFAULT '', fetched_at_ms " "TEXT NOT NULL DEFAULT '0', PRIMARY KEY (server_name, media_id)" }, SchemaTableDefinition{"federation_destinations", @@ -133,11 +136,12 @@ namespace "method TEXT NOT NULL, target TEXT NOT NULL, origin TEXT NOT NULL, " "origin_server_ts TEXT NOT NULL, body TEXT NOT NULL, retry_count TEXT NOT NULL, " "next_retry_ts TEXT NOT NULL" }, - SchemaTableDefinition{"rate_limits", "scope TEXT NOT NULL, key TEXT NOT NULL, count TEXT NOT NULL, reset_ts " + SchemaTableDefinition{"rate_limits", "scope TEXT NOT NULL, key TEXT NOT NULL, count TEXT NOT NULL, reset_ts " "TEXT NOT NULL, PRIMARY KEY (scope, key)" }, - SchemaTableDefinition{"audit_log", "category TEXT NOT NULL, event_type TEXT NOT NULL, actor TEXT NOT NULL, " - "target TEXT NOT NULL, reason TEXT NOT NULL, created_at_ms TEXT NOT NULL DEFAULT '0'"}, - SchemaTableDefinition{"policy_rules", "rule_id TEXT PRIMARY KEY, scope TEXT NOT NULL, entity TEXT NOT NULL, " + SchemaTableDefinition{"audit_log", + "category TEXT NOT NULL, event_type TEXT NOT NULL, actor TEXT NOT NULL, " + "target TEXT NOT NULL, reason TEXT NOT NULL, created_at_ms TEXT NOT NULL DEFAULT '0'" }, + SchemaTableDefinition{"policy_rules", "rule_id TEXT PRIMARY KEY, scope TEXT NOT NULL, entity TEXT NOT NULL, " "action TEXT NOT NULL, reason TEXT NOT NULL" }, SchemaTableDefinition{"admin_actions", "admin_user_id TEXT NOT NULL, action TEXT NOT NULL, target TEXT NOT NULL" }, @@ -155,18 +159,19 @@ namespace "DEFAULT 'offline', status_msg TEXT NOT NULL DEFAULT '', last_active_ago TEXT NOT NULL " "DEFAULT '0', currently_active TEXT NOT NULL DEFAULT 'false'" }, SchemaTableDefinition{ - "sync_stream_watermark", "singleton INTEGER PRIMARY KEY CHECK (singleton = 1), watermark TEXT NOT NULL DEFAULT '0'" }, + "sync_stream_watermark", "singleton INTEGER PRIMARY KEY CHECK (singleton = 1), watermark TEXT NOT NULL DEFAULT '0'" }, SchemaTableDefinition{ - "event_stream_watermark", "singleton INTEGER PRIMARY KEY CHECK (singleton = 1), watermark TEXT NOT NULL DEFAULT '0'" }, + "event_stream_watermark", "singleton INTEGER PRIMARY KEY CHECK (singleton = 1), watermark TEXT NOT NULL DEFAULT '0'" }, SchemaTableDefinition{"stream_token_epoch", - "singleton INTEGER PRIMARY KEY CHECK (singleton = 1), epoch TEXT NOT NULL"}, - SchemaTableDefinition{"profiles", "user_id TEXT PRIMARY KEY, displayname TEXT NOT NULL DEFAULT '', " - "avatar_url TEXT NOT NULL DEFAULT '', fields_json TEXT NOT NULL DEFAULT '{}'" }, + "singleton INTEGER PRIMARY KEY CHECK (singleton = 1), epoch TEXT NOT NULL" }, + SchemaTableDefinition{"profiles", + "user_id TEXT PRIMARY KEY, displayname TEXT NOT NULL DEFAULT '', " + "avatar_url TEXT NOT NULL DEFAULT '', fields_json TEXT NOT NULL DEFAULT '{}'" }, SchemaTableDefinition{"client_txn_ids", "user_id TEXT NOT NULL, room_id TEXT NOT NULL, event_type TEXT NOT NULL, " "txn_id TEXT NOT NULL, event_id TEXT NOT NULL, device_id TEXT NOT NULL DEFAULT '', " "created_at_ms TEXT NOT NULL DEFAULT '0', " - "PRIMARY KEY (user_id, device_id, room_id, event_type, txn_id)" }, + "PRIMARY KEY (user_id, device_id, room_id, event_type, txn_id)" }, SchemaTableDefinition{"pushers", "user_id TEXT NOT NULL, app_id TEXT NOT NULL, pushkey TEXT NOT NULL, " "kind TEXT NOT NULL, app_display_name TEXT NOT NULL DEFAULT '', " @@ -180,7 +185,7 @@ namespace "stream_ordering TEXT NOT NULL DEFAULT '0', ts TEXT NOT NULL DEFAULT '0', " "actions TEXT NOT NULL DEFAULT '[]', profile_tag TEXT NOT NULL DEFAULT '', " "highlight TEXT NOT NULL DEFAULT 'false', PRIMARY KEY (user_id, event_id)" }, - SchemaTableDefinition{"openid_tokens", "user_id TEXT NOT NULL, token_hash TEXT PRIMARY KEY, " + SchemaTableDefinition{"openid_tokens", "user_id TEXT NOT NULL, token_hash TEXT PRIMARY KEY, " "expires_at TEXT NOT NULL DEFAULT '0'" }, SchemaTableDefinition{"login_tokens", "user_id TEXT NOT NULL, token_hash TEXT PRIMARY KEY, expires_at TEXT NOT NULL " @@ -196,7 +201,7 @@ namespace "event_id TEXT NOT NULL, PRIMARY KEY (state_group_id, event_type, state_key)" }, // ADR-0064: maps an event to the state group holding the // room's state immediately after it. - SchemaTableDefinition{"event_state_groups", "event_id TEXT PRIMARY KEY, state_group_id TEXT NOT NULL" }, + SchemaTableDefinition{"event_state_groups", "event_id TEXT PRIMARY KEY, state_group_id TEXT NOT NULL" }, // ADR-0064: a room's current forward extremities (DAG leaves). SchemaTableDefinition{"forward_extremities", "room_id TEXT NOT NULL, event_id TEXT NOT NULL, PRIMARY KEY (room_id, event_id)" }, @@ -215,7 +220,7 @@ namespace // unthreaded receipt has thread_id ''. Numbers are TEXT like every other // numeric column here. SchemaTableDefinition{ - "receipts", "room_id TEXT NOT NULL, receipt_type TEXT NOT NULL, user_id TEXT NOT NULL, " + "receipts", "room_id TEXT NOT NULL, receipt_type TEXT NOT NULL, user_id TEXT NOT NULL, " "thread_id TEXT NOT NULL DEFAULT '', event_id TEXT NOT NULL, ts TEXT NOT NULL DEFAULT '0', " "stream_id TEXT NOT NULL DEFAULT '0', PRIMARY KEY (room_id, receipt_type, user_id, thread_id)" }, // ADR-0192: a room an appservice published to the directory of one of its networks. @@ -237,26 +242,59 @@ namespace // `room_id` alone (ADR-0490), and the credential tables' per-device and per-predecessor revocations (F-08): // their WHERE clauses name `user_id`, `device_id` and `predecessor_hash`; `token_hash` is the primary key. constexpr auto core_indexes = std::array{ - SchemaIndexDefinition{"event_edges_prev_event_id", "event_edges", "prev_event_id"}, + SchemaIndexDefinition{"event_edges_prev_event_id", "event_edges", "prev_event_id" }, SchemaIndexDefinition{"idx_to_device_messages_recipient_age", "to_device_messages", - "target_user_id, target_device_id, created_at_ms" }, - SchemaIndexDefinition{"idx_deferred_pdus_room_id", "deferred_pdus", "room_id" }, - SchemaIndexDefinition{"idx_media_pending_uploads_owner", "media_pending_uploads", "owner_user_id"}, - SchemaIndexDefinition{"idx_events_room_id", "events", "room_id" }, - SchemaIndexDefinition{"idx_state_groups_room_id", "state_groups", "room_id" }, + "target_user_id, target_device_id, created_at_ms" }, + SchemaIndexDefinition{"idx_deferred_pdus_room_id", "deferred_pdus", "room_id" }, + SchemaIndexDefinition{"idx_media_pending_uploads_owner", "media_pending_uploads", "owner_user_id" }, + SchemaIndexDefinition{"idx_events_room_id", "events", "room_id" }, + SchemaIndexDefinition{"idx_state_groups_room_id", "state_groups", "room_id" }, SchemaIndexDefinition{"idx_access_tokens_user_device", "access_tokens", "user_id, device_id"}, SchemaIndexDefinition{"idx_refresh_tokens_user_device", "refresh_tokens", "user_id, device_id"}, - SchemaIndexDefinition{"idx_refresh_tokens_predecessor", "refresh_tokens", "predecessor_hash"}, + SchemaIndexDefinition{"idx_refresh_tokens_predecessor", "refresh_tokens", "predecessor_hash" }, + }; + + // Migration 002 (ADR-0776): the OAuth 2.0 API's tables. Numbers are TEXT like + // every other numeric column here. No foreign key: the token tables do not + // reference `devices` either, and the store keeps both rules in code (a + // session names a held client; a client with a session is never deleted). + constexpr auto oauth_tables = std::array{ + SchemaTableDefinition{"oauth_clients", + "client_id TEXT PRIMARY KEY, metadata_json TEXT NOT NULL, created_at_ms TEXT NOT NULL, " + "last_used_at_ms TEXT NOT NULL" }, + SchemaTableDefinition{"oauth_sessions", + "user_id TEXT NOT NULL, device_id TEXT NOT NULL, client_id TEXT NOT NULL, " + "scope TEXT NOT NULL, created_at_ms TEXT NOT NULL, PRIMARY KEY (user_id, device_id)"}, }; + // The store answers "does this client have a session" from memory; the + // index keeps a lookup of a client's sessions in the database itself (an + // operator's query, a later reader) from scanning the table. + constexpr auto oauth_indexes = std::array{ + SchemaIndexDefinition{"idx_oauth_sessions_client_id", "oauth_sessions", "client_id"}, + }; + + template + auto append_all(std::vector& into, std::array const& from) -> void + { + into.insert(into.end(), from.begin(), from.end()); + } + + [[nodiscard]] auto index_is_registered(SchemaIndexDefinition const& index) -> bool + { + auto const same = [&index](SchemaIndexDefinition const& known) { + 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); + } + [[nodiscard]] auto index_sql(SchemaIndexDefinition const& index, std::string_view prefix) -> std::optional { - // Only registered indexes on core tables may participate in generated - // DDL; names are checked against the same identifier rule as tables. - auto const registered = std::ranges::any_of(core_indexes, [&index](SchemaIndexDefinition const& known) { - return known.name == index.name && known.table == index.table && known.columns_sql == index.columns_sql; - }); + // Only registered indexes on tables of the current schema may + // participate in generated DDL; names are checked against the same + // identifier rule as tables. + auto const registered = index_is_registered(index); if (!registered || !schema_table_is_core(index.table) || !quote_sqlite_identifier(index.name).has_value() || !quote_sqlite_identifier(index.table).has_value()) { @@ -273,30 +311,75 @@ auto current_schema_version() noexcept -> std::uint32_t return schema_version; } -// While v1 is the only version, the shape v1 creates is the current one. The -// first post-1.0 migration must split them again: initial_* keeps returning -// exactly what v1 created (migrations/001_initial_schema.sql is that record), -// and only current_* gains what the later migration adds. +// The schema split (ADR-0778): each version's own tables and indexes are one +// array. initial_* is exactly what v1 created (migrations/001_initial_schema.sql +// is that record, and the bootstraps build only it); current_* is every version +// up to current_schema_version() in order, which a fresh database reaches by +// the same later steps as a migrated v1 database. +auto schema_definitions_added_by(std::uint32_t version) -> std::vector +{ + auto tables = std::vector{}; + if (version == 1U) + { + append_all(tables, core_tables); + } + else if (version == 2U) + { + append_all(tables, oauth_tables); + } + return tables; +} + +auto schema_indexes_added_by(std::uint32_t version) -> std::vector +{ + auto indexes = std::vector{}; + if (version == 1U) + { + append_all(indexes, core_indexes); + } + else if (version == 2U) + { + append_all(indexes, oauth_indexes); + } + return indexes; +} + auto initial_schema_definitions() -> std::vector { - return {core_tables.begin(), core_tables.end()}; + return schema_definitions_added_by(1U); } auto current_schema_definitions() -> std::vector { - return {core_tables.begin(), core_tables.end()}; + auto tables = std::vector{}; + for (auto version = std::uint32_t{1U}; version <= schema_version; ++version) + { + auto added = schema_definitions_added_by(version); + tables.insert(tables.end(), added.begin(), added.end()); + } + return tables; } auto initial_schema_indexes() -> std::vector { - return {core_indexes.begin(), core_indexes.end()}; + return schema_indexes_added_by(1U); +} + +auto current_schema_indexes() -> std::vector +{ + auto indexes = std::vector{}; + for (auto version = std::uint32_t{1U}; version <= schema_version; ++version) + { + auto added = schema_indexes_added_by(version); + indexes.insert(indexes.end(), added.begin(), added.end()); + } + return indexes; } auto initial_schema_tables() -> std::vector { auto tables = std::vector{}; - tables.reserve(core_tables.size()); - for (auto const& table : core_tables) + for (auto const& table : initial_schema_definitions()) { tables.push_back(table.name); } @@ -306,8 +389,7 @@ auto initial_schema_tables() -> std::vector auto current_schema_tables() -> std::vector { auto tables = std::vector{}; - tables.reserve(core_tables.size()); - for (auto const& table : core_tables) + for (auto const& table : current_schema_definitions()) { tables.push_back(table.name); } @@ -316,10 +398,18 @@ auto current_schema_tables() -> std::vector auto schema_table_definition(std::string_view table_name) noexcept -> std::optional { - auto const iterator = std::ranges::find_if(core_tables, [table_name](SchemaTableDefinition const& table) { + auto const named = [table_name](SchemaTableDefinition const& table) { return table.name == table_name; - }); - return iterator == core_tables.end() ? std::nullopt : std::optional{*iterator}; + }; + if (auto const core = std::ranges::find_if(core_tables, named); core != core_tables.end()) + { + return *core; + } + if (auto const oauth = std::ranges::find_if(oauth_tables, named); oauth != oauth_tables.end()) + { + return *oauth; + } + return std::nullopt; } auto schema_table_is_core(std::string_view table_name) noexcept -> bool diff --git a/src/database/SqliteStore.cpp b/src/database/SqliteStore.cpp index 71f8f10bc..8d4aa3822 100644 --- a/src/database/SqliteStore.cpp +++ b/src/database/SqliteStore.cpp @@ -1168,6 +1168,20 @@ namespace entry.used = text_is_true(column_text(row, 3)); store.login_tokens.push_back(std::move(entry)); }) && + // Migration 002 (ADR-0776): OAuth 2.0 clients and the devices that are their sessions. + load_rows(connection, + "SELECT client_id, metadata_json, created_at_ms, last_used_at_ms FROM oauth_clients", + [&store](sqlite3_stmt& row) { + std::ignore = store.oauth.insert_client({column_text(row, 0), column_text(row, 1), + parse_u64(column_text(row, 2)), + parse_u64(column_text(row, 3))}); + }) && + load_rows(connection, "SELECT user_id, device_id, client_id, scope, created_at_ms FROM oauth_sessions", + [&store](sqlite3_stmt& row) { + std::ignore = store.oauth.insert_session({column_text(row, 0), column_text(row, 1), + column_text(row, 2), column_text(row, 3), + parse_u64(column_text(row, 4))}); + }) && // Application service delivery state: transaction cursors, the outbox and the directory mapping. load_rows(connection, "SELECT appservice_id, next_txn_id, delivered_stream_ordering, pending_txn_id, " diff --git a/src/database/meson.build b/src/database/meson.build index 2f2ea76cf..bd7d74e0c 100644 --- a/src/database/meson.build +++ b/src/database/meson.build @@ -6,6 +6,8 @@ database_sources = files( 'LibraryVersions.cpp', 'MigrationFiles.cpp', 'Migration.cpp', + 'OAuthStore.cpp', + 'OAuthTables.cpp', 'PersistentStore.cpp', 'PersistentServerSigningKey.cpp', 'PostgresqlConnection.cpp', diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 651500408..ec1ea045a 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -26,7 +26,7 @@ This is the largest and most complex module — read this file carefully before | `RoomService.cpp` | Room operations, event persistence, signing-key lifecycle, appservice and push delivery | | `AppserviceDelivery.cpp` | Application Service API outbound queue (ADR-0163): `enqueue_appservice_delivery` (request path, no network) and `drain_appservice_queues` (the one drainer thread, run by a `PeriodicJob` from `main.cpp`) | | `ClientTxnPrune.cpp` | `prune_client_transactions`: the sweep the `client-txn-prune` `PeriodicJob` runs every hour, deleting to-device `client_txn_ids` records older than 7 days (F-54, ADR-0381) | -| `RetentionSweep.cpp` | `run_retention_sweep`: the sweep the `retention-sweep` `PeriodicJob` runs every hour. Deletes sessions and tokens that can no longer authenticate and `audit_log` rows past `security.audit_log_retention_days`, in transactions of at most 500 rows (`retention_batch_rows`), at most 20 batches per kind per sweep. `runtime.mutex` is taken for one batch at a time, never across the whole sweep (ADR-0488, ADR-0489) | +| `RetentionSweep.cpp` | `run_retention_sweep`: the sweep the `retention-sweep` `PeriodicJob` runs every hour. Deletes sessions and tokens that can no longer authenticate and `audit_log` rows past `security.audit_log_retention_days`, and OAuth 2.0 clients with no session unused for 30 days (`oauth_client_retention`, least recently used first; never a client with a session, nor one `oauth_client_has_pending_authorisation` names, a seam that is false until phase 5; ADR-0777), in transactions of at most 500 rows (`retention_batch_rows`), at most 20 batches per kind per sweep. `runtime.mutex` is taken for one batch at a time, never across the whole sweep (ADR-0488, ADR-0489) | | `LoginTokenStore.cpp` | `LoginTokenStore`: the in-memory, bounded, single-use login tokens `POST /login/get_token` mints (CS8, ADR-0548). Hash only, constant-time scan, never evicts; guarded by `runtime.mutex` | | `SessionTable.cpp` | `SessionTable`: `LocalDatabase::sessions` with an index of token-hash digests, so `find_session` does not scan (ADR-0488), and an index by (user ID, device ID) behind `erase_device` (F-08), which a login on a held device and a refresh call after their database commit (ADR-0590); `rows_examined()` counts the sessions it visits | | `DeferredPduRetry.cpp` | Retains federation PDUs that could not yet be placed (`deferred_pdus`) and retries them: `retry_deferred_pdus`, `DeferredPduRetryJob` (R03, ADR-0165). A retry holds no lock across `ingest_pdu_event`; `ingest_pdu_event` writes rows only after signature verification | diff --git a/src/homeserver/RetentionSweep.cpp b/src/homeserver/RetentionSweep.cpp index 3edf52fc4..d20457840 100644 --- a/src/homeserver/RetentionSweep.cpp +++ b/src/homeserver/RetentionSweep.cpp @@ -3,6 +3,7 @@ #include "merovingian/homeserver/RetentionSweep.hpp" +#include "merovingian/database/OAuthStore.hpp" #include "merovingian/database/PersistentStore.hpp" #include "merovingian/database/PersistentStoreBackend.hpp" #include "merovingian/database/UnusableCredentials.hpp" @@ -20,6 +21,7 @@ #include #include #include +#include #include #include #include @@ -166,14 +168,68 @@ namespace return done; } + // Returns true when every expired sessionless client was deleted (or there was none), false when the sweep + // stopped at its batch cap or was asked to stop. Each batch is chosen and deleted in one hold of the lock, so a + // session granted between batches is seen by the next choice: delete_oauth_clients refuses a client with one. + [[nodiscard]] auto sweep_oauth_clients(HomeserverRuntime& runtime, std::chrono::system_clock::time_point now, + StopFlag const& stop) -> bool + { + auto const now_ms = static_cast( + std::chrono::duration_cast(now.time_since_epoch()).count()); + auto const keep_ms = static_cast( + std::chrono::duration_cast(oauth_client_retention).count()); + if (now_ms <= keep_ms) + { + return true; + } + auto const used_before_ms = now_ms - keep_ms; + auto const pending = [&runtime](std::string_view client_id) { + return oauth_client_has_pending_authorisation(runtime, client_id); + }; + auto batches = std::size_t{0U}; + auto deleted = std::size_t{0U}; + auto done = false; + while (batches < retention_max_batches && !stop.stop_requested()) + { + auto const guard = RuntimeLock{runtime.mutex}; + auto const expired = database::oauth_clients_without_sessions( + runtime.database.persistent_store, retention_batch_rows, used_before_ms, pending); + if (expired.empty()) + { + done = true; + break; + } + if (!database::delete_oauth_clients(runtime.database.persistent_store, expired)) + { + LOG_WARNING("Retention sweep could not delete a batch of unused OAuth 2.0 clients; will retry"); + return true; + } + deleted += expired.size(); + ++batches; + } + if (deleted != 0U) + { + LOG_INFO("Retention sweep deleted unused OAuth 2.0 clients; clients=" + std::to_string(deleted)); + } + return done; + } + } // namespace +// The seam phase 5 fills in: no authorisation request is kept yet, so none can name a client. +auto oauth_client_has_pending_authorisation([[maybe_unused]] HomeserverRuntime const& runtime, + [[maybe_unused]] std::string_view client_id) -> bool +{ + return false; +} + auto run_retention_sweep(HomeserverRuntime& runtime, std::chrono::system_clock::time_point now, StopFlag const& stop) -> std::chrono::milliseconds { auto const credentials_done = sweep_credentials(runtime, now, stop); auto const audit_done = sweep_audit_log(runtime, now, stop); - if (credentials_done && audit_done) + auto const oauth_done = sweep_oauth_clients(runtime, now, stop); + if (credentials_done && audit_done && oauth_done) { return std::chrono::duration_cast(retention_sweep_interval); } diff --git a/tests/integration/test_database_upgrade_flow.cpp b/tests/integration/test_database_upgrade_flow.cpp index 0c941f6d2..3465ab971 100644 --- a/tests/integration/test_database_upgrade_flow.cpp +++ b/tests/integration/test_database_upgrade_flow.cpp @@ -1,21 +1,21 @@ // SPDX-FileCopyrightText: 2026 James Chapman // SPDX-License-Identifier: GPL-3.0-or-later // -// The schema's upgrade path (ADR-0216, ADR-0224). Every pre-1.0 migration is -// collapsed into the one v1 step, so these scenarios show what the path does -// today: a fresh database is built at v1 in its final shape, the forward-only -// seam (migrate_*_schema_to) never moves past this build or backwards, and a -// database a pre-1.0 build created is refused rather than misread. Upgrade -// compatibility is promised from 1.0.0; when a v2 migration exists, the -// "any older schema version" scenario starts to cover it, and when 1.1 starts -// a fixture written by the last 1.0.x release joins them. +// The schema's upgrade path (ADR-0216, ADR-0224, ADR-0778). Every pre-1.0 +// migration is collapsed into the one v1 step and 1.1.0 adds migration 002 (the +// OAuth 2.0 tables), so these scenarios show what the path does: a database is +// built at v1 exactly as 1.0.x built it, a v1 database is migrated to the +// current version and then holds exactly the schema a fresh one does, the +// forward-only seam (migrate_*_schema_to) never moves past this build or +// backwards, and a database a pre-1.0 build created is refused rather than +// misread. A fixture written by the last 1.0.x release joins them. #include "../support/TempDirectory.hpp" #include "ScratchPostgresqlDatabase.hpp" #include "merovingian/database/ExaminedRows.hpp" #include "merovingian/database/PersistentStore.hpp" -#include "merovingian/database/SchemaState.hpp" #include "merovingian/database/PostgresqlStore.hpp" #include "merovingian/database/Schema.hpp" +#include "merovingian/database/SchemaState.hpp" #include #include @@ -102,6 +102,18 @@ class SqliteQuery final return statement_ != nullptr && sqlite3_step(statement_.get()) == SQLITE_DONE; } + // The first column of every row, as text. + [[nodiscard]] auto first_column_texts() -> std::vector + { + auto texts = std::vector{}; + while (statement_ != nullptr && sqlite3_step(statement_.get()) == SQLITE_ROW) + { + auto const* text = sqlite3_column_text(statement_.get(), 0); + texts.emplace_back(text == nullptr ? "" : reinterpret_cast(text)); + } + return texts; + } + // The first column of the first row as an integer, or -1 when there is none. [[nodiscard]] auto first_integer() -> std::int64_t { @@ -130,6 +142,16 @@ class SqliteQuery final return SqliteQuery{path, sql, std::move(values)}.first_integer(); } +// Every table and index SQLite records, as its type, name and normalised DDL, in a fixed order. +[[nodiscard]] auto sqlite_schema_shape(std::filesystem::path const& path) -> std::vector +{ + return SqliteQuery{path, + "SELECT type || ' ' || name || ' ' || coalesce(sql, '') FROM sqlite_master " + "WHERE name NOT LIKE 'sqlite_%' ORDER BY type, name", + {}} + .first_column_texts(); +} + struct PgFinish final { auto operator()(PGconn* connection) const noexcept -> void @@ -183,6 +205,33 @@ struct PgClear final return std::stoll(PQgetvalue(result.get(), 0, 0)); } +// The first column of every row, as text; empty when the query fails. +[[nodiscard]] auto pg_texts(std::string const& conninfo, std::string const& sql) -> std::vector +{ + auto const result = pg_query(conninfo, sql, {}); + auto texts = std::vector{}; + if (PQresultStatus(result.get()) != PGRES_TUPLES_OK) + { + return texts; + } + for (auto row = 0; row < PQntuples(result.get()); ++row) + { + texts.emplace_back(PQgetvalue(result.get(), row, 0)); + } + return texts; +} + +// Every column (with its type, nullability and default) and every index definition of the public schema. +[[nodiscard]] auto pg_schema_shape(std::string const& conninfo) -> std::vector +{ + auto shape = pg_texts(conninfo, "SELECT table_name || '.' || column_name || ' ' || data_type || ' ' || is_nullable " + "|| ' ' || coalesce(column_default, '') FROM information_schema.columns WHERE " + "table_schema = 'public' ORDER BY table_name, column_name"); + auto indexes = pg_texts(conninfo, "SELECT indexdef FROM pg_indexes WHERE schemaname = 'public' ORDER BY indexname"); + shape.insert(shape.end(), std::make_move_iterator(indexes.begin()), std::make_move_iterator(indexes.end())); + return shape; +} + [[nodiscard]] auto postgresql_uri_from_environment() -> std::string { auto const* value = std::getenv("MEROVINGIAN_TEST_POSTGRESQL_URI"); @@ -225,12 +274,9 @@ struct FoldedColumn final } constexpr auto v1_index_names = std::array{ - std::string_view{"event_edges_prev_event_id"}, - std::string_view{"idx_to_device_messages_recipient_age"}, - std::string_view{"idx_deferred_pdus_room_id"}, - std::string_view{"idx_media_pending_uploads_owner"}, - std::string_view{"idx_events_room_id"}, - std::string_view{"idx_state_groups_room_id"}, + std::string_view{"event_edges_prev_event_id"}, std::string_view{"idx_to_device_messages_recipient_age"}, + std::string_view{"idx_deferred_pdus_room_id"}, std::string_view{"idx_media_pending_uploads_owner"}, + std::string_view{"idx_events_room_id"}, std::string_view{"idx_state_groups_room_id"}, }; // Versions 2 to 26 of the ledger every pre-1.0 build up to 0.12.46 wrote, after @@ -278,17 +324,20 @@ SCENARIO("A SQLite schema is built at v1 and stops there", "[database][upgrade][ { auto const migrated = merovingian::database::migrate_sqlite_schema_to(path.string(), 1U); - THEN("the schema is at v1, recorded by one ledger row, with every current table") + THEN("the schema is at v1, recorded by one ledger row, with every v1 table and no later one") { REQUIRE(migrated.ok); REQUIRE(migrated.state.version == 1U); REQUIRE(migrated.state.applied_migrations.size() == 1U); REQUIRE(migrated.state.applied_migrations.front().name == "initial_schema"); - for (auto const table : merovingian::database::current_schema_tables()) + for (auto const table : merovingian::database::initial_schema_tables()) { INFO("table " << table); REQUIRE(has_table(migrated.state, table)); } + REQUIRE_FALSE(has_table(migrated.state, "oauth_clients")); + REQUIRE_FALSE(has_table(migrated.state, "oauth_sessions")); + REQUIRE(sqlite_count(path, "SELECT count(*) FROM sqlite_master WHERE name LIKE 'oauth%'") == 0); } } std::filesystem::remove(path); @@ -432,6 +481,44 @@ SCENARIO("A SQLite database at any older schema version opens at the current ver } } +SCENARIO("A SQLite database migrated from v1 holds exactly the schema a fresh one does", + "[database][upgrade][sqlite][oauth]") +{ + GIVEN("a database built at v1 and no fresh database yet") + { + auto const migrated_path = unique_sqlite_path("v1-to-current"); + auto const fresh_path = unique_sqlite_path("fresh-current"); + std::filesystem::remove(migrated_path); + std::filesystem::remove(fresh_path); + REQUIRE(merovingian::database::migrate_sqlite_schema_to(migrated_path.string(), 1U).ok); + + WHEN("the v1 database and a fresh one are each opened as a persistent store") + { + auto const migrated = merovingian::database::open_sqlite_persistent_store(migrated_path.string()); + auto const fresh = merovingian::database::open_sqlite_persistent_store(fresh_path.string()); + + THEN("migration 002 ran on the v1 database, both tables are empty, and the two schemas are identical") + { + REQUIRE(migrated.ok); + REQUIRE(fresh.ok); + REQUIRE(migrated.store.schema.version == merovingian::database::current_schema_version()); + REQUIRE(migrated.store.schema.applied_migrations.back().name == "oauth_tables"); + REQUIRE(sqlite_count(migrated_path, "SELECT count(*) FROM schema_migrations") == 2); + 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); + auto const migrated_shape = sqlite_schema_shape(migrated_path); + REQUIRE_FALSE(migrated_shape.empty()); + REQUIRE(migrated_shape == sqlite_schema_shape(fresh_path)); + REQUIRE(sqlite_count(migrated_path, "SELECT count(*) FROM sqlite_master WHERE type = 'index' AND " + "name = 'idx_oauth_sessions_client_id'") == 1); + } + } + std::filesystem::remove(migrated_path); + std::filesystem::remove(fresh_path); + } +} + SCENARIO("A fresh SQLite database has every column and index of the v1 schema", "[database][upgrade][sqlite][collapse]") { GIVEN("no database file") @@ -518,16 +605,20 @@ SCENARIO("A PostgreSQL schema is built at v1 and stops there", "[database][upgra { auto const migrated = merovingian::database::migrate_postgresql_schema_to(scratch.conninfo(), 1U); - THEN("the schema is at v1, recorded by one ledger row, with every current table") + THEN("the schema is at v1, recorded by one ledger row, with every v1 table and no later one") { REQUIRE(migrated.ok); REQUIRE(migrated.state.version == 1U); REQUIRE(migrated.state.applied_migrations.size() == 1U); - for (auto const table : merovingian::database::current_schema_tables()) + for (auto const table : merovingian::database::initial_schema_tables()) { INFO("table " << table); REQUIRE(has_table(migrated.state, table)); } + REQUIRE_FALSE(has_table(migrated.state, "oauth_clients")); + REQUIRE_FALSE(has_table(migrated.state, "oauth_sessions")); + REQUIRE(pg_count(scratch.conninfo(), "SELECT count(*) FROM information_schema.tables WHERE " + "table_schema = 'public' AND table_name LIKE 'oauth%'") == 0); } } } @@ -632,6 +723,45 @@ SCENARIO("A PostgreSQL server that cannot be reached is refused", "[database][up } } +SCENARIO("A PostgreSQL database migrated from v1 holds exactly the schema a fresh one does", + "[database][upgrade][postgresql][integration][oauth]") +{ + GIVEN("a database built at v1 and an empty one") + { + auto const uri = postgresql_uri_from_environment(); + if (uri.empty()) + { + SUCCEED("skipped: MEROVINGIAN_TEST_POSTGRESQL_URI is not set"); + return; + } + auto const migrated_scratch = merovingian::tests::ScratchPostgresqlDatabase{uri}; + auto const fresh_scratch = merovingian::tests::ScratchPostgresqlDatabase{uri}; + REQUIRE(migrated_scratch.created()); + REQUIRE(fresh_scratch.created()); + REQUIRE(merovingian::database::migrate_postgresql_schema_to(migrated_scratch.conninfo(), 1U).ok); + + WHEN("each is opened as a persistent store") + { + auto const migrated = merovingian::database::open_postgresql_persistent_store(migrated_scratch.conninfo()); + auto const fresh = merovingian::database::open_postgresql_persistent_store(fresh_scratch.conninfo()); + + THEN("migration 002 ran on the v1 database, both tables are empty, and the two schemas are identical") + { + INFO("migrated: " << migrated.reason << " fresh: " << fresh.reason); + 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") == 2); + 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()); + REQUIRE_FALSE(migrated_shape.empty()); + REQUIRE(migrated_shape == pg_schema_shape(fresh_scratch.conninfo())); + } + } + } +} + SCENARIO("A fresh PostgreSQL database has every column and index of the v1 schema", "[database][upgrade][postgresql][integration][collapse]") { diff --git a/tests/integration/test_persistent_homeserver_flow.cpp b/tests/integration/test_persistent_homeserver_flow.cpp index c25760463..9eb593c5a 100644 --- a/tests/integration/test_persistent_homeserver_flow.cpp +++ b/tests/integration/test_persistent_homeserver_flow.cpp @@ -783,12 +783,14 @@ SCENARIO("Persistent homeserver runtime bootstraps a fresh migrated schema", "[d REQUIRE(merovingian::homeserver::database_has_table(started.runtime.database, "device_keys")); REQUIRE(merovingian::homeserver::database_has_table(started.runtime.database, "key_backup_sessions")); REQUIRE(merovingian::homeserver::database_has_table(started.runtime.database, "admin_actions")); - // The whole schema is the single v1 migration. - REQUIRE(started.runtime.database.persistent_store.schema.applied_migrations.size() == 1U); - REQUIRE(started.runtime.database.persistent_store.schema.applied_migrations.front().direction == - merovingian::database::MigrationDirection::upgrade); - REQUIRE(started.runtime.database.persistent_store.schema.applied_migrations.front().name == - "initial_schema"); + // The frozen v1 migration, then migration 002 (the OAuth 2.0 tables), one ledger row each. + auto const& applied = started.runtime.database.persistent_store.schema.applied_migrations; + 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 == "oauth_tables"); + REQUIRE(merovingian::homeserver::database_has_table(started.runtime.database, "oauth_clients")); + REQUIRE(merovingian::homeserver::database_has_table(started.runtime.database, "oauth_sessions")); } } } @@ -814,7 +816,8 @@ SCENARIO("Persistent homeserver startup is idempotent for an already migrated sc REQUIRE(started.started); REQUIRE(started.runtime.database.persistent_store.schema.version == merovingian::database::current_schema_version()); - REQUIRE(started.runtime.database.persistent_store.schema.applied_migrations.size() == 1U); + REQUIRE(started.runtime.database.persistent_store.schema.applied_migrations.size() == + merovingian::database::current_schema_version()); } } } diff --git a/tests/integration/test_postgresql_store_behaviour_flow.cpp b/tests/integration/test_postgresql_store_behaviour_flow.cpp index 0e8f5d409..14c574375 100644 --- a/tests/integration/test_postgresql_store_behaviour_flow.cpp +++ b/tests/integration/test_postgresql_store_behaviour_flow.cpp @@ -7,6 +7,8 @@ // MEROVINGIAN_TEST_POSTGRESQL_URI is not set; a skip is not a pass. #include +#include +#include #include #include @@ -1613,3 +1615,68 @@ SCENARIO("A removal from current state survives a reopen on PostgreSQL", "[postg } } } + +SCENARIO("PostgreSQL OAuth clients and sessions survive a reopen and a session goes with its device", + "[database][postgresql][integration][pg-behaviour][oauth]") +{ + GIVEN("a client, a second client to touch, and a device holding an OAuth session") + { + 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 user_id = "@oauth-" + suffix + ":example.org"; + auto const client_id = "client-" + suffix; + auto const touched_id = "touched-" + suffix; + REQUIRE(make_user(opened.store, user_id)); + REQUIRE(db::store_device(opened.store, {user_id, "DEV", "phone"})); + REQUIRE(db::store_device(opened.store, {user_id, "KEEP", "laptop"})); + REQUIRE(db::store_oauth_client(opened.store, {client_id, R"({"client_name":"A"})", 5U, 5U}) == + db::OAuthClientStoreResult::inserted); + REQUIRE(db::store_oauth_client(opened.store, {touched_id, R"({"client_name":"B"})", 6U, 6U}) == + db::OAuthClientStoreResult::inserted); + REQUIRE(db::store_oauth_session(opened.store, {user_id, "DEV", client_id, "urn:matrix:client:api:*", 7U})); + REQUIRE(db::store_oauth_session(opened.store, {user_id, "KEEP", client_id, "openid", 8U})); + + WHEN("the second client is touched a day later, the device is deleted, and the store is reopened") + { + auto const later = 6U + db::oauth_client_touch_interval_ms + 1U; + REQUIRE(db::touch_oauth_client(opened.store, touched_id, later)); + REQUIRE(db::delete_device(opened.store, user_id, "DEV")); + opened = {}; + auto reopened = reopen(uri); + auto const* held = db::find_oauth_client(reopened.store, client_id); + auto const* touched = db::find_oauth_client(reopened.store, touched_id); + + THEN("both clients keep their fields, the touch persisted, and only the kept device's session remains") + { + REQUIRE(held != nullptr); + REQUIRE(held->metadata_json == R"({"client_name":"A"})"); + REQUIRE(held->created_at_ms == 5U); + REQUIRE(touched != nullptr); + REQUIRE(touched->last_used_at_ms == later); + REQUIRE(db::find_oauth_session(reopened.store, user_id, "DEV") == nullptr); + auto const* kept = db::find_oauth_session(reopened.store, user_id, "KEEP"); + REQUIRE(kept != nullptr); + REQUIRE(kept->scope == "openid"); + REQUIRE(kept->created_at_ms == 8U); + REQUIRE(db::oauth_client_has_session(reopened.store, client_id)); + } + + AND_THEN("a sessionless client can be deleted, and the client with a session cannot") + { + auto const sessionless = std::vector{touched_id}; + auto const with_session = std::vector{client_id}; + REQUIRE(db::delete_oauth_clients(reopened.store, sessionless)); + REQUIRE_FALSE(db::delete_oauth_clients(reopened.store, with_session)); + auto again = reopen(uri); + REQUIRE(db::find_oauth_client(again.store, touched_id) == nullptr); + REQUIRE(db::find_oauth_client(again.store, client_id) != nullptr); + } + } + } +} diff --git a/tests/integration/test_retention_sweep_flow.cpp b/tests/integration/test_retention_sweep_flow.cpp index 186ba0585..bb746d599 100644 --- a/tests/integration/test_retention_sweep_flow.cpp +++ b/tests/integration/test_retention_sweep_flow.cpp @@ -13,11 +13,15 @@ #include "merovingian/config/SecurityConfig.hpp" #include "merovingian/config/ServerConfig.hpp" #include "merovingian/database/ExaminedRows.hpp" +#include "merovingian/database/OAuthClientStoreResult.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentOAuthClient.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" #include "merovingian/database/PersistentStore.hpp" -#include "merovingian/homeserver/HomeserverRuntime.hpp" -#include "merovingian/homeserver/RuntimeStartResult.hpp" #include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/RetentionSweep.hpp" +#include "merovingian/homeserver/RuntimeStartResult.hpp" #include #include @@ -31,6 +35,7 @@ #include #include #include +#include namespace { @@ -340,3 +345,166 @@ SCENARIO("One audit deletion batch never deletes more rows than its limit", "[in } } } + +namespace +{ + +[[nodiscard]] auto oauth_client_at(std::string id, std::chrono::system_clock::time_point at) + -> merovingian::database::PersistentOAuthClient +{ + auto const at_ms = static_cast( + std::chrono::duration_cast(at.time_since_epoch()).count()); + return {std::move(id), R"({"client_name":"Example"})", at_ms, at_ms}; +} + +[[nodiscard]] auto oauth_session_of(std::string user_id, std::string device_id, std::string client_id) + -> merovingian::database::PersistentOAuthSession +{ + return {std::move(user_id), std::move(device_id), std::move(client_id), "urn:matrix:client:api:*", 1000U}; +} + +} // namespace + +SCENARIO("The retention sweep deletes OAuth clients unused for 30 days, never one with a session", + "[integration][sqlite][retention][oauth]") +{ + GIVEN("a client unused for 31 days, one unused as long that holds a session, and one used 29 days ago") + { + REQUIRE(sodium_init() >= 0); + auto database = TemporarySqliteDatabase{}; + auto started = merovingian::homeserver::start_runtime(sqlite_config(database.path(), 365U)); + REQUIRE(started.started); + auto& runtime = started.runtime; + auto& persistent = runtime.database.persistent_store; + auto const registration = merovingian::homeserver::register_local_user( + runtime, "alice", "CorrectHorse7!Battery", merovingian::tests::registration_token); + REQUIRE(registration.ok); + auto const user_id = std::string{registration.value}; + REQUIRE(merovingian::homeserver::login_local_user(runtime, user_id, "CorrectHorse7!Battery", "OAUTHDEV").ok); + + auto const now = std::chrono::system_clock::now(); + auto const day = std::chrono::hours{24}; + REQUIRE(merovingian::database::store_oauth_client(persistent, oauth_client_at("old-idle", now - (31 * day))) == + merovingian::database::OAuthClientStoreResult::inserted); + REQUIRE(merovingian::database::store_oauth_client(persistent, oauth_client_at("old-held", now - (31 * day))) == + merovingian::database::OAuthClientStoreResult::inserted); + REQUIRE( + merovingian::database::store_oauth_client(persistent, oauth_client_at("recent-idle", now - (29 * day))) == + merovingian::database::OAuthClientStoreResult::inserted); + REQUIRE( + merovingian::database::store_oauth_session(persistent, oauth_session_of(user_id, "OAUTHDEV", "old-held"))); + + WHEN("the retention sweep runs") + { + auto const next = merovingian::homeserver::run_retention_sweep(runtime, now, never_stopped); + + THEN("only the sessionless client past 30 days is deleted, from the database and from memory") + { + REQUIRE(durable_row_count(database.path(), "oauth_clients", "client_id = 'old-idle'") == 0); + REQUIRE(durable_row_count(database.path(), "oauth_clients", "client_id = 'old-held'") == 1); + REQUIRE(durable_row_count(database.path(), "oauth_clients", "client_id = 'recent-idle'") == 1); + REQUIRE(merovingian::database::find_oauth_client(persistent, "old-idle") == nullptr); + REQUIRE(merovingian::database::find_oauth_client(persistent, "old-held") != nullptr); + REQUIRE(merovingian::database::find_oauth_client(persistent, "recent-idle") != nullptr); + REQUIRE(next == merovingian::homeserver::retention_sweep_interval); + } + + AND_THEN("the seam for pending authorisations names no client yet") + { + REQUIRE_FALSE(merovingian::homeserver::oauth_client_has_pending_authorisation(runtime, "recent-idle")); + } + } + } +} + +SCENARIO("The OAuth client sweep deletes at most 500 clients per transaction", + "[integration][sqlite][retention][oauth]") +{ + GIVEN("1001 clients unused for 40 days") + { + REQUIRE(sodium_init() >= 0); + auto database = TemporarySqliteDatabase{}; + auto started = merovingian::homeserver::start_runtime(sqlite_config(database.path(), 365U)); + REQUIRE(started.started); + auto& runtime = started.runtime; + auto& persistent = runtime.database.persistent_store; + auto const now = std::chrono::system_clock::now(); + for (auto index = 0; index < 1001; ++index) + { + REQUIRE(merovingian::database::store_oauth_client( + persistent, oauth_client_at("client-" + std::to_string(index), + now - std::chrono::hours{24 * 40} + std::chrono::seconds{index})) == + merovingian::database::OAuthClientStoreResult::inserted); + } + + WHEN("the retention sweep runs") + { + auto const before = merovingian::database::committed_transaction_count(persistent); + std::ignore = merovingian::homeserver::run_retention_sweep(runtime, now, never_stopped); + auto const transactions = merovingian::database::committed_transaction_count(persistent) - before; + + THEN("every client goes, in three transactions of at most 500") + { + REQUIRE(durable_row_count(database.path(), "oauth_clients") == 0); + REQUIRE(merovingian::database::oauth_client_count(persistent) == 0U); + REQUIRE(transactions == 3U); + } + } + } +} + +SCENARIO("Every way a device is deleted deletes its OAuth session row", "[integration][sqlite][oauth][device]") +{ + GIVEN("alice with four OAuth devices, each holding a session") + { + REQUIRE(sodium_init() >= 0); + auto database = TemporarySqliteDatabase{}; + auto started = merovingian::homeserver::start_runtime(sqlite_config(database.path(), 365U)); + REQUIRE(started.started); + auto& runtime = started.runtime; + auto& persistent = runtime.database.persistent_store; + auto const registration = merovingian::homeserver::register_local_user( + runtime, "alice", "CorrectHorse7!Battery", merovingian::tests::registration_token); + REQUIRE(registration.ok); + auto const user_id = std::string{registration.value}; + REQUIRE(merovingian::database::store_oauth_client( + persistent, oauth_client_at("client-a", std::chrono::system_clock::now())) == + merovingian::database::OAuthClientStoreResult::inserted); + auto tokens = std::vector{}; + for (auto const* device : {"DEVA", "DEVB", "DEVC", "DEVD"}) + { + auto const login = + merovingian::homeserver::login_local_user(runtime, user_id, "CorrectHorse7!Battery", device); + REQUIRE(login.ok); + tokens.emplace_back(login.value); + REQUIRE( + merovingian::database::store_oauth_session(persistent, oauth_session_of(user_id, device, "client-a"))); + } + auto const session_rows = [&database](std::string const& device) { + return durable_row_count(database.path(), "oauth_sessions", "device_id = '" + device + "'"); + }; + REQUIRE(session_rows("DEVA") == 1); + + WHEN("DEVA logs out, DEVD is deleted through the device API, then DEVB logs out everywhere") + { + REQUIRE(merovingian::homeserver::logout_local_user(runtime, tokens[0]).ok); + auto const after_logout_a = session_rows("DEVA"); + auto const b_after_logout_a = session_rows("DEVB"); + REQUIRE(merovingian::homeserver::delete_local_device(runtime, user_id, "DEVD").ok); + auto const after_delete_d = session_rows("DEVD"); + REQUIRE(merovingian::homeserver::logout_all_local_user(runtime, tokens[1]).ok); + + THEN("each removed device's session row is gone from the database and from memory, and the client " + "is then sessionless") + { + REQUIRE(after_logout_a == 0); + REQUIRE(b_after_logout_a == 1); + REQUIRE(after_delete_d == 0); + REQUIRE(durable_row_count(database.path(), "oauth_sessions") == 0); + REQUIRE(merovingian::database::oauth_sessions_of_user(persistent, user_id).empty()); + REQUIRE_FALSE(merovingian::database::oauth_client_has_session(persistent, "client-a")); + REQUIRE(durable_row_count(database.path(), "oauth_clients", "client_id = 'client-a'") == 1); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index 99eb13dd4..95ce4b04d 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -343,6 +343,7 @@ shell = find_program('sh') 'unit/test_database_security_boundaries.cpp', 'unit/test_observability_bounded_text.cpp', 'unit/test_database_persistence.cpp', + 'unit/test_database_oauth_store.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 074941803..7081fedea 100644 --- a/tests/smoke/meson.build +++ b/tests/smoke/meson.build @@ -4,6 +4,7 @@ db_migrate_executable = meson.project_build_root() / 'src' / 'merovingian-db-mig setup_dev_env_script = meson.project_source_root() / 'scripts' / 'setup-dev-env.sh' build_linux_script = meson.project_source_root() / 'scripts' / 'build-linux.sh' example_config = meson.project_source_root() / 'config' / 'merovingian.conf.example' +migrations_directory = meson.project_source_root() / 'migrations' tmp_smoke_prefix = 'tmpdir=$(mktemp -d) && trap "rm -rf \"$tmpdir\"" EXIT HUP INT TERM && ' # The example config sets security.secrets.master_key_file, and a configured # master key that is missing fails --check-config and --dry-run. Provision one @@ -577,3 +578,25 @@ test( db_migrate_executable + ' --plan 1 1 > /dev/null 2>&1', ], ) + +# Migration 002 (1.1.0): a plan from v1 takes the checked-in 002 file alone, never 001 again, and a plan from an +# empty database takes both (ADR-0778). +test( + 'db-migrate-plans-v1-to-v2-from-files-smoke-test', + smoke_test, + args: [ + '-c', + db_migrate_executable + ' --plan 1 2 --migrations "' + migrations_directory + + '" | grep -q "current_version=1 target_version=2 steps=1"', + ], +) + +test( + 'db-migrate-plans-empty-to-v2-from-files-smoke-test', + smoke_test, + args: [ + '-c', + db_migrate_executable + ' --plan 0 2 --migrations "' + migrations_directory + + '" | grep -q "current_version=0 target_version=2 steps=2"', + ], +) diff --git a/tests/unit/test_database_oauth_store.cpp b/tests/unit/test_database_oauth_store.cpp new file mode 100644 index 000000000..40cf29aeb --- /dev/null +++ b/tests/unit/test_database_oauth_store.cpp @@ -0,0 +1,530 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The OAuth 2.0 client and session tables (migration 002, ADR-0776, ADR-0777): the store functions on the memory +// and SQLite backends, the caps, the 24-hour touch rule counted in transactions, the idle-client order retention +// reads, and the session row that goes with its device in one transaction. +#include "../support/TempDirectory.hpp" +#include "merovingian/database/BoundValue.hpp" +#include "merovingian/database/OAuthClientStoreResult.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentDevice.hpp" +#include "merovingian/database/PersistentOAuthClient.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/database/PersistentStoreOpenResult.hpp" +#include "merovingian/database/PreparedStatement.hpp" + +#include +#include + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::database::OAuthClientStoreResult; +using merovingian::database::PersistentOAuthClient; +using merovingian::database::PersistentOAuthSession; +using merovingian::database::PersistentStore; + +constexpr auto day_ms = std::uint64_t{24U} * 60U * 60U * 1000U; +constexpr auto all_times = std::numeric_limits::max(); + +[[nodiscard]] auto unique_sqlite_path(std::string_view label) -> std::filesystem::path +{ + auto const now = std::chrono::steady_clock::now().time_since_epoch().count(); + return merovingian::tests::temporary_directory() / + ("merovingian-oauth-store-" + std::string{label} + "-" + std::to_string(now) + ".sqlite3"); +} + +[[nodiscard]] auto client(std::string id, std::uint64_t at_ms) -> PersistentOAuthClient +{ + return {std::move(id), R"({"client_name":"Example"})", at_ms, at_ms}; +} + +[[nodiscard]] auto session(std::string user, std::string device, std::string client_id) -> PersistentOAuthSession +{ + return {std::move(user), std::move(device), std::move(client_id), "urn:matrix:client:api:*", 1000U}; +} + +struct SqliteClose final +{ + auto operator()(sqlite3* connection) const noexcept -> void + { + sqlite3_close(connection); + } +}; + +// Runs one statement on its own connection to the file, outside the store. +[[nodiscard]] auto sqlite_run(std::filesystem::path const& path, char const* sql) -> bool +{ + auto* raw = static_cast(nullptr); + auto const opened = sqlite3_open_v2(path.string().c_str(), &raw, SQLITE_OPEN_READWRITE, nullptr); + auto const connection = std::unique_ptr{raw}; + return opened == SQLITE_OK && sqlite3_exec(connection.get(), sql, nullptr, nullptr, nullptr) == SQLITE_OK; +} + +} // namespace + +SCENARIO("An OAuth client row is stored once, kept as first written, and refused over its caps", + "[database][oauth][oauth-store]") +{ + GIVEN("a memory store") + { + auto opened = merovingian::database::open_persistent_store(); + REQUIRE(opened.ok); + auto& store = opened.store; + + WHEN("a client is stored, stored again with other metadata, and oversized rows are offered") + { + auto const first = merovingian::database::store_oauth_client(store, client("client-a", 5000U)); + auto again = client("client-a", 9000U); + again.metadata_json = R"({"client_name":"Other"})"; + auto const second = merovingian::database::store_oauth_client(store, again); + + auto at_cap = client(std::string(merovingian::database::max_oauth_client_id_bytes, 'c'), 1U); + auto over_id = client(std::string(merovingian::database::max_oauth_client_id_bytes + 1U, 'c'), 1U); + auto at_metadata = client("client-big", 1U); + at_metadata.metadata_json = std::string(merovingian::database::max_oauth_client_metadata_bytes, 'm'); + auto over_metadata = client("client-bigger", 1U); + over_metadata.metadata_json = std::string(merovingian::database::max_oauth_client_metadata_bytes + 1U, 'm'); + auto const transactions_before = merovingian::database::committed_transaction_count(store); + auto const over_id_result = merovingian::database::store_oauth_client(store, over_id); + auto const over_metadata_result = merovingian::database::store_oauth_client(store, over_metadata); + auto const empty_id_result = merovingian::database::store_oauth_client(store, client("", 1U)); + auto const refused_transactions = + merovingian::database::committed_transaction_count(store) - transactions_before; + auto const at_cap_result = merovingian::database::store_oauth_client(store, at_cap); + auto const at_metadata_result = merovingian::database::store_oauth_client(store, at_metadata); + + THEN("the first write inserts, the second keeps the first row, and only rows within the caps are stored") + { + REQUIRE(first == OAuthClientStoreResult::inserted); + REQUIRE(second == OAuthClientStoreResult::existing); + auto const* held = merovingian::database::find_oauth_client(store, "client-a"); + REQUIRE(held != nullptr); + REQUIRE(held->metadata_json == R"({"client_name":"Example"})"); + REQUIRE(held->created_at_ms == 5000U); + REQUIRE(over_id_result == OAuthClientStoreResult::refused); + REQUIRE(over_metadata_result == OAuthClientStoreResult::refused); + REQUIRE(empty_id_result == OAuthClientStoreResult::refused); + REQUIRE(refused_transactions == 0U); + REQUIRE(at_cap_result == OAuthClientStoreResult::inserted); + REQUIRE(at_metadata_result == OAuthClientStoreResult::inserted); + REQUIRE(merovingian::database::oauth_client_count(store) == 3U); + } + } + } +} + +SCENARIO("Using an OAuth client writes its last use at most once a day", "[database][oauth][oauth-store][touch]") +{ + GIVEN("a memory store holding a client last used at day 10") + { + auto opened = merovingian::database::open_persistent_store(); + REQUIRE(opened.ok); + auto& store = opened.store; + auto const day_ten = 10U * day_ms; + REQUIRE(merovingian::database::store_oauth_client(store, client("client-a", day_ten)) == + OAuthClientStoreResult::inserted); + + WHEN("it is used a thousand times within the day, then once just after the day, then from the past") + { + auto const before = merovingian::database::committed_transaction_count(store); + auto all_ok = true; + for (auto use = std::uint64_t{0U}; use < 1000U; ++use) + { + all_ok = + merovingian::database::touch_oauth_client(store, "client-a", day_ten + (use * 86'000U)) && all_ok; + } + all_ok = merovingian::database::touch_oauth_client(store, "client-a", day_ten + day_ms) && all_ok; + auto const within_day = merovingian::database::committed_transaction_count(store) - before; + auto const after_day = day_ten + day_ms + 1U; + auto const touched = merovingian::database::touch_oauth_client(store, "client-a", after_day); + auto const after_touch = merovingian::database::committed_transaction_count(store) - before; + auto const from_past = merovingian::database::touch_oauth_client(store, "client-a", day_ten); + auto const unknown = merovingian::database::touch_oauth_client(store, "client-unknown", after_day); + + THEN("nothing is written inside the day, exactly one write follows it, and the clock never goes back") + { + REQUIRE(all_ok); + REQUIRE(within_day == 0U); + REQUIRE(touched); + REQUIRE(after_touch == 1U); + REQUIRE(from_past); + REQUIRE(merovingian::database::committed_transaction_count(store) - before == 1U); + REQUIRE(merovingian::database::find_oauth_client(store, "client-a")->last_used_at_ms == after_day); + REQUIRE_FALSE(unknown); + } + } + } +} + +SCENARIO("Sessionless OAuth clients are listed least recently used first without reading the sessions", + "[database][oauth][oauth-store][retention]") +{ + GIVEN("a memory store with five clients, one of them holding a session") + { + auto opened = merovingian::database::open_persistent_store(); + REQUIRE(opened.ok); + auto& store = opened.store; + for (auto const& [id, at] : std::vector>{ + {"client-e", 50U}, + {"client-b", 20U}, + {"client-a", 10U}, + {"client-d", 40U}, + {"client-c", 30U} + }) + { + REQUIRE(merovingian::database::store_oauth_client(store, client(id, at)) == + OAuthClientStoreResult::inserted); + } + REQUIRE(merovingian::database::store_device(store, {"@alice:example.org", "DEVA", ""})); + REQUIRE(merovingian::database::store_oauth_session(store, session("@alice:example.org", "DEVA", "client-b"))); + // Sessions that name no held client cost nothing either: the order is kept on the clients alone. + for (auto index = 0; index < 50; ++index) + { + REQUIRE(merovingian::database::remember_oauth_session( + store, session("@bob:example.org", "DEV" + std::to_string(index), "client-gone"))); + } + + WHEN("the sessionless clients are listed, capped, cut by time, and with one excluded") + { + auto const examined_before = store.oauth.rows_examined(); + auto const all = merovingian::database::oauth_clients_without_sessions(store, 10U, all_times); + auto const examined = store.oauth.rows_examined() - examined_before; + auto const capped = merovingian::database::oauth_clients_without_sessions(store, 2U, all_times); + auto const before_forty = merovingian::database::oauth_clients_without_sessions(store, 10U, 40U); + auto const without_a = + merovingian::database::oauth_clients_without_sessions(store, 2U, all_times, [](std::string_view id) { + return id == "client-a"; + }); + + THEN("they come oldest first, never the client with a session, and only the clients are walked") + { + REQUIRE(all == std::vector{"client-a", "client-c", "client-d", "client-e"}); + REQUIRE(examined == 4U); + REQUIRE(capped == std::vector{"client-a", "client-c"}); + REQUIRE(before_forty == std::vector{"client-a", "client-c"}); + REQUIRE(without_a == std::vector{"client-c", "client-d"}); + REQUIRE(merovingian::database::oauth_client_has_session(store, "client-b")); + } + } + + WHEN("a client is touched, and the session is deleted") + { + REQUIRE(merovingian::database::touch_oauth_client(store, "client-a", 10U + (2U * day_ms))); + REQUIRE(merovingian::database::delete_oauth_session(store, "@alice:example.org", "DEVA")); + auto const order = merovingian::database::oauth_clients_without_sessions(store, 10U, all_times); + + THEN("the touched client moves to the back and the freed client takes its place by its last use") + { + REQUIRE(order == std::vector{"client-b", "client-c", "client-d", "client-e", "client-a"}); + REQUIRE_FALSE(merovingian::database::oauth_client_has_session(store, "client-b")); + } + } + } +} + +SCENARIO("Deleting OAuth clients is all or nothing and never takes a client with a session", + "[database][oauth][oauth-store][retention]") +{ + GIVEN("a memory store with 300 sessionless clients and one with a session") + { + auto opened = merovingian::database::open_persistent_store(); + REQUIRE(opened.ok); + auto& store = opened.store; + auto ids = std::vector{}; + for (auto index = 0; index < 300; ++index) + { + ids.push_back("client-" + std::to_string(index)); + REQUIRE(merovingian::database::store_oauth_client(store, client(ids.back(), 1U)) == + OAuthClientStoreResult::inserted); + } + REQUIRE(merovingian::database::store_oauth_client(store, client("client-held", 1U)) == + OAuthClientStoreResult::inserted); + REQUIRE(merovingian::database::store_device(store, {"@alice:example.org", "DEVA", ""})); + REQUIRE( + merovingian::database::store_oauth_session(store, session("@alice:example.org", "DEVA", "client-held"))); + + WHEN("sets naming the held client, an unknown client, or one client twice are offered") + { + auto const before = merovingian::database::committed_transaction_count(store); + auto const with_held = std::vector{"client-1", "client-held"}; + auto const with_unknown = std::vector{"client-1", "client-unknown"}; + auto const with_repeat = std::vector{"client-1", "client-1"}; + + THEN("each is refused whole and nothing is written") + { + REQUIRE_FALSE(merovingian::database::delete_oauth_clients(store, with_held)); + REQUIRE_FALSE(merovingian::database::delete_oauth_clients(store, with_unknown)); + REQUIRE_FALSE(merovingian::database::delete_oauth_clients(store, with_repeat)); + REQUIRE(merovingian::database::committed_transaction_count(store) == before); + REQUIRE(merovingian::database::oauth_client_count(store) == 301U); + } + } + + WHEN("the 300 sessionless clients are deleted, with the write forced to fail once first") + { + merovingian::database::force_next_persist_failures(store, 1U); + auto const failed = merovingian::database::delete_oauth_clients(store, ids); + auto const count_after_failure = merovingian::database::oauth_client_count(store); + auto const before = merovingian::database::committed_transaction_count(store); + auto const deleted = merovingian::database::delete_oauth_clients(store, ids); + + THEN("the failure changes nothing, and the delete is one transaction leaving only the held client") + { + REQUIRE_FALSE(failed); + REQUIRE(count_after_failure == 301U); + REQUIRE(deleted); + REQUIRE(merovingian::database::committed_transaction_count(store) - before == 1U); + REQUIRE(merovingian::database::oauth_client_count(store) == 1U); + REQUIRE(merovingian::database::find_oauth_client(store, "client-held") != nullptr); + REQUIRE(merovingian::database::oauth_clients_without_sessions(store, 10U, all_times).empty()); + } + } + } +} + +SCENARIO("An OAuth session is keyed by user and device, read through the user's index, and capped", + "[database][oauth][oauth-store]") +{ + GIVEN("a memory store holding one client") + { + auto opened = merovingian::database::open_persistent_store(); + REQUIRE(opened.ok); + auto& store = opened.store; + REQUIRE(merovingian::database::store_oauth_client(store, client("client-a", 1U)) == + OAuthClientStoreResult::inserted); + for (auto index = 0; index < 3; ++index) + { + REQUIRE(merovingian::database::store_oauth_session( + store, session("@alice:example.org", "DEV" + std::to_string(index), "client-a"))); + } + for (auto index = 0; index < 40; ++index) + { + REQUIRE(merovingian::database::store_oauth_session( + store, session("@bob:example.org", "DEV" + std::to_string(index), "client-a"))); + } + + WHEN("sessions are read and bad ones are prepared") + { + auto const examined_before = store.oauth.rows_examined(); + auto const alice = merovingian::database::oauth_sessions_of_user(store, "@alice:example.org"); + auto const examined = store.oauth.rows_examined() - examined_before; + auto over_scope = session("@alice:example.org", "DEVX", "client-a"); + over_scope.scope = std::string(merovingian::database::max_oauth_scope_bytes + 1U, 's'); + auto at_scope = session("@alice:example.org", "DEVY", "client-a"); + at_scope.scope = std::string(merovingian::database::max_oauth_scope_bytes, 's'); + + THEN("a user's sessions cost that user's rows, and every malformed or duplicate row is refused") + { + REQUIRE(alice.size() == 3U); + REQUIRE(examined == 3U); + auto const* found = merovingian::database::find_oauth_session(store, "@alice:example.org", "DEV1"); + REQUIRE(found != nullptr); + REQUIRE(found->client_id == "client-a"); + REQUIRE(merovingian::database::find_oauth_session(store, "@alice:example.org", "DEV9") == nullptr); + REQUIRE_FALSE(merovingian::database::prepare_oauth_session_insert(store, over_scope).has_value()); + REQUIRE(merovingian::database::prepare_oauth_session_insert(store, at_scope).has_value()); + REQUIRE_FALSE(merovingian::database::prepare_oauth_session_insert( + store, session("@alice:example.org", "DEV1", "client-a")) + .has_value()); + REQUIRE_FALSE(merovingian::database::prepare_oauth_session_insert( + store, session("@alice:example.org", "DEVZ", "client-unknown")) + .has_value()); + REQUIRE_FALSE( + merovingian::database::prepare_oauth_session_insert(store, session("", "DEVZ", "client-a")) + .has_value()); + REQUIRE_FALSE(merovingian::database::prepare_oauth_session_insert( + store, session("@alice:example.org", "", "client-a")) + .has_value()); + } + } + } +} + +SCENARIO("A session row is written in the caller's own transaction with its device and tokens", + "[database][oauth][oauth-store][composable]") +{ + GIVEN("a memory store holding a client and no device") + { + auto opened = merovingian::database::open_persistent_store(); + REQUIRE(opened.ok); + auto& store = opened.store; + REQUIRE(merovingian::database::store_oauth_client(store, client("client-a", 1U)) == + OAuthClientStoreResult::inserted); + auto const row = session("@alice:example.org", "DEVA", "client-a"); + + WHEN("the session statement joins a device insert in one transaction that fails, then one that commits") + { + auto const prepared = merovingian::database::prepare_oauth_session_insert(store, row); + REQUIRE(prepared.has_value()); + auto const device_insert = merovingian::database::PreparedStatement{ + "insert_device", + "INSERT INTO devices VALUES ($1, $2, $3)", + {{"@alice:example.org", false}, {"DEVA", false}, {"", false}} + }; + merovingian::database::force_persist_failure_for_statement(store, prepared->name); + auto const failed = merovingian::database::commit_persistent_transaction(store, {device_insert, *prepared}); + auto const absent_after_failure = + merovingian::database::find_oauth_session(store, "@alice:example.org", "DEVA") == nullptr; + auto const before = merovingian::database::committed_transaction_count(store); + auto const committed = + merovingian::database::commit_persistent_transaction(store, {device_insert, *prepared}); + auto const remembered = committed && merovingian::database::remember_oauth_session(store, row); + + THEN("memory takes the session only after the one commit") + { + REQUIRE_FALSE(failed); + REQUIRE(absent_after_failure); + REQUIRE(committed); + REQUIRE(merovingian::database::committed_transaction_count(store) - before == 1U); + REQUIRE(remembered); + REQUIRE(merovingian::database::oauth_client_has_session(store, "client-a")); + } + } + } +} + +SCENARIO("Deleting a device deletes its OAuth session in the same transaction", + "[database][oauth][oauth-store][device]") +{ + GIVEN("a memory store with alice's OAuth device and a second device of hers") + { + auto opened = merovingian::database::open_persistent_store(); + REQUIRE(opened.ok); + auto& store = opened.store; + REQUIRE(merovingian::database::store_oauth_client(store, client("client-a", 1U)) == + OAuthClientStoreResult::inserted); + REQUIRE(merovingian::database::store_device(store, {"@alice:example.org", "DEVA", ""})); + REQUIRE(merovingian::database::store_device(store, {"@alice:example.org", "DEVB", ""})); + REQUIRE(merovingian::database::store_oauth_session(store, session("@alice:example.org", "DEVA", "client-a"))); + REQUIRE(merovingian::database::store_oauth_session(store, session("@alice:example.org", "DEVB", "client-a"))); + + WHEN("the session delete in the device's transaction fails") + { + merovingian::database::force_persist_failure_for_statement(store, "delete_oauth_session_of_device"); + auto const deleted = merovingian::database::delete_device(store, "@alice:example.org", "DEVA"); + + THEN("the device and its session both stay") + { + REQUIRE_FALSE(deleted); + REQUIRE(merovingian::database::has_user_device(store, "@alice:example.org", "DEVA")); + REQUIRE(merovingian::database::find_oauth_session(store, "@alice:example.org", "DEVA") != nullptr); + } + } + + WHEN("the device is deleted") + { + auto const before = merovingian::database::committed_transaction_count(store); + auto const deleted = merovingian::database::delete_device(store, "@alice:example.org", "DEVA"); + + THEN("its session goes in the same one transaction and the other device keeps its session") + { + REQUIRE(deleted); + REQUIRE(merovingian::database::committed_transaction_count(store) - before == 1U); + REQUIRE_FALSE(merovingian::database::has_user_device(store, "@alice:example.org", "DEVA")); + REQUIRE(merovingian::database::find_oauth_session(store, "@alice:example.org", "DEVA") == nullptr); + REQUIRE(merovingian::database::find_oauth_session(store, "@alice:example.org", "DEVB") != nullptr); + REQUIRE(merovingian::database::oauth_client_has_session(store, "client-a")); + } + } + } +} + +SCENARIO("OAuth clients and sessions survive a SQLite reopen, and a device delete takes both rows or neither", + "[database][oauth][oauth-store][sqlite]") +{ + GIVEN("a SQLite store with a client, a touched last use, alice's OAuth device and a sessionless client") + { + auto const path = unique_sqlite_path("reopen"); + std::filesystem::remove(path); + { + auto opened = merovingian::database::open_sqlite_persistent_store(path.string()); + REQUIRE(opened.ok); + auto& store = opened.store; + REQUIRE(merovingian::database::store_oauth_client(store, client("client-a", 1U)) == + OAuthClientStoreResult::inserted); + REQUIRE(merovingian::database::store_oauth_client(store, client("client-idle", 2U)) == + OAuthClientStoreResult::inserted); + REQUIRE(merovingian::database::touch_oauth_client(store, "client-a", 3U * day_ms)); + REQUIRE(merovingian::database::store_device(store, {"@alice:example.org", "DEVA", ""})); + REQUIRE( + merovingian::database::store_oauth_session(store, session("@alice:example.org", "DEVA", "client-a"))); + } + + WHEN("it is reopened") + { + auto reopened = merovingian::database::open_sqlite_persistent_store(path.string()); + REQUIRE(reopened.ok); + auto const& store = reopened.store; + + THEN("both tables are hydrated with their values and the idle order") + { + auto const* held = merovingian::database::find_oauth_client(store, "client-a"); + REQUIRE(held != nullptr); + REQUIRE(held->last_used_at_ms == 3U * day_ms); + REQUIRE(held->created_at_ms == 1U); + REQUIRE(held->metadata_json == R"({"client_name":"Example"})"); + auto const* row = merovingian::database::find_oauth_session(store, "@alice:example.org", "DEVA"); + REQUIRE(row != nullptr); + REQUIRE(row->scope == "urn:matrix:client:api:*"); + REQUIRE(merovingian::database::oauth_clients_without_sessions(store, 10U, all_times) == + std::vector{"client-idle"}); + } + } + + WHEN("the database refuses the session delete inside the device's transaction") + { + REQUIRE(sqlite_run(path, "CREATE TRIGGER refuse_oauth_session_delete BEFORE DELETE ON oauth_sessions " + "BEGIN SELECT RAISE(ABORT, 'refused'); END")); + auto reopened = merovingian::database::open_sqlite_persistent_store(path.string()); + REQUIRE(reopened.ok); + auto const deleted = merovingian::database::delete_device(reopened.store, "@alice:example.org", "DEVA"); + REQUIRE(sqlite_run(path, "DROP TRIGGER refuse_oauth_session_delete")); + auto again = merovingian::database::open_sqlite_persistent_store(path.string()); + REQUIRE(again.ok); + + THEN("the device row stays with the session row, in memory and on disk") + { + REQUIRE_FALSE(deleted); + REQUIRE(merovingian::database::has_user_device(reopened.store, "@alice:example.org", "DEVA")); + REQUIRE(merovingian::database::find_oauth_session(reopened.store, "@alice:example.org", "DEVA") != + nullptr); + REQUIRE(merovingian::database::has_user_device(again.store, "@alice:example.org", "DEVA")); + REQUIRE(merovingian::database::find_oauth_session(again.store, "@alice:example.org", "DEVA") != + nullptr); + } + } + + WHEN("the device is deleted") + { + { + auto reopened = merovingian::database::open_sqlite_persistent_store(path.string()); + REQUIRE(reopened.ok); + REQUIRE(merovingian::database::delete_device(reopened.store, "@alice:example.org", "DEVA")); + } + auto again = merovingian::database::open_sqlite_persistent_store(path.string()); + REQUIRE(again.ok); + + THEN("the session row is gone from the file and its client is sessionless") + { + REQUIRE(merovingian::database::find_oauth_session(again.store, "@alice:example.org", "DEVA") == + nullptr); + REQUIRE_FALSE(merovingian::database::oauth_client_has_session(again.store, "client-a")); + } + } + std::filesystem::remove(path); + } +} diff --git a/tests/unit/test_database_persistence.cpp b/tests/unit/test_database_persistence.cpp index b0c8eed71..e844729cb 100644 --- a/tests/unit/test_database_persistence.cpp +++ b/tests/unit/test_database_persistence.cpp @@ -3,9 +3,12 @@ #include "../support/JoiningThreads.hpp" #include "../support/TempDirectory.hpp" #include "merovingian/database/BoundValue.hpp" +#include "merovingian/database/Connection.hpp" #include "merovingian/database/DatabaseExecutor.hpp" #include "merovingian/database/ExaminedRows.hpp" +#include "merovingian/database/Migration.hpp" #include "merovingian/database/MigrationDirection.hpp" +#include "merovingian/database/MigrationFiles.hpp" #include "merovingian/database/MigrationPlan.hpp" #include "merovingian/database/MigrationStep.hpp" #include "merovingian/database/PersistentAccountData.hpp" @@ -24,15 +27,12 @@ #include "merovingian/database/PersistentStore.hpp" #include "merovingian/database/PersistentStoreBackend.hpp" #include "merovingian/database/PostgresqlConnection.hpp" +#include "merovingian/database/PostgresqlStore.hpp" #include "merovingian/database/PreparedStatement.hpp" #include "merovingian/database/QueryResult.hpp" +#include "merovingian/database/Schema.hpp" #include "merovingian/database/SchemaState.hpp" #include "merovingian/database/SchemaTableDefinition.hpp" -#include "merovingian/database/Connection.hpp" -#include "merovingian/database/Migration.hpp" -#include "merovingian/database/MigrationFiles.hpp" -#include "merovingian/database/PostgresqlStore.hpp" -#include "merovingian/database/Schema.hpp" #include #include @@ -1332,7 +1332,7 @@ SCENARIO("Database migration plans are contiguous and direction-aware", "[databa } } -SCENARIO("Database migration runner applies the single v1 schema step and its explicit downgrade", +SCENARIO("Database migration runner applies the v1 and v2 schema steps and their explicit downgrades", "[database][migration]") { GIVEN("an empty schema state") @@ -1348,25 +1348,30 @@ SCENARIO("Database migration runner applies the single v1 schema step and its ex 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("one step builds the whole current schema at v1, and one step takes it away") + THEN("v1 then v2 build the whole current schema, and two steps take it away newest first") { - REQUIRE(merovingian::database::current_schema_version() == 1U); + REQUIRE(merovingian::database::current_schema_version() == 2U); REQUIRE(upgrade_plan.direction == merovingian::database::MigrationDirection::upgrade); REQUIRE(upgrade_plan.current_version == 0U); - REQUIRE(upgrade_plan.target_version == 1U); - REQUIRE(upgrade_plan.steps.size() == 1U); - REQUIRE(upgrade_plan.steps.front().version == 1U); - REQUIRE(upgrade_plan.steps.front().name == "initial_schema"); + REQUIRE(upgrade_plan.target_version == 2U); + REQUIRE(upgrade_plan.steps.size() == 2U); + 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(upgraded.ok); - REQUIRE(upgraded.state.version == 1U); - REQUIRE(upgraded.state.applied_migrations.size() == 1U); + REQUIRE(upgraded.state.version == 2U); + REQUIRE(upgraded.state.applied_migrations.size() == 2U); REQUIRE(upgraded.state.applied_migrations.front().name == "initial_schema"); + REQUIRE(upgraded.state.applied_migrations.back().name == "oauth_tables"); 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() == 1U); - REQUIRE(downgrade_plan.steps.front().name == "drop_initial_schema"); + REQUIRE(downgrade_plan.steps.size() == 2U); + REQUIRE(downgrade_plan.steps[0].name == "drop_oauth_tables"); + REQUIRE(downgrade_plan.steps[0].version == 1U); + REQUIRE(downgrade_plan.steps[1].name == "drop_initial_schema"); REQUIRE(downgraded.ok); REQUIRE(downgraded.state.version == 0U); REQUIRE(downgraded.state.tables.empty()); @@ -1377,10 +1382,10 @@ SCENARIO("Database migration runner applies the single v1 schema step and its ex SCENARIO("The v1 schema step creates every table in its final shape and every index", "[database][migration][collapse]") { - GIVEN("the v1 schema step and the current table inventory") + GIVEN("the v1 schema step and the v1 table inventory") { auto const step = merovingian::database::initial_schema_migration(); - auto const tables = merovingian::database::current_schema_definitions(); + auto const tables = merovingian::database::initial_schema_definitions(); WHEN("its statements are inspected") { @@ -1391,24 +1396,20 @@ SCENARIO("The v1 schema step creates every table in its final shape and every in return found == step.statements.end() ? std::string{} : found->sql; }; - THEN("each current table is created whole, by exactly the DDL the registry describes") + THEN("each v1 table is created whole, by exactly the DDL the registry describes") { - REQUIRE(merovingian::database::upgrade_migration_catalog().size() == 1U); - REQUIRE(merovingian::database::downgrade_migration_catalog().size() == 1U); + REQUIRE(merovingian::database::upgrade_migration_catalog().size() == 2U); + REQUIRE(merovingian::database::downgrade_migration_catalog().size() == 2U); for (auto const& table : tables) { INFO("table " << table.name); REQUIRE(statement_sql("create_" + std::string{table.name}) == merovingian::database::create_table_sql(table).value()); } - // The v1 step's own table set is the current one: nothing is left to a later step. - auto const initial = merovingian::database::initial_schema_definitions(); - REQUIRE(initial.size() == tables.size()); - for (auto index = std::size_t{0U}; index < tables.size(); ++index) - { - REQUIRE(initial[index].name == tables[index].name); - REQUIRE(initial[index].columns_sql == tables[index].columns_sql); - } + // v1 is frozen (ADR-0224): its table set is what version 1 adds, and no later table leaks into it. + REQUIRE(tables.size() == merovingian::database::schema_definitions_added_by(1U).size()); + REQUIRE(statement_sql("create_oauth_clients").empty()); + REQUIRE(statement_sql("create_oauth_sessions").empty()); } AND_THEN("every column the pre-1.0 chain ALTERed on is part of its table's CREATE") @@ -1471,6 +1472,60 @@ SCENARIO("The v1 schema step creates every table in its final shape and every in } } +SCENARIO("The v2 schema step adds only the OAuth 2.0 tables and their index", "[database][migration][oauth]") +{ + GIVEN("the v2 schema step, its downgrade and the current table inventory") + { + auto const step = merovingian::database::oauth_tables_migration(); + auto const downgrade = merovingian::database::downgrade_oauth_tables_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 oauth_clients, oauth_sessions and the client index, and nothing else") + { + REQUIRE(step.version == 2U); + REQUIRE(step.name == "oauth_tables"); + REQUIRE(step.direction == merovingian::database::MigrationDirection::upgrade); + REQUIRE(names == std::vector{"create_oauth_clients", "create_oauth_sessions", + "create_idx_oauth_sessions_client_id"}); + REQUIRE(step.statements[0].sql == + "CREATE TABLE \"oauth_clients\" (client_id TEXT PRIMARY KEY, metadata_json TEXT NOT NULL, " + "created_at_ms TEXT NOT NULL, last_used_at_ms TEXT NOT NULL)"); + REQUIRE(step.statements[1].sql == + "CREATE TABLE \"oauth_sessions\" (user_id TEXT NOT NULL, device_id TEXT NOT NULL, client_id " + "TEXT NOT NULL, scope TEXT NOT NULL, created_at_ms TEXT NOT NULL, PRIMARY KEY (user_id, " + "device_id))"); + REQUIRE(step.statements[2].sql == + "CREATE INDEX idx_oauth_sessions_client_id ON oauth_sessions (client_id)"); + REQUIRE(current.size() == initial.size() + 2U); + 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()); + } + + AND_THEN("its downgrade drops only those two tables, sessions first, back to version 1") + { + REQUIRE(downgrade.version == 1U); + REQUIRE(downgrade.name == "drop_oauth_tables"); + REQUIRE(downgrade.statements.size() == 2U); + REQUIRE(downgrade.statements[0].sql.find("oauth_sessions") != std::string::npos); + REQUIRE(downgrade.statements[1].sql.find("oauth_clients") != std::string::npos); + } + } + } +} + SCENARIO("A schema ledger naming a migration this build does not have is refused", "[database][migration][collapse][security]") { @@ -2324,10 +2379,9 @@ SCENARIO("Physical migration files load into validated migration plans", "[datab } } -// The checked-in file is the frozen record of v1. Once 1.0.0 ships it must -// never change, and neither may the step the build runs: a change to a table -// that breaks this scenario belongs in a new numbered migration instead. -SCENARIO("Checked-in migrations hold exactly the v1 step this build runs", "[database][migration][files]") +// The checked-in files are the frozen record of each step. v1 must never change once 1.0.0 shipped, nor 002 once +// 1.1.0 ships, and neither may the step the build runs: a change to a table belongs in a new numbered migration. +SCENARIO("Checked-in migrations hold exactly the steps this build runs", "[database][migration][files]") { GIVEN("the repository migration directory") { @@ -2337,28 +2391,70 @@ SCENARIO("Checked-in migrations hold exactly the v1 step this build runs", "[dat { REQUIRE_FALSE(directory.empty()); auto const loaded = merovingian::database::load_migration_files(directory.string()); - auto const built = merovingian::database::initial_schema_migration(); + auto const built = merovingian::database::upgrade_migration_catalog(); - THEN("there is one file, v1, statement for statement the same as the build's v1 step") + THEN("there is one file per catalog step, statement for statement the same as the build's step") { REQUIRE(loaded.ok); - REQUIRE(loaded.steps.size() == 1U); - auto const& file = loaded.steps.front(); - REQUIRE(file.version == 1U); - REQUIRE(file.name == built.name); - REQUIRE(file.direction == merovingian::database::MigrationDirection::upgrade); - REQUIRE(file.statements.size() == built.statements.size()); - for (auto index = std::size_t{0U}; index < built.statements.size(); ++index) + REQUIRE(loaded.steps.size() == built.size()); + REQUIRE(built.size() == merovingian::database::current_schema_version()); + for (auto step = std::size_t{0U}; step < built.size(); ++step) { - INFO("statement " << built.statements[index].name); - REQUIRE(file.statements[index].name == built.statements[index].name); - REQUIRE(file.statements[index].sql == built.statements[index].sql); + auto const& file = loaded.steps[step]; + INFO("step " << built[step].name); + REQUIRE(file.version == step + 1U); + REQUIRE(file.version == built[step].version); + REQUIRE(file.name == built[step].name); + REQUIRE(file.direction == merovingian::database::MigrationDirection::upgrade); + REQUIRE(file.statements.size() == built[step].statements.size()); + for (auto index = std::size_t{0U}; index < built[step].statements.size(); ++index) + { + INFO("statement " << built[step].statements[index].name); + REQUIRE(file.statements[index].name == built[step].statements[index].name); + REQUIRE(file.statements[index].sql == built[step].statements[index].sql); + } } } } } } +SCENARIO("An offline plan takes only the migration files between its two versions", + "[database][migration][files][oauth]") +{ + GIVEN("the repository migration directory and the migration role") + { + auto const directory = locate_repository_migrations_directory(); + REQUIRE_FALSE(directory.empty()); + auto const loaded = merovingian::database::load_migration_files(directory.string()); + REQUIRE(loaded.ok); + auto migration_config = merovingian::config::DatabaseConfig{}; + migration_config.role = merovingian::config::DatabaseRole::migration; + + WHEN("plans from v1 to v2 and from nothing to v2 are built from the files") + { + auto const from_v1 = + merovingian::database::build_offline_migration_plan(migration_config, 1U, 2U, loaded.steps); + auto const from_empty = + merovingian::database::build_offline_migration_plan(migration_config, 0U, 2U, loaded.steps); + auto const no_op = + merovingian::database::build_offline_migration_plan(migration_config, 2U, 2U, loaded.steps); + + THEN("a v1 database gets 002 alone, an empty one gets 001 then 002, and a v2 one gets nothing") + { + REQUIRE(from_v1.ok); + REQUIRE(from_v1.plan.steps.size() == 1U); + REQUIRE(from_v1.plan.steps.front().name == "oauth_tables"); + REQUIRE(from_empty.ok); + REQUIRE(from_empty.plan.steps.size() == 2U); + REQUIRE(from_empty.plan.steps.front().name == "initial_schema"); + REQUIRE(no_op.ok); + REQUIRE(no_op.plan.steps.empty()); + } + } + } +} + SCENARIO("Offline migrator plans require migration database role", "[database][migration][role]") { GIVEN("runtime and migration database roles") @@ -2405,11 +2501,11 @@ SCENARIO("Database schema inventory covers the core Matrix tables", "[database][ THEN("required Matrix storage areas have table-specific definitions") { - // Every table belongs to the v1 schema: the pre-1.0 migration chain - // collapsed into it, so the initial and current inventories match. + // The pre-1.0 migration chain collapsed into v1's 64 tables; migration 002 (1.1.0) adds the two + // OAuth 2.0 tables. REQUIRE(tables.size() == 64U); - REQUIRE(merovingian::database::current_schema_version() == 1U); - REQUIRE(merovingian::database::current_schema_tables().size() == 64U); + REQUIRE(merovingian::database::current_schema_version() == 2U); + REQUIRE(merovingian::database::current_schema_tables().size() == 66U); REQUIRE(users_definition.has_value()); REQUIRE(current_state_definition.has_value()); REQUIRE(room_aliases_definition.has_value()); diff --git a/tests/unit/test_worker_table_load_profile.cpp b/tests/unit/test_worker_table_load_profile.cpp index dd6a0dd23..8846104eb 100644 --- a/tests/unit/test_worker_table_load_profile.cpp +++ b/tests/unit/test_worker_table_load_profile.cpp @@ -198,6 +198,10 @@ namespace // ADR-0212: mxc:// URIs reserved by POST /_matrix/media/v1/create. // The client API and the federation media download run in main. "media_pending_uploads", + // ADR-0776: OAuth 2.0 client registrations and sessions (migration 002). Every OAuth 2.0 endpoint and the + // token checks run in main; the worker serves no client API. + "oauth_clients", + "oauth_sessions", // 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 @@ -268,6 +272,8 @@ SCENARIO("The federation_worker load profile excludes every table outside the al REQUIRE_FALSE(merovingian::database::table_load_profile_includes("login_tokens", profile)); REQUIRE_FALSE(merovingian::database::table_load_profile_includes("openid_tokens", profile)); REQUIRE_FALSE(merovingian::database::table_load_profile_includes("account_threepids", profile)); + REQUIRE_FALSE(merovingian::database::table_load_profile_includes("oauth_clients", profile)); + REQUIRE_FALSE(merovingian::database::table_load_profile_includes("oauth_sessions", profile)); } AND_THEN("an arbitrary non-allowlisted table is excluded, proving this is a fail-closed allowlist " "rather than a denylist") From 6059cd26477526240dd6f25766d712004db087cb Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 03:13:42 +0000 Subject: [PATCH 11/42] Serve OAuth 2.0 client registration at /_merovingian/oauth2/register (ADR-0779 to ADR-0781) POST /_merovingian/oauth2/register validates RFC 7591 client metadata and answers 201 with a client ID that is a keyed BLAKE2b hash of the canonical metadata, under a master-key-derived key with its own label, so a repeat registration is the same row and costs no commit within a day. At most 10000 clients are held: at the cap up to 8 idle clients without a session or pending authorisation are evicted, least recently used first, else 503 temporarily_unavailable. Every OAuth answer comes from one helper with application/json and no-store. /_merovingian/oauth2/* and /_merovingian/account* take the auth_sensitive tier, and 201 has its reason phrase. Co-Authored-By: Claude Opus 5.5 --- .../references/module-invariants.md | 3 + CHANGELOG.md | 9 +- ...s-a-keyed-hash-of-the-accepted-metadata.md | 60 +++ ...s-are-evicted-least-recently-used-first.md | 58 +++ ...th-errors-with-no-store-from-one-helper.md | 54 +++ docs/adr/index.md | 3 + docs/auth-identity.md | 24 +- docs/crypto-boundary.md | 5 + docs/http-transport.md | 15 +- docs/log-filtering.md | 1 + docs/matrix-v1.19-client-server-api.md | 2 +- docs/observability-audit.md | 11 + docs/security-coding-rules.md | 10 +- docs/user-manual.md | 7 +- include/merovingian/crypto/OAuthClientId.hpp | 26 ++ include/merovingian/crypto/TokenHmacKeys.hpp | 4 +- include/merovingian/crypto/TokenKey.hpp | 9 +- .../homeserver/ClientApiLimits.hpp | 5 + .../homeserver/HomeserverRuntime.hpp | 4 + .../homeserver/OAuthClientRegistration.hpp | 63 +++ .../homeserver/OAuthJsonResponse.hpp | 28 ++ .../merovingian/homeserver/RetentionSweep.hpp | 5 +- include/merovingian/oauth/OAuthErrorCodes.hpp | 4 + src/crypto/AGENTS.md | 3 +- src/crypto/OAuthClientId.cpp | 36 ++ src/crypto/TokenKey.cpp | 15 +- src/crypto/meson.build | 1 + src/homeserver/AGENTS.md | 14 + src/homeserver/ClientServerRuntime.cpp | 27 ++ src/homeserver/OAuthClientRegistration.cpp | 323 +++++++++++++++ src/homeserver/OAuthJsonResponse.cpp | 51 +++ src/homeserver/RetentionSweep.cpp | 8 +- src/homeserver/meson.build | 2 + src/http/RateLimit.cpp | 5 +- src/http/ResponseHead.cpp | 2 + tests/conformance/AGENTS.md | 1 + ..._oauth_client_registration_conformance.cpp | 378 ++++++++++++++++++ .../test_route_query_conformance.cpp | 9 +- .../test_oauth_client_registration_flow.cpp | 355 ++++++++++++++++ tests/meson.build | 3 + tests/support/AGENTS.md | 1 + tests/support/OAuthRegistrationSupport.hpp | 73 ++++ tests/unit/test_crypto_oauth_client_id.cpp | 116 ++++++ tests/unit/test_http_rate_limit_tiers.cpp | 6 + tests/unit/test_http_response_head.cpp | 1 + 45 files changed, 1818 insertions(+), 22 deletions(-) create mode 100644 docs/adr/0779-an-oauth-client-id-is-a-keyed-hash-of-the-accepted-metadata.md create mode 100644 docs/adr/0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md create mode 100644 docs/adr/0781-oauth-endpoints-answer-oauth-errors-with-no-store-from-one-helper.md create mode 100644 include/merovingian/crypto/OAuthClientId.hpp create mode 100644 include/merovingian/homeserver/OAuthClientRegistration.hpp create mode 100644 include/merovingian/homeserver/OAuthJsonResponse.hpp create mode 100644 src/crypto/OAuthClientId.cpp create mode 100644 src/homeserver/OAuthClientRegistration.cpp create mode 100644 src/homeserver/OAuthJsonResponse.cpp create mode 100644 tests/conformance/test_oauth_client_registration_conformance.cpp create mode 100644 tests/integration/test_oauth_client_registration_flow.cpp create mode 100644 tests/support/OAuthRegistrationSupport.hpp create mode 100644 tests/unit/test_crypto_oauth_client_id.cpp diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index a472753b8..d4ddde8f7 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -181,6 +181,9 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that secret into an owned `SecretBuffer` first. `src/homeserver/AGENTS.md#The runtime lock and blocking calls` - Work under the lock is linear in request input. Per-user row counts are capped with the documented errcodes: `400 M_TOO_LARGE` (ADR-0173). `#Work under the runtime lock is bounded by the request` +- OAuth answers come from `oauth_json_response` / `oauth_error_response`; client IDs only from `oauth_client_id_of`; + registrations are capped and never evict a client with a session (ADR-0779 to ADR-0781). + `src/homeserver/AGENTS.md#OAuth 2.0 API (ADR-0760, ADR-0773)` - Worker frames are untrusted. Relayed PDUs are re-verified with main's resolver **before** taking `runtime.mutex`, and the envelope is rebuilt from the verified event (ADR-0171). `#Federation worker relays are untrusted input` diff --git a/CHANGELOG.md b/CHANGELOG.md index 58782b726..d1fe8b2e8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -27,6 +27,11 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) deletes its OAuth session in the same transaction (ADR-0776, ADR-0778). * The retention sweep deletes OAuth clients with no session unused for 30 days, never one with a session, and a client's last use is written at most once a day (ADR-0777). +* `POST /_merovingian/oauth2/register` registers OAuth 2.0 clients (RFC 7591); the client ID is a keyed hash of the + accepted metadata, so a repeat registration is the same client (ADR-0779, ADR-0781). +* At most 10000 OAuth clients are held: at the cap idle ones go least recently used first, else 503 (ADR-0780). +* `/_merovingian/oauth2/*` and `/_merovingian/account*` take the `auth_sensitive` rate limit; `201 Created` has its + reason phrase. ## Security Fixes @@ -43,8 +48,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Release notes 1.1.0 is in development. A configuration that sets any `server.oidc.*` key is now refused at start-up: remove those -keys and set `server.oauth.enabled` instead (ADR-0764). The metadata names the authorisation, token, registration and -revocation endpoints, which later 1.1.0 changes serve; leave `server.oauth.enabled` off until then. 1.1.0 migrates +keys and set `server.oauth.enabled` instead (ADR-0764). The metadata names the authorisation, token and revocation endpoints, +which later 1.1.0 changes serve (registration is served now); leave `server.oauth.enabled` off until then. 1.1.0 migrates the database: on first start it applies migration 002, which adds two empty tables and changes no existing one. A 1.0.x server refuses the migrated database, so back it up before upgrading if you may need to go back. diff --git a/docs/adr/0779-an-oauth-client-id-is-a-keyed-hash-of-the-accepted-metadata.md b/docs/adr/0779-an-oauth-client-id-is-a-keyed-hash-of-the-accepted-metadata.md new file mode 100644 index 000000000..1eb59fa7a --- /dev/null +++ b/docs/adr/0779-an-oauth-client-id-is-a-keyed-hash-of-the-accepted-metadata.md @@ -0,0 +1,60 @@ +# An OAuth client ID is a keyed hash of the accepted metadata + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 4 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), proposal P2 + +## Context and Problem Statement + +`POST /_merovingian/oauth2/register` is unauthenticated (the spec: "Client registration"), and a client may register +again on every start. Each registration that makes a row costs storage and counts against the registration cap +(ADR-0780). What client ID does a registration get? + +## Decision Drivers + +* A client that registers again with the same metadata must not cost a new row, or one app's restarts fill the table. +* An ID must not let anyone who knows a client's metadata predict its ID on this server without the server's key, so + IDs of one server say nothing about another and cannot be precomputed against a leaked metadata list. +* The ID travels in a query string, a form body and a log line: it must need no escaping in any of them and fit + `database::max_oauth_client_id_bytes` (128). + +## Considered Options + +* A keyed hash of `ClientMetadata::canonical_bytes()`. +* A random ID per registration. +* An unkeyed hash of the canonical metadata. + +## Decision Outcome + +Chosen option: a keyed hash. The ID is the unpadded URL-safe base64 of the 32-byte keyed BLAKE2b digest of the +canonical metadata (`crypto::oauth_client_id`, 43 characters of `A-Z a-z 0-9 - _`). The key is derived from the master +key with its own label, `merovingian:oauth-client-id:1` (`crypto::derive_oauth_client_id_key`), the way the access-token +keys are, and is cached with them in `TokenHmacKeys` from one read of the master key file. Canonical bytes make the +ID independent of key order, repeated list entries and ignored members, so a repeat registration finds its row and only +touches its last use (at most one write a day, ADR-0777). + +### Positive Consequences + +* A client's restarts cost no row and, within a day, no commit. +* A client ID cannot be computed without the master key, and changing the master key changes every ID. + +### Negative Consequences + +* Two installs of one app with identical metadata share a client ID. Nothing in the API binds a secret to it + (`token_endpoint_auth_method` is `none`), so the shared ID gives neither install anything over the other. +* Replacing the master key orphans every registered client; clients register again, as the spec allows. + +## Pros and Cons of the Options + +### A random ID per registration + +* Good, because the ID reveals nothing about the metadata. +* Bad, because every restart of every client makes a row, so the cap is reached by ordinary use and eviction becomes + routine instead of the exception. + +### An unkeyed hash + +* Good, because it needs no key. +* Bad, because anyone can compute a client's ID from its metadata, the same on every server. diff --git a/docs/adr/0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md b/docs/adr/0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md new file mode 100644 index 000000000..65b543449 --- /dev/null +++ b/docs/adr/0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md @@ -0,0 +1,58 @@ +# OAuth registrations are capped, and idle clients are evicted least recently used first + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 4 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +Client registration is unauthenticated. The `auth_sensitive` rate limit bounds one address, but many addresses can +still register distinct metadata, each a row of up to 16 KiB held in memory and in the database. The spec says "The +server MUST NOT delete client registrations that have an active session". How is the number of clients bounded? + +## Decision Drivers + +* Memory and database rows must stay bounded whatever unauthenticated callers send. +* A client with a session, or one in the middle of an authorisation, must never be deleted. +* Work under `runtime.mutex` per registration must be bounded. + +## Considered Options + +* A cap (`ClientApiLimits::max_oauth_clients`, 10000) at which a registration evicts least-recently-used clients with + no session and no pending authorisation, at most `max_oauth_client_evictions_per_registration` (8), and otherwise + answers `503 temporarily_unavailable` and stores nothing. +* A cap that refuses every new registration once reached. +* No cap, relying on the 30-day retention sweep. + +## Decision Outcome + +Chosen option: cap with bounded eviction. `make_room_for_a_client` (`OAuthClientRegistration.cpp`) counts the rows, +and at the cap asks `oauth_clients_without_sessions` for the oldest sessionless clients, skipping those +`oauth_client_has_pending_authorisation` names, and deletes them in one transaction. A client with a session is not a +candidate and `delete_oauth_clients` refuses one. A repeat registration of a held client is answered without eviction. +The cap is a field so tests can lower it; it is not configurable. + +### Positive Consequences + +* At most 10000 clients are held, whatever is sent. +* An attacker filling the table evicts only other idle registrations, which register again for free (ADR-0779). + +### Negative Consequences + +* A flood can evict a legitimate client between registration and authorisation start. The client registers again. +* With every held client protected, new clients get 503 until sessions end or the sweep runs. Accepted: the + alternative breaks the spec's MUST NOT. + +## Pros and Cons of the Options + +### Refuse at the cap + +* Good, because nothing is ever evicted. +* Bad, because one flood shuts registration for 30 days, until the sweep. + +### No cap + +* Good, because nothing is refused. +* Bad, because memory grows without bound for 30 days at the rate limit times the number of addresses. diff --git a/docs/adr/0781-oauth-endpoints-answer-oauth-errors-with-no-store-from-one-helper.md b/docs/adr/0781-oauth-endpoints-answer-oauth-errors-with-no-store-from-one-helper.md new file mode 100644 index 000000000..c1cac3555 --- /dev/null +++ b/docs/adr/0781-oauth-endpoints-answer-oauth-errors-with-no-store-from-one-helper.md @@ -0,0 +1,54 @@ +# OAuth endpoints answer OAuth errors with no-store, from one helper + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 4 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +The OAuth endpoints under `/_merovingian/oauth2/` speak OAuth (RFC 6749 section 5.2, RFC 7591 section 3.2.2), whose +error body is `{"error", "error_description"}`, not the Matrix `{"errcode", "error"}`. The dispatcher's gates in front of +the handlers answer Matrix errors. Which shape does each answer take, and where is it built? + +## Decision Drivers + +* An OAuth client reads `error`; a Matrix error body means nothing to it. +* Token and registration answers must not be cached (`Cache-Control: no-store`). +* Phases 6 and 7 add more endpoints; their errors must not each be built by hand. + +## Considered Options + +* One helper, `oauth_error_response` (`OAuthJsonResponse.cpp`), builds every OAuth error from an `OAuthRefusal`, with + `application/json` and `no-store`; `oauth_json_response` builds every OAuth success the same way. The general body + cap answers the registration path with `400 invalid_client_metadata`. The gates that judge the request before its + route (the not-started 503, the 429 rate limit, the 405 and the 404 with OAuth off) stay Matrix-shaped. +* Matrix errors everywhere. +* Each handler builds its own JSON. + +## Decision Outcome + +Chosen option: the one helper. A body over `max_body_bytes` on the registration path is metadata the server will not +accept, which RFC 7591 names `invalid_client_metadata`, so it is answered by the handler instead of `413 M_TOO_LARGE`. +The 429 is the same for every route and its `Retry-After` is what a client acts on, so it stays shared. + +### Positive Consequences + +* One place sets the content type and `no-store` for every OAuth answer. + +### Negative Consequences + +* A client can see a Matrix-shaped 429, 405 or 404 from an OAuth path. These are transport answers a generic HTTP + client handles by status. + +## Pros and Cons of the Options + +### Matrix errors everywhere + +* Good, because one error shape. +* Bad, because OAuth clients do not read `errcode`, so refusals look like unknown failures. + +### Each handler builds its own JSON + +* Bad, because a missed `no-store` or content type would go unnoticed. diff --git a/docs/adr/index.md b/docs/adr/index.md index 01031ad36..2c811cc1e 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -660,3 +660,6 @@ * [0776 - An OAuth session is a row keyed by user and device, and the token tables do not change](0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md) * [0777 - An OAuth client's last use is written at most once a day](0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md) * [0778 - The schema is built from per-version tables, and each migration step from what its version adds](0778-the-schema-is-built-from-per-version-tables-and-each-migration-step-from-what-its-version-adds.md) +* [0779 - An OAuth client ID is a keyed hash of the accepted metadata](0779-an-oauth-client-id-is-a-keyed-hash-of-the-accepted-metadata.md) +* [0780 - OAuth registrations are capped, and idle clients are evicted least recently used first](0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md) +* [0781 - OAuth endpoints answer OAuth errors with no-store, from one helper](0781-oauth-endpoints-answer-oauth-errors-with-no-store-from-one-helper.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 7879e134c..dbe8c8c0c 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -156,7 +156,7 @@ production-gated. (issue #437), had no caller and was removed. - Client-server auth/device/key actions append durable audit rows without logging plaintext credentials, bearer tokens, or key payloads. -- `GET /_matrix/client/v1/auth_metadata` (and its MSC2965 unstable path) returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. `oauth::server_metadata` builds the document and every address in it comes from `oauth::OAuthBaseUrl`: the issuer is `server.public_baseurl` with one trailing slash and the endpoints sit under `/_merovingian/oauth2/` (ADR-0773). The endpoint is unauthenticated, carries CORS headers and stays in the generic rate-limit tier (ADR-0775). The authorization, token, registration and revocation endpoints it names are not served yet; they land in later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). The former `server.oidc.*` keys are refused at start-up. +- `GET /_matrix/client/v1/auth_metadata` (and its MSC2965 unstable path) returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. `oauth::server_metadata` builds the document and every address in it comes from `oauth::OAuthBaseUrl`: the issuer is `server.public_baseurl` with one trailing slash and the endpoints sit under `/_merovingian/oauth2/` (ADR-0773). The endpoint is unauthenticated, carries CORS headers and stays in the generic rate-limit tier (ADR-0775). The registration endpoint is served (see "OAuth 2.0 client registration" below); the authorization, token and revocation endpoints it names are not served yet; they land in later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). The former `server.oidc.*` keys are refused at start-up. - **Application Service API identity (Matrix v1.19, `merovingian::appservice`).** Registration files (`appservice.registration_files`, parsed as JSON) build an in-memory `AppserviceRegistry` at startup in the main process only (the federation worker @@ -1077,6 +1077,28 @@ The built-in OAuth 2.0 API ([ADR-0760](adr/0760-the-oauth-2-0-api-is-built-into- Neither table is read by the federation worker. +## OAuth 2.0 client registration + +`POST /_merovingian/oauth2/register` (spec "Client registration", RFC 7591) is served while `server.oauth.enabled` is +true, without authentication, by `register_oauth_client` (`homeserver/OAuthClientRegistration.cpp`) under +`runtime.mutex`, with no network call: + +- The body must be `application/json` (a `charset=utf-8` parameter is allowed), at most 16 KiB, and valid JSON; + otherwise `400 invalid_client_metadata`. `oauth::ClientMetadata::validate` judges it; a refusal is a 400 with its + code (`invalid_redirect_uri` or `invalid_client_metadata`). +- The client ID is a keyed BLAKE2b hash of the canonical metadata, under a key derived from the master key with its + own label, as 43 URL-safe base64 characters (ADR-0779). The same metadata in any key order, with repeated list + entries or ignored members, is the same client: a repeat finds its row and only touches its last use. +- The answer is `201` with `client_id`, `client_id_issued_at` (seconds, the row's first registration) and every + registered value of `ClientMetadata::to_json()`, with `Cache-Control: no-store`. Locale-tagged values and + `logo_uri` are not registered and not echoed. +- At most 10000 clients are held (`ClientApiLimits::max_oauth_clients`). At the cap a new client evicts up to 8 + least-recently-used clients that have no session and no pending authorisation; if that is not enough it is + `503 temporarily_unavailable` and nothing is stored (ADR-0780). A client with a session is never deleted. +- Errors are `{"error", "error_description"}` from `oauth_error_response` (ADR-0781). +- `find_registered_oauth_client` reads a client back for later phases: unknown, unparsable or no longer valid metadata + is "no client"; a row that fails validation is logged without its content. + ## Next starting points 1. Preserve the reviewed libsodium boundary for random token generation and password hashing as auth flows expand. diff --git a/docs/crypto-boundary.md b/docs/crypto-boundary.md index 7ea8a27d3..db4d78283 100644 --- a/docs/crypto-boundary.md +++ b/docs/crypto-boundary.md @@ -118,6 +118,11 @@ implementing custom cryptographic primitives. other key is derived from is actually materialised in process memory, and removes the concurrent `mlock` churn that could exhaust `RLIMIT_MEMLOCK` under load. +- **The OAuth 2.0 client ID key** (`derive_oauth_client_id_key`, label `merovingian:oauth-client-id:1`) is derived + from the master key like the access-token keys and cached beside them in `TokenHmacKeys` from the same read; the + cache fails closed if any of the three cannot be derived. `oauth_client_id` (`OAuthClientId.cpp`) is the keyed + BLAKE2b-256 of the canonical client metadata, as unpadded URL-safe base64 (ADR-0779). The key is used for nothing + else. - **Master-key lock failure is fatal.** The secure-file reader rejects an unlocked `SecretBuffer` before returning material to `crypto::load_master_key_material()`; the loader also has a defensive lock diff --git a/docs/http-transport.md b/docs/http-transport.md index fc307f2fb..3bf3809c1 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -800,7 +800,7 @@ cap applies regardless of which room, device, or media ID appears in the URL. | Tier | Routes | Default per-IP policy | | --- | --- | --- | -| `auth_sensitive` | `/login`, `/register`, `/refresh`, and every `*/requestToken` route (matched by suffix) — unauthenticated, so the per-IP bucket is the only defense | 20/60s | +| `auth_sensitive` | `/login`, `/register`, `/refresh`, every `*/requestToken` route (matched by suffix), `/_merovingian/oauth2/*` and `/_merovingian/account*` — unauthenticated, so the per-IP bucket is the only defense | 20/60s | | `media` | `/_matrix/media/*` and `/_matrix/client/v1/media/*` | 120/60s; thumbnail refinement 240/60s | | `sync` | `/sync` plus the MSC4186 and simplified MSC3575 sliding-sync long-polls | 3000/60s | | `federation` | `/_matrix/federation/*` routes reaching the client-server dispatcher | 3000/60s | @@ -948,6 +948,19 @@ listener: `200` with the body `ok` while the dispatcher is running, `503` with ` needs no token, is not rate-limited, reads one atomic flag and takes no lock (not `runtime.mutex`), so a long request cannot delay it. It says nothing of the database or the federation worker; `/_merovingian/admin/health` does. +### OAuth 2.0 routes (ADR-0779 to ADR-0781) + +`POST /_merovingian/oauth2/register` goes through the client-server dispatcher like any route: a `static_routes` entry +gives it its own rate-limit bucket, in the `auth_sensitive` tier (as do the later `/_merovingian/oauth2/*` and +`/_merovingian/account*` paths), and a `client_static_route_allow` row answers any other method `405` with +`Allow: POST`. It is answered before the authentication gate. `OPTIONS` is answered for it as for every path, and +CORS headers are added at the same single boundary, so it carries exactly those of `/login`. The Matrix `M_NOT_JSON` +gate covers only `/_matrix/client/`; the handler judges the JSON content type itself. A body over `max_body_bytes` +on this path is answered `400 invalid_client_metadata` by the handler instead of `413 M_TOO_LARGE`; one over the +transport's own body cap is still refused by the connection handler. With `server.oauth.enabled` off the route is +`404 M_UNRECOGNIZED`. Every OAuth answer is built by `oauth_json_response` or `oauth_error_response` +(`application/json`, `Cache-Control: no-store`); the 429, 405, 404 and not-started 503 stay Matrix-shaped. + ### Admin routes `/_merovingian/admin/*` (health, metrics, audit, accounts, review, media moderation) is served on diff --git a/docs/log-filtering.md b/docs/log-filtering.md index 687c1ea26..2176d309e 100644 --- a/docs/log-filtering.md +++ b/docs/log-filtering.md @@ -132,6 +132,7 @@ used as the first argument to `observability::log_diagnostic` and `log_diagnosti | `sync_notifier` | Sync stream publish, change wake-up and long-poll timeout | | `stream_token_epoch` | The database's sync token epoch: created at first start, replaced by `--after-restore`, or refused | | `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 | 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 2e1a5ec46..94d06efdb 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -393,7 +393,7 @@ lists have no server maximum (ADR-0332). | --- | --- | --- | --- | --- | --- | | `GET` | `/_matrix/client/v1/auth_metadata` | `getAuthMetadata` | none | - | 200, 404 | -Implemented: returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. The MSC2965 path `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answers the same. The endpoints the document names are served from later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). +Implemented: returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. The MSC2965 path `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answers the same. Its registration endpoint, `POST /_merovingian/oauth2/register` (spec "Client registration"), is served: unauthenticated, `201` with the client ID and the registered metadata, RFC 7591 errors (ADR-0779 to ADR-0781). The other endpoints the document names are served from later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). | `POST` | `/_matrix/client/v1/login/get_token` | `generateLoginToken` | access token | required application/json | 200, 400, 401, 429 | | `GET` | `/_matrix/client/v3/account/whoami` | `getTokenOwner` | access token | - | 200, 401, 403, 429 | | `GET` | `/_matrix/client/v3/login` | `getLoginFlows` | none | - | 200, 404, 429 | diff --git a/docs/observability-audit.md b/docs/observability-audit.md index aac49d590..16146e9b2 100644 --- a/docs/observability-audit.md +++ b/docs/observability-audit.md @@ -541,6 +541,17 @@ and is never persisted. Its connection identifier data is limited to presence and byte length, and it contains no request bodies, tokens, event content, or encryption material. +## OAuth 2.0 client registration diagnostics (ADR-0779, ADR-0780) + +`POST /_merovingian/oauth2/register` logs under the `oauth` module with the fields `client_id`, `application_type` +and `client_host` (the host of `client_uri`) only, never the request body or any other metadata value: +`oauth.client.registered` (info, a new row), `oauth.client.registered_again` (debug, a held client), +`oauth.client.evicted` (info, idle clients removed at the cap, with `clients` and `limit` in place of the client fields), `oauth.client.cap_reached` (warning, a +503), and `oauth.client.store_failed` and `oauth.client.touch_failed` (warning). A stored row that no longer +validates is logged as `oauth.client.stored_metadata_refused` (warning, `client_id` only) each time it is read. +Registration writes no audit row: it is unauthenticated, grants nothing, and is bounded by the `auth_sensitive` rate +limit, whose 429s are audited as `rate_limit.exceeded`. + ## Outbound client request diagnostics (F-76, ADR-0418) `http::OutboundClient::perform` logs one debug line per request under the `outbound_client` module: diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index caabc3a5e..9196f6822 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1025,6 +1025,14 @@ quickly finding everything a given `AGENTS.md` file contributed. much of a guess matched (CWE-208). Source: `src/oauth/AGENTS.md`. +- **A client ID is only ever the keyed hash of the accepted metadata (`oauth_client_id_of`), and the number of + registrations is capped: at the cap only idle clients without a session or pending authorisation are evicted, a + bounded number per request, else 503 with nothing stored. Registration logs the client ID, application type and + client host, never the body.** + Why: registration is unauthenticated, so without the cap rows grow without bound (CWE-770); deleting a client in + use breaks the spec's MUST NOT; the body is attacker-chosen text (CWE-117) (ADR-0779, ADR-0780). + Source: `src/homeserver/AGENTS.md`. + ## HTTP and network boundary - **Rate limiting is applied before any auth check.** Do not move it after auth. @@ -1895,7 +1903,7 @@ For finding everything a specific file contributed, without re-reading the whole | `src/http/AGENTS.md` | HTTP and network boundary | | `src/net/AGENTS.md` | Memory safety; HTTP and network boundary | | `src/oauth/AGENTS.md` | OAuth 2.0 API | -| `src/homeserver/AGENTS.md` | Authentication and authorization; HTTP and network boundary; Federation; Media; Sync | +| `src/homeserver/AGENTS.md` | Authentication and authorization; OAuth 2.0 API; HTTP and network boundary; Federation; Media; Sync | | `src/media/AGENTS.md` | HTTP and network boundary; Media | | `src/database/AGENTS.md` | Database | | `migrations/AGENTS.md` | Database | diff --git a/docs/user-manual.md b/docs/user-manual.md index ba2fe206e..869e20f24 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -830,8 +830,11 @@ homeserver serves. It is **off by default**: `GET /_matrix/client/v1/auth_metada and its unstable form `GET /_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answer `404 M_UNRECOGNIZED`, as the spec asks of a server without the API. With `server.oauth.enabled=true` both answer the server metadata. In 1.1.0 the API -is being built in phases; this release serves the metadata, and the endpoints it -names follow. Until they do, a client that follows the metadata cannot log in, +is being built in phases; this release serves the metadata and client +registration (`POST /_merovingian/oauth2/register`), and the other endpoints it +names follow. At most 10000 client registrations are held; once every held one +is in use, a new client is answered `503 temporarily_unavailable` until one is +freed. Until they do, a client that follows the metadata cannot log in, so leave the API off. No address is configured. The issuer is `server.public_baseurl` with one diff --git a/include/merovingian/crypto/OAuthClientId.hpp b/include/merovingian/crypto/OAuthClientId.hpp new file mode 100644 index 000000000..f8dd384a8 --- /dev/null +++ b/include/merovingian/crypto/OAuthClientId.hpp @@ -0,0 +1,26 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/crypto/TokenHmacKey.hpp" + +#include +#include +#include +#include + +namespace merovingian::crypto +{ + +// The length of every OAuth 2.0 client ID: a 32-byte BLAKE2b digest in unpadded URL-safe base64. +inline constexpr auto oauth_client_id_chars = std::size_t{43U}; + +// The OAuth 2.0 client ID of the accepted client metadata `canonical_metadata` (oauth::ClientMetadata::canonical_bytes, +// plan P2, ADR-0779): BLAKE2b-256 keyed with `key` (derive_oauth_client_id_key), in unpadded URL-safe base64, so +// exactly `oauth_client_id_chars` characters of A-Z a-z 0-9 - _, safe in a form field, a URL query and a log line. +// The same metadata and key always give the same ID; without the key no one can compute the ID of given metadata. +// nullopt only when libsodium fails. +[[nodiscard]] auto oauth_client_id(std::string_view canonical_metadata, TokenHmacKey const& key) + -> std::optional; + +} // namespace merovingian::crypto diff --git a/include/merovingian/crypto/TokenHmacKeys.hpp b/include/merovingian/crypto/TokenHmacKeys.hpp index 5efafbebf..4808c7954 100644 --- a/include/merovingian/crypto/TokenHmacKeys.hpp +++ b/include/merovingian/crypto/TokenHmacKeys.hpp @@ -9,11 +9,13 @@ namespace merovingian::crypto { -// Both access-token HMAC keys, derived together from one read of the master key. +// Both access-token HMAC keys and the OAuth 2.0 client ID key, derived together from one read of the master key. struct TokenHmacKeys final { std::optional v3{}; std::optional v4{}; + // The key of crypto::oauth_client_id (ADR-0779), never used to hash a token. + std::optional oauth_client_id{}; }; } // namespace merovingian::crypto diff --git a/include/merovingian/crypto/TokenKey.hpp b/include/merovingian/crypto/TokenKey.hpp index 51aa2b45a..8ca5c14ac 100644 --- a/include/merovingian/crypto/TokenKey.hpp +++ b/include/merovingian/crypto/TokenKey.hpp @@ -35,9 +35,16 @@ namespace merovingian::crypto [[nodiscard]] auto derive_token_hmac_key_v3(std::span master_key_material) noexcept -> std::optional; +// Derive the key of the OAuth 2.0 client ID hash (plan P2, ADR-0779) from master key material, with a +// domain-separation label of its own, so it is independent of both access-token keys and of every other derived +// key. The same material always gives the same key, so a client keeps its ID across restarts. Returns nullopt if +// libsodium is not initialised or the material is empty. +[[nodiscard]] auto derive_oauth_client_id_key(std::span master_key_material) noexcept + -> std::optional; + static_assert(SecureKeyBytes::key_bytes == crypto_generichash_KEYBYTES); -// The token HMAC keys derived from the master key file at `path`, cached +// The token HMAC keys (and the OAuth 2.0 client ID key) derived from the master key file at `path`, cached // against that file's identity (ISO-7: identity and bytes from one open). // // CRY-4, PR #509 review: these keys are on every authenticated request's path. diff --git a/include/merovingian/homeserver/ClientApiLimits.hpp b/include/merovingian/homeserver/ClientApiLimits.hpp index 76f24100f..6abdbcee7 100644 --- a/include/merovingian/homeserver/ClientApiLimits.hpp +++ b/include/merovingian/homeserver/ClientApiLimits.hpp @@ -78,6 +78,11 @@ struct ClientApiLimits final // PUT /devices/{deviceId} answer 400 M_TOO_LARGE over it. The per-user device count is // `device_count_limit`, a constant, because device creation has no ClientApiLimits. std::size_t max_device_display_name_bytes{device_display_name_byte_limit}; + // ADR-0780: the most OAuth 2.0 client registrations held. Registration is unauthenticated, so the table needs a + // bound; one row per distinct client application (ADR-0779) is far below it on any real server, and 10000 rows of + // at most 16 KiB stay small in memory. At the cap a new registration first evicts idle clients, least recently + // used first; tests lower it. + std::size_t max_oauth_clients{10000U}; sync::SlidingSyncLimits sliding_sync{500U, 1024U, 1024U}; std::uint32_t sliding_sync_connections_per_device{16U}; }; diff --git a/include/merovingian/homeserver/HomeserverRuntime.hpp b/include/merovingian/homeserver/HomeserverRuntime.hpp index 5bbe4f1bc..4d1210832 100644 --- a/include/merovingian/homeserver/HomeserverRuntime.hpp +++ b/include/merovingian/homeserver/HomeserverRuntime.hpp @@ -233,6 +233,10 @@ struct HomeserverRuntime final // tombstone is sent, with runtime.mutex released, so a test can change the old room as a concurrent // request would (C21). Always empty in production. std::function test_after_upgrade_room_created{}; + // Test-only: when set, `oauth_client_has_pending_authorisation` also answers true for each client ID it answers + // true for, so a test can stand in for an authorisation still pending before phase 5 of the OAuth 2.0 work keeps + // them. Called with runtime.mutex held; must not take it. Always empty in production. + std::function test_oauth_pending_authorisation{}; // Application Service API registry (Matrix v1.19). Built once at // start_runtime() time from config.appservice().registration_files and // never mutated afterward — every request reads it as an immutable, diff --git a/include/merovingian/homeserver/OAuthClientRegistration.hpp b/include/merovingian/homeserver/OAuthClientRegistration.hpp new file mode 100644 index 000000000..a17d29b20 --- /dev/null +++ b/include/merovingian/homeserver/OAuthClientRegistration.hpp @@ -0,0 +1,63 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/oauth/ClientMetadata.hpp" + +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +struct ClientServerRuntime; +struct HomeserverRuntime; + +// The most idle clients one registration deletes to make room at the cap (ADR-0780). A registration needs one slot, +// so one deletion is the usual case; the bound keeps a request's work fixed even if the cap was lowered below the +// number held. +inline constexpr auto max_oauth_client_evictions_per_registration = std::size_t{8U}; + +// POST /_merovingian/oauth2/register (spec "Client registration", RFC 7591; plan P2, ADR-0779 to ADR-0781). +// `content_type` is the request's Content-Type header (empty when absent) and `body` its body; the dispatcher has +// matched the route and checked that `server.oauth.enabled` is true. +// +// - A body over database::max_oauth_client_metadata_bytes, a Content-Type other than `application/json` (optionally +// with `charset=utf-8`), or a body that is not JSON: 400 `invalid_client_metadata`. +// - Metadata oauth::ClientMetadata::validate refuses: 400 with the refusal's code and fixed text. +// - Otherwise the client ID is `oauth_client_id_of` the accepted metadata. A held client is touched +// (database::touch_oauth_client, a write at most once a day); a new one is stored, after deleting idle clients +// least recently used first when `runtime.limits.max_oauth_clients` are held. A client with a session, or one +// `oauth_client_has_pending_authorisation` names, is never deleted. When nothing can go: 503 +// `temporarily_unavailable`, nothing stored. +// - Success: 201 with `client_id`, `client_id_issued_at` (seconds, from the row's creation) and every member of +// oauth::ClientMetadata::to_json. +// +// Every answer is oauth_json_response or oauth_error_response. Logs the client ID, the application type and the +// `client_uri` host, never the body. Requires runtime.homeserver.mutex held; makes no network call. +[[nodiscard]] auto register_oauth_client(ClientServerRuntime& runtime, std::string_view content_type, + std::string_view body) -> LocalHttpResponse; + +// The 400 `invalid_client_metadata` for a registration body over database::max_oauth_client_metadata_bytes, as +// register_oauth_client answers it. Reads no state, so the dispatcher's general body cap may answer it before taking +// runtime.homeserver.mutex (ADR-0781). +[[nodiscard]] auto oauth_client_metadata_too_large() -> LocalHttpResponse; + +// The client ID this server gives `metadata` (plan P2, ADR-0779): crypto::oauth_client_id over +// `metadata.canonical_bytes()` under the key derived from the master key file. The same metadata always gives the same +// ID on this server. nullopt when no master key can be read or a primitive failed: no ID can be issued then. +[[nodiscard]] auto oauth_client_id_of(HomeserverRuntime const& runtime, oauth::ClientMetadata const& metadata) + -> std::optional; + +// The registered metadata of client `client_id`, read back for an authorisation, token or revocation request +// (oauth/AGENTS.md rule 11): the row is found, its `metadata_json` parsed and validated again by +// oauth::ClientMetadata::validate. nullopt for an unknown client, and for a stored row that no longer validates, +// which is treated as unknown and logged at warning level with its client ID only, never its content. Requires +// runtime.mutex held; reads memory only. +[[nodiscard]] auto find_registered_oauth_client(HomeserverRuntime const& runtime, std::string_view client_id) + -> std::optional; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/OAuthJsonResponse.hpp b/include/merovingian/homeserver/OAuthJsonResponse.hpp new file mode 100644 index 000000000..9b98fbff0 --- /dev/null +++ b/include/merovingian/homeserver/OAuthJsonResponse.hpp @@ -0,0 +1,28 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/oauth/OAuthRefusal.hpp" + +#include + +namespace merovingian::homeserver +{ + +// The answers of the OAuth 2.0 JSON endpoints (registration, token, revocation; ADR-0781). They follow OAuth rules, +// not Matrix ones: an error is `{"error": ..., "error_description": ...}` (RFC 6749 section 5.2, RFC 7591 section +// 3.2.2), never a Matrix `errcode`, and every answer carries `Content-Type: application/json` and +// `Cache-Control: no-store`, because a registration or token answer must never be stored by a cache. CORS headers are +// added at the dispatcher's boundary like every other client-server answer. + +// `body` serialised as canonical JSON with `status`. A body the serialiser refuses (which only a defect can build) +// becomes a 500 `server_error` with a fixed description. +[[nodiscard]] auto oauth_json_response(std::uint16_t status, canonicaljson::Value const& body) -> LocalHttpResponse; + +// The error answer of `refusal` with `status`: its `error_code` as `error` and its fixed message as +// `error_description`. The message never quotes the request (oauth/AGENTS.md rule 2), so it is safe to send. +[[nodiscard]] auto oauth_error_response(std::uint16_t status, oauth::OAuthRefusal const& refusal) -> LocalHttpResponse; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/RetentionSweep.hpp b/include/merovingian/homeserver/RetentionSweep.hpp index c9bcd9b46..dd44b0260 100644 --- a/include/merovingian/homeserver/RetentionSweep.hpp +++ b/include/merovingian/homeserver/RetentionSweep.hpp @@ -30,8 +30,9 @@ inline constexpr auto expired_access_token_grace = std::chrono::hours{24 * 7}; inline constexpr auto oauth_client_retention = std::chrono::hours{24 * 30}; // Whether an authorisation request still pending names `client_id`, so its client must not be deleted under it. -// Phase 5 of the OAuth 2.0 work keeps pending authorisations; until then none exist and this is always false. -// Called with HomeserverRuntime::mutex held. +// Phase 5 of the OAuth 2.0 work keeps pending authorisations; until then none exist and this is false unless a test +// set `HomeserverRuntime::test_oauth_pending_authorisation`. The retention sweep and the registration cap +// (`register_oauth_client`) both ask it before deleting a client. Called with HomeserverRuntime::mutex held. [[nodiscard]] auto oauth_client_has_pending_authorisation(HomeserverRuntime const& runtime, std::string_view client_id) -> bool; diff --git a/include/merovingian/oauth/OAuthErrorCodes.hpp b/include/merovingian/oauth/OAuthErrorCodes.hpp index 64acf534a..67a540d38 100644 --- a/include/merovingian/oauth/OAuthErrorCodes.hpp +++ b/include/merovingian/oauth/OAuthErrorCodes.hpp @@ -15,5 +15,9 @@ inline constexpr std::string_view error_invalid_grant = "invalid_grant"; inline constexpr std::string_view error_invalid_scope = "invalid_scope"; inline constexpr std::string_view error_invalid_redirect_uri = "invalid_redirect_uri"; inline constexpr std::string_view error_invalid_client_metadata = "invalid_client_metadata"; +// RFC 6749 section 4.1.2.1: the server cannot take the request now (the client registration cap, ADR-0780) or failed +// in a way the client cannot fix. +inline constexpr std::string_view error_temporarily_unavailable = "temporarily_unavailable"; +inline constexpr std::string_view error_server_error = "server_error"; } // namespace merovingian::oauth diff --git a/src/crypto/AGENTS.md b/src/crypto/AGENTS.md index 1550b1ddd..0041af52b 100644 --- a/src/crypto/AGENTS.md +++ b/src/crypto/AGENTS.md @@ -22,7 +22,8 @@ or `src/core/SecretBuffer.cpp`.** `scripts/reject-unsafe.sh` enforces this for b | `Encoding.cpp` | Hex and base64 (URL-safe and original) encoding wrappers | | `MasterKey.cpp` | Loads and validates the operator master key into locked memory; fails closed if it cannot be locked | | `SecretBox.cpp` | `SecretBoxKey` — encrypts server signing secrets at rest (`secretbox:v1:` format) | -| `TokenKey.cpp` | `TokenHmacKey` — master-key-derived key for `v3`/`v4` access-token hashing | +| `TokenKey.cpp` | `TokenHmacKey` — master-key-derived keys for `v3`/`v4` access-token hashing and the OAuth client ID (own label, ADR-0779), cached together | +| `OAuthClientId.cpp` | `oauth_client_id`: keyed BLAKE2b of canonical OAuth client metadata, 43 URL-safe base64 characters (ADR-0779) | | `IpcAuthKey.cpp` | `IpcAuthKey` — master-key-derived key that authenticates the federation-worker IPC handshake | | `IpcStreamCipher.cpp` | `crypto_kx` session keys and `secretstream` AEAD framing for the IPC channel | diff --git a/src/crypto/OAuthClientId.cpp b/src/crypto/OAuthClientId.cpp new file mode 100644 index 000000000..f54c409c4 --- /dev/null +++ b/src/crypto/OAuthClientId.cpp @@ -0,0 +1,36 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/crypto/OAuthClientId.hpp" + +#include "merovingian/crypto/Encoding.hpp" +#include "merovingian/crypto/GenericHash.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::crypto +{ + +auto oauth_client_id(std::string_view canonical_metadata, TokenHmacKey const& key) -> std::optional +{ + auto const pieces = std::array{canonical_metadata}; + auto const digest = generic_hash_bytes(pieces, std::span{key.bytes.data(), key.bytes.size()}); + if (!digest.has_value()) + { + return std::nullopt; + } + auto encoded = + base64_urlsafe_encode(std::string_view{reinterpret_cast(digest->data()), digest->size()}); + if (!encoded.has_value() || encoded->size() != oauth_client_id_chars) + { + return std::nullopt; + } + return encoded; +} + +} // namespace merovingian::crypto diff --git a/src/crypto/TokenKey.cpp b/src/crypto/TokenKey.cpp index cb7511bfc..0f6535bcd 100644 --- a/src/crypto/TokenKey.cpp +++ b/src/crypto/TokenKey.cpp @@ -32,6 +32,9 @@ namespace // prevents key reuse across cryptographic purposes. constexpr auto k_context_v4 = std::string_view{"merovingian:access-token-hmac:1"}; constexpr auto k_context_v3 = std::string_view{"merovingian:access-token-hmac:legacy-v3:1"}; + // The OAuth 2.0 client ID key (ADR-0779). Its own label: a client ID is published, so the key that makes it + // must never be one that also hashes a secret. + constexpr auto k_context_oauth_client_id = std::string_view{"merovingian:oauth-client-id:1"}; [[nodiscard]] auto sodium_is_ready() noexcept -> bool { @@ -76,6 +79,12 @@ auto derive_token_hmac_key_v3(std::span master_key_material) return derive_with_label(master_key_material, k_context_v3); } +auto derive_oauth_client_id_key(std::span master_key_material) noexcept + -> std::optional +{ + return derive_with_label(master_key_material, k_context_oauth_client_id); +} + auto cached_token_hmac_keys(std::string_view path) -> std::shared_ptr // SHARED_PTR: reviewed — locked keys shared by readers try @@ -123,13 +132,15 @@ try auto const material = load_master_key_material(*opened); auto v3 = material.has_value() ? derive_token_hmac_key_v3(material->bytes()) : std::nullopt; auto v4 = material.has_value() ? derive_token_hmac_key(material->bytes()) : std::nullopt; - if (!v3.has_value() || !v4.has_value()) + auto client_id = material.has_value() ? derive_oauth_client_id_key(material->bytes()) : std::nullopt; + if (!v3.has_value() || !v4.has_value() || !client_id.has_value()) { cached_identity.clear(); cached_keys.reset(); return nullptr; } - cached_keys = std::make_shared(TokenHmacKeys{std::move(v3), std::move(v4)}); + cached_keys = std::make_shared( // SHARED_PTR: reviewed — locked keys shared by readers + TokenHmacKeys{std::move(v3), std::move(v4), std::move(client_id)}); cached_identity = opened->identity; return cached_keys; } diff --git a/src/crypto/meson.build b/src/crypto/meson.build index f0e6b1ec2..fed88f0c8 100644 --- a/src/crypto/meson.build +++ b/src/crypto/meson.build @@ -8,6 +8,7 @@ crypto_sources = files( 'IpcStreamCipher.cpp', 'LibraryVersions.cpp', 'MasterKey.cpp', + 'OAuthClientId.cpp', 'Random.cpp', 'RefusingEd25519Provider.cpp', 'RuntimeEd25519Provider.cpp', diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index ec1ea045a..3970db0f0 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -27,6 +27,8 @@ This is the largest and most complex module — read this file carefully before | `AppserviceDelivery.cpp` | Application Service API outbound queue (ADR-0163): `enqueue_appservice_delivery` (request path, no network) and `drain_appservice_queues` (the one drainer thread, run by a `PeriodicJob` from `main.cpp`) | | `ClientTxnPrune.cpp` | `prune_client_transactions`: the sweep the `client-txn-prune` `PeriodicJob` runs every hour, deleting to-device `client_txn_ids` records older than 7 days (F-54, ADR-0381) | | `RetentionSweep.cpp` | `run_retention_sweep`: the sweep the `retention-sweep` `PeriodicJob` runs every hour. Deletes sessions and tokens that can no longer authenticate and `audit_log` rows past `security.audit_log_retention_days`, and OAuth 2.0 clients with no session unused for 30 days (`oauth_client_retention`, least recently used first; never a client with a session, nor one `oauth_client_has_pending_authorisation` names, a seam that is false until phase 5; ADR-0777), in transactions of at most 500 rows (`retention_batch_rows`), at most 20 batches per kind per sweep. `runtime.mutex` is taken for one batch at a time, never across the whole sweep (ADR-0488, ADR-0489) | +| `OAuthClientRegistration.cpp` | `POST /_merovingian/oauth2/register` (`register_oauth_client`), the client ID (`oauth_client_id_of`, ADR-0779), the cap and its eviction (ADR-0780), and `find_registered_oauth_client` | +| `OAuthJsonResponse.cpp` | `oauth_json_response` / `oauth_error_response`: every OAuth JSON answer, with `no-store` (ADR-0781) | | `LoginTokenStore.cpp` | `LoginTokenStore`: the in-memory, bounded, single-use login tokens `POST /login/get_token` mints (CS8, ADR-0548). Hash only, constant-time scan, never evicts; guarded by `runtime.mutex` | | `SessionTable.cpp` | `SessionTable`: `LocalDatabase::sessions` with an index of token-hash digests, so `find_session` does not scan (ADR-0488), and an index by (user ID, device ID) behind `erase_device` (F-08), which a login on a held device and a refresh call after their database commit (ADR-0590); `rows_examined()` counts the sessions it visits | | `DeferredPduRetry.cpp` | Retains federation PDUs that could not yet be placed (`deferred_pdus`) and retries them: `retry_deferred_pdus`, `DeferredPduRetryJob` (R03, ADR-0165). A retry holds no lock across `ingest_pdu_event`; `ingest_pdu_event` writes rows only after signature verification | @@ -108,6 +110,18 @@ absolute OAuth address a handler writes comes from `oauth::OAuthBaseUrl` read fr constant from `oauth/OAuthPaths.hpp`; never join the base URL and a path here. The two paths stay in the generic rate-limit tier (ADR-0775); the other OAuth endpoints take `auth_sensitive`. +`POST /_merovingian/oauth2/register` is `register_oauth_client` (`OAuthClientRegistration.cpp`), answered before the +authentication gate, and also from the general body cap so an oversized body is an OAuth 400 (ADR-0781). Rules: + +- Every OAuth answer is built by `oauth_json_response` or `oauth_error_response` (`OAuthJsonResponse.cpp`): + `application/json`, `Cache-Control: no-store`, `{"error", "error_description"}`. Never build OAuth JSON by hand. +- The client ID is `oauth_client_id_of` (keyed hash of `canonical_bytes()`, ADR-0779); never mint one another way. +- At `ClientApiLimits::max_oauth_clients` a new client evicts at most `max_oauth_client_evictions_per_registration` + idle clients, never one with a session or one `oauth_client_has_pending_authorisation` names, else 503 with nothing + stored (ADR-0780). A repeat registration is never refused by the cap. +- Log `client_id`, `application_type` and the `client_uri` host only; never the body. +- Read a client back with `find_registered_oauth_client`, which re-validates the stored metadata. + ## Password reset by email (ADR-0481) `POST /account/password/email/requestToken`, the submit step and `POST /account/password` with `m.login.email.identity` diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index 6fbd7ddf0..0e7c3f57b 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -98,6 +98,7 @@ #include "merovingian/homeserver/LocalServices.hpp" #include "merovingian/homeserver/LocalUser.hpp" #include "merovingian/homeserver/MutualRoomsToken.hpp" +#include "merovingian/homeserver/OAuthClientRegistration.hpp" #include "merovingian/homeserver/OperationResult.hpp" #include "merovingian/homeserver/OperatorAdmin.hpp" #include "merovingian/homeserver/OutboundDeadline.hpp" @@ -4064,6 +4065,7 @@ namespace "/_matrix/client/v3/logout/all", "/_matrix/client/v1/auth_metadata", "/_matrix/client/unstable/org.matrix.msc2965/auth_metadata", + "/_merovingian/oauth2/register", "/_matrix/client/v3/account/3pid/email/requestToken", "/_matrix/client/v3/account/3pid/msisdn/requestToken", "/_matrix/client/v3/account/password/email/requestToken", @@ -4160,6 +4162,7 @@ namespace {"/_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" }, {"/_matrix/client/v3/account/3pid/email/requestToken", "POST" }, {"/_matrix/client/v3/account/3pid/msisdn/requestToken", "POST" }, {"/_matrix/client/v3/account/password/email/requestToken", "POST" }, @@ -14479,6 +14482,13 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp }, observability::LogEventSeverity::warning, observability::AuditCategory::policy, "request.rejected", "", req.target, "413:request body too large"); + // OAuth 2.0 client registration answers every refused body as an OAuth error (ADR-0781). This gate runs before + // runtime.mutex is taken, so it answers with the fixed refusal, which reads no state. + if (request_path == oauth::register_path.view() && req.method == "POST" && + rt.homeserver.config.server().oauth.enabled) + { + return DispatchResult{DispatchResult::Status::complete, oauth_client_metadata_too_large(), {}}; + } return dispatch_err(req, rt, 413U, "M_TOO_LARGE", "request body too large"); } // CORS preflight: browsers send OPTIONS before any cross-origin POST/PUT/DELETE. @@ -16019,6 +16029,23 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return dispatch_resp(req, rt, 200U, json_serialize(oauth::server_metadata(std::get(base), options))); } + // POST /_merovingian/oauth2/register (spec "Client registration", RFC 7591). Unauthenticated, so it is answered + // before the access-token gate; with the OAuth 2.0 API off the path is not served at all, so it is 404 whatever the + // method, as an unknown route is. Another method falls through to the 405 gate (client_static_route_allow). + // The handler is OAuthClientRegistration.cpp; its answers are OAuth errors, never Matrix ones (ADR-0781). + if (request_path == oauth::register_path.view()) + { + if (!rt.homeserver.config.server().oauth.enabled) + { + return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); + } + if (req.method == "POST") + { + return DispatchResult{DispatchResult::Status::complete, + register_oauth_client(rt, request_header(req, "Content-Type"), req.body), + {}}; + } + } // The rest of the MSC2965 namespace (`auth_issuer`, from an earlier draft of the MSC) is not served. It is // answered 404 before the access-token gate, so a probe does not read a 401 as partial support. if (req.method == "GET" && starts_with(req.target, "/_matrix/client/unstable/org.matrix.msc2965/")) diff --git a/src/homeserver/OAuthClientRegistration.cpp b/src/homeserver/OAuthClientRegistration.cpp new file mode 100644 index 000000000..04ed461af --- /dev/null +++ b/src/homeserver/OAuthClientRegistration.cpp @@ -0,0 +1,323 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/OAuthClientRegistration.hpp" + +#include "merovingian/canonicaljson/ParseError.hpp" +#include "merovingian/canonicaljson/Parser.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/core/Error.hpp" +#include "merovingian/core/ErrorCode.hpp" +#include "merovingian/crypto/OAuthClientId.hpp" +#include "merovingian/crypto/TokenKey.hpp" +#include "merovingian/database/OAuthClientStoreResult.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentOAuthClient.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/OAuthJsonResponse.hpp" +#include "merovingian/homeserver/RetentionSweep.hpp" +#include "merovingian/oauth/ApplicationType.hpp" +#include "merovingian/oauth/OAuthErrorCodes.hpp" +#include "merovingian/oauth/OAuthRefusal.hpp" +#include "merovingian/observability/LogEventSeverity.hpp" +#include "merovingian/observability/SingleLog.hpp" +#include "merovingian/observability/StructuredLogField.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ +namespace +{ + + [[nodiscard]] auto wall_clock_ms() -> std::uint64_t + { + auto const now = + std::chrono::duration_cast(std::chrono::system_clock::now().time_since_epoch()); + return now.count() < 0 ? std::uint64_t{0U} : static_cast(now.count()); + } + + [[nodiscard]] auto refusal(std::string_view code, core::ErrorCode kind, std::string message) -> oauth::OAuthRefusal + { + return oauth::OAuthRefusal{ + std::string{code}, + core::Error{kind, std::move(message)} + }; + } + + [[nodiscard]] auto invalid_metadata(std::string message) -> LocalHttpResponse + { + return oauth_error_response( + 400U, refusal(oauth::error_invalid_client_metadata, core::ErrorCode::parse_failure, std::move(message))); + } + + [[nodiscard]] auto server_error(std::string message) -> LocalHttpResponse + { + return oauth_error_response( + 500U, refusal(oauth::error_server_error, core::ErrorCode::internal_failure, std::move(message))); + } + + [[nodiscard]] auto ascii_lower(char value) noexcept -> char + { + return value >= 'A' && value <= 'Z' ? static_cast(value - 'A' + 'a') : value; + } + + [[nodiscard]] auto equals_ignoring_ascii_case(std::string_view left, std::string_view right) noexcept -> bool + { + if (left.size() != right.size()) + { + return false; + } + for (auto index = std::size_t{0U}; index < left.size(); ++index) + { + if (ascii_lower(left[index]) != ascii_lower(right[index])) + { + return false; + } + } + return true; + } + + [[nodiscard]] auto trim_whitespace(std::string_view text) noexcept -> std::string_view + { + while (!text.empty() && (text.front() == ' ' || text.front() == '\t')) + { + text.remove_prefix(1U); + } + while (!text.empty() && (text.back() == ' ' || text.back() == '\t')) + { + text.remove_suffix(1U); + } + return text; + } + + // `application/json`, alone or with the one parameter `charset=utf-8`, in any ASCII case (RFC 9110 section 8.3.1: + // type, subtype and parameter names are case-insensitive). Anything else is refused rather than guessed at: the + // body is read as JSON and nothing else. + [[nodiscard]] auto content_type_is_json(std::string_view content_type) noexcept -> bool + { + auto const separator = content_type.find(';'); + if (!equals_ignoring_ascii_case(trim_whitespace(content_type.substr(0U, separator)), "application/json")) + { + return false; + } + if (separator == std::string_view::npos) + { + return true; + } + auto const parameter = trim_whitespace(content_type.substr(separator + 1U)); + return equals_ignoring_ascii_case(parameter, "charset=utf-8") || + equals_ignoring_ascii_case(parameter, "charset=\"utf-8\""); + } + + [[nodiscard]] auto application_type_name(oauth::ApplicationType type) noexcept -> std::string_view + { + return type == oauth::ApplicationType::native ? "native" : "web"; + } + + auto log_oauth(std::string_view event, std::vector fields, + observability::LogEventSeverity severity) -> void + { + observability::log_diagnostic("oauth", event, std::move(fields), severity); + } + + // The 201 body: the registered metadata, the client ID and when it was first issued (RFC 7591 section 3.2.1). + [[nodiscard]] auto registration_response(oauth::ClientMetadata const& metadata, std::string const& client_id, + std::uint64_t created_at_ms) -> LocalHttpResponse + { + auto const registered = metadata.to_json(); + auto const* members = std::get_if(®istered.storage()); + if (members == nullptr) + { + return server_error("The registered client metadata could not be written."); + } + auto object = *members; + object.push_back(canonicaljson::make_member("client_id", canonicaljson::Value{client_id})); + auto const issued_at_seconds = created_at_ms / 1000U; + object.push_back(canonicaljson::make_member( + "client_id_issued_at", + canonicaljson::Value{static_cast( + issued_at_seconds > static_cast(std::numeric_limits::max()) + ? static_cast(std::numeric_limits::max()) + : issued_at_seconds)})); + return oauth_json_response(201U, canonicaljson::Value{std::move(object)}); + } + + // Makes room for one more client at the cap by deleting idle clients, least recently used first (ADR-0780). True + // when there is room afterwards. Never deletes a client with a session (delete_oauth_clients refuses one, and + // oauth_clients_without_sessions never offers one) nor one a pending authorisation names. + [[nodiscard]] auto make_room_for_a_client(ClientServerRuntime& runtime) -> bool + { + auto& store = runtime.homeserver.database.persistent_store; + auto const held = database::oauth_client_count(store); + auto const limit = runtime.limits.max_oauth_clients; + if (held < limit) + { + return true; + } + auto const needed = held - limit + 1U; + if (needed > max_oauth_client_evictions_per_registration) + { + return false; + } + auto const& homeserver = runtime.homeserver; + auto const pending = [&homeserver](std::string_view client_id) { + return oauth_client_has_pending_authorisation(homeserver, client_id); + }; + auto const idle = + database::oauth_clients_without_sessions(store, needed, std::numeric_limits::max(), pending); + if (idle.size() < needed || !database::delete_oauth_clients(store, idle)) + { + return false; + } + log_oauth("oauth.client.evicted", + { + {"clients", std::to_string(idle.size()), false}, + {"limit", std::to_string(limit), false} + }, + observability::LogEventSeverity::info); + return true; + } + +} // namespace + +auto oauth_client_id_of(HomeserverRuntime const& runtime, oauth::ClientMetadata const& metadata) + -> std::optional +{ + auto canonical = metadata.canonical_bytes(); + if (std::holds_alternative(canonical)) + { + return std::nullopt; + } + auto const keys = crypto::cached_token_hmac_keys(runtime.config.security().secrets.master_key_file); + if (keys == nullptr || !keys->oauth_client_id.has_value()) + { + return std::nullopt; + } + return crypto::oauth_client_id(std::get(canonical), *keys->oauth_client_id); +} + +auto find_registered_oauth_client(HomeserverRuntime const& runtime, std::string_view client_id) + -> std::optional +{ + if (client_id.empty() || client_id.size() > database::max_oauth_client_id_bytes) + { + return std::nullopt; + } + auto const* row = database::find_oauth_client(runtime.database.persistent_store, client_id); + if (row == nullptr) + { + return std::nullopt; + } + auto const parsed = canonicaljson::parse_json(row->metadata_json); + if (parsed.error == canonicaljson::ParseError::none) + { + auto validated = oauth::ClientMetadata::validate(parsed.value); + if (auto* metadata = std::get_if(&validated); metadata != nullptr) + { + return std::move(*metadata); + } + } + // A row this server wrote that its own rules now refuse (a rule tightened since): the client is unknown until it + // registers again. Its metadata is attacker-chosen text, so it is not logged. + log_oauth("oauth.client.stored_metadata_refused", + { + {"client_id", std::string{client_id}, false} + }, + observability::LogEventSeverity::warning); + return std::nullopt; +} + +auto oauth_client_metadata_too_large() -> LocalHttpResponse +{ + return invalid_metadata("The client metadata is larger than this server accepts."); +} + +auto register_oauth_client(ClientServerRuntime& runtime, std::string_view content_type, std::string_view body) + -> LocalHttpResponse +{ + if (body.size() > database::max_oauth_client_metadata_bytes) + { + return oauth_client_metadata_too_large(); + } + if (!content_type_is_json(content_type)) + { + return invalid_metadata("The client metadata must be sent as application/json."); + } + auto const parsed = canonicaljson::parse_json(body); + if (parsed.error != canonicaljson::ParseError::none) + { + return invalid_metadata("The client metadata is not valid JSON."); + } + auto validated = oauth::ClientMetadata::validate(parsed.value); + if (auto const* refused = std::get_if(&validated); refused != nullptr) + { + return oauth_error_response(400U, *refused); + } + auto const& metadata = std::get(validated); + auto canonical = metadata.canonical_bytes(); + if (std::holds_alternative(canonical)) + { + return server_error("The client metadata could not be registered."); + } + auto& metadata_json = std::get(canonical); + if (metadata_json.size() > database::max_oauth_client_metadata_bytes) + { + // The defaults the server adds can take a body just under the cap over it. + return oauth_client_metadata_too_large(); + } + auto const client_id = oauth_client_id_of(runtime.homeserver, metadata); + if (!client_id.has_value()) + { + return server_error("The server cannot issue client IDs now."); + } + + auto& store = runtime.homeserver.database.persistent_store; + auto const now_ms = wall_clock_ms(); + auto const log_fields = std::vector{ + {"client_id", *client_id, false}, + {"application_type", std::string{application_type_name(metadata.application_type())}, false}, + {"client_host", metadata.client_uri().host_lower(), false}, + }; + if (auto const* held = database::find_oauth_client(store, *client_id); held != nullptr) + { + // The pointer is valid only until the next write; the touch is one. + auto const created_at_ms = held->created_at_ms; + if (!database::touch_oauth_client(store, *client_id, now_ms)) + { + // The row is held and answered; only its last use is stale, which ages it towards eviction early. + log_oauth("oauth.client.touch_failed", log_fields, observability::LogEventSeverity::warning); + } + log_oauth("oauth.client.registered_again", log_fields, observability::LogEventSeverity::debug); + return registration_response(metadata, *client_id, created_at_ms); + } + + if (!make_room_for_a_client(runtime)) + { + log_oauth("oauth.client.cap_reached", log_fields, observability::LogEventSeverity::warning); + return oauth_error_response(503U, + refusal(oauth::error_temporarily_unavailable, core::ErrorCode::invalid_argument, + "The server holds as many client registrations as it can.")); + } + auto const stored = database::store_oauth_client( + store, database::PersistentOAuthClient{*client_id, std::move(metadata_json), now_ms, now_ms}); + if (stored == database::OAuthClientStoreResult::refused) + { + log_oauth("oauth.client.store_failed", log_fields, observability::LogEventSeverity::warning); + return server_error("The client could not be registered."); + } + log_oauth("oauth.client.registered", log_fields, observability::LogEventSeverity::info); + return registration_response(metadata, *client_id, now_ms); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/OAuthJsonResponse.cpp b/src/homeserver/OAuthJsonResponse.cpp new file mode 100644 index 000000000..8b36e0530 --- /dev/null +++ b/src/homeserver/OAuthJsonResponse.cpp @@ -0,0 +1,51 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/OAuthJsonResponse.hpp" + +#include "merovingian/canonicaljson/CanonicalJsonError.hpp" +#include "merovingian/canonicaljson/Serializer.hpp" + +#include +#include +#include +#include + +namespace merovingian::homeserver +{ +namespace +{ + + // Written when serialisation itself failed, so it is fixed text rather than built. + constexpr auto unserialisable_body = + std::string_view{R"({"error":"server_error","error_description":"The server could not write its answer."})"}; + + [[nodiscard]] auto with_oauth_headers(std::uint16_t status, std::string body) -> LocalHttpResponse + { + auto response = LocalHttpResponse{status, std::move(body), {}}; + response.headers.emplace_back("Content-Type", "application/json"); + response.headers.emplace_back("Cache-Control", "no-store"); + return response; + } + +} // namespace + +auto oauth_json_response(std::uint16_t status, canonicaljson::Value const& body) -> LocalHttpResponse +{ + auto serialized = canonicaljson::serialize_canonical(body); + if (serialized.error != canonicaljson::CanonicalJsonError::none) + { + return with_oauth_headers(500U, std::string{unserialisable_body}); + } + return with_oauth_headers(status, std::move(serialized.output)); +} + +auto oauth_error_response(std::uint16_t status, oauth::OAuthRefusal const& refusal) -> LocalHttpResponse +{ + auto object = canonicaljson::Object{}; + object.push_back(canonicaljson::make_member("error", canonicaljson::Value{refusal.error_code})); + object.push_back(canonicaljson::make_member("error_description", canonicaljson::Value{refusal.error.message()})); + return oauth_json_response(status, canonicaljson::Value{std::move(object)}); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/RetentionSweep.cpp b/src/homeserver/RetentionSweep.cpp index d20457840..d75038f6f 100644 --- a/src/homeserver/RetentionSweep.cpp +++ b/src/homeserver/RetentionSweep.cpp @@ -216,11 +216,11 @@ namespace } // namespace -// The seam phase 5 fills in: no authorisation request is kept yet, so none can name a client. -auto oauth_client_has_pending_authorisation([[maybe_unused]] HomeserverRuntime const& runtime, - [[maybe_unused]] std::string_view client_id) -> bool +// The seam phase 5 fills in: no authorisation request is kept yet, so none can name a client. A test stands in for one +// through `test_oauth_pending_authorisation`, which production never sets. +auto oauth_client_has_pending_authorisation(HomeserverRuntime const& runtime, std::string_view client_id) -> bool { - return false; + return runtime.test_oauth_pending_authorisation && runtime.test_oauth_pending_authorisation(client_id); } auto run_retention_sweep(HomeserverRuntime& runtime, std::chrono::system_clock::time_point now, StopFlag const& stop) diff --git a/src/homeserver/meson.build b/src/homeserver/meson.build index 13adb22a9..70ff17a33 100644 --- a/src/homeserver/meson.build +++ b/src/homeserver/meson.build @@ -27,6 +27,8 @@ homeserver_sources = files( 'MediaService.cpp', 'StreamedBody.cpp', 'MediaUploadNotifier.cpp', + 'OAuthClientRegistration.cpp', + 'OAuthJsonResponse.cpp', 'OperatorAdmin.cpp', 'UrlPreviewService.cpp', 'PeriodicJob.cpp', diff --git a/src/http/RateLimit.cpp b/src/http/RateLimit.cpp index cb889a736..d43829408 100644 --- a/src/http/RateLimit.cpp +++ b/src/http/RateLimit.cpp @@ -51,9 +51,12 @@ auto rate_limit_tier_for(std::string_view target) noexcept -> RateLimitTier // against /login is the same enumeration surface as a POST, and the // /requestToken family spans several parents // (/account/3pid/email|msisdn/requestToken, /register/*/requestToken), - // so it is matched by suffix. + // so it is matched by suffix. The OAuth 2.0 endpoints and pages (client registration, the authorisation and + // token endpoints, the account pages) are unauthenticated credential surfaces like /login and /register; the two + // `auth_metadata` paths are not among them and stay generic (ADR-0775). if (starts_with(target, "/_matrix/client/v3/login") || starts_with(target, "/_matrix/client/v3/refresh") || starts_with(target, "/_matrix/client/v3/register") || starts_with(target, "/_matrix/client/v1/register") || + starts_with(target, "/_merovingian/oauth2/") || starts_with(target, "/_merovingian/account") || target.find("/requestToken") != std::string_view::npos || target.find("/submitToken") != std::string_view::npos) { return RateLimitTier::auth_sensitive; diff --git a/src/http/ResponseHead.cpp b/src/http/ResponseHead.cpp index c068ffb96..aa34e6c9e 100644 --- a/src/http/ResponseHead.cpp +++ b/src/http/ResponseHead.cpp @@ -36,6 +36,8 @@ auto reason_phrase(std::uint16_t status) noexcept -> std::string_view { case 200U: return "OK"; + case 201U: + return "Created"; case 202U: return "Accepted"; case 302U: diff --git a/tests/conformance/AGENTS.md b/tests/conformance/AGENTS.md index 13224ed5c..9f6e277f3 100644 --- a/tests/conformance/AGENTS.md +++ b/tests/conformance/AGENTS.md @@ -62,6 +62,7 @@ Every test in this directory directly encodes a **MUST** or **SHOULD** from the | `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) | +| `test_oauth_client_registration_conformance.cpp` | [CS API § Client registration](../../docs/matrix-v1.19-spec/client-server-api.md#client-registration) · [§ Client metadata](../../docs/matrix-v1.19-spec/client-server-api.md#client-metadata) · [§ Redirect URI validation](../../docs/matrix-v1.19-spec/client-server-api.md#redirect-uri-validation) · [§ Dynamic client registration flow](../../docs/matrix-v1.19-spec/client-server-api.md#dynamic-client-registration-flow) (`POST /_merovingian/oauth2/register`: 201 with `client_id` and the registered metadata, web and native, `none`, unknown values ignored, the spec's redirect URI examples, a client with a session never deleted) | | `test_pdu_format_conformance.cpp` | [SS API § PDUs](../../docs/matrix-v1.19-spec/server-server-api.md#pdus) | | `test_pdu_ingestion_conformance.cpp` | [SS API § Checks performed on receipt of a PDU](../../docs/matrix-v1.19-spec/server-server-api.md#checks-performed-on-receipt-of-a-pdu) · [Room v12 § State resolution](../../docs/matrix-v1.19-spec/rooms/v12.md) (auth_events selection: m.room.create MUST NOT be selected) · [§ Calculating the reference hash](../../docs/matrix-v1.19-spec/server-server-api.md#calculating-the-reference-hash-for-an-event) (a received PDU is stored without its `unsigned`, under an unchanged event ID) | | `test_pdu_signature_conformance.cpp` | [SS API § Validating hashes and signatures on received events](../../docs/matrix-v1.19-spec/server-server-api.md#validating-hashes-and-signatures-on-received-events) · [Room v5 § Signing key validity period](../../docs/matrix-v1.19-spec/rooms/v5.md) (key validity at `origin_server_ts`, 7-day cap) · [Room v8 § Authorisation rules](../../docs/matrix-v1.19-spec/rooms/v8.md#authorisation-rules) (`join_authorised_via_users_server` needs the authorising server's signature from room version 8 only) | diff --git a/tests/conformance/test_oauth_client_registration_conformance.cpp b/tests/conformance/test_oauth_client_registration_conformance.cpp new file mode 100644 index 000000000..3745bca27 --- /dev/null +++ b/tests/conformance/test_oauth_client_registration_conformance.cpp @@ -0,0 +1,378 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// +-------------------------------------------------------------------------+ +// | OAUTH 2.0 CLIENT REGISTRATION CONFORMANCE TESTS | +// | | +// | Spec: Matrix Client-Server API v1.19 — "Client registration", | +// | "Client metadata", "Redirect URI validation" and | +// | "Dynamic client registration flow" (RFC 7591) | +// | URL: ../../docs/matrix-v1.19-spec/client-server-api.md | +// +-------------------------------------------------------------------------+ +// +// Every requirement of those sections that `POST /_merovingian/oauth2/register` can show, through the endpoint. + +#include "../support/JsonTestSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include + +#include +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; + +// A registration of one redirect URI for `https://example.com/` as `application_type`. +[[nodiscard]] auto redirect_registration(std::string_view application_type, std::string_view redirect_uri) + -> std::string +{ + return R"({"client_uri":"https://example.com/","application_type":")" + std::string{application_type} + + R"(","redirect_uris":[")" + std::string{redirect_uri} + R"("],"token_endpoint_auth_method":"none"})"; +} + +[[nodiscard]] auto string_list(merovingian::canonicaljson::Object const& object, std::string_view key) + -> std::optional> +{ + auto const* array = object_member_as_array(object, key); + if (array == nullptr) + { + return std::nullopt; + } + auto out = std::vector{}; + for (auto const& item : *array) + { + auto const* text = std::get_if(&item.storage()); + if (text == nullptr) + { + return std::nullopt; + } + out.push_back(*text); + } + return out; +} + +[[nodiscard]] auto oauth_error_of(merovingian::homeserver::LocalHttpResponse const& response) -> std::string +{ + auto const body = parse_object(response.body); + auto const* error = string_member(body, "error"); + return error == nullptr ? std::string{} : *error; +} + +// The registration request of the spec's own example ("Dynamic client registration flow"). +constexpr auto spec_example_request = std::string_view{R"({ + "client_name": "My App", + "client_name#fr": "Mon application", + "client_uri": "https://example.com/", + "logo_uri": "https://example.com/logo.png", + "tos_uri": "https://example.com/tos.html", + "tos_uri#fr": "https://example.com/fr/tos.html", + "policy_uri": "https://example.com/policy.html", + "policy_uri#fr": "https://example.com/fr/policy.html", + "redirect_uris": ["https://app.example.com/callback"], + "token_endpoint_auth_method": "none", + "response_types": ["code"], + "grant_types": [ + "authorization_code", + "refresh_token", + "urn:ietf:params:oauth:grant-type:token-exchange" + ], + "application_type": "web" +})"}; + +} // namespace + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Dynamic client registration flow +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#dynamic-client-registration-flow +// +// "Upon successful registration, the server replies with an HTTP 201 Created response, with a JSON object containing +// the allocated client_id and all the registered metadata values." The spec's example: the unknown grant type and the +// locale-specific values are not registered, so they are not in the answer. +SCENARIO("the spec's registration example is answered 201 with a client_id and the registered metadata", + "[conformance][client-server][oauth][registration]") +{ + GIVEN("a homeserver with the OAuth 2.0 API on") + { + auto started = merovingian::homeserver::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + + WHEN("the spec's example registration request is posted") + { + auto const response = post_client_registration(started.runtime, std::string{spec_example_request}); + + THEN("it is 201 with a JSON object holding a client_id and every registered value") + { + // Spec MUST: "replies with an HTTP 201 Created response". + REQUIRE(response.status == 201U); + CHECK(response_header(response, "Content-Type") == "application/json"); + auto const body = parse_object(response.body); + auto const* client_id = string_member(body, "client_id"); + // Spec MUST: "a JSON object containing the allocated client_id". + REQUIRE(client_id != nullptr); + CHECK_FALSE(client_id->empty()); + // Spec MUST: "... and all the registered metadata values". + REQUIRE(string_member(body, "client_name") != nullptr); + CHECK(*string_member(body, "client_name") == "My App"); + REQUIRE(string_member(body, "client_uri") != nullptr); + CHECK(*string_member(body, "client_uri") == "https://example.com/"); + REQUIRE(string_member(body, "tos_uri") != nullptr); + CHECK(*string_member(body, "tos_uri") == "https://example.com/tos.html"); + REQUIRE(string_member(body, "policy_uri") != nullptr); + CHECK(*string_member(body, "policy_uri") == "https://example.com/policy.html"); + REQUIRE(string_member(body, "application_type") != nullptr); + CHECK(*string_member(body, "application_type") == "web"); + REQUIRE(string_member(body, "token_endpoint_auth_method") != nullptr); + CHECK(*string_member(body, "token_endpoint_auth_method") == "none"); + CHECK(string_list(body, "redirect_uris") == + std::vector{"https://app.example.com/callback"}); + CHECK(string_list(body, "response_types") == std::vector{"code"}); + } + + THEN("the unknown grant type is ignored and not in the answer") + { + REQUIRE(response.status == 201U); + auto const body = parse_object(response.body); + // Spec MUST: "The server MUST ignore values that it does not understand" (grant_types). + CHECK(string_list(body, "grant_types") == + std::vector{"authorization_code", "refresh_token"}); + } + + THEN("the localized values and the logo are not registered, so they are not in the answer") + { + REQUIRE(response.status == 201U); + auto const body = parse_object(response.body); + // Spec: "the server has not registered the locale-specific values ... which is why they are not + // present in the response". This server never registers a logo: it never fetches one. + CHECK(object_member(body, "client_name#fr") == nullptr); + CHECK(object_member(body, "tos_uri#fr") == nullptr); + CHECK(object_member(body, "policy_uri#fr") == nullptr); + CHECK(object_member(body, "logo_uri") == nullptr); + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Client metadata (`application_type`, `token_endpoint_auth_method`, `response_types`) +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#client-metadata +// +// "The homeserver MUST support the web and native values" of application_type; "The homeserver MUST support the none +// value" of token_endpoint_auth_method; response_types: "The server MUST ignore values that it does not understand." +SCENARIO("web and native clients, the none auth method and unknown response types are accepted", + "[conformance][client-server][oauth][registration]") +{ + GIVEN("a homeserver with the OAuth 2.0 API on") + { + auto started = merovingian::homeserver::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + + WHEN("a web client, a native client and a client with an unknown response type register") + { + auto const web = + post_client_registration(started.runtime, redirect_registration("web", "https://example.com/callback")); + auto const native = + post_client_registration(started.runtime, redirect_registration("native", "com.example.app:/callback")); + auto const unknown_type = post_client_registration( + started.runtime, R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],)" + R"("response_types":["code","code id_token"],"token_endpoint_auth_method":"none"})"); + + THEN("each is registered") + { + // Spec MUST: support application_type "web". + REQUIRE(web.status == 201U); + // Spec MUST: support application_type "native". + REQUIRE(native.status == 201U); + REQUIRE(unknown_type.status == 201U); + auto const web_body = parse_object(web.body); + auto const native_body = parse_object(native.body); + CHECK(*string_member(web_body, "application_type") == "web"); + CHECK(*string_member(native_body, "application_type") == "native"); + // Spec MUST: support token_endpoint_auth_method "none". + CHECK(*string_member(web_body, "token_endpoint_auth_method") == "none"); + // Spec MUST: ignore response types it does not understand; they are not registered. + CHECK(string_list(parse_object(unknown_type.body), "response_types") == + std::vector{"code"}); + } + } + + WHEN("a client omits application_type") + { + auto const response = post_client_registration( + started.runtime, R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"]})"); + + THEN("it is registered as a web client") + { + REQUIRE(response.status == 201U); + // Spec: application_type "Defaults to web if omitted." + CHECK(*string_member(parse_object(response.body), "application_type") == "web"); + } + } + + WHEN("a client's client_uri does not use https") + { + auto const response = post_client_registration( + started.runtime, R"({"client_uri":"http://example.com/","redirect_uris":["https://example.com/cb"]})"); + + THEN("it is refused as invalid client metadata") + { + // Spec MUST: client_uri "MUST use the https scheme"; RFC 7591 section 3.2.2 names the error. + REQUIRE(response.status == 400U); + CHECK(oauth_error_of(response) == "invalid_client_metadata"); + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Redirect URI validation ("Web clients") +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#redirect-uri-validation +// +// The spec's own valid and invalid web redirect URIs for the client URI https://example.com/. "The server MUST +// perform validation on redirect URIs"; RFC 7591 section 3.2.2 answers a refused one `invalid_redirect_uri`. +SCENARIO("the spec's web redirect URI examples are accepted and refused as it says", + "[conformance][client-server][oauth][registration][redirect]") +{ + GIVEN("a homeserver with the OAuth 2.0 API on") + { + auto started = merovingian::homeserver::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + constexpr auto valid = std::to_array({ + "https://example.com/callback", + "https://app.example.com/callback", + "https://example.com:5173/?query=value", + }); + constexpr auto invalid = std::to_array({ + "https://example.com/callback#fragment", + "http://example.com/callback", + "http://localhost/", + }); + + WHEN("a web client registers each example") + { + THEN("the valid ones are registered and the invalid ones refused with invalid_redirect_uri") + { + for (auto const uri : valid) + { + INFO(uri); + auto const response = post_client_registration(started.runtime, redirect_registration("web", uri)); + // Spec: listed among "the following are valid redirect URIs". + CHECK(response.status == 201U); + } + for (auto const uri : invalid) + { + INFO(uri); + auto const response = post_client_registration(started.runtime, redirect_registration("web", uri)); + // Spec MUST: no fragment; "MUST use the https scheme"; on the client URI's host. + CHECK(response.status == 400U); + CHECK(oauth_error_of(response) == "invalid_redirect_uri"); + } + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Redirect URI validation ("Native clients") +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#redirect-uri-validation +// +// The spec's own valid and invalid native redirect URIs for the client URI https://example.com/: a private-use scheme +// that is the reversed client host with no authority, or http on a loopback host with no port. +SCENARIO("the spec's native redirect URI examples are accepted and refused as it says", + "[conformance][client-server][oauth][registration][redirect]") +{ + GIVEN("a homeserver with the OAuth 2.0 API on") + { + auto started = merovingian::homeserver::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + constexpr auto valid = std::to_array({ + "com.example.app:/callback", + "com.example:/", + "com.example:callback", + "http://localhost/callback", + "http://127.0.0.1/callback", + "http://[::1]/callback", + }); + constexpr auto invalid = std::to_array({ + "example:/callback", + "com.example.app://callback", + "https://localhost/callback", + "http://localhost:1234/callback", + }); + + WHEN("a native client registers each example") + { + THEN("the valid ones are registered and the invalid ones refused with invalid_redirect_uri") + { + for (auto const uri : valid) + { + INFO(uri); + auto const response = + post_client_registration(started.runtime, redirect_registration("native", uri)); + // Spec: listed among "These are valid redirect URIs". + CHECK(response.status == 201U); + } + for (auto const uri : invalid) + { + INFO(uri); + auto const response = + post_client_registration(started.runtime, redirect_registration("native", uri)); + // Spec MUST: reversed client host as the scheme, no authority, loopback without a port. + CHECK(response.status == 400U); + CHECK(oauth_error_of(response) == "invalid_redirect_uri"); + } + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Dynamic client registration flow +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#dynamic-client-registration-flow +// +// "The server MUST NOT delete client registrations that have an active session." This server deletes idle clients to +// make room at its registration cap; one with a session is never among them. +SCENARIO("a client with a session is never deleted to make room for another", + "[conformance][client-server][oauth][registration][cap]") +{ + GIVEN("a homeserver that holds at most one client, and that client has a session") + { + auto started = merovingian::homeserver::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + rt.limits.max_oauth_clients = 1U; + auto const first = post_client_registration(rt, redirect_registration("web", "https://example.com/one")); + REQUIRE(first.status == 201U); + auto const client_id = *string_member(parse_object(first.body), "client_id"); + REQUIRE(merovingian::database::store_oauth_session( + rt.homeserver.database.persistent_store, + merovingian::database::PersistentOAuthSession{"@alice:example.org", "DEVICE", client_id, + "urn:matrix:client:api:*", 1U})); + + WHEN("a client with other metadata registers") + { + auto const second = post_client_registration(rt, redirect_registration("web", "https://example.com/two")); + + THEN("it is refused and the client with a session is still registered") + { + CHECK(second.status == 503U); + CHECK(oauth_error_of(second) == "temporarily_unavailable"); + // Spec MUST NOT: delete a client registration that has an active session. + REQUIRE(merovingian::database::find_oauth_client(rt.homeserver.database.persistent_store, client_id) != + nullptr); + } + } + } +} diff --git a/tests/conformance/test_route_query_conformance.cpp b/tests/conformance/test_route_query_conformance.cpp index d57f46e28..bd1aae1de 100644 --- a/tests/conformance/test_route_query_conformance.cpp +++ b/tests/conformance/test_route_query_conformance.cpp @@ -41,8 +41,12 @@ using merovingian::homeserver::ClientServerRuntime; auto security = merovingian::config::SecurityConfig{}; security.secrets.master_key_file = merovingian::tests::shared_master_key_file(); merovingian::tests::enable_token_registration(security); + // The OAuth 2.0 API is on so that its fixed routes are served and can be checked like the others. + auto server = merovingian::config::ServerConfig{}; + server.public_baseurl = "https://matrix.example.org"; + server.oauth.enabled = true; return { - merovingian::config::ServerConfig{}, + std::move(server), merovingian::config::ListenersConfig{}, merovingian::tests::in_memory_database_config(), security, @@ -105,12 +109,13 @@ 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", ""}, {"GET", "/_matrix/client/v1/auth_metadata", ""}, {"GET", "/_matrix/client/unstable/org.matrix.msc2965/auth_metadata", ""}, + {"POST", "/_merovingian/oauth2/register", "{}"}, {"POST", "/_matrix/client/v3/register/email/requestToken", "{}"}, {"POST", "/_matrix/client/v3/register/msisdn/requestToken", "{}"}, {"POST", "/_matrix/client/v3/register", "{}"}, diff --git a/tests/integration/test_oauth_client_registration_flow.cpp b/tests/integration/test_oauth_client_registration_flow.cpp new file mode 100644 index 000000000..5f205a388 --- /dev/null +++ b/tests/integration/test_oauth_client_registration_flow.cpp @@ -0,0 +1,355 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// `POST /_merovingian/oauth2/register` through the client-server dispatcher: one row per accepted metadata whatever the +// request's form, a repeat that costs no commit, the route and body gates, the rate-limit tier, CORS, the read-back of +// a stored client, and the registration cap (ADR-0779, ADR-0780, ADR-0781). + +#include "../support/JsonTestSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/config/ServerConfig.hpp" +#include "merovingian/database/OAuthClientStoreResult.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentOAuthClient.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/homeserver/OAuthClientRegistration.hpp" + +#include + +#include +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace db = merovingian::database; +namespace hs = merovingian::homeserver; + +// A web client of https://example.com/ with one redirect URI under `path`. +[[nodiscard]] auto web_client(std::string_view path) -> std::string +{ + return R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/)" + std::string{path} + + R"("],"token_endpoint_auth_method":"none"})"; +} + +[[nodiscard]] auto client_id_of(hs::LocalHttpResponse const& response) -> std::string +{ + auto const body = parse_object(response.body); + auto const* client_id = string_member(body, "client_id"); + return client_id == nullptr ? std::string{} : *client_id; +} + +[[nodiscard]] auto oauth_error_of(hs::LocalHttpResponse const& response) -> std::string +{ + auto const body = parse_object(response.body); + auto const* error = string_member(body, "error"); + return error == nullptr ? std::string{} : *error; +} + +// Stores a client row directly, with a chosen last use, as a registration long ago would have left it. +auto seed_client(db::PersistentStore& store, std::string client_id, std::uint64_t last_used_at_ms) -> void +{ + REQUIRE(db::store_oauth_client(store, db::PersistentOAuthClient{std::move(client_id), web_client("seeded"), + last_used_at_ms, last_used_at_ms}) == + db::OAuthClientStoreResult::inserted); +} + +} // namespace + +SCENARIO("one accepted metadata is one client whatever the request's form", "[integration][oauth][registration]") +{ + GIVEN("a homeserver with the OAuth 2.0 API on") + { + auto started = hs::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + auto& store = rt.homeserver.database.persistent_store; + + WHEN("the same metadata is sent with another key order, an unknown key and a repeated array entry") + { + auto const first = post_client_registration( + rt, R"({"client_uri":"https://example.com/","redirect_uris":["https://example.com/cb"],)" + R"("grant_types":["authorization_code","refresh_token"]})"); + auto const commits_before = db::committed_transaction_count(store); + auto const second = post_client_registration( + rt, R"({"x_vendor":1,"grant_types":["refresh_token","authorization_code","refresh_token"],)" + R"("redirect_uris":["https://example.com/cb","https://example.com/cb"],)" + R"("client_uri":"https://example.com/"})"); + auto const commits_after = db::committed_transaction_count(store); + + THEN("both are answered with the same client ID, one row is held and the repeat commits nothing") + { + REQUIRE(first.status == 201U); + REQUIRE(second.status == 201U); + CHECK_FALSE(client_id_of(first).empty()); + CHECK(client_id_of(first) == client_id_of(second)); + CHECK(db::oauth_client_count(store) == 1U); + CHECK(commits_after == commits_before); + CHECK(response_header(second, "Cache-Control") == "no-store"); + auto const first_body = parse_object(first.body); + auto const second_body = parse_object(second.body); + auto const* issued_first = int_member(first_body, "client_id_issued_at"); + auto const* issued_second = int_member(second_body, "client_id_issued_at"); + REQUIRE(issued_first != nullptr); + REQUIRE(issued_second != nullptr); + CHECK(*issued_first == *issued_second); + } + } + + WHEN("two clients differ in one redirect URI") + { + auto const one = post_client_registration(rt, web_client("one")); + auto const two = post_client_registration(rt, web_client("two")); + + THEN("each has its own client ID and row") + { + REQUIRE(one.status == 201U); + REQUIRE(two.status == 201U); + CHECK(client_id_of(one) != client_id_of(two)); + CHECK(db::oauth_client_count(store) == 2U); + } + } + + WHEN("a registered client, a stored row that no longer validates and an unknown ID are read back") + { + auto const registered = post_client_registration(rt, web_client("cb")); + REQUIRE(registered.status == 201U); + REQUIRE(db::store_oauth_client( + store, db::PersistentOAuthClient{"stored-invalid", R"({"client_uri":1})", 1U, 1U}) == + db::OAuthClientStoreResult::inserted); + + THEN("only the registered client is found, with its metadata") + { + auto const found = hs::find_registered_oauth_client(rt.homeserver, client_id_of(registered)); + REQUIRE(found.has_value()); + CHECK(hs::oauth_client_id_of(rt.homeserver, *found) == client_id_of(registered)); + CHECK_FALSE(hs::find_registered_oauth_client(rt.homeserver, "stored-invalid").has_value()); + CHECK_FALSE(hs::find_registered_oauth_client(rt.homeserver, "no-such-client").has_value()); + } + } + } +} + +SCENARIO("the registration route and its body are gated", "[integration][oauth][registration]") +{ + GIVEN("a homeserver with the OAuth 2.0 API off") + { + auto started = hs::start_client_server(oauth_registration_config(false)); + REQUIRE(started.started); + + WHEN("a client registers") + { + auto const response = post_client_registration(started.runtime, web_client("cb")); + + THEN("the route does not exist") + { + REQUIRE(response.status == 404U); + CHECK(response.body.find("M_UNRECOGNIZED") != std::string::npos); + CHECK(db::oauth_client_count(started.runtime.homeserver.database.persistent_store) == 0U); + } + } + } + + GIVEN("a homeserver with the OAuth 2.0 API on") + { + auto started = hs::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + + WHEN("the endpoint is asked with GET") + { + auto const response = post_client_registration(rt, {}, {}, "GET"); + + THEN("it is 405 naming POST") + { + REQUIRE(response.status == 405U); + CHECK(response_header(response, "Allow") == "POST"); + } + } + + WHEN("bodies that are too large, not JSON by type, or malformed are sent") + { + auto const over_cap = std::string(db::max_oauth_client_metadata_bytes + 1U, ' ') + web_client("cb"); + auto const over_transport_cap = std::string(rt.limits.max_body_bytes + 1U, ' ') + web_client("cb"); + auto const oversized = post_client_registration(rt, over_cap); + auto const over_general_cap = post_client_registration(rt, over_transport_cap); + auto const wrong_type = post_client_registration(rt, web_client("cb"), "text/plain"); + auto const no_type = post_client_registration(rt, web_client("cb"), {}); + auto const malformed = post_client_registration(rt, R"({"client_uri":)"); + auto const charset = post_client_registration(rt, web_client("cb"), "application/json; charset=utf-8"); + + THEN("each refusal is 400 invalid_client_metadata and stores nothing, and a charset is accepted") + { + for (auto const* refused : + std::to_array({&oversized, &over_general_cap, &wrong_type, &no_type, &malformed})) + { + CHECK(refused->status == 400U); + CHECK(oauth_error_of(*refused) == "invalid_client_metadata"); + CHECK(response_header(*refused, "Cache-Control") == "no-store"); + } + CHECK(charset.status == 201U); + CHECK(db::oauth_client_count(rt.homeserver.database.persistent_store) == 1U); + } + } + } +} + +SCENARIO("registration takes the auth-sensitive rate limit and carries the CORS headers", + "[integration][oauth][registration][rate-limit][cors]") +{ + GIVEN("a homeserver with the OAuth 2.0 API on and the default rate limits") + { + auto started = hs::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + + WHEN("one address registers 21 times in a minute") + { + auto last_status = std::uint16_t{0U}; + auto statuses_ok = true; + for (auto attempt = 0; attempt < 21; ++attempt) + { + auto const response = post_client_registration(rt, web_client("cb")); + last_status = response.status; + if (attempt < 20 && response.status != 201U) + { + statuses_ok = false; + } + } + + THEN("the first 20 are answered and the 21st is limited") + { + // The auth_sensitive tier allows 20 a minute per address (ADR-0775). + CHECK(statuses_ok); + CHECK(last_status == 429U); + } + } + + WHEN("a browser preflights and posts the registration, and preflights login") + { + auto preflight = hs::LocalHttpRequest{"OPTIONS", std::string{oauth_register_path}, {}, {}}; + preflight.headers.push_back({"Origin", "https://app.example.com"}); + auto login_preflight = preflight; + login_preflight.target = "/_matrix/client/v3/login"; + auto const register_options = hs::handle_client_server_request(rt, preflight, false).response; + auto const login_options = hs::handle_client_server_request(rt, login_preflight, false).response; + auto post = preflight; + post.method = "POST"; + post.body = web_client("cb"); + post.headers.push_back({"Content-Type", "application/json"}); + auto const registered = hs::handle_client_server_request(rt, post, false).response; + + THEN("the registration answers carry the same CORS headers as login") + { + REQUIRE(register_options.status == 200U); + for (auto const name : {"Access-Control-Allow-Origin", "Access-Control-Allow-Methods", + "Access-Control-Allow-Headers", "Access-Control-Max-Age", "Vary"}) + { + INFO(name); + CHECK_FALSE(response_header(register_options, name).empty()); + CHECK(response_header(register_options, name) == response_header(login_options, name)); + } + REQUIRE(registered.status == 201U); + CHECK(response_header(registered, "Access-Control-Allow-Origin") == + response_header(login_options, "Access-Control-Allow-Origin")); + CHECK(response_header(registered, "X-Content-Type-Options") == "nosniff"); + } + } + } +} + +SCENARIO("at the registration cap idle clients go least recently used first, and protected ones never", + "[integration][oauth][registration][cap]") +{ + GIVEN("a homeserver holding four clients at a cap of four: one with a session, one pending, two idle") + { + auto started = hs::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + auto& store = rt.homeserver.database.persistent_store; + rt.limits.max_oauth_clients = 4U; + seed_client(store, "with-session", 1U); + seed_client(store, "pending", 2U); + seed_client(store, "idle-older", 3U); + seed_client(store, "idle-newer", 4U); + REQUIRE(db::store_oauth_session( + store, db::PersistentOAuthSession{"@alice:example.org", "DEVICE", "with-session", "openid", 1U})); + rt.homeserver.test_oauth_pending_authorisation = [](std::string_view client_id) { + return client_id == "pending"; + }; + + WHEN("one client registers") + { + auto const response = post_client_registration(rt, web_client("first")); + + THEN("only the least recently used idle client was removed") + { + REQUIRE(response.status == 201U); + CHECK(db::oauth_client_count(store) == 4U); + CHECK(db::find_oauth_client(store, "idle-older") == nullptr); + CHECK(db::find_oauth_client(store, "idle-newer") != nullptr); + } + } + + WHEN("a flood of distinct clients registers") + { + for (auto index = 0; index < 12; ++index) + { + auto const response = post_client_registration(rt, web_client("flood-" + std::to_string(index))); + CHECK(response.status == 201U); + } + + THEN("the client with a session and the pending one are still held, and the cap is kept") + { + CHECK(db::oauth_client_count(store) == 4U); + // Spec MUST NOT: delete a client registration that has an active session. + CHECK(db::find_oauth_client(store, "with-session") != nullptr); + CHECK(db::find_oauth_client(store, "pending") != nullptr); + CHECK(db::find_oauth_client(store, "idle-older") == nullptr); + CHECK(db::find_oauth_client(store, "idle-newer") == nullptr); + } + } + } + + GIVEN("a homeserver at a cap of two whose clients are both protected") + { + auto started = hs::start_client_server(oauth_registration_config()); + REQUIRE(started.started); + auto& rt = started.runtime; + auto& store = rt.homeserver.database.persistent_store; + rt.limits.max_oauth_clients = 2U; + seed_client(store, "with-session", 1U); + seed_client(store, "pending", 2U); + REQUIRE(db::store_oauth_session( + store, db::PersistentOAuthSession{"@alice:example.org", "DEVICE", "with-session", "openid", 1U})); + rt.homeserver.test_oauth_pending_authorisation = [](std::string_view client_id) { + return client_id == "pending"; + }; + + WHEN("a new client registers") + { + auto const refused = post_client_registration(rt, web_client("new")); + + THEN("the new one is 503 temporarily_unavailable with nothing stored or removed") + { + REQUIRE(refused.status == 503U); + CHECK(oauth_error_of(refused) == "temporarily_unavailable"); + CHECK(response_header(refused, "Cache-Control") == "no-store"); + CHECK(db::oauth_client_count(store) == 2U); + CHECK(db::find_oauth_client(store, "with-session") != nullptr); + CHECK(db::find_oauth_client(store, "pending") != nullptr); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index 95ce4b04d..b5fbd823f 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -334,6 +334,7 @@ shell = find_program('sh') 'unit/test_config_reload_plan.cpp', 'unit/test_config_reload_policy.cpp', 'unit/test_crypto.cpp', + 'unit/test_crypto_oauth_client_id.cpp', 'unit/test_crypto_token_key_cache.cpp', 'unit/test_database_backend_config.cpp', 'unit/test_database_connection_pool.cpp', @@ -642,6 +643,7 @@ shell = find_program('sh') 'conformance/test_canonicaljson_serializer.cpp', 'conformance/test_client_server_conformance.cpp', 'conformance/test_oauth_metadata_conformance.cpp', + 'conformance/test_oauth_client_registration_conformance.cpp', 'conformance/test_open_registration_conformance.cpp', 'conformance/test_account_lifecycle_conformance.cpp', 'conformance/test_device_lifecycle_conformance.cpp', @@ -850,6 +852,7 @@ shell = find_program('sh') 'integration/test_media_thumbnail_flow.cpp', 'integration/test_media_thumbnail_revalidation_flow.cpp', 'integration/test_security_audit_remote_media.cpp', + 'integration/test_oauth_client_registration_flow.cpp', 'integration/test_oauth_metadata_flow.cpp', 'integration/test_observability_flow.cpp', 'integration/test_operator_admin_flow.cpp', diff --git a/tests/support/AGENTS.md b/tests/support/AGENTS.md index c505eb69e..8eb70b739 100644 --- a/tests/support/AGENTS.md +++ b/tests/support/AGENTS.md @@ -31,6 +31,7 @@ Shared test utilities used across unit, conformance, and integration tests. | `CrossSigningSet.hpp` | `CrossSigningSet`: a user's master, self-signing and user-signing keys, the latter two signed by the master key | | `EduRelayChannels.hpp` / `EduRelayContext.hpp` | `EduRelayChannels` and `make_edu_relay_channels()`: a main and a worker `IpcChannel` over a real authenticated transport, for the downstream EDU relay fixtures. Creates a `socketpair`, so it is an I/O exception | | `InMemoryDatabaseConfig.hpp` | `in_memory_database_config()`: selects the process-local database for tests that do not exercise persistence (production config parsing does not expose it) | +| `OAuthRegistrationSupport.hpp` | `oauth_registration_config()` (OAuth on or off, `public_baseurl`, in-memory database, shared master key), `post_client_registration()` and `response_header()` for the OAuth 2.0 client registration conformance and integration scenarios | | `E2eeCapsSupport.hpp` | `caps_config()` and a logged-in-user helper for the CSAZ-10 per-user end-to-end key and filter cap scenarios | | `MembershipFixtureSupport.hpp` | Helpers that build membership PDUs (send_join, send_leave, send_knock bodies) with the `auth_events` and `prev_events` a real server would send (ADR-0064 phase B2) | | `MembershipAcceptorFixture.hpp` / `Genesis.hpp` | A local server "local.example.org" with a public room version 10 and a local joined admin (`seed_room_genesis`), and the builders for membership PDUs and envelopes the membership acceptor's unit and conformance scenarios share (`build_event_json`, `make_envelope`, `seed_accepted_event`, `config_with_sqlite`) | diff --git a/tests/support/OAuthRegistrationSupport.hpp b/tests/support/OAuthRegistrationSupport.hpp new file mode 100644 index 000000000..5b2220818 --- /dev/null +++ b/tests/support/OAuthRegistrationSupport.hpp @@ -0,0 +1,73 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +// Shared by the OAuth 2.0 client registration conformance and integration scenarios: a homeserver config with the +// OAuth 2.0 API on or off, and a POST to the registration endpoint as a client sends it. + +#include "InMemoryDatabaseConfig.hpp" +#include "MasterKey.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/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include +#include +#include + +namespace merovingian::tests +{ + +inline constexpr auto oauth_register_path = std::string_view{"/_merovingian/oauth2/register"}; + +// A homeserver at https://matrix.example.org with the OAuth 2.0 API on (or off), an in-memory database and the +// shared test master key, which derives the client ID key. +[[nodiscard]] inline auto oauth_registration_config(bool oauth_enabled = true, + config::ServerConfig server = config::ServerConfig{}) + -> config::Config +{ + auto security = config::SecurityConfig{}; + security.secrets.master_key_file = shared_master_key_file(); + server.public_baseurl = "https://matrix.example.org"; + server.oauth.enabled = oauth_enabled; + return { + std::move(server), config::ListenersConfig{}, in_memory_database_config(), + std::move(security), config::ClientRateLimitsConfig{}, config::LogModulesConfig{}, + }; +} + +// POST `body` to the registration endpoint with `content_type` (no Content-Type header when empty). +[[nodiscard]] inline auto post_client_registration(homeserver::ClientServerRuntime& runtime, std::string body, + std::string_view content_type = "application/json", + std::string method = "POST") -> homeserver::LocalHttpResponse +{ + auto request = + homeserver::LocalHttpRequest{std::move(method), std::string{oauth_register_path}, {}, std::move(body)}; + if (!content_type.empty()) + { + request.headers.push_back({"Content-Type", std::string{content_type}}); + } + return homeserver::handle_client_server_request(runtime, request, /*can_wait=*/false).response; +} + +// The value of the response header `name` (exact name match, as the dispatcher writes them), or empty. +[[nodiscard]] inline auto response_header(homeserver::LocalHttpResponse const& response, std::string_view name) + -> std::string +{ + for (auto const& [header_name, value] : response.headers) + { + if (header_name == name) + { + return value; + } + } + return {}; +} + +} // namespace merovingian::tests diff --git a/tests/unit/test_crypto_oauth_client_id.cpp b/tests/unit/test_crypto_oauth_client_id.cpp new file mode 100644 index 000000000..ec2e310e6 --- /dev/null +++ b/tests/unit/test_crypto_oauth_client_id.cpp @@ -0,0 +1,116 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// The OAuth 2.0 client ID (plan P2, ADR-0779): a keyed BLAKE2b-256 hash of the accepted client metadata, under a key +// derived from the master key with a label of its own, written in unpadded URL-safe base64. + +#include "merovingian/crypto/OAuthClientId.hpp" +#include "merovingian/crypto/TokenKey.hpp" + +#include + +#include +#include +#include +#include + +namespace +{ + +[[nodiscard]] auto client_id_key(std::uint8_t fill) -> merovingian::crypto::TokenHmacKey +{ + auto const material = std::vector(32U, fill); + auto key = merovingian::crypto::derive_oauth_client_id_key(material); + REQUIRE(key.has_value()); + return *key; +} + +[[nodiscard]] auto is_url_safe(std::string const& text) -> bool +{ + return std::ranges::all_of(text, [](char const value) { + return (value >= 'A' && value <= 'Z') || (value >= 'a' && value <= 'z') || (value >= '0' && value <= '9') || + value == '-' || value == '_'; + }); +} + +} // namespace + +SCENARIO("The OAuth client ID key is separate from every access-token key", "[crypto][token_key][oauth][boundary]") +{ + GIVEN("one master key byte string") + { + auto const material = std::vector(32U, 0x5AU); + + WHEN("the client ID key and both access-token keys are derived from it") + { + auto const client_id = merovingian::crypto::derive_oauth_client_id_key(material); + auto const v4 = merovingian::crypto::derive_token_hmac_key(material); + auto const v3 = merovingian::crypto::derive_token_hmac_key_v3(material); + + THEN("all three derivations succeed and the client ID key equals neither token key") + { + REQUIRE(client_id.has_value()); + REQUIRE(v4.has_value()); + REQUIRE(v3.has_value()); + CHECK(client_id->bytes != v4->bytes); + CHECK(client_id->bytes != v3->bytes); + } + } + + WHEN("the client ID key is derived from empty material") + { + auto const refused = merovingian::crypto::derive_oauth_client_id_key(std::vector{}); + + THEN("it is refused") + { + CHECK_FALSE(refused.has_value()); + } + } + } +} + +SCENARIO("A client ID is a deterministic keyed hash in URL-safe characters", "[crypto][oauth][client_id]") +{ + GIVEN("a client ID key and two canonical metadata texts") + { + auto const key = client_id_key(0x11U); + auto const metadata = std::string{R"({"application_type":"web","client_uri":"https://a.example"})"}; + auto const other = std::string{R"({"application_type":"web","client_uri":"https://b.example"})"}; + + WHEN("the ID of each is computed, the first twice") + { + auto const first = merovingian::crypto::oauth_client_id(metadata, key); + auto const again = merovingian::crypto::oauth_client_id(metadata, key); + auto const different = merovingian::crypto::oauth_client_id(other, key); + + THEN("the same metadata gives the same ID and other metadata another one") + { + REQUIRE(first.has_value()); + REQUIRE(again.has_value()); + REQUIRE(different.has_value()); + CHECK(*first == *again); + CHECK(*first != *different); + } + + THEN("the ID is 43 characters of A-Z a-z 0-9 - and _") + { + REQUIRE(first.has_value()); + CHECK(first->size() == merovingian::crypto::oauth_client_id_chars); + CHECK(is_url_safe(*first)); + } + } + + WHEN("the same metadata is hashed under the key of another master key") + { + auto const here = merovingian::crypto::oauth_client_id(metadata, key); + auto const elsewhere = merovingian::crypto::oauth_client_id(metadata, client_id_key(0x22U)); + + THEN("the IDs differ, so an ID cannot be computed without this server's key") + { + REQUIRE(here.has_value()); + REQUIRE(elsewhere.has_value()); + CHECK(*here != *elsewhere); + } + } + } +} diff --git a/tests/unit/test_http_rate_limit_tiers.cpp b/tests/unit/test_http_rate_limit_tiers.cpp index c115d7881..559e2f075 100644 --- a/tests/unit/test_http_rate_limit_tiers.cpp +++ b/tests/unit/test_http_rate_limit_tiers.cpp @@ -63,6 +63,12 @@ SCENARIO("Rate-limit tiers classify client-server routes explicitly", "[http][ra REQUIRE(tier_of("/_matrix/client/v3/register/email/requestToken") == RateLimitTier::auth_sensitive); // Method-agnostic: a GET against /login is the same surface. REQUIRE(tier_of("/_matrix/client/v3/login/sso/redirect") == RateLimitTier::auth_sensitive); + // The OAuth 2.0 API under this server's own namespace: every endpoint and page. + REQUIRE(tier_of("/_merovingian/oauth2/register") == RateLimitTier::auth_sensitive); + REQUIRE(tier_of("/_merovingian/oauth2/authorize?client_id=x") == RateLimitTier::auth_sensitive); + REQUIRE(tier_of("/_merovingian/oauth2/token") == RateLimitTier::auth_sensitive); + REQUIRE(tier_of("/_merovingian/oauth2/revoke") == RateLimitTier::auth_sensitive); + REQUIRE(tier_of("/_merovingian/account") == RateLimitTier::auth_sensitive); // media: both media trees. REQUIRE(tier_of("/_matrix/media/v3/download/a/b") == RateLimitTier::media); diff --git a/tests/unit/test_http_response_head.cpp b/tests/unit/test_http_response_head.cpp index 970622d86..ff1c6ae43 100644 --- a/tests/unit/test_http_response_head.cpp +++ b/tests/unit/test_http_response_head.cpp @@ -144,6 +144,7 @@ SCENARIO("Statuses the server answers with carry their reason phrase", "[http][r THEN("each has its RFC 9110 phrase, and an unlisted status has none") { REQUIRE(merovingian::http::reason_phrase(200U) == "OK"); + REQUIRE(merovingian::http::reason_phrase(201U) == "Created"); REQUIRE(merovingian::http::reason_phrase(202U) == "Accepted"); REQUIRE(merovingian::http::reason_phrase(302U) == "Found"); REQUIRE(merovingian::http::reason_phrase(303U) == "See Other"); From e383c4c55f6f02772a274519f088b4704261291e Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 03:31:03 +0000 Subject: [PATCH 12/42] Wrap the 1.1.0 release notes within the changelog's line limit Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d1fe8b2e8..9d714eba4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,10 +48,11 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Release notes 1.1.0 is in development. A configuration that sets any `server.oidc.*` key is now refused at start-up: remove those -keys and set `server.oauth.enabled` instead (ADR-0764). The metadata names the authorisation, token and revocation endpoints, -which later 1.1.0 changes serve (registration is served now); leave `server.oauth.enabled` off until then. 1.1.0 migrates -the database: on first start it applies migration 002, which adds two empty tables and changes no existing one. A -1.0.x server refuses the migrated database, so back it up before upgrading if you may need to go back. +keys and set `server.oauth.enabled` instead (ADR-0764). The metadata names the authorisation, token and revocation +endpoints, which later 1.1.0 changes serve (registration is served now); leave `server.oauth.enabled` off until +then. 1.1.0 migrates the database: on first start it applies migration 002, which adds two empty tables and changes +no existing one. A 1.0.x server refuses the migrated database, so back it up before upgrading if you may need to go +back. # Version 1.0.2 From 96d0343ec5ed2c7b07cba07d604a57ddf432f3d7 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 04:28:51 +0000 Subject: [PATCH 13/42] Add the OAuth 2.0 phase 5a building blocks (ADR-0782 to ADR-0786) - PendingAuthorisationStore and AuthorizationCodeStore: in memory on HomeserverRuntime, 32-byte secrets kept as hashes, a digest index with constant-time confirmation, bounded (8192, 16 per address; 8192 codes), never evicting a live entry. oauth_client_has_pending_authorisation is answered from them in O(1); the test seam is gone. The idle-client walk examines at most max_idle_client_rows_examined rows. - verify_login_credentials is the password check of POST /login, moved unchanged; verify_password_login adds the shared account-state gate. create_local_account makes /register's username checks and every registration gate with the caller's client key; /register passes 127.0.0.1 as before. - sanitized_http_target drops the whole query under /_merovingian/oauth2 and /_merovingian/account. - LocalHttpResponse::page: the boundary adds no CORS header to a page and wrap() leaves it alone. - Referrer-Policy same-origin on pages, and form_post_origin_is_accepted. Co-Authored-By: Claude Opus 5.5 --- .../references/module-invariants.md | 10 +- CHANGELOG.md | 9 + ...-names-only-a-validated-redirect-origin.md | 2 +- ...-last-use-is-written-at-most-once-a-day.md | 2 +- ...memory-hashed-bounded-and-never-evicted.md | 77 +++ ...y-the-matrix-routes-and-the-oauth-pages.md | 72 +++ ...orm-post-must-name-this-server-s-origin.md | 53 ++ ...ed-in-its-type-and-gets-no-cors-headers.md | 48 ++ ...ery-of-an-oauth-request-is-never-logged.md | 49 ++ docs/adr/index.md | 5 + docs/auth-identity.md | 27 + docs/debug-logging.md | 4 + docs/http-transport.md | 7 + docs/observability-audit.md | 5 + docs/security-coding-rules.md | 23 + docs/todos/oauth-2-0-api.md | 4 +- include/merovingian/database/OAuthStore.hpp | 5 +- include/merovingian/database/OAuthTables.hpp | 16 +- .../homeserver/AccountCreationRequest.hpp | 26 + .../merovingian/homeserver/AuthService.hpp | 24 + .../AuthorizationCodeRedemption.hpp | 34 ++ .../homeserver/AuthorizationCodeStore.hpp | 90 +++ .../homeserver/AuthorizationGrant.hpp | 26 + .../homeserver/ClientServerRuntime.hpp | 5 + .../homeserver/HashedSecretTable.hpp | 137 +++++ .../homeserver/HomeserverRuntime.hpp | 11 +- .../homeserver/LocalHttpResponse.hpp | 5 + .../merovingian/homeserver/OAuthSecret.hpp | 27 + .../homeserver/PasswordLoginRequest.hpp | 24 + .../homeserver/PasswordLoginVerification.hpp | 40 ++ .../homeserver/PendingAuthorisation.hpp | 47 ++ .../homeserver/PendingAuthorisationStore.hpp | 120 ++++ .../merovingian/homeserver/RetentionSweep.hpp | 14 +- include/merovingian/oauth/FormPostOrigin.hpp | 28 + include/merovingian/oauth/PageHeaders.hpp | 2 +- include/merovingian/oauth/ResponseMode.hpp | 18 + src/auth/AGENTS.md | 11 + src/database/OAuthTables.cpp | 2 +- src/homeserver/AGENTS.md | 16 +- src/homeserver/AuthService.cpp | 517 +++++++++++------- src/homeserver/AuthorizationCodeStore.cpp | 97 ++++ src/homeserver/ClientServerRuntime.cpp | 53 +- src/homeserver/OAuthClientRegistration.cpp | 14 +- src/homeserver/OAuthSecret.cpp | 24 + src/homeserver/PendingAuthorisationStore.cpp | 169 ++++++ src/homeserver/RetentionSweep.cpp | 21 +- src/homeserver/meson.build | 3 + src/oauth/AGENTS.md | 9 +- src/oauth/FormPostOrigin.cpp | 42 ++ src/oauth/Page.cpp | 2 +- src/oauth/PageHeaders.cpp | 2 +- src/oauth/meson.build | 1 + src/observability/Observability.cpp | 23 +- .../test_oauth_account_creation_flow.cpp | 272 +++++++++ .../test_oauth_client_registration_flow.cpp | 40 +- .../integration/test_oauth_log_query_flow.cpp | 99 ++++ .../test_oauth_password_login_flow.cpp | 331 +++++++++++ .../integration/test_retention_sweep_flow.cpp | 43 +- tests/meson.build | 7 + tests/support/ConsoleLogCapture.hpp | 5 +- tests/unit/test_database_oauth_store.cpp | 57 ++ .../test_oauth_authorization_code_store.cpp | 256 +++++++++ tests/unit/test_oauth_form_post_origin.cpp | 118 ++++ tests/unit/test_oauth_page.cpp | 6 +- tests/unit/test_oauth_page_response.cpp | 106 ++++ ...test_oauth_pending_authorisation_store.cpp | 374 +++++++++++++ tests/unit/test_observability.cpp | 52 +- 67 files changed, 3586 insertions(+), 282 deletions(-) create mode 100644 docs/adr/0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md create mode 100644 docs/adr/0783-login-verification-and-account-creation-are-one-function-each-shared-by-the-matrix-routes-and-the-oauth-pages.md create mode 100644 docs/adr/0784-oauth-pages-use-a-same-origin-referrer-policy-and-a-form-post-must-name-this-server-s-origin.md create mode 100644 docs/adr/0785-an-oauth-page-response-is-marked-in-its-type-and-gets-no-cors-headers.md create mode 100644 docs/adr/0786-the-query-of-an-oauth-request-is-never-logged.md create mode 100644 include/merovingian/homeserver/AccountCreationRequest.hpp create mode 100644 include/merovingian/homeserver/AuthorizationCodeRedemption.hpp create mode 100644 include/merovingian/homeserver/AuthorizationCodeStore.hpp create mode 100644 include/merovingian/homeserver/AuthorizationGrant.hpp create mode 100644 include/merovingian/homeserver/HashedSecretTable.hpp create mode 100644 include/merovingian/homeserver/OAuthSecret.hpp create mode 100644 include/merovingian/homeserver/PasswordLoginRequest.hpp create mode 100644 include/merovingian/homeserver/PasswordLoginVerification.hpp create mode 100644 include/merovingian/homeserver/PendingAuthorisation.hpp create mode 100644 include/merovingian/homeserver/PendingAuthorisationStore.hpp create mode 100644 include/merovingian/oauth/FormPostOrigin.hpp create mode 100644 include/merovingian/oauth/ResponseMode.hpp create mode 100644 src/homeserver/AuthorizationCodeStore.cpp create mode 100644 src/homeserver/OAuthSecret.cpp create mode 100644 src/homeserver/PendingAuthorisationStore.cpp create mode 100644 src/oauth/FormPostOrigin.cpp create mode 100644 tests/integration/test_oauth_account_creation_flow.cpp create mode 100644 tests/integration/test_oauth_log_query_flow.cpp create mode 100644 tests/integration/test_oauth_password_login_flow.cpp create mode 100644 tests/unit/test_oauth_authorization_code_store.cpp create mode 100644 tests/unit/test_oauth_form_post_origin.cpp create mode 100644 tests/unit/test_oauth_page_response.cpp create mode 100644 tests/unit/test_oauth_pending_authorisation_store.cpp diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index d4ddde8f7..375510be2 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -182,8 +182,11 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that - Work under the lock is linear in request input. Per-user row counts are capped with the documented errcodes: `400 M_TOO_LARGE` (ADR-0173). `#Work under the runtime lock is bounded by the request` - OAuth answers come from `oauth_json_response` / `oauth_error_response`; client IDs only from `oauth_client_id_of`; - registrations are capped and never evict a client with a session (ADR-0779 to ADR-0781). - `src/homeserver/AGENTS.md#OAuth 2.0 API (ADR-0760, ADR-0773)` + registrations are capped and never evict a client with a session (ADR-0779 to ADR-0781). Pending authorisations + and codes live only in their hashed, bounded, never-evicting stores (ADR-0782); a password is checked only by + `verify_login_credentials` and a session-less account made only by `create_local_account` (ADR-0783); a page is + marked `LocalHttpResponse::page` and gets no CORS header (ADR-0785); an OAuth target's query is never logged + (ADR-0786). `src/homeserver/AGENTS.md#OAuth 2.0 API (ADR-0760, ADR-0773)` - Worker frames are untrusted. Relayed PDUs are re-verified with main's resolver **before** taking `runtime.mutex`, and the envelope is rebuilt from the verified event (ADR-0171). `#Federation worker relays are untrusted input` @@ -250,7 +253,8 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that - Client addresses only through `ParsedUri::read`; redirect URIs matched byte for byte by `match_redirect_uri` (ADR-0770). No redirect before the client and its redirect URI are validated. - HTML only through `Page` with `HtmlText` or compile-time parts; every page sends `page_headers()`; only a matched - redirect URI adds a `form-action` source (ADR-0772). PKCE `S256` only, constant-time. + redirect URI adds a `form-action` source (ADR-0772). PKCE `S256` only, constant-time. Pages send + `Referrer-Policy: same-origin`, and a form post is accepted only by `form_post_origin_is_accepted` (ADR-0784). - Every absolute OAuth address comes from `OAuthBaseUrl` with a path from `OAuthPaths.hpp` (ADR-0773). A hand-off allowlist entry is an https origin or a bare private-use scheme, never a prefix (ADR-0774). diff --git a/CHANGELOG.md b/CHANGELOG.md index 9d714eba4..166d1f59c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,9 +32,18 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * At most 10000 OAuth clients are held: at the cap idle ones go least recently used first, else 503 (ADR-0780). * `/_merovingian/oauth2/*` and `/_merovingian/account*` take the `auth_sensitive` rate limit; `201 Created` has its reason phrase. +* In-memory, hashed, bounded OAuth 2.0 pending authorisations and authorization codes that never evict a live entry; + the sweep and the client cap keep a client that holds one (ADR-0782). +* The password check of `POST /login` and the account creation of `POST /register` are each one function, shared + with the coming OAuth 2.0 pages; both routes answer as before (ADR-0783). +* OAuth 2.0 pages send `Referrer-Policy: same-origin`, get no CORS headers, and accept a form post only from this + server's origin (ADR-0784, ADR-0785). ## Security Fixes +* The query of a `/_merovingian/oauth2/*` or `/_merovingian/account*` request is never logged, so a state, code or + login hint cannot reach the log (ADR-0786). + * A response header that would frame the message (`Content-Length`, `Connection`, ...) or holds CR or LF now turns the response into a 500 instead of being written or silently dropped (ADR-0767). diff --git a/docs/adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md b/docs/adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md index b2a0814ca..dc0962bb7 100644 --- a/docs/adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md +++ b/docs/adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md @@ -29,7 +29,7 @@ distinct name and value pairs, and a password input never carries a value. `page_headers()` sends `default-src 'none'; style-src 'sha256-…'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'`, the hash computed from the one fixed style block, with `X-Frame-Options: DENY`, -`Referrer-Policy: no-referrer` and `Cache-Control: no-store`. `page_headers(target)` adds to `form-action` only +`Referrer-Policy: no-referrer` (since amended to `same-origin` by [ADR-0784](0784-oauth-pages-use-a-same-origin-referrer-policy-and-a-form-post-must-name-this-server-s-origin.md)) and `Cache-Control: no-store`. `page_headers(target)` adds to `form-action` only `ParsedUri::csp_source()` of the matched redirect URI: `scheme://host[:port]`, or `scheme:` for a private-use scheme, built from fields the reader limited to characters that cannot end a source or a directive. As defence in depth it adds nothing for an authority scheme other than `http` or `https`, or for a scheme without a `.`. diff --git a/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md b/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md index 0557ab77a..83132a063 100644 --- a/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md +++ b/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md @@ -36,7 +36,7 @@ value (a clock that stepped back) or within `oauth_client_touch_interval_ms` (24 `oauth_clients_without_sessions` walks only the oldest sessionless clients and never reads the session table. A client with a session is never in that set, and `delete_oauth_clients` refuses one, so neither the sweep nor the cap can delete it (the spec: "The server MUST NOT delete client registrations that have an active session"). The sweep -asks `oauth_client_has_pending_authorisation` too; it is false until phase 5 keeps pending authorisations. +asks `oauth_client_has_pending_authorisation` too; it was false until phase 5 kept pending authorisations, and is answered from the stores since [ADR-0782](0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md). ### Positive Consequences diff --git a/docs/adr/0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md b/docs/adr/0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md new file mode 100644 index 000000000..59338f625 --- /dev/null +++ b/docs/adr/0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md @@ -0,0 +1,77 @@ +# Pending authorisations and authorization codes are in memory, hashed, bounded and never evicted + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 5a of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) (P5) + +## Context and Problem Statement + +An authorization request (RFC 6749 section 4.1.1) lives across several page round trips before the user is sent back +with a code, and the code (section 4.1.2) lives until the client redeems it. Both are bearer secrets: whoever holds a +pending authorisation's identifier and the browser's token, or a code and the PKCE verifier, completes the grant. Where +are they kept, how are they found, and what happens when there are too many? + +## Decision Drivers + +* A leaked store (a core dump, a database backup) must not hand out live grants. +* Lookup must not leak by timing which identifiers exist, and must not cost a scan under `runtime.mutex`. +* An unauthenticated client starts a pending authorisation; it must not be able to push a real user's out. +* The retention sweep must know that a client is in use without a scan (ADR-0777, ADR-0780). + +## Considered Options + +* In memory on `HomeserverRuntime`, keyed by the BLAKE2b hash of a 32-byte random secret, bounded, refusing when full +* Persisted in the database next to the OAuth sessions +* In memory, evicting the oldest entry when full + +## Decision Outcome + +Chosen option: in memory, hashed, bounded, refusing when full. + +* `PendingAuthorisationStore` and `AuthorizationCodeStore` (`src/homeserver/`) live on `HomeserverRuntime`, guarded by + `runtime.mutex`. Each secret is 32 random bytes (64 hex digits, `make_oauth_secret`); only `oauth_secret_hash` of it + is kept. Lookup goes through `HashedSecretTable`: an index of digests of the hash, every candidate confirmed with + `crypto::constant_time_equal`, never a fall-back scan (the ADR-0488 shape). +* A pending authorisation lives 10 minutes and is bound to a browser token, compared in constant time; a wrong token + answers exactly as an unknown identifier. A code lives 60 seconds; a redeemed code is kept, marked, until its own + expiry, so a replay is told apart (RFC 6749 section 4.1.2: revoke what the code issued) and names the user and + device it went to. +* Every operation takes the current time; an entry is expired when `expires_at <= now` and is removed on the next + operation. Caps: 8192 pending authorisations, 16 per client address, 8192 codes. At a cap, expired entries are + purged first; if the store is still full the request is refused. A live entry is never evicted. +* `oauth_client_has_pending_authorisation(runtime, client_id, now_ms)` is the O(1) answer the retention sweep and the + registration cap's eviction ask: a per-client multiset of expiries, whose latest is compared with `now`. The test + seam `test_oauth_pending_authorisation` is gone; tests hold real entries. +* `OAuthTables::idle_clients` examines at most `max_idle_client_rows_examined` (8192 + 8192 + 512) rows: the clients + the stores can name plus one retention batch. Nothing idle within the bound means nothing can go this round. + +### Positive Consequences + +* Nothing a backup or a dump holds can be redeemed; a restart ends every pending grant, which a user retries. +* An unauthenticated caller fills at most its own 16 places and then the shared cap; it never removes another user's. + +### Negative Consequences + +* A restart loses every pending authorisation and unredeemed code. +* At the total cap new authorisations are refused for up to 10 minutes; the per-address cap bounds one address's part. + +## Pros and Cons of the Options + +### Persisted in the database + +* Good, because a restart keeps grants. +* Bad, because every page round trip writes a row, and the rows outlive their 60 seconds in backups. + +### Evicting the oldest when full + +* Good, because a new request always gets a place. +* Bad, because an attacker who fills the store pushes out every real user's authorisation in progress. + +## Links + +* Refines [ADR-0777](0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md) and + [ADR-0780](0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md) +* Model: [ADR-0548](0548-login-tokens-are-opt-in-single-use-and-held-in-memory.md), + [ADR-0488](0488-sessions-are-found-through-a-digest-index-and-unusable-credentials-are-deleted.md) diff --git a/docs/adr/0783-login-verification-and-account-creation-are-one-function-each-shared-by-the-matrix-routes-and-the-oauth-pages.md b/docs/adr/0783-login-verification-and-account-creation-are-one-function-each-shared-by-the-matrix-routes-and-the-oauth-pages.md new file mode 100644 index 000000000..e52e11c5c --- /dev/null +++ b/docs/adr/0783-login-verification-and-account-creation-are-one-function-each-shared-by-the-matrix-routes-and-the-oauth-pages.md @@ -0,0 +1,72 @@ +# Login verification and account creation are one function each, shared by the Matrix routes and the OAuth pages + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 5a of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +The OAuth 2.0 login and account pages must check a password and create an account without issuing a Matrix session. +`POST /login` and `POST /register` already hold every check that makes those safe: the failed-login throttle, the +Argon2id admission slot, the lock release and re-validation around the hash, the dummy hash for an unknown user, the +account-state gates, the username checks, the registration policy and the registration token. How do the pages get +the same checks without a second copy that drifts? + +## Decision Drivers + +* A check added to one path and not the other is an authentication bypass. +* `POST /login` and `POST /register` must answer byte for byte as before; no check may be reordered or weakened. + +## Considered Options + +* One verification function and one account-creation function, called by both the Matrix routes and the pages +* The pages call `login_local_user` and `register_local_user` and throw the session away +* The pages carry their own copy of the checks + +## Decision Outcome + +Chosen option: one function each. + +* `verify_login_credentials` (`AuthService.cpp`) is the password check of `login_local_user`, moved unchanged: log + `login.started`; the throttle (a refusal costs no hash and is not a failure); an Argon2id slot (none is `busy`, not a + failure); the stored hash or the dummy hash; the verification with `runtime.mutex` released; re-find the user and + require its hash unchanged; on failure count it against the claimed user ID and audit `login.rejected`, on success + clear this source's failures. `login_local_user` calls it, then `login_local_user_by_id` as before. +* `verify_password_login` is `verify_login_credentials` followed by `account_state_refusal`, the one account-state gate, + which `complete_login` and `login_local_user_by_id` also call. The gate stays out of `verify_login_credentials` + because `/login` applies it after its device checks (invalid device ID, cross-signing collision, device cap); moving + it in front would change what `/login` answers when two refusals apply. `PasswordLoginVerification::Outcome` + distinguishes exactly what `/login` does: verified, invalid login, throttled, busy, deactivated. +* `login_identifier_user_id` is the one normalisation of a typed identifier (`parse_login_body` uses it). +* `create_local_account` makes `/register`'s post-UIA username checks (not valid, reserved, an appservice's exclusive + namespace or sender, with `/register`'s errcodes in `OperationResult::errcode`) and then `register_password_account`, + the gates `register_local_user` always made, with the caller's client key given to the registration policy. + `/register` calls it with `127.0.0.1`, the address it has always passed; `register_local_user` passes the same. + Neither creates a device, a token or a session. + +### Positive Consequences + +* A check added to the shared function protects both surfaces; the pages cannot skip one. +* The existing login and registration tests prove the Matrix routes unchanged. + +### Negative Consequences + +* `/register` keeps judging the registration policy for the fixed address `127.0.0.1`; changing that is a behaviour + change for its own branch. + +## Pros and Cons of the Options + +### Calling the session-issuing functions and discarding the session + +* Good, because no code moves. +* Bad, because it creates a device and a token the user never sees, and a device past the cap refuses a valid login. + +### A second copy in the page handlers + +* Bad, because the two copies drift, and the drift is a bypass. + +## Links + +* Relates to [ADR-0246](0246-the-password-hashing-concurrency-cap-is-configurable.md) diff --git a/docs/adr/0784-oauth-pages-use-a-same-origin-referrer-policy-and-a-form-post-must-name-this-server-s-origin.md b/docs/adr/0784-oauth-pages-use-a-same-origin-referrer-policy-and-a-form-post-must-name-this-server-s-origin.md new file mode 100644 index 000000000..5d44b236c --- /dev/null +++ b/docs/adr/0784-oauth-pages-use-a-same-origin-referrer-policy-and-a-form-post-must-name-this-server-s-origin.md @@ -0,0 +1,53 @@ +# OAuth pages use a same-origin referrer policy, and a form post must name this server's origin + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 5a of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +The OAuth 2.0 pages post forms (sign in, create an account, consent) back to this server. A cross-site form post +(login CSRF, consent forged from another site) must be refused. `SameSite` cookies are one line of defence; the request +headers a browser sets, `Origin` and `Sec-Fetch-Site`, are the other. ADR-0772 set `Referrer-Policy: no-referrer`, and +under it some browsers send `Origin: null` on a same-origin form post, which makes the origin check useless. What +policy, and what exact rule? + +## Decision Drivers + +* No other origin may learn a page's address, whose query carries a state and a pending authorisation identifier. +* A same-origin form post must carry a usable `Origin`. +* The rule must be exact: no prefix match, no case folding, no guessing at ports. + +## Considered Options + +* `same-origin`, and a form post accepted only when `Origin` equals this server's origin and `Sec-Fetch-Site`, when + present, is `same-origin` +* Keep `no-referrer` and accept `Origin: null` +* Keep `no-referrer` and rely on `SameSite` cookies alone + +## Decision Outcome + +Chosen option: `same-origin` with the exact `Origin` rule. + +* `oauth::page_headers` sends `Referrer-Policy: same-origin`, and every page's `` says the same, + so the two never disagree. A navigation to another origin, the client's redirect URI included, carries no Referer. +* `oauth::form_post_origin_is_accepted(base_url, origin, sec_fetch_site)` is the check. The expected origin is + `form_post_origin(base_url)`: `https://`, the base URL's host in lower case, and `:` only for a port other than + 443 (RFC 6454 section 6.1 leaves the default port out, as browsers serialise it). `Origin` must be present and equal + it byte for byte: absent, `null`, an explicit `:443`, a trailing slash, another case, scheme, host or port are refused. + `Sec-Fetch-Site`, when present, must be exactly `same-origin`; absent is accepted, since not every browser sends it. + +### Positive Consequences + +* A forged cross-site post is refused whatever the cookies say. +* A same-origin Referer is available to this server, and to no one else. + +### Negative Consequences + +* A browser or privacy extension that strips `Origin` from same-origin posts cannot use the pages. + +## Links + +* Amends the `Referrer-Policy` of [ADR-0772](0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md) diff --git a/docs/adr/0785-an-oauth-page-response-is-marked-in-its-type-and-gets-no-cors-headers.md b/docs/adr/0785-an-oauth-page-response-is-marked-in-its-type-and-gets-no-cors-headers.md new file mode 100644 index 000000000..dc67483ea --- /dev/null +++ b/docs/adr/0785-an-oauth-page-response-is-marked-in-its-type-and-gets-no-cors-headers.md @@ -0,0 +1,48 @@ +# An OAuth page response is marked in its type and gets no CORS headers + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 5a of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +The client-server boundary (`handle_client_server_request`) adds `Access-Control-Allow-Origin` and `Vary: Origin` to +every complete response, as the spec requires of the Matrix API, and the client API's `wrap()` re-encodes a router +answer as JSON. An OAuth 2.0 page is HTML for a browser at this server's own origin; a CORS header on it would let +another origin read a page holding a pending authorisation identifier, and a rewrite would break its headers. Where is +the exception made? + +## Considered Options + +* A `page` flag on `LocalHttpResponse`, read at the one boundary that adds the headers and by `wrap()` +* A list of page paths at the boundary +* A header the page sets and the boundary looks for + +## Decision Outcome + +Chosen option: the flag in the response type. + +`LocalHttpResponse::page` is set by whoever builds a page with `oauth::page_headers`. `apply_client_response_headers` +(the boundary's call, public so a test can hand it a built response) adds only `X-Content-Type-Options: nosniff` to a +page, never a CORS header, preflight or not; `wrap()` returns a page unchanged. The flag is internal: never written to +the wire. + +### Positive Consequences + +* A page cannot gain a CORS header by being served from a new path; nothing has to keep a path list in step. + +### Negative Consequences + +* A handler that builds a page and forgets the flag gets CORS headers; the page tests of phase 5b check every page. + +## Pros and Cons of the Options + +### A path list at the boundary + +* Bad, because a page served at a path the list misses is readable cross-origin. + +### A marker header + +* Bad, because a header is written to the wire, and anything that copies headers could forge or drop it. diff --git a/docs/adr/0786-the-query-of-an-oauth-request-is-never-logged.md b/docs/adr/0786-the-query-of-an-oauth-request-is-never-logged.md new file mode 100644 index 000000000..afe433d39 --- /dev/null +++ b/docs/adr/0786-the-query-of-an-oauth-request-is-never-logged.md @@ -0,0 +1,49 @@ +# The query of an OAuth request is never logged + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 5a of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +Every log line that names a request target goes through `observability::sanitized_http_target`, which keeps the query +and redacts the values of parameters whose names hold a marker such as `token`. The OAuth 2.0 pages and endpoints +carry secrets under names no marker list covers: `state`, `code`, `login_hint`, a pending authorisation identifier. +How are they kept out of the logs? + +## Considered Options + +* Drop the whole query of every target under `/_merovingian/oauth2` and `/_merovingian/account` in + `sanitized_http_target` +* Add `state`, `code` and the others to the marker list +* Log nothing about OAuth requests + +## Decision Outcome + +Chosen option: drop the whole query of those paths, in `sanitized_http_target` itself. + +The path `/_merovingian/oauth2` or `/_merovingian/account`, alone or followed by `/`, is logged without its `?` and +query. Every request-target log site in `ClientServerRuntime.cpp`, `HttpServer.cpp`, `LocalHttpRouter.cpp` and +`FederationProxy.cpp` already calls it, so none needs changing. Audit rows already drop every query +(`sanitized_audit_target`). `[observability][oauth]` in `tests/unit/test_observability.cpp` holds every path of +`oauth/OAuthPaths.hpp` to the rule, and `[oauth-log]` drives the dispatcher with the log captured at debug level. + +### Positive Consequences + +* A new OAuth parameter is safe in the logs without anyone remembering to list it. + +### Negative Consequences + +* An operator cannot see which parameters an OAuth request carried; the path, method and status remain. + +## Pros and Cons of the Options + +### More markers + +* Bad, because `code` and `state` are common words in other queries, and the next OAuth parameter is missed. + +## Links + +* Same reasoning as [ADR-0418](0418-the-outbound-client-logs-an-url-without-its-query.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 2c811cc1e..009a8cc11 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -663,3 +663,8 @@ * [0779 - An OAuth client ID is a keyed hash of the accepted metadata](0779-an-oauth-client-id-is-a-keyed-hash-of-the-accepted-metadata.md) * [0780 - OAuth registrations are capped, and idle clients are evicted least recently used first](0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md) * [0781 - OAuth endpoints answer OAuth errors with no-store, from one helper](0781-oauth-endpoints-answer-oauth-errors-with-no-store-from-one-helper.md) +* [0782 - Pending authorisations and authorization codes are in memory, hashed, bounded and never evicted](0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md) +* [0783 - Login verification and account creation are one function each, shared by the Matrix routes and the OAuth pages](0783-login-verification-and-account-creation-are-one-function-each-shared-by-the-matrix-routes-and-the-oauth-pages.md) +* [0784 - OAuth pages use a same-origin referrer policy, and a form post must name this server's origin](0784-oauth-pages-use-a-same-origin-referrer-policy-and-a-form-post-must-name-this-server-s-origin.md) +* [0785 - An OAuth page response is marked in its type and gets no CORS headers](0785-an-oauth-page-response-is-marked-in-its-type-and-gets-no-cors-headers.md) +* [0786 - The query of an OAuth request is never logged](0786-the-query-of-an-oauth-request-is-never-logged.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index dbe8c8c0c..e327ae8f9 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -1099,6 +1099,33 @@ true, without authentication, by `register_oauth_client` (`homeserver/OAuthClien - `find_registered_oauth_client` reads a client back for later phases: unknown, unparsable or no longer valid metadata is "no client"; a row that fails validation is logged without its content. +## OAuth 2.0 authorisation building blocks (phase 5a) + +Phase 5a adds what the authorisation pages of phase 5b call; no route serves them yet. + +- **Pending authorisations** (`PendingAuthorisationStore`, ADR-0782): a validated authorization request kept in memory + for 10 minutes under a fresh 32-byte identifier, returned once, of which only the hash is kept. It is found only with + the identifier and the browser token, compared in constant time; a wrong token answers as an unknown identifier. At + most 8192, and 16 per client address key; at a cap expired entries are purged, then the request is refused. Live + entries are never evicted. The authenticated user is recorded on it, and it is consumed once. +- **Authorization codes** (`AuthorizationCodeStore`): 32 random bytes, kept as a hash, valid 60 seconds, bound to the + client, redirect URI, PKCE challenge, user, device and scope. At most 8192, never evicted. Redemption answers fresh + (with the grant), replayed (with the user and device, until the code's own expiry) or unknown. +- **The retention sweep and the registration cap** keep a client that holds a live pending authorisation or an + unredeemed code (`oauth_client_has_pending_authorisation`, O(1)); the idle-client walk examines at most + `max_idle_client_rows_examined` rows. +- **Password verification** (`verify_password_login`, ADR-0783) is the password check of `POST /login`, unchanged and + shared: the failed-login throttle, the Argon2id admission slot, the dummy hash for an unknown user, the verification + with `runtime.mutex` released and the re-validation, then the account-state gate (deactivated; locked; a suspended + account may log in, as on `/login`). It creates no device and no token. Its outcomes are what `/login` tells apart: + verified, invalid login, throttled (429 with a delay), busy (429 with a delay) and deactivated. +- **Account creation** (`create_local_account`, ADR-0783) makes `POST /register`'s username checks and every + registration gate, with the caller's client key given to the registration policy, and creates no device, token or + session. `POST /register` calls it with `127.0.0.1`, the address its policy has always been judged for. The + registration token is the token file's, checked with Argon2id and not counted, so no attempt spends it. +- **Form posts** are accepted only from this server's origin (`oauth::form_post_origin_is_accepted`, ADR-0784), the + pages send `Referrer-Policy: same-origin`, and the query of an OAuth request is never logged (ADR-0786). + ## Next starting points 1. Preserve the reviewed libsodium boundary for random token generation and password hashing as auth flows expand. diff --git a/docs/debug-logging.md b/docs/debug-logging.md index ab5e8199c..9d20360d9 100644 --- a/docs/debug-logging.md +++ b/docs/debug-logging.md @@ -132,6 +132,10 @@ The `outbound_client` module logs `request.success`, `request.error` and port and path of the request, never its query (ADR-0418): a query can carry an identity server's `client_secret`, or text a user chose. +The `client_server` module's request lines (`request.received`, `request.route_not_found`, `request.auth.*`) keep a +target's query, with marked parameters redacted, except under `/_merovingian/oauth2` and `/_merovingian/account`, whose +query is never written, even at debug (ADR-0786). + ## Join Failure Diagnostics For failed room joins, enable debug/file logging and inspect events with these diff --git a/docs/http-transport.md b/docs/http-transport.md index 3bf3809c1..f2101f120 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -961,6 +961,13 @@ transport's own body cap is still refused by the connection handler. With `serve `404 M_UNRECOGNIZED`. Every OAuth answer is built by `oauth_json_response` or `oauth_error_response` (`application/json`, `Cache-Control: no-store`); the 429, 405, 404 and not-started 503 stay Matrix-shaped. +The OAuth HTML pages (phase 5b) are marked `LocalHttpResponse::page`: `apply_client_response_headers`, the boundary +that adds the CORS headers, gives a page only `X-Content-Type-Options: nosniff`, and the client API's `wrap()` returns +a page unchanged (ADR-0785). A page sends `Referrer-Policy: same-origin`, and a form post to one is accepted only when +`Origin` equals the base URL's origin (`https://`, lower-case host, a port only when not 443) and `Sec-Fetch-Site`, +when sent, is `same-origin` (`oauth::form_post_origin_is_accepted`, ADR-0784). No log line keeps the query of a target +under `/_merovingian/oauth2` or `/_merovingian/account` (`sanitized_http_target`, ADR-0786). + ### Admin routes `/_merovingian/admin/*` (health, metrics, audit, accounts, review, media moderation) is served on diff --git a/docs/observability-audit.md b/docs/observability-audit.md index 16146e9b2..6308fcae8 100644 --- a/docs/observability-audit.md +++ b/docs/observability-audit.md @@ -85,6 +85,11 @@ is full. `access_token`/`refresh_token`/`session_token` — needed because `GET /_matrix/client/v1/register/m.login.registration_token/validity` passes the plaintext registration token as `?token=`. +- `sanitized_http_target` drops the whole query, `?` included, of a target whose path is `/_merovingian/oauth2` or + `/_merovingian/account`, alone or followed by `/` (ADR-0786): the OAuth pages and endpoints carry `state`, `code`, + `login_hint` and pending authorisation identifiers under names no marker covers. Every request-target log site + (`request.received`, `request.rejected`, `request.route_not_found`, `request.auth.*`, `rate_limit.exceeded` and the + transport's lines) goes through it; audit rows already drop every query (`sanitized_audit_target`). - Stable request-correlation fields (`request_id`, `trace_id`, `span_id`) for local HTTP router diagnostics. - Health, metric, and hardening snapshot helpers. diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index 9196f6822..e9b1638f1 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1033,6 +1033,29 @@ quickly finding everything a given `AGENTS.md` file contributed. use breaks the spec's MUST NOT; the body is attacker-chosen text (CWE-117) (ADR-0779, ADR-0780). Source: `src/homeserver/AGENTS.md`. +- **Pending authorisations and authorization codes are kept only as the hash of a 32-byte random secret, found through + a digest index and a constant-time comparison, bounded, and never evicted while live; a wrong browser token answers + as an unknown identifier.** + Why: a stored secret is a live grant to whoever reads memory or a dump (CWE-312); a timing or answer difference + tells an attacker which identifiers exist (CWE-208, CWE-204); evicting a live entry lets an unauthenticated flood + cancel every real login (CWE-400) (ADR-0782). + Source: `src/homeserver/AGENTS.md`. + +- **A password is checked only through `verify_login_credentials` (POST /login, `verify_password_login`) and a + password account is created only through `register_password_account` (`register_local_user`, + `create_local_account`).** Never copy the throttle, admission, dummy-hash, re-validation or account-state steps. + Why: a check present on one path and missing on the other is an authentication bypass (CWE-287) or an account + enumeration oracle (CWE-204) (ADR-0783). + Source: `src/auth/AGENTS.md`. + +- **An OAuth page sends `Referrer-Policy: same-origin`, gets no CORS header (`LocalHttpResponse::page`), and accepts + a form post only when `oauth::form_post_origin_is_accepted` does; the query of `/_merovingian/oauth2/*` and + `/_merovingian/account/*` is never logged.** + Why: a cross-site post forges a login or a consent (CWE-352); a CORS header lets another origin read a page that + holds a pending authorisation identifier (CWE-942); the query holds a state, a code or a login hint under names the + marker redaction misses (CWE-532) (ADR-0784, ADR-0785, ADR-0786). + Source: `src/oauth/AGENTS.md`, `src/homeserver/AGENTS.md`. + ## HTTP and network boundary - **Rate limiting is applied before any auth check.** Do not move it after auth. diff --git a/docs/todos/oauth-2-0-api.md b/docs/todos/oauth-2-0-api.md index 181434ae7..d86fb9c88 100644 --- a/docs/todos/oauth-2-0-api.md +++ b/docs/todos/oauth-2-0-api.md @@ -220,8 +220,8 @@ migrates and serves it on SQLite and on PostgreSQL. Every page is fixed HTML rendered by one function that accepts only escaped fragments (ADR-0763). Every page sends `Content-Security-Policy` (`default-src 'none'`, a hashed inline style, `frame-ancestors 'none'`), -`X-Frame-Options: DENY`, `Referrer-Policy: no-referrer` and `Cache-Control: no-store`. A page that posts a form -checks the `Origin` header. +`X-Frame-Options: DENY`, `Referrer-Policy: same-origin` and `Cache-Control: no-store`. A page that posts a form +checks `Origin` and `Sec-Fetch-Site` with `oauth::form_post_origin_is_accepted` (ADR-0784). ### Account pages and the `m.oauth` stage diff --git a/include/merovingian/database/OAuthStore.hpp b/include/merovingian/database/OAuthStore.hpp index c5400a8b8..916a62dfa 100644 --- a/include/merovingian/database/OAuthStore.hpp +++ b/include/merovingian/database/OAuthStore.hpp @@ -53,8 +53,9 @@ inline constexpr auto oauth_client_touch_interval_ms = std::uint64_t{24U} * 60U // is repeated, or names a client with a session (never deleted: spec "Client registration"), or the write fails. [[nodiscard]] auto delete_oauth_clients(PersistentStore& store, std::span client_ids) -> bool; // The clients with no session, least recently used first, at most `max`, and only those last used before -// `used_before_ms` (pass UINT64_MAX for all). A client `excluded` answers true for (phase 5: a pending authorisation -// names it) is skipped and does not count against `max`. Costs the clients walked, not the session table. +// `used_before_ms` (pass UINT64_MAX for all). A client `excluded` answers true for (a pending authorisation or an +// unredeemed code names it) is skipped and does not count against `max`. The walk stops after +// `max_idle_client_rows_examined` clients, whatever it found. Costs the clients walked, not the session table. [[nodiscard]] auto oauth_clients_without_sessions(PersistentStore const& store, std::size_t max, std::uint64_t used_before_ms, std::function const& excluded = {}) diff --git a/include/merovingian/database/OAuthTables.hpp b/include/merovingian/database/OAuthTables.hpp index 109c775ff..252b3164f 100644 --- a/include/merovingian/database/OAuthTables.hpp +++ b/include/merovingian/database/OAuthTables.hpp @@ -20,6 +20,15 @@ namespace merovingian::database { +// The most idle clients one `OAuthTables::idle_clients` call examines (ADR-0782). The walk runs under `runtime.mutex` +// and skips every client a pending authorisation or an unredeemed code names, so without a bound its cost was bounded +// only by the client cap. 16 896 is the 8192 pending authorisations plus the 8192 codes the homeserver can hold (each +// names one client, so at most 16 384 clients are skipped) plus 512, more than any caller asks for +// (`retention_batch_rows` 500; `RetentionSweep.cpp` and `OAuthClientRegistration.cpp` assert it): a walk that stops +// here has therefore already found `max` clients or every idle one. A walk that finds nothing within it answers +// "nothing can go". +inline constexpr auto max_idle_client_rows_examined = std::size_t{16'896U}; + // The in-memory copy of `oauth_clients` and `oauth_sessions` (migration 002, ADR-0776, ADR-0777). 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. A client is found by ID and a session by (user, device) with one hash lookup; a user's sessions through a @@ -48,9 +57,10 @@ class OAuthTables final // an active session"). auto erase_client(std::string_view client_id) -> bool; - // The held clients no session names, least recently used first (ties by ID), stopping at `max` IDs or at the - // first client used at or after `used_before_ms`. A client `excluded` answers true for is skipped. Costs the - // clients walked, counted in `rows_examined`, never the session table. + // The held clients no session names, least recently used first (ties by ID), stopping at `max` IDs, at the + // first client used at or after `used_before_ms`, or once `max_idle_client_rows_examined` clients were examined. + // A client `excluded` answers true for is skipped. Costs the clients walked, counted in `rows_examined`, never the + // session table. [[nodiscard]] auto idle_clients(std::size_t max, std::uint64_t used_before_ms, std::function const& excluded) const -> std::vector; diff --git a/include/merovingian/homeserver/AccountCreationRequest.hpp b/include/merovingian/homeserver/AccountCreationRequest.hpp new file mode 100644 index 000000000..84224fb19 --- /dev/null +++ b/include/merovingian/homeserver/AccountCreationRequest.hpp @@ -0,0 +1,26 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::homeserver +{ + +// An account to create without a session (`create_local_account`, ADR-0783). Borrowed views: the caller keeps the +// strings alive for the call. +struct AccountCreationRequest final +{ + // The desired localpart, already chosen (POST /register generates one when the client named none). + std::string_view localpart{}; + // The password as typed. Never logged. + std::string_view password{}; + // The registration token the caller presented, or empty. + std::string_view registration_token{}; + // The client key the registration policy judges (`trust_safety::RegistrationPolicyRequest::requester_address`, + // which refuses an empty one). POST /register passes "127.0.0.1", as it always has; the OAuth 2.0 account page + // passes `rate_limit_client_key`. + std::string_view client_key{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/AuthService.hpp b/include/merovingian/homeserver/AuthService.hpp index dcaf9ccbb..69c6b3336 100644 --- a/include/merovingian/homeserver/AuthService.hpp +++ b/include/merovingian/homeserver/AuthService.hpp @@ -5,6 +5,7 @@ #include "merovingian/auth/AccountState.hpp" #include "merovingian/config/RegistrationSecurityConfig.hpp" #include "merovingian/config/SsoConfig.hpp" +#include "merovingian/homeserver/AccountCreationRequest.hpp" #include "merovingian/homeserver/AccountSummary.hpp" #include "merovingian/homeserver/AdminAuthResult.hpp" #include "merovingian/homeserver/DeactivationAudit.hpp" @@ -12,6 +13,8 @@ #include "merovingian/homeserver/LocalSession.hpp" #include "merovingian/homeserver/OpenidTokenIssueResult.hpp" #include "merovingian/homeserver/OperationResult.hpp" +#include "merovingian/homeserver/PasswordLoginRequest.hpp" +#include "merovingian/homeserver/PasswordLoginVerification.hpp" #include "merovingian/homeserver/PasswordVerificationResult.hpp" #include "merovingian/homeserver/SessionRefreshResult.hpp" #include "merovingian/homeserver/SsoRedirectResult.hpp" @@ -28,6 +31,14 @@ namespace merovingian::homeserver [[nodiscard]] auto register_local_user(HomeserverRuntime& runtime, std::string_view localpart, std::string_view password, std::string_view registration_token = {}) -> OperationResult; +// Creates a password account and nothing else: no device, no token, no session (ADR-0783). The username checks POST +// /register makes after user-interactive auth (not valid: 400 M_INVALID_USERNAME; reserved: 400 M_USER_IN_USE; an +// application service's exclusive namespace or sender: 400 M_EXCLUSIVE), then every gate of register_local_user with +// `request.client_key` given to the registration policy. A refusal sets `status`, `reason` and, where the status +// cannot name it, `errcode`. POST /register calls it with "127.0.0.1". The caller holds runtime.mutex through a +// RequestLockScope. +[[nodiscard]] auto create_local_account(HomeserverRuntime& runtime, AccountCreationRequest const& request) + -> OperationResult; [[nodiscard]] auto bootstrap_admin_user(HomeserverRuntime& runtime, std::string_view localpart, std::string_view password) -> OperationResult; // `display_name` is the client's `initial_device_display_name`, stored with a device this login creates (ignored for @@ -51,6 +62,19 @@ namespace merovingian::homeserver [[nodiscard]] auto login_local_user_by_id(HomeserverRuntime& runtime, std::string_view user_id, std::string_view device_id, bool with_ttl = false, std::string_view display_name = {}) -> OperationResult; +// The full user ID a typed login identifier names: unchanged when it starts with `@`, else `@:`. +// POST /login and the OAuth 2.0 login page both normalise through it (ADR-0783). +[[nodiscard]] auto login_identifier_user_id(std::string_view server_name, std::string_view identifier) -> std::string; +// The password check POST /login makes, for a caller that wants no session (the OAuth 2.0 login page, ADR-0783), then +// the account-state gate. In order: the failed-login throttle (`throttled`), an Argon2id admission slot (`busy`), the +// stored hash or the dummy hash for an unknown user, the verification with runtime.mutex released, the re-validation +// that the user and its hash are unchanged (else `invalid_login`, counted as a failed attempt), then deactivated +// (`account_deactivated`) and locked (`invalid_login`); a suspended account is `verified`, as POST /login lets it log +// in (spec v1.19 "Account suspension"). Creates no device and no token. The caller holds +// runtime.mutex, published through a RequestLockScope as the request dispatchers publish it, exactly as for +// login_local_user: the verification releases it with RuntimeLockRelease and takes it back. +[[nodiscard]] auto verify_password_login(HomeserverRuntime& runtime, PasswordLoginRequest const& request) + -> PasswordLoginVerification; // Application Service API (Matrix v1.19): see the .cpp definitions for the // full spec citation. The caller MUST have already verified the presented // as_token and that the target user_id/localpart is within the appservice's diff --git a/include/merovingian/homeserver/AuthorizationCodeRedemption.hpp b/include/merovingian/homeserver/AuthorizationCodeRedemption.hpp new file mode 100644 index 000000000..449702592 --- /dev/null +++ b/include/merovingian/homeserver/AuthorizationCodeRedemption.hpp @@ -0,0 +1,34 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/AuthorizationGrant.hpp" + +#include +#include + +namespace merovingian::homeserver +{ + +// What `AuthorizationCodeStore::redeem` found for a presented code. +struct AuthorizationCodeRedemption final +{ + enum class Outcome : std::uint8_t + { + // The first redemption of a live code: `grant` holds what it stands for, and the code is now spent. + fresh, + // A live code already redeemed once: `user_id` and `device_id` name the session the first redemption was for, + // so the token endpoint can revoke it ("a code presented twice revokes the session it produced"). `grant` is + // empty. + replayed, + // No live code has this value: never minted, expired, or the hash failed. Nothing else is set. + unknown, + }; + + Outcome outcome{Outcome::unknown}; + AuthorizationGrant grant{}; + std::string user_id{}; + std::string device_id{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/AuthorizationCodeStore.hpp b/include/merovingian/homeserver/AuthorizationCodeStore.hpp new file mode 100644 index 000000000..688fe7e14 --- /dev/null +++ b/include/merovingian/homeserver/AuthorizationCodeStore.hpp @@ -0,0 +1,90 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/StateGroupKeyHash.hpp" +#include "merovingian/homeserver/AuthorizationCodeRedemption.hpp" +#include "merovingian/homeserver/AuthorizationGrant.hpp" +#include "merovingian/homeserver/HashedSecretTable.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +// The authorisation codes minted by approvals and not yet expired (plan P5, "The authorisation flow" steps 5 and 6, +// ADR-0782). In memory only: a code lives 60 seconds, and a restart only makes the client start its login again. +// +// A code is a fresh 256-bit secret, returned once by `issue`; only its hash is kept, found through a digest index and +// confirmed in constant time (`HashedSecretTable`). Redemption is single use. A redeemed code stays remembered, marked +// redeemed, until its own expiry, so that a second presentation is recognised as a replay and names the session the +// first one produced (RFC 6749 section 4.1.2: a code used twice MUST be refused and SHOULD revoke the tokens it gave). +// +// Bounded: `max_codes` in all, redeemed ones included. At the cap the expired codes are purged and, if it is still +// full, the issue is refused; a live code is never evicted. Every operation takes the current time. Not thread-safe: +// `runtime.mutex` serialises every use (the store is `HomeserverRuntime::oauth_codes`). +class AuthorizationCodeStore final +{ +public: + // A code is valid this long from its issue (RFC 6749 section 4.1.2 recommends at most ten minutes; the client + // redeems it at once, so 60 seconds leaves room for a slow network and little for a stolen code). + static constexpr auto lifetime_ms = std::uint64_t{60'000U}; + // At most this many codes, redeemed ones included: a code is minted only after a verified password and an + // approval, so this is far above honest use, and it bounds the retention sweep's walk (ADR-0782). + static constexpr auto max_codes = std::size_t{8192U}; + + enum class Refusal : std::uint8_t + { + // `max_codes` live codes are held. + store_full, + // The random source or the hash failed. + secret_unavailable, + }; + + // Mints a code for `grant`, valid for `lifetime_ms` from `now_ms`. Returns the code (`make_oauth_secret`, 64 hex + // digits), once, or why nothing was stored. + [[nodiscard]] auto issue(AuthorizationGrant grant, std::uint64_t now_ms) -> std::variant; + + // Redeems `code` at `now_ms`: `fresh` the first time (and the code is spent), `replayed` every later time until + // the code's own expiry, `unknown` otherwise. + [[nodiscard]] auto redeem(std::string_view code, std::uint64_t now_ms) -> AuthorizationCodeRedemption; + + // How many live, unredeemed codes name `client_id`, after removing the expired ones. No scan. + [[nodiscard]] auto unredeemed_count_for_client(std::string_view client_id, std::uint64_t now_ms) -> std::size_t; + + // Whether a live, unredeemed code names `client_id`, without changing the store. O(1). + [[nodiscard]] auto holds_unredeemed_code_for_client(std::string_view client_id, std::uint64_t now_ms) const -> bool; + + // Removes every code whose lifetime ended at or before `now_ms`. + auto erase_expired(std::uint64_t now_ms) -> void; + + // Codes held, redeemed and expired ones not yet removed included. + [[nodiscard]] auto size() const noexcept -> std::size_t; + +private: + struct Entry final + { + AuthorizationGrant grant{}; + std::uint64_t expires_at_ms{0U}; + bool redeemed{false}; + }; + + template + using KeyedBy = std::unordered_map>; + + // Drops an unredeemed code from the per-client expiries. + auto forget_unredeemed(Entry const& entry) -> void; + + HashedSecretTable m_codes{}; + // client_id -> the expiry of each of its unredeemed codes; the last element is the latest. + KeyedBy> m_unredeemed_expiries_by_client{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/AuthorizationGrant.hpp b/include/merovingian/homeserver/AuthorizationGrant.hpp new file mode 100644 index 000000000..a0caff796 --- /dev/null +++ b/include/merovingian/homeserver/AuthorizationGrant.hpp @@ -0,0 +1,26 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::homeserver +{ + +// What an authorisation code stands for (plan "The authorisation flow", step 5): the approved request, bound to the +// user who approved it. The token endpoint (phase 6) checks the client, the redirect URI and the PKCE verifier against +// it before it writes a session. +struct AuthorizationGrant final +{ + std::string client_id{}; + // The redirect URI exactly as the authorisation request gave it. + std::string redirect_uri{}; + // The PKCE `S256` challenge the token request's verifier must match. + std::string code_challenge{}; + std::string user_id{}; + std::string device_id{}; + // The granted scope in canonical order. + std::string scope{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/ClientServerRuntime.hpp b/include/merovingian/homeserver/ClientServerRuntime.hpp index f67db9c70..01629c8db 100644 --- a/include/merovingian/homeserver/ClientServerRuntime.hpp +++ b/include/merovingian/homeserver/ClientServerRuntime.hpp @@ -175,6 +175,11 @@ auto run_presence_idle_sweep(ClientServerRuntime& runtime) -> std::chrono::milli // again on the media fetch pool. [[nodiscard]] auto handle_client_server_request(ClientServerRuntime& runtime, LocalHttpRequest const& request, ClientServerDispatchOptions const& options) -> DispatchResult; +// The headers the client-server boundary adds to every complete response: `X-Content-Type-Options: nosniff`, then +// the CORS headers `cors` allows (spec v1.19 "Web Browser Clients"), except on an OAuth 2.0 page +// (`LocalHttpResponse::page`, ADR-0785), which gets none of them. A header the response already holds is kept. +auto apply_client_response_headers(LocalHttpRequest const& request, LocalHttpResponse& response, + config::CorsConfig const& cors) -> void; // HTTP-1 / HTTP-6 (ADR-0077): decides from the request head alone whether a // media upload may have its body read under the raised // security.media.max_upload_size cap. `head` is the request with an empty diff --git a/include/merovingian/homeserver/HashedSecretTable.hpp b/include/merovingian/homeserver/HashedSecretTable.hpp new file mode 100644 index 000000000..2ce05cd3a --- /dev/null +++ b/include/merovingian/homeserver/HashedSecretTable.hpp @@ -0,0 +1,137 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/crypto/ConstantTime.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +// The table behind the in-memory OAuth 2.0 stores (`PendingAuthorisationStore`, `AuthorizationCodeStore`, ADR-0782): +// values keyed by the hash of a secret, each with an expiry, found without a scan and expired without a scan. +// +// Entries are held in a map ordered by (expiry, insertion sequence), so the soonest to expire is always first and +// `erase_expired` costs only the entries it removes. Beside it an index maps a digest of the stored hash to the +// entry's key, as `SessionTable` indexes its sessions (ADR-0488): the digest is `std::hash` of the hash, itself a +// uniformly distributed BLAKE2b output, so a client holding only a secret cannot steer which bucket a lookup lands in. +// The index only narrows the search: `find` confirms every candidate with `crypto::constant_time_equal` on the full +// hash and never decides a match from the digest. There is no fall-back scan for a miss. +// +// The caller bounds the table (it decides whether `insert` may run) and keeps any per-key counters, which it updates +// from the value `erase` and `erase_expired` hand back. Not thread-safe: `runtime.mutex` serialises every use. +template +class HashedSecretTable final +{ +public: + // Adds `value` under `secret_hash`, expiring at `expires_at_ms`. The caller has checked the caps. + auto insert(std::string secret_hash, Value value, std::uint64_t expires_at_ms) -> void + { + auto const key = Key{expires_at_ms, m_next_sequence++}; + auto const digest = digest_of(secret_hash); + m_entries.emplace(key, Entry{std::move(secret_hash), std::move(value)}); + m_index.emplace(digest, key); + } + + // The value held under `secret_hash`, or nullptr. Every candidate the index offers is compared in constant time. + // Valid until the next insert or erase. + [[nodiscard]] auto find(std::string_view secret_hash) -> Value* + { + auto const key = find_key(secret_hash); + if (!key.has_value()) + { + return nullptr; + } + return &m_entries.find(*key)->second.value; + } + + // Removes the value held under `secret_hash` and hands it back, or nothing when none is held. + [[nodiscard]] auto erase(std::string_view secret_hash) -> std::optional + { + auto const key = find_key(secret_hash); + if (!key.has_value()) + { + return std::nullopt; + } + return erase_at(m_entries.find(*key)); + } + + // Removes every value whose expiry is at or before `now_ms`, soonest first, handing each to `on_erase` after it + // left the table. Costs the values removed, not the table. + template + auto erase_expired(std::uint64_t now_ms, OnErase&& on_erase) -> void + { + while (!m_entries.empty() && m_entries.begin()->first.first <= now_ms) + { + auto const value = erase_at(m_entries.begin()); + std::invoke(on_erase, value); + } + } + + [[nodiscard]] auto size() const noexcept -> std::size_t + { + return m_entries.size(); + } + +private: + // (expiry, insertion sequence): unique, and ordered soonest expiry first. + using Key = std::pair; + + struct Entry final + { + std::string secret_hash{}; + Value value; + }; + + [[nodiscard]] static auto digest_of(std::string_view secret_hash) noexcept -> std::size_t + { + return std::hash{}(secret_hash); + } + + [[nodiscard]] auto find_key(std::string_view secret_hash) const -> std::optional + { + auto found = std::optional{}; + auto const [first, last] = m_index.equal_range(digest_of(secret_hash)); + for (auto candidate = first; candidate != last; ++candidate) + { + auto const entry = m_entries.find(candidate->second); + // Every candidate is compared, whatever matched first, so the work does not depend on which one matched. + if (entry != m_entries.end() && crypto::constant_time_equal(entry->second.secret_hash, secret_hash)) + { + found = candidate->second; + } + } + return found; + } + + [[nodiscard]] auto erase_at(typename std::map::iterator entry) -> Value + { + auto const [first, last] = m_index.equal_range(digest_of(entry->second.secret_hash)); + for (auto candidate = first; candidate != last; ++candidate) + { + if (candidate->second == entry->first) + { + m_index.erase(candidate); + break; + } + } + auto value = std::move(entry->second.value); + m_entries.erase(entry); + return value; + } + + std::map m_entries{}; + std::unordered_multimap m_index{}; + std::uint64_t m_next_sequence{0U}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/HomeserverRuntime.hpp b/include/merovingian/homeserver/HomeserverRuntime.hpp index 4d1210832..98b66e822 100644 --- a/include/merovingian/homeserver/HomeserverRuntime.hpp +++ b/include/merovingian/homeserver/HomeserverRuntime.hpp @@ -21,12 +21,14 @@ #include "merovingian/homeserver/AppserviceDeliveryBackoff.hpp" #include "merovingian/homeserver/AppserviceEphemeralQueue.hpp" #include "merovingian/homeserver/AppservicePendingEphemeral.hpp" +#include "merovingian/homeserver/AuthorizationCodeStore.hpp" #include "merovingian/homeserver/ClientOutboundProxy.hpp" #include "merovingian/homeserver/ClientOutboundProxyPolicy.hpp" #include "merovingian/homeserver/InboundTypingUser.hpp" #include "merovingian/homeserver/LocalDatabase.hpp" #include "merovingian/homeserver/LocalRoom.hpp" #include "merovingian/homeserver/MediaUploadNotifier.hpp" +#include "merovingian/homeserver/PendingAuthorisationStore.hpp" #include "merovingian/homeserver/PendingFederatedJoin.hpp" #include "merovingian/homeserver/RemoteMediaFetchCoalescer.hpp" #include "merovingian/homeserver/RoomMembers.hpp" @@ -233,10 +235,11 @@ struct HomeserverRuntime final // tombstone is sent, with runtime.mutex released, so a test can change the old room as a concurrent // request would (C21). Always empty in production. std::function test_after_upgrade_room_created{}; - // Test-only: when set, `oauth_client_has_pending_authorisation` also answers true for each client ID it answers - // true for, so a test can stand in for an authorisation still pending before phase 5 of the OAuth 2.0 work keeps - // them. Called with runtime.mutex held; must not take it. Always empty in production. - std::function test_oauth_pending_authorisation{}; + // The OAuth 2.0 authorisation requests waiting for their user, and the authorisation codes minted by approvals + // (plan P5, ADR-0782). In memory only, hashed, bounded, never evicting a live entry. Guarded by `mutex`. A client + // either names is never deleted (`oauth_client_has_pending_authorisation`). + PendingAuthorisationStore oauth_pending_authorisations{}; + AuthorizationCodeStore oauth_codes{}; // Application Service API registry (Matrix v1.19). Built once at // start_runtime() time from config.appservice().registration_files and // never mutated afterward — every request reads it as an immutable, diff --git a/include/merovingian/homeserver/LocalHttpResponse.hpp b/include/merovingian/homeserver/LocalHttpResponse.hpp index 10acf6b74..dc2b5f71c 100644 --- a/include/merovingian/homeserver/LocalHttpResponse.hpp +++ b/include/merovingian/homeserver/LocalHttpResponse.hpp @@ -34,6 +34,11 @@ struct LocalHttpResponse final // ADR-0574: when set, `body` is empty and the HTTP layer sends these bytes, read from the database in chunks // as it writes, with Content-Length set to `size_bytes`. std::optional body_stream{}; + // An OAuth 2.0 HTML page (ADR-0785), built with `oauth::page_headers`. A page is served to the browser at its own + // origin and never read cross-origin, so the client-server boundary adds no CORS header to it + // (`apply_client_response_headers` adds only `X-Content-Type-Options`), and nothing downstream rewrites it: the + // client API's `wrap()` of a router answer returns a page unchanged. Internal only, never written to the wire. + bool page{false}; }; } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/OAuthSecret.hpp b/include/merovingian/homeserver/OAuthSecret.hpp new file mode 100644 index 000000000..df8f7621b --- /dev/null +++ b/include/merovingian/homeserver/OAuthSecret.hpp @@ -0,0 +1,27 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +// The random bytes in every OAuth 2.0 secret this server mints: a pending authorisation's identifier, an +// authorisation code and the browser-binding cookie value. 256 bits, as an access token has. +inline constexpr auto oauth_secret_bytes = std::size_t{32U}; + +// A fresh secret of `oauth_secret_bytes` from the project's secure random source (`crypto::secure_random_hex`), as 64 +// lower-case hex digits: safe unescaped in a URL query, a fragment, a form field and a cookie value. nullopt when the +// random source fails. Returned once to the caller and never kept: a store keeps only `oauth_secret_hash` of it. +[[nodiscard]] auto make_oauth_secret() -> std::optional; + +// The hash an OAuth 2.0 store keeps of a secret: unkeyed BLAKE2b-256 as lower-case hex, as `LoginTokenStore` keeps a +// login token. The secret is 256 random bits, so an unkeyed hash cannot be reversed by guessing. nullopt when +// hashing fails. Compare two results only with `crypto::constant_time_equal`. +[[nodiscard]] auto oauth_secret_hash(std::string_view secret) -> std::optional; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/PasswordLoginRequest.hpp b/include/merovingian/homeserver/PasswordLoginRequest.hpp new file mode 100644 index 000000000..17b8cae52 --- /dev/null +++ b/include/merovingian/homeserver/PasswordLoginRequest.hpp @@ -0,0 +1,24 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::homeserver +{ + +// A password to verify for a login (`verify_password_login`, ADR-0783). Borrowed views: the caller keeps the strings +// alive for the call. +struct PasswordLoginRequest final +{ + // The full user ID, as `login_identifier_user_id` makes it from what the user typed (POST /login does the same). + std::string_view user_id{}; + // The password as typed. Never logged. + std::string_view password{}; + // The rate-limit client key of the caller (`rate_limit_client_key`): failures are counted per (account, source). + std::string_view client_source{}; + // The device the login is for, as the log and audit lines name it. Not validated or created here. + std::string_view device_id{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/PasswordLoginVerification.hpp b/include/merovingian/homeserver/PasswordLoginVerification.hpp new file mode 100644 index 000000000..5e1b3e17a --- /dev/null +++ b/include/merovingian/homeserver/PasswordLoginVerification.hpp @@ -0,0 +1,40 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::homeserver +{ + +// What `verify_password_login` found (ADR-0783). The outcomes are exactly what POST /login tells a client apart, and +// nothing more: an unknown user, a wrong password, a password changed during the hash, and a locked account are all +// `invalid_login`, as /login answers each of them `403 M_FORBIDDEN "invalid login"`. A suspended account is +// `verified`: /login lets it log in (spec v1.19 "Account suspension"). +struct PasswordLoginVerification final +{ + enum class Outcome : std::uint8_t + { + // The password is the account's, and the account may log in: `user_id` names it. + verified, + // /login's `403 M_FORBIDDEN "invalid login"`. + invalid_login, + // The failed-login throttle refused before the password was looked at: /login's `429 M_LIMIT_EXCEEDED "too + // many failed login attempts"` with `retry_after_ms`. + throttled, + // No Argon2id admission slot was free: /login's `429 M_LIMIT_EXCEEDED "too many concurrent authentication + // attempts"` with `retry_after_ms`. Not a failed attempt. + busy, + // The account is deactivated: /login's `403 M_FORBIDDEN "account deactivated"`. + account_deactivated, + }; + + Outcome outcome{Outcome::invalid_login}; + // The verified user; empty unless `outcome` is `verified`. + std::string user_id{}; + // For `throttled` and `busy`: milliseconds until a retry may succeed. Zero otherwise. + std::uint32_t retry_after_ms{0U}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/PendingAuthorisation.hpp b/include/merovingian/homeserver/PendingAuthorisation.hpp new file mode 100644 index 000000000..1d8cc2e3c --- /dev/null +++ b/include/merovingian/homeserver/PendingAuthorisation.hpp @@ -0,0 +1,47 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/oauth/ResponseMode.hpp" + +#include +#include +#include + +namespace merovingian::homeserver +{ + +// A validated authorisation request (`GET /_merovingian/oauth2/authorize`) waiting for the user to log in or register +// and then approve or deny it (plan P5, ADR-0782). `PendingAuthorisationStore` holds it in memory under the hash of a +// random identifier, bound to the browser by the hash of a cookie value. +// +// Every field but the last three is the request as the handler validated it, never repaired. The store sets +// `created_at_ms` and `client_address_key` from its own arguments and starts `user_id` empty. +struct PendingAuthorisation final +{ + // The registered client that asked. + std::string client_id{}; + // The redirect URI exactly as the request gave it (a native loopback URI keeps the port it was sent with); it was + // matched against the registration with `oauth::match_redirect_uri` before the entry was made. + std::string redirect_uri{}; + oauth::ResponseMode response_mode{oauth::ResponseMode::query}; + // The client's `state`, returned with the answer. Empty when the client sent none. + std::string state{}; + // The PKCE `S256` challenge, checked with `oauth::pkce_challenge_is_valid`. + std::string code_challenge{}; + // The device ID the scope names, and the granted scope in canonical order (`oauth::parse_scope`). + std::string device_id{}; + std::string scope{}; + // Whether the request asked for account creation (`prompt=create`). + bool create_account{false}; + // The client's `login_hint`, if any. Shown only as escaped text and never trusted. + std::optional login_hint{}; + // The user whose password was verified on the login or registration page; empty until then. + std::string user_id{}; + // The rate-limit client key of the browser that made the request (`rate_limit_client_key`). + std::string client_address_key{}; + // When the store took the entry, in milliseconds since the epoch. + std::uint64_t created_at_ms{0U}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/PendingAuthorisationStore.hpp b/include/merovingian/homeserver/PendingAuthorisationStore.hpp new file mode 100644 index 000000000..7eefd200e --- /dev/null +++ b/include/merovingian/homeserver/PendingAuthorisationStore.hpp @@ -0,0 +1,120 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/StateGroupKeyHash.hpp" +#include "merovingian/homeserver/HashedSecretTable.hpp" +#include "merovingian/homeserver/PendingAuthorisation.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +// The authorisation requests waiting for their user (plan P5, ADR-0782). In memory only: an entry lives ten minutes, +// and a restart ends a login in progress and nothing else. +// +// An entry is held under the hash of a fresh 256-bit identifier, which `create` returns once (the page carries it in a +// hidden form field); the identifier itself is never kept. It is bound to the browser by the hash of the +// browser-binding token, the value of a cookie: every operation that names an entry needs both, the token is compared +// in constant time, and a wrong token is answered exactly as an unknown identifier is. +// +// Bounded: `max_entries` in all and `max_entries_per_address` per client address key. At a cap the expired entries +// are purged and, if it is still full, the creation is refused. A live entry is never evicted: a flood of requests +// must not be able to end another user's login in progress. Expired entries are removed at the start of every +// operation, soonest first, at the cost of the entries removed. An expired entry behaves as absent. +// +// Every operation takes the current time, so a test needs no clock. Not thread-safe: `runtime.mutex` serialises every +// use (the store is `HomeserverRuntime::oauth_pending_authorisations`). +class PendingAuthorisationStore final +{ +public: + // An entry lives this long from its creation; authenticating does not extend it (spec leaves the lifetime to the + // server; ten minutes is long enough to type a password and register, short enough not to be a standing grant). + static constexpr auto lifetime_ms = std::uint64_t{600'000U}; + // At most this many entries in all: an entry is a few hundred bytes, so the store stays under a few MiB, and the + // retention sweep's walk past clients with pending entries stays bounded (ADR-0782). + static constexpr auto max_entries = std::size_t{8192U}; + // At most this many entries per client address key: one browser has a handful of logins in flight at most, and an + // address cannot fill the store alone. + static constexpr auto max_entries_per_address = std::size_t{16U}; + + enum class Refusal : std::uint8_t + { + // `max_entries` live entries are held. + store_full, + // `max_entries_per_address` live entries are held for the client address key. + address_full, + // The browser-binding token is empty. + no_browser_token, + // The random source or the hash failed. + secret_unavailable, + }; + + // Takes `authorisation`, bound to `browser_token`, for the browser at `client_address_key`, valid for + // `lifetime_ms` from `now_ms`. Sets its `created_at_ms` and `client_address_key` and empties its `user_id`. + // Returns the fresh identifier (`make_oauth_secret`, 64 hex digits), once, or why nothing was stored. + [[nodiscard]] auto create(PendingAuthorisation authorisation, std::string_view browser_token, + std::string_view client_address_key, std::uint64_t now_ms) + -> std::variant; + + // A copy of the live entry `identifier` names, when `browser_token` is the one it is bound to; otherwise nullopt, + // the same for an unknown identifier and for a wrong token. + [[nodiscard]] auto find(std::string_view identifier, std::string_view browser_token, std::uint64_t now_ms) + -> std::optional; + + // Records `user_id` as the user whose password was verified for the entry. False, changing nothing, when `find` + // would answer nullopt. Does not extend the entry's lifetime. + [[nodiscard]] auto record_user(std::string_view identifier, std::string_view browser_token, + std::string_view user_id, std::uint64_t now_ms) -> bool; + + // Removes the entry and returns it, for an approval or a denial; nullopt, removing nothing, when `find` would + // answer nullopt (a wrong token does not spend the entry). + [[nodiscard]] auto consume(std::string_view identifier, std::string_view browser_token, std::uint64_t now_ms) + -> std::optional; + + // How many live entries name `client_id`, after removing the expired ones. No scan. + [[nodiscard]] auto live_count_for_client(std::string_view client_id, std::uint64_t now_ms) -> std::size_t; + + // Whether a live entry names `client_id`, without changing the store. O(1): the latest expiry held for the client. + [[nodiscard]] auto holds_live_entry_for_client(std::string_view client_id, std::uint64_t now_ms) const -> bool; + + // Removes every entry whose lifetime ended at or before `now_ms`. + auto erase_expired(std::uint64_t now_ms) -> void; + + // Entries held, expired ones not yet removed included. + [[nodiscard]] auto size() const noexcept -> std::size_t; + +private: + struct Entry final + { + PendingAuthorisation authorisation{}; + std::string browser_token_hash{}; + std::uint64_t expires_at_ms{0U}; + }; + + template + using KeyedBy = std::unordered_map>; + + // The live entry `identifier` names when `browser_token` matches its binding, or nullptr. Removes expired entries + // first. Valid until the next change. + [[nodiscard]] auto bound_entry(std::string_view identifier, std::string_view browser_token, std::uint64_t now_ms) + -> std::pair; + // Drops an entry that left the table from the per-address and per-client counters. + auto forget(Entry const& entry) -> void; + + HashedSecretTable m_entries{}; + KeyedBy m_count_by_address{}; + // client_id -> the expiry of each of its entries; the last element is the latest. + KeyedBy> m_expiries_by_client{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/RetentionSweep.hpp b/include/merovingian/homeserver/RetentionSweep.hpp index dd44b0260..b3bdfaaf5 100644 --- a/include/merovingian/homeserver/RetentionSweep.hpp +++ b/include/merovingian/homeserver/RetentionSweep.hpp @@ -6,6 +6,7 @@ #include #include +#include #include namespace merovingian::homeserver @@ -29,12 +30,13 @@ inline constexpr auto expired_access_token_grace = std::chrono::hours{24 * 7}; // with a session is never deleted: "The server MUST NOT delete client registrations that have an active session." inline constexpr auto oauth_client_retention = std::chrono::hours{24 * 30}; -// Whether an authorisation request still pending names `client_id`, so its client must not be deleted under it. -// Phase 5 of the OAuth 2.0 work keeps pending authorisations; until then none exist and this is false unless a test -// set `HomeserverRuntime::test_oauth_pending_authorisation`. The retention sweep and the registration cap -// (`register_oauth_client`) both ask it before deleting a client. Called with HomeserverRuntime::mutex held. -[[nodiscard]] auto oauth_client_has_pending_authorisation(HomeserverRuntime const& runtime, std::string_view client_id) - -> bool; +// Whether, at `now_ms` (milliseconds since the epoch), a live pending authorisation or a live unredeemed +// authorisation code names `client_id`, so its client must not be deleted under it (ADR-0780, ADR-0782). O(1): it asks +// `HomeserverRuntime::oauth_pending_authorisations` and `oauth_codes`, never scans them. The retention sweep and the +// registration cap (`register_oauth_client`) both ask it before deleting a client. Called with +// HomeserverRuntime::mutex held. +[[nodiscard]] auto oauth_client_has_pending_authorisation(HomeserverRuntime const& runtime, std::string_view client_id, + std::uint64_t now_ms) -> bool; // One sweep at `now`: // - deletes the sessions and tokens that can no longer authenticate (revoked or long-expired access tokens, diff --git a/include/merovingian/oauth/FormPostOrigin.hpp b/include/merovingian/oauth/FormPostOrigin.hpp new file mode 100644 index 000000000..5eebeb705 --- /dev/null +++ b/include/merovingian/oauth/FormPostOrigin.hpp @@ -0,0 +1,28 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/oauth/OAuthBaseUrl.hpp" + +#include +#include +#include + +namespace merovingian::oauth +{ + +// The origin a browser names in `Origin` for a page of this server (ADR-0784): `https://`, the base URL's host in +// lower case, and `:` only when the base URL names a port other than 443. A browser serialises an origin so +// (RFC 6454 section 6.1: the default port is left out), so this is the one form compared. +[[nodiscard]] auto form_post_origin(OAuthBaseUrl const& base_url) -> std::string; + +// Whether a form post to an OAuth 2.0 page came from this server's own pages (ADR-0784). `origin` and +// `sec_fetch_site` are the request's `Origin` and `Sec-Fetch-Site` header values, nullopt when absent. +// - `Origin` must be present and equal `form_post_origin(base_url)` byte for byte. Absent, `null`, another scheme, +// host or port, an explicit `:443`, a trailing slash or a different case is refused. +// - `Sec-Fetch-Site`, when present, must be exactly `same-origin`. Absent is accepted: not every browser sends it. +// Anything else is refused. Pure: no state, no I/O. +[[nodiscard]] auto form_post_origin_is_accepted(OAuthBaseUrl const& base_url, std::optional origin, + std::optional sec_fetch_site) -> bool; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/PageHeaders.hpp b/include/merovingian/oauth/PageHeaders.hpp index 072fab629..ac6d1ee55 100644 --- a/include/merovingian/oauth/PageHeaders.hpp +++ b/include/merovingian/oauth/PageHeaders.hpp @@ -22,7 +22,7 @@ namespace merovingian::oauth // - `Content-Security-Policy: default-src 'none'; style-src 'sha256-'; // base-uri 'none'; frame-ancestors 'none'; form-action 'self'`. When hashing fails the style source is `'none'`, // so the page loses its style, never its policy; -// - `X-Frame-Options: DENY`, `Referrer-Policy: no-referrer`, `Cache-Control: no-store`. +// - `X-Frame-Options: DENY`, `Referrer-Policy: same-origin` (ADR-0784), `Cache-Control: no-store`. [[nodiscard]] auto page_headers() -> std::vector>; // page_headers() for a page whose form post the server answers with a redirect to `redirect_target`, the client's diff --git a/include/merovingian/oauth/ResponseMode.hpp b/include/merovingian/oauth/ResponseMode.hpp new file mode 100644 index 000000000..f500eb6d5 --- /dev/null +++ b/include/merovingian/oauth/ResponseMode.hpp @@ -0,0 +1,18 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::oauth +{ + +// Where an authorisation answer travels to the client's redirect URI (spec "Login flow", `response_mode`): in the +// query string or in the fragment. The two values `response_modes_supported` advertises. +enum class ResponseMode : std::uint8_t +{ + query, + fragment, +}; + +} // namespace merovingian::oauth diff --git a/src/auth/AGENTS.md b/src/auth/AGENTS.md index 6b4495e1f..7392e20f5 100644 --- a/src/auth/AGENTS.md +++ b/src/auth/AGENTS.md @@ -68,6 +68,17 @@ failures must not feed the login tables either. A successful login clears only t source) key, never the per-account ceiling. Keep the cap and the amortised-O(1) expiry: no code path may scan a table. See `docs/auth-identity.md` "Failed-login throttle". +## One password check, one account creation (ADR-0783) + +A password login is checked only by `verify_login_credentials` (`src/homeserver/AuthService.cpp`), which `POST /login` +(`login_local_user`) and the OAuth 2.0 login page (`verify_password_login`) both call. Its order is fixed: log +`login.started`; the throttle; an Argon2id slot; the stored hash or the dummy hash; the hash with the lock released; +re-find the user and require its hash unchanged; count a failure against the claimed ID or clear the source's +failures. The account-state gate is `account_state_refusal`, one function called after it (`/login` calls it after +its device checks, so keep it out of the verification). A password account is created only by +`register_password_account`, through `register_local_user` or `create_local_account` (the username checks of +`/register` first). Never copy any of these steps into a route or a page: change the shared function. + ## Session lookup and retention `LocalDatabase::sessions` is a `homeserver::SessionTable`: `find` narrows by an index of token-hash digests and then calls diff --git a/src/database/OAuthTables.cpp b/src/database/OAuthTables.cpp index 4b1010a31..7b3b5daea 100644 --- a/src/database/OAuthTables.cpp +++ b/src/database/OAuthTables.cpp @@ -98,7 +98,7 @@ auto OAuthTables::idle_clients(std::size_t max, std::uint64_t used_before_ms, auto walked = std::uint64_t{0U}; for (auto const& [last_used_at_ms, client_id] : idle_) { - if (chosen.size() >= max || last_used_at_ms >= used_before_ms) + if (chosen.size() >= max || last_used_at_ms >= used_before_ms || walked >= max_idle_client_rows_examined) { break; } diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 3970db0f0..a06aa2e73 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -26,9 +26,12 @@ This is the largest and most complex module — read this file carefully before | `RoomService.cpp` | Room operations, event persistence, signing-key lifecycle, appservice and push delivery | | `AppserviceDelivery.cpp` | Application Service API outbound queue (ADR-0163): `enqueue_appservice_delivery` (request path, no network) and `drain_appservice_queues` (the one drainer thread, run by a `PeriodicJob` from `main.cpp`) | | `ClientTxnPrune.cpp` | `prune_client_transactions`: the sweep the `client-txn-prune` `PeriodicJob` runs every hour, deleting to-device `client_txn_ids` records older than 7 days (F-54, ADR-0381) | -| `RetentionSweep.cpp` | `run_retention_sweep`: the sweep the `retention-sweep` `PeriodicJob` runs every hour. Deletes sessions and tokens that can no longer authenticate and `audit_log` rows past `security.audit_log_retention_days`, and OAuth 2.0 clients with no session unused for 30 days (`oauth_client_retention`, least recently used first; never a client with a session, nor one `oauth_client_has_pending_authorisation` names, a seam that is false until phase 5; ADR-0777), in transactions of at most 500 rows (`retention_batch_rows`), at most 20 batches per kind per sweep. `runtime.mutex` is taken for one batch at a time, never across the whole sweep (ADR-0488, ADR-0489) | +| `RetentionSweep.cpp` | `run_retention_sweep`: the sweep the `retention-sweep` `PeriodicJob` runs every hour. Deletes sessions and tokens that can no longer authenticate and `audit_log` rows past `security.audit_log_retention_days`, and OAuth 2.0 clients with no session unused for 30 days (`oauth_client_retention`, least recently used first; never a client with a session, nor one `oauth_client_has_pending_authorisation` names: a live pending authorisation or an unredeemed code, answered in O(1) from the stores; ADR-0777, ADR-0782), in transactions of at most 500 rows (`retention_batch_rows`), at most 20 batches per kind per sweep. `runtime.mutex` is taken for one batch at a time, never across the whole sweep (ADR-0488, ADR-0489) | | `OAuthClientRegistration.cpp` | `POST /_merovingian/oauth2/register` (`register_oauth_client`), the client ID (`oauth_client_id_of`, ADR-0779), the cap and its eviction (ADR-0780), and `find_registered_oauth_client` | | `OAuthJsonResponse.cpp` | `oauth_json_response` / `oauth_error_response`: every OAuth JSON answer, with `no-store` (ADR-0781) | +| `PendingAuthorisationStore.cpp` | `PendingAuthorisationStore` (`HomeserverRuntime::oauth_pending_authorisations`): OAuth 2.0 authorization requests in progress, 10 minutes, under a 32-byte identifier kept as a hash and bound to a browser token compared in constant time; 8192 in all and 16 per client address, never evicting a live entry (ADR-0782). Guarded by `runtime.mutex` | +| `AuthorizationCodeStore.cpp` | `AuthorizationCodeStore` (`HomeserverRuntime::oauth_codes`): authorization codes, 60 s, hashed, bound to client, redirect URI, PKCE challenge, user, device and scope; 8192, never evicted; a redeemed code is remembered until its expiry so a replay is told apart (ADR-0782). Guarded by `runtime.mutex` | +| `OAuthSecret.cpp`, `HashedSecretTable.hpp` | `make_oauth_secret` / `oauth_secret_hash` (32 random bytes, BLAKE2b) and the digest-indexed, constant-time, expiry-ordered table both stores keep their entries in | | `LoginTokenStore.cpp` | `LoginTokenStore`: the in-memory, bounded, single-use login tokens `POST /login/get_token` mints (CS8, ADR-0548). Hash only, constant-time scan, never evicts; guarded by `runtime.mutex` | | `SessionTable.cpp` | `SessionTable`: `LocalDatabase::sessions` with an index of token-hash digests, so `find_session` does not scan (ADR-0488), and an index by (user ID, device ID) behind `erase_device` (F-08), which a login on a held device and a refresh call after their database commit (ADR-0590); `rows_examined()` counts the sessions it visits | | `DeferredPduRetry.cpp` | Retains federation PDUs that could not yet be placed (`deferred_pdus`) and retries them: `retry_deferred_pdus`, `DeferredPduRetryJob` (R03, ADR-0165). A retry holds no lock across `ingest_pdu_event`; `ingest_pdu_event` writes rows only after signature verification | @@ -110,6 +113,17 @@ absolute OAuth address a handler writes comes from `oauth::OAuthBaseUrl` read fr constant from `oauth/OAuthPaths.hpp`; never join the base URL and a path here. The two paths stay in the generic rate-limit tier (ADR-0775); the other OAuth endpoints take `auth_sensitive`. +The authorisation pages (phase 5b) build on four things that are in place now; use them, never a copy: + +- `verify_password_login` and `create_local_account` (`AuthService.cpp`, ADR-0783) are the only password check and the + only session-less account creation. The page passes `rate_limit_client_key` as the client source and client key. +- `PendingAuthorisationStore` and `AuthorizationCodeStore` (ADR-0782) are the only places an authorisation in progress + or a code is kept. Pass `wall_clock_ms()`; never evict, never keep a secret unhashed. +- A page response sets `LocalHttpResponse::page` and carries `oauth::page_headers()`; the boundary then adds no CORS + header and `wrap()` leaves it alone (ADR-0785). A form post is refused unless `oauth::form_post_origin_is_accepted` + accepts its `Origin` and `Sec-Fetch-Site` (ADR-0784). +- Never log a target's query by hand: `sanitized_http_target` drops the whole query under `/_merovingian/oauth2` and + `/_merovingian/account` (ADR-0786). `POST /_merovingian/oauth2/register` is `register_oauth_client` (`OAuthClientRegistration.cpp`), answered before the authentication gate, and also from the general body cap so an oversized body is an OAuth 400 (ADR-0781). Rules: diff --git a/src/homeserver/AuthService.cpp b/src/homeserver/AuthService.cpp index 2c8296e51..6d1657c64 100644 --- a/src/homeserver/AuthService.cpp +++ b/src/homeserver/AuthService.cpp @@ -851,43 +851,22 @@ namespace return true; } - // Shared tail of login_local_user() and login_appservice_user(): device - // validation, account-state (locked/suspended) policy, token issuance, - // and session persistence. The two callers differ only in how they got - // to a validated `user` — one via password verification, the other via - // as_token + namespace verification — everything after that point is - // identical, so it lives here once rather than being duplicated. - // NOLINTBEGIN(bugprone-easily-swappable-parameters) - [[nodiscard]] auto complete_login(HomeserverRuntime& runtime, LocalUser& user, std::string_view device_id, - bool with_ttl, std::string_view display_name) -> OperationResult - { - if (!auth::device_id_is_valid(device_id)) - { - log_diagnostic_audit(runtime.database, "auth", "login.rejected", - { - {"user_id", user.user_id, false}, - {"device_id", std::string{device_id}, false}, - {"reason", "invalid device id", false} - }, - observability::LogEventSeverity::warning, observability::AuditCategory::auth, - "login.rejected", user.user_id, audit_claimed_device_id(device_id), - "invalid device id"); - return make_operation_result(false, {}, "invalid device id"); - } - if (device_id_is_cross_signing_key_id(runtime, user.user_id, device_id)) - { - return make_operation_result(false, {}, "device id must not be a cross-signing key id", 403U); - } - auto const owned_devices = scan_user_devices(runtime.database.persistent_store, user.user_id, device_id); - if (device_creation_over_cap(runtime, user.user_id, device_id, owned_devices)) - { - return make_operation_result(false, {}, "too many devices", 403U); - } + // Why the account may not log in, or nothing (ADR-0783). A deactivated account can never log in again (spec: POST + // /account/deactivate, "removing all ability for the user to login again"); it is checked before the reversible + // locked and suspended states because it outranks them and is permanent. Then auth::login_policy: a locked account + // is answered "invalid login", as a wrong password is; a suspended one may log in (spec v1.19 "Account + // suspension"), its session then refused by the M_USER_SUSPENDED request gate. Each refusal is logged and audited + // as login.rejected. Shared by complete_login, login_local_user_by_id and verify_password_login, so the gate is one + // piece of code. + struct AccountStateRefusal final + { + bool deactivated{false}; + OperationResult result{}; + }; - // A deactivated account can never log in again (spec: POST - // /account/deactivate, "removing all ability for the user to login - // again"). Checked before the reversible locked/suspended states because - // it outranks them and is permanent. + [[nodiscard]] auto account_state_refusal(HomeserverRuntime& runtime, LocalUser const& user, + std::string_view device_id) -> std::optional + { if (user.deactivated) { log_diagnostic_audit(runtime.database, "auth", "login.rejected", @@ -898,7 +877,7 @@ namespace }, observability::LogEventSeverity::warning, observability::AuditCategory::auth, "login.rejected", user.user_id, std::string{device_id}, "403:account deactivated"); - return make_operation_result(false, {}, "account deactivated", 403U); + return AccountStateRefusal{true, make_operation_result(false, {}, "account deactivated", 403U)}; } auto state = auth::AccountState::active; @@ -923,7 +902,48 @@ namespace }, observability::LogEventSeverity::warning, observability::AuditCategory::auth, "login.rejected", user.user_id, std::string{device_id}, "403:" + login.reason); - return make_operation_result(false, {}, "invalid login", 403U); + return AccountStateRefusal{false, make_operation_result(false, {}, "invalid login", 403U)}; + } + return std::nullopt; + } + + // Shared tail of login_local_user() and login_appservice_user(): device + // validation, account-state (locked/suspended) policy, token issuance, + // and session persistence. The two callers differ only in how they got + // to a validated `user` — one via password verification, the other via + // as_token + namespace verification — everything after that point is + // identical, so it lives here once rather than being duplicated. + // NOLINTBEGIN(bugprone-easily-swappable-parameters) + [[nodiscard]] auto complete_login(HomeserverRuntime& runtime, LocalUser& user, std::string_view device_id, + bool with_ttl, std::string_view display_name) -> OperationResult + { + if (!auth::device_id_is_valid(device_id)) + { + log_diagnostic_audit(runtime.database, "auth", "login.rejected", + { + {"user_id", user.user_id, false}, + {"device_id", std::string{device_id}, false}, + {"reason", "invalid device id", false} + }, + observability::LogEventSeverity::warning, observability::AuditCategory::auth, + "login.rejected", user.user_id, audit_claimed_device_id(device_id), + "invalid device id"); + return make_operation_result(false, {}, "invalid device id"); + } + if (device_id_is_cross_signing_key_id(runtime, user.user_id, device_id)) + { + return make_operation_result(false, {}, "device id must not be a cross-signing key id", 403U); + } + auto const owned_devices = scan_user_devices(runtime.database.persistent_store, user.user_id, device_id); + if (device_creation_over_cap(runtime, user.user_id, device_id, owned_devices)) + { + return make_operation_result(false, {}, "too many devices", 403U); + } + + // Deactivated, locked or suspended (the shared gate above). + if (auto refusal = account_state_refusal(runtime, user, device_id); refusal.has_value()) + { + return std::move(refusal->result); } auto const token = issue_token(); @@ -1110,55 +1130,112 @@ namespace return hash; } +namespace +{ + + // The registration gates every password account passes (ADR-0783), in this order: the registration switch and + // token requirement, the trust-and-safety registration policy for `client_key`, the registration token (Argon2id + // inside an admission slot, runtime.mutex released), then make_user (user ID, password policy, reserved, exists, + // hash, store). Shared by register_local_user and create_local_account. + [[nodiscard]] auto register_password_account(HomeserverRuntime& runtime, std::string_view localpart, + std::string_view password, std::string_view registration_token, + std::string_view client_key) -> OperationResult; + +} // namespace + auto register_local_user(HomeserverRuntime& runtime, std::string_view localpart, std::string_view password, std::string_view registration_token) -> OperationResult { - auto const user_id = user_id_from_localpart(runtime.config.server().server_name, localpart); - auto const& registration = runtime.config.security().registration; - auto const policy = - auth::registration_policy({registration.enabled, registration.require_token, !registration_token.empty()}); - if (!policy.allowed) + // The registration policy has always been judged for the fixed address 127.0.0.1 on this path; kept so. + return register_password_account(runtime, localpart, password, registration_token, "127.0.0.1"); +} + +auto create_local_account(HomeserverRuntime& runtime, AccountCreationRequest const& request) -> OperationResult +{ + // The username checks POST /register makes after user-interactive auth, in its order and with its answers. + if (!auth::localpart_is_valid_new(request.localpart)) { - auto const status = policy.reason == "registration token required" ? 403U : 400U; - auto const reason = policy.reason == "registration disabled" ? "registration_disabled" : policy.reason; - return make_operation_result(false, {}, reason, static_cast(status)); + auto refused = make_operation_result(false, {}, "desired username is not valid", 400U); + refused.errcode = "M_INVALID_USERNAME"; + return refused; } - - auto const local_rule = find_policy_rule(runtime, "registration", user_id); - auto const blocked_by_local_policy = local_rule.has_value() && local_rule->action != "allow"; - auto const decision = trust_safety::evaluate_registration_policy( - {user_id, "127.0.0.1", runtime.config.security().registration.enabled, blocked_by_local_policy, - resolve_policy_server_hook(runtime, trust_safety::PolicySurface::registration, user_id)}); - if (!decision.allowed) + // The server's own localparts (the remote media cache owner) are never given to an account; answered as for a + // name already in use (security audit run-1). + if (auth::localpart_is_reserved(request.localpart)) { - return make_operation_result(false, {}, decision.reason.code, 403U); + auto refused = make_operation_result(false, {}, "desired username is already taken", 400U); + refused.errcode = "M_USER_IN_USE"; + return refused; } + // Spec (Application Service API): a user may not create an account inside a namespace an application service + // holds exclusively, nor take an application service's sender. + auto const& server_name = runtime.config.server().server_name; + if (auto const desired_user_id = "@" + std::string{request.localpart} + ":" + server_name; + runtime.appservices.user_namespace_exclusively_owned_by_other(desired_user_id, {}) || + runtime.appservices.is_sender_user_id(desired_user_id, server_name)) + { + auto refused = make_operation_result(false, {}, "this username is reserved for a registered appservice", 400U); + refused.errcode = "M_EXCLUSIVE"; + return refused; + } + return register_password_account(runtime, request.localpart, request.password, request.registration_token, + request.client_key); +} + +namespace +{ - if (registration.require_token) + auto register_password_account(HomeserverRuntime& runtime, std::string_view localpart, std::string_view password, + std::string_view registration_token, std::string_view client_key) -> OperationResult { - // AUTH-4: registration-token verification is Argon2id and must respect - // the same admission cap as /login. Shed load with 429 before doing any - // hash work. - auto const argon_slot = runtime.argon2id_admission->try_acquire(); - if (!argon_slot) + auto const user_id = user_id_from_localpart(runtime.config.server().server_name, localpart); + auto const& registration = runtime.config.security().registration; + auto const policy = + auth::registration_policy({registration.enabled, registration.require_token, !registration_token.empty()}); + if (!policy.allowed) { - return argon2id_admission_refusal(); + auto const status = policy.reason == "registration token required" ? 403U : 400U; + auto const reason = policy.reason == "registration disabled" ? "registration_disabled" : policy.reason; + return make_operation_result(false, {}, reason, static_cast(status)); } - auto const expected_hash = load_hashed_registration_token(registration); - auto const token_ok = [expected_hash = expected_hash.value_or(std::string{}), registration_token]() { - // AUTH-4: registration-token verification is also Argon2id; release - // the runtime mutex while it runs. - auto const released = merovingian::homeserver::RuntimeLockRelease{}; - return !expected_hash.empty() && auth::registration_token_matches(expected_hash, registration_token); - }(); - if (!token_ok) + + auto const local_rule = find_policy_rule(runtime, "registration", user_id); + auto const blocked_by_local_policy = local_rule.has_value() && local_rule->action != "allow"; + auto const decision = trust_safety::evaluate_registration_policy( + {user_id, std::string{client_key}, runtime.config.security().registration.enabled, blocked_by_local_policy, + resolve_policy_server_hook(runtime, trust_safety::PolicySurface::registration, user_id)}); + if (!decision.allowed) { - return make_operation_result(false, {}, "registration token rejected", 403U); + return make_operation_result(false, {}, decision.reason.code, 403U); + } + + if (registration.require_token) + { + // AUTH-4: registration-token verification is Argon2id and must respect + // the same admission cap as /login. Shed load with 429 before doing any + // hash work. + auto const argon_slot = runtime.argon2id_admission->try_acquire(); + if (!argon_slot) + { + return argon2id_admission_refusal(); + } + auto const expected_hash = load_hashed_registration_token(registration); + auto const token_ok = [expected_hash = expected_hash.value_or(std::string{}), registration_token]() { + // AUTH-4: registration-token verification is also Argon2id; release + // the runtime mutex while it runs. + auto const released = merovingian::homeserver::RuntimeLockRelease{}; + return !expected_hash.empty() && auth::registration_token_matches(expected_hash, registration_token); + }(); + if (!token_ok) + { + return make_operation_result(false, {}, "registration token rejected", 403U); + } } + + return make_user(runtime, localpart, password, false, "created"); } - return make_user(runtime, localpart, password, false, "created"); -} +} // namespace auto bootstrap_admin_user(HomeserverRuntime& runtime, std::string_view localpart, std::string_view password) -> OperationResult @@ -1196,106 +1273,181 @@ auto register_appservice_user(HomeserverRuntime& runtime, std::string_view local /*enforce_password_policy=*/false); } +namespace +{ + + // The password check of a login (ADR-0783), shared by POST /login (login_local_user) and the OAuth 2.0 login page + // (verify_password_login). In this order, which must not change (src/auth/AGENTS.md): + // 1. log login.started; + // 2. the failed-login throttle, (account, source) and per account: a refusal is not a failure and costs no hash; + // 3. an Argon2id admission slot: none free is `busy`, never a failed attempt; + // 4. snapshot the stored hash, or the dummy hash for an unknown user, so the time does not reveal which accounts + // exist (the dummy's first use hashes, inside the slot: ADR-0246); + // 5. release runtime.mutex around only the Argon2id verification; + // 6. re-take it and re-validate: the user still exists and its stored hash is still the snapshot; + // 7. on any failure count it against the claimed user ID (existing or not) and audit login.rejected; on success + // clear this source's failures only, never the per-account ceiling. + // The account-state gate is not here: /login applies it in login_local_user_by_id after its device checks. + [[nodiscard]] auto verify_login_credentials(HomeserverRuntime& runtime, PasswordLoginRequest const& request) + -> PasswordLoginVerification + { + auto const user_id = request.user_id; + auto const device_id = request.device_id; + log_diagnostic("login.started", + { + {"user_id", std::string{user_id}, false}, + {"device_id", std::string{device_id}, false} + }); + + // #487, AUTH-2: failures are counted per (account, client source) and per + // account. A refusal here is before the password is looked at, so it neither + // counts as a failure nor costs any Argon2id work. + if (auto const retry_after_ms = login_lockout_remaining_ms(runtime, user_id, request.client_source); + retry_after_ms > 0U) + { + log_diagnostic_audit(runtime.database, "auth", "login.throttled", + { + {"user_id", std::string{user_id}, false}, + {"device_id", std::string{device_id}, false}, + {"retry_after_ms", std::to_string(retry_after_ms), false} + }, + observability::LogEventSeverity::warning, observability::AuditCategory::auth, + "login.throttled", audit_claimed_user_id(user_id), audit_claimed_device_id(device_id), + "429:too many failed login attempts"); + return {PasswordLoginVerification::Outcome::throttled, + {}, + static_cast( + std::min(retry_after_ms, std::numeric_limits::max()))}; + } + + // Snapshot the claimed identity and the hash to verify against. The user + // pointer itself must not outlive the RuntimeLockRelease below: the vector + // may be reallocated while runtime.mutex is dropped around Argon2id. + auto const verified_user_id = std::string{user_id}; + // AUTH-4: bound concurrent Argon2id work before it can start. Shedding load + // here returns 429/M_LIMIT_EXCEEDED and never counts as a failed login, so + // an admission-saturated pile-on does not also exhaust the lockout budget. + // Taken before the dummy hash below: its first use hashes, and that hash + // must count against the cap too (ADR-0246). + auto const argon_slot = runtime.argon2id_admission->try_acquire(); + if (!argon_slot) + { + return {PasswordLoginVerification::Outcome::busy, {}, argon2id_admission_retry_after_ms}; + } + // An unknown user is verified against the dummy hash so the response time + // does not reveal which accounts exist. The dummy is absent only if hashing + // it failed at first use; there is then nothing to verify against and the + // login is refused like any other bad credential. + auto const password_hash = [&]() -> std::optional { + if (auto const* initial_user = find_user(runtime.database, verified_user_id); initial_user != nullptr) + { + return initial_user->password_hash; + } + if (auto const* dummy = dummy_password_hash(); dummy != nullptr) + { + return *dummy; + } + return std::nullopt; + }(); + // AUTH-4: release the runtime mutex around Argon2id verification so a pile + // of login attempts cannot serialise every other request. Snapshot the hash + // by value first; then verify outside the lock. + auto password_valid = false; + { + auto const released = merovingian::homeserver::RuntimeLockRelease{}; + password_valid = password_hash.has_value() && auth::password_matches(*password_hash, request.password); + } + // RuntimeLockRelease has re-acquired the lock. Re-find the user and insist + // the stored password hash is still the one we just verified. A concurrent + // password change (or account deletion) during Argon2id must not issue a + // session against the old credentials. + auto const* user = find_user(runtime.database, verified_user_id); + if (user == nullptr || !password_valid || user->password_hash != *password_hash) + { + // Counted against the *claimed* user_id whether or not it exists, so the + // lockout cannot be used to probe which accounts are real. + record_failed_login(runtime, verified_user_id, request.client_source); + auto const audit_reason = user == nullptr ? "unknown user" : "bad credentials"; + log_diagnostic_audit(runtime.database, "auth", "login.rejected", + { + {"user_id", std::string{user_id}, false}, + {"device_id", std::string{device_id}, false}, + {"status", "403", false}, + {"reason", audit_reason, false} + }, + observability::LogEventSeverity::warning, observability::AuditCategory::auth, + "login.rejected", audit_claimed_user_id(user_id), audit_claimed_device_id(device_id), + std::string{"403:"} + audit_reason); + return {PasswordLoginVerification::Outcome::invalid_login, {}, 0U}; + } + // A correct password clears this source's failure history, so an interrupted + // legitimate login attempt cannot accumulate toward a lockout. The + // per-account ceiling is deliberately left alone. + clear_failed_logins(runtime, user->user_id, request.client_source); + return {PasswordLoginVerification::Outcome::verified, user->user_id, 0U}; + } + +} // namespace + +auto login_identifier_user_id(std::string_view server_name, std::string_view identifier) -> std::string +{ + if (identifier.starts_with("@")) + { + return std::string{identifier}; + } + return "@" + std::string{identifier} + ":" + std::string{server_name}; +} + +auto verify_password_login(HomeserverRuntime& runtime, PasswordLoginRequest const& request) -> PasswordLoginVerification +{ + auto verified = verify_login_credentials(runtime, request); + if (verified.outcome != PasswordLoginVerification::Outcome::verified) + { + return verified; + } + // The lock has been held since the re-validation inside verify_login_credentials, so the user is still there. + auto const* user = find_user(runtime.database, verified.user_id); + if (user == nullptr) + { + return {PasswordLoginVerification::Outcome::invalid_login, {}, 0U}; + } + if (auto const refusal = account_state_refusal(runtime, *user, request.device_id); refusal.has_value()) + { + return {refusal->deactivated ? PasswordLoginVerification::Outcome::account_deactivated + : PasswordLoginVerification::Outcome::invalid_login, + {}, + 0U}; + } + return verified; +} + // NOLINTBEGIN(bugprone-easily-swappable-parameters) auto login_local_user(HomeserverRuntime& runtime, std::string_view user_id, std::string_view password, std::string_view device_id, bool with_ttl, std::string_view client_source, std::string_view display_name) -> OperationResult { - log_diagnostic("login.started", - { - {"user_id", std::string{user_id}, false}, - {"device_id", std::string{device_id}, false} - }); - - // #487, AUTH-2: failures are counted per (account, client source) and per - // account. A refusal here is before the password is looked at, so it neither - // counts as a failure nor costs any Argon2id work. - if (auto const retry_after_ms = login_lockout_remaining_ms(runtime, user_id, client_source); retry_after_ms > 0U) - { - log_diagnostic_audit(runtime.database, "auth", "login.throttled", - { - {"user_id", std::string{user_id}, false}, - {"device_id", std::string{device_id}, false}, - {"retry_after_ms", std::to_string(retry_after_ms), false} - }, - observability::LogEventSeverity::warning, observability::AuditCategory::auth, - "login.throttled", audit_claimed_user_id(user_id), audit_claimed_device_id(device_id), - "429:too many failed login attempts"); + // The password check is shared with the OAuth 2.0 login page (verify_password_login, ADR-0783); the account-state + // gate stays in login_local_user_by_id, after the device checks, where /login has always applied it. + auto const verified = verify_login_credentials(runtime, {user_id, password, client_source, device_id}); + switch (verified.outcome) + { + case PasswordLoginVerification::Outcome::verified: + return login_local_user_by_id(runtime, verified.user_id, device_id, with_ttl, display_name); + case PasswordLoginVerification::Outcome::throttled: { auto throttled = make_operation_result(false, {}, "too many failed login attempts", 429U); - // Carry the delay already computed above so the caller can render the - // Matrix-standard M_LIMIT_EXCEEDED with retry_after_ms rather than a - // 429 a compliant client cannot schedule a retry from. - throttled.retry_after_ms = static_cast( - std::min(retry_after_ms, std::numeric_limits::max())); + // Carry the delay already computed so the caller can render the Matrix-standard M_LIMIT_EXCEEDED with + // retry_after_ms rather than a 429 a compliant client cannot schedule a retry from. + throttled.retry_after_ms = verified.retry_after_ms; return throttled; } - - // Snapshot the claimed identity and the hash to verify against. The user - // pointer itself must not outlive the RuntimeLockRelease below: the vector - // may be reallocated while runtime.mutex is dropped around Argon2id. - auto const verified_user_id = std::string{user_id}; - // AUTH-4: bound concurrent Argon2id work before it can start. Shedding load - // here returns 429/M_LIMIT_EXCEEDED and never counts as a failed login, so - // an admission-saturated pile-on does not also exhaust the lockout budget. - // Taken before the dummy hash below: its first use hashes, and that hash - // must count against the cap too (ADR-0246). - auto const argon_slot = runtime.argon2id_admission->try_acquire(); - if (!argon_slot) - { + case PasswordLoginVerification::Outcome::busy: return argon2id_admission_refusal(); + case PasswordLoginVerification::Outcome::invalid_login: + case PasswordLoginVerification::Outcome::account_deactivated: + break; } - // An unknown user is verified against the dummy hash so the response time - // does not reveal which accounts exist. The dummy is absent only if hashing - // it failed at first use; there is then nothing to verify against and the - // login is refused like any other bad credential. - auto const password_hash = [&]() -> std::optional { - if (auto const* initial_user = find_user(runtime.database, verified_user_id); initial_user != nullptr) - { - return initial_user->password_hash; - } - if (auto const* dummy = dummy_password_hash(); dummy != nullptr) - { - return *dummy; - } - return std::nullopt; - }(); - // AUTH-4: release the runtime mutex around Argon2id verification so a pile - // of login attempts cannot serialise every other request. Snapshot the hash - // by value first; then verify outside the lock. - auto password_valid = false; - { - auto const released = merovingian::homeserver::RuntimeLockRelease{}; - password_valid = password_hash.has_value() && auth::password_matches(*password_hash, password); - } - // RuntimeLockRelease has re-acquired the lock. Re-find the user and insist - // the stored password hash is still the one we just verified. A concurrent - // password change (or account deletion) during Argon2id must not issue a - // session against the old credentials. - auto* user = find_user(runtime.database, verified_user_id); - if (user == nullptr || !password_valid || user->password_hash != *password_hash) - { - // Counted against the *claimed* user_id whether or not it exists, so the - // lockout cannot be used to probe which accounts are real. - record_failed_login(runtime, verified_user_id, client_source); - auto const audit_reason = user == nullptr ? "unknown user" : "bad credentials"; - // Matrix spec §5.7.2: login failures must be 403 M_FORBIDDEN. - log_diagnostic_audit(runtime.database, "auth", "login.rejected", - { - {"user_id", std::string{user_id}, false}, - {"device_id", std::string{device_id}, false}, - {"status", "403", false}, - {"reason", audit_reason, false} - }, - observability::LogEventSeverity::warning, observability::AuditCategory::auth, - "login.rejected", audit_claimed_user_id(user_id), audit_claimed_device_id(device_id), - std::string{"403:"} + audit_reason); - return make_operation_result(false, {}, "invalid login", 403U); - } - // A correct password clears this source's failure history, so an interrupted - // legitimate login attempt cannot accumulate toward a lockout. The - // per-account ceiling is deliberately left alone. - clear_failed_logins(runtime, user->user_id, client_source); - return login_local_user_by_id(runtime, user->user_id, device_id, with_ttl, display_name); + // Matrix spec §5.7.2: login failures must be 403 M_FORBIDDEN. + return make_operation_result(false, {}, "invalid login", 403U); } // NOLINTEND(bugprone-easily-swappable-parameters) @@ -1347,44 +1499,11 @@ auto login_local_user_by_id(HomeserverRuntime& runtime, std::string_view user_id return make_operation_result(false, {}, "too many devices", 403U); } - // See the deactivation gate in the shared helper above: permanent and - // outranking the reversible moderation states. - if (user->deactivated) - { - log_diagnostic_audit(runtime.database, "auth", "login.rejected", - { - {"user_id", std::string{user_id}, false}, - {"device_id", std::string{device_id}, false}, - {"reason", "account deactivated", false} - }, - observability::LogEventSeverity::warning, observability::AuditCategory::auth, - "login.rejected", std::string{user_id}, std::string{device_id}, "403:account deactivated"); - return make_operation_result(false, {}, "account deactivated", 403U); - } - - auto state = auth::AccountState::active; - if (user->locked) + // The account-state gate shared with complete_login and verify_password_login: deactivated (permanent, and + // outranking the reversible moderation states), then locked or suspended. + if (auto refusal = account_state_refusal(runtime, *user, device_id); refusal.has_value()) { - state = auth::AccountState::locked; - } - if (user->suspended) - { - state = auth::AccountState::suspended; - } - auto const login = auth::login_policy({user->user_id, state}); - if (!login.allowed) - { - // Account locked or suspended: still a 403, not a 400. - log_diagnostic_audit(runtime.database, "auth", "login.rejected", - { - {"user_id", user->user_id, false}, - {"device_id", std::string{device_id}, false}, - {"status", "403", false}, - {"reason", login.reason, false} - }, - observability::LogEventSeverity::warning, observability::AuditCategory::auth, - "login.rejected", user->user_id, std::string{device_id}, "403:" + login.reason); - return make_operation_result(false, {}, "invalid login", 403U); + return std::move(refusal->result); } auto const token = issue_token(); diff --git a/src/homeserver/AuthorizationCodeStore.cpp b/src/homeserver/AuthorizationCodeStore.cpp new file mode 100644 index 000000000..dd4395eca --- /dev/null +++ b/src/homeserver/AuthorizationCodeStore.cpp @@ -0,0 +1,97 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/AuthorizationCodeStore.hpp" + +#include "merovingian/homeserver/OAuthSecret.hpp" + +#include + +namespace merovingian::homeserver +{ + +auto AuthorizationCodeStore::forget_unredeemed(Entry const& entry) -> void +{ + auto const client = m_unredeemed_expiries_by_client.find(entry.grant.client_id); + if (client == m_unredeemed_expiries_by_client.end()) + { + return; + } + if (auto const expiry = client->second.find(entry.expires_at_ms); expiry != client->second.end()) + { + client->second.erase(expiry); + } + if (client->second.empty()) + { + m_unredeemed_expiries_by_client.erase(client); + } +} + +auto AuthorizationCodeStore::erase_expired(std::uint64_t now_ms) -> void +{ + m_codes.erase_expired(now_ms, [this](Entry const& entry) { + if (!entry.redeemed) + { + forget_unredeemed(entry); + } + }); +} + +auto AuthorizationCodeStore::issue(AuthorizationGrant grant, std::uint64_t now_ms) -> std::variant +{ + erase_expired(now_ms); + if (m_codes.size() >= max_codes) + { + return Refusal::store_full; + } + auto code = make_oauth_secret(); + auto code_hash = code.has_value() ? oauth_secret_hash(*code) : std::nullopt; + if (!code_hash.has_value()) + { + return Refusal::secret_unavailable; + } + auto const expires_at_ms = now_ms + lifetime_ms; + m_unredeemed_expiries_by_client[grant.client_id].insert(expires_at_ms); + m_codes.insert(std::move(*code_hash), Entry{std::move(grant), expires_at_ms, false}, expires_at_ms); + return std::move(*code); +} + +auto AuthorizationCodeStore::redeem(std::string_view code, std::uint64_t now_ms) -> AuthorizationCodeRedemption +{ + erase_expired(now_ms); + auto const code_hash = oauth_secret_hash(code); + auto* entry = code_hash.has_value() ? m_codes.find(*code_hash) : nullptr; + if (entry == nullptr) + { + return {}; + } + if (entry->redeemed) + { + return {AuthorizationCodeRedemption::Outcome::replayed, {}, entry->grant.user_id, entry->grant.device_id}; + } + forget_unredeemed(*entry); + entry->redeemed = true; + return {AuthorizationCodeRedemption::Outcome::fresh, entry->grant, entry->grant.user_id, entry->grant.device_id}; +} + +auto AuthorizationCodeStore::unredeemed_count_for_client(std::string_view client_id, std::uint64_t now_ms) + -> std::size_t +{ + erase_expired(now_ms); + auto const client = m_unredeemed_expiries_by_client.find(client_id); + return client == m_unredeemed_expiries_by_client.end() ? 0U : client->second.size(); +} + +auto AuthorizationCodeStore::holds_unredeemed_code_for_client(std::string_view client_id, std::uint64_t now_ms) const + -> bool +{ + auto const client = m_unredeemed_expiries_by_client.find(client_id); + return client != m_unredeemed_expiries_by_client.end() && !client->second.empty() && + *client->second.rbegin() > now_ms; +} + +auto AuthorizationCodeStore::size() const noexcept -> std::size_t +{ + return m_codes.size(); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index 0e7c3f57b..187b5eff8 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -388,7 +388,8 @@ namespace -> void { append_header_if_missing(response.headers, "X-Content-Type-Options", "nosniff"); - if (cors.allowed_origins.empty()) + // An OAuth 2.0 page is same-origin only: no CORS header may let another origin read it (ADR-0785). + if (response.page || cors.allowed_origins.empty()) { return; } @@ -3093,13 +3094,10 @@ namespace return json_serialize(json_obj(std::move(members))); } + // The one normalisation of a typed identifier, shared with the OAuth 2.0 login page (ADR-0783). [[nodiscard]] auto matrix_user_id(std::string_view server_name, std::string_view user) -> std::string { - if (user.starts_with("@")) - { - return std::string{user}; - } - return "@" + std::string{user} + ":" + std::string{server_name}; + return login_identifier_user_id(server_name, user); } [[nodiscard]] auto parse_login_body(std::string_view body, std::string_view server_name) @@ -8135,6 +8133,11 @@ namespace [[nodiscard]] auto wrap(LocalHttpResponse const& r, std::string_view key) -> LocalHttpResponse { + // A page is served as built, never re-encoded as JSON (ADR-0785). + if (r.page) + { + return r; + } if (r.status != 200U) { return err(r.status, error_code_for(r), r.body); @@ -15609,30 +15612,12 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return dispatch_err(req, rt, 500U, "M_UNKNOWN", "could not generate a user ID"); } } - if (!auth::localpart_is_valid_new(*body->localpart)) - { - return dispatch_err(req, rt, 400U, "M_INVALID_USERNAME", "desired username is not valid"); - } - // The server's own localparts (the remote media cache owner) are never given to an - // account; answer as for a name already in use (security audit run-1). - if (auth::localpart_is_reserved(*body->localpart)) - { - return dispatch_err(req, rt, 400U, "M_USER_IN_USE", "desired username is already taken"); - } - // Spec: "normal users who attempt to create users ... inside an - // application service-defined namespace will receive ... M_EXCLUSIVE - // ... but only if the application service has defined the namespace - // as exclusive." This path is reached only for an ordinary - // (non-appservice) registration — the m.login.application_service - // branch above already returned. - if (auto const desired_user_id = "@" + *body->localpart + ":" + rt.homeserver.config.server().server_name; - rt.homeserver.appservices.user_namespace_exclusively_owned_by_other(desired_user_id, {}) || - rt.homeserver.appservices.is_sender_user_id(desired_user_id, rt.homeserver.config.server().server_name)) - { - return dispatch_err(req, rt, 400U, "M_EXCLUSIVE", "this username is reserved for a registered appservice"); - } - auto const result = - register_local_user(rt.homeserver, *body->localpart, body->password, body->registration_token); + // The username checks (not valid, reserved, an appservice's exclusive namespace or sender) and every + // registration gate, shared with the OAuth 2.0 account page (ADR-0783). This path is reached only for an + // ordinary (non-appservice) registration: the m.login.application_service branch above already returned. + // The registration policy is judged for the fixed address 127.0.0.1 here, as it always has been. + auto const result = create_local_account( + rt.homeserver, {*body->localpart, body->password, body->registration_token, "127.0.0.1"}); if (!result.ok) { // A refusal that names its own errcode (M_WEAK_PASSWORD, ADR-0236) keeps it. @@ -22269,11 +22254,17 @@ auto handle_client_server_request(ClientServerRuntime& rt, LocalHttpRequest cons } if (result.status == DispatchResult::Status::complete) { - apply_cors_headers(req, result.response, rt.cors); + apply_client_response_headers(req, result.response, rt.cors); } return result; } +auto apply_client_response_headers(LocalHttpRequest const& req, LocalHttpResponse& response, + config::CorsConfig const& cors) -> void +{ + apply_cors_headers(req, response, cors); +} + auto device_count(ClientServerRuntime const& rt, std::string_view user) noexcept -> std::size_t { return static_cast(std::ranges::count_if(rt.devices, [user](ClientDevice const& d) { diff --git a/src/homeserver/OAuthClientRegistration.cpp b/src/homeserver/OAuthClientRegistration.cpp index 04ed461af..9baef1990 100644 --- a/src/homeserver/OAuthClientRegistration.cpp +++ b/src/homeserver/OAuthClientRegistration.cpp @@ -12,10 +12,13 @@ #include "merovingian/crypto/TokenKey.hpp" #include "merovingian/database/OAuthClientStoreResult.hpp" #include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/OAuthTables.hpp" #include "merovingian/database/PersistentOAuthClient.hpp" +#include "merovingian/homeserver/AuthorizationCodeStore.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/OAuthJsonResponse.hpp" +#include "merovingian/homeserver/PendingAuthorisationStore.hpp" #include "merovingian/homeserver/RetentionSweep.hpp" #include "merovingian/oauth/ApplicationType.hpp" #include "merovingian/oauth/OAuthErrorCodes.hpp" @@ -37,6 +40,12 @@ namespace merovingian::homeserver { + +// The evictions one registration may make must fit in the idle-client walk after it skipped every client a pending +// authorisation or an unredeemed code can name (ADR-0782). +static_assert(PendingAuthorisationStore::max_entries + AuthorizationCodeStore::max_codes + + max_oauth_client_evictions_per_registration <= + database::max_idle_client_rows_examined); namespace { @@ -171,8 +180,9 @@ namespace return false; } auto const& homeserver = runtime.homeserver; - auto const pending = [&homeserver](std::string_view client_id) { - return oauth_client_has_pending_authorisation(homeserver, client_id); + auto const now_ms = wall_clock_ms(); + auto const pending = [&homeserver, now_ms](std::string_view client_id) { + return oauth_client_has_pending_authorisation(homeserver, client_id, now_ms); }; auto const idle = database::oauth_clients_without_sessions(store, needed, std::numeric_limits::max(), pending); diff --git a/src/homeserver/OAuthSecret.cpp b/src/homeserver/OAuthSecret.cpp new file mode 100644 index 000000000..1b93c1eb9 --- /dev/null +++ b/src/homeserver/OAuthSecret.cpp @@ -0,0 +1,24 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/OAuthSecret.hpp" + +#include "merovingian/crypto/GenericHash.hpp" +#include "merovingian/crypto/Random.hpp" + +#include + +namespace merovingian::homeserver +{ + +auto make_oauth_secret() -> std::optional +{ + return crypto::secure_random_hex(oauth_secret_bytes); +} + +auto oauth_secret_hash(std::string_view secret) -> std::optional +{ + auto const pieces = std::array{secret}; + return crypto::generic_hash(pieces); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/PendingAuthorisationStore.cpp b/src/homeserver/PendingAuthorisationStore.cpp new file mode 100644 index 000000000..343347a1e --- /dev/null +++ b/src/homeserver/PendingAuthorisationStore.cpp @@ -0,0 +1,169 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/PendingAuthorisationStore.hpp" + +#include "merovingian/crypto/ConstantTime.hpp" +#include "merovingian/homeserver/OAuthSecret.hpp" + +#include + +namespace merovingian::homeserver +{ +namespace +{ + + // Compared with the offered token's hash when no entry matched the identifier, so a wrong token and an unknown + // identifier cost the same comparison. 64 hex digits, as every `oauth_secret_hash` is. + constexpr auto unmatched_token_hash = + std::string_view{"0000000000000000000000000000000000000000000000000000000000000000"}; + +} // namespace + +auto PendingAuthorisationStore::forget(Entry const& entry) -> void +{ + if (auto const address = m_count_by_address.find(entry.authorisation.client_address_key); + address != m_count_by_address.end()) + { + if (--address->second == 0U) + { + m_count_by_address.erase(address); + } + } + if (auto const client = m_expiries_by_client.find(entry.authorisation.client_id); + client != m_expiries_by_client.end()) + { + if (auto const expiry = client->second.find(entry.expires_at_ms); expiry != client->second.end()) + { + client->second.erase(expiry); + } + if (client->second.empty()) + { + m_expiries_by_client.erase(client); + } + } +} + +auto PendingAuthorisationStore::erase_expired(std::uint64_t now_ms) -> void +{ + m_entries.erase_expired(now_ms, [this](Entry const& entry) { + forget(entry); + }); +} + +auto PendingAuthorisationStore::create(PendingAuthorisation authorisation, std::string_view browser_token, + std::string_view client_address_key, std::uint64_t now_ms) + -> std::variant +{ + if (browser_token.empty()) + { + return Refusal::no_browser_token; + } + erase_expired(now_ms); + if (m_entries.size() >= max_entries) + { + return Refusal::store_full; + } + if (auto const address = m_count_by_address.find(client_address_key); + address != m_count_by_address.end() && address->second >= max_entries_per_address) + { + return Refusal::address_full; + } + auto identifier = make_oauth_secret(); + auto identifier_hash = identifier.has_value() ? oauth_secret_hash(*identifier) : std::nullopt; + auto browser_token_hash = oauth_secret_hash(browser_token); + if (!identifier_hash.has_value() || !browser_token_hash.has_value()) + { + return Refusal::secret_unavailable; + } + authorisation.client_address_key = std::string{client_address_key}; + authorisation.created_at_ms = now_ms; + authorisation.user_id.clear(); + auto const expires_at_ms = now_ms + lifetime_ms; + ++m_count_by_address[authorisation.client_address_key]; + m_expiries_by_client[authorisation.client_id].insert(expires_at_ms); + m_entries.insert(std::move(*identifier_hash), + Entry{std::move(authorisation), std::move(*browser_token_hash), expires_at_ms}, expires_at_ms); + return std::move(*identifier); +} + +auto PendingAuthorisationStore::bound_entry(std::string_view identifier, std::string_view browser_token, + std::uint64_t now_ms) -> std::pair +{ + erase_expired(now_ms); + auto identifier_hash = oauth_secret_hash(identifier); + auto const token_hash = oauth_secret_hash(browser_token); + if (!identifier_hash.has_value() || !token_hash.has_value()) + { + return {nullptr, {}}; + } + auto* entry = m_entries.find(*identifier_hash); + // Compare the token whether or not the identifier was found, so both refusals cost the same. + auto const token_matches = crypto::constant_time_equal( + entry == nullptr ? unmatched_token_hash : std::string_view{entry->browser_token_hash}, *token_hash); + if (entry == nullptr || !token_matches || browser_token.empty()) + { + return {nullptr, {}}; + } + return {entry, std::move(*identifier_hash)}; +} + +auto PendingAuthorisationStore::find(std::string_view identifier, std::string_view browser_token, std::uint64_t now_ms) + -> std::optional +{ + auto const [entry, identifier_hash] = bound_entry(identifier, browser_token, now_ms); + if (entry == nullptr) + { + return std::nullopt; + } + return entry->authorisation; +} + +auto PendingAuthorisationStore::record_user(std::string_view identifier, std::string_view browser_token, + std::string_view user_id, std::uint64_t now_ms) -> bool +{ + auto const [entry, identifier_hash] = bound_entry(identifier, browser_token, now_ms); + if (entry == nullptr) + { + return false; + } + entry->authorisation.user_id = std::string{user_id}; + return true; +} + +auto PendingAuthorisationStore::consume(std::string_view identifier, std::string_view browser_token, + std::uint64_t now_ms) -> std::optional +{ + auto const [entry, identifier_hash] = bound_entry(identifier, browser_token, now_ms); + if (entry == nullptr) + { + return std::nullopt; + } + auto taken = m_entries.erase(identifier_hash); + if (!taken.has_value()) + { + return std::nullopt; + } + forget(*taken); + return std::move(taken->authorisation); +} + +auto PendingAuthorisationStore::live_count_for_client(std::string_view client_id, std::uint64_t now_ms) -> std::size_t +{ + erase_expired(now_ms); + auto const client = m_expiries_by_client.find(client_id); + return client == m_expiries_by_client.end() ? 0U : client->second.size(); +} + +auto PendingAuthorisationStore::holds_live_entry_for_client(std::string_view client_id, std::uint64_t now_ms) const + -> bool +{ + auto const client = m_expiries_by_client.find(client_id); + return client != m_expiries_by_client.end() && !client->second.empty() && *client->second.rbegin() > now_ms; +} + +auto PendingAuthorisationStore::size() const noexcept -> std::size_t +{ + return m_entries.size(); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/RetentionSweep.cpp b/src/homeserver/RetentionSweep.cpp index d75038f6f..9c4e8629e 100644 --- a/src/homeserver/RetentionSweep.cpp +++ b/src/homeserver/RetentionSweep.cpp @@ -4,12 +4,15 @@ #include "merovingian/homeserver/RetentionSweep.hpp" #include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/OAuthTables.hpp" #include "merovingian/database/PersistentStore.hpp" #include "merovingian/database/PersistentStoreBackend.hpp" #include "merovingian/database/UnusableCredentials.hpp" +#include "merovingian/homeserver/AuthorizationCodeStore.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/KeyServerCache.hpp" #include "merovingian/homeserver/LocalServices.hpp" +#include "merovingian/homeserver/PendingAuthorisationStore.hpp" #include "merovingian/observability/AuditCategory.hpp" #include "merovingian/observability/SingleLog.hpp" @@ -29,6 +32,11 @@ namespace merovingian::homeserver { +// A batch of the client sweep must fit in the idle-client walk after it skipped every client a pending authorisation +// or an unredeemed code can name, or a walk that stopped at its bound could hide a client that may go (ADR-0782). +static_assert(PendingAuthorisationStore::max_entries + AuthorizationCodeStore::max_codes + retention_batch_rows <= + database::max_idle_client_rows_examined); + namespace { @@ -183,8 +191,8 @@ namespace return true; } auto const used_before_ms = now_ms - keep_ms; - auto const pending = [&runtime](std::string_view client_id) { - return oauth_client_has_pending_authorisation(runtime, client_id); + auto const pending = [&runtime, now_ms](std::string_view client_id) { + return oauth_client_has_pending_authorisation(runtime, client_id, now_ms); }; auto batches = std::size_t{0U}; auto deleted = std::size_t{0U}; @@ -216,11 +224,12 @@ namespace } // namespace -// The seam phase 5 fills in: no authorisation request is kept yet, so none can name a client. A test stands in for one -// through `test_oauth_pending_authorisation`, which production never sets. -auto oauth_client_has_pending_authorisation(HomeserverRuntime const& runtime, std::string_view client_id) -> bool +// Two lookups by client ID, each answered from the latest expiry the store holds for the client: no scan. +auto oauth_client_has_pending_authorisation(HomeserverRuntime const& runtime, std::string_view client_id, + std::uint64_t now_ms) -> bool { - return runtime.test_oauth_pending_authorisation && runtime.test_oauth_pending_authorisation(client_id); + return runtime.oauth_pending_authorisations.holds_live_entry_for_client(client_id, now_ms) || + runtime.oauth_codes.holds_unredeemed_code_for_client(client_id, now_ms); } auto run_retention_sweep(HomeserverRuntime& runtime, std::chrono::system_clock::time_point now, StopFlag const& stop) diff --git a/src/homeserver/meson.build b/src/homeserver/meson.build index 70ff17a33..9ebdf2536 100644 --- a/src/homeserver/meson.build +++ b/src/homeserver/meson.build @@ -7,6 +7,9 @@ homeserver_sources = files( 'ClientTxnPrune.cpp', 'SessionTable.cpp', 'LoginTokenStore.cpp', + 'AuthorizationCodeStore.cpp', + 'OAuthSecret.cpp', + 'PendingAuthorisationStore.cpp', 'SafetyReportIndex.cpp', 'RetentionSweep.cpp', 'DefaultPushRuleset.cpp', diff --git a/src/oauth/AGENTS.md b/src/oauth/AGENTS.md index b4ec57146..061e63c1b 100644 --- a/src/oauth/AGENTS.md +++ b/src/oauth/AGENTS.md @@ -22,6 +22,7 @@ Pure functions and value types for the built-in OAuth 2.0 API | `OAuthPaths.hpp` | Every OAuth route path: the `PagePath` constants under `/_merovingian/oauth2/` and `/_merovingian/account`, and the two `auth_metadata` paths (ADR-0773) | | `OAuthBaseUrl.cpp` | `OAuthBaseUrl::read`: `server.public_baseurl` as an `https` URL with a host and no query; `issuer()` (one trailing slash) and `url(PagePath)` (ADR-0773) | | `ServerMetadata.cpp`, `ServerMetadataOptions.hpp` | `server_metadata`: the `auth_metadata` document, device grant, `prompt=create` and account management fields only when their option is on | +| `FormPostOrigin.cpp` | `form_post_origin`, `form_post_origin_is_accepted`: a page's form post must name this server's origin exactly, and `Sec-Fetch-Site`, when sent, `same-origin` (ADR-0784) | | `HandOffAllowlist.cpp` | `hand_off_allowlist_entry_error`, `hand_off_allowlist_error`: an https origin or a bare private-use scheme, at most 32, each once (ADR-0774) | | `DisplayText.cpp`, `AsciiCase.cpp` | Module-internal: `display_text_is_safe` (no control or bidirectional formatting character) and `ascii_lower` | @@ -42,7 +43,9 @@ Pure functions and value types for the built-in OAuth 2.0 API `HtmlLiteral`, `HtmlName` or `PagePath`. Never concatenate a value into markup, add a `")"); + auto& rt = fixture.started.runtime; + auto const page = start_page(rt, oauth_authorize_parameters(fixture.client_id)); + + WHEN("alice signs in") + { + auto const consent = login(rt, page, "alice", alice_password); + + THEN("the name is shown as text, never as markup") + { + REQUIRE(consent.status == 200U); + CHECK_FALSE(contains(consent.body, "&"}; +constexpr auto markup_escaped = std::string_view{""><script>alert('x')</script>&amp;"}; +// U+202E RIGHT-TO-LEFT OVERRIDE, which can make a host read backwards. +constexpr auto bidi_override = std::string_view{"\xE2\x80\xAE"}; + +[[nodiscard]] auto with_bidi(std::string_view text) -> std::string +{ + auto value = std::string{bidi_override}; + value.append(text); + return value; +} + +[[nodiscard]] auto read(std::string_view text) -> ParsedUri +{ + auto parsed = ParsedUri::read(text); + REQUIRE(std::holds_alternative(parsed)); + return std::get(std::move(parsed)); +} + +[[nodiscard]] auto count(std::string_view haystack, std::string_view needle) -> std::size_t +{ + auto found = std::size_t{0U}; + for (auto at = haystack.find(needle); at != std::string_view::npos; at = haystack.find(needle, at + 1U)) + { + ++found; + } + return found; +} + +[[nodiscard]] auto contains(std::string_view haystack, std::string_view needle) -> bool +{ + return haystack.find(needle) != std::string_view::npos; +} + +// No markup a page did not write itself: no script element, no raw payload, no override character. +auto require_no_injection(std::string_view html) -> void +{ + REQUIRE_FALSE(contains(html, "That username and password do not match.)")); + REQUIRE(count(html, "This server does not accept new accounts.)")); + } + } + } +} + +SCENARIO("The consent page escapes every client value and falls back for one it cannot show", + "[oauth][authorize-page][consent][security]") +{ + GIVEN("a client whose name, user ID and device ID hold markup") + { + auto input = ConsentPageInput{}; + input.pending_id = pending; + input.client_name = markup; + input.client_host = "app.example.com"; + input.user_id = markup; + input.device_id = markup; + input.policy_uri = "https://app.example.com/policy?a=1&b=\"2\""; + input.tos_uri = "javascript:alert(1)"; + auto const target = read("https://callback.example.com/cb"); + + WHEN("the consent page is rendered") + { + auto const html = merovingian::oauth::consent_page(input, target).render(); + + THEN("every value is escaped, the destination is the redirect host, and approve and deny are offered") + { + require_no_injection(html); + REQUIRE(count(html, markup_escaped) == 3U); + REQUIRE(contains(html, "app.example.com")); + REQUIRE(contains(html, "callback.example.com")); + REQUIRE(contains(html, "full access to your account")); + REQUIRE(contains(html, R"(name="action" value="approve")")); + REQUIRE(contains(html, R"(name="action" value="deny")")); + } + + THEN("only an https link becomes an href") + { + REQUIRE_FALSE(contains(html, "javascript:")); + REQUIRE_FALSE(contains(html, "Terms of service")); + REQUIRE_FALSE(contains(html, "Privacy policy")); + } + } + } + + GIVEN("a name with a right-to-left override, a name of 10 KiB, and no name") + { + auto const bidi_name = with_bidi("Element"); + auto const long_name = std::string(10U * 1024U, 'A'); + auto const target = read("com.example.app:/callback"); + auto input = ConsentPageInput{}; + input.pending_id = pending; + input.client_host = "app.example.com"; + input.user_id = "@alice:example.org"; + input.device_id = "DEVICEABCDEF"; + input.policy_uri = "https://app.example.com/policy"; + input.replaces_existing_device = true; + + WHEN("the consent page is rendered for each") + { + input.client_name = bidi_name; + auto const bidi = merovingian::oauth::consent_page(input, target).render(); + input.client_name = long_name; + auto const long_page = merovingian::oauth::consent_page(input, target).render(); + input.client_name.reset(); + auto const unnamed = merovingian::oauth::consent_page(input, target).render(); + + THEN("each shows the fixed phrase, never the raw name") + { + for (auto const* html : {&bidi, &long_page, &unnamed}) + { + require_no_injection(*html); + REQUIRE(contains(*html, "An application with no name")); + REQUIRE_FALSE(contains(*html, "Element")); + REQUIRE_FALSE(contains(*html, long_name.substr(0U, 200U))); + } + } + + THEN("the private-use destination is named by its scheme, the policy is linked, the replacement noticed") + { + REQUIRE(contains(unnamed, "com.example.app: (an application on your device)")); + REQUIRE(contains(unnamed, R"()")); + REQUIRE(contains(unnamed, "signs that session out and replaces it")); + } + } + } +} + +SCENARIO("The error page shows its title and message and no form", "[oauth][authorize-page]") +{ + GIVEN("a fixed title and message") + { + WHEN("the error page is rendered") + { + auto const html = merovingian::oauth::error_page(HtmlText{"Sign-in expired"}, + HtmlText{"Return to the application and start again."}) + .render(); + + THEN("it holds both and no form") + { + REQUIRE(contains(html, "

Sign-in expired

")); + REQUIRE(contains(html, "Return to the application and start again.")); + REQUIRE_FALSE(contains(html, " + +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::oauth::authorization_redirect_address; +using merovingian::oauth::ParsedUri; +using merovingian::oauth::RedirectParameter; +using merovingian::oauth::ResponseMode; + +[[nodiscard]] auto read(std::string_view text) -> ParsedUri +{ + auto parsed = ParsedUri::read(text); + REQUIRE(std::holds_alternative(parsed)); + return std::get(std::move(parsed)); +} + +constexpr auto code_and_state = std::array{ + RedirectParameter{"code", "c0de"}, + RedirectParameter{"state", "s1" }, +}; + +// Whether every byte of `text` after `from` is an unreserved character, `%`, an upper-case hex digit, `=` or `&`. +[[nodiscard]] auto only_encoded_after(std::string_view text, std::size_t from) -> bool +{ + for (auto const value : text.substr(from)) + { + auto const allowed = (value >= 'A' && value <= 'Z') || (value >= 'a' && value <= 'z') || + (value >= '0' && value <= '9') || value == '-' || value == '.' || value == '_' || + value == '~' || value == '%' || value == '=' || value == '&'; + if (!allowed) + { + return false; + } + } + return true; +} + +} // namespace + +SCENARIO("An authorisation answer goes in the query of the redirect URI", "[oauth][redirect-address]") +{ + GIVEN("redirect URIs with and without a query, a private-use scheme with and without a path, and a loopback URI") + { + auto const plain = read("https://app.example.com/cb"); + auto const with_query = read("https://app.example.com/cb?tab=1"); + auto const bare_question_mark = read("https://app.example.com/cb?"); + auto const private_use_path = read("com.example.app:/callback"); + auto const private_use_no_path = read("com.example.app:"); + auto const loopback = read("http://127.0.0.1:51234/cb"); + + WHEN("code and state are added with the query response mode") + { + THEN("a new query starts with ?, an existing one continues with &, a bare ? takes them directly") + { + REQUIRE(authorization_redirect_address(plain, ResponseMode::query, code_and_state) == + "https://app.example.com/cb?code=c0de&state=s1"); + REQUIRE(authorization_redirect_address(with_query, ResponseMode::query, code_and_state) == + "https://app.example.com/cb?tab=1&code=c0de&state=s1"); + REQUIRE(authorization_redirect_address(bare_question_mark, ResponseMode::query, code_and_state) == + "https://app.example.com/cb?code=c0de&state=s1"); + REQUIRE(authorization_redirect_address(private_use_path, ResponseMode::query, code_and_state) == + "com.example.app:/callback?code=c0de&state=s1"); + REQUIRE(authorization_redirect_address(private_use_no_path, ResponseMode::query, code_and_state) == + "com.example.app:?code=c0de&state=s1"); + REQUIRE(authorization_redirect_address(loopback, ResponseMode::query, code_and_state) == + "http://127.0.0.1:51234/cb?code=c0de&state=s1"); + } + } + } +} + +SCENARIO("An authorisation answer goes in the fragment when the response mode says so", "[oauth][redirect-address]") +{ + GIVEN("a redirect URI with a query and a private-use one") + { + auto const with_query = read("https://app.example.com/cb?tab=1"); + auto const private_use = read("com.example.app:/callback"); + + WHEN("code and state are added with the fragment response mode") + { + THEN("they follow a # and the query of the URI is left as it was") + { + REQUIRE(authorization_redirect_address(with_query, ResponseMode::fragment, code_and_state) == + "https://app.example.com/cb?tab=1#code=c0de&state=s1"); + REQUIRE(authorization_redirect_address(private_use, ResponseMode::fragment, code_and_state) == + "com.example.app:/callback#code=c0de&state=s1"); + } + } + } +} + +SCENARIO("Hostile parameter values cannot break out of their parameter", "[oauth][redirect-address][security]") +{ + GIVEN("a state holding CR, LF, &, =, #, a space, a quote, % and non-ASCII UTF-8, and a hostile name") + { + auto const target = read("https://app.example.com/cb"); + auto const state = std::string{"a&b=c#d e\r\nSet-Cookie: x\"%\xC3\xA9"}; + auto const parameters = std::array{ + RedirectParameter{"state", state}, + RedirectParameter{"x&y=z", "v" }, + }; + + WHEN("the address is built in each response mode") + { + auto const in_query = authorization_redirect_address(target, ResponseMode::query, parameters); + auto const in_fragment = authorization_redirect_address(target, ResponseMode::fragment, parameters); + + THEN("every byte outside the unreserved set is %XX with upper-case hex, so no CR, LF, # or space appears") + { + REQUIRE(in_query == "https://app.example.com/cb?state=a%26b%3Dc%23d%20e%0D%0ASet-Cookie%3A%20x%22%25" + "%C3%A9&x%26y%3Dz=v"); + REQUIRE(in_fragment.ends_with(in_query.substr(in_query.find('?') + 1U))); + REQUIRE(only_encoded_after(in_query, in_query.find('?') + 1U)); + REQUIRE(in_query.find('\r') == std::string::npos); + REQUIRE(in_query.find('\n') == std::string::npos); + REQUIRE(in_query.find('#') == std::string::npos); + REQUIRE(in_fragment.find('#') == in_fragment.rfind('#')); + } + } + + WHEN("unreserved characters and an empty value are encoded") + { + THEN("they stay as they are") + { + REQUIRE(merovingian::oauth::percent_encode_redirect_value("AZaz09-._~") == "AZaz09-._~"); + REQUIRE(merovingian::oauth::percent_encode_redirect_value("").empty()); + REQUIRE(merovingian::oauth::percent_encode_redirect_value("+/") == "%2B%2F"); + } + } + } +} + +SCENARIO("An answer with no parameters leaves the redirect URI unchanged", "[oauth][redirect-address][boundary]") +{ + GIVEN("a redirect URI") + { + auto const target = read("https://app.example.com/cb?tab=1"); + + WHEN("no parameter is added") + { + auto const address = + authorization_redirect_address(target, ResponseMode::fragment, std::span{}); + + THEN("the address is the URI as registered") + { + REQUIRE(address == "https://app.example.com/cb?tab=1"); + } + } + } +} From 017692c8a13f8389274b69975c6303533e6ad56b Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 06:47:21 +0000 Subject: [PATCH 15/42] Serve the OAuth 2.0 token and revocation endpoints (ADR-0791 to ADR-0795) POST /_merovingian/oauth2/token serves the authorization code grant (PKCE S256, the redirect URI byte for byte, one transaction with the audit row, a replayed code ending only the session it produced) and the refresh token grant, for public clients only; an OAuth access token always expires. POST /_merovingian/oauth2/revoke ends the session of an access or refresh token as /logout does. POST /refresh and the refresh grant refuse each other's sessions before rotating. Every UIA endpoint answers an OAuth session 403 naming the account page, and device_signing/upload now asks for UIA only to change held keys, as the spec says. Co-Authored-By: Claude Opus 5.5 --- .../references/module-invariants.md | 11 +- CHANGELOG.md | 20 +- ...nd-an-oauth-access-token-always-expires.md | 51 ++ ...-code-ends-only-the-session-it-produced.md | 50 ++ ...ons-do-not-mix-at-the-refresh-endpoints.md | 34 + ...ning-upload-follows-the-spec-exemptions.md | 46 + ...the-session-as-logout-does-whoever-asks.md | 38 + docs/adr/index.md | 5 + docs/auth-identity.md | 51 +- docs/http-transport.md | 9 + docs/matrix-v1.19-client-server-api.md | 2 +- docs/observability-audit.md | 14 + docs/security-coding-rules.md | 18 +- docs/todos/capability-gaps.md | 2 +- docs/user-manual.md | 24 +- include/merovingian/database/OAuthStore.hpp | 8 +- .../merovingian/database/PersistentStore.hpp | 14 +- .../merovingian/homeserver/AuthService.hpp | 33 +- .../AuthorizationCodeRedemption.hpp | 12 +- .../homeserver/AuthorizationCodeStore.hpp | 17 + .../homeserver/ClientDeviceSessions.hpp | 36 + .../homeserver/OAuthClientCredentials.hpp | 27 + .../homeserver/OAuthGrantRequest.hpp | 27 + .../homeserver/OAuthJsonResponse.hpp | 9 + .../homeserver/OAuthRevocation.hpp | 32 + .../homeserver/OAuthTokenEndpoint.hpp | 43 + .../merovingian/homeserver/SignedInDevice.hpp | 20 + .../merovingian/oauth/AccessTokenLifetime.hpp | 35 + include/merovingian/oauth/FormContentType.hpp | 21 + include/merovingian/oauth/OAuthErrorCodes.hpp | 5 + src/auth/AGENTS.md | 16 + src/database/AGENTS.md | 6 +- src/database/OAuthStore.cpp | 6 +- src/database/PersistentStore.cpp | 173 +++- src/homeserver/AGENTS.md | 32 +- src/homeserver/AuthService.cpp | 347 ++++++-- src/homeserver/AuthorizationCodeStore.cpp | 34 +- src/homeserver/ClientServerRuntime.cpp | 311 +++++-- src/homeserver/OAuthAuthorization.cpp | 26 +- src/homeserver/OAuthClientCredentials.cpp | 70 ++ src/homeserver/OAuthJsonResponse.cpp | 19 + src/homeserver/OAuthRevocation.cpp | 112 +++ src/homeserver/OAuthTokenEndpoint.cpp | 301 +++++++ src/homeserver/meson.build | 3 + src/oauth/AGENTS.md | 2 + src/oauth/FormContentType.cpp | 73 ++ src/oauth/meson.build | 1 + tests/conformance/AGENTS.md | 1 + .../test_account_lifecycle_conformance.cpp | 12 +- .../test_client_server_conformance.cpp | 58 +- .../test_oauth_token_conformance.cpp | 245 ++++++ .../test_route_query_conformance.cpp | 4 +- tests/integration/test_oauth_token_flow.cpp | 821 ++++++++++++++++++ tests/meson.build | 3 + tests/support/AGENTS.md | 1 + tests/support/OAuthTokenSupport.hpp | 174 ++++ .../test_oauth_authorization_code_store.cpp | 96 ++ tests/unit/test_oauth_token_rules.cpp | 93 ++ 58 files changed, 3505 insertions(+), 249 deletions(-) create mode 100644 docs/adr/0791-the-oauth-token-endpoint-reuses-the-login-tokens-and-an-oauth-access-token-always-expires.md create mode 100644 docs/adr/0792-an-oauth-grant-is-one-transaction-and-a-replayed-code-ends-only-the-session-it-produced.md create mode 100644 docs/adr/0793-oauth-and-legacy-sessions-do-not-mix-at-the-refresh-endpoints.md create mode 100644 docs/adr/0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md create mode 100644 docs/adr/0795-oauth-revocation-ends-the-session-as-logout-does-whoever-asks.md create mode 100644 include/merovingian/homeserver/ClientDeviceSessions.hpp create mode 100644 include/merovingian/homeserver/OAuthClientCredentials.hpp create mode 100644 include/merovingian/homeserver/OAuthGrantRequest.hpp create mode 100644 include/merovingian/homeserver/OAuthRevocation.hpp create mode 100644 include/merovingian/homeserver/OAuthTokenEndpoint.hpp create mode 100644 include/merovingian/homeserver/SignedInDevice.hpp create mode 100644 include/merovingian/oauth/AccessTokenLifetime.hpp create mode 100644 include/merovingian/oauth/FormContentType.hpp create mode 100644 src/homeserver/OAuthClientCredentials.cpp create mode 100644 src/homeserver/OAuthRevocation.cpp create mode 100644 src/homeserver/OAuthTokenEndpoint.cpp create mode 100644 src/oauth/FormContentType.cpp create mode 100644 tests/conformance/test_oauth_token_conformance.cpp create mode 100644 tests/integration/test_oauth_token_flow.cpp create mode 100644 tests/support/OAuthTokenSupport.hpp create mode 100644 tests/unit/test_oauth_token_rules.cpp diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index 375510be2..f436525e8 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -57,6 +57,9 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that - UIA sessions are capped and answer 429, never evicting (ADR-0683). Login on an existing device deletes earlier rows (ADR-0590). Login tokens are never persisted (ADR-0548). `#UIAA` - The production password cost is pinned by `tests/password_cost/` (ADR-0510). +- An OAuth session is created only by `grant_oauth_session` with a finite access token; the refresh endpoints refuse + each other's sessions before rotating; a UIA endpoint refuses an OAuth session first; revocation goes through + `end_device_session` (ADR-0791 to ADR-0795). `#OAuth 2.0 sessions (ADR-0791 to ADR-0795)` ## src/canonicaljson @@ -106,7 +109,9 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that is added to every hand-written copy, move and serialise path too. - Schema changes go only through `migrations/` (ADR-0224). Nothing but SQLite opens an SQLite file (ADR-0157). - A path that deletes a `devices` row deletes its `oauth_sessions` row in the same transaction, and no path deletes - an OAuth client that has a session (ADR-0776, ADR-0777). `src/database/AGENTS.md#OAuth 2.0 tables (migration 002, ADR-0776, ADR-0777)` + an OAuth client that has a session (ADR-0776, ADR-0777). Whatever replaces a device's credentials replaces its + `oauth_sessions` row in the same transaction; a grant's audit row is in its transaction (ADR-0792). + `src/database/AGENTS.md#OAuth 2.0 tables (migration 002, ADR-0776, ADR-0777)` ## src/email @@ -186,7 +191,9 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that and codes live only in their hashed, bounded, never-evicting stores (ADR-0782); a password is checked only by `verify_login_credentials` and a session-less account made only by `create_local_account` (ADR-0783); a page is marked `LocalHttpResponse::page` and gets no CORS header (ADR-0785); an OAuth target's query is never logged - (ADR-0786). `src/homeserver/AGENTS.md#OAuth 2.0 API (ADR-0760, ADR-0773)` + (ADR-0786). A grant is one transaction, a session ends only through `end_device_session_and_announce`, and every + UIA endpoint calls `oauth_session_uia_refusal` first (ADR-0792, ADR-0794, ADR-0795). + `src/homeserver/AGENTS.md#OAuth 2.0 API (ADR-0760, ADR-0773)` - Worker frames are untrusted. Relayed PDUs are re-verified with main's resolver **before** taking `runtime.mutex`, and the envelope is rebuilt from the verified event (ADR-0171). `#Federation worker relays are untrusted input` diff --git a/CHANGELOG.md b/CHANGELOG.md index 61176c718..fdf2defb1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -44,6 +44,14 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) form's pending identifier, at most 16 in progress per address (ADR-0787, ADR-0788). * An approval judges the account again, is audited, and its redirect sends no referrer; it creates no device, token or OAuth session (ADR-0790). +* `POST /_merovingian/oauth2/token` serves the code grant (PKCE, exact redirect URI, one transaction) and the + refresh grant, for public clients only; an OAuth access token always expires (ADR-0791, ADR-0792). +* `POST /_merovingian/oauth2/revoke` ends the session of an access or refresh token as `/logout` does, and answers + 200 for an unknown token (ADR-0795). +* A replayed authorization code ends only the session it produced; `POST /refresh` and the refresh grant each refuse + the other kind of session, before the token is spent (ADR-0792, ADR-0793). +* Endpoints that ask for User-Interactive Authentication answer an OAuth session `403 M_FORBIDDEN` naming the + account page; application services are not refused (ADR-0794). ## Security Fixes @@ -59,15 +67,17 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) and 302, 303, 409, 504 and other statuses now carry their reason phrase instead of `OK`. * `merovingian-db-migrate --plan 1 2 --migrations` now plans only the files between the two versions, instead of every file in the directory. +* `POST /keys/device_signing/upload` asks for UIA only to change held keys: a first upload or a repeat of the held + keys succeeds without it, and an application service never needs it, as the spec says (ADR-0794). ## Release notes 1.1.0 is in development. A configuration that sets any `server.oidc.*` key is now refused at start-up: remove those -keys and set `server.oauth.enabled` instead (ADR-0764). The metadata names the authorisation, token and revocation -endpoints, which later 1.1.0 changes serve (registration is served now); leave `server.oauth.enabled` off until -then. 1.1.0 migrates the database: on first start it applies migration 002, which adds two empty tables and changes -no existing one. A 1.0.x server refuses the migrated database, so back it up before upgrading if you may need to go -back. +keys and set `server.oauth.enabled` instead (ADR-0764). The authorisation, token and revocation endpoints are +served; the account page is not yet, so a user signed in through OAuth cannot change a password or delete a device +there: leave `server.oauth.enabled` off until then. 1.1.0 migrates the database: on first start it applies +migration 002, which adds two empty tables and changes no existing one. A 1.0.x server refuses the migrated +database, so back it up before upgrading if you may need to go back. # Version 1.0.2 diff --git a/docs/adr/0791-the-oauth-token-endpoint-reuses-the-login-tokens-and-an-oauth-access-token-always-expires.md b/docs/adr/0791-the-oauth-token-endpoint-reuses-the-login-tokens-and-an-oauth-access-token-always-expires.md new file mode 100644 index 000000000..5c5a84e09 --- /dev/null +++ b/docs/adr/0791-the-oauth-token-endpoint-reuses-the-login-tokens-and-an-oauth-access-token-always-expires.md @@ -0,0 +1,51 @@ +# The OAuth token endpoint reuses the login's tokens, and an OAuth access token always expires + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 6 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) (proposal P4) + +## Context and Problem Statement + +`POST /_merovingian/oauth2/token` turns an authorization code into a session. Which access and refresh tokens does it +issue, how long does the access token live, and what does the endpoint accept as a request? + +## Decision Drivers + +* The spec: "The access token MUST be short-lived" (Client-Server API, "Refresh token grant"). +* `security.access_token_lifetime_ms` may be 0, which makes a legacy access token never expire. +* Every check a password login makes on a device (account state, the device cap, a device ID that is a cross-signing + key ID) must hold for an OAuth session too. +* Every client of this server is public (`token_endpoint_auth_method` `none`, ADR-0779). + +## Considered Options + +* A separate token format and table for OAuth sessions, with their own lifetime setting. +* The existing opaque `mvs_` tokens, hashed and indexed as today, issued through the login's own checks, with the + configured lifetime, or one hour when the configuration sets none. + +## Decision Outcome + +Chosen option: the second. + +* `grant_oauth_session` (`AuthService.cpp`) runs `admit_device_login` and `mint_login_token`, the two halves + `login_local_user_by_id` now uses, so the checks and the token are the login's; only the write differs (ADR-0792). +* The access token's lifetime is `oauth::access_token_lifetime_ms(security.access_token_lifetime_ms)`: the configured + value when it is positive, otherwise `default_access_token_lifetime_ms` (one hour). `expires_in` is that lifetime in + whole seconds, at least 1. A rotation through the refresh grant uses the same rule. The legacy API keeps its + behaviour: 0 still means no expiry there. +* The token and revocation endpoints accept `application/x-www-form-urlencoded` with an optional `charset=utf-8` + parameter, quoted or not (`api_form_content_type_is_accepted`); the authorisation pages keep the exact type + (`page_form_content_type_is_accepted`), since only a browser posts to them. +* Client credentials are refused, never ignored: an `Authorization: Basic` header is 401 `invalid_client` with + `WWW-Authenticate: Basic`, and a `client_secret` field is 400 `invalid_client` (RFC 6749 section 5.2). An unknown + client is 400 `invalid_client`: no client authenticates, so a 401 would need a `WWW-Authenticate` challenge there is + no scheme for. +* The refresh grant needs the client to be registered for `refresh_token`, else `unauthorized_client`, as the code grant + needs `authorization_code`. Its `scope` parameter is ignored: the session keeps the scope it was granted. + +### Negative Consequences + +* An operator who set the lifetime to 0 for legacy clients gets one-hour OAuth access tokens and no setting to change + that. It is the spec's MUST, not a choice to expose. diff --git a/docs/adr/0792-an-oauth-grant-is-one-transaction-and-a-replayed-code-ends-only-the-session-it-produced.md b/docs/adr/0792-an-oauth-grant-is-one-transaction-and-a-replayed-code-ends-only-the-session-it-produced.md new file mode 100644 index 000000000..fbf990c35 --- /dev/null +++ b/docs/adr/0792-an-oauth-grant-is-one-transaction-and-a-replayed-code-ends-only-the-session-it-produced.md @@ -0,0 +1,50 @@ +# An OAuth grant is one transaction, and a replayed code ends only the session it produced + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 6 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +A code grant writes a device (when new), an access token, a refresh token, the deletion of the device's earlier +credentials and an `oauth_sessions` row. RFC 6749 section 4.1.2 says a code used twice SHOULD revoke the tokens issued +from it. A device can hold several grants in turn, and a password login can take an OAuth device over. What is written +together, and what does a replay end? + +## Decision Drivers + +* A failure between writes must not leave a device without its session row, or tokens without a device. +* `oauth_sessions` is keyed by (user, device) (ADR-0776): a later grant on the same device replaces the row. +* A replay may come after a second, legitimate grant on the same device. + +## Considered Options + +* Write the rows one after another, and on a replay end whatever session the device holds. +* Write them in one transaction (`database::store_oauth_grant`), and on a replay end the device's session only if its + row is the one that code wrote. + +## Decision Outcome + +Chosen option: the second. + +* `store_oauth_grant` commits the device, the deletes of the device's access, refresh and `oauth_sessions` rows, the + new access and refresh rows, the new `oauth_sessions` row and the `oauth.session.granted` audit row in one + transaction (the audit row as ADR-0629 writes it), then updates memory. A failed commit + leaves none of them and the token endpoint answers 500 `server_error`; the code stays spent. +* Each row's `created_at_ms` comes from `AuthorizationCodeStore::next_session_created_at_ms`, strictly increasing in + the process. After a grant, `record_issued_session` stores it on the redeemed code. A replay (`redeem` answers + `replayed`) ends the device's session through `end_device_session_and_announce` only when the device's row names the + code's client and that `created_at_ms`; otherwise nothing is ended. Either way the replay is `invalid_grant` and is + logged at warning level (`oauth.code.replayed`). +* A code presented with the wrong client, redirect URI or verifier is spent: it was redeemed before the comparison. A + malformed verifier is refused before the code is redeemed (`invalid_request`). +* `store_device_and_access_token` with replacement (every password login on a held device) also deletes the device's + `oauth_sessions` row in its transaction: after `POST /login` on an OAuth device, the device is a legacy session + (ADR-0793). + +### Negative Consequences + +* The replay record lives in memory with the code (60 s, ADR-0782). A replay after a restart, or after the code + expired, is an unknown code and ends nothing. diff --git a/docs/adr/0793-oauth-and-legacy-sessions-do-not-mix-at-the-refresh-endpoints.md b/docs/adr/0793-oauth-and-legacy-sessions-do-not-mix-at-the-refresh-endpoints.md new file mode 100644 index 000000000..11c58281f --- /dev/null +++ b/docs/adr/0793-oauth-and-legacy-sessions-do-not-mix-at-the-refresh-endpoints.md @@ -0,0 +1,34 @@ +# OAuth and legacy sessions do not mix at the refresh endpoints + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 6 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +Both APIs issue the same kind of refresh token. Should `POST /_merovingian/oauth2/token` with +`grant_type=refresh_token` rotate a legacy session, and should the legacy `POST /refresh` rotate an OAuth one? + +## Considered Options + +* Accept any refresh token at either endpoint. +* Accept at each endpoint only the sessions it issued, decided before anything is rotated. + +## Decision Outcome + +Chosen option: the second. + +* `refresh_local_session` takes an optional client ID. With one (the token endpoint), the token's device must hold an + `oauth_sessions` row naming that client; without one (`POST /refresh`), the device must hold none. A mismatch is + refused as an unknown token (401 inside; `invalid_grant` or `M_UNKNOWN_TOKEN` outside) before the reuse check and + before any rotation, so it changes nothing, not even the reuse bookkeeping of ADR-0590. +* The token endpoint turns every 4xx of `refresh_local_session` into 400 `invalid_grant` and a 5xx into 500 + `server_error`, so a client follows the spec's rule: 4xx means logged out, 5xx means retry. +* An OAuth rotation's access token takes the OAuth lifetime (ADR-0791). + +### Positive Consequences + +* A leaked legacy refresh token cannot be turned into an OAuth session by naming any registered client, and an OAuth + session cannot be refreshed through the legacy endpoint, which knows nothing of clients. diff --git a/docs/adr/0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md b/docs/adr/0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md new file mode 100644 index 000000000..67974b532 --- /dev/null +++ b/docs/adr/0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md @@ -0,0 +1,46 @@ +# A UIA endpoint refuses an OAuth session, and the cross-signing upload follows the spec's exemptions + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 6 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) (proposal P7) + +## Context and Problem Statement + +A session from the OAuth 2.0 API has no password the client may be asked for: the user typed it on this server's +page, never into the client. The spec has User-Interactive Authentication use the `m.oauth` stage for such a session, +which sends the user to the account management page. This server has no account management page yet. What does a UIA +endpoint answer an OAuth session? + +Separately, `POST /keys/device_signing/upload` always asked for UIA here, but since v1.11 the spec exempts an upload +when no master key is held or when every uploaded key matches the held one, and since v1.17 an application service. An +OAuth client (Element X) uploads its first keys right after signing in. + +## Considered Options + +* Offer the `m.oauth` UIA stage now. +* Answer 403 `M_FORBIDDEN` with a fixed message naming `OAuthBaseUrl::url(account_path)`, until the account page exists. +* Keep asking for `m.login.password`, which an OAuth client cannot answer. + +## Decision Outcome + +Chosen option: the second, with the spec's exemptions for the cross-signing upload. + +* `oauth_session_uia_refusal` (`ClientServerRuntime.cpp`) is asked first by every handler that asks for UIA with an + access token: `POST /login/get_token` (after its enabled check), `POST /account/password`, `POST /account/deactivate`, + `POST /account/3pid/add`, `DELETE /devices/{deviceId}` and `POST /delete_devices`. It answers for a session whose + device has an `oauth_sessions` row, before the body is read and before a UIA session is issued; never for an + application service (a masquerade token), which the spec exempts. A new UIA endpoint asks it too. +* `POST /keys/device_signing/upload` asks `cross_signing_upload_is_uia_exempt` first: an application service, a user + with no master key, or a request whose master key and every other key are byte for byte the canonical JSON held needs + no UIA, for every session. Only the remaining case, a change to held keys, asks `oauth_session_uia_refusal` and then + the password stage. +* When the account page lands, the `m.oauth` stage replaces the 403 (a superseding ADR). + +### Negative Consequences + +* An OAuth session cannot change its password, deactivate the account, add an email address, delete a device or + replace its cross-signing keys until the account page lands. The message says where it will be. +* A token holder can now upload the first cross-signing keys of an account that has none without the password, as the + spec allows. diff --git a/docs/adr/0795-oauth-revocation-ends-the-session-as-logout-does-whoever-asks.md b/docs/adr/0795-oauth-revocation-ends-the-session-as-logout-does-whoever-asks.md new file mode 100644 index 000000000..4e34b7583 --- /dev/null +++ b/docs/adr/0795-oauth-revocation-ends-the-session-as-logout-does-whoever-asks.md @@ -0,0 +1,38 @@ +# OAuth revocation ends the session as logout does, whoever asks + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 7 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) (proposal P8) + +## Context and Problem Statement + +`POST /_merovingian/oauth2/revoke` takes a token, optionally its type hint and a client ID. The spec says the server +MUST revoke both tokens of the session, SHOULD revoke even when the client ID is missing or wrong, and lists a 401 for a +client "not authorised to revoke the token". What is ended, for which tokens, and when is the answer 401? + +## Considered Options + +* Revoke only the tokens, keep the device, and only for OAuth sessions whose client matches. +* End the session exactly as `POST /logout` does, for any live access or refresh token, whatever the client ID. + +## Decision Outcome + +Chosen option: the second. + +* `revocable_session_of_token` finds the session by the token as a live access token or an unrevoked, unexpired + refresh token; `token_type_hint` is ignored whatever its value. No session: 200 with an empty body. +* `end_device_session_and_announce` is the one shared path: `end_device_session` (`AuthService.cpp`, the former tail of + `logout_local_user`) revokes every token of the device in one transaction, deletes the device and with it the + `oauth_sessions` row, and audits; then the device leaves the runtime, local users sharing a room are told, and remote + servers get `m.device_list_update` with `deleted: true`. `POST /logout`, revocation (`oauth.session.revoked`) and a + replayed code (`oauth.code.replayed`, ADR-0792) all use it. +* A legacy token is revoked the same way: the token proves possession, as for `POST /logout`. +* There is no 401 case: a client that holds the token is authorised to revoke it, and no client authenticates + (ADR-0791). Client credentials are refused as at the token endpoint. + +### Negative Consequences + +* A leaked token lets anyone end its session. That is the spec's intent ("help good actors like secret scanning + tools"), and the holder could have used the token anyway. diff --git a/docs/adr/index.md b/docs/adr/index.md index 5001cac5c..e2939dccd 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -672,3 +672,8 @@ * [0788 - The OAuth browser binding is one `__Host-` cookie, and the pending identifier is the form token](0788-the-oauth-browser-binding-is-one-host-cookie-and-the-pending-identifier-is-the-form-token.md) * [0789 - `response_mode=query` is accepted for an `https` redirect URI](0789-response-mode-query-is-accepted-for-an-https-redirect-uri.md) * [0790 - An OAuth approval is judged again and audited, and its redirect sends no referrer](0790-an-oauth-approval-is-judged-again-and-audited-and-its-redirect-sends-no-referrer.md) +* [0791 - The OAuth token endpoint reuses the login's tokens, and an OAuth access token always expires](0791-the-oauth-token-endpoint-reuses-the-login-tokens-and-an-oauth-access-token-always-expires.md) +* [0792 - An OAuth grant is one transaction, and a replayed code ends only the session it produced](0792-an-oauth-grant-is-one-transaction-and-a-replayed-code-ends-only-the-session-it-produced.md) +* [0793 - OAuth and legacy sessions do not mix at the refresh endpoints](0793-oauth-and-legacy-sessions-do-not-mix-at-the-refresh-endpoints.md) +* [0794 - A UIA endpoint refuses an OAuth session, and the cross-signing upload follows the spec's exemptions](0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md) +* [0795 - OAuth revocation ends the session as logout does, whoever asks](0795-oauth-revocation-ends-the-session-as-logout-does-whoever-asks.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 40116ad89..573bbeaaf 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -156,7 +156,7 @@ production-gated. (issue #437), had no caller and was removed. - Client-server auth/device/key actions append durable audit rows without logging plaintext credentials, bearer tokens, or key payloads. -- `GET /_matrix/client/v1/auth_metadata` (and its MSC2965 unstable path) returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. `oauth::server_metadata` builds the document and every address in it comes from `oauth::OAuthBaseUrl`: the issuer is `server.public_baseurl` with one trailing slash and the endpoints sit under `/_merovingian/oauth2/` (ADR-0773). The endpoint is unauthenticated, carries CORS headers and stays in the generic rate-limit tier (ADR-0775). The registration endpoint and the authorization endpoint are served (see "OAuth 2.0 client registration" and "OAuth 2.0 authorisation pages" below); the token and revocation endpoints it names are not served yet; they land in later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). The former `server.oidc.*` keys are refused at start-up. +- `GET /_matrix/client/v1/auth_metadata` (and its MSC2965 unstable path) returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. `oauth::server_metadata` builds the document and every address in it comes from `oauth::OAuthBaseUrl`: the issuer is `server.public_baseurl` with one trailing slash and the endpoints sit under `/_merovingian/oauth2/` (ADR-0773). The endpoint is unauthenticated, carries CORS headers and stays in the generic rate-limit tier (ADR-0775). The registration, authorization, token and revocation endpoints are served (see "OAuth 2.0 client registration", "OAuth 2.0 authorisation pages" and "OAuth 2.0 token and revocation endpoints" below); the device authorisation endpoint and the account page it names are not served yet; they land in later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). The former `server.oidc.*` keys are refused at start-up. - **Application Service API identity (Matrix v1.19, `merovingian::appservice`).** Registration files (`appservice.registration_files`, parsed as JSON) build an in-memory `AppserviceRegistry` at startup in the main process only (the federation worker @@ -1042,7 +1042,7 @@ is left out rather than taking the resident server's value. ## OAuth 2.0 building blocks (`oauth`) The built-in OAuth 2.0 API ([ADR-0760](adr/0760-the-oauth-2-0-api-is-built-into-the-homeserver.md), plan in -`todos/oauth-2-0-api.md`) is not served yet. The `oauth` module holds its pure parts, with no state, I/O or logging +`todos/oauth-2-0-api.md`) is served in part (the sections below). The `oauth` module holds its pure parts, with no state, I/O or logging ([ADR-0768](adr/0768-the-oauth-module-is-pure-and-carries-the-wire-error-beside-core-error.md)); a refusal is an `OAuthRefusal`, the wire `error` code beside a `core::Error` with fixed text. Rules: `src/oauth/AGENTS.md`. @@ -1165,6 +1165,53 @@ characters. `oauth_sessions` row; the token endpoint creates those. No browser session is kept: every authorisation asks for the password (ADR-0787). +## OAuth 2.0 token and revocation endpoints (phases 6 and 7) + +`POST /_merovingian/oauth2/token` (`handle_oauth_token`, `homeserver/OAuthTokenEndpoint.cpp`) and +`POST /_merovingian/oauth2/revoke` (`handle_oauth_revoke`, `homeserver/OAuthRevocation.cpp`) are served while +`server.oauth.enabled` is true (404 `M_UNRECOGNIZED` otherwise), before the authentication gate, in the +`auth_sensitive` rate tier. The body is `application/x-www-form-urlencoded` (a `charset=utf-8` parameter is accepted), +read with `core::FormFields`; anything else is 400 `invalid_request`. Every answer is an OAuth JSON answer with +`Cache-Control: no-store` and the usual CORS headers. Only public clients exist: `Authorization: Basic` is 401 +`invalid_client` with `WWW-Authenticate: Basic`, and a `client_secret` field 400 `invalid_client` (ADR-0791). + +- **Authorization code grant.** In order: `client_id`, `code`, `redirect_uri` and `code_verifier` present; the client + registered (`invalid_client`) for `authorization_code` (`unauthorized_client`); the verifier well formed + (`invalid_request`, the code is not spent); the code redeemed (unknown: `invalid_grant`); the client ID, the redirect + URI byte for byte and the PKCE `S256` verifier matched (`invalid_grant`, the code is spent); then + `account_sign_in_gate` and the login's device checks (`invalid_grant`). `grant_oauth_session` (`AuthService.cpp`) + shares `admit_device_login` and `mint_login_token` with `login_local_user_by_id`, and `database::store_oauth_grant` + writes the device (named after the client's `client_name` when it is new and fits the 256-byte cap), the deletion of + the device's earlier tokens and OAuth row, both new tokens, the `oauth_sessions` row and the `oauth.session.granted` + audit row (actor the user, target the client, reason the device) in ONE transaction (ADR-0792). The device then joins + the runtime's device list as after `POST /login`. The answer is 200 + `{access_token, token_type: "Bearer", expires_in, refresh_token, scope}`. +- **Access token lifetime.** Always finite: `security.access_token_lifetime_ms`, or one hour when it is 0 + (`oauth::access_token_lifetime_ms`, ADR-0791). The refresh token takes `refresh_token_lifetime_ms`. +- **A replayed code** is `invalid_grant` and ends the session that code produced, if the device's `oauth_sessions` row + is still that one (its client and its process-unique `created_at_ms`, recorded on the code); a later grant on the same + device is left alone (ADR-0792). Logged `oauth.code.replayed` at warning level and audited when a session ended. +- **Refresh token grant.** `refresh_token` and `client_id`, the client registered for `refresh_token`, then + `refresh_local_session` with the client ID: the token's device must hold an `oauth_sessions` row for that client, + checked before anything is rotated. The legacy `POST /refresh` refuses a token whose device holds a row, as an unknown + token (ADR-0793). A refusal is 400 `invalid_grant`, a storage failure 500 `server_error`. `scope` is ignored. +- **Legacy login on an OAuth device.** `POST /login` on a device that holds an `oauth_sessions` row deletes the row in + the login's own transaction: the device becomes a legacy session. +- **Revocation.** `token` is required (`invalid_request`); `token_type_hint` and `client_id` are ignored. The token is + looked up as a live access token or an unrevoked, unexpired refresh token (`revocable_session_of_token`). Not found: + 200 with an empty body. Found, OAuth or legacy: `end_device_session_and_announce` ends the session as `POST /logout` + does (every token of the device revoked, the device and its `oauth_sessions` row deleted, the deletion announced), + audited `oauth.session.revoked`, then 200 with an empty body. There is no 401 case (ADR-0795). +- **User-Interactive Authentication.** An OAuth session holds no password the client can be asked for. Every endpoint + that asks for UIA with an access token (`POST /login/get_token`, `POST /account/password`, `POST /account/deactivate`, + `POST /account/3pid/add`, `DELETE /devices/{deviceId}`, `POST /delete_devices`, and a change of held cross-signing + keys) answers it 403 `M_FORBIDDEN` naming the account page (`oauth_session_uia_refusal`); an application service is + exempt. `POST /keys/device_signing/upload` needs no UIA for any session when no master key is held or when every key + sent matches the held one, nor for an application service (spec v1.11 and v1.17; ADR-0794). +- **Logging.** Under `oauth`: `oauth.token.refused` (debug: grant type, error, client ID), `oauth.session.granted`, + `oauth.session.persistence_failed`, `oauth.refresh.refused`, `oauth.code.replayed`, `oauth.revocation.refused` and + `oauth.revocation.accepted`, with `user_id`, `device_id` and `client_id` only. Never a code, a verifier or a token. + ## Next starting points 1. Preserve the reviewed libsodium boundary for random token generation and password hashing as auth flows expand. diff --git a/docs/http-transport.md b/docs/http-transport.md index 941182791..e22ea92a2 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -977,6 +977,15 @@ cookie (ADR-0788). `Origin`, `Sec-Fetch-Site` and `Cookie` are read with `reques (`homeserver/RequestHeaders.hpp`) and a header sent twice counts as absent. A form body over `max_body_bytes` gets the general `413 M_TOO_LARGE` JSON answer, not a page. +`POST /_merovingian/oauth2/token` and `POST /_merovingian/oauth2/revoke` (ADR-0791 to ADR-0795) are routed the same +way (`static_routes`, `auth_sensitive`, a `client_static_route_allow` row of `POST`, so another method is `405`), +before the authentication gate, and are `404 M_UNRECOGNIZED` with the API off. The body must be +`application/x-www-form-urlencoded` (a `charset=utf-8` parameter is allowed) and is read with `core::FormFields`; anything +else is `400 invalid_request`. Every answer is built by `oauth_json_response`, `oauth_error_response` or +`oauth_empty_response` (`Cache-Control: no-store`) and carries the CORS headers of the single boundary. Only public +clients exist: a `client_secret` field is `400 invalid_client`, and an `Authorization: Basic` header `401 +invalid_client` with `WWW-Authenticate: Basic`. A body over `max_body_bytes` gets the general `413 M_TOO_LARGE`. + ### Admin routes `/_merovingian/admin/*` (health, metrics, audit, accounts, review, media moderation) is served on diff --git a/docs/matrix-v1.19-client-server-api.md b/docs/matrix-v1.19-client-server-api.md index 468310cea..682d8519c 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -393,7 +393,7 @@ lists have no server maximum (ADR-0332). | --- | --- | --- | --- | --- | --- | | `GET` | `/_matrix/client/v1/auth_metadata` | `getAuthMetadata` | none | - | 200, 404 | -Implemented: returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. The MSC2965 path `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answers the same. Its registration endpoint, `POST /_merovingian/oauth2/register` (spec "Client registration"), is served: unauthenticated, `201` with the client ID and the registered metadata, RFC 7591 errors (ADR-0779 to ADR-0781). Its authorization endpoint, `GET` and `POST /_merovingian/oauth2/authorize` (spec "Authorisation code grant"), is served: the sign-in, account creation and consent pages, then a redirect with `code` and `state`, or an RFC 6749 error, in the query or the fragment (ADR-0787 to ADR-0789). The other endpoints the document names are served from later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). +Implemented: returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. The MSC2965 path `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answers the same. Its registration endpoint, `POST /_merovingian/oauth2/register` (spec "Client registration"), is served: unauthenticated, `201` with the client ID and the registered metadata, RFC 7591 errors (ADR-0779 to ADR-0781). Its authorization endpoint, `GET` and `POST /_merovingian/oauth2/authorize` (spec "Authorisation code grant"), is served: the sign-in, account creation and consent pages, then a redirect with `code` and `state`, or an RFC 6749 error, in the query or the fragment (ADR-0787 to ADR-0789). Its token endpoint, `POST /_merovingian/oauth2/token` (spec "Token endpoint"), serves the `authorization_code` grant (PKCE `S256`, the redirect URI byte for byte, one transaction, a replayed code ending the session it produced) and the `refresh_token` grant (rotation as `/refresh`), for public clients only (ADR-0791 to ADR-0793). Its revocation endpoint, `POST /_merovingian/oauth2/revoke` (spec "Token revocation"), ends the session of an access or refresh token as `/logout` does and answers 200 whether or not the token was known (ADR-0795). A session from the token endpoint is refused at every endpoint that uses User-Interactive Authentication with `403 M_FORBIDDEN` naming the account page, and at `POST /refresh` (ADR-0793, ADR-0794). The account page and the device authorization grant are served from later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). | `POST` | `/_matrix/client/v1/login/get_token` | `generateLoginToken` | access token | required application/json | 200, 400, 401, 429 | | `GET` | `/_matrix/client/v3/account/whoami` | `getTokenOwner` | access token | - | 200, 401, 403, 429 | | `GET` | `/_matrix/client/v3/login` | `getLoginFlows` | none | - | 200, 404, 429 | diff --git a/docs/observability-audit.md b/docs/observability-audit.md index 67fae52f1..6b532f2c5 100644 --- a/docs/observability-audit.md +++ b/docs/observability-audit.md @@ -568,6 +568,20 @@ audit row (category `auth`, actor the user, target the client ID, reason the dev is; `oauth.authorization.denied` is audited the same way only when a user had signed in, since a denial before the password is anyone's to send. +## OAuth 2.0 token and revocation diagnostics and audit (ADR-0791 to ADR-0795) + +`POST /_merovingian/oauth2/token` logs under the `oauth` module: `oauth.token.refused` (debug, `grant_type`, `error` +and, once read, `client_id`), `oauth.session.granted` (info, `user_id`, `device_id`, `client_id`) and +`oauth.session.persistence_failed` (warning, the same fields). A replayed authorization code is logged +`oauth.code.replayed` (warning, `client_id`, `user_id`, `device_id` and `session_ended`). `POST /_merovingian/oauth2/revoke` logs +`oauth.revocation.refused` (debug, `error`) and `oauth.revocation.accepted` (info, `user_id`, `device_id` and, for an +OAuth session, `client_id`). Never a code, a code verifier, an access or refresh token, or the request body. + +Durable audit rows (category `auth`, actor the user): `oauth.session.granted` (target the client ID, reason the device +ID), written in the grant's own transaction; `oauth.session.revoked` and `oauth.code.replayed` (target the device ID, +reason `revoked`), written when the session ends, as `auth.logout` is. A refresh grant writes the `auth.refresh` rows of the legacy +refresh. + ## Outbound client request diagnostics (F-76, ADR-0418) `http::OutboundClient::perform` logs one debug line per request under the `outbound_client` module: diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index e781a0365..21cd011df 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1064,6 +1064,20 @@ quickly finding everything a given `AGENTS.md` file contributed. a duplicated header picks the copy an attacker chose (CWE-444) (ADR-0788). Source: `src/homeserver/AGENTS.md`. +- **An OAuth grant is written in one transaction, an authorization code is spent on redemption whatever follows, and a + replayed code ends the session it produced; the two refresh endpoints refuse each other's sessions before rotating.** + Why: a partial grant leaves a device or token the client was never told of; a code usable after a failed check can + be guessed at (CWE-307); a replay is the sign of a stolen code (RFC 6749 section 4.1.2); a refresh token accepted at + the wrong endpoint escapes its client binding (ADR-0792, ADR-0793). + Source: `src/homeserver/AGENTS.md`, `src/auth/AGENTS.md`, `src/database/AGENTS.md`. + +- **Every endpoint that asks for User-Interactive Authentication refuses an OAuth session with 403 before checking a + password, and revocation or a replay ends a session only through the path `POST /logout` uses.** + Why: a session the user granted to an application must not be able to change the password, deactivate the account + or delete devices with a password the application may have captured (CWE-306); a second end-of-session path forgets + a token, the device list or the remote servers (ADR-0794, ADR-0795). + Source: `src/homeserver/AGENTS.md`, `src/auth/AGENTS.md`. + ## HTTP and network boundary - **Rate limiting is applied before any auth check.** Do not move it after auth. @@ -1925,7 +1939,7 @@ For finding everything a specific file contributed, without re-reading the whole | `src/core/AGENTS.md` | Memory safety; Secrets and logging; HTTP and network boundary; Sync | | `src/crypto/AGENTS.md` | Secrets and logging; Cryptography | | `src/canonicaljson/AGENTS.md` | Cryptography | -| `src/auth/AGENTS.md` | Secrets and logging; Cryptography; Authentication and authorization; Database | +| `src/auth/AGENTS.md` | Secrets and logging; Cryptography; Authentication and authorization; OAuth 2.0 API; Database | | `src/events/AGENTS.md` | Cryptography; Authentication and authorization | | `src/rooms/AGENTS.md` | Authentication and authorization | | `src/federation/AGENTS.md` | Federation | @@ -1936,7 +1950,7 @@ For finding everything a specific file contributed, without re-reading the whole | `src/oauth/AGENTS.md` | OAuth 2.0 API | | `src/homeserver/AGENTS.md` | Authentication and authorization; OAuth 2.0 API; HTTP and network boundary; Federation; Media; Sync | | `src/media/AGENTS.md` | HTTP and network boundary; Media | -| `src/database/AGENTS.md` | Database | +| `src/database/AGENTS.md` | OAuth 2.0 API; Database | | `migrations/AGENTS.md` | Database | | `src/config/AGENTS.md` | Secrets and logging | | `src/observability/AGENTS.md` | Secrets and logging | diff --git a/docs/todos/capability-gaps.md b/docs/todos/capability-gaps.md index 50e410a29..cb2e4d046 100644 --- a/docs/todos/capability-gaps.md +++ b/docs/todos/capability-gaps.md @@ -47,7 +47,7 @@ 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. The endpoints it names are later phases of the [OAuth 2.0 API plan](oauth-2-0-api.md). | +| `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) and revocation are served (ADR-0779 to ADR-0795); the account page and the device authorization grant are later phases of the [OAuth 2.0 API plan](oauth-2-0-api.md). | | `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). | | 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. | | Room summary over federation | `runtime-wired` | `GET /v1/room_summary/{roomIdOrAlias}?via=` asks up to 3 `via` servers over federation `GET /hierarchy/{roomId}` (the `room` chunk; v1.19 defines no federation summary route) for a room this server holds no state for (ADR-0556): one ADR-0079 slot (429 at once without one, also without a token), one deadline, unverified answer, shown only by its own `join_rule` / `world_readable` / `allowed_room_ids`. Local state always wins; a malformed `via` is `400 M_INVALID_PARAM`. Not implemented: resolving an alias that lives on another server (404 / 401), and `membership` for a room not held locally. | diff --git a/docs/user-manual.md b/docs/user-manual.md index 1696e0f40..de9ed77b5 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -831,13 +831,23 @@ and its unstable form `GET /_matrix/client/unstable/org.matrix.msc2965/auth_meta answer `404 M_UNRECOGNIZED`, as the spec asks of a server without the API. With `server.oauth.enabled=true` both answer the server metadata. In 1.1.0 the API is being built in phases; this release serves the metadata, client -registration (`POST /_merovingian/oauth2/register`) and the sign-in pages +registration (`POST /_merovingian/oauth2/register`), the sign-in pages (`/_merovingian/oauth2/authorize`, where a user signs in or creates an account -and allows the application), and the other endpoints it names follow. Every -authorisation asks for the password; the server keeps no browser session. At most 10000 client registrations are held; once every held one -is in use, a new client is answered `503 temporarily_unavailable` until one is -freed. Until they do, a client that follows the metadata cannot log in, -so leave the API off. +and allows the application), the token endpoint +(`POST /_merovingian/oauth2/token`, the authorization code and refresh grants) +and revocation (`POST /_merovingian/oauth2/revoke`); the account page and the +device grant follow. Every authorisation asks for the password; the server +keeps no browser session. At most 10000 client registrations are held; once +every held one is in use, a new client is answered `503 temporarily_unavailable` +until one is freed. Until the account page lands, a user signed in through +OAuth cannot change their password, deactivate the account, add an email +address or delete a device from that session: those requests are answered +`403 M_FORBIDDEN` naming `/_merovingian/account` (ADR-0794), so leave the API +off unless users can do those things from a legacy login. + +An OAuth access token always expires: it lives +`security.access_token_lifetime_ms`, or one hour when that is `0` (ADR-0791), +and the client renews it with its refresh token. No address is configured. The issuer is `server.public_baseurl` with one trailing slash, and every endpoint is under it: `/_merovingian/oauth2/register`, @@ -850,7 +860,7 @@ pass `/_merovingian/oauth2/` and `/_merovingian/account` through, as it does | Key | Default | When to change | |---|---|---| | `server.oauth.enabled` | `false` | Set `true` to serve the OAuth 2.0 API. `server.public_baseurl` must then be an `https` URL with a host and no query, fragment or userinfo (a path is allowed), and `server.sso.authorization_url` must be empty. | -| `server.oauth.legacy_api_enabled` | `true` | Set `false` to stop the legacy login and registration API issuing new sessions to users (ADR-0761). Refused unless `server.oauth.enabled=true`, so users always have a way to log in. Checked now, acted on once the OAuth login pages land. | +| `server.oauth.legacy_api_enabled` | `true` | Set `false` to stop the legacy login and registration API issuing new sessions to users (ADR-0761). Refused unless `server.oauth.enabled=true`, so users always have a way to log in. Checked now, but not yet acted on: the OAuth login pages have landed, and the legacy API still issues sessions whatever this key says. | | `server.oauth.device_grant_enabled` | `false` | Set `true` to offer the device authorization grant (RFC 8628): the metadata then lists the device code grant type and `device_authorization_endpoint`. Refused unless `server.oauth.enabled=true`. | | `server.oauth.hand_off_redirect_allowlist` | (empty) | Comma-separated places the hand-off from the legacy SSO redirect may send the browser: `https` origins (`https://app.example.com`, `https://app.example.com:8443`, nothing after the host or port) and bare private-use schemes (`io.element.app:`), in lower case. Never a URL prefix (ADR-0774). At most 32 entries, none twice. Refused unless `server.oauth.enabled=true`. Checked now, used once the hand-off lands. | diff --git a/include/merovingian/database/OAuthStore.hpp b/include/merovingian/database/OAuthStore.hpp index 916a62dfa..32dfb5e81 100644 --- a/include/merovingian/database/OAuthStore.hpp +++ b/include/merovingian/database/OAuthStore.hpp @@ -72,8 +72,12 @@ inline constexpr auto oauth_client_touch_interval_ms = std::uint64_t{24U} * 60U // The `oauth_sessions` INSERT for a transaction that also writes the device and its tokens (phase 6): append it to // that transaction's statements, commit, and only then call `remember_oauth_session` with the same row. nullopt when // the row is refused: an empty user, device or client, a client ID or scope over its cap, a client that is not -// held, or a (user, device) that already holds a session. Reads the store; changes nothing. -[[nodiscard]] auto prepare_oauth_session_insert(PersistentStore const& store, PersistentOAuthSession const& session) +// held, or a (user, device) that already holds a session. With `replaces_device_session` a held session is not a +// refusal: the caller's transaction deletes it first (`delete_oauth_session_of_device_statement`, ahead of this +// statement) and the caller erases it from memory after the commit, before `remember_oauth_session` (ADR-0792). +// Reads the store; changes nothing. +[[nodiscard]] auto prepare_oauth_session_insert(PersistentStore const& store, PersistentOAuthSession const& session, + bool replaces_device_session = false) -> std::optional; // The memory half of `prepare_oauth_session_insert`, after its transaction committed. False when memory already // holds a session for the device, which cannot happen if nothing wrote between the prepare and the commit. diff --git a/include/merovingian/database/PersistentStore.hpp b/include/merovingian/database/PersistentStore.hpp index 532fb244b..d9c59ceb2 100644 --- a/include/merovingian/database/PersistentStore.hpp +++ b/include/merovingian/database/PersistentStore.hpp @@ -51,6 +51,7 @@ #include "merovingian/database/PersistentMediaBlob.hpp" #include "merovingian/database/PersistentMembership.hpp" #include "merovingian/database/PersistentNotification.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" #include "merovingian/database/PersistentOneTimeKey.hpp" #include "merovingian/database/PersistentOpenidToken.hpp" #include "merovingian/database/PersistentPendingMediaUpload.hpp" @@ -760,10 +761,21 @@ auto set_write_connection_limit(PersistentStore& store, std::uint32_t limit) -> // One transaction: the device row when `device` is set, the access token, and, with `replace_device_credentials`, the // DELETE of every earlier access and refresh row of the token's (user, device) first (F-08, ADR-0590: a login on a // device the user holds replaces its credentials; deleted, not revoked, because a presented revoked refresh row counts -// as reuse). Memory changes only after the commit; a failed commit changes nothing. +// as reuse). A replacement also deletes the device's `oauth_sessions` row, if it has one, in the same transaction: a +// legacy login on an OAuth device makes it a legacy device (ADR-0792). Memory changes only after the commit; a failed +// commit changes nothing. [[nodiscard]] auto store_device_and_access_token(PersistentStore& store, std::optional device, PersistentAccessToken token, bool replace_device_credentials = false) -> bool; +// An OAuth 2.0 authorization code grant's writes in ONE transaction (ADR-0792): the device row when `device` is set, +// the DELETE of every earlier access and refresh row of the device and of its `oauth_sessions` row, then the access +// row, the refresh row, the new `oauth_sessions` row `session` and the `audit` row. The three session rows must name +// the same (user, device). False, with nothing written and memory unchanged, when they do not, a token hash is held +// already, the device row is held already, the session row is refused (`prepare_oauth_session_insert`) or the commit +// fails. Memory changes only after the commit. +[[nodiscard]] auto store_oauth_grant(PersistentStore& store, std::optional device, + PersistentAccessToken access, PersistentRefreshToken refresh, + PersistentOAuthSession session, PersistentAuditEvent audit) -> bool; // A refresh rotation's writes in one transaction (F-08, ADR-0590): every earlier access row of the device is deleted, // the new access and refresh rows are inserted, and `evicted_refresh_hashes` (rows the caller found retired, from // `CredentialTable::oldest_retired_beyond`) are deleted. False, with nothing changed, if a named row is not retired. diff --git a/include/merovingian/homeserver/AuthService.hpp b/include/merovingian/homeserver/AuthService.hpp index 278de38aa..cd8cb7ff6 100644 --- a/include/merovingian/homeserver/AuthService.hpp +++ b/include/merovingian/homeserver/AuthService.hpp @@ -11,6 +11,7 @@ #include "merovingian/homeserver/DeactivationAudit.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/LocalSession.hpp" +#include "merovingian/homeserver/OAuthGrantRequest.hpp" #include "merovingian/homeserver/OpenidTokenIssueResult.hpp" #include "merovingian/homeserver/OperationResult.hpp" #include "merovingian/homeserver/PasswordLoginRequest.hpp" @@ -92,8 +93,38 @@ namespace merovingian::homeserver -> OperationResult; [[nodiscard]] auto issue_refresh_token_for_session(HomeserverRuntime& runtime, std::string_view user_id, std::string_view device_id) -> OperationResult; -[[nodiscard]] auto refresh_local_session(HomeserverRuntime& runtime, std::string_view refresh_token) +// Rotates a refresh token (ADR-0074, ADR-0590). `oauth_client_id` says which API presents it (ADR-0793): nullopt for +// the legacy POST /refresh, which refuses a token of a device that has an `oauth_sessions` row; a client ID for the +// OAuth 2.0 token endpoint, which refuses a token of a device whose row does not name that client, or that has none. +// Either refusal is a 401 "refresh token rejected" decided before anything is rotated or revoked. An OAuth rotation's +// access token always expires (oauth::access_token_lifetime_ms, ADR-0791). Every other refusal and the lost-response +// retry are unchanged; a status of 500 or more is a server failure the client may retry. +[[nodiscard]] auto refresh_local_session(HomeserverRuntime& runtime, std::string_view refresh_token, + std::optional oauth_client_id = std::nullopt) -> SessionRefreshResult; +// The OAuth 2.0 authorization code grant's session (ADR-0792): every check login_local_user_by_id makes (the account +// exists and passes the account-state gate, the device ID is valid and not a cross-signing key ID, a new device fits +// under the device count), the same access token, a refresh token, and ONE transaction that writes the device (created +// with `request.display_name`, or kept when the user holds it), deletes the device's earlier tokens and OAuth session, +// and inserts the access row, the refresh row and the `oauth_sessions` row. Memory changes only after the commit. A +// refused check keeps the status POST /login would answer (4xx); a token the server could not make or a failed commit +// is 500 with nothing written. Audits `oauth.session.granted`. The caller holds runtime.mutex. +[[nodiscard]] auto grant_oauth_session(HomeserverRuntime& runtime, OAuthGrantRequest const& request) + -> SessionRefreshResult; +// Ends the session of (`user_id`, `device_id`) as POST /logout does (P13, ADR-0491, ADR-0795): in one transaction +// `presented_access_hash` (may be empty) and every access and refresh token of the device are revoked, the store is +// checked, the in-memory sessions are marked, then the device is deleted (with its `oauth_sessions` row; a failure +// there is logged, the tokens stay revoked) and `audit_event` is audited. 500 when the revocation did not persist, +// with nothing marked, so the call can be retried. The caller holds runtime.mutex and announces the deleted device. +[[nodiscard]] auto end_device_session(HomeserverRuntime& runtime, std::string_view user_id, std::string_view device_id, + std::string_view presented_access_hash, std::string_view audit_event) + -> OperationResult; +// The session `token` authenticates, for OAuth 2.0 revocation (ADR-0795): a live access token (not revoked, not +// expired) or an unrevoked, unexpired refresh token, whichever it is, found through the digest indexes and confirmed in +// constant time. nullopt for anything else, an application service token included: none is held as a session. The +// session's `access_token_hash` is set only when `token` is an access token. +[[nodiscard]] auto revocable_session_of_token(HomeserverRuntime const& runtime, std::string_view token) + -> std::optional; // True when `user_id` is a registered, not-deactivated local account. Identity // assertion (Application Service API) must act only as such a user (AUTH-12): // asserting an unregistered or deactivated user is refused with 403 diff --git a/include/merovingian/homeserver/AuthorizationCodeRedemption.hpp b/include/merovingian/homeserver/AuthorizationCodeRedemption.hpp index 449702592..252ca35a2 100644 --- a/include/merovingian/homeserver/AuthorizationCodeRedemption.hpp +++ b/include/merovingian/homeserver/AuthorizationCodeRedemption.hpp @@ -5,6 +5,7 @@ #include "merovingian/homeserver/AuthorizationGrant.hpp" #include +#include #include namespace merovingian::homeserver @@ -17,9 +18,10 @@ struct AuthorizationCodeRedemption final { // The first redemption of a live code: `grant` holds what it stands for, and the code is now spent. fresh, - // A live code already redeemed once: `user_id` and `device_id` name the session the first redemption was for, - // so the token endpoint can revoke it ("a code presented twice revokes the session it produced"). `grant` is - // empty. + // A live code already redeemed once: `user_id`, `device_id` and `client_id` name the session the first + // redemption was for, and `session_created_at_ms` is set when that redemption issued one (recorded with + // `AuthorizationCodeStore::record_issued_session`), so the token endpoint can revoke it ("a code presented + // twice revokes the session it produced") and only it (ADR-0792). `grant` is empty. replayed, // No live code has this value: never minted, expired, or the hash failed. Nothing else is set. unknown, @@ -29,6 +31,10 @@ struct AuthorizationCodeRedemption final AuthorizationGrant grant{}; std::string user_id{}; std::string device_id{}; + std::string client_id{}; + // `replayed` only: the `created_at_ms` of the `oauth_sessions` row the first redemption wrote, or nullopt when it + // wrote none (the grant was refused or failed). + std::optional session_created_at_ms{}; }; } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/AuthorizationCodeStore.hpp b/include/merovingian/homeserver/AuthorizationCodeStore.hpp index 688fe7e14..d2a2e54ed 100644 --- a/include/merovingian/homeserver/AuthorizationCodeStore.hpp +++ b/include/merovingian/homeserver/AuthorizationCodeStore.hpp @@ -10,6 +10,7 @@ #include #include #include +#include #include #include #include @@ -56,6 +57,18 @@ class AuthorizationCodeStore final // the code's own expiry, `unknown` otherwise. [[nodiscard]] auto redeem(std::string_view code, std::uint64_t now_ms) -> AuthorizationCodeRedemption; + // The `created_at_ms` for the `oauth_sessions` row a grant from a code is about to write: `now_ms`, or one more + // than the last value this store gave if that is not less. Strictly increasing over the store's life, so the value + // recorded for a code names one row: a later grant on the same device ID, whose row replaces it, has another + // (ADR-0792). Codes live in memory only, so uniqueness within the process is all a replay needs. + [[nodiscard]] auto next_session_created_at_ms(std::uint64_t now_ms) noexcept -> std::uint64_t; + + // Records that the redemption of `code` issued the session whose row has `session_created_at_ms`, so a replay + // names it. False, recording nothing, when `code` is not held as a redeemed code at `now_ms` (it expired since, + // or was never redeemed) or already has a session recorded. + [[nodiscard]] auto record_issued_session(std::string_view code, std::uint64_t session_created_at_ms, + std::uint64_t now_ms) -> bool; + // How many live, unredeemed codes name `client_id`, after removing the expired ones. No scan. [[nodiscard]] auto unredeemed_count_for_client(std::string_view client_id, std::uint64_t now_ms) -> std::size_t; @@ -74,6 +87,8 @@ class AuthorizationCodeStore final AuthorizationGrant grant{}; std::uint64_t expires_at_ms{0U}; bool redeemed{false}; + // The session row the redemption issued, once recorded. + std::optional session_created_at_ms{}; }; template @@ -85,6 +100,8 @@ class AuthorizationCodeStore final HashedSecretTable m_codes{}; // client_id -> the expiry of each of its unredeemed codes; the last element is the latest. KeyedBy> m_unredeemed_expiries_by_client{}; + // The last value next_session_created_at_ms gave. + std::uint64_t m_last_session_created_at_ms{0U}; }; } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/ClientDeviceSessions.hpp b/include/merovingian/homeserver/ClientDeviceSessions.hpp new file mode 100644 index 000000000..bc9b08c3b --- /dev/null +++ b/include/merovingian/homeserver/ClientDeviceSessions.hpp @@ -0,0 +1,36 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/OperationResult.hpp" +#include "merovingian/homeserver/SignedInDevice.hpp" + +#include + +namespace merovingian::homeserver +{ + +struct ClientServerRuntime; + +// Module-internal (src/AGENTS.md "Where module-local helpers go"): the client-server side of a session's start and end, +// shared by POST /login, POST /logout and the OAuth 2.0 token and revocation endpoints. Both are defined in +// ClientServerRuntime.cpp, beside the device-list helpers they use. The caller holds runtime.homeserver.mutex; neither +// releases it or makes a network call (EDUs are queued). + +// After a session was granted on (`user_id`, `device_id`): a device missing from the runtime's device list is added +// with `display_name`, and for SignedInDevice::new_session the user's own device-list change is recorded, as POST +// /login does. +auto remember_signed_in_device(ClientServerRuntime& runtime, std::string_view user_id, std::string_view device_id, + std::string_view display_name, SignedInDevice kind) -> void; + +// Ends the session of (`user_id`, `device_id`) exactly as POST /logout does for that device (ADR-0795). The servers +// sharing a room with the user are read first, then end_device_session revokes the device's access and refresh tokens, +// deletes the device (its `oauth_sessions` row with it) and audits `audit_event`; on success the device leaves the +// runtime's device list, local users who share a room are told, and each remote server is sent `m.device_list_update` +// with `deleted: true` if the device row went. Used by OAuth 2.0 revocation and by the token endpoint when an +// authorization code is replayed. +[[nodiscard]] auto end_device_session_and_announce(ClientServerRuntime& runtime, std::string_view user_id, + std::string_view device_id, std::string_view audit_event) + -> OperationResult; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/OAuthClientCredentials.hpp b/include/merovingian/homeserver/OAuthClientCredentials.hpp new file mode 100644 index 000000000..a08b8e107 --- /dev/null +++ b/include/merovingian/homeserver/OAuthClientCredentials.hpp @@ -0,0 +1,27 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include + +namespace merovingian::core +{ +class FormFields; +} // namespace merovingian::core + +namespace merovingian::homeserver +{ + +struct LocalHttpRequest; + +// Module-internal: the refusal of a request to the token or revocation endpoint that carries client credentials, or +// nullopt when it carries none. Every client of this server is public (ADR-0791), so credentials are never accepted: +// an `Authorization` header with the `Basic` scheme (any case, RFC 9110 section 11.1) is 401 `invalid_client` with +// `WWW-Authenticate: Basic`, which RFC 6749 section 5.2 requires when the client tried that header; a `client_secret` +// field is 400 `invalid_client`. Logs nothing. +[[nodiscard]] auto oauth_client_credentials_refusal(LocalHttpRequest const& request, core::FormFields const& fields) + -> std::optional; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/OAuthGrantRequest.hpp b/include/merovingian/homeserver/OAuthGrantRequest.hpp new file mode 100644 index 000000000..a9769b055 --- /dev/null +++ b/include/merovingian/homeserver/OAuthGrantRequest.hpp @@ -0,0 +1,27 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::homeserver +{ + +// The session an OAuth 2.0 authorization code grant writes (grant_oauth_session, ADR-0792): what the redeemed code +// was bound to, after the token endpoint matched the client, the redirect URI and the PKCE verifier. +struct OAuthGrantRequest final +{ + std::string user_id{}; + std::string device_id{}; + std::string client_id{}; + // The granted scope, as the code holds it. + std::string scope{}; + // The display name of a device the grant creates: the client's registered name, or empty for none. + std::string display_name{}; + // The `oauth_sessions` row's `created_at_ms`, from AuthorizationCodeStore::next_session_created_at_ms, so the code + // can name the row it produced. + std::uint64_t created_at_ms{0U}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/OAuthJsonResponse.hpp b/include/merovingian/homeserver/OAuthJsonResponse.hpp index 9b98fbff0..342772ffe 100644 --- a/include/merovingian/homeserver/OAuthJsonResponse.hpp +++ b/include/merovingian/homeserver/OAuthJsonResponse.hpp @@ -7,6 +7,7 @@ #include "merovingian/oauth/OAuthRefusal.hpp" #include +#include namespace merovingian::homeserver { @@ -24,5 +25,13 @@ namespace merovingian::homeserver // The error answer of `refusal` with `status`: its `error_code` as `error` and its fixed message as // `error_description`. The message never quotes the request (oauth/AGENTS.md rule 2), so it is safe to send. [[nodiscard]] auto oauth_error_response(std::uint16_t status, oauth::OAuthRefusal const& refusal) -> LocalHttpResponse; +// The same for a refusal written at the call site: `error_code` (one of oauth/OAuthErrorCodes.hpp) and a fixed +// `description` that never quotes the request. +[[nodiscard]] auto oauth_error_response(std::uint16_t status, std::string_view error_code, std::string_view description) + -> LocalHttpResponse; + +// An answer with no body and `Cache-Control: no-store`: the 200 of a revocation request (RFC 7009 section 2.2: "The +// content of the response body is ignored by the client"; ADR-0795). No `Content-Type`, since there is no content. +[[nodiscard]] auto oauth_empty_response(std::uint16_t status) -> LocalHttpResponse; } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/OAuthRevocation.hpp b/include/merovingian/homeserver/OAuthRevocation.hpp new file mode 100644 index 000000000..5835022a1 --- /dev/null +++ b/include/merovingian/homeserver/OAuthRevocation.hpp @@ -0,0 +1,32 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +namespace merovingian::homeserver +{ + +struct ClientServerRuntime; +struct LocalHttpRequest; + +// `POST /_merovingian/oauth2/revoke` (spec "Token revocation"; RFC 7009; ADR-0795). The dispatcher has matched the +// path and the method and checked that `server.oauth.enabled` is true. +// +// The body is `application/x-www-form-urlencoded` read with core::FormFields: another type, an unreadable body or a +// missing `token` is 400 `invalid_request`. As at the token endpoint, a `client_secret` field is 400 `invalid_client` +// and `Authorization: Basic` credentials 401 `invalid_client`. `token_type_hint` is ignored, whatever its value (RFC +// 7009 section 2.1 lets the server search every kind of token); so are `client_id` and any other field. +// +// The token is looked up as an access token and as a refresh token (revocable_session_of_token). No session: 200 with +// an empty body (RFC 7009 section 2.2: an invalid token is not an error). A session, OAuth or legacy, whoever sent the +// request: it is ended as POST /logout ends it (end_device_session_and_announce: both tokens revoked, the device and +// its `oauth_sessions` row deleted, the deletion announced), audited `oauth.session.revoked`, then 200 with an empty +// body; 500 `server_error` when the revocation could not be stored. The token itself is the proof of possession, so +// there is no case for the spec's 401. +// +// Requires runtime.homeserver.mutex held; nothing here releases it. Never logs the token. +[[nodiscard]] auto handle_oauth_revoke(ClientServerRuntime& runtime, LocalHttpRequest const& request) + -> LocalHttpResponse; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/OAuthTokenEndpoint.hpp b/include/merovingian/homeserver/OAuthTokenEndpoint.hpp new file mode 100644 index 000000000..c8c766b7a --- /dev/null +++ b/include/merovingian/homeserver/OAuthTokenEndpoint.hpp @@ -0,0 +1,43 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +namespace merovingian::homeserver +{ + +struct ClientServerRuntime; +struct LocalHttpRequest; + +// `POST /_merovingian/oauth2/token` (spec "Token endpoint", "Authorisation code grant", "Refresh token grant"; +// RFC 6749 sections 4.1.3, 5 and 6; RFC 7636 section 4.6; ADR-0791 to ADR-0793). The dispatcher has matched the path +// and the method and checked that `server.oauth.enabled` is true. Every answer is built by `oauth_json_response` or +// `oauth_error_response`. +// +// The body is `application/x-www-form-urlencoded` (oauth::api_form_content_type_is_accepted) read with +// core::FormFields: another type, an unreadable body or a repeated parameter is 400 `invalid_request`. Only public +// clients exist: a `client_secret` field is 400 `invalid_client`, client credentials in an `Authorization: Basic` +// header 401 `invalid_client` with `WWW-Authenticate: Basic` (RFC 6749 sections 2.3.1 and 5.2). A missing +// `grant_type` is `invalid_request`, one other than the two below `unsupported_grant_type`. +// +// `authorization_code`, in order: `client_id`, `code`, `redirect_uri` and `code_verifier` present (`invalid_request`); +// the client registered (`invalid_client`) for the `authorization_code` grant (`unauthorized_client`); the verifier +// well formed (`invalid_request`); the code redeemed: unknown is `invalid_grant`, and a replay is `invalid_grant` that +// also ends the session the code produced, if it produced one still held (ADR-0792); then the client ID, the redirect +// URI byte for byte and the PKCE verifier must match (`invalid_grant`, the code stays spent); then +// `account_sign_in_gate` and grant_oauth_session's device checks (`invalid_grant`). A grant writes the device, both +// tokens and the `oauth_sessions` row in one transaction (500 `server_error` with nothing written on failure) and +// answers 200 `{access_token, token_type: "Bearer", expires_in, refresh_token, scope}`. +// +// `refresh_token`: `refresh_token` and `client_id` present (`invalid_request`), the client registered +// (`invalid_client`) for the `refresh_token` grant (`unauthorized_client`), then refresh_local_session with the client +// ID: a token whose device has no `oauth_sessions` row for that client is refused before anything is rotated +// (ADR-0793). A refusal is 400 `invalid_grant`, a storage failure 500 `server_error`. The `scope` parameter is ignored: +// the session keeps the scope it was granted. +// +// Requires runtime.homeserver.mutex held; nothing here releases it. Never logs a code, a verifier or a token. +[[nodiscard]] auto handle_oauth_token(ClientServerRuntime& runtime, LocalHttpRequest const& request) + -> LocalHttpResponse; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/SignedInDevice.hpp b/include/merovingian/homeserver/SignedInDevice.hpp new file mode 100644 index 000000000..b02e6859b --- /dev/null +++ b/include/merovingian/homeserver/SignedInDevice.hpp @@ -0,0 +1,20 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::homeserver +{ + +// How a device came to hold a session, for remember_signed_in_device (ClientDeviceSessions.hpp). +enum class SignedInDevice : std::uint8_t +{ + // A login or an OAuth 2.0 grant: a device new to the runtime's list also records the user's own device-list + // change, so the user's other devices and the new device's first /sync re-query the keys. + new_session, + // A refresh: only the runtime's device list is healed (after a restart), nothing is announced. + refreshed_session, +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/oauth/AccessTokenLifetime.hpp b/include/merovingian/oauth/AccessTokenLifetime.hpp new file mode 100644 index 000000000..e4fb10c80 --- /dev/null +++ b/include/merovingian/oauth/AccessTokenLifetime.hpp @@ -0,0 +1,35 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::oauth +{ + +// The lifetime of an OAuth 2.0 access token when `security.access_token_lifetime_ms` is 0, which means "no expiry" for +// a legacy token: one hour, the configuration's default. The spec says an OAuth access token MUST be short-lived, so +// it never goes without an expiry (ADR-0791). +inline constexpr auto default_access_token_lifetime_ms = std::int64_t{3'600'000}; + +// The lifetime in milliseconds of an access token issued or refreshed through the OAuth 2.0 token endpoint: +// `configured_lifetime_ms` (`security.access_token_lifetime_ms`, validated at start-up to 0 .. 30 days) when it is +// positive, otherwise default_access_token_lifetime_ms. +[[nodiscard]] constexpr auto access_token_lifetime_ms(std::int64_t configured_lifetime_ms) noexcept -> std::int64_t +{ + return configured_lifetime_ms > 0 ? configured_lifetime_ms : default_access_token_lifetime_ms; +} + +// The token response's `expires_in` (RFC 6749 section 5.1, whole seconds) for a lifetime of `lifetime_ms`: rounded +// down, so the client refreshes no later than the token expires, and at least 1 for any positive lifetime. +[[nodiscard]] constexpr auto expires_in_seconds(std::int64_t lifetime_ms) noexcept -> std::int64_t +{ + if (lifetime_ms <= 0) + { + return 0; + } + auto const seconds = lifetime_ms / 1000; + return seconds > 0 ? seconds : 1; +} + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/FormContentType.hpp b/include/merovingian/oauth/FormContentType.hpp new file mode 100644 index 000000000..94a4ff7b5 --- /dev/null +++ b/include/merovingian/oauth/FormContentType.hpp @@ -0,0 +1,21 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::oauth +{ + +// The `Content-Type` an OAuth 2.0 form body must carry: `application/x-www-form-urlencoded`, in any ASCII case (RFC +// 9110 section 8.3.1). Anything else is refused rather than guessed at: the body is read as a form and nothing else. + +// A page's form post: the type alone, with no parameter, which is what an HTML form sends. +[[nodiscard]] auto page_form_content_type_is_accepted(std::string_view content_type) noexcept -> bool; + +// A token or revocation request: the type alone, or with the one parameter `charset=utf-8` (quoted or not, any ASCII +// case, optional spaces around the `;`), which a browser's `fetch` with `URLSearchParams` sends (ADR-0791). RFC 6749 +// appendix B makes the form UTF-8 in any case, so the parameter changes nothing; any other parameter is refused. +[[nodiscard]] auto api_form_content_type_is_accepted(std::string_view content_type) noexcept -> bool; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/OAuthErrorCodes.hpp b/include/merovingian/oauth/OAuthErrorCodes.hpp index aa688c0eb..1e14c1a68 100644 --- a/include/merovingian/oauth/OAuthErrorCodes.hpp +++ b/include/merovingian/oauth/OAuthErrorCodes.hpp @@ -15,6 +15,11 @@ inline constexpr std::string_view error_invalid_grant = "invalid_grant"; inline constexpr std::string_view error_invalid_scope = "invalid_scope"; inline constexpr std::string_view error_invalid_redirect_uri = "invalid_redirect_uri"; inline constexpr std::string_view error_invalid_client_metadata = "invalid_client_metadata"; +// RFC 6749 section 5.2, from the token and revocation endpoints: client authentication failed (an unknown client, or +// a client that sent a secret this server never issues: every client is public), and a `grant_type` this server does +// not serve. +inline constexpr std::string_view error_invalid_client = "invalid_client"; +inline constexpr std::string_view error_unsupported_grant_type = "unsupported_grant_type"; // RFC 6749 section 4.1.2.1: the server cannot take the request now (the client registration cap, ADR-0780) or failed // in a way the client cannot fix. inline constexpr std::string_view error_temporarily_unavailable = "temporarily_unavailable"; diff --git a/src/auth/AGENTS.md b/src/auth/AGENTS.md index 7392e20f5..ff269fa52 100644 --- a/src/auth/AGENTS.md +++ b/src/auth/AGENTS.md @@ -79,6 +79,22 @@ its device checks, so keep it out of the verification). A password account is cr `register_password_account`, through `register_local_user` or `create_local_account` (the username checks of `/register` first). Never copy any of these steps into a route or a page: change the shared function. +## OAuth 2.0 sessions (ADR-0791 to ADR-0795) + +An OAuth 2.0 session is a legacy session (an access and a refresh row in `SessionTable`, rotated by the same +`refresh_local_session`) plus an `oauth_sessions` row naming the client. Rules: + +- `grant_oauth_session` (`src/homeserver/AuthService.cpp`) is the only path that creates one. It reuses + `admit_device_login` and `mint_login_token`, never a copy, and always gives the access token an expiry + (`oauth::access_token_lifetime_ms`: one hour when `security.access_token_lifetime_ms` is `0`). +- The refresh endpoints do not mix kinds: `POST /refresh` refuses a token of a device with an `oauth_sessions` row, and + the token endpoint's refresh grant refuses one without a row for the client that asks (ADR-0793). The check runs + before the rotation, so a refused token is never spent. +- A UIA endpoint answers an OAuth session `403 M_FORBIDDEN` before the password check (`oauth_session_uia_refusal`, + ADR-0794): the password is not the credential such a session was given. A new UIA endpoint calls it first. +- Revocation and a replayed code end the session through `end_device_session` exactly as `POST /logout` does + (ADR-0795); never revoke only the tokens. + ## Session lookup and retention `LocalDatabase::sessions` is a `homeserver::SessionTable`: `find` narrows by an index of token-hash digests and then calls diff --git a/src/database/AGENTS.md b/src/database/AGENTS.md index 4994c855e..b8fe64fd0 100644 --- a/src/database/AGENTS.md +++ b/src/database/AGENTS.md @@ -203,7 +203,11 @@ A session row is written in the caller's transaction: `prepare_oauth_session_ins commits it with the device and tokens, and only then calls `remember_oauth_session`. **Every path that deletes a `devices` row deletes its `oauth_sessions` row in the same transaction**: today that is `delete_device`, which appends `delete_oauth_session_of_device_statement` and erases the memory row after the commit. A new device-deleting path does -the same. Neither table is read by the federation worker. +the same. **Whatever replaces a device's credentials replaces its `oauth_sessions` row in the same transaction** +(ADR-0792): `store_oauth_grant` deletes the device's earlier tokens and row and inserts the new ones, and +`store_device_and_access_token` (a legacy login) deletes the row, so the device is then a legacy device. 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. ## Backend selection diff --git a/src/database/OAuthStore.cpp b/src/database/OAuthStore.cpp index 2073697fe..f6a6f4891 100644 --- a/src/database/OAuthStore.cpp +++ b/src/database/OAuthStore.cpp @@ -167,12 +167,12 @@ auto oauth_client_has_session(PersistentStore const& store, std::string_view cli return store.oauth.sessions_of_client(client_id) != 0U; } -auto prepare_oauth_session_insert(PersistentStore const& store, PersistentOAuthSession const& session) - -> std::optional +auto prepare_oauth_session_insert(PersistentStore const& store, PersistentOAuthSession const& session, + bool replaces_device_session) -> std::optional { if (session.user_id.empty() || session.device_id.empty() || !client_id_is_storable(session.client_id) || session.scope.size() > max_oauth_scope_bytes || store.oauth.find_client(session.client_id) == nullptr || - store.oauth.find_session(session.user_id, session.device_id) != nullptr) + (!replaces_device_session && store.oauth.find_session(session.user_id, session.device_id) != nullptr)) { return std::nullopt; } diff --git a/src/database/PersistentStore.cpp b/src/database/PersistentStore.cpp index 7150b4cdf..46459dd10 100644 --- a/src/database/PersistentStore.cpp +++ b/src/database/PersistentStore.cpp @@ -1997,6 +1997,88 @@ namespace return true; } +namespace +{ + + // The writes a login and an OAuth 2.0 grant share (ADR-0590, ADR-0792), as statements for the caller's one + // transaction, and their memory half after it committed. + + [[nodiscard]] auto insert_device_statement(PersistentDevice const& device) -> PreparedStatement + { + return record_statement("insert_device", "INSERT INTO devices VALUES ($1, $2, $3)", + { + {device.user_id, false}, + {device.device_id, false}, + {device.display_name, false} + }); + } + + [[nodiscard]] auto insert_access_token_statement(PersistentAccessToken const& token) -> PreparedStatement + { + return record_statement("insert_access_token", "INSERT INTO access_tokens VALUES ($1, $2, $3, $4, $5, $6)", + { + {token.user_id, false}, + {token.device_id, false}, + {token.token_hash, true }, + {token.revoked ? "true" : "false", false}, + {expires_at_text(token.expires_at), false}, + {token.predecessor_refresh_hash, true } + }); + } + + [[nodiscard]] auto insert_refresh_token_statement(PersistentRefreshToken const& token) -> PreparedStatement + { + return record_statement("insert_refresh_token", + "INSERT INTO refresh_tokens VALUES ($1, $2, $3, $4, $5, $6, $7)", + { + {token.token_hash, true}, + {token.user_id, false}, + {token.device_id, false}, + {token.revoked ? "true" : "false", false}, + {expires_at_text(token.expires_at), false}, + {token.predecessor_hash, true}, + {std::to_string(std::max(token.issued_at_ms, 0)), false} + }); + } + + // DELETE, not revoke (ADR-0590): a revoked refresh row that is presented counts as reuse and ends the device's + // session, so a stale client holding the old refresh token would end the login that replaced it. The device's + // OAuth session row goes too (ADR-0792): whatever replaces the credentials decides what kind of device it is. + auto append_device_credential_deletes(std::vector& statements, std::string_view user_id, + std::string_view device_id) -> void + { + statements.push_back(record_statement("delete_device_access_tokens", + "DELETE FROM access_tokens WHERE user_id = $1 AND device_id = $2", + { + {std::string{user_id}, false}, + {std::string{device_id}, false} + })); + statements.push_back(record_statement("delete_device_refresh_tokens", + "DELETE FROM refresh_tokens WHERE user_id = $1 AND device_id = $2", + { + {std::string{user_id}, false}, + {std::string{device_id}, false} + })); + statements.push_back(delete_oauth_session_of_device_statement(user_id, device_id)); + } + + // The memory half of append_device_credential_deletes, after the commit. + auto forget_device_credentials(PersistentStore& store, std::string_view user_id, std::string_view device_id) -> void + { + std::ignore = store.access_tokens.erase_for_device(user_id, device_id); + std::ignore = store.refresh_tokens.erase_for_device(user_id, device_id); + std::ignore = store.oauth.erase_session(user_id, device_id); + } + + auto remember_device(PersistentStore& store, PersistentDevice device) -> void + { + sync_device_index(store); + store.devices.push_back(std::move(device)); + store.device_user_index.note_appended(store.devices.size(), store.devices.back().user_id); + } + +} // namespace + [[nodiscard]] auto store_device_and_access_token(PersistentStore& store, std::optional device, PersistentAccessToken token, bool replace_device_credentials) -> bool { @@ -2011,41 +2093,13 @@ namespace { return false; } - statements.push_back( - record_statement("insert_device", "INSERT INTO devices VALUES ($1, $2, $3)", - { - {device->user_id, false}, - {device->device_id, false}, - {device->display_name, false} - })); + statements.push_back(insert_device_statement(*device)); } if (replace_device_credentials) { - // DELETE, not revoke (ADR-0590): a revoked refresh row that is presented counts as reuse and ends the - // device's session, so a stale client holding the old refresh token would end the login that replaced it. - statements.push_back(record_statement("delete_device_access_tokens", - "DELETE FROM access_tokens WHERE user_id = $1 AND device_id = $2", - { - {token.user_id, false}, - {token.device_id, false} - })); - statements.push_back(record_statement("delete_device_refresh_tokens", - "DELETE FROM refresh_tokens WHERE user_id = $1 AND device_id = $2", - { - {token.user_id, false}, - {token.device_id, false} - })); + append_device_credential_deletes(statements, token.user_id, token.device_id); } - statements.push_back(record_statement("insert_access_token", - "INSERT INTO access_tokens VALUES ($1, $2, $3, $4, $5, $6)", - { - {token.user_id, false}, - {token.device_id, false}, - {token.token_hash, true }, - {token.revoked ? "true" : "false", false}, - {expires_at_text(token.expires_at), false}, - {token.predecessor_refresh_hash, true } - })); + statements.push_back(insert_access_token_statement(token)); if (!commit_persistent_transaction(store, statements)) { return false; @@ -2053,19 +2107,66 @@ namespace // Memory changes only after the commit. if (replace_device_credentials) { - std::ignore = store.access_tokens.erase_for_device(token.user_id, token.device_id); - std::ignore = store.refresh_tokens.erase_for_device(token.user_id, token.device_id); + forget_device_credentials(store, token.user_id, token.device_id); } if (device.has_value()) { - sync_device_index(store); - store.devices.push_back(std::move(*device)); - store.device_user_index.note_appended(store.devices.size(), store.devices.back().user_id); + remember_device(store, std::move(*device)); } std::ignore = store.access_tokens.insert(std::move(token)); return true; } +[[nodiscard]] auto store_oauth_grant(PersistentStore& store, std::optional device, + PersistentAccessToken access, PersistentRefreshToken refresh, + PersistentOAuthSession session, PersistentAuditEvent audit) -> bool +{ + if (!token_is_hash(access.token_hash) || !token_is_hash(refresh.token_hash) || access.user_id != refresh.user_id || + access.device_id != refresh.device_id || session.user_id != access.user_id || + session.device_id != access.device_id || access_token_exists(store, access.token_hash) || + refresh_token_exists(store, refresh.token_hash)) + { + return false; + } + if (device.has_value() && + (device->user_id != access.user_id || device->device_id != access.device_id || device_exists(store, *device))) + { + return false; + } + auto session_insert = prepare_oauth_session_insert(store, session, true); + if (!session_insert.has_value()) + { + return false; + } + audit = stamped_audit_event(std::move(audit)); + auto statements = std::vector{}; + statements.reserve(8U); + if (device.has_value()) + { + statements.push_back(insert_device_statement(*device)); + } + append_device_credential_deletes(statements, access.user_id, access.device_id); + statements.push_back(insert_access_token_statement(access)); + statements.push_back(insert_refresh_token_statement(refresh)); + statements.push_back(std::move(*session_insert)); + statements.push_back(audit_insert_statement("oauth_grant_audit", audit)); + if (!commit_persistent_transaction(store, statements)) + { + return false; + } + // Memory changes only after the commit, in the order of the statements. + forget_device_credentials(store, access.user_id, access.device_id); + if (device.has_value()) + { + remember_device(store, std::move(*device)); + } + std::ignore = store.access_tokens.insert(std::move(access)); + std::ignore = store.refresh_tokens.insert(std::move(refresh)); + std::ignore = remember_oauth_session(store, std::move(session)); + remember_audit_event(store, std::move(audit)); + return true; +} + [[nodiscard]] auto rotate_device_credentials(PersistentStore& store, PersistentAccessToken access, PersistentRefreshToken refresh, std::span evicted_refresh_hashes) -> bool diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 73814e5c7..643b7a4de 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -28,7 +28,10 @@ This is the largest and most complex module — read this file carefully before | `ClientTxnPrune.cpp` | `prune_client_transactions`: the sweep the `client-txn-prune` `PeriodicJob` runs every hour, deleting to-device `client_txn_ids` records older than 7 days (F-54, ADR-0381) | | `RetentionSweep.cpp` | `run_retention_sweep`: the sweep the `retention-sweep` `PeriodicJob` runs every hour. Deletes sessions and tokens that can no longer authenticate and `audit_log` rows past `security.audit_log_retention_days`, and OAuth 2.0 clients with no session unused for 30 days (`oauth_client_retention`, least recently used first; never a client with a session, nor one `oauth_client_has_pending_authorisation` names: a live pending authorisation or an unredeemed code, answered in O(1) from the stores; ADR-0777, ADR-0782), in transactions of at most 500 rows (`retention_batch_rows`), at most 20 batches per kind per sweep. `runtime.mutex` is taken for one batch at a time, never across the whole sweep (ADR-0488, ADR-0489) | | `OAuthClientRegistration.cpp` | `POST /_merovingian/oauth2/register` (`register_oauth_client`), the client ID (`oauth_client_id_of`, ADR-0779), the cap and its eviction (ADR-0780), and `find_registered_oauth_client` | -| `OAuthJsonResponse.cpp` | `oauth_json_response` / `oauth_error_response`: every OAuth JSON answer, with `no-store` (ADR-0781) | +| `OAuthJsonResponse.cpp` | `oauth_json_response` / `oauth_error_response` / `oauth_empty_response`: every OAuth JSON (or empty) answer, with `no-store` (ADR-0781) | +| `OAuthTokenEndpoint.cpp` | `POST /_merovingian/oauth2/token` (`handle_oauth_token`): the authorization code grant and the refresh grant (ADR-0791 to ADR-0793) | +| `OAuthRevocation.cpp` | `POST /_merovingian/oauth2/revoke` (`handle_oauth_revoke`): ends the session of an access or refresh token as `/logout` does (ADR-0795) | +| `OAuthClientCredentials.cpp` | `oauth_client_credentials_refusal`: refuses a `client_secret` field or `Authorization: Basic` (only public clients exist) at the token and revocation endpoints | | `OAuthAuthorization.cpp` | `GET` and `POST /_merovingian/oauth2/authorize` (`handle_oauth_authorize`): the authorisation request, the browser cookie, the login, registration and consent pages, and the redirect with a code or an error (ADR-0787 to ADR-0789) | | `OAuthClock.cpp` | `oauth_wall_clock_ms`: the wall-clock milliseconds every OAuth store and handler passes | | `RequestHeaders.cpp` | `request_header` (first value, case-insensitive name) and `request_header_values` (every value, for a check that refuses a repeated header) | @@ -144,6 +147,25 @@ Rules for the authorisation pages: endpoint creates those. - Log under `oauth` with `client_id`, `application_type`, `error`, `user_id` and `device_id` only. Granted, and denied after a sign-in, are durable audit rows. +The token and revocation endpoints are `handle_oauth_token` and `handle_oauth_revoke`, answered before the authentication +gate; `ClientServerRuntime.cpp` holds only the route matches. Rules: + +- **A grant is one transaction** (`grant_oauth_session` and `database::store_oauth_grant`, ADR-0792): the device, the + deletion of the device's earlier credentials and OAuth row, both tokens, the `oauth_sessions` row and the audit row. + Then `remember_signed_in_device` adds the device to the runtime's list as `POST /login` does; never add a write after + the commit that a failure could leave behind. +- **The code grant's checks are in order**: client and grant type, verifier shape, redeem (a spent code whatever + follows), then client, redirect URI byte for byte and PKCE, then `account_sign_in_gate` and the device checks. A + replayed code ends only the session that code produced (`AuthorizationCodeStore::record_issued_session`, matched on + client and `created_at_ms`). +- **A session ends through `end_device_session_and_announce`** (`ClientDeviceSessions.hpp`), shared with `POST /logout`: + revocation, a replayed code, any new path that ends a session. +- **A UIA endpoint calls `oauth_session_uia_refusal` first** (ADR-0794): `GET`/`POST /login/get_token`, + `POST /account/password`, `/account/deactivate`, `/account/3pid/add`, `DELETE /devices/{deviceId}`, + `POST /delete_devices`, and `POST /keys/device_signing/upload` when the upload is not UIA-exempt. An application + service's masquerade token is never refused. +- Never log a code, a verifier, a token or the body; log `client_id`, `grant_type`, `error`, `user_id`, `device_id`. + `POST /_merovingian/oauth2/register` is `register_oauth_client` (`OAuthClientRegistration.cpp`), answered before the authentication gate, and also from the general body cap so an oversized body is an OAuth 400 (ADR-0781). Rules: @@ -237,6 +259,11 @@ refused whole (`room_key_batch_refusal`, 400 `M_BAD_JSON`) for a missing or non- session, and writes its sessions with `database::store_key_backup_sessions` in one transaction; a failed write is a 500, never a 200 with an etag. Do not skip a malformed entry or ignore a write result. +The upload asks for User-Interactive Authentication only when it changes a held key (spec v1.11 "Cross-signing", ADR-0794): +`cross_signing_upload_is_uia_exempt` exempts an application service, a user with no master key, and an upload whose +master key and every other key sent equal the held ones (canonical JSON). While a master key is held, an upload +without one, or with any key that differs from the held one, is UIA, and an OAuth session is refused it with 403. + ## The runtime lock and blocking calls `handle_client_server_request` and `handle_local_http_request` each take @@ -808,7 +835,8 @@ client, sender or remote server controls, and per-user rows that requests scan m - A client's device or key change goes through `record_shared_room_device_changes`: local observers only, deduplicated across rooms, one batch (ADR-0317). Never loop over a roster calling `record_device_list_change`; a federated room's roster is chosen by a remote server. -- A device removal (`DELETE /devices/{deviceId}`, `POST /delete_devices`, `POST /logout`, `POST /logout/all`) reads +- A device removal (`DELETE /devices/{deviceId}`, `POST /delete_devices`, `POST /logout`, `POST /logout/all`, OAuth + revocation and a replayed code) reads `remote_servers_for_user` before the removal, then calls `announce_deleted_devices` once with the devices that really went: one `m.device_list_update` with `deleted: true` per device and server, each on its own `allocate_sync_stream_id` position, enqueue only. A new path that deletes a device does the same. Account deactivation deletes none today. diff --git a/src/homeserver/AuthService.cpp b/src/homeserver/AuthService.cpp index 3146a10cd..614099fe9 100644 --- a/src/homeserver/AuthService.cpp +++ b/src/homeserver/AuthService.cpp @@ -9,9 +9,9 @@ #include "merovingian/auth/AccountState.hpp" #include "merovingian/auth/Argon2idAdmission.hpp" #include "merovingian/auth/FailureWindowTable.hpp" -#include "merovingian/auth/PasswordPolicy.hpp" #include "merovingian/auth/Identity.hpp" #include "merovingian/auth/Password.hpp" +#include "merovingian/auth/PasswordPolicy.hpp" #include "merovingian/auth/Session.hpp" #include "merovingian/auth/Token.hpp" #include "merovingian/config/Config.hpp" @@ -19,23 +19,25 @@ #include "merovingian/config/SsoConfig.hpp" #include "merovingian/config/SsoIdentityProvider.hpp" #include "merovingian/core/FileDescriptor.hpp" -#include "merovingian/core/SecretBuffer.hpp" #include "merovingian/core/QueryParams.hpp" -#include "merovingian/crypto/TokenHmacKey.hpp" -#include "merovingian/crypto/TokenHmacKeys.hpp" +#include "merovingian/core/SecretBuffer.hpp" #include "merovingian/crypto/ConstantTime.hpp" #include "merovingian/crypto/Random.hpp" +#include "merovingian/crypto/TokenHmacKey.hpp" +#include "merovingian/crypto/TokenHmacKeys.hpp" #include "merovingian/crypto/TokenKey.hpp" +#include "merovingian/database/OAuthStore.hpp" #include "merovingian/federation/KeySignatures.hpp" #include "merovingian/homeserver/AccountSummary.hpp" #include "merovingian/homeserver/AdminAuthResult.hpp" #include "merovingian/homeserver/DeactivationAudit.hpp" +#include "merovingian/homeserver/DeviceLimits.hpp" +#include "merovingian/homeserver/LocalServices.hpp" #include "merovingian/homeserver/OpenidTokenIssueResult.hpp" #include "merovingian/homeserver/PasswordVerificationResult.hpp" #include "merovingian/homeserver/RuntimeLockRelease.hpp" #include "merovingian/homeserver/SsoRedirectResult.hpp" -#include "merovingian/homeserver/DeviceLimits.hpp" -#include "merovingian/homeserver/LocalServices.hpp" +#include "merovingian/oauth/AccessTokenLifetime.hpp" #include "merovingian/observability/AuditCategory.hpp" #include "merovingian/observability/BoundedText.hpp" #include "merovingian/observability/LogEventSeverity.hpp" @@ -43,8 +45,8 @@ #include "merovingian/observability/SingleLog.hpp" #include "merovingian/observability/StructuredLogField.hpp" #include "merovingian/platform/FileMetadataSupport.hpp" -#include "merovingian/trust_safety/PolicySurface.hpp" #include "merovingian/trust_safety/PolicyEngine.hpp" +#include "merovingian/trust_safety/PolicySurface.hpp" #include #include @@ -65,6 +67,7 @@ #include #include #include +#include #include namespace merovingian::homeserver @@ -907,6 +910,108 @@ namespace return std::nullopt; } + // What a session grant for a verified user may go ahead with: the user, and what the one pass over the device + // table found. + struct DeviceLoginAdmission final + { + LocalUser* user{nullptr}; + UserDeviceScan devices{}; + }; + + // Every check login_local_user_by_id makes before it writes, shared with the OAuth 2.0 authorization code grant + // (grant_oauth_session, ADR-0792) so the two cannot drift: the user exists, the device ID is valid, it is not one + // of the user's cross-signing key IDs, a device the user does not hold yet fits under `device_count_limit`, and the + // account-state gate (deactivated, locked; account_state_refusal). Each refusal is logged and audited as + // login.rejected and returned as the OperationResult POST /login answers. + [[nodiscard]] auto admit_device_login(HomeserverRuntime& runtime, std::string_view user_id, + std::string_view device_id) + -> std::variant + { + auto* user = find_user(runtime.database, user_id); + if (user == nullptr) + { + log_diagnostic_audit(runtime.database, "auth", "login.rejected", + { + {"user_id", std::string{user_id}, false}, + {"device_id", std::string{device_id}, false}, + {"reason", "unknown user", false} + }, + observability::LogEventSeverity::warning, observability::AuditCategory::auth, + "login.rejected", std::string{user_id}, std::string{device_id}, "403:unknown user"); + return make_operation_result(false, {}, "invalid login", 403U); + } + if (!auth::device_id_is_valid(device_id)) + { + log_diagnostic_audit(runtime.database, "auth", "login.rejected", + { + {"user_id", std::string{user_id}, false}, + {"device_id", std::string{device_id}, false}, + {"reason", "invalid device id", false} + }, + observability::LogEventSeverity::warning, observability::AuditCategory::auth, + "login.rejected", std::string{user_id}, std::string{device_id}, "invalid device id"); + return make_operation_result(false, {}, "invalid device id"); + } + if (device_id_is_cross_signing_key_id(runtime, user_id, device_id)) + { + return make_operation_result(false, {}, "device id must not be a cross-signing key id", 403U); + } + auto const owned_devices = scan_user_devices(runtime.database.persistent_store, user->user_id, device_id); + if (device_creation_over_cap(runtime, user->user_id, device_id, owned_devices)) + { + return make_operation_result(false, {}, "too many devices", 403U); + } + // The account-state gate shared with complete_login and verify_password_login: deactivated (permanent, and + // outranking the reversible moderation states), then locked or suspended. + if (auto refusal = account_state_refusal(runtime, *user, device_id); refusal.has_value()) + { + return std::move(refusal->result); + } + return DeviceLoginAdmission{user, owned_devices}; + } + + // A fresh opaque token and its v4 hash. + struct MintedToken final + { + std::string token{}; + std::string hash{}; + }; + + // Mints the access token of a session grant for `user_id` on `device_id`, as login_local_user_by_id always has: a + // failure is logged and audited as login.rejected and returned as the OperationResult POST /login answers (400 for + // the random source, 503 for a missing token key). + [[nodiscard]] auto mint_login_token(HomeserverRuntime& runtime, std::string const& user_id, + std::string_view device_id) -> std::variant + { + auto const token = issue_token(); + if (!token.has_value()) + { + log_diagnostic_audit(runtime.database, "auth", "login.rejected", + { + {"user_id", user_id, false}, + {"device_id", std::string{device_id}, false}, + {"reason", "token generation failed", false} + }, + observability::LogEventSeverity::warning, observability::AuditCategory::auth, + "login.rejected", user_id, std::string{device_id}, "token generation failed"); + return make_operation_result(false, {}, "token generation failed"); + } + auto const token_hash = issue_token_hash(runtime, *token); + if (!token_hash.has_value()) + { + log_diagnostic_audit(runtime.database, "auth", "login.rejected", + { + {"user_id", user_id, false}, + {"device_id", std::string{device_id}, false}, + {"reason", "token hashing failed", false} + }, + observability::LogEventSeverity::warning, observability::AuditCategory::auth, + "login.rejected", user_id, std::string{device_id}, "token hashing failed"); + return make_operation_result(false, {}, "token key unavailable", 503U); + } + return MintedToken{*token, *token_hash}; + } + // Shared tail of login_local_user() and login_appservice_user(): device // validation, account-state (locked/suspended) policy, token issuance, // and session persistence. The two callers differ only in how they got @@ -1473,74 +1578,22 @@ auto login_local_user(HomeserverRuntime& runtime, std::string_view user_id, std: auto login_local_user_by_id(HomeserverRuntime& runtime, std::string_view user_id, std::string_view device_id, bool with_ttl, std::string_view display_name) -> OperationResult { - auto* user = find_user(runtime.database, user_id); - if (user == nullptr) - { - log_diagnostic_audit(runtime.database, "auth", "login.rejected", - { - {"user_id", std::string{user_id}, false}, - {"device_id", std::string{device_id}, false}, - {"reason", "unknown user", false} - }, - observability::LogEventSeverity::warning, observability::AuditCategory::auth, - "login.rejected", std::string{user_id}, std::string{device_id}, "403:unknown user"); - return make_operation_result(false, {}, "invalid login", 403U); - } - if (!auth::device_id_is_valid(device_id)) - { - log_diagnostic_audit(runtime.database, "auth", "login.rejected", - { - {"user_id", std::string{user_id}, false}, - {"device_id", std::string{device_id}, false}, - {"reason", "invalid device id", false} - }, - observability::LogEventSeverity::warning, observability::AuditCategory::auth, - "login.rejected", std::string{user_id}, std::string{device_id}, "invalid device id"); - return make_operation_result(false, {}, "invalid device id"); - } - if (device_id_is_cross_signing_key_id(runtime, user_id, device_id)) + // The checks and the token are shared with the OAuth 2.0 grant (grant_oauth_session, ADR-0792). + auto admitted = admit_device_login(runtime, user_id, device_id); + if (auto* refusal = std::get_if(&admitted); refusal != nullptr) { - return make_operation_result(false, {}, "device id must not be a cross-signing key id", 403U); - } - auto const owned_devices = scan_user_devices(runtime.database.persistent_store, user->user_id, device_id); - if (device_creation_over_cap(runtime, user->user_id, device_id, owned_devices)) - { - return make_operation_result(false, {}, "too many devices", 403U); - } - - // The account-state gate shared with complete_login and verify_password_login: deactivated (permanent, and - // outranking the reversible moderation states), then locked or suspended. - if (auto refusal = account_state_refusal(runtime, *user, device_id); refusal.has_value()) - { - return std::move(refusal->result); + return std::move(*refusal); } + auto* const user = std::get(admitted).user; + auto const owned_devices = std::get(admitted).devices; - auto const token = issue_token(); - if (!token.has_value()) - { - log_diagnostic_audit(runtime.database, "auth", "login.rejected", - { - {"user_id", user->user_id, false}, - {"device_id", std::string{device_id}, false}, - {"reason", "token generation failed", false} - }, - observability::LogEventSeverity::warning, observability::AuditCategory::auth, - "login.rejected", user->user_id, std::string{device_id}, "token generation failed"); - return make_operation_result(false, {}, "token generation failed"); - } - auto const token_hash = issue_token_hash(runtime, *token); - if (!token_hash.has_value()) + auto minted = mint_login_token(runtime, user->user_id, device_id); + if (auto* refusal = std::get_if(&minted); refusal != nullptr) { - log_diagnostic_audit(runtime.database, "auth", "login.rejected", - { - {"user_id", user->user_id, false}, - {"device_id", std::string{device_id}, false}, - {"reason", "token hashing failed", false} - }, - observability::LogEventSeverity::warning, observability::AuditCategory::auth, - "login.rejected", user->user_id, std::string{device_id}, "token hashing failed"); - return make_operation_result(false, {}, "token key unavailable", 503U); + return std::move(*refusal); } + auto const token = std::optional{std::get(minted).token}; + auto const token_hash = std::optional{std::get(minted).hash}; auto device = std::optional{}; if (!owned_devices.holds_device) { @@ -1581,6 +1634,75 @@ auto login_local_user_by_id(HomeserverRuntime& runtime, std::string_view user_id } // NOLINTEND(bugprone-easily-swappable-parameters) +auto grant_oauth_session(HomeserverRuntime& runtime, OAuthGrantRequest const& request) -> SessionRefreshResult +{ + // The same checks and the same access token as a login (login_local_user_by_id); only the write differs. + auto admitted = admit_device_login(runtime, request.user_id, request.device_id); + if (auto const* refusal = std::get_if(&admitted); refusal != nullptr) + { + return {false, refusal->status, {}, {}, request.user_id, request.device_id, refusal->reason}; + } + auto* const user = std::get(admitted).user; + auto const holds_device = std::get(admitted).devices.holds_device; + auto minted = mint_login_token(runtime, user->user_id, request.device_id); + if (auto const* refusal = std::get_if(&minted); refusal != nullptr) + { + // A token the server could not make is its own failure, never the client's. + return {false, 500U, {}, {}, request.user_id, request.device_id, refusal->reason}; + } + auto const& access = std::get(minted); + auto const refresh_token = issue_token(); + auto const refresh_hash = refresh_token.has_value() ? issue_token_hash(runtime, *refresh_token) : std::nullopt; + if (!refresh_hash.has_value()) + { + return {false, 500U, {}, {}, request.user_id, request.device_id, "refresh token generation failed"}; + } + + auto device = std::optional{}; + if (!holds_device) + { + device = database::PersistentDevice{user->user_id, request.device_id, request.display_name}; + } + // The spec's MUST: an OAuth access token is short-lived, so it always has an expiry (ADR-0791). + auto const access_expires_at = + token_expires_at(oauth::access_token_lifetime_ms(runtime.config.security().access_token_lifetime_ms)); + auto const refresh_expires_at = token_expires_at(runtime.config.security().refresh_token_lifetime_ms); + // ONE transaction (ADR-0792): the device, the deletion of its earlier credentials and OAuth session (a device the + // user holds has its earlier tokens invalidated, as a login on it does, ADR-0590), the access and refresh rows and + // the oauth_sessions row and the durable audit row (as auth.login is for a password login: actor the user, target + // the client, reason the device). A failed commit leaves none of them. + if (!database::store_oauth_grant( + runtime.database.persistent_store, std::move(device), + {user->user_id, request.device_id, access.hash, false, access_expires_at}, + {user->user_id, request.device_id, *refresh_hash, false, refresh_expires_at, {}, wall_clock_ms()}, + {user->user_id, request.device_id, request.client_id, request.scope, request.created_at_ms}, + local_audit_row(observability::AuditCategory::auth, "oauth.session.granted", user->user_id, + request.client_id, request.device_id))) + { + observability::log_diagnostic("oauth", "oauth.session.persistence_failed", + { + {"user_id", user->user_id, false}, + {"device_id", request.device_id, false}, + {"client_id", request.client_id, false} + }, + observability::LogEventSeverity::warning); + return {false, 500U, {}, {}, request.user_id, request.device_id, "session persistence failed"}; + } + ++runtime.database.next_session_id; + std::ignore = runtime.database.sessions.erase_device(user->user_id, request.device_id); + runtime.database.sessions.push_back({user->user_id, request.device_id, access.hash, false, access_expires_at}); + remember_local_audit(runtime.database, observability::AuditCategory::auth, "oauth.session.granted", user->user_id, + request.client_id, request.device_id); + observability::log_diagnostic("oauth", "oauth.session.granted", + { + {"user_id", user->user_id, false}, + {"device_id", request.device_id, false}, + {"client_id", request.client_id, false} + }, + observability::LogEventSeverity::info); + return {true, 200U, access.token, *refresh_token, user->user_id, request.device_id, {}}; +} + // Application Service API (Matrix v1.19) §"Server admin style permissions": // logs in as `user_id` WITHOUT a password check, for a `POST /login` call // authenticated with an appservice's `as_token` and @@ -1648,7 +1770,28 @@ auto issue_refresh_token_for_session(HomeserverRuntime& runtime, std::string_vie return make_operation_result(true, *refresh_token); } -auto refresh_local_session(HomeserverRuntime& runtime, std::string_view refresh_token) -> SessionRefreshResult +namespace +{ + + // Whether the API presenting a refresh token of (`user_id`, `device_id`) may use it (ADR-0793): the legacy + // POST /refresh (`oauth_client_id` nullopt) only for a device with no `oauth_sessions` row, the OAuth 2.0 token + // endpoint only for a device whose row names the presented client. The two APIs never mix. + [[nodiscard]] auto refresh_api_matches_device(HomeserverRuntime const& runtime, std::string_view user_id, + std::string_view device_id, + std::optional oauth_client_id) -> bool + { + auto const* session = database::find_oauth_session(runtime.database.persistent_store, user_id, device_id); + if (!oauth_client_id.has_value()) + { + return session == nullptr; + } + return session != nullptr && session->client_id == *oauth_client_id; + } + +} // namespace + +auto refresh_local_session(HomeserverRuntime& runtime, std::string_view refresh_token, + std::optional oauth_client_id) -> SessionRefreshResult { if (token_hmac_key_v4(runtime) == nullptr) { @@ -1679,6 +1822,24 @@ auto refresh_local_session(HomeserverRuntime& runtime, std::string_view refresh_ auto const presented_hash = refresh->token_hash; auto const predecessor_hash = refresh->predecessor_hash; + // ADR-0793: before anything is rotated or revoked, the token must belong to a device of the presenting API. A + // legacy refresh token at the OAuth token endpoint, an OAuth one at POST /refresh, or another client's, is + // answered as an unknown token and changes nothing: not even a retired token's reuse detection runs for it. + if (!refresh_api_matches_device(runtime, user_id, device_id, oauth_client_id)) + { + if (oauth_client_id.has_value()) + { + observability::log_diagnostic("oauth", "oauth.refresh.refused", + { + {"user_id", user_id, false}, + {"client_id", std::string{*oauth_client_id}, false}, + {"reason", "not a session of the client", false} + }, + observability::LogEventSeverity::warning); + } + return {false, 401U, {}, {}, {}, {}, "refresh token rejected"}; + } + // ADR-0074 (Matrix v1.19 CS API, refresh tokens): "The homeserver SHOULD // consider that the session is compromised if an old, invalidated refresh // token is used, and SHOULD revoke the session." A refresh token is @@ -1798,7 +1959,11 @@ auto refresh_local_session(HomeserverRuntime& runtime, std::string_view refresh_ auto const evicted_refresh_hashes = runtime.database.persistent_store.refresh_tokens.oldest_retired_beyond( user_id, device_id, max_retired_refresh_tokens_per_device); - auto const new_access_expires_at = token_expires_at(runtime.config.security().access_token_lifetime_ms); + // An OAuth access token always expires (ADR-0791); a legacy one keeps the configured lifetime, 0 meaning none. + auto const configured_access_lifetime_ms = runtime.config.security().access_token_lifetime_ms; + auto const new_access_expires_at = + token_expires_at(oauth_client_id.has_value() ? oauth::access_token_lifetime_ms(configured_access_lifetime_ms) + : configured_access_lifetime_ms); auto const new_refresh_expires_at = token_expires_at(runtime.config.security().refresh_token_lifetime_ms); if (!database::rotate_device_credentials( runtime.database.persistent_store, @@ -2088,7 +2253,15 @@ auto logout_local_user(HomeserverRuntime& runtime, std::string_view access_token { return make_operation_result(false, {}, "unauthenticated"); } + // Shared with OAuth 2.0 revocation, which ends a session exactly as logout does (ADR-0795). + return end_device_session(runtime, user_id, device_id, persisted_hash, "auth.logout"); +} +auto end_device_session(HomeserverRuntime& runtime, std::string_view user_id_view, std::string_view device_id_view, + std::string_view persisted_hash, std::string_view audit_event) -> OperationResult +{ + auto const user_id = std::string{user_id_view}; + auto const device_id = std::string{device_id_view}; // P13 (ADR-0491): the presented token, the device's refresh tokens and the device's access tokens are // revoked in one transaction; the checks below confirm the store agrees before anything is marked. std::ignore = @@ -2118,10 +2291,10 @@ auto logout_local_user(HomeserverRuntime& runtime, std::string_view access_token { return make_operation_result(false, {}, "token revocation persistence failed", 500U); } + // The presented token is one of the device's, so marking the device's sessions marks it too. for (auto& session : runtime.database.sessions) { - if (matches_any_token_hash(session.access_token_hash, token_hashes) || - (session.user_id == user_id && session.device_id == device_id)) + if (session.user_id == user_id && session.device_id == device_id) { session.revoked = true; } @@ -2138,7 +2311,7 @@ auto logout_local_user(HomeserverRuntime& runtime, std::string_view access_token }, observability::LogEventSeverity::warning); } - append_local_audit(runtime.database, observability::AuditCategory::auth, "auth.logout", user_id, device_id, + append_local_audit(runtime.database, observability::AuditCategory::auth, audit_event, user_id, device_id, "revoked"); log_diagnostic("logout.accepted", { @@ -2149,6 +2322,30 @@ auto logout_local_user(HomeserverRuntime& runtime, std::string_view access_token return make_operation_result(true, user_id); } +auto revocable_session_of_token(HomeserverRuntime const& runtime, std::string_view token) -> std::optional +{ + // Hashed the same way whatever the token turns out to be, and looked up as both kinds, so the work does not depend + // on which kind it is or whether it is held. lookup_token_hashes refuses an empty token. + auto const token_hashes = lookup_token_hashes(runtime, token); + if (token_hashes.empty()) + { + return std::nullopt; + } + auto const now = std::chrono::system_clock::now(); + auto const* session = find_session(runtime.database, token_hashes, now); + auto const* refresh = runtime.database.persistent_store.refresh_tokens.find(token_hashes); + if (session != nullptr) + { + return *session; + } + if (refresh != nullptr && matches_any_token_hash(refresh->token_hash, token_hashes) && !refresh->revoked && + !is_expired(refresh->expires_at, now)) + { + return LocalSession{refresh->user_id, refresh->device_id, {}, false, std::nullopt}; + } + return std::nullopt; +} + auto logout_all_local_user(HomeserverRuntime& runtime, std::string_view access_token) -> OperationResult { auto const session = authenticated_session(runtime, access_token); diff --git a/src/homeserver/AuthorizationCodeStore.cpp b/src/homeserver/AuthorizationCodeStore.cpp index dd4395eca..28238cb55 100644 --- a/src/homeserver/AuthorizationCodeStore.cpp +++ b/src/homeserver/AuthorizationCodeStore.cpp @@ -66,11 +66,41 @@ auto AuthorizationCodeStore::redeem(std::string_view code, std::uint64_t now_ms) } if (entry->redeemed) { - return {AuthorizationCodeRedemption::Outcome::replayed, {}, entry->grant.user_id, entry->grant.device_id}; + return {AuthorizationCodeRedemption::Outcome::replayed, + {}, + entry->grant.user_id, + entry->grant.device_id, + entry->grant.client_id, + entry->session_created_at_ms}; } forget_unredeemed(*entry); entry->redeemed = true; - return {AuthorizationCodeRedemption::Outcome::fresh, entry->grant, entry->grant.user_id, entry->grant.device_id}; + return {AuthorizationCodeRedemption::Outcome::fresh, + entry->grant, + entry->grant.user_id, + entry->grant.device_id, + entry->grant.client_id, + std::nullopt}; +} + +auto AuthorizationCodeStore::next_session_created_at_ms(std::uint64_t now_ms) noexcept -> std::uint64_t +{ + m_last_session_created_at_ms = now_ms > m_last_session_created_at_ms ? now_ms : m_last_session_created_at_ms + 1U; + return m_last_session_created_at_ms; +} + +auto AuthorizationCodeStore::record_issued_session(std::string_view code, std::uint64_t session_created_at_ms, + std::uint64_t now_ms) -> bool +{ + erase_expired(now_ms); + auto const code_hash = oauth_secret_hash(code); + auto* entry = code_hash.has_value() ? m_codes.find(*code_hash) : nullptr; + if (entry == nullptr || !entry->redeemed || entry->session_created_at_ms.has_value()) + { + return false; + } + entry->session_created_at_ms = session_created_at_ms; + return true; } auto AuthorizationCodeStore::unredeemed_count_for_client(std::string_view client_id, std::uint64_t now_ms) diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index 03d526ea1..a87b628ed 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -43,6 +43,7 @@ #include "merovingian/crypto/GenericHash.hpp" #include "merovingian/crypto/Random.hpp" #include "merovingian/database/ExaminedRows.hpp" +#include "merovingian/database/OAuthStore.hpp" #include "merovingian/database/PersistentAccountData.hpp" #include "merovingian/database/PersistentAuditEvent.hpp" #include "merovingian/database/PersistentCrossSigningKey.hpp" @@ -80,6 +81,7 @@ #include "merovingian/homeserver/AuthService.hpp" #include "merovingian/homeserver/ClientApiLimits.hpp" #include "merovingian/homeserver/ClientDevice.hpp" +#include "merovingian/homeserver/ClientDeviceSessions.hpp" #include "merovingian/homeserver/ClientOutboundProxy.hpp" #include "merovingian/homeserver/ClientServerClock.hpp" #include "merovingian/homeserver/ClientServerStartOptions.hpp" @@ -100,6 +102,8 @@ #include "merovingian/homeserver/MutualRoomsToken.hpp" #include "merovingian/homeserver/OAuthAuthorization.hpp" #include "merovingian/homeserver/OAuthClientRegistration.hpp" +#include "merovingian/homeserver/OAuthRevocation.hpp" +#include "merovingian/homeserver/OAuthTokenEndpoint.hpp" #include "merovingian/homeserver/OperationResult.hpp" #include "merovingian/homeserver/OperatorAdmin.hpp" #include "merovingian/homeserver/OutboundDeadline.hpp" @@ -4034,6 +4038,8 @@ namespace "/_matrix/client/unstable/org.matrix.msc2965/auth_metadata", "/_merovingian/oauth2/register", "/_merovingian/oauth2/authorize", + "/_merovingian/oauth2/token", + "/_merovingian/oauth2/revoke", "/_matrix/client/v3/account/3pid/email/requestToken", "/_matrix/client/v3/account/3pid/msisdn/requestToken", "/_matrix/client/v3/account/password/email/requestToken", @@ -4132,6 +4138,8 @@ namespace {"/_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" }, {"/_matrix/client/v3/account/3pid/email/requestToken", "POST" }, {"/_matrix/client/v3/account/3pid/msisdn/requestToken", "POST" }, {"/_matrix/client/v3/account/password/email/requestToken", "POST" }, @@ -4493,6 +4501,35 @@ namespace // runtime.mutex; the Argon2id check inside verify_local_user_password releases it itself. UIA with the account // password is required on EVERY call: the spec says servers "MUST always re-prompt", and a UIA session id // carries no authority here, so nothing from an earlier call is honoured. + // P7 (ADR-0794): a session that signed in through the OAuth 2.0 API holds no password the server could ask for in + // User-Interactive Authentication, and this server does not offer the `m.oauth` stage. Every endpoint that would + // ask for UIA answers such a session 403 M_FORBIDDEN instead, naming the account page, before it reads the body + // or issues a UIA session. nullopt for every other caller: a legacy session, and an application service (a + // masquerade token), which the spec exempts from UIA and which holds no session here. + [[nodiscard]] auto oauth_session_uia_refusal(ClientServerRuntime const& rt, std::string_view access_token) + -> std::optional + { + if (appservice::decode_masquerade_token(access_token).has_value()) + { + return std::nullopt; + } + auto const session = authenticated_session(rt.homeserver, access_token); + if (!session.has_value() || database::find_oauth_session(rt.homeserver.database.persistent_store, + session->user_id, session->device_id) == nullptr) + { + return std::nullopt; + } + auto message = std::string{"This session signed in through OAuth 2.0 and cannot confirm this request here. " + "Manage the account at the server's account page"}; + auto const base = oauth::OAuthBaseUrl::read(rt.homeserver.config.server().public_baseurl); + if (auto const* const url = std::get_if(&base); url != nullptr) + { + message += ": " + url->url(oauth::account_path); + } + message += '.'; + return message; + } + [[nodiscard]] auto handle_get_login_token(ClientServerRuntime& rt, LocalHttpRequest const& req, std::string_view user_id) -> DispatchResult { @@ -4500,6 +4537,10 @@ namespace { return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); } + if (auto const refusal = oauth_session_uia_refusal(rt, req.access_token); refusal.has_value()) + { + return dispatch_err(req, rt, 403U, "M_FORBIDDEN", *refusal); + } auto const challenge = [&](bool password_failed) -> DispatchResult { auto const session = issue_uia_session(rt, "login_get_token", user_id); if (!session.has_value()) @@ -4729,6 +4770,20 @@ namespace rt.devices.erase(first, last); } + // What follows a session that ended with its device (POST /logout, OAuth 2.0 revocation and code replay, + // ADR-0795): the runtime's device list loses it, the users who share a room are told, and the servers in + // `destinations` (remote_servers_for_user, read before the removal) are told of the device only if its row went. + auto announce_ended_device_session(ClientServerRuntime& rt, std::string_view user_id, std::string_view device_id, + std::vector const& destinations) -> void + { + erase_runtime_device(rt, user_id, device_id); + std::ignore = record_shared_room_device_changes(rt, user_id, NotifyOwnDevices::no); + announce_deleted_devices( + rt, user_id, + devices_removed_since(rt.homeserver.database.persistent_store, user_id, {std::string{device_id}}), + destinations); + } + [[nodiscard]] auto joined(LocalRoom const& room, std::string_view user) -> bool { return room.members.contains(user); @@ -13282,50 +13337,118 @@ namespace return resp(200U, found->json); } - // POST /_matrix/client/v3/keys/device_signing/upload: password-authenticated upload of the cross-signing keys. - [[nodiscard]] auto handle_upload_cross_signing_keys(ClientServerRuntime& rt, auth::KeyApiRoute const& route, - std::string_view user, std::string_view device_id, - LocalHttpRequest const& req) -> LocalHttpResponse + // Whether POST /keys/device_signing/upload may skip User-Interactive Authentication (spec v1.19, "Changed in + // v1.11" and "v1.17"; ADR-0794): the caller is an application service, or the user holds no master key, or the + // request carries the master key and every key it carries is byte for byte the canonical JSON already held under + // that slot, so it changes nothing. A request without a master key, once one is held, needs UIA. + [[nodiscard]] auto cross_signing_upload_is_uia_exempt(ClientServerRuntime const& rt, std::string_view user, + canonicaljson::Object const& body, + LocalHttpRequest const& req) -> bool { - // Spec §11.12.1: MUST require UIA (m.login.password) to prevent key takeover. - auto const cs_uia = json_obj({ - json_member("flows", - json_arr({json_obj({json_member("stages", json_arr({json_str("m.login.password")}))})})), - json_member("params", json_obj({})), - json_member("session", json_str("cross_signing_upload")), - }); - auto const cs_body = parsed_json_object(req.body); - auto const* cs_auth = cs_body.has_value() ? object_member_object(*cs_body, "auth") : nullptr; - if (cs_auth == nullptr) + if (appservice::decode_masquerade_token(req.access_token).has_value()) { - return resp(401U, json_serialize(cs_uia)); + return true; } - auto const* cs_auth_type = string_member(*cs_auth, "type"); - if (cs_auth_type == nullptr || *cs_auth_type != "m.login.password") + constexpr auto slots = std::array, 3U>{ + { + {"master_key", "master"}, + {"self_signing_key", "self_signing"}, + {"user_signing_key", "user_signing"}, + } + }; + auto held = std::array, slots.size()>{}; + database::for_each_user_cross_signing_key(rt.homeserver.database.persistent_store, user, + [&](database::PersistentCrossSigningKey const& row) { + for (std::size_t index = 0U; index < slots.size(); ++index) + { + if (row.key_type == slots.at(index).second) + { + held.at(index) = row.json; + } + } + return true; + }); + if (!held.front().has_value()) { - return resp(401U, json_serialize(cs_uia)); + return true; } - auto const* cs_password = string_member(*cs_auth, "password"); - if (cs_password == nullptr || cs_password->empty()) + if (object_member(body, slots.front().first) == nullptr) { - return resp(401U, json_serialize(cs_uia)); + return false; } - auto const password_verified = verify_local_user_password(rt.homeserver, req.access_token, *cs_password); - if (!password_verified.ok) + for (std::size_t index = 0U; index < slots.size(); ++index) { - if (password_verified.retry_after_ms > 0U) + auto const* const value = object_member(body, slots.at(index).first); + if (value == nullptr) { - auto const retry_after = static_cast(std::min( - password_verified.retry_after_ms, std::numeric_limits::max())); - auto response = - LocalHttpResponse{429U, - matrix_error("M_LIMIT_EXCEEDED", - "Too many password attempts. Please try again later.", retry_after), - {{"Retry-After", std::to_string((retry_after + 999U) / 1000U)}}}; - apply_cors_headers(req, response, rt.cors); - return response; + continue; + } + auto const serialized = canonicaljson::serialize_canonical(*value); + if (serialized.error != canonicaljson::CanonicalJsonError::none || !held.at(index).has_value() || + *held.at(index) != serialized.output) + { + return false; + } + } + return true; + } + + // POST /_matrix/client/v3/keys/device_signing/upload: upload of the cross-signing keys, password-authenticated + // unless cross_signing_upload_is_uia_exempt. + [[nodiscard]] auto handle_upload_cross_signing_keys(ClientServerRuntime& rt, auth::KeyApiRoute const& route, + std::string_view user, std::string_view device_id, + LocalHttpRequest const& req) -> LocalHttpResponse + { + // Spec v1.19 POST /keys/device_signing/upload: UIA "MUST be performed for regular clients, except" when no + // master key is held, or when every key the request carries matches the one held; never for an application + // service (ADR-0794). + auto const cs_body = parsed_json_object(req.body); + auto const uia_exempt = cs_body.has_value() && cross_signing_upload_is_uia_exempt(rt, user, *cs_body, req); + if (!uia_exempt) + { + if (auto const refusal = oauth_session_uia_refusal(rt, req.access_token); refusal.has_value()) + { + return err(403U, "M_FORBIDDEN", *refusal); + } + // Spec §11.12.1: MUST require UIA (m.login.password) to prevent key takeover. + auto const cs_uia = json_obj({ + json_member("flows", + json_arr({json_obj({json_member("stages", json_arr({json_str("m.login.password")}))})})), + json_member("params", json_obj({})), + json_member("session", json_str("cross_signing_upload")), + }); + auto const* cs_auth = cs_body.has_value() ? object_member_object(*cs_body, "auth") : nullptr; + if (cs_auth == nullptr) + { + return resp(401U, json_serialize(cs_uia)); + } + auto const* cs_auth_type = string_member(*cs_auth, "type"); + if (cs_auth_type == nullptr || *cs_auth_type != "m.login.password") + { + return resp(401U, json_serialize(cs_uia)); + } + auto const* cs_password = string_member(*cs_auth, "password"); + if (cs_password == nullptr || cs_password->empty()) + { + return resp(401U, json_serialize(cs_uia)); + } + auto const password_verified = verify_local_user_password(rt.homeserver, req.access_token, *cs_password); + if (!password_verified.ok) + { + if (password_verified.retry_after_ms > 0U) + { + auto const retry_after = static_cast(std::min( + password_verified.retry_after_ms, std::numeric_limits::max())); + auto response = LocalHttpResponse{ + 429U, + matrix_error("M_LIMIT_EXCEEDED", "Too many password attempts. Please try again later.", + retry_after), + {{"Retry-After", std::to_string((retry_after + 999U) / 1000U)}}}; + apply_cors_headers(req, response, rt.cors); + return response; + } + return resp(401U, uia_password_failure_body(json_serialize(cs_uia))); } - return resp(401U, uia_password_failure_body(json_serialize(cs_uia))); } for (auto const* key_type : {"master_key", "self_signing_key", "user_signing_key"}) { @@ -14056,6 +14179,50 @@ namespace } // namespace +auto remember_signed_in_device(ClientServerRuntime& runtime, std::string_view user_id, std::string_view device_id, + std::string_view display_name, SignedInDevice kind) -> void +{ + if (find_device(runtime, user_id, device_id) != nullptr) + { + return; + } + runtime.devices.push_back({std::string{user_id}, std::string{device_id}, std::string{display_name}}); + if (kind == SignedInDevice::refreshed_session) + { + return; + } + // A new login creates a new device identity. Record a self + // device-list-change so the user's other devices see the user in + // device_lists.changed and re-query /keys/query, AND so this new + // device's own first /sync lists the user in device_lists.changed + // — prompting it to fetch the user's *existing* devices' keys + // before any m.key.verification.request can arrive. Without this, + // a new device (e.g. Element X) receives a verification request + // from an existing verified device but has not yet fetched the + // sender's device keys, so matrix-rust-sdk drops the request + // ("Could not retrieve the device data ... ignoring it"). Key + // upload alone records a self-DLC, but the new device's initial + // sync runs before its own key upload. The spec sanctions the HS + // adding a user to device_lists.changed when a device's cached + // list may be stale; a brand-new device's cache is empty. + auto const self_change = + database::PersistentDeviceListChange{0U, std::string{user_id}, std::string{user_id}, "changed"}; + std::ignore = record_device_list_change(runtime, self_change); +} + +auto end_device_session_and_announce(ClientServerRuntime& runtime, std::string_view user_id, std::string_view device_id, + std::string_view audit_event) -> OperationResult +{ + // Read before the removal, as POST /logout does: afterwards the device is gone from the lists it is read from. + auto const destinations = remote_servers_for_user(runtime.homeserver, user_id); + auto result = end_device_session(runtime.homeserver, user_id, device_id, {}, audit_event); + if (result.ok) + { + announce_ended_device_session(runtime, user_id, device_id, destinations); + } + return result; +} + // Translate the operator-facing `config::ClientRateLimitsConfig` into the // engine's `http::RateLimitConfig`. Start from the design-doc defaults so // every client-server route has a sensible cap even when the operator leaves @@ -15842,27 +16009,7 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } return dispatch_err(req, rt, result.status, "M_FORBIDDEN", result.reason); } - if (find_device(rt, body->user_id, body->device_id) == nullptr) - { - rt.devices.push_back({body->user_id, body->device_id, body->display_name}); - // A new login creates a new device identity. Record a self - // device-list-change so the user's other devices see the user in - // device_lists.changed and re-query /keys/query, AND so this new - // device's own first /sync lists the user in device_lists.changed - // — prompting it to fetch the user's *existing* devices' keys - // before any m.key.verification.request can arrive. Without this, - // a new device (e.g. Element X) receives a verification request - // from an existing verified device but has not yet fetched the - // sender's device keys, so matrix-rust-sdk drops the request - // ("Could not retrieve the device data ... ignoring it"). Key - // upload alone records a self-DLC, but the new device's initial - // sync runs before its own key upload. The spec sanctions the HS - // adding a user to device_lists.changed when a device's cached - // list may be stale; a brand-new device's cache is empty. - auto const self_change = database::PersistentDeviceListChange{0U, std::string{body->user_id}, - std::string{body->user_id}, "changed"}; - std::ignore = record_device_list_change(rt, self_change); - } + remember_signed_in_device(rt, body->user_id, body->device_id, body->display_name, SignedInDevice::new_session); auto response_body = canonicaljson::Object{ json_member("access_token", json_str(result.value)), json_member("user_id", json_str(body->user_id)), @@ -15938,14 +16085,8 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp auto const r = call_local(req); if (r.status == 200U && logged_out_session.has_value()) { - erase_runtime_device(rt, logged_out_session->user_id, logged_out_session->device_id); - std::ignore = record_shared_room_device_changes(rt, logged_out_session->user_id, NotifyOwnDevices::no); // logout deletes the device, but only announce it if the row really went. - announce_deleted_devices(rt, logged_out_session->user_id, - devices_removed_since(rt.homeserver.database.persistent_store, - logged_out_session->user_id, - {logged_out_session->device_id}), - destinations); + announce_ended_device_session(rt, logged_out_session->user_id, logged_out_session->device_id, destinations); } // actor is not yet resolved here (pre-auth gate); log token presence only log_diagnostic(r.status == 200U ? "account.logout.accepted" : "account.logout.rejected", @@ -16016,6 +16157,32 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return DispatchResult{DispatchResult::Status::complete, handle_oauth_authorize(rt, req), {}}; } } + // POST /_merovingian/oauth2/token (spec "Token endpoint") and POST /_merovingian/oauth2/revoke (spec "Token + // revocation"): a client presents a code, a refresh token or the token to revoke, never an access token, so both + // are answered before the access-token gate, 404 with the OAuth 2.0 API off. Another method falls through to the + // 405 gate. The handlers are OAuthTokenEndpoint.cpp (ADR-0791 to ADR-0793) and OAuthRevocation.cpp (ADR-0795). + if (request_path == oauth::token_path.view()) + { + if (!rt.homeserver.config.server().oauth.enabled) + { + return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); + } + if (req.method == "POST") + { + return DispatchResult{DispatchResult::Status::complete, handle_oauth_token(rt, req), {}}; + } + } + if (request_path == oauth::revoke_path.view()) + { + if (!rt.homeserver.config.server().oauth.enabled) + { + return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); + } + if (req.method == "POST") + { + return DispatchResult{DispatchResult::Status::complete, handle_oauth_revoke(rt, req), {}}; + } + } // The rest of the MSC2965 namespace (`auth_issuer`, from an earlier draft of the MSC) is not served. It is // answered 404 before the access-token gate, so a probe does not read a 401 as partial support. if (req.method == "GET" && starts_with(req.target, "/_matrix/client/unstable/org.matrix.msc2965/")) @@ -17068,6 +17235,10 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } if (req.method == "POST" && request_path == "/_matrix/client/v3/account/password") { + if (auto const refusal = oauth_session_uia_refusal(rt, req.access_token); refusal.has_value()) + { + return dispatch_err(req, rt, 403U, "M_FORBIDDEN", *refusal); + } auto const object = parsed_json_object(req.body); if (!object.has_value()) { @@ -17150,6 +17321,10 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp // lock/suspend existed, and that is reversible rather than final. if (req.method == "POST" && request_path == "/_matrix/client/v3/account/deactivate") { + if (auto const refusal = oauth_session_uia_refusal(rt, req.access_token); refusal.has_value()) + { + return dispatch_err(req, rt, 403U, "M_FORBIDDEN", *refusal); + } auto const object = parsed_json_object(req.body); if (!object.has_value()) { @@ -17262,6 +17437,10 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } if (req.method == "POST" && request_path == "/_matrix/client/v3/account/3pid/add") { + if (auto const refusal = oauth_session_uia_refusal(rt, req.access_token); refusal.has_value()) + { + return dispatch_err(req, rt, 403U, "M_FORBIDDEN", *refusal); + } auto const body = parse_account_threepid_add_body(req.body); if (!body.has_value()) { @@ -18755,6 +18934,10 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } if (req.method == "DELETE" && starts_with(req.target, dev_prefix)) { + if (auto const refusal = oauth_session_uia_refusal(rt, req.access_token); refusal.has_value()) + { + return dispatch_err(req, rt, 403U, "M_FORBIDDEN", *refusal); + } // Spec §10.7.1: DELETE /devices/{deviceId} requires UIA with // m.login.password to prove account ownership before deletion. auto const challenge = [&](bool password_failed) -> DispatchResult { @@ -18822,6 +19005,10 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } if (req.method == "POST" && request_path == "/_matrix/client/v3/delete_devices") { + if (auto const refusal = oauth_session_uia_refusal(rt, req.access_token); refusal.has_value()) + { + return dispatch_err(req, rt, 403U, "M_FORBIDDEN", *refusal); + } auto const challenge = [&](bool password_failed) -> DispatchResult { auto const session = issue_uia_session(rt, "delete_devices", *user); if (!session.has_value()) diff --git a/src/homeserver/OAuthAuthorization.cpp b/src/homeserver/OAuthAuthorization.cpp index 8586cdcb0..0d630d7c1 100644 --- a/src/homeserver/OAuthAuthorization.cpp +++ b/src/homeserver/OAuthAuthorization.cpp @@ -34,6 +34,7 @@ #include "merovingian/oauth/AuthorizationRedirect.hpp" #include "merovingian/oauth/ClientMetadata.hpp" #include "merovingian/oauth/ConsentPageInput.hpp" +#include "merovingian/oauth/FormContentType.hpp" #include "merovingian/oauth/FormPostOrigin.hpp" #include "merovingian/oauth/GrantedScope.hpp" #include "merovingian/oauth/HtmlText.hpp" @@ -633,29 +634,6 @@ namespace oauth::error_access_denied, "The user denied the request.", consumed->state); } - // `application/x-www-form-urlencoded`, in any ASCII case, with no parameter: what an HTML form posts. - [[nodiscard]] auto is_form_content_type(std::string_view content_type) noexcept -> bool - { - constexpr auto expected = std::string_view{"application/x-www-form-urlencoded"}; - if (content_type.size() != expected.size()) - { - return false; - } - for (auto index = std::size_t{0U}; index < expected.size(); ++index) - { - auto value = content_type[index]; - if (value >= 'A' && value <= 'Z') - { - value = static_cast(value - 'A' + 'a'); - } - if (value != expected[index]) - { - return false; - } - } - return true; - } - [[nodiscard]] auto handle_post(ClientServerRuntime& rt, LocalHttpRequest const& request) -> LocalHttpResponse { auto& runtime = rt.homeserver; @@ -676,7 +654,7 @@ namespace oauth::HtmlText{"This form was not sent from a page of this server."}); } auto const content_type = single_header(request, "Content-Type"); - if (!content_type.has_value() || !is_form_content_type(*content_type)) + if (!content_type.has_value() || !oauth::page_form_content_type_is_accepted(*content_type)) { return error_page_response(status_bad_request, oauth::HtmlText{"Form refused"}, oauth::HtmlText{"This form could not be read."}); diff --git a/src/homeserver/OAuthClientCredentials.cpp b/src/homeserver/OAuthClientCredentials.cpp new file mode 100644 index 000000000..17d7f580f --- /dev/null +++ b/src/homeserver/OAuthClientCredentials.cpp @@ -0,0 +1,70 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/OAuthClientCredentials.hpp" + +#include "merovingian/core/FormFields.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/OAuthJsonResponse.hpp" +#include "merovingian/homeserver/RequestHeaders.hpp" +#include "merovingian/oauth/OAuthErrorCodes.hpp" + +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +namespace +{ + + [[nodiscard]] auto ascii_lower(char c) noexcept -> char + { + return c >= 'A' && c <= 'Z' ? static_cast(c - 'A' + 'a') : c; + } + + // Whether `value` is an `Authorization` header value of the `Basic` scheme: the scheme alone, or followed by a + // space and the credentials. + [[nodiscard]] auto is_basic_scheme(std::string_view value) noexcept -> bool + { + constexpr auto scheme = std::string_view{"basic"}; + if (value.size() < scheme.size() || (value.size() > scheme.size() && value[scheme.size()] != ' ')) + { + return false; + } + for (std::size_t index = 0U; index < scheme.size(); ++index) + { + if (ascii_lower(value[index]) != scheme[index]) + { + return false; + } + } + return true; + } + +} // namespace + +auto oauth_client_credentials_refusal(LocalHttpRequest const& request, core::FormFields const& fields) + -> std::optional +{ + for (auto const value : request_header_values(request, "Authorization")) + { + if (is_basic_scheme(value)) + { + auto response = oauth_error_response(std::uint16_t{401U}, oauth::error_invalid_client, + "This server has only public clients, which send no credentials."); + response.headers.emplace_back("WWW-Authenticate", "Basic"); + return response; + } + } + if (fields.find("client_secret").has_value()) + { + return oauth_error_response(std::uint16_t{400U}, oauth::error_invalid_client, + "This server has only public clients, which send no client_secret."); + } + return std::nullopt; +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/OAuthJsonResponse.cpp b/src/homeserver/OAuthJsonResponse.cpp index 8b36e0530..c05f9c9ed 100644 --- a/src/homeserver/OAuthJsonResponse.cpp +++ b/src/homeserver/OAuthJsonResponse.cpp @@ -5,6 +5,8 @@ #include "merovingian/canonicaljson/CanonicalJsonError.hpp" #include "merovingian/canonicaljson/Serializer.hpp" +#include "merovingian/core/Error.hpp" +#include "merovingian/core/ErrorCode.hpp" #include #include @@ -48,4 +50,21 @@ auto oauth_error_response(std::uint16_t status, oauth::OAuthRefusal const& refus return oauth_json_response(status, canonicaljson::Value{std::move(object)}); } +auto oauth_error_response(std::uint16_t status, std::string_view error_code, std::string_view description) + -> LocalHttpResponse +{ + return oauth_error_response( + status, oauth::OAuthRefusal{ + std::string{error_code}, + core::Error{core::ErrorCode::invalid_argument, std::string{description}} + }); +} + +auto oauth_empty_response(std::uint16_t status) -> LocalHttpResponse +{ + auto response = LocalHttpResponse{status, {}, {}}; + response.headers.emplace_back("Cache-Control", "no-store"); + return response; +} + } // namespace merovingian::homeserver diff --git a/src/homeserver/OAuthRevocation.cpp b/src/homeserver/OAuthRevocation.cpp new file mode 100644 index 000000000..29cf8be74 --- /dev/null +++ b/src/homeserver/OAuthRevocation.cpp @@ -0,0 +1,112 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/OAuthRevocation.hpp" + +#include "merovingian/core/FormFields.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientDeviceSessions.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalSession.hpp" +#include "merovingian/homeserver/OAuthClientCredentials.hpp" +#include "merovingian/homeserver/OAuthJsonResponse.hpp" +#include "merovingian/homeserver/RequestHeaders.hpp" +#include "merovingian/oauth/FormContentType.hpp" +#include "merovingian/oauth/OAuthErrorCodes.hpp" +#include "merovingian/observability/LogEventSeverity.hpp" +#include "merovingian/observability/SingleLog.hpp" +#include "merovingian/observability/StructuredLogField.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +namespace +{ + + constexpr auto status_ok = std::uint16_t{200U}; + constexpr auto status_bad_request = std::uint16_t{400U}; + constexpr auto status_server_error = std::uint16_t{500U}; + + // Logs a refused revocation request by its wire error only: the request carried a token. + auto log_refused(std::string_view error_code) -> void + { + observability::log_diagnostic("oauth", "oauth.revocation.refused", + { + {"error", std::string{error_code}, false} + }, + observability::LogEventSeverity::debug); + } + +} // namespace + +auto handle_oauth_revoke(ClientServerRuntime& runtime, LocalHttpRequest const& request) -> LocalHttpResponse +{ + if (!oauth::api_form_content_type_is_accepted(request_header(request, "Content-Type"))) + { + log_refused(oauth::error_invalid_request); + return oauth_error_response(status_bad_request, oauth::error_invalid_request, + "The body must be application/x-www-form-urlencoded."); + } + // The parsed fields hold the token; FormFields wipes them when `parsed` ends. + auto parsed = core::FormFields::parse(request.body); + auto const* const fields = std::get_if(&parsed); + if (fields == nullptr) + { + log_refused(oauth::error_invalid_request); + return oauth_error_response(status_bad_request, oauth::error_invalid_request, "The body is malformed."); + } + if (auto credentials_refusal = oauth_client_credentials_refusal(request, *fields); credentials_refusal.has_value()) + { + log_refused(oauth::error_invalid_client); + return std::move(*credentials_refusal); + } + auto const token = fields->find("token"); + if (!token.has_value()) + { + log_refused(oauth::error_invalid_request); + return oauth_error_response(status_bad_request, oauth::error_invalid_request, "The request lacks token."); + } + + auto& homeserver = runtime.homeserver; + auto const session = revocable_session_of_token(homeserver, *token); + if (!session.has_value()) + { + // RFC 7009 section 2.2: a token that is invalid, expired or already revoked is answered 200 all the same. + return oauth_empty_response(status_ok); + } + auto const* const oauth_row = + database::find_oauth_session(homeserver.database.persistent_store, session->user_id, session->device_id); + auto const client_id = oauth_row != nullptr ? oauth_row->client_id : std::string{}; + auto const ended = + end_device_session_and_announce(runtime, session->user_id, session->device_id, "oauth.session.revoked"); + if (!ended.ok) + { + log_refused(oauth::error_server_error); + return oauth_error_response(status_server_error, oauth::error_server_error, + "The server could not revoke the session."); + } + auto fields_logged = std::vector{ + {"user_id", session->user_id, false}, + {"device_id", session->device_id, false} + }; + if (!client_id.empty()) + { + fields_logged.push_back({"client_id", client_id, false}); + } + observability::log_diagnostic("oauth", "oauth.revocation.accepted", std::move(fields_logged), + observability::LogEventSeverity::info); + return oauth_empty_response(status_ok); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/OAuthTokenEndpoint.cpp b/src/homeserver/OAuthTokenEndpoint.cpp new file mode 100644 index 000000000..155e2527a --- /dev/null +++ b/src/homeserver/OAuthTokenEndpoint.cpp @@ -0,0 +1,301 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/OAuthTokenEndpoint.hpp" + +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/core/FormFields.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/AuthorizationCodeRedemption.hpp" +#include "merovingian/homeserver/AuthorizationCodeStore.hpp" +#include "merovingian/homeserver/ClientDeviceSessions.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/OAuthClientCredentials.hpp" +#include "merovingian/homeserver/OAuthClientRegistration.hpp" +#include "merovingian/homeserver/OAuthClock.hpp" +#include "merovingian/homeserver/OAuthGrantRequest.hpp" +#include "merovingian/homeserver/OAuthJsonResponse.hpp" +#include "merovingian/homeserver/PasswordLoginVerification.hpp" +#include "merovingian/homeserver/RequestHeaders.hpp" +#include "merovingian/homeserver/SessionRefreshResult.hpp" +#include "merovingian/homeserver/SignedInDevice.hpp" +#include "merovingian/oauth/AccessTokenLifetime.hpp" +#include "merovingian/oauth/ClientMetadata.hpp" +#include "merovingian/oauth/FormContentType.hpp" +#include "merovingian/oauth/OAuthErrorCodes.hpp" +#include "merovingian/oauth/Pkce.hpp" +#include "merovingian/observability/LogEventSeverity.hpp" +#include "merovingian/observability/SingleLog.hpp" +#include "merovingian/observability/StructuredLogField.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +namespace +{ + + constexpr auto status_ok = std::uint16_t{200U}; + constexpr auto status_bad_request = std::uint16_t{400U}; + constexpr auto status_server_error = std::uint16_t{500U}; + constexpr auto first_server_error_status = std::uint16_t{500U}; + + // Logs a refused token request: the grant type, the wire error and the client ID when one was sent. Never the + // code, the verifier, a token or any other value the request carried. + auto log_refused(std::string_view grant_type, std::string_view error_code, std::string_view client_id) -> void + { + auto fields = std::vector{ + {"grant_type", std::string{grant_type}, false}, + {"error", std::string{error_code}, false} + }; + if (!client_id.empty()) + { + fields.push_back({"client_id", std::string{client_id}, false}); + } + observability::log_diagnostic("oauth", "oauth.token.refused", std::move(fields), + observability::LogEventSeverity::debug); + } + + [[nodiscard]] auto token_answer(SessionRefreshResult const& session, std::int64_t expires_in, + std::string_view scope) -> LocalHttpResponse + { + auto object = canonicaljson::Object{}; + object.push_back(canonicaljson::make_member("access_token", canonicaljson::Value{session.access_token})); + object.push_back(canonicaljson::make_member("expires_in", canonicaljson::Value{expires_in})); + object.push_back(canonicaljson::make_member("refresh_token", canonicaljson::Value{session.refresh_token})); + object.push_back(canonicaljson::make_member("scope", canonicaljson::Value{std::string{scope}})); + object.push_back(canonicaljson::make_member("token_type", canonicaljson::Value{std::string{"Bearer"}})); + return oauth_json_response(status_ok, canonicaljson::Value{std::move(object)}); + } + + [[nodiscard]] auto oauth_expires_in(HomeserverRuntime const& runtime) -> std::int64_t + { + return oauth::expires_in_seconds( + oauth::access_token_lifetime_ms(runtime.config.security().access_token_lifetime_ms)); + } + + // A replayed code (ADR-0792): the session its first redemption produced is ended, and only it. The device's + // current `oauth_sessions` row must be the very one that redemption wrote, named by its client and its + // process-unique `created_at_ms`; a row written since (a later grant on the same device) is left alone. + auto end_replayed_session(ClientServerRuntime& rt, AuthorizationCodeRedemption const& redemption) -> void + { + auto& runtime = rt.homeserver; + auto ended = false; + if (redemption.session_created_at_ms.has_value()) + { + auto const* const row = database::find_oauth_session(runtime.database.persistent_store, redemption.user_id, + redemption.device_id); + if (row != nullptr && row->client_id == redemption.client_id && + row->created_at_ms == *redemption.session_created_at_ms) + { + ended = + end_device_session_and_announce(rt, redemption.user_id, redemption.device_id, "oauth.code.replayed") + .ok; + } + } + observability::log_diagnostic("oauth", "oauth.code.replayed", + { + {"client_id", redemption.client_id, false}, + {"user_id", redemption.user_id, false}, + {"device_id", redemption.device_id, false}, + {"session_ended", ended ? "true" : "false", false} + }, + observability::LogEventSeverity::warning); + } + + [[nodiscard]] auto device_display_name(ClientServerRuntime const& rt, oauth::ClientMetadata const& client) + -> std::string + { + auto const& name = client.client_name(); + if (!name.has_value() || name->size() > rt.limits.max_device_display_name_bytes) + { + return {}; + } + return *name; + } + + [[nodiscard]] auto authorization_code_grant(ClientServerRuntime& rt, core::FormFields const& fields) + -> LocalHttpResponse + { + constexpr auto grant_type = oauth::grant_type_authorization_code; + auto& runtime = rt.homeserver; + auto const client_id = fields.find("client_id"); + auto const code = fields.find("code"); + auto const redirect_uri = fields.find("redirect_uri"); + auto const verifier = fields.find("code_verifier"); + auto const refuse = [&](std::uint16_t status, std::string_view error_code, + std::string_view description) -> LocalHttpResponse { + log_refused(grant_type, error_code, client_id.value_or(std::string_view{})); + return oauth_error_response(status, error_code, description); + }; + if (!client_id.has_value() || !code.has_value() || !redirect_uri.has_value() || !verifier.has_value()) + { + return refuse(status_bad_request, oauth::error_invalid_request, + "The request lacks client_id, code, redirect_uri or code_verifier."); + } + auto const client = find_registered_oauth_client(runtime, *client_id); + if (!client.has_value()) + { + return refuse(status_bad_request, oauth::error_invalid_client, "The client is not registered."); + } + if (!client->has_grant_type(grant_type)) + { + return refuse(status_bad_request, oauth::error_unauthorized_client, + "The client is not registered for the authorization_code grant."); + } + if (!oauth::pkce_verifier_is_valid(*verifier)) + { + return refuse(status_bad_request, oauth::error_invalid_request, "The code_verifier is malformed."); + } + + auto const now_ms = oauth_wall_clock_ms(); + auto const redemption = runtime.oauth_codes.redeem(*code, now_ms); + if (redemption.outcome == AuthorizationCodeRedemption::Outcome::replayed) + { + end_replayed_session(rt, redemption); + return refuse(status_bad_request, oauth::error_invalid_grant, "The authorization code was already used."); + } + if (redemption.outcome != AuthorizationCodeRedemption::Outcome::fresh) + { + return refuse(status_bad_request, oauth::error_invalid_grant, + "The authorization code is invalid or expired."); + } + // The code is spent from here, whatever the outcome (RFC 6749 section 4.1.2: single use). + auto const& grant = redemption.grant; + if (grant.client_id != *client_id || grant.redirect_uri != *redirect_uri || + !oauth::pkce_s256_matches(*verifier, grant.code_challenge)) + { + return refuse(status_bad_request, oauth::error_invalid_grant, + "The authorization code was not issued for this request."); + } + if (account_sign_in_gate(runtime, grant.user_id, grant.device_id) != + PasswordLoginVerification::Outcome::verified) + { + return refuse(status_bad_request, oauth::error_invalid_grant, "The account cannot sign in."); + } + + auto request = OAuthGrantRequest{}; + request.user_id = grant.user_id; + request.device_id = grant.device_id; + request.client_id = grant.client_id; + request.scope = grant.scope; + request.display_name = device_display_name(rt, *client); + request.created_at_ms = runtime.oauth_codes.next_session_created_at_ms(now_ms); + auto const session = grant_oauth_session(runtime, request); + if (!session.ok) + { + if (session.status >= first_server_error_status) + { + return refuse(status_server_error, oauth::error_server_error, + "The server could not complete the grant."); + } + return refuse(status_bad_request, oauth::error_invalid_grant, "The session cannot be granted."); + } + // Names the row this code produced, so a replay ends it and nothing else. The code is held: nothing above + // released runtime.mutex, so it cannot have expired from under the redemption. + std::ignore = runtime.oauth_codes.record_issued_session(*code, request.created_at_ms, oauth_wall_clock_ms()); + remember_signed_in_device(rt, session.user_id, session.device_id, request.display_name, + SignedInDevice::new_session); + return token_answer(session, oauth_expires_in(runtime), grant.scope); + } + + [[nodiscard]] auto refresh_token_grant(ClientServerRuntime& rt, core::FormFields const& fields) -> LocalHttpResponse + { + constexpr auto grant_type = oauth::grant_type_refresh_token; + auto& runtime = rt.homeserver; + auto const client_id = fields.find("client_id"); + auto const refresh_token = fields.find("refresh_token"); + auto const refuse = [&](std::uint16_t status, std::string_view error_code, + std::string_view description) -> LocalHttpResponse { + log_refused(grant_type, error_code, client_id.value_or(std::string_view{})); + return oauth_error_response(status, error_code, description); + }; + if (!client_id.has_value() || !refresh_token.has_value()) + { + return refuse(status_bad_request, oauth::error_invalid_request, + "The request lacks client_id or refresh_token."); + } + auto const client = find_registered_oauth_client(runtime, *client_id); + if (!client.has_value()) + { + return refuse(status_bad_request, oauth::error_invalid_client, "The client is not registered."); + } + if (!client->has_grant_type(grant_type)) + { + return refuse(status_bad_request, oauth::error_unauthorized_client, + "The client is not registered for the refresh_token grant."); + } + auto const session = refresh_local_session(runtime, *refresh_token, *client_id); + if (!session.ok) + { + if (session.status >= first_server_error_status) + { + return refuse(status_server_error, oauth::error_server_error, + "The server could not refresh the session."); + } + return refuse(status_bad_request, oauth::error_invalid_grant, "The refresh token is invalid."); + } + // As POST /refresh does: the runtime's device list is healed after a restart, nothing is announced. + remember_signed_in_device(rt, session.user_id, session.device_id, session.device_id, + SignedInDevice::refreshed_session); + auto const* const row = + database::find_oauth_session(runtime.database.persistent_store, session.user_id, session.device_id); + auto const scope = row != nullptr ? row->scope : std::string{}; + return token_answer(session, oauth_expires_in(runtime), scope); + } + +} // namespace + +auto handle_oauth_token(ClientServerRuntime& runtime, LocalHttpRequest const& request) -> LocalHttpResponse +{ + if (!oauth::api_form_content_type_is_accepted(request_header(request, "Content-Type"))) + { + log_refused({}, oauth::error_invalid_request, {}); + return oauth_error_response(status_bad_request, oauth::error_invalid_request, + "The body must be application/x-www-form-urlencoded."); + } + auto parsed = core::FormFields::parse(request.body); + auto const* const fields = std::get_if(&parsed); + if (fields == nullptr) + { + log_refused({}, oauth::error_invalid_request, {}); + return oauth_error_response(status_bad_request, oauth::error_invalid_request, "The body is malformed."); + } + // The parsed fields hold the code, the verifier or the refresh token; FormFields wipes them when `parsed` ends. + if (auto credentials_refusal = oauth_client_credentials_refusal(request, *fields); credentials_refusal.has_value()) + { + log_refused({}, oauth::error_invalid_client, {}); + return std::move(*credentials_refusal); + } + auto const grant_type = fields->find("grant_type"); + if (!grant_type.has_value()) + { + log_refused({}, oauth::error_invalid_request, {}); + return oauth_error_response(status_bad_request, oauth::error_invalid_request, "The request lacks grant_type."); + } + if (*grant_type == oauth::grant_type_authorization_code) + { + return authorization_code_grant(runtime, *fields); + } + if (*grant_type == oauth::grant_type_refresh_token) + { + return refresh_token_grant(runtime, *fields); + } + log_refused({}, oauth::error_unsupported_grant_type, {}); + return oauth_error_response(status_bad_request, oauth::error_unsupported_grant_type, + "The grant_type is not supported."); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/meson.build b/src/homeserver/meson.build index 34a666a92..ae8e81f0b 100644 --- a/src/homeserver/meson.build +++ b/src/homeserver/meson.build @@ -32,9 +32,12 @@ homeserver_sources = files( 'StreamedBody.cpp', 'MediaUploadNotifier.cpp', 'OAuthAuthorization.cpp', + 'OAuthClientCredentials.cpp', 'OAuthClientRegistration.cpp', 'OAuthClock.cpp', 'OAuthJsonResponse.cpp', + 'OAuthRevocation.cpp', + 'OAuthTokenEndpoint.cpp', 'OperatorAdmin.cpp', 'UrlPreviewService.cpp', 'PeriodicJob.cpp', diff --git a/src/oauth/AGENTS.md b/src/oauth/AGENTS.md index 67b3f8652..dbf6068ea 100644 --- a/src/oauth/AGENTS.md +++ b/src/oauth/AGENTS.md @@ -26,6 +26,8 @@ Pure functions and value types for the built-in OAuth 2.0 API | `AuthorizationPages.cpp`, `AccountFormInput.hpp`, `ConsentPageInput.hpp` | The login, registration, consent and error pages of `/_merovingian/oauth2/authorize`, and the form field and action names they post. A value `HtmlText::escape` refuses is replaced by fixed text | | `FormPostOrigin.cpp` | `form_post_origin`, `form_post_origin_is_accepted`: a page's form post must name this server's origin exactly, and `Sec-Fetch-Site`, when sent, `same-origin` (ADR-0784) | | `HandOffAllowlist.cpp` | `hand_off_allowlist_entry_error`, `hand_off_allowlist_error`: an https origin or a bare private-use scheme, at most 32, each once (ADR-0774) | +| `FormContentType.cpp` | `api_form_content_type_is_accepted`: the token and revocation endpoints take `application/x-www-form-urlencoded` only, with at most a `charset=utf-8` parameter | +| `AccessTokenLifetime.hpp` | `access_token_lifetime_ms` (the configured lifetime, or one hour when it is 0: an OAuth access token always expires, ADR-0791) and `expires_in_seconds` | | `DisplayText.cpp`, `AsciiCase.cpp` | Module-internal: `display_text_is_safe` (no control or bidirectional formatting character) and `ascii_lower` | ## Rules diff --git a/src/oauth/FormContentType.cpp b/src/oauth/FormContentType.cpp new file mode 100644 index 000000000..5a68090fd --- /dev/null +++ b/src/oauth/FormContentType.cpp @@ -0,0 +1,73 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/oauth/FormContentType.hpp" + +#include +#include + +namespace merovingian::oauth +{ +namespace +{ + + constexpr auto form_type = std::string_view{"application/x-www-form-urlencoded"}; + + [[nodiscard]] constexpr auto lower(char value) noexcept -> char + { + return value >= 'A' && value <= 'Z' ? static_cast(value - 'A' + 'a') : value; + } + + // `text` equals the lower-case `expected` in any ASCII case. + [[nodiscard]] auto equals_ignoring_case(std::string_view text, std::string_view expected) noexcept -> bool + { + if (text.size() != expected.size()) + { + return false; + } + for (auto index = std::size_t{0U}; index < expected.size(); ++index) + { + if (lower(text[index]) != expected[index]) + { + return false; + } + } + return true; + } + + [[nodiscard]] auto trim_spaces(std::string_view text) noexcept -> std::string_view + { + while (!text.empty() && (text.front() == ' ' || text.front() == '\t')) + { + text.remove_prefix(1U); + } + while (!text.empty() && (text.back() == ' ' || text.back() == '\t')) + { + text.remove_suffix(1U); + } + return text; + } + +} // namespace + +auto page_form_content_type_is_accepted(std::string_view content_type) noexcept -> bool +{ + return equals_ignoring_case(content_type, form_type); +} + +auto api_form_content_type_is_accepted(std::string_view content_type) noexcept -> bool +{ + auto const separator = content_type.find(';'); + if (!equals_ignoring_case(trim_spaces(content_type.substr(0U, separator)), form_type)) + { + return false; + } + if (separator == std::string_view::npos) + { + return true; + } + auto const parameter = trim_spaces(content_type.substr(separator + 1U)); + return equals_ignoring_case(parameter, "charset=utf-8") || equals_ignoring_case(parameter, "charset=\"utf-8\""); +} + +} // namespace merovingian::oauth diff --git a/src/oauth/meson.build b/src/oauth/meson.build index 8f7709e3e..28bb17a2c 100644 --- a/src/oauth/meson.build +++ b/src/oauth/meson.build @@ -5,6 +5,7 @@ oauth_sources = files( 'ClientMetadata.cpp', 'ClientUri.cpp', 'DisplayText.cpp', + 'FormContentType.cpp', 'FormPostOrigin.cpp', 'HandOffAllowlist.cpp', 'HtmlText.cpp', diff --git a/tests/conformance/AGENTS.md b/tests/conformance/AGENTS.md index 5d3896e06..e4bda23ac 100644 --- a/tests/conformance/AGENTS.md +++ b/tests/conformance/AGENTS.md @@ -63,6 +63,7 @@ Every test in this directory directly encodes a **MUST** or **SHOULD** from the | `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) | | `test_oauth_authorization_conformance.cpp` | [CS API § Authorisation code grant](../../docs/matrix-v1.19-spec/client-server-api.md#authorisation-code-grant) · [§ Scope](../../docs/matrix-v1.19-spec/client-server-api.md#scope) · [§ User registration](../../docs/matrix-v1.19-spec/client-server-api.md#user-registration) (`/_merovingian/oauth2/authorize`: an unregistered redirect URI is never redirected to; `state` on success and error; the response mode places the answer; S256 required; the API and exactly one device scope; `prompt=create` shows registration only when accepted) | +| `test_oauth_token_conformance.cpp` | [CS API § Refresh token grant](../../docs/matrix-v1.19-spec/client-server-api.md#refresh-token-grant) · [§ Token revocation](../../docs/matrix-v1.19-spec/client-server-api.md#token-revocation) (`/_merovingian/oauth2/token` and `/revoke`: an access token always expires; a lost refresh answer can be retried and the old token is refused once the new one is used; revocation ends both tokens whatever the `client_id` and answers 200 for an unknown token) | | `test_oauth_client_registration_conformance.cpp` | [CS API § Client registration](../../docs/matrix-v1.19-spec/client-server-api.md#client-registration) · [§ Client metadata](../../docs/matrix-v1.19-spec/client-server-api.md#client-metadata) · [§ Redirect URI validation](../../docs/matrix-v1.19-spec/client-server-api.md#redirect-uri-validation) · [§ Dynamic client registration flow](../../docs/matrix-v1.19-spec/client-server-api.md#dynamic-client-registration-flow) (`POST /_merovingian/oauth2/register`: 201 with `client_id` and the registered metadata, web and native, `none`, unknown values ignored, the spec's redirect URI examples, a client with a session never deleted) | | `test_pdu_format_conformance.cpp` | [SS API § PDUs](../../docs/matrix-v1.19-spec/server-server-api.md#pdus) | | `test_pdu_ingestion_conformance.cpp` | [SS API § Checks performed on receipt of a PDU](../../docs/matrix-v1.19-spec/server-server-api.md#checks-performed-on-receipt-of-a-pdu) · [Room v12 § State resolution](../../docs/matrix-v1.19-spec/rooms/v12.md) (auth_events selection: m.room.create MUST NOT be selected) · [§ Calculating the reference hash](../../docs/matrix-v1.19-spec/server-server-api.md#calculating-the-reference-hash-for-an-event) (a received PDU is stored without its `unsigned`, under an unchanged event ID) | diff --git a/tests/conformance/test_account_lifecycle_conformance.cpp b/tests/conformance/test_account_lifecycle_conformance.cpp index 3b9300081..38a3e3761 100644 --- a/tests/conformance/test_account_lifecycle_conformance.cpp +++ b/tests/conformance/test_account_lifecycle_conformance.cpp @@ -5,6 +5,7 @@ // Authentication failure body, logout deleting the device, M_MISSING_TOKEN on logout, // registration sessions and username checks, M_NOT_JSON, and 405 M_UNRECOGNIZED. +#include "../support/CrossSigningFixture.hpp" #include "../support/InMemoryDatabaseConfig.hpp" #include "../support/JsonTestSupport.hpp" #include "../support/MasterKey.hpp" @@ -19,8 +20,8 @@ #include "merovingian/homeserver/ClientServerStartResult.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/LocalHttpResponse.hpp" -#include "merovingian/homeserver/RuntimeStartResult.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" +#include "merovingian/homeserver/RuntimeStartResult.hpp" #include @@ -208,10 +209,15 @@ SCENARIO("A failed User-Interactive Authentication stage answers 401 with errcod check_failure(response); } } - WHEN("the wrong password is given to POST /keys/device_signing/upload") + WHEN("the wrong password is given to POST /keys/device_signing/upload to replace a held master key") { + // Spec v1.19 ("Changed in v1.11"): no UIA is asked for while no master key is held, so one is held first. + REQUIRE(send(started.runtime, "POST", "/_matrix/client/v3/keys/device_signing/upload", token, + "{" + merovingian::tests::make_cross_signing_set("@alice:example.org").master_member() + "}") + .status == 200U); + auto const replacement = merovingian::tests::make_cross_signing_set("@alice:example.org").master_member(); auto const response = send(started.runtime, "POST", "/_matrix/client/v3/keys/device_signing/upload", token, - "{" + password_auth("alice", "WrongHorse7!") + "}"); + "{" + replacement + "," + password_auth("alice", "WrongHorse7!") + "}"); THEN("the failure carries errcode M_FORBIDDEN and error") { check_failure(response); diff --git a/tests/conformance/test_client_server_conformance.cpp b/tests/conformance/test_client_server_conformance.cpp index 98d8bdb85..3de5ba82c 100644 --- a/tests/conformance/test_client_server_conformance.cpp +++ b/tests/conformance/test_client_server_conformance.cpp @@ -1960,34 +1960,66 @@ SCENARIO("POST /keys/upload with OTKs then POST /keys/claim returns and consumes // --- POST /_matrix/client/v3/keys/device_signing/upload ---------------------- // Spec: ../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3keysdevice_signingupload // -// This endpoint uses the User-Interactive Authentication API (UIA). -// A request without auth MUST return 401 with the UIA flows challenge. +// "Changed in v1.11: UIA is not always required for this endpoint." "User-Interactive Authentication MUST be +// performed for regular clients, except in these cases: there is no existing master signing key uploaded to the +// homeserver, OR there is an existing master signing key and it exactly matches the master signing key provided in +// the request body. If there are any additional keys provided in the request (self-signing key, user-signing key) +// they MUST also match the existing keys stored on the server." // Success MUST return HTTP 200 with an empty JSON object {}. -SCENARIO("POST /keys/device_signing/upload without auth returns 401 UIA challenge", - "[conformance][client-server][e2ee][keys]") +SCENARIO("POST /keys/device_signing/upload asks for UIA only to change a held master key", + "[conformance][client-server][e2ee][keys][cross-signing-uia]") { - GIVEN("a logged-in device") + GIVEN("a logged-in device whose user holds no cross-signing key") { auto started = merovingian::homeserver::start_client_server(conformance_config()); REQUIRE(started.started); auto const token = logged_in_token(started.runtime); + auto const upload = [&](std::string body) { + return merovingian::homeserver::handle_client_server_request( + started.runtime, {"POST", "/_matrix/client/v3/keys/device_signing/upload", token, std::move(body)}); + }; + auto const first = merovingian::tests::make_cross_signing_set("@alice:example.org"); + auto const first_members = first.selected_members(true, true, true); - WHEN("the device uploads cross-signing keys without providing auth") + WHEN("the device uploads its first keys without auth") { - auto const response = merovingian::homeserver::handle_client_server_request( - started.runtime, - {"POST", "/_matrix/client/v3/keys/device_signing/upload", token, - R"({"master_key":{"user_id":"@alice:example.org","keys":{"ed25519:master":"base64key"},"usage":["master"]}})"}); - - THEN("the server issues a UIA challenge with m.login.password flow") + auto const response = upload("{" + first_members + "}"); + THEN("they are stored without a UIA challenge") + { + // Spec MUST NOT require UIA: "there is no existing master signing key uploaded to the homeserver". + REQUIRE(response.response.status == 200U); + REQUIRE(response.response.body == "{}"); + } + } + WHEN("the same keys are uploaded again without auth") + { + REQUIRE(upload("{" + first_members + "}").response.status == 200U); + auto const repeated = upload("{" + first_members + "}"); + auto const master_only = upload("{" + first.selected_members(true, false, false) + "}"); + THEN("the repeat is accepted, since it holds no new key") + { + // Spec: the existing master key "exactly matches" and every other key "MUST also match". + REQUIRE(repeated.response.status == 200U); + REQUIRE(master_only.response.status == 200U); + } + } + WHEN("a different master key is uploaded without auth once one is held") + { + REQUIRE(upload("{" + first_members + "}").response.status == 200U); + auto const second = merovingian::tests::make_cross_signing_set("@alice:example.org"); + auto const response = upload("{" + second.selected_members(true, true, true) + "}"); + auto const self_signing_only = upload("{" + second.selected_members(false, true, false) + "}"); + THEN("the server issues a UIA challenge with the m.login.password flow") { - // Spec MUST: cross-signing upload uses UIA to prevent key takeover. + // Spec MUST: replacing a held master key requires UIA, to prevent key takeover. REQUIRE(response.response.status == 401U); auto const body = parse_object(response.response.body); // Spec MUST: UIA challenge body contains flows, params, and session. REQUIRE(object_member(body, "flows") != nullptr); REQUIRE(object_member_as_object(body, "params") != nullptr); REQUIRE(object_member(body, "session") != nullptr); + // Spec: a request without the matching master key is not one of the exempt cases. + REQUIRE(self_signing_only.response.status == 401U); } } } diff --git a/tests/conformance/test_oauth_token_conformance.cpp b/tests/conformance/test_oauth_token_conformance.cpp new file mode 100644 index 000000000..85c0e92a4 --- /dev/null +++ b/tests/conformance/test_oauth_token_conformance.cpp @@ -0,0 +1,245 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The OAuth 2.0 token and revocation endpoints against the Matrix Client-Server API v1.19: the authorisation code and +// refresh token grants, and token revocation (RFC 6749, RFC 7009). + +#include "../support/OAuthAuthorizationSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "../support/OAuthTokenSupport.hpp" +#include "../support/RegistrationToken.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include + +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace hs = merovingian::homeserver; + +constexpr auto alice_password = std::string_view{"AlicePass99!x"}; + +struct Fixture final +{ + hs::ClientServerStartResult started; + std::string client_id; +}; + +// OAuth on, alice registered, a web client registered; `access_token_lifetime_ms` as given. +[[nodiscard]] auto make_fixture(std::int64_t access_token_lifetime_ms = 3'600'000) -> Fixture +{ + auto config = oauth_registration_config(); + config.server().server_name = "example.org"; + enable_token_registration(config.security()); + config.security().access_token_lifetime_ms = access_token_lifetime_ms; + auto started = hs::start_client_server(config); + REQUIRE(started.started); + REQUIRE( + hs::register_local_user(started.runtime.homeserver, "alice", alice_password, std::string{registration_token}) + .ok); + auto client_id = register_oauth_web_client(started.runtime, oauth_both_grant_types); + REQUIRE_FALSE(client_id.empty()); + return {std::move(started), std::move(client_id)}; +} + +[[nodiscard]] auto whoami_status(hs::ClientServerRuntime& rt, std::string const& token) -> std::uint16_t +{ + return static_cast( + hs::handle_client_server_request(rt, {"GET", "/_matrix/client/v3/account/whoami", token, {}}, false) + .response.status); +} + +[[nodiscard]] auto oauth_error(hs::LocalHttpResponse const& response) -> std::string +{ + auto const body = parse_object(response.body); + auto const* error = string_member(body, "error"); + return error == nullptr ? std::string{} : *error; +} + +} // namespace + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Refresh token grant, Authorisation code grant +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#refresh-token-grant +// +// "When authorisation is granted to a client, the homeserver MUST issue a refresh token to the client in addition to +// the access token. The access token MUST be short-lived". RFC 6749 section 5.1: `access_token`, `token_type`, +// `expires_in`, `refresh_token`, `scope`. +SCENARIO("An authorisation code grant issues a short-lived access token and a refresh token", + "[conformance][client-server][oauth][oauth-token]") +{ + GIVEN("a server whose legacy access tokens never expire") + { + auto fixture = make_fixture(0); + auto& rt = fixture.started.runtime; + + WHEN("alice signs in through OAuth 2.0") + { + auto const answer = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + + THEN("the answer holds both tokens and a finite lifetime") + { + REQUIRE(answer.ok); + // Spec MUST: a refresh token is issued in addition to the access token. + REQUIRE_FALSE(answer.refresh_token.empty()); + REQUIRE_FALSE(answer.access_token.empty()); + // Spec MUST: "The access token MUST be short-lived", whatever the legacy configuration. + REQUIRE(answer.expires_in > 0); + REQUIRE(answer.expires_in <= 3600); + // RFC 6749 section 7.1: a Bearer token. + REQUIRE(answer.token_type == "Bearer"); + REQUIRE(answer.scope == oauth_test_scope); + REQUIRE(whoami_status(rt, answer.access_token) == 200U); + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Refresh token grant +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#refresh-token-grant +// +// "The homeserver SHOULD issue a new refresh token each time an old one is used, and invalidate the old one. However, +// it MUST ensure that the client is able to retry the refresh request in the case that the response to the request is +// lost." "The homeserver SHOULD consider that the session is compromised if an old, invalidated refresh token is used, +// and SHOULD revoke the session." +SCENARIO("The refresh token grant rotates, allows a lost answer to be retried, and revokes on reuse", + "[conformance][client-server][oauth][oauth-refresh]") +{ + GIVEN("alice signed in through OAuth 2.0") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const session = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + REQUIRE(session.ok); + + WHEN("the refresh token is used, and the answer is lost, so it is used again") + { + auto const lost = read_token_answer( + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(fixture.client_id, session.refresh_token))); + auto const retried = read_token_answer( + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(fixture.client_id, session.refresh_token))); + + THEN("both requests succeed with new tokens") + { + // Spec MUST: the client is able to retry a refresh whose answer was lost. + REQUIRE(lost.ok); + REQUIRE(retried.ok); + // Spec SHOULD: a new refresh token each time. + REQUIRE(retried.refresh_token != session.refresh_token); + REQUIRE(whoami_status(rt, retried.access_token) == 200U); + } + + AND_WHEN("the new refresh token is used, and then the old one again") + { + auto const next = read_token_answer(post_oauth_form( + rt, oauth_token_path, refresh_grant_fields(fixture.client_id, retried.refresh_token))); + REQUIRE(next.ok); + auto const reused = post_oauth_form(rt, oauth_token_path, + refresh_grant_fields(fixture.client_id, session.refresh_token)); + + THEN("the old token is refused and the session is revoked") + { + // Spec SHOULD: the old refresh token is invalidated once its successor is used. + REQUIRE(reused.status == 400U); + REQUIRE(oauth_error(reused) == "invalid_grant"); + // Spec SHOULD: reuse of an invalidated refresh token revokes the session. + REQUIRE(whoami_status(rt, next.access_token) == 401U); + } + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Token revocation +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#token-revocation +// +// "The server MUST revoke both the access token and refresh token associated with the token provided in the request." +// "If the `client_id` is not provided, or does not match the client associated with the token, the server SHOULD still +// revoke the token." "If the token is already revoked or invalid, the server returns a `200 OK` response". +SCENARIO("Token revocation revokes both tokens of the session", "[conformance][client-server][oauth][oauth-revoke]") +{ + GIVEN("alice signed in through OAuth 2.0") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const session = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + REQUIRE(session.ok); + + WHEN("the access token is revoked under a client ID that is not the session's") + { + auto const response = post_oauth_form(rt, oauth_revoke_path, + { + {"token", session.access_token}, + {"token_type_hint", "access_token" }, + {"client_id", "someone-else" }, + }); + + THEN("both tokens stop working") + { + // Spec SHOULD: revoked although the client ID does not match. + REQUIRE(response.status == 200U); + // Spec MUST: the access token is revoked. + REQUIRE(whoami_status(rt, session.access_token) == 401U); + // Spec MUST: the refresh token associated with it is revoked too. + auto const refreshed = post_oauth_form(rt, oauth_token_path, + refresh_grant_fields(fixture.client_id, session.refresh_token)); + REQUIRE(refreshed.status == 400U); + REQUIRE(oauth_error(refreshed) == "invalid_grant"); + } + + AND_WHEN("the same token is revoked again") + { + auto const again = post_oauth_form(rt, oauth_revoke_path, + { + {"token", session.access_token} + }); + THEN("the answer is 200 OK") + { + // Spec SHOULD: "If the token is already revoked or invalid, the server returns a 200 OK". + REQUIRE(again.status == 200U); + } + } + } + WHEN("the refresh token is revoked") + { + auto const response = post_oauth_form(rt, oauth_revoke_path, + { + {"token", session.refresh_token}, + {"token_type_hint", "refresh_token" }, + }); + THEN("the access token stops working too") + { + REQUIRE(response.status == 200U); + // Spec MUST: both tokens of the session are revoked. + REQUIRE(whoami_status(rt, session.access_token) == 401U); + } + } + WHEN("the token parameter is missing") + { + auto const response = post_oauth_form(rt, oauth_revoke_path, + { + {"token_type_hint", "access_token"} + }); + THEN("the answer is 400 with error details") + { + // Spec SHOULD: "For other errors, the server returns a 400 Bad Request response with error details". + REQUIRE(response.status == 400U); + REQUIRE(oauth_error(response) == "invalid_request"); + } + } + } +} diff --git a/tests/conformance/test_route_query_conformance.cpp b/tests/conformance/test_route_query_conformance.cpp index 60e427244..3885d48dd 100644 --- a/tests/conformance/test_route_query_conformance.cpp +++ b/tests/conformance/test_route_query_conformance.cpp @@ -109,7 +109,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", ""}, @@ -118,6 +118,8 @@ SCENARIO("every client route that matched its whole target answers a request wit {"POST", "/_merovingian/oauth2/register", "{}"}, {"GET", "/_merovingian/oauth2/authorize", ""}, {"POST", "/_merovingian/oauth2/authorize", ""}, + {"POST", "/_merovingian/oauth2/token", ""}, + {"POST", "/_merovingian/oauth2/revoke", ""}, {"POST", "/_matrix/client/v3/register/email/requestToken", "{}"}, {"POST", "/_matrix/client/v3/register/msisdn/requestToken", "{}"}, {"POST", "/_matrix/client/v3/register", "{}"}, diff --git a/tests/integration/test_oauth_token_flow.cpp b/tests/integration/test_oauth_token_flow.cpp new file mode 100644 index 000000000..b35392cad --- /dev/null +++ b/tests/integration/test_oauth_token_flow.cpp @@ -0,0 +1,821 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// `POST /_merovingian/oauth2/token` and `POST /_merovingian/oauth2/revoke` through the client-server dispatcher, after +// a real sign-in through the authorisation pages: the authorization code grant and its one transaction, a replayed or +// mismatched code, the refresh grant and the separation of the OAuth and legacy sessions, revocation, and the +// User-Interactive Authentication endpoints answering an OAuth session (ADR-0791 to ADR-0795). + +#include "../support/AppserviceTestConfig.hpp" +#include "../support/CrossSigningFixture.hpp" +#include "../support/OAuthAuthorizationSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "../support/OAuthTokenSupport.hpp" +#include "../support/RegistrationToken.hpp" +#include "../support/TestAppservice.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentOAuthSession.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace db = merovingian::database; +namespace hs = merovingian::homeserver; + +constexpr auto alice_password = std::string_view{"AlicePass99!x"}; +constexpr auto alice_id = std::string_view{"@alice:example.org"}; +constexpr auto account_url = std::string_view{"https://matrix.example.org/_merovingian/account"}; + +[[nodiscard]] auto token_config(bool oauth_enabled = true) -> merovingian::config::Config +{ + auto config = oauth_registration_config(oauth_enabled); + config.server().server_name = "example.org"; + enable_token_registration(config.security()); + return config; +} + +// A runtime with alice and a registered web client named "Test App". +struct Fixture final +{ + hs::ClientServerStartResult started; + std::string client_id; +}; + +[[nodiscard]] auto make_fixture( + std::string_view client_extra = R"(,"client_name":"Test App","grant_types":["authorization_code","refresh_token"])") + -> Fixture +{ + auto started = hs::start_client_server(token_config()); + REQUIRE(started.started); + REQUIRE( + hs::register_local_user(started.runtime.homeserver, "alice", alice_password, std::string{registration_token}) + .ok); + auto client_id = register_oauth_web_client(started.runtime, client_extra); + REQUIRE_FALSE(client_id.empty()); + return {std::move(started), std::move(client_id)}; +} + +[[nodiscard]] auto send(hs::ClientServerRuntime& rt, std::string method, std::string target, std::string token, + std::string body = {}) -> hs::LocalHttpResponse +{ + return hs::handle_client_server_request(rt, + {std::move(method), std::move(target), std::move(token), std::move(body)}, + /*can_wait=*/false) + .response; +} + +[[nodiscard]] auto whoami_status(hs::ClientServerRuntime& rt, std::string const& token) -> std::uint16_t +{ + return static_cast(send(rt, "GET", "/_matrix/client/v3/account/whoami", token).status); +} + +[[nodiscard]] auto oauth_error(hs::LocalHttpResponse const& response) -> std::string +{ + auto const body = parse_object(response.body); + auto const* error = string_member(body, "error"); + return error == nullptr ? std::string{} : *error; +} + +[[nodiscard]] auto legacy_login(hs::ClientServerRuntime& rt, std::string_view device_id) -> hs::LocalHttpResponse +{ + return send( + rt, "POST", "/_matrix/client/v3/login", {}, + R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":"@alice:example.org"},"password":")" + + std::string{alice_password} + R"(","device_id":")" + std::string{device_id} + R"(","refresh_token":true})"); +} + +[[nodiscard]] auto member(hs::LocalHttpResponse const& response, std::string_view name) -> std::string +{ + auto const body = parse_object(response.body); + auto const* value = string_member(body, name); + return value == nullptr ? std::string{} : *value; +} + +[[nodiscard]] auto oauth_row(hs::ClientServerRuntime const& rt, std::string_view device_id) + -> db::PersistentOAuthSession const* +{ + return db::find_oauth_session(rt.homeserver.database.persistent_store, alice_id, device_id); +} + +[[nodiscard]] auto holds_device(hs::ClientServerRuntime const& rt, std::string_view device_id) -> bool +{ + return db::has_user_device(rt.homeserver.database.persistent_store, alice_id, device_id); +} + +[[nodiscard]] auto audit_count(hs::ClientServerRuntime const& rt, std::string_view event_type) -> std::size_t +{ + return static_cast(std::ranges::count_if(rt.homeserver.database.audit_events, [&](auto const& event) { + return event.event_type == event_type; + })); +} + +auto set_locked(hs::ClientServerRuntime& rt, bool locked) -> void +{ + auto& users = rt.homeserver.database.users; + auto const user = std::ranges::find_if(users, [](auto const& candidate) { + return candidate.user_id == alice_id; + }); + REQUIRE(user != users.end()); + user->locked = locked; +} + +} // namespace + +SCENARIO("An authorization code is exchanged for a session the client-server API accepts", + "[integration][oauth][oauth-token]") +{ + GIVEN("alice and a registered web client named Test App") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const code = obtain_oauth_code(rt, fixture.client_id, "alice", alice_password); + REQUIRE_FALSE(code.empty()); + + WHEN("the client redeems the code in one request") + { + auto const before = db::committed_transaction_count(rt.homeserver.database.persistent_store); + auto const response = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + auto const after = db::committed_transaction_count(rt.homeserver.database.persistent_store); + auto const answer = read_token_answer(response); + + THEN("it is given a Bearer access token with a finite lifetime, a refresh token and the scope") + { + REQUIRE(answer.ok); + CHECK(answer.token_type == "Bearer"); + CHECK(answer.expires_in == 3600); + CHECK(answer.scope == oauth_test_scope); + CHECK(answer.access_token != answer.refresh_token); + CHECK(response_header(response, "Cache-Control") == "no-store"); + CHECK(response_header(response, "Content-Type") == "application/json"); + } + + THEN("the device, both tokens, the OAuth session and its audit row were written in one transaction") + { + // One commit for the grant; the other two are the self device-list change POST /login also records + // after its own write (the sync stream position, then the change row). "A grant that cannot be stored + // leaves nothing ..." shows the grant's rows stand or fall together. + CHECK(after - before == 3U); + CHECK(audit_count(rt, "oauth.session.granted") == 1U); + REQUIRE(holds_device(rt, oauth_test_device)); + auto const* row = oauth_row(rt, oauth_test_device); + REQUIRE(row != nullptr); + CHECK(row->client_id == fixture.client_id); + CHECK(row->scope == oauth_test_scope); + CHECK(audit_count(rt, "oauth.session.granted") == 1U); + } + + THEN("the access token authenticates as alice on the device, which is named after the client") + { + auto const whoami = send(rt, "GET", "/_matrix/client/v3/account/whoami", answer.access_token); + REQUIRE(whoami.status == 200U); + CHECK(member(whoami, "user_id") == alice_id); + CHECK(member(whoami, "device_id") == oauth_test_device); + auto const device = send(rt, "GET", "/_matrix/client/v3/devices/" + std::string{oauth_test_device}, + answer.access_token); + REQUIRE(device.status == 200U); + CHECK(member(device, "display_name") == "Test App"); + CHECK(send(rt, "GET", "/_matrix/client/v3/sync?timeout=0", answer.access_token).status == 200U); + } + + AND_WHEN("the same code is presented again") + { + auto const replay = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + + THEN("it is refused and the session it produced is ended") + { + REQUIRE(replay.status == 400U); + CHECK(oauth_error(replay) == "invalid_grant"); + CHECK(whoami_status(rt, answer.access_token) == 401U); + CHECK_FALSE(holds_device(rt, oauth_test_device)); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + auto const refreshed = post_oauth_form( + rt, oauth_token_path, refresh_grant_fields(fixture.client_id, answer.refresh_token)); + CHECK(oauth_error(refreshed) == "invalid_grant"); + } + } + } + } +} + +SCENARIO("A replayed code ends only the session it produced", "[integration][oauth][oauth-token][oauth-replay]") +{ + GIVEN("a session from a first code, replaced on the same device by a second code's session") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const first_code = obtain_oauth_code(rt, fixture.client_id, "alice", alice_password); + REQUIRE_FALSE(first_code.empty()); + auto const first = + read_token_answer(post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, first_code))); + REQUIRE(first.ok); + auto const second = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + REQUIRE(second.ok); + + WHEN("the first code is presented again") + { + auto const replay = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, first_code)); + + THEN("it is refused, the first session's tokens are gone and the second session is untouched") + { + REQUIRE(replay.status == 400U); + CHECK(oauth_error(replay) == "invalid_grant"); + CHECK(whoami_status(rt, first.access_token) == 401U); + CHECK(whoami_status(rt, second.access_token) == 200U); + CHECK(oauth_row(rt, oauth_test_device) != nullptr); + } + } + } +} + +SCENARIO("A code presented with the wrong redirect URI, verifier or client is spent", + "[integration][oauth][oauth-token]") +{ + GIVEN("alice, the web client and a second registered client") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const other_client = register_oauth_web_client( + rt, R"(,"client_name":"Other","grant_types":["authorization_code","refresh_token"])"); + REQUIRE_FALSE(other_client.empty()); + REQUIRE(other_client != fixture.client_id); + + auto const check_spent = [&](OAuthFields const& wrong, std::string const& code) { + auto const refused = post_oauth_form(rt, oauth_token_path, wrong); + REQUIRE(refused.status == 400U); + CHECK(oauth_error(refused) == "invalid_grant"); + auto const retried = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + CHECK(retried.status == 400U); + CHECK(oauth_error(retried) == "invalid_grant"); + CHECK_FALSE(holds_device(rt, oauth_test_device)); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + }; + + WHEN("the redirect URI differs by one byte") + { + auto const code = obtain_oauth_code(rt, fixture.client_id, "alice", alice_password); + REQUIRE_FALSE(code.empty()); + THEN("the code is refused and cannot be used afterwards") + { + check_spent(with_parameter(code_grant_fields(fixture.client_id, code), "redirect_uri", + std::string{oauth_client_redirect} + "/"), + code); + } + } + WHEN("the verifier does not match the challenge") + { + auto const code = obtain_oauth_code(rt, fixture.client_id, "alice", alice_password); + REQUIRE_FALSE(code.empty()); + THEN("the code is refused and cannot be used afterwards") + { + check_spent( + with_parameter(code_grant_fields(fixture.client_id, code), "code_verifier", std::string(43U, 'a')), + code); + } + } + WHEN("another registered client presents it") + { + auto const code = obtain_oauth_code(rt, fixture.client_id, "alice", alice_password); + REQUIRE_FALSE(code.empty()); + THEN("the code is refused and cannot be used afterwards") + { + check_spent(code_grant_fields(other_client, code), code); + } + } + WHEN("the verifier is malformed") + { + auto const code = obtain_oauth_code(rt, fixture.client_id, "alice", alice_password); + REQUIRE_FALSE(code.empty()); + auto const refused = + post_oauth_form(rt, oauth_token_path, + with_parameter(code_grant_fields(fixture.client_id, code), "code_verifier", "short")); + auto const retried = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + THEN("the request is malformed and the code is not spent") + { + CHECK(refused.status == 400U); + CHECK(oauth_error(refused) == "invalid_request"); + CHECK(read_token_answer(retried).ok); + } + } + WHEN("an unknown code is presented") + { + auto const refused = + post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, std::string(64U, 'f'))); + THEN("it is invalid_grant") + { + CHECK(refused.status == 400U); + CHECK(oauth_error(refused) == "invalid_grant"); + } + } + } +} + +SCENARIO("A grant that cannot be stored leaves nothing, and an account that cannot sign in gets no session", + "[integration][oauth][oauth-token]") +{ + GIVEN("alice, the web client and a fresh code") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const code = obtain_oauth_code(rt, fixture.client_id, "alice", alice_password); + REQUIRE_FALSE(code.empty()); + + WHEN("the transaction fails") + { + db::force_next_persist_failures(rt.homeserver.database.persistent_store, 1U); + auto const response = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + THEN("the answer is server_error and no device, token or session row exists") + { + REQUIRE(response.status == 500U); + CHECK(oauth_error(response) == "server_error"); + CHECK_FALSE(holds_device(rt, oauth_test_device)); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + CHECK(audit_count(rt, "oauth.session.granted") == 0U); + } + } + WHEN("the account is locked between the consent and the token request") + { + set_locked(rt, true); + auto const response = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + THEN("the grant is refused and nothing is written") + { + REQUIRE(response.status == 400U); + CHECK(oauth_error(response) == "invalid_grant"); + CHECK_FALSE(holds_device(rt, oauth_test_device)); + } + } + } +} + +SCENARIO( + "A grant on a device alice already holds replaces its tokens, and a legacy login on it drops the OAuth session", + "[integration][oauth][oauth-token]") +{ + GIVEN("alice signed in with a password on the device the OAuth request names") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const legacy = legacy_login(rt, oauth_test_device); + REQUIRE(legacy.status == 200U); + auto const legacy_access = member(legacy, "access_token"); + + WHEN("an OAuth grant is made for the same device") + { + auto const answer = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + THEN("the device's earlier token stops working and the OAuth one works") + { + REQUIRE(answer.ok); + CHECK(whoami_status(rt, legacy_access) == 401U); + CHECK(whoami_status(rt, answer.access_token) == 200U); + CHECK(oauth_row(rt, oauth_test_device) != nullptr); + } + + AND_WHEN("alice then logs in on that device with POST /login") + { + auto const again = legacy_login(rt, oauth_test_device); + THEN("the device is a legacy session again: no OAuth row, and the OAuth refresh token is refused") + { + REQUIRE(again.status == 200U); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + auto const refreshed = post_oauth_form( + rt, oauth_token_path, refresh_grant_fields(fixture.client_id, answer.refresh_token)); + CHECK(oauth_error(refreshed) == "invalid_grant"); + CHECK(whoami_status(rt, member(again, "access_token")) == 200U); + } + } + } + } +} + +SCENARIO("The refresh grant rotates an OAuth session's tokens and only an OAuth session's", + "[integration][oauth][oauth-token][oauth-refresh]") +{ + GIVEN("alice signed in through OAuth and, on another device, through POST /login") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const session = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + REQUIRE(session.ok); + auto const legacy = legacy_login(rt, "LEGACYDEV"); + REQUIRE(legacy.status == 200U); + auto const legacy_refresh = member(legacy, "refresh_token"); + REQUIRE_FALSE(legacy_refresh.empty()); + + WHEN("the client refreshes its session") + { + auto const response = + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(fixture.client_id, session.refresh_token)); + auto const rotated = read_token_answer(response); + THEN("new tokens with the granted scope are issued, and they work") + { + REQUIRE(rotated.ok); + CHECK(rotated.token_type == "Bearer"); + CHECK(rotated.expires_in == 3600); + CHECK(rotated.scope == oauth_test_scope); + CHECK(rotated.access_token != session.access_token); + CHECK(rotated.refresh_token != session.refresh_token); + CHECK(whoami_status(rt, rotated.access_token) == 200U); + CHECK(oauth_row(rt, oauth_test_device) != nullptr); + } + } + WHEN("another registered client presents the refresh token") + { + auto const other_client = register_oauth_web_client( + rt, R"(,"client_name":"Other","grant_types":["authorization_code","refresh_token"])"); + REQUIRE_FALSE(other_client.empty()); + auto const refused = + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(other_client, session.refresh_token)); + auto const after = + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(fixture.client_id, session.refresh_token)); + THEN("it is invalid_grant and nothing was rotated") + { + CHECK(refused.status == 400U); + CHECK(oauth_error(refused) == "invalid_grant"); + CHECK(read_token_answer(after).ok); + } + } + WHEN("the legacy session's refresh token is presented to the OAuth token endpoint") + { + auto const refused = + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(fixture.client_id, legacy_refresh)); + auto const legacy_after = + send(rt, "POST", "/_matrix/client/v3/refresh", {}, R"({"refresh_token":")" + legacy_refresh + R"("})"); + THEN("it is invalid_grant and the legacy session still refreshes through POST /refresh") + { + CHECK(refused.status == 400U); + CHECK(oauth_error(refused) == "invalid_grant"); + CHECK(legacy_after.status == 200U); + } + } + WHEN("the OAuth refresh token is presented to POST /refresh") + { + auto const refused = send(rt, "POST", "/_matrix/client/v3/refresh", {}, + R"({"refresh_token":")" + session.refresh_token + R"("})"); + auto const after = + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(fixture.client_id, session.refresh_token)); + THEN("it is an unknown token there, and the OAuth session is unchanged") + { + CHECK(refused.status == 401U); + CHECK(member(refused, "errcode") == "M_UNKNOWN_TOKEN"); + CHECK(read_token_answer(after).ok); + } + } + WHEN("the refresh request lacks the client ID or names an unknown client") + { + auto const missing = post_oauth_form(rt, oauth_token_path, + { + {"grant_type", "refresh_token" }, + {"refresh_token", session.refresh_token}, + }); + auto const unknown = + post_oauth_form(rt, oauth_token_path, refresh_grant_fields("not-a-client", session.refresh_token)); + THEN("they are invalid_request and invalid_client") + { + CHECK(oauth_error(missing) == "invalid_request"); + CHECK(oauth_error(unknown) == "invalid_client"); + } + } + } +} + +SCENARIO("The token endpoint refuses malformed requests and client credentials", + "[integration][oauth][oauth-token][oauth-token-refusals]") +{ + GIVEN("a registered web client") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const body = form_encode(code_grant_fields(fixture.client_id, std::string(64U, 'f'))); + + WHEN("the body is JSON, a client_secret is sent, Basic credentials are sent, or the grant type is unknown") + { + auto const json = + post_oauth_body(rt, oauth_token_path, R"({"grant_type":"authorization_code"})", "application/json"); + auto const secret = post_oauth_body(rt, oauth_token_path, body + "&client_secret=s3cret"); + auto const basic = post_oauth_body(rt, oauth_token_path, body, oauth_form_type, + { + {"Authorization", "Basic YTpi"} + }); + auto const grant = post_oauth_form(rt, oauth_token_path, + { + {"grant_type", "password" }, + {"client_id", fixture.client_id}, + }); + auto const repeated = post_oauth_body(rt, oauth_token_path, body + "&code=again"); + auto const charset = + post_oauth_body(rt, oauth_token_path, body, "application/x-www-form-urlencoded; charset=UTF-8"); + + THEN("each answer is the OAuth error RFC 6749 names, with no-store and CORS headers") + { + CHECK(json.status == 400U); + CHECK(oauth_error(json) == "invalid_request"); + CHECK(secret.status == 400U); + CHECK(oauth_error(secret) == "invalid_client"); + CHECK(basic.status == 401U); + CHECK(oauth_error(basic) == "invalid_client"); + CHECK(response_header(basic, "WWW-Authenticate") == "Basic"); + CHECK(grant.status == 400U); + CHECK(oauth_error(grant) == "unsupported_grant_type"); + CHECK(oauth_error(repeated) == "invalid_request"); + // The charset parameter is accepted; the code is unknown. + CHECK(oauth_error(charset) == "invalid_grant"); + for (auto const* response : {&json, &secret, &basic, &grant}) + { + CHECK(response_header(*response, "Cache-Control") == "no-store"); + CHECK_FALSE(response_header(*response, "Access-Control-Allow-Origin").empty()); + } + } + } + WHEN("a client registered without the refresh_token grant asks for it") + { + auto const code_only = register_oauth_web_client(rt, R"(,"grant_types":["authorization_code"])"); + REQUIRE_FALSE(code_only.empty()); + auto const refused = + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(code_only, std::string(64U, 'a'))); + THEN("it is unauthorized_client") + { + CHECK(oauth_error(refused) == "unauthorized_client"); + } + } + WHEN("the endpoints are called with GET") + { + auto const token = send(rt, "GET", std::string{oauth_token_path}, {}); + auto const revoke = send(rt, "GET", std::string{oauth_revoke_path}, {}); + THEN("the method is not allowed") + { + CHECK(token.status == 405U); + CHECK(revoke.status == 405U); + } + } + } + + GIVEN("a server with the OAuth 2.0 API off") + { + auto started = hs::start_client_server(token_config(false)); + REQUIRE(started.started); + WHEN("the token and revocation endpoints are called") + { + auto const token = post_oauth_form(started.runtime, oauth_token_path, + { + {"grant_type", "refresh_token"} + }); + auto const revoke = post_oauth_form(started.runtime, oauth_revoke_path, + { + {"token", "x"} + }); + THEN("neither route exists") + { + CHECK(token.status == 404U); + CHECK(member(token, "errcode") == "M_UNRECOGNIZED"); + CHECK(revoke.status == 404U); + CHECK(member(revoke, "errcode") == "M_UNRECOGNIZED"); + } + } + } +} + +SCENARIO("Revocation ends the session a token belongs to, as POST /logout does", "[integration][oauth][oauth-revoke]") +{ + GIVEN("alice signed in through OAuth") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const session = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + REQUIRE(session.ok); + + auto const check_ended = [&](hs::LocalHttpResponse const& response) { + REQUIRE(response.status == 200U); + CHECK(response.body.empty()); + CHECK(response_header(response, "Cache-Control") == "no-store"); + CHECK(whoami_status(rt, session.access_token) == 401U); + CHECK_FALSE(holds_device(rt, oauth_test_device)); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + CHECK(oauth_error(post_oauth_form(rt, oauth_token_path, + refresh_grant_fields(fixture.client_id, session.refresh_token))) == + "invalid_grant"); + CHECK(audit_count(rt, "oauth.session.revoked") == 1U); + }; + + WHEN("the access token is revoked with its hint") + { + auto const response = post_oauth_form(rt, oauth_revoke_path, + { + {"token", session.access_token}, + {"token_type_hint", "access_token" }, + {"client_id", fixture.client_id }, + }); + THEN("the session and its device are gone") + { + check_ended(response); + } + } + WHEN("the refresh token is revoked with an unknown hint and no client ID") + { + auto const response = post_oauth_form(rt, oauth_revoke_path, + { + {"token", session.refresh_token}, + {"token_type_hint", "something_else" }, + }); + THEN("the session and its device are gone") + { + check_ended(response); + } + } + WHEN("an unknown token is revoked, or the same token twice") + { + auto const unknown = post_oauth_form(rt, oauth_revoke_path, + { + {"token", std::string(68U, 'a')} + }); + auto const first = post_oauth_form(rt, oauth_revoke_path, + { + {"token", session.access_token} + }); + auto const second = post_oauth_form(rt, oauth_revoke_path, + { + {"token", session.access_token} + }); + THEN("each answer is 200 with an empty body") + { + CHECK(unknown.status == 200U); + CHECK(unknown.body.empty()); + CHECK(first.status == 200U); + CHECK(second.status == 200U); + CHECK(second.body.empty()); + } + } + WHEN("the token is missing, the body is JSON, or a client_secret is sent") + { + auto const missing = post_oauth_form(rt, oauth_revoke_path, + { + {"token_type_hint", "access_token"} + }); + auto const json = post_oauth_body(rt, oauth_revoke_path, R"({"token":"x"})", "application/json"); + auto const secret = post_oauth_form(rt, oauth_revoke_path, + { + {"token", session.access_token}, + {"client_secret", "s" } + }); + THEN("each is refused and the session remains") + { + CHECK(oauth_error(missing) == "invalid_request"); + CHECK(oauth_error(json) == "invalid_request"); + CHECK(oauth_error(secret) == "invalid_client"); + CHECK(whoami_status(rt, session.access_token) == 200U); + } + } + } + + GIVEN("alice signed in with POST /login") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const legacy = legacy_login(rt, "LEGACYDEV"); + REQUIRE(legacy.status == 200U); + WHEN("its access token is revoked") + { + auto const response = post_oauth_form(rt, oauth_revoke_path, + { + {"token", member(legacy, "access_token")} + }); + THEN("the legacy session ends too") + { + CHECK(response.status == 200U); + CHECK(whoami_status(rt, member(legacy, "access_token")) == 401U); + CHECK_FALSE(holds_device(rt, "LEGACYDEV")); + } + } + } +} + +SCENARIO("Every User-Interactive Authentication endpoint refuses an OAuth session with the account page", + "[integration][oauth][oauth-uia]") +{ + GIVEN("alice signed in through OAuth and on another device with a password") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + rt.homeserver.config.security().login_token.enabled = true; + auto const session = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + REQUIRE(session.ok); + auto const legacy = legacy_login(rt, "LEGACYDEV"); + REQUIRE(legacy.status == 200U); + auto const legacy_token = member(legacy, "access_token"); + + struct Endpoint final + { + std::string_view method; + std::string_view path; + }; + constexpr auto endpoints = std::array{ + { + {"POST", "/_matrix/client/v1/login/get_token"}, + {"POST", "/_matrix/client/v3/account/password"}, + {"POST", "/_matrix/client/v3/account/deactivate"}, + {"POST", "/_matrix/client/v3/account/3pid/add"}, + {"DELETE", "/_matrix/client/v3/devices/LEGACYDEV"}, + {"POST", "/_matrix/client/v3/delete_devices"}, + } + }; + auto const body = std::string{R"({"new_password":"AnotherPass77!y","client_secret":"cs","sid":"sid",)" + R"("devices":["LEGACYDEV"]})"}; + + WHEN("the OAuth session calls each of them") + { + THEN("each answers 403 M_FORBIDDEN naming the account page, and nothing changes") + { + for (auto const& endpoint : endpoints) + { + INFO(endpoint.method << ' ' << endpoint.path); + auto const response = + send(rt, std::string{endpoint.method}, std::string{endpoint.path}, session.access_token, body); + CHECK(response.status == 403U); + CHECK(member(response, "errcode") == "M_FORBIDDEN"); + CHECK(member(response, "error").find(account_url) != std::string::npos); + } + CHECK(holds_device(rt, "LEGACYDEV")); + CHECK(whoami_status(rt, session.access_token) == 200U); + } + } + WHEN("the password session calls each of them without auth") + { + THEN("each answers the 401 UIA challenge as before") + { + for (auto const& endpoint : endpoints) + { + INFO(endpoint.method << ' ' << endpoint.path); + auto const response = + send(rt, std::string{endpoint.method}, std::string{endpoint.path}, legacy_token, body); + CHECK(response.status == 401U); + CHECK(response.body.find("\"flows\"") != std::string::npos); + } + } + } + WHEN("the OAuth session uploads its first cross-signing keys, then tries to replace the master key") + { + auto const upload = [&](std::string const& members) { + return send(rt, "POST", "/_matrix/client/v3/keys/device_signing/upload", session.access_token, + "{" + members + "}"); + }; + auto const first = upload(make_cross_signing_set(std::string{alice_id}).selected_members(true, true, true)); + auto const replacement = upload(make_cross_signing_set(std::string{alice_id}).master_member()); + THEN("the first upload needs no UIA and the replacement is refused with the account page") + { + CHECK(first.status == 200U); + CHECK(replacement.status == 403U); + CHECK(member(replacement, "errcode") == "M_FORBIDDEN"); + CHECK(member(replacement, "error").find(account_url) != std::string::npos); + } + } + } +} + +SCENARIO("An application service replaces cross-signing keys without User-Interactive Authentication", + "[integration][oauth][oauth-uia][appservice]") +{ + GIVEN("an application service whose namespace holds alice, who already holds a master key") + { + auto bridge = TestAppservice{.id = "bridge", .users_regex = "@alice:example.org"}; + auto config = appservice_test_config({bridge}); + config.server().server_name = "example.org"; + config.server().public_baseurl = "https://matrix.example.org"; + config.server().oauth.enabled = true; + auto started = hs::start_client_server(config); + REQUIRE(started.started); + auto& rt = started.runtime; + REQUIRE(hs::register_local_user(rt.homeserver, "alice", alice_password, std::string{registration_token}).ok); + auto const target = std::string{"/_matrix/client/v3/keys/device_signing/upload?user_id=@alice:example.org"}; + REQUIRE(send(rt, "POST", target, bridge.as_token(), + "{" + make_cross_signing_set(std::string{alice_id}).master_member() + "}") + .status == 200U); + + WHEN("it uploads a different master key with no auth") + { + auto const response = send(rt, "POST", target, bridge.as_token(), + "{" + make_cross_signing_set(std::string{alice_id}).master_member() + "}"); + THEN("it is stored: the spec exempts application services") + { + CHECK(response.status == 200U); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index 93170652d..319a3e044 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -448,6 +448,7 @@ shell = find_program('sh') 'unit/test_oauth_redirect_uri.cpp', 'unit/test_oauth_scope.cpp', 'unit/test_oauth_server_metadata.cpp', + 'unit/test_oauth_token_rules.cpp', 'unit/test_http_request_limits.cpp', 'unit/test_inbound_ingestion.cpp', 'unit/test_join_routing.cpp', @@ -651,6 +652,7 @@ shell = find_program('sh') 'conformance/test_oauth_metadata_conformance.cpp', 'conformance/test_oauth_authorization_conformance.cpp', 'conformance/test_oauth_client_registration_conformance.cpp', + 'conformance/test_oauth_token_conformance.cpp', 'conformance/test_open_registration_conformance.cpp', 'conformance/test_account_lifecycle_conformance.cpp', 'conformance/test_device_lifecycle_conformance.cpp', @@ -865,6 +867,7 @@ shell = find_program('sh') 'integration/test_oauth_log_query_flow.cpp', 'integration/test_oauth_metadata_flow.cpp', 'integration/test_oauth_password_login_flow.cpp', + 'integration/test_oauth_token_flow.cpp', 'integration/test_observability_flow.cpp', 'integration/test_operator_admin_flow.cpp', 'integration/test_admin_masquerade_refusal_flow.cpp', diff --git a/tests/support/AGENTS.md b/tests/support/AGENTS.md index 6a2a84b62..38d323270 100644 --- a/tests/support/AGENTS.md +++ b/tests/support/AGENTS.md @@ -32,6 +32,7 @@ Shared test utilities used across unit, conformance, and integration tests. | `EduRelayChannels.hpp` / `EduRelayContext.hpp` | `EduRelayChannels` and `make_edu_relay_channels()`: a main and a worker `IpcChannel` over a real authenticated transport, for the downstream EDU relay fixtures. Creates a `socketpair`, so it is an I/O exception | | `InMemoryDatabaseConfig.hpp` | `in_memory_database_config()`: selects the process-local database for tests that do not exercise persistence (production config parsing does not expose it) | | `OAuthRegistrationSupport.hpp` | `oauth_registration_config()` (OAuth on or off, `public_baseurl`, in-memory database, shared master key), `post_client_registration()` and `response_header()` for the OAuth 2.0 client registration conformance and integration scenarios | +| `OAuthTokenSupport.hpp` | The token and revocation paths, an RFC 7636 verifier, `oauth_both_grant_types`, `obtain_oauth_code` (authorise, sign in, approve), `post_oauth_body` / `post_oauth_form` (form-encoded, from the client's origin), the grant fields (`code_grant_fields`, `refresh_grant_fields`), `read_token_answer` and `oauth_sign_in` (a code redeemed into a session) | | `OAuthAuthorizationSupport.hpp` | A registered web client, the authorisation request's parameters (`oauth_authorize_parameters`, `with_parameter`), `get_authorize` / `post_authorize` as a browser sends them (`BrowserContext`: address, cookie, `Origin`, `Sec-Fetch-Site`, content type), and readers for the pending identifier, the cookie and a redirect's parameters (`redirect_answer`) | | `E2eeCapsSupport.hpp` | `caps_config()` and a logged-in-user helper for the CSAZ-10 per-user end-to-end key and filter cap scenarios | | `MembershipFixtureSupport.hpp` | Helpers that build membership PDUs (send_join, send_leave, send_knock bodies) with the `auth_events` and `prev_events` a real server would send (ADR-0064 phase B2) | diff --git a/tests/support/OAuthTokenSupport.hpp b/tests/support/OAuthTokenSupport.hpp new file mode 100644 index 000000000..199d5f4ea --- /dev/null +++ b/tests/support/OAuthTokenSupport.hpp @@ -0,0 +1,174 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +// Shared by the OAuth 2.0 token and revocation conformance and integration scenarios: an authorization code obtained +// through the real pages (sign in, approve), the token and revocation requests as a client sends them, and a reader +// for the token answer. + +#include "JsonTestSupport.hpp" +#include "OAuthAuthorizationSupport.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/http/Header.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::tests +{ + +inline constexpr auto oauth_token_path = std::string_view{"/_merovingian/oauth2/token"}; +inline constexpr auto oauth_revoke_path = std::string_view{"/_merovingian/oauth2/revoke"}; +// RFC 7636 appendix B: the verifier of oauth_test_challenge. +inline constexpr auto oauth_test_verifier = std::string_view{"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"}; +inline constexpr auto oauth_form_type = std::string_view{"application/x-www-form-urlencoded"}; + +using OAuthFields = std::vector>; + +// The scope of the authorisation request for `device_id`: the client-server API and that one device. +[[nodiscard]] inline auto oauth_scope_for_device(std::string_view device_id) -> std::string +{ + return "urn:matrix:client:api:* urn:matrix:client:device:" + std::string{device_id}; +} + +// Signs `username` in through the authorisation pages and approves: the code the redirect carries, or empty when any +// step did not answer as a successful flow does. `parameters` is the authorisation request (by default +// oauth_authorize_parameters, whose device is oauth_test_device). +[[nodiscard]] inline auto obtain_oauth_code(homeserver::ClientServerRuntime& runtime, std::string_view client_id, + std::string_view username, std::string_view password, + std::optional parameters = std::nullopt) -> std::string +{ + auto browser = BrowserContext{}; + auto const page = get_authorize(runtime, parameters.value_or(oauth_authorize_parameters(client_id)), browser); + auto const pending = pending_of(page); + browser.cookie = cookie_of(page); + if (page.status != 200U || pending.empty() || browser.cookie.empty()) + { + return {}; + } + auto const consent = post_authorize(runtime, + { + {"pending", pending }, + {"action", "login" }, + {"username", std::string{username}}, + {"password", std::string{password}}, + }, + browser); + if (consent.status != 200U) + { + return {}; + } + auto const approved = post_authorize(runtime, + { + {"pending", pending }, + {"action", "approve"}, + }, + browser); + auto const answer = redirect_answer(approved); + auto const code = answer.parameters.find("code"); + return approved.status == 303U && code != answer.parameters.end() ? code->second : std::string{}; +} + +// The metadata members (leading comma) of a client that may use both grants the token endpoint serves: the spec's +// client metadata MUST list authorization_code and refresh_token, and the refresh grant refuses a client without it. +inline constexpr auto oauth_both_grant_types = + std::string_view{R"(,"grant_types":["authorization_code","refresh_token"])"}; + +// POST `body` to `path` with `content_type` (none when empty) and the extra `headers`, from the client's web origin +// (https://app.example.com), as a browser-based client sends it. +[[nodiscard]] inline auto post_oauth_body(homeserver::ClientServerRuntime& runtime, std::string_view path, + std::string body, std::string_view content_type = oauth_form_type, + std::vector headers = {}, std::string method = "POST") + -> homeserver::LocalHttpResponse +{ + auto request = homeserver::LocalHttpRequest{std::move(method), std::string{path}, {}, std::move(body)}; + request.remote_addr = "198.51.100.30"; + request.headers = std::move(headers); + request.headers.push_back({"Origin", "https://app.example.com"}); + if (!content_type.empty()) + { + request.headers.push_back({"Content-Type", std::string{content_type}}); + } + return homeserver::handle_client_server_request(runtime, request, /*can_wait=*/false).response; +} + +[[nodiscard]] inline auto post_oauth_form(homeserver::ClientServerRuntime& runtime, std::string_view path, + OAuthFields const& fields) -> homeserver::LocalHttpResponse +{ + return post_oauth_body(runtime, path, form_encode(fields)); +} + +// The fields of an authorization code grant for `code`, as the client that asked for it sends them. +[[nodiscard]] inline auto code_grant_fields(std::string_view client_id, std::string_view code) -> OAuthFields +{ + return { + {"grant_type", "authorization_code" }, + {"code", std::string{code} }, + {"redirect_uri", std::string{oauth_client_redirect}}, + {"client_id", std::string{client_id} }, + {"code_verifier", std::string{oauth_test_verifier} }, + }; +} + +[[nodiscard]] inline auto refresh_grant_fields(std::string_view client_id, std::string_view refresh_token) + -> OAuthFields +{ + return { + {"grant_type", "refresh_token" }, + {"refresh_token", std::string{refresh_token}}, + {"client_id", std::string{client_id} }, + }; +} + +// What a 200 token answer carries; `ok` is false when a member is missing or of the wrong type. +struct OAuthTokenAnswer final +{ + bool ok{false}; + std::string access_token{}; + std::string refresh_token{}; + std::string token_type{}; + std::string scope{}; + std::int64_t expires_in{0}; +}; + +[[nodiscard]] inline auto read_token_answer(homeserver::LocalHttpResponse const& response) -> OAuthTokenAnswer +{ + auto answer = OAuthTokenAnswer{}; + if (response.status != 200U) + { + return answer; + } + auto const body = parse_object(response.body); + auto const* access = string_member(body, "access_token"); + auto const* refresh = string_member(body, "refresh_token"); + auto const* type = string_member(body, "token_type"); + auto const* scope = string_member(body, "scope"); + auto const* expires_in = int_member(body, "expires_in"); + if (access == nullptr || refresh == nullptr || type == nullptr || scope == nullptr || expires_in == nullptr) + { + return answer; + } + answer = {true, *access, *refresh, *type, *scope, *expires_in}; + return answer; +} + +// A whole sign-in: a code for `username` and its redemption at the token endpoint. +[[nodiscard]] inline auto oauth_sign_in(homeserver::ClientServerRuntime& runtime, std::string_view client_id, + std::string_view username, std::string_view password, + std::optional parameters = std::nullopt) -> OAuthTokenAnswer +{ + auto const code = obtain_oauth_code(runtime, client_id, username, password, std::move(parameters)); + if (code.empty()) + { + return {}; + } + return read_token_answer(post_oauth_form(runtime, oauth_token_path, code_grant_fields(client_id, code))); +} + +} // namespace merovingian::tests diff --git a/tests/unit/test_oauth_authorization_code_store.cpp b/tests/unit/test_oauth_authorization_code_store.cpp index 4661bc3e3..c157dbb2d 100644 --- a/tests/unit/test_oauth_authorization_code_store.cpp +++ b/tests/unit/test_oauth_authorization_code_store.cpp @@ -254,3 +254,99 @@ SCENARIO("The unredeemed codes of a client are counted without a scan", "[oauth] } } } + +SCENARIO("A replay names the session the first redemption issued, and only once one was recorded", + "[oauth][oauth-code][oauth-replay]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("a store holding one code that has been redeemed") + { + auto store = AuthorizationCodeStore{}; + auto const code = code_of(store.issue(grant_for("client-a", "DEVICEA"), start_ms)); + REQUIRE(store.redeem(code, start_ms + 1U).outcome == Outcome::fresh); + + WHEN("it is presented again before any session was recorded") + { + auto const replay = store.redeem(code, start_ms + 2U); + + THEN("the replay names the client and no session") + { + REQUIRE(replay.outcome == Outcome::replayed); + CHECK(replay.client_id == "client-a"); + CHECK_FALSE(replay.session_created_at_ms.has_value()); + } + } + + WHEN("the session its redemption issued is recorded and the code is presented again") + { + auto const recorded = store.record_issued_session(code, start_ms + 7U, start_ms + 2U); + auto const again = store.record_issued_session(code, start_ms + 9U, start_ms + 3U); + auto const replay = store.redeem(code, start_ms + 4U); + + THEN("the replay names that session, and a second record changes nothing") + { + CHECK(recorded); + CHECK_FALSE(again); + REQUIRE(replay.outcome == Outcome::replayed); + REQUIRE(replay.session_created_at_ms.has_value()); + CHECK(*replay.session_created_at_ms == start_ms + 7U); + } + } + + WHEN("a session is recorded after the code expired") + { + auto const recorded = + store.record_issued_session(code, start_ms + 7U, start_ms + AuthorizationCodeStore::lifetime_ms); + + THEN("nothing is recorded") + { + CHECK_FALSE(recorded); + } + } + } + + GIVEN("a store holding one code that was never redeemed") + { + auto store = AuthorizationCodeStore{}; + auto const code = code_of(store.issue(grant_for("client-a", "DEVICEA"), start_ms)); + + WHEN("a session is recorded for it, or for a code never issued") + { + auto const unredeemed = store.record_issued_session(code, start_ms + 7U, start_ms + 1U); + auto const unknown = store.record_issued_session(std::string(64U, 'a'), start_ms + 7U, start_ms + 1U); + + THEN("nothing is recorded, and the code is still fresh") + { + CHECK_FALSE(unredeemed); + CHECK_FALSE(unknown); + CHECK(store.redeem(code, start_ms + 2U).outcome == Outcome::fresh); + } + } + } +} + +SCENARIO("The creation times a code store gives OAuth sessions strictly increase", "[oauth][oauth-code][oauth-replay]") +{ + GIVEN("an empty store") + { + auto store = AuthorizationCodeStore{}; + + WHEN("it is asked three times within one millisecond, then once later, then once with the clock back") + { + auto const first = store.next_session_created_at_ms(start_ms); + auto const second = store.next_session_created_at_ms(start_ms); + auto const third = store.next_session_created_at_ms(start_ms); + auto const later = store.next_session_created_at_ms(start_ms + 100U); + auto const backwards = store.next_session_created_at_ms(start_ms); + + THEN("each value is the clock or one past the last, whichever is greater") + { + CHECK(first == start_ms); + CHECK(second == start_ms + 1U); + CHECK(third == start_ms + 2U); + CHECK(later == start_ms + 100U); + CHECK(backwards == start_ms + 101U); + } + } + } +} diff --git a/tests/unit/test_oauth_token_rules.cpp b/tests/unit/test_oauth_token_rules.cpp new file mode 100644 index 000000000..65e1dab99 --- /dev/null +++ b/tests/unit/test_oauth_token_rules.cpp @@ -0,0 +1,93 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// The pure rules of the OAuth 2.0 token and revocation endpoints (ADR-0791): which form content types they read, and +// the access token lifetime and `expires_in` they answer with. + +#include "merovingian/oauth/AccessTokenLifetime.hpp" +#include "merovingian/oauth/FormContentType.hpp" + +#include + +#include +#include + +using merovingian::oauth::access_token_lifetime_ms; +using merovingian::oauth::api_form_content_type_is_accepted; +using merovingian::oauth::default_access_token_lifetime_ms; +using merovingian::oauth::expires_in_seconds; +using merovingian::oauth::page_form_content_type_is_accepted; + +SCENARIO("A token request is a form body, with no parameter or only charset=utf-8", "[oauth][token-rules]") +{ + GIVEN("the content types a client may send") + { + WHEN("each is judged for a token or revocation request") + { + THEN("the form type alone, in any case, and with a UTF-8 charset are accepted") + { + CHECK(api_form_content_type_is_accepted("application/x-www-form-urlencoded")); + CHECK(api_form_content_type_is_accepted("Application/X-WWW-Form-URLEncoded")); + CHECK(api_form_content_type_is_accepted("application/x-www-form-urlencoded;charset=UTF-8")); + CHECK(api_form_content_type_is_accepted("application/x-www-form-urlencoded; charset=utf-8")); + CHECK(api_form_content_type_is_accepted("application/x-www-form-urlencoded; charset=\"UTF-8\"")); + } + + THEN("another type, another charset, another parameter or nothing at all is refused") + { + CHECK_FALSE(api_form_content_type_is_accepted("")); + CHECK_FALSE(api_form_content_type_is_accepted("application/json")); + CHECK_FALSE(api_form_content_type_is_accepted("multipart/form-data")); + CHECK_FALSE(api_form_content_type_is_accepted("application/x-www-form-urlencoded; charset=latin1")); + CHECK_FALSE(api_form_content_type_is_accepted("application/x-www-form-urlencoded; boundary=x")); + CHECK_FALSE(api_form_content_type_is_accepted("application/x-www-form-urlencoded; charset=utf-8; x=y")); + CHECK_FALSE(api_form_content_type_is_accepted("application/x-www-form-urlencodedx")); + CHECK_FALSE(api_form_content_type_is_accepted("application/x-www-form-urlencoded;")); + } + } + + WHEN("each is judged for a page's form post") + { + THEN("only the type alone, in any case, is accepted") + { + CHECK(page_form_content_type_is_accepted("application/x-www-form-urlencoded")); + CHECK(page_form_content_type_is_accepted("APPLICATION/X-WWW-FORM-URLENCODED")); + CHECK_FALSE(page_form_content_type_is_accepted("application/x-www-form-urlencoded;charset=UTF-8")); + CHECK_FALSE(page_form_content_type_is_accepted("application/json")); + CHECK_FALSE(page_form_content_type_is_accepted("")); + } + } + } +} + +SCENARIO("An OAuth access token always expires, and expires_in is its lifetime in whole seconds", + "[oauth][token-rules]") +{ + GIVEN("the configured access token lifetimes") + { + WHEN("the lifetime is configured, or configured as 0 (no expiry for a legacy token)") + { + auto const configured = access_token_lifetime_ms(300'000); + auto const unlimited = access_token_lifetime_ms(0); + + THEN("a configured lifetime is used, and 0 is replaced by one hour") + { + CHECK(configured == 300'000); + CHECK(unlimited == default_access_token_lifetime_ms); + CHECK(default_access_token_lifetime_ms == 3'600'000); + } + } + + WHEN("expires_in is computed") + { + THEN("it is rounded down to whole seconds, at least 1 for a positive lifetime") + { + CHECK(expires_in_seconds(3'600'000) == 3600); + CHECK(expires_in_seconds(1'999) == 1); + CHECK(expires_in_seconds(1) == 1); + CHECK(expires_in_seconds(0) == 0); + CHECK(expires_in_seconds(std::int64_t{2'592'000'000}) == 2'592'000); + } + } + } +} From bc55dd7a3800a6183ce73965998c881d42f39203 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 08:17:49 +0000 Subject: [PATCH 16/42] Serve the OAuth 2.0 account pages and the m.oauth UIA stage (ADR-0796 to ADR-0798) /_merovingian/account signs a user in with their password into a fixed 15-minute in-memory session (hashed secret, __Host- cookie with SameSite=Strict, a form token per session, Origin checked first), and serves the overview, devices, device sign-out, password change, deactivation and cross-signing reset approval. Each action calls the client API's own function. An OAuth session's replacing cross-signing upload is offered the m.oauth stage, completed by a one-use approval given on the account page. The server metadata names the account management URI and its actions. Co-Authored-By: Claude Opus 5.5 --- .../merovingian/homeserver/AccountPage.hpp | 44 + .../merovingian/homeserver/AccountSession.hpp | 22 + .../homeserver/AccountSessionStore.hpp | 113 +++ .../merovingian/homeserver/AuthService.hpp | 7 + .../homeserver/ClientDeviceSessions.hpp | 28 +- .../homeserver/CrossSigningResetApprovals.hpp | 77 ++ .../homeserver/HomeserverRuntime.hpp | 7 + .../homeserver/OAuthPageResponse.hpp | 54 ++ .../merovingian/oauth/AccountDeviceRow.hpp | 26 + .../merovingian/oauth/AccountPageFrame.hpp | 26 + include/merovingian/oauth/AccountPages.hpp | 103 +++ .../merovingian/oauth/AccountSignInInput.hpp | 32 + .../oauth/ServerMetadataOptions.hpp | 4 +- src/homeserver/AccountPage.cpp | 824 ++++++++++++++++++ src/homeserver/AccountSessionStore.cpp | 172 ++++ src/homeserver/AuthService.cpp | 177 ++-- src/homeserver/ClientServerRuntime.cpp | 336 +++++-- src/homeserver/CrossSigningResetApprovals.cpp | 90 ++ src/homeserver/OAuthAuthorization.cpp | 148 +--- src/homeserver/OAuthPageResponse.cpp | 106 +++ src/homeserver/meson.build | 4 + src/oauth/AccountPages.cpp | 369 ++++++++ src/oauth/meson.build | 1 + ...t_oauth_account_management_conformance.cpp | 260 ++++++ .../test_route_query_conformance.cpp | 4 +- .../test_oauth_account_pages_flow.cpp | 758 ++++++++++++++++ .../integration/test_oauth_metadata_flow.cpp | 16 +- tests/integration/test_oauth_token_flow.cpp | 11 +- tests/meson.build | 5 + tests/support/OAuthAccountPageSupport.hpp | 145 +++ tests/unit/test_oauth_account_pages.cpp | 265 ++++++ .../unit/test_oauth_account_session_store.cpp | 201 +++++ ...st_oauth_cross_signing_reset_approvals.cpp | 160 ++++ 33 files changed, 4323 insertions(+), 272 deletions(-) create mode 100644 include/merovingian/homeserver/AccountPage.hpp create mode 100644 include/merovingian/homeserver/AccountSession.hpp create mode 100644 include/merovingian/homeserver/AccountSessionStore.hpp create mode 100644 include/merovingian/homeserver/CrossSigningResetApprovals.hpp create mode 100644 include/merovingian/homeserver/OAuthPageResponse.hpp create mode 100644 include/merovingian/oauth/AccountDeviceRow.hpp create mode 100644 include/merovingian/oauth/AccountPageFrame.hpp create mode 100644 include/merovingian/oauth/AccountPages.hpp create mode 100644 include/merovingian/oauth/AccountSignInInput.hpp create mode 100644 src/homeserver/AccountPage.cpp create mode 100644 src/homeserver/AccountSessionStore.cpp create mode 100644 src/homeserver/CrossSigningResetApprovals.cpp create mode 100644 src/homeserver/OAuthPageResponse.cpp create mode 100644 src/oauth/AccountPages.cpp create mode 100644 tests/conformance/test_oauth_account_management_conformance.cpp create mode 100644 tests/integration/test_oauth_account_pages_flow.cpp create mode 100644 tests/support/OAuthAccountPageSupport.hpp create mode 100644 tests/unit/test_oauth_account_pages.cpp create mode 100644 tests/unit/test_oauth_account_session_store.cpp create mode 100644 tests/unit/test_oauth_cross_signing_reset_approvals.cpp diff --git a/include/merovingian/homeserver/AccountPage.hpp b/include/merovingian/homeserver/AccountPage.hpp new file mode 100644 index 000000000..c9fe8e991 --- /dev/null +++ b/include/merovingian/homeserver/AccountPage.hpp @@ -0,0 +1,44 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/homeserver/RuntimeMutex.hpp" + +#include +#include + +namespace merovingian::homeserver +{ + +struct ClientServerRuntime; +struct LocalHttpRequest; + +// The cookie of an account-page session (ADR-0796): `__Host-`, `Secure`, `HttpOnly`, `SameSite=Strict`, for the fixed +// lifetime of the session. Strict, unlike the authorisation cookie: nothing reaches these pages from another site with +// a reason to carry it, so a link from elsewhere opens the sign-in form. +inline constexpr auto account_cookie_name = std::string_view{"__Host-mv-account"}; +inline constexpr auto account_cookie_max_age_seconds = std::uint32_t{900U}; + +// `GET` and `POST /_merovingian/account` (spec "Account management"; plan P6, phase 8; ADR-0796 to ADR-0798). The +// dispatcher has matched the path and the method and checked that `server.oauth.enabled` is true. `guard` is the +// dispatcher's lock on runtime.mutex, released only by a deactivation's identity-server unbinds. Every answer is an +// HTML page or a redirect marked `LocalHttpResponse::page`, with `oauth::page_headers()`, so it carries no CORS header. +// +// `GET` reads `action` (one of the six spec actions; anything else shows the overview) and, for the two device actions, +// `device_id` (only one `auth::device_id_is_valid` accepts). Without a live session it shows the sign-in form, which +// carries both in hidden fields; with one, the page for the action. +// +// `POST` is refused unless `oauth::form_post_origin_is_accepted` accepts its `Origin` and `Sec-Fetch-Site`, before +// anything is read. The sign-in form (`action=sign_in`) needs nothing else; it verifies the password with +// `verify_password_login` (the throttle `/login` uses) and always issues a fresh session, answering 303 to the page +// asked for. Every other form needs the session cookie and the session's form token, compared in constant time. Each +// action calls the service function the client API calls: `delete_device_and_announce`, +// `change_password_on_account_page` (the core of the password reset), `deactivate_user_account` with +// `finish_account_deactivation`. A session whose user no longer passes `account_sign_in_gate` ends at once. +// +// Logs `user_id` and the action only, never a password, a cookie, a form token or the query. +[[nodiscard]] auto handle_account_page(ClientServerRuntime& rt, RuntimeLock& guard, LocalHttpRequest const& request) + -> LocalHttpResponse; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/AccountSession.hpp b/include/merovingian/homeserver/AccountSession.hpp new file mode 100644 index 000000000..2e2c413cf --- /dev/null +++ b/include/merovingian/homeserver/AccountSession.hpp @@ -0,0 +1,22 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::homeserver +{ + +// One signed-in session of the account pages (`AccountSessionStore`, ADR-0796): whose it is and when it ends. The +// session's secret is not here: the store keeps only its hash. +struct AccountSession final +{ + // The user whose password was verified when the session began. + std::string user_id{}; + std::uint64_t created_at_ms{0U}; + // `created_at_ms` plus the fixed lifetime; never extended. + std::uint64_t expires_at_ms{0U}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/AccountSessionStore.hpp b/include/merovingian/homeserver/AccountSessionStore.hpp new file mode 100644 index 000000000..0f6ee6d5c --- /dev/null +++ b/include/merovingian/homeserver/AccountSessionStore.hpp @@ -0,0 +1,113 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/StateGroupKeyHash.hpp" +#include "merovingian/homeserver/AccountSession.hpp" +#include "merovingian/homeserver/HashedSecretTable.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +// The signed-in sessions of the account pages at `/_merovingian/account` (plan P6, ADR-0796). In memory only: a session +// lives 15 minutes from sign-in and is never extended, and a restart signs every browser out of the pages and nothing +// else. +// +// A session is held under the hash of a fresh 256-bit secret (`make_oauth_secret`), which `create` returns once for the +// `__Host-mv-account` cookie; the secret itself is never kept. Every form of a signed-in page also carries the +// session's form token (`form_token`): a hash of the secret under its own label, so it is bound to the session, is not +// the cookie value, and cannot be derived from what the store keeps. +// +// Bounded: `max_sessions` in all and `max_sessions_per_user` per user. A sign-in first purges the expired sessions; a +// user at the per-user cap then loses their own oldest session (never another user's), and at the total cap the +// sign-in is refused. Expired sessions are removed at the start of every operation, soonest first, at the cost of the +// sessions removed. An expired session behaves as absent. +// +// Every operation takes the current time, so a test needs no clock. Not thread-safe: `runtime.mutex` serialises every +// use (the store is `HomeserverRuntime::account_sessions`). +class AccountSessionStore final +{ +public: + // A session lives this long from sign-in and is never extended: long enough to delete a device or change a + // password, short enough that a browser left open is not a standing credential (plan P6). + static constexpr auto lifetime_ms = std::uint64_t{900'000U}; + // At most this many sessions in all: a session is about a hundred bytes, so the store stays well under a MiB, and + // each one needed a verified password, which the login throttle and the Argon2id budget already limit. + static constexpr auto max_sessions = std::size_t{4096U}; + // At most this many per user: a person has a browser or two open on these pages at once; a fifth sign-in replaces + // that user's oldest, so a user cannot fill the store and nobody can end another user's session by signing in. + static constexpr auto max_sessions_per_user = std::size_t{4U}; + + enum class Refusal : std::uint8_t + { + // `max_sessions` live sessions are held, none of them the user's. + store_full, + // The user ID is empty. + no_user, + // The random source or the hash failed. + secret_unavailable, + }; + + // A fresh session for `user_id`, valid for `lifetime_ms` from `now_ms`. Returns its secret (64 hex digits), once, + // or why nothing was stored. Never reuses a secret a request supplied. + [[nodiscard]] auto create(std::string_view user_id, std::uint64_t now_ms) -> std::variant; + + // A copy of the live session `secret` names, or nullopt. Compared in constant time through the digest index. + [[nodiscard]] auto find(std::string_view secret, std::uint64_t now_ms) -> std::optional; + + // Ends the session `secret` names. False when there is none. + auto end(std::string_view secret, std::uint64_t now_ms) -> bool; + + // Ends every session of `user_id` (sign-out of a deactivated account, a password change). Returns how many ended. + // Costs the user's own sessions, at most `max_sessions_per_user`. + auto end_user(std::string_view user_id) -> std::size_t; + + // The form token of the session `secret` names: BLAKE2b-256 of a fixed label and the secret, as hex. nullopt when + // hashing fails or the secret is empty. + [[nodiscard]] static auto form_token(std::string_view secret) -> std::optional; + + // Whether `offered` is the form token of `secret`, compared in constant time. + [[nodiscard]] static auto form_token_matches(std::string_view secret, std::string_view offered) -> bool; + + // How many live sessions `user_id` holds, after removing the expired ones. + [[nodiscard]] auto live_count_for_user(std::string_view user_id, std::uint64_t now_ms) -> std::size_t; + + // Removes every session whose lifetime ended at or before `now_ms`. + auto erase_expired(std::uint64_t now_ms) -> void; + + // Sessions held, expired ones not yet removed included. + [[nodiscard]] auto size() const noexcept -> std::size_t; + +private: + struct Entry final + { + AccountSession session{}; + // The key the table holds the entry under, kept here too so the per-user index can be updated when the + // table hands an expired entry back. + std::string secret_hash{}; + }; + + template + using KeyedBy = std::unordered_map>; + + // Drops an entry that left the table from the per-user index. + auto forget(Entry const& entry) -> void; + // Removes the session held under `secret_hash` from the table and the index. + auto erase_hash(std::string_view secret_hash) -> bool; + + HashedSecretTable m_sessions{}; + // user_id -> the hashes of the user's sessions, oldest first. At most `max_sessions_per_user` each. + KeyedBy> m_hashes_by_user{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/AuthService.hpp b/include/merovingian/homeserver/AuthService.hpp index cd8cb7ff6..99b101ad5 100644 --- a/include/merovingian/homeserver/AuthService.hpp +++ b/include/merovingian/homeserver/AuthService.hpp @@ -180,6 +180,13 @@ namespace merovingian::homeserver // that is no longer active. [[nodiscard]] auto reset_local_user_password(HomeserverRuntime& runtime, std::string_view user_id, std::string_view new_password, bool logout_devices) -> OperationResult; +// Sets a new password for `user_id`, signed in to the account page with the current password re-verified (ADR-0798). +// The same change as `reset_local_user_password` with `logout_devices`, the client API's default: a page holds no +// device, so every access token, refresh token, OpenID token and pusher of the account goes, and no device is deleted. +// Audited as `auth.password_changed`. Like every password change, it ends the user's account-page sessions and any +// cross-signing reset approval. +[[nodiscard]] auto change_password_on_account_page(HomeserverRuntime& runtime, std::string_view user_id, + std::string_view new_password) -> OperationResult; [[nodiscard]] auto verify_local_user_password(HomeserverRuntime& runtime, std::string_view access_token, std::string_view password) -> PasswordVerificationResult; // Returns true when the presented access token exists in the session store but diff --git a/include/merovingian/homeserver/ClientDeviceSessions.hpp b/include/merovingian/homeserver/ClientDeviceSessions.hpp index bc9b08c3b..3e95e3a38 100644 --- a/include/merovingian/homeserver/ClientDeviceSessions.hpp +++ b/include/merovingian/homeserver/ClientDeviceSessions.hpp @@ -3,8 +3,11 @@ #pragma once #include "merovingian/homeserver/OperationResult.hpp" +#include "merovingian/homeserver/RuntimeMutex.hpp" #include "merovingian/homeserver/SignedInDevice.hpp" +#include +#include #include namespace merovingian::homeserver @@ -13,9 +16,10 @@ namespace merovingian::homeserver struct ClientServerRuntime; // Module-internal (src/AGENTS.md "Where module-local helpers go"): the client-server side of a session's start and end, -// shared by POST /login, POST /logout and the OAuth 2.0 token and revocation endpoints. Both are defined in -// ClientServerRuntime.cpp, beside the device-list helpers they use. The caller holds runtime.homeserver.mutex; neither -// releases it or makes a network call (EDUs are queued). +// shared by POST /login, POST /logout, device deletion, deactivation, the OAuth 2.0 token and revocation endpoints and +// the account page. All are defined in ClientServerRuntime.cpp, beside the device-list helpers they use. The caller +// holds runtime.homeserver.mutex; only finish_account_deactivation releases it or makes a network call (EDUs are +// queued). // After a session was granted on (`user_id`, `device_id`): a device missing from the runtime's device list is added // with `display_name`, and for SignedInDevice::new_session the user's own device-list change is recorded, as POST @@ -33,4 +37,22 @@ auto remember_signed_in_device(ClientServerRuntime& runtime, std::string_view us std::string_view device_id, std::string_view audit_event) -> OperationResult; +// Deletes the user's device `device_id` exactly as DELETE /devices/{deviceId} does after its User-Interactive +// Authentication (shared with the account page, ADR-0796): the servers sharing a room are read first, then +// delete_local_device revokes the device's tokens, deletes it (its `oauth_sessions` row with it) and audits +// `device.deleted`; on success the device leaves the runtime's list, local users who share a room are told, and each +// remote server is sent `m.device_list_update` with `deleted: true`. A device that is not the user's is 404, whoever +// holds it. +[[nodiscard]] auto delete_device_and_announce(ClientServerRuntime& runtime, std::string_view user_id, + std::string_view device_id) -> OperationResult; + +// What POST /account/deactivate does once deactivate_user_account succeeded (shared with the account page): the +// user's login tokens go and every 3PID bound at an identity server is unbound, `requested_id_server` when given, +// otherwise each binding's own. Releases `guard` (the caller's lock on runtime.mutex) around each identity-server +// call, so the caller trusts nothing it read before. Returns the spec's `id_server_unbind_result`. +[[nodiscard]] auto finish_account_deactivation(ClientServerRuntime& runtime, RuntimeLock& guard, + std::string_view user_id, + std::optional const& requested_id_server) + -> std::string_view; + } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/CrossSigningResetApprovals.hpp b/include/merovingian/homeserver/CrossSigningResetApprovals.hpp new file mode 100644 index 000000000..536fdfd08 --- /dev/null +++ b/include/merovingian/homeserver/CrossSigningResetApprovals.hpp @@ -0,0 +1,77 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/StateGroupKeyHash.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +// The cross-signing reset approvals the account page grants (`org.matrix.cross_signing_reset`, ADR-0797): one per user, +// in memory, valid `lifetime_ms` from the approval, and spent by exactly one replacing upload of +// `POST /keys/device_signing/upload` from an OAuth session (the `m.oauth` UIA stage). A restart forgets every approval, +// which only means the user approves again. +// +// The upload takes the approval (`take`) before it stores the keys and gives it back (`restore`) when the store failed, +// so a failed store does not spend it and two concurrent uploads cannot both use one approval: `runtime.mutex` +// serialises every use, and the second upload finds nothing to take. +// +// Bounded at `max_approvals`; expired approvals are removed at the start of every operation, soonest first, at the cost +// of those removed. Every operation takes the current time, so a test needs no clock. +class CrossSigningResetApprovals final +{ +public: + // The spec's example ("the user can approve the reset for a limited time") leaves the time open; ten minutes lets a + // person switch back to the application and retry, and is short enough that a forgotten approval lapses. + static constexpr auto lifetime_ms = std::uint64_t{600'000U}; + // At most this many users with an approval at once. Each one needed a signed-in account-page session, itself + // bounded at 4096 (`AccountSessionStore::max_sessions`). + static constexpr auto max_approvals = std::size_t{4096U}; + + // Records an approval for `user_id` valid until `now_ms + lifetime_ms`, replacing any the user holds. False, with + // nothing recorded, for an empty user ID or at `max_approvals` approvals of other users. + [[nodiscard]] auto approve(std::string_view user_id, std::uint64_t now_ms) -> bool; + + // Whether `user_id` holds a live approval. + [[nodiscard]] auto holds(std::string_view user_id, std::uint64_t now_ms) -> bool; + + // Removes the user's live approval and returns its expiry, or nullopt when there is none. + [[nodiscard]] auto take(std::string_view user_id, std::uint64_t now_ms) -> std::optional; + + // Gives back an approval `take` returned, unless it has expired since or the user approved again meanwhile. + auto restore(std::string_view user_id, std::uint64_t expires_at_ms, std::uint64_t now_ms) -> void; + + // Removes the user's approval, live or not (a password change, a deactivation). + auto withdraw(std::string_view user_id) -> void; + + // Removes every approval whose lifetime ended at or before `now_ms`. + auto erase_expired(std::uint64_t now_ms) -> void; + + [[nodiscard]] auto size() const noexcept -> std::size_t; + +private: + using ExpiryIndex = std::multimap; + + struct Approval final + { + std::uint64_t expires_at_ms{0U}; + ExpiryIndex::iterator expiry{}; + }; + + auto record(std::string_view user_id, std::uint64_t expires_at_ms) -> void; + + std::unordered_map> m_by_user{}; + // expiry -> user, soonest first, so `erase_expired` costs only what it removes. + ExpiryIndex m_by_expiry{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/HomeserverRuntime.hpp b/include/merovingian/homeserver/HomeserverRuntime.hpp index 98b66e822..9ade7b68c 100644 --- a/include/merovingian/homeserver/HomeserverRuntime.hpp +++ b/include/merovingian/homeserver/HomeserverRuntime.hpp @@ -17,6 +17,7 @@ #include "merovingian/federation/FederationRuntimeState.hpp" #include "merovingian/federation/RemoteDeviceListCache.hpp" #include "merovingian/federation/ServerDiscoveryNetwork.hpp" +#include "merovingian/homeserver/AccountSessionStore.hpp" #include "merovingian/homeserver/ActiveServerSigningKeySecret.hpp" #include "merovingian/homeserver/AppserviceDeliveryBackoff.hpp" #include "merovingian/homeserver/AppserviceEphemeralQueue.hpp" @@ -24,6 +25,7 @@ #include "merovingian/homeserver/AuthorizationCodeStore.hpp" #include "merovingian/homeserver/ClientOutboundProxy.hpp" #include "merovingian/homeserver/ClientOutboundProxyPolicy.hpp" +#include "merovingian/homeserver/CrossSigningResetApprovals.hpp" #include "merovingian/homeserver/InboundTypingUser.hpp" #include "merovingian/homeserver/LocalDatabase.hpp" #include "merovingian/homeserver/LocalRoom.hpp" @@ -240,6 +242,11 @@ struct HomeserverRuntime final // either names is never deleted (`oauth_client_has_pending_authorisation`). PendingAuthorisationStore oauth_pending_authorisations{}; AuthorizationCodeStore oauth_codes{}; + // The signed-in sessions of the account pages at `/_merovingian/account` (plan P6, ADR-0796) and the cross-signing + // reset approvals they grant (ADR-0797). In memory only, bounded. Here, not on `ClientServerRuntime`, because a + // password change, a password reset and a deactivation (`AuthService.cpp`) end them. Guarded by `mutex`. + AccountSessionStore account_sessions{}; + CrossSigningResetApprovals cross_signing_reset_approvals{}; // Application Service API registry (Matrix v1.19). Built once at // start_runtime() time from config.appservice().registration_files and // never mutated afterward — every request reads it as an immutable, diff --git a/include/merovingian/homeserver/OAuthPageResponse.hpp b/include/merovingian/homeserver/OAuthPageResponse.hpp new file mode 100644 index 000000000..7a3b5de85 --- /dev/null +++ b/include/merovingian/homeserver/OAuthPageResponse.hpp @@ -0,0 +1,54 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/oauth/HtmlText.hpp" +#include "merovingian/oauth/Page.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +// Module-internal: what the server's own HTML pages (the OAuth 2.0 authorisation pages, `OAuthAuthorization.cpp`, and +// the account pages, `AccountPage.cpp`) share to answer and to read a browser's request. Not public API. + +// A page answer: the rendered page with `headers` (normally `oauth::page_headers()`, ADR-0772, ADR-0784) and the page +// mark, so the boundary adds no CORS header and `wrap()` leaves it alone (ADR-0785). +[[nodiscard]] auto oauth_page_response(std::uint16_t status, oauth::Page const& page, + std::vector> headers) -> LocalHttpResponse; + +// `page` with `status` and `oauth::page_headers()`. +[[nodiscard]] auto oauth_plain_page(std::uint16_t status, oauth::Page const& page) -> LocalHttpResponse; + +// `oauth::error_page(title, message)` with `status` and `oauth::page_headers()`. +[[nodiscard]] auto oauth_error_page_response(std::uint16_t status, oauth::HtmlText title, + oauth::HtmlText const& message) -> LocalHttpResponse; + +// The query of a request target, without the `?`; empty when there is none. +[[nodiscard]] auto request_target_query(std::string_view target) noexcept -> std::string_view; + +// The one value of header `name`, or nullopt when it is absent or sent more than once (a repeated `Origin`, +// `Sec-Fetch-Site`, `Content-Type` or `Cookie` is treated as absent, never resolved). +[[nodiscard]] auto single_request_header(LocalHttpRequest const& request, std::string_view name) + -> std::optional; + +// Whether `value` has the form `make_oauth_secret` mints: 64 lower-case hex digits. +[[nodiscard]] auto is_oauth_secret_text(std::string_view value) noexcept -> bool; + +// The value of cookie `cookie_name` when the request carries exactly one `Cookie` header, it parses, and the value has +// the form of a minted secret (`is_oauth_secret_text`). Anything else is nullopt: never a value to look up. +[[nodiscard]] auto request_secret_cookie(LocalHttpRequest const& request, std::string_view cookie_name) + -> std::optional; + +// `Retry-After` in whole seconds, rounded up, at least one. +[[nodiscard]] auto retry_after_seconds(std::uint32_t retry_after_ms) noexcept -> std::uint32_t; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/oauth/AccountDeviceRow.hpp b/include/merovingian/oauth/AccountDeviceRow.hpp new file mode 100644 index 000000000..d0fb52650 --- /dev/null +++ b/include/merovingian/oauth/AccountDeviceRow.hpp @@ -0,0 +1,26 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::oauth +{ + +// One device as the account pages show it. Every view is borrowed for the call. The display name and the client name +// are chosen by a client: the page builder escapes them and shows fixed text for one it cannot show. +struct AccountDeviceRow final +{ + // A device ID that passed `auth::device_id_is_valid`. + std::string_view device_id{}; + // The device's display name, empty when none was set. + std::string_view display_name{}; + // Whether the device signed in through the OAuth 2.0 API (it has an `oauth_sessions` row). + bool oauth_session{false}; + // For an OAuth device, the registered `client_name` of its client, or nullopt when the client registered none or + // is no longer registered. + std::optional client_name{}; +}; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/AccountPageFrame.hpp b/include/merovingian/oauth/AccountPageFrame.hpp new file mode 100644 index 000000000..70b37f172 --- /dev/null +++ b/include/merovingian/oauth/AccountPageFrame.hpp @@ -0,0 +1,26 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::oauth +{ + +// What every page of a signed-in account-page session shows and carries (`AccountPages.hpp`). Every view is borrowed +// for the call. Each string is escaped by the page builder; one that cannot be shown is replaced by fixed text. +struct AccountPageFrame final +{ + // `server.server_name`, named at the top of the page. + std::string_view server_name{}; + // The signed-in user, named at the top of the page. + std::string_view user_id{}; + // The session's form token, the hidden `form_token` field of every form. A page whose token cannot be shown holds + // no form. + std::string_view form_token{}; + // `OAuthBaseUrl::url(account_path)`: the base of every link between the pages, which add only `?action=` and + // `&device_id=`. + std::string_view account_url{}; +}; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/AccountPages.hpp b/include/merovingian/oauth/AccountPages.hpp new file mode 100644 index 000000000..7cd099cdf --- /dev/null +++ b/include/merovingian/oauth/AccountPages.hpp @@ -0,0 +1,103 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/oauth/AccountDeviceRow.hpp" +#include "merovingian/oauth/AccountPageFrame.hpp" +#include "merovingian/oauth/AccountSignInInput.hpp" +#include "merovingian/oauth/HtmlName.hpp" +#include "merovingian/oauth/HtmlText.hpp" +#include "merovingian/oauth/Page.hpp" + +#include +#include +#include +#include +#include + +namespace merovingian::oauth +{ + +// The account pages at `/_merovingian/account` (spec "Account management", plan phase 8): pure functions of their +// inputs, built only with the Page renderer, English and fixed text (ADR-0763). The handler sends each with +// `page_headers()`. +// +// Every form posts to `account_path` with a submit button named `action`; every form of a signed-in page also carries +// the session's form token in the hidden field `form_token`. The names below are the ones the handler reads. + +// The spec's account management actions (spec "Account management URL actions"), all of which these pages implement. +inline constexpr auto account_action_profile = std::string_view{"org.matrix.profile"}; +inline constexpr auto account_action_devices_list = std::string_view{"org.matrix.devices_list"}; +inline constexpr auto account_action_device_view = std::string_view{"org.matrix.device_view"}; +inline constexpr auto account_action_device_delete = std::string_view{"org.matrix.device_delete"}; +inline constexpr auto account_action_account_deactivate = std::string_view{"org.matrix.account_deactivate"}; +inline constexpr auto account_action_cross_signing_reset = std::string_view{"org.matrix.cross_signing_reset"}; + +// The six actions in the order `account_management_actions_supported` advertises them. Nothing that is not +// implemented is listed. +[[nodiscard]] constexpr auto account_management_actions() noexcept -> std::array +{ + return {account_action_profile, account_action_devices_list, account_action_device_view, + account_action_device_delete, account_action_account_deactivate, account_action_cross_signing_reset}; +} + +// The `action` that one of the six names, or nullopt for anything else (absent, unknown, a different case). +[[nodiscard]] auto account_management_action(std::optional action) noexcept + -> std::optional; +// Whether `action` takes the `device_id` parameter (spec: "Actions which don't support the device ID will ignore it"). +[[nodiscard]] auto account_action_takes_device(std::string_view action) noexcept -> bool; + +// The address of the account page for `action` and, when given, `device_id`: `account_url` (`OAuthBaseUrl::url( +// account_path)`) with `?action=` and `&device_id=`, each value percent-encoded (`percent_encode_redirect_value`) so +// nothing in it can change the query's shape. Every link between the pages, the redirect after sign-in and the +// `m.oauth` stage's URL are built here. +[[nodiscard]] auto account_action_address(std::string_view account_url, std::string_view action, + std::optional device_id = std::nullopt) -> std::string; + +// Form field names. +inline constexpr auto account_form_token_field = HtmlName{"form_token"}; +inline constexpr auto account_next_action_field = HtmlName{"next_action"}; +inline constexpr auto account_next_device_field = HtmlName{"next_device_id"}; +inline constexpr auto account_device_field = HtmlName{"device_id"}; +inline constexpr auto account_current_password_field = HtmlName{"current_password"}; +inline constexpr auto account_new_password_field = HtmlName{"new_password"}; +inline constexpr auto account_new_password_confirm_field = HtmlName{"new_password_confirm"}; +// The values of `action` the forms post. +inline constexpr auto account_post_sign_in = HtmlName{"sign_in"}; +inline constexpr auto account_post_sign_out = HtmlName{"sign_out"}; +inline constexpr auto account_post_show_password = HtmlName{"show_password"}; +inline constexpr auto account_post_change_password = HtmlName{"change_password"}; +inline constexpr auto account_post_delete_device = HtmlName{"delete_device"}; +inline constexpr auto account_post_deactivate = HtmlName{"deactivate"}; +inline constexpr auto account_post_approve_reset = HtmlName{"approve_cross_signing_reset"}; + +// The sign-in form: username and password, and the requested action and device in hidden fields. +[[nodiscard]] auto account_sign_in_page(AccountSignInInput const& input) -> Page; +// The overview (`org.matrix.profile`): the user ID and display name (read only, none when `display_name` is nullopt or +// cannot be shown), links to the other pages and the button that opens the password form. +[[nodiscard]] auto account_overview_page(AccountPageFrame const& frame, std::optional display_name) + -> Page; +// `org.matrix.devices_list`: one entry per device with its ID, display name and, for an OAuth device, its client's +// name, each linking to its device page. +[[nodiscard]] auto account_devices_page(AccountPageFrame const& frame, std::span devices) + -> Page; +// `org.matrix.device_view`: one device's details and a link to sign it out. +[[nodiscard]] auto account_device_page(AccountPageFrame const& frame, AccountDeviceRow const& device) -> Page; +// `org.matrix.device_delete`: a confirmation naming the device, with the button that signs it out. +[[nodiscard]] auto account_device_delete_page(AccountPageFrame const& frame, AccountDeviceRow const& device) -> Page; +// The answer for a device ID the user does not hold: the same page whether it never existed or is another user's. +[[nodiscard]] auto account_unknown_device_page(AccountPageFrame const& frame) -> Page; +// The password form: the current password, the new one twice, and what a change does to the other sessions. +[[nodiscard]] auto account_password_page(AccountPageFrame const& frame, std::optional const& error) -> Page; +// `org.matrix.account_deactivate`: what deactivation does, and the password again. +[[nodiscard]] auto account_deactivate_page(AccountPageFrame const& frame, std::optional const& error) -> Page; +// `org.matrix.cross_signing_reset`: that the user's encryption identity will be replaced and other users will see them +// as unverified, and the approve button. +[[nodiscard]] auto account_cross_signing_reset_page(AccountPageFrame const& frame) -> Page; +// A signed-in page that reports what was done (or what failed): `title`, `message` and the links back. +[[nodiscard]] auto account_result_page(AccountPageFrame const& frame, HtmlText title, HtmlText const& message) -> Page; +// A page with no session: `title`, `message` and a link to sign in again at `account_url`. +[[nodiscard]] auto account_signed_out_page(HtmlText title, HtmlText const& message, std::string_view account_url) + -> Page; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/AccountSignInInput.hpp b/include/merovingian/oauth/AccountSignInInput.hpp new file mode 100644 index 000000000..6fadce2bf --- /dev/null +++ b/include/merovingian/oauth/AccountSignInInput.hpp @@ -0,0 +1,32 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/oauth/HtmlText.hpp" + +#include +#include + +namespace merovingian::oauth +{ + +// What the account pages' sign-in form shows and carries (`account_sign_in_page`). Every view is borrowed for the call. +struct AccountSignInInput final +{ + // `server.server_name`, named in the opening line. + std::string_view server_name{}; + // The account management action (spec "Account management URL actions") the browser asked for, carried in a hidden + // field so the user lands on that page after signing in. Only one of `account_management_actions()`. + std::optional next_action{}; + // The device ID the browser asked for, carried with `next_action`. Only one that passed + // `auth::device_id_is_valid`, and only with a device action. + std::optional next_device_id{}; + // A username to prefill (what the user typed when the form is shown again), or none. + std::optional username{}; + // A fixed message about the last attempt, shown as an error box. + std::optional error{}; + // A fixed notice, such as "You have signed out". + std::optional notice{}; +}; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/ServerMetadataOptions.hpp b/include/merovingian/oauth/ServerMetadataOptions.hpp index bb50c0040..0f6c0d34c 100644 --- a/include/merovingian/oauth/ServerMetadataOptions.hpp +++ b/include/merovingian/oauth/ServerMetadataOptions.hpp @@ -18,8 +18,8 @@ struct ServerMetadataOptions final // so a client never offers account creation the registration page would refuse (ADR-0762). bool registration_enabled{false}; // The account management actions the account page implements, in the order to advertise. Empty leaves out both - // `account_management_uri` and `account_management_actions_supported`; the account pages arrive in phase 8, and - // until then nothing passes an action. + // `account_management_uri` and `account_management_actions_supported`. The served document passes all six + // (`account_management_actions()`, `AccountPages.hpp`). std::vector account_management_actions{}; }; diff --git a/src/homeserver/AccountPage.cpp b/src/homeserver/AccountPage.cpp new file mode 100644 index 000000000..1713ac531 --- /dev/null +++ b/src/homeserver/AccountPage.cpp @@ -0,0 +1,824 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/AccountPage.hpp" + +#include "merovingian/auth/AccountState.hpp" +#include "merovingian/auth/Identity.hpp" +#include "merovingian/core/CookieSameSite.hpp" +#include "merovingian/core/FormFields.hpp" +#include "merovingian/core/HostCookie.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/homeserver/AccountSession.hpp" +#include "merovingian/homeserver/AccountSessionStore.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientDeviceSessions.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/DeactivationAudit.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpRouter.hpp" +#include "merovingian/homeserver/LocalServices.hpp" +#include "merovingian/homeserver/OAuthClientRegistration.hpp" +#include "merovingian/homeserver/OAuthClock.hpp" +#include "merovingian/homeserver/OAuthPageResponse.hpp" +#include "merovingian/homeserver/OperationResult.hpp" +#include "merovingian/homeserver/PasswordLoginRequest.hpp" +#include "merovingian/homeserver/PasswordLoginVerification.hpp" +#include "merovingian/oauth/AccountDeviceRow.hpp" +#include "merovingian/oauth/AccountPageFrame.hpp" +#include "merovingian/oauth/AccountPages.hpp" +#include "merovingian/oauth/AccountSignInInput.hpp" +#include "merovingian/oauth/AuthorizationPages.hpp" +#include "merovingian/oauth/ClientMetadata.hpp" +#include "merovingian/oauth/FormContentType.hpp" +#include "merovingian/oauth/FormPostOrigin.hpp" +#include "merovingian/oauth/HtmlText.hpp" +#include "merovingian/oauth/OAuthBaseUrl.hpp" +#include "merovingian/oauth/OAuthPaths.hpp" +#include "merovingian/oauth/Page.hpp" +#include "merovingian/observability/AuditCategory.hpp" +#include "merovingian/observability/LogEventSeverity.hpp" +#include "merovingian/observability/SingleLog.hpp" +#include "merovingian/observability/StructuredLogField.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +namespace +{ + + using Outcome = PasswordLoginVerification::Outcome; + + constexpr auto status_ok = std::uint16_t{200U}; + constexpr auto status_see_other = std::uint16_t{303U}; + constexpr auto status_bad_request = std::uint16_t{400U}; + constexpr auto status_unauthorized = std::uint16_t{401U}; + constexpr auto status_forbidden = std::uint16_t{403U}; + constexpr auto status_not_found = std::uint16_t{404U}; + constexpr auto status_too_many_requests = std::uint16_t{429U}; + constexpr auto status_server_error = std::uint16_t{500U}; + constexpr auto status_unavailable = std::uint16_t{503U}; + // The longest username read from the sign-in form: a user ID is at most 255 bytes, so no account has a longer one. + constexpr auto max_sign_in_username_bytes = std::size_t{255U}; + + auto log_account(std::string_view event, std::string_view user_id, observability::LogEventSeverity severity) -> void + { + auto fields = std::vector{}; + if (!user_id.empty()) + { + fields.push_back({"user_id", std::string{user_id}, false}); + } + observability::log_diagnostic("oauth", event, fields, severity); + } + + // What every handler step works with: the runtime, the request and the address of the pages. + struct AccountContext final + { + ClientServerRuntime& rt; + RuntimeLock& guard; + LocalHttpRequest const& request; + oauth::OAuthBaseUrl const& base_url; + std::string account_url{}; + }; + + // A live session found from the request's cookie: its secret (to end it), its user and its form token. + struct SignedIn final + { + std::string secret{}; + AccountSession session{}; + std::string form_token{}; + }; + + // The `Set-Cookie` that deletes the session cookie, or nothing when it cannot be built (a fixed, valid name: only a + // defect refuses it). + [[nodiscard]] auto with_cookie_deleted(LocalHttpResponse response) -> LocalHttpResponse + { + auto deletion = core::host_cookie_deletion(account_cookie_name, core::CookieSameSite::strict); + if (auto const* const value = std::get_if(&deletion); value != nullptr) + { + response.headers.emplace_back("Set-Cookie", *value); + } + return response; + } + + [[nodiscard]] auto form_refused(oauth::HtmlText const& message, std::uint16_t status = status_bad_request) + -> LocalHttpResponse + { + return oauth_error_page_response(status, oauth::HtmlText{"Form refused"}, message); + } + + [[nodiscard]] auto server_name_of(AccountContext const& context) -> std::string_view + { + return context.rt.homeserver.config.server().server_name; + } + + [[nodiscard]] auto frame_of(AccountContext const& context, SignedIn const& signed_in) -> oauth::AccountPageFrame + { + return oauth::AccountPageFrame{server_name_of(context), signed_in.session.user_id, signed_in.form_token, + context.account_url}; + } + + // The action and device the browser asked for, each only when valid: `action` one of the six spec actions, and + // `device_id` only with a device action and only one `auth::device_id_is_valid` accepts (spec: "Actions which don't + // support the device ID will ignore it"). + struct RequestedPage final + { + std::optional action{}; + std::optional device_id{}; + }; + + [[nodiscard]] auto requested_page(std::optional action, std::optional device_id) + -> RequestedPage + { + auto page = RequestedPage{}; + page.action = oauth::account_management_action(action); + if (page.action.has_value() && oauth::account_action_takes_device(*page.action) && device_id.has_value() && + auth::device_id_is_valid(*device_id)) + { + page.device_id = std::string{*device_id}; + } + return page; + } + + // The live session the request's cookie names, its user still allowed to sign in. A session whose user no longer + // may (deactivated, locked, gone) is ended here. + [[nodiscard]] auto find_signed_in(AccountContext const& context) -> std::optional + { + auto secret = request_secret_cookie(context.request, account_cookie_name); + if (!secret.has_value()) + { + return std::nullopt; + } + auto& runtime = context.rt.homeserver; + auto const now_ms = oauth_wall_clock_ms(); + auto session = runtime.account_sessions.find(*secret, now_ms); + if (!session.has_value()) + { + return std::nullopt; + } + if (account_sign_in_gate(runtime, session->user_id, {}) != Outcome::verified) + { + std::ignore = runtime.account_sessions.end(*secret, now_ms); + return std::nullopt; + } + auto form_token = AccountSessionStore::form_token(*secret); + if (!form_token.has_value()) + { + return std::nullopt; + } + return SignedIn{std::move(*secret), std::move(*session), std::move(*form_token)}; + } + + // Whether the session `signed_in` names is still live and its user may still sign in: asked again after any call + // that released runtime.mutex. + [[nodiscard]] auto still_signed_in(AccountContext const& context, SignedIn const& signed_in) -> bool + { + auto& runtime = context.rt.homeserver; + auto const now_ms = oauth_wall_clock_ms(); + auto const session = runtime.account_sessions.find(signed_in.secret, now_ms); + if (!session.has_value() || session->user_id != signed_in.session.user_id) + { + return false; + } + if (account_sign_in_gate(runtime, session->user_id, {}) != Outcome::verified) + { + std::ignore = runtime.account_sessions.end(signed_in.secret, now_ms); + return false; + } + return true; + } + + [[nodiscard]] auto sign_in_page_response(AccountContext const& context, std::uint16_t status, + RequestedPage const& requested, std::optional username, + std::optional error, + std::optional notice = std::nullopt) -> LocalHttpResponse + { + auto input = oauth::AccountSignInInput{}; + input.server_name = server_name_of(context); + input.next_action = requested.action; + if (requested.device_id.has_value()) + { + input.next_device_id = *requested.device_id; + } + // A username is shown again only when it could be an account's: never text that is not a user ID or localpart. + if (username.has_value() && (auth::localpart_is_valid_new(*username) || auth::user_id_is_valid(*username))) + { + input.username = *username; + } + input.error = std::move(error); + input.notice = std::move(notice); + return oauth_plain_page(status, oauth::account_sign_in_page(input)); + } + + // The page with no session: a form that needs one was sent without, or the session ended. + [[nodiscard]] auto signed_out_response(AccountContext const& context, std::uint16_t status, oauth::HtmlText title, + oauth::HtmlText const& message) -> LocalHttpResponse + { + return with_cookie_deleted( + oauth_plain_page(status, oauth::account_signed_out_page(std::move(title), message, context.account_url))); + } + + [[nodiscard]] auto session_ended_response(AccountContext const& context) -> LocalHttpResponse + { + return signed_out_response( + context, status_forbidden, oauth::HtmlText{"Signed out"}, + oauth::HtmlText{"Your session on these pages has ended. Sign in again to continue."}); + } + + // The devices of the user, through the per-user device index, with the registered client name of each OAuth + // device. At most the per-user device cap; a client is read once however many of its devices there are. + struct OwnedDeviceRow final + { + std::string device_id{}; + std::string display_name{}; + bool oauth_session{false}; + std::optional client_name{}; + }; + + [[nodiscard]] auto owned_row(HomeserverRuntime const& runtime, database::PersistentDevice const& device, + std::map, std::less<>>& client_names) + -> OwnedDeviceRow + { + auto row = OwnedDeviceRow{device.device_id, device.display_name, false, std::nullopt}; + auto const* const oauth_session = + database::find_oauth_session(runtime.database.persistent_store, device.user_id, device.device_id); + if (oauth_session == nullptr) + { + return row; + } + row.oauth_session = true; + auto known = client_names.find(oauth_session->client_id); + if (known == client_names.end()) + { + auto const client = find_registered_oauth_client(runtime, oauth_session->client_id); + auto name = client.has_value() ? client->client_name() : std::optional{}; + known = client_names.emplace(oauth_session->client_id, std::move(name)).first; + } + row.client_name = known->second; + return row; + } + + [[nodiscard]] auto view_of(OwnedDeviceRow const& row) -> oauth::AccountDeviceRow + { + auto view = oauth::AccountDeviceRow{row.device_id, row.display_name, row.oauth_session, std::nullopt}; + if (row.client_name.has_value()) + { + view.client_name = *row.client_name; + } + return view; + } + + [[nodiscard]] auto user_devices(HomeserverRuntime const& runtime, std::string_view user_id) + -> std::vector + { + auto rows = std::vector{}; + auto client_names = std::map, std::less<>>{}; + database::for_each_user_device(runtime.database.persistent_store, user_id, + [&](database::PersistentDevice const& device) { + rows.push_back(owned_row(runtime, device, client_names)); + return true; + }); + return rows; + } + + // One device of the user, or nullopt when the user holds no device with this ID (whoever else may). + [[nodiscard]] auto user_device(HomeserverRuntime const& runtime, std::string_view user_id, + std::string_view device_id) -> std::optional + { + auto found = std::optional{}; + auto client_names = std::map, std::less<>>{}; + database::for_each_user_device(runtime.database.persistent_store, user_id, + [&](database::PersistentDevice const& device) { + if (device.device_id != device_id) + { + return true; + } + found = owned_row(runtime, device, client_names); + return false; + }); + return found; + } + + [[nodiscard]] auto unknown_device_response(AccountContext const& context, SignedIn const& signed_in) + -> LocalHttpResponse + { + return oauth_plain_page(status_not_found, oauth::account_unknown_device_page(frame_of(context, signed_in))); + } + + // The page `requested` names, for a signed-in user. + [[nodiscard]] auto action_page(AccountContext const& context, SignedIn const& signed_in, + RequestedPage const& requested) -> LocalHttpResponse + { + auto const& runtime = context.rt.homeserver; + auto const frame = frame_of(context, signed_in); + auto const& user_id = signed_in.session.user_id; + auto const action = requested.action.value_or(oauth::account_action_profile); + if (action == oauth::account_action_devices_list || + (oauth::account_action_takes_device(action) && !requested.device_id.has_value())) + { + auto const rows = user_devices(runtime, user_id); + auto views = std::vector{}; + views.reserve(rows.size()); + for (auto const& row : rows) + { + views.push_back(view_of(row)); + } + return oauth_plain_page(status_ok, oauth::account_devices_page(frame, views)); + } + if (oauth::account_action_takes_device(action)) + { + auto const device = user_device(runtime, user_id, *requested.device_id); + if (!device.has_value()) + { + return unknown_device_response(context, signed_in); + } + auto const view = view_of(*device); + return oauth_plain_page(status_ok, action == oauth::account_action_device_delete + ? oauth::account_device_delete_page(frame, view) + : oauth::account_device_page(frame, view)); + } + if (action == oauth::account_action_account_deactivate) + { + return oauth_plain_page(status_ok, oauth::account_deactivate_page(frame, std::nullopt)); + } + if (action == oauth::account_action_cross_signing_reset) + { + return oauth_plain_page(status_ok, oauth::account_cross_signing_reset_page(frame)); + } + auto const profile = database::find_profile(runtime.database.persistent_store, user_id); + auto display_name = std::optional{}; + if (profile.has_value()) + { + display_name = profile->displayname; + } + return oauth_plain_page(status_ok, oauth::account_overview_page(frame, display_name)); + } + + [[nodiscard]] auto handle_get(AccountContext const& context) -> LocalHttpResponse + { + auto parsed = core::FormFields::parse(request_target_query(context.request.target)); + auto const* const fields = std::get_if(&parsed); + // An unreadable query (a parameter sent twice, a bad escape) asks for nothing: the overview. + auto const requested = + fields == nullptr ? RequestedPage{} : requested_page(fields->find("action"), fields->find("device_id")); + auto const signed_in = find_signed_in(context); + if (!signed_in.has_value()) + { + auto response = sign_in_page_response(context, status_ok, requested, std::nullopt, std::nullopt); + // A cookie that names no live session is deleted, so the browser stops sending it. + if (request_secret_cookie(context.request, account_cookie_name).has_value()) + { + response = with_cookie_deleted(std::move(response)); + } + return response; + } + return action_page(context, *signed_in, requested); + } + + // The outcome of checking a password a form carries, as a page when it failed. + struct PasswordCheck final + { + bool verified{false}; + Outcome outcome{Outcome::invalid_login}; + std::uint32_t retry_after_seconds{0U}; + }; + + // Verifies `password` for `user_id` as POST /login does, with its throttle (per account and client source). + // Releases runtime.mutex around Argon2id: the caller trusts nothing it read before. + [[nodiscard]] auto check_password(AccountContext const& context, std::string_view user_id, + std::string_view password) -> PasswordCheck + { + auto& runtime = context.rt.homeserver; + auto const client_key = rate_limit_client_key(context.request, runtime.config.server()); + auto const verified = verify_password_login(runtime, PasswordLoginRequest{user_id, password, client_key, {}}); + auto check = PasswordCheck{}; + check.outcome = verified.outcome; + check.verified = verified.outcome == Outcome::verified && verified.user_id == user_id; + if (verified.outcome == Outcome::throttled || verified.outcome == Outcome::busy) + { + check.retry_after_seconds = retry_after_seconds(verified.retry_after_ms); + } + return check; + } + + // The message, status and headers of a failed password check on a signed-in form. + struct PasswordFailure final + { + std::uint16_t status{status_unauthorized}; + // A default member initialiser is not constant-evaluated: the HtmlLiteral check runs at run time here, so the + // text holds nothing that would need escaping. + oauth::HtmlText message{"That is not the password of this account."}; + std::optional retry_after_seconds{}; + }; + + [[nodiscard]] auto password_failure(PasswordCheck const& check) -> PasswordFailure + { + switch (check.outcome) + { + case Outcome::throttled: { + auto text = "Too many failed password attempts for this account. Try again in " + + std::to_string(check.retry_after_seconds) + " seconds."; + auto message = oauth::HtmlText::escape(text); + return {status_too_many_requests, + message.has_value() ? std::move(*message) + : oauth::HtmlText{"Too many failed password attempts. Try again later."}, + check.retry_after_seconds}; + } + case Outcome::busy: + return {status_unavailable, oauth::HtmlText{"The server is busy. Try again in a moment."}, + check.retry_after_seconds}; + case Outcome::verified: + case Outcome::invalid_login: + case Outcome::account_deactivated: + break; + } + return {}; + } + + [[nodiscard]] auto with_retry_after(LocalHttpResponse response, std::optional seconds) + -> LocalHttpResponse + { + if (seconds.has_value()) + { + response.headers.emplace_back("Retry-After", std::to_string(*seconds)); + } + return response; + } + + [[nodiscard]] auto handle_sign_in(AccountContext const& context, core::FormFields const& fields) + -> LocalHttpResponse + { + auto& runtime = context.rt.homeserver; + auto const requested = requested_page(fields.find(oauth::account_next_action_field.view()), + fields.find(oauth::account_next_device_field.view())); + auto const username = fields.find(oauth::username_field.view()); + auto const password = fields.find(oauth::password_field.view()); + if (!username.has_value() || username->empty() || !password.has_value() || password->empty()) + { + return sign_in_page_response(context, status_bad_request, requested, username, + oauth::HtmlText{"Enter your username and password."}); + } + auto const invalid_login = [&]() { + return sign_in_page_response( + context, status_unauthorized, requested, username, + oauth::HtmlText{"That username and password do not match an account on this server."}); + }; + if (username->size() > max_sign_in_username_bytes) + { + return invalid_login(); + } + auto const user_id = login_identifier_user_id(server_name_of(context), *username); + // Releases runtime.mutex around Argon2id. + auto const check = check_password(context, user_id, *password); + switch (check.outcome) + { + case Outcome::verified: + break; + case Outcome::invalid_login: + return invalid_login(); + case Outcome::account_deactivated: + return sign_in_page_response( + context, status_forbidden, requested, username, + oauth::HtmlText{"This account has been deactivated and can no longer sign in."}); + case Outcome::throttled: + case Outcome::busy: { + auto failure = password_failure(check); + return with_retry_after( + sign_in_page_response(context, failure.status, requested, username, std::move(failure.message)), + failure.retry_after_seconds); + } + } + if (!check.verified) + { + return invalid_login(); + } + auto const now_ms = oauth_wall_clock_ms(); + // A session the browser already held ends: a sign-in always starts a session of its own. + if (auto const previous = request_secret_cookie(context.request, account_cookie_name); previous.has_value()) + { + std::ignore = runtime.account_sessions.end(*previous, now_ms); + } + auto const busy = [&]() { + return with_retry_after( + sign_in_page_response(context, status_unavailable, requested, username, + oauth::HtmlText{"The server cannot sign you in now. Try again in a moment."}), + 1U); + }; + auto created = runtime.account_sessions.create(user_id, now_ms); + auto const* const secret = std::get_if(&created); + if (secret == nullptr) + { + return busy(); + } + auto cookie = core::host_cookie(account_cookie_name, *secret, core::CookieSameSite::strict, + account_cookie_max_age_seconds); + auto const* const set_cookie = std::get_if(&cookie); + if (set_cookie == nullptr) + { + std::ignore = runtime.account_sessions.end(*secret, now_ms); + return busy(); + } + log_account("account.page.signed_in", user_id, observability::LogEventSeverity::info); + auto location = context.account_url; + if (requested.action.has_value()) + { + location = oauth::account_action_address( + context.account_url, *requested.action, + requested.device_id.has_value() ? std::optional{*requested.device_id} : std::nullopt); + } + auto response = LocalHttpResponse{}; + response.status = status_see_other; + response.headers = { + {"Location", std::move(location)}, + {"Cache-Control", "no-store" }, + {"Referrer-Policy", "same-origin" }, + {"Set-Cookie", *set_cookie }, + }; + response.page = true; + return response; + } + + [[nodiscard]] auto result_page(AccountContext const& context, SignedIn const& signed_in, std::uint16_t status, + oauth::HtmlText title, oauth::HtmlText const& message) -> LocalHttpResponse + { + return oauth_plain_page(status, + oauth::account_result_page(frame_of(context, signed_in), std::move(title), message)); + } + + [[nodiscard]] auto handle_delete_device(AccountContext const& context, SignedIn const& signed_in, + core::FormFields const& fields) -> LocalHttpResponse + { + auto const device_id = fields.find(oauth::account_device_field.view()); + if (!device_id.has_value() || !auth::device_id_is_valid(*device_id)) + { + return unknown_device_response(context, signed_in); + } + // The client API's DELETE /devices/{deviceId}, after its authentication: a device that is not this user's is + // 404 whoever holds it, and the same page as a device that never existed. + auto const result = delete_device_and_announce(context.rt, signed_in.session.user_id, *device_id); + if (!result.ok) + { + if (result.status == status_not_found || result.status == status_bad_request) + { + return unknown_device_response(context, signed_in); + } + return result_page(context, signed_in, status_server_error, oauth::HtmlText{"Device not signed out"}, + oauth::HtmlText{"The device could not be signed out. Try again later."}); + } + log_account("account.page.device_deleted", signed_in.session.user_id, observability::LogEventSeverity::info); + return result_page(context, signed_in, status_ok, oauth::HtmlText{"Device signed out"}, + oauth::HtmlText{"The device is signed out and removed from your account."}); + } + + [[nodiscard]] auto password_page(AccountContext const& context, SignedIn const& signed_in, std::uint16_t status, + std::optional error) -> LocalHttpResponse + { + return oauth_plain_page(status, oauth::account_password_page(frame_of(context, signed_in), error)); + } + + // The fixed message and status for a refused password change. + [[nodiscard]] auto password_change_refusal(OperationResult const& result) + -> std::pair + { + if (result.errcode == "M_WEAK_PASSWORD") + { + return {status_bad_request, + oauth::HtmlText{"This password is too weak. Choose a longer one that is harder to guess."}}; + } + if (result.status == status_too_many_requests) + { + return {status_unavailable, oauth::HtmlText{"The server is busy. Try again in a moment."}}; + } + if (result.status == status_forbidden) + { + return {status_forbidden, + oauth::HtmlText{"The password was changed elsewhere meanwhile. Sign in again and retry."}}; + } + return {status_server_error, oauth::HtmlText{"The password could not be changed. Try again later."}}; + } + + [[nodiscard]] auto handle_change_password(AccountContext const& context, SignedIn const& signed_in, + core::FormFields const& fields) -> LocalHttpResponse + { + auto& runtime = context.rt.homeserver; + auto const& user_id = signed_in.session.user_id; + // The client API refuses POST /account/password to a suspended account (its allowlist does not hold it). + if (account_state_for_user(runtime, user_id) == auth::AccountState::suspended) + { + return result_page(context, signed_in, status_forbidden, oauth::HtmlText{"Password not changed"}, + oauth::HtmlText{"This account is suspended, so its password cannot be changed."}); + } + auto const current = fields.find(oauth::account_current_password_field.view()); + auto const replacement = fields.find(oauth::account_new_password_field.view()); + auto const confirmation = fields.find(oauth::account_new_password_confirm_field.view()); + if (!current.has_value() || current->empty() || !replacement.has_value() || replacement->empty() || + !confirmation.has_value()) + { + return password_page(context, signed_in, status_bad_request, oauth::HtmlText{"Fill in every field."}); + } + if (*replacement != *confirmation) + { + return password_page(context, signed_in, status_bad_request, + oauth::HtmlText{"The two new passwords do not match."}); + } + // Releases runtime.mutex around Argon2id: the session is found again below. + auto const check = check_password(context, user_id, *current); + if (!still_signed_in(context, signed_in)) + { + return session_ended_response(context); + } + if (!check.verified) + { + auto failure = password_failure(check); + return with_retry_after(password_page(context, signed_in, failure.status, std::move(failure.message)), + failure.retry_after_seconds); + } + // The core of the password reset: no device is kept, so every session of the account ends, these pages + // included (ADR-0798). Releases runtime.mutex around the hash. + auto const result = change_password_on_account_page(runtime, user_id, *replacement); + if (!result.ok) + { + if (!still_signed_in(context, signed_in)) + { + return session_ended_response(context); + } + auto [status, message] = password_change_refusal(result); + return password_page(context, signed_in, status, std::move(message)); + } + // As POST /account/password with logout_devices does: no login token outlives the change. + context.rt.login_tokens.erase_user(user_id); + log_account("account.page.password_changed", user_id, observability::LogEventSeverity::info); + return signed_out_response(context, status_ok, oauth::HtmlText{"Password changed"}, + oauth::HtmlText{"Your password is changed and every session of your account is " + "signed out. Sign in again with the new password."}); + } + + [[nodiscard]] auto deactivate_page(AccountContext const& context, SignedIn const& signed_in, std::uint16_t status, + std::optional error) -> LocalHttpResponse + { + return oauth_plain_page(status, oauth::account_deactivate_page(frame_of(context, signed_in), error)); + } + + [[nodiscard]] auto handle_deactivate(AccountContext const& context, SignedIn const& signed_in, + core::FormFields const& fields) -> LocalHttpResponse + { + auto& runtime = context.rt.homeserver; + auto const user_id = signed_in.session.user_id; + auto const password = fields.find(oauth::password_field.view()); + if (!password.has_value() || password->empty()) + { + return deactivate_page(context, signed_in, status_bad_request, oauth::HtmlText{"Enter your password."}); + } + // Releases runtime.mutex around Argon2id: the session is found again below. + auto const check = check_password(context, user_id, *password); + if (!still_signed_in(context, signed_in)) + { + return session_ended_response(context); + } + if (!check.verified) + { + auto failure = password_failure(check); + return with_retry_after(deactivate_page(context, signed_in, failure.status, std::move(failure.message)), + failure.retry_after_seconds); + } + // The client API's deactivation and what its handler does after it: every token, pusher and account-page + // session goes, the login tokens, and every 3PID bound at an identity server is unbound (releasing + // runtime.mutex for each call). Devices stay, as POST /account/deactivate leaves them. + auto const result = deactivate_user_account( + runtime, user_id, DeactivationAudit{user_id, user_id, "deactivated on the account page"}); + if (!result.ok) + { + return result_page(context, signed_in, status_server_error, oauth::HtmlText{"Account not deactivated"}, + oauth::HtmlText{"The account could not be deactivated. Try again later."}); + } + std::ignore = finish_account_deactivation(context.rt, context.guard, user_id, std::nullopt); + log_account("account.page.deactivated", user_id, observability::LogEventSeverity::info); + return signed_out_response( + context, status_ok, oauth::HtmlText{"Account deactivated"}, + oauth::HtmlText{"Your account is deactivated and every session of it is signed out."}); + } + + [[nodiscard]] auto handle_approve_reset(AccountContext const& context, SignedIn const& signed_in) + -> LocalHttpResponse + { + auto& runtime = context.rt.homeserver; + auto const& user_id = signed_in.session.user_id; + if (!runtime.cross_signing_reset_approvals.approve(user_id, oauth_wall_clock_ms())) + { + return with_retry_after(result_page(context, signed_in, status_unavailable, + oauth::HtmlText{"Reset not allowed"}, + oauth::HtmlText{"The server cannot record this now. Try again later."}), + 1U); + } + append_local_audit(runtime.database, observability::AuditCategory::auth, "cross_signing.reset_approved", + user_id, user_id, "account page"); + log_account("account.page.cross_signing_reset_approved", user_id, observability::LogEventSeverity::info); + return result_page(context, signed_in, status_ok, oauth::HtmlText{"Reset allowed"}, + oauth::HtmlText{"Return to your application to finish the reset. The permission lasts 10 " + "minutes and is used by one reset."}); + } + + [[nodiscard]] auto handle_post(AccountContext const& context) -> LocalHttpResponse + { + // Before anything is read: another site's post is refused whatever it carries (ADR-0784, ADR-0796). + if (!oauth::form_post_origin_is_accepted(context.base_url, single_request_header(context.request, "Origin"), + single_request_header(context.request, "Sec-Fetch-Site"))) + { + log_account("account.page.forbidden_origin", {}, observability::LogEventSeverity::debug); + return form_refused(oauth::HtmlText{"This form was not sent from a page of this server."}, + status_forbidden); + } + auto const content_type = single_request_header(context.request, "Content-Type"); + if (!content_type.has_value() || !oauth::page_form_content_type_is_accepted(*content_type)) + { + return form_refused(oauth::HtmlText{"This form could not be read."}); + } + auto parsed = core::FormFields::parse(context.request.body); + auto const* const fields = std::get_if(&parsed); + if (fields == nullptr) + { + return form_refused(oauth::HtmlText{"This form could not be read."}); + } + auto const action = fields->find(oauth::action_field.view()).value_or(std::string_view{}); + if (action == oauth::account_post_sign_in.view()) + { + return handle_sign_in(context, *fields); + } + // Every other form needs the session and its form token, which is not the cookie and is bound to it. + auto const signed_in = find_signed_in(context); + if (!signed_in.has_value()) + { + return session_ended_response(context); + } + auto const form_token = fields->find(oauth::account_form_token_field.view()); + if (!form_token.has_value() || !AccountSessionStore::form_token_matches(signed_in->secret, *form_token)) + { + return form_refused(oauth::HtmlText{"This form does not belong to your session. Reload the page and " + "try again."}, + status_forbidden); + } + if (action == oauth::account_post_sign_out.view()) + { + std::ignore = context.rt.homeserver.account_sessions.end(signed_in->secret, oauth_wall_clock_ms()); + log_account("account.page.signed_out", signed_in->session.user_id, observability::LogEventSeverity::info); + return signed_out_response(context, status_ok, oauth::HtmlText{"Signed out"}, + oauth::HtmlText{"You have signed out of these pages."}); + } + if (action == oauth::account_post_show_password.view()) + { + return password_page(context, *signed_in, status_ok, std::nullopt); + } + if (action == oauth::account_post_change_password.view()) + { + return handle_change_password(context, *signed_in, *fields); + } + if (action == oauth::account_post_delete_device.view()) + { + return handle_delete_device(context, *signed_in, *fields); + } + if (action == oauth::account_post_deactivate.view()) + { + return handle_deactivate(context, *signed_in, *fields); + } + if (action == oauth::account_post_approve_reset.view()) + { + return handle_approve_reset(context, *signed_in); + } + return form_refused(oauth::HtmlText{"This form asked for something this page does not do."}); + } + +} // namespace + +auto handle_account_page(ClientServerRuntime& rt, RuntimeLock& guard, LocalHttpRequest const& request) + -> LocalHttpResponse +{ + auto base = oauth::OAuthBaseUrl::read(rt.homeserver.config.server().public_baseurl); + auto const* const base_url = std::get_if(&base); + if (base_url == nullptr) + { + return oauth_error_page_response(status_server_error, oauth::HtmlText{"Account pages are not available"}, + oauth::HtmlText{"This server is not configured for its account pages."}); + } + auto const context = AccountContext{rt, guard, request, *base_url, base_url->url(oauth::account_path)}; + if (request.method == "POST") + { + return handle_post(context); + } + return handle_get(context); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/AccountSessionStore.cpp b/src/homeserver/AccountSessionStore.cpp new file mode 100644 index 000000000..6c21913a8 --- /dev/null +++ b/src/homeserver/AccountSessionStore.cpp @@ -0,0 +1,172 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/AccountSessionStore.hpp" + +#include "merovingian/crypto/ConstantTime.hpp" +#include "merovingian/crypto/GenericHash.hpp" +#include "merovingian/homeserver/OAuthSecret.hpp" + +#include +#include +#include + +namespace merovingian::homeserver +{ +namespace +{ + + // Separates the form token from every other hash of the session secret (the stored `oauth_secret_hash` is + // unlabelled), so the token cannot be computed from what the store keeps and is never the cookie value. + constexpr auto form_token_label = std::string_view{"merovingian.account.form_token.v1"}; + +} // namespace + +auto AccountSessionStore::forget(Entry const& entry) -> void +{ + auto const user = m_hashes_by_user.find(entry.session.user_id); + if (user == m_hashes_by_user.end()) + { + return; + } + // The per-user list is a hash we stored ourselves, not a secret a request offered: a plain comparison is enough. + std::erase(user->second, entry.secret_hash); + if (user->second.empty()) + { + m_hashes_by_user.erase(user); + } +} + +auto AccountSessionStore::erase_hash(std::string_view secret_hash) -> bool +{ + auto taken = m_sessions.erase(secret_hash); + if (!taken.has_value()) + { + return false; + } + forget(*taken); + return true; +} + +auto AccountSessionStore::erase_expired(std::uint64_t now_ms) -> void +{ + m_sessions.erase_expired(now_ms, [this](Entry const& entry) { + forget(entry); + }); +} + +auto AccountSessionStore::create(std::string_view user_id, std::uint64_t now_ms) -> std::variant +{ + if (user_id.empty()) + { + return Refusal::no_user; + } + erase_expired(now_ms); + auto secret = make_oauth_secret(); + auto secret_hash = secret.has_value() ? oauth_secret_hash(*secret) : std::nullopt; + if (!secret_hash.has_value()) + { + return Refusal::secret_unavailable; + } + if (auto const user = m_hashes_by_user.find(user_id); + user != m_hashes_by_user.end() && user->second.size() >= max_sessions_per_user) + { + // Replace this user's oldest session; every session has the same lifetime, so the oldest is the first. + auto const oldest = user->second.front(); + erase_hash(oldest); + } + else if (m_sessions.size() >= max_sessions) + { + return Refusal::store_full; + } + auto const expires_at_ms = now_ms + lifetime_ms; + auto session = AccountSession{std::string{user_id}, now_ms, expires_at_ms}; + m_hashes_by_user[session.user_id].push_back(*secret_hash); + auto hash_copy = *secret_hash; + m_sessions.insert(std::move(*secret_hash), Entry{std::move(session), std::move(hash_copy)}, expires_at_ms); + return std::move(*secret); +} + +auto AccountSessionStore::find(std::string_view secret, std::uint64_t now_ms) -> std::optional +{ + erase_expired(now_ms); + if (secret.empty()) + { + return std::nullopt; + } + auto const secret_hash = oauth_secret_hash(secret); + if (!secret_hash.has_value()) + { + return std::nullopt; + } + auto const* entry = m_sessions.find(*secret_hash); + if (entry == nullptr) + { + return std::nullopt; + } + return entry->session; +} + +auto AccountSessionStore::end(std::string_view secret, std::uint64_t now_ms) -> bool +{ + erase_expired(now_ms); + if (secret.empty()) + { + return false; + } + auto const secret_hash = oauth_secret_hash(secret); + return secret_hash.has_value() && erase_hash(*secret_hash); +} + +auto AccountSessionStore::end_user(std::string_view user_id) -> std::size_t +{ + auto const user = m_hashes_by_user.find(user_id); + if (user == m_hashes_by_user.end()) + { + return 0U; + } + // Copied first: each erase edits the list through `forget`. + auto const hashes = user->second; + auto ended = std::size_t{0U}; + for (auto const& hash : hashes) + { + if (erase_hash(hash)) + { + ++ended; + } + } + return ended; +} + +auto AccountSessionStore::form_token(std::string_view secret) -> std::optional +{ + if (secret.empty()) + { + return std::nullopt; + } + auto const pieces = std::array{form_token_label, secret}; + return crypto::generic_hash(pieces); +} + +auto AccountSessionStore::form_token_matches(std::string_view secret, std::string_view offered) -> bool +{ + auto const expected = form_token(secret); + if (!expected.has_value() || offered.empty()) + { + return false; + } + return crypto::constant_time_equal(*expected, offered); +} + +auto AccountSessionStore::live_count_for_user(std::string_view user_id, std::uint64_t now_ms) -> std::size_t +{ + erase_expired(now_ms); + auto const user = m_hashes_by_user.find(user_id); + return user == m_hashes_by_user.end() ? 0U : user->second.size(); +} + +auto AccountSessionStore::size() const noexcept -> std::size_t +{ + return m_sessions.size(); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/AuthService.cpp b/src/homeserver/AuthService.cpp index 614099fe9..4f778acdf 100644 --- a/src/homeserver/AuthService.cpp +++ b/src/homeserver/AuthService.cpp @@ -2443,6 +2443,15 @@ namespace return all_deleted; } + // Ends what the account pages hold for `user_id`: every signed-in page session and any cross-signing reset + // approval (ADR-0796, ADR-0797, ADR-0798). Run by every password change, reset and deactivation, so a browser left + // signed in to the pages, or an approval granted before, does not outlive the credential that opened it. + auto end_account_page_access(HomeserverRuntime& runtime, std::string_view user_id) -> void + { + std::ignore = runtime.account_sessions.end_user(user_id); + runtime.cross_signing_reset_approvals.withdraw(user_id); + } + } // namespace // Permanently deactivates `user_id`: the one deactivation, run for the account's owner after UIA (spec: @@ -2482,6 +2491,7 @@ auto deactivate_user_account(HomeserverRuntime& runtime, std::string_view user_i remember_local_audit(runtime.database, observability::AuditCategory::auth, "auth.account_deactivated", audit.actor, audit.target, audit.reason); } + end_account_page_access(runtime, user_id); // Every credential dies with the account, including the caller's own -- unlike // a password change, there is no session to preserve. @@ -2739,86 +2749,123 @@ auto change_local_user_password(HomeserverRuntime& runtime, std::string_view acc } } } + end_account_page_access(runtime, user_id); append_local_audit(runtime.database, observability::AuditCategory::auth, "auth.password_changed", user_id, session->device_id, logout_devices ? "changed; revoked other devices" : "changed"); return make_operation_result(true, std::string{user_id}); } -auto reset_local_user_password(HomeserverRuntime& runtime, std::string_view user_id, std::string_view new_password, - bool logout_devices) -> OperationResult +namespace { - if (!asserted_user_is_active(runtime, user_id)) - { - return make_operation_result(false, {}, "account is not active", 403U); - } - if (!auth::password_is_acceptable(new_password, configured_password_policy(runtime))) - { - return weak_password_refusal(); - } - auto const* const initial_user = find_user(runtime.database, user_id); - if (initial_user == nullptr) - { - return make_operation_result(false, {}, "account is not active", 403U); - } - auto const hash_replaced = initial_user->password_hash; - auto const argon_slot = runtime.argon2id_admission->try_acquire(); - if (!argon_slot) - { - return argon2id_admission_refusal(); - } - auto const new_hash = std::invoke([&]() { - auto const released = merovingian::homeserver::RuntimeLockRelease{}; - return auth::hash_password(new_password); - }); - if (!new_hash.has_value()) - { - return make_operation_result(false, {}, "password hashing failed", 500U); - } - // The lock is held again: write nothing unless the account is still active and still holds the hash this - // reset set out to replace (a concurrent change or deactivation altered it). - auto const* const user_now = find_user(runtime.database, user_id); - if (user_now == nullptr || user_now->password_hash != hash_replaced || !asserted_user_is_active(runtime, user_id)) - { - return make_operation_result(false, {}, "password changed concurrently", 403U); - } - // Pushers go first, as in change_local_user_password: a failure then commits no credential change. - if (logout_devices && !delete_pushers_of_user(runtime, user_id, std::nullopt)) - { - return make_operation_result(false, {}, "pusher removal persistence failed", 500U); - } - if (!database::update_user_password(runtime.database.persistent_store, user_id, *new_hash)) - { - return make_operation_result(false, {}, "password update failed", 500U); - } - auto const it = std::ranges::find_if(runtime.database.users, [&](LocalUser const& u) { - return u.user_id == user_id; - }); - if (it != runtime.database.users.end()) + + // What a password change with no calling device audits: the email reset (ADR-0481) and the account page + // (ADR-0798) share one core, so the two can never drift apart. + struct DevicelessPasswordAudit final { - it->password_hash = *new_hash; - } - if (logout_devices) + std::string_view event{}; + std::string_view reason{}; + }; + + // Sets `new_password` for `user_id` with no device to keep: with `logout_devices`, every access, refresh and + // OpenID token and every pusher of the account goes. Hashes with runtime.mutex released and the Argon2id budget + // held, then writes nothing unless the account is still active and still holds the hash this change set out to + // replace. Ends the user's account-page sessions and reset approvals on success. + [[nodiscard]] auto replace_password_without_device(HomeserverRuntime& runtime, std::string_view user_id, + std::string_view new_password, bool logout_devices, + DevicelessPasswordAudit const& audit) -> OperationResult { - // Spec (POST /account/password): with logout_devices the server revokes the access tokens of all the - // user's devices; there is no device to keep, so none is spared. - std::ignore = database::revoke_access_tokens_for_user(runtime.database.persistent_store, user_id); - std::ignore = database::revoke_refresh_tokens_for_user(runtime.database.persistent_store, user_id); - if (!user_tokens_are_revoked(runtime.database.persistent_store, user_id) || - !database::revoke_openid_tokens_for_user(runtime.database.persistent_store, user_id)) + if (!asserted_user_is_active(runtime, user_id)) { - return make_operation_result(false, {}, "token revocation persistence failed", 500U); + return make_operation_result(false, {}, "account is not active", 403U); } - for (auto& candidate : runtime.database.sessions) + if (!auth::password_is_acceptable(new_password, configured_password_policy(runtime))) + { + return weak_password_refusal(); + } + auto const* const initial_user = find_user(runtime.database, user_id); + if (initial_user == nullptr) + { + return make_operation_result(false, {}, "account is not active", 403U); + } + auto const hash_replaced = initial_user->password_hash; + auto const argon_slot = runtime.argon2id_admission->try_acquire(); + if (!argon_slot) + { + return argon2id_admission_refusal(); + } + auto const new_hash = std::invoke([&]() { + auto const released = merovingian::homeserver::RuntimeLockRelease{}; + return auth::hash_password(new_password); + }); + if (!new_hash.has_value()) + { + return make_operation_result(false, {}, "password hashing failed", 500U); + } + // The lock is held again: write nothing unless the account is still active and still holds the hash this + // reset set out to replace (a concurrent change or deactivation altered it). + auto const* const user_now = find_user(runtime.database, user_id); + if (user_now == nullptr || user_now->password_hash != hash_replaced || + !asserted_user_is_active(runtime, user_id)) + { + return make_operation_result(false, {}, "password changed concurrently", 403U); + } + // Pushers go first, as in change_local_user_password: a failure then commits no credential change. + if (logout_devices && !delete_pushers_of_user(runtime, user_id, std::nullopt)) { - if (candidate.user_id == user_id) + return make_operation_result(false, {}, "pusher removal persistence failed", 500U); + } + if (!database::update_user_password(runtime.database.persistent_store, user_id, *new_hash)) + { + return make_operation_result(false, {}, "password update failed", 500U); + } + auto const it = std::ranges::find_if(runtime.database.users, [&](LocalUser const& u) { + return u.user_id == user_id; + }); + if (it != runtime.database.users.end()) + { + it->password_hash = *new_hash; + } + if (logout_devices) + { + // Spec (POST /account/password): with logout_devices the server revokes the access tokens of all the + // user's devices; there is no device to keep, so none is spared. + std::ignore = database::revoke_access_tokens_for_user(runtime.database.persistent_store, user_id); + std::ignore = database::revoke_refresh_tokens_for_user(runtime.database.persistent_store, user_id); + if (!user_tokens_are_revoked(runtime.database.persistent_store, user_id) || + !database::revoke_openid_tokens_for_user(runtime.database.persistent_store, user_id)) { - candidate.revoked = true; + return make_operation_result(false, {}, "token revocation persistence failed", 500U); + } + for (auto& candidate : runtime.database.sessions) + { + if (candidate.user_id == user_id) + { + candidate.revoked = true; + } } } + end_account_page_access(runtime, user_id); + append_local_audit(runtime.database, observability::AuditCategory::auth, audit.event, user_id, {}, + audit.reason); + return make_operation_result(true, std::string{user_id}); } - append_local_audit(runtime.database, observability::AuditCategory::auth, "auth.password_reset", user_id, {}, - logout_devices ? "reset by email; revoked all devices" : "reset by email"); - return make_operation_result(true, std::string{user_id}); + +} // namespace + +auto reset_local_user_password(HomeserverRuntime& runtime, std::string_view user_id, std::string_view new_password, + bool logout_devices) -> OperationResult +{ + return replace_password_without_device( + runtime, user_id, new_password, logout_devices, + {"auth.password_reset", logout_devices ? "reset by email; revoked all devices" : "reset by email"}); +} + +auto change_password_on_account_page(HomeserverRuntime& runtime, std::string_view user_id, + std::string_view new_password) -> OperationResult +{ + return replace_password_without_device( + runtime, user_id, new_password, true, + {"auth.password_changed", "changed on the account page; revoked all devices"}); } auto verify_local_user_password(HomeserverRuntime& runtime, std::string_view access_token, std::string_view password) diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index a87b628ed..fab957519 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -76,6 +76,7 @@ #include "merovingian/federation/PublicRoomsFilter.hpp" #include "merovingian/federation/PublicRoomsRefusal.hpp" #include "merovingian/federation/Security.hpp" +#include "merovingian/homeserver/AccountPage.hpp" #include "merovingian/homeserver/AppserviceDelivery.hpp" #include "merovingian/homeserver/AppserviceEphemeral.hpp" #include "merovingian/homeserver/AuthService.hpp" @@ -102,6 +103,7 @@ #include "merovingian/homeserver/MutualRoomsToken.hpp" #include "merovingian/homeserver/OAuthAuthorization.hpp" #include "merovingian/homeserver/OAuthClientRegistration.hpp" +#include "merovingian/homeserver/OAuthClock.hpp" #include "merovingian/homeserver/OAuthRevocation.hpp" #include "merovingian/homeserver/OAuthTokenEndpoint.hpp" #include "merovingian/homeserver/OperationResult.hpp" @@ -145,6 +147,7 @@ #include "merovingian/http/RequestErrorCode.hpp" #include "merovingian/identity/IdentityServerClient.hpp" #include "merovingian/media/Security.hpp" +#include "merovingian/oauth/AccountPages.hpp" #include "merovingian/oauth/OAuthBaseUrl.hpp" #include "merovingian/oauth/OAuthPaths.hpp" #include "merovingian/oauth/ServerMetadata.hpp" @@ -4040,6 +4043,7 @@ namespace "/_merovingian/oauth2/authorize", "/_merovingian/oauth2/token", "/_merovingian/oauth2/revoke", + "/_merovingian/account", "/_matrix/client/v3/account/3pid/email/requestToken", "/_matrix/client/v3/account/3pid/msisdn/requestToken", "/_matrix/client/v3/account/password/email/requestToken", @@ -4140,6 +4144,7 @@ namespace {"/_merovingian/oauth2/authorize", "GET, POST" }, {"/_merovingian/oauth2/token", "POST" }, {"/_merovingian/oauth2/revoke", "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" }, @@ -13393,6 +13398,129 @@ namespace return true; } + // The UIA session purpose of the `m.oauth` stage of a replacing cross-signing upload (ADR-0797). + constexpr auto cross_signing_reset_uia_purpose = std::string_view{"cross_signing_reset"}; + + // A cross-signing reset approval an OAuth session's replacing upload has taken (ADR-0797). It goes back to the + // store unless `spend` is called once the keys are stored, so a refused or failed upload does not use it up. Lives + // within one request, under runtime.mutex. + class TakenResetApproval final + { + public: + TakenResetApproval(ClientServerRuntime& rt, std::string_view user_id, std::uint64_t expires_at_ms) + : m_rt{&rt} + , m_user_id{user_id} + , m_expires_at_ms{expires_at_ms} + { + } + TakenResetApproval(TakenResetApproval const&) = delete; + auto operator=(TakenResetApproval const&) -> TakenResetApproval& = delete; + TakenResetApproval(TakenResetApproval&&) = delete; + auto operator=(TakenResetApproval&&) -> TakenResetApproval& = delete; + ~TakenResetApproval() noexcept + { + if (m_spent) + { + return; + } + try + { + m_rt->homeserver.cross_signing_reset_approvals.restore(m_user_id, m_expires_at_ms, + oauth_wall_clock_ms()); + } + catch (...) + { + // Restoring allocates. If it cannot, the approval is lost and the user approves again: fail closed. + m_spent = true; + } + } + + // The keys are stored: the approval is used up, and the use is audited. + auto spend() -> void + { + m_spent = true; + append_local_audit(m_rt->homeserver.database, observability::AuditCategory::auth, + "cross_signing.reset_used", m_user_id, m_user_id, "m.oauth"); + } + + private: + ClientServerRuntime* m_rt; + std::string m_user_id; + std::uint64_t m_expires_at_ms; + bool m_spent{false}; + }; + + // The outcome of the `m.oauth` stage: the answer to send (a 401 challenge, a 429 for a full UIA pool, a 500), or, + // with no answer, the expiry of the approval the request has taken. + struct OAuthResetStage final + { + std::optional answer{}; + std::uint64_t approval_expires_at_ms{0U}; + }; + + // The `m.oauth` User-Interactive Authentication stage of a replacing cross-signing upload from an OAuth session + // (spec v1.19 "OAuth authentication" and "Account management"; ADR-0797). nullopt when the stage cannot be offered + // (OAuth off, or no usable `server.public_baseurl`): the caller keeps the ADR-0794 403. + // + // The stage is complete only when the `auth` dict carries a session this server issued to this user for this + // purpose, its `type` is absent or `m.oauth` (a password stage is answered with the challenge and never checked: + // an OAuth session cannot complete the upload with a password), and the user approved the reset on the account page + // in the last ten minutes. The approval is taken here and spent only by a stored upload. + [[nodiscard]] auto oauth_cross_signing_reset_stage(ClientServerRuntime& rt, LocalHttpRequest const& req, + std::string_view user, + std::optional const& body) + -> std::optional + { + if (!rt.homeserver.config.server().oauth.enabled) + { + return std::nullopt; + } + auto const base = oauth::OAuthBaseUrl::read(rt.homeserver.config.server().public_baseurl); + auto const* const base_url = std::get_if(&base); + if (base_url == nullptr) + { + return std::nullopt; + } + auto const challenge = [base_url](std::string_view session) { + auto const url = oauth::account_action_address(base_url->url(oauth::account_path), + oauth::account_action_cross_signing_reset); + auto const body_json = json_obj({ + json_member("flows", json_arr({json_obj({json_member("stages", json_arr({json_str("m.oauth")}))})})), + json_member("params", + json_obj({json_member("m.oauth", json_obj({json_member("url", json_str(url))}))})), + json_member("session", json_str(std::string{session})), + }); + return OAuthResetStage{resp(401U, json_serialize(body_json)), 0U}; + }; + auto const* const auth = body.has_value() ? object_member_object(*body, "auth") : nullptr; + auto const* const type = auth != nullptr ? string_member(*auth, "type") : nullptr; + auto const* const session = auth != nullptr ? string_member(*auth, "session") : nullptr; + if (session != nullptr && uia_session_is_valid(rt, cross_signing_reset_uia_purpose, *session, user)) + { + if (type == nullptr || *type == "m.oauth") + { + if (auto const expires_at_ms = + rt.homeserver.cross_signing_reset_approvals.take(user, oauth_wall_clock_ms()); + expires_at_ms.has_value()) + { + return OAuthResetStage{std::nullopt, *expires_at_ms}; + } + } + // Not approved yet, or another stage: the same session, so the client keeps waiting on it. + return challenge(*session); + } + auto const issued = issue_uia_session(rt, cross_signing_reset_uia_purpose, user); + if (!issued.has_value()) + { + return OAuthResetStage{uia_pool_full_response(rt, req).response, 0U}; + } + if (issued->empty()) + { + return OAuthResetStage{err(500U, "M_UNKNOWN", "no authentication session could be issued"), 0U}; + } + return challenge(*issued); + } + // POST /_matrix/client/v3/keys/device_signing/upload: upload of the cross-signing keys, password-authenticated // unless cross_signing_upload_is_uia_exempt. [[nodiscard]] auto handle_upload_cross_signing_keys(ClientServerRuntime& rt, auth::KeyApiRoute const& route, @@ -13404,50 +13532,66 @@ namespace // service (ADR-0794). auto const cs_body = parsed_json_object(req.body); auto const uia_exempt = cs_body.has_value() && cross_signing_upload_is_uia_exempt(rt, user, *cs_body, req); + // An OAuth session's replacing upload completes the `m.oauth` stage with an approval from the account page, + // which is taken here and put back on every way out except a stored upload (ADR-0797). + auto taken_approval = std::optional{}; if (!uia_exempt) { if (auto const refusal = oauth_session_uia_refusal(rt, req.access_token); refusal.has_value()) { - return err(403U, "M_FORBIDDEN", *refusal); - } - // Spec §11.12.1: MUST require UIA (m.login.password) to prevent key takeover. - auto const cs_uia = json_obj({ - json_member("flows", - json_arr({json_obj({json_member("stages", json_arr({json_str("m.login.password")}))})})), - json_member("params", json_obj({})), - json_member("session", json_str("cross_signing_upload")), - }); - auto const* cs_auth = cs_body.has_value() ? object_member_object(*cs_body, "auth") : nullptr; - if (cs_auth == nullptr) - { - return resp(401U, json_serialize(cs_uia)); - } - auto const* cs_auth_type = string_member(*cs_auth, "type"); - if (cs_auth_type == nullptr || *cs_auth_type != "m.login.password") - { - return resp(401U, json_serialize(cs_uia)); - } - auto const* cs_password = string_member(*cs_auth, "password"); - if (cs_password == nullptr || cs_password->empty()) - { - return resp(401U, json_serialize(cs_uia)); + auto const stage = oauth_cross_signing_reset_stage(rt, req, user, cs_body); + if (!stage.has_value()) + { + return err(403U, "M_FORBIDDEN", *refusal); + } + if (stage->answer.has_value()) + { + return *stage->answer; + } + taken_approval.emplace(rt, user, stage->approval_expires_at_ms); } - auto const password_verified = verify_local_user_password(rt.homeserver, req.access_token, *cs_password); - if (!password_verified.ok) + else { - if (password_verified.retry_after_ms > 0U) + // Spec §11.12.1: MUST require UIA (m.login.password) to prevent key takeover. + auto const cs_uia = json_obj({ + json_member("flows", json_arr({json_obj( + {json_member("stages", json_arr({json_str("m.login.password")}))})})), + json_member("params", json_obj({})), + json_member("session", json_str("cross_signing_upload")), + }); + auto const* cs_auth = cs_body.has_value() ? object_member_object(*cs_body, "auth") : nullptr; + if (cs_auth == nullptr) + { + return resp(401U, json_serialize(cs_uia)); + } + auto const* cs_auth_type = string_member(*cs_auth, "type"); + if (cs_auth_type == nullptr || *cs_auth_type != "m.login.password") + { + return resp(401U, json_serialize(cs_uia)); + } + auto const* cs_password = string_member(*cs_auth, "password"); + if (cs_password == nullptr || cs_password->empty()) { - auto const retry_after = static_cast(std::min( - password_verified.retry_after_ms, std::numeric_limits::max())); - auto response = LocalHttpResponse{ - 429U, - matrix_error("M_LIMIT_EXCEEDED", "Too many password attempts. Please try again later.", - retry_after), - {{"Retry-After", std::to_string((retry_after + 999U) / 1000U)}}}; - apply_cors_headers(req, response, rt.cors); - return response; + return resp(401U, json_serialize(cs_uia)); + } + auto const password_verified = + verify_local_user_password(rt.homeserver, req.access_token, *cs_password); + if (!password_verified.ok) + { + if (password_verified.retry_after_ms > 0U) + { + auto const retry_after = static_cast(std::min( + password_verified.retry_after_ms, std::numeric_limits::max())); + auto response = LocalHttpResponse{ + 429U, + matrix_error("M_LIMIT_EXCEEDED", "Too many password attempts. Please try again later.", + retry_after), + {{"Retry-After", std::to_string((retry_after + 999U) / 1000U)}}}; + apply_cors_headers(req, response, rt.cors); + return response; + } + return resp(401U, uia_password_failure_body(json_serialize(cs_uia))); } - return resp(401U, uia_password_failure_body(json_serialize(cs_uia))); } } for (auto const* key_type : {"master_key", "self_signing_key", "user_signing_key"}) @@ -13472,6 +13616,10 @@ namespace { return err(500U, "M_UNKNOWN", "key API persistence failed"); } + if (taken_approval.has_value()) + { + taken_approval->spend(); + } // Spec §11.11.1: cross-signing key change MUST appear in device_lists.changed. // Self-notify so the user's own other devices re-query the new keys (required // for verification to complete). Also fan out to room-sharing local users and @@ -14223,6 +14371,62 @@ auto end_device_session_and_announce(ClientServerRuntime& runtime, std::string_v return result; } +auto delete_device_and_announce(ClientServerRuntime& runtime, std::string_view user_id, std::string_view device_id) + -> OperationResult +{ + // The servers to tell, read before the device is removed. + auto const destinations = remote_servers_for_user(runtime.homeserver, user_id); + auto result = delete_local_device(runtime.homeserver, user_id, device_id); + if (!result.ok) + { + return result; + } + erase_runtime_device(runtime, user_id, device_id); + std::ignore = record_shared_room_device_changes(runtime, user_id, NotifyOwnDevices::no); + announce_deleted_devices(runtime, user_id, {std::string{device_id}}, destinations); + return result; +} + +auto finish_account_deactivation(ClientServerRuntime& runtime, RuntimeLock& guard, std::string_view user_id, + std::optional const& requested_id_server) -> std::string_view +{ + // F-07: a deactivated account holds no login token. + runtime.login_tokens.erase_user(user_id); + // Unbind every identity-server-bound 3PID the account holds. Spec: the + // 200 response's id_server_unbind_result is "success" only when *all* + // identifiers were unbound -- and when there were none to unbind -- + // and "no-support" when one or more could not be, whether because the + // identity server refused or because none could be determined. + // + // Deactivation itself has already happened and is not undone by an + // unbind failure: the spec models a partial unbind as a 200 carrying + // "no-support", not as a failed deactivation. This is the opposite + // disposition to POST /account/3pid/unbind, which fails closed so the + // user can retry -- there is no retry after deactivation. + // + // Addresses are copied out before the loop: the outbound call drops the + // runtime lock, so the store vector can move and any iterator, pointer + // or index taken across it would dangle. + auto const user = std::string{user_id}; + auto pending_unbinds = std::vector>{}; + for (auto const& record : runtime.homeserver.database.persistent_store.account_threepids) + { + if (record.user_id == user && record.bound) + { + pending_unbinds.emplace_back(record.medium, record.address); + } + } + auto unbind_result = std::string_view{"success"}; + for (auto const& [medium, address] : pending_unbinds) + { + if (!unbind_threepid_for_deactivation(runtime, guard, user, medium, address, requested_id_server)) + { + unbind_result = "no-support"; + } + } + return unbind_result; +} + // Translate the operator-facing `config::ClientRateLimitsConfig` into the // engine's `http::RateLimitConfig`. Start from the design-doc defaults so // every client-server route has a sensible cap even when the operator leaves @@ -16123,6 +16327,11 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp auto options = oauth::ServerMetadataOptions{}; options.device_grant_enabled = server_config.oauth.device_grant_enabled; options.registration_enabled = rt.homeserver.config.security().registration.enabled; + // Spec "Account management": the account pages implement every action, so all six are listed. + for (auto const action : oauth::account_management_actions()) + { + options.account_management_actions.emplace_back(action); + } return dispatch_resp(req, rt, 200U, json_serialize(oauth::server_metadata(std::get(base), options))); } @@ -16183,6 +16392,20 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return DispatchResult{DispatchResult::Status::complete, handle_oauth_revoke(rt, req), {}}; } } + // GET and POST /_merovingian/account (spec "Account management"): the account pages, signed in with the account's + // password and their own short session (ADR-0796), so they are answered before the access-token gate, 404 with the + // OAuth 2.0 API off. Another method falls through to the 405 gate. The handler is AccountPage.cpp. + if (request_path == oauth::account_path.view()) + { + if (!rt.homeserver.config.server().oauth.enabled) + { + return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); + } + if (req.method == "GET" || req.method == "POST") + { + return DispatchResult{DispatchResult::Status::complete, handle_account_page(rt, guard, req), {}}; + } + } // The rest of the MSC2965 namespace (`auth_issuer`, from an earlier draft of the MSC) is not served. It is // answered 404 before the access-token gate, so a probe does not read a 401 as partial support. if (req.method == "GET" && starts_with(req.target, "/_matrix/client/unstable/org.matrix.msc2965/")) @@ -17372,45 +17595,13 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return dispatch_err(req, rt, result.status, result.status == 401U ? "M_UNKNOWN_TOKEN" : "M_FORBIDDEN", result.reason); } - // F-07: a deactivated account holds no login token. - rt.login_tokens.erase_user(*user); - // Unbind every identity-server-bound 3PID the account holds. Spec: the - // 200 response's id_server_unbind_result is "success" only when *all* - // identifiers were unbound -- and when there were none to unbind -- - // and "no-support" when one or more could not be, whether because the - // identity server refused or because none could be determined. - // - // Deactivation itself has already happened and is not undone by an - // unbind failure: the spec models a partial unbind as a 200 carrying - // "no-support", not as a failed deactivation. This is the opposite - // disposition to POST /account/3pid/unbind, which fails closed so the - // user can retry -- there is no retry after deactivation. - // - // Addresses are copied out before the loop: the outbound call drops the - // runtime lock, so the store vector can move and any iterator, pointer - // or index taken across it would dangle. // Optional per spec; when absent each binding's own recorded id_server is // used instead. auto const requested_id_server = [&object]() -> std::optional { auto const* value = string_member(*object, "id_server"); return value == nullptr || value->empty() ? std::nullopt : std::optional{*value}; }(); - auto pending_unbinds = std::vector>{}; - for (auto const& record : rt.homeserver.database.persistent_store.account_threepids) - { - if (record.user_id == result.value && record.bound) - { - pending_unbinds.emplace_back(record.medium, record.address); - } - } - auto unbind_result = std::string_view{"success"}; - for (auto const& [medium, address] : pending_unbinds) - { - if (!unbind_threepid_for_deactivation(rt, guard, result.value, medium, address, requested_id_server)) - { - unbind_result = "no-support"; - } - } + auto const unbind_result = finish_account_deactivation(rt, guard, result.value, requested_id_server); return dispatch_resp( req, rt, 200U, json_serialize(json_obj({json_member("id_server_unbind_result", json_str(unbind_result))}))); } @@ -18990,17 +19181,12 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return challenge(true); } auto const device_id = device_id_from_device_path(request_path); - // The servers to tell, read before the device is removed. - auto const destinations = remote_servers_for_user(rt.homeserver, *user); - auto const result = delete_local_device(rt.homeserver, *user, device_id); + auto const result = delete_device_and_announce(rt, *user, device_id); if (!result.ok) { return dispatch_err(req, rt, result.status, result.status == 404U ? "M_NOT_FOUND" : "M_UNKNOWN", result.reason); } - erase_runtime_device(rt, *user, device_id); - std::ignore = record_shared_room_device_changes(rt, *user, NotifyOwnDevices::no); - announce_deleted_devices(rt, *user, {std::string{device_id}}, destinations); return dispatch_resp(req, rt, 200U, "{}"); } if (req.method == "POST" && request_path == "/_matrix/client/v3/delete_devices") diff --git a/src/homeserver/CrossSigningResetApprovals.cpp b/src/homeserver/CrossSigningResetApprovals.cpp new file mode 100644 index 000000000..597c203ca --- /dev/null +++ b/src/homeserver/CrossSigningResetApprovals.cpp @@ -0,0 +1,90 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/CrossSigningResetApprovals.hpp" + +namespace merovingian::homeserver +{ + +auto CrossSigningResetApprovals::erase_expired(std::uint64_t now_ms) -> void +{ + while (!m_by_expiry.empty() && m_by_expiry.begin()->first <= now_ms) + { + auto const first = m_by_expiry.begin(); + if (auto const user = m_by_user.find(first->second); user != m_by_user.end()) + { + m_by_user.erase(user); + } + m_by_expiry.erase(first); + } +} + +auto CrossSigningResetApprovals::withdraw(std::string_view user_id) -> void +{ + auto const user = m_by_user.find(user_id); + if (user == m_by_user.end()) + { + return; + } + m_by_expiry.erase(user->second.expiry); + m_by_user.erase(user); +} + +auto CrossSigningResetApprovals::record(std::string_view user_id, std::uint64_t expires_at_ms) -> void +{ + withdraw(user_id); + auto const expiry = m_by_expiry.emplace(expires_at_ms, std::string{user_id}); + m_by_user.emplace(std::string{user_id}, Approval{expires_at_ms, expiry}); +} + +auto CrossSigningResetApprovals::approve(std::string_view user_id, std::uint64_t now_ms) -> bool +{ + if (user_id.empty()) + { + return false; + } + erase_expired(now_ms); + if (!m_by_user.contains(user_id) && m_by_user.size() >= max_approvals) + { + return false; + } + record(user_id, now_ms + lifetime_ms); + return true; +} + +auto CrossSigningResetApprovals::holds(std::string_view user_id, std::uint64_t now_ms) -> bool +{ + erase_expired(now_ms); + return m_by_user.contains(user_id); +} + +auto CrossSigningResetApprovals::take(std::string_view user_id, std::uint64_t now_ms) -> std::optional +{ + erase_expired(now_ms); + auto const user = m_by_user.find(user_id); + if (user == m_by_user.end()) + { + return std::nullopt; + } + auto const expires_at_ms = user->second.expires_at_ms; + m_by_expiry.erase(user->second.expiry); + m_by_user.erase(user); + return expires_at_ms; +} + +auto CrossSigningResetApprovals::restore(std::string_view user_id, std::uint64_t expires_at_ms, std::uint64_t now_ms) + -> void +{ + erase_expired(now_ms); + if (user_id.empty() || expires_at_ms <= now_ms || m_by_user.contains(user_id) || m_by_user.size() >= max_approvals) + { + return; + } + record(user_id, expires_at_ms); +} + +auto CrossSigningResetApprovals::size() const noexcept -> std::size_t +{ + return m_by_user.size(); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/OAuthAuthorization.cpp b/src/homeserver/OAuthAuthorization.cpp index 0d630d7c1..5b47ef247 100644 --- a/src/homeserver/OAuthAuthorization.cpp +++ b/src/homeserver/OAuthAuthorization.cpp @@ -8,7 +8,6 @@ #include "merovingian/core/Error.hpp" #include "merovingian/core/FormFields.hpp" #include "merovingian/core/HostCookie.hpp" -#include "merovingian/core/RequestCookies.hpp" #include "merovingian/database/PersistentStore.hpp" #include "merovingian/homeserver/AccountCreationRequest.hpp" #include "merovingian/homeserver/AuthService.hpp" @@ -21,13 +20,13 @@ #include "merovingian/homeserver/LocalServices.hpp" #include "merovingian/homeserver/OAuthClientRegistration.hpp" #include "merovingian/homeserver/OAuthClock.hpp" +#include "merovingian/homeserver/OAuthPageResponse.hpp" #include "merovingian/homeserver/OAuthSecret.hpp" #include "merovingian/homeserver/OperationResult.hpp" #include "merovingian/homeserver/PasswordLoginRequest.hpp" #include "merovingian/homeserver/PasswordLoginVerification.hpp" #include "merovingian/homeserver/PendingAuthorisation.hpp" #include "merovingian/homeserver/PendingAuthorisationStore.hpp" -#include "merovingian/homeserver/RequestHeaders.hpp" #include "merovingian/oauth/AccountFormInput.hpp" #include "merovingian/oauth/ApplicationType.hpp" #include "merovingian/oauth/AuthorizationPages.hpp" @@ -84,8 +83,6 @@ namespace constexpr auto status_unavailable = std::uint16_t{503U}; // The longest username read from the login form: a user ID is at most 255 bytes, so no account has a longer one. constexpr auto max_login_username_bytes = std::size_t{255U}; - // A browser cookie value as make_oauth_secret mints it: 64 lower-case hex digits. - constexpr auto browser_token_chars = std::size_t{oauth_secret_bytes * 2U}; [[nodiscard]] auto application_type_name(oauth::ApplicationType type) noexcept -> std::string_view { @@ -112,42 +109,21 @@ namespace log_oauth("oauth.authorization.refused", std::move(fields), observability::LogEventSeverity::debug); } - // A page answer: the rendered page with the page headers (ADR-0772, ADR-0784) and the page mark (ADR-0785). - [[nodiscard]] auto page_response(std::uint16_t status, oauth::Page const& page, - std::vector> headers) -> LocalHttpResponse - { - auto response = LocalHttpResponse{}; - response.status = status; - response.body = page.render(); - response.headers = std::move(headers); - response.page = true; - return response; - } - - [[nodiscard]] auto plain_page(std::uint16_t status, oauth::Page const& page) -> LocalHttpResponse - { - return page_response(status, page, oauth::page_headers()); - } - - [[nodiscard]] auto error_page_response(std::uint16_t status, oauth::HtmlText title, oauth::HtmlText const& message) - -> LocalHttpResponse - { - return plain_page(status, oauth::error_page(std::move(title), message)); - } - // Step 1 of the request: nothing is redirected, because no address has been validated. [[nodiscard]] auto bad_request_page(oauth::HtmlText const& message) -> LocalHttpResponse { - return error_page_response(status_bad_request, oauth::HtmlText{"This sign-in request cannot be used"}, message); + return oauth_error_page_response(status_bad_request, oauth::HtmlText{"This sign-in request cannot be used"}, + message); } // The answer to a form post whose pending authorisation is gone, never was, or is bound to another browser. The // server no longer holds a validated address for it, so the user is sent back to the application by hand. [[nodiscard]] auto expired_page() -> LocalHttpResponse { - return error_page_response(status_bad_request, oauth::HtmlText{"Sign-in expired"}, - oauth::HtmlText{"This sign-in has expired or was already finished. Return to the " - "application and start again."}); + return oauth_error_page_response( + status_bad_request, oauth::HtmlText{"Sign-in expired"}, + oauth::HtmlText{"This sign-in has expired or was already finished. Return to the " + "application and start again."}); } // A redirect to the client: the redirect URI the request gave, matched against the registration, with the answer in @@ -183,64 +159,6 @@ namespace return redirect_response(status, target, mode, parameters); } - // The query of a request target, without the `?`; empty when there is none. - [[nodiscard]] auto target_query(std::string_view target) noexcept -> std::string_view - { - auto const at = target.find('?'); - return at == std::string_view::npos ? std::string_view{} : target.substr(at + 1U); - } - - // The one value of header `name`, or nullopt when it is absent or sent more than once (a repeated `Origin`, - // `Sec-Fetch-Site` or `Cookie` is treated as absent, never resolved). - [[nodiscard]] auto single_header(LocalHttpRequest const& request, std::string_view name) - -> std::optional - { - auto const values = request_header_values(request, name); - if (values.size() != 1U) - { - return std::nullopt; - } - return values.front(); - } - - [[nodiscard]] auto is_browser_token(std::string_view value) noexcept -> bool - { - if (value.size() != browser_token_chars) - { - return false; - } - for (auto const character : value) - { - if (!((character >= '0' && character <= '9') || (character >= 'a' && character <= 'f'))) - { - return false; - } - } - return true; - } - - // The browser token the request's cookie carries, when it carries exactly one well-formed value. - [[nodiscard]] auto request_browser_token(LocalHttpRequest const& request) -> std::optional - { - auto const header = single_header(request, "Cookie"); - if (!header.has_value()) - { - return std::nullopt; - } - auto parsed = core::RequestCookies::parse(*header); - auto const* cookies = std::get_if(&parsed); - if (cookies == nullptr) - { - return std::nullopt; - } - auto const value = cookies->find(oauth_browser_cookie_name); - if (!value.has_value() || !is_browser_token(*value)) - { - return std::nullopt; - } - return std::string{*value}; - } - // The username a `login_hint` prefills (spec "Login flow" leaves its form to the server): `mxid:` and a valid user // ID of this server gives its localpart; a bare valid localpart gives itself; anything else nothing. [[nodiscard]] auto login_hint_username(std::optional hint, std::string_view server_name) @@ -336,20 +254,13 @@ namespace [[nodiscard]] auto login_page_response(std::uint16_t status, oauth::AccountFormInput const& input) -> LocalHttpResponse { - return plain_page(status, oauth::login_page(input)); + return oauth_plain_page(status, oauth::login_page(input)); } [[nodiscard]] auto registration_page_response(std::uint16_t status, oauth::AccountFormInput const& input) -> LocalHttpResponse { - return plain_page(status, oauth::registration_page(input)); - } - - // `Retry-After` in whole seconds, rounded up, at least one. - [[nodiscard]] auto retry_after_seconds(std::uint32_t retry_after_ms) -> std::uint32_t - { - auto const seconds = (retry_after_ms / 1000U) + (retry_after_ms % 1000U == 0U ? 0U : 1U); - return seconds == 0U ? 1U : seconds; + return oauth_plain_page(status, oauth::registration_page(input)); } // The consent page for the pending authorisation `post` names, now authenticated as `user_id`. Its policy allows @@ -382,8 +293,8 @@ namespace } input.replaces_existing_device = database::has_user_device(runtime.database.persistent_store, user_id, post.entry.device_id); - return page_response(status_ok, oauth::consent_page(input, target->redirect_target), - oauth::page_headers(target->redirect_target)); + return oauth_page_response(status_ok, oauth::consent_page(input, target->redirect_target), + oauth::page_headers(target->redirect_target)); } // Records `user_id` on the entry and answers the consent page. The store finds the entry again, so a login or a @@ -641,33 +552,33 @@ namespace auto const* base_url = std::get_if(&base); if (base_url == nullptr) { - return error_page_response( + return oauth_error_page_response( status_server_error, oauth::HtmlText{"Sign-in is not available"}, oauth::HtmlText{"This server is not configured for sign-in through applications."}); } // Before anything is read: another site's post is refused whatever it carries (ADR-0784, ADR-0788). - if (!oauth::form_post_origin_is_accepted(*base_url, single_header(request, "Origin"), - single_header(request, "Sec-Fetch-Site"))) + if (!oauth::form_post_origin_is_accepted(*base_url, single_request_header(request, "Origin"), + single_request_header(request, "Sec-Fetch-Site"))) { log_refused({}, "forbidden_origin"); - return error_page_response(status_forbidden, oauth::HtmlText{"Form refused"}, - oauth::HtmlText{"This form was not sent from a page of this server."}); + return oauth_error_page_response(status_forbidden, oauth::HtmlText{"Form refused"}, + oauth::HtmlText{"This form was not sent from a page of this server."}); } - auto const content_type = single_header(request, "Content-Type"); + auto const content_type = single_request_header(request, "Content-Type"); if (!content_type.has_value() || !oauth::page_form_content_type_is_accepted(*content_type)) { - return error_page_response(status_bad_request, oauth::HtmlText{"Form refused"}, - oauth::HtmlText{"This form could not be read."}); + return oauth_error_page_response(status_bad_request, oauth::HtmlText{"Form refused"}, + oauth::HtmlText{"This form could not be read."}); } auto parsed = core::FormFields::parse(request.body); auto const* fields = std::get_if(&parsed); if (fields == nullptr) { - return error_page_response(status_bad_request, oauth::HtmlText{"Form refused"}, - oauth::HtmlText{"This form could not be read."}); + return oauth_error_page_response(status_bad_request, oauth::HtmlText{"Form refused"}, + oauth::HtmlText{"This form could not be read."}); } auto const pending_id = fields->find(oauth::pending_field.view()); - auto browser_token = request_browser_token(request); + auto browser_token = request_secret_cookie(request, oauth_browser_cookie_name); if (!pending_id.has_value() || pending_id->empty() || !browser_token.has_value()) { return expired_page(); @@ -709,8 +620,8 @@ namespace { return handle_deny(post); } - return error_page_response(status_bad_request, oauth::HtmlText{"Form refused"}, - oauth::HtmlText{"This form asked for something this page does not do."}); + return oauth_error_page_response(status_bad_request, oauth::HtmlText{"Form refused"}, + oauth::HtmlText{"This form asked for something this page does not do."}); } // What the `prompt` parameter asks the first page to be. @@ -725,7 +636,7 @@ namespace { auto& runtime = rt.homeserver; // Step 1: the client and its redirect URI. Nothing here is ever sent to an address. - auto parsed = core::FormFields::parse(target_query(request.target)); + auto parsed = core::FormFields::parse(request_target_query(request.target)); auto const* fields = std::get_if(&parsed); if (fields == nullptr) { @@ -822,7 +733,7 @@ namespace auto const hint = login_hint_username(fields->find("login_hint"), server_name); // Step 3: bind a pending authorisation to this browser. - auto browser_token = request_browser_token(request); + auto browser_token = request_secret_cookie(request, oauth_browser_cookie_name); if (!browser_token.has_value()) { browser_token = make_oauth_secret(); @@ -834,8 +745,9 @@ namespace auto const* set_cookie = std::get_if(&cookie); if (set_cookie == nullptr) { - return error_page_response(status_unavailable, oauth::HtmlText{"Sign-in is not available"}, - oauth::HtmlText{"The server cannot start a sign-in now. Try again later."}); + return oauth_error_page_response( + status_unavailable, oauth::HtmlText{"Sign-in is not available"}, + oauth::HtmlText{"The server cannot start a sign-in now. Try again later."}); } auto authorisation = PendingAuthorisation{}; authorisation.client_id = std::string{*client_id}; @@ -857,7 +769,7 @@ namespace if (pending_id == nullptr) { log_refused(*client_id, oauth::error_temporarily_unavailable); - return error_page_response( + return oauth_error_page_response( status_unavailable, oauth::HtmlText{"Sign-in is not available"}, oauth::HtmlText{"Too many sign-ins are in progress. Try again in a few minutes."}); } diff --git a/src/homeserver/OAuthPageResponse.cpp b/src/homeserver/OAuthPageResponse.cpp new file mode 100644 index 000000000..67c4aa078 --- /dev/null +++ b/src/homeserver/OAuthPageResponse.cpp @@ -0,0 +1,106 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#include "merovingian/homeserver/OAuthPageResponse.hpp" + +#include "merovingian/core/RequestCookies.hpp" +#include "merovingian/homeserver/OAuthSecret.hpp" +#include "merovingian/homeserver/RequestHeaders.hpp" +#include "merovingian/oauth/AuthorizationPages.hpp" +#include "merovingian/oauth/PageHeaders.hpp" + +#include +#include + +namespace merovingian::homeserver +{ + +namespace +{ + + // A secret as make_oauth_secret mints it: 64 lower-case hex digits. + constexpr auto secret_text_chars = std::size_t{oauth_secret_bytes * 2U}; + +} // namespace + +auto oauth_page_response(std::uint16_t status, oauth::Page const& page, + std::vector> headers) -> LocalHttpResponse +{ + auto response = LocalHttpResponse{}; + response.status = status; + response.body = page.render(); + response.headers = std::move(headers); + response.page = true; + return response; +} + +auto oauth_plain_page(std::uint16_t status, oauth::Page const& page) -> LocalHttpResponse +{ + return oauth_page_response(status, page, oauth::page_headers()); +} + +auto oauth_error_page_response(std::uint16_t status, oauth::HtmlText title, oauth::HtmlText const& message) + -> LocalHttpResponse +{ + return oauth_plain_page(status, oauth::error_page(std::move(title), message)); +} + +auto request_target_query(std::string_view target) noexcept -> std::string_view +{ + auto const at = target.find('?'); + return at == std::string_view::npos ? std::string_view{} : target.substr(at + 1U); +} + +auto single_request_header(LocalHttpRequest const& request, std::string_view name) -> std::optional +{ + auto const values = request_header_values(request, name); + if (values.size() != 1U) + { + return std::nullopt; + } + return values.front(); +} + +auto is_oauth_secret_text(std::string_view value) noexcept -> bool +{ + if (value.size() != secret_text_chars) + { + return false; + } + for (auto const character : value) + { + if (!((character >= '0' && character <= '9') || (character >= 'a' && character <= 'f'))) + { + return false; + } + } + return true; +} + +auto request_secret_cookie(LocalHttpRequest const& request, std::string_view cookie_name) -> std::optional +{ + auto const header = single_request_header(request, "Cookie"); + if (!header.has_value()) + { + return std::nullopt; + } + auto parsed = core::RequestCookies::parse(*header); + auto const* cookies = std::get_if(&parsed); + if (cookies == nullptr) + { + return std::nullopt; + } + auto const value = cookies->find(cookie_name); + if (!value.has_value() || !is_oauth_secret_text(*value)) + { + return std::nullopt; + } + return std::string{*value}; +} + +auto retry_after_seconds(std::uint32_t retry_after_ms) noexcept -> std::uint32_t +{ + auto const seconds = (retry_after_ms / 1000U) + (retry_after_ms % 1000U == 0U ? 0U : 1U); + return seconds == 0U ? 1U : seconds; +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/meson.build b/src/homeserver/meson.build index ae8e81f0b..48c1ef4c6 100644 --- a/src/homeserver/meson.build +++ b/src/homeserver/meson.build @@ -8,6 +8,8 @@ homeserver_sources = files( 'SessionTable.cpp', 'LoginTokenStore.cpp', 'AuthorizationCodeStore.cpp', + 'AccountSessionStore.cpp', + 'CrossSigningResetApprovals.cpp', 'OAuthSecret.cpp', 'PendingAuthorisationStore.cpp', 'RequestHeaders.cpp', @@ -31,11 +33,13 @@ homeserver_sources = files( 'MediaService.cpp', 'StreamedBody.cpp', 'MediaUploadNotifier.cpp', + 'AccountPage.cpp', 'OAuthAuthorization.cpp', 'OAuthClientCredentials.cpp', 'OAuthClientRegistration.cpp', 'OAuthClock.cpp', 'OAuthJsonResponse.cpp', + 'OAuthPageResponse.cpp', 'OAuthRevocation.cpp', 'OAuthTokenEndpoint.cpp', 'OperatorAdmin.cpp', diff --git a/src/oauth/AccountPages.cpp b/src/oauth/AccountPages.cpp new file mode 100644 index 000000000..0367ba3aa --- /dev/null +++ b/src/oauth/AccountPages.cpp @@ -0,0 +1,369 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/oauth/AccountPages.hpp" + +#include "merovingian/oauth/AuthorizationPages.hpp" +#include "merovingian/oauth/AuthorizationRedirect.hpp" +#include "merovingian/oauth/HtmlLiteral.hpp" +#include "merovingian/oauth/OAuthPaths.hpp" +#include "merovingian/oauth/PageDetail.hpp" +#include "merovingian/oauth/PageForm.hpp" +#include "merovingian/oauth/SubmitButton.hpp" +#include "merovingian/oauth/TextInput.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::oauth +{ + +namespace +{ + + // The fixed phrase the consent page shows for a client with no name it can show. + constexpr auto unnamed_client = HtmlLiteral{"An application with no name"}; + + // `text` escaped, or `fallback` when HtmlText::escape refuses it: the raw value is never shown. + [[nodiscard]] auto shown(std::string_view text, HtmlLiteral fallback) -> HtmlText + { + auto escaped = HtmlText::escape(text); + return escaped.has_value() ? std::move(*escaped) : HtmlText{fallback}; + } + + // `prefix`, `value` and `suffix` as one escaped sentence, or `fallback` when the value cannot be shown. + [[nodiscard]] auto sentence(std::string_view prefix, std::string_view value, std::string_view suffix, + HtmlLiteral fallback) -> HtmlText + { + if (value.empty()) + { + return HtmlText{fallback}; + } + auto text = std::string{prefix}; + text.append(value); + text.append(suffix); + return shown(text, fallback); + } + + // A form posting `action` with the session's form token, or nullopt when the token cannot be shown (the page then + // has no form). + [[nodiscard]] auto session_form(AccountPageFrame const& frame) -> std::optional + { + auto token = HtmlText::escape(frame.form_token); + if (!token.has_value()) + { + return std::nullopt; + } + auto form = PageForm{account_path}; + form.hidden(account_form_token_field, std::move(*token)); + return form; + } + + // The opening line every signed-in page has, naming the server and the user. + auto add_signed_in_as(Page& page, AccountPageFrame const& frame) -> void + { + page.details(std::array{ + PageDetail{HtmlText{"Server"}, shown(frame.server_name, "this server") }, + PageDetail{HtmlText{"Signed in as"}, shown(frame.user_id, "an account that cannot be shown")}, + }); + } + + // The links back to the overview and the device list, and the sign-out button, at the foot of every signed-in + // page. + auto add_footer(Page& page, AccountPageFrame const& frame) -> void + { + std::ignore = + page.link(HtmlText{"Your account"}, account_action_address(frame.account_url, account_action_profile)); + std::ignore = + page.link(HtmlText{"Your devices"}, account_action_address(frame.account_url, account_action_devices_list)); + if (auto form = session_form(frame); form.has_value()) + { + std::ignore = + form->button(SubmitButton{action_field, account_post_sign_out, HtmlText{"Sign out of this page"}}); + std::ignore = page.form(*form); + } + } + + auto add_error(Page& page, std::optional const& error) -> void + { + if (error.has_value()) + { + page.error(*error); + } + } + + [[nodiscard]] auto password_input(HtmlName name, HtmlText label, HtmlName autocomplete) -> TextInput + { + auto input = TextInput{name, std::move(label), autocomplete}; + input.concealed = true; + return input; + } + + // The details of one device: its ID, its name, and how it signed in. + [[nodiscard]] auto device_details(AccountDeviceRow const& device) -> std::array + { + auto const name = device.display_name.empty() ? HtmlText{"No name set"} + : shown(device.display_name, "A name that cannot be shown"); + auto signed_in_with = HtmlText{"A password, in the application"}; + if (device.oauth_session) + { + signed_in_with = + device.client_name.has_value() ? shown(*device.client_name, unnamed_client) : HtmlText{unnamed_client}; + } + return { + PageDetail{HtmlText{"Device ID"}, shown(device.device_id, "a device that cannot be shown")}, + PageDetail{HtmlText{"Name"}, name}, + PageDetail{HtmlText{"Signed in with"}, std::move(signed_in_with)}, + }; + } + + // A link to `action` for `device`, labelled with the device ID (or fixed text when it cannot be shown). + auto add_device_link(Page& page, AccountPageFrame const& frame, std::string_view label_prefix, + std::string_view action, AccountDeviceRow const& device) -> void + { + auto const label = sentence(label_prefix, device.device_id, "", "A device that cannot be shown"); + std::ignore = page.link(label, account_action_address(frame.account_url, action, device.device_id)); + } + +} // namespace + +auto account_action_address(std::string_view account_url, std::string_view action, + std::optional device_id) -> std::string +{ + auto address = std::string{account_url}; + address.append("?action="); + address.append(percent_encode_redirect_value(action)); + if (device_id.has_value()) + { + address.append("&device_id="); + address.append(percent_encode_redirect_value(*device_id)); + } + return address; +} + +auto account_management_action(std::optional action) noexcept -> std::optional +{ + if (!action.has_value()) + { + return std::nullopt; + } + for (auto const known : account_management_actions()) + { + if (*action == known) + { + return known; + } + } + return std::nullopt; +} + +auto account_action_takes_device(std::string_view action) noexcept -> bool +{ + return action == account_action_device_view || action == account_action_device_delete; +} + +auto account_sign_in_page(AccountSignInInput const& input) -> Page +{ + auto page = Page{HtmlText{"Sign in to manage your account"}}; + page.paragraph(sentence("Sign in with your account on ", input.server_name, " to manage it.", + "Sign in with your account on this server to manage it.")); + if (input.notice.has_value()) + { + page.notice(*input.notice); + } + add_error(page, input.error); + auto form = PageForm{account_path}; + // The action and device are carried only when they can be shown; the handler validated both before. + if (auto const action = account_management_action(input.next_action); action.has_value()) + { + if (auto text = HtmlText::escape(*action); text.has_value()) + { + form.hidden(account_next_action_field, std::move(*text)); + } + if (input.next_device_id.has_value() && account_action_takes_device(*action)) + { + if (auto text = HtmlText::escape(*input.next_device_id); text.has_value()) + { + form.hidden(account_next_device_field, std::move(*text)); + } + } + } + auto username = TextInput{username_field, HtmlText{"Username"}, HtmlName{"username"}}; + if (input.username.has_value()) + { + username.value = HtmlText::escape(*input.username); + } + std::ignore = form.input(std::move(username)); + std::ignore = form.input(password_input(password_field, HtmlText{"Password"}, HtmlName{"current-password"})); + std::ignore = form.button(SubmitButton{action_field, account_post_sign_in, HtmlText{"Sign in"}}); + std::ignore = page.form(form); + page.paragraph(HtmlText{"You stay signed in to these pages for 15 minutes at most."}); + return page; +} + +auto account_overview_page(AccountPageFrame const& frame, std::optional display_name) -> Page +{ + auto page = Page{HtmlText{"Your account"}}; + add_signed_in_as(page, frame); + auto const name = display_name.has_value() && !display_name->empty() + ? shown(*display_name, "A name that cannot be shown") + : HtmlText{"No display name set"}; + page.details(std::array{ + PageDetail{HtmlText{"User ID"}, shown(frame.user_id, "an account that cannot be shown")}, + PageDetail{HtmlText{"Display name"}, name}, + }); + page.paragraph(HtmlText{"Change your display name and avatar in your application."}); + std::ignore = page.link(HtmlText{"See and sign out your devices"}, + account_action_address(frame.account_url, account_action_devices_list)); + std::ignore = page.link(HtmlText{"Reset your encryption identity"}, + account_action_address(frame.account_url, account_action_cross_signing_reset)); + std::ignore = page.link(HtmlText{"Deactivate your account"}, + account_action_address(frame.account_url, account_action_account_deactivate)); + if (auto form = session_form(frame); form.has_value()) + { + std::ignore = + form->button(SubmitButton{action_field, account_post_show_password, HtmlText{"Change your password"}}); + std::ignore = page.form(*form); + } + add_footer(page, frame); + return page; +} + +auto account_devices_page(AccountPageFrame const& frame, std::span devices) -> Page +{ + auto page = Page{HtmlText{"Your devices"}}; + add_signed_in_as(page, frame); + if (devices.empty()) + { + page.paragraph(HtmlText{"No device is signed in to your account."}); + } + for (auto const& device : devices) + { + page.details(device_details(device)); + add_device_link(page, frame, "Details of ", account_action_device_view, device); + } + add_footer(page, frame); + return page; +} + +auto account_device_page(AccountPageFrame const& frame, AccountDeviceRow const& device) -> Page +{ + auto page = Page{HtmlText{"Device"}}; + add_signed_in_as(page, frame); + page.details(device_details(device)); + add_device_link(page, frame, "Sign out ", account_action_device_delete, device); + add_footer(page, frame); + return page; +} + +auto account_device_delete_page(AccountPageFrame const& frame, AccountDeviceRow const& device) -> Page +{ + auto page = Page{HtmlText{"Sign out a device"}}; + add_signed_in_as(page, frame); + page.details(device_details(device)); + page.paragraph(HtmlText{"Signing this device out ends its session: the application on it can no longer use your " + "account, and the device is removed from your account."}); + auto device_value = HtmlText::escape(device.device_id); + if (auto form = session_form(frame); form.has_value() && device_value.has_value()) + { + form->hidden(account_device_field, std::move(*device_value)); + std::ignore = + form->button(SubmitButton{action_field, account_post_delete_device, HtmlText{"Sign out this device"}}); + std::ignore = page.form(*form); + } + add_footer(page, frame); + return page; +} + +auto account_unknown_device_page(AccountPageFrame const& frame) -> Page +{ + auto page = Page{HtmlText{"Device not found"}}; + add_signed_in_as(page, frame); + page.error(HtmlText{"Your account has no device with this ID."}); + add_footer(page, frame); + return page; +} + +auto account_password_page(AccountPageFrame const& frame, std::optional const& error) -> Page +{ + auto page = Page{HtmlText{"Change your password"}}; + add_signed_in_as(page, frame); + page.paragraph(HtmlText{"After the change every session of your account is signed out, in every application and on " + "every device, and so are these pages. Sign in again with the new password."}); + add_error(page, error); + if (auto form = session_form(frame); form.has_value()) + { + std::ignore = form->input( + password_input(account_current_password_field, HtmlText{"Current password"}, HtmlName{"current-password"})); + std::ignore = + form->input(password_input(account_new_password_field, HtmlText{"New password"}, HtmlName{"new-password"})); + std::ignore = form->input(password_input(account_new_password_confirm_field, + HtmlText{"Repeat the new password"}, HtmlName{"new-password"})); + std::ignore = + form->button(SubmitButton{action_field, account_post_change_password, HtmlText{"Change password"}}); + std::ignore = page.form(*form); + } + add_footer(page, frame); + return page; +} + +auto account_deactivate_page(AccountPageFrame const& frame, std::optional const& error) -> Page +{ + auto page = Page{HtmlText{"Deactivate your account"}}; + add_signed_in_as(page, frame); + page.paragraph(HtmlText{"Deactivation cannot be undone. Every session of your account is signed out, you can never " + "sign in again, and nobody can register your user ID again."}); + add_error(page, error); + if (auto form = session_form(frame); form.has_value()) + { + std::ignore = + form->input(password_input(password_field, HtmlText{"Your password"}, HtmlName{"current-password"})); + std::ignore = + form->button(SubmitButton{action_field, account_post_deactivate, HtmlText{"Deactivate my account"}}); + std::ignore = page.form(*form); + } + add_footer(page, frame); + return page; +} + +auto account_cross_signing_reset_page(AccountPageFrame const& frame) -> Page +{ + auto page = Page{HtmlText{"Reset your encryption identity"}}; + add_signed_in_as(page, frame); + page.paragraph(HtmlText{"Your application asked to replace your encryption identity (your cross-signing keys). If " + "you allow it, the people you talk to will see you as unverified until they verify you " + "again, and your other devices must be verified again."}); + page.paragraph( + HtmlText{"Allow it only if you started the reset in your application. The permission lasts 10 minutes " + "and is used by one reset."}); + if (auto form = session_form(frame); form.has_value()) + { + std::ignore = form->button(SubmitButton{action_field, account_post_approve_reset, HtmlText{"Allow the reset"}}); + std::ignore = page.form(*form); + } + add_footer(page, frame); + return page; +} + +auto account_result_page(AccountPageFrame const& frame, HtmlText title, HtmlText const& message) -> Page +{ + auto page = Page{std::move(title)}; + add_signed_in_as(page, frame); + page.paragraph(message); + add_footer(page, frame); + return page; +} + +auto account_signed_out_page(HtmlText title, HtmlText const& message, std::string_view account_url) -> Page +{ + auto page = Page{std::move(title)}; + page.paragraph(message); + std::ignore = page.link(HtmlText{"Sign in"}, account_url); + return page; +} + +} // namespace merovingian::oauth diff --git a/src/oauth/meson.build b/src/oauth/meson.build index 28bb17a2c..eeb8fb874 100644 --- a/src/oauth/meson.build +++ b/src/oauth/meson.build @@ -1,4 +1,5 @@ oauth_sources = files( + 'AccountPages.cpp', 'AsciiCase.cpp', 'AuthorizationPages.cpp', 'AuthorizationRedirect.cpp', diff --git a/tests/conformance/test_oauth_account_management_conformance.cpp b/tests/conformance/test_oauth_account_management_conformance.cpp new file mode 100644 index 000000000..24a183364 --- /dev/null +++ b/tests/conformance/test_oauth_account_management_conformance.cpp @@ -0,0 +1,260 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// +-------------------------------------------------------------------------+ +// | OAUTH 2.0 ACCOUNT MANAGEMENT CONFORMANCE TESTS | +// | | +// | Spec: Matrix Client-Server API v1.19 — "Account management" (OAuth | +// | 2.0 API) and "OAuth authentication" (the m.oauth UIA type) | +// | URL: ../../docs/matrix-v1.19-spec/client-server-api.md | +// +-------------------------------------------------------------------------+ +// +// The account management URL the metadata advertises, its `action` and `device_id` parameters, and the `m.oauth` stage +// of a replacing `POST /keys/device_signing/upload` from an OAuth session (ADR-0796, ADR-0797). + +#include "../support/CrossSigningFixture.hpp" +#include "../support/JsonTestSupport.hpp" +#include "../support/OAuthAccountPageSupport.hpp" +#include "../support/OAuthAuthorizationSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "../support/OAuthTokenSupport.hpp" +#include "../support/RegistrationToken.hpp" +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include + +#include +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace hs = merovingian::homeserver; + +constexpr auto alice_password = std::string_view{"AlicePass99!x"}; +constexpr auto alice_id = std::string_view{"@alice:example.org"}; + +struct Fixture final +{ + hs::ClientServerStartResult started; + std::string client_id; +}; + +[[nodiscard]] auto make_fixture() -> Fixture +{ + auto config = oauth_registration_config(true); + config.server().server_name = "example.org"; + enable_token_registration(config.security()); + auto started = hs::start_client_server(config); + REQUIRE(started.started); + REQUIRE( + hs::register_local_user(started.runtime.homeserver, "alice", alice_password, std::string{registration_token}) + .ok); + auto client_id = register_oauth_web_client( + started.runtime, R"(,"client_name":"Test App","grant_types":["authorization_code","refresh_token"])"); + REQUIRE_FALSE(client_id.empty()); + return {std::move(started), std::move(client_id)}; +} + +[[nodiscard]] auto upload(hs::ClientServerRuntime& rt, std::string const& token, std::string const& members) + -> hs::LocalHttpResponse +{ + return hs::handle_client_server_request( + rt, {"POST", "/_matrix/client/v3/keys/device_signing/upload", token, "{" + members + "}"}, false) + .response; +} + +[[nodiscard]] auto object_of(merovingian::canonicaljson::Object const& object, std::string_view key) + -> merovingian::canonicaljson::Object const* +{ + auto const* value = object_member(object, key); + return value == nullptr ? nullptr : std::get_if(&value->storage()); +} + +[[nodiscard]] auto string_array(merovingian::canonicaljson::Object const& object, std::string_view key) + -> std::vector +{ + auto out = std::vector{}; + auto const* array = object_member_as_array(object, key); + if (array == nullptr) + { + return out; + } + for (auto const& entry : *array) + { + if (auto const* text = std::get_if(&entry.storage()); text != nullptr) + { + out.push_back(*text); + } + } + return out; +} + +} // namespace + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Account management URL discovery; Account management URL actions +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#account-management-url-discovery +// ../../docs/matrix-v1.19-spec/client-server-api.md#account-management-url-actions +// +// The metadata "is extended to include the following optional fields": `account_management_actions_supported`, a +// "List of actions that the account management URL supports", and `account_management_uri`, "The URL where the user is +// able to access the account management capabilities of the server". The six Matrix-specific actions are listed. +SCENARIO("auth_metadata advertises the account management URL and the six Matrix actions", + "[conformance][client-server][oauth][oauth-account]") +{ + GIVEN("a running homeserver with the OAuth 2.0 API on") + { + auto fixture = make_fixture(); + + WHEN("the metadata is read and the advertised URL is opened") + { + auto const metadata = + hs::handle_client_server_request(fixture.started.runtime, + {"GET", "/_matrix/client/v1/auth_metadata", {}, {}}, false) + .response; + auto const body = parse_object(metadata.body); + auto const page = get_account(fixture.started.runtime, {}); + + THEN("the URL is an https URL this server answers, and every listed action is one of the six") + { + REQUIRE(metadata.status == 200U); + auto const* uri = string_member(body, "account_management_uri"); + REQUIRE(uri != nullptr); + REQUIRE(*uri == oauth_account_url); + auto const actions = string_array(body, "account_management_actions_supported"); + REQUIRE(actions == std::vector{"org.matrix.profile", "org.matrix.devices_list", + "org.matrix.device_view", "org.matrix.device_delete", + "org.matrix.account_deactivate", + "org.matrix.cross_signing_reset"}); + REQUIRE(page.status == 200U); + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Account management URL parameters +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#account-management-url-parameters +// +// `action`: "The action that the user wishes to take. Must match one of the actions advertised". `device_id`: "Actions +// which don't support the device ID will ignore it. If the org.matrix.device_view or org.matrix.device_delete actions +// are advertised as supported by the server then the server SHOULD support the device_id parameter." +SCENARIO("The account management URL takes action and device_id, and ignores the device for other actions", + "[conformance][client-server][oauth][oauth-account]") +{ + GIVEN("alice signed in through OAuth (device OAUTHDEV01) and signed in to the account pages") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + REQUIRE(oauth_sign_in(rt, fixture.client_id, "alice", alice_password).ok); + auto const signed_in = account_sign_in(rt, "alice", alice_password); + REQUIRE_FALSE(signed_in.form_token.empty()); + + WHEN("each action is opened, the device actions with her device") + { + auto const view = get_account(rt, "action=org.matrix.device_view&device_id=OAUTHDEV01", signed_in.browser); + auto const remove = + get_account(rt, "action=org.matrix.device_delete&device_id=OAUTHDEV01", signed_in.browser); + auto const list = get_account(rt, "action=org.matrix.devices_list&device_id=OAUTHDEV01", signed_in.browser); + auto const profile = get_account(rt, "action=org.matrix.profile&device_id=OAUTHDEV01", signed_in.browser); + auto const deactivate = get_account(rt, "action=org.matrix.account_deactivate", signed_in.browser); + auto const reset = get_account(rt, "action=org.matrix.cross_signing_reset", signed_in.browser); + + THEN("each is answered with its page, and the device appears only where the action takes it") + { + REQUIRE(view.status == 200U); + REQUIRE(view.body.find("OAUTHDEV01") != std::string::npos); + REQUIRE(remove.status == 200U); + REQUIRE(remove.body.find(R"(name="device_id" value="OAUTHDEV01")") != std::string::npos); + REQUIRE(list.status == 200U); + REQUIRE(list.body.find("Your devices") != std::string::npos); + REQUIRE(profile.status == 200U); + REQUIRE(profile.body.find("@alice:example.org") != std::string::npos); + REQUIRE(profile.body.find("OAUTHDEV01") == std::string::npos); + REQUIRE(deactivate.status == 200U); + REQUIRE(deactivate.body.find(R"(value="deactivate")") != std::string::npos); + REQUIRE(reset.status == 200U); + REQUIRE(reset.body.find(R"(value="approve_cross_signing_reset")") != std::string::npos); + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: OAuth authentication (m.oauth); Account management URL actions; POST /keys/device_signing/upload +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#oauth-authentication +// ../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3keysdevice_signingupload +// +// "the server returns a 401 response on the respective request, where the response body includes m.oauth in the flows +// list, and the m.oauth property in the params object has the structure shown below" (`url`). "Once the user has done +// so, the client submits an auth dict with just the session". `org.matrix.cross_signing_reset`: "Servers SHOULD use +// this action in the URL of the m.oauth UIA type." +SCENARIO( + "A replacing cross-signing upload from an OAuth session is the m.oauth stage, completed with the session alone", + "[conformance][client-server][oauth][oauth-account][oauth-uia]") +{ + GIVEN("alice signed in through OAuth, holding cross-signing keys") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const oauth = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + REQUIRE(oauth.ok); + REQUIRE(upload(rt, oauth.access_token, + make_cross_signing_set(std::string{alice_id}).selected_members(true, true, true)) + .status == 200U); + auto const replacement = make_cross_signing_set(std::string{alice_id}).master_member(); + + WHEN("she uploads a new master key, approves the reset on the account page, and retries with the session") + { + auto const challenge = upload(rt, oauth.access_token, replacement); + auto const body = parse_object(challenge.body); + auto const* session = string_member(body, "session"); + REQUIRE(session != nullptr); + auto const signed_in = account_sign_in(rt, "alice", alice_password); + auto const approved = + post_account(rt, + { + {"form_token", signed_in.form_token }, + {"action", "approve_cross_signing_reset"} + }, + signed_in.browser); + auto const completed = + upload(rt, oauth.access_token, replacement + R"(,"auth":{"session":")" + *session + R"("})"); + + THEN("the 401 lists m.oauth with the reset URL, and the session alone completes the stage") + { + // Spec: "the server returns a 401 response". + REQUIRE(challenge.status == 401U); + auto const* flows = object_member_as_array(body, "flows"); + REQUIRE(flows != nullptr); + REQUIRE(flows->size() == 1U); + auto const* flow = std::get_if(&flows->front().storage()); + REQUIRE(flow != nullptr); + // Spec: "the response body includes m.oauth in the flows list". + REQUIRE(string_array(*flow, "stages") == std::vector{"m.oauth"}); + auto const* params = object_of(body, "params"); + REQUIRE(params != nullptr); + auto const* oauth_params = object_of(*params, "m.oauth"); + REQUIRE(oauth_params != nullptr); + auto const* url = string_member(*oauth_params, "url"); + REQUIRE(url != nullptr); + // Spec SHOULD: the org.matrix.cross_signing_reset action in the URL of the m.oauth UIA type. + REQUIRE(*url == std::string{oauth_account_url} + "?action=org.matrix.cross_signing_reset"); + REQUIRE(approved.status == 200U); + // Spec: "the client submits an auth dict with just the session ... to complete the stage". + REQUIRE(completed.status == 200U); + } + } + } +} diff --git a/tests/conformance/test_route_query_conformance.cpp b/tests/conformance/test_route_query_conformance.cpp index 3885d48dd..3729e5ab7 100644 --- a/tests/conformance/test_route_query_conformance.cpp +++ b/tests/conformance/test_route_query_conformance.cpp @@ -109,7 +109,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", ""}, @@ -120,6 +120,8 @@ SCENARIO("every client route that matched its whole target answers a request wit {"POST", "/_merovingian/oauth2/authorize", ""}, {"POST", "/_merovingian/oauth2/token", ""}, {"POST", "/_merovingian/oauth2/revoke", ""}, + {"GET", "/_merovingian/account", ""}, + {"POST", "/_merovingian/account", ""}, {"POST", "/_matrix/client/v3/register/email/requestToken", "{}"}, {"POST", "/_matrix/client/v3/register/msisdn/requestToken", "{}"}, {"POST", "/_matrix/client/v3/register", "{}"}, diff --git a/tests/integration/test_oauth_account_pages_flow.cpp b/tests/integration/test_oauth_account_pages_flow.cpp new file mode 100644 index 000000000..1b8f25e84 --- /dev/null +++ b/tests/integration/test_oauth_account_pages_flow.cpp @@ -0,0 +1,758 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// `GET` and `POST /_merovingian/account` through the client-server dispatcher: the sign-in form and its session +// (ADR-0796), each account management action with its effect checked in the store, the form protections (Origin, the +// cookie, the form token), the URL parameters, and the `m.oauth` stage of a replacing cross-signing upload (ADR-0797). +// No browser runs here: what a browser does with the cookie, the form or the policy is not tested. + +#include "../support/CrossSigningFixture.hpp" +#include "../support/OAuthAccountPageSupport.hpp" +#include "../support/OAuthAuthorizationSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "../support/OAuthTokenSupport.hpp" +#include "../support/RegistrationToken.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/homeserver/AccountSessionStore.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/CrossSigningResetApprovals.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/homeserver/OAuthClock.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace db = merovingian::database; +namespace hs = merovingian::homeserver; +using Fields = std::vector>; + +constexpr auto alice_password = std::string_view{"AlicePass99!x"}; +constexpr auto alice_id = std::string_view{"@alice:example.org"}; +constexpr auto bob_password = std::string_view{"BobPass99!xyz"}; +constexpr auto bob_id = std::string_view{"@bob:example.org"}; +constexpr auto upload_path = std::string_view{"/_matrix/client/v3/keys/device_signing/upload"}; +constexpr auto reset_url = + std::string_view{"https://matrix.example.org/_merovingian/account?action=org.matrix.cross_signing_reset"}; + +[[nodiscard]] auto account_config(bool oauth_enabled = true) -> merovingian::config::Config +{ + auto config = oauth_registration_config(oauth_enabled); + config.server().server_name = "example.org"; + enable_token_registration(config.security()); + return config; +} + +// alice and bob, and a registered web client named "Test App". +struct Fixture final +{ + hs::ClientServerStartResult started; + std::string client_id; +}; + +[[nodiscard]] auto make_fixture(bool oauth_enabled = true) -> Fixture +{ + auto started = hs::start_client_server(account_config(oauth_enabled)); + REQUIRE(started.started); + auto& homeserver = started.runtime.homeserver; + REQUIRE(hs::register_local_user(homeserver, "alice", alice_password, std::string{registration_token}).ok); + REQUIRE(hs::register_local_user(homeserver, "bob", bob_password, std::string{registration_token}).ok); + auto client_id = std::string{}; + if (oauth_enabled) + { + client_id = register_oauth_web_client( + started.runtime, R"(,"client_name":"Test App","grant_types":["authorization_code","refresh_token"])"); + REQUIRE_FALSE(client_id.empty()); + } + return {std::move(started), std::move(client_id)}; +} + +[[nodiscard]] auto send(hs::ClientServerRuntime& rt, std::string method, std::string target, std::string token, + std::string body = {}) -> hs::LocalHttpResponse +{ + return hs::handle_client_server_request(rt, + {std::move(method), std::move(target), std::move(token), std::move(body)}, + /*can_wait=*/false) + .response; +} + +[[nodiscard]] auto contains(std::string_view text, std::string_view part) -> bool +{ + return text.find(part) != std::string_view::npos; +} + +[[nodiscard]] auto has_header(hs::LocalHttpResponse const& response, std::string_view prefix) -> bool +{ + return std::ranges::any_of(response.headers, [prefix](auto const& header) { + return header.first.starts_with(prefix); + }); +} + +[[nodiscard]] auto member(hs::LocalHttpResponse const& response, std::string_view name) -> std::string +{ + auto const body = parse_object(response.body); + auto const* value = string_member(body, name); + return value == nullptr ? std::string{} : *value; +} + +[[nodiscard]] auto password_login(hs::ClientServerRuntime& rt, std::string_view user, std::string_view password, + std::string_view device_id) -> std::string +{ + auto const response = send(rt, "POST", "/_matrix/client/v3/login", {}, + R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":")" + + std::string{user} + R"("},"password":")" + std::string{password} + + R"(","device_id":")" + std::string{device_id} + R"("})"); + return response.status == 200U ? member(response, "access_token") : std::string{}; +} + +[[nodiscard]] auto whoami_status(hs::ClientServerRuntime& rt, std::string const& token) -> std::uint16_t +{ + return static_cast(send(rt, "GET", "/_matrix/client/v3/account/whoami", token).status); +} + +[[nodiscard]] auto holds_device(hs::ClientServerRuntime const& rt, std::string_view user, std::string_view device) + -> bool +{ + return db::has_user_device(rt.homeserver.database.persistent_store, user, device); +} + +[[nodiscard]] auto audit_count(hs::ClientServerRuntime const& rt, std::string_view event_type) -> std::size_t +{ + return static_cast(std::ranges::count_if(rt.homeserver.database.audit_events, [&](auto const& event) { + return event.event_type == event_type; + })); +} + +// A form of a signed-in page: `action` and the session's form token, with `extra` fields. +[[nodiscard]] auto session_form(AccountSignedIn const& signed_in, std::string_view action, Fields extra = {}) -> Fields +{ + extra.emplace_back("form_token", signed_in.form_token); + extra.emplace_back("action", std::string{action}); + return extra; +} + +[[nodiscard]] auto approval_held(hs::ClientServerRuntime& rt, std::string_view user) -> bool +{ + return rt.homeserver.cross_signing_reset_approvals.holds(user, hs::oauth_wall_clock_ms()); +} + +} // namespace + +SCENARIO("A browser signs in to the account pages and gets a short session of its own", + "[integration][oauth][oauth-account]") +{ + GIVEN("alice and a browser with no session") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + + WHEN("it opens the page and signs in") + { + auto const first = get_account(rt, {}); + auto const signed_in = account_sign_in(rt, "alice", alice_password); + auto const overview = get_account(rt, {}, signed_in.browser); + + THEN("the sign-in form, then a 303 setting a strict host cookie, then the overview naming alice") + { + REQUIRE(first.status == 200U); + CHECK(first.page); + CHECK(contains(first.body, "Sign in to manage your account")); + CHECK_FALSE(has_header(first, "Access-Control-")); + CHECK(response_header(first, "Cache-Control") == "no-store"); + CHECK(contains(response_header(first, "Content-Security-Policy"), "form-action 'self'")); + + REQUIRE(signed_in.sign_in.status == 303U); + CHECK(response_header(signed_in.sign_in, "Location") == oauth_account_url); + CHECK_FALSE(has_header(signed_in.sign_in, "Access-Control-")); + auto const set_cookie = response_header(signed_in.sign_in, "Set-Cookie"); + CHECK(set_cookie.starts_with("__Host-mv-account=")); + CHECK(contains(set_cookie, "; Secure")); + CHECK(contains(set_cookie, "; HttpOnly")); + CHECK(contains(set_cookie, "SameSite=Strict")); + CHECK(contains(set_cookie, "Max-Age=900")); + CHECK(contains(set_cookie, "Path=/")); + REQUIRE(signed_in.browser.cookie.size() == 64U); + + REQUIRE(overview.status == 200U); + CHECK(contains(overview.body, "@alice:example.org")); + CHECK_FALSE(has_header(overview, "Access-Control-")); + REQUIRE(signed_in.form_token.size() == 64U); + CHECK(signed_in.form_token != signed_in.browser.cookie); + CHECK(rt.homeserver.account_sessions.live_count_for_user(alice_id, hs::oauth_wall_clock_ms()) == 1U); + } + } + } +} + +SCENARIO("A wrong password on the account page shares the login throttle with POST /login", + "[integration][oauth][oauth-account]") +{ + GIVEN("alice") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + + WHEN("wrong passwords are tried until the page throttles, then POST /login is tried from the same address") + { + auto const first = account_sign_in(rt, "alice", "WrongPass99!x"); + auto last = first.sign_in; + for (auto attempt = 0; attempt < 5; ++attempt) + { + last = account_sign_in(rt, "alice", "WrongPass99!x").sign_in; + } + auto legacy_request = hs::LocalHttpRequest{ + "POST", + "/_matrix/client/v3/login", + {}, + R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":"alice"},"password":"AlicePass99!x"})"}; + legacy_request.remote_addr = AccountBrowser{}.remote_addr; + legacy_request.headers.push_back({"Content-Type", "application/json"}); + auto const legacy = hs::handle_client_server_request(rt, legacy_request, false).response; + + THEN("the first is a 401 form keeping no password, the last a 429, and /login is throttled too") + { + CHECK(first.sign_in.status == 401U); + CHECK(contains(first.sign_in.body, "do not match an account")); + CHECK_FALSE(contains(first.sign_in.body, "WrongPass99!x")); + CHECK(first.browser.cookie.empty()); + CHECK(last.status == 429U); + CHECK_FALSE(response_header(last, "Retry-After").empty()); + CHECK(legacy.status == 429U); + } + } + } +} + +SCENARIO("The account page carries action and device_id through the sign-in and never shows the query unescaped", + "[integration][oauth][oauth-account]") +{ + GIVEN("alice signed in to a client through OAuth, so she holds device OAUTHDEV01") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + REQUIRE(oauth_sign_in(rt, fixture.client_id, "alice", alice_password).ok); + + WHEN("a device page is opened with no session, signed in to, and hostile queries are sent") + { + auto const form = get_account(rt, "action=org.matrix.device_view&device_id=OAUTHDEV01"); + auto const profile_form = get_account(rt, "action=org.matrix.profile&device_id=OAUTHDEV01"); + auto const signed_in = account_sign_in(rt, "alice", alice_password, + { + {"next_action", "org.matrix.device_view"}, + {"next_device_id", "OAUTHDEV01" }, + }); + auto const device_page = + get_account(rt, "action=org.matrix.device_view&device_id=OAUTHDEV01", signed_in.browser); + auto const hostile_form = + get_account(rt, "action=%3Cscript%3Ealert(1)%3C%2Fscript%3E&device_id=%22%3E%3Cb%3E"); + auto const hostile_signed_in = get_account( + rt, "action=org.matrix.device_view&device_id=%3Cscript%3Ealert(1)%3C%2Fscript%3E", signed_in.browser); + auto const unknown_action = get_account(rt, "action=org.matrix.nonsense", signed_in.browser); + + THEN("the form carries both, the sign-in lands on that page, and nothing hostile is reflected") + { + REQUIRE(form.status == 200U); + CHECK(contains(form.body, R"(name="next_action" value="org.matrix.device_view")")); + CHECK(contains(form.body, R"(name="next_device_id" value="OAUTHDEV01")")); + CHECK(contains(profile_form.body, R"(name="next_action" value="org.matrix.profile")")); + CHECK_FALSE(contains(profile_form.body, "next_device_id")); + + REQUIRE(signed_in.sign_in.status == 303U); + CHECK(response_header(signed_in.sign_in, "Location") == + std::string{oauth_account_url} + "?action=org.matrix.device_view&device_id=OAUTHDEV01"); + REQUIRE(device_page.status == 200U); + CHECK(contains(device_page.body, "OAUTHDEV01")); + CHECK(contains(device_page.body, "Test App")); + + CHECK(hostile_form.status == 200U); + CHECK_FALSE(contains(hostile_form.body, "&"}; +constexpr auto markup_escaped = std::string_view{""><script>alert('x')</script>&amp;"}; +// U+202E RIGHT-TO-LEFT OVERRIDE. +constexpr auto bidi_override = std::string_view{"\xE2\x80\xAE"}; +constexpr auto account_url = std::string_view{"https://matrix.example.org/_merovingian/account"}; +constexpr auto form_token = std::string_view{"00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff"}; + +[[nodiscard]] auto with_bidi(std::string_view text) -> std::string +{ + auto value = std::string{bidi_override}; + value.append(text); + return value; +} + +[[nodiscard]] auto contains(std::string_view haystack, std::string_view needle) -> bool +{ + return haystack.find(needle) != std::string_view::npos; +} + +[[nodiscard]] auto count(std::string_view haystack, std::string_view needle) -> std::size_t +{ + auto found = std::size_t{0U}; + for (auto at = haystack.find(needle); at != std::string_view::npos; at = haystack.find(needle, at + 1U)) + { + ++found; + } + return found; +} + +auto require_no_injection(std::string_view html) -> void +{ + REQUIRE_FALSE(contains(html, " AccountPageFrame +{ + return AccountPageFrame{server, user, token, account_url}; +} + +} // namespace + +SCENARIO("The account sign-in form escapes the server and the username and carries only a known action", + "[oauth][account-page][security]") +{ + GIVEN("a server name and a username holding markup, and a device action with a device") + { + auto const server = std::string{"example.org"} + std::string{markup}; + auto input = AccountSignInInput{}; + input.server_name = server; + input.username = markup; + input.next_action = "org.matrix.device_view"; + input.next_device_id = "ABCDEFGH"; + + WHEN("the form is rendered") + { + auto const html = merovingian::oauth::account_sign_in_page(input).render(); + + THEN("both values appear escaped and the action and device ride in hidden fields") + { + require_no_injection(html); + CHECK(count(html, markup_escaped) == 2U); + CHECK(contains(html, R"(action="/_merovingian/account")")); + CHECK(contains(html, R"(name="next_action" value="org.matrix.device_view")")); + CHECK(contains(html, R"(name="next_device_id" value="ABCDEFGH")")); + CHECK(contains(html, R"(name="action" value="sign_in")")); + CHECK_FALSE(contains(html, "form_token")); + } + } + } + + GIVEN("an unknown action, a device for an action that takes none, and values with an override character") + { + auto const server = with_bidi("example.org"); + auto const username = with_bidi("alice"); + auto unknown = AccountSignInInput{}; + unknown.server_name = "example.org"; + unknown.next_action = markup; + unknown.next_device_id = "ABCDEFGH"; + auto profile = AccountSignInInput{}; + profile.server_name = "example.org"; + profile.next_action = "org.matrix.profile"; + profile.next_device_id = "ABCDEFGH"; + auto hidden = AccountSignInInput{}; + hidden.server_name = server; + hidden.username = username; + + WHEN("each form is rendered") + { + auto const unknown_html = merovingian::oauth::account_sign_in_page(unknown).render(); + auto const profile_html = merovingian::oauth::account_sign_in_page(profile).render(); + auto const hidden_html = merovingian::oauth::account_sign_in_page(hidden).render(); + + THEN("nothing unknown is carried, the device only with a device action, and the fallback text is shown") + { + require_no_injection(unknown_html); + CHECK_FALSE(contains(unknown_html, "next_action")); + CHECK_FALSE(contains(unknown_html, "next_device_id")); + CHECK(contains(profile_html, R"(name="next_action" value="org.matrix.profile")")); + CHECK_FALSE(contains(profile_html, "next_device_id")); + require_no_injection(hidden_html); + CHECK(contains(hidden_html, "Sign in with your account on this server to manage it.")); + CHECK_FALSE(contains(hidden_html, "alice")); + } + } + } +} + +SCENARIO("Every signed-in account page escapes the user, the server and every device field", + "[oauth][account-page][security]") +{ + GIVEN("a frame and a device whose every client-chosen value holds markup") + { + auto const server = std::string{"example.org"} + std::string{markup}; + auto const user = std::string{"@alice:example.org"} + std::string{markup}; + auto const frame = frame_with(server, user, form_token); + auto const device = AccountDeviceRow{markup, markup, true, markup}; + auto const devices = std::array{device}; + + WHEN("each page is rendered") + { + auto const pages = std::array{ + merovingian::oauth::account_overview_page(frame, markup).render(), + merovingian::oauth::account_devices_page(frame, devices).render(), + merovingian::oauth::account_device_page(frame, device).render(), + merovingian::oauth::account_device_delete_page(frame, device).render(), + merovingian::oauth::account_unknown_device_page(frame).render(), + merovingian::oauth::account_password_page(frame, HtmlText{"An error."}).render(), + merovingian::oauth::account_deactivate_page(frame, std::nullopt).render(), + merovingian::oauth::account_cross_signing_reset_page(frame).render(), + merovingian::oauth::account_result_page(frame, HtmlText{"Done"}, HtmlText{"It was done."}).render(), + }; + + THEN("nothing is injected, every form carries the form token, and links keep their shape") + { + for (auto const& html : pages) + { + require_no_injection(html); + CHECK(contains(html, markup_escaped)); + CHECK(count(html, "An error.)")); + CHECK(contains(pages.at(6U), R"(name="action" value="deactivate")")); + CHECK(contains(pages.at(7U), R"(name="action" value="approve_cross_signing_reset")")); + } + } + } +} + +SCENARIO("An account page shows fixed text for a value it cannot show, and no form without a form token", + "[oauth][account-page][security]") +{ + GIVEN("a frame and a device holding override characters, and a frame whose form token cannot be shown") + { + auto const user = with_bidi("@alice:example.org"); + auto const name = with_bidi("Phone"); + auto const client = with_bidi("Test App"); + auto const frame = frame_with("example.org", user, form_token); + auto const device = AccountDeviceRow{"ABCDEFGH", name, true, client}; + auto const no_token = with_bidi("token"); + auto const tokenless = frame_with("example.org", "@alice:example.org", no_token); + + WHEN("the device page and the token-less pages are rendered") + { + auto const device_html = merovingian::oauth::account_device_page(frame, device).render(); + auto const overview = merovingian::oauth::account_overview_page(tokenless, std::nullopt).render(); + auto const reset = merovingian::oauth::account_cross_signing_reset_page(tokenless).render(); + auto const remove = merovingian::oauth::account_device_delete_page(tokenless, device).render(); + + THEN("fixed text replaces each value, and a page with no token shows no form") + { + require_no_injection(device_html); + CHECK(contains(device_html, "an account that cannot be shown")); + CHECK(contains(device_html, "A name that cannot be shown")); + CHECK(contains(device_html, "An application with no name")); + for (auto const* html : {&overview, &reset, &remove}) + { + require_no_injection(*html); + CHECK_FALSE(contains(*html, " +#include + +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::homeserver::AccountSessionStore; + +constexpr auto start_ms = std::uint64_t{5'000'000U}; +constexpr auto alice = std::string_view{"@alice:example.org"}; +constexpr auto bob = std::string_view{"@bob:example.org"}; + +[[nodiscard]] auto secret_of(std::variant const& created) -> std::string +{ + REQUIRE(std::holds_alternative(created)); + return std::get(created); +} + +} // namespace + +SCENARIO("An account-page session is found by its secret alone and lives a fixed 15 minutes", + "[oauth][oauth-account-session]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("a store holding one session of alice") + { + auto store = AccountSessionStore{}; + auto const secret = secret_of(store.create(alice, start_ms)); + + WHEN("it is looked up just before its end, at its end, and with other secrets") + { + auto const live = store.find(secret, start_ms + AccountSessionStore::lifetime_ms - 1U); + auto const wrong = store.find(std::string(64U, 'a'), start_ms + 1U); + auto const empty = store.find({}, start_ms + 1U); + auto const truncated = store.find(std::string_view{secret}.substr(0U, 63U), start_ms + 1U); + auto const ended = store.find(secret, start_ms + AccountSessionStore::lifetime_ms); + + THEN("only the secret finds it, a use does not extend it, and the secret is 64 hex digits") + { + CHECK(secret.size() == 64U); + CHECK(secret.find_first_not_of("0123456789abcdef") == std::string::npos); + REQUIRE(live.has_value()); + CHECK(live->user_id == alice); + CHECK(live->created_at_ms == start_ms); + CHECK(live->expires_at_ms == start_ms + AccountSessionStore::lifetime_ms); + CHECK_FALSE(wrong.has_value()); + CHECK_FALSE(empty.has_value()); + CHECK_FALSE(truncated.has_value()); + CHECK_FALSE(ended.has_value()); + CHECK(store.size() == 0U); + } + } + } +} + +SCENARIO("An account-page session ends alone, or with every session of its user", "[oauth][oauth-account-session]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("two sessions of alice and one of bob") + { + auto store = AccountSessionStore{}; + auto const first = secret_of(store.create(alice, start_ms)); + auto const second = secret_of(store.create(alice, start_ms + 1U)); + auto const bobs = secret_of(store.create(bob, start_ms + 2U)); + + WHEN("one of alice's is ended, then all of alice's") + { + auto const ended_one = store.end(first, start_ms + 3U); + auto const ended_again = store.end(first, start_ms + 3U); + auto const second_after_one = store.find(second, start_ms + 3U).has_value(); + auto const ended_user = store.end_user(alice); + + THEN("each ends what it names and nothing of bob's") + { + CHECK(ended_one); + CHECK_FALSE(ended_again); + CHECK(second_after_one); + CHECK(ended_user == 1U); + CHECK_FALSE(store.find(second, start_ms + 3U).has_value()); + CHECK(store.find(bobs, start_ms + 3U).has_value()); + CHECK(store.live_count_for_user(alice, start_ms + 3U) == 0U); + CHECK(store.live_count_for_user(bob, start_ms + 3U) == 1U); + } + } + } +} + +SCENARIO("A fifth sign-in of a user replaces that user's oldest session, never another user's", + "[oauth][oauth-account-session]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("alice at the per-user cap and one session of bob") + { + auto store = AccountSessionStore{}; + auto alice_secrets = std::vector{}; + for (auto index = std::size_t{0U}; index < AccountSessionStore::max_sessions_per_user; ++index) + { + alice_secrets.push_back(secret_of(store.create(alice, start_ms + index))); + } + auto const bobs = secret_of(store.create(bob, start_ms + 10U)); + + WHEN("alice signs in once more") + { + auto const newest = secret_of(store.create(alice, start_ms + 20U)); + + THEN("her oldest session is gone, the others and bob's stay") + { + CHECK_FALSE(store.find(alice_secrets.front(), start_ms + 21U).has_value()); + for (auto index = std::size_t{1U}; index < alice_secrets.size(); ++index) + { + CHECK(store.find(alice_secrets.at(index), start_ms + 21U).has_value()); + } + CHECK(store.find(newest, start_ms + 21U).has_value()); + CHECK(store.find(bobs, start_ms + 21U).has_value()); + CHECK(store.live_count_for_user(alice, start_ms + 21U) == AccountSessionStore::max_sessions_per_user); + } + } + } +} + +SCENARIO("A full account-session store refuses a new user's sign-in until a session expires", + "[oauth][oauth-account-session]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("a store holding max_sessions sessions of other users") + { + auto store = AccountSessionStore{}; + for (auto index = std::size_t{0U}; index < AccountSessionStore::max_sessions; ++index) + { + std::ignore = secret_of(store.create("@user" + std::to_string(index) + ":example.org", start_ms)); + } + + WHEN("alice signs in while they live, and again once they have expired, and an empty user is given") + { + auto const refused = store.create(alice, start_ms + 1U); + auto const no_user = store.create({}, start_ms + 1U); + auto const later = store.create(alice, start_ms + AccountSessionStore::lifetime_ms); + + THEN("the first is store_full, the empty user no_user, and the later one succeeds after the purge") + { + REQUIRE(std::holds_alternative(refused)); + CHECK(std::get(refused) == AccountSessionStore::Refusal::store_full); + REQUIRE(std::holds_alternative(no_user)); + CHECK(std::get(no_user) == AccountSessionStore::Refusal::no_user); + CHECK(std::holds_alternative(later)); + CHECK(store.size() == 1U); + } + } + } +} + +SCENARIO("The form token is bound to its session and is not the cookie value", "[oauth][oauth-account-session]") +{ + REQUIRE(sodium_init() >= 0); + GIVEN("the secrets of two sessions") + { + auto store = AccountSessionStore{}; + auto const first = secret_of(store.create(alice, start_ms)); + auto const second = secret_of(store.create(bob, start_ms)); + + WHEN("their form tokens are derived and compared") + { + auto const token = AccountSessionStore::form_token(first); + auto const other = AccountSessionStore::form_token(second); + auto const of_empty = AccountSessionStore::form_token({}); + + THEN("each matches only its own session, and none is the secret") + { + REQUIRE(token.has_value()); + REQUIRE(other.has_value()); + CHECK(token->size() == 64U); + CHECK(*token != first); + CHECK(*token != *other); + CHECK(AccountSessionStore::form_token(first) == token); + CHECK(AccountSessionStore::form_token_matches(first, *token)); + CHECK_FALSE(AccountSessionStore::form_token_matches(first, *other)); + CHECK_FALSE(AccountSessionStore::form_token_matches(second, *token)); + CHECK_FALSE(AccountSessionStore::form_token_matches(first, first)); + CHECK_FALSE(AccountSessionStore::form_token_matches(first, {})); + CHECK_FALSE(AccountSessionStore::form_token_matches(first, std::string_view{*token}.substr(0U, 63U))); + CHECK_FALSE(of_empty.has_value()); + } + } + } +} diff --git a/tests/unit/test_oauth_cross_signing_reset_approvals.cpp b/tests/unit/test_oauth_cross_signing_reset_approvals.cpp new file mode 100644 index 000000000..ff6e30932 --- /dev/null +++ b/tests/unit/test_oauth_cross_signing_reset_approvals.cpp @@ -0,0 +1,160 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// ADR-0797: the cross-signing reset approvals the account page grants. One per user, ten minutes, taken by one +// replacing upload and given back when that upload is not stored, bounded. + +#include "merovingian/homeserver/CrossSigningResetApprovals.hpp" + +#include + +#include +#include +#include +#include + +namespace +{ + +using merovingian::homeserver::CrossSigningResetApprovals; + +constexpr auto start_ms = std::uint64_t{9'000'000U}; +constexpr auto alice = std::string_view{"@alice:example.org"}; +constexpr auto bob = std::string_view{"@bob:example.org"}; + +} // namespace + +SCENARIO("A cross-signing reset approval lives ten minutes and is taken once", "[oauth][oauth-reset-approval]") +{ + GIVEN("an approval of alice") + { + auto approvals = CrossSigningResetApprovals{}; + REQUIRE(approvals.approve(alice, start_ms)); + + WHEN("it is read, taken twice, and read at its end") + { + auto const held_before_end = + approvals.holds(alice, start_ms + CrossSigningResetApprovals::lifetime_ms - 1U); + auto const bob_holds = approvals.holds(bob, start_ms + 1U); + auto const first = approvals.take(alice, start_ms + 1U); + auto const second = approvals.take(alice, start_ms + 2U); + + THEN("it is alice's alone, the first take returns its expiry and the second finds nothing") + { + CHECK(held_before_end); + CHECK_FALSE(bob_holds); + REQUIRE(first.has_value()); + CHECK(*first == start_ms + CrossSigningResetApprovals::lifetime_ms); + CHECK_FALSE(second.has_value()); + CHECK(approvals.size() == 0U); + } + } + + WHEN("it is read at its end") + { + auto const held = approvals.holds(alice, start_ms + CrossSigningResetApprovals::lifetime_ms); + auto const taken = approvals.take(alice, start_ms + CrossSigningResetApprovals::lifetime_ms); + + THEN("it has expired") + { + CHECK_FALSE(held); + CHECK_FALSE(taken.has_value()); + } + } + } +} + +SCENARIO("A taken approval goes back only while it is live and the user has not approved again", + "[oauth][oauth-reset-approval]") +{ + GIVEN("an approval of alice taken by an upload") + { + auto approvals = CrossSigningResetApprovals{}; + REQUIRE(approvals.approve(alice, start_ms)); + auto const expiry = approvals.take(alice, start_ms + 1U); + REQUIRE(expiry.has_value()); + + WHEN("the upload is refused and gives it back") + { + approvals.restore(alice, *expiry, start_ms + 2U); + + THEN("alice holds it again with its first expiry") + { + CHECK(approvals.holds(alice, start_ms + 3U)); + CHECK(approvals.take(alice, start_ms + 3U) == expiry); + } + } + + WHEN("it is given back after its expiry") + { + approvals.restore(alice, *expiry, *expiry); + + THEN("nothing is held") + { + CHECK_FALSE(approvals.holds(alice, *expiry)); + CHECK(approvals.size() == 0U); + } + } + + WHEN("alice approves again before the upload gives it back") + { + REQUIRE(approvals.approve(alice, start_ms + 100U)); + approvals.restore(alice, *expiry, start_ms + 101U); + + THEN("the newer approval stays") + { + CHECK(approvals.take(alice, start_ms + 102U) == + start_ms + 100U + CrossSigningResetApprovals::lifetime_ms); + } + } + } +} + +SCENARIO("An approval is withdrawn, replaced by a newer one, and bounded", "[oauth][oauth-reset-approval]") +{ + GIVEN("approvals of alice and bob") + { + auto approvals = CrossSigningResetApprovals{}; + REQUIRE(approvals.approve(alice, start_ms)); + REQUIRE(approvals.approve(bob, start_ms)); + + WHEN("alice's is withdrawn and bob approves again") + { + approvals.withdraw(alice); + REQUIRE(approvals.approve(bob, start_ms + 50U)); + + THEN("alice holds none and bob one, with the later expiry") + { + CHECK_FALSE(approvals.holds(alice, start_ms + 1U)); + CHECK(approvals.size() == 1U); + CHECK(approvals.take(bob, start_ms + 51U) == start_ms + 50U + CrossSigningResetApprovals::lifetime_ms); + } + } + } + + GIVEN("max_approvals approvals of other users") + { + auto approvals = CrossSigningResetApprovals{}; + for (auto index = std::size_t{0U}; index < CrossSigningResetApprovals::max_approvals; ++index) + { + REQUIRE(approvals.approve("@user" + std::to_string(index) + ":example.org", start_ms)); + } + + WHEN("alice approves while they live, then after they expire, and an empty user approves") + { + auto const refused = approvals.approve(alice, start_ms + 1U); + auto const repeat = approvals.approve("@user0:example.org", start_ms + 1U); + auto const empty = approvals.approve({}, start_ms + 1U); + auto const later = approvals.approve(alice, start_ms + CrossSigningResetApprovals::lifetime_ms); + + THEN("a new user is refused at the cap, a held user may approve again, and the cap frees on expiry") + { + CHECK_FALSE(refused); + CHECK(repeat); + CHECK_FALSE(empty); + CHECK(later); + CHECK(approvals.holds(alice, start_ms + CrossSigningResetApprovals::lifetime_ms)); + } + } + } +} From 10afc041099948293aaa40ba7b410de5b544c19c Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 08:18:24 +0000 Subject: [PATCH 17/42] Document the OAuth 2.0 account pages and record ADR-0796 to ADR-0798 The user manual, auth, HTTP, audit and client-server API guides, the module guidance, the security coding rules and the review skill now describe the account pages and the m.oauth stage. The changelog lists them under 1.1.0. Co-Authored-By: Claude Opus 5.5 --- .../references/module-invariants.md | 5 +- CHANGELOG.md | 20 +++-- ...und-to-a-strict-cookie-and-a-form-token.md | 77 +++++++++++++++++++ ...he-m-oauth-stage-and-a-one-use-approval.md | 74 ++++++++++++++++++ ...assword-change-ends-account-page-access.md | 72 +++++++++++++++++ docs/adr/index.md | 3 + docs/auth-identity.md | 50 ++++++++++-- docs/http-transport.md | 8 ++ docs/matrix-v1.19-client-server-api.md | 4 +- docs/observability-audit.md | 13 ++++ docs/security-coding-rules.md | 13 +++- docs/todos/capability-gaps.md | 2 +- docs/todos/oauth-2-0-api.md | 9 ++- docs/user-manual.md | 36 ++++++--- src/homeserver/AGENTS.md | 33 +++++++- src/oauth/AGENTS.md | 5 +- tests/conformance/AGENTS.md | 1 + tests/support/AGENTS.md | 1 + 18 files changed, 395 insertions(+), 31 deletions(-) create mode 100644 docs/adr/0796-the-account-pages-keep-a-fixed-15-minute-session-in-memory-bound-to-a-strict-cookie-and-a-form-token.md create mode 100644 docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md create mode 100644 docs/adr/0798-account-page-actions-share-the-client-api-cores-and-every-password-change-ends-account-page-access.md diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index f436525e8..8ba6c0eac 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -192,7 +192,10 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that `verify_login_credentials` and a session-less account made only by `create_local_account` (ADR-0783); a page is marked `LocalHttpResponse::page` and gets no CORS header (ADR-0785); an OAuth target's query is never logged (ADR-0786). A grant is one transaction, a session ends only through `end_device_session_and_announce`, and every - UIA endpoint calls `oauth_session_uia_refusal` first (ADR-0792, ADR-0794, ADR-0795). + UIA endpoint calls `oauth_session_uia_refusal` first (ADR-0792, ADR-0794, ADR-0795). Account-page sessions and + reset approvals live only in `AccountSessionStore` and `CrossSigningResetApprovals`; a page action calls the client + API's own function; a password change, reset or deactivation calls `end_account_page_access`; a taken approval is + spent only after the keys are stored (ADR-0796 to ADR-0798). `src/homeserver/AGENTS.md#OAuth 2.0 API (ADR-0760, ADR-0773)` - Worker frames are untrusted. Relayed PDUs are re-verified with main's resolver **before** taking `runtime.mutex`, and the envelope is rebuilt from the verified event (ADR-0171). diff --git a/CHANGELOG.md b/CHANGELOG.md index fdf2defb1..6d4cf40e6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -52,11 +52,21 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) the other kind of session, before the token is spent (ADR-0792, ADR-0793). * Endpoints that ask for User-Interactive Authentication answer an OAuth session `403 M_FORBIDDEN` naming the account page; application services are not refused (ADR-0794). +* `GET` and `POST /_merovingian/account` serve the account pages: sign-in, devices, device sign-out, password + change, deactivation and cross-signing reset approval, with all six spec actions advertised (ADR-0796). +* An account-page session lives a fixed 15 minutes in memory behind a strict `__Host-` cookie and a form token; its + sign-in shares the `POST /login` throttle (ADR-0796). +* An OAuth session replaces its cross-signing keys through the `m.oauth` stage: one approval on the account page, + valid 10 minutes, spent only by a stored upload (ADR-0797). +* Each account-page action calls the client API's own function; a page password change logs every session out and + keeps the devices (ADR-0798). ## Security Fixes * The query of a `/_merovingian/oauth2/*` or `/_merovingian/account*` request is never logged, so a state, code or login hint cannot reach the log (ADR-0786). +* Every password change, reset and deactivation now ends the user's account-page sessions and withdraws a + cross-signing reset approval (ADR-0798). * A response header that would frame the message (`Content-Length`, `Connection`, ...) or holds CR or LF now turns the response into a 500 instead of being written or silently dropped (ADR-0767). @@ -73,11 +83,11 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Release notes 1.1.0 is in development. A configuration that sets any `server.oidc.*` key is now refused at start-up: remove those -keys and set `server.oauth.enabled` instead (ADR-0764). The authorisation, token and revocation endpoints are -served; the account page is not yet, so a user signed in through OAuth cannot change a password or delete a device -there: leave `server.oauth.enabled` off until then. 1.1.0 migrates the database: on first start it applies -migration 002, which adds two empty tables and changes no existing one. A 1.0.x server refuses the migrated -database, so back it up before upgrading if you may need to go back. +keys and set `server.oauth.enabled` instead (ADR-0764). The authorisation, token and revocation endpoints and the +account pages at `/_merovingian/account` are served; a user signed in through OAuth changes a password, signs out a +device, deactivates the account or approves a cross-signing reset there. 1.1.0 migrates the database: on first +start it applies migration 002, which adds two empty tables and changes no existing one. A 1.0.x server refuses the +migrated database, so back it up before upgrading if you may need to go back. # Version 1.0.2 diff --git a/docs/adr/0796-the-account-pages-keep-a-fixed-15-minute-session-in-memory-bound-to-a-strict-cookie-and-a-form-token.md b/docs/adr/0796-the-account-pages-keep-a-fixed-15-minute-session-in-memory-bound-to-a-strict-cookie-and-a-form-token.md new file mode 100644 index 000000000..59257cf4f --- /dev/null +++ b/docs/adr/0796-the-account-pages-keep-a-fixed-15-minute-session-in-memory-bound-to-a-strict-cookie-and-a-form-token.md @@ -0,0 +1,77 @@ +# The account pages keep a fixed 15-minute session in memory, bound to a strict cookie and a form token + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 8 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) (proposal P6) + +## Context and Problem Statement + +The spec puts all account management of an OAuth 2.0 user in the homeserver's web UI ("Account management"): +`account_management_uri` with the six `org.matrix.*` actions. The pages at `/_merovingian/account` let a user sign +out a device, change the password, deactivate the account and approve a cross-signing reset. Unlike the authorisation +pages (ADR-0787), they need to remember a signed-in user across a few page loads. How is that session held and how is a +form post tied to it? + +## Decision Drivers + +* A session that outlives its use is a standing credential in a browser. +* A form post must not be forgeable from another site, nor by one signed-in session for another. +* Nothing the session needs survives a restart, and nothing about it should be in the database. + +## Considered Options + +* A session in memory: 15 minutes from sign-in, never extended, under the hash of a 32-byte secret sent as a + `__Host-mv-account` cookie (`Secure`, `HttpOnly`, `SameSite=Strict`, `Max-Age=900`), with a form token derived from + the secret. +* A database-backed session with a sliding expiry. +* No session: ask for the password on every action, as the authorisation pages do. + +## Decision Outcome + +Chosen option: the first. + +* `AccountSessionStore` (`HomeserverRuntime::account_sessions`) holds a session under `oauth_secret_hash` of the + secret; the secret is returned once and never kept. 4096 sessions in all, 4 per user: a fifth sign-in replaces the + user's own oldest, a sign-in at the total cap is refused (503), never another user's session evicted. Expired + sessions are purged at the start of every operation. Every call takes the time, so tests need no clock. +* The form token is BLAKE2b-256 of a fixed label and the secret (`AccountSessionStore::form_token`), so it is bound to + the session, is not the cookie value, and is not derivable from what the store keeps. Compared in constant time. +* A POST is refused (403) unless `form_post_origin_is_accepted` accepts `Origin` and `Sec-Fetch-Site` (ADR-0784), + before the body is read. The sign-in form needs nothing else; every other form needs the cookie's live session and + its form token. +* The sign-in goes through `verify_password_login` with `rate_limit_client_key`, so it shares the throttle of + `POST /login`. A sign-in always issues a fresh session and ends the one the old cookie named. +* Every page load and every form re-judges the user with `account_sign_in_gate`; a session whose user is locked or + deactivated ends at once. +* `action` and `device_id` (spec "Account management URL parameters") are read only when they are one of the six + actions and a valid device ID, and are carried through the sign-in form in hidden fields. +* A device ID the user does not hold, whether unknown or another user's, gets the same 404 page. +* `SameSite=Strict`, unlike the authorisation cookie (`Lax`): nothing reaches these pages from another site with a + reason to carry the session, so a link from a client opens the sign-in form first. + +### Negative Consequences + +* A restart signs every browser out of the pages (and nothing else). +* A client's deep link always shows the sign-in form when the user has no live session: one more password entry. +* The device list shows no last-seen time or address; the server keeps none. + +## Pros and Cons of the Options + +### A database-backed session with a sliding expiry + +* Bad, because it is a standing credential that a browser left open keeps alive, and it needs a table, a migration and + a retention rule for no gain. + +### No session + +* Bad, because a user who follows a client's link to sign out a device would type the password for every page. + +## Links + +* Builds on [ADR-0782](0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md), + [ADR-0784](0784-oauth-pages-use-a-same-origin-referrer-policy-and-a-form-post-must-name-this-server-s-origin.md) and + [ADR-0786](0786-the-query-of-an-oauth-request-is-never-logged.md) +* Differs on purpose from [ADR-0787](0787-every-oauth-authorisation-asks-for-the-password-and-no-browser-session-is-kept.md), + which keeps no session for the authorisation pages diff --git a/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md b/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md new file mode 100644 index 000000000..d97f770a6 --- /dev/null +++ b/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md @@ -0,0 +1,74 @@ +# An OAuth session replaces its cross-signing keys through the m.oauth stage and a one-use approval + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 8 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md). Amends +[ADR-0794](0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md) for +`POST /keys/device_signing/upload`. + +## Context and Problem Statement + +ADR-0794 refused every UIA endpoint to an OAuth session with 403 until the account pages existed. The spec's +`m.oauth` stage ("OAuth authentication") is valid only on `/keys/device_signing/upload`: the server answers 401 with +`m.oauth` in `flows` and `params["m.oauth"].url`, the user confirms in the account management web UI, and the client +completes the stage with an `auth` dict holding just the `session`. What does "confirms" record, how long does it +last, and what may use it? + +## Decision Drivers + +* A stolen access token alone must not replace a user's cross-signing identity. +* One confirmation must not authorise more than one replacement. +* A refused or failed upload must not use up the user's confirmation. +* A password session must never be satisfied by the account page, and an OAuth session never by a password. + +## Considered Options + +* A per-user approval in memory, 10 minutes, spent by exactly one stored upload, completed with a real UIA session. +* An approval bound to the UIA session ID shown in the URL. +* Accept any upload for a few minutes after the approval. + +## Decision Outcome + +Chosen option: the first. + +* A replacing upload (not `cross_signing_upload_is_uia_exempt`) from a session `oauth_session_uia_refusal` names is + answered `401` with exactly: + `{"flows":[{"stages":["m.oauth"]}],"params":{"m.oauth":{"url":"?action=org.matrix.cross_signing_reset"}},"session":""}`, + the session issued with `issue_uia_session` for the purpose `cross_signing_reset` and the user (a full pool is 429). +* The account page's reset form records `CrossSigningResetApprovals::approve` for the signed-in user (10 minutes, + replacing any earlier one; 4096 users at most) and audits `cross_signing.reset_approved`. +* A retry with a session this server issued to this user for that purpose, whose `type` is absent or `m.oauth`, takes + the approval (`take`) inside the request. Any other `type` (a password stage) gets the same challenge and its + password is never checked. Without an approval it gets the same challenge and session. +* The taken approval is held by `TakenResetApproval`, which gives it back (`restore`) on every way out except a stored + upload: a refusal by `cross_signing_upload_refusal`, a key named like a device, or a failed store keeps the + approval. `spend()` runs only after `store_key_api_payload` succeeds, and audits `cross_signing.reset_used`. + `runtime.mutex` serialises the take and the store, so two concurrent uploads cannot both use one approval. +* A password (legacy) session keeps the `m.login.password` flow and never reads or spends an approval. +* With OAuth off, or no usable `public_baseurl`, the OAuth session keeps ADR-0794's 403. +* Every password change, reset and deactivation withdraws the user's approval (ADR-0798). + +### Negative Consequences + +* The approval is per user, not per client: any of the user's OAuth sessions may use it within the 10 minutes. The + account page's text says the permission is used by one reset. +* A restart forgets every approval; the user approves again. + +## Pros and Cons of the Options + +### An approval bound to the UIA session ID in the URL + +* Good, because it ties the approval to one request. +* Bad, because the spec's URL carries only `action` (and `device_id`): the page would need a parameter the spec does + not define, and the session ID would sit in a URL the user's browser keeps in its history. + +### Accept any upload for a few minutes + +* Bad, because one confirmation would authorise any number of replacements. + +## Links + +* Amends [ADR-0794](0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md) +* Uses the session of [ADR-0796](0796-the-account-pages-keep-a-fixed-15-minute-session-in-memory-bound-to-a-strict-cookie-and-a-form-token.md) diff --git a/docs/adr/0798-account-page-actions-share-the-client-api-cores-and-every-password-change-ends-account-page-access.md b/docs/adr/0798-account-page-actions-share-the-client-api-cores-and-every-password-change-ends-account-page-access.md new file mode 100644 index 000000000..e73164d62 --- /dev/null +++ b/docs/adr/0798-account-page-actions-share-the-client-api-cores-and-every-password-change-ends-account-page-access.md @@ -0,0 +1,72 @@ +# Account-page actions share the client API's cores, and every password change ends account-page access + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 8 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) + +## Context and Problem Statement + +The account pages (ADR-0796) sign out a device, change the password and deactivate the account. The client API does +the same through `DELETE /devices/{deviceId}`, `POST /account/password` and `POST /account/deactivate`, each with +bookkeeping that is easy to forget: device-list announcements, pusher removal, 3PID unbinds, login tokens. And +`change_local_user_password` keeps the calling device, which a page does not have. What does each page action call, +and what does a password change do to the user's other sessions? + +## Decision Drivers + +* A second copy of an action drifts from the first; the copy is the one that misses a later fix. +* A password change is what a user does after a compromise: nothing an attacker may hold should survive it. +* A browser left signed in to the pages must not outlive the credential that opened it. + +## Considered Options + +* Each page action calls the function the client API calls; a session-less password change shares the password + reset's core and keeps no device; every password change, reset and deactivation ends account-page access. +* Copy the client handlers' steps into the page handler. +* Have the page call `change_local_user_password` with a made-up device. + +## Decision Outcome + +Chosen option: the first. + +* `DELETE /devices/{deviceId}` and the page's device sign-out both call `delete_device_and_announce` + (`ClientDeviceSessions.hpp`): `remote_servers_for_user`, `delete_local_device`, the runtime's device list, + `record_shared_room_device_changes` and `announce_deleted_devices`. An OAuth device's `oauth_sessions` row goes with + it. +* `POST /account/deactivate` and the page's deactivation both call `deactivate_user_account` and then + `finish_account_deactivation` (login tokens erased, 3PIDs unbound at their identity servers with `runtime.mutex` + released). The page has no `id_server` and passes none. +* The page's password change is `change_password_on_account_page`, which shares `replace_password_without_device` + with `reset_local_user_password` (the email reset). It always logs out: every access, refresh and OpenID token and + every pusher of the account goes, because the page holds no device to keep. Devices are kept (the client API's + `logout_devices` revokes, it does not delete). The page also erases the user's login tokens. Audited as + `auth.password_changed` with the reason "changed on the account page; revoked all devices". +* `end_account_page_access` (`AuthService.cpp`) ends every account-page session of the user and withdraws any + cross-signing reset approval. `change_local_user_password`, `replace_password_without_device` (so both the reset and + the page change) and `deactivate_user_account` call it on success. A new path that changes a password or closes an + account calls it too. +* The page re-verifies the current password with `verify_password_login` before a change or a deactivation, and + re-reads its session after (the check releases `runtime.mutex`). + +### Negative Consequences + +* After a page password change every client signs in again, including the one the user came from. The page says so. +* An OAuth session's refresh token is revoked by the change while its `oauth_sessions` row and device stay; the client + must authorise again, which replaces the row. + +## Pros and Cons of the Options + +### Copy the client handlers' steps + +* Bad, because the device-list announcement and the 3PID unbinds would exist twice and drift. + +### `change_local_user_password` with a made-up device + +* Bad, because it keeps one device's tokens: the page would leave a device signed in that the user never chose. + +## Links + +* Builds on [ADR-0796](0796-the-account-pages-keep-a-fixed-15-minute-session-in-memory-bound-to-a-strict-cookie-and-a-form-token.md) + and [ADR-0797](0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index e2939dccd..09e406770 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -677,3 +677,6 @@ * [0793 - OAuth and legacy sessions do not mix at the refresh endpoints](0793-oauth-and-legacy-sessions-do-not-mix-at-the-refresh-endpoints.md) * [0794 - A UIA endpoint refuses an OAuth session, and the cross-signing upload follows the spec's exemptions](0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md) * [0795 - OAuth revocation ends the session as logout does, whoever asks](0795-oauth-revocation-ends-the-session-as-logout-does-whoever-asks.md) +* [0796 - The account pages keep a fixed 15-minute session in memory, bound to a strict cookie and a form token](0796-the-account-pages-keep-a-fixed-15-minute-session-in-memory-bound-to-a-strict-cookie-and-a-form-token.md) +* [0797 - An OAuth session replaces its cross-signing keys through the m.oauth stage and a one-use approval](0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md) +* [0798 - Account-page actions share the client API's cores, and every password change ends account-page access](0798-account-page-actions-share-the-client-api-cores-and-every-password-change-ends-account-page-access.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 573bbeaaf..6e628494f 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -156,7 +156,7 @@ production-gated. (issue #437), had no caller and was removed. - Client-server auth/device/key actions append durable audit rows without logging plaintext credentials, bearer tokens, or key payloads. -- `GET /_matrix/client/v1/auth_metadata` (and its MSC2965 unstable path) returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. `oauth::server_metadata` builds the document and every address in it comes from `oauth::OAuthBaseUrl`: the issuer is `server.public_baseurl` with one trailing slash and the endpoints sit under `/_merovingian/oauth2/` (ADR-0773). The endpoint is unauthenticated, carries CORS headers and stays in the generic rate-limit tier (ADR-0775). The registration, authorization, token and revocation endpoints are served (see "OAuth 2.0 client registration", "OAuth 2.0 authorisation pages" and "OAuth 2.0 token and revocation endpoints" below); the device authorisation endpoint and the account page it names are not served yet; they land in later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). The former `server.oidc.*` keys are refused at start-up. +- `GET /_matrix/client/v1/auth_metadata` (and its MSC2965 unstable path) returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. `oauth::server_metadata` builds the document and every address in it comes from `oauth::OAuthBaseUrl`: the issuer is `server.public_baseurl` with one trailing slash and the endpoints sit under `/_merovingian/oauth2/` (ADR-0773). The endpoint is unauthenticated, carries CORS headers and stays in the generic rate-limit tier (ADR-0775). The registration, authorization, token and revocation endpoints are served (see "OAuth 2.0 client registration", "OAuth 2.0 authorisation pages" and "OAuth 2.0 token and revocation endpoints" below); the account pages are served (see "OAuth 2.0 account pages" below); the device authorisation endpoint is not served yet; it lands in a later phase of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). The former `server.oidc.*` keys are refused at start-up. - **Application Service API identity (Matrix v1.19, `merovingian::appservice`).** Registration files (`appservice.registration_files`, parsed as JSON) build an in-memory `AppserviceRegistry` at startup in the main process only (the federation worker @@ -1204,14 +1204,54 @@ read with `core::FormFields`; anything else is 400 `invalid_request`. Every answ audited `oauth.session.revoked`, then 200 with an empty body. There is no 401 case (ADR-0795). - **User-Interactive Authentication.** An OAuth session holds no password the client can be asked for. Every endpoint that asks for UIA with an access token (`POST /login/get_token`, `POST /account/password`, `POST /account/deactivate`, - `POST /account/3pid/add`, `DELETE /devices/{deviceId}`, `POST /delete_devices`, and a change of held cross-signing - keys) answers it 403 `M_FORBIDDEN` naming the account page (`oauth_session_uia_refusal`); an application service is - exempt. `POST /keys/device_signing/upload` needs no UIA for any session when no master key is held or when every key - sent matches the held one, nor for an application service (spec v1.11 and v1.17; ADR-0794). + `POST /account/3pid/add`, `DELETE /devices/{deviceId}`, `POST /delete_devices`) answers it 403 `M_FORBIDDEN` naming + the account page (`oauth_session_uia_refusal`); an application service is exempt. `POST /keys/device_signing/upload` + needs no UIA for any session when no master key is held or when every key sent matches the held one, nor for an + application service (spec v1.11 and v1.17; ADR-0794). A change of held keys from an OAuth session is the `m.oauth` + stage (see "OAuth 2.0 account pages"). - **Logging.** Under `oauth`: `oauth.token.refused` (debug: grant type, error, client ID), `oauth.session.granted`, `oauth.session.persistence_failed`, `oauth.refresh.refused`, `oauth.code.replayed`, `oauth.revocation.refused` and `oauth.revocation.accepted`, with `user_id`, `device_id` and `client_id` only. Never a code, a verifier or a token. +## OAuth 2.0 account pages (phase 8) + +`GET` and `POST /_merovingian/account` (`handle_account_page`, `AccountPage.cpp`) are the account management web UI +the spec's "Account management" names: `account_management_uri` and all six `org.matrix.*` actions in the metadata. +`404 M_UNRECOGNIZED` while `server.oauth.enabled` is false; another method is 405. + +- **Session (ADR-0796).** `AccountSessionStore` (`HomeserverRuntime::account_sessions`), in memory: 15 minutes from + sign-in, never extended, under `oauth_secret_hash` of a 32-byte secret sent as `__Host-mv-account` (`Secure`, + `HttpOnly`, `SameSite=Strict`, `Max-Age=900`). 4096 sessions, 4 per user (a fifth sign-in ends the user's oldest; at + the total cap a sign-in is 503). Each signed-in form carries a form token, BLAKE2b of a label and the secret, + compared in constant time. A session whose user no longer passes `account_sign_in_gate` ends at once. +- **Sign-in.** `verify_password_login` with `rate_limit_client_key`, so it shares the `POST /login` throttle; a 429 + carries `Retry-After`. A sign-in always issues a fresh session and ends the one the old cookie named, then answers 303 + to the page asked for. `action` (one of the six) and `device_id` (only for the two device actions, only a valid + device ID) are carried through the form in hidden fields; anything else is ignored. +- **Form posts.** Refused 403 unless `form_post_origin_is_accepted` accepts `Origin` and `Sec-Fetch-Site`, before the + body is read; then `application/x-www-form-urlencoded`, then the cookie's live session and its form token. +- **Devices.** Read through the user's device index; a device ID the user does not hold, unknown or another user's, + is the same 404 page. Signing out a device is `delete_device_and_announce`, the core of `DELETE /devices/{deviceId}` + (ADR-0798). +- **Password change (ADR-0798).** The current password is checked with `verify_password_login`, the new one twice. + `change_password_on_account_page` shares the email reset's core, `replace_password_without_device`: every access, + refresh and OpenID token and every pusher of the account goes, devices stay; the page also erases the user's login + tokens. Audited `auth.password_changed`. A suspended account cannot change its password here, as in the client API. +- **Deactivation.** The password again, then `deactivate_user_account` and `finish_account_deactivation`, the core of + `POST /account/deactivate`. +- **Ending page access.** `end_account_page_access` ends every account-page session of the user and withdraws any + cross-signing reset approval; `change_local_user_password`, the reset, the page change and `deactivate_user_account` + call it. +- **Cross-signing reset (ADR-0797).** The reset page records `CrossSigningResetApprovals::approve` (10 minutes, one + per user) and audits `cross_signing.reset_approved`. A replacing upload from an OAuth session is answered 401 + `{"flows":[{"stages":["m.oauth"]}],"params":{"m.oauth":{"url":"?action=org.matrix.cross_signing_reset"}},"session":""}` + with a UIA session of purpose `cross_signing_reset`. A retry with that session and `type` absent or `m.oauth` takes + the approval; it goes back unless the keys are stored, and a stored upload audits `cross_signing.reset_used`. A + password stage from an OAuth session is never checked; a legacy session keeps `m.login.password` and never touches + an approval. +- **Logging.** Under `oauth`, `account.page.*` events with `user_id` only. Never a password, a cookie, a form token or + the query (`sanitized_http_target` drops it, ADR-0786). + ## Next starting points 1. Preserve the reviewed libsodium boundary for random token generation and password hashing as auth flows expand. diff --git a/docs/http-transport.md b/docs/http-transport.md index e22ea92a2..ed076763d 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -986,6 +986,14 @@ else is `400 invalid_request`. Every answer is built by `oauth_json_response`, ` clients exist: a `client_secret` field is `400 invalid_client`, and an `Authorization: Basic` header `401 invalid_client` with `WWW-Authenticate: Basic`. A body over `max_body_bytes` gets the general `413 M_TOO_LARGE`. +`GET` and `POST /_merovingian/account` (ADR-0796) are routed the same way (`static_routes`, `auth_sensitive`, a +`client_static_route_allow` row of `GET, POST`, so another method is `405`), before the authentication gate, and are +`404 M_UNRECOGNIZED` with the API off. Every answer is a page or a 303 marked `LocalHttpResponse::page`, so none carries +a CORS header. A form post is refused `403` unless `form_post_origin_is_accepted` accepts it, before the body is read; +the body must be `application/x-www-form-urlencoded`. The session cookie `__Host-mv-account` is `Secure`, `HttpOnly`, +`SameSite=Strict`, `Path=/` and `Max-Age=900`, and is read like `__Host-mv-oauth`: a `Cookie` header sent twice counts +as absent. A cookie that names no live session is deleted (`Max-Age=0`). + ### Admin routes `/_merovingian/admin/*` (health, metrics, audit, accounts, review, media moderation) is served on diff --git a/docs/matrix-v1.19-client-server-api.md b/docs/matrix-v1.19-client-server-api.md index 682d8519c..31a3f7ee5 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -108,7 +108,7 @@ and the password-UIA requirement remain unchanged. | --- | --- | --- | --- | --- | --- | | `GET` | `/_matrix/client/v3/keys/changes` | `getKeysChanges` | access token | - | 200 | | `POST` | `/_matrix/client/v3/keys/claim` | `claimKeys` | access token | required application/json | 200 | -| `POST` | `/_matrix/client/v3/keys/device_signing/upload` | `uploadCrossSigningKeys` | access token | required application/json | 200, 400, 403 | +| `POST` | `/_matrix/client/v3/keys/device_signing/upload` | `uploadCrossSigningKeys` | access token | required application/json | 200, 400, 401 (UIA: `m.login.password`, or `m.oauth` for an OAuth session, ADR-0797), 403 | | `POST` | `/_matrix/client/v3/keys/query` | `queryKeys` | access token | required application/json | 200 | | `POST` | `/_matrix/client/v3/keys/signatures/upload` | `uploadCrossSigningSignatures` | access token | required application/json | 200 | | `POST` | `/_matrix/client/v3/keys/upload` | `uploadKeys` | access token | required application/json | 200 | @@ -393,7 +393,7 @@ lists have no server maximum (ADR-0332). | --- | --- | --- | --- | --- | --- | | `GET` | `/_matrix/client/v1/auth_metadata` | `getAuthMetadata` | none | - | 200, 404 | -Implemented: returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. The MSC2965 path `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answers the same. Its registration endpoint, `POST /_merovingian/oauth2/register` (spec "Client registration"), is served: unauthenticated, `201` with the client ID and the registered metadata, RFC 7591 errors (ADR-0779 to ADR-0781). Its authorization endpoint, `GET` and `POST /_merovingian/oauth2/authorize` (spec "Authorisation code grant"), is served: the sign-in, account creation and consent pages, then a redirect with `code` and `state`, or an RFC 6749 error, in the query or the fragment (ADR-0787 to ADR-0789). Its token endpoint, `POST /_merovingian/oauth2/token` (spec "Token endpoint"), serves the `authorization_code` grant (PKCE `S256`, the redirect URI byte for byte, one transaction, a replayed code ending the session it produced) and the `refresh_token` grant (rotation as `/refresh`), for public clients only (ADR-0791 to ADR-0793). Its revocation endpoint, `POST /_merovingian/oauth2/revoke` (spec "Token revocation"), ends the session of an access or refresh token as `/logout` does and answers 200 whether or not the token was known (ADR-0795). A session from the token endpoint is refused at every endpoint that uses User-Interactive Authentication with `403 M_FORBIDDEN` naming the account page, and at `POST /refresh` (ADR-0793, ADR-0794). The account page and the device authorization grant are served from later phases of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). +Implemented: returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. The MSC2965 path `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answers the same. Its registration endpoint, `POST /_merovingian/oauth2/register` (spec "Client registration"), is served: unauthenticated, `201` with the client ID and the registered metadata, RFC 7591 errors (ADR-0779 to ADR-0781). Its authorization endpoint, `GET` and `POST /_merovingian/oauth2/authorize` (spec "Authorisation code grant"), is served: the sign-in, account creation and consent pages, then a redirect with `code` and `state`, or an RFC 6749 error, in the query or the fragment (ADR-0787 to ADR-0789). Its token endpoint, `POST /_merovingian/oauth2/token` (spec "Token endpoint"), serves the `authorization_code` grant (PKCE `S256`, the redirect URI byte for byte, one transaction, a replayed code ending the session it produced) and the `refresh_token` grant (rotation as `/refresh`), for public clients only (ADR-0791 to ADR-0793). Its revocation endpoint, `POST /_merovingian/oauth2/revoke` (spec "Token revocation"), ends the session of an access or refresh token as `/logout` does and answers 200 whether or not the token was known (ADR-0795). A session from the token endpoint is refused at `POST /refresh` and at every endpoint that uses User-Interactive Authentication with `403 M_FORBIDDEN` naming the account page (ADR-0793, ADR-0794), except a change of held keys at `POST /keys/device_signing/upload`, which is the `m.oauth` stage (spec "OAuth authentication"): a 401 whose only flow is `m.oauth` with `params.m.oauth.url` the account page with `?action=org.matrix.cross_signing_reset`, completed by an `auth` holding just the `session` once the user has approved the reset there (ADR-0797). The account management URL (spec "Account management"), `GET` and `POST /_merovingian/account`, is served and advertised as `account_management_uri` with all six `org.matrix.*` actions; it reads `action` and `device_id` (ADR-0796, ADR-0798). The device authorization grant is served from a later phase of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). | `POST` | `/_matrix/client/v1/login/get_token` | `generateLoginToken` | access token | required application/json | 200, 400, 401, 429 | | `GET` | `/_matrix/client/v3/account/whoami` | `getTokenOwner` | access token | - | 200, 401, 403, 429 | | `GET` | `/_matrix/client/v3/login` | `getLoginFlows` | none | - | 200, 404, 429 | diff --git a/docs/observability-audit.md b/docs/observability-audit.md index 6b532f2c5..ca7f7a10b 100644 --- a/docs/observability-audit.md +++ b/docs/observability-audit.md @@ -582,6 +582,19 @@ ID), written in the grant's own transaction; `oauth.session.revoked` and `oauth. reason `revoked`), written when the session ends, as `auth.logout` is. A refresh grant writes the `auth.refresh` rows of the legacy refresh. +## OAuth 2.0 account page diagnostics and audit (ADR-0796 to ADR-0798) + +`/_merovingian/account` logs under the `oauth` module, with `user_id` only: `account.page.signed_in`, +`account.page.signed_out`, `account.page.device_deleted`, `account.page.password_changed`, `account.page.deactivated` +and `account.page.cross_signing_reset_approved` (info), and `account.page.forbidden_origin` (debug, no field). Never a +password, the session cookie, a form token or the query. + +Durable audit rows (category `auth`): `cross_signing.reset_approved` (actor and target the user, reason `account +page`) when the user approves a cross-signing reset, and `cross_signing.reset_used` (actor and target the user, reason +`m.oauth`) when an OAuth session's replacing upload is stored with it. The page's actions write the rows of the client +API functions they call: `device.deleted` for a device sign-out, `auth.password_changed` (reason `changed on the account +page; revoked all devices`) and `auth.account_deactivated` (reason `deactivated on the account page`). + ## Outbound client request diagnostics (F-76, ADR-0418) `http::OutboundClient::perform` logs one debug line per request under the `outbound_client` module: diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index 21cd011df..ce83c259e 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1072,12 +1072,23 @@ quickly finding everything a given `AGENTS.md` file contributed. Source: `src/homeserver/AGENTS.md`, `src/auth/AGENTS.md`, `src/database/AGENTS.md`. - **Every endpoint that asks for User-Interactive Authentication refuses an OAuth session with 403 before checking a - password, and revocation or a replay ends a session only through the path `POST /logout` uses.** + password, except a replacing cross-signing upload, which offers only the `m.oauth` stage; revocation or a replay + ends a session only through the path `POST /logout` uses.** Why: a session the user granted to an application must not be able to change the password, deactivate the account or delete devices with a password the application may have captured (CWE-306); a second end-of-session path forgets a token, the device list or the remote servers (ADR-0794, ADR-0795). Source: `src/homeserver/AGENTS.md`, `src/auth/AGENTS.md`. +- **An account-page form is accepted only with this server's `Origin`, the `__Host-mv-account` session and that + session's form token (constant time); each page action calls the client API's own function; every password change, + reset and deactivation ends the user's account-page sessions and reset approvals; a cross-signing reset approval is + spent only by a stored upload and is never usable by a password session or with a password stage.** + Why: a forged post signs out a device or deactivates an account (CWE-352); one session's token must not act for + another; a copied action drifts and misses a revocation step (CWE-613); a page session or approval that outlives a + password change keeps a stolen credential's reach (CWE-613); a token alone must not replace a user's cross-signing + identity (CWE-306) (ADR-0796, ADR-0797, ADR-0798). + Source: `src/homeserver/AGENTS.md`. + ## HTTP and network boundary - **Rate limiting is applied before any auth check.** Do not move it after auth. diff --git a/docs/todos/capability-gaps.md b/docs/todos/capability-gaps.md index cb2e4d046..8776c8c3d 100644 --- a/docs/todos/capability-gaps.md +++ b/docs/todos/capability-gaps.md @@ -47,7 +47,7 @@ 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) and revocation are served (ADR-0779 to ADR-0795); the account page and the device authorization grant are later phases of the [OAuth 2.0 API plan](oauth-2-0-api.md). | +| `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) and the `m.oauth` UIA stage are served (ADR-0779 to ADR-0798); the device authorization grant is a later phase of the [OAuth 2.0 API plan](oauth-2-0-api.md). An OAuth session still cannot add an email address or mint a login token (no page; `403 M_FORBIDDEN`). | | `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). | | 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. | | Room summary over federation | `runtime-wired` | `GET /v1/room_summary/{roomIdOrAlias}?via=` asks up to 3 `via` servers over federation `GET /hierarchy/{roomId}` (the `room` chunk; v1.19 defines no federation summary route) for a room this server holds no state for (ADR-0556): one ADR-0079 slot (429 at once without one, also without a token), one deadline, unverified answer, shown only by its own `join_rule` / `world_readable` / `allowed_room_ids`. Local state always wins; a malformed `via` is `400 M_INVALID_PARAM`. Not implemented: resolving an alias that lives on another server (404 / 401), and `membership` for a room not held locally. | diff --git a/docs/todos/oauth-2-0-api.md b/docs/todos/oauth-2-0-api.md index d86fb9c88..10842d646 100644 --- a/docs/todos/oauth-2-0-api.md +++ b/docs/todos/oauth-2-0-api.md @@ -228,12 +228,15 @@ checks `Origin` and `Sec-Fetch-Site` with `oauth::form_post_origin_is_accepted` `/_merovingian/account` asks for the password, then keeps a 15-minute session in a `__Host-` cookie with `SameSite=Strict`. It lists devices, shows one, deletes one, changes the password, deactivates the account and approves a cross-signing reset. Each action calls the service function the client API already uses -(`delete_local_device`, `change_local_user_password`, `deactivate_user_account`). Deactivation asks for the password -again. `account_management_actions_supported` lists exactly the actions that are implemented. +(`delete_device_and_announce`, `deactivate_user_account` with `finish_account_deactivation`); the password change is +`change_password_on_account_page`, the email reset's core, because `change_local_user_password` keeps a calling device +the page does not have (ADR-0798). Deactivation asks for the password again. `account_management_actions_supported` +lists exactly the actions that are implemented: all six. Done in phase 8 (ADR-0796 to ADR-0798). A cross-signing reset approval is a per-user flag, in memory, valid for 10 minutes and spent by one upload. `POST /keys/device_signing/upload` from an OAuth session that would replace existing keys answers `401` with the -`m.oauth` stage and the account page URL, and accepts the retry once the flag is set. +`m.oauth` stage and the account page URL, and accepts the retry once the flag is set. The approval is taken by the +retry and given back unless the keys are stored (ADR-0797). ### The legacy API beside OAuth diff --git a/docs/user-manual.md b/docs/user-manual.md index de9ed77b5..4004a0b19 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -835,15 +835,33 @@ registration (`POST /_merovingian/oauth2/register`), the sign-in pages (`/_merovingian/oauth2/authorize`, where a user signs in or creates an account and allows the application), the token endpoint (`POST /_merovingian/oauth2/token`, the authorization code and refresh grants) -and revocation (`POST /_merovingian/oauth2/revoke`); the account page and the -device grant follow. Every authorisation asks for the password; the server -keeps no browser session. At most 10000 client registrations are held; once -every held one is in use, a new client is answered `503 temporarily_unavailable` -until one is freed. Until the account page lands, a user signed in through -OAuth cannot change their password, deactivate the account, add an email -address or delete a device from that session: those requests are answered -`403 M_FORBIDDEN` naming `/_merovingian/account` (ADR-0794), so leave the API -off unless users can do those things from a legacy login. +revocation (`POST /_merovingian/oauth2/revoke`) and the account pages +(`/_merovingian/account`); the device grant follows. Every authorisation asks +for the password; the server keeps no browser session for it. At most 10000 +client registrations are held; once every held one is in use, a new client is +answered `503 temporarily_unavailable` until one is freed. + +The account pages are where a user signed in through OAuth manages the account +(spec "Account management"; ADR-0796 to ADR-0798). The metadata names them as +`account_management_uri` and lists all six actions: the overview, the device +list, one device, signing a device out, deactivation and approving a +cross-signing reset. A user signs in there with the password (the same +throttle as `POST /login`) and gets a session of 15 minutes that is never +extended and is kept only in memory, so a restart signs every browser out of +the pages. The pages also change the password. A password change there signs +out every session of the account, in every application and on every device, +and keeps the devices; every application must sign in again. A password change, +a reset and a deactivation each end the user's account-page sessions. + +A client signed in through OAuth asks for User-Interactive Authentication only +to replace its cross-signing keys. It is then sent to the account page +(`?action=org.matrix.cross_signing_reset`, the `m.oauth` stage), where the +user allows one reset within 10 minutes. The other User-Interactive +Authentication endpoints (`POST /account/password`, `/account/deactivate`, +`/account/3pid/add`, `DELETE /devices/{deviceId}`, `POST /delete_devices`, +`/login/get_token`) still answer an OAuth session `403 M_FORBIDDEN` naming the +account page (ADR-0794); the user does those things on the pages, except +adding an email address and minting a login token, which have no page yet. An OAuth access token always expires: it lives `security.access_token_lifetime_ms`, or one hour when that is `0` (ADR-0791), diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 643b7a4de..c6f4628b5 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -34,6 +34,10 @@ This is the largest and most complex module — read this file carefully before | `OAuthClientCredentials.cpp` | `oauth_client_credentials_refusal`: refuses a `client_secret` field or `Authorization: Basic` (only public clients exist) at the token and revocation endpoints | | `OAuthAuthorization.cpp` | `GET` and `POST /_merovingian/oauth2/authorize` (`handle_oauth_authorize`): the authorisation request, the browser cookie, the login, registration and consent pages, and the redirect with a code or an error (ADR-0787 to ADR-0789) | | `OAuthClock.cpp` | `oauth_wall_clock_ms`: the wall-clock milliseconds every OAuth store and handler passes | +| `AccountPage.cpp` | `GET` and `POST /_merovingian/account` (`handle_account_page`): the account pages' sign-in, overview, devices, device sign-out, password change, deactivation and cross-signing reset approval (ADR-0796 to ADR-0798) | +| `AccountSessionStore.cpp` | `AccountSessionStore` (`HomeserverRuntime::account_sessions`): account-page sessions, 15 minutes fixed, hashed secret, 4096 in all and 4 per user (the user's oldest goes), and the session's form token (ADR-0796). Guarded by `runtime.mutex` | +| `CrossSigningResetApprovals.cpp` | `CrossSigningResetApprovals` (`HomeserverRuntime::cross_signing_reset_approvals`): one approval per user, 10 minutes, taken by a replacing upload and restored unless the keys are stored (ADR-0797). Guarded by `runtime.mutex` | +| `OAuthPageResponse.cpp` | Module-internal helpers both page handlers share: `oauth_page_response`, `oauth_plain_page`, `oauth_error_page_response`, `request_target_query`, `single_request_header`, `request_secret_cookie`, `retry_after_seconds` | | `RequestHeaders.cpp` | `request_header` (first value, case-insensitive name) and `request_header_values` (every value, for a check that refuses a repeated header) | | `PendingAuthorisationStore.cpp` | `PendingAuthorisationStore` (`HomeserverRuntime::oauth_pending_authorisations`): OAuth 2.0 authorization requests in progress, 10 minutes, under a 32-byte identifier kept as a hash and bound to a browser token compared in constant time; 8192 in all and 16 per client address, never evicting a live entry (ADR-0782). Guarded by `runtime.mutex` | | `AuthorizationCodeStore.cpp` | `AuthorizationCodeStore` (`HomeserverRuntime::oauth_codes`): authorization codes, 60 s, hashed, bound to client, redirect URI, PKCE challenge, user, device and scope; 8192, never evicted; a redeemed code is remembered until its expiry so a replay is told apart (ADR-0782). Guarded by `runtime.mutex` | @@ -162,10 +166,32 @@ gate; `ClientServerRuntime.cpp` holds only the route matches. Rules: revocation, a replayed code, any new path that ends a session. - **A UIA endpoint calls `oauth_session_uia_refusal` first** (ADR-0794): `GET`/`POST /login/get_token`, `POST /account/password`, `/account/deactivate`, `/account/3pid/add`, `DELETE /devices/{deviceId}`, - `POST /delete_devices`, and `POST /keys/device_signing/upload` when the upload is not UIA-exempt. An application - service's masquerade token is never refused. + `POST /delete_devices`, and `POST /keys/device_signing/upload` when the upload is not UIA-exempt, which then offers + the `m.oauth` stage instead of the 403 (ADR-0797). An application service's masquerade token is never refused. - Never log a code, a verifier, a token or the body; log `client_id`, `grant_type`, `error`, `user_id`, `device_id`. +The account pages are `handle_account_page` (`AccountPage.cpp`); `ClientServerRuntime.cpp` holds only the route match. +Rules (ADR-0796 to ADR-0798): + +- **A form post is checked in order**: `form_post_origin_is_accepted` (403, before the body is read), the content + type, the form; then, for anything but `sign_in`, the cookie's live session (`AccountSessionStore::find`, then + `account_sign_in_gate`) and the session's form token (`form_token_matches`). Never act on a post before all of these. +- **Each action calls the client API's function, never a copy**: `delete_device_and_announce` (shared with + `DELETE /devices/{deviceId}`), `deactivate_user_account` then `finish_account_deactivation` (shared with + `POST /account/deactivate`), `change_password_on_account_page` (the email reset's core, + `replace_password_without_device`). A new page action finds or factors out the client API's core first. +- **`verify_password_login` releases `runtime.mutex`**: after it, find the session again (`still_signed_in`) before + acting. +- **Every password change, reset and deactivation calls `end_account_page_access`** (`AuthService.cpp`), which ends the + user's account-page sessions and withdraws a reset approval. A new path that changes a password or closes an account + does too. +- **A device the user does not hold is the same 404 page**, whether unknown or another user's. +- **The `m.oauth` stage** (`oauth_cross_signing_reset_stage` in `ClientServerRuntime.cpp`) is offered only to an OAuth + session's replacing upload; a legacy session keeps `m.login.password` and never touches an approval. The approval is + taken into a `TakenResetApproval`, which restores it on every way out; `spend()` only after `store_key_api_payload` + succeeds. A password stage from an OAuth session is answered with the challenge and never checked. +- Log `user_id` only (`account.page.*`); never a password, the cookie, a form token or the query. + `POST /_merovingian/oauth2/register` is `register_oauth_client` (`OAuthClientRegistration.cpp`), answered before the authentication gate, and also from the general body cap so an oversized body is an OAuth 400 (ADR-0781). Rules: @@ -262,7 +288,8 @@ never a 200 with an etag. Do not skip a malformed entry or ignore a write result The upload asks for User-Interactive Authentication only when it changes a held key (spec v1.11 "Cross-signing", ADR-0794): `cross_signing_upload_is_uia_exempt` exempts an application service, a user with no master key, and an upload whose master key and every other key sent equal the held ones (canonical JSON). While a master key is held, an upload -without one, or with any key that differs from the held one, is UIA, and an OAuth session is refused it with 403. +without one, or with any key that differs from the held one, is UIA: `m.login.password` for a password session, the +`m.oauth` stage and a one-use account-page approval for an OAuth session (ADR-0797; 403 with OAuth off). ## The runtime lock and blocking calls diff --git a/src/oauth/AGENTS.md b/src/oauth/AGENTS.md index dbf6068ea..ec118344a 100644 --- a/src/oauth/AGENTS.md +++ b/src/oauth/AGENTS.md @@ -24,6 +24,7 @@ Pure functions and value types for the built-in OAuth 2.0 API | `ServerMetadata.cpp`, `ServerMetadataOptions.hpp` | `server_metadata`: the `auth_metadata` document, device grant, `prompt=create` and account management fields only when their option is on | | `AuthorizationRedirect.cpp` | `percent_encode_redirect_value`, `authorization_redirect_address`: the answer's parameters percent-encoded (everything but the unreserved characters) into the query or the fragment of a matched redirect URI | | `AuthorizationPages.cpp`, `AccountFormInput.hpp`, `ConsentPageInput.hpp` | The login, registration, consent and error pages of `/_merovingian/oauth2/authorize`, and the form field and action names they post. A value `HtmlText::escape` refuses is replaced by fixed text | +| `AccountPages.cpp`, `AccountPageFrame.hpp`, `AccountDeviceRow.hpp`, `AccountSignInInput.hpp` | The account pages of `/_merovingian/account` (ADR-0796): sign-in, overview, devices, one device, device sign-out, password, deactivation, cross-signing reset and result pages; the six spec actions (`account_management_actions`, `account_management_action`, `account_action_takes_device`), `account_action_address` (every link, the post-sign-in redirect and the `m.oauth` URL), and the form field and action names. Every signed-in form carries `form_token`; a page whose token cannot be shown holds no form | | `FormPostOrigin.cpp` | `form_post_origin`, `form_post_origin_is_accepted`: a page's form post must name this server's origin exactly, and `Sec-Fetch-Site`, when sent, `same-origin` (ADR-0784) | | `HandOffAllowlist.cpp` | `hand_off_allowlist_entry_error`, `hand_off_allowlist_error`: an https origin or a bare private-use scheme, at most 32, each once (ADR-0774) | | `FormContentType.cpp` | `api_form_content_type_is_accepted`: the token and revocation endpoints take `application/x-www-form-urlencoded` only, with at most a `charset=utf-8` parameter | @@ -69,7 +70,9 @@ Pure functions and value types for the built-in OAuth 2.0 API `[oauth][server_metadata]`), `test_oauth_hand_off_allowlist.cpp` (`[oauth][allowlist]`), `test_oauth_form_post_origin.cpp` (`[oauth][form-origin]`), `test_oauth_page_response.cpp` (`[oauth][page-response]`), `test_oauth_authorization_redirect.cpp` (`[oauth][redirect-address]`), -`test_oauth_authorization_pages.cpp` (`[oauth][authorize-page]`). The authorisation endpoint: +`test_oauth_authorization_pages.cpp` (`[oauth][authorize-page]`), `test_oauth_account_pages.cpp` +(`[oauth][account-page]`). The account pages: `tests/conformance/test_oauth_account_management_conformance.cpp` and +`tests/integration/test_oauth_account_pages_flow.cpp` (`[oauth-account]`, `[oauth-uia]`). The authorisation endpoint: `tests/conformance/test_oauth_authorization_conformance.cpp` and `tests/integration/test_oauth_authorization_flow.cpp` (`[oauth-authorize]`). The served document: `tests/conformance/test_oauth_metadata_conformance.cpp` and `tests/integration/test_oauth_metadata_flow.cpp` diff --git a/tests/conformance/AGENTS.md b/tests/conformance/AGENTS.md index e4bda23ac..82a036e78 100644 --- a/tests/conformance/AGENTS.md +++ b/tests/conformance/AGENTS.md @@ -63,6 +63,7 @@ Every test in this directory directly encodes a **MUST** or **SHOULD** from the | `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) | | `test_oauth_authorization_conformance.cpp` | [CS API § Authorisation code grant](../../docs/matrix-v1.19-spec/client-server-api.md#authorisation-code-grant) · [§ Scope](../../docs/matrix-v1.19-spec/client-server-api.md#scope) · [§ User registration](../../docs/matrix-v1.19-spec/client-server-api.md#user-registration) (`/_merovingian/oauth2/authorize`: an unregistered redirect URI is never redirected to; `state` on success and error; the response mode places the answer; S256 required; the API and exactly one device scope; `prompt=create` shows registration only when accepted) | +| `test_oauth_account_management_conformance.cpp` | [CS API § Account management](../../docs/matrix-v1.19-spec/client-server-api.md#account-management-url-discovery) · [§ OAuth authentication](../../docs/matrix-v1.19-spec/client-server-api.md#oauth-authentication) (`account_management_uri` and the six actions; `action` and `device_id` on `/_merovingian/account`, the device ignored by the actions that take none; a replacing cross-signing upload from an OAuth session is a 401 with the `m.oauth` flow and the `org.matrix.cross_signing_reset` URL, completed by the `session` alone after the approval) | | `test_oauth_token_conformance.cpp` | [CS API § Refresh token grant](../../docs/matrix-v1.19-spec/client-server-api.md#refresh-token-grant) · [§ Token revocation](../../docs/matrix-v1.19-spec/client-server-api.md#token-revocation) (`/_merovingian/oauth2/token` and `/revoke`: an access token always expires; a lost refresh answer can be retried and the old token is refused once the new one is used; revocation ends both tokens whatever the `client_id` and answers 200 for an unknown token) | | `test_oauth_client_registration_conformance.cpp` | [CS API § Client registration](../../docs/matrix-v1.19-spec/client-server-api.md#client-registration) · [§ Client metadata](../../docs/matrix-v1.19-spec/client-server-api.md#client-metadata) · [§ Redirect URI validation](../../docs/matrix-v1.19-spec/client-server-api.md#redirect-uri-validation) · [§ Dynamic client registration flow](../../docs/matrix-v1.19-spec/client-server-api.md#dynamic-client-registration-flow) (`POST /_merovingian/oauth2/register`: 201 with `client_id` and the registered metadata, web and native, `none`, unknown values ignored, the spec's redirect URI examples, a client with a session never deleted) | | `test_pdu_format_conformance.cpp` | [SS API § PDUs](../../docs/matrix-v1.19-spec/server-server-api.md#pdus) | diff --git a/tests/support/AGENTS.md b/tests/support/AGENTS.md index 38d323270..e6ed7cd03 100644 --- a/tests/support/AGENTS.md +++ b/tests/support/AGENTS.md @@ -34,6 +34,7 @@ Shared test utilities used across unit, conformance, and integration tests. | `OAuthRegistrationSupport.hpp` | `oauth_registration_config()` (OAuth on or off, `public_baseurl`, in-memory database, shared master key), `post_client_registration()` and `response_header()` for the OAuth 2.0 client registration conformance and integration scenarios | | `OAuthTokenSupport.hpp` | The token and revocation paths, an RFC 7636 verifier, `oauth_both_grant_types`, `obtain_oauth_code` (authorise, sign in, approve), `post_oauth_body` / `post_oauth_form` (form-encoded, from the client's origin), the grant fields (`code_grant_fields`, `refresh_grant_fields`), `read_token_answer` and `oauth_sign_in` (a code redeemed into a session) | | `OAuthAuthorizationSupport.hpp` | A registered web client, the authorisation request's parameters (`oauth_authorize_parameters`, `with_parameter`), `get_authorize` / `post_authorize` as a browser sends them (`BrowserContext`: address, cookie, `Origin`, `Sec-Fetch-Site`, content type), and readers for the pending identifier, the cookie and a redirect's parameters (`redirect_answer`) | +| `OAuthAccountPageSupport.hpp` | The account pages (`/_merovingian/account`): `AccountBrowser` (address, cookie, `Origin`, `Sec-Fetch-Site`, content type), `get_account` / `post_account` as a browser sends them, `account_cookie_of`, `form_token_of`, and `account_sign_in` (the sign-in form, then the overview's form token) | | `E2eeCapsSupport.hpp` | `caps_config()` and a logged-in-user helper for the CSAZ-10 per-user end-to-end key and filter cap scenarios | | `MembershipFixtureSupport.hpp` | Helpers that build membership PDUs (send_join, send_leave, send_knock bodies) with the `auth_events` and `prev_events` a real server would send (ADR-0064 phase B2) | | `MembershipAcceptorFixture.hpp` / `Genesis.hpp` | A local server "local.example.org" with a public room version 10 and a local joined admin (`seed_room_genesis`), and the builders for membership PDUs and envelopes the membership acceptor's unit and conformance scenarios share (`build_event_json`, `make_envelope`, `seed_accepted_event`, `config_with_sqlite`) | From 31617f9a195df0070d84854fdc12e3ae6d3ab6b2 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 08:38:02 +0000 Subject: [PATCH 18/42] Accept a polling m.oauth retry and refuse page text in member initialisers (ADR-0799, ADR-0800) The m.oauth stage of a replacing cross-signing upload now completes, with a live approval, for a retry with no auth or no session, as polling clients send it; the challenge reuses the user's live UIA session, so polling costs one session, and offers org.matrix.cross_signing_reset as a second flow. Clang 18 compiles a consteval HtmlLiteral call in a default member initialiser as a run-time call. A tooling test now refuses such an initialiser for the four page text types, and the one in AccountPage.cpp is gone. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 + ...he-m-oauth-stage-and-a-one-use-approval.md | 5 + ...sion-and-reuses-the-user-s-live-session.md | 79 +++++++ ...xt-because-clang-18-runs-it-at-run-time.md | 71 ++++++ docs/adr/index.md | 2 + docs/auth-identity.md | 17 +- docs/coding-rules.md | 1 + docs/security-coding-rules.md | 11 +- include/merovingian/oauth/HtmlLiteral.hpp | 4 +- src/homeserver/AGENTS.md | 5 +- src/homeserver/AccountPage.cpp | 8 +- src/homeserver/ClientServerRuntime.cpp | 87 ++++++-- src/oauth/AGENTS.md | 6 + ...t_oauth_account_management_conformance.cpp | 14 +- .../test_oauth_account_pages_flow.cpp | 105 ++++++++- tests/meson.build | 6 + .../test_page_text_member_initialisers.py | 204 ++++++++++++++++++ 17 files changed, 590 insertions(+), 39 deletions(-) create mode 100644 docs/adr/0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md create mode 100644 docs/adr/0800-no-default-member-initialiser-holds-oauth-page-text-because-clang-18-runs-it-at-run-time.md create mode 100644 tests/tooling/test_page_text_member_initialisers.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 6d4cf40e6..0703319da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -60,6 +60,10 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) valid 10 minutes, spent only by a stored upload (ADR-0797). * Each account-page action calls the client API's own function; a page password change logs every session out and keeps the devices (ADR-0798). +* The `m.oauth` stage accepts a polling retry with no `auth` once approved, reuses the user's live UIA session, and + also offers its pre-standard name `org.matrix.cross_signing_reset` (ADR-0799). +* A tooling test refuses a default member initialiser holding OAuth page text, which clang 18 checks only at run + time (ADR-0800). ## Security Fixes diff --git a/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md b/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md index d97f770a6..270b6783d 100644 --- a/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md +++ b/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md @@ -8,6 +8,11 @@ Technical Story: phase 8 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md). [ADR-0794](0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md) for `POST /keys/device_signing/upload`. +Amended by [ADR-0799](0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md) +(2026-11-16): with a live approval a retry with no `auth`, or no `session`, also completes the stage; the challenge +reuses the user's live session and offers `org.matrix.cross_signing_reset` as a second flow. The decision below is +otherwise unchanged. + ## Context and Problem Statement ADR-0794 refused every UIA endpoint to an OAuth session with 403 until the account pages existed. The spec's diff --git a/docs/adr/0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md b/docs/adr/0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md new file mode 100644 index 000000000..ac0e34dfb --- /dev/null +++ b/docs/adr/0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md @@ -0,0 +1,79 @@ +# The m.oauth stage accepts a polling retry without a session and reuses the user's live session + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 9 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), part 0. Amends +[ADR-0797](0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md). + +## Context and Problem Statement + +ADR-0797 completed the `m.oauth` stage of a replacing `POST /keys/device_signing/upload` only when the retry carried an +`auth` dict naming the session the challenge issued, as the spec's "OAuth authentication" section describes. Clients +built on matrix-rust-sdk are believed (from its source as recalled, not verified here) to resend the same upload with no +`auth` dict, about twice a second for up to two minutes, until it succeeds, which the reference server accepts. Under +ADR-0797 each such poll issued a fresh UIA session and none ever completed; sixteen polls filled the user's share of +the session pool. Older clients also look for the stage under its pre-standard name, `org.matrix.cross_signing_reset`. + +## Decision Drivers + +* The approval, not the session ID, is what authorises the replacement: it is a per-user flag that any of the user's + OAuth sessions may spend once (ADR-0797), and the session ID is handed to whoever holds the access token. Demanding + the ID adds no secret. +* A client that polls must not consume a UIA session per request, nor be able to fill the pool. +* The spec's form (`auth` with just `session`) keeps working, and nothing else about ADR-0797 changes: one approval, + one stored upload, never a password from an OAuth session, never an approval for a legacy session. + +## Considered Options + +* Accept a retry with no session when an approval is live, and reuse the user's live session in the challenge. +* Keep requiring the session ID and only stop issuing a session per poll. +* Accept any retry, also one naming a session this server did not issue. + +## Decision Outcome + +Chosen option: the first. + +* With a live approval, an OAuth session's replacing upload completes the stage when the request has no `auth`, an + `auth` dict without `session`, or an `auth` dict naming a session this server issued to this user for the purpose + `cross_signing_reset`; and its `type`, if present, is `m.oauth` or `org.matrix.cross_signing_reset`. +* An `auth` dict naming any other session, an `auth` that is not an object, a `type` or `session` that is not a string, + or another `type` (a password stage) gets the challenge and never takes the approval. A password is never checked. +* The challenge names the session the request named when that is live, otherwise the user's newest live session for + the purpose (`live_uia_session`), and issues a new one only when there is none. A user therefore holds at most one + live session for this purpose: sixty polls before the approval cost one session, and a session lives ten minutes, + so a poll more than ten minutes after the first issues the second. The per-user cap of 16 and the pool cap still + apply to that issue. +* The challenge offers the pre-standard name as a second flow with the same parameters: + `{"flows":[{"stages":["m.oauth"]},{"stages":["org.matrix.cross_signing_reset"]}],"params":{"m.oauth":{"url":U},"org.matrix.cross_signing_reset":{"url":U}},"session":S}`. + +### Positive Consequences + +* A polling client succeeds on its first poll after the user approves, and polling costs no new session. + +### Negative Consequences + +* With a live approval, the first replacing upload from any of the user's OAuth sessions spends it, whether or not that + client showed the user the challenge. ADR-0797 already accepted this ("any of the user's OAuth sessions may use it"); + the session ID never narrowed it, since any OAuth session of the user could obtain one by asking. +* `POST /keys/device_signing/upload` is in the `/keys/` per-IP refinement, 120 requests a minute per client address and + route in a fixed window: two polls a second from one address meet the limit exactly, so a client polling slightly + faster, or behind an address shared with other clients, is answered 429 until the window rolls. + +## Pros and Cons of the Options + +### Keep requiring the session ID + +* Good, because it is the spec's literal form. +* Bad, because a client that polls without `auth` never completes, and the user is left with a reset that cannot finish. + +### Accept a retry naming a foreign session + +* Bad, because a session this server did not issue is a malformed request; answering it with the challenge, as every + other UIA endpoint does, keeps one rule for an unknown session. + +## Links + +* Amends [ADR-0797](0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md) +* Pool and per-owner cap: [ADR-0683](0683-uia-sessions-belong-to-an-owner-and-a-full-pool-refuses-instead-of-evicting.md) diff --git a/docs/adr/0800-no-default-member-initialiser-holds-oauth-page-text-because-clang-18-runs-it-at-run-time.md b/docs/adr/0800-no-default-member-initialiser-holds-oauth-page-text-because-clang-18-runs-it-at-run-time.md new file mode 100644 index 000000000..917d1f7cf --- /dev/null +++ b/docs/adr/0800-no-default-member-initialiser-holds-oauth-page-text-because-clang-18-runs-it-at-run-time.md @@ -0,0 +1,71 @@ +# No default member initialiser holds OAuth page text, because clang 18 runs it at run time + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: phase 9 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), part 0. Refines +[ADR-0772](0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md). + +## Context and Problem Statement + +`oauth::HtmlLiteral`, `HtmlName` and `PagePath` check their text in a `consteval` constructor (ADR-0772), so a literal +that holds a character needing escaping should not compile. In phase 8 a struct written as +`oauth::HtmlText message{"That's ..."};`, a default member initialiser, compiled and threw from the `HtmlLiteral` +constructor during a request. + +Compiling probes with the Linux build's compiler (Ubuntu clang 18.1.3, `-std=c++2c`) on the VM showed: + +* `auto w = Wrapper{"it's"};` in a function body is refused: "call to consteval function ... is not a constant + expression". +* The same call in a default member initialiser compiles, whether the class is an aggregate built with `S{}` or with + designated initialisers, has a defaulted constructor, or has a user-provided constructor, and whether the member's + type is `HtmlLiteral` itself or a type built from one. Clang compiles the immediate invocation as an ordinary call, + made when the member is initialised. + +The standard requires the immediate invocation to be a constant expression in every one of these cases (for a +user-provided constructor, which is not immediate-escalating, there is no way out), so this is a compiler defect, not +the language rule. No form of the constructor makes clang 18 refuse it: the check never runs at compile time there. + +## Decision Drivers + +* A page's fixed text must be checked before the server runs, not during a request. +* The compiler cannot be relied on for this form, and the build compiler is not chosen per branch. + +## Considered Options + +* A tooling test that refuses the form in `src/` and `include/`. +* Make page text a template argument (`html<"text">`), which is always constant-evaluated. +* Leave it to review. + +## Decision Outcome + +Chosen option: the tooling test, `page-text-member-initialiser-tooling` +(`tests/tooling/test_page_text_member_initialisers.py`). No data member of a class, struct or union whose declared +type names `HtmlText`, `HtmlLiteral`, `HtmlName` or `PagePath` may have a default member initialiser other than empty +braces (an empty optional or vector holds no text). Text is given where the object is built, as an ordinary +expression that clang does check. The rule is `src/oauth/AGENTS.md` rule 12. The one such initialiser, +`PasswordFailure::message` in `AccountPage.cpp`, now gets its text in `password_failure`. + +### Negative Consequences + +* The test is a text scanner, not a parser: it strips comments, literals and preprocessor lines and tracks which braces + open a class body. Its own cases cover a brace and an `=` initialiser, a wrapped type, local and nested classes, and + the forms it must leave alone. +* A default argument of these types (`f(HtmlText t = "...")`) is not covered; none exists. + +## Pros and Cons of the Options + +### Page text as a template argument + +* Good, because a template argument is constant-evaluated in every context, so the compiler would refuse the form. +* Bad, because every page text literal in the module and the handlers converts implicitly today; changing every call + site is a larger change than the defect, made for one compiler's bug. + +### Leave it to review + +* Bad, because the defect was already missed once and only showed as a request that threw. + +## Links + +* Refines [ADR-0772](0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 09e406770..57f35b68d 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -680,3 +680,5 @@ * [0796 - The account pages keep a fixed 15-minute session in memory, bound to a strict cookie and a form token](0796-the-account-pages-keep-a-fixed-15-minute-session-in-memory-bound-to-a-strict-cookie-and-a-form-token.md) * [0797 - An OAuth session replaces its cross-signing keys through the m.oauth stage and a one-use approval](0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md) * [0798 - Account-page actions share the client API's cores, and every password change ends account-page access](0798-account-page-actions-share-the-client-api-cores-and-every-password-change-ends-account-page-access.md) +* [0799 - The m.oauth stage accepts a polling retry without a session and reuses the user's live session](0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md) +* [0800 - No default member initialiser holds OAuth page text, because clang 18 runs it at run time](0800-no-default-member-initialiser-holds-oauth-page-text-because-clang-18-runs-it-at-run-time.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 6e628494f..623db1c86 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -1242,13 +1242,16 @@ the spec's "Account management" names: `account_management_uri` and all six `org - **Ending page access.** `end_account_page_access` ends every account-page session of the user and withdraws any cross-signing reset approval; `change_local_user_password`, the reset, the page change and `deactivate_user_account` call it. -- **Cross-signing reset (ADR-0797).** The reset page records `CrossSigningResetApprovals::approve` (10 minutes, one - per user) and audits `cross_signing.reset_approved`. A replacing upload from an OAuth session is answered 401 - `{"flows":[{"stages":["m.oauth"]}],"params":{"m.oauth":{"url":"?action=org.matrix.cross_signing_reset"}},"session":""}` - with a UIA session of purpose `cross_signing_reset`. A retry with that session and `type` absent or `m.oauth` takes - the approval; it goes back unless the keys are stored, and a stored upload audits `cross_signing.reset_used`. A - password stage from an OAuth session is never checked; a legacy session keeps `m.login.password` and never touches - an approval. +- **Cross-signing reset (ADR-0797, ADR-0799).** The reset page records `CrossSigningResetApprovals::approve` (10 + minutes, one per user) and audits `cross_signing.reset_approved`. A replacing upload from an OAuth session is + answered 401 with two flows, `m.oauth` and its pre-standard name `org.matrix.cross_signing_reset`, each with the URL + `?action=org.matrix.cross_signing_reset` in `params`, and a UIA session of purpose + `cross_signing_reset`: the session the request named if it is live, else the user's newest live one, else a new one, + so a client that polls holds one session. With a live approval, a retry with no `auth`, an `auth` without `session`, + or one naming that session, with `type` absent or either stage name, takes the approval; it goes back unless the keys + are stored, and a stored upload audits `cross_signing.reset_used`. A `session` this server did not issue for this, + and a password stage, get the challenge; a password from an OAuth session is never checked; a legacy session keeps + `m.login.password` and never touches an approval. - **Logging.** Under `oauth`, `account.page.*` events with `user_id` only. Never a password, a cookie, a form token or the query (`sanitized_http_target` drops it, ADR-0786). diff --git a/docs/coding-rules.md b/docs/coding-rules.md index 381eac70c..e3f442e90 100644 --- a/docs/coding-rules.md +++ b/docs/coding-rules.md @@ -277,6 +277,7 @@ defects on executed paths; a clean run does not prove that all paths are safe. | `generate-sbom-tooling` | `scripts/generate_sbom.py` names every shipped licence row with its licence and wrap pin, is deterministic, and refuses an unmapped row, wrap or section (ADR-0598) | | `release-workflow-tooling`, `stage-release-tarball-tooling` | A release tag must name the `meson.build` version, 0.x releases are prereleases, and release tarballs carry every executable `meson install` installs, both workers included (ADR-0597) | | `docs-site-tooling` | The documentation site builds strictly on every branch, only `main` deploys it, its dependencies are hash-locked, and every published document has a `mkdocs.yml` nav entry | +| `page-text-member-initialiser-tooling` | No data member of type `HtmlText`, `HtmlLiteral`, `HtmlName` or `PagePath` has a default member initialiser other than `{}`: clang 18 runs their compile-time check at run time there (ADR-0800) | | `catch-report-capture-tooling` | A test binary writing its CI skip report still lets a test capture `std::cout` (ADR-0546) | | `tests/tooling/test_packages_workflow.py` | Version consistency and packaging requirements | | `workflow-action-pinning-tooling` | The GitHub Action pinning policy | diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index ce83c259e..ef570a883 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1020,6 +1020,12 @@ quickly finding everything a given `AGENTS.md` file contributed. injection on the login page (CWE-79), and a policy source built from raw input can add directives (CWE-116). Source: `src/oauth/AGENTS.md`. +- **No data member of type `HtmlText`, `HtmlLiteral`, `HtmlName` or `PagePath` has a default member initialiser other + than empty braces** (`page-text-member-initialiser-tooling`). + Why: clang 18 compiles the compile-time text check there as a run-time call, so text that needs escaping is found + only when a request throws, not when the build runs (ADR-0800). + Source: `src/oauth/AGENTS.md`. + - **PKCE is `S256` only, compared in constant time.** Why: `plain` sends the verifier through the browser, which defeats PKCE, and a variable-time comparison leaks how much of a guess matched (CWE-208). @@ -1082,11 +1088,12 @@ quickly finding everything a given `AGENTS.md` file contributed. - **An account-page form is accepted only with this server's `Origin`, the `__Host-mv-account` session and that session's form token (constant time); each page action calls the client API's own function; every password change, reset and deactivation ends the user's account-page sessions and reset approvals; a cross-signing reset approval is - spent only by a stored upload and is never usable by a password session or with a password stage.** + spent only by a stored upload and is never usable by a password session or with a password stage; the `m.oauth` + challenge reuses the user's live UIA session, so a polling client costs one session.** Why: a forged post signs out a device or deactivates an account (CWE-352); one session's token must not act for another; a copied action drifts and misses a revocation step (CWE-613); a page session or approval that outlives a password change keeps a stolen credential's reach (CWE-613); a token alone must not replace a user's cross-signing - identity (CWE-306) (ADR-0796, ADR-0797, ADR-0798). + identity (CWE-306); a session issued per poll fills the user's UIA pool (CWE-770) (ADR-0796 to ADR-0799). Source: `src/homeserver/AGENTS.md`. ## HTTP and network boundary diff --git a/include/merovingian/oauth/HtmlLiteral.hpp b/include/merovingian/oauth/HtmlLiteral.hpp index dd82b3665..6f237d295 100644 --- a/include/merovingian/oauth/HtmlLiteral.hpp +++ b/include/merovingian/oauth/HtmlLiteral.hpp @@ -9,7 +9,9 @@ namespace merovingian::oauth // Page text fixed at compile time: a string literal of printable ASCII (space to `~`) holding none of `& < > " '`, // so it needs no escaping. The constructor is consteval: a value that is not a constant expression, or that breaks -// the rule, does not compile (ADR-0772). Text known only at run time goes through HtmlText::escape. +// the rule, does not compile (ADR-0772). Text known only at run time goes through HtmlText::escape. Clang 18 does not +// apply this in a default member initialiser, where the check runs at run time instead; such initialisers are refused +// by a tooling test (ADR-0800). The same holds for HtmlName and PagePath. class HtmlLiteral final { public: diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index c6f4628b5..b4e782cfb 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -189,7 +189,10 @@ Rules (ADR-0796 to ADR-0798): - **The `m.oauth` stage** (`oauth_cross_signing_reset_stage` in `ClientServerRuntime.cpp`) is offered only to an OAuth session's replacing upload; a legacy session keeps `m.login.password` and never touches an approval. The approval is taken into a `TakenResetApproval`, which restores it on every way out; `spend()` only after `store_key_api_payload` - succeeds. A password stage from an OAuth session is answered with the challenge and never checked. + succeeds. A password stage from an OAuth session is answered with the challenge and never checked. A retry with no + `auth` or no `session` completes the stage when an approval is live (clients poll that way); a `session` this server + did not issue for this does not. The challenge names `live_uia_session` before issuing one, so polling never costs a + session per request (ADR-0799); keep both when changing the stage. - Log `user_id` only (`account.page.*`); never a password, the cookie, a form token or the query. `POST /_merovingian/oauth2/register` is `register_oauth_client` (`OAuthClientRegistration.cpp`), answered before the diff --git a/src/homeserver/AccountPage.cpp b/src/homeserver/AccountPage.cpp index 1713ac531..a83a554f2 100644 --- a/src/homeserver/AccountPage.cpp +++ b/src/homeserver/AccountPage.cpp @@ -419,9 +419,9 @@ namespace struct PasswordFailure final { std::uint16_t status{status_unauthorized}; - // A default member initialiser is not constant-evaluated: the HtmlLiteral check runs at run time here, so the - // text holds nothing that would need escaping. - oauth::HtmlText message{"That is not the password of this account."}; + // No default member initialiser: clang 18 does not constant-evaluate an HtmlLiteral there (src/oauth/AGENTS.md + // rule 12, ADR-0800), so every return below names its text. + oauth::HtmlText message; std::optional retry_after_seconds{}; }; @@ -446,7 +446,7 @@ namespace case Outcome::account_deactivated: break; } - return {}; + return {status_unauthorized, oauth::HtmlText{"That is not the password of this account."}, std::nullopt}; } [[nodiscard]] auto with_retry_after(LocalHttpResponse response, std::optional seconds) diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index fab957519..bfe1d51e1 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -2265,6 +2265,24 @@ namespace }); } + // The newest live session this server issued to `owner` for `purpose`, or nullopt. A challenge that may be + // repeated by polling (the `m.oauth` stage, ADR-0799) names it instead of issuing another, so the owner holds one + // session for the purpose at a time. One pass over the pool, which is capped at `max_uia_sessions`. + [[nodiscard]] auto live_uia_session(ClientServerRuntime const& rt, std::string_view purpose, std::string_view owner) + -> std::optional + { + auto const now_ms = wall_clock_milliseconds(); + for (auto session = rt.uia_sessions.rbegin(); session != rt.uia_sessions.rend(); ++session) + { + if (!session->session_id.empty() && session->purpose == purpose && session->owner == owner && + (now_ms <= session->created_at_ms || now_ms - session->created_at_ms <= uia_session_ttl_ms)) + { + return session->session_id; + } + } + return std::nullopt; + } + [[nodiscard]] auto normalize_threepid_address(std::string_view medium, std::string_view address) -> std::string { if (medium == "email") @@ -13458,14 +13476,25 @@ namespace std::uint64_t approval_expires_at_ms{0U}; }; + // The name the `m.oauth` stage had before spec v1.17, offered as a second flow with the same parameters for clients + // that still look for it (ADR-0799). + constexpr auto cross_signing_reset_unstable_stage = std::string_view{"org.matrix.cross_signing_reset"}; + // The `m.oauth` User-Interactive Authentication stage of a replacing cross-signing upload from an OAuth session - // (spec v1.19 "OAuth authentication" and "Account management"; ADR-0797). nullopt when the stage cannot be offered - // (OAuth off, or no usable `server.public_baseurl`): the caller keeps the ADR-0794 403. + // (spec v1.19 "OAuth authentication" and "Account management"; ADR-0797, ADR-0799). nullopt when the stage cannot + // be offered (OAuth off, or no usable `server.public_baseurl`): the caller keeps the ADR-0794 403. + // + // The stage is complete when the user approved the reset on the account page in the last ten minutes and the + // request either names a session this server issued to this user for this purpose, or names no session at all + // (no `auth` dict, or one without `session`): a client that polls by resending the same upload is accepted once + // the approval exists (ADR-0799). The approval is a per-user flag any of the user's OAuth sessions may spend once, + // so the session ID adds no secret. A `type` other than absent, `m.oauth` or the pre-standard name (a password + // stage) is answered with the challenge and never checked: an OAuth session cannot complete the upload with a + // password. So is a `session` this server did not issue to this user for this purpose. The approval is taken here + // and spent only by a stored upload. // - // The stage is complete only when the `auth` dict carries a session this server issued to this user for this - // purpose, its `type` is absent or `m.oauth` (a password stage is answered with the challenge and never checked: - // an OAuth session cannot complete the upload with a password), and the user approved the reset on the account page - // in the last ten minutes. The approval is taken here and spent only by a stored upload. + // A challenge reuses the user's newest live session for this purpose before issuing one, so a client polling + // before the approval holds one session, not one per poll (a session lives ten minutes; ADR-0799). [[nodiscard]] auto oauth_cross_signing_reset_stage(ClientServerRuntime& rt, LocalHttpRequest const& req, std::string_view user, std::optional const& body) @@ -13484,31 +13513,55 @@ namespace auto const challenge = [base_url](std::string_view session) { auto const url = oauth::account_action_address(base_url->url(oauth::account_path), oauth::account_action_cross_signing_reset); + auto const flow = [](std::string_view stage) { + return json_obj({json_member("stages", json_arr({json_str(std::string{stage})}))}); + }; + auto const params = [&url]() { + return json_obj({json_member("url", json_str(url))}); + }; auto const body_json = json_obj({ - json_member("flows", json_arr({json_obj({json_member("stages", json_arr({json_str("m.oauth")}))})})), + json_member("flows", json_arr({flow("m.oauth"), flow(cross_signing_reset_unstable_stage)})), json_member("params", - json_obj({json_member("m.oauth", json_obj({json_member("url", json_str(url))}))})), + json_obj({json_member("m.oauth", params()), + json_member(std::string{cross_signing_reset_unstable_stage}, params())})), json_member("session", json_str(std::string{session})), }); return OAuthResetStage{resp(401U, json_serialize(body_json)), 0U}; }; + // `auth`, when present, must be an object, and its `type` and `session`, when present, strings: anything else + // is answered with the challenge, as a foreign session is. + auto const* const auth_value = body.has_value() ? object_member(*body, "auth") : nullptr; auto const* const auth = body.has_value() ? object_member_object(*body, "auth") : nullptr; + auto const* const type_value = auth != nullptr ? object_member(*auth, "type") : nullptr; auto const* const type = auth != nullptr ? string_member(*auth, "type") : nullptr; + auto const* const session_value = auth != nullptr ? object_member(*auth, "session") : nullptr; auto const* const session = auth != nullptr ? string_member(*auth, "session") : nullptr; - if (session != nullptr && uia_session_is_valid(rt, cross_signing_reset_uia_purpose, *session, user)) + auto const well_formed = (auth_value == nullptr || auth != nullptr) && + (type_value == nullptr || type != nullptr) && + (session_value == nullptr || session != nullptr); + auto const issued_session = + session != nullptr && uia_session_is_valid(rt, cross_signing_reset_uia_purpose, *session, user); + auto const names_this_stage = + type == nullptr || *type == "m.oauth" || *type == cross_signing_reset_unstable_stage; + if (well_formed && names_this_stage && (session_value == nullptr || issued_session)) { - if (type == nullptr || *type == "m.oauth") + if (auto const expires_at_ms = + rt.homeserver.cross_signing_reset_approvals.take(user, oauth_wall_clock_ms()); + expires_at_ms.has_value()) { - if (auto const expires_at_ms = - rt.homeserver.cross_signing_reset_approvals.take(user, oauth_wall_clock_ms()); - expires_at_ms.has_value()) - { - return OAuthResetStage{std::nullopt, *expires_at_ms}; - } + return OAuthResetStage{std::nullopt, *expires_at_ms}; } - // Not approved yet, or another stage: the same session, so the client keeps waiting on it. + } + // Not approved yet, another stage, or a session this server did not issue for this: the challenge, naming the + // session the request named when it is a live one, else the user's newest live one, so polling issues none. + if (issued_session) + { return challenge(*session); } + if (auto const live = live_uia_session(rt, cross_signing_reset_uia_purpose, user); live.has_value()) + { + return challenge(*live); + } auto const issued = issue_uia_session(rt, cross_signing_reset_uia_purpose, user); if (!issued.has_value()) { diff --git a/src/oauth/AGENTS.md b/src/oauth/AGENTS.md index ec118344a..dd2eecef5 100644 --- a/src/oauth/AGENTS.md +++ b/src/oauth/AGENTS.md @@ -61,6 +61,12 @@ Pure functions and value types for the built-in OAuth 2.0 API 10. **A hand-off allowlist entry is an origin or a bare scheme, never a prefix** (ADR-0774). 11. **Client metadata is validated once, by `ClientMetadata::validate`,** also when a stored registration is read back. The client ID is a keyed hash of `canonical_bytes()` (phase 4); do not hash anything else for it. +12. **No default member initialiser holds page text** (ADR-0800). Clang 18 does not constant-evaluate a consteval call + in a default member initialiser: it compiles `HtmlText message{"..."}` there and runs the `HtmlLiteral` check when + the member is initialised, so a bad literal throws during a request instead of failing the build. No data member + whose type names `HtmlText`, `HtmlLiteral`, `HtmlName` or `PagePath` may have an initialiser other than empty + braces; give the text where the object is built. `page-text-member-initialiser-tooling` + (`tests/tooling/test_page_text_member_initialisers.py`) scans `src/` and `include/` for it. ## Tests diff --git a/tests/conformance/test_oauth_account_management_conformance.cpp b/tests/conformance/test_oauth_account_management_conformance.cpp index 24a183364..01343a703 100644 --- a/tests/conformance/test_oauth_account_management_conformance.cpp +++ b/tests/conformance/test_oauth_account_management_conformance.cpp @@ -28,6 +28,7 @@ #include +#include #include #include #include @@ -238,11 +239,14 @@ SCENARIO( REQUIRE(challenge.status == 401U); auto const* flows = object_member_as_array(body, "flows"); REQUIRE(flows != nullptr); - REQUIRE(flows->size() == 1U); - auto const* flow = std::get_if(&flows->front().storage()); - REQUIRE(flow != nullptr); - // Spec: "the response body includes m.oauth in the flows list". - REQUIRE(string_array(*flow, "stages") == std::vector{"m.oauth"}); + // Spec: "the response body includes m.oauth in the flows list". The list may hold other flows (this + // server adds the pre-standard stage name as a second one, ADR-0799); one of them is m.oauth alone. + auto const oauth_flows = + std::ranges::count_if(*flows, [](merovingian::canonicaljson::Value const& value) { + auto const* flow = std::get_if(&value.storage()); + return flow != nullptr && string_array(*flow, "stages") == std::vector{"m.oauth"}; + }); + REQUIRE(oauth_flows == 1); auto const* params = object_of(body, "params"); REQUIRE(params != nullptr); auto const* oauth_params = object_of(*params, "m.oauth"); diff --git a/tests/integration/test_oauth_account_pages_flow.cpp b/tests/integration/test_oauth_account_pages_flow.cpp index 1b8f25e84..fb386a2c5 100644 --- a/tests/integration/test_oauth_account_pages_flow.cpp +++ b/tests/integration/test_oauth_account_pages_flow.cpp @@ -649,9 +649,11 @@ SCENARIO("An OAuth session replaces its cross-signing keys through the m.oauth s { CHECK(repeat.status == 200U); REQUIRE(challenge.status == 401U); - CHECK(contains(challenge.body, R"("flows":[{"stages":["m.oauth"]}])")); CHECK(contains(challenge.body, - std::string{R"("params":{"m.oauth":{"url":")"} + std::string{reset_url} + R"("}})")); + R"("flows":[{"stages":["m.oauth"]},{"stages":["org.matrix.cross_signing_reset"]}])")); + CHECK(contains(challenge.body, std::string{R"("params":{"m.oauth":{"url":")"} + std::string{reset_url} + + R"("},"org.matrix.cross_signing_reset":{"url":")" + + std::string{reset_url} + R"("}})")); REQUIRE_FALSE(session.empty()); CHECK(before_approval.status == 401U); CHECK(member(before_approval, "session") == session); @@ -667,6 +669,105 @@ SCENARIO("An OAuth session replaces its cross-signing keys through the m.oauth s } } +SCENARIO("A client polling the replacing upload with no auth holds one session and succeeds once after approval", + "[integration][oauth][oauth-account][oauth-uia]") +{ + GIVEN("alice signed in through OAuth with her first cross-signing keys, and on the account page") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const oauth = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + REQUIRE(oauth.ok); + auto const upload = [&](std::string const& members) { + return send(rt, "POST", std::string{upload_path}, oauth.access_token, "{" + members + "}"); + }; + REQUIRE(upload(make_cross_signing_set(std::string{alice_id}).selected_members(true, true, true)).status == + 200U); + auto const alice = account_sign_in(rt, "alice", alice_password); + REQUIRE_FALSE(alice.form_token.empty()); + auto const approve = [&]() { + return post_account(rt, session_form(alice, "approve_cross_signing_reset"), alice.browser).status; + }; + auto const reset_sessions = [&]() { + return std::ranges::count_if(rt.uia_sessions, [](auto const& session) { + return session.owner == alice_id && session.purpose == "cross_signing_reset"; + }); + }; + auto const replacement = make_cross_signing_set(std::string{alice_id}).master_member(); + + WHEN("the same replacing upload is sent sixty times with no auth, then once more after the approval") + { + auto statuses = std::vector{}; + auto session_ids = std::vector{}; + for (auto poll = 0; poll < 60; ++poll) + { + auto const answer = upload(replacement); + statuses.push_back(static_cast(answer.status)); + session_ids.push_back(member(answer, "session")); + } + auto const sessions_before_approval = reset_sessions(); + auto const approved = approve(); + auto const accepted = upload(replacement); + auto const after = upload(make_cross_signing_set(std::string{alice_id}).master_member()); + + THEN("every poll is the challenge naming one session; the poll after the approval stores the keys once") + { + CHECK(std::ranges::all_of(statuses, [](std::uint16_t status) { + return status == 401U; + })); + REQUIRE_FALSE(session_ids.front().empty()); + CHECK(std::ranges::all_of(session_ids, [&](std::string const& id) { + return id == session_ids.front(); + })); + CHECK(sessions_before_approval == 1); + CHECK(approved == 200U); + CHECK(accepted.status == 200U); + CHECK_FALSE(approval_held(rt, alice_id)); + CHECK(audit_count(rt, "cross_signing.reset_used") == 1U); + CHECK(after.status == 401U); + CHECK(member(after, "session") == session_ids.front()); + } + } + + WHEN("after an approval, the retry carries an auth dict without a session, or the pre-standard stage name") + { + REQUIRE(approve() == 200U); + auto const no_session = upload(replacement + R"(,"auth":{"type":"m.oauth"})"); + auto const session = + member(upload(make_cross_signing_set(std::string{alice_id}).master_member()), "session"); + REQUIRE(approve() == 200U); + auto const unstable = + upload(make_cross_signing_set(std::string{alice_id}).master_member() + + R"(,"auth":{"type":"org.matrix.cross_signing_reset","session":")" + session + R"("})"); + + THEN("both complete the stage, each spending one approval") + { + CHECK(no_session.status == 200U); + REQUIRE_FALSE(session.empty()); + CHECK(unstable.status == 200U); + CHECK_FALSE(approval_held(rt, alice_id)); + CHECK(audit_count(rt, "cross_signing.reset_used") == 2U); + } + } + + WHEN("after an approval, the retry names a session this server did not issue, or sends auth that is no object") + { + REQUIRE(approve() == 200U); + auto const foreign = upload(replacement + R"(,"auth":{"session":"not-a-session-of-ours"})"); + auto const not_object = upload(replacement + R"(,"auth":"m.oauth")"); + + THEN("each gets the challenge and the approval stays") + { + CHECK(foreign.status == 401U); + CHECK(contains(foreign.body, "m.oauth")); + CHECK(not_object.status == 401U); + CHECK(approval_held(rt, alice_id)); + CHECK(audit_count(rt, "cross_signing.reset_used") == 0U); + } + } + } +} + SCENARIO("A cross-signing reset approval is not usable expired, by a refused upload, by a password stage or by a " "password session", "[integration][oauth][oauth-account][oauth-uia]") diff --git a/tests/meson.build b/tests/meson.build index e261922e1..e43868dce 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -157,6 +157,12 @@ shell = find_program('sh') args: [meson.project_source_root() / 'tests' / 'tooling' / 'test_outbound_answer_trust.py'], ) + test( + 'page-text-member-initialiser-tooling', + python, + args: [meson.project_source_root() / 'tests' / 'tooling' / 'test_page_text_member_initialisers.py'], + ) + test( 'startup-hardening-gate-tooling', python, diff --git a/tests/tooling/test_page_text_member_initialisers.py b/tests/tooling/test_page_text_member_initialisers.py new file mode 100644 index 000000000..390c1407e --- /dev/null +++ b/tests/tooling/test_page_text_member_initialisers.py @@ -0,0 +1,204 @@ +#!/usr/bin/env python3 +"""No default member initialiser holds OAuth page text (ADR-0800). + +`oauth::HtmlLiteral`, `HtmlName` and `PagePath` check their text in a consteval +constructor, so a literal that breaks the rule should not compile. Clang 18 (the +Linux build's compiler) does not constant-evaluate an immediate invocation in a +default member initialiser: it compiles the call and runs it when the member is +initialised, so a bad literal throws during a request instead of failing the +build. Phase 8 met it as an apostrophe on the account page. The compiler cannot +be made to refuse the form, so this test does: no data member of a class, struct +or union whose declared type names `HtmlText`, `HtmlLiteral`, `HtmlName` or +`PagePath` may have a default member initialiser other than empty braces (an +empty optional or vector holds no text), anywhere under `src/` or `include/`. +Give the text where the object is built instead. + +The scanner is text-based, not a C++ parser. It removes comments, string and +character literals and preprocessor lines, tracks which braces open a class body, +and judges each declaration made directly in one. +""" +from __future__ import annotations + +import re +import unittest +from pathlib import Path + + +REPO_ROOT = Path(__file__).resolve().parents[2] +SCANNED_DIRS = (REPO_ROOT / "src", REPO_ROOT / "include") +SUFFIXES = {".cpp", ".hpp", ".h", ".cc", ".hh", ".ipp"} + +PAGE_TEXT_TYPE = re.compile(r"\b(?:HtmlText|HtmlLiteral|HtmlName|PagePath)\b") +RAW_STRING = re.compile(r'R"([^(\s"\\]{0,16})\((?:.|\n)*?\)\1"') +STRING = re.compile(r'"(?:\\.|[^"\\\n])*"') +CHARACTER = re.compile(r"'(?:\\.|[^'\\\n])'") +BLOCK_COMMENT = re.compile(r"/\*(?:.|\n)*?\*/") +LINE_COMMENT = re.compile(r"//[^\n]*") +PREPROCESSOR = re.compile(r"^[ \t]*#[^\n]*(?:\\\n[^\n]*)*", re.M) +ATTRIBUTE = re.compile(r"\[\[.*?\]\]", re.S) +ACCESS = re.compile(r"^\s*(?:(?:public|private|protected)\s*:\s*)+") +CLASS_HEAD = re.compile(r"^\s*(?:template\s*<.*>\s*)?(?:struct|class|union)\b") +ENUM_HEAD = re.compile(r"^\s*enum\b") +# Declarations directly in a class body that are not data members with an initialiser. +NOT_A_MEMBER = re.compile( + r"^\s*(?:static|constexpr|constinit|using|typedef|friend|template|static_assert|enum|struct|class|union)\b" +) +DECLARATOR_END = re.compile(r"[A-Za-z_]\w*\s*$") + + +def strip_code(text: str) -> str: + """The text with comments, literals and preprocessor lines blanked, line breaks kept.""" + + def blank(match: re.Match[str]) -> str: + return re.sub(r"[^\n]", " ", match.group(0)) + + def blank_literal(match: re.Match[str]) -> str: + # A literal keeps a mark, so `{"text"}` is not mistaken for empty braces. + return "0" + blank(match)[1:] + + for pattern in (RAW_STRING, BLOCK_COMMENT, LINE_COMMENT, STRING, CHARACTER, PREPROCESSOR): + text = pattern.sub(blank_literal if pattern in (RAW_STRING, STRING, CHARACTER) else blank, text) + return text + + +def is_initialised_page_text_member(statement: str, opener: str) -> bool: + """Whether `statement`, the text in a class body before `opener` (`{` or `;`), declares a page text member with a + default member initialiser.""" + statement = ACCESS.sub("", ATTRIBUTE.sub(" ", statement)) + if NOT_A_MEMBER.match(statement): + return False + if opener == "{": + declaration, _, _ = statement.partition("=") + if "=" not in statement and not DECLARATOR_END.search(declaration): + return False + else: + if "=" not in statement: + return False + declaration, _, _ = statement.partition("=") + if "operator" in declaration: + return False + # A function (declaration or definition) has a parameter list before any initialiser. + if "(" in declaration: + return False + return PAGE_TEXT_TYPE.search(declaration) is not None + + +def initialised_page_text_members(text: str) -> list[int]: + """The line numbers of every page text data member with a default member initialiser in `text`.""" + code = strip_code(text) + findings: list[int] = [] + stack: list[str] = [] + statement_start = 0 + for index, char in enumerate(code): + if char not in "{};": + continue + statement = code[statement_start:index] + in_class = bool(stack) and stack[-1] == "class" + if char == "{": + # An empty `{}` value-initialises (an empty optional or vector) and holds no text. + empty_braces = code[index + 1 :].lstrip().startswith("}") + if in_class and not empty_braces and is_initialised_page_text_member(statement, "{"): + findings.append(code.count("\n", 0, index) + 1) + opens_class = CLASS_HEAD.match(ACCESS.sub("", statement)) is not None and "(" not in statement + stack.append("class" if opens_class and not ENUM_HEAD.match(statement) else "other") + elif char == "}": + if stack: + stack.pop() + elif in_class and is_initialised_page_text_member(statement, ";"): + findings.append(code.count("\n", 0, index) + 1) + statement_start = index + 1 + return findings + + +def scanned_files() -> list[Path]: + return sorted( + path + for directory in SCANNED_DIRS + for path in directory.rglob("*") + if path.is_file() and path.suffix in SUFFIXES + ) + + +class ScannerFindsTheForm(unittest.TestCase): + def test_a_brace_initialised_member_is_found(self) -> None: + text = 'struct Failure final\n{\n int status{1};\n oauth::HtmlText message{"it\'s"};\n};\n' + self.assertEqual(initialised_page_text_members(text), [4]) + + def test_an_equals_initialised_member_is_found(self) -> None: + text = 'class Page\n{\npublic:\n HtmlLiteral title = "Sign in";\n};\n' + self.assertEqual(initialised_page_text_members(text), [4]) + + def test_a_wrapped_type_is_found(self) -> None: + text = 'struct S\n{\n std::optional notice{oauth::HtmlText{"x"}};\n};\n' + self.assertEqual(initialised_page_text_members(text), [3]) + + def test_a_local_struct_in_a_function_is_found(self) -> None: + text = 'auto f() -> int\n{\n struct Local\n {\n PagePath path{"/a"};\n };\n return 0;\n}\n' + self.assertEqual(initialised_page_text_members(text), [5]) + + def test_a_nested_struct_is_found(self) -> None: + text = 'struct Outer\n{\n struct Inner final : Base\n {\n HtmlName name{"n"};\n };\n};\n' + self.assertEqual(initialised_page_text_members(text), [5]) + + +class ScannerLeavesOtherFormsAlone(unittest.TestCase): + def test_a_member_without_an_initialiser(self) -> None: + text = "struct S\n{\n oauth::HtmlText message;\n int count{0};\n};\n" + self.assertEqual(initialised_page_text_members(text), []) + + def test_an_empty_brace_initialiser(self) -> None: + text = "struct S\n{\n std::optional error{};\n std::vector names = {};\n};\n" + self.assertEqual(initialised_page_text_members(text), []) + + def test_a_local_variable(self) -> None: + text = 'auto f() -> void\n{\n auto text = oauth::HtmlText{"x"};\n HtmlText other{"y"};\n}\n' + self.assertEqual(initialised_page_text_members(text), []) + + def test_member_functions_and_static_constants(self) -> None: + text = ( + "class Page\n{\npublic:\n" + " Page(HtmlText title);\n" + " [[nodiscard]] auto title() const -> HtmlText const& { return m_title; }\n" + ' static constexpr PagePath path{"/a"};\n' + " auto operator=(HtmlText const&) -> Page& = delete;\n" + "private:\n HtmlText m_title;\n};\n" + ) + self.assertEqual(initialised_page_text_members(text), []) + + def test_text_in_comments_and_strings(self) -> None: + text = ( + "struct S\n{\n" + ' // HtmlText message{"x"};\n' + ' char const* doc{"HtmlText message{}"};\n' + ' char const* raw{R"(HtmlLiteral x = "y";)"};\n' + "};\n" + ) + self.assertEqual(initialised_page_text_members(text), []) + + def test_an_enum_class_body(self) -> None: + text = "enum class Kind\n{\n html_text = 1,\n};\n" + self.assertEqual(initialised_page_text_members(text), []) + + +class SourcesHaveNoInitialisedPageTextMember(unittest.TestCase): + def test_the_scan_reads_the_page_text_types(self) -> None: + files = scanned_files() + self.assertTrue(any(path.name == "HtmlText.hpp" for path in files)) + self.assertTrue(any(path.name == "AccountPage.cpp" for path in files)) + + def test_no_page_text_member_has_a_default_member_initialiser(self) -> None: + findings = [ + f"{path.relative_to(REPO_ROOT).as_posix()}:{line}" + for path in scanned_files() + for line in initialised_page_text_members(path.read_text(encoding="utf-8")) + ] + self.assertEqual( + findings, + [], + "a data member of type HtmlText, HtmlLiteral, HtmlName or PagePath has a default member initialiser; " + "clang 18 runs its compile-time check at run time there (ADR-0800). Give the text where the object is built.", + ) + + +if __name__ == "__main__": + unittest.main() From cd52c3804d68947223025defaaf7708fd88a584f Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 08:55:32 +0000 Subject: [PATCH 19/42] Turn the legacy authentication API off with server.oauth.legacy_api_enabled=false (ADR-0801) legacy_auth_refusal is the one decision every legacy route asks: GET /login, a user's login, the SSO redirects and get_token answer 404 M_UNRECOGNIZED; m.login.application_service and an appservice registration without inhibit_login answer 400 M_APPSERVICE_LOGIN_UNSUPPORTED; a user's registration 403 M_FORBIDDEN. Sessions already issued carry on, and with the key true no answer changes. Co-Authored-By: Claude Opus 5.5 --- .../references/module-invariants.md | 2 + CHANGELOG.md | 2 + ...ch-refused-use-answers-as-the-spec-says.md | 70 ++++ docs/adr/index.md | 1 + docs/auth-identity.md | 13 + docs/matrix-v1.19-client-server-api.md | 1 + docs/security-coding-rules.md | 8 + docs/user-manual.md | 25 +- .../homeserver/LegacyAuthPolicy.hpp | 36 ++ .../homeserver/LegacyAuthRefusal.hpp | 20 + .../merovingian/homeserver/LegacyAuthUse.hpp | 31 ++ src/homeserver/AGENTS.md | 6 + src/homeserver/ClientServerRuntime.cpp | 82 ++++- src/homeserver/LegacyAuthPolicy.cpp | 42 +++ src/homeserver/meson.build | 1 + tests/conformance/AGENTS.md | 1 + .../test_oauth_legacy_api_conformance.cpp | 188 ++++++++++ .../test_oauth_legacy_api_flow.cpp | 344 ++++++++++++++++++ tests/meson.build | 3 + tests/unit/test_legacy_auth_policy.cpp | 118 ++++++ 20 files changed, 988 insertions(+), 6 deletions(-) create mode 100644 docs/adr/0801-one-function-decides-the-legacy-api-switch-and-each-refused-use-answers-as-the-spec-says.md create mode 100644 include/merovingian/homeserver/LegacyAuthPolicy.hpp create mode 100644 include/merovingian/homeserver/LegacyAuthRefusal.hpp create mode 100644 include/merovingian/homeserver/LegacyAuthUse.hpp create mode 100644 src/homeserver/LegacyAuthPolicy.cpp create mode 100644 tests/conformance/test_oauth_legacy_api_conformance.cpp create mode 100644 tests/integration/test_oauth_legacy_api_flow.cpp create mode 100644 tests/unit/test_legacy_auth_policy.cpp diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index 8ba6c0eac..3741c77cf 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -267,6 +267,8 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that `Referrer-Policy: same-origin`, and a form post is accepted only by `form_post_origin_is_accepted` (ADR-0784). - Every absolute OAuth address comes from `OAuthBaseUrl` with a path from `OAuthPaths.hpp` (ADR-0773). A hand-off allowlist entry is an https origin or a bare private-use scheme, never a prefix (ADR-0774). +- The legacy API switch is `legacy_auth_refusal` alone; a route that issues a legacy session asks it (ADR-0801). + `src/homeserver/AGENTS.md` ## src/observability diff --git a/CHANGELOG.md b/CHANGELOG.md index 0703319da..b6263bd4c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -64,6 +64,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) also offers its pre-standard name `org.matrix.cross_signing_reset` (ADR-0799). * A tooling test refuses a default member initialiser holding OAuth page text, which clang 18 checks only at run time (ADR-0800). +* `server.oauth.legacy_api_enabled=false` stops legacy logins and registrations; appservices register with + `inhibit_login`, and sessions already issued carry on (ADR-0801). ## Security Fixes diff --git a/docs/adr/0801-one-function-decides-the-legacy-api-switch-and-each-refused-use-answers-as-the-spec-says.md b/docs/adr/0801-one-function-decides-the-legacy-api-switch-and-each-refused-use-answers-as-the-spec-says.md new file mode 100644 index 000000000..e3f2fea23 --- /dev/null +++ b/docs/adr/0801-one-function-decides-the-legacy-api-switch-and-each-refused-use-answers-as-the-spec-says.md @@ -0,0 +1,70 @@ +# One function decides the legacy API switch, and each refused use answers as the spec says + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: plan P9, `server.oauth.legacy_api_enabled=false`, [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), +[ADR-0761](0761-the-legacy-authentication-api-stays-on-by-default-and-a-config-key-turns-it-off.md) + +## Context and Problem Statement + +With `server.oauth.legacy_api_enabled=false` the legacy authentication API must stop listing logins and stop issuing +users new sessions, while application services keep `POST /register` and sessions already issued carry on. Seven +places issue or advertise a legacy session. Where is the decision made, and what does each refused use answer? + +## Considered Options + +* One pure function, `legacy_auth_refusal(OAuthConfig, LegacyAuthUse)`, that every affected route asks, answering + the spec's status and errcode where the spec gives one and `404 M_UNRECOGNIZED` otherwise. +* A test of `legacy_api_enabled` in each route. +* `404 M_UNRECOGNIZED` for every refused use, application services included. + +## Decision Outcome + +Chosen option: the first. `homeserver::legacy_auth_refusal` (`LegacyAuthPolicy.cpp`) returns nothing while the key is +true, so with the default no answer changes. With it false: + +| Use | Route | Answer | Spec | +|---|---|---|---| +| `login_flows` | `GET /login` | 404 `M_UNRECOGNIZED` | `GET /login` 404: "the homeserver does not support the legacy authentication API" | +| `user_login` | `POST /login`, any type but `m.login.application_service` | 404 `M_UNRECOGNIZED` | none of its own | +| `appservice_login` | `POST /login` `m.login.application_service` | 400 `M_APPSERVICE_LOGIN_UNSUPPORTED` | "it MUST return a 400 HTTP status code with an M_APPSERVICE_LOGIN_UNSUPPORTED error code" | +| `user_registration` | `POST /register` for a user | 403 `M_FORBIDDEN` | `POST /register` 403: "registration is generally not supported by the homeserver" | +| `appservice_registration_with_login` | `POST /register` `m.login.application_service` without `"inhibit_login": true` | 400 `M_APPSERVICE_LOGIN_UNSUPPORTED` | "the server MUST return a 400 HTTP status code with an M_APPSERVICE_LOGIN_UNSUPPORTED error code" | +| `sso_redirect` | `GET /login/sso/redirect`, `/{idpId}` | 404 `M_UNRECOGNIZED` | none of its own | +| `login_token_mint` | `POST /login/get_token`, the `m.get_login_token` capability | 404 `M_UNRECOGNIZED`, capability `enabled: false` | none of its own | + +Rules the routes keep: + +* The application-service checks of `POST /register` (a valid `as_token`, 401 otherwise) come first; the + `inhibit_login` refusal follows, before the namespace checks and before the user is created, so a refusal stores + nothing. With the legacy API on an application service without `inhibit_login` still gets a token. +* `POST /login` reads the body's `type` only once a login is refused, so with the key true the body is parsed once, + as before. +* A user's `POST /register` is refused before User-Interactive Authentication, so no UIA session is issued. +* Not uses, and left alone: `/refresh`, `/logout`, `/logout/all`, every authenticated endpoint and UIA (P9: sessions + already issued carry on), `GET /register/available`, the registration token validity check, the email and phone + token requests and password reset by email, none of which issues a session. The in-process router's + `/login` and `/register` (`LocalHttpRouter.cpp`) are not reachable from a client and are not gated. + +### Positive Consequences + +* One place to read what the switch does, and one unit-tested table. +* An application service gets the answer the spec names, which tells its operator what to change. + +### Negative Consequences + +* `POST /login` for a user, the SSO redirects and `get_token` answer as if absent, which a client cannot tell from an + old server. The spec gives no other answer for them. + +## Pros and Cons of the Options + +### A test of `legacy_api_enabled` in each route + +* Bad, because the seven places drift: a new route that issues a session would need its own copy. + +### `404 M_UNRECOGNIZED` for every refused use + +* Bad, because the spec requires 400 `M_APPSERVICE_LOGIN_UNSUPPORTED` for application services, and `POST /register` + has a 403 for "registration is generally not supported". diff --git a/docs/adr/index.md b/docs/adr/index.md index 57f35b68d..3bdface20 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -682,3 +682,4 @@ * [0798 - Account-page actions share the client API's cores, and every password change ends account-page access](0798-account-page-actions-share-the-client-api-cores-and-every-password-change-ends-account-page-access.md) * [0799 - The m.oauth stage accepts a polling retry without a session and reuses the user's live session](0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md) * [0800 - No default member initialiser holds OAuth page text, because clang 18 runs it at run time](0800-no-default-member-initialiser-holds-oauth-page-text-because-clang-18-runs-it-at-run-time.md) +* [0801 - One function decides the legacy API switch, and each refused use answers as the spec says](0801-one-function-decides-the-legacy-api-switch-and-each-refused-use-answers-as-the-spec-says.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 623db1c86..f6da0d5da 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -1255,6 +1255,19 @@ the spec's "Account management" names: `account_management_uri` and all six `org - **Logging.** Under `oauth`, `account.page.*` events with `user_id` only. Never a password, a cookie, a form token or the query (`sanitized_http_target` drops it, ADR-0786). +## The legacy API beside OAuth 2.0 (phase 9) + +- **Switch (ADR-0761, ADR-0801).** `server.oauth.legacy_api_enabled=false` stops the legacy API listing logins and + issuing users new sessions. `legacy_auth_refusal` (`LegacyAuthPolicy.cpp`) is the one decision, asked by `GET /login`, + `POST /login`, `POST /register`, both SSO redirects and `POST /login/get_token`: `GET /login`, a user's login, the SSO + redirects and `get_token` answer `404 M_UNRECOGNIZED`; `m.login.application_service` on `POST /login`, and an + application service's registration without `"inhibit_login": true`, answer `400 M_APPSERVICE_LOGIN_UNSUPPORTED`; a + user's registration answers `403 M_FORBIDDEN`, before User-Interactive Authentication. `m.get_login_token` reports + `enabled: false`. With the key true (the default) no answer changes. +- **What carries on.** Sessions already issued, `/refresh`, `/logout`, `/logout/all`, User-Interactive Authentication + and every authenticated endpoint; the username availability and registration-token validity checks, the email and + phone token requests, and password reset by email, none of which issues a session. + ## Next starting points 1. Preserve the reviewed libsodium boundary for random token generation and password hashing as auth flows expand. diff --git a/docs/matrix-v1.19-client-server-api.md b/docs/matrix-v1.19-client-server-api.md index 31a3f7ee5..65010e3ba 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -568,6 +568,7 @@ Room account data (`GET`/`PUT /user/{userId}/rooms/{roomId}/account_data/{type}` device IDs to the remote server and returns only those devices. - **Admin whois (CS8, ADR-0548).** `GET /v3/admin/whois/{userId}`: a server admin may look up any local user, any other caller only themselves. A non-admin asking about someone else gets `403 M_FORBIDDEN` before any lookup (so it cannot probe for accounts). For an admin: a malformed or non-local ID is `400 M_INVALID_PARAM`, an unknown or deactivated local user `404 M_NOT_FOUND`. The answer holds `user_id` and one entry per device, each with one session whose `connections` is empty: the server records no IP address, user agent or last-seen time, and whois does not start recording them. - **Login tokens (CS8, ADR-0548).** Off unless `security.login_token.enabled`; off, `POST /v1/login/get_token` is `404 M_UNRECOGNIZED`, `GET /login` offers no `m.login.token` flow and `GET /capabilities` carries `m.get_login_token: {"enabled": false}`. On, the flow is offered as `{"type":"m.login.token","get_login_token":true}`, the capability is `enabled: true`, and `get_token` runs UIA with `m.login.password` on every call (never a recent session): no auth is a `401` challenge, a wrong password `401 M_FORBIDDEN`. Success is `{"login_token", "expires_in_ms": 120000}`. The token is 256 random bits, kept in memory as a hash, spent by the first `POST /login` that names it (success or not). A user holds 4 live tokens and the server 1024 (`429 M_LIMIT_EXCEEDED` with `retry_after_ms`), and the per-user rate limit is 4 requests a minute. `POST /login` with a token creates a device as password login does and refuses a locked, suspended or deactivated account the same way. The SSO `loginToken` redeemed through the same `type` is unchanged. +- **Without the legacy API (P9, ADR-0801).** With `server.oauth.legacy_api_enabled=false`: `GET /login` `404 M_UNRECOGNIZED` (spec "Authentication API discovery"); `POST /login` for a user, both `/login/sso/redirect` routes and `POST /login/get_token` `404 M_UNRECOGNIZED` (the spec gives them no answer of their own); `m.login.application_service` on `POST /login` `400 M_APPSERVICE_LOGIN_UNSUPPORTED`; `POST /register` for a user `403 M_FORBIDDEN` before UIA, and for an application service served only with `"inhibit_login": true`, else `400 M_APPSERVICE_LOGIN_UNSUPPORTED` with nothing created. Sessions already issued, `/refresh`, `/logout` and UIA carry on. - `GET /capabilities` carries `m.account_moderation` (`lock`, `suspend`) for server admins and omits it for other users. - A joined room's `/sync` timeline no longer carries the unspecified `event_count`. diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index ef570a883..e61b4f06e 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1096,6 +1096,14 @@ quickly finding everything a given `AGENTS.md` file contributed. identity (CWE-306); a session issued per poll fills the user's UIA pool (CWE-770) (ADR-0796 to ADR-0799). Source: `src/homeserver/AGENTS.md`. +- **With `server.oauth.legacy_api_enabled=false` no legacy route issues a user a new session or lists the legacy + logins, and the decision is `legacy_auth_refusal` alone; an application service registers only with + `"inhibit_login": true`, judged before the user is created.** + Why: a route that tests the key itself is the one a later change forgets, leaving a password login that bypasses + the OAuth consent and device checks the operator chose (CWE-288); a refused registration that still created the + user leaves an account behind (ADR-0801). + Source: `src/homeserver/AGENTS.md`. + ## HTTP and network boundary - **Rate limiting is applied before any auth check.** Do not move it after auth. diff --git a/docs/user-manual.md b/docs/user-manual.md index 4004a0b19..9b97df08a 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -878,7 +878,7 @@ pass `/_merovingian/oauth2/` and `/_merovingian/account` through, as it does | Key | Default | When to change | |---|---|---| | `server.oauth.enabled` | `false` | Set `true` to serve the OAuth 2.0 API. `server.public_baseurl` must then be an `https` URL with a host and no query, fragment or userinfo (a path is allowed), and `server.sso.authorization_url` must be empty. | -| `server.oauth.legacy_api_enabled` | `true` | Set `false` to stop the legacy login and registration API issuing new sessions to users (ADR-0761). Refused unless `server.oauth.enabled=true`, so users always have a way to log in. Checked now, but not yet acted on: the OAuth login pages have landed, and the legacy API still issues sessions whatever this key says. | +| `server.oauth.legacy_api_enabled` | `true` | Set `false` to stop the legacy login and registration API issuing new sessions to users (ADR-0761, ADR-0801). Refused unless `server.oauth.enabled=true`, so users always have a way to log in. See [Turning the legacy API off](#turning-the-legacy-api-off). | | `server.oauth.device_grant_enabled` | `false` | Set `true` to offer the device authorization grant (RFC 8628): the metadata then lists the device code grant type and `device_authorization_endpoint`. Refused unless `server.oauth.enabled=true`. | | `server.oauth.hand_off_redirect_allowlist` | (empty) | Comma-separated places the hand-off from the legacy SSO redirect may send the browser: `https` origins (`https://app.example.com`, `https://app.example.com:8443`, nothing after the host or port) and bare private-use schemes (`io.element.app:`), in lower case. Never a URL prefix (ADR-0774). At most 32 entries, none twice. Refused unless `server.oauth.enabled=true`. Checked now, used once the hand-off lands. | @@ -888,6 +888,29 @@ follows the legacy registration settings (ADR-0762). Every `server.oauth.*` key needs a restart. +##### Turning the legacy API off + +With `server.oauth.legacy_api_enabled=false` users sign in and register only +through the OAuth 2.0 API (ADR-0801): + +| Request | Answer | +|---|---| +| `GET /_matrix/client/v3/login` | `404 M_UNRECOGNIZED` | +| `POST /_matrix/client/v3/login`, a user's login of any type | `404 M_UNRECOGNIZED` | +| `POST /_matrix/client/v3/login`, `m.login.application_service` | `400 M_APPSERVICE_LOGIN_UNSUPPORTED` | +| `POST /_matrix/client/v3/register`, a user | `403 M_FORBIDDEN` | +| `POST /_matrix/client/v3/register`, an application service without `"inhibit_login": true` | `400 M_APPSERVICE_LOGIN_UNSUPPORTED`, nothing created | +| `POST /_matrix/client/v3/register`, an application service with `"inhibit_login": true` | served as before | +| `GET /_matrix/client/v3/login/sso/redirect` and `/{idpId}` | `404 M_UNRECOGNIZED` | +| `POST /_matrix/client/v1/login/get_token` | `404 M_UNRECOGNIZED`; `m.get_login_token` reports `enabled: false` | + +Unchanged: every session already issued, with `/refresh`, `/logout`, +`/logout/all`, User-Interactive Authentication and every authenticated +endpoint; `GET /register/available`; the registration token validity check; +the email and phone token requests; and password reset by email. An +application service must send `"inhibit_login": true` when it registers a +user, and acts as its users with its `as_token`. + **`server.oidc.*` is refused.** Before 1.1.0 these keys made `auth_metadata` advertise an external authorisation server that Merovingian could not log anyone in through. A configuration that still sets any `server.oidc.*` key does diff --git a/include/merovingian/homeserver/LegacyAuthPolicy.hpp b/include/merovingian/homeserver/LegacyAuthPolicy.hpp new file mode 100644 index 000000000..4cdcde8c1 --- /dev/null +++ b/include/merovingian/homeserver/LegacyAuthPolicy.hpp @@ -0,0 +1,36 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/config/OAuthConfig.hpp" +#include "merovingian/homeserver/LegacyAuthRefusal.hpp" +#include "merovingian/homeserver/LegacyAuthUse.hpp" + +#include + +namespace merovingian::homeserver +{ + +// The one decision on whether the legacy authentication API serves `use` (plan P9, ADR-0761, ADR-0801). Every route +// that lists the legacy logins or issues a user a new session asks it, before it reads anything else from the request; +// never test `legacy_api_enabled` in a route. +// +// nullopt (served as before) while `oauth.legacy_api_enabled` is true, whatever `oauth.enabled` says. With it false: +// +// - appservice_login, appservice_registration_with_login: 400 `M_APPSERVICE_LOGIN_UNSUPPORTED` (spec `POST /login` +// `m.login.application_service`, and `POST /register`, both "MUST"); +// - user_registration: 403 `M_FORBIDDEN` (spec `POST /register` 403: "registration is generally not supported"); +// - login_flows, user_login, sso_redirect, login_token_mint: 404 `M_UNRECOGNIZED` (spec `GET /login` 404 and +// "Authentication API discovery"; the others have no answer of their own, so they answer as an absent endpoint). +// +// Sessions already issued, `/refresh`, `/logout`, User-Interactive Authentication and every other endpoint are not +// uses: they carry on (P9). +[[nodiscard]] auto legacy_auth_refusal(config::OAuthConfig const& oauth, LegacyAuthUse use) + -> std::optional; + +// Whether the legacy SSO redirect hands the browser to the built-in sign-in pages and back with a login token (plan +// P10, ADR-0802): both the OAuth 2.0 API and the legacy API on. `GET /login` then offers `m.login.sso` with +// `oauth_aware_preferred`. +[[nodiscard]] auto legacy_login_hand_off_enabled(config::OAuthConfig const& oauth) noexcept -> bool; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/LegacyAuthRefusal.hpp b/include/merovingian/homeserver/LegacyAuthRefusal.hpp new file mode 100644 index 000000000..6e85240d5 --- /dev/null +++ b/include/merovingian/homeserver/LegacyAuthRefusal.hpp @@ -0,0 +1,20 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::homeserver +{ + +// How a route answers a use of the legacy authentication API while `server.oauth.legacy_api_enabled` is false +// (`legacy_auth_refusal`, ADR-0801). Fixed text: every field names a literal. +struct LegacyAuthRefusal final +{ + std::uint16_t status{404U}; + std::string_view errcode{"M_UNRECOGNIZED"}; + std::string_view reason{"route not found"}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/LegacyAuthUse.hpp b/include/merovingian/homeserver/LegacyAuthUse.hpp new file mode 100644 index 000000000..21f5996a9 --- /dev/null +++ b/include/merovingian/homeserver/LegacyAuthUse.hpp @@ -0,0 +1,31 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::homeserver +{ + +// What a request asks of the legacy authentication API, for `legacy_auth_refusal` (ADR-0801). Each value is one way +// the legacy API lists its logins or issues a user a new session; nothing else is gated by +// `server.oauth.legacy_api_enabled`. +enum class LegacyAuthUse : std::uint8_t +{ + // `GET /login`: the login types. + login_flows, + // `POST /login` with any type but `m.login.application_service`. + user_login, + // `POST /login` with `m.login.application_service`. + appservice_login, + // `POST /register` for a user (no `m.login.application_service`). + user_registration, + // `POST /register` with `m.login.application_service` without `"inhibit_login": true`. + appservice_registration_with_login, + // `GET /login/sso/redirect` and `GET /login/sso/redirect/{idpId}`. + sso_redirect, + // `POST /login/get_token`, and the `m.get_login_token` capability. + login_token_mint, +}; + +} // namespace merovingian::homeserver diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index b4e782cfb..85df1e424 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -195,6 +195,12 @@ Rules (ADR-0796 to ADR-0798): session per request (ADR-0799); keep both when changing the stage. - Log `user_id` only (`account.page.*`); never a password, the cookie, a form token or the query. +The legacy API switch (`server.oauth.legacy_api_enabled`, ADR-0801) is decided by `legacy_auth_refusal` +(`LegacyAuthPolicy.cpp`) alone. `GET /login`, `POST /login`, `POST /register`, both SSO redirects and +`POST /login/get_token` (and its capability) ask it, through `legacy_auth_refused`, before they judge credentials or +create anything. A new route that lists the legacy logins or issues a user a session asks it too; never test the key +in a route. A session already issued, `/refresh`, `/logout` and UIA are not uses and are never gated. + `POST /_merovingian/oauth2/register` is `register_oauth_client` (`OAuthClientRegistration.cpp`), answered before the authentication gate, and also from the general body cap so an oversized body is an OAuth 400 (ADR-0781). Rules: diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index bfe1d51e1..339132238 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -94,6 +94,7 @@ #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/InvitePermission.hpp" #include "merovingian/homeserver/KeyServerCache.hpp" +#include "merovingian/homeserver/LegacyAuthPolicy.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/LocalHttpResponse.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" @@ -4486,6 +4487,27 @@ namespace return rt.homeserver.config.security().login_token.enabled; } + // Whether POST /login/get_token is served: the operator switch, and the legacy API that redeems what it mints + // (`legacy_auth_refusal`, ADR-0801). Also the `m.get_login_token` capability. + [[nodiscard]] auto login_token_minting_served(ClientServerRuntime const& rt) -> bool + { + return login_tokens_enabled(rt) && + !legacy_auth_refusal(rt.homeserver.config.server().oauth, LegacyAuthUse::login_token_mint).has_value(); + } + + // The answer to `use` of the legacy authentication API when `legacy_auth_refusal` refuses it, or nullopt to serve + // it (ADR-0801). + [[nodiscard]] auto legacy_auth_refused(LocalHttpRequest const& req, ClientServerRuntime const& rt, + LegacyAuthUse use) -> std::optional + { + auto const refusal = legacy_auth_refusal(rt.homeserver.config.server().oauth, use); + if (!refusal.has_value()) + { + return std::nullopt; + } + return dispatch_err(req, rt, refusal->status, refusal->errcode, refusal->reason); + } + // Hash of a login token as `LoginTokenStore` keeps it. The token is 256 random bits, so an unkeyed hash suffices. [[nodiscard]] auto login_token_hash(std::string_view token) -> std::optional { @@ -4556,7 +4578,7 @@ namespace [[nodiscard]] auto handle_get_login_token(ClientServerRuntime& rt, LocalHttpRequest const& req, std::string_view user_id) -> DispatchResult { - if (!login_tokens_enabled(rt)) + if (!login_token_minting_served(rt)) { return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); } @@ -15832,6 +15854,19 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return dispatch_err(req, rt, 401U, errcode, "m.login.application_service requires a valid appservice as_token"); } + auto const* inhibit_login_value = boolean_member(*registration_object, "inhibit_login"); + auto const inhibit_login = inhibit_login_value != nullptr && *inhibit_login_value; + // Spec (POST /register, v1.17): without the legacy API the endpoint still serves application services, + // which "MUST set the "inhibit_login": true parameter"; otherwise 400 M_APPSERVICE_LOGIN_UNSUPPORTED. + // Judged before the user is created, so a refusal creates nothing. + if (!inhibit_login) + { + if (auto refused = legacy_auth_refused(req, rt, LegacyAuthUse::appservice_registration_with_login); + refused.has_value()) + { + return std::move(*refused); + } + } auto const* username = string_member(*registration_object, "username"); if (username == nullptr) { @@ -15873,8 +15908,7 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp result.reason, result.retry_after_ms); } auto const full_user_id = result.value; - auto const* inhibit_login_value = boolean_member(*registration_object, "inhibit_login"); - if (inhibit_login_value != nullptr && *inhibit_login_value) + if (inhibit_login) { return dispatch_resp(req, rt, 200U, json_serialize(json_obj({json_member("user_id", json_str(full_user_id))}))); @@ -15902,6 +15936,12 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp json_member("device_id", json_str(reg_device_id)), }))); } + // With the legacy API off (ADR-0801) a user registers through the OAuth 2.0 API: spec (POST /register 403) + // "registration is generally not supported by the homeserver". Before UIA, so no session is issued. + if (auto refused = legacy_auth_refused(req, rt, LegacyAuthUse::user_registration); refused.has_value()) + { + return std::move(*refused); + } // Spec (POST /register, 400): "Homeservers MUST perform the relevant checks and return // these codes before performing User-Interactive Authentication" -- M_INVALID_USERNAME, // M_USER_IN_USE and M_EXCLUSIVE. The same checks run again after authentication below @@ -16050,6 +16090,11 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } if (req.method == "GET" && request_path == "/_matrix/client/v3/login") { + // Spec (GET /login 404): "the homeserver does not support the legacy authentication API" (ADR-0801). + if (auto refused = legacy_auth_refused(req, rt, LegacyAuthUse::login_flows); refused.has_value()) + { + return std::move(*refused); + } auto flows = canonicaljson::Array{}; flows.emplace_back(json_obj({json_member("type", json_str("m.login.password"))})); // Matrix v1.19 Application Service API §"Server admin style @@ -16110,6 +16155,10 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp // -- like GET /login above -- because it is itself unauthenticated. if (req.method == "GET" && request_path == "/_matrix/client/v3/login/sso/redirect") { + if (auto refused = legacy_auth_refused(req, rt, LegacyAuthUse::sso_redirect); refused.has_value()) + { + return std::move(*refused); + } auto const redirect_url = query_param_value(req.target, "redirectUrl"); auto const action = query_param_value(req.target, "action"); auto const result = sso_redirect_target(rt.homeserver, {}, redirect_url.value_or(std::string{}), @@ -16124,6 +16173,10 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } if (req.method == "GET" && starts_with(req.target, "/_matrix/client/v3/login/sso/redirect/")) { + if (auto refused = legacy_auth_refused(req, rt, LegacyAuthUse::sso_redirect); refused.has_value()) + { + return std::move(*refused); + } auto path_and_idp = req.target.substr(std::string_view{"/_matrix/client/v3/login/sso/redirect/"}.size()); if (auto const query = path_and_idp.find('?'); query != std::string_view::npos) { @@ -16144,6 +16197,23 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } if (req.method == "POST" && request_path == "/_matrix/client/v3/login") { + // ADR-0801: with the legacy API off no user logs in here. Spec (m.login.application_service, v1.17): "If this + // login type is used and the server doesn't support logging in via the Legacy authentication API, it MUST + // return a 400 HTTP status code with an M_APPSERVICE_LOGIN_UNSUPPORTED error code." Every other type has no + // answer of its own and is answered as an absent endpoint. Judged on the body's `type` alone, before the body + // is parsed as a login or any credential is checked; the body is read for it only when a login is refused. + if (legacy_auth_refusal(rt.homeserver.config.server().oauth, LegacyAuthUse::user_login).has_value()) + { + auto const login_object = parsed_json_object(req.body); + auto const* login_type = login_object.has_value() ? string_member(*login_object, "type") : nullptr; + auto const use = login_type != nullptr && *login_type == "m.login.application_service" + ? LegacyAuthUse::appservice_login + : LegacyAuthUse::user_login; + if (auto refused = legacy_auth_refused(req, rt, use); refused.has_value()) + { + return std::move(*refused); + } + } auto body = parse_login_body(req.body, rt.homeserver.config.server().server_name); if (!body.has_value()) { @@ -16839,7 +16909,8 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp // authentication ("implemented, but the incorrect HTTP method is used"). // CS8 (ADR-0548): with the feature off this endpoint is not served at all, so it is 404 whatever the method or // credentials, as before it was implemented. - if (request_path == get_login_token_path && !login_tokens_enabled(rt)) + // With the legacy API off (ADR-0801) likewise. + if (request_path == get_login_token_path && !login_token_minting_served(rt)) { return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); } @@ -18290,7 +18361,8 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp json_member("m.change_password", json_obj({json_member("enabled", json_bool(true))})), json_member("m.3pid_changes", json_obj({json_member("enabled", json_bool(true))})), // Spec (m.get_login_token, v1.7): whether the user may use POST /login/get_token. - json_member("m.get_login_token", json_obj({json_member("enabled", json_bool(login_tokens_enabled(rt)))})), + json_member("m.get_login_token", + json_obj({json_member("enabled", json_bool(login_token_minting_served(rt)))})), // Spec (m.profile_fields, v1.16): every field is the user's to set; this server has // no allowed or disallowed list. json_member("m.profile_fields", json_obj({json_member("enabled", json_bool(true))})), diff --git a/src/homeserver/LegacyAuthPolicy.cpp b/src/homeserver/LegacyAuthPolicy.cpp new file mode 100644 index 000000000..76212c866 --- /dev/null +++ b/src/homeserver/LegacyAuthPolicy.cpp @@ -0,0 +1,42 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/LegacyAuthPolicy.hpp" + +namespace merovingian::homeserver +{ + +auto legacy_auth_refusal(config::OAuthConfig const& oauth, LegacyAuthUse use) -> std::optional +{ + if (oauth.legacy_api_enabled) + { + return std::nullopt; + } + switch (use) + { + case LegacyAuthUse::appservice_login: + return LegacyAuthRefusal{400U, "M_APPSERVICE_LOGIN_UNSUPPORTED", + "this server does not log in through the legacy authentication API"}; + case LegacyAuthUse::appservice_registration_with_login: + return LegacyAuthRefusal{400U, "M_APPSERVICE_LOGIN_UNSUPPORTED", + "this server does not log in through the legacy authentication API; set " + "inhibit_login to true"}; + case LegacyAuthUse::user_registration: + return LegacyAuthRefusal{403U, "M_FORBIDDEN", + "registration through the legacy authentication API is not supported; register " + "through the OAuth 2.0 API"}; + case LegacyAuthUse::login_flows: + case LegacyAuthUse::user_login: + case LegacyAuthUse::sso_redirect: + case LegacyAuthUse::login_token_mint: + break; + } + return LegacyAuthRefusal{}; +} + +auto legacy_login_hand_off_enabled(config::OAuthConfig const& oauth) noexcept -> bool +{ + return oauth.enabled && oauth.legacy_api_enabled; +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/meson.build b/src/homeserver/meson.build index 48c1ef4c6..c7b7765d8 100644 --- a/src/homeserver/meson.build +++ b/src/homeserver/meson.build @@ -34,6 +34,7 @@ homeserver_sources = files( 'StreamedBody.cpp', 'MediaUploadNotifier.cpp', 'AccountPage.cpp', + 'LegacyAuthPolicy.cpp', 'OAuthAuthorization.cpp', 'OAuthClientCredentials.cpp', 'OAuthClientRegistration.cpp', diff --git a/tests/conformance/AGENTS.md b/tests/conformance/AGENTS.md index 82a036e78..195f66a20 100644 --- a/tests/conformance/AGENTS.md +++ b/tests/conformance/AGENTS.md @@ -65,6 +65,7 @@ Every test in this directory directly encodes a **MUST** or **SHOULD** from the | `test_oauth_authorization_conformance.cpp` | [CS API § Authorisation code grant](../../docs/matrix-v1.19-spec/client-server-api.md#authorisation-code-grant) · [§ Scope](../../docs/matrix-v1.19-spec/client-server-api.md#scope) · [§ User registration](../../docs/matrix-v1.19-spec/client-server-api.md#user-registration) (`/_merovingian/oauth2/authorize`: an unregistered redirect URI is never redirected to; `state` on success and error; the response mode places the answer; S256 required; the API and exactly one device scope; `prompt=create` shows registration only when accepted) | | `test_oauth_account_management_conformance.cpp` | [CS API § Account management](../../docs/matrix-v1.19-spec/client-server-api.md#account-management-url-discovery) · [§ OAuth authentication](../../docs/matrix-v1.19-spec/client-server-api.md#oauth-authentication) (`account_management_uri` and the six actions; `action` and `device_id` on `/_merovingian/account`, the device ignored by the actions that take none; a replacing cross-signing upload from an OAuth session is a 401 with the `m.oauth` flow and the `org.matrix.cross_signing_reset` URL, completed by the `session` alone after the approval) | | `test_oauth_token_conformance.cpp` | [CS API § Refresh token grant](../../docs/matrix-v1.19-spec/client-server-api.md#refresh-token-grant) · [§ Token revocation](../../docs/matrix-v1.19-spec/client-server-api.md#token-revocation) (`/_merovingian/oauth2/token` and `/revoke`: an access token always expires; a lost refresh answer can be retried and the old token is refused once the new one is used; revocation ends both tokens whatever the `client_id` and answers 200 for an unknown token) | +| `test_oauth_legacy_api_conformance.cpp` | [CS API § Authentication API discovery](../../docs/matrix-v1.19-spec/client-server-api.md#authentication-api-discovery) · [`GET /login`](../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv3login) · [`POST /login`](../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3login) · [`POST /register`](../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3register) (without the legacy API: `GET /login` 404 `M_UNRECOGNIZED`, `m.login.application_service` and an appservice registration without `inhibit_login` 400 `M_APPSERVICE_LOGIN_UNSUPPORTED`, an appservice registration with it served, a user's registration 403) | | `test_oauth_client_registration_conformance.cpp` | [CS API § Client registration](../../docs/matrix-v1.19-spec/client-server-api.md#client-registration) · [§ Client metadata](../../docs/matrix-v1.19-spec/client-server-api.md#client-metadata) · [§ Redirect URI validation](../../docs/matrix-v1.19-spec/client-server-api.md#redirect-uri-validation) · [§ Dynamic client registration flow](../../docs/matrix-v1.19-spec/client-server-api.md#dynamic-client-registration-flow) (`POST /_merovingian/oauth2/register`: 201 with `client_id` and the registered metadata, web and native, `none`, unknown values ignored, the spec's redirect URI examples, a client with a session never deleted) | | `test_pdu_format_conformance.cpp` | [SS API § PDUs](../../docs/matrix-v1.19-spec/server-server-api.md#pdus) | | `test_pdu_ingestion_conformance.cpp` | [SS API § Checks performed on receipt of a PDU](../../docs/matrix-v1.19-spec/server-server-api.md#checks-performed-on-receipt-of-a-pdu) · [Room v12 § State resolution](../../docs/matrix-v1.19-spec/rooms/v12.md) (auth_events selection: m.room.create MUST NOT be selected) · [§ Calculating the reference hash](../../docs/matrix-v1.19-spec/server-server-api.md#calculating-the-reference-hash-for-an-event) (a received PDU is stored without its `unsigned`, under an unchanged event ID) | diff --git a/tests/conformance/test_oauth_legacy_api_conformance.cpp b/tests/conformance/test_oauth_legacy_api_conformance.cpp new file mode 100644 index 000000000..021920575 --- /dev/null +++ b/tests/conformance/test_oauth_legacy_api_conformance.cpp @@ -0,0 +1,188 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// +-------------------------------------------------------------------------+ +// | LEGACY AUTHENTICATION API BESIDE OAUTH 2.0 CONFORMANCE | +// | | +// | Spec: Matrix Client-Server API v1.19 — "Authentication API discovery", | +// | "GET /login", "POST /login" (m.login.application_service), | +// | "POST /register", "OAuth 2.0 aware clients" | +// | URL: ../../docs/matrix-v1.19-spec/client-server-api.md | +// +-------------------------------------------------------------------------+ +// +// What a server without the legacy authentication API answers (plan P9, ADR-0801). + +#include "../support/AppserviceTestConfig.hpp" +#include "../support/JsonTestSupport.hpp" +#include "../support/TestAppservice.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include + +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace hs = merovingian::homeserver; + +[[nodiscard]] auto bridge() -> TestAppservice +{ + auto appservice = TestAppservice{}; + appservice.id = "bridge"; + appservice.users_regex = "@_bridge_.*"; + return appservice; +} + +[[nodiscard]] auto start_without_legacy_api() -> hs::ClientServerStartResult +{ + auto config = appservice_test_config({bridge()}); + config.server().public_baseurl = "https://matrix.example.org"; + config.server().oauth.enabled = true; + config.server().oauth.legacy_api_enabled = false; + auto started = hs::start_client_server(config); + REQUIRE(started.started); + started.runtime.rate_limit_engine.reset(); + return started; +} + +[[nodiscard]] auto send(hs::ClientServerRuntime& rt, std::string method, std::string target, std::string token, + std::string body = {}) -> hs::LocalHttpResponse +{ + return hs::handle_client_server_request(rt, + {std::move(method), std::move(target), std::move(token), std::move(body)}, + /*can_wait=*/false) + .response; +} + +[[nodiscard]] auto errcode(hs::LocalHttpResponse const& response) -> std::string +{ + auto const body = parse_object(response.body); + auto const* value = string_member(body, "errcode"); + return value == nullptr ? std::string{} : *value; +} + +} // namespace + +// Spec: CS API v1.19 "GET /login", 404: "With M_UNRECOGNIZED: the homeserver does not support the legacy authentication +// API." "Authentication API discovery": "the server SHOULD respond with 404 and an M_UNRECOGNIZED error code if the +// corresponding API is not supported." +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv3login +SCENARIO("A server without the legacy API answers GET /login with 404 M_UNRECOGNIZED", + "[oauth][legacy-api][conformance]") +{ + GIVEN("a server with the legacy authentication API off") + { + auto started = start_without_legacy_api(); + + WHEN("GET /login is read") + { + auto const response = send(started.runtime, "GET", "/_matrix/client/v3/login", {}); + + THEN("it is 404 M_UNRECOGNIZED") + { + REQUIRE(response.status == 404U); + REQUIRE(errcode(response) == "M_UNRECOGNIZED"); + } + } + } +} + +// Spec: CS API v1.19 "Appservice Login": "If this login type is used and the server doesn't support logging in via the +// Legacy authentication API, it MUST return a 400 HTTP status code with an M_APPSERVICE_LOGIN_UNSUPPORTED error code." +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3login +SCENARIO("A server without the legacy API refuses m.login.application_service with M_APPSERVICE_LOGIN_UNSUPPORTED", + "[oauth][legacy-api][conformance][appservice]") +{ + GIVEN("a server with the legacy authentication API off and a registered appservice") + { + auto started = start_without_legacy_api(); + + WHEN("the appservice logs in one of its users") + { + auto const response = + send(started.runtime, "POST", "/_matrix/client/v3/login", bridge().as_token(), + R"({"type":"m.login.application_service","identifier":{"type":"m.id.user","user":"_bridge_a"}})"); + + THEN("it is 400 M_APPSERVICE_LOGIN_UNSUPPORTED") + { + REQUIRE(response.status == 400U); + REQUIRE(errcode(response) == "M_APPSERVICE_LOGIN_UNSUPPORTED"); + } + } + } +} + +// Spec: CS API v1.19 "POST /register": "Even if the server doesn't support the Legacy authentication API, it MUST +// support this endpoint for application services to be able to create users. In that case application services MUST +// set the "inhibit_login": true parameter as they cannot use it to log in as users. If the inhibit_login parameter is +// not set to true, the server MUST return a 400 HTTP status code with an M_APPSERVICE_LOGIN_UNSUPPORTED error code." +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3register +SCENARIO("A server without the legacy API still registers appservice users that set inhibit_login", + "[oauth][legacy-api][conformance][appservice]") +{ + GIVEN("a server with the legacy authentication API off and a registered appservice") + { + auto started = start_without_legacy_api(); + + WHEN("the appservice registers a user without inhibit_login") + { + auto const response = send(started.runtime, "POST", "/_matrix/client/v3/register", bridge().as_token(), + R"({"type":"m.login.application_service","username":"_bridge_a"})"); + + THEN("it is 400 M_APPSERVICE_LOGIN_UNSUPPORTED") + { + REQUIRE(response.status == 400U); + REQUIRE(errcode(response) == "M_APPSERVICE_LOGIN_UNSUPPORTED"); + } + } + + WHEN("the appservice registers a user with inhibit_login true") + { + auto const response = + send(started.runtime, "POST", "/_matrix/client/v3/register", bridge().as_token(), + R"({"type":"m.login.application_service","username":"_bridge_a","inhibit_login":true})"); + + THEN("the user is registered") + { + REQUIRE(response.status == 200U); + auto const body = parse_object(response.body); + auto const* user_id = string_member(body, "user_id"); + REQUIRE(user_id != nullptr); + REQUIRE(*user_id == "@_bridge_a:example.org"); + REQUIRE(string_member(body, "access_token") == nullptr); + } + } + } +} + +// Spec: CS API v1.19 "POST /register", 403: "The homeserver does not permit registering the account. This response can +// be used to identify ... that registration is generally not supported by the homeserver." "Account registration": +// "With the OAuth 2.0 API, a client can't register a new account directly." +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3register +SCENARIO("A server without the legacy API refuses a user's registration with 403", "[oauth][legacy-api][conformance]") +{ + GIVEN("a server with the legacy authentication API off") + { + auto started = start_without_legacy_api(); + + WHEN("a client registers a user with no auth") + { + auto const response = send(started.runtime, "POST", "/_matrix/client/v3/register", {}, + R"({"username":"carol","password":"CarolPass99!x"})"); + + THEN("it is 403 M_FORBIDDEN, not a User-Interactive Authentication challenge") + { + REQUIRE(response.status == 403U); + REQUIRE(errcode(response) == "M_FORBIDDEN"); + } + } + } +} diff --git a/tests/integration/test_oauth_legacy_api_flow.cpp b/tests/integration/test_oauth_legacy_api_flow.cpp new file mode 100644 index 000000000..4469b3350 --- /dev/null +++ b/tests/integration/test_oauth_legacy_api_flow.cpp @@ -0,0 +1,344 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// `server.oauth.legacy_api_enabled=false` through the client-server dispatcher (plan P9, ADR-0761, ADR-0801): no legacy +// endpoint lists the logins or issues a user a new session, application services still register with +// `inhibit_login`, and a session issued before carries on. With the key true nothing changes; every other test in the +// suite runs with it true. + +#include "../support/AppserviceTestConfig.hpp" +#include "../support/JsonTestSupport.hpp" +#include "../support/RegistrationToken.hpp" +#include "../support/TestAppservice.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/homeserver/LocalUser.hpp" + +#include + +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace hs = merovingian::homeserver; + +constexpr auto alice_id = std::string_view{"@alice:example.org"}; +constexpr auto alice_password = std::string_view{"AlicePass99!x"}; + +[[nodiscard]] auto bridge() -> TestAppservice +{ + auto appservice = TestAppservice{}; + appservice.id = "bridge"; + appservice.users_regex = "@_bridge_.*"; + return appservice; +} + +// The OAuth 2.0 API on, the legacy API on or off, login tokens on (so get_token would be served), one appservice. +[[nodiscard]] auto legacy_config(bool legacy_api_enabled) -> merovingian::config::Config +{ + auto config = appservice_test_config({bridge()}); + config.server().public_baseurl = "https://matrix.example.org"; + config.server().oauth.enabled = true; + config.server().oauth.legacy_api_enabled = legacy_api_enabled; + config.security().login_token.enabled = true; + return config; +} + +[[nodiscard]] auto start(bool legacy_api_enabled) -> hs::ClientServerStartResult +{ + auto started = hs::start_client_server(legacy_config(legacy_api_enabled)); + REQUIRE(started.started); + // Every request comes from one address; the built-in limits are not what this file tests. + started.runtime.rate_limit_engine.reset(); + REQUIRE( + hs::register_local_user(started.runtime.homeserver, "alice", alice_password, std::string{registration_token}) + .ok); + return started; +} + +[[nodiscard]] auto send(hs::ClientServerRuntime& rt, std::string method, std::string target, std::string token, + std::string body = {}) -> hs::LocalHttpResponse +{ + return hs::handle_client_server_request(rt, + {std::move(method), std::move(target), std::move(token), std::move(body)}, + /*can_wait=*/false) + .response; +} + +[[nodiscard]] auto member(hs::LocalHttpResponse const& response, std::string_view name) -> std::string +{ + auto const body = parse_object(response.body); + auto const* value = string_member(body, name); + return value == nullptr ? std::string{} : *value; +} + +[[nodiscard]] auto user_exists(hs::ClientServerRuntime const& rt, std::string_view user_id) -> bool +{ + return std::ranges::any_of(rt.homeserver.database.users, [user_id](hs::LocalUser const& user) { + return user.user_id == user_id; + }); +} + +[[nodiscard]] auto password_login_body(std::string_view device_id) -> std::string +{ + return R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":"alice"},"password":")" + + std::string{alice_password} + R"(","device_id":")" + std::string{device_id} + R"("})"; +} + +// A legacy session alice holds from before the switch: the access token and its refresh token. +struct LegacySession final +{ + std::string access_token; + std::string refresh_token; +}; + +[[nodiscard]] auto legacy_session(hs::ClientServerRuntime& rt, std::string_view device_id) -> LegacySession +{ + auto const login = hs::login_local_user(rt.homeserver, alice_id, alice_password, device_id, true, "127.0.0.1"); + REQUIRE(login.ok); + auto const refresh = hs::issue_refresh_token_for_session(rt.homeserver, alice_id, device_id); + REQUIRE(refresh.ok); + return {login.value, refresh.value}; +} + +} // namespace + +SCENARIO("With the legacy API off no legacy endpoint lists the logins or issues a user a session", + "[oauth][legacy-api][client-server]") +{ + GIVEN("a server with the OAuth 2.0 API on, the legacy API off and login tokens on") + { + auto started = start(false); + auto& rt = started.runtime; + + WHEN("GET /login is read") + { + auto const response = send(rt, "GET", "/_matrix/client/v3/login", {}); + + THEN("it is 404 M_UNRECOGNIZED") + { + REQUIRE(response.status == 404U); + CHECK(member(response, "errcode") == "M_UNRECOGNIZED"); + } + } + + WHEN("alice logs in with her right password, or with a login token") + { + auto const password = send(rt, "POST", "/_matrix/client/v3/login", {}, password_login_body("NEWDEV")); + auto const token = send(rt, "POST", "/_matrix/client/v3/login", {}, + R"({"type":"m.login.token","token":"0123456789abcdef"})"); + + THEN("each is 404 M_UNRECOGNIZED and no device is created") + { + REQUIRE(password.status == 404U); + CHECK(member(password, "errcode") == "M_UNRECOGNIZED"); + REQUIRE(token.status == 404U); + CHECK(member(token, "errcode") == "M_UNRECOGNIZED"); + CHECK_FALSE(merovingian::database::has_user_device(rt.homeserver.database.persistent_store, alice_id, + "NEWDEV")); + } + } + + WHEN("a user registers with a complete registration-token stage") + { + auto const response = send( + rt, "POST", "/_matrix/client/v3/register", {}, + R"({"username":"carol","password":"CarolPass99!x","auth":{"type":"m.login.registration_token","token":")" + + std::string{registration_token} + R"("}})"); + + THEN("it is 403 M_FORBIDDEN and no account is created") + { + REQUIRE(response.status == 403U); + CHECK(member(response, "errcode") == "M_FORBIDDEN"); + CHECK_FALSE(user_exists(rt, "@carol:example.org")); + } + } + + WHEN("the appservice logs in one of its users") + { + auto const response = send( + rt, "POST", "/_matrix/client/v3/login", bridge().as_token(), + R"({"type":"m.login.application_service","identifier":{"type":"m.id.user","user":"_bridge_ann"}})"); + + THEN("it is 400 M_APPSERVICE_LOGIN_UNSUPPORTED") + { + REQUIRE(response.status == 400U); + CHECK(member(response, "errcode") == "M_APPSERVICE_LOGIN_UNSUPPORTED"); + } + } + + WHEN("the appservice registers a user without inhibit_login, and with inhibit_login false") + { + auto const absent = send(rt, "POST", "/_matrix/client/v3/register", bridge().as_token(), + R"({"type":"m.login.application_service","username":"_bridge_ann"})"); + auto const negative = + send(rt, "POST", "/_matrix/client/v3/register", bridge().as_token(), + R"({"type":"m.login.application_service","username":"_bridge_ann","inhibit_login":false})"); + + THEN("each is 400 M_APPSERVICE_LOGIN_UNSUPPORTED and the user is not created") + { + REQUIRE(absent.status == 400U); + CHECK(member(absent, "errcode") == "M_APPSERVICE_LOGIN_UNSUPPORTED"); + REQUIRE(negative.status == 400U); + CHECK(member(negative, "errcode") == "M_APPSERVICE_LOGIN_UNSUPPORTED"); + CHECK_FALSE(user_exists(rt, "@_bridge_ann:example.org")); + } + } + + WHEN("the appservice registers a user with inhibit_login true") + { + auto const response = + send(rt, "POST", "/_matrix/client/v3/register", bridge().as_token(), + R"({"type":"m.login.application_service","username":"_bridge_ann","inhibit_login":true})"); + + THEN("the user is created and no access token is returned") + { + REQUIRE(response.status == 200U); + CHECK(member(response, "user_id") == "@_bridge_ann:example.org"); + CHECK(member(response, "access_token").empty()); + CHECK(user_exists(rt, "@_bridge_ann:example.org")); + } + } + + WHEN("a browser follows either SSO redirect endpoint") + { + auto const plain = send( + rt, "GET", "/_matrix/client/v3/login/sso/redirect?redirectUrl=https%3A%2F%2Fapp.example.com%2F", {}); + auto const with_idp = + send(rt, "GET", + "/_matrix/client/v3/login/sso/redirect/oidc?redirectUrl=https%3A%2F%2Fapp.example.com%2F", {}); + + THEN("each is 404 M_UNRECOGNIZED") + { + REQUIRE(plain.status == 404U); + CHECK(member(plain, "errcode") == "M_UNRECOGNIZED"); + REQUIRE(with_idp.status == 404U); + CHECK(member(with_idp, "errcode") == "M_UNRECOGNIZED"); + } + } + + WHEN("a signed-in user asks for a login token and reads the capabilities") + { + auto const session = legacy_session(rt, "LEGACYDEV"); + auto const get_token = send(rt, "POST", "/_matrix/client/v1/login/get_token", session.access_token, "{}"); + auto const capabilities = send(rt, "GET", "/_matrix/client/v3/capabilities", session.access_token); + + THEN("get_token is 404 M_UNRECOGNIZED and the capability says it is not enabled") + { + REQUIRE(get_token.status == 404U); + CHECK(member(get_token, "errcode") == "M_UNRECOGNIZED"); + REQUIRE(capabilities.status == 200U); + CHECK(capabilities.body.find(R"("m.get_login_token":{"enabled":false})") != std::string::npos); + } + } + + WHEN("the endpoints the switch leaves alone are called") + { + auto const available = send(rt, "GET", "/_matrix/client/v3/register/available?username=dave", {}); + + THEN("they answer as before") + { + REQUIRE(available.status == 200U); + } + } + } +} + +SCENARIO("With the legacy API off a session issued before carries on", "[oauth][legacy-api][client-server]") +{ + GIVEN("a server with the legacy API off and two legacy sessions of alice") + { + auto started = start(false); + auto& rt = started.runtime; + auto const first = legacy_session(rt, "LEGACYONE"); + auto const second = legacy_session(rt, "LEGACYTWO"); + + WHEN("the first session calls an authenticated endpoint") + { + auto const whoami = send(rt, "GET", "/_matrix/client/v3/account/whoami", first.access_token); + + THEN("it is served") + { + REQUIRE(whoami.status == 200U); + CHECK(member(whoami, "user_id") == alice_id); + } + } + + WHEN("the first session refreshes its token") + { + auto const refreshed = send(rt, "POST", "/_matrix/client/v3/refresh", {}, + R"({"refresh_token":")" + first.refresh_token + R"("})"); + auto const new_token = member(refreshed, "access_token"); + + THEN("a new access token is issued and works") + { + REQUIRE(refreshed.status == 200U); + REQUIRE_FALSE(new_token.empty()); + CHECK(send(rt, "GET", "/_matrix/client/v3/account/whoami", new_token).status == 200U); + } + } + + WHEN("the first session deletes the second device with the password stage") + { + auto const deleted = send( + rt, "DELETE", "/_matrix/client/v3/devices/LEGACYTWO", first.access_token, + R"({"auth":{"type":"m.login.password","identifier":{"type":"m.id.user","user":"alice"},"password":")" + + std::string{alice_password} + R"("}})"); + + THEN("User-Interactive Authentication completes and the second session ends") + { + REQUIRE(deleted.status == 200U); + CHECK(send(rt, "GET", "/_matrix/client/v3/account/whoami", second.access_token).status == 401U); + } + } + + WHEN("the first session logs out, and the second logs out everywhere") + { + auto const logout = send(rt, "POST", "/_matrix/client/v3/logout", first.access_token, "{}"); + auto const logout_all = send(rt, "POST", "/_matrix/client/v3/logout/all", second.access_token, "{}"); + + THEN("both are served and both tokens stop working") + { + REQUIRE(logout.status == 200U); + REQUIRE(logout_all.status == 200U); + CHECK(send(rt, "GET", "/_matrix/client/v3/account/whoami", first.access_token).status == 401U); + CHECK(send(rt, "GET", "/_matrix/client/v3/account/whoami", second.access_token).status == 401U); + } + } + } +} + +SCENARIO("With both APIs on an appservice registration without inhibit_login still logs in", + "[oauth][legacy-api][client-server][appservice]") +{ + GIVEN("a server with the OAuth 2.0 API and the legacy API on") + { + auto started = start(true); + auto& rt = started.runtime; + + WHEN("the appservice registers a user without inhibit_login") + { + auto const response = send(rt, "POST", "/_matrix/client/v3/register", bridge().as_token(), + R"({"type":"m.login.application_service","username":"_bridge_bob"})"); + + THEN("the user is created and an access token is returned, as before") + { + REQUIRE(response.status == 200U); + CHECK(member(response, "user_id") == "@_bridge_bob:example.org"); + CHECK_FALSE(member(response, "access_token").empty()); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index e43868dce..b41ad56b0 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -443,6 +443,7 @@ shell = find_program('sh') 'unit/test_core_request_cookies.cpp', 'unit/test_oauth_client_metadata.cpp', 'unit/test_oauth_hand_off_allowlist.cpp', + 'unit/test_legacy_auth_policy.cpp', 'unit/test_oauth_authorization_code_store.cpp', 'unit/test_oauth_authorization_pages.cpp', 'unit/test_oauth_authorization_redirect.cpp', @@ -663,6 +664,7 @@ shell = find_program('sh') 'conformance/test_oauth_authorization_conformance.cpp', 'conformance/test_oauth_client_registration_conformance.cpp', 'conformance/test_oauth_token_conformance.cpp', + 'conformance/test_oauth_legacy_api_conformance.cpp', 'conformance/test_open_registration_conformance.cpp', 'conformance/test_account_lifecycle_conformance.cpp', 'conformance/test_device_lifecycle_conformance.cpp', @@ -879,6 +881,7 @@ shell = find_program('sh') 'integration/test_oauth_password_login_flow.cpp', 'integration/test_oauth_token_flow.cpp', 'integration/test_oauth_account_pages_flow.cpp', + 'integration/test_oauth_legacy_api_flow.cpp', 'integration/test_observability_flow.cpp', 'integration/test_operator_admin_flow.cpp', 'integration/test_admin_masquerade_refusal_flow.cpp', diff --git a/tests/unit/test_legacy_auth_policy.cpp b/tests/unit/test_legacy_auth_policy.cpp new file mode 100644 index 000000000..8b95415b3 --- /dev/null +++ b/tests/unit/test_legacy_auth_policy.cpp @@ -0,0 +1,118 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// `legacy_auth_refusal`, the one decision on whether the legacy authentication API serves a use (plan P9, ADR-0801), +// and `legacy_login_hand_off_enabled` (plan P10, ADR-0802). + +#include "merovingian/config/OAuthConfig.hpp" +#include "merovingian/homeserver/LegacyAuthPolicy.hpp" +#include "merovingian/homeserver/LegacyAuthUse.hpp" + +#include +#include + +#include + +namespace +{ + +using merovingian::homeserver::LegacyAuthUse; + +[[nodiscard]] auto oauth_config(bool enabled, bool legacy) -> merovingian::config::OAuthConfig +{ + auto oauth = merovingian::config::OAuthConfig{}; + oauth.enabled = enabled; + oauth.legacy_api_enabled = legacy; + return oauth; +} + +} // namespace + +SCENARIO("The legacy API serves every use while legacy_api_enabled is true", "[oauth][legacy-api]") +{ + GIVEN("a configuration with the legacy API on, the OAuth 2.0 API on or off") + { + auto const oauth = oauth_config(GENERATE(false, true), true); + auto const use = + GENERATE(LegacyAuthUse::login_flows, LegacyAuthUse::user_login, LegacyAuthUse::appservice_login, + LegacyAuthUse::user_registration, LegacyAuthUse::appservice_registration_with_login, + LegacyAuthUse::sso_redirect, LegacyAuthUse::login_token_mint); + + WHEN("a use is judged") + { + auto const refusal = merovingian::homeserver::legacy_auth_refusal(oauth, use); + + THEN("nothing is refused") + { + REQUIRE_FALSE(refusal.has_value()); + } + } + } +} + +SCENARIO("With legacy_api_enabled false each use gets the spec's answer", "[oauth][legacy-api]") +{ + GIVEN("a configuration with the OAuth 2.0 API on and the legacy API off") + { + auto const oauth = oauth_config(true, false); + + WHEN("an application service logs in, or registers without inhibit_login") + { + auto const use = + GENERATE(LegacyAuthUse::appservice_login, LegacyAuthUse::appservice_registration_with_login); + auto const refusal = merovingian::homeserver::legacy_auth_refusal(oauth, use); + + THEN("it is 400 M_APPSERVICE_LOGIN_UNSUPPORTED") + { + REQUIRE(refusal.has_value()); + CHECK(refusal->status == 400U); + CHECK(refusal->errcode == std::string_view{"M_APPSERVICE_LOGIN_UNSUPPORTED"}); + } + } + + WHEN("a user registers") + { + auto const refusal = merovingian::homeserver::legacy_auth_refusal(oauth, LegacyAuthUse::user_registration); + + THEN("it is 403 M_FORBIDDEN") + { + REQUIRE(refusal.has_value()); + CHECK(refusal->status == 403U); + CHECK(refusal->errcode == std::string_view{"M_FORBIDDEN"}); + } + } + + WHEN("the login types are read, a user logs in, the SSO redirect is followed or a login token is minted") + { + auto const use = GENERATE(LegacyAuthUse::login_flows, LegacyAuthUse::user_login, + LegacyAuthUse::sso_redirect, LegacyAuthUse::login_token_mint); + auto const refusal = merovingian::homeserver::legacy_auth_refusal(oauth, use); + + THEN("it is 404 M_UNRECOGNIZED") + { + REQUIRE(refusal.has_value()); + CHECK(refusal->status == 404U); + CHECK(refusal->errcode == std::string_view{"M_UNRECOGNIZED"}); + } + } + } +} + +SCENARIO("The legacy login hand-off runs only with both APIs on", "[oauth][legacy-api][hand-off]") +{ + GIVEN("each combination of the two switches") + { + auto const enabled = GENERATE(false, true); + auto const legacy = GENERATE(false, true); + + WHEN("the hand-off is asked about") + { + auto const hand_off = merovingian::homeserver::legacy_login_hand_off_enabled(oauth_config(enabled, legacy)); + + THEN("it is on only when both are on") + { + REQUIRE(hand_off == (enabled && legacy)); + } + } + } +} From 09dcc3c3a536c1f00fc7a0d2d2ecefc74d20dabf Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 09:17:55 +0000 Subject: [PATCH 20/42] Hand legacy SSO logins off to the OAuth 2.0 pages with a confirmation and a login token (ADR-0802) With server.oauth.enabled and the legacy API both on, GET /login adds m.login.sso with oauth_aware_preferred: true (and m.login.token when get_token did not), and both SSO redirects start the /authorize sign-in or registration pages through a new login_token_hand_off kind of pending authorisation. redirectUrl must be https, loopback http or a private-use scheme, and match the allowlist when one is set; a refused one is a 400 page with no redirect. After the password a confirmation page names the account and the destination; continue mints a 30-second single-use token into LoginTokenStore and answers 303 with every older loginToken removed; cancel redirects nowhere. Co-Authored-By: Claude Opus 5.5 --- .../references/module-invariants.md | 2 + CHANGELOG.md | 2 + config/merovingian.conf.bsd.example | 4 +- config/merovingian.conf.example | 4 +- ...firms-and-mints-a-30-second-login-token.md | 83 ++++ docs/adr/index.md | 1 + docs/auth-identity.md | 12 + docs/http-transport.md | 5 + docs/matrix-v1.19-client-server-api.md | 1 + docs/observability-audit.md | 9 +- docs/security-coding-rules.md | 6 + docs/todos/capability-gaps.md | 4 +- docs/todos/oauth-2-0-api.md | 5 +- docs/user-manual.md | 26 +- .../homeserver/LoginTokenStore.hpp | 3 + .../homeserver/OAuthAuthorization.hpp | 18 + .../homeserver/PendingAuthorisation.hpp | 7 +- .../homeserver/PendingAuthorisationKind.hpp | 21 + .../merovingian/oauth/AuthorizationPages.hpp | 9 + include/merovingian/oauth/HandOffRedirect.hpp | 42 ++ src/homeserver/AGENTS.md | 5 + src/homeserver/ClientServerRuntime.cpp | 47 +- src/homeserver/LoginTokenStore.cpp | 9 + src/homeserver/OAuthAuthorization.cpp | 262 +++++++++-- src/oauth/AGENTS.md | 10 +- src/oauth/AuthorizationPages.cpp | 38 +- src/oauth/HandOffRedirect.cpp | 129 ++++++ src/oauth/meson.build | 1 + tests/conformance/AGENTS.md | 1 + .../test_oauth_aware_clients_conformance.cpp | 192 +++++++++ .../test_oauth_login_hand_off_flow.cpp | 405 ++++++++++++++++++ tests/meson.build | 3 + tests/unit/test_oauth_hand_off_redirect.cpp | 172 ++++++++ 33 files changed, 1466 insertions(+), 72 deletions(-) create mode 100644 docs/adr/0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md create mode 100644 include/merovingian/homeserver/PendingAuthorisationKind.hpp create mode 100644 include/merovingian/oauth/HandOffRedirect.hpp create mode 100644 src/oauth/HandOffRedirect.cpp create mode 100644 tests/conformance/test_oauth_aware_clients_conformance.cpp create mode 100644 tests/integration/test_oauth_login_hand_off_flow.cpp create mode 100644 tests/unit/test_oauth_hand_off_redirect.cpp diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index 3741c77cf..0682c0d96 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -269,6 +269,8 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that allowlist entry is an https origin or a bare private-use scheme, never a prefix (ADR-0774). - The legacy API switch is `legacy_auth_refusal` alone; a route that issues a legacy session asks it (ADR-0801). `src/homeserver/AGENTS.md` +- The legacy login hand-off confirms before every redirect, re-reads `redirectUrl` with `hand_off_redirect_target`, + and is a kind of `PendingAuthorisation`, not a copied handler (ADR-0802). `src/homeserver/AGENTS.md` ## src/observability diff --git a/CHANGELOG.md b/CHANGELOG.md index b6263bd4c..7ea407915 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -66,6 +66,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) time (ADR-0800). * `server.oauth.legacy_api_enabled=false` stops legacy logins and registrations; appservices register with `inhibit_login`, and sessions already issued carry on (ADR-0801). +* With OAuth on, `GET /login` prefers `m.login.sso`, whose redirect signs in on the built-in pages, confirms, and + returns a single-use 30-second `loginToken` to `redirectUrl` (ADR-0802). ## Security Fixes diff --git a/config/merovingian.conf.bsd.example b/config/merovingian.conf.bsd.example index ea428618c..30dcd890b 100644 --- a/config/merovingian.conf.bsd.example +++ b/config/merovingian.conf.bsd.example @@ -640,7 +640,9 @@ security.media.decode_in_sandbox=true # advertises the device authorization grant. # hand_off_redirect_allowlist (only with enabled=true, at most 32 entries) lists # https origins (https://app.example.org) and bare private-use schemes -# (io.element.app:) a hand-off may return to; never a URL prefix. +# (io.element.app:) the legacy SSO redirect's hand-off may return a login +# token to; never a URL prefix. Empty accepts any https address, a loopback +# http address or a private-use scheme, always after a confirmation page. # The former server.oidc.* keys are refused at start-up. # server.oauth.enabled=false # server.oauth.legacy_api_enabled=true diff --git a/config/merovingian.conf.example b/config/merovingian.conf.example index 0ed52eebf..f64d9bb5c 100644 --- a/config/merovingian.conf.example +++ b/config/merovingian.conf.example @@ -613,7 +613,9 @@ security.media.decode_in_sandbox=true # advertises the device authorization grant. # hand_off_redirect_allowlist (only with enabled=true, at most 32 entries) lists # https origins (https://app.example.org) and bare private-use schemes -# (io.element.app:) a hand-off may return to; never a URL prefix. +# (io.element.app:) the legacy SSO redirect's hand-off may return a login +# token to; never a URL prefix. Empty accepts any https address, a loopback +# http address or a private-use scheme, always after a confirmation page. # The former server.oidc.* keys are refused at start-up. # server.oauth.enabled=false # server.oauth.legacy_api_enabled=true diff --git a/docs/adr/0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md b/docs/adr/0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md new file mode 100644 index 000000000..2f4fad8ba --- /dev/null +++ b/docs/adr/0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md @@ -0,0 +1,83 @@ +# The legacy SSO redirect hands off to the built-in pages, always confirms, and mints a 30-second login token + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: plan P10 in `docs/todos/oauth-2-0-api.md`, the hand-off for clients that know only the legacy API. + +## Context and Problem Statement + +With the OAuth 2.0 API on, the spec ("OAuth 2.0 aware clients", Server behaviour) requires the legacy `m.login.sso` +flow with `oauth_aware_preferred: true` and an `action` parameter on the SSO redirect. This server has no external +identity provider when OAuth is on (`server.sso.*` cannot be combined with it), so the redirect must lead to its own +sign-in pages and end, as the spec's "Client login via SSO" does, with a `loginToken` added to `redirectUrl`. A +`redirectUrl` is attacker-chosen: the spec's security considerations describe a link that sends a victim's login token +to `evil.com`. How should the redirect, the pages and the token be built? + +## Decision Drivers + +* A login token gives full access to the account; it must reach only an address the user agreed to. +* The `/authorize` machinery (browser cookie, Origin check, pending store and its per-address cap, the shared login + throttle, `verify_password_login`, `create_local_account`) is already reviewed; a second copy would drift. +* No new persistent state, no migration. + +## Considered Options + +* Reuse `complete_sso_login` and its persistent `login_tokens` table. +* Mint into `LoginTokenStore` (`ClientServerRuntime::login_tokens`, the store `POST /login/get_token` uses) from a new + kind of pending authorisation that the `/authorize` pages carry. +* Skip the confirmation for allowlisted addresses. + +## Decision Outcome + +Chosen option: the second, because it reuses every reviewed piece and holds the token only in memory, hashed. + +* **One pending store, two kinds.** `PendingAuthorisation` carries `PendingAuthorisationKind`. The SSO redirect + (`handle_login_hand_off`) creates a `login_token_hand_off` entry through the same `start_sign_in` the authorisation + request uses, and the forms post to `/_merovingian/oauth2/authorize`. Only the consent page, `approve` and `deny` + branch on the kind. A new kind is added the same way; never copy the handler. +* **The address rules** (`oauth::hand_off_redirect_target`): `https` with a host; `http` only on `localhost`, + `127.0.0.1` or `[::1]`; a private-use scheme (one holding a `.`); nothing else. With + `server.oauth.hand_off_redirect_allowlist` set, the address must also match an entry (ADR-0774); a loopback address + matches none. A refused address is a 400 page with no `Location`. The entry stores the text, and the confirmation and + `approve` read it again under the rules in force then. +* **Always confirm.** After the password, a page names the account and the destination (the host, or the scheme for an + application on the device) and is sent with `page_headers(target)`, so its form may post only here and be answered + by a redirect to that address. Even an allowlisted address is confirmed: the allowlist limits who can receive a + token, the confirmation stops a link from spending the victim's session on a listed application. +* **The token.** `approve` judges the account again (`account_sign_in_gate`), mints 32 random bytes into + `LoginTokenStore` under its caps with `hand_off_login_token_lifetime_ms` (30 seconds), audits + `auth.login_token.issued` with reason `hand_off`, and answers 303 to `redirectUrl` with every `loginToken` parameter + removed and the new one added (spec step 4), `no-store` and `no-referrer`. `deny` redirects nowhere. +* **Redeeming.** `POST /login` `m.login.token` redeems from `LoginTokenStore` when get_token is enabled or the hand-off + is (`legacy_login_hand_off_enabled`). With the legacy API off, `POST /login` is refused before any token is read + (ADR-0801), so no hand-off token is redeemable then. +* **The identity provider ID is not read.** `GET /login` lists no `identity_providers`, so `/redirect/{idpId}` starts + the same pages for any ID. + +### Positive Consequences + +* No second login form, throttle or cookie; the per-address pending cap bounds how many hand-offs one address starts. +* A token never touches the database and is single use. + +### Negative Consequences + +* The token lifetime is 30 seconds, not the "around five seconds" the spec says a login token SHOULD be limited to: + a native application on a phone must be switched to and send `POST /login`, which five seconds does not reliably + allow. `complete_sso_login` already uses 30 seconds. The token is single use and bound to the user. +* `/redirect/{idpId}` with an unknown ID is served rather than answered 404. +* `complete_sso_login` stays without a caller while OAuth is on; it serves `server.sso.*` alone. + +## Pros and Cons of the Options + +### Reuse `complete_sso_login` + +* Bad, because it requires `server.sso.*`, which cannot be configured with OAuth on. +* Bad, because it checks a different allowlist and writes the token to the database. + +### Skip the confirmation for allowlisted addresses + +* Good, because one click fewer. +* Bad, because a link to the redirect with a listed `redirectUrl` would then sign a victim's browser into an + application the victim did not open, which the spec's security considerations warn of. diff --git a/docs/adr/index.md b/docs/adr/index.md index 3bdface20..50e88c607 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -683,3 +683,4 @@ * [0799 - The m.oauth stage accepts a polling retry without a session and reuses the user's live session](0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md) * [0800 - No default member initialiser holds OAuth page text, because clang 18 runs it at run time](0800-no-default-member-initialiser-holds-oauth-page-text-because-clang-18-runs-it-at-run-time.md) * [0801 - One function decides the legacy API switch, and each refused use answers as the spec says](0801-one-function-decides-the-legacy-api-switch-and-each-refused-use-answers-as-the-spec-says.md) +* [0802 - The legacy SSO redirect hands off to the built-in pages, always confirms, and mints a 30-second login token](0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index f6da0d5da..974923661 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -1267,6 +1267,18 @@ the spec's "Account management" names: `account_management_uri` and all six `org - **What carries on.** Sessions already issued, `/refresh`, `/logout`, `/logout/all`, User-Interactive Authentication and every authenticated endpoint; the username availability and registration-token validity checks, the email and phone token requests, and password reset by email, none of which issues a session. +- **Hand-off (P10, ADR-0802).** With both APIs on (`legacy_login_hand_off_enabled`), `GET /login` adds `m.login.sso` + with `oauth_aware_preferred: true` (and `m.login.token` if get_token did not), and both SSO redirects call + `handle_login_hand_off` (`OAuthAuthorization.cpp`). `redirectUrl` must pass `oauth::hand_off_redirect_target` + (`https`; `http` on a loopback host; a private-use scheme; the allowlist when set), else a 400 page. A + `PendingAuthorisation` of kind `login_token_hand_off` is started by the same `start_sign_in` as `/authorize`, and its + forms post there: the shared cookie, Origin check, pending cap, login throttle and account creation. After the + password a confirmation page (`page_headers(target)`) names the account and the destination. `approve` re-reads the + address, runs `account_sign_in_gate`, mints 32 random bytes into `LoginTokenStore` for + `hand_off_login_token_lifetime_ms` (30 s, under the get_token caps), audits `auth.login_token.issued` with reason + `hand_off`, and answers 303 to `oauth::hand_off_return_address` (old `loginToken` parameters removed). `deny` answers + a page. `POST /login` `m.login.token` redeems from that store when get_token or the hand-off is on. + `complete_sso_login` is not used: it needs `server.sso.*`, which cannot be set with OAuth on. ## Next starting points diff --git a/docs/http-transport.md b/docs/http-transport.md index ed076763d..d812dc260 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -977,6 +977,11 @@ cookie (ADR-0788). `Origin`, `Sec-Fetch-Site` and `Cookie` are read with `reques (`homeserver/RequestHeaders.hpp`) and a header sent twice counts as absent. A form body over `max_body_bytes` gets the general `413 M_TOO_LARGE` JSON answer, not a page. +With the OAuth 2.0 API and the legacy API both on, `GET /_matrix/client/v3/login/sso/redirect` and `/{idpId}` answer +the same pages (ADR-0802): a 200 sign-in or registration page with the `__Host-mv-oauth` cookie, or a 400 page with no +`Location` for a refused `redirectUrl`, all marked `LocalHttpResponse::page`. The final redirect is the `303` to the +`redirectUrl` from the confirmation page's form post, with `Cache-Control: no-store` and `Referrer-Policy: no-referrer`. + `POST /_merovingian/oauth2/token` and `POST /_merovingian/oauth2/revoke` (ADR-0791 to ADR-0795) are routed the same way (`static_routes`, `auth_sensitive`, a `client_static_route_allow` row of `POST`, so another method is `405`), before the authentication gate, and are `404 M_UNRECOGNIZED` with the API off. The body must be diff --git a/docs/matrix-v1.19-client-server-api.md b/docs/matrix-v1.19-client-server-api.md index 65010e3ba..09ee57944 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -568,6 +568,7 @@ Room account data (`GET`/`PUT /user/{userId}/rooms/{roomId}/account_data/{type}` device IDs to the remote server and returns only those devices. - **Admin whois (CS8, ADR-0548).** `GET /v3/admin/whois/{userId}`: a server admin may look up any local user, any other caller only themselves. A non-admin asking about someone else gets `403 M_FORBIDDEN` before any lookup (so it cannot probe for accounts). For an admin: a malformed or non-local ID is `400 M_INVALID_PARAM`, an unknown or deactivated local user `404 M_NOT_FOUND`. The answer holds `user_id` and one entry per device, each with one session whose `connections` is empty: the server records no IP address, user agent or last-seen time, and whois does not start recording them. - **Login tokens (CS8, ADR-0548).** Off unless `security.login_token.enabled`; off, `POST /v1/login/get_token` is `404 M_UNRECOGNIZED`, `GET /login` offers no `m.login.token` flow and `GET /capabilities` carries `m.get_login_token: {"enabled": false}`. On, the flow is offered as `{"type":"m.login.token","get_login_token":true}`, the capability is `enabled: true`, and `get_token` runs UIA with `m.login.password` on every call (never a recent session): no auth is a `401` challenge, a wrong password `401 M_FORBIDDEN`. Success is `{"login_token", "expires_in_ms": 120000}`. The token is 256 random bits, kept in memory as a hash, spent by the first `POST /login` that names it (success or not). A user holds 4 live tokens and the server 1024 (`429 M_LIMIT_EXCEEDED` with `retry_after_ms`), and the per-user rate limit is 4 requests a minute. `POST /login` with a token creates a device as password login does and refuses a locked, suspended or deactivated account the same way. The SSO `loginToken` redeemed through the same `type` is unchanged. +- **OAuth 2.0 aware clients (P10, ADR-0802).** With `server.oauth.enabled=true` and the legacy API on: `GET /login` adds `{"type":"m.login.sso","oauth_aware_preferred":true}` (and `m.login.token` when get_token did not); `m.login.password` stays. Both `/login/sso/redirect` routes read `redirectUrl` (required; `https`, loopback `http` or a private-use scheme, and the allowlist when set, else a 400 page) and `action` (`register` opens registration, anything else sign-in), ignore `idpId`, and answer the built-in pages; a confirmation names the account and the destination before a 303 adds one `loginToken` (30 s, single use, older `loginToken` parameters removed). The spec's 302 to an SSO interface becomes a 200 page: the pages are the SSO interface. - **Without the legacy API (P9, ADR-0801).** With `server.oauth.legacy_api_enabled=false`: `GET /login` `404 M_UNRECOGNIZED` (spec "Authentication API discovery"); `POST /login` for a user, both `/login/sso/redirect` routes and `POST /login/get_token` `404 M_UNRECOGNIZED` (the spec gives them no answer of their own); `m.login.application_service` on `POST /login` `400 M_APPSERVICE_LOGIN_UNSUPPORTED`; `POST /register` for a user `403 M_FORBIDDEN` before UIA, and for an application service served only with `"inhibit_login": true`, else `400 M_APPSERVICE_LOGIN_UNSUPPORTED` with nothing created. Sessions already issued, `/refresh`, `/logout` and UIA carry on. - `GET /capabilities` carries `m.account_moderation` (`lock`, `suspend`) for server admins and omits it for other users. - A joined room's `/sync` timeline no longer carries the unspecified `event_count`. diff --git a/docs/observability-audit.md b/docs/observability-audit.md index ca7f7a10b..099fccdb9 100644 --- a/docs/observability-audit.md +++ b/docs/observability-audit.md @@ -273,7 +273,7 @@ Grepping for `append_local_audit` call sites finds these event-name families: `auth.account_deactivated`, `auth.password_changed`, `auth.openid.request_token`, `auth.sso.login_token.issued`, `auth.sso.login_token.redeemed`, `auth.login_token.issued`, - `auth.login_token.redeemed` (tokens from `POST /login/get_token`), + `auth.login_token.redeemed` (tokens from `POST /login/get_token`, and from the OAuth hand-off, issued with reason `hand_off`), `auth.refresh.reuse_detected`, `auth.refresh.predecessor_revoke`, `auth.password_reset`. - `device.*` (`src/homeserver/AuthService.cpp`, `src/homeserver/ClientServerRuntime.cpp`): @@ -568,6 +568,13 @@ audit row (category `auth`, actor the user, target the client ID, reason the dev is; `oauth.authorization.denied` is audited the same way only when a user had signed in, since a denial before the password is anyone's to send. +The legacy login hand-off (ADR-0802) logs under the same module: `oauth.hand_off.started` (debug, no field), +`oauth.hand_off.refused` (debug for a refused `redirectUrl` or a store refusal, no field; info with `user_id` when the +account fails `account_sign_in_gate` or the login token store is full), `oauth.hand_off.granted` and +`oauth.hand_off.cancelled` (info, `user_id` once signed in). Never the `redirectUrl`, the login token, the cookie or +the pending identifier. A granted hand-off writes the durable `auth.login_token.issued` row (actor the user, reason +`hand_off`); its redemption is `auth.login_token.redeemed`, as for a get_token token. + ## OAuth 2.0 token and revocation diagnostics and audit (ADR-0791 to ADR-0795) `POST /_merovingian/oauth2/token` logs under the `oauth` module: `oauth.token.refused` (debug, `grant_type`, `error` diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index e61b4f06e..feecca9f4 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1104,6 +1104,12 @@ quickly finding everything a given `AGENTS.md` file contributed. user leaves an account behind (ADR-0801). Source: `src/homeserver/AGENTS.md`. +- **The legacy login hand-off sends a login token only to a `redirectUrl` that `oauth::hand_off_redirect_target` + accepts, read again at every step, and only after the signed-in user confirmed on a page naming it.** + Why: the spec's own example is a link that sends a victim's login token to `evil.com` (CWE-601, CWE-352); an + allowlist alone does not stop a link spending the victim's session on a listed application (ADR-0802). + Source: `src/homeserver/AGENTS.md`. + ## HTTP and network boundary - **Rate limiting is applied before any auth check.** Do not move it after auth. diff --git a/docs/todos/capability-gaps.md b/docs/todos/capability-gaps.md index 8776c8c3d..dbd258fcd 100644 --- a/docs/todos/capability-gaps.md +++ b/docs/todos/capability-gaps.md @@ -47,7 +47,7 @@ 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) and the `m.oauth` UIA stage are served (ADR-0779 to ADR-0798); the device authorization grant is a later phase of the [OAuth 2.0 API plan](oauth-2-0-api.md). An OAuth session still cannot add an email address or mint a login token (no page; `403 M_FORBIDDEN`). | +| `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); the device authorization grant is a later phase of the [OAuth 2.0 API plan](oauth-2-0-api.md). An OAuth session still cannot add an email address or mint a login token (no page; `403 M_FORBIDDEN`). | | `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). | | 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. | | Room summary over federation | `runtime-wired` | `GET /v1/room_summary/{roomIdOrAlias}?via=` asks up to 3 `via` servers over federation `GET /hierarchy/{roomId}` (the `room` chunk; v1.19 defines no federation summary route) for a room this server holds no state for (ADR-0556): one ADR-0079 slot (429 at once without one, also without a token), one deadline, unverified answer, shown only by its own `join_rule` / `world_readable` / `allowed_room_ids`. Local state always wins; a malformed `via` is `400 M_INVALID_PARAM`. Not implemented: resolving an alias that lives on another server (404 / 401), and `membership` for a room not held locally. | @@ -90,7 +90,7 @@ When adding a capability, record what is *missing* as explicitly as what works. | `GET /_matrix/client/v3/rooms/{roomId}/context/{eventId}` | `spec-covered` | Returns `events_before`/`event`/`events_after`/`state` around a permalink target. Same read gate as `/messages` and `/event/{eventId}` (no read access and not world_readable: 403; an unknown event id, an event id from a different room, and an event the user may not see under the room's history visibility all 404 `M_NOT_FOUND`, identically, so existence elsewhere is not leaked). `events_before` and `events_after` hold only events the user may see, so the `state` below is pinned to one of them. `limit` (default 10, spec-applied to the combined `events_before`+`events_after` size) is clamped to the `/messages` maximum. `filter` accepts a `RoomEventFilter` via `sync::parse_room_event_filter_argument()`; malformed JSON is rejected with 400 `M_BAD_JSON`. `start`/`end` are the same plain stream-ordering tokens `/messages` produces. **`state` is now reconstructed at the last event actually returned (0.11.11, PR #479 review fix)** rather than read off the room's current state, per CS API: "The state of the room at the last event returned." `federation::resolve_state_event_ids_at()` (`src/federation/EventQuery.cpp`) reuses the same backward event-DAG walk `build_state_response`/`build_state_ids_response` already use for the federation `GET /state`/`/state_ids` endpoints (`reconstruct_state_at_event`, landed 0.8.10), then folds the pinned event's own state contribution back in when it is itself a state event — the federation endpoints intentionally stop one step short of that (SS API `GET /state`: "prior to considering any state changes induced by the requested event"), while `/context`'s `state` wants the room's state inclusive of the pinned event. Proven by a conformance scenario where a room's name changes strictly after the last event a bounded `limit` admits: `state` still carries the pre-rename name, not the room's present-day one. **`GET /messages` was deliberately left unchanged** — see its own row below for why extending this fix there does not apply cleanly. **`lazy_load_members` (0.12.73, ADR-0451):** `state` is only the `m.room.member` events of the senders of `events_before`, `event` and `events_after`; the filter's `types`/`senders` do not remove them; redundancy is not tracked. | | `GET /_matrix/client/v3/rooms/{roomId}/messages` | `spec-covered` | Paginates the room timeline via `from`/`to`/`dir`/`limit`/`filter` (`RoomEventFilter`). **History visibility is enforced (audit CSAZ-3)**: every event goes through `sync::HistoryVisibility`, the page skips what the user may not see, and `end` still moves past skipped events; one page examines at most `ClientApiLimits::max_messages_events_examined` (2000) events, then returns what it has with a token to continue from (an empty `chunk` does not mean the timeline ended). A user who has left or was banned may read (state as of their departure), and a room whose current visibility is `world_readable` may be read without joining; everyone else is 403. **Chunk-relevant `state` landed in 0.12.2**, closing the divergence from `/context` recorded here: `lazy_load_members` was never parsed anywhere in the codebase, and this endpoint passed a default-constructed filter to its state builder, so it returned the room's full current state including every member. Membership state is now limited to senders appearing in the chunk; since 0.12.60 `state` holds nothing but those members' `m.room.member` events when `lazy_load_members` is set (Complement), and redundant memberships are re-sent on every page. The endpoint-shape distinction is worth keeping: `/context` returns "the state of the room at the last event returned" and reconstructs it via the event-DAG walk, whereas `/messages` returns "state events relevant to showing the `chunk`" — so applying `/context`'s temporal fix here would have left `state` wrong in a different way (over-inclusive, unfiltered by relevance) rather than right. | | `POST /_matrix/client/v3/user/{userId}/openid/request_token` | `spec-covered` | Mints a short-lived OpenID token (`request_openid_token`), stored in its own `openid_tokens` table — never the `access_tokens` table — so it cannot authenticate ordinary client-server requests. Path `userId` must equal the authenticated caller; a mismatch fails closed 403 `M_FORBIDDEN` identically whether or not the named user exists. Redeemed via the paired federation `GET /_matrix/federation/v1/openid/userinfo` (see the Federation API table); conformance-covered for both halves plus the access-token/OpenID-token separation in both directions. | -| SSO login (`m.login.sso`, `GET /_matrix/client/v3/login/sso/redirect[/{idpId}]`) | `runtime-wired` | `m.login.sso` is advertised from `GET /login` with configured `identity_providers`; the redirect route validates `redirectUrl` against `server.sso.redirect_url_allowlist`, validates `idpId`, and redirects to the configured authorization URL. `m.login.token` uses short-lived single-use login tokens in the durable `login_tokens` table (migration 012), separate from access tokens. Merovingian does not provide a first-party CAS/SAML/OIDC adapter; `homeserver::complete_sso_login` is the integration point for an operator's external IdP adapter. Older statements that SSO is unrouted are obsolete. See `docs/auth-identity.md` and `docs/threat-model.md`. | +| SSO login (`m.login.sso`, `GET /_matrix/client/v3/login/sso/redirect[/{idpId}]`) | `runtime-wired` | `m.login.sso` is advertised from `GET /login` with configured `identity_providers`; the redirect route validates `redirectUrl` against `server.sso.redirect_url_allowlist`, validates `idpId`, and redirects to the configured authorization URL. `m.login.token` uses short-lived single-use login tokens in the durable `login_tokens` table (migration 012), separate from access tokens. Merovingian does not provide a first-party CAS/SAML/OIDC adapter; `homeserver::complete_sso_login` is the integration point for an operator's external IdP adapter. Older statements that SSO is unrouted are obsolete. See `docs/auth-identity.md` and `docs/threat-model.md`. With `server.oauth.enabled=true` the `server.sso.*` keys cannot be set and the redirect is the OAuth hand-off to the built-in pages instead (ADR-0802). | | Ignoring users (`m.ignored_user_list`) | `spec-covered` | Enforced (0.11.11) via `merovingian::trust_safety::ignore_list` (`resolve_ignored_users` / `is_delivery_suppressed`), called from every client-facing delivery surface: `GET /sync` (timeline, invite list, typing/receipts), MSC4186 sliding sync (timeline, required_state — including the invite override for an explicitly-subscribed room, since sliding sync has no separate invite surface — and the receipts/typing extensions), `GET /messages`, `GET /context/{eventId}` (events_before/events_after only — the requested event itself is always returned), and push notification delivery (`build_pending_push_deliveries`, covering both message and membership/invite pushes). Per spec: non-state events from an ignored sender are withheld; state events are still delivered (room state stays accurate); a new-room invite is withheld even though it is itself a state event. Filtering is delivery-side only — it never touches event persistence, auth rules, state resolution, or federation acceptance, and it does not retroactively hide events already delivered to the client (a fresh sync is required for that, per spec). A malformed or absent `m.ignored_user_list` fails safe to "nothing ignored". Conformance-covered in `tests/conformance/test_ignoring_users_conformance.cpp`; sliding sync and push-delivery suppression are integration-covered in `tests/integration/test_sliding_sync_flow.cpp` and `tests/integration/test_push_delivery_flow.cpp`. **Known gap**: sliding sync's room *list* only ever enumerates joined rooms (a pre-existing limitation, not introduced here) — an invite can only be observed there via an explicit `room_subscriptions` entry naming the room, which now yields the invite's stripped `invite_state` only (an ignored inviter's invite is omitted), and that is where the suppression is proven. | | `GET /_matrix/client/v3/thirdparty/{protocols,protocol/{p},location,location/{p},user,user/{p}}` | `spec-covered` | All six third-party lookup routes are wired (`src/appservice/AppserviceClient.cpp`'s `query_thirdparty_*` methods, routed in `ClientServerRuntime.cpp`). `protocols`/`protocol/{protocol}` call the owning appservice's `GET /_matrix/app/v1/thirdparty/protocol/{protocol}` and mint `instance_id` per spec; `location`/`user` (bare) fan out to every registered appservice and aggregate; `location/{protocol}`/`user/{protocol}` fan out to every appservice declaring that protocol, forwarding the client's query string verbatim as search fields. An unknown protocol is `404 M_NOT_FOUND`; `protocols` still returns `{}` (not 404) when no appservice is registered. An unreachable/erroring/timing-out appservice degrades to "no results" for the routes it would have contributed to rather than failing the whole request — proven in `tests/integration/test_appservice_thirdparty_flow.cpp`. All six routes are unauthenticated-rejected (401) and bypass client rate limiting per the spec's `Rate-limited: No` flag. Every field taken from an appservice's reply is type-checked and bounded before being echoed to the client (`AppserviceClient.cpp`'s `parse_thirdparty_*` — a bridge is not a trusted peer). Conformance-covered in `tests/conformance/test_appservice_thirdparty_conformance.cpp`. | | `PUT /_matrix/client/v3/profile/{userId}/avatar_url` | `spec-covered` | Conformance fixture now covers successful update, cross-user 403 guard, and retrieval via `GET /_matrix/client/v3/profile/{userId}/avatar_url`. 0.12.30: a display name or avatar change now sends an `m.room.member` join carrying it to every joined room ("Events on Change of Profile Information"), and this server's own joins carry the profile. The same section's `m.presence` update is sent too, and `/sync` `m.presence` events carry `displayname`/`avatar_url` from the profile. 0.12.35 (ADR-0182): the PUT answers 200 once the field is stored, even when a room or the presence write fails (logged at warning); the next profile change rechecks joined rooms and skips membership events already carrying the current profile. Rooms are chosen by current `m.room.member` state, so a stale runtime member list cannot rejoin a user to a room they left. | diff --git a/docs/todos/oauth-2-0-api.md b/docs/todos/oauth-2-0-api.md index 10842d646..f8dd5cf70 100644 --- a/docs/todos/oauth-2-0-api.md +++ b/docs/todos/oauth-2-0-api.md @@ -242,8 +242,9 @@ retry and given back unless the keys are stored (ADR-0797). - With both APIs on, `GET /login` adds `m.login.sso` with `oauth_aware_preferred: true`. The SSO redirect endpoints read `action` and send the browser to the built-in login or registration page. After the confirmation page (P10) - the browser returns to the client with a login token, which the client redeems with `m.login.token`. This gives - `complete_sso_login` its first caller. + the browser returns to the client with a login token, which the client redeems with `m.login.token`. Done in + phase 9 (ADR-0802): the token is minted into `LoginTokenStore`, not by `complete_sso_login`, which needs + `server.sso.*`. - With `server.oauth.legacy_api_enabled=false`: `GET /login` is `404 M_UNRECOGNIZED`; `POST /login` and `POST /register` refuse users; `POST /register` still serves application services and requires `inhibit_login: true`; `m.login.application_service` is `400 M_APPSERVICE_LOGIN_UNSUPPORTED`. Existing legacy diff --git a/docs/user-manual.md b/docs/user-manual.md index 9b97df08a..9f9c6dcee 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -880,7 +880,7 @@ pass `/_merovingian/oauth2/` and `/_merovingian/account` through, as it does | `server.oauth.enabled` | `false` | Set `true` to serve the OAuth 2.0 API. `server.public_baseurl` must then be an `https` URL with a host and no query, fragment or userinfo (a path is allowed), and `server.sso.authorization_url` must be empty. | | `server.oauth.legacy_api_enabled` | `true` | Set `false` to stop the legacy login and registration API issuing new sessions to users (ADR-0761, ADR-0801). Refused unless `server.oauth.enabled=true`, so users always have a way to log in. See [Turning the legacy API off](#turning-the-legacy-api-off). | | `server.oauth.device_grant_enabled` | `false` | Set `true` to offer the device authorization grant (RFC 8628): the metadata then lists the device code grant type and `device_authorization_endpoint`. Refused unless `server.oauth.enabled=true`. | -| `server.oauth.hand_off_redirect_allowlist` | (empty) | Comma-separated places the hand-off from the legacy SSO redirect may send the browser: `https` origins (`https://app.example.com`, `https://app.example.com:8443`, nothing after the host or port) and bare private-use schemes (`io.element.app:`), in lower case. Never a URL prefix (ADR-0774). At most 32 entries, none twice. Refused unless `server.oauth.enabled=true`. Checked now, used once the hand-off lands. | +| `server.oauth.hand_off_redirect_allowlist` | (empty) | Comma-separated places the hand-off from the legacy SSO redirect may send the browser: `https` origins (`https://app.example.com`, `https://app.example.com:8443`, nothing after the host or port) and bare private-use schemes (`io.element.app:`), in lower case. Never a URL prefix (ADR-0774). At most 32 entries, none twice. Refused unless `server.oauth.enabled=true`. Empty, any `https` address, a loopback `http` address or a private-use scheme is accepted. See [The hand-off for legacy clients](#the-hand-off-for-legacy-clients). | The metadata offers `prompt=create` (`prompt_values_supported`) only while `security.registration.enabled=true`: account creation through the pages @@ -888,7 +888,27 @@ follows the legacy registration settings (ADR-0762). Every `server.oauth.*` key needs a restart. -##### Turning the legacy API off +##### The hand-off for legacy clients + +With `server.oauth.enabled=true` and `server.oauth.legacy_api_enabled=true` (the +default), clients that know only the legacy API are sent to this server's own +sign-in pages (ADR-0802). `GET /_matrix/client/v3/login` adds `m.login.sso` +with `"oauth_aware_preferred": true`, and `m.login.token` when +`security.login_token.enabled` did not already add it; `m.login.password` stays. +`GET /_matrix/client/v3/login/sso/redirect` (and `/{idpId}`, whatever the ID) +needs a `redirectUrl`: + +- `https://` with a host; `http://` only to `localhost`, `127.0.0.1` or + `[::1]`; or a private-use scheme holding a `.` (`io.element.app:/callback`). + Anything else, and an address `server.oauth.hand_off_redirect_allowlist` + does not list when it is set, gets a 400 page and no redirect. +- `action=register` opens the registration page (when registration is open); + anything else the sign-in page. +- After the password, a confirmation page names the account and where the + browser goes next. Continue sends the browser there with a `loginToken` that + works once, within 30 seconds; Cancel sends it nowhere. + +#### Turning the legacy API off With `server.oauth.legacy_api_enabled=false` users sign in and register only through the OAuth 2.0 API (ADR-0801): @@ -901,7 +921,7 @@ through the OAuth 2.0 API (ADR-0801): | `POST /_matrix/client/v3/register`, a user | `403 M_FORBIDDEN` | | `POST /_matrix/client/v3/register`, an application service without `"inhibit_login": true` | `400 M_APPSERVICE_LOGIN_UNSUPPORTED`, nothing created | | `POST /_matrix/client/v3/register`, an application service with `"inhibit_login": true` | served as before | -| `GET /_matrix/client/v3/login/sso/redirect` and `/{idpId}` | `404 M_UNRECOGNIZED` | +| `GET /_matrix/client/v3/login/sso/redirect` and `/{idpId}` | `404 M_UNRECOGNIZED`; no hand-off | | `POST /_matrix/client/v1/login/get_token` | `404 M_UNRECOGNIZED`; `m.get_login_token` reports `enabled: false` | Unchanged: every session already issued, with `/refresh`, `/logout`, diff --git a/include/merovingian/homeserver/LoginTokenStore.hpp b/include/merovingian/homeserver/LoginTokenStore.hpp index 2c061b4e6..bd29e31f4 100644 --- a/include/merovingian/homeserver/LoginTokenStore.hpp +++ b/include/merovingian/homeserver/LoginTokenStore.hpp @@ -45,6 +45,9 @@ class LoginTokenStore final std::uint64_t retry_after_ms{0U}; }; + // The hash this store keeps of `token` (unkeyed BLAKE2b-256 as lower-case hex), or nullopt when hashing failed. + // Every caller that issues or redeems hashes with this. + [[nodiscard]] static auto token_hash(std::string_view token) -> std::optional; // Records `token_hash` for `user_id`, valid for `lifetime_ms` from `now_ms`. [[nodiscard]] auto issue(std::string_view user_id, std::string token_hash, std::uint64_t now_ms, std::uint64_t lifetime_ms, std::size_t per_user_cap, std::size_t total_cap) -> IssueResult; diff --git a/include/merovingian/homeserver/OAuthAuthorization.hpp b/include/merovingian/homeserver/OAuthAuthorization.hpp index e488eb386..61806a158 100644 --- a/include/merovingian/homeserver/OAuthAuthorization.hpp +++ b/include/merovingian/homeserver/OAuthAuthorization.hpp @@ -56,4 +56,22 @@ inline constexpr auto max_oauth_login_hint_bytes = std::size_t{255U}; [[nodiscard]] auto handle_oauth_authorize(ClientServerRuntime& runtime, LocalHttpRequest const& request) -> LocalHttpResponse; +// How long a login token minted by the hand-off can be redeemed. The spec recommends around five seconds for an SSO +// login token ("Client login via SSO"); 30 seconds leaves room for a mobile operating system to switch to the +// application, and the token is still single use (ADR-0802). +inline constexpr auto hand_off_login_token_lifetime_ms = std::uint32_t{30000U}; + +// `GET /_matrix/client/v3/login/sso/redirect` and `/{idpId}` with the OAuth 2.0 API and the legacy API both on (spec +// "OAuth 2.0 aware clients"; plan P10; ADR-0802). The dispatcher has checked both keys. `redirectUrl` (required) must +// pass oauth::hand_off_redirect_target with `server.oauth.hand_off_redirect_allowlist`, else a 400 page with no +// redirect. `action=register` starts on the registration page; any other `action`, or none, on the login page. The +// identity provider ID is not read. A pending authorisation of kind `login_token_hand_off` is created exactly as the +// authorisation request does, and the forms post to `/_merovingian/oauth2/authorize`: after the password, a +// confirmation page names the account and the destination; `approve` mints a login token into +// ClientServerRuntime::login_tokens (hand_off_login_token_lifetime_ms) and answers 303 to the address +// oauth::hand_off_return_address makes; `deny` answers a page and redirects nowhere. Same lock rules as +// handle_oauth_authorize. Never logs the address, the token, the cookie or the pending identifier. +[[nodiscard]] auto handle_login_hand_off(ClientServerRuntime& runtime, LocalHttpRequest const& request) + -> LocalHttpResponse; + } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/PendingAuthorisation.hpp b/include/merovingian/homeserver/PendingAuthorisation.hpp index 1d8cc2e3c..b4cc96cca 100644 --- a/include/merovingian/homeserver/PendingAuthorisation.hpp +++ b/include/merovingian/homeserver/PendingAuthorisation.hpp @@ -2,6 +2,7 @@ // SPDX-License-Identifier: GPL-3.0-or-later #pragma once +#include "merovingian/homeserver/PendingAuthorisationKind.hpp" #include "merovingian/oauth/ResponseMode.hpp" #include @@ -19,10 +20,14 @@ namespace merovingian::homeserver // `created_at_ms` and `client_address_key` from its own arguments and starts `user_id` empty. struct PendingAuthorisation final { + // What the entry ends in. A hand-off (`login_token_hand_off`, ADR-0802) has no client: `client_id`, `state`, + // `code_challenge`, `device_id`, `scope` and `login_hint` stay empty. + PendingAuthorisationKind kind{PendingAuthorisationKind::authorization_code}; // The registered client that asked. std::string client_id{}; // The redirect URI exactly as the request gave it (a native loopback URI keeps the port it was sent with); it was - // matched against the registration with `oauth::match_redirect_uri` before the entry was made. + // matched against the registration with `oauth::match_redirect_uri` before the entry was made. For a hand-off, + // the `redirectUrl` `oauth::hand_off_redirect_target` accepted. std::string redirect_uri{}; oauth::ResponseMode response_mode{oauth::ResponseMode::query}; // The client's `state`, returned with the answer. Empty when the client sent none. diff --git a/include/merovingian/homeserver/PendingAuthorisationKind.hpp b/include/merovingian/homeserver/PendingAuthorisationKind.hpp new file mode 100644 index 000000000..4a1a27a07 --- /dev/null +++ b/include/merovingian/homeserver/PendingAuthorisationKind.hpp @@ -0,0 +1,21 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::homeserver +{ + +// What a pending authorisation ends in once its user signed in and approved (ADR-0802). +enum class PendingAuthorisationKind : std::uint8_t +{ + // An OAuth 2.0 authorisation request: the consent page, then an authorization code sent to the client's matched + // redirect URI (ADR-0787 to ADR-0790). + authorization_code, + // The legacy SSO redirect's hand-off: the confirmation page, then a login token added to the `redirectUrl` the + // hand-off accepted (`oauth::hand_off_redirect_target`). No client is registered for it. + login_token_hand_off, +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/oauth/AuthorizationPages.hpp b/include/merovingian/oauth/AuthorizationPages.hpp index 2675bbba7..209bb2cac 100644 --- a/include/merovingian/oauth/AuthorizationPages.hpp +++ b/include/merovingian/oauth/AuthorizationPages.hpp @@ -9,6 +9,8 @@ #include "merovingian/oauth/Page.hpp" #include "merovingian/oauth/ParsedUri.hpp" +#include + namespace merovingian::oauth { @@ -48,6 +50,13 @@ inline constexpr auto action_deny = HtmlName{"deny"}; // buttons. [[nodiscard]] auto consent_page(ConsentPageInput const& input, ParsedUri const& redirect_target) -> Page; +// The confirmation page of the legacy login hand-off (plan P10, ADR-0802): the user signed in, and the application +// at `target` (its host for an `http` or `https` address, else its scheme) is about to receive a login token for the +// account. Continue (`approve`) and cancel (`deny`) post to `authorize_path`. Sent with `page_headers(target)`. +[[nodiscard]] auto hand_off_page(std::string_view pending_id, std::string_view user_id, ParsedUri const& target) + -> Page; +// The page a cancelled hand-off ends on: nothing is sent to the application. +[[nodiscard]] auto hand_off_cancelled_page() -> Page; // A page that only says what went wrong: `title` and one paragraph, no form. [[nodiscard]] auto error_page(HtmlText title, HtmlText const& message) -> Page; diff --git a/include/merovingian/oauth/HandOffRedirect.hpp b/include/merovingian/oauth/HandOffRedirect.hpp new file mode 100644 index 000000000..f91ca2333 --- /dev/null +++ b/include/merovingian/oauth/HandOffRedirect.hpp @@ -0,0 +1,42 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/oauth/ParsedUri.hpp" + +#include +#include +#include +#include + +namespace merovingian::oauth +{ + +// The rules for the `redirectUrl` of the legacy SSO redirect when it hands the browser to the built-in pages (plan +// P10, ADR-0802). Pure: no state, no I/O. + +// `redirect_url` read with ParsedUri::read (so at most ParsedUri::max_uri_bytes, printable ASCII, no fragment, no +// userinfo) and accepted when its scheme, compared in ASCII lower case, is +// +// - `https`, with a host; +// - `http`, with the host `localhost`, `127.0.0.1` or `[::1]` (any port): a native client's loopback listener; +// - a private-use scheme, one holding a `.` (RFC 8252 section 7.1), with or without an authority. +// +// Anything else is refused: `javascript:`, `data:`, `file:` and every scheme without a `.` other than the two above. +// With a non-empty `allowlist` (`server.oauth.hand_off_redirect_allowlist`, its entries already checked by +// hand_off_allowlist_entry_error) the target must also match an entry: an `https` origin entry matches an `https` +// target with the same host (ASCII lower case) and the same port (443 when none is written); a bare scheme entry +// (`io.element.app:`) matches a target of that scheme in any case. An `http` loopback target matches no entry, so an +// allowlist refuses it. nullopt when refused. +[[nodiscard]] auto hand_off_redirect_target(std::string_view redirect_url, std::span allowlist) + -> std::optional; + +// The address the browser is sent to after the hand-off: `target` with every query parameter named exactly +// `loginToken` removed (spec "Handling the callback from the Authentication server", step 4: "If it already includes +// one or more loginToken parameters, they should be removed before adding the new one"), then `loginToken=` +// added to the query by authorization_redirect_address (percent-encoded). nullopt only if the address without those +// parameters is no longer one ParsedUri reads, which removing whole parameters cannot cause. +[[nodiscard]] auto hand_off_return_address(ParsedUri const& target, std::string_view login_token) + -> std::optional; + +} // namespace merovingian::oauth diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 85df1e424..a853d3383 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -201,6 +201,11 @@ The legacy API switch (`server.oauth.legacy_api_enabled`, ADR-0801) is decided b create anything. A new route that lists the legacy logins or issues a user a session asks it too; never test the key in a route. A session already issued, `/refresh`, `/logout` and UIA are not uses and are never gated. +With both APIs on, the SSO redirects call `handle_login_hand_off` (`OAuthAuthorization.cpp`, ADR-0802). It starts a +`PendingAuthorisation` of kind `login_token_hand_off` through the same `start_sign_in` as `/authorize`; only the +consent page, `approve` and `deny` branch on the kind. A hand-off never redirects before the user confirmed, reads its +`redirectUrl` again with `oauth::hand_off_redirect_target` at every step, and mints only into `rt.login_tokens`. + `POST /_merovingian/oauth2/register` is `register_oauth_client` (`OAuthClientRegistration.cpp`), answered before the authentication gate, and also from the general body cap so an oversized body is an OAuth 400 (ADR-0781). Rules: diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index 339132238..a9d117569 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -4508,13 +4508,6 @@ namespace return dispatch_err(req, rt, refusal->status, refusal->errcode, refusal->reason); } - // Hash of a login token as `LoginTokenStore` keeps it. The token is 256 random bits, so an unkeyed hash suffices. - [[nodiscard]] auto login_token_hash(std::string_view token) -> std::optional - { - auto const pieces = std::array{token}; - return crypto::generic_hash(pieces); - } - // F-07: the operator accounts route deactivates through `HomeserverRuntime` alone, which cannot reach the // login tokens. After a successful POST to it, a target that is now deactivated holds none. auto erase_login_tokens_of_deactivated_target(ClientServerRuntime& rt, std::string_view request_path) -> void @@ -4638,7 +4631,7 @@ namespace }); } auto const token = crypto::secure_random_hex(32U); - auto const token_hash = token.has_value() ? login_token_hash(*token) : std::nullopt; + auto const token_hash = token.has_value() ? LoginTokenStore::token_hash(*token) : std::nullopt; if (!token_hash.has_value()) { return dispatch_err(req, rt, 500U, "M_UNKNOWN", "could not generate a login token"); @@ -4665,16 +4658,19 @@ namespace }))); } - // Consumes a login token minted by get_token, answering the user it was minted for. A token is spent by the - // attempt that names it, so this is called once per login. Empty when the feature is off. + // Consumes a login token minted by get_token or by the legacy login hand-off (ADR-0802), answering the user it was + // minted for. A token is spent by the attempt that names it, so this is called once per login. Empty when neither + // mints tokens. [[nodiscard]] auto redeem_minted_login_token(ClientServerRuntime& rt, std::string_view token) -> std::optional { - if (!login_tokens_enabled(rt) || token.empty()) + auto const minted_here = + login_tokens_enabled(rt) || legacy_login_hand_off_enabled(rt.homeserver.config.server().oauth); + if (!minted_here || token.empty()) { return std::nullopt; } - auto const token_hash = login_token_hash(token); + auto const token_hash = LoginTokenStore::token_hash(token); if (!token_hash.has_value()) { return std::nullopt; @@ -16143,6 +16139,22 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp } flows.emplace_back(json_obj(std::move(sso_flow))); } + // Spec "OAuth 2.0 aware clients", server behaviour: with the OAuth 2.0 API on, `m.login.sso` with + // `oauth_aware_preferred: true`, its redirect handing the browser to the built-in pages (ADR-0802). The login + // token the hand-off returns is redeemed with `m.login.token`, offered here when get_token did not already. + // `m.login.password` stays ("If password authentication was previously enabled"). `server.sso.*` cannot be + // configured with OAuth on, so the flow above is never offered twice. + if (legacy_login_hand_off_enabled(rt.homeserver.config.server().oauth)) + { + if (!login_tokens_enabled(rt)) + { + flows.emplace_back(json_obj({json_member("type", json_str("m.login.token"))})); + } + flows.emplace_back(json_obj({ + json_member("type", json_str("m.login.sso")), + json_member("oauth_aware_preferred", json_bool(true)), + })); + } return dispatch_resp(req, rt, 200U, json_serialize(json_obj({ json_member("flows", json_arr(std::move(flows))), @@ -16159,6 +16171,12 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp { return std::move(*refused); } + // With the OAuth 2.0 API on, the built-in pages answer the redirect (ADR-0802): sign-in or registration, a + // confirmation, then a login token back to `redirectUrl`. + if (legacy_login_hand_off_enabled(rt.homeserver.config.server().oauth)) + { + return DispatchResult{DispatchResult::Status::complete, handle_login_hand_off(rt, req), {}}; + } auto const redirect_url = query_param_value(req.target, "redirectUrl"); auto const action = query_param_value(req.target, "action"); auto const result = sso_redirect_target(rt.homeserver, {}, redirect_url.value_or(std::string{}), @@ -16177,6 +16195,11 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp { return std::move(*refused); } + // The hand-off advertises no identity provider, so every `idpId` starts the same pages (ADR-0802). + if (legacy_login_hand_off_enabled(rt.homeserver.config.server().oauth)) + { + return DispatchResult{DispatchResult::Status::complete, handle_login_hand_off(rt, req), {}}; + } auto path_and_idp = req.target.substr(std::string_view{"/_matrix/client/v3/login/sso/redirect/"}.size()); if (auto const query = path_and_idp.find('?'); query != std::string_view::npos) { diff --git a/src/homeserver/LoginTokenStore.cpp b/src/homeserver/LoginTokenStore.cpp index 2b2ed54aa..5f507b0b9 100644 --- a/src/homeserver/LoginTokenStore.cpp +++ b/src/homeserver/LoginTokenStore.cpp @@ -3,8 +3,10 @@ #include "merovingian/homeserver/LoginTokenStore.hpp" #include "merovingian/crypto/ConstantTime.hpp" +#include "merovingian/crypto/GenericHash.hpp" #include +#include #include #include @@ -74,6 +76,13 @@ auto LoginTokenStore::erase_user(std::string_view user_id) -> void }); } +auto LoginTokenStore::token_hash(std::string_view token) -> std::optional +{ + // The token is 256 random bits, so an unkeyed hash suffices. + auto const pieces = std::array{token}; + return crypto::generic_hash(pieces); +} + auto LoginTokenStore::size() const noexcept -> std::size_t { return m_entries.size(); diff --git a/src/homeserver/OAuthAuthorization.cpp b/src/homeserver/OAuthAuthorization.cpp index 5b47ef247..d622a798f 100644 --- a/src/homeserver/OAuthAuthorization.cpp +++ b/src/homeserver/OAuthAuthorization.cpp @@ -8,6 +8,7 @@ #include "merovingian/core/Error.hpp" #include "merovingian/core/FormFields.hpp" #include "merovingian/core/HostCookie.hpp" +#include "merovingian/crypto/Random.hpp" #include "merovingian/database/PersistentStore.hpp" #include "merovingian/homeserver/AccountCreationRequest.hpp" #include "merovingian/homeserver/AuthService.hpp" @@ -18,6 +19,7 @@ #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" #include "merovingian/homeserver/LocalServices.hpp" +#include "merovingian/homeserver/LoginTokenStore.hpp" #include "merovingian/homeserver/OAuthClientRegistration.hpp" #include "merovingian/homeserver/OAuthClock.hpp" #include "merovingian/homeserver/OAuthPageResponse.hpp" @@ -26,6 +28,7 @@ #include "merovingian/homeserver/PasswordLoginRequest.hpp" #include "merovingian/homeserver/PasswordLoginVerification.hpp" #include "merovingian/homeserver/PendingAuthorisation.hpp" +#include "merovingian/homeserver/PendingAuthorisationKind.hpp" #include "merovingian/homeserver/PendingAuthorisationStore.hpp" #include "merovingian/oauth/AccountFormInput.hpp" #include "merovingian/oauth/ApplicationType.hpp" @@ -36,6 +39,7 @@ #include "merovingian/oauth/FormContentType.hpp" #include "merovingian/oauth/FormPostOrigin.hpp" #include "merovingian/oauth/GrantedScope.hpp" +#include "merovingian/oauth/HandOffRedirect.hpp" #include "merovingian/oauth/HtmlText.hpp" #include "merovingian/oauth/OAuthBaseUrl.hpp" #include "merovingian/oauth/OAuthErrorCodes.hpp" @@ -81,6 +85,8 @@ namespace constexpr auto status_too_many_requests = std::uint16_t{429U}; constexpr auto status_server_error = std::uint16_t{500U}; constexpr auto status_unavailable = std::uint16_t{503U}; + // A hand-off's login token: 32 random bytes, as get_token mints, and redeemable for 30 seconds (ADR-0802). + constexpr auto login_token_bytes = std::size_t{32U}; // The longest username read from the login form: a user ID is at most 255 bytes, so no account has a longer one. constexpr auto max_login_username_bytes = std::size_t{255U}; @@ -208,6 +214,31 @@ namespace return ClientTarget{std::move(*metadata), std::move(*matched)}; } + [[nodiscard]] auto is_hand_off(PendingAuthorisation const& entry) noexcept -> bool + { + return entry.kind == PendingAuthorisationKind::login_token_hand_off; + } + + // A hand-off's `redirectUrl` read again under the rules and the allowlist in force now, for the confirmation page + // and the final redirect. nullopt when it no longer passes. + [[nodiscard]] auto hand_off_target(HomeserverRuntime const& runtime, PendingAuthorisation const& entry) + -> std::optional + { + return oauth::hand_off_redirect_target(entry.redirect_uri, + runtime.config.server().oauth.hand_off_redirect_allowlist); + } + + auto log_hand_off(std::string_view event, std::string_view user_id, observability::LogEventSeverity severity) + -> void + { + auto fields = std::vector{}; + if (!user_id.empty()) + { + fields.push_back({"user_id", std::string{user_id}, false}); + } + log_oauth(event, std::move(fields), severity); + } + // What every form post of one pending authorisation shares. struct FormPost final { @@ -268,6 +299,18 @@ namespace [[nodiscard]] auto consent_response(FormPost const& post, std::string_view user_id) -> LocalHttpResponse { auto const& runtime = post.runtime.homeserver; + if (is_hand_off(post.entry)) + { + // The confirmation page (ADR-0802): it names the account and where the browser goes, and its policy allows + // the redirect to that address alone. + auto const destination = hand_off_target(runtime, post.entry); + if (!destination.has_value()) + { + return expired_page(); + } + return oauth_page_response(status_ok, oauth::hand_off_page(post.pending_id, user_id, *destination), + oauth::page_headers(*destination)); + } auto const target = client_target(runtime, post.entry); if (!target.has_value()) { @@ -452,6 +495,62 @@ namespace return authenticated(post, created.value); } + // `approve` of a hand-off, its entry already spent: the account is judged again, and a single-use login token for + // the user is minted into the store get_token uses and added to the `redirectUrl` (ADR-0802). Refusals are pages: + // the address is the application's, and an error there would mean nothing to it. + [[nodiscard]] auto finish_hand_off(ClientServerRuntime& rt, PendingAuthorisation const& consumed) + -> LocalHttpResponse + { + auto& runtime = rt.homeserver; + auto const target = hand_off_target(runtime, consumed); + if (!target.has_value()) + { + return expired_page(); + } + if (account_sign_in_gate(runtime, consumed.user_id, {}) != Outcome::verified) + { + log_hand_off("oauth.hand_off.refused", consumed.user_id, observability::LogEventSeverity::info); + return oauth_error_page_response(status_forbidden, oauth::HtmlText{"Sign-in refused"}, + oauth::HtmlText{"This account cannot sign in."}); + } + auto const unavailable = []() { + return oauth_error_page_response( + status_unavailable, oauth::HtmlText{"Sign-in is not available"}, + oauth::HtmlText{"The server cannot complete the sign-in now. Try again later."}); + }; + auto const token = crypto::secure_random_hex(login_token_bytes); + auto token_hash = token.has_value() ? LoginTokenStore::token_hash(*token) : std::nullopt; + if (!token_hash.has_value()) + { + return unavailable(); + } + auto const issued = rt.login_tokens.issue(consumed.user_id, std::move(*token_hash), oauth_wall_clock_ms(), + hand_off_login_token_lifetime_ms, rt.limits.max_login_tokens_per_user, + rt.limits.max_login_tokens); + if (issued.outcome != LoginTokenStore::IssueOutcome::issued) + { + log_hand_off("oauth.hand_off.refused", consumed.user_id, observability::LogEventSeverity::info); + return unavailable(); + } + auto const address = oauth::hand_off_return_address(*target, *token); + if (!address.has_value()) + { + return unavailable(); + } + log_hand_off("oauth.hand_off.granted", consumed.user_id, observability::LogEventSeverity::info); + append_local_audit(runtime.database, observability::AuditCategory::auth, "auth.login_token.issued", + consumed.user_id, {}, "hand_off"); + auto response = LocalHttpResponse{}; + response.status = status_see_other; + response.headers = { + {"Location", *address }, + {"Cache-Control", "no-store" }, + {"Referrer-Policy", "no-referrer"}, + }; + response.page = true; + return response; + } + // `approve`: the entry must hold a verified user. It is spent, the account is judged again, and a code bound to the // whole request and the user is sent to the client. [[nodiscard]] auto handle_approve(FormPost const& post) -> LocalHttpResponse @@ -467,6 +566,10 @@ namespace { return expired_page(); } + if (is_hand_off(*consumed)) + { + return finish_hand_off(post.runtime, *consumed); + } auto const target = client_target(runtime, *consumed); if (!target.has_value()) { @@ -523,6 +626,12 @@ namespace { return expired_page(); } + if (is_hand_off(*consumed)) + { + // Nothing is sent to the application: the browser stays on this server (ADR-0802). + log_hand_off("oauth.hand_off.cancelled", consumed->user_id, observability::LogEventSeverity::info); + return oauth_plain_page(status_ok, oauth::hand_off_cancelled_page()); + } auto const target = client_target(runtime, *consumed); if (!target.has_value()) { @@ -624,7 +733,7 @@ namespace oauth::HtmlText{"This form asked for something this page does not do."}); } - // What the `prompt` parameter asks the first page to be. + // What the `prompt` parameter (or the hand-off's `action`) asks the first page to be. enum class FirstPage : std::uint8_t { login, @@ -632,6 +741,69 @@ namespace registration_closed, }; + // The first page of a sign-in and whether the sign-in started: false when no cookie could be made or the store + // refused the entry, and the page says so. + struct SignInStart final + { + LocalHttpResponse response; + bool started{false}; + }; + + // Binds `authorisation` to this browser's cookie (reused when the request carries a well-formed one, else fresh), + // stores it and answers the first page with the cookie. Shared by the authorisation request and the hand-off. + [[nodiscard]] auto start_sign_in(ClientServerRuntime& rt, LocalHttpRequest const& request, + PendingAuthorisation authorisation, FirstPage first_page) -> SignInStart + { + auto& runtime = rt.homeserver; + auto browser_token = request_secret_cookie(request, oauth_browser_cookie_name); + if (!browser_token.has_value()) + { + browser_token = make_oauth_secret(); + } + auto const cookie = browser_token.has_value() + ? core::host_cookie(oauth_browser_cookie_name, *browser_token, + core::CookieSameSite::lax, oauth_browser_cookie_max_age_seconds) + : std::variant{core::Error{}}; + auto const* set_cookie = std::get_if(&cookie); + if (set_cookie == nullptr) + { + return SignInStart{ + oauth_error_page_response(status_unavailable, oauth::HtmlText{"Sign-in is not available"}, + oauth::HtmlText{"The server cannot start a sign-in now. Try again later."}), + false}; + } + auto const hint = authorisation.login_hint; + auto created = runtime.oauth_pending_authorisations.create( + std::move(authorisation), *browser_token, rate_limit_client_key(request, runtime.config.server()), + oauth_wall_clock_ms()); + auto const* pending_id = std::get_if(&created); + if (pending_id == nullptr) + { + return SignInStart{oauth_error_page_response( + status_unavailable, oauth::HtmlText{"Sign-in is not available"}, + oauth::HtmlText{"Too many sign-ins are in progress. Try again in a few minutes."}), + false}; + } + auto response = std::invoke([&]() { + if (first_page == FirstPage::registration) + { + return registration_page_response(status_ok, registration_form_input(runtime, *pending_id)); + } + auto input = login_form_input(runtime, *pending_id); + if (hint.has_value()) + { + input.username = *hint; + } + if (first_page == FirstPage::registration_closed) + { + input.notice = registration_closed_notice(); + } + return login_page_response(status_ok, input); + }); + response.headers.emplace_back("Set-Cookie", *set_cookie); + return SignInStart{std::move(response), true}; + } + [[nodiscard]] auto handle_get(ClientServerRuntime& rt, LocalHttpRequest const& request) -> LocalHttpResponse { auto& runtime = rt.homeserver; @@ -733,22 +905,6 @@ namespace auto const hint = login_hint_username(fields->find("login_hint"), server_name); // Step 3: bind a pending authorisation to this browser. - auto browser_token = request_secret_cookie(request, oauth_browser_cookie_name); - if (!browser_token.has_value()) - { - browser_token = make_oauth_secret(); - } - auto const cookie = browser_token.has_value() - ? core::host_cookie(oauth_browser_cookie_name, *browser_token, - core::CookieSameSite::lax, oauth_browser_cookie_max_age_seconds) - : std::variant{core::Error{}}; - auto const* set_cookie = std::get_if(&cookie); - if (set_cookie == nullptr) - { - return oauth_error_page_response( - status_unavailable, oauth::HtmlText{"Sign-in is not available"}, - oauth::HtmlText{"The server cannot start a sign-in now. Try again later."}); - } auto authorisation = PendingAuthorisation{}; authorisation.client_id = std::string{*client_id}; authorisation.redirect_uri = std::string{*requested_redirect}; @@ -762,16 +918,11 @@ namespace { authorisation.login_hint = *hint; } - auto created = runtime.oauth_pending_authorisations.create( - std::move(authorisation), *browser_token, rate_limit_client_key(request, runtime.config.server()), - oauth_wall_clock_ms()); - auto const* pending_id = std::get_if(&created); - if (pending_id == nullptr) + auto start = start_sign_in(rt, request, std::move(authorisation), first_page); + if (!start.started) { log_refused(*client_id, oauth::error_temporarily_unavailable); - return oauth_error_page_response( - status_unavailable, oauth::HtmlText{"Sign-in is not available"}, - oauth::HtmlText{"Too many sign-ins are in progress. Try again in a few minutes."}); + return std::move(start.response); } log_oauth("oauth.authorization.started", { @@ -779,29 +930,52 @@ namespace {"application_type", std::string{application_type_name(metadata->application_type())}, false} }, observability::LogEventSeverity::debug); - - auto response = std::invoke([&]() { - if (first_page == FirstPage::registration) - { - return registration_page_response(status_ok, registration_form_input(runtime, *pending_id)); - } - auto input = login_form_input(runtime, *pending_id); - if (hint.has_value()) - { - input.username = *hint; - } - if (first_page == FirstPage::registration_closed) - { - input.notice = registration_closed_notice(); - } - return login_page_response(status_ok, input); - }); - response.headers.emplace_back("Set-Cookie", *set_cookie); - return response; + return std::move(start.response); } } // namespace +auto handle_login_hand_off(ClientServerRuntime& rt, LocalHttpRequest const& request) -> LocalHttpResponse +{ + auto& runtime = rt.homeserver; + auto parsed = core::FormFields::parse(request_target_query(request.target)); + auto const* fields = std::get_if(&parsed); + if (fields == nullptr) + { + log_hand_off("oauth.hand_off.refused", {}, observability::LogEventSeverity::debug); + return bad_request_page(oauth::HtmlText{"The request is malformed. Return to the application and try again."}); + } + auto const redirect_url = fields->find("redirectUrl"); + if (!redirect_url.has_value() || redirect_url->empty()) + { + log_hand_off("oauth.hand_off.refused", {}, observability::LogEventSeverity::debug); + return bad_request_page(oauth::HtmlText{"The application did not say where to return after the sign-in. " + "Return to the application and try again."}); + } + // Read here only to refuse; the entry keeps the text and every later step reads it again (ADR-0802). + if (!oauth::hand_off_redirect_target(*redirect_url, runtime.config.server().oauth.hand_off_redirect_allowlist) + .has_value()) + { + log_hand_off("oauth.hand_off.refused", {}, observability::LogEventSeverity::debug); + return bad_request_page(oauth::HtmlText{"The application asked to return to an address this server does not " + "send sign-ins to. Return to the application and try again."}); + } + // Spec `GET /login/sso/redirect`: `action` is `login` or `register`; anything else, or none, is a login. + auto first_page = FirstPage::login; + if (fields->find("action") == std::optional{"register"}) + { + first_page = registration_enabled(runtime) ? FirstPage::registration : FirstPage::registration_closed; + } + auto authorisation = PendingAuthorisation{}; + authorisation.kind = PendingAuthorisationKind::login_token_hand_off; + authorisation.redirect_uri = std::string{*redirect_url}; + authorisation.create_account = first_page != FirstPage::login; + auto start = start_sign_in(rt, request, std::move(authorisation), first_page); + log_hand_off(start.started ? "oauth.hand_off.started" : "oauth.hand_off.refused", {}, + observability::LogEventSeverity::debug); + return std::move(start.response); +} + auto handle_oauth_authorize(ClientServerRuntime& runtime, LocalHttpRequest const& request) -> LocalHttpResponse { if (request.method == "POST") diff --git a/src/oauth/AGENTS.md b/src/oauth/AGENTS.md index dd2eecef5..383ae68f8 100644 --- a/src/oauth/AGENTS.md +++ b/src/oauth/AGENTS.md @@ -26,6 +26,7 @@ Pure functions and value types for the built-in OAuth 2.0 API | `AuthorizationPages.cpp`, `AccountFormInput.hpp`, `ConsentPageInput.hpp` | The login, registration, consent and error pages of `/_merovingian/oauth2/authorize`, and the form field and action names they post. A value `HtmlText::escape` refuses is replaced by fixed text | | `AccountPages.cpp`, `AccountPageFrame.hpp`, `AccountDeviceRow.hpp`, `AccountSignInInput.hpp` | The account pages of `/_merovingian/account` (ADR-0796): sign-in, overview, devices, one device, device sign-out, password, deactivation, cross-signing reset and result pages; the six spec actions (`account_management_actions`, `account_management_action`, `account_action_takes_device`), `account_action_address` (every link, the post-sign-in redirect and the `m.oauth` URL), and the form field and action names. Every signed-in form carries `form_token`; a page whose token cannot be shown holds no form | | `FormPostOrigin.cpp` | `form_post_origin`, `form_post_origin_is_accepted`: a page's form post must name this server's origin exactly, and `Sec-Fetch-Site`, when sent, `same-origin` (ADR-0784) | +| `HandOffRedirect.cpp` | `hand_off_redirect_target` (`https`, loopback `http` or a private-use scheme, then the allowlist) and `hand_off_return_address` (every `loginToken` removed, the new one added) for the legacy SSO redirect's hand-off (ADR-0802) | | `HandOffAllowlist.cpp` | `hand_off_allowlist_entry_error`, `hand_off_allowlist_error`: an https origin or a bare private-use scheme, at most 32, each once (ADR-0774) | | `FormContentType.cpp` | `api_form_content_type_is_accepted`: the token and revocation endpoints take `application/x-www-form-urlencoded` only, with at most a `charset=utf-8` parameter | | `AccessTokenLifetime.hpp` | `access_token_lifetime_ms` (the configured lifetime, or one hour when it is 0: an OAuth access token always expires, ADR-0791) and `expires_in_seconds` | @@ -76,9 +77,12 @@ Pure functions and value types for the built-in OAuth 2.0 API `[oauth][server_metadata]`), `test_oauth_hand_off_allowlist.cpp` (`[oauth][allowlist]`), `test_oauth_form_post_origin.cpp` (`[oauth][form-origin]`), `test_oauth_page_response.cpp` (`[oauth][page-response]`), `test_oauth_authorization_redirect.cpp` (`[oauth][redirect-address]`), -`test_oauth_authorization_pages.cpp` (`[oauth][authorize-page]`), `test_oauth_account_pages.cpp` -(`[oauth][account-page]`). The account pages: `tests/conformance/test_oauth_account_management_conformance.cpp` and -`tests/integration/test_oauth_account_pages_flow.cpp` (`[oauth-account]`, `[oauth-uia]`). The authorisation endpoint: +`test_oauth_authorization_pages.cpp` (`[oauth][authorize-page]`), `test_oauth_hand_off_redirect.cpp` +(`[oauth][hand-off-redirect]`), `test_oauth_account_pages.cpp` (`[oauth][account-page]`). The account pages: +`tests/conformance/test_oauth_account_management_conformance.cpp` and +`tests/integration/test_oauth_account_pages_flow.cpp` (`[oauth-account]`, `[oauth-uia]`). The hand-off: +`tests/conformance/test_oauth_aware_clients_conformance.cpp` and `tests/integration/test_oauth_login_hand_off_flow.cpp` +(`[hand-off]`). The authorisation endpoint: `tests/conformance/test_oauth_authorization_conformance.cpp` and `tests/integration/test_oauth_authorization_flow.cpp` (`[oauth-authorize]`). The served document: `tests/conformance/test_oauth_metadata_conformance.cpp` and `tests/integration/test_oauth_metadata_flow.cpp` diff --git a/src/oauth/AuthorizationPages.cpp b/src/oauth/AuthorizationPages.cpp index 526d9fa42..690481543 100644 --- a/src/oauth/AuthorizationPages.cpp +++ b/src/oauth/AuthorizationPages.cpp @@ -3,6 +3,7 @@ #include "merovingian/oauth/AuthorizationPages.hpp" +#include "merovingian/oauth/AsciiCase.hpp" #include "merovingian/oauth/HtmlLiteral.hpp" #include "merovingian/oauth/OAuthPaths.hpp" #include "merovingian/oauth/PageDetail.hpp" @@ -100,13 +101,14 @@ namespace // private-use scheme (which names the application, since it is the reversed host of its client URI). [[nodiscard]] auto destination_of(ParsedUri const& target) -> HtmlText { - auto const& scheme = target.scheme(); + // A scheme's case is not significant (RFC 3986 section 3.1): `HTTPS://host` is shown as its host. + auto const scheme = ascii_lower(target.scheme()); auto const web = scheme == "https" || scheme == "http"; if (web && target.has_authority()) { return shown(target.host(), "an address that cannot be shown"); } - auto text = scheme; + auto text = target.scheme(); text.append(": (an application on your device)"); return shown(text, "an address that cannot be shown"); } @@ -212,6 +214,38 @@ auto consent_page(ConsentPageInput const& input, ParsedUri const& redirect_targe return page; } +auto hand_off_page(std::string_view pending_id, std::string_view user_id, ParsedUri const& target) -> Page +{ + auto page = Page{HtmlText{"Sign in to an application"}}; + auto const details = std::array{ + PageDetail{HtmlText{"Account"}, shown(user_id, "an account that cannot be shown")}, + PageDetail{HtmlText{"Application"}, destination_of(target)}, + }; + page.details(details); + page.paragraph(HtmlText{"If you continue, this application is signed in to your account and gets full access to " + "it: it can read and send your messages, join and leave rooms and change your settings, " + "as you can. Continue only if you started this sign-in from that application."}); + auto const pending = pending_value(pending_id); + if (!pending.has_value()) + { + add_cannot_continue(page); + return page; + } + auto form = PageForm{authorize_path}; + form.hidden(pending_field, *pending); + std::ignore = form.button(SubmitButton{action_field, action_approve, HtmlText{"Continue"}}); + std::ignore = form.button(SubmitButton{action_field, action_deny, HtmlText{"Cancel"}}); + std::ignore = page.form(form); + return page; +} + +auto hand_off_cancelled_page() -> Page +{ + auto page = Page{HtmlText{"Sign-in cancelled"}}; + page.paragraph(HtmlText{"The application was not signed in. You can close this page."}); + return page; +} + auto error_page(HtmlText title, HtmlText const& message) -> Page { auto page = Page{std::move(title)}; diff --git a/src/oauth/HandOffRedirect.cpp b/src/oauth/HandOffRedirect.cpp new file mode 100644 index 000000000..4ab42e3f2 --- /dev/null +++ b/src/oauth/HandOffRedirect.cpp @@ -0,0 +1,129 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/oauth/HandOffRedirect.hpp" + +#include "merovingian/oauth/AsciiCase.hpp" +#include "merovingian/oauth/AuthorizationRedirect.hpp" +#include "merovingian/oauth/ResponseMode.hpp" + +#include +#include +#include +#include +#include + +namespace merovingian::oauth +{ +namespace +{ + + constexpr auto default_https_port = std::uint16_t{443U}; + constexpr auto login_token_parameter = std::string_view{"loginToken"}; + + [[nodiscard]] auto is_loopback_host(std::string_view host) -> bool + { + auto const lower = ascii_lower(host); + return lower == "localhost" || lower == "127.0.0.1" || lower == "[::1]"; + } + + // Whether `target`'s scheme (already in lower case as `scheme`) is one the hand-off may send a browser to. + [[nodiscard]] auto scheme_is_accepted(ParsedUri const& target, std::string_view scheme) -> bool + { + if (scheme == "https") + { + return target.has_authority(); + } + if (scheme == "http") + { + return target.has_authority() && is_loopback_host(target.host()); + } + return scheme.find('.') != std::string_view::npos; + } + + [[nodiscard]] auto matches_entry(ParsedUri const& target, std::string_view scheme, std::string_view entry) -> bool + { + auto parsed = ParsedUri::read(entry); + auto const* entry_uri = std::get_if(&parsed); + if (entry_uri == nullptr) + { + return false; + } + if (!entry_uri->has_authority()) + { + // A bare private-use scheme and its colon. + return scheme == ascii_lower(entry_uri->scheme()); + } + return scheme == "https" && target.has_authority() && + ascii_lower(target.host()) == ascii_lower(entry_uri->host()) && + target.port().value_or(default_https_port) == entry_uri->port().value_or(default_https_port); + } + +} // namespace + +auto hand_off_redirect_target(std::string_view redirect_url, std::span allowlist) + -> std::optional +{ + auto parsed = ParsedUri::read(redirect_url); + auto* target = std::get_if(&parsed); + if (target == nullptr) + { + return std::nullopt; + } + auto const scheme = ascii_lower(target->scheme()); + if (!scheme_is_accepted(*target, scheme)) + { + return std::nullopt; + } + if (!allowlist.empty() && std::ranges::none_of(allowlist, [&](std::string const& entry) { + return matches_entry(*target, scheme, entry); + })) + { + return std::nullopt; + } + return std::move(*target); +} + +auto hand_off_return_address(ParsedUri const& target, std::string_view login_token) -> std::optional +{ + auto const& text = target.text(); + auto address = std::string{text.substr(0U, text.find('?'))}; + if (target.has_query()) + { + auto kept = std::string{}; + auto query = std::string_view{target.query()}; + while (true) + { + auto const end = std::min(query.find('&'), query.size()); + auto const parameter = query.substr(0U, end); + auto const name = parameter.substr(0U, std::min(parameter.find('='), parameter.size())); + if (name != login_token_parameter) + { + if (!kept.empty()) + { + kept.push_back('&'); + } + kept.append(parameter); + } + if (end == query.size()) + { + break; + } + query.remove_prefix(end + 1U); + } + address.push_back('?'); + address.append(kept); + } + auto reread = ParsedUri::read(address); + auto const* without_tokens = std::get_if(&reread); + if (without_tokens == nullptr) + { + return std::nullopt; + } + auto const parameters = std::array{ + RedirectParameter{login_token_parameter, login_token} + }; + return authorization_redirect_address(*without_tokens, ResponseMode::query, parameters); +} + +} // namespace merovingian::oauth diff --git a/src/oauth/meson.build b/src/oauth/meson.build index eeb8fb874..d539838c7 100644 --- a/src/oauth/meson.build +++ b/src/oauth/meson.build @@ -9,6 +9,7 @@ oauth_sources = files( 'FormContentType.cpp', 'FormPostOrigin.cpp', 'HandOffAllowlist.cpp', + 'HandOffRedirect.cpp', 'HtmlText.cpp', 'OAuthBaseUrl.cpp', 'Page.cpp', diff --git a/tests/conformance/AGENTS.md b/tests/conformance/AGENTS.md index 195f66a20..0e4078f62 100644 --- a/tests/conformance/AGENTS.md +++ b/tests/conformance/AGENTS.md @@ -66,6 +66,7 @@ Every test in this directory directly encodes a **MUST** or **SHOULD** from the | `test_oauth_account_management_conformance.cpp` | [CS API § Account management](../../docs/matrix-v1.19-spec/client-server-api.md#account-management-url-discovery) · [§ OAuth authentication](../../docs/matrix-v1.19-spec/client-server-api.md#oauth-authentication) (`account_management_uri` and the six actions; `action` and `device_id` on `/_merovingian/account`, the device ignored by the actions that take none; a replacing cross-signing upload from an OAuth session is a 401 with the `m.oauth` flow and the `org.matrix.cross_signing_reset` URL, completed by the `session` alone after the approval) | | `test_oauth_token_conformance.cpp` | [CS API § Refresh token grant](../../docs/matrix-v1.19-spec/client-server-api.md#refresh-token-grant) · [§ Token revocation](../../docs/matrix-v1.19-spec/client-server-api.md#token-revocation) (`/_merovingian/oauth2/token` and `/revoke`: an access token always expires; a lost refresh answer can be retried and the old token is refused once the new one is used; revocation ends both tokens whatever the `client_id` and answers 200 for an unknown token) | | `test_oauth_legacy_api_conformance.cpp` | [CS API § Authentication API discovery](../../docs/matrix-v1.19-spec/client-server-api.md#authentication-api-discovery) · [`GET /login`](../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv3login) · [`POST /login`](../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3login) · [`POST /register`](../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3register) (without the legacy API: `GET /login` 404 `M_UNRECOGNIZED`, `m.login.application_service` and an appservice registration without `inhibit_login` 400 `M_APPSERVICE_LOGIN_UNSUPPORTED`, an appservice registration with it served, a user's registration 403) | +| `test_oauth_aware_clients_conformance.cpp` | [CS API § OAuth 2.0 aware clients](../../docs/matrix-v1.19-spec/client-server-api.md#oauth-20-aware-clients) · [`GET /login/sso/redirect`](../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv3loginssoredirect) · [§ Client login via SSO](../../docs/matrix-v1.19-spec/client-server-api.md#client-login-via-sso) (with the OAuth 2.0 API and the legacy API on: `m.login.sso` with `oauth_aware_preferred: true` beside `m.login.password`; `action=register` and `action=login`; a confirmation naming the site before one fresh `loginToken` replaces any in `redirectUrl`) | | `test_oauth_client_registration_conformance.cpp` | [CS API § Client registration](../../docs/matrix-v1.19-spec/client-server-api.md#client-registration) · [§ Client metadata](../../docs/matrix-v1.19-spec/client-server-api.md#client-metadata) · [§ Redirect URI validation](../../docs/matrix-v1.19-spec/client-server-api.md#redirect-uri-validation) · [§ Dynamic client registration flow](../../docs/matrix-v1.19-spec/client-server-api.md#dynamic-client-registration-flow) (`POST /_merovingian/oauth2/register`: 201 with `client_id` and the registered metadata, web and native, `none`, unknown values ignored, the spec's redirect URI examples, a client with a session never deleted) | | `test_pdu_format_conformance.cpp` | [SS API § PDUs](../../docs/matrix-v1.19-spec/server-server-api.md#pdus) | | `test_pdu_ingestion_conformance.cpp` | [SS API § Checks performed on receipt of a PDU](../../docs/matrix-v1.19-spec/server-server-api.md#checks-performed-on-receipt-of-a-pdu) · [Room v12 § State resolution](../../docs/matrix-v1.19-spec/rooms/v12.md) (auth_events selection: m.room.create MUST NOT be selected) · [§ Calculating the reference hash](../../docs/matrix-v1.19-spec/server-server-api.md#calculating-the-reference-hash-for-an-event) (a received PDU is stored without its `unsigned`, under an unchanged event ID) | diff --git a/tests/conformance/test_oauth_aware_clients_conformance.cpp b/tests/conformance/test_oauth_aware_clients_conformance.cpp new file mode 100644 index 000000000..741c54a4f --- /dev/null +++ b/tests/conformance/test_oauth_aware_clients_conformance.cpp @@ -0,0 +1,192 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// +-------------------------------------------------------------------------+ +// | OAUTH 2.0 AWARE CLIENTS CONFORMANCE | +// | | +// | Spec: Matrix Client-Server API v1.19 — "OAuth 2.0 aware clients", | +// | "GET /login", "GET /login/sso/redirect", "Client login via SSO" | +// | URL: ../../docs/matrix-v1.19-spec/client-server-api.md | +// +-------------------------------------------------------------------------+ +// +// What a server with the OAuth 2.0 API and the legacy API both on offers clients that know only the legacy API (plan +// P10, ADR-0802). + +#include "../support/JsonTestSupport.hpp" +#include "../support/OAuthAuthorizationSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "../support/RegistrationToken.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/oauth/AuthorizationRedirect.hpp" + +#include + +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace hs = merovingian::homeserver; + +constexpr auto alice_password = std::string_view{"AlicePass99!x"}; + +[[nodiscard]] auto start_with_hand_off() -> hs::ClientServerStartResult +{ + auto config = oauth_registration_config(); + config.server().server_name = "example.org"; + enable_token_registration(config.security()); + auto started = hs::start_client_server(std::move(config)); + REQUIRE(started.started); + started.runtime.rate_limit_engine.reset(); + REQUIRE( + hs::register_local_user(started.runtime.homeserver, "alice", alice_password, std::string{registration_token}) + .ok); + return started; +} + +[[nodiscard]] auto get(hs::ClientServerRuntime& rt, std::string target, BrowserContext const& browser = {}) + -> hs::LocalHttpResponse +{ + return authorize_request(rt, "GET", std::move(target), {}, browser); +} + +[[nodiscard]] auto contains(std::string_view text, std::string_view part) -> bool +{ + return text.find(part) != std::string_view::npos; +} + +[[nodiscard]] auto count_occurrences(std::string_view text, std::string_view part) -> std::size_t +{ + auto found = std::size_t{0U}; + for (auto at = text.find(part); at != std::string_view::npos; at = text.find(part, at + 1U)) + { + ++found; + } + return found; +} + +} // namespace + +// Spec: CS API v1.19 "OAuth 2.0 aware clients", Server behaviour: the homeserver MUST "Provide an implementation of the +// m.login.sso authentication flow", "If password authentication was previously enabled on the homeserver then provide +// an implementation of the m.login.password authentication flow", and "Indicate that the m.login.sso flow is preferred +// by setting oauth_aware_preferred to true." +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#oauth-20-aware-clients +SCENARIO("GET /login offers m.login.sso with oauth_aware_preferred and keeps m.login.password", + "[oauth][hand-off][conformance]") +{ + GIVEN("a server with the OAuth 2.0 API and the legacy API on") + { + auto started = start_with_hand_off(); + + WHEN("GET /login is read") + { + auto const response = get(started.runtime, "/_matrix/client/v3/login"); + + THEN("m.login.sso is preferred, and m.login.password and m.login.token are offered") + { + REQUIRE(response.status == 200U); + REQUIRE(contains(response.body, R"("type":"m.login.sso")")); + REQUIRE(contains(response.body, R"("oauth_aware_preferred":true)")); + REQUIRE(contains(response.body, R"("type":"m.login.password")")); + REQUIRE(contains(response.body, R"("type":"m.login.token")")); + } + } + } +} + +// Spec: CS API v1.19 "OAuth 2.0 aware clients", Server behaviour: the homeserver MUST "Support a value for the action +// param on the SSO redirect endpoints." "GET /login/sso/redirect", `action`: "login: the SSO redirect is for the +// purposes of signing an existing user in. register: the SSO redirect is for the purpose of registering a new user +// account." +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv3loginssoredirect +SCENARIO("The SSO redirect starts registration for action=register and sign-in for action=login", + "[oauth][hand-off][conformance]") +{ + GIVEN("a server with the hand-off on and registration open") + { + auto started = start_with_hand_off(); + auto const base = std::string{"/_matrix/client/v3/login/sso/redirect?redirectUrl=io.element.app%3A%2Fcb"}; + + WHEN("the redirect is opened with each action") + { + auto const registering = get(started.runtime, base + "&action=register"); + auto const signing_in = get(started.runtime, base + "&action=login"); + + THEN("register shows the registration form and login the sign-in form") + { + REQUIRE(registering.status == 200U); + REQUIRE(contains(registering.body, R"(name="password_confirm")")); + REQUIRE(signing_in.status == 200U); + REQUIRE(contains(signing_in.body, R"(autocomplete="current-password")")); + REQUIRE_FALSE(contains(signing_in.body, R"(name="password_confirm")")); + } + } + } +} + +// Spec: CS API v1.19 "Client login via SSO", Security considerations: "Homeservers SHOULD confirm with the user that +// they are happy to grant access to their matrix account to the site named in the redirectUrl." Handling the callback, +// step 4: "If it already includes one or more loginToken parameters, they should be removed before adding the new +// one." +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#client-login-via-sso +SCENARIO("The hand-off confirms the destination before it adds exactly one loginToken", + "[oauth][hand-off][conformance][security]") +{ + GIVEN("a sign-in started for a redirectUrl holding a stale loginToken") + { + auto started = start_with_hand_off(); + auto& rt = started.runtime; + auto browser = BrowserContext{}; + auto const opened = + get(rt, + "/_matrix/client/v3/login/sso/redirect?redirectUrl=" + + merovingian::oauth::percent_encode_redirect_value("https://app.example.com/cb?loginToken=stale"), + browser); + REQUIRE(opened.status == 200U); + browser.cookie = cookie_of(opened); + auto const pending = pending_of(opened); + + WHEN("alice signs in, then continues") + { + auto const confirmation = post_authorize(rt, + { + {"pending", pending }, + {"action", "login" }, + {"username", "alice" }, + {"password", std::string{alice_password}}, + }, + browser); + auto const approved = post_authorize(rt, + { + {"pending", pending }, + {"action", "approve"}, + }, + browser); + auto const answer = redirect_answer(approved); + + THEN("a confirmation naming the site comes first, and the redirect carries one fresh loginToken") + { + REQUIRE(confirmation.status == 200U); + REQUIRE(contains(confirmation.body, "app.example.com")); + REQUIRE(response_header(confirmation, "Location").empty()); + REQUIRE(approved.status == 303U); + REQUIRE(answer.base == "https://app.example.com/cb"); + REQUIRE(answer.parameters.size() == 1U); + REQUIRE(answer.parameters.contains("loginToken")); + REQUIRE(answer.parameters.at("loginToken") != "stale"); + REQUIRE(count_occurrences(response_header(approved, "Location"), "loginToken=") == 1U); + } + } + } +} diff --git a/tests/integration/test_oauth_login_hand_off_flow.cpp b/tests/integration/test_oauth_login_hand_off_flow.cpp new file mode 100644 index 000000000..7a67edaf9 --- /dev/null +++ b/tests/integration/test_oauth_login_hand_off_flow.cpp @@ -0,0 +1,405 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The legacy login hand-off through the client-server dispatcher (plan P10, ADR-0802): with the OAuth 2.0 API and the +// legacy API both on, `GET /login` prefers `m.login.sso`, and the SSO redirect starts the built-in pages, which end +// in a confirmation and a single-use login token added to `redirectUrl`. No browser runs here: what a browser does +// with the cookie, the policy or the redirect is not tested. + +#include "../support/JsonTestSupport.hpp" +#include "../support/OAuthAuthorizationSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "../support/RegistrationToken.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include +#include + +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace hs = merovingian::homeserver; +using Fields = std::vector>; + +constexpr auto alice_password = std::string_view{"AlicePass99!x"}; +constexpr auto sso_redirect_path = std::string_view{"/_matrix/client/v3/login/sso/redirect"}; +constexpr auto app_return = std::string_view{"https://app.example.com/cb?a=1&loginToken=stale"}; + +[[nodiscard]] auto hand_off_config(bool oauth_enabled = true, std::vector allowlist = {}) + -> merovingian::config::Config +{ + auto config = oauth_registration_config(oauth_enabled); + config.server().server_name = "example.org"; + config.server().oauth.hand_off_redirect_allowlist = std::move(allowlist); + enable_token_registration(config.security()); + return config; +} + +[[nodiscard]] auto start(merovingian::config::Config config) -> hs::ClientServerStartResult +{ + auto started = hs::start_client_server(std::move(config)); + REQUIRE(started.started); + // Every request comes from one address; the built-in limits are not what this file tests. + started.runtime.rate_limit_engine.reset(); + REQUIRE( + hs::register_local_user(started.runtime.homeserver, "alice", alice_password, std::string{registration_token}) + .ok); + return started; +} + +[[nodiscard]] auto contains(std::string_view text, std::string_view part) -> bool +{ + return text.find(part) != std::string_view::npos; +} + +[[nodiscard]] auto audit_count(hs::HomeserverRuntime const& runtime, std::string_view event_type) -> std::size_t +{ + auto count = std::size_t{0U}; + for (auto const& event : runtime.database.audit_events) + { + if (event.event_type == event_type) + { + ++count; + } + } + return count; +} + +[[nodiscard]] auto send(hs::ClientServerRuntime& rt, std::string method, std::string target, std::string body = {}) + -> hs::LocalHttpResponse +{ + return hs::handle_client_server_request(rt, {std::move(method), std::move(target), {}, std::move(body)}, + /*can_wait=*/false) + .response; +} + +// A started hand-off: the redirect's answer, the pending identifier and the browser it is bound to. +struct HandOff final +{ + hs::LocalHttpResponse response; + std::string pending; + BrowserContext browser; +}; + +[[nodiscard]] auto open_hand_off(hs::ClientServerRuntime& rt, Fields const& parameters, + std::string_view path = sso_redirect_path) -> HandOff +{ + auto browser = BrowserContext{}; + auto response = authorize_request(rt, "GET", std::string{path} + "?" + form_encode(parameters), {}, browser); + auto pending = pending_of(response); + browser.cookie = cookie_of(response); + return {std::move(response), std::move(pending), std::move(browser)}; +} + +[[nodiscard]] auto post(hs::ClientServerRuntime& rt, HandOff const& hand_off, Fields fields) -> hs::LocalHttpResponse +{ + fields.emplace_back("pending", hand_off.pending); + return post_authorize(rt, fields, hand_off.browser); +} + +[[nodiscard]] auto sign_in(hs::ClientServerRuntime& rt, HandOff const& hand_off) -> hs::LocalHttpResponse +{ + return post(rt, hand_off, + { + {"action", "login" }, + {"username", "alice" }, + {"password", std::string{alice_password}}, + }); +} + +[[nodiscard]] auto token_login(hs::ClientServerRuntime& rt, std::string_view token) -> hs::LocalHttpResponse +{ + return send(rt, "POST", "/_matrix/client/v3/login", + R"({"type":"m.login.token","token":")" + std::string{token} + R"("})"); +} + +} // namespace + +SCENARIO("With the OAuth 2.0 API on, GET /login prefers m.login.sso and keeps the password login", + "[integration][oauth][hand-off]") +{ + GIVEN("a server with the OAuth 2.0 API on and the legacy API on") + { + auto started = start(hand_off_config()); + auto& rt = started.runtime; + + WHEN("a client lists the login flows") + { + auto const response = send(rt, "GET", "/_matrix/client/v3/login"); + + THEN("m.login.password, m.login.token and m.login.sso with oauth_aware_preferred are offered") + { + REQUIRE(response.status == 200U); + CHECK(contains(response.body, R"({"type":"m.login.password"})")); + CHECK(contains(response.body, R"({"type":"m.login.token"})")); + CHECK(contains(response.body, R"("type":"m.login.sso")")); + CHECK(contains(response.body, R"("oauth_aware_preferred":true)")); + } + } + } + + GIVEN("a server with the OAuth 2.0 API off") + { + auto started = start(hand_off_config(false)); + auto& rt = started.runtime; + + WHEN("a client lists the login flows and opens the SSO redirect") + { + auto const flows = send(rt, "GET", "/_matrix/client/v3/login"); + auto const redirect = open_hand_off(rt, { + {"redirectUrl", std::string{app_return}} + }); + + THEN("neither changes: no SSO flow, and the redirect is not served without SSO configured") + { + REQUIRE(flows.status == 200U); + CHECK_FALSE(contains(flows.body, "m.login.sso")); + CHECK_FALSE(contains(flows.body, "oauth_aware_preferred")); + CHECK(redirect.response.status != 200U); + CHECK(redirect.pending.empty()); + } + } + } +} + +SCENARIO("The SSO redirect signs alice in, confirms, and returns one single-use login token", + "[integration][oauth][hand-off][security]") +{ + GIVEN("a server with the hand-off on") + { + auto started = start(hand_off_config()); + auto& rt = started.runtime; + + WHEN("an application opens the SSO redirect with a redirectUrl that already holds a loginToken") + { + auto const hand_off = open_hand_off(rt, { + {"redirectUrl", std::string{app_return}} + }); + + THEN("the login page is answered with the browser cookie and no redirect") + { + REQUIRE(hand_off.response.status == 200U); + REQUIRE(hand_off.pending.size() == 64U); + REQUIRE(hand_off.browser.cookie.size() == 64U); + CHECK(response_header(hand_off.response, "Location").empty()); + CHECK(contains(hand_off.response.body, R"(autocomplete="current-password")")); + } + + AND_WHEN("alice signs in") + { + auto const confirmation = sign_in(rt, hand_off); + + THEN("the confirmation page names her and the application, and may post to its origin alone") + { + REQUIRE(confirmation.status == 200U); + CHECK(contains(confirmation.body, "@alice:example.org")); + CHECK(contains(confirmation.body, "app.example.com")); + CHECK(contains(confirmation.body, R"(value="approve")")); + CHECK( + contains(response_header(confirmation, "Content-Security-Policy"), "https://app.example.com")); + CHECK(response_header(confirmation, "Location").empty()); + CHECK(audit_count(rt.homeserver, "auth.login_token.issued") == 0U); + } + + AND_WHEN("she continues and the application redeems the token twice") + { + auto const approved = post(rt, hand_off, + { + {"action", "approve"} + }); + auto const answer = redirect_answer(approved); + auto const token = + answer.parameters.contains("loginToken") ? answer.parameters.at("loginToken") : std::string{}; + auto const first = token_login(rt, token); + auto const second = token_login(rt, token); + auto const replayed_page = post(rt, hand_off, + { + {"action", "approve"} + }); + + THEN("the browser is sent to redirectUrl with one new loginToken, which logs in once") + { + REQUIRE(approved.status == 303U); + CHECK(response_header(approved, "Cache-Control") == "no-store"); + CHECK(response_header(approved, "Referrer-Policy") == "no-referrer"); + CHECK(answer.base == "https://app.example.com/cb"); + CHECK(answer.separator == '?'); + CHECK(answer.parameters.at("a") == "1"); + REQUIRE(token.size() == 64U); + CHECK(token != "stale"); + CHECK_FALSE(contains(response_header(approved, "Location"), "stale")); + CHECK(audit_count(rt.homeserver, "auth.login_token.issued") == 1U); + REQUIRE(first.status == 200U); + auto const body = parse_object(first.body); + auto const* user_id = string_member(body, "user_id"); + REQUIRE(user_id != nullptr); + CHECK(*user_id == "@alice:example.org"); + CHECK(second.status == 403U); + // The pending authorisation was spent: a second approve is the expired page. + CHECK(replayed_page.status == 400U); + CHECK(response_header(replayed_page, "Location").empty()); + } + } + + AND_WHEN("she cancels") + { + auto const cancelled = post(rt, hand_off, + { + {"action", "deny"} + }); + + THEN("a page says so, nothing is sent to the application and no token is minted") + { + REQUIRE(cancelled.status == 200U); + CHECK(contains(cancelled.body, "Sign-in cancelled")); + CHECK(response_header(cancelled, "Location").empty()); + CHECK(audit_count(rt.homeserver, "auth.login_token.issued") == 0U); + } + } + } + + AND_WHEN("the wrong password is sent") + { + auto const refused = post(rt, hand_off, + { + {"action", "login" }, + {"username", "alice" }, + {"password", "wrong-password"}, + }); + + THEN("the login page is answered again and nothing is redirected") + { + CHECK(refused.status == 401U); + CHECK(response_header(refused, "Location").empty()); + CHECK_FALSE(contains(refused.body, R"(value="approve")")); + } + } + + AND_WHEN("another browser posts the approval") + { + auto stranger = hand_off; + stranger.browser.cookie = std::string(64U, 'a'); + auto const refused = post(rt, stranger, + { + {"action", "approve"} + }); + + THEN("the expired page is answered and no token is minted") + { + CHECK(refused.status == 400U); + CHECK(response_header(refused, "Location").empty()); + CHECK(audit_count(rt.homeserver, "auth.login_token.issued") == 0U); + } + } + } + } +} + +SCENARIO("A redirectUrl the hand-off does not accept is refused with a page and no redirect", + "[integration][oauth][hand-off][security]") +{ + GIVEN("a server with the hand-off on") + { + auto started = start(hand_off_config()); + auto& rt = started.runtime; + auto const parameters = GENERATE( + Fields{ + }, + Fields{{"redirectUrl", ""}}, Fields{{"redirectUrl", "javascript:alert(1)"}}, + Fields{{"redirectUrl", "http://app.example.com/cb"}}, Fields{{"redirectUrl", "myapp:/cb"}}, + Fields{{"redirectUrl", "https://app.example.com/cb#x"}}, + Fields{{"redirectUrl", "https://app.example.com/cb"}, {"redirectUrl", "https://evil.example.com/"}}); + + WHEN("the SSO redirect is opened with it") + { + auto const refused = open_hand_off(rt, parameters); + + THEN("a 400 page is answered with no Location, no cookie and no pending sign-in") + { + CHECK(refused.response.status == 400U); + CHECK(refused.response.page); + CHECK(response_header(refused.response, "Location").empty()); + CHECK(response_header(refused.response, "Set-Cookie").empty()); + CHECK(refused.pending.empty()); + } + } + } +} + +SCENARIO("The SSO redirect honours action, the identity provider form and the allowlist", + "[integration][oauth][hand-off]") +{ + GIVEN("a server with the hand-off on and registration open") + { + auto started = start(hand_off_config()); + auto& rt = started.runtime; + + WHEN("the redirect is opened with action=register, an unknown action, and through /{idpId}") + { + auto const registering = + open_hand_off(rt, { + {"redirectUrl", "io.element.app:/cb"}, + {"action", "register" } + }); + auto const unknown = open_hand_off(rt, { + {"redirectUrl", "io.element.app:/cb"}, + {"action", "dance" } + }); + auto const by_idp = open_hand_off(rt, + { + {"redirectUrl", "http://127.0.0.1:8080/cb"} + }, + std::string{sso_redirect_path} + "/oidc-anything"); + + THEN("register shows the registration page, anything else the login page") + { + REQUIRE(registering.response.status == 200U); + CHECK(contains(registering.response.body, R"(name="password_confirm")")); + REQUIRE(unknown.response.status == 200U); + CHECK(contains(unknown.response.body, R"(autocomplete="current-password")")); + CHECK_FALSE(contains(unknown.response.body, R"(name="password_confirm")")); + REQUIRE(by_idp.response.status == 200U); + CHECK_FALSE(by_idp.pending.empty()); + } + } + } + + GIVEN("a server whose allowlist names one https origin") + { + auto started = start(hand_off_config(true, {"https://app.example.com"})); + auto& rt = started.runtime; + + WHEN("a listed and an unlisted address are opened") + { + auto const listed = open_hand_off(rt, { + {"redirectUrl", "https://app.example.com/cb"} + }); + auto const unlisted = open_hand_off(rt, { + {"redirectUrl", "https://other.example.com/cb"} + }); + auto const loopback = open_hand_off(rt, { + {"redirectUrl", "http://localhost:8080/cb"} + }); + + THEN("only the listed origin starts a sign-in") + { + CHECK(listed.response.status == 200U); + CHECK(unlisted.response.status == 400U); + CHECK(loopback.response.status == 400U); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index b41ad56b0..d4af1e94d 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -444,6 +444,7 @@ shell = find_program('sh') 'unit/test_oauth_client_metadata.cpp', 'unit/test_oauth_hand_off_allowlist.cpp', 'unit/test_legacy_auth_policy.cpp', + 'unit/test_oauth_hand_off_redirect.cpp', 'unit/test_oauth_authorization_code_store.cpp', 'unit/test_oauth_authorization_pages.cpp', 'unit/test_oauth_authorization_redirect.cpp', @@ -665,6 +666,7 @@ shell = find_program('sh') 'conformance/test_oauth_client_registration_conformance.cpp', 'conformance/test_oauth_token_conformance.cpp', 'conformance/test_oauth_legacy_api_conformance.cpp', + 'conformance/test_oauth_aware_clients_conformance.cpp', 'conformance/test_open_registration_conformance.cpp', 'conformance/test_account_lifecycle_conformance.cpp', 'conformance/test_device_lifecycle_conformance.cpp', @@ -882,6 +884,7 @@ shell = find_program('sh') 'integration/test_oauth_token_flow.cpp', 'integration/test_oauth_account_pages_flow.cpp', 'integration/test_oauth_legacy_api_flow.cpp', + 'integration/test_oauth_login_hand_off_flow.cpp', 'integration/test_observability_flow.cpp', 'integration/test_operator_admin_flow.cpp', 'integration/test_admin_masquerade_refusal_flow.cpp', diff --git a/tests/unit/test_oauth_hand_off_redirect.cpp b/tests/unit/test_oauth_hand_off_redirect.cpp new file mode 100644 index 000000000..7a2bf89f2 --- /dev/null +++ b/tests/unit/test_oauth_hand_off_redirect.cpp @@ -0,0 +1,172 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The legacy login hand-off's `redirectUrl` rules and its return address (oauth/HandOffRedirect.hpp), and its two +// pages (oauth/AuthorizationPages.hpp), plan P10, ADR-0802. Pure functions: no runtime. + +#include "merovingian/oauth/AuthorizationPages.hpp" +#include "merovingian/oauth/HandOffRedirect.hpp" +#include "merovingian/oauth/ParsedUri.hpp" + +#include +#include + +#include +#include +#include +#include + +namespace +{ + +using merovingian::oauth::hand_off_redirect_target; +using merovingian::oauth::hand_off_return_address; + +[[nodiscard]] auto contains(std::string_view haystack, std::string_view needle) -> bool +{ + return haystack.find(needle) != std::string_view::npos; +} + +[[nodiscard]] auto accepted(std::string_view url, std::vector const& allowlist = {}) -> bool +{ + return hand_off_redirect_target(url, allowlist).has_value(); +} + +// U+202E RIGHT-TO-LEFT OVERRIDE: HtmlText refuses it, so a page holding it as the pending identifier shows no form. +constexpr auto unshowable_pending = std::string_view{"abc\xE2\x80\xAE"}; +constexpr auto pending = std::string_view{"0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"}; + +} // namespace + +SCENARIO("An https address, a loopback http address and a private-use scheme are hand-off targets", + "[oauth][hand-off-redirect]") +{ + GIVEN("an address of an accepted shape") + { + auto const url = GENERATE(as{}, "https://app.example.com/cb", "https://app.example.com:8443/x?y=1", + "HTTPS://App.Example.com/cb", "http://localhost:8080/cb", "http://127.0.0.1/cb", + "http://[::1]:9000/", "http://LOCALHOST/cb", "io.element.app:/callback", + "com.example.app://login", "Com.Example.App:/x"); + + WHEN("no allowlist is configured") + { + THEN("it is accepted") + { + INFO(url); + REQUIRE(accepted(url)); + } + } + } +} + +SCENARIO("Any other address is refused as a hand-off target", "[oauth][hand-off-redirect][security]") +{ + GIVEN("an address of a refused shape") + { + auto const url = GENERATE(as{}, "", "javascript:alert(1)", "data:text/html,x", + "file:///etc/passwd", "http://app.example.com/cb", "http://10.0.0.1/cb", + "http://localhost.evil.com/", "https:/no-authority", "ftp://example.com/", + "myapp:/cb", "/relative/path", "https://app.example.com/cb#fragment", + "https://user@app.example.com/cb", "https://app.example.com/a b"); + + WHEN("it is checked") + { + THEN("it is refused") + { + INFO(url); + REQUIRE_FALSE(accepted(url)); + } + } + } +} + +SCENARIO("A configured allowlist limits the hand-off to its origins and schemes", "[oauth][hand-off-redirect]") +{ + GIVEN("an allowlist of one https origin and one private-use scheme") + { + auto const allowlist = std::vector{"https://app.example.com", "io.element.app:"}; + + WHEN("addresses are checked against it") + { + THEN("only a matching origin, port or scheme passes") + { + CHECK(accepted("https://app.example.com/cb", allowlist)); + CHECK(accepted("https://APP.example.com:443/other", allowlist)); + CHECK(accepted("IO.Element.App:/cb", allowlist)); + CHECK_FALSE(accepted("https://app.example.com:8443/cb", allowlist)); + CHECK_FALSE(accepted("https://evil.example.com/cb", allowlist)); + CHECK_FALSE(accepted("https://app.example.com.evil.com/cb", allowlist)); + CHECK_FALSE(accepted("com.example.app:/cb", allowlist)); + // A loopback address matches no entry, so an allowlist refuses it. + CHECK_FALSE(accepted("http://localhost:8080/cb", allowlist)); + } + } + } +} + +SCENARIO("The return address replaces every loginToken and keeps the rest", "[oauth][hand-off-redirect][security]") +{ + GIVEN("targets with and without a query") + { + auto const plain = hand_off_redirect_target("https://app.example.com/cb", {}); + auto const with_query = hand_off_redirect_target( + "https://app.example.com/cb?a=1&loginToken=old&b=2&loginToken=older&loginTokenX=keep", {}); + auto const only_token = hand_off_redirect_target("io.element.app:/cb?loginToken=old", {}); + REQUIRE(plain.has_value()); + REQUIRE(with_query.has_value()); + REQUIRE(only_token.has_value()); + + WHEN("a token is added") + { + auto const plain_address = hand_off_return_address(*plain, "tok"); + auto const query_address = hand_off_return_address(*with_query, "tok"); + auto const only_address = hand_off_return_address(*only_token, "a b&c"); + + THEN("the token appears once, earlier values are gone and other parameters keep their order") + { + REQUIRE(plain_address == std::optional{"https://app.example.com/cb?loginToken=tok"}); + REQUIRE(query_address == std::optional{ + "https://app.example.com/cb?a=1&b=2&loginTokenX=keep&loginToken=tok"}); + // The token is percent-encoded. + REQUIRE(only_address == std::optional{"io.element.app:/cb?loginToken=a%20b%26c"}); + } + } + } +} + +SCENARIO("The hand-off confirmation page names the account and the destination", "[oauth][hand-off-redirect]") +{ + GIVEN("an https target and a private-use target") + { + auto const web = hand_off_redirect_target("HTTPS://app.example.com/cb", {}); + auto const native = hand_off_redirect_target("io.element.app:/cb", {}); + REQUIRE(web.has_value()); + REQUIRE(native.has_value()); + + WHEN("the pages are rendered") + { + auto const web_html = merovingian::oauth::hand_off_page(pending, "@alice:example.org", *web).render(); + auto const native_html = merovingian::oauth::hand_off_page(pending, "@alice:example.org", *native).render(); + auto const markup_html = merovingian::oauth::hand_off_page(pending, "\">", *web).render(); + auto const no_form = + merovingian::oauth::hand_off_page(unshowable_pending, "@alice:example.org", *web).render(); + auto const cancelled = merovingian::oauth::hand_off_cancelled_page().render(); + + THEN("the host or the scheme is shown, the forms post to the authorisation endpoint, and markup is escaped") + { + CHECK(contains(web_html, "@alice:example.org")); + CHECK(contains(web_html, "app.example.com")); + CHECK_FALSE(contains(web_html, "HTTPS:")); + CHECK(contains(web_html, R"(action="/_merovingian/oauth2/authorize")")); + CHECK(contains(web_html, R"(value="approve")")); + CHECK(contains(web_html, R"(value="deny")")); + CHECK(contains(web_html, pending)); + CHECK(contains(native_html, "io.element.app: (an application on your device)")); + CHECK_FALSE(contains(markup_html, " Date: Mon, 16 Nov 2026 10:08:15 +0000 Subject: [PATCH 21/42] Answer an exception that escapes a client-server handler with 500 M_UNKNOWN (ADR-0803) handle_client_server_request caught only std::overflow_error; any other exception left the dispatcher and the transport closed the connection with no answer. A catch-all after the overflow catch now answers 500 M_UNKNOWN with a fixed text and the CORS headers, and logs one error line (request.exception) with the method, the normalised route and the exception's type, never its message, which can quote request data. The lock is released by the unwinding and taken afresh only to build the answer. current_exception_type_name moves to core (CurrentException.hpp) from its two copies in ThreadPool.cpp and HttpServer.cpp. HomeserverRuntime::test_client_request_hook lets a test make one request throw. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 + ...ption-with-a-500-and-logs-only-its-type.md | 76 +++++++ docs/adr/index.md | 1 + docs/http-transport.md | 6 + docs/observability-audit.md | 8 + include/merovingian/core/CurrentException.hpp | 15 ++ .../homeserver/HomeserverRuntime.hpp | 4 + src/core/AGENTS.md | 1 + src/core/CurrentException.cpp | 26 +++ src/core/meson.build | 2 +- src/homeserver/AGENTS.md | 8 + src/homeserver/ClientServerRuntime.cpp | 24 +++ src/homeserver/HttpServer.cpp | 36 ++-- src/net/ThreadPool.cpp | 32 +-- src/net/meson.build | 1 + .../test_request_exception_flow.cpp | 200 ++++++++++++++++++ tests/meson.build | 1 + 17 files changed, 393 insertions(+), 50 deletions(-) create mode 100644 docs/adr/0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md create mode 100644 include/merovingian/core/CurrentException.hpp create mode 100644 src/core/CurrentException.cpp create mode 100644 tests/integration/test_request_exception_flow.cpp diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ea407915..b79261439 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -81,6 +81,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Bug fixes +* An exception a client-server handler lets escape is answered `500 M_UNKNOWN` instead of closing the connection, + and its log line names the route and type but never the message (ADR-0803). * A handler's `Content-Type` spelled in another letter case no longer adds a second `Content-Type` to the response, and 302, 303, 409, 504 and other statuses now carry their reason phrase instead of `OK`. * `merovingian-db-migrate --plan 1 2 --migrations` now plans only the files between the two versions, instead of diff --git a/docs/adr/0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md b/docs/adr/0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md new file mode 100644 index 000000000..df36c308e --- /dev/null +++ b/docs/adr/0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md @@ -0,0 +1,76 @@ +# The client-server dispatch boundary answers an escaped exception with a 500 and logs only its type + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: part 0 of the device authorization grant work (plan P11 in `docs/todos/oauth-2-0-api.md`). + +## Context and Problem Statement + +Handlers return errors as values, but a handler can still throw: `std::bad_alloc`, a standard library precondition, a +bug. Before this decision `handle_client_server_request` caught only `std::overflow_error` (the sync stream counter, +ADR-0315). Anything else left the dispatcher: on the main pool the transport's outer catch logged it and closed the +connection with no answer, the media fetch pool answered its own 500, and a sync poll swallowed it. The client saw a +dropped connection and retried, and the log line held whatever `what()` said. Where should an escaped exception be +answered, and what may the log say about it? + +## Decision Drivers + +* Every client-server request, from any pool, passes through `handle_client_server_request`. +* The runtime lock must be free after the exception, whatever the handler held. +* An exception's message can carry request data: a parser quoting its input, a path, a user ID, a value from a form. + Under `/_merovingian/oauth2` and `/_merovingian/account` that can be a code, a token or a password field. +* The existing `std::overflow_error` answer ("sync stream counter exhausted") is relied on by tests and clients. + +## Considered Options + +* One `catch (...)` in `handle_client_server_request`, after the `std::overflow_error` catch, answering + `500 M_UNKNOWN` with a fixed text and logging the method, the normalised route and the exception's type. +* The same, but logging `what()` as well. +* A catch in each transport call site (`HttpServer.cpp` main pool, sync pool, media fetch pool). + +## Decision Outcome + +Chosen option: one `catch (...)` at the dispatch boundary, logging the type and never the message. + +* The answer is `dispatch_err(req, rt, 500U, "M_UNKNOWN", "internal server error")` with the request's CORS headers, + as the overflow answer is built, so the connection carries on as it does after any other 500. +* The log is one `client_server` line at error level, `request.exception`, with `method`, `route` + (`normalized_target`, so no ID and no query) and `type` (`core::current_exception_type_name`, the mangled type name + from the C++ ABI, `unknown` where it is not available). It never includes `what()`. +* The lock: the handler's `RuntimeLock` and `RequestLockScope` are destroyed while the exception unwinds (a + `RuntimeLockRelease` in scope re-acquires first and the guard then releases), so the catch takes the lock afresh + for building the answer, as the overflow catch does, and releases it on return. +* `HomeserverRuntime::test_client_request_hook` is called with the request path after the rate limit, with the lock + held, so a test can make one request throw (`tests/integration/test_request_exception_flow.cpp`). It is empty in + production. +* `current_exception_type_name` moved to `core` (`CurrentException.hpp`) from the two copies in `net/ThreadPool.cpp` + and `homeserver/HttpServer.cpp`, so the three users share one; `net` now links `core`. + +### Positive Consequences + +* A client gets an answer instead of a dropped connection, and the request is counted as completed. +* No request data reaches the log from an exception message. + +### Negative Consequences + +* Without the message, finding the throwing site needs the route and type, and then a reproduction. The thread pool's + own catch-all still logs `what()`; it handles background tasks, not requests, and is unchanged. +* `std::bad_alloc` is answered too: the answer needs a little memory, and if building it throws, the exception leaves + the dispatcher as before. + +## Pros and Cons of the Options + +### Logging `what()` as well + +* Good, because the message often names the site. +* Bad, because the message can quote request data, and under the OAuth paths that is a secret. + +### A catch in each transport call site + +* Bad, because three copies drift, and a fourth caller (a test, the local router) gets none. + +## Links + +* Refines [ADR-0315](0315-a-sync-token-ahead-of-the-streams-is-an-initial-sync-and-the-counter-never-wraps.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 50e88c607..c01b445fd 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -684,3 +684,4 @@ * [0800 - No default member initialiser holds OAuth page text, because clang 18 runs it at run time](0800-no-default-member-initialiser-holds-oauth-page-text-because-clang-18-runs-it-at-run-time.md) * [0801 - One function decides the legacy API switch, and each refused use answers as the spec says](0801-one-function-decides-the-legacy-api-switch-and-each-refused-use-answers-as-the-spec-says.md) * [0802 - The legacy SSO redirect hands off to the built-in pages, always confirms, and mints a 30-second login token](0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md) +* [0803 - The client-server dispatch boundary answers an escaped exception with a 500 and logs only its type](0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md) diff --git a/docs/http-transport.md b/docs/http-transport.md index d812dc260..ff79b5ed9 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -582,6 +582,12 @@ redacted from logged targets (`sanitized_http_target`). Request parser failures use stable error names and HTTP statuses. Oversized start lines, headers, header counts, and bodies map to `413`. Malformed request lines, invalid methods, invalid targets, and invalid content lengths map to `400`. Unsupported transfer encoding maps to `501` until streaming support exists. +An exception a client-server handler lets escape is answered at the dispatch boundary, `handle_client_server_request`, +with `500 M_UNKNOWN` and the fixed text `internal server error`, the request's CORS headers, and a kept connection, +whichever pool ran the request (ADR-0803). The runtime lock is released by the unwinding and taken afresh only to +build the answer. A `std::overflow_error` from the sync stream counter keeps its answer, `sync stream counter +exhausted` (ADR-0315). See `observability-audit.md` for the log line, which never carries the exception's message. + The public client-server and internal local-router entry points also preflight the **path portion**, before the first `?`, for literal NUL and `%00` (DB-6). They return `400 M_INVALID_PARAM` before a path-component diff --git a/docs/observability-audit.md b/docs/observability-audit.md index 099fccdb9..093d4f2cc 100644 --- a/docs/observability-audit.md +++ b/docs/observability-audit.md @@ -602,6 +602,14 @@ page`) when the user approves a cross-signing reset, and `cross_signing.reset_us API functions they call: `device.deleted` for a device sign-out, `auth.password_changed` (reason `changed on the account page; revoked all devices`) and `auth.account_deactivated` (reason `deactivated on the account page`). +## Exceptions at the client-server dispatch boundary (ADR-0803) + +An exception a client-server handler lets escape is answered `500 M_UNKNOWN` by `handle_client_server_request` and +logged once under `client_server` at error level as `request.exception`, with `method`, `route` (the normalised route +template, no ID and no query) and `type` (the exception's mangled type name, `unknown` where the ABI cannot name it). +The exception's message is never logged: it can quote request data. A `std::overflow_error` from the sync stream +counter keeps its own answer and is not logged this way. + ## Outbound client request diagnostics (F-76, ADR-0418) `http::OutboundClient::perform` logs one debug line per request under the `outbound_client` module: diff --git a/include/merovingian/core/CurrentException.hpp b/include/merovingian/core/CurrentException.hpp new file mode 100644 index 000000000..d23fd7eee --- /dev/null +++ b/include/merovingian/core/CurrentException.hpp @@ -0,0 +1,15 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +namespace merovingian::core +{ + +// The mangled type name of the exception being handled (`abi::__cxa_current_exception_type`), for a log line that +// must say what was thrown without its message, which can hold request data (ADR-0803). "unknown" when no exception +// is being handled or the toolchain has no . Not demangled: the helper stays portable across libstdc++ and +// libc++. The text comes from the program's own type information, never from a request. Call it only inside a +// `catch` block. +[[nodiscard]] auto current_exception_type_name() noexcept -> char const*; + +} // namespace merovingian::core diff --git a/include/merovingian/homeserver/HomeserverRuntime.hpp b/include/merovingian/homeserver/HomeserverRuntime.hpp index 9ade7b68c..e943cdb33 100644 --- a/include/merovingian/homeserver/HomeserverRuntime.hpp +++ b/include/merovingian/homeserver/HomeserverRuntime.hpp @@ -237,6 +237,10 @@ struct HomeserverRuntime final // tombstone is sent, with runtime.mutex released, so a test can change the old room as a concurrent // request would (C21). Always empty in production. std::function test_after_upgrade_room_created{}; + // Test-only: called by handle_client_server_request for every request, with the request's path, after the rate + // limit and with runtime.mutex held, so a test can make one request throw and see what the dispatch boundary + // answers (ADR-0803). Always empty in production. + std::function test_client_request_hook{}; // The OAuth 2.0 authorisation requests waiting for their user, and the authorisation codes minted by approvals // (plan P5, ADR-0782). In memory only, hashed, bounded, never evicting a live entry. Guarded by `mutex`. A client // either names is never deleted (`oauth_client_has_pending_authorisation`). diff --git a/src/core/AGENTS.md b/src/core/AGENTS.md index bec478f75..02f546cb1 100644 --- a/src/core/AGENTS.md +++ b/src/core/AGENTS.md @@ -15,6 +15,7 @@ Low-level utilities used across all other modules. No module-specific logic live | `RequestCookies.cpp` | `RequestCookies::parse`: the `Cookie` header reader. A malformed or repeated cookie makes its own name unusable (`find` answers nothing), never the others (ADR-0766) | | `HostCookie.cpp` | `host_cookie` / `host_cookie_deletion`: the only `Set-Cookie` writers, `__Host-` names with `Secure`, `HttpOnly`, `Path=/`, `SameSite` from `CookieSameSite`, `Max-Age` | | `CookieOctets.cpp`, `HttpToken.cpp`, `Utf8.cpp` | `cookie_octets_are_valid`, `http_token_is_valid` (also behind `http::header_name_is_valid`) and `utf8_is_valid` (also behind `canonicaljson::utf8_is_valid`) | +| `CurrentException.cpp` | `current_exception_type_name`: the mangled type name of the exception being handled, `unknown` without the C++ ABI. The one copy for every catch-all that logs a type (ADR-0803); never log the message of a request's exception | | `LibraryVersion.cpp` | `LibraryVersion`, `describe_library` (static or dynamic, from `dladdr(3)` on an address inside the library, ADR-0222) and the startup log line. Each module reports its own library; core never calls a third-party library's version function | ## Headers-only (no .cpp) diff --git a/src/core/CurrentException.cpp b/src/core/CurrentException.cpp new file mode 100644 index 000000000..b276958c6 --- /dev/null +++ b/src/core/CurrentException.cpp @@ -0,0 +1,26 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/core/CurrentException.hpp" + +#if __has_include() && defined(__GNUC__) +#include +#define MEROVINGIAN_HAS_CXXABI 1 +#else +#define MEROVINGIAN_HAS_CXXABI 0 +#endif + +namespace merovingian::core +{ + +auto current_exception_type_name() noexcept -> char const* +{ +#if MEROVINGIAN_HAS_CXXABI + auto const* type = abi::__cxa_current_exception_type(); + return type == nullptr ? "unknown" : type->name(); +#else + return "unknown"; +#endif +} + +} // namespace merovingian::core diff --git a/src/core/meson.build b/src/core/meson.build index 2614eb43a..197061a6c 100644 --- a/src/core/meson.build +++ b/src/core/meson.build @@ -1,3 +1,3 @@ -core_sources = files('CookieOctets.cpp', 'FileDescriptor.cpp', 'FoldedSubstringMatcher.cpp', 'FormFields.cpp', 'HostCookie.cpp', 'HttpToken.cpp', 'LibraryVersion.cpp', 'PortableSemaphore.cpp', 'QueryParams.cpp', 'RequestCookies.cpp', 'SecretBuffer.cpp', 'SemaphorePermit.cpp', 'Utf8.cpp', ) +core_sources = files('CookieOctets.cpp', 'CurrentException.cpp', 'FileDescriptor.cpp', 'FoldedSubstringMatcher.cpp', 'FormFields.cpp', 'HostCookie.cpp', 'HttpToken.cpp', 'LibraryVersion.cpp', 'PortableSemaphore.cpp', 'QueryParams.cpp', 'RequestCookies.cpp', 'SecretBuffer.cpp', 'SemaphorePermit.cpp', 'Utf8.cpp', ) core_lib = static_library('merovingian-core', core_sources, include_directories : inc, dependencies: [libsodium_dep, dl_dep], ) diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index a853d3383..c30feac55 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -80,6 +80,14 @@ This is the largest and most complex module — read this file carefully before | `Tls.cpp` | TLS connection setup, certificate loading, non-blocking read/write retry loop (ADR-0054) | | `LocalSmokeFlow.cpp` | In-process register → login → room → message flow exercised by the vertical-slice integration test | +## An escaped exception is answered at the dispatch boundary (ADR-0803) + +`handle_client_server_request` catches `std::overflow_error` (the sync stream counter) and then anything else, which it +answers `500 M_UNKNOWN` (`internal server error`) and logs as `request.exception` with the method, `normalized_target` +and `core::current_exception_type_name()`. Never log `what()` of a request's exception, and never add a catch-all in a +handler or a transport call site in its place: handlers still return errors as values, and this is the backstop. +`HomeserverRuntime::test_client_request_hook` is the test seam that makes a request throw. + ## Architecture boundaries ``` diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index a9d117569..e88e9c9e2 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -31,6 +31,7 @@ #include "merovingian/canonicaljson/Serializer.hpp" #include "merovingian/canonicaljson/Signable.hpp" #include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/core/CurrentException.hpp" #include "merovingian/core/FoldedSubstringMatcher.hpp" #include "merovingian/core/QueryParams.hpp" #include "merovingian/core/SecretBuffer.hpp" @@ -14942,6 +14943,10 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return dispatch_err(req, rt, 429U, "M_LIMIT_EXCEEDED", "rate limit exceeded", rate_limit_decision.retry_after_ms); } + if (rt.homeserver.test_client_request_hook) + { + std::invoke(rt.homeserver.test_client_request_hook, request_path); + } // Spec M_NOT_JSON: "Request did not contain valid JSON." A body that is not JSON (including // invalid UTF-8 in a string) is refused here, for every endpoint at once, so no handler // answers it with the M_BAD_JSON that is for JSON malformed in some other way. Only the @@ -22754,6 +22759,25 @@ auto handle_client_server_request(ClientServerRuntime& rt, LocalHttpRequest cons apply_cors_headers(req, result.response, rt.cors); return result; } + catch (...) + { + // ADR-0803: any other exception a handler lets escape is answered here, so the client gets a 500 instead of + // a closed connection. The handler's RuntimeLock and RequestLockScope were unwound before this block runs + // (a RuntimeLockRelease scope re-acquires on unwind, and the guard then releases), so the lock is taken + // afresh, as the overflow_error answer does. The log names the route's template and the exception's type, + // never its message: what() can carry request data (a parser quoting its input, a path, a value). + auto const guard = std::lock_guard{rt.homeserver.mutex}; + log_diagnostic("request.exception", + { + {"method", req.method, false}, + {"route", normalized_target(req.target), false}, + {"type", core::current_exception_type_name(), false} + }, + observability::LogEventSeverity::error); + result = dispatch_err(req, rt, 500U, "M_UNKNOWN", "internal server error"); + apply_cors_headers(req, result.response, rt.cors); + return result; + } if (fetch_scope.deferred()) { return DispatchResult{DispatchResult::Status::needs_media_fetch, {}, {}}; diff --git a/src/homeserver/HttpServer.cpp b/src/homeserver/HttpServer.cpp index 88bf497f0..7cf28747d 100644 --- a/src/homeserver/HttpServer.cpp +++ b/src/homeserver/HttpServer.cpp @@ -5,6 +5,7 @@ #include "merovingian/config/Config.hpp" #include "merovingian/config/HttpTransportConfig.hpp" +#include "merovingian/core/CurrentException.hpp" #include "merovingian/core/Error.hpp" #include "merovingian/core/QueryParams.hpp" #include "merovingian/core/SocketHandle.hpp" @@ -51,6 +52,13 @@ #include "merovingian/sync/ParkedPollLimits.hpp" #include "merovingian/sync/WakeReason.hpp" +#include +#include +#include +#include +#include +#include + #include #include #include @@ -72,17 +80,6 @@ #include #include -#if __has_include() && defined(__GNUC__) -#include -#endif - -#include -#include -#include -#include -#include -#include - namespace merovingian::homeserver { namespace @@ -137,19 +134,10 @@ namespace // C2: the three swallowed-exception sites in this file (sync wait, sync // pool dispatch, dispatch_local_http_request) previously logged only - // {"reason":"exception"}. Capture the mangled type and the std::exception - // message so a postmortem can identify the throwing site. The mangled - // name is intentionally not demangled here so the helper stays portable - // across libstdc++ / libc++ / MSVC. - [[nodiscard]] auto current_exception_type_name() noexcept -> char const* - { -#if __has_include() && defined(__GNUC__) - auto const* type = abi::__cxa_current_exception_type(); - return type == nullptr ? "unknown" : type->name(); -#else - return "unknown"; -#endif - } + // {"reason":"exception"}. Capture the mangled type + // (core::current_exception_type_name) and the std::exception message so a + // postmortem can identify the throwing site. + using core::current_exception_type_name; [[nodiscard]] auto current_exception_message() noexcept -> std::string { diff --git a/src/net/ThreadPool.cpp b/src/net/ThreadPool.cpp index 7d323091a..a69c8af94 100644 --- a/src/net/ThreadPool.cpp +++ b/src/net/ThreadPool.cpp @@ -3,6 +3,7 @@ #include "merovingian/net/ThreadPool.hpp" +#include "merovingian/core/CurrentException.hpp" #include "merovingian/observability/LogEventSeverity.hpp" #include "merovingian/observability/SingleLog.hpp" #include "merovingian/observability/StructuredLogField.hpp" @@ -14,13 +15,6 @@ #include #include -#if __has_include() && defined(__GNUC__) -#include -#define MEROVINGIAN_HAS_CXXABI 1 -#else -#define MEROVINGIAN_HAS_CXXABI 0 -#endif - namespace merovingian::net { @@ -35,21 +29,9 @@ namespace // The thread_pool catch-all previously logged only {"action":"swallowed"}. // For a security-first homeserver an unhandled exception in a worker is a - // signal worth keeping; capture the mangled type name and the - // std::exception message so postmortem can identify the throwing site. We - // log the raw mangled name (not demangled) to keep this portable across - // libstdc++ / libc++ / MSVC, and fall back to "unknown" on toolchains - // without . - [[nodiscard]] auto current_exception_type_name() noexcept -> char const* - { -#if MEROVINGIAN_HAS_CXXABI - auto const* type = abi::__cxa_current_exception_type(); - return type == nullptr ? "unknown" : type->name(); -#else - return "unknown"; -#endif - } - + // signal worth keeping; capture the mangled type name + // (core::current_exception_type_name) and the std::exception message so + // postmortem can identify the throwing site. [[nodiscard]] auto current_exception_message() noexcept -> std::string { try @@ -206,9 +188,9 @@ auto ThreadPool::worker_loop() -> void // exception escape the worker loop — std::thread::join would // call std::terminate. log_diagnostic("worker.exception", { - {"action", "swallowed", false}, - {"type", current_exception_type_name(), false}, - {"what", current_exception_message(), false} + {"action", "swallowed", false}, + {"type", core::current_exception_type_name(), false}, + {"what", current_exception_message(), false} }); } } diff --git a/src/net/meson.build b/src/net/meson.build index afe9575db..facfe1f04 100644 --- a/src/net/meson.build +++ b/src/net/meson.build @@ -11,4 +11,5 @@ net_lib = static_library( 'merovingian-net', net_sources, include_directories: inc, + link_with: [core_lib], ) diff --git a/tests/integration/test_request_exception_flow.cpp b/tests/integration/test_request_exception_flow.cpp new file mode 100644 index 000000000..d580dd5cc --- /dev/null +++ b/tests/integration/test_request_exception_flow.cpp @@ -0,0 +1,200 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The client-server dispatch boundary answers an exception a handler lets escape (ADR-0803): a 500 M_UNKNOWN with a +// fixed body, one error line naming the route and the exception's type but never its message, and the runtime lock +// free afterwards. `HomeserverRuntime::test_client_request_hook` makes one request throw. +#include "../support/ConsoleLogCapture.hpp" +#include "../support/InMemoryDatabaseConfig.hpp" +#include "../support/MasterKey.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/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" + +#include + +#include +#include +#include +#include +#include + +namespace +{ + +constexpr auto throwing_path = std::string_view{"/_matrix/client/v3/account/whoami"}; +constexpr auto secret_text = std::string_view{"secret-request-data-7f3a"}; + +[[nodiscard]] auto test_config() -> merovingian::config::Config +{ + auto security = merovingian::config::SecurityConfig{}; + security.secrets.master_key_file = merovingian::tests::shared_master_key_file(); + return merovingian::config::Config{ + merovingian::config::ServerConfig{}, + merovingian::config::ListenersConfig{}, + merovingian::tests::in_memory_database_config(), + security, + merovingian::config::ClientRateLimitsConfig{}, + merovingian::config::LogModulesConfig{}, + }; +} + +// Whether another thread can take the runtime lock now: a lock leaked by the unwinding would refuse it. +[[nodiscard]] auto lock_is_free_for_another_thread(merovingian::homeserver::ClientServerRuntime const& runtime) -> bool +{ + return std::async(std::launch::async, + [&runtime] { + auto const& mutex = runtime.homeserver.mutex; + if (!mutex.try_lock()) + { + return false; + } + mutex.unlock(); + return true; + }) + .get(); +} + +[[nodiscard]] auto contains(std::string_view text, std::string_view part) -> bool +{ + return text.find(part) != std::string_view::npos; +} + +} // namespace + +SCENARIO("An exception a client-server handler lets escape is answered with a 500", "[homeserver][request-exception]") +{ + GIVEN("a runtime whose whoami request throws a standard exception carrying request data") + { + auto started = merovingian::homeserver::start_client_server(test_config()); + REQUIRE(started.started); + auto& runtime = started.runtime; + runtime.rate_limit_engine.reset(); + runtime.homeserver.test_client_request_hook = [](std::string_view path) { + if (path == throwing_path) + { + throw std::runtime_error{std::string{secret_text}}; + } + }; + + WHEN("the request is made") + { + auto const capture = merovingian::tests::ConsoleLogCapture{}; + auto const answered = + merovingian::homeserver::handle_client_server_request(runtime, {"GET", std::string{throwing_path}}); + auto const log = capture.text(); + + THEN("the client gets 500 M_UNKNOWN with the fixed text and nothing of the message") + { + REQUIRE(answered.response.status == 500U); + REQUIRE(contains(answered.response.body, R"("errcode":"M_UNKNOWN")")); + REQUIRE(contains(answered.response.body, "internal server error")); + REQUIRE_FALSE(contains(answered.response.body, secret_text)); + } + THEN("one error line names the route and the type, never the message") + { + REQUIRE(capture.has_line("ERROR", "request.exception")); + REQUIRE(contains(log, throwing_path)); + REQUIRE(contains(log, "runtime_error")); + REQUIRE_FALSE(contains(log, secret_text)); + } + THEN("the runtime lock is released") + { + REQUIRE_FALSE(runtime.homeserver.mutex.held_by_current_thread()); + REQUIRE(lock_is_free_for_another_thread(runtime)); + } + } + + WHEN("the request throws and then a request that does not throw is made") + { + std::ignore = + merovingian::homeserver::handle_client_server_request(runtime, {"GET", std::string{throwing_path}}); + auto const versions = + merovingian::homeserver::handle_client_server_request(runtime, {"GET", "/_matrix/client/versions"}); + + THEN("the second request is answered as usual") + { + REQUIRE(versions.response.status == 200U); + REQUIRE(contains(versions.response.body, "\"versions\"")); + } + } + } + + GIVEN("a runtime whose whoami request throws something that is not a standard exception") + { + auto started = merovingian::homeserver::start_client_server(test_config()); + REQUIRE(started.started); + auto& runtime = started.runtime; + runtime.rate_limit_engine.reset(); + runtime.homeserver.test_client_request_hook = [](std::string_view path) { + if (path == throwing_path) + { + throw 42; + } + }; + + WHEN("the request is made") + { + auto const answered = + merovingian::homeserver::handle_client_server_request(runtime, {"GET", std::string{throwing_path}}); + + THEN("it is answered with the same 500 and the lock is released") + { + REQUIRE(answered.response.status == 500U); + REQUIRE(contains(answered.response.body, R"("errcode":"M_UNKNOWN")")); + REQUIRE(lock_is_free_for_another_thread(runtime)); + } + } + } + + GIVEN("a runtime whose whoami request throws std::overflow_error") + { + auto started = merovingian::homeserver::start_client_server(test_config()); + REQUIRE(started.started); + auto& runtime = started.runtime; + runtime.rate_limit_engine.reset(); + runtime.homeserver.test_client_request_hook = [](std::string_view path) { + if (path == throwing_path) + { + throw std::overflow_error{"counter"}; + } + }; + + WHEN("the request is made") + { + auto const answered = + merovingian::homeserver::handle_client_server_request(runtime, {"GET", std::string{throwing_path}}); + + THEN("the existing sync stream counter answer is kept") + { + REQUIRE(answered.response.status == 500U); + REQUIRE(contains(answered.response.body, "sync stream counter exhausted")); + } + } + } + + GIVEN("a runtime with no hook") + { + auto started = merovingian::homeserver::start_client_server(test_config()); + REQUIRE(started.started); + auto& runtime = started.runtime; + runtime.rate_limit_engine.reset(); + + WHEN("the same request is made without a token") + { + auto const answered = + merovingian::homeserver::handle_client_server_request(runtime, {"GET", std::string{throwing_path}}); + + THEN("it gets the handler's own answer") + { + REQUIRE(answered.response.status == 401U); + REQUIRE(contains(answered.response.body, "M_MISSING_TOKEN")); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index d4af1e94d..465f88842 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -920,6 +920,7 @@ shell = find_program('sh') 'integration/test_push_delivery_flow.cpp', 'integration/test_push_user_isolation_flow.cpp', 'integration/test_request_lock_contention_flow.cpp', + 'integration/test_request_exception_flow.cpp', 'integration/test_create_room_state_reads_flow.cpp', 'integration/test_runtime_hardening_flow.cpp', 'integration/test_seccomp_sqlite_flow.cpp', From 20bcdca39f7491493208412cf59124aece5cd060 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 10:28:37 +0000 Subject: [PATCH 22/42] Serve the OAuth 2.0 device authorization grant (ADR-0804 to ADR-0806) With server.oauth.device_grant_enabled, POST /_merovingian/oauth2/device (the device authorization endpoint) issues a device code and an eight-letter user code; the link page takes the code, signs the user in with the existing login pages, and a consent page that warns first records the answer for the device to collect at the token endpoint with the device_code grant (RFC 8628). Authorisations live in a capped in-memory store; wrong user codes are throttled per address and the throttle fails closed at its cap. A device sign-in creates no account and runs in one browser at a time under a two-minute lease. Co-Authored-By: Claude Opus 5.5 --- .../references/module-invariants.md | 7 +- CHANGELOG.md | 13 +- config/merovingian.conf.bsd.example | 3 +- config/merovingian.conf.example | 3 +- ...8-and-a-redeemed-device-code-is-expired.md | 86 +++ ...d-and-guessing-is-throttled-per-address.md | 94 +++ ...count-and-runs-in-one-browser-at-a-time.md | 82 ++ docs/adr/index.md | 3 + docs/auth-identity.md | 41 +- docs/http-transport.md | 12 + docs/matrix-v1.19-client-server-api.md | 2 +- docs/observability-audit.md | 12 + docs/security-coding-rules.md | 11 +- docs/todos/capability-gaps.md | 2 +- docs/user-manual.md | 41 +- include/merovingian/database/OAuthTables.hpp | 7 +- .../homeserver/DeviceAuthorisation.hpp | 38 + .../homeserver/DeviceAuthorisationState.hpp | 20 + .../homeserver/DeviceAuthorisationStore.hpp | 209 ++++++ .../homeserver/HomeserverRuntime.hpp | 10 + .../homeserver/OAuthAuthorization.hpp | 18 + include/merovingian/homeserver/OAuthClock.hpp | 7 + .../homeserver/OAuthDeviceAuthorization.hpp | 28 + .../homeserver/PendingAuthorisation.hpp | 6 +- .../homeserver/PendingAuthorisationKind.hpp | 4 + .../merovingian/homeserver/RetentionSweep.hpp | 9 +- .../homeserver/UserCodeAttemptThrottle.hpp | 68 ++ .../merovingian/oauth/AuthorizationPages.hpp | 21 + .../oauth/DeviceConsentPageInput.hpp | 30 + include/merovingian/oauth/OAuthErrorCodes.hpp | 9 +- include/merovingian/oauth/UserCode.hpp | 40 + src/homeserver/AGENTS.md | 32 +- src/homeserver/ClientServerRuntime.cpp | 25 + src/homeserver/DeviceAuthorisationStore.cpp | 275 +++++++ src/homeserver/OAuthAuthorization.cpp | 338 ++++++++- src/homeserver/OAuthClientRegistration.cpp | 5 +- src/homeserver/OAuthClock.cpp | 7 + src/homeserver/OAuthDeviceAuthorization.cpp | 165 ++++ src/homeserver/OAuthTokenEndpoint.cpp | 90 +++ src/homeserver/RetentionSweep.cpp | 13 +- src/homeserver/UserCodeAttemptThrottle.cpp | 64 ++ src/homeserver/meson.build | 3 + src/oauth/AGENTS.md | 15 +- src/oauth/AuthorizationPages.cpp | 76 ++ src/oauth/UserCode.cpp | 94 +++ src/oauth/meson.build | 1 + tests/conformance/AGENTS.md | 1 + .../test_oauth_device_grant_conformance.cpp | 270 +++++++ .../test_route_query_conformance.cpp | 9 +- .../test_oauth_device_grant_flow.cpp | 706 ++++++++++++++++++ tests/meson.build | 4 + tests/unit/test_oauth_authorization_pages.cpp | 130 +++- .../test_oauth_device_authorisation_store.cpp | 587 +++++++++++++++ tests/unit/test_oauth_user_code.cpp | 182 +++++ 54 files changed, 3977 insertions(+), 51 deletions(-) create mode 100644 docs/adr/0804-the-device-authorization-grant-answers-rfc-8628-and-a-redeemed-device-code-is-expired.md create mode 100644 docs/adr/0805-device-authorisations-and-user-codes-are-held-in-memory-capped-and-guessing-is-throttled-per-address.md create mode 100644 docs/adr/0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md create mode 100644 include/merovingian/homeserver/DeviceAuthorisation.hpp create mode 100644 include/merovingian/homeserver/DeviceAuthorisationState.hpp create mode 100644 include/merovingian/homeserver/DeviceAuthorisationStore.hpp create mode 100644 include/merovingian/homeserver/OAuthDeviceAuthorization.hpp create mode 100644 include/merovingian/homeserver/UserCodeAttemptThrottle.hpp create mode 100644 include/merovingian/oauth/DeviceConsentPageInput.hpp create mode 100644 include/merovingian/oauth/UserCode.hpp create mode 100644 src/homeserver/DeviceAuthorisationStore.cpp create mode 100644 src/homeserver/OAuthDeviceAuthorization.cpp create mode 100644 src/homeserver/UserCodeAttemptThrottle.cpp create mode 100644 src/oauth/UserCode.cpp create mode 100644 tests/conformance/test_oauth_device_grant_conformance.cpp create mode 100644 tests/integration/test_oauth_device_grant_flow.cpp create mode 100644 tests/unit/test_oauth_device_authorisation_store.cpp create mode 100644 tests/unit/test_oauth_user_code.cpp diff --git a/.agent/skills/merovingian-review/references/module-invariants.md b/.agent/skills/merovingian-review/references/module-invariants.md index 0682c0d96..4383e2124 100644 --- a/.agent/skills/merovingian-review/references/module-invariants.md +++ b/.agent/skills/merovingian-review/references/module-invariants.md @@ -259,7 +259,8 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that ## src/oauth -- No state, I/O or logging; caps stated and refused at, never truncated; errors quote no input. `src/oauth/AGENTS.md#Rules` +- No state, I/O or logging; caps stated and refused at, never truncated; errors quote no input; `normalise_user_code` + is the only reader that normalises (ADR-0805). `src/oauth/AGENTS.md#Rules` - Client addresses only through `ParsedUri::read`; redirect URIs matched byte for byte by `match_redirect_uri` (ADR-0770). No redirect before the client and its redirect URI are validated. - HTML only through `Page` with `HtmlText` or compile-time parts; every page sends `page_headers()`; only a matched @@ -271,6 +272,10 @@ look at every time. Read the `AGENTS.md` itself before judging a change to that `src/homeserver/AGENTS.md` - The legacy login hand-off confirms before every redirect, re-reads `redirectUrl` with `hand_off_redirect_target`, and is a kind of `PendingAuthorisation`, not a copied handler (ADR-0802). `src/homeserver/AGENTS.md` +- The device grant keeps its entries only in `DeviceAuthorisationStore` and its wrong codes only in + `UserCodeAttemptThrottle`, both on `oauth_device_clock_ms`; the link page checks origin, cookie and throttle before + any lookup; one browser answers a code; a device sign-in creates no account and its consent page warns first; a + redeemed device code is `expired_token` (ADR-0804 to ADR-0806). `src/homeserver/AGENTS.md` ## src/observability diff --git a/CHANGELOG.md b/CHANGELOG.md index b79261439..f17712059 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -68,6 +68,12 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) `inhibit_login`, and sessions already issued carry on (ADR-0801). * With OAuth on, `GET /login` prefers `m.login.sso`, whose redirect signs in on the built-in pages, confirms, and returns a single-use 30-second `loginToken` to `redirectUrl` (ADR-0802). +* `server.oauth.device_grant_enabled` serves the device authorization grant: `POST /_merovingian/oauth2/device`, the + code page `/_merovingian/oauth2/link` and the device code grant, as RFC 8628 answers it (ADR-0804). +* Device sign-ins are held in memory, 4096 at most and 8 per address; five wrong codes block an address for the rest + of ten minutes (ADR-0805). +* A device sign-in's consent page warns first that another device is being signed in, never creates an account, and + one browser at a time answers a code (ADR-0806). ## Security Fixes @@ -95,9 +101,10 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) 1.1.0 is in development. A configuration that sets any `server.oidc.*` key is now refused at start-up: remove those keys and set `server.oauth.enabled` instead (ADR-0764). The authorisation, token and revocation endpoints and the account pages at `/_merovingian/account` are served; a user signed in through OAuth changes a password, signs out a -device, deactivates the account or approves a cross-signing reset there. 1.1.0 migrates the database: on first -start it applies migration 002, which adds two empty tables and changes no existing one. A 1.0.x server refuses the -migrated database, so back it up before upgrading if you may need to go back. +device, deactivates the account or approves a cross-signing reset there. The device authorization grant is off by +default; turn on `server.oauth.device_grant_enabled` only if your users sign in devices without a browser. 1.1.0 +migrates the database: on first start it applies migration 002, which adds two empty tables and changes no existing +one. A 1.0.x server refuses the migrated database, so back it up before upgrading if you may need to go back. # Version 1.0.2 diff --git a/config/merovingian.conf.bsd.example b/config/merovingian.conf.bsd.example index 30dcd890b..072879541 100644 --- a/config/merovingian.conf.bsd.example +++ b/config/merovingian.conf.bsd.example @@ -637,7 +637,8 @@ security.media.decode_in_sandbox=true # server.sso.authorization_url. Every key here needs a restart. # legacy_api_enabled=false (only with enabled=true) turns off the legacy # /login and /register API. device_grant_enabled=true (only with enabled=true) -# advertises the device authorization grant. +# serves the device authorization grant: POST /_merovingian/oauth2/device and +# the code page /_merovingian/oauth2/link, which a reverse proxy must pass. # hand_off_redirect_allowlist (only with enabled=true, at most 32 entries) lists # https origins (https://app.example.org) and bare private-use schemes # (io.element.app:) the legacy SSO redirect's hand-off may return a login diff --git a/config/merovingian.conf.example b/config/merovingian.conf.example index f64d9bb5c..598867b3d 100644 --- a/config/merovingian.conf.example +++ b/config/merovingian.conf.example @@ -610,7 +610,8 @@ security.media.decode_in_sandbox=true # server.sso.authorization_url. Every key here needs a restart. # legacy_api_enabled=false (only with enabled=true) turns off the legacy # /login and /register API. device_grant_enabled=true (only with enabled=true) -# advertises the device authorization grant. +# serves the device authorization grant: POST /_merovingian/oauth2/device and +# the code page /_merovingian/oauth2/link, which a reverse proxy must pass. # hand_off_redirect_allowlist (only with enabled=true, at most 32 entries) lists # https origins (https://app.example.org) and bare private-use schemes # (io.element.app:) the legacy SSO redirect's hand-off may return a login diff --git a/docs/adr/0804-the-device-authorization-grant-answers-rfc-8628-and-a-redeemed-device-code-is-expired.md b/docs/adr/0804-the-device-authorization-grant-answers-rfc-8628-and-a-redeemed-device-code-is-expired.md new file mode 100644 index 000000000..e5a77aa0e --- /dev/null +++ b/docs/adr/0804-the-device-authorization-grant-answers-rfc-8628-and-a-redeemed-device-code-is-expired.md @@ -0,0 +1,86 @@ +# The device authorization grant answers RFC 8628, and a redeemed device code is expired + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: plan P11 and phase 10 in `docs/todos/oauth-2-0-api.md`. + +## Context and Problem Statement + +The spec makes the device authorisation grant optional and defers to RFC 8628. The plan serves it only when +`server.oauth.device_grant_enabled` is true (P11). RFC 8628 leaves several answers to the server: what a second poll +after the tokens were issued hears, how long a denied code is remembered, how `slow_down` is measured, what a full +store answers, and whether `verification_uri_complete` may sign in without the user confirming the code. Each choice +looks arbitrary in the code, and a later change could quietly make the grant easier to abuse. + +## Decision Drivers + +* The grant lets an attacker start a sign-in and send a victim the link (plan "Risks"). Nothing a device or a link + does may skip the user's own confirmation. +* A device code is a bearer secret until it is redeemed, and must be redeemed once. +* RFC 8628 section 3.5: `slow_down` adds five seconds "for this and all subsequent requests". +* The token endpoint is in the `auth_sensitive` rate-limit tier (20 a minute per address, ADR-0775). + +## Considered Options + +For a second poll after the tokens were issued: + +* `expired_token`, as for any code the store does not hold. +* `invalid_grant`, as the code grant answers a replayed code. +* Ending the session the first poll created, as a replayed authorization code does (ADR-0792). + +## Decision Outcome + +* **Routes and switch.** `POST /_merovingian/oauth2/device` and `GET`/`POST /_merovingian/oauth2/link` are answered + before the access-token gate and are `404 M_UNRECOGNIZED` unless `server.oauth.enabled` and + `server.oauth.device_grant_enabled` are both true. The token endpoint answers the grant type + `urn:ietf:params:oauth:grant-type:device_code` only then; otherwise `unsupported_grant_type`. The metadata names + the endpoint and the grant only then. +* **The device endpoint** takes a registered client that lists the device grant (`invalid_client`, + `unauthorized_client` otherwise), the spec scope (`parse_scope`), and answers `device_code`, `user_code` (shown as + `XXXX-XXXX`), `verification_uri`, `verification_uri_complete`, `expires_in` 600 and `interval` 5, with the CORS + headers and `Cache-Control: no-store`. A full store, in all or for the address, is `503 temporarily_unavailable` + (RFC 6749 section 4.1.2.1 as the registration cap answers, ADR-0780); a random-source failure is `500 + server_error`. +* **The poll's checks are in order**: `client_id` and `device_code` present (`invalid_request`), the client registered + (`invalid_client`) and for the grant (`unauthorized_client`), then the store: an unknown, expired or redeemed code is + `expired_token`; another client's code is `invalid_grant`; a denied code is `access_denied`, at every poll until it + expires; an approved code is redeemed once; a poll sooner than the interval after the previous poll is `slow_down`, + which grows the interval by five seconds for good; otherwise `authorization_pending`. The first poll is never + `slow_down`. Every refusal is 400; a failed session write is `500 server_error`. +* **A second poll after the tokens were issued is `expired_token`.** The store removes an approved entry when it hands + it out, so a redeemed code is indistinguishable from an unknown one. Chosen over ending the session: a device code + is polled from one device by design, and a retry after a lost answer is the likely cause of a second poll, not + theft; the device can sign in again. Chosen over `invalid_grant`: RFC 8628 says a device code that can no longer be + used is `expired_token`. +* **An approval goes through the same session write as the code grant** (`grant_oauth_session`, ADR-0792), after + `account_sign_in_gate` judges the account again: a user locked, suspended or deactivated between the approval and + the poll gets no session (`invalid_grant`). +* **`verification_uri_complete` only prefills the code.** `GET /link` looks nothing up; the user presses Continue, + which posts the code like a typed one, through the same Origin check, cookie and throttle (ADR-0805). A crafted link + never signs anyone in by being opened: the user still signs in and allows on the consent page (ADR-0806). +* **Polling margin.** A device polling every 5 seconds makes 12 requests a minute against the tier's 20. The link, + login and consent pages from the same address share that bucket (the tier is per address, not per route), so a + user signing in from the same network as the device leaves a margin of about 8 requests a minute. Each `slow_down` + halves the device's rate again. + +### Positive Consequences + +* A device code works once, and a code another client learns is useless to it. +* Every refusal the RFC names is reachable and tested, with no sleep: the store takes the time, and + `HomeserverRuntime::test_device_grant_clock_advance_ms` moves the clock the handlers read. + +### Negative Consequences + +* A device that loses the token answer must start again; nothing tells it that the session exists. +* A household signing in from behind one address near the tier's limit can be answered 429 on the pages while a device + polls. + +## Links + +* [ADR-0775](0775-auth-metadata-stays-in-the-generic-rate-limit-tier.md), [ADR-0780](0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md), + [ADR-0792](0792-an-oauth-grant-is-one-transaction-and-a-replayed-code-ends-only-the-session-it-produced.md), + [ADR-0805](0805-device-authorisations-and-user-codes-are-held-in-memory-capped-and-guessing-is-throttled-per-address.md), + [ADR-0806](0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md) +* RFC 8628 sections 3.1 to 3.5, 5.1 and 6.1 diff --git a/docs/adr/0805-device-authorisations-and-user-codes-are-held-in-memory-capped-and-guessing-is-throttled-per-address.md b/docs/adr/0805-device-authorisations-and-user-codes-are-held-in-memory-capped-and-guessing-is-throttled-per-address.md new file mode 100644 index 000000000..cce04262e --- /dev/null +++ b/docs/adr/0805-device-authorisations-and-user-codes-are-held-in-memory-capped-and-guessing-is-throttled-per-address.md @@ -0,0 +1,94 @@ +# Device authorisations and user codes are held in memory, capped, and guessing is throttled per address + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: plan P5 and P11, phase 10 in `docs/todos/oauth-2-0-api.md`. + +## Context and Problem Statement + +A device authorisation holds two secrets. The device code is 256 random bits and only the device sees it. The user +code is typed by a person, so it is short: RFC 8628 section 6.1 suggests eight characters from twenty consonants, +about 34.5 bits. Anyone can type at the link page, so the user code's strength is the throttle on wrong codes, and +the store holding them is reachable without authentication. How are the entries kept, how is a user code drawn and +read, and how is guessing bounded? + +## Decision Drivers + +* Nothing an unauthenticated caller does may grow memory without bound or evict another user's sign-in. +* A user code must be uniform over its alphabet, and unique among the live entries. +* RFC 8628 section 6.1 asks the server to accept a user code however it is typed (case, dashes, spaces). + `src/oauth/AGENTS.md` rule 2 says a reader refuses and never normalises. +* The retention sweep and the registration cap must not delete a client that a live device authorisation names + (ADR-0780), and must answer that in O(1). +* No test may sleep. + +## Considered Options + +For the throttle at its own capacity: + +* Fail closed: an address with no window waits until the soonest window ends. +* Fail open: an address with no window is not counted. +* Evict the oldest window. + +For the user code reader: + +* Normalise case and the separators `-`, space, `.` and `_`, and refuse everything else. +* Refuse anything but the stored form, as rule 2 says. + +## Decision Outcome + +* **In memory, as the other OAuth stores** (P5, ADR-0782): `DeviceAuthorisationStore` + (`HomeserverRuntime::oauth_device_authorisations`) keeps entries in a `HashedSecretTable` under the hash of the + device code; a second index maps the hash of the user code to the entry. Neither code is kept in clear except the + user code inside the entry, which the consent page shows. A restart ends every sign-in in progress and nothing else. +* **Caps.** 4096 entries in all and 8 per client address key (`rate_limit_client_key`). At a cap the expired entries + are purged and the creation is refused if it is still full; a live entry is never evicted. Every operation first + removes the expired entries, soonest first, at the cost of the entries removed. +* **The idle-client walk bound** (`database::max_idle_client_rows_examined`) grows from 16'896 to 20'992 by the 4096 + entries, because each can name a different client the walk must skip. The registration and retention + `static_assert`s include the new cap. +* **Retention.** `oauth_client_has_pending_authorisation` also asks `holds_live_entry_for_client`, which reads the + latest expiry of the client's entries from a per-client index: O(1), no scan. +* **User codes.** Eight characters from `BCDFGHJKLMNPQRSTVWXZ` by rejection sampling: a byte below 240 gives the + character at its value modulo twenty, a byte of 240 or more is skipped, so each character is equally likely. One + draw takes 32 random bytes; a code that clashes with a live one is drawn again, at most 8 times, then the creation + is refused (`secret_unavailable`, a 500). The store takes a `RandomSource` so a test can force a clash. +* **The reader normalises, as an exception to `src/oauth/AGENTS.md` rule 2.** `normalise_user_code` reads a lower-case + letter as its capital and skips `-`, space, `.` and `_`; any other byte (a digit, a vowel, a letter outside the + alphabet, a control or non-ASCII byte) refuses the whole text, as does text over 32 bytes or with other than eight + characters left. The exception is required by RFC 8628 section 6.1 and is the only one in the module; the reader is + still bounded and its error is fixed. +* **The throttle.** `UserCodeAttemptThrottle` (`HomeserverRuntime::oauth_user_code_attempts`) counts wrong codes per + client address key in a window of ten minutes from the first wrong one. Five wrong codes block the address until + the window ends: the page then answers 429 with `Retry-After` before the code is looked up, so the right code is + refused too and a blocked guesser learns nothing. With 4096 live codes in a space of 20^8, five guesses in ten + minutes find one with a chance of about 8 in 10^7 per address per window. A typed code that does not read as a code + counts as wrong; a post without the browser cookie is not counted (it guesses nothing). The block is logged once, as + `oauth.device.throttled` with `client_key`, at warning level. +* **The throttle fails closed at its cap** of 8192 windows: an address with no window waits until the soonest window + ends. Failing open would let a flood of addresses lift the limit for itself; evicting the oldest window would let it + lift the limit for the address it evicts. The cost is that such a flood blocks every other address's first try for + up to ten minutes, which an operator sees in the log. +* **The clock.** Every store and throttle operation takes the time. The handlers pass `oauth_device_clock_ms`, the wall + clock plus `HomeserverRuntime::test_device_grant_clock_advance_ms`, which only tests set. + +### Positive Consequences + +* The store's memory is bounded, a flood from one address cannot fill it, and no sign-in in progress is lost to one. +* A user code is uniform, unique while live, and accepted as people type it. + +### Negative Consequences + +* Behind a shared address (a carrier NAT, an office), five wrong codes from anyone block everyone there for ten + minutes, and eight sign-ins at once from that address are the most it gets. +* A flood of distinct addresses past 8192 delays every address's first code. + +## Links + +* [ADR-0780](0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md), + [ADR-0782](0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md), + [ADR-0804](0804-the-device-authorization-grant-answers-rfc-8628-and-a-redeemed-device-code-is-expired.md), + [ADR-0806](0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md) +* RFC 8628 sections 5.1, 5.2 and 6.1 diff --git a/docs/adr/0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md b/docs/adr/0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md new file mode 100644 index 000000000..b86069d65 --- /dev/null +++ b/docs/adr/0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md @@ -0,0 +1,82 @@ +# A device sign-in warns first, creates no account, and runs in one browser at a time + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: plan P11 and phase 10 in `docs/todos/oauth-2-0-api.md`. + +## Context and Problem Statement + +After the user types a right code on the link page, the sign-in goes through the same login pages as the authorisation +code grant, then a consent page, and the user's answer is recorded for the device to collect. Three things differ from +the code grant. The person answering is not the person who started the flow: the device did, and anyone can start one +and send the user its code. The code is shared, not bound to one browser: anyone who reads it off the screen, or is +sent it, can type it too. And nothing is redirected afterwards. What does the consent page say, may the pages create +an account, and what happens when two browsers type the same code? + +## Decision Drivers + +* The grant's inherent attack is phishing: an attacker starts a sign-in on a device they hold and persuades the user + to approve it (RFC 8628 section 5.4, plan "Risks"). The only defence in the flow is the user's informed refusal. +* A code typed in two browsers must not let one browser's sign-in decide for another browser's user, and must not + leave a sign-in in progress that a later answer from the other browser silently overrides. +* A browser that typed the code and walked away must not lock the code for the rest of its ten minutes. + +## Considered Options + +For two browsers: + +* One browser at a time, under a lease: the first holds the code for two minutes after each step it completes; + another browser is answered 409 until the lease lapses, then takes over and the first can no longer answer. +* First come, first served for the whole lifetime. +* Any browser may answer; the first answer wins. + +For the consent page: + +* The warning first, as the page's error notice, before the code and the client. +* The warning after the details, as on the code grant's consent page. + +## Decision Outcome + +* **The warning is the first thing on the consent page**: it says a different device, not this browser, is being signed + in, to continue only if the user started it on that device and the code matches, and to deny if someone sent the + code or the link. Then the code (as `XXXX-XXXX`), the client's name (or "An application with no name") and its + `client_uri` host, the account and the device ID, the full-access statement and, when the user already holds the + device ID, the replacement notice. Placed first because the attack works on a user who reads the client's familiar + name and stops reading. +* **A device sign-in creates no account.** The login page offers no registration, and `register` and `show_register` + are refused with 403. A device is signed in to an account the user already has; an attacker gains nothing from an + account the victim creates for them, and the page need not explain a second path. +* **One browser at a time, under a two-minute lease.** The right code attaches the browser (by its `__Host-mv-oauth` + cookie, compared as a hash) to the device authorisation; the lease is renewed when its user signs in. Another browser + typing the code is answered 409 with `Retry-After` until the lease lapses, then takes the code over. The first + browser's sign-in then ends with the "Device sign-in ended" page at its next step, and its `approve` cannot decide. + The same browser typing the code again gets a fresh attachment that ends its earlier one. Chosen over first come, + first served, which lets a browser that walked away (or an attacker who saw the code) lock it out; chosen over + "first answer wins", which lets a sign-in in another browser decide while this user is still reading. +* **An answer counts only from the latest attachment**, and only while the entry is pending: `decide` is refused + otherwise and the user sees the ended page. An approval judges the account again (`account_sign_in_gate`); a refused + account releases the attachment so another browser need not wait, and the device stays pending. +* **Nothing is redirected.** The answer pages say to return to the other device (approved) or that it was not let in + (denied), and carry no form; the device learns the answer by polling (ADR-0804). + +### Positive Consequences + +* A user who reads the first line of the page knows what they are approving. +* A code seen by a second person cannot be answered behind the first user's back, and a walked-away browser holds it + for two minutes at most. + +### Negative Consequences + +* A user who takes more than two minutes to type the password while someone else types the same code loses the + sign-in and starts again from the code. +* The warning cannot stop a user who approves anyway. + +## Links + +* [ADR-0788](0788-the-oauth-browser-binding-is-one-host-cookie-and-the-pending-identifier-is-the-form-token.md), + [ADR-0802](0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md), + [ADR-0804](0804-the-device-authorization-grant-answers-rfc-8628-and-a-redeemed-device-code-is-expired.md), + [ADR-0805](0805-device-authorisations-and-user-codes-are-held-in-memory-capped-and-guessing-is-throttled-per-address.md) +* RFC 8628 sections 3.3 and 5.4 diff --git a/docs/adr/index.md b/docs/adr/index.md index c01b445fd..510529613 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -685,3 +685,6 @@ * [0801 - One function decides the legacy API switch, and each refused use answers as the spec says](0801-one-function-decides-the-legacy-api-switch-and-each-refused-use-answers-as-the-spec-says.md) * [0802 - The legacy SSO redirect hands off to the built-in pages, always confirms, and mints a 30-second login token](0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md) * [0803 - The client-server dispatch boundary answers an escaped exception with a 500 and logs only its type](0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md) +* [0804 - The device authorization grant answers RFC 8628, and a redeemed device code is expired](0804-the-device-authorization-grant-answers-rfc-8628-and-a-redeemed-device-code-is-expired.md) +* [0805 - Device authorisations and user codes are held in memory, capped, and guessing is throttled per address](0805-device-authorisations-and-user-codes-are-held-in-memory-capped-and-guessing-is-throttled-per-address.md) +* [0806 - A device sign-in warns first, creates no account, and runs in one browser at a time](0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 974923661..1b7f4ee5f 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -156,7 +156,7 @@ production-gated. (issue #437), had no caller and was removed. - Client-server auth/device/key actions append durable audit rows without logging plaintext credentials, bearer tokens, or key payloads. -- `GET /_matrix/client/v1/auth_metadata` (and its MSC2965 unstable path) returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. `oauth::server_metadata` builds the document and every address in it comes from `oauth::OAuthBaseUrl`: the issuer is `server.public_baseurl` with one trailing slash and the endpoints sit under `/_merovingian/oauth2/` (ADR-0773). The endpoint is unauthenticated, carries CORS headers and stays in the generic rate-limit tier (ADR-0775). The registration, authorization, token and revocation endpoints are served (see "OAuth 2.0 client registration", "OAuth 2.0 authorisation pages" and "OAuth 2.0 token and revocation endpoints" below); the account pages are served (see "OAuth 2.0 account pages" below); the device authorisation endpoint is not served yet; it lands in a later phase of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). The former `server.oidc.*` keys are refused at start-up. +- `GET /_matrix/client/v1/auth_metadata` (and its MSC2965 unstable path) returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. `oauth::server_metadata` builds the document and every address in it comes from `oauth::OAuthBaseUrl`: the issuer is `server.public_baseurl` with one trailing slash and the endpoints sit under `/_merovingian/oauth2/` (ADR-0773). The endpoint is unauthenticated, carries CORS headers and stays in the generic rate-limit tier (ADR-0775). The registration, authorization, token and revocation endpoints are served (see "OAuth 2.0 client registration", "OAuth 2.0 authorisation pages" and "OAuth 2.0 token and revocation endpoints" below); the account pages are served (see "OAuth 2.0 account pages" below); the device authorization grant is served when `server.oauth.device_grant_enabled` is also true (see "OAuth 2.0 device authorization grant" below). The former `server.oidc.*` keys are refused at start-up. - **Application Service API identity (Matrix v1.19, `merovingian::appservice`).** Registration files (`appservice.registration_files`, parsed as JSON) build an in-memory `AppserviceRegistry` at startup in the main process only (the federation worker @@ -1280,6 +1280,45 @@ the spec's "Account management" names: `account_management_uri` and all six `org a page. `POST /login` `m.login.token` redeems from that store when get_token or the hand-off is on. `complete_sso_login` is not used: it needs `server.sso.*`, which cannot be set with OAuth on. +## OAuth 2.0 device authorization grant (phase 10) + +Served only while `server.oauth.enabled` and `server.oauth.device_grant_enabled` are both true; otherwise the routes are +`404 M_UNRECOGNIZED` and the token endpoint answers the grant `unsupported_grant_type` (P11, ADR-0804 to ADR-0806). + +- **Device endpoint.** `POST /_merovingian/oauth2/device` (`handle_oauth_device_authorization`, + `OAuthDeviceAuthorization.cpp`) takes the form body the token endpoint takes: a registered client (`invalid_client`) + listing `urn:ietf:params:oauth:grant-type:device_code` (`unauthorized_client`) and the spec scope (`parse_scope`). + It answers `device_code` (32 random bytes), `user_code` shown as `XXXX-XXXX`, `verification_uri` + (`/_merovingian/oauth2/link`), `verification_uri_complete` (the same with `?user_code=`), `expires_in` 600 and + `interval` 5. A full store is `503 temporarily_unavailable`. +- **Store (ADR-0805).** `DeviceAuthorisationStore` (`HomeserverRuntime::oauth_device_authorisations`), in memory, under + the hash of the device code, with an index by the hash of the user code; 4096 entries, 8 per client address key, + never evicting a live one. A live entry keeps its client from the retention sweep and the registration cap + (`oauth_client_has_pending_authorisation`). User codes are eight of `BCDFGHJKLMNPQRSTVWXZ`, drawn by rejection + sampling and unique among live entries; `oauth::normalise_user_code` reads them in any case with `-`, space, `.` and + `_` skipped, and refuses anything else. +- **Link page.** `GET /_merovingian/oauth2/link` sets the `__Host-mv-oauth` cookie and prefills a `user_code` that reads + as one; it looks nothing up. The form post is checked for its origin, then the cookie (without one: the form again + with a cookie, not counted), then `UserCodeAttemptThrottle`: five wrong codes from an address in ten minutes block it + until the ten minutes end (429, no lookup). A wrong, expired or answered code is one 400 page. A right one starts a + `PendingAuthorisation` of kind `device_authorization` on the login page through the same `start_sign_in` as + `/authorize`; its forms post there, with the same Origin check, cookie, pending cap and login throttle. +- **One browser (ADR-0806).** Typing the right code attaches the browser to the entry for two minutes, renewed when its + user signs in. Another browser is answered 409 with `Retry-After` until the lease lapses, and then takes over: the + earlier browser's sign-in ends with the "Device sign-in ended" page. Only the browser holding the latest attachment + can answer. +- **Consent.** A device sign-in never offers or accepts registration (403). After the password the consent page warns + first that a different device is being signed in and to deny a code someone else sent, then shows the code, the + client's name and `client_uri` host, the account and the device ID, the full-access statement and the replacement + notice. `approve` spends the pending entry, judges the account again (`account_sign_in_gate`; a refused account + releases the device entry), records the answer and shows "return to your other device"; `deny` records a denial. + Nothing is redirected; the device learns the answer by polling. +- **Token grant.** `grant_type=urn:ietf:params:oauth:grant-type:device_code` with `device_code` and `client_id`: the + client checks of the device endpoint, then the store: `expired_token` (unknown, expired or already redeemed), + `invalid_grant` (another client's code), `access_denied`, `slow_down` (sooner than the interval since the last poll; + the interval grows by five seconds for good), `authorization_pending`. An approved code is redeemed once: + `account_sign_in_gate` again, then `grant_oauth_session` and the same answer as the code grant. + ## Next starting points 1. Preserve the reviewed libsodium boundary for random token generation and password hashing as auth flows expand. diff --git a/docs/http-transport.md b/docs/http-transport.md index ff79b5ed9..930461620 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -997,6 +997,18 @@ else is `400 invalid_request`. Every answer is built by `oauth_json_response`, ` clients exist: a `client_secret` field is `400 invalid_client`, and an `Authorization: Basic` header `401 invalid_client` with `WWW-Authenticate: Basic`. A body over `max_body_bytes` gets the general `413 M_TOO_LARGE`. +`POST /_merovingian/oauth2/device` and `GET` and `POST /_merovingian/oauth2/link` (ADR-0804 to ADR-0806) are routed +the same way (`static_routes`, `auth_sensitive`, `client_static_route_allow` rows of `POST` and of `GET, POST`), before +the authentication gate, and are `404 M_UNRECOGNIZED` unless `server.oauth.enabled` and +`server.oauth.device_grant_enabled` are both true. The device endpoint is an API endpoint: a form body as the token +endpoint takes it, JSON answers from `oauth_json_response` with `Cache-Control: no-store` and the CORS headers, and +`503 temporarily_unavailable` when the store is full. The link page is a page (`LocalHttpResponse::page`, no CORS +header): its `GET` sets the `__Host-mv-oauth` cookie and prefills a `user_code` from the query, and its form post is +checked with `form_post_origin_is_accepted` before the body is read. A wrong or expired code is `400`, an address +that reached five wrong codes in ten minutes is `429` with `Retry-After` (before the code is looked up), and a code +another browser holds is `409` with `Retry-After`. The device polls the token endpoint every 5 seconds, 12 requests +a minute in the 20 of `auth_sensitive`; the pages from the same address share that bucket. + `GET` and `POST /_merovingian/account` (ADR-0796) are routed the same way (`static_routes`, `auth_sensitive`, a `client_static_route_allow` row of `GET, POST`, so another method is `405`), before the authentication gate, and are `404 M_UNRECOGNIZED` with the API off. Every answer is a page or a 303 marked `LocalHttpResponse::page`, so none carries diff --git a/docs/matrix-v1.19-client-server-api.md b/docs/matrix-v1.19-client-server-api.md index 09ee57944..5bb9cb03c 100644 --- a/docs/matrix-v1.19-client-server-api.md +++ b/docs/matrix-v1.19-client-server-api.md @@ -393,7 +393,7 @@ lists have no server maximum (ADR-0332). | --- | --- | --- | --- | --- | --- | | `GET` | `/_matrix/client/v1/auth_metadata` | `getAuthMetadata` | none | - | 200, 404 | -Implemented: returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. The MSC2965 path `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answers the same. Its registration endpoint, `POST /_merovingian/oauth2/register` (spec "Client registration"), is served: unauthenticated, `201` with the client ID and the registered metadata, RFC 7591 errors (ADR-0779 to ADR-0781). Its authorization endpoint, `GET` and `POST /_merovingian/oauth2/authorize` (spec "Authorisation code grant"), is served: the sign-in, account creation and consent pages, then a redirect with `code` and `state`, or an RFC 6749 error, in the query or the fragment (ADR-0787 to ADR-0789). Its token endpoint, `POST /_merovingian/oauth2/token` (spec "Token endpoint"), serves the `authorization_code` grant (PKCE `S256`, the redirect URI byte for byte, one transaction, a replayed code ending the session it produced) and the `refresh_token` grant (rotation as `/refresh`), for public clients only (ADR-0791 to ADR-0793). Its revocation endpoint, `POST /_merovingian/oauth2/revoke` (spec "Token revocation"), ends the session of an access or refresh token as `/logout` does and answers 200 whether or not the token was known (ADR-0795). A session from the token endpoint is refused at `POST /refresh` and at every endpoint that uses User-Interactive Authentication with `403 M_FORBIDDEN` naming the account page (ADR-0793, ADR-0794), except a change of held keys at `POST /keys/device_signing/upload`, which is the `m.oauth` stage (spec "OAuth authentication"): a 401 whose only flow is `m.oauth` with `params.m.oauth.url` the account page with `?action=org.matrix.cross_signing_reset`, completed by an `auth` holding just the `session` once the user has approved the reset there (ADR-0797). The account management URL (spec "Account management"), `GET` and `POST /_merovingian/account`, is served and advertised as `account_management_uri` with all six `org.matrix.*` actions; it reads `action` and `device_id` (ADR-0796, ADR-0798). The device authorization grant is served from a later phase of the [OAuth 2.0 API plan](todos/oauth-2-0-api.md). +Implemented: returns the OAuth 2.0 server metadata while `server.oauth.enabled` is true, and `404 M_UNRECOGNIZED` while it is off. The MSC2965 path `/_matrix/client/unstable/org.matrix.msc2965/auth_metadata` answers the same. Its registration endpoint, `POST /_merovingian/oauth2/register` (spec "Client registration"), is served: unauthenticated, `201` with the client ID and the registered metadata, RFC 7591 errors (ADR-0779 to ADR-0781). Its authorization endpoint, `GET` and `POST /_merovingian/oauth2/authorize` (spec "Authorisation code grant"), is served: the sign-in, account creation and consent pages, then a redirect with `code` and `state`, or an RFC 6749 error, in the query or the fragment (ADR-0787 to ADR-0789). Its token endpoint, `POST /_merovingian/oauth2/token` (spec "Token endpoint"), serves the `authorization_code` grant (PKCE `S256`, the redirect URI byte for byte, one transaction, a replayed code ending the session it produced) and the `refresh_token` grant (rotation as `/refresh`), for public clients only (ADR-0791 to ADR-0793). Its revocation endpoint, `POST /_merovingian/oauth2/revoke` (spec "Token revocation"), ends the session of an access or refresh token as `/logout` does and answers 200 whether or not the token was known (ADR-0795). A session from the token endpoint is refused at `POST /refresh` and at every endpoint that uses User-Interactive Authentication with `403 M_FORBIDDEN` naming the account page (ADR-0793, ADR-0794), except a change of held keys at `POST /keys/device_signing/upload`, which is the `m.oauth` stage (spec "OAuth authentication"): a 401 whose only flow is `m.oauth` with `params.m.oauth.url` the account page with `?action=org.matrix.cross_signing_reset`, completed by an `auth` holding just the `session` once the user has approved the reset there (ADR-0797). The account management URL (spec "Account management"), `GET` and `POST /_merovingian/account`, is served and advertised as `account_management_uri` with all six `org.matrix.*` actions; it reads `action` and `device_id` (ADR-0796, ADR-0798). With `server.oauth.device_grant_enabled=true` the device authorization grant (spec "Device authorisation grant", RFC 8628) is served and advertised: `POST /_merovingian/oauth2/device` as `device_authorization_endpoint`, the code page `/_merovingian/oauth2/link`, and the `urn:ietf:params:oauth:grant-type:device_code` grant at the token endpoint, answering `authorization_pending`, `slow_down`, `access_denied` and `expired_token` (ADR-0804 to ADR-0806); with it off the routes are `404 M_UNRECOGNIZED` and the grant `unsupported_grant_type`. | `POST` | `/_matrix/client/v1/login/get_token` | `generateLoginToken` | access token | required application/json | 200, 400, 401, 429 | | `GET` | `/_matrix/client/v3/account/whoami` | `getTokenOwner` | access token | - | 200, 401, 403, 429 | | `GET` | `/_matrix/client/v3/login` | `getLoginFlows` | none | - | 200, 404, 429 | diff --git a/docs/observability-audit.md b/docs/observability-audit.md index 093d4f2cc..c389b108f 100644 --- a/docs/observability-audit.md +++ b/docs/observability-audit.md @@ -589,6 +589,18 @@ ID), written in the grant's own transaction; `oauth.session.revoked` and `oauth. reason `revoked`), written when the session ends, as `auth.logout` is. A refresh grant writes the `auth.refresh` rows of the legacy refresh. +## OAuth 2.0 device authorization grant diagnostics and audit (ADR-0804 to ADR-0806) + +`POST /_merovingian/oauth2/device` logs under the `oauth` module: `oauth.device.started` (info, `client_id`) and +`oauth.device.refused` (debug, `error` and, once read, `client_id`). The link page logs `oauth.device.throttled` +(warning, `client_key`: the client address key the rate limiter uses) once, when an address reaches five wrong codes; +the wrong codes themselves are not logged. A user's answer is `oauth.device.approved` or `oauth.device.denied` (info, +`client_id`, `user_id`, `device_id`), and each is also a durable audit row (category `auth`, actor the user, target the +client ID, reason the device ID). The device code grant logs as the other grants: `oauth.token.refused` (debug, +`grant_type` `urn:ietf:params:oauth:grant-type:device_code`, `error`, `client_id`), except `authorization_pending`, +which a polling device answers every few seconds and is not logged, then `oauth.session.granted` with its audit row. +Never the device code, the user code, the cookie, the pending identifier or the query. + ## OAuth 2.0 account page diagnostics and audit (ADR-0796 to ADR-0798) `/_merovingian/account` logs under the `oauth` module, with `user_id` only: `account.page.signed_in`, diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index feecca9f4..3026144fe 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -996,7 +996,8 @@ quickly finding everything a given `AGENTS.md` file contributed. ## OAuth 2.0 API - **The `oauth` module holds no state, does no I/O and logs nothing; every reader has a stated cap, refuses rather - than truncates or repairs, and never quotes its input in an error.** + than truncates or repairs, and never quotes its input in an error.** The one reader that normalises is + `normalise_user_code`, which RFC 8628 section 6.1 requires; it skips only four separators and folds only case. Why: its inputs are attacker-chosen and some are secrets (PKCE verifiers, page passwords); a validator that repairs input checks one value and lets another through (CWE-20), and an error that echoes input leaks it into logs and pages (CWE-532). @@ -1110,6 +1111,14 @@ quickly finding everything a given `AGENTS.md` file contributed. allowlist alone does not stop a link spending the victim's session on a listed application (ADR-0802). Source: `src/homeserver/AGENTS.md`. +- **A device authorization grant's user code is looked up only for an address the wrong-code throttle lets through, + a wrong, expired and answered code are one answer, one browser at a time answers a code, and the consent page warns + first and never creates an account.** + Why: a user code has about 34.5 bits, so its strength is the throttle (CWE-307); a different answer for an expired + code tells a guesser it was once right (CWE-204); and the grant lets an attacker send a victim a code for the + attacker's device, which only the victim's informed refusal stops (CWE-451, ADR-0804 to ADR-0806). + Source: `src/homeserver/AGENTS.md`. + ## HTTP and network boundary - **Rate limiting is applied before any auth check.** Do not move it after auth. diff --git a/docs/todos/capability-gaps.md b/docs/todos/capability-gaps.md index dbd258fcd..ec86a0e2c 100644 --- a/docs/todos/capability-gaps.md +++ b/docs/todos/capability-gaps.md @@ -47,7 +47,7 @@ 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); the device authorization grant is a later phase of the [OAuth 2.0 API plan](oauth-2-0-api.md). An OAuth session still cannot add an email address or mint a login token (no page; `403 M_FORBIDDEN`). | +| `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`). | | `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). | | 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. | | Room summary over federation | `runtime-wired` | `GET /v1/room_summary/{roomIdOrAlias}?via=` asks up to 3 `via` servers over federation `GET /hierarchy/{roomId}` (the `room` chunk; v1.19 defines no federation summary route) for a room this server holds no state for (ADR-0556): one ADR-0079 slot (429 at once without one, also without a token), one deadline, unverified answer, shown only by its own `join_rule` / `world_readable` / `allowed_room_ids`. Local state always wins; a malformed `via` is `400 M_INVALID_PARAM`. Not implemented: resolving an alias that lives on another server (404 / 401), and `membership` for a room not held locally. | diff --git a/docs/user-manual.md b/docs/user-manual.md index 9f9c6dcee..380a4094e 100644 --- a/docs/user-manual.md +++ b/docs/user-manual.md @@ -835,8 +835,9 @@ registration (`POST /_merovingian/oauth2/register`), the sign-in pages (`/_merovingian/oauth2/authorize`, where a user signs in or creates an account and allows the application), the token endpoint (`POST /_merovingian/oauth2/token`, the authorization code and refresh grants) -revocation (`POST /_merovingian/oauth2/revoke`) and the account pages -(`/_merovingian/account`); the device grant follows. Every authorisation asks +revocation (`POST /_merovingian/oauth2/revoke`), the account pages +(`/_merovingian/account`) and, when turned on, the device authorization grant +(see [The device authorization grant](#the-device-authorization-grant)). Every authorisation asks for the password; the server keeps no browser session for it. At most 10000 client registrations are held; once every held one is in use, a new client is answered `503 temporarily_unavailable` until one is freed. @@ -870,8 +871,8 @@ and the client renews it with its refresh token. No address is configured. The issuer is `server.public_baseurl` with one trailing slash, and every endpoint is under it: `/_merovingian/oauth2/register`, `/_merovingian/oauth2/authorize`, `/_merovingian/oauth2/token`, -`/_merovingian/oauth2/revoke`, `/_merovingian/oauth2/device` and -`/_merovingian/account` (ADR-0773). A reverse proxy in front of the server must +`/_merovingian/oauth2/revoke`, `/_merovingian/oauth2/device`, +`/_merovingian/oauth2/link` and `/_merovingian/account` (ADR-0773). A reverse proxy in front of the server must pass `/_merovingian/oauth2/` and `/_merovingian/account` through, as it does `/_matrix/`. @@ -879,7 +880,7 @@ pass `/_merovingian/oauth2/` and `/_merovingian/account` through, as it does |---|---|---| | `server.oauth.enabled` | `false` | Set `true` to serve the OAuth 2.0 API. `server.public_baseurl` must then be an `https` URL with a host and no query, fragment or userinfo (a path is allowed), and `server.sso.authorization_url` must be empty. | | `server.oauth.legacy_api_enabled` | `true` | Set `false` to stop the legacy login and registration API issuing new sessions to users (ADR-0761, ADR-0801). Refused unless `server.oauth.enabled=true`, so users always have a way to log in. See [Turning the legacy API off](#turning-the-legacy-api-off). | -| `server.oauth.device_grant_enabled` | `false` | Set `true` to offer the device authorization grant (RFC 8628): the metadata then lists the device code grant type and `device_authorization_endpoint`. Refused unless `server.oauth.enabled=true`. | +| `server.oauth.device_grant_enabled` | `false` | Set `true` to serve the device authorization grant (RFC 8628): `POST /_merovingian/oauth2/device`, the code page `/_merovingian/oauth2/link` and the device code grant at the token endpoint, and the metadata lists the grant type and `device_authorization_endpoint`. Off, those routes are `404 M_UNRECOGNIZED` and the grant `unsupported_grant_type`. Refused unless `server.oauth.enabled=true`. See [The device authorization grant](#the-device-authorization-grant). | | `server.oauth.hand_off_redirect_allowlist` | (empty) | Comma-separated places the hand-off from the legacy SSO redirect may send the browser: `https` origins (`https://app.example.com`, `https://app.example.com:8443`, nothing after the host or port) and bare private-use schemes (`io.element.app:`), in lower case. Never a URL prefix (ADR-0774). At most 32 entries, none twice. Refused unless `server.oauth.enabled=true`. Empty, any `https` address, a loopback `http` address or a private-use scheme is accepted. See [The hand-off for legacy clients](#the-hand-off-for-legacy-clients). | The metadata offers `prompt=create` (`prompt_values_supported`) only while @@ -888,6 +889,36 @@ follows the legacy registration settings (ADR-0762). Every `server.oauth.*` key needs a restart. +##### The device authorization grant + +With `server.oauth.device_grant_enabled=true`, a device without a usable browser +(a television, a command-line client) can be signed in from another device +(RFC 8628; ADR-0804 to ADR-0806). The device asks +`POST /_merovingian/oauth2/device` for a code and shows the user a code such as +`BCDF-GHJK` and the address `/_merovingian/oauth2/link` (or a QR code of the +address with the code in it). The user opens it in any browser, enters the +code, signs in with the password, and allows or denies; the device polls the +token endpoint every 5 seconds and is signed in once the user allows. The page +never creates an account, and warns first that a different device is being +signed in: someone who sends a user a code is asking to be let into that +account, so turn the grant on only if your users need it. + +- A code lives 10 minutes and works once. +- At most 4096 device sign-ins are in progress at once, and 8 from one client + address; past either the device is answered `503 temporarily_unavailable`. +- Five wrong codes entered from one client address in 10 minutes block that + address until the 10 minutes end (`429` with `Retry-After`, the right code + included). Behind a shared address (a carrier NAT, an office) this blocks + everyone there; the log line is `oauth.device.throttled`. +- One browser at a time signs in with a code. Another browser entering it is + answered `409` until the first has been idle for two minutes, after which the + second takes over and the first can no longer answer. +- A restart ends every device sign-in in progress. + +The pages and the token endpoint share the `auth_sensitive` rate limit of their +address (20 a minute), so a device polling from the same network as the +browser leaves about 8 requests a minute for the pages. + ##### The hand-off for legacy clients With `server.oauth.enabled=true` and `server.oauth.legacy_api_enabled=true` (the diff --git a/include/merovingian/database/OAuthTables.hpp b/include/merovingian/database/OAuthTables.hpp index 252b3164f..58445ac31 100644 --- a/include/merovingian/database/OAuthTables.hpp +++ b/include/merovingian/database/OAuthTables.hpp @@ -22,12 +22,13 @@ namespace merovingian::database // The most idle clients one `OAuthTables::idle_clients` call examines (ADR-0782). The walk runs under `runtime.mutex` // and skips every client a pending authorisation or an unredeemed code names, so without a bound its cost was bounded -// only by the client cap. 16 896 is the 8192 pending authorisations plus the 8192 codes the homeserver can hold (each -// names one client, so at most 16 384 clients are skipped) plus 512, more than any caller asks for +// only by the client cap. 20 992 is the 8192 pending authorisations, the 8192 codes and the 4096 device authorisations +// the homeserver can hold (each names one client, so at most 20 480 clients are skipped, ADR-0805) plus 512, more than +// any caller asks for // (`retention_batch_rows` 500; `RetentionSweep.cpp` and `OAuthClientRegistration.cpp` assert it): a walk that stops // here has therefore already found `max` clients or every idle one. A walk that finds nothing within it answers // "nothing can go". -inline constexpr auto max_idle_client_rows_examined = std::size_t{16'896U}; +inline constexpr auto max_idle_client_rows_examined = std::size_t{20'992U}; // The in-memory copy of `oauth_clients` and `oauth_sessions` (migration 002, ADR-0776, ADR-0777). 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 diff --git a/include/merovingian/homeserver/DeviceAuthorisation.hpp b/include/merovingian/homeserver/DeviceAuthorisation.hpp new file mode 100644 index 000000000..7d61102ae --- /dev/null +++ b/include/merovingian/homeserver/DeviceAuthorisation.hpp @@ -0,0 +1,38 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/DeviceAuthorisationState.hpp" + +#include +#include +#include + +namespace merovingian::homeserver +{ + +// One device authorisation (`POST /_merovingian/oauth2/device`, RFC 8628 section 3.1; plan P11; ADR-0804), held by +// `DeviceAuthorisationStore` under the hash of its device code. The store sets every field from its own arguments. +struct DeviceAuthorisation final +{ + // The registered client that asked, and the scope it was granted (`oauth::parse_scope`, canonical order) with the + // device ID that scope names. + std::string client_id{}; + std::string scope{}; + std::string device_id{}; + // The user code in its stored form (eight alphabet characters), shown on the consent page. + std::string user_code{}; + // The rate-limit client key of the device's request (`rate_limit_client_key`). + std::string client_address_key{}; + std::uint64_t created_at_ms{0U}; + std::uint64_t expires_at_ms{0U}; + // The polling interval the device must keep; `slow_down` adds five seconds to it (RFC 8628 section 3.5). + std::uint64_t interval_ms{0U}; + // When the device last polled and was answered `authorization_pending` or `slow_down`; none before its first poll. + std::optional last_poll_ms{}; + DeviceAuthorisationState state{DeviceAuthorisationState::pending}; + // The user who approved or denied; empty while pending. + std::string user_id{}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/DeviceAuthorisationState.hpp b/include/merovingian/homeserver/DeviceAuthorisationState.hpp new file mode 100644 index 000000000..7545543af --- /dev/null +++ b/include/merovingian/homeserver/DeviceAuthorisationState.hpp @@ -0,0 +1,20 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include + +namespace merovingian::homeserver +{ + +// Where a device authorisation stands (RFC 8628; ADR-0804). It starts pending; a user's answer on the consent page +// makes it approved or denied, once. An approved one is removed when the device redeems it; a denied one stays until +// it expires, so every poll until then hears `access_denied`. +enum class DeviceAuthorisationState : std::uint8_t +{ + pending, + approved, + denied, +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/DeviceAuthorisationStore.hpp b/include/merovingian/homeserver/DeviceAuthorisationStore.hpp new file mode 100644 index 000000000..4c61db433 --- /dev/null +++ b/include/merovingian/homeserver/DeviceAuthorisationStore.hpp @@ -0,0 +1,209 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/StateGroupKeyHash.hpp" +#include "merovingian/homeserver/DeviceAuthorisation.hpp" +#include "merovingian/homeserver/HashedSecretTable.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +// The device authorisations of the device authorization grant (RFC 8628; plan P11; ADR-0804, ADR-0805). In memory +// only: an entry lives ten minutes, and a restart ends every one in progress and nothing else. +// +// An entry is held under the hash of its device code (`make_oauth_secret`, 256 bits), which `create` returns once to +// the device; the code itself is never kept. A second index maps the hash of the user code to the entry, for the +// link page. User codes are unique among the entries held. +// +// One browser at a time may sign in for an entry (ADR-0806): `attach` binds it to the browser's cookie for +// `attachment_lease_ms`, renewed by `renew` at each step that browser completes. While the lease runs another browser +// is told the code is busy; after it lapses the next browser takes the entry over, and the earlier browser's sign-in +// can no longer decide it. A user's answer (`decide`) counts only from the browser holding the latest attachment. +// +// Bounded: `max_entries` in all and `max_entries_per_address` per client address key. At a cap the expired entries are +// purged and, if it is still full, the creation is refused. A live entry is never evicted. Expired entries are removed +// at the start of every operation, soonest first, at the cost of the entries removed; an expired entry behaves as +// absent. +// +// Every operation takes the current time, so a test needs no clock. Not thread-safe: `runtime.mutex` serialises every +// use (the store is `HomeserverRuntime::oauth_device_authorisations`). +class DeviceAuthorisationStore final +{ +public: + // The source of the random bytes user codes are drawn from; `crypto::secure_random_bytes` unless a test passes + // one that repeats itself. nullopt is a failure of the source. + using RandomSource = std::function>(std::size_t)>; + + // RFC 8628 section 3.2 leaves the lifetime to the server; ten minutes, as a pending authorisation, is long enough + // to find a phone and sign in, and short enough that a code read off a screen is soon useless. + static constexpr auto lifetime_ms = std::uint64_t{600'000U}; + // At most this many entries in all. An entry is a few hundred bytes, and the idle-client walk skips every client + // an entry names, so this is part of `database::max_idle_client_rows_examined` (ADR-0805). + static constexpr auto max_entries = std::size_t{4096U}; + // At most this many entries per client address key: one household has a few devices to sign in at once, and an + // address cannot fill the store or crowd the user code space alone. + static constexpr auto max_entries_per_address = std::size_t{8U}; + // The polling interval the device is told (RFC 8628 section 3.2 suggests five seconds), and what `slow_down` adds + // to it (section 3.5: "increased by 5 seconds for this and all subsequent requests"). + static constexpr auto initial_interval_ms = std::uint64_t{5'000U}; + static constexpr auto slow_down_step_ms = std::uint64_t{5'000U}; + // How long one browser holds an entry after it typed the right code or completed a step (ADR-0806): two minutes to + // type a password, after which another browser may take the entry over. + static constexpr auto attachment_lease_ms = std::uint64_t{120'000U}; + // How many user codes `create` draws before it gives up on finding one not held. With every entry held, a draw + // clashes with probability 4096 / 20^8 (about 1.6e-7), so a second draw is already rare. + static constexpr auto max_user_code_draws = std::size_t{8U}; + // The random bytes one draw takes: eight are needed, and a byte is skipped with probability 1/16. + static constexpr auto user_code_random_bytes = std::size_t{32U}; + + explicit DeviceAuthorisationStore(RandomSource random = {}); + + enum class Refusal : std::uint8_t + { + // `max_entries` live entries are held. + store_full, + // `max_entries_per_address` live entries are held for the client address key. + address_full, + // The random source or the hash failed, or no unused user code was drawn. + secret_unavailable, + }; + + // What `create` hands the device, once. + struct Started final + { + std::string device_code{}; + std::string user_code{}; + std::uint64_t expires_in_ms{0U}; + std::uint64_t interval_ms{0U}; + }; + + // Takes a pending authorisation for `client_id`, granted `scope` naming `device_id`, asked from + // `client_address_key`, valid for `lifetime_ms` from `now_ms`. + [[nodiscard]] auto create(std::string_view client_id, std::string_view scope, std::string_view device_id, + std::string_view client_address_key, std::uint64_t now_ms) + -> std::variant; + + // The browser that typed the user code now holds the entry. `key` names the entry in the other operations. + struct Attached final + { + std::string key{}; + std::uint64_t attachment{0U}; + DeviceAuthorisation authorisation{}; + }; + // Another browser holds the entry for this much longer. + struct Busy final + { + std::uint64_t retry_after_ms{0U}; + }; + enum class NotFound : std::uint8_t + { + // No live pending entry has this user code: unknown, expired, or already answered. + unknown, + }; + + // Attaches the browser `browser_token` names to the live pending entry `user_code` (stored form) names. The browser + // already attached is attached again, under a fresh attachment that ends its earlier one. + [[nodiscard]] auto attach(std::string_view user_code, std::string_view browser_token, std::uint64_t now_ms) + -> std::variant; + + // A copy of the live pending entry `key` names while `attachment` is its latest; nullopt otherwise. + [[nodiscard]] auto find_attached(std::string_view key, std::uint64_t attachment, std::uint64_t now_ms) + -> std::optional; + + // Extends the lease of `attachment` to `attachment_lease_ms` from `now_ms`. False, changing nothing, when + // `find_attached` would answer nullopt. + [[nodiscard]] auto renew(std::string_view key, std::uint64_t attachment, std::uint64_t now_ms) -> bool; + + // Ends `attachment` when it is the entry's latest, so another browser need not wait for the lease. + auto release(std::string_view key, std::uint64_t attachment) -> void; + + // Records `user_id`'s answer and ends the attachment. False, changing nothing, when `find_attached` would answer + // nullopt: the entry ended, was answered, or another browser took it over. + [[nodiscard]] auto decide(std::string_view key, std::uint64_t attachment, std::string_view user_id, bool approve, + std::uint64_t now_ms) -> bool; + + // RFC 8628 section 3.5, in the order the store judges a poll. + enum class PollOutcome : std::uint8_t + { + // No live entry has this device code: never issued, expired, or already redeemed. + expired_token, + // The entry was issued to another client. + wrong_client, + // Answered no. + access_denied, + // Answered yes: the entry is removed and handed back in `PollResult::authorisation`. + approved, + // Polled sooner than the interval after the last poll: the interval grows by `slow_down_step_ms`. + slow_down, + authorization_pending, + }; + struct PollResult final + { + PollOutcome outcome{PollOutcome::expired_token}; + // The interval in force after this poll. + std::uint64_t interval_ms{0U}; + std::optional authorisation{}; + }; + + // The device's poll with `device_code` as `client_id`. Only `authorization_pending` and `slow_down` record the + // poll's time; the first poll is never `slow_down`. + [[nodiscard]] auto poll(std::string_view device_code, std::string_view client_id, std::uint64_t now_ms) + -> PollResult; + + // How many live entries name `client_id`, after removing the expired ones. No scan. + [[nodiscard]] auto live_count_for_client(std::string_view client_id, std::uint64_t now_ms) -> std::size_t; + // Whether a live entry names `client_id`, without changing the store. O(1). + [[nodiscard]] auto holds_live_entry_for_client(std::string_view client_id, std::uint64_t now_ms) const -> bool; + + // Removes every entry whose lifetime ended at or before `now_ms`. + auto erase_expired(std::uint64_t now_ms) -> void; + + // Entries held, expired ones not yet removed included. + [[nodiscard]] auto size() const noexcept -> std::size_t; + +private: + struct Attachment final + { + std::uint64_t id{0U}; + std::string browser_token_hash{}; + std::uint64_t lease_until_ms{0U}; + }; + + struct Entry final + { + DeviceAuthorisation authorisation{}; + std::string user_code_hash{}; + std::optional attachment{}; + }; + + template + using KeyedBy = std::unordered_map>; + + // A user code not held now, or nullopt after `max_user_code_draws` clashes or a failure of the source. + [[nodiscard]] auto draw_user_code() -> std::optional; + // The live pending entry `key` names whose latest attachment is `attachment`, or nullptr. + [[nodiscard]] auto attached_entry(std::string_view key, std::uint64_t attachment, std::uint64_t now_ms) -> Entry*; + auto forget(Entry const& entry) -> void; + + RandomSource m_random{}; + HashedSecretTable m_entries{}; + // The hash of a user code -> the hash of its entry's device code. + KeyedBy m_by_user_code{}; + KeyedBy m_count_by_address{}; + KeyedBy> m_expiries_by_client{}; + std::uint64_t m_next_attachment{0U}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/HomeserverRuntime.hpp b/include/merovingian/homeserver/HomeserverRuntime.hpp index e943cdb33..b556963f3 100644 --- a/include/merovingian/homeserver/HomeserverRuntime.hpp +++ b/include/merovingian/homeserver/HomeserverRuntime.hpp @@ -26,6 +26,7 @@ #include "merovingian/homeserver/ClientOutboundProxy.hpp" #include "merovingian/homeserver/ClientOutboundProxyPolicy.hpp" #include "merovingian/homeserver/CrossSigningResetApprovals.hpp" +#include "merovingian/homeserver/DeviceAuthorisationStore.hpp" #include "merovingian/homeserver/InboundTypingUser.hpp" #include "merovingian/homeserver/LocalDatabase.hpp" #include "merovingian/homeserver/LocalRoom.hpp" @@ -40,6 +41,7 @@ #include "merovingian/homeserver/SessionTable.hpp" #include "merovingian/homeserver/TestOnlyForcedOutboundResolution.hpp" #include "merovingian/homeserver/TypingExpiry.hpp" +#include "merovingian/homeserver/UserCodeAttemptThrottle.hpp" #include "merovingian/http/InFlightBudget.hpp" #include "merovingian/http/OutboundClient.hpp" #include "merovingian/http/OutboundRequest.hpp" @@ -246,6 +248,14 @@ struct HomeserverRuntime final // either names is never deleted (`oauth_client_has_pending_authorisation`). PendingAuthorisationStore oauth_pending_authorisations{}; AuthorizationCodeStore oauth_codes{}; + // The device authorization grant's authorisations and the wrong user codes typed on its link page, counted per + // address (plan P11, ADR-0804, ADR-0805). In memory only, bounded. Guarded by `mutex`. Both take their time from + // `oauth_device_clock_ms`; a client a live device authorisation names is never deleted either. + DeviceAuthorisationStore oauth_device_authorisations{}; + UserCodeAttemptThrottle oauth_user_code_attempts{}; + // Test-only: added to the wall clock by `oauth_device_clock_ms`, so a test moves the device grant's time (expiry, + // polling interval, the wrong-code window) without sleeping. Always 0 in production. + std::uint64_t test_device_grant_clock_advance_ms{0U}; // The signed-in sessions of the account pages at `/_merovingian/account` (plan P6, ADR-0796) and the cross-signing // reset approvals they grant (ADR-0797). In memory only, bounded. Here, not on `ClientServerRuntime`, because a // password change, a password reset and a deactivation (`AuthService.cpp`) end them. Guarded by `mutex`. diff --git a/include/merovingian/homeserver/OAuthAuthorization.hpp b/include/merovingian/homeserver/OAuthAuthorization.hpp index 61806a158..fcc6d4dd7 100644 --- a/include/merovingian/homeserver/OAuthAuthorization.hpp +++ b/include/merovingian/homeserver/OAuthAuthorization.hpp @@ -56,6 +56,24 @@ inline constexpr auto max_oauth_login_hint_bytes = std::size_t{255U}; [[nodiscard]] auto handle_oauth_authorize(ClientServerRuntime& runtime, LocalHttpRequest const& request) -> LocalHttpResponse; +// `GET` and `POST /_merovingian/oauth2/link`, the device authorization grant's verification page (RFC 8628 section +// 3.3; plan P11; ADR-0804 to ADR-0806). The dispatcher has matched the path and the method and checked that +// `server.oauth.enabled` and `server.oauth.device_grant_enabled` are both true. Every answer is a page marked +// `LocalHttpResponse::page`. +// +// `GET` answers the code form with the browser cookie, prefilled from the query's `user_code` only when +// oauth::normalise_user_code reads it; it looks nothing up. `POST` is refused with a 403 page unless +// oauth::form_post_origin_is_accepted accepts it, and with a 400 page unless FormFields reads it. Without the cookie +// it is the form again (400, a fresh cookie, not counted). Then, in order: an address `UserCodeAttemptThrottle` blocks +// gets 429 with `Retry-After` and no lookup; a code that does not read, or names no live pending device authorisation, +// is the same 400 page and counts against the address; a device authorisation another browser holds is 409 with +// `Retry-After`; otherwise this browser holds it and a pending authorisation of kind `device_authorization` starts on +// the login page (no registration), whose forms post to `/_merovingian/oauth2/authorize` and end on the device consent +// page. Same lock rules as handle_oauth_authorize. Never logs the code, the query or the cookie; logs +// `oauth.device.throttled` with the client key when an address reaches the limit. +[[nodiscard]] auto handle_oauth_link(ClientServerRuntime& runtime, LocalHttpRequest const& request) + -> LocalHttpResponse; + // How long a login token minted by the hand-off can be redeemed. The spec recommends around five seconds for an SSO // login token ("Client login via SSO"); 30 seconds leaves room for a mobile operating system to switch to the // application, and the token is still single use (ADR-0802). diff --git a/include/merovingian/homeserver/OAuthClock.hpp b/include/merovingian/homeserver/OAuthClock.hpp index 07c0af3ff..c1c503200 100644 --- a/include/merovingian/homeserver/OAuthClock.hpp +++ b/include/merovingian/homeserver/OAuthClock.hpp @@ -7,8 +7,15 @@ namespace merovingian::homeserver { +struct HomeserverRuntime; + // The wall-clock time the OAuth 2.0 handlers give `PendingAuthorisationStore` and `AuthorizationCodeStore`, in // milliseconds since the epoch; zero for a clock set before it. [[nodiscard]] auto oauth_wall_clock_ms() -> std::uint64_t; +// The time the device authorization grant's stores and handlers use (`DeviceAuthorisationStore`, +// `UserCodeAttemptThrottle`): `oauth_wall_clock_ms` plus `runtime.test_device_grant_clock_advance_ms`, which is 0 +// outside tests (ADR-0805). +[[nodiscard]] auto oauth_device_clock_ms(HomeserverRuntime const& runtime) -> std::uint64_t; + } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/OAuthDeviceAuthorization.hpp b/include/merovingian/homeserver/OAuthDeviceAuthorization.hpp new file mode 100644 index 000000000..5c89f8991 --- /dev/null +++ b/include/merovingian/homeserver/OAuthDeviceAuthorization.hpp @@ -0,0 +1,28 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +namespace merovingian::homeserver +{ + +struct ClientServerRuntime; +struct LocalHttpRequest; + +// `POST /_merovingian/oauth2/device`, the device authorization endpoint (spec "Device authorization grant"; RFC 8628 +// section 3.1; plan P11; ADR-0804). The dispatcher has matched the path and the method and checked that +// `server.oauth.enabled` and `server.oauth.device_grant_enabled` are both true. +// +// Read as the token endpoint reads its body: `application/x-www-form-urlencoded` (`invalid_request` otherwise), parsed +// with core::FormFields, and a `client_secret` or `Authorization: Basic` refused (`invalid_client`). Then `client_id` +// (`invalid_request` when missing), a registered client (`invalid_client`) that lists the device code grant +// (`unauthorized_client`), and `scope` (oauth::parse_scope; `invalid_scope`). A 200 JSON answer holds `device_code`, +// `user_code` (`XXXX-XXXX`), `verification_uri` (the link page), `verification_uri_complete` (with `user_code`), +// `expires_in` (600) and `interval` (5). A full store is 503 `temporarily_unavailable`; a failed random source 500 +// `server_error`. Every answer is an OAuth JSON answer (`oauth_json_response`, `no-store`) and gets the CORS headers. +// Logs `oauth.device.started` with the client ID; never the device code or the user code. +[[nodiscard]] auto handle_oauth_device_authorization(ClientServerRuntime& runtime, LocalHttpRequest const& request) + -> LocalHttpResponse; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/PendingAuthorisation.hpp b/include/merovingian/homeserver/PendingAuthorisation.hpp index b4cc96cca..78bd294f2 100644 --- a/include/merovingian/homeserver/PendingAuthorisation.hpp +++ b/include/merovingian/homeserver/PendingAuthorisation.hpp @@ -16,7 +16,8 @@ namespace merovingian::homeserver // and then approve or deny it (plan P5, ADR-0782). `PendingAuthorisationStore` holds it in memory under the hash of a // random identifier, bound to the browser by the hash of a cookie value. // -// Every field but the last three is the request as the handler validated it, never repaired. The store sets +// Every field but `user_id`, `client_address_key` and `created_at_ms` is the request as the handler validated it, never +// repaired. The store sets // `created_at_ms` and `client_address_key` from its own arguments and starts `user_id` empty. struct PendingAuthorisation final { @@ -47,6 +48,9 @@ struct PendingAuthorisation final std::string client_address_key{}; // When the store took the entry, in milliseconds since the epoch. std::uint64_t created_at_ms{0U}; + // A device sign-in only (ADR-0806): the `DeviceAuthorisationStore` entry's key and this browser's attachment to it. + std::string device_authorisation_key{}; + std::uint64_t device_attachment{0U}; }; } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/PendingAuthorisationKind.hpp b/include/merovingian/homeserver/PendingAuthorisationKind.hpp index 4a1a27a07..ef2af8d27 100644 --- a/include/merovingian/homeserver/PendingAuthorisationKind.hpp +++ b/include/merovingian/homeserver/PendingAuthorisationKind.hpp @@ -16,6 +16,10 @@ enum class PendingAuthorisationKind : std::uint8_t // The legacy SSO redirect's hand-off: the confirmation page, then a login token added to the `redirectUrl` the // hand-off accepted (`oauth::hand_off_redirect_target`). No client is registered for it. login_token_hand_off, + // A device authorisation reached from the link page (plan P11, ADR-0806): the device consent page, then the + // `DeviceAuthorisationStore` entry is approved or denied. No redirect: `redirect_uri`, `state`, `code_challenge` + // and `login_hint` stay empty, and the page offers no registration. + device_authorization, }; } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/RetentionSweep.hpp b/include/merovingian/homeserver/RetentionSweep.hpp index b3bdfaaf5..5ccbff005 100644 --- a/include/merovingian/homeserver/RetentionSweep.hpp +++ b/include/merovingian/homeserver/RetentionSweep.hpp @@ -30,10 +30,11 @@ inline constexpr auto expired_access_token_grace = std::chrono::hours{24 * 7}; // with a session is never deleted: "The server MUST NOT delete client registrations that have an active session." inline constexpr auto oauth_client_retention = std::chrono::hours{24 * 30}; -// Whether, at `now_ms` (milliseconds since the epoch), a live pending authorisation or a live unredeemed -// authorisation code names `client_id`, so its client must not be deleted under it (ADR-0780, ADR-0782). O(1): it asks -// `HomeserverRuntime::oauth_pending_authorisations` and `oauth_codes`, never scans them. The retention sweep and the -// registration cap (`register_oauth_client`) both ask it before deleting a client. Called with +// Whether, at `now_ms` (milliseconds since the epoch), a live pending authorisation, a live unredeemed authorisation +// code or a live device authorisation names `client_id`, so its client must not be deleted under it (ADR-0780, +// ADR-0782, ADR-0805). O(1): it asks `HomeserverRuntime::oauth_pending_authorisations`, `oauth_codes` and +// `oauth_device_authorisations` (at `now_ms` plus `test_device_grant_clock_advance_ms`), never scans them. The +// retention sweep and the registration cap (`register_oauth_client`) both ask it before deleting a client. Called with // HomeserverRuntime::mutex held. [[nodiscard]] auto oauth_client_has_pending_authorisation(HomeserverRuntime const& runtime, std::string_view client_id, std::uint64_t now_ms) -> bool; diff --git a/include/merovingian/homeserver/UserCodeAttemptThrottle.hpp b/include/merovingian/homeserver/UserCodeAttemptThrottle.hpp new file mode 100644 index 000000000..904482bfd --- /dev/null +++ b/include/merovingian/homeserver/UserCodeAttemptThrottle.hpp @@ -0,0 +1,68 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include "merovingian/database/StateGroupKeyHash.hpp" + +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +// The wrong user codes typed on the link page, counted per client address key (RFC 8628 section 5.1; plan P11; +// ADR-0805). A user code has about 34.5 bits; five wrong codes in ten minutes per address keeps a guesser's chance +// of hitting any of the `DeviceAuthorisationStore::max_entries` live codes in a window below 1 in 10^6. +// +// A window starts at an address's first wrong code and lasts `window_ms`. Once `max_wrong_codes` were wrong in it, the +// address is blocked until the window ends: the page is not looked up at all, so the right code is refused too. +// +// Bounded: at most `max_addresses` windows. At the cap the ended windows are removed; if every window is still live an +// address with no window is blocked until the soonest one ends (it fails closed, ADR-0805), so a flood of addresses +// cannot lift the limit for itself. Every operation takes the current time. Not thread-safe: `runtime.mutex` +// serialises every use (`HomeserverRuntime::oauth_user_code_attempts`). +class UserCodeAttemptThrottle final +{ +public: + static constexpr auto window_ms = std::uint64_t{600'000U}; + static constexpr auto max_wrong_codes = std::uint32_t{5U}; + // Each window is a key and two integers; 8192 is far more addresses than type codes in ten minutes, and the table + // stays well under a MiB. + static constexpr auto max_addresses = std::size_t{8192U}; + + // How long `client_key` must still wait before a code it types is looked up, or nullopt when it may try now. + [[nodiscard]] auto blocked_for_ms(std::string_view client_key, std::uint64_t now_ms) + -> std::optional; + + // Counts one wrong code for `client_key`. True when this one reached `max_wrong_codes`, so the caller logs the + // block once. An address the table has no room for is not counted (it is already blocked by `blocked_for_ms`). + [[nodiscard]] auto record_wrong(std::string_view client_key, std::uint64_t now_ms) -> bool; + + // Windows held, ended ones not yet removed included. + [[nodiscard]] auto size() const noexcept -> std::size_t; + +private: + struct Window final + { + std::uint64_t ends_at_ms{0U}; + std::uint64_t sequence{0U}; + std::uint32_t wrong{0U}; + }; + using Order = std::pair; + + auto erase_ended(std::uint64_t now_ms) -> void; + + std::unordered_map> m_windows{}; + // (ends_at_ms, sequence) -> client key, soonest end first. + std::map m_by_end{}; + std::uint64_t m_next_sequence{0U}; +}; + +} // namespace merovingian::homeserver diff --git a/include/merovingian/oauth/AuthorizationPages.hpp b/include/merovingian/oauth/AuthorizationPages.hpp index 209bb2cac..92bae8e9d 100644 --- a/include/merovingian/oauth/AuthorizationPages.hpp +++ b/include/merovingian/oauth/AuthorizationPages.hpp @@ -4,11 +4,13 @@ #include "merovingian/oauth/AccountFormInput.hpp" #include "merovingian/oauth/ConsentPageInput.hpp" +#include "merovingian/oauth/DeviceConsentPageInput.hpp" #include "merovingian/oauth/HtmlName.hpp" #include "merovingian/oauth/HtmlText.hpp" #include "merovingian/oauth/Page.hpp" #include "merovingian/oauth/ParsedUri.hpp" +#include #include namespace merovingian::oauth @@ -57,6 +59,25 @@ inline constexpr auto action_deny = HtmlName{"deny"}; -> Page; // The page a cancelled hand-off ends on: nothing is sent to the application. [[nodiscard]] auto hand_off_cancelled_page() -> Page; +// The pages of the device authorization grant (plan P11; ADR-0804, ADR-0806). None redirects anywhere: each is sent +// with `page_headers()`. +// +// The field the link page's form posts the typed code in. +inline constexpr auto user_code_field = HtmlName{"user_code"}; +// The link page (`GET` and `POST /_merovingian/oauth2/link`): one input for the code the other device shows, posting +// to `link_path`. `user_code`, a stored-form code, is prefilled as `XXXX-XXXX` (from `verification_uri_complete`); +// `error` is a fixed message about the last attempt. +[[nodiscard]] auto device_link_page(std::optional user_code, std::optional const& error) + -> Page; +// The consent page of a device sign-in. It opens with the warning that a different device is being signed in and that +// the user should continue only if they started this themselves and the code matches; then the code, the application, +// its website, the account and the device ID; the statement of full access; the notice when the device's session is +// replaced; and Allow and Deny posting to `authorize_path`. +[[nodiscard]] auto device_consent_page(DeviceConsentPageInput const& input) -> Page; +// The pages a device sign-in ends on: approved (return to the other device, which finishes on its own) and denied. +[[nodiscard]] auto device_approved_page() -> Page; +[[nodiscard]] auto device_denied_page() -> Page; + // A page that only says what went wrong: `title` and one paragraph, no form. [[nodiscard]] auto error_page(HtmlText title, HtmlText const& message) -> Page; diff --git a/include/merovingian/oauth/DeviceConsentPageInput.hpp b/include/merovingian/oauth/DeviceConsentPageInput.hpp new file mode 100644 index 000000000..cb4a74d91 --- /dev/null +++ b/include/merovingian/oauth/DeviceConsentPageInput.hpp @@ -0,0 +1,30 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::oauth +{ + +// What the consent page of a device authorisation shows (`device_consent_page`, ADR-0806). Every view is borrowed for +// the call. The client's values are attacker-chosen: each is escaped, and one that cannot be shown is replaced by +// fixed text, never shown raw. +struct DeviceConsentPageInput final +{ + // The pending authorisation identifier, the form's hidden `pending` field. + std::string_view pending_id{}; + // The user code in its stored form; the page shows it as `XXXX-XXXX`. + std::string_view user_code{}; + // The registered `client_name`, or none, and the host of its `client_uri` in lower case. + std::optional client_name{}; + std::string_view client_host{}; + // The user being signed in, and the device ID the scope names. + std::string_view user_id{}; + std::string_view device_id{}; + // Whether the user already holds a device with this ID, whose session an approval replaces. + bool replaces_existing_device{false}; +}; + +} // namespace merovingian::oauth diff --git a/include/merovingian/oauth/OAuthErrorCodes.hpp b/include/merovingian/oauth/OAuthErrorCodes.hpp index 1e14c1a68..1407b5df4 100644 --- a/include/merovingian/oauth/OAuthErrorCodes.hpp +++ b/include/merovingian/oauth/OAuthErrorCodes.hpp @@ -24,11 +24,16 @@ inline constexpr std::string_view error_unsupported_grant_type = "unsupported_gr // in a way the client cannot fix. inline constexpr std::string_view error_temporarily_unavailable = "temporarily_unavailable"; inline constexpr std::string_view error_server_error = "server_error"; -// RFC 6749 section 4.1.2.1, sent only in a redirect from the authorisation endpoint: a `response_type` other than -// `code`, a client not registered for the authorization code grant, and a user who denied the request. +// RFC 6749 section 4.1.2.1: a `response_type` other than `code`, a client not registered for the grant it uses, and a +// user who denied the request. The device code grant also answers the last two in JSON (RFC 8628 section 3.5). inline constexpr std::string_view error_unsupported_response_type = "unsupported_response_type"; inline constexpr std::string_view error_unauthorized_client = "unauthorized_client"; inline constexpr std::string_view error_access_denied = "access_denied"; +// RFC 8628 section 3.5, from the token endpoint's device code grant (ADR-0804): the user has not answered yet; the +// device polled sooner than its interval (which grows by five seconds); the device code is unknown, expired or spent. +inline constexpr std::string_view error_authorization_pending = "authorization_pending"; +inline constexpr std::string_view error_slow_down = "slow_down"; +inline constexpr std::string_view error_expired_token = "expired_token"; // OpenID Connect Core 1.0 section 3.1.2.6: `prompt=none`, which this server cannot honour because every authorisation // asks for the password (ADR-0787). inline constexpr std::string_view error_login_required = "login_required"; diff --git a/include/merovingian/oauth/UserCode.hpp b/include/merovingian/oauth/UserCode.hpp new file mode 100644 index 000000000..4ffdbdc35 --- /dev/null +++ b/include/merovingian/oauth/UserCode.hpp @@ -0,0 +1,40 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include +#include +#include +#include +#include + +namespace merovingian::oauth +{ + +// The user code of the device authorization grant (RFC 8628 section 6.1; plan P11; ADR-0805): eight characters drawn +// uniformly from twenty consonants, with no vowel (no word can be spelt) and no digit (nothing to confuse with a +// letter). 20^8 is about 2^34.5 codes; the server lets an address try five wrong ones in ten minutes. +inline constexpr auto user_code_alphabet = std::string_view{"BCDFGHJKLMNPQRSTVWXZ"}; +inline constexpr auto user_code_length = std::size_t{8U}; +// The longest text read as a typed user code: the eight characters shown as `XXXX-XXXX`, with room for spaces and +// dashes a user adds. Anything longer is refused, never shortened. +inline constexpr auto max_typed_user_code_bytes = std::size_t{32U}; + +// A user code from `random_bytes` by rejection sampling: a byte below 240 (twelve times twenty) gives the character +// at its value modulo twenty, so every character is equally likely; a byte of 240 or more is skipped. nullopt when the +// bytes run out before eight characters were drawn (the caller draws again). +[[nodiscard]] auto user_code_from_bytes(std::span random_bytes) -> std::optional; + +// The user code a person typed, in the stored form (eight upper-case alphabet characters), or nullopt. RFC 8628 +// section 6.1 asks the server to accept the code however the user types it, so this is the one reader in this module +// that normalises (ADR-0805): a lower-case letter is read as its capital, and a dash, space, dot or underscore is +// skipped. Every other byte (a digit, a vowel, any letter outside the alphabet, a control or non-ASCII byte) refuses +// the whole text, as does text over max_typed_user_code_bytes or with other than eight characters left. +[[nodiscard]] auto normalise_user_code(std::string_view typed) -> std::optional; + +// `code` as it is shown to the user: the first four characters, a dash, the last four (`XXXX-XXXX`). `code` must be a +// stored user code; anything else is returned unchanged. +[[nodiscard]] auto display_user_code(std::string_view code) -> std::string; + +} // namespace merovingian::oauth diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index c30feac55..3f70b97e1 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -29,11 +29,14 @@ This is the largest and most complex module — read this file carefully before | `RetentionSweep.cpp` | `run_retention_sweep`: the sweep the `retention-sweep` `PeriodicJob` runs every hour. Deletes sessions and tokens that can no longer authenticate and `audit_log` rows past `security.audit_log_retention_days`, and OAuth 2.0 clients with no session unused for 30 days (`oauth_client_retention`, least recently used first; never a client with a session, nor one `oauth_client_has_pending_authorisation` names: a live pending authorisation or an unredeemed code, answered in O(1) from the stores; ADR-0777, ADR-0782), in transactions of at most 500 rows (`retention_batch_rows`), at most 20 batches per kind per sweep. `runtime.mutex` is taken for one batch at a time, never across the whole sweep (ADR-0488, ADR-0489) | | `OAuthClientRegistration.cpp` | `POST /_merovingian/oauth2/register` (`register_oauth_client`), the client ID (`oauth_client_id_of`, ADR-0779), the cap and its eviction (ADR-0780), and `find_registered_oauth_client` | | `OAuthJsonResponse.cpp` | `oauth_json_response` / `oauth_error_response` / `oauth_empty_response`: every OAuth JSON (or empty) answer, with `no-store` (ADR-0781) | -| `OAuthTokenEndpoint.cpp` | `POST /_merovingian/oauth2/token` (`handle_oauth_token`): the authorization code grant and the refresh grant (ADR-0791 to ADR-0793) | +| `OAuthTokenEndpoint.cpp` | `POST /_merovingian/oauth2/token` (`handle_oauth_token`): the authorization code grant, the refresh grant (ADR-0791 to ADR-0793) and the device code grant (ADR-0804) | | `OAuthRevocation.cpp` | `POST /_merovingian/oauth2/revoke` (`handle_oauth_revoke`): ends the session of an access or refresh token as `/logout` does (ADR-0795) | | `OAuthClientCredentials.cpp` | `oauth_client_credentials_refusal`: refuses a `client_secret` field or `Authorization: Basic` (only public clients exist) at the token and revocation endpoints | -| `OAuthAuthorization.cpp` | `GET` and `POST /_merovingian/oauth2/authorize` (`handle_oauth_authorize`): the authorisation request, the browser cookie, the login, registration and consent pages, and the redirect with a code or an error (ADR-0787 to ADR-0789) | -| `OAuthClock.cpp` | `oauth_wall_clock_ms`: the wall-clock milliseconds every OAuth store and handler passes | +| `OAuthAuthorization.cpp` | `GET` and `POST /_merovingian/oauth2/authorize` (`handle_oauth_authorize`): the authorisation request, the browser cookie, the login, registration and consent pages, and the redirect with a code or an error (ADR-0787 to ADR-0789); the legacy SSO hand-off (`handle_login_hand_off`, ADR-0802); the device grant's link page (`handle_oauth_link`) and its consent and answer (ADR-0806) | +| `OAuthClock.cpp` | `oauth_wall_clock_ms`: the wall-clock milliseconds every OAuth store and handler passes; `oauth_device_clock_ms`, the same plus `HomeserverRuntime::test_device_grant_clock_advance_ms`, which the device grant's stores are given | +| `OAuthDeviceAuthorization.cpp` | `POST /_merovingian/oauth2/device` (`handle_oauth_device_authorization`): the device grant's codes (ADR-0804) | +| `DeviceAuthorisationStore.cpp` | `DeviceAuthorisationStore` (`HomeserverRuntime::oauth_device_authorisations`): device authorisations, 10 minutes, under the hash of the device code with an index by the hash of the user code; 4096 in all and 8 per client address, never evicting a live entry; one browser attached at a time (ADR-0805, ADR-0806). Guarded by `runtime.mutex` | +| `UserCodeAttemptThrottle.cpp` | `UserCodeAttemptThrottle` (`HomeserverRuntime::oauth_user_code_attempts`): five wrong user codes per client address key in ten minutes, 8192 windows, failing closed at the cap (ADR-0805). Guarded by `runtime.mutex` | | `AccountPage.cpp` | `GET` and `POST /_merovingian/account` (`handle_account_page`): the account pages' sign-in, overview, devices, device sign-out, password change, deactivation and cross-signing reset approval (ADR-0796 to ADR-0798) | | `AccountSessionStore.cpp` | `AccountSessionStore` (`HomeserverRuntime::account_sessions`): account-page sessions, 15 minutes fixed, hashed secret, 4096 in all and 4 per user (the user's oldest goes), and the session's form token (ADR-0796). Guarded by `runtime.mutex` | | `CrossSigningResetApprovals.cpp` | `CrossSigningResetApprovals` (`HomeserverRuntime::cross_signing_reset_approvals`): one approval per user, 10 minutes, taken by a replacing upload and restored unless the keys are stored (ADR-0797). Guarded by `runtime.mutex` | @@ -214,6 +217,29 @@ With both APIs on, the SSO redirects call `handle_login_hand_off` (`OAuthAuthori consent page, `approve` and `deny` branch on the kind. A hand-off never redirects before the user confirmed, reads its `redirectUrl` again with `oauth::hand_off_redirect_target` at every step, and mints only into `rt.login_tokens`. +The device authorization grant (ADR-0804 to ADR-0806) is `handle_oauth_device_authorization`, `handle_oauth_link` and +the token endpoint's `device_code_grant`; `ClientServerRuntime.cpp` holds only the route matches, which answer 404 +unless `server.oauth.enabled` and `server.oauth.device_grant_enabled` are both true. Rules: + +- **`DeviceAuthorisationStore` is the only place a device authorisation is kept, `UserCodeAttemptThrottle` the only + count of wrong user codes.** Pass `oauth_device_clock_ms`; never `oauth_wall_clock_ms` to either, or the tests' clock + and the server's disagree. Never evict a live entry, never keep a device code unhashed. +- **The link page's post is checked in order**: `form_post_origin_is_accepted` (403, before the body is read), the + content type and form, the cookie (missing: the form again with a cookie, not counted), the throttle (429 before any + lookup), then the code. A code that does not read and a code no live pending entry has are the same 400 page and both + count. Never look a code up for a blocked address, and never tell a wrong code from an expired or answered one. +- **One browser at a time** (ADR-0806): `attach` on the right code, `renew` when the user signs in, `decide` only with + the attachment the pending entry carries; `release` whenever the sign-in ends without an answer (a failed start, a + refused account). A device sign-in is a `PendingAuthorisation` of kind `device_authorization` and goes through + `start_sign_in` and the `/authorize` form posts; only the consent page, `approve` and `deny` branch on the kind. +- **A device sign-in never creates an account**: `register` and `show_register` are 403, and the login page offers no + registration. +- **The consent page's warning is the first thing on it**, before the code and the client. Do not move it below them. +- **A redeemed device code is `expired_token`**: the store removes an approved entry when the poll takes it. The + approval is judged again with `account_sign_in_gate` and written with `grant_oauth_session`, never another path. +- `authorization_pending` is never logged (a device polls every five seconds). Log `client_id`, `user_id`, `device_id` + and, for the throttle, `client_key`; never a device code, a user code, the cookie or the query. + `POST /_merovingian/oauth2/register` is `register_oauth_client` (`OAuthClientRegistration.cpp`), answered before the authentication gate, and also from the general body cap so an oversized body is an OAuth 400 (ADR-0781). Rules: diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index e88e9c9e2..e275469f8 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -106,6 +106,7 @@ #include "merovingian/homeserver/OAuthAuthorization.hpp" #include "merovingian/homeserver/OAuthClientRegistration.hpp" #include "merovingian/homeserver/OAuthClock.hpp" +#include "merovingian/homeserver/OAuthDeviceAuthorization.hpp" #include "merovingian/homeserver/OAuthRevocation.hpp" #include "merovingian/homeserver/OAuthTokenEndpoint.hpp" #include "merovingian/homeserver/OperationResult.hpp" @@ -4063,6 +4064,8 @@ namespace "/_merovingian/oauth2/authorize", "/_merovingian/oauth2/token", "/_merovingian/oauth2/revoke", + "/_merovingian/oauth2/device", + "/_merovingian/oauth2/link", "/_merovingian/account", "/_matrix/client/v3/account/3pid/email/requestToken", "/_matrix/client/v3/account/3pid/msisdn/requestToken", @@ -4164,6 +4167,8 @@ namespace {"/_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" }, @@ -16543,6 +16548,26 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp return DispatchResult{DispatchResult::Status::complete, handle_oauth_revoke(rt, req), {}}; } } + // 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 + // handlers are OAuthDeviceAuthorization.cpp and OAuthAuthorization.cpp. + if (request_path == oauth::device_path.view() || request_path == oauth::link_path.view()) + { + auto const& oauth_config = rt.homeserver.config.server().oauth; + if (!oauth_config.enabled || !oauth_config.device_grant_enabled) + { + return dispatch_err(req, rt, 404U, "M_UNRECOGNIZED", "route not found"); + } + if (request_path == oauth::device_path.view() && req.method == "POST") + { + return DispatchResult{DispatchResult::Status::complete, handle_oauth_device_authorization(rt, req), {}}; + } + if (request_path == oauth::link_path.view() && (req.method == "GET" || req.method == "POST")) + { + return DispatchResult{DispatchResult::Status::complete, handle_oauth_link(rt, req), {}}; + } + } // GET and POST /_merovingian/account (spec "Account management"): the account pages, signed in with the account's // password and their own short session (ADR-0796), so they are answered before the access-token gate, 404 with the // OAuth 2.0 API off. Another method falls through to the 405 gate. The handler is AccountPage.cpp. diff --git a/src/homeserver/DeviceAuthorisationStore.cpp b/src/homeserver/DeviceAuthorisationStore.cpp new file mode 100644 index 000000000..5372a4091 --- /dev/null +++ b/src/homeserver/DeviceAuthorisationStore.cpp @@ -0,0 +1,275 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/DeviceAuthorisationStore.hpp" + +#include "merovingian/crypto/ConstantTime.hpp" +#include "merovingian/crypto/Random.hpp" +#include "merovingian/homeserver/OAuthSecret.hpp" +#include "merovingian/oauth/UserCode.hpp" + +#include +#include + +namespace merovingian::homeserver +{ + +DeviceAuthorisationStore::DeviceAuthorisationStore(RandomSource random) + : m_random{random ? std::move(random) : RandomSource{[](std::size_t size) { + return crypto::secure_random_bytes(size); + }}} +{ +} + +auto DeviceAuthorisationStore::forget(Entry const& entry) -> void +{ + m_by_user_code.erase(entry.user_code_hash); + if (auto const address = m_count_by_address.find(entry.authorisation.client_address_key); + address != m_count_by_address.end()) + { + if (--address->second == 0U) + { + m_count_by_address.erase(address); + } + } + if (auto const client = m_expiries_by_client.find(entry.authorisation.client_id); + client != m_expiries_by_client.end()) + { + if (auto const expiry = client->second.find(entry.authorisation.expires_at_ms); expiry != client->second.end()) + { + client->second.erase(expiry); + } + if (client->second.empty()) + { + m_expiries_by_client.erase(client); + } + } +} + +auto DeviceAuthorisationStore::erase_expired(std::uint64_t now_ms) -> void +{ + m_entries.erase_expired(now_ms, [this](Entry const& entry) { + forget(entry); + }); +} + +auto DeviceAuthorisationStore::draw_user_code() -> std::optional +{ + for (auto draw = std::size_t{0U}; draw < max_user_code_draws; ++draw) + { + auto const bytes = m_random(user_code_random_bytes); + if (!bytes.has_value()) + { + return std::nullopt; + } + auto code = oauth::user_code_from_bytes(std::span{*bytes}); + if (!code.has_value()) + { + continue; + } + auto const hash = oauth_secret_hash(*code); + if (!hash.has_value()) + { + return std::nullopt; + } + if (!m_by_user_code.contains(*hash)) + { + return code; + } + } + return std::nullopt; +} + +auto DeviceAuthorisationStore::create(std::string_view client_id, std::string_view scope, std::string_view device_id, + std::string_view client_address_key, std::uint64_t now_ms) + -> std::variant +{ + erase_expired(now_ms); + if (m_entries.size() >= max_entries) + { + return Refusal::store_full; + } + if (auto const address = m_count_by_address.find(client_address_key); + address != m_count_by_address.end() && address->second >= max_entries_per_address) + { + return Refusal::address_full; + } + auto device_code = make_oauth_secret(); + auto device_code_hash = device_code.has_value() ? oauth_secret_hash(*device_code) : std::nullopt; + auto user_code = draw_user_code(); + auto user_code_hash = user_code.has_value() ? oauth_secret_hash(*user_code) : std::nullopt; + if (!device_code_hash.has_value() || !user_code_hash.has_value()) + { + return Refusal::secret_unavailable; + } + auto entry = Entry{}; + auto& authorisation = entry.authorisation; + authorisation.client_id = std::string{client_id}; + authorisation.scope = std::string{scope}; + authorisation.device_id = std::string{device_id}; + authorisation.user_code = *user_code; + authorisation.client_address_key = std::string{client_address_key}; + authorisation.created_at_ms = now_ms; + authorisation.expires_at_ms = now_ms + lifetime_ms; + authorisation.interval_ms = initial_interval_ms; + entry.user_code_hash = *user_code_hash; + ++m_count_by_address[authorisation.client_address_key]; + m_expiries_by_client[authorisation.client_id].insert(authorisation.expires_at_ms); + m_by_user_code.emplace(std::move(*user_code_hash), *device_code_hash); + auto const expires_at_ms = authorisation.expires_at_ms; + m_entries.insert(std::move(*device_code_hash), std::move(entry), expires_at_ms); + return Started{std::move(*device_code), std::move(*user_code), lifetime_ms, initial_interval_ms}; +} + +auto DeviceAuthorisationStore::attach(std::string_view user_code, std::string_view browser_token, std::uint64_t now_ms) + -> std::variant +{ + erase_expired(now_ms); + auto const user_code_hash = oauth_secret_hash(user_code); + auto token_hash = oauth_secret_hash(browser_token); + if (!user_code_hash.has_value() || !token_hash.has_value() || browser_token.empty()) + { + return NotFound::unknown; + } + auto const indexed = m_by_user_code.find(*user_code_hash); + if (indexed == m_by_user_code.end()) + { + return NotFound::unknown; + } + auto* entry = m_entries.find(indexed->second); + if (entry == nullptr || entry->authorisation.state != DeviceAuthorisationState::pending) + { + return NotFound::unknown; + } + if (entry->attachment.has_value() && entry->attachment->lease_until_ms > now_ms && + !crypto::constant_time_equal(entry->attachment->browser_token_hash, *token_hash)) + { + return Busy{entry->attachment->lease_until_ms - now_ms}; + } + auto const id = ++m_next_attachment; + entry->attachment = Attachment{id, std::move(*token_hash), now_ms + attachment_lease_ms}; + return Attached{indexed->second, id, entry->authorisation}; +} + +auto DeviceAuthorisationStore::attached_entry(std::string_view key, std::uint64_t attachment, std::uint64_t now_ms) + -> Entry* +{ + erase_expired(now_ms); + auto* entry = m_entries.find(key); + if (entry == nullptr || entry->authorisation.state != DeviceAuthorisationState::pending || + !entry->attachment.has_value() || entry->attachment->id != attachment) + { + return nullptr; + } + return entry; +} + +auto DeviceAuthorisationStore::find_attached(std::string_view key, std::uint64_t attachment, std::uint64_t now_ms) + -> std::optional +{ + auto const* entry = attached_entry(key, attachment, now_ms); + if (entry == nullptr) + { + return std::nullopt; + } + return entry->authorisation; +} + +auto DeviceAuthorisationStore::renew(std::string_view key, std::uint64_t attachment, std::uint64_t now_ms) -> bool +{ + auto* entry = attached_entry(key, attachment, now_ms); + if (entry == nullptr) + { + return false; + } + entry->attachment->lease_until_ms = now_ms + attachment_lease_ms; + return true; +} + +auto DeviceAuthorisationStore::release(std::string_view key, std::uint64_t attachment) -> void +{ + auto* entry = m_entries.find(key); + if (entry != nullptr && entry->attachment.has_value() && entry->attachment->id == attachment) + { + entry->attachment.reset(); + } +} + +auto DeviceAuthorisationStore::decide(std::string_view key, std::uint64_t attachment, std::string_view user_id, + bool approve, std::uint64_t now_ms) -> bool +{ + auto* entry = attached_entry(key, attachment, now_ms); + if (entry == nullptr) + { + return false; + } + entry->authorisation.state = approve ? DeviceAuthorisationState::approved : DeviceAuthorisationState::denied; + entry->authorisation.user_id = std::string{user_id}; + entry->attachment.reset(); + return true; +} + +auto DeviceAuthorisationStore::poll(std::string_view device_code, std::string_view client_id, std::uint64_t now_ms) + -> PollResult +{ + erase_expired(now_ms); + auto const device_code_hash = oauth_secret_hash(device_code); + auto* entry = device_code_hash.has_value() ? m_entries.find(*device_code_hash) : nullptr; + if (entry == nullptr) + { + return PollResult{PollOutcome::expired_token, 0U, std::nullopt}; + } + auto& authorisation = entry->authorisation; + if (authorisation.client_id != client_id) + { + return PollResult{PollOutcome::wrong_client, 0U, std::nullopt}; + } + switch (authorisation.state) + { + case DeviceAuthorisationState::denied: + return PollResult{PollOutcome::access_denied, authorisation.interval_ms, std::nullopt}; + case DeviceAuthorisationState::approved: { + // Redeemed once: the entry leaves the store, so a second poll with the code is `expired_token` (ADR-0804). + auto taken = m_entries.erase(*device_code_hash); + if (!taken.has_value()) + { + return PollResult{PollOutcome::expired_token, 0U, std::nullopt}; + } + forget(*taken); + auto const interval_ms = taken->authorisation.interval_ms; + return PollResult{PollOutcome::approved, interval_ms, std::move(taken->authorisation)}; + } + case DeviceAuthorisationState::pending: + break; + } + auto const too_soon = + authorisation.last_poll_ms.has_value() && now_ms - *authorisation.last_poll_ms < authorisation.interval_ms; + authorisation.last_poll_ms = now_ms; + if (too_soon) + { + authorisation.interval_ms += slow_down_step_ms; + return PollResult{PollOutcome::slow_down, authorisation.interval_ms, std::nullopt}; + } + return PollResult{PollOutcome::authorization_pending, authorisation.interval_ms, std::nullopt}; +} + +auto DeviceAuthorisationStore::live_count_for_client(std::string_view client_id, std::uint64_t now_ms) -> std::size_t +{ + erase_expired(now_ms); + auto const client = m_expiries_by_client.find(client_id); + return client == m_expiries_by_client.end() ? 0U : client->second.size(); +} + +auto DeviceAuthorisationStore::holds_live_entry_for_client(std::string_view client_id, std::uint64_t now_ms) const + -> bool +{ + auto const client = m_expiries_by_client.find(client_id); + return client != m_expiries_by_client.end() && !client->second.empty() && *client->second.rbegin() > now_ms; +} + +auto DeviceAuthorisationStore::size() const noexcept -> std::size_t +{ + return m_entries.size(); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/OAuthAuthorization.cpp b/src/homeserver/OAuthAuthorization.cpp index d622a798f..8310f11a5 100644 --- a/src/homeserver/OAuthAuthorization.cpp +++ b/src/homeserver/OAuthAuthorization.cpp @@ -15,6 +15,7 @@ #include "merovingian/homeserver/AuthorizationCodeStore.hpp" #include "merovingian/homeserver/AuthorizationGrant.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/DeviceAuthorisationStore.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/LocalHttpRouter.hpp" @@ -36,6 +37,7 @@ #include "merovingian/oauth/AuthorizationRedirect.hpp" #include "merovingian/oauth/ClientMetadata.hpp" #include "merovingian/oauth/ConsentPageInput.hpp" +#include "merovingian/oauth/DeviceConsentPageInput.hpp" #include "merovingian/oauth/FormContentType.hpp" #include "merovingian/oauth/FormPostOrigin.hpp" #include "merovingian/oauth/GrantedScope.hpp" @@ -51,15 +53,18 @@ #include "merovingian/oauth/RedirectUriRules.hpp" #include "merovingian/oauth/ResponseMode.hpp" #include "merovingian/oauth/ScopeParser.hpp" +#include "merovingian/oauth/UserCode.hpp" #include "merovingian/observability/AuditCategory.hpp" #include "merovingian/observability/LogEventSeverity.hpp" #include "merovingian/observability/SingleLog.hpp" #include "merovingian/observability/StructuredLogField.hpp" +#include #include #include #include #include +#include #include #include #include @@ -82,6 +87,7 @@ namespace constexpr auto status_bad_request = std::uint16_t{400U}; constexpr auto status_unauthorized = std::uint16_t{401U}; constexpr auto status_forbidden = std::uint16_t{403U}; + constexpr auto status_conflict = std::uint16_t{409U}; constexpr auto status_too_many_requests = std::uint16_t{429U}; constexpr auto status_server_error = std::uint16_t{500U}; constexpr auto status_unavailable = std::uint16_t{503U}; @@ -256,13 +262,21 @@ namespace return runtime.config.security().registration.enabled; } - [[nodiscard]] auto login_form_input(HomeserverRuntime const& runtime, std::string_view pending_id) - -> oauth::AccountFormInput + [[nodiscard]] auto is_device_sign_in(PendingAuthorisation const& entry) noexcept -> bool + { + return entry.kind == PendingAuthorisationKind::device_authorization; + } + + // The login page offers registration only when it is enabled, and never for a device sign-in, which signs a + // device in to an account that exists (ADR-0806). + [[nodiscard]] auto login_form_input(HomeserverRuntime const& runtime, std::string_view pending_id, + PendingAuthorisationKind kind) -> oauth::AccountFormInput { auto input = oauth::AccountFormInput{}; input.server_name = runtime.config.server().server_name; input.pending_id = pending_id; - input.offer_other_form = registration_enabled(runtime); + input.offer_other_form = + registration_enabled(runtime) && kind != PendingAuthorisationKind::device_authorization; return input; } @@ -294,10 +308,64 @@ namespace return oauth_plain_page(status, oauth::registration_page(input)); } + // The answer when a device sign-in's entry ended, was answered, or was taken over by another browser (ADR-0806). + [[nodiscard]] auto device_sign_in_ended_page() -> LocalHttpResponse + { + return oauth_error_page_response( + status_bad_request, oauth::HtmlText{"Device sign-in ended"}, + oauth::HtmlText{"This device sign-in has expired, was already answered, or was continued in another " + "browser. Enter the code your device shows again."}); + } + + // Logs a device sign-in's answer: the client, the user and the device. Never the user code, the device code or + // the cookie. + auto log_device_answer(std::string_view event, PendingAuthorisation const& entry) -> void + { + log_oauth(event, + { + {"client_id", entry.client_id, false}, + {"user_id", entry.user_id, false}, + {"device_id", entry.device_id, false} + }, + observability::LogEventSeverity::info); + } + + // The consent page of a device sign-in (ADR-0806): the code, read again from the device authorisation this browser + // still holds, and the client, read again from its registration. No redirect follows, so the page carries the + // plain headers. + [[nodiscard]] auto device_consent_response(FormPost const& post, std::string_view user_id) -> LocalHttpResponse + { + auto& runtime = post.runtime.homeserver; + auto const device = runtime.oauth_device_authorisations.find_attached( + post.entry.device_authorisation_key, post.entry.device_attachment, oauth_device_clock_ms(runtime)); + auto const metadata = find_registered_oauth_client(runtime, post.entry.client_id); + if (!device.has_value() || !metadata.has_value()) + { + return device_sign_in_ended_page(); + } + auto input = oauth::DeviceConsentPageInput{}; + input.pending_id = post.pending_id; + input.user_code = device->user_code; + if (metadata->client_name().has_value()) + { + input.client_name = *metadata->client_name(); + } + input.client_host = metadata->client_uri().host_lower(); + input.user_id = user_id; + input.device_id = post.entry.device_id; + input.replaces_existing_device = + database::has_user_device(runtime.database.persistent_store, user_id, post.entry.device_id); + return oauth_plain_page(status_ok, oauth::device_consent_page(input)); + } + // The consent page for the pending authorisation `post` names, now authenticated as `user_id`. Its policy allows // the form post to be answered by a redirect to the matched redirect URI, and to nothing else (ADR-0772). [[nodiscard]] auto consent_response(FormPost const& post, std::string_view user_id) -> LocalHttpResponse { + if (is_device_sign_in(post.entry)) + { + return device_consent_response(post, user_id); + } auto const& runtime = post.runtime.homeserver; if (is_hand_off(post.entry)) { @@ -349,13 +417,22 @@ namespace { return expired_page(); } + // A device sign-in keeps its hold on the device authorisation while its user is active (ADR-0806); one taken + // over meanwhile by another browser ends here. + auto& devices = post.runtime.homeserver.oauth_device_authorisations; + if (is_device_sign_in(post.entry) && + !devices.renew(post.entry.device_authorisation_key, post.entry.device_attachment, + oauth_device_clock_ms(post.runtime.homeserver))) + { + return device_sign_in_ended_page(); + } return consent_response(post, user_id); } [[nodiscard]] auto handle_login(FormPost const& post, core::FormFields const& fields) -> LocalHttpResponse { auto& runtime = post.runtime.homeserver; - auto input = login_form_input(runtime, post.pending_id); + auto input = login_form_input(runtime, post.pending_id, post.entry.kind); auto const username = fields.find(oauth::username_field.view()); auto const password = fields.find(oauth::password_field.view()); if (!username.has_value() || username->empty() || !password.has_value() || password->empty()) @@ -450,7 +527,7 @@ namespace auto& runtime = post.runtime.homeserver; if (!registration_enabled(runtime)) { - auto input = login_form_input(runtime, post.pending_id); + auto input = login_form_input(runtime, post.pending_id, post.entry.kind); input.notice = registration_closed_notice(); return login_page_response(status_forbidden, input); } @@ -551,6 +628,39 @@ namespace return response; } + // `approve` or `deny` of a device sign-in, its pending entry already spent (ADR-0806): the device authorisation is + // answered if this browser still holds it, and the browser stays here either way. An approval first judges the + // account again; a refused account leaves the device authorisation pending and lets another browser take it. + [[nodiscard]] auto finish_device_sign_in(ClientServerRuntime& rt, PendingAuthorisation const& consumed, + bool approve) -> LocalHttpResponse + { + auto& runtime = rt.homeserver; + auto& devices = runtime.oauth_device_authorisations; + if (consumed.user_id.empty()) + { + devices.release(consumed.device_authorisation_key, consumed.device_attachment); + return device_sign_in_ended_page(); + } + if (approve && account_sign_in_gate(runtime, consumed.user_id, consumed.device_id) != Outcome::verified) + { + devices.release(consumed.device_authorisation_key, consumed.device_attachment); + log_refused(consumed.client_id, oauth::error_access_denied); + return oauth_error_page_response(status_forbidden, oauth::HtmlText{"Sign-in refused"}, + oauth::HtmlText{"This account cannot sign in."}); + } + if (!devices.decide(consumed.device_authorisation_key, consumed.device_attachment, consumed.user_id, approve, + oauth_device_clock_ms(runtime))) + { + return device_sign_in_ended_page(); + } + auto const event = + approve ? std::string_view{"oauth.device.approved"} : std::string_view{"oauth.device.denied"}; + log_device_answer(event, consumed); + append_local_audit(runtime.database, observability::AuditCategory::auth, event, consumed.user_id, + consumed.client_id, consumed.device_id); + return oauth_plain_page(status_ok, approve ? oauth::device_approved_page() : oauth::device_denied_page()); + } + // `approve`: the entry must hold a verified user. It is spent, the account is judged again, and a code bound to the // whole request and the user is sent to the client. [[nodiscard]] auto handle_approve(FormPost const& post) -> LocalHttpResponse @@ -570,6 +680,10 @@ namespace { return finish_hand_off(post.runtime, *consumed); } + if (is_device_sign_in(*consumed)) + { + return finish_device_sign_in(post.runtime, *consumed, true); + } auto const target = client_target(runtime, *consumed); if (!target.has_value()) { @@ -632,6 +746,10 @@ namespace log_hand_off("oauth.hand_off.cancelled", consumed->user_id, observability::LogEventSeverity::info); return oauth_plain_page(status_ok, oauth::hand_off_cancelled_page()); } + if (is_device_sign_in(*consumed)) + { + return finish_device_sign_in(post.runtime, *consumed, false); + } auto const target = client_target(runtime, *consumed); if (!target.has_value()) { @@ -699,6 +817,13 @@ namespace } auto const post = FormPost{rt, request, std::string{*pending_id}, std::move(*browser_token), std::move(*entry)}; auto const action = fields->find(oauth::action_field.view()).value_or(std::string_view{}); + // A device sign-in signs a device in to an account that exists; it never creates one (ADR-0806). + if (is_device_sign_in(post.entry) && + (action == oauth::action_register.view() || action == oauth::action_show_register.view())) + { + return oauth_error_page_response(status_forbidden, oauth::HtmlText{"Form refused"}, + oauth::HtmlText{"A device can only be signed in to an existing account."}); + } if (action == oauth::action_login.view()) { return handle_login(post, *fields); @@ -711,7 +836,7 @@ namespace { if (!registration_enabled(runtime)) { - auto input = login_form_input(runtime, post.pending_id); + auto input = login_form_input(runtime, post.pending_id, post.entry.kind); input.notice = registration_closed_notice(); return login_page_response(status_ok, input); } @@ -719,7 +844,7 @@ namespace } if (action == oauth::action_show_login.view()) { - return login_page_response(status_ok, login_form_input(runtime, post.pending_id)); + return login_page_response(status_ok, login_form_input(runtime, post.pending_id, post.entry.kind)); } if (action == oauth::action_approve.view()) { @@ -773,6 +898,7 @@ namespace false}; } auto const hint = authorisation.login_hint; + auto const kind = authorisation.kind; auto created = runtime.oauth_pending_authorisations.create( std::move(authorisation), *browser_token, rate_limit_client_key(request, runtime.config.server()), oauth_wall_clock_ms()); @@ -789,7 +915,7 @@ namespace { return registration_page_response(status_ok, registration_form_input(runtime, *pending_id)); } - auto input = login_form_input(runtime, *pending_id); + auto input = login_form_input(runtime, *pending_id, kind); if (hint.has_value()) { input.username = *hint; @@ -933,8 +1059,204 @@ namespace return std::move(start.response); } + // The link page with `status`, a fixed `error` when there is one, and the code to prefill. + [[nodiscard]] auto link_page_response(std::uint16_t status, std::optional user_code, + std::optional const& error) -> LocalHttpResponse + { + return oauth_plain_page(status, oauth::device_link_page(user_code, error)); + } + + // This browser's cookie value, reused when the request carries a well-formed one, else fresh, and the + // `Set-Cookie` header that (re)sets it; nullopt when neither a value nor the header could be made. + struct BrowserCookie final + { + std::string token; + std::string set_cookie; + }; + + [[nodiscard]] auto browser_cookie(LocalHttpRequest const& request) -> std::optional + { + auto token = request_secret_cookie(request, oauth_browser_cookie_name); + if (!token.has_value()) + { + token = make_oauth_secret(); + } + if (!token.has_value()) + { + return std::nullopt; + } + auto cookie = core::host_cookie(oauth_browser_cookie_name, *token, core::CookieSameSite::lax, + oauth_browser_cookie_max_age_seconds); + auto* const header = std::get_if(&cookie); + if (header == nullptr) + { + return std::nullopt; + } + return BrowserCookie{std::move(*token), std::move(*header)}; + } + + [[nodiscard]] auto link_unavailable_page() -> LocalHttpResponse + { + return oauth_error_page_response(status_unavailable, oauth::HtmlText{"Sign-in is not available"}, + oauth::HtmlText{"The server cannot start a sign-in now. Try again later."}); + } + + // `GET /_merovingian/oauth2/link`: the form, prefilled from `user_code` only when it reads as a code, with the + // browser cookie the form post needs. Nothing is looked up: the user confirms the code by sending the form. + [[nodiscard]] auto handle_link_get(LocalHttpRequest const& request) -> LocalHttpResponse + { + auto parsed = core::FormFields::parse(request_target_query(request.target)); + auto const* fields = std::get_if(&parsed); + auto prefill = std::optional{}; + if (fields != nullptr) + { + if (auto const typed = fields->find("user_code"); typed.has_value()) + { + prefill = oauth::normalise_user_code(*typed); + } + } + auto const cookie = browser_cookie(request); + if (!cookie.has_value()) + { + return link_unavailable_page(); + } + auto response = link_page_response(status_ok, prefill, std::nullopt); + response.headers.emplace_back("Set-Cookie", cookie->set_cookie); + return response; + } + + // A wrong or expired code, counted against the address. The block is logged once, when it is reached. + [[nodiscard]] auto wrong_code(ClientServerRuntime& rt, std::string_view client_key, std::uint64_t now_ms) + -> LocalHttpResponse + { + if (rt.homeserver.oauth_user_code_attempts.record_wrong(client_key, now_ms)) + { + log_oauth("oauth.device.throttled", + { + {"client_key", std::string{client_key}, false} + }, + observability::LogEventSeverity::warning); + } + return link_page_response(status_bad_request, std::nullopt, + oauth::HtmlText{"That code is not right, or it has expired. Check the code your " + "device shows and try again."}); + } + + // A wait in milliseconds as retry_after_seconds takes it; the device grant's waits are at most ten minutes. + [[nodiscard]] auto clamped_retry_ms(std::uint64_t retry_after_ms) noexcept -> std::uint32_t + { + return static_cast( + std::min(retry_after_ms, std::numeric_limits::max())); + } + + // `POST /_merovingian/oauth2/link`: the code the user typed (ADR-0805, ADR-0806). + [[nodiscard]] auto handle_link_post(ClientServerRuntime& rt, LocalHttpRequest const& request) -> LocalHttpResponse + { + auto& runtime = rt.homeserver; + auto base = oauth::OAuthBaseUrl::read(runtime.config.server().public_baseurl); + auto const* base_url = std::get_if(&base); + if (base_url == nullptr) + { + return link_unavailable_page(); + } + // Before anything is read: another site's post is refused whatever it carries (ADR-0784). + if (!oauth::form_post_origin_is_accepted(*base_url, single_request_header(request, "Origin"), + single_request_header(request, "Sec-Fetch-Site"))) + { + return oauth_error_page_response(status_forbidden, oauth::HtmlText{"Form refused"}, + oauth::HtmlText{"This form was not sent from a page of this server."}); + } + auto const content_type = single_request_header(request, "Content-Type"); + if (!content_type.has_value() || !oauth::page_form_content_type_is_accepted(*content_type)) + { + return oauth_error_page_response(status_bad_request, oauth::HtmlText{"Form refused"}, + oauth::HtmlText{"This form could not be read."}); + } + auto parsed = core::FormFields::parse(request.body); + auto const* fields = std::get_if(&parsed); + if (fields == nullptr) + { + return oauth_error_page_response(status_bad_request, oauth::HtmlText{"Form refused"}, + oauth::HtmlText{"This form could not be read."}); + } + // A post without the page's cookie is not a guess: it is not counted, and the page is sent again with one. + auto browser_token = request_secret_cookie(request, oauth_browser_cookie_name); + if (!browser_token.has_value()) + { + auto const cookie = browser_cookie(request); + if (!cookie.has_value()) + { + return link_unavailable_page(); + } + auto response = + link_page_response(status_bad_request, std::nullopt, + oauth::HtmlText{"Your browser did not send the cookie this page sets. Enter the " + "code again; if this repeats, allow cookies for this server."}); + response.headers.emplace_back("Set-Cookie", cookie->set_cookie); + return response; + } + auto const client_key = rate_limit_client_key(request, runtime.config.server()); + auto const now_ms = oauth_device_clock_ms(runtime); + // The throttle comes before the lookup: a blocked address is not told whether its code is right. + if (auto const blocked = runtime.oauth_user_code_attempts.blocked_for_ms(client_key, now_ms); + blocked.has_value()) + { + auto const seconds = retry_after_seconds(clamped_retry_ms(*blocked)); + auto response = link_page_response( + status_too_many_requests, std::nullopt, + oauth::HtmlText{"Too many wrong codes were entered from your network. Wait a few minutes and try " + "again."}); + response.headers.emplace_back("Retry-After", std::to_string(seconds)); + return response; + } + auto const typed = fields->find(oauth::user_code_field.view()); + auto const user_code = typed.has_value() ? oauth::normalise_user_code(*typed) : std::nullopt; + if (!user_code.has_value()) + { + return wrong_code(rt, client_key, now_ms); + } + auto attached = runtime.oauth_device_authorisations.attach(*user_code, *browser_token, now_ms); + if (std::holds_alternative(attached)) + { + return wrong_code(rt, client_key, now_ms); + } + if (auto const* busy = std::get_if(&attached); busy != nullptr) + { + auto const seconds = retry_after_seconds(clamped_retry_ms(busy->retry_after_ms)); + auto response = link_page_response( + status_conflict, std::nullopt, + oauth::HtmlText{"This code is being used to sign in from another browser right now. Try again in two " + "minutes."}); + response.headers.emplace_back("Retry-After", std::to_string(seconds)); + return response; + } + auto& hold = std::get(attached); + auto authorisation = PendingAuthorisation{}; + authorisation.kind = PendingAuthorisationKind::device_authorization; + authorisation.client_id = hold.authorisation.client_id; + authorisation.device_id = hold.authorisation.device_id; + authorisation.scope = hold.authorisation.scope; + authorisation.device_authorisation_key = hold.key; + authorisation.device_attachment = hold.attachment; + auto start = start_sign_in(rt, request, std::move(authorisation), FirstPage::login); + if (!start.started) + { + runtime.oauth_device_authorisations.release(hold.key, hold.attachment); + } + return std::move(start.response); + } + } // namespace +auto handle_oauth_link(ClientServerRuntime& runtime, LocalHttpRequest const& request) -> LocalHttpResponse +{ + if (request.method == "POST") + { + return handle_link_post(runtime, request); + } + return handle_link_get(request); +} + auto handle_login_hand_off(ClientServerRuntime& rt, LocalHttpRequest const& request) -> LocalHttpResponse { auto& runtime = rt.homeserver; diff --git a/src/homeserver/OAuthClientRegistration.cpp b/src/homeserver/OAuthClientRegistration.cpp index fba1fe6fd..8c09213ce 100644 --- a/src/homeserver/OAuthClientRegistration.cpp +++ b/src/homeserver/OAuthClientRegistration.cpp @@ -16,6 +16,7 @@ #include "merovingian/database/PersistentOAuthClient.hpp" #include "merovingian/homeserver/AuthorizationCodeStore.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/DeviceAuthorisationStore.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/OAuthClock.hpp" #include "merovingian/homeserver/OAuthJsonResponse.hpp" @@ -42,9 +43,9 @@ namespace merovingian::homeserver { // The evictions one registration may make must fit in the idle-client walk after it skipped every client a pending -// authorisation or an unredeemed code can name (ADR-0782). +// authorisation, an unredeemed code or a device authorisation can name (ADR-0782, ADR-0805). static_assert(PendingAuthorisationStore::max_entries + AuthorizationCodeStore::max_codes + - max_oauth_client_evictions_per_registration <= + DeviceAuthorisationStore::max_entries + max_oauth_client_evictions_per_registration <= database::max_idle_client_rows_examined); namespace { diff --git a/src/homeserver/OAuthClock.cpp b/src/homeserver/OAuthClock.cpp index a94f070e7..a9dcc992d 100644 --- a/src/homeserver/OAuthClock.cpp +++ b/src/homeserver/OAuthClock.cpp @@ -3,6 +3,8 @@ #include "merovingian/homeserver/OAuthClock.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" + #include #include @@ -16,4 +18,9 @@ auto oauth_wall_clock_ms() -> std::uint64_t return now.count() < 0 ? std::uint64_t{0U} : static_cast(now.count()); } +auto oauth_device_clock_ms(HomeserverRuntime const& runtime) -> std::uint64_t +{ + return oauth_wall_clock_ms() + runtime.test_device_grant_clock_advance_ms; +} + } // namespace merovingian::homeserver diff --git a/src/homeserver/OAuthDeviceAuthorization.cpp b/src/homeserver/OAuthDeviceAuthorization.cpp new file mode 100644 index 000000000..8d94096a2 --- /dev/null +++ b/src/homeserver/OAuthDeviceAuthorization.cpp @@ -0,0 +1,165 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/OAuthDeviceAuthorization.hpp" + +#include "merovingian/canonicaljson/Value.hpp" +#include "merovingian/core/FormFields.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/DeviceAuthorisationStore.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpRouter.hpp" +#include "merovingian/homeserver/OAuthClientCredentials.hpp" +#include "merovingian/homeserver/OAuthClientRegistration.hpp" +#include "merovingian/homeserver/OAuthClock.hpp" +#include "merovingian/homeserver/OAuthJsonResponse.hpp" +#include "merovingian/homeserver/RequestHeaders.hpp" +#include "merovingian/oauth/ClientMetadata.hpp" +#include "merovingian/oauth/FormContentType.hpp" +#include "merovingian/oauth/GrantedScope.hpp" +#include "merovingian/oauth/OAuthBaseUrl.hpp" +#include "merovingian/oauth/OAuthErrorCodes.hpp" +#include "merovingian/oauth/OAuthPaths.hpp" +#include "merovingian/oauth/OAuthRefusal.hpp" +#include "merovingian/oauth/ScopeParser.hpp" +#include "merovingian/oauth/UserCode.hpp" +#include "merovingian/observability/LogEventSeverity.hpp" +#include "merovingian/observability/SingleLog.hpp" +#include "merovingian/observability/StructuredLogField.hpp" + +#include +#include +#include +#include +#include +#include + +namespace merovingian::homeserver +{ + +namespace +{ + + constexpr auto status_ok = std::uint16_t{200U}; + constexpr auto status_bad_request = std::uint16_t{400U}; + constexpr auto status_server_error = std::uint16_t{500U}; + constexpr auto status_unavailable = std::uint16_t{503U}; + constexpr auto ms_per_second = std::uint64_t{1000U}; + + // Logs a refused device authorization request: the wire error and the client ID when one was sent. Never a value + // the request carried beyond that. + auto log_refused(std::string_view error_code, std::string_view client_id) -> void + { + auto fields = std::vector{ + {"error", std::string{error_code}, false} + }; + if (!client_id.empty()) + { + fields.push_back({"client_id", std::string{client_id}, false}); + } + observability::log_diagnostic("oauth", "oauth.device.refused", std::move(fields), + observability::LogEventSeverity::debug); + } + + [[nodiscard]] auto seconds_of(std::uint64_t milliseconds) -> std::int64_t + { + return static_cast(milliseconds / ms_per_second); + } + +} // namespace + +auto handle_oauth_device_authorization(ClientServerRuntime& rt, LocalHttpRequest const& request) -> LocalHttpResponse +{ + auto& runtime = rt.homeserver; + if (!oauth::api_form_content_type_is_accepted(request_header(request, "Content-Type"))) + { + log_refused(oauth::error_invalid_request, {}); + return oauth_error_response(status_bad_request, oauth::error_invalid_request, + "The body must be application/x-www-form-urlencoded."); + } + auto parsed = core::FormFields::parse(request.body); + auto const* const fields = std::get_if(&parsed); + if (fields == nullptr) + { + log_refused(oauth::error_invalid_request, {}); + return oauth_error_response(status_bad_request, oauth::error_invalid_request, "The body is malformed."); + } + if (auto credentials_refusal = oauth_client_credentials_refusal(request, *fields); credentials_refusal.has_value()) + { + log_refused(oauth::error_invalid_client, {}); + return std::move(*credentials_refusal); + } + auto const client_id = fields->find("client_id"); + if (!client_id.has_value() || client_id->empty()) + { + log_refused(oauth::error_invalid_request, {}); + return oauth_error_response(status_bad_request, oauth::error_invalid_request, "The request lacks client_id."); + } + auto const client = find_registered_oauth_client(runtime, *client_id); + if (!client.has_value()) + { + log_refused(oauth::error_invalid_client, *client_id); + return oauth_error_response(status_bad_request, oauth::error_invalid_client, "The client is not registered."); + } + if (!client->has_grant_type(oauth::grant_type_device_code)) + { + log_refused(oauth::error_unauthorized_client, *client_id); + return oauth_error_response(status_bad_request, oauth::error_unauthorized_client, + "The client is not registered for the device code grant."); + } + auto scope = oauth::parse_scope(fields->find("scope").value_or(std::string_view{})); + if (auto const* refused = std::get_if(&scope); refused != nullptr) + { + log_refused(refused->error_code, *client_id); + return oauth_error_response(status_bad_request, *refused); + } + auto const& granted = std::get(scope); + auto base = oauth::OAuthBaseUrl::read(runtime.config.server().public_baseurl); + auto const* const base_url = std::get_if(&base); + if (base_url == nullptr) + { + log_refused(oauth::error_server_error, *client_id); + return oauth_error_response(status_server_error, oauth::error_server_error, + "The server is not configured for the device code grant."); + } + + auto created = runtime.oauth_device_authorisations.create(*client_id, granted.scope, granted.device_id, + rate_limit_client_key(request, runtime.config.server()), + oauth_device_clock_ms(runtime)); + if (auto const* refusal = std::get_if(&created); refusal != nullptr) + { + if (*refusal == DeviceAuthorisationStore::Refusal::secret_unavailable) + { + log_refused(oauth::error_server_error, *client_id); + return oauth_error_response(status_server_error, oauth::error_server_error, + "The server could not start the device authorisation."); + } + log_refused(oauth::error_temporarily_unavailable, *client_id); + return oauth_error_response(status_unavailable, oauth::error_temporarily_unavailable, + "Too many device sign-ins are in progress. Try again in a few minutes."); + } + auto const& started = std::get(created); + auto const shown_code = oauth::display_user_code(started.user_code); + auto const verification_uri = base_url->url(oauth::link_path); + // The shown code has only capital consonants and a dash, all unreserved: it needs no percent-encoding. + auto const verification_uri_complete = verification_uri + "?user_code=" + shown_code; + + observability::log_diagnostic("oauth", "oauth.device.started", + { + {"client_id", std::string{*client_id}, false} + }, + observability::LogEventSeverity::info); + + auto object = canonicaljson::Object{}; + object.push_back(canonicaljson::make_member("device_code", canonicaljson::Value{started.device_code})); + object.push_back(canonicaljson::make_member("expires_in", canonicaljson::Value{seconds_of(started.expires_in_ms)})); + object.push_back(canonicaljson::make_member("interval", canonicaljson::Value{seconds_of(started.interval_ms)})); + object.push_back(canonicaljson::make_member("user_code", canonicaljson::Value{shown_code})); + object.push_back(canonicaljson::make_member("verification_uri", canonicaljson::Value{verification_uri})); + object.push_back( + canonicaljson::make_member("verification_uri_complete", canonicaljson::Value{verification_uri_complete})); + return oauth_json_response(status_ok, canonicaljson::Value{std::move(object)}); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/OAuthTokenEndpoint.cpp b/src/homeserver/OAuthTokenEndpoint.cpp index 155e2527a..cf7862de1 100644 --- a/src/homeserver/OAuthTokenEndpoint.cpp +++ b/src/homeserver/OAuthTokenEndpoint.cpp @@ -12,6 +12,7 @@ #include "merovingian/homeserver/AuthorizationCodeStore.hpp" #include "merovingian/homeserver/ClientDeviceSessions.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/DeviceAuthorisationStore.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/OAuthClientCredentials.hpp" @@ -211,6 +212,90 @@ namespace return token_answer(session, oauth_expires_in(runtime), grant.scope); } + // RFC 8628 section 3.4 and 3.5 (ADR-0804): every refusal is 400 with the section's code, except a failed + // storage write (500). The device code is spent once the store hands back an approval, whatever follows. + [[nodiscard]] auto device_code_grant(ClientServerRuntime& rt, core::FormFields const& fields) -> LocalHttpResponse + { + constexpr auto grant_type = oauth::grant_type_device_code; + auto& runtime = rt.homeserver; + auto const client_id = fields.find("client_id"); + auto const device_code = fields.find("device_code"); + auto const refuse = [&](std::uint16_t status, std::string_view error_code, + std::string_view description) -> LocalHttpResponse { + log_refused(grant_type, error_code, client_id.value_or(std::string_view{})); + return oauth_error_response(status, error_code, description); + }; + // RFC 6749 section 3.1: a parameter sent without a value is treated as omitted. + if (!client_id.has_value() || client_id->empty() || !device_code.has_value() || device_code->empty()) + { + return refuse(status_bad_request, oauth::error_invalid_request, + "The request lacks client_id or device_code."); + } + auto const client = find_registered_oauth_client(runtime, *client_id); + if (!client.has_value()) + { + return refuse(status_bad_request, oauth::error_invalid_client, "The client is not registered."); + } + if (!client->has_grant_type(grant_type)) + { + return refuse(status_bad_request, oauth::error_unauthorized_client, + "The client is not registered for the device code grant."); + } + auto const polled = + runtime.oauth_device_authorisations.poll(*device_code, *client_id, oauth_device_clock_ms(runtime)); + using PollOutcome = DeviceAuthorisationStore::PollOutcome; + switch (polled.outcome) + { + case PollOutcome::expired_token: + return refuse(status_bad_request, oauth::error_expired_token, + "The device code is unknown, expired or already used."); + case PollOutcome::wrong_client: + return refuse(status_bad_request, oauth::error_invalid_grant, + "The device code was not issued to this client."); + case PollOutcome::access_denied: + return refuse(status_bad_request, oauth::error_access_denied, "The user denied the request."); + case PollOutcome::slow_down: + return refuse(status_bad_request, oauth::error_slow_down, "Polling too often; wait longer between polls."); + case PollOutcome::authorization_pending: + // Not logged: a device polls every few seconds until the user answers. + return oauth_error_response(status_bad_request, oauth::error_authorization_pending, + "The user has not answered yet."); + case PollOutcome::approved: + break; + } + if (!polled.authorisation.has_value()) + { + return refuse(status_bad_request, oauth::error_expired_token, + "The device code is unknown, expired or already used."); + } + auto const& approved = *polled.authorisation; + if (account_sign_in_gate(runtime, approved.user_id, approved.device_id) != + PasswordLoginVerification::Outcome::verified) + { + return refuse(status_bad_request, oauth::error_invalid_grant, "The account cannot sign in."); + } + auto request = OAuthGrantRequest{}; + request.user_id = approved.user_id; + request.device_id = approved.device_id; + request.client_id = approved.client_id; + request.scope = approved.scope; + request.display_name = device_display_name(rt, *client); + request.created_at_ms = runtime.oauth_codes.next_session_created_at_ms(oauth_wall_clock_ms()); + auto const session = grant_oauth_session(runtime, request); + if (!session.ok) + { + if (session.status >= first_server_error_status) + { + return refuse(status_server_error, oauth::error_server_error, + "The server could not complete the grant."); + } + return refuse(status_bad_request, oauth::error_invalid_grant, "The session cannot be granted."); + } + remember_signed_in_device(rt, session.user_id, session.device_id, request.display_name, + SignedInDevice::new_session); + return token_answer(session, oauth_expires_in(runtime), approved.scope); + } + [[nodiscard]] auto refresh_token_grant(ClientServerRuntime& rt, core::FormFields const& fields) -> LocalHttpResponse { constexpr auto grant_type = oauth::grant_type_refresh_token; @@ -293,6 +378,11 @@ auto handle_oauth_token(ClientServerRuntime& runtime, LocalHttpRequest const& re { return refresh_token_grant(runtime, *fields); } + // Served only with the device grant on (ADR-0804); off, the grant type is as unknown as any other. + if (*grant_type == oauth::grant_type_device_code && runtime.homeserver.config.server().oauth.device_grant_enabled) + { + return device_code_grant(runtime, *fields); + } log_refused({}, oauth::error_unsupported_grant_type, {}); return oauth_error_response(status_bad_request, oauth::error_unsupported_grant_type, "The grant_type is not supported."); diff --git a/src/homeserver/RetentionSweep.cpp b/src/homeserver/RetentionSweep.cpp index 9c4e8629e..3719e639a 100644 --- a/src/homeserver/RetentionSweep.cpp +++ b/src/homeserver/RetentionSweep.cpp @@ -9,6 +9,7 @@ #include "merovingian/database/PersistentStoreBackend.hpp" #include "merovingian/database/UnusableCredentials.hpp" #include "merovingian/homeserver/AuthorizationCodeStore.hpp" +#include "merovingian/homeserver/DeviceAuthorisationStore.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/KeyServerCache.hpp" #include "merovingian/homeserver/LocalServices.hpp" @@ -32,9 +33,11 @@ namespace merovingian::homeserver { -// A batch of the client sweep must fit in the idle-client walk after it skipped every client a pending authorisation -// or an unredeemed code can name, or a walk that stopped at its bound could hide a client that may go (ADR-0782). -static_assert(PendingAuthorisationStore::max_entries + AuthorizationCodeStore::max_codes + retention_batch_rows <= +// A batch of the client sweep must fit in the idle-client walk after it skipped every client a pending authorisation, +// an unredeemed code or a device authorisation can name, or a walk that stopped at its bound could hide a client that +// may go (ADR-0782, ADR-0805). +static_assert(PendingAuthorisationStore::max_entries + AuthorizationCodeStore::max_codes + + DeviceAuthorisationStore::max_entries + retention_batch_rows <= database::max_idle_client_rows_examined); namespace @@ -229,7 +232,9 @@ auto oauth_client_has_pending_authorisation(HomeserverRuntime const& runtime, st std::uint64_t now_ms) -> bool { return runtime.oauth_pending_authorisations.holds_live_entry_for_client(client_id, now_ms) || - runtime.oauth_codes.holds_unredeemed_code_for_client(client_id, now_ms); + runtime.oauth_codes.holds_unredeemed_code_for_client(client_id, now_ms) || + runtime.oauth_device_authorisations.holds_live_entry_for_client( + client_id, now_ms + runtime.test_device_grant_clock_advance_ms); } auto run_retention_sweep(HomeserverRuntime& runtime, std::chrono::system_clock::time_point now, StopFlag const& stop) diff --git a/src/homeserver/UserCodeAttemptThrottle.cpp b/src/homeserver/UserCodeAttemptThrottle.cpp new file mode 100644 index 000000000..69a170472 --- /dev/null +++ b/src/homeserver/UserCodeAttemptThrottle.cpp @@ -0,0 +1,64 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/UserCodeAttemptThrottle.hpp" + +namespace merovingian::homeserver +{ + +auto UserCodeAttemptThrottle::erase_ended(std::uint64_t now_ms) -> void +{ + while (!m_by_end.empty() && m_by_end.begin()->first.first <= now_ms) + { + m_windows.erase(m_by_end.begin()->second); + m_by_end.erase(m_by_end.begin()); + } +} + +auto UserCodeAttemptThrottle::blocked_for_ms(std::string_view client_key, std::uint64_t now_ms) + -> std::optional +{ + erase_ended(now_ms); + if (auto const window = m_windows.find(client_key); window != m_windows.end()) + { + if (window->second.wrong >= max_wrong_codes) + { + return window->second.ends_at_ms - now_ms; + } + return std::nullopt; + } + if (m_windows.size() >= max_addresses && !m_by_end.empty()) + { + return m_by_end.begin()->first.first - now_ms; + } + return std::nullopt; +} + +auto UserCodeAttemptThrottle::record_wrong(std::string_view client_key, std::uint64_t now_ms) -> bool +{ + erase_ended(now_ms); + auto window = m_windows.find(client_key); + if (window == m_windows.end()) + { + if (m_windows.size() >= max_addresses) + { + return false; + } + auto const fresh = Window{now_ms + window_ms, m_next_sequence++, 0U}; + window = m_windows.emplace(std::string{client_key}, fresh).first; + m_by_end.emplace(Order{fresh.ends_at_ms, fresh.sequence}, std::string{client_key}); + } + if (window->second.wrong >= max_wrong_codes) + { + return false; + } + ++window->second.wrong; + return window->second.wrong == max_wrong_codes; +} + +auto UserCodeAttemptThrottle::size() const noexcept -> std::size_t +{ + return m_windows.size(); +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/meson.build b/src/homeserver/meson.build index c7b7765d8..7f8385b39 100644 --- a/src/homeserver/meson.build +++ b/src/homeserver/meson.build @@ -12,6 +12,8 @@ homeserver_sources = files( 'CrossSigningResetApprovals.cpp', 'OAuthSecret.cpp', 'PendingAuthorisationStore.cpp', + 'DeviceAuthorisationStore.cpp', + 'UserCodeAttemptThrottle.cpp', 'RequestHeaders.cpp', 'SafetyReportIndex.cpp', 'RetentionSweep.cpp', @@ -39,6 +41,7 @@ homeserver_sources = files( 'OAuthClientCredentials.cpp', 'OAuthClientRegistration.cpp', 'OAuthClock.cpp', + 'OAuthDeviceAuthorization.cpp', 'OAuthJsonResponse.cpp', 'OAuthPageResponse.cpp', 'OAuthRevocation.cpp', diff --git a/src/oauth/AGENTS.md b/src/oauth/AGENTS.md index 383ae68f8..54d032fe0 100644 --- a/src/oauth/AGENTS.md +++ b/src/oauth/AGENTS.md @@ -23,8 +23,9 @@ Pure functions and value types for the built-in OAuth 2.0 API | `OAuthBaseUrl.cpp` | `OAuthBaseUrl::read`: `server.public_baseurl` as an `https` URL with a host and no query; `issuer()` (one trailing slash) and `url(PagePath)` (ADR-0773) | | `ServerMetadata.cpp`, `ServerMetadataOptions.hpp` | `server_metadata`: the `auth_metadata` document, device grant, `prompt=create` and account management fields only when their option is on | | `AuthorizationRedirect.cpp` | `percent_encode_redirect_value`, `authorization_redirect_address`: the answer's parameters percent-encoded (everything but the unreserved characters) into the query or the fragment of a matched redirect URI | -| `AuthorizationPages.cpp`, `AccountFormInput.hpp`, `ConsentPageInput.hpp` | The login, registration, consent and error pages of `/_merovingian/oauth2/authorize`, and the form field and action names they post. A value `HtmlText::escape` refuses is replaced by fixed text | +| `AuthorizationPages.cpp`, `AccountFormInput.hpp`, `ConsentPageInput.hpp`, `DeviceConsentPageInput.hpp` | The login, registration, consent and error pages of `/_merovingian/oauth2/authorize`, the device grant's link, consent and answer pages (ADR-0806: the consent page's warning comes first), and the form field and action names they post. A value `HtmlText::escape` refuses is replaced by fixed text | | `AccountPages.cpp`, `AccountPageFrame.hpp`, `AccountDeviceRow.hpp`, `AccountSignInInput.hpp` | The account pages of `/_merovingian/account` (ADR-0796): sign-in, overview, devices, one device, device sign-out, password, deactivation, cross-signing reset and result pages; the six spec actions (`account_management_actions`, `account_management_action`, `account_action_takes_device`), `account_action_address` (every link, the post-sign-in redirect and the `m.oauth` URL), and the form field and action names. Every signed-in form carries `form_token`; a page whose token cannot be shown holds no form | +| `UserCode.cpp` | The device authorization grant's user code (ADR-0805): `user_code_from_bytes` (rejection sampling over `BCDFGHJKLMNPQRSTVWXZ`), `normalise_user_code` (the rule 2 exception below) and `display_user_code` (`XXXX-XXXX`) | | `FormPostOrigin.cpp` | `form_post_origin`, `form_post_origin_is_accepted`: a page's form post must name this server's origin exactly, and `Sec-Fetch-Site`, when sent, `same-origin` (ADR-0784) | | `HandOffRedirect.cpp` | `hand_off_redirect_target` (`https`, loopback `http` or a private-use scheme, then the allowlist) and `hand_off_return_address` (every `loginToken` removed, the new one added) for the legacy SSO redirect's hand-off (ADR-0802) | | `HandOffAllowlist.cpp` | `hand_off_allowlist_entry_error`, `hand_off_allowlist_error`: an https origin or a bare private-use scheme, at most 32, each once (ADR-0774) | @@ -38,7 +39,10 @@ Pure functions and value types for the built-in OAuth 2.0 API a password typed into a page). A function that needs the runtime, the database or the clock belongs in `src/homeserver/`. 2. **Refuse, never repair.** Every reader has a hard cap with its reason beside it, refuses instead of truncating, - stripping or normalising, and its error text is fixed: it never quotes the input. + stripping or normalising, and its error text is fixed: it never quotes the input. The one exception is + `normalise_user_code`, because RFC 8628 section 6.1 asks the server to accept a user code however it is typed: it + reads lower case as upper and skips `-`, space, `.` and `_`, and still refuses every other byte and anything over + its cap (ADR-0805). Do not add another. 3. **Every address a client supplies is read with `ParsedUri::read`.** Never `http::parse_outbound_url`, which canonicalises through libcurl and knows no private-use scheme, and never a private parser. A redirect URI is checked with `validate_redirect_uri` at registration and found with `match_redirect_uri` on every request; the @@ -77,13 +81,16 @@ Pure functions and value types for the built-in OAuth 2.0 API `[oauth][server_metadata]`), `test_oauth_hand_off_allowlist.cpp` (`[oauth][allowlist]`), `test_oauth_form_post_origin.cpp` (`[oauth][form-origin]`), `test_oauth_page_response.cpp` (`[oauth][page-response]`), `test_oauth_authorization_redirect.cpp` (`[oauth][redirect-address]`), -`test_oauth_authorization_pages.cpp` (`[oauth][authorize-page]`), `test_oauth_hand_off_redirect.cpp` +`test_oauth_authorization_pages.cpp` (`[oauth][authorize-page]`, the device pages `[device]`), +`test_oauth_user_code.cpp` (`[oauth][user-code]`), `test_oauth_hand_off_redirect.cpp` (`[oauth][hand-off-redirect]`), `test_oauth_account_pages.cpp` (`[oauth][account-page]`). The account pages: `tests/conformance/test_oauth_account_management_conformance.cpp` and `tests/integration/test_oauth_account_pages_flow.cpp` (`[oauth-account]`, `[oauth-uia]`). The hand-off: `tests/conformance/test_oauth_aware_clients_conformance.cpp` and `tests/integration/test_oauth_login_hand_off_flow.cpp` (`[hand-off]`). The authorisation endpoint: `tests/conformance/test_oauth_authorization_conformance.cpp` and `tests/integration/test_oauth_authorization_flow.cpp` -(`[oauth-authorize]`). The served document: +(`[oauth-authorize]`). The device grant: `tests/unit/test_oauth_device_authorisation_store.cpp`, +`tests/conformance/test_oauth_device_grant_conformance.cpp` and `tests/integration/test_oauth_device_grant_flow.cpp` +(`[oauth-device]`). The served document: `tests/conformance/test_oauth_metadata_conformance.cpp` and `tests/integration/test_oauth_metadata_flow.cpp` (`[oauth]`). Fuzz targets: `fuzz_oauth_redirect_uri.cpp`, `fuzz_oauth_scope.cpp`, `fuzz_oauth_client_metadata.cpp`. diff --git a/src/oauth/AuthorizationPages.cpp b/src/oauth/AuthorizationPages.cpp index 690481543..865e4bf9c 100644 --- a/src/oauth/AuthorizationPages.cpp +++ b/src/oauth/AuthorizationPages.cpp @@ -10,6 +10,7 @@ #include "merovingian/oauth/PageForm.hpp" #include "merovingian/oauth/SubmitButton.hpp" #include "merovingian/oauth/TextInput.hpp" +#include "merovingian/oauth/UserCode.hpp" #include #include @@ -246,6 +247,81 @@ auto hand_off_cancelled_page() -> Page return page; } +auto device_link_page(std::optional user_code, std::optional const& error) -> Page +{ + auto page = Page{HtmlText{"Sign in a device"}}; + page.paragraph(HtmlText{"Enter the code your other device shows, such as a TV or a computer without a browser. " + "You then sign in here and choose whether to let that device into your account."}); + if (error.has_value()) + { + page.error(*error); + } + auto input = TextInput{user_code_field, HtmlText{"Code"}, HtmlName{"off"}}; + if (user_code.has_value()) + { + input.value = HtmlText::escape(display_user_code(*user_code)); + } + auto form = PageForm{link_path}; + std::ignore = form.input(input); + std::ignore = form.button(SubmitButton{HtmlName{"continue"}, HtmlName{"continue"}, HtmlText{"Continue"}}); + std::ignore = page.form(form); + return page; +} + +auto device_consent_page(DeviceConsentPageInput const& input) -> Page +{ + auto page = Page{HtmlText{"Sign in a different device"}}; + // The warning comes first (ADR-0806): the code may have been sent by someone else to get into this account. + page.error(HtmlText{"You are about to sign in a different device, not this browser. Continue only if you started " + "this sign-in yourself on that device and the code below is the one it shows. If someone " + "sent you this code or link, deny."}); + auto const client_name = input.client_name.has_value() ? shown(*input.client_name, "An application with no name") + : HtmlText{"An application with no name"}; + auto const details = std::array{ + PageDetail{HtmlText{"Code on the device"}, + shown(display_user_code(input.user_code), "a code that cannot be shown")}, + PageDetail{HtmlText{"Application"}, client_name}, + PageDetail{HtmlText{"Application website"}, shown(input.client_host, "an address that cannot be shown")}, + PageDetail{HtmlText{"Account"}, shown(input.user_id, "an account that cannot be shown")}, + PageDetail{HtmlText{"Device ID"}, shown(input.device_id, "a device that cannot be shown")}, + }; + page.details(details); + page.paragraph(HtmlText{"If you allow it, that device gets full access to your account: it can read and send your " + "messages, join and leave rooms and change your settings, as you can."}); + if (input.replaces_existing_device) + { + page.notice(HtmlText{"Your account already has a session with this device ID. Allowing access signs that " + "session out and replaces it."}); + } + auto const pending = pending_value(input.pending_id); + if (!pending.has_value()) + { + add_cannot_continue(page); + return page; + } + auto form = PageForm{authorize_path}; + form.hidden(pending_field, *pending); + std::ignore = form.button(SubmitButton{action_field, action_approve, HtmlText{"Allow"}}); + std::ignore = form.button(SubmitButton{action_field, action_deny, HtmlText{"Deny"}}); + std::ignore = page.form(form); + return page; +} + +auto device_approved_page() -> Page +{ + auto page = Page{HtmlText{"Device signed in"}}; + page.paragraph( + HtmlText{"Return to your other device: it finishes signing in on its own. You can close this page."}); + return page; +} + +auto device_denied_page() -> Page +{ + auto page = Page{HtmlText{"Device not signed in"}}; + page.paragraph(HtmlText{"The other device was not let into your account. You can close this page."}); + return page; +} + auto error_page(HtmlText title, HtmlText const& message) -> Page { auto page = Page{std::move(title)}; diff --git a/src/oauth/UserCode.cpp b/src/oauth/UserCode.cpp new file mode 100644 index 000000000..25dff0938 --- /dev/null +++ b/src/oauth/UserCode.cpp @@ -0,0 +1,94 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/oauth/UserCode.hpp" + +namespace merovingian::oauth +{ + +namespace +{ + + // Twelve whole copies of the twenty-letter alphabet fit in a byte; the sixteen values above them are skipped. + constexpr auto accepted_byte_limit = std::uint8_t{240U}; + constexpr auto display_group = std::size_t{4U}; + + [[nodiscard]] auto in_alphabet(char letter) noexcept -> bool + { + return user_code_alphabet.find(letter) != std::string_view::npos; + } + + [[nodiscard]] auto is_separator(char letter) noexcept -> bool + { + return letter == '-' || letter == ' ' || letter == '.' || letter == '_'; + } + +} // namespace + +auto user_code_from_bytes(std::span random_bytes) -> std::optional +{ + auto code = std::string{}; + code.reserve(user_code_length); + for (auto const byte : random_bytes) + { + if (code.size() == user_code_length) + { + break; + } + if (byte >= accepted_byte_limit) + { + continue; + } + code.push_back(user_code_alphabet[byte % user_code_alphabet.size()]); + } + if (code.size() != user_code_length) + { + return std::nullopt; + } + return code; +} + +auto normalise_user_code(std::string_view typed) -> std::optional +{ + if (typed.size() > max_typed_user_code_bytes) + { + return std::nullopt; + } + auto code = std::string{}; + code.reserve(user_code_length); + for (auto letter : typed) + { + if (is_separator(letter)) + { + continue; + } + if (letter >= 'a' && letter <= 'z') + { + letter = static_cast(letter - 'a' + 'A'); + } + if (!in_alphabet(letter) || code.size() == user_code_length) + { + return std::nullopt; + } + code.push_back(letter); + } + if (code.size() != user_code_length) + { + return std::nullopt; + } + return code; +} + +auto display_user_code(std::string_view code) -> std::string +{ + if (code.size() != user_code_length) + { + return std::string{code}; + } + auto shown = std::string{code.substr(0U, display_group)}; + shown.push_back('-'); + shown.append(code.substr(display_group)); + return shown; +} + +} // namespace merovingian::oauth diff --git a/src/oauth/meson.build b/src/oauth/meson.build index d539838c7..77042015b 100644 --- a/src/oauth/meson.build +++ b/src/oauth/meson.build @@ -20,6 +20,7 @@ oauth_sources = files( 'RedirectUriRules.cpp', 'ScopeParser.cpp', 'ServerMetadata.cpp', + 'UserCode.cpp', ) # Pure functions only: no runtime state, no I/O, no logging (src/oauth/AGENTS.md). diff --git a/tests/conformance/AGENTS.md b/tests/conformance/AGENTS.md index 0e4078f62..dccaf0ea3 100644 --- a/tests/conformance/AGENTS.md +++ b/tests/conformance/AGENTS.md @@ -64,6 +64,7 @@ Every test in this directory directly encodes a **MUST** or **SHOULD** from the | `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) | | `test_oauth_authorization_conformance.cpp` | [CS API § Authorisation code grant](../../docs/matrix-v1.19-spec/client-server-api.md#authorisation-code-grant) · [§ Scope](../../docs/matrix-v1.19-spec/client-server-api.md#scope) · [§ User registration](../../docs/matrix-v1.19-spec/client-server-api.md#user-registration) (`/_merovingian/oauth2/authorize`: an unregistered redirect URI is never redirected to; `state` on success and error; the response mode places the answer; S256 required; the API and exactly one device scope; `prompt=create` shows registration only when accepted) | | `test_oauth_account_management_conformance.cpp` | [CS API § Account management](../../docs/matrix-v1.19-spec/client-server-api.md#account-management-url-discovery) · [§ OAuth authentication](../../docs/matrix-v1.19-spec/client-server-api.md#oauth-authentication) (`account_management_uri` and the six actions; `action` and `device_id` on `/_merovingian/account`, the device ignored by the actions that take none; a replacing cross-signing upload from an OAuth session is a 401 with the `m.oauth` flow and the `org.matrix.cross_signing_reset` URL, completed by the `session` alone after the approval) | +| `test_oauth_device_grant_conformance.cpp` | [CS API § Device authorisation flow](../../docs/matrix-v1.19-spec/client-server-api.md#device-authorisation-flow) · [§ Device authorisation grant](../../docs/matrix-v1.19-spec/client-server-api.md#device-authorisation-grant) (`/_merovingian/oauth2/device`: the six response members, `verification_uri_complete` naming the code; token polling's `authorization_pending`, `slow_down`, `access_denied` and `expired_token`, each 400; a granted device gets a refresh token the refresh grant serves) | | `test_oauth_token_conformance.cpp` | [CS API § Refresh token grant](../../docs/matrix-v1.19-spec/client-server-api.md#refresh-token-grant) · [§ Token revocation](../../docs/matrix-v1.19-spec/client-server-api.md#token-revocation) (`/_merovingian/oauth2/token` and `/revoke`: an access token always expires; a lost refresh answer can be retried and the old token is refused once the new one is used; revocation ends both tokens whatever the `client_id` and answers 200 for an unknown token) | | `test_oauth_legacy_api_conformance.cpp` | [CS API § Authentication API discovery](../../docs/matrix-v1.19-spec/client-server-api.md#authentication-api-discovery) · [`GET /login`](../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv3login) · [`POST /login`](../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3login) · [`POST /register`](../../docs/matrix-v1.19-spec/client-server-api.md#post_matrixclientv3register) (without the legacy API: `GET /login` 404 `M_UNRECOGNIZED`, `m.login.application_service` and an appservice registration without `inhibit_login` 400 `M_APPSERVICE_LOGIN_UNSUPPORTED`, an appservice registration with it served, a user's registration 403) | | `test_oauth_aware_clients_conformance.cpp` | [CS API § OAuth 2.0 aware clients](../../docs/matrix-v1.19-spec/client-server-api.md#oauth-20-aware-clients) · [`GET /login/sso/redirect`](../../docs/matrix-v1.19-spec/client-server-api.md#get_matrixclientv3loginssoredirect) · [§ Client login via SSO](../../docs/matrix-v1.19-spec/client-server-api.md#client-login-via-sso) (with the OAuth 2.0 API and the legacy API on: `m.login.sso` with `oauth_aware_preferred: true` beside `m.login.password`; `action=register` and `action=login`; a confirmation naming the site before one fresh `loginToken` replaces any in `redirectUrl`) | diff --git a/tests/conformance/test_oauth_device_grant_conformance.cpp b/tests/conformance/test_oauth_device_grant_conformance.cpp new file mode 100644 index 000000000..5282d9c21 --- /dev/null +++ b/tests/conformance/test_oauth_device_grant_conformance.cpp @@ -0,0 +1,270 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The device authorisation grant against the Matrix Client-Server API v1.19 (RFC 8628): the device authorisation +// response, the token polling errors, and the refresh token a granted device receives. + +#include "../support/OAuthAuthorizationSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "../support/OAuthTokenSupport.hpp" +#include "../support/RegistrationToken.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" + +#include + +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace hs = merovingian::homeserver; + +constexpr auto alice_password = std::string_view{"AlicePass99!x"}; +constexpr auto device_path = std::string_view{"/_merovingian/oauth2/device"}; +constexpr auto link_path = std::string_view{"/_merovingian/oauth2/link"}; +constexpr auto device_grant = std::string_view{"urn:ietf:params:oauth:grant-type:device_code"}; + +struct Fixture final +{ + hs::ClientServerStartResult started; + std::string client_id; +}; + +// OAuth and the device grant on, alice registered, a client registered for the device and refresh grants. +[[nodiscard]] auto make_fixture() -> Fixture +{ + auto config = oauth_registration_config(); + config.server().server_name = "example.org"; + config.server().oauth.device_grant_enabled = true; + enable_token_registration(config.security()); + auto started = hs::start_client_server(config); + REQUIRE(started.started); + started.runtime.rate_limit_engine.reset(); + REQUIRE( + hs::register_local_user(started.runtime.homeserver, "alice", alice_password, std::string{registration_token}) + .ok); + auto client_id = register_oauth_web_client( + started.runtime, R"(,"grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"])"); + REQUIRE_FALSE(client_id.empty()); + return {std::move(started), std::move(client_id)}; +} + +[[nodiscard]] auto member(hs::LocalHttpResponse const& response, std::string_view name) -> std::string +{ + auto const body = parse_object(response.body); + auto const* value = string_member(body, name); + return value == nullptr ? std::string{} : *value; +} + +[[nodiscard]] auto request_codes(hs::ClientServerRuntime& rt, std::string_view client_id) -> hs::LocalHttpResponse +{ + return post_oauth_form(rt, device_path, + { + {"client_id", std::string{client_id} }, + {"scope", oauth_scope_for_device("CONFDEVICE")}, + }); +} + +[[nodiscard]] auto poll(hs::ClientServerRuntime& rt, std::string_view client_id, std::string_view device_code) + -> hs::LocalHttpResponse +{ + return post_oauth_form(rt, oauth_token_path, + { + {"grant_type", std::string{device_grant}}, + {"device_code", std::string{device_code} }, + {"client_id", std::string{client_id} }, + }); +} + +// Alice types `user_code` on the link page, signs in and answers `action`. +[[nodiscard]] auto user_answers(hs::ClientServerRuntime& rt, std::string_view user_code, std::string_view action) + -> hs::LocalHttpResponse +{ + auto browser = BrowserContext{}; + auto const page = authorize_request(rt, "GET", std::string{link_path}, {}, browser); + browser.cookie = cookie_of(page); + auto const login = authorize_request(rt, "POST", + std::string{ + link_path + }, + form_encode({{"user_code", std::string{user_code}}}), browser); + auto const pending = pending_of(login); + std::ignore = post_authorize(rt, + { + {"pending", pending }, + {"action", "login" }, + {"username", "alice" }, + {"password", std::string{alice_password}}, + }, + browser); + return post_authorize(rt, + { + {"pending", pending }, + {"action", std::string{action}}, + }, + browser); +} + +} // namespace + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Device authorisation flow +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#device-authorisation-flow +// +// "The server responds with a JSON object as defined in RFC 8628 section 3.2, containing: device_code, user_code, +// verification_uri, verification_uri_complete, expires_in, interval". "It is RECOMMENDED that the server provides a +// verification_uri_complete". +SCENARIO("The device authorisation response holds every RFC 8628 member", + "[conformance][client-server][oauth][oauth-device]") +{ + GIVEN("a client registered for the device grant") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + + WHEN("it sends the device authorisation request") + { + auto const response = request_codes(rt, fixture.client_id); + + THEN("the answer is JSON with the six members, and the complete URI names the user code") + { + REQUIRE(response.status == 200U); + auto const body = parse_object(response.body); + REQUIRE_FALSE(member(response, "device_code").empty()); + REQUIRE_FALSE(member(response, "user_code").empty()); + REQUIRE(member(response, "verification_uri") == "https://matrix.example.org/_merovingian/oauth2/link"); + // Spec RECOMMENDED: a URI that does not require the user to type the code. + REQUIRE(member(response, "verification_uri_complete") == + member(response, "verification_uri") + "?user_code=" + member(response, "user_code")); + auto const* expires_in = int_member(body, "expires_in"); + auto const* interval = int_member(body, "interval"); + REQUIRE(expires_in != nullptr); + REQUIRE(*expires_in > 0); + REQUIRE(interval != nullptr); + REQUIRE(*interval >= 5); + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Device authorisation flow (Token polling) +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#device-authorisation-flow +// +// "While authorisation is pending, the server returns an authorization_pending error (or slow_down if the client is +// polling too frequently). If authorisation is denied, the server returns an access_denied error. If the device code +// expires, the server returns an expired_token error." RFC 8628 section 3.5: each is an RFC 6749 section 5.2 error +// response, HTTP 400. +SCENARIO("Token polling answers the RFC 8628 section 3.5 errors", "[conformance][client-server][oauth][oauth-device]") +{ + GIVEN("a pending device authorisation") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const codes = request_codes(rt, fixture.client_id); + auto const device_code = member(codes, "device_code"); + REQUIRE_FALSE(device_code.empty()); + + WHEN("the client polls twice at once") + { + auto const first = poll(rt, fixture.client_id, device_code); + auto const second = poll(rt, fixture.client_id, device_code); + + THEN("it hears authorization_pending, then slow_down, both 400") + { + REQUIRE(first.status == 400U); + REQUIRE(member(first, "error") == "authorization_pending"); + REQUIRE(second.status == 400U); + REQUIRE(member(second, "error") == "slow_down"); + } + } + + WHEN("the user denies and the client polls") + { + auto const denied = user_answers(rt, member(codes, "user_code"), "deny"); + rt.homeserver.test_device_grant_clock_advance_ms += 5'000U; + auto const polled = poll(rt, fixture.client_id, device_code); + + THEN("it hears access_denied") + { + REQUIRE(denied.status == 200U); + REQUIRE(polled.status == 400U); + REQUIRE(member(polled, "error") == "access_denied"); + } + } + + WHEN("the device code expires and the client polls") + { + rt.homeserver.test_device_grant_clock_advance_ms += 600'000U; + auto const polled = poll(rt, fixture.client_id, device_code); + + THEN("it hears expired_token") + { + REQUIRE(polled.status == 400U); + REQUIRE(member(polled, "error") == "expired_token"); + } + } + } +} + +// Spec: Matrix Client-Server API v1.19 +// Endpoint / Section: Device authorisation grant +// URL: ../../docs/matrix-v1.19-spec/client-server-api.md#device-authorisation-grant +// +// "when authorisation is granted to a client, the homeserver MUST issue a refresh token to the client in addition to +// the access token." The client "can call the /whoami endpoint to get the user ID that owns the access token". +SCENARIO("A granted device receives an access token and a refresh token", + "[conformance][client-server][oauth][oauth-device]") +{ + GIVEN("a device authorisation that alice allows") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const codes = request_codes(rt, fixture.client_id); + auto const allowed = user_answers(rt, member(codes, "user_code"), "approve"); + REQUIRE(allowed.status == 200U); + + WHEN("the client polls") + { + auto const answer = read_token_answer(poll(rt, fixture.client_id, member(codes, "device_code"))); + + THEN("the answer holds both tokens, Bearer, a finite lifetime and the scope, and whoami names alice") + { + REQUIRE(answer.ok); + // Spec MUST: a refresh token in addition to the access token. + REQUIRE_FALSE(answer.refresh_token.empty()); + REQUIRE(answer.token_type == "Bearer"); + REQUIRE(answer.expires_in > 0); + REQUIRE(answer.scope == oauth_scope_for_device("CONFDEVICE")); + auto const whoami = + hs::handle_client_server_request( + rt, {"GET", "/_matrix/client/v3/account/whoami", answer.access_token, {}}, false) + .response; + REQUIRE(whoami.status == 200U); + REQUIRE(member(whoami, "user_id") == "@alice:example.org"); + } + + AND_WHEN("the refresh token is used") + { + auto const refreshed = read_token_answer(post_oauth_form( + rt, oauth_token_path, refresh_grant_fields(fixture.client_id, answer.refresh_token))); + + THEN("the refresh token grant serves it") + { + REQUIRE(refreshed.ok); + } + } + } + } +} diff --git a/tests/conformance/test_route_query_conformance.cpp b/tests/conformance/test_route_query_conformance.cpp index 3729e5ab7..b247f599a 100644 --- a/tests/conformance/test_route_query_conformance.cpp +++ b/tests/conformance/test_route_query_conformance.cpp @@ -41,10 +41,12 @@ using merovingian::homeserver::ClientServerRuntime; auto security = merovingian::config::SecurityConfig{}; security.secrets.master_key_file = merovingian::tests::shared_master_key_file(); merovingian::tests::enable_token_registration(security); - // The OAuth 2.0 API is on so that its fixed routes are served and can be checked like the others. + // The OAuth 2.0 API and its device grant are on so that their fixed routes are served and can be checked like the + // others. auto server = merovingian::config::ServerConfig{}; server.public_baseurl = "https://matrix.example.org"; server.oauth.enabled = true; + server.oauth.device_grant_enabled = true; return { std::move(server), merovingian::config::ListenersConfig{}, @@ -109,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", ""}, @@ -120,6 +122,9 @@ SCENARIO("every client route that matched its whole target answers a request wit {"POST", "/_merovingian/oauth2/authorize", ""}, {"POST", "/_merovingian/oauth2/token", ""}, {"POST", "/_merovingian/oauth2/revoke", ""}, + {"POST", "/_merovingian/oauth2/device", ""}, + {"GET", "/_merovingian/oauth2/link", ""}, + {"POST", "/_merovingian/oauth2/link", ""}, {"GET", "/_merovingian/account", ""}, {"POST", "/_merovingian/account", ""}, {"POST", "/_matrix/client/v3/register/email/requestToken", "{}"}, diff --git a/tests/integration/test_oauth_device_grant_flow.cpp b/tests/integration/test_oauth_device_grant_flow.cpp new file mode 100644 index 000000000..30d60a18f --- /dev/null +++ b/tests/integration/test_oauth_device_grant_flow.cpp @@ -0,0 +1,706 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +// +// The device authorization grant through the client-server dispatcher (RFC 8628; plan P11; ADR-0804 to ADR-0806): a +// device asks for codes at POST /_merovingian/oauth2/device, a user types the user code at /_merovingian/oauth2/link, +// signs in, and allows or denies; the device polls the token endpoint. The clock is moved with +// `HomeserverRuntime::test_device_grant_clock_advance_ms`, so nothing sleeps. No browser runs here: what a browser does +// with the cookie or the page is not tested. + +#include "../support/JsonTestSupport.hpp" +#include "../support/OAuthAuthorizationSupport.hpp" +#include "../support/OAuthRegistrationSupport.hpp" +#include "../support/OAuthTokenSupport.hpp" +#include "../support/RegistrationToken.hpp" +#include "merovingian/config/Config.hpp" +#include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/ClientServerRuntime.hpp" +#include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/DeviceAuthorisationStore.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" +#include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/homeserver/OAuthClock.hpp" +#include "merovingian/homeserver/RetentionSweep.hpp" + +#include + +#include +#include +#include +#include +#include +#include + +namespace +{ + +using namespace merovingian::tests; +namespace hs = merovingian::homeserver; + +constexpr auto alice_password = std::string_view{"AlicePass99!x"}; +constexpr auto alice_id = std::string_view{"@alice:example.org"}; +constexpr auto device_path = std::string_view{"/_merovingian/oauth2/device"}; +constexpr auto link_path = std::string_view{"/_merovingian/oauth2/link"}; +constexpr auto link_url = std::string_view{"https://matrix.example.org/_merovingian/oauth2/link"}; +constexpr auto device_grant = std::string_view{"urn:ietf:params:oauth:grant-type:device_code"}; +constexpr auto tv_device = std::string_view{"TVDEVICE01"}; +constexpr auto device_client_members = std::string_view{ + R"(,"client_name":"Living Room TV","grant_types":["urn:ietf:params:oauth:grant-type:device_code","refresh_token"])"}; + +[[nodiscard]] auto device_config(bool device_grant_enabled = true) -> merovingian::config::Config +{ + auto config = oauth_registration_config(true); + config.server().server_name = "example.org"; + config.server().oauth.device_grant_enabled = device_grant_enabled; + enable_token_registration(config.security()); + return config; +} + +// A runtime with alice, a device client and a web client registered without the device grant. +struct Fixture final +{ + hs::ClientServerStartResult started; + std::string client_id; + std::string web_client_id; +}; + +[[nodiscard]] auto make_fixture(bool device_grant_enabled = true) -> Fixture +{ + auto started = hs::start_client_server(device_config(device_grant_enabled)); + REQUIRE(started.started); + // Every request comes from one or two addresses; the built-in limits are not what this file tests. + started.runtime.rate_limit_engine.reset(); + REQUIRE( + hs::register_local_user(started.runtime.homeserver, "alice", alice_password, std::string{registration_token}) + .ok); + auto client_id = register_oauth_web_client(started.runtime, device_client_members); + REQUIRE_FALSE(client_id.empty()); + auto web_client_id = register_oauth_web_client(started.runtime); + REQUIRE_FALSE(web_client_id.empty()); + return {std::move(started), std::move(client_id), std::move(web_client_id)}; +} + +[[nodiscard]] auto contains(std::string_view text, std::string_view part) -> bool +{ + return text.find(part) != std::string_view::npos; +} + +[[nodiscard]] auto member(hs::LocalHttpResponse const& response, std::string_view name) -> std::string +{ + auto const body = parse_object(response.body); + auto const* value = string_member(body, name); + return value == nullptr ? std::string{} : *value; +} + +[[nodiscard]] auto audit_count(hs::HomeserverRuntime const& runtime, std::string_view event_type) -> std::size_t +{ + auto count = std::size_t{0U}; + for (auto const& event : runtime.database.audit_events) + { + if (event.event_type == event_type) + { + ++count; + } + } + return count; +} + +auto advance(hs::ClientServerRuntime& rt, std::uint64_t milliseconds) -> void +{ + rt.homeserver.test_device_grant_clock_advance_ms += milliseconds; +} + +// What POST /device answered. +struct DeviceStart final +{ + hs::LocalHttpResponse response; + std::string device_code; + std::string user_code; +}; + +[[nodiscard]] auto start_device(hs::ClientServerRuntime& rt, std::string_view client_id, + std::string_view device_id = tv_device) -> DeviceStart +{ + auto response = post_oauth_form(rt, device_path, + { + {"client_id", std::string{client_id} }, + {"scope", oauth_scope_for_device(device_id)}, + }); + auto device_code = member(response, "device_code"); + auto user_code = member(response, "user_code"); + return {std::move(response), std::move(device_code), std::move(user_code)}; +} + +[[nodiscard]] auto poll(hs::ClientServerRuntime& rt, std::string_view client_id, std::string_view device_code) + -> hs::LocalHttpResponse +{ + return post_oauth_form(rt, oauth_token_path, + { + {"grant_type", std::string{device_grant}}, + {"device_code", std::string{device_code} }, + {"client_id", std::string{client_id} }, + }); +} + +[[nodiscard]] auto oauth_error(hs::LocalHttpResponse const& response) -> std::string +{ + return member(response, "error"); +} + +// A browser that opened the link page: it holds the cookie the page set. +[[nodiscard]] auto open_link(hs::ClientServerRuntime& rt, std::string_view query = {}, + std::string_view remote_addr = "198.51.100.20") + -> std::pair +{ + auto browser = BrowserContext{}; + browser.remote_addr = std::string{remote_addr}; + auto target = std::string{link_path}; + if (!query.empty()) + { + target.append("?").append(query); + } + auto response = authorize_request(rt, "GET", target, {}, browser); + browser.cookie = cookie_of(response); + return {std::move(response), std::move(browser)}; +} + +[[nodiscard]] auto post_link(hs::ClientServerRuntime& rt, BrowserContext const& browser, std::string_view user_code) + -> hs::LocalHttpResponse +{ + return authorize_request(rt, "POST", + std::string{ + link_path + }, + form_encode({{"user_code", std::string{user_code}}}), browser); +} + +[[nodiscard]] auto sign_in(hs::ClientServerRuntime& rt, BrowserContext const& browser, std::string_view pending) + -> hs::LocalHttpResponse +{ + return post_authorize(rt, + { + {"pending", std::string{pending} }, + {"action", "login" }, + {"username", "alice" }, + {"password", std::string{alice_password}}, + }, + browser); +} + +[[nodiscard]] auto answer(hs::ClientServerRuntime& rt, BrowserContext const& browser, std::string_view pending, + std::string_view action) -> hs::LocalHttpResponse +{ + return post_authorize(rt, + { + {"pending", std::string{pending}}, + {"action", std::string{action} }, + }, + browser); +} + +[[nodiscard]] auto whoami(hs::ClientServerRuntime& rt, std::string token) -> hs::LocalHttpResponse +{ + return hs::handle_client_server_request(rt, {"GET", "/_matrix/client/v3/account/whoami", std::move(token), {}}, + /*can_wait=*/false) + .response; +} + +// Types the code in a fresh browser and signs alice in: the consent page and what it needs to be answered. +struct ConsentStep final +{ + hs::LocalHttpResponse consent; + BrowserContext browser; + std::string pending; +}; + +[[nodiscard]] auto reach_consent(hs::ClientServerRuntime& rt, std::string_view user_code) -> ConsentStep +{ + auto [page, browser] = open_link(rt); + REQUIRE(page.status == 200U); + auto const login = post_link(rt, browser, user_code); + REQUIRE(login.status == 200U); + auto pending = pending_of(login); + REQUIRE_FALSE(pending.empty()); + auto consent = sign_in(rt, browser, pending); + return {std::move(consent), std::move(browser), std::move(pending)}; +} + +} // namespace + +SCENARIO("A device signs in with a user code that alice types and allows", "[integration][oauth][oauth-device]") +{ + GIVEN("a server with the device grant on and a device client") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + + WHEN("the device asks for codes") + { + auto const device = start_device(rt, fixture.client_id); + + THEN("it is told both codes, the link page, ten minutes and five seconds, with CORS and no-store") + { + REQUIRE(device.response.status == 200U); + auto const body = parse_object(device.response.body); + REQUIRE(device.device_code.size() == 64U); + REQUIRE(device.user_code.size() == 9U); + CHECK(device.user_code[4] == '-'); + CHECK(member(device.response, "verification_uri") == link_url); + CHECK(member(device.response, "verification_uri_complete") == + std::string{link_url} + "?user_code=" + device.user_code); + auto const* expires_in = int_member(body, "expires_in"); + auto const* interval = int_member(body, "interval"); + REQUIRE(expires_in != nullptr); + REQUIRE(interval != nullptr); + CHECK(*expires_in == 600); + CHECK(*interval == 5); + CHECK(response_header(device.response, "Cache-Control") == "no-store"); + CHECK_FALSE(response_header(device.response, "Access-Control-Allow-Origin").empty()); + } + + AND_WHEN("it polls before alice answers") + { + auto const pending = poll(rt, fixture.client_id, device.device_code); + + THEN("it hears authorization_pending") + { + CHECK(pending.status == 400U); + CHECK(oauth_error(pending) == "authorization_pending"); + } + } + + AND_WHEN("alice opens the complete link, sends the prefilled code and signs in") + { + auto const query = "user_code=" + device.user_code; + auto [page, browser] = open_link(rt, query); + auto const login = post_link(rt, browser, device.user_code); + auto const pending = pending_of(login); + auto const consent = sign_in(rt, browser, pending); + + THEN("the link page is prefilled and sets the cookie, the login page offers no registration, and the " + "consent page warns before it names the code, the client, alice and the device") + { + REQUIRE(page.status == 200U); + CHECK(contains(page.body, "value=\"" + device.user_code + "\"")); + CHECK(browser.cookie.size() == 64U); + CHECK(response_header(page, "Access-Control-Allow-Origin").empty()); + REQUIRE(login.status == 200U); + CHECK(contains(login.body, R"(autocomplete="current-password")")); + CHECK_FALSE(contains(login.body, R"(value="show_register")")); + REQUIRE(consent.status == 200U); + auto const warning = consent.body.find("not this browser"); + auto const code = consent.body.find(device.user_code); + REQUIRE(warning != std::string::npos); + REQUIRE(code != std::string::npos); + CHECK(warning < code); + CHECK(contains(consent.body, "Living Room TV")); + CHECK(contains(consent.body, "app.example.com")); + CHECK(contains(consent.body, alice_id)); + CHECK(contains(consent.body, tv_device)); + CHECK(response_header(consent, "Location").empty()); + } + + AND_WHEN("she allows it and the device polls once its interval has passed, then again") + { + auto const approved = answer(rt, browser, pending, "approve"); + advance(rt, 5'000U); + auto const granted = poll(rt, fixture.client_id, device.device_code); + auto const tokens = read_token_answer(granted); + advance(rt, 5'000U); + auto const again = poll(rt, fixture.client_id, device.device_code); + + THEN("the page sends her back to the device, which gets tokens for its device once") + { + REQUIRE(approved.status == 200U); + CHECK(contains(approved.body, "Return to your other device")); + CHECK(response_header(approved, "Location").empty()); + REQUIRE(tokens.ok); + CHECK(tokens.token_type == "Bearer"); + CHECK(tokens.scope == oauth_scope_for_device(tv_device)); + CHECK_FALSE(tokens.refresh_token.empty()); + auto const me = whoami(rt, tokens.access_token); + REQUIRE(me.status == 200U); + CHECK(member(me, "user_id") == alice_id); + CHECK(member(me, "device_id") == tv_device); + CHECK(again.status == 400U); + CHECK(oauth_error(again) == "expired_token"); + CHECK(audit_count(rt.homeserver, "oauth.device.approved") == 1U); + } + } + + AND_WHEN("she denies it and the device polls twice") + { + auto const denied = answer(rt, browser, pending, "deny"); + advance(rt, 5'000U); + auto const first = poll(rt, fixture.client_id, device.device_code); + advance(rt, 5'000U); + auto const second = poll(rt, fixture.client_id, device.device_code); + auto const retyped = post_link(rt, browser, device.user_code); + + THEN("the device hears access_denied each time, and the code is no longer accepted") + { + REQUIRE(denied.status == 200U); + CHECK(contains(denied.body, "was not let into your account")); + CHECK(first.status == 400U); + CHECK(oauth_error(first) == "access_denied"); + CHECK(oauth_error(second) == "access_denied"); + CHECK(retyped.status == 400U); + CHECK(audit_count(rt.homeserver, "oauth.device.denied") == 1U); + } + } + + AND_WHEN("she asks for the registration form instead") + { + auto const registration = answer(rt, browser, pending, "show_register"); + + THEN("it is refused: a device sign-in never creates an account") + { + CHECK(registration.status == 403U); + } + } + } + } + } +} + +SCENARIO("A device that polls too fast is slowed down, and one that waits too long has expired", + "[integration][oauth][oauth-device]") +{ + GIVEN("a pending device authorisation") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const device = start_device(rt, fixture.client_id); + REQUIRE(device.response.status == 200U); + + WHEN("the device polls twice at once, then five seconds later, then ten seconds after that") + { + auto const first = poll(rt, fixture.client_id, device.device_code); + auto const second = poll(rt, fixture.client_id, device.device_code); + advance(rt, 5'000U); + auto const third = poll(rt, fixture.client_id, device.device_code); + advance(rt, 15'000U); + auto const fourth = poll(rt, fixture.client_id, device.device_code); + + THEN("the second and third are slow_down, and the fourth waited out the grown interval") + { + CHECK(oauth_error(first) == "authorization_pending"); + CHECK(second.status == 400U); + CHECK(oauth_error(second) == "slow_down"); + CHECK(oauth_error(third) == "slow_down"); + CHECK(oauth_error(fourth) == "authorization_pending"); + } + } + + WHEN("ten minutes pass and the device polls and alice types the code") + { + advance(rt, hs::DeviceAuthorisationStore::lifetime_ms); + auto const late = poll(rt, fixture.client_id, device.device_code); + auto [page, browser] = open_link(rt); + auto const typed = post_link(rt, browser, device.user_code); + + THEN("the device hears expired_token and the code is the wrong-code page") + { + CHECK(late.status == 400U); + CHECK(oauth_error(late) == "expired_token"); + CHECK(typed.status == 400U); + CHECK(contains(typed.body, "not right, or it has expired")); + } + } + } +} + +SCENARIO("A device code serves only its own client, and the grant serves only clients registered for it", + "[integration][oauth][oauth-device][security]") +{ + GIVEN("a pending device authorisation and a client without the device grant") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const device = start_device(rt, fixture.client_id); + REQUIRE(device.response.status == 200U); + + WHEN("the other client polls with the device code, asks for codes, and an unknown client asks") + { + auto const stolen = poll(rt, fixture.web_client_id, device.device_code); + auto const unregistered = start_device(rt, fixture.web_client_id); + auto const unknown = start_device(rt, "not-a-client"); + auto const made_up = poll(rt, fixture.client_id, "not-a-device-code"); + + THEN("each is refused, and the device code still works for its own client") + { + CHECK(stolen.status == 400U); + CHECK(oauth_error(stolen) == "unauthorized_client"); + CHECK(unregistered.response.status == 400U); + CHECK(oauth_error(unregistered.response) == "unauthorized_client"); + CHECK(unknown.response.status == 400U); + CHECK(oauth_error(unknown.response) == "invalid_client"); + CHECK(oauth_error(made_up) == "expired_token"); + CHECK(oauth_error(poll(rt, fixture.client_id, device.device_code)) == "authorization_pending"); + } + } + + WHEN("a second device client polls with the first one's device code") + { + auto const second_client = register_oauth_web_client( + rt, R"(,"client_name":"Other TV","grant_types":["urn:ietf:params:oauth:grant-type:device_code"])"); + REQUIRE_FALSE(second_client.empty()); + auto const stolen = poll(rt, second_client, device.device_code); + + THEN("it hears invalid_grant") + { + CHECK(stolen.status == 400U); + CHECK(oauth_error(stolen) == "invalid_grant"); + } + } + + WHEN("the client's registration retention is asked about") + { + auto const now_ms = hs::oauth_device_clock_ms(rt.homeserver); + auto const pending = hs::oauth_client_has_pending_authorisation(rt.homeserver, fixture.client_id, now_ms); + auto const after = hs::oauth_client_has_pending_authorisation( + rt.homeserver, fixture.client_id, now_ms + hs::DeviceAuthorisationStore::lifetime_ms); + + THEN("the live device authorisation keeps the client, and stops keeping it once it expired") + { + CHECK(pending); + CHECK_FALSE(after); + } + } + + WHEN("the same address asks for codes until the store refuses") + { + auto statuses = std::vector{}; + for (auto index = 0U; index < hs::DeviceAuthorisationStore::max_entries_per_address; ++index) + { + statuses.push_back(start_device(rt, fixture.client_id).response.status); + } + + THEN("the ninth from one address is 503 temporarily_unavailable") + { + // The GIVEN step's request was the first of the eight. + for (auto index = std::size_t{0U}; index + 1U < statuses.size(); ++index) + { + CHECK(statuses[index] == 200U); + } + CHECK(statuses.back() == 503U); + CHECK(oauth_error(start_device(rt, fixture.client_id).response) == "temporarily_unavailable"); + } + } + } +} + +SCENARIO("The link page throttles wrong codes per address and refuses foreign or cookieless posts", + "[integration][oauth][oauth-device][security]") +{ + GIVEN("a pending device authorisation and a browser on the link page") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const device = start_device(rt, fixture.client_id); + REQUIRE(device.response.status == 200U); + auto [page, browser] = open_link(rt); + REQUIRE(page.status == 200U); + + WHEN("five wrong codes are typed, then the right one") + { + auto wrong = std::vector{}; + for (auto const* typed : {"BCDF-GHJK", "nonsense", "ZZZZ-ZZZZ", "", "XXXX-XXXX"}) + { + wrong.push_back(post_link(rt, browser, typed).status); + } + auto const right = post_link(rt, browser, device.user_code); + auto [other_page, other_browser] = open_link(rt, {}, "203.0.113.50"); + auto const elsewhere = post_link(rt, other_browser, device.user_code); + + THEN("each wrong code is the same 400 page, the right one is then 429 with Retry-After, and another " + "address is not blocked") + { + // A typed code that is the real one by chance would make this flaky; the odds are 5 in 20^8. + for (auto const status : wrong) + { + CHECK(status == 400U); + } + CHECK(right.status == 429U); + auto const retry = response_header(right, "Retry-After"); + REQUIRE_FALSE(retry.empty()); + CHECK(std::stoul(retry) <= 600U); + CHECK(pending_of(right).empty()); + CHECK(elsewhere.status == 200U); + } + + AND_WHEN("ten minutes pass") + { + advance(rt, 600'000U); + auto const fresh = start_device(rt, fixture.client_id); + auto const later = post_link(rt, browser, fresh.user_code); + + THEN("the address may type codes again") + { + CHECK(later.status == 200U); + } + } + } + + WHEN("a post comes from another origin, and one comes without the cookie six times") + { + auto foreign = browser; + foreign.origin = "https://evil.example.net"; + auto const refused = post_link(rt, foreign, device.user_code); + auto cookieless = browser; + cookieless.cookie.clear(); + auto missing = std::vector{}; + for (auto attempt = 0U; attempt < 6U; ++attempt) + { + missing.push_back(post_link(rt, cookieless, device.user_code)); + } + auto const right = post_link(rt, browser, device.user_code); + + THEN("the foreign post is 403, the cookieless ones get the form and a cookie, and none counted") + { + CHECK(refused.status == 403U); + for (auto const& response : missing) + { + CHECK(response.status == 400U); + CHECK_FALSE(cookie_of(response).empty()); + CHECK(pending_of(response).empty()); + } + CHECK(right.status == 200U); + CHECK_FALSE(pending_of(right).empty()); + } + } + } +} + +SCENARIO("One browser at a time signs in for a user code", "[integration][oauth][oauth-device][security]") +{ + GIVEN("a pending device authorisation that a first browser has typed the code for") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const device = start_device(rt, fixture.client_id); + REQUIRE(device.response.status == 200U); + auto [first_page, first] = open_link(rt); + auto const first_login = post_link(rt, first, device.user_code); + REQUIRE(first_login.status == 200U); + auto const first_pending = pending_of(first_login); + + WHEN("a second browser types the code at once") + { + auto [second_page, second] = open_link(rt, {}, "203.0.113.50"); + auto const busy = post_link(rt, second, device.user_code); + + THEN("it is 409 with Retry-After and gets no sign-in") + { + CHECK(busy.status == 409U); + CHECK_FALSE(response_header(busy, "Retry-After").empty()); + CHECK(pending_of(busy).empty()); + } + } + + WHEN("the lease lapses, a second browser takes over, and the first then signs in") + { + advance(rt, hs::DeviceAuthorisationStore::attachment_lease_ms); + auto [second_page, second] = open_link(rt, {}, "203.0.113.50"); + auto const second_login = post_link(rt, second, device.user_code); + auto const first_consent = sign_in(rt, first, first_pending); + auto const second_consent = sign_in(rt, second, pending_of(second_login)); + auto const second_approved = answer(rt, second, pending_of(second_login), "approve"); + auto const granted = poll(rt, fixture.client_id, device.device_code); + + THEN("the first browser's sign-in has ended, and the second one's approval signs the device in") + { + REQUIRE(second_login.status == 200U); + CHECK(first_consent.status == 400U); + CHECK(contains(first_consent.body, "Device sign-in ended")); + CHECK(second_consent.status == 200U); + CHECK(second_approved.status == 200U); + CHECK(read_token_answer(granted).ok); + } + } + } + + GIVEN("a device authorisation the first browser has reached consent for") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const device = start_device(rt, fixture.client_id); + auto step = reach_consent(rt, device.user_code); + REQUIRE(step.consent.status == 200U); + + WHEN("it approves after another browser took the code over") + { + advance(rt, hs::DeviceAuthorisationStore::attachment_lease_ms); + auto [other_page, other] = open_link(rt, {}, "203.0.113.50"); + auto const taken = post_link(rt, other, device.user_code); + auto const approved = answer(rt, step.browser, step.pending, "approve"); + advance(rt, 5'000U); + auto const polled = poll(rt, fixture.client_id, device.device_code); + + THEN("the approval is the ended page and the device is still pending") + { + REQUIRE(taken.status == 200U); + CHECK(approved.status == 400U); + CHECK(oauth_error(polled) == "authorization_pending"); + CHECK(audit_count(rt.homeserver, "oauth.device.approved") == 0U); + } + } + } +} + +SCENARIO("With the device grant off, its routes do not exist and the token endpoint refuses the grant", + "[integration][oauth][oauth-device]") +{ + GIVEN("a server with the OAuth 2.0 API on and the device grant off") + { + auto fixture = make_fixture(false); + auto& rt = fixture.started.runtime; + + WHEN("a device asks for codes, a browser opens the link page, and the grant is polled") + { + auto const device = start_device(rt, fixture.client_id); + auto [page, browser] = open_link(rt); + auto const posted = post_link(rt, browser, "BCDF-GHJK"); + auto const polled = poll(rt, fixture.client_id, "anything"); + auto const metadata = hs::handle_client_server_request( + rt, {"GET", "/_matrix/client/v1/auth_metadata", {}, {}}, /*can_wait=*/false) + .response; + + THEN("the routes are 404 M_UNRECOGNIZED, the grant is unsupported_grant_type, and no device endpoint is " + "advertised") + { + CHECK(device.response.status == 404U); + CHECK(member(device.response, "errcode") == "M_UNRECOGNIZED"); + CHECK(page.status == 404U); + CHECK(posted.status == 404U); + CHECK(polled.status == 400U); + CHECK(oauth_error(polled) == "unsupported_grant_type"); + REQUIRE(metadata.status == 200U); + CHECK_FALSE(contains(metadata.body, "device_authorization_endpoint")); + } + } + } + + GIVEN("a server with the device grant on") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + + WHEN("the metadata is read") + { + auto const metadata = hs::handle_client_server_request( + rt, {"GET", "/_matrix/client/v1/auth_metadata", {}, {}}, /*can_wait=*/false) + .response; + + THEN("it names the device endpoint and the grant") + { + REQUIRE(metadata.status == 200U); + CHECK(contains( + metadata.body, + R"("device_authorization_endpoint":"https://matrix.example.org/_merovingian/oauth2/device")")); + CHECK(contains(metadata.body, device_grant)); + } + } + } +} diff --git a/tests/meson.build b/tests/meson.build index 465f88842..1534b5d8d 100644 --- a/tests/meson.build +++ b/tests/meson.build @@ -454,12 +454,14 @@ shell = find_program('sh') 'unit/test_oauth_account_pages.cpp', 'unit/test_oauth_account_session_store.cpp', 'unit/test_oauth_cross_signing_reset_approvals.cpp', + 'unit/test_oauth_device_authorisation_store.cpp', 'unit/test_oauth_pending_authorisation_store.cpp', 'unit/test_oauth_pkce.cpp', 'unit/test_oauth_redirect_uri.cpp', 'unit/test_oauth_scope.cpp', 'unit/test_oauth_server_metadata.cpp', 'unit/test_oauth_token_rules.cpp', + 'unit/test_oauth_user_code.cpp', 'unit/test_http_request_limits.cpp', 'unit/test_inbound_ingestion.cpp', 'unit/test_join_routing.cpp', @@ -664,6 +666,7 @@ shell = find_program('sh') 'conformance/test_oauth_account_management_conformance.cpp', 'conformance/test_oauth_authorization_conformance.cpp', 'conformance/test_oauth_client_registration_conformance.cpp', + 'conformance/test_oauth_device_grant_conformance.cpp', 'conformance/test_oauth_token_conformance.cpp', 'conformance/test_oauth_legacy_api_conformance.cpp', 'conformance/test_oauth_aware_clients_conformance.cpp', @@ -878,6 +881,7 @@ shell = find_program('sh') 'integration/test_oauth_account_creation_flow.cpp', 'integration/test_oauth_authorization_flow.cpp', 'integration/test_oauth_client_registration_flow.cpp', + 'integration/test_oauth_device_grant_flow.cpp', 'integration/test_oauth_log_query_flow.cpp', 'integration/test_oauth_metadata_flow.cpp', 'integration/test_oauth_password_login_flow.cpp', diff --git a/tests/unit/test_oauth_authorization_pages.cpp b/tests/unit/test_oauth_authorization_pages.cpp index a05330bbb..8a8aee7b6 100644 --- a/tests/unit/test_oauth_authorization_pages.cpp +++ b/tests/unit/test_oauth_authorization_pages.cpp @@ -2,19 +2,21 @@ // SPDX-License-Identifier: GPL-3.0-or-later // // The pages of the authorisation endpoint (oauth/AuthorizationPages.hpp, ADR-0763, ADR-0772): login, registration, -// consent and error, each a pure function of its inputs. Every slot is fed hostile text: markup, quotes, `&`, -// bidirectional override characters and a 10 KiB value. None may inject markup, and a value that cannot be shown is -// replaced by fixed text. +// consent, error and device (P11) pages, each a pure function of its inputs. Every slot is fed hostile text: markup, +// quotes, `&`, bidirectional override characters and a 10 KiB value. None may inject markup, and a value that cannot be +// shown is replaced by fixed text. #include "merovingian/oauth/AccountFormInput.hpp" #include "merovingian/oauth/AuthorizationPages.hpp" #include "merovingian/oauth/ConsentPageInput.hpp" +#include "merovingian/oauth/DeviceConsentPageInput.hpp" #include "merovingian/oauth/HtmlText.hpp" #include "merovingian/oauth/ParsedUri.hpp" #include #include +#include #include #include #include @@ -340,3 +342,125 @@ SCENARIO("The error page shows its title and message and no form", "[oauth][auth } } } + +SCENARIO("The device link page offers the code form and prefills only a code", "[oauth][authorize-page][device]") +{ + GIVEN("a stored user code and no code") + { + WHEN("the link page is rendered with each, and with an error") + { + auto const prefilled = merovingian::oauth::device_link_page("BCDFGHJK", std::nullopt).render(); + auto const empty = merovingian::oauth::device_link_page(std::nullopt, std::nullopt).render(); + auto const refused = + merovingian::oauth::device_link_page(std::nullopt, HtmlText{"That code is not right."}).render(); + + THEN("the form posts to the link page with the code field, shown as two groups of four when prefilled") + { + for (auto const* html : {&prefilled, &empty, &refused}) + { + REQUIRE(contains(*html, R"(action="/_merovingian/oauth2/link")")); + REQUIRE(contains(*html, R"(name="user_code")")); + REQUIRE(contains(*html, R"(autocomplete="off")")); + REQUIRE(count(*html, "tv.example.com")); + REQUIRE(contains(html, "full access to your account")); + REQUIRE_FALSE(contains(html, "signs that session out")); + } + + THEN("one form posts the pending identifier to the authorisation endpoint with allow and deny") + { + REQUIRE(count(html, "An application with no name")); + REQUIRE_FALSE(contains(html, "Television")); + REQUIRE(contains(html, "signs that session out and replaces it")); + REQUIRE_FALSE(contains(html, " + +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::homeserver::DeviceAuthorisationState; +using merovingian::homeserver::DeviceAuthorisationStore; +using merovingian::homeserver::UserCodeAttemptThrottle; +using PollOutcome = DeviceAuthorisationStore::PollOutcome; + +constexpr auto start_ms = std::uint64_t{1'000'000U}; +constexpr auto client = std::string_view{"client-a"}; +constexpr auto other_client = std::string_view{"client-b"}; +constexpr auto scope = std::string_view{"urn:matrix:client:api:* urn:matrix:client:device:TVDEVICE"}; +constexpr auto device = std::string_view{"TVDEVICE"}; +constexpr auto address = std::string_view{"198.51.100.7"}; +constexpr auto browser = std::string_view{"browser-one-token"}; +constexpr auto second_browser = std::string_view{"browser-two-token"}; + +// Hands out the byte strings it was given, in order, then fails. +[[nodiscard]] auto scripted(std::vector> draws) -> DeviceAuthorisationStore::RandomSource +{ + auto queue = std::make_shared>>(draws.begin(), draws.end()); + return [queue](std::size_t) -> std::optional> { + if (queue->empty()) + { + return std::nullopt; + } + auto next = std::move(queue->front()); + queue->pop_front(); + return next; + }; +} + +// A draw that gives the code whose characters are at `first` .. `first + 7` of the alphabet (modulo twenty). +[[nodiscard]] auto draw_from(std::uint8_t first) -> std::vector +{ + auto bytes = std::vector{}; + for (auto offset = std::uint8_t{0U}; offset < 8U; ++offset) + { + bytes.push_back(static_cast(first + offset)); + } + return bytes; +} + +[[nodiscard]] auto started(std::variant created) + -> DeviceAuthorisationStore::Started +{ + REQUIRE(std::holds_alternative(created)); + return std::get(std::move(created)); +} + +[[nodiscard]] auto attached(std::variant held) -> DeviceAuthorisationStore::Attached +{ + REQUIRE(std::holds_alternative(held)); + return std::get(std::move(held)); +} + +[[nodiscard]] auto address_number(std::size_t index) -> std::string +{ + return "address-" + std::to_string(index); +} + +} // namespace + +SCENARIO("A device authorisation hands out a device code and a user code once and keeps neither readable", + "[oauth][oauth-device]") +{ + GIVEN("an empty store") + { + auto store = DeviceAuthorisationStore{}; + + WHEN("a device authorisation is created") + { + auto const created = started(store.create(client, scope, device, address, start_ms)); + + THEN("the device is told the codes, ten minutes and five seconds") + { + REQUIRE(created.device_code.size() == 64U); + REQUIRE(created.user_code.size() == merovingian::oauth::user_code_length); + REQUIRE(merovingian::oauth::normalise_user_code(created.user_code) == created.user_code); + REQUIRE(created.expires_in_ms == 600'000U); + REQUIRE(created.interval_ms == 5'000U); + REQUIRE(store.size() == 1U); + } + + AND_THEN("the user code finds the entry, which holds what was asked and no user") + { + auto const hold = attached(store.attach(created.user_code, browser, start_ms)); + REQUIRE(hold.key != created.device_code); + REQUIRE(hold.authorisation.client_id == client); + REQUIRE(hold.authorisation.scope == scope); + REQUIRE(hold.authorisation.device_id == device); + REQUIRE(hold.authorisation.state == DeviceAuthorisationState::pending); + REQUIRE(hold.authorisation.user_id.empty()); + } + + AND_THEN("the device code does not find the entry on the link page") + { + REQUIRE(std::holds_alternative( + store.attach(created.device_code, browser, start_ms))); + } + } + } +} + +SCENARIO("A user code that clashes with a held one is drawn again, and a source that keeps clashing refuses", + "[oauth][oauth-device]") +{ + GIVEN("a source that gives the same code twice, then another") + { + auto store = DeviceAuthorisationStore{scripted({draw_from(0U), draw_from(0U), draw_from(1U)})}; + auto const first = started(store.create(client, scope, device, address, start_ms)); + + WHEN("a second authorisation is created") + { + auto const second = started(store.create(client, scope, device, address, start_ms)); + + THEN("it gets the third draw, not the clashing one") + { + REQUIRE(first.user_code == "BCDFGHJK"); + REQUIRE(second.user_code == "CDFGHJKL"); + } + } + } + + GIVEN("a source that gives only the held code") + { + auto draws = std::vector>{}; + for (auto index = std::size_t{0U}; index <= DeviceAuthorisationStore::max_user_code_draws; ++index) + { + draws.push_back(draw_from(0U)); + } + auto store = DeviceAuthorisationStore{scripted(std::move(draws))}; + std::ignore = started(store.create(client, scope, device, address, start_ms)); + + WHEN("another authorisation is created") + { + auto const refused = store.create(client, scope, device, address, start_ms); + + THEN("it is refused after the bounded number of draws, and nothing is stored") + { + REQUIRE(std::holds_alternative(refused)); + REQUIRE(std::get(refused) == + DeviceAuthorisationStore::Refusal::secret_unavailable); + REQUIRE(store.size() == 1U); + } + } + } + + GIVEN("a source that fails") + { + auto store = DeviceAuthorisationStore{scripted({})}; + + WHEN("an authorisation is created") + { + auto const refused = store.create(client, scope, device, address, start_ms); + + THEN("it is refused as a secret failure") + { + REQUIRE(std::get(refused) == + DeviceAuthorisationStore::Refusal::secret_unavailable); + REQUIRE(store.size() == 0U); + } + } + } +} + +SCENARIO("A device authorisation ends at exactly ten minutes", "[oauth][oauth-device]") +{ + GIVEN("an authorisation") + { + auto store = DeviceAuthorisationStore{}; + auto const created = started(store.create(client, scope, device, address, start_ms)); + auto const ends = start_ms + DeviceAuthorisationStore::lifetime_ms; + + WHEN("it is polled and looked up one millisecond before the end") + { + auto const poll = store.poll(created.device_code, client, ends - 1U); + + THEN("it is still pending") + { + REQUIRE(poll.outcome == PollOutcome::authorization_pending); + REQUIRE(store.holds_live_entry_for_client(client, ends - 1U)); + } + } + + WHEN("it is polled and looked up at the end") + { + auto const live = store.holds_live_entry_for_client(client, ends); + auto const poll = store.poll(created.device_code, client, ends); + auto const link = store.attach(created.user_code, browser, ends); + + THEN("it is gone: the device hears expired_token and the code is unknown") + { + REQUIRE_FALSE(live); + REQUIRE(poll.outcome == PollOutcome::expired_token); + REQUIRE(std::holds_alternative(link)); + REQUIRE(store.size() == 0U); + REQUIRE(store.live_count_for_client(client, ends) == 0U); + } + } + } +} + +SCENARIO("The store refuses past its caps and never evicts a live entry", "[oauth][oauth-device][security]") +{ + GIVEN("one address holding its eight authorisations") + { + auto store = DeviceAuthorisationStore{}; + for (auto index = std::size_t{0U}; index < DeviceAuthorisationStore::max_entries_per_address; ++index) + { + std::ignore = started(store.create(client, scope, device, address, start_ms)); + } + + WHEN("it asks for a ninth, and another address asks for one") + { + auto const ninth = store.create(client, scope, device, address, start_ms); + auto const elsewhere = store.create(client, scope, device, "203.0.113.9", start_ms); + + THEN("the ninth is refused for the address, and the other address is served") + { + REQUIRE(std::get(ninth) == + DeviceAuthorisationStore::Refusal::address_full); + REQUIRE(std::holds_alternative(elsewhere)); + REQUIRE(store.size() == DeviceAuthorisationStore::max_entries_per_address + 1U); + } + } + + WHEN("the eight have expired") + { + auto const later = + store.create(client, scope, device, address, start_ms + DeviceAuthorisationStore::lifetime_ms); + + THEN("the address is served again") + { + REQUIRE(std::holds_alternative(later)); + REQUIRE(store.size() == 1U); + } + } + } + + GIVEN("a full store") + { + auto store = DeviceAuthorisationStore{}; + for (auto index = std::size_t{0U}; index < DeviceAuthorisationStore::max_entries; ++index) + { + std::ignore = started(store.create( + client, scope, device, address_number(index / DeviceAuthorisationStore::max_entries_per_address), + start_ms + index)); + } + + WHEN("one more is asked for before the oldest expires, and again when it has") + { + auto const full = store.create(client, scope, device, "fresh-address", start_ms + 10'000U); + auto const after = + store.create(client, scope, device, "fresh-address", start_ms + DeviceAuthorisationStore::lifetime_ms); + + THEN("the first is refused with nothing evicted, and the second takes the expired entry's place") + { + REQUIRE(std::get(full) == + DeviceAuthorisationStore::Refusal::store_full); + REQUIRE(std::holds_alternative(after)); + REQUIRE(store.size() == DeviceAuthorisationStore::max_entries); + } + } + } +} + +SCENARIO("A device polling too fast is told to slow down, and its interval grows for good", "[oauth][oauth-device]") +{ + GIVEN("a pending authorisation") + { + auto store = DeviceAuthorisationStore{}; + auto const created = started(store.create(client, scope, device, address, start_ms)); + + WHEN("the device polls at once, then again a second later") + { + auto const first = store.poll(created.device_code, client, start_ms); + auto const second = store.poll(created.device_code, client, start_ms + 1'000U); + + THEN("the first poll is pending, the second slow_down with ten seconds") + { + REQUIRE(first.outcome == PollOutcome::authorization_pending); + REQUIRE(first.interval_ms == 5'000U); + REQUIRE(second.outcome == PollOutcome::slow_down); + REQUIRE(second.interval_ms == 10'000U); + } + + AND_WHEN("it next polls five seconds later, then ten seconds after that") + { + auto const five = store.poll(created.device_code, client, start_ms + 6'000U); + auto const ten = store.poll(created.device_code, client, start_ms + 16'000U); + + THEN("both are too soon under the grown interval, and a poll a whole interval later is in time") + { + REQUIRE(five.outcome == PollOutcome::slow_down); + REQUIRE(five.interval_ms == 15'000U); + REQUIRE(ten.outcome == PollOutcome::slow_down); + REQUIRE(ten.interval_ms == 20'000U); + auto const in_time = store.poll(created.device_code, client, start_ms + 36'000U); + REQUIRE(in_time.outcome == PollOutcome::authorization_pending); + REQUIRE(in_time.interval_ms == 20'000U); + } + } + } + + WHEN("the device polls exactly at its interval") + { + std::ignore = store.poll(created.device_code, client, start_ms); + auto const on_time = store.poll(created.device_code, client, start_ms + 5'000U); + + THEN("it is pending, not slow_down") + { + REQUIRE(on_time.outcome == PollOutcome::authorization_pending); + } + } + } +} + +SCENARIO("A device code polled by another client, or never issued, gives the device nothing", "[oauth][oauth-device]") +{ + GIVEN("an approved authorisation") + { + auto store = DeviceAuthorisationStore{}; + auto const created = started(store.create(client, scope, device, address, start_ms)); + auto const hold = attached(store.attach(created.user_code, browser, start_ms)); + REQUIRE(store.decide(hold.key, hold.attachment, "@alice:example.org", true, start_ms)); + + WHEN("another client polls with its device code, and a made-up code is polled") + { + auto const wrong = store.poll(created.device_code, other_client, start_ms + 5'000U); + auto const unknown = store.poll("not-a-device-code", client, start_ms + 5'000U); + + THEN("the other client is wrong_client, the made-up code expired_token, and the entry stays") + { + REQUIRE(wrong.outcome == PollOutcome::wrong_client); + REQUIRE_FALSE(wrong.authorisation.has_value()); + REQUIRE(unknown.outcome == PollOutcome::expired_token); + REQUIRE(store.size() == 1U); + } + } + + WHEN("its client polls twice") + { + auto const first = store.poll(created.device_code, client, start_ms + 5'000U); + auto const second = store.poll(created.device_code, client, start_ms + 10'000U); + + THEN("the first redeems it with the user, and the second hears expired_token") + { + REQUIRE(first.outcome == PollOutcome::approved); + REQUIRE(first.authorisation.has_value()); + REQUIRE(first.authorisation->user_id == "@alice:example.org"); + REQUIRE(first.authorisation->device_id == device); + REQUIRE(second.outcome == PollOutcome::expired_token); + REQUIRE(store.size() == 0U); + REQUIRE_FALSE(store.holds_live_entry_for_client(client, start_ms + 10'000U)); + } + } + } + + GIVEN("a denied authorisation") + { + auto store = DeviceAuthorisationStore{}; + auto const created = started(store.create(client, scope, device, address, start_ms)); + auto const hold = attached(store.attach(created.user_code, browser, start_ms)); + REQUIRE(store.decide(hold.key, hold.attachment, "@alice:example.org", false, start_ms)); + + WHEN("its client polls twice, and the code is typed again") + { + auto const first = store.poll(created.device_code, client, start_ms + 5'000U); + auto const second = store.poll(created.device_code, client, start_ms + 10'000U); + auto const retyped = store.attach(created.user_code, browser, start_ms + 10'000U); + + THEN("both polls hear access_denied, and the answered code is no longer found") + { + REQUIRE(first.outcome == PollOutcome::access_denied); + REQUIRE(second.outcome == PollOutcome::access_denied); + REQUIRE(std::holds_alternative(retyped)); + } + } + } +} + +SCENARIO("One browser at a time holds a device authorisation", "[oauth][oauth-device][security]") +{ + GIVEN("a pending authorisation the first browser holds") + { + auto store = DeviceAuthorisationStore{}; + auto const created = started(store.create(client, scope, device, address, start_ms)); + auto const first = attached(store.attach(created.user_code, browser, start_ms)); + + WHEN("a second browser types the code within the lease") + { + auto const busy = store.attach(created.user_code, second_browser, start_ms + 30'000U); + + THEN("it is busy until the lease ends, and the first browser still holds it") + { + REQUIRE(std::holds_alternative(busy)); + REQUIRE(std::get(busy).retry_after_ms == 90'000U); + REQUIRE(store.find_attached(first.key, first.attachment, start_ms + 30'000U).has_value()); + } + } + + WHEN("the first browser renews, and the second tries just after the original lease") + { + REQUIRE(store.renew(first.key, first.attachment, start_ms + 100'000U)); + auto const busy = store.attach(created.user_code, second_browser, + start_ms + DeviceAuthorisationStore::attachment_lease_ms); + + THEN("the renewed lease still holds it") + { + REQUIRE(std::holds_alternative(busy)); + } + } + + WHEN("the lease lapses and the second browser takes it over") + { + auto const lapse = start_ms + DeviceAuthorisationStore::attachment_lease_ms; + auto const second = attached(store.attach(created.user_code, second_browser, lapse)); + + THEN("the first browser can neither renew nor decide, and the second decides") + { + REQUIRE_FALSE(store.renew(first.key, first.attachment, lapse)); + REQUIRE_FALSE(store.decide(first.key, first.attachment, "@mallory:example.org", true, lapse)); + REQUIRE_FALSE(store.find_attached(first.key, first.attachment, lapse).has_value()); + REQUIRE(store.decide(second.key, second.attachment, "@alice:example.org", true, lapse)); + auto const poll = store.poll(created.device_code, client, lapse); + REQUIRE(poll.outcome == PollOutcome::approved); + REQUIRE(poll.authorisation->user_id == "@alice:example.org"); + } + } + + WHEN("the first browser releases it") + { + store.release(first.key, first.attachment); + auto const second = store.attach(created.user_code, second_browser, start_ms + 1'000U); + + THEN("the second browser takes it at once") + { + REQUIRE(std::holds_alternative(second)); + } + } + + WHEN("the first browser types the code again") + { + auto const again = attached(store.attach(created.user_code, browser, start_ms + 1'000U)); + + THEN("it holds a fresh attachment and the earlier one no longer decides") + { + REQUIRE(again.attachment != first.attachment); + REQUIRE_FALSE(store.decide(first.key, first.attachment, "@alice:example.org", true, start_ms + 1'000U)); + REQUIRE(store.decide(again.key, again.attachment, "@alice:example.org", true, start_ms + 1'000U)); + } + } + + WHEN("an empty browser token types the code") + { + auto const empty = store.attach(created.user_code, "", start_ms + 200'000U); + + THEN("it is not found") + { + REQUIRE(std::holds_alternative(empty)); + } + } + } +} + +SCENARIO("Live device authorisations are counted per client for client retention", "[oauth][oauth-device]") +{ + GIVEN("two authorisations for one client, created a minute apart") + { + auto store = DeviceAuthorisationStore{}; + std::ignore = started(store.create(client, scope, device, address, start_ms)); + std::ignore = started(store.create(client, scope, device, address, start_ms + 60'000U)); + + WHEN("the store is asked before and after the first expires, and after both") + { + auto const both = store.live_count_for_client(client, start_ms); + auto const one = store.live_count_for_client(client, start_ms + DeviceAuthorisationStore::lifetime_ms); + auto const held = + store.holds_live_entry_for_client(client, start_ms + DeviceAuthorisationStore::lifetime_ms); + auto const none_held = + store.holds_live_entry_for_client(client, start_ms + 60'000U + DeviceAuthorisationStore::lifetime_ms); + + THEN("the counts follow, and another client is never named") + { + REQUIRE(both == 2U); + REQUIRE(one == 1U); + REQUIRE(held); + REQUIRE_FALSE(none_held); + REQUIRE(store.live_count_for_client(other_client, start_ms) == 0U); + REQUIRE_FALSE(store.holds_live_entry_for_client(other_client, start_ms)); + } + } + } +} + +SCENARIO("Five wrong user codes from an address block it for the rest of ten minutes", + "[oauth][oauth-device][security]") +{ + GIVEN("an empty throttle") + { + auto throttle = UserCodeAttemptThrottle{}; + + WHEN("an address types four wrong codes") + { + auto reached = false; + for (auto attempt = 0U; attempt < 4U; ++attempt) + { + reached = throttle.record_wrong(address, start_ms + attempt) || reached; + } + + THEN("it is not blocked") + { + REQUIRE_FALSE(reached); + REQUIRE_FALSE(throttle.blocked_for_ms(address, start_ms + 4U).has_value()); + } + + AND_WHEN("it types a fifth a minute in") + { + auto const fifth = throttle.record_wrong(address, start_ms + 60'000U); + + THEN("the fifth reaches the limit, and the address waits until the window ends") + { + REQUIRE(fifth); + REQUIRE(throttle.blocked_for_ms(address, start_ms + 60'000U) == + std::optional{540'000U}); + REQUIRE(throttle.blocked_for_ms(address, start_ms + 599'999U) == std::optional{1U}); + REQUIRE_FALSE(throttle.blocked_for_ms(address, start_ms + 600'000U).has_value()); + REQUIRE_FALSE(throttle.blocked_for_ms("203.0.113.9", start_ms + 60'000U).has_value()); + REQUIRE_FALSE(throttle.record_wrong(address, start_ms + 70'000U)); + } + } + } + } + + GIVEN("a throttle holding a window for every address it can") + { + auto throttle = UserCodeAttemptThrottle{}; + for (auto index = std::size_t{0U}; index < UserCodeAttemptThrottle::max_addresses; ++index) + { + std::ignore = throttle.record_wrong(address_number(index), start_ms + index); + } + + WHEN("an address with no window asks, before and after the oldest window ends") + { + auto const before = throttle.blocked_for_ms("fresh-address", start_ms + 1'000U); + auto const counted = throttle.record_wrong("fresh-address", start_ms + 1'000U); + auto const after = throttle.blocked_for_ms("fresh-address", start_ms + UserCodeAttemptThrottle::window_ms); + + THEN("it is blocked until the oldest window ends, fails closed, and is let in afterwards") + { + REQUIRE(before == std::optional{UserCodeAttemptThrottle::window_ms - 1'000U}); + REQUIRE_FALSE(counted); + REQUIRE_FALSE(after.has_value()); + REQUIRE(throttle.size() == UserCodeAttemptThrottle::max_addresses - 1U); + } + } + } +} diff --git a/tests/unit/test_oauth_user_code.cpp b/tests/unit/test_oauth_user_code.cpp new file mode 100644 index 000000000..4b666f647 --- /dev/null +++ b/tests/unit/test_oauth_user_code.cpp @@ -0,0 +1,182 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +// Plan P11 (ADR-0805): the device authorization grant's user code. Eight characters from twenty consonants, drawn by +// rejection sampling; a typed code is read in any case and with dashes, spaces, dots or underscores, and anything else +// is refused whole. + +#include "merovingian/oauth/UserCode.hpp" + +#include + +#include +#include +#include +#include +#include +#include +#include + +namespace +{ + +using merovingian::oauth::display_user_code; +using merovingian::oauth::normalise_user_code; +using merovingian::oauth::user_code_alphabet; +using merovingian::oauth::user_code_from_bytes; +using merovingian::oauth::user_code_length; + +[[nodiscard]] auto from(std::vector const& bytes) -> std::optional +{ + return user_code_from_bytes(std::span{bytes}); +} + +} // namespace + +SCENARIO("A user code is eight alphabet characters, each byte below 240 giving one", "[oauth][user-code]") +{ + GIVEN("the alphabet") + { + THEN("it holds twenty distinct upper-case consonants and no vowel or digit") + { + REQUIRE(user_code_alphabet.size() == 20U); + for (auto const c : user_code_alphabet) + { + REQUIRE(c >= 'A'); + REQUIRE(c <= 'Z'); + REQUIRE(std::string_view{"AEIOUY"}.find(c) == std::string_view::npos); + REQUIRE(user_code_alphabet.find(c) == user_code_alphabet.rfind(c)); + } + } + } + + GIVEN("bytes whose values are the alphabet positions") + { + WHEN("a code is drawn from 0 to 7") + { + auto const code = from({0U, 1U, 2U, 3U, 4U, 5U, 6U, 7U}); + + THEN("it is the first eight characters") + { + REQUIRE(code == std::optional{"BCDFGHJK"}); + } + } + + WHEN("a code is drawn from bytes at the top of the accepted range") + { + auto const code = from({20U, 39U, 219U, 239U, 0U, 19U, 220U, 238U}); + + THEN("each byte gives the character at its value modulo twenty") + { + REQUIRE(code.has_value()); + REQUIRE(code->size() == user_code_length); + REQUIRE((*code)[0] == 'B'); + REQUIRE((*code)[1] == 'Z'); + REQUIRE((*code)[2] == 'Z'); + REQUIRE((*code)[3] == 'Z'); + REQUIRE((*code)[4] == 'B'); + REQUIRE((*code)[5] == 'Z'); + REQUIRE((*code)[6] == 'B'); + REQUIRE((*code)[7] == 'X'); + } + } + } + + GIVEN("bytes of 240 and over between accepted ones") + { + WHEN("a code is drawn") + { + auto const code = from({240U, 0U, 255U, 1U, 2U, 3U, 250U, 4U, 5U, 6U, 7U}); + + THEN("those bytes are skipped, so no character is more likely than another") + { + REQUIRE(code == std::optional{"BCDFGHJK"}); + } + } + } + + GIVEN("too few bytes below 240") + { + WHEN("a code is drawn from seven usable bytes and many rejected ones") + { + auto const code = from({0U, 1U, 2U, 3U, 4U, 5U, 6U, 240U, 241U, 255U}); + auto const empty = from({}); + + THEN("no code is made") + { + REQUIRE_FALSE(code.has_value()); + REQUIRE_FALSE(empty.has_value()); + } + } + } +} + +SCENARIO("A typed user code is read in any case, with separators skipped, and refused whole otherwise", + "[oauth][user-code][security]") +{ + GIVEN("the ways a user may type the code BCDFGHJK") + { + WHEN("each is read") + { + THEN("each is the stored form") + { + for (auto const typed : + {"BCDFGHJK", "bcdfghjk", "BCDF-GHJK", "bcdf ghjk", " BcDf.Gh_Jk ", "B-C-D-F-G-H-J-K"}) + { + REQUIRE(normalise_user_code(typed) == std::optional{"BCDFGHJK"}); + } + } + } + } + + GIVEN("text that is not a code") + { + WHEN("each is read") + { + THEN("each is refused") + { + // A vowel, a digit, a letter the alphabet lacks, seven and nine characters, a control byte, a + // non-ASCII letter, a plus sign, nothing at all, and only separators. + for (auto const typed : {"BCDFGHJA", "BCDFGHJ1", "BCDFGHJY", "BCDFGHJ", "BCDFGHJKL", "BCDF\tGHJK", + "BCDF\xC3\x89GHJK", "BCDF+GHJK", "", "----"}) + { + REQUIRE_FALSE(normalise_user_code(typed).has_value()); + } + } + } + } + + GIVEN("a right code padded past the length cap") + { + auto padded = std::string(merovingian::oauth::max_typed_user_code_bytes - 8U, ' '); + padded.append("BCDFGHJK"); + auto over = padded; + over.push_back(' '); + + WHEN("both are read") + { + THEN("the one at the cap is read and the one over it refused, never shortened") + { + REQUIRE(padded.size() == merovingian::oauth::max_typed_user_code_bytes); + REQUIRE(normalise_user_code(padded) == std::optional{"BCDFGHJK"}); + REQUIRE_FALSE(normalise_user_code(over).has_value()); + } + } + } +} + +SCENARIO("A stored user code is shown as two groups of four", "[oauth][user-code]") +{ + GIVEN("a stored code and text that is not one") + { + WHEN("each is shown") + { + THEN("the code gets a dash in the middle and the other text is unchanged") + { + REQUIRE(display_user_code("BCDFGHJK") == "BCDF-GHJK"); + REQUIRE(display_user_code("abc") == "abc"); + REQUIRE(display_user_code("BCDFGHJKL") == "BCDFGHJKL"); + } + } + } +} From 96ca4e234fba176814cd86e2ac0284e018caeaa3 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:14:44 +0000 Subject: [PATCH 23/42] End an OAuth sign-in in progress when the password changes (ADR-0807) A sign-in past the password step now records the user's credential stamp, a hash of the stored password hash. It travels with the authorisation code and the device approval, and approve, the code grant and the device-code grant compare it in constant time after account_sign_in_gate. A password change, reset or deactivation since makes it differ, and the sign-in is refused and spent instead of granted. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 3 +- ...password-check-and-ends-when-it-changes.md | 77 +++++++++++ docs/adr/index.md | 1 + docs/auth-identity.md | 14 +- docs/observability-audit.md | 4 +- docs/security-coding-rules.md | 7 + .../merovingian/homeserver/AuthService.hpp | 11 ++ .../homeserver/AuthorizationGrant.hpp | 3 + .../homeserver/DeviceAuthorisation.hpp | 3 + .../homeserver/DeviceAuthorisationStore.hpp | 9 +- .../homeserver/PendingAuthorisation.hpp | 9 +- .../homeserver/PendingAuthorisationStore.hpp | 11 +- src/homeserver/AGENTS.md | 11 +- src/homeserver/AuthService.cpp | 23 ++++ src/homeserver/DeviceAuthorisationStore.cpp | 3 +- src/homeserver/OAuthAuthorization.cpp | 28 +++- src/homeserver/OAuthTokenEndpoint.cpp | 10 ++ src/homeserver/PendingAuthorisationStore.cpp | 5 +- .../test_oauth_device_grant_flow.cpp | 64 ++++++++++ .../test_oauth_login_hand_off_flow.cpp | 45 +++++++ tests/integration/test_oauth_token_flow.cpp | 120 ++++++++++++++++++ .../test_oauth_device_authorisation_store.cpp | 15 ++- ...test_oauth_pending_authorisation_store.cpp | 8 +- 23 files changed, 452 insertions(+), 32 deletions(-) create mode 100644 docs/adr/0807-an-oauth-sign-in-carries-the-credential-stamp-of-its-password-check-and-ends-when-it-changes.md diff --git a/CHANGELOG.md b/CHANGELOG.md index f17712059..cc60424e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -81,9 +81,10 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) login hint cannot reach the log (ADR-0786). * Every password change, reset and deactivation now ends the user's account-page sessions and withdraws a cross-signing reset approval (ADR-0798). - * A response header that would frame the message (`Content-Length`, `Connection`, ...) or holds CR or LF now turns the response into a 500 instead of being written or silently dropped (ADR-0767). +* A password change, reset or deactivation now ends an OAuth sign-in already past the password, an unredeemed code + and an unpolled device approval: they are refused, not granted (ADR-0807). ## Bug fixes diff --git a/docs/adr/0807-an-oauth-sign-in-carries-the-credential-stamp-of-its-password-check-and-ends-when-it-changes.md b/docs/adr/0807-an-oauth-sign-in-carries-the-credential-stamp-of-its-password-check-and-ends-when-it-changes.md new file mode 100644 index 000000000..a75af9e63 --- /dev/null +++ b/docs/adr/0807-an-oauth-sign-in-carries-the-credential-stamp-of-its-password-check-and-ends-when-it-changes.md @@ -0,0 +1,77 @@ +# An OAuth sign-in carries the credential stamp of its password check and ends when it changes + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: review finding 1 on `feature/oauth-20-v110`. + +## Context and Problem Statement + +A sign-in on `/_merovingian/oauth2/authorize` checks the password once and records the user on the pending entry. +Everything after that trusts the record: the consent page's `approve` (ten minutes later at most), the authorization +code it mints (60 seconds), the device grant's approval and the poll that collects it, and the legacy hand-off's +confirmation. `account_sign_in_gate` at those steps refuses a deactivated or locked account, but not one whose password +changed. Someone who knows a user's password can therefore sign in and wait; when the user changes or resets the +password because of exactly that, the attacker still gets a code, tokens or a login token. How does a sign-in in +progress learn that the credential it checked is no longer the account's? + +## Decision Drivers + +* Every password change, reset and deactivation must end every sign-in in progress, without each of those paths + having to know about the OAuth stores (four paths today, and every future one). +* The value kept in the stores and compared must not reveal the password or its stored hash if a store's memory or a + log leaked, and must never be logged. +* A sign-in with no change in between must still work. + +## Considered Options + +* A credential stamp derived from the stored password hash, recorded when the password is verified or the account + created, and compared at every later step. +* Have every password change walk the pending, code and device stores and end the user's entries. +* A per-user generation counter, bumped by every password change. + +## Decision Outcome + +Chosen option: the credential stamp. `user_credential_stamp` (`AuthService.cpp`, the one place it is computed) is +`oauth_secret_hash` of the user's stored password hash, compared with `user_credential_stamp_matches` in constant time. +Every write of a password hash (change, email reset, account page, deactivation's `!deactivated`) stores a new +Argon2id string (`crypto_pwhash_str`) with a fresh random salt, so the stamp changes with it, and nothing has to remember to bump it. The +stored hash carries a 128-bit salt and a 256-bit tag, so its unkeyed BLAKE2b hash cannot test a password guess or be +reversed; the stamp is never logged and never leaves the process. + +It is recorded by `PendingAuthorisationStore::record_user`, taken in the same hold of `runtime.mutex` in which +`verify_password_login` confirmed the stored hash (or `create_local_account` wrote it), and carried into +`AuthorizationGrant::credential_stamp` and, through `DeviceAuthorisationStore::decide`, into the device authorisation's +approval. It is checked at `approve` for all three kinds of entry (an authorisation code, a device sign-in, the legacy +hand-off's confirmation), and at the token endpoint after `account_sign_in_gate` for the code grant and the device-code +grant. A mismatch is the expired page on a page (the entry is already consumed; a device sign-in releases its hold on +the device authorisation) and `invalid_grant` at the token endpoint (the code or device code is already spent). The +consent page is rendered in the same hold of the lock that recorded the stamp, so it needs no check of its own. + +### Positive Consequences + +* A password change ends an attacker's sign-in in progress whichever path changed it, including paths added later. +* The stores hold a value that is useless if leaked. + +### Negative Consequences + +* A sign-in started just before the user changed their own password must be started again. + +## Pros and Cons of the Options + +### Walk the stores on every password change + +* Bad, because each password path must call it, and a forgotten path is a silent hole. +* Bad, because the stores live in two runtimes (the code and device stores in `HomeserverRuntime`, nothing in the + pending store indexes by user), so it costs a scan. + +### A generation counter + +* Good, because it is cheap to compare. +* Bad, because it is new persistent state every password writer must bump; the stored hash already changes. + +## Links + +* Builds on [ADR-0782](0782-pending-authorisations-and-authorization-codes-are-in-memory-hashed-bounded-and-never-evicted.md) + and [ADR-0783](0783-login-verification-and-account-creation-are-one-function-each-shared-by-the-matrix-routes-and-the-oauth-pages.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 510529613..1c012557e 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -688,3 +688,4 @@ * [0804 - The device authorization grant answers RFC 8628, and a redeemed device code is expired](0804-the-device-authorization-grant-answers-rfc-8628-and-a-redeemed-device-code-is-expired.md) * [0805 - Device authorisations and user codes are held in memory, capped, and guessing is throttled per address](0805-device-authorisations-and-user-codes-are-held-in-memory-capped-and-guessing-is-throttled-per-address.md) * [0806 - A device sign-in warns first, creates no account, and runs in one browser at a time](0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md) +* [0807 - An OAuth sign-in carries the credential stamp of its password check and ends when it changes](0807-an-oauth-sign-in-carries-the-credential-stamp-of-its-password-check-and-ends-when-it-changes.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 1b7f4ee5f..4b0618805 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -1164,6 +1164,12 @@ characters. - **What it leaves.** An approval leaves one authorization code (60 s) and nothing else: no device, token or `oauth_sessions` row; the token endpoint creates those. No browser session is kept: every authorisation asks for the password (ADR-0787). +- **A password change ends a sign-in in progress (ADR-0807).** Signing in records the user's credential stamp + (`user_credential_stamp`: `oauth_secret_hash` of the stored password hash) on the entry; it travels with the code + and the device authorisation's approval. `approve` (every kind: the code, the device sign-in, the hand-off) and the + token endpoint's code and device-code grants compare it in constant time after `account_sign_in_gate`. Any password + change, reset or deactivation since makes it differ: the expired page on a page, `invalid_grant` at the token + endpoint, and the entry or code is spent. Logged `oauth.authorization.credentials_changed` (client and user only). ## OAuth 2.0 token and revocation endpoints (phases 6 and 7) @@ -1179,7 +1185,8 @@ read with `core::FormFields`; anything else is 400 `invalid_request`. Every answ registered (`invalid_client`) for `authorization_code` (`unauthorized_client`); the verifier well formed (`invalid_request`, the code is not spent); the code redeemed (unknown: `invalid_grant`); the client ID, the redirect URI byte for byte and the PKCE `S256` verifier matched (`invalid_grant`, the code is spent); then - `account_sign_in_gate` and the login's device checks (`invalid_grant`). `grant_oauth_session` (`AuthService.cpp`) + `account_sign_in_gate`, the credential stamp of the sign-in (ADR-0807) and the login's device checks + (`invalid_grant`). `grant_oauth_session` (`AuthService.cpp`) shares `admit_device_login` and `mint_login_token` with `login_local_user_by_id`, and `database::store_oauth_grant` writes the device (named after the client's `client_name` when it is new and fits the 256-byte cap), the deletion of the device's earlier tokens and OAuth row, both new tokens, the `oauth_sessions` row and the `oauth.session.granted` @@ -1274,7 +1281,7 @@ the spec's "Account management" names: `account_management_uri` and all six `org `PendingAuthorisation` of kind `login_token_hand_off` is started by the same `start_sign_in` as `/authorize`, and its forms post there: the shared cookie, Origin check, pending cap, login throttle and account creation. After the password a confirmation page (`page_headers(target)`) names the account and the destination. `approve` re-reads the - address, runs `account_sign_in_gate`, mints 32 random bytes into `LoginTokenStore` for + address, runs `account_sign_in_gate` and the credential stamp check (ADR-0807), mints 32 random bytes into `LoginTokenStore` for `hand_off_login_token_lifetime_ms` (30 s, under the get_token caps), audits `auth.login_token.issued` with reason `hand_off`, and answers 303 to `oauth::hand_off_return_address` (old `loginToken` parameters removed). `deny` answers a page. `POST /login` `m.login.token` redeems from that store when get_token or the hand-off is on. @@ -1317,7 +1324,8 @@ Served only while `server.oauth.enabled` and `server.oauth.device_grant_enabled` client checks of the device endpoint, then the store: `expired_token` (unknown, expired or already redeemed), `invalid_grant` (another client's code), `access_denied`, `slow_down` (sooner than the interval since the last poll; the interval grows by five seconds for good), `authorization_pending`. An approved code is redeemed once: - `account_sign_in_gate` again, then `grant_oauth_session` and the same answer as the code grant. + `account_sign_in_gate` again, the credential stamp of the approval (`invalid_grant` after a password change, + ADR-0807), then `grant_oauth_session` and the same answer as the code grant. ## Next starting points diff --git a/docs/observability-audit.md b/docs/observability-audit.md index c389b108f..f195c0422 100644 --- a/docs/observability-audit.md +++ b/docs/observability-audit.md @@ -566,7 +566,9 @@ limit, whose 429s are audited as `rate_limit.exceeded`. challenge, the code, the cookie, the pending identifier or a password. `oauth.authorization.granted` is also a durable audit row (category `auth`, actor the user, target the client ID, reason the device ID), as a successful `auth.login` is; `oauth.authorization.denied` is audited the same way only when a user had signed in, since a denial before the -password is anyone's to send. +password is anyone's to send. `oauth.authorization.credentials_changed` (info, `client_id` and `user_id`) records an +`approve` refused because the account's password changed since the sign-in (ADR-0807); the stamp itself is never +logged. The legacy login hand-off (ADR-0802) logs under the same module: `oauth.hand_off.started` (debug, no field), `oauth.hand_off.refused` (debug for a refused `redirectUrl` or a store refusal, no field; info with `user_id` when the diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index 3026144fe..dff8d4373 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1078,6 +1078,13 @@ quickly finding everything a given `AGENTS.md` file contributed. the wrong endpoint escapes its client binding (ADR-0792, ADR-0793). Source: `src/homeserver/AGENTS.md`, `src/auth/AGENTS.md`, `src/database/AGENTS.md`. +- **An OAuth sign-in carries the credential stamp of its password check, and every later step (`approve`, the code and + device-code grants) refuses it once the stamp no longer matches.** + Why: a sign-in in progress outlives the password check by up to ten minutes; without the stamp, someone who knew + the old password signs in, waits for the user's change or reset, and still gets tokens (CWE-613). The stamp is a + hash of the salted stored hash, never the hash itself, and is never logged (ADR-0807). + Source: `src/homeserver/AGENTS.md`. + - **Every endpoint that asks for User-Interactive Authentication refuses an OAuth session with 403 before checking a password, except a replacing cross-signing upload, which offers only the `m.oauth` stage; revocation or a replay ends a session only through the path `POST /logout` uses.** diff --git a/include/merovingian/homeserver/AuthService.hpp b/include/merovingian/homeserver/AuthService.hpp index 99b101ad5..a3e8de0dc 100644 --- a/include/merovingian/homeserver/AuthService.hpp +++ b/include/merovingian/homeserver/AuthService.hpp @@ -82,6 +82,17 @@ namespace merovingian::homeserver // the login does. The caller holds runtime.mutex; makes no call that releases it. [[nodiscard]] auto account_sign_in_gate(HomeserverRuntime& runtime, std::string_view user_id, std::string_view device_id) -> PasswordLoginVerification::Outcome; +// The credential stamp of `user_id` (ADR-0807): `oauth_secret_hash` of the stored password hash, 64 hex digits. Every +// password change, reset or deactivation writes a new stored hash with a fresh salt, so the stamp changes with it; +// the stamp names no password and cannot test a guess. An OAuth 2.0 sign-in records it when the password is verified +// or the account created, and every later step compares it (`user_credential_stamp_matches`). nullopt for an unknown +// user or a failed hash. The caller holds runtime.mutex; never logged, never sent. +[[nodiscard]] auto user_credential_stamp(HomeserverRuntime const& runtime, std::string_view user_id) + -> std::optional; +// Whether `stamp` is still `user_id`'s credential stamp, compared in constant time. False for an empty stamp, an +// unknown user or a failed hash, so a sign-in that recorded none never passes. +[[nodiscard]] auto user_credential_stamp_matches(HomeserverRuntime const& runtime, std::string_view user_id, + std::string_view stamp) -> bool; // Application Service API (Matrix v1.19): see the .cpp definitions for the // full spec citation. The caller MUST have already verified the presented // as_token and that the target user_id/localpart is within the appservice's diff --git a/include/merovingian/homeserver/AuthorizationGrant.hpp b/include/merovingian/homeserver/AuthorizationGrant.hpp index a0caff796..94218b01b 100644 --- a/include/merovingian/homeserver/AuthorizationGrant.hpp +++ b/include/merovingian/homeserver/AuthorizationGrant.hpp @@ -21,6 +21,9 @@ struct AuthorizationGrant final std::string device_id{}; // The granted scope in canonical order. std::string scope{}; + // The user's credential stamp when the password was verified (ADR-0807): the token endpoint refuses the code with + // `invalid_grant` once it no longer matches. + std::string credential_stamp{}; }; } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/DeviceAuthorisation.hpp b/include/merovingian/homeserver/DeviceAuthorisation.hpp index 7d61102ae..5583bf12c 100644 --- a/include/merovingian/homeserver/DeviceAuthorisation.hpp +++ b/include/merovingian/homeserver/DeviceAuthorisation.hpp @@ -33,6 +33,9 @@ struct DeviceAuthorisation final DeviceAuthorisationState state{DeviceAuthorisationState::pending}; // The user who approved or denied; empty while pending. std::string user_id{}; + // An approval only: the user's credential stamp when the password was verified (ADR-0807). The poll that takes the + // approval is refused with `invalid_grant` once it no longer matches. + std::string credential_stamp{}; }; } // namespace merovingian::homeserver diff --git a/include/merovingian/homeserver/DeviceAuthorisationStore.hpp b/include/merovingian/homeserver/DeviceAuthorisationStore.hpp index 4c61db433..b8e70fe86 100644 --- a/include/merovingian/homeserver/DeviceAuthorisationStore.hpp +++ b/include/merovingian/homeserver/DeviceAuthorisationStore.hpp @@ -129,10 +129,11 @@ class DeviceAuthorisationStore final // Ends `attachment` when it is the entry's latest, so another browser need not wait for the lease. auto release(std::string_view key, std::uint64_t attachment) -> void; - // Records `user_id`'s answer and ends the attachment. False, changing nothing, when `find_attached` would answer - // nullopt: the entry ended, was answered, or another browser took it over. - [[nodiscard]] auto decide(std::string_view key, std::uint64_t attachment, std::string_view user_id, bool approve, - std::uint64_t now_ms) -> bool; + // Records `user_id`'s answer and ends the attachment; an approval keeps `credential_stamp` (ADR-0807) for the poll + // to check. False, changing nothing, when `find_attached` would answer nullopt: the entry ended, was answered, or + // another browser took it over. + [[nodiscard]] auto decide(std::string_view key, std::uint64_t attachment, std::string_view user_id, + std::string_view credential_stamp, bool approve, std::uint64_t now_ms) -> bool; // RFC 8628 section 3.5, in the order the store judges a poll. enum class PollOutcome : std::uint8_t diff --git a/include/merovingian/homeserver/PendingAuthorisation.hpp b/include/merovingian/homeserver/PendingAuthorisation.hpp index 78bd294f2..7cfb9fddf 100644 --- a/include/merovingian/homeserver/PendingAuthorisation.hpp +++ b/include/merovingian/homeserver/PendingAuthorisation.hpp @@ -16,9 +16,9 @@ namespace merovingian::homeserver // and then approve or deny it (plan P5, ADR-0782). `PendingAuthorisationStore` holds it in memory under the hash of a // random identifier, bound to the browser by the hash of a cookie value. // -// Every field but `user_id`, `client_address_key` and `created_at_ms` is the request as the handler validated it, never -// repaired. The store sets -// `created_at_ms` and `client_address_key` from its own arguments and starts `user_id` empty. +// Every field but `user_id`, `credential_stamp`, `client_address_key` and `created_at_ms` is the request as the handler +// validated it, never repaired. The store sets `created_at_ms` and `client_address_key` from its own arguments and +// starts `user_id` and `credential_stamp` empty. struct PendingAuthorisation final { // What the entry ends in. A hand-off (`login_token_hand_off`, ADR-0802) has no client: `client_id`, `state`, @@ -44,6 +44,9 @@ struct PendingAuthorisation final std::optional login_hint{}; // The user whose password was verified on the login or registration page; empty until then. std::string user_id{}; + // That user's credential stamp when the password was verified or the account created (`user_credential_stamp`, + // ADR-0807); every later step refuses the entry once it no longer matches. Empty until then. + std::string credential_stamp{}; // The rate-limit client key of the browser that made the request (`rate_limit_client_key`). std::string client_address_key{}; // When the store took the entry, in milliseconds since the epoch. diff --git a/include/merovingian/homeserver/PendingAuthorisationStore.hpp b/include/merovingian/homeserver/PendingAuthorisationStore.hpp index 7eefd200e..7407fbfdf 100644 --- a/include/merovingian/homeserver/PendingAuthorisationStore.hpp +++ b/include/merovingian/homeserver/PendingAuthorisationStore.hpp @@ -60,7 +60,8 @@ class PendingAuthorisationStore final }; // Takes `authorisation`, bound to `browser_token`, for the browser at `client_address_key`, valid for - // `lifetime_ms` from `now_ms`. Sets its `created_at_ms` and `client_address_key` and empties its `user_id`. + // `lifetime_ms` from `now_ms`. Sets its `created_at_ms` and `client_address_key` and empties its `user_id` and + // `credential_stamp`. // Returns the fresh identifier (`make_oauth_secret`, 64 hex digits), once, or why nothing was stored. [[nodiscard]] auto create(PendingAuthorisation authorisation, std::string_view browser_token, std::string_view client_address_key, std::uint64_t now_ms) @@ -71,10 +72,12 @@ class PendingAuthorisationStore final [[nodiscard]] auto find(std::string_view identifier, std::string_view browser_token, std::uint64_t now_ms) -> std::optional; - // Records `user_id` as the user whose password was verified for the entry. False, changing nothing, when `find` - // would answer nullopt. Does not extend the entry's lifetime. + // Records `user_id` as the user whose password was verified for the entry, with that user's credential stamp at + // the moment of the check (`user_credential_stamp`, ADR-0807). False, changing nothing, when `find` would answer + // nullopt. Does not extend the entry's lifetime. [[nodiscard]] auto record_user(std::string_view identifier, std::string_view browser_token, - std::string_view user_id, std::uint64_t now_ms) -> bool; + std::string_view user_id, std::string_view credential_stamp, std::uint64_t now_ms) + -> bool; // Removes the entry and returns it, for an approval or a denial; nullopt, removing nothing, when `find` would // answer nullopt (a wrong token does not spend the entry). diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 3f70b97e1..1543bf6e5 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -156,6 +156,11 @@ Rules for the authorisation pages: - **`verify_password_login` and `create_local_account` release `runtime.mutex`.** Nothing read before them is trusted after: `record_user` finds the entry again, and `approve` consumes it and judges the account again with `account_sign_in_gate`. +- **A sign-in carries the credential stamp of its password check** (ADR-0807). `record_user` stores + `user_credential_stamp` (`AuthService.cpp`, the only place it is computed); it travels in `AuthorizationGrant` and the + device authorisation's approval, and `approve` and the token endpoint's code and device-code grants call + `user_credential_stamp_matches` after `account_sign_in_gate`. A new step that acts on an earlier password check + compares it too. Never log it, and never put the password hash itself in a store. - **No browser session is kept** (ADR-0787): every authorisation asks for the password, and `prompt=none` is `login_required`. - **An approval leaves one authorization code and nothing else**: no device, token or `oauth_sessions` row; the token @@ -170,7 +175,8 @@ gate; `ClientServerRuntime.cpp` holds only the route matches. Rules: Then `remember_signed_in_device` adds the device to the runtime's list as `POST /login` does; never add a write after the commit that a failure could leave behind. - **The code grant's checks are in order**: client and grant type, verifier shape, redeem (a spent code whatever - follows), then client, redirect URI byte for byte and PKCE, then `account_sign_in_gate` and the device checks. A + follows), then client, redirect URI byte for byte and PKCE, then `account_sign_in_gate`, the credential stamp and the + device checks. A replayed code ends only the session that code produced (`AuthorizationCodeStore::record_issued_session`, matched on client and `created_at_ms`). - **A session ends through `end_device_session_and_announce`** (`ClientDeviceSessions.hpp`), shared with `POST /logout`: @@ -236,7 +242,8 @@ unless `server.oauth.enabled` and `server.oauth.device_grant_enabled` are both t registration. - **The consent page's warning is the first thing on it**, before the code and the client. Do not move it below them. - **A redeemed device code is `expired_token`**: the store removes an approved entry when the poll takes it. The - approval is judged again with `account_sign_in_gate` and written with `grant_oauth_session`, never another path. + approval is judged again with `account_sign_in_gate` and its credential stamp, and written with + `grant_oauth_session`, never another path. - `authorization_pending` is never logged (a device polls every five seconds). Log `client_id`, `user_id`, `device_id` and, for the throttle, `client_key`; never a device code, a user code, the cookie or the query. diff --git a/src/homeserver/AuthService.cpp b/src/homeserver/AuthService.cpp index 4f778acdf..992e1e5b6 100644 --- a/src/homeserver/AuthService.cpp +++ b/src/homeserver/AuthService.cpp @@ -33,6 +33,7 @@ #include "merovingian/homeserver/DeactivationAudit.hpp" #include "merovingian/homeserver/DeviceLimits.hpp" #include "merovingian/homeserver/LocalServices.hpp" +#include "merovingian/homeserver/OAuthSecret.hpp" #include "merovingian/homeserver/OpenidTokenIssueResult.hpp" #include "merovingian/homeserver/PasswordVerificationResult.hpp" #include "merovingian/homeserver/RuntimeLockRelease.hpp" @@ -1535,6 +1536,28 @@ auto account_sign_in_gate(HomeserverRuntime& runtime, std::string_view user_id, return PasswordLoginVerification::Outcome::verified; } +auto user_credential_stamp(HomeserverRuntime const& runtime, std::string_view user_id) -> std::optional +{ + auto const* user = find_user(runtime.database, user_id); + if (user == nullptr) + { + return std::nullopt; + } + // The stored hash carries its own random salt, so an unkeyed hash of it is as unguessable as an OAuth secret. + return oauth_secret_hash(user->password_hash); +} + +auto user_credential_stamp_matches(HomeserverRuntime const& runtime, std::string_view user_id, std::string_view stamp) + -> bool +{ + if (stamp.empty()) + { + return false; + } + auto const current = user_credential_stamp(runtime, user_id); + return current.has_value() && crypto::constant_time_equal(*current, stamp); +} + // NOLINTBEGIN(bugprone-easily-swappable-parameters) auto login_local_user(HomeserverRuntime& runtime, std::string_view user_id, std::string_view password, std::string_view device_id, bool with_ttl, std::string_view client_source, diff --git a/src/homeserver/DeviceAuthorisationStore.cpp b/src/homeserver/DeviceAuthorisationStore.cpp index 5372a4091..a95283813 100644 --- a/src/homeserver/DeviceAuthorisationStore.cpp +++ b/src/homeserver/DeviceAuthorisationStore.cpp @@ -196,7 +196,7 @@ auto DeviceAuthorisationStore::release(std::string_view key, std::uint64_t attac } auto DeviceAuthorisationStore::decide(std::string_view key, std::uint64_t attachment, std::string_view user_id, - bool approve, std::uint64_t now_ms) -> bool + std::string_view credential_stamp, bool approve, std::uint64_t now_ms) -> bool { auto* entry = attached_entry(key, attachment, now_ms); if (entry == nullptr) @@ -205,6 +205,7 @@ auto DeviceAuthorisationStore::decide(std::string_view key, std::uint64_t attach } entry->authorisation.state = approve ? DeviceAuthorisationState::approved : DeviceAuthorisationState::denied; entry->authorisation.user_id = std::string{user_id}; + entry->authorisation.credential_stamp = approve ? std::string{credential_stamp} : std::string{}; entry->attachment.reset(); return true; } diff --git a/src/homeserver/OAuthAuthorization.cpp b/src/homeserver/OAuthAuthorization.cpp index 8310f11a5..18aaad3a8 100644 --- a/src/homeserver/OAuthAuthorization.cpp +++ b/src/homeserver/OAuthAuthorization.cpp @@ -413,7 +413,11 @@ namespace [[nodiscard]] auto authenticated(FormPost const& post, std::string_view user_id) -> LocalHttpResponse { auto& store = post.runtime.homeserver.oauth_pending_authorisations; - if (!store.record_user(post.pending_id, post.browser_token, user_id, oauth_wall_clock_ms())) + // Taken under the same hold of runtime.mutex that verified the password (or created the account), so it is the + // stamp of the credential just checked (ADR-0807). + auto const stamp = user_credential_stamp(post.runtime.homeserver, user_id); + if (!stamp.has_value() || + !store.record_user(post.pending_id, post.browser_token, user_id, *stamp, oauth_wall_clock_ms())) { return expired_page(); } @@ -648,8 +652,8 @@ namespace return oauth_error_page_response(status_forbidden, oauth::HtmlText{"Sign-in refused"}, oauth::HtmlText{"This account cannot sign in."}); } - if (!devices.decide(consumed.device_authorisation_key, consumed.device_attachment, consumed.user_id, approve, - oauth_device_clock_ms(runtime))) + if (!devices.decide(consumed.device_authorisation_key, consumed.device_attachment, consumed.user_id, + consumed.credential_stamp, approve, oauth_device_clock_ms(runtime))) { return device_sign_in_ended_page(); } @@ -676,6 +680,23 @@ namespace { return expired_page(); } + // The password that signed in must still be the account's (ADR-0807): a change, reset or deactivation since + // ends this sign-in of every kind, and the entry is already spent. + if (!user_credential_stamp_matches(runtime, consumed->user_id, consumed->credential_stamp)) + { + if (is_device_sign_in(*consumed)) + { + runtime.oauth_device_authorisations.release(consumed->device_authorisation_key, + consumed->device_attachment); + } + log_oauth("oauth.authorization.credentials_changed", + { + {"client_id", consumed->client_id, false}, + {"user_id", consumed->user_id, false} + }, + observability::LogEventSeverity::info); + return expired_page(); + } if (is_hand_off(*consumed)) { return finish_hand_off(post.runtime, *consumed); @@ -703,6 +724,7 @@ namespace grant.user_id = consumed->user_id; grant.device_id = consumed->device_id; grant.scope = consumed->scope; + grant.credential_stamp = consumed->credential_stamp; auto issued = runtime.oauth_codes.issue(std::move(grant), now_ms); auto const* code = std::get_if(&issued); if (code == nullptr) diff --git a/src/homeserver/OAuthTokenEndpoint.cpp b/src/homeserver/OAuthTokenEndpoint.cpp index cf7862de1..3176c6ad8 100644 --- a/src/homeserver/OAuthTokenEndpoint.cpp +++ b/src/homeserver/OAuthTokenEndpoint.cpp @@ -186,6 +186,11 @@ namespace { return refuse(status_bad_request, oauth::error_invalid_grant, "The account cannot sign in."); } + // The password that signed in must still be the account's (ADR-0807); the code is spent either way. + if (!user_credential_stamp_matches(runtime, grant.user_id, grant.credential_stamp)) + { + return refuse(status_bad_request, oauth::error_invalid_grant, "The authorization is no longer valid."); + } auto request = OAuthGrantRequest{}; request.user_id = grant.user_id; @@ -274,6 +279,11 @@ namespace { return refuse(status_bad_request, oauth::error_invalid_grant, "The account cannot sign in."); } + // The password that approved must still be the account's (ADR-0807); the device code is spent either way. + if (!user_credential_stamp_matches(runtime, approved.user_id, approved.credential_stamp)) + { + return refuse(status_bad_request, oauth::error_invalid_grant, "The authorization is no longer valid."); + } auto request = OAuthGrantRequest{}; request.user_id = approved.user_id; request.device_id = approved.device_id; diff --git a/src/homeserver/PendingAuthorisationStore.cpp b/src/homeserver/PendingAuthorisationStore.cpp index 343347a1e..3919c6728 100644 --- a/src/homeserver/PendingAuthorisationStore.cpp +++ b/src/homeserver/PendingAuthorisationStore.cpp @@ -78,6 +78,7 @@ auto PendingAuthorisationStore::create(PendingAuthorisation authorisation, std:: authorisation.client_address_key = std::string{client_address_key}; authorisation.created_at_ms = now_ms; authorisation.user_id.clear(); + authorisation.credential_stamp.clear(); auto const expires_at_ms = now_ms + lifetime_ms; ++m_count_by_address[authorisation.client_address_key]; m_expiries_by_client[authorisation.client_id].insert(expires_at_ms); @@ -119,7 +120,8 @@ auto PendingAuthorisationStore::find(std::string_view identifier, std::string_vi } auto PendingAuthorisationStore::record_user(std::string_view identifier, std::string_view browser_token, - std::string_view user_id, std::uint64_t now_ms) -> bool + std::string_view user_id, std::string_view credential_stamp, + std::uint64_t now_ms) -> bool { auto const [entry, identifier_hash] = bound_entry(identifier, browser_token, now_ms); if (entry == nullptr) @@ -127,6 +129,7 @@ auto PendingAuthorisationStore::record_user(std::string_view identifier, std::st return false; } entry->authorisation.user_id = std::string{user_id}; + entry->authorisation.credential_stamp = std::string{credential_stamp}; return true; } diff --git a/tests/integration/test_oauth_device_grant_flow.cpp b/tests/integration/test_oauth_device_grant_flow.cpp index 30d60a18f..9e223333d 100644 --- a/tests/integration/test_oauth_device_grant_flow.cpp +++ b/tests/integration/test_oauth_device_grant_flow.cpp @@ -13,6 +13,7 @@ #include "../support/OAuthTokenSupport.hpp" #include "../support/RegistrationToken.hpp" #include "merovingian/config/Config.hpp" +#include "merovingian/database/PersistentStore.hpp" #include "merovingian/homeserver/AuthService.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" @@ -704,3 +705,66 @@ SCENARIO("With the device grant off, its routes do not exist and the token endpo } } } + +SCENARIO("A password change ends a device sign-in that is not yet approved or not yet polled", + "[integration][oauth][oauth-device][credential-stamp][security]") +{ + GIVEN("a device waiting for alice, who signed in on the link page with her password") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const device = start_device(rt, fixture.client_id); + auto step = reach_consent(rt, device.user_code); + REQUIRE(step.consent.status == 200U); + + WHEN("her password is reset by email before she allows the device") + { + REQUIRE(hs::reset_local_user_password(rt.homeserver, alice_id, "NewAlicePass42!y", true).ok); + auto const approved = answer(rt, step.browser, step.pending, "approve"); + advance(rt, 5'000U); + auto const polled = poll(rt, fixture.client_id, device.device_code); + + THEN("the approval is refused as expired and the device is still waiting, with no device created") + { + CHECK(approved.status == 400U); + CHECK(contains(approved.body, "Sign-in expired")); + CHECK(oauth_error(polled) == "authorization_pending"); + CHECK(audit_count(rt.homeserver, "oauth.device.approved") == 0U); + CHECK_FALSE(merovingian::database::has_user_device(rt.homeserver.database.persistent_store, alice_id, + tv_device)); + } + } + + WHEN("she allows the device and her password is changed on the account page before it polls") + { + REQUIRE(answer(rt, step.browser, step.pending, "approve").status == 200U); + REQUIRE(hs::change_password_on_account_page(rt.homeserver, alice_id, "NewAlicePass42!y").ok); + advance(rt, 5'000U); + auto const polled = poll(rt, fixture.client_id, device.device_code); + advance(rt, 5'000U); + auto const again = poll(rt, fixture.client_id, device.device_code); + + THEN("the poll is invalid_grant, the device code is spent, and no session was granted") + { + CHECK(polled.status == 400U); + CHECK(oauth_error(polled) == "invalid_grant"); + CHECK(oauth_error(again) == "expired_token"); + CHECK(audit_count(rt.homeserver, "oauth.session.granted") == 0U); + CHECK_FALSE(merovingian::database::has_user_device(rt.homeserver.database.persistent_store, alice_id, + tv_device)); + } + } + + WHEN("she allows the device and nothing changes before it polls") + { + REQUIRE(answer(rt, step.browser, step.pending, "approve").status == 200U); + advance(rt, 5'000U); + auto const tokens = read_token_answer(poll(rt, fixture.client_id, device.device_code)); + + THEN("the device gets its tokens") + { + CHECK(tokens.ok); + } + } + } +} diff --git a/tests/integration/test_oauth_login_hand_off_flow.cpp b/tests/integration/test_oauth_login_hand_off_flow.cpp index 7a67edaf9..717400f53 100644 --- a/tests/integration/test_oauth_login_hand_off_flow.cpp +++ b/tests/integration/test_oauth_login_hand_off_flow.cpp @@ -403,3 +403,48 @@ SCENARIO("The SSO redirect honours action, the identity provider form and the al } } } + +SCENARIO("A password change ends a hand-off that alice signed in to but did not yet continue", + "[integration][oauth][hand-off][credential-stamp][security]") +{ + GIVEN("a hand-off alice signed in to with her password") + { + auto started = start(hand_off_config()); + auto& rt = started.runtime; + auto const hand_off = open_hand_off(rt, { + {"redirectUrl", std::string{app_return}} + }); + REQUIRE(sign_in(rt, hand_off).status == 200U); + + WHEN("her password is changed on the account page and the hand-off is then continued") + { + REQUIRE(hs::change_password_on_account_page(rt.homeserver, "@alice:example.org", "NewAlicePass42!y").ok); + auto const approved = post(rt, hand_off, + { + {"action", "approve"} + }); + + THEN("it is the expired page: no redirect and no login token") + { + CHECK(approved.status == 400U); + CHECK(contains(approved.body, "Sign-in expired")); + CHECK(response_header(approved, "Location").empty()); + CHECK(audit_count(rt.homeserver, "auth.login_token.issued") == 0U); + } + } + + WHEN("nothing changes before the hand-off is continued") + { + auto const approved = post(rt, hand_off, + { + {"action", "approve"} + }); + + THEN("the browser is sent back with a login token") + { + CHECK(approved.status == 303U); + CHECK(audit_count(rt.homeserver, "auth.login_token.issued") == 1U); + } + } + } +} diff --git a/tests/integration/test_oauth_token_flow.cpp b/tests/integration/test_oauth_token_flow.cpp index da5806412..100819bb8 100644 --- a/tests/integration/test_oauth_token_flow.cpp +++ b/tests/integration/test_oauth_token_flow.cpp @@ -820,3 +820,123 @@ SCENARIO("An application service replaces cross-signing keys without User-Intera } } } + +namespace +{ + +// Signs alice in on the authorisation page and stops at the consent page: the browser and the pending identifier the +// approval needs. +struct SignedInOnPage final +{ + BrowserContext browser; + std::string pending; +}; + +[[nodiscard]] auto sign_in_on_page(hs::ClientServerRuntime& rt, std::string_view client_id) -> SignedInOnPage +{ + auto signed_in = SignedInOnPage{}; + auto const page = get_authorize(rt, oauth_authorize_parameters(client_id), signed_in.browser); + signed_in.pending = pending_of(page); + signed_in.browser.cookie = cookie_of(page); + REQUIRE(page.status == 200U); + auto const consent = post_authorize(rt, + { + {"pending", signed_in.pending }, + {"action", "login" }, + {"username", "alice" }, + {"password", std::string{alice_password}}, + }, + signed_in.browser); + REQUIRE(consent.status == 200U); + return signed_in; +} + +// POST /account/password from a legacy session of alice, keeping her other devices. +[[nodiscard]] auto change_password_through_client_api(hs::ClientServerRuntime& rt) -> std::uint16_t +{ + auto const login = legacy_login(rt, "PWDEVICE"); + REQUIRE(login.status == 200U); + return static_cast( + send(rt, "POST", "/_matrix/client/v3/account/password", member(login, "access_token"), + R"({"auth":{"type":"m.login.password","identifier":{"type":"m.id.user","user":"@alice:example.org"},)" + R"("password":")" + + std::string{alice_password} + R"("},"new_password":"NewAlicePass42!y","logout_devices":false})") + .status); +} + +} // namespace + +SCENARIO("A password change ends a sign-in waiting for approval and a code not yet redeemed", + "[integration][oauth][oauth-token][credential-stamp][security]") +{ + GIVEN("alice and a registered web client") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + + WHEN("alice signs in on the page, then changes her password through POST /account/password, then approves") + { + auto const signed_in = sign_in_on_page(rt, fixture.client_id); + REQUIRE(change_password_through_client_api(rt) == 200U); + auto const approved = post_authorize(rt, + { + {"pending", signed_in.pending}, + {"action", "approve" }, + }, + signed_in.browser); + + THEN("the approval is the expired page, no code is sent and the entry is spent") + { + CHECK(approved.status == 400U); + CHECK(approved.body.find("Sign-in expired") != std::string::npos); + CHECK(response_header(approved, "Location").empty()); + CHECK(rt.homeserver.oauth_pending_authorisations.size() == 0U); + CHECK(audit_count(rt, "oauth.authorization.granted") == 0U); + } + } + + WHEN("a code is issued, then alice's password is changed on the account page, then the code is redeemed") + { + auto const code = obtain_oauth_code(rt, fixture.client_id, "alice", alice_password); + REQUIRE_FALSE(code.empty()); + REQUIRE(hs::change_password_on_account_page(rt.homeserver, alice_id, "NewAlicePass42!y").ok); + auto const redeemed = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + auto const again = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + + THEN("the redemption is invalid_grant, writes no session, and the code is spent") + { + CHECK(redeemed.status == 400U); + CHECK(oauth_error(redeemed) == "invalid_grant"); + CHECK(oauth_error(again) == "invalid_grant"); + CHECK_FALSE(holds_device(rt, oauth_test_device)); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + CHECK(audit_count(rt, "oauth.session.granted") == 0U); + } + } + + WHEN("a code is issued, then alice's password is reset by email, then the code is redeemed") + { + auto const code = obtain_oauth_code(rt, fixture.client_id, "alice", alice_password); + REQUIRE_FALSE(code.empty()); + REQUIRE(hs::reset_local_user_password(rt.homeserver, alice_id, "NewAlicePass42!y", false).ok); + auto const redeemed = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + + THEN("the redemption is invalid_grant and writes no session") + { + CHECK(oauth_error(redeemed) == "invalid_grant"); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + } + } + + WHEN("alice signs in, approves and the code is redeemed with no change in between") + { + auto const answer = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + + THEN("the session is granted") + { + CHECK(answer.ok); + CHECK(oauth_row(rt, oauth_test_device) != nullptr); + } + } + } +} diff --git a/tests/unit/test_oauth_device_authorisation_store.cpp b/tests/unit/test_oauth_device_authorisation_store.cpp index 51f231db2..350a09396 100644 --- a/tests/unit/test_oauth_device_authorisation_store.cpp +++ b/tests/unit/test_oauth_device_authorisation_store.cpp @@ -351,7 +351,7 @@ SCENARIO("A device code polled by another client, or never issued, gives the dev auto store = DeviceAuthorisationStore{}; auto const created = started(store.create(client, scope, device, address, start_ms)); auto const hold = attached(store.attach(created.user_code, browser, start_ms)); - REQUIRE(store.decide(hold.key, hold.attachment, "@alice:example.org", true, start_ms)); + REQUIRE(store.decide(hold.key, hold.attachment, "@alice:example.org", "stamp", true, start_ms)); WHEN("another client polls with its device code, and a made-up code is polled") { @@ -378,6 +378,7 @@ SCENARIO("A device code polled by another client, or never issued, gives the dev REQUIRE(first.authorisation.has_value()); REQUIRE(first.authorisation->user_id == "@alice:example.org"); REQUIRE(first.authorisation->device_id == device); + REQUIRE(first.authorisation->credential_stamp == "stamp"); REQUIRE(second.outcome == PollOutcome::expired_token); REQUIRE(store.size() == 0U); REQUIRE_FALSE(store.holds_live_entry_for_client(client, start_ms + 10'000U)); @@ -390,7 +391,7 @@ SCENARIO("A device code polled by another client, or never issued, gives the dev auto store = DeviceAuthorisationStore{}; auto const created = started(store.create(client, scope, device, address, start_ms)); auto const hold = attached(store.attach(created.user_code, browser, start_ms)); - REQUIRE(store.decide(hold.key, hold.attachment, "@alice:example.org", false, start_ms)); + REQUIRE(store.decide(hold.key, hold.attachment, "@alice:example.org", "stamp", false, start_ms)); WHEN("its client polls twice, and the code is typed again") { @@ -448,9 +449,9 @@ SCENARIO("One browser at a time holds a device authorisation", "[oauth][oauth-de THEN("the first browser can neither renew nor decide, and the second decides") { REQUIRE_FALSE(store.renew(first.key, first.attachment, lapse)); - REQUIRE_FALSE(store.decide(first.key, first.attachment, "@mallory:example.org", true, lapse)); + REQUIRE_FALSE(store.decide(first.key, first.attachment, "@mallory:example.org", "stamp", true, lapse)); REQUIRE_FALSE(store.find_attached(first.key, first.attachment, lapse).has_value()); - REQUIRE(store.decide(second.key, second.attachment, "@alice:example.org", true, lapse)); + REQUIRE(store.decide(second.key, second.attachment, "@alice:example.org", "stamp", true, lapse)); auto const poll = store.poll(created.device_code, client, lapse); REQUIRE(poll.outcome == PollOutcome::approved); REQUIRE(poll.authorisation->user_id == "@alice:example.org"); @@ -475,8 +476,10 @@ SCENARIO("One browser at a time holds a device authorisation", "[oauth][oauth-de THEN("it holds a fresh attachment and the earlier one no longer decides") { REQUIRE(again.attachment != first.attachment); - REQUIRE_FALSE(store.decide(first.key, first.attachment, "@alice:example.org", true, start_ms + 1'000U)); - REQUIRE(store.decide(again.key, again.attachment, "@alice:example.org", true, start_ms + 1'000U)); + REQUIRE_FALSE( + store.decide(first.key, first.attachment, "@alice:example.org", "stamp", true, start_ms + 1'000U)); + REQUIRE( + store.decide(again.key, again.attachment, "@alice:example.org", "stamp", true, start_ms + 1'000U)); } } diff --git a/tests/unit/test_oauth_pending_authorisation_store.cpp b/tests/unit/test_oauth_pending_authorisation_store.cpp index cc7a69d41..82ee85565 100644 --- a/tests/unit/test_oauth_pending_authorisation_store.cpp +++ b/tests/unit/test_oauth_pending_authorisation_store.cpp @@ -121,7 +121,8 @@ SCENARIO("A pending authorisation is stored under a fresh identifier and read ba WHEN("a wrong browser token tries to record a user and to consume it") { - auto const recorded = store.record_user(identifier, "another-browser", "@mallory:example.org", start_ms); + auto const recorded = + store.record_user(identifier, "another-browser", "@mallory:example.org", "stamp", start_ms); auto const consumed = store.consume(identifier, "another-browser", start_ms); THEN("both are refused and the entry is untouched") @@ -136,7 +137,7 @@ SCENARIO("A pending authorisation is stored under a fresh identifier and read ba WHEN("the authenticated user is recorded and the entry is consumed") { - REQUIRE(store.record_user(identifier, browser, "@alice:example.org", start_ms + 10U)); + REQUIRE(store.record_user(identifier, browser, "@alice:example.org", "stamp", start_ms + 10U)); auto const consumed = store.consume(identifier, browser, start_ms + 20U); auto const again = store.consume(identifier, browser, start_ms + 30U); @@ -144,6 +145,7 @@ SCENARIO("A pending authorisation is stored under a fresh identifier and read ba { REQUIRE(consumed.has_value()); CHECK(consumed->user_id == "@alice:example.org"); + CHECK(consumed->credential_stamp == "stamp"); CHECK_FALSE(again.has_value()); CHECK(store.size() == 0U); CHECK(store.live_count_for_client("client-a", start_ms + 30U) == 0U); @@ -193,7 +195,7 @@ SCENARIO("A pending authorisation lives ten minutes from its creation, to the mi WHEN("it is read one millisecond before its end") { - REQUIRE(store.record_user(identifier, browser, "@alice:example.org", end_ms - 2U)); + REQUIRE(store.record_user(identifier, browser, "@alice:example.org", "stamp", end_ms - 2U)); auto const found = store.find(identifier, browser, end_ms - 1U); THEN("it is live, and recording the user did not extend it") From 80344215c785c9283d2d1007514023e41757f335 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:17:57 +0000 Subject: [PATCH 24/42] Delete an OAuth session row with the last credential of its device (ADR-0808) Every path that revokes all of a device's or a user's tokens (a password change with logout_devices, a reset, an account-page change, deactivation, logout/all, device deletion and refresh-token reuse) now deletes the matching oauth_sessions rows in the same transaction, and memory follows only the commit. The retention sweep deletes the row of a device that holds no live access or refresh token, judging it again in the hold that deletes it, before it judges the clients, so a client whose sessions all ended can be evicted or aged out. Amends ADR-0776, ADR-0777 and ADR-0780. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 + ...vice-and-the-token-tables-do-not-change.md | 4 + ...-last-use-is-written-at-most-once-a-day.md | 4 + ...s-are-evicted-least-recently-used-first.md | 3 + ...-with-the-last-credential-of-its-device.md | 73 ++++++++ docs/adr/index.md | 1 + docs/auth-identity.md | 6 +- docs/database-persistence.md | 7 +- docs/security-coding-rules.md | 8 + .../merovingian/database/CredentialTable.hpp | 22 +++ include/merovingian/database/OAuthStore.hpp | 24 +++ include/merovingian/database/OAuthTables.hpp | 3 + .../merovingian/database/PersistentStore.hpp | 10 + src/database/AGENTS.md | 8 +- src/database/OAuthStore.cpp | 92 ++++++++++ src/database/OAuthTables.cpp | 9 + src/database/PersistentStore.cpp | 97 ++++++++++ src/homeserver/AGENTS.md | 2 +- src/homeserver/AuthService.cpp | 25 +-- src/homeserver/RetentionSweep.cpp | 40 +++- tests/integration/test_oauth_token_flow.cpp | 172 ++++++++++++++++++ .../integration/test_retention_sweep_flow.cpp | 69 +++++++ 22 files changed, 664 insertions(+), 17 deletions(-) create mode 100644 docs/adr/0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md diff --git a/CHANGELOG.md b/CHANGELOG.md index cc60424e4..3ca358edc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -85,6 +85,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) the response into a 500 instead of being written or silently dropped (ADR-0767). * A password change, reset or deactivation now ends an OAuth sign-in already past the password, an unredeemed code and an unpolled device approval: they are refused, not granted (ADR-0807). +* An OAuth session's row now goes with the last credential of its device (a password change, reset, deactivation, + refresh-token reuse or expiry), so its client can be evicted or aged out (ADR-0808). ## Bug fixes diff --git a/docs/adr/0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md b/docs/adr/0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md index 7e39dcb4a..6e7fd5ce2 100644 --- a/docs/adr/0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md +++ b/docs/adr/0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md @@ -6,6 +6,10 @@ Technical Story: phase 3 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), proposal P3 +Amended by [ADR-0808](0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md): a session row is also +deleted, in the same transaction, wherever every token of its device is revoked, and by the retention sweep once its +device holds no live token. + ## Context and Problem Statement The OAuth 2.0 API needs to know which devices were created by an OAuth grant, with which client and which scope, so diff --git a/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md b/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md index 83132a063..c61eeb6d0 100644 --- a/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md +++ b/docs/adr/0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md @@ -6,6 +6,10 @@ Technical Story: phase 3 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), the `oauth_clients` retention rule +Amended by [ADR-0808](0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md): the retention sweep +first deletes the session rows whose device holds no live token, so a client whose sessions all ended becomes idle and +ages out here. + ## Context and Problem Statement The retention sweep deletes a client registration that has no session and has not been used for 30 days, and diff --git a/docs/adr/0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md b/docs/adr/0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md index 65b543449..7e8bed1a8 100644 --- a/docs/adr/0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md +++ b/docs/adr/0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md @@ -6,6 +6,9 @@ Technical Story: phase 4 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) +Amended by [ADR-0808](0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md): a client whose sessions +all ended with their devices' credentials has no session row left, so it is idle and may be evicted at the cap. + ## Context and Problem Statement Client registration is unauthenticated. The `auth_sensitive` rate limit bounds one address, but many addresses can diff --git a/docs/adr/0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md b/docs/adr/0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md new file mode 100644 index 000000000..77dae376c --- /dev/null +++ b/docs/adr/0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md @@ -0,0 +1,73 @@ +# An OAuth session row ends with the last credential of its device + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: review finding 2 on `feature/oauth-20-v110`. + +## Context and Problem Statement + +An `oauth_sessions` row (ADR-0776) was deleted only with its device (`delete_device`) or replaced by a new grant or +login on the device (ADR-0792). Several paths end every credential of a device and keep the device: a password +change with `logout_devices`, a reset or account-page change (`replace_password_without_device`), deactivation, +refresh-token reuse detection, and the expiry of the device's tokens. Each left the row behind. A leftover row keeps +its client from ever being idle, so the client is never evicted at the cap (ADR-0780) or removed by retention +(ADR-0777), and the device still counts as an OAuth device to the UIA gate though nothing of the session is live. +What decides when the row goes? + +## Decision Drivers + +* The spec forbids deleting a client registration "that has an active session" (Client-Server API, "Client + registration"); a row whose device holds no live token is not one. +* A row and the tokens it describes must agree after a commit and after a failed commit. +* The sweep keeps the discipline of ADR-0488 and ADR-0489: batches of at most `retention_batch_rows`, at most + `retention_max_batches` per sweep, one hold of `runtime.mutex` per batch. + +## Considered Options + +* Delete the row in the transaction that revokes the tokens, and sweep rows whose device holds no live token. +* Keep the rows and teach the client sweep and the cap to judge a client by its sessions' tokens. + +## Decision Outcome + +Chosen option: delete the row with the tokens, because the row then means what ADR-0776 says it means, and no +reader of it needs to know about tokens. + +* `database::revoke_user_credentials` (all of a user's devices, or all but the caller's) and + `database::revoke_device_tokens` revoke the access and refresh tokens and delete the matching `oauth_sessions` rows + in one transaction; memory changes only after the commit, and a failed commit changes nothing. Logout's + `revoke_device_credentials` adds the row's DELETE to its transaction. `deactivate_user_account`, + `replace_password_without_device`, `change_local_user_password` (with `logout_devices`), `logout_all_local_user`, + `delete_local_device` and the reuse detection of `refresh_local_session` call them. +* The retention sweep's `sweep_oauth_sessions`, run before the client sweep, deletes the row of a device that holds no + access or refresh token that is neither revoked nor expired. Each batch is chosen and deleted in one hold of the lock + and judged again just before the DELETE, so a device granted again between batches keeps its new row. A client whose + last session ended this way is then idle and may go in the same sweep. + +A live access token alone keeps the row, though the finding asked only about refresh tokens: a device holding a +working access token is still an OAuth device, and dropping its row would let it answer UIA with a password. + +### Positive Consequences + +* A client with no live session is evicted at the cap and removed by retention, as ADR-0777 and ADR-0780 intended. +* A device whose credentials all ended is no longer judged an OAuth device by the UIA gate. + +### Negative Consequences + +* The sweep walks every session row once per batch under the lock; the session count is bounded by the users' + device cap. + +## Pros and Cons of the Options + +### Judge clients by their sessions' tokens + +* Bad, because the client sweep, the cap and the UIA gate would each have to read the token tables, and each new + reader of the row would have to remember to. + +## Links + +* Amends [ADR-0776](0776-an-oauth-session-is-a-row-keyed-by-user-and-device-and-the-token-tables-do-not-change.md), + [ADR-0777](0777-an-oauth-client-s-last-use-is-written-at-most-once-a-day.md) and + [ADR-0780](0780-oauth-registrations-are-capped-and-idle-clients-are-evicted-least-recently-used-first.md) +* Follows the batch discipline of [ADR-0488](0488-sessions-are-found-through-a-digest-index-and-unusable-credentials-are-deleted.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index 1c012557e..f975db1a9 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -689,3 +689,4 @@ * [0805 - Device authorisations and user codes are held in memory, capped, and guessing is throttled per address](0805-device-authorisations-and-user-codes-are-held-in-memory-capped-and-guessing-is-throttled-per-address.md) * [0806 - A device sign-in warns first, creates no account, and runs in one browser at a time](0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md) * [0807 - An OAuth sign-in carries the credential stamp of its password check and ends when it changes](0807-an-oauth-sign-in-carries-the-credential-stamp-of-its-password-check-and-ends-when-it-changes.md) +* [0808 - An OAuth session row ends with the last credential of its device](0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 4b0618805..d18e36049 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -1073,7 +1073,11 @@ The built-in OAuth 2.0 API ([ADR-0760](adr/0760-the-oauth-2-0-api-is-built-into- - `oauth_sessions`: one row per OAuth device, keyed by (user ID, device ID), naming its client and granted scope (at most 2048 bytes). A device is an OAuth device exactly when it has a row. The row is written in the transaction that writes the device and its tokens (phase 6), and deleted in the transaction that deletes the device, which covers - `POST /logout`, `POST /logout/all`, `DELETE /devices/{deviceId}` and `POST /delete_devices`. + `POST /logout`, `POST /logout/all`, `DELETE /devices/{deviceId}` and `POST /delete_devices`. It is also deleted with + the tokens wherever every token of its device is revoked and the device kept: a password change with + `logout_devices`, a reset or account-page change, deactivation and refresh-token reuse. The hourly sweep deletes the + row of a device that holds no live access or refresh token, before it judges the clients, so a client whose sessions + all ended is idle and can be evicted or aged out (ADR-0808). Neither table is read by the federation worker. diff --git a/docs/database-persistence.md b/docs/database-persistence.md index b8bc79bbd..f80d85858 100644 --- a/docs/database-persistence.md +++ b/docs/database-persistence.md @@ -65,7 +65,12 @@ value. Test fixtures that do not exercise persistence select it through session row is written in the caller's transaction (`prepare_oauth_session_insert`, then `remember_oauth_session` after the commit) and deleted by `delete_device` in the transaction that deletes the - device. No foreign keys: no v1 table declares one, and the deleting + device. It is also deleted in the transaction that revokes every token of + its device (`revoke_user_credentials`, `revoke_device_tokens`, + `revoke_device_credentials`), and by the retention sweep once its device + holds no access or refresh token that is neither revoked nor expired + ([ADR-0808](adr/0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md)). + No foreign keys: no v1 table declares one, and the deleting transaction removes dependent rows explicitly. - In memory: `PersistentStore::oauth` (`OAuthTables`), hydrated on both backends, with sessions by (user, device), a per-user index, a session diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index dff8d4373..734addff8 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -645,6 +645,14 @@ quickly finding everything a given `AGENTS.md` file contributed. spec forbids deleting a client registration that has an active session (ADR-0776, ADR-0777). Source: `src/database/AGENTS.md`, `src/homeserver/AGENTS.md`. +- **An OAuth session row never outlives every credential of its device.** A path that revokes all of a device's or a + user's tokens calls `revoke_user_credentials`, `revoke_device_tokens` or `revoke_device_credentials`, which delete + the matching `oauth_sessions` rows in the same transaction; the retention sweep deletes a row whose device holds no + live token, judging it again in the hold that deletes it. + Why: a row left behind keeps an ended session's client from being evicted or aged out, and keeps judging a device + with no live credential as an OAuth device at the UIA gate (ADR-0808, CWE-613). + Source: `src/database/AGENTS.md`. + - **A change to a stored event's JSON or status forgets the room in `ResolvedStateMemo`, and a memo hit is still applied through the normal write path.** Why: a resolution reads both, and `current_state` has other writers, so a stale or skipped result leaves state a diff --git a/include/merovingian/database/CredentialTable.hpp b/include/merovingian/database/CredentialTable.hpp index a95f6ee6a..d84da525a 100644 --- a/include/merovingian/database/CredentialTable.hpp +++ b/include/merovingian/database/CredentialTable.hpp @@ -125,6 +125,28 @@ class CredentialTable final return any_unrevoked(positions_of_device(user_id, device_id)); } + // Whether the device holds a row that is neither revoked nor expired at `now` (a row with no expiry never expires). + // Costs the device's own rows, counted in `rows_examined`. + [[nodiscard]] auto has_live_for_device(std::string_view user_id, std::string_view device_id, + std::chrono::system_clock::time_point now) const -> bool + { + auto const* positions = positions_of_device(user_id, device_id); + if (positions == nullptr) + { + return false; + } + for (auto const position : *positions) + { + examined_.add(1U); + auto const& row = rows_[position]; + if (!row.revoked && (!row.expires_at.has_value() || *row.expires_at > now)) + { + return true; + } + } + return false; + } + // Whether the user holds a row that is not revoked. [[nodiscard]] auto has_unrevoked_for_user(std::string_view user_id) const -> bool { diff --git a/include/merovingian/database/OAuthStore.hpp b/include/merovingian/database/OAuthStore.hpp index 32dfb5e81..3e918644b 100644 --- a/include/merovingian/database/OAuthStore.hpp +++ b/include/merovingian/database/OAuthStore.hpp @@ -7,6 +7,7 @@ #include "merovingian/database/PersistentOAuthSession.hpp" #include "merovingian/database/PreparedStatement.hpp" +#include #include #include #include @@ -14,6 +15,7 @@ #include #include #include +#include #include namespace merovingian::database @@ -94,4 +96,26 @@ inline constexpr auto oauth_client_touch_interval_ms = std::uint64_t{24U} * 60U [[nodiscard]] auto delete_oauth_session_of_device_statement(std::string_view user_id, std::string_view device_id) -> PreparedStatement; +// The `oauth_sessions` DELETE for every session of `user_id` but the one of `keep_device_id`, if given, for a +// transaction that revokes the same tokens (ADR-0808). The memory half is `forget_oauth_sessions_of_user`. +[[nodiscard]] auto delete_oauth_sessions_of_user_statement(std::string_view user_id, + std::optional keep_device_id) + -> PreparedStatement; +// Erases from memory what `delete_oauth_sessions_of_user_statement` deleted, after its commit. +auto forget_oauth_sessions_of_user(PersistentStore& store, std::string_view user_id, + std::optional keep_device_id) -> void; + +// At most `max` sessions, as (user_id, device_id), whose device holds no access or refresh token that is neither +// revoked nor expired at `now` (ADR-0808): the session has ended, and the row only keeps its client from eviction. +// Walks every session (counted in the table's `rows_examined`) and each one's own tokens. +[[nodiscard]] auto oauth_sessions_without_live_credentials(PersistentStore const& store, + std::chrono::system_clock::time_point now, std::size_t max) + -> std::vector>; +// Deletes, in one transaction, the sessions of `candidates` that still have no live credential at `now` (a grant +// since they were chosen is kept), then erases them from memory. Returns how many were deleted, or nullopt when the +// commit failed and nothing changed. +[[nodiscard]] auto delete_oauth_sessions_without_live_credentials( + PersistentStore& store, std::span const> candidates, + std::chrono::system_clock::time_point now) -> std::optional; + } // namespace merovingian::database diff --git a/include/merovingian/database/OAuthTables.hpp b/include/merovingian/database/OAuthTables.hpp index 58445ac31..22cde64aa 100644 --- a/include/merovingian/database/OAuthTables.hpp +++ b/include/merovingian/database/OAuthTables.hpp @@ -76,6 +76,9 @@ class OAuthTables final // Every session of `user_id`, in no particular order. Costs the user's own sessions, counted in // `rows_examined`. [[nodiscard]] auto sessions_of_user(std::string_view user_id) const -> std::vector; + // Calls `visit` with (user_id, device_id) of every session, in no particular order. Costs every session, counted + // in `rows_examined`; only the retention sweep calls it (ADR-0808). `visit` must not change the table. + auto for_each_session(std::function const& visit) const -> void; // Adds `session`. False, and nothing changes, when (user, device) already holds one. The client need not be // held (hydration may load the sessions first); a held client named by it stops being idle. diff --git a/include/merovingian/database/PersistentStore.hpp b/include/merovingian/database/PersistentStore.hpp index d9c59ceb2..506eb9f73 100644 --- a/include/merovingian/database/PersistentStore.hpp +++ b/include/merovingian/database/PersistentStore.hpp @@ -805,6 +805,16 @@ auto set_write_connection_limit(PersistentStore& store, std::uint32_t limit) -> // "restore" helper: revocation is one-way by design. Do not add one. [[nodiscard]] auto revoke_tokens_for_user_except_device(PersistentStore& store, std::string_view user_id, std::string_view keep_device_id) -> std::size_t; +// Revokes every access and refresh token of `user_id` (but those of `keep_device_id`, if given) and deletes the +// matching `oauth_sessions` rows, in one transaction; memory changes only after the commit. False when the commit +// failed, and then nothing changed. The path every password change, reset, deactivation and logout of all devices +// takes, so no OAuth session row outlives its device's credentials (ADR-0808). +[[nodiscard]] auto revoke_user_credentials(PersistentStore& store, std::string_view user_id, + std::optional keep_device_id) -> bool; +// Revokes every access and refresh token of the device and deletes its `oauth_sessions` row, in one transaction +// (ADR-0808). False when the commit failed, and then nothing changed. +[[nodiscard]] auto revoke_device_tokens(PersistentStore& store, std::string_view user_id, std::string_view device_id) + -> bool; [[nodiscard]] auto update_device_display_name(PersistentStore& store, std::string_view user_id, std::string_view device_id, std::string_view display_name) -> bool; [[nodiscard]] auto delete_device(PersistentStore& store, std::string_view user_id, std::string_view device_id) -> bool; diff --git a/src/database/AGENTS.md b/src/database/AGENTS.md index b8fe64fd0..dbfc49cf4 100644 --- a/src/database/AGENTS.md +++ b/src/database/AGENTS.md @@ -205,7 +205,13 @@ commits it with the device and tokens, and only then calls `remember_oauth_sessi `delete_oauth_session_of_device_statement` and erases the memory row after the commit. A new device-deleting path does the same. **Whatever replaces a device's credentials replaces its `oauth_sessions` row in the same transaction** (ADR-0792): `store_oauth_grant` deletes the device's earlier tokens and row and inserts the new ones, and -`store_device_and_access_token` (a legacy login) deletes the row, so the device is then a legacy device. The grant's +`store_device_and_access_token` (a legacy login) deletes the row, so the device is then a legacy device. **A row never +outlives every credential of its device** (ADR-0808): `revoke_user_credentials`, `revoke_device_tokens` and +`revoke_device_credentials` delete the matching rows in the transaction that revokes the tokens, and the retention +sweep deletes a row whose device holds no access or refresh token that is neither revoked nor expired +(`oauth_sessions_without_live_credentials`, then `delete_oauth_sessions_without_live_credentials`, which judges each +again). A new path that revokes all of a device's or a user's tokens uses one of those functions, never the +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. diff --git a/src/database/OAuthStore.cpp b/src/database/OAuthStore.cpp index f6a6f4891..48b19d3ac 100644 --- a/src/database/OAuthStore.cpp +++ b/src/database/OAuthStore.cpp @@ -8,8 +8,12 @@ #include "merovingian/database/PersistentStore.hpp" #include +#include +#include +#include #include #include +#include #include #include #include @@ -218,4 +222,92 @@ auto delete_oauth_session_of_device_statement(std::string_view user_id, std::str }; } +auto delete_oauth_sessions_of_user_statement(std::string_view user_id, std::optional keep_device_id) + -> PreparedStatement +{ + if (keep_device_id.has_value()) + { + return { + "delete_oauth_sessions_of_user_except_device", + "DELETE FROM oauth_sessions WHERE user_id = $1 AND device_id <> $2", + {text(user_id), text(*keep_device_id)} + }; + } + return {"delete_oauth_sessions_of_user", "DELETE FROM oauth_sessions WHERE user_id = $1", {text(user_id)}}; +} + +auto forget_oauth_sessions_of_user(PersistentStore& store, std::string_view user_id, + std::optional keep_device_id) -> void +{ + for (auto const& session : store.oauth.sessions_of_user(user_id)) + { + if (!keep_device_id.has_value() || session.device_id != *keep_device_id) + { + std::ignore = store.oauth.erase_session(session.user_id, session.device_id); + } + } +} + +namespace +{ + + // Whether the device still holds a credential that authenticates: an access token or a refresh token that is + // neither revoked nor expired. Either keeps the session active (spec: a client with an active session is never + // deleted), and an access token alone still makes the device an OAuth device to the UIA gate. + [[nodiscard]] auto device_has_live_credential(PersistentStore const& store, std::string_view user_id, + std::string_view device_id, std::chrono::system_clock::time_point now) + -> bool + { + return store.refresh_tokens.has_live_for_device(user_id, device_id, now) || + store.access_tokens.has_live_for_device(user_id, device_id, now); + } + +} // namespace + +auto oauth_sessions_without_live_credentials(PersistentStore const& store, std::chrono::system_clock::time_point now, + std::size_t max) -> std::vector> +{ + auto ended = std::vector>{}; + if (max == 0U) + { + return ended; + } + store.oauth.for_each_session([&](std::string_view user_id, std::string_view device_id) { + if (ended.size() < max && !device_has_live_credential(store, user_id, device_id, now)) + { + ended.emplace_back(std::string{user_id}, std::string{device_id}); + } + }); + return ended; +} + +auto delete_oauth_sessions_without_live_credentials(PersistentStore& store, + std::span const> candidates, + std::chrono::system_clock::time_point now) + -> std::optional +{ + auto statements = std::vector{}; + auto chosen = std::vector>{}; + for (auto const& [user_id, device_id] : candidates) + { + // Judged again in this hold of the lock: a grant since the candidates were chosen replaced the row and its + // tokens, and that session is live. + if (store.oauth.find_session(user_id, device_id) != nullptr && + !device_has_live_credential(store, user_id, device_id, now)) + { + statements.push_back(delete_oauth_session_of_device_statement(user_id, device_id)); + chosen.emplace_back(user_id, device_id); + } + } + if (!commit_persistent_transaction(store, statements)) + { + return std::nullopt; + } + for (auto const& [user_id, device_id] : chosen) + { + std::ignore = store.oauth.erase_session(user_id, device_id); + } + return chosen.size(); +} + } // namespace merovingian::database diff --git a/src/database/OAuthTables.cpp b/src/database/OAuthTables.cpp index 7b3b5daea..f68f7a2da 100644 --- a/src/database/OAuthTables.cpp +++ b/src/database/OAuthTables.cpp @@ -140,6 +140,15 @@ auto OAuthTables::sessions_of_user(std::string_view user_id) const -> std::vecto return rows; } +auto OAuthTables::for_each_session(std::function const& visit) const -> void +{ + for (auto const& [key, session] : sessions_) + { + visit(session.user_id, session.device_id); + } + rows_examined_.add(sessions_.size()); +} + auto OAuthTables::insert_session(PersistentOAuthSession session) -> bool { auto key = session_key(session.user_id, session.device_id); diff --git a/src/database/PersistentStore.cpp b/src/database/PersistentStore.cpp index 46459dd10..795ffad6b 100644 --- a/src/database/PersistentStore.cpp +++ b/src/database/PersistentStore.cpp @@ -1773,6 +1773,8 @@ auto has_room_membership_row(PersistentStore const& store, std::string_view room {std::string{user_id}, false}, {std::string{device_id}, false} })); + // No credential of the device is left, so its OAuth session row goes in the same transaction (ADR-0808). + statements.push_back(delete_oauth_session_of_device_statement(user_id, device_id)); if (!commit_persistent_transaction(store, statements)) { return false; @@ -1780,6 +1782,7 @@ auto has_room_membership_row(PersistentStore const& store, std::string_view room std::ignore = store.access_tokens.revoke_hash(access_token_hash); std::ignore = store.access_tokens.revoke_for_device(user_id, device_id); std::ignore = store.refresh_tokens.revoke_for_device(user_id, device_id); + std::ignore = store.oauth.erase_session(user_id, device_id); return true; } @@ -2399,6 +2402,100 @@ namespace return revoked; } +// ADR-0808: an `oauth_sessions` row never outlives every credential of its device, so ending all of a device's or a +// user's tokens deletes the matching rows in the same transaction, and memory follows only the commit. +[[nodiscard]] auto revoke_user_credentials(PersistentStore& store, std::string_view user_id, + std::optional keep_device_id) -> bool +{ + auto statements = std::vector{}; + if (keep_device_id.has_value()) + { + statements.push_back(record_statement( + "revoke_user_access_tokens_except_device", + "UPDATE access_tokens SET revoked = $1 WHERE user_id = $2 AND " + "device_id <> $3", + { + {"true", false}, + {std::string{user_id}, false}, + {std::string{*keep_device_id}, false} + })); + statements.push_back(record_statement( + "revoke_user_refresh_tokens_except_device", + "UPDATE refresh_tokens SET revoked = $1 WHERE user_id = $2 AND " + "device_id <> $3", + { + {"true", false}, + {std::string{user_id}, false}, + {std::string{*keep_device_id}, false} + })); + } + else + { + statements.push_back(record_statement("revoke_user_access_tokens", + "UPDATE access_tokens SET revoked = $1 WHERE user_id = $2", + { + {"true", false}, + {std::string{user_id}, false} + })); + statements.push_back(record_statement("revoke_user_refresh_tokens", + "UPDATE refresh_tokens SET revoked = $1 WHERE user_id = $2", + { + {"true", false}, + {std::string{user_id}, false} + })); + } + statements.push_back(delete_oauth_sessions_of_user_statement(user_id, keep_device_id)); + if (!commit_persistent_transaction(store, statements)) + { + return false; + } + if (keep_device_id.has_value()) + { + std::ignore = store.access_tokens.revoke_for_user_except_device(user_id, *keep_device_id); + std::ignore = store.refresh_tokens.revoke_for_user_except_device(user_id, *keep_device_id); + } + else + { + std::ignore = store.access_tokens.revoke_for_user(user_id); + std::ignore = store.refresh_tokens.revoke_for_user(user_id); + } + forget_oauth_sessions_of_user(store, user_id, keep_device_id); + return true; +} + +[[nodiscard]] auto revoke_device_tokens(PersistentStore& store, std::string_view user_id, std::string_view device_id) + -> bool +{ + auto statements = std::vector{}; + statements.push_back( + record_statement("revoke_device_access_tokens", + "UPDATE access_tokens SET revoked = $1 WHERE user_id = $2 AND " + "device_id = $3", + { + {"true", false}, + {std::string{user_id}, false}, + {std::string{device_id}, false} + })); + statements.push_back( + record_statement("revoke_device_refresh_tokens", + "UPDATE refresh_tokens SET revoked = $1 WHERE user_id = $2 AND " + "device_id = $3", + { + {"true", false}, + {std::string{user_id}, false}, + {std::string{device_id}, false} + })); + statements.push_back(delete_oauth_session_of_device_statement(user_id, device_id)); + if (!commit_persistent_transaction(store, statements)) + { + return false; + } + std::ignore = store.access_tokens.revoke_for_device(user_id, device_id); + std::ignore = store.refresh_tokens.revoke_for_device(user_id, device_id); + std::ignore = store.oauth.erase_session(user_id, device_id); + return true; +} + [[nodiscard]] auto update_device_display_name(PersistentStore& store, std::string_view user_id, std::string_view device_id, std::string_view display_name) -> bool { diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 1543bf6e5..3709e9099 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -26,7 +26,7 @@ This is the largest and most complex module — read this file carefully before | `RoomService.cpp` | Room operations, event persistence, signing-key lifecycle, appservice and push delivery | | `AppserviceDelivery.cpp` | Application Service API outbound queue (ADR-0163): `enqueue_appservice_delivery` (request path, no network) and `drain_appservice_queues` (the one drainer thread, run by a `PeriodicJob` from `main.cpp`) | | `ClientTxnPrune.cpp` | `prune_client_transactions`: the sweep the `client-txn-prune` `PeriodicJob` runs every hour, deleting to-device `client_txn_ids` records older than 7 days (F-54, ADR-0381) | -| `RetentionSweep.cpp` | `run_retention_sweep`: the sweep the `retention-sweep` `PeriodicJob` runs every hour. Deletes sessions and tokens that can no longer authenticate and `audit_log` rows past `security.audit_log_retention_days`, and OAuth 2.0 clients with no session unused for 30 days (`oauth_client_retention`, least recently used first; never a client with a session, nor one `oauth_client_has_pending_authorisation` names: a live pending authorisation or an unredeemed code, answered in O(1) from the stores; ADR-0777, ADR-0782), in transactions of at most 500 rows (`retention_batch_rows`), at most 20 batches per kind per sweep. `runtime.mutex` is taken for one batch at a time, never across the whole sweep (ADR-0488, ADR-0489) | +| `RetentionSweep.cpp` | `run_retention_sweep`: the sweep the `retention-sweep` `PeriodicJob` runs every hour. Deletes sessions and tokens that can no longer authenticate and `audit_log` rows past `security.audit_log_retention_days`, OAuth 2.0 session rows whose device holds no live access or refresh token (judged again in the hold that deletes them, ADR-0808), and OAuth 2.0 clients with no session unused for 30 days (`oauth_client_retention`, least recently used first; never a client with a session, nor one `oauth_client_has_pending_authorisation` names: a live pending authorisation or an unredeemed code, answered in O(1) from the stores; ADR-0777, ADR-0782), in transactions of at most 500 rows (`retention_batch_rows`), at most 20 batches per kind per sweep. `runtime.mutex` is taken for one batch at a time, never across the whole sweep (ADR-0488, ADR-0489) | | `OAuthClientRegistration.cpp` | `POST /_merovingian/oauth2/register` (`register_oauth_client`), the client ID (`oauth_client_id_of`, ADR-0779), the cap and its eviction (ADR-0780), and `find_registered_oauth_client` | | `OAuthJsonResponse.cpp` | `oauth_json_response` / `oauth_error_response` / `oauth_empty_response`: every OAuth JSON (or empty) answer, with `no-store` (ADR-0781) | | `OAuthTokenEndpoint.cpp` | `POST /_merovingian/oauth2/token` (`handle_oauth_token`): the authorization code grant, the refresh grant (ADR-0791 to ADR-0793) and the device code grant (ADR-0804) | diff --git a/src/homeserver/AuthService.cpp b/src/homeserver/AuthService.cpp index 992e1e5b6..f1938aa71 100644 --- a/src/homeserver/AuthService.cpp +++ b/src/homeserver/AuthService.cpp @@ -1870,8 +1870,8 @@ auto refresh_local_session(HomeserverRuntime& runtime, std::string_view refresh_ // a password change, so presenting one ends the device's session. if (refresh->revoked) { - std::ignore = database::revoke_access_tokens_for_device(runtime.database.persistent_store, user_id, device_id); - std::ignore = database::revoke_refresh_tokens_for_device(runtime.database.persistent_store, user_id, device_id); + // With the device's OAuth session row, in one transaction (ADR-0808). + std::ignore = database::revoke_device_tokens(runtime.database.persistent_store, user_id, device_id); if (!device_tokens_are_revoked(runtime.database.persistent_store, user_id, device_id)) { append_local_audit(runtime.database, observability::AuditCategory::auth, "auth.refresh.reuse_detected", @@ -2376,8 +2376,8 @@ auto logout_all_local_user(HomeserverRuntime& runtime, std::string_view access_t { return make_operation_result(false, {}, "unauthenticated", 401U); } - std::ignore = database::revoke_access_tokens_for_user(runtime.database.persistent_store, session->user_id); - std::ignore = database::revoke_refresh_tokens_for_user(runtime.database.persistent_store, session->user_id); + // With the user's OAuth session rows, in one transaction (ADR-0808). + std::ignore = database::revoke_user_credentials(runtime.database.persistent_store, session->user_id, std::nullopt); if (!user_tokens_are_revoked(runtime.database.persistent_store, session->user_id)) { return make_operation_result(false, {}, "session revocation persistence failed", 500U); @@ -2532,8 +2532,8 @@ auto deactivate_user_account(HomeserverRuntime& runtime, std::string_view user_i // What must not pass is a persistence failure, which store_* surfaces by // leaving the row unchanged; both calls are re-checked below against the // store to make the outcome, not the return count, the thing that decides. - std::ignore = database::revoke_access_tokens_for_user(runtime.database.persistent_store, user_id); - std::ignore = database::revoke_refresh_tokens_for_user(runtime.database.persistent_store, user_id); + // With the user's OAuth session rows, in one transaction (ADR-0808). + std::ignore = database::revoke_user_credentials(runtime.database.persistent_store, user_id, std::nullopt); if (!user_tokens_are_revoked(runtime.database.persistent_store, user_id)) { return make_operation_result(false, {}, "token revocation failed during deactivation", 500U); @@ -2645,8 +2645,8 @@ auto delete_local_device(HomeserverRuntime& runtime, std::string_view user_id, s // Revoke only when a token is still live, so a repeated delete of a gone device writes nothing. if (!device_tokens_are_revoked(runtime.database.persistent_store, user_id, device_id)) { - std::ignore = database::revoke_access_tokens_for_device(runtime.database.persistent_store, user_id, device_id); - std::ignore = database::revoke_refresh_tokens_for_device(runtime.database.persistent_store, user_id, device_id); + // With the device's OAuth session row, in one transaction (ADR-0808). + std::ignore = database::revoke_device_tokens(runtime.database.persistent_store, user_id, device_id); if (!device_tokens_are_revoked(runtime.database.persistent_store, user_id, device_id)) { return make_operation_result(false, {}, "token revocation persistence failed", 500U); @@ -2752,8 +2752,9 @@ auto change_local_user_password(HomeserverRuntime& runtime, std::string_view acc // password change is the action a user takes *after* a compromise, and it // was handing the attacker's revoked token back. This call never touches // the caller's device, so no revoked credential is ever reinstated. - std::ignore = database::revoke_tokens_for_user_except_device(runtime.database.persistent_store, user_id, - session->device_id); + // With the other devices' OAuth session rows, in one transaction (ADR-0808). + std::ignore = database::revoke_user_credentials(runtime.database.persistent_store, user_id, + std::string_view{session->device_id}); if (!user_tokens_except_device_are_revoked(runtime.database.persistent_store, user_id, session->device_id)) { return make_operation_result(false, {}, "token revocation persistence failed", 500U); @@ -2852,8 +2853,8 @@ namespace { // Spec (POST /account/password): with logout_devices the server revokes the access tokens of all the // user's devices; there is no device to keep, so none is spared. - std::ignore = database::revoke_access_tokens_for_user(runtime.database.persistent_store, user_id); - std::ignore = database::revoke_refresh_tokens_for_user(runtime.database.persistent_store, user_id); + // With the user's OAuth session rows, in one transaction (ADR-0808). + std::ignore = database::revoke_user_credentials(runtime.database.persistent_store, user_id, std::nullopt); if (!user_tokens_are_revoked(runtime.database.persistent_store, user_id) || !database::revoke_openid_tokens_for_user(runtime.database.persistent_store, user_id)) { diff --git a/src/homeserver/RetentionSweep.cpp b/src/homeserver/RetentionSweep.cpp index 3719e639a..81b69198a 100644 --- a/src/homeserver/RetentionSweep.cpp +++ b/src/homeserver/RetentionSweep.cpp @@ -179,6 +179,42 @@ namespace return done; } + // Returns true when every OAuth session row whose device holds no live credential was deleted (or there was none), + // false when the sweep stopped at its batch cap or was asked to stop (ADR-0808). Each batch is chosen and deleted + // in one hold of the lock, so a grant between batches is seen: a re-granted device holds live tokens again. + [[nodiscard]] auto sweep_oauth_sessions(HomeserverRuntime& runtime, std::chrono::system_clock::time_point now, + StopFlag const& stop) -> bool + { + auto batches = std::size_t{0U}; + auto deleted = std::size_t{0U}; + auto done = false; + while (batches < retention_max_batches && !stop.stop_requested()) + { + auto const guard = RuntimeLock{runtime.mutex}; + auto const ended = database::oauth_sessions_without_live_credentials(runtime.database.persistent_store, now, + retention_batch_rows); + if (ended.empty()) + { + done = true; + break; + } + auto const removed = + database::delete_oauth_sessions_without_live_credentials(runtime.database.persistent_store, ended, now); + if (!removed.has_value()) + { + LOG_WARNING("Retention sweep could not delete a batch of ended OAuth 2.0 sessions; will retry"); + return true; + } + deleted += *removed; + ++batches; + } + if (deleted != 0U) + { + LOG_INFO("Retention sweep deleted ended OAuth 2.0 sessions; sessions=" + std::to_string(deleted)); + } + return done; + } + // Returns true when every expired sessionless client was deleted (or there was none), false when the sweep // stopped at its batch cap or was asked to stop. Each batch is chosen and deleted in one hold of the lock, so a // session granted between batches is seen by the next choice: delete_oauth_clients refuses a client with one. @@ -242,8 +278,10 @@ auto run_retention_sweep(HomeserverRuntime& runtime, std::chrono::system_clock:: { auto const credentials_done = sweep_credentials(runtime, now, stop); auto const audit_done = sweep_audit_log(runtime, now, stop); + // Before the clients, so a client whose only session ended this way may go in the same sweep. + auto const sessions_done = sweep_oauth_sessions(runtime, now, stop); auto const oauth_done = sweep_oauth_clients(runtime, now, stop); - if (credentials_done && audit_done && oauth_done) + if (credentials_done && audit_done && sessions_done && oauth_done) { return std::chrono::duration_cast(retention_sweep_interval); } diff --git a/tests/integration/test_oauth_token_flow.cpp b/tests/integration/test_oauth_token_flow.cpp index 100819bb8..38539355d 100644 --- a/tests/integration/test_oauth_token_flow.cpp +++ b/tests/integration/test_oauth_token_flow.cpp @@ -17,6 +17,7 @@ #include "merovingian/database/OAuthStore.hpp" #include "merovingian/database/PersistentOAuthSession.hpp" #include "merovingian/database/PersistentStore.hpp" +#include "merovingian/database/PersistentStoreBackend.hpp" #include "merovingian/homeserver/AuthService.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" @@ -30,6 +31,7 @@ #include #include #include +#include #include #include #include @@ -940,3 +942,173 @@ SCENARIO("A password change ends a sign-in waiting for approval and a code not y } } } + +namespace +{ + +[[nodiscard]] auto signed_in_client(hs::ClientServerRuntime& rt, std::string_view client_id) -> OAuthTokenAnswer +{ + auto answer = oauth_sign_in(rt, client_id, "alice", alice_password); + REQUIRE(answer.ok); + REQUIRE(oauth_row(rt, oauth_test_device) != nullptr); + return answer; +} + +[[nodiscard]] auto password_auth() -> std::string +{ + return R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":"@alice:example.org"},"password":")" + + std::string{alice_password} + R"("})"; +} + +} // namespace + +SCENARIO("Ending every credential of a device deletes its OAuth session row with them", + "[integration][oauth][oauth-token][oauth-session-end][security]") +{ + GIVEN("alice with an OAuth session on OAUTHDEV01 and a legacy session on PWDEVICE") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const answer = signed_in_client(rt, fixture.client_id); + auto const legacy = legacy_login(rt, "PWDEVICE"); + REQUIRE(legacy.status == 200U); + auto const legacy_token = member(legacy, "access_token"); + + WHEN("she changes her password with POST /account/password and logout_devices") + { + auto const changed = + send(rt, "POST", "/_matrix/client/v3/account/password", legacy_token, + R"({"auth":)" + password_auth() + R"(,"new_password":"NewAlicePass42!y","logout_devices":true})"); + + THEN("the OAuth device's tokens and its session row are gone, and the caller's device keeps working") + { + REQUIRE(changed.status == 200U); + CHECK(whoami_status(rt, answer.access_token) == 401U); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + CHECK_FALSE(db::oauth_client_has_session(rt.homeserver.database.persistent_store, fixture.client_id)); + CHECK(whoami_status(rt, legacy_token) == 200U); + } + } + + WHEN("she changes her password on the account page") + { + REQUIRE(hs::change_password_on_account_page(rt.homeserver, alice_id, "NewAlicePass42!y").ok); + + THEN("the tokens and the session row are gone") + { + CHECK(whoami_status(rt, answer.access_token) == 401U); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + } + } + + WHEN("her password is reset by email with every device signed out") + { + REQUIRE(hs::reset_local_user_password(rt.homeserver, alice_id, "NewAlicePass42!y", true).ok); + + THEN("the tokens and the session row are gone") + { + CHECK(whoami_status(rt, answer.access_token) == 401U); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + } + } + + WHEN("her password is reset by email keeping her devices") + { + REQUIRE(hs::reset_local_user_password(rt.homeserver, alice_id, "NewAlicePass42!y", false).ok); + + THEN("the OAuth session keeps its tokens and its row") + { + CHECK(whoami_status(rt, answer.access_token) == 200U); + CHECK(oauth_row(rt, oauth_test_device) != nullptr); + } + } + + WHEN("she deactivates her account") + { + auto const deactivated = send(rt, "POST", "/_matrix/client/v3/account/deactivate", legacy_token, + R"({"auth":)" + password_auth() + "}"); + + THEN("the tokens and the session row are gone") + { + REQUIRE(deactivated.status == 200U); + CHECK(whoami_status(rt, answer.access_token) == 401U); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + } + } + + WHEN("the client refreshes, and the spent refresh token is presented again") + { + auto const refreshed = read_token_answer( + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(fixture.client_id, answer.refresh_token))); + REQUIRE(refreshed.ok); + REQUIRE(whoami_status(rt, refreshed.access_token) == 200U); + auto const reused = + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(fixture.client_id, answer.refresh_token)); + + THEN("reuse ends the session: its tokens and its row are gone, and the device is no OAuth device") + { + CHECK(oauth_error(reused) == "invalid_grant"); + CHECK(whoami_status(rt, refreshed.access_token) == 401U); + CHECK(oauth_row(rt, oauth_test_device) == nullptr); + } + } + + WHEN("the store cannot commit while the user's and the device's credentials are ended") + { + auto& store = rt.homeserver.database.persistent_store; + auto const backend = store.backend; + store.backend = db::PersistentStoreBackend::sqlite; + store.sqlite_path.clear(); + auto const user_ended = db::revoke_user_credentials(store, alice_id, std::nullopt); + auto const device_ended = db::revoke_device_tokens(store, alice_id, oauth_test_device); + store.backend = backend; + + THEN("both fail, and the tokens and the session row are all still there") + { + CHECK_FALSE(user_ended); + CHECK_FALSE(device_ended); + CHECK(oauth_row(rt, oauth_test_device) != nullptr); + CHECK(whoami_status(rt, answer.access_token) == 200U); + CHECK(whoami_status(rt, legacy_token) == 200U); + } + } + } +} + +SCENARIO("A client whose only session ended with its credentials is evicted at the registration cap", + "[integration][oauth][oauth-token][oauth-session-end][cap]") +{ + GIVEN("alice signed in to Test App, at a cap of one client") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + std::ignore = signed_in_client(rt, fixture.client_id); + rt.limits.max_oauth_clients = 1U; + auto const other_client = std::string{ + R"({"client_uri":"https://other.example.com/","redirect_uris":[)" + R"("https://other.example.com/cb"],"token_endpoint_auth_method":"none","client_name":"Other"})"}; + + WHEN("her password is changed on the account page, then another client registers") + { + REQUIRE(hs::change_password_on_account_page(rt.homeserver, alice_id, "NewAlicePass42!y").ok); + auto const registered = post_client_registration(rt, other_client); + + THEN("the ended session no longer protects Test App, which is evicted") + { + CHECK(registered.status == 201U); + CHECK(db::find_oauth_client(rt.homeserver.database.persistent_store, fixture.client_id) == nullptr); + } + } + + WHEN("another client registers while her session is live") + { + auto const refused = post_client_registration(rt, other_client); + + THEN("Test App is kept and the new client refused") + { + CHECK(refused.status == 503U); + CHECK(db::find_oauth_client(rt.homeserver.database.persistent_store, fixture.client_id) != nullptr); + } + } + } +} diff --git a/tests/integration/test_retention_sweep_flow.cpp b/tests/integration/test_retention_sweep_flow.cpp index 831f69d8f..1e4e191d8 100644 --- a/tests/integration/test_retention_sweep_flow.cpp +++ b/tests/integration/test_retention_sweep_flow.cpp @@ -547,3 +547,72 @@ SCENARIO("Every way a device is deleted deletes its OAuth session row", "[integr } } } + +SCENARIO("The retention sweep deletes an OAuth session row once its device holds no live token", + "[integration][sqlite][retention][oauth][oauth-session-end]") +{ + GIVEN("two clients unused for 31 days, one session whose refresh token expires in an hour, one in 90 days") + { + REQUIRE(sodium_init() >= 0); + auto database = TemporarySqliteDatabase{}; + auto started = merovingian::homeserver::start_runtime(sqlite_config(database.path(), 365U)); + REQUIRE(started.started); + auto& runtime = started.runtime; + auto& persistent = runtime.database.persistent_store; + auto const registration = merovingian::homeserver::register_local_user( + runtime, "alice", "CorrectHorse7!Battery", merovingian::tests::registration_token); + REQUIRE(registration.ok); + auto const user_id = std::string{registration.value}; + auto const now = std::chrono::system_clock::now(); + auto const day = std::chrono::hours{24}; + auto const add_session = [&](std::string const& device, std::string const& client, + std::chrono::system_clock::time_point refresh_expires_at) { + REQUIRE(merovingian::database::store_oauth_client(persistent, oauth_client_at(client, now - (31 * day))) == + merovingian::database::OAuthClientStoreResult::inserted); + REQUIRE(merovingian::database::store_oauth_session(persistent, oauth_session_of(user_id, device, client))); + REQUIRE(merovingian::database::store_access_token( + persistent, {user_id, device, "token-hash:v4:access-" + device, false, now + std::chrono::minutes{5}})); + REQUIRE(merovingian::database::store_refresh_token( + persistent, {user_id, device, "token-hash:v4:refresh-" + device, false, refresh_expires_at})); + }; + add_session("DEVENDING", "client-ending", now + std::chrono::hours{1}); + add_session("DEVLIVE", "client-live", now + (90 * day)); + auto const session_rows = [&database](std::string const& device) { + return durable_row_count(database.path(), "oauth_sessions", "device_id = '" + device + "'"); + }; + + WHEN("the sweep runs while both refresh tokens are live") + { + std::ignore = merovingian::homeserver::run_retention_sweep(runtime, now, never_stopped); + + THEN("both sessions and both clients are kept") + { + REQUIRE(session_rows("DEVENDING") == 1); + REQUIRE(session_rows("DEVLIVE") == 1); + REQUIRE(merovingian::database::find_oauth_client(persistent, "client-ending") != nullptr); + REQUIRE(merovingian::database::find_oauth_client(persistent, "client-live") != nullptr); + } + } + + WHEN("the sweep runs two hours later, when one refresh token has expired") + { + std::ignore = + merovingian::homeserver::run_retention_sweep(runtime, now + std::chrono::hours{2}, never_stopped); + + THEN("that session's row goes, from the database and from memory, and its client goes with it") + { + REQUIRE(session_rows("DEVENDING") == 0); + REQUIRE(merovingian::database::find_oauth_session(persistent, user_id, "DEVENDING") == nullptr); + REQUIRE(durable_row_count(database.path(), "oauth_clients", "client_id = 'client-ending'") == 0); + REQUIRE(merovingian::database::find_oauth_client(persistent, "client-ending") == nullptr); + } + + THEN("the session whose refresh token is live, and its client, are kept") + { + REQUIRE(session_rows("DEVLIVE") == 1); + REQUIRE(merovingian::database::find_oauth_session(persistent, user_id, "DEVLIVE") != nullptr); + REQUIRE(merovingian::database::find_oauth_client(persistent, "client-live") != nullptr); + } + } + } +} From 4079b7a83a053fde044d59678e61bf3eea4ee02c Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:19:01 +0000 Subject: [PATCH 25/42] Bind a cross-signing reset approval to the OAuth device that asked (ADR-0809) The m.oauth challenge URL now carries the requesting device's device_id, which the spec lets a Matrix-specific account management action take. When it names one of the signed-in user's own OAuth devices, the reset page names the device and its client, and the approval it gives is bound: only that device's upload takes it, and a restored approval stays bound. Any other device_id is ignored and never shown, and the approval is unbound as before. A posted device that is no longer one of the user's OAuth devices is refused with nothing approved. Amends ADR-0797 and ADR-0799. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 + ...he-m-oauth-stage-and-a-one-use-approval.md | 4 + ...sion-and-reuses-the-user-s-live-session.md | 3 + ...d-to-the-oauth-device-that-asked-for-it.md | 60 ++++++++ docs/adr/index.md | 1 + docs/auth-identity.md | 7 + docs/security-coding-rules.md | 9 +- .../homeserver/CrossSigningResetApprovals.hpp | 30 +++- include/merovingian/oauth/AccountPages.hpp | 10 +- src/homeserver/AGENTS.md | 5 +- src/homeserver/AccountPage.cpp | 57 +++++-- src/homeserver/ClientServerRuntime.cpp | 46 +++--- src/homeserver/CrossSigningResetApprovals.cpp | 36 ++++- src/oauth/AccountPages.cpp | 25 ++- ...t_oauth_account_management_conformance.cpp | 7 +- .../test_oauth_account_pages_flow.cpp | 142 +++++++++++++++++- tests/unit/test_oauth_account_pages.cpp | 4 +- ...st_oauth_cross_signing_reset_approvals.cpp | 99 +++++++++--- 18 files changed, 466 insertions(+), 81 deletions(-) create mode 100644 docs/adr/0809-a-cross-signing-reset-approval-is-bound-to-the-oauth-device-that-asked-for-it.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ca358edc..f4437ccf8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -87,6 +87,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) and an unpolled device approval: they are refused, not granted (ADR-0807). * An OAuth session's row now goes with the last credential of its device (a password change, reset, deactivation, refresh-token reuse or expiry), so its client can be evicted or aged out (ADR-0808). +* A cross-signing reset approved on a page that named the asking OAuth device can be used only by that device; the + `m.oauth` URL now carries `device_id` (ADR-0809). ## Bug fixes diff --git a/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md b/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md index 270b6783d..5842f4929 100644 --- a/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md +++ b/docs/adr/0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md @@ -13,6 +13,10 @@ Amended by [ADR-0799](0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-s reuses the user's live session and offers `org.matrix.cross_signing_reset` as a second flow. The decision below is otherwise unchanged. +Amended by [ADR-0809](0809-a-cross-signing-reset-approval-is-bound-to-the-oauth-device-that-asked-for-it.md) (2026-11-16): the +challenge URL carries the requesting device, and an approval given on a page that named one of the user's OAuth devices +is spent only by that device's upload. + ## Context and Problem Statement ADR-0794 refused every UIA endpoint to an OAuth session with 403 until the account pages existed. The spec's diff --git a/docs/adr/0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md b/docs/adr/0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md index ac0e34dfb..64e6bab8d 100644 --- a/docs/adr/0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md +++ b/docs/adr/0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md @@ -7,6 +7,9 @@ Technical Story: phase 9 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md), part 0. Amends [ADR-0797](0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md). +Amended by [ADR-0809](0809-a-cross-signing-reset-approval-is-bound-to-the-oauth-device-that-asked-for-it.md) (2026-11-16): a +retry without a session completes the stage only with an approval that is unbound or bound to the retrying device. + ## Context and Problem Statement ADR-0797 completed the `m.oauth` stage of a replacing `POST /keys/device_signing/upload` only when the retry carried an diff --git a/docs/adr/0809-a-cross-signing-reset-approval-is-bound-to-the-oauth-device-that-asked-for-it.md b/docs/adr/0809-a-cross-signing-reset-approval-is-bound-to-the-oauth-device-that-asked-for-it.md new file mode 100644 index 000000000..0fc18cadb --- /dev/null +++ b/docs/adr/0809-a-cross-signing-reset-approval-is-bound-to-the-oauth-device-that-asked-for-it.md @@ -0,0 +1,60 @@ +# A cross-signing reset approval is bound to the OAuth device that asked for it + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: review finding 3 on `feature/oauth-20-v110`. Amends +[ADR-0797](0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md) +and [ADR-0799](0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md). + +## Context and Problem Statement + +The approval the account page grants for `org.matrix.cross_signing_reset` (ADR-0797) is a per-user flag, and +ADR-0799 lets a replacing upload complete the `m.oauth` stage without naming a UIA session. Any of the user's OAuth +sessions can therefore spend it: a client the user forgot about, or one whose token was stolen, that keeps polling a +replacing upload replaces the user's cross-signing identity the moment the user approves a reset another client asked +for. The page cannot tell the user which device will use it. How is an approval tied to the device the user meant? + +## Decision Drivers + +* The spec's account management URL "MAY accept" `device_id`, "For Matrix-specific actions, the user's device ID. + Actions which don't support the device ID will ignore it" (Client-Server API, "Account management URL parameters"). + `org.matrix.cross_signing_reset` is a Matrix-specific action, so the parameter may be carried on it; nothing requires + a server to use it. +* A client that opens the URL without `device_id` (hand-built, or an older server's URL) must keep working. +* The page must never show a device the user does not hold, or confirm that another user's device exists. + +## Considered Options + +* Carry the requesting device in the challenge URL and bind the approval to it when the page can show it. +* Bind the approval to the UIA session the challenge issued. +* Keep the per-user flag. + +## Decision Outcome + +Chosen option: carry the device. The `m.oauth` challenge URL is `account_action_address(..., device_id)` with the +requesting device. When the reset page gets a `device_id` that names one of the signed-in user's own devices holding an +`oauth_sessions` row, it names the device and its client and carries the ID in its form; the approval is then bound +(`CrossSigningResetApprovals::approve(user, device, now)`) and `take(user, device, now)` gives it only to that device's +upload, which also restores it bound. Any other `device_id` (another user's, a legacy device, an unknown one, a +malformed one) is ignored and never shown: the page is the unbound one, which says in plain words that any application +signed in with OAuth can use the permission, and its approval behaves as before. A posted `device_id` that is no +longer one of the user's OAuth devices is refused with nothing approved, never widened into an unbound approval. + +Binding to the UIA session was rejected because ADR-0799 accepts a retry with no session (clients poll that way), and +a session ID is not shown to the user anyway. + +### Positive Consequences + +* An approval given on the page a client opened can be spent by that client's device only. +* The user sees which device and which application the permission is for. + +### Negative Consequences + +* An approval the user gave on the unbound page is still usable by any of the user's OAuth sessions. + +## Links + +* Amends [ADR-0797](0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md) + and [ADR-0799](0799-the-m-oauth-stage-accepts-a-polling-retry-without-a-session-and-reuses-the-user-s-live-session.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index f975db1a9..a0378a7ce 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -690,3 +690,4 @@ * [0806 - A device sign-in warns first, creates no account, and runs in one browser at a time](0806-a-device-sign-in-warns-first-creates-no-account-and-runs-in-one-browser-at-a-time.md) * [0807 - An OAuth sign-in carries the credential stamp of its password check and ends when it changes](0807-an-oauth-sign-in-carries-the-credential-stamp-of-its-password-check-and-ends-when-it-changes.md) * [0808 - An OAuth session row ends with the last credential of its device](0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md) +* [0809 - A cross-signing reset approval is bound to the OAuth device that asked for it](0809-a-cross-signing-reset-approval-is-bound-to-the-oauth-device-that-asked-for-it.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index d18e36049..329ca56e1 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -1263,6 +1263,13 @@ the spec's "Account management" names: `account_management_uri` and all six `org are stored, and a stored upload audits `cross_signing.reset_used`. A `session` this server did not issue for this, and a password stage, get the challenge; a password from an OAuth session is never checked; a legacy session keeps `m.login.password` and never touches an approval. +- **The device that asked (ADR-0809).** The challenge URL also carries `&device_id=` with the requesting device (the + spec lets a Matrix-specific action take it). When that names one of the signed-in user's own OAuth devices, the reset + page names the device and its client and its form carries the ID: the approval is bound, and only that device's + upload takes it (another device's poll gets the challenge and leaves it). Any other `device_id` is ignored and never + shown; the page then says that any application signed in through this server's sign-in page can use the permission, + and the approval is unbound as before. A posted `device_id` that is no longer one of the user's OAuth devices is a + 400 page with nothing approved. - **Logging.** Under `oauth`, `account.page.*` events with `user_id` only. Never a password, a cookie, a form token or the query (`sanitized_http_target` drops it, ADR-0786). diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index 734addff8..6020c044e 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1104,12 +1104,15 @@ quickly finding everything a given `AGENTS.md` file contributed. - **An account-page form is accepted only with this server's `Origin`, the `__Host-mv-account` session and that session's form token (constant time); each page action calls the client API's own function; every password change, reset and deactivation ends the user's account-page sessions and reset approvals; a cross-signing reset approval is - spent only by a stored upload and is never usable by a password session or with a password stage; the `m.oauth` - challenge reuses the user's live UIA session, so a polling client costs one session.** + spent only by a stored upload and is never usable by a password session or with a password stage; an approval given + on a page that named the requesting OAuth device is spent only by that device, and a `device_id` that is not one of + the user's OAuth devices is never shown or bound; the `m.oauth` challenge reuses the user's live UIA session, so a + polling client costs one session.** Why: a forged post signs out a device or deactivates an account (CWE-352); one session's token must not act for another; a copied action drifts and misses a revocation step (CWE-613); a page session or approval that outlives a password change keeps a stolen credential's reach (CWE-613); a token alone must not replace a user's cross-signing - identity (CWE-306); a session issued per poll fills the user's UIA pool (CWE-770) (ADR-0796 to ADR-0799). + identity (CWE-306); another of the user's OAuth sessions must not spend an approval given for the device that asked + (CWE-863); a session issued per poll fills the user's UIA pool (CWE-770) (ADR-0796 to ADR-0799, ADR-0809). Source: `src/homeserver/AGENTS.md`. - **With `server.oauth.legacy_api_enabled=false` no legacy route issues a user a new session or lists the legacy diff --git a/include/merovingian/homeserver/CrossSigningResetApprovals.hpp b/include/merovingian/homeserver/CrossSigningResetApprovals.hpp index 536fdfd08..52a629a79 100644 --- a/include/merovingian/homeserver/CrossSigningResetApprovals.hpp +++ b/include/merovingian/homeserver/CrossSigningResetApprovals.hpp @@ -25,6 +25,10 @@ namespace merovingian::homeserver // so a failed store does not spend it and two concurrent uploads cannot both use one approval: `runtime.mutex` // serialises every use, and the second upload finds nothing to take. // +// An approval may be bound to one of the user's OAuth devices, the one whose upload asked for it (the `device_id` of +// the `m.oauth` challenge URL, ADR-0809): only that device's upload may take it. An approval with an empty device is +// unbound and any of the user's OAuth sessions may take it, as before. +// // Bounded at `max_approvals`; expired approvals are removed at the start of every operation, soonest first, at the cost // of those removed. Every operation takes the current time, so a test needs no clock. class CrossSigningResetApprovals final @@ -37,18 +41,26 @@ class CrossSigningResetApprovals final // bounded at 4096 (`AccountSessionStore::max_sessions`). static constexpr auto max_approvals = std::size_t{4096U}; - // Records an approval for `user_id` valid until `now_ms + lifetime_ms`, replacing any the user holds. False, with - // nothing recorded, for an empty user ID or at `max_approvals` approvals of other users. - [[nodiscard]] auto approve(std::string_view user_id, std::uint64_t now_ms) -> bool; + // Records an approval for `user_id` valid until `now_ms + lifetime_ms`, bound to `device_id` (empty: unbound), + // replacing any the user holds. False, with nothing recorded, for an empty user ID or at `max_approvals` approvals + // of other users. + [[nodiscard]] auto approve(std::string_view user_id, std::string_view device_id, std::uint64_t now_ms) -> bool; // Whether `user_id` holds a live approval. [[nodiscard]] auto holds(std::string_view user_id, std::uint64_t now_ms) -> bool; - // Removes the user's live approval and returns its expiry, or nullopt when there is none. - [[nodiscard]] auto take(std::string_view user_id, std::uint64_t now_ms) -> std::optional; + // The device the user's live approval is bound to: empty when unbound, nullopt when there is no live approval. + [[nodiscard]] auto bound_device(std::string_view user_id, std::uint64_t now_ms) -> std::optional; + + // Removes the user's live approval and returns its expiry, or nullopt when there is none or it is bound to a device + // other than `device_id` (which then keeps it). + [[nodiscard]] auto take(std::string_view user_id, std::string_view device_id, std::uint64_t now_ms) + -> std::optional; - // Gives back an approval `take` returned, unless it has expired since or the user approved again meanwhile. - auto restore(std::string_view user_id, std::uint64_t expires_at_ms, std::uint64_t now_ms) -> void; + // Gives back an approval `take` returned, with the device it was bound to, unless it has expired since or the user + // approved again meanwhile. + auto restore(std::string_view user_id, std::string_view bound_device_id, std::uint64_t expires_at_ms, + std::uint64_t now_ms) -> void; // Removes the user's approval, live or not (a password change, a deactivation). auto withdraw(std::string_view user_id) -> void; @@ -64,10 +76,12 @@ class CrossSigningResetApprovals final struct Approval final { std::uint64_t expires_at_ms{0U}; + // Empty when unbound. + std::string device_id{}; ExpiryIndex::iterator expiry{}; }; - auto record(std::string_view user_id, std::uint64_t expires_at_ms) -> void; + auto record(std::string_view user_id, std::string_view device_id, std::uint64_t expires_at_ms) -> void; std::unordered_map> m_by_user{}; // expiry -> user, soonest first, so `erase_expired` costs only what it removes. diff --git a/include/merovingian/oauth/AccountPages.hpp b/include/merovingian/oauth/AccountPages.hpp index 7cd099cdf..050679eed 100644 --- a/include/merovingian/oauth/AccountPages.hpp +++ b/include/merovingian/oauth/AccountPages.hpp @@ -46,6 +46,9 @@ inline constexpr auto account_action_cross_signing_reset = std::string_view{"org -> std::optional; // Whether `action` takes the `device_id` parameter (spec: "Actions which don't support the device ID will ignore it"). [[nodiscard]] auto account_action_takes_device(std::string_view action) noexcept -> bool; +// Whether `action` carries a `device_id` through the sign-in: the device actions, and the cross-signing reset, whose +// approval is bound to the device that asked for it (ADR-0809). +[[nodiscard]] auto account_action_carries_device(std::string_view action) noexcept -> bool; // The address of the account page for `action` and, when given, `device_id`: `account_url` (`OAuthBaseUrl::url( // account_path)`) with `?action=` and `&device_id=`, each value percent-encoded (`percent_encode_redirect_value`) so @@ -92,8 +95,11 @@ inline constexpr auto account_post_approve_reset = HtmlName{"approve_cross_signi // `org.matrix.account_deactivate`: what deactivation does, and the password again. [[nodiscard]] auto account_deactivate_page(AccountPageFrame const& frame, std::optional const& error) -> Page; // `org.matrix.cross_signing_reset`: that the user's encryption identity will be replaced and other users will see them -// as unverified, and the approve button. -[[nodiscard]] auto account_cross_signing_reset_page(AccountPageFrame const& frame) -> Page; +// as unverified, and the approve button. With `device` (one of the user's OAuth devices, the one that asked), the page +// names the device and its client and the form carries its ID, so only that device may use the approval; without, it +// says that any application signed in with OAuth may use it (ADR-0809). +[[nodiscard]] auto account_cross_signing_reset_page(AccountPageFrame const& frame, + std::optional const& device) -> Page; // A signed-in page that reports what was done (or what failed): `title`, `message` and the links back. [[nodiscard]] auto account_result_page(AccountPageFrame const& frame, HtmlText title, HtmlText const& message) -> Page; // A page with no session: `title`, `message` and a link to sign in again at `account_url`. diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 3709e9099..e2b21dfc7 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -209,7 +209,10 @@ Rules (ADR-0796 to ADR-0798): succeeds. A password stage from an OAuth session is answered with the challenge and never checked. A retry with no `auth` or no `session` completes the stage when an approval is live (clients poll that way); a `session` this server did not issue for this does not. The challenge names `live_uia_session` before issuing one, so polling never costs a - session per request (ADR-0799); keep both when changing the stage. + session per request (ADR-0799); keep both when changing the stage. The challenge URL carries the requesting device, + and the reset page binds the approval to it only when it is one of the user's OAuth devices + (`reset_requesting_device`); a bound approval is taken only by that device's upload and restored bound (ADR-0809). + Never show or bind a `device_id` that check refuses. - Log `user_id` only (`account.page.*`); never a password, the cookie, a form token or the query. The legacy API switch (`server.oauth.legacy_api_enabled`, ADR-0801) is decided by `legacy_auth_refusal` diff --git a/src/homeserver/AccountPage.cpp b/src/homeserver/AccountPage.cpp index a83a554f2..b655231dc 100644 --- a/src/homeserver/AccountPage.cpp +++ b/src/homeserver/AccountPage.cpp @@ -133,8 +133,8 @@ namespace } // The action and device the browser asked for, each only when valid: `action` one of the six spec actions, and - // `device_id` only with a device action and only one `auth::device_id_is_valid` accepts (spec: "Actions which don't - // support the device ID will ignore it"). + // `device_id` only with a device action or the cross-signing reset (ADR-0809) and only one + // `auth::device_id_is_valid` accepts (spec: "Actions which don't support the device ID will ignore it"). struct RequestedPage final { std::optional action{}; @@ -146,7 +146,7 @@ namespace { auto page = RequestedPage{}; page.action = oauth::account_management_action(action); - if (page.action.has_value() && oauth::account_action_takes_device(*page.action) && device_id.has_value() && + if (page.action.has_value() && oauth::account_action_carries_device(*page.action) && device_id.has_value() && auth::device_id_is_valid(*device_id)) { page.device_id = std::string{*device_id}; @@ -313,6 +313,25 @@ namespace return found; } + // The device a cross-signing reset approval may be bound to: one of the user's own devices that holds an OAuth + // session (ADR-0809). Anything else (another user's device, an unknown one, a legacy device) is nullopt and is + // never shown. + [[nodiscard]] auto reset_requesting_device(HomeserverRuntime const& runtime, std::string_view user_id, + std::optional device_id) + -> std::optional + { + if (!device_id.has_value() || !auth::device_id_is_valid(*device_id)) + { + return std::nullopt; + } + auto device = user_device(runtime, user_id, *device_id); + if (!device.has_value() || !device->oauth_session) + { + return std::nullopt; + } + return device; + } + [[nodiscard]] auto unknown_device_response(AccountContext const& context, SignedIn const& signed_in) -> LocalHttpResponse { @@ -357,7 +376,12 @@ namespace } if (action == oauth::account_action_cross_signing_reset) { - return oauth_plain_page(status_ok, oauth::account_cross_signing_reset_page(frame)); + auto const device = reset_requesting_device( + runtime, user_id, + requested.device_id.has_value() ? std::optional{*requested.device_id} : std::nullopt); + auto const view = + device.has_value() ? std::optional{view_of(*device)} : std::nullopt; + return oauth_plain_page(status_ok, oauth::account_cross_signing_reset_page(frame, view)); } auto const profile = database::find_profile(runtime.database.persistent_store, user_id); auto display_name = std::optional{}; @@ -712,12 +736,27 @@ namespace oauth::HtmlText{"Your account is deactivated and every session of it is signed out."}); } - [[nodiscard]] auto handle_approve_reset(AccountContext const& context, SignedIn const& signed_in) - -> LocalHttpResponse + [[nodiscard]] auto handle_approve_reset(AccountContext const& context, SignedIn const& signed_in, + core::FormFields const& fields) -> LocalHttpResponse { auto& runtime = context.rt.homeserver; auto const& user_id = signed_in.session.user_id; - if (!runtime.cross_signing_reset_approvals.approve(user_id, oauth_wall_clock_ms())) + // The page carries the device it named (ADR-0809). A posted device that is no longer one of the user's OAuth + // devices is refused, never widened into an approval any session could use. + auto const posted_device = fields.find(oauth::account_device_field.view()); + auto bound_device = std::string{}; + if (posted_device.has_value()) + { + auto const device = reset_requesting_device(runtime, user_id, posted_device); + if (!device.has_value()) + { + return result_page(context, signed_in, status_bad_request, oauth::HtmlText{"Reset not allowed"}, + oauth::HtmlText{"The device that asked for the reset is no longer signed in to your " + "account. Nothing was allowed."}); + } + bound_device = device->device_id; + } + if (!runtime.cross_signing_reset_approvals.approve(user_id, bound_device, oauth_wall_clock_ms())) { return with_retry_after(result_page(context, signed_in, status_unavailable, oauth::HtmlText{"Reset not allowed"}, @@ -725,7 +764,7 @@ namespace 1U); } append_local_audit(runtime.database, observability::AuditCategory::auth, "cross_signing.reset_approved", - user_id, user_id, "account page"); + user_id, user_id, bound_device.empty() ? "account page" : "account page; bound to a device"); log_account("account.page.cross_signing_reset_approved", user_id, observability::LogEventSeverity::info); return result_page(context, signed_in, status_ok, oauth::HtmlText{"Reset allowed"}, oauth::HtmlText{"Return to your application to finish the reset. The permission lasts 10 " @@ -796,7 +835,7 @@ namespace } if (action == oauth::account_post_approve_reset.view()) { - return handle_approve_reset(context, *signed_in); + return handle_approve_reset(context, *signed_in, *fields); } return form_refused(oauth::HtmlText{"This form asked for something this page does not do."}); } diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index e275469f8..fc23ec6d9 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -13449,9 +13449,11 @@ namespace class TakenResetApproval final { public: - TakenResetApproval(ClientServerRuntime& rt, std::string_view user_id, std::uint64_t expires_at_ms) + TakenResetApproval(ClientServerRuntime& rt, std::string_view user_id, std::string_view bound_device_id, + std::uint64_t expires_at_ms) : m_rt{&rt} , m_user_id{user_id} + , m_bound_device_id{bound_device_id} , m_expires_at_ms{expires_at_ms} { } @@ -13467,7 +13469,7 @@ namespace } try { - m_rt->homeserver.cross_signing_reset_approvals.restore(m_user_id, m_expires_at_ms, + m_rt->homeserver.cross_signing_reset_approvals.restore(m_user_id, m_bound_device_id, m_expires_at_ms, oauth_wall_clock_ms()); } catch (...) @@ -13488,6 +13490,8 @@ namespace private: ClientServerRuntime* m_rt; std::string m_user_id; + // The device the approval was bound to (empty: unbound), so a restored approval keeps its binding (ADR-0809). + std::string m_bound_device_id; std::uint64_t m_expires_at_ms; bool m_spent{false}; }; @@ -13498,6 +13502,7 @@ namespace { std::optional answer{}; std::uint64_t approval_expires_at_ms{0U}; + std::string approval_device_id{}; }; // The name the `m.oauth` stage had before spec v1.17, offered as a second flow with the same parameters for clients @@ -13511,16 +13516,18 @@ namespace // The stage is complete when the user approved the reset on the account page in the last ten minutes and the // request either names a session this server issued to this user for this purpose, or names no session at all // (no `auth` dict, or one without `session`): a client that polls by resending the same upload is accepted once - // the approval exists (ADR-0799). The approval is a per-user flag any of the user's OAuth sessions may spend once, - // so the session ID adds no secret. A `type` other than absent, `m.oauth` or the pre-standard name (a password - // stage) is answered with the challenge and never checked: an OAuth session cannot complete the upload with a - // password. So is a `session` this server did not issue to this user for this purpose. The approval is taken here - // and spent only by a stored upload. + // the approval exists (ADR-0799). The challenge URL carries the requesting device's `device_id` (spec "Account + // management URL parameters": a Matrix-specific action may take it), so the page can bind the approval to that + // device; a bound approval is spent only by that device's upload, an unbound one by any of the user's OAuth + // sessions (ADR-0809). The session ID adds no secret. A `type` other than absent, `m.oauth` or the pre-standard + // name (a password stage) is answered with the challenge and never checked: an OAuth session cannot complete the + // upload with a password. So is a `session` this server did not issue to this user for this purpose. The approval + // is taken here and spent only by a stored upload. // // A challenge reuses the user's newest live session for this purpose before issuing one, so a client polling // before the approval holds one session, not one per poll (a session lives ten minutes; ADR-0799). [[nodiscard]] auto oauth_cross_signing_reset_stage(ClientServerRuntime& rt, LocalHttpRequest const& req, - std::string_view user, + std::string_view user, std::string_view device_id, std::optional const& body) -> std::optional { @@ -13534,9 +13541,9 @@ namespace { return std::nullopt; } - auto const challenge = [base_url](std::string_view session) { + auto const challenge = [base_url, device_id](std::string_view session) { auto const url = oauth::account_action_address(base_url->url(oauth::account_path), - oauth::account_action_cross_signing_reset); + oauth::account_action_cross_signing_reset, device_id); auto const flow = [](std::string_view stage) { return json_obj({json_member("stages", json_arr({json_str(std::string{stage})}))}); }; @@ -13550,7 +13557,7 @@ namespace json_member(std::string{cross_signing_reset_unstable_stage}, params())})), json_member("session", json_str(std::string{session})), }); - return OAuthResetStage{resp(401U, json_serialize(body_json)), 0U}; + return OAuthResetStage{resp(401U, json_serialize(body_json)), 0U, {}}; }; // `auth`, when present, must be an object, and its `type` and `session`, when present, strings: anything else // is answered with the challenge, as a foreign session is. @@ -13569,11 +13576,12 @@ namespace type == nullptr || *type == "m.oauth" || *type == cross_signing_reset_unstable_stage; if (well_formed && names_this_stage && (session_value == nullptr || issued_session)) { - if (auto const expires_at_ms = - rt.homeserver.cross_signing_reset_approvals.take(user, oauth_wall_clock_ms()); - expires_at_ms.has_value()) + auto& approvals = rt.homeserver.cross_signing_reset_approvals; + auto const now_ms = oauth_wall_clock_ms(); + auto bound_device = approvals.bound_device(user, now_ms).value_or(std::string{}); + if (auto const expires_at_ms = approvals.take(user, device_id, now_ms); expires_at_ms.has_value()) { - return OAuthResetStage{std::nullopt, *expires_at_ms}; + return OAuthResetStage{std::nullopt, *expires_at_ms, std::move(bound_device)}; } } // Not approved yet, another stage, or a session this server did not issue for this: the challenge, naming the @@ -13589,11 +13597,11 @@ namespace auto const issued = issue_uia_session(rt, cross_signing_reset_uia_purpose, user); if (!issued.has_value()) { - return OAuthResetStage{uia_pool_full_response(rt, req).response, 0U}; + return OAuthResetStage{uia_pool_full_response(rt, req).response, 0U, {}}; } if (issued->empty()) { - return OAuthResetStage{err(500U, "M_UNKNOWN", "no authentication session could be issued"), 0U}; + return OAuthResetStage{err(500U, "M_UNKNOWN", "no authentication session could be issued"), 0U, {}}; } return challenge(*issued); } @@ -13616,7 +13624,7 @@ namespace { if (auto const refusal = oauth_session_uia_refusal(rt, req.access_token); refusal.has_value()) { - auto const stage = oauth_cross_signing_reset_stage(rt, req, user, cs_body); + auto const stage = oauth_cross_signing_reset_stage(rt, req, user, device_id, cs_body); if (!stage.has_value()) { return err(403U, "M_FORBIDDEN", *refusal); @@ -13625,7 +13633,7 @@ namespace { return *stage->answer; } - taken_approval.emplace(rt, user, stage->approval_expires_at_ms); + taken_approval.emplace(rt, user, stage->approval_device_id, stage->approval_expires_at_ms); } else { diff --git a/src/homeserver/CrossSigningResetApprovals.cpp b/src/homeserver/CrossSigningResetApprovals.cpp index 597c203ca..e07d49494 100644 --- a/src/homeserver/CrossSigningResetApprovals.cpp +++ b/src/homeserver/CrossSigningResetApprovals.cpp @@ -2,6 +2,10 @@ // SPDX-License-Identifier: GPL-3.0-or-later #include "merovingian/homeserver/CrossSigningResetApprovals.hpp" +#include +#include +#include + namespace merovingian::homeserver { @@ -29,14 +33,16 @@ auto CrossSigningResetApprovals::withdraw(std::string_view user_id) -> void m_by_user.erase(user); } -auto CrossSigningResetApprovals::record(std::string_view user_id, std::uint64_t expires_at_ms) -> void +auto CrossSigningResetApprovals::record(std::string_view user_id, std::string_view device_id, + std::uint64_t expires_at_ms) -> void { withdraw(user_id); auto const expiry = m_by_expiry.emplace(expires_at_ms, std::string{user_id}); - m_by_user.emplace(std::string{user_id}, Approval{expires_at_ms, expiry}); + m_by_user.emplace(std::string{user_id}, Approval{expires_at_ms, std::string{device_id}, expiry}); } -auto CrossSigningResetApprovals::approve(std::string_view user_id, std::uint64_t now_ms) -> bool +auto CrossSigningResetApprovals::approve(std::string_view user_id, std::string_view device_id, std::uint64_t now_ms) + -> bool { if (user_id.empty()) { @@ -47,7 +53,7 @@ auto CrossSigningResetApprovals::approve(std::string_view user_id, std::uint64_t { return false; } - record(user_id, now_ms + lifetime_ms); + record(user_id, device_id, now_ms + lifetime_ms); return true; } @@ -57,7 +63,8 @@ auto CrossSigningResetApprovals::holds(std::string_view user_id, std::uint64_t n return m_by_user.contains(user_id); } -auto CrossSigningResetApprovals::take(std::string_view user_id, std::uint64_t now_ms) -> std::optional +auto CrossSigningResetApprovals::bound_device(std::string_view user_id, std::uint64_t now_ms) + -> std::optional { erase_expired(now_ms); auto const user = m_by_user.find(user_id); @@ -65,21 +72,34 @@ auto CrossSigningResetApprovals::take(std::string_view user_id, std::uint64_t no { return std::nullopt; } + return user->second.device_id; +} + +auto CrossSigningResetApprovals::take(std::string_view user_id, std::string_view device_id, std::uint64_t now_ms) + -> std::optional +{ + erase_expired(now_ms); + auto const user = m_by_user.find(user_id); + // A bound approval is the one device's to spend (ADR-0809); another device's upload leaves it in place. + if (user == m_by_user.end() || (!user->second.device_id.empty() && user->second.device_id != device_id)) + { + return std::nullopt; + } auto const expires_at_ms = user->second.expires_at_ms; m_by_expiry.erase(user->second.expiry); m_by_user.erase(user); return expires_at_ms; } -auto CrossSigningResetApprovals::restore(std::string_view user_id, std::uint64_t expires_at_ms, std::uint64_t now_ms) - -> void +auto CrossSigningResetApprovals::restore(std::string_view user_id, std::string_view bound_device_id, + std::uint64_t expires_at_ms, std::uint64_t now_ms) -> void { erase_expired(now_ms); if (user_id.empty() || expires_at_ms <= now_ms || m_by_user.contains(user_id) || m_by_user.size() >= max_approvals) { return; } - record(user_id, expires_at_ms); + record(user_id, bound_device_id, expires_at_ms); } auto CrossSigningResetApprovals::size() const noexcept -> std::size_t diff --git a/src/oauth/AccountPages.cpp b/src/oauth/AccountPages.cpp index 0367ba3aa..86cb73c69 100644 --- a/src/oauth/AccountPages.cpp +++ b/src/oauth/AccountPages.cpp @@ -166,6 +166,11 @@ auto account_action_takes_device(std::string_view action) noexcept -> bool return action == account_action_device_view || action == account_action_device_delete; } +auto account_action_carries_device(std::string_view action) noexcept -> bool +{ + return account_action_takes_device(action) || action == account_action_cross_signing_reset; +} + auto account_sign_in_page(AccountSignInInput const& input) -> Page { auto page = Page{HtmlText{"Sign in to manage your account"}}; @@ -184,7 +189,7 @@ auto account_sign_in_page(AccountSignInInput const& input) -> Page { form.hidden(account_next_action_field, std::move(*text)); } - if (input.next_device_id.has_value() && account_action_takes_device(*action)) + if (input.next_device_id.has_value() && account_action_carries_device(*action)) { if (auto text = HtmlText::escape(*input.next_device_id); text.has_value()) { @@ -330,18 +335,34 @@ auto account_deactivate_page(AccountPageFrame const& frame, std::optional Page +auto account_cross_signing_reset_page(AccountPageFrame const& frame, std::optional const& device) + -> Page { auto page = Page{HtmlText{"Reset your encryption identity"}}; add_signed_in_as(page, frame); page.paragraph(HtmlText{"Your application asked to replace your encryption identity (your cross-signing keys). If " "you allow it, the people you talk to will see you as unverified until they verify you " "again, and your other devices must be verified again."}); + auto device_value = device.has_value() ? HtmlText::escape(device->device_id) : std::nullopt; + if (device_value.has_value()) + { + page.paragraph(HtmlText{"The reset was asked for by this device. Only this device can use the permission:"}); + page.details(device_details(*device)); + } + else + { + page.paragraph(HtmlText{"The request did not say which device asked for the reset. Any application signed in " + "to your account through the sign-in page of this server can use the permission."}); + } page.paragraph( HtmlText{"Allow it only if you started the reset in your application. The permission lasts 10 minutes " "and is used by one reset."}); if (auto form = session_form(frame); form.has_value()) { + if (device_value.has_value()) + { + form->hidden(account_device_field, std::move(*device_value)); + } std::ignore = form->button(SubmitButton{action_field, account_post_approve_reset, HtmlText{"Allow the reset"}}); std::ignore = page.form(*form); } diff --git a/tests/conformance/test_oauth_account_management_conformance.cpp b/tests/conformance/test_oauth_account_management_conformance.cpp index 01343a703..59ef47df4 100644 --- a/tests/conformance/test_oauth_account_management_conformance.cpp +++ b/tests/conformance/test_oauth_account_management_conformance.cpp @@ -253,8 +253,11 @@ SCENARIO( REQUIRE(oauth_params != nullptr); auto const* url = string_member(*oauth_params, "url"); REQUIRE(url != nullptr); - // Spec SHOULD: the org.matrix.cross_signing_reset action in the URL of the m.oauth UIA type. - REQUIRE(*url == std::string{oauth_account_url} + "?action=org.matrix.cross_signing_reset"); + // Spec SHOULD: the org.matrix.cross_signing_reset action in the URL of the m.oauth UIA type. Spec + // (account management URL parameters): "For Matrix-specific actions, the user's device ID" MAY be + // carried as device_id; the server names the device that asked (ADR-0809). + REQUIRE(*url == std::string{oauth_account_url} + "?action=org.matrix.cross_signing_reset&device_id=" + + std::string{oauth_test_device}); REQUIRE(approved.status == 200U); // Spec: "the client submits an auth dict with just the session ... to complete the stage". REQUIRE(completed.status == 200U); diff --git a/tests/integration/test_oauth_account_pages_flow.cpp b/tests/integration/test_oauth_account_pages_flow.cpp index fb386a2c5..f50274fb1 100644 --- a/tests/integration/test_oauth_account_pages_flow.cpp +++ b/tests/integration/test_oauth_account_pages_flow.cpp @@ -49,8 +49,9 @@ constexpr auto alice_id = std::string_view{"@alice:example.org"}; constexpr auto bob_password = std::string_view{"BobPass99!xyz"}; constexpr auto bob_id = std::string_view{"@bob:example.org"}; constexpr auto upload_path = std::string_view{"/_matrix/client/v3/keys/device_signing/upload"}; -constexpr auto reset_url = - std::string_view{"https://matrix.example.org/_merovingian/account?action=org.matrix.cross_signing_reset"}; +// The challenge names the requesting device (ADR-0809); the fixture's OAuth device is OAUTHDEV01. +constexpr auto reset_url = std::string_view{ + "https://matrix.example.org/_merovingian/account?action=org.matrix.cross_signing_reset&device_id=OAUTHDEV01"}; [[nodiscard]] auto account_config(bool oauth_enabled = true) -> merovingian::config::Config { @@ -796,10 +797,10 @@ SCENARIO("A cross-signing reset approval is not usable expired, by a refused upl WHEN("each misuse is tried") { // An approval granted just over ten minutes ago. - REQUIRE(approvals.approve(alice_id, now - hs::CrossSigningResetApprovals::lifetime_ms)); + REQUIRE(approvals.approve(alice_id, {}, now - hs::CrossSigningResetApprovals::lifetime_ms)); auto const expired = upload(oauth.access_token, replacement.master_member() + session_auth); // A live approval, then an upload that takes it and is refused (bob's key) before anything is stored. - REQUIRE(approvals.approve(alice_id, now)); + REQUIRE(approvals.approve(alice_id, {}, now)); auto const refused = upload(oauth.access_token, make_cross_signing_set(std::string{bob_id}).master_member() + session_auth); auto const held_after_refusal = approval_held(rt, alice_id); @@ -857,3 +858,136 @@ SCENARIO("The OAuth server metadata names the account page and its six actions", } } } + +SCENARIO("A cross-signing reset approval given for the device that asked is spent only by that device", + "[integration][oauth][oauth-account][oauth-uia][reset-binding][security]") +{ + GIVEN("alice signed in through OAuth on OAUTHDEV01 and OAUTHDEV0B, with a password on LEGACYDEV, and keys held") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const device_a = oauth_sign_in(rt, fixture.client_id, "alice", alice_password); + REQUIRE(device_a.ok); + auto const device_b = oauth_sign_in(rt, fixture.client_id, "alice", alice_password, + with_parameter(oauth_authorize_parameters(fixture.client_id), "scope", + oauth_scope_for_device("OAUTHDEV0B"))); + REQUIRE(device_b.ok); + REQUIRE_FALSE(password_login(rt, "alice", alice_password, "LEGACYDEV").empty()); + REQUIRE_FALSE(password_login(rt, "bob", bob_password, "BOBDEV").empty()); + auto const upload = [&](std::string const& token, std::string const& members) { + return send(rt, "POST", std::string{upload_path}, token, "{" + members + "}"); + }; + REQUIRE(upload(device_a.access_token, + make_cross_signing_set(std::string{alice_id}).selected_members(true, true, true)) + .status == 200U); + auto const alice = account_sign_in(rt, "alice", alice_password); + REQUIRE_FALSE(alice.form_token.empty()); + auto const reset_page = [&](std::string_view device) { + return get_account(rt, "action=org.matrix.cross_signing_reset&device_id=" + std::string{device}, + alice.browser); + }; + + WHEN("OAUTHDEV0B's replacing upload is challenged, and alice opens the URL it names") + { + auto const challenge = + upload(device_b.access_token, make_cross_signing_set(std::string{alice_id}).master_member()); + auto const page = reset_page("OAUTHDEV0B"); + + THEN("the URL carries OAUTHDEV0B, and the page names the device and its client and carries its ID") + { + REQUIRE(challenge.status == 401U); + CHECK(contains(challenge.body, "action=org.matrix.cross_signing_reset&device_id=OAUTHDEV0B")); + REQUIRE(page.status == 200U); + CHECK(contains(page.body, "Only this device can use the permission")); + CHECK(contains(page.body, "OAUTHDEV0B")); + CHECK(contains(page.body, "Test App")); + CHECK(contains(page.body, R"(name="device_id" value="OAUTHDEV0B")")); + } + } + + WHEN("alice approves for OAUTHDEV0B, then OAUTHDEV01 polls its upload, then OAUTHDEV0B does") + { + auto const approved = post_account(rt, + session_form(alice, "approve_cross_signing_reset", + { + {"device_id", "OAUTHDEV0B"} + }), + alice.browser); + auto const by_a = + upload(device_a.access_token, make_cross_signing_set(std::string{alice_id}).master_member()); + auto const held_after_a = approval_held(rt, alice_id); + auto const by_b = + upload(device_b.access_token, make_cross_signing_set(std::string{alice_id}).master_member()); + + THEN("OAUTHDEV01 is challenged and leaves the approval; OAUTHDEV0B spends it") + { + CHECK(approved.status == 200U); + CHECK(by_a.status == 401U); + CHECK(held_after_a); + CHECK(by_b.status == 200U); + CHECK_FALSE(approval_held(rt, alice_id)); + CHECK(audit_count(rt, "cross_signing.reset_used") == 1U); + } + } + + WHEN("alice approves with no device, then OAUTHDEV01 polls its upload") + { + auto const page = get_account(rt, "action=org.matrix.cross_signing_reset", alice.browser); + auto const approved = post_account(rt, session_form(alice, "approve_cross_signing_reset"), alice.browser); + auto const by_a = + upload(device_a.access_token, make_cross_signing_set(std::string{alice_id}).master_member()); + + THEN("the page says any OAuth application may use it, and any of her OAuth sessions spends it as before") + { + CHECK(contains(page.body, "Any application signed in to your account")); + CHECK_FALSE(contains(page.body, R"(name="device_id")")); + CHECK(approved.status == 200U); + CHECK(by_a.status == 200U); + CHECK_FALSE(approval_held(rt, alice_id)); + } + } + + WHEN("the page is asked for with bob's device, a legacy device of alice's, and an unknown device") + { + auto const bobs = reset_page("BOBDEV"); + auto const legacy = reset_page("LEGACYDEV"); + auto const unknown = reset_page("NOSUCHDEV"); + + THEN("each device is ignored and never shown: the page is the unbound one") + { + for (auto const* page : {&bobs, &legacy, &unknown}) + { + CHECK(page->status == 200U); + CHECK(contains(page->body, "Any application signed in to your account")); + CHECK_FALSE(contains(page->body, R"(name="device_id")")); + } + CHECK_FALSE(contains(bobs.body, "BOBDEV")); + CHECK_FALSE(contains(legacy.body, "LEGACYDEV")); + CHECK_FALSE(contains(unknown.body, "NOSUCHDEV")); + } + } + + WHEN("an approval is posted naming a device that is not one of her OAuth devices") + { + auto const for_legacy = post_account(rt, + session_form(alice, "approve_cross_signing_reset", + { + {"device_id", "LEGACYDEV"} + }), + alice.browser); + auto const for_bobs = post_account(rt, + session_form(alice, "approve_cross_signing_reset", + { + {"device_id", "BOBDEV"} + }), + alice.browser); + + THEN("nothing is approved") + { + CHECK(for_legacy.status == 400U); + CHECK(for_bobs.status == 400U); + CHECK_FALSE(approval_held(rt, alice_id)); + } + } + } +} diff --git a/tests/unit/test_oauth_account_pages.cpp b/tests/unit/test_oauth_account_pages.cpp index 922708fb2..ac1309b6c 100644 --- a/tests/unit/test_oauth_account_pages.cpp +++ b/tests/unit/test_oauth_account_pages.cpp @@ -159,7 +159,7 @@ SCENARIO("Every signed-in account page escapes the user, the server and every de merovingian::oauth::account_unknown_device_page(frame).render(), merovingian::oauth::account_password_page(frame, HtmlText{"An error."}).render(), merovingian::oauth::account_deactivate_page(frame, std::nullopt).render(), - merovingian::oauth::account_cross_signing_reset_page(frame).render(), + merovingian::oauth::account_cross_signing_reset_page(frame, std::nullopt).render(), merovingian::oauth::account_result_page(frame, HtmlText{"Done"}, HtmlText{"It was done."}).render(), }; @@ -201,7 +201,7 @@ SCENARIO("An account page shows fixed text for a value it cannot show, and no fo { auto const device_html = merovingian::oauth::account_device_page(frame, device).render(); auto const overview = merovingian::oauth::account_overview_page(tokenless, std::nullopt).render(); - auto const reset = merovingian::oauth::account_cross_signing_reset_page(tokenless).render(); + auto const reset = merovingian::oauth::account_cross_signing_reset_page(tokenless, std::nullopt).render(); auto const remove = merovingian::oauth::account_device_delete_page(tokenless, device).render(); THEN("fixed text replaces each value, and a page with no token shows no form") diff --git a/tests/unit/test_oauth_cross_signing_reset_approvals.cpp b/tests/unit/test_oauth_cross_signing_reset_approvals.cpp index ff6e30932..9615a8fbc 100644 --- a/tests/unit/test_oauth_cross_signing_reset_approvals.cpp +++ b/tests/unit/test_oauth_cross_signing_reset_approvals.cpp @@ -10,6 +10,7 @@ #include #include +#include #include #include @@ -29,15 +30,15 @@ SCENARIO("A cross-signing reset approval lives ten minutes and is taken once", " GIVEN("an approval of alice") { auto approvals = CrossSigningResetApprovals{}; - REQUIRE(approvals.approve(alice, start_ms)); + REQUIRE(approvals.approve(alice, {}, start_ms)); WHEN("it is read, taken twice, and read at its end") { auto const held_before_end = approvals.holds(alice, start_ms + CrossSigningResetApprovals::lifetime_ms - 1U); auto const bob_holds = approvals.holds(bob, start_ms + 1U); - auto const first = approvals.take(alice, start_ms + 1U); - auto const second = approvals.take(alice, start_ms + 2U); + auto const first = approvals.take(alice, {}, start_ms + 1U); + auto const second = approvals.take(alice, {}, start_ms + 2U); THEN("it is alice's alone, the first take returns its expiry and the second finds nothing") { @@ -53,7 +54,7 @@ SCENARIO("A cross-signing reset approval lives ten minutes and is taken once", " WHEN("it is read at its end") { auto const held = approvals.holds(alice, start_ms + CrossSigningResetApprovals::lifetime_ms); - auto const taken = approvals.take(alice, start_ms + CrossSigningResetApprovals::lifetime_ms); + auto const taken = approvals.take(alice, {}, start_ms + CrossSigningResetApprovals::lifetime_ms); THEN("it has expired") { @@ -70,24 +71,24 @@ SCENARIO("A taken approval goes back only while it is live and the user has not GIVEN("an approval of alice taken by an upload") { auto approvals = CrossSigningResetApprovals{}; - REQUIRE(approvals.approve(alice, start_ms)); - auto const expiry = approvals.take(alice, start_ms + 1U); + REQUIRE(approvals.approve(alice, {}, start_ms)); + auto const expiry = approvals.take(alice, {}, start_ms + 1U); REQUIRE(expiry.has_value()); WHEN("the upload is refused and gives it back") { - approvals.restore(alice, *expiry, start_ms + 2U); + approvals.restore(alice, {}, *expiry, start_ms + 2U); THEN("alice holds it again with its first expiry") { CHECK(approvals.holds(alice, start_ms + 3U)); - CHECK(approvals.take(alice, start_ms + 3U) == expiry); + CHECK(approvals.take(alice, {}, start_ms + 3U) == expiry); } } WHEN("it is given back after its expiry") { - approvals.restore(alice, *expiry, *expiry); + approvals.restore(alice, {}, *expiry, *expiry); THEN("nothing is held") { @@ -98,12 +99,12 @@ SCENARIO("A taken approval goes back only while it is live and the user has not WHEN("alice approves again before the upload gives it back") { - REQUIRE(approvals.approve(alice, start_ms + 100U)); - approvals.restore(alice, *expiry, start_ms + 101U); + REQUIRE(approvals.approve(alice, {}, start_ms + 100U)); + approvals.restore(alice, {}, *expiry, start_ms + 101U); THEN("the newer approval stays") { - CHECK(approvals.take(alice, start_ms + 102U) == + CHECK(approvals.take(alice, {}, start_ms + 102U) == start_ms + 100U + CrossSigningResetApprovals::lifetime_ms); } } @@ -115,19 +116,20 @@ SCENARIO("An approval is withdrawn, replaced by a newer one, and bounded", "[oau GIVEN("approvals of alice and bob") { auto approvals = CrossSigningResetApprovals{}; - REQUIRE(approvals.approve(alice, start_ms)); - REQUIRE(approvals.approve(bob, start_ms)); + REQUIRE(approvals.approve(alice, {}, start_ms)); + REQUIRE(approvals.approve(bob, {}, start_ms)); WHEN("alice's is withdrawn and bob approves again") { approvals.withdraw(alice); - REQUIRE(approvals.approve(bob, start_ms + 50U)); + REQUIRE(approvals.approve(bob, {}, start_ms + 50U)); THEN("alice holds none and bob one, with the later expiry") { CHECK_FALSE(approvals.holds(alice, start_ms + 1U)); CHECK(approvals.size() == 1U); - CHECK(approvals.take(bob, start_ms + 51U) == start_ms + 50U + CrossSigningResetApprovals::lifetime_ms); + CHECK(approvals.take(bob, {}, start_ms + 51U) == + start_ms + 50U + CrossSigningResetApprovals::lifetime_ms); } } } @@ -137,15 +139,15 @@ SCENARIO("An approval is withdrawn, replaced by a newer one, and bounded", "[oau auto approvals = CrossSigningResetApprovals{}; for (auto index = std::size_t{0U}; index < CrossSigningResetApprovals::max_approvals; ++index) { - REQUIRE(approvals.approve("@user" + std::to_string(index) + ":example.org", start_ms)); + REQUIRE(approvals.approve("@user" + std::to_string(index) + ":example.org", {}, start_ms)); } WHEN("alice approves while they live, then after they expire, and an empty user approves") { - auto const refused = approvals.approve(alice, start_ms + 1U); - auto const repeat = approvals.approve("@user0:example.org", start_ms + 1U); - auto const empty = approvals.approve({}, start_ms + 1U); - auto const later = approvals.approve(alice, start_ms + CrossSigningResetApprovals::lifetime_ms); + auto const refused = approvals.approve(alice, {}, start_ms + 1U); + auto const repeat = approvals.approve("@user0:example.org", {}, start_ms + 1U); + auto const empty = approvals.approve({}, {}, start_ms + 1U); + auto const later = approvals.approve(alice, {}, start_ms + CrossSigningResetApprovals::lifetime_ms); THEN("a new user is refused at the cap, a held user may approve again, and the cap frees on expiry") { @@ -158,3 +160,58 @@ SCENARIO("An approval is withdrawn, replaced by a newer one, and bounded", "[oau } } } + +SCENARIO("An approval bound to a device is taken only by that device's upload", "[oauth][oauth-reset-approval]") +{ + GIVEN("alice's approval bound to her device DEVB") + { + auto approvals = CrossSigningResetApprovals{}; + REQUIRE(approvals.approve(alice, "DEVB", start_ms)); + + WHEN("device DEVA's upload tries to take it, then DEVB's") + { + auto const by_a = approvals.take(alice, "DEVA", start_ms + 1U); + auto const bound = approvals.bound_device(alice, start_ms + 1U); + auto const by_b = approvals.take(alice, "DEVB", start_ms + 2U); + + THEN("DEVA takes nothing and leaves it, and DEVB takes it") + { + CHECK_FALSE(by_a.has_value()); + CHECK(bound == std::optional{"DEVB"}); + CHECK(by_b == start_ms + CrossSigningResetApprovals::lifetime_ms); + CHECK_FALSE(approvals.holds(alice, start_ms + 3U)); + } + } + + WHEN("DEVB takes it and gives it back") + { + auto const expiry = approvals.take(alice, "DEVB", start_ms + 1U); + REQUIRE(expiry.has_value()); + approvals.restore(alice, "DEVB", *expiry, start_ms + 2U); + + THEN("it is still bound to DEVB") + { + CHECK_FALSE(approvals.take(alice, "DEVA", start_ms + 3U).has_value()); + CHECK(approvals.take(alice, "DEVB", start_ms + 4U) == expiry); + } + } + } + + GIVEN("alice's unbound approval") + { + auto approvals = CrossSigningResetApprovals{}; + REQUIRE(approvals.approve(alice, {}, start_ms)); + + WHEN("device DEVA's upload takes it") + { + auto const bound = approvals.bound_device(alice, start_ms + 1U); + auto const by_a = approvals.take(alice, "DEVA", start_ms + 1U); + + THEN("any device may take it, as before") + { + CHECK(bound == std::optional{""}); + CHECK(by_a.has_value()); + } + } + } +} From 5a96eb1b067fef5cec764f51f32e185de4a2ac78 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:20:24 +0000 Subject: [PATCH 26/42] Log only a registered client_id, finish the code grant before its commit, keep the display name on refresh A refused token or device authorization request now logs client_id only after find_registered_oauth_client found it; before then it is text the caller chose. The code grant records the session a replayed code would end at the redemption's instant, before the grant commits, so nothing that can fail follows the commit (the old call ran after it, on a fresh clock, and could find the code expired). The refresh grant lists a device the runtime lost with the display name stored on its row, not its device ID. The token flow test now includes for the std::ignore of the previous commit. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 5 ++ src/homeserver/AGENTS.md | 7 +- src/homeserver/OAuthDeviceAuthorization.cpp | 7 +- src/homeserver/OAuthTokenEndpoint.cpp | 57 ++++++++++++--- .../integration/test_oauth_log_query_flow.cpp | 71 +++++++++++++++++-- tests/integration/test_oauth_token_flow.cpp | 25 +++++++ 6 files changed, 153 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f4437ccf8..7c5c3a7ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -89,6 +89,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) refresh-token reuse or expiry), so its client can be evicted or aged out (ADR-0808). * A cross-signing reset approved on a page that named the asking OAuth device can be used only by that device; the `m.oauth` URL now carries `device_id` (ADR-0809). +* A refused OAuth token or device request logs its `client_id` only when it names a registered client, so a caller + cannot write text of its choosing into the log. ## Bug fixes @@ -100,6 +102,9 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) every file in the directory. * `POST /keys/device_signing/upload` asks for UIA only to change held keys: a first upload or a repeat of the held keys succeeds without it, and an application service never needs it, as the spec says (ADR-0794). +* The code grant names the session a replayed code ends before it commits, so no step that can fail follows the + commit (ADR-0792). +* The OAuth refresh grant lists a device after a restart with its stored display name, not its device ID. ## Release notes diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index e2b21dfc7..8eaf54436 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -178,7 +178,10 @@ gate; `ClientServerRuntime.cpp` holds only the route matches. Rules: follows), then client, redirect URI byte for byte and PKCE, then `account_sign_in_gate`, the credential stamp and the device checks. A replayed code ends only the session that code produced (`AuthorizationCodeStore::record_issued_session`, matched on - client and `created_at_ms`). + client and `created_at_ms`), recorded at the redemption's instant before the grant commits, so nothing that can fail + follows the commit. +- **The refresh grant heals the runtime's device list with the device row's stored display name**, never the device + ID. - **A session ends through `end_device_session_and_announce`** (`ClientDeviceSessions.hpp`), shared with `POST /logout`: revocation, a replayed code, any new path that ends a session. - **A UIA endpoint calls `oauth_session_uia_refusal` first** (ADR-0794): `GET`/`POST /login/get_token`, @@ -186,6 +189,8 @@ gate; `ClientServerRuntime.cpp` holds only the route matches. Rules: `POST /delete_devices`, and `POST /keys/device_signing/upload` when the upload is not UIA-exempt, which then offers the `m.oauth` stage instead of the 403 (ADR-0797). An application service's masquerade token is never refused. - Never log a code, a verifier, a token or the body; log `client_id`, `grant_type`, `error`, `user_id`, `device_id`. + A refusal logs `client_id` only once `find_registered_oauth_client` found it, in the token and the device + authorization endpoints: before then it is text of the caller's choosing. The account pages are `handle_account_page` (`AccountPage.cpp`); `ClientServerRuntime.cpp` holds only the route match. Rules (ADR-0796 to ADR-0798): diff --git a/src/homeserver/OAuthDeviceAuthorization.cpp b/src/homeserver/OAuthDeviceAuthorization.cpp index 8d94096a2..a68121143 100644 --- a/src/homeserver/OAuthDeviceAuthorization.cpp +++ b/src/homeserver/OAuthDeviceAuthorization.cpp @@ -47,8 +47,8 @@ namespace constexpr auto status_unavailable = std::uint16_t{503U}; constexpr auto ms_per_second = std::uint64_t{1000U}; - // Logs a refused device authorization request: the wire error and the client ID when one was sent. Never a value - // the request carried beyond that. + // Logs a refused device authorization request: the wire error and the client ID once it names a registered client. + // Never a value the request carried beyond that. auto log_refused(std::string_view error_code, std::string_view client_id) -> void { auto fields = std::vector{ @@ -99,7 +99,8 @@ auto handle_oauth_device_authorization(ClientServerRuntime& rt, LocalHttpRequest auto const client = find_registered_oauth_client(runtime, *client_id); if (!client.has_value()) { - log_refused(oauth::error_invalid_client, *client_id); + // Not the client ID: it names no registered client, so it is text of the caller's choosing. + log_refused(oauth::error_invalid_client, {}); return oauth_error_response(status_bad_request, oauth::error_invalid_client, "The client is not registered."); } if (!client->has_grant_type(oauth::grant_type_device_code)) diff --git a/src/homeserver/OAuthTokenEndpoint.cpp b/src/homeserver/OAuthTokenEndpoint.cpp index 3176c6ad8..068a1e46d 100644 --- a/src/homeserver/OAuthTokenEndpoint.cpp +++ b/src/homeserver/OAuthTokenEndpoint.cpp @@ -6,7 +6,9 @@ #include "merovingian/canonicaljson/Value.hpp" #include "merovingian/core/FormFields.hpp" #include "merovingian/database/OAuthStore.hpp" +#include "merovingian/database/PersistentDevice.hpp" #include "merovingian/database/PersistentOAuthSession.hpp" +#include "merovingian/database/PersistentStore.hpp" #include "merovingian/homeserver/AuthService.hpp" #include "merovingian/homeserver/AuthorizationCodeRedemption.hpp" #include "merovingian/homeserver/AuthorizationCodeStore.hpp" @@ -37,7 +39,6 @@ #include #include #include -#include #include #include #include @@ -53,8 +54,9 @@ namespace constexpr auto status_server_error = std::uint16_t{500U}; constexpr auto first_server_error_status = std::uint16_t{500U}; - // Logs a refused token request: the grant type, the wire error and the client ID when one was sent. Never the - // code, the verifier, a token or any other value the request carried. + // Logs a refused token request: the grant type, the wire error and the client ID once it names a registered client + // (empty before then, so a caller cannot write text of its choosing into the log). Never the code, the verifier, a + // token or any other value the request carried. auto log_refused(std::string_view grant_type, std::string_view error_code, std::string_view client_id) -> void { auto fields = std::vector{ @@ -127,6 +129,23 @@ namespace return *name; } + // The display name the device row holds, or empty when there is no row. + [[nodiscard]] auto stored_display_name(HomeserverRuntime const& runtime, std::string_view user_id, + std::string_view device_id) -> std::string + { + auto name = std::string{}; + database::for_each_user_device(runtime.database.persistent_store, user_id, + [&](database::PersistentDevice const& device) { + if (device.device_id != device_id) + { + return true; + } + name = device.display_name; + return false; + }); + return name; + } + [[nodiscard]] auto authorization_code_grant(ClientServerRuntime& rt, core::FormFields const& fields) -> LocalHttpResponse { @@ -136,9 +155,11 @@ namespace auto const code = fields.find("code"); auto const redirect_uri = fields.find("redirect_uri"); auto const verifier = fields.find("code_verifier"); + // Set once the client ID names a registered client; a refusal before then logs no client ID. + auto registered_client_id = std::string_view{}; auto const refuse = [&](std::uint16_t status, std::string_view error_code, std::string_view description) -> LocalHttpResponse { - log_refused(grant_type, error_code, client_id.value_or(std::string_view{})); + log_refused(grant_type, error_code, registered_client_id); return oauth_error_response(status, error_code, description); }; if (!client_id.has_value() || !code.has_value() || !redirect_uri.has_value() || !verifier.has_value()) @@ -151,6 +172,7 @@ namespace { return refuse(status_bad_request, oauth::error_invalid_client, "The client is not registered."); } + registered_client_id = *client_id; if (!client->has_grant_type(grant_type)) { return refuse(status_bad_request, oauth::error_unauthorized_client, @@ -199,6 +221,14 @@ namespace request.scope = grant.scope; request.display_name = device_display_name(rt, *client); request.created_at_ms = runtime.oauth_codes.next_session_created_at_ms(now_ms); + // Names the row this code is about to produce, so a replay ends it and nothing else (ADR-0792). Recorded + // before the grant commits and at the redemption's own instant, at which the code is held, so nothing that + // can fail follows the commit. Should the grant then fail, the value names no row: every value is + // new, so a replay ends nothing. + if (!runtime.oauth_codes.record_issued_session(*code, request.created_at_ms, now_ms)) + { + return refuse(status_server_error, oauth::error_server_error, "The server could not complete the grant."); + } auto const session = grant_oauth_session(runtime, request); if (!session.ok) { @@ -209,9 +239,6 @@ namespace } return refuse(status_bad_request, oauth::error_invalid_grant, "The session cannot be granted."); } - // Names the row this code produced, so a replay ends it and nothing else. The code is held: nothing above - // released runtime.mutex, so it cannot have expired from under the redemption. - std::ignore = runtime.oauth_codes.record_issued_session(*code, request.created_at_ms, oauth_wall_clock_ms()); remember_signed_in_device(rt, session.user_id, session.device_id, request.display_name, SignedInDevice::new_session); return token_answer(session, oauth_expires_in(runtime), grant.scope); @@ -225,9 +252,11 @@ namespace auto& runtime = rt.homeserver; auto const client_id = fields.find("client_id"); auto const device_code = fields.find("device_code"); + // Set once the client ID names a registered client; a refusal before then logs no client ID. + auto registered_client_id = std::string_view{}; auto const refuse = [&](std::uint16_t status, std::string_view error_code, std::string_view description) -> LocalHttpResponse { - log_refused(grant_type, error_code, client_id.value_or(std::string_view{})); + log_refused(grant_type, error_code, registered_client_id); return oauth_error_response(status, error_code, description); }; // RFC 6749 section 3.1: a parameter sent without a value is treated as omitted. @@ -241,6 +270,7 @@ namespace { return refuse(status_bad_request, oauth::error_invalid_client, "The client is not registered."); } + registered_client_id = *client_id; if (!client->has_grant_type(grant_type)) { return refuse(status_bad_request, oauth::error_unauthorized_client, @@ -312,9 +342,11 @@ namespace auto& runtime = rt.homeserver; auto const client_id = fields.find("client_id"); auto const refresh_token = fields.find("refresh_token"); + // Set once the client ID names a registered client; a refusal before then logs no client ID. + auto registered_client_id = std::string_view{}; auto const refuse = [&](std::uint16_t status, std::string_view error_code, std::string_view description) -> LocalHttpResponse { - log_refused(grant_type, error_code, client_id.value_or(std::string_view{})); + log_refused(grant_type, error_code, registered_client_id); return oauth_error_response(status, error_code, description); }; if (!client_id.has_value() || !refresh_token.has_value()) @@ -327,6 +359,7 @@ namespace { return refuse(status_bad_request, oauth::error_invalid_client, "The client is not registered."); } + registered_client_id = *client_id; if (!client->has_grant_type(grant_type)) { return refuse(status_bad_request, oauth::error_unauthorized_client, @@ -342,8 +375,10 @@ namespace } return refuse(status_bad_request, oauth::error_invalid_grant, "The refresh token is invalid."); } - // As POST /refresh does: the runtime's device list is healed after a restart, nothing is announced. - remember_signed_in_device(rt, session.user_id, session.device_id, session.device_id, + // The runtime's device list is healed after a restart, with the device's stored display name; nothing is + // announced. + remember_signed_in_device(rt, session.user_id, session.device_id, + stored_display_name(runtime, session.user_id, session.device_id), SignedInDevice::refreshed_session); auto const* const row = database::find_oauth_session(runtime.database.persistent_store, session.user_id, session.device_id); diff --git a/tests/integration/test_oauth_log_query_flow.cpp b/tests/integration/test_oauth_log_query_flow.cpp index 6697b34ca..2963d54ab 100644 --- a/tests/integration/test_oauth_log_query_flow.cpp +++ b/tests/integration/test_oauth_log_query_flow.cpp @@ -7,7 +7,9 @@ // level, so the per-request lines (request.received, request.route_not_found, request.rejected) are seen. #include "../support/ConsoleLogCapture.hpp" +#include "../support/OAuthAuthorizationSupport.hpp" #include "../support/OAuthRegistrationSupport.hpp" +#include "../support/OAuthTokenSupport.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" @@ -35,12 +37,13 @@ auto send(hs::ClientServerRuntime& runtime, std::string method, std::string targ std::ignore = hs::handle_client_server_request(runtime, request, /*can_wait=*/false); } -// Lowers the client_server module's log level to debug for the scope, so its per-request lines are written. +// Lowers a module's log level to debug for the scope (client_server by default), so its per-request lines are written. class DebugClientServerLog final { public: - DebugClientServerLog() - : previous_{merovingian::observability::SingleLog::instance().exchange_module_log_level( + explicit DebugClientServerLog(std::string module_name = "client_server") + : module_name_{std::move(module_name)} + , previous_{merovingian::observability::SingleLog::instance().exchange_module_log_level( module_name_, merovingian::observability::LogLevel::debug)} { } @@ -55,7 +58,7 @@ class DebugClientServerLog final auto operator=(DebugClientServerLog&&) -> DebugClientServerLog& = delete; private: - std::string module_name_{"client_server"}; + std::string module_name_; std::optional previous_; }; @@ -97,3 +100,63 @@ SCENARIO("The query of an OAuth 2.0 request is never logged", "[integration][oau } } } + +SCENARIO("A refused token or device request logs the client ID only when it names a registered client", + "[integration][oauth][oauth-log][logging][security]") +{ + GIVEN("a homeserver with the device grant on, a client registered for the code grant only, and the oauth log at " + "debug level") + { + auto config = merovingian::tests::oauth_registration_config(); + config.server().oauth.device_grant_enabled = true; + auto started = hs::start_client_server(std::move(config)); + REQUIRE(started.started); + auto& runtime = started.runtime; + auto const code_only = + merovingian::tests::register_oauth_web_client(runtime, R"(,"grant_types":["authorization_code"])"); + REQUIRE_FALSE(code_only.empty()); + + WHEN("an unregistered client ID is sent to every token grant and to the device endpoint, and the registered " + "client asks for a grant it does not hold") + { + auto const debug_module = DebugClientServerLog{"oauth"}; + auto const capture = merovingian::tests::ConsoleLogCapture{merovingian::observability::LogLevel::debug}; + constexpr auto probe = std::string_view{"UNREGISTEREDPROBE"}; + auto const refresh = merovingian::tests::post_oauth_form( + runtime, merovingian::tests::oauth_token_path, + merovingian::tests::refresh_grant_fields(probe, std::string(64U, 'a'))); + auto const code = merovingian::tests::post_oauth_form( + runtime, merovingian::tests::oauth_token_path, + merovingian::tests::code_grant_fields(probe, std::string(64U, 'f'))); + auto const device_grant = + merovingian::tests::post_oauth_form(runtime, merovingian::tests::oauth_token_path, + { + {"grant_type", "urn:ietf:params:oauth:grant-type:device_code"}, + {"client_id", std::string{probe}}, + {"device_code", std::string(64U, 'd')}, + }); + auto const device = merovingian::tests::post_oauth_form(runtime, "/_merovingian/oauth2/device", + { + {"client_id", std::string{probe}}, + {"scope", "openid" }, + }); + auto const registered = merovingian::tests::post_oauth_form( + runtime, merovingian::tests::oauth_token_path, + merovingian::tests::refresh_grant_fields(code_only, std::string(64U, 'a'))); + auto const text = capture.text(); + + THEN("every refusal is logged, the unregistered ID never, and the registered one is") + { + for (auto const* response : {&refresh, &code, &device_grant, &device}) + { + CHECK(response->status == 400U); + } + CHECK(registered.status == 400U); + CHECK(text.find("oauth.token.refused") != std::string::npos); + CHECK(text.find("oauth.device.refused") != std::string::npos); + CHECK(text.find(code_only) != std::string::npos); + CHECK(text.find(probe) == std::string::npos); + } + } + } +} diff --git a/tests/integration/test_oauth_token_flow.cpp b/tests/integration/test_oauth_token_flow.cpp index 38539355d..c1ca6d80d 100644 --- a/tests/integration/test_oauth_token_flow.cpp +++ b/tests/integration/test_oauth_token_flow.cpp @@ -19,11 +19,14 @@ #include "merovingian/database/PersistentStore.hpp" #include "merovingian/database/PersistentStoreBackend.hpp" #include "merovingian/homeserver/AuthService.hpp" +#include "merovingian/homeserver/AuthorizationCodeRedemption.hpp" +#include "merovingian/homeserver/AuthorizationCodeStore.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" #include "merovingian/homeserver/HomeserverRuntime.hpp" #include "merovingian/homeserver/LocalHttpRequest.hpp" #include "merovingian/homeserver/LocalHttpResponse.hpp" +#include "merovingian/homeserver/OAuthClock.hpp" #include @@ -34,6 +37,7 @@ #include #include #include +#include #include #include @@ -345,6 +349,8 @@ SCENARIO("A grant that cannot be stored leaves nothing, and an account that cann { db::force_next_persist_failures(rt.homeserver.database.persistent_store, 1U); auto const response = post_oauth_form(rt, oauth_token_path, code_grant_fields(fixture.client_id, code)); + // The session a replay would end was named before the commit, so no bookkeeping follows it. + auto const replay = rt.homeserver.oauth_codes.redeem(code, hs::oauth_wall_clock_ms()); THEN("the answer is server_error and no device, token or session row exists") { REQUIRE(response.status == 500U); @@ -352,6 +358,8 @@ SCENARIO("A grant that cannot be stored leaves nothing, and an account that cann CHECK_FALSE(holds_device(rt, oauth_test_device)); CHECK(oauth_row(rt, oauth_test_device) == nullptr); CHECK(audit_count(rt, "oauth.session.granted") == 0U); + CHECK(replay.outcome == hs::AuthorizationCodeRedemption::Outcome::replayed); + CHECK(replay.session_created_at_ms.has_value()); } } WHEN("the account is locked between the consent and the token request") @@ -439,6 +447,23 @@ SCENARIO("The refresh grant rotates an OAuth session's tokens and only an OAuth CHECK(oauth_row(rt, oauth_test_device) != nullptr); } } + WHEN("the runtime's device list lost the device, as after a restart, and the client refreshes") + { + std::erase_if(rt.devices, [](auto const& device) { + return device.user_id == alice_id && device.device_id == oauth_test_device; + }); + auto const rotated = read_token_answer( + post_oauth_form(rt, oauth_token_path, refresh_grant_fields(fixture.client_id, session.refresh_token))); + auto const healed = std::ranges::find_if(rt.devices, [](auto const& device) { + return device.user_id == alice_id && device.device_id == oauth_test_device; + }); + THEN("the device is listed again with its stored display name, not its device ID") + { + REQUIRE(rotated.ok); + REQUIRE(healed != rt.devices.end()); + CHECK(healed->display_name == "Test App"); + } + } WHEN("another registered client presents the refresh token") { auto const other_client = register_oauth_web_client( From b2362896b390db7079302224a0fbe32f99c72f38 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:21:06 +0000 Subject: [PATCH 27/42] Answer an exception escaping one of the server's own pages with an error page (ADR-0810) The dispatch boundary's final catch now asks request_serves_page whether the request was routed to the authorisation, device link or account page, or to an SSO redirect that hands off to them, judged on the same path, method and configuration the routes match on. Such a request gets a fixed 500 HTML error page under the pages' own headers and no CORS header; every other request keeps the 500 M_UNKNOWN JSON answer. Amends ADR-0803. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 + ...ption-with-a-500-and-logs-only-its-type.md | 3 + ...ges-is-answered-with-a-fixed-error-page.md | 43 +++++++++++++ docs/adr/index.md | 1 + docs/http-transport.md | 5 +- src/homeserver/AGENTS.md | 3 + src/homeserver/ClientServerRuntime.cpp | 32 ++++++++++ .../test_request_exception_flow.cpp | 64 +++++++++++++++++++ 8 files changed, 152 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0810-an-exception-escaping-one-of-the-server-s-own-pages-is-answered-with-a-fixed-error-page.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c5c3a7ad..0d2618822 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -104,6 +104,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) keys succeeds without it, and an application service never needs it, as the spec says (ADR-0794). * The code grant names the session a replayed code ends before it commits, so no step that can fail follows the commit (ADR-0792). +* An exception escaping the authorisation, device link, account or SSO hand-off page is answered with an HTML error + page under the pages' headers, not JSON (ADR-0810). * The OAuth refresh grant lists a device after a restart with its stored display name, not its device ID. ## Release notes diff --git a/docs/adr/0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md b/docs/adr/0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md index df36c308e..ec211672b 100644 --- a/docs/adr/0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md +++ b/docs/adr/0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md @@ -6,6 +6,9 @@ Technical Story: part 0 of the device authorization grant work (plan P11 in `docs/todos/oauth-2-0-api.md`). +Amended by [ADR-0810](0810-an-exception-escaping-one-of-the-server-s-own-pages-is-answered-with-a-fixed-error-page.md): +a request routed to one of the server's own HTML pages is answered with a fixed error page instead of the JSON 500. + ## Context and Problem Statement Handlers return errors as values, but a handler can still throw: `std::bad_alloc`, a standard library precondition, a diff --git a/docs/adr/0810-an-exception-escaping-one-of-the-server-s-own-pages-is-answered-with-a-fixed-error-page.md b/docs/adr/0810-an-exception-escaping-one-of-the-server-s-own-pages-is-answered-with-a-fixed-error-page.md new file mode 100644 index 000000000..b60ec9a11 --- /dev/null +++ b/docs/adr/0810-an-exception-escaping-one-of-the-server-s-own-pages-is-answered-with-a-fixed-error-page.md @@ -0,0 +1,43 @@ +# An exception escaping one of the server's own pages is answered with a fixed error page + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: review finding 6 on `feature/oauth-20-v110`. Amends +[ADR-0803](0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md). + +## Context and Problem Statement + +ADR-0803 answers every exception a client-server handler lets escape with a JSON `500 M_UNKNOWN` and the CORS headers. +A browser that opened the authorisation page, the device link page, the account page or a legacy SSO redirect that +hands off to those pages (ADR-0802) then shows raw JSON, served without the pages' Content-Security-Policy and framing +headers (ADR-0772, ADR-0784) and with a CORS header the pages never carry (ADR-0785). What should a page path answer? + +## Considered Options + +* A fixed HTML error page for the page paths, the JSON answer for every other path. +* The JSON answer everywhere (ADR-0803 as it stood). + +## Decision Outcome + +Chosen option: the fixed page. When the escaped exception came from a request the dispatcher routes to a page +(`request_serves_page` in `ClientServerRuntime.cpp`: `GET` or `POST` of `/_merovingian/oauth2/authorize` or +`/_merovingian/account` with the OAuth 2.0 API on, of `/_merovingian/oauth2/link` with the device grant on too, and +`GET` of `/_matrix/client/v3/login/sso/redirect` and `/_matrix/client/v3/login/sso/redirect/{idpId}` while the hand-off +is on), the answer is `oauth_error_page_response(500, ...)`: `page = true`, `oauth::page_headers()`, no CORS header, +and a fixed text that holds nothing of the exception. The test matches on the same path, method and configuration as +the routes, so a page path and its route cannot disagree. Every other path, the OAuth API endpoints that answer JSON +included, keeps ADR-0803's answer. The log line is unchanged. + +### Positive Consequences + +* A browser gets a page it can show, under the same headers as every other page. + +### Negative Consequences + +* `request_serves_page` restates the page routes; a new page route must be added to it. + +## Links + +* Amends [ADR-0803](0803-the-client-server-dispatch-boundary-answers-an-escaped-exception-with-a-500-and-logs-only-its-type.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index a0378a7ce..dc44ff037 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -691,3 +691,4 @@ * [0807 - An OAuth sign-in carries the credential stamp of its password check and ends when it changes](0807-an-oauth-sign-in-carries-the-credential-stamp-of-its-password-check-and-ends-when-it-changes.md) * [0808 - An OAuth session row ends with the last credential of its device](0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md) * [0809 - A cross-signing reset approval is bound to the OAuth device that asked for it](0809-a-cross-signing-reset-approval-is-bound-to-the-oauth-device-that-asked-for-it.md) +* [0810 - An exception escaping one of the server's own pages is answered with a fixed error page](0810-an-exception-escaping-one-of-the-server-s-own-pages-is-answered-with-a-fixed-error-page.md) diff --git a/docs/http-transport.md b/docs/http-transport.md index 930461620..fc856de31 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -586,7 +586,10 @@ An exception a client-server handler lets escape is answered at the dispatch bou with `500 M_UNKNOWN` and the fixed text `internal server error`, the request's CORS headers, and a kept connection, whichever pool ran the request (ADR-0803). The runtime lock is released by the unwinding and taken afresh only to build the answer. A `std::overflow_error` from the sync stream counter keeps its answer, `sync stream counter -exhausted` (ADR-0315). See `observability-audit.md` for the log line, which never carries the exception's message. +exhausted` (ADR-0315). A request routed to one of the server's own HTML pages (the authorisation, device link and +account pages, and the legacy SSO redirects while they hand off to them) is answered instead with a fixed 500 error +page under the pages' own headers and no CORS header (ADR-0810). See `observability-audit.md` for the log line, which +never carries the exception's message. The public client-server and internal local-router entry points also preflight the **path portion**, before the first `?`, for literal NUL and diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 8eaf54436..41272d85c 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -90,6 +90,9 @@ answers `500 M_UNKNOWN` (`internal server error`) and logs as `request.exception and `core::current_exception_type_name()`. Never log `what()` of a request's exception, and never add a catch-all in a handler or a transport call site in its place: handlers still return errors as values, and this is the backstop. `HomeserverRuntime::test_client_request_hook` is the test seam that makes a request throw. +A request `request_serves_page` names (the authorisation, device link and account pages, and the SSO redirects while +they hand off) gets a fixed HTML error page instead (`oauth_error_page_response`, ADR-0810); a new page route must be +added there too. ## Architecture boundaries diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index fc23ec6d9..031a388a7 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -107,6 +107,7 @@ #include "merovingian/homeserver/OAuthClientRegistration.hpp" #include "merovingian/homeserver/OAuthClock.hpp" #include "merovingian/homeserver/OAuthDeviceAuthorization.hpp" +#include "merovingian/homeserver/OAuthPageResponse.hpp" #include "merovingian/homeserver/OAuthRevocation.hpp" #include "merovingian/homeserver/OAuthTokenEndpoint.hpp" #include "merovingian/homeserver/OperationResult.hpp" @@ -22755,6 +22756,28 @@ auto media_upload_authentication_refusal(ClientServerRuntime& rt, LocalHttpReque return dispatch_err(head, rt, 401U, errcode, "unauthenticated").response; } +// Whether the request was routed to one of the server's own HTML pages: the authorisation, device link and account +// pages, and the legacy SSO redirects while they hand off to those pages (ADR-0802). Judged on the same path, method +// and configuration the routes match on, so an exception escaping a page handler is answered with a page (ADR-0803). +static auto request_serves_page(ClientServerRuntime const& rt, LocalHttpRequest const& req, std::string_view path) + -> bool +{ + if (req.method != "GET" && req.method != "POST") + { + return false; + } + auto const& oauth_config = rt.homeserver.config.server().oauth; + if (oauth_config.enabled && (path == oauth::authorize_path.view() || path == oauth::account_path.view() || + (path == oauth::link_path.view() && oauth_config.device_grant_enabled))) + { + return true; + } + auto constexpr sso_redirect = std::string_view{"/_matrix/client/v3/login/sso/redirect"}; + return req.method == "GET" && legacy_login_hand_off_enabled(oauth_config) && + (path == sso_redirect || + (path.starts_with(sso_redirect) && path.substr(sso_redirect.size()).starts_with('/'))); +} + auto handle_client_server_request(ClientServerRuntime& rt, LocalHttpRequest const& req, bool can_wait) -> DispatchResult { return handle_client_server_request(rt, req, ClientServerDispatchOptions{.can_wait = can_wait}); @@ -22807,6 +22830,15 @@ auto handle_client_server_request(ClientServerRuntime& rt, LocalHttpRequest cons {"type", core::current_exception_type_name(), false} }, observability::LogEventSeverity::error); + if (request_serves_page(rt, req, path)) + { + // A browser is on the other end: a fixed page with the pages' own headers, and no CORS header (ADR-0785). + return DispatchResult{DispatchResult::Status::complete, + oauth_error_page_response(500U, oauth::HtmlText{"Something went wrong"}, + oauth::HtmlText{"The server could not answer this page. " + "Try again later."}), + {}}; + } result = dispatch_err(req, rt, 500U, "M_UNKNOWN", "internal server error"); apply_cors_headers(req, result.response, rt.cors); return result; diff --git a/tests/integration/test_request_exception_flow.cpp b/tests/integration/test_request_exception_flow.cpp index d580dd5cc..ab32c1f00 100644 --- a/tests/integration/test_request_exception_flow.cpp +++ b/tests/integration/test_request_exception_flow.cpp @@ -7,6 +7,7 @@ #include "../support/ConsoleLogCapture.hpp" #include "../support/InMemoryDatabaseConfig.hpp" #include "../support/MasterKey.hpp" +#include "../support/OAuthRegistrationSupport.hpp" #include "merovingian/config/ClientRateLimitsConfig.hpp" #include "merovingian/config/Config.hpp" #include "merovingian/config/ListenersConfig.hpp" @@ -15,9 +16,11 @@ #include "merovingian/config/ServerConfig.hpp" #include "merovingian/homeserver/ClientServerRuntime.hpp" #include "merovingian/homeserver/ClientServerStartResult.hpp" +#include "merovingian/homeserver/LocalHttpRequest.hpp" #include +#include #include #include #include @@ -198,3 +201,64 @@ SCENARIO("An exception a client-server handler lets escape is answered with a 50 } } } + +SCENARIO("An exception escaping one of the server's own pages is answered with a page", + "[homeserver][request-exception][oauth][oauth-page]") +{ + GIVEN("a runtime with the OAuth 2.0 API and the device grant on, whose every request throws") + { + auto config = merovingian::tests::oauth_registration_config(); + config.server().oauth.device_grant_enabled = true; + auto started = merovingian::homeserver::start_client_server(std::move(config)); + REQUIRE(started.started); + auto& runtime = started.runtime; + runtime.rate_limit_engine.reset(); + runtime.homeserver.test_client_request_hook = [](std::string_view) { + throw std::runtime_error{std::string{secret_text}}; + }; + + WHEN("a browser opens each page: authorisation, device link, account, and the SSO redirects") + { + auto const targets = std::array{ + std::string_view{"/_merovingian/oauth2/authorize?client_id=x"}, + std::string_view{"/_merovingian/oauth2/link"}, + std::string_view{"/_merovingian/account?action=org.matrix.profile"}, + std::string_view{"/_matrix/client/v3/login/sso/redirect?redirectUrl=https%3A%2F%2Fapp.example.com%2F"}, + std::string_view{ + "/_matrix/client/v3/login/sso/redirect/oidc?redirectUrl=https%3A%2F%2Fapp.example.com%2F"}, + }; + THEN("each answer is a 500 HTML page with the pages' headers, no CORS header and nothing of the message") + { + for (auto const target : targets) + { + INFO(target); + auto const answered = + merovingian::homeserver::handle_client_server_request(runtime, {"GET", std::string{target}}); + REQUIRE(answered.response.status == 500U); + CHECK(answered.response.page); + CHECK(merovingian::tests::response_header(answered.response, "Content-Type") + .starts_with("text/html")); + CHECK_FALSE( + merovingian::tests::response_header(answered.response, "Content-Security-Policy").empty()); + CHECK( + merovingian::tests::response_header(answered.response, "Access-Control-Allow-Origin").empty()); + CHECK_FALSE(contains(answered.response.body, "M_UNKNOWN")); + CHECK_FALSE(contains(answered.response.body, secret_text)); + } + REQUIRE(lock_is_free_for_another_thread(runtime)); + } + } + WHEN("an OAuth API endpoint that answers JSON throws") + { + auto request = merovingian::homeserver::LocalHttpRequest{"POST", "/_merovingian/oauth2/token"}; + request.headers.push_back({"Content-Type", "application/x-www-form-urlencoded"}); + auto const answered = merovingian::homeserver::handle_client_server_request(runtime, request); + THEN("it keeps the JSON 500 M_UNKNOWN") + { + REQUIRE(answered.response.status == 500U); + CHECK_FALSE(answered.response.page); + CHECK(contains(answered.response.body, R"("errcode":"M_UNKNOWN")")); + } + } + } +} From dc71e3b767862cc1188769ac766c98555b3b6ac4 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:21:58 +0000 Subject: [PATCH 28/42] Tighten the OAuth URI, client metadata and hand-off rules (ADR-0811) - The URI reader takes an IPv6 host only in the RFC 3986 IPv6address grammar, and csp_source() gives a bracketed IPv6 host its scheme alone, since the CSP host-source grammar cannot name one (ADR-0811, amending ADR-0772). - The hand-off accepts a private-use scheme only with no authority. - A client URI host whose last label ends in a number by the WHATWG rule is refused. - client_name refuses the soft hyphen, the Mongolian vowel separator, the zero-width characters, the word joiner and invisible operators, the BOM, the interlinear annotation characters and the tag characters. - The hand-off confirmation page shows the destination's port. - The redirect URI fuzz target aborts when csp_source() holds a space, ';', ',' or a quote, when a match differs from the request, or when a validated URI does not match itself. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 9 ++ ...t-metadata-rules-and-its-canonical-form.md | 6 ++ ...-names-only-a-validated-redirect-origin.md | 3 + ...firms-and-mints-a-30-second-login-token.md | 4 + ...get-adds-only-its-scheme-to-form-action.md | 47 +++++++++ docs/adr/index.md | 1 + docs/auth-identity.md | 5 +- docs/security-coding-rules.md | 3 +- include/merovingian/oauth/DisplayText.hpp | 6 +- include/merovingian/oauth/ParsedUri.hpp | 3 +- src/oauth/AGENTS.md | 6 +- src/oauth/AuthorizationPages.cpp | 9 +- src/oauth/ClientUri.cpp | 29 +++++- src/oauth/DisplayText.cpp | 92 ++++++++++++------ src/oauth/HandOffRedirect.cpp | 5 +- src/oauth/ParsedUri.cpp | 95 ++++++++++++++++++- tests/fuzz/AGENTS.md | 2 + tests/fuzz/fuzz_oauth_redirect_uri.cpp | 50 +++++++++- tests/unit/test_oauth_client_metadata.cpp | 74 +++++++++++++++ tests/unit/test_oauth_hand_off_redirect.cpp | 34 ++++++- tests/unit/test_oauth_page.cpp | 7 +- tests/unit/test_oauth_redirect_uri.cpp | 88 ++++++++++++++++- 22 files changed, 519 insertions(+), 59 deletions(-) create mode 100644 docs/adr/0811-a-bracketed-ipv6-redirect-target-adds-only-its-scheme-to-form-action.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0d2618822..29d2b73f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -91,6 +91,12 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) `m.oauth` URL now carries `device_id` (ADR-0809). * A refused OAuth token or device request logs its `client_id` only when it names a registered client, so a caller cannot write text of its choosing into the log. +* A client URI host whose last label is a number to a browser (`app.0x7f`, the WHATWG rule) is refused (ADR-0771). +* A client name holding an invisible character (soft hyphen, zero-width characters, word joiner, BOM, tag characters + and others) is refused, so two names cannot look alike (ADR-0771). +* The legacy SSO hand-off refuses a private-use scheme address with an authority, such as `com.example.app://host/`, + which an allowlisted bare scheme never named (ADR-0802). +* The URI reader takes an IPv6 host only in the RFC 3986 grammar, not any run of hex digits, `:` and `.` (ADR-0811). ## Bug fixes @@ -107,6 +113,9 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * An exception escaping the authorisation, device link, account or SSO hand-off page is answered with an HTML error page under the pages' headers, not JSON (ADR-0810). * The OAuth refresh grant lists a device after a restart with its stored display name, not its device ID. +* A native client on an `http://[::1]` redirect URI completes its sign-in: CSP cannot name an IPv6 host, so + `form-action` gets `http:` for it (ADR-0811). +* The hand-off confirmation page shows the destination's port, so two loopback applications are told apart. ## Release notes diff --git a/docs/adr/0771-oauth-client-metadata-rules-and-its-canonical-form.md b/docs/adr/0771-oauth-client-metadata-rules-and-its-canonical-form.md index 0e0df2af2..fd29d40e8 100644 --- a/docs/adr/0771-oauth-client-metadata-rules-and-its-canonical-form.md +++ b/docs/adr/0771-oauth-client-metadata-rules-and-its-canonical-form.md @@ -4,6 +4,12 @@ * Deciders: James Chapman * Date: 2026-11-15 +Amended 2026-11-16 (review finding 10): the last label is refused under the WHATWG URL Standard's "ends in a number" +rule, all digits or `0x`/`0X` followed only by hex digits (`app.0x7f`), since a browser reads such a host as an IPv4 +address. +Amended 2026-11-16 (review finding 11): a displayed name also refuses the invisible characters that let two names +look alike: U+00AD, U+180E, U+200B to U+200D, U+2060 to U+2064, U+FEFF, U+FFF9 to U+FFFB and U+E0000 to U+E007F. + ## Context and Problem Statement Client registration is unauthenticated (spec "Client registration", RFC 7591). The spec fixes some rules (`web` and diff --git a/docs/adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md b/docs/adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md index dc0962bb7..b5a867900 100644 --- a/docs/adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md +++ b/docs/adr/0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md @@ -4,6 +4,9 @@ * Deciders: James Chapman * Date: 2026-11-15 +Amended by [ADR-0811](0811-a-bracketed-ipv6-redirect-target-adds-only-its-scheme-to-form-action.md): a matched +redirect target on a bracketed IPv6 host adds only its scheme, `http:`, which CSP can name. + ## Context and Problem Statement [ADR-0763](0763-the-authentication-pages-are-built-into-the-binary-without-javascript.md) requires that text reaches a diff --git a/docs/adr/0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md b/docs/adr/0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md index 2f4fad8ba..b73baf74d 100644 --- a/docs/adr/0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md +++ b/docs/adr/0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md @@ -6,6 +6,10 @@ Technical Story: plan P10 in `docs/todos/oauth-2-0-api.md`, the hand-off for clients that know only the legacy API. +Amended 2026-11-16 (review finding 9): a private-use scheme address must also have no authority +(`com.example.app:/cb`, never `com.example.app://host/cb`), as RFC 8252 section 7.1 writes one, so an allowlisted bare +scheme cannot reach an authority it never named. + ## Context and Problem Statement With the OAuth 2.0 API on, the spec ("OAuth 2.0 aware clients", Server behaviour) requires the legacy `m.login.sso` diff --git a/docs/adr/0811-a-bracketed-ipv6-redirect-target-adds-only-its-scheme-to-form-action.md b/docs/adr/0811-a-bracketed-ipv6-redirect-target-adds-only-its-scheme-to-form-action.md new file mode 100644 index 000000000..c8d0c3062 --- /dev/null +++ b/docs/adr/0811-a-bracketed-ipv6-redirect-target-adds-only-its-scheme-to-form-action.md @@ -0,0 +1,47 @@ +# A bracketed IPv6 redirect target adds only its scheme to form-action + +* Status: accepted +* Deciders: James Chapman +* Date: 2026-11-16 + +Technical Story: review finding 8 on `feature/oauth-20-v110`. Amends +[ADR-0772](0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md). + +## Context and Problem Statement + +`page_headers(target)` adds the matched redirect URI's origin to `form-action` (ADR-0772), as `ParsedUri::csp_source()` +writes it. A native client may register a loopback redirect URI on `[::1]` (RFC 8252 section 7.3), but the CSP +host-source grammar (CSP3 section 2.3.1) has no form for an IPv6 literal: `http://[::1]:5000` is not a source, a +browser drops it, and Chromium then blocks the redirect after the consent form, so the sign-in never completes. Which +source names such a target? + +## Considered Options + +* The scheme alone, `http:`. +* No source: the IPv6 loopback redirect is left blocked. +* The bracketed text anyway. + +## Decision Outcome + +Chosen option: the scheme alone. `csp_source()` returns `scheme:` for a host that starts with `[`, as it does for a +URI with no authority. A redirect URI with an IPv6 host passes `match_redirect_uri` only as a native loopback URI, so +the source is only ever `http:` after a matched loopback target. The bracketed text was rejected because a browser +ignores it, so it blocks the redirect as surely as no source; leaving it blocked was rejected because RFC 8252 names +`[::1]` as a redirect a native client may use. + +At the same time `ParsedUri::read` takes an IPv6 host only in the RFC 3986 `IPv6address` grammar (eight 16-bit pieces, +or fewer with one `::`, the last two possibly a dotted IPv4 address with no leading zero), not any run of hex digits, +`:` and `.`; no zone identifier and no `IPvFuture`. + +### Positive Consequences + +* A native client on `[::1]` completes its sign-in. + +### Negative Consequences + +* For that one page, `form-action` allows a form post's redirect to any `http:` origin. The page's only form posts to + `'self'`, and the redirect target is the matched loopback URI, so nothing on the page uses the wider source. + +## Links + +* Amends [ADR-0772](0772-page-text-is-escaped-by-type-and-the-page-policy-names-only-a-validated-redirect-origin.md) diff --git a/docs/adr/index.md b/docs/adr/index.md index dc44ff037..5fdd9e093 100644 --- a/docs/adr/index.md +++ b/docs/adr/index.md @@ -692,3 +692,4 @@ * [0808 - An OAuth session row ends with the last credential of its device](0808-an-oauth-session-row-ends-with-the-last-credential-of-its-device.md) * [0809 - A cross-signing reset approval is bound to the OAuth device that asked for it](0809-a-cross-signing-reset-approval-is-bound-to-the-oauth-device-that-asked-for-it.md) * [0810 - An exception escaping one of the server's own pages is answered with a fixed error page](0810-an-exception-escaping-one-of-the-server-s-own-pages-is-answered-with-a-fixed-error-page.md) +* [0811 - A bracketed IPv6 redirect target adds only its scheme to form-action](0811-a-bracketed-ipv6-redirect-target-adds-only-its-scheme-to-form-action.md) diff --git a/docs/auth-identity.md b/docs/auth-identity.md index 329ca56e1..b7f2cd81e 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -1288,10 +1288,11 @@ the spec's "Account management" names: `account_management_uri` and all six `org - **Hand-off (P10, ADR-0802).** With both APIs on (`legacy_login_hand_off_enabled`), `GET /login` adds `m.login.sso` with `oauth_aware_preferred: true` (and `m.login.token` if get_token did not), and both SSO redirects call `handle_login_hand_off` (`OAuthAuthorization.cpp`). `redirectUrl` must pass `oauth::hand_off_redirect_target` - (`https`; `http` on a loopback host; a private-use scheme; the allowlist when set), else a 400 page. A + (`https`; `http` on a loopback host; a private-use scheme with no authority; the allowlist when set), else a 400 page. A `PendingAuthorisation` of kind `login_token_hand_off` is started by the same `start_sign_in` as `/authorize`, and its forms post there: the shared cookie, Origin check, pending cap, login throttle and account creation. After the - password a confirmation page (`page_headers(target)`) names the account and the destination. `approve` re-reads the + password a confirmation page (`page_headers(target)`) names the account and the destination (its host and port, or + the private-use scheme). `approve` re-reads the address, runs `account_sign_in_gate` and the credential stamp check (ADR-0807), mints 32 random bytes into `LoginTokenStore` for `hand_off_login_token_lifetime_ms` (30 s, under the get_token caps), audits `auth.login_token.issued` with reason `hand_off`, and answers 303 to `oauth::hand_off_return_address` (old `loginToken` parameters removed). `deny` answers diff --git a/docs/security-coding-rules.md b/docs/security-coding-rules.md index 6020c044e..57cdd23fe 100644 --- a/docs/security-coding-rules.md +++ b/docs/security-coding-rules.md @@ -1024,7 +1024,8 @@ quickly finding everything a given `AGENTS.md` file contributed. Source: `src/oauth/AGENTS.md`. - **HTML is built only by `oauth::Page`, whose parts accept only `HtmlText` (escaped) or compile-time values; every - page carries `page_headers()`, and only a matched redirect URI's origin is added to `form-action`.** + page carries `page_headers()`, and only a matched redirect URI's origin is added to `form-action` (its scheme alone + for a bracketed IPv6 loopback host, which CSP cannot name; ADR-0811).** Why: the pages take passwords and show text an unauthenticated client chose; one unescaped value is script injection on the login page (CWE-79), and a policy source built from raw input can add directives (CWE-116). Source: `src/oauth/AGENTS.md`. diff --git a/include/merovingian/oauth/DisplayText.hpp b/include/merovingian/oauth/DisplayText.hpp index 22702a459..9df09fbf9 100644 --- a/include/merovingian/oauth/DisplayText.hpp +++ b/include/merovingian/oauth/DisplayText.hpp @@ -11,9 +11,11 @@ namespace merovingian::oauth // Whether `text` may be shown to a user: valid UTF-8 holding no control character and no character that changes // how the text around it is displayed. Refused: C0 controls and DEL (U+0000 to U+001F, U+007F), C1 controls (U+0080 -// to U+009F), the line and paragraph separators (U+2028, U+2029) and the bidirectional formatting characters +// to U+009F), the line and paragraph separators (U+2028, U+2029), the bidirectional formatting characters // (U+061C, U+200E, U+200F, U+202A to U+202E, U+2066 to U+2069), which can make a client's name read as another -// (ADR-0771). Nothing is stripped or replaced: the caller refuses the text. +// (ADR-0771), and the invisible characters that let two names look alike: U+00AD, U+180E, U+200B to U+200D, U+2060 +// to U+2064, U+FEFF, U+FFF9 to U+FFFB and the tag characters U+E0000 to U+E007F. Nothing is stripped or replaced: +// the caller refuses the text. [[nodiscard]] auto display_text_is_safe(std::string_view text) noexcept -> bool; } // namespace merovingian::oauth diff --git a/include/merovingian/oauth/ParsedUri.hpp b/include/merovingian/oauth/ParsedUri.hpp index ea6423ec6..828138829 100644 --- a/include/merovingian/oauth/ParsedUri.hpp +++ b/include/merovingian/oauth/ParsedUri.hpp @@ -62,7 +62,8 @@ class ParsedUri final [[nodiscard]] auto query() const noexcept -> std::string const&; // The origin as a Content-Security-Policy source: `scheme://host` or `scheme://host:port` with an authority, - // `scheme:` without one. Built from the fields above only, so it holds no space, `;`, `,` or quote. + // `scheme:` without one or with a bracketed IPv6 host, which CSP cannot name (ADR-0811). Built from the fields + // above only, so it holds no space, `;`, `,` or quote. [[nodiscard]] auto csp_source() const -> std::string; private: diff --git a/src/oauth/AGENTS.md b/src/oauth/AGENTS.md index 54d032fe0..bfadf9cb2 100644 --- a/src/oauth/AGENTS.md +++ b/src/oauth/AGENTS.md @@ -13,7 +13,7 @@ Pure functions and value types for the built-in OAuth 2.0 API | `Pkce.cpp` | `pkce_challenge_is_valid`, `pkce_verifier_is_valid`, `pkce_s256_matches`: RFC 7636 with `S256` only, compared in constant time | | `ScopeParser.cpp` | `parse_scope` and `oauth_device_id_is_valid`: the API token and exactly one device token, unknown tokens dropped (ADR-0769) | | `ParsedUri.cpp` | `ParsedUri::read`: the strict URI reader for every address a client supplies and every page link (ADR-0770) | -| `ClientUri.cpp` | `ClientUri::read`: `https` on a DNS name of two or more labels (ADR-0771) | +| `ClientUri.cpp` | `ClientUri::read`: `https` on a DNS name of two or more labels whose last label does not end in a number by the WHATWG rule (all digits, or `0x` and hex digits) (ADR-0771) | | `RedirectUriRules.cpp` | `validate_redirect_uri` (registration), `match_redirect_uri` (authorisation and token requests), `https_uri_is_on_client_host` | | `ClientMetadata.cpp` | `ClientMetadata::validate`, `to_json`, `canonical_bytes`: RFC 7591 registration rules (ADR-0771) | | `HtmlText.cpp`, `HtmlLiteral.hpp`, `HtmlName.hpp`, `PagePath.hpp` | Page text: escaped at run time, or fixed and checked at compile time (ADR-0772) | @@ -27,11 +27,11 @@ Pure functions and value types for the built-in OAuth 2.0 API | `AccountPages.cpp`, `AccountPageFrame.hpp`, `AccountDeviceRow.hpp`, `AccountSignInInput.hpp` | The account pages of `/_merovingian/account` (ADR-0796): sign-in, overview, devices, one device, device sign-out, password, deactivation, cross-signing reset and result pages; the six spec actions (`account_management_actions`, `account_management_action`, `account_action_takes_device`), `account_action_address` (every link, the post-sign-in redirect and the `m.oauth` URL), and the form field and action names. Every signed-in form carries `form_token`; a page whose token cannot be shown holds no form | | `UserCode.cpp` | The device authorization grant's user code (ADR-0805): `user_code_from_bytes` (rejection sampling over `BCDFGHJKLMNPQRSTVWXZ`), `normalise_user_code` (the rule 2 exception below) and `display_user_code` (`XXXX-XXXX`) | | `FormPostOrigin.cpp` | `form_post_origin`, `form_post_origin_is_accepted`: a page's form post must name this server's origin exactly, and `Sec-Fetch-Site`, when sent, `same-origin` (ADR-0784) | -| `HandOffRedirect.cpp` | `hand_off_redirect_target` (`https`, loopback `http` or a private-use scheme, then the allowlist) and `hand_off_return_address` (every `loginToken` removed, the new one added) for the legacy SSO redirect's hand-off (ADR-0802) | +| `HandOffRedirect.cpp` | `hand_off_redirect_target` (`https`, loopback `http` or a private-use scheme with no authority, then the allowlist) and `hand_off_return_address` (every `loginToken` removed, the new one added) for the legacy SSO redirect's hand-off (ADR-0802) | | `HandOffAllowlist.cpp` | `hand_off_allowlist_entry_error`, `hand_off_allowlist_error`: an https origin or a bare private-use scheme, at most 32, each once (ADR-0774) | | `FormContentType.cpp` | `api_form_content_type_is_accepted`: the token and revocation endpoints take `application/x-www-form-urlencoded` only, with at most a `charset=utf-8` parameter | | `AccessTokenLifetime.hpp` | `access_token_lifetime_ms` (the configured lifetime, or one hour when it is 0: an OAuth access token always expires, ADR-0791) and `expires_in_seconds` | -| `DisplayText.cpp`, `AsciiCase.cpp` | Module-internal: `display_text_is_safe` (no control or bidirectional formatting character) and `ascii_lower` | +| `DisplayText.cpp`, `AsciiCase.cpp` | Module-internal: `display_text_is_safe` (no control, bidirectional formatting or invisible character, by code point) and `ascii_lower` | ## Rules diff --git a/src/oauth/AuthorizationPages.cpp b/src/oauth/AuthorizationPages.cpp index 865e4bf9c..dd14b2389 100644 --- a/src/oauth/AuthorizationPages.cpp +++ b/src/oauth/AuthorizationPages.cpp @@ -107,7 +107,14 @@ namespace auto const web = scheme == "https" || scheme == "http"; if (web && target.has_authority()) { - return shown(target.host(), "an address that cannot be shown"); + // The port when one is written: `localhost:8080` and `localhost:9090` are different applications. + auto host = target.host(); + if (target.port().has_value()) + { + host.push_back(':'); + host.append(std::to_string(*target.port())); + } + return shown(host, "an address that cannot be shown"); } auto text = target.scheme(); text.append(": (an application on your device)"); diff --git a/src/oauth/ClientUri.cpp b/src/oauth/ClientUri.cpp index da25709f6..3235f8c5d 100644 --- a/src/oauth/ClientUri.cpp +++ b/src/oauth/ClientUri.cpp @@ -8,6 +8,7 @@ #include "merovingian/oauth/OAuthErrorCodes.hpp" #include +#include #include namespace merovingian::oauth @@ -43,6 +44,27 @@ namespace return reversed; } + // The WHATWG URL Standard's "ends in a number checker" for the last label: all ASCII digits, or `0x` / `0X` + // followed only by hex digits (`0x` alone included). A browser reads such a host as an IPv4 address (`0x7f.1` is + // 127.0.0.1 to it), so it is never a DNS name here. + [[nodiscard]] auto ends_in_a_number(std::string_view label) noexcept -> bool + { + auto const digits = [](std::string_view text, auto&& accepted) noexcept { + return std::ranges::all_of(text, accepted); + }; + if (!label.empty() && digits(label, [](char value) noexcept { + return value >= '0' && value <= '9'; + })) + { + return true; + } + return label.size() >= 2U && label[0] == '0' && (label[1] == 'x' || label[1] == 'X') && + digits(label.substr(2U), [](char value) noexcept { + return (value >= '0' && value <= '9') || (value >= 'a' && value <= 'f') || + (value >= 'A' && value <= 'F'); + }); + } + } // namespace ClientUri::ClientUri(ParsedUri uri) @@ -74,14 +96,11 @@ auto ClientUri::read(std::string_view text) -> std::variant= '0' && value <= '9'; - })) + if (ends_in_a_number(std::string_view{host}.substr(last_dot + 1U))) { return refuse(core::ErrorCode::parse_failure, "The client_uri host must be a DNS name."); } - if (top_label == "localhost") + if (std::string_view{host}.substr(last_dot + 1U) == "localhost") { return refuse(core::ErrorCode::parse_failure, "The client_uri host must not be a loopback name."); } diff --git a/src/oauth/DisplayText.cpp b/src/oauth/DisplayText.cpp index f1df2f4df..dd2710acd 100644 --- a/src/oauth/DisplayText.cpp +++ b/src/oauth/DisplayText.cpp @@ -5,10 +5,49 @@ #include "merovingian/core/Utf8.hpp" +#include #include +#include +#include namespace merovingian::oauth { +namespace +{ + + // Inclusive code point ranges a displayed name may not hold. See DisplayText.hpp for what each is. + constexpr auto refused_ranges = std::array, 14>{ + { + {0x0000U, 0x001FU}, // C0 controls + {0x007FU, 0x009FU}, // DEL and the C1 controls + {0x00ADU, 0x00ADU}, // soft hyphen + {0x061CU, 0x061CU}, // ARABIC LETTER MARK + {0x180EU, 0x180EU}, // MONGOLIAN VOWEL SEPARATOR + {0x200BU, 0x200DU}, // zero width space, non-joiner, joiner + {0x200EU, 0x200FU}, // LEFT-TO-RIGHT MARK, RIGHT-TO-LEFT MARK + {0x2028U, 0x2029U}, // line and paragraph separators + {0x202AU, 0x202EU}, // bidirectional embeddings and overrides + {0x2060U, 0x2064U}, // word joiner and the invisible operators + {0x2066U, 0x2069U}, // bidirectional isolates + {0xFEFFU, 0xFEFFU}, // zero width no-break space (byte order mark) + {0xFFF9U, 0xFFFBU}, // interlinear annotation characters + {0xE0000U, 0xE007FU}, // tag characters + } + }; + + [[nodiscard]] auto is_refused(std::uint32_t code_point) noexcept -> bool + { + for (auto const& [first, last] : refused_ranges) + { + if (code_point >= first && code_point <= last) + { + return true; + } + } + return false; + } + +} // namespace auto display_text_is_safe(std::string_view text) noexcept -> bool { @@ -17,44 +56,39 @@ auto display_text_is_safe(std::string_view text) noexcept -> bool return false; } // The text is valid UTF-8 here, so a lead byte is always followed by its continuation bytes. - for (auto index = std::size_t{0U}; index < text.size(); ++index) + constexpr auto continuation_bits = 6U; + constexpr auto continuation_mask = 0x3FU; + auto index = std::size_t{0U}; + while (index < text.size()) { - auto const byte = static_cast(text[index]); - if (byte < 0x20U || byte == 0x7FU) + auto const lead = static_cast(text[index]); + auto length = std::size_t{1U}; + auto code_point = static_cast(lead); + if (lead >= 0xF0U) { - return false; + length = 4U; + code_point = lead & 0x07U; } - if (byte == 0xC2U) + else if (lead >= 0xE0U) { - // U+0080..U+009F: C2 80..C2 9F. - auto const next = static_cast(text[index + 1U]); - if (next >= 0x80U && next <= 0x9FU) - { - return false; - } + length = 3U; + code_point = lead & 0x0FU; } - else if (byte == 0xD8U) + else if (lead >= 0xC0U) { - // U+061C ARABIC LETTER MARK: D8 9C. - if (static_cast(text[index + 1U]) == 0x9CU) - { - return false; - } + length = 2U; + code_point = lead & 0x1FU; } - else if (byte == 0xE2U) + for (auto offset = std::size_t{1U}; offset < length; ++offset) { - auto const second = static_cast(text[index + 1U]); - auto const third = static_cast(text[index + 2U]); - // U+200E, U+200F: E2 80 8E/8F. U+2028..U+202E: E2 80 A8..AE. U+2066..U+2069: E2 81 A6..A9. - if (second == 0x80U && (third == 0x8EU || third == 0x8FU || (third >= 0xA8U && third <= 0xAEU))) - { - return false; - } - if (second == 0x81U && third >= 0xA6U && third <= 0xA9U) - { - return false; - } + code_point = (code_point << continuation_bits) | + (static_cast(text[index + offset]) & continuation_mask); + } + if (is_refused(code_point)) + { + return false; } + index += length; } return true; } diff --git a/src/oauth/HandOffRedirect.cpp b/src/oauth/HandOffRedirect.cpp index 4ab42e3f2..0a5799069 100644 --- a/src/oauth/HandOffRedirect.cpp +++ b/src/oauth/HandOffRedirect.cpp @@ -38,7 +38,10 @@ namespace { return target.has_authority() && is_loopback_host(target.host()); } - return scheme.find('.') != std::string_view::npos; + // A private-use scheme (RFC 8252 section 7.1) is a reversed DNS name with no authority (ADR-0802, amended): + // `com.example.app://evil.example/` could otherwise reach an authority the allowlist entry `com.example.app:` + // never named. + return scheme.find('.') != std::string_view::npos && !target.has_authority(); } [[nodiscard]] auto matches_entry(ParsedUri const& target, std::string_view scheme, std::string_view entry) -> bool diff --git a/src/oauth/ParsedUri.cpp b/src/oauth/ParsedUri.cpp index ead5dff81..e86f69577 100644 --- a/src/oauth/ParsedUri.cpp +++ b/src/oauth/ParsedUri.cpp @@ -6,6 +6,8 @@ #include "merovingian/core/ErrorCode.hpp" #include +#include +#include namespace merovingian::oauth { @@ -103,16 +105,96 @@ namespace } } + // RFC 3986 dec-octet: 0 to 255, no leading zero. + [[nodiscard]] auto dec_octet_is_valid(std::string_view octet) noexcept -> bool + { + constexpr auto max_octet = 255U; + if (octet.empty() || octet.size() > 3U || (octet.size() > 1U && octet.front() == '0') || + !std::ranges::all_of(octet, is_digit)) + { + return false; + } + auto value = 0U; + for (auto const digit : octet) + { + value = (value * 10U) + static_cast(digit - '0'); + } + return value <= max_octet; + } + + // RFC 3986 IPv4address: four dec-octets separated by dots. + [[nodiscard]] auto ipv4_address_is_valid(std::string_view text) noexcept -> bool + { + constexpr auto octets = 4U; + auto count = 0U; + while (true) + { + auto const dot = text.find('.'); + if (!dec_octet_is_valid(text.substr(0U, dot))) + { + return false; + } + ++count; + if (dot == std::string_view::npos) + { + return count == octets; + } + text = text.substr(dot + 1U); + } + } + + // The 16-bit pieces of one side of an IPv6 address: `h16 *(":" h16)`, the last one of the address possibly an + // IPv4address (worth two pieces). nullopt when malformed; 0 for an empty side. + [[nodiscard]] auto ipv6_pieces(std::string_view side, bool may_end_in_ipv4) noexcept -> std::optional + { + if (side.empty()) + { + return 0U; + } + auto pieces = std::size_t{0U}; + while (true) + { + auto const colon = side.find(':'); + auto const piece = side.substr(0U, colon); + if (colon == std::string_view::npos && may_end_in_ipv4 && piece.find('.') != std::string_view::npos) + { + return ipv4_address_is_valid(piece) ? std::optional{pieces + 2U} : std::nullopt; + } + if (piece.empty() || piece.size() > 4U || !std::ranges::all_of(piece, is_hex_digit)) + { + return std::nullopt; + } + ++pieces; + if (colon == std::string_view::npos) + { + return pieces; + } + side = side.substr(colon + 1U); + } + } + + // RFC 3986 IP-literal holding an IPv6address: eight 16-bit pieces, or fewer with one `::` standing for at least + // one, the last two possibly written as an IPv4 address. No zone identifier and no IPvFuture. [[nodiscard]] auto ipv6_literal_is_valid(std::string_view host) noexcept -> bool { + constexpr auto ipv6_pieces_total = std::size_t{8U}; if (host.size() < 4U || host.size() > max_ipv6_literal_bytes || host.front() != '[' || host.back() != ']') { return false; } auto const inner = host.substr(1U, host.size() - 2U); - return inner.find(':') != std::string_view::npos && std::ranges::all_of(inner, [](char value) noexcept { - return is_hex_digit(value) || value == ':' || value == '.'; - }); + auto const elision = inner.find("::"); + if (elision == std::string_view::npos) + { + return ipv6_pieces(inner, true) == ipv6_pieces_total; + } + if (inner.find("::", elision + 1U) != std::string_view::npos) + { + return false; + } + auto const head = ipv6_pieces(inner.substr(0U, elision), false); + auto const tail = ipv6_pieces(inner.substr(elision + 2U), true); + return head.has_value() && tail.has_value() && *head + *tail < ipv6_pieces_total; } // 1 to 5 digits, no leading zero, 1..65535. @@ -307,6 +389,13 @@ auto ParsedUri::csp_source() const -> std::string { return source; } + // A bracketed IPv6 host has no form in the CSP host-source grammar (CSP3 section 2.3.1), and a browser drops a + // source it cannot parse, which would block the redirect; the scheme alone is the narrowest source that names it + // (ADR-0811). + if (m_host.starts_with('[')) + { + return source; + } source.append("//"); source.append(m_host); if (m_port.has_value()) diff --git a/tests/fuzz/AGENTS.md b/tests/fuzz/AGENTS.md index b29b793bc..da445eef6 100644 --- a/tests/fuzz/AGENTS.md +++ b/tests/fuzz/AGENTS.md @@ -37,6 +37,8 @@ Add a new `fuzz_.cpp` that: 2. Feeds the raw bytes into the parsing surface under test 3. Asserts that the parser does not crash, corrupt memory, or loop infinitely 4. Does **not** assert a specific output — fuzzing is about stability, not correctness + A target may abort (`std::abort`) when a property that must hold for every input breaks, such as + `fuzz_oauth_redirect_uri.cpp`'s CSP source, exact match and self-match checks; never on one input's expected value. Register the target in `tests/fuzz/meson.build`. diff --git a/tests/fuzz/fuzz_oauth_redirect_uri.cpp b/tests/fuzz/fuzz_oauth_redirect_uri.cpp index 18b8e6f05..0fc1d9a96 100644 --- a/tests/fuzz/fuzz_oauth_redirect_uri.cpp +++ b/tests/fuzz/fuzz_oauth_redirect_uri.cpp @@ -4,6 +4,10 @@ // Exercises the strict URI reader (oauth::ParsedUri::read), the client URI rules and the redirect URI rules // (validate_redirect_uri, match_redirect_uri). Bytes before the first NUL are the redirect URI; bytes after it are // the client URI, which is also the one registered URI the redirect URI is matched against. +// +// Beside stability it aborts when a property that holds for every input breaks: a CSP source holds no space, `;`, `,` +// or quote (it is joined into a policy header), a match returns the very text requested (the redirect goes there), +// and a redirect URI that validates matches itself once registered. #include "fuzz_input.hpp" #include "merovingian/oauth/ApplicationType.hpp" @@ -14,10 +18,41 @@ #include #include #include +#include +#include #include -#include +#include #include +namespace +{ + +// Aborts the run, which libFuzzer reports as a crash with the input that broke the property. +auto require(bool property) -> void +{ + if (!property) + { + std::abort(); + } +} + +auto require_safe_csp_source(merovingian::oauth::ParsedUri const& uri) -> void +{ + auto const source = uri.csp_source(); + require(source.find_first_of(" ;,'\"") == std::string::npos); +} + +auto require_exact_match(std::optional const& match, std::string_view requested) -> void +{ + if (match.has_value()) + { + require(match->text() == requested); + require_safe_csp_source(*match); + } +} + +} // namespace + extern "C" auto LLVMFuzzerTestOneInput(std::uint8_t const* data, std::size_t size) -> int { using merovingian::oauth::ApplicationType; @@ -28,13 +63,13 @@ extern "C" auto LLVMFuzzerTestOneInput(std::uint8_t const* data, std::size_t siz auto const parsed = merovingian::oauth::ParsedUri::read(redirect); if (auto const* uri = std::get_if(&parsed)) { - std::ignore = uri->csp_source(); + require_safe_csp_source(*uri); } auto const registered = std::array{std::string{client}}; for (auto const type : {ApplicationType::web, ApplicationType::native}) { - std::ignore = merovingian::oauth::match_redirect_uri(redirect, type, registered); + require_exact_match(merovingian::oauth::match_redirect_uri(redirect, type, registered), redirect); } auto const client_uri = merovingian::oauth::ClientUri::read(client); @@ -42,7 +77,14 @@ extern "C" auto LLVMFuzzerTestOneInput(std::uint8_t const* data, std::size_t siz { for (auto const type : {ApplicationType::web, ApplicationType::native}) { - std::ignore = merovingian::oauth::validate_redirect_uri(redirect, type, *base); + auto const validated = merovingian::oauth::validate_redirect_uri(redirect, type, *base); + if (std::holds_alternative(validated)) + { + auto const itself = std::array{std::string{redirect}}; + auto const match = merovingian::oauth::match_redirect_uri(redirect, type, itself); + require(match.has_value()); + require_exact_match(match, redirect); + } } } return 0; diff --git a/tests/unit/test_oauth_client_metadata.cpp b/tests/unit/test_oauth_client_metadata.cpp index ac602ad9a..d72e679dc 100644 --- a/tests/unit/test_oauth_client_metadata.cpp +++ b/tests/unit/test_oauth_client_metadata.cpp @@ -339,6 +339,80 @@ SCENARIO("client_name is capped and refuses control and bidirectional characters } } +SCENARIO("client_name refuses invisible characters that make two names look alike", "[oauth][metadata][security]") +{ + GIVEN("a name holding each invisible character, at the edges of each refused range, and names next to them") + { + auto const with_name = [](std::string name) { + auto object = Object{}; + object.push_back( + merovingian::canonicaljson::make_member("client_uri", Value{std::string{"https://example.com/"}})); + auto uris = merovingian::canonicaljson::Array{}; + uris.emplace_back(std::string{"https://example.com/cb"}); + object.push_back(merovingian::canonicaljson::make_member("redirect_uris", Value{std::move(uris)})); + object.push_back(merovingian::canonicaljson::make_member("client_name", Value{std::move(name)})); + return ClientMetadata::validate(Value{std::move(object)}); + }; + + WHEN("each is validated") + { + THEN("each invisible character is refused and its neighbours are registered") + { + // U+00AD, U+180E, U+200B, U+200D, U+2060, U+2064, U+FEFF, U+FFF9, U+FFFB, U+E0000, U+E0041, U+E007F. + for (auto const& bad : std::array{ + std::string{"Pay\xc2\xad" + "Pal"}, + std::string{"Pay\xe1\xa0\x8e" + "Pal"}, + std::string{"Pay\xe2\x80\x8b" + "Pal"}, + std::string{"Pay\xe2\x80\x8d" + "Pal"}, + std::string{"Pay\xe2\x81\xa0" + "Pal"}, + std::string{"Pay\xe2\x81\xa4" + "Pal"}, + std::string{"\xef\xbb\xbf" + "PayPal"}, + std::string{"Pay\xef\xbf\xb9" + "Pal"}, + std::string{"Pay\xef\xbf\xbb" + "Pal"}, + std::string{"Pay\xf3\xa0\x80\x80" + "Pal"}, + std::string{"PayPal\xf3\xa0\x81\x81"}, + std::string{"PayPal\xf3\xa0\x81\xbf"}, + }) + { + INFO(bad); + REQUIRE(refusal_code(with_name(bad)) == merovingian::oauth::error_invalid_client_metadata); + } + // U+00AC, U+00AE, U+200A, U+2065 (unassigned, outside both ranges), U+FFFC, U+E0080, U+1F600. + for (auto const& good : std::array{ + std::string{"Pay\xc2\xac" + "Pal"}, + std::string{"Pay\xc2\xae" + "Pal"}, + std::string{"Pay\xe2\x80\x8a" + "Pal"}, + std::string{"Pay\xe2\x81\xa5" + "Pal"}, + std::string{"Pay\xef\xbf\xbc" + "Pal"}, + std::string{"Pay\xf3\xa0\x82\x80" + "Pal"}, + std::string{"Pay\xf0\x9f\x98\x80" + "Pal"}, + }) + { + INFO(good); + REQUIRE(std::holds_alternative(with_name(good))); + } + } + } + } +} + SCENARIO("policy_uri and tos_uri must be https on the client host", "[oauth][metadata][security]") { GIVEN("policy and terms URIs on http, another host, with userinfo, and a subdomain") diff --git a/tests/unit/test_oauth_hand_off_redirect.cpp b/tests/unit/test_oauth_hand_off_redirect.cpp index 7a2bf89f2..5c4b24c9a 100644 --- a/tests/unit/test_oauth_hand_off_redirect.cpp +++ b/tests/unit/test_oauth_hand_off_redirect.cpp @@ -46,7 +46,7 @@ SCENARIO("An https address, a loopback http address and a private-use scheme are auto const url = GENERATE(as{}, "https://app.example.com/cb", "https://app.example.com:8443/x?y=1", "HTTPS://App.Example.com/cb", "http://localhost:8080/cb", "http://127.0.0.1/cb", "http://[::1]:9000/", "http://LOCALHOST/cb", "io.element.app:/callback", - "com.example.app://login", "Com.Example.App:/x"); + "com.example.app:/login", "Com.Example.App:/x"); WHEN("no allowlist is configured") { @@ -67,7 +67,9 @@ SCENARIO("Any other address is refused as a hand-off target", "[oauth][hand-off- "file:///etc/passwd", "http://app.example.com/cb", "http://10.0.0.1/cb", "http://localhost.evil.com/", "https:/no-authority", "ftp://example.com/", "myapp:/cb", "/relative/path", "https://app.example.com/cb#fragment", - "https://user@app.example.com/cb", "https://app.example.com/a b"); + "https://user@app.example.com/cb", "https://app.example.com/a b", + // A private-use scheme takes no authority (RFC 8252 section 7.1). + "com.example.app://login", "com.example.app://evil.example/cb"); WHEN("it is checked") { @@ -170,3 +172,31 @@ SCENARIO("The hand-off confirmation page names the account and the destination", } } } + +SCENARIO("The hand-off confirmation page shows the destination's port when it has one", "[oauth][hand-off-redirect]") +{ + GIVEN("two loopback targets on different ports, and an https target on a port") + { + auto const first = hand_off_redirect_target("http://localhost:8080/cb", {}); + auto const second = hand_off_redirect_target("http://localhost:9090/cb", {}); + auto const web = hand_off_redirect_target("https://app.example.com:8443/cb", {}); + REQUIRE(first.has_value()); + REQUIRE(second.has_value()); + REQUIRE(web.has_value()); + + WHEN("the pages are rendered") + { + auto const first_html = merovingian::oauth::hand_off_page(pending, "@alice:example.org", *first).render(); + auto const second_html = merovingian::oauth::hand_off_page(pending, "@alice:example.org", *second).render(); + auto const web_html = merovingian::oauth::hand_off_page(pending, "@alice:example.org", *web).render(); + + THEN("each names its host and port, so the two loopback applications are told apart") + { + CHECK(contains(first_html, "localhost:8080")); + CHECK(contains(second_html, "localhost:9090")); + CHECK_FALSE(contains(first_html, "localhost:9090")); + CHECK(contains(web_html, "app.example.com:8443")); + } + } + } +} diff --git a/tests/unit/test_oauth_page.cpp b/tests/unit/test_oauth_page.cpp index 90160f9c1..cfa3e6667 100644 --- a/tests/unit/test_oauth_page.cpp +++ b/tests/unit/test_oauth_page.cpp @@ -292,16 +292,18 @@ SCENARIO("A redirect target adds only its own origin to form-action", "[oauth][p auto const web = read("https://app.example.com:8443/cb;script-src%20*?x=1;default-src%20*,'unsafe-inline'"); auto const loopback = read("http://127.0.0.1:5000/cb?a=;b"); auto const native = read("com.example.app:/cb;script-src"); + auto const ipv6_loopback = read("http://[::1]:5000/cb?a=;b"); WHEN("headers are built for each") { auto const web_policy = header(merovingian::oauth::page_headers(web), "Content-Security-Policy"); auto const loopback_policy = header(merovingian::oauth::page_headers(loopback), "Content-Security-Policy"); auto const native_policy = header(merovingian::oauth::page_headers(native), "Content-Security-Policy"); + auto const ipv6_policy = header(merovingian::oauth::page_headers(ipv6_loopback), "Content-Security-Policy"); THEN("each policy has the same five directives and ends with the target's origin or scheme") { - for (auto const& policy : {web_policy, loopback_policy, native_policy}) + for (auto const& policy : {web_policy, loopback_policy, native_policy, ipv6_policy}) { REQUIRE(count(policy, ";") == 4U); REQUIRE(policy.find("script-src") == std::string::npos); @@ -310,6 +312,9 @@ SCENARIO("A redirect target adds only its own origin to form-action", "[oauth][p REQUIRE(web_policy.ends_with("; form-action 'self' https://app.example.com:8443")); REQUIRE(loopback_policy.ends_with("; form-action 'self' http://127.0.0.1:5000")); REQUIRE(native_policy.ends_with("; form-action 'self' com.example.app:")); + // CSP has no form for an IPv6 host, so a bracketed loopback target adds its scheme (ADR-0811). + REQUIRE(ipv6_policy.ends_with("; form-action 'self' http:")); + REQUIRE(ipv6_policy.find('[') == std::string::npos); } } } diff --git a/tests/unit/test_oauth_redirect_uri.cpp b/tests/unit/test_oauth_redirect_uri.cpp index 247a63e5e..34b0a7b9b 100644 --- a/tests/unit/test_oauth_redirect_uri.cpp +++ b/tests/unit/test_oauth_redirect_uri.cpp @@ -145,6 +145,61 @@ SCENARIO("The URI reader refuses hostile and ambiguous forms", "[oauth][uri][sec } } +SCENARIO("The URI reader takes an IPv6 host only in the RFC 3986 IPv6address grammar", "[oauth][uri][boundary]") +{ + GIVEN("well-formed IPv6 literals and literals the old character check let through") + { + auto const good = std::array{ + "http://[::1]/cb", + "http://[::]/cb", + "http://[1:2:3:4:5:6:7:8]/cb", + "http://[1::8]:8080/cb", + "http://[1:2:3:4:5:6:7::]/cb", + "http://[::2:3:4:5:6:7:8]/cb", + "http://[::ffff:127.0.0.1]/cb", + "http://[1:2:3:4:5:6:1.2.3.4]/cb", + "http://[FE80::aB:0]/cb", + }; + auto const bad = std::array{ + "http://[:]/cb", + "http://[:::]/cb", + "http://[1::2::3]/cb", + "http://[1:2:3:4:5:6:7:8:9]/cb", + "http://[1:2:3:4:5:6:7]/cb", + "http://[1:2:3:4:5:6:7:8::]/cb", + "http://[12345::1]/cb", + "http://[:1::2]/cb", + "http://[1::2:]/cb", + "http://[1.2.3.4::]/cb", + "http://[::1.2.3.4:5]/cb", + "http://[::256.0.0.1]/cb", + "http://[::01.2.3.4]/cb", + "http://[::1.2.3]/cb", + "http://[::1.2.3.4.5]/cb", + "http://[1:2:3:4:5:6:7:1.2.3.4]/cb", + "http://[...:]/cb", + "http://[v1.x]/cb", + }; + + WHEN("each is read") + { + THEN("the well-formed ones are read and the others refused") + { + for (auto const text : good) + { + INFO(text); + REQUIRE(reads(text)); + } + for (auto const text : bad) + { + INFO(text); + REQUIRE_FALSE(reads(text)); + } + } + } + } +} + SCENARIO("The URI reader refuses NUL, non-ASCII and over-long input", "[oauth][uri][boundary]") { GIVEN("a URI with an embedded NUL, one with a UTF-8 host, one of 2048 bytes and one of 2049") @@ -329,10 +384,24 @@ SCENARIO("A client URI must be https on a DNS name of two or more labels", "[oau { GIVEN("client URIs on IP literals, loopback names, single labels, http, or with userinfo or a fragment") { - auto const refused = std::array{ - "http://example.com/", "https://localhost/", "https://app.localhost/", "https://127.0.0.1/", - "https://[::1]/", "https://example/", "https://user@example.com/", "https://example.com/#", - "https://example.123/", "com.example:/", "https:example.com", + auto const refused = std::array{ + "http://example.com/", + "https://localhost/", + "https://app.localhost/", + "https://127.0.0.1/", + "https://[::1]/", + "https://example/", + "https://user@example.com/", + "https://example.com/#", + "https://example.123/", + "com.example:/", + "https:example.com", + // The WHATWG "ends in a number" rule: a browser reads these hosts as IPv4 addresses. + "https://app.0x7f/", + "https://app.0X1/", + "https://1.0x/", + "https://a.0xABCdef/", + "https://0x7f.1/", }; WHEN("each is read") @@ -359,6 +428,17 @@ SCENARIO("A client URI must be https on a DNS name of two or more labels", "[oau REQUIRE(base.reversed_host_lower() == "com.example.app"); } } + AND_WHEN("hosts whose last label only looks like a number are read") + { + THEN("they are DNS names and accepted") + { + for (auto const text : {"https://app.0xg1/", "https://app.x7f/", "https://app.1a/", "https://app.0y1/"}) + { + INFO(text); + REQUIRE(std::holds_alternative(ClientUri::read(text))); + } + } + } } } From 38d15c0fcdd38cd519207dc4b912ef521e693d02 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:22:42 +0000 Subject: [PATCH 29/42] Read a page query's bare name or empty field as not sent (ADR-0765) FormFields::parse_query reads the query strings of /authorize, /link, /account and the legacy SSO redirect's hand-off as parse reads a body, except that a bare name with no '=' and an empty field count as not sent, as RFC 6749 section 3.1 asks. A bare name is still decoded and checked, so a malformed escape, NUL or invalid UTF-8 in it refuses the query; 'name=' keeps its empty value. Form bodies are still read with parse. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 + ...body-is-read-strictly-and-refused-whole.md | 6 ++ docs/http-transport.md | 3 + include/merovingian/core/FormFields.hpp | 16 ++++++ src/core/AGENTS.md | 2 +- src/core/FormFields.cpp | 36 ++++++++++++ src/homeserver/AccountPage.cpp | 2 +- src/homeserver/OAuthAuthorization.cpp | 6 +- .../test_oauth_authorization_flow.cpp | 37 ++++++++++++ tests/unit/test_core_form_fields.cpp | 57 +++++++++++++++++++ 10 files changed, 162 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 29d2b73f2..84daad4ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -116,6 +116,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * A native client on an `http://[::1]` redirect URI completes its sign-in: CSP cannot name an IPv6 host, so `form-action` gets `http:` for it (ADR-0811). * The hand-off confirmation page shows the destination's port, so two loopback applications are told apart. +* The page queries of `/authorize`, `/link`, `/account` and the SSO redirect read a bare name or an empty field as + not sent, as RFC 6749 section 3.1 asks, instead of refusing the request (ADR-0765). ## Release notes diff --git a/docs/adr/0765-a-form-body-is-read-strictly-and-refused-whole.md b/docs/adr/0765-a-form-body-is-read-strictly-and-refused-whole.md index f1b27a4b4..9c7306e7b 100644 --- a/docs/adr/0765-a-form-body-is-read-strictly-and-refused-whole.md +++ b/docs/adr/0765-a-form-body-is-read-strictly-and-refused-whole.md @@ -5,6 +5,12 @@ Technical Story: phase 1 of the OAuth 2.0 API plan (`docs/todos/oauth-2-0-api.md`) +Amended 2026-11-16 (review finding 13): the query strings of the browser pages (`/_merovingian/oauth2/authorize`, +`/_merovingian/oauth2/link`, `/_merovingian/account` and the legacy SSO redirect) are read with +`FormFields::parse_query`, which counts a bare name with no `=` and an empty field (`&&`, a leading or trailing `&`) +as not sent, as RFC 6749 section 3.1 asks of a parameter sent without a value. The bare name is still decoded and +checked, and every other refusal holds. A request body is still read with `parse`, which refuses both. + ## Context and Problem Statement The OAuth 2.0 token and revocation endpoints and the authentication pages read `application/x-www-form-urlencoded` diff --git a/docs/http-transport.md b/docs/http-transport.md index fc856de31..d12eb5187 100644 --- a/docs/http-transport.md +++ b/docs/http-transport.md @@ -287,6 +287,9 @@ escape, a field with no `=` or an empty name, an empty field (`&&`), a raw byte NUL or invalid UTF-8, and a repeated name each refuse the whole body. `+` is a space; an empty body is an empty set. Caps, each refused rather than cut: 64 KiB of body, 64 fields, 64 bytes of decoded name, 8 KiB of decoded value. `parse_query_params` stays lenient and is not for these bodies. +`core::FormFields::parse_query` reads the query of the browser pages (`/_merovingian/oauth2/authorize`, +`/_merovingian/oauth2/link`, `/_merovingian/account` and the legacy SSO redirect's hand-off) the same way, except that a +bare name with no `=` and an empty field count as not sent (RFC 6749 section 3.1); the bare name is still checked. `core::RequestCookies::parse` reads a `Cookie` header (RFC 6265 section 4.2.1) without percent-decoding (ADR-0766). A sibling host under the same parent domain can add cookies to what the browser sends, so a malformed or repeated diff --git a/include/merovingian/core/FormFields.hpp b/include/merovingian/core/FormFields.hpp index 83cc2655f..8258ff05a 100644 --- a/include/merovingian/core/FormFields.hpp +++ b/include/merovingian/core/FormFields.hpp @@ -58,6 +58,14 @@ class FormFields final // ErrorCode::invalid_argument: a cap above is exceeded. Either message is fixed text, never input. [[nodiscard]] static auto parse(std::string_view body) -> std::variant; + // The fields of a page's request query (the part after `?`, without it), read as `parse` reads a body except that + // a bare name with no `=` and an empty field (`&&`, a leading or trailing `&`) count as not sent: RFC 6749 section + // 3.1, "Parameters sent without a value MUST be treated as if they were omitted from the request". A bare name is + // still decoded and checked, so a malformed escape, NUL or invalid UTF-8 in it refuses the query, and every other + // refusal and cap of `parse` holds; a bare name repeated, or beside a sent field of that name, is not a repeat. + // Only for the queries of the browser pages (ADR-0765): a body is read with `parse`. + [[nodiscard]] static auto parse_query(std::string_view query) -> std::variant; + // The decoded value of field `name`, or nullopt when it was not sent. The view lives as long as this object. [[nodiscard]] auto find(std::string_view name) const noexcept -> std::optional; @@ -68,6 +76,14 @@ class FormFields final [[nodiscard]] auto fields() const noexcept -> std::vector> const&; private: + // Omission: whether a bare name or an empty field is refused (`parse`) or counts as not sent (`parse_query`). + enum class Omission : unsigned char + { + refused, + not_sent, + }; + + [[nodiscard]] static auto read(std::string_view text, Omission omission) -> std::variant; auto wipe() noexcept -> void; std::vector> m_fields{}; diff --git a/src/core/AGENTS.md b/src/core/AGENTS.md index 02f546cb1..1a310b0cf 100644 --- a/src/core/AGENTS.md +++ b/src/core/AGENTS.md @@ -11,7 +11,7 @@ Low-level utilities used across all other modules. No module-specific logic live | `QueryParams.cpp` | Percent-decode and parse `?key=value&...` query strings from request URIs | | `PortableSemaphore.cpp` | `PortableSemaphore` (counting semaphore; NetBSD's libc++ has no `std::counting_semaphore`) and `SemaphorePermit`, the RAII owner of one acquired slot | | `FoldedSubstringMatcher.cpp` | `FoldedSubstringMatcher`: ASCII-case-insensitive substring search in time linear in the text (KMP over folded bytes) with a `steps()` count, and `max_search_term_bytes`, the one cap on a client search term (ADR-0330). Use it for any search of a client's term in text a client chose; never `std::search` or `find` there | -| `FormFields.cpp` | `FormFields::parse`: the strict `application/x-www-form-urlencoded` reader for OAuth bodies and page forms. Any malformed escape, empty or `=`-less field, raw non-printable byte, NUL, invalid UTF-8 or repeated name refuses the whole body; caps 64 KiB, 64 fields, 64-byte names, 8 KiB values (ADR-0765) | +| `FormFields.cpp` | `FormFields::parse`: the strict `application/x-www-form-urlencoded` reader for OAuth bodies and page forms. Any malformed escape, empty or `=`-less field, raw non-printable byte, NUL, invalid UTF-8 or repeated name refuses the whole body; caps 64 KiB, 64 fields, 64-byte names, 8 KiB values (ADR-0765). `FormFields::parse_query`, for the browser pages' query strings only, counts a bare name or an empty field as not sent (RFC 6749 section 3.1) and keeps every other refusal | | `RequestCookies.cpp` | `RequestCookies::parse`: the `Cookie` header reader. A malformed or repeated cookie makes its own name unusable (`find` answers nothing), never the others (ADR-0766) | | `HostCookie.cpp` | `host_cookie` / `host_cookie_deletion`: the only `Set-Cookie` writers, `__Host-` names with `Secure`, `HttpOnly`, `Path=/`, `SameSite` from `CookieSameSite`, `Max-Age` | | `CookieOctets.cpp`, `HttpToken.cpp`, `Utf8.cpp` | `cookie_octets_are_valid`, `http_token_is_valid` (also behind `http::header_name_is_valid`) and `utf8_is_valid` (also behind `canonicaljson::utf8_is_valid`) | diff --git a/src/core/FormFields.cpp b/src/core/FormFields.cpp index 10fad22ef..7170b5275 100644 --- a/src/core/FormFields.cpp +++ b/src/core/FormFields.cpp @@ -10,6 +10,7 @@ #include #include #include +#include namespace merovingian::core { @@ -92,6 +93,18 @@ namespace return decoded.find('\0') == std::string_view::npos && utf8_is_valid(decoded); } + // A bare name (a query field with no `=`) is not kept, but it must still be well formed: the same escapes, bytes, + // UTF-8 and length as a kept name. + [[nodiscard]] auto bare_name_is_acceptable(std::string_view encoded) -> bool + { + auto decoded = std::string{}; + decoded.reserve(encoded.size()); + auto const acceptable = decode_component(encoded, decoded) && decoded.size() <= FormFields::max_name_bytes && + decoded_text_is_acceptable(decoded); + wipe_string(decoded); + return acceptable; + } + } // namespace FormFields::~FormFields() noexcept @@ -121,6 +134,16 @@ auto FormFields::wipe() noexcept -> void } auto FormFields::parse(std::string_view body) -> std::variant +{ + return read(body, Omission::refused); +} + +auto FormFields::parse_query(std::string_view query) -> std::variant +{ + return read(query, Omission::not_sent); +} + +auto FormFields::read(std::string_view body, Omission omission) -> std::variant { if (body.size() > max_body_bytes) { @@ -145,6 +168,19 @@ auto FormFields::parse(std::string_view body) -> std::variant auto const separator = remaining.find('&'); auto const field = remaining.substr(0U, separator); auto const equals = field.find('='); + if (omission == Omission::not_sent && (field.empty() || equals == std::string_view::npos)) + { + if (!field.empty() && !bare_name_is_acceptable(field)) + { + return malformed(); + } + if (separator == std::string_view::npos) + { + break; + } + remaining.remove_prefix(separator + 1U); + continue; + } if (field.empty() || equals == std::string_view::npos || equals == 0U) { return malformed(); diff --git a/src/homeserver/AccountPage.cpp b/src/homeserver/AccountPage.cpp index b655231dc..891e0d086 100644 --- a/src/homeserver/AccountPage.cpp +++ b/src/homeserver/AccountPage.cpp @@ -394,7 +394,7 @@ namespace [[nodiscard]] auto handle_get(AccountContext const& context) -> LocalHttpResponse { - auto parsed = core::FormFields::parse(request_target_query(context.request.target)); + auto parsed = core::FormFields::parse_query(request_target_query(context.request.target)); auto const* const fields = std::get_if(&parsed); // An unreadable query (a parameter sent twice, a bad escape) asks for nothing: the overview. auto const requested = diff --git a/src/homeserver/OAuthAuthorization.cpp b/src/homeserver/OAuthAuthorization.cpp index 18aaad3a8..e8627b77f 100644 --- a/src/homeserver/OAuthAuthorization.cpp +++ b/src/homeserver/OAuthAuthorization.cpp @@ -956,7 +956,7 @@ namespace { auto& runtime = rt.homeserver; // Step 1: the client and its redirect URI. Nothing here is ever sent to an address. - auto parsed = core::FormFields::parse(request_target_query(request.target)); + auto parsed = core::FormFields::parse_query(request_target_query(request.target)); auto const* fields = std::get_if(&parsed); if (fields == nullptr) { @@ -1127,7 +1127,7 @@ namespace // browser cookie the form post needs. Nothing is looked up: the user confirms the code by sending the form. [[nodiscard]] auto handle_link_get(LocalHttpRequest const& request) -> LocalHttpResponse { - auto parsed = core::FormFields::parse(request_target_query(request.target)); + auto parsed = core::FormFields::parse_query(request_target_query(request.target)); auto const* fields = std::get_if(&parsed); auto prefill = std::optional{}; if (fields != nullptr) @@ -1282,7 +1282,7 @@ auto handle_oauth_link(ClientServerRuntime& runtime, LocalHttpRequest const& req auto handle_login_hand_off(ClientServerRuntime& rt, LocalHttpRequest const& request) -> LocalHttpResponse { auto& runtime = rt.homeserver; - auto parsed = core::FormFields::parse(request_target_query(request.target)); + auto parsed = core::FormFields::parse_query(request_target_query(request.target)); auto const* fields = std::get_if(&parsed); if (fields == nullptr) { diff --git a/tests/integration/test_oauth_authorization_flow.cpp b/tests/integration/test_oauth_authorization_flow.cpp index 2d76eae0d..aaebd204a 100644 --- a/tests/integration/test_oauth_authorization_flow.cpp +++ b/tests/integration/test_oauth_authorization_flow.cpp @@ -546,6 +546,43 @@ SCENARIO("An authorisation request whose client or redirect URI cannot be valida } } +SCENARIO("An authorisation request with a bare name or an empty field reads them as not sent", + "[integration][oauth][oauth-authorize][form-query]") +{ + GIVEN("a registered client") + { + auto fixture = make_fixture(false); + auto& rt = fixture.started.runtime; + auto const query = form_encode(oauth_authorize_parameters(fixture.client_id)); + auto const raw = [&](std::string const& target_query) { + return authorize_request(rt, "GET", std::string{oauth_authorize_path} + "?" + target_query, {}, + BrowserContext{}); + }; + + WHEN("the well-formed request is sent with a bare name, a doubled & and a trailing &") + { + auto const answer = raw("prompt&" + query + "&&ui_locales&"); + + THEN("it is the sign-in page, as for the request without them") + { + CHECK(answer.status == 200U); + CHECK(answer.page); + CHECK_FALSE(response_header(answer, "Set-Cookie").empty()); + } + } + WHEN("a bare name holds a malformed escape") + { + auto const answer = raw("bad%zz&" + query); + + THEN("it is still refused as a 400 page") + { + CHECK(answer.status == 400U); + CHECK(response_header(answer, "Location").empty()); + } + } + } +} + SCENARIO("A refused authorisation request is redirected to the client with the error and the state", "[integration][oauth][oauth-authorize]") { diff --git a/tests/unit/test_core_form_fields.cpp b/tests/unit/test_core_form_fields.cpp index eddaf09aa..dcae1bedf 100644 --- a/tests/unit/test_core_form_fields.cpp +++ b/tests/unit/test_core_form_fields.cpp @@ -269,6 +269,63 @@ SCENARIO("A form body is read up to each cap and refused one past it", "[core][f } } +SCENARIO("A page query counts a bare name and an empty field as not sent", "[core][form][form-query]") +{ + GIVEN("queries with bare names and empty fields beside real fields") + { + WHEN("each is read as a page query and as a body") + { + auto const bare = FormFields::parse_query("prompt&client_id=abc&&state=x%20y&"); + auto const bare_body = FormFields::parse("prompt&client_id=abc&&state=x%20y&"); + auto const leading = FormFields::parse_query("&client_id=abc"); + auto const only_bare = FormFields::parse_query("state&state&&"); + auto const bare_and_sent = FormFields::parse_query("state&state=one"); + + THEN("the page query keeps only the fields with a value, and the body is refused") + { + REQUIRE(refusal_code(bare) == ErrorCode::none); + auto const& fields = std::get(bare); + CHECK(fields.size() == 2U); + CHECK(fields.find("client_id") == "abc"); + CHECK(fields.find("state") == "x y"); + CHECK_FALSE(fields.find("prompt").has_value()); + CHECK(refusal_code(bare_body) == ErrorCode::parse_failure); + REQUIRE(refusal_code(leading) == ErrorCode::none); + CHECK(std::get(leading).find("client_id") == "abc"); + REQUIRE(refusal_code(only_bare) == ErrorCode::none); + CHECK(std::get(only_bare).empty()); + REQUIRE(refusal_code(bare_and_sent) == ErrorCode::none); + CHECK(std::get(bare_and_sent).find("state") == "one"); + } + } + WHEN("a page query breaks any other rule") + { + THEN("it is refused as a body would be") + { + for (auto const query : std::array{ + "a=1&a=2", + "=x", + "a=%zz", + "bad%zz&a=1", + "a%00&b=1", + "a=%00", + "a=%ff", + "a b=1", + "x&a=1&a=2", + }) + { + INFO(query); + CHECK(refusal_code(FormFields::parse_query(query)) == ErrorCode::parse_failure); + } + auto const long_bare = std::string(FormFields::max_name_bytes + 1U, 'n') + "&a=1"; + CHECK(refusal_code(FormFields::parse_query(long_bare)) == ErrorCode::parse_failure); + CHECK(refusal_code(FormFields::parse_query(repeated("a&", FormFields::max_fields))) == + ErrorCode::invalid_argument); + } + } + } +} + SCENARIO("Moving a form keeps its fields and empties the source", "[core][form]") { GIVEN("a parsed form") From acfbe7b9b1d1b3d4167818468c72eb08d8d0434a Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:23:23 +0000 Subject: [PATCH 30/42] Build every device and token insert through one statement helper each store_device, store_access_token, store_refresh_token and rotate_device_credentials now build their rows through insert_device_statement, insert_access_token_statement and insert_refresh_token_statement, which the grant writer already used. The SQL text, parameters and behaviour are unchanged. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 1 + src/database/PersistentStore.cpp | 142 +++++++++++-------------------- 2 files changed, 53 insertions(+), 90 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 84daad4ff..a1fa36c99 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -118,6 +118,7 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * The hand-off confirmation page shows the destination's port, so two loopback applications are told apart. * The page queries of `/authorize`, `/link`, `/account` and the SSO redirect read a bare name or an empty field as not sent, as RFC 6749 section 3.1 asks, instead of refusing the request (ADR-0765). +* The device and token inserts of a login, a grant and a refresh share one statement each; the SQL is unchanged. ## Release notes diff --git a/src/database/PersistentStore.cpp b/src/database/PersistentStore.cpp index 795ffad6b..86987c7a7 100644 --- a/src/database/PersistentStore.cpp +++ b/src/database/PersistentStore.cpp @@ -1925,20 +1925,59 @@ namespace return true; } +namespace +{ + + // The row inserts every device and token writer shares (ADR-0590, ADR-0792): one text for each statement, whether + // it is committed alone or in the caller's one transaction. + + [[nodiscard]] auto insert_device_statement(PersistentDevice const& device) -> PreparedStatement + { + return record_statement("insert_device", "INSERT INTO devices VALUES ($1, $2, $3)", + { + {device.user_id, false}, + {device.device_id, false}, + {device.display_name, false} + }); + } + + [[nodiscard]] auto insert_access_token_statement(PersistentAccessToken const& token) -> PreparedStatement + { + return record_statement("insert_access_token", "INSERT INTO access_tokens VALUES ($1, $2, $3, $4, $5, $6)", + { + {token.user_id, false}, + {token.device_id, false}, + {token.token_hash, true }, + {token.revoked ? "true" : "false", false}, + {expires_at_text(token.expires_at), false}, + {token.predecessor_refresh_hash, true } + }); + } + + [[nodiscard]] auto insert_refresh_token_statement(PersistentRefreshToken const& token) -> PreparedStatement + { + return record_statement("insert_refresh_token", + "INSERT INTO refresh_tokens VALUES ($1, $2, $3, $4, $5, $6, $7)", + { + {token.token_hash, true}, + {token.user_id, false}, + {token.device_id, false}, + {token.revoked ? "true" : "false", false}, + {expires_at_text(token.expires_at), false}, + {token.predecessor_hash, true}, + {std::to_string(std::max(token.issued_at_ms, 0)), false} + }); + } + +} // namespace + [[nodiscard]] auto store_device(PersistentStore& store, PersistentDevice device) -> bool { if (device_exists(store, device)) { return false; } - if (!record_and_persist( - store, - record_statement("insert_device", "INSERT INTO devices VALUES ($1, $2, $3)", - { - {device.user_id, false}, - {device.device_id, false}, - {device.display_name, false} - }))) + if (!record_and_persist(store, insert_device_statement(device))) { return false; } @@ -1958,16 +1997,7 @@ namespace { return false; } - if (!record_and_persist(store, record_statement("insert_access_token", - "INSERT INTO access_tokens VALUES ($1, $2, $3, $4, $5, $6)", - { - {token.user_id, false}, - {token.device_id, false}, - {token.token_hash, true }, - {token.revoked ? "true" : "false", false}, - {expires_at_text(token.expires_at), false}, - {token.predecessor_refresh_hash, true } - }))) + if (!record_and_persist(store, insert_access_token_statement(token))) { return false; } @@ -1981,18 +2011,7 @@ namespace { return false; } - if (!record_and_persist( - store, - record_statement("insert_refresh_token", "INSERT INTO refresh_tokens VALUES ($1, $2, $3, $4, $5, $6, $7)", - { - {token.token_hash, true}, - {token.user_id, false}, - {token.device_id, false}, - {token.revoked ? "true" : "false", false}, - {expires_at_text(token.expires_at), false}, - {token.predecessor_hash, true}, - {std::to_string(std::max(token.issued_at_ms, 0)), false} - }))) + if (!record_and_persist(store, insert_refresh_token_statement(token))) { return false; } @@ -2003,47 +2022,9 @@ namespace namespace { - // The writes a login and an OAuth 2.0 grant share (ADR-0590, ADR-0792), as statements for the caller's one + // The deletes a login and an OAuth 2.0 grant share (ADR-0590, ADR-0792), as statements for the caller's one // transaction, and their memory half after it committed. - [[nodiscard]] auto insert_device_statement(PersistentDevice const& device) -> PreparedStatement - { - return record_statement("insert_device", "INSERT INTO devices VALUES ($1, $2, $3)", - { - {device.user_id, false}, - {device.device_id, false}, - {device.display_name, false} - }); - } - - [[nodiscard]] auto insert_access_token_statement(PersistentAccessToken const& token) -> PreparedStatement - { - return record_statement("insert_access_token", "INSERT INTO access_tokens VALUES ($1, $2, $3, $4, $5, $6)", - { - {token.user_id, false}, - {token.device_id, false}, - {token.token_hash, true }, - {token.revoked ? "true" : "false", false}, - {expires_at_text(token.expires_at), false}, - {token.predecessor_refresh_hash, true } - }); - } - - [[nodiscard]] auto insert_refresh_token_statement(PersistentRefreshToken const& token) -> PreparedStatement - { - return record_statement("insert_refresh_token", - "INSERT INTO refresh_tokens VALUES ($1, $2, $3, $4, $5, $6, $7)", - { - {token.token_hash, true}, - {token.user_id, false}, - {token.device_id, false}, - {token.revoked ? "true" : "false", false}, - {expires_at_text(token.expires_at), false}, - {token.predecessor_hash, true}, - {std::to_string(std::max(token.issued_at_ms, 0)), false} - }); - } - // DELETE, not revoke (ADR-0590): a revoked refresh row that is presented counts as reuse and ends the device's // session, so a stale client holding the old refresh token would end the login that replaced it. The device's // OAuth session row goes too (ADR-0792): whatever replaces the credentials decides what kind of device it is. @@ -2197,27 +2178,8 @@ namespace {access.user_id, false}, {access.device_id, false} })); - statements.push_back(record_statement("insert_access_token", - "INSERT INTO access_tokens VALUES ($1, $2, $3, $4, $5, $6)", - { - {access.user_id, false}, - {access.device_id, false}, - {access.token_hash, true }, - {access.revoked ? "true" : "false", false}, - {expires_at_text(access.expires_at), false}, - {access.predecessor_refresh_hash, true } - })); - statements.push_back( - record_statement("insert_refresh_token", "INSERT INTO refresh_tokens VALUES ($1, $2, $3, $4, $5, $6, $7)", - { - {refresh.token_hash, true}, - {refresh.user_id, false}, - {refresh.device_id, false}, - {refresh.revoked ? "true" : "false", false}, - {expires_at_text(refresh.expires_at), false}, - {refresh.predecessor_hash, true}, - {std::to_string(std::max(refresh.issued_at_ms, 0)), false} - })); + statements.push_back(insert_access_token_statement(access)); + statements.push_back(insert_refresh_token_statement(refresh)); for (auto const& hash : evicted_refresh_hashes) { // The `revoked` condition is a second guard: the statement can never delete a live row. From 7e54dc07982526e1976924a73ea1c96e602d7d31 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:23:57 +0000 Subject: [PATCH 31/42] Bring the 1.1.0 CHANGELOG and two ADR notes up to date The early-phase Features bullets no longer say that nothing is served yet. ADR-0794 records that ADR-0797 amends it, and ADR-0033 notes that server.sso.authorization_url cannot be combined with server.oauth.enabled. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 12 ++++++------ ...so-protocol-integration-to-an-operator-gateway.md | 5 +++++ ...oss-signing-upload-follows-the-spec-exemptions.md | 3 +++ 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a1fa36c99..b062c98c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,11 +7,11 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) ## Features -* The plan for a built-in OAuth 2.0 API, which Element X needs to create accounts, is in - `docs/todos/oauth-2-0-api.md`. Nothing the server does has changed yet (ADR-0760 to ADR-0764). -* Strict form-body and `Cookie` header readers and a `__Host-` `Set-Cookie` builder in `core`, for the OAuth 2.0 - pages and endpoints; no route uses them yet (ADR-0765, ADR-0766). -* A module `oauth` of pure OAuth 2.0 building blocks, not yet served: PKCE `S256` and the scope parser +* A built-in OAuth 2.0 API, which Element X needs to create accounts, planned in `docs/todos/oauth-2-0-api.md` + (ADR-0760 to ADR-0764). +* Strict form-body and `Cookie` header readers and a `__Host-` `Set-Cookie` builder in `core`, which the OAuth 2.0 + pages and endpoints read and write with (ADR-0765, ADR-0766). +* A module `oauth` of pure OAuth 2.0 building blocks the endpoints call: PKCE `S256` and the scope parser (ADR-0768, ADR-0769). * A strict URI reader, redirect URI rules with byte-exact matching, and RFC 7591 client metadata validation with a canonical form (ADR-0770, ADR-0771). @@ -35,7 +35,7 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * In-memory, hashed, bounded OAuth 2.0 pending authorisations and authorization codes that never evict a live entry; the sweep and the client cap keep a client that holds one (ADR-0782). * The password check of `POST /login` and the account creation of `POST /register` are each one function, shared - with the coming OAuth 2.0 pages; both routes answer as before (ADR-0783). + with the OAuth 2.0 pages; both routes answer as before (ADR-0783). * OAuth 2.0 pages send `Referrer-Policy: same-origin`, get no CORS headers, and accept a form post only from this server's origin (ADR-0784, ADR-0785). * `GET` and `POST /_merovingian/oauth2/authorize` serve the sign-in, account creation and consent pages and send the diff --git a/docs/adr/0033-leave-sso-protocol-integration-to-an-operator-gateway.md b/docs/adr/0033-leave-sso-protocol-integration-to-an-operator-gateway.md index 19f8bb073..9b5182c91 100644 --- a/docs/adr/0033-leave-sso-protocol-integration-to-an-operator-gateway.md +++ b/docs/adr/0033-leave-sso-protocol-integration-to-an-operator-gateway.md @@ -3,6 +3,11 @@ * Status: accepted * Date: 2026-09-06 +Amended 2026-11-16: `server.sso.authorization_url` cannot be combined with `server.oauth.enabled`, and a configuration +that sets both is refused at start-up. With OAuth on, the legacy SSO redirect hands off to the built-in OAuth 2.0 pages +instead of an operator gateway +([ADR-0802](0802-the-legacy-sso-redirect-hands-off-to-the-built-in-pages-confirms-and-mints-a-30-second-login-token.md)). + ## Context and Problem Statement Matrix SSO login requires the homeserver to hand off to an external system — diff --git a/docs/adr/0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md b/docs/adr/0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md index 67974b532..9e1f97e3e 100644 --- a/docs/adr/0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md +++ b/docs/adr/0794-a-uia-endpoint-refuses-an-oauth-session-and-cross-signing-upload-follows-the-spec-exemptions.md @@ -6,6 +6,9 @@ Technical Story: phase 6 of the [OAuth 2.0 API plan](../todos/oauth-2-0-api.md) (proposal P7) +Amended by [ADR-0797](0797-an-oauth-session-replaces-its-cross-signing-keys-through-the-m-oauth-stage-and-a-one-use-approval.md): +a replacing `POST /keys/device_signing/upload` from an OAuth session is offered the `m.oauth` stage instead of the 403. + ## Context and Problem Statement A session from the OAuth 2.0 API has no password the client may be asked for: the user typed it on this server's From 08b23e4f29e92ad8df15d153840e2f9de8688446 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:46:28 +0000 Subject: [PATCH 32/42] List a device POST /refresh heals under its stored display name POST /refresh re-added a device the runtime's device list had lost (after a restart) with its device ID as the display name. It now reads the device row's stored name through stored_device_display_name, moved out of the OAuth token endpoint into StoredDeviceDisplayName.{hpp,cpp} so both refresh paths share it, and adds the device through remember_signed_in_device. New integration scenario [legacy-refresh-device-name] in test_oauth_token_flow.cpp. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 + docs/auth-identity.md | 3 ++ .../homeserver/StoredDeviceDisplayName.hpp | 20 ++++++++++ src/homeserver/AGENTS.md | 2 +- src/homeserver/ClientServerRuntime.cpp | 11 +++--- src/homeserver/OAuthTokenEndpoint.cpp | 21 +--------- src/homeserver/StoredDeviceDisplayName.cpp | 32 ++++++++++++++++ src/homeserver/meson.build | 1 + tests/integration/test_oauth_token_flow.cpp | 38 +++++++++++++++++++ 9 files changed, 105 insertions(+), 25 deletions(-) create mode 100644 include/merovingian/homeserver/StoredDeviceDisplayName.hpp create mode 100644 src/homeserver/StoredDeviceDisplayName.cpp diff --git a/CHANGELOG.md b/CHANGELOG.md index b062c98c9..5a698e9f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -113,6 +113,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) * An exception escaping the authorisation, device link, account or SSO hand-off page is answered with an HTML error page under the pages' headers, not JSON (ADR-0810). * The OAuth refresh grant lists a device after a restart with its stored display name, not its device ID. +* `POST /refresh` now does the same, through the function the refresh grant uses: a device it lists again after a + restart keeps its stored display name. * A native client on an `http://[::1]` redirect URI completes its sign-in: CSP cannot name an IPv6 host, so `form-action` gets `http:` for it (ADR-0811). * The hand-off confirmation page shows the destination's port, so two loopback applications are told apart. diff --git a/docs/auth-identity.md b/docs/auth-identity.md index b7f2cd81e..25c9cf59c 100644 --- a/docs/auth-identity.md +++ b/docs/auth-identity.md @@ -84,6 +84,9 @@ production-gated. an unrevoked row); a retired token older than that is a plain 401, the session survives and no `auth.refresh.reuse_detected` row is written. A user's credential rows are bounded by `device_count_limit` times these per-device bounds. +- A refresh whose device is missing from the runtime's in-memory device list (after a restart) lists it again under the + display name its device row holds, never its device ID; `POST /refresh` and the OAuth 2.0 refresh grant share + `stored_device_display_name` for it (1.1.0). - Refresh-token hashes are persisted, rotated, and revoked on single-device logout, global logout, device deletion, or password change with `logout_devices: true` (spec default) without storing plaintext token diff --git a/include/merovingian/homeserver/StoredDeviceDisplayName.hpp b/include/merovingian/homeserver/StoredDeviceDisplayName.hpp new file mode 100644 index 000000000..a8231321c --- /dev/null +++ b/include/merovingian/homeserver/StoredDeviceDisplayName.hpp @@ -0,0 +1,20 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later +#pragma once + +#include +#include + +namespace merovingian::homeserver +{ + +struct HomeserverRuntime; + +// Module-internal (src/AGENTS.md "Where module-local helpers go"): the display name the persistent device row of +// (`user_id`, `device_id`) holds, or empty when there is no row. Shared by POST /refresh and the OAuth 2.0 refresh +// grant, which re-add a device the runtime's device list lost (after a restart) under this name, never its device ID. +// Reads one user's devices; the caller holds runtime.mutex. +[[nodiscard]] auto stored_device_display_name(HomeserverRuntime const& runtime, std::string_view user_id, + std::string_view device_id) -> std::string; + +} // namespace merovingian::homeserver diff --git a/src/homeserver/AGENTS.md b/src/homeserver/AGENTS.md index 41272d85c..b347d4d4a 100644 --- a/src/homeserver/AGENTS.md +++ b/src/homeserver/AGENTS.md @@ -184,7 +184,7 @@ gate; `ClientServerRuntime.cpp` holds only the route matches. Rules: client and `created_at_ms`), recorded at the redemption's instant before the grant commits, so nothing that can fail follows the commit. - **The refresh grant heals the runtime's device list with the device row's stored display name**, never the device - ID. + ID: `stored_device_display_name` (`StoredDeviceDisplayName.cpp`), which `POST /refresh` calls too. - **A session ends through `end_device_session_and_announce`** (`ClientDeviceSessions.hpp`), shared with `POST /logout`: revocation, a replayed code, any new path that ends a session. - **A UIA endpoint calls `oauth_session_uia_refusal` first** (ADR-0794): `GET`/`POST /login/get_token`, diff --git a/src/homeserver/ClientServerRuntime.cpp b/src/homeserver/ClientServerRuntime.cpp index 031a388a7..764c1b9e2 100644 --- a/src/homeserver/ClientServerRuntime.cpp +++ b/src/homeserver/ClientServerRuntime.cpp @@ -135,6 +135,7 @@ #include "merovingian/homeserver/SpaceHierarchy.hpp" #include "merovingian/homeserver/SpaceHierarchyRequest.hpp" #include "merovingian/homeserver/StateBookkeeping.hpp" +#include "merovingian/homeserver/StoredDeviceDisplayName.hpp" #include "merovingian/homeserver/StoredPushRules.hpp" #include "merovingian/homeserver/StoredRoomVersion.hpp" #include "merovingian/homeserver/TurnCredentials.hpp" @@ -16426,11 +16427,11 @@ static auto handle_client_server_request_impl(ClientServerRuntime& rt, LocalHttp // Repopulates the in-memory device cache only. refresh_local_session has // already established that the device row exists in the persistent // store, so this can no longer resurrect a deleted device — it only - // heals a cache that a restart or a worker split left incomplete. - if (find_device(rt, refreshed.user_id, refreshed.device_id) == nullptr) - { - rt.devices.push_back({refreshed.user_id, refreshed.device_id, refreshed.device_id}); - } + // heals a cache that a restart or a worker split left incomplete, under + // the display name the device row holds (as the OAuth refresh grant does). + remember_signed_in_device(rt, refreshed.user_id, refreshed.device_id, + stored_device_display_name(rt.homeserver, refreshed.user_id, refreshed.device_id), + SignedInDevice::refreshed_session); auto response_body = canonicaljson::Object{ json_member("access_token", json_str(refreshed.access_token)), json_member("refresh_token", json_str(refreshed.refresh_token)), diff --git a/src/homeserver/OAuthTokenEndpoint.cpp b/src/homeserver/OAuthTokenEndpoint.cpp index 068a1e46d..e635c08f8 100644 --- a/src/homeserver/OAuthTokenEndpoint.cpp +++ b/src/homeserver/OAuthTokenEndpoint.cpp @@ -6,7 +6,6 @@ #include "merovingian/canonicaljson/Value.hpp" #include "merovingian/core/FormFields.hpp" #include "merovingian/database/OAuthStore.hpp" -#include "merovingian/database/PersistentDevice.hpp" #include "merovingian/database/PersistentOAuthSession.hpp" #include "merovingian/database/PersistentStore.hpp" #include "merovingian/homeserver/AuthService.hpp" @@ -26,6 +25,7 @@ #include "merovingian/homeserver/RequestHeaders.hpp" #include "merovingian/homeserver/SessionRefreshResult.hpp" #include "merovingian/homeserver/SignedInDevice.hpp" +#include "merovingian/homeserver/StoredDeviceDisplayName.hpp" #include "merovingian/oauth/AccessTokenLifetime.hpp" #include "merovingian/oauth/ClientMetadata.hpp" #include "merovingian/oauth/FormContentType.hpp" @@ -129,23 +129,6 @@ namespace return *name; } - // The display name the device row holds, or empty when there is no row. - [[nodiscard]] auto stored_display_name(HomeserverRuntime const& runtime, std::string_view user_id, - std::string_view device_id) -> std::string - { - auto name = std::string{}; - database::for_each_user_device(runtime.database.persistent_store, user_id, - [&](database::PersistentDevice const& device) { - if (device.device_id != device_id) - { - return true; - } - name = device.display_name; - return false; - }); - return name; - } - [[nodiscard]] auto authorization_code_grant(ClientServerRuntime& rt, core::FormFields const& fields) -> LocalHttpResponse { @@ -378,7 +361,7 @@ namespace // The runtime's device list is healed after a restart, with the device's stored display name; nothing is // announced. remember_signed_in_device(rt, session.user_id, session.device_id, - stored_display_name(runtime, session.user_id, session.device_id), + stored_device_display_name(runtime, session.user_id, session.device_id), SignedInDevice::refreshed_session); auto const* const row = database::find_oauth_session(runtime.database.persistent_store, session.user_id, session.device_id); diff --git a/src/homeserver/StoredDeviceDisplayName.cpp b/src/homeserver/StoredDeviceDisplayName.cpp new file mode 100644 index 000000000..2df1801be --- /dev/null +++ b/src/homeserver/StoredDeviceDisplayName.cpp @@ -0,0 +1,32 @@ +// SPDX-FileCopyrightText: 2026 James Chapman +// SPDX-License-Identifier: GPL-3.0-or-later + +#include "merovingian/homeserver/StoredDeviceDisplayName.hpp" + +#include "merovingian/database/PersistentDevice.hpp" +#include "merovingian/database/PersistentStore.hpp" +#include "merovingian/homeserver/HomeserverRuntime.hpp" + +#include +#include + +namespace merovingian::homeserver +{ + +auto stored_device_display_name(HomeserverRuntime const& runtime, std::string_view user_id, std::string_view device_id) + -> std::string +{ + auto name = std::string{}; + database::for_each_user_device(runtime.database.persistent_store, user_id, + [&](database::PersistentDevice const& device) { + if (device.device_id != device_id) + { + return true; + } + name = device.display_name; + return false; + }); + return name; +} + +} // namespace merovingian::homeserver diff --git a/src/homeserver/meson.build b/src/homeserver/meson.build index 7f8385b39..c7fa1c5c5 100644 --- a/src/homeserver/meson.build +++ b/src/homeserver/meson.build @@ -67,6 +67,7 @@ homeserver_sources = files( 'SearchRoomIndex.cpp', 'UserDirectorySearch.cpp', 'StoredRoomVersion.cpp', + 'StoredDeviceDisplayName.cpp', 'StreamTokenEpoch.cpp', 'RemoteMediaFetchScope.cpp', 'RequestLockScope.cpp', diff --git a/tests/integration/test_oauth_token_flow.cpp b/tests/integration/test_oauth_token_flow.cpp index c1ca6d80d..666831d0a 100644 --- a/tests/integration/test_oauth_token_flow.cpp +++ b/tests/integration/test_oauth_token_flow.cpp @@ -335,6 +335,44 @@ SCENARIO("A code presented with the wrong redirect URI, verifier or client is sp } } +SCENARIO("POST /refresh lists a device the runtime lost under the display name its row holds", + "[integration][oauth][legacy-refresh][legacy-refresh-device-name]") +{ + GIVEN("alice logged in with POST /login, naming her device and asking for a refresh token") + { + auto fixture = make_fixture(); + auto& rt = fixture.started.runtime; + auto const login = + send(rt, "POST", "/_matrix/client/v3/login", {}, + R"({"type":"m.login.password","identifier":{"type":"m.id.user","user":"@alice:example.org"},)" + R"("password":")" + + std::string{alice_password} + + R"(","device_id":"NAMEDDEV","initial_device_display_name":"Alice's laptop",)" + R"("refresh_token":true})"); + REQUIRE(login.status == 200U); + auto const refresh_token = member(login, "refresh_token"); + REQUIRE_FALSE(refresh_token.empty()); + + WHEN("the runtime's device list lost the device, as after a restart, and the client refreshes") + { + std::erase_if(rt.devices, [](auto const& device) { + return device.user_id == alice_id && device.device_id == "NAMEDDEV"; + }); + auto const refreshed = + send(rt, "POST", "/_matrix/client/v3/refresh", {}, R"({"refresh_token":")" + refresh_token + R"("})"); + auto const healed = std::ranges::find_if(rt.devices, [](auto const& device) { + return device.user_id == alice_id && device.device_id == "NAMEDDEV"; + }); + THEN("the device is listed again with its stored display name, not its device ID") + { + REQUIRE(refreshed.status == 200U); + REQUIRE(healed != rt.devices.end()); + CHECK(healed->display_name == "Alice's laptop"); + } + } + } +} + SCENARIO("A grant that cannot be stored leaves nothing, and an account that cannot sign in gets no session", "[integration][oauth][oauth-token]") { From bad2e61558244166539a5d2e9318f930268b9c90 Mon Sep 17 00:00:00 2001 From: James Chapman Date: Mon, 16 Nov 2026 12:51:04 +0000 Subject: [PATCH 33/42] Add the OAuth 2.0 API to the threat model and the review checklist The threat model gains a section on the OAuth 2.0 surface: the server's own pages, cross-site form posts, open redirect and code theft, client impersonation, the device grant as a phishing tool, the legacy SSO hand-off, resource exhaustion, the credential and session lifecycle, logging and the exception backstop, each with its mitigation and the risk its ADR accepts, and an open item: nothing has been tried in a real browser or client yet. The security review checklist gains the checks for a new page, form action, endpoint, store, session path and password path. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 + docs/security-review-checklist.md | 46 ++++++++ docs/threat-model.md | 178 ++++++++++++++++++++++++++++++ 3 files changed, 226 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a698e9f2..518c2366b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -74,6 +74,8 @@ Changes before 1.0.0 are in [CHANGELOG-pre-release.md](CHANGELOG-pre-release.md) of ten minutes (ADR-0805). * A device sign-in's consent page warns first that another device is being signed in, never creates an account, and one browser at a time answers a code (ADR-0806). +* The threat model and the security review checklist cover the OAuth 2.0 API: its pages, form posts, redirects, + stores, sessions and logging, with the risks the ADRs accept. ## Security Fixes diff --git a/docs/security-review-checklist.md b/docs/security-review-checklist.md index f8ee086fe..fc3d1ee90 100644 --- a/docs/security-review-checklist.md +++ b/docs/security-review-checklist.md @@ -24,6 +24,52 @@ Use this checklist for every release candidate. deactivation without `"confirm": true` (400). Its summary carries no hash or token. It reads at most 4096 bytes of body. +## OAuth 2.0 API + +The rules are in `src/homeserver/AGENTS.md` ("OAuth 2.0 API") and `src/oauth/AGENTS.md` ("Rules"); the threats they +answer are in [the threat model](threat-model.md#oauth-20-api-110-adr-0760-to-adr-0811). On a change to this surface: + +- **A new page.** It is built only by `oauth::Page` from `HtmlText` or compile-time text (no concatenated markup, no + `